create-pmos 0.131.0 → 0.133.0

package/workspace/lib/vendor/scripts/workflow-state.js

@@ -0,0 +1,1888 @@
+#!/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 { nineStages } = require('./nine-stages');
+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');
+/*
+ * Three flags the ladder cannot see (status-from-artifacts, Run 1): a spec file changed after an
+ * approval, requirement ids the rubric never cites, and `status:` prose the ladder contradicts. They
+ * sit BESIDE the steps. They never change a step, the stage, a colour or a count, and they write
+ * nothing. See scripts/status-facts.js.
+ */
+const statusFacts = require('./status-facts');
+
+// 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.
+//
+// KEYED BY WHAT THE FILES ARE, never by where they live alone. The workspace server requires this
+// module in-process and holds it for days, so a root-only key kept serving the ladder yesterday's
+// anchor index after the PM fixed the OKR document — the OKR panel (which reads fresh) and the
+// anchor rung disagreed about one field until a restart, the exact two-readers defect
+// anchor-resolve was extracted to end. The stamp is mtime+size over the documents and their
+// directories (the directory catches a file added or removed); the stats cost microseconds against
+// the parse they guard. delivery-index keys its cache on the trunk head sha for the same reason.
+// One stated limit: an `okrs/` directory born at a location no prior read has seen is picked up on
+// the next change to a watched path or the next process, not instantly.
+const _okrCache = new Map();      // root -> { stamp, files, index }
+const _budCache = new Map();      // root -> { stamp, value }
+function statStamp(p) {
+  try { const s = fs.statSync(p); return `${s.mtimeMs}:${s.size}`; } catch { return 'absent'; }
+}
+function okrStamp(files) {
+  const dirs = [...new Set(files.map((f) => path.dirname(f)))];
+  return files.concat(dirs).map((p) => `${p}=${statStamp(p)}`).join('|');
+}
+function okrIndexFor(root) {
+  const hit = _okrCache.get(root);
+  if (hit && hit.files.length && okrStamp(hit.files) === hit.stamp) return hit.index;
+  const files = anchors.listOkrFiles(root);
+  const entry = { stamp: okrStamp(files), files, index: anchors.parseOkrIndex(root) };
+  _okrCache.set(root, entry);
+  return entry.index;
+}
+function budgetsFor(root, L) {
+  const stamp = statStamp(L.budgets);
+  const hit = _budCache.get(root);
+  if (!hit || hit.stamp !== stamp) {
+    let value;
+    try { value = { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }; }
+    catch { value = { ok: false, text: '', path: path.relative(root, L.budgets) }; }
+    _budCache.set(root, { stamp, value });
+  }
+  // D67: the domain registry rides on the budgets object, read fresh (a small, PM-edited file)
+  return anchors.withDomains(_budCache.get(root).value, path.dirname(L.budgets), 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. The closing ---
+// fence is TERMINAL, never skipped: the fence used to be stepped over, so a key-shaped FIRST body
+// line was absorbed into the block and could fake a declaration at the fence boundary (the one
+// shape the gamma prose-then-keys fixture never exercised). Fenceless files keep parsing from line
+// 1 and stop at the first non-key line — the kit's smoke fixtures carry no fences and must keep
+// parsing. Mirrors workspace/lib/file-mode-parse.js, kit/scripts/metrics.py and the two bash gates'
+// readers — first value wins, one pair of surrounding double quotes stripped — so all the readers
+// agree on what a record declared (kit/fixtures/test_parsers.py + workspace/fixture-parity.test.mjs
+// hold the agreement).
+function parseLeadingFrontmatter(text) {
+  const fm = {};
+  let fenceOpen = false;
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    if (line.startsWith('---')) {
+      // Only the FIRST ---, before any key, opens the block; every later --- ends it.
+      if (fenceOpen || Object.keys(fm).length) break;
+      fenceOpen = true;
+      continue;
+    }
+    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()) 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.
+ */
+// The implementation lives in scripts/read-jsonl.js now — this contract became the shared one after
+// six hand-rolled readers each re-decided the torn-line question (and two got it wrong). The thin
+// wrapper keeps this file's call sites and the out-of-band defects channel unchanged.
+const jsonl = require('./read-jsonl');
+function readJsonl(file, defects) {
+  const r = jsonl.readJsonl(file);
+  // Dropped, never guessed — and said out loud to anyone who asked to hear it.
+  if (Array.isArray(defects)) defects.push(...r.defects);
+  return r.rows;
+}
+
+// The ledgers are read once per VERSION OF THE FILE, not once per initiative — the same per-root
+// rule the OKR cache above states, applied to the other four per-root inputs it was skipping. The
+// board filters ~665 KB of parsed rows once per ladder; re-reading and re-parsing the files each
+// time was ~145 MB of work per board. The stamp is mtime+size for the same reason as the OKR
+// cache's: the workspace server holds this module in-process, and a run or acceptance appended
+// between requests must be visible on the next derivation, not after a restart. Callers filter the
+// shared rows and never mutate them.
+const _ledgerCache = new Map();   // absolute path -> { stamp, rows }
+function cachedJsonl(file) {
+  const stamp = statStamp(file);
+  const hit = _ledgerCache.get(file);
+  if (hit && hit.stamp === stamp) return hit.rows;
+  const rows = readJsonl(file);
+  _ledgerCache.set(file, { stamp, rows });
+  return rows;
+}
+
+// ── 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;
+}
+
+/*
+ * When was each path last touched, answered from the range's OWN single pass. A `git log -1
+ * --format=%ct -- <paths>` per initiative was one subprocess per board row — ~85% of the board's
+ * runtime spent re-reading history buildRange had already captured (see the single-pass note
+ * above). Built lazily, memoised on the range object, so every ladder on the board shares one map.
+ */
+function touchIndex(range) {
+  if (!range._touch) {
+    const m = new Map();
+    for (let i = 0; i < range.shas.length; i++) {
+      const t = range.dates[i];
+      if (!Number.isFinite(t)) continue;
+      for (const f of (range.changed[i] || [])) {
+        const prev = m.get(f);
+        if (prev === undefined || t > prev) m.set(f, t);
+      }
+    }
+    range._touch = m;
+  }
+  return range._touch;
+}
+
+// The set of paths git tracks, one `ls-files` shared across the board via the range object. Used
+// only where a range is EMPTY — see the note at the chgIdx computation. `null` = git could not
+// answer, which callers must treat as "fall back", never as "nothing is tracked".
+function trackedIn(root, range) {
+  if (range._tracked === undefined) {
+    const out = git(root, ['ls-files', '-z']);
+    range._tracked = out == null ? null : new Set(out.split('\0').filter(Boolean));
+  }
+  return range._tracked;
+}
+
+/*
+ * 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 recordIdx = opts && opts.recordIdx;
+  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), { recordsDir: layout(root).initiatives });
+    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;
+    /* Inside a PR RANGE the id filter above does not apply, because a pull request was assumed to
+     * carry one initiative and everything in it to be that initiative's build. A branch carrying
+     * several breaks that: PR #287 held five, and the FIRST commit on it — a D01 propagation touching
+     * supabase/functions/mcp/index.ts — was attributed to `sink-discipline-backport`, whose record did
+     * not yet exist. The gate reported ORDER VIOLATION, spec-after-build, for an initiative whose spec
+     * demonstrably preceded its build by three commits.
+     *
+     * A commit made BEFORE an initiative's record first appeared cannot be that initiative's
+     * implementation — the initiative did not exist to be built. That is the whole rule, and it is
+     * narrow on purpose: an implementation commit landing AFTER the record but BEFORE the PRD still
+     * fails, which is the case D13 actually exists to catch. This removes a false violation without
+     * removing a true one. */
+    if (!whole && recordIdx != null && recordIdx !== undefined && recordIdx >= 0 && i < recordIdx) continue;
+    count++;
+    if (first === null) { first = i; sample = hit; }
+  }
+  if (whole && id && (signal === 'branch' || signal === 'change') && 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';
+}
+
+// ── Repository profile (D68) ──────────────────────────────────────────────────────────────────
+// A repository declares `pm-artifacts` (a PM's documents, strategy and specifications — no code) or
+// `product-code` (PMOS-self and code repositories) in a one-line `.pmos-profile` file at its root.
+// No file, or anything else in it, is `product-code`: every existing repository behaves as before.
+// D77 — the lane lists, tracks and rung sets are DATA in scripts/lane-defs.js. This file reads them;
+// it holds no lane list of its own, so editing a definition changes the ladder with no edit here.
+const laneDefs = require('./lane-defs');
+function profileOf(root) {
+  try {
+    const line = fs.readFileSync(path.join(root, '.pmos-profile'), 'utf8')
+      .split('\n').map((l) => l.replace(/#.*$/, '').trim()).find(Boolean);
+    return line === 'pm-artifacts' ? 'pm-artifacts' : 'product-code';
+  } catch { return 'product-code'; }
+}
+
+/** The lanes a repository's initiatives may declare — what the lane picker offers and the lane write accepts. */
+function laneNames(profile) { return laneDefs.laneNames(profile === 'pm-artifacts' ? 'pm-artifacts' : 'product-code'); }
+function lanesFor(root) {
+  const profile = profileOf(path.resolve(root || process.cwd()));
+  return { profile, lanes: laneNames(profile), defs: laneDefs.defsFor(profile) };
+}
+
+// ── 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,
+  };
+}
+
+/*
+ * D77 — the basis of every step: the rule that decides it, and what it read.
+ *
+ * `rule` is one sentence from lane-defs.js (the engine's test, restated for a PM). `file` is a
+ * repository path the step read, and is set ONLY when that file exists — a path the engine did not
+ * find is never offered as a basis. `source` says what kind of thing decided the step: a `file`, a
+ * `ledger` (a .jsonl row), `git` (commit history) or `none`. `first_seen` is the date the file first
+ * appeared, read from the range's own index where it holds one; it is null rather than guessed.
+ */
+function attachBasis(steps, c) {
+  const { profile, root, L, fm, recRel, range, hasEvals, hasAcceptance } = c;
+  const rel = (abs) => path.relative(root, abs);
+  const runs = rel(path.join(L.runsDir, L.runsFile));
+  const evalsLedger = rel(path.join(L.runsDir, 'evals.jsonl'));
+  const acceptLedger = rel(path.join(L.runsDir, 'acceptances.jsonl'));
+  const outcomeLedger = rel(path.join(L.runsDir, 'outcome_checks.jsonl'));
+  const exists = (p) => !!p && fs.existsSync(path.join(root, p));
+  const inEvidence = (st) => {
+    const m = String(st.evidence || '').match(/[\w./-]+\.(?:md|jsonl)\b/);
+    return m && exists(m[0]) ? m[0] : null;
+  };
+  const prd = String(fm.prd_path || '').trim();
+  const pick = {
+    'pm-artifacts': {
+      route: [recRel], anchor: [recRel],
+      brief: [String(fm.brief_path || fm.prd_path || '').trim()], draft: [String(fm.doc_path || '').trim()],
+      review: [hasEvals ? evalsLedger : recRel], approved: [acceptLedger], handoff: [recRel],
+    },
+    'product-code': {
+      route: [recRel], anchor: [recRel], prototype: [prd], understand: [String(fm.explainer_path || '').trim()],
+      spec: [prd, fm.lane === 'chore' ? recRel : null], priors: [runs], contract: [runs], build: [], quality: [],
+      review: [hasEvals ? evalsLedger : null], explain: [], accept: [hasAcceptance ? acceptLedger : null],
+      outcome: [outcomeLedger],
+    },
+  }[profile] || {};
+  for (const st of steps) {
+    let file = null;
+    for (const cand of (pick[st.key] || [])) if (exists(cand)) { file = cand; break; }
+    if (!file && st.status === 'done') file = inEvidence(st);
+    if (st.status === 'na') file = null;
+    let source = 'none';
+    if (file) source = file.endsWith('.jsonl') ? 'ledger' : 'file';
+    else if (st.key === 'build' && st.status === 'done') source = 'git';
+    let firstSeen = null;
+    if (file && source === 'file' && range && range.ok && range.dates) {
+      const idx = firstAppearance(root, range, file);
+      const t = typeof idx === 'number' && idx >= 0 ? range.dates[idx] : null;
+      if (t) firstSeen = new Date(t * 1000).toISOString().slice(0, 10);
+    }
+    st.basis = { rule: laneDefs.rungRule(profile, st.key), file, source, first_seen: firstSeen };
+  }
+  return steps;
+}
+
+// D74 — `generated: {by: x, at: "2026-10-02T01:00:00Z"}` on one line (the only form PMOS writes). Returns the `at`, or ''.
+function generatedAt(v) {
+  const m = /\bat:\s*["']?([^"',}\s]+)/.exec(String(v || ''));
+  return m ? m[1] : '';
+}
+function computeWorkflowDerived(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 profile = profileOf(root);
+  const pmProfile = profile === 'pm-artifacts';
+  const lane = (fm.lane || (pmProfile ? 'prd' : 'feature')).trim() || (pmProfile ? 'prd' : 'feature');
+  const knownLane = pmProfile ? laneNames('pm-artifacts').includes(lane)
+    : laneNames('product-code').includes(lane);
+  // unknown lane = the profile's strictest (feature in product-code, a governed prd in pm-artifacts)
+  const effLane = knownLane ? lane : (pmProfile ? 'prd' : 'feature');
+  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 || generatedAt(fm.generated) || '').slice(0, 10) < ENFORCED_FROM;   // fallback — see ENFORCED_FROM; D74: OKF v0.2 `generated.at` stands in for `timestamp`
+  /*
+   * `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);
+  // A ZERO-COMMIT range contains nothing, so firstAppearance's per-path fallback — a full-history
+  // `git log --diff-filter=A`, once per initiative on any full clone whose base..HEAD is empty
+  // (HEAD level with main) — can only conclude what one shared `ls-files` already says: a tracked
+  // record predates the range (-1), an on-disk-untracked one is uncommitted (Infinity). The gate's
+  // range — non-empty — keeps the fallback, which is what tells "added before the range" from
+  // "never committed" for O1/O2.
+  const emptyChange = !!changeRange && changeRange.ok && changeRange.shas.length === 0;
+  const tracked = emptyChange ? trackedIn(root, changeRange) : null;
+  const chgIdx = !changeRange ? null
+    : tracked ? (tracked.has(recRel) ? -1 : fs.existsSync(recAbs) ? Infinity : null)
+      : firstAppearance(root, changeRange, recRel);
+  const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
+  const lastActivity = (() => {
+    const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
+    // The board supplies the trunk range, whose single pass already holds every commit's paths and
+    // dates — so the answer is a map lookup, not a subprocess. The trunk alone would demote
+    // branch-fresh work (`git log -1` reads from HEAD, which sees branch-local commits the trunk
+    // range excludes), so the gate's base..HEAD range is overlaid, max date per path. The
+    // subprocess survives only where no whole-history range was supplied — the single-ladder call.
+    // One deliberate difference from the per-path subprocess: a true merge lists no files in the
+    // single pass, so a merge that merely reconciles histories no longer counts as activity on the
+    // paths it carried — the date it stamped was the sync's, not the work's.
+    if (opts && opts.range && range.ok && range.wholeHistory) {
+      const trunk = touchIndex(range);
+      const branch = changeRange && changeRange.ok ? touchIndex(changeRange) : null;
+      let best = null;
+      for (const p of paths) {
+        const t = Math.max(trunk.get(p) || 0, (branch && branch.get(p)) || 0);
+        if (t > 0 && (best === null || t > best)) best = t;
+      }
+      return best;
+    }
+    const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
+    const t = out && parseInt(out.trim(), 10);
+    return Number.isFinite(t) ? t : null;
+  })();
+  const steps = [];
+  // Steps the PM cut or made optional on 2026-10-07 (planning/initiatives/sdlc-step-cuts.md).
+  const CUT_NOTE = 'cut by the PM 2026-10-07 (sdlc-step-cuts)';
+
+  // ── 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 (effLane !== 'feature') {
+      // The routing questions are asked of feature work only.
+      steps.push(step('route', 'route', 'done', `${lane} lane — routing questions are for features only (${CUT_NOTE})`));
+    } 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.kind === 'domain') {
+      // D67 — the domain's standing goal: resolved like a health budget, rejected like one when the
+      // id is not in the PM-edited registry.
+      const domRel = (budgetsFor(root, L).domains || {}).path || 'planning/okrs/domains.md';
+      if (r.status === 'resolved') {
+        steps.push(step('anchor', 'anchor', 'done', `domain:${r.domain} — ${r.domain_goal || 'standing goal not written'} (no OKR, D67)`));
+      } else {
+        steps.push(step('anchor', 'anchor', legacy ? 'unknown' : 'blocked',
+          `domain:${r.domain} is not a declared domain`,
+          `only the PM adds a domain — use an id from ${domRel}, or anchor to a KR or a health budget`,
+          { 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' }));
+    }
+  }
+
+  // ── D68: the pm-artifacts ladder replaces everything after the anchor ─────────────────────────
+  if (pmProfile) {
+    return pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity, opts });
+  }
+
+  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,
+    // Where this initiative's own record first appears in the range — the earliest commit that could
+    // possibly be its build. Already computed above as `recIdx`, from identical arguments.
+    // See the note in buildCommits' attribution loop.
+    recordIdx: recIdx,
+    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, made optional (sdlc-step-cuts) ───────────────────────────────────────
+  // An explain-surface pass that exists is shown; a missing one never blocks.
+  {
+    const expl = String(fm.explainer_path || '').trim();
+    if (expl && fs.existsSync(path.join(root, expl))) {
+      steps.push(step('understand', 'understand', 'done', `${expl} — optional surface explainer`));
+    } else {
+      steps.push(step('understand', 'understand', 'na', `the surface explainer is optional — ${CUT_NOTE}`));
+    }
+  }
+
+  // ── spec ─ the lane's artifacts, and O1/O2: they precede the build ───────────────────────────
+  // A feature PRD's done-criteria section can serve as its rubric (sdlc-step-cuts), so a separate
+  // rubric file is optional in every lane. One that is declared must still exist.
+  const needsRubric = false;
+  {
+    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) with its done-criteria (D13), then set prd_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 = cachedJsonl(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, cut (sdlc-step-cuts) ───────────────────────────────────────────────────────
+  // Reading earlier runs is still good practice; citing them is no longer checked.
+  steps.push(step('priors', 'priors', 'na', `prior-run citation is not required — ${CUT_NOTE}`));
+
+  // ── contract ─ O5: PM-approved done-criteria. Reported, never blocking ─────────────────────
+  // Since sdlc-step-cuts only the feature lane asks for it, and a missing sign-off is pending, not
+  // blocked: the PM's approval of the PRD and the acceptance at the end are the sign-offs that count.
+  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 (effLane !== 'feature') {
+      steps.push(step('contract', 'contract', 'na', `${effLane} lane — the PM's acceptance stands in for a contract sign-off (${CUT_NOTE})`));
+    } else {
+      steps.push(step('contract', 'contract', 'pending',
+        runs.length ? `${runs.length} run(s) logged, none with pre_run_contract.PM_approved: true` : 'no run logged for this initiative yet',
+        `agree done_criteria + test_method with the PM (approving the PRD counts) and record it in ${runsRel}`,
+        { 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.
+   *
+   * THE BUILD RULE (PRD R6, pm-os-absorb Run 4). Items never complete a stage, with one exception: when plan items
+   * under Build were materialized (a D65 `declared` line names them as `plan_item`, D86 point 1), the step is done
+   * when every one of those work items is integrated, and pending until then, whatever the commits say. With no
+   * materialized item the commits decide, as above. The rule reads both ledgers through plan-items-stage.js, the
+   * engine's own pure fold (X29: the engine cannot require workspace/lib). A broken delivered_by stays blocked first.
+   */
+  const buildRule = require('./plan-items-stage').buildRuleFor(root, id);
+  const ruleStep = build.failedDeclaration || !(buildRule.applies || buildRule.unknown) ? null
+    : buildRule.unknown
+      ? step('build', 'build', 'unknown', buildRule.reason)
+      : buildRule.pending.length === 0
+        ? step('build', 'build', 'done',
+          `every materialized item under Build is integrated (${buildRule.integrated.length} of ${buildRule.materialized.length} in planning/work-items.jsonl)`)
+        : step('build', 'build', 'pending',
+          `${buildRule.integrated.length} of ${buildRule.materialized.length} materialized item(s) under Build integrated — waiting on ${buildRule.pending.join(', ')}`,
+          'merge each work item with a `Work-Item: <id>` trailer on the trunk, then run `pmos verify-work`');
+  steps.push(ruleStep || (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 = cachedJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
+  {
+    /* The rung reads the RUBRIC, not the lane.
+     *
+     * It keyed on `lane` alone, so a chore that deliberately carries a rubric could never surface
+     * its Review Gate — the ladder said "chore lane carries no rubric (D56)" while a SKIPPED verdict
+     * sat in evals.jsonl unread. That is how `guard-and-ledger-hardening`, a chore whose own record
+     * argues "blast radius overrides lane" and which carried a rubric on purpose, reached `accept`
+     * with the gate never run. The board could not show what the ledger already knew.
+     *
+     * A prototype is still never scored — D60 grills leg A as dialogue, and that is a property of
+     * the lane, not of whether someone attached a rubric. Every other lane defers to the artifact. */
+    const declaresRubric = !!String(fm.rubric_path || '').trim();
+    /* EVERY lane defers to the artifact — the first version said so in the comment and applied it
+     * only to `chore`, so a discovery or incident initiative with no rubric (legitimate under D56)
+     * showed a permanent `no Review-Gate verdict recorded`: a rung it could never satisfy. The lanes
+     * that carry no rubric by design are named once, here. */
+    const RUBRIC_OPTIONAL = ['chore', 'discovery', 'incident', 'content'];
+    if (effLane === 'prototype') {
+      steps.push(step('review', 'review', 'na', 'leg A is grilled as dialogue, never scored (D60)'));
+    } else if (RUBRIC_OPTIONAL.includes(effLane) && !declaresRubric && !evals.length) {
+      steps.push(step('review', 'review', 'na', `${effLane} lane carries no rubric (D56)`));
+    } else if (evals.length) {
+      const last = evals[evals.length - 1];
+      const verdict = String(last.verdict || '').toUpperCase();
+      const label = `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`;
+      /* A SKIPPED gate is NOT a satisfied gate, and a FAIL is emphatically not one.
+       *
+       * This rung rendered both as a green ✓, which is the watermelon this repo names as its own
+       * failure mode: the board said the Review Gate was done over a row that says judging never
+       * happened. Thirteen initiatives currently render `✓ review` over a SKIPPED verdict, and the
+       * fix that made a chore's gate visible ADDED one. The module's own rule, repeated in three
+       * files — "a skip is an honest RECORD that verification did not happen; it is not
+       * verification" — now applies to the surface that reports it. */
+      // The Review Gate runs on request since sdlc-step-cuts: a skip is n/a, and a FAIL is reported
+      // for the PM to weigh at acceptance rather than holding the gate shut.
+      if (verdict === 'SKIPPED') {
+        steps.push(step('review', 'review', 'na', `${label} — skipped; the Review Gate runs on request (${CUT_NOTE})`));
+      } else if (verdict === 'FAIL') {
+        steps.push(step('review', 'review', 'pending', label,
+          'the Review Gate FAILED — weigh the findings at acceptance, or remediate and record a new verdict', { rule: 'R3' }));
+      } else {
+        steps.push(step('review', 'review', 'done', label));
+      }
+    } else {
+      steps.push(step('review', 'review', 'na', `no Review-Gate verdict — it runs on request (${CUT_NOTE})`));
+    }
+  }
+
+  // ── explain ─ O6, made optional (sdlc-step-cuts) ────────────────────────────────────────────
+  // A run explainer that exists is shown; a missing one never blocks 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; }
+    }
+    steps.push(found
+      ? step('explain', 'explain', 'done', found)
+      : step('explain', 'explain', 'na', `the run explainer is optional — ${CUT_NOTE}`));
+  }
+
+  // ── accept ─ the human PM, final and non-delegable (D12) ─────────────────────────────────────
+  const accepted = cachedJsonl(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', 'no acceptance record needed (D94)',
+        'merge once the required checks are green and the PM has not returned the run'));
+    }
+  }
+
+  /* ── outcome ─ D57: did the bet pay off? A SECOND verdict, at a second time ───────────────────
+   *
+   * This rung did not exist, and its absence is why the loop never ran: `outcome_metric` is optional
+   * in D57, nothing ever asked for it, and 0 of ~170 records declared one. An optional field with no
+   * prompt and no surface is a field that does not exist.
+   *
+   * `na` is a first-class, non-failing state on purpose. Most work is not a bet, and a rung that
+   * renders red for every initiative without a metric becomes noise and gets ignored — which is how
+   * you end up with a board nobody reads. */
+  {
+    const metric = String(fm.outcome_metric || '').trim();
+    const horizon = String(fm.outcome_horizon || '').trim();
+    const checks = cachedJsonl(path.join(L.runsDir, 'outcome_checks.jsonl'))
+      .filter((c) => c && c.initiative_id === id && ['validated', 'refuted', 'inconclusive'].includes(c.disposition));
+    const latest = checks.length ? checks[checks.length - 1] : null;
+    const today = new Date().toISOString().slice(0, 10);
+
+    if (!metric) {
+      steps.push(step('outcome', 'outcome', 'na', 'no outcome declared — most work is not a bet (D57)'));
+    } else if (!horizon) {
+      /* A metric with no horizon can never come due, so it reads as diligence for ever while
+       * committing to nothing. That is worse than declaring nothing at all. */
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome_metric declared with NO outcome_horizon — a bet that can never come due`,
+        'add outcome_horizon: YYYY-MM-DD to the initiative record, or remove the metric', { rule: 'D57' }));
+    } else if (latest) {
+      /* A refuted bet is a COMPLETED check and an UNSUCCESSFUL bet. The rung says both — rendering
+       * it as a plain green tick is the same watermelon the review rung was fixed for. */
+      const done = latest.disposition === 'refuted' ? 'blocked' : 'done';
+      steps.push(step('outcome', 'outcome', done,
+        `${latest.disposition}${latest.evidence ? ` — ${String(latest.evidence).slice(0, 60)}` : ''}`,
+        latest.disposition === 'refuted'
+          ? 'the check is complete and the bet did not pay off — that is a result, not a failure to record'
+          : undefined));
+    } else if (horizon <= today) {
+      steps.push(step('outcome', 'outcome', 'blocked',
+        `outcome check DUE — horizon ${horizon} has passed and no disposition is recorded`,
+        'dispose it: node scripts/record-outcome.js (validated | refuted | inconclusive, evidence required)',
+        { rule: 'D57' }));
+    } else {
+      steps.push(step('outcome', 'outcome', 'pending', `outcome pending — horizon ${horizon}`));
+    }
+  }
+
+  attachBasis(steps, { profile: 'product-code', root, L, fm, recRel, range, hasEvals: evals.length > 0, hasAcceptance: accepted.length > 0 });
+
+  // ── 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;
+
+  // `opts.facts === false` exists so a test can prove the flags change nothing else in the ladder.
+  const facts = (opts && opts.facts === false) ? {}
+    : statusFacts.compute({ root, L, id, fm, lane: effLane, stage, runs, accepted });
+
+  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, profile: 'product-code',
+    nine_stages: nineStages(effLane, { stage, steps }),
+    ...facts,
+    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,
+  };
+}
+
+// ── The document scan (scan-documents S1–S4) — what the repository holds for each initiative ─────
+// A pm-artifacts record often names none of its documents: the PRD, the evaluation and the Jira
+// tickets sit in the repository and the record was never told. The ladder used to read the record
+// only, so that work read as not started. This reads the repository once per root (tracked and
+// untracked, not ignored), joins each document to an initiative by its frontmatter or by the id in
+// its path, and gives it a role from its name. It is evidence a named path outranks, never a
+// blocker, and nothing is written back. The cache holds SCAN_TTL_MS; `forgetDocumentScan` (the
+// workspace's Scan repository) drops it at once.
+const SCAN_TTL_MS = 30000;
+const SCAN_MAX_FILES = 20000;
+const SCAN_EXT = /\.(md|markdown|mdx|txt|docx|pdf|html?)$/i;
+const SCAN_TEXT = /\.(md|markdown|mdx|txt)$/i;
+const SCAN_ROLES = [   // first match wins, in this order (S2)
+  ['review', ['eval', 'evals', 'evaluation', 'evaluations', 'review', 'reviews', 'verdict', 'scorecard']],
+  ['handoff', ['handoff', 'handover', 'hand-off']],
+  ['brief', ['brief', 'briefs', 'problem', 'idea', 'ideas', 'intake', 'one-pager', 'onepager', 'bug-report']],
+  ['draft', ['prd', 'prds', 'spec', 'specs', 'specification', 'requirements', 'findings', 'plan', 'strategy', 'report', 'decision']],
+];
+const SCAN_NOT_EVIDENCE = ['rubric', 'rubrics', 'template', 'templates'];
+const JIRA_KEY = /^[A-Z][A-Z0-9_]+-\d+$/;
+const _scanCache = new Map();   // root -> { at, index: Map(id -> { brief:[], draft:[], review:[], handoff:[] }) }
+function forgetDocumentScan(root) { if (root) _scanCache.delete(path.resolve(root)); else _scanCache.clear(); }
+
+function scanWords(s) {
+  const lower = String(s || '').toLowerCase();
+  const words = lower.split(/[^a-z0-9]+/).filter(Boolean);
+  // The hyphenated role words are matched as joined pairs too: "hand-off", "one-pager", "bug-report".
+  const n = words.length;
+  for (let i = 0; i + 1 < n; i++) words.push(`${words[i]}-${words[i + 1]}`);
+  return words;
+}
+function roleOfWords(words, extra) {
+  const set = new Set(words);
+  for (const [role, list] of SCAN_ROLES) {
+    if (list.some((w) => set.has(w))) return role;
+    if (role === 'draft' && extra && extra.some((w) => set.has(w))) return role;
+  }
+  return null;
+}
+/** A name as a slug: lower case, every run of other characters one dash. "Checkout Redesign PRD.docx" → "checkout-redesign-prd-docx". */
+const scanSlug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+/**
+ * Does the slug `name` carry the key? Equal, or the key leads it ("checkout-prd"). A key of two words or more, or of
+ * six characters or more, may also stand anywhere between dashes ("prd-checkout-redesign-v2"): a short one-word key
+ * such as "app" would otherwise claim every file with that word in it.
+ */
+function slugHasKey(name, key) {
+  if (!name || !key) return false;
+  if (name === key || name.startsWith(key + '-')) return true;
+  if (!key.includes('-') && key.length < 6) return false;
+  return name.endsWith('-' + key) || name.includes('-' + key + '-');
+}
+/**
+ * The initiatives a document belongs to (S1): its frontmatter names them; else the record whose key — its id, or its
+ * title as a slug — is a folder in the path, leads or stands in the file name, or stands in the document's own title.
+ * The longest key wins, so "checkout-redesign" takes a file that "checkout" would also match.
+ */
+function documentOwners(rel, fm, idSet, keys) {
+  const named = [fm.initiative, fm.initiative_id, fm.initiatives].filter(Boolean)
+    .flatMap((v) => String(v).replace(/^\[|\]$/g, '').split(',')).map((s) => s.trim().replace(/^["']|["']$/g, ''))
+    .filter((s) => idSet.has(s));
+  if (named.length) return { ids: [...new Set(named)], key: null };
+  const parts = rel.split('/');
+  const base = scanSlug(parts[parts.length - 1].replace(/\.[^.]+$/, ''));
+  const dirs = parts.slice(0, -1).map(scanSlug);
+  const title = scanSlug(fm.title);
+  for (const { id, key } of keys) {
+    if (dirs.includes(key) || slugHasKey(base, key) || slugHasKey(title, key)) return { ids: [id], key };
+  }
+  return { ids: [], key: null };
+}
+/** The role of a found document (S2): its file name, then its frontmatter `type:`, then its folders. */
+function documentRole(rel, type, key) {
+  const parts = rel.split('/');
+  const base = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+  // A rubric or a template says what good looks like; it is not evidence that the work was judged or done.
+  if (scanWords(base).some((x) => SCAN_NOT_EVIDENCE.includes(x))) return null;
+  // The initiative's own name is not a role word: "problem-reporting-prd" is the PRD of the initiative problem-reporting.
+  const strip = (s) => { const slug = scanSlug(s); return key ? slug.split(key).join('-') : slug; };
+  return roleOfWords(scanWords(strip(base))) || roleOfWords(scanWords(type))
+    || roleOfWords(scanWords(strip(parts.slice(0, -1).join('/'))));
+}
+/** Every record: its id and the keys a document may carry — the id, and the title as a slug when it is not too short. */
+function recordKeys(L) {
+  let files = [];
+  try { files = fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)); }
+  catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const id = f.slice(0, -3);
+    const fm = readFrontmatter(path.join(L.initiatives, f)) || {};
+    const keys = new Set([scanSlug(id)]);
+    const t = scanSlug(fm.title);
+    if (t && (t.includes('-') || t.length >= 6)) keys.add(t);
+    for (const key of keys) if (key.length >= 3) out.push({ id, key });
+  }
+  return out.sort((a, b) => b.key.length - a.key.length);
+}
+/** The repository's files: git's list (tracked, and untracked but not ignored); a walk of the folder when it is not a git repository. */
+function scanFiles(root) {
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  if (out != null) return [...new Set(out.split('\0').filter(Boolean))].slice(0, SCAN_MAX_FILES);
+  const files = [];
+  const walk = (dir, rel) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (files.length >= SCAN_MAX_FILES) return;
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.isFile()) files.push(r);
+    }
+  };
+  walk(root, '');
+  return files;
+}
+/** Where the tidy (S10) moves a duplicate, repository-relative: `<state>/archive/duplicates/`. The scan does not read it. */
+function duplicatesArchive(root, L) {
+  return path.relative(root, path.join(path.dirname(L.initiatives), 'archive', 'duplicates')).split(path.sep).join('/') + '/';
+}
+function scanRepository(root, L) { return scanDetail(root, L).index; }
+/** The kinds the PM confirmed (S11): `<state>/document-kinds.jsonl`, the latest line for a path. A kind is a role, or `none`. */
+const DOCUMENT_KINDS = ['brief', 'draft', 'review', 'handoff', 'none'];
+function documentKinds(L) {
+  const out = new Map();
+  let text = '';
+  try { text = fs.readFileSync(path.join(path.dirname(L.initiatives), 'document-kinds.jsonl'), 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (o && typeof o.path === 'string' && DOCUMENT_KINDS.includes(o.kind)) out.set(o.path, o.kind);
+    } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+/** The scan's index, and how many initiatives each found document belongs to (`owners`, for the tidy). */
+function scanDetail(root, L) {
+  const key = path.resolve(root);
+  const hit = _scanCache.get(key);
+  if (hit && Date.now() - hit.at < SCAN_TTL_MS) return hit;
+  const index = new Map();
+  const owners = new Map();
+  const owned = [];     // every document tied to an initiative, with or without a role (the Jev check reads them, S11)
+  const kinds = documentKinds(L);
+  const keys = recordKeys(L);
+  const idSet = new Set(keys.map((k) => k.id));
+  const recDir = path.relative(root, L.initiatives).split(path.sep).join('/') + '/';
+  const archDir = duplicatesArchive(root, L);
+  for (const rel of scanFiles(root)) {
+    if (!SCAN_EXT.test(rel) || rel.startsWith(recDir) || rel.startsWith(archDir) || /(^|\/)(node_modules|\.git)\//.test(rel)) continue;
+    let fm = {};
+    if (SCAN_TEXT.test(rel)) {
+      try {
+        const fd = fs.openSync(path.join(root, rel), 'r');
+        const buf = Buffer.alloc(4096);
+        const n = fs.readSync(fd, buf, 0, 4096, 0);
+        fs.closeSync(fd);
+        fm = parseLeadingFrontmatter(buf.slice(0, n).toString('utf8')) || {};
+      } catch { continue; }
+    }
+    const owner = documentOwners(rel, fm, idSet, keys);
+    if (!owner.ids.length) continue;
+    // git's index still lists a tracked file that was moved or deleted and not yet staged
+    if (!SCAN_TEXT.test(rel) && !fs.existsSync(path.join(root, rel))) continue;
+    const local = documentRole(rel, fm.type, owner.key);
+    const kind = kinds.get(rel) || null;   // a kind the PM confirmed outranks the name (S11)
+    const role = kind ? (kind === 'none' ? null : kind) : local;
+    owned.push({ path: rel, ids: owner.ids, role, local, kind, title: fm.title ? String(fm.title) : null });
+    if (!role) continue;
+    owners.set(rel, owner.ids.length);
+    for (const id of owner.ids) {
+      if (!index.has(id)) index.set(id, { brief: [], draft: [], review: [], handoff: [] });
+      index.get(id)[role].push(rel);
+    }
+  }
+  for (const v of index.values()) for (const k of Object.keys(v)) v[k].sort();
+  const out = { at: Date.now(), index, owners, owned };
+  _scanCache.set(key, out);
+  return out;
+}
+/** When a document last changed, in seconds: its last commit, else the file's own time. */
+function documentChangedAt(root, rel) {
+  const t = Number(String(git(root, ['log', '-1', '--format=%ct', '--', rel]) || '').trim());
+  if (t > 0) return t;
+  try { return Math.floor(fs.statSync(path.join(root, rel)).mtimeMs / 1000); } catch { return 0; }
+}
+/**
+ * Every document the scan ties to an initiative, for the Jev check (S11): { ok, profile, kinds, documents: [{ path, ids,
+ * role, local, kind, title, text }] }. `local` is the role the name gives, `kind` the one the PM confirmed, `role` the one
+ * the scan uses, and `text` says whether the file is Markdown or text (only those can be read by Jev). Nothing is written.
+ */
+function documentCandidates(root, opts) {
+  const L = layout(root);
+  const profile = profileOf(root);
+  const kinds = path.relative(root, path.join(path.dirname(L.initiatives), 'document-kinds.jsonl')).split(path.sep).join('/');
+  if (profile !== 'pm-artifacts') return { ok: true, profile, kinds, documents: [] };
+  if (opts && opts.fresh) forgetDocumentScan(root);
+  const { owned } = scanDetail(root, L);
+  const titles = {};
+  try {
+    for (const f of fs.readdirSync(L.initiatives)) {
+      if (!f.endsWith('.md') || /^(README|index|log)\.md$/i.test(f)) continue;
+      titles[f.slice(0, -3)] = String((readFrontmatter(path.join(L.initiatives, f)) || {}).title || f.slice(0, -3));
+    }
+  } catch { /* no records */ }
+  return { ok: true, profile, kinds, titles, documents: owned.map((d) => ({ ...d, text: SCAN_TEXT.test(d.path), changed: documentChangedAt(root, d.path) })) };
+}
+/**
+ * The duplicates the tidy offers (S10): for each initiative, each role with more than one document. The group keeps the
+ * file the record names, else the most recently changed, else the shortest path. A document that belongs to more than one
+ * initiative is listed as `shared` and is never one to move. Only a pm-artifacts repository has groups. Nothing is written.
+ *   { ok, profile, archive, groups: [{ id, title, role, keep, files: [{ path, changed }], shared: [path] }] }
+ */
+function documentDuplicates(root, opts) {
+  const L = layout(root);
+  const profile = profileOf(root);
+  const archive = duplicatesArchive(root, L);
+  if (profile !== 'pm-artifacts') return { ok: true, profile, archive, groups: [] };
+  if (opts && opts.fresh) forgetDocumentScan(root);
+  const { index, owners } = scanDetail(root, L);
+  const norm = (p) => { const v = String(p || '').trim(); return v ? path.relative(root, path.resolve(root, v)).split(path.sep).join('/') : ''; };
+  const groups = [];
+  for (const [id, roles] of [...index].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const fm = readFrontmatter(path.join(L.initiatives, `${id}.md`)) || {};
+    const named = { brief: norm(fm.brief_path || fm.prd_path), draft: norm(fm.doc_path) };
+    for (const role of ['brief', 'draft', 'review', 'handoff']) {
+      const own = roles[role].filter((f) => (owners.get(f) || 0) <= 1);
+      const shared = roles[role].filter((f) => (owners.get(f) || 0) > 1);
+      const pin = named[role] && fs.existsSync(path.join(root, named[role])) ? named[role] : '';
+      if (pin && !own.includes(pin) && !shared.includes(pin)) own.push(pin);
+      if (own.length < 2) continue;
+      const files = own.map((f) => ({ path: f, changed: documentChangedAt(root, f) }));
+      files.sort((a, b) => (b.path === pin) - (a.path === pin) || b.changed - a.changed
+        || a.path.length - b.path.length || a.path.localeCompare(b.path));
+      groups.push({ id, title: fm.title || id, role, keep: files[0].path, files, shared, named: !!pin && files[0].path === pin });
+    }
+  }
+  return { ok: true, profile, archive, groups };
+}
+/**
+ * Jira keys the repository holds for an initiative (S4): the Jira tab's draft; the record's `jira:` keys; in the
+ * record's text, a Jira link (`…/browse/KEY`) or a key on a line that says Jira; and a Jira link in its found
+ * documents. A bare key elsewhere is not read: "UTF-8" and "ISO-8601" have the same shape.
+ */
+function jiraKeysOf(root, L, id, fm, found) {
+  const keys = [];
+  const draft = path.join(path.dirname(L.initiatives), 'tracker', 'jira', `${id}-tickets.md`);
+  try {
+    for (const line of fs.readFileSync(draft, 'utf8').split('\n')) {
+      const m = /^- jira:\s*(\S+)\s*$/.exec(line);
+      if (m && JIRA_KEY.test(m[1].toUpperCase())) keys.push(m[1].toUpperCase());
+    }
+  } catch { /* no draft */ }
+  for (const k of ['jira', 'jira_key', 'jira_keys', 'jira_epic']) {
+    for (const m of String(fm[k] || '').toUpperCase().matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+  }
+  const fromText = (text, lines) => {
+    for (const m of String(text).matchAll(/\/browse\/([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    if (lines) for (const line of String(text).split('\n')) {
+      if (!/jira/i.test(line)) continue;
+      for (const m of line.matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    }
+  };
+  try { fromText(fs.readFileSync(path.join(L.initiatives, `${id}.md`), 'utf8'), true); } catch { /* no record text */ }
+  for (const rel of found ? [].concat(found.brief, found.draft, found.review, found.handoff) : []) {
+    if (!SCAN_TEXT.test(rel)) continue;
+    try { fromText(fs.readFileSync(path.join(root, rel), 'utf8').slice(0, 200000), false); } catch { /* unreadable */ }
+  }
+  return [...new Set(keys)];
+}
+
+/**
+ * D68 — the pm-artifacts ladder: route → anchor → brief → draft → review → approved → handed off.
+ *
+ * Route and anchor are computed by the shared code above and keep their rules (anchoring holds in
+ * every profile — D59/D67); route is re-stated here because its product-code form asks the
+ * specimen/surface questions, which a PM document does not need. What follows is evidence-derived
+ * like every other rung — nothing is declared done:
+ *   brief    — the brief file (`brief_path`, or `prd_path`) exists
+ *   draft    — the deliverable (`doc_path`) exists, and — governed only — did not appear before the brief
+ *   review   — an evals.jsonl verdict for this id, or a named `reviewed_by:` (a rubric, an agent, a human)
+ *   approved — the PM's acceptance in acceptances.jsonl (D12, never automatic)
+ *   handoff  — `handed_off:` names where it went; n/a for decision records, reports and chores
+ * When the record names no file for brief, draft or review, or names one that does not exist, a
+ * document the repository scan found for the id completes the step (scan-documents S3); Jira keys
+ * in the repository complete the handoff (S4). Found evidence never blocks and never fails CI.
+ * Track: `light` (guidance — only route and anchor can fail CI) or `governed` (brief and draft
+ * existence and their order fail CI for a non-legacy record). Review, approval and handoff are never
+ * CI-blocking in either track: none can be true before the PR exists.
+ */
+function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity, opts }) {
+  const declared = String(fm.track || '').trim().toLowerCase();
+  const track = declared === 'light' || declared === 'governed' ? declared
+    : (laneDefs.laneDef('pm-artifacts', effLane) || laneDefs.laneDef('pm-artifacts', 'prd')).track;
+  const enforce = track === 'governed' && !legacy;
+  const exists = (p) => !!p && fs.existsSync(path.join(root, p));
+  // D77 — the lane's own definition decides which rungs it passes and what it calls them.
+  const def = laneDefs.laneDef('pm-artifacts', effLane) || laneDefs.laneDef('pm-artifacts', 'prd');
+  const flows = (k) => def.rungs.includes(k);
+  const skipped = (key, label) => step(key, label, 'na', `${effLane} lane — ${label} is not part of this flow`);
+
+  // route — the lane is a pm-artifacts lane
+  steps[0] = knownLane
+    ? step('route', 'route', 'done', `${lane} lane · ${track} track (pm-artifacts profile, D68)`)
+    : step('route', 'route', 'done', `unknown lane '${lane}' — treated as a governed prd, the profile's strictest (D68)`,
+      `set lane: to one of ${laneNames('pm-artifacts').join(', ')}`);
+
+  const found = (opts && opts.scan === false) ? null : (scanRepository(root, L).get(id) || null);
+  const foundOf = (role) => (found && found[role].length ? found[role][0] : null);
+  const briefPath = String(fm.brief_path || fm.prd_path || '').trim();
+  const docPath = String(fm.doc_path || '').trim();
+  const foundBrief = exists(briefPath) ? null : foundOf('brief');
+  const foundDraft = exists(docPath) ? null : foundOf('draft');
+  const briefIdx = briefPath ? firstAppearance(root, range, briefPath) : null;
+  const docIdx = docPath ? firstAppearance(root, range, docPath) : null;
+
+  if (!flows('brief')) steps.push(skipped('brief', def.brief_label));
+  else if (foundBrief) steps.push(step('brief', def.brief_label, 'done', `${foundBrief} — found by the repository scan`));
+  else if (exists(briefPath)) steps.push(step('brief', def.brief_label, 'done', `${briefPath} present`));
+  else steps.push(step('brief', def.brief_label, enforce ? 'blocked' : 'pending',
+    briefPath ? `brief_path '${briefPath}' does not exist` : `no ${def.brief_label} yet`,
+    `write the ${def.brief_label} (${def.input}) and set brief_path in ${recRel}`,
+    { blocking: enforce, rule: 'P1' }));
+
+  if (!flows('draft')) steps.push(skipped('draft', def.draft_label));
+  else if (foundDraft) steps.push(step('draft', def.draft_label, 'done', `${foundDraft} — found by the repository scan`));
+  else if (exists(docPath)) {
+    const inOrder = briefIdx == null || docIdx == null ? null : docIdx >= briefIdx;
+    if (enforce && inOrder === false) {
+      steps.push(step('draft', def.draft_label, 'blocked', `${docPath} appeared before its brief ${briefPath}`,
+        'a governed document is briefed before it is drafted — the brief must land first', { blocking: true, rule: 'P2' }));
+    } else steps.push(step('draft', def.draft_label, 'done', `${docPath} present`));
+  } else steps.push(step('draft', def.draft_label, enforce && docPath ? 'blocked' : 'pending',
+    docPath ? `doc_path '${docPath}' does not exist` : `no ${def.draft_label} yet`,
+    `write the ${def.draft_label} (${def.output}) and set doc_path in ${recRel}`, { blocking: enforce && !!docPath, rule: 'P2' }));
+
+  const evals = cachedJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
+  const reviewer = String(fm.reviewed_by || '').trim();
+  if (!flows('review')) steps.push(skipped('review', 'review'));
+  else if (evals.length) steps.push(step('review', 'review', 'done', `${evals[evals.length - 1].verdict || 'verdict'} recorded in evals.jsonl`));
+  else if (reviewer) steps.push(step('review', 'review', 'done', `reviewed by ${reviewer}`));
+  else if (foundOf('review')) steps.push(step('review', 'review', 'done', `${foundOf('review')} — evaluation found by the repository scan`));
+  else steps.push(step('review', 'review', 'pending', 'not reviewed yet',
+    'name the reviewer in reviewed_by: (a person, an agent, or a rubric verdict in evals.jsonl)'));
+
+  const accepted = cachedJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
+    .filter((a) => a && a.initiative_id === id && a.accepted === true);
+  const acceptedOn = accepted.length ? (accepted[accepted.length - 1].accepted_at || accepted[accepted.length - 1].at) : null;
+  // D86 point 3 — a report is approved when the PM issues it: an `issued` line in issues.jsonl naming its doc_path.
+  // Its own minimal parse (X29: the vendored engine never requires workspace/lib); a line counts only if the PM wrote it.
+  const norm = (p) => String(p || '').trim().replace(/^\.\//, '');
+  const issued = effLane !== 'report' || !docPath ? []
+    : cachedJsonl(path.join(L.runsDir, 'issues.jsonl')).filter((r) => r && r.ev === 'issued' && norm(r.path) === norm(docPath)
+      && /^pm:/.test(String(r.by || '')) && (r.via === 'ui' || r.via === 'cli') && /^[0-9a-f]{40}$/.test(String(r.sha || '')));
+  steps.push(!flows('approved') ? skipped('approved', 'approved')
+    : issued.length
+    ? step('approved', 'approved', 'done', `issued by the PM on ${String(issued[0].at || '').slice(0, 10)} (issues.jsonl)`)
+    : accepted.length
+    ? step('approved', 'approved', 'done', `accepted by the PM${acceptedOn ? ' on ' + String(acceptedOn).slice(0, 10) : ''}`)
+    : effLane === 'report'
+    ? step('approved', 'approved', 'pending', 'awaiting the PM\'s Issue (D86 point 3)', 'the PM issues the report (pmos report issue, or Issue on Reports) — never automatic')
+    : step('approved', 'approved', 'pending', 'awaiting the PM\'s acceptance (D12)', 'the PM accepts the document — never automatic'));
+
+  if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));
+  else {
+    const to = String(fm.handed_off || '').trim();
+    const keys = to ? [] : jiraKeysOf(root, L, id, fm, found);
+    steps.push(to ? step('handoff', 'handed off', 'done', `handed off — ${to}`)
+      : keys.length ? step('handoff', 'handed off', 'done', `handed off to Jira — ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ` and ${keys.length - 5} more` : ''}`)
+      : foundOf('handoff') ? step('handoff', 'handed off', 'done', `${foundOf('handoff')} — handoff found by the repository scan`)
+      : step('handoff', 'handed off', 'pending', 'not handed off yet',
+        'record where it went in handed_off: (a tracker link, the team, or "accepted as the deliverable")'));
+  }
+
+  attachBasis(steps, { profile: 'pm-artifacts', root, L, fm, recRel, range, hasEvals: evals.length > 0, hasAcceptance: accepted.length > 0 });
+  const by = Object.fromEntries(steps.map((x) => [x.key, x]));
+  let stage = 'intake';
+  if (by.brief.status === 'done') stage = 'brief';
+  if (by.draft.status === 'done') stage = 'draft';
+  if (by.review.status === 'done') stage = 'review';
+  if (by.handoff && by.handoff.status === 'done') stage = 'handoff';
+  if (accepted.length) stage = 'accepted';
+  const blockers = steps.filter((x) => x.status === 'blocked');
+  const gateFailures = blockers.filter((x) => x.blocking);
+  const next = steps.find((x) => x.status === 'blocked') || steps.find((x) => x.status === 'pending' && x.next) || null;
+  // status-from-artifacts: a document repository gets the one fact that applies to it — the brief or the deliverable
+  // changed after the PM accepted it. Coverage and the status-line check are product-code facts and stay null here.
+  const facts = (opts && opts.facts === false) ? {}
+    : statusFacts.computeArtifacts({ root, L, fm, accepted });
+  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, profile: 'pm-artifacts', track,
+    found: found ? { brief: found.brief.slice(), draft: found.draft.slice(), review: found.review.slice(), handoff: found.handoff.slice() } : null,
+    ...facts,
+    steps, blockers: blockers.map((x) => x.key), gate_failures: gateFailures.map((x) => x.rule || x.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,
+  };
+}
+
+// ── Lifecycle (D70) — a stopped initiative is a ledger line, never a record field ───────────────
+// `lifecycle.jsonl` beside the other ledgers: {initiative_id, state, reason, pm, at}. The latest line
+// for an id wins. `active` reopens. The same reader exists in workspace/lib/lifecycle.js; a parity
+// fixture keeps the two in step. A lifecycle line is never an acceptance and never writes one.
+const STOPPED_STATES = ['closed', 'on-hold', 'cancelled'];
+function readLifecycle(root) {
+  const L = layout(root);
+  const latest = new Map();
+  for (const r of cachedJsonl(path.join(L.runsDir, 'lifecycle.jsonl'))) {
+    if (!r || typeof r.initiative_id !== 'string') continue;
+    if (r.state !== 'active' && !STOPPED_STATES.includes(r.state)) continue;
+    latest.set(r.initiative_id, { state: r.state, reason: r.reason || '', pm: r.pm || '', at: r.at || '' });
+  }
+  return latest;
+}
+function computeWorkflow(id, opts) {
+  const w = computeWorkflowDerived(id, opts);
+  if (!w.ok) return w;
+  const lc = readLifecycle(path.resolve((opts && opts.root) || process.cwd())).get(id);
+  if (!lc || lc.state === 'active') return w;
+  // Stopped: leaves the board and stops gating. The ladder is kept so a reopen shows where it was.
+  return { ...w, stopped: lc, blockers: [], gate_failures: [], next: null,
+    steps: w.steps.map((x) => (x.status === 'blocked' ? { ...x, status: 'pending', blocking: false } : x)) };
+}
+
+// ── 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;
+}
+
+/**
+ * The three status-from-artifacts lines, one plain sentence each with its basis. A flag, never a
+ * step: nothing here is a state, and a missing basis prints nothing (never a pass).
+ */
+function renderFacts(w) {
+  const out = [];
+  const sa = w.since_approval;
+  if (sa) {
+    if (sa.status === 'unknown') out.push(`  ${c(90, '?')} since approval ${c(90, `cannot tell — ${sa.reason}`)}`);
+    else {
+      for (const a of sa.approvals) {
+        const what = a.kind === 'contract' ? 'the contract was approved' : 'the PM accepted';
+        if (a.status === 'unknown') out.push(`  ${c(90, '?')} since approval ${c(90, `${what} (${a.run_id || 'no run id'}) — ${a.reason}`)}`);
+        else if (!a.changed.length) out.push(`  ${c(90, '·')} since approval ${c(90, `no spec file changed since ${what} (${a.approved_sha})`)}`);
+        else {
+          const files = [...new Set(a.changed.map((x) => x.file))].join(', ');
+          const last = a.changed[a.changed.length - 1];
+          out.push(`  ${c(33, '!')} since approval ${files} changed after ${what} (${a.approved_sha}); ${a.changed_total} commit(s), latest ${last.sha} ${last.date || ''}`);
+        }
+      }
+    }
+  }
+  const cv = w.coverage;
+  if (cv) {
+    if (cv.status === 'unknown') out.push(`  ${c(90, '?')} coverage      ${c(90, `cannot tell — ${cv.reason}`)}`);
+    else if (!cv.uncited.length && !cv.orphan_citations.length) out.push(`  ${c(90, '·')} coverage      ${c(90, `all ${cv.requirements} requirement ids are cited in the rubric`)}`);
+    else {
+      const bits = [];
+      if (cv.uncited.length) bits.push(`${cv.uncited.join(', ')} not cited in the rubric`);
+      if (cv.orphan_citations.length) bits.push(`${cv.orphan_citations.join(', ')} cited but not in the PRD`);
+      out.push(`  ${c(33, '!')} coverage      ${bits.join('; ')} (cited is not graded)`);
+    }
+  }
+  const rs = w.record_says;
+  if (rs) out.push(`  ${c(33, '!')} record says    status: ${rs.reason}`);
+  return out;
+}
+
+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))}`);
+  }
+  const flags = renderFacts(w);
+  if (flags.length) { out.push(`  ${c(90, '─'.repeat(78))}`); out.push(...flags); }
+  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))}`);
+  const stoppedList = () => {
+  const stopped = rows.filter((r) => r.ok && r.stopped);
+  if (stopped.length) {
+    out.push(`  ${c(90, `stopped (${stopped.length}) — off the board, not gating:`)}`);
+    for (const r of stopped) out.push(`  ${c(90, `─ ${r.id}  ${r.stopped.state}${r.stopped.at ? ' ' + String(r.stopped.at).slice(0, 10) : ''}${r.stopped.reason ? ' — ' + brief(r.stopped.reason, 60) : ''}`)}`);
+    out.push('');
+  }
+  };
+  if (!shown.length) { out.push(`  ${c(32, 'every initiative here has a recorded acceptance.')}`); out.push(''); stoppedList(); 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.
+  stoppedList();
+  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 && !r.stopped));
+  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; let lanes = 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 === '--lanes') { lanes = 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',
+        '    --lanes        every lane this repository offers: when to use it, input, output, done',
+        '    --json         machine-readable (what an agent reads at session start)', '',
+      ].join('\n') + '\n');
+      return 0;
+    }
+    rest.push(a);
+  }
+  if (lanes) {
+    const info = lanesFor(root);
+    if (json) { process.stdout.write(JSON.stringify(info, null, 2) + '\n'); return 0; }
+    const out = ['', `  ${info.profile} — ${info.lanes.length} lanes`, ''];
+    for (const name of info.lanes) {
+      const d = info.defs[name];
+      out.push(`  ${c(1, name)}${d.label ? ` — ${d.label}` : ''}${d.track ? c(90, `  [${d.track} track]`) : ''}`);
+      out.push(`    when    ${d.when}`);
+      out.push(`    input   ${d.requires || d.input}`);
+      out.push(`    output  ${d.output}`);
+      out.push(`    done    ${d.done}`, '');
+    }
+    process.stdout.write(out.join('\n') + '\n');
+    return 0;
+  }
+  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; }
+    if (w.stopped) { process.stdout.write(`ℹ️  '${w.id}' is ${w.stopped.state} — stopped initiatives do not gate (D70).\n✅ workflow gate PASSED — '${w.id}' is ${w.stopped.state}.\n`); return 0; }
+    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, { recordsDir: layout(root).initiatives });
+  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, readLifecycle, STOPPED_STATES, 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,
+  lanesFor, laneNames,
+  forgetDocumentScan, documentDuplicates, documentCandidates, DOCUMENT_KINDS,
+};
+
+/*
+ * `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);