Bot stages load 34 KB of local-machine context on every run, on every turn

[johanzander]

Problem

Every bot stage loads CLAUDE.md before it does anything, and 74% of that
file is a section that cannot apply to a CI run. It is re-sent on every turn
of every stage, on both the main agent and its sub-agent, and it is the single
largest item in the fixed context floor.

This is the follow-up to #646. That issue fixed runs that produced nothing;
this one is about what every run pays before it produces anything.

Measured

CLAUDE.md is 45,488 B. One section is most of it:

Section	Bytes	Share
Worktree Conventions (incl. Permissions, rulesets, sandbox knobs, Playwright)	33,743	74%
Automated Agent Workflow	4,130	9%
the other 11 sections combined	7,615	17%

Stage 2's fixed floor, before it reads the issue, the debug bundle, or any
source file:

Loaded	Bytes
CLAUDE.md (auto-loaded — settingSources: ["user","project","local"])	45,488
.claude/agents/bess-analyst.md (REQUIRED READING)	25,681
docs/agents/rules.md	10,548
the inline prompt:	7,098
docs/agents/architecture.md	3,623
total	92,438 (~24k tokens)

Worktree Conventions alone is 36% of that floor, and it is loaded again by
the bess-analyst sub-agent, which starts its own turn loop with its own copy
of the project context.

Why it cannot apply in CI

The section documents this machine. A stage runs on a fresh ubuntu-latest
runner under --permission-mode bypassPermissions:

• Permissions / deny-ask-allow — there is no prompt to avoid; the run
  bypasses permissions entirely.
• The macOS sandbox knobs (allowMachLookup, allowLocalBinding,
  allowWrite, trustd/keychain, podman over local TCP) — no macOS, no podman
  VM, no .venv/node_modules symlinks.
• Worktree conventions — the runner does one actions/checkout; there are
  no siblings, no .claude/worktrees/, no worktree-setup.sh.
• The Playwright install hang — no E2E runner in any bot stage.
• git stash prohibition — the reasoning is "~20 worktrees share one
  refs/stash"; a runner has one checkout and no other agents.

Confirmed by grep: no workflow references the section. The only permission
hits in .github/workflows/ are pr-review.yml's own self-contained prose
about gh api being gated.

Proposal

Relocate, do not delete. Move ## Worktree Conventions verbatim to
docs/agents/local-agent-environment.md and reference it from the existing
Agent Documentation Index table — the structure CLAUDE.md already uses for
rules.md, architecture.md, patterns.md, etc. Every word survives; local
agents reach it through the index like every other doc.

Effect: CLAUDE.md drops 45,488 B → ~11,700 B, on all five stages, on both
the main agent and the sub-agent, on every turn.

Two inbound links repoint in the same change:

• .claude/skills/sweep-prs/SKILL.md:78
• docs/agents/skill-architecture.md:132

Secondary, needs verification first

Stage 2's REQUIRED READING includes .claude/agents/bess-analyst.md (25,681 B)
— but that file is the sub-agent's own definition, so the main agent reads
25 KB describing how the sub-agent should work, then delegates to the sub-agent
that already has it. If that is genuinely redundant it is the second-largest
item in the floor. Confirm by inspection before touching it — the main
agent may be relying on the checklist to verify the sub-agent's output.

Explicitly out of scope

• Deleting or condensing any of the relocated content. It is hard-won and
  load-bearing for local autonomous runs. This issue moves it; it does not
  judge it.
• Changing --setting-sources to drop project from the CI stages. It would
  cut more, but .claude/agents/bess-analyst.md is discovered through project
  settings, so it would break the delegation Stage 2 depends on.

Acceptance

• CLAUDE.md under ~12 KB with no content lost from the repo.
• Both inbound links resolve.
• scripts/quality-check.sh still passes (it reads CLAUDE.md and pins
  permission command strings — verify the gate does not depend on the moved
  prose).
• A Stage 2 run still delegates to bess-analyst and still publishes.