baldart 4.76.1 → 4.78.0

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -208,16 +208,31 @@ available (probe `get_design_context` / `get_screenshot` tools at runtime):
 If the MCP tools error or time out, fall through silently to level (b) — do
 not surface the failure as a blocker.
 
-### Level (b) — Local image
-
-If `card.links.design[]` contains a local file path (PNG / JPG / PDF) OR the
-card has a `mockups/` directory alongside its YAML:
-
-- Resolve the path. For PDFs, extract the first page as PNG (use `pdftoppm`
-  or equivalent — degrade gracefully if unavailable).
-- Copy to `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png`.
+### Level (b) — Local image (PNG / JPG / PDF / **HTML**)
+
+If `card.links.design[]` contains a local file path OR the card has a `mockups/`
+directory alongside its YAML:
+
+- **PNG / JPG**: copy to `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png`.
+- **PDF**: extract the first page as PNG (`pdftoppm` or equivalent — degrade gracefully
+  if unavailable).
+- **HTML** (`links.design` ends in `.html`): the mockup is markup, not an image. Two
+  things happen — (1) render it headless to a PNG for the visual pass: open `file://<abs
+  path>` with Playwright at 1440px and `page.screenshot({fullPage:true})` →
+  `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png` (degrade gracefully if
+  the render fails — the structural pass below still runs); (2) **retain the HTML path**
+  for the route-free structural pass (Phase 2.7).
 - Record `mockup_source.level = "local"` and the source path.
 
+**Structural source (route-free ground truth).** Independently of the image, record a
+`structural_source` for the route when the mockup is **code**:
+- `links.design` is an `.html` file → `structural_source = { level: "html", mockup_path:
+  "<abs html path>" }`.
+- `links.design_src` is set / `mockups/_src/` exists (finished Claude Design CODE, v4.75)
+  → `structural_source = { level: "design_src", design_src_dir: "<abs dir>" }`.
+This feeds Phase 2.7 (`markup-fidelity-verifier`) and is what makes per-card fidelity
+verifiable **without rendering the live route**.
+
 ### Level (c) — Compliance-only (registry)
 
 If no mockup image is available BUT `features.has_design_system: true`:
@@ -244,6 +259,59 @@ The cascade output is appended to the plan under `mockup_refs[]`.
 
 ---
 
+## Phase 2.7 — Structural Fidelity (route-free, runs BEFORE the browser)
+
+**Goal**: catch layout/structure divergence from the mockup **without rendering the live
+route** — the route-independent first line of defense. This is what would have caught
+FEAT-0061 (a 2-column desktop mockup built as a single column) even though the
+auth-gated route returned 500 in the harness. SSOT: `framework/agents/design-system-protocol.md` §
+"Route-Independent Fidelity & Coverage Obligation" → 1. Structural Fidelity.
+
+**When it runs**: for every route whose `structural_source` was recorded in Phase 2
+(`level == "html"` or `"design_src"`). Skip the route here only when there is no
+code-form mockup (image-only `figma`/PNG mockups have nothing to diff structurally —
+they go through Phase 4 visual + the coverage obligation instead).
+
+For each such route:
+
+1. **Resolve the implementation files** for the route from the diff / the card's File
+   Ownership Map (the `*.tsx` / `*.css` / `*.module.css` / `*.scss` / `*.svelte` / `*.vue`
+   the card touched under `${paths.app_dir}` / `${paths.components_root}`).
+2. **Invoke `markup-fidelity-verifier`** (input contract in
+   [`markup-fidelity-verifier.md`](../../agents/markup-fidelity-verifier.md)):
+
+   ```
+   subagent_type: "markup-fidelity-verifier"
+   mode: "bypassPermissions"   // when called from /new
+   prompt: |
+     Compare the implementation's code structure against the mockup's code structure
+     and return JSON per your output schema.
+
+     Input payload:
+     {
+       "card_id": "FEAT-XXXX",
+       "route": "/settings",
+       "mockup_source": { ...the route's structural_source (html | design_src)... },
+       "implementation_files": [ ...abs paths the card touched for this route... ],
+       "tolerance": "<from config>",
+       "resolved_orphans": [ ...from the card's UI Element Inventory, as in Phase 4... ]
+     }
+   ```
+3. **Parse the JSON strictly** (same discipline as Phase 4). On malformed output log
+   `markup_verifier_protocol_violation` in `gaps[]` and treat the route's structural
+   findings as empty.
+4. **Aggregate** structural findings into `structural_findings[]` (tag each `source:
+   "structural"`). They flow into the Phase 5 gate under the canonical taxonomy — a
+   `layout-break` here is Critical and BLOCKS. Because this runs before Phase 3/4, a clear
+   structural divergence blocks **cheaply**, before the expensive browser + multimodal
+   passes.
+
+This phase is **route-independent**: it never starts a dev server, never authenticates,
+never needs data. It is the workhorse of per-card fidelity; the render passes (Phase 4)
+are the confirmation.
+
+---
+
 ## Phase 3 — Functional E2E (browser-based)
 
 **Goal**: execute the Gherkin scenarios from Phase 1 in a real browser and
@@ -324,11 +392,72 @@ capture the result + screenshots per route.
    - `failure_reason` (when failed, the first assertion error + stack hint)
    - `screenshot_paths[]` (per route: the desktop `<route-slug>.png` AND the
      mobile `<route-slug>@mobile.png`)
+   - `render_health` (per route): the HTTP status of the route navigation and
+     whether the screenshot is a **degenerate render** — a non-2xx/error page, or
+     a blank/empty-state page. Capture the response status from the Playwright
+     navigation (`response.status()`); flag `degenerate: true` when status is not
+     2xx OR the page has no meaningful content. This drives Phase 3.8.
 5. **Functional findings**: every `failed` or `flaky` scenario becomes a
    functional finding in the aggregate report (Phase 5). Severity:
    - Auth / payments / data-mutation scenario failed → `critical`
    - Display-only scenario failed → `major`
    - Flaky (passed on retry) → `minor` with `confidence: low`
+   - **A `skipped` scenario is NOT silently dropped when its route has a mockup
+     (`mockup_source.level != "skip"`)**: a skip means the fidelity check did not
+     run, which is a coverage concern, not a pass — it is carried into Phase 3.8
+     (state remediation) and, if still un-renderable, into the coverage obligation
+     (Phase 4 step 1c). Silently skipping a mockup'd route is the exact FEAT-0061
+     failure and is prohibited.
+
+---
+
+## Phase 3.8 — Comparable-render gate (route-independent lane + state remediation)
+
+**Goal**: guarantee that the screenshot handed to Phase 4 is **comparable to the
+mockup** — rendered route-independently where possible, and in the **data state the
+mockup depicts**. The reviewer never accepts "I opened the page, it's empty, I skip".
+SSOT: `design-system-protocol.md` § "Route-Independent Fidelity & Coverage Obligation"
+→ 2. Visual Fidelity + 3. State-aware Fidelity.
+
+For each route with a mockup (`mockup_source.level != "skip"`):
+
+1. **Pick the render lane** (priority order):
+   - **(a) Isolated render** — when the route's primary surface is a **registry
+     primitive** (a component documented under `${paths.components_primitives}` with a
+     spec HEAD), render it in isolation via the `/ds-render` harness (`baldart render
+     build|shot`). This needs no route, no auth, no data — the route-independent visual
+     confirmation. Save to `.baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.iso.png`
+     and use it as the implementation screenshot for Phase 4. (Composed page surfaces are
+     NOT auto-rendered in isolation — that was refuted in v4.76; they use lane (b).)
+   - **(b) Live-route screenshot** from Phase 3, when the route rendered cleanly
+     (`render_health.degenerate != true`).
+2. **State remediation (the reach-state loop)** — when the chosen render is **degenerate**
+   (`render_health.degenerate == true`: non-2xx, empty-state, wrong tenant/store) and the
+   mockup depicts a populated state, do NOT accept it. Run a **bounded** loop (cap = 2):
+   - Read the consumer's `.baldart/overlays/e2e-review.md` **reach-state recipes** and run
+     the applicable ones in order: `seed_data` → `select_populated_context` (the multi-store
+     case: select a store/tenant that has data) → `goto_populated_entity`. Re-render, re-check
+     `render_health`.
+   - **Generic fallbacks when no recipe exists**: authenticate with the persona's real
+     creds (`test_plan.test_credentials`); enable MSW/API-mock of the data response if the
+     project supports it; apply a deterministic factory/snapshot seed; or heuristically
+     auto-seek a populated context via `webapp-testing` (enumerate an on-screen
+     store/tenant selector, pick the option that yields non-empty content).
+   - Stop as soon as a non-degenerate, populated render is produced.
+3. **Outcome**:
+   - A comparable render was produced → it is the implementation screenshot for Phase 4.
+   - Still degenerate after the loop **and** the mockup is **code-form** (a Phase 2.7
+     `structural_source` exists) → the structural pass already covered fidelity; record
+     `render_unavailable` in `gaps[]` and let Phase 4's visual step skip this route's
+     desktop diff (no false coverage-gap — structure was checked route-free).
+   - Still degenerate after the loop **and** the mockup is **image-only**
+     (`level ∈ {figma, local}` with no `structural_source`) → mark the route
+     `coverage_obligation_unmet = true` for Phase 4 step 1c (it will synthesize a
+     `coverage-gap`).
+
+The orchestrator owns navigation/seeding here; `visual-fidelity-verifier` stays stateless
+and only judges the frame it is handed (emitting `data-state-mismatch` if the state is
+still wrong).
 
 ---
 
@@ -353,8 +482,19 @@ For each `route` in `plan.routes[]`:
    - When `mockup_source.level == "skip"`, skip the **desktop fidelity diff**
      (steps 2) for this route — but still run the **mobile responsive pass**
      (step 2b) if a `<route-slug>@mobile.png` screenshot was captured, since it
-     needs no mockup. Skip the route entirely only when no screenshot exists
-     (route unrenderable).
+     needs no mockup.
+   - **1c. Coverage obligation (un-runnable required check BLOCKS, never passes).**
+     When the route is marked `coverage_obligation_unmet = true` from Phase 3.8 (an
+     **image-only** mockup — `level ∈ {figma, local}` with no `structural_source` — that
+     could not be rendered in any lane and whose state could not be reached), **synthesize
+     a `coverage-gap` finding (Critical)** instead of silently skipping the route. SSOT:
+     `design-system-protocol.md` § "...→ 4. Coverage Obligation". **Guards — NEVER synthesize
+     `coverage-gap`** when `mockup_source.level` is `skip` / `harness-render` /
+     `compliance-only`, nor for the mobile pass (it runs at `level: skip`), nor when a
+     Phase 2.7 `structural_source` already covered fidelity route-free. A `coverage-gap`
+     is **not fixable by an agent** — it bypasses the Phase 5b self-heal loop and maps to
+     the `blocked` verdict (the route still will not render). This is the guard that turns
+     the FEAT-0061 "skip masked as pass" into a real block.
    - When `mockup_source.level == "harness-render"` (a render-harness PNG of an
      ISOLATED registry primitive, from `/ds-render` — Stage C of the closed loop),
      **NEVER run the fidelity diff (step 2)**: the image is a render of the
@@ -505,14 +645,20 @@ For each such `route`:
 the canonical severity taxonomy from `visual-fidelity-verifier.md`.
 
 1. **Compose** the `findings[]` array:
+   - **Structural findings** from Phase 2.7 (`source: "structural"`) — route-free
+     code-structure divergence (`markup-fidelity-verifier`).
    - Functional findings from Phase 3 (`source: "functional"`).
-   - Visual findings from Phase 4 (`source: "visual"`).
+   - Visual findings from Phase 4 (`source: "visual"`) — including any
+     `data-state-mismatch` (the verifier saw an empty/wrong-state render) and any
+     orchestrator-synthesized `coverage-gap` (Phase 4 step 1c — a required check that
+     could not run at all).
    - Design-quality findings from Phase 4b (`source: "design-quality"`).
    - Each finding carries: `severity`, `category` (or `dimension` for
      design-quality), `source`, `route`, `description`, `expected`, `actual`,
-     `fix_hint`, `evidence`, `ds_drift_code`, `confidence`. All three sources
+     `fix_hint`, `evidence`, `ds_drift_code`, `confidence`. All sources
      share the **same canonical severity taxonomy**, so the tolerance filter in
-     step 2 applies to them uniformly — no per-source special-casing.
+     step 2 applies to them uniformly — no per-source special-casing. (`coverage-gap`
+     and `data-state-mismatch` are Critical and gate in every tolerance.)
 2. **Apply tolerance filter** based on
    `features.e2e_review.fidelity_tolerance`:
    - `strict` (DEFAULT): Critical + Major + Minor all gate. Additionally,
@@ -533,16 +679,25 @@ applies only when `verdict == "blocked"` AND `iteration < max`.
 
 For each iteration:
 
-1. **Route the gating findings to the right fixer by `source`**, then spawn the
-   fixer(s). Design-quality fixes are UI-scoped (presentation / layout / styling
-   / motion) — they belong to `ui-expert`, the UI domain owner, NOT to `coder`.
-   Functional fixes belong to `coder`. (Visual-fidelity findings follow their
-   nature: token/spacing/typography fixes route to `ui-expert`; a missing or
-   mis-wired element route to `coder`.) When both buckets are non-empty, run
-   `coder` first (structure), then `ui-expert` (presentation), so the critic
-   re-evaluates the final surface.
-
-   - **`ui-expert`** — gating findings where `source == "design-quality"` (and
+0. **`coverage-gap` findings bypass the loop.** A `coverage-gap` is not fixable by any
+   agent (the route still will not render — it is a harness/data limitation, not a code
+   defect). Do NOT spawn a fixer for it. It keeps the verdict `blocked` and flows straight
+   to the override path below (programmatic mode returns `blocked`; `/new` escalates it to
+   a follow-up card). If `coverage-gap` is the ONLY gating finding, skip the rest of this
+   loop entirely.
+
+1. **Route the remaining gating findings to the right fixer by `source`**, then spawn the
+   fixer(s). **Fidelity is UI-scoped**: `source == "structural"` (layout/grid/order —
+   `markup-fidelity-verifier`), `source == "design-quality"`, and UI-presentation
+   `source == "visual"` (token/spacing/typography/color, `data-state-mismatch` left to
+   state remediation) all belong to **`ui-expert`**, the UI domain owner, NOT `coder`.
+   `coder` gets only `source == "functional"` and genuine **wiring/data-binding** visual
+   findings (a missing element that is unwired, not mis-laid-out). When both buckets are
+   non-empty, run `coder` first (structure/wiring), then `ui-expert` (presentation), so the
+   critic re-evaluates the final surface. **On a pure-graphics card (`owner_agent:
+   ui-expert`), ALL fidelity fixes go to `ui-expert` — `coder` is not involved.**
+
+   - **`ui-expert`** — gating findings where `source in {structural, design-quality}` (and
      UI-presentation `source == "visual"` findings):
 
      ```
@@ -553,13 +708,16 @@ For each iteration:
 
      ## Gating findings
      [paste the JSON findings filtered to gating severity, source in
-      {design-quality, visual}]
+      {structural, design-quality, visual}]
 
      ## Rules
      - File ownership: stay within the card's allowed file set (see
        /tmp/batch-tracker-<FIRST-CARD-ID>.md ## File Ownership Map).
      - One fix per finding. Reuse existing tokens / primitives before inventing
        new ones (cite ${paths.design_system}/INDEX.md + tokens-reference.md).
+     - For a `structural` `layout-break`, match the mockup's layout exactly (e.g.
+       restore the 2-column grid the mockup declares) — cite the mockup ref in the
+       finding's `expected`.
      - Run the Post-Intervention Coherence Check on any registry-touching fix.
      - After the fixes, re-run lint and typecheck. Both must pass.
      - Do NOT modify Playwright specs or this skill's state files.
@@ -594,8 +752,10 @@ For each iteration:
 
    Both fixers run in `bypassPermissions` mode when called by `/new`.
 
-2. **Re-run Phase 3 (functional), Phase 4 (visual), and Phase 4b (quality)**
-   with fresh screenshots. Increment `iteration`.
+2. **Re-run the affected verifiers**: Phase 2.7 (structural, route-free — re-run when a
+   `structural` fix was applied), Phase 3 (functional), Phase 3.8 (re-render / state),
+   Phase 4 (visual), and Phase 4b (quality) with fresh screenshots. Increment `iteration`.
+   (A `coverage-gap`-only block does not enter this loop — see step 0.)
 3. **Re-aggregate and re-decide** (back to Phase 5 step 1).
 4. **STOP** when `verdict == "passed"` OR `iteration == max`.
 
@@ -698,8 +858,14 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 - **`/design-review` command** — when invoked from this skill with
   `mode: "programmatic"`, returns JSON instead of Markdown for gating.
   See [`framework/.claude/commands/design-review.md`](../../commands/design-review.md).
+- **`markup-fidelity-verifier`** (Phase 2.7) — route-free structural twin of
+  `visual-fidelity-verifier`: compares the mockup's code structure (HTML / `design_src`)
+  against the implementation source, no render. See
+  [`markup-fidelity-verifier.md`](../../agents/markup-fidelity-verifier.md). Its fixes
+  route to `ui-expert`.
 - **`visual-fidelity-verifier`** (Phase 4) — judges fidelity to the mockup /
-  spec. See [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md).
+  spec (pixels), and emits `data-state-mismatch` when the render is in the wrong data
+  state. See [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md).
 - **`ui-quality-critic`** (Phase 4b) — judges intrinsic design quality against
   the rubric, independent of any mockup. See
   [`ui-quality-critic.md`](../../agents/ui-quality-critic.md). It is the design
@@ -740,6 +906,9 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 | Quality loop never converges (design-quality findings persist) | Taste-leaning Minor findings, or `ui-expert` fixing one dimension while regressing another | Confirm the findings are gating (not low-confidence Minor auto-demoted in strict). If genuine and unresolved after max iterations, override with reason and open a `ui-expert` follow-up card — do NOT block indefinitely on subjective polish |
 | `quality_critic_protocol_violation` in gaps | `ui-quality-critic` returned prose mixed with JSON | Re-spawn the critic once; if persistent, surface to user (likely a model regression). Treat that route's quality findings as empty meanwhile |
 | `verifier_protocol_violation` in gaps | `visual-fidelity-verifier` returned prose mixed with JSON | Re-spawn the verifier once; if persistent, surface to user (likely a model regression) |
+| `coverage-gap` (Critical) on a route | An image-only mockup route could not be rendered in any lane and its state could not be reached | Correct by design — the gate BLOCKS instead of silently passing. Add a reach-state recipe to `.baldart/overlays/e2e-review.md` (seed / select populated context), or provide an HTML/`design_src` mockup so the route-free structural pass covers it. Never override without fixing the lane |
+| `data-state-mismatch` (Critical) on a route | Render opened an empty / wrong-tenant / error state; mockup depicts a populated state | The reach-state loop (Phase 3.8) should seed/select a populated context. If it has no recipe and cannot auto-seek, add `select_populated_context` / `seed_data` to the e2e-review overlay |
+| `markup_verifier_protocol_violation` in gaps | `markup-fidelity-verifier` returned prose mixed with JSON | Re-spawn once; if persistent, surface to user. Treat that route's structural findings as empty meanwhile |
 
 ---
 

package/framework/.claude/skills/new/references/codex-gate.md

@@ -44,7 +44,21 @@ Log the detector output in the tracker for traceability. **This step never short
 > `baldart teardown-codex-broker`), with the `baldart doctor` reaper as the safety net. Per-card hygiene
 > is none.
 
-For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
+**Pure-graphics-card skip (narrow exception — since v4.78.0).** Skip the per-card
+`/codexreview` gate entirely when the card is **pure-graphics**: `owner_agent: ui-expert`
+**AND** `review_profile: light` **AND** `areas == [ui]` exactly (no `api`/`data`/`logic`/`auth`
+area) **AND** Step A matched **zero** high-risk triggers on the actual diff. Rationale: a
+zero-logic UI card's meaningful review is the **`/e2e-review` fidelity trio** —
+`markup-fidelity-verifier` (structure) + `visual-fidelity-verifier` (pixels + a11y) +
+`ui-quality-critic` (quality) — plus the mechanical build/lint/tsc gates; a general Codex
+bug-sweep over presentational CSS/JSX is low-value noise (the user's "qa codex review non
+serve" for graphics). **Safety net preserved:** the **Final-review FULL `/codexreview`**
+(net #2 below) ALWAYS re-sweeps the ENTIRE batch diff before merge — so the graphics card's
+code is still Codex-reviewed batch-wide, just not per-card. The Step-A zero-trigger condition
+means any high-risk path on the diff cancels the skip (escalation-only invariant). Log
+`codex: SKIPPED (pure-graphics — fidelity trio is the review; Final FULL gate re-sweeps)`.
+
+For EVERY other card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
 
 0. **Select the Codex review profile (deterministic — Review Profile Selector)** by mapping the
    card's review profile (read from the card's `review_profile` field per the QA Profile Selector

package/framework/.claude/skills/new/references/completeness.md

@@ -263,6 +263,8 @@ This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` a
 
    Do NOT batch the question across multiple ACs — one `AskUserQuestion` per AC, so the user sees each AC's text in isolation. Issue the questions sequentially.
 
+   **Fidelity-AC carve-out (BLOCKING — the FEAT-0061 fix).** When the deferred AC is a **visual-fidelity AC** — its text matches `/visual|fidelit|mockup|layout|responsive|1:1|design (match|reference)/i` OR it asserts the screen matches a design reference (`links.design` / `links.design_src`) — option 2 **"Approva il deferral" is NOT offered**. A fidelity AC cannot be silently deferred or "covered by a downstream card": that is exactly the `FEAT-0061-08 → 04/10` cross-card deferral that shipped a 1-column page against a 2-column mockup. Offer only **1 (Implementa adesso — route the fix to `ui-expert`)**, **3 (Sposta su follow-up card — explicit, tracked, and the new card carries the fidelity AC + `links.design`, so it re-faces the `/e2e-review` gate)**, **4 (Ferma il batch)**. **When AUTONOMOUS:** take option 3 (follow-up card) — never approve the deferral. Note: with the route-free structural pass (`/e2e-review` Phase 2.7) a UI card now verifies its OWN surface without a live route, so a genuine *need* to defer fidelity should be rare; treat a fidelity deferral as a signal that the per-card gate was skipped, not as a routine outcome.
+
 5. **`implementation_notes` deferral audit (cheap text grep — also BLOCKING)** — before exiting the phase, scan the card YAML's `implementation_notes` field (post-edits, including any text added during this phase) for any of these phrases:
 
    - `deferred` / `deferral` / `defer to`

package/framework/.claude/skills/new/references/review-cycle.md

@@ -116,6 +116,8 @@ so it surfaces in telemetry.
 
 > **Trivial fast-lane gate**: re-confirm `IS_TRIVIAL` on the ACTUAL committed diff (§ "Trivial-card fast-lane" — all 3 conditions, now including the real non-source diff check). If trivial → **SKIP this phase** AND Phase 3.5 QA + Phase 3.7 Codex; instead run the **inline mechanical gates** (`markdownlint` on changed `.md`, `lint` on lintable changed files, `build` as a sanity check — no qa-sentinel, no test suite), then proceed to Phase 3 (doc review, which DOES run) and Phase 4 (commit). Log `simplify/qa/codex: SKIPPED (trivial — non-source diff)`. If the actual diff turned out to contain a source file → NOT trivial → run this phase and the normal review path. AC-Closure (Phase 2.5b) already ran and is never skipped.
 
+> **Pure-graphics fast-lane gate (since v4.78.0)**: when the card is **pure-graphics** (`owner_agent: ui-expert` AND `review_profile: light` AND `areas == [ui]` exactly — no api/data/logic/auth — AND zero Step-A high-risk triggers on the diff), **SKIP this Simplify phase** (quality-only; `ui-expert` already builds reuse-first) and Phase 3.7 Codex (per `codex-gate.md` § "Pure-graphics-card skip"). QA (Phase 3.5) is already skipped at `light` — the mechanical lint/tsc/build from Phase 2 step 8 is the "qa = build" floor. **Phase 2.6 `/e2e-review` is NOT skipped** — the fidelity trio (`markup-fidelity-verifier` + `visual-fidelity-verifier` + `ui-quality-critic`) is the real review for a graphics card. Doc-review (Phase 3) still runs (registry/spec reconciliation). Log `simplify/codex: SKIPPED (pure-graphics — fidelity trio is the review)`.
+
 After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.
 
 **Step-by-step**:
@@ -156,6 +158,17 @@ The skill replaces the previous advisory pair (legacy Phase 2.6 E2E testing
 and Phase 2.7 visual design review). It runs by default on every UI card,
 auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
 
+> **Route-independent, self-contained verification (since v4.78.0).** This card verifies
+> its **OWN** UI surface — it does NOT defer fidelity to a downstream card. `/e2e-review`
+> now runs a **route-free structural pass** (Phase 2.7, `markup-fidelity-verifier`: the
+> mockup's HTML/`design_src` code vs the implementation source) before any browser, so a
+> component card with no route of its own is still fully verifiable. Consequences for the
+> gating table below: a fidelity AC closes **only** on a real `passed` (a comparison was
+> performed) — a `skipped` does NOT close it, and a route that opened empty/degenerate
+> surfaces as `blocked` via `data-state-mismatch` / `coverage-gap`, never a silent pass.
+> A genuine cross-card fidelity deferral must go through the Phase 2.5b fidelity-AC
+> carve-out (explicit follow-up card), never a free-text note. This is the FEAT-0061 fix.
+
 #### Gate (skip the whole phase when any of the below is true)
 
 | Condition | Action |
@@ -206,7 +219,7 @@ When the gate above passes, the orchestrator invokes `/e2e-review` in
 | `status` from `/e2e-review` | Orchestrator action |
 |----|----|
 | `"passed"` | Log result in tracker. Proceed to Phase 3 (doc review + code review). |
-| `"skipped"` | Log skip reason. Proceed to Phase 3. |
+| `"skipped"` | Log skip reason. Proceed to Phase 3. **If the card has `links.design` / `links.design_src` yet the skill returned `skipped`, that is suspicious post-v4.78.0** (the route-free structural pass should have run): record `[E2E-FIDELITY-SKIP] <reason>` in `## Issues & Flags`, and do NOT mark any fidelity AC `[x]` on a skip — a fidelity AC closes only on a real `passed`. |
 | `"overridden"` | Log override + reason in `## Issues & Flags` as `[E2E-OVERRIDE] <reason>`. Proceed to Phase 3. |
 | `"blocked"` | **STOP the card**. Log findings in tracker + `## Issues & Flags` as `[E2E-BLOCKED] <count> gating findings (<categories>)`. Ask the user whether to (a) override with reason, (b) escalate (open follow-up card), or (c) abandon this card and continue the batch. Do NOT proceed to Phase 3 silently. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a blocked E2E is a real gating failure) → take (b) escalate to a follow-up card; NEVER take (a) override autonomously.** |
 | `"error"` | Log error in `## Issues & Flags`. Ask the user whether to retry, skip, or abandon. Do NOT proceed silently. **Retry re-entry (defined path, capped):** on "retry", re-enter at step 1 of this Invocation contract — reset the `.baldart/e2e-review/<CARD-ID>/` state dir, re-spawn `/e2e-review` with the SAME payload, and re-parse. **Cap: 2 error-retries per card** (central repair cap, consistent with the other loops). On the 2nd `error`, do NOT re-offer "retry" — re-invoke `AskUserQuestion` with only skip/abandon, so the loop cannot recur unbounded. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=retry once (the capped re-entry above); if still `error` → skip the E2E for this card AND materialize a follow-up card to re-run it (NEVER abandon the card silently).** |

package/framework/agents/component-manifest-schema.md

@@ -51,11 +51,12 @@ source: components/ui/Button.tsx          # path relative to repo root
 source_sha: a1b2c3d                        # git blob sha of source at last generation (drift anchor)
 status: stable                            # stable | experimental | deprecated  (default stable; `deprecated` is a hand override)
 category: primitive                       # primitive | composite | feature      (heuristic on import fan-in; hand-overridable)
-props:                                    # from the TS prop type / interface
+props:                                    # from the TS prop type / interface (TS-aware: resolves aliases / unions / intersections / Omit / Pick)
   variant: { type: "'primary'|'ghost'|'destructive'", required: false, default: "'primary'" }
   size:    { type: "'sm'|'md'|'lg'", required: false, default: "'md'" }
   disabled: { type: boolean, required: false, default: false }
-variants: [primary, ghost, destructive]   # enumerated literal union of the `variant` prop
+variant_prop: variant                     # which prop IS the variant axis (ranked; '' if none). NOT hardcoded to `variant` — a Chip whose axis is `tone` reports `tone`.
+variants: [primary, ghost, destructive]   # enumerated literal union of the `variant_prop` type
 composes: [Slot, Spinner]                 # in-registry primitives imported by this component
 # === AGENTIC — curated by doc-reviewer; survives regeneration, never clobbered when non-empty ===
 purpose: "Primary action trigger; one primary per surface."
@@ -76,7 +77,27 @@ owner: doc-reviewer                       # curation owner (constant; documents
 
 | Origin | Fields | Rule |
 |---|---|---|
-| **Deterministic** (TS/git) | `name`, `source`, `source_sha`, `status` (default), `category` (heuristic), `props`, `variants`, `composes` | Always safe to **overwrite** on regeneration — they are derived. Extracted by a pure Node script (no agent), so the path is **portable to Codex**. |
+| **Deterministic** (TS/git) | `name`, `source`, `source_sha`, `status` (default), `category` (heuristic), `props`, `variant_prop`, `variants`, `composes` | Always safe to **overwrite** on regeneration — they are derived. Extracted by a pure Node script (no agent), so the path is **portable to Codex**. |
+
+**TS-aware extraction (since v4.77.0).** When `typescript` is resolvable from the
+consumer root, the extractor parses the source syntactically (`ts.createSourceFile`
+— no tsconfig/TypeChecker) and resolves type **aliases**, **unions**,
+**intersections**, and **`Omit`/`Pick`** in the props type (`type V='a'|'b'; variant: V`
+→ `['a','b']`). Opaque / imported types (`ComponentPropsWithoutRef<'button'>`,
+`HTMLAttributes`) stay **empty** — never a DOM-attribute dump. When typescript is
+absent (Codex / greenfield / non-TS stack) or a file fails to parse, it falls back
+to the zero-dep **regex** path for that file (today's behaviour, no regression).
+
+**`variant_prop` (the variant axis).** A prop is a variant-axis *candidate* iff its
+resolved type is a pure string-literal union; the winner is the first by the rank
+`variant > tone > intent > kind > appearance > state > status > color > severity`,
+else the sole candidate, else `''`. `variants` is the literal members of
+`variant_prop`'s type. Consumers (render harness, `@dsCard` compiler) use
+`variant_prop` as the axis key — so a `Chip` whose axis is `tone` mounts `tone`,
+not a phantom `variant`. **Legacy HEADs** (pre-v4.77.0, no `variant_prop`) **default
+the axis to `'variant'`** when `variants` is non-empty, so existing registries keep
+rendering identically; a one-time re-extract backfills the field (see
+`/design-system-init` UPGRADE mode).
 | **Agentic** (doc-reviewer) | `purpose`, `token_bindings`, `a11y`, `related`, `must_rules`, `canonical_for`, `use_when`, `selection_closed`, `last_verified`; plus `status: deprecated` as a judgment | **Never clobbered** when non-empty. Empty agentic fields = "not yet enriched", filled later by `doc-reviewer` / `ds-drift`, never auto-invented. |
 
 ### Selection-policy fields (the closed-set layer)

package/framework/agents/design-system-protocol.md

@@ -576,6 +576,84 @@ the most damaging case (a CSS-hidden heavy subtree) is invisible to a JS AST rul
 Rule 2 violations are HIGH; a viewport-scoped edit that mutates the other branch
 (rule 1) is MEDIUM.
 
+## Route-Independent Fidelity & Coverage Obligation (BLOCKING — SSOT)
+
+This is the single definition of how UI fidelity is verified per-card. `/e2e-review`,
+`/new` (implement + code-reviewer), `/ui-design`, and `/design-review` **cite** this
+section; they do not redefine it. The driving lesson (FEAT-0061): a fidelity check that
+depends on rendering a *live, data-bearing route* silently degrades to a pass when that
+route cannot render (auth-gated, empty database, wrong tenant) — a **skip masked as a
+pass**. The fix is to make verification **route-independent first** and to make an
+**un-runnable required check block, never pass**.
+
+### 1. Structural Fidelity (route-free) — runs FIRST
+
+When a card has a mockup expressed as code — `links.design` pointing to an **HTML**
+file, or `links.design_src` / `mockups/_src/` (finished Claude Design CODE, v4.75) — the
+**code-structural** comparison runs before any browser render, via the
+`markup-fidelity-verifier` agent. It compares the mockup's markup/CSS structure (grid vs
+flex, column count, element order, region presence, `@media` breakpoints) against the
+implementation source. This is the analogue of **tree-edit-distance over the DOM** — the
+*structural* dimension, complementary to the *perceptual* (pixel) dimension of
+`visual-fidelity-verifier`. It needs no browser, no auth, no data, and it deterministically
+catches the **2-column-mockup → 1-column-build** class of divergence. Its findings use the
+canonical severity taxonomy (SSOT in `visual-fidelity-verifier.md`); a structural
+`layout-break` is Critical. **Fixes route to `ui-expert`** (layout is the UI domain).
+
+### 2. Visual Fidelity — render as CONFIRMATION, route-independent where possible
+
+The pixel diff (`visual-fidelity-verifier`) confirms the structural result on a rendered
+image. The render source, in priority order: (a) **isolated render** of the surface via
+the `/ds-render` harness when it is a registry primitive (no route/auth/data needed);
+(b) the live-route screenshot when the route renders; (c) neither → a coverage obligation
+(below). The live-route screenshot is **not** the only fidelity source.
+
+### 3. State-aware Fidelity — `data-state-mismatch` (never compare a degenerate render)
+
+The render must reach the **data state the mockup depicts** (a populated table, a selected
+store/tenant). An empty-state / placeholder / error / wrong-context render of a route that
+HAS a mockup is a **`data-state-mismatch`** (Critical) — emitted by `visual-fidelity-verifier`,
+which sees the emptiness — **not** a silent skip or pass. The orchestrator owns *reaching*
+the depicted state via a bounded **reach-state loop**: project-specific recipes from the
+consumer's `.baldart/overlays/e2e-review.md` (`seed_data`, `select_populated_context`,
+`goto_populated_entity`), with generic fallbacks (real auth from the persona creds,
+MSW/API-mock, deterministic factory/snapshot, heuristic context auto-seek). The framework
+owns the contract + the loop; the overlay owns the project-specific *how*.
+
+### 4. Coverage Obligation — `coverage-gap` (un-runnable required check BLOCKS)
+
+A required fidelity check that **could not execute at all** must block, never pass. The
+orchestrator synthesizes a **`coverage-gap`** (Critical) finding when an **image-only**
+mockup exists (`mockup_source.level ∈ {figma, local}`, i.e. no HTML/code to diff
+structurally) AND neither an isolated render nor a route render produced a comparable
+screenshot, AND the state could not be reached. **Guards (never fire `coverage-gap`):**
+`mockup_source.level == skip` (no mockup → no obligation), `harness-render` (assertion-fitting
+guard — these go to quality only), `compliance-only` (registry-based, no image target), and
+the mobile responsive pass (runs at `level: skip` by construction). A `coverage-gap` is
+**not fixable by an agent** (the route still will not render) — it **bypasses the self-heal
+loop** and maps to the existing `blocked` verdict (the orchestrator's autonomous handling
+escalates it to a follow-up card). No new verdict status is introduced.
+
+### 5. Graphics-only card → `ui-expert` + the fidelity trio IS the review
+
+For a **pure-graphics card** (`owner_agent: ui-expert`, `review_profile: light`,
+`areas == [ui]` exactly — no api/data/logic/auth), the implementer is `ui-expert` (not
+`coder`), and the **fidelity trio is the review**: `markup-fidelity-verifier` (structure)
++ `visual-fidelity-verifier` (pixels + a11y) + `ui-quality-critic` (intrinsic quality,
+advisory), plus the mechanical build/lint/tsc gates. The deep `/codexreview` and
+`simplify` passes are skipped — their UI-relevant coverage (a11y, token-bypass, DS-drift,
+layout) is absorbed by the trio. All fidelity fixes (structural, presentational, quality)
+route to `ui-expert`.
+
+### Gating philosophy (calibration)
+
+Vision-model reliability research (*MLLM as a UI Judge*, 2025) shows multimodal judges are
+reliable at **comparison with clear differences** (~93%) but weak at **absolute scoring**
+(~35% exact, hedging toward low variance). Therefore the **hard gate is FIDELITY**
+(comparison against a ground truth: structural + visual), and **intrinsic-quality absolute
+scoring (`ui-quality-critic`) stays advisory / confidence-gated**, never a hard block. The
+2-col → 1-col case is a "clear difference" → maximum judge reliability.
+
 ## Post-Intervention Coherence Check (BLOCKING completion gate)
 
 The BLOCKING pre-work above enforces *reads* before any UI change. This
@@ -600,7 +678,7 @@ and the advisory check 6 (mirror, non-blocking):
 2. **Modified primitive ⇒ updated spec**: did the change alter a primitive's
    props / variants / accessibility behavior? If yes, the corresponding
    `components/<Name>.md` MUST be updated to match — including its **frontmatter
-   HEAD** (deterministic fields `props`/`variants`/`composes`/`source_sha`
+   HEAD** (deterministic fields `props`/`variant_prop`/`variants`/`composes`/`source_sha`
    regenerated from source; agentic fields re-verified). Stale spec =
    `DS_COMPONENT_STALE` finding, task blocked. (A prose-only spec lacking a HEAD
    is NOT stale merely for that — see `agents/component-manifest-schema.md`

package/framework/docs/COMPONENT-MANIFEST-LAYER.md

@@ -40,7 +40,7 @@ BALDART wraps the **standard** (DTCG) and owns only a thin generator — the sam
 |---|---|---|
 | HEAD schema | `framework/agents/component-manifest-schema.md` | SSOT for the frontmatter fields + read/regeneration/leniency contract |
 | Gate + cascade | `framework/agents/design-system-protocol.md` | BLOCKING reads, drift codes, token SSOT inversion, Authority Matrix |
-| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (`extractFile`) + `extract-one.mjs` (single-component wrapper) | zero-dep Node; name/source/source_sha/props/variants/composes (Codex-portable) |
+| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (`extractFile`) + `extract-one.mjs` (single-component wrapper) + `extract-ts.mjs` (optional TS-aware resolver) | Node; name/source/source_sha/props/variant_prop/variants/composes. **TS-aware** when `typescript` resolves from the consumer root (aliases/unions/intersections/Omit/Pick); **zero-dep regex fallback** otherwise (Codex-portable) |
 | Spec template | `framework/templates/component-spec.template.md` | CANONICAL prose-body template (SSOT); serializer fills it on creation via `--prose-template` (default) |
 | Bootstrap/upgrade | `framework/.claude/skills/design-system-init/SKILL.md` | greenfield + upgrade modes |
 | Token emitters | `src/utils/token-emitters/{index,ts,css}.js` | DTCG → stack-native output (REGISTRY pattern) |
@@ -72,8 +72,11 @@ has_design_system: true (no separate flag — the manifest rides on it)
 ## 5. Invariants (do not break)
 
 - **Codex portability**: the READ path and the deterministic half (extractor,
-  `baldart tokens build`) run with **no subagent**. Only agentic enrichment needs
-  Claude; under Codex it degrades to empty/TODO fields — never a hard failure.
+  `baldart tokens build`) run with **no subagent**. The TS-aware resolver
+  (`extract-ts.mjs`) is **optional** — it uses the consumer's own `typescript` when
+  resolvable and falls back to the **zero-dep regex** path per file otherwise, so
+  Codex / non-TS stacks are unaffected. Only agentic enrichment needs Claude; under
+  Codex it degrades to empty/TODO fields — never a hard failure.
 - **No twin**: ONE artifact per component (the spec, evolved) and ONE token SSOT
   (`.tokens.json`); `tokens-reference.md` and `tokens.ts`/CSS are **generated
   views/outputs**, never hand-authored sources. The INDEX is a generated router.

package/framework/templates/component-spec.template.md

@@ -24,8 +24,9 @@ source: {{file_path}}
 source_sha: {{source_sha}}
 status: {{status}}           # stable | experimental | deprecated  (default stable)
 category: {{category}}       # primitive | composite | feature
-props: {{props_yaml}}        # name → { type, required, default }  ({} if unresolved)
-variants: {{variants_yaml}}  # [] if none / unresolved
+props: {{props_yaml}}        # name → { type, required, default }  ({} if unresolved; TS-aware: resolves aliases/unions/intersections/Omit/Pick)
+variant_prop: {{variant_prop}}  # which prop is the variant axis (ranked; '' if none / unresolved; legacy HEADs default to 'variant')
+variants: {{variants_yaml}}  # [] if none / unresolved (literal members of variant_prop's type)
 composes: {{composes_yaml}}  # in-registry primitives this imports
 # AGENTIC fields (curated by doc-reviewer — preserved across regeneration):
 purpose: "{{purpose}}"