create-pmos 0.134.0 → 0.135.0

package/workspace/lib/vendor/workspace/lib/board-cache.js

@@ -1,156 +0,0 @@
-'use strict';
-/*
- * board-cache.js — the workflow board, cached and derived OFF the event loop.
- *
- * WHY THIS EXISTS. `console-state.workflow()` runs `scripts/workflow-state.js` over every
- * initiative record, and the engine resolves each artifact's FIRST APPEARANCE by shelling `git`.
- * Measured on the PMOS repo, 2026-07-29: ~260 ms per initiative × 109 records = **~30 seconds**, and
- * every millisecond of it is SYNCHRONOUS. Today that cost is paid only when the PM opens the
- * `workflow` lens, where it freezes the server — and with it every PTY WebSocket — for half a minute.
- *
- * PRD R4 puts the same board behind EVERY sidebar row, so an uncached in-process derivation would
- * turn a 30-second freeze into a freeze on every render. Two rules follow, and they are the whole
- * design:
- *
- *   1. NEVER derive on the request path. A miss spawns a CHILD PROCESS and returns immediately.
- *      The event loop is never blocked, however cold the cache is.
- *   2. NEVER serve a stale board as if it were fresh. Every hit carries `as_of` and `stale`, and a
- *      cold cache returns `pending: true` rather than an empty board. A surface that cannot say how
- *      old its answer is has no business showing a stage — that is R5's rule applied to time
- *      instead of to branch.
- *
- * The signature is HEAD + the initiative records' own mtimes, so editing a record refreshes the
- * board without a commit, and switching branch refreshes it without an edit.
- */
-const fs = require('fs');
-const path = require('path');
-const { spawnSync, spawn } = require('child_process');
-
-const MAX_AGE_MS = 10 * 60 * 1000;   // a board older than this is refreshed even if the signature holds
-const REFRESH_TIMEOUT_MS = 120000;   // a derivation that cannot finish in 2 minutes is reported, not awaited
-
-const cache = new Map();             // root -> { sig, at, value, error }
-const inflight = new Map();          // root -> true
-
-// headSha runs on every signature, and the needs poll asks for a signature per registered tree several times per
-// request, so a `git rev-parse` each time held the server for seconds with twenty trees registered. The answer is
-// kept per root while the files a commit, checkout or reset touches (HEAD, its ref, packed-refs, the HEAD reflog)
-// are unchanged; anything unreadable falls back to asking git.
-const headMemo = new Map();          // root -> { key, sha }
-function gitDirOf(root) {
-  const dotgit = path.join(root, '.git');
-  const st = fs.statSync(dotgit);
-  if (st.isDirectory()) return { dir: dotgit, common: dotgit };
-  const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotgit, 'utf8'));
-  if (!m) throw new Error('no gitdir');
-  const dir = path.resolve(root, m[1].trim());
-  let common = dir;
-  try { common = path.resolve(dir, fs.readFileSync(path.join(dir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
-  return { dir, common };
-}
-function headKey(root) {
-  const { dir, common } = gitDirOf(root);
-  const head = fs.readFileSync(path.join(dir, 'HEAD'), 'utf8').trim();
-  const stat = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}:${st.ino}`; } catch { return '-'; } };
-  const ref = /^ref:\s*(.+)$/.exec(head);
-  return [head, ref ? stat(path.join(common, ref[1])) : '', stat(path.join(common, 'packed-refs')), stat(path.join(dir, 'logs', 'HEAD'))].join('|');
-}
-function headSha(root) {
-  let key = null;
-  try { key = headKey(root); } catch { key = null; }
-  const hit = headMemo.get(root);
-  if (key && hit && hit.key === key) return hit.sha;
-  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 });
-  const sha = r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
-  if (key) headMemo.set(root, { key, sha });
-  return sha;
-}
-
-// The records' own state, so an UNCOMMITTED edit still invalidates. Cheap: one readdir + one stat
-// per record, no git, no file contents.
-function recordsSig(root) {
-  // Both layouts (pmos-self `planning/`, a PM repository's `pmos/state/`), and the ledgers the
-  // board's rows depend on: an uncommitted lifecycle or acceptance line must not wait out the TTL (D70).
-  // pm-os-absorb: plan-items.jsonl (Run 4's Build rule reads items) and issues.jsonl (Run 5's report lane reads issues).
-  const dirs = [path.join(root, 'planning', 'initiatives'), path.join(root, 'pmos', 'state', 'initiatives')];
-  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl', 'plan-items.jsonl', 'issues.jsonl'].flatMap((f) => [
-    path.join(root, 'planning', 'runs', f), path.join(root, 'pmos', 'state', f)]);
-  let total = 0; let newest = 0; let any = false;
-  for (const dir of dirs) {
-    let names = [];
-    try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort(); } catch { continue; }
-    any = true; total += names.length;
-    for (const n of names) {
-      try { const st = fs.statSync(path.join(dir, n)); if (st.mtimeMs > newest) newest = st.mtimeMs; }
-      catch { /* a record that vanished mid-scan just does not raise the watermark */ }
-    }
-  }
-  if (!any) return 'none';
-  let led = 0;
-  for (const f of ledgers) { try { const st = fs.statSync(f); led = Math.max(led, Math.round(st.mtimeMs)) + st.size; } catch { /* absent */ } }
-  return `${total}:${Math.round(newest)}:${led}`;
-}
-
-function signature(root) { return `${headSha(root)}|${recordsSig(root)}`; }
-
-// The child runs the SAME reader the lens uses — no second implementation of the board to drift.
-function refresh(root, sig) {
-  if (inflight.get(root)) return;
-  inflight.set(root, true);
-  const script = `
-    const cs = require(${JSON.stringify(path.join(__dirname, 'console-state.js'))});
-    process.stdout.write(JSON.stringify(cs.workflow({ root: ${JSON.stringify(root)} })));
-  `;
-  let out = '';
-  let child;
-  try { child = spawn(process.execPath, ['-e', script], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }); }
-  catch (e) {
-    inflight.delete(root);
-    cache.set(root, { sig, at: Date.now(), value: null, error: 'could not start the board derivation: ' + (e.code || e.message) });
-    return;
-  }
-  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, REFRESH_TIMEOUT_MS);
-  if (timer.unref) timer.unref();
-  child.stdout.on('data', (c) => { out += c; });
-  child.on('error', (e) => {
-    clearTimeout(timer); inflight.delete(root);
-    cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation failed to run: ' + (e.code || e.message) });
-  });
-  child.on('close', (code, signal) => {
-    clearTimeout(timer); inflight.delete(root);
-    if (signal === 'SIGKILL') {
-      cache.set(root, { sig, at: Date.now(), value: null, error: `the board took longer than ${Math.round(REFRESH_TIMEOUT_MS / 1000)}s to derive and was stopped` });
-      return;
-    }
-    if (code !== 0 || !out) {
-      cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation exited without a result' });
-      return;
-    }
-    try { cache.set(root, { sig, at: Date.now(), value: JSON.parse(out), error: null }); }
-    catch { cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation returned unreadable output' }); }
-  });
-}
-
-/*
- * The read the request path uses. Always returns immediately.
- *   { pending: true }                       nothing cached yet; a derivation was started
- *   { ok:false, error, as_of, stale }       the derivation failed — render RED, never a calm empty
- *   { ...workflowPayload, as_of, stale }    a board; `stale` means a refresh is running behind it
- */
-function board(root, { refreshNow = false } = {}) {
-  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow board', as_of: null, stale: false };
-  let sig;
-  try { sig = signature(root); } catch { sig = 'unreadable'; }
-  const hit = cache.get(root);
-  const fresh = hit && hit.sig === sig && (Date.now() - hit.at) < MAX_AGE_MS;
-  if (!fresh || refreshNow) refresh(root, sig);
-  if (!hit) return { pending: true, refreshing: true, as_of: null, stale: false };
-  const envelope = { as_of: new Date(hit.at).toISOString(), stale: !fresh, refreshing: !!inflight.get(root) };
-  if (hit.error) return { ok: false, error: hit.error, ...envelope };
-  return { ...hit.value, ...envelope };
-}
-
-// Test/maintenance seam: drop everything, or one root.
-function invalidate(root) { if (root) { cache.delete(root); inflight.delete(root); } else { cache.clear(); inflight.clear(); } }
-
-module.exports = { board, invalidate, signature, MAX_AGE_MS, REFRESH_TIMEOUT_MS };

package/workspace/lib/vendor/workspace/lib/console-state.js

@@ -1,295 +0,0 @@
-'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');
-const gitInfo = require('./git-info');       // R5: the ladder is branch-scoped — name the branch it came from
-
-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,
-  } };
-}
-
-/*
- * ── workflow: where each initiative is, what is next, what is blocking ────────────────────────
- *
- * The one surface that answers "where am I in the loop" without the PM reconstructing it from
- * files. It renders the SAME ladder the CLI and the Initiative Gate print, from the same engine —
- * `scripts/workflow-state.js` — so the panel can never disagree with what CI is about to say.
- *
- * The engine is the one BUNDLED WITH THE WORKSPACE, pointed at the opened repo via its `root`
- * option. It is deliberately not `require`d out of the opened directory: the engine only reads
- * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
- * executed. An install that does not carry the engine gets an honest error, never a blank panel.
- *
- * WHERE THE ENGINE ACTUALLY LIVES — the defect this list exists to close (incident
- * kit-workflow-engine-missing). "Bundled with the workspace" was the INTENT above; packaging never
- * implemented it. `npm-pkg/package.json` ships only bin/ payload/ workspace/, so in a published
- * install there is no repo two levels up and `../../scripts/workflow-state.js` resolves to nothing.
- * Every adopter row read "ladder unreadable" from 0.11.0 back to whenever this surface shipped —
- * the ladder had never once run outside a PMOS checkout. Two locations, tried in order:
- *
- *   1. `../../scripts/workflow-state.js` — a repo checkout (PMOS-self, any dev clone). Preferred on
- *      purpose: it is the very file `.github/scripts/initiative-gate.sh` executes, so a developer's
- *      panel can never disagree with what CI is about to print on their PR.
- *   2. `lib/engine/workflow-state.js` — the copy the publish step vendors into the bundle. This is
- *      what an adopter runs, and the only reason the ladder derives at all outside this repo.
- *
- * ABSENT and BROKEN are answered differently, because they are different facts (R10). A path that
- * does not exist means "try the next one"; a path that exists and throws is a real fault in an
- * engine that IS installed, and reporting that as "not present" would send the PM looking for a
- * packaging bug they do not have.
- */
-const ENGINE_PATHS = [
-  path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js'),
-  path.join(__dirname, 'engine', 'workflow-state.js'),
-];
-function loadEngine() {
-  const tried = [];
-  for (const p of ENGINE_PATHS) {
-    if (!fs.existsSync(p)) { tried.push(p); continue; }
-    try { return { ok: true, engine: require(p), from: p }; }
-    catch (e) {
-      return { ok: false, error: `the workflow engine at ${p} is installed but failed to load — ${String((e && e.message) || e).slice(0, 160)}` };
-    }
-  }
-  return { ok: false, error: `the workflow engine is not present in this install — the ladder cannot be derived here (looked in: ${tried.join(', ')})` };
-}
-function workflow({ root }) {
-  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
-  const loaded = loadEngine();
-  if (!loaded.ok) return { ok: false, error: loaded.error };
-  const engine = loaded.engine;
-  let ids;
-  try { ids = engine.listInitiatives(root); }
-  catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
-  if (!ids.length) return { ok: true, empty: true, source: 'file-mode' };
-
-  /*
-   * THE TRUNK, not the pull request (workflow-status-sweep R-3).
-   *
-   * This used to be `engine.commitRange(root)` — merge-base(origin/main, HEAD)..HEAD — and the trap
-   * is documented three lines below in words that were written and then not acted on: on `main`, or
-   * on a branch level with it, that range is EMPTY with `range.ok === true`. Nothing reads as
-   * degraded, every `build` rung legitimately reports `pending`, and the four-panel fold rolls
-   * BUILD/EVAL/ACCEPTED to 0/3 for every initiative in the repository — including ones that shipped
-   * months ago. The PM opens the panel to ask what is delivered and is told nothing is.
-   *
-   * So the panel asks the question the CLI board already asks — "where does this initiative stand?",
-   * which only the trunk can answer — and passes the PR range alongside as `changeRange`, which is
-   * what `● in this change` means and the one thing the trunk range genuinely cannot answer. Same
-   * split, same reasons, stated in `historyRange`'s own header. The `build` rung is attributed per
-   * initiative now (R-2), so a trunk-wide range no longer means a trunk-wide answer.
-   */
-  const range = engine.historyRange(root);
-  const changeRange = engine.commitRange(root);
-  // ONE delivery index for the board, built once and shared, exactly as the CLI board does.
-  let deliveryIndex = null;
-  try { deliveryIndex = require(path.join(path.dirname(loaded.from), 'delivery-index.js')).deliveryIndex(root, ids, { recordsDir: engine.layout(root).initiatives }); }
-  catch { deliveryIndex = null; }   // absent → each ladder builds its own; the engine handles it
-  const bi = gitInfo.branchInfo(root);
-  const scope = {
-    branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
-    branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
-    commits: range.ok ? range.shas.length : null,
-    whole_history: range.ok ? !!range.wholeHistory : null,
-    // Kept, and now describing `changeRange` rather than the derivation range. It is no longer the
-    // trap it names — the derivation cannot land in it — but a consumer that wants to say "nothing
-    // in this branch touches these initiatives" still needs the fact, and deleting a field because
-    // the bug it documented was fixed is how the next reader loses the reason.
-    empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
-    change_commits: changeRange.ok ? changeRange.shas.length : null,
-  };
-  const rows = ids.map((id) => {
-    try { return engine.computeWorkflow(id, { root, range, changeRange, deliveryIndex }); }
-    catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
-  });
-  // Same `inFlight` the CLI and the gate use — the panel must not invent its own idea of what is
-  // open. Filtering by `legacy` here was a real bug: on main every record is legacy, so the panel
-  // read "0 in flight" against 93 initiatives, blank at exactly the moment someone opens it.
-  const { shown, hidden, total } = engine.inFlight(rows);
-  const shape = (r) => (r.ok ? {
-    id: r.id, title: r.title, lane: r.lane, stage: r.stage, legacy: r.legacy,
-    in_change: r.in_change, anchor: r.anchor,
-    record: r.record, blockers: r.blockers, next: r.next,
-    steps: r.steps.map((s) => ({ key: s.key, status: s.status, evidence: s.evidence, next: s.next, blocking: s.blocking, rule: s.rule })),
-  } : { id: r.id, error: r.error });
-  return {
-    ok: true, empty: false, source: 'file-mode',
-    data: {
-      live: shown.map(shape),
-      hidden,                       // reported on the client — a silent cap reads as "that is all"
-      total,
-      accepted: rows.filter((r) => r.ok && r.accepted).length,
-      // D70 — stopped initiatives are off the board and not gating, but listed, never dropped silently.
-      stopped: rows.filter((r) => r.ok && r.stopped).map((r) => ({ id: r.id, title: r.title, state: r.stopped.state, reason: r.stopped.reason, at: r.stopped.at, pm: r.stopped.pm })),
-      unreadable: rows.filter((r) => !r.ok).map(shape),
-      blocked: shown.filter((r) => r.ok && r.blockers.length).length,
-      degraded: range.ok ? null : range.reason,
-      scope,                        // R5 — the branch this ladder was derived from; never omit it
-      enforced_from: engine.ENFORCED_FROM,
-    },
-  };
-}
-
-// ENGINE_PATHS/loadEngine are exported for the packaging guard in workspace/test.js: the incident
-// that made them a list was invisible to every unit test precisely because resolution was inline.
-/* ONE initiative's ladder, derived on demand.
- *
- * WHY THIS IS SEPARATE FROM `workflow`. The board caps what it returns (`inFlight`) and reports the
- * remainder as `hidden` — 12 shown against 93 hidden in this repository. That cap is right for a
- * board, which is a list of what is in flight. It is wrong for a PANEL, which is asked about one
- * initiative the PM picked by name: reading the capped list and finding nothing there means "not in
- * the top twelve", and a panel that renders that as "no initiative record" states something false
- * about 93 of 105 records. This derives the one that was asked for, so the answer is about the
- * initiative rather than about its rank.
- *
- * It is safe on the request path for the same reason the board is not: this shells git once for the
- * commit range and runs the engine ONCE, rather than 105 times. `workflow` still owns the board.
- */
-function ladder({ root, id }) {
-  if (!root) return { ok: false, error: 'no workspace root resolved for the ladder' };
-  if (!id) return { ok: false, error: 'no initiative id given' };
-  const loaded = loadEngine();
-  if (!loaded.ok) return { ok: false, error: loaded.error };
-  const engine = loaded.engine;
-  // ABSENT and BROKEN are different facts and must not share an answer. The engine returns
-  // `ok:false` for BOTH "there is no record with this id" and "the record is there and unreadable",
-  // and collapsing them makes the panel paint a red "read failed" over an initiative that simply
-  // does not exist — overstating a missing file as a fault. The initiative list is the arbiter:
-  // an id the repository does not know is an empty read, and only an id it DOES know can fail one.
-  let known = null;
-  try { known = engine.listInitiatives(root); } catch { known = null; }
-  if (Array.isArray(known) && !known.includes(id)) return { ok: true, empty: true, row: null };
-  // The trunk, for the reason `workflow` above states at length: this is asked about ONE initiative
-  // the PM named, and "where does it stand" is a question the pull-request range cannot answer — on
-  // main it is empty, so the panel reported `BUILD 0/3` on delivered work (R-3).
-  let range, changeRange, row;
-  try { range = engine.historyRange(root); }
-  catch (e) { return { ok: false, error: 'could not resolve the commit range: ' + String((e && e.message) || 'error').slice(0, 120) }; }
-  try { changeRange = engine.commitRange(root); } catch { changeRange = { ok: false }; }
-  try { row = engine.computeWorkflow(id, { root, range, changeRange }); }
-  catch (e) { return { ok: false, error: `could not derive the ladder for ${id}: ` + String((e && e.message) || 'error').slice(0, 160) }; }
-  if (row && row.ok === false) return { ok: false, error: row.error || `the record for ${id} could not be read` };
-  const bi = gitInfo.branchInfo(root);
-  return {
-    ok: true,
-    empty: !row,                        // no such record — distinct from a read that failed
-    row: row || null,
-    scope: {
-      branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
-      branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
-      commits: range.ok ? range.shas.length : null,
-      whole_history: range.ok ? !!range.wholeHistory : null,
-      empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
-      change_commits: changeRange.ok ? changeRange.shas.length : null,
-    },
-  };
-}
-
-module.exports = { metrics, radar, workflow, ladder, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };

package/workspace/lib/vendor/workspace/lib/factory-join.js

@@ -1,158 +0,0 @@
-'use strict';
-/* factory-join.js — THE ONE JOIN of the factory graph's work items onto plan items and initiatives (pm-os-absorb Run 4,
- * PRD R6, R7, R8, R19; D65, D86 point 1).
- *
- *   joinFactory(root, { initiative, fold } = {}) → {
- *     ok: true,
- *     byInit: {
- *       [initiativeId]: {
- *         items:   [{ id, plan_item, state, pr, integrated, integrated_at }],
- *                    id = work-item id; plan_item = plan item id | null; state = the work item's folded state
- *                    (scripts/work-item.js deriveItems: declared, claimed, verified, failed, integrated, shipped,
- *                    withdrawn); pr = a pull-request reference from its evidence | null; integrated = true once
- *                    `pmos verify-work` saw its trailer on the default branch; integrated_at = that line's time | null
- *         batches: [{ id, ready, items: [<work-item id>] }],     a D65 Release batch; ready = every item passed its checks
- *       }
- *     },
- *     flags: [{ kind, id, why }],                                a dangling plan_item, an unreadable line, a missing engine
- *     unreadable?: why                                           only when the ledger EXISTS but cannot be read or folded
- *   }
- *   factoryOf(join, id) → that initiative's entry, or null; when the join is `unreadable`, { items: [], batches: [],
- *                         unreadable: why } for every id, so a health rule says Unknown (R8) and never "on track"
- *
- * `initiative` narrows byInit to that one id. `fold` is an optional lib/plan-items.js fold the caller already holds
- * (lib/plan-tree.js layout passes its own), so the dangling check does not read the plan-items ledger twice. Readers
- * never throw; a bad line is a flag.
- *
- * THE FOLD IS D65's, NOT A COPY. Work-item state comes from scripts/work-item.js deriveItems, the fold the writer and
- * the CI checker (scripts/check-work-items.js) use, so this join cannot call an item verified that the gate calls
- * failed. That module lives in scripts/ and is not vendored into a published workspace (its sink guard requires a
- * directory the vendoring walk refuses). In an install without it, a repository that HAS a factory ledger gets the
- * flag `engine-missing` and an empty join; one without a ledger gets an empty join and no flag. Only PMOS-self runs a
- * factory today.
- *
- * WHERE THE LEDGER IS. `planning/work-items.jsonl` of the MAIN working tree of `root`, the same tree the plan-items
- * ledger resolves to (lib/plan-items.js ledgerRoot), so the two halves of the join are read from one tree.
- *
- * A BATCH (D65 Release, D86 point 2) is the work items one materialization declared: one Commit covers the whole batch
- * (R14), and the materialization writes their `declared` lines with ONE `at`. The ledger has no batch field (D86 point
- * 1 adds `plan_item` and nothing else), so the batch is that shared `at`. Only materialized items (a `plan_item`) form
- * batches; a withdrawn or shipped item has left its batch. The batch is keyed on that `at` as an INSTANT, and its id is
- * `b<UTC digits of that at>` — 14 digits to the second, and the 3 millisecond digits after them when they are not
- * 000 — so two materializations in one second have two ids, and one Release grant names `<initiative>:<batch id>`. `ready` = every item in it is verified or integrated, and none failed.
- *
- * Consumers (all read through this module, never work-items.jsonl directly):
- *   - health ctx.factory = factoryOf(joinFactory(root), id)   (lib/health-rules-factory.js reads it; 2C's routes and
- *     5A's drafter assemble it);
- *   - lib/plan-tree.js layout (a materialized item reads Done once integrated, R7);
- *   - 4D's Board and work-check-needs (Review and Release rows);
- *   - 5A's blocks (factory progress when present).
- *
- * Nothing is cached (D33). No network, no git.
- */
-const fs = require('fs');
-const path = require('path');
-
-const WORK_ITEM_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'work-item.js')];
-const READY = new Set(['verified', 'integrated']);
-const PR_RE = /^(?:https?:\/\/\S+\/pull\/\d+\S*|pr:#?\d+)$/i;
-
-function loadWorkItem() {
-  for (const p of WORK_ITEM_PATHS) {
-    if (!fs.existsSync(p)) continue;
-    try { return { ok: true, mod: require(p) }; }
-    catch (e) { return { ok: false, error: `scripts/work-item.js is present but failed to load — ${String((e && e.message) || e).slice(0, 160)}` }; }
-  }
-  return { ok: false, error: 'the work-item fold (scripts/work-item.js) is not in this install, so factory work cannot be read here' };
-}
-
-function mainTreeOf(root) {
-  try { return require('./plan-tree.js').mainTree(path.resolve(String(root))); } catch { return path.resolve(String(root)); }
-}
-
-/** Per work item, from the raw lines: the `at` of its declaration, its last integrated time and its last PR evidence. */
-function lineFacts(text) {
-  const facts = new Map();
-  for (const raw of String(text).split('\n')) {
-    if (!raw.trim()) continue;
-    let r;
-    try { r = JSON.parse(raw); } catch { continue; }
-    if (!r || typeof r !== 'object' || typeof r.item_id !== 'string') continue;
-    const f = facts.get(r.item_id) || { declaredAt: null, integratedAt: null, pr: null };
-    if (r.event === 'declared' && !f.declaredAt && typeof r.at === 'string') f.declaredAt = r.at;
-    if (r.event === 'integrated' && typeof r.at === 'string') f.integratedAt = r.at;
-    if (typeof r.evidence === 'string' && PR_RE.test(r.evidence.trim())) f.pr = r.evidence.trim();
-    facts.set(r.item_id, f);
-  }
-  return facts;
-}
-
-/** The batch id of one declared instant: b + 14 digits, + the milliseconds when they are not 000. Unique per instant. */
-function batchId(at) {
-  const t = Date.parse(at);
-  if (!Number.isFinite(t)) return `b${String(at).replace(/\D/g, '')}`;
-  const digits = new Date(t).toISOString().replace(/\D/g, '');   // YYYYMMDDHHMMSSmmm
-  return `b${digits.endsWith('000') ? digits.slice(0, 14) : digits}`;
-}
-
-function joinFactory(root, { initiative, fold } = {}) {
-  const out = { ok: true, byInit: {}, flags: [] };
-  const unreadable = (kind, why) => { out.flags.push({ kind, id: null, why }); out.unreadable = why; return out; };
-  const file = path.join(mainTreeOf(root), 'planning', 'work-items.jsonl');
-  let text = '';
-  try { text = fs.readFileSync(file, 'utf8'); }
-  catch (e) {
-    if (!(e && e.code === 'ENOENT')) return unreadable('unreadable', `planning/work-items.jsonl cannot be read (${(e && e.code) || e})`);
-    return out;
-  }
-  if (!text.trim()) return out;
-  const W = loadWorkItem();
-  if (!W.ok) return unreadable('engine-missing', W.error);
-
-  let derived;
-  try { derived = W.mod.deriveItems(text, { now: new Date().toISOString() }); }
-  catch (e) { return unreadable('unreadable', `the work-item fold failed: ${String((e && e.message) || e).slice(0, 160)}`); }
-  for (const d of derived.defects) out.flags.push({ kind: d.kind, id: d.item_id || null, why: `line ${d.line}: ${d.detail}` });
-
-  let planFold = fold || null;
-  if (!planFold && derived.items.some((it) => typeof it.plan_item === 'string')) {
-    try { planFold = require('./plan-items.js').readFold(root); }
-    catch (e) { out.flags.push({ kind: 'plan-items-unreadable', id: null, why: `the plan-items ledger cannot be read, so no plan_item is checked: ${String((e && e.message) || e).slice(0, 160)}` }); }
-  }
-  const known = planFold ? new Set([...Object.keys(planFold.items || {}), ...(planFold.withdrawnIds || [])]) : null;
-
-  const facts = lineFacts(text);
-  const batchesOf = new Map();
-  for (const it of derived.items) {
-    if (initiative && it.initiative_id !== initiative) continue;
-    const id = it.item_id;
-    const f = facts.get(id) || {};
-    const planItem = typeof it.plan_item === 'string' ? it.plan_item : null;
-    if (planItem && known && !known.has(planItem)) {
-      out.flags.push({ kind: 'dangling-plan-item', id, why: `plan_item ${planItem} names no plan item` });
-    }
-    const integrated = (it.history || []).includes('integrated');
-    const entry = out.byInit[it.initiative_id] || (out.byInit[it.initiative_id] = { items: [], batches: [] });
-    entry.items.push({ id, plan_item: planItem, state: it.state, pr: f.pr || null, integrated, integrated_at: integrated ? f.integratedAt || null : null });
-    if (planItem && it.state !== 'withdrawn' && it.state !== 'shipped' && f.declaredAt) {
-      const t = Date.parse(f.declaredAt);
-      const key = `${it.initiative_id}\u0000${Number.isFinite(t) ? t : f.declaredAt}`;
-      if (!batchesOf.has(key)) batchesOf.set(key, { init: it.initiative_id, at: f.declaredAt, items: [], states: [] });
-      const b = batchesOf.get(key);
-      b.items.push(id); b.states.push(it.state);
-    }
-  }
-  for (const b of batchesOf.values()) {
-    out.byInit[b.init].batches.push({ id: batchId(b.at), ready: b.states.every((s) => READY.has(s)), items: b.items.slice().sort() });
-  }
-  for (const e of Object.values(out.byInit)) e.batches.sort((a, b) => a.id.localeCompare(b.id));
-  return out;
-}
-
-/** The health ctx.factory value for one initiative: its join entry, or null. */
-function factoryOf(join, id) {
-  if (join && typeof join.unreadable === 'string') return { items: [], batches: [], unreadable: join.unreadable };
-  return (join && join.byInit && Object.prototype.hasOwnProperty.call(join.byInit, id)) ? join.byInit[id] : null;
-}
-
-module.exports = { joinFactory, factoryOf };