git:20261016.e1956ea to git:20261018.e3cf6dc

- ### 0. Inspect stack and input

-

- 1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.ts` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).

- 2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"

-

- ### 1. Enumerate components and templates

-

- | Stack | Where to look |

- |---|---|

- | `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |

- | `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |

- | `vue` | `resources/js/components/`, `src/components/`, `pages/` |

- | `plain` | `resources/views/`, plus any `*.html` under `public/` |

-

- Capture each component/template as:

- `{path, name, kind: component|view|style|page, exports?: [props]}`.

-

- The `kind` set is the one `agent-config ui:audit` actually emits — its single

- definition is `AUDIT_KINDS` in `src/cli/commands/uiAudit.ts`, and a test asserts

- this line against that constant rather than restating it. It read

- `page|partial|component|layout` until 2026-08-26; only two of those four values

- existed in the code, so an artefact written by the command was being read here

- against a contract it did not satisfy.

-

- `partial` and `layout` are not in the set. Neither has an operational definition

- that survives contact with a real tree, and adding a branch for a category

- nobody can test is how the previous mismatch happened.

-

- `view` is the **Blade** classification — `*.blade.php` and `resources/views/`.

- It reads zero in a JavaScript tree by construction, which is not the same as

- unused.

-

- ### 1b. Detect the component-granularity taxonomy the project already chose

-

- ```bash

- npx tsx scripts/work_engine/taxonomy/detect.ts # or import detect_component_taxonomy(root)

- ```

-

- Returns the project's **own** tier names joined with `/` — `atoms/molecules/organisms`, `primitives/patterns/features`, whatever it actually uses — or `none`. Record it as `state.ui_audit.component_taxonomy`, with `state.ui_audit.component_root` for where the components live. `none` is a real answer, and leaves every downstream step behaving exactly as it did before this detection existed. Never write a taxonomy the project does not evidence, and never "tidy" a layout into one — this step *finds* the project's structure, it never supplies one. Detection rules, the declared-beats-inferred precedence and the two collision floors: [`references/component-taxonomy-detection.md`](references/component-taxonomy-detection.md).

-

- ### 2. Identify the design system

-

- Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.

-

- | Marker | Signal | Where |

- |---|---|---|

- | Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |

- | shadcn/ui | `components.json` exists at the **workspace** root — the package that owns it; in a monorepo this is never the repository root | `components.json` |

- | Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |

- | Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |

- | Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |

- | Custom / none | none of the above match | — |

-

- ### 3. Detect design tokens

-

- Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):

-

- | Source | What to extract |

- |---|---|

- | **`tailwind-v3`** (`axes.css`) — `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |

- | **`tailwind-v4`** (`axes.css`) — the `@theme` block in the entry CSS; **no config file exists**, and `components.json` `"tailwind": {"config": ""}` is the marker | every `--token: value` declared inside `@theme` / `@theme inline` |

- | `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |

- | `theme.json` / `tokens.json` (any depth) | flat or nested token tree |

- | `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |

- | **A supplied `design-system.json`** (handed over with a provided artifact) | `colors`, `typography`, `spacing`, `radius`, `shadow`, **and `motion`** (`durations`, `easings`) — read as the answer, never re-derived |

- | **A supplied artifact's own `:root { --… }` / inline `<style>`** (the handover file itself, e.g. `design.html`) | every `--token-name: value` pair, when no `design-system.json` accompanies it |

-

- Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.

-

- **Branch on the axis, do not probe for a config file.** `detect_stack()` emits

- `axes.css` as `tailwind-v3` or `tailwind-v4`

- (`work_engine/stack/detect.ts:521-524`); reading it is how this step and

- `react-shadcn-ui` § Gotcha stay on the same key. Absence of

- `tailwind.config.*` is v4's normal state, never a missing file.

-

- **Artifact-sourced tokens stay distinguishable from project tokens.** Every

- group carries a `source` — `project` for the first four rows, `artifact` for the

- last two — because the mapping between them is the thing a port has to keep

- visible. Collapsing them loses the answer to "did this value come from what the

- user handed me, or from what the repo already had?", and that is exactly the

- question the apply coverage report has to answer per item. The two sets may

- disagree; when they do, surface the conflict rather than merging it (a supplied

- spec outranks house taste, but not a registered brand token — see

- [`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).

-

- `motion` is new here: the block has existed in the `design-system.json` schema

- since capture shipped and **nothing consumed it**. On the port branch it is

- read, so easing and duration stop being values the brief silently regenerates.

-

- ### 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)

-

- Read `components.json` for the registered style + base color, then read the `package.json` **of the scope root** — `state.stack.scope_root`, relative to the project root, empty when the project root *is* the scope — for `@radix-ui/*` or the unified `radix-ui` package, plus any locally vendored `components/ui/*.tsx` files. In a monorepo the repository root carries neither the marker nor the dependency, so reading it finds nothing. Write into `state.ui_audit.shadcn_inventory`:

-

- ```

- {

- version: <from package.json shadcn registry CLI version, or null>,

- style: "default" | "new-york" | <other>,

- base_color: "slate" | "zinc" | ...,

- primitives: ["Button", "Dialog", "Form", "Table", ...], // names of files in components/ui/

- installed_radix: ["@radix-ui/react-dialog", ...] // raw radix list

- }

- ```

-

- ### 4b. Prefer a live Storybook read over the hand-read inventory — when one is running

-

- When the project carries `@storybook/addon-mcp` **and** a Storybook is running, query it

- instead of reading files: `docs-list` for the inventory, then `docs-show` for the components

- that matter. **The live read wins; the hand-read inventory of step 4 is the fallback and is

- never removed** — an agent that cannot reach a running Storybook must still be able to

- inventory the library. The channel disappearing is normal, not an error.

-

- **The names are version-bound, and these are the current ones.** Own derivation, from a

- throwaway `npm install` on 2026-09-13, not from any document: at `@storybook/addon-mcp@10.6.0`

- the docs tools are registered by `storybook`'s own `createDocsToolset` under the method ids

- `docs.list` / `docs.show` / `docs.showStory`, and `toMcpToolName` renders those as `docs-list`,

- `docs-show` and `docs-show-story`. The older `list-all-documentation` / `get-documentation` were

- the literal names at `@storybook/addon-mcp@0.7.0` (via `@storybook/mcp@0.8.0`); at 10.6.0 they

- survive only as the tools' human-readable **titles**. There is no 10.5.x of the addon — it goes

- 0.7.0 → 10.6.0 — so a project on the current scaffold gets the `docs-*` names. If a live

- `tools/list` disagrees, the live read wins over this paragraph.

-

- **React-only while the toolset is in preview.** Storybook's own MCP FAQ (docs **10.5**,

- `docs/ai/mcp/overview` § FAQ) states the documentation toolset supports React only during

- preview, so Vue, Angular, and Web Components take the file-read path. Stated here rather than

- discovered at runtime, because the failure otherwise looks like a broken MCP server.

-

- Discipline for what the live read returns is [`storybook-workshop`](../storybook-workshop/SKILL.md)'s

- — in particular: never use a prop the manifest does not document, and fetch the project's

- story instructions before writing a story.

-

- ### 5. List reusable patterns

-

- Categorize what already exists. Empty arrays are valid, never omit the keys.

-

- ```

- state.ui_audit.patterns = {

- forms: [<component path:str>, ...], // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>

- tables: [...], // <table>, <flux:table>, DataTable, headless table primitives

- modals: [...], // <flux:modal>, <Dialog>, AlertDialog, Sheet

- empty_states: [...], // components matching grep "no results"|"empty"|"keine"|"nothing yet"

- navigation: [...], // sidebar, breadcrumb, tabs

- data_display: [...] // cards, lists, stat tiles

- }

- ```

-

- ### 6. Match candidates for the current input

-

- For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:

-

- ```

- [{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]

- ```

-

- If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.

-

- #### 6b. Conformance gate — when a provided artifact is the spec

-

- Similarity above is scored against `state.input.data`. That answers *"is this

- component like the thing being asked for"* and it does **not** answer *"does

- this component satisfy the artifact"* — which is a different question with a

- different answer, because a candidate can be an excellent name-and-props match

- and still use the wrong type scale, the wrong control, or a colour the artifact

- never states. Until this step existed nothing anywhere asked the second

- question, while `ui-audit-gate` carried *"reuse

- beats duplication"* as unqualified prose. Reused on an artifact port, an

- unconforming candidate is a fidelity deviation dressed as good hygiene.

-

- So when a provided design artifact is the spec

- ([`design-fidelity`](../../rules/design-fidelity.md)), each candidate carries a

- **conformance verdict** alongside its score, and reuse is conditional on it:

-

- ```

- [{path, name, score, reason,

- conformance: {verdict: "conforms|deviates|unknown",

- dimensions: {structure, values, behaviour, responsive},

- refused_by: "values"}}, ...]

- ```

-

- - **`conforms`** → reuse it. This is the ordinary case and nothing changed.

- - **`deviates`** → do **not** reuse silently. Name the dimension that refused

- it — *"`Card` deviates on `values`: type scale 14/20 against the artifact's

- 16/24"* — and surface reuse-with-adaptation versus build-new as a choice.

- A bare "candidate rejected" is not a discharge; the caller cannot act on it.

- - **`unknown`** → the candidate was not scored against the artifact (no

- extraction yet, or a subtree the audit could not read). Treat as `deviates`

- for the purpose of not reusing silently, and say which of the two it is —

- "did not conform" and "was not checked" are different facts.

-

- **And the decision moves after extraction, not before it.** A conformance

- verdict needs the artifact's own values, so a reuse decision taken before

- extraction is taken without the evidence that decides it. Where the run has an

- artifact, order is: extract → audit → score → conform → decide. The unqualified

- reuse-first ordering stands only where there is no artifact to conform to.

-

- **Scope:** this is a gate on REUSE, not a license to rewrite the incumbent. A

- candidate that deviates is left alone; the choice is whether *this* work builds

- on it.

-

- ### 7. Greenfield branch

-

- If **all** are true:

- - `state.ui_audit.components` is empty

- - `state.ui_audit.design_system == "custom-or-none"`

- - `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)

-

- then set `state.ui_audit.greenfield = true` and emit a halt:

-

- ```

- > No existing UI surface detected — this looks like greenfield.

- >

- > 1. Scaffold a minimal token set + a base component primitive folder

- > before building (recommended for projects with >1 planned screen)

- > 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)

- > 3. Point me at an external design-system reference (URL or file)

- > 4. Scaffold + a granularity convention — as 1, and new components go into

- > named granularity folders you pick the names for; rename or drop it later

- > and nothing here objects

-

- **Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen

- benefits from a shared base; the scaffold cost is ~10 min and saves

- re-doing every primitive on screen 2. Caveat: flip to 2 if this is a

- demo or single-page prototype that will not grow.

- ```

-

- Option 4 is an **offer**, and the only one made anywhere: a project that already exists is never asked (§ 1b reads what it chose), and a greenfield project picking any other number has declined terminally, because the halt is a no-op once any decision is recorded. It stays one more number in the same block rather than a second question — a single number still answers it, which is what the reply-shape rule requires.

-

- Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference` | `granularity_convention`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay). `granularity_convention` takes the same scaffold path as `scaffold` — it adds the convention, it does not replace the scaffolding.

-

- ### 8. (Optional) Capture an a11y baseline

-

- The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`

- when present; the review gate then filters incoming

- `state.ui_review.a11y.violations` against it so pre-existing

- violations stay informational and only NEW or CHANGED entries block

- the polish loop. Without a baseline the gate sees every violation as

- actionable — fine for greenfield, noisy for legacy surfaces.

-

- Capture the baseline when:

-

- - The audit covers components with known a11y debt the project does

- not intend to fix in this run (legacy templates, third-party

- embeds, vendor widgets).

- - The user says "don't block on existing a11y issues" or similar.

-

- Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`

- unset) when:

-

- - The surface is greenfield — the review gate should treat every

- violation as new.

- - The project's a11y posture is "zero known violations" and any

- finding is by definition actionable.

-

- Shape (each entry must carry at least `rule` + `selector`; severity

- is optional but recommended so the review gate's severity-floor

- filter behaves the same on replay):

-

- ```

- state.ui_audit.a11y_baseline = [

- {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},

- {rule: "label", selector: "form#search input[type=search]"},

- ...

- ]

- ```

-

- Producer parity: the review skill that writes

- `state.ui_review.a11y.violations` MUST use the same `(rule, selector)`

- shape, otherwise the engine's de-dup will miss matches and pre-existing

- violations will surface as new findings on every run.

-

- ### 9. Validate and write findings

- 1. Verify every key in the **Output format** below is present in `state.ui_audit` (empty arrays/objects allowed; `null` only for `shadcn_inventory` outside the react-shadcn stack).

- 2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.

- 3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.