curate: hone AGENTS.md back under its 6,000-token budget (6,747 → 5,970)

[gregoryfoster]

AGENTS.md is loaded on every invocation, and it has been over .skills/context-budget since the #79 / #82 / #80 rounds each added a bullet. 6,747 → 5,988 exact tokens against a 6,000 budget (ledger: 6,001 on 2026-09-08, so the overrun is four days and three issues old, not one branch's doing).

Measured with measure-context.sh --exact (Anthropic count_tokens) at both ends; both rows are in .skills/context-metrics.jsonl, the after-row stamped with this branch's commit.

Per-section disposition

Section	Before	After	Class	What happened
Bus Conventions	2,245	1,815	C + one D	Eight bullets rewritten to the rule, with the reasoning left in the doc that already carried it. The "Where the reasoning lives" mini-index deleted (class D).
Detail Docs	914	853	C	Index blurbs trimmed back to pointers; every row kept.
Project Overview	375	~120	B — demoted	The command→fact diagram and the paragraph above it moved to docs/ARCHITECTURE.md.
Environment Variables	397	389	C	Prose only.
Server Lifecycle	391	383	C	Prose only; all three gotchas kept verbatim in substance.
Project Layout · Infrastructure · Environment & Tooling · Conventions · Code Exploration Notes	—	—	C	Prose only.
Code Exploration Policy	443	452	A — untouched	Inside the socraticode-policy marker pair; init-socraticode regenerates it, so an edit here is reverted on the next run.
Common Commands · Development Methodology · Agent Skills	—	—	A	Untouched.

The one relocation

AGENTS.md ## Project Overview → docs/ARCHITECTURE.md ## What it owns, and what it emits (new section, above ## Project Layout):

• "Owns content fetching, temp storage, and fingerprinting — the network-bound, byte-handling work re-homed out of Watcher…" (verbatim)
• the four-line content.fetch / content.replicate → fact diagram (verbatim)

AGENTS.md keeps the identity line, the worker-first constraint (a charter rule, not an overview), and a pointer. docs/ARCHITECTURE.md goes 1,463 → 1,681 tokens against a 10,000 per-doc budget. The rubric's own measurement is that overviews in a policy file do not help an agent reach files faster; the constraint beside it does.

The one deletion, with its warrant

duplicate — the four-line "Where the reasoning lives" list under Bus Conventions pointed at docs/STREAMS.md, docs/CONVENTIONS.md, docs/STORAGE.md and docs/TESTING.md. ## Detail Docs, 100 lines below in the same file, lists all four with fuller one-liners. Verified row by row before deleting.

What proves the rewrites kept their claims

prove-no-loss.sh --base 8d63a77 --claims
  lost: 0   loss_warranted: 77   claims_dropped: 0   claims_warranted: 0

claims_dropped: 0 is the load-bearing number: every backticked identifier, #NNN reference and link target present in the base file is still somewhere in the surface. The 77 warranted lines are class-C rewrites and re-wrapped fragments, each judged in .skills/context-loss-ok against the destination that carries its reasoning — docs/CONVENTIONS.md (OOM, ACL, the three fates, the dedupe keys), docs/STORAGE.md (the backend seam, to_thread inside the shutdown budget), docs/STREAMS.md (the compiled-in local default), docs/DEPLOYMENT.md (guard verdicts, the co-core pin).

Seams and counts

• check-seams.sh: 0 to review, 32 acknowledged — but read that number narrowly. The sweep printed note: 157 tracked source file(s) not swept — nothing left the policy file since --base, and that premise is wrong: the diagram did leave AGENTS.md, so the source-side half never ran. Established by hand instead — grep for Project Overview and for the diagram across *.py, *.sh, *.yml and *.md outside docs/plans/ returns only AGENTS.md's own heading, so nothing outside the docs tree points at what moved. The tool's heuristic looks section-level (no ## heading disappeared), which is a gregoryfoster/skills issue rather than an edit here. Four new judgements — three docs/SKILLS.md back-references that name the arrangement (## Project Layout, ## Detail Docs) rather than a moved block, and one #79 provenance heading in docs/TESTING.md this run moved nothing into. Two stale acknowledgements pruned on the tool's advice.
• check-counts.sh: this repo's first pass — 0 to review, 9 acknowledged in a new .skills/context-counts-ok. Two rhetorical counts dropped to prose rather than warranted ("the three ways a skew has already failed" → "the ways"; "one formatter, two installers" → "its formatter, its installers"); the rest are enumerated beside their list, plus one stable (XAUTOCLAIM's three-element reply — Redis wire format).

Review round CR 13-20

Reviewed after the curation and before merge; eight findings, one commit each, all applied.

#	What was wrong	Fix
13	The capped-broker bullet dropped "never the shared one" — the only line telling an agent not to set maxmemory on the broker three services share	Restored
14	The .env security paragraph was fused into one garden-path sentence and lost "the worker has no use for"	Restored byte-identical to base
15	The STREAMS.md index row said "one bullet per rule stated here", which resolves to STREAMS.md — contradicting that doc's own opening line	Subject restored
16	The logging→STYLE.md pointer was merged into General:, leaving the Logging block without one and a dangling "Those"	Pointer back under Logging, on its own line
17	docs/ARCHITECTURE.md's index row still said "founding design, module by module" — it now also holds the flow diagram	Row names the flow
18	This PR body claimed a seam result broader than what ran	Corrected above
19	"by decision, not by schedule" kept the contrast and lost its evidence	Restated self-contained (#7)
20	The new overview pointer duplicated Project Layout's pointer to the same doc	Trimmed

13–17 add text; 19, 20 and trims to four Detail Docs rows pay for them, so the file ships at 5,988 rather than the 6,017 the fixes alone cost. The ledger row was rewritten in place to the shipping tree (Phase 7's within-run rewrite), not appended to.

Verification

• uv run pytest — 972 passed, 44 deselected, coverage 99.86% (re-run after CR 13-20)
• uv run ruff check . — clean
• measure-context.sh --exact — dead: [], dead_anchors: [], orphans: []

Review notes

duplicated: 4 is unchanged from the baseline and not this branch's doing: two runnable commands live in both ## Common Commands and docs/COMMANDS.md/docs/DEPLOYMENT.md, which is the load-bearing-in-both-places case the tool asks you to judge rather than a copy left behind.

Worth a second pair of eyes on the Bus Conventions rewrites specifically — that is where the words came from, and "same claim, fewer words" is the judgement a fresh reader is better placed to check than the author.

🤖 Generated with Claude Code