Repository navigation
Description
Problem
Two of the four live agent-context files are over budget. Every session pays for AGENTS.md, and DEPLOYMENT.md is the runbook most issues send an agent to.
Measured 2026-11-07 on e81eb9f with curating-context's measure-context.sh --exact --file AGENTS.md --docs-dir docs. Counts come from count_tokens, not estimates. The repo has no .skills/context-* knobs, so the skill's defaults apply: 6,000 tokens for the policy file and 10,000 per reference doc.
| File | Tokens | Budget | Verdict |
|---|---|---|---|
AGENTS.md |
6,663 | 6,000 | over by 663 (11%) |
docs/DEPLOYMENT.md |
44,066 | 10,000 | over by 34,066 (4.4×) |
docs/SKILLS.md |
5,574 | 10,000 | ok |
docs/SOCRATICODE.md |
4,477 | 10,000 | ok |
tokens_liveis 60,780.- There are no orphaned or unindexed docs.
- 31 archival docs (
docs/plans/,docs/specs/, …) are excluded by the skill's default. - The offline estimator undercounts this repo: it measured 2.46 bytes/token against its 2.70 default, and so read AGENTS.md as 5,852 tokens, under budget. Gate on
--exact.
AGENTS.md. ## Infrastructure is 2,781 tokens, 41% of the file. The skill treats any section over about 30% as the finding in itself. The section is a 28-row table whose cells carry runbook detail (patching times, CI pins, drift and liveness thresholds) that DEPLOYMENT.md already holds. The next largest sections are Conventions (598), Environment & Tooling (587) and Development Methodology (492).
DEPLOYMENT.md. It has 24 ## sections. These are the largest, using byte shares of the exact total:
| Section | ~Tokens | Share |
|---|---|---|
| Patching | 6,540 | 14.8% |
Deploy a change: scripts/deploy.sh |
4,526 | 10.2% |
| Prerequisites (operator) | 4,020 | 9.1% |
| Tailscale DNS | 3,439 | 7.8% |
| CI pins and Dependabot | 3,139 | 7.1% |
| Tailnet flaps | 2,253 | 5.1% |
| The drift check | 2,243 | 5.1% |
No single trim fixes a document at 4.4× its budget. Getting under budget probably means splitting it into several reference docs (for example deploy and rollback; CI and dependencies; host operations covering patching, disk and memory; and the network, covering Tailscale DNS and flaps), each under 10,000, all indexed from AGENTS.md.
Approach
Run curating-context as written, in a worktree on a branch: measure with --baseline, verify facts, keep/demote/tighten/delete, plan to the budget, then record the after-row.
- Relocate, don't delete. Most of this text records why something is the way it is (issue refs, measured values, operator decisions). The skill's rubric decides what moves where.
- Cross-links. The anchors other files point at (
docs/DEPLOYMENT.md#bumping-co-core,#patching,#the-lock-audit,#tailscale-dns, …) must keep resolving after a split, or be rewritten wherever they're cited.- 15 test files mention
DEPLOYMENT.md(tests/test_deploy.py,test_patching_knob.py,test_lock_audit.py,test_pin.py, …). tests/test_shipping_knobs.pyfails on any.skills/doc-sectionsheading that no longer exists.- Run the full suite.
check-seams.shandverify-facts.shcover the rest.
- 15 test files mention
- Budget knobs. The skill reads
.skills/context-budget,.skills/context-doc-budgetand the guard (install-guard.sh), and can install a weekly cadence (install-cadence.sh). Decide with the operator whether to adopt the guard so that drift back over budget fails early.
Hazards
- Don't touch
§ Patchingbefore Patching: a missed window goes unnoticed — solicit approval before each window, or automate unless overridden #113's first real window (Tue 2026-11-10, 05:00–10:00Z) closes. The attended run follows that section. Start with AGENTS.md and the other sections, or start after the window. - Docs only, so no deploy.
docs/andAGENTS.mdare notprocessor.drift.RUNTIME_*paths. Moving adeploy/orscripts/comment along with the text would make it one. - Line by line. Some sentences in DEPLOYMENT.md are the only record of a measurement (for example the CI image, the Redis pin and the WIF chain). A sentence that
verify-facts.shcan't check gets moved, not dropped.
Done when
measure-context.sh --exactreports AGENTS.md ≤ 6,000 and every live doc ≤ 10,000, with no orphans or unindexed docs.- The baseline and after-rows are both recorded (
record-telemetry.sh). - Every link into a moved section resolves.
- CI is green by job (
lint,test).
Activity
#126 chore: install curating-context's write guard and weekly measure…
#126 chore: backfill the after-row's repo_commit
gregoryfoster commentedon Nov 8, 2026
Part 1 merged: PR #128, fast-forwarded to
mainat 25467d4 (CI green). Docs and tooling only, so no deploy.AGENTS.md: 6,663 → 5,929 tokens (budget 6,000).docs/DEPLOYMENT.mdwas split intoPROVISIONING.md(8,303),DEPENDENCIES.md(8,126),MONITORING.md(7,633) andNETWORK.md(5,801). Each moved heading keeps a stub under DEPLOYMENT.md § Moved sections.DEPLOYMENT.mdis still 17,639, because § Patching and § Node.js are held until Patching: a missed window goes unnoticed — solicit approval before each window, or automate unless overridden #113's window (2026-11-10 05:00–10:00Z).context-cadence.ymlare installed. The first run (42502688352) was green and opened chore: weekly context measurement #129. It flagged DEPLOYMENT.md over budget and AGENTS.md approaching its budget (71 tokens left).Left for part 2, after the window:
docs/PATCHING.mdbehind stubs.pyproject.toml:51(Shell lint) and the tailscaled drop-in's "Install: docs/DEPLOYMENT.md".#126 fix: address the fresh-eyes review
#126 chore: amend part 2's after-row after review
#126 chore: backfill the after-row's repo_commit
gregoryfoster commentedon Nov 10, 2026
Part 2 merged and deployed. PR #132 was fast-forwarded to
mainat 176acf9 (CI run 42850230431 green), and live is now176acf9b4564.Done-when, against
measure-context.sh --exact:AGENTS.mdis 5,945 (budget 6,000).Live (2026-11-10):
scripts/deploy.sh:processorrestarted on 176acf9 (starting,consuming, smoke run passed, NRestarts 0). No warnings since, and the liveness check-in returned 202 at 16:03:30Z.root:root 644), followed bydaemon-reload:processor-periodicapt-daily.timer.ddrop-inprocessor.confdisk-gc.confoom_score_adjstill -950,brokerresolves.HOST_CONFIGSnow match their installed copies, so the next deploy prints nodiffers fromnote.test_apt_automatic,test_disk_gc,test_needrestart,test_tailscaledandtest_nodesourcegive 73 passed.ok, HTTP 202.Not stubbed: the
###anchors#the-patch-due-check,#patching-node,#moving-the-major-lineand#removing-it. As in part 1, only##sections have stubs, and nothing in the repo links those four.