v2.4.0: the skills stop paying for their own history

Released 2026-09-11. One issue, one PR, one number that mattered: a run of implement-issue cost about 250k tokens, and most of that was the kit re-reading itself.

What we were trying to fix

skills/auto-dev/references/token-economics.md had already measured the shape of the cost: about 127 turns per session, and roughly 83 percent of a run’s spend is context re-read, not new work. Against that measurement, implement-issue/SKILL.md was 51 KB (about 13k tokens), merge-pr was 63 KB, create-issue was 55 KB, and each loaded whole at invocation and stayed loaded on every later turn. Three more multipliers stacked on top: every golden suite printed every ok line into the context at each TDD step, closing one task took four separate tool turns (tick, guarded commit, guarded push, sync), and the three skills linked a further ~70k tokens of shared references.

What we decided

Progressive disclosure for the three lifecycle skills. SKILL.md keeps only a router: contract, inputs, checklist, and a step index. Each ## Step N moved to its own file under references/steps/NN-<slug>.md, read only when a run actually reaches it. Measured after the split: implement-issue’s router fell from 51 KB to 11 KB, merge-pr from 63 KB to 10 KB, create-issue from 55 KB to 11 KB. tests/_lib.sh gained kit_skill_prose so a pin on a step’s wording still reads the router and its step files as one assembly, and decisions/registry.json now names the step file that invokes each decision as its owner, not the router.

Alongside the split, two smaller cuts to the same cost: every suite now runs through a log file and the loop reads only its tail on failure, and finish-task.sh composes guarded commit, plan tick, PR mirror edit and guarded push into one script, so closing a task costs one turn instead of four.

What got cut

Nothing from the scope of #499. The release was one issue end to end: the router split, the quiet suites, and the one-turn task close were shipped together because they attack the same number from three sides, and none of the three is useful alone.

What bit us

Nothing on the way in: every gate and suite came back green except dotnet test samples/LegacyShop, which needs a net6 runtime this host does not carry, an environmental gap rather than a defect. What the split did leave behind is a standing cost of its own: three routers now point at many more step files, and every one of those files that names a _shared/*.md reference has to keep appearing in that reference’s own Consumers list, in both directions, or check-shared-refs catches it later instead of at the split.