create-pmos 0.15.0 → 0.16.0

package/README.md

@@ -333,6 +333,44 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.16.0
+
+**The Terminal Workspace is now a four-panel surface.** The three-column layout is retired and
+replaced by one built to a PM-authored design: repositories, initiatives, initiative detail, and a
+tab strip. Run `npx create-pmos@latest workspace`; the version bump means an existing install
+auto-upgrades.
+
+- **Panel 1 — repositories.** Every repo you've added, with its kind (`⎇` github / `▤` local) and
+  its initiative count, plus a settings & tools drawer holding the secondary modes — `agents`,
+  `memory`, `knowledge` for the current repository, and `focus`, `skills`, `connections`,
+  `scheduled` across all of them.
+- **Panel 2 — initiatives, as a channel list.** Collapsible objective/KR groups over `#slug` rows,
+  one search box that forces the groups open and reports matches elsewhere, and an add form.
+  Initiatives with no anchor are filed and shown as rejected (D59) rather than quietly hidden.
+- **Panel 3 — initiative detail.** The record's pills and derived footer, **task phases** whose
+  status is derived from the workflow ladder rather than declared, a **links** section for
+  references that are not repo files, and the artifact list. A record that fails to parse renders
+  red with the parse error — never a blank panel.
+- **Panel 4 — tabs, scoped per repository.** Three kinds side by side: **term** (a real PTY running
+  your agent CLI untouched), **doc** (view/raw/edit/diff with save, revert and a dirty flag), and
+  **task** (the task spec view). New session, close, and split.
+- **A phone surface.** The same four panels collapse into a mobile navigation model, so triage from
+  a phone is a first-class path and not a scaled-down desktop.
+- **Artifact links are declarations, not integrations.** Linking an artifact to an external
+  destination appends `{artifact_path, kind, target}` to `pmos/state/artifact-links.jsonl`. The sync
+  panel is rendered, but with no connector configured its summary line says exactly that — *no
+  connector configured — nothing was read, and nothing will be written* — and the approval buttons
+  are disabled. It will not show you a difference it never read.
+- **`?fixture=proto`** renders the whole surface from a bundled fixture with no repository at all,
+  which is also how the design comparison is run. It is never the default path.
+
+Unchanged where it matters: **no database, no network at runtime, no telemetry.** The front end
+loads only same-origin assets — fonts and the terminal emulator are served from the install, never
+from a CDN — the server binds `127.0.0.1`, and the only outbound paths remain the ones you invoke
+yourself (`git clone` on repo ingest, `pmos upgrade`, and the one-time `npm install` that builds
+node-pty). No new runtime dependency was added. The file-mode kit itself is unchanged and still
+dependency-free.
+
 ## What's new in 0.15.0
 
 **A major Terminal Workspace rebuild** (#242) — the PM spine, a Claude Design refresh, and a proper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@7b15792
+kernel-source: pmos@198c57c
 assembled: 2026-07-30
 mode: vendor

package/workspace/README.md

@@ -1,7 +1,7 @@
 ---
 type: Reference
 title: "PMOS Terminal Workspace"
-timestamp: 2026-07-25
+timestamp: 2026-07-30
 ---
 
 # PMOS Terminal Workspace
@@ -49,14 +49,34 @@ npm run test:ui      # browser checks: terminal geometry, reader scroll, markdow
 ```
 </details>
 
-## Layout (PM-directed, D62 R9 + round 2)
-Three columns. **Left = the workspace**: repos on top, running agents below, equal halves.
-**Middle = the terminal**, sessions as tabs. **Right rail = the library over the document
-reader** — either pane folds away (click its header), the whole rail hides (`rail`), and both
-the split and the rail width are draggable. The layout you choose survives a reload.
-
-- **Add a repo by picking a folder** — `＋` opens your machine's own folder chooser (typing a
-  path still works; where no chooser exists, an in-app folder browser stands in).
+## Layout — four panels (PM-directed design, built by `workspace-four-panel`)
+The three-column layout is retired. The surface is now **four collapsible panels** under a 44px top
+bar and a 26px status bar, on the oklch token layer, in both themes:
+
+1. **Repositories** — every repo you've added, with its kind (`⎇` github / `▤` local) and a
+   `github|local · N initiatives` sub-line. `＋` adds one by picking a folder (typing a path still
+   works; where no chooser exists, an in-app folder browser stands in). The **settings & tools**
+   drawer holds the secondary modes in two groups: *this repository* (`agents` · `memory` ·
+   `knowledge`) and *all repositories* (`focus` · `skills` · `connections` · `scheduled`). There is
+   deliberately no `workflow` entry — workflows are decided by the agent at runtime, not configured.
+2. **Initiatives** — a channel list. Collapsible objective/KR groups over `#slug` rows, one search
+   box that forces the groups open and reports matches elsewhere, and an add form. Unanchored
+   initiatives are filed honestly and shown **rejected** under D59, never hidden.
+3. **Initiative detail** — the record's header and pills (type / anchor / flow / branch), the derived
+   footer, **task phases** (collapsible; a phase's status is derived from its tasks, and the tasks
+   are derived from the workflow ladder unless the record authors them), a **links** section for
+   references that are not repo files, and **artifacts** with an external destination and the sync
+   panel. A record that fails to read renders **red with the parse error** — never a blank panel.
+4. **Tabs** — scoped per repository, two-line labels naming the initiative, three kinds: **term** (a
+   real PTY), **doc** (view/raw/edit/diff, save/revert, dirty flag), and **task** (the task spec).
+   `＋ session`, close, split.
+
+`⌘K`/`Ctrl-K` focuses search; `Esc` closes the active tab. The panel state you choose survives a
+reload.
+
+- **A phone surface.** The same four panel modules render on a phone — one shell, one renderer, no
+  phone-shaped copy of a list. `lib/mobile-nav.js` owns the destinations and the stack; the live
+  terminal host is never re-parented, so a session you navigate away from keeps running.
 - **Rename a session any time** — the ✎ on its row, a double-click on its tab, or `F2`. Live or
   exited, and it survives a server restart.
 - **Documents read like documents** — the identity block becomes a card, tables are tables,
@@ -66,6 +86,18 @@ the split and the rail width are draggable. The layout you choose survives a rel
   denied); markdown renders **repo-relative images inline**. A remote `![](https://…)` image is
   never fetched (no zero-click beacon); a binary stays listed but inert (open it in your editor).
 
+**Fixture mode.** `?fixture=proto` renders the whole surface from a bundled seed file, with the
+server unable to read any repository — that is how the design comparison is run
+(`npm run test:parity`), and it is never the default.
+
+## Artifact links are declarations, not integrations
+PMOS makes no outbound request and holds no credential. Linking an artifact to an external
+destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to
+`pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector
+configured its summary line says exactly that: *no connector configured — nothing was read, and
+nothing will be written*, with the approval buttons disabled. A difference summary it never read
+would be the watermelon this repo has a word for.
+
 ## The gates are real, never automatic (R5)
 `approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and
 clear the matching needs entry — only ever on your click.
@@ -83,9 +115,9 @@ count them. `pm_label` is **never** derived from a click — κ labels are the P
 
 ## Your own runs are searchable (the history lens)
 Every session's scrollback is already mirrored to disk, which makes it a record of what earlier
-runs actually **did** — the thing structured run rows don't carry. The rail's fourth lens,
-**history**, searches it; the filter box becomes the query. An agent working in a pane can ask
-the same question itself: `GET /api/search?q=…&ws=…`.
+runs actually **did** — the thing structured run rows don't carry. `GET /api/search?q=…&ws=…`
+searches it, and an agent working in a pane can ask the question itself. (The four-panel rebuild
+has not yet re-surfaced this as a UI lens — the endpoint is live, the front-end entry point is not.)
 
 Two guarantees. It is scoped to **one repo** — a workspace never searches another's history
 (R1/R3), and an unrecognised workspace id resolves to home, so it can only ever see less.

package/workspace/design-parity.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/* design-parity — decides whether the workspace matches the design the PM handed over.
+ *
+ * The PM's bar for this surface was one word: IDENTICAL. That is not a thing anyone can hold in
+ * their head across four panels, two themes and ten interaction states, so it is decided here
+ * mechanically instead. This renders the PM's own prototype and the built app side by side at the
+ * same viewport with the same font files, and diffs them on four axes:
+ *
+ *   text      the ordered list of rendered text nodes — a reworded label is a failure
+ *   style     computed styles on structurally-matched elements
+ *   geometry  bounding boxes, to a 2px tolerance
+ *   pixels    a screenshot diff, failing above 0.5% of the viewport
+ *
+ * WHY THE APP IS RENDERED IN FIXTURE MODE. A diff needs like-for-like content, and the app's real
+ * content is this repository. `?fixture=proto` loads the prototype's own seed data through the app's
+ * real renderer — so what is being compared is the rendering, which is the thing under test, and not
+ * the data, which is not. The same fixture doubles as the offline demo path: it proves the UI draws
+ * with no repository readable at all. What it deliberately does NOT prove is that the app is wired to
+ * anything; that is dimension 2 of the rubric and it is asserted in ui-test.js against real state.
+ *
+ * OFFLINE BY CONSTRUCTION. The prototype's runtime fetches React from unpkg. Both files are vendored
+ * under planning/design/four-panel/vendor/ and injected through the runtime's own `window.__resources`
+ * override, and the Google Fonts link is rewritten to the workspace's own vendored woff2 — the same
+ * byte-identical faces the app serves, so a font-fallback difference can never be mistaken for a
+ * 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 --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
+ *   node design-parity.js --keep           keep the rendered PNGs for inspection
+ *
+ * THE STATE WALK. `--states` was advertised in this header for two review rounds while doing
+ * nothing — the flag was never read, so "identical across the captured interaction states" (PRD
+ * success criterion 1, and the rubric's test_method) was decided on the opening screen alone. It is
+ * implemented now: each state is a list of LABELS to click, applied to the prototype and to the app
+ * from a fresh load, and the same four axes are diffed at the end of the sequence. The steps are
+ * text, not selectors, deliberately — a selector would encode one page's DOM and quietly stop
+ * matching on the other, which is the shape a check takes when it goes decorative. A step that
+ * cannot find its label on EITHER page is a hard failure: "could not drive the app there" must
+ * never be recorded as "the app matched there".
+ *
+ * Exit 0 only when every axis is clean. Exit 3 means it could not run (no browser, no server) —
+ * which is a skip, and is reported as one rather than as a pass.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const DESIGN = path.join(ROOT, 'planning', 'design', 'four-panel');
+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'];
+const KEEP = argv.includes('--keep');
+const W = 1600, H = 1000;
+
+/* THE CAPTURED INTERACTION STATES.
+ *
+ * Each entry is a state the PM can put the surface into, expressed as the labels a person would
+ * click to get there — read as the element's OWN text, so "add repository" means the span holding
+ * exactly that, in either page's markup. `default` is the opening screen and always runs.
+ *
+ * Chosen because each one changes a DIFFERENT part of the layout, so the set covers the interaction
+ * model the handoff brief calls final rather than repeating one kind of change: a drawer over panel
+ * 1, a collapsed group in panel 2, an expanded task tree and an opened tab in panels 3 and 4, a
+ * collapsed column, and the panel-3 inline expansion. A state whose divergence is a DECISION rather
+ * than a defect does not belong here — it belongs in the PRD — so if one is ever excluded, the
+ * reason goes in `why` and gets printed, not left as an absence nobody can see.
+ */
+const STATES = [
+  { id: 'default', steps: [] },
+  { id: 'settings-drawer', steps: ['settings & tools'] },
+  { id: 'group-collapsed', steps: ['health:tech'] },
+  { id: 'phase-collapsed', steps: ['intake'] },
+  { id: 'task-tab-open', steps: ['produce the build output'] },
+  { id: 'column-collapsed', steps: ['⟨'] },
+  { id: 'add-repository', steps: ['add repository'] },
+];
+const stateArg = argv.find((a) => a.startsWith('--state='));
+const states = stateArg
+  ? STATES.filter((s) => s.id === stateArg.split('=')[1])
+  : (argv.includes('--states') ? STATES : STATES.filter((s) => s.id === 'default'));
+if (!states.length) {
+  console.error(`no such state: ${stateArg.split('=')[1]} — known: ${STATES.map((s) => s.id).join(', ')}`);
+  process.exit(2);
+}
+
+const PROPS = [
+  'display', 'gridTemplateColumns', 'gridTemplateRows', 'flexDirection', 'alignItems',
+  'justifyContent', 'gap', 'minHeight', 'padding', 'backgroundColor', 'color',
+  'borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth',
+  'borderLeftColor', 'borderBottomColor', 'borderRadius', 'fontFamily', 'fontSize', 'fontWeight',
+  'lineHeight', 'letterSpacing', 'textTransform', 'writingMode', 'overflowX', 'overflowY',
+];
+
+function skip(why) { console.log(`⏭  design-parity SKIPPED — ${why}`); process.exit(3); }
+
+function requireOptional(name) { try { return require(name); } catch { return null; } }
+
+// ── the reference page, patched offline in memory ───────────────────────────────────────────────
+function referenceHtml() {
+  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',
+    'https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js': './vendor/react-dom.production.min.js',
+  });
+  let h = src.replace('<script src="./support.js"></script>',
+    `<script>window.__resources=${map};</script>\n<script src="./support.js"></script>`);
+  h = h.replace(/<link rel="preconnect"[^>]*>\s*/g, '');
+  h = h.replace(/<link href="https:\/\/fonts\.googleapis\.com[^>]*>/, '<link rel="stylesheet" href="./fonts.css">');
+  if (/fonts\.googleapis|unpkg\.com/.test(h.replace(map, ''))) {
+    throw new Error('reference page still carries a remote asset after patching — refusing to compare against a page that would need the network');
+  }
+  return h;
+}
+
+const FONTS_CSS = `
+@font-face{font-family:"Space Grotesk";src:url("./fonts/space-grotesk-var.woff2") format("woff2-variations");font-weight:300 700;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-400.woff2") format("woff2");font-weight:400;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-500.woff2") format("woff2");font-weight:500;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-700.woff2") format("woff2");font-weight:700;font-style:normal;font-display:block}
+`;
+
+function serveReference() {
+  const html = referenceHtml();
+  const types = { '.js': 'text/javascript', '.css': 'text/css', '.woff2': 'font/woff2', '.html': 'text/html' };
+  const server = http.createServer((req, res) => {
+    const p = decodeURIComponent(req.url.split('?')[0]);
+    if (p === '/' || p === '/index.html') { res.writeHead(200, { 'content-type': 'text/html' }); return res.end(html); }
+    if (p === '/fonts.css') { res.writeHead(200, { 'content-type': 'text/css' }); return res.end(FONTS_CSS); }
+    let file = null;
+    if (p.startsWith('/fonts/')) file = path.join(FONTS, path.basename(p));
+    else if (p === '/support.js' || p.startsWith('/vendor/')) file = path.join(DESIGN, p.replace(/^\//, ''));
+    if (file && fs.existsSync(file)) {
+      res.writeHead(200, { 'content-type': types[path.extname(file)] || 'application/octet-stream' });
+      return res.end(fs.readFileSync(file));
+    }
+    res.writeHead(404).end('not found');
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(REF_PORT, '127.0.0.1', () => resolve(server));
+  });
+}
+
+/* Click the element whose OWN text is `label`, on whichever page it is given. Returns false when
+ * nothing visible carries that text — the caller turns that into a failure rather than skipping the
+ * state, because a state that could not be reached is not a state that matched. `closest('button')`
+ * is what actually gets clicked: the prototype's runtime wraps each interpolated label in a span, so
+ * the text node and the control are usually different elements. */
+async function drive(page, steps) {
+  const applied = [];
+  for (const label of steps) {
+    const hit = await page.evaluate((lab) => {
+      const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3)
+        .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).join(' ').trim();
+      const visible = (e) => {
+        const cs = getComputedStyle(e);
+        if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
+        const r = e.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+      };
+      const target = [...document.querySelectorAll('*')].find((e) => own(e) === lab && visible(e));
+      if (!target) return false;
+      (target.closest('button,[role="button"]') || target).click();
+      return true;
+    }, label);
+    applied.push({ label, hit });
+    await page.waitForTimeout(600);
+  }
+  return applied;
+}
+
+async function snap(browser, url, theme, tag, steps = []) {
+  const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
+  const errors = [];
+  page.on('pageerror', (e) => errors.push(String(e.message)));
+  page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+  await page.waitForTimeout(1200);
+  if (theme === 'light') {
+    await page.evaluate(() => {
+      const b = [...document.querySelectorAll('button')].find((x) => /theme/i.test(x.textContent || ''));
+      if (b) b.click();
+    });
+    await page.waitForTimeout(500);
+  }
+  // The interaction steps are applied AFTER the theme is settled, so a state is diffed in the theme
+  // it was reached in rather than in whatever theme the toggle left behind.
+  const applied = await drive(page, 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) => {
+    const root = document.querySelector('[data-pm-theme]') || document.body;
+    const nodes = [], texts = [];
+    const walk = (e) => {
+      const cs = getComputedStyle(e);
+      if (cs.display === 'none') 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 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 });
+      // 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
+      // " sessions running", so hoisting produced "…server · sessions running 3" and reported a text
+      // difference on a bar that is pixel-identical. Reading order is what the PM sees; it is what
+      // the stream has to be.
+      for (const c of e.childNodes) {
+        if (c.nodeType === 3) {
+          const s = c.textContent.replace(/\s+/g, ' ').trim();
+          if (s) texts.push(s);
+        } else if (c.nodeType === 1) walk(c);
+      }
+    };
+    walk(root);
+    return { nodes, texts };
+  }, PROPS);
+  await page.close();
+  return { ...data, errors, png, applied };
+}
+
+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(' | ')}`);
+  // Compare the CONCATENATED stream, not the node list. Node boundaries are an artefact of the
+  // prototype's interpolation wrappers: its template runtime wraps every {{ }} in a <span>, so the
+  // status bar's session count is three text nodes there and one in the app. The handoff brief calls
+  // that runtime an implementation detail, so reproducing its wrapper elements would be copying the
+  // scaffolding rather than the design. What the PM reads is the sequence of words on screen, and
+  // that is what has to match — in content and in order.
+  const streamA = A.texts.join(' ').replace(/\s+/g, ' ').trim();
+  const streamB = B.texts.join(' ').replace(/\s+/g, ' ').trim();
+  let missing = [], extra = [];
+  if (streamA !== streamB) {
+    const wa = streamA.split(' '), wb = streamB.split(' ');
+    let i = 0;
+    while (i < wa.length && i < wb.length && wa[i] === wb[i]) i++;
+    missing = wa.slice(i, i + 20); extra = wb.slice(i, i + 20);
+    problems.push('the rendered text differs — first divergence at word ' + i + ':\n    design: …' +
+      wa.slice(Math.max(0, i - 6), i + 14).join(' ') + '\n    app:    …' +
+      wb.slice(Math.max(0, i - 6), i + 14).join(' '));
+  }
+
+  // Anchor on FULL text, keeping the OUTERMOST match. The walk is pre-order, so a parent is seen
+  // before its children and first-wins yields the outermost element carrying that text — pairing the
+  // design's <button> with the app's <button>, rather than pairing the design's interpolation <span>
+  // against the app's button and reporting the button's own padding and border as differences.
+  const index = (ns) => { const m = new Map(); for (const n of ns) if (n.full && !m.has(n.full)) m.set(n.full, n); return m; };
+  const ia = index(A.nodes), ib = index(B.nodes);
+  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 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 (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 };
+}
+
+(async () => {
+  const pw = requireOptional('playwright-core');
+  if (!pw) skip('playwright-core is not installed (npm install in workspace/)');
+  // Discovery is lib/find-browser.js's, not a third private candidate list. This file used to hunt
+  // only under /opt/pw-browsers, so on a runner whose browser is /usr/bin/chromium-browser it found
+  // 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}`);
+
+  const alive = await new Promise((r) => {
+    const req = http.get(APP_URL, (res) => { res.resume(); r(true); });
+    req.on('error', () => r(false)); req.setTimeout(3000, () => { req.destroy(); r(false); });
+  });
+  if (!alive) skip(`the workspace is not running at ${APP_URL} (node server.js)`);
+
+  fs.mkdirSync(OUT, { recursive: true });
+  const server = await serveReference();
+  const browser = await pw.chromium.launch({ executablePath: exe, args: ['--no-sandbox', '--font-render-hinting=none'] });
+
+  let failed = 0, compared = 0;
+  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 d = diff(A, B, theme);
+
+    // COULD THE STATE BE REACHED AT ALL? Asserted before anything is compared, and on BOTH pages: a
+    // step that found no label leaves the page in the previous state, where a clean diff would say
+    // only that two unchanged screens still match. Reported as a failure with the step named.
+    const missedD = A.applied.filter((s) => !s.hit).map((s) => s.label);
+    const missedA = B.applied.filter((s) => !s.hit).map((s) => s.label);
+    if (missedD.length || missedA.length) {
+      d.problems.push(`the state could not be reached — ` +
+        (missedD.length ? `no visible "${missedD.join('", "')}" in the DESIGN; ` : '') +
+        (missedA.length ? `no visible "${missedA.join('", "')}" in the APP; ` : '') +
+        `nothing below this line is a comparison of ${st.id}`);
+    }
+
+    let pixels = null;
+    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) {
+        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));
+        pixels = n / (a.width * a.height);
+        if (pixels > 0.005) d.problems.push(`pixel diff ${(pixels * 100).toFixed(2)}% of the viewport — ${path.join(OUT, `diff-${theme}-${st.id}.png`)}`);
+      } else d.problems.push(`screenshot sizes differ: design ${a.width}x${a.height}, app ${b.width}x${b.height}`);
+    }
+
+    report[key] = {
+      steps: st.steps,
+      designNodes: A.nodes.length, appNodes: B.nodes.length,
+      textMissing: d.missing.length, textExtra: d.extra.length,
+      styleDiffs: d.styleDiffs.length,
+      pixelPct: pixels === null ? 'not measured (pixelmatch/pngjs absent)' : +(pixels * 100).toFixed(3),
+      clean: d.problems.length === 0,
+    };
+    compared++;
+    console.log(`\n── ${key} ──`);
+    console.log(JSON.stringify(report[key], null, 1));
+    if (d.problems.length) { failed++; console.log('\n' + d.problems.join('\n\n')); }
+  }
+
+  await browser.close();
+  server.close();
+  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));
+
+  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).`);
+  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.)');
+  }
+})().catch((e) => { console.error('design-parity ERROR:', e.stack); process.exit(2); });

package/workspace/lib/find-browser.js

@@ -0,0 +1,60 @@
+'use strict';
+/* find-browser — locate a Chrome/Chromium this machine already has.
+ *
+ * WHY THIS EXISTS AS A MODULE. Three suites need a browser (ui-test, pm-shell-test, design-parity)
+ * and each had its own candidate list. Two of them listed only system paths — /usr/bin/chromium and
+ * the two macOS bundles — and so found nothing on a machine whose browser is the Playwright-managed
+ * one under a browsers root. What happens then is the part worth naming: the suite prints
+ * "no Chrome/Chromium — skipped" and exits 0. **A skip is indistinguishable from a pass in a CI
+ * summary**, which is how the browser assertions came to be believed without ever having run. The
+ * explainer for this surface found the same thing from the other end: ui-test.js is the only suite
+ * that measures real geometry, and it does not run in CI.
+ *
+ * So discovery is one function, it knows about the Playwright layout, and the callers report a skip
+ * as its own outcome rather than as success.
+ *
+ * NO DOWNLOAD, EVER. This finds a browser; it never fetches one. PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is
+ * the environment's own stance and this module agrees with it: a local PM tool must not pull 150 MB
+ * off the network because a test ran.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// A Playwright browsers root holds versioned directories — chromium-1194, chromium_headless_shell-1194
+// — each with the executable at a platform-specific path inside. Enumerated rather than hard-coded,
+// because the version suffix changes with every Playwright bump and a pinned one silently stops
+// matching (which is the same skip-looks-like-pass failure, arriving later).
+function playwrightCandidates() {
+  const roots = [process.env.PLAYWRIGHT_BROWSERS_PATH, '/opt/pw-browsers',
+    path.join(process.env.HOME || '', '.cache', 'ms-playwright')].filter(Boolean);
+  const out = [];
+  for (const root of roots) {
+    let entries = [];
+    try { entries = fs.readdirSync(root); } catch { continue; }
+    for (const dir of entries.sort().reverse()) {          // newest version first
+      if (!/^chromium/.test(dir)) continue;
+      out.push(
+        path.join(root, dir, 'chrome-linux', 'chrome'),
+        path.join(root, dir, 'chrome-linux', 'headless_shell'),
+        path.join(root, dir, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'),
+        path.join(root, dir, 'chrome-win', 'chrome.exe'),
+      );
+    }
+  }
+  return out;
+}
+
+function findBrowser() {
+  const cands = [
+    process.env.PMOS_CHROME,
+    process.env.PMOS_CHROMIUM,
+    ...playwrightCandidates(),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  ].filter(Boolean);
+  return cands.find((c) => { try { fs.accessSync(c, fs.constants.X_OK); return true; } catch { return false; } });
+}
+
+module.exports = { findBrowser, playwrightCandidates };