@event4u/agent-config 1.15.0 → 1.16.0

package/.agent-src/rules/guidelines.md

@@ -12,7 +12,7 @@ Coding guidelines live in `.augment/guidelines/` organized by language.
 
 ## Available Guidelines
 
-### PHP (`.augment/guidelines/php/`)
+### PHP (`../../docs/guidelines/php/`)
 
 | File | Topic |
 |---|---|
@@ -37,7 +37,7 @@ Coding guidelines live in `.augment/guidelines/` organized by language.
 | `websocket.md` | WebSocket conventions — Broadcasting, channel types, connection management |
 | `patterns.md` | Design patterns index (links to `patterns/` subdirectory) |
 
-### PHP Patterns (`.augment/guidelines/php/patterns/`)
+### PHP Patterns (`../../docs/guidelines/php/patterns/`)
 
 | File | Pattern |
 |---|---|
@@ -51,11 +51,11 @@ Coding guidelines live in `.augment/guidelines/` organized by language.
 | `pipelines.md` | Laravel Pipeline pattern |
 | `strategy.md` | Strategy pattern implementation |
 
-### E2E (`.augment/guidelines/e2e/`)
+### E2E (`../../docs/guidelines/e2e/`)
 
 Playwright best practices, Page Objects, fixtures, CI.
 
-### Agent Infrastructure (`.augment/guidelines/agent-infra/`)
+### Agent Infrastructure (`../../docs/guidelines/agent-infra/`)
 
 | File | Topic |
 |---|---|

package/.agent-src/rules/improve-before-implement.md

@@ -41,10 +41,10 @@ Before coding, quickly verify:
 - Does it follow established patterns in the codebase?
 - Does it contradict existing conventions?
 - Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
-- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`guidelines/php/patterns/strategy.md`](../guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`docs/guidelines/php/patterns/strategy.md`](../../docs/guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
 
 **If misfit** → show evidence (file references), propose alternative.
-**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
 
 ### 3. Is the approach sound?
 

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

@@ -22,36 +22,24 @@ language, codebase language, open-file language, files-just-edited
 language, convenience. First thing to check on every reply, last thing
 to check before sending.
 
-Canonical failure: agent edited English `.md` for many turns; user
-types short German (`3`, `weiter`, `mach das`, `und jetzt X`); agent
-answers English because momentum wins. **Trigger is the user's last
-message, not the turn count.** Length irrelevant — `3` after a German
-question still means German continues.
+Trigger is the user's last chat message, not turn count or message
+length — short German (`3`, `weiter`, `mach das`) after many English
+turns still flips the reply to German.
 
 ### Source of language truth — chat messages ONLY
 
-```
-THE LANGUAGE SIGNAL IS THE USER'S CHAT MESSAGES. NOTHING ELSE.
-OPEN FILES, ROADMAPS, .md CONTENT, TOOL OUTPUT, CODE, COMMIT MESSAGES,
-TICKETS, PR DESCRIPTIONS, FILE NAMES — NONE OF THEM COUNT.
-```
-
-`.md` files in this repo are English by rule (see below) — that says
-nothing about chat language. Same for: file contents read via `view` /
-`grep`, quoted commits / tickets / PRs / branches, code identifiers,
-the agent's own previous replies. Only the most recent **chat message**
-sets the language. User opens an English roadmap and types German →
-reply in German.
+Only the most recent **chat message** sets the language. `.md` files,
+file contents read via `view` / `grep`, quoted commits / tickets / PRs,
+code identifiers, and the agent's own previous replies do **not** count.
+User opens an English roadmap and types German → reply in German.
 
 ### Pre-send gate — MANDATORY before every reply
 
 Run silently **before** emitting any tokens:
 
 1. **Detect** — language of user's last **chat message** (not the open
-   file, not the roadmap, not the prior reply).
-   German signals: "ich", "Du", "nicht", "warum", "wie", "ist", umlauts. <!-- md-language-check: ignore -->
-   English signals: "I", "you", "is", "the", "how".
-   Mixed → mirror the **dominant** language; tie → German wins (project default).
+   file, not the roadmap, not the prior reply). Mixed → mirror the
+   **dominant** language; tie → German wins (project default).
 2. **Check** — is drafted prose (not code, not file contents) in that language?
 3. **Rewrite** — if no, rewrite whole prose before sending. No exceptions, no
    "just this sentence", no "the technical term is English anyway".
@@ -74,28 +62,15 @@ Run silently **before** emitting any tokens:
 
 ### When the user calls out a language slip
 
-1. Acknowledge **once**, briefly, in the correct language ("Entschuldigung" /
-   "Sorry"). One sentence, no excuses.
-2. Switch immediately on the same reply.
-3. Do **not** re-explain the mistake in the wrong language.
-4. Do **not** promise "from now on" — just do it. Only behaviour changes
-   prove compliance.
-5. If user asks to harden the rule, harden it on this turn — don't defer.
-
-### Failure modes to watch for
-
-- Drafting reply in English first, then "translating the intro" → English
-  phrasing with German words. Draft in target language from the first token.
-- Copy-pasting English option labels from `.md` sources without translating.
-- Mixing languages inside a table or bullet list because "the technical term
-  is English" — surrounding prose must still mirror. Keep proper nouns and
-  code identifiers as-is; translate everything else.
-- Assuming English because "the codebase is English" — codebase language ≠
-  conversation language.
-- Mirroring the **open file** the IDE reports — open files are background
-  context, not chat messages.
-- Mirroring the **roadmap or ticket** being executed — artefacts are English
-  by `.md` rule; chat language is whatever the user wrote.
+Acknowledge **once**, briefly, in the correct language ("Entschuldigung" /
+"Sorry"). Switch immediately on the same reply. Do **not** re-explain in
+the wrong language. Do **not** promise "from now on" — just do it. If
+user asks to harden the rule, harden it on this turn.
+
+### Failure modes
+
+See [`../../docs/guidelines/agent-infra/language-and-tone-examples.md`](../../docs/guidelines/agent-infra/language-and-tone-examples.md)
+for the full failure-mode list.
 
 ## Other language rules
 
@@ -108,64 +83,30 @@ Run silently **before** emitting any tokens:
 
 ## `.md` files are ALWAYS English — no exceptions
 
-**Every** piece of text inside `.md` files in `.augment/` and `agents/` must be in English.
-This includes:
-
-- Headings, paragraphs, and bullet points
-- **Example option labels** (e.g., `> 1. Yes — start implementing`, NOT `> 1. Ja — mit der Umsetzung starten`)
-- **Example prompts and questions** (e.g., `"Found X unresolved comments."`, NOT `"X offene Kommentare gefunden."`)
-- **Template placeholders and sample output** (e.g., `Progress:`, NOT `Fortschritt:`)
-- **ASCII art labels** in formatted output blocks (e.g., `CHANGES:`, NOT `ÄNDERUNGEN:`)
-- **Table headers and content**
-
-The agent translates to the user's language **at runtime** when presenting options.
-The `.md` source files are the English blueprint — they define WHAT to say, not in which language.
-
-**Wrong** (German in `.md`):
-```
-> 1. Interaktiv — bei jedem Kommentar nachfragen
-> 2. Automatisch — alle selbstständig abarbeiten
-```
-
-**Correct** (English in `.md`):
-```
-> 1. Interactive — ask before each comment
-> 2. Automatic — handle all independently
-```
-
-### Quoted user-input examples — same rule, with one labeled exception
+**Every** piece of text inside `.md` files in `.augment/` and `agents/`
+must be in English: headings, paragraphs, bullets, example option labels,
+example prompts/questions, template placeholders, ASCII-art labels in
+formatted output blocks, table headers and content.
 
-Common drift pattern: a rule documents trigger phrases the agent
-should recognize and writes them as quoted German examples inside
-English prose. **Not allowed**, even when demonstrative.
-
-**Wrong** (DE quote embedded in EN prose):
-
-```md
-Single-decision delegation ("für diesen Schritt entscheide du") →
-handle that step autonomously.
-
-A standing "arbeite selbstständig" never lifts the floor.
-```
+The agent translates to the user's language **at runtime** when
+presenting options. The `.md` source files are the English blueprint —
+they define WHAT to say, not in which language. Concrete wrong-vs-correct
+examples live in [`../../docs/guidelines/agent-infra/language-and-tone-examples.md`](../../docs/guidelines/agent-infra/language-and-tone-examples.md).
 
-**Correct** — two ways:
+### Quoted user-input examples — labeled-anchor exception
 
-1. **Translate to English.** Trigger recognition is semantic; the
-   agent matches intent across languages regardless of the example.
-   `("you decide for this step")` works as well as the German.
-2. **Use a labeled `DE: … · EN: …` anchor list** when the
-   multilingual nature of recognition is the point:
+Drift pattern: a rule writes quoted German examples inside English prose.
+**Not allowed**. Two correct ways:
 
-   ```md
-   - DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
-   - EN: "work autonomously" · "don't ask" · "just do it"
-   ```
+1. **Translate to English.** Trigger recognition is semantic; the agent
+   matches intent across languages regardless of the example.
+2. **Use a labeled `DE: … · EN: …` anchor list** when the multilingual
+   nature of recognition is the point — the **only** allowed location
+   for German prose in an English `.md`. Reference established phrases
+   abstractly later and link back to the anchor block.
 
-The labeled-anchor block is the **only** allowed location for German
-prose in an English `.md` file. Body text, example sentences, prompt
-templates, agent-rendered strings, and failure modes must be English.
-Reference established phrases abstractly later (e.g. "a standing
-autonomy directive") and link back to the anchor block.
+Wrong-vs-correct snippets in
+[`../../docs/guidelines/agent-infra/language-and-tone-examples.md`](../../docs/guidelines/agent-infra/language-and-tone-examples.md).
 
 ### Detection heuristic
 

package/.agent-src/rules/minimal-safe-diff.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-alwaysApply: true
-description: "Minimal safe diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code"
+type: "auto"
+alwaysApply: false
+description: "When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code"
 source: package
 ---
 

package/.agent-src/rules/model-recommendation.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Model recommendation — detect task complexity, suggest optimal model (Opus/Sonnet/GPT), check on task changes and command invocations"
-alwaysApply: true
+type: "auto"
+description: "Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work"
+alwaysApply: false
 source: package
 ---
 
@@ -30,7 +30,7 @@ If the detected model is `gemini`, immediately trigger the Gemini warning (see b
 `/commit`, `/fix-pr-comments` are sonnet tasks — even if the previous task was opus-level.
 This is the most commonly missed check. Do NOT skip it.
 
-**Priority over commands rule**: This check runs BEFORE the `slash-commands` rule. If a model switch
+**Priority over commands rule**: This check runs BEFORE the `slash-command-routing-policy` rule. If a model switch
 is recommended, show the suggestion first. Only after the user responds, execute the command.
 
 **If ambiguous** (could be opus or sonnet): default to **sonnet** — cheaper, and the user can escalate.

package/.agent-src/rules/no-cheap-questions.md

@@ -0,0 +1,89 @@
+---
+type: "always"
+description: "No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on)"
+alwaysApply: true
+source: package
+---
+
+# No Cheap Questions
+
+A question is **cheap** when the answer follows from stated context,
+when an option would breach an Iron Law, when choices differ only in
+sequencing or format, or when one option is obviously dominant. Cheap
+questions are noise, regardless of `personal.autonomy`.
+
+Mode-independent. The "trivial" failure modes in
+[`autonomous-execution`](autonomous-execution.md) are scoped to
+`personal.autonomy: on` (or `auto`-after-opt-in); this rule lifts the
+**no-trade-off** subset to apply in `off` and pre-opt-in `auto` too.
+
+## The Iron Laws
+
+```
+NEVER ASK WHAT THE STATED CONTEXT ALREADY ANSWERS.
+NEVER PRESENT AN OPTION THAT VIOLATES AN IRON LAW.
+NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
+```
+
+Hold in `off`, `auto`, and `on`. Autonomy never lifts them.
+
+## What counts as cheap
+
+| Class | Pattern · why cheap |
+|---|---|
+| **Sequencing** | "Step 2 or 3 next?" when roadmap orders them — answer is in the roadmap |
+| **Format-only** | "Table or paragraph?" — no semantic trade-off |
+| **Commit asks** | "Commit now?" — [`commit-policy`](commit-policy.md): never ask |
+| **CI / test asks** | "Run tests now?" — [`verify-before-complete`](verify-before-complete.md) decides |
+| **Fenced-step re-asks** | "Start Phase 1?" after "plan only" — [`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates) |
+| **Iron-Law option** | Option breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default` — does not exist |
+| **Context-derived** | Answer follows from prior turn / standing instruction / roadmap — act, state assumption inline |
+| **Dominant option** | One choice obviously correct; alternatives carry no upside — pick it |
+| **Re-ask after decline** | Same path after user said no — [`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task) |
+
+## Pre-Send Self-Check — MANDATORY before every question
+
+Before drafting any numbered-options block, run silently:
+
+1. Does the answer follow from already-stated context?
+2. Does any option violate [`commit-policy`](commit-policy.md),
+   [`scope-control § git-ops`](scope-control.md), or
+   [`non-destructive-by-default`](non-destructive-by-default.md)?
+3. Are options pure sequencing / format with no trade-off?
+4. Is one option obviously dominant?
+5. Did the user fence the next step (*"plan only"*, *"review first"*)?
+   → deliver + handback per [`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates).
+6. Did the user already decline? Re-asking is forbidden per
+   [`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+
+Any "yes" → **do not ask**. Pick the dominant path, state the
+assumption inline (*"assuming X — adjust if wrong"*), hand back. The
+one-question-per-turn Iron Law from
+[`ask-when-uncertain`](ask-when-uncertain.md) still applies when the
+question is genuine.
+
+## When asking IS allowed
+
+- Real architectural / scope decision with non-obvious trade-offs.
+- Vague-request trigger per
+  [`ask-when-uncertain`](ask-when-uncertain.md#vague-request-triggers--must-ask).
+- Security-sensitive path per
+  [`security-sensitive-stop`](security-sensitive-stop.md).
+- Hard Floor in [`non-destructive-by-default`](non-destructive-by-default.md)
+  fires — confirmation is mandatory, never cheap.
+- Two genuinely-equivalent paths; user preference is the tiebreaker.
+
+In doubt → genuine. Ask. This rule narrows asking, never widens silence.
+
+## Interactions
+
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague triggers +
+  one-question-per-turn; this rule narrows the cheap subset.
+- [`autonomous-execution`](autonomous-execution.md) — mode-scoped
+  triviality there; mode-independent floor here.
+- [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) ·
+  [`non-destructive-by-default`](non-destructive-by-default.md) —
+  the Iron Laws this rule defends.
+- [`user-interaction`](user-interaction.md) — numbered-options shape;
+  this rule decides whether the block is sent at all.
+- [`direct-answers`](direct-answers.md) — brevity, no flattery.

package/.agent-src/rules/non-destructive-by-default.md

@@ -1,8 +1,10 @@
 ---
 type: "always"
-description: "Agent is never destructive and never endangers production systems — Hard Floor that always asks for production-trunk merges, deploys, pushes, prod data/infra changes, whimsical bulk deletions, and commits containing bulk deletions or infra changes; no autonomy setting, roadmap step, or standing instruction can bypass it"
+description: "Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass"
 alwaysApply: true
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/authority/destructive-mechanics.md
 ---
 
 # Non-Destructive by Default
@@ -51,57 +53,21 @@ of truth makes it reversible. Lives in
 ## Bulk deletions during WIP — allowed if task-connected
 
 Deletions inside an **active, user-stated task** are allowed in the
-working tree, **even multiple files or multiple folders**. The floor
-moves to the **commit** (row 6 above), not the in-progress edit.
-
-**Allowed during WIP (no floor on the edit):**
-
-- A roadmap step or current task explicitly names the files / folders to remove
-- Refactor naturally drops deprecated code the user already agreed is dead
-- Cleanup of generated artifacts — `node_modules/`, `dist/`, `.next/`,
-  build caches, `vendor/` reinstall — never source code
-- Single-file edits, single-class refactors, deleting **one** file the
-  user just named
-- Renames and moves (technically delete + add)
-
-**Floor fires on the edit when the deletion is:**
-
-- Whimsical — "while I was in there", drive-by cleanup not part of the task
-- Unnamed scope — "delete all the old tests" without a list, glob
-  across unrelated files, "clean up the legacy folder" with no inventory
-- ≥5 unrelated files in one operation, outside the current task scope
-- Content destruction — `DROP TABLE`, `TRUNCATE`, `git reset --hard`
-  past unpushed work, database wipes (destroys *content*, not just tree)
-
-Ambiguous → floor wins. Ask.
-
-**The commit of task-aligned bulk deletions still needs its own ask.**
-A roadmap or task authorizes the *edit*; only the user-this-turn
-authorizes the *commit* (row 6). Surface the diff (paths + counts), get
-confirmation, then commit.
+working tree, **even multiple files or multiple folders** — the Hard
+Floor moves to the **commit** (row 6 above), not the in-progress edit.
+Whimsical / drive-by / unnamed-scope deletions still trip the floor on
+the edit. Full allowed/forbidden lists in
+[`destructive-mechanics`](../contexts/authority/destructive-mechanics.md)
+§ Bulk deletions during WIP.
 
 ## Failure modes
 
-- Treating a standing autonomy directive as cover for a Hard-Floor
-  action. Standing autonomy never lifts the floor; merging to `main`,
-  deploying, pushing, prod-data edits, or whimsical `rm -rf <dir>`
-  always ask.
-- Reading a roadmap step that says "deploy to staging" or
-  "merge into main" as authorization. The roadmap can sequence the
-  work; only the user-this-turn can authorize the floor crossing.
-- Refusing to delete files the user already named because "the floor
-  fires on `rm`". It does not — task-aligned WIP deletions are
-  allowed, even multi-folder. The floor fires when the deletion is
-  whimsical, unscoped, or about to be committed.
-- Committing a diff that removes a directory, deletes ≥5 unrelated
-  files, or touches Terraform / k8s manifests / Ansible without
-  surfacing the diff first — even when [`commit-policy`](commit-policy.md)
-  otherwise authorizes commits (e.g. `/commit-in-chunks`, roadmap
-  pre-scan, an explicit "commit this now"). Bulk-deletion / infra
-  commits need their own ask, every time.
-- Reading a roadmap step listing files to delete as authorization to
-  *commit* the deletion. The step authorizes the *edit*; the commit
-  is row 6 of the Hard Floor and needs its own confirmation.
+The full failure-mode catalog (autonomy-as-cover, roadmap-as-authorization,
+refusing-named-deletions, commit-without-diff-surface,
+roadmap-step-≠-commit-authorization) lives in
+[`destructive-mechanics`](../contexts/authority/destructive-mechanics.md)
+§ Failure modes. Reach for it when a Hard-Floor situation feels
+ambiguous; the rule itself stays focused on the trigger table.
 
 ## Cloud Behavior
 

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

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "First-run gate — when onboarding.onboarded is false in .agent-settings.yml, prompt the user to run /onboard before anything else"
-alwaysApply: true
+type: "auto"
+description: "First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request"
+alwaysApply: false
 source: package
 ---
 
@@ -73,7 +73,7 @@ gate. This protects projects that were set up before this rule shipped.
   conversation, max.
 - Replace normal settings edits. Mid-life changes are ad-hoc (edit the
   file directly or ask the agent, which follows
-  [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules));
+  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules));
   this rule is a one-time gate.
 - Run on every agent turn. First turn only.
 
@@ -89,6 +89,6 @@ gate. This protects projects that were set up before this rule shipped.
 ## See also
 
 - [`/onboard`](../commands/onboard.md) — the command this gate invokes
-- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
+- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — `onboarding.onboarded` reference
 - [`rule-type-governance`](rule-type-governance.md) — why this is `always`

package/.agent-src/rules/review-routing-awareness.md

@@ -37,8 +37,8 @@ Look, in order, for:
 - `.github/historical-bug-patterns.yml` (or
   `agents/historical-bug-patterns.yml`)
 
-If neither exists, fall back to engineering-memory via
-[`memory-access`](../guidelines/agent-infra/memory-access.md):
+If neither file exists, fall back to the engineering-memory layer via
+[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
 
 ```python
 from scripts.memory_lookup import retrieve
@@ -50,11 +50,11 @@ extra = retrieve(
 ```
 
 Curated memory (`agents/memory/ownership.yml`,
-`agents/memory/historical-patterns.yml`) shares the schema with the
-project-local YAMLs and is merged into the routing output. If both
-memory and project YAMLs are absent, skip this rule and rely on
-[`reviewer-awareness`](reviewer-awareness.md) defaults. **Do not invent
-owners or patterns** from context.
+`agents/memory/historical-patterns.yml`) carries the same schema as the
+project-local YAMLs and is merged into the routing output alongside
+them. If both memory and project YAMLs are absent, skip this rule and
+rely on [`reviewer-awareness`](reviewer-awareness.md) defaults. **Do
+not invent owners or patterns** from context.
 
 ### 2. Match the diff
 
@@ -66,7 +66,7 @@ For every changed file, collect:
   mode and the minimum control or test the project expects.
 
 Matching uses glob patterns (see
-[`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+[`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
 for the schema).
 
 ### 3. Surface findings
@@ -117,7 +117,7 @@ When producing a review plan, include:
 
 - [`reviewer-awareness`](reviewer-awareness.md) — formatting reviewer
   suggestions.
-- [`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+- [`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
   — YAML schemas for ownership-map and historical-bug-patterns.
 - [`review-routing`](../skills/review-routing/SKILL.md) — the skill
   that produces the merged routing report.

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

@@ -1,10 +1,13 @@
 ---
 type: "auto"
-description: "Any touch to agents/roadmaps/ — creating, renaming, deleting, or moving a roadmap file (including into archive/ or skipped/), editing checkboxes ([x], [~], [-]), or adding/renaming/removing phases — must regenerate the roadmap dashboard in the SAME response; a roadmap that hits 0 open items must also be archived in the SAME response"
+description: "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"
 alwaysApply: false
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
+
 # Roadmap Progress Sync
 
 ## Iron Law — dashboard sync
@@ -30,6 +33,7 @@ without regenerating? The dashboard claims it does not exist. Marked
 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.py` (CANNOT BE DEFERRED).
 ```
 
 **Active roadmap =** any file in `agents/roadmaps/` (root, not
@@ -42,9 +46,16 @@ 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 …`, or
-`## Block A` do **not** count — only the canonical `Phase <id>`
-form parsed by the dashboard.
+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.py` (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`
 
@@ -69,11 +80,6 @@ in the dashboard.
   executable phases. Flip to ready (or remove the field) the
   moment the roadmap is ready to track.
 
-A `## Decisions` or `## Block sequencing` table is **not** a roadmap
-on its own. Either pair it with a `## Phase N: <name>` section whose
-checkboxes execute the decision, or mark the file `status: draft`
-until the executable phases land.
-
 **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]`
@@ -130,20 +136,9 @@ Step counts as completed when:
 Then in the **same reply**: flip the checkbox, regenerate the
 dashboard, commit if commit policy allows.
 
-**Forbidden pattern** (canonical failure):
-
-> Turn 1: implement Step 1. Turn 2: implement Step 2. Turn 3:
-> implement Step 3. Turn 4: implement Step 4. Turn 5: "all done,
-> let me update the roadmap and commit." → the user spent four turns
-> without dashboard movement.
-
-**Required pattern:**
-
-> Turn 1: implement Step 1, flip `[x]`, regen, commit.
-> Turn 2: implement Step 2, flip `[x]`, regen, commit. …
-
-A reply that lands a verified step without flipping its checkbox
-is a rule violation.
+**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.
 
 **In-progress marker:** when a step takes more than one reply,
 mark it `[~]` the moment work starts on it and regenerate. The
@@ -180,14 +175,13 @@ Any "yes" + no regen run = rule violation. Rerun before sending.
   flat the whole time, single regen at the end** — user lost
   progress visibility for the entire run. Each completed step must
   flip its checkbox in the reply that ships it.
-- **Decision-only roadmap shipped without checkboxes** — the file
-  documents synthesized decisions, ICE matrices, or block sequencing
-  but contains zero `- [ ]` items. The dashboard regenerates with
-  `0/0 steps` for that file or omits it from the open set entirely.
-  The reader thinks no work is planned. Either pair the decisions
-  with a `## Phase N` / `## Implementation Checklist` section, or
-  mark the file `status: draft` so it is hidden until the executable
-  phases land.
+- **Decision-only roadmap shipped without checkboxes** — file
+  contains decisions / ICE / block-sequencing but zero `- [ ]`,
+  dashboard shows `0/0` or omits it. Pair with a `## Phase N`
+  section or mark `status: draft` (CI catches this now).
+- **Headings off-canon (`### P0 #N`, `## Block A`, `### Sequencing
+  — Phase 1`)** — `PHASE_RE` skips them, roadmap invisible to the
+  dashboard. Rename to `## Phase <id>` or mark `status: draft`.
 
 ## Do NOT
 
@@ -195,5 +189,4 @@ Any "yes" + no regen run = rule violation. Rerun before sending.
 - Do NOT defer the regen to "next commit" or "before push" — same response.
 - Do NOT rely on CI (`--check` mode) as the first line of defence — CI is last-line, not real-time.
 - Do NOT skip the 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 it in the same response, ask the user afterwards if needed, not before.
-- Do NOT regenerate the dashboard before the `git mv` when a roadmap closes — otherwise the completed roadmap reappears in "Open roadmaps".
+- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — `git mv` to archive **before** regenerating, otherwise it reappears in "Open roadmaps".

package/.agent-src/rules/role-mode-adherence.md

@@ -9,7 +9,7 @@ source: package
 
 Auto-activates when `.agent-settings.yml` sets `roles.active_role` to
 one of the six modes defined in
-[`role-contracts`](../guidelines/agent-infra/role-contracts.md):
+[`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
 `developer`, `reviewer`, `tester`, `po`, `incident`, `planner`.
 
 Read `roles.active_role` from `.agent-settings.yml` at session start.
@@ -47,7 +47,7 @@ Infer the mode (Phase-3 router does that). Touch `.agent-settings.yml`
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md)
 - [`/mode`](../commands/mode.md)
 - [`ask-when-uncertain`](ask-when-uncertain.md)
 - [`scope-control`](scope-control.md)