@event4u/agent-config 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -318,6 +318,79 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.23.0](https://github.com/event4u-app/agent-config/compare/1.22.0...1.23.0) (2026-05-08)
+
+### Features
+
+* **skills:** add script-writing skill for scripts/ conventions ([1f8655d](https://github.com/event4u-app/agent-config/commit/1f8655d6cbf007410e3846ab502eea5745a7f66f))
+* **scripts:** Phase 10.7 --quiet flag + silent Taskfile + caveman compile-time toggle ([1d319e6](https://github.com/event4u-app/agent-config/commit/1d319e61a3c782eb5c86075f34275306a67c621c))
+* **linter:** frugality charter writer-cite validator + writer skill citations ([0e34709](https://github.com/event4u-app/agent-config/commit/0e3470965d5e2f4a8b11f27137d4ba43d2471be2))
+* **verbosity:** add verbosity toggles + gate routine outputs ([580d4cc](https://github.com/event4u-app/agent-config/commit/580d4cc2d1f4d4b091b6128f0a29d1f7e619895d))
+* **roadmap-sync:** pre-commit backstop blocks stale dashboard ([c577fc0](https://github.com/event4u-app/agent-config/commit/c577fc0aabc13faaae64c88d20d8ca66338ae5fc))
+* **create-pr:** drop council-review prompt ([e694811](https://github.com/event4u-app/agent-config/commit/e694811f7ca06b3db275cc70e83e6dbc4db72e42))
+* cite SPARC escalation thresholds in test-driven-development ([836f2ed](https://github.com/event4u-app/agent-config/commit/836f2edc2c288bcc7f878e97f42de954add8bb5b))
+* add mcp-request-signing guideline with HTTP-bridge appendix ([2ab67cd](https://github.com/event4u-app/agent-config/commit/2ab67cd401333ea61f47d43e952e7b07958feff3))
+* add cost-report command with token cost tracking ([262d865](https://github.com/event4u-app/agent-config/commit/262d865072d613647a439e89f83ded7334b60b1b))
+* add adr-create skill with index regeneration script ([7225105](https://github.com/event4u-app/agent-config/commit/7225105797d6810cad75bfa851f02b100e41ba29))
+
+### Bug Fixes
+
+* **docs:** bump command counts to 103 after cost-report addition ([2810fa5](https://github.com/event4u-app/agent-config/commit/2810fa5a54b7099123ae65e6c7c1325430bf3b77))
+
+### Documentation
+
+* sync counts (139 skills, 60 rules) + meta cleanups ([00c8b21](https://github.com/event4u-app/agent-config/commit/00c8b211edbc86cbe2f886107227e6bd46049c3b))
+* codify defer-with-trigger harvest policy ([b30dcd7](https://github.com/event4u-app/agent-config/commit/b30dcd72d0ffbd1fb2dbdd8ca28493a5b05a6bed))
+
+### Refactoring
+
+* **rules:** apply trim-frugality-canon Phase 1-3 trims ([ea1828a](https://github.com/event4u-app/agent-config/commit/ea1828af7bc69426386f6852cb69891309dce65f))
+
+### Chores
+
+* regenerate stale generated mirrors ([ea52e94](https://github.com/event4u-app/agent-config/commit/ea52e94415c4db5598e91d001e0fbeee10cae9be))
+* regenerate auto-generated artefacts ([fbe7d9e](https://github.com/event4u-app/agent-config/commit/fbe7d9ef137c9e584d7f88ce660afe29ab1a8d00))
+* bump skill/command/guideline counts and compression hashes ([18f4fad](https://github.com/event4u-app/agent-config/commit/18f4fad2372fd4347210199986909319c24ea0ec))
+* archive ruflo-adoption, move caveman-integration to skipped ([4c6c1eb](https://github.com/event4u-app/agent-config/commit/4c6c1eb1e00356421e0038704a82e1f10ac9a3e5))
+
+## [1.22.0](https://github.com/event4u-app/agent-config/compare/1.21.0...1.22.0) (2026-05-07)
+
+### Features
+
+* **commands:** add /grill-me alias for /challenge-me + expand triggers ([d2be4ee](https://github.com/event4u-app/agent-config/commit/d2be4ee1a97d2ca2374c6543e0fd908eca0a0f1a))
+* **challenge-me:** add !roadmap and !ai triggers ([7bfbd69](https://github.com/event4u-app/agent-config/commit/7bfbd6943852d781ca7ad29e51750de24d3ef413))
+* **create-pr:** default to skipping description preview to save tokens ([80e77ae](https://github.com/event4u-app/agent-config/commit/80e77aed76a13c26fac8316bc5d58a3533dbbe44))
+* **council:** add critical-evaluation stance for council findings ([7e2524b](https://github.com/event4u-app/agent-config/commit/7e2524b75fd84ca4b6afb6deae0b8777e8b81ac7))
+* **council:** add /roadmap:ai-council deep-tier sub-command ([c5933e4](https://github.com/event4u-app/agent-config/commit/c5933e4b2301a0f9d1c116d2843ed4953bd92163))
+* replace /roadmap-execute with autonomous /roadmap:process-* cluster ([9d4ffd0](https://github.com/event4u-app/agent-config/commit/9d4ffd0815fb7923b337bfd0b3847d9bc5a01e54))
+* **council:** mark architecture/refactor/bug-diagnose artefacts as deep ([6f903c1](https://github.com/event4u-app/agent-config/commit/6f903c194e4bc54512e93a32e1876e84d0292401))
+* **council:** add deep reasoning depth tier with schema enforcement ([f4efd7a](https://github.com/event4u-app/agent-config/commit/f4efd7a11b9d57e93153e6e4605c968565c8924d))
+* **linter:** require suggestion block on commands ([231df91](https://github.com/event4u-app/agent-config/commit/231df918b2d15ea9cc2fa8fe12bae4c2482990df))
+* add --siblings council mode and refine convener wording ([9075647](https://github.com/event4u-app/agent-config/commit/9075647ba520efb5f10ab7612970111e9f9d16e9))
+* add PRD template to technical-specification ([f9ee749](https://github.com/event4u-app/agent-config/commit/f9ee7496434f9342d6b46b95dce14c4703d07d96))
+* add 6-phase loop checklist to systematic-debugging ([29c9e94](https://github.com/event4u-app/agent-config/commit/29c9e9419c9d08dd93c4fc7364e51b93bc771131))
+* add invite-challenge rule for pre-execution goal restatement ([e96da5f](https://github.com/event4u-app/agent-config/commit/e96da5fdf124da3582e454fc625fe32a27ada634))
+* add /challenge-me cluster with vision and with-docs sub-commands ([74481ef](https://github.com/event4u-app/agent-config/commit/74481ef7e7850d3e015ff0f9853be6ea618ac1d9))
+
+### Documentation
+
+* **roadmap:** drop council-response file links per no-council-references ([d792100](https://github.com/event4u-app/agent-config/commit/d792100ef6b2727cca1338c89fefc4c591513265))
+* **readme:** bump hero command count from 100 to 102 ([3212db4](https://github.com/event4u-app/agent-config/commit/3212db48fb1d62a70f9e87cf9307ee73059b7e4e))
+* **roadmap:** integrate R5 council verdict for caveman-insurance ([38b26e2](https://github.com/event4u-app/agent-config/commit/38b26e2f00504a7c6c821c356964cb0cabefd905))
+* **roadmap:** incorporate R4 verdict + structural findings into caveman integration ([c50f39b](https://github.com/event4u-app/agent-config/commit/c50f39bc9b08c8d59c4cf547aeec7fffbff38bc0))
+* **roadmap:** convert caveman integration Phase 2 to hard cutover ([fb459be](https://github.com/event4u-app/agent-config/commit/fb459be70a093eea1814a38a3b1fec9cf9261363))
+* **harvest:** add Superpowers harvest roadmap, hardened by council R2 ([e559259](https://github.com/event4u-app/agent-config/commit/e559259f789014603067e87141d9feb815b480ab))
+* **harvest:** analyze obra/superpowers v5.1.0 for adoption candidates ([e89e0ee](https://github.com/event4u-app/agent-config/commit/e89e0eeadc4b76517b181c559422e88df5c8122a))
+* **council:** document council_depth frontmatter convention in templates ([ba56412](https://github.com/event4u-app/agent-config/commit/ba56412c76204bbe49366bbceb62e4d31c994fc2))
+
+### Chores
+
+* **sync:** re-sync compressed mirror with create-pr preview-gate + agent-settings preview_description ([ceab79e](https://github.com/event4u-app/agent-config/commit/ceab79e23be2c1d4ba504b80426d1b91ffdaadd1))
+* bump artefact counts and refresh compression hashes ([2801342](https://github.com/event4u-app/agent-config/commit/28013424668177fc23df45cc56390faba6fd010e))
+* regenerate tool-dir symlinks for challenge-me and invite-challenge ([b3b0ada](https://github.com/event4u-app/agent-config/commit/b3b0ada9ce108b220289c9f044b3f3d0209f0a12))
+* bump artefact counts and refresh compression hashes ([4147de3](https://github.com/event4u-app/agent-config/commit/4147de3b4da24494128a847be194ac901e506df9))
+* sync compressed projection for challenge-me cluster ([9165762](https://github.com/event4u-app/agent-config/commit/91657620e6d822fbe28923e3b008e218f13e5cea))
+
 ## [1.21.0](https://github.com/event4u-app/agent-config/compare/1.20.0...1.21.0) (2026-05-06)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ 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>136 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>56 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>140 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>58 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -343,7 +343,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/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 95 active commands](.agent-src/commands/)
+→ [Browse all 103 active commands](.agent-src/commands/)
 
 ---
 
@@ -368,7 +368,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 + 136 skills + 95 native commands). Cursor, Cline, Windsurf,
+> package (rules + 140 skills + 103 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.
@@ -413,6 +413,8 @@ for the per-rule routing.
 - **Challenge to improve** — agents are thought partners, not yes-machines
 - **Strict by design** — quality over flexibility
 - **Zero overhead by default** — nothing runs until you ask for it
+- **Terse-by-default chat output** — verbosity flags off, intent narration off,
+  caveman-speak prose-only — flip back via [`docs/customization.md` § Verbosity](docs/customization.md#verbosity)
 
 ---
 
@@ -480,10 +482,8 @@ re-enabled or the chat ends. Full scoring contract and hardening:
 Edit in `.agent-src.uncompressed/`, compress, verify:
 
 ```bash
-task sync          # Sync non-.md files
 task ci            # Run all CI checks
 task test          # Run all tests
-task lint-skills   # Lint skills, rules, commands
 ```
 
 → Full commands and project structure: [**docs/development.md**](docs/development.md)

package/config/agent-settings.template.yml

@@ -238,6 +238,16 @@ ai_council:
   # invocation (or `--rounds N` to the CLI) to override.
   min_rounds: 2
 
+  # Higher floor for deep-reasoning artefacts (architecture review,
+  # refactoring proposals, bug-diagnosis runs). Activated when the
+  # consuming rule, skill, or command declares `council_depth: deep`
+  # in its frontmatter, or the user passes `--depth deep` to the CLI.
+  # Effective rounds = max(deep_min_rounds, min_rounds), so this floor
+  # is monotonic — lowering it below `min_rounds` has no effect.
+  # Standard tasks keep `min_rounds`; cost rises only when an artefact
+  # opts in. Set to `min_rounds` to disable the deep tier.
+  deep_min_rounds: 3
+
   # Hard cost ceiling per /council invocation. The orchestrator pauses
   # before any member whose projected spend would breach a cap and asks
   # the user to continue. `max_total_usd: 0` disables the USD ceiling
@@ -298,3 +308,15 @@ commands:
     # Commands to never suggest. Still work when typed explicitly.
     # Example: ["/refine-ticket", "/work"]
     blocklist: []
+
+  # --- /create-pr behavior ---
+  #
+  # Pre-creation preview of the generated PR description.
+  # false (default): skip the title/body preview + adjust loop in
+  # /create-pr; use the generated content directly. Saves agent tokens
+  # by avoiding a re-render of the full description in chat.
+  # true: show title and body in copyable code blocks and ask for
+  # adjustments before creating the PR.
+  # /create-pr:description-only always previews — that is its sole purpose.
+  create_pr:
+    preview_description: false

package/docs/architecture.md

@@ -96,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 136 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **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** | 56 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Skills** | 140 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 58 | 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/contracts/command-clusters.md

@@ -33,7 +33,7 @@ column 1 of this table.
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
-| `roadmap` | 2 | `create` · `execute` | `roadmap-create` · `roadmap-execute` |
+| `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
 | `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
@@ -43,6 +43,7 @@ column 1 of this table.
 | `commit` | 2 | `in-chunks` | `commit-in-chunks` |
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
 | `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
+| `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use
@@ -51,6 +52,49 @@ autocomplete them. The standalone `/review` surface that mirrors
 `judge solo` lives at
 [`commands/review-changes.md`](../../.agent-src.uncompressed/commands/review-changes.md).
 
+## Cluster depth and sub-command naming
+
+Locked by [ADR-003](../decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md)
+(2026-05-07). The shape is the default for **every** new cluster and
+every new sub-command added to an existing cluster.
+
+1. **Flat only.** A cluster has exactly one level of sub-commands.
+   No sub-sub-commands. A dispatcher routes `/cluster <sub>` to a
+   single sub-file; sub-files do not dispatch further. Two-level
+   dispatch is a deliberate contract change requiring a new ADR
+   superseding ADR-003.
+
+2. **Composite sub-names for verb+scope.** When a cluster carries
+   multiple verbs (e.g. authoring + execution), encode the verb in
+   the sub-name, joined with `-`:
+
+   - ✅ `/roadmap:create` · `/roadmap:process-step` ·
+     `/roadmap:process-phase` · `/roadmap:process-full`
+   - ❌ `/roadmap:process:phase` (sub-sub — forbidden)
+   - ❌ `/roadmap:step` · `/roadmap:phase` · `/roadmap:full`
+     (verb hidden — breaks symmetry with `create`)
+   - ❌ separate `/roadmap-process` cluster (domain split — forbidden
+     when one cluster can carry both verbs flat)
+
+   Sibling sub-names stay in the same shape: either all bare verbs,
+   all bare nouns/scopes, or all composite. Mixing bare and composite
+   in the same cluster is allowed only when the bare sibling is the
+   cluster's primary verb (e.g. `/roadmap:create` + `process-*`
+   composites).
+
+3. **Sub-name format.** kebab-case (`pr-bots`, `process-phase`),
+   ≤ 24 chars, no leading verb that duplicates the cluster name
+   (use `/fix:ci`, not `/fix:fix-ci`).
+
+4. **Colon-canonical invocation.**
+   `/<cluster>:<sub>` is the canonical form everywhere — catalog,
+   docs, examples, deprecation warnings. The space-separated form
+   `/<cluster> <sub>` is a first-class equivalent and routes to the
+   same dispatcher; it must keep working. Autocompletion-aware UIs
+   surface the colon form because it stays a single token. Full
+   semantics: [`slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+   § Routing semantics.
+
 ## Frontmatter contract
 
 A new command file under `.agent-src.uncompressed/commands/` MUST

package/docs/customization.md

@@ -120,6 +120,78 @@ behavior — the per-profile table is just the initial default.
 
 `custom` ignores these defaults — set every value explicitly.
 
+### Verbosity
+
+The `verbosity:` block and `caveman.speak_scope` control how much narration
+the agent emits around routine actions. Defaults are tuned for token
+frugality — flip values to `true` (or higher tier) to restore legacy verbose
+output. Iron-Law gates (`commit-policy`, `scope-control` git-ops,
+`non-destructive-by-default`) ALWAYS confirm regardless of these flags.
+
+| Setting | Values | Default | Description |
+|---|---|---|---|
+| `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, and branch names before acting. `false` = use the generated content directly. |
+| `verbosity.routine_confirmations` | `true`, `false` | `false` | Confirmation prompts for routine workflow steps when there is one obvious answer ("looks good — commit?"). Iron-Law gates always ask regardless. |
+| `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). The `/council` command itself is unaffected. |
+| `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |
+| `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
+| `verbosity.script_output` | `silent`, `minimal`, `verbose` | `minimal` | Stdout chatter from `scripts/*.py`, `scripts/*.sh`, and `.augment/scripts/`. `silent` = stderr only; `minimal` = one summary line per script; `verbose` = pre-Phase-10 per-step prints. Iron-Law surfaces (release confirms, install secrets prompts, error markers) ignore this key. |
+| `verbosity.taskfile_command_echo` | `true`, `false` | `false` | Suppress the `task: [name] cmd...` echo Taskfile prints before each task body. `true` = echoes preserved (legacy behaviour); `false` = `silent: true` is set on every Phase-10 safe task. |
+| `caveman.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely caveman-speak grammar applies in chat. `off` = no caveman; `prose_only` = caveman in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = caveman everywhere except Iron-Law literals. |
+
+The cross-rule index for these defaults lives in
+[`.agent-src.uncompressed/contexts/contracts/frugality-charter.md`](../.agent-src.uncompressed/contexts/contracts/frugality-charter.md).
+Writer skills (`skill-writing`, `rule-writing`, `command-writing`,
+`guideline-writing`, `roadmap-writing`, `persona-writing`,
+`agent-docs-writing`, `context-authoring`, `conventional-commits-writing`,
+`readme-writing`, `readme-writing-package`, `adr-create`) cite the charter
+under their `## Frugality Standards` section.
+
+#### Behavior change vs. legacy — `/create-pr` silent draft default
+
+When `verbosity.routine_confirmations: false` (the new default),
+`/create-pr` creates the PR as a **draft silently** instead of asking
+"draft or ready?". A one-line postscript surfaces the override:
+
+```
+→ #42 opened: https://github.com/org/repo/pull/42
+→ created as draft — run `gh pr ready 42` to flip
+```
+
+Per-invocation overrides (no settings change required):
+
+| You want | Argument |
+|---|---|
+| Ready-for-review immediately | `/create-pr:ready` or `/create-pr:final` |
+| Explicit draft (no postscript change) | `/create-pr:draft` |
+| Numbered prompt restored | set `verbosity.routine_confirmations: true` |
+
+`/create-pr` still skips the AI council prompt unconditionally per the
+existing carve-out — `verbosity.offer_council_in_delivery` does not
+re-enable it. Use `/council diff:<base>..<head>` separately.
+
+#### Script-output level — env-var overrides
+
+`verbosity.script_output` is read by `scripts/_lib/script_output.py`.
+For incident debugging when editing `.agent-settings.yml` is awkward,
+two env vars override the file for the current process tree:
+
+| Env var | Value | Effect |
+|---|---|---|
+| `AGENT_SCRIPT_VERBOSITY` | `silent`, `minimal`, `verbose` | Authoritative — wins over the settings file |
+| `SCRIPT_OUTPUT_VERBOSE` | `1` | Alias — equivalent to `AGENT_SCRIPT_VERBOSITY=verbose` |
+
+Once the helper resolves the level, it exports the resolved value back
+into `AGENT_SCRIPT_VERBOSITY` so child processes inherit the same level
+without re-reading the settings file. Per-call `--quiet` flags on a
+child script still win at the call site (per-call override > inherited
+level).
+
+Iron-Law surfaces — production-deploy confirmation prompts in
+`scripts/release.py`, secret-installer prompts in `install_*_key.sh`,
+and any output via `error()` — bypass the helper and stay loud at every
+level.
+
 ---
 
 ## Project documentation

package/docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md

@@ -0,0 +1,126 @@
+# ADR-003 — Flat Cluster Sub-Commands and Colon-Canonical Invocation
+
+- **Status:** Accepted (2026-05-07)
+- **Phase:** Command-cluster contract (Phase 2 follow-up)
+- **Supersedes:** none — extends the locked cluster set in
+  `docs/contracts/command-clusters.md`.
+- **Related:** `roadmap-process` migration (2026-05-07) — the trigger
+  that forced the decision; `contexts/execution/roadmap-process-loop.md`
+  (the shared mechanics extracted alongside).
+
+## Context
+
+`roadmap-execute` was being replaced by an autonomous-execution surface
+with three scopes: single step, single phase, full roadmap. The
+question was where those three commands live in the cluster catalog.
+Four shapes were on the table:
+
+- **A — separate `/roadmap-process` cluster.** Two top-level clusters
+  (`/roadmap` for authoring, `/roadmap-process` for execution).
+- **B — sub-sub-commands** (`/roadmap:process:phase`). One cluster,
+  two-level dispatch.
+- **C — flat under `/roadmap`, no verb** (`/roadmap:step` ·
+  `/roadmap:phase` · `/roadmap:full`). Verb hidden in cluster
+  description.
+- **D — flat under `/roadmap`, verb fused with scope**
+  (`/roadmap:process-step` · `/roadmap:process-phase` ·
+  `/roadmap:process-full`). One cluster, one dispatch level, composite
+  sub-name carries the verb.
+
+Existing infrastructure assumed a single dispatch level: the contract
+table at `docs/contracts/command-clusters.md`, the linter
+`scripts/lint_no_new_atomic_commands.py`, and the dispatcher-shape
+checker `scripts/check_cluster_patterns.py` all parse one column of
+sub-names per cluster.
+
+## Decision
+
+1. **Cluster depth stays flat.** A cluster has exactly one level of
+   sub-commands. No sub-sub-commands. Option B is rejected.
+
+2. **Verb-and-scope sub-commands use a composite name** joined by `-`
+   (`process-step`, `process-phase`, `process-full`). The verb stays
+   visible in the autocomplete list; symmetry with sibling
+   sub-commands (`/roadmap:create`) is preserved as
+   verb-or-noun-per-sub. Option D wins over C.
+
+3. **Colon is the canonical invocation form** (`/<cluster>:<sub>`).
+   The space-separated form (`/<cluster> <sub>`) remains a
+   first-class equivalent — both forms route to the same dispatcher.
+   Autocompletion-aware UIs (Claude Code picker, IDE slash-menus,
+   shell completers) MUST surface the colon form because it stays a
+   single token.
+
+4. **Future verb+scope clusters follow the same shape.** Any future
+   cluster with multiple verbs (e.g. an authoring verb and an
+   execution verb) uses composite sub-names rather than introducing a
+   second cluster or a second dispatch level.
+
+## Rationale
+
+- **Option A (separate cluster)** scatters one domain across two
+  top-level surfaces. Users have to remember which cluster owns
+  which verb; the catalog grows without adding capability.
+- **Option B (sub-sub)** would be the first two-level dispatcher in
+  the repo. Cost: contract change in `command-clusters.md`,
+  linter change in `lint_no_new_atomic_commands.py` (parse a second
+  column), pattern-checker change in `check_cluster_patterns.py`
+  (allow nested dispatch sections), plus an ADR to set the precedent
+  — for a cohesion benefit that Option D delivers at zero
+  architectural cost.
+- **Option C (no verb)** breaks symmetry: `/roadmap:create` is a
+  verb, `/roadmap:phase` is a scope. The mental model becomes
+  inconsistent in the same cluster.
+- **Option D (composite verb-scope)** keeps the cluster flat, keeps
+  the verb visible, costs nothing in the linter or contract
+  parser (one row, four sub-names, kebab-case as before), and
+  scales to any future verb+scope cluster.
+
+The colon form was already canonical for flag-clusters
+(`/commit:in-chunks`, `/create-pr:description-only`). Promoting it
+to the canonical form for dispatcher-clusters too unifies the
+catalog: every sub-command is a single token.
+
+## Consequences
+
+- **Pro:** Zero architectural cost. The locked contract, both
+  linters, the dispatcher pattern checker, and the routing rule all
+  keep working unchanged. The cluster row in
+  `docs/contracts/command-clusters.md` extends with three new
+  sub-names.
+- **Pro:** Single-token autocompletion across the entire command
+  surface. Greppable in chat history and logs.
+- **Pro:** Domain cohesion — `/roadmap:*` covers the full
+  authoring + execution lifecycle.
+- **Con:** Sub-names get longer when the verb is non-obvious from the
+  cluster. `/roadmap:process-phase` is 24 chars vs.
+  `/roadmap-process:phase` (Option A, 23 chars) or
+  `/roadmap:phase` (Option C, 16 chars). Acceptable trade for
+  symmetry and zero contract churn.
+- **Con:** A cluster cannot grow into a true two-level surface
+  without revisiting this ADR. Rolling back to Option B is the
+  escape hatch if a future cluster genuinely needs nested verbs.
+
+## Rollback
+
+If a future cluster grows past ~8 sibling sub-commands and the
+composite-name pattern produces ambiguous or unreadable
+sub-commands, revisit by:
+
+1. Splitting the cluster into two flat clusters (Option A on a
+   case-by-case basis), or
+2. Introducing sub-sub-commands as a deliberate contract change —
+   updating `command-clusters.md`, `lint_no_new_atomic_commands.py`,
+   `check_cluster_patterns.py`, and superseding this ADR.
+
+Both moves are reversible. This ADR locks the default, not the
+ceiling.
+
+## See also
+
+- [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md)
+  — locked cluster set + sub-command naming contract.
+- [`.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+  — runtime routing semantics and the colon-canonical rule.
+- [`.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md)
+  — the shared mechanics that motivated the cluster shape.

package/docs/decisions/INDEX.md

@@ -0,0 +1,15 @@
+# ADR Index
+
+_Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [ADR-001](ADR-001-kernel-swap-deferred.md) | Kernel Swap Deferred | accepted | 2026-05-06 | — |
+| [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | — | — | — |
+| [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | — | — | — |
+
+## Unnumbered (legacy)
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [ADR-rule-kernel-and-router](ADR-rule-kernel-and-router.md) | — | — | — | — |

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 58 rules. No configuration needed.
+This is enforced automatically by 60 rules. No configuration needed.
 
 ---
 
@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 95 active commands](../.agent-src/commands/)
+→ [Browse all 103 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/asking-and-brevity-examples.md

@@ -12,21 +12,22 @@ always-loaded rule body — extracted to fit the always-rule budget.
 
 ## Vague-request triggers — example questions
 
-Companion to `ask-when-uncertain` § Vague-request triggers. The rule
-lists the trigger patterns and the "missing info" columns; this file
-adds the example question to ask back at the user.
+Companion to `ask-when-uncertain` § Vague-request triggers. This
+section is the canonical home for the nine trigger patterns, the
+missing-info each one hides, and the example clarifying question —
+the rule cites it instead of restating the catalog.
 
-| Pattern | Example clarifying question |
-|---|---|
-| "improve / optimize this" | "Optimize for what — execution speed or readability?" |
-| "add caching" | "Which cache driver, and what invalidates it?" |
-| "make it better / cleaner" | "What specifically feels wrong in the current code?" |
-| "clean up this file" | "Remove unused code, reformat, or restructure?" |
-| "fix this" (without specifying) | "What output/behavior is wrong right now?" |
-| "refactor X" | "Refactor toward what — smaller methods, extract class, or something else?" |
-| "use best practices" | "Best practices for what specifically — testing, naming, structure?" |
-| "handle errors properly" | "For which failure modes, and what should happen on error?" |
-| "add a UI / component / tile / page" when the repo mixes frameworks | "This repo uses {A} and {B} for UI — which one for this?" |
+| Pattern | Missing info | Example clarifying question |
+|---|---|---|
+| "improve / optimize this" | metric — speed, readability, memory? | "Optimize for what — execution speed or readability?" |
+| "add caching" | store, scope, invalidation | "Which cache driver, and what invalidates it?" |
+| "make it better / cleaner" | by what standard? | "What specifically feels wrong in the current code?" |
+| "clean up this file" | dead code, format, refactor? | "Remove unused code, reformat, or restructure?" |
+| "fix this" (no symptom) | what output is wrong? | "What output/behavior is wrong right now?" |
+| "refactor X" | target pattern, boundaries | "Refactor toward what — smaller methods, extract class, or something else?" |
+| "use best practices" | whose, for what? | "Best practices for what specifically — testing, naming, structure?" |
+| "handle errors properly" | which errors — log/retry/propagate? | "For which failure modes, and what should happen on error?" |
+| "add a UI / component / tile / page" in mixed-framework repo | which stack? | "This repo uses {A} and {B} for UI — which one for this?" |
 
 ## One-question-per-turn — why serial always wins
 
@@ -49,8 +50,10 @@ next. Serial preserves the framing; parallel destroys it.
 
 ## Cheap-question class catalog — extended examples
 
-Companion to `no-cheap-questions` § What counts as cheap. The rule
-lists the classes; this file adds longer-form examples per class.
+Companion to `no-cheap-questions` § What counts as cheap. This
+section is the canonical home for the nine cheap-question classes
+and their per-class patterns — the rule cites it instead of
+restating the catalog.
 
 | Class | Pattern · why cheap | Concrete example |
 |---|---|---|
@@ -66,9 +69,10 @@ lists the classes; this file adds longer-form examples per class.
 
 ## Direct-answers — severity-tiered claim examples
 
-Companion to `direct-answers` § Iron Law 2 (no invented facts). The
-rule lists the severity table; this file adds concrete examples and
-hedge-language patterns.
+Companion to `direct-answers` § Iron Law 2 (no invented facts). This
+section is the canonical home for the severity tiers, per-tier
+verification actions, and the override carve-out — the rule cites it
+instead of restating the table.
 
 | Severity | Examples | Verification action |
 |---|---|---|
@@ -76,6 +80,10 @@ hedge-language patterns.
 | **Medium — project-shape** | "This project uses Pest for testing", "controllers live under `app/Http/Controllers`" | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
 | **Low — well-known idioms** | "PHP `array_map` returns a new array", "git tags are immutable", "JS arrays are zero-indexed" | Inference acceptable. Mark as inference if not 100% sure. |
 
+**Override:** "just guess" / "rough estimate" / "skip verify" in the
+user's turn drops every claim to **Low** for that turn only. Reverts
+on the next turn unless the user repeats the override.
+
 Hedge-language patterns:
 
 - ✅ "haven't verified X — likely from {known-similar-codebase}"

package/docs/guidelines/agent-infra/carve-out-predicates.md

@@ -0,0 +1,17 @@
+# Decidable Carve-Out Predicates
+
+Companion to [`frugality-charter`](../../../.agent-src.uncompressed/contexts/contracts/frugality-charter.md). Each carve-out below carries a one-sentence test. If the test cannot be answered yes/no from the artifact alone, the carve-out does not fire and default-terse rules apply.
+
+## Predicates
+
+- **Iron-Law literal** — the prose is an ALL-CAPS fenced block inside a rule whose title appears in [`docs/contracts/kernel-membership.md`](../../contracts/kernel-membership.md).
+
+- **Numbered-options with genuine trade-off** — the options differ in consequence (a chosen path produces a measurably different artifact or state), not in sequencing or output format. Per [`no-cheap-questions § What counts as cheap`](../../../.agent-src.uncompressed/rules/no-cheap-questions.md#what-counts-as-cheap).
+
+- **Security-sensitive prompt** — the prompt requires credential input OR modifies auth / tenant / secret state, matching a trigger in [`security-sensitive-stop`](../../../.agent-src.uncompressed/rules/security-sensitive-stop.md).
+
+- **Structured CLI contract** — the script's stdout is consumed by another script (a downstream parser exists under `scripts/` or `.augment/scripts/`), so the format is part of an interface contract, not narration.
+
+## How to use
+
+Writer skills (`skill-writing`, `rule-writing`, `command-writing`, `guideline-writing`, `context-authoring`, `agent-docs-writing`, `conventional-commits-writing`, `readme-writing`, `readme-writing-package`, `adr-create`, `persona-writing`, `roadmap-writing`) cite this file when an artifact's pre-save check needs a decidable test for a carve-out exception. The default is **terse** — predicates here only fire when the artifact provides the yes/no evidence.