@event4u/agent-config 1.16.0 → 1.18.0

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

@@ -3,6 +3,8 @@ type: "auto"
 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
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md
 ---
 
 <!-- cloud_safe: degrade -->
@@ -10,6 +12,11 @@ source: package
 
 # Roadmap Progress Sync
 
+> **Enforced by:** [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
+> below is the specification the hook implements and the fallback when
+> the platform has no hook surface.
+
 ## Iron Law — dashboard sync
 
 ```
@@ -88,32 +95,27 @@ 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
+## Agent-authored roadmaps — placement is mandatory
 
-```bash
-./agent-config roadmap:progress
+```
+A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
+(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
+(b) NOT BE IN agents/roadmaps/ AT ALL.
+NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
 ```
 
-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
+When the agent autonomously creates a roadmap, it owns the placement
+in the **same response**:
 
-| 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 |
-| **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
-| Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
+- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
 
-**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.
+A non-trackable file in `agents/roadmaps/` is a rule violation — the
+trackable CI fails it, the dashboard hides it. The agent that
+created it moves it the same response. If the autonomous run also
+**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
+the completion-archival rule above fires too — same response.
 
 ## Autonomous execution — checkbox cadence
 
@@ -146,47 +148,11 @@ 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.
-
-## Failure modes
-
-- **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 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".
+## Mechanics — triggers, regen command, self-check, failures
+
+The triggers table, the regen command (`./agent-config roadmap:progress`),
+the mandatory pre-send self-check, the failure-mode catalog, and the
+`Do NOT` list live in
+[`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
+Pull it whenever a trigger fires — the rule above is the obligation
+surface; the mechanics file is the lookup material.

package/.agent-src/rules/rule-type-governance.md

@@ -44,3 +44,31 @@ The `description` field IS the trigger. It must describe **when** the rule appli
 - Default to `auto`. Justify `always`.
 - If >50% of conversations don't need a rule → it must be `auto`.
 - `optimize-agents` command checks this and suggests changes.
+
+## Hardening tier — required on new or edited rules
+
+Every new rule, and every edited rule whose body changes the trigger
+or the obligation, MUST classify itself against the hardening tiers
+documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+
+| Tier | Meaning |
+|---|---|
+| `1` | Mechanically enforceable — hook acts, rule body stays minimal. |
+| `2a` | Marker nudge — hook injects signal, agent acts on it. |
+| `2b` | Structured injection / tool-call gate — hook reads/writes state, may deny. |
+| `3` | Soft, judgment-bound — no platform surface; self-check rule. |
+| `safety-floor` | Iron-Law subset, never modified. |
+| `mechanical-already` | Precedent — script enforces, rule body documents. |
+
+Classification surface: the optional `tier:` frontmatter field
+(declared in `scripts/schemas/rule.schema.json`). Recommended for new
+rules; bulk-retrofit of existing rules is tracked separately.
+
+Tier 3 dispositions are recorded centrally in
+[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+with a 6-month re-audit clock. New Tier 3 rules append to that list
+on landing.
+
+The `optimize-agents` command checks the tier alongside `type`/`source`
+and suggests escalations when a rule's trigger matches a hardening
+opportunity that has shipped since the rule was authored.

package/.agent-src/rules/security-sensitive-stop.md

@@ -41,8 +41,8 @@ STOP writing code. Run the matching analysis skill first:
 | Data flows to logs / API / external | `data-flow-mapper` |
 | Wide refactor of security-sensitive code | `blast-radius-analyzer` |
 
-**Before the analysis, consult memory for prior incidents** on this
-surface. Via [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
+**Before running the analysis, consult memory for prior incidents** on
+this surface. Via [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
 
 ```python
 from scripts.memory_lookup import retrieve
@@ -53,14 +53,14 @@ priors = retrieve(
 )
 ```
 
-A prior security incident on the same path is the cheapest input to a
-threat pass — cite any matching `id` so the required control or
-regression test ships with the fix.
+A prior security incident on the same path is the cheapest possible
+input to a threat pass — cite any matching `id` in the analysis output
+so the required control or regression test ships with the fix.
 
 Capture the analysis output (abuse cases, missing controls, required
-negative tests) — implement against that list, not your first instinct.
-Never silently fall back to editing without the analysis; if blocked,
-ask the user.
+negative tests) — implement against that list, not against your first
+instinct. Never silently fall back to editing without the analysis; if
+it is blocked, ask the user.
 
 ## When NOT to fire
 

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

@@ -3,6 +3,8 @@ type: "auto"
 description: "Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/skill-quality-mechanics.md
 ---
 
 # Skill Quality
@@ -30,26 +32,13 @@ and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
 
 ## Description Triggering
 
-Claude routes skills by reading the frontmatter `description`. Polite, generic,
-or hedged descriptions cause **undertriggering** — the skill never loads when it
-should, and the user never learns it exists.
-
-Make descriptions "pushy" — explicit about when to fire:
-
-- Start with a concrete verb phrase: `Use when ...`, `Creates ...`, `Reviews ...`.
-- Name 2+ concrete triggers — domains, symptoms, file types, user phrasing.
-- End with: `... even if they don't explicitly ask for \`<skill-name>\`.`
-- Avoid hedges: `may help with`, `can be useful for`, `covers various`.
-- **Keep it ≤ 200 characters.** `scripts/skill_linter.py` warns at
-  `description_too_long` above this. If the pushy tail pushes you over, cut
-  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).
-
-**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
-route to this skill, the description is too polite. Rewrite it.
+Claude routes skills by their frontmatter `description`. Pushy,
+trigger-rich descriptions are required — polite or hedged ones cause
+undertriggering. The full recipe (concrete verb phrase, ≥2 triggers,
+`even if they don't explicitly ask for …` tail, ≤200 chars,
+litmus test) lives in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Description Triggering.
 
 ## Skill Independence
 
@@ -64,35 +53,14 @@ If a skill is not executable without opening a guideline, it is broken.
 **Litmus test:** Cover all guideline references in the Procedure. Is it still executable?
 If not → the skill needs more own steps, decisions, and validation — not more guideline links.
 
-## Merge Preservation
-
-When merging or refactoring skills, the merged result MUST preserve:
-
-1. **Strongest validation** from each source skill
-2. **Strongest example** (good/bad contrast) from each source
-3. **Strongest anti-pattern** from each source
-4. **All concrete decision criteria** that differ between sources
-
-A merge is invalid if:
-- Validation got weaker than the strongest source
-- Examples were lost without replacement
-- Anti-pattern coverage decreased
-- The merged skill became a generic umbrella doc
-
-## Compression Preservation
-
-When compressing a skill, the compressed version MUST preserve:
-
-- Trigger quality (description + When to use)
-- All procedure steps that contain decisions
-- All concrete validation checks
-- All gotchas and anti-patterns
-- Strongest example (at minimum one good/bad contrast)
+## Merge & Compression Preservation
 
-Compression may remove:
-- Verbose explanations
-- Redundant examples (keep the strongest)
-- Commentary that doesn't affect execution
+When merging or compressing skills, the result MUST preserve the
+strongest validation, strongest examples, all anti-patterns, all
+decision criteria, and trigger quality. Full preservation invariants
+and "merge is invalid if …" / "compression may remove …" lists in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Merge Preservation and § Compression Preservation.
 
 ## Refactor Safety
 

package/.agent-src/rules/slash-command-routing-policy.md

@@ -3,6 +3,8 @@ type: "auto"
 description: "When user types a slash command like /create-pr, /commit, or pastes command file content"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md
 ---
 
 # Commands
@@ -22,9 +24,10 @@ When the user types a command (`/create-pr`, `# create-pr`, or pastes a command
 
 ## Open files are irrelevant for command detection
 
-Editor may report an open file (e.g., "user has `compress.md` open"). **Irrelevant** for commands.
+The editor may report that the user has a file open (e.g., "The user has file `compress.md` open").
+This is **irrelevant** for command detection.
 
-- `/compress` typed → **run** compress command — even if `compress.md` is open in editor.
-- Command content in context + open file → **command invocation takes priority**.
+- If the user types `/compress`, they want to **run** the compress command — even if `compress.md` is open in the editor.
+- If command file content appears in the context alongside an open file, the **command invocation takes priority**.
 - Do NOT confuse "file is open" with "user wants to discuss this file".
-- User's typed message determines intent — not editor state.
+- The user's typed message determines intent — not editor state.

package/.agent-src/rules/think-before-action.md

@@ -16,77 +16,87 @@ source: package
 - If requirements are unclear, ask a precise clarification question instead of making hidden assumptions
 - Refactors must preserve behavior, validation, examples, and anti-failure guidance unless there is an explicit reason to change them
 - Do NOT modify code you do not fully understand — read it first, trace the flow, then change it
-- Multiple valid frameworks/patterns already in the codebase (Tailwind + Flux, multiple form libs, competing state stores) → do NOT pick one silently, ask. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation)
+- When multiple valid frameworks/patterns already exist in the codebase (e.g. Tailwind + Flux, multiple form libraries, competing state stores), do NOT pick one silently — ask which to use. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation)
 
 ## The Developer Workflow
 
-Work like a real developer. Follow this order strictly:
+Work like a real developer — not a text generator. Follow this order strictly:
 
-1. **Understand** — Read task, ticket, acceptance criteria. Unclear? Ask, don't assume.
-2. **Analyze** — Read affected code, trace data flow, compare with requirements.
-3. **Plan** — What to change, what NOT to change, how to verify.
-4. **Implement** — Focused changes. Follow existing patterns. No unrelated rewrites.
-5. **Verify** — Run tests, hit endpoint, check UI. Real execution, not "should work".
+1. **Understand** — Read the task, ticket, acceptance criteria. If unclear: ask, don't assume.
+2. **Analyze** — Read affected code, trace data flow, compare with requirements and existing patterns.
+3. **Plan** — Decide what to change, what NOT to change, and how to verify success.
+4. **Implement** — Make focused changes. Follow existing patterns. No unrelated rewrites.
+5. **Verify** — Run tests, hit the endpoint, check the UI. Real execution, not "should work".
 
-Skipping steps 1-3 = #1 cause of wrong implementations and wasted retries.
+Skipping steps 1-3 is the #1 cause of wrong implementations and wasted retries.
 
-## Consult memory before editing
+## Minimum read set — read before you write
 
-Before writing code for the touched paths, call
-[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md):
+Before editing code, read the minimum set that defines its behavior:
 
-```python
-from scripts.memory_lookup import retrieve
-priors = retrieve(
-    types=["architecture-decisions", "domain-invariants"],
-    keys=<touched paths>,
-    limit=3,
-)
-```
+1. **Symbol under edit** — full method/function body, not just the planned line.
+2. **Direct callers** — one level up (`grep -rn "<symbol>"` + open the matches).
+3. **Tests** — if a test file exists, it encodes the contract.
+4. **One layer of related abstractions** — interface, parent class, or trait (one hop, not the full hierarchy).
+5. **Data changes:** the migration that created the column + any seeder/factory that references it.
 
+Stop expanding once you can explain, in your own words, what the symbol does, who calls
+it, and what breaks if you change its behavior. If you cannot → read more. Never write
+code based on guessed behavior.
+
+### Consult memory before editing
+
+Prior decisions and invariants live in the memory layer. Via
+[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md), call
+`retrieve(types=["architecture-decisions", "domain-invariants"], keys=<touched paths>, limit=3)`.
 A matching `architecture-decision` explains *why* the current shape
 exists; a matching `domain-invariant` is a hard constraint you cannot
-violate. Cite the `id` if a match influences the plan. No match → no
-overhead; proceed.
+violate. Cite the `id` if a match influences the plan.
 
 ## Verify with real tools
 
+Always verify changes with actual execution — not by reading code and assuming it works.
+
 | What changed | How to verify |
 |---|---|
-| **Backend/API** | `curl`, Postman (or Postman MCP), test endpoint |
-| **Frontend/UI** | Playwright MCP or browser — rendered state, interactions |
-| **Logic/flow** | Xdebug (or Xdebug MCP) — trace execution, inspect variables |
-| **CLI/Jobs** | Run command, check side effects, exit code |
-| **Database** | Query result, check migrations |
+| **Backend/API** | `curl`, Postman (or Postman MCP if available), test endpoint |
+| **Frontend/UI** | Playwright MCP or browser — check rendered state, interactions |
+| **Logic/flow** | Xdebug (or Xdebug MCP if available) — trace execution, inspect variables |
+| **CLI/Jobs** | Run the command, check side effects, verify exit code |
+| **Database** | Query the result, check migrations ran correctly |
 
-If debugging/testing tool available as MCP server — prefer it.
+If a debugging/testing tool is available as MCP server — prefer it over manual alternatives.
 
-If verification not possible: state what is missing and how change should be tested.
+If verification is not possible (no endpoint, no UI, no test): explicitly state what is missing
+and explain how the change should be tested.
 
 ## Reduce output — targeted tools over full dumps
 
 Never load full datasets into context. Extract what you need:
 
-- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'`
-- `rg` / `grep` for text — specific patterns, not full files
-- `head`, `tail`, `cut`, `sort`, `uniq` to narrow results
-- `--filter`, `--json`, `--format` flags on CLI tools
-- Logs: filter by request ID, timestamp, error type — not full files
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'` — not the full response
+- `rg` / `grep` for text: search specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
+- `--filter`, `--json`, `--format` flags on CLI tools — use them
+- Laravel: `route:list --json | jq` over raw `route:list` dump
+- Logs: filter by request ID, timestamp, or error type — not full log files
 
 ## No blind retries
 
-- Fail? **Read the error**, analyze cause, then fix
-- Do NOT retry same approach hoping for different result
-- Do NOT loop trial-and-error when one inspection reveals the cause
-- Max 2 retries same approach — then stop and rethink
+- If something fails: **read the error**, analyze the cause, then fix it
+- Do NOT retry the same approach hoping for a different result
+- Do NOT loop through trial-and-error when one targeted inspection would reveal the cause
+- Max 2 retries for the same approach — then stop and rethink
 
 ## Open files are context, not intent
 
-The editor may report an open file. This is **background context only** — NOT the user's intent.
+The editor may report that the user has a file open. This is **background context only** —
+it does NOT mean the user's message is about that file.
 
-- **User's message determines intent** — not which file is open.
-- User has `README.md` open + types `/compress` → intent is compress, not README.
-- User has `UserController.php` open + asks "how do tests work?" → intent is testing, not the controller.
-- Only treat open file as relevant when the user explicitly references it ("fix this file", "what does this do?").
+- **The user's message determines intent** — not which file is open.
+- A user can have `README.md` open and type `/compress` — the intent is to compress, not to discuss the README.
+- A user can have `UserController.php` open and ask "how do tests work?" — the intent is testing, not the controller.
+- Only treat the open file as relevant when the user's message explicitly references it
+  (e.g., "fix this file", "what does this do?", "update the open file").
 
 If analysis is skipped → results are unreliable.

package/.agent-src/rules/tool-safety.md

@@ -6,31 +6,34 @@ description: "When a skill uses external tools — enforce allowlist, deny-by-de
 
 # Tool Safety
 
+## Core principle
+
 Tools are permissions, not abilities. Every tool access must be declared and reviewable.
 
 ## Constraints
 
-- **Deny by default** — no access unless in `allowed_tools`
-- **Allowlist only** — names must match tool registry
-- **Read-first** — write requires explicit approval
-- **No hidden credentials** — no API keys in skill files
-- **No arbitrary execution** — adapters have fixed interfaces
-- **Audit trail** — tool usage must be observable
+- **Deny by default** — no tool access unless explicitly listed in `allowed_tools`
+- **Allowlist only** — tool names must match the tool registry
+- **Read-first** — prefer read-only actions; write requires explicit approval
+- **No hidden credentials** — tools must not embed API keys or tokens in skill files
+- **No arbitrary execution** — tool adapters have fixed interfaces, not free-form calls
+- **Audit trail** — tool usage should be observable and logged
 
 ## When this applies
 
-- Skills declaring `allowed_tools`
-- Skills referencing external APIs (GitHub, Jira)
-- Runtime execution accessing external services
+- Skills that declare `allowed_tools` in their execution block
+- Skills that reference external APIs (GitHub, Jira, etc.)
+- Any runtime execution that accesses external services
 
 ## Escalation
 
-1. Do NOT use unregistered tools
-2. Flag as registry extension suggestion
-3. Tool must be added to registry before use
+If a skill needs a tool that is not in the registry:
+1. Do NOT use the tool
+2. Flag it as a suggestion for registry extension
+3. The tool must be added to the registry before use
 
-## Not covered
+## What this rule does NOT cover
 
-- Internal agent capabilities (not external tools)
-- MCP server configuration (`mcp` skill)
-- Credential management (environment config)
+- Internal agent capabilities (file reading, code analysis) — these are not external tools
+- MCP server configuration — handled by the `mcp` skill
+- Credential management — handled by environment configuration

package/.agent-src/rules/ui-audit-gate.md

@@ -3,6 +3,8 @@ type: "auto"
 description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/ui-audit-gate-mechanics.md
 ---
 
 # UI-Audit Before Build
@@ -50,19 +52,6 @@ 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.
@@ -74,33 +63,30 @@ emit `@agent-directive: existing-ui-audit` instead of writing code.
    external-reference halt **before** code; record the pick in
    `state.ui_audit.greenfield_decision`.
 
+## What "audit findings" means
+
+`state.ui_audit` is a non-empty dict carrying at least one of:
+
+- `components_found` — inventory entries from `existing-ui-audit`.
+- `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 —
+the empty dict is rejected on purpose. An audit that finds nothing
+must record either ≥1 `components_found` or the greenfield branch.
+
 ## 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.
+- Citing a similar-looking component from memory without verifying.
+- Treating `state.ui_audit = {}` as "audit ran, found nothing".
 - 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.
+## Lookup material — see mechanics
+
+The full failure-mode catalog, cross-rule interactions, and the
+cloud-surface adaptation live in
+[`contexts/communication/rules-auto/ui-audit-gate-mechanics.md`](../contexts/communication/rules-auto/ui-audit-gate-mechanics.md).
+Pull it whenever the gate fires or the agent is unsure whether a
+recorded `state.ui_audit` qualifies.