token budget S3 and S4: one use for the Agent tool, two skills on a diet

[buzzdan]

Implements stages S3 and S4 of docs/token-budget.md, the second pair after S1 and S2 (#61). No rule text changes; only skills, one agent, one command and their reference files under core/, with the three renderings regenerated. The second commit applies a two-hat review (AI cost expert, LDD expert) of the first.

S3 — budgets and the general-purpose ban

• The linter-driven-development skill names the two agents it spawns (the lint-fixer, and the skeptic in PREPARE gate 4) and says the review agents belong to the skills that own them; refactoring is a skill invoked in the main thread, never delegated to a general-purpose or any other subagent, however many escalations there are. The quickfix command repeats it beside the escalation step; the refactoring skill says the same of itself.
• The lint-fixer has a budget: twelve turns per spawn (about six lint runs and forty edits), one multi-edit turn per file. What its budget did not reach returns as ESCALATED: <linter> → mechanical, budget spent — respawn lint-fixer at <file:line>; leftovers of its two-run no-progress stop return as mechanical, no progress and are never respawned. Callers respawn a fresh lint-fixer at most three times per scope and stop after one reports FIXED: none on the same packages. The parsed report openings are unchanged.

S4 — skill text on a diet

• pre-commit-review: SKILL.md keeps the protocol and the contract the graders read (spawn-prompt items, one line per anchored finding, cluster entries, the reconciliation header with not reached: and PARTIAL coverage, report as the message), plus the bundle recipe, which every review needs early. A new reference.md holds the hunt-focus table, waiting for agents, hunter output, skeptic and critic verdicts, the merged report and the report example.
• refactoring: SKILL.md keeps the routing table, the loop, the suppression prohibition with its scan, the compact six-step stopping criteria and the Stop check output contract. reference.md gains the pattern index, <file_and_package_routing> / <package_decomposition>, preparatory mode in full, the stopping criteria in full and integration, and keeps the multi-rule procedures.
• Round trips, not text, decide S4's sign (the cost review's finding). Every reference range is printed inside a Bash call the step already makes — the pre-filter, the bundle write, the loop's first lint run, the Gates run of the exit — never as a call of its own; only the report's long form is read on its own, once, before writing. Every pointer carries its sed range; all twelve cited ranges resolve against the rendered reference files; no command wraps across lines.
• Cross-references updated: code-designing (core and the Go and Python includes), the LDD skill, the quickfix command, the routing-table includes and the Go package-size hook all cite <package_decomposition> in the refactoring skill's reference.md, with the range.
• Rendered sizes: both skills at about 13k, from 30k and 23k. The 10k target was not reached; the remainder is the routing table, the bundle recipe, the suppression scan, the spawn-prompt items and the two contracts, which are protocol. The docs say so.

Also in this PR

• docs/token-budget.md: S3 and S4 describe what landed, including the batching rule; S1 to S4 marked landed but unproven. Changelog entries under [Unreleased] in all three bindings. The core README's residue section regenerated by lint-core.
• Passing locally: ldd-gen -check, lint-core, the generator's Go tests, the three gate test matrices, the docs gate, bash -n on the edited hook.

Cases that must not move (Gate 1)

Every refactor case's stop-check grader (six Stop check openings in order) and art judges; every review case's graders, the whole-repository review's recall count, the clean-tree controls; the red-lint quickfix's LINT STATUS and escalation routing.

Gate 2 to check on the proof run

Refactor tier from 65.9M toward about 45M; the 20M-token class of run gone (no general row in the spend report's per-agent table); lint-fixer read as spawns times median turns, not median turns alone; main-thread calls per run up by no more than about three from the reference reads; mean context on refactor runs down by 3k to 5k.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bs5wvpmT7xZst7m1nXXkWB

[Copilot]

Copilot review overview

🟡 Changes recommended

Reference ordering, an invalid doctrine path, incomplete decomposition ranges, and unresolved mechanical-escalation handling can break the documented workflows.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 5 · 4

Open (9)

• Stop and report unresolved failures after retry cutoff · New
• Do not route mechanical budget leftovers to refactoring · New
• Print inspection ranges before applying refactoring · New
• Fix incorrect relative path to documentation reference · New
• Include full package decomposition procedure in cited range · New
• Describe Agent restriction as delegated refactoring only · New
• Remove bundle recipe from moved-material list · New
• Remove bundle recipe from moved-material list · New
• Remove bundle recipe from moved-material list · New

What changed in this PR

Implements token-budget stages S3–S4 by bounding lint-fixer work, keeping refactoring in the main thread, and moving detailed skill guidance into reference files.

Changes:

• Adds lint-fixer retry and budget protocols.
• Extracts review/refactoring guidance into ranged reference sections.
• Regenerates all language bindings and updates documentation.

File	Description
core/​agents/​lint-fixer.md	Defines the lint-fixer budget and escalation format.
core/​commands/​{{.CmdPrefix}}-quickfix.md	Adds retry and delegation rules.
core/​includes/​skills/​code-designing/​linter-triggers.md	Updates package-decomposition reference.
core/​includes/​skills/​refactoring/​routing-table.md	Updates refactoring reference range.
core/​README.md	Regenerates language-residue counts.
core/​skills/​code-designing/​SKILL.md	Updates decomposition guidance.
core/​skills/​linter-driven-development/​SKILL.md	Defines agent ownership and retry handling.
core/​skills/​pre-commit-review/​reference.md	Adds extracted review guidance.
core/​skills/​refactoring/​reference.md	Adds extracted refactoring guidance.
core/​skills/​refactoring/​SKILL.md	Compacts the refactoring protocol.
docs/​token-budget.md	Documents landed S3–S4 behavior.
go-linter-driven-development/​agents/​lint-fixer.md	Renders Go lint-fixer budgeting.
go-linter-driven-development/​CHANGELOG.md	Records Go binding changes.
go-linter-driven-development/​commands/​go-ldd-quickfix.md	Renders Go retry rules.
go-linter-driven-development/​hooks/​check-package-sizes.sh	Updates decomposition guidance.
go-linter-driven-development/​skills/​code-designing/​SKILL.md	Renders Go design references.
go-linter-driven-development/​skills/​linter-driven-development/​SKILL.md	Renders Go agent protocol.
go-linter-driven-development/​skills/​pre-commit-review/​reference.md	Renders Go review reference.
go-linter-driven-development/​skills/​refactoring/​reference.md	Renders Go refactoring reference.
go-linter-driven-development/​skills/​refactoring/​SKILL.md	Renders compact Go refactoring skill.
lang/​generic/​passthrough/​CHANGELOG.md	Supplies generic changelog text.
lang/​go/​passthrough/​CHANGELOG.md	Supplies Go changelog text.
lang/​go/​passthrough/​hooks/​check-package-sizes.sh	Supplies updated hook message.
lang/​go/​skills/​code-designing/​linter-triggers.md	Supplies Go design trigger reference.
lang/​go/​skills/​refactoring/​routing-table.md	Supplies Go routing reference.
lang/​python/​passthrough/​CHANGELOG.md	Supplies Python changelog text.
lang/​python/​skills/​code-designing/​linter-triggers.md	Supplies Python design trigger reference.
lang/​python/​skills/​refactoring/​routing-table.md	Supplies Python routing reference.
linter-driven-development/​agents/​lint-fixer.md	Renders generic lint-fixer budgeting.
linter-driven-development/​CHANGELOG.md	Records generic binding changes.
linter-driven-development/​commands/​ldd-quickfix.md	Renders generic retry rules.
linter-driven-development/​skills/​code-designing/​SKILL.md	Renders generic design references.
linter-driven-development/​skills/​linter-driven-development/​SKILL.md	Renders generic agent protocol.
linter-driven-development/​skills/​pre-commit-review/​reference.md	Renders generic review reference.
linter-driven-development/​skills/​refactoring/​reference.md	Renders generic refactoring reference.
linter-driven-development/​skills/​refactoring/​SKILL.md	Renders compact generic refactoring skill.
python-linter-driven-development/​agents/​lint-fixer.md	Renders Python lint-fixer budgeting.
python-linter-driven-development/​CHANGELOG.md	Records Python binding changes.
python-linter-driven-development/​commands/​py-ldd-quickfix.md	Renders Python retry rules.
python-linter-driven-development/​skills/​code-designing/​SKILL.md	Renders Python design references.
python-linter-driven-development/​skills/​linter-driven-development/​SKILL.md	Renders Python agent protocol.
python-linter-driven-development/​skills/​pre-commit-review/​reference.md	Renders Python review reference.
python-linter-driven-development/​skills/​refactoring/​reference.md	Renders Python refactoring reference.
python-linter-driven-development/​skills/​refactoring/​SKILL.md	Renders compact Python refactoring skill.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.