refactor(harness): refit — cut always-loaded context 23%, resolve 7 contradictions, add client boundary guard

[rdemeritt]

Refit pass over the harness: remove scaffolding that costs baseline tokens or forces the model to reconcile contradictory instructions. Every number below was computed, not estimated. Full baseline, measurement commands, and rationale in docs/refit-2026-08-10.md.

Measured result

Surface	Before	After	Δ
CLAUDE.md	10,390 B / 188 L	5,316 B / 87 L	-49%
Agent frontmatter (25)	11,031 B	11,031 B	0
Command frontmatter (13)	1,091 B	1,091 B	0
Always-loaded total	22,512 B (~5.6k tok)	17,438 B (~4.4k tok)	-23%

83 insertions, 1,748 deletions, 27 files removed.

The main cut

## Team Structure was 30% of CLAUDE.md restating agent descriptions that are already always-loaded as frontmatter — measured median 67% keyword overlap, 100% for backend-developer and innovation-lead, 93–94% for the apple/blockchain/llm trio. A straight double charge.

Replaced with a council→slug routing table (council membership is the one thing frontmatter genuinely lacks) plus a Traps section spending the reclaimed budget on what the file tree cannot show: no-lock disables scoping, a missing .env silently redirects SOURCE_ROOT_BASE to the harness's parent directory, sprint files never live in specs/, CURRENT is a symlink not a copy.

Contradictions resolved (7)

1. Nobody owned opening PRs. backend/frontend named Account Lead or Architect; apple/blockchain/llm named the GitHub & VC Specialist; that agent's own file called PRs "the developer's responsibility". The named owner disclaimed the job. → Developers open their own PRs, VC Specialist advises and never opens or merges, merging is a human decision. Stated once, 10 restatements collapsed.
2. Gate list divergence: CLAUDE.md 6, GEMINI.md 5, README prose "Six". → verified identical six, same order, same owners.
3. "Three councils" in 5 files against 4 actual councils. SETUP.md also claimed 17 roles vs 25 actual. docs/onboarding.md omitted the Hardware Council entirely.
4. CLAUDE.md said "Technical Writer"; the agent file is tech-writer.
5. .gemini/ was a stale mirror — 15 of 25 agents, missing every Hardware Council role, blockchain-engineer at 1,187 B vs 6,306 B, 2 orphan agents in no roster. Deleted with GEMINI.md and .geminiignore.
6. settings.json wrote .claude/sessions/<id>.pm; the reader hook reads .pm-mode. Nothing ever read .pm — a silent no-op on every /pm.
7. pm.md pointed at .claude/active-client, a file nothing writes, still allow-listed in settings.

New mechanism: client boundary guard

The client workspace boundary was prose-only while settings.json allowed Write(clients/**) wholesale. .claude/hooks/client-boundary-guard.sh is a PreToolUse guard on Write|Edit|NotebookEdit that exits 2 — the only code that blocks — on cross-client writes.

Fails open by design when no session lock is set: a session that has not run /use-client has no declared client, so there is no boundary to cross. Documented in CLAUDE.md § Traps.

Written for bash 3.2 with no set -u/set -e — an aborted PreToolUse hook reads as allow, so it must never abort early.

23 test cases, both directions, all passing. Allow: same-client relative/absolute, outside clients/, clients/ root files, no lock, empty session_id, non-path tools, sibling source repos, malformed JSON, empty stdin, null tool_input. Block: other client relative/absolute, deep project paths, notebook_path, and two path-traversal escapes (clients/<active>/../<other>/... and patterns/../clients/<other>/...).

Not done

• Nothing outside this repo. ~37.1k of the measured 42.7k first-turn context (87%) is Claude Code's system prompt, global agents, plugins, and connectors — a larger lever than everything here, but global config. Left alone.
• Domain NEVERs in the apple/blockchain/llm/backend/frontend agents kept — hard-won knowledge, not backseat driving. Only the PR-ownership lines went.
• Agent/command descriptions untouched: they are the routing contract.
• .env.template:52 still sets DEFAULT_MODEL=gemini-2.0-flash and setup.sh:97 prompts for a Gemini key. Possibly dead now, but GOOGLE_API_KEY may serve client work and a default-model change is behavior-changing. Flagged, not changed.

Caveat

n=1. The only transcript for this project directory is the session that ran the refit — no usage history, zero recorded subagent spawns or command invocations. Dormant-capability analysis was impossible, so nothing was retired on usage grounds. No capability-generation reference was consulted; every cut is justified by evidence internal to this harness, not by claims about what this model generation can infer.

🤖 Generated with Claude Code