[gregoryfoster]

Closes #146.

All three over-budget reference docs are under the 10,000-token per-doc budget (exact count_tokens). Sections were moved verbatim to the doc that owns the behaviour they describe, and each old location keeps a pointer. Nothing was deleted.

Doc	Before	After	Δ
docs/COMMANDS.md	10378	9521	−857
docs/SKILLS.md	10059	8959	−1100
docs/ENVIRONMENT.md	10014	9299	−715
docs/POLITENESS.md (destination)	6943	7944	+1001
docs/SOCRATICODE.md (destination)	4447	5662	+1215
docs/DEPLOYMENT.md (destination)	7570	8658	+1088
AGENTS.md	5991	5991	0

Disposition

Source section	Class	Disposition
COMMANDS.md ### Politeness — content.fetch-policy (#19): rcli reads, journal greps, and the four paragraphs that read them	B	Moved to POLITENESS.md ### Inspecting the stream, directly above ### Reading the apply log, which already opened by pointing back at these greps. #136 had already put a politeness grep in POLITENESS.md under budget pressure, and this follows the same direction. The heading stays in COMMANDS.md as a pointer.
COMMANDS.md handler-hold greps (broker#20), previously under the Politeness heading	A	Kept, now under its own ### How long a handler holds its group heading.
SKILLS.md "The SocratiCode plugin is installed…" and "The health hook used to lie…" paragraphs	B	Moved to SOCRATICODE.md ## Repo-specific notes → ### The plugin and its hooks (below the generated END marker, so a re-run keeps it). SKILLS.md keeps a pointer.
SKILLS.md ### After an init-socraticode re-run	B	Moved verbatim to SOCRATICODE.md ## Repo-specific notes at the same ### depth.
ENVIRONMENT.md bullets REPLICATOR_REDIS_FLOOR_TIMEOUT, REPLICATOR_REDIS_FLOOR_WAIT, REPLICATOR_ALLOW_ANY_CHECKOUT	B	Moved to DEPLOYMENT.md ## Environment Variables, next to the unit they gate. This is the same pattern STORAGE.md, POLITENESS.md and FAILURE-NOTIFICATION.md already follow. ENVIRONMENT.md keeps a pointer bullet that names all three, and its preamble lists the new location.
Everything else in all three docs	A	Kept as is.

Rewritten lines (judged in .skills/context-loss-ok / context-claims-ok)

• retarget: POLITENESS.md "Of the journal greps for this stream…" now reads "[above]" instead of pointing at the old COMMANDS.md anchor.
• retarget: the moved block's "Why: [POLITENESS.md]" link is now a same-doc "[below]" link.
• retarget: the moved plugin paragraph's "are in [SOCRATICODE.md]" now reads "are above".
• retarget: the list in ENVIRONMENT.md's preamble of where variable reasoning lives gains DEPLOYMENT.md.
• retarget: docs/reference/tailscale.md now links REPLICATOR_REDIS_FLOOR_WAIT to DEPLOYMENT.md instead of ENVIRONMENT.md.
• rename: ### The patching gate's in-flight count (#131) loses its provenance suffix. A seams ack had asked for this with the next COMMANDS.md edit. #131 moves into a lead-in line.

Gates

• prove-no-loss --claims, base beda65d, on all seven touched docs: lost 0, claims dropped 0. Every rewrite is warranted.
• check-seams: 0, both on the default sweep and with --file on each curated doc. New acks are for back-references to content that did not move. One Catch up co-core 0.19.6 → 0.36.0 ahead of the generation release #140 ack stopped matching once its line moved, and was dropped with a note.
• check-counts: no new counts. My new lines carry none, and moved counts travelled with their text. One anchor slug (#two-launch-paths…) is acked as stable.
• Links: no dead, dead_anchors, orphans or unindexed.
• Tests: full suite 1421 passed, 1 skipped.
• CR (round 2, findings 9–11): DEPLOYMENT.md's preamble names the variables it now keeps; the politeness pointer names the live-apply greps; .skills/doc-sections routes SOCRATICODE_SPEC to SOCRATICODE.md. Full suite re-run green.
• Fresh-eyes review: the false "beside the guards they set" claim, the missing hold-greps heading, the ENVIRONMENT/DEPLOYMENT lead-in that read as a contradiction, the stale ack and the manifest wording were fixed in the CR 1 commit.
• Telemetry: one baseline and one curation row per curated doc in .skills/context-metrics.jsonl.

Left as is (reviewer's low findings; all verbatim-moved text that is still correct)

• DEPLOYMENT.md's moved ALLOW_ANY_CHECKOUT bullet links its own doc by filename. It resolves.
• SOCRATICODE.md's moved re-run text names "the doc" in the third person. Its list of repo-specific notes is an example list, not a complete one.
• POLITENESS.md's moved "fire on a change" paragraph partly repeats ### Reading the apply log just below it. The repeat is not verbatim, so it has no deletion warrant.

After merge

• Run codebase_update. The manifest descriptions for POLITENESS.md, DEPLOYMENT.md, ENVIRONMENT.md and SOCRATICODE.md changed, and nothing re-embeds them otherwise.

Near-budget docs (the issue's "then decide")

These are still near-budget: content-replicate-issuer-contract.md 9893, content-fetch-outcome-reference.md 9840, CONVENTIONS.md 9745, replicator-boundaries.md 9726, content-fetch-issuer-contract.md 9723, COMMANDS.md 9521, ENVIRONMENT.md 9299 and STREAMS.md 9285.

Recommendation: split each one before its next growing edit, not pre-emptively. The four contract docs have 100–280 tokens of headroom, so any substantive edit will cross the budget. #144 already has to split replicator-boundaries.md. COMMANDS.md's next candidate is the broker-ACL narrative under "Inspecting the consume path" (~1400 tokens). It has no home with room today: INFRASTRUCTURE.md would land at ~9970.

🤖 Generated with Claude Code