create-pmos 0.22.0 → 0.23.0

package/payload/scripts/workflow-state.js

@@ -0,0 +1,1139 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS workflow state — the derivation engine.
+ *
+ *   node scripts/workflow-state.js                 the board: every initiative, stage + blocker
+ *   node scripts/workflow-state.js <id>            the ladder for one initiative
+ *   node scripts/workflow-state.js <id> --json     the same, machine-readable
+ *   node scripts/workflow-state.js --gate <id>     CI: exit 1 on a BLOCKING order violation
+ *   node scripts/workflow-state.js --open          the board, open initiatives only
+ *     --root <dir>   operate on another repo root (fixtures, tenant workspaces)
+ *
+ * WHY THIS EXISTS. The Initiative Gate asserts that a lane's spec artifacts EXIST when CI runs. It
+ * has never asserted that they came FIRST. A PRD written after the implementation, in the same PR,
+ * satisfies it byte-for-byte identically to one written before — so "eval-driven PM" (D13),
+ * "prototype before PRD" (D60) and "explain the surface before you spec it" were norms with nothing
+ * behind them. See planning/prd/workflow-enforcement-prd.md §2 for the seven holes this closes.
+ *
+ * TWO DESIGN RULES, both load-bearing:
+ *
+ *   1. DERIVED, NEVER DECLARED. There is deliberately no `stage:` key. Stage and step status are
+ *      computed from the record's frontmatter, the files it points at, the append-only rows in
+ *      planning/runs/*.jsonl, and git's own first-appearance history. A status field nobody updates
+ *      is a board that lies, and a board that lies is a watermelon generator — worse than no board.
+ *
+ *   2. ORDER COMES FROM GIT, NOT FROM TIMESTAMPS. Author/commit dates are rewritten by rebases and
+ *      can tie within a second. So ordering compares POSITION IN THE COMMIT RANGE (oldest = 0),
+ *      never clock time. A path introduced before the range is index -1 (it already existed); a path
+ *      on disk that no commit has added yet is Infinity (uncommitted).
+ *
+ * HONESTY BY CONSTRUCTION. Every step carries one of: done · current · blocked · pending · n/a ·
+ * unknown. `unknown` is its own state and never collapses into `done` or `n/a` — a shallow clone or
+ * an unreadable input must be visibly distinct from a satisfied step. A gate that cannot see its
+ * inputs reports that it cannot see them; it never reports a pass.
+ *
+ * Zero dependencies, stock Node. It runs in CI, in a terminal, and inside the workspace server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+/*
+ * ONE resolver, shared with the workspace (spec R-6 / contract C-7). Two readers that disagreed
+ * about whether an anchor resolves would reproduce the exact defect this work removes — the ladder
+ * and the OKR surface previously held separate, incompatible opinions about the same field.
+ */
+const anchors = require('./anchor-resolve');
+/*
+ * ONE reader for delivery too (workflow-status-sweep R-1). `buildCommits` used to answer "is there a
+ * build commit in this range" — a question about a RANGE — while both of its callers asked a
+ * question about an INITIATIVE. Over a pull-request range those coincide, because the range IS one
+ * initiative's work; over the trunk they do not, and every initiative read `done` with the same 488
+ * commits of evidence. The attribution signal already existed, module-private, inside the workspace
+ * server. It is shared now, for the same reason `anchor-resolve` is.
+ */
+const delivery = require('./delivery-index');
+
+// The OKR documents and the budget registry are read once per root, not once per initiative: the
+// board derives ~100 ladders in a single pass and re-reading the same three files each time is the
+// same waste the shared commit-range exists to avoid.
+const _okrCache = new Map();
+const _budCache = new Map();
+function okrIndexFor(root) {
+  if (!_okrCache.has(root)) _okrCache.set(root, anchors.parseOkrIndex(root));
+  return _okrCache.get(root);
+}
+function budgetsFor(root, L) {
+  if (!_budCache.has(root)) {
+    try { _budCache.set(root, { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }); }
+    catch { _budCache.set(root, { ok: false, text: '', path: path.relative(root, L.budgets) }); }
+  }
+  return _budCache.get(root);
+}
+
+/*
+ * ── Enforcement boundary ──────────────────────────────────────────────────────────────────────
+ * An initiative is LEGACY when its record already existed before the change under review — i.e. its
+ * record first-appeared outside this commit range. Legacy records are reported and never failed by
+ * the rules introduced here (R0/O3/O4/O5/O6/O7); the original artifact-existence contract (R1/R2)
+ * binds everywhere, because it always did.
+ *
+ * The boundary is DERIVED FROM GIT, not from the record's own `timestamp:` frontmatter. A
+ * self-declared date is a field the record controls, so backdating it would grandfather you out of
+ * your own gate — the one thing a compliance boundary must not permit. Git's add-date is written by
+ * the commit, not by the author of the file's contents.
+ *
+ * `ENFORCED_FROM` is only the FALLBACK, used when git cannot answer (no history, a fresh fixture
+ * repo, a shallow clone). It is deliberately not the primary test.
+ *
+ * The 92 records that predate this are NOT backfilled. Inventing a specimen-test answer for work
+ * already shipped would be fabricating a judgement nobody made, and a gate whose history is
+ * fabricated is worth less than no gate at all.
+ */
+const ENFORCED_FROM = '2026-07-28';
+
+// A path counts as BUILD when it is neither a planning artifact nor documentation. `prototype/` is
+// build only in the prototype lane, where the specimen IS the deliverable (D60); in every other lane
+// a prototype directory is somebody else's leg-A work and must not count as this initiative's build.
+function isBuildPath(p, lane) {
+  if (!p) return false;
+  if (p.startsWith('planning/') || p.startsWith('okf/') || p.startsWith('pmos/state/')) return false;
+  if (p.startsWith('prototype/')) return lane === 'prototype';
+  if (p.endsWith('.md')) return false;               // docs, incl. root governance files
+  return true;
+}
+
+// ── Frontmatter ────────────────────────────────────────────────────────────────────────────────
+// The LEADING block only — body text must never be able to fake a declaration. Mirrors
+// workspace/lib/file-mode-parse.js and kit/scripts/metrics.py, plus the surrounding-quote strip the
+// bash gate does, so all four readers agree on what a record declared.
+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].replace(/^"(.*)"$/s, '$1');
+      continue;
+    }
+    if (line.trim() && !line.startsWith('---')) break;
+  }
+  return fm;
+}
+function readFrontmatter(file) {
+  try { return parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+/*
+ * The ledger reader, and the one place a torn line is REPORTED rather than merely dropped (R-4).
+ *
+ * A line that does not parse is still never guessed at — that part was always right. What was wrong
+ * was the silence: a truncated acceptance row did not make the ladder say "a row here is
+ * unreadable", it made the ladder say the initiative was never accepted. The file's own honesty rule
+ * ("a gate that cannot see its inputs reports that it cannot see them") held for git ranges and not
+ * for ledger lines.
+ *
+ * The channel is out-of-band — an optional `defects` array the caller passes in — rather than a
+ * changed return type, because every existing call site wants the rows and only the sweep wants the
+ * damage. Changing the shape would have made ~six callers handle a case none of them can act on.
+ */
+function readJsonl(file, defects) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); }
+    catch (e) {
+      // Dropped, never guessed — and now said out loud to anyone who asked to hear it.
+      if (Array.isArray(defects)) {
+        defects.push({ file, line: i + 1, reason: String((e && e.message) || 'not valid JSON').slice(0, 120), text: t.slice(0, 120) });
+      }
+    }
+  }
+  return out;
+}
+
+// ── Repo layout — pmos-self and the kit disagree on where state lives, so detect rather than assume
+function layout(root) {
+  const selfDir = path.join(root, 'planning', 'initiatives');
+  const kitDir = path.join(root, 'pmos', 'state', 'initiatives');
+  const isKit = !fs.existsSync(selfDir) && fs.existsSync(kitDir);
+  return {
+    root,
+    kit: isKit,
+    initiatives: isKit ? kitDir : selfDir,
+    runsDir: isKit ? path.join(root, 'pmos', 'state') : path.join(root, 'planning', 'runs'),
+    runsFile: isKit ? 'runs.jsonl' : 'agent-runs.jsonl',
+    explainers: isKit
+      ? path.join(root, 'pmos', 'state', 'explainers')
+      : path.join(root, 'planning', 'evals', 'explainers'),
+    budgets: isKit
+      ? path.join(root, 'pmos', 'state', 'health-budgets.md')
+      : path.join(root, 'planning', 'okrs', 'health-budgets.md'),
+  };
+}
+
+// ── Git ────────────────────────────────────────────────────────────────────────────────────────
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+/*
+ * The commit range this initiative's work lives in, oldest first, as sha -> index.
+ *
+ * In CI that is base..HEAD for the PR. Locally it is the merge-base with the default branch. When
+ * neither resolves — a shallow clone, a detached checkout with no base — the range is NULL and every
+ * order check downgrades to `unknown`. It does not downgrade to `pass`: an order rule that cannot be
+ * evaluated has not been satisfied, and saying so is the whole point of the honesty rule above.
+ */
+function commitRange(root) {
+  return buildRange(root, { spec: null });
+}
+
+/*
+ * The BOARD's range: the whole trunk, not the pull request.
+ *
+ * These are two different questions and they were sharing an answer. The gate asks "inside this
+ * diff, did the spec precede the build?" — only decidable within the PR. The board asks "where does
+ * this initiative stand?", which the PR range cannot answer at all: on a branch level with `main`
+ * the range is EMPTY, so every initiative reported `no implementation commits in this range` and
+ * collapsed to stage `spec`. A delivered initiative rendered identically to one never started.
+ *
+ * Splitting them means a rule can read `done` on the board and still be evaluated inside the gate.
+ * That is intended and is stated in the board's own footer, so it never reads as a discrepancy.
+ */
+function historyRange(root) {
+  const trunk = ['origin/main', 'main', 'origin/master', 'master']
+    .find((c) => git(root, ['rev-parse', '--verify', '--quiet', c]));
+  return buildRange(root, { spec: trunk || 'HEAD', whole: true });
+}
+
+/*
+ * ONE pass over the range, not one git call per question.
+ *
+ * Two `git log` invocations build every index the ladder needs: which paths each commit CHANGED
+ * (for buildCommits) and where each path was ADDED (for firstAppearance). Previously firstAppearance
+ * shelled out once per path per initiative and buildCommits ran `git show` once per commit per
+ * initiative — 330+ processes for the board on an empty range (23 s), and O(commits × initiatives)
+ * on a full one, which is what made full history look impossible rather than merely unimplemented.
+ */
+function buildRange(root, { spec, whole }) {
+  if ((git(root, ['rev-parse', '--is-shallow-repository']) || '').trim() === 'true') {
+    return { ok: false, reason: 'shallow clone — no history to order commits by (CI needs fetch-depth: 0)' };
+  }
+  let base = null;
+  let range = spec;
+  if (!range) {
+    const candidates = [];
+    if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
+    candidates.push('origin/main', 'main', 'origin/master', 'master');
+    for (const c of candidates) {
+      if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
+      const mb = git(root, ['merge-base', c, 'HEAD']);
+      if (mb && mb.trim()) { base = mb.trim(); break; }
+    }
+    range = base ? `${base}..HEAD` : 'HEAD';
+  }
+  // %x1e separates commits; %x1f separates the header from the message and the message from
+  // --name-only's file list. The MESSAGE is captured in this same pass because attribution over the
+  // trunk needs it (R-2) — a second `git log` per initiative is exactly the O(commits × initiatives)
+  // cost this single-pass rewrite existed to remove.
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct%x1f%s %b%x1f', '--name-only', range]);
+  if (log == null) return { ok: false, reason: 'git history unreadable' };
+
+  const shas = [];
+  const changed = [];                 // index -> string[] of paths touched
+  const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  const subjects = [];                // index -> subject + body, one line, for attribution
+  for (const chunk of log.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const parts = chunk.split('\x1f');
+    const head = (parts[0] || '').trim();
+    const [sha, ct] = head.split(/\s+/);
+    if (!sha) continue;
+    shas.push(sha);
+    dates.push(Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null);
+    subjects.push(String(parts[1] || '').replace(/\s+/g, ' ').trim());
+    changed.push(String(parts[2] || '').split('\n').map((s) => s.trim()).filter(Boolean));
+  }
+  const index = new Map();
+  shas.forEach((sha, i) => index.set(sha, i));
+
+  // Where each path was ADDED, as an index into the same range. `--diff-filter=A` in one pass.
+  const added = new Map();
+  const addLog = git(root, ['log', '--reverse', '--format=%x1e%H', '--diff-filter=A', '--name-only', range]);
+  if (addLog != null) {
+    for (const chunk of addLog.split('\x1e')) {
+      if (!chunk.trim()) continue;
+      const lines = chunk.split('\n');
+      const sha = (lines.shift() || '').trim();
+      const at = index.has(sha) ? index.get(sha) : null;
+      if (at == null) continue;
+      for (const f of lines.map((s) => s.trim()).filter(Boolean)) {
+        if (!added.has(f)) added.set(f, at);
+      }
+    }
+  }
+  return { ok: true, base, index, shas, changed, dates, subjects, added, wholeHistory: whole ? true : !base };
+}
+
+/*
+ * Where a path FIRST APPEARED, as an index into the range.
+ *   -1         it already existed before the range began
+ *   0..n       the position of the commit that added it
+ *   Infinity   it exists on disk but no commit has added it yet (uncommitted)
+ *   undefined  it exists, but its position is unknowable (no usable history)
+ *   null       it does not exist at all
+ *
+ * `undefined` and `-1` are kept apart on purpose. "Already existed" is a fact that satisfies an
+ * ordering rule; "I cannot tell" is not, and collapsing the second into the first is exactly how a
+ * shallow clone would turn every order check into a silent pass.
+ */
+function firstAppearance(root, range, rel) {
+  const onDisk = fs.existsSync(path.join(root, rel));
+  if (!range.ok) return onDisk ? undefined : null;
+  // The single-pass index answers first, and over the whole trunk it answers everything that has
+  // ever been committed — so the fallback below only runs for a PR range, where "added before the
+  // range" and "never committed" are genuinely different answers and only git can tell them apart.
+  if (range.added && range.added.has(rel)) return range.added.get(rel);
+  const log = git(root, ['log', '--diff-filter=A', '--reverse', '--format=%H', '--', rel]);
+  const sha = log ? log.split('\n').map((s) => s.trim()).filter(Boolean)[0] : null;
+  if (!sha) return onDisk ? Infinity : null;
+  return range.index.has(sha) ? range.index.get(sha) : -1;
+}
+
+/*
+ * The earliest position in the range at which this initiative's implementation was touched, plus a
+ * count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
+ * reported as n/a rather than as a pass it did not earn.
+ *
+ * ATTRIBUTION (R-2). This function used to take no id, so it answered a question about the RANGE
+ * while both of its callers asked one about an INITIATIVE. Which of those is right depends entirely
+ * on what the range is, and the two cases are answered differently on purpose:
+ *
+ *   · A PULL-REQUEST RANGE (`base..HEAD`) — the range IS this initiative's work, by the branch
+ *     convention the Initiative Gate already enforces. Any build commit in it is therefore this
+ *     initiative's build commit, and the O1/O2 order rules depend on exactly that reading. This path
+ *     is UNCHANGED, deliberately: the gate's verdicts must not move for a reporting fix.
+ *
+ *   · THE WHOLE TRUNK (`range.wholeHistory`) — the range is everyone's work. Attribution comes from
+ *     `delivery-index`: a merged `initiative/<id>` branch, or a commit that names the id and touches
+ *     a build path. Without it every initiative reported `done` with the identical count, which is
+ *     the tell that a per-initiative fact was being read from a repository-wide one.
+ *
+ * `signal` travels back with the answer so the rung can say WHICH evidence decided it. A bare count
+ * is what let 488 stand as an explanation for 177 different initiatives.
+ */
+function buildCommits(root, range, lane, opts) {
+  if (!range.ok) return { unknown: true };
+  const id = opts && opts.id;
+  const whole = !!range.wholeHistory;
+
+  // Over the trunk, the id must be attributable before any commit counts. The index is built once
+  // per trunk head by the shared reader and passed in by the board; a caller that did not supply one
+  // gets it built here (single-ladder invocations, where one extra `git log` is the whole cost).
+  let signal = null;
+  let declared = null;
+  if (whole && id) {
+    // The PM's declaration is consulted FIRST, and its failure is reported before anything else
+    // (R-2b). A `delivered_by` that does not check out must not be able to hide behind a convention
+    // signal that happens to succeed: a broken declaration is a defect in the record either way, and
+    // silently ignoring it would leave a false pointer sitting in the file forever.
+    declared = delivery.declaredDelivery(root, opts && opts.declaredDelivery);
+    if (declared && declared.declared && !declared.ok) {
+      return { unknown: false, failedDeclaration: declared, first: null, count: 0, sample: null, signal: null, attributed: true };
+    }
+    const index = (opts && opts.deliveryIndex) || delivery.deliveryIndex(root, listInitiatives(root));
+    signal = delivery.attribution(index, id);
+    if (declared && declared.ok) {
+      // A verified declaration attributes the work regardless of what the conventions found. It is
+      // the PM naming the commit, checked against git — strictly better evidence than a heuristic.
+      return { first: null, count: 0, sample: null, signal: 'declared', declaredSha: declared.sha, attributed: true, mergedOnly: true };
+    }
+    if (signal === 'unknown') return { unknown: true, reason: delivery.attributionEvidence('unknown', id) };
+    if (!signal) return { first: null, count: 0, sample: null, signal: null, attributed: true };
+  }
+
+  let first = null; let count = 0; let sample = null;
+  for (let i = 0; i < range.shas.length; i++) {
+    // range.changed came from the range's own single pass; the per-commit `git show` this replaced
+    // ran once per commit PER INITIATIVE, which is why the board took 23 s before it read anything.
+    const files = (range.changed && range.changed[i]) || [];
+    const hit = files.find((f) => isBuildPath(f, lane));
+    if (!hit) continue;
+    // Over the trunk, only commits that carry the id themselves are this initiative's. The branch
+    // signal is a MERGE subject, so the merge commit is the one that names it — which makes the
+    // merge position the honest "when did this land", and keeps a squashed or rebased history
+    // answerable at all. `--name-only` lists no files for a true merge commit, so a branch-attributed
+    // initiative is counted from its merge subject below rather than from this per-file loop.
+    if (whole && id && !commitNamesId(range, i, id)) continue;
+    count++;
+    if (first === null) { first = i; sample = hit; }
+  }
+  if (whole && id && signal === 'branch' && first === null) {
+    // The branch merged and every commit it carried was written on the branch, so no trunk commit
+    // subject names the id. The merge itself is the evidence, and saying "0 commits" over a merged
+    // branch would be the under-claim in a new place.
+    return { first: null, count: 0, sample: null, signal, attributed: true, mergedOnly: true };
+  }
+  return { first, count, sample, signal, attributed: whole && !!id };
+}
+
+// Whether the commit at `i` names this initiative in its own subject or body. The subjects come from
+// the range's own single pass, so this costs nothing per initiative.
+function commitNamesId(range, i, id) {
+  const msg = (range.subjects && range.subjects[i]) || '';
+  return msg.includes(id);
+}
+
+// ── Declaration readers ────────────────────────────────────────────────────────────────────────
+// Both keys are a LEADING TOKEN from a closed set followed by free prose. The token is what the gate
+// reads; the prose is the agent's reasoning for the PM. Closed-enum-only was rejected: D60's 2026-07-24
+// amendment widened the lane past UI work precisely because the interesting part is the reasoning.
+function specimenRoute(v) {
+  const t = String(v || '').trim().toLowerCase();
+  if (!t) return 'undeclared';
+  if (t.startsWith('needs-instance')) return 'instance';
+  if (t.startsWith('description-judgeable')) return 'description';
+  return 'malformed';
+}
+// The `priors` citation on a run record — the episodic read AGENTS.md step 3 mandates, written down.
+// Two shapes are accepted deliberately: the bare list (`priors: ["run-a"]`) for the common case, and
+// the object form (`priors: {consulted: [...], note: "…"}`) when the run needs to say WHY it consulted
+// nothing. Anything else returns `malformed` rather than falling through to "absent" — a field that is
+// present but unreadable must never be scored the same as a field nobody wrote, because the two call
+// for opposite fixes.
+function priorsCitation(run) {
+  if (!run || !('priors' in run) || run.priors === null) return { declared: false };
+  const p = run.priors;
+  if (Array.isArray(p)) return { declared: true, consulted: p.map((x) => String(x).trim()), note: '' };
+  if (typeof p === 'object') {
+    if (!('consulted' in p)) return { declared: true, malformed: 'priors object has no `consulted` key' };
+    if (!Array.isArray(p.consulted)) return { declared: true, malformed: '`priors.consulted` is not a list of run ids' };
+    return {
+      declared: true,
+      consulted: p.consulted.map((x) => String(x).trim()),
+      note: String(p.note == null ? '' : p.note).trim(),
+    };
+  }
+  return { declared: true, malformed: 'priors is neither a list of run ids nor {consulted, note}' };
+}
+
+function surfaceRoute(v) {
+  const t = String(v || '').trim().toLowerCase();
+  if (!t) return 'undeclared';
+  if (t.startsWith('existing')) return 'existing';
+  if (t.startsWith('greenfield')) return 'greenfield';
+  return 'malformed';
+}
+
+// ── Step model ─────────────────────────────────────────────────────────────────────────────────
+// status ∈ done | current | blocked | pending | na | unknown
+// `blocking` marks a step whose failure fails CI. O5/O6/O7 are deliberately NOT blocking: none can
+// be true before the diff exists, and a rule enforced at a moment it cannot be satisfied only
+// teaches people to reach for the escape hatch.
+function step(key, label, status, evidence, next, opts) {
+  return {
+    key, label, status, evidence: evidence || null, next: next || null,
+    blocking: !!(opts && opts.blocking), rule: (opts && opts.rule) || null,
+  };
+}
+
+function computeWorkflow(id, opts) {
+  const root = path.resolve((opts && opts.root) || process.cwd());
+  const L = layout(root);
+  const recRel = path.relative(root, path.join(L.initiatives, `${id}.md`));
+  const recAbs = path.join(L.initiatives, `${id}.md`);
+  if (!fs.existsSync(recAbs)) {
+    return { ok: false, id, error: `no initiative record at ${recRel} — an initiative must exist before its work` };
+  }
+  const fm = readFrontmatter(recAbs) || {};
+  const lane = (fm.lane || 'feature').trim() || 'feature';
+  const knownLane = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'].includes(lane);
+  const effLane = knownLane ? lane : 'feature';           // unknown lane = strictest, as the bash gate does
+  const range = (opts && opts.range) || commitRange(root);
+  // See ENFORCED_FROM: git decides, the frontmatter only breaks a tie git cannot see.
+  //
+  // `recIdx === -1` — "the record predates this range" — is the right test for a PR range and a
+  // MEANINGLESS one over the whole trunk, where nothing predates the range and every legacy record
+  // would suddenly be enforced. So the commit DATE decides whenever the range can supply it, and
+  // -1 keeps its meaning for the gate's range. Same question, asked of evidence that survives both.
+  const recIdx = firstAppearance(root, range, recRel);
+  const recAt = (range.dates && typeof recIdx === 'number' && recIdx >= 0) ? range.dates[recIdx] : null;
+  /*
+   * `reconstructed_from` — the merge date of work whose record was written afterwards.
+   *
+   * A record backfilled today for a PR that merged in June has TODAY's commit date, so the date
+   * test would enforce today's rules on work that predates them and report a violation nobody
+   * could ever have avoided. The declared merge date decides instead.
+   *
+   * This is not an escape hatch: it must name a date, that date is checkable against the merge it
+   * claims, and declaring one AFTER `ENFORCED_FROM` makes the record non-legacy — so work that
+   * genuinely skipped the loop still reports blocked, which is the point of writing it down.
+   */
+  const recon = String(fm.reconstructed_from || '').trim().slice(0, 10);
+  const legacy = recIdx === -1 ? true
+    : /^\d{4}-\d{2}-\d{2}$/.test(recon) ? recon < ENFORCED_FROM
+      : recAt ? new Date(recAt * 1000).toISOString().slice(0, 10) < ENFORCED_FROM
+        : String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM;   // fallback — see ENFORCED_FROM
+  /*
+   * `legacy` answers the ENFORCEMENT question — should this PR fail? It is NOT the visibility
+   * question. Filtering the board by it was a real bug: on `main`, every record is legacy, so the
+   * board and the workspace panel both read "0 in flight" against 93 initiatives — the surface was
+   * blank at exactly the moment someone opens it to ask where they are.
+   *
+   * The two axes below are what the board actually orders by. `inChange` is precise (git says so);
+   * `lastActivity` is the honest fallback for everything else, because "when was this last worked
+   * on" is a fact the repo already holds and nobody has to maintain.
+   */
+  // `● in this change` must keep meaning "the diff under review touches this". Over the whole trunk
+  // that is true of everything, which makes the marker noise — so the board passes the GATE's range
+  // separately and the marker is answered from that, or dropped when there is no such range.
+  const changeRange = (opts && opts.changeRange) || (range.wholeHistory ? null : range);
+  const chgIdx = changeRange ? firstAppearance(root, changeRange, recRel) : null;
+  const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
+  const lastActivity = (() => {
+    const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
+    const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
+    const t = out && parseInt(out.trim(), 10);
+    return Number.isFinite(t) ? t : null;
+  })();
+  const steps = [];
+
+  // ── route ─ the lane is chosen and the two intake questions are answered ─────────────────────
+  const sRoute = specimenRoute(fm.specimen_test);
+  const fRoute = surfaceRoute(fm.surface_check);
+  {
+    const missing = [];
+    if (sRoute === 'undeclared' || sRoute === 'malformed') missing.push('specimen_test');
+    if (fRoute === 'undeclared' || fRoute === 'malformed') missing.push('surface_check');
+    if (!missing.length) {
+      steps.push(step('route', 'route', 'done',
+        `${lane} lane · specimen test ${sRoute} · surface ${fRoute}`));
+    } else if (legacy) {
+      steps.push(step('route', 'route', 'unknown',
+        `${lane} lane · ${missing.join(' + ')} not declared (record predates ${ENFORCED_FROM})`));
+    } else {
+      const how = missing.map((k) => k === 'specimen_test'
+        ? 'specimen_test: "description-judgeable — …" or "needs-instance — …"'
+        : 'surface_check: "greenfield — …" or "existing — …"').join('; ');
+      steps.push(step('route', 'route', 'blocked',
+        `${missing.join(' + ')} ${missing.length > 1 ? 'are' : 'is'} ${sRoute === 'malformed' || fRoute === 'malformed' ? 'malformed' : 'not declared'}`,
+        `run the pmos-router skill and record its answers in ${recRel} — ${how}`,
+        { blocking: true, rule: 'R0' }));
+    }
+  }
+
+  // ── anchor ─ every initiative anchors to a KR or a declared health budget (D59) ──────────────
+  {
+    const anchor = String(fm.parent_kr || '').trim();
+    const r = anchors.resolveAnchor(anchor, okrIndexFor(root), budgetsFor(root, L));
+    const budRel = path.relative(root, L.budgets);
+    if (r.kind === 'empty') {
+      steps.push(step('anchor', 'anchor', legacy ? 'unknown' : 'blocked',
+        'parent_kr is empty — unanchored work is rejected (D59)',
+        `set parent_kr in ${recRel} to a KR, or to health:<id> from ${budRel}`,
+        { blocking: !legacy, rule: 'R1' }));
+    } else if (r.status === 'unknown') {
+      steps.push(step('anchor', 'anchor', 'unknown', `${anchor} — ${r.reason}`));
+    } else if (r.kind === 'health') {
+      if (r.status === 'resolved') {
+        steps.push(step('anchor', 'anchor', 'done', `health:${r.budget} — declared in ${budRel}`));
+      } else {
+        steps.push(step('anchor', 'anchor', legacy ? 'unknown' : 'blocked',
+          `health:${r.budget} is not a declared budget`,
+          `only the PM adds a budget — use an existing id from ${budRel} or anchor to a KR`,
+          { blocking: !legacy, rule: 'R1' }));
+      }
+    } else if (r.status === 'resolved') {
+      steps.push(step('anchor', 'anchor', 'done',
+        `${anchors.canonical(r, (okrIndexFor(root) || {}).period) || anchor} — ${r.reason}`));
+    } else {
+      // REPORTED, NEVER CI-BLOCKING (spec assumption A1). The anchor names an objective or KR the
+      // OKR documents do not declare — which is exactly the class that went unnoticed for two days
+      // (`q3-2026:integrity:kr-a` and `:kr-b` were anchored by three initiatives and written in no
+      // file). It is shown as a failed step so it cannot hide, and deliberately does NOT fail CI:
+      // making it blocking would turn one typo into a hard failure on every unrelated PR, and the
+      // recorded intent put the RED in the surface, not the gate. Raising it to blocking is a
+      // separate PM decision (spec Open questions), not a thing to slip in with a resolver.
+      steps.push(step('anchor', 'anchor', 'blocked',
+        `${anchor} — ${r.reason}`,
+        `write an anchor that names something the OKR documents declare, or add the KR (a PM act) — see ${budRel} for the health form`,
+        { blocking: false, rule: 'R1' }));
+    }
+  }
+
+  const prd = String(fm.prd_path || '').trim();
+  const rubric = String(fm.rubric_path || '').trim();
+  const prdIdx = prd ? firstAppearance(root, range, prd) : null;
+  const build = buildCommits(root, range, effLane, {
+    id,
+    deliveryIndex: opts && opts.deliveryIndex,
+    declaredDelivery: fm.delivered_by,
+  });
+
+  // Shared helper: "A must not come after B", stated as positions, never as clock time.
+  function ordered(aIdx, bIdx) {
+    // null = absent (a different step's problem); undefined = position unknowable. Neither is a pass.
+    if (aIdx == null || bIdx == null) return null;
+    return aIdx <= bIdx;
+  }
+
+  // ── prototype ─ O3: a "needs-instance" answer obliges a prototype BEFORE the PRD (D60) ───────
+  {
+    const pred = String(fm.predecessor || '').trim();
+    // The lane is part of the question, not just the answer. O3 asks "does a lookable instance have
+    // to precede this spec?" — and for a PROTOTYPE-lane record the instance IS what this record
+    // produces (D60). Demanding a predecessor of the leg that answers the specimen test is not
+    // merely wrong, it is unsatisfiable: a prototype leg has no leg before it. The file already
+    // holds this same fact twice — `isBuildPath` (:93) and the `review` step both read
+    // `lane === 'prototype'` — so this is the third place, not a new idea.
+    // The other three O3 branches are untouched: a FEATURE record still owes its prototype, named,
+    // of the right lane, and briefed before its PRD.
+    if (sRoute !== 'instance' || effLane === 'prototype') {
+      steps.push(step('prototype', 'prototype', 'na',
+        effLane === 'prototype'
+          ? 'prototype lane — this record IS the leg the specimen test asks for (D60), so nothing precedes it'
+          : sRoute === 'description' ? 'specimen test says description-judgeable — routed straight to spec, untaxed'
+            : 'specimen test not declared'));
+    } else if (!pred) {
+      steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+        'specimen_test says needs-instance but no predecessor is named',
+        'run the prototype lane first (skills/core/prototype.skill), then set predecessor: <prototype-id>',
+        { blocking: !legacy, rule: 'O3' }));
+    } else {
+      const predAbs = path.join(L.initiatives, `${pred}.md`);
+      const predFm = readFrontmatter(predAbs);
+      if (!predFm) {
+        steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+          `predecessor '${pred}' has no initiative record at ${path.relative(root, predAbs)}`,
+          'name a prototype-lane initiative that exists, or correct predecessor:',
+          { blocking: !legacy, rule: 'O3' }));
+      } else if ((predFm.lane || '').trim() !== 'prototype') {
+        steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+          `predecessor '${pred}' is lane '${predFm.lane || 'feature'}', not prototype`,
+          'the specimen test is answered by a prototype leg — point predecessor: at one',
+          { blocking: !legacy, rule: 'O3' }));
+      } else {
+        const brief = String(predFm.prd_path || '').trim();
+        const briefIdx = brief ? firstAppearance(root, range, brief) : null;
+        const ok = ordered(briefIdx, prdIdx);
+        if (ok === null) {
+          steps.push(step('prototype', 'prototype', 'unknown',
+            `predecessor ${pred} present; order undecidable (${range.ok ? 'a path is missing' : range.reason})`));
+        } else if (ok) {
+          steps.push(step('prototype', 'prototype', 'done', `${pred} — brief ${brief} first-appeared before ${prd}`));
+        } else {
+          steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+            `ORDER VIOLATION — the PRD (${prd}) first-appeared BEFORE the prototype brief (${brief})`,
+            'the prototype is what validates the direction the PRD then specifies — it cannot follow it (D60)',
+            { blocking: !legacy, rule: 'O3' }));
+        }
+      }
+    }
+  }
+
+  // ── understand ─ O4: an existing surface is explained BEFORE it is specified ─────────────────
+  {
+    const expl = String(fm.explainer_path || '').trim();
+    if (fRoute !== 'existing') {
+      steps.push(step('understand', 'understand', 'na',
+        fRoute === 'greenfield' ? 'greenfield — nothing existing to explain first' : 'surface check not declared'));
+    } else if (!expl) {
+      steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+        'surface_check says existing but no explainer_path is set',
+        'run build-skills/explain-surface.skill in a FRESH context (not the agent that will write the spec), then set explainer_path:',
+        { blocking: !legacy, rule: 'O4' }));
+    } else if (!fs.existsSync(path.join(root, expl))) {
+      steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+        `explainer_path '${expl}' does not exist in the repo`,
+        'set explainer_path to a real explain-surface output',
+        { blocking: !legacy, rule: 'O4' }));
+    } else {
+      const eIdx = firstAppearance(root, range, expl);
+      const ok = ordered(eIdx, prdIdx);
+      if (ok === null) {
+        steps.push(step('understand', 'understand', 'unknown',
+          `${expl} present; order undecidable (${range.ok ? 'no spec artifact to order against' : range.reason})`));
+      } else if (ok) {
+        steps.push(step('understand', 'understand', 'done', `${expl} — first-appeared before ${prd}`));
+      } else {
+        steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+          `ORDER VIOLATION — the spec (${prd}) first-appeared BEFORE the explainer (${expl})`,
+          'without the pass first, the AGENT acquires the understanding and the PM approves a spec built on facts they never saw',
+          { blocking: !legacy, rule: 'O4' }));
+      }
+    }
+  }
+
+  // ── spec ─ the lane's artifacts, and O1/O2: they precede the build ───────────────────────────
+  const needsRubric = effLane === 'feature';
+  {
+    const wants = {
+      feature: 'a PRD', discovery: 'a spike brief', incident: 'an incident record',
+      content: 'a content brief', prototype: 'a quick prototype brief',
+    }[effLane];
+    if (effLane === 'chore') {
+      const intent = String(fm.status || '').trim();
+      steps.push(intent
+        ? step('spec', 'spec', 'done', 'chore lane — intent stated in the record\'s status')
+        : step('spec', 'spec', 'blocked', 'chore lane requires a one-paragraph intent in status:',
+          `write the intent in ${recRel} — anchor-free trivia takes the no-initiative label instead`,
+          { blocking: true, rule: 'R2' }));
+    } else if (!prd) {
+      steps.push(step('spec', 'spec', 'blocked', `no prd_path — the ${effLane} lane needs ${wants}`,
+        effLane === 'feature'
+          ? 'author the PRD (skills/core/prd.skill) and the rubric alongside it (D13), then set prd_path + rubric_path'
+          : `author ${wants} and set prd_path in ${recRel}`,
+        { blocking: true, rule: 'R2' }));
+    } else if (prdIdx === null) {
+      steps.push(step('spec', 'spec', 'blocked', `prd_path '${prd}' does not exist in the repo`,
+        'create the file the record points at, or correct prd_path',
+        { blocking: true, rule: 'R2' }));
+    } else if (needsRubric && !rubric) {
+      steps.push(step('spec', 'spec', 'blocked', 'no rubric_path — the feature lane writes the eval before the build (D13)',
+        'author the rubric (skills/core/eval-rubric.skill) and set rubric_path',
+        { blocking: true, rule: 'R2' }));
+    } else if (rubric && !fs.existsSync(path.join(root, rubric))) {
+      steps.push(step('spec', 'spec', 'blocked', `rubric_path '${rubric}' does not exist in the repo`,
+        'optional never means dangling — point rubric_path at a real file or clear it',
+        { blocking: true, rule: 'R2' }));
+    } else {
+      // Artifacts are present. Now the order rules the old gate could not see.
+      const rubricIdx = rubric ? firstAppearance(root, range, rubric) : null;
+      const specIdx = rubricIdx == null ? prdIdx : Math.max(prdIdx, rubricIdx);
+      const specNames = rubric ? `${prd} + ${rubric}` : prd;
+      if (specIdx === undefined || (rubricIdx === undefined)) {
+        steps.push(step('spec', 'spec', 'unknown', `${specNames} present — order vs the build undecidable (${range.reason || 'no usable history'})`));
+      } else if (build.unknown) {
+        steps.push(step('spec', 'spec', 'unknown', `${specNames} present — order vs the build undecidable (${range.reason})`));
+      } else if (build.first === null) {
+        steps.push(step('spec', 'spec', 'done', `${specNames} present — no implementation commits in this range, so nothing can precede them`));
+      } else if (specIdx <= build.first) {
+        steps.push(step('spec', 'spec', 'done', `${specNames} — first-appeared at or before the first build commit`));
+      } else {
+        const late = rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? rubric : prd;
+        // `legacy` applies here exactly as it does to O4. It always should have — the rule simply
+        // never fired for a legacy record while the board shared the gate's PR range, because an
+        // empty range has no build commit to be out of order with. Reading the trunk exposed it:
+        // 81 records that predate enforcement were suddenly failing a rule written after them.
+        steps.push(step('spec', 'spec', legacy ? 'unknown' : 'blocked',
+          `ORDER VIOLATION — implementation (${build.sample}) was committed BEFORE ${late} first appeared`,
+          'the rubric is the spec (D13). Land the spec artifacts in an earlier commit than the build, or split this PR so the spec lands first',
+          { blocking: !legacy, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
+      }
+    }
+  }
+
+  const runs = readJsonl(path.join(L.runsDir, L.runsFile)).filter((r) => r && r.initiative_id === id);
+  const runsRel = path.relative(root, path.join(L.runsDir, L.runsFile));
+
+  // ── priors ─ O7: the episodic read is CITED, and the citation is checked ─────────────────────
+  // AGENTS.md step 3 mandates reading this initiative's earlier runs BEFORE acting — the one kernel
+  // invariant that was still asserted only in prose. Nothing can derive that a file was READ, and
+  // this rule does not pretend to: what it derives is the three things that ARE decidable from the
+  // record, and together they are what separates it from a checkbox.
+  //   1. whether earlier runs existed at all      — the rule is vacuous on a first run, and says so
+  //   2. whether the run declared what it consulted
+  //   3. whether the ids it named are REAL and actually EARLIER
+  // (3) is the part that matters. O5's `PM_approved: true` is a bare boolean, satisfiable by typing
+  // it; a fabricated `priors` list fails against the corpus it claims to have read. The rule is
+  // NON-BLOCKING for the same reason O5/O6 are: it cannot be true before a run exists, and a rule
+  // enforced at a moment it cannot be satisfied only teaches people to reach for the escape hatch.
+  {
+    const latest = runs.length ? runs[runs.length - 1] : null;
+    const earlier = runs.slice(0, -1);
+    const cite = priorsCitation(latest);
+    const how = `consult this initiative's earlier runs BEFORE acting (AGENTS.md step 3) and cite them as \`priors\` on the run in ${runsRel}`;
+    if (!latest) {
+      steps.push(step('priors', 'priors', 'pending', 'no run logged for this initiative yet', how, { rule: 'O7' }));
+    } else if (!earlier.length) {
+      // Not a pass — there was nothing to pass. A tick here would be the watermelon this engine exists to prevent.
+      steps.push(step('priors', 'priors', 'na',
+        `${latest.run_id} is the first run on this initiative — no priors to consult`));
+    } else if (cite.malformed) {
+      steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+        `${latest.run_id} has a malformed priors citation — ${cite.malformed}`,
+        `use \`priors: ["<run_id>", …]\` or \`priors: {consulted: [...], note: "…"}\` in ${runsRel}`,
+        { rule: 'O7' }));
+    } else if (!cite.declared) {
+      steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+        `${latest.run_id} follows ${earlier.length} earlier run(s) on this initiative and cites no priors`,
+        how, { rule: 'O7' }));
+    } else {
+      const byId = new Map(runs.map((r) => [String(r.run_id), r]));
+      const earlierIds = new Set(earlier.map((r) => String(r.run_id)));
+      const missing = cite.consulted.filter((x) => !byId.has(x));
+      const notEarlier = cite.consulted.filter((x) => byId.has(x) && !earlierIds.has(x));
+      if (missing.length) {
+        // The check a declared field would otherwise never get. A citation naming a run that does not
+        // exist reports a read that cannot have happened — worse than an absent citation, because it
+        // reads as compliance on the board.
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} cites prior run(s) that do not exist on this initiative: ${missing.join(', ')}`,
+          `cite run_ids that are actually in ${runsRel} — a citation naming nothing reports a read that cannot have happened`,
+          { rule: 'O7' }));
+      } else if (notEarlier.length) {
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} cites ${notEarlier.join(', ')}, which ${notEarlier.length > 1 ? 'are' : 'is'} not EARLIER than it`,
+          'a run cannot consult itself or a run that came after it — cite only runs logged before this one',
+          { rule: 'O7' }));
+      } else if (!cite.consulted.length && !cite.note) {
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} declares an empty priors list with no note, over ${earlier.length} earlier run(s)`,
+          'an empty list with no reason is indistinguishable from not looking — say which priors were read, or say in `note` why none applied',
+          { rule: 'O7' }));
+      } else if (!cite.consulted.length) {
+        // Allowed, and deliberately not silent: the machine cannot judge whether the priors were
+        // genuinely irrelevant, so it surfaces the claim verbatim for the PM instead of ticking.
+        steps.push(step('priors', 'priors', 'done',
+          `${latest.run_id} consulted none of ${earlier.length} earlier run(s) — declared irrelevant: ${cite.note}`));
+      } else {
+        steps.push(step('priors', 'priors', 'done',
+          `${latest.run_id} cites ${cite.consulted.length} prior run(s): ${cite.consulted.join(', ')}${cite.note ? ` — ${cite.note}` : ''}`));
+      }
+    }
+  }
+
+  // ── contract ─ O5: PM-approved done-criteria before the build. Reported, never CI-blocking ────
+  const approved = runs.find((r) => r.pre_run_contract && r.pre_run_contract.PM_approved === true);
+  {
+    if (approved) {
+      steps.push(step('contract', 'contract', 'done',
+        `PM-approved pre_run_contract on run ${approved.run_id}${approved.pre_run_contract.approved_by ? ` (by ${approved.pre_run_contract.approved_by})` : ''}`));
+    } else if (runs.length) {
+      steps.push(step('contract', 'contract', legacy ? 'pending' : 'blocked',
+        `${runs.length} run(s) logged, none with pre_run_contract.PM_approved: true`,
+        `agree numbered done_criteria + test_method with the PM and record the approval in ${runsRel}`,
+        { rule: 'O5' }));
+    } else {
+      steps.push(step('contract', 'contract', 'pending',
+        'no run logged for this initiative yet',
+        `agree done_criteria + test_method BEFORE building and append the run to ${runsRel} with PM_approved: true`,
+        { rule: 'O5' }));
+    }
+  }
+
+  // ── build ────────────────────────────────────────────────────────────────────────────────────
+  /*
+   * The evidence names WHICH signal decided, never a bare count (R-2). `488 commit(s) on
+   * implementation paths` was true of the repository and said nothing about the initiative it was
+   * printed under — the identical number on every row was the tell.
+   *
+   * The three pending sentences below are deliberately different from each other. "No commit on the
+   * trunk is attributable to this initiative" is a statement about the INITIATIVE; "no implementation
+   * commits in this range" is a statement about the RANGE, and on a branch level with `main` that
+   * range is legitimately empty. A reader who cannot tell those apart calls the second one "never
+   * built", which is the console's half of this defect.
+   */
+  steps.push(build.unknown
+    ? step('build', 'build', 'unknown', build.reason || range.reason)
+    : build.failedDeclaration
+      // REPORTED, never CI-blocking — the same stance R1 takes on an unresolvable anchor. Making a
+      // record's own broken pointer fail every unrelated PR would turn one typo into a repo-wide
+      // outage; the RED belongs in the surface. `blocked` still closes the accept step below, which
+      // is where a false delivery claim actually needs to stop something.
+      ? step('build', 'build', 'blocked', build.failedDeclaration.reason,
+        `point delivered_by at a commit that is reachable from the trunk and changes a build path in ${recRel}, or remove the key — a declaration that fails its own check reads as evidence`,
+        { blocking: false, rule: 'R-2b' })
+      : build.mergedOnly
+        ? step('build', 'build', 'done',
+          delivery.attributionEvidence(build.signal || 'branch', id, build.declaredSha))
+        : build.first === null
+          ? step('build', 'build', 'pending', build.attributed
+            ? delivery.attributionEvidence(null, id)
+            : 'no implementation commits in this range')
+          : step('build', 'build', 'done', build.signal
+            ? `${build.count} commit(s) on implementation paths — ${delivery.attributionEvidence(build.signal, id, build.declaredSha)}`
+            : `${build.count} commit(s) on implementation paths`));
+
+  // ── quality ─ CI's verdict, never this engine's ──────────────────────────────────────────────
+  steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
+
+  // ── review ─ the Review Gate's verdict, where the lane has a rubric ──────────────────────────
+  const evals = readJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
+  {
+    if (effLane === 'chore' || effLane === 'prototype') {
+      steps.push(step('review', 'review', 'na', effLane === 'prototype'
+        ? 'leg A is grilled as dialogue, never scored (D60)'
+        : 'chore lane carries no rubric (D56)'));
+    } else if (evals.length) {
+      const last = evals[evals.length - 1];
+      steps.push(step('review', 'review', 'done',
+        `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`));
+    } else {
+      steps.push(step('review', 'review', 'pending', 'no Review-Gate verdict recorded',
+        'score the build against the rubric (build-skills/evaluator.skill), then append to evals.jsonl',
+        { rule: 'R3' }));
+    }
+  }
+
+  // ── explain ─ O6: the run is explained AFTER the build and BEFORE acceptance ─────────────────
+  {
+    let found = null;
+    for (const r of runs) {
+      const p = path.join(L.explainers, `${r.run_id}-explainer.md`);
+      if (fs.existsSync(p)) { found = path.relative(root, p); break; }
+    }
+    if (found) {
+      steps.push(step('explain', 'explain', 'done', found));
+    } else if (!runs.length) {
+      steps.push(step('explain', 'explain', 'pending', 'no run to explain yet',
+        'log the run first, then run build-skills/explain-run.skill against its diff', { rule: 'O6' }));
+    } else {
+      steps.push(step('explain', 'explain', legacy ? 'pending' : 'blocked',
+        `no explainer at ${path.relative(root, L.explainers)}/${runs[runs.length - 1].run_id}-explainer.md`,
+        'run build-skills/explain-run.skill — raw-transcript vigilance degrades within ~30 min, so the explainer is what the PM actually reviews',
+        { rule: 'O6' }));
+    }
+  }
+
+  // ── accept ─ the human PM, final and non-delegable (D12) ─────────────────────────────────────
+  const accepted = readJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
+    .filter((a) => a && a.initiative_id === id && a.accepted === true);
+  {
+    const blockers = steps.filter((s) => s.status === 'blocked').map((s) => s.key);
+    if (accepted.length) {
+      const last = accepted[accepted.length - 1];
+      steps.push(step('accept', 'accept', 'done', `accepted by ${last.pm || 'PM'}${last.at ? ` on ${String(last.at).slice(0, 10)}` : ''}`));
+    } else if (blockers.length) {
+      steps.push(step('accept', 'accept', 'blocked', `blocked by: ${blockers.join(', ')}`,
+        'the Acceptance Gate is the PM\'s (D12) — but it does not open over an unfinished ladder'));
+    } else {
+      steps.push(step('accept', 'accept', 'pending', 'PM Acceptance Gate open — non-delegable (D12)',
+        'the PM names one thing verified BY HAND in the acceptance note, then appends to acceptances.jsonl'));
+    }
+  }
+
+  // ── stage, derived from what the steps found ─────────────────────────────────────────────────
+  const by = Object.fromEntries(steps.map((s) => [s.key, s]));
+  let stage = 'intake';
+  if (by.spec.status === 'done') stage = 'spec';
+  if (by.contract.status === 'done') stage = 'contract';
+  if (by.build.status === 'done') stage = 'build';
+  if (evals.length || runs.length) stage = 'eval';
+  if (accepted.length) stage = 'accepted';
+
+  const blockers = steps.filter((s) => s.status === 'blocked');
+  const gateFailures = blockers.filter((s) => s.blocking);
+  const next = steps.find((s) => s.status === 'blocked')
+    || steps.find((s) => s.status === 'pending' && s.next)
+    || null;
+
+  return {
+    ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
+    last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
+    title: fm.title || id, anchor: fm.parent_kr || null,
+    steps, blockers: blockers.map((s) => s.key), gate_failures: gateFailures.map((s) => s.rule || s.key),
+    next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
+    range: range.ok ? { base: range.base, commits: range.shas.length, whole_history: !!range.wholeHistory } : { error: range.reason },
+    enforced_from: ENFORCED_FROM,
+  };
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────────────────────────────
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const GLYPH = {
+  done: ['✓', 32], current: ['●', 36], blocked: ['✗', 31],
+  pending: ['·', 90], na: ['─', 90], unknown: ['?', 33],
+};
+function mark(status) {
+  const [g, col] = GLYPH[status] || ['?', 33];
+  return c(col, g);
+}
+// Record prose is deliberately long — the reasoning is for the PM to read in the record, not to
+// wrap a terminal. The ladder shows the declaration, then stops.
+function brief(s, n) {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+function renderLadder(w) {
+  if (!w.ok) return c(31, `✗ ${w.error}`);
+  const out = [];
+  const head = `${c(1, w.id)} · ${w.lane}${w.laneKnown ? '' : c(33, ' (unknown lane — enforcing feature)')} · ${w.anchor ? brief(w.anchor, 46) : c(31, 'unanchored')}`;
+  out.push('');
+  out.push(`  ${head}`);
+  out.push(`  ${c(90, 'stage')} ${c(1, w.stage)}${w.legacy ? c(33, `   legacy — record predates ${w.enforced_from}, order rules report but do not fail`) : ''}`);
+  out.push(`  ${c(90, '─'.repeat(78))}`);
+  for (const s of w.steps) {
+    const label = s.label.padEnd(11);
+    out.push(`  ${mark(s.status)} ${s.status === 'na' || s.status === 'pending' ? c(90, label) : label} ${brief(s.evidence, 110)}`);
+    if (s.next) out.push(`    ${c(90, '→')} ${c(s.status === 'blocked' ? 33 : 90, brief(s.next, 150))}`);
+  }
+  out.push('');
+  if (w.next) out.push(`  ${c(1, 'next:')} ${w.next.action}`);
+  else out.push(`  ${c(32, 'nothing blocking — the ladder is complete')}`);
+  if (w.range.error) out.push(`  ${c(33, `order checks degraded: ${w.range.error}`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+function renderBoard(rows, opts) {
+  const out = [''];
+  const acceptedN = rows.filter((r) => r.ok && r.accepted).length;
+  const { shown, hidden, total } = inFlight(rows, { cap: opts.all ? Infinity : BOARD_CAP });
+  const blocked = shown.filter((r) => r.ok && r.blockers.length).length;
+  // "Open" is stated as what it is DERIVED FROM — no recorded acceptance — not as "in flight". The
+  // difference matters here: this repo has 10 acceptances against 93 initiatives, so most of these
+  // are finished work whose acceptance was never logged. Calling that "in flight" would be the
+  // board inventing a fact; naming the gap is the board doing its job.
+  out.push(`  ${c(1, 'PMOS workflow board')} · ${total} without a recorded acceptance · ${blocked ? c(31, `${blocked} blocked`) : c(32, 'none blocked')}${acceptedN ? c(90, ` · ${acceptedN} accepted`) : ''}`);
+  out.push(`  ${c(90, 'most recently worked on first · ✗ blocked · ● in this change')}`);
+  out.push(`  ${c(90, '─'.repeat(78))}`);
+  if (!shown.length) { out.push(`  ${c(32, 'every initiative here has a recorded acceptance.')}`); out.push(''); return out.join('\n'); }
+  const w1 = Math.min(34, Math.max(...shown.map((r) => r.id.length), 4));
+  for (const r of shown) {
+    if (!r.ok) { out.push(`  ${c(31, '✗')} ${r.id.padEnd(w1)}  ${c(31, r.error)}`); continue; }
+    const status = r.blockers.length ? 'blocked' : r.in_change ? 'current' : 'pending';
+    // The board shows WHICH step and WHY in a few words; the full next action lives on the ladder,
+    // where there is room for it. Repeating a 90-character instruction on every row taught nothing.
+    const why = r.next ? `${r.next.step} — ${brief(r.next.why, 62)}` : 'nothing blocking';
+    const note = r.blockers.length ? c(31, why) : c(90, why);
+    const tag = r.in_change ? c(36, ' ·this change') : '';
+    out.push(`  ${mark(status)} ${r.id.padEnd(w1)}  ${r.lane.padEnd(9)} ${r.stage.padEnd(9)} ${note}${tag}`);
+  }
+  out.push('');
+  // Never a silent cap — a truncated list that does not say so reads as "that is everything".
+  if (hidden) out.push(`  ${c(33, `+ ${hidden} more without a recorded acceptance, not shown`)} ${c(90, `— node ${opts.self} --all`)}`);
+  // The two ranges, said out loud. The board reads the whole trunk so a delivered initiative does
+  // not render as unstarted; the gate reads the PR so "spec before build" stays decidable. A rule
+  // can therefore read done here and still be evaluated on the PR — intended, and not a discrepancy.
+  out.push(`  ${c(90, 'derived from the whole trunk history; the CI gate evaluates order within the PR only')}`);
+  out.push(`  ${c(90, `one initiative in detail:  node ${opts.self} <id>`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+/*
+ * What "in flight" means, in one place, so the CLI, the gate and the workspace panel cannot drift.
+ *
+ * NOT `!legacy` — that was the bug this replaced. Legacy is about whether a rule may fail a PR;
+ * being old has nothing to do with whether work is live. In flight = **not accepted**, ordered so
+ * the rows worth looking at come first:
+ *   1. anything blocked            — the reason you opened the surface
+ *   2. anything this change carries — precise, git says so
+ *   3. most recently worked on     — the honest fallback, and the repo already knows it
+ *
+ * The cap is REPORTED, never silent: a list quietly truncated to 12 reads as "that's everything",
+ * which is the same class of lie as a false green.
+ */
+const BOARD_CAP = 12;
+function inFlight(rows, opts) {
+  const cap = (opts && opts.cap) || BOARD_CAP;
+  const live = rows.filter((r) => !r.ok || !r.accepted);
+  const rank = (r) => (!r.ok ? 0 : r.blockers.length ? 1 : r.in_change ? 2 : 3);
+  const sorted = [...live].sort((a, b) =>
+    rank(a) - rank(b)
+    || (b.last_activity || 0) - (a.last_activity || 0)
+    || String(a.id).localeCompare(String(b.id)));
+  return { shown: sorted.slice(0, cap), hidden: Math.max(0, sorted.length - cap), total: sorted.length };
+}
+
+function listInitiatives(root) {
+  const L = layout(root);
+  try {
+    return fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && f !== 'README.md' && f !== 'index.md')
+      .map((f) => f.replace(/\.md$/, '')).sort();
+  } catch { return []; }
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────────────
+function main(argv) {
+  const args = argv.slice(2);
+  let root = process.cwd(); let json = false; let gate = false; let all = false;
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--root') { root = args[++i]; continue; }
+    if (a === '--json') { json = true; continue; }
+    if (a === '--gate') { gate = true; continue; }
+    if (a === '--all') { all = true; continue; }
+    if (a === '--open') { continue; }          // the board is in-flight-only by default now
+    if (a === '--help' || a === '-h') {
+      process.stdout.write([
+        '', '  node scripts/workflow-state.js [<initiative-id>] [--json] [--gate] [--all] [--root <dir>]', '',
+        '    (no id)        the board — what is in flight, blocked first, then this change, then recency',
+        '    <id>           the ladder for one initiative: where you are, what is next, what blocks',
+        '    --gate <id>    CI mode — exit 1 on a blocking order violation, with the next action',
+        '    --all          the board without the 12-row cap',
+        '    --json         machine-readable (what an agent reads at session start)', '',
+      ].join('\n') + '\n');
+      return 0;
+    }
+    rest.push(a);
+  }
+  const self = path.relative(root, __filename) || 'scripts/workflow-state.js';
+  const id = rest[0];
+
+  if (id) {
+    const w = computeWorkflow(id, { root });
+    if (json) { process.stdout.write(JSON.stringify(w, null, 2) + '\n'); }
+    else { process.stdout.write(renderLadder(w) + '\n'); }
+    if (!gate) return w.ok ? 0 : 1;
+
+    // ── gate mode ──────────────────────────────────────────────────────────────────────────────
+    if (!w.ok) { process.stdout.write(`::error::workflow-gate: ${w.error}\n`); return 1; }
+    const fails = w.steps.filter((s) => s.status === 'blocked' && s.blocking);
+    if (fails.length) {
+      for (const f of fails) {
+        process.stdout.write(`::error::workflow-gate [${f.rule || f.key}]: ${f.evidence}\n`);
+        process.stdout.write(`❌ ${f.key} — ${f.evidence}\n   → ${f.next}\n`);
+      }
+      return 1;
+    }
+    const reported = w.steps.filter((s) => s.status === 'blocked' && !s.blocking);
+    for (const r of reported) {
+      // Reported, not failed: O5/O6 cannot be true before the diff exists. Saying WHY at the point
+      // of report is what stops this reading as a gate that was quietly skipped.
+      process.stdout.write(`::notice::workflow-gate [${r.rule || r.key}]: ${r.evidence} — reported, not failed: this rule closes after the diff exists, and blocks the Acceptance step instead.\n`);
+      process.stdout.write(`⚠️  ${r.key} — ${r.evidence}\n   → ${r.next}\n`);
+    }
+    if (w.legacy) process.stdout.write(`ℹ️  '${w.id}' is LEGACY (record predates ${ENFORCED_FROM}) — order rules reported, not enforced.\n`);
+    if (w.range.error) process.stdout.write(`⚠️  order checks degraded — ${w.range.error}\n`);
+    process.stdout.write(`✅ workflow gate PASSED — '${w.id}' (${w.lane}) at stage ${w.stage}.\n`);
+    return 0;
+  }
+
+  // R-7: the BOARD reads the trunk, not the pull request. The gate path above keeps commitRange().
+  // The PR range is still computed and passed alongside — it is what `● in this change` means, and
+  // it is the one thing the trunk range genuinely cannot answer.
+  const range = historyRange(root);
+  const changeRange = commitRange(root);
+  const ids = listInitiatives(root);
+  // ONE delivery index for the whole board. Built here rather than inside each ladder for the same
+  // reason the commit range is: `deliveryIndex` memoises per trunk head, so a per-initiative build
+  // would be cheap but the intent — one read, shared — is what keeps the rows consistent with each
+  // other even if the trunk moved mid-run.
+  const deliveryIdx = delivery.deliveryIndex(root, ids);
+  const rows = ids.map((i) => computeWorkflow(i, { root, range, changeRange, deliveryIndex: deliveryIdx }));
+  if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
+  if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
+  process.stdout.write(renderBoard(rows, { self, all }));
+  return 0;
+}
+
+module.exports = {
+  computeWorkflow, renderLadder, renderBoard, listInitiatives, layout, inFlight, BOARD_CAP,
+  parseLeadingFrontmatter, specimenRoute, surfaceRoute, priorsCitation, isBuildPath, commitRange,
+  // the board's trunk range, exported so the suite can assert the split: the same record is legacy
+  // under BOTH ranges, and `in this change` is false under the trunk one.
+  historyRange,
+  ENFORCED_FROM,
+};
+
+/*
+ * `exitCode`, not `process.exit()`. `process.exit` tears the process down without waiting for stdout
+ * to drain, and when stdout is a PIPE — every CI invocation, every `| jq`, every test harness —
+ * writes larger than the pipe buffer are asynchronous. `--json` on this repository is ~65 KB, so it
+ * arrived TRUNCATED MID-STRING and parsed as invalid JSON, while an interactive run to a TTY looked
+ * perfect. Setting the code and letting the process end naturally flushes first.
+ */
+if (require.main === module) process.exitCode = main(process.argv);