@event4u/agent-config 9.10.0 → 9.12.0

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/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.10.0"
+agent_config_version: "9.12.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/scripts/work_engine/directives/ui/apply.ts

@@ -17,14 +17,25 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
-import { PLACEHOLDER_PATTERNS } from './design.js';
+import { placeholder_paths } from './design.js';
+import {
+    is_ambiguous_stack,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
 /** Map `state.stack.frontend` → agent-directive skill name. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
+    'blade-livewire': 'ui-apply-blade-livewire',
+    filament: 'ui-apply-filament',
     'react-shadcn': 'ui-apply-react-shadcn',
+    react: 'ui-apply-react',
     vue: 'ui-apply-vue',
     plain: 'ui-apply-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-apply-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -104,47 +115,40 @@ function _resolve_directive(state: DeliveryState): string {
     return DEFAULT_DIRECTIVE;
 }
 
-/** Return paths into `envelope['rendered']` whose text matches a pattern. */
+/**
+ * Return paths into `envelope['rendered']` whose text matches a pattern.
+ *
+ * Delegates to the walker shared with `design`, so the producer-side and
+ * consumer-side gates cannot drift apart. They previously held
+ * byte-identical copies of the same array-blind recursion, which meant the
+ * contract's "defense-in-depth" framing described two layers that failed on
+ * exactly the same inputs.
+ */
 function _placeholder_violations_in_output(envelope: Record<string, Any>): string[] {
-    const rendered = envelope['rendered'];
-    if (!_isDict(rendered)) {
-        return [];
-    }
-    const violations: string[] = [];
-    _walk_rendered(rendered, '', violations);
-    return violations;
-}
-
-function _walk_rendered(node: Record<string, Any>, prefix: string, violations: string[]): void {
-    for (const key of Object.keys(node)) {
-        const value = node[key];
-        const path = prefix ? `${prefix}.${key}` : String(key);
-        if (_isDict(value)) {
-            _walk_rendered(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
-        for (const pattern of PLACEHOLDER_PATTERNS) {
-            if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
-            }
-        }
-    }
+    return placeholder_paths(envelope['rendered']);
 }
 
 /** First-pass halt — emit the stack-specific apply directive. */
 function _delegate_to_stack_skill(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);
     const stack_label = _stack_label(state);
+    if (is_ambiguous_stack(state.stack)) {
+        const conflicts = ((state.stack as Record<string, Any>)['ambiguity'] ??
+            []) as ReadonlyArray<string>;
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('apply', conflicts),
+            message:
+                `UI apply halted: detection is ambiguous (${conflicts.join('; ')}) — ` +
+                'the open question is which project to build for.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
+            bundle_line(state.stack, 'build', stack_label),
             '> Microcopy is locked — every button label, empty-state ' +
                 'message, and validation message must come verbatim from ' +
                 '`state.ui_design.microcopy`.',

package/dist/agent-src/templates/scripts/work_engine/directives/ui/design.ts

@@ -146,7 +146,17 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
             missing.push(key);
             continue;
         }
-        if (key === 'states' && _isDict(value)) {
+        if (key === 'states') {
+            // A non-object `states` (a string, a list) used to skip the
+            // per-state loop entirely, so `states: "n/a"` satisfied the gate
+            // without covering a single state. Report every required key
+            // instead — the author gets the same actionable list either way.
+            if (!_isDict(value)) {
+                for (const state_key of REQUIRED_STATE_KEYS) {
+                    missing.push(`states.${state_key}`);
+                }
+                continue;
+            }
             for (const state_key of REQUIRED_STATE_KEYS) {
                 if (!_pyTruthy(value[state_key])) {
                     missing.push(`states.${state_key}`);
@@ -157,37 +167,74 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
     return missing;
 }
 
-/** Return microcopy paths whose values match a placeholder pattern. */
+/**
+ * Return brief paths whose values match a placeholder pattern.
+ *
+ * Covers `microcopy` **and** `states`. The five required states were checked
+ * for truthiness only, so `states.error: "TBD"` satisfied the gate — the brief
+ * looked complete while covering nothing. Both slots carry strings the user
+ * signs off on, so both are held to the same bar.
+ *
+ * An explicit `"n/a"` stays legitimate: a static landing page genuinely has no
+ * error or disabled state, and *declaring* that is the opposite of inventing
+ * filler. That is why the gate demands all five keys rather than branching on
+ * page type — the author states the answer instead of the engine guessing which
+ * states a surface ought to have.
+ */
 function _placeholder_violations(design: Record<string, Any>): string[] {
-    const microcopy = design['microcopy'];
-    if (!_isDict(microcopy)) return [];
+    return [
+        ...placeholder_paths(design['microcopy'], 'microcopy'),
+        ...placeholder_paths(design['states'], 'states'),
+    ];
+}
+
+/**
+ * Return every path under `node` whose leaf string carries a placeholder.
+ *
+ * Traverses objects **and arrays**. The array arm is load-bearing, not
+ * defensive: a list is the natural shape for the most common microcopy
+ * (`nav_items`, `menu`, `steps`) and for a rendered file split into lines,
+ * and a walker that recursed into objects only let
+ * `{ nav_items: ["Home", "TODO: Link"] }` through both the brief lock and
+ * the rendered-output gate.
+ *
+ * Array elements are addressed `key[i]` so the halt names the exact element
+ * the author has to fix, not just the list.
+ *
+ * Shared by `design` (producer side, on `microcopy`) and `apply` (consumer
+ * side, on the rendered envelope). One implementation on purpose: the two
+ * call sites previously carried byte-identical copies of the same bug, so
+ * duplicating them bought no independence — see
+ * `docs/contracts/ui-track-flow.md` § implement → apply.
+ */
+export function placeholder_paths(node: Any, prefix = ''): string[] {
     const violations: string[] = [];
-    _walk_microcopy(microcopy, '', violations);
+    _walk_placeholders(node, prefix, violations);
     return violations;
 }
 
-function _walk_microcopy(
-    node: Record<string, Any>,
-    prefix: string,
-    violations: string[],
-): void {
-    for (const key of Object.keys(node)) {
-        const value = node[key];
-        const path = prefix ? `${prefix}.${key}` : String(key);
-        if (_isDict(value)) {
-            _walk_microcopy(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
+function _walk_placeholders(node: Any, prefix: string, violations: string[]): void {
+    if (typeof node === 'string') {
+        const lowered = node.toLowerCase();
         for (const pattern of PLACEHOLDER_PATTERNS) {
             if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
+                violations.push(prefix);
+                return;
             }
         }
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((value, index) => {
+            _walk_placeholders(value, `${prefix}[${index}]`, violations);
+        });
+        return;
+    }
+    if (_isDict(node)) {
+        for (const key of Object.keys(node)) {
+            const path = prefix ? `${prefix}.${key}` : String(key);
+            _walk_placeholders(node[key], path, violations);
+        }
     }
 }
 
@@ -311,15 +358,23 @@ function _halt_unconfirmed(state: DeliveryState, design: Record<string, Any>): S
     });
 }
 
-/** Count leaf string entries in `microcopy` (recursive). */
-function _count_microcopy(microcopy: Record<string, Any>): number {
-    let total = 0;
-    for (const value of Object.values(microcopy)) {
-        if (_isDict(value)) {
-            total += _count_microcopy(value);
-        } else if (typeof value === 'string') {
-            total += 1;
-        }
+/**
+ * Count leaf string entries in `microcopy` (recursive, arrays included).
+ *
+ * The count is shown in the sign-off the user confirms, so it has to agree
+ * with what the placeholder walker inspects — an object-only count reported
+ * fewer locked strings than were actually locked.
+ */
+function _count_microcopy(microcopy: Any): number {
+    if (typeof microcopy === 'string') return 1;
+    if (Array.isArray(microcopy)) {
+        return microcopy.reduce((total: number, value) => total + _count_microcopy(value), 0);
+    }
+    if (_isDict(microcopy)) {
+        return Object.values(microcopy).reduce(
+            (total: number, value) => total + _count_microcopy(value),
+            0,
+        );
     }
-    return total;
+    return 0;
 }

package/dist/agent-src/templates/scripts/work_engine/directives/ui/polish.ts

@@ -15,6 +15,11 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    is_ambiguous_stack,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
 /** Maximum number of polish rounds per `/work` run. */
 export const POLISH_CEILING = 2;
@@ -31,9 +36,15 @@ export const TOKEN_REPEAT_THRESHOLD = 2;
 /** Map `state.stack.frontend` → agent-directive skill name. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-polish-blade-livewire-flux',
+    'blade-livewire': 'ui-polish-blade-livewire',
+    filament: 'ui-polish-filament',
     'react-shadcn': 'ui-polish-react-shadcn',
+    react: 'ui-polish-react',
     vue: 'ui-polish-vue',
     plain: 'ui-polish-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-polish-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -184,6 +195,17 @@ function _delegate_to_polish_skill(
     ceiling: number,
 ): StepResult {
     const directive = _resolve_directive(state);
+    if (is_ambiguous_stack(state.stack)) {
+        const conflicts = ((state.stack as Record<string, Any>)['ambiguity'] ??
+            []) as ReadonlyArray<string>;
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('polish', conflicts),
+            message:
+                `UI polish halted: detection is ambiguous (${conflicts.join('; ')}) — ` +
+                'the open question is which project to build for.',
+        });
+    }
     const stack_label = _stack_label(state);
     const next_round = rounds + 1;
     let findings_line =
@@ -203,6 +225,7 @@ function _delegate_to_polish_skill(
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Polish round ${next_round} of ${ceiling}.`,
+            bundle_line(state.stack, 'build', stack_label),
             findings_line,
             '> Fix chart-type / contrast findings against the adopted ' +
                 "corpus rows (design-intelligence § 'Grounding the " +

package/dist/agent-src/templates/scripts/work_engine/directives/ui/review.ts

@@ -16,13 +16,24 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    is_ambiguous_stack,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
-/** Map `state.stack.frontend` → agent-directive skill name. */
+/** Map `state.stack.frontend` → agent-directive verb. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-design-review-blade-livewire-flux',
+    'blade-livewire': 'ui-design-review-blade-livewire',
+    filament: 'ui-design-review-filament',
     'react-shadcn': 'ui-design-review-react-shadcn',
+    react: 'ui-design-review-react',
     vue: 'ui-design-review-vue',
     plain: 'ui-design-review-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-design-review-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -181,12 +192,24 @@ function _stack_label(state: DeliveryState): string {
 function _delegate_to_review_skill(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);
     const stack_label = _stack_label(state);
+    if (is_ambiguous_stack(state.stack)) {
+        const conflicts = ((state.stack as Record<string, Any>)['ambiguity'] ??
+            []) as ReadonlyArray<string>;
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('review', conflicts),
+            message:
+                `UI review halted: detection is ambiguous (${conflicts.join('; ')}) — ` +
+                'the open question is which project to build for.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
+            bundle_line(state.stack, 'review', stack_label),
             '> The review pass compares `state.ticket.ui_apply.rendered` ' +
                 'against `state.ui_design` (microcopy, states, a11y, layout) ' +
                 'and produces a structured `findings` list.',