create-pmos 0.52.0 → 0.53.0

package/workspace/lib/breakdown-export.js

@@ -0,0 +1,80 @@
+'use strict';
+/* breakdown-export.js — an initiative's breakdown as markdown, for a document or a message (pm-os-absorb Run 2, D86
+ * point 4.3, map-spec X7).
+ *
+ *   exportBreakdown(root, id) → { ok: true, id, markdown } | { ok: false, status, error }
+ *
+ * D86 point 4: a project document is an EXPORT of the Breakdown tree, so the document and the board it describes have
+ * one source and cannot disagree. The output is deterministic — the same ledger gives the same bytes, with no clock
+ * and no random part — so two exports can be compared with diff. Stage headers come in the stage order of the
+ * initiative's lane (lib/plan-tree.js), each with "n of m"; under each header the items in tree order, each with its
+ * state, owner, dates and the milestone mark. Proposed items (an agent's batch not kept yet) are listed with
+ * "proposed"; withdrawn items are left out. Items whose stage the lane does not have are listed under "Other".
+ *
+ * Nothing is written: the CLI prints the markdown, the route answers it, and the PM saves it where they choose.
+ * Work lanes only (D86 point 4): a document-lane initiative is a file already, so it is refused with 404.
+ * No heading or label says "plan" (glossary rule `plan`).
+ */
+const fs = require('fs');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const rows = require('./initiative-rows.js');
+const consoleState = require('./console-state');
+
+const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done' };
+const refuse = (status, error) => ({ ok: false, status, error });
+
+function ownerLabel(owner) {
+  const s = String(owner || '');
+  if (s === 'you') return 'you';
+  if (s === 'agent') return 'agent';
+  const m = /^(person|tracker):(.+)$/.exec(s);
+  return m ? m[2] : (s || 'no owner');
+}
+
+function itemLine(it) {
+  const bits = [STATE_LABEL[it.state] || it.state, ownerLabel(it.owner)];
+  if (it.start && it.due) bits.push(`${it.start} → ${it.due}`);
+  else if (it.due) bits.push(`due ${it.due}`);
+  else if (it.start) bits.push(`from ${it.start}`);
+  if (it.milestone) bits.push('milestone');
+  if (it.blocked) bits.push(`blocked: ${String(it.blocked.reason || '').replace(/\s+/g, ' ').trim()}`);
+  if (it.proposed) bits.push('proposed');
+  return `- [${it.state === 'done' ? 'x' : ' '}] ${it.title.replace(/\s+/g, ' ').trim()} · ${bits.join(' · ')}`;
+}
+
+function exportBreakdown(root, id) {
+  if (typeof id !== 'string' || !planTree.INIT_RE.test(id)) return refuse(400, 'an initiative id is required');
+  const file = planTree.recordPath(root, id);
+  if (!file) return refuse(404, `no initiative ${id} in this repository`);
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) return refuse(500, loaded.error);
+  let fm = {};
+  try { fm = loaded.engine.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {}; } catch { fm = {}; }
+  const { lane } = planTree.profileAndLane(root, id);
+  let groups;
+  try { groups = rows.workGroupOf(root); } catch { groups = {}; }
+  const declared = String(fm.lane || '').trim();
+  if (groups[Object.prototype.hasOwnProperty.call(groups, declared) ? declared : lane] !== 'work') {
+    return refuse(404, `${id} is not on a work lane; a document is a file and has no breakdown to export`);
+  }
+  const fold = planItems.readFold(root, { now: 0 });
+  const lay = planTree.layout({ root, initiative: id, fold, ladder: null, now: 0 });
+  const title = String(fm.title || id).replace(/\s+/g, ' ').trim();
+  const out = [`# ${title}`, '', `Initiative \`${id}\` · ${lay.lane} lane · anchor ${String(fm.parent_kr || 'none').trim()} · ${lay.progress.label}`, ''];
+  const section = (heading, ids) => {
+    out.push(heading, '');
+    if (!ids.length) out.push('No items.');
+    for (const itemId of ids) out.push(itemLine(lay.items[itemId]));
+    out.push('');
+  };
+  for (const st of lay.stages) {
+    if (!st.items.length) continue;
+    section(`## ${st.label}${st.count ? ` · ${st.count}` : ''}`, st.items);
+  }
+  if (lay.other.items.length) section('## Other', lay.other.items);
+  if (!lay.stages.some((s) => s.items.length) && !lay.other.items.length) out.push('No breakdown yet.', '');
+  return { ok: true, id, markdown: out.join('\n') };
+}
+
+module.exports = { exportBreakdown, itemLine };

package/workspace/lib/capture.js

@@ -0,0 +1,98 @@
+'use strict';
+/* capture.js — the ⌘K "Capture as note" writer (pm-os-absorb Run 3, PRD R11 and R16, X16).
+ *
+ *   write(stateDir, { text, actor, now? }) → { ok: true, id, file, path, n, day } | { ok: false, status, error }
+ *   list(stateDir)                         → [{ id, file, n, day, timestamp, by, text }], oldest first
+ *   render({ text, day, n, timestamp, by }) → the file's whole text
+ *
+ * A capture is ONE NOTE FILE, `<state>/requirements/capture-YYYY-MM-DD-<n>.md`, with `<n>` counting from 1 per UTC day.
+ * There is no ledger: the folder is the one the day's live-notes note and the report skill already read, and the next
+ * step (triage, Run 2, slice 2C) reads the notes newer than its last run and files each as a proposal. Capture itself
+ * decides nothing: it keeps the words, which is why it is the row ⌘K always offers (D71).
+ *
+ * The frontmatter is `type: Reference` (`Requirement` is not in scripts/frontmatter_registry.txt, and the Frontmatter
+ * Gate would refuse it), `title`, `timestamp` (ISO UTC), `source: capture` and `by`. `by` comes from the CALL PATH (the
+ * `actor` the route got from pm-guard), never from a field the caller sends. The body is the captured text, unchanged.
+ *
+ * THE FILE IS NEVER OVERWRITTEN. The write is exclusive (`wx`): when two captures race for one number, the loser takes
+ * the next. Nothing is read from outside the folder, and no capture is deleted or edited here.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DIR = 'requirements';
+const FILE_RE = /^capture-(\d{4}-\d{2}-\d{2})-(\d+)\.md$/;
+const MAX_TEXT = 8000;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+
+const refuse = (status, error) => ({ ok: false, status, error });
+
+/** The whole file. Pure, so the test can hold it to the fixture byte for byte. */
+function render({ text, day, n, timestamp, by }) {
+  const body = String(text).replace(/\r\n?/g, '\n').trim();
+  return `---\ntype: Reference\ntitle: "Capture ${day} ${n}"\ntimestamp: ${timestamp}\nsource: capture\nby: ${by}\n---\n\n${body}\n`;
+}
+
+/** The text a capture may carry: a non-empty string of at most MAX_TEXT characters, with no NUL. Null when it passes. */
+function textProblem(text) {
+  if (typeof text !== 'string') return 'The capture needs text.';
+  if (!text.trim()) return 'The capture is empty. Type the idea first.';
+  if (text.length > MAX_TEXT) return `The capture is too long. The limit is ${MAX_TEXT} characters.`;
+  if (text.includes('\u0000')) return 'The capture holds a character that a note cannot keep.';
+  return null;
+}
+
+/** The numbers already taken on `day`, from the file names in the folder. */
+function taken(dir, day) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const f of names) { const m = FILE_RE.exec(f); if (m && m[1] === day) out.push(Number(m[2])); }
+  return out;
+}
+
+function write(stateDir, { text, actor, now } = {}) {
+  if (!stateDir || typeof stateDir !== 'string') return refuse(409, 'This repository has no state folder to keep the capture in.');
+  const bad = textProblem(text);
+  if (bad) return refuse(400, bad);
+  if (!actor || typeof actor.by !== 'string' || !BY_RE.test(actor.by)) return refuse(500, 'capture: the writer needs the actor from the call path.');
+  const at = now instanceof Date && !Number.isNaN(now.getTime()) ? now : new Date();
+  const timestamp = at.toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const day = timestamp.slice(0, 10);
+  const dir = path.join(stateDir, DIR);
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { return refuse(500, 'The capture could not be saved: ' + String((e && e.message) || e).slice(0, 160)); }
+  let n = Math.max(0, ...taken(dir, day)) + 1;
+  for (let tries = 0; tries < 50; tries++, n++) {
+    const file = `capture-${day}-${n}.md`;
+    try {
+      fs.writeFileSync(path.join(dir, file), render({ text, day, n, timestamp, by: actor.by }), { flag: 'wx' });
+      return { ok: true, id: file.replace(/\.md$/, ''), file, path: path.join(dir, file), n, day, timestamp };
+    } catch (e) {
+      if (e && e.code === 'EEXIST') continue;   // another capture took this number first
+      return refuse(500, 'The capture could not be saved: ' + String((e && e.message) || e).slice(0, 160));
+    }
+  }
+  return refuse(500, 'The capture could not be saved: no free number today.');
+}
+
+/** Every capture note in the folder, oldest first. A file that does not parse as a capture is left out, not an error. */
+function list(stateDir) {
+  const dir = path.join(stateDir, DIR);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const rows = [];
+  for (const file of names) {
+    const m = FILE_RE.exec(file);
+    if (!m) continue;
+    let raw = '';
+    try { raw = fs.readFileSync(path.join(dir, file), 'utf8'); } catch { continue; }
+    const f = /^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/.exec(raw);
+    if (!f) continue;
+    const fm = {};
+    for (const line of f[1].split('\n')) { const k = /^([a-z_]+): ?(.*)$/.exec(line); if (k) fm[k[1]] = k[2].replace(/^"(.*)"$/, '$1'); }
+    rows.push({ id: file.replace(/\.md$/, ''), file, day: m[1], n: Number(m[2]), timestamp: fm.timestamp || '', by: fm.by || '', text: f[2].replace(/\n$/, '') });
+  }
+  return rows.sort((a, b) => (a.day === b.day ? a.n - b.n : a.day < b.day ? -1 : 1));
+}
+
+module.exports = { DIR, MAX_TEXT, FILE_RE, render, write, list, textProblem };

package/workspace/lib/engine/plan-items-stage.js

@@ -0,0 +1,271 @@
+'use strict';
+/* plan-items-stage.js — the stage of each plan item, and the Build rule, for the workflow engine (pm-os-absorb Run 4,
+ * PRD R6, map-spec X29).
+ *
+ *   foldStages(text)               → { items: { [id]: { initiative, stage } }, withdrawn: [id…] }
+ *   readFactory(text)              → { items: { [workItemId]: { initiative, plan_item, integrated, withdrawn } } }
+ *   mainTree(root)                 → the main working tree of root's repository (root itself when it is not linked)
+ *   buildRule({ planText, workText, initiative })
+ *                                  → { applies, materialized: [id…], integrated: [id…], pending: [id…] }
+ *   buildRuleFor(root, id)         → the same, read from the repository's two ledgers; { applies: false } when neither
+ *                                    file is there
+ *   planItemsPath(root) · workItemsPath(root)
+ *
+ * THE BUILD RULE (R6). Items never complete a stage, with one exception: a code initiative's Build stage is done when
+ * every MATERIALIZED item under it is integrated. A materialized item is a work item whose `declared` line names a
+ * plan item (`plan_item`, D86 point 1) that sits in the Build stage of the same initiative and is not withdrawn. A
+ * work item that is withdrawn in the factory ledger is not counted. When an initiative has no materialized item under
+ * Build, the rule does not apply and the engine decides the Build step from the commits, as before.
+ *
+ * WHY THIS FILE EXISTS (X29). The engine (scripts/workflow-state.js) is vendored into the workspace bundle and into
+ * the kit, so it cannot require workspace/lib/plan-items.js. This module reads the same ledger with a small pure fold
+ * of its own. workspace/plan-items-stage-parity.test.js holds it to plan-items.js's fold (stage, withdrawn) and to
+ * scripts/work-item.js's fold (integrated, withdrawn) on every fixture, so a rule added to one fold and not the
+ * other fails a test instead of making CI and the workspace disagree.
+ *
+ * DELIBERATELY FLAT in scripts/, not scripts/lib/ (read-jsonl.js has the same note): the kit and the workspace bundle
+ * vendor the engine's require closure by BASENAME into one directory, so a `./lib/` require from the engine would
+ * load in this checkout and break in every vendored copy.
+ *
+ * The factory half is D65's ORDER, restated small: lines sorted by instant (ledger order breaks a tie), the type's
+ * chain (scripts/work-item.js CHAIN, chainFor), and a two-outcome node satisfied by its LATEST outcome (failed revokes
+ * verified, released revokes claimed). A line that skips its predecessor is not counted, the same as deriveItems
+ * discards it, so a hand-appended `integrated` with no `verified` before it never makes the Build step done. It does
+ * not restate the per-field schema: scripts/check-work-items.js fails CI on a schema-invalid line. Restated, not
+ * required, because work-item.js cannot be vendored (its sink guard requires ./lib/sink.js); the parity test holds the
+ * two folds to one answer, on valid and on invalid ledgers.
+ *
+ * BOTH LEDGERS ARE READ FROM THE MAIN WORKING TREE, as lib/plan-items.js, lib/plan-ledgers.js and lib/factory-join.js
+ * read them. From a linked worktree (where every factory agent works) the engine, check-work-items and the workspace
+ * then read the same two files. mainTree is the filesystem-only walk of lib/plan-tree.js mainTree, restated here.
+ *
+ * Pure apart from the two file reads in buildRuleFor. No network, no git, no clock. Zero dependencies, stock Node.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// ── the plan-items schema, as workspace/lib/plan-items.js lineErr states it ──────────────────────────────────────
+// Every line that lib/plan-items.js ignores must be ignored here too, or the two folds disagree about which line of
+// a repeated event id wins. So the whole stored-line schema is restated, not only the stage fields.
+const EVENTS = ['planned', 'set', 'moved', 'flagged', 'withdrawn', 'kept'];
+const STATES = ['todo', 'doing', 'review', 'done'];
+const SET_FIELDS = ['title', 'stage', 'order', 'owner', 'after', 'start', 'due', 'milestone', 'note'];
+const EVIDENCE_KINDS = ['commit', 'pr', 'file', 'session', 'note'];
+const ID_RE = /^(.+)\.([0-9a-z]{10})$/;
+const INIT_RE = /^[A-Za-z0-9][\w.-]{0,119}$/;
+const EID_RE = /^[0-9a-z]{12}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+
+const isStr = (v) => typeof v === 'string';
+const oneLine = (v, max) => isStr(v) && v.trim().length >= 1 && v.length <= max && !/[\r\n]/.test(v);
+const initiativeOf = (id) => { const m = ID_RE.exec(String(id || '')); return m ? m[1] : null; };
+function ownerOk(v) {
+  if (v === 'you' || v === 'agent') return true;
+  const m = /^(person|tracker):(.+)$/s.exec(String(v));
+  return !!m && m[2].length >= 1 && m[2].length <= 60 && !/[\r\n]/.test(m[2]);
+}
+const dateOk = (v) => v === null || (isStr(v) && DATE_RE.test(v) && (() => {
+  const t = Date.parse(v + 'T00:00:00Z');
+  return Number.isFinite(t) && new Date(t).toISOString().slice(0, 10) === v;
+})());
+function evidenceBad(e) {
+  if (!e || typeof e !== 'object' || Array.isArray(e) || !EVIDENCE_KINDS.includes(e.kind) || !isStr(e.ref)) return true;
+  const ref = e.ref;
+  if (e.kind === 'commit') return !/^[0-9a-f]{7,40}$/i.test(ref);
+  if (e.kind === 'pr') return !/^#?\d+$/.test(ref);
+  if (e.kind === 'file') return !ref || ref.length > 300 || path.isAbsolute(ref) || ref.split(/[\\/]/).includes('..') || /[\r\n]/.test(ref);
+  if (e.kind === 'session') return !/^sess-\d+$/.test(ref);
+  return !oneLine(ref, 200);
+}
+function fieldBad(k, v) {
+  switch (k) {
+    case 'title': return !oneLine(v, 200);
+    case 'stage': return !(isStr(v) && v.trim());
+    case 'order': return !(typeof v === 'number' && Number.isFinite(v));
+    case 'owner': return !ownerOk(v);
+    case 'after': return !(Array.isArray(v) && v.every((x) => isStr(x) && ID_RE.test(x)));
+    case 'start': case 'due': return !dateOk(v);
+    case 'milestone': return typeof v !== 'boolean';
+    case 'note': return !(v === null || (isStr(v) && v.length <= 1000));
+    default: return true;
+  }
+}
+/** true when lib/plan-items.js would ignore this stored line as schema-invalid. */
+function lineBad(r) {
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return true;
+  if (r.v !== 1 || !isStr(r.eid) || !EID_RE.test(r.eid) || !EVENTS.includes(r.ev)) return true;
+  if (!isStr(r.by) || !BY_RE.test(r.by) || (r.via !== 'ui' && r.via !== 'cli')) return true;
+  if (!isStr(r.at) || !AT_RE.test(r.at) || Number.isNaN(Date.parse(r.at))) return true;
+  if (!isStr(r.initiative) || !INIT_RE.test(r.initiative)) return true;
+  if (r.ev !== 'kept' && (!isStr(r.item) || !ID_RE.test(r.item) || initiativeOf(r.item) !== r.initiative)) return true;
+  switch (r.ev) {
+    case 'planned': return SET_FIELDS.some((k) => fieldBad(k, r[k]));
+    case 'set': {
+      const f = r.fields;
+      if (!f || typeof f !== 'object' || Array.isArray(f) || !Object.keys(f).length) return true;
+      return Object.keys(f).some((k) => !SET_FIELDS.includes(k)
+        || (!((k === 'start' || k === 'due' || k === 'note') && f[k] === null) && fieldBad(k, f[k])));
+    }
+    case 'moved':
+      if (!STATES.includes(r.to)) return true;
+      if (r.evidence !== undefined && evidenceBad(r.evidence)) return true;
+      if (r.override !== undefined && (r.override !== true || !String(r.by).startsWith('pm:'))) return true;
+      return false;
+    case 'flagged': return r.blocked === true ? !oneLine(r.reason, 200) : r.blocked !== false;
+    case 'withdrawn': return false;
+    case 'kept':
+      return r.item !== undefined || !isStr(r.batch) || !/^agent:/.test(r.batch)
+        || !Array.isArray(r.items) || !r.items.length || !r.items.every((x) => isStr(x) && ID_RE.test(x));
+    default: return true;
+  }
+}
+
+/**
+ * The plan-items ledger text → each live item's initiative and stage, and the withdrawn ids. The same order-free
+ * fold as lib/plan-items.js: drop byte-identical duplicates, sort by (at, eid, line), keep the first line of an event
+ * id, ignore a second `planned` of one id and every line after a withdraw.
+ */
+function foldStages(text) {
+  const seenRaw = new Set();
+  const lines = [];
+  for (const raw0 of String(text == null ? '' : text).split('\n')) {
+    const raw = raw0.replace(/\r$/, '').trim();
+    if (!raw || seenRaw.has(raw)) continue;
+    let rec;
+    try { rec = JSON.parse(raw); } catch { continue; }
+    if (lineBad(rec)) continue;
+    seenRaw.add(raw);
+    lines.push({ raw, rec });
+  }
+  lines.sort((a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at))
+    || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0)
+    || (a.raw < b.raw ? -1 : a.raw > b.raw ? 1 : 0));
+  const seenEid = new Set();
+  const items = {};
+  const withdrawn = new Set();
+  for (const { rec } of lines) {
+    if (seenEid.has(rec.eid)) continue;
+    seenEid.add(rec.eid);
+    if (rec.ev === 'kept') continue;
+    if (rec.ev === 'planned') {
+      if (items[rec.item] || withdrawn.has(rec.item)) continue;
+      items[rec.item] = { initiative: rec.initiative, stage: rec.stage };
+      continue;
+    }
+    const it = items[rec.item];
+    if (!it || withdrawn.has(rec.item)) continue;
+    if (rec.ev === 'set' && Object.prototype.hasOwnProperty.call(rec.fields, 'stage')) it.stage = rec.fields.stage;
+    if (rec.ev === 'withdrawn') { delete items[rec.item]; withdrawn.add(rec.item); }
+  }
+  return { items, withdrawn: [...withdrawn].sort() };
+}
+
+/* D65(d)'s chain per type (scripts/work-item.js CHAIN, chainFor, NEGATED_BY, standsSatisfied), restated. */
+const FACTORY_EVENTS = ['declared', 'claimed', 'released', 'verified', 'failed', 'integrated', 'shipped', 'withdrawn'];
+const CHAIN_DEFAULT = ['claimed', 'verified', 'integrated', 'shipped'];
+const CHAIN_HOTFIX = ['claimed', 'verified', 'shipped', 'integrated'];
+const chainFor = (type) => (type === 'spike-item' ? CHAIN_DEFAULT.filter((e) => e !== 'verified') : type === 'hotfix' ? CHAIN_HOTFIX : CHAIN_DEFAULT);
+const NEGATED_BY = { verified: 'failed', claimed: 'released' };
+function standsSatisfied(history, need) {
+  const negator = NEGATED_BY[need];
+  if (!negator) return history.includes(need);
+  for (let i = history.length - 1; i >= 0; i -= 1) {
+    if (history[i] === need) return true;
+    if (history[i] === negator) return false;
+  }
+  return false;
+}
+
+/** The factory ledger text → per work item: its initiative, its plan item, and whether it is integrated or withdrawn. */
+function readFactory(text) {
+  const lines = [];
+  String(text == null ? '' : text).split('\n').forEach((raw, idx) => {
+    if (!raw.trim()) return;
+    let rec;
+    try { rec = JSON.parse(raw); } catch { return; }
+    if (!rec || typeof rec !== 'object' || !isStr(rec.item_id) || !isStr(rec.initiative_id) || !FACTORY_EVENTS.includes(rec.event)) return;
+    const t = typeof rec.at === 'string' ? Date.parse(rec.at) : NaN;
+    if (Number.isNaN(t)) return;
+    lines.push({ rec, idx, t });
+  });
+  lines.sort((a, b) => a.t - b.t || a.idx - b.idx);
+  const items = {}; const fold = {};
+  for (const { rec } of lines) {
+    const id = rec.item_id;
+    if (rec.event === 'declared') {
+      if (items[id]) continue;   // declared twice: the fold keeps the first
+      items[id] = { initiative: rec.initiative_id, plan_item: isStr(rec.plan_item) ? rec.plan_item : null, integrated: false, withdrawn: false };
+      fold[id] = { type: rec.type, history: ['declared'] };
+      continue;
+    }
+    const it = items[id];
+    if (!it || it.withdrawn) continue;
+    const chain = chainFor(fold[id].type);
+    const pos = chain.indexOf(rec.event === 'failed' ? 'verified' : rec.event);
+    if (pos > 0 && !standsSatisfied(fold[id].history, chain[pos - 1])) continue;   // out of order: deriveItems discards it
+    fold[id].history.push(rec.event);
+    if (rec.event === 'integrated') it.integrated = true;
+    if (rec.event === 'withdrawn') it.withdrawn = true;
+  }
+  return { items };
+}
+
+/** The Build rule over the two ledgers' text, for one initiative. */
+function buildRule({ planText, workText, initiative }) {
+  const plan = foldStages(planText);
+  const work = readFactory(workText);
+  const materialized = []; const integrated = []; const pending = [];
+  for (const [wid, w] of Object.entries(work.items)) {
+    if (w.initiative !== initiative || w.withdrawn || !w.plan_item) continue;
+    const p = plan.items[w.plan_item];
+    if (!p || p.initiative !== initiative || p.stage !== 'build') continue;
+    materialized.push(wid);
+    (w.integrated ? integrated : pending).push(wid);
+  }
+  const sort = (a) => a.sort();
+  return { applies: materialized.length > 0, materialized: sort(materialized), integrated: sort(integrated), pending: sort(pending) };
+}
+
+/** The main working tree of root's repository: root itself, unless root is a linked worktree. Filesystem only. */
+function mainTree(root) {
+  try {
+    const dotgit = path.join(root, '.git');
+    if (fs.statSync(dotgit).isDirectory()) return root;
+    const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotgit, 'utf8'));
+    if (!m) return root;
+    const gitdir = path.resolve(root, m[1].trim());
+    const common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
+    if (path.basename(common) !== '.git') return root;
+    const main = path.dirname(common);
+    return fs.statSync(path.join(main, '.git')).isDirectory() ? main : root;
+  } catch { return root; }
+}
+
+/** The plan-items ledger of a repository: planning/runs/ for PMOS-self, pmos/state/ in a kit (workflow-state layout). */
+function planItemsPath(root) {
+  const main = mainTree(path.resolve(String(root)));
+  const self = path.join(main, 'planning', 'initiatives');
+  const kit = path.join(main, 'pmos', 'state', 'initiatives');
+  const isKit = !fs.existsSync(self) && fs.existsSync(kit);
+  return isKit ? path.join(main, 'pmos', 'state', 'plan-items.jsonl') : path.join(main, 'planning', 'runs', 'plan-items.jsonl');
+}
+/** The D65 factory ledger of a repository (the one scripts/check-work-items.js reads), in the main working tree. */
+const workItemsPath = (root) => path.join(mainTree(path.resolve(String(root))), 'planning', 'work-items.jsonl');
+
+function readText(file) {
+  try { return { ok: true, text: fs.readFileSync(file, 'utf8') }; }
+  catch (e) { return { ok: e && e.code === 'ENOENT', text: '', missing: true, error: e && e.code !== 'ENOENT' ? String(e.message || e) : null }; }
+}
+
+function buildRuleFor(root, initiative) {
+  const work = readText(workItemsPath(root));
+  if (work.missing && work.ok) return { applies: false, materialized: [], integrated: [], pending: [] };
+  if (!work.ok) return { applies: false, unknown: true, reason: `the factory ledger could not be read: ${work.error}`, materialized: [], integrated: [], pending: [] };
+  const plan = readText(planItemsPath(root));
+  if (!plan.ok) return { applies: false, unknown: true, reason: `the plan-items ledger could not be read: ${plan.error}`, materialized: [], integrated: [], pending: [] };
+  return buildRule({ planText: plan.text, workText: work.text, initiative });
+}
+
+module.exports = { foldStages, readFactory, buildRule, buildRuleFor, mainTree, planItemsPath, workItemsPath, lineBad };

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

@@ -1067,8 +1067,24 @@ function computeWorkflowDerived(id, opts) {
    * commits in this range" is a statement about the RANGE, and on a branch level with `main` that
    * range is legitimately empty. A reader who cannot tell those apart calls the second one "never
    * built", which is the console's half of this defect.
+   *
+   * THE BUILD RULE (PRD R6, pm-os-absorb Run 4). Items never complete a stage, with one exception: when plan items
+   * under Build were materialized (a D65 `declared` line names them as `plan_item`, D86 point 1), the step is done
+   * when every one of those work items is integrated, and pending until then, whatever the commits say. With no
+   * materialized item the commits decide, as above. The rule reads both ledgers through plan-items-stage.js, the
+   * engine's own pure fold (X29: the engine cannot require workspace/lib). A broken delivered_by stays blocked first.
    */
-  steps.push(build.unknown
+  const buildRule = require('./plan-items-stage').buildRuleFor(root, id);
+  const ruleStep = build.failedDeclaration || !(buildRule.applies || buildRule.unknown) ? null
+    : buildRule.unknown
+      ? step('build', 'build', 'unknown', buildRule.reason)
+      : buildRule.pending.length === 0
+        ? step('build', 'build', 'done',
+          `every materialized item under Build is integrated (${buildRule.integrated.length} of ${buildRule.materialized.length} in planning/work-items.jsonl)`)
+        : step('build', 'build', 'pending',
+          `${buildRule.integrated.length} of ${buildRule.materialized.length} materialized item(s) under Build integrated — waiting on ${buildRule.pending.join(', ')}`,
+          'merge each work item with a `Work-Item: <id>` trailer on the trunk, then run `pmos verify-work`');
+  steps.push(ruleStep || (build.unknown
     ? step('build', 'build', 'unknown', build.reason || range.reason)
     : build.failedDeclaration
       // REPORTED, never CI-blocking — the same stance R1 takes on an unresolvable anchor. Making a
@@ -1087,7 +1103,7 @@ function computeWorkflowDerived(id, opts) {
             : '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`));
+            : `${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'));
@@ -1325,9 +1341,19 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   const accepted = cachedJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
     .filter((a) => a && a.initiative_id === id && a.accepted === true);
   const acceptedOn = accepted.length ? (accepted[accepted.length - 1].accepted_at || accepted[accepted.length - 1].at) : null;
+  // D86 point 3 — a report is approved when the PM issues it: an `issued` line in issues.jsonl naming its doc_path.
+  // Its own minimal parse (X29: the vendored engine never requires workspace/lib); a line counts only if the PM wrote it.
+  const norm = (p) => String(p || '').trim().replace(/^\.\//, '');
+  const issued = effLane !== 'report' || !docPath ? []
+    : cachedJsonl(path.join(L.runsDir, 'issues.jsonl')).filter((r) => r && r.ev === 'issued' && norm(r.path) === norm(docPath)
+      && /^pm:/.test(String(r.by || '')) && (r.via === 'ui' || r.via === 'cli') && /^[0-9a-f]{40}$/.test(String(r.sha || '')));
   steps.push(!flows('approved') ? skipped('approved', 'approved')
+    : issued.length
+    ? step('approved', 'approved', 'done', `issued by the PM on ${String(issued[0].at || '').slice(0, 10)} (issues.jsonl)`)
     : accepted.length
     ? step('approved', 'approved', 'done', `accepted by the PM${acceptedOn ? ' on ' + String(acceptedOn).slice(0, 10) : ''}`)
+    : effLane === 'report'
+    ? step('approved', 'approved', 'pending', 'awaiting the PM\'s Issue (D86 point 3)', 'the PM issues the report (pmos report issue, or Issue on Reports) — never automatic')
     : step('approved', 'approved', 'pending', 'awaiting the PM\'s acceptance (D12)', 'the PM accepts the document — never automatic'));
 
   if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));