@event4u/agent-config 9.11.0 → 9.13.0

package/dist/agent-src/skills/overbuild-review-lens/SKILL.md

@@ -0,0 +1,201 @@
+---
+model_tier: high
+name: overbuild-review-lens
+description: "Use when a diff builds more than the task needs — code that should not exist, a dependency the platform already covers, or a clever form where a flat one reads better. Deletion-hunting, not quality."
+personas:
+  - senior-engineer
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# overbuild-review-lens
+
+> A deletion-hunting lens. It asks one question the other judges never
+> ask: **should this code exist at all?** Sibling of
+> [`architecture-review-lens`](../architecture-review-lens/SKILL.md) and
+> the `judge-*` family — never overlaps with them.
+
+## When to use
+
+- A diff adds a helper, a wrapper, a config layer, an abstraction, or a
+  dependency.
+- A rewrite, v2, or large refactor landed — the peak over-build context
+  (see [`minimal-safe-diff-mechanics`](../../../docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md)
+  § The sanctioned-rewrite trap).
+- A reviewer asks "is all of this needed?", "could the platform do
+  this?", or "why is this so clever?".
+
+Do NOT use when:
+
+- The concern is whether the code is **correct** — route to
+  [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md).
+- The concern is **security** — route to
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md).
+- The concern is **naming, single-responsibility, or convention fit** of
+  code whose existence is not in question — route to
+  [`judge-code-quality`](../judge-code-quality/SKILL.md). That judge asks
+  *is this code malformed*; this lens asks *should it exist*.
+- The concern is **performance** — route to
+  [`performance`](../performance/SKILL.md). Speed is out of scope here.
+- The diff is documentation-only or formatting-only.
+
+## The scope fence — read this before the first finding
+
+```
+CORRECTNESS, SECURITY AND PERFORMANCE ARE OUT OF SCOPE FOR THIS LENS.
+THE MINIMUM RUNNABLE CHECK IS NEVER FLAGGED FOR DELETION.
+A SIZE REDUCTION THAT DROPS A GUARD IS A LOSS, NOT A FINDING.
+```
+
+The measured failure mode this fence exists for: a bare "make it
+simpler" critic was the only arm in a controlled comparison that dropped
+a safety guard — the three lines it saved were a path-traversal check.
+Tests, validation, authorization checks, tenant scoping, and error paths
+that can actually occur are **not** over-build. If removing something
+would reduce coverage of a real case, it is not a finding here.
+
+## Procedure
+
+### 1. Establish what the task actually asked for
+
+Read the ticket / prompt, not just the diff. Over-build is measured
+against the **requirement**, not against your taste. Anything the diff
+adds beyond the requirement is a candidate; anything the requirement
+demands is not, however large.
+
+### 2. Walk each addition down the solution-size ladder
+
+For every new unit (function, class, module, config key, dependency),
+find the highest rung that would have carried it — see
+[`agent-interaction-and-decision-quality`](../../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md)
+§ 8b-ladder:
+
+| Tag | Meaning | The evidence that makes it a finding |
+|---|---|---|
+| `delete:` | This should not exist at all | A fence line (see § 3) — mandatory |
+| `stdlib:` | The language stdlib or framework already does it | Name the exact API and show it is equivalent |
+| `native:` | The OS / runtime / browser / database already does it | Name the platform capability and its availability floor |
+| `yagni:` | Built for a requirement nobody stated | Quote the requirement it exceeds |
+| `shrink:` | Must exist, but smaller | Name the lines that carry no requirement |
+| `flatten:` | Must exist, but in a **simpler form** | Name the cognitive cost, not the line count |
+
+`flatten:` is the shape-axis inverse of `shrink:` — same logic, simpler
+form, **even when that costs a line or two**. Without it the lens only
+ever argues downward and becomes a golfing engine. A nested ternary
+replaced by an `if` block is a valid `flatten:` finding even though the
+diff grows.
+
+### 3. Every `delete:` carries a fence line — no exceptions
+
+Chesterton's Fence, operationalised. Agents are documented as
+especially fence-blind: complex code reads as an invitation to simplify
+when the complexity may exist for a reason the reader has no context
+for. This does not restate
+[`minimal-safe-diff`](../../../src/rules/minimal-safe-diff.md)'s "never
+delete code that *looks* dead without proof" — it is the output contract
+that makes the proof visible.
+
+The fence line has three fields, all required:
+
+```
+Fence: why=<why the code existed — blame, test, issue, or "unknown">
+       safe=<the evidence that removal is safe>
+       covered=<yes|no|partial — was the removed path under test?>
+```
+
+- `why=unknown` is a legal value and it is **not** a pass. It downgrades
+  the finding to a question for the author, never an instruction.
+- `covered=` is the one machine-checkable input to an otherwise
+  archaeological judgement (the Beyoncé rule: if you liked it, you put a
+  test on it). Deleting *tested* behaviour trips a test and is visible;
+  deleting *untested* behaviour breaks silently — so `covered=no` is
+  surfaced as **higher** risk, not as equivalent.
+
+### 4. Emit the null when there is nothing to cut
+
+```
+A LENS THAT CANNOT SAY "NOTHING TO CUT" IS A FINDING GENERATOR.
+```
+
+A lean diff must produce the honest null, not an invented finding. This
+is the load-bearing output, not a fallback: a reviewer who sees findings
+on every diff stops reading them.
+
+### 5. Validate before emitting
+
+- Every finding has a `file:line` and exactly one tag from § 2.
+- Every `delete:` has all three fence fields.
+- No finding restates a correctness, security, or performance concern.
+- The net-lines summary counts `flatten:` findings honestly, including
+  the ones that **add** lines.
+- Zero findings → emit the null block, not an empty issues list.
+
+## Output format
+
+The verdict block carries these ordered fields:
+
+1. `Lens:` — fixed value `overbuild-review-lens`
+2. `Target:` — the diff range or file set reviewed
+3. `Verdict:` — exactly one of `lean` / `trim` / `overbuilt`
+4. `Findings:` — one line per finding: tag, `file:line`, one sentence;
+   `delete:` findings carry their `Fence:` line directly beneath
+5. `Net:` — lines removable if every finding is applied, stated as a
+   signed number so a line-adding `flatten:` is visible
+
+```
+Lens:    overbuild-review-lens
+Target:  <branch / diff range>
+
+Verdict: lean | trim | overbuilt
+
+Findings:
+1. stdlib:  src/util/uuid.ts:1     Hand-rolled v4 generator; crypto.randomUUID covers it.
+2. delete:  src/config/flags.ts:12 Flag read by nothing since the feature shipped.
+   Fence: why=guarded the 2026-03 rollout  safe=zero readers, grep clean  covered=no
+3. flatten: src/parser.ts:88       Nested ternary; an if/else reads flat (+2 lines).
+
+Net: -34 lines
+```
+
+The null, when there is nothing to cut — emit verbatim, do not
+paraphrase:
+
+```
+Lens:    overbuild-review-lens
+Target:  <branch / diff range>
+
+Verdict: lean
+
+Findings: none — nothing in this diff exceeds the stated requirement.
+
+Net: 0 lines
+```
+
+## Gotcha
+
+- **The requirement is the yardstick, not your preference.** A large
+  diff that the ticket demanded is not over-built. Say so and emit the
+  null.
+- **`covered=no` makes a deletion riskier, not more attractive.** The
+  absence of a test is the absence of a tripwire.
+- **A `flatten:` finding that saves lines is suspicious.** If it is
+  shorter *and* simpler it is probably a `shrink:`; `flatten:` exists
+  for the cases where simplicity costs length.
+- **Never flag the minimum runnable check.** One happy-path test is not
+  over-build; it is the floor.
+- **Do not count `delete:` lines that git already removed.** The net
+  figure is about the diff as proposed, not the diff's own deletions.
+
+## Do NOT
+
+- Do NOT emit a `delete:` finding without all three fence fields — the
+  output contract rejects it.
+- Do NOT invent a finding to avoid an empty report.
+- Do NOT review correctness, security, or performance — other surfaces
+  own those, and a size argument against a guard is the canonical
+  failure this lens is fenced against.
+- Do NOT report a size number as a score. A size metric is a
+  measurement, never a target.

package/dist/agent-src/skills/performance/SKILL.md

@@ -28,6 +28,20 @@ Do NOT use when:
 3. Check for N+1 queries on list endpoints.
 4. Search for existing cache services in the project.
 
+**Performance complexity is a claim, and a claim needs evidence.** No cache
+layer, no denormalised column, no materialised view, no read replica ships on
+"this will be slow" — it ships on a profile, a query log, or a timing that names
+the bottleneck. The added complexity is permanent (invalidation bugs, stale
+reads, a second source of truth); the speedup is hypothetical until measured.
+State the measurement in the change, or do not add the mechanism.
+
+**Carve-out — this does not override the `scale-discipline` floor.** Where that
+pack is installed, R-A2 *mandates* an index on every FK and every WHERE / ORDER
+BY column, and R-A4 governs duplicated data by waiver. Those are structural
+defaults that ship with the query, not optimisations awaiting a profiler; the
+evidence gate above applies to *added mechanisms* (caches, denormalisation,
+replicas, bespoke indexes beyond parity), never to the floor's baseline.
+
 ### Step 1: Apply the right fix
 
 | Bottleneck | Fix |

package/dist/agent-src/skills/pixar-storyteller/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: pixar-storyteller
-description: "Use when turning an idea into a Pixar-style animation prompt — character sheet, scene, image, video — anchored in emotional beat, want, obstacle. Triggers 'Pixar prompt', 'animated scene'."
+description: "Use when an idea becomes a Pixar-style animation prompt — character sheet, scene, image, video; emotional beat, want, obstacle. Triggers 'Pixar prompt', 'animated scene'. Live-action → video-director."
 domain: product
 workspaces:
   - small-business
@@ -119,12 +119,15 @@ Any "no" → revise that block.
 
 ## Policies
 
+Paths, enforcement model, and the full set: the
+[media policy preamble](../../../agents/settings/policies/media/README.md).
+
 The Pixar-storyteller skill anchors prompts to named films and studios by design — the policy surface is the largest in the video cluster:
 
-- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — naming a film + year as the *primary* anchor crosses the "in the style of [STUDIO]" trigger; surface and refuse without a transformative-intent rationale.
-- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — when a beat references a named animator's signature character (real-person extension of style).
-- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — when the storyteller's character is a recognised public figure rendered in Pixar shape.
-- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every Pixar-style output ships with the AI-generation disclosure; parody / commentary cases are flagged for human review.
+- **`style`** — naming a film + year as the *primary* anchor crosses the "in the style of [STUDIO]" trigger; surface and refuse without a transformative-intent rationale.
+- **`likeness`** — when a beat references a named animator's signature character (real-person extension of style).
+- **`public-figures`** — when the storyteller's character is a recognised public figure rendered in Pixar shape.
+- **`disclosure`** — every Pixar-style output ships with the AI-generation disclosure; parody / commentary cases are flagged for human review.
 
 Refuse-and-surface when style ⇒ primary signature, not one influence among several.
 

package/dist/agent-src/skills/scene-expander/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: scene-expander
-description: "Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — provider-agnostic, includes optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'."
+description: "Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'. 11-block refine → video-director."
 personas:
   - hollywood-director
 domain: product
@@ -146,13 +146,16 @@ Any "no" → revise that block.
 
 ## Policies
 
+Paths, enforcement model, and the full set: the
+[media policy preamble](../../../agents/settings/policies/media/README.md).
+
 The 12-block Cinematic Scene Blueprint is the policy choke point — every downstream skill (`motion-choreographer`, `video-director`) inherits whatever the blueprint encodes. Before emitting:
 
-- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — when the SUBJECT block names or visually identifies a real person.
-- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — when the SUBJECT block is a recognised public figure.
-- [`agents/settings/policies/media/brand-impersonation.md`](../../../agents/settings/policies/media/brand-impersonation.md) — when STYLE / ENVIRONMENT references a recognised brand's visual identity.
-- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — when STYLE anchors to a named living artist or studio as the primary signature.
-- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every distributed blueprint output carries the AI-generation disclosure downstream.
+- **`likeness`** — when the SUBJECT block names or visually identifies a real person.
+- **`public-figures`** — when the SUBJECT block is a recognised public figure.
+- **`brand-impersonation`** — when STYLE / ENVIRONMENT references a recognised brand's visual identity.
+- **`style`** — when STYLE anchors to a named living artist or studio as the primary signature.
+- **`disclosure`** — every distributed blueprint output carries the AI-generation disclosure downstream.
 
 Refuse-and-surface at the blueprint layer; do not push policy questions down to the adapter.
 

package/dist/agent-src/skills/supply-chain-intake/SKILL.md

@@ -32,6 +32,16 @@ PIN IT, LOCK IT, CVE-SCAN IT. NEVER PIPE A REMOTE SCRIPT STRAIGHT TO A SHELL.
 
 ## Procedure — intake gate (run in order before adding a dependency)
 
+0. **Do you need a dependency at all?** The cheapest supply-chain risk is the
+   one never taken. Walk the rungs above "installed dependency" first — is it
+   already in the tree (`npm ls <pkg>`, `composer show`, `pip list`), does the
+   stdlib or framework carry it, does the **platform** already do it
+   (`crypto.randomUUID` before a uuid package, `Intl` before a formatting
+   library, `AbortSignal.timeout` before a timeout helper, the database's own
+   full-text / JSON support before an application-side index)? Full ordering:
+   [`agent-interaction-and-decision-quality` § 8b-ladder](../../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md).
+   A dependency added for something already present is permanent cost — install
+   surface, CVE surface, upgrade surface — bought against a capability you had.
 1. **Existence** — confirm the exact string resolves on the real registry, published before your session and with real usage:
    ```bash
    npm view <pkg> version        # non-zero exit = does not exist (hallucination)

package/dist/agent-src/skills/typography-system/SKILL.md

@@ -53,7 +53,10 @@ degrades gracefully: with no brand layer, only stage 1 runs.
    `$type: "typography"` and `$value` objects carrying `fontFamily`,
    `fontSize`, `fontWeight`, `lineHeight`.
 5. **Verify** — confirm both chosen fonts exist on Google Fonts (check the
-   `Google Fonts URL` column in the CSV); run
+   `Google Fonts URL` column in the CSV — this is an **availability** check,
+   "does this font exist?", and is deliberately separate from the **delivery**
+   decision, "how does it get onto the page?" — see § Delivery below; conflating
+   the two is what produced a single hard-wired hotlink); run
    `./scripts-run <skills-root>/design-tokens/scripts/tokens validate --dir src/`
    to confirm no hardcoded font-size or font-family values remain outside the
    token file; exit code 0 is the evidence.
@@ -92,6 +95,31 @@ Consumer brand tokens outrank the corpus filter
 ([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)) — if the
 brand already registers fonts, use them and skip the filter.
 
+## Delivery — hosting mode (self-hosted by default)
+
+The delivery policy is **owned** by
+[`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md)
+§ Asset & imagery discipline ([`ADR-205`](../../../docs/decisions/ADR-205-webfont-delivery-ownership.md));
+this skill is a consumer and emits the route, never a competing policy. A font
+CDN link transmits the **visitor's IP** to that third party on every page view —
+a German court (LG München I) ruled on exactly that for hotlinked Google Fonts. <!-- md-language-check: ignore -->
+
+**Default: self-hosted.** Take the row's `Self-Hosted Route` column and resolve
+it against the detected target stack:
+
+| Detected target | Route to emit | Where that answer comes from |
+|---|---|---|
+| Next.js | `next/font/google` (self-hosts at build) or `next/font/local` | `data/stacks/nextjs.csv` rows 22–24 — already prescribes this and lists the CDN `<link>` in its **Don't** column |
+| Any bundler stack (Vite / webpack — React, Vue, Svelte, Nuxt, Astro) | the font's `@fontsource/*` package + a CSS import of the package | the package registry; verify it exists before suggesting it (`supply-chain-intake`) |
+| Server-rendered asset pipeline (Laravel/Vite, Rails, Django) | copy the `woff2` into the project's asset directory, serve it, declare `@font-face` | the project's own pipeline (`design-fidelity-mechanics` § owned-asset path) |
+| No build step / plain HTML | `@font-face` over a locally-served `woff2`, plus `<link rel="preload" as="font">` | `data/stacks/astro.csv` row 23 (preload of a local `woff2`) |
+| Stack unknown | the plain `@font-face` floor, and **say** the route is unresolved — never fall back to the hotlink to avoid the question | — |
+
+**Hotlink: opt-in only.** Emit the row's `CSS Import` value **only** when the
+consumer explicitly asked for the CDN route, and state in the same breath that
+it transmits the visitor's IP to the third party. Never pick it because it is
+the shorter line.
+
 ## Output format
 
 1. **Chosen pairing + rationale** — heading font, body font, the CSV row's
@@ -99,19 +127,31 @@ brand already registers fonts, use them and skip the filter.
 2. **DTCG type-token block** — the `typography` section ready to paste into
    `tokens.json` (DTCG `$type: "typography"`, `$value` with `fontFamily`,
    `fontSize`, `fontWeight`, `lineHeight` per level).
-3. **CSS/Tailwind import line** — the `@import url(…)` from the CSV's
-   `CSS Import` column, and the Tailwind `fontFamily` config snippet from
-   `Tailwind Config`.
+3. **Font delivery block** — the self-hosted route for the detected stack per
+   § Delivery (from the row's `Self-Hosted Route` column), and the Tailwind
+   `fontFamily` config snippet from `Tailwind Config`. The row's
+   `CSS Import` hotlink appears here **only** under an explicit consumer opt-in,
+   with its IP-transmission note.
 
 ## Gotcha
 
-- **Stale CSV URL → silent system-font fallback.** `font-pairings-reference.csv`
-  is Reference data on a freshness contract — never substitute a live Google
-  Fonts API call. If a font was retired or renamed, the `@import` URL 404s at
-  build time and the browser silently falls back to the system font, shipping
-  broken visual design with no obvious error. Always verify the URL resolves
-  (Step 5) before emitting the import line; if it 404s, surface the error and
-  ask the user to pick an alternative pairing from the CSV.
+- **Stale CSV URL → silent system-font fallback (opt-in hotlink path only).**
+  `font-pairings-reference.csv` is Reference data on a freshness contract — never
+  substitute a live Google Fonts API call. If a font was retired or renamed, the
+  `@import` URL 404s at build time and the browser silently falls back to the
+  system font, shipping broken visual design with no obvious error. This caveat
+  **still applies verbatim to the opt-in hotlink route**: verify the URL resolves
+  (Step 5) before emitting the import line; if it 404s, surface the error and ask
+  the user to pick an alternative pairing from the CSV.
+- **The self-hosted default replaces that failure mode, it does not delete it.**
+  For a package route (`next/font`, `@fontsource/*`) resolution moves to
+  **install** time, where a wrong name fails loudly instead of 404-ing at build.
+  What remains is a **family-name mismatch**: the emitted CSS asks for
+  `font-family: 'Inter'` while the installed package provides a differently-named
+  family (`Inter Tight`), which renders the system font at runtime with no error
+  at all — the same silence, one layer later. Assert the family name in the
+  emitted CSS matches the one the installed package declares; the row's
+  `Google Fonts URL` stays useful as the reference spelling to compare against.
 
 ## Do NOT
 
@@ -119,6 +159,10 @@ brand already registers fonts, use them and skip the filter.
   inline) — every size belongs in `tokens.json` under the `typography` layer.
 - Do NOT bypass `design-tokens` and write raw CSS custom properties for fonts
   — `tokens.json` is the single source; hand-crafted `--font-*` vars drift.
+- Do NOT emit a font-CDN `@import` / `<link>` as the default deliverable — the
+  self-hosted route is the default and the hotlink is an explicit opt-in
+  (§ Delivery). Reaching for the CDN line because the stack was not detected is
+  the exact substitution this skill used to hard-wire.
 - Do NOT treat `font-pairings-reference.csv` as decision logic — it is
   Reference data; the agent picks based on the style constraint, not by
   iterating the CSV as a rules engine.

package/dist/agent-src/skills/ui-apply-generic/SKILL.md

@@ -0,0 +1,180 @@
+---
+model_tier: medium
+name: ui-apply-generic
+description: "Use when implementing a UI brief on a stack with no framework executor — Svelte, Astro, Angular, plain HTML. Carries the stack-independent contract; idiom comes from the stack corpus."
+personas:
+  - frontend-engineer
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# ui-apply-generic
+
+> The `plain` lane used to be a name with nothing behind it. This skill is the
+> lane: it carries the implementation discipline that previously lived **only**
+> inside the framework executors, and it gets framework idiom from the 16-stack
+> corpus instead of from prose written here.
+>
+> That split is the whole point. One skill plus a corpus serves Svelte, Astro,
+> Angular, Alpine, htmx and everything future at once. Sixteen framework skills
+> would serve the same set and cost a single maintainer sixteen surfaces to keep
+> current — the enumeration this package refuses.
+
+## When to use
+
+- `state.stack.frontend` resolves to `plain`, or to a label with no
+  framework-specific overlay.
+- A stack whose `axes.reactivity` or `axes.meta` is recognised but has no
+  executor skill (`svelte`, `angular`, `astro`, `solid`, `qwik`, `htmx`).
+- As the base of a composition: an overlay skill (`livewire`, `flux`,
+  `blade-ui`, `react-shadcn-ui`) adds framework specifics **on top** of this
+  contract, it does not replace it.
+
+Do NOT use when a framework executor already covers the whole job — then this
+skill is the base and the executor is the overlay, dispatched together.
+
+## Procedure
+
+### Step 1 — Query the stack corpus (mandatory)
+
+Read `state.stack.axes` and query per resolved axis value, most specific first:
+`meta` → `reactivity` → `component_lib`.
+
+```bash
+<skills-root>/corpus-grounding/scripts/ground search \
+  --manifest <skills-root>/design-intelligence/data/manifest.json \
+  --stack <axis-value> "<the concrete question>"
+```
+
+`axes.meta: nuxt` with `axes.reactivity: vue` means **two** queries —
+`--stack nuxtjs` and `--stack vue`. A meta-framework does not replace the layer
+it wraps; that conflation is the defect the axes exist to fix.
+
+**Cite what you used.** The result names the corpus rows the implementation
+followed. An uncited pick is indistinguishable from the model's memory, and
+memory is exactly what the corpus exists to replace.
+
+**No corpus domain for the detected stack** → say so, in the result:
+
+> No stack corpus for `<stack>` — proceeding on the generic contract. Framework
+> idiom below is not grounded and should be reviewed by someone who knows this
+> stack.
+
+Silence is the failure mode. An unstated gap reads as grounded output.
+
+### Step 2 — Apply the stack-independent contract
+
+Every item is a hard requirement, and none of them is framework-specific:
+
+1. **Verbatim floor.** Microcopy comes from `state.ui_design.microcopy` exactly
+   as written — every label, empty-state line, and validation message. No
+   paraphrase, no improvement. Where a source artifact was provided, it beats
+   the brief (see `design-fidelity`).
+2. **Token discipline.** Colour, spacing, radius and shadow values come from the
+   project's tokens. A raw hex or arbitrary px that no token backs is a finding,
+   not a choice. Validate with `design-tokens`' `tokens validate`.
+3. **Component reuse.** Check `state.ui_audit.components_found` before creating
+   anything. In a run that has already added components, re-read the component
+   directories — the audit inventory is computed once per state-file and does
+   not refresh (see `existing-ui-audit` § Gotchas).
+4. **a11y floor.** Semantic elements over `div` + role; every interactive
+   element reachable and labelled; focus visible; contrast meets the project's
+   stated level, AA when unstated.
+5. **All five states.** `empty`, `loading`, `error`, `success`, `disabled` per
+   the brief. An explicit `n/a` is legitimate for a surface that genuinely has
+   no such state — declaring that is the opposite of inventing filler.
+6. **Asset discipline.** Copy referenced assets into the project's asset path.
+   Never hotlink; never fabricate a logo or a screenshot.
+7. **No placeholders.** `<placeholder>`, `lorem`, `todo:`, `tbd`, `xxx` are
+   rejected at the boundary — including inside arrays.
+
+### Step 3 — Verify, with honest degrade
+
+Exercise the result with whatever the host actually has, and name which:
+
+| Available | Do |
+|---|---|
+| Browser / Playwright | Render, check the states, exercise one interaction |
+| Screenshot only | Capture and inspect layout at 375 / 768 / 1280 |
+| Neither | Static inspection only, and **say** the render is unverified |
+
+Never claim a state or interaction works without having exercised it. A caveat
+is a finding; a silent claim is a defect.
+
+## Output format
+
+Four requirements, in order — each is checkable by a reader of the result:
+
+1. **Name the corpora queried**, or state that none exists for this stack.
+2. **Cite the rows that changed a decision** — not every row read.
+3. **State the verification method and its caveats**, never an unqualified
+   "works".
+4. **List components reused before components added**, so a duplicate is
+   visible rather than buried.
+
+Write `state.ticket["ui_apply"]`:
+
+```yaml
+ui_apply:
+  files: ["resources/js/UserCard.svelte"]
+  rendered:
+    "resources/js/UserCard.svelte": |
+      <full text, microcopy-locked>
+  components_added: ["UserCard"]
+  components_reused: ["Button"]
+  microcopy_lock: true
+  stack_corpus:                 # which corpora answered, or the degrade note
+    queried: ["svelte"]
+    cited: ["svelte.csv:12 — prefer stores over prop drilling"]
+  verify:
+    method: static_inspect      # or playwright / screenshot
+    caveats: ["render not verified — no browser available"]
+```
+
+## Gotchas
+
+- **Do not write framework prose into this skill.** The moment it explains how
+  Svelte stores work, it stops being one maintainable surface and starts being
+  sixteen. Framework knowledge belongs in the corpus.
+- **`axes.reactivity: unknown` is not `none`.** `unknown` means a project has
+  manifests and no recognised reactivity layer — proceed, and say the stack was
+  not recognised. `none` means there genuinely is no reactivity layer, which is
+  the normal shape for a static page.
+- **A meta-framework needs its own query.** Querying only `--stack vue` for a
+  Nuxt project silently drops the routing, data-fetching and SSR idioms that
+  are the whole reason Nuxt exists.
+- **The generic contract is a floor, not a ceiling.** Where an overlay skill is
+  dispatched with this one, its framework rules win on their subject.
+- **The floor now lives in exactly one place, and that is the point.** Overlay
+  composition applies this contract to every lane, so a future change to any of
+  its seven items is a one-point edit here rather than four lane patches that
+  drift apart. Concretely: the five-states requirement reaches every lane
+  through this skill. That requirement is deliberately unconditional — an
+  explicit `n/a` is the escape for a surface that genuinely has no such state
+  (asserted in `ui_lane_matrix.test.ts`), so this is not a defect being
+  broadened. But if the decision is ever revisited, revisit it here.
+
+## Do NOT
+
+- Emit framework code from memory and present it as grounded.
+- Skip the corpus query because the stack "looks obvious".
+- Claim a render or an interaction was verified when no primitive was available.
+- Invent states, sections, or copy the brief does not carry.
+- Treat a missing corpus as an evidence gap — it is a missing pack, and the two
+  must not be recorded the same way.
+
+## See also
+
+- [`design-intelligence`](../design-intelligence/SKILL.md) — the `--stack`
+  corpus this skill queries (16 stacks).
+- [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — the inventory Step 2
+  checks, and its once-per-state-file limit.
+- [`design-tokens`](../design-tokens/SKILL.md) — `tokens validate`.
+- [`fe-design`](../fe-design/SKILL.md) — where the brief's selection decisions
+  come from, and what it does when the corpus is not installed.
+- [`ui-component-architect`](../ui-component-architect/SKILL.md),
+  [`tailwind-engineer`](../tailwind-engineer/SKILL.md) — stack-neutral
+  companions this skill composes with.

package/dist/agent-src/skills/universal-project-analysis/SKILL.md

@@ -31,15 +31,11 @@ Do NOT use when:
 
 ## Mission
 
-Act as the top-level router for deep project investigation.
-
-This skill must:
-
-* confirm whether full-project analysis is justified
-* identify the stack and framework
-* choose the correct analysis mode
-* route to the right specialist analysis skills
-* define the required output for broad project investigations
+Run the deep multi-pass audit itself, and hand each pass to the right
+specialist. Picking *which* skill a request needs in the first place belongs to
+[`analysis-skill-router`](../analysis-skill-router/SKILL.md) — that chooser and
+this orchestrator are deliberately separate files, and the scope test, the
+detection step, and the decision table live there, not here.
 
 This skill must NOT become:
 
@@ -88,9 +84,9 @@ Goal: identify hot paths, find expensive boundaries, route into architecture or
 
 ### 1. Confirm scope
 
-Check whether full-project analysis is really needed.
-Use this skill only if the user wants: broad system understanding, architecture reconstruction, deep multi-layer debugging, broad audit across modules or runtime boundaries.
-If not: route to the narrower specialist skill directly.
+Invoked through the router, this is already settled — proceed. Invoked
+directly, apply the router's scope test before spending a multi-pass audit on
+something a specialist covers.
 
 ### 2. Discover the project
 
@@ -128,36 +124,17 @@ Check:
 * uncertainties are marked
 * conclusions are evidence-based
 
-## Routing map
-
-### Universal analysis skills
-
-* `project-analysis-core`
-* `project-analysis-hypothesis-driven`
-
-### Framework-specific deep dives
-
-* `project-analysis-laravel`
-* `project-analysis-symfony`
-* `project-analysis-zend-laminas`
-* `project-analysis-node-express`
-* `project-analysis-react`
-* `project-analysis-nextjs`
-
-### Optional downstream specialists
-
-* `bug-analyzer`
-* `performance-analysis`
-* `security-audit`
-
-### Ingestion preprocessor
+## Ingestion preprocessor
 
 * `markitdown` — when the project ships PDFs, DOCX, XLSX, PPTX, EPUB,
-  images, or audio that need to feed into any of the analysis skills
-  above. Convert first via the upstream `markitdown-mcp` server, then
+  images, or audio that need to feed into any of the routes in steps 3–4.
+  Convert first via the upstream `markitdown-mcp` server, then
   route the resulting Markdown into the relevant deep-dive skill.
   Never read a binary office format raw.
 
+> The route lists in steps 3 and 4 are the routing map. A second copy of them
+> lived here until 2026-08-02 and was removed — one list, one place.
+
 ## When to add a new framework analysis skill
 
 A framework gets its own `project-analysis-*` skill ONLY if: