@event4u/agent-config 1.14.0 → 1.16.0

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

@@ -1,17 +1,19 @@
 ---
 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
 
-Agent is **never** destructive and **never** endangers user work or
-production systems. Universal safety floor — applies in every mode,
-every conversation, every turn. Autonomy settings, "just keep going"
-directives, roadmap authorizations, and standing permissions narrow
-other rules; **none lift this one**.
+The agent is **never** destructive and **never** endangers user work
+or production systems. This is the universal safety floor — it applies
+in every mode, every conversation, every turn. Autonomy settings, "just
+keep going" directives, roadmap authorizations, and standing
+permissions narrow other rules; **none of them lift this one**.
 
 ## The Iron Law
 
@@ -23,8 +25,8 @@ NO "JUST KEEP GOING" CAN BYPASS IT.
 
 Triggers below require explicit user confirmation **on this turn** —
 not from a previous turn, not from a roadmap, not from a standing
-autonomy directive (anchor list of recognized phrases:
-[`autonomous-execution`](autonomous-execution.md#opt-in-detection--match-by-intent-not-exact-string)):
+autonomy directive (see [`autonomous-execution`](autonomous-execution.md#opt-in-detection--match-by-intent-not-exact-string)
+for the anchor list of recognized phrases):
 
 | Trigger | Examples |
 |---|---|
@@ -32,7 +34,7 @@ autonomy directive (anchor list of recognized phrases:
 | **Deploy / release** | `terraform apply` on prod, `kubectl apply` on prod, deploy scripts, release commands, tag pushes that trigger CI deployment |
 | **Push to remote** | any `git push` (also covered by [`scope-control`](scope-control.md), restated so the floor never weakens) |
 | **Production data / infra** | prod DB writes or migrations, prod config, secrets rotation, IAM / role / policy, DNS, anything in a `prod`-scoped path or pipeline |
-| **Whimsical or unscoped bulk deletion** | `rm -rf <dir>`, `git rm -r`, glob deletions, `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work — when **not required by the current task**. Task-aligned bulk deletions are allowed during WIP — see below. |
+| **Whimsical or unscoped bulk deletion** | `rm -rf <dir>`, `git rm -r`, glob deletions, `DROP TABLE`, `TRUNCATE`, `git reset --hard` past unpushed work — when the deletions are **not required by the current task**. Task-aligned bulk deletions are allowed during WIP — see below. |
 | **Commit containing bulk deletions or infra changes** | a commit whose diff removes a directory, deletes ≥5 unrelated files, or touches Terraform / Pulumi / k8s manifests / Ansible / cloud-config — surface the diff and confirm even when [`commit-policy`](commit-policy.md) otherwise authorizes the commit |
 
 Standing "just keep going" + next step crosses the floor → STOP,
@@ -51,63 +53,27 @@ 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**. 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 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 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. Roadmap can sequence work;
-  only the user-this-turn authorizes 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. 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. 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
 
 The Hard Floor applies on every surface, including Claude.ai Web,
-Skills API, and any cloud agent. No "cloud override" — the floor
-predates and outranks any platform-specific autonomy default.
+Skills API, and any cloud agent. There is no "cloud override" — the
+floor predates and outranks any platform-specific autonomy default.
 
 ## See also
 

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,13 +1,16 @@
 ---
 type: "auto"
-description: "Editing checkboxes in agents/roadmaps/*.md — [x], [~], [-], or add/rename/remove 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
+## Iron Law — dashboard sync
 
 ```
 ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
@@ -15,21 +18,75 @@ 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]` ↔ `[~]` ↔ `[-]`).
+**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.
 
-`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.
+## Iron Law — every active roadmap is trackable
 
-**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.
+```
+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
+`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.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`
+
+```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.
 
 ## How to regenerate
 
@@ -37,30 +94,32 @@ skipped table.
 ./agent-config roadmap:progress
 ```
 
-`./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.
+The `./agent-config` wrapper is written into the project root by the
+package installer and delegates to the master CLI inside
+`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
+No global tooling required.
 
 ## Triggers
 
 | Edit | Must run, same response |
 |---|---|
-| **Create new roadmap file** | regenerate dashboard |
-| **Rename or delete roadmap file** | regenerate dashboard |
+| **Create a new roadmap file** | regenerate dashboard |
+| **Rename or delete a roadmap file** | regenerate dashboard |
 | Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | regenerate dashboard |
-| Add, rename, or remove phase | regenerate dashboard |
+| Add, rename, or remove a 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 → **single**
-regen at end is enough. One edit closes a roadmap → archive first,
-then single regen. Response must not end without it.
+**Batching rule:** if you edit multiple checkboxes in one response, a
+**single** regeneration at the end of that response is enough — but
+the response must not end without it. If one of those edits closes a
+roadmap, archive it first, then run the single regen.
 
 ## 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:
+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.
@@ -68,73 +127,66 @@ 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.
+Step counts as completed when:
 
-**Forbidden pattern** (canonical failure):
+- 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.
 
-> 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.
+Then in the **same reply**: flip the checkbox, regenerate the
+dashboard, commit if commit policy allows.
 
-**Required pattern:**
+**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.
 
-> 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.
+**In-progress marker:** when a step takes more than one reply,
+mark it `[~]` the moment work starts on it and regenerate. The
+user sees one row move from `[ ]` to `[~]` to `[x]` instead of
+silent rows. `[~]` is treated as open for `count_open` but moves
+the phase percentage forward in the dashboard.
 
 ## Pre-send self-check — MANDATORY
 
-Before sending any reply that touched `agents/roadmaps/`, silent gate:
+Before sending any reply that touched `agents/roadmaps/`, run this
+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.
+1. Did this turn create, rename, delete, or move a roadmap file? → regen MUST be in the reply.
+2. Did this turn flip any checkbox in a roadmap file? → regen MUST be in the reply.
+3. Did the regen output (`✅ Wrote agents/roadmaps-progress.md · …`) actually appear this turn? → if 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.
+5. **Trackable-roadmap gate** — did this turn create or substantially edit a roadmap file? → does it now contain at least one `- [ ]` per non-intro phase, **or** carry `status: draft` in frontmatter? → if neither, add the checklist or the draft flag before sending.
 
 Any "yes" + no regen run = rule violation. Rerun before sending.
 
-## Why this is a rule, not a skill tip
+## Failure modes
 
-`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".
+- **Created the roadmap, marked Phase 1 done across multiple turns,
+  never regenerated** — dashboard silently lies "this roadmap does
+  not exist" to the next reader. Canonical failure of this rule;
+  the rule was hardened in response to it.
+- **Regenerated yesterday, edited today, "I'll regen at session
+  end"** — session ends from a crash, regen never lands.
+- **Closed a roadmap (last `[ ]` → `[x]`) and regenerated before
+  `git mv`** — the closed roadmap reappears in "Open roadmaps".
+- **Edited the dashboard by hand to "fix it quickly"** — next regen
+  overwrites the manual edit; no audit trail of why.
+- **Autonomous run, four steps shipped across four turns, dashboard
+  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** — 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
 
 - 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" — 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.
+- 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" — `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.
@@ -42,12 +42,12 @@ When active, every closing output MUST:
 
 ## What this rule does NOT do
 
-Infer the mode (Phase-3 router does that). Modify `.agent-settings.yml`
+Infer the mode (Phase-3 router does that). Touch `.agent-settings.yml`
 (only `/mode` writes). Change the contracts (guideline is source of truth).
 
 ## 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)

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

@@ -3,6 +3,8 @@ type: "always"
 description: "Scope control — no unsolicited architectural changes, refactors, or library replacements"
 alwaysApply: true
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/authority/scope-mechanics.md
 ---
 
 # Scope Control
@@ -20,62 +22,79 @@ source: package
 
 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).
+> **Commit specifics:** see the canonical [`commit-policy`](commit-policy.md)
+> rule — narrower than the general "no git ops without permission"
+> below (covers the never-ask-about-committing default and the
+> 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.
-  Includes spike, scratch, throwaway, worktree branches.
-- NEVER create, close, reopen, or retarget a pull request without explicit
-  user permission.
+- NEVER create a new branch, switch to a different branch, or delete a
+  branch without explicit user permission. This includes spike, scratch,
+  throwaway, and worktree branches.
+- NEVER create, close, reopen, or change the target of 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.
+- NEVER include version numbers, target releases, deprecation dates,
+  release-tied milestones, or git tags inside roadmaps, plans, tickets,
+  or any other planning artifact. Roadmaps plan **work**; releases and
+  tags are a separate decision the user makes outside the roadmap.
+  Never surface "which release should this ship in?" as an option in
+  numbered choices, ADRs, or roadmap text. If the user wants a release
+  pinned to a milestone, they will 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.
-  2. **What** — files touched, experiments run, expected duration.
-  3. **How it continues** — merge back, cherry-pick, throwaway, PR
-     target, how the current branch is protected meanwhile.
-  Then present numbered options with "stay on current branch" as
-  default. User decides. Do NOT branch first and explain later.
-
-"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.
+  the user before asking** — see
+  [`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+  § Brief-before-asking for the required Why / What / How sequence.
+
+"Explicit permission" means the user said so **in this turn or in a
+standing instruction they have not revoked**. Earlier permission for a
+different operation 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:
+A subset of the operations above is **never** autonomous and never
+auto-permitted by a standing autonomy directive. Canonical rule:
+[`non-destructive-by-default`](non-destructive-by-default.md). The
+trigger list (production-branch merges, deploys / releases, prod
+data / infra, bulk-destructive ops) and the
+"authorization is this turn, not earlier" clarification live in
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Production, infrastructure, bulk-destructive.
 
-- **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.
+## Decline = silence — no re-asking on the same task
 
-A roadmap step or earlier turn does **not** count as authorization for
-these. Authorization is "the user said so on this turn".
+After the user **declines** a proposal (branch switch, PR creation,
+tag/release entry, separate worktree, version pinning in a roadmap),
+do **not** raise the same proposal again on the same task. The decline
+stands until the user reopens the topic themselves.
 
-## Decline = silence — no re-asking on the same task
+Timing and "is this worth asking?" guidance lives in
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Decline = silence — context.
+
+## Fenced step — user-set review gates
+
+When the user explicitly fences off the next step — *"don't implement
+yet"*, *"plan only"*, *"just write the roadmap, I'll review"*,
+*"review first"*, *"erst Roadmap, ich schau drüber"*, *"nichts
+implementieren"*, *"nur planen"*, *"erstmal nur X, dann ich"* — the
+agent's reply is **the deliverable plus a handoff**, never the
+deliverable plus *"shall we start?"*.
 
-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.
+```
+USER FENCED OFF EXECUTION → DELIVER + HAND BACK.
+NO NUMBERED OPTION OFFERING TO BEGIN WORK.
+NO "READY TO IMPLEMENT?" RE-ASK.
+NO "STARTEN WIR MIT PHASE 1?" PIVOT.
+```
 
-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.
+The fence stands until the user reopens the topic themselves, exactly
+like `Decline = silence` above. Permitted follow-up questions on the
+same turn cover **the deliverable** (adjust scope, fix wording, add a
+section), never **its execution**.
 
-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.
+For the failure-mode catalog (Option 1 = "start now", re-asking after
+delivery, hand-off-to-execution drift, inferring acceptance from a
+thumbs-up) and the explicit bypass phrases that lift the fence, see
+[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
+§ Fenced step.