@event4u/agent-config 1.16.0 → 1.17.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 -->
@@ -88,33 +90,6 @@ 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
-
-```bash
-./agent-config roadmap:progress
-```
-
-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 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 |
-
-**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
@@ -146,47 +121,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/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.

package/.agent-src/rules/user-interaction.md

@@ -3,6 +3,8 @@ type: "auto"
 description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
 ---
 
 # User Interaction
@@ -55,7 +57,7 @@ recommendation line is mandatory.
 - Hiding behind "you know the project better"
 - Inline `(recommended)` tag with no follow-up `Recommendation: N` line
 
-**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#when-the-user-calls-out-a-language-slip).**
+**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#slip-handling).**
 User calls out a missing or wrong recommendation → acknowledge once
 in the user's language, rewrite the reply with a recommendation,
 ship. No "from now on" promises — only the next reply proves
@@ -84,12 +86,11 @@ Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft
 (non-zero exit on any rule above). Self-scan is the primary gate; the
 script is the deterministic safety net for ambiguous cases.
 
-### Common failure modes — known, named, no excuses
-
-- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `> 1. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
-- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
-- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
-- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 above closes this.
+Common failure modes (end-of-turn menu skipped, "no preference"
+hedges, multi-block reply with one recommendation) and the named
+slip catalog live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md)
+§ Common failure modes.
 
 ## Numbered Options — Always
 
@@ -117,65 +118,9 @@ just a number (e.g., `1`) instead of typing a sentence.
 - **Use the user's language** for the question and options.
 - **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
 
-### Examples
-
-**Binary choice:**
-
-```
-> 1. Interactive — ask before each comment
-> 2. Automatic — handle all independently
-
-**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
-so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
-if the comments turn out to be pure formatting.
-```
-
-**Multiple choice with skip:**
-
-```
-> 1. Fix the code
-> 2. Fix the test
-> 3. Skip
-
-**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
-the production code drifted from the contract. Caveat: pick 2 only if the contract
-itself is wrong.
-```
-
-**Confirmation with context:**
-
-```
-> Found PR #1399 on branch `chore/refactor-agent-setup-2`.
->
-> 1. Yes, that's the right PR
-> 2. No, different PR — I'll provide the URL
+### Examples and "when NOT to use" — see mechanics
 
-**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
-Caveat: flip to 2 if the PR was reopened from a different branch.
-```
-
-### When NOT to use numbered options
-
-- **Open-ended questions** where the answer is free text (e.g., "What should the class be named?").
-- **Simple yes/no** can use numbered options OR accept "ja"/"nein" directly.
-  Even for yes/no, prefer numbered options if there's additional context to show.
-
-## Progress Indicators
-
-When processing multiple items (e.g., review comments, test failures), show progress:
-
-```
-**Comment 3/7** — `filename.php:42`
-```
-
-## Summaries
-
-After completing a batch of actions, provide a summary table:
-
-```
-| # | File | Action |
-|---|---|---|
-| 1 | `file.php` | Fixed null check |
-| 2 | `test.php` | Updated assertion |
-| 3 | `config.php` | Skipped (intentional) |
-```
+Worked examples (binary choice, multiple choice with skip,
+confirmation with context), the "when NOT to use numbered options"
+catalog, progress indicators, and summary-table patterns live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).

package/.agent-src/skills/ai-council/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when polling external AIs (OpenAI, Anthropic) outside the host
 source: package
 ---
 
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
 # ai-council
 
 ## When to use

package/.agent-src/skills/api-testing/SKILL.md

@@ -13,7 +13,7 @@ contract validation, response structure checks, or external service mocking.
 
 ## Procedure: Write API tests
 
-1. **Understand the endpoint** — Read controller, form request, existing tests. Understand expected behavior and edge cases before writing anything.
+1. **Understand the endpoint** — Read the controller, form request, and existing tests. Understand expected behavior, edge cases, and auth requirements before writing anything.
 2. **Set up test data** — Use seeders (preferred) or factories. Mock external services with `Http::fake()`.
 3. **Write test cases** — Cover success, validation errors, authorization failures, edge cases.
 4. **Assert response** — Check status code, JSON structure, data values. Use `assertJsonStructure()`.