Visual Fidelity Reconciliation

Visual-Fidelity Reconciliation — Pixel-Perfect QA Against the Design Contract

"It looks fine" is a judgment call. This skill makes the look-and-feel of every shipped frontend change auditable against DESIGN_MAP.md. Every (screen, element, state) tuple in scope gets a verdict — perfect, drift, or gap — with evidence at every node. Drift is never patched inline; it is escalated to the architect-team for a fix routed through the standard dev loops with proper spec attribution.

This skill is the dual of design-fidelity-mapping:

• design-fidelity-mapping captures the contract (DESIGN_MAP.md).
• visual-fidelity-reconciliation verifies the implementation honors the contract.

Without this skill, design drift accumulates one PR at a time — each one too small to flag, the cumulative effect too large to ignore.

Four disciplines:

1. Zero-tolerance defaults. Bounding boxes match to the pixel. Colors match to the exact computed value. Typography matches family-AND-weight-AND-size-AND-line-height. Border radii, shadows, padding, and margins match exactly. Tolerances are explicit per-element overrides with recorded rationale — never silent global slop.
2. Exhaustive state walks. Every state listed in DESIGN_MAP.md OR implied by the component code gets verified: default, hover, focus, active, disabled, loading, error, empty, plus every responsive breakpoint declared in DESIGN_MAP.md's viewports_responsive frontmatter. Missing a state is a gap.
3. Fix drift to align to the spec; escalate only for genuine ambiguity or scope barriers. DESIGN_MAP.md is the agreed contract. When reconciliation finds drift, the default action is to CHANGE THE IMPLEMENTATION to match the spec, re-run reconciliation, and verify perfect. Escalation is the exception — reserved for cases where (a) the fix requires editing files outside the agent's scope, (b) the spec itself is ambiguous / internally inconsistent / references tokens that don't exist, or (c) the implementation has an element NOT in the spec and the architect-team must decide whether to add to spec or remove from implementation. Alerting the user without fixing is a process failure: the discipline converges to the spec, autonomously, every time.
4. Verify against the Oracle, never against a classification. Reconciliation establishes compliance by ONE means only: a fresh, direct comparison of the running implementation to the design contract (DESIGN_MAP.md), for every screen in scope, every run. It NEVER substitutes a classification for that comparison. A code-diff, a prior run's report, an intake / Phase −1B "design-recon" verdict, an "unchanged" / "untouched" / "not migrated" label — these answer what changed or what to re-map; they are NOT verdicts about what is design-compliant. "A prior run classified this screen UNCHANGED, so skip it" is the exact reasoning that lets systemic drift sail through undetected across a whole set of screens at once. A classification is a hint about where to look first — never a licence to NOT look.

When to run

• Phase 3 — Team review gate (automatic). When a frontend teammate marks any task complete and files_changed includes a frontend file AND DESIGN_MAP.md exists for the touched codebase, the teammate MUST produce a reconciliation report covering every (screen, element, state) tuple their change touched. The review-gate hook enforces this via the visual_fidelity_review evidence field (must be "pass" or "n/a"; "fail" blocks completion).
• Phase 5 — Cross-layer integration (automatic). The integration agent runs reconciliation across ALL screens (not just changed ones) as a regression check that upstream / sibling changes have not drifted the contract.
• On-demand audit via /architect-team:visual-qa (manual). Operator invokes the command at any point; the command refreshes DESIGN_MAP.md if stale, then runs reconciliation across all designed screens.

Phase 0 — Precondition: the LIVE RUNNING APP (a hard gate, before everything)

Visual-fidelity reconciliation compares the running application a real user would load against the design Oracle. The live app is the substrate of this entire skill. Before any scoping, any analysis, any verdict:

1. Start the real app. Use the documented dev / serve command from CODEBASE_MAP.md, running against the real backend (real dev API, real dev data — per dev-api-integration-testing and the v0.9.5 real-backend discipline; a data-bearing screen reconciled against fake data is meaningless).
2. Confirm it serves. Poll the app URL until HTTP 200; confirm what loads is the actual application, not a 404 / error overlay / placeholder.
3. Confirm you can reach every in-scope screen. Navigate to each; if a screen is unreachable, that is itself a finding.

If the live app cannot be made to run, you CANNOT do visual-fidelity reconciliation. STOP and escalate ("live app not runnable — visual-fidelity blocked"). You do NOT proceed to Phase B. You do NOT substitute static analysis, the design mockups, or Storybook-in-isolation for the live render. Static analysis (Phase B) is a cross-check layered on top of the live render — it is never a replacement for it. Reasoning about the code is not rendering the app; the two are not interchangeable, and a reconciliation built only on code-reading has verified nothing about what the user actually sees.

Every verdict this skill produces in Phase D MUST be backed by a screenshot of the LIVE APP captured during this run (Phase C). A tuple verdict with no live screenshot did not happen — it is a guess, not a verdict, and the report is invalid.

Phase A — Scope identification

Phase A.0 — Establish the design baseline FIRST (before any scoping)

Before scoping anything, answer one question: has the design Oracle itself moved since the implementation was last reconciled clean?

1. Read DESIGN_MAP.md's design_baseline (the label/version of the design generation it encodes — e.g. V2).
2. Determine the baseline the implementation was last reconciled-perfect against — read the design_baseline of the most recent reconciliation report. If there is no prior report, treat the last-clean baseline as unknown.
3. If the two differ — or DESIGN_MAP.md was just refreshed in a baseline migration per design-fidelity-mapping — a design-baseline migration is in progress. Apply "Design-baseline migrations" below.
4. If they are the same, this is a steady-state reconciliation; proceed to ordinary scoping.

Design-baseline migrations — when the Oracle moved (the "unchanged" inversion)

When the design generation itself changed — a redesign, a design-system version bump (Full → V2) — the normal intuition inverts, and you must reason about it explicitly rather than pattern-match:

• Every screen with a spec in DESIGN_MAP.md is in scope. No exceptions, regardless of phase. A baseline migration is not a per-team diff event — it is a whole-surface event. Phase 3's diff-scope (below) is insufficient during a migration; the every-screen sweep is mandatory.
• "Implementation unchanged" is the STRONGEST drift signal — never a skip signal. In steady state, an unchanged screen is probably still compliant. In a migration, a screen whose implementation has NOT changed has NOT been migrated to the new baseline: it is still rendering the OLD design and is therefore drifted by definition. An "unchanged" / "untouched" / "UNCHANGED Full→V2" classification during a migration means "this screen is unfinished work" — it is the LOUDEST possible call to reconcile-and-fix, the literal opposite of "skip."
• A classification that says a screen is unchanged is answering the wrong question. "Did the code change since the last run?" is a re-mapping question. "Does the implementation match the V2 Oracle?" is the reconciliation question. During a migration, those two questions have OPPOSITE answers for every unmigrated screen. Reconcile every screen directly against the V2 Oracle; do not let a code-diff, an intake recon report, or a prior-run classification narrow the set.

Concrete failure this prevents: a Full→V2 migration where a prior Phase −1B design-recon classified three role-landing-page screens as UNCHANGED Full→V2. Agents read "UNCHANGED" as "skip" and never reconciled those screens — so three h1s shipped at the old Full sizes/weights (26px/500, 20px/600) instead of the V2 Oracle (38px/400, 36px/400). The correct reading: UNCHANGED during a Full→V2 migration = "not yet migrated" = guaranteed drift = reconcile and fix every one.

Ordinary scoping (steady state — no baseline migration)

For Phase 3 (per-team), the scope is the set of (screen, element, state) tuples touched by the teammate's diff:

1. Read files_changed from the review evidence.
2. For each changed file, identify which screens / components it affects:
   • Component file (Button.tsx) → every screen that imports it (grep -r "from.*Button" --include="*.tsx" --include="*.jsx").
   • Token file (tailwind.config.{js,ts} / theme.ts / tokens.json / styles/tokens.css) → every screen (it cascades).
   • Asset file (logo.svg) → every screen referencing it (grep -r "logo.svg").
   • Stylesheet (globals.css / app.css) → every screen that loads it (cascades).
   • Storybook story (*.stories.tsx) → the component the story covers.
3. For each affected screen, the relevant rows from DESIGN_MAP.md's ## Per-Screen Visual Specs table become the in-scope reconciliation checklist. Plus every state listed for those elements + every responsive viewport from the frontmatter.

For Phase 5 (integration regression) and /architect-team:visual-qa, the scope is every screen with a per-screen visual spec in DESIGN_MAP.md. No exceptions; this is the regression net. "No exceptions" means literally that: the scope is NEVER narrowed by a changed-files list, a code-diff, a prior-run report, an intake recon classification, or an "unchanged" / "untouched" label. The reconciliation report's screens_reconciled_count MUST equal design_map_screen_count for a Phase 5 / on-demand run — a regression run that covers fewer screens than DESIGN_MAP has is an incomplete reconciliation, not a pass.

Phase B — Code-first static analysis (mandatory, BEFORE running the browser)

Before launching Playwright, read the component code that renders each in-scope element and statically confirm the values resolve to the DESIGN_MAP spec. Static analysis catches drift even when runtime tests pass (because someone updated the tests to match the drift).

For each in-scope element:

1. Locate the component source — grep for the testid or role-name in the codebase to find the JSX/template that renders the element. Identify every styling layer that affects it:
   • Inline styles (style={{ ... }}).
   • Tailwind classes (className="bg-brand-500 text-white px-4 py-2 ...") — resolve each class to its token value via the tailwind.config.{js,ts} and confirm against the DESIGN_MAP token.
   • CSS / SCSS module classes — find the source .module.css / .module.scss and resolve.
   • Styled-components / Emotion / Vanilla Extract / Stitches CSS-in-JS — read the styled.div\...`` block.
   • Global CSS / theme variables — trace var(--brand-primary) to its declaration in :root / [data-theme=...].
   • Inherited styles — check the parent chain for cascade.
2. Compare each style property to the DESIGN_MAP spec — for every property listed in the per-element row:
   • Code value resolves to spec value → tentative perfect (runtime will confirm).
   • Code value resolves to a different value → static drift, capture both with file:line citation.
   • Code value is dynamic (depends on a prop / theme / feature flag) → record the dependency and resolve at runtime in Phase C.
3. Check asset references statically — for every <img src=...> / <svg use href=...> / background-image: url(...), verify the path resolves to an entry in DESIGN_MAP's Asset Registry, and the file at that path matches the registered SHA-256 (compute via sha256sum / certutil).
4. Check link targets — for every element with a target_link in DESIGN_MAP, locate the click handler / href / to prop / router.push(...) / navigate(...) call in the source. Compare:
   • source: "explicit" → match REQUIRED. Mismatch is drift; fix the implementation to match the explicit target.
   • source: "inferred", confidence: "high" → match expected. Mismatch is drift, but with a note: the inference may have been wrong (the implementation is the more recent intent) OR the implementation drifted from intent. The fix-or-escalate decision uses the standard Phase E matrix; in practice, high-confidence inferences that match a coherent navigation web should be honored as the contract, and mismatches fix the implementation.
   • source: "inferred", confidence: "medium" or "low" → match is informational only. Mismatch escalates to clarify (awaiting_confirmation: true items become escalations naturally; the user confirms the target, which becomes explicit on the next DESIGN_MAP refresh).
   • source: "unknown" (target is "?") → cannot reconcile; record the implementation's actual link target as evidence and escalate so the user can promote it to explicit or correct it.

The static analysis output is a per-element static_verdict field captured into the reconciliation JSON before runtime. The runtime in Phase C either confirms it or contradicts it (which itself is a finding — usually means a cascade or runtime computation the static pass missed).

Phase C — Runtime verification against the LIVE APP (mandatory — this is the comparison)

After the static pass, run Playwright against the live running app from Phase 0 — the real application, real backend — per viewport declared in DESIGN_MAP.md, and verify the rendered values for every in-scope tuple. This is not an optional confirmation step layered on Phase B; it IS the reconciliation. Phase B (static) tells you what the code should resolve to; Phase C tells you what the user actually sees. The two disagree more often than intuition expects (runtime cascade, theme application, dynamic data, hydration) — and when they disagree, Phase C is the truth.

Phase C is the most-cut step in this skill. It is also the only step that actually compares the design to reality. Cutting it — doing Phase B and writing "perfect" without ever rendering the app — is the precise failure this skill exists to prevent. There is no verdict without a live render.

Setup per viewport

await page.setViewportSize({ width: 1440, height: 900 }); // EXACT viewport from DESIGN_MAP
await page.goto(screenUrl);
await page.waitForLoadState('networkidle');

Induce each state explicitly

After inducing, wait for the state-defining element / class to be present before measuring (e.g., await element.waitFor({ state: 'visible' }), or wait for a CSS class change indicating the state).

Measure every property

const styles = await element.evaluate((el) => {
  const cs = window.getComputedStyle(el);
  return {
    fontFamily: cs.fontFamily,
    fontSize: cs.fontSize,
    fontWeight: cs.fontWeight,
    fontStyle: cs.fontStyle,
    lineHeight: cs.lineHeight,
    letterSpacing: cs.letterSpacing,
    textTransform: cs.textTransform,
    textDecoration: cs.textDecorationLine,
    color: cs.color,
    backgroundColor: cs.backgroundColor,
    backgroundImage: cs.backgroundImage,
    paddingTop: cs.paddingTop, paddingRight: cs.paddingRight, paddingBottom: cs.paddingBottom, paddingLeft: cs.paddingLeft,
    marginTop: cs.marginTop, marginRight: cs.marginRight, marginBottom: cs.marginBottom, marginLeft: cs.marginLeft,
    borderTopWidth: cs.borderTopWidth, borderRightWidth: cs.borderRightWidth, borderBottomWidth: cs.borderBottomWidth, borderLeftWidth: cs.borderLeftWidth,
    borderTopColor: cs.borderTopColor, borderRightColor: cs.borderRightColor, borderBottomColor: cs.borderBottomColor, borderLeftColor: cs.borderLeftColor,
    borderTopStyle: cs.borderTopStyle,
    borderTopLeftRadius: cs.borderTopLeftRadius, borderTopRightRadius: cs.borderTopRightRadius, borderBottomRightRadius: cs.borderBottomRightRadius, borderBottomLeftRadius: cs.borderBottomLeftRadius,
    boxShadow: cs.boxShadow,
    outline: cs.outline, outlineColor: cs.outlineColor, outlineWidth: cs.outlineWidth, outlineOffset: cs.outlineOffset,
    cursor: cs.cursor,
    opacity: cs.opacity,
    transform: cs.transform,
    zIndex: cs.zIndex,
  };
});
const box = await element.boundingBox();

Plus take a per-state screenshot at the element scope:

await element.screenshot({ path: `<test-output-dir>/visual-fidelity/screenshots/<screen>-<element>-<state>-<viewport>.png` });

And a full-page screenshot at the viewport scope:

await page.screenshot({ path: `<test-output-dir>/visual-fidelity/screenshots/<screen>-<state>-<viewport>-page.png`, fullPage: true });

Screenshots are evidence; they go into the reconciliation JSON's per-tuple evidence[] array.

Compare with zero-tolerance defaults

Per-element tolerance overrides are allowed only when DESIGN_MAP.md has an explicit tolerance: clause for that element with a recorded rationale (e.g., tolerance: { width: 1px, rationale: "sub-pixel rounding observed across browser engines; not user-perceivable" }). Silent slop is forbidden.

Phase D — Reconciliation report

For each screen reconciled, persist <test-output-dir>/visual-fidelity/<screen>-<viewport>-<timestamp>.json:

{
  "schema_version": 2,
  "screen": "/login",
  "reconciled_at": "<ISO 8601 UTC>",
  "design_map_version": "<DESIGN_MAP.md last_designed timestamp>",
  "design_baseline": "<DESIGN_MAP.md design_baseline — the design generation reconciled against, e.g. V2>",
  "design_map_sha": "<git blob SHA of DESIGN_MAP.md at reconciliation time>",
  "viewport": { "width": 1440, "height": 900 },
  "engine": "chromium",
  "tuples": [
    {
      "element_id": "submit-button",
      "state": "default",
      "verdict": "perfect",
      "static_verdict": "perfect",
      "runtime_verdict": "perfect",
      "captured": { "font-family": "Inter, system-ui, sans-serif", "color": "rgb(255, 255, 255)", "background-color": "rgb(37, 99, 235)", "padding-top": "10px", "padding-right": "16px", "padding-bottom": "10px", "padding-left": "16px", "border-radius": "6px", "box-shadow": "0 1px 2px rgba(0, 0, 0, 0.05)", "width": 240, "height": 40 },
      "spec": { "font-family": "Inter, system-ui, sans-serif", "color": "#FFFFFF", "background-color": "#2563EB", "padding": "10px 16px", "border-radius": "6px", "box-shadow": "shadow.sm", "width": 240, "height": 40 },
      "delta": [],
      "evidence": ["screenshots/login-submit-button-default-1440.png", "screenshots/login-default-1440-page.png"]
    },
    {
      "element_id": "submit-button",
      "state": "hover",
      "verdict": "drift",
      "static_verdict": "drift",
      "runtime_verdict": "drift",
      "captured": { "background-color": "rgb(37, 99, 235)" },
      "spec": { "background-color": "#1D4ED8" },
      "delta": [
        {
          "property": "background-color",
          "captured": "rgb(37, 99, 235)",
          "spec": "rgb(29, 78, 216)",
          "severity": "high",
          "user_perceivable": true,
          "note": "hover state not implemented — element retains default background on :hover",
          "static_evidence": "Button.tsx:24 has no :hover styling for variant=primary",
          "runtime_evidence": "screenshots/login-submit-button-hover-1440.png"
        }
      ],
      "evidence": ["screenshots/login-submit-button-hover-1440.png"]
    },
    {
      "element_id": "remember-me-checkbox",
      "state": "default",
      "verdict": "gap",
      "captured": { "rendered": false },
      "spec": { "expected": "16x16 checkbox inline-flex with 'Remember me' label, 8px gap" },
      "delta": [
        {
          "property": "exists",
          "captured": "not rendered",
          "spec": "rendered",
          "severity": "high",
          "user_perceivable": true,
          "note": "checkbox component absent from JSX; spec calls for it",
          "static_evidence": "LoginForm.tsx — no <input type=\"checkbox\" /> nor RememberMe component referenced",
          "runtime_evidence": "screenshots/login-default-1440-page.png"
        }
      ],
      "evidence": ["screenshots/login-default-1440-page.png"]
    }
  ],
  "summary": {
    "tuples_reconciled": 24,
    "perfect": 22,
    "drift": 1,
    "gap": 1,
    "perfect_percentage": 91.67,
    "screens_in_scope": ["/login"],
    "viewports_in_scope": [{ "width": 1440, "height": 900 }],
    "states_in_scope": ["default", "hover", "focus", "disabled", "loading", "error"]
  }
}

Then aggregate all per-screen JSONs into a single <cwd>/.architect-team/visual-fidelity-summary-<ts>.md for the orchestrator and architect-team to read. The summary lists every drift and gap with screen + element + state + delta + severity. The aggregate summary MUST also record, in its header: the design_baseline reconciled against, design_map_screen_count (how many screens have a per-screen spec in DESIGN_MAP.md), and screens_reconciled_count (how many were actually reconciled in this run). For a Phase 5 regression run or an on-demand /architect-team:visual-qa run, screens_reconciled_count MUST equal design_map_screen_count. If it is lower, the reconciliation is incomplete — some screens were skipped — and the run does NOT pass; reconcile the remaining screens. This count check is the mechanical guard against the "a prior run said these were unchanged, so I skipped them" failure.

Phase E — Drift / gap remediation (fix to spec by default; escalate only on the narrow exceptions)

When Phase D produces any tuple with verdict drift or gap, the discipline is to FIX the implementation to align with the spec. The hook will eventually block visual_fidelity_review: "fail" — but the goal is to never need that branch. The reconciliation loop is fix → re-run Phase B (static) and Phase C (runtime) → verify perfect → set "pass".

The fix-or-escalate decision matrix

For each drift / gap row in the reconciliation JSON, decide:

How to fix (concrete)

1. Identify the styling layer carrying the drifted value (inline / Tailwind class / CSS module / CSS-in-JS / theme variable / cascading parent).
2. Change the value at its source — prefer fixing the token (in tailwind.config.{js,ts} / theme.ts / tokens.json / :root CSS variables) over fixing the call-site if the spec value matches an existing token name. Prefer fixing the call-site over inventing new tokens when the spec value is one-off.
3. Never bandage — adding a class that overrides a wrong inherited value is a bandage; fix the inheritance.
4. Asset fixes — if src is wrong, point it to the registered asset. If the file's SHA-256 has drifted, the asset bytes were modified; restore from the registry or escalate if the modification was intentional.
5. State-induction fixes — if :hover styles are missing (the drift is "default and hover have the same bg"), add the :hover (or data-state=hover / &:hover in CSS-in-JS) rule producing the spec value.
6. Responsive fixes — if a breakpoint diverges, add or correct the @media / Tailwind breakpoint variant (e.g., md:px-6) for that viewport.
7. Re-run reconciliation on the tuples you fixed before claiming verdict pass. The reconciliation JSON's passes_after_fix field should record how many iterations the convergence took (1 ideally; more than 3 is a smell — escalate).

Escalation (only for the narrow exceptions above)

When escalating:

1. Write the reconciliation JSON(s) and the summary as evidence (these already exist from Phase D).
2. Set visual_fidelity_review: "fail" in the review evidence — the hook will block the TaskUpdate, which is correct: a teammate cannot mark complete with unresolved drift.
3. Write the handoff to <cwd>/.architect-team/handoffs/<self>-to-architect-visual-<reason>-<screen>-<ts>.md where <reason> is one of: out-of-scope, implementation-extras, spec-ambiguity, cascade-blast-radius. The handoff contains:
   • DESIGN_MAP.md version reconciled against (timestamp + blob SHA).
   • The summary of every drift / gap with severity.
   • The link(s) to the reconciliation JSON(s) and the per-state screenshots.
   • Crucially: WHY this isn't being fixed autonomously — name the specific decision matrix row that triggered escalation. Without this, the handoff is just an alert (which the user said is insufficient).
   • For scope-out-of-bounds escalations, identify the team that owns the file (git log ownership) so the orchestrator can route directly.
4. Write a solution requirement (mandatory) per team-spawning-and-review-gates's ## Solution Requirements section to <cwd>/.architect-team/solution-requirements/SR-<screen>-<element>-<state>-<ts>.json with origin.kind: "visual-fidelity-drift", the reconciliation artifact path in evidence, affected_screens populated, acceptance_criteria listing both "reconciliation for reaches verdict perfect at all viewports" AND any specific behavioral assertions implied by the drift, and suggested_team set per the decision-matrix case (out-of-scope → file-owning team; implementation-extras / spec-ambiguity → architect for user input; cascade-blast-radius → architect for cross-screen planning). The orchestrator picks up the SR and spawns the fix team automatically; the loop re-enters without manual triage.
5. Signal idle.

The hook value "fail" is the SAFETY NET, not the default workflow. The default workflow is: drift found → fix → re-run → "pass". If you find yourself reaching for "fail", you have either (a) hit one of the four escalation cases above and the handoff is the right action, or (b) you're avoiding a fix that you should be making. Choose carefully.

Allowed verdict values for visual_fidelity_review in review-gate evidence:

• "pass" — reconciliation ran, every tuple is perfect (after all fix-and-re-run iterations). Required when frontend was touched AND DESIGN_MAP.md exists. THIS IS THE STEADY STATE.
• "n/a" — either no frontend was touched OR DESIGN_MAP.md does not exist for this codebase. MUST also include visual_fidelity_review_note with a one-sentence justification of which branch applies.
• "fail" — reconciliation ran, at least one tuple was drift or gap AND the discipline could not converge to pass autonomously (one of the four escalation cases applies). The hook BLOCKS this value — the teammate has escalated and is waiting for the architect-routed clarification, after which they re-run reconciliation and only mark complete when verdict is "pass".

Phase F — Independent verification by the visual-verification-team

A reconciliation report is a self-report — and self-reported visual QA fails in one specific, recurring way: the agent reads the code, reasons about the styles, writes "perfect," and never renders the running app. So this report does not stand on its own.

After reconciliation completes (Phase 5 integration, or an on-demand /architect-team:visual-qa audit), the orchestrator runs the visual-verification-team — a three-role team that does NOT trust this report: visual-capture agents start the live app and capture screenshots + computed-style data for every DESIGN_MAP screen (countable artifacts); visual-analyzer agents run the objective data diff + pixel diff + code cross-check; the system-architect synthesizes the gaps holistically. A screen this report claimed perfect that the team finds drifted, or a screen this report never covered, is caught — the analysis is data, not an impression, and the synthesis confirms screens_captured == screens_analyzed == design_map_screen_count. The team's consolidated verdict — not this report — is what gates the run. visual_fidelity_review is not truly pass until the team returns overall: pass.

The practical consequence: producing a thorough, honest reconciliation here is not optional diligence. The verification team WILL render the live app for every screen and WILL catch a cut step. The only path to a real pass is to have actually done the comparison — every screen, every state, against the live app.

Hard rules — non-negotiable

• Phase 0 + Phase C are not skippable. No verdict exists without a live render of the running app. Static analysis, design mockups, and Storybook-in-isolation are NOT substitutes for the live render. If the app cannot be made to run, escalate blocked — never quietly fall back to code-reading.
• No cutting steps, no apologies. Every (screen, element, state, viewport) tuple in the declared scope gets a live render and a verdict. If you find yourself about to apologize for skipping a screen or a state — STOP and do not skip it. The tuple you are tempted to cut is the one most likely to be drifted. An apology after the fact ships the drift anyway; it is worthless. There is no partial pass.
• Zero-tolerance defaults. No silent slop. Per-element tolerance overrides go in DESIGN_MAP.md with a written rationale, not in test code.
• Exhaustive states. Every state listed or implied must be reconciled. A spec that only covers default while the component has hover / focus / disabled is itself a gap (escalate to update DESIGN_MAP first, then re-reconcile).
• Exhaustive viewports. Reconciliation runs at every viewport declared in DESIGN_MAP.md's viewports_responsive frontmatter. Different viewport → different verdict.
• Code-first BEFORE runtime. Skipping the static analysis means missing the cases where Playwright happens to pass but the underlying code is wrong (e.g., theme variable was changed and so was the test).
• Screenshots are mandatory evidence. Every tuple's evidence[] array includes at minimum one per-state element screenshot AND one per-viewport full-page screenshot. They go into the review-gate evidence as artifact paths.
• Fix to spec is the default. When the file is in scope and the spec is unambiguous, the agent CHANGES the implementation to match DESIGN_MAP, re-runs reconciliation, and verifies perfect. Alerting without fixing is a process failure.
• Escalation is for the narrow exceptions only. Out-of-scope files, implementation-has-extras-not-in-spec, spec-ambiguity, cross-screen cascade blast radius. Every escalation handoff names which case triggered it.
• Asset SHA-256 always verified at runtime. A src match without a hash match is incomplete — the served bytes are what the user actually sees.
• The spec is the contract, not a suggestion. DESIGN_MAP.md is what was agreed. Implementation drift is a code defect; the fix is code, not negotiation. If the spec is wrong, fix the spec via design-fidelity-mapping FIRST (with user / architect-team input), then re-reconcile against the corrected spec.
• Verify against the Oracle, never skip on a classification. A code-diff, a prior-run report, an intake / Phase −1B design-recon verdict, an "unchanged" label — none of these is a compliance verdict. Reconciliation establishes compliance ONLY by a fresh comparison to DESIGN_MAP. Never narrow the scope of a Phase 5 / on-demand run with any of them.
• Check the design baseline first. Phase A.0 — before scoping, determine whether the design Oracle itself moved. During a baseline migration EVERY screen is in scope, and an implementation that has not changed is drifted by definition (it was never migrated). "Unchanged" is a skip signal in steady state and a drift signal during a migration — reason about which you are in.

Anti-pattern rationalizations to reject

…(truncated)