@event4u/agent-config 1.15.0 → 1.17.0

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.

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

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "Security-sensitive code paths — authentication, authorization, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
+description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
 source: package
 ---
 
@@ -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`](../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/size-enforcement.md

@@ -22,7 +22,7 @@ source: package
   - Rules and system instructions should stay well below 200 lines
   - Smaller (≈60 lines) is strongly preferred
 
-→ Size limits and details: `.augment/guidelines/agent-infra/size-and-scope.md`
+→ Size limits and details: `../../docs/guidelines/agent-infra/size-and-scope.md`
 
 → Frontmatter contract: schemas live in `scripts/schemas/` and are enforced by
 `python3 scripts/validate_frontmatter.py`.

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-commands.md → 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

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Always analyze before acting. Prefer targeted inspection, tests, and real verification over guessing or trial-and-error."
-alwaysApply: true
+type: "auto"
+description: "Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error"
+alwaysApply: false
 source: package
 ---
 
@@ -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`](../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`](../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/token-efficiency.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Token efficiency — redirect output, minimize tool calls, keep responses concise"
-alwaysApply: true
+type: "auto"
+description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
+alwaysApply: false
 source: package
 ---
 
@@ -96,4 +96,4 @@ When `personal.minimal_output: true`:
 - Debugging: OK to read more context around one error.
 - User explicitly asks for full output: show it.
 
-→ Detailed patterns: `guidelines/agent-infra/output-patterns.md`
+→ Detailed patterns: `docs/guidelines/agent-infra/output-patterns.md`

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-before-build.md → ui-audit-gate.md}

@@ -1,8 +1,10 @@
 ---
-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
+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.