[gregoryfoster]

Closes #35.

Before / after — measured exactly, not estimated

File	Before	After	Budget
AGENTS.md	6,349	5,954	6,000
docs/ARCHITECTURE.md	11,075	9,510	10,000
docs/contracts/content-replicate-issuer-contract.md	10,284	9,274	10,000
docs/contracts/replicator-boundaries.md	9,152	9,152	10,000
docs/CONVENTIONS.md (new)	—	1,870	10,000
docs/TESTING.md	905	1,088	10,000

totals.tokens_live 73,998 → 73,081. Dead links: 0. Orphans: 0. Full suite: 682 passed.

The issue's premise, checked

replicator-boundaries.md was never over budget. Exact count 9,152 — 848 under, not 385 over.

The issue guessed the hook was "measuring something wider than the file". It isn't. measure-context.sh persists a bytes-per-token ratio computed from the policy file alone (RATIO_X100=$(( P_BYTES * 100 / P_TOKENS ))), and the write guard then applies that one ratio to every reference doc. AGENTS.md tokenizes at 2.52 bytes/token; the contract docs, which are much denser in tables and links, tokenize at ~2.83. So the guard over-reports them:

File	guard estimate	exact	error
replicator-boundaries.md	10,386	9,152	+13.5%
content-replicate-issuer-contract.md	11,708	10,284	+13.8%
ARCHITECTURE.md	12,150	11,075	+9.7%
AGENTS.md	6,427	6,349	+1.2%

10,386 is the "~385 over" in the issue. The cl100k cross-check in the issue (6,148 / 6,026) errs the other way — it is OpenAI's tokenizer and undercounts Claude badly.

Two files the issue did not name were genuinely over: docs/ARCHITECTURE.md by 1,075 (the largest breach), and AGENTS.md itself by 349 — it grew 477 tokens between the last ledger row and #29 landing.

Filed upstream against the skill: the ratio should be calibrated over the whole measured surface, not the policy file.

Per-section disposition

Section	Class	Disposition
ARCHITECTURE.md → stream-agnostic bus rules (15 bullets)	B	moved verbatim → docs/CONVENTIONS.md
content-replicate-issuer-contract.md → ## Why the issuer renders	B	moved verbatim → docs/plans/2026-08-14-why-the-issuer-renders-settled.md
AGENTS.md → Conventions/General test-layout bullet	B	moved verbatim → docs/TESTING.md (## Test layout)
AGENTS.md → Project Overview founding-design pointers	B	moved verbatim → docs/ARCHITECTURE.md header
AGENTS.md → Bus Conventions "replicate loop writes for gcs"	C	tightened
AGENTS.md → Bus Conventions "Three normative contracts"	C	tightened
AGENTS.md → Project Layout	C	tightened
AGENTS.md → Environment & Tooling co-core floor tail	C	tightened (every fact retained)
AGENTS.md → env-load snippet under Environment Variables	D	deleted — verbatim duplicate of the one in Common Commands
AGENTS.md → --no-cov rationale, 2nd occurrence	D	deleted — verbatim duplicate three lines above
AGENTS.md → "Read ARCHITECTURE.md before changing what any of them carries"	D	deleted — duplicate of the Detail Docs routing line
AGENTS.md → Bus Conventions (9 core rules), Code Exploration Policy, Detail Docs, Common Commands, Environment Variables	A	kept

Relocations, with destinations

• docs/CONVENTIONS.md (new, 1,870 tok) — the 15 co-core/Redis-Streams bullets that hold for every stream: outbox posture, extra="ignore" validation, batch-poison / count=1, dead_letter, decoding a fieldless frame, the global from_wire dispatch table, claim_stale, times_delivered, the XINFO CONSUMERS liveness trap, message-vs-cycle failure, injection-only clients, store-then-publish, tz-aware occurred_at, keyword-only topic/message_id, sha256's home. ARCHITECTURE.md keeps what each individual stream carries. Indexed in Detail Docs and in the context manifest.
• docs/plans/2026-08-14-why-the-issuer-renders-settled.md (new) — T3's rejected alternatives, what the chosen shape costs, and the consequences for cannobserv#303. Same split #24 made for the fetch_failed open question. The contract keeps a six-line stub pointing at it; the inbound #why-the-issuer-renders anchor at T3 was repointed. The doc's own URL is unchanged, so sibling-repo links are unaffected — this is why the section was relocated rather than the document split.
• docs/TESTING.md ## Test layout — the split-by-concern rule and the _integration filename exception. AGENTS.md keeps the mirror rule and routes.
• docs/ARCHITECTURE.md header — the founding-design and parent-strategy plan pointers (archival paths; the Detail Docs line now names them).

Deletions, with warrants

Three, all class D, all verbatim duplication — quoted above in the disposition table. No deletion rests on an UNVERIFIABLE verdict.

Verification

• verify-facts.sh --issues: 0 FALSE, 50 TRUE, 15 UNVERIFIABLE — all 15 benign (absolute paths outside the repo, illustrative templates like src/foo.py, bare filenames named in prose). Nothing deleted on an UNVERIFIABLE.
• prove-no-loss.sh --base main: 160 lines still inline, 2 relocated verbatim, 28 unaccounted. Every one is a class-C reflow or a class-D duplicate; each warrant is named above and each is verifiable against docs/ARCHITECTURE.md, docs/CONVENTIONS.md, or the Detail Docs index. Ledger records no_loss: "failed" honestly rather than claiming a clean pass.
• uv run pytest: 682 passed, coverage 99.83%. tests/test_boundaries.py (106 assertions incl. the AGENTS.md structural ones) and tests/test_deploy.py green.
• Re-measure: 0 dead links, 0 orphans, every live doc under the per-doc budget.

Note on the ledger delta

The row reads +82 because it diffs against the last recorded row (5,872 on 2026-08-11), not against today's baseline. The run's actual effect on AGENTS.md is 6,349 → 5,954 (−395); the intervening +477 was #29 landing without a curation pass.

Follow-up

codebase_context_index must be re-run after merge — the manifest is a source, not the artifact (#19 CR #17). The manifest edits are in this PR; the embeddings are not.

🤖 Generated with Claude Code

[gregoryfoster]

CR round 1 applied — a1581c3

Item	Action	Result
1	Fixed	AGENTS.md:63 — src/core/ restored to Project Layout
2	Fixed	AGENTS.md:178 — integration --no-cov reason restored; warrant reclassified D → C
3	Fixed	AGENTS.md:158-159 — Bus Conventions routes to ARCHITECTURE.md + CONVENTIONS.md inline
4	Fixed	manifest agent-guidelines — counts removed ("nine bus rules", "two normative contracts")
5	Fixed	docs/CONVENTIONS.md — ## Conventions heading dropped
6	Fixed	replicate contract's "Where the rest of the contract lives" now indexes the plan doc, matching the fetch contract
7	Stet	—

Plus: the policy block, per review direction

init-socraticode did ship the split — gregoryfoster/skills#115, upstream commit 9125148. Our vendored pin 3fc7b71 predates it, so it had not reached this repo. The block is now on the upstream Variant A shape:

• AGENTS.md keeps the indexed-state line, the negative rule, a three-row table and a link — 935 → 446 tokens.
• New docs/SOCRATICODE.md (1,414 tok) carries the full ten-row table, the prefetch/hook note, per-tool gotchas, cross-repo search, graph-yield health, and .socraticodeignore scope.
• Repo-authored content is rescued into ## Code Exploration Notes (repo-specific) outside the marker pair — the step-1a contract that same upstream change added. The manifest-is-a-source gotcha (Consume content.fetch-policy — replace the single env default with Watcher's per-host numbers (cannobserv#285) #19 CR A body-less 304 dead-letters — make "not modified" a first-class outcome before conditional GET is usable #17) lives there now; left inside the markers, the next init-socraticode run would have deleted it silently.

This is why finding 3 mattered more than it looked: the file now routes to four detail docs from the sections that need them.

Numbers

	Before run	After CR
AGENTS.md	6,349	5,837 (budget 6,000)
Code Exploration Policy	935	446
headroom	−349	+163

Every live doc under 10,000. 0 dead links, 0 orphans. ruff check clean, ruff format --check 92 files formatted, 683 tests pass (99.83%).

prove-no-loss.sh: 149 inline, 10 relocated verbatim (8 → SOCRATICODE.md, 1 → ARCHITECTURE.md, 1 → TESTING.md), 31 unaccounted — the template-owned policy block regenerated from upstream Variant A (not repo prose to preserve), the class-D duplications listed in the original PR body, and reflows. Ledger row rewritten in place rather than appended, since this is one run.

Follow-up beyond this PR

The vendored skills submodule sits at 3fc7b71; upstream main is c3f40f7 and carries #115 plus other work. Bumping the pin is separate from this docs curation — worth its own issue so the init-socraticode re-run and its report land deliberately.