@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/skills/persona-writing/SKILL.md

@@ -0,0 +1,158 @@
+---
+model_tier: inherit
+name: persona-writing
+description: "Use when creating or editing a persona in src/agent-src/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: degrade -->
+
+# persona-writing
+
+## When to use
+
+* Creating a new persona file in
+  `src/agent-src/personas/{id}.md`
+* Rewriting an existing persona (focus shift, output-expectation
+  change — not a typo fix)
+* Deciding whether a new reviewer voice should be a persona at all
+  (vs. a skill of its own)
+
+Do NOT use this skill when:
+
+* The content is a multi-step workflow → use
+  [`skill-writing`](../skill-writing/SKILL.md)
+* The content is a hard obligation the agent must always honor → use
+  [`rule-writing`](../rule-writing/SKILL.md)
+* The content describes the project's role-mode contract → that lives
+  in `docs/guidelines/agent-infra/role-contracts.md`, not in personas
+
+## Persona vs skill vs role-mode — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Agent should review through a specific lens" | **Persona** |
+| "Agent should run a multi-step workflow" | **Skill** |
+| "Agent's closing contract differs by role" | **Role-mode** (contract file) |
+
+A persona is **passive reference content** — it never triggers by
+description, never appears in `<available_skills>`. Skills cite
+personas via the `personas:` frontmatter key.
+
+## Procedure
+
+### 0. Drafting protocol
+
+Creating or materially rewriting a persona must go through
+Understand → Research → Draft per the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
+rule. Inspect existing personas under
+`src/agent-src/personas/` for overlap before writing a new
+one.
+
+### 1. Decide focus, not topic
+
+A persona owns **one focus**: automation-readiness, adversarial
+challenge, product-owner priorities, etc. If the focus needs three
+sentences, it is two personas.
+
+### 2. Draft the persona file
+
+Required sections:
+
+* `## Focus` — one paragraph, what this lens *cares about* and what
+  it *ignores*.
+* `## Unique questions` — 4–7 questions only this persona would ask.
+  Each question must be decidable against the artifact under review.
+* `## Output expectations` — what the persona produces (verdict
+  format, severity vocabulary, citation discipline).
+
+Optional: `## Anti-patterns this persona catches` — concrete examples
+the persona is calibrated to flag.
+
+### 3. Cite from at least one skill
+
+A persona that is not cited by any skill via the `personas:`
+frontmatter key is dead code. Either wire it into an existing skill
+or do not ship it.
+
+## Frontmatter shape
+
+```yaml
+---
+id: <kebab-case-id>
+role: <Human-Readable Role>
+description: "One sentence: what this voice catches that others miss."
+tier: core | specialty
+mode: developer | product-owner | qa | stakeholder | none
+version: "1.0"
+source: package
+---
+```
+
+The `mode:` field is advisory only — it suggests which role-mode the
+persona pairs naturally with; it does not bind.
+
+## Output format
+
+A single Markdown file at `src/agent-src/personas/{id}.md`:
+
+1. Frontmatter (`id`, `role`, `description`, `tier`, `mode`,
+   `version`, `source`)
+2. `## Focus` — one paragraph, what the lens cares about and ignores
+3. `## Unique questions` — 4–7 decidable questions
+4. `## Output expectations` — verdict format, severity vocabulary
+
+Length: ≤ 80 lines for a tier-core persona; longer signals the focus
+is too broad.
+
+## Gotchas
+
+- **Persona without a citing skill** — a persona that no skill
+  references via `personas:` never loads. Wire it in or do not ship.
+- **Focus drift across rewrites** — adding "and also …" to `## Focus`
+  is the first symptom of a second persona hiding inside the first.
+- **Vibe-based unique questions** — "Does this feel right?" cannot
+  be evaluated against the artifact. Replace with decidable triggers.
+- **Restating role-mode contracts** — closing-contract obligations
+  belong in `docs/guidelines/agent-infra/role-contracts.md`, not in the persona
+  body.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every persona you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, `## Focus` opens with what
+  the persona cares about, not "This persona was created to…".
+- Per the cite-don't-restate principle, link rules the persona
+  enforces; do not paste their text into the persona body.
+- Per the cheap-question check, `## Unique questions` lists decidable
+  questions only — drop any that read like vibe checks.
+
+**Pre-save self-check:**
+1. Does `## Focus` open with the lens, or with persona meta-narrative?
+2. Are unique questions decidable against the artifact alone?
+3. Are any questions duplicated from another persona?
+4. Is the persona cited by at least one skill via `personas:`?
+
+## Do NOT
+
+* Author a persona that nobody cites.
+* Restate Iron-Law text from rules inside `## Output expectations`.
+* Use ALL-CAPS Iron-Law fenced blocks — those belong in rules on the
+  [`kernel-membership`](../../../docs/contracts/kernel-membership.md)
+  list.
+* Ship a persona that overlaps an existing one's focus by more than
+  50 % — merge instead.
+
+## Examples
+
+See `src/agent-src/personas/ai-agent.md` (automation
+readiness) and `critical-challenger.md` (adversarial review) for
+canonical structure.

package/dist/agent-src/skills/prompt-validator/SKILL.md

@@ -0,0 +1,167 @@
+---
+model_tier: inherit
+name: prompt-validator
+description: "Pre-spend contradiction gate for AI-video runs: checks every prompt in the batch, blocks on style / character / physics mismatch. Triggers 'validate the prompts', 'check the storyboard'."
+personas:
+  - ai-video-technical-director
+domain: product
+workspaces:
+  - small-business
+packs:
+  - ai-video
+lifecycle: experimental
+trust:
+  level: experimental
+install:
+  default: false
+  removable: true
+---
+
+# prompt-validator
+
+> Deterministic pre-spend gate: collect **every** prompt a video run is
+> about to send (all scenes, all blocks), cross-check against each other
+> and against the run's locked facts (character lock, vocal map, model
+> capabilities), **block with a specific error** on contradiction.
+> Skills are deterministic — a multi-scene batch fails by
+> *contradiction*, not drift: two prompts that cannot both be true of
+> the same video (AI-council convergence, 2026-06-06). One blocked
+> batch costs a re-edit; one rendered contradiction costs the whole
+> spend.
+
+## When to use
+
+- Immediately **before** the unified storyboard/cost preview gate in
+  [`/video:from-song`](../../commands/video/from-song.md)
+  Step 8 / [`/video:from-script`](../../commands/video/from-script.md) —
+  after every scene's eight-block prompt exists, before anything is
+  shown for approval or sent live.
+- After an operator hand-edits scene prompts (`/video:scene` re-runs) —
+  re-validate the batch, not just the edited scene.
+
+Do NOT use when:
+
+- Only a single scene exists (nothing to contradict) — per-scene checks
+  in `video-director` cover internal consistency.
+- Pure preview with no approval intent — validate when the batch is
+  about to be gated, not on every draft keystroke.
+
+## Inputs
+
+- `<project>/script.md` — every `## Scene N` (duration, mood, action,
+  camera, dialogue).
+- Every rendered scene prompt (eight-block image/video prompts from
+  `video-director` / blueprint JSON), in scene order.
+- `<project>/character.json` — when present, the locked identity
+  (subject, palette, wardrobe, prop, seed).
+- `<project>/vocal-map.json` — when present, the signed-off
+  line → singer assignments.
+- The chosen model's capability entry (`capability --model <id>`).
+
+## Procedure
+
+### 1. Collect the full prompt set
+
+Read every scene's prompt blocks into one table:
+`scene → {style, subject, environment, action, camera, lens, lighting,
+mood, duration, aspect, dialogue/singer}`. Prompt missing or
+unparseable → **block**: `scene N: prompt missing/unreadable` — an
+incomplete batch already contradicts the script.
+
+### 2. Style consistency
+
+`style` block must agree across all scenes — one look per video unless
+the script *names* an intentional break (e.g. "dream sequence").
+
+- Conflicting render families (`photorealistic` vs `cel-shaded` /
+  `claymation` / `watercolor`) with no scripted break →
+  `style mismatch: scene 3 'photorealistic' vs scene 7 'cel-shaded'`.
+- Conflicting era/grade tokens (`1970s film grain` vs `clean digital
+  HDR`) → same error shape, name both scenes + both tokens.
+
+### 3. Character consistency (character mode)
+
+With `character.json` present, every scene naming the subject must
+match the lock:
+
+- Wardrobe / palette / prop drift (`red coat` locked, scene says
+  `blue jacket`) → `character mismatch: scene 5 'blue jacket' vs lock
+  'red coat'`.
+- A scene inventing a second recurring subject the script never cast →
+  flag — uncast identities break continuity AND the likeness gate.
+- **Lip-sync ownership:** a scene with a `dialogue:` line must name the
+  vocal map's singer for that line — wrong mouth on wrong words is the
+  render-money-burning failure (`media-sync-ground-truth`). A `"?"`
+  singer with a lip-sync scene → block until resolved.
+
+### 4. Physics + continuity
+
+- Day/night or weather flips **inside one contiguous song section**
+  with no scripted transition → `continuity: scene 4 'noon sun' →
+  scene 5 'starry night' within the same chorus`.
+- Impossible camera/action pairs (`locked-off tripod` + `whip pan`),
+  (`underwater` + `desert dust`) → name scene + both tokens.
+- Duration / aspect vs. model envelope: any scene outside
+  `[min_duration, max_duration]` or with an unlisted aspect → block
+  with the violated bound (defense-in-depth after `song-to-script`
+  Step 1 — hand-edited prompts re-open this hole).
+
+### 5. Verdict
+
+- **Zero findings** → emit `prompt-validator: N scenes, no
+  contradictions`, hand the batch to the preview gate.
+- **Any finding** → **block the gate**. Report every finding (not just
+  the first), each as `class: scene(s) + conflicting values + fix
+  hint`. Operator (or calling command) fixes prompts, re-runs the
+  validator — never "approve anyway" past a contradiction; an
+  intentional break gets *scripted* (named in `script.md`), which
+  legitimizes it on the next pass.
+
+## Output format
+
+1. One line per finding — `class: scene(s) + conflicting values + fix
+   hint` — and report **every** finding, never just the first.
+2. Terminal `verdict:` line: `OK` with the scene count, or
+   `BLOCKED (N contradictions) — fix and re-run`; a blocked verdict
+   never hands the batch to the preview gate.
+
+```
+prompt-validator: 12 scenes checked
+✅ style: one look (neo-noir, consistent)
+❌ character: scene 5 'blue jacket' vs character.json 'red coat' — align scene 5 or update the lock
+❌ lip-sync: scene 9 dialogue assigned to 'Freya' but vocal-map line 24.5-27.8 is singer '?' — resolve the singer first
+verdict: BLOCKED (2 contradictions) — fix and re-run
+```
+
+## Gotchas
+
+- **An intentional style break is scripted, not waved through.** Only a
+  break `script.md` names is accepted; "operator said it's fine in
+  chat" does not survive to the next run.
+- **Re-validate after every hand-edit.** One edited scene can
+  contradict five untouched ones; the batch is the unit, not the scene.
+- **`verified: false` capability entries still gate.** Blocking on a
+  documented-best-effort bound beats rendering past a real one; the
+  report names the unverified flag — override by editing the manifest,
+  never by skipping the check.
+
+## Do NOT
+
+- Do NOT auto-fix prompts — report and block; the fix is the operator's
+  (or calling skill's) edit, visible in the diff.
+- Do NOT validate only changed scenes — always the full batch.
+- Do NOT soften a contradiction into a warning — contradictions block;
+  only consistency passes.
+- Do NOT duplicate `video-director`'s per-scene craft checks — this
+  skill owns *cross-scene* contradiction only.
+
+## See also
+
+- [`/video:from-song`](../../commands/video/from-song.md) — invokes this
+  before the unified storyboard/cost preview gate (Step 8).
+- [`video-director`](../video-director/SKILL.md) — produces the prompts
+  this skill cross-checks.
+- [`character-consistency`](../character-consistency/SKILL.md) — the
+  lock this skill enforces against.
+- [`song-to-script`](../song-to-script/SKILL.md) — upstream timing +
+  vocal-map source.

package/dist/agent-src/skills/prompt-validator/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "prompt-validator",
+  "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger covers the pre-spend batch-contradiction gate (style / character / physics / lip-sync ownership). Should-not-trigger covers near-miss neighbors: single-prompt craft (video-director), LLM prompt tuning (prompt-optimizer / prompt-engineering-patterns), and vocal-map validation (validate-vocal-map.sh path).",
+  "queries": [
+    {"q": "validate the prompts before we render", "trigger": true},
+    {"q": "check the storyboard for contradictions", "trigger": true},
+    {"q": "do the scene prompts contradict each other?", "trigger": true},
+    {"q": "run the contradiction gate over the whole batch", "trigger": true},
+    {"q": "scene 5 says blue jacket but the character lock says red coat — check the full set", "trigger": true},
+    {"q": "improve this prompt for better image quality", "trigger": false, "note": "single-prompt craft — video-director / image prompting"},
+    {"q": "write the prompt for scene 3", "trigger": false, "note": "prompt authoring, not cross-scene validation"},
+    {"q": "validate the vocal map against the transcript", "trigger": false, "note": "validate-vocal-map.sh / song-to-script Step 3, not prompt contradiction"},
+    {"q": "review my ChatGPT system prompt", "trigger": false, "note": "routes to prompt-optimizer"},
+    {"q": "optimize the prompt for the LLM router", "trigger": false, "note": "routes to prompt-engineering-patterns"}
+  ]
+}

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

@@ -0,0 +1,235 @@
+---
+model_tier: medium
+name: react-shadcn-ui
+description: "Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - react
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+execution:
+  type: assisted
+  handler: shell
+  safety_mode: strict
+  allowed_tools:
+    - npx
+---
+
+# react-shadcn-ui
+
+> **Grounded stack guidance:** pull idiomatic Do/Don't + docs URLs via
+> `ground.py search --manifest <skills-root>/design-intelligence/data/manifest.json
+> --stack shadcn "<topic>"` (also `--stack react`, `--stack nextjs`). See
+> [`design-intelligence`](../design-intelligence/SKILL.md).
+
+## Component installer — `scripts/shadcn_add.py` (gated, assisted)
+
+Bundled installer (Apache-2.0-derived, see header + `design-intelligence/ATTRIBUTION.md`)
+wraps `npx shadcn@latest add <components>` — **the only subprocess+network
+surface in the adopted suite**. Per `runtime-safety` + the `execution`
+block above:
+
+1. **Propose, never silent-run** — show exact `npx` command + component list first (`--dry-run`); user confirms before live run.
+2. **Missing tool** → per `missing-tool-handling`: `npx`/Node absent → STOP and ask (install vs manual copy) — never silently work around.
+3. **Verify after run** — `components/ui/<name>.tsx` exists, `components.json` unchanged or sanely updated, before reporting success.
+
+## Compatibility
+
+- **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
+- 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).
+
+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.
+
+## 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. 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.
+- **Anti-AI-slop: shadcn-default look.** The out-of-the-box shadcn
+  theme + `Inter`-as-system-fallback + neutral grays reads as
+  template across projects. Unless `state.ui_audit.design_tokens`
+  pins the neutral palette as the project's identity, the polish
+  step should match typography and color tokens to the design
+  brief's `aesthetic:` line (from `fe-design` aesthetic-direction).
+  Theme/font drift within a single audited project breaks
+  consistency — variation lives between projects, not between
+  components in the same surface.
+
+## Covered primitives
+
+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`.
+- **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
+- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`,
+  `Avatar`, `Skeleton`, `Progress`.
+- **Feedback:** `Toast` (sonner), `Alert`.
+
+## Not covered — fall back to manual composition
+
+- 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.
+
+## 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, 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.**
+   - `states` → empty / loading / error / success / disabled coverage.
+   - `a11y` → ARIA labels, keyboard nav, focus order.
+
+### Step 1: Compose primitives
+
+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 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 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`).
+5. Keyboard: Tab through every focusable element; focus ring visible.
+
+## Output format
+
+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 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
+
+- Do NOT install `shadcn-ui` from npm — primitives are scaffolded.
+- 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 — 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 the project uses shadcn)
+- Radix primitive
+- Tailwind dark mode
+- React Hook Form + zod