@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/dogfood-sweep/SKILL.md

@@ -1,1000 +0,0 @@
----
-name: dogfood-sweep
-description: Six-mode static + visual sweep across `/site/components/*`, `apps/`, `playgrounds/`, `catalog/`. Modes — (1) component visual probe (headless Chromium), (2) app-shell static QA, (3) HTML typo sweep, (4) native-primitive leak (`<button>` vs `<button-ui>`, `<input>` vs `<input-ui>`, etc.), (5) admin-shell composition (flags FEEDBACK-41 cluster — `<admin-statusbar>` / `[data-spacer]` / `[data-actions]` missing — the 2026-05-23 claims-ui regression class), (6) component anatomy + card header sweep (card-ui `<header><div>` wrapper anti-pattern + missing anatomy sections per FB-52). Triggers on "run dogfood sweep", "scan component pages", "find broken demos", "visual-QA all components", "audit native primitive leaks", "find raw `<button>` usage", "any `<button>` instead of `<button-ui>`?", "audit admin-shell composition", "shell composition audit", "find shells missing statusbar", "is the admin-shell complete?", "audit card header anatomy", "scan card-ui div wrappers", or scheduled `dogfood-*` routines.
----
-
-# dogfood-sweep
-
-Walks every `/site/components/*` demo page in headless Chromium and runs
-the visual-correctness probes that type-checks and tests don't catch.
-Emits a severity-ranked report, applies the unambiguous fixes, opens a
-PR with the report and any landed diffs.
-
-The script (`.agents/skills/dogfood-sweep/analyze.mjs`) is the data gatherer. This
-skill is the orchestrator: env setup, triage, fixes, PR.
-
-## When to use
-
-- A scheduled routine triggers the skill (CRON every 4h is the default
-  cadence — short enough to catch regressions before they ship, long
-  enough that the cache stays meaningful).
-- A human asks to "dogfood the components", "scan the demos for visual
-  bugs", "run the headless visual sweep".
-- After a wide refactor of token semantics, slot vocabulary, or
-  component-stamping patterns — exactly the changes that silently break
-  demos but pass the verify gate.
-
-## What the script catches
-
-| # | Probe | Bug class |
-|---|-------|----------|
-| 1 | Zero-area | Element collapsed: parent `display:none`, toolbar overflow spilled it, layout glitch |
-| 2 | Transparent fill | `[data-swatch]` / variant pill / button / chart indicator with `rgba(0,0,0,0)` background — fallback token doesn't resolve (the chart-legend `--chart-N` class) |
-| 3 | Empty control | `input-ui` / `search-ui` whose `connected()` should have stamped internals but didn't |
-| 4 | Synonym-attr / synonym-slot drift | Markers from `docs/conventions/attribute-api-migration.md` (`avatar-ui[name]`, `grid-ui[cols]`, `card-ui [slot=meta]`, `stepper-ui[current]`, `stepper-item-ui[state]`) |
-| 5 | Alert flex-row | `alert-ui` with multiple bare `<text-ui>` children (need `<col-ui slot="content">` wrap) |
-| 6 | **Missing component CSS** | `*-ui` tag rendered on page but no stylesheet matching `/components/{prefix}/{prefix}.css` loaded. Catches the swap-to-primitive-but-forget-the-link class — markup looks right, JS registers the element, listbox renders **unstyled**. Added 2026-05-04 after a real miss. |
-| 7 | **Unstyled popover** | `[popover]:popover-open` with transparent background + zero padding. Visual-symptom probe for the same class as #6, from the runtime side. |
-| 8 | Console | Every `console.error` + `console.warn` during page load + 800ms settling |
-
-Severity:
-- **critical** — page is visibly broken; element collapsed, swatch
-  transparent, control un-stamped.
-- **warning** — likely-broken composition the layout will silently
-  mis-render (e.g. alert flex-row).
-- **info** — synonym-attribute or deprecation drift; not breaking,
-  sweep when convenient.
-
-## Workflow
-
-```bash
-# 1. Fresh checkout / clean tree.
-git checkout main && git pull
-npm install --frozen-lockfile
-
-# 2. Start dev server in the background. Wait for "ready".
-npm run dev > /tmp/vite.log 2>&1 &
-DEV_PID=$!
-for i in {1..30}; do
-  grep -q "ready in" /tmp/vite.log && break
-  sleep 1
-done
-
-# 3. Run the analyzer. Exits 1 iff any critical findings.
-node .agents/skills/dogfood-sweep/analyze.mjs
-ANALYZER_EXIT=$?
-
-# 4. Stop the dev server.
-kill $DEV_PID 2>/dev/null
-```
-
-The report lands at `docs/reports/dogfooding-YYYY-MM-DD.md`.
-
-## Triage rules
-
-For each **critical** finding, evaluate independently:
-
-1. **Diagnosis right?** Cross-check with component source. Probes are
-   probabilistic — `tab-ui`/`list-ui` 0×0 height, for example, is often
-   a logical-marker case, not a bug.
-2. **Fix mechanical and unambiguous?** Decision rule below; if you'd
-   need to negotiate with a human about *what* the right fix is, leave
-   it for the human.
-3. **Pattern documented?** Cross-check
-   `docs/conventions/attribute-api-migration.md` and the project memory
-   under `~/.claude/projects/-Users-kimba-Projects-chat-ui/memory/`.
-
-Apply the fix iff all three are true.
-
-## Fix decision rules (apply unattended)
-
-| Finding kind | Mechanical fix | Source-of-truth |
-|--------------|----------------|------------------|
-| `transparent-fill` on `[data-swatch]` with inline `var(--chart-N)` fallback | Swap fallback to `var(--a-data-N)` in component CSS + JS | Memory: hard rule 6 ("All colors must reference --a-chrome-*, --a-data-0..9, or semantic tokens") |
-| `drift` on `<avatar-ui name=…>` | `perl -i -pe 's/(<avatar-ui[^>]*?\s)name=/\1text=/g'` | `MIGRATION GUIDE.md` v0.0.20 section item 9 |
-| `drift` on `<grid-ui cols=…>` | `cols=` → `columns=` via the same perl pattern | `attribute-api-migration.md` |
-| `drift` on `<stepper-ui current=…>` | `current=` → `step=` | same |
-| `drift` on `<stepper-item-ui state=…>` | drop the attribute (parent drives via `[step]`) | same |
-| `drift` on `<card-ui [slot="meta"]>` | nest the tag inside `slot="heading"` (heading is `display: flex`) | `attribute-api-migration.md` |
-| `alert-flex-row` | wrap multi-element body in `<col-ui slot="content" gap="0-5">` | `attribute-api-migration.md` |
-
-Do **NOT** auto-fix:
-
-- `zero-area` findings — diagnosis varies (intentional empty-state
-  demo, logical-marker pattern, real bug). Always human-eyeballed.
-- `empty-control` on a component the skill doesn't recognize.
-- Any finding with severity `warning` that lacks a documented fix
-  recipe in the table above.
-- More than 5 mechanical fixes per PR — bound the blast radius so
-  humans can review fix shape before scaling to a sweep.
-
-## Verification gate after any fix
-
-Per `AGENTS.md`:
-
-```bash
-node scripts/build/components.mjs --verify   # must print "clean"
-npm run test:a2ui                             # must be 25/0/1 or better
-node .agents/skills/dogfood-sweep/analyze.mjs              # the original critical
-                                              # finding must be gone
-```
-
-If any gate fails after applying a fix, **revert the fix and file the
-finding for human review** instead of opening a broken PR.
-
-## After harvest
-
-Always commit the report file under `docs/reports/`, even when zero
-critical/warning findings — it's a paper trail of "things were fine on
-this date", which is the data the agent uses to detect when something
-*used* to be fine and is now broken.
-
-If chunks regenerated as a side effect of any fix, run
-`npm run harvest:chunks`.
-
-## PR shape
-
-```
-title: dogfood: <YYYY-MM-DD> — <N> critical, <M> warning
-body:
-  ## Findings
-
-  ${first 100 lines of the report}
-
-  Full report: [docs/reports/dogfooding-${date}.md](...)
-
-  ## Auto-applied fixes (${K})
-
-  - [x] avatar-ui name= → text= in packages/web-components/components/table/index.html (5 instances)
-  - [x] (etc.)
-
-  ## Left for human review (${L})
-
-  - zero-area on tab-ui (logical marker; needs human eyeball)
-  - (etc.)
-```
-
-Title is bounded so it sorts naturally in the PR list. Body always
-includes the report excerpt + link.
-
-## Repo touchpoints
-
-- Script: [`analyze.mjs`](analyze.mjs) (sibling file).
-- Script docs: [`README.md`](README.md) (sibling file).
-- Reports archive: `docs/reports/dogfooding-*.md`
-- Probe contract source: probes are inline in `analyze.mjs`. New probe →
-  add to that file's `runProbes()` or `runStampContractProbe()`, then
-  document the bug class it catches in the table above.
-
-## When to expand the probe set
-
-- New component ships with internal stamping logic → add to
-  `STAMP_CONTRACTS` in `analyze.mjs`.
-- New synonym-attribute drift class documented in
-  `attribute-api-migration.md` → add to `DRIFT_MARKERS`.
-- A class of bugs slips past the analyzer in a real PR → add a probe
-  for that bug class first, **then** fix the bug. Test for the test.
-
-## Cadence rationale
-
-4-hour CRON cadence chosen because:
-
-- Pages drift on the order of hours, not days, when a wide-refactor
-  PR lands. A daily sweep would let a regression sit half a day.
-- The full sweep is ~3 minutes (82 pages × ~2s each), bounded by
-  Playwright's networkidle. Cheap to run.
-- The Anthropic prompt cache is 5-minute TTL, so 4h sweeps don't
-  share cache but each fully amortizes their own miss.
-- Pre-merge checks should still catch most regressions; this is the
-  belt-and-braces layer for the things that slip through.
-
----
-
-## § App Shell QA
-
-Mechanical QA sweep across every `apps/<name>/.../<page>.html` shell.
-Pairs with dogfood-sweep (both run headless check scripts over HTML files)
-but targets the Shell + Fragment + Controller trio pitfalls (ADR-0021)
-rather than component visual correctness.
-
-### When to use
-
-- After any `apps/` structural sweep — new app, page-trio migration,
-  cluster rollup, contents.js refactor.
-- Before tagging a release — the trio convention is consumer-facing;
-  broken shells deploy as 404s on EXE.
-- When a single playground regresses visually and you suspect a class
-  issue rather than a one-off.
-- On request: "audit app shells", "QA the playgrounds", "find broken
-  app pages", "shell sweep".
-
-### What the script catches
-
-The six pitfalls from `docs/conventions/composition-and-examples.md § Pitfalls when shell-ifying`:
-
-| # | Pitfall | Audit finding |
-|---|---------|---------------|
-| 1 | Co-located custom-elements not imported | `[unregistered-tag] <tab-ui>` (lives in `tabs/tab.js`, not `tab/`) |
-| 2 | Demo-root flex chain broken | `[demo-root-flex] body is full-height flex but #demo-root has display:block flex:0` |
-| 3 | Composite renders internal *-ui tags HTML doesn't show | `[unregistered-tag] <textarea-ui>` when only `<chat-input-ui>` is in the markup |
-| 4 | Top-level await without async setup wrap | `[setup-failed] contents.js setup failed:` console error |
-| 5 | Vite import-analysis 500 on dynamic import | `[network-4xx] 500 import-analysis` for `./<name>.contents.js` |
-| 6 | icon-ui not imported despite `<icon-ui>` / `[icon=…]` / composites that render icons | `[icon-ui-missing]` |
-
-Plus three secondary signals:
-- `[collapsed-element] <foo-ui> is 0px tall` — element registered but layout collapsed.
-- `[unregistered-tag] <bar-ui>` for any non-CSS-only primitive.
-- `[network-4xx]` — typoed `<link rel="stylesheet">` href, missing contents.html,
-  or a stale `import.meta.url` reference.
-
-False positives already filtered: CSS-only components (`aside-ui`, `header-ui`,
-`section-ui`, `footer-ui`), inherently-thin elements (`divider-ui`,
-`separator-ui`), empty containers with no children.
-
-### How to run
-
-```bash
-# Full sweep (~2 min wall-clock, 73 shells × ~1.5s each)
-node scripts/dev/audit-app-shells.mjs
-
-# One page (debug a specific finding)
-node scripts/dev/audit-app-shells.mjs --only=chat
-
-# Stop on first issue
-node scripts/dev/audit-app-shells.mjs --fail-fast
-
-# Diff against prod to see what's locally regressed
-node scripts/dev/audit-app-shells.mjs --compare-prod
-```
-
-Prerequisites:
-1. `npm run dev` must be running (vite on `:5173`)
-2. `npm run proxy` (or `node packages/llm/server.js`) for the LLM proxy (only if probing chat / gen-ui)
-
-If vite is mid dep-reoptimization, the first sweep may stall. Wait 30s, then re-run.
-
-### Expected output
-
-Clean run: each shell line prints a green checkmark with finding count = 0.
-Any findings print the pitfall tag + a one-line description. Exit code 0 when
-no critical findings; exit code 1 on any critical.
-
-### When to escalate
-
-Apply the fix recipes from `docs/conventions/composition-and-examples.md`
-for pitfalls 1–6 unattended. Escalate to human review when:
-- A finding cannot be matched to a known pitfall (unexpected tag name, novel
-  import pattern, framework-level error in console).
-- More than 10 shells are affected — bound blast radius.
-- The fix would alter shared catalog/ or packages/ files (not just the shell).
-
-### Fix recipes (summary)
-
-Full recipes in `docs/conventions/composition-and-examples.md § Pitfalls when shell-ifying`.
-Quick index:
-
-- **Pitfall 1** — add `import "/packages/web-components/components/tabs/tab.js"` (co-located sibling).
-- **Pitfall 2** — add `#demo-root { flex: 1; display: flex; flex-direction: column; min-height: 0; }`.
-- **Pitfall 3** — import every primitive the composite renders internally (see composite table below).
-- **Pitfall 4** — wrap top-level `await` in `export default async function setup(host) { ... }`.
-- **Pitfall 5** — add `/* @vite-ignore */` to the dynamic import.
-- **Pitfall 6** — add `import "/packages/web-components/components/icon/icon.js"` to shell head or contents.js.
-
-Known composites and their internal primitives:
-
-| Composite | Internally renders |
-|-----------|-------------------|
-| `chat-input-ui` | `textarea-ui`, `select-ui` |
-| `search-ui` | `input-ui` |
-| `empty-state-ui` | `icon-ui`, `text-ui` |
-| `button-ui` (with `icon=`) | `icon-ui` |
-| `badge-ui` (with `icon=`) | `icon-ui` |
-| `menu-item-ui` | `icon-ui`, `text-ui` |
-
-### Verification
-
-1. Apply diffs.
-2. Re-run `node scripts/dev/audit-app-shells.mjs`. Target: 0 findings on real issues.
-3. Spot-check the worst-affected page in a real browser.
-4. Commit: `fix(repo-org): icon-ui imports in N contents.js — empty-state, theme toggle, send button missing`
-
-### Related artifacts
-
-- Audit script: `scripts/dev/audit-app-shells.mjs`
-- Pitfalls + recipes: `docs/conventions/composition-and-examples.md § Pitfalls when shell-ifying`
-- Page-trio convention: ADR-0021 (`.brain/adrs/0021-page-shell-contents-controller-trio.md`)
-- Apps directory layout: ADR-0020 (`.brain/adrs/0020-apps-and-component-demo-co-location.md`)
-
----
-
-## § HTML Typo Sweep
-
-Find and fix a specific, high-frequency HTML authoring bug: attribute values
-that open with `"`, embed additional `"` characters unescaped, and close with
-another `"` — breaking the attribute boundary and confusing the HTML parser.
-Both this sweep and the dogfood analyzer operate on static HTML files,
-making them natural companions.
-
-### The bug class
-
-Canonical broken pattern:
-
-```html
-<div data-artifact-label="name="attachment"">
-```
-
-The parser sees:
-- `data-artifact-label=""` — value empty (closes at the second `"`)
-- `attachment` — a new, unquoted attribute
-- `""` — a stray empty-valued attribute
-
-Common offenders: `data-artifact-label`, `data-note`, `aria-label`, `title`, `alt`.
-
-### When to use
-
-- User says "fix html typos", "sweep for broken attributes", "check for nested
-  double quotes", "audit html for this pattern".
-- You just fixed one instance in one file and the user asks whether the same
-  bug exists elsewhere.
-- A commit touches docs/demo HTML at scale; use as a pre-flight check.
-
-### When NOT to use
-
-- Fixing a single isolated typo in one file (use targeted edit directly).
-- Fixing broader HTML issues: missing closing tags, malformed nesting, bad entity
-  references. This skill does one thing only.
-- JavaScript string literals or template-literal HTML inside `<script>` blocks.
-- Non-HTML files (Markdown with inline HTML blocks, JSX, Vue templates).
-
-### Detection regex
-
-Use the **narrow** audit regex — a broad regex produces thousands of false
-positives on legitimate multi-attribute tags:
-
-```js
-// Narrow: an attribute closes with " and the next char is not whitespace or >
-const AUDIT = /ATTR_NAME="[^"]*"(?=[^\s>])/g;
-```
-
-Audit loop — Node one-shot:
-
-```js
-import fs from 'node:fs';
-import path from 'node:path';
-
-function walk(dir) {
-  const out = [];
-  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-    const p = path.join(dir, e.name);
-    if (e.isDirectory()) out.push(...walk(p));
-    else if (e.name.endsWith('.html')) out.push(p);
-  }
-  return out;
-}
-
-const ATTR = 'data-artifact-label';                  // the attr to sweep
-const ROOT = 'site';                                 // the tree to scan
-const RE   = new RegExp(`${ATTR}="[^"]*"(?=[^\\s>])`, 'g');
-
-let total = 0;
-const perFile = [];
-for (const f of walk(ROOT)) {
-  const html = fs.readFileSync(f, 'utf8');
-  let m, count = 0;
-  while ((m = RE.exec(html)) !== null) count++;
-  if (count) { total += count; perFile.push({ f, count }); }
-}
-console.log(`${total} broken across ${perFile.length} files`);
-for (const { f, count } of perFile) console.log(`  ${count}\t${f}`);
-```
-
-Report per-file counts to the user before fixing. If count is zero, stop.
-
-### Fix procedure
-
-Fix regex — captures intended value, stops at `>` so it never crosses a
-tag boundary:
-
-```js
-const FIX = new RegExp(
-  `${ATTR}="([^>]*[a-z0-9][a-z0-9_-]*="[^"]*")"(?=[\\s>])`,
-  'g',
-);
-```
-
-Wrap the captured value in single quotes on the outside (HTML allows
-single-quoted attribute values; preferred over `&quot;` for readability):
-
-```js
-const fixed = html.replace(FIX, (_m, value) => {
-  if (value.includes("'")) {
-    const escaped = value.replace(/"/g, '&quot;');
-    return `${ATTR}="${escaped}"`;
-  }
-  return `${ATTR}='${value}'`;
-});
-```
-
-After the automated pass, re-run the Phase 1 audit. Any remaining hits are
-edge cases (trailing prose, no outer `ident=` prefix) — fix each individually
-with a targeted edit. Don't extend the automated regex for these.
-
-### Which attributes to sweep
-
-Start with the attribute the user flagged, then iterate in order:
-
-1. `data-artifact-label` — design-system demo pages label each example.
-2. `data-note` — often holds prose with example attribute syntax inline.
-3. `aria-label` — often authored as `aria-label="Save "foo""`.
-4. `title` — tooltip text with inline attribute citations.
-5. `alt` — image alt text occasionally references attributes.
-6. `placeholder` — rare, but seen.
-
-Run each attribute independently. Do NOT glob `ANY_ATTR="..."` in one regex.
-
-### Verification
-
-All three must pass before declaring the sweep done:
-
-1. **Zero remaining** — re-run the Phase 1 audit. Expected: `0` broken values across 0 files.
-2. **Tag balance** — for each touched file, count opening vs closing tags:
-   ```js
-   const openDiv  = (html.match(/<div\b/g) || []).length;
-   const closeDiv = (html.match(/<\/div>/g) || []).length;
-   // Expect openDiv === closeDiv. Same for section, grid-ui, article, etc.
-   ```
-3. **HTTP spot check** — if a dev server is running, sample-curl a handful of fixed pages:
-   ```bash
-   for p in breadcrumb stat input upload; do
-     code=$(curl -s -o /dev/null -w "%{http_code}" \
-       "http://localhost:5174/site/pages/components/$p/index.html")
-     echo "$code  $p"
-   done
-   ```
-
-### Anti-patterns
-
-- **Never sweep with a broad regex** like `="[^"]*"[^"]*"` across all attributes.
-- **Never auto-fix with the non-greedy version of the capture** — it stops at
-  the first `"` and captures only `name=` instead of `name="attachment"`.
-- **Never edit `<script>` block content with these regexes** — embedded JS
-  strings have different quoting rules.
-- **Never silently skip edge cases** after the automated pass. Phase 1
-  re-audit is non-optional.
-- **Never commit the one-shot fix script to the repo.** Use `/tmp` or `node -e`.
-
-### Output format to user
-
-```
-Swept `data-artifact-label` across site/**/*.html:
-- 86 fixes across 21 files (automated regex).
-- 4 edge cases fixed manually (trailing prose / no outer ident= prefix):
-  calendar-picker (1), menu (1), segmented (2).
-
-Verification:
-- Final audit — 0 remaining broken values.
-- Tag balance — div/section/grid-ui match on all 22 touched files.
-- HTTP spot check — 200 on 13 sampled pages.
-```
-
----
-
-## § Native Primitive Leak Audit
-
-Static-HTML probe that **flags questionable implementations** where an
-agent (or human) reached for a native HTML primitive (`<button>`,
-`<input>`, `<select>`, `<textarea>`, `<a href>`, `<img>`, `<table>`)
-inside a composition surface (`apps/`, `playgrounds/`, `catalog/`)
-when an AdiaUI `*-ui` primitive exists.
-
-**Distinct from the component-CSS-loaded probe (#6 above)**: that probe
-catches "you used `<button-ui>` but forgot the CSS link"; this probe
-catches "you used `<button>` instead of `<button-ui>` at all". Same
-bug-class family (design-system bypass) from the opposite direction.
-
-**Why this exists**: AdiaUI is light-DOM substrate (ADR-0033). Native
-primitives bypass theme tokens, focus-ring discipline, accessibility
-patterns, and the trait registry. Even when type-checks + visual
-sweeps pass, raw `<button>` is a smell — usually an agent
-short-circuit, occasionally a legitimate escape hatch (file pickers,
-hidden inputs, content-loaded images).
-
-### When to use
-
-- After any wide authoring sweep where an agent generated screens
-  (genui rendering session, page-shell template authoring,
-  catalog/ui-patterns rollouts).
-- Before tagging a release — questionable native primitives are
-  consumer-facing smells.
-- On request: "audit native primitive leaks", "find raw button usage",
-  "flag questionable HTML implementations", "scan for non-adia
-  primitives", "any `<button>` instead of `<button-ui>`?", "any
-  `<input>` instead of `<input-ui>`?".
-- As part of the dogfood CRON sweep — pairs with the visual probes
-  to catch both "wrong CSS" (#6/7) and "wrong tag" (this).
-
-### How to run
-
-```bash
-# Default — criticals + warnings only, info hidden
-node scripts/dev/audit-native-primitive-leak.mjs
-
-# Show all findings including info-level (<a href>, <img>)
-node scripts/dev/audit-native-primitive-leak.mjs --all
-
-# Promote <a href> probe to warning severity (off by default — too noisy
-# given how often raw <a> is legitimate for navigation/anchors)
-node scripts/dev/audit-native-primitive-leak.mjs --strict-links
-
-# Restrict to a specific tag
-node scripts/dev/audit-native-primitive-leak.mjs --tag=button
-
-# Restrict to a specific directory
-node scripts/dev/audit-native-primitive-leak.mjs --include=apps/genui
-
-# JSON output for downstream processing
-node scripts/dev/audit-native-primitive-leak.mjs --json
-
-# Strict mode — any finding (incl. info) fails the build
-node scripts/dev/audit-native-primitive-leak.mjs --strict
-```
-
-Exit codes: `0` = no critical findings; `1` = ≥1 critical (or any finding in `--strict`).
-
-### What the probe catches
-
-| Tag | Severity | AdiaUI equivalent | Escape hatches (NOT flagged) |
-|-----|----------|-------------------|------------------------------|
-| `<button>` | **critical** | `button-ui` | None — always a smell |
-| `<input>` | **critical** | `input-ui` | `type="hidden"`, `type="file"`, `type="radio"`, `type="checkbox"` |
-| `<select>` | **critical** | `select-ui` | None |
-| `<textarea>` | **critical** | `textarea-ui` | None |
-| `<table>` | **critical** | `table-ui` | None |
-| `<a href>` | info (warning with `--strict-links`) | `link-ui` | Bare `<a name=…>` anchors (no `href`) |
-| `<img>` | info | `image-ui` | None automatic — `<img>` is often legit for content-loaded assets |
-
-**Skipped automatically**:
-- Showcase demos at `packages/web-components/components/<name>/<name>.html`
-  — these legitimately demonstrate native usage in code-block examples
-- Native primitives inside `<code>`, `<pre>`, `<script>`, `<style>` blocks
-  — code examples, not rendered DOM
-- Native primitives inside the matching primitive's own component
-  directory (e.g. `<input>` inside `packages/web-components/components/input/`
-  is stamp-internal)
-- `node_modules`, `.git`, `dist`, `build`, `.brain`
-
-### Intentional escape hatch — annotation
-
-When a native primitive IS the right answer (file picker, hidden
-field, content-loaded image, anchor with custom semantics, code-editor
-input that's not a form field, docs-index table that's not a data
-widget), annotate adjacent to the tag so the audit demotes the finding
-to `info`. Two equivalent forms:
-
-**Attribute form (most reliable — preferred)**:
-
-```html
-<input type="file" data-native-ok="file picker, no upload-ui equiv" accept=".json" />
-```
-
-**Preceding-comment form**:
-
-```html
-<!-- native-ok: file picker, no upload-ui equivalent -->
-<input type="file" accept=".json" />
-```
-
-The audit checks a **200-char window before** the opening tag for
-intent markers (`<!-- native-ok:` or `data-native-ok=`). The window
-was widened from 80 chars in commit `<post-§3-commit>` after a peer
-agent found that realistic preceding-line comments (indent + comment
-prefix + reason text + closing `-->` + newline) sat at exactly the
-80-char boundary and were not detected. The attribute form is still
-more reliable because it lives INSIDE the opening tag — no window
-math needed.
-
-Intent markers within the window demote the finding to `info`-level
-(still visible in `--all` mode for the paper trail, but doesn't fail
-the audit).
-
-### Triage rules
-
-For each **critical** finding:
-
-1. **Is there a genuine escape hatch?** (file picker, hidden input,
-   stamp-internal usage that wasn't auto-detected) — add the
-   `<!-- native-ok -->` annotation; re-run audit.
-2. **Is it a real bug?** Replace `<button>` with `<button-ui>`,
-   `<input>` with `<input-ui>` (preserving slot/attribute semantics
-   via `attribute-api-migration.md`).
-3. **Is the AdiaUI primitive registered in the consuming shell?**
-   Cross-check that `button.js` / `input.js` etc. are imported via
-   the page-trio's `.contents.js` or via a `<link rel="stylesheet">`.
-
-**Do NOT auto-fix** — native-primitive replacement requires
-attribute-shape decisions (`button` → `button-ui label="…"` vs
-`<button-ui><text-ui>…</text-ui></button-ui>` depending on slot
-discipline). Human eyeball every replacement; this audit surfaces, it
-doesn't repair.
-
-### Pair with peer probes
-
-- The **component-CSS-loaded probe (#6)** catches "wrong CSS"; this
-  catches "wrong tag". Run both as a regular sweep.
-- The **app-shell QA sweep** (`scripts/dev/audit-app-shells.mjs`)
-  catches "missing import"; this catches "didn't use the primitive at
-  all". Pre-merge gate composition: shell-QA + native-primitive-leak
-  for a 2-script "are we using the design system honestly?" check.
-
-### Output shape (human-readable)
-
-```
-[audit-native-primitive-leak] scanning apps, playgrounds, catalog
-
-  apps/genui/app/render-preview/render-preview.contents.html
-    ✗ L36  <textarea> → consider <textarea-ui>
-        <textarea
-  apps/overview.examples.html
-    ✗ L10  <table> → consider <table-ui>
-        <table>
-
-Summary: 2 critical, 0 warning, 168 info
-(scanned: apps + playgrounds + catalog; 7 probe(s) active)
-(168 info-level finding(s) hidden; pass --all to see)
-```
-
-### When to expand the probe set
-
-- A new AdiaUI primitive ships that has a clear native equivalent →
-  add to the `PROBES` array in `audit-native-primitive-leak.mjs`.
-- A class of native-primitive smell slips past the audit in a real PR
-  → add the probe first, **then** fix the bug. Test for the test.
-- A native primitive is consistently legitimate in a specific surface
-  → add it to the showcase-demo / stamp-internal skip-list, document
-  the rationale in this section.
-
-### Repo touchpoints
-
-- Script: `scripts/dev/audit-native-primitive-leak.mjs`
-- Probe contract: `PROBES` array at top of the script — each entry has
-  `tag` + `adiaEquivalent` + `severity` + `rationale` + escape-hatch
-  rules
-- Intent-marker contract: `INTENT_MARKERS` array — adjacent
-  `<!-- native-ok -->` or `data-native-ok=` annotations
-- Related skill content: `adia-ui-authoring/references/primitive-audit.md`
-  (the consumer-side authoring discipline that this audit enforces)
-
-### Anti-patterns
-
-- **Don't bulk-replace `<a href>` with `<link-ui>`** without
-  understanding link semantics — many `<a href>` cases are legitimately
-  navigation anchors and the `--strict-links` flag exists exactly so
-  you can opt-in when you want that scrutiny.
-- **Don't suppress findings by stripping the script's PROBES entries**
-  to make the audit pass. The right move is either (a) replace the
-  native tag, (b) annotate the escape hatch, or (c) document why the
-  probe should be retired (and update the PROBES array deliberately).
-- **Don't run this on `docs/` or showcase demos** — they're skipped
-  by default because they contain literal code-block examples that
-  use native primitives. Adding them to the scan roots produces
-  noise.
-- **Don't escalate `--strict-links` to default** — `<a href>` is the
-  fundamental web hyperlink primitive. Most usage is legitimate.
-  The flag exists for the rare "I want to audit every link" sweep.
-- **Don't trust the preceding-comment annotation form for very long
-  reason text** — if the `<!-- native-ok: <reason> -->` block exceeds
-  ~180 chars total (indent + prefix + reason + `-->`), the comment-
-  begin can fall outside the 200-char detection window. The
-  attribute form (`data-native-ok="<reason>"`) lives inside the
-  opening tag and never has this problem. Prefer the attribute form
-  when reason text is verbose.
-
----
-
-## § Admin-Shell Composition Audit
-
-Static-HTML probe that **flags incomplete admin-shell compositions** —
-the FEEDBACK-41 cluster where a consumer (agent or human) drops in
-`<admin-shell>` + `<admin-sidebar>` + `<admin-content>` but skips the
-4 "easy-to-forget" canonical parts that make the result look like the
-reference at `ui-kit.exe.xyz/site/examples/admin-dashboard`. The
-2026-05-23 claims-ui regression class.
-
-The script (`scripts/dev/audit-shell-composition.mjs`) walks
-`apps/<name>/.../*.html`, `playgrounds/<name>/*.html`, and
-`catalog/page-shells/*.html`, parses each `<admin-shell>` it finds, and
-checks the **13 canonical parts** any complete admin-shell should
-have. The authoritative reference is `chat-ui:site/index.html` lines
-42-120 — the actual source that renders
-`ui-kit.exe.xyz/site/examples/admin-dashboard`:
-
-1. `<admin-shell mode="rounded borderless">` outer (with a canonical mode attr)
-2. `<admin-sidebar slot="leading" resizable collapsible>` (left rail)
-3. Sidebar's inner `<admin-topbar slot="header">` with `<select-ui avatar="…" value="…" variant="ghost">` (workspace/context switcher — NOT `<menu-ui>`; that's the legacy v0.5.x pattern) — ★ commonly mis-implemented
-4. Sidebar's `<section-ui>` (the AdiaUI primitive, NOT native `<section>`) wrapping `<nav-ui>`
-5. Sidebar's `<admin-statusbar slot="footer">` with `<select-ui avatar="…">` (user menu) — ★ commonly missing
-6. Sidebar's `<div data-resize></div>` (REQUIRED when `resizable` is on)
-7. `<admin-content>` with inner `<admin-topbar>` containing `<button-ui data-sidebar-toggle="leading" icon="sidebar">` + `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>` — ★ spacer + actions commonly missing
-8. `[data-actions]` contains `<popover-ui>` + `<theme-panel slot="content">` for theme picker (NOT a custom `<theme-picker-ui>` — that doesn't exist)
-9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` + `<router-ui>` (or `<admin-page>` directly for non-routed)
-10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
-11. `<admin-statusbar>` at content footer (version-strip band) — ★ commonly missing
-12. Second `<admin-sidebar slot="trailing">` (changelog/inspector rail, hidden by default) — strongly recommended
-13. `<admin-command>` with `<command-ui>` (cmd-K palette, top-level child of admin-shell) — strongly recommended
-
-Severity:
-- **critical** — outer `<admin-shell>` exists but the page would render
-  as broken structure (no admin-content, no admin-sidebar, etc.).
-- **warning** — structure is present but one of the commonly-missing
-  parts (3, 5, 6, 7 spacer/actions, 8 theme picker, 11) is absent OR
-  uses the wrong primitive (e.g. `<menu-ui>` instead of `<select-ui>`
-  for the context-switcher; native `<section>` instead of
-  `<section-ui>` for the nav wrap). Cite the canonical reference.
-- **info** — parts 12-13 absent (strongly recommended but not strictly
-  required for minimal surfaces); alternate section wrapper choice;
-  opted-out mode declared via `data-shell-opt-out=`.
-
-### When to use
-
-- After any wide screen-authoring sweep where an agent composed admin
-  surfaces (genui rendering, page-shell template authoring, consumer
-  feedback triage where the diagnosis is "doesn't look like the
-  reference").
-- After a fresh consumer onboarding (claims-ui-vN, new third-party
-  product) — the FEEDBACK-41 cluster surfaces here repeatedly.
-- Before publishing a new `apps/<name>` admin surface — last gate
-  before users see structural drift.
-- As a follow-up gate when the `adia-ui-kit` skill's pre-author bundle
-  gate (`§LoadingProtocol` 8-canonical-parts enumeration) is skipped or
-  half-followed.
-
-### When NOT to use
-
-- Component demos under `/site/components/*` — those are intentional
-  single-component spotlights, not shells. Use `§ Component Dogfood`
-  (the §Workflow at the top of this skill) for those.
-- Surfaces with `data-shell-opt-out="<reason>"` on the outer
-  `<admin-shell>` — the escape hatch is honored, audit skips them.
-- Marketing pages that use `<admin-shell>` for narrow visual chrome
-  but aren't full admin dashboards. Annotate with `data-shell-opt-out=`.
-
-### How to run
-
-```bash
-# Default — scan apps/, playgrounds/, catalog/page-shells/; warn-only
-npm run audit:shell-composition
-
-# Strict — exit non-zero on any warning (CI gate)
-npm run audit:shell-composition:strict
-
-# All surfaces — include docs/ examples (noisier; usually skip)
-npm run audit:shell-composition:all
-```
-
-The probe is structurally static — no headless browser, just AST walks
-on the HTML files. Fast enough to run in pre-commit.
-
-### What the probe catches
-
-| # | Symptom | Diagnosis |
-|---|---------|-----------|
-| 1 | `<admin-shell>` with no inner `<admin-content>` | Critical — wrong outer composition |
-| 2 | `<admin-sidebar>` missing `<admin-statusbar slot="footer">` | Warning — part 5 missing (user-menu band) |
-| 3 | `<admin-content>` `<admin-topbar>` missing `[data-spacer]` | Warning — part 6 spacer missing |
-| 4 | `<admin-content>` `<admin-topbar>` missing `[data-actions]` | Warning — part 6 actions missing |
-| 5 | `<admin-content>` missing trailing `<admin-statusbar>` | Warning — part 8 missing (version-strip band) |
-| 6 | `<admin-sidebar>` `<admin-topbar>` only contains plain text | Warning — part 3 missing context-switcher menu |
-| 7 | `<admin-scroll>` missing as wrapper around `<admin-page>` | Warning — part 7 wrap missing |
-
-### Intentional escape hatch — annotation
-
-If a page deliberately uses an incomplete admin-shell (a marketing
-hero, a narrow modal preview, etc.), annotate the outer tag:
-
-```html
-<admin-shell mode="rounded" data-shell-opt-out="marketing hero, no sidebar needed">
-  <admin-content>
-    <admin-page>
-      <admin-page-header><h1>Welcome</h1></admin-page-header>
-    </admin-page>
-  </admin-content>
-</admin-shell>
-```
-
-The audit skips the structural checks but emits an **info** finding
-naming the opt-out reason. Reviewers can sanity-check the annotation
-during code review.
-
-### Triage rules
-
-For each **warning** finding:
-
-1. **Is the page a canonical product surface?** (apps/saas, apps/genui
-   admin examples, catalog/page-shells/admin-*) — fix mandatory; this
-   is the reference. Add the missing parts.
-2. **Is the page a playground for ONE narrow feature?** — fix optional;
-   acceptable to annotate `data-shell-opt-out="playground for X"`.
-3. **Is the page a consumer-feedback regression class** (per kit skill
-   `§FailureModeReceipts`)? — fix mandatory; document the missing parts
-   in the receipt.
-
-For each **critical** finding: halt, re-author the outer composition
-from the canonical 8-part template at `adia-ui-kit` `§Patterns` →
-"Admin shell anatomy" before continuing.
-
-### Pair with peer probes
-
-The audit is **complementary** to the pre-author bundle gate in
-`adia-ui-kit` SKILL.md `§LoadingProtocol`: the gate is a **forward-time**
-check (before generation), the audit is a **backward-time** check
-(after generation). Use both.
-
-Also complementary to **§ Native Primitive Leak Audit**: that probe
-catches "agent reached for `<button>` instead of `<button-ui>`"; this
-probe catches "agent assembled the right primitives but skipped the
-canonical composition recipe". Same root cause family (incomplete
-substrate adherence), different surface.
-
-### Output shape (human-readable)
-
-```
-audit-shell-composition v1.0.0
-
-Scanned 18 files across apps/ + playgrounds/ + catalog/page-shells/
-
-CRITICAL findings: 0
-WARNING findings:  3
-INFO findings:     2
-
-WARNING — apps/genui/app/admin-dashboard.html:14
-  <admin-sidebar> missing <admin-statusbar slot="footer"> (part 5)
-  → Add user-menu band with avatar + menu-ui trigger
-  → Reference: catalog/page-shells/admin-default.html line 22
-
-WARNING — playgrounds/admin-shell/admin-shell.html:31
-  <admin-content> <admin-topbar> missing [data-spacer] (part 6)
-  → Add <div data-spacer></div> between breadcrumb and [data-actions]
-
-INFO — apps/saas/app/marketing-hero.html:8
-  <admin-shell> has data-shell-opt-out="marketing hero, no sidebar"
-  → Audit skipped per opt-out
-
-Exit: 0 (warn-only mode); use --strict to fail on warnings.
-```
-
-### Repo touchpoints
-
-- `scripts/dev/audit-shell-composition.mjs` — the probe itself.
-- `package.json` — `audit:shell-composition{,:strict,:all}` npm scripts.
-- `.agents/skills/adia-ui-kit/SKILL.md` `§LoadingProtocol` — the
-  forward-time companion (pre-author bundle gate 8-canonical-parts
-  enumeration).
-- `.agents/skills/adia-ui-kit/SKILL.md` `§Patterns` → "Admin shell
-  anatomy" — the canonical 8-part template the probe checks against.
-- `.agents/skills/adia-ui-release/references/gates-catalog.md` —
-  Category 6 entries for the 3 npm scripts.
-
-### Anti-patterns
-
-- **Don't run on raw component demo pages** — `/site/components/*` is
-  not in the default scan root because most demos are single-primitive
-  spotlights, not shells. If you point the audit at them, you'll get
-  noise findings for "missing admin-shell" on demos that legitimately
-  don't have one.
-- **Don't silence warnings by stripping the CANONICAL_PARTS array** to
-  make the audit pass. The fix is to add the missing parts to the
-  consumer surface or annotate `data-shell-opt-out=` with a reason.
-- **Don't escalate `:strict` to default on personal branches** — the
-  warn-only default lets authors iterate; CI bumps to `:strict` at
-  publish time.
-- **Don't run the audit on consumer repos directly** — the audit is
-  substrate-side tooling. For consumer repos (claims-ui, third-party
-  products), point them at the `adia-ui-kit` skill's `§Patterns` →
-  "Admin shell anatomy" or the live reference at
-  `ui-kit.exe.xyz/site/examples/admin-dashboard`.
-
----
-
-## § Component Anatomy + Card Header Sweep (v2.27.4+, FB-52 §11)
-
-Two static-grep probes added after the 2026-05-23 docs-overhaul session
-surfaced patterns that the existing 5 modes don't catch:
-
-1. **Card-ui header `<div>` wrapper anti-pattern** — header content
-   wrapped in a bare `<div>` (no `slot=`) bypasses card-ui's
-   `:has(> [slot])` grid activator. Title + badge collapse into one
-   row instead of the canonical 1fr-heading + auto-action grid.
-2. **Component anatomy section coverage** — component example pages
-   missing the canonical anatomy sections (`props`, `events`, `slots`,
-   `data-attrs`, `keyboard`, `css-vars`, `a2ui`, `related`) after
-   `anatomy-sweep.mjs` should have populated them.
-
-Both probes are static greps (no headless browser), fast enough to run
-in pre-commit.
-
-### Probe A — Card-ui header `<div>` wrapper
-
-Detection: any `<header>` directly inside `<card-ui>` whose immediate
-child is a `<div>` with no `slot=` attribute.
-
-```bash
-# Find candidate card-ui files
-grep -rln '<card-ui' \
-  packages/web-components/patterns/ \
-  packages/web-modules/ \
-  site/ \
-  apps/ \
-  playgrounds/ \
-  catalog/ \
-  2>/dev/null | \
-while read -r file; do
-  # Look for card-ui > header > div without slot=
-  awk '
-    /<card-ui/ { in_card = 1 }
-    in_card && /<header>/ { in_header = 1; next }
-    in_header && /<div>[^<]*$|<div [^>]*>$/ {
-      if ($0 !~ /slot=/) {
-        print FILENAME ":" NR ": " $0
-      }
-      in_header = 0
-    }
-    /<\/card-ui>/ { in_card = 0; in_header = 0 }
-  ' "$file"
-done
-```
-
-**Severity**: warning. The card renders, but heading + action collapse
-into a full-width row. No console error; pure visual regression.
-
-**Fix**: hoist the header children out of the wrapper `<div>`. Apply
-`slot="action"` to badges/buttons that should land in the trailing
-column. Reference: `adia-ui-kit/references/patterns-recipes.md`
-`§Card-ui header — slotted children, NOT <div> wrapper`.
-
-### Probe B — Component anatomy section coverage
-
-Detection: a component's `*.examples.html` page is missing the
-schema-derivable anatomy sections that `scripts/docs/anatomy-sweep.mjs`
-should have populated.
-
-```bash
-# A component page is under-documented if it has no reference sections at all
-for f in packages/web-components/components/*/*.examples.html; do
-  name=$(basename "$(dirname "$f")")
-  if ! grep -q 'data-property="props"\|data-property="events"\|data-property="slots"' "$f"; then
-    echo "MISSING anatomy: $name → $f"
-  fi
-done
-```
-
-**Severity**: info — a page can ship without anatomy sections if the
-component is intentionally minimal (e.g. a one-prop primitive), but
-the sweep should have offered at minimum `props` or `events`. If
-neither is present, it's worth a manual review.
-
-**Fix**: run `node scripts/docs/anatomy-sweep.mjs` to auto-populate
-schema-derivable sections. If the sweep still skips the component,
-investigate whether the yaml has missing `props:`/`events:`/`slots:`
-declarations.
-
-### When to use both probes
-
-- After any wide screen-authoring sweep that generated `<card-ui>` blocks
-- After a new-component yaml + examples.html author-pass (probe B
-  catches the case where the author skipped the sweep step)
-- Before publishing a docs-site refresh — both probes should be 0
-  findings or have explicit opt-outs
-
-### Anti-patterns
-
-- **Don't probe non-component `<header>` tags** — admin-shell's own
-  `<header>` (inside admin-topbar, drawer-ui, etc.) is structurally
-  different and the `<div>`-wrapper pattern is acceptable there. The
-  awk script above restricts to `<card-ui>` ancestor scope.
-- **Don't auto-fix probe A findings** — the right fix depends on
-  intent (which child should be `slot="action"` vs auto-placed). Flag
-  + manual review only.
-- **Don't escalate probe B to error severity** — some components
-  legitimately have only a `usage` section (e.g. CSS-only primitives
-  with no JS API). Info-level only.
-