@event4u/agent-config 1.13.0 → 1.14.0

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

@@ -7,22 +7,29 @@ source: package
 
 # Roadmap Progress Sync
 
-## Rule
+## Iron Law
 
-**CRITICAL — ZERO TOLERANCE:** Whenever you change checkbox state in a
-roadmap file (`agents/roadmaps/*.md`, module or package equivalents)
-you MUST regenerate the dashboard **in the same response** — not
-later, not batched across sessions, not "at the end of the roadmap".
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+A ROADMAP NOT IN THE DASHBOARD IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+**Roadmap touch =** create file, rename, delete, move between
+`roadmaps/` ↔ `archive/` ↔ `skipped/`, add/rename/remove phase,
+**OR** flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`).
 
-`agents/roadmaps-progress.md` is the read-only dashboard. Every
-unsynced edit makes it lie to the next reader.
+`agents/roadmaps-progress.md` is read-only dashboard. Every unsynced
+edit lies to next reader. Created roadmap, no regen → dashboard
+claims it does not exist. Marked 8 steps `[x]`, forgot regen →
+dashboard says 0 done.
 
-**Completion = archival, same response.** When the edit takes a
-roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
-`git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no
-`[x]` at all) **before** regenerating. A 100%-complete roadmap left
-in `agents/roadmaps/` is a rule violation. See `roadmap-management`
-for the archive vs skipped decision table.
+**Completion = archival, same response.** Edit takes roadmap to
+`count_open == 0` (every item `[x]`, `[~]`, or `[-]`) → `git mv` to
+`agents/roadmaps/archive/` (or `skipped/` if no `[x]` at all)
+**before** regen. 100%-complete roadmap left in `agents/roadmaps/`
+is rule violation. See `roadmap-management` skill for archive vs
+skipped table.
 
 ## How to regenerate
 
@@ -30,38 +37,104 @@ for the archive vs skipped decision table.
 ./agent-config roadmap:progress
 ```
 
-The `./agent-config` wrapper is written into the project root by the
-installer and delegates to the master CLI inside
-`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
-No global tooling required.
+`./agent-config` wrapper sits in project root, written by installer,
+delegates to master CLI in `node_modules/@event4u/agent-config/` or
+`vendor/event4u/agent-config/`. No global tooling.
 
 ## Triggers
 
 | Edit | Must run, same response |
 |---|---|
+| **Create new roadmap file** | regenerate dashboard |
+| **Rename or delete roadmap file** | regenerate dashboard |
 | Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | regenerate dashboard |
-| Add, rename, or remove a phase | regenerate dashboard |
-| Create a new roadmap file | regenerate dashboard |
+| Add, rename, or remove phase | regenerate dashboard |
 | **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
 | Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
 
-**Batching:** multiple checkbox edits in one response → a **single**
-regeneration at the end is enough. If one closes a roadmap, archive
-it first, then run the single regen. But the response must not end
-without it.
+**Batching:** multiple checkbox edits in one response → **single**
+regen at end is enough. One edit closes a roadmap → archive first,
+then single regen. Response must not end without it.
+
+## Autonomous execution — checkbox cadence
+
+Autonomous roadmap run (multi-turn, no per-step user prompt) → user
+loses progress unless checkboxes flip **as work lands**, not at end.
+Iron Law:
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] IN NEXT REPLY THAT ACKNOWLEDGES IT.
+NO "I UPDATE ROADMAP AT END OF PHASE."
+NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
+```
+
+Step counts as done when:
+
+- Code / docs change for step **written and saved** AND
+- Verification cited in step (project CI command, targeted test, lint) **passed
+  in this response or earlier** — fresh output, not memory.
+
+Then in **same reply**: flip checkbox, regen dashboard, commit if
+commit policy allows.
+
+**Forbidden pattern** (canonical failure):
+
+> Turn 1: Step 1. Turn 2: Step 2. Turn 3: Step 3. Turn 4: Step 4.
+> Turn 5: "all done, update roadmap and commit." → user spent four
+> turns without dashboard movement.
+
+**Required pattern:**
+
+> Turn 1: Step 1, flip `[x]`, regen, commit.
+> Turn 2: Step 2, flip `[x]`, regen, commit. …
+
+Reply that lands verified step without flipping checkbox = rule violation.
+
+**In-progress marker:** step takes more than one reply → mark `[~]`
+moment work starts, regen. User sees row move `[ ]` → `[~]` → `[x]`
+instead of silent rows. `[~]` open for `count_open` but moves phase
+percentage forward.
+
+## Pre-send self-check — MANDATORY
+
+Before sending any reply that touched `agents/roadmaps/`, silent gate:
+
+1. Did this turn create, rename, delete, or move a roadmap file? → regen MUST be in reply.
+2. Did this turn flip any checkbox in a roadmap file? → regen MUST be in reply.
+3. Did the regen output (`✅ Wrote agents/roadmaps-progress.md · …`) actually appear this turn? → no → run it now before sending.
+4. **Autonomous roadmap execution gate** — did this turn complete a roadmap step (code saved + verification passed) without flipping its checkbox? → flip `[x]` (or `[~]` if multi-turn) and regen before sending.
+
+Any "yes" + no regen run = rule violation. Rerun before sending.
 
 ## Why this is a rule, not a skill tip
 
-The `roadmap-management` skill documents the command in several
-places, but skill body text is easy to miss under procedure pressure.
-A rule collapses the constraint into one line the model cannot skip:
-"checkbox edit → regenerate dashboard — same response".
+`roadmap-management` skill documents command in several places, but
+skill body text easy to miss under procedure pressure. Rule collapses
+constraint into one line model cannot skip: "checkbox edit →
+regenerate dashboard — same response".
 
 ## Do NOT
 
 - Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
 - Do NOT defer regen to "next commit" or "before push" — same response.
 - Do NOT rely on CI (`--check` mode) as first line of defence — CI is last-line, not real-time.
-- Do NOT skip regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
-- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — archive same response, ask the user afterwards if needed, not before.
-- Do NOT regenerate the dashboard before the `git mv` when a roadmap closes — otherwise it reappears in "Open roadmaps".
+- Do NOT skip regen because "only one checkbox changed" — dashboard aggregates counts and phase percentages that shift on single edits.
+- Do NOT leave 100%-complete roadmap in `agents/roadmaps/` "for review" — archive same response, ask user afterwards if needed.
+- Do NOT regenerate dashboard before `git mv` when roadmap closes — otherwise it reappears in "Open roadmaps".
+
+## Failure modes
+
+- **Created roadmap, marked Phase 1 done across multiple turns,
+  never regenerated** — dashboard silently lies "this roadmap does
+  not exist" to next reader. Canonical failure of this rule; rule
+  hardened in response to it.
+- **Regenerated yesterday, edited today, "regen at session end"** —
+  session ends from crash, regen never lands.
+- **Closed roadmap (last `[ ]` → `[x]`) and regenerated before
+  `git mv`** — closed roadmap reappears in "Open roadmaps".
+- **Edited dashboard by hand to "fix it quickly"** — next regen
+  overwrites manual edit; no audit trail.
+- **Autonomous run, four steps shipped across four turns, dashboard
+  flat whole time, single regen at end** — user lost progress
+  visibility for entire run. Each done step must flip checkbox in
+  reply that ships it.

package/.agent-src/rules/scope-control.md

@@ -18,7 +18,11 @@ source: package
 
 ## Git operations — permission-gated
 
-The user decides the git shape of the work.
+The user decides the git shape of the work. Never improvise.
+
+> **Commit specifics:** see [`commit-policy`](commit-policy.md) — narrower
+> than the general "no git ops without permission" below (never-ask
+> default + roadmap-authorized exception).
 
 - NEVER commit, push, merge, rebase, or force-push without explicit user permission.
 - NEVER create, switch, or delete a branch without explicit user permission.
@@ -26,6 +30,12 @@ The user decides the git shape of the work.
 - NEVER create, close, reopen, or retarget a pull request without explicit
   user permission.
 - NEVER push a tag or create a release without explicit user permission.
+- NEVER include version numbers, releases, deprecation dates,
+  release-tied milestones, or git tags in roadmaps, plans, tickets, or
+  any planning artifact. Roadmaps plan **work**; releases are a
+  separate user decision. Never surface "which release" as a numbered
+  option, ADR field, or roadmap entry. If user wants a release pinned
+  to a milestone, they say so explicitly.
 - If a task seems to need a separate branch or PR, STOP and **brief
   first, ask second**. The brief MUST cover, in order:
   1. **Why** — what the new branch solves that the current one cannot.
@@ -38,3 +48,34 @@ The user decides the git shape of the work.
 "Explicit permission" = the user said so this turn or gave a standing
 instruction they have not revoked. Earlier permission for another op
 does not carry over.
+
+## Production, infrastructure, bulk-destructive — Hard Floor
+
+Subset of the above is **never** autonomous and never auto-permitted
+by a standing autonomy directive. Canonical rule:
+[`non-destructive-by-default`](non-destructive-by-default.md).
+Restated so this file remains the single read for git/scope concerns:
+
+- **Production-branch merges** — `main`, `master`, `prod`, `production`, `release/*`, or any deployment-trunk branch. Always ask, even when the roadmap step says "merge".
+- **Deploys / releases** — `terraform apply` / `kubectl apply` on prod, deploy scripts, release commands, tag pushes that trigger CI deployment. Always ask.
+- **Production data / infrastructure** — prod DB writes / migrations, prod config edits, secrets rotation, IAM / role / policy, DNS, anything in a `prod`-scoped path or pipeline. Always ask.
+- **Bulk-destructive ops** — wildcard or directory deletion (`rm -rf <dir>`, `git rm -r`), `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work, mass class / module / migration deletion. Always ask.
+
+A roadmap step or earlier turn does **not** count as authorization for
+these. Authorization is "the user said so on this turn".
+
+## Decline = silence — no re-asking on the same task
+
+After a declined proposal (branch switch, PR, tag/release entry,
+worktree, version pinning in a roadmap), do **not** raise it again on
+the same task. Decline stands until user reopens it.
+
+Right moment to ask — at most **once**, only when genuinely useful —
+is **before** work starts (writing roadmap, opening ticket), not
+mid-execution. During roadmap execution the branch question is
+settled; do not resurface it step by step.
+
+A proposal that "might be sensible" is not enough reason to ask.
+Default: stay on current branch, no release language. Only ask with
+concrete evidence-based reason (e.g. risky migration → spike branch).
+If in doubt, do not ask.

package/.agent-src/rules/size-enforcement.md

@@ -24,6 +24,4 @@ source: package
 
 → Size limits and details: `.augment/guidelines/agent-infra/size-and-scope.md`
 
-→ Frontmatter contract (required/optional keys per type):
-[`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md).
-Schemas live in `scripts/schemas/` and are enforced by `python3 scripts/validate_frontmatter.py`.
+→ Frontmatter contract: schemas live in `scripts/schemas/` and are enforced by `python3 scripts/validate_frontmatter.py`.

package/.agent-src/rules/skill-quality.md

@@ -25,10 +25,8 @@ Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `D
 ## Frontmatter Contract
 
 Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
-See [`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md)
-for the human-readable contract across all artefact types. Violations are
-reported by `scripts/skill_linter.py` as `schema_<rule>` errors and fail
-`python3 scripts/validate_frontmatter.py` and the full CI pipeline.
+Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
+and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
 
 ## Description Triggering
 
@@ -47,10 +45,7 @@ Make descriptions "pushy" — explicit about when to fire:
   adjectives, drop the second example phrasing, or collapse a list — do
   **not** drop the trigger vocabulary or the `even if ...` tail.
 
-Source: [`skills/skill-creator` in `anthropics/skills`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
-— description-optimization guidance adopted via
-[`agents/roadmaps/archive/road-to-anthropic-alignment.md`](../../../agents/roadmaps/archive/road-to-anthropic-alignment.md)
-Phase 2.
+Source: [`skills/skill-creator` in `anthropics/skills`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md).
 
 **Litmus test:** Read the description cold, without the skill's body. If you
 cannot name at least two phrasings a user would realistically type that should

package/.agent-src/rules/ui-audit-before-build.md

@@ -0,0 +1,106 @@
+---
+type: "always"
+description: "UI work — never write a component, screen, or partial without existing-ui-audit findings populated in state.ui_audit; the audit is the gate, not a suggestion"
+alwaysApply: true
+source: package
+---
+
+# UI-Audit Before Build
+
+Defense-in-depth twin of the dispatcher gate in
+[`directives/ui/audit.py`](../templates/scripts/work_engine/directives/ui/audit.py).
+The dispatcher refuses to advance past `refine` without
+`state.ui_audit`; this rule refuses the write even when the agent
+acts outside the dispatcher (free-form edit, "add a tile" request,
+side conversation that bypasses [`/work`](../commands/work.md) or
+[`/implement-ticket`](../commands/implement-ticket.md)).
+
+## The Iron Law
+
+```
+NO NEW COMPONENT, SCREEN, PARTIAL, OR PAGE WITHOUT AUDIT FINDINGS.
+EXISTING-UI-AUDIT RUNS FIRST. ALWAYS.
+```
+
+Skipping the audit is the single biggest source of duplicated
+components and drift from project tokens. The audit is cheap (60 s
+on a primed cache); the cost of skipping is a refactor.
+
+## When this rule activates
+
+Before writing or editing any non-trivial UI surface:
+
+- New page / screen / route component
+- New Livewire / Flux / Blade / React / Vue / Svelte component or partial
+- Major edit to an existing screen (new section, new state, new layout band)
+
+Recognise the trigger from wording even when nobody says "audit":
+"add a dashboard tile", "build a settings panel", "neue Komponente
+für …", "render the orders table", "create the empty state for …".
+
+## Allow-list — when to skip
+
+Skip only when **all** hold:
+
+- `directive_set == "ui-trivial"` (set by Phase 1's intent classifier).
+- The change is provably bounded: ≤ 1 file, ≤ 5 changed lines, no
+  new component, no new state, no new dependency.
+
+Any precondition fails at edit time → stop, reclassify as
+`ui-improve`, re-enter the gate. Backend-only edits and
+documentation work were never in scope for this rule.
+
+## What "audit findings" means
+
+`state.ui_audit` is a non-empty dict carrying at least one of:
+
+- `components_found` — `{path, name, kind, similarity?}` inventory
+  entries from [`existing-ui-audit`](../skills/existing-ui-audit/SKILL.md).
+- `greenfield: true` plus `greenfield_decision` ∈
+  `{scaffold, bare, external_reference}`.
+- Legacy `components` alias — back-compat for the same shape.
+
+`null`, `{}`, or a dict without those keys is **not** findings;
+emit `@agent-directive: existing-ui-audit` instead of writing code.
+
+## What to do when the gate fires
+
+1. Stop. Do not open an editor on a component file.
+2. Run [`existing-ui-audit`](../skills/existing-ui-audit/SKILL.md);
+   it writes the result to `state.ui_audit`.
+3. On rebound, the dispatcher enters `design` with the audit as
+   defaults in the design-brief halt.
+4. Greenfield → present the numbered scaffold / bare /
+   external-reference halt **before** code; record the pick in
+   `state.ui_audit.greenfield_decision`.
+
+## Failure modes
+
+- Writing the component first and "thinking about reuse later".
+- Citing a similar-looking component from memory without verifying
+  it via the audit.
+- Treating `state.ui_audit = {}` as "audit ran, found nothing" —
+  empty dict is rejected on purpose; an audit that finds nothing
+  must record either ≥1 `components_found` or the greenfield branch.
+- Bypassing the gate for "just one tile".
+
+## Interactions
+
+- [`improve-before-implement`](improve-before-implement.md) — runs
+  first when the request is ambiguous; this rule is the next gate.
+- [`ask-when-uncertain`](ask-when-uncertain.md) — "just build it"
+  does **not** drop the audit; acknowledge, run audit, continue.
+- [`directives/ui/audit.py`](../templates/scripts/work_engine/directives/ui/audit.py)
+  — code-layer twin; this rule covers the cases where the engine
+  is not in the loop.
+- [`existing-ui-audit`](../skills/existing-ui-audit/SKILL.md) — the
+  skill that produces the findings.
+
+## Cloud Behavior
+
+On cloud surfaces the engine is not shipped, so `state.ui_audit`
+does not exist. The Iron Law still applies: take the visible
+inventory of files in conversation context as the audit, and
+surface a one-line audit summary in the reply before writing the
+component. The gate is satisfied by an explicit summary, not by
+silently skipping.

package/.agent-src/rules/user-interaction.md

@@ -7,95 +7,127 @@ source: package
 
 # User Interaction
 
-## Numbered Options — Always
-
-When asking the user a question with predefined choices, **always present numbered options**.
-The user should be able to reply with just a number (e.g., `1`) instead of typing a sentence.
+Two Iron Laws govern every reply that contains numbered options. They
+override conversation momentum, brevity, and the urge to defer to the
+user. **Missing a recommendation is a rule violation, not a slip.**
 
-### Format
+## Iron Law 1 — Single-Source Recommendation
 
 ```
-> 1. First option — brief explanation
-> 2. Second option — brief explanation
-> 3. Third option — brief explanation
+EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NUMBER.
+THE OPTION BLOCK STAYS NEUTRAL. THE RECOMMENDATION LINE IS THE ONLY SOURCE OF TRUTH.
+DRIFT BETWEEN OPTION-BLOCK AND PROSE IS STRUCTURALLY IMPOSSIBLE WHEN THE TAG DOES NOT EXIST.
+MISSING RECOMMENDATION = RULE VIOLATION, NOT A SLIP.
 ```
 
-### Rules
+The agent has read the code, the contracts, the trade-offs. Refusing
+to take a position dumps that work back on the user. Take the
+position; be wrong out loud if needed. "Egal, was bevorzugst Du?" /
+"no preference" is NEVER acceptable.
 
-- **Every question with choices** must use numbered options — no exceptions.
-- **Keep options short** — one line each, with a brief explanation after the dash.
-- **Always include a "skip" or "no change" option** when applicable.
-- **Always state a recommendation** — see iron law below.
-- **Use the user's language** for the question and options.
-- **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
+**Format — non-negotiable:**
+
+- Options block stays NEUTRAL — no `(recommended)`, no `(rec)`, no `←`, no bold, no checkmark.
+- Directly after the options block, ONE line, bolded, in the user's language:
+  - English: `**Recommendation: N — <option-name>** — <why>. Caveat: <flip-condition>.`
+  - German:  `**Empfehlung: N — <option-name>** — <warum>. Caveat: <flip-bedingung>.`
+- Other numbers MAY appear later in the prose, but ONLY as caveats
+  (`escalate to 3 if …`, `flip to 1 when …`). NEVER as a primary recommendation.
+- If the agent genuinely cannot pick (rare — true 50/50 with missing data),
+  say what data would break the tie and ask for that instead.
+
+**What does NOT count as a recommendation:**
 
-### Iron Law — ALWAYS recommend
+- "Both work" / "either is fine" / "depends on what you prefer"
+- Listing pros and cons without picking a number
+- "I'd lean towards X" without a reason
+- Hiding behind "you know the project better"
+- Inline `(recommended)` tag with no follow-up `Recommendation: N` line
+
+**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#when-the-user-calls-out-a-language-slip).**
+User calls out a missing or wrong recommendation → acknowledge once
+in the user's language, rewrite the reply with a recommendation,
+ship. No "from now on" promises — only the next reply proves
+compliance.
+
+## Iron Law 2 — Pre-Send Self-Check
 
 ```
-EVERY numbered-option question MUST state which option the agent recommends and WHY.
-"Egal, was bevorzugst Du?" / "no preference" is NEVER an acceptable agent stance.
+EVERY REPLY WITH NUMBERED OPTIONS RUNS THE SELF-CHECK. NO EXCEPTIONS.
+SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
 ```
 
-The user is asking the agent because the agent has read the code, the
-contracts, the trade-offs. Refusing to take a position dumps that work
-back on the user. Take the position; be wrong out loud if needed.
+Before emitting any reply that contains numbered options, scan the
+drafted text:
 
-**Format:**
+1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)` inline next to a numbered option → MUST be **zero**. Found one → rewrite, drop the tag.
+2. Count distinct `Recommendation:\s*N` / `Empfehlung:\s*N` lines (case-insensitive) → MUST be **exactly one**. Zero → add one. Two or more distinct numbers → rewrite, pick one.
+3. The number on the recommendation line MUST exist in the option block.
 
-- Mark the recommended option inline: `1. Do X — short explanation (recommended)`.
-- After the option block, state **WHY** in 1–3 sentences: the trade-off
-  that tips the balance, plus the **caveat** that would flip it.
-- If the agent genuinely cannot pick (rare — true 50/50 with missing
-  data), say what data would break the tie and ask for that instead.
+Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft.md`
+(non-zero exit on any rule above). Self-scan is the primary gate; the
+script is the deterministic safety net for ambiguous cases.
 
-**Example:**
+## Numbered Options — Always
+
+When asking the user a question with predefined choices, **always
+present numbered options**. The user should be able to reply with
+just a number (e.g., `1`) instead of typing a sentence.
+
+### Format
 
 ```
-> 1. Hybrid contract — keys + query (recommended)
-> 2. Key-based — extend the package
-> 3. Semantic — change all call sites
+> 1. First option — brief explanation
+> 2. Second option — brief explanation
+> 3. Third option — brief explanation
 
-I recommend 1: solves the acute consult-flow without a cross-repo PR,
-and the file-fallback stays trivial. Caveat — if hit-rate on the
-concat-shim turns out poor in practice, escalate to 2.
+**Recommendation: 2 — Second option** — <one-sentence reason>. Caveat: <flip-condition>.
 ```
 
-**What does NOT count as a recommendation:**
+### Rules
 
-- "Both work" / "either is fine" / "depends on what you prefer"
-- Listing pros and cons without picking
-- "I'd lean towards X" without a reason
-- Hiding behind "you know the project better" (the agent just researched it)
+- **Every question with choices** must use numbered options — no exceptions.
+- **Keep options short** — one line each, with a brief explanation after the dash.
+- **Always include a "skip" or "no change" option** when applicable.
+- **Always state a recommendation** — Iron Law 1 above.
+- **Use the user's language** for the question and options.
+- **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
 
 ### Examples
 
-**Binary choice (with recommendation):**
+**Binary choice:**
+
 ```
-> 1. Interactive — ask before each comment (recommended)
+> 1. Interactive — ask before each comment
 > 2. Automatic — handle all independently
 
-I recommend 1: the comments touch security-sensitive code, so a wrong
-auto-fix is more expensive than the friction of approving each one.
-Switch to 2 if the comments turn out to be pure formatting.
+**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
+so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
+if the comments turn out to be pure formatting.
 ```
 
-**Multiple choice with skip (with recommendation):**
+**Multiple choice with skip:**
+
 ```
-> 1. Fix the code (recommended)
+> 1. Fix the code
 > 2. Fix the test
 > 3. Skip
 
-I recommend 1: the test is asserting the documented behavior; the
-production code drifted from the contract. Pick 2 only if the contract
+**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
+the production code drifted from the contract. Caveat: pick 2 only if the contract
 itself is wrong.
 ```
 
-**Confirmation with context (recommendation implicit in framing):**
+**Confirmation with context:**
+
 ```
 > Found PR #1399 on branch `chore/refactor-agent-setup-2`.
 >
-> 1. Yes, that's the right PR (recommended — branch matches)
+> 1. Yes, that's the right PR
 > 2. No, different PR — I'll provide the URL
+
+**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
+Caveat: flip to 2 if the PR was reopened from a different branch.
 ```
 
 ### When NOT to use numbered options

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

@@ -73,6 +73,10 @@ class PhaseStats:
     def total_active(self) -> int:  # denominator for %
         return self.done + self.open_
 
+    @property
+    def total_all(self) -> int:  # all checkboxes incl. deferred + cancelled
+        return self.done + self.open_ + self.deferred + self.cancelled
+
     @property
     def percent(self) -> int:
         return round(self.done * 100 / self.total_active) if self.total_active else 0
@@ -117,6 +121,10 @@ class RoadmapStats:
     def total_active(self) -> int:
         return self.done + self.open_
 
+    @property
+    def total_all(self) -> int:
+        return self.done + self.open_ + self.deferred + self.cancelled
+
     @property
     def percent(self) -> int:
         return round(self.done * 100 / self.total_active) if self.total_active else 0
@@ -213,12 +221,16 @@ def render(roadmaps: list[RoadmapStats]) -> str:
         lines.append("_No open roadmaps._\n")
         return "\n".join(lines) + "\n"
     lines.append("## Open roadmaps\n")
-    lines.append("| # | Roadmap | Phases | Steps | Done | Open | Deferred | Cancelled | Progress |")
+    # Steps = ALL checkboxes (done + open + deferred + cancelled) so the row
+    # arithmetic adds up: Steps − Done − Deferred − Cancelled = Open. Open
+    # comes before Done by design — at-a-glance "what's left to do" first,
+    # historical "what's behind us" second.
+    lines.append("| # | Roadmap | Phases | Steps | Open | Done | Deferred | Cancelled | Progress |")
     lines.append("|---|---|---:|---:|---:|---:|---:|---:|---|")
     for i, r in enumerate(roadmaps, 1):
         lines.append(
-            f"| {i} | [{r.rel}](roadmaps/{r.rel}) | {len(r.phases)} | {r.total_active} | "
-            f"{r.done} | {r.open_} | {r.deferred} | {r.cancelled} | "
+            f"| {i} | [{r.rel}](roadmaps/{r.rel}) | {len(r.phases)} | {r.total_all} | "
+            f"{r.open_} | {r.done} | {r.deferred} | {r.cancelled} | "
             f"{bar(r.percent)} {r.percent}% |"
         )
     lines.append("")
@@ -227,11 +239,11 @@ def render(roadmaps: list[RoadmapStats]) -> str:
     for r in roadmaps:
         lines.append(f"### [{r.rel}](roadmaps/{r.rel})\n")
         lines.append(f"**{r.title}** — {r.done} / {r.total_active} done ({r.percent}%)\n")
-        lines.append("| # | Phase | State | Done | Open | Deferred | Cancelled | % |")
+        lines.append("| # | Phase | State | Open | Done | Deferred | Cancelled | % |")
         lines.append("|---|---|---|---:|---:|---:|---:|---:|")
         for p in r.phases:
             lines.append(
-                f"| {p.id} | {p.name} | {p.state} | {p.done} | {p.open_} | "
+                f"| {p.id} | {p.name} | {p.state} | {p.open_} | {p.done} | "
                 f"{p.deferred} | {p.cancelled} | {p.percent}% |"
             )
         lines.append("")