create-pmos 0.5.0 → 0.6.0

package/workspace/bin/pmos.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/* pmos — one-word launcher for the PMOS Terminal Workspace (Herdr-style).
+ *
+ *   pmos            open THIS directory's repo as a workspace (starting the server if needed)
+ *   pmos <path>     open another directory as a workspace
+ *   pmos status     is the server running? which workspaces, which sessions?
+ *   pmos ls         list the registered workspaces
+ *   pmos stop       stop the server (running sessions end — it says so first)
+ *   pmos doctor     diagnose the environment (node-pty arch, PTY spawn, …)
+ *
+ * The directory you type `pmos` in IS the workspace: it is resolved to its git root and
+ * registered with the server, and the browser opens focused on it. One server hosts many
+ * repos — opening a second repo never disturbs the first one's running sessions.
+ *
+ * The server is started DETACHED: closing this terminal does not kill it — sessions
+ * keep running until `pmos stop` (the persistent-server model, R7). Dependency-free.
+ */
+'use strict';
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const WS = path.resolve(__dirname, '..');              // workspace/
+const STATE = path.join(WS, 'state');
+const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+// pid/log are PER-PORT: a second workspace (or a test server) on another port must never clobber
+// this one's pid file — that is exactly how `pmos stop` was left unable to find the real server.
+const PIDFILE = path.join(STATE, `server-${PORT}.pid`);
+const LOGFILE = path.join(STATE, `server-${PORT}.log`);
+const URL_ = `http://127.0.0.1:${PORT}`;
+const NO_OPEN = process.env.PMOS_NO_OPEN === '1';      // tests set this
+
+const say = (s) => console.log(s);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function probe() {
+  return new Promise((res) => {
+    const req = http.get(`${URL_}/api/sessions`, { timeout: 900 }, (r) => {
+      let b = ''; r.on('data', (c) => (b += c));
+      r.on('end', () => { try { res(JSON.parse(b)); } catch { res(null); } });
+    });
+    req.on('error', () => res(null));
+    req.on('timeout', () => { req.destroy(); res(null); });
+  });
+}
+function api(method, pathname, body) {
+  return new Promise((res) => {
+    const data = body ? JSON.stringify(body) : null;
+    const req = http.request(`${URL_}${pathname}`, {
+      method, timeout: 3000,
+      headers: data ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } : {},
+    }, (r) => { let b = ''; r.on('data', (c) => (b += c)); r.on('end', () => { try { res(JSON.parse(b)); } catch { res(null); } }); });
+    req.on('error', () => res(null));
+    req.on('timeout', () => { req.destroy(); res(null); });
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+// The workspace is the REPO you are in, not the folder you happen to stand in — so `pmos`
+// from a subdirectory opens the whole repo, the same way every git tool behaves.
+function repoRootOf(dir) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' });
+  const top = r.status === 0 ? String(r.stdout).trim() : '';
+  return top && fs.existsSync(top) ? top : path.resolve(dir);
+}
+
+function openBrowser(url) {
+  if (NO_OPEN) return;
+  const cmd = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try { spawn(cmd[0], cmd[1], { detached: true, stdio: 'ignore' }).unref(); } catch {}
+}
+
+function ensureInstalled() {
+  if (fs.existsSync(path.join(WS, 'node_modules', 'node-pty'))) return true;
+  say('First run — installing the workspace (one-time, ~20s)…');
+  const r = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm',
+    ['install', '--no-audit', '--no-fund'], { cwd: WS, stdio: 'inherit' });
+  if (r.status !== 0) {
+    say('✗ install failed. Run `npm run doctor` inside the workspace folder for the exact fix.');
+    return false;
+  }
+  return true;
+}
+
+// Register the target directory and open the browser ON IT. The `focus` broadcast matters:
+// the OS may refocus an already-open tab instead of opening our URL, and without it the PM
+// would be looking at the previously-opened repo — the defect this replaces.
+async function openWorkspace(dir) {
+  const root = repoRootOf(dir);
+  const reg = await api('POST', '/api/workspaces', { root, name: path.basename(root) });
+  if (!reg || !reg.ok) {
+    say(`✗ could not open ${root}${reg && reg.error ? ` — ${reg.error}` : ''}`);
+    openBrowser(URL_);
+    return 1;
+  }
+  const w = reg.workspace;
+  say(`✓ workspace “${w.name}” — ${URL_}?ws=${w.id}`);
+  say(`  ${root}`);
+  openBrowser(`${URL_}?ws=${w.id}`);
+  return 0;
+}
+
+async function up(dir) {
+  if (await probe()) return openWorkspace(dir);
+  if (!ensureInstalled()) return 1;
+  fs.mkdirSync(STATE, { recursive: true });
+  const log = fs.openSync(LOGFILE, 'a');
+  const child = spawn(process.execPath, [path.join(WS, 'server.js')], {
+    cwd: WS, detached: true, stdio: ['ignore', log, log], env: process.env,
+  });
+  child.unref();
+  try { fs.writeFileSync(PIDFILE, String(child.pid)); } catch {}
+  process.stdout.write('starting the workspace ');
+  for (let i = 0; i < 40; i++) {                        // up to ~10s
+    if (await probe()) {
+      say('');
+      say('  sessions keep running after you close this terminal · `pmos stop` shuts it down');
+      return openWorkspace(dir);
+    }
+    process.stdout.write('.');
+    await sleep(250);
+  }
+  say(`\n✗ the server did not come up. Its log says:`);
+  try { say('  ' + fs.readFileSync(LOGFILE, 'utf8').trim().split('\n').slice(-6).join('\n  ')); } catch {}
+  say('  Run `pmos doctor` for a diagnosis.');
+  return 1;
+}
+
+async function status() {
+  const s = await probe();
+  if (!s) { say(`○ not running (start it with: pmos)`); return 1; }
+  const wl = (await api('GET', '/api/workspaces')) || { workspaces: [] };
+  const live = s.sessions.filter((x) => x.state !== 'exited').length;
+  say(`✓ running — ${URL_}`);
+  say(`  ${wl.workspaces.length} workspace(s): ${wl.workspaces.map((w) => w.name).join(' · ') || 'none'}`);
+  say(`  ${s.sessions.length} session(s), ${live} live: ${s.sessions.map((x) => `${x.name}[${x.state}]`).join(' · ') || 'none'}`);
+  return 0;
+}
+
+async function ls() {
+  if (!(await probe())) { say('○ not running (start it with: pmos)'); return 1; }
+  const wl = (await api('GET', '/api/workspaces')) || { workspaces: [] };
+  if (!wl.workspaces.length) { say('no workspaces registered.'); return 0; }
+  for (const w of wl.workspaces) {
+    say(`${w.home ? '★' : '·'} ${w.name}  ${w.sessions} session(s)  [${w.shape}]`);
+    say(`   ${w.root}`);
+  }
+  return 0;
+}
+
+// The pid of whatever is LISTENING on our port — the fallback when the pid file is missing
+// (a crash, or a stale run that removed it). posix only; Windows keeps the manual message.
+function listenerPid() {
+  if (process.platform === 'win32') return null;
+  try {
+    const r = spawnSync('lsof', ['-ti', `tcp:${PORT}`, '-sTCP:LISTEN'], { encoding: 'utf8' });
+    const pid = Number(String(r.stdout || '').split('\n')[0].trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch { return null; }
+}
+
+async function stop() {
+  if (!(await probe())) { say('○ not running.'); try { fs.unlinkSync(PIDFILE); } catch {} return 0; }
+  let pid = null;
+  try { pid = Number(fs.readFileSync(PIDFILE, 'utf8').trim()); } catch {}
+  if (!pid) pid = listenerPid();     // pid file lost — find the server by the port it owns
+  if (!pid) { say(`✗ could not locate the server process (no pid file, and nothing I can see owns port ${PORT}). Stop it manually.`); return 1; }
+  // sessions are tmux-backed: stopping the server leaves them running; the next `pmos` re-attaches.
+  say('stopping the workspace — sessions keep running in tmux and re-attach on the next launch…');
+  try { process.kill(pid); } catch (e) { say(`✗ could not signal pid ${pid}: ${e.message}`); return 1; }
+  for (let i = 0; i < 20; i++) { if (!(await probe())) { say('✓ stopped.'); try { fs.unlinkSync(PIDFILE); } catch {} return 0; } await sleep(250); }
+  say('✗ still responding after 5s — kill it manually.'); return 1;
+}
+
+function doctor() {
+  const r = spawnSync(process.execPath, [path.join(WS, 'doctor.js')], { stdio: 'inherit' });
+  return r.status || 0;
+}
+
+(async () => {
+  const arg = process.argv[2];
+  const cmd = (arg || 'up').toLowerCase();
+  let code = 0;
+  if (cmd === 'status') code = await status();
+  else if (cmd === 'ls' || cmd === 'list') code = await ls();
+  else if (cmd === 'stop') code = await stop();
+  else if (cmd === 'doctor') code = doctor();
+  else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    say('usage: pmos [<path>|status|ls|stop|doctor]');
+    say('  pmos          open the current repo as a workspace (starts the server if needed)');
+    say('  pmos <path>   open another repo as a workspace');
+    code = 0;
+  } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {
+    // `pmos open ../other-repo` — the path is the argument AFTER the verb
+    code = await up(process.argv[3] ? path.resolve(process.argv[3]) : process.cwd());
+  } else if (arg && !arg.startsWith('-')) {
+    code = await up(path.resolve(arg));                 // `pmos ../other-repo`
+  } else {
+    code = await up(process.cwd());
+  }
+  process.exit(code);
+})();

package/workspace/doctor.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/* pmos workspace doctor — diagnoses the environment the server needs.
+ * Checks, in order: Node version → node-pty loads → native binary arch matches the Node
+ * process → a real PTY actually spawns and echoes. Prints the exact fix for each failure.
+ * Exit 0 = healthy; exit 1 = something needs fixing (the output says what). */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const checks = [];
+const ok = (name, extra) => { checks.push(true); console.log(`✓ ${name}${extra ? ' — ' + extra : ''}`); };
+const bad = (name, fix) => { checks.push(false); console.log(`✗ ${name}`); if (fix) console.log(`  fix: ${fix}`); };
+
+// Read the CPU arch a compiled binary was built for, from its magic bytes (no external tools).
+function binaryArch(file) {
+  try {
+    const b = Buffer.alloc(8);
+    const fd = fs.openSync(file, 'r'); fs.readSync(fd, b, 0, 8, 0); fs.closeSync(fd);
+    if (b[0] === 0x7f && b[1] === 0x45) return { x: 'ELF', arch: b[4] === 2 ? (b.readUInt16LE ? 'elf64' : 'elf') : 'elf32' };
+    const m = b.readUInt32LE(0);
+    if (m === 0xfeedfacf) { const cpu = b.readUInt32LE(4); return { x: 'Mach-O', arch: cpu === 0x0100000c ? 'arm64' : cpu === 0x01000007 ? 'x86_64' : 'cpu:' + cpu.toString(16) }; }
+    if (m === 0xbebafeca || m === 0xcafebabe) return { x: 'Mach-O universal', arch: 'universal' };
+    if (b[0] === 0x4d && b[1] === 0x5a) return { x: 'PE', arch: 'windows' };
+  } catch {}
+  return null;
+}
+
+(async () => {
+  console.log(`pmos workspace doctor — node ${process.version} (${process.platform}/${process.arch})\n`);
+
+  // 1. Node version
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 18) ok(`Node ${process.version} (>= 18)`);
+  else bad(`Node ${process.version} is too old`, 'install Node 18+ (arm64-native on Apple Silicon)');
+
+  // 2. node-pty loads
+  let pty = null;
+  try { pty = require('node-pty'); ok('node-pty native module loads'); }
+  catch (e) {
+    bad(`node-pty failed to load: ${e.message.split('\n')[0]}`,
+      'npm rebuild node-pty --build-from-source   (needs: macOS `xcode-select --install`; Linux `apt install build-essential python3`)');
+  }
+
+  // 3. native binary arch matches the running Node (the posix_spawnp culprit)
+  const helper = path.join(__dirname, 'node_modules', 'node-pty', 'build', 'Release',
+    process.platform === 'win32' ? 'pty.node' : 'spawn-helper');
+  const alt = path.join(__dirname, 'node_modules', 'node-pty', 'build', 'Release', 'pty.node');
+  const bin = fs.existsSync(helper) ? helper : (fs.existsSync(alt) ? alt : null);
+  if (!bin) bad('node-pty native binary not found (build incomplete)', 'rm -rf node_modules && npm install');
+  else {
+    const info = binaryArch(bin);
+    const want = process.arch;                       // arm64 | x64 | …
+    const got = info && info.arch;
+    const match = !info || info.arch === 'universal' || info.x === 'ELF' || info.x === 'PE' ||
+      (want === 'arm64' && got === 'arm64') || (want === 'x64' && got === 'x86_64');
+    if (match) ok(`native binary present${got && got !== 'universal' && info.x === 'Mach-O' ? ` (${got})` : ''}`);
+    else bad(`ARCH MISMATCH: Node is ${want} but node-pty's binary is ${got} — this causes 'posix_spawnp failed' on every session`,
+      `install a ${want}-native Node (e.g. \`brew install node\` on an arm64 shell), then: rm -rf node_modules && npm install`);
+  }
+
+  // 4. a real PTY spawns and echoes
+  if (pty) {
+    const sh = process.platform === 'win32' ? (process.env.COMSPEC || 'powershell.exe') : '/bin/sh';
+    try {
+      const out = await new Promise((resolve, reject) => {
+        let acc = '';
+        const p = pty.spawn(sh, [], { name: 'xterm-256color', cols: 80, rows: 24, cwd: __dirname, env: process.env });
+        const t = setTimeout(() => { try { p.kill(); } catch {}; reject(new Error('timeout — shell spawned but never echoed')); }, 4000);
+        p.onData((d) => { acc += d; if (acc.includes('DOCTOR_OK')) { clearTimeout(t); try { p.kill(); } catch {}; resolve(acc); } });
+        p.onExit(() => { if (!acc.includes('DOCTOR_OK')) { clearTimeout(t); reject(new Error(`shell exited before echoing (got ${acc.length} bytes)`)); } });
+        p.write('echo DOCTOR_OK\r');
+      });
+      ok(`real PTY spawns + echoes (${sh})`);
+    } catch (e) {
+      bad(`PTY spawn failed: ${e.message}`,
+        /posix_spawnp/.test(e.message)
+          ? 'this is the broken-native-build signature — npm rebuild node-pty --build-from-source (and see the arch check above)'
+          : process.platform === 'win32' ? 'native Windows needs WSL for a real PTY — run the workspace inside WSL'
+          : 'check that /bin/sh exists and is executable');
+    }
+  }
+
+  // 5. tmux — the session-persistence backing. Not fatal: absent, the server falls back to
+  //    direct PTYs (sessions still work, but a `pmos stop`/restart ends them). Present, a session
+  //    OUTLIVES a server restart and is re-attached live. This check explains which mode you're in.
+  const tmuxV = spawnSync('tmux', ['-V'], { encoding: 'utf8' });
+  if (tmuxV.status === 0) {
+    ok(`tmux present (${String(tmuxV.stdout).trim()}) — sessions PERSIST across \`pmos stop\`/restart`);
+  } else {
+    // a soft note, not a ✗: everything still works, just without restart-proof sessions
+    console.log('• tmux not found — sessions run on direct PTYs and END on `pmos stop`/restart (no live persistence).');
+    console.log('  optional fix: install tmux (macOS `brew install tmux`; Linux `apt install tmux`) for restart-proof sessions.');
+  }
+
+  const fails = checks.filter((c) => !c).length;
+  console.log(`\n${checks.length - fails}/${checks.length} checks passed${fails ? ' — fix the ✗ items above, then re-run npm run doctor' : ' — environment healthy, npm start away'}`);
+  process.exit(fails ? 1 : 0);
+})();

package/workspace/lib/console-state.js

@@ -0,0 +1,117 @@
+'use strict';
+/*
+ * Read-only console state readers (D64 / pivot-workspace-first, Track B).
+ *
+ * The workspace console surfaces — the "needs you" queue, a radar-style health summary, and a
+ * metrics view — derive ONLY from local file-mode state: the kit's `pmos/state/*.jsonl` and, as a
+ * seed/demo source when no live state exists yet, the committed hosted snapshot under
+ * `planning/data-export/<date>-hosted-snapshot/*.json`. Live file-mode state is ALWAYS preferred.
+ *
+ * HONESTY BY CONSTRUCTION (the anti-watermelon rule): every reader returns a discriminated result —
+ *   { ok:true,  empty:false, source, data }   data present
+ *   { ok:true,  empty:true,  source }          genuinely nothing (calm empty state on the client)
+ *   { ok:false, error }                        a missing source / parse failure — the client MUST
+ *                                              render this RED, never a green "all clear".
+ * A missing DATA source (no live file AND no snapshot) is an ERROR, not an empty — a health surface
+ * that cannot read its inputs is broken, and a broken honesty surface must read red.
+ */
+const fs = require('fs');
+const path = require('path');
+const reviewGate = require('./review-gate');
+
+function loadJson(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  try { return { ok: true, data: JSON.parse(text) }; }
+  catch { return { ok: false, error: `${path.basename(file)} is not valid JSON — the file-mode source is corrupt, not empty` }; }
+}
+function loadJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  const rows = []; let bad = 0;
+  for (const line of text.split('\n')) {
+    const t = line.trim(); if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch { bad++; }
+  }
+  // A file that is entirely unparseable is corrupt state — surface it red rather than call it empty.
+  if (bad > 0 && rows.length === 0) return { ok: false, error: `every line in ${path.basename(file)} is malformed — corrupt file-mode state` };
+  return { ok: true, data: rows, bad };
+}
+
+function computeMetricsFromRuns(runs) {
+  const corr = runs.map((r) => Number(r.human_corrections) || 0);
+  const total = corr.reduce((a, b) => a + b, 0);
+  const needing = corr.filter((c) => c > 0).length;
+  const n = runs.length;
+  return {
+    total_runs: n,
+    avg_corrections_per_run: n ? +(total / n).toFixed(3) : 0,
+    runs_needing_correction: needing,
+    share_runs_corrected: n ? +(needing / n).toFixed(3) : 0,
+    per_initiative: [],
+  };
+}
+
+// ── metrics: prefer live pmos/state/runs.jsonl; fall back to the snapshot's metrics.json ──
+function metrics({ stateDir, snapshotDir }) {
+  if (stateDir) {
+    const live = loadJsonl(path.join(stateDir, 'runs.jsonl'));
+    if (live.ok) {
+      if (!live.data.length) return { ok: true, empty: true, source: 'file-mode' };
+      return { ok: true, empty: false, source: 'file-mode', data: computeMetricsFromRuns(live.data) };
+    }
+    if (live.ok === false) return { ok: false, error: live.error };
+    // live.missing → fall through to the snapshot
+  }
+  if (!snapshotDir) return { ok: false, error: 'no metrics source — no live runs.jsonl and no hosted snapshot for this workspace' };
+  const snap = loadJson(path.join(snapshotDir, 'metrics.json'));
+  if (snap.missing) return { ok: false, error: 'metrics source missing — neither live runs.jsonl nor the hosted snapshot is present' };
+  if (!snap.ok) return { ok: false, error: snap.error };
+  const m = snap.data || {};
+  return { ok: true, empty: false, source: 'snapshot', data: {
+    total_runs: m.total_runs, avg_corrections_per_run: m.avg_corrections_per_run,
+    runs_needing_correction: m.runs_needing_correction, share_runs_corrected: m.share_runs_corrected,
+    per_initiative: Array.isArray(m.per_initiative) ? m.per_initiative.slice(0, 12) : [],
+  } };
+}
+
+// ── radar: prefer a live pmos/state/radar.json; fall back to the snapshot's radar_all_sections.json ──
+function radar({ stateDir, snapshotDir }) {
+  let src = null, source = null;
+  if (stateDir) {
+    const live = loadJson(path.join(stateDir, 'radar.json'));
+    if (live.ok) { src = live.data; source = 'file-mode'; }
+    else if (live.ok === false) return { ok: false, error: live.error };
+  }
+  if (!src) {
+    if (!snapshotDir) return { ok: false, error: 'no radar source — no live radar.json and no hosted snapshot for this workspace' };
+    const snap = loadJson(path.join(snapshotDir, 'radar_all_sections.json'));
+    if (snap.missing) return { ok: false, error: 'radar source missing — neither live radar.json nor the hosted snapshot is present' };
+    if (!snap.ok) return { ok: false, error: snap.error };
+    src = snap.data; source = 'snapshot';
+  }
+  const d = src || {};
+  const gates = Array.isArray(d.eval_gates) ? d.eval_gates : [];
+  const passing = gates.filter((g) => reviewGate.isReviewPass(g.verdict, g.score)).length;
+  const wms = (Array.isArray(d.watermelons) ? d.watermelons : []).map((w) => ({
+    id: w.id, title: w.title, rag: w.rag,
+    verdict: w.latest_eval_verdict, score: w.latest_eval_score, corrections: w.avg_human_corrections,
+  }));
+  const calRaw = Array.isArray(d.calibration) ? d.calibration[0] : d.calibration;
+  const calibration = calRaw ? {
+    n: calRaw.n, kappa: calRaw.kappa, tnr: calRaw.tnr, status: calRaw.status,
+    meets_d40: !!calRaw.meets_d40_kappa, caveat: calRaw.leakage_caveat || null,
+  } : null;
+  const okr = (Array.isArray(d.okr_pulse) ? d.okr_pulse : []).slice(0, 8).map((o) => ({
+    objective: o.objective, kr: o.kr, progress: o.progress_pct, pulse: o.pulse,
+  }));
+  return { ok: true, empty: false, source, data: {
+    // watermelon flags = anything not green (amber/red) leads; the whole point is to surface drift
+    watermelons: wms,
+    flags: wms.filter((w) => w.rag && String(w.rag).toLowerCase() !== 'green').length,
+    eval_gate: { total: gates.length, passing, pass_rate: gates.length ? +(passing / gates.length).toFixed(3) : null },
+    calibration, okr_pulse: okr,
+  } };
+}
+
+module.exports = { metrics, radar, computeMetricsFromRuns, loadJson, loadJsonl };

package/workspace/lib/file-mode-parse.js

@@ -0,0 +1,58 @@
+'use strict';
+/*
+ * Canonical file-mode state parsers (D64 / pivot-workspace-first, Track D1).
+ *
+ * The workspace server (server.js) and the kit's metrics.py both read the SAME file-mode records —
+ * acceptances.jsonl, evals.jsonl, runs.jsonl, and the leading frontmatter of initiative markdown —
+ * and MUST agree on what a repo declared. Before D64 each had its own inline copy of these parsers,
+ * so they were free to drift. server.js now delegates to this module; metrics.py mirrors it in
+ * Python; kit/fixtures/test_parsers.py runs both against kit/fixtures/** and fails CI on disagreement.
+ */
+const fs = require('fs');
+const reviewGate = require('./review-gate');
+
+// The LEADING YAML-ish frontmatter block ONLY — body text must never be able to fake a declaration.
+// Mirrors metrics.py exactly: `key: value` lines (first value wins), `---` fences and blank lines are
+// skipped, and the FIRST non-frontmatter, non-fence, non-blank line ends the block.
+function parseLeadingFrontmatter(text) {
+  const fm = {};
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.+?)\s*$/);
+    if (m) { if (!(m[1] in fm)) fm[m[1]] = m[2]; continue; }
+    if (line.trim() && !line.startsWith('---')) break;
+  }
+  return fm;
+}
+function leadingFrontmatter(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return {}; }
+  return parseLeadingFrontmatter(text);
+}
+
+// One JSON object per line; blank lines skipped, torn lines tolerated (dropped), never guessed.
+function readJsonlRows(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* torn line — skipped, mirrors metrics.py */ }
+  }
+  return out;
+}
+
+// The kit's north-star / throughput field: an acceptance counts only when accepted === true.
+function isAccepted(row) { return !!row && row.accepted === true; }
+
+// A declared outcome is DUE when it has an id + outcome_metric and its horizon is past today. A
+// MISSING horizon counts as due (horizon-gaming-by-omission) — identical to metrics.py.
+function outcomeDue(fm, today) {
+  if (!fm || !fm.id || !fm.outcome_metric) return false;
+  return String(fm.outcome_horizon || '0000-00-00') < String(today);
+}
+
+module.exports = {
+  parseLeadingFrontmatter, leadingFrontmatter, readJsonlRows, isAccepted, outcomeDue,
+  isReviewPass: reviewGate.isReviewPass,
+};