create-pmos 0.22.0 → 0.23.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pmos",
-  "version": "0.22.0",
-  "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.",
+  "version": "0.23.0",
+  "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 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. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {
     "create-pmos": "bin/create-pmos.js"
@@ -25,6 +25,8 @@
     "create",
     "workspace",
     "terminal",
-    "gui"
+    "gui",
+    "workflow",
+    "audit"
   ]
 }

package/payload/AGENTS.md

@@ -136,6 +136,13 @@ in **dependency order**, from [templates/ticket-template.md](templates/ticket-te
 - Frontmatter: `id` (the NNN), `title`, `status` (`todo | doing | done`), and `blocked_by` — an
   explicit list of the ticket ids that must be `done` first. Blocking edges are **text**, not a
   hidden graph.
+- **Sweep the state you derive from.** `node pmos/scripts/workflow-sweep.js` audits the records and
+  the three ledgers everything else reads. Run it before a review and after any bulk edit. It reports
+  **defects** (state that contradicts reality — a torn ledger line, a row naming no initiative, a
+  duplicate `run_id`, a record pointing at a file nobody wrote) separately from **owed** work (a
+  merged initiative with no run logged, an open Acceptance Gate). `--fix` repairs only the mechanical
+  defects and writes no `.jsonl` and no judgement — closing your own loops is your job and the
+  Acceptance Gate is yours alone (D12).
 - **Work the frontier.** `pmos/scripts/frontier.sh` lists exactly the tickets that are not done and
   whose every blocker is done — the workable set. Start only from there. If it reports the frontier
   is *blocked*, there is a cycle or an undone blocker to resolve before more work is startable.

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@38fc236
+kernel-source: pmos@76ed2d3
 assembled: 2026-07-31
 mode: vendor

package/payload/README.md

@@ -36,7 +36,22 @@ personally-owned PMOS backend).
   initiative into ordered, dependency-numbered work (file-mode's board — see AGENTS.md).
 - `scripts/` — `gate-initiative.sh` (the fail-closed CI gate), `metrics.py` (north star +
   calibration + Goodhart tripwire), `kit-update.sh` (kernel refresh), `frontier.sh` (lists the
-  workable tickets — those not done whose blockers are all done).
+  workable tickets — those not done whose blockers are all done), `workflow-sweep.js` (audits the
+  state everything above derives from — see below), plus `workflow-state.js`, `anchor-resolve.js`
+  and `delivery-index.js`, the readers it and the ladder share.
+- **`scripts/workflow-sweep.js` — the state audit.** Everything PMOS reports is *derived*, which
+  makes it self-maintaining and does **not** make it self-correcting: a derivation is only as true
+  as what it reads. Run `node pmos/scripts/workflow-sweep.js` to find state that misreports —
+  ledger lines that do not parse (every reader drops them silently, so a torn acceptance reads as
+  "never accepted"), rows naming an initiative that does not exist, duplicate `run_id`s, records
+  pointing at files nobody wrote, merged branches with no record.
+
+  It separates two things and never mixes them: a **defect** is state that contradicts reality —
+  the board is lying — and an **owed** finding is work that honestly has not happened. `--fix`
+  repairs only the mechanical defects (a stale pointer, text an earlier commit can restore); it
+  **never** writes a run, an eval, an acceptance or any `.jsonl`, because a tool that closes your
+  loops by writing the rows produces a green board out of evidence nobody produced. `--gate` exits
+  non-zero on defects only, so it can run in CI without failing on your backlog.
 - `templates/pmos-gate.yml` — CI drop-in; copy to `.github/workflows/`.
 - `KIT-VERSION` — which PMOS kernel this was assembled from.
 

package/payload/scripts/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/payload/scripts/delivery-index.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS delivery evidence — the one place git's history answers "did THIS initiative ship?".
+ *
+ *   const D = require('./delivery-index');
+ *   const idx = D.deliveryIndex(root, ids);     // { ok, reason?, byBranch:Set, byMention:Set }
+ *   D.attribution(idx, id)                      // 'branch' | 'mention' | null | 'unknown'
+ *   D.isDeliveryPath('workspace/server.js')     // true — a build path, not planning prose
+ *
+ * WHY THIS EXISTS. This derivation shipped inside `workspace/server.js` as a module-private
+ * function, so it answered for exactly one surface. The engine — `scripts/workflow-state.js`, which
+ * CI, the CLI and the workspace ladder all run — could not see it, and derived its `build` rung from
+ * a signal carrying no attribution at all: `buildCommits` counted every commit in a range that
+ * touched a build path, with no idea which initiative it was answering about. Over a pull-request
+ * range that is correct, because the range IS one initiative's work. Over the trunk it reported the
+ * same 488 commits as evidence for all 177 initiatives, including ones that shipped nothing.
+ *
+ * So the GUI's initiative board and the engine's ladder held two different opinions about the same
+ * question, in the same process, three hundred lines apart — one attributed, one not. That is the
+ * shape `scripts/anchor-resolve.js` was extracted to end for `parent_kr`, stated in its own header,
+ * and delivery is the same kind of fact. See
+ * planning/explainers/workflow-status-sweep-surface-explainer.md.
+ *
+ * TWO SIGNALS, because one is not enough (board-delivery-truth R-2):
+ *
+ *   1. THE BRANCH CONVENTION is precise and incomplete. A merge whose subject names
+ *      `initiative/<id>` is unambiguous — but 31% of this repository's merged pull requests shipped
+ *      on `claude/*` branches, which match no id, and a convention nothing enforces cannot be the
+ *      only signal.
+ *
+ *   2. A COMMIT THAT MENTIONS THE ID AND TOUCHES A BUILD PATH. The build-path requirement is what
+ *      keeps the mention signal honest: `feat(planning): add <id> PRD` mentions the id while
+ *      delivering nothing, and without the path test every SPECIFIED initiative would read as
+ *      shipped — which is the same class of false green this module exists to remove.
+ *
+ * HONESTY BY CONSTRUCTION. `ok:false` is a real answer and never degrades into "nothing was
+ * delivered". A caller that cannot read the history must say so; silently reporting `planning` for
+ * every shipped initiative is precisely the failure being fixed. `attribution()` returns the string
+ * `'unknown'` for that case, and it is deliberately not `null` — "I cannot tell" and "I looked and
+ * there is nothing" call for opposite responses from every caller.
+ *
+ * Zero dependencies, stock Node. It runs in CI, in a terminal, inside the workspace server, and
+ * inside an adopter's vendored kit.
+ */
+
+const { spawnSync } = require('child_process');
+
+/*
+ * A path counts as DELIVERY when it is neither a planning artifact nor governance prose.
+ *
+ * This is deliberately a SEPARATE rule from the engine's `isBuildPath`, and the difference is not an
+ * oversight. `isBuildPath` answers "is this commit implementation work for the lane under review?"
+ * and therefore lane-gates `prototype/` — in the prototype lane the specimen IS the deliverable
+ * (D60), in every other lane it is somebody else's leg-A work. This answers a coarser question
+ * asked of the whole trunk at once, where no single lane is under review, so `prototype/` is always
+ * excluded: a prototype never ships (D01), so a commit touching only `prototype/` is never evidence
+ * that something was delivered. Merging the two rules would force one of the two questions to be
+ * answered wrongly. They are kept apart, and each says why in the place it is written.
+ */
+const EXCLUDED_PREFIX = /^(planning|okf|prototype)\//;
+function isDeliveryPath(f) {
+  if (!f) return false;
+  if (EXCLUDED_PREFIX.test(f)) return false;
+  // Root-level governance prose (DECISIONS.md, CLAUDE.md, AGENTS.md…) is not a build. A markdown
+  // file deeper in the tree may well be — `workspace/docs/*.md` ships with the app — so the test is
+  // on the shape of the path, not on the extension alone.
+  return !/^[^/]+\.md$/.test(f);
+}
+
+function gitCap(root, args) {
+  try {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status !== 0) {
+      return { ok: false, out: '', err: (r.stderr || (r.error && r.error.message) || '').trim() };
+    }
+    return { ok: true, out: r.stdout || '' };
+  } catch (e) { return { ok: false, out: '', err: String((e && e.message) || e) }; }
+}
+
+function trunkRef(root) {
+  for (const c of ['origin/main', 'main', 'origin/master', 'master']) {
+    const r = gitCap(root, ['rev-parse', '--verify', '--quiet', c]);
+    if (r.ok && r.out.trim()) return { ref: c, head: r.out.trim() };
+  }
+  return null;
+}
+
+// ONE `git log` per trunk head, memoised on that sha — ~0.3 s and ~800 KB on this repository's
+// 1,200 commits, paid once and reused by every caller until the trunk moves. The cache key is the
+// head sha rather than the root, so a fetch that advances the trunk invalidates it by construction
+// rather than by anyone remembering to.
+const deliveryCache = new Map();      // root -> { head, index }
+
+/**
+ * Which initiatives the trunk's own history says were delivered.
+ *
+ * @param {string} root  repository root
+ * @param {Iterable<string>} ids  the known initiative ids — the mention signal can only recognise
+ *                                ids it was told about, and matching arbitrary tokens would turn
+ *                                any commit subject into a delivery claim
+ * @returns {{ok:boolean, reason?:string, byBranch:Set<string>, byMention:Set<string>}}
+ */
+function deliveryIndex(root, ids) {
+  const t = trunkRef(root);
+  if (!t) {
+    return {
+      ok: false,
+      reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived',
+      byBranch: new Set(), byMention: new Set(),
+    };
+  }
+  const hit = deliveryCache.get(root);
+  if (hit && hit.head === t.head) return hit.index;
+
+  // %x1e separates commits, %x1f separates the message from --name-only's file list.
+  const r = gitCap(root, ['log', '--format=%x1e%s %b%x1f', '--name-only', t.head]);
+  if (!r.ok) {
+    return {
+      ok: false,
+      reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`,
+      byBranch: new Set(), byMention: new Set(),
+    };
+  }
+  const byBranch = new Set();
+  const byMention = new Set();
+  const known = Array.isArray(ids) ? ids : [...(ids || [])];
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const msg = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    for (const m of msg.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) byBranch.add(m[1]);
+    if (!files.some(isDeliveryPath)) continue;
+    // `id.length > 3` guards against a short id matching incidentally inside an unrelated word.
+    // It is a heuristic and is named as one in the PRD's risks; a miss reads as `pending`, which is
+    // the safe direction and the one the surface already errs in.
+    for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
+  }
+  const index = { ok: true, byBranch, byMention };
+  deliveryCache.set(root, { head: t.head, index });
+  return index;
+}
+
+/*
+ * The branches that actually MERGED — a strictly narrower signal than `byBranch`, and the two are
+ * kept apart on purpose.
+ *
+ * `deliveryIndex` scans every commit's subject AND body, because a squash-merged pull request often
+ * names its branch only in the body. That breadth is right for ATTRIBUTION, where the question is
+ * "is there evidence this initiative's work landed" and a stray match against an id that already has
+ * a record costs nothing.
+ *
+ * It is wrong for any caller that RE-CREATES something from the match. A commit body quoting
+ * `initiative/foo` inside a code example is a real occurrence in this repository's history, and a
+ * caller that wrote a record for every token it found would manufacture initiatives named `foo`,
+ * `save_okr` and `pmos-operating-guide.` out of prose. So this reads MERGE SUBJECTS only, and
+ * requires the id to have the shape ids actually have. On this repository that is the difference
+ * between 4 fabricated records and the 1 that is genuinely missing.
+ */
+const ID_SHAPE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function mergedBranches(root) {
+  const t = trunkRef(root);
+  if (!t) return { ok: false, reason: 'no trunk branch (main/master) is reachable from this repository', ids: new Map() };
+  const r = gitCap(root, ['log', '--merges', '--format=%x1e%H %ct%x1f%s', t.head]);
+  if (!r.ok) return { ok: false, reason: `git could not read the merge history at ${t.ref}`, ids: new Map() };
+  const ids = new Map();               // id -> { sha, at (unix s), subject }
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const [head, subject] = chunk.split('\x1f');
+    const [sha, ct] = String(head || '').trim().split(/\s+/);
+    const subj = String(subject || '').replace(/\s+/g, ' ').trim();
+    /*
+     * A BACK-merge — `merge: main into initiative/x` — merges the trunk INTO the branch, and it is
+     * still EVIDENCE THE BRANCH LANDED: it is only reachable from the trunk at all because the
+     * branch was subsequently merged in. What it must not do is supply the record's title and date,
+     * because it describes mid-flight housekeeping rather than the work, and its date is the
+     * housekeeping's. So it counts, and a landing merge outranks it whenever one exists. The
+     * direction is stated in the subject, so this is a fact rather than a guess.
+     */
+    const back = /\binto\s+\S*initiative\//i.test(subj);
+    for (const m of subj.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) {
+      const id = m[1].replace(/[.,;`'")\]]+$/, '');
+      if (!ID_SHAPE.test(id)) continue;
+      const held = ids.get(id);
+      // The log runs newest-first, so the first LANDING merge seen is the most recent one — and it
+      // always wins over a back-merge, whenever it is found.
+      if (held && (!held.back || back)) continue;
+      ids.set(id, { sha: sha || null, at: Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null, subject: subj, back });
+    }
+  }
+  return { ok: true, ids };
+}
+
+/*
+ * `delivered_by:` — the PM's lever, and the check that keeps it from becoming a status field (R-2b).
+ *
+ * Both signals above are CONVENTIONS. Work delivered under a neighbouring initiative's branch and
+ * commit names satisfies neither, and on this repository that is not hypothetical: the initiative the
+ * PM opened has a PRD, a rubric and shipped code, and no commit on the trunk names it. `null` is the
+ * honest reading of the evidence and it leaves the PM holding a true statement with no way to correct
+ * it.
+ *
+ * So a record may name the commit its work landed in. The reason this does not reintroduce the
+ * declared status that D64 and the engine's own header forbid: `delivered_by` declares a **fact git
+ * can check**, in the shape `reconstructed_from:` already established for a merge date — not a
+ * verdict about where the work stands. The check is the whole point, and it is deliberately strict in
+ * BOTH directions:
+ *
+ *   · reachable from the trunk AND touching at least one build path → `{ok:true}`; the caller
+ *     attributes with signal `declared` and shows the sha it verified.
+ *   · unreachable, unparseable, or reachable while touching nothing that counts as a build →
+ *     `{ok:false, reason}`. The caller renders that BLOCKED, never `done`. A declaration that fails
+ *     its own check is worse than no declaration, because a reader takes it for evidence.
+ */
+function declaredDelivery(root, declared) {
+  const raw = String(declared == null ? '' : declared).trim();
+  if (!raw) return { declared: false };
+  // Take the leading token: the field is `<commit-ish> — free prose`, in the same shape as the
+  // record's other declared keys, so the prose stays available to the PM without breaking the check.
+  const token = raw.split(/[\s,]/)[0].replace(/[.,;]+$/, '');
+  if (!token) return { declared: true, ok: false, reason: 'delivered_by is present but names nothing' };
+  const t = trunkRef(root);
+  if (!t) {
+    return { declared: true, ok: false, unknown: true, reason: 'no trunk branch (main/master) is reachable — delivered_by cannot be verified here' };
+  }
+  const rev = gitCap(root, ['rev-parse', '--verify', '--quiet', `${token}^{commit}`]);
+  if (!rev.ok || !rev.out.trim()) {
+    return { declared: true, ok: false, token, reason: `delivered_by names '${token}', which is not a commit in this repository` };
+  }
+  const sha = rev.out.trim();
+  const anc = gitCap(root, ['merge-base', '--is-ancestor', sha, t.head]);
+  if (!anc.ok) {
+    return { declared: true, ok: false, token, sha, reason: `delivered_by names ${sha.slice(0, 8)}, which is not reachable from ${t.ref} — it has not landed on the trunk` };
+  }
+  const files = gitCap(root, ['show', '--format=', '--name-only', sha]);
+  const touched = files.ok ? files.out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  if (!touched.some(isDeliveryPath)) {
+    return {
+      declared: true, ok: false, token, sha,
+      reason: `delivered_by names ${sha.slice(0, 8)}, which changes no build path — naming a planning commit as the delivery is the false green this check exists to catch`,
+    };
+  }
+  return { declared: true, ok: true, token, sha };
+}
+
+/**
+ * Which signal — if any — attributes a delivery to this initiative.
+ *
+ * `'unknown'` is returned when the index could not be built, and is deliberately NOT `null`. A
+ * caller that collapses the two reports "nothing was delivered" for a repository whose history it
+ * failed to read, which is a claim the missing evidence cannot support.
+ *
+ * @returns {'branch'|'mention'|'unknown'|null}
+ */
+function attribution(index, id) {
+  if (!index || !index.ok) return 'unknown';
+  if (index.byBranch.has(id)) return 'branch';
+  if (index.byMention.has(id)) return 'mention';
+  return null;
+}
+
+/** The sentence a surface shows for an attribution, so no caller writes its own wording. */
+function attributionEvidence(signal, id, extra) {
+  if (signal === 'branch') return `an initiative/${id} branch merged to the trunk`;
+  if (signal === 'mention') return 'a commit on the trunk names this initiative and changes build files';
+  if (signal === 'declared') return `delivered_by ${String(extra || '').slice(0, 8)} — verified on the trunk, and it changes build paths`;
+  if (signal === 'unknown') return 'the trunk history could not be read — delivery cannot be derived here';
+  return 'no commit on the trunk is attributable to this initiative';
+}
+
+// Exported for tests that need a clean read after mutating a fixture's history in place.
+function _resetCache() { deliveryCache.clear(); }
+
+module.exports = {
+  deliveryIndex, attribution, attributionEvidence, declaredDelivery, mergedBranches,
+  isDeliveryPath, trunkRef, _resetCache,
+};