@event4u/agent-config 14.6.0 → 14.7.0

package/dist/agent-src/skills/roadmap-management/SKILL.md

@@ -98,419 +98,25 @@ actual paths in the current project; never assume `app/Modules/`.
 The file `.augment/templates/roadmaps.md` defines the canonical structure.
 **Always read it first** before creating or modifying roadmaps.
 
-## Roadmap structure
 
-Every roadmap follows this structure:
+## Modes
 
-```markdown
-# Roadmap: {Short descriptive title}
+This skill is a router head. The dashboard-sync obligation above, the procedure
+skeleton, and the location table are true in every mode and stay here. The
+per-mode procedure bodies live in `references/`; load the one the task calls
+for, not the set.
 
-> {One sentence: What is the expected outcome?}
-
-## Prerequisites
-
-- [ ] Read `AGENTS.md` and relevant docs
-- [ ] {specific prerequisites}
-
-## Context
-
-{Why this roadmap exists. Which module/domain. Links to Jira tickets.}
-
-## Phase 1: {Phase name}
-
-- [ ] **Step 1:** {Clear, actionable instruction}
-- [ ] **Step 2:** {Next step — reference files/classes}
-- [ ] ...
-
-## Phase 2: {Phase name}
-
-- [ ] **Step 1:** {description}
-- [ ] ...
-
-## Acceptance Criteria
-
-- [ ] {Observable, testable criterion}
-- [ ] All quality gates pass — the project's type-checker, auto-fixer, linter, and full test suite (see the `quality-tools` skill for stack-specific invocations)
-
-## Notes
-
-{Edge cases, decisions, links}
-```
-
-## Key rules for roadmaps
-
-### Checkboxes — mandatory, not decorative
-
-- **Every active roadmap MUST contain at least one `- [ ]` per non-intro phase.** Decision tables, ICE matrices, and block-sequencing tables are valid rationale, but they do not satisfy this rule on their own — pair them with a `## Phase N` or `## Implementation Checklist` section whose checkboxes execute the decision. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` and violates [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) Iron Law #2.
-- Every actionable step uses `- [ ]` (unchecked) or `- [x]` (completed).
-- Mark steps as `[x]` immediately after completing them.
-- Never remove completed steps — they serve as history.
-- **Status is binary: `ready` (default, implicit) or `draft`.** New roadmaps are created **ready** unless the user explicitly says otherwise — `ready` is implicit and need not be written. A roadmap that is still being authored, awaiting upstream decisions, or capturing options without a worked plan declares `status: draft` in YAML frontmatter at the top of the file. Drafts are hidden from `agents/roadmaps-progress.md` until the flag is removed or flipped to `ready`. There are no other status values; legacy banners (`**Status: directional**`, `Status: capture-only`, `mode: feedback`) are removed.
-
-### Awaiting evidence — a blocker entry, never a new glyph
-
-- Waiting on **evidence that has not arrived** (soak still running, benchmark unfunded, adopter absent) is neither `[~]` nor `[-]`. Signal it with a structured `## Blockers` entry — five-field shape in [`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md) — whose `Resolved when:` names the decidable signal ending the wait. The item stays `- [ ]` and points at it: `<!-- blocked-by: <id> -->`.
-- **No new glyph.** `[ ]` + `blocked-by:` = open, awaiting named evidence (stays active) · `[~]` = deferred by decision (bars archival, Iron Law 3) · `[-]` = cancelled with a reason (does not bar it). A fifth state buys nothing the entry above does not already carry.
-
-### Phases
-
-- Group related steps into phases (e.g. "Preparation", "Migration", "Cleanup").
-- Complete one phase before starting the next (unless steps are independent).
-- After completing a phase, summarize what was done.
-
-### Quality gates
-
-Every roadmap implicitly includes the project's quality pipeline
-(static analysis, autofixes, tests). Whether the agent runs it locally
-at all is gated by `quality.local_auto_run`: `false` or missing (the
-default) → the agent never runs the pipeline locally; the user runs it
-manually and remote CI on the PR is the authoritative gate (run-end
-report: *"quality gates delegated to remote CI"*; new-gate carve-out
-steps still run once). When `local_auto_run: true`, **when** the
-pipeline runs during `/roadmap:process-step|phase|full` is controlled
-by `roadmap.quality_cadence` in `.agent-settings.yml`:
-
-| Cadence | Pipeline runs (`local_auto_run: true` only) | Trade-off |
-|---|---|---|
-| `end_of_roadmap` (default) | Once before archiving | Fastest, fewest tokens; errors compound across phases |
-| `per_phase` | After every completed phase + final | Balanced; catches drift at phase boundaries |
-| `per_step` | After every completed step + final | Legacy verbose; highest token cost |
-
-The default is `end_of_roadmap` because most steps are checkbox-only
-content edits and a final pipeline run is the cheapest way to satisfy
-`verify-before-complete`. Switch to `per_phase` for risky migrations or
-unfamiliar codebases.
-
-**Always-on, regardless of cadence:**
-
-- Step checkboxes flip `[ ] → [x]` and the dashboard regenerates **same
-  response** (enforced by `roadmap-progress-sync`).
-- Before any "roadmap complete" claim or archival, the pipeline runs
-  fresh (enforced by `verify-before-complete`).
-
-### Step granularity
-
-- Each step should be completable in one session (< 1 hour of work).
-- If a step is too large, break it down into sub-steps.
-- Steps should reference specific files/classes when possible.
-
-### Language
-
-- Roadmap files are written in **English** (per project convention).
-- Step descriptions should be precise and actionable, not vague.
-
-## Working with roadmaps
-
-### Creating a roadmap
-
-1. Ask the user for goal, context-create, and phases.
-2. Use the template structure from `.augment/templates/roadmaps.md`.
-3. Review with the user iteratively until approved.
-4. **Branch & release questions — at most once, only if genuinely useful.**
-   Default: stay on the current branch, no version numbers in the
-   roadmap. Only propose a separate branch when there is concrete,
-   evidence-based reason (e.g. risky migration benefits from a spike).
-   Never include release versions, deprecation dates, or git tags in
-   the roadmap text. If the user declines, do **not** re-propose during
-   `/roadmap:process-*`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
-5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
-   **Before writing**, scan the entire roadmap namespace for a
-   collision — active, `archive/`, `skipped/`, and nested subdirs —
-   with `find agents/roadmaps -type f -iname "<name>.md"`. If any
-   hit comes back, stop and ask the user to rename, open the
-   existing file, or abort. Never silently overwrite an archived
-   or skipped roadmap. Detailed prompt in
-   [`commands/roadmap/create.md`](../../commands/roadmap/create.md)
-   step 6.
-6. Regenerate the dashboard so the new roadmap is included.
-
-### Executing a roadmap
-
-0. Resolve the mode per `roadmap-process-loop` § 3a: suffix, frontmatter
-   `execution.mode`, invocation form (absent = derived, not
-   `interactive`). Under `/roadmap:process-*` the mode selects the
-   interaction pattern via the run-start execution contract — see
-   [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
-   The manual flow below describes `interactive`; under `autonomous`
-   / `phase-checkpoints` step 4's per-step ask is replaced by the
-   accepted contract. **Mode never changes archival semantics** —
-   glyph counting, the closure decision table, and the Iron Law 3
-   deferred-resolution gate below apply identically in every mode.
-1. Read the full roadmap.
-2. Find the next unchecked step (`- [ ]`).
-3. Summarize what needs to be done.
-4. Ask the user before implementing (numbered options: implement / adjust / skip).
-5. After implementation: mark `[x]`, run quality gates, then regenerate the dashboard.
-6. Move to the next step.
-
-### Resuming a roadmap
-
-When picking up a roadmap in a new session:
-1. Read the roadmap to understand the full context.
-2. Check which steps are already completed (`[x]`).
-3. Summarize progress to the user.
-4. Continue from the next open step.
-
-### Completing, archiving & skipping a roadmap
-
-Every roadmap ends in exactly one of four states:
-
-| State | Folder | Trigger |
+| Task | Mode body | Covers |
 |---|---|---|
-| **Active** | `agents/roadmaps/` | Work in progress or planned **and workable now** |
-| **Archived** | `agents/roadmaps/archive/` | Work was done (fully or partially) and no more work is planned |
-| **Skipped** | `agents/roadmaps/skipped/` | Decision against pursuit — superseded, scope rejected, wrong direction. Typically **0 items `[x]`** |
-| **Later** | `agents/roadmaps/later/` | Open work remains but is **blocked-for-later** — gated on an external trigger or a decision, **will resume** when unblocked. Set frontmatter `status: later` + a `Blocked until` / `Trigger` resume line. Excluded from the dashboard and `/roadmap:process-*` (parked, not abandoned). |
-
-**Active vs. Later — the test:** can the agent make progress on this roadmap *now*, autonomously? If every open item is gated on something outside this roadmap (a real consumer repo, a benchmark re-open, host-model access, a kernel soak, a pruning track, a human decision), it is **not** active — move it to `later/` with its resume condition. A blocked roadmap left in the active tree silently lies to the dashboard and to `/roadmap:process-*`, which will keep trying to execute it. The `lint_roadmap_later_disposition` guard enforces the placement↔`status: later` contract.
-
-After the last step of a roadmap is done, check completion status:
-
-0. **Completion review (Gate R2)** — last open item done → findings BEFORE
-   fixes, before any archival decision:
-   - `dispatch_r2_reviewer` builds the reviewer input; a **fresh subagent
-     without the implementation context** writes
-     `agents/evidence/reviews/<slug>.findings.md`.
-   - Work findings in priority order — each ends `fixed` / `accepted-risk` /
-     `deferred`. No code surface → explicit skip, never silent.
-   - Grammar, scope-hash binding, escape hatch:
-     [`plan-review-gates § 2`](../../../docs/contracts/plan-review-gates.md).
-
-1. **Scan the file** for all checkbox markers: `- [x]`, `- [ ]`, `- [~]`, `- [-]`.
-2. **Classify:**
-   - `[x]` = completed
-   - `[ ]` = open (not done)
-   - `[~]` = deferred (intentionally pushed out, may come back)
-   - `[-]` = cancelled (individual item dropped)
-
-3. **Decision rule — `count_open == 0` means the roadmap has no active
-   work left. `[x]`, `[-]` are final states. `[~]` deferred items
-   block silent closure — they carry plans the user has not consented
-   to drop (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
-   Iron Law 3).**
-
-   | count_x | count_open | count_deferred | count_cancelled | Action |
-   |---|---|---|---|---|
-   | ≥ 1 | 0 | 0 | 0 | **Auto-archive** (silent) — pure completion |
-   | ≥ 1 | 0 | 0 | ≥ 1 | **Auto-archive** (silent) — done with explicit drops |
-   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present the options, resolve by the preservation test (council where the item survives, user where it does not). See step 4b. |
-   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Was this a scope-drop or deferred-to-later? Same options and same routing as 4b. |
-   | 0 | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work, all cancelled |
-   | ≥ 0 | ≥ 1 | ≥ 0 | ≥ 0 | **Ask the user** — open work remains (step 4a) |
-
-   Show on auto-move:
-
-   - Archive: `✅  Roadmap archived → agents/roadmaps/archive/{filename}`
-   - Skip:    `⏭️  Roadmap skipped → agents/roadmaps/skipped/{filename}`
-   - Later:   `🕒  Roadmap parked for later → agents/roadmaps/later/{filename}`
-
-   `[-]` cancelled items remain searchable inside the archived file —
-   they were explicit drops. `[~]` deferred items, by contrast, may
-   not silently follow the file into archive: they represent work the
-   user planned and would lose track of. Step 4b is the gate.
-
-4a. **Open items remain (`count_open ≥ 1`)** → **Ask the user.** Show what's incomplete:
-
-   ```
-   📋 Roadmap completion check:
-
-     ✅  Completed: {count_x}
-     ⬜  Open:      {count_open}  — {list of open items, 1 line each}
-     ⏭️  Deferred:  {count_deferred}  — {list of deferred items, 1 line each}
-     ❌  Cancelled: {count_cancelled} — {list of cancelled items, 1 line each}
-
-   > 1. Archive — mark open items as cancelled [-] and archive now
-   > 2. Keep active — I want to finish the open items
-   > 3. Mark open items as deferred [~] and archive (triggers Iron Law 3 flow)
-   > 4. Skip — move to skipped/ (no meaningful work done, not pursuing)
-   > 5. Later — park in later/ (open work is blocked on an external trigger / decision but will resume)
-   ```
-
-   Option 4 is only appropriate when `count_x == 0` or the completed items were
-   trivial (e.g. prerequisites only). If the user picks 4 despite meaningful work
-   being done, confirm once — archive is usually the right choice. Picking option 3
-   does NOT archive immediately — it converts open → deferred and re-enters the
-   `count_deferred > 0` branch, which runs step 4b.
-
-   **Option 5 (Later) is the right choice when the open items are real but
-   cannot proceed now** — gated on an external trigger or a decision. Set the
-   roadmap's frontmatter `status: later`, ensure it carries a `Blocked until` /
-   `Trigger` resume line, `git mv` it to `agents/roadmaps/later/`, migrate any
-   inbound references to the new path, and regenerate the dashboard. The open
-   `[ ]` items stay open (they are not cancelled or deferred) — the roadmap is
-   parked whole, ready to resume when the trigger fires. **Roadmaps with open
-   tasks deferred for later are always moved to `later/`**, never left to rot in
-   the active tree.
-
-4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
-   Archive **blocked** until resolved. WHO resolves is the preservation test in
-   [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md),
-   never the mode — same menu either way, only the resolver differs:
-
-   - **1, 2, 4** keep the item alive → **council**, recorded at the item (2 only
-     if the follow-up lands in the SAME change).
-   - **3, 5** drop or weaken it → **user**, always. In doubt: user.
-
-   ```
-   📋 Roadmap closure check — deferred items must resolve before archive:
-
-     ✅  Completed: {count_x}
-     ⏭️  Deferred:  {count_deferred}
-     {for each deferred item:}
-       - Phase {N}: {step text}  {<!-- deferred: <annotation> --> if present}
-
-   These items carry plans you would lose to a silent archive.
-
-   > 1. Spawn follow-up roadmap as DRAFT
-   >    → agents/roadmaps/road-to-{auto-slug}.md, status: draft,
-   >      parent_roadmap: {this-slug}. Hidden from the dashboard until
-   >      you flip status to "ready".
-   > 2. Spawn follow-up roadmap as READY (with blocked-until note)
-   >    → status: ready (default), parent_roadmap: {this-slug}, plus
-   >      a `> Blocked until <condition>` line in the body. Visible
-   >      in the dashboard; execution waits on the condition.
-   > 3. Keep deferred items in this archive — confirm "no follow-up"
-   >    is an intentional drop. Items stay searchable in archive/.
-   > 4. Restore selected items to [ ] — finish them here before archive.
-   > 5. Convert selected items to [-] cancelled — drop with rationale.
-   ```
-
-   Picks 1 or 2 → see "Spawn follow-up from deferred items" procedure below.
-   Picks 3, 4, or 5 → apply the change in this roadmap; re-evaluate the
-   decision table; archive when the gate clears.
-
-### Spawn follow-up from deferred items (procedure)
-
-When the user picks option 1 or 2 in step 4b:
-
-1. **Derive the slug.** Default `<parent-slug>-followup` (e.g.
-   `road-to-x.md` → `road-to-x-followup.md`). If a user-supplied
-   slug was given in the picker, use that. Avoid collisions with
-   `agents/roadmaps/` (active + `archive/` + `skipped/`).
-
-2. **Write the new file** at `agents/roadmaps/<slug>.md`:
-
-   ```markdown
-   ---
-   complexity: lightweight            # bump if the parent was structural
-   status: draft                      # option 1; omit for option 2 (= ready)
-   parent_roadmap: <parent-slug>      # back-link to source
-   ---
-
-   # Roadmap: Follow-up to <parent-title>
-
-   > <One sentence stating the carried-over outcome.>
-
-   ## Context
-
-   This roadmap collects items deferred from
-   [`agents/roadmaps/archive/<parent-slug>.md`](archive/<parent-slug>.md).
-   See the parent's archive entry for the original rationale.
-
-   ## Prerequisites
-
-   - [ ] Read `AGENTS.md` and the parent archive entry.
-   {parent prerequisites still relevant, copied verbatim}
-
-   <!-- Option 2 only — body note, NOT a frontmatter key: -->
-   > Blocked until <condition>. Execution starts when the condition clears.
-
-   ## Phase 1: <name carried from parent>
-
-   - [ ] {deferred step text, copied verbatim with parent-phase pointer}
-   {repeat per deferred item, regrouped by parent phase}
-
-   ## Acceptance Criteria
-
-   - [ ] {restate or adjust per the deferred scope}
-   - [ ] All quality gates pass — see `quality-tools`.
-   ```
-
-3. **In the parent roadmap** (still in the working tree), append a
-   line at the bottom (above any final `---`):
-
-   ```
-   <!-- Deferred items migrated to agents/roadmaps/<followup-slug>.md on YYYY-MM-DD -->
-   ```
-
-   Do **not** delete the `[~]` lines — keep them visible in the
-   archived parent so the trail stays grep-able. The follow-up
-   carries forward the executable copy.
-
-4. **Regenerate the dashboard.** The follow-up appears (draft hidden,
-   ready visible) and the parent — once moved — drops off.
-
-5. **Archive the parent** (`git mv` → `archive/`) and regen one
-   more time per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
-   Iron Laws 1 + 3.
-
-5. **Move the file** with `git mv` so history is preserved:
-
-   ```bash
-   # Archive (work was done)
-   git mv agents/roadmaps/{file} agents/roadmaps/archive/{file}
-
-   # Skipped (not pursuing)
-   git mv agents/roadmaps/{file} agents/roadmaps/skipped/{file}
-   ```
-
-6. **Regenerate the dashboard** (see "Command" below). The moved roadmap is
-   excluded from the active set once it sits in `archive/` or `skipped/`.
-
-### When to use `skipped/` vs `archive/`
-
-| Situation | Destination |
-|---|---|
-| Finished all phases | `archive/` |
-| Finished some phases, rest deferred/cancelled on purpose | `archive/` |
-| Whole roadmap deferred or cancelled (no `[x]` at all) | `skipped/` |
-| Never started, scope decision reversed | `skipped/` |
-| Superseded by another roadmap | `skipped/` — add a pointer line at the top: `> Superseded by agents/roadmaps/{other}.md` |
-| Research proved the direction wrong | `skipped/` — add a 1-line reason at the top |
-
-If in doubt: archive beats skipped. `skipped/` is reserved for roadmaps where
-no meaningful work was invested and the scope itself was rejected.
-
-## Progress dashboard — `agents/roadmaps-progress.md`
-
-A generated dashboard aggregates progress across every open roadmap. It sits at
-`agents/roadmaps-progress.md` (outside `roadmaps/` to keep the folder clean) and
-is rewritten by `.augment/scripts/update_roadmap_progress.ts`.
-
-**Always regenerate in the SAME response** after any of the following
-(enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
-
-- Creating a new roadmap (`/roadmap:create`)
-- Marking a step `[x]`, `[~]`, or `[-]` during `/roadmap:process-*`
-- Archiving or moving a roadmap to `skipped/`
-- Adding, renaming, or removing a phase
-
-Command:
-
-```bash
-./agent-config roadmap:progress           # rewrite the dashboard
-./agent-config roadmap:progress-check     # CI: fail if stale
-```
-
-The `./agent-config` wrapper lives in the project root (written by the
-package installer, gitignored) and delegates to the master CLI inside
-`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
-No global tooling required.
-
-The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
-
-### Blockers on the dashboard
-
-The overview table's `Blocker` column counts each roadmap's open
-`## Blockers` entries (or the legacy `> Blocked until` note) and links
-to the per-roadmap breakdown, which lists every open blocker with
-owner, blocked scope, and full instructions. Authoring shape:
-[`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md);
-authoring guidance: [`roadmap-writing § 5b`](../roadmap-writing/SKILL.md).
-Clearing a blocker flips its `Status: resolved` and regenerates the
-dashboard in the same reply, same cadence as a checkbox flip. The
-blocker entry is also the canonical **awaiting-evidence** signal —
-see [§ Awaiting evidence](#awaiting-evidence--a-blocker-entry-never-a-new-glyph).
+| Author a roadmap — structure and the rules it must satisfy | [`references/authoring.md`](references/authoring.md) | The canonical structure block, checkbox semantics, awaiting-evidence as a blocker entry, phases, quality gates, step granularity, language |
+| Create, execute, or resume a roadmap | [`references/lifecycle.md`](references/lifecycle.md) | Creating a roadmap, executing one step by step, resuming a partially-done one |
+| Complete, archive, or skip a roadmap | [`references/archival.md`](references/archival.md) | The four end states, the archival sweep and its manual fallback, spawning a follow-up from deferred items, `skipped/` versus `archive/` |
+| Regenerate or read the progress dashboard | [`references/dashboard.md`](references/dashboard.md) | The generated dashboard, its regeneration cadence, blockers on the dashboard |
+
+Archival is the mode with the sharpest failure: an archive that buries deferred
+work or open blockers is the thing the sweep refuses to do, so load
+[`references/archival.md`](references/archival.md) before archiving anything
+rather than working from memory of it.
 
 ## Rubric pass (optional, surfacing-only)
 

package/dist/agent-src/skills/roadmap-management/references/archival.md

@@ -0,0 +1,226 @@
+# roadmap-management — completing, archiving, skipping
+
+> Mode body of the [`roadmap-management`](../SKILL.md) skill (router-head
+> retrofit, 2026-08-20). Content moved VERBATIM from SKILL.md — load this
+> file when the mode table in SKILL.md routes here.
+
+### Completing, archiving & skipping a roadmap
+
+Every roadmap ends in exactly one of four states:
+
+| State | Folder | Trigger |
+|---|---|---|
+| **Active** | `agents/roadmaps/` | Work in progress or planned **and workable now** |
+| **Archived** | `agents/roadmaps/archive/` | Work was done (fully or partially) and no more work is planned |
+| **Skipped** | `agents/roadmaps/skipped/` | Decision against pursuit — superseded, scope rejected, wrong direction. Typically **0 items `[x]`** |
+| **Later** | `agents/roadmaps/later/` | Open work remains but is **blocked-for-later** — gated on an external trigger or a decision, **will resume** when unblocked. Set frontmatter `status: later` + a `Blocked until` / `Trigger` resume line. Excluded from the dashboard and `/roadmap:process-*` (parked, not abandoned). |
+
+**Active vs. Later — the test:** can the agent make progress on this roadmap *now*, autonomously? If every open item is gated on something outside this roadmap (a real consumer repo, a benchmark re-open, host-model access, a kernel soak, a pruning track, a human decision), it is **not** active — move it to `later/` with its resume condition. A blocked roadmap left in the active tree silently lies to the dashboard and to `/roadmap:process-*`, which will keep trying to execute it. The `lint_roadmap_later_disposition` guard enforces the placement↔`status: later` contract.
+
+After the last step of a roadmap is done, check completion status:
+
+0. **Completion review (Gate R2)** — last open item done → findings BEFORE
+   fixes, before any archival decision:
+   - `dispatch_r2_reviewer` builds the reviewer input; a **fresh subagent
+     without the implementation context** writes
+     `agents/evidence/reviews/<slug>.findings.md`.
+   - Work findings in priority order — each ends `fixed` / `accepted-risk` /
+     `deferred`. No code surface → explicit skip, never silent.
+   - Grammar, scope-hash binding, escape hatch:
+     [`plan-review-gates § 2`](../../../../docs/contracts/plan-review-gates.md).
+
+1. **Scan the file** for all checkbox markers: `- [x]`, `- [ ]`, `- [~]`, `- [-]`.
+2. **Classify:**
+   - `[x]` = completed
+   - `[ ]` = open (not done)
+   - `[~]` = deferred (intentionally pushed out, may come back)
+   - `[-]` = cancelled (individual item dropped)
+
+3. **Decision rule — `count_open == 0` means the roadmap has no active
+   work left. `[x]`, `[-]` are final states. `[~]` deferred items
+   block silent closure — they carry plans the user has not consented
+   to drop (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+   Iron Law 3).**
+
+   | count_x | count_open | count_deferred | count_cancelled | Action |
+   |---|---|---|---|---|
+   | ≥ 1 | 0 | 0 | 0 | **Auto-archive** (silent) — pure completion |
+   | ≥ 1 | 0 | 0 | ≥ 1 | **Auto-archive** (silent) — done with explicit drops |
+   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present the options, resolve by the preservation test (council where the item survives, user where it does not). See step 4b. |
+   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Was this a scope-drop or deferred-to-later? Same options and same routing as 4b. |
+   | 0 | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work, all cancelled |
+   | ≥ 0 | ≥ 1 | ≥ 0 | ≥ 0 | **Ask the user** — open work remains (step 4a) |
+
+   Show on auto-move:
+
+   - Archive: `✅  Roadmap archived → agents/roadmaps/archive/{filename}`
+   - Skip:    `⏭️  Roadmap skipped → agents/roadmaps/skipped/{filename}`
+   - Later:   `🕒  Roadmap parked for later → agents/roadmaps/later/{filename}`
+
+   `[-]` cancelled items remain searchable inside the archived file —
+   they were explicit drops. `[~]` deferred items, by contrast, may
+   not silently follow the file into archive: they represent work the
+   user planned and would lose track of. Step 4b is the gate.
+
+4a. **Open items remain (`count_open ≥ 1`)** → **Ask the user.** Show what's incomplete:
+
+   ```
+   📋 Roadmap completion check:
+
+     ✅  Completed: {count_x}
+     ⬜  Open:      {count_open}  — {list of open items, 1 line each}
+     ⏭️  Deferred:  {count_deferred}  — {list of deferred items, 1 line each}
+     ❌  Cancelled: {count_cancelled} — {list of cancelled items, 1 line each}
+
+   > 1. Archive — mark open items as cancelled [-] and archive now
+   > 2. Keep active — I want to finish the open items
+   > 3. Mark open items as deferred [~] and archive (triggers Iron Law 3 flow)
+   > 4. Skip — move to skipped/ (no meaningful work done, not pursuing)
+   > 5. Later — park in later/ (open work is blocked on an external trigger / decision but will resume)
+   ```
+
+   Option 4 is only appropriate when `count_x == 0` or the completed items were
+   trivial (e.g. prerequisites only). If the user picks 4 despite meaningful work
+   being done, confirm once — archive is usually the right choice. Picking option 3
+   does NOT archive immediately — it converts open → deferred and re-enters the
+   `count_deferred > 0` branch, which runs step 4b.
+
+   **Option 5 (Later) is the right choice when the open items are real but
+   cannot proceed now** — gated on an external trigger or a decision. Set the
+   roadmap's frontmatter `status: later`, ensure it carries a `Blocked until` /
+   `Trigger` resume line, `git mv` it to `agents/roadmaps/later/`, migrate any
+   inbound references to the new path, and regenerate the dashboard. The open
+   `[ ]` items stay open (they are not cancelled or deferred) — the roadmap is
+   parked whole, ready to resume when the trigger fires. **Roadmaps with open
+   tasks deferred for later are always moved to `later/`**, never left to rot in
+   the active tree.
+
+4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
+   Archive **blocked** until resolved. WHO resolves is the preservation test in
+   [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md),
+   never the mode — same menu either way, only the resolver differs:
+
+   - **1, 2, 4** keep the item alive → **council**, recorded at the item (2 only
+     if the follow-up lands in the SAME change).
+   - **3, 5** drop or weaken it → **user**, always. In doubt: user.
+
+   ```
+   📋 Roadmap closure check — deferred items must resolve before archive:
+
+     ✅  Completed: {count_x}
+     ⏭️  Deferred:  {count_deferred}
+     {for each deferred item:}
+       - Phase {N}: {step text}  {<!-- deferred: <annotation> --> if present}
+
+   These items carry plans you would lose to a silent archive.
+
+   > 1. Spawn follow-up roadmap as DRAFT
+   >    → agents/roadmaps/road-to-{auto-slug}.md, status: draft,
+   >      parent_roadmap: {this-slug}. Hidden from the dashboard until
+   >      you flip status to "ready".
+   > 2. Spawn follow-up roadmap as READY (with blocked-until note)
+   >    → status: ready (default), parent_roadmap: {this-slug}, plus
+   >      a `> Blocked until <condition>` line in the body. Visible
+   >      in the dashboard; execution waits on the condition.
+   > 3. Keep deferred items in this archive — confirm "no follow-up"
+   >    is an intentional drop. Items stay searchable in archive/.
+   > 4. Restore selected items to [ ] — finish them here before archive.
+   > 5. Convert selected items to [-] cancelled — drop with rationale.
+   ```
+
+   Picks 1 or 2 → see "Spawn follow-up from deferred items" procedure below.
+   Picks 3, 4, or 5 → apply the change in this roadmap; re-evaluate the
+   decision table; archive when the gate clears.
+
+### Spawn follow-up from deferred items (procedure)
+
+When the user picks option 1 or 2 in step 4b:
+
+1. **Derive the slug.** Default `<parent-slug>-followup` (e.g.
+   `road-to-x.md` → `road-to-x-followup.md`). If a user-supplied
+   slug was given in the picker, use that. Avoid collisions with
+   `agents/roadmaps/` (active + `archive/` + `skipped/`).
+
+2. **Write the new file** at `agents/roadmaps/<slug>.md`:
+
+   ```markdown
+   ---
+   complexity: lightweight            # bump if the parent was structural
+   status: draft                      # option 1; omit for option 2 (= ready)
+   parent_roadmap: <parent-slug>      # back-link to source
+   ---
+
+   # Roadmap: Follow-up to <parent-title>
+
+   > <One sentence stating the carried-over outcome.>
+
+   ## Context
+
+   This roadmap collects items deferred from
+   [`agents/roadmaps/archive/<parent-slug>.md`](archive/<parent-slug>.md).
+   See the parent's archive entry for the original rationale.
+
+   ## Prerequisites
+
+   - [ ] Read `AGENTS.md` and the parent archive entry.
+   {parent prerequisites still relevant, copied verbatim}
+
+   <!-- Option 2 only — body note, NOT a frontmatter key: -->
+   > Blocked until <condition>. Execution starts when the condition clears.
+
+   ## Phase 1: <name carried from parent>
+
+   - [ ] {deferred step text, copied verbatim with parent-phase pointer}
+   {repeat per deferred item, regrouped by parent phase}
+
+   ## Acceptance Criteria
+
+   - [ ] {restate or adjust per the deferred scope}
+   - [ ] All quality gates pass — see `quality-tools`.
+   ```
+
+3. **In the parent roadmap** (still in the working tree), append a
+   line at the bottom (above any final `---`):
+
+   ```
+   <!-- Deferred items migrated to agents/roadmaps/<followup-slug>.md on YYYY-MM-DD -->
+   ```
+
+   Do **not** delete the `[~]` lines — keep them visible in the
+   archived parent so the trail stays grep-able. The follow-up
+   carries forward the executable copy.
+
+4. **Regenerate the dashboard.** The follow-up appears (draft hidden,
+   ready visible) and the parent — once moved — drops off.
+
+5. **Archive the parent** (`git mv` → `archive/`) and regen one
+   more time per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+   Iron Laws 1 + 3.
+
+5. **Move the file** with `git mv` so history is preserved:
+
+   ```bash
+   # Archive (work was done)
+   git mv agents/roadmaps/{file} agents/roadmaps/archive/{file}
+
+   # Skipped (not pursuing)
+   git mv agents/roadmaps/{file} agents/roadmaps/skipped/{file}
+   ```
+
+6. **Regenerate the dashboard** (see "Command" below). The moved roadmap is
+   excluded from the active set once it sits in `archive/` or `skipped/`.
+
+### When to use `skipped/` vs `archive/`
+
+| Situation | Destination |
+|---|---|
+| Finished all phases | `archive/` |
+| Finished some phases, rest deferred/cancelled on purpose | `archive/` |
+| Whole roadmap deferred or cancelled (no `[x]` at all) | `skipped/` |
+| Never started, scope decision reversed | `skipped/` |
+| Superseded by another roadmap | `skipped/` — add a pointer line at the top: `> Superseded by agents/roadmaps/{other}.md` |
+| Research proved the direction wrong | `skipped/` — add a 1-line reason at the top |
+
+If in doubt: archive beats skipped. `skipped/` is reserved for roadmaps where
+no meaningful work was invested and the scope itself was rejected.
+