@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/design-parity.mjs

@@ -0,0 +1,591 @@
+// design-parity — the FIDELITY gate: does the deliverable match the design
+// source it was derived from?
+//
+//   node design-parity.mjs scaffold --source <ref>:<path> --surface <name> --url <path>
+//        [--role <name>=<selector> ...]
+//        → emits a manifest skeleton carrying EVERY catalog row for every declared
+//          role, each `expected: TODO`. The catalog is doctrine-fixed, so the rows
+//          you would have forgotten are the ones already in the file.
+//   node design-parity.mjs validate <manifest> [--observed <results.json>] [--diff <base>] [--root <dir>]
+//        → blocks on: a TODO row, a rejected row with no real reason, a `from:`
+//          citation that does not resolve in the source blob, a catalog row missing
+//          for a declared role, and — with --observed — any measured divergence.
+//          `--diff <base>` adds the re-baseline-to-green check: an `expected` value
+//          rewritten to match the page under an unmoved source is a blocker.
+//   node design-parity.mjs probe <manifest> --viewport <px>
+//        → prints the JS to evaluate in the page; its output IS the results file.
+//          Keeps this skill agent-agnostic: e2e-test, agent-browser or a raw
+//          Playwright call can drive it, none of them owns it.
+//
+// ---------------------------------------------------------------------------
+// Why this is not a differ.
+//
+// The obvious tool here diffs the design source against the implementation. It
+// only works when both are the same stack — and the incident that produced this
+// script (fmm-express #521) is the case where they happened to be: a React+Tailwind
+// prototype and a React+Tailwind page, so a class-token diff looked general when it
+// was overfit. Point that differ at an HTML prototype, a v0 export or a Figma frame
+// and it returns noise. Comparing ACROSS technologies is judgment and does not
+// mechanize.
+//
+// So the work splits at that line. A human reads both, rendered, once, and writes
+// down the load-bearing properties in units that survive a stack change — computed
+// pixels, not `sm:text-3xl`. That manifest is the interchange format, and it is the
+// only step that needs eyes. Everything after it — is the manifest complete, do its
+// citations resolve, does the built page still measure that way — is mechanical and
+// runs every round.
+//
+// Why FIDELITY and not drift. `presentation:visual` pins a page against a baseline
+// captured FROM THE IMPLEMENTATION, so a baseline shot of the wrong page is green
+// forever — in #521 it would have locked in the card plane and the flattened type
+// scale and reported success. Here every `expected` is read off the SOURCE. That
+// one difference is the whole point of the file.
+//
+// Named incident (fmm-express #521, 2026-08-06): a settled prototype was cited by
+// exact path in the issue, summarized ONCE into four prose bullets, and every
+// downstream artifact descended from the summary. What the summary dropped — page
+// measure, card plane, the Amount input's responsive type steps, Description's
+// scale — could never be found again, because nothing re-read the source and
+// nothing rendered it (one image in a 3,040-message session, and the user pasted
+// it). The criteria doc then listed "visual screenshot baselines" under Non-goals,
+// so a fully green suite shipped a page that took four user corrections to fix.
+// The manifest is that same act of summarizing, with an assertable output: "6px"
+// either holds or it does not, where "the tip sits tight under Amount" was true of
+// the broken page too.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- The catalog (doctrine-fixed; you do not pick these per-unit) -----------
+//
+// These are the properties that carry a design across a re-implementation, chosen
+// because each one is a thing #521 actually lost. A unit may REJECT a row with a
+// written reason; it may not quietly omit one. Adding rows is free; the catalog is
+// raise-only, mirroring the Surface Baseline Contract.
+export const PARITY_CATALOG = [
+  {
+    id: 'container.measure', group: 'Container', role: 'container', css: ['max-width'],
+    why: 'the measure the page is laid out to — the first thing lost in a port, and invisible to every functional assertion (shipped max-w-md against a max-w-2xl source)',
+  },
+  {
+    id: 'container.plane', group: 'Container', role: 'container',
+    css: ['background-color', 'border-top-width', 'box-shadow'],
+    why: 'card vs flat is one decision read through three properties; pinning only one lets a plane come back through the other two',
+  },
+  {
+    id: 'container.padding', group: 'Container', role: 'container', css: ['padding-top', 'padding-left'],
+    why: 'a card that lost its border keeps its inset and still reads as a card',
+  },
+  {
+    id: 'primary.scale', group: 'Hierarchy', role: 'primary', css: ['font-size'], perViewport: true,
+    why: 'the primary control carries the page. Per-viewport because a responsive step-up is exactly what a hand-port drops silently (source stepped 24px→30px; shipped held 24px)',
+  },
+  {
+    id: 'primary.box', group: 'Hierarchy', role: 'primary', css: ['padding-top', 'border-radius'],
+    why: 'type scale alone does not make a control primary — its box has to grow with it',
+  },
+  {
+    id: 'secondary.scale', group: 'Hierarchy', role: 'secondary', css: ['font-size'], perViewport: true,
+    why: 'a secondary field inheriting the shared input class reads at primary weight; that is the defect, and only a number catches it',
+  },
+  {
+    id: 'secondary.box', group: 'Hierarchy', role: 'secondary', css: ['padding-top', 'border-radius'],
+    why: 'same shape as primary.box, from the other end',
+  },
+  {
+    id: 'rhythm.coupled', group: 'Rhythm', role: 'coupled', css: ['margin-top'],
+    why: 'a tight gap says "this modifies that", a loose one says "next section" — the prose form ("sits tight under Amount") was true of the broken page too',
+  },
+  {
+    id: 'hierarchy.order', group: 'Hierarchy', relation: 'primary.font-size > secondary.font-size',
+    why: 'the one row that survives both a stack change and a token change: whatever the numbers become, primary must out-scale secondary',
+  },
+]
+
+export const ROLES = ['container', 'primary', 'secondary', 'coupled']
+
+// The presentation floor viewports (ensure-coverage → presentation/axis.md).
+export const FLOOR_VIEWPORTS = [375, 1280]
+
+// A reason has to be a reason. "n/a", "-", "none" are the ritual forms this exists
+// to refuse — they are how a gated exclusion decays back into a silent omission.
+const EMPTY_REASON = /^\s*(n\/?a|none|-+|todo|tbd|\.)?\s*$/i
+
+export function isRealReason(s) {
+  const t = String(s ?? '').trim()
+  return t.length >= 12 && !EMPTY_REASON.test(t)
+}
+
+// ---- Manifest expansion ----------------------------------------------------
+
+// Catalog × declared roles × viewports → the row set a complete manifest must
+// carry. `validate` re-derives this rather than trusting the file: a manifest is
+// hand-edited, and the edit that deletes an inconvenient row is the one to catch.
+export function expectedRows(elements = {}, viewports = FLOOR_VIEWPORTS) {
+  const out = []
+  for (const entry of PARITY_CATALOG) {
+    if (entry.relation) {
+      // A relation is owed only when both of its operands are declared — otherwise
+      // it is a row nothing can ever measure, which trains readers to ignore rows.
+      const roles = entry.relation.split(/\s*(?:>=|<=|==|>|<)\s*/).map((s) => s.trim().split('.')[0])
+      if (roles.every((role) => elements[role])) out.push({ id: entry.id, relation: entry.relation })
+      continue
+    }
+    if (!elements[entry.role]) continue // role not declared → its rows are not owed
+    for (const css of entry.css) {
+      if (entry.perViewport) for (const v of viewports) out.push({ id: entry.id, role: entry.role, css, viewport: v })
+      else out.push({ id: entry.id, role: entry.role, css })
+    }
+  }
+  return out
+}
+
+export function rowKey(r) {
+  return r.relation
+    ? `${r.id}|relation`
+    : `${r.id}|${r.role}|${r.css}|${r.viewport ?? '*'}`
+}
+
+// ---- Parsing ---------------------------------------------------------------
+//
+// .json is the zero-dep path (and what the tests use); .yml needs js-yaml, which
+// scripts/ already carries for the ledger. Same split, same reason: a gate that
+// cannot run without an install is a gate that gets skipped.
+export async function parseText(raw, nameHint = '') {
+  if (/\.json$/i.test(nameHint)) return JSON.parse(raw)
+  let yaml
+  try { ({ default: yaml } = await import('js-yaml')) }
+  catch { throw new Error(`Reading ${nameHint || 'the manifest'} needs YAML support. Run \`npm install js-yaml\` in scripts/, or write the manifest as .json.`) }
+  return yaml.load(raw)
+}
+
+export async function loadManifest(file) {
+  return parseText(fs.readFileSync(file, 'utf8'), file)
+}
+
+// ---- Validation ------------------------------------------------------------
+
+// `sourceResolver` mirrors coverage-checklist's `fileResolver`: it answers "does
+// this citation point at something real", and when git cannot answer it says so
+// rather than inventing a verdict. Every wrong block here costs a round the gate
+// exists to save, so an unanswerable check downgrades to a warning.
+export function sourceResolver(root, source) {
+  if (!source?.path) return null
+  const ref = source.sha || source.ref
+  if (!ref) return null
+  const cache = new Map()
+  return (citedPath, line) => {
+    // A citation may name the source file bare or with its full repo path.
+    const target = citedPath.endsWith(source.path) || source.path.endsWith(citedPath) ? source.path : citedPath
+    if (!cache.has(target)) {
+      try {
+        const blob = execFileSync('git', ['show', `${ref}:${target}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+        cache.set(target, blob.split('\n').length)
+      } catch { cache.set(target, null) }
+    }
+    const lines = cache.get(target)
+    if (lines === null) return { ok: false, why: `no \`${target}\` in ${ref}` }
+    if (line != null && line > lines) return { ok: false, why: `${target} in ${ref} has ${lines} lines, cited :${line}` }
+    return { ok: true }
+  }
+}
+
+const CITATION_RE = /^([\w.][\w./-]*\.\w{1,12}):(\d+)$/
+
+export function validateManifest(manifest, opts = {}) {
+  const violations = []
+  const warnings = []
+  const push = (row, problem) => violations.push({ row, problem })
+
+  const elements = manifest?.elements || {}
+  const viewports = manifest?.viewports?.length ? manifest.viewports : FLOOR_VIEWPORTS
+  const rows = manifest?.rows || []
+
+  // 0 — the manifest has to say what it was read off. A parity manifest with no
+  // resolvable source is a baseline wearing a fidelity label.
+  if (!manifest?.source?.path) push('source', 'no `source.path` — a parity manifest must name the design source it was read off')
+  if (!manifest?.source?.sha && !manifest?.source?.ref) push('source', 'no `source.sha` / `source.ref` — pin the design source at a commit; a moving ref is not a source')
+  if (!Object.keys(elements).length) push('elements', 'no `elements` — declare at least one role → selector')
+  for (const role of Object.keys(elements)) {
+    if (!ROLES.includes(role)) warnings.push({ row: `elements.${role}`, problem: `unknown role (catalog roles: ${ROLES.join(', ')}) — its rows are not derived, so nothing checks it` })
+  }
+
+  // 1 — completeness. The anti-omission device: a manifest missing a catalog row
+  // for a role it declared is the #521 failure in miniature (the container plane
+  // was never on anyone's list, so nobody ever decided against it).
+  const present = new Map(rows.map((r) => [rowKey(r), r]))
+  for (const owed of expectedRows(elements, viewports)) {
+    if (!present.has(rowKey(owed))) {
+      const entry = PARITY_CATALOG.find((c) => c.id === owed.id)
+      push(owed.id, `missing row ${rowKey(owed)} — ${entry?.why || 'in the catalog'}. Pin it or reject it with a reason; omission is not a decision`)
+    }
+  }
+
+  // 2 — every row is decided, and decided against something checkable.
+  const resolve = opts.resolveSource
+  for (const r of rows) {
+    const label = rowKey(r)
+    const rejected = r.reject !== undefined && r.reject !== null
+    if (rejected) {
+      if (!isRealReason(r.reject)) push(label, `rejected with no real reason (\`reject: ${String(r.reject).trim() || '<empty>'}\`) — a gated exclusion needs an argument a reader can disagree with`)
+      continue
+    }
+    if (r.expected === undefined || r.expected === null || /^\s*todo\s*$/i.test(String(r.expected))) {
+      if (!r.relation) { push(label, 'expected is TODO — read the value off the rendered source, or reject the row'); continue }
+    }
+    if (!r.from) { push(label, 'no `from:` citation — every expected value names the line of the source it was read off'); continue }
+    const m = CITATION_RE.exec(String(r.from).trim())
+    if (!m) { push(label, `\`from: ${r.from}\` is not a \`<path>:<line>\` citation`); continue }
+    if (resolve) {
+      const res = resolve(m[1], Number(m[2]))
+      if (!res.ok) push(label, `\`from: ${r.from}\` does not resolve — ${res.why}`)
+    } else {
+      warnings.push({ row: label, problem: 'citation not resolved (no git context) — shape checked only' })
+    }
+  }
+
+  violations.warnings = warnings
+  return violations
+}
+
+// ---- Observed comparison ---------------------------------------------------
+
+const LENGTH_RE = /^(-?\d+(?:\.\d+)?)px$/
+const TOLERANCE_PX = 0.5 // sub-pixel layout is normal; 0.5px is not a design decision
+
+export function normalize(value) {
+  const s = String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ')
+  const m = LENGTH_RE.exec(s)
+  return m ? { num: Number(m[1]) } : { str: s }
+}
+
+export function valuesAgree(expected, observed) {
+  const e = normalize(expected)
+  const o = normalize(observed)
+  if (e.num !== undefined && o.num !== undefined) return Math.abs(e.num - o.num) <= TOLERANCE_PX
+  // A bare number in `expected` is a courtesy: "24" means 24px.
+  if (e.num === undefined && o.num !== undefined && /^-?\d+(\.\d+)?$/.test(e.str)) return Math.abs(Number(e.str) - o.num) <= TOLERANCE_PX
+  return e.str === o.str
+}
+
+function observedIndex(observed) {
+  const idx = new Map()
+  for (const run of observed?.runs || []) {
+    for (const mm of run.measurements || []) idx.set(`${mm.role}|${mm.css}|${run.viewport}`, mm)
+  }
+  return idx
+}
+
+function lookup(idx, role, css, viewport, viewports) {
+  if (viewport != null) return idx.get(`${role}|${css}|${viewport}`)
+  // A viewport-independent row is satisfied by any floor viewport that measured it,
+  // but it must AGREE across the ones that did — a property that is 0 at 375 and 24
+  // at 1280 is a responsive decision hiding in a row that claims not to be one.
+  const hits = viewports.map((v) => idx.get(`${role}|${css}|${v}`)).filter(Boolean)
+  if (!hits.length) return undefined
+  return hits.every((h) => valuesAgree(hits[0].value, h.value)) ? hits[0] : { ...hits[0], disagrees: hits }
+}
+
+export function compareObserved(manifest, observed) {
+  const mismatches = []
+  const viewports = manifest?.viewports?.length ? manifest.viewports : FLOOR_VIEWPORTS
+  const idx = observedIndex(observed)
+
+  for (const r of manifest?.rows || []) {
+    if (r.reject !== undefined && r.reject !== null) continue
+    const label = rowKey(r)
+
+    if (r.relation) {
+      const parsed = /^\s*(\w+)\.([\w-]+)\s*(>|>=|<|<=|==)\s*(\w+)\.([\w-]+)\s*$/.exec(r.relation)
+      if (!parsed) { mismatches.push({ row: label, problem: `relation \`${r.relation}\` is not \`<role>.<css> <op> <role>.<css>\`` }); continue }
+      const [, lRole, lCss, op, rRole, rCss] = parsed
+      const l = lookup(idx, lRole, lCss, null, viewports)
+      const rr = lookup(idx, rRole, rCss, null, viewports)
+      if (!l || !rr) { mismatches.push({ row: label, problem: `not measured (${!l ? `${lRole}.${lCss}` : `${rRole}.${rCss}`} missing from the results)` }); continue }
+      const a = normalize(l.value).num
+      const b = normalize(rr.value).num
+      if (a === undefined || b === undefined) { mismatches.push({ row: label, problem: `relation needs two lengths, got ${l.value} and ${rr.value}` }); continue }
+      const ok = op === '>' ? a > b : op === '>=' ? a >= b : op === '<' ? a < b : op === '<=' ? a <= b : a === b
+      if (!ok) mismatches.push({ row: label, problem: `${lRole}.${lCss}=${l.value} is not ${op} ${rRole}.${rCss}=${rr.value}` })
+      continue
+    }
+
+    const hit = lookup(idx, r.role, r.css, r.viewport, viewports)
+    if (!hit) { mismatches.push({ row: label, problem: 'not measured — the results file has no value for this row (element missing, or the probe did not run at this viewport)' }); continue }
+    if (hit.value === null || hit.value === undefined) { mismatches.push({ row: label, problem: `element not found on the page (\`${manifest.elements?.[r.role] || r.role}\`)` }); continue }
+    if (hit.disagrees) { mismatches.push({ row: label, problem: `pinned as viewport-independent but measures ${hit.disagrees.map((h) => `${h.value}@?`).join(' / ')} across viewports — split it per viewport` }); continue }
+    if (!valuesAgree(r.expected, hit.value)) {
+      mismatches.push({ row: label, problem: `expected ${r.expected}, page has ${hit.value}${r.from ? ` (source: ${r.from})` : ''}` })
+    }
+  }
+  return mismatches
+}
+
+// ---- Expectation rewrites (the re-baseline-to-green analogue) ---------------
+//
+// The cheapest way to make this gate pass is to stop fixing the page and edit the
+// manifest instead: change `expected: 672px` to `448px` and the divergence is gone.
+// That is the same move as a bare `--update-snapshots`, which `review-pr` already
+// blocks for `presentation:visual` — except here it is easier, because it is one
+// character in a YAML file rather than a regenerated PNG, and it leaves no image in
+// the diff for a reviewer to notice.
+//
+// It is also mechanically detectable, because of the one property that makes this
+// fidelity and not drift: the source is pinned at a commit and is therefore
+// IMMUTABLE. If `source.sha` has not moved and a row's `from:` line has not moved,
+// then the value read off that line cannot have changed. A changed `expected` under
+// those conditions is one of exactly two things — a mis-read being corrected (fine,
+// and worth saying out loud) or a capitulation to the page (the thing to stop).
+//
+// So the rewrite is not forbidden; it is made to announce itself. `rebase: <reason>`
+// on the row clears it, which is the same shape as the declared-intended-UI-change
+// rule the visual baseline already uses. When the source itself moved, expectations
+// are expected to change and this warns instead of blocking.
+export function detectExpectationRewrites(prev, next) {
+  const out = []
+  if (!prev || !next) return out
+  const sourceMoved = (prev.source?.sha || prev.source?.ref) !== (next.source?.sha || next.source?.ref)
+  const before = new Map((prev.rows || []).map((r) => [rowKey(r), r]))
+
+  for (const r of next.rows || []) {
+    const was = before.get(rowKey(r))
+    if (!was) continue                                   // new row: nothing was rewritten
+    if (was.expected === undefined || r.expected === undefined) continue
+    if (String(was.expected) === String(r.expected)) continue
+
+    const citationMoved = String(was.from ?? '') !== String(r.from ?? '')
+    const declared = isRealReason(r.rebase)
+    if (declared) continue
+
+    if (sourceMoved) {
+      out.push({ row: rowKey(r), level: 'warn', problem: `expected ${was.expected} → ${r.expected} and the design source moved (${prev.source?.sha} → ${next.source?.sha}) — plausible, but say so with \`rebase:\` so the reviewer is not re-deriving it` })
+    } else if (citationMoved) {
+      out.push({ row: rowKey(r), level: 'warn', problem: `expected ${was.expected} → ${r.expected} with a new citation (${was.from} → ${r.from}) — re-read from a different line; \`rebase:\` it if that was the correction` })
+    } else {
+      out.push({ row: rowKey(r), level: 'block', problem: `expected ${was.expected} → ${r.expected} with the SAME source (${next.source?.sha}) and the SAME citation (${r.from}). The source is pinned and cannot have changed, so this moves the target to the page instead of the page to the target. Fix the page, or state the mis-read with \`rebase: <reason>\`` })
+    }
+  }
+  return out
+}
+
+// ---- Probe -----------------------------------------------------------------
+//
+// Emitted rather than executed: e2e-test owns browser runners, this skill owns
+// what must be proven. The snippet is deliberately dependency-free so it pastes
+// into Playwright's `page.evaluate`, agent-browser, or a devtools console alike.
+export function probeScript(manifest, viewport) {
+  const wanted = []
+  const seen = new Set()
+  const viewports = manifest?.viewports?.length ? manifest.viewports : FLOOR_VIEWPORTS
+  for (const owed of expectedRows(manifest?.elements || {}, viewports)) {
+    if (owed.relation) continue
+    const k = `${owed.role}|${owed.css}`
+    if (seen.has(k)) continue
+    seen.add(k)
+    wanted.push({ role: owed.role, css: owed.css, selector: manifest.elements[owed.role] })
+  }
+  // Relational rows need their operands measured even when no plain row asks for them.
+  for (const entry of PARITY_CATALOG) {
+    if (!entry.relation) continue
+    for (const side of entry.relation.split(/\s*(?:>=|<=|==|>|<)\s*/)) {
+      const [role, css] = side.trim().split('.')
+      if (!manifest?.elements?.[role] || seen.has(`${role}|${css}`)) continue
+      seen.add(`${role}|${css}`)
+      wanted.push({ role, css, selector: manifest.elements[role] })
+    }
+  }
+  return `(() => {
+  const want = ${JSON.stringify(wanted, null, 2).replace(/\n/g, '\n  ')};
+  return {
+    surface: ${JSON.stringify(manifest?.surface || null)},
+    runs: [{
+      viewport: ${Number(viewport)},
+      measurements: want.map((w) => {
+        const el = document.querySelector(w.selector);
+        return { role: w.role, css: w.css, value: el ? getComputedStyle(el)[w.css] : null };
+      }),
+    }],
+  };
+})()`
+}
+
+// ---- Scaffold --------------------------------------------------------------
+//
+// Rendered as a string rather than dumped from js-yaml, so each group carries the
+// catalog's `why` into the file. The reason a row exists is the thing that stops it
+// being deleted when it is inconvenient.
+export function scaffoldManifest({ source, surface, url, elements = {}, viewports = FLOOR_VIEWPORTS }) {
+  const L = []
+  L.push(`# design-parity manifest — ${surface || '<surface>'}`)
+  L.push('#')
+  L.push('# FIDELITY, not drift: every `expected` below is read off the DESIGN SOURCE,')
+  L.push('# with it rendered in front of you — never off the implementation. A value')
+  L.push('# copied from the page you built is green forever, whatever it looks like.')
+  L.push('#')
+  L.push('# Fill `expected` in computed units (px), or `reject:` the row with a reason.')
+  L.push('# Omitting a row is not a decision and `validate` blocks on it.')
+  L.push('')
+  L.push('source:')
+  L.push(`  ref: ${source?.ref || '<branch-or-tag>'}`)
+  L.push(`  sha: ${source?.sha || '<commit-sha>'}`)
+  L.push(`  path: ${source?.path || '<path/in/that/ref>'}`)
+  L.push(`  kind: ${source?.kind || 'react'}   # react | html | figma | image`)
+  L.push(`surface: ${surface || '<surface-id>'}`)
+  L.push(`url: ${url || '<route>'}`)
+  L.push(`viewports: [${viewports.join(', ')}]`)
+  L.push('')
+  L.push('elements:')
+  for (const role of ROLES) {
+    const sel = elements[role]
+    L.push(sel ? `  ${role}: '${sel}'` : `  # ${role}: '<selector>'   # undeclared → its catalog rows are not owed`)
+  }
+  L.push('')
+  L.push('rows:')
+  const all = expectedRows(elements, viewports)
+  let group = null
+  for (const entry of PARITY_CATALOG) {
+    const owed = all.filter((r) => r.id === entry.id)
+    if (!owed.length) continue
+    if (entry.group !== group) { group = entry.group; L.push(`  # ── ${group} ──`) }
+    L.push(`  # ${entry.why}`)
+    for (const r of owed) {
+      L.push(`  - id: ${r.id}`)
+      if (r.relation) {
+        // The relation IS the expectation — there is no value to fill in, only a
+        // line to cite. Emitting `expected: TODO` here would teach the reader that
+        // TODO is sometimes fine to leave.
+        L.push(`    relation: '${r.relation}'`)
+      } else {
+        L.push(`    role: ${r.role}`)
+        L.push(`    css: ${r.css}`)
+        if (r.viewport != null) L.push(`    viewport: ${r.viewport}`)
+        L.push('    expected: TODO')
+      }
+      L.push(`    from: TODO   # ${source?.path || '<source>'}:<line>`)
+    }
+  }
+  L.push('')
+  return L.join('\n')
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+function repoRoot(explicit) {
+  if (explicit) return explicit
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim() }
+  catch { return process.cwd() }
+}
+
+function flag(argv, name) { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2)
+
+  if (cmd === 'scaffold') {
+    const src = flag(rest, '--source') || ''
+    const ci = src.lastIndexOf(':')
+    const ref = ci > 0 ? src.slice(0, ci) : ''
+    const p = ci > 0 ? src.slice(ci + 1) : ''
+    if (!ref || !p) { console.error('usage: design-parity.mjs scaffold --source <ref>:<path> --surface <name> --url <route> [--role primary=<selector> ...]'); process.exit(2) }
+    // If the ref will not resolve here (a prototype branch in another repo, a ref
+    // not fetched yet), leave the placeholder rather than copying the ref into
+    // `sha:`. A moving ref sitting in the pinned field looks pinned and is not —
+    // and the whole manifest rests on the source being a fixed commit.
+    let sha = null
+    try { sha = execFileSync('git', ['rev-parse', '--short', ref], { cwd: repoRoot(flag(rest, '--root')), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { /* leave it unresolved */ }
+    if (!sha) console.error(`design-parity: could not resolve \`${ref}\` here — leaving \`sha:\` unfilled. Pin it before validating (\`git rev-parse --short ${ref}\`).`)
+    const elements = {}
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] !== '--role') continue
+      const [role, ...sel] = String(rest[i + 1] || '').split('=')
+      if (role && sel.length) elements[role] = sel.join('=')
+    }
+    console.log(scaffoldManifest({
+      source: { ref, sha, path: p, kind: flag(rest, '--kind') || 'react' },
+      surface: flag(rest, '--surface'),
+      url: flag(rest, '--url'),
+      elements,
+    }))
+    process.exit(0)
+  }
+
+  if (cmd === 'validate') {
+    const file = rest.find((a) => !a.startsWith('--'))
+    if (!file || !fs.existsSync(file)) { console.error('usage: design-parity.mjs validate <manifest.yml|.json> [--observed <results.json>] [--root <dir>]'); process.exit(2) }
+    const root = repoRoot(flag(rest, '--root'))
+    const manifest = await loadManifest(file)
+    const observedFile = flag(rest, '--observed')
+
+    const violations = validateManifest(manifest, { resolveSource: sourceResolver(root, manifest?.source) })
+    for (const w of violations.warnings) console.log(`  ! ${w.row}: ${w.problem}`)
+
+    // Rewrite check: needs the manifest as it stood at the merge base. Silent when
+    // no --diff is given (the reduced form already says the run is partial), and
+    // never fatal on a git failure — a manifest added by this PR has no previous
+    // version, which is not a problem to report.
+    let rewrites = []
+    const base = flag(rest, '--diff')
+    if (base) {
+      // Both sides through realpath before differencing. `process.cwd()` returns a
+      // resolved path while an explicit --root is taken verbatim, so on any host
+      // where the tree sits behind a symlink (macOS `/var`→`/private/var`, and this
+      // skill family's own symlink-farm install) the naive relative path escapes the
+      // repo as `../../..` and `git show` silently finds nothing — which reads as
+      // "no previous version", i.e. the check passes exactly where it should fire.
+      const real = (p) => { try { return fs.realpathSync(p) } catch { return path.resolve(p) } }
+      const rel = path.relative(real(root), real(file))
+      try {
+        const prevRaw = execFileSync('git', ['show', `${base}:${rel}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+        rewrites = detectExpectationRewrites(await parseText(prevRaw, file), manifest)
+      } catch { /* new manifest at this base — nothing to compare */ }
+      for (const w of rewrites.filter((x) => x.level === 'warn')) console.log(`  ! ${w.row}: ${w.problem}`)
+    }
+    const blockingRewrites = rewrites.filter((x) => x.level === 'block')
+
+    let mismatches = []
+    if (observedFile) {
+      if (!fs.existsSync(observedFile)) { console.error(`design-parity: --observed ${observedFile} does not exist`); process.exit(2) }
+      mismatches = compareObserved(manifest, JSON.parse(fs.readFileSync(observedFile, 'utf8')))
+    } else {
+      // Same failure shape coverage-checklist hit: two runs of one command, opposite
+      // verdicts, and no way to tell from the output which question was asked. Without
+      // --observed this checks that the manifest is COMPLETE, never that the page
+      // conforms — and the pass is the misleading one, so it announces itself.
+      console.error('design-parity: NOTE — no --observed: this is the reduced form. It checks the manifest is complete and its citations resolve; it does NOT check the page. A green run here is not the green the reviewer will get.')
+    }
+
+    if (!violations.length && !mismatches.length && !blockingRewrites.length) {
+      const scope = observedFile ? `${(manifest.rows || []).length} row(s) hold against the rendered page` : `${(manifest.rows || []).length} row(s) decided and cited — manifest only, page unchecked`
+      console.log(`design-parity: ✓ ${scope}${violations.warnings.length ? ` (${violations.warnings.length} warning(s) above)` : ''}`)
+      process.exit(0)
+    }
+    if (violations.length) {
+      console.log(`design-parity: ✗ ${violations.length} manifest problem(s):\n`)
+      for (const v of violations) console.log(`  • ${v.row}: ${v.problem}`)
+    }
+    if (blockingRewrites.length) {
+      console.log(`\ndesign-parity: ✗ ${blockingRewrites.length} expectation(s) rewritten to match the page:\n`)
+      for (const w of blockingRewrites) console.log(`  • ${w.row}: ${w.problem}`)
+    }
+    if (mismatches.length) {
+      console.log(`\ndesign-parity: ✗ ${mismatches.length} divergence(s) from the design source:\n`)
+      for (const m of mismatches) console.log(`  • ${m.row}: ${m.problem}`)
+    }
+    process.exit(1)
+  }
+
+  if (cmd === 'probe') {
+    const file = rest.find((a) => !a.startsWith('--'))
+    const vp = flag(rest, '--viewport')
+    if (!file || !fs.existsSync(file) || !vp) { console.error('usage: design-parity.mjs probe <manifest.yml|.json> --viewport <px>'); process.exit(2) }
+    console.log(probeScript(await loadManifest(file), vp))
+    process.exit(0)
+  }
+
+  console.error('usage: design-parity.mjs <scaffold|validate|probe>')
+  process.exit(2)
+}
+
+if (isMainModule(import.meta.url)) await main()