curating-context: adopt the context budget (wave A, pair 3) — AGENTS.md is 17,521 tokens and all 4 docs are orphaned

[gregoryfoster]

AGENTS.md is 17,521 tokens against a 6,000 budget, and all four of this
repo's reference docs are orphaned — nothing in the policy file links any of
them. The maintenance cost is being paid; the routing benefit is not.

This issue asks this repo to adopt curating-context
v1.2 and run it once.

Measured today, read-only

measure-context.sh --exact against remote HEAD, counted with the
count_tokens endpoint — exact, not estimated. Nothing was written here.

AGENTS.md	17,521 tokens / 304 lines
Budget	6,000
Live reference docs	4 — all orphaned
Whole live surface (tokens_live)	17,521
Dead links	0
Orphaned docs	4

What a run will find

## Bus Conventions is 50% of the file at 8,831 tokens — on its own, 1.5× the
whole budget. Above ~30% a section is the finding rather than a symptom, so it
gets demoted wholesale. Its largest subsection is Retention (2,143), which
suggests a clean A+B split: the two or three rules needed on nearly every task
stay inline, the reference material moves.

Next: Environment Variables 2,850 (16%) and Conventions 1,505 (8%).

Every doc is an orphan — docs/COMMANDS.md, docs/SKILLS.md,
docs/contracts/content-fetch-issuer-contract.md,
docs/contracts/replicator-boundaries.md. This is the most common defect in the
cohort and the cheapest to fix: a ## Detail Docs index with one line per doc
naming what a task would need it for. Note the consequence in the numbers
above — tokens_live equals the policy file exactly, because nothing else is
reachable.

docs/contracts/content-fetch-issuer-contract.md is 14,772 tokens, over the
10,000 per-doc budget. Don't demote into it; it needs splitting first.
docs/COMMANDS.md (2,881) and replicator-boundaries.md (6,682) have room.

Zero dead links — the cleanest link hygiene in wave A.

Pairing

Wave A, pair 3, matched against watcher (19,715 at the last cohort
measurement). This is the weakest match in the roster: 29% apart where every
other pair is within 8%, because watcher has no size neighbour. A difference on
this pair is partly a difference in difficulty, and the analysis will say so
rather than pretending otherwise.

Vendored pointer

This repo is at 82702ea, 22 commits behind main, and that pointer
predates curating-context entirely — the skill is not vendored here yet, so
step 1 below is required rather than optional. Other vendored skills also moved
in those 22 commits; expect to review more than this one skill's effects.

You are wave A — adopt now, then hold

The twelve cohort repos are the held-out validation split for curating-context
itself. Changes to the skill are no longer adopted on judgement: a proposal is
tried on one arm and scored against the other, and it is adopted only if it wins
every informative pair with no safety gate tripped. See
validation-gate.md.

That means the ask here has two halves, and the second one matters as much:

1. Adopt v1.2 and curate once. Record the telemetry row.
2. Then hold at v1.2 until the wave-B comparison resolves.

Wave A is the control arm. When the next change to the skill is proposed,
wave B adopts it and your repo's v1.2 run is what it gets scored against.
Bumping the vendored pointer past v1.2 before then takes this repo out of the
experiment — the roll-up would show two versions inside one arm and
score-cohort.sh returns INCONCLUSIVE rather than a verdict.

A repo's first curation is the unit of comparison, because a first run and a
fifth are not the same task. That is the whole reason adoption is staged instead
of going out to all twelve at once: a simultaneous rollout spends every first
curation at one version and forfeits the comparison permanently.

How to adopt

# 1. Bump the vendored skills pointer to the merge that carries v1.2
git -C skills-vendor/gregoryfoster-skills fetch origin
git -C skills-vendor/gregoryfoster-skills checkout 3fc7b71

# 2. Link the skill (relative, per the vendoring convention)
ln -s ../../skills-vendor/gregoryfoster-skills/skills/curating-context \
      .claude/skills/curating-context

# 3. Heal any dangling vendor symlinks the bump created
bash .skills/doctor.sh

Then run the skill in a Claude Code session in this repo — "curate context" — and
let it work its eight phases. Three things make the resulting ledger row usable
as experiment data rather than just a number:

• --exact must actually succeed. A Claude Code session exports no
  ANTHROPIC_API_KEY; the skill will read one from a repo-root .env. If it
  falls back to the offline estimate the row records tokens_exact: false and
  record-telemetry.sh will refuse to append it (exit 4) rather than reset the
  trend baseline. Fix the credential; do not pass --allow-method-change.
• Pass --no-loss ok once prove-no-loss.sh confirms nothing was dropped.
  The gate treats a missing verdict as unscorable, never as a pass, so a row
  without it cannot clear the safety check and the pair drops out.
• Tag --actions specifically. demote:Project Layout teaches something;
  cleanup does not. The tags are the only thing connecting a token delta to
  its cause in the cross-repo roll-up.

Commit the ledger with the edits, on a branch, and open a PR whose body carries
the before/after count, the per-section disposition, every relocated block with
its destination, and every deletion with its warrant.

Finally

Phase 8 will offer the write-guard hook. Take it — it is the other half of the
ratchet. The weekly run recovers ground; the guard stops regrowth between runs,
and a repo with the run but no guard sawtooths back to where it started.

This issue was filed from gregoryfoster/skills and nothing was written to this
repo. Cross-repo work goes out as issues, never as commits.

[gregoryfoster]

Done — merged as d4a5e02 (PR #23).

Result: AGENTS.md 19,032 → 5,773 tokens (exact, count_tokens; tokens_exact: true), under the 6,000 budget. Four orphaned docs → zero. Largest section 52% → 18%.

The issue quoted 17,521 against remote HEAD; the branch point measured 19,032. Same file, later commits.

• Adopted v1.2 and curated once. Pointer bumped 549a88b → 3fc7b71, skill linked through this repo's two-hop vendoring convention, doctor.sh clean. Ledger row recorded with --no-loss ok and nine specific --actions tags.
• Zero deletions in the curation. Phase 2 returned 41 TRUE / 50 UNVERIFIABLE / 0 FALSE, so no warrant existed. prove-no-loss.sh accounted for all 226 non-blank lines — 106 inline, 120 relocated verbatim. Code review later removed exactly one further line, with its warrant named and the refuting command in the PR.
• Bus Conventions at 52% was demoted wholesale, as the issue predicted, and rebuilt inline as nine rules that bind every change. Four other sections split A+B. Five new docs, all under the 10,000 per-doc budget: ARCHITECTURE.md 8,101 · DEPLOYMENT.md 4,270 · STORAGE.md 1,842 · STYLE.md 1,034 · TESTING.md 905.
• Write guard installed (Phase 8), and the daily skills auto-refresh suspended so the v1.2 hold survives — skills-submodule-update.sh would otherwise have bumped past 3fc7b71 within a day and put two versions inside the wave-A arm. Same remedy CannObserv/cli took; tracked upstream at managing-skills: no way to pin one skills-vendor submodule while the auto-refresh hook updates the rest gregoryfoster/skills#100.
• Also re-embedded .socraticodecontextartifacts.json in the same change, per this repo's own rule that editing the manifest is not what codebase_context_search returns.

Holding at v1.2 until the wave-B comparison resolves. docs/SKILLS.md records the pin, why the suspension is blunter than the problem, the manual update path while it holds, and when to restore.

Follow-up left open: #24 — docs/contracts/content-fetch-issuer-contract.md is still 14,772 tokens, the only live doc over the per-doc budget. Nothing was demoted into it, per this issue.