@event4u/agent-config 1.16.0 → 1.17.0

package/.agent-src/skills/judge-code-quality/SKILL.md

@@ -112,8 +112,8 @@ Required fields (ordered):
    a codebase convention; omit only when verdict is `apply`
 
 If a finding needs runtime confirmation (running a formatter, linter,
-or static analyzer), note it as a follow-up for the implementer — the
-judge does not execute tools.
+or static analyzer to see the actual report), note it as a follow-up
+for the implementer — the judge does not execute tools.
 
 ## Gotcha
 
@@ -140,16 +140,15 @@ judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Code-review rubric** — Google Engineering Practices, "The Standard
   of Code Review" and "What to look for in a code review",
   [google.github.io/eng-practices/review/reviewer](https://google.github.io/eng-practices/review/reviewer/).
   The lenses (design, functionality, complexity, tests, naming, comments,
-  style, consistency) the judge applies — codebase conventions over
-  external style preferences.
+  style, consistency) the judge applies — prioritizing codebase conventions
+  over external style preferences.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),

package/.agent-src/skills/judge-security-auditor/SKILL.md

@@ -150,13 +150,12 @@ Runtime boundary: the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Security rubric** — OWASP Application Security Verification Standard
   (ASVS), [owasp.org/www-project-application-security-verification-standard](https://owasp.org/www-project-application-security-verification-standard/).
-  Finding categories (authentication, access control, validation,
+  The finding categories (authentication, access control, validation,
   cryptography, error handling) the judge walks on every diff.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -134,10 +134,9 @@ as a follow-up for the implementer — the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Test-value rubric** — Martin Fowler, "Test Pyramid",
   [martinfowler.com/bliki/TestPyramid.html](https://martinfowler.com/bliki/TestPyramid.html),
   and Kent Beck, "Test Desiderata",

package/.agent-src/skills/lint-skills/SKILL.md

@@ -17,56 +17,74 @@ execution:
 
 ## When to use
 
-- Validate shape of every skill/rule in `.agent-src.uncompressed/`
-- Verify `execution:` metadata is well-formed
-- Pre-PR local check before CI skill-lint job
-- Investigate reported linter failure
+Use this skill when:
 
-NOT: single file (call `skill_linter.py <path>`), cross-refs (use `check-refs`),
-compression freshness (use `bash scripts/compress.sh --check`).
+- Validating the shape of every skill and rule in `.agent-src.uncompressed/`
+- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
+- Checking locally before opening a PR that CI's skill-lint job will pass
+- Investigating a reported linter failure on a specific skill or rule
+
+Do NOT use when:
+
+- Linting only one file — call `python3 scripts/skill_linter.py <path>` directly
+- Checking cross-references between files — use `check-refs` instead
+- Checking compression freshness — use `bash scripts/compress.sh --check` instead
 
 ## Procedure
 
-1. **Inspect env** — `python3` on PATH, cwd = agent-config repo root (linter
-   resolves `.agent-src.uncompressed/skills/` relative to cwd).
-2. **Dispatch via runtime** —
+### 1. Inspect the environment
 
-   ```bash
-   python3 scripts/runtime_dispatcher.py run --skill lint-skills
-   ```
+Confirm `python3` is available and the working directory is the agent-config
+repository root — the linter expects to find `.agent-src.uncompressed/skills/`
+and related directories relative to `cwd`.
 
-   Handler runs `python3 scripts/skill_linter.py --all`, captures stdout/stderr,
-   returns typed `ExecutionResult`.
-3. **Verify result** —
-   - `status: success` + `exit_code: 0` → all clean
-   - `exit_code: 1` → warnings only — review stdout
-   - `exit_code: 2` → errors — fix flagged files
-   - `status: timeout` → investigate slowdown, do not just raise timeout
-   - `status: error` → interpreter missing or wrong cwd
+### 2. Dispatch via the runtime layer
 
-## Output
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
 
-1. One-line summary: status, exit code, duration (ms)
-2. Count of skills/rules inspected if known
-3. First 10 errored files: code + message
-4. Next action: fix, re-run, or surface raw stdout
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
 
-## Gotcha
+The dispatcher resolves the request, the shell handler runs
+`python3 scripts/skill_linter.py --all`, captures stdout/stderr, and returns
+a typed `ExecutionResult`.
 
-- `--all` walks full tree — several seconds; bump `timeout_seconds` if repo grew
-- Running outside repo root → zero skills inspected, looks green but is a no-op
-- `exit_code: 1` (warnings) does not fail CI — not the same as "clean"
+### 3. Verify the result
 
-## Do NOT
+Check the returned `ExecutionResult`:
+
+- `status: success` and `exit_code: 0` → all skills and rules are clean
+- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
+- `exit_code: 2` → errors present — fix the flagged files before continuing
+- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
+- `status: error` → the interpreter could not launch — check that `python3`
+  is on `PATH` and the repository root is the current working directory
 
-- Do NOT call `skill_linter.py` directly when the intent is to exercise the
-  runtime path — go through the dispatcher
-- Do NOT raise `timeout_seconds` to mask slowdowns
-- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+## Output format
 
-## References
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of skills and rules the linter inspected, if known
+3. List of files with errors (first 10), each with code and message
+4. Next action: fix errors, re-run, or surface the raw `stdout` for review
+
+## Gotchas
+
+- The command uses `--all`, which walks the full tree — expect several seconds
+  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
+- Running outside the agent-config repo root will make the linter report zero
+  skills, which looks like a pass but is actually a no-op
+- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
+  "green" when the task is to get to zero warnings
+
+## Do NOT
 
-- Skill: `check-refs` — sibling pilot that runs the cross-ref checker
-- Rule: `runtime-safety` — execution metadata constraints
-- Script: `scripts/skill_linter.py`, `scripts/runtime_dispatcher.py`,
-  `scripts/runtime_handler.py`
+- Do NOT invoke `scripts/skill_linter.py` directly when the intent is to test
+  the runtime path — use the dispatcher so the handler and result object are
+  exercised
+- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
+  investigate the slowdown first
+- Do NOT add shell redirection or pipes to `command` — the handler runs
+  `subprocess.run` with `shell=False`; only argv form is supported

package/.agent-src/skills/md-language-check/SKILL.md

@@ -16,29 +16,32 @@ execution:
 
 ## When to use
 
-Fire **before** saving any `.md` file under:
+Fire this skill **before** writing or saving any `.md` file under:
 
-- `.agent-src.uncompressed/` (source of truth)
+- `.agent-src.uncompressed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
 - `.agent-src/` (compressed projection)
 - `.augment/` (local agent projection)
-- `agents/` (project roadmaps, contexts, sessions)
+- `agents/` (project-specific roadmaps, contexts, sessions)
 
-Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md`
-files are ALWAYS English" + § Detection heuristic, every `.md` in
-those trees must be English. Bilingual content lives only in labeled
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md` files
+are ALWAYS English" and § Detection heuristic, every `.md` file in those
+trees must be English. Bilingual content lives only in labeled
 `DE: … · EN: …` anchor blocks.
 
 Do NOT use when:
 
-- Editing project content outside the trees above
-- Reviewing non-`.md` files (checker rejects them)
+- Editing project content outside the trees listed above (READMEs of
+  consumer projects, application docs that follow a different policy)
+- Reviewing chat history files (`.agent-chat-history` is JSONL, not `.md`)
+- Inspecting non-`.md` files — the checker rejects them with a warning
 
 ## Procedure
 
 ### 1. Identify the file(s) about to be saved
 
-Collect every `.md` path the agent is about to create or modify this
-turn. Multiple files → one invocation.
+Collect the absolute or repo-relative path of every `.md` file the
+agent is about to create or modify in this turn. Multiple files in
+one turn → pass them all to a single invocation.
 
 ### 2. Run the checker
 
@@ -46,58 +49,77 @@ turn. Multiple files → one invocation.
 python3 scripts/check_md_language.py <path> [<path> …] [--format json]
 ```
 
-Exit codes: `0` clean, `1` violations (save **blocked** until fixed
-or suppressed), `3` internal error.
+Exit codes:
+
+- `0` → no German content detected, save proceeds
+- `1` → violations found, save is **blocked** until they are resolved
+  or explicitly suppressed
+- `3` → internal error (unreadable file, decode failure)
 
 ### 3. Resolve findings
 
-| Kind | Cause | Fix |
+For every violation:
+
+| Kind | Likely cause | Fix |
 |---|---|---|
-| `umlaut` | German prose in body | Translate to English |
-| `de_word` | German function word in unquoted prose | Translate; or move into `DE: … · EN: …` block |
+| `umlaut` | German prose leaked into body text | Translate the sentence to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into a `DE: … · EN: …` block if intentional bilingual anchor |
 
-Meta-doc that **must** quote German tokens (e.g. the heuristic in
-`language-and-tone.md` itself) → append
-`<!-- md-language-check: ignore -->` to that single line. Never as a
-wholesale silencer.
+If the line is meta-documentation that **must** quote German tokens
+(e.g. the detection heuristic in `language-and-tone.md` itself),
+append `<!-- md-language-check: ignore -->` at the end of that single
+line — never as a wholesale silencer.
 
 ### 4. Re-run and confirm
 
-After every fix re-run on the same paths. Save proceeds only on `0`.
+After every fix, re-run the checker on the same paths. Save only
+proceeds on exit `0`.
 
 ## Allowed escape hatches
 
-- **Labeled anchor** — lines starting with `DE:` / `- DE:` / `* DE:`
-  (and the same for `EN:`) auto-skipped.
-- **Fenced code blocks** — exempt; shell snippets, JSON fixtures,
-  quoted user input pass through.
-- **Inline code** — backtick spans stripped before scanning.
-- **Per-line marker** — `<!-- md-language-check: ignore -->` on lines
-  that genuinely quote German tokens (rare).
+- **Labeled anchor block** — lines starting with `DE:` / `- DE:` /
+  `* DE:` (and the same for `EN:`) are skipped automatically. Use this
+  for intent-based opt-in / opt-out anchors.
+- **Fenced code blocks** — `\`\`\` … \`\`\`` content is exempt, so
+  shell snippets, JSON fixtures, and quoted user input in code
+  blocks pass through untouched.
+- **Inline code** — backtick spans are stripped before scanning;
+  identifiers like `für_test` inside backticks do not flag.
+- **Per-line marker** — append `<!-- md-language-check: ignore -->`
+  to a line that genuinely needs to quote a German token in body
+  prose (rare; reserved for the rules that document the heuristic).
 
 ## Output format
 
 1. One-line summary: `clean` or `N violation(s) found`
 2. Per violation: `file:line — kind \`match\`` plus the offending line
 3. Next action: translate, move into a `DE:`/`EN:` block, add the
-   per-line ignore marker, or revert
+   per-line ignore marker, or revert the change
 
 ## Gotchas
 
-- `.md` files only; non-`.md` paths emit a warning and skip
-- Word list is short and conservative — clean run is **necessary
-  but not sufficient**; agent owns the final language judgement
-- Frontmatter (`--- … ---`) is exempt
+- The checker scans `.md` files only; passing a non-`.md` path emits a
+  warning and skips it
+- The detection word list is intentionally short and conservative —
+  a clean run is **necessary but not sufficient**; the agent still
+  owns the final language judgement
+- Frontmatter (`--- … ---` at file head) is exempt; descriptions and
+  YAML keys can use international characters where the schema allows
 
 ## Do NOT
 
-- Do NOT silence by deleting trigger words from
-  `scripts/check_md_language.py`; extend the allow-list instead
-- Do NOT use the ignore marker as a generic mute
-- Do NOT skip the gate "because the file is small"
+- Do NOT silence the checker by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list (anchor
+  blocks, ignore marker) instead
+- Do NOT add the ignore marker to body prose just to push a save
+  through; the marker is for meta-documentation that quotes tokens,
+  not a generic mute
+- Do NOT skip the gate "because the file is small" — `language-and-tone`
+  § Detection heuristic applies to every save under the four trees
 
 ## Cloud Behavior
 
-Cloud surfaces (Claude.ai Web, Skills API) ship without the script,
-so this skill is **inert** there — apply the heuristic from
-[`language-and-tone`](../../rules/language-and-tone.md) manually.
+On cloud surfaces (Claude.ai Web, Skills API) the checker script is
+not shipped, so this skill is **inert** — the agent applies the
+heuristic from [`language-and-tone`](../../rules/language-and-tone.md)
+manually before emitting the file.

package/.agent-src/skills/override-management/SKILL.md

@@ -31,11 +31,11 @@ Changes to `.augment/` affect ALL projects. Use overrides instead.
 
 ## Procedure: Create an override
 
-Before creating, understand the original:
+Before creating an override, understand the original:
 
-1. **Read the original** from `.augment/{type}/{name}` — understand purpose and behavior
-2. **Check existing overrides** in `agents/overrides/{type}/` — avoid duplicates
-3. **Identify what needs changing** — only override specific behavior that differs
+1. **Read the original** from `.augment/{type}/{name}` — understand its purpose, structure, and behavior.
+2. **Check for existing overrides** in `agents/overrides/{type}/` — avoid duplicates.
+3. **Identify what needs changing** — only override the specific behavior that differs for this project.
 
 When loading any skill, rule, or command:
 
@@ -69,7 +69,7 @@ Override files **must match the original filename** exactly:
 |---|---|
 | `.augment/rules/php-coding.md` | `agents/overrides/rules/php-coding.md` |
 | `.augment/skills/eloquent/SKILL.md` | `agents/overrides/skills/eloquent.md` |
-| `.augment/commands/feature-plan.md` | `agents/overrides/commands/feature-plan.md` |
+| `.augment/commands/feature/plan.md` | `agents/overrides/commands/feature/plan.md` |
 | `../../../docs/guidelines/php/controllers.md` | `agents/overrides/guidelines/php-controllers.md` |
 | `.augment/templates/roadmaps.md` | `agents/overrides/templates/roadmaps.md` |
 

package/.agent-src/skills/quality-tools/SKILL.md

@@ -52,8 +52,8 @@ Use the **first matching** command style:
 | `symplify/easy-coding-standard` | `vendor/bin/ecs` | `vendor/bin/ecs check --fix` |
 
 **Priority:** If a project ships a `quality:*` wrapper (Artisan or Composer script), always prefer it —
-wrappers typically add
-git-aware execution, caching, automatic baseline regeneration, and memory management.
+wrappers typically add git-aware execution, caching, automatic baseline regeneration, and memory
+management on top of the native tools.
 
 If none of the above is installed → skip quality checks, inform the user.
 

package/.agent-src/skills/react-shadcn-ui/SKILL.md

@@ -9,35 +9,59 @@ source: package
 ## Compatibility
 
 - **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
-- Audit step (`directives/ui/audit.py`) reads the line above and compares it with `state.ui_audit.shadcn_inventory.version`; major mismatch triggers a soft halt before this skill runs.
+- The audit step (`directives/ui/audit.py`) reads the line above and
+  compares it with `state.ui_audit.shadcn_inventory.version`; a major
+  mismatch triggers a soft halt before this skill runs.
 
 ## When to use
 
-Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`, `review.py`, or `polish.py` dispatches to this skill, or when a React project clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*` dependencies, a `components/ui/` folder of generated primitives).
+Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`,
+`review.py`, or `polish.py` dispatches to this skill, or when a React project
+clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*`
+dependencies, a `components/ui/` folder of generated primitives).
 
 Do NOT use when:
-
 - Project is Blade + Livewire + Flux (use `flux` / `livewire` / `blade-ui`).
 - Project is Vue (use the Vue stack skills).
-- Plain React without shadcn/ui — fall back to manual composition; this skill assumes the primitive set exists.
+- Plain React without shadcn/ui — fall back to manual composition; this skill
+  assumes the primitive set exists.
 
 ## Gotcha
 
-- shadcn/ui is **not** an npm package. Primitives are copied into `components/ui/` and edited in-place. Do not `npm install shadcn-ui`. Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
-- Major-version drift between this skill's `## Compatibility` line and the project's installed primitives is a real risk. Audit step writes `state.ui_audit.shadcn_inventory` with the detected version — when it diverges by a major, audit emits a soft halt before this skill runs.
-- shadcn/ui composes Radix primitives. Accessibility built in via Radix but only when wrapper components used correctly (`asChild`, `<DialogTrigger>` instead of bare `<button>`).
-- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`) and CSS custom properties on `:root` and `.dark` (`--background`, `--foreground`, `--primary`, `--ring`, …). Audit writes them into `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
-- Dark mode is class-based (`<html class="dark">`). Every color must come from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
-- Every interactive primitive must declare a focus-visible state via `focus-visible:ring-2 focus-visible:ring-ring`; comes free with generated primitives but easy to remove during a refactor.
+- shadcn/ui is **not** an npm package. Primitives are copied into
+  `components/ui/` and edited in-place. Do not `npm install shadcn-ui`.
+  Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
+- Major-version drift between this skill's `## Compatibility` line and
+  the project's installed primitives is a real risk. The audit step
+  writes `state.ui_audit.shadcn_inventory` with the detected version —
+  when it diverges by a major, audit emits a soft halt before this
+  skill runs.
+- shadcn/ui composes Radix primitives. Accessibility is built in via Radix
+  but only when you use the wrapper components correctly (`asChild`,
+  `<DialogTrigger>` instead of a bare `<button>`).
+- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`)
+  and CSS custom properties on `:root` and `.dark` (`--background`,
+  `--foreground`, `--primary`, `--ring`, …). Audit writes them into
+  `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
+- Dark mode is class-based (`<html class="dark">`). Every color must come
+  from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
+- Every interactive primitive must declare a focus-visible state via
+  `focus-visible:ring-2 focus-visible:ring-ring`; that comes for free with
+  the generated primitives but is easy to remove during a refactor.
 
 ## Covered primitives
 
-Validated against the following shadcn primitives at the declared version:
+This skill is validated against the following shadcn primitives at the
+declared version:
 
-- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form wrapper + `zodResolver`).
-- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`, `AlertDialog`.
+- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`,
+  `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form
+  wrapper + `zodResolver`).
+- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`,
+  `AlertDialog`.
 - **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
-- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`, `Avatar`, `Skeleton`, `Progress`.
+- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`,
+  `Avatar`, `Skeleton`, `Progress`.
 - **Feedback:** `Toast` (sonner), `Alert`.
 
 ## Not covered — fall back to manual composition
@@ -45,63 +69,110 @@ Validated against the following shadcn primitives at the declared version:
 - Marketing-only components (Hero, Pricing, Features) — outside shadcn/ui.
 - `Calendar` / `DatePicker` — composition skill required, not generated.
 - `Combobox` — built from `Command` + `Popover`; case-by-case.
-- Streaming / partial-prerender boundaries — use the project's framework patterns (Next.js / Remix), not shadcn/ui.
+- Streaming / partial-prerender boundaries — use the project's framework
+  patterns (Next.js / Remix), not shadcn/ui.
 
 ## Procedure: render a shadcn/ui component for the design brief
 
 ### Step 0: Inspect
 
-1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches the version in `## Compatibility` within the same major. If audit flagged a mismatch, user already chose to proceed — note that in `state.changes`.
-2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius in rendered output must reference a token from this map.
+1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches
+   the version in `## Compatibility` within the same major. If audit
+   flagged a mismatch, the user already chose to proceed — note that
+   in `state.changes`.
+2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius
+   in the rendered output must reference a token from this map.
 3. Read `state.ui_design`:
    - `components` → the primitive list to compose.
-   - `microcopy` → button labels, empty-state text, validation messages. **Lock — render verbatim.**
+   - `microcopy` → button labels, empty-state text, validation messages.
+     **Lock — render verbatim.**
    - `states` → empty / loading / error / success / disabled coverage.
    - `a11y` → ARIA labels, keyboard nav, focus order.
 
 ### Step 1: Compose primitives
 
-1. Import primitives from project's `components/ui/` path (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
-2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` → `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
-3. Use variant API of `Button` (`variant="default" | "destructive" | "outline" | "secondary" | "ghost" | "link"`); do not override with raw Tailwind for the variant set.
-4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` → `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` → `<FormControl>` → `<FormMessage>`. Validation messages come from the zod schema, mirrored to design-brief microcopy.
+1. Import primitives from the project's `components/ui/` path
+   (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
+2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` →
+   `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap
+   `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
+3. Use the variant API of `Button` (`variant="default" | "destructive" |
+   "outline" | "secondary" | "ghost" | "link"`); do not override with
+   raw Tailwind for the variant set.
+4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` →
+   `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` →
+   `<FormControl>` → `<FormMessage>`. Validation messages come from
+   the zod schema, mirrored to the design-brief microcopy.
 
 ### Step 2: Apply tokens, dark mode, a11y
 
-1. Colors via semantic classes: `bg-background`, `text-foreground`, `bg-primary text-primary-foreground`, `text-muted-foreground`. No `bg-white` / `text-black` / hardcoded `#fff`.
-2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius` in `tailwind.config.{js,ts}`). Polish refactors hardcoded values when a token equivalent exists.
-3. Dark mode: never branch on a `dark` prop; rely on `.dark` class on root and semantic tokens.
-4. Every interactive primitive: keyboard trigger present (Enter/Space on buttons, Esc on dialogs — Radix free), visible focus ring, `aria-label` from `state.ui_design.a11y` when icon-only.
+1. Colors via semantic classes: `bg-background`, `text-foreground`,
+   `bg-primary text-primary-foreground`, `text-muted-foreground`. No
+   `bg-white` / `text-black` / hardcoded `#fff`.
+2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius`
+   in `tailwind.config.{js,ts}`). Polish refactors hardcoded values
+   when a token equivalent exists.
+3. Dark mode: never branch on a `dark` prop; rely on the `.dark` class
+   on the root and semantic tokens.
+4. Every interactive primitive: keyboard trigger present (Enter/Space
+   on buttons, Esc on dialogs — Radix free), visible focus ring,
+   `aria-label` from `state.ui_design.a11y` when icon-only.
 
 ### Step 3: State coverage
 
-1. Empty: render design-brief empty-state copy in a `Card` or inline placeholder; never `null`.
-2. Loading: `Skeleton` rows for tables; `Button` `disabled` + `Loader2` icon for submit-in-flight.
-3. Error: `Alert variant="destructive"` with design-brief message; `FormMessage` for field-level errors.
-4. Success: `toast.success(...)` from `sonner` with design-brief confirmation copy.
-5. Disabled: `disabled` prop on trigger plus design-brief reason as `aria-describedby` text.
+1. Empty: render the design-brief empty-state copy in a `Card` or
+   inline placeholder; never `null`.
+2. Loading: `Skeleton` rows for tables; `Button` `disabled` +
+   `Loader2` icon for submit-in-flight.
+3. Error: `Alert variant="destructive"` with the design-brief message;
+   `FormMessage` for field-level errors.
+4. Success: `toast.success(...)` from `sonner` with the design-brief
+   confirmation copy.
+5. Disabled: `disabled` prop on the trigger plus the design-brief
+   reason as `aria-describedby` text.
 
 ### Step 4: Validate
 
 1. No raw `<input>` / `<button>` / `<select>` outside the primitive set.
 2. No hardcoded colors / spacing — every value is a token.
 3. Microcopy matches `state.ui_design.microcopy` byte-for-byte.
-4. Dark mode: toggle `.dark` on `<html>`, render the component, every surface still legible (no `text-white on bg-white`).
+4. Dark mode: toggle `.dark` on `<html>`, render the component, every
+   surface still legible (no `text-white on bg-white`).
 5. Keyboard: Tab through every focusable element; focus ring visible.
 
 ## Output format
 
-1. React component file(s) under project's `components/` (or `app/`) tree, importing primitives from `@/components/ui/*`.
-2. Per file, one entry recorded in `state.changes` with `kind="ui"`, `stack="react-shadcn"`, and the design-brief summary.
+1. React component file(s) under the project's `components/` (or `app/`)
+   tree, importing primitives from `@/components/ui/*`.
+2. Per file, one entry recorded in `state.changes` with `kind="ui"`,
+   `stack="react-shadcn"`, and the design-brief summary.
 
 ### Review pass — a11y findings + preview envelope
 
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Run a11y tool against rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`, `jest-axe`) and translate hits into this shape. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Run an a11y tool against the
+  rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`,
+  `jest-axe`) and translate hits into this shape. Use the same
+  `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so the
+  engine's de-dup matches pre-existing entries on replay. Omit the
+  envelope on apply passes; the engine's `_apply_a11y_gate` only fires
+  when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 
 ## Do NOT
 
@@ -109,13 +180,15 @@ Polish dispatch: when dispatcher skips `review` because previous review pass ret
 - Do NOT hardcode colors / spacing / radii — use the token map.
 - Do NOT branch on a `dark` prop — use semantic tokens + the `.dark` class.
 - Do NOT rewrite microcopy — it is locked by `state.ui_design`.
-- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar Radix wrappers — breaks the accessibility contract.
-- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same surface — pick one system per surface.
+- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar
+  Radix wrappers — it breaks the accessibility contract.
+- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same
+  surface — pick one system per surface.
 
 ## Auto-trigger keywords
 
 - shadcn / shadcn ui / shadcn/ui
-- React component (when project uses shadcn)
+- React component (when the project uses shadcn)
 - Radix primitive
 - Tailwind dark mode
 - React Hook Form + zod