@event4u/agent-config 1.13.0 → 1.15.0

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

@@ -0,0 +1,117 @@
+---
+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"
+alwaysApply: true
+source: package
+---
+
+# Non-Destructive by Default
+
+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
+
+```
+HARD FLOOR OVERRIDES EVERYTHING.
+NO AUTONOMY SETTING, NO ROADMAP STEP, NO STANDING INSTRUCTION,
+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 (see [`autonomous-execution`](autonomous-execution.md#opt-in-detection--match-by-intent-not-exact-string)
+for the anchor list of recognized phrases):
+
+| Trigger | Examples |
+|---|---|
+| **Production-branch merge** | merging into `main`, `master`, `prod`, `production`, `release/*`, or any branch the project marks as deployment trunk |
+| **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 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,
+surface what's about to happen (one numbered-options block per
+[`user-interaction`](user-interaction.md)), wait. Other rules still
+apply to every other step.
+
+## Not in scope — deterministic regeneration
+
+Output regenerated from a tracked source (compression, code-gen,
+formatter passes, lock-file rebuilds) is not destructive — the source
+of truth makes it reversible. Lives in
+[`autonomous-execution`](autonomous-execution.md#trivial--just-act-do-not-ask)
+§ Trivial, not here. Per-file diff approval is theater.
+
+## 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.
+
+## 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.
+
+## Cloud Behavior
+
+The Hard Floor applies on every surface, including Claude.ai Web,
+Skills API, and any cloud agent. There is no "cloud override" — the
+floor predates and outranks any platform-specific autonomy default.
+
+## See also
+
+- [`autonomous-execution`](autonomous-execution.md) — defers to this rule for the floor; covers trivial-vs-blocking and opt-in detection only
+- [`commit-policy`](commit-policy.md) — four commit-exception paths; row 6 of the floor still applies on top of all four
+- [`scope-control`](scope-control.md) — git-ops permission gate; the floor is the never-overridable subset
+- [`user-interaction`](user-interaction.md) — numbered-options Iron Law for the confirmation prompt

package/.agent-src/rules/package-ci-checks.md

@@ -9,10 +9,14 @@ source: package
 
 Before **any** push/PR in agent-config: run ALL CI checks locally.
 
+## The Iron Law
+
 ```
 NEVER push without running ALL CI checks locally first.
 ```
 
+Every CI pipeline failure is preventable by running these checks before pushing.
+
 ## Required checks
 
 ### 1. Sync

package/.agent-src/rules/preservation-guard.md

@@ -9,8 +9,25 @@ source: package
 
 Transformations (merge, refactor, compress, split) must produce output **at least as strong** as input.
 
+## Iron Laws — every passage stays, caveman is fine
+
+Sections marked **Iron Law** (heading matches `# Iron Law`, `# Iron Laws`,
+`# The Iron Law`, any level, numbered like `Iron Law 1`, `Iron Law 2`)
+are **non-negotiable**, strictest preservation:
+
+- [ ] **Heading verbatim** — exact text, exact level. Drop heading → law gone, even if code block survives.
+- [ ] **Fenced code blocks byte-for-byte** — the law itself.
+- [ ] **Negation clauses kept** — `NO X`, `NEVER Y`, `NOT Z` stay. Load-bearing exception denials, not filler.
+- [ ] **Every passage stays** — every paragraph, every list item, every fenced code block from source survives in compressed output, in order. One paragraph → one paragraph; one bullet → one bullet. Dropping whole sentences, merging two paragraphs, skipping a list item is forbidden, even if surviving prose still "makes the point".
+- [ ] **No Iron Law downgrades** — `## Iron Law` MUST NOT become `### Iron Law`, `**Iron Law:**`, or inline prose. Heading level is part of prominence.
+
+**Caveman style encouraged for Iron Law bodies** — drop articles ("the", "a"), shorten phrasing, primitive grammar, terse cave-speak. Word count not a budget; structural unit count is. Every paragraph, bullet, code block from source present → compress as hard as you want. Forbidden is **deletion**: rationale paragraph stays, canonical-failure example stays, every "NEVER X" bullet stays.
+
+`scripts/check_compression.py` enforces mechanically — any violation is `error`, not warning.
+
 ## Checklist — verify before completing
 
+- [ ] **Iron Law sections** preserved per rules above — heading, body, fenced blocks, rationale
 - [ ] Strongest validation step preserved
 - [ ] Strongest example preserved
 - [ ] Strongest anti-pattern / "Do NOT" preserved
@@ -21,6 +38,9 @@ Transformations (merge, refactor, compress, split) must produce output **at leas
 
 ## Reject if
 
+- Iron Law heading removed or downgraded
+- Paragraph, list item, or fenced code block dropped from Iron Law section
+- Negation clauses or canonical-failure prose stripped from Iron Law
 - Validation, example, or anti-pattern removed without replacement
 - Decision logic weakened
 - Scope broadened by merging unrelated concerns

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

@@ -1,28 +1,86 @@
 ---
 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/ — 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"
 alwaysApply: false
 source: package
 ---
 
 # Roadmap Progress Sync
 
-## Rule
+## Iron Law — dashboard sync
 
-**CRITICAL — ZERO TOLERANCE:** Whenever you change checkbox state in a
-roadmap file (`agents/roadmaps/*.md`, module or package equivalents)
-you MUST regenerate the dashboard **in the same response** — not
-later, not batched across sessions, not "at the end of the roadmap".
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+A ROADMAP NOT IN THE DASHBOARD IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+**Roadmap touch =** create 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.
+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.
+```
+
+**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 …`, or
+`## Block A` do **not** count — only the canonical `Phase <id>`
+form parsed by the dashboard.
+
+## 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.
+
+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]` at all) **before** regenerating. A 100%-complete roadmap left
-in `agents/roadmaps/` is a rule violation. See `roadmap-management`
-for the archive vs skipped decision table.
+`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
 
@@ -31,7 +89,7 @@ for the archive vs skipped decision table.
 ```
 
 The `./agent-config` wrapper is written into the project root by the
-installer and delegates to the master CLI inside
+package installer and delegates to the master CLI inside
 `node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
 No global tooling required.
 
@@ -39,29 +97,103 @@ No global tooling required.
 
 | Edit | Must run, same response |
 |---|---|
+| **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 a phase | regenerate dashboard |
-| Create a new roadmap file | regenerate dashboard |
 | **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
 | Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
 
-**Batching:** multiple checkbox edits in one response → a **single**
-regeneration at the end is enough. If one closes a roadmap, archive
-it first, then run the single regen. But the response must not end
-without it.
+**Batching 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
+
+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 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.
+
+**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/`, run this
+silent gate:
+
+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
 
-The `roadmap-management` skill documents the command in several
-places, but skill body text is easy to miss under procedure pressure.
-A rule collapses the constraint into one line the model cannot skip:
-"checkbox edit → regenerate dashboard — same response".
+- **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** — 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.
 
 ## Do NOT
 
 - Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
-- Do NOT defer regen to "next commit" or "before push" — same response.
-- Do NOT rely on CI (`--check` mode) as first line of defence — CI is last-line, not real-time.
-- Do NOT skip regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
-- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — archive same response, ask the user afterwards if needed, not before.
-- Do NOT regenerate the dashboard before the `git mv` when a roadmap closes — otherwise it reappears in "Open roadmaps".
+- Do NOT 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".

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

@@ -42,7 +42,7 @@ 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

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

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

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

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

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

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

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

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