@event4u/agent-config 1.21.0 → 1.22.0

package/.agent-src/commands/roadmap/ai-council.md

@@ -0,0 +1,183 @@
+---
+name: roadmap:ai-council
+cluster: roadmap
+sub: ai-council
+skills: [ai-council, agent-docs-writing, roadmap-management]
+description: Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council default` pinned to `--input-mode roadmap --depth deep`; patches surface as numbered options.
+disable-model-invocation: true
+council_depth: deep
+suggestion:
+  eligible: true
+  trigger_description: "council on roadmap, challenge this roadmap, stress-test the plan, refactor roadmap from council findings"
+  trigger_context: "existing agents/roadmaps/*.md the user wants reviewed before execution"
+---
+
+# /roadmap:ai-council
+
+Council-driven challenge + refactor scope of the
+[`/roadmap`](../roadmap.md) cluster. Pins the input mode to
+`roadmap` and the depth tier to `deep` (architecture / refactor
+artefact), then drives the user through applying convergence
+findings as numbered patches against the roadmap file.
+
+**Source of truth:** `.agent-src.uncompressed/` — never read or edit
+`.agent-src/` or `.augment/` directly.
+
+## Instructions
+
+### 1. Resolve the target roadmap
+
+Parse the argument as a roadmap path or filename:
+
+- `/roadmap:ai-council agents/roadmaps/<name>.md` — explicit path.
+- `/roadmap:ai-council <name>` — fuzzy match against
+  `agents/roadmaps/*.md`; if multiple match, list and ask
+  (one question per turn per `ask-when-uncertain`).
+- No argument → list `agents/roadmaps/*.md` and ask.
+
+Capture the **original ask** verbatim — the user's framing sentence
+that triggered this council run (e.g. *"review this roadmap before
+I execute it"*). This flows into `--original-ask`.
+
+### 2. Run the `/council default` flow with these pinned flags
+
+Follow [`/council default`](../council/default.md) Steps 2–4
+**verbatim**, with these arguments fixed:
+
+- `--input-mode roadmap`
+- `--depth deep` (this command declares `council_depth: deep` in
+  frontmatter; the host translates it into `--depth deep`)
+- `--output agents/council-responses/<roadmap-stem>-roadmap.json`
+  (overwrite if it exists; the previous run is the predecessor for
+  this iteration)
+- `--original-ask "<captured-ask>"`
+
+`--depth deep` floors rounds at
+`max(ai_council.deep_min_rounds, ai_council.min_rounds)` (default
+`3`). Do **not** pass `--rounds` unless the user explicitly asked
+for a different count.
+
+The cost gate from `/council default` Step 3 still applies — billable
+members require user confirmation **even under `personal.autonomy: on`**
+(per the deep tier surcharge — typical cost ~$0.05–0.13 vs. ~$0.02
+for the standard tier).
+
+### 3. Render the report
+
+Run `./agent-config council:render <output.json>` and write the
+**Convergence / Divergence** section per
+[`/council default § Render`](../council/default.md). Do **not** end
+with `/council default`'s generic numbered-options block — the
+refactor flow in Step 4 replaces it.
+
+### 4. Append a Council review block to the roadmap
+
+Open the roadmap file and append (do **not** overwrite existing
+content):
+
+```markdown
+
+## Council review (<UTC date>)
+
+<Convergence section verbatim>
+
+### Convergence findings
+
+1. **<Finding 1 title>** — <one-line summary> · trace: §<member-section>
+2. **<Finding 2 title>** — <one-line summary> · trace: §<member-section>
+…
+
+### Divergences (no consensus)
+
+- **<Topic>** — <Member A says X, Member B says Y; user decides>
+
+### Predecessor council trace
+
+`agents/council-responses/<roadmap-stem>-roadmap.json` (this run).
+```
+
+Run `./agent-config roadmap:progress` after the append. The block
+adds no `[ ]` checkboxes, so the dashboard counts stay flat.
+
+### 5. Apply the critical-evaluation lens, then surface verdicted patches
+
+Before drafting any patch, run every finding from Step 4 through the
+*Critical evaluation* checklist from the
+[`ai-council` skill](../../skills/ai-council/SKILL.md#critical-evaluation--convener-skeptic-stance):
+
+- **Codebase fit** — does the finding match the actual roadmap content, file paths, scripts, contracts cited in the roadmap? (`view` / `codebase-retrieval`)
+- **Locked-decision conflict** — does it contradict an ADR (`docs/decisions/`), a contract (`docs/contracts/`), a kernel rule, or an earlier locked decision in **this** roadmap?
+- **Already addressed** — is the finding already covered by an existing step, AC, or phase in the roadmap?
+- **Cost / benefit** — does the patch's scope vs. roadmap value clear the bar?
+- **Hallucination** — does the finding cite a file, function, phase, or step that does not exist?
+
+For every finding, attach a verdict — **`accept`**, **`accept-with-modification`**, **`reject`**, or **`needs-input`** — with a one-line reason citing host evidence (file:line, ADR, contract, roadmap step).
+
+Append a **Host verdict** sub-block under the Council review block in the roadmap:
+
+```markdown
+### Host verdict
+
+| # | Finding | Verdict | Reason |
+|---|---|---|---|
+| 1 | <one-line> | `accept` | matches `agents/roadmaps/<this>.md` Phase X step Y |
+| 2 | <one-line> | `accept-with-modification` | narrow scope to phase Z — global change contradicts AC §N |
+| 3 | <one-line> | `reject` | contradicts ADR `docs/decisions/<adr>.md` |
+| 4 | <one-line> | `needs-input` | open question — user picks below |
+```
+
+Then surface a single numbered-options block per [`user-interaction`](../../rules/user-interaction.md), carrying the verdict per option:
+
+> 1. `[accept]` Apply finding 1 — <one-line patch summary>
+> 2. `[accept-with-modification]` Apply finding 2 (modified) — <one-line patch summary + adjustment>
+> 3. `[reject]` Skip finding 3 — <one-line reason> (override available below)
+> 4. `[needs-input]` <open question for finding 4>
+> …
+> N. Apply all `accept` findings (recommended only if non-conflicting)
+> N+1. Override host verdict — apply a finding the host rejected (specify number)
+> N+2. Skip — leave Council review block + Host verdict as advisory only
+
+The user picks one or more numbers (`1,3,5` is allowed). Apply each selected patch via `str-replace-editor` against the roadmap, then re-run `./agent-config roadmap:progress` once at the end so the dashboard reflects the new step / AC count.
+
+**Verdict ≠ filter.** Every finding stays visible in the Host verdict block with its verdict and reason — the user can override at any time. The host filters its **own** recommendation; it does not hide council output.
+
+### 6. Hard floor — text + roadmap edits only
+
+`/roadmap:ai-council` may:
+
+- write `agents/council-responses/<…>.json`
+- append the Council review block to the named roadmap
+- apply user-picked patches to the same roadmap
+- regenerate `agents/roadmaps-progress.md`
+
+It does **NOT**:
+
+- edit any other roadmap, command, rule, or skill file
+- commit, push, or open a PR
+- run `git` beyond `git diff` (read-only)
+
+## Rules
+
+- **One roadmap per invocation.** Re-run for the next file.
+- **Critical evaluation is mandatory** — every council finding gets
+  a host verdict (`accept` / `accept-with-modification` / `reject` /
+  `needs-input`) with one-line evidence before any patch is drafted.
+  Convergence ≠ correctness; the council never saw the codebase. See
+  [`ai-council § Critical evaluation`](../../skills/ai-council/SKILL.md#critical-evaluation--convener-skeptic-stance).
+- **Decline = silence** ([`scope-control`](../../rules/scope-control.md)) —
+  if the user picks "Skip — advisory only", the Council review block
+  + Host verdict stay in the roadmap, but no patches are applied. Do
+  not re-ask the question on the same task.
+- **Cost gate is non-negotiable** — the deep tier costs more than
+  standard; confirm before every billable run, even with
+  `personal.autonomy: on`.
+- **No commit.** Patches land in the working tree only; commit
+  decisions stay with the user per
+  [`commit-policy`](../../rules/commit-policy.md).
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/council default`](../council/default.md) — base flow this command wraps
+- [`ai-council`](../../skills/ai-council/SKILL.md) — neutrality, redaction, deep tier
+- [`scripts/council_cli.py`](../../../scripts/council_cli.py) — CLI entry point

package/.agent-src/commands/roadmap/create.md

@@ -168,7 +168,12 @@ If the user picks **2** → continue.
 
 After saving (and any council review), ask the user (in their language) whether to start executing the roadmap immediately.
 
-If yes → switch to the `roadmap-execute` command workflow with the newly created file.
+If yes → switch to [`/roadmap:process-phase`](process-phase.md) with
+the newly created file (the default execution scope of the `/roadmap`
+cluster). Offer [`process-step`](process-step.md) and
+[`process-full`](process-full.md) as alternatives. The legacy
+`/roadmap execute` command was removed — autonomous execution is the
+only path now.
 
 ### Rules
 

package/.agent-src/commands/roadmap/process-full.md

@@ -0,0 +1,58 @@
+---
+name: roadmap:process-full
+cluster: roadmap
+sub: process-full
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "process the whole roadmap, finish the roadmap, komplette roadmap abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants the entire file done end-to-end"
+---
+
+# /roadmap:process-full
+
+Whole-roadmap execution scope of the [`/roadmap`](../roadmap.md)
+cluster. Same canonical loop as
+[`/roadmap:process-phase`](process-phase.md), but does **not** stop at
+phase boundaries — continues until every step is closed (or a halt
+condition fires).
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**.
+
+## Scope delta
+
+- **Working set:** every open step across every phase, in document
+  order.
+- **Stop after:** the entire roadmap reaches `count_open == 0`, or a
+  halt condition fires (Hard-Floor, council-off + ambiguity,
+  security-sensitive, scope-out-of-roadmap, test/quality red).
+- **Phase boundary handling:** at every phase boundary, run the
+  per-phase quality pipeline when `quality_cadence: per_phase` (or
+  `per_step`). On red → stop, surface, do **not** silently roll into
+  the next phase.
+- **Final archival:** when the roadmap is fully closed, run the
+  archival check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+
+## Rules
+
+- **No silent acceleration past a halt.** Every halt condition stops
+  the run; the user resumes on the next turn.
+- **Phase quality pipeline runs at every phase boundary** when cadence
+  is `per_phase` or `per_step`. `end_of_roadmap` skips per-phase and
+  runs only at the final archival check.
+- All other rules from
+  [`process-phase § Rules`](process-phase.md#rules) apply unchanged.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-step`](process-step.md) — single-step variant
+- [`/roadmap:process-phase`](process-phase.md) — default scope, single phase
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics

package/.agent-src/commands/roadmap/process-phase.md

@@ -0,0 +1,69 @@
+---
+name: roadmap:process-phase
+cluster: roadmap
+sub: process-phase
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "process the next phase, finish this phase autonomously, eine phase abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants the next phase done end-to-end"
+---
+
+# /roadmap:process-phase
+
+Default execution scope of the [`/roadmap`](../roadmap.md) cluster.
+Sibling of [`/roadmap:process-step`](process-step.md) and
+[`/roadmap:process-full`](process-full.md). Replaces the legacy
+`/roadmap execute` (which paused for confirmation before every step).
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**. The loop file owns roadmap discovery,
+pre-run summary, cadence resolution, commit-step pre-scan, the step
+loop with AI-council branching, halt conditions, and the archival
+check.
+
+## Scope delta
+
+- **Working set:** all open steps in the **first phase with
+  `count_open > 0`**. If every phase is closed → report "Roadmap
+  already complete." and run the archival check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+- **Stop after:** the phase boundary. Do **not** advance into the next
+  phase. Use [`/roadmap:process-full`](process-full.md) for continuous
+  execution across phases.
+- **Quality cadence at the boundary:** run the per-phase pipeline when
+  `quality_cadence: per_phase` (or `per_step`). Skip when
+  `end_of_roadmap`.
+
+## Rules
+
+- **Autonomous within the phase, never beyond.** The user picks
+  `process-step` for one step or `process-full` for the whole roadmap.
+- **No commit, push, branch, PR, tag, or bulk-destructive op** without
+  explicit permission this turn — see
+  [`commit-policy`](../../rules/commit-policy.md) and
+  [`scope-control § git-ops`](../../rules/scope-control.md#git-operations--permission-gated).
+  Roadmap-listed commit steps follow the single-upfront-ask flow in
+  [`roadmap-process-loop § 3`](../../contexts/execution/roadmap-process-loop.md#3-commit-step-pre-scan--one-upfront-ask).
+- **Every checkbox edit syncs the dashboard in the same response** per
+  [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
+- **AI-council consultations run silently when council is on.** No
+  per-call confirmation. The opt-in covers the whole run.
+- **Decline = silence.** Once the user said "skip council", do not
+  re-offer for the rest of this run.
+- **Halt cleanly on Hard-Floor or true ambiguity.** Surface state,
+  wait. Resume on the user's next turn from the same checkbox.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-step`](process-step.md) — single-step variant
+- [`/roadmap:process-full`](process-full.md) — across-phases variant
+- [`/roadmap:create`](create.md) — sibling, scaffolds roadmaps
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics
+- [`roadmap-management`](../../skills/roadmap-management/SKILL.md) — checkbox + archival mechanics

package/.agent-src/commands/roadmap/process-step.md

@@ -0,0 +1,57 @@
+---
+name: roadmap:process-step
+cluster: roadmap
+sub: process-step
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "process the next step, do the next roadmap step, einen schritt abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants exactly one step done autonomously"
+---
+
+# /roadmap:process-step
+
+One-step execution scope of the [`/roadmap`](../roadmap.md) cluster.
+Same canonical loop as [`/roadmap:process-phase`](process-phase.md),
+bounded to a single iteration.
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**.
+
+## Scope delta
+
+- **Working set:** the **first checkbox `[ ]` in document order**
+  inside the first phase with `count_open > 0`. If every step is
+  closed → report "Roadmap already complete." and run the archival
+  check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+- **Stop after:** one full iteration of
+  [`roadmap-process-loop § 5`](../../contexts/execution/roadmap-process-loop.md#5-step-loop)
+  (sub-steps 1–7). After the checkbox edit + dashboard regen, **stop**.
+- **Quality cadence:** run the per-step pipeline only when
+  `quality_cadence: per_step`. Skip otherwise.
+- **Phase boundary:** if this single step happens to close the phase,
+  do **not** advance. Report the phase as complete and stop.
+- **Roadmap boundary:** if this single step happens to close the
+  entire roadmap, run the archival check before reporting.
+
+## Rules
+
+- **Stop after one step**, even if the next step is trivial. The user
+  picks `process-phase` or `process-full` when they want more.
+- All other rules from
+  [`process-phase § Rules`](process-phase.md#rules) apply unchanged:
+  Hard-Floor, no auto-commit, dashboard sync, AI-council silent-when-on,
+  decline = silence.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-phase`](process-phase.md) — default scope, single phase
+- [`/roadmap:process-full`](process-full.md) — across-phases variant
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics

package/.agent-src/commands/roadmap.md

@@ -1,44 +1,72 @@
 ---
 name: roadmap
-description: Roadmap orchestrator — routes to create, execute
+description: Roadmap orchestrator — routes to create (authoring) and process-step / process-phase / process-full (autonomous execution).
 cluster: roadmap
 disable-model-invocation: true
 suggestion:
   eligible: true
-  trigger_description: "create a roadmap, execute a roadmap, plan a roadmap interactively"
-  trigger_context: "user wants to scaffold or run a roadmap under agents/roadmaps/"
+  trigger_description: "create a roadmap, process a roadmap, work through a roadmap autonomously, plan or abarbeiten"
+  trigger_context: "user wants to scaffold or autonomously execute a roadmap under agents/roadmaps/"
 ---
 
 # /roadmap
 
-Top-level orchestrator for the `/roadmap` family. Replaces 2 standalone
-commands with a single entry point + sub-command dispatch.
+Top-level orchestrator for the `/roadmap` family. Carries authoring
+(`create`) and the three autonomous-execution scopes (`process-step`,
+`process-phase`, `process-full`). The legacy `/roadmap execute` (which
+paused for confirmation before every step) was removed —
+`process-phase` is the default execution scope.
 
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
 |---|---|---|
-| `/roadmap create` | `commands/roadmap/create.md` | Interactively create a new roadmap in `agents/roadmaps/` |
-| `/roadmap execute` | `commands/roadmap/execute.md` | Read and interactively execute a roadmap |
+| `/roadmap:create` | `commands/roadmap/create.md` | Interactively scaffold a new roadmap in `agents/roadmaps/` |
+| `/roadmap:ai-council` | `commands/roadmap/ai-council.md` | Challenge an existing roadmap with the AI council (deep tier) and refactor from convergence findings |
+| `/roadmap:process-step` | `commands/roadmap/process-step.md` | Autonomously process the next open step, then stop |
+| `/roadmap:process-phase` (**default execution scope**) | `commands/roadmap/process-phase.md` | Autonomously process every open step in the current phase |
+| `/roadmap:process-full` | `commands/roadmap/process-full.md` | Autonomously process every open step across every phase |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+`:` and space are equivalent at the cluster boundary — see
+[`slash-command-routing-policy-mechanics`](../contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md#routing-semantics).
+The three `process-*` subs share the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../contexts/execution/roadmap-process-loop.md);
+each only binds a scope delta.
 
 ## Dispatch
 
-1. Parse the user's argument: `/roadmap <sub-command> [args]`.
+1. Parse the user's argument: `/roadmap[:<sub>] [args]` or
+   `/roadmap <sub> [args]`.
 2. Look up the sub-command in the table above.
-3. Load the body of the routed file and follow its `## Instructions` section
-   verbatim with the remaining args.
-4. If the sub-command is unknown or missing, print the table above and ask:
+3. Load the body of the routed file and follow its `## Instructions`
+   section verbatim with the remaining args.
+4. **Legacy forwarding:**
+   - `/roadmap execute` or `/roadmap-execute` → forward to
+     [`/roadmap:process-phase`](roadmap/process-phase.md) (default
+     scope) with a one-time migration notice.
+   - `/roadmap-process[:<sub>]` (legacy top-level cluster) → forward
+     to `/roadmap:process-<sub>` with a one-time migration notice.
+5. If the sub-command is unknown or missing, print the table above
+   and ask:
 
    > 1. create — scaffold a new roadmap interactively
-   > 2. execute — run an existing roadmap step by step
+   > 2. ai-council — challenge + refactor an existing roadmap (deep tier)
+   > 3. process-step — process the next open step, then stop
+   > 4. process-phase — process the current phase (default)
+   > 5. process-full — process every open step across every phase
 
 ## Rules
 
-- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
-  authorizes it.
+- **Do NOT commit, push, or open a PR** unless the sub-command
+  explicitly authorizes it. Roadmap-listed commit steps follow the
+  single-upfront-ask flow in
+  [`roadmap-process-loop § 3`](../contexts/execution/roadmap-process-loop.md#3-commit-step-pre-scan--one-upfront-ask).
 - **Do NOT chain sub-commands.** One `/roadmap <sub>` per turn.
-- If the user invokes `/roadmap` with no argument, **show the menu** — do
-  not guess which sub-command they meant.
+- If the user invokes `/roadmap` with no argument, **show the menu** —
+  do not guess which sub-command they meant.
+- Execution intents (*"work through the roadmap"*, *"abarbeiten"*,
+  *"finish this phase"*) default to
+  [`/roadmap:process-phase`](roadmap/process-phase.md) unless the user
+  named a different scope.

package/.agent-src/commands/threat-model.md

@@ -3,6 +3,7 @@ name: threat-model
 skills: [threat-modeling, authz-review, security-sensitive-stop]
 description: 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
 disable-model-invocation: true
+council_depth: deep
 suggestion:
   eligible: true
   trigger_description: "threat model this change, what could go wrong security-wise"

package/.agent-src/contexts/augment-infrastructure.md

@@ -106,7 +106,7 @@ Commands organized by workflow:
 | **Bugs** | `bug-investigate`, `bug-fix` |
 | **Contexts** | `context-create`, `context-refactor` |
 | **Modules** | `module-create`, `module-explore` |
-| **Roadmaps** | `roadmap-create`, `roadmap-execute` |
+| **Roadmaps** | `roadmap:create`, `roadmap:process-step`, `roadmap:process-phase`, `roadmap:process-full` |
 | **Quality** | `quality-fix`, `review-changes`, `prepare-for-review`, `update-form-request-messages`, `fix-seeder` |
 | **CI/PR** | `fix-ci`, `create-pr`, `create-pr-description`, `fix-pr-comments`, `fix-pr-bot-comments`, `fix-pr-developer-comments` |
 | **Testing** | `tests-create`, `tests-execute` |

package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -10,40 +10,75 @@ this file mirrors that contract for runtime lookup. Linter:
 
 ## Locked clusters and sub-commands
 
-| Cluster | Phase | Sub-commands | Replaces |
-|---|:-:|---|---|
+| Cluster | Phase | Sub-commands | Replaces                                                                                                                                        |
+|---|:-:|---|-------------------------------------------------------------------------------------------------------------------------------------------------|
 | `/fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `/fix-ci` · `/fix-pr-comments` · `/fix-pr-bot-comments` · `/fix-pr-developer-comments` · `/fix-portability` · `/fix-references` · `/fix-seeder` |
-| `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills` |
-| `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap` |
-| `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` |
-| `/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` |
-| `/module` | 2 | `create` · `explore` | `/module-create` · `/module-explore` |
-| `/tests` | 2 | `create` · `execute` | `/tests-create` · `/tests-execute` |
-| `/context` | 2 | `create` · `refactor` | `/context-create` · `/context-refactor` |
-| `/override` | 2 | `create` · `manage` | `/override-create` · `/override-manage` |
-| `/copilot-agents` | 2 | `init` · `optimize` | `/copilot-agents-init` · `/copilot-agents-optimize` |
-| `/judge` | 2 | `solo` · `on-diff` · `steps` | `/judge` (legacy standalone) · `/do-and-judge` · `/do-in-steps` |
-| `/commit` | 2 | flag: `--in-chunks` | `/commit:in-chunks` |
-| `/create-pr` | 2 | flag: `--description-only` | `/create-pr:description-only` |
+| `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills`                                                   |
+| `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap`                                                                 |
+| `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only`                                 |
+| `/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` · `process-step` · `process-phase` · `process-full` | `/roadmap-create` · `/roadmap-process` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope)                |
+| `/module` | 2 | `create` · `explore` | `/module-create` · `/module-explore`                                                                                                            |
+| `/tests` | 2 | `create` · `execute` | `/tests-create` · `/tests-execute`                                                                                                              |
+| `/context` | 2 | `create` · `refactor` | `/context-create` · `/context-refactor`                                                                                                         |
+| `/override` | 2 | `create` · `manage` | `/override-create` · `/override-manage`                                                                                                         |
+| `/copilot-agents` | 2 | `init` · `optimize` | `/copilot-agents-init` · `/copilot-agents-optimize`                                                                                             |
+| `/judge` | 2 | `solo` · `on-diff` · `steps` | `/judge` (legacy standalone) · `/do-and-judge` · `/do-in-steps`                                                                                 |
+| `/commit` | 2 | flag: `--in-chunks` | `/commit:in-chunks`                                                                                                                             |
+| `/create-pr` | 2 | flag: `--description-only` | `/create-pr:description-only`                                                                                                                   |
 
 ## Routing semantics
 
-1. The user types `/<cluster> [<sub>] [args]`.
+1. The user invokes a cluster sub-command in **one of two equivalent
+   forms**:
+   - `/<cluster>:<sub> [args]` — **canonical**. Single token, plays
+     well with shell autocompletion and the slash-command picker.
+   - `/<cluster> <sub> [args]` — **space-separated equivalent**.
+     Identical semantics. Accept everywhere.
+
+   Both forms route to the **same file** and the **same dispatcher**.
+   Implementations MUST treat `:` and `<space>` as interchangeable
+   delimiters at the cluster boundary. Autocompletion-aware UIs
+   (Claude.ai picker, IDE slash-menus, shell completers) should
+   surface the `:` form because it stays a single token.
+
 2. Match the cluster against the table above. If the leading token is
    a dispatcher cluster, route to the dispatcher's `commands/<cluster>.md`
    and let the dispatcher's "Dispatch" section pick the sub-command.
+
 3. If the leading token is a flag-cluster (`/commit`, `/create-pr`),
    the cluster file is the entry point itself; flags absorb the
    former helper command.
+
 4. **Legacy atomic shims** (`/fix-ci`, `/agents-audit`, …) keep working
    for one release cycle. They emit a deprecation warning and forward
    to the cluster invocation. New invocations should always use the
-   cluster form.
+   cluster form. **`/roadmap-execute` is removed** — invocations route
+   to `/roadmap:process-phase` (default execution scope) with a
+   one-time migration notice. Legacy `/roadmap-process[:<sub>]`
+   invocations (the short-lived top-level cluster) likewise forward
+   to `/roadmap:process-<sub>`.
+
 5. If a sub-command is unknown, the dispatcher prints the menu — never
    guess.
 
+## Why colon is canonical
+
+Locked by [ADR-003](../../../../docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md)
+(2026-05-07) alongside the flat-cluster + composite-sub-name shape.
+
+- **Single token in autocompleters.** `roadmap:process-phase` completes
+  as one piece; `roadmap process-phase` requires the picker to
+  re-prompt after the space.
+- **Stable in chat history and logs.** Greppable as one string.
+- **Unambiguous against free-text args.** `/roadmap:process-phase
+  road-to-X.md` parses cleanly; the picker never confuses the sub
+  with the first argument.
+- **Symmetric across the catalog.** `/commit:in-chunks` and
+  `/create-pr:description-only` already use this form; cluster
+  dispatchers gain it without regressing the space form.
+
 ## Removal cycle
 
 | Cycle | Active form | Shim form |