@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -0,0 +1,274 @@
+# Roadmap Progress Sync
+
+> Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response
+
+_Origin: migrated from `.agent-src.uncondensed/rules/roadmap-progress-sync.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+<!-- cloud_safe: degrade -->
+<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
+
+# Roadmap Progress Sync
+
+> **Enforced by (defence in depth):**
+> 1. [`scripts/roadmap_progress_hook.ts`](../../../src/scripts/roadmap_progress_hook.ts)
+>    on Augment + Claude Code (`PostToolUse`) — auto-regen on write.
+> 2. `.git/hooks/pre-commit` (installed by `scripts/install-hooks.sh`) —
+>    blocks any commit whose staged set touches `agents/roadmaps/` or
+>    `agents/roadmaps-progress.md` while the dashboard is stale.
+> 3. The `ci` task runs `roadmap-progress-check` so a PR cannot land with a
+>    stale dashboard even if local hooks were bypassed.
+>
+> Hook is primary; the prose below is the specification the hook
+> implements and the fallback where no hook is bound on the platform.
+
+## Iron Law — dashboard sync
+
+```
+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 the file, rename it, delete it, move it
+between `roadmaps/` ↔ `archive/` ↔ `skipped/`, add/rename/remove a
+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. Created a roadmap
+without regenerating? The dashboard claims it does not exist. Marked
+8 steps `[x]` and forgot the regen? The dashboard says 0 done.
+
+## Iron Law — every active roadmap is trackable
+
+```
+EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
+(`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
+EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
+CI-ENFORCED: `scripts/check_roadmap_trackable.ts` (CANNOT BE DEFERRED).
+```
+
+**Active roadmap =** any file in `agents/roadmaps/` (root, not
+`archive/` or `skipped/`) without `status: draft` frontmatter.
+
+**Trackable checkbox =** an actionable `- [ ]` line under a `## Phase N`
+or `### Phase N` heading (numeric `Phase 1`, roman `Phase II`, or
+letter-track `Phase A1` — matched by the dashboard's `PHASE_RE`).
+Tables of decisions, ICE matrices, ADR captures, and "block
+sequencing" tables are valid **rationale**, but they do not satisfy
+this rule on their own — they must be paired with at least one
+`## Phase N` section whose checkboxes execute the decision.
+Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
+`### P0 #1 — …`, or `## Block A` do **not** count — only the
+canonical `Phase <id>` form parsed by the dashboard.
+
+**CI backstop.** `scripts/check_roadmap_trackable.ts` (package-shipped,
+wire into the consumer's pre-commit / pre-push / Actions gate) fails
+when an active roadmap has zero canonical `Phase` headings or when
+any parsed phase has zero checkboxes. Last line of defence — real-time
+authoring still flips checkboxes and regenerates the dashboard the
+same response.
+
+## Status — binary `ready` (default) vs `draft`
+
+```yaml
+---
+status: draft          # hidden from the dashboard until flipped
+---
+```
+
+Two values, no synonyms. Anything else — no frontmatter at all,
+`status: ready`, an unknown value — counts as **ready** and lands
+in the dashboard.
+
+- **Ready** is the implicit default. New roadmaps are created
+  ready unless the user explicitly says draft. Ready roadmaps are
+  listed in the dashboard, count towards open/done totals, and
+  trip the "completed but not archived" warning when they close.
+- **Draft** hides the file from the dashboard entirely (not
+  counted, not listed). Use it while the roadmap is still being
+  authored, while waiting for upstream decisions, or as a
+  capture-only synthesis that has not yet been promoted to
+  executable phases. Flip to ready (or remove the field) the
+  moment the roadmap is ready to track.
+
+**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 the dashboard. A 100%-complete
+roadmap left under `agents/roadmaps/` is a rule violation, not an
+optional cleanup. See `roadmap-management` skill for the archive vs
+skipped decision table.
+
+## Agent-authored roadmaps — placement is mandatory
+
+```
+A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
+(a) PASS check_roadmap_trackable.ts AND LAND IN THE DASHBOARD, OR
+(b) NOT BE IN agents/roadmaps/ AT ALL.
+NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
+```
+
+When the agent autonomously creates a roadmap, it owns the placement
+in the **same response**:
+
+- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/settings/contexts/<name>.md`.
+- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
+
+A non-trackable file in `agents/roadmaps/` is a rule violation — the
+trackable CI fails it, the dashboard hides it. The agent that
+created it moves it the same response. If the autonomous run also
+**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
+the completion-archival rule above fires too — same response.
+
+## Autonomous execution — checkbox cadence
+
+When executing a roadmap autonomously (multi-turn, no per-step user
+prompt), the user loses progress visibility unless checkboxes flip
+**as work lands**, not in a batch at the 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 completed when:
+
+- Code / docs change for that step has been **written and saved** AND
+- Verification cited in the step (project CI command, targeted test, lint) has
+  **passed in this response or an earlier one** — fresh output, not memory.
+
+Then in the **same reply**: flip the checkbox, regenerate the
+dashboard, commit if commit policy allows.
+
+**Forbidden:** four turns of step work, dashboard flat, single regen at the end.
+**Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
+A reply that lands a verified step without flipping its checkbox is a rule violation.
+
+**Deterministic flip-guard.** The autonomous loop carries a per-step
+guard at [`roadmap-process-loop § 5b`](../../contexts/execution/roadmap-process-loop.md#5b-flip-guard--deterministic):
+after the atomic flip, the loop runs
+`git diff --name-only -- agents/roadmaps/<file>.md` and halts loudly
+when the diff is empty. The `command:` triggers on
+`roadmap-progress-sync` keep the rule loaded for the entire
+`/roadmap:process-*` run; the guard is the deterministic backstop
+that catches a forgotten flip per step rather than at run end.
+
+**`[~]` semantics — superseded note:** `[~]` is **not** an "in-progress"
+indicator (the earlier in-progress-marker guidance here is superseded by
+the glyph table in § Glyph semantics below — kept as the stronger, current
+source of truth). Mid-reply work-in-flight has no checkbox change until
+the step lands; that's a normal `[ ] → [x]` transition.
+
+## Mechanics — triggers, regen command, self-check, failures
+
+The triggers table, the regen command (`./agent-config roadmap:progress`),
+the pre-send self-check, the failure-mode catalog and the `Do NOT` list are
+**in this file**; the rule
+[`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) is the
+obligation surface.
+
+> **Corrected 2026-08-26.** This pointed at a `rules-auto` mechanics file that
+> exists nowhere — a split that never happened, while the content was here.
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/roadmap_progress_hook.ts` cannot detect roadmap-file writes
+structurally. The dashboard at `agents/roadmaps-progress.md` will
+not regenerate on its own.
+
+The cooperative path: every time a roadmap touch fires (per the
+trigger list in the mechanics context above), the agent regenerates
+the dashboard in the same response — which is the same Iron Law the
+hook enforces, just executed manually:
+
+```bash
+./agent-config roadmap:progress
+```
+
+The hook implementation is the specification; on Copilot the agent
+runs the regenerator itself after the same triggers fire. Skipping
+it is a rule violation, not a hook gap — the Iron Law on dashboard
+sync survives the missing hook surface.
+
+## Migrated depth from the `roadmap-progress-sync` rule (per P4)
+
+The sections below carry the long-form body of the
+`roadmap-progress-sync` rule; the Iron-Law fences and the mandatory
+pre-send self-check stay in the rule itself.
+
+### Iron Law 2 — cadence detail
+
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The checkbox itself is the real-time monitor — the markdown file is the source of truth, the dashboard is a derived view.
+
+The `command:` triggers in the rule's frontmatter ensure it loads the moment one of the `/roadmap:process-*` commands is invoked and stays loaded for the whole run — independent of whether the agent is currently editing files under `agents/roadmaps/`. The loop carries its own deterministic flip-guard at `roadmap-process-loop § 5b` — defense-in-depth, not a substitute for the inline flip. (Merged with § Autonomous execution → "Deterministic flip-guard" above, which carries the concrete guard command.)
+
+**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). (Merged with § Autonomous execution → "Step counts as completed" above — same contract.)
+
+### Glyph semantics — single source of truth
+
+Keep aligned with the dashboard counter in `scripts/update_roadmap_progress.ts` (regenerated via `./agent-config roadmap:progress`) and the closure-table in the `roadmap-management` skill:
+
+| Glyph | Meaning | Counts towards |
+|---|---|---|
+| `[ ]` | open — planned, not yet done | `count_open` |
+| `[x]` | done — work landed + verified | `count_done` |
+| `[~]` | deferred — planned but not happening **this** run; resolution required before archive (Iron Law 3) | `count_deferred` |
+| `[-]` | cancelled — scope dropped, won't happen at all | `count_cancelled` |
+
+`[~]` is **not** an "in-progress" indicator. Mid-reply work-in-flight has no checkbox change until the step lands; that's a normal `[ ] → [x]` transition.
+
+#### `guarded-baseline` — a sub-state of `[ ]`, never a fifth glyph
+
+See [`guarded-baseline`](guarded-baseline.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` (`every_5_steps` default · `per_step` · `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.
+
+**Blockers follow the same cadence as checkboxes.** Clearing a `## Blockers` entry (per `templates/roadmaps.md` rule 20) flips its `Status: resolved` and regenerates the dashboard in the same reply — Iron Law 1's "same response" obligation applies to blocker resolution exactly as it applies to a checkbox flip.
+
+### Iron Law 3 — deferred-resolution flow
+
+When the closure check fires (`count_open == 0` and `count_deferred > 0`), the agent MUST:
+
+1. Enumerate every `[~]` step in the roadmap (phase + step text + any inline `<!-- deferred: ... -->` annotation).
+2. Present numbered options (per the `user-interaction` rule) — at minimum:
+   1. **Follow-up roadmap (draft)** — spawn `agents/roadmaps/road-to-<slug>.md` with `status: draft` frontmatter, `parent_roadmap: <this-slug>`, and the deferred steps lifted verbatim into phases. Draft stays hidden from the dashboard until the user flips it to `ready`.
+   2. **Follow-up roadmap (ready, blocked)** — spawn the file with `status: ready` (default), frontmatter `parent_roadmap: <this-slug>` plus a body note (`> Blocked until <condition>`) so the dashboard surfaces it but execution waits.
+   3. **Keep in this archive** — confirm the deferred items stay searchable in the archived file; no follow-up roadmap. Choosing this records an explicit decision-to-drop in the same reply.
+   4. **Restore selected items to `[ ]`** — finish them in this roadmap before archive.
+   5. **Convert selected items to `[-]` cancelled** — drop them with rationale recorded inline.
+3. Route by the **preservation test** — full table, recording contract and residual limit in [`roadmap-progress-sync § Who resolves it`](../../rules/roadmap-progress-sync.md). In one line: options 1, 2, 4 keep the item alive → council; 3 and 5 drop or weaken it → user, always; in doubt, user.
+4. Only after the deferrals are resolved does the `git mv` to `archive/` run. The dashboard regen happens after the resolution, not before.
+
+The migration mechanics (file naming, frontmatter pattern, body shape, parent-back-link) live in `roadmap-management § Spawn follow-up from deferred items`. The rule owns the obligation; the skill owns the procedure.
+
+### Later disposition — detail
+
+`later/` is the fourth disposition alongside `archive/` (done, none planned) and `skipped/` (won't pursue): open work remains but is blocked-for-later. Set frontmatter `status: later` + a `Blocked until` / `Trigger` resume line, `git mv` to `agents/roadmaps/later/`, migrate inbound `agents/roadmaps/<x>.md` refs to the new path, regen. Open `[ ]` items stay open — the roadmap is parked whole, not cancelled or deferred-item-by-item. `later/` is excluded from the dashboard and `/roadmap:process-*` (same as `archive/`/`skipped/`); the `lint_roadmap_later_disposition` guard enforces the `status: later` ⇔ `later/` placement contract and that every parked roadmap records a resume condition. Procedure + the Active-vs-Later test live in the `roadmap-management` skill.
+
+### PR-gate — detail
+
+A roadmap that reaches `count_open == 0 && count_deferred == 0` is **complete**
+and is archived **in the same PR that completes it** — deterministically, by a
+script, before the PR exists. There is no "hold the last item open + archive
+manually after merge" step (that step got forgotten and left finished roadmaps
+rotting unarchived in the trunk — the exact failure this gate makes impossible).
+
+The sweep — `scripts/archive_completed_roadmaps.ts`, invoked by
+`/create-pr` § 1c — archives every roadmap that is
+complete **and** touched in this branch (`git log origin/main..HEAD`), `git mv`s
+it to `archive/`, migrates inbound `agents/roadmaps/<x>.md` references to the
+archive path in the **same branch** (so links never break — this was the only
+real reason the old design deferred archival), regenerates the dashboard, and
+stages it. Completion is read from the checkbox counts; no marker is required.
+
+**Backstop:** `./agent-config roadmap:progress-check` (wrapping `update_roadmap_progress.ts --check`) hard-fails when a roadmap
+hits `count_open == 0` while still under `agents/roadmaps/`. Because
+`/create-pr` archives before the push, the PR branch is green; a push that
+bypasses the sweep red-flags in CI — the forcing function that makes
+"finished roadmap left unarchived in the trunk" structurally impossible. Legacy
+`merge-gated` annotations are archived by the next `/create-pr` like any other
+completed roadmap; the dashboard still surfaces any stranded
+complete-but-unarchived roadmap so it can never hide inside a partial progress bar.

package/dist/agent-src/guidelines/agent-infra/role-contracts.md

@@ -0,0 +1,209 @@
+# Role Contracts
+
+Six named working modes with a fixed output contract per mode. Loading
+a role frame stabilizes smaller models: they stop inventing a frame per
+task and produce reproducible outputs on the same input.
+
+Referenced by `road-to-role-modes.md` Phase 1. Each contract is a
+*skeleton*, not a form — fields without evidence become questions via
+`ask-when-uncertain`, never fabrications.
+
+## The six modes
+
+| Mode | Entry signal | Default skills | Output contract |
+|---|---|---|---|
+| **Developer** | "implement X", `/jira-ticket`, `/bug-fix` | `php-coder`, `laravel`, `test-driven-development`, `quality-tools` | Goal / Plan / Changes / Tests / Open questions |
+| **Reviewer** | `/review-changes`, `/judge`, PR open on branch | `judge-bug-hunter`, `judge-code-quality`, `judge-security-auditor`, `judge-test-coverage` | Summary / Risks / Findings / Required actions / Verdict |
+| **Tester** | "add tests", "why does X fail", test output in context | `pest-testing`, `api-testing`, `e2e-plan`, `test-performance` | Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps |
+| **PO** | "I want a feature", `/feature-explore`, `/feature-plan` | `validate-feature-fit`, `api-design`, `threat-modeling` | Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder |
+| **Incident** | "production is down", `break-glass: true`, hotfix branch | `bug-investigate`, `systematic-debugging`, `authz-review` | Symptom / Reproduction / Minimal reversible change / Deferred verification / Follow-up commitment / Incident learning |
+| **Planner** | "what's the strategy", `/feature-roadmap`, multi-step work with unclear order | `feature-plan`, `feature-roadmap`, `blast-radius-analyzer` | Goal / Constraints / Option set / Recommendation / Dependencies / Rollback |
+
+## Contract skeletons
+
+### Developer
+
+```
+**Goal:** <what the user asked for, one sentence>
+**Plan:** <ordered steps, ≤5>
+**Changes:** <files touched, one line each>
+**Tests:** <added/updated tests + how to run>
+**Open questions:** <unresolved items, none if blank>
+```
+
+### Reviewer
+
+```
+**Summary:** <one-paragraph overview of the diff>
+**Risks:** <ranked list: high/medium/low>
+**Findings:** <file:line → issue → fix suggestion>
+**Required actions:** <numbered list the author must address>
+**Verdict:** approve | request changes | block
+```
+
+### Tester
+
+```
+**Behaviour under test:** <the invariant, one sentence>
+**Edge cases:** <boundary + error paths covered>
+**Negative paths:** <expected failures, error types>
+**Reproduction:** <how to run a single failing case>
+**Coverage gaps:** <what stayed untested and why>
+```
+
+### PO
+
+```
+**Goal:** <user-facing outcome>
+**Assumptions:** <each marked `verify with: {name}` if unconfirmed>
+**Acceptance criteria:** <testable, numbered>
+**Impacted modules:** <paths, not speculation>
+**Risks:** <business + technical>
+**Open questions for stakeholder:** <blocking decisions only>
+```
+
+### Incident
+
+```
+**Symptom:** <what users see, not the hypothesis>
+**Reproduction:** <minimal steps or "not reproduced">
+**Minimal reversible change:** <the smallest fix>
+**Deferred verification:** <what was skipped under break-glass>
+**Follow-up commitment:** <PR/ticket for full verification, due date>
+**Incident learning:** <intake signal id, OR `/memory-add incident-learnings` draft ref>
+```
+
+**Memory-write is the final field, not a nice-to-have.** Before the
+mode exits, the agent MUST either emit an intake signal via
+[`memory-access`](memory-access.md) (`scripts/memory_signal.ts`
+append — one line, fire-and-forget) or draft a curated entry with
+[`/memory-add incident-learnings`](../../../src/domains/meta/memory/add/command.md).
+Pattern + consequence + guardrail, redacted. Skipping this field
+means the incident did not produce a learning — log the absence,
+do not pretend verification happened.
+
+### Planner
+
+```
+**Goal:** <target state, one paragraph>
+**Constraints:** <hard limits: time, deps, policy>
+**Option set:** <2-4 options with trade-offs>
+**Recommendation:** <which option + one-line justification>
+**Dependencies:** <what must ship first>
+**Rollback:** <how to revert if it fails>
+```
+
+## Integration rules
+
+- **`ask-when-uncertain`** — any contract field without evidence becomes
+  a question, not a guess. The contract does not license fabrication.
+- **`scope-control`** — `Reviewer` mode forbids implementation work.
+  `Developer` mode forbids producing review verdicts on own code.
+  `PO` mode forbids committing to absent stakeholders' decisions.
+- **`preservation-guard`** — no mode justifies rewriting or removing
+  existing skills. Modes *compose* skills, they do not replace them.
+- **`verify-before-complete`** — the final field of every contract is
+  an evidence field (Tests, Verdict, Reproduction, Acceptance criteria,
+  Deferred verification, Rollback). No mode ships without it.
+
+## When to load a contract
+
+- **Explicit**: user invokes a command in the entry-signal column.
+- **Inferred**: first message matches a signal — surface one line
+  (`> entering {mode} mode — contract: {fields}`) and continue.
+- **Overridden**: user says "no mode" or invokes `/mode none` — drop
+  the frame and fall back to default conversation.
+
+## Structured mode markers
+
+Every contract output MUST begin with a one-line HTML comment so
+session captures, log scrapers, and the measurement hook can count
+contract-conformant outputs per mode:
+
+```
+<!-- role-mode: developer | contract: goal,plan,changes,tests,open-questions -->
+```
+
+The marker is:
+
+- **Invisible** in rendered markdown — no UI noise.
+- **Greppable** with a stable prefix (`role-mode:`).
+- **Self-describing** — `contract:` lists the fields in kebab-case and
+  in the order they must appear, so a scraper can verify conformance
+  without hardcoding the mode→contract map.
+
+Reserved values for `role-mode`:
+
+- `developer` · `reviewer` · `tester` · `po` · `incident` · `planner`
+
+Any other value is treated as non-conformant. A reply with no marker
+counts as the default "no-mode" conversation and does not feed the
+mode statistics.
+
+## Personas (advisory pairings)
+
+Modes own the **workflow closing contract**. Personas own the
+**voice** a skill brings to the work. They compose: a skill invoked
+inside a mode can cite one or more personas to shape *how* it
+reviews, reasons, or pushes back — without changing the mode's
+output contract.
+
+This table is **advisory**, not enforcing. A skill may cite any
+persona inside any mode; the mapping below is just the most common
+fit. See [`../../personas/README.md`](../../personas/README.md) for
+the persona catalog and schema.
+
+| Mode | Typical persona companions | Why |
+|---|---|---|
+| **Developer** | `developer`, `ai-agent` | Implementation voice + automation-readiness check on the plan |
+| **Reviewer** | `critical-challenger`, `senior-engineer`, `qa` | Fake-clarity hunt, architectural lock-in, coverage gaps |
+| **Tester** | `qa`, `developer` | Testability lens + implementation-reality sanity check |
+| **PO** | `product-owner`, `stakeholder`, `critical-challenger` | Outcome/AC, business fit, challenge hidden assumptions |
+| **Incident** | `senior-engineer`, `developer` | Smallest reversible change + long-term risk on the hotfix |
+| **Planner** | `senior-engineer`, `stakeholder`, `critical-challenger` | Architecture impact, business framing, option-set honesty |
+
+### Invocation
+
+Skills cite personas in frontmatter:
+
+```yaml
+---
+name: requesting-code-review
+personas: [critical-challenger]
+---
+```
+
+Commands accept a CLI-style override that wins over the skill default:
+
+```
+/refine-ticket --personas=product-owner,senior-engineer,+qa
+```
+
+Prefix `+` adds a persona to the default cast; prefix `-` removes one.
+Omitting `--personas` uses the skill's documented default.
+
+### Conflict resolution
+
+If the active mode forbids an action and a persona would push for
+that action (e.g. Reviewer mode + `developer` persona suggesting an
+implementation fix), the agent surfaces a numbered-options prompt per
+[`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) —
+never silently switches mode, never silently drops the persona
+finding. See the Q4 rule in `road-to-personas.md`.
+
+## Anti-patterns
+
+- **Do NOT** mix two contracts in one reply. If the task shifts
+  (review → fix), close the current contract first with its evidence
+  field, then enter the next mode.
+- **Do NOT** invent fields the contract does not list. The skeleton
+  is the maximum surface, not the minimum.
+- **Do NOT** hand-wave the final evidence field ("tests should pass").
+  Run the verification or mark it as deferred with a follow-up commit.
+- **Do NOT** treat the default-skills list as mandatory. The skills
+  are pre-loaded; the contract decides which get invoked.
+
+## See also
+
+- [`output-patterns.md`](output-patterns.md) — generic output conventions modes inherit
+- [`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) — how modes interact with the numbered-options protocol

package/dist/agent-src/guidelines/agent-infra/role-mode-router.md

@@ -0,0 +1,89 @@
+# Role Mode Router
+
+Maps common entry signals to the correct role mode defined in
+[`role-contracts`](role-contracts.md). The router is advisory —
+it proposes a mode, the user can veto with `/mode none`.
+
+## Entry signal → mode
+
+| Signal pattern | Inferred mode |
+|---|---|
+| "implement X", "add feature", `/jira-ticket`, `/bug-fix` | `developer` |
+| `/review-changes`, `/judge`, "review this PR", PR open on active branch | `reviewer` |
+| "add tests", "why does X fail", test output pasted in context | `tester` |
+| "I want a feature", `/feature-explore`, `/feature-plan`, "what should it do" | `po` |
+| "production is down", `break-glass: true`, hotfix branch, live incident framing | `incident` |
+| "what's the strategy", `/feature-roadmap`, multi-step work with unclear order | `planner` |
+
+The signals are **non-exclusive**. When two patterns match, prefer the
+narrower one (`incident` > `developer`; `reviewer` > `tester`).
+
+## Surfacing the inferred switch
+
+Before doing any work, the agent emits **one line** in the user's
+language (per `language-and-tone`):
+
+```
+> entering {mode} mode — contract: {goal-field} / {constraints-field} / {output-field}
+```
+
+This is the only announcement. Do not narrate the reasoning for the
+mode choice. If the user is silent, proceed; if they reply
+`/mode none` or `/mode <other>`, switch immediately.
+
+## When NOT to infer
+
+- `roles.active_role` is already non-empty in `.agent-settings.yml` —
+  respect the explicit setting; do not second-guess it.
+- `roles.default_role` is set and matches the inferred mode — still
+  surface the announcement (it reassures the user the frame loaded).
+- No signal matches — **do NOT guess**. Stay mode-less and let
+  `ask-when-uncertain` handle the scope question.
+
+## Precedence
+
+1. Explicit `/mode <name>` in the current message — wins absolutely.
+2. `roles.active_role` from `.agent-settings.yml` — sticky within session.
+3. Router inference from the entry signal table above.
+4. `roles.default_role` fallback — only when no signal matches.
+5. No mode — rule `role-mode-adherence` stays inert.
+
+## Veto path
+
+```
+> 1. Switch to {mode-b} — run /mode {mode-b}
+> 2. Stay in {mode-a}
+> 3. Clear mode — run /mode none
+```
+
+The agent MUST use numbered options (per `user-interaction`) and accept
+both the number and the spelled-out slash command.
+
+## Interactions
+
+- [`role-contracts`](role-contracts.md) — the contracts this router targets.
+- [`role-mode-adherence`](../../rules/role-mode-adherence.md) — enforces
+  the contract once a mode is active.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
+  fallback when no signal matches.
+- [`/mode`](../../../src/domains/meta/mode/command.md) — user-facing override.
+
+## Signal table maintenance
+
+The table lives here, not in `role-contracts.md`. Commands and rules
+reference modes by slug only — the routing layer is the single place
+that maps free-form intent to a slug. Add a signal only when:
+
+- ≥3 real sessions in `agents/sessions/` have surfaced the same pattern.
+- The pattern does not collide with an existing row (check neighbours).
+- The inferred mode is one of the six — never invent a seventh.
+
+Signals captured but not yet promoted live in a scratch list at the
+bottom of this file (delete when promoted).
+
+## Scratch list (candidates)
+
+<!-- Add `{signal} → {mode}` lines here; promote to the table above
+     only after the criteria in the previous section are met. -->
+
+_None yet._