@event4u/agent-config 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -318,6 +318,95 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.17.0](https://github.com/event4u-app/agent-config/compare/1.16.0...1.17.0) (2026-05-04)
+
+### Features
+
+* **commands:** nest commit/create-pr/feature sub-commands under colon namespace ([ceef48b](https://github.com/event4u-app/agent-config/commit/ceef48bd5b5ff550bc560e722516037a4f45e895))
+* **rules:** add no-roadmap-references rule + CI linter ([a2882a8](https://github.com/event4u-app/agent-config/commit/a2882a8a424b6bee8829426f19e531931e9c77c2))
+* **hooks:** add roadmap-progress-sync pilot hook ([48484f2](https://github.com/event4u-app/agent-config/commit/48484f28cf1ca8857c54d65e7965f62aed552ea2))
+* **budget:** add concentration gate + trend logging ([06f3855](https://github.com/event4u-app/agent-config/commit/06f385518e8326bc4528a7bf7ebfc0c639ddd89a))
+* **council:** add /council cluster dispatcher ([e7aa0c6](https://github.com/event4u-app/agent-config/commit/e7aa0c6970db634b484046f5899165e8fd3ac8a2))
+* **rules:** slim 12 auto-rules — extract mechanics to load_context (Phase 2B) ([9d211c6](https://github.com/event4u-app/agent-config/commit/9d211c68824dde0e7c21592a3079f76deae8cd96))
+* **commands:** Phase 1 — command cluster Phase 2 dispatchers + shims ([2e9d8e0](https://github.com/event4u-app/agent-config/commit/2e9d8e0fcb85f1b34d528a3f3e991e6cd5ba1388))
+* **followups:** land Phase 1 — load_context: rollout regression test + 1.15 archive verification (F2, F12) ([4ce552a](https://github.com/event4u-app/agent-config/commit/4ce552a8181668ee4c7ac20d669ce179dbdd4ab6))
+* **followups:** land Phase 0b.2 budget headroom recovery (F10) ([62838b3](https://github.com/event4u-app/agent-config/commit/62838b3df6fe7493876594ed84c908241cc286c7))
+* **structural:** lock Phase 0.4 2A.4 contract after council acceptance ([70a13d3](https://github.com/event4u-app/agent-config/commit/70a13d3a17bbea11a7b55af3bd8c16f130d954f2))
+* **structural:** land Phase 0.5 3a-spike scoring protocol + persona-voice rubric ([0fac3eb](https://github.com/event4u-app/agent-config/commit/0fac3ebafa00855d69dc9ca4cbade1a8b3797244))
+* **structural:** land Phase 0.4 2A.4 worked example ([e1412d3](https://github.com/event4u-app/agent-config/commit/e1412d345eb5432e4443b3e077bc1693d2cf3855))
+* **structural:** land Phase 0.3 Phase 6 -> 2B decoupling proof ([67b1024](https://github.com/event4u-app/agent-config/commit/67b1024560552547d79019c3566c1dec0299a948))
+* **structural:** land Phase 0.2 load_context: budget accounting model ([32cfcd4](https://github.com/event4u-app/agent-config/commit/32cfcd41d23998a705128c78f2c0a2bcdf341c87))
+* **structural:** land Phase 0.1 file-ownership matrix schema + generator ([d1dfb02](https://github.com/event4u-app/agent-config/commit/d1dfb024d4ef31aab88bfd749a6e5e5167ac5d75))
+* **structural:** land Phase 0.6 context-file path conventions ([e9c72f4](https://github.com/event4u-app/agent-config/commit/e9c72f4bde948c38bde6e5e740852c29582df91c))
+
+### Bug Fixes
+
+* **refs:** repair 4 broken cross-references ([7b0f014](https://github.com/event4u-app/agent-config/commit/7b0f014db19af0e9d68979a3ff9d12555f1ee6f5))
+* **sync:** prevent recursive _user prefixing and heal legacy corruption ([0cb0845](https://github.com/event4u-app/agent-config/commit/0cb0845320e14584348505fa0540315091ba7ef9))
+* **ci:** install pyyaml in consistency workflow ([bbad5d0](https://github.com/event4u-app/agent-config/commit/bbad5d06009a3f204051ca3b01102827162fe2f3))
+* **check-refs:** skip references into SKIP_DIRS (gitignored audit trails) ([cd6fcce](https://github.com/event4u-app/agent-config/commit/cd6fcce5411c35baaf228dc3fe0a4202acab6eca))
+* **roadmaps:** mark example/spike/coupling docs as status: draft ([d84dcf4](https://github.com/event4u-app/agent-config/commit/d84dcf44a9f777d87ef273b700ef66389216157d))
+* **compress:** carry load_context into compressed slash-command-routing-policy ([8332fb0](https://github.com/event4u-app/agent-config/commit/8332fb06a4c61ec65e9e21a6a123ea10484477de))
+
+### Documentation
+
+* repoint cross-references to nested command paths ([fbfb048](https://github.com/event4u-app/agent-config/commit/fbfb0481113aa065779ace75cbd0914eaf002d7c))
+* **roadmap:** add Phase 0a closeout hygiene to rule-hardening ([d68c4f2](https://github.com/event4u-app/agent-config/commit/d68c4f22d09ed9c3b567e996834c0148ffd17492))
+* sync command-count messaging in README/AGENTS/getting-started ([c683e9a](https://github.com/event4u-app/agent-config/commit/c683e9a4bc93294940a8f07402f88510796d91d8))
+* **roadmap:** rule-hardening v2 — council-reviewed revisions ([4d9e225](https://github.com/event4u-app/agent-config/commit/4d9e225108b9c647157eb1f6df9b55c13665588e))
+* **roadmaps:** add context-layer-maturity v2 and rule-hardening ([620961b](https://github.com/event4u-app/agent-config/commit/620961b3f469ddf0ac40ee491c3b65cab0e1000a))
+* **phase6:** chat-history-* trigger overlap audit — Path B (orthogonal) ([62ffad2](https://github.com/event4u-app/agent-config/commit/62ffad234c50ab9930115813e6801a2a8e976199))
+* **phase3:** consolidation audit — DO NOT CONSOLIDATE verdict ([03dc6aa](https://github.com/event4u-app/agent-config/commit/03dc6aad88aee2ebd85bd1d95f402742fcce05d1))
+* **readme:** trim Requirements section to clear lint-readme overload threshold ([30bf18d](https://github.com/event4u-app/agent-config/commit/30bf18da26ce69fe8bf1d688309ad375a082de6b))
+* **counts:** sync command-count messaging after Phase 1 clusters ([8902f49](https://github.com/event4u-app/agent-config/commit/8902f49f3239274828d13ce61a2b28a415dda3f5))
+* **roadmap:** drop slow-rollout protocol; lock single-PR execution (v3.2) ([35885b0](https://github.com/event4u-app/agent-config/commit/35885b01ee3c1510b2e30ad9a3bd40b686efefdf))
+* **followups:** land Phase 2 — README onboarding anchor + host-agent terminology (F1, F3, F4) ([cd12f97](https://github.com/event4u-app/agent-config/commit/cd12f9717c6b6e34efa01e55046d9f0ba0276286))
+* **roadmap:** close out 1.16 followups Phase 0a (F9 + F14 = no-op) ([6171f80](https://github.com/event4u-app/agent-config/commit/6171f805729d45084fee80704be9ec6908f1c84e))
+* **ai-council:** add experimental banner per F11 ([17308e1](https://github.com/event4u-app/agent-config/commit/17308e124fa436fac47f42649a5d1abcdb20f503))
+* **roadmap:** add 1.16.0 follow-ups roadmap v1.1 ([e402e1d](https://github.com/event4u-app/agent-config/commit/e402e1d599d1797a04a70b9fb538fa0bae913645))
+* **roadmap:** add structural-optimization roadmap v3.1 ([547f802](https://github.com/event4u-app/agent-config/commit/547f8024671e1f79570b2a5d69218f93ef1a346c))
+
+### Refactoring
+
+* **commands:** nest cluster commands into subdirectories ([5fd0df3](https://github.com/event4u-app/agent-config/commit/5fd0df387f0f2182e029fc3f40e5bce3fc4ed598))
+* **refs:** purge roadmap-file links from stable artifacts ([b5a1429](https://github.com/event4u-app/agent-config/commit/b5a1429e3f6a7fa754e816d9ddb1c4b0a6034735))
+* **rules:** amortize shared brevity examples to guideline ([ee581f6](https://github.com/event4u-app/agent-config/commit/ee581f69cc1106ec485dfb7f3ac07ffc2e2886cb))
+
+### Tests
+
+* **followups:** land Phase 0b.1 failure-mode coverage (F13) ([9560667](https://github.com/event4u-app/agent-config/commit/9560667a328f746316828ab44f0a7ba1fe8c254c))
+
+### Chores
+
+* **generated:** regenerate compressed dispatchers + hash registry ([552ddfe](https://github.com/event4u-app/agent-config/commit/552ddfeef4837b9681fc3ee72a1a01cf6c230d1a))
+* **commands:** drop ## Migration sections from cluster dispatchers ([02a03e7](https://github.com/event4u-app/agent-config/commit/02a03e7b7fbcc62c1203b7fedef38f0685e85321))
+* **generated:** regenerate compressed sources, tool projections, marketplace, ownership matrix ([f1dddd2](https://github.com/event4u-app/agent-config/commit/f1dddd2499625382b7f7902268bdd468426ce515))
+* **test:** align command-suggester golden + count gate to colon naming ([e1aad41](https://github.com/event4u-app/agent-config/commit/e1aad41624b877e4cb066d6e5075326de79f3693))
+* **generated:** regenerate file-ownership-matrix after command nesting ([12dc0f3](https://github.com/event4u-app/agent-config/commit/12dc0f3b266d6cdec6a53c918fc86098103d0373))
+* **generated:** regenerate compressed sources, tool projections,                    marketplace, and ownership matrix ([6724878](https://github.com/event4u-app/agent-config/commit/67248786c7589a63c2dabc80b683ace602611ddf))
+* **tooling:** teach scripts to walk nested command directories ([fe5913e](https://github.com/event4u-app/agent-config/commit/fe5913ef2ab6766a042d5e9470e0871d80804ddd))
+* **generated:** regenerate counts, hashes, windsurfrules ([5613b48](https://github.com/event4u-app/agent-config/commit/5613b4858da531a23aa27e23a2bda561152d3809))
+* **roadmaps:** archive 4 closed phase-evidence reports ([d5995c3](https://github.com/event4u-app/agent-config/commit/d5995c31febb3dad31df95d72970de1e1bcf3181))
+* **generated:** regenerate file-ownership-matrix ([75ff69f](https://github.com/event4u-app/agent-config/commit/75ff69fdb45952e00320918d597ea2db239a7f0b))
+* **generated:** regenerate windsurfrules + counts + claude council-default ([02ad3e1](https://github.com/event4u-app/agent-config/commit/02ad3e1079f797f8a72c33f800f1d395499b951e))
+* add ai council scripts ([4cf513c](https://github.com/event4u-app/agent-config/commit/4cf513c90649292324579444f586becd78cfad96))
+* **roadmap:** close & archive road-to-structural-optimization ([3bfef51](https://github.com/event4u-app/agent-config/commit/3bfef5118cdb66db5809fddb3688bb22d3aa8aff))
+* **compression:** refresh compression hashes ([20717d7](https://github.com/event4u-app/agent-config/commit/20717d798c86dd99f17d4c851ea0a8754e249333))
+* regenerate ownership matrix after Phase 2B rule slimming ([17ac19c](https://github.com/event4u-app/agent-config/commit/17ac19cf1938c7fca945b4500c6232cfa4549f2c))
+* **structural:** regenerate file-ownership-matrix after Phase 1 clusters ([29aabb1](https://github.com/event4u-app/agent-config/commit/29aabb11351f9fe648644b508eb6d24a5870b160))
+* **sync:** regenerate agents/index.md + docs/catalog.md after Phase 1 clusters ([f07987a](https://github.com/event4u-app/agent-config/commit/f07987ac12aaa77cbc4c7584ac00607e5a438318))
+* **sync:** regenerate compressed outputs + tool projections for Phase 1 clusters ([99466c0](https://github.com/event4u-app/agent-config/commit/99466c0a77116c7ed70db38fd957d061ad18e307))
+* **sync:** compress contexts/judges/persona-voice-rubric.md into .agent-src/ ([4060d01](https://github.com/event4u-app/agent-config/commit/4060d01af0680c2a913295166b978b605b1453db))
+* **roadmap:** archive road-to-1-16-followups (100% done) + regen dashboard ([f78a9ad](https://github.com/event4u-app/agent-config/commit/f78a9ada649c01c03aa4e866e20bb32b547cd9d0))
+* **roadmap:** regenerate progress dashboard after 1.16 followups Phase 1+2 ([780db39](https://github.com/event4u-app/agent-config/commit/780db39b68230b68c51f158d8cc8b78e7937a40c))
+* **ai-council:** add multi-provider council scripts and openai sdk ([3c2360d](https://github.com/event4u-app/agent-config/commit/3c2360d137069287b7e2547a6132d36ebed09978))
+* add task command, to install chatgpt key ([1acea8b](https://github.com/event4u-app/agent-config/commit/1acea8b6dc329c70079cec42d5a98886c913acfd))
+
+### Other
+
+* **commands:** update cross-references to colon-namespaced sub-commands ([13caa6d](https://github.com/event4u-app/agent-config/commit/13caa6d9c116012f726947fa50a281ca34ce16c2))
+* fix_: thinking drift ([1d2d158](https://github.com/event4u-app/agent-config/commit/1d2d15833e6b9764e7c734e66b25cecdf1dc12ab))
+
 ## [1.16.0](https://github.com/event4u-app/agent-config/compare/1.15.0...1.16.0) (2026-05-03)
 
 ### Features
@@ -552,7 +641,7 @@ our recommendation order, not its support status.
 * **linear:** Phase 3 — Linear AI rules digest builder + three-layer split ([3dcbf0a](https://github.com/event4u-app/agent-config/commit/3dcbf0af3c2dca70ef70f18af70a3568516f0147))
 * **rules:** add commit-policy as canonical no-commit-no-ask rule ([fd208ea](https://github.com/event4u-app/agent-config/commit/fd208ea1c0f95aaa58d930c99ff0e51dd27600ed))
 * **rules:** add autonomous-execution rule with intent-based opt-in ([fbff529](https://github.com/event4u-app/agent-config/commit/fbff5299b32606b7f13f06c856a4d4556c908fcb))
-* **commands:** add /commit-in-chunks for autonomous commit splitting ([b53fa7b](https://github.com/event4u-app/agent-config/commit/b53fa7b277a107af8acc6076baf8c985f0fbb901))
+* **commands:** add /commit:in-chunks for autonomous commit splitting ([b53fa7b](https://github.com/event4u-app/agent-config/commit/b53fa7b277a107af8acc6076baf8c985f0fbb901))
 * **cloud:** mark T3-H artifacts cloud-safe (4 noop + 4 degrade) ([0eb7eb3](https://github.com/event4u-app/agent-config/commit/0eb7eb3cdbf590e3ef87f372c3fd09d85aa5cfd5))
 * **cloud:** cloud-safe marker detection + variant rendering ([67bf28b](https://github.com/event4u-app/agent-config/commit/67bf28b8f85384333f5d26807ad92e6d0b456288))
 * **cloud:** cloud-bundle builder with T3-H gating + tests ([f749edc](https://github.com/event4u-app/agent-config/commit/f749edc8c0f16cded153eb24580c4b262a6065ae))

package/README.md

@@ -7,11 +7,21 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>129 Skills</strong> · <strong>57 Rules</strong> · <strong>69 Commands</strong> · <strong>47 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>129 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>48 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
 
+## Start here
+
+New to agent-config? 60 seconds, three links:
+
+1. **[Install](#quickstart)** — `composer require` or `npm install`, then run the installer.
+2. **[First command](#2-minute-demo-implement-ticket)** — `/implement-ticket` or `/work` walkthrough.
+3. **[Where the rules live](#documentation)** — `.augment/`, `.claude/`, `.cursor/`, and friends.
+
+---
+
 ## Quickstart
 
 Two minutes from `composer require` to a better-behaved agent.
@@ -322,7 +332,7 @@ Nothing runs automatically without your control. [Configure modes →](docs/cust
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 69 active commands](.agent-src/commands/) &nbsp;<sub>(84 files total — 15 are deprecation shims that redirect to clustered commands)</sub>
+→ [Browse all 95 active commands](.agent-src/commands/)
 
 ---
 
@@ -347,7 +357,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 129 skills + 69 native commands). Cursor, Cline, Windsurf,
+> package (rules + 129 skills + 95 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.
@@ -479,20 +489,11 @@ task lint-skills   # Lint skills, rules, commands
   orchestrator skips bridges and completes the payload sync.
 - **Composer or npm** — to pull the package itself.
 
-**Platform support:**
-
-| Platform | Status |
-|---|---|
-| macOS 12.3+ | ✅ Supported |
-| Linux (modern distros) | ✅ Supported |
-| Windows (WSL2) | ✅ Supported |
-| Windows (Git Bash) | ⚠️ Works; symlinks need Developer Mode |
-| Windows (native PowerShell/cmd) | ❌ Not supported |
-
-**For contributors only** (rebuilding `.augment/` locally):
-
-- [Task](https://taskfile.dev/) — runs the CI pipeline (`task ci`).
+**Platform support:** macOS 12.3+, Linux (modern distros), and Windows
+(WSL2) are fully supported. Git Bash works but symlinks require
+Developer Mode; native PowerShell / cmd is not supported. Contributors
+rebuilding `.augment/` locally also need [Task](https://taskfile.dev/).
 
 ## License
 
-[MIT](LICENSE) — you can use, fork, and redistribute this freely.
+[MIT](LICENSE).

package/docs/architecture.md

@@ -19,9 +19,7 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 - **experimental** = scaffold or pilot status; breaks allowed in any release.
 
 > The previous "observability, feedback, lifecycle" layers were removed in
-> 1.5 — they were scaffolds without production consumers. See the
-> [`archive/road-to-9.md`](../agents/roadmaps/archive/road-to-9.md) roadmap,
-> phase 4, for the rationale.
+> 1.5 — they were scaffolds without production consumers.
 
 ## Content pipeline
 
@@ -65,9 +63,9 @@ fails on any source-side violation, without producing artifacts.
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 129 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 57 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 84 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 47 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 95 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 48 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **299 public artefacts** shipped by
+Consumer-facing catalog of all **327 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -141,7 +141,7 @@ are excluded.
 | skill | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) |  | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (54)
+## Rules (55)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -175,6 +175,7 @@ are excluded.
 | rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
+| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request |
 | rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | auto | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
@@ -200,85 +201,112 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (69)
+## Commands (95)
 
 | kind | name | cluster | description |
 |---|---|---|---|
 | command | [`agent-handoff`](../.agent-src/commands/agent-handoff.md) |  | Generate a context summary for continuing work in a fresh chat. Replaces the session system. |
 | command | [`agent-status`](../.agent-src/commands/agent-status.md) |  | Show current conversation stats — message count, token costs, task progress, next freshness check. |
-| command | [`agents-audit`](../.agent-src/commands/agents-audit.md) |  | Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap. |
-| command | [`agents-cleanup`](../.agent-src/commands/agents-cleanup.md) |  | Execute cleanup actions from an agents-audit — move, merge, delete, and update agent docs |
-| command | [`agents-prepare`](../.agent-src/commands/agents-prepare.md) |  | Scaffold the agents/ directory structure with all required subdirectories and .gitkeep files |
+| command | [`agents:audit`](../.agent-src/commands/agents/audit.md) | cluster: agents | Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap. |
+| command | [`agents:cleanup`](../.agent-src/commands/agents/cleanup.md) | cluster: agents | Execute cleanup actions from an agents-audit — move, merge, delete, and update agent docs |
+| command | [`agents:prepare`](../.agent-src/commands/agents/prepare.md) | cluster: agents | Scaffold the agents/ directory structure with all required subdirectories and .gitkeep files |
+| command | [`agents`](../.agent-src/commands/agents.md) | cluster: agents | Agents-folder orchestrator — routes to audit, cleanup, prepare |
 | command | [`analyze-reference-repo`](../.agent-src/commands/analyze-reference-repo.md) |  | Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project. |
 | command | [`bug-fix`](../.agent-src/commands/bug-fix.md) |  | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 | command | [`bug-investigate`](../.agent-src/commands/bug-investigate.md) |  | Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause |
-| command | [`chat-history-checkpoint`](../.agent-src/commands/chat-history-checkpoint.md) |  | Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s. |
-| command | [`chat-history-clear`](../.agent-src/commands/chat-history-clear.md) |  | Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping |
-| command | [`chat-history-resume`](../.agent-src/commands/chat-history-resume.md) |  | Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue |
-| command | [`chat-history`](../.agent-src/commands/chat-history.md) |  | Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries |
+| command | [`chat-history:checkpoint`](../.agent-src/commands/chat-history/checkpoint.md) | cluster: chat-history | Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s. |
+| command | [`chat-history:clear`](../.agent-src/commands/chat-history/clear.md) | cluster: chat-history | Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping |
+| command | [`chat-history:resume`](../.agent-src/commands/chat-history/resume.md) | cluster: chat-history | Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue |
+| command | [`chat-history:show`](../.agent-src/commands/chat-history/show.md) | cluster: chat-history | Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries |
+| command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, resume, clear, checkpoint |
 | command | [`check-current-md`](../.agent-src/commands/check-current-md.md) |  | Check the open .md file (or a passed path) for German outside DE:/EN: anchor blocks — umlauts, function words, untranslated quotes. Reports and offers fixes. |
-| command | [`commit-in-chunks`](../.agent-src/commands/commit-in-chunks.md) |  | Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for autonomous flows |
-| command | [`commit`](../.agent-src/commands/commit.md) |  | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
+| command | [`commit:in-chunks`](../.agent-src/commands/commit/in-chunks.md) | cluster: commit | Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for autonomous flows |
+| command | [`commit`](../.agent-src/commands/commit.md) | cluster: commit | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
 | command | [`compress`](../.agent-src/commands/compress.md) |  | Compress .md files from .agent-src.uncompressed/ into caveman format and write to .agent-src/ |
-| command | [`context-create`](../.agent-src/commands/context-create.md) |  | Analyze a codebase area and create a structured context document |
-| command | [`context-refactor`](../.agent-src/commands/context-refactor.md) |  | Analyze, update, and extend an existing context document |
-| command | [`copilot-agents-init`](../.agent-src/commands/copilot-agents-init.md) |  | Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers. |
-| command | [`copilot-agents-optimize`](../.agent-src/commands/copilot-agents-optimize.md) |  | Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience. |
-| command | [`council-design`](../.agent-src/commands/council-design.md) | cluster: optimize | Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment. |
-| command | [`council-optimize`](../.agent-src/commands/council-optimize.md) | cluster: optimize | Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice. |
-| command | [`council-pr`](../.agent-src/commands/council-pr.md) | cluster: optimize | Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in. |
-| command | [`council`](../.agent-src/commands/council.md) | cluster: optimize | Consult external AIs (OpenAI, Anthropic) for an independent second opinion on a prompt, roadmap, diff, or file set — neutral framing, redacted context, advisory output only. |
-| command | [`create-pr-description`](../.agent-src/commands/create-pr-description.md) |  | Generate a PR description as a copyable markdown block — used standalone or by create-pr |
-| command | [`create-pr`](../.agent-src/commands/create-pr.md) |  | Create a GitHub PR with structured description from Jira ticket and code changes |
-| command | [`do-and-judge`](../.agent-src/commands/do-and-judge.md) |  | Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user |
-| command | [`do-in-steps`](../.agent-src/commands/do-in-steps.md) |  | Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict |
+| command | [`context:create`](../.agent-src/commands/context/create.md) | cluster: context | Analyze a codebase area and create a structured context document |
+| command | [`context:refactor`](../.agent-src/commands/context/refactor.md) | cluster: context | Analyze, update, and extend an existing context document |
+| command | [`context`](../.agent-src/commands/context.md) | cluster: context | Context orchestrator — routes to create, refactor |
+| command | [`copilot-agents:init`](../.agent-src/commands/copilot-agents/init.md) | cluster: copilot-agents | Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers. |
+| command | [`copilot-agents:optimize`](../.agent-src/commands/copilot-agents/optimize.md) | cluster: copilot-agents | Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience. |
+| command | [`copilot-agents`](../.agent-src/commands/copilot-agents.md) | cluster: copilot-agents | Copilot agents-doc orchestrator — routes to init, optimize |
+| command | [`council:default`](../.agent-src/commands/council/default.md) | cluster: council | Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare. |
+| command | [`council:design`](../.agent-src/commands/council/design.md) | cluster: council | Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment. |
+| command | [`council:optimize`](../.agent-src/commands/council/optimize.md) | cluster: council | Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice. |
+| command | [`council:pr`](../.agent-src/commands/council/pr.md) | cluster: council | Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in. |
+| command | [`council`](../.agent-src/commands/council.md) | cluster: council | Council orchestrator — routes to default, pr, design, optimize |
+| command | [`create-pr:description-only`](../.agent-src/commands/create-pr/description-only.md) | cluster: create-pr | Generate a PR description as a copyable markdown block — used standalone or by create-pr |
+| command | [`create-pr`](../.agent-src/commands/create-pr.md) | cluster: create-pr | Create a GitHub PR with structured description from Jira ticket and code changes |
 | command | [`e2e-heal`](../.agent-src/commands/e2e-heal.md) |  | Find, debug, and fix failing Playwright E2E tests |
 | command | [`e2e-plan`](../.agent-src/commands/e2e-plan.md) |  | Explore the application and create a structured E2E test plan in Markdown |
 | command | [`estimate-ticket`](../.agent-src/commands/estimate-ticket.md) |  | Estimate a Jira/Linear ticket before sprint planning — size + risk + split recommendation + uncertainty, sibling to /refine-ticket, ends with a close-prompt |
-| command | [`feature-dev`](../.agent-src/commands/feature-dev.md) |  | Full 7-phase feature development workflow for complex features. |
+| command | [`feature:dev`](../.agent-src/commands/feature/dev.md) | cluster: feature | Full 7-phase feature development workflow for complex features. |
+| command | [`feature:explore`](../.agent-src/commands/feature/explore.md) | cluster: feature | Brainstorm and explore a feature idea before committing to a full plan |
+| command | [`feature:plan`](../.agent-src/commands/feature/plan.md) | cluster: feature | Interactively plan a feature — research, discuss, and create a structured feature document |
+| command | [`feature:refactor`](../.agent-src/commands/feature/refactor.md) | cluster: feature | Refine and update an existing feature plan through interactive discussion |
+| command | [`feature:roadmap`](../.agent-src/commands/feature/roadmap.md) | cluster: feature | Generate implementation roadmap(s) from a feature plan and link them |
 | command | [`feature`](../.agent-src/commands/feature.md) | cluster: feature | Feature orchestrator — routes to explore, plan, refactor, roadmap, dev |
+| command | [`fix:ci`](../.agent-src/commands/fix/ci.md) | cluster: fix | Fetch CI errors from GitHub Actions and fix them |
+| command | [`fix:portability`](../.agent-src/commands/fix/portability.md) | cluster: fix | Find and fix project-specific references in shared .augment/ package files |
+| command | [`fix:pr-bots`](../.agent-src/commands/fix/pr-bots.md) | cluster: fix | Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR |
+| command | [`fix:pr-developers`](../.agent-src/commands/fix/pr-developers.md) | cluster: fix | Fix and reply to human reviewer comments on a GitHub PR |
+| command | [`fix:pr`](../.agent-src/commands/fix/pr.md) | cluster: fix | Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR |
+| command | [`fix:refs`](../.agent-src/commands/fix/refs.md) | cluster: fix | Find and fix broken cross-references in .augment/ and agents/ files |
+| command | [`fix:seeder`](../.agent-src/commands/fix/seeder.md) | cluster: fix | Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them |
 | command | [`fix`](../.agent-src/commands/fix.md) | cluster: fix | Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments |
 | command | [`implement-ticket`](../.agent-src/commands/implement-ticket.md) |  | Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, block-on-ambiguity, no auto-git. |
 | command | [`jira-ticket`](../.agent-src/commands/jira-ticket.md) |  | Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug |
-| command | [`judge`](../.agent-src/commands/judge.md) |  | Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only |
-| command | [`memory-add`](../.agent-src/commands/memory-add.md) |  | Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules) |
-| command | [`memory-full`](../.agent-src/commands/memory-full.md) |  | Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analysis, never auto-triggered |
-| command | [`memory-promote`](../.agent-src/commands/memory-promote.md) |  | Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the admission gate. |
+| command | [`judge:on-diff`](../.agent-src/commands/judge/on-diff.md) | cluster: judge | Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user |
+| command | [`judge:solo`](../.agent-src/commands/judge/solo.md) | cluster: judge | Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only |
+| command | [`judge:steps`](../.agent-src/commands/judge/steps.md) | cluster: judge | Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict |
+| command | [`judge`](../.agent-src/commands/judge.md) | cluster: judge | Judge orchestrator — routes to solo, steps, on-diff |
+| command | [`memory:add`](../.agent-src/commands/memory/add.md) | cluster: memory | Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules) |
+| command | [`memory:load`](../.agent-src/commands/memory/load.md) | cluster: memory | Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analysis, never auto-triggered |
+| command | [`memory:promote`](../.agent-src/commands/memory/promote.md) | cluster: memory | Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the admission gate. |
+| command | [`memory:propose`](../.agent-src/commands/memory/propose.md) | cluster: memory | Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or agent) to record a finding without committing to a curated entry. |
+| command | [`memory`](../.agent-src/commands/memory.md) | cluster: memory | Memory orchestrator — routes to add, load, promote, propose |
 | command | [`mode`](../.agent-src/commands/mode.md) |  | Set the active role mode — prints the contract, lists default skills, and refuses work outside the contract (see role-contracts) |
-| command | [`module-create`](../.agent-src/commands/module-create.md) |  | Create a new module from .module-template with interactive setup |
-| command | [`module-explore`](../.agent-src/commands/module-explore.md) |  | Explore a module — load its structure, docs, and context into the current conversation |
+| command | [`module:create`](../.agent-src/commands/module/create.md) | cluster: module | Create a new module from .module-template with interactive setup |
+| command | [`module:explore`](../.agent-src/commands/module/explore.md) | cluster: module | Explore a module — load its structure, docs, and context into the current conversation |
+| command | [`module`](../.agent-src/commands/module.md) | cluster: module | Module orchestrator — routes to create, explore |
 | command | [`onboard`](../.agent-src/commands/onboard.md) |  | First-run setup for a developer on this project — captures name, IDE, bot-icon preference, rtk, cost_profile, and learning opt-out, then sets onboarding.onboarded=true |
+| command | [`optimize:agents`](../.agent-src/commands/optimize/agents.md) | cluster: optimize | Audits agent infrastructure — measures token overhead, checks rule triggers, verifies AGENTS.md. Suggest only, never auto-apply. |
+| command | [`optimize:augmentignore`](../.agent-src/commands/optimize/augmentignore.md) | cluster: optimize | Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules. |
+| command | [`optimize:rtk`](../.agent-src/commands/optimize/rtk.md) | cluster: optimize | Create or optimize project-local rtk filters based on the actual toolchain |
+| command | [`optimize:skills`](../.agent-src/commands/optimize/skills.md) | cluster: optimize | Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply. |
 | command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters |
-| command | [`override-create`](../.agent-src/commands/override-create.md) |  | Creates a project-level override for a shared skill, rule, or command. |
-| command | [`override-manage`](../.agent-src/commands/override-manage.md) |  | Reviews, updates, and refactors existing project-level overrides. |
+| command | [`override:create`](../.agent-src/commands/override/create.md) | cluster: override | Creates a project-level override for a shared skill, rule, or command. |
+| command | [`override:manage`](../.agent-src/commands/override/manage.md) | cluster: override | Reviews, updates, and refactors existing project-level overrides. |
+| command | [`override`](../.agent-src/commands/override.md) | cluster: override | Override orchestrator — routes to create, manage |
 | command | [`package-reset`](../.agent-src/commands/package-reset.md) |  | /package-reset |
 | command | [`package-test`](../.agent-src/commands/package-test.md) |  | /package-test |
 | command | [`prepare-for-review`](../.agent-src/commands/prepare-for-review.md) |  | Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date |
 | command | [`project-analyze`](../.agent-src/commands/project-analyze.md) |  | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
 | command | [`project-health`](../.agent-src/commands/project-health.md) |  | Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything |
-| command | [`propose-memory`](../.agent-src/commands/propose-memory.md) |  | Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or agent) to record a finding without committing to a curated entry. |
 | command | [`quality-fix`](../.agent-src/commands/quality-fix.md) |  | Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files |
 | command | [`refine-ticket`](../.agent-src/commands/refine-ticket.md) |  | Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt |
 | command | [`review-changes`](../.agent-src/commands/review-changes.md) |  | Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts |
 | command | [`review-routing`](../.agent-src/commands/review-routing.md) |  | Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml |
-| command | [`roadmap-create`](../.agent-src/commands/roadmap-create.md) |  | Interactively create a new roadmap file in agents/roadmaps/ |
-| command | [`roadmap-execute`](../.agent-src/commands/roadmap-execute.md) |  | Read and interactively execute a roadmap from agents/roadmaps/ |
+| command | [`roadmap:create`](../.agent-src/commands/roadmap/create.md) | cluster: roadmap | Interactively create a new roadmap file in agents/roadmaps/ |
+| command | [`roadmap:execute`](../.agent-src/commands/roadmap/execute.md) | cluster: roadmap | Read and interactively execute a roadmap from agents/roadmaps/ |
+| command | [`roadmap`](../.agent-src/commands/roadmap.md) | cluster: roadmap | Roadmap orchestrator — routes to create, execute |
 | command | [`rule-compliance-audit`](../.agent-src/commands/rule-compliance-audit.md) |  | Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules |
 | command | [`set-cost-profile`](../.agent-src/commands/set-cost-profile.md) |  | Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection |
 | command | [`sync-agent-settings`](../.agent-src/commands/sync-agent-settings.md) |  | Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing |
 | command | [`sync-gitignore`](../.agent-src/commands/sync-gitignore.md) |  | Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing |
-| command | [`tests-create`](../.agent-src/commands/tests-create.md) |  | Write meaningful tests for the changes in the current branch |
-| command | [`tests-execute`](../.agent-src/commands/tests-execute.md) |  | Run PHP tests inside the Docker container |
+| command | [`tests:create`](../.agent-src/commands/tests/create.md) | cluster: tests | Write meaningful tests for the changes in the current branch |
+| command | [`tests:execute`](../.agent-src/commands/tests/execute.md) | cluster: tests | Run PHP tests inside the Docker container |
+| command | [`tests`](../.agent-src/commands/tests.md) | cluster: tests | Tests orchestrator — routes to create, execute |
 | command | [`threat-model`](../.agent-src/commands/threat-model.md) |  | Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and authorization gaps before the first line of code is written |
 | command | [`update-form-request-messages`](../.agent-src/commands/update-form-request-messages.md) |  | Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and clean up stale ones |
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (47)
+## Guidelines (48)
 
 | kind | name | category | description |
 |---|---|---|---|
 | guideline | [`agent-interaction-and-decision-quality`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md) | agent-infra |  |
+| guideline | [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md) | agent-infra |  |
 | guideline | [`break-glass-usage`](../docs/guidelines/agent-infra/break-glass-usage.md) | agent-infra |  |
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |

package/docs/contracts/STABILITY.md

@@ -95,13 +95,21 @@ Numeric caps on the always-active rule surface. These are **load-bearing
 constants** — every reply the agent emits pays the always-rule cost, so
 the budget is part of the public contract, not an implementation detail.
 
+The accounting model since Phase 0.2 of `road-to-structural-optimization`
+is **Model (b) literal** — a rule's effective size is its own char count
+plus every context it loads (transitively, depth ≤ 2). See
+[`load-context-budget-model.md`](load-context-budget-model.md) (beta)
+for the contract and the transitional allowlist.
+
 | Constant | Value | Stability | Owner |
 |---|---|---|---|
-| Total always-rule budget | **49,000 chars** | `stable` | `tests/test_always_budget.py::test_always_rules_total_chars_under_cap` |
-| Warn threshold (CI) | **80% (39,200 chars)** | `beta` | `scripts/check_always_budget.py` |
-| Fail threshold (CI) | **90% (44,100 chars)** | `beta` | `scripts/check_always_budget.py` |
-| Per-rule cap | **6,000 chars** | `beta` | `tests/test_always_budget.py::test_no_single_always_rule_over_per_rule_cap` · `scripts/check_always_budget.py` |
-| Top-3 combined cap | **24,500 chars** (50% of total) | `beta` | `tests/test_always_budget.py::test_top3_always_rules_under_cap` · `scripts/check_always_budget.py` |
+| Total always-rule budget | **49,000 chars** (extended) | `stable` | `tests/test_always_budget.py::test_always_rules_total_extended_within_tolerance` |
+| G3 tolerance band | **2 % overshoot** (≤ 49,980 chars) | `beta` | `scripts/check_always_budget.py` · `tests/test_always_budget.py` |
+| Warn threshold (CI) | **80 % (39,200 chars)** | `beta` | `scripts/check_always_budget.py` |
+| Fail threshold (CI) | **90 % (44,100 chars)** below 100 %; **> 102 %** above | `beta` | `scripts/check_always_budget.py` |
+| Per-rule cap | **6,000 chars** (extended) with transitional allowlist | `beta` | `tests/test_always_budget.py::test_no_unallowlisted_per_rule_breach` · `scripts/check_always_budget.py` |
+| Top-3 combined cap | **24,500 chars** (extended, 50 % of total) | `beta` | `tests/test_always_budget.py::test_top3_extended_under_cap` · `scripts/check_always_budget.py` |
+| `load_context:` nesting cap | **depth ≤ 2** | `beta` | `tests/test_always_budget.py::test_load_context_depth_within_cap` · `scripts/check_always_budget.py` |
 
 **Promises a consumer can rely on:**
 
@@ -128,7 +136,5 @@ the budget is part of the public contract, not an implementation detail.
 
 ## See also
 
-- [`agents/roadmaps/road-to-post-pr29-optimize.md`](../../agents/roadmaps/road-to-post-pr29-optimize.md) — P0.1, P0.1a, P0.1b
-- [`agents/roadmaps/road-to-pr-34-followups.md`](../../agents/roadmaps/road-to-pr-34-followups.md) — Phase 7 (budget hardening)
 - [`docs/architecture.md`](../architecture.md) — package architecture overview
 - [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which always-rule wins on conflict

package/docs/contracts/adr-chat-history-split.md

@@ -4,9 +4,7 @@ stability: beta
 
 # ADR — Chat-history rule split
 
-> **Status:** Decided · 2026-05-02 · scoped under
-> [`road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md)
-> Phase 2 item P2.1.
+> **Status:** Decided · 2026-05-02
 > **Context:** AI #1, AI #3, AI #5 review of PR #29 flagged the
 > 200-line monolithic `rules/chat-history.md` as the rule the agent
 > revisited 12+ times during the 1.14.0 cycle — three independent

package/docs/contracts/adr-command-suggestion.md

@@ -5,7 +5,6 @@ stability: stable
 # ADR — Context-Aware Command Suggestion
 
 > **Status:** Decided · Phases 1–7 shipped · 2026-04-30
-> **Roadmap:** [`road-to-context-aware-command-suggestion.md`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md)
 > **Rule:** [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md)
 > **Eligibility table:** [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md)
 > **Engine:** `scripts/command_suggester/`
@@ -141,6 +140,5 @@ retirement candidates without a hard SLA.
 
 - [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md) — runtime rule
 - [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md) — locked eligibility table
-- [`road-to-context-aware-command-suggestion.md`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md) — phased delivery
 - [`adr-prompt-driven-execution.md`](adr-prompt-driven-execution.md) — `/work` entrypoint that explicit slash invocations route to
 - [`agent-settings`](../../.agent-src.uncompressed/templates/agent-settings.md) — `commands.suggestion.*` reference

package/docs/contracts/adr-implement-ticket-runtime.md

@@ -5,8 +5,7 @@ stability: stable
 # ADR — `/implement-ticket` runtime: Python
 
 > **Status:** Decided · Phase 0 spike closed · 2026-04-22
-> **Context:** [`implement-ticket-flow.md`](implement-ticket-flow.md) ·
-> [`road-to-implement-ticket.md`](../../agents/roadmaps/road-to-implement-ticket.md)
+> **Context:** [`implement-ticket-flow.md`](implement-ticket-flow.md)
 > **Supersedes:** the `Runtime: TBD` placeholder in `implement-ticket-flow.md`.
 
 ## Decision

package/docs/contracts/adr-product-ui-track.md

@@ -5,13 +5,11 @@ stability: stable
 # ADR — Product UI Track: audit-as-hard-gate, design-review loop, stack dispatch
 
 > **Status:** Decided · R3 Phases 1–6 shipped · 2026-05-01
-> **Context:** [`ui-track-flow.md`](ui-track-flow.md) ·
-> [`road-to-product-ui-track.md`](../../agents/roadmaps/road-to-product-ui-track.md) ·
-> [`road-to-product-ui-track-followup.md`](../../agents/roadmaps/archive/road-to-product-ui-track-followup.md)
+> **Context:** [`ui-track-flow.md`](ui-track-flow.md)
 > **Builds on:** [`adr-prompt-driven-execution.md`](adr-prompt-driven-execution.md)
 > — R2 envelope routing and the band-action gate that R3 widens to UI.
-> **Defers to:** Roadmap 4 (`road-to-visual-review-loop.md`, stub) for
-> headless-browser screenshot capture and visual-regression assertions.
+> **Defers to:** the visual-review-loop track for headless-browser
+> screenshot capture and visual-regression assertions.
 
 ## Decision
 
@@ -315,7 +313,6 @@ the contract first costs one halt and saves an entire polish round.
 ## R4 amendment — Visual Review Loop (2026-05-01)
 
 > **Status:** Decided · R4 Phases 0–4 shipped · Phase 5 in progress
-> **Roadmap:** [`road-to-visual-review-loop.md`](../../agents/roadmaps/road-to-visual-review-loop.md)
 
 R4 narrows the polish-termination contract from "subjective ceiling
 only" to "subjective ceiling **plus** objective a11y block", adds a

package/docs/contracts/adr-prompt-driven-execution.md

@@ -5,12 +5,11 @@ stability: stable
 # ADR — Prompt-Driven Execution: `/work` and the confidence-band gate
 
 > **Status:** Decided · R2 Phases 1–6 shipped · 2026-04-28
-> **Context:** [`implement-ticket-flow.md`](implement-ticket-flow.md) ·
-> [`road-to-prompt-driven-execution.md`](../../agents/roadmaps/archive/road-to-prompt-driven-execution.md)
+> **Context:** [`implement-ticket-flow.md`](implement-ticket-flow.md)
 > **Builds on:** [`adr-work-engine-rename.md`](adr-work-engine-rename.md) —
 > the universal-dispatcher refactor that this entrypoint slots into.
-> **Defers to:** Roadmap 3 (`road-to-product-ui-track.md`) for UI- and
-> mixed-intent prompts; this ADR is backend-only.
+> **Defers to:** [`adr-product-ui-track.md`](adr-product-ui-track.md) for
+> UI- and mixed-intent prompts; this ADR is backend-only.
 
 ## Decision
 

package/docs/contracts/agent-memory-contract.md

@@ -20,9 +20,9 @@ Last refreshed: 2026-04-22.
 
 ## What this doc is *not*
 
-- Not a replacement for
-  [`road-to-retrieval-contract.md`](../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md)
-  — that is the spec we hand to the agent-memory implementer.
+- Not a replacement for the agent-memory retrieval-contract spec —
+  that lives in the agent-memory package and is the spec we hand to
+  the implementer.
 - Not a commitment that consumer code looks exactly like this forever
   — it is a point-in-time pin.
 - Not an agent-facing skill. Humans read this when the package lands.
@@ -64,9 +64,9 @@ If the released package diverges from these names, we update
 
 ## Expected retrieval shape (present path)
 
-Source of truth:
-[`road-to-retrieval-contract.md`](../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md).
-Consumer skills call the shared abstraction, not the package directly.
+Source of truth: the retrieval-contract spec in the agent-memory
+package. Consumer skills call the shared abstraction, not the package
+directly.
 
 **Request** (Python):
 
@@ -139,11 +139,6 @@ holds:
 
 ## See also
 
-- [`road-to-memory-self-consumption.md`](../../agents/roadmaps/road-to-memory-self-consumption.md)
-- [`road-to-agent-memory-integration.md`](../../agents/roadmaps/road-to-agent-memory-integration.md)
-- [`agent-memory/road-to-retrieval-contract.md`](../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md)
-- [`agent-memory/road-to-promotion-flow.md`](../../agents/roadmaps/agent-memory/road-to-promotion-flow.md)
 - [`memory-access guideline`](../../docs/guidelines/agent-infra/memory-access.md)
 - [`scripts/memory_status.py`](../../.agent-src.uncompressed/templates/scripts/memory_status.py)
 - [`scripts/memory_lookup.py`](../../.agent-src.uncompressed/templates/scripts/memory_lookup.py)
-- [`open-questions-2.md`](../../agents/roadmaps/archive/open-questions-2.md) — Q29