create-pmos 0.22.0 → 0.23.0

package/workspace/lib/console-state.js

@@ -170,28 +170,43 @@ function workflow({ root }) {
   catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
   if (!ids.length) return { ok: true, empty: true, source: 'file-mode' };
 
-  // One commit range for the whole board — resolving it per initiative would re-shell git for each.
-  const range = engine.commitRange(root);
-  // WHERE the ladder was derived from. `commitRange` resolves merge-base(origin/main, HEAD)..HEAD —
-  // this BRANCH's commits, and an EMPTY range on main. So `build`/`quality`, and the stage that
-  // follows from them, are branch-scoped facts. A consumer that prints a stage without saying which
-  // branch produced it states something the data does not support: pmos-terminal-workspace, shipped
-  // under D62, derives to `spec` with "no implementation commits in this range" on every branch that
-  // did not build it. Two worktrees of one repo legitimately print two different ladders.
-  // This block is what lets a caller say so; it is not decoration (PRD R5, rubric dimension 1).
+  /*
+   * THE TRUNK, not the pull request (workflow-status-sweep R-3).
+   *
+   * This used to be `engine.commitRange(root)` — merge-base(origin/main, HEAD)..HEAD — and the trap
+   * is documented three lines below in words that were written and then not acted on: on `main`, or
+   * on a branch level with it, that range is EMPTY with `range.ok === true`. Nothing reads as
+   * degraded, every `build` rung legitimately reports `pending`, and the four-panel fold rolls
+   * BUILD/EVAL/ACCEPTED to 0/3 for every initiative in the repository — including ones that shipped
+   * months ago. The PM opens the panel to ask what is delivered and is told nothing is.
+   *
+   * So the panel asks the question the CLI board already asks — "where does this initiative stand?",
+   * which only the trunk can answer — and passes the PR range alongside as `changeRange`, which is
+   * what `● in this change` means and the one thing the trunk range genuinely cannot answer. Same
+   * split, same reasons, stated in `historyRange`'s own header. The `build` rung is attributed per
+   * initiative now (R-2), so a trunk-wide range no longer means a trunk-wide answer.
+   */
+  const range = engine.historyRange(root);
+  const changeRange = engine.commitRange(root);
+  // ONE delivery index for the board, built once and shared, exactly as the CLI board does.
+  let deliveryIndex = null;
+  try { deliveryIndex = require(path.join(path.dirname(loaded.from), 'delivery-index.js')).deliveryIndex(root, ids); }
+  catch { deliveryIndex = null; }   // absent → each ladder builds its own; the engine handles it
   const bi = gitInfo.branchInfo(root);
   const scope = {
     branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
     branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
     commits: range.ok ? range.shas.length : null,
     whole_history: range.ok ? !!range.wholeHistory : null,
-    // The empty range is the trap: range.ok is TRUE with zero commits (you are on main, or level
-    // with it), so nothing is "degraded" — every build step legitimately reads `pending` and a naive
-    // reader calls that "never built". Named separately because it needs different words.
-    empty_range: range.ok ? range.shas.length === 0 : null,
+    // Kept, and now describing `changeRange` rather than the derivation range. It is no longer the
+    // trap it names — the derivation cannot land in it — but a consumer that wants to say "nothing
+    // in this branch touches these initiatives" still needs the fact, and deleting a field because
+    // the bug it documented was fixed is how the next reader loses the reason.
+    empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
+    change_commits: changeRange.ok ? changeRange.shas.length : null,
   };
   const rows = ids.map((id) => {
-    try { return engine.computeWorkflow(id, { root, range }); }
+    try { return engine.computeWorkflow(id, { root, range, changeRange, deliveryIndex }); }
     catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
   });
   // Same `inFlight` the CLI and the gate use — the panel must not invent its own idea of what is
@@ -249,10 +264,14 @@ function ladder({ root, id }) {
   let known = null;
   try { known = engine.listInitiatives(root); } catch { known = null; }
   if (Array.isArray(known) && !known.includes(id)) return { ok: true, empty: true, row: null };
-  let range, row;
-  try { range = engine.commitRange(root); }
+  // The trunk, for the reason `workflow` above states at length: this is asked about ONE initiative
+  // the PM named, and "where does it stand" is a question the pull-request range cannot answer — on
+  // main it is empty, so the panel reported `BUILD 0/3` on delivered work (R-3).
+  let range, changeRange, row;
+  try { range = engine.historyRange(root); }
   catch (e) { return { ok: false, error: 'could not resolve the commit range: ' + String((e && e.message) || 'error').slice(0, 120) }; }
-  try { row = engine.computeWorkflow(id, { root, range }); }
+  try { changeRange = engine.commitRange(root); } catch { changeRange = { ok: false }; }
+  try { row = engine.computeWorkflow(id, { root, range, changeRange }); }
   catch (e) { return { ok: false, error: `could not derive the ladder for ${id}: ` + String((e && e.message) || 'error').slice(0, 160) }; }
   if (row && row.ok === false) return { ok: false, error: row.error || `the record for ${id} could not be read` };
   const bi = gitInfo.branchInfo(root);
@@ -264,7 +283,9 @@ function ladder({ root, id }) {
       branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
       branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
       commits: range.ok ? range.shas.length : null,
-      empty_range: range.ok ? range.shas.length === 0 : null,
+      whole_history: range.ok ? !!range.wholeHistory : null,
+      empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
+      change_commits: changeRange.ok ? changeRange.shas.length : null,
     },
   };
 }

package/workspace/lib/engine/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,
+};

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

@@ -45,6 +45,15 @@ const { execFileSync } = require('child_process');
  * and the OKR surface previously held separate, incompatible opinions about the same field.
  */
 const anchors = require('./anchor-resolve');
+/*
+ * ONE reader for delivery too (workflow-status-sweep R-1). `buildCommits` used to answer "is there a
+ * build commit in this range" — a question about a RANGE — while both of its callers asked a
+ * question about an INITIATIVE. Over a pull-request range those coincide, because the range IS one
+ * initiative's work; over the trunk they do not, and every initiative read `done` with the same 488
+ * commits of evidence. The attribution signal already existed, module-private, inside the workspace
+ * server. It is shared now, for the same reason `anchor-resolve` is.
+ */
+const delivery = require('./delivery-index');
 
 // The OKR documents and the budget registry are read once per root, not once per initiative: the
 // board derives ~100 ladders in a single pass and re-reading the same three files each time is the
@@ -114,14 +123,34 @@ function parseLeadingFrontmatter(text) {
 function readFrontmatter(file) {
   try { return parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')); } catch { return null; }
 }
-function readJsonl(file) {
+/*
+ * The ledger reader, and the one place a torn line is REPORTED rather than merely dropped (R-4).
+ *
+ * A line that does not parse is still never guessed at — that part was always right. What was wrong
+ * was the silence: a truncated acceptance row did not make the ladder say "a row here is
+ * unreadable", it made the ladder say the initiative was never accepted. The file's own honesty rule
+ * ("a gate that cannot see its inputs reports that it cannot see them") held for git ranges and not
+ * for ledger lines.
+ *
+ * The channel is out-of-band — an optional `defects` array the caller passes in — rather than a
+ * changed return type, because every existing call site wants the rows and only the sweep wants the
+ * damage. Changing the shape would have made ~six callers handle a case none of them can act on.
+ */
+function readJsonl(file, defects) {
   let text;
   try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
   const out = [];
-  for (const line of text.split('\n')) {
-    const t = line.trim();
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
     if (!t) continue;
-    try { out.push(JSON.parse(t)); } catch { /* torn line — dropped, never guessed */ }
+    try { out.push(JSON.parse(t)); }
+    catch (e) {
+      // Dropped, never guessed — and now said out loud to anyone who asked to hear it.
+      if (Array.isArray(defects)) {
+        defects.push({ file, line: i + 1, reason: String((e && e.message) || 'not valid JSON').slice(0, 120), text: t.slice(0, 120) });
+      }
+    }
   }
   return out;
 }
@@ -211,21 +240,27 @@ function buildRange(root, { spec, whole }) {
     }
     range = base ? `${base}..HEAD` : 'HEAD';
   }
-  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct', '--name-only', range]);
+  // %x1e separates commits; %x1f separates the header from the message and the message from
+  // --name-only's file list. The MESSAGE is captured in this same pass because attribution over the
+  // trunk needs it (R-2) — a second `git log` per initiative is exactly the O(commits × initiatives)
+  // cost this single-pass rewrite existed to remove.
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct%x1f%s %b%x1f', '--name-only', range]);
   if (log == null) return { ok: false, reason: 'git history unreadable' };
 
   const shas = [];
   const changed = [];                 // index -> string[] of paths touched
   const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  const subjects = [];                // index -> subject + body, one line, for attribution
   for (const chunk of log.split('\x1e')) {
     if (!chunk.trim()) continue;
-    const lines = chunk.split('\n');
-    const head = (lines.shift() || '').trim();
+    const parts = chunk.split('\x1f');
+    const head = (parts[0] || '').trim();
     const [sha, ct] = head.split(/\s+/);
     if (!sha) continue;
     shas.push(sha);
     dates.push(Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null);
-    changed.push(lines.map((s) => s.trim()).filter(Boolean));
+    subjects.push(String(parts[1] || '').replace(/\s+/g, ' ').trim());
+    changed.push(String(parts[2] || '').split('\n').map((s) => s.trim()).filter(Boolean));
   }
   const index = new Map();
   shas.forEach((sha, i) => index.set(sha, i));
@@ -245,7 +280,7 @@ function buildRange(root, { spec, whole }) {
       }
     }
   }
-  return { ok: true, base, index, shas, changed, dates, added, wholeHistory: whole ? true : !base };
+  return { ok: true, base, index, shas, changed, dates, subjects, added, wholeHistory: whole ? true : !base };
 }
 
 /*
@@ -273,11 +308,58 @@ function firstAppearance(root, range, rel) {
   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) {
+/*
+ * The earliest position in the range at which this initiative's implementation was touched, plus a
+ * count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
+ * reported as n/a rather than as a pass it did not earn.
+ *
+ * ATTRIBUTION (R-2). This function used to take no id, so it answered a question about the RANGE
+ * while both of its callers asked one about an INITIATIVE. Which of those is right depends entirely
+ * on what the range is, and the two cases are answered differently on purpose:
+ *
+ *   · A PULL-REQUEST RANGE (`base..HEAD`) — the range IS this initiative's work, by the branch
+ *     convention the Initiative Gate already enforces. Any build commit in it is therefore this
+ *     initiative's build commit, and the O1/O2 order rules depend on exactly that reading. This path
+ *     is UNCHANGED, deliberately: the gate's verdicts must not move for a reporting fix.
+ *
+ *   · THE WHOLE TRUNK (`range.wholeHistory`) — the range is everyone's work. Attribution comes from
+ *     `delivery-index`: a merged `initiative/<id>` branch, or a commit that names the id and touches
+ *     a build path. Without it every initiative reported `done` with the identical count, which is
+ *     the tell that a per-initiative fact was being read from a repository-wide one.
+ *
+ * `signal` travels back with the answer so the rung can say WHICH evidence decided it. A bare count
+ * is what let 488 stand as an explanation for 177 different initiatives.
+ */
+function buildCommits(root, range, lane, opts) {
   if (!range.ok) return { unknown: true };
+  const id = opts && opts.id;
+  const whole = !!range.wholeHistory;
+
+  // Over the trunk, the id must be attributable before any commit counts. The index is built once
+  // per trunk head by the shared reader and passed in by the board; a caller that did not supply one
+  // gets it built here (single-ladder invocations, where one extra `git log` is the whole cost).
+  let signal = null;
+  let declared = null;
+  if (whole && id) {
+    // The PM's declaration is consulted FIRST, and its failure is reported before anything else
+    // (R-2b). A `delivered_by` that does not check out must not be able to hide behind a convention
+    // signal that happens to succeed: a broken declaration is a defect in the record either way, and
+    // silently ignoring it would leave a false pointer sitting in the file forever.
+    declared = delivery.declaredDelivery(root, opts && opts.declaredDelivery);
+    if (declared && declared.declared && !declared.ok) {
+      return { unknown: false, failedDeclaration: declared, first: null, count: 0, sample: null, signal: null, attributed: true };
+    }
+    const index = (opts && opts.deliveryIndex) || delivery.deliveryIndex(root, listInitiatives(root));
+    signal = delivery.attribution(index, id);
+    if (declared && declared.ok) {
+      // A verified declaration attributes the work regardless of what the conventions found. It is
+      // the PM naming the commit, checked against git — strictly better evidence than a heuristic.
+      return { first: null, count: 0, sample: null, signal: 'declared', declaredSha: declared.sha, attributed: true, mergedOnly: true };
+    }
+    if (signal === 'unknown') return { unknown: true, reason: delivery.attributionEvidence('unknown', id) };
+    if (!signal) return { first: null, count: 0, sample: null, signal: null, attributed: true };
+  }
+
   let first = null; let count = 0; let sample = null;
   for (let i = 0; i < range.shas.length; i++) {
     // range.changed came from the range's own single pass; the per-commit `git show` this replaced
@@ -285,10 +367,29 @@ function buildCommits(root, range, lane) {
     const files = (range.changed && range.changed[i]) || [];
     const hit = files.find((f) => isBuildPath(f, lane));
     if (!hit) continue;
+    // Over the trunk, only commits that carry the id themselves are this initiative's. The branch
+    // signal is a MERGE subject, so the merge commit is the one that names it — which makes the
+    // merge position the honest "when did this land", and keeps a squashed or rebased history
+    // answerable at all. `--name-only` lists no files for a true merge commit, so a branch-attributed
+    // initiative is counted from its merge subject below rather than from this per-file loop.
+    if (whole && id && !commitNamesId(range, i, id)) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
   }
-  return { first, count, sample };
+  if (whole && id && signal === 'branch' && first === null) {
+    // The branch merged and every commit it carried was written on the branch, so no trunk commit
+    // subject names the id. The merge itself is the evidence, and saying "0 commits" over a merged
+    // branch would be the under-claim in a new place.
+    return { first: null, count: 0, sample: null, signal, attributed: true, mergedOnly: true };
+  }
+  return { first, count, sample, signal, attributed: whole && !!id };
+}
+
+// Whether the commit at `i` names this initiative in its own subject or body. The subjects come from
+// the range's own single pass, so this costs nothing per initiative.
+function commitNamesId(range, i, id) {
+  const msg = (range.subjects && range.subjects[i]) || '';
+  return msg.includes(id);
 }
 
 // ── Declaration readers ────────────────────────────────────────────────────────────────────────
@@ -471,7 +572,11 @@ function computeWorkflow(id, opts) {
   const prd = String(fm.prd_path || '').trim();
   const rubric = String(fm.rubric_path || '').trim();
   const prdIdx = prd ? firstAppearance(root, range, prd) : null;
-  const build = buildCommits(root, range, effLane);
+  const build = buildCommits(root, range, effLane, {
+    id,
+    deliveryIndex: opts && opts.deliveryIndex,
+    declaredDelivery: fm.delivered_by,
+  });
 
   // Shared helper: "A must not come after B", stated as positions, never as clock time.
   function ordered(aIdx, bIdx) {
@@ -716,11 +821,37 @@ function computeWorkflow(id, opts) {
   }
 
   // ── build ────────────────────────────────────────────────────────────────────────────────────
+  /*
+   * The evidence names WHICH signal decided, never a bare count (R-2). `488 commit(s) on
+   * implementation paths` was true of the repository and said nothing about the initiative it was
+   * printed under — the identical number on every row was the tell.
+   *
+   * The three pending sentences below are deliberately different from each other. "No commit on the
+   * trunk is attributable to this initiative" is a statement about the INITIATIVE; "no implementation
+   * commits in this range" is a statement about the RANGE, and on a branch level with `main` that
+   * range is legitimately empty. A reader who cannot tell those apart calls the second one "never
+   * built", which is the console's half of this defect.
+   */
   steps.push(build.unknown
-    ? step('build', 'build', 'unknown', 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`));
+    ? step('build', 'build', 'unknown', build.reason || range.reason)
+    : build.failedDeclaration
+      // REPORTED, never CI-blocking — the same stance R1 takes on an unresolvable anchor. Making a
+      // record's own broken pointer fail every unrelated PR would turn one typo into a repo-wide
+      // outage; the RED belongs in the surface. `blocked` still closes the accept step below, which
+      // is where a false delivery claim actually needs to stop something.
+      ? step('build', 'build', 'blocked', build.failedDeclaration.reason,
+        `point delivered_by at a commit that is reachable from the trunk and changes a build path in ${recRel}, or remove the key — a declaration that fails its own check reads as evidence`,
+        { blocking: false, rule: 'R-2b' })
+      : build.mergedOnly
+        ? step('build', 'build', 'done',
+          delivery.attributionEvidence(build.signal || 'branch', id, build.declaredSha))
+        : build.first === null
+          ? step('build', 'build', 'pending', build.attributed
+            ? delivery.attributionEvidence(null, id)
+            : 'no implementation commits in this range')
+          : step('build', 'build', 'done', build.signal
+            ? `${build.count} commit(s) on implementation paths — ${delivery.attributionEvidence(build.signal, id, build.declaredSha)}`
+            : `${build.count} commit(s) on implementation paths`));
 
   // ── quality ─ CI's verdict, never this engine's ──────────────────────────────────────────────
   steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
@@ -976,7 +1107,13 @@ function main(argv) {
   // it is the one thing the trunk range genuinely cannot answer.
   const range = historyRange(root);
   const changeRange = commitRange(root);
-  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range, changeRange }));
+  const ids = listInitiatives(root);
+  // ONE delivery index for the whole board. Built here rather than inside each ladder for the same
+  // reason the commit range is: `deliveryIndex` memoises per trunk head, so a per-initiative build
+  // would be cheap but the intent — one read, shared — is what keeps the rows consistent with each
+  // other even if the trunk moved mid-run.
+  const deliveryIdx = delivery.deliveryIndex(root, ids);
+  const rows = ids.map((i) => computeWorkflow(i, { root, range, changeRange, deliveryIndex: deliveryIdx }));
   if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
   if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
   process.stdout.write(renderBoard(rows, { self, all }));
@@ -992,4 +1129,11 @@ module.exports = {
   ENFORCED_FROM,
 };
 
-if (require.main === module) process.exit(main(process.argv));
+/*
+ * `exitCode`, not `process.exit()`. `process.exit` tears the process down without waiting for stdout
+ * to drain, and when stdout is a PIPE — every CI invocation, every `| jq`, every test harness —
+ * writes larger than the pipe buffer are asynchronous. `--json` on this repository is ~65 KB, so it
+ * arrived TRUNCATED MID-STRING and parsed as invalid JSON, while an interactive run to a TTY looked
+ * perfect. Setting the code and letting the process end naturally flushes first.
+ */
+if (require.main === module) process.exitCode = main(process.argv);