create-pmos 0.16.1 → 0.17.0

package/README.md

@@ -333,6 +333,36 @@ 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.17.0
+
+**Your board stops calling shipped work unstarted.** Run `npx create-pmos@latest workspace`; the
+version bump means an existing install auto-upgrades.
+
+- **An initiative's status is now read from what happened, not from what someone typed.** The
+  workspace took each initiative's state from a `status:` line written by hand into a PRD and
+  matched it against a list of words. In the repo this was built in, that one field held 23
+  different values, 33 initiatives had none at all, and several were cut off mid-sentence by a
+  stray comma. The plainest value of the lot — `build complete, PR #138` — matched the word
+  "build" first and displayed as *in progress*. Status is now derived from your acceptance
+  records, your logged runs, your open items, and your repository's own merge history, and each
+  row states which of those it was read from. Nothing you type can move it.
+- **`delivered` and `accepted` are no longer the same thing.** Work that merged and work you
+  actually signed off are now separate states. That gap is usually the interesting number: in the
+  repo this was built in, 62 of 63 delivered initiatives had no acceptance recorded — invisible
+  while both wore one label.
+- **The board reads your whole project history, not just the branch you are standing on.** It
+  shared a commit range with the CI gate, and that range is *empty* when your branch is level with
+  `main` — so every initiative reported "no implementation commits" and fell back to its earliest
+  stage. Work finished weeks ago looked identical to work never begun. The gate still reads only
+  the pull request, which is correct for judging whether a spec came before its build.
+- **A history it cannot read is now said out loud.** In a shallow clone (some CI checkouts) the
+  delivery history genuinely is not there. The board reports that, with the reason, instead of
+  quietly showing everything as unstarted — which would look exactly like a project where nothing
+  has happened.
+
+Unchanged where it matters: **no database, no network at runtime, no telemetry.** The server still
+binds `127.0.0.1` only. The file-mode kit itself is unchanged and still dependency-free.
+
 ## What's new in 0.16.1
 
 **Two fixes on the Terminal Workspace's entry path — how a repository reaches a running workspace.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.16.1",
+  "version": "0.17.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.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@011b77e
+kernel-source: pmos@4cb5198
 assembled: 2026-07-31
 mode: vendor

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

@@ -164,25 +164,88 @@ function git(root, args) {
  * evaluated has not been satisfied, and saying so is the whole point of the honesty rule above.
  */
 function commitRange(root) {
+  return buildRange(root, { spec: null });
+}
+
+/*
+ * The BOARD's range: the whole trunk, not the pull request.
+ *
+ * These are two different questions and they were sharing an answer. The gate asks "inside this
+ * diff, did the spec precede the build?" — only decidable within the PR. The board asks "where does
+ * this initiative stand?", which the PR range cannot answer at all: on a branch level with `main`
+ * the range is EMPTY, so every initiative reported `no implementation commits in this range` and
+ * collapsed to stage `spec`. A delivered initiative rendered identically to one never started.
+ *
+ * Splitting them means a rule can read `done` on the board and still be evaluated inside the gate.
+ * That is intended and is stated in the board's own footer, so it never reads as a discrepancy.
+ */
+function historyRange(root) {
+  const trunk = ['origin/main', 'main', 'origin/master', 'master']
+    .find((c) => git(root, ['rev-parse', '--verify', '--quiet', c]));
+  return buildRange(root, { spec: trunk || 'HEAD', whole: true });
+}
+
+/*
+ * ONE pass over the range, not one git call per question.
+ *
+ * Two `git log` invocations build every index the ladder needs: which paths each commit CHANGED
+ * (for buildCommits) and where each path was ADDED (for firstAppearance). Previously firstAppearance
+ * shelled out once per path per initiative and buildCommits ran `git show` once per commit per
+ * initiative — 330+ processes for the board on an empty range (23 s), and O(commits × initiatives)
+ * on a full one, which is what made full history look impossible rather than merely unimplemented.
+ */
+function buildRange(root, { spec, whole }) {
   if ((git(root, ['rev-parse', '--is-shallow-repository']) || '').trim() === 'true') {
     return { ok: false, reason: 'shallow clone — no history to order commits by (CI needs fetch-depth: 0)' };
   }
-  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; }
+  let range = spec;
+  if (!range) {
+    const candidates = [];
+    if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
+    candidates.push('origin/main', 'main', 'origin/master', 'master');
+    for (const c of candidates) {
+      if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
+      const mb = git(root, ['merge-base', c, 'HEAD']);
+      if (mb && mb.trim()) { base = mb.trim(); break; }
+    }
+    range = base ? `${base}..HEAD` : 'HEAD';
   }
-  const spec = base ? `${base}..HEAD` : 'HEAD';
-  const log = git(root, ['log', '--reverse', '--format=%H', spec]);
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct', '--name-only', range]);
   if (log == null) return { ok: false, reason: 'git history unreadable' };
-  const shas = log.split('\n').map((s) => s.trim()).filter(Boolean);
+
+  const shas = [];
+  const changed = [];                 // index -> string[] of paths touched
+  const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  for (const chunk of log.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const lines = chunk.split('\n');
+    const head = (lines.shift() || '').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));
+  }
   const index = new Map();
   shas.forEach((sha, i) => index.set(sha, i));
-  return { ok: true, base, index, shas, wholeHistory: !base };
+
+  // Where each path was ADDED, as an index into the same range. `--diff-filter=A` in one pass.
+  const added = new Map();
+  const addLog = git(root, ['log', '--reverse', '--format=%x1e%H', '--diff-filter=A', '--name-only', range]);
+  if (addLog != null) {
+    for (const chunk of addLog.split('\x1e')) {
+      if (!chunk.trim()) continue;
+      const lines = chunk.split('\n');
+      const sha = (lines.shift() || '').trim();
+      const at = index.has(sha) ? index.get(sha) : null;
+      if (at == null) continue;
+      for (const f of lines.map((s) => s.trim()).filter(Boolean)) {
+        if (!added.has(f)) added.set(f, at);
+      }
+    }
+  }
+  return { ok: true, base, index, shas, changed, dates, added, wholeHistory: whole ? true : !base };
 }
 
 /*
@@ -200,6 +263,10 @@ function commitRange(root) {
 function firstAppearance(root, range, rel) {
   const onDisk = fs.existsSync(path.join(root, rel));
   if (!range.ok) return onDisk ? undefined : null;
+  // The single-pass index answers first, and over the whole trunk it answers everything that has
+  // ever been committed — so the fallback below only runs for a PR range, where "added before the
+  // range" and "never committed" are genuinely different answers and only git can tell them apart.
+  if (range.added && range.added.has(rel)) return range.added.get(rel);
   const log = git(root, ['log', '--diff-filter=A', '--reverse', '--format=%H', '--', rel]);
   const sha = log ? log.split('\n').map((s) => s.trim()).filter(Boolean)[0] : null;
   if (!sha) return onDisk ? Infinity : null;
@@ -213,9 +280,10 @@ 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));
+    // range.changed came from the range's own single pass; the per-commit `git show` this replaced
+    // ran once per commit PER INITIATIVE, which is why the board took 23 s before it read anything.
+    const files = (range.changed && range.changed[i]) || [];
+    const hit = files.find((f) => isBuildPath(f, lane));
     if (!hit) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
@@ -290,10 +358,29 @@ function computeWorkflow(id, opts) {
   const effLane = knownLane ? lane : 'feature';           // unknown lane = strictest, as the bash gate does
   const range = (opts && opts.range) || commitRange(root);
   // See ENFORCED_FROM: git decides, the frontmatter only breaks a tie git cannot see.
+  //
+  // `recIdx === -1` — "the record predates this range" — is the right test for a PR range and a
+  // MEANINGLESS one over the whole trunk, where nothing predates the range and every legacy record
+  // would suddenly be enforced. So the commit DATE decides whenever the range can supply it, and
+  // -1 keeps its meaning for the gate's range. Same question, asked of evidence that survives both.
   const recIdx = firstAppearance(root, range, recRel);
-  const legacy = (recIdx === undefined || recIdx === null)
-    ? String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM   // fallback only — see ENFORCED_FROM
-    : recIdx === -1;
+  const recAt = (range.dates && typeof recIdx === 'number' && recIdx >= 0) ? range.dates[recIdx] : null;
+  /*
+   * `reconstructed_from` — the merge date of work whose record was written afterwards.
+   *
+   * A record backfilled today for a PR that merged in June has TODAY's commit date, so the date
+   * test would enforce today's rules on work that predates them and report a violation nobody
+   * could ever have avoided. The declared merge date decides instead.
+   *
+   * This is not an escape hatch: it must name a date, that date is checkable against the merge it
+   * claims, and declaring one AFTER `ENFORCED_FROM` makes the record non-legacy — so work that
+   * genuinely skipped the loop still reports blocked, which is the point of writing it down.
+   */
+  const recon = String(fm.reconstructed_from || '').trim().slice(0, 10);
+  const legacy = recIdx === -1 ? true
+    : /^\d{4}-\d{2}-\d{2}$/.test(recon) ? recon < ENFORCED_FROM
+      : recAt ? new Date(recAt * 1000).toISOString().slice(0, 10) < ENFORCED_FROM
+        : String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM;   // fallback — see ENFORCED_FROM
   /*
    * `legacy` answers the ENFORCEMENT question — should this PR fail? It is NOT the visibility
    * question. Filtering the board by it was a real bug: on `main`, every record is legacy, so the
@@ -304,7 +391,12 @@ function computeWorkflow(id, opts) {
    * `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;
+  // `● in this change` must keep meaning "the diff under review touches this". Over the whole trunk
+  // that is true of everything, which makes the marker noise — so the board passes the GATE's range
+  // separately and the marker is answered from that, or dropped when there is no such range.
+  const changeRange = (opts && opts.changeRange) || (range.wholeHistory ? null : range);
+  const chgIdx = changeRange ? firstAppearance(root, changeRange, recRel) : null;
+  const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
   const lastActivity = (() => {
     const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
     const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
@@ -522,10 +614,14 @@ function computeWorkflow(id, opts) {
         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',
+        // `legacy` applies here exactly as it does to O4. It always should have — the rule simply
+        // never fired for a legacy record while the board shared the gate's PR range, because an
+        // empty range has no build commit to be out of order with. Reading the trunk exposed it:
+        // 81 records that predate enforcement were suddenly failing a rule written after them.
+        steps.push(step('spec', 'spec', legacy ? 'unknown' : 'blocked',
           `ORDER VIOLATION — implementation (${build.sample}) was committed BEFORE ${late} first appeared`,
           'the rubric is the spec (D13). Land the spec artifacts in an earlier commit than the build, or split this PR so the spec lands first',
-          { blocking: true, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
+          { blocking: !legacy, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
       }
     }
   }
@@ -776,6 +872,10 @@ function renderBoard(rows, opts) {
   out.push('');
   // Never a silent cap — a truncated list that does not say so reads as "that is everything".
   if (hidden) out.push(`  ${c(33, `+ ${hidden} more without a recorded acceptance, not shown`)} ${c(90, `— node ${opts.self} --all`)}`);
+  // The two ranges, said out loud. The board reads the whole trunk so a delivered initiative does
+  // not render as unstarted; the gate reads the PR so "spec before build" stays decidable. A rule
+  // can therefore read done here and still be evaluated on the PR — intended, and not a discrepancy.
+  out.push(`  ${c(90, 'derived from the whole trunk history; the CI gate evaluates order within the PR only')}`);
   out.push(`  ${c(90, `one initiative in detail:  node ${opts.self} <id>`)}`);
   out.push('');
   return out.join('\n');
@@ -871,8 +971,12 @@ function main(argv) {
     return 0;
   }
 
-  const range = commitRange(root);
-  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range }));
+  // R-7: the BOARD reads the trunk, not the pull request. The gate path above keeps commitRange().
+  // The PR range is still computed and passed alongside — it is what `● in this change` means, and
+  // it is the one thing the trunk range genuinely cannot answer.
+  const range = historyRange(root);
+  const changeRange = commitRange(root);
+  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range, changeRange }));
   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 }));
@@ -882,6 +986,9 @@ function main(argv) {
 module.exports = {
   computeWorkflow, renderLadder, renderBoard, listInitiatives, layout, inFlight, BOARD_CAP,
   parseLeadingFrontmatter, specimenRoute, surfaceRoute, priorsCitation, isBuildPath, commitRange,
+  // the board's trunk range, exported so the suite can assert the split: the same record is legacy
+  // under BOTH ranges, and `in this change` is false under the trunk one.
+  historyRange,
   ENFORCED_FROM,
 };
 

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/server.js

@@ -523,6 +523,10 @@ const ROLE_BY_DIR = {
   prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
   okrs: 'OKR', radar: 'radar', gtm: 'gtm', 'out-of-scope': 'rejected', 'harness-refine': 'harness',
   'design-export': 'design', explainers: 'explainer', fixtures: 'fixture',
+  // The initiative RECORD (planning/initiatives/<id>.md) is the canonical anchor+lane carrier and
+  // the only artifact that exists for work backfilled from a merge. Before it was a role, a record
+  // with no sibling PRD landed in `ungrouped` and the initiative was invisible here.
+  initiatives: 'record',
 };
 // ── D60 specimens: prototype/<id>/, deliberately OUTSIDE planning/ ───────────────────────────
 // The planning walk cannot reach them (planningRoots only finds `planning`), so a prototype leg was
@@ -575,17 +579,23 @@ function parseHead(full) {
     head = buf.slice(0, n).toString('utf8');
   } catch { return {}; }
   const id = head.match(/^\s*[-*]?\s*initiative_id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
+  // An initiative RECORD names itself with `id:`, not `initiative_id:`. Only the record role reads
+  // this (see docMeta) — a bare `id:` on any other document must not invent an initiative.
+  const rid = head.match(/^\s*id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
   const h1 = head.match(/^#\s+(.+)$/m);
-  // status/stage/anchor ride the PRD's identity block — the only initiative signal that lives on
-  // disk today. RICE/effort/milestones/progress do NOT (net-new state) and are never invented.
+  // The anchor and the lane are DECLARED state and are read as such — they say what the work is
+  // pointed at, never how far along it is. `status:`/`stage:` are deliberately NOT read: they were
+  // hand-typed free text (23 distinct values in this repo, 33 absent, several truncated mid-YAML)
+  // funnelled through a regex, so `build complete, PR #138` rendered as `building`. Position is
+  // derived from evidence in deliveryIndex/deriveState instead — see the surface explainer.
   const clean = (m) => m ? m[1].replace(/\*\*/g, '').split(/\s+[—–-]\s|\(/)[0].trim().slice(0, 48) : null;
-  const status = head.match(/^\s*[-*]?\s*status\s*:\s*(.+?)\s*$/mi);
-  const stage = head.match(/^\s*[-*]?\s*stage\s*:\s*(.+?)\s*$/mi);
   const kr = head.match(/^\s*[-*]?\s*parent[_-]?kr\s*:\s*(.+?)\s*$/mi);
+  const lane = head.match(/^\s*[-*]?\s*lane\s*:\s*(.+?)\s*$/mi);
   return {
     initiative: id ? id[1] : null,
+    recordId: rid ? rid[1] : null,
     title: h1 ? h1[1].replace(/^(PRD|Eval Rubric|Design Brief)\s*:\s*/i, '').trim() : null,
-    status: clean(status), stage: clean(stage), kr: clean(kr),
+    kr: clean(kr), lane: clean(lane),
   };
 }
 function roleAndStem(rel, base) {
@@ -608,8 +618,9 @@ function docMeta(root, full) {
   const meta = {
     mtimeMs: st.mtimeMs, path: rel, name: base, role,
     // frontmatter wins; the filename convention is the fallback, never the override
-    initiative: head.initiative || null, stem, title: head.title || null,
-    status: head.status || null, stage: head.stage || null, kr: head.kr || null,
+    initiative: head.initiative || (role === 'record' ? head.recordId : null) || null,
+    stem, title: head.title || null,
+    kr: head.kr || null, lane: head.lane || null,
   };
   metaCache.set(full, meta);
   return meta;
@@ -650,17 +661,17 @@ function initiativeIndex(root) {
     const k = keyFor(m);
     const art = { name: m.name, path: m.path, role: m.role, title: m.title };
     if (!k) { ungrouped.push(art); continue; }
-    if (!groups.has(k)) groups.set(k, { id: k, title: null, status: null, stage: null, kr: null, artifacts: [] });
+    if (!groups.has(k)) groups.set(k, { id: k, title: null, kr: null, lane: null, artifacts: [] });
     const g = groups.get(k);
     g.artifacts.push(art);
     if (m.role === 'PRD' && m.title) g.title = m.title;      // the PRD names the initiative
     else if (!g.title && m.title) g.title = m.title;
-    // status/stage/anchor: the PRD is authoritative; any artifact fills a gap, never overrides it
-    if (m.status && (m.role === 'PRD' || !g.status)) g.status = m.status;
-    if (m.stage && (m.role === 'PRD' || !g.stage)) g.stage = m.stage;
-    if (m.kr && (m.role === 'PRD' || !g.kr)) g.kr = m.kr;
+    // The anchor and lane are the RECORD's to declare (D56/D59 — it is what the gates read); the
+    // PRD fills a gap for legacy initiatives that predate repo-native records, never overrides it.
+    if (m.kr && (m.role === 'record' || !g.kr)) g.kr = m.kr;
+    if (m.lane && (m.role === 'record' || !g.lane)) g.lane = m.lane;
   }
-  const ROLE_ORDER = ['PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
+  const ROLE_ORDER = ['record', 'PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
   const initiatives = [...groups.values()].map((g) => {
     g.artifacts.sort((a, b) => {
       const ia = ROLE_ORDER.indexOf(a.role), ib = ROLE_ORDER.indexOf(b.role);
@@ -695,57 +706,207 @@ function library(root) {
 // client renders it; a surface that can't be produced returns ok:false and the client shows an
 // honest can't-produce state. RICE/effort/milestones/progress are NET-NEW state → emitted as null
 // ("— not tracked"), never invented (D14/D40 honesty).
-const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', landed: 'report' };
-function statusKey(raw) {
-  const s = String(raw || '').toLowerCase();
-  if (/block/.test(s)) return 'blocked';
-  if (/ship|merg|accept|closed|done|live/.test(s)) return 'landed';
-  if (/build|progress|in build|dogfood/.test(s)) return 'building';
-  if (/intake|spec|plan|draft|propos/.test(s)) return 'planning';
+const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', delivered: 'report', accepted: 'report', unknown: 'plan' };
+
+// ── Delivery evidence (board-delivery-truth R-2/R-3). ──────────────────────────────────────────
+// "Has this shipped?" answered from the trunk's own history rather than from anything anyone typed.
+//
+// ONE `git log` per trunk head, memoised on that sha — ~0.3s and ~800 KB on this repo's 1,214
+// commits, paid once and reused by every surface until the trunk moves. Local only: git reads the
+// object store on disk, so the suite's "no network" guarantee (K. Surfaces) is untouched.
+//
+// TWO signals, because one is not enough. The branch convention (`initiative/<id>`) is precise but
+// incomplete: 31% of this repo's merged PRs shipped on `claude/*` branches, which match no id. So a
+// commit that MENTIONS the id and TOUCHES a build path counts too. 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.
+const BUILD_EXCLUDE = /^(planning|okf|prototype)\//;
+function isDeliveryPath(f) {
+  if (!f) return false;
+  if (BUILD_EXCLUDE.test(f)) return false;
+  return !/^[^/]+\.md$/.test(f);      // root governance prose (DECISIONS.md, CLAUDE.md…) is not a build
+}
+const deliveryCache = new Map();      // root -> { head, index }
+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;
 }
-function statusFrom(g) {
-  return statusKey(g.status) || statusKey(g.stage) || 'planning';
+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) }; }
+}
+/**
+ * → { ok, reason?, byBranch:Set<id>, byMention:Set<id> }
+ * `ok:false` is a REAL answer and never degrades into "nothing was delivered" — the caller renders
+ * it red and marks every initiative's delivery `unknown` (R-3). A board that cannot read the
+ * history must say so; silently reporting `planning` for 110 shipped initiatives is the failure
+ * this whole initiative exists to remove.
+ */
+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(), 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;
+    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 five states, in precedence order. Every one of them names the artifact it was read from, so
+ * the surface can show its own evidence instead of asking to be trusted.
+ *
+ * `blocked` deliberately outranks `delivered`: work the PM RETURNED is work that needs them, and
+ * hiding that behind a delivery glyph would reproduce, in a new place, the exact failure of a board
+ * that reports green over a red underneath. (The PRD's R-1 table lists delivered first; this is the
+ * one ordering departure, made because the alternative buries a returned initiative.)
+ */
+function deriveState(ev) {
+  if (ev.accepted) return { state: 'accepted', why: `accepted by the PM${ev.acceptedAt ? ` on ${String(ev.acceptedAt).slice(0, 10)}` : ''}` };
+  if (ev.returned) return { state: 'blocked', why: 'the PM returned this at the Acceptance Gate' };
+  if (ev.needs) return { state: 'blocked', why: `${ev.needs} open item${ev.needs > 1 ? 's' : ''} in needs.json` };
+  // Not `planning`. An unreadable history means the evidence for the delivery states is missing,
+  // and `planning` is itself a claim ("nothing has happened") that the missing evidence cannot
+  // support. `unknown` is the only honest answer, and it is visibly not a resting state.
+  if (ev.delivery === 'unknown') return { state: 'unknown', why: 'the trunk history could not be read — delivery cannot be derived here' };
+  if (ev.deliveredBy) return { state: 'delivered', why: ev.deliveredBy === 'branch' ? 'an initiative/<id> branch merged to the trunk' : 'a commit on the trunk names this initiative and changes build files' };
+  if (ev.runs) return { state: 'building', why: `${ev.runs} run${ev.runs > 1 ? 's' : ''} logged, nothing merged yet` };
+  return { state: 'planning', why: 'no run, no merge, no acceptance — nothing has happened yet' };
+}
+// BOTH acceptance ledgers, oldest-wins-never: the workspace writes to its state dir, while the
+// ladder and every hand-recorded acceptance in pmos-self live in planning/runs/. Reading only the
+// state dir is why this surface reported 0 accepted against 23 real acceptance rows — the same
+// "one field, several readers, none agreeing" defect the anchor resolver was built to end.
+function acceptanceFilesFor(w) {
+  const out = [];
+  const d = stateDirFor(w);
+  if (d) out.push(path.join(d, 'acceptances.jsonl'));
+  if (w && w.root) out.push(path.join(w.root, 'planning', 'runs', 'acceptances.jsonl'));
+  return out;
 }
 function readAcceptances(w) {
-  const acc = new Map();   // initiative_id -> last action (accept | approve | return)
-  const f = acceptancesFileFor(w);
-  if (!f) return acc;
-  try {
-    for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+  const acc = new Map();   // initiative_id -> { action, at }
+  for (const f of acceptanceFilesFor(w)) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
       if (!line.trim()) continue;
       // Tolerate both shapes: this server's {action} and the kit's {accepted} (D54 adapter).
+      // THE BOOLEAN OUTRANKS THE LABEL. `action` is an open vocabulary describing what the PM did
+      // — this corpus holds accept, merge, publish, return — while `accepted` is the D12 verdict
+      // itself. Reading `action` first (the previous behaviour) meant every row labelled `merge` or
+      // `publish` carried `accepted: true` and was still not counted: 7 of 16 real acceptances went
+      // missing, and the surface reported those initiatives as merely `building`.
       try {
         const r = JSON.parse(line);
         if (!r.initiative_id) continue;
-        acc.set(r.initiative_id, r.action || (r.accepted === true ? 'accept' : r.accepted === false ? 'return' : null));
+        const label = String(r.action || '').toLowerCase();
+        const action = r.accepted === true ? 'accept'
+          : r.accepted === false ? 'return'
+            : label === 'return' ? 'return'
+              : ['accept', 'approve', 'merge', 'publish'].includes(label) ? 'accept'
+                : null;
+        const at = r.at || r.date || null;
+        // Last write wins, but a row with no timestamp never displaces a dated one.
+        const prev = acc.get(r.initiative_id);
+        if (prev && prev.at && !at) continue;
+        acc.set(r.initiative_id, { action, at });
       } catch {}
     }
-  } catch {}
+  }
   return acc;
 }
+// How many runs each initiative has logged — evidence that work STARTED, which is the only thing
+// separating `building` from `planning`. The file is the same one the ladder reads.
+function readRunCounts(w) {
+  const counts = new Map();
+  const d = stateDirFor(w);
+  const files = [];
+  if (d) files.push(path.join(d, 'agent-runs.jsonl'));
+  if (w && w.root) files.push(path.join(w.root, 'planning', 'runs', 'agent-runs.jsonl'));
+  for (const f of files) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const r = JSON.parse(line);
+        if (r && r.initiative_id) counts.set(r.initiative_id, (counts.get(r.initiative_id) || 0) + 1);
+      } catch {}
+    }
+  }
+  return counts;
+}
 function surfaceInitiatives(root, w) {
   const { initiatives } = initiativeIndex(root);
   const acc = readAcceptances(w);
+  const runs = readRunCounts(w);
+  const needsRaw = readNeeds(w) || [];
+  const needsBy = new Map();
+  for (const n of needsRaw) if (n && n.initiative_id) needsBy.set(n.initiative_id, (needsBy.get(n.initiative_id) || 0) + 1);
+
+  const del = deliveryIndex(root, initiatives.map((g) => g.id));
   const items = initiatives.map((g) => {
-    const sk = statusFrom(g);
+    const a = acc.get(g.id) || {};
+    const deliveredBy = !del.ok ? null : del.byBranch.has(g.id) ? 'branch' : del.byMention.has(g.id) ? 'mention' : null;
+    const { state, why } = deriveState({
+      accepted: a.action === 'accept' || a.action === 'approve', acceptedAt: a.at,
+      returned: a.action === 'return',
+      needs: needsBy.get(g.id) || 0,
+      delivery: del.ok ? 'known' : 'unknown',
+      deliveredBy,
+      runs: runs.get(g.id) || 0,
+    });
     return {
       id: g.id, title: g.title || null,
-      status: sk, statusText: g.status || g.stage || sk, phase: PHASE_OF[sk] || 'plan',
-      stage: g.stage || null, kr: g.kr || null,
-      accepted: acc.get(g.id) === 'accept',
-      artifacts: g.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path })),
+      status: state, statusText: why, phase: PHASE_OF[state] || 'plan',
+      // `stage` was the declared field this surface used to trust. It is gone, not renamed —
+      // the client renders `statusText`, which always names the artifact the state was read from.
+      stage: null, kr: g.kr || null, lane: g.lane || null,
+      accepted: state === 'accepted',
+      delivered: state === 'accepted' || state === 'delivered',
+      delivery_evidence: deliveredBy,
+      artifacts: g.artifacts.map((a2) => ({ role: a2.role, name: a2.name, path: a2.path })),
       // NET-NEW state — not on disk yet, so null (the surface renders "— not tracked", never a guess)
       rice: null, effort: null, milestones: null, progress: null, tracked: false,
     };
   });
   const by = (k) => items.filter((i) => i.status === k).length;
-  const needs = (readNeeds(w) || []).map((n) => ({
+  const needs = needsRaw.map((n) => ({
     t: n.question || '(unstated)', kind: n.kind || 'question', initiative_id: n.initiative_id || null,
   }));
   return {
     initiatives: items,
-    pulse: { total: items.length, planning: by('planning'), building: by('building'), blocked: by('blocked'), landed: by('landed') },
+    pulse: {
+      total: items.length, planning: by('planning'), building: by('building'),
+      blocked: by('blocked'), delivered: by('delivered'), accepted: by('accepted'),
+      unknown: by('unknown'),
+    },
+    // R-3: a failed read is reported, never absorbed. The client renders this RED above the list
+    // rather than letting 110 shipped initiatives quietly read `planning`.
+    delivery_read: del.ok ? null : (del.reason || 'the trunk history could not be read'),
     needs,
   };
 }
@@ -755,7 +916,7 @@ function surfaceRoadmap(root, w) {
     label, dates_tracked: false,
     items: items.filter((i) => keys.includes(i.status)).map((i) => ({ id: i.id, status: i.status, phase: i.phase, progress: i.progress })),
   });
-  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['landed'])]
+  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['delivered', 'accepted'])]
     .filter((g) => g.items.length);
   return { groups, note: 'dates are net-new state — grouped by status until a timeline is tracked' };
 }
@@ -932,12 +1093,16 @@ function surfaceReport(root, w) {
   const s = surfaceInitiatives(root, w);
   const line = (i) => `${i.id}${i.title ? ' — ' + i.title : ''}`;
   const inflight = s.initiatives.filter((i) => i.status === 'building' || i.status === 'blocked');
-  const landed = s.initiatives.filter((i) => i.status === 'landed');
+  // Delivered and accepted are reported SEPARATELY, not summed into one "landed" heading. The gap
+  // between them is the D12 Acceptance Gate's backlog — the number this report exists to surface.
+  const delivered = s.initiatives.filter((i) => i.status === 'delivered');
+  const accepted = s.initiatives.filter((i) => i.status === 'accepted');
   const sections = [
     { heading: 'In flight', items: inflight.map(line) },
-    { heading: 'Landed', items: landed.map(line) },
+    { heading: 'Delivered — acceptance not recorded', items: delivered.map(line) },
+    { heading: 'Accepted', items: accepted.map(line) },
     { heading: 'Needs you', items: s.needs.map((n) => n.t) },
-    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.landed} landed`] },
+    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.delivered} delivered · ${s.pulse.accepted} accepted`] },
   ];
   return { cadence: 'weekly', sections };
 }
@@ -3608,10 +3773,27 @@ async function handleRequest(req, res) {
       'and useful answer.',
     ].filter((l) => l !== '').join('\n');
 
+    // NOT typed blind into the PTY. An agent CLI opening a folder it has never seen shows a
+    // trust prompt first — and a fresh tenant repo is by definition such a folder, so the case this
+    // feature exists for is the exact case where blind input is swallowed by a security dialog and
+    // the drafting silently never happens. Found by installing the published kit and watching a real
+    // session sit at "Is this a project you trust?" with the prompt already gone.
+    //
+    // Auto-answering that dialog is not on the table: it is the PM's decision, not ours. So the
+    // prompt is PERSISTED and STAGED instead — it cannot be lost, and the PM sends it once the agent
+    // is actually at its input.
+    const promptFile = path.join(adir, 'prompt-' + Date.now() + '.md');
+    try { fs.writeFileSync(promptFile, prompt + '\n'); }
+    catch (e) { warnWriteFail('alignment prompt', e); return json(res, { ok: false, error: 'could not stage the drafting prompt' }, 500); }
+
     const s = spawnSession({ name: 'align: ' + path.basename(rel), agent: 'claude', ws: w.id,
-      origin: 'align:' + rel, initialInput: prompt + '\r' });
+      origin: 'align:' + rel });
     const started = !!(s && s.pty);
+    let staged = false;
+    if (started) { try { writeScratchpad(w, s.id, prompt); staged = true; } catch {} }
     return json(res, { ok: started, sessionId: s && s.id, targets, sink: adir,
+      prompt_file: promptFile, staged,
+      next: started ? 'the drafting prompt is staged in this session\'s scratchpad — answer any trust prompt the agent shows, then send it' : undefined,
       error: started ? undefined : ((s && s.note) || 'could not start the session') });
   }
   if (p === '/api/align/drafts') {
@@ -3626,8 +3808,19 @@ async function handleRequest(req, res) {
     let doc;
     try { doc = JSON.parse(fs.readFileSync(path.join(adir, pick), 'utf8')); }
     catch { return json(res, { ok: false, error: `the draft file '${pick}' is unreadable or not valid JSON` }, 500); }
-    const drafts = Array.isArray(doc.drafts) ? doc.drafts.filter((d) => d && typeof d.file === 'string') : [];
-    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts });
+    // A malformed draft is REFUSED at read, not half-rendered (contract crit 4). Silently dropping a
+    // bad draft would let the agent's mistake reach the PM as a shorter, unexplained list — the same
+    // "looks fine, is wrong" failure the anchored write guard exists to stop. An empty `drafts` array
+    // is valid and calm (crit 3): the agent looked and found nothing to realign.
+    if (!Array.isArray(doc.drafts)) {
+      return json(res, { ok: false, error: `the draft file '${pick}' has no drafts array — the agent did not produce the documented shape` }, 422);
+    }
+    for (const d of doc.drafts) {
+      if (!d || typeof d.file !== 'string' || typeof d.after !== 'string' || (d.before != null && typeof d.before !== 'string')) {
+        return json(res, { ok: false, error: `a draft in '${pick}' is missing a file or an after — refusing to render a partial set (crit 4)` }, 422);
+      }
+    }
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts: doc.drafts });
   }
   if (p === '/api/align/apply' && req.method === 'POST') {
     // Apply ONE drafted realignment. Same anchored guard as everything else that writes here: the
@@ -3969,4 +4162,9 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // where the anchor resolver is looked for — exported so the suite can assert the INSTALL
   // location is in the list. A dev checkout satisfies entry 1 and would hide the loss of entry 2
   // exactly as it hid the workflow engine's absence for four releases (PKG4).
-  ANCHOR_LIB_PATHS };
+  ANCHOR_LIB_PATHS,
+  // the delivery derivation (board-delivery-truth), exported so the suite can assert the three
+  // things that matter independently of a rendered page: that no declared field reaches a status,
+  // that an unreadable history reports rather than degrades, and that a planning-only commit does
+  // not count as delivery.
+  surfaceInitiatives, deliveryIndex, deriveState, isDeliveryPath };