create-pmos 0.11.0 → 0.11.1

package/README.md

@@ -333,6 +333,28 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.11.1
+
+**Fixes: the ladder never actually worked.** If you installed 0.11.0 and every row in the new
+sidebar read `ladder unreadable` in red — that was us, not your repository.
+
+The engine that derives an initiative's stage, next step and blockers was **not included in any
+published package**. It lives at `scripts/workflow-state.js` in the PMOS repo, and the workspace
+looked for it two directories above itself — a path that exists in a development checkout and in no
+install. The surface 0.11.0 was released for could not run for anyone who installed it.
+
+0.11.1 bundles the engine with the app, and adds the check that would have caught this: publishing
+now **derives a ladder from the packed tarball** and fails if it cannot, rather than only confirming
+that files are present.
+
+So rows now show what 0.11.0 described: lane, derived stage, and the next step or the blocker —
+each one naming the branch it was derived from.
+
+A repository with no `planning/initiatives/` records is no longer an error; it simply has no
+initiatives, and reads calmly. Some of the wording around that is still terser than it should be
+(a folder that is not a git repository currently reports an unreadable branch rather than saying it
+is not a repository) — that is being fixed separately and is a label, not a failure.
+
 ## What's new in 0.11.0
 
 **The workspace navigates by initiative instead of by folder.** If you upgrade and the left column

package/package.json

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

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@cb9565d
+kernel-source: pmos@cae81d8
 assembled: 2026-07-29
 mode: vendor

package/workspace/lib/console-state.js

@@ -126,14 +126,45 @@ function radar({ stateDir, snapshotDir }) {
  * option. It is deliberately not `require`d out of the opened directory: the engine only reads
  * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
  * executed. An install that does not carry the engine gets an honest error, never a blank panel.
+ *
+ * WHERE THE ENGINE ACTUALLY LIVES — the defect this list exists to close (incident
+ * kit-workflow-engine-missing). "Bundled with the workspace" was the INTENT above; packaging never
+ * implemented it. `npm-pkg/package.json` ships only bin/ payload/ workspace/, so in a published
+ * install there is no repo two levels up and `../../scripts/workflow-state.js` resolves to nothing.
+ * Every adopter row read "ladder unreadable" from 0.11.0 back to whenever this surface shipped —
+ * the ladder had never once run outside a PMOS checkout. Two locations, tried in order:
+ *
+ *   1. `../../scripts/workflow-state.js` — a repo checkout (PMOS-self, any dev clone). Preferred on
+ *      purpose: it is the very file `.github/scripts/initiative-gate.sh` executes, so a developer's
+ *      panel can never disagree with what CI is about to print on their PR.
+ *   2. `lib/engine/workflow-state.js` — the copy the publish step vendors into the bundle. This is
+ *      what an adopter runs, and the only reason the ladder derives at all outside this repo.
+ *
+ * ABSENT and BROKEN are answered differently, because they are different facts (R10). A path that
+ * does not exist means "try the next one"; a path that exists and throws is a real fault in an
+ * engine that IS installed, and reporting that as "not present" would send the PM looking for a
+ * packaging bug they do not have.
  */
+const ENGINE_PATHS = [
+  path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js'),
+  path.join(__dirname, 'engine', 'workflow-state.js'),
+];
+function loadEngine() {
+  const tried = [];
+  for (const p of ENGINE_PATHS) {
+    if (!fs.existsSync(p)) { tried.push(p); continue; }
+    try { return { ok: true, engine: require(p), from: p }; }
+    catch (e) {
+      return { ok: false, error: `the workflow engine at ${p} is installed but failed to load — ${String((e && e.message) || e).slice(0, 160)}` };
+    }
+  }
+  return { ok: false, error: `the workflow engine is not present in this install — the ladder cannot be derived here (looked in: ${tried.join(', ')})` };
+}
 function workflow({ root }) {
   if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
-  let engine;
-  try { engine = require(path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js')); }
-  catch {
-    return { ok: false, error: 'the workflow engine (scripts/workflow-state.js) is not present in this install — the ladder cannot be derived here' };
-  }
+  const loaded = loadEngine();
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const engine = loaded.engine;
   let ids;
   try { ids = engine.listInitiatives(root); }
   catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
@@ -189,4 +220,6 @@ function workflow({ root }) {
   };
 }
 
-module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl };
+// ENGINE_PATHS/loadEngine are exported for the packaging guard in workspace/test.js: the incident
+// that made them a list was invisible to every unit test precisely because resolution was inline.
+module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };

package/workspace/lib/engine/anchor-resolve.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS anchor resolution — the one place a `parent_kr` string becomes a structured answer.
+ *
+ *   const A = require('./anchor-resolve');
+ *   const index = A.parseOkrIndex(root);          // what the OKR documents actually declare
+ *   const r     = A.resolveAnchor(raw, index);    // { kind, objective, kr, status, ... }
+ *   A.canonical(r)                                // the one normative written form
+ *
+ * WHY THIS EXISTS. Before this module, `parent_kr` was a string that nothing dereferenced. The
+ * ladder's R1 passed any non-empty value that did not contain `health:` as `done` without ever
+ * opening the OKR documents — so `parent_kr: banana` passed, and so did an anchor naming a KR that
+ * existed in no file (`q3-2026:integrity:kr-a` and `:kr-b` did exactly that for two days). The
+ * workspace's OKR surface, meanwhile, never read `parent_kr` at all. One field, several readers,
+ * none of them agreeing what it meant. See
+ * planning/explainers/okr-anchor-resolution-surface-explainer.md.
+ *
+ * THREE RULES, all load-bearing (planning/prd/anchor-normalization-spec.md R-2/R-3/R-4):
+ *
+ *   1. PERMANENTLY BACKWARD-COMPATIBLE (R-2). Every syntax present in the corpus at authoring time
+ *      is accepted, and keeps being accepted — not behind a migration window. The kit ships to
+ *      adopters as `create-pmos` (D55), so records written in the legacy forms exist in repos no
+ *      rewrite here can reach. ACCEPTED_FORMS below is that enumeration, and it is a promise.
+ *
+ *   2. HEALTH IS A FORM TEST, NEVER A SUBSTRING SEARCH (R-3). The corpus contains
+ *      `okrs-q3-2026 → O1.KR1    # or health:<id> from planning/okrs/health-budgets.md` — an OKR
+ *      anchor whose *commentary* mentions health. A substring search classifies it as a health
+ *      anchor and then rejects it as an undeclared budget: recognised, then refused, for a reason
+ *      that is not the reader's fault. Classification therefore tests the START of the value.
+ *
+ *   3. THE OBJECTIVE AND KR PATTERNS WIDEN TOGETHER (R-4). Widening the objective pattern alone
+ *      would let a previously-unmatched KR attach to the *previous matched* objective rather than
+ *      stay unmatched — a silent mis-filing, which is worse than the omission it replaces.
+ *
+ * HONESTY BY CONSTRUCTION. `status` is one of `resolved` · `unresolvable` · `empty` · `unknown`.
+ * `unknown` means the OKR documents could not be read and never collapses into either a pass or a
+ * failure — a resolver that cannot see its inputs says so rather than guessing. Nothing in this
+ * module blocks anything: per the spec's assumption A1 the gates keep accepting any non-empty
+ * anchor, and the RED belongs to the surface. This module reports; callers decide.
+ *
+ * Zero dependencies, stock Node. Runs in CI, in the ladder, and inside the workspace server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/*
+ * The census, from the explainer, as executable documentation. Each entry is a real form found in
+ * planning/initiatives/ at authoring time (2026-07-28). Adding a form here without a matching
+ * pattern below, or vice versa, is the drift this list exists to make visible — the test suite
+ * asserts every example resolves.
+ */
+const ACCEPTED_FORMS = [
+  { example: 'health:tech',                    note: 'D59 registry form, bare' },
+  { example: 'health:tech (D59 — commentary)', note: 'registry form with trailing commentary' },
+  { example: 'q3-2026:o1:kr1',                 note: 'CANONICAL — colon triple' },
+  { example: 'q3-2026:integrity:kr-a',         note: 'canonical, non-numeric objective + KR ids' },
+  { example: 'Q3-2026:O1:KR2',                 note: 'canonical, upper-case variant' },
+  { example: 'okrs-q3-2026 → O1.KR1',          note: 'legacy arrow form, filename-prefixed' },
+  { example: 'okrs-q3-2026 → O1',              note: 'legacy arrow, objective only (no KR)' },
+  { example: 'q3-2026 → O1.KR2',               note: 'legacy arrow, period-prefixed' },
+  { example: 'O1.KR3',                         note: 'legacy bare objective.KR' },
+  { example: '**O1**',                         note: 'legacy bare objective, markdown-bolded' },
+  { example: "okrs-q3-2026 → O2.KR2 / B4 (Cohen's kappa)", note: 'trailing commentary after a slash' },
+  { example: 'okrs-q3-2026 → O1.KR1    # or health:<id> from planning/okrs/health-budgets.md',
+    note: 'R-3 trap: OKR anchor whose COMMENTARY mentions health — must classify as okr' },
+];
+
+/*
+ * Objective and KR tokens are deliberately NOT `O\w+` / `KR\w+`. The OKR document's own H1 is
+ * `# OKRs — Q3 2026`, and a loose objective pattern matches `OKRs` there, inventing an objective
+ * called `okrs` that every subsequent KR would then attach to. The shape is therefore pinned:
+ * an objective is `O` + digits, or `O-` + a word; a KR is `KR` + digits, or `KR-` + a word.
+ */
+const OBJ_TOKEN = '(O\\d+|O-[A-Za-z][A-Za-z0-9-]*)';
+const KR_TOKEN = '(KR\\d+|KR-[A-Za-z][A-Za-z0-9-]*)';
+const PERIOD = '((?:q|Q)[1-4]-\\d{4})';
+
+const RE_OBJ_HEADING = new RegExp('^#{1,3}\\s+' + OBJ_TOKEN + '\\s*(?:[—–:-]\\s*(.*))?$');
+const RE_KR_BULLET = new RegExp('^\\s*[-*]\\s*\\*\\*\\s*' + KR_TOKEN + '\\s*[—–:-]?\\s*(.+?)\\*\\*');
+
+// Anchor forms. Order matters only in that the colon forms are tried before the looser ones.
+const RE_HEALTH = /^health:([a-z0-9_-]+)/i;                       // START-anchored — rule 2
+const RE_COLON_KR = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*):(kr-?[a-z0-9-]+)$', 'i');
+const RE_COLON_OBJ = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*)$', 'i');
+const RE_ARROW = new RegExp('^(?:okrs-)?' + PERIOD + '\\s*(?:→|->)\\s*' + OBJ_TOKEN + '(?:\\.' + KR_TOKEN + ')?$', 'i');
+const RE_BARE = new RegExp('^' + OBJ_TOKEN + '(?:\\.' + KR_TOKEN + ')?$', 'i');
+
+/** Strip markdown emphasis and trailing commentary. `(`, `#` and `/` never appear inside an id. */
+function stripCommentary(raw) {
+  let s = String(raw == null ? '' : raw).replace(/\*\*/g, '').trim();
+  const cut = s.search(/[(#/]/);
+  if (cut >= 0) s = s.slice(0, cut);
+  return s.trim();
+}
+
+/** `O-INTEGRITY` → `integrity`; `O1` → `o1`. The anchors write `integrity`, the heading writes
+ *  `O-INTEGRITY`; the explainer flagged that a widened parser must pick one. This picks: the id is
+ *  the heading token minus a leading `O-`, lower-cased. */
+function objectiveId(token) {
+  const t = String(token || '').trim();
+  const m = /^O-(.+)$/i.exec(t);
+  return (m ? m[1] : t).toLowerCase();
+}
+
+/** `KR1` → `kr1`; `KR-C` → `kr-c`. Case only. */
+function krId(token) {
+  return String(token || '').trim().toLowerCase();
+}
+
+function listOkrFiles(root) {
+  const out = [];
+  const seen = new Set();
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'okrs') {
+          let files;
+          try { files = fs.readdirSync(full); } catch { continue; }
+          for (const f of files) {
+            if (!f.endsWith('.md')) continue;
+            const p = path.join(full, f);
+            if (!seen.has(p)) { seen.add(p); out.push(p); }
+          }
+        } else walk(full, depth + 1);
+      }
+    }
+  };
+  walk(root, 0);
+  return out.sort();
+}
+
+/**
+ * Read every OKR document under `root` and return what they declare.
+ * → { ok, objectives: [{id, token, name, krs:[{id, token, name}], file}], files, error }
+ * `ok:false` is a genuine read failure and must render as an error, never as "no objectives".
+ */
+function parseOkrIndex(root) {
+  const files = listOkrFiles(root);
+  if (!files.length) {
+    return { ok: false, objectives: [], files: [], error: 'no OKR documents found under ' + root };
+  }
+  const objectives = [];
+  const byId = new Map();
+  let period = null;
+  for (const file of files) {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); }
+    catch (e) {
+      return { ok: false, objectives: [], files, error: `could not read ${file}: ${String((e && e.message) || e).slice(0, 120)}` };
+    }
+    let cur = null;
+    for (const line of text.split('\n')) {
+      if (!period) {
+        const p = /^\s*[-*]?\s*period\s*:\s*(\d{4})-(Q[1-4])\s*$/i.exec(line);
+        if (p) period = `${p[2].toLowerCase()}-${p[1]}`;
+      }
+      const o = RE_OBJ_HEADING.exec(line);
+      if (o) {
+        const id = objectiveId(o[1]);
+        cur = byId.get(id);
+        if (!cur) {
+          cur = { id, token: o[1], name: (o[2] || '').replace(/\*\*/g, '').trim(), krs: [], file: path.relative(root, file) };
+          byId.set(id, cur);
+          objectives.push(cur);
+        }
+        continue;
+      }
+      const k = RE_KR_BULLET.exec(line);
+      // A KR with no open objective stays UNATTACHED (rule 3) — never inherited from a previous one.
+      if (k && cur && !cur.krs.some((x) => x.id === krId(k[1]))) {
+        cur.krs.push({ id: krId(k[1]), token: k[1], name: (k[2] || '').trim() });
+      }
+    }
+  }
+  return { ok: true, objectives, files: files.map((f) => path.relative(root, f)), period: period || null, error: null };
+}
+
+function readBudgets(root) {
+  const p = path.join(root, 'planning', 'okrs', 'health-budgets.md');
+  try { return { ok: true, text: fs.readFileSync(p, 'utf8'), path: path.relative(root, p) }; }
+  catch { return { ok: false, text: '', path: path.relative(root, p) }; }
+}
+
+/**
+ * Resolve one raw `parent_kr` value.
+ * → { raw, kind, status, objective, kr, budget, period, form, reason }
+ *   kind   : 'health' | 'okr' | 'empty'
+ *   status : 'resolved' | 'unresolvable' | 'empty' | 'unknown'
+ * `index` comes from parseOkrIndex; `budgets` from readBudgets (optional — omit to skip the
+ * registry check, which callers that only need the FORM can do).
+ */
+function resolveAnchor(raw, index, budgets) {
+  const original = String(raw == null ? '' : raw).trim();
+  const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
+  if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
+
+  // Rule 2: the FORM decides, not a substring. Commentary is stripped only for the OKR branch,
+  // because a health anchor's id must sit at the very start of the raw value.
+  const h = RE_HEALTH.exec(original);
+  if (h) {
+    const id = h[1].toLowerCase();
+    const out = Object.assign({}, base, { kind: 'health', budget: id, form: 'health:<id>' });
+    if (!budgets) return Object.assign(out, { status: 'unknown', reason: 'health budget registry not supplied to the resolver' });
+    if (!budgets.ok) return Object.assign(out, { status: 'unknown', reason: `health-budget registry unreadable at ${budgets.path}` });
+    // Same case handling as the classifier (R-3): recognised case-insensitively, looked up the same way.
+    const declared = new RegExp('health:' + id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i').test(budgets.text);
+    return declared
+      ? Object.assign(out, { status: 'resolved', reason: `declared in ${budgets.path}` })
+      : Object.assign(out, { status: 'unresolvable', reason: `health:${id} is not a declared budget in ${budgets.path}` });
+  }
+
+  const s = stripCommentary(original);
+  if (!s) {
+    return Object.assign(base, { kind: 'okr', status: 'unresolvable', reason: 'no anchor left after commentary was stripped' });
+  }
+
+  let period = null, objTok = null, krTok = null, form = null;
+  let m;
+  if ((m = RE_COLON_KR.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; krTok = m[3]; form = 'q3-2026:<objective>:<kr>'; }
+  else if ((m = RE_COLON_OBJ.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; form = 'q3-2026:<objective>'; }
+  else if ((m = RE_ARROW.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; krTok = m[3] || null; form = 'legacy arrow'; }
+  else if ((m = RE_BARE.exec(s))) { objTok = m[1]; krTok = m[2] || null; form = 'legacy bare'; }
+  else {
+    return Object.assign(base, { kind: 'okr', status: 'unresolvable', form: 'unrecognised', reason: `'${s}' matches no accepted anchor form` });
+  }
+
+  const out = Object.assign({}, base, {
+    kind: 'okr', form, period,
+    objective: objectiveId(objTok),
+    kr: krTok ? krId(krTok) : null,
+  });
+
+  if (!index) return Object.assign(out, { status: 'unknown', reason: 'OKR index not supplied to the resolver' });
+  if (!index.ok) return Object.assign(out, { status: 'unknown', reason: index.error || 'OKR documents unreadable' });
+
+  const obj = index.objectives.find((o) => o.id === out.objective);
+  if (!obj) {
+    return Object.assign(out, { status: 'unresolvable', reason: `objective '${out.objective}' is not declared in ${index.files.join(', ')}` });
+  }
+  if (!out.kr) {
+    // Assumption A2: objective-only anchoring is a legitimate resolvable kind, not debt.
+    return Object.assign(out, { status: 'resolved', reason: `objective '${obj.id}' — no KR written (objective-level anchor)` });
+  }
+  const kr = obj.krs.find((k) => k.id === out.kr);
+  if (!kr) {
+    return Object.assign(out, { status: 'unresolvable', reason: `objective '${obj.id}' declares no KR '${out.kr}' (has: ${obj.krs.map((k) => k.id).join(', ') || 'none'})` });
+  }
+  return Object.assign(out, { status: 'resolved', reason: `${obj.id}/${kr.id} — ${kr.name}`.slice(0, 160) });
+}
+
+/**
+ * The one normative written form (R-1, as amended 2026-07-28 by PM decision).
+ * Returns null when the input does not resolve to something writable — callers must not invent one.
+ */
+function canonical(resolved, fallbackPeriod) {
+  if (!resolved) return null;
+  if (resolved.kind === 'health') return resolved.budget ? `health:${resolved.budget}` : null;
+  if (resolved.kind !== 'okr' || !resolved.objective) return null;
+  const period = resolved.period || fallbackPeriod || null;
+  if (!period) return null;
+  return resolved.kr ? `${period}:${resolved.objective}:${resolved.kr}` : `${period}:${resolved.objective}`;
+}
+
+module.exports = {
+  parseOkrIndex, readBudgets, resolveAnchor, canonical,
+  objectiveId, krId, stripCommentary, listOkrFiles,
+  ACCEPTED_FORMS,
+  // exported for the tests that assert the widening happened together (R-4)
+  RE_OBJ_HEADING, RE_KR_BULLET,
+};

package/workspace/lib/engine/workflow-state.js

@@ -0,0 +1,878 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS workflow state — the derivation engine.
+ *
+ *   node scripts/workflow-state.js                 the board: every initiative, stage + blocker
+ *   node scripts/workflow-state.js <id>            the ladder for one initiative
+ *   node scripts/workflow-state.js <id> --json     the same, machine-readable
+ *   node scripts/workflow-state.js --gate <id>     CI: exit 1 on a BLOCKING order violation
+ *   node scripts/workflow-state.js --open          the board, open initiatives only
+ *     --root <dir>   operate on another repo root (fixtures, tenant workspaces)
+ *
+ * WHY THIS EXISTS. The Initiative Gate asserts that a lane's spec artifacts EXIST when CI runs. It
+ * has never asserted that they came FIRST. A PRD written after the implementation, in the same PR,
+ * satisfies it byte-for-byte identically to one written before — so "eval-driven PM" (D13),
+ * "prototype before PRD" (D60) and "explain the surface before you spec it" were norms with nothing
+ * behind them. See planning/prd/workflow-enforcement-prd.md §2 for the seven holes this closes.
+ *
+ * TWO DESIGN RULES, both load-bearing:
+ *
+ *   1. DERIVED, NEVER DECLARED. There is deliberately no `stage:` key. Stage and step status are
+ *      computed from the record's frontmatter, the files it points at, the append-only rows in
+ *      planning/runs/*.jsonl, and git's own first-appearance history. A status field nobody updates
+ *      is a board that lies, and a board that lies is a watermelon generator — worse than no board.
+ *
+ *   2. ORDER COMES FROM GIT, NOT FROM TIMESTAMPS. Author/commit dates are rewritten by rebases and
+ *      can tie within a second. So ordering compares POSITION IN THE COMMIT RANGE (oldest = 0),
+ *      never clock time. A path introduced before the range is index -1 (it already existed); a path
+ *      on disk that no commit has added yet is Infinity (uncommitted).
+ *
+ * HONESTY BY CONSTRUCTION. Every step carries one of: done · current · blocked · pending · n/a ·
+ * unknown. `unknown` is its own state and never collapses into `done` or `n/a` — a shallow clone or
+ * an unreadable input must be visibly distinct from a satisfied step. A gate that cannot see its
+ * inputs reports that it cannot see them; it never reports a pass.
+ *
+ * Zero dependencies, stock Node. It runs in CI, in a terminal, and inside the workspace server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+/*
+ * ONE resolver, shared with the workspace (spec R-6 / contract C-7). Two readers that disagreed
+ * about whether an anchor resolves would reproduce the exact defect this work removes — the ladder
+ * and the OKR surface previously held separate, incompatible opinions about the same field.
+ */
+const anchors = require('./anchor-resolve');
+
+// The OKR documents and the budget registry are read once per root, not once per initiative: the
+// board derives ~100 ladders in a single pass and re-reading the same three files each time is the
+// same waste the shared commit-range exists to avoid.
+const _okrCache = new Map();
+const _budCache = new Map();
+function okrIndexFor(root) {
+  if (!_okrCache.has(root)) _okrCache.set(root, anchors.parseOkrIndex(root));
+  return _okrCache.get(root);
+}
+function budgetsFor(root, L) {
+  if (!_budCache.has(root)) {
+    try { _budCache.set(root, { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }); }
+    catch { _budCache.set(root, { ok: false, text: '', path: path.relative(root, L.budgets) }); }
+  }
+  return _budCache.get(root);
+}
+
+/*
+ * ── Enforcement boundary ──────────────────────────────────────────────────────────────────────
+ * An initiative is LEGACY when its record already existed before the change under review — i.e. its
+ * record first-appeared outside this commit range. Legacy records are reported and never failed by
+ * the rules introduced here (R0/O3/O4/O5/O6/O7); the original artifact-existence contract (R1/R2)
+ * binds everywhere, because it always did.
+ *
+ * The boundary is DERIVED FROM GIT, not from the record's own `timestamp:` frontmatter. A
+ * self-declared date is a field the record controls, so backdating it would grandfather you out of
+ * your own gate — the one thing a compliance boundary must not permit. Git's add-date is written by
+ * the commit, not by the author of the file's contents.
+ *
+ * `ENFORCED_FROM` is only the FALLBACK, used when git cannot answer (no history, a fresh fixture
+ * repo, a shallow clone). It is deliberately not the primary test.
+ *
+ * The 92 records that predate this are NOT backfilled. Inventing a specimen-test answer for work
+ * already shipped would be fabricating a judgement nobody made, and a gate whose history is
+ * fabricated is worth less than no gate at all.
+ */
+const ENFORCED_FROM = '2026-07-28';
+
+// A path counts as BUILD when it is neither a planning artifact nor documentation. `prototype/` is
+// build only in the prototype lane, where the specimen IS the deliverable (D60); in every other lane
+// a prototype directory is somebody else's leg-A work and must not count as this initiative's build.
+function isBuildPath(p, lane) {
+  if (!p) return false;
+  if (p.startsWith('planning/') || p.startsWith('okf/') || p.startsWith('pmos/state/')) return false;
+  if (p.startsWith('prototype/')) return lane === 'prototype';
+  if (p.endsWith('.md')) return false;               // docs, incl. root governance files
+  return true;
+}
+
+// ── Frontmatter ────────────────────────────────────────────────────────────────────────────────
+// The LEADING block only — body text must never be able to fake a declaration. Mirrors
+// workspace/lib/file-mode-parse.js and kit/scripts/metrics.py, plus the surrounding-quote strip the
+// bash gate does, so all four readers agree on what a record declared.
+function parseLeadingFrontmatter(text) {
+  const fm = {};
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    const m = line.match(/^([a-z_]+):\s*(.*?)\s*$/);
+    if (m) {
+      if (!(m[1] in fm)) fm[m[1]] = m[2].replace(/^"(.*)"$/s, '$1');
+      continue;
+    }
+    if (line.trim() && !line.startsWith('---')) break;
+  }
+  return fm;
+}
+function readFrontmatter(file) {
+  try { return parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+function readJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* torn line — dropped, never guessed */ }
+  }
+  return out;
+}
+
+// ── Repo layout — pmos-self and the kit disagree on where state lives, so detect rather than assume
+function layout(root) {
+  const selfDir = path.join(root, 'planning', 'initiatives');
+  const kitDir = path.join(root, 'pmos', 'state', 'initiatives');
+  const isKit = !fs.existsSync(selfDir) && fs.existsSync(kitDir);
+  return {
+    root,
+    kit: isKit,
+    initiatives: isKit ? kitDir : selfDir,
+    runsDir: isKit ? path.join(root, 'pmos', 'state') : path.join(root, 'planning', 'runs'),
+    runsFile: isKit ? 'runs.jsonl' : 'agent-runs.jsonl',
+    explainers: isKit
+      ? path.join(root, 'pmos', 'state', 'explainers')
+      : path.join(root, 'planning', 'evals', 'explainers'),
+    budgets: isKit
+      ? path.join(root, 'pmos', 'state', 'health-budgets.md')
+      : path.join(root, 'planning', 'okrs', 'health-budgets.md'),
+  };
+}
+
+// ── Git ────────────────────────────────────────────────────────────────────────────────────────
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+/*
+ * The commit range this initiative's work lives in, oldest first, as sha -> index.
+ *
+ * In CI that is base..HEAD for the PR. Locally it is the merge-base with the default branch. When
+ * neither resolves — a shallow clone, a detached checkout with no base — the range is NULL and every
+ * order check downgrades to `unknown`. It does not downgrade to `pass`: an order rule that cannot be
+ * evaluated has not been satisfied, and saying so is the whole point of the honesty rule above.
+ */
+function commitRange(root) {
+  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)' };
+  }
+  const candidates = [];
+  if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
+  candidates.push('origin/main', 'main', 'origin/master', 'master');
+  let base = null;
+  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; }
+  }
+  const spec = base ? `${base}..HEAD` : 'HEAD';
+  const log = git(root, ['log', '--reverse', '--format=%H', spec]);
+  if (log == null) return { ok: false, reason: 'git history unreadable' };
+  const shas = log.split('\n').map((s) => s.trim()).filter(Boolean);
+  const index = new Map();
+  shas.forEach((sha, i) => index.set(sha, i));
+  return { ok: true, base, index, shas, wholeHistory: !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;
+  const log = git(root, ['log', '--diff-filter=A', '--reverse', '--format=%H', '--', rel]);
+  const sha = log ? log.split('\n').map((s) => s.trim()).filter(Boolean)[0] : null;
+  if (!sha) return onDisk ? Infinity : null;
+  return range.index.has(sha) ? range.index.get(sha) : -1;
+}
+
+// The earliest position in the range at which this initiative's implementation was touched, plus a
+// count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
+// reported as n/a rather than as a pass it did not earn.
+function buildCommits(root, range, lane) {
+  if (!range.ok) return { unknown: true };
+  let first = null; let count = 0; let sample = null;
+  for (let i = 0; i < range.shas.length; i++) {
+    const files = git(root, ['show', '--name-only', '--format=', range.shas[i]]);
+    if (!files) continue;
+    const hit = files.split('\n').map((s) => s.trim()).filter(Boolean).find((f) => isBuildPath(f, lane));
+    if (!hit) continue;
+    count++;
+    if (first === null) { first = i; sample = hit; }
+  }
+  return { first, count, sample };
+}
+
+// ── Declaration readers ────────────────────────────────────────────────────────────────────────
+// Both keys are a LEADING TOKEN from a closed set followed by free prose. The token is what the gate
+// reads; the prose is the agent's reasoning for the PM. Closed-enum-only was rejected: D60's 2026-07-24
+// amendment widened the lane past UI work precisely because the interesting part is the reasoning.
+function specimenRoute(v) {
+  const t = String(v || '').trim().toLowerCase();
+  if (!t) return 'undeclared';
+  if (t.startsWith('needs-instance')) return 'instance';
+  if (t.startsWith('description-judgeable')) return 'description';
+  return 'malformed';
+}
+// The `priors` citation on a run record — the episodic read AGENTS.md step 3 mandates, written down.
+// Two shapes are accepted deliberately: the bare list (`priors: ["run-a"]`) for the common case, and
+// the object form (`priors: {consulted: [...], note: "…"}`) when the run needs to say WHY it consulted
+// nothing. Anything else returns `malformed` rather than falling through to "absent" — a field that is
+// present but unreadable must never be scored the same as a field nobody wrote, because the two call
+// for opposite fixes.
+function priorsCitation(run) {
+  if (!run || !('priors' in run) || run.priors === null) return { declared: false };
+  const p = run.priors;
+  if (Array.isArray(p)) return { declared: true, consulted: p.map((x) => String(x).trim()), note: '' };
+  if (typeof p === 'object') {
+    if (!('consulted' in p)) return { declared: true, malformed: 'priors object has no `consulted` key' };
+    if (!Array.isArray(p.consulted)) return { declared: true, malformed: '`priors.consulted` is not a list of run ids' };
+    return {
+      declared: true,
+      consulted: p.consulted.map((x) => String(x).trim()),
+      note: String(p.note == null ? '' : p.note).trim(),
+    };
+  }
+  return { declared: true, malformed: 'priors is neither a list of run ids nor {consulted, note}' };
+}
+
+function surfaceRoute(v) {
+  const t = String(v || '').trim().toLowerCase();
+  if (!t) return 'undeclared';
+  if (t.startsWith('existing')) return 'existing';
+  if (t.startsWith('greenfield')) return 'greenfield';
+  return 'malformed';
+}
+
+// ── Step model ─────────────────────────────────────────────────────────────────────────────────
+// status ∈ done | current | blocked | pending | na | unknown
+// `blocking` marks a step whose failure fails CI. O5/O6/O7 are deliberately NOT blocking: none can
+// be true before the diff exists, and a rule enforced at a moment it cannot be satisfied only
+// teaches people to reach for the escape hatch.
+function step(key, label, status, evidence, next, opts) {
+  return {
+    key, label, status, evidence: evidence || null, next: next || null,
+    blocking: !!(opts && opts.blocking), rule: (opts && opts.rule) || null,
+  };
+}
+
+function computeWorkflow(id, opts) {
+  const root = path.resolve((opts && opts.root) || process.cwd());
+  const L = layout(root);
+  const recRel = path.relative(root, path.join(L.initiatives, `${id}.md`));
+  const recAbs = path.join(L.initiatives, `${id}.md`);
+  if (!fs.existsSync(recAbs)) {
+    return { ok: false, id, error: `no initiative record at ${recRel} — an initiative must exist before its work` };
+  }
+  const fm = readFrontmatter(recAbs) || {};
+  const lane = (fm.lane || 'feature').trim() || 'feature';
+  const knownLane = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'].includes(lane);
+  const effLane = knownLane ? lane : 'feature';           // unknown lane = strictest, as the bash gate does
+  const range = (opts && opts.range) || commitRange(root);
+  // See ENFORCED_FROM: git decides, the frontmatter only breaks a tie git cannot see.
+  const recIdx = firstAppearance(root, range, recRel);
+  const legacy = (recIdx === undefined || recIdx === null)
+    ? String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM   // fallback only — see ENFORCED_FROM
+    : recIdx === -1;
+  /*
+   * `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.
+   */
+  const inChange = recIdx !== -1 && recIdx !== null && recIdx !== undefined;
+  const lastActivity = (() => {
+    const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
+    const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
+    const t = out && parseInt(out.trim(), 10);
+    return Number.isFinite(t) ? t : null;
+  })();
+  const steps = [];
+
+  // ── route ─ the lane is chosen and the two intake questions are answered ─────────────────────
+  const sRoute = specimenRoute(fm.specimen_test);
+  const fRoute = surfaceRoute(fm.surface_check);
+  {
+    const missing = [];
+    if (sRoute === 'undeclared' || sRoute === 'malformed') missing.push('specimen_test');
+    if (fRoute === 'undeclared' || fRoute === 'malformed') missing.push('surface_check');
+    if (!missing.length) {
+      steps.push(step('route', 'route', 'done',
+        `${lane} lane · specimen test ${sRoute} · surface ${fRoute}`));
+    } else if (legacy) {
+      steps.push(step('route', 'route', 'unknown',
+        `${lane} lane · ${missing.join(' + ')} not declared (record predates ${ENFORCED_FROM})`));
+    } else {
+      const how = missing.map((k) => k === 'specimen_test'
+        ? 'specimen_test: "description-judgeable — …" or "needs-instance — …"'
+        : 'surface_check: "greenfield — …" or "existing — …"').join('; ');
+      steps.push(step('route', 'route', 'blocked',
+        `${missing.join(' + ')} ${missing.length > 1 ? 'are' : 'is'} ${sRoute === 'malformed' || fRoute === 'malformed' ? 'malformed' : 'not declared'}`,
+        `run the pmos-router skill and record its answers in ${recRel} — ${how}`,
+        { blocking: true, rule: 'R0' }));
+    }
+  }
+
+  // ── anchor ─ every initiative anchors to a KR or a declared health budget (D59) ──────────────
+  {
+    const anchor = String(fm.parent_kr || '').trim();
+    const r = anchors.resolveAnchor(anchor, okrIndexFor(root), budgetsFor(root, L));
+    const budRel = path.relative(root, L.budgets);
+    if (r.kind === 'empty') {
+      steps.push(step('anchor', 'anchor', legacy ? 'unknown' : 'blocked',
+        'parent_kr is empty — unanchored work is rejected (D59)',
+        `set parent_kr in ${recRel} to a KR, or to health:<id> from ${budRel}`,
+        { blocking: !legacy, rule: 'R1' }));
+    } else if (r.status === 'unknown') {
+      steps.push(step('anchor', 'anchor', 'unknown', `${anchor} — ${r.reason}`));
+    } else if (r.kind === 'health') {
+      if (r.status === 'resolved') {
+        steps.push(step('anchor', 'anchor', 'done', `health:${r.budget} — declared in ${budRel}`));
+      } else {
+        steps.push(step('anchor', 'anchor', legacy ? 'unknown' : 'blocked',
+          `health:${r.budget} is not a declared budget`,
+          `only the PM adds a budget — use an existing id from ${budRel} or anchor to a KR`,
+          { blocking: !legacy, rule: 'R1' }));
+      }
+    } else if (r.status === 'resolved') {
+      steps.push(step('anchor', 'anchor', 'done',
+        `${anchors.canonical(r, (okrIndexFor(root) || {}).period) || anchor} — ${r.reason}`));
+    } else {
+      // REPORTED, NEVER CI-BLOCKING (spec assumption A1). The anchor names an objective or KR the
+      // OKR documents do not declare — which is exactly the class that went unnoticed for two days
+      // (`q3-2026:integrity:kr-a` and `:kr-b` were anchored by three initiatives and written in no
+      // file). It is shown as a failed step so it cannot hide, and deliberately does NOT fail CI:
+      // making it blocking would turn one typo into a hard failure on every unrelated PR, and the
+      // recorded intent put the RED in the surface, not the gate. Raising it to blocking is a
+      // separate PM decision (spec Open questions), not a thing to slip in with a resolver.
+      steps.push(step('anchor', 'anchor', 'blocked',
+        `${anchor} — ${r.reason}`,
+        `write an anchor that names something the OKR documents declare, or add the KR (a PM act) — see ${budRel} for the health form`,
+        { blocking: false, rule: 'R1' }));
+    }
+  }
+
+  const prd = String(fm.prd_path || '').trim();
+  const rubric = String(fm.rubric_path || '').trim();
+  const prdIdx = prd ? firstAppearance(root, range, prd) : null;
+  const build = buildCommits(root, range, effLane);
+
+  // 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();
+    if (sRoute !== 'instance') {
+      steps.push(step('prototype', 'prototype', 'na',
+        sRoute === 'description' ? 'specimen test says description-judgeable — routed straight to spec, untaxed'
+          : 'specimen test not declared'));
+    } else if (!pred) {
+      steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+        'specimen_test says needs-instance but no predecessor is named',
+        'run the prototype lane first (skills/core/prototype.skill), then set predecessor: <prototype-id>',
+        { blocking: !legacy, rule: 'O3' }));
+    } else {
+      const predAbs = path.join(L.initiatives, `${pred}.md`);
+      const predFm = readFrontmatter(predAbs);
+      if (!predFm) {
+        steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+          `predecessor '${pred}' has no initiative record at ${path.relative(root, predAbs)}`,
+          'name a prototype-lane initiative that exists, or correct predecessor:',
+          { blocking: !legacy, rule: 'O3' }));
+      } else if ((predFm.lane || '').trim() !== 'prototype') {
+        steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+          `predecessor '${pred}' is lane '${predFm.lane || 'feature'}', not prototype`,
+          'the specimen test is answered by a prototype leg — point predecessor: at one',
+          { blocking: !legacy, rule: 'O3' }));
+      } else {
+        const brief = String(predFm.prd_path || '').trim();
+        const briefIdx = brief ? firstAppearance(root, range, brief) : null;
+        const ok = ordered(briefIdx, prdIdx);
+        if (ok === null) {
+          steps.push(step('prototype', 'prototype', 'unknown',
+            `predecessor ${pred} present; order undecidable (${range.ok ? 'a path is missing' : range.reason})`));
+        } else if (ok) {
+          steps.push(step('prototype', 'prototype', 'done', `${pred} — brief ${brief} first-appeared before ${prd}`));
+        } else {
+          steps.push(step('prototype', 'prototype', legacy ? 'unknown' : 'blocked',
+            `ORDER VIOLATION — the PRD (${prd}) first-appeared BEFORE the prototype brief (${brief})`,
+            'the prototype is what validates the direction the PRD then specifies — it cannot follow it (D60)',
+            { blocking: !legacy, rule: 'O3' }));
+        }
+      }
+    }
+  }
+
+  // ── understand ─ O4: an existing surface is explained BEFORE it is specified ─────────────────
+  {
+    const expl = String(fm.explainer_path || '').trim();
+    if (fRoute !== 'existing') {
+      steps.push(step('understand', 'understand', 'na',
+        fRoute === 'greenfield' ? 'greenfield — nothing existing to explain first' : 'surface check not declared'));
+    } else if (!expl) {
+      steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+        'surface_check says existing but no explainer_path is set',
+        'run build-skills/explain-surface.skill in a FRESH context (not the agent that will write the spec), then set explainer_path:',
+        { blocking: !legacy, rule: 'O4' }));
+    } else if (!fs.existsSync(path.join(root, expl))) {
+      steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+        `explainer_path '${expl}' does not exist in the repo`,
+        'set explainer_path to a real explain-surface output',
+        { blocking: !legacy, rule: 'O4' }));
+    } else {
+      const eIdx = firstAppearance(root, range, expl);
+      const ok = ordered(eIdx, prdIdx);
+      if (ok === null) {
+        steps.push(step('understand', 'understand', 'unknown',
+          `${expl} present; order undecidable (${range.ok ? 'no spec artifact to order against' : range.reason})`));
+      } else if (ok) {
+        steps.push(step('understand', 'understand', 'done', `${expl} — first-appeared before ${prd}`));
+      } else {
+        steps.push(step('understand', 'understand', legacy ? 'unknown' : 'blocked',
+          `ORDER VIOLATION — the spec (${prd}) first-appeared BEFORE the explainer (${expl})`,
+          'without the pass first, the AGENT acquires the understanding and the PM approves a spec built on facts they never saw',
+          { blocking: !legacy, rule: 'O4' }));
+      }
+    }
+  }
+
+  // ── spec ─ the lane's artifacts, and O1/O2: they precede the build ───────────────────────────
+  const needsRubric = effLane === 'feature';
+  {
+    const wants = {
+      feature: 'a PRD', discovery: 'a spike brief', incident: 'an incident record',
+      content: 'a content brief', prototype: 'a quick prototype brief',
+    }[effLane];
+    if (effLane === 'chore') {
+      const intent = String(fm.status || '').trim();
+      steps.push(intent
+        ? step('spec', 'spec', 'done', 'chore lane — intent stated in the record\'s status')
+        : step('spec', 'spec', 'blocked', 'chore lane requires a one-paragraph intent in status:',
+          `write the intent in ${recRel} — anchor-free trivia takes the no-initiative label instead`,
+          { blocking: true, rule: 'R2' }));
+    } else if (!prd) {
+      steps.push(step('spec', 'spec', 'blocked', `no prd_path — the ${effLane} lane needs ${wants}`,
+        effLane === 'feature'
+          ? 'author the PRD (skills/core/prd.skill) and the rubric alongside it (D13), then set prd_path + rubric_path'
+          : `author ${wants} and set prd_path in ${recRel}`,
+        { blocking: true, rule: 'R2' }));
+    } else if (prdIdx === null) {
+      steps.push(step('spec', 'spec', 'blocked', `prd_path '${prd}' does not exist in the repo`,
+        'create the file the record points at, or correct prd_path',
+        { blocking: true, rule: 'R2' }));
+    } else if (needsRubric && !rubric) {
+      steps.push(step('spec', 'spec', 'blocked', 'no rubric_path — the feature lane writes the eval before the build (D13)',
+        'author the rubric (skills/core/eval-rubric.skill) and set rubric_path',
+        { blocking: true, rule: 'R2' }));
+    } else if (rubric && !fs.existsSync(path.join(root, rubric))) {
+      steps.push(step('spec', 'spec', 'blocked', `rubric_path '${rubric}' does not exist in the repo`,
+        'optional never means dangling — point rubric_path at a real file or clear it',
+        { blocking: true, rule: 'R2' }));
+    } else {
+      // Artifacts are present. Now the order rules the old gate could not see.
+      const rubricIdx = rubric ? firstAppearance(root, range, rubric) : null;
+      const specIdx = rubricIdx == null ? prdIdx : Math.max(prdIdx, rubricIdx);
+      const specNames = rubric ? `${prd} + ${rubric}` : prd;
+      if (specIdx === undefined || (rubricIdx === undefined)) {
+        steps.push(step('spec', 'spec', 'unknown', `${specNames} present — order vs the build undecidable (${range.reason || 'no usable history'})`));
+      } else if (build.unknown) {
+        steps.push(step('spec', 'spec', 'unknown', `${specNames} present — order vs the build undecidable (${range.reason})`));
+      } else if (build.first === null) {
+        steps.push(step('spec', 'spec', 'done', `${specNames} present — no implementation commits in this range, so nothing can precede them`));
+      } else if (specIdx <= build.first) {
+        steps.push(step('spec', 'spec', 'done', `${specNames} — first-appeared at or before the first build commit`));
+      } else {
+        const late = rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? rubric : prd;
+        steps.push(step('spec', 'spec', '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: true, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
+      }
+    }
+  }
+
+  const runs = readJsonl(path.join(L.runsDir, L.runsFile)).filter((r) => r && r.initiative_id === id);
+  const runsRel = path.relative(root, path.join(L.runsDir, L.runsFile));
+
+  // ── priors ─ O7: the episodic read is CITED, and the citation is checked ─────────────────────
+  // AGENTS.md step 3 mandates reading this initiative's earlier runs BEFORE acting — the one kernel
+  // invariant that was still asserted only in prose. Nothing can derive that a file was READ, and
+  // this rule does not pretend to: what it derives is the three things that ARE decidable from the
+  // record, and together they are what separates it from a checkbox.
+  //   1. whether earlier runs existed at all      — the rule is vacuous on a first run, and says so
+  //   2. whether the run declared what it consulted
+  //   3. whether the ids it named are REAL and actually EARLIER
+  // (3) is the part that matters. O5's `PM_approved: true` is a bare boolean, satisfiable by typing
+  // it; a fabricated `priors` list fails against the corpus it claims to have read. The rule is
+  // NON-BLOCKING for the same reason O5/O6 are: it cannot be true before a run exists, and a rule
+  // enforced at a moment it cannot be satisfied only teaches people to reach for the escape hatch.
+  {
+    const latest = runs.length ? runs[runs.length - 1] : null;
+    const earlier = runs.slice(0, -1);
+    const cite = priorsCitation(latest);
+    const how = `consult this initiative's earlier runs BEFORE acting (AGENTS.md step 3) and cite them as \`priors\` on the run in ${runsRel}`;
+    if (!latest) {
+      steps.push(step('priors', 'priors', 'pending', 'no run logged for this initiative yet', how, { rule: 'O7' }));
+    } else if (!earlier.length) {
+      // Not a pass — there was nothing to pass. A tick here would be the watermelon this engine exists to prevent.
+      steps.push(step('priors', 'priors', 'na',
+        `${latest.run_id} is the first run on this initiative — no priors to consult`));
+    } else if (cite.malformed) {
+      steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+        `${latest.run_id} has a malformed priors citation — ${cite.malformed}`,
+        `use \`priors: ["<run_id>", …]\` or \`priors: {consulted: [...], note: "…"}\` in ${runsRel}`,
+        { rule: 'O7' }));
+    } else if (!cite.declared) {
+      steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+        `${latest.run_id} follows ${earlier.length} earlier run(s) on this initiative and cites no priors`,
+        how, { rule: 'O7' }));
+    } else {
+      const byId = new Map(runs.map((r) => [String(r.run_id), r]));
+      const earlierIds = new Set(earlier.map((r) => String(r.run_id)));
+      const missing = cite.consulted.filter((x) => !byId.has(x));
+      const notEarlier = cite.consulted.filter((x) => byId.has(x) && !earlierIds.has(x));
+      if (missing.length) {
+        // The check a declared field would otherwise never get. A citation naming a run that does not
+        // exist reports a read that cannot have happened — worse than an absent citation, because it
+        // reads as compliance on the board.
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} cites prior run(s) that do not exist on this initiative: ${missing.join(', ')}`,
+          `cite run_ids that are actually in ${runsRel} — a citation naming nothing reports a read that cannot have happened`,
+          { rule: 'O7' }));
+      } else if (notEarlier.length) {
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} cites ${notEarlier.join(', ')}, which ${notEarlier.length > 1 ? 'are' : 'is'} not EARLIER than it`,
+          'a run cannot consult itself or a run that came after it — cite only runs logged before this one',
+          { rule: 'O7' }));
+      } else if (!cite.consulted.length && !cite.note) {
+        steps.push(step('priors', 'priors', legacy ? 'pending' : 'blocked',
+          `${latest.run_id} declares an empty priors list with no note, over ${earlier.length} earlier run(s)`,
+          'an empty list with no reason is indistinguishable from not looking — say which priors were read, or say in `note` why none applied',
+          { rule: 'O7' }));
+      } else if (!cite.consulted.length) {
+        // Allowed, and deliberately not silent: the machine cannot judge whether the priors were
+        // genuinely irrelevant, so it surfaces the claim verbatim for the PM instead of ticking.
+        steps.push(step('priors', 'priors', 'done',
+          `${latest.run_id} consulted none of ${earlier.length} earlier run(s) — declared irrelevant: ${cite.note}`));
+      } else {
+        steps.push(step('priors', 'priors', 'done',
+          `${latest.run_id} cites ${cite.consulted.length} prior run(s): ${cite.consulted.join(', ')}${cite.note ? ` — ${cite.note}` : ''}`));
+      }
+    }
+  }
+
+  // ── contract ─ O5: PM-approved done-criteria before the build. Reported, never CI-blocking ────
+  const approved = runs.find((r) => r.pre_run_contract && r.pre_run_contract.PM_approved === true);
+  {
+    if (approved) {
+      steps.push(step('contract', 'contract', 'done',
+        `PM-approved pre_run_contract on run ${approved.run_id}${approved.pre_run_contract.approved_by ? ` (by ${approved.pre_run_contract.approved_by})` : ''}`));
+    } else if (runs.length) {
+      steps.push(step('contract', 'contract', legacy ? 'pending' : 'blocked',
+        `${runs.length} run(s) logged, none with pre_run_contract.PM_approved: true`,
+        `agree numbered done_criteria + test_method with the PM and record the approval in ${runsRel}`,
+        { rule: 'O5' }));
+    } else {
+      steps.push(step('contract', 'contract', 'pending',
+        'no run logged for this initiative yet',
+        `agree done_criteria + test_method BEFORE building and append the run to ${runsRel} with PM_approved: true`,
+        { rule: 'O5' }));
+    }
+  }
+
+  // ── build ────────────────────────────────────────────────────────────────────────────────────
+  steps.push(build.unknown
+    ? step('build', 'build', 'unknown', range.reason)
+    : build.first === null
+      ? step('build', 'build', 'pending', 'no implementation commits in this range')
+      : step('build', 'build', 'done', `${build.count} commit(s) on implementation paths`));
+
+  // ── quality ─ CI's verdict, never this engine's ──────────────────────────────────────────────
+  steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
+
+  // ── review ─ the Review Gate's verdict, where the lane has a rubric ──────────────────────────
+  const evals = readJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
+  {
+    if (effLane === 'chore' || effLane === 'prototype') {
+      steps.push(step('review', 'review', 'na', effLane === 'prototype'
+        ? 'leg A is grilled as dialogue, never scored (D60)'
+        : 'chore lane carries no rubric (D56)'));
+    } else if (evals.length) {
+      const last = evals[evals.length - 1];
+      steps.push(step('review', 'review', 'done',
+        `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`));
+    } else {
+      steps.push(step('review', 'review', 'pending', 'no Review-Gate verdict recorded',
+        'score the build against the rubric (build-skills/evaluator.skill), then append to evals.jsonl',
+        { rule: 'R3' }));
+    }
+  }
+
+  // ── explain ─ O6: the run is explained AFTER the build and BEFORE acceptance ─────────────────
+  {
+    let found = null;
+    for (const r of runs) {
+      const p = path.join(L.explainers, `${r.run_id}-explainer.md`);
+      if (fs.existsSync(p)) { found = path.relative(root, p); break; }
+    }
+    if (found) {
+      steps.push(step('explain', 'explain', 'done', found));
+    } else if (!runs.length) {
+      steps.push(step('explain', 'explain', 'pending', 'no run to explain yet',
+        'log the run first, then run build-skills/explain-run.skill against its diff', { rule: 'O6' }));
+    } else {
+      steps.push(step('explain', 'explain', legacy ? 'pending' : 'blocked',
+        `no explainer at ${path.relative(root, L.explainers)}/${runs[runs.length - 1].run_id}-explainer.md`,
+        'run build-skills/explain-run.skill — raw-transcript vigilance degrades within ~30 min, so the explainer is what the PM actually reviews',
+        { rule: 'O6' }));
+    }
+  }
+
+  // ── accept ─ the human PM, final and non-delegable (D12) ─────────────────────────────────────
+  const accepted = readJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
+    .filter((a) => a && a.initiative_id === id && a.accepted === true);
+  {
+    const blockers = steps.filter((s) => s.status === 'blocked').map((s) => s.key);
+    if (accepted.length) {
+      const last = accepted[accepted.length - 1];
+      steps.push(step('accept', 'accept', 'done', `accepted by ${last.pm || 'PM'}${last.at ? ` on ${String(last.at).slice(0, 10)}` : ''}`));
+    } else if (blockers.length) {
+      steps.push(step('accept', 'accept', 'blocked', `blocked by: ${blockers.join(', ')}`,
+        'the Acceptance Gate is the PM\'s (D12) — but it does not open over an unfinished ladder'));
+    } else {
+      steps.push(step('accept', 'accept', 'pending', 'PM Acceptance Gate open — non-delegable (D12)',
+        'the PM names one thing verified BY HAND in the acceptance note, then appends to acceptances.jsonl'));
+    }
+  }
+
+  // ── stage, derived from what the steps found ─────────────────────────────────────────────────
+  const by = Object.fromEntries(steps.map((s) => [s.key, s]));
+  let stage = 'intake';
+  if (by.spec.status === 'done') stage = 'spec';
+  if (by.contract.status === 'done') stage = 'contract';
+  if (by.build.status === 'done') stage = 'build';
+  if (evals.length || runs.length) stage = 'eval';
+  if (accepted.length) stage = 'accepted';
+
+  const blockers = steps.filter((s) => s.status === 'blocked');
+  const gateFailures = blockers.filter((s) => s.blocking);
+  const next = steps.find((s) => s.status === 'blocked')
+    || steps.find((s) => s.status === 'pending' && s.next)
+    || null;
+
+  return {
+    ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
+    last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
+    title: fm.title || id, anchor: fm.parent_kr || null,
+    steps, blockers: blockers.map((s) => s.key), gate_failures: gateFailures.map((s) => s.rule || s.key),
+    next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
+    range: range.ok ? { base: range.base, commits: range.shas.length, whole_history: !!range.wholeHistory } : { error: range.reason },
+    enforced_from: ENFORCED_FROM,
+  };
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────────────────────────────
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const GLYPH = {
+  done: ['✓', 32], current: ['●', 36], blocked: ['✗', 31],
+  pending: ['·', 90], na: ['─', 90], unknown: ['?', 33],
+};
+function mark(status) {
+  const [g, col] = GLYPH[status] || ['?', 33];
+  return c(col, g);
+}
+// Record prose is deliberately long — the reasoning is for the PM to read in the record, not to
+// wrap a terminal. The ladder shows the declaration, then stops.
+function brief(s, n) {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+function renderLadder(w) {
+  if (!w.ok) return c(31, `✗ ${w.error}`);
+  const out = [];
+  const head = `${c(1, w.id)} · ${w.lane}${w.laneKnown ? '' : c(33, ' (unknown lane — enforcing feature)')} · ${w.anchor ? brief(w.anchor, 46) : c(31, 'unanchored')}`;
+  out.push('');
+  out.push(`  ${head}`);
+  out.push(`  ${c(90, 'stage')} ${c(1, w.stage)}${w.legacy ? c(33, `   legacy — record predates ${w.enforced_from}, order rules report but do not fail`) : ''}`);
+  out.push(`  ${c(90, '─'.repeat(78))}`);
+  for (const s of w.steps) {
+    const label = s.label.padEnd(11);
+    out.push(`  ${mark(s.status)} ${s.status === 'na' || s.status === 'pending' ? c(90, label) : label} ${brief(s.evidence, 110)}`);
+    if (s.next) out.push(`    ${c(90, '→')} ${c(s.status === 'blocked' ? 33 : 90, brief(s.next, 150))}`);
+  }
+  out.push('');
+  if (w.next) out.push(`  ${c(1, 'next:')} ${w.next.action}`);
+  else out.push(`  ${c(32, 'nothing blocking — the ladder is complete')}`);
+  if (w.range.error) out.push(`  ${c(33, `order checks degraded: ${w.range.error}`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+function renderBoard(rows, opts) {
+  const out = [''];
+  const acceptedN = rows.filter((r) => r.ok && r.accepted).length;
+  const { shown, hidden, total } = inFlight(rows, { cap: opts.all ? Infinity : BOARD_CAP });
+  const blocked = shown.filter((r) => r.ok && r.blockers.length).length;
+  // "Open" is stated as what it is DERIVED FROM — no recorded acceptance — not as "in flight". The
+  // difference matters here: this repo has 10 acceptances against 93 initiatives, so most of these
+  // are finished work whose acceptance was never logged. Calling that "in flight" would be the
+  // board inventing a fact; naming the gap is the board doing its job.
+  out.push(`  ${c(1, 'PMOS workflow board')} · ${total} without a recorded acceptance · ${blocked ? c(31, `${blocked} blocked`) : c(32, 'none blocked')}${acceptedN ? c(90, ` · ${acceptedN} accepted`) : ''}`);
+  out.push(`  ${c(90, 'most recently worked on first · ✗ blocked · ● in this change')}`);
+  out.push(`  ${c(90, '─'.repeat(78))}`);
+  if (!shown.length) { out.push(`  ${c(32, 'every initiative here has a recorded acceptance.')}`); out.push(''); return out.join('\n'); }
+  const w1 = Math.min(34, Math.max(...shown.map((r) => r.id.length), 4));
+  for (const r of shown) {
+    if (!r.ok) { out.push(`  ${c(31, '✗')} ${r.id.padEnd(w1)}  ${c(31, r.error)}`); continue; }
+    const status = r.blockers.length ? 'blocked' : r.in_change ? 'current' : 'pending';
+    // The board shows WHICH step and WHY in a few words; the full next action lives on the ladder,
+    // where there is room for it. Repeating a 90-character instruction on every row taught nothing.
+    const why = r.next ? `${r.next.step} — ${brief(r.next.why, 62)}` : 'nothing blocking';
+    const note = r.blockers.length ? c(31, why) : c(90, why);
+    const tag = r.in_change ? c(36, ' ·this change') : '';
+    out.push(`  ${mark(status)} ${r.id.padEnd(w1)}  ${r.lane.padEnd(9)} ${r.stage.padEnd(9)} ${note}${tag}`);
+  }
+  out.push('');
+  // Never a silent cap — a truncated list that does not say so reads as "that is everything".
+  if (hidden) out.push(`  ${c(33, `+ ${hidden} more without a recorded acceptance, not shown`)} ${c(90, `— node ${opts.self} --all`)}`);
+  out.push(`  ${c(90, `one initiative in detail:  node ${opts.self} <id>`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+/*
+ * What "in flight" means, in one place, so the CLI, the gate and the workspace panel cannot drift.
+ *
+ * NOT `!legacy` — that was the bug this replaced. Legacy is about whether a rule may fail a PR;
+ * being old has nothing to do with whether work is live. In flight = **not accepted**, ordered so
+ * the rows worth looking at come first:
+ *   1. anything blocked            — the reason you opened the surface
+ *   2. anything this change carries — precise, git says so
+ *   3. most recently worked on     — the honest fallback, and the repo already knows it
+ *
+ * The cap is REPORTED, never silent: a list quietly truncated to 12 reads as "that's everything",
+ * which is the same class of lie as a false green.
+ */
+const BOARD_CAP = 12;
+function inFlight(rows, opts) {
+  const cap = (opts && opts.cap) || BOARD_CAP;
+  const live = rows.filter((r) => !r.ok || !r.accepted);
+  const rank = (r) => (!r.ok ? 0 : r.blockers.length ? 1 : r.in_change ? 2 : 3);
+  const sorted = [...live].sort((a, b) =>
+    rank(a) - rank(b)
+    || (b.last_activity || 0) - (a.last_activity || 0)
+    || String(a.id).localeCompare(String(b.id)));
+  return { shown: sorted.slice(0, cap), hidden: Math.max(0, sorted.length - cap), total: sorted.length };
+}
+
+function listInitiatives(root) {
+  const L = layout(root);
+  try {
+    return fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && f !== 'README.md' && f !== 'index.md')
+      .map((f) => f.replace(/\.md$/, '')).sort();
+  } catch { return []; }
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────────────
+function main(argv) {
+  const args = argv.slice(2);
+  let root = process.cwd(); let json = false; let gate = false; let all = false;
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--root') { root = args[++i]; continue; }
+    if (a === '--json') { json = true; continue; }
+    if (a === '--gate') { gate = true; continue; }
+    if (a === '--all') { all = true; continue; }
+    if (a === '--open') { continue; }          // the board is in-flight-only by default now
+    if (a === '--help' || a === '-h') {
+      process.stdout.write([
+        '', '  node scripts/workflow-state.js [<initiative-id>] [--json] [--gate] [--all] [--root <dir>]', '',
+        '    (no id)        the board — what is in flight, blocked first, then this change, then recency',
+        '    <id>           the ladder for one initiative: where you are, what is next, what blocks',
+        '    --gate <id>    CI mode — exit 1 on a blocking order violation, with the next action',
+        '    --all          the board without the 12-row cap',
+        '    --json         machine-readable (what an agent reads at session start)', '',
+      ].join('\n') + '\n');
+      return 0;
+    }
+    rest.push(a);
+  }
+  const self = path.relative(root, __filename) || 'scripts/workflow-state.js';
+  const id = rest[0];
+
+  if (id) {
+    const w = computeWorkflow(id, { root });
+    if (json) { process.stdout.write(JSON.stringify(w, null, 2) + '\n'); }
+    else { process.stdout.write(renderLadder(w) + '\n'); }
+    if (!gate) return w.ok ? 0 : 1;
+
+    // ── gate mode ──────────────────────────────────────────────────────────────────────────────
+    if (!w.ok) { process.stdout.write(`::error::workflow-gate: ${w.error}\n`); return 1; }
+    const fails = w.steps.filter((s) => s.status === 'blocked' && s.blocking);
+    if (fails.length) {
+      for (const f of fails) {
+        process.stdout.write(`::error::workflow-gate [${f.rule || f.key}]: ${f.evidence}\n`);
+        process.stdout.write(`❌ ${f.key} — ${f.evidence}\n   → ${f.next}\n`);
+      }
+      return 1;
+    }
+    const reported = w.steps.filter((s) => s.status === 'blocked' && !s.blocking);
+    for (const r of reported) {
+      // Reported, not failed: O5/O6 cannot be true before the diff exists. Saying WHY at the point
+      // of report is what stops this reading as a gate that was quietly skipped.
+      process.stdout.write(`::notice::workflow-gate [${r.rule || r.key}]: ${r.evidence} — reported, not failed: this rule closes after the diff exists, and blocks the Acceptance step instead.\n`);
+      process.stdout.write(`⚠️  ${r.key} — ${r.evidence}\n   → ${r.next}\n`);
+    }
+    if (w.legacy) process.stdout.write(`ℹ️  '${w.id}' is LEGACY (record predates ${ENFORCED_FROM}) — order rules reported, not enforced.\n`);
+    if (w.range.error) process.stdout.write(`⚠️  order checks degraded — ${w.range.error}\n`);
+    process.stdout.write(`✅ workflow gate PASSED — '${w.id}' (${w.lane}) at stage ${w.stage}.\n`);
+    return 0;
+  }
+
+  const range = commitRange(root);
+  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range }));
+  if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
+  if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
+  process.stdout.write(renderBoard(rows, { self, all }));
+  return 0;
+}
+
+module.exports = {
+  computeWorkflow, renderLadder, renderBoard, listInitiatives, layout, inFlight, BOARD_CAP,
+  parseLeadingFrontmatter, specimenRoute, surfaceRoute, priorsCitation, isBuildPath, commitRange,
+  ENFORCED_FROM,
+};
+
+if (require.main === module) process.exit(main(process.argv));

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.1.0",
+  "version": "0.11.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.1.0",
+      "version": "0.11.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",