@event4u/agent-config 4.9.0 → 5.1.0

package/.agent-src/commands/implement-ticket.md

@@ -59,12 +59,13 @@ Three cases, in this order:
   and `.work-state.json` does not. Migrate before doing anything else:
 
   ```bash
-  ./agent-config migrate-state
+  ./agent-config migrate
   ```
 
-  Writes `.work-state.json` and renames the source to
-  `.implement-ticket-state.json.bak`. Idempotent and safe to skip if
-  already done. After this, treat the run as **Resume**.
+  Unified `migrate` writes `.work-state.json`, renames source to
+  `.implement-ticket-state.json.bak`, sweeps other legacy install
+  artefacts (see `docs/contracts/migrate-command.md`). Idempotent and
+  safe to skip if already done. After this, treat the run as **Resume**.
 - **Fresh run** — no state file at all. Write the resolved ticket to
   `ticket.json` (id, title, body, acceptance_criteria) and pass it via
   `--ticket-file ticket.json`. Honour `roles.active_role` from

package/.agent-src/contexts/execution/roadmap-process-loop.md

@@ -231,10 +231,36 @@ execution either way.
   consultations count (if on), steps remaining, halts.
 - Final dashboard regen.
 - **If the entire roadmap reached `count_open == 0`** → run the full
-  project quality pipeline. On green → archival via the
-  [`roadmap-management`](../../skills/roadmap-management/SKILL.md) skill
-  (`git mv` to `agents/roadmaps/archive/`, regenerate dashboard). On
-  red → stop, surface failures, do **not** archive.
+  project quality pipeline. On red → stop, surface failures, do **not**
+  archive. On green → run **deferred-resolution gate** below before
+  archival.
+
+### 6a. Deferred-resolution gate — Iron Law 3
+
+Before any `git mv` to `archive/`, count `[~]` items in closing
+roadmap. If `count_deferred > 0`, archival **blocked** per
+[`roadmap-progress-sync § Iron Law 3`](../../rules/roadmap-progress-sync.md).
+Loop MUST:
+
+1. Enumerate every `[~]` step (phase + text + optional
+   `<!-- deferred: ... -->` annotation).
+2. Surface numbered-options block from
+   [`roadmap-management § 4b`](../../skills/roadmap-management/SKILL.md) —
+   five choices: follow-up (draft), follow-up (ready + blocked),
+   keep-in-archive (intentional drop), restore to `[ ]`, convert
+   to `[-]` cancelled.
+3. Wait for user. Autonomous mandate (`/work`,
+   `/roadmap:process-full`, "decide for me") does **not** lift this
+   gate — Iron Law 3 calls it "the canonical lost-information failure
+   mode this rule exists to prevent."
+4. On picks 1 / 2 → run "Spawn follow-up from deferred items"
+   procedure in [`roadmap-management`](../../skills/roadmap-management/SKILL.md).
+   On picks 3 / 4 / 5 → apply change, re-evaluate decision table,
+   archive when gate clears.
+
+`count_deferred == 0` → archive proceeds via
+[`roadmap-management`](../../skills/roadmap-management/SKILL.md) skill
+(`git mv`, regen).
 
 ## Scope deltas — what each wrapper binds
 

package/.agent-src/rules/language-and-tone.md

@@ -49,26 +49,20 @@ Stays in source language: code blocks, command output, file contents, quoted too
 1. **Detect** — language of user's last chat message. Mixed → dominant; tie → German.
 2. **Scan** — every user-visible token per catalog above.
 3. **Rewrite** — wrong-language token → rewrite the whole reply.
-4. **Confirm** — first sentence in target language; recommendation label matches; no English filler-phrase opener (`Let me`, `Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`) when target is German; no German opener (`Lass mich`, `Jetzt`, `Gefunden`, `Bestätigt`) when target is English.
+4. **Confirm** — first sentence in target language; recommendation label matches; no wrong-language filler-phrase opener. Blocklist: [`language-and-tone-examples § Pre-send gate`](../docs/guidelines/agent-infra/language-and-tone-examples.md#pre-send-gate--filler-phrase-blocklist).
 
 ## Spelled out
 
 - German → informal "Du" (never "Sie"); capitalized at sentence start, lowercase otherwise.
 - Code blocks / command output / file contents / quoted tool output stay native; only surrounding prose mirrors.
 - Numbered options — `.md` source English; rendered reply translated at runtime.
+- Code comments in English. `.md` files in English (see below). Translate existing German `.md` files when touched.
 
 ## Slip handling
 
 Acknowledge **once** in the correct language ("Entschuldigung" / "Sorry"). Switch on the same reply. No re-explain in wrong language; no "from now on" promise.
 
-Examples + wrong-vs-correct: [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md).
-
-## Other language rules
-
-- Code comments in English.
-- `.md` files in English (see below). Translate existing German `.md` files when touched.
-- Two spaces after `❌`, `✅`, `⚠️` in CLI; one space for other icons.
-- One blank line max; no double/triple blanks. File ends with exactly one newline.
+Examples + CLI spacing rules + wrong-vs-correct: [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md).
 
 ## `.md` files — ALWAYS English
 
@@ -76,4 +70,4 @@ Every text inside `.md` under `.augment/`, `.agent-src/`, `.agent-src.uncondense
 
 **Labeled-anchor exception** — quoting German inside English prose is forbidden. Either translate, OR use a labeled `DE: … · EN: …` anchor block (only allowed location for German prose).
 
-**Detection heuristic** before saving: scan for umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) outside fenced code / paths / anchor blocks; German function words (`für`, `nicht`, `dass`, `wenn`, `sollte`, `werden`, `arbeite`, `selbstständig`, `jetzt`, `einfach`, `weiter`, `lösche`, `frag`, `schreib`, `mach`); non-English quoted phrases in body text. Hit → translate or move to `DE: … · EN: …` block.
+Pre-save detection heuristic (umlauts / German function words / non-English quoted phrases): [`language-and-tone-examples § pre-save detection`](../docs/guidelines/agent-infra/language-and-tone-examples.md#md-files--pre-save-detection-heuristic).

package/.agent-src/rules/linked-projects-onboarding-gate.md

@@ -0,0 +1,82 @@
+---
+type: "auto"
+tier: "2b"
+alwaysApply: false
+description: "IDE-attached sibling repo detected — prompt once to opt it into proactive cross-repo awareness, persist local-only, then surface cross-repo impact on relevant changes"
+source: package
+triggers:
+  - intent: "work across two projects"
+  - intent: "sibling repository"
+  - keyword: "linked project"
+  - keyword: "cross-repo"
+  - keyword: "sibling repo"
+  - path_prefix: ".idea/modules.xml"
+  - path_prefix: ".idea/vcs.xml"
+validator_ignore:
+  - type: "substring"
+    pattern: "scripts/_lib/linked_projects.py"
+    reason: "Rule names the detector module as the runtime detection entrypoint."
+workspaces:
+  - agent-config-maintainer
+  - engineering
+packs:
+  - engineering-base
+lifecycle: experimental
+trust:
+  level: experimental
+  confidence: medium
+  human_review_required: false
+install:
+  default: true
+  removable: true
+---
+
+# Linked-Projects Onboarding Gate
+
+**Iron Law.** IDE attached a sibling repo and it is not yet in `linked_projects` → prompt developer **once** to opt in, persist local-only, then proactively flag cross-repo impact — never bulk-include the sibling's files.
+
+Closes the **proactivity gap**: agent can already read/write a sibling, but does not *consider* one unless told — and the developer who most needs cross-repo awareness won't think to mention the sibling. Detection reads the relationship already encoded by attaching the repo in the IDE (zero-knowledge). See the cross-repo guide (`docs/guides/cross-repo-linked-projects.md`) and ADR-032.
+
+## When this fires
+
+First substantive turn (and on new IDE attachment), when a detected sibling is absent from `linked_projects` in `.agent-settings.local.yml` (in agents/settings/). Inert when no sibling attached or every detected sibling already decided (opted-in or declined).
+
+## Detection
+
+Run the detector against project root:
+
+```bash
+python3 -c "from scripts._lib.linked_projects import detect_linked_projects; \
+import json; print(json.dumps(detect_linked_projects('.')))"
+```
+
+Returns config-attached siblings only (PhpStorm `.idea/modules.xml` + `vcs.xml`, VS Code `*.code-workspace`) resolving outside the project, existing, git repos. A sibling above `linked_projects_max_files` (default 20000) carries `"large": true` — awareness only, never excluded.
+
+## Opt-in (one-time per sibling)
+
+For each detected sibling **not** already in `linked_projects`, ask once (numbered options per `user-interaction`): include / decline / always / never-ask. Persist to `.agent-settings.local.yml` (in agents/settings/) (gitignored per-machine layer — never committed `.agent-settings.yml`):
+
+```yaml
+linked_projects:
+  - path: /abs/path/to/sibling
+    include: true        # false = declined; never re-prompt
+```
+
+Declined sibling (`include: false`) never prompted again.
+
+## Behavioral directive (each `include: true` sibling)
+
+- **proactively check cross-repo impact** when a change here may affect it — API-contract changes, shared-type / enum drift, renamed routes the sibling consumes — and **warn** before finishing;
+- **do not bulk-include** the sibling's files (passive awareness, not implicit inclusion — large repos stay cheap);
+- out-of-root edits are normal work, but the host agent's own out-of-root **permission gate still applies** (no silent cross-repo write).
+
+## Kill-switch
+
+Experimental, removable rule. If opt-in consistently declined or siblings never cited, remove it — no telemetry, signal is local.
+
+## Follow-up (not yet shipped)
+
+- Consumer-install detector reachability: detector lives in `scripts/_lib/`; exposing it as an `agent-config` CLI subcommand for consumers is a follow-up. Import-reachable in this repo / co-located maintainer setups today.
+- Multi-agent verification: only Claude Code empirically validated (ADR-032). Cursor / Augment / Copilot unverified — manual fallback in the guide covers them until tested.
+
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/roadmap-progress-sync.md

@@ -48,11 +48,42 @@ IS A RULE VIOLATION, NOT AN OVERSIGHT.
 
 `command:` triggers in this rule's frontmatter load it the moment any `/roadmap:process-*` command fires and keep it loaded for the whole run — independent of whether the agent is editing files under `agents/roadmaps/`. The loop carries its own deterministic flip-guard at [`roadmap-process-loop § 5b`](../contexts/execution/roadmap-process-loop.md#5b-flip-guard--deterministic) — defense-in-depth, not a substitute for the inline flip.
 
-**Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one).
+**Step counts as done** when code/doc saved AND verification cited in step passed (fresh output, this reply or earlier).
 
-**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+**Glyph semantics** — single source of truth, aligned with `scripts/update_roadmap_progress.py` and [`roadmap-management`](../skills/roadmap-management/SKILL.md):
 
-**Dashboard regen cadence — opt-in batching.** The checkbox flip is non-batchable. The **subprocess regen** (`./agent-config roadmap:progress`) is batchable per `roadmap.dashboard_regen_cadence` in `.agent-settings.yml` (`per_step` default · `every_5_steps` · `phase_boundary`). Run end, phase boundary, and any file-shape touch (rename / phase add / archive — Iron Law 1) always force an immediate regen regardless of cadence.
+| Glyph | Meaning | Counter |
+|---|---|---|
+| `[ ]` | open — planned, not done | `count_open` |
+| `[x]` | done — landed + verified | `count_done` |
+| `[~]` | deferred — planned, not happening **this** run; blocks archive (Iron Law 3) | `count_deferred` |
+| `[-]` | cancelled — scope dropped | `count_cancelled` |
+
+`[~]` is **not** "in-progress". Mid-reply work-in-flight has no checkbox change until step lands — normal `[ ] → [x]`.
+
+**Dashboard regen cadence — opt-in batching.** Checkbox flip is non-batchable. **Subprocess regen** (`./agent-config roadmap:progress`) is batchable per `roadmap.dashboard_regen_cadence` (`per_step` default · `every_5_steps` · `phase_boundary`). Run end, phase boundary, any file-shape touch (rename / phase add / archive — Iron Law 1) always force immediate regen regardless of cadence.
+
+## Iron Law 3 — no silent archive with unresolved deferred items
+
+```
+A ROADMAP WITH `[~]` DEFERRED ITEMS NEVER AUTO-ARCHIVES SILENTLY.
+SURFACE EVERY DEFERRED STEP. ASK USER WHAT HAPPENS TO THE PLAN.
+A SILENT ARCHIVE THAT BURIES PLANNED-FOR-LATER WORK
+IS A RULE VIOLATION, NOT A CONVENIENCE.
+```
+
+When closure check fires (`count_open == 0` and `count_deferred > 0`), agent MUST:
+
+1. Enumerate every `[~]` step (phase + step text + any inline `<!-- deferred: ... -->` annotation).
+2. Present numbered options (per [`user-interaction`](user-interaction.md)) — at minimum:
+   1. **Follow-up roadmap (draft)** — spawn `agents/roadmaps/road-to-<slug>.md` with `status: draft`, `parent_roadmap: <this-slug>`, deferred steps lifted verbatim into phases. Draft hidden from dashboard until flipped to `ready`.
+   2. **Follow-up roadmap (ready, blocked)** — spawn with `status: ready` (default), `parent_roadmap: <this-slug>`, plus body note `> Blocked until <condition>`. Dashboard surfaces it; execution waits.
+   3. **Keep in this archive** — confirm deferred items stay searchable in archived file; no follow-up. Records explicit decision-to-drop in same reply.
+   4. **Restore selected items to `[ ]`** — finish them in this roadmap before archive.
+   5. **Convert selected items to `[-]` cancelled** — drop with rationale recorded inline.
+3. Only after user resolves deferrals does `git mv` to `archive/` run. Dashboard regen happens after resolution.
+
+Migration mechanics (file naming, frontmatter, body shape, parent back-link) live in [`roadmap-management § Spawn follow-up from deferred items`](../skills/roadmap-management/SKILL.md). Rule owns obligation; skill owns procedure.
 
 ## Pre-send self-check — MANDATORY
 
@@ -66,9 +97,12 @@ Before sending any reply that landed roadmap work:
    - `phase_boundary` → only when this reply closes the phase or run.
    - Any file-shape touch (rename / phase add / archive) → yes, regardless of cadence.
    If yes and not run yet → run `./agent-config roadmap:progress`, then continue.
-4. Did `count_open` reach 0? If yes → `git mv` to `archive/` and regen again — same reply.
+4. Did `count_open` reach 0?
+   - **No** → continue normally.
+   - **Yes + `count_deferred == 0`** → `git mv` to `archive/` and regen again — same reply.
+   - **Yes + `count_deferred > 0`** → STOP. Run Iron Law 3 deferred-resolution flow (surface items + numbered options + wait). Archive only after resolution.
 
-Any "no" at step 2 → reply is incomplete. Do not send. A skipped step 3 regen is fine when cadence permits — checkbox truth lives in the markdown file.
+Any "no" at step 2 → reply is incomplete. Do not send. Skipped step 3 regen fine when cadence permits — checkbox truth lives in markdown file. Skipping deferred-resolution gate at step 4 is **never** acceptable; it is the canonical "lost-information" failure mode this rule exists to prevent.
 
 Long-form mechanics (failure-mode catalog, Copilot fallback, `[~]` vs `[ ]` semantics, hook + CI defence-in-depth) live in `guideline:agent-infra/roadmap-progress-mechanics`.
 Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/scripts/update_roadmap_progress.py

@@ -16,6 +16,13 @@ Checkbox states:
 Percentage = done / (done + open). Deferred and cancelled do not count towards
 "open" (they are explicit decisions).
 
+`[~]` deferred items carry plans the user intends to revisit later. They
+block silent auto-archive per `roadmap-progress-sync` Iron Law 3: a
+roadmap with `count_open == 0` and `count_deferred > 0` is reported
+separately (`pending_iron_law_3`) and the user must resolve the
+deferrals (spawn follow-up roadmap, restore, or convert to cancelled)
+before the file moves to `archive/`.
+
 Roadmap visibility is binary:
 
   - No `status:` frontmatter (or `status: ready`) → executable, listed.
@@ -245,18 +252,38 @@ def collect(roadmap_root: Path) -> list[RoadmapStats]:
 
 
 def unarchived_complete(roadmaps: list[RoadmapStats]) -> list[RoadmapStats]:
-    # A roadmap is complete when every active checkbox is done and at least
-    # one active checkbox exists. The `roadmap-progress-sync` rule mandates
-    # that such a roadmap be moved to `agents/roadmaps/archive/` in the
-    # same response that closes its last open item; `collect()` already
-    # excludes that directory, so anything left here is unarchived.
-    return [r for r in roadmaps if r.total_active > 0 and r.open_ == 0]
+    # A roadmap is complete-and-clean when every active checkbox is done,
+    # at least one active checkbox exists, AND no `[~]` deferred items
+    # remain. The `roadmap-progress-sync` rule mandates that such a
+    # roadmap be moved to `agents/roadmaps/archive/` in the same response
+    # that closes its last open item; `collect()` already excludes that
+    # directory, so anything left here is unarchived.
+    #
+    # Deferred items are intentionally excluded — they block silent
+    # archive per Iron Law 3 (see `pending_iron_law_3` below).
+    return [
+        r for r in roadmaps
+        if r.total_active > 0 and r.open_ == 0 and r.deferred == 0
+    ]
+
+
+def pending_iron_law_3(roadmaps: list[RoadmapStats]) -> list[RoadmapStats]:
+    # Roadmaps with no open work but unresolved `[~]` deferred items.
+    # Per `roadmap-progress-sync` Iron Law 3 the agent must NOT auto-
+    # archive these — surface the deferred items and ask the user
+    # (spawn follow-up, restore, or convert). The dashboard merely
+    # reports the state; the obligation lives in the rule.
+    return [
+        r for r in roadmaps
+        if r.total_active > 0 and r.open_ == 0 and r.deferred > 0
+    ]
 
 
 def render(roadmaps: list[RoadmapStats]) -> str:
     total_done = sum(r.done for r in roadmaps)
     total_active = sum(r.total_active for r in roadmaps)
     overall_pct = round(total_done * 100 / total_active) if total_active else 0
+    pending = pending_iron_law_3(roadmaps)
     lines: list[str] = []
     lines.append("# Roadmap Progress\n")
     header_meta = (
@@ -274,6 +301,21 @@ def render(roadmaps: list[RoadmapStats]) -> str:
     lines.append("## Overall\n")
     lines.append(f"**{total_done} / {total_active} steps done · {overall_pct}%**\n")
     lines.append("```text\n" + bar(overall_pct, 40) + f"   {overall_pct}%\n```\n")
+    if pending:
+        lines.append("## ⚠️ Iron Law 3 — unresolved deferred items\n")
+        lines.append(
+            "These roadmaps have `count_open == 0` but carry `[~]` deferred "
+            "items. Per `roadmap-progress-sync` Iron Law 3 they do NOT "
+            "auto-archive — the user must resolve the deferrals first "
+            "(spawn follow-up, restore, or cancel). See "
+            "[`roadmap-management § 4b`](../packages/core/.agent-src.uncondensed/skills/roadmap-management/SKILL.md).\n"
+        )
+        lines.append("| Roadmap | Done | Deferred | Cancelled |")
+        lines.append("|---|---:|---:|---:|")
+        for r in pending:
+            lines.append(f"| [{r.rel}](roadmaps/{r.rel}) | {r.done} | "
+                         f"{r.deferred} | {r.cancelled} |")
+        lines.append("")
     if not roadmaps:
         lines.append("_No open roadmaps._\n")
         return "\n".join(lines) + "\n"
@@ -326,6 +368,7 @@ def main() -> int:
     new_text = render(roadmaps)
     current = target.read_text(encoding="utf-8") if target.exists() else ""
     complete = unarchived_complete(roadmaps)
+    pending = pending_iron_law_3(roadmaps)
     if args.check:
         stale = current != new_text
         if stale:
@@ -340,7 +383,14 @@ def main() -> int:
             for r in complete:
                 print(f"      - {r.rel}  ({r.done}/{r.total_active} done)",
                       file=sys.stderr)
-        if stale or complete:
+        if pending:
+            print("❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred "
+                  "items must NOT auto-archive. Resolve via `roadmap-management § 4b` "
+                  "(spawn follow-up, restore, or cancel):", file=sys.stderr)
+            for r in pending:
+                print(f"      - {r.rel}  ({r.done}/{r.total_active} done · "
+                      f"{r.deferred} deferred)", file=sys.stderr)
+        if stale or complete or pending:
             return 1
         print(f"✅  {target.relative_to(args.repo_root)} is up to date.")
         return 0
@@ -353,6 +403,12 @@ def main() -> int:
               "`agents/roadmaps/archive/`:", file=sys.stderr)
         for r in complete:
             print(f"      - {r.rel}", file=sys.stderr)
+    if pending:
+        print("⚠️   Iron Law 3 — roadmaps with unresolved `[~]` deferred items. "
+              "Surface them and ask the user (`roadmap-management § 4b`) "
+              "before any archive:", file=sys.stderr)
+        for r in pending:
+            print(f"      - {r.rel}  ({r.deferred} deferred)", file=sys.stderr)
     return 0
 
 

package/.agent-src/skills/command-routing/SKILL.md

@@ -80,10 +80,11 @@ output — surface it as-is. The two flows are mutually exclusive at the
 state-file level: one `.work-state.json` carries one envelope at a
 time, and the engine refuses to switch mid-flight.
 
-A sibling subcommand `./agent-config migrate-state` upgrades a legacy
-`.implement-ticket-state.json` file to the v1 `.work-state.json`
-schema. The wrapper invokes it automatically when the legacy file is
-detected; agents should not bypass the dispatcher.
+Unified `./agent-config migrate` sweeps a legacy
+`.implement-ticket-state.json` file into the v1 `.work-state.json`
+schema as one cleanup step (see `docs/contracts/migrate-command.md`).
+Wrapper invokes it automatically when legacy file is detected;
+agents should not bypass the dispatcher.
 
 ## GitHub API: Replying to PR review comments
 

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

@@ -238,45 +238,145 @@ After the last step of a roadmap is done, check completion status:
    - `[-]` = cancelled (individual item dropped)
 
 3. **Decision rule — `count_open == 0` means the roadmap has no active
-   work left. `[x]`, `[~]`, `[-]` are all finalized states; only `[ ]`
-   blocks closure. "Fertig ist fertig" — deferred and cancelled items
-   don't hold a finished roadmap in the active set.**
-
-   | count_x | count_open | count_deferred / cancelled | Action |
-   |---|---|---|---|
-   | ≥ 1 | 0 | 0 | **Auto-archive** (silent) — pure completion |
-   | ≥ 1 | 0 | ≥ 1 | **Auto-archive** (silent) — done with intentional skips |
-   | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work happened, scope dropped |
-   | ≥ 0 | ≥ 1 | ≥ 0 | **Ask the user** — open work remains |
+   work left. `[x]`, `[-]` are final states. `[~]` deferred items
+   block silent closure — they carry plans 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 follow-up options, wait. Step 4b. |
+   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Scope-drop or deferred-to-later? Same options 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}`
 
-   The deferred/cancelled items remain searchable inside the archived file
-   (grep for `- [~]` / `- [-]` across `archive/`); a future revival opens a
-   new roadmap that cites the archived one.
+   `[-]` cancelled items remain searchable in archived file — they were
+   explicit drops. `[~]` deferred items, by contrast, may not silently
+   follow file into archive: they represent work user planned and would
+   lose track of. Step 4b is the gate.
 
-4. **If any items are `[ ]`:** → **Ask the user.** Show what's incomplete:
+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_skip}  — {list of deferred items, 1 line each}
-     ❌  Cancelled: {count_cancel} — {list of cancelled 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
+   > 3. Mark open items as deferred [~] and archive (triggers Iron Law 3 flow)
    > 4. Skip — move to skipped/ (no meaningful work done, not pursuing)
    ```
 
-   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.
+   Option 4 only appropriate when `count_x == 0` or completed items were
+   trivial (e.g. prerequisites). If user picks 4 despite meaningful work
+   done, confirm once — archive usually right. Picking option 3 does
+   NOT archive immediately — converts open → deferred, re-enters the
+   `count_deferred > 0` branch, which runs step 4b.
+
+4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
+   Archive **blocked** until user resolves deferrals. Surface plan and ask:
+
+   ```
+   📋 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 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
+   >      `> Blocked until <condition>` line in body. Visible in
+   >      dashboard; execution waits on condition.
+   > 3. Keep deferred items in this archive — confirm "no follow-up"
+   >    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" below.
+   Picks 3, 4, or 5 → apply the change in this roadmap; re-evaluate
+   the decision table; archive when gate clears.
+
+### Spawn follow-up from deferred items (procedure)
+
+When user picks option 1 or 2 in step 4b:
+
+1. **Derive slug.** Default `<parent-slug>-followup` (e.g. `road-to-x.md`
+   → `road-to-x-followup.md`). User-supplied slug in picker → use that.
+   Avoid collisions with `agents/roadmaps/` (active + `archive/` + `skipped/`).
+
+2. **Write new file** at `agents/roadmaps/<slug>.md`:
+
+   ```markdown
+   ---
+   complexity: lightweight            # bump if 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 carried-over outcome.>
+
+   ## Context
+
+   This roadmap collects items deferred from
+   [`agents/roadmaps/archive/<parent-slug>.md`](archive/<parent-slug>.md).
+   See parent's archive entry for original rationale.
+
+   ## Prerequisites
+
+   - [ ] Read `AGENTS.md` and parent archive entry.
+   {parent prerequisites still relevant, copied verbatim}
+
+   <!-- Option 2 only — body note, NOT a frontmatter key: -->
+   > Blocked until <condition>. Execution starts when 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 deferred scope}
+   - [ ] All quality gates pass — see `quality-tools`.
+   ```
+
+3. **In parent roadmap** (still in working tree), append a line at
+   bottom (above any final `---`):
+
+   ```
+   <!-- Deferred items migrated to agents/roadmaps/<followup-slug>.md on YYYY-MM-DD -->
+   ```
+
+   Do **not** delete `[~]` lines — keep visible in archived parent so
+   trail stays grep-able. Follow-up carries forward executable copy.
+
+4. **Regenerate dashboard.** Follow-up appears (draft hidden, ready
+   visible) and parent — once moved — drops off.
+
+5. **Archive 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:
 
@@ -351,7 +451,7 @@ The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate
 - Roadmap files go in `agents/roadmaps/` — don't create them in other directories.
 - Don't mark phases complete without running verification (tests, quality checks) — the verify-before-complete rule applies.
 - The model tends to skip phases it deems "simple" — every phase must be explicitly completed.
-- Auto-archive only when ALL checkboxes are `[x]`. Even one `[~]` or `[-]` requires user confirmation.
+- Auto-archive is allowed when `count_open == 0` AND `count_deferred == 0`. `[-]` cancelled items archive silently (explicit drops). `[~]` deferred items **block** silent archive — they trigger the Iron Law 3 flow (see step 4b).
 - `archive/` and `skipped/` are distinct — `archive/` = work happened, `skipped/` = no meaningful work, not pursuing. Create either directory if it doesn't exist.
 - Use `git mv` (not `mv`) so history follows the file.
 

package/.agent-src/skills/roadmap-writing/SKILL.md

@@ -99,6 +99,69 @@ phase is done) and **rollback** (what to revert if the phase fails).
 A phase without exit criteria is open-ended; a phase without
 rollback assumes success.
 
+### 6. Step-marker semantics — pick `[~]` (defer) vs `[-]` (cancel) honestly
+
+Difference carries load when authoring (and especially when rewriting
+mid-flight):
+
+| Glyph | Semantic | When to use |
+|---|---|---|
+| `[~]` | **deferred** — planned, will be done, just not in this roadmap | Scope-cut + clear intent to revisit. Triggers Iron Law 3 follow-up flow before archive — info preservation enforced. |
+| `[-]` | **cancelled** — won't be done at all | Scope rejected, design changed, replaced by another roadmap. Decision final; no follow-up implied. |
+
+Optional inline annotations on same line:
+
+```markdown
+- [~] Migrate bulk-import job to chunked dispatch. <!-- deferred: ops capacity in Q3 -->
+- [-] Wire SQS retry topic. <!-- cancelled: superseded by Lambda DLQ in road-to-event-bridge -->
+```
+
+Annotation for next human reader (and for migration procedure when
+[`roadmap-management`](../roadmap-management/SKILL.md) spawns a follow-up).
+Bare `[~]` / `[-]` allowed; annotated preferred.
+
+### 7. Follow-up roadmaps spawn from deferred items — frontmatter shape
+
+When parent roadmap closes with `[~]` items,
+[`roadmap-management`](../roadmap-management/SKILL.md) skill spawns a
+follow-up. Authors and reviewers must recognise the shape:
+
+```markdown
+---
+complexity: lightweight
+status: draft                      # optional — draft hides from dashboard
+parent_roadmap: <parent-slug>      # back-link to archived source
+---
+
+# Roadmap: Follow-up to <parent-title>
+
+> <One sentence: carried-over outcome.>
+
+## Context
+
+This roadmap collects items deferred from
+[`agents/roadmaps/archive/<parent-slug>.md`](../archive/<parent-slug>.md).
+{ … original phases preserved verbatim … }
+
+<!-- For option 2 (ready + blocked), add as body note, NOT in frontmatter: -->
+> Blocked until <condition>. Execution starts when condition clears.
+```
+
+Two states author picks between (mirrors Iron Law 3 numbered-options
+block in [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
+
+- **`status: draft`** → hidden from `agents/roadmaps-progress.md` until
+  flipped. Use for items user wants captured but not surfaced to
+  active backlog yet.
+- **`status: ready` (default; omit key)** plus body `> Blocked until …`
+  note → visible in dashboard, execution gated by documented
+  condition. Blocking is body convention, not enforced by dashboard
+  generator — readers honor the note.
+
+Follow-up is **not** authored from scratch — deferred steps copied
+verbatim (with phase context). Preserves plan exactly as author
+originally wrote it.
+
 ## Output format
 
 A single Markdown file at `agents/roadmaps/{name}.md`: