@adia-ai/adia-ui-forge 0.1.2 → 0.8.0

package/skills/adia-gen-review/references/loop-protocol.md

@@ -0,0 +1,216 @@
+# Loop Protocol — one full review cycle
+
+Five phases per prompt; human QA gate at cycle close; Phase 5 runs for FAILING
+prompts only. Scripts ship in this skill at
+`${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/` and are run from the
+monorepo root (they read `apps/genui/…/gallery-latest.json` and write the
+`review/` tree there). Corpus-pattern doctrine consumed by Phase 5:
+[corpus-html-patterns.md](corpus-html-patterns.md).
+
+---
+
+## §Setup (before the first prompt)
+
+1. Read `apps/genui/app/gen-ui-gallery/outputs/gallery-latest.json`. Validate
+   structure (generated artifact — untrusted): must have `version` (integer),
+   `generatedAt` (ISO string), `engines` (array), `groups` (array). Any key
+   missing → stop and report. Do NOT validate it against scores.schema.json
+   (that is the review OUTPUT contract). Extract only group slugs, prompt
+   slugs, engine output component arrays.
+2. Determine the cycle number with read-then-lock:
+   - `N = max(cycle numbers in review/cycle-ledger.json ∪ on-disk
+     review/cycle-* directory numbers) + 1`, or 1 if neither exists.
+     (Dirs can outrun the ledger — decompose runs create `cycle-N/` before a
+     scoring pass records it. Ledger-only numbering collides with those
+     orphan dirs.)
+   - Write a `cycle-{N}.lock` sentinel BEFORE writing any cycle data. If the
+     lock already exists: another agent is running — stop.
+3. Create `review/cycle-{N}/` and a `scores.json` skeleton conforming to
+   [scores.schema.json](scores.schema.json) — all prompt scores null,
+   status `OPEN`.
+4. Open `review/cycle-{N}/review-report.md` for append-only writing; header:
+   cycle number, timestamp, prompt count, engine list.
+5. Confirm the dev server responds (Playwright needs it). Do not boot a
+   background server — the operator runs it (see §ManualHandoff).
+
+---
+
+## §Phase 1 — Ideal-Output Specification (A data)
+
+Delegate to **`adia-author`** per prompt:
+
+> "Compose the ideal AdiaUI UI for: '{prompt text}'. Output: (1) user intent +
+> primary task + states, (2) ASCII DOM wireframe, (3) slot vocabulary table,
+> (4) key prop/attr table."
+
+Binary success check — the spec itself is not scored:
+
+- Structured spec returned → `specProduced: true`, proceed.
+- Error/empty/off-topic → `specProduced: false`, `status: FAILING` with cause
+  `FREE_FORM_HALLUC`, skip Phases 2–5 for this prompt, log in review-report.md.
+
+Capture as A-data: `spec.rootComponent`, `spec.layoutPrimitive`,
+`spec.keyComponents` (DOM order), `spec.slotVocabulary`
+(`{parent, slot, child}` triples), `spec.states`, `spec.wireframe` (stored as
+string, not interpreted).
+
+---
+
+## §Phase 2 — Canvas Decomposition (B data)
+
+Mechanized end-to-end by the decompose script — screenshots, DOM walk,
+primitive lookup (`TAG_TO_COMPONENT`, the authoritative table), attr
+sanitization, overflow gate:
+
+```text
+node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/gen-review-decompose.mjs
+  --cycle N  [--group <slug>] [--prompt <slug>] [--port 5300] [--settle 2500] [--dry-run]
+```
+
+Outputs per prompt under `review/cycle-N/`: `screenshots/<slug>.png`,
+`raw-dom/<slug>.json` (internal only), `decomposed/<slug>.json` — the
+trust-boundary file:
+
+```json
+{
+  "promptSlug": "auth-login-form",
+  "renderFailure": false,
+  "rootComponent": "Card",
+  "layoutPrimitive": "Column",
+  "components": ["Card", "NativeHeader", "NativeSection", "Column", "Field", "Input", "Button"],
+  "slotPositions": [{ "parent": "Card", "slot": "header", "child": "NativeHeader" }],
+  "attrs": { "Button": { "variant": "primary", "text": "Sign in" } },
+  "unknownElements": [],
+  "overflowElements": [],
+  "screenshotPath": "review/cycle-N/screenshots/auth-login-form.png"
+}
+```
+
+Only allowlisted attrs survive (`ATTR_ALLOWLIST` in the script); `data-*`,
+`aria-*`, and raw text nodes are discarded. Assess decomposition quality with
+[rubric-decompose.md](rubric-decompose.md).
+
+**Overflow gate (mechanical, visual lane).** The script checks text-bearing
+elements for `scrollWidth/Height > clientWidth/Height` under computed
+`overflow: hidden`; hits land in `overflowElements`. Each entry auto-promotes
+to a P1 in Phase 4. This lane is independent of Phase 3: score 93 with
+overflow is still FAILING.
+
+**RENDER_FAILURE protocol.** Canvas height < 50px OR empty `components`:
+`renderFailure: true`, `status: RENDER_FAILURE` in scores.json, skip Phases
+3–5, log in review-report.md, count toward `aggregate.renderFailureCount`.
+RENDER_FAILURE does not block cycle close; the same prompt failing 3+ cycles
+escalates to the operator as a pipeline bug.
+
+---
+
+## §Phase 3 — A-vs-B Gap Scoring
+
+Rubric: [rubric-score.md](rubric-score.md). Inputs: `spec.*` (A) + the
+decomposed file (B) — never the raw DOM. Before scoring, run the rubric's
+§DomainMismatchCheck. Score D1–D5 (0–20 each) + D6 (mechanical root-component
+match, 0 or +5; max 105). Record `rubricScore.score`, `rubricScore.delta` vs
+prior cycle, dimension breakdown, and cause codes per gap.
+
+**Regression block**: any prompt with `rubricScore.delta < -10` marks the
+cycle `BLOCKED` — no cycle close until the regression is explained and the
+prior cycle's fix plan audited.
+
+---
+
+## §Phase 4 — Cosmetic Audit
+
+Rubric: [rubric-cosmetic.md](rubric-cosmetic.md). Input: the Phase 2
+screenshot. Runs for ALL prompts (a structurally passing prompt can still
+carry a P1). Record P1/P2/P3 counts + issue list in scores.json.
+
+---
+
+## §Phase 5 — Root Cause + Fix Plan
+
+Runs ONLY for `status: FAILING` prompts — structural gate: read
+`decomposed/<slug>.json`, confirm `renderFailure: false` and
+`status: FAILING` in scores.json first. PASSING and RENDER_FAILURE prompts
+never get fix plans. Reads ONLY the decomposed file.
+
+0. **SoT HTML lookup (required).** Identify the canonical HTML page for the
+   prompt's domain (corpus-html-patterns.md §SourceOfTruth map). If it has a
+   `data-chunk` marker for this pattern: run `npm run verify:corpus`; stale →
+   plan a re-harvest. If not: the plan is to ADD the marker to the canonical
+   HTML then harvest — the plan's `file:` points at the HTML source, never
+   chunk JSON. No canonical HTML for the domain → new authoring task
+   (`adia-author`), do not invent a pattern.
+1. **Trace causes** using the 9 codes in rubric-score.md §Root-Cause
+   Classification. Run the diagnostic confirmation for the suspected code
+   before recording it (RETRIEVAL_SCORE → actually run the retrieval search;
+   EMPTY_CHUNK → inspect the chunk JSON).
+2. **Write the plan.** Each entry: `rank`, `action`, `file`, `impact`, `skill`
+   (schema-required). `file` must be inside `apps/`, `catalog/`,
+   `packages/a2ui/corpus/`, or `packages/a2ui/runtime/` — anything else is
+   flagged for operator review. Corpus-class causes route to `adia-a2ui`;
+   TRANSPILER_GAP / FREE_FORM_HALLUC route to `adia-author`.
+3. Append the ranked plan to `review/cycle-N/review-report.md`.
+
+---
+
+## §CycleClose
+
+1. **Regression block check** — a `BLOCKED` flag from Phase 3 stops here.
+2. **Apply fix plans** (FAILING prompts only) via the routed peer skills:
+   edit SoT HTML → `npm run harvest:chunks` → `npm run verify:corpus`. This
+   skill does not perform the edits.
+3. **Regenerate**: `npm run gallery:generate`; confirm 0 console
+   errors/warnings in the canvas output.
+4. **Human QA gate — required for COMPLETE.** Operator reviews 5 random
+   PASSING prompts against: (a) serves the user's task? (b) right primary
+   primitive? (c) would ship unchanged? Record
+   `humanQA.{sampledPrompts,passCount,failCount}`. `failCount ≥ 2` → cycle
+   stays `OPEN`: the thresholds are miscalibrated — recalibrate
+   rubric-score.md §Thresholds against the human judgments.
+5. **Schema gate** (must exit 0 before touching the ledger):
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/validate-cycle-scores.mjs --cycle N --strict
+   ```
+
+6. **Update ledger** (`review/cycle-ledger.json`): `cycleNumber`,
+   `completedAt`, `engine`, `status`, `aggregate`
+   (passingCount/failingCount/renderFailureCount/meanScore/Δ), `humanQA`.
+   Remove the `cycle-{N}.lock` sentinel.
+7. **Exit condition**:
+
+   ```bash
+   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/gen-review-status.mjs --check-exit
+   ```
+
+   Exit 0 → `status: COMPLETE`; exit 1 → `status: OPEN` (the script lists the
+   blockers). Δ = 0 for every prompt across a full cycle → escalate to the
+   operator: the causes need substrate changes beyond corpus patching.
+
+---
+
+## §ManualHandoff — human-executed steps per cycle
+
+`gallery:generate` and the decompose script need a running dev server, which
+the agent must not boot in the background. Per cycle the operator runs:
+
+```text
+[Agent: Phases 1–5, fix plans] → HUMAN: apply data-chunk edits (via adia-a2ui plans)
+  → HUMAN: npm run harvest:chunks
+  → HUMAN: npm run gallery:generate
+  → HUMAN: node <plugin>/skills/adia-gen-review/scripts/gen-review-decompose.mjs --cycle N
+  → [Agent: re-score Phases 3–5]
+  → HUMAN: npm run eval:diff -- --engine <engine>   ← corpus changes must hold the eval floors
+  → [Agent: scores.json + ledger + schema gate + exit check]
+```
+
+---
+
+## §Modes
+
+**Single prompt** (diagnostic): same phases for the named prompt only; skip
+cycle-close regeneration; write `review/single-{slug}-{timestamp}.json`; no
+human QA gate.
+
+**Root-cause only**: skip Phases 1–3; requires a prior cycle's decomposed file
++ scores.json as input; run Phase 5 directly.

package/skills/adia-gen-review/references/rubric-cosmetic.md

@@ -0,0 +1,100 @@
+# Rubric — Cosmetic & Visual Quality
+
+Phase 4 of [loop-protocol.md](loop-protocol.md). Input: the Phase 2 canvas
+screenshot. Output: P1/P2/P3 counts + issue list. Runs for ALL prompts;
+P1 blocks a prompt from PASSING.
+
+---
+
+## §Thresholds
+
+Cosmetically PASSING: P1 = 0 AND P2 ≤ 2 AND P3 ≤ 4.
+Cosmetic BLOCK (prompt cannot pass overall): P1 ≥ 1. Overflow entries from the
+Phase 2 gate auto-count as P1s here.
+
+---
+
+## §Severity Definitions
+
+| Severity | Meaning | Example |
+| --- | --- | --- |
+| **P1** | User-visible layout failure; looks broken or unusable | Content overflows canvas, zero-height element, overlapping text, invisible text |
+| **P2** | Noticeably wrong; degrades quality, doesn't break function | Wrong field padding, badge outside its container, inconsistent gap scale |
+| **P3** | Minor cosmetic; acceptable but suboptimal | Slightly off optical alignment, icon size mismatch |
+
+---
+
+## §Cosmetic Dimensions
+
+### COS-1 — Container geometry
+
+- Zero height/width where non-zero expected → P1
+- Container visibly overflows its parent → P1
+- Distorted card/image aspect ratio → P2
+- Container expands beyond content without reason → P2
+- Unbalanced internal whitespace (all padding one side) → P3
+
+### COS-2 — Spacing scale
+
+- 0 visible gap where clear separation needed → P1
+- Visually inconsistent spacing within one region (3px vs 20px between fields) → P2
+- Off the AdiaUI token scale (multiples of 4px) → P3
+- Optically unbalanced margins in a centred block → P3
+
+### COS-3 — Optical alignment
+
+- Misaligned text baselines across a row → P2
+- Icons not vertically centred against companion text → P2/P3
+- Action buttons not trailing-edge aligned → P3
+- Labels not consistently flush-left within a group → P3
+
+### COS-4 — Visual balance
+
+- One element dominates the canvas with no counterweight → P2
+- Heading and body at identical weight (no hierarchy contrast) → P2
+- Left/right or top/bottom regions unbalanced vs importance → P3
+
+### COS-5 — Token usage signals
+
+- Component appears unstyled (raw browser styles bleeding through) → P1
+- Very low text contrast (fg-subtle on bg-subtle class) → P2
+- Black/white background where a subtle tint belongs → P2
+- Border too thick/thin for context → P3
+
+### COS-6 — Empty state quality
+
+- Empty state is a blank box (not communicative) → P2
+- Collapsed to near-zero height → P2
+- Placeholder text unreadable or unstyled → P3
+
+---
+
+## §Issue Format
+
+```json
+[
+  { "severity": "P1", "location": "card-ui root", "issue": "Card height is zero — canvas-ui likely returned empty components array" },
+  { "severity": "P2", "location": "field-ui email label", "issue": "Label right-aligned instead of left; field-ui inline mode applied incorrectly" },
+  { "severity": "P3", "location": "col-ui body gap", "issue": "Gap between form fields inconsistent — some 8px, some 16px" }
+]
+```
+
+---
+
+## §Screenshot Reading Protocol
+
+1. Scan for P1 first (broken layout, overflow, invisible content), then P2 per
+   region top-to-bottom, then P3.
+2. Report only what is visible — "spacing appears inconsistent", never an
+   invented "gap is 7px".
+3. Use prompt context: a sparse loading skeleton is correct; a sparse
+   completed form is a COS-6 finding.
+
+---
+
+## §Connection to Root Causes
+
+Cosmetic findings usually trace to: gallery canvas CSS
+(`gallery-canvas-wrap`), component token overrides inside a2ui-root, missing
+template attrs (`gap=` absent from the node), or a structurally wrong
+primitive. Note the suspected connection when obvious; Phase 5 confirms it.

package/skills/adia-gen-review/references/rubric-decompose.md

@@ -0,0 +1,101 @@
+# Rubric — Canvas Decomposition
+
+Phase 2 of [loop-protocol.md](loop-protocol.md). Evaluates the quality of the
+decomposition itself (screenshot + DOM walk → decomposed file), not the
+quality of the generated output (that is [rubric-score.md](rubric-score.md)).
+Output: score 0–100 + findings.
+
+---
+
+## §Thresholds
+
+| Level | Score | Meaning |
+| --- | --- | --- |
+| **Excellence** | 85–100 | Complete outside-in decomposition; every element named with its correct primitive |
+| **Acceptable** | 65–84 | One level missed or one element misidentified |
+| **Failing** | 0–64 | Root container or a major child missed |
+
+**Phase gate: ≥ 65.** A failing decomposition invalidates the Phase 3 score.
+
+---
+
+## §Decomposition Protocol (outside-in, in order)
+
+1. **Root container** — outermost rendered component node (canvas-ui →
+   a2ui-root are shells, skipped by the lookup).
+2. **Layout strategy** — flex? grid? col-ui? row-ui? raw block?
+3. **Primary regions** — header / body / footer, named card slots, panes.
+4. **Content regions** — the primitives filling each region.
+5. **Leaf nodes** — text, icon, button leaves.
+6. **Data binding** — content-carrying attrs (`text=`, `label=`, `value=`,
+   `icon=`).
+
+Per level record: element tag, key attrs observed, slot placement if slotted.
+Primitive naming comes from `TAG_TO_COMPONENT` in the decompose script — a
+lookup, never interpretation.
+
+---
+
+## §Dimensions (0–20 each, total 100)
+
+### D1 — Root container identification
+
+| Score | Description |
+| --- | --- |
+| 18–20 | Correct tag + key attrs recorded |
+| 13–17 | Tag correct, attrs incomplete |
+| 8–12 | Tag partially correct ("some card element") |
+| 0–7 | Root not identified or wrong |
+
+### D2 — Layout strategy accuracy
+
+| Score | Description |
+| --- | --- |
+| 18–20 | Layout primitive named with direction + gap where applicable |
+| 13–17 | Layout type correct, gap or direction missing |
+| 8–12 | "stacked"/"column" without naming the primitive |
+| 0–7 | Layout not described or incorrect |
+
+### D3 — Region completeness
+
+Proportional credit for key regions identified (card header, body section,
+footer must all be named when present).
+
+### D4 — Primitive identification accuracy
+
+`button-ui` not "a button"; `field-ui` not "div with label"; `badge-ui` not
+"small colored text". Deduct 3 per misidentified primitive. Floor 0.
+
+Native tags in the tree map to `Native*` names (NativeHeader, NativeH3, …) —
+their presence is itself a quality signal (e.g. `NativeLink` where `link-ui`
+belongs).
+
+### D5 — Data binding capture
+
+Content attrs (`text=`, `label=`, `value=`, `icon=`, `heading=`) + structural
+attrs (`variant=`, `size=`, `gap=`, `columns=`). Deduct 4 per visible attr
+missed. Floor 0.
+
+---
+
+## §Screenshot Requirements
+
+- [ ] Taken AFTER canvas settle (the script waits ≥2.5s per prompt).
+- [ ] Clip is exactly the `.gallery-canvas-wrap` bounding box.
+- [ ] Saved to the cycle's `screenshots/<slug>.png`.
+- [ ] Canvas height < 50px → RENDER_FAILURE, skip Phase 3.
+
+---
+
+## §Findings Format
+
+Observations, not judgments:
+
+```json
+[
+  "Root: card-ui (no size or variant attrs visible)",
+  "Layout: col-ui gap=3 inside section slot",
+  "Missing: no footer slot populated; actions appear inline in body",
+  "D5: button-ui text attr absent — label rendered via ::after pseudo, not captured"
+]
+```

package/skills/adia-gen-review/references/rubric-score.md

@@ -0,0 +1,214 @@
+# Rubric — A-vs-B Gap Score (Fidelity)
+
+Phase 3 of [loop-protocol.md](loop-protocol.md). Input: `spec.*` fields from
+Phase 1 + the sanitized decomposed file from Phase 2 — never the raw DOM.
+Output: score 0–105, delta vs prior cycle, per-dimension breakdown.
+
+---
+
+## §Thresholds
+
+Max score 105 (D1–D5 at 20 each = 100; D6 mechanical = 0 or +5).
+
+| Level | Score | Meaning |
+| --- | --- | --- |
+| **Excellence** | 92–105 | Matches the ideal spec with only cosmetic gaps |
+| **Acceptable** | 70–91 | Structural intent met; minor substitutions or missing secondary elements |
+| **Failing** | 0–69 | Wrong root container, wrong layout strategy, or primary intent not represented |
+
+**Exit gate**: every prompt at Excellence (92+) AND zero
+`overflowElements` — see §VisualGate.
+
+**Recalibrating** (when human QA contradicts mechanical scores across 2+
+cycles): sweep candidate threshold values and read the pass-flips at each step
+against the human verdicts — never pick a round number by feel. A threshold
+change must also update the exit gate in SKILL.md and the schema comment, and
+new cause codes / dimensions bump `schemaVersion` in
+[scores.schema.json](scores.schema.json).
+
+---
+
+## §VisualGate (independent of structural score)
+
+Evaluated from `decomposed.overflowElements` before Phase 3 scoring; a high
+structural score cannot compensate. A prompt with `rubricScore.score ≥ 92` is
+still **FAILING** if `overflowElements.length > 0`. Each overflow entry
+auto-promotes to a Phase 4 P1
+(`"[tag] content clipped — overflow:hidden with scrollWidth > clientWidth"`).
+
+Two independent lanes, both must clear:
+
+- **Structural lane** (Phase 3): correct component types, nesting, attributes.
+- **Visual lane** (Phase 2→4 overflow gate): legible, unclipped, visible.
+
+Canonical example: analytics-chart at score 93 with every stat label clipped
+to "T.." / "$.." and an invisible chart — structural pass, visual fail.
+
+---
+
+## §Dimensions
+
+### D1 — Root container fidelity (0–20)
+
+| Score | Condition |
+| --- | --- |
+| 20 | Exact match: same tag + same key attrs |
+| 15 | Same tag, minor attr difference (missing `size` or `variant`) |
+| 10 | Same category (both card-like, or both layout-only) |
+| 5 | Wrong category but not catastrophically wrong |
+| 0 | Completely wrong (bare div where card-ui expected; form stamped as table) |
+
+### D2 — Layout strategy fidelity (0–20)
+
+| Score | Condition |
+| --- | --- |
+| 20 | Exact: same layout primitive, same gap, same direction |
+| 15 | Same direction but wrong primitive or missing gap attr |
+| 10 | Direction correct; gap incorrect or missing |
+| 5 | Wrong direction but content still readable |
+| 0 | Horizontal where vertical required (or vice versa), or no layout applied |
+
+### D3 — Slot vocabulary fidelity (0–20)
+
+Key slot contracts:
+
+- card-ui header: `slot=icon` / `slot=heading` / `slot=description` /
+  `slot=action`; body: `<section>` child; footer element for actions
+- list-item-ui: `slot=icon` / `slot=text` / `slot=description` / `slot=action`
+- field-ui: no slots — content is the control child
+
+18–20 = all key slots correct. Deduct 5 per incorrect or missing slot
+placement. Floor 0.
+
+### D4 — Primitive accuracy (0–20)
+
+Compare `spec.keyComponents` (A) against `decomposed.components` (B), using
+the `TAG_TO_COMPONENT` names from the decompose script:
+
+- 20 = all key elements match
+- −5 per wrong primitive · −3 per missing element (in A, absent from B) ·
+  −2 per unexpected element (in B, absent from A). Floor 0.
+
+### D5 — Content and data binding fidelity (0–20)
+
+Start at 20, apply deductions, floor 0:
+
+| Attr | Expected | Deduct if missing |
+| --- | --- | --- |
+| `text=` on button-ui | Non-empty action label | −4 |
+| `label=` on field-ui | Describes the field | −3 |
+| `value=` on stat-ui | Realistic number | −4 |
+| `change=` on stat-ui | Trend delta | −2 |
+| `icon=` on button/nav | Correct semantic icon | −3 |
+| `variant=` on badge/tag | Correct semantic variant | −2 |
+
+### D6 — Root component match (mechanical, 0 or +5)
+
+`decomposed.rootComponent` exactly equals `spec.rootComponent` → +5, else 0.
+A single lookup comparison — no judgment. (It replaced a ±10 subjective
+"intent satisfaction" modifier; the human QA gate covers intent.)
+
+---
+
+## §Delta
+
+`delta = score(cycle N) − score(cycle N−1)`; null if no prior cycle.
+Zero for two consecutive cycles → investigate. Negative → must be explained in
+root-cause analysis; `delta < −10` → cycle `BLOCKED` (loop-protocol §Phase 3).
+
+---
+
+## §Root-Cause Classification
+
+| Code | Cause |
+| --- | --- |
+| `WRONG_CHUNK` | Retrieval returned the wrong corpus chunk for the intent |
+| `EMPTY_CHUNK` | Chunk exists but template has no useful attrs (props not transpiled) |
+| `WRONG_COMPONENT` | Right structure, wrong primitive (e.g. select-ui children are Text nodes) |
+| `MISSING_PROPS` | Component present but key attrs not set (label, text, value) |
+| `WRONG_NESTING` | Correct component at wrong DOM depth |
+| `TRANSPILER_GAP` | Prop not in catalog; transpiler cannot extract it |
+| `RETRIEVAL_SCORE` | Correct chunk exists but scored lower than a wrong chunk |
+| `FREE_FORM_HALLUC` | Free-form LLM chose a non-existent or wrong primitive |
+| `COSMETIC_ONLY` | Structure correct; only visual/spacing issue |
+
+Record per gap in `scores.json`. Before pinning MISSING_PROPS or
+TRANSPILER_GAP, check the component yaml — components no-op on made-up attrs,
+so the "missing" prop may never have existed
+(corpus-html-patterns.md §Silent-failure attrs).
+
+---
+
+## §DomainMismatchCheck (pre-scoring gate)
+
+Verify the retrieved chunk's domain matches the prompt's group:
+
+```text
+auth/          → auth, forms
+billing/       → billing, settings, forms
+dashboard/     → dashboard, data
+data-tables/   → data, settings
+forms/         → forms, data
+content/       → content, layout, marketing
+navigation/    → navigation, layout
+settings/      → settings, forms
+notifications/ → agent, data
+team-access/   → settings, data
+onboarding/    → onboarding, forms, auth
+```
+
+If the decomposed components clearly indicate a different domain (email inbox
+for a contact-form prompt), classify `RETRIEVAL_SCORE` and flag for human QA.
+Never mark these PASSING without human verification — DOM scoring sees valid
+component types regardless of whether the content answers the prompt.
+
+---
+
+## §KnownGaps — failures mechanical scoring cannot detect
+
+These pass Phases 3 and 4 mechanically but are visually wrong. Human QA
+(loop-protocol §CycleClose) is the only gate that catches them unless a
+computed-style probe is added to Phase 2.
+
+### Layout-axis collapse (validated: analytics-chart)
+
+**What**: elements that belong on separate lines render on one line because
+the wrong CSS display mode is active — `text-ui` is `display:inline` by
+default, so wherever the card-header grid fails to activate, an inline
+text-ui collapses next to a block heading. (The original trigger — the
+transpiler dropping `slot=` — was fixed with the universal slot preserve; the
+failure class remains live for any future grid-activation miss.)
+
+**Why it passes**: Phase 3 scores component presence (both Text nodes are in
+the tree → D4 satisfied); the overflow gate detects clipping, not wrong-axis
+layout.
+
+**Detection**: human QA, or a computed-style probe checking
+`getComputedStyle(el).display` + `getBoundingClientRect().top` per Text node.
+
+**Prevention**: canonical slot grammar / native block elements (`h3`, `p`) in
+card headers — corpus-html-patterns.md §CanonicalCardAnatomy.
+
+### Empty chart (no data)
+
+`chart-ui` with no data renders 0px high but IS in the tree → D4 satisfied;
+the overflow gate only fires if the whole card collapses below 50px.
+Prevention: always inline `data='[…]'` (corpus-html-patterns.md §FailsWorks).
+
+### Viewport clipping (canvas boundary)
+
+Content cut by the canvas paint boundary, not a CSS `overflow:hidden` box —
+the overflow detector requires computed `overflow:hidden`, so this class never
+fires it. Canonical case: magic-link-sent alert "Didn't get th...". Detection:
+human screenshot inspection only. Prevention: keep canvas-bound content
+narrow; `text-ui align="center"` for centered auth cards.
+
+### RETRIEVAL_SCORE (wrong content, correct-looking DOM)
+
+A different chunk sharing component types (Card + List + Avatar) fools
+component-presence scoring every time. Canonical cases: contact-form → email
+inbox; team-members → email inbox; blog-post-card → social post; invoice-table
+→ invoice line-items. Detection: §DomainMismatchCheck pre-screen + the human
+QA gate (this failure class is WHY the gate exists). Prevention: each gallery
+prompt needs a dedicated, grounded chunk whose keywords outscore generic
+competitors.

package/skills/{adia-ui-gen-review → adia-gen-review}/references/scores.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "adia-ui-gen-review/scores",
+  "$id": "adia-gen-review/scores",
   "title": "Gen UI Review Scores — per cycle",
   "description": "Formal contract for review/cycle-N/scores.json. Every downstream tool that reads cycle data must validate against this schema.",
   "type": "object",
@@ -48,7 +48,7 @@
         "cycle": { "type": "integer" },
         "specProduced": {
           "type": "boolean",
-          "description": "Whether the Phase-1 spec sub-skill successfully produced an A-spec (replaces rubric-spec scoring)"
+          "description": "Whether the Phase-1 spec delegate successfully produced an A-spec (the spec itself is not scored)"
         },
         "rubricDecompose": {
           "type": "object",

package/skills/{adia-ui-gen-review → adia-gen-review}/scripts/gen-review-coverage-audit.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * gen-review-coverage-audit.mjs — SelfAudit check 5 for adia-ui-gen-review.
+ * gen-review-coverage-audit.mjs — TAG_TO_COMPONENT parity gate for adia-gen-review.
  *
  * Verifies that every AdiaUI primitive tag (from component yamls) has
  * an entry in gen-review-decompose.mjs TAG_TO_COMPONENT. Reports any
@@ -17,9 +17,9 @@
  * script is run.
  *
  * Usage (from the monorepo root):
- *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-gen-review/scripts/gen-review-coverage-audit.mjs           # report gaps
- *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-gen-review/scripts/gen-review-coverage-audit.mjs --strict  # exit 1 if gaps exist
- *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-gen-review/scripts/gen-review-coverage-audit.mjs --json    # machine-readable output
+ *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/gen-review-coverage-audit.mjs           # report gaps
+ *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/gen-review-coverage-audit.mjs --strict  # exit 1 if gaps exist
+ *   node ${CLAUDE_PLUGIN_ROOT}/skills/adia-gen-review/scripts/gen-review-coverage-audit.mjs --json    # machine-readable output
  */
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';