create-pmos 0.46.0 → 0.48.0

package/workspace/bin/live-notes.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/* live-notes — Run 1 of jev-live-notes: place the talking points of a conversation against a repository's open
+ * initiatives, as proposals. No page, no microphone, no audio, no network call.
+ *
+ *   node bin/live-notes.js run --repo <dir> [--segments <file>|-] [--answers <file>] [--session <id>] [--anchor <a>] [--json]
+ *   node bin/live-notes.js decide --repo <dir> --session <id> --segment <id> --action accept|change|reject [--initiative <id>] [--relation <word>]
+ *   node bin/live-notes.js close --repo <dir> --session <id>
+ *   node bin/live-notes.js ingest --repo <dir> --transcript <file> --source <name> --session <id>   a transcript, only what is new (Run 4)
+ *   node bin/live-notes.js list  --repo <dir> --session <id> [--json]       the ranked list (Run 2)
+ *   node bin/live-notes.js rate  --repo <dir> --session <id>
+ *   node bin/live-notes.js plan  --repo <dir> --session <id> [--json]       what an agent should write, on which tier (Run 3)
+ *   node bin/live-notes.js context --repo <dir> --session <id> --answers <file>   LIVECONTEXT and LIVECANDIDATE lines (Run 3)
+ *   node bin/live-notes.js switch --repo <dir> on|off [--retention-days <n>]
+ *
+ * Segments are one per line: plain text, or a JSON object {"text","at","speaker","source","private"}.
+ * Without `--answers`, each point is left `pending` and the prompt for an agent session is printed; the agent's
+ * `LIVENOTE {json}` lines go back in with `--answers`. When all three gates hold (a key, consent for the repository,
+ * and `switch on`), the prompt asks that agent session to make the two choices with the Typesafe skill (Run 5). This
+ * command sends nothing itself and injects no sender. The key is never read, only whether one exists.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const live = require('../lib/live-notes');
+const settings = require('../lib/typesafe-settings');
+const { defaultRoot } = require('../lib/state-root');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const opt = (n, d = null) => { const i = argv.indexOf('--' + n); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const flag = (n) => argv.includes('--' + n);
+const die = (m, c = 2) => { console.error('live-notes: ' + m); process.exit(c); };
+
+if (!['run', 'decide', 'close', 'rate', 'switch', 'plan', 'context', 'ingest', 'list'].includes(cmd)) die('commands: run, ingest, list, decide, close, rate, switch, plan, context (see the header of this file)');
+const root = path.resolve(opt('repo', process.cwd()));
+if (!fs.existsSync(root)) die('no such directory: ' + root);
+const runtimeDir = defaultRoot();
+const exclude = settings.getRepo(runtimeDir, root).exclude;
+const consent = settings.getRepo(runtimeDir, root).consent;
+const sw = live.getSwitch(runtimeDir, root);
+live.purgeExpired(runtimeDir);
+
+function session(id, extra = {}) {
+  return live.openSession({ root, runtimeDir, session: id, key: settings.status(runtimeDir, process.env).present ? 'present' : null,
+    flags: { consent, live: sw.live }, exclude, anchor: opt('anchor'), ask: null, ...extra });
+}
+
+(async () => {
+  try {
+    if (cmd === 'switch') {
+      const pos = argv.filter((x, i) => !x.startsWith('--') && !(argv[i - 1] || '').startsWith('--'));
+      const on = pos[1] === 'on' ? true : pos[1] === 'off' ? false : null;
+      if (on === null && !opt('retention-days')) die('say on or off, or --retention-days <n>');
+      const r = live.setSwitch(runtimeDir, root, { live: on === null ? undefined : on, retention_days: opt('retention-days') ? Number(opt('retention-days')) : undefined });
+      console.log(`live notes may use Jev: ${r.live ? 'on' : 'off'} · raw transcript kept ${r.retention_days ? r.retention_days + ' day(s) after close' : 'only until close'}`);
+      return;
+    }
+    const id = opt('session');
+    if (cmd === 'run' || cmd === 'ingest') {
+      const src = cmd === 'ingest' ? opt('transcript') : opt('segments');
+      if (cmd === 'ingest' && !src) die('--transcript <file> is required');
+      if (!src && !opt('answers')) die('give --segments <file>|- , --answers <file>, or both');
+      const probe = session(id);
+      const out = { session: probe.id, path: probe.path, gates_missing: probe.gates.missing, withheld: [], pending: [], error: null, rows: [], rejected: [] };
+      let prompt = null;
+      let s = probe;
+      if (src) {
+        const text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
+        const sourceName = opt('source') || (src === '-' ? 'stdin' : path.basename(src));
+        const raw = cmd === 'ingest' ? live.segmentsFromTranscript(text, { source: sourceName }) : text.split(/\r?\n/).filter((l) => l.trim()).map((l) => { if (l.trim().startsWith('{')) { try { return JSON.parse(l); } catch { /* plain */ } } return l; });
+        const r = await s.add(raw, { source: sourceName, dedupe: cmd === 'ingest' });
+        out.skipped_duplicates = r.skipped_duplicates;
+        Object.assign(out, { withheld: r.withheld, pending: r.pending, error: r.error || null, rows: r.rows });
+        prompt = r.prompt;
+      }
+      if (opt('answers')) {
+        const ans = live.parseAgentAnswers(fs.readFileSync(opt('answers'), 'utf8'), s.items.map((i) => i.id));
+        out.rejected = ans.rejected;
+        const r = s.answer(ans.answers);
+        out.rows = out.rows.concat(r.answered);
+        out.pending = out.pending.filter((x) => !r.answered.some((a) => a.segment === x));
+        if (r.unknown.length) out.unknown_segments = r.unknown;
+        if (r.answered.length) prompt = null;
+      }
+      if (flag('json')) { console.log(JSON.stringify({ ...out, prompt }, null, 2)); return; }
+      const why = out.path === 'jev-agent' ? 'the prompt asks your agent session to use the Typesafe skill; this command sends nothing itself' : live.gateSentence(out.gates_missing) || 'all gates are open';
+      console.log(`session ${out.session} · path: ${out.path} (${why})`);
+      if (out.error) console.log('stopped: ' + out.error);
+      if (out.skipped_duplicates) console.log(`skipped ${out.skipped_duplicates} point(s) already in this session`);
+      if (out.rejected.length) console.log(`rejected ${out.rejected.length} off-shape answer line(s): ${out.rejected.join(', ')}`);
+      for (const x of out.rows) console.log(`  ${x.segment}: ${x.status === 'proposed' ? `${x.relation} ${x.initiative} (${x.relation_band}) · ${x.confidence}${x.in_scope === false ? ' · outside scope' : ''}` : x.status}`);
+      for (const w of out.withheld) console.log(`  ${w.id}: withheld — ${w.reason}`);
+      if (prompt) console.log('\nGive this to an agent session, then pass its LIVENOTE lines back with --answers <file> --session ' + out.session + ':\n\n' + prompt);
+      return;
+    }
+    if (!id) die('--session <id> is required');
+    { const known = live.apiList({ root, session: id }); if (!known.ok) die(known.error, 1); }   // a command on a session that does not exist creates nothing
+    const s = session(id);
+    if (cmd === 'decide') { const row = s.decide({ segment: opt('segment'), action: opt('action'), initiative: opt('initiative'), relation: opt('relation') }); console.log(`recorded: ${row.action} ${row.segment}${row.overridden ? ' (override)' : ''}`); return; }
+    if (cmd === 'close') { const r = s.close({ retentionDays: sw.retention_days }); console.log(r.already ? 'already closed' : `closed · note: ${r.note} · raw transcript: ${r.transcript}`); return; }
+    if (cmd === 'list') {
+      const r = live.apiList({ root, session: id });
+      if (!r.ok) die(r.error, 1);
+      if (flag('json')) { console.log(JSON.stringify(r.ranked, null, 2)); return; }
+      const k = r.ranked;
+      console.log(`session ${id} · path: ${k.path}${k.closed ? ' · closed' : ''} · ${k.counts.points} point(s), ${k.counts.pending} not yet answered, ${k.withheld} withheld${k.paused ? ' · PAUSED: ' + k.paused.reason : ''}`);
+      for (const sec of k.sections) {
+        console.log(`\n${sec.title}`);
+        for (const x of sec.items) console.log(`  ${x.segment}: "${x.quote}"${x.initiative && x.initiative !== 'none' ? ` — ${x.relation} ${x.initiative} (${x.relation_band})` : ''}${x.in_scope === false ? ' · outside scope' : ''}${x.decision ? ' · PM: ' + x.decision.action : ''}${x.context ? ' · note: ' + x.context.note : ''}`);
+      }
+      if (k.candidates.length) { console.log('\nPossible new initiatives'); for (const c of k.candidates) console.log(`  ${c.candidate}: ${c.draft ? '"' + c.draft.title + '" (' + c.draft.lane + ')' : c.topic_terms.join(', ')} · ${c.segments.length} points · prior-rejection check found ${c.prior_rejection_found}`); }
+      return;
+    }
+    if (cmd === 'plan') {
+      const p = s.plan();
+      if (flag('json')) { console.log(JSON.stringify(p, null, 2)); return; }
+      console.log(`tagging: ${p.tagging_tier} tier · ${p.context.filter((x) => !x.done).length} context note(s) and ${p.candidates.filter((x) => !x.done).length} candidate draft(s) to write`);
+      for (const x of p.context) console.log(`  ${x.done ? '✓' : '·'} ${x.segment} [${x.tier}] ${x.reasons.join('; ')} — read ${x.read.join(', ')}`);
+      for (const x of p.candidates) console.log(`  ${x.done ? '✓' : '·'} ${x.candidate} [${x.tier}] ${x.topic_terms.join(', ')}`);
+      return;
+    }
+    if (cmd === 'context') {
+      if (!opt('answers')) die('--answers <file> is required');
+      const text = fs.readFileSync(opt('answers'), 'utf8');
+      const c = s.addContext(live.parseContext(text).entries);
+      const d = s.addDrafts(live.parseDrafts(text).entries);
+      console.log(`accepted ${c.accepted.length} context note(s) and ${d.accepted.length} candidate draft(s)`);
+      for (const r of c.rejected.concat(d.rejected)) console.log(`  rejected ${r.segment || r.candidate || '?'}: ${r.reason}`);
+      return;
+    }
+    if (cmd === 'rate') { console.log(JSON.stringify(live.overrideRate(s.ledger()), null, 2)); return; }
+  } catch (e) { die(e.message, 1); }
+})();

package/workspace/design-parity.js

@@ -25,7 +25,10 @@
  * design difference. Babel is not vendored because the prototype does not need it (verified: the
  * render is node-for-node identical without it).
  *
- *   node design-parity.js                  both themes, default state
+ *   node design-parity.js --board=WsA      the cockpit mockup's Option A board (planning/design/cockpit-mockup/), dark, 1600x900,
+ *                                          against `?fixture=cockpit`. This is `npm run test:parity` and the BLOCKING CI step.
+ *   node design-parity.js                  the four-panel prototype (the layout workspace-cockpit-nav replaced), both themes,
+ *                                          against `?fixture=proto`. `npm run test:parity:four-panel`; no longer in CI.
  *   node design-parity.js --theme=light    one theme
  *   node design-parity.js --states         also walk the interaction states (see STATES below)
  *   node design-parity.js --state=<id>     one named state
@@ -52,15 +55,19 @@ const os = require('os');
 
 const ROOT = path.resolve(__dirname, '..');
 const DESIGN = path.join(ROOT, 'planning', 'design', 'four-panel');
+const COCKPIT = path.join(ROOT, 'planning', 'design', 'cockpit-mockup');
 const FONTS = path.join(__dirname, 'public', 'vendor');
 const APP_URL = process.env.PMOS_PARITY_APP || 'http://127.0.0.1:7433';
 const REF_PORT = +(process.env.PMOS_PARITY_PORT || 8899);
 const OUT = process.env.PMOS_PARITY_OUT || path.join(os.tmpdir(), 'pmos-design-parity');
 
 const argv = process.argv.slice(2);
-const themes = argv.some((a) => a.startsWith('--theme=')) ? [argv.find((a) => a.startsWith('--theme=')).split('=')[1]] : ['dark', 'light'];
+/* `--board=<Name>` points the check at a board of the cockpit mockup instead of the four-panel prototype. The boards are static, drawn
+ * at 1600x900 in the dark theme only, so a board run is one theme, one state, at that size. */
+const BOARD = (argv.find((a) => a.startsWith('--board=')) || '').split('=')[1] || null;
+const themes = BOARD ? ['dark'] : argv.some((a) => a.startsWith('--theme=')) ? [argv.find((a) => a.startsWith('--theme=')).split('=')[1]] : ['dark', 'light'];
 const KEEP = argv.includes('--keep');
-const W = 1600, H = 1000;
+const W = 1600, H = BOARD ? 900 : 1000;
 
 /* THE CAPTURED INTERACTION STATES.
  *
@@ -85,7 +92,7 @@ const STATES = [
   { id: 'add-repository', steps: ['add repository'] },
 ];
 const stateArg = argv.find((a) => a.startsWith('--state='));
-const states = stateArg
+const states = BOARD ? STATES.filter((s) => s.id === 'default') : stateArg
   ? STATES.filter((s) => s.id === stateArg.split('=')[1])
   : (argv.includes('--states') ? STATES : STATES.filter((s) => s.id === 'default'));
 if (!states.length) {
@@ -101,12 +108,190 @@ const PROPS = [
   'lineHeight', 'letterSpacing', 'textTransform', 'writingMode', 'overflowX', 'overflowY',
 ];
 
+/* ── THE EXCLUSIONS: differences that are DECISIONS, named one by one ──────────────────────────────────────────────────────────
+ *
+ * A board run compares the app against a picture the PM drew before some later decisions were taken. Where the app differs from the
+ * picture BECAUSE OF A DECISION (a PRD requirement, a PM answer, a feature a later run added on purpose), the difference is listed
+ * here, by name, with the decision that makes it one. Nothing else is excluded, and no tolerance is loosened: the four axes, the 2px
+ * geometry bound and the 0.5% pixel bound are the same for every run.
+ *
+ * What an exclusion does, and only for the element or phrase it names:
+ *   text      the named element's text (or the named phrase) is left out of that page's word stream
+ *   style     the named element and everything inside it are not paired or measured
+ *   pixels    the named element's box, on the page where it is found, is painted identically on both screenshots before the diff
+ *
+ * A NARROW exclusion (`only`) leaves the element in every axis and skips just the listed comparisons on it — a list of computed-style
+ * properties, or `box` for its geometry. Its text is compared, the rest of its style is compared, and its pixels are diffed.
+ *
+ * Each side is located the way a person would point at it. The app side uses the app's own stable hooks (`sel`). The board has no
+ * hooks, so its side is anchored on visible text: `own` is the element whose own text is exactly that string, `up` climbs to an
+ * ancestor, `child` steps down to one of its children (an element with no text of its own, such as a dot), and `phrase` is a run of
+ * characters inside one text node. A side that is `null` means the element exists on the other
+ * page only.
+ *
+ * A STALE EXCLUSION FAILS THE RUN. If a named side matches nothing, the run fails and says which: an exclusion that no longer
+ * matches would otherwise be a silent hole that a future difference could hide in. Masked area is printed per exclusion, so how
+ * much of the screen is NOT compared is always on the report, never only in this file.
+ *
+ * No exclusion is a reworded label. A label the app says differently from the board is a defect and is fixed in the app.
+ */
+const EXCLUSIONS = {
+  WsA: [
+    {
+      name: 'terminal content',
+      why: 'The body of a terminal tab is the session\'s own output: the agent CLI and the cockpit mod draw it (the "Blocked" band and '
+        + 'the acceptance band are pmos-cockpit-mod M8 and M10), not the workspace. The workspace-cockpit-nav PRD puts "the terminal '
+        + 'mod and its boards" out of scope. The tab strip above it is compared.',
+      design: { own: 'accepted. merge PR 41 and publish the kit', up: 1 },
+      app: { sel: '[data-tabs="panes"]' },
+    },
+    {
+      name: 'scratchpad bar',
+      why: 'The session scratchpad\'s handle under the panes (Run 3, PRD R10, drawn from ViewFilesPad.dc.html). WsA predates it and '
+        + 'the PRD keeps it (R12, nothing is lost). On the board that strip is terminal body, which the exclusion above leaves out.',
+      design: null,
+      app: { sel: '[data-tabs="bottom"]' },
+    },
+    {
+      name: 'breadcrumb: last crumb',
+      why: 'PRD R8 makes the breadcrumb "repository, initiative, step, active tab", so the last crumb is the active tab\'s title '
+        + '("claude · merge PR 41"). The board ends it with the highlighted task. The first three crumbs are compared.',
+      design: { own: 'Run independent review', nth: 0 },
+      app: { sel: '[data-top="crumb"] > [data-crumb="tab"]' },
+      follows: [{
+        what: 'the trail\'s width, and its clipping of a long name',
+        only: ['box', 'overflowX', 'overflowY'],
+        design: { own: 'microsites', up: 1 },
+        app: { sel: '[data-top="crumb"]' },
+      }],
+    },
+    {
+      name: 'grants: the Grant button and the grants count',
+      why: 'PRD Q3, answered by the PM on 2026-10-04: Grant buttons and the grants count are hidden until the grants ledger behind '
+        + 'them exists (R5\'s rule: what has no backing is hidden, not greyed). The blocker card keeps the button\'s height, so '
+        + 'nothing moves when it comes; the rest of the status bar is compared.',
+      design: { own: 'Grant' },
+      app: null,
+      also: [{ design: { phrase: 'grants 0 active · ' }, app: null }],
+      follows: [{
+        what: 'the width of the status bar\'s right-hand text',
+        only: ['box'],
+        design: { phrase: '⌘K jump · Esc closes tab', parent: true },
+        app: { sel: '[data-shell="status"] > span:last-child' },
+      }],
+    },
+    {
+      name: 'Done: the third row',
+      why: 'The board labels the group "Done · 3" and draws two rows. The seed has three done initiatives (the count is the board\'s '
+        + 'own), and the app draws every row its count names. The label and the first two rows are compared.',
+      design: null,
+      app: { sel: '[data-row="shortlink-redirects"]' },
+      follows: [{ what: 'the height of the rows\' container', only: ['box'], design: { own: 'Needs you · 2', up: 1 }, app: { sel: '#pm-list [data-list="rows"]' } }],
+    },
+    {
+      name: 'artifact: the sync claim, and the link and sync controls',
+      why: 'The board\'s artifact row ends in "⇄ in sync". The app never says "in sync": it has never compared the repository file '
+        + 'with the linked document, and the external-linking work decided it shows only states a row on disk records '
+        + '(panel-detail.js, SYNC_NOT_A_SYNC). The artifact\'s link and sync controls (D53) sit under the row instead (R12). The '
+        + 'row\'s role badge and path are compared.',
+      design: { own: '⇄ in sync' },
+      app: { sel: '[data-art-links]' },
+      follows: [
+        { what: 'the path\'s width (it fills the row)', only: ['box'], design: { own: 'planning/prd/ooh-weather…-prd.md' }, app: { sel: '[data-art-path]' } },
+        { what: 'the height of the artifacts section', only: ['box'], design: { own: 'Artifacts', up: 1 }, app: { sel: '[data-cockpit="artifacts"]' } },
+      ],
+    },
+    {
+      name: 'tab: second line',
+      why: 'A tab names its initiative and session under its title ("<initiative> · session <id>"): after a reload the PM could not '
+        + 'tell which session a reopened tab was on (a PM-reported defect; ui-test AC6). The board\'s tabs have one line. The second '
+        + 'line sits in the tab\'s own lower padding, so the title stays where the board puts it.',
+      design: null,
+      app: { sel: '[data-tab-sub]' },
+    },
+    {
+      name: 'tab: close control on a tab not in front',
+      why: 'The board draws × on the tab in front only. The app keeps it on every tab, so a tab can be closed without first being '
+        + 'brought forward (a control shown only on hover is the trap this surface\'s earlier reviews named). It sits in the tab\'s '
+        + 'right padding, so no tab moves. The × of the tab in front is compared.',
+      design: null,
+      app: { sel: '[data-tab-active="0"] > [data-tab-close]' },
+    },
+    {
+      name: 'tab strip: options and split',
+      why: '"⋯ options" is the pre-flight composer an accepted PRD (workspace-repo-first) kept reachable; "⫽ split" shows two tabs side '
+        + 'by side. Both are live controls the board does not draw (R12). They sit left of "+ session", which is compared where the '
+        + 'board puts it.',
+      design: null,
+      app: { sel: '#pm-tabs [data-tabs="bar"] > button:not([data-tab]):not(:last-child)' },
+    },
+    {
+      name: 'tab: a view\'s dot colour',
+      why: 'PRD R4: a view tab has its own dot colour. The board paints "tool · memory" in the purple the app gives task tabs. Only the '
+        + 'dot\'s colour is skipped; its box and its pixels are compared.',
+      only: ['backgroundColor', 'color', 'borderLeftColor', 'borderBottomColor'],
+      design: { own: 'tool · memory', child: 0 },
+      app: { sel: '[data-tab-dot="view"]' },
+    },
+    {
+      name: 'the tabs column\'s fill',
+      why: 'The tabs column is painted --term-bg so a terminal stays dark in the light theme. The board is drawn dark only, where '
+        + '--term-bg and the page are the same colour, so the board leaves the column unpainted. Only that property is skipped.',
+      only: ['backgroundColor'],
+      design: { own: '+ session', up: 2 },
+      app: { sel: '#pm-tabs' },
+    },
+    {
+      name: 'the body: a grid with a scroll chain',
+      why: 'The board lays its four columns out as a flex row; the app\'s body is a grid, so Focus and the legacy shell re-place the '
+        + 'same four hosts without moving a terminal (R12), and each host down to the scrolling one has a zero minimum and clips '
+        + '(app.js: one tall document once scrolled the whole page). The list\'s rows, the detail and the tab strip scroll, because a '
+        + 'real repository has more than one screen of each; the board is a still picture. Only the layout mechanism, overflow and '
+        + 'minimum height of those containers are skipped; every column\'s box, and everything inside, is compared.',
+      only: ['display', 'gridTemplateColumns', 'gridTemplateRows', 'overflowX', 'overflowY', 'minHeight'],
+      design: null,
+      app: { sel: '[data-shell="body"]' },
+      follows: [{
+        what: 'the overflow and minimum height of the four columns and of the three containers that scroll',
+        only: ['overflowX', 'overflowY', 'minHeight'],
+        design: null,
+        app: { sel: '#pm-rail, #pm-list, #pm-detail, #pm-tabs, #pm-list [data-list="rows"], #pm-tabs [data-tabs="bar"]' },
+      }],
+    },
+  ],
+};
+/* The run's list: each exclusion and its sides, then each of its consequences (`follows`), which is always narrow (`only`) and is
+ * printed under the decision it follows from. */
+const exclusions = (BOARD ? (EXCLUSIONS[BOARD] || []) : []).flatMap((x) => [
+  x,
+  ...(x.also || []).map((y) => ({ ...y, name: x.name, why: x.why, also: true })),
+  ...(x.follows || []).map((f) => ({ ...f, name: x.name + ' → ' + f.what, why: 'follows from "' + x.name + '"', follows: true })),
+]);
+
 function skip(why) { console.log(`⏭  design-parity SKIPPED — ${why}`); process.exit(3); }
 
 function requireOptional(name) { try { return require(name); } catch { return null; } }
 
+// ── a cockpit board as a static reference page ──────────────────────────────────────────────────
+/* A board is a `*.dc.html` file: a <helmet> holding the board's own CSS (and a Google Fonts link), then the board markup inside
+ * <x-dc>. The boards render statically without the design canvas runtime, so the page is built here: the helmet's <style> goes in the
+ * head, the Google Fonts link is replaced by the workspace's own vendored faces, and the markup sits inside a `data-pm-theme="dark"`
+ * root so the comparer's walk starts at the same place on both pages. Nothing is fetched from the network. */
+function boardHtml(name) {
+  const file = path.join(COCKPIT, name + '.dc.html');
+  if (!fs.existsSync(file)) throw new Error('no such board: ' + file);
+  const src = fs.readFileSync(file, 'utf8');
+  const style = (/<helmet>[\s\S]*?<style>([\s\S]*?)<\/style>[\s\S]*?<\/helmet>/.exec(src) || [])[1];
+  const body = (/<\/helmet>([\s\S]*?)<\/x-dc>/.exec(src) || [])[1];
+  if (!style || !body) throw new Error('board ' + name + ' has no <helmet><style> or no <x-dc> body — it cannot be rendered statically');
+  // The board's own root element carries `data-pm-theme`, so the walk starts at the board itself and not at a wrapper of this script's.
+  const rooted = body.replace(/<div\b/, '<div data-pm-theme="dark"');
+  return '<!doctype html><html><head><meta charset="utf-8"><link rel="stylesheet" href="./fonts.css"><style>' + style + '</style></head><body>' + rooted + '</body></html>';
+}
+
 // ── the reference page, patched offline in memory ───────────────────────────────────────────────
 function referenceHtml() {
+  if (BOARD) return boardHtml(BOARD);
   const src = fs.readFileSync(path.join(DESIGN, 'prototype-original.html'), 'utf8');
   const map = JSON.stringify({
     'https://unpkg.com/react@18.3.1/umd/react.production.min.js': './vendor/react.production.min.js',
@@ -179,7 +364,7 @@ async function drive(page, steps) {
   return applied;
 }
 
-async function snap(browser, url, theme, tag, steps = []) {
+async function snap(browser, url, theme, tag, steps = [], side = null) {
   const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
   const errors = [];
   page.on('pageerror', (e) => errors.push(String(e.message)));
@@ -199,21 +384,77 @@ async function snap(browser, url, theme, tag, steps = []) {
   await page.waitForFunction(() => document.fonts.status === 'loaded', null, { timeout: 15000 }).catch(() => {});
   const png = path.join(OUT, `${tag}.png`);
   await page.screenshot({ path: png });
-  const data = await page.evaluate((props) => {
+  // this page's side of each exclusion (see EXCLUSIONS); null when the excluded thing exists on the other page only
+  const xs = side ? exclusions.map((x) => ({ name: x.name, loc: x[side] || null, only: x.only || null })) : [];
+  const data = await page.evaluate(([props, xs, frame, tokenNames]) => {
+    const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3)
+      .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
+    const shown = (e) => { const cs = getComputedStyle(e); const r = e.getBoundingClientRect(); return cs.display !== 'none' && r.width > 0 && r.height > 0; };
+    // ── mark the excluded elements and phrases, and keep their boxes for the pixel mask ──
+    const masks = [], phrases = [];
+    for (const x of xs) {
+      if (!x.loc) continue;
+      const m = { name: x.name, found: 0, boxes: [] };
+      masks.push(m);
+      if (x.loc.phrase) {
+        const tw = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+          const at = n.textContent.indexOf(x.loc.phrase);
+          if (at < 0) continue;
+          if (x.loc.parent) {      // the element that holds the phrase, for a narrow exclusion
+            if (x.only) { n.parentElement.setAttribute('data-parity-only', x.only.join(',')); m.found++; }
+            continue;
+          }
+          const rg = document.createRange(); rg.setStart(n, at); rg.setEnd(n, at + x.loc.phrase.length);
+          const r = rg.getBoundingClientRect();
+          m.found++; m.boxes.push([r.x, r.y, r.width, r.height]); phrases.push({ node: n, phrase: x.loc.phrase });
+        }
+        continue;
+      }
+      let hits = x.loc.sel ? [...document.querySelectorAll(x.loc.sel)]
+        : [...document.querySelectorAll('body *')].filter((e) => own(e) === x.loc.own && shown(e));
+      if (typeof x.loc.nth === 'number') hits = hits.slice(x.loc.nth, x.loc.nth + 1);
+      for (let e of hits) {
+        for (let i = 0; i < (x.loc.up || 0) && e.parentElement; i++) e = e.parentElement;
+        if (typeof x.loc.child === 'number') e = e.children[x.loc.child];
+        if (!e) continue;
+        if (!shown(e)) continue;
+        if (x.only) { e.setAttribute('data-parity-only', x.only.join(',')); m.found++; continue; }
+        e.setAttribute('data-parity-excluded', x.name);
+        const r = e.getBoundingClientRect();
+        m.found++; m.boxes.push([r.x, r.y, r.width, r.height]);
+      }
+    }
+    const cut = (n) => { let t = n.textContent; for (const p of phrases) if (p.node === n) t = t.split(p.phrase).join(' '); return t; };
+    const excluded = (e) => e.hasAttribute('data-parity-excluded');
+    // an element's whole visible text, leaving out what is excluded inside it
+    const fullText = (e) => {
+      let t = '';
+      for (const c of e.childNodes) {
+        if (c.nodeType === 3) t += cut(c);
+        else if (c.nodeType === 1 && !excluded(c)) t += ' ' + fullText(c) + ' ';
+      }
+      return t;
+    };
     const root = document.querySelector('[data-pm-theme]') || document.body;
     const nodes = [], texts = [];
     const walk = (e) => {
+      if (excluded(e)) return;
       const cs = getComputedStyle(e);
       if (cs.display === 'none') return;
+      // On a board run the walk's root is a FRAME on both pages and is not itself a compared node: the board's root is a flex column and
+      // the app's is a grid (the phone's stylesheet places its rows), two ways of drawing the same three bands. Its geometry is the
+      // viewport on both, its fill is diffed by the pixel axis, and everything inside it is compared.
+      if (frame && e === root) { for (const c of e.childNodes) { if (c.nodeType === 3) { const s0 = cut(c).replace(/\s+/g, ' ').trim(); if (s0) texts.push(s0); } else if (c.nodeType === 1) walk(c); } return; }
       const r = e.getBoundingClientRect();
-      const own = [...e.childNodes].filter((n) => n.nodeType === 3)
-        .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
+      const ownT = [...e.childNodes].filter((n) => n.nodeType === 3)
+        .map((n) => cut(n).replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
       const st = {}; for (const p of props) st[p] = cs[p];
       // `full` is the element's WHOLE visible text, used to anchor style comparison; `own` is only
       // its own text nodes. They differ because the prototype's runtime wraps each interpolation in
       // a span, so its label sits one element deeper than the app's.
-      nodes.push({ text: own.slice(0, 60), full: (e.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
-        box: [r.x, r.y, r.width, r.height].map(Math.round), st });
+      nodes.push({ text: ownT.slice(0, 60), full: fullText(e).replace(/\s+/g, ' ').trim().slice(0, 80),
+        box: [r.x, r.y, r.width, r.height].map(Math.round), st, only: (e.getAttribute('data-parity-only') || '').split(',').filter(Boolean) });
       // Walk childNodes IN ORDER, emitting text where it actually sits rather than hoisting all of an
       // element's own text ahead of its children. The status bar is the case that forced this: the
       // design writes "local · persistent server · ", then a <span> holding the count, then
@@ -222,18 +463,44 @@ async function snap(browser, url, theme, tag, steps = []) {
       // the stream has to be.
       for (const c of e.childNodes) {
         if (c.nodeType === 3) {
-          const s = c.textContent.replace(/\s+/g, ' ').trim();
+          const s = cut(c).replace(/\s+/g, ' ').trim();
           if (s) texts.push(s);
         } else if (c.nodeType === 1) walk(c);
       }
     };
     walk(root);
-    return { nodes, texts };
-  }, PROPS);
+    // what each design token resolves to on this page (see TOKENS)
+    const tokens = {};
+    for (const t of tokenNames) {
+      const probe = document.createElement('div');
+      probe.style.color = 'var(--' + t + ')';
+      root.appendChild(probe);
+      tokens[t] = getComputedStyle(probe).color;
+      probe.remove();
+    }
+    return { nodes, texts, masks, tokens };
+  }, [PROPS, xs, !!BOARD, BOARD ? TOKENS : []]);
   await page.close();
   return { ...data, errors, png, applied };
 }
 
+/* THE TOKEN MAPPING (PRD R12). A board declares its own token values at its :root, and four of them are not the token system's:
+ * --card, --sidebar, --accent and --brand-wash are drawn a shade or two off the D38 values the app uses. R12 decided it: "the
+ * mockup's --brand, --success and similar values map to the token system, not to new hex values". So on a board run a computed
+ * colour that is exactly what a board token resolves to is read as that token, and matches when the app's element has the SAME
+ * token's value. It is a mapping by token name, never a tolerance: a colour the board wrote out by hand, or a different token, still
+ * differs. The tokens whose values differ are printed with each run. */
+const TOKENS = ['background', 'foreground', 'card', 'sidebar', 'secondary', 'accent', 'muted-foreground', 'border', 'input', 'brand',
+  'brand-wash', 'success', 'warning', 'info', 'destructive'];
+let tokenMap = new Map();      // design-resolved value -> app-resolved value, for the tokens whose values differ
+
+/* On a board run `font-family` is compared by its FIRST family only. The mockup's fallback tail (`system-ui, sans-serif`) and the token
+ * system's (`ui-sans-serif, system-ui, sans-serif, …`) differ by design (PRD R12: the mockup's values map to the tokens, they do not
+ * replace them), and a fallback is never drawn while the first family loads — the fonts are vendored, so the check would be measuring
+ * a stack nobody sees. Every other property is compared exactly. */
+const sameValue = (p, a, b) => (BOARD && p === 'fontFamily') ? String(a).split(',')[0] === String(b).split(',')[0]
+  : a === b || (BOARD && tokenMap.has(a) && tokenMap.get(a) === b);
+
 function diff(A, B, theme) {
   const problems = [];
   if (B.errors.length) problems.push(`console errors in the app (${B.errors.length}): ${B.errors.slice(0, 5).join(' | ')}`);
@@ -265,11 +532,15 @@ function diff(A, B, theme) {
   const sd = [];
   for (const [t, na] of ia) {
     const nb = ib.get(t); if (!nb) continue;
-    for (const p of PROPS) if (na.st[p] !== nb.st[p]) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] ${p}: design=${na.st[p]} app=${nb.st[p]}`);
+    const skipped = new Set([...(na.only || []), ...(nb.only || [])]);   // a narrow exclusion's listed comparisons (see EXCLUSIONS)
+    for (const p of PROPS) if (!skipped.has(p) && !sameValue(p, na.st[p], nb.st[p])) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] ${p}: design=${na.st[p]} app=${nb.st[p]}`);
     const off = na.box.map((v, i) => Math.abs(v - nb.box[i]));
-    if (Math.max(...off) > 2) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] box: design=${na.box} app=${nb.box}`);
+    if (!skipped.has('box') && Math.max(...off) > 2) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] box: design=${na.box} app=${nb.box}`);
+  }
+  if (sd.length) {
+    problems.push(`${sd.length} computed-style / geometry difference(s)${sd.length > 40 ? ' (the first 40; all of them are in ' + path.join(OUT, 'differences-' + theme + '.txt') + ')' : ''}:\n` + sd.slice(0, 40).join('\n'));
+    try { fs.writeFileSync(path.join(OUT, 'differences-' + theme + '.txt'), sd.join('\n') + '\n'); } catch { /* the report is still printed */ }
   }
-  if (sd.length) problems.push(`${sd.length} computed-style / geometry difference(s):\n` + sd.slice(0, 40).join('\n'));
   return { problems, missing, extra, styleDiffs: sd, theme };
 }
 
@@ -281,7 +552,7 @@ function diff(A, B, theme) {
   // nothing and reported a SKIP — from a machine that had a browser the whole time.
   const exe = require('./lib/find-browser').findBrowser();
   if (!exe) skip('no Chrome/Chromium found (set PMOS_CHROME, or install one)');
-  if (!fs.existsSync(path.join(DESIGN, 'prototype-original.html'))) skip(`the design reference is missing at ${DESIGN}`);
+  if (!BOARD && !fs.existsSync(path.join(DESIGN, 'prototype-original.html'))) skip(`the design reference is missing at ${DESIGN}`);
 
   const alive = await new Promise((r) => {
     const req = http.get(APP_URL, (res) => { res.resume(); r(true); });
@@ -297,8 +568,15 @@ function diff(A, B, theme) {
   const report = {};
   for (const theme of themes) for (const st of states) {
     const key = `${theme}/${st.id}`;
-    const A = await snap(browser, `http://127.0.0.1:${REF_PORT}/index.html`, theme, `design-${theme}-${st.id}`, st.steps);
-    const B = await snap(browser, `${APP_URL}/?fixture=proto`, theme, `app-${theme}-${st.id}`, st.steps);
+    const A = await snap(browser, `http://127.0.0.1:${REF_PORT}/index.html`, theme, `design-${theme}-${st.id}`, st.steps, 'design');
+    const B = await snap(browser, `${APP_URL}/?fixture=${BOARD ? 'cockpit' : 'proto'}`, theme, `app-${theme}-${st.id}`, st.steps, 'app');
+    tokenMap = new Map();
+    const mapped = [];
+    for (const t of TOKENS) {
+      const dv = A.tokens && A.tokens[t], av = B.tokens && B.tokens[t];
+      if (dv && av && dv !== av && !tokenMap.has(dv)) { tokenMap.set(dv, av); mapped.push(`--${t}: ${dv} → ${av}`); }
+    }
+    if (mapped.length) console.log(`\ntoken mapping (PRD R12), by name: ${mapped.join(' · ')}`);
     const d = diff(A, B, theme);
 
     // COULD THE STATE BE REACHED AT ALL? Asserted before anything is compared, and on BOTH pages: a
@@ -313,12 +591,31 @@ function diff(A, B, theme) {
         `nothing below this line is a comparison of ${st.id}`);
     }
 
-    let pixels = null;
+    // A STALE EXCLUSION FAILS: every side an exclusion names must still match something on that page.
+    const stale = [];
+    for (const [who, P] of [['design', A], ['app', B]]) for (const m of P.masks) if (!m.found) stale.push(`"${m.name}" matches nothing in the ${who.toUpperCase()}`);
+    if (stale.length) d.problems.push('stale exclusion(s) — remove or repair them in EXCLUSIONS:\n    ' + stale.join('\n    '));
+    const maskBoxes = [...A.masks, ...B.masks].flatMap((m) => m.boxes.map((b) => ({ name: m.name, b })));
+
+    let pixels = null, maskedPct = 0;
     const pixelmatch = requireOptional('pixelmatch'); const pngjs = requireOptional('pngjs');
     if (pixelmatch && pngjs) {
       const pm = pixelmatch.default || pixelmatch;
       const a = pngjs.PNG.sync.read(fs.readFileSync(A.png)), b = pngjs.PNG.sync.read(fs.readFileSync(B.png));
       if (a.width === b.width && a.height === b.height) {
+        // Paint each excluded box identically on both screenshots (the design's pixels are copied into the app's), so only what is
+        // compared can differ. The masked area is counted and reported, not hidden.
+        const masked = new Uint8Array(a.width * a.height);
+        for (const { b: [x0, y0, w0, h0] } of maskBoxes) {
+          const x1 = Math.max(0, Math.floor(x0)), y1 = Math.max(0, Math.floor(y0));
+          const x2 = Math.min(a.width, Math.ceil(x0 + w0)), y2 = Math.min(a.height, Math.ceil(y0 + h0));
+          for (let y = y1; y < y2; y++) for (let x = x1; x < x2; x++) {
+            const i = y * a.width + x; masked[i] = 1;
+            for (let k = 0; k < 4; k++) b.data[i * 4 + k] = a.data[i * 4 + k];
+          }
+        }
+        let nMasked = 0; for (const v of masked) nMasked += v;
+        maskedPct = +(100 * nMasked / (a.width * a.height)).toFixed(2);
         const out = new pngjs.PNG({ width: a.width, height: a.height });
         const n = pm(a.data, b.data, out.data, a.width, a.height, { threshold: 0.12 });
         fs.writeFileSync(path.join(OUT, `diff-${theme}-${st.id}.png`), pngjs.PNG.sync.write(out));
@@ -332,6 +629,8 @@ function diff(A, B, theme) {
       designNodes: A.nodes.length, appNodes: B.nodes.length,
       textMissing: d.missing.length, textExtra: d.extra.length,
       styleDiffs: d.styleDiffs.length,
+      exclusions: (EXCLUSIONS[BOARD] || []).map((x) => x.name),
+      maskedPct,
       pixelPct: pixels === null ? 'not measured (pixelmatch/pngjs absent)' : +(pixels * 100).toFixed(3),
       clean: d.problems.length === 0,
     };
@@ -346,12 +645,20 @@ function diff(A, B, theme) {
   fs.writeFileSync(path.join(OUT, 'report.json'), JSON.stringify(report, null, 1));
   if (!KEEP && !failed) for (const f of fs.readdirSync(OUT)) if (f.endsWith('.png')) fs.unlinkSync(path.join(OUT, f));
 
+  if (exclusions.length) {
+    const top = EXCLUSIONS[BOARD] || [];
+    console.log(`\n${top.length} named exclusion(s) on board ${BOARD} — each a decision, not a defect:`);
+    for (const x of top) {
+      console.log(`  · ${x.name}${x.only ? ' (only: ' + x.only.join(', ') + ')' : ''} — ${x.why}`);
+      for (const f of x.follows || []) console.log(`      ↳ follows: ${f.what} (only: ${f.only.join(', ')})`);
+    }
+  }
   const scope = `${themes.join(' and ')} × ${states.length} state(s) [${states.map((s) => s.id).join(', ')}]`;
   if (failed) {
     console.log(`\n❌ design parity FAILED in ${failed}/${compared} comparison(s). Renders kept in ${OUT}.`);
     process.exit(1);
   }
-  console.log(`\n✅ design parity — the app is identical to the PM's prototype across ${scope} — ${compared} comparison(s).`);
+  console.log(`\n✅ design parity — the app is identical to ${BOARD ? 'the cockpit board ' + BOARD : "the PM's prototype"} across ${scope} — ${compared} comparison(s).`);
   if (states.length === 1 && states[0].id === 'default') {
     console.log('   (default state only. `--states` walks all ' + STATES.length + ', which is what the PRD asks for.)');
   }