create-pmos 0.51.0 → 0.53.0

package/payload/scripts/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/payload/scripts/pmos-log.sh

@@ -151,7 +151,7 @@ case "$cmd" in
     nonempty note "$4"
     run_exists "$1" || fail "run_id '$1' is not in state/runs.jsonl — log the run first (pmos-log.sh run ...), then accept it."
     acc=true; [ "$3" = fail ] && acc=false
-    append acceptances.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"accepted\":$acc,\"pm_label\":$(js "$3"),\"note\":$(js "${4:-}"),\"date\":\"$today\"}"
+    append acceptances.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"accepted\":$acc,\"pm_label\":$(js "$3"),\"note\":$(js "${4:-}"),\"date\":\"$today\",\"via\":\"cli\"}"
     ;;
   outcome)
     [ $# -ge 2 ] || fail "usage: outcome <initiative_id> <validated|refuted|inconclusive> [evidence]"
@@ -169,7 +169,7 @@ case "$cmd" in
     echo "✅ appended to state/discoveries.md: - $today $* #friction"
     ;;
   grant)
-    [ $# -ge 3 ] || fail "usage: grant <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes] [initiative_id]"
+    [ $# -ge 3 ] || fail "usage: grant <merge:<PR or branch>|publish:<artifact>|release:<initiative>:<batch-id>|lifecycle-bulk:<state>:<id>,…> <pm> <instruction> [ttl_minutes] [initiative_id]"
     nonempty pm "$2"; nonempty instruction "$3"
     row="$(python3 - "$1" "$2" "$3" "${4:-120}" "${5:-}" "$STATE" <<'PY'
 import datetime, json, os, re, secrets, sys
@@ -178,12 +178,23 @@ def die(m):
     sys.stderr.write("pmos-log: ERROR — %s\n" % m); sys.exit(1)
 if re.match(r"^(docs-sync|outward)(:|$)", scope):
     die('"%s" is a standing scope. Standing grants are not allowed in this release (D81). Mint one single-use grant per action.' % scope)
+# The same scopes and target patterns as scripts/record-grant.js and the cockpit mod's grants.mjs (D81;
+# D86 point 2 added release and lifecycle-bulk). scripts/tests/record-grant.test.js runs one table through all three.
+SLUG = r"[a-z0-9][a-z0-9._-]{0,99}"
+PATS = {
+    "merge": r"^(?:[0-9]{1,9}|[A-Za-z0-9][A-Za-z0-9._/-]{0,79})$",
+    "publish": r"^[A-Za-z0-9@][A-Za-z0-9@._/-]{0,99}$",
+    "release": r"^" + SLUG + r":[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+    "lifecycle-bulk": r"^(?:active|closed|on-hold|cancelled):" + SLUG + r"(?:," + SLUG + r"){0,19}$",
+}
+WHAT = {"merge": "PR number or branch name", "publish": "artifact name", "release": "<initiative>:<batch-id>",
+        "lifecycle-bulk": "<state>:<id>,<id>,… (one of active, closed, on-hold, cancelled, then 1 to 20 initiative ids)"}
 kind, sep, target = scope.partition(":")
-if not sep or kind not in ("merge", "publish"):
-    die('unknown scope "%s". Use merge:<PR number or branch> or publish:<artifact>.' % scope)
-pat = r"^(?:[0-9]{1,9}|[A-Za-z0-9][A-Za-z0-9._/-]{0,79})$" if kind == "merge" else r"^[A-Za-z0-9@][A-Za-z0-9@._/-]{0,99}$"
-if not re.match(pat, target) or "*" in target or ".." in target:
-    die('"%s" is not a single %s. A grant names one target; a wildcard is refused.' % (target, "PR number or branch name" if kind == "merge" else "artifact name"))
+if not sep or kind not in PATS:
+    die('unknown scope "%s". Use merge:<PR number or branch>, publish:<artifact>, release:<initiative>:<batch-id> or lifecycle-bulk:<state>:<id>,<id>,….' % scope)
+ids = target.partition(":")[2].split(",") if kind == "lifecycle-bulk" else []
+if not re.match(PATS[kind] + r"\Z", target) or "*" in target or ".." in target or len(set(ids)) != len(ids):
+    die('"%s" is not a single %s. A grant names one target; a wildcard is refused.' % (target, WHAT[kind]))
 if not re.match(r"^[0-9]{1,4}$", ttl) or not (1 <= int(ttl) <= 1440):
     die("ttl_minutes must be a whole number from 1 to 1440, got '%s'." % ttl)
 if initiative:

package/payload/scripts/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`));

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-05T04:02:12Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T00:08:33Z"}
 status: stable
 ---
 

package/payload/state/log.md

@@ -2,6 +2,6 @@
 
 Newest first, ISO dates.
 
-## 2026-10-05
+## 2026-10-06
 
 - Adopted OKF v0.2 (D73).

package/workspace/bin/pmos.js

@@ -406,6 +406,18 @@ function doctor() {
     // Reads tracked .md files straight from disk (lib/kg-cli.js); needs no running server.
     code = require('../lib/kg-cli').run(process.argv.slice(2), { say });
   }
+  else if (cmd === 'item') {
+    // An initiative's breakdown items (pm-os-absorb Run 1): the same writer and fold as the workspace page,
+    // straight from disk, no running server. The write is attributed from this terminal, never from an argument.
+    code = await require('../lib/item-cli.js').run(process.argv.slice(2), { say });
+    await new Promise((r) => process.stdout.write('', r));   // drain a long --json before process.exit below
+  }
+  else if (require('../lib/pmos-verbs.js').has(cmd)) {
+    // pm-os-absorb Runs 2–5: one module per verb (lib/pmos-verbs.js). A verb whose run has not built it says so.
+    code = await require('../lib/pmos-verbs.js').run(cmd, process.argv.slice(2), {
+      say, call: async (m, p, b) => { const live = await discover(); return live.length ? api(live[0].port, m, p, b) : null; } });
+    await new Promise((r) => process.stdout.write('', r));
+  }
   else if (cmd === 'upgrade') {
     // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
     // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
@@ -417,13 +429,15 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive|kg]');
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive|kg|item|' + require('../lib/pmos-verbs.js').names().join('|') + ']');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
     say('  pmos schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
     say('  pmos skill …     list, read, create and edit skills');
     say('  pmos proactive … what is waiting for you, feedback, settings (pmos proactive --help)');
     say('  pmos kg …       find a card, a section or a decision\'s citers without reading whole files (pmos kg --help)');
+    say('  pmos item add|set|move|withdraw|list — an initiative\'s breakdown items (pmos item help)');
+    for (const line of require('../lib/pmos-verbs.js').helpLines()) say(line);
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {

package/workspace/cut-stub.js

@@ -0,0 +1,40 @@
+'use strict';
+/* PMOS workspace — the suites whose subject R29 cut (pm-os-absorb Run 3, slice 3D).
+ *
+ * The All repos, Knowledge, Memory, Skills and Scheduled views, and the Reports tab, are gone from the shell. The suites that
+ * drew them in a browser (pm-r29-portfolio, -knowledge, -memory, -skills-scheduled, -reports-addrepo) have nothing to draw.
+ * Each keeps its file and its name, and asserts what is left of its subject: the view is not in the table, its module is not
+ * on disk, and the thing that replaced it is still there. Every removed assertion is in workspace/replaced-tests.json
+ * (C03 to C11). No browser and no server: these are reads of the sources, so they run in milliseconds.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const PM = path.join(__dirname, 'public', 'pm');
+const read = (f) => { try { return fs.readFileSync(path.join(PM, f), 'utf8'); } catch { return null; } };
+const gone = (f) => !fs.existsSync(path.join(PM, f));
+/** The keys of `export const VIEWS = { … }` in panel-cockpit.js, in order. */
+const viewKeys = () => {
+  const m = /export const VIEWS = \{([\s\S]*?)\n\};/.exec(read('panel-cockpit.js') || '');
+  return m ? [...m[1].matchAll(/^ {2}(\w+):/gm)].map((x) => x[1]) : [];
+};
+/** The keys of `BOARD_MODULES = { … }` in panel-cockpit.js. */
+const boardKeys = () => {
+  const m = /BOARD_MODULES = \{([\s\S]*?)\};/.exec(read('panel-cockpit.js') || '');
+  return m ? [...m[1].matchAll(/(\w+):\s*'\.\/view-/g)].map((x) => x[1]) : [];
+};
+
+function suite(label, cases) {
+  const results = [];
+  for (const [name, fn] of cases) {
+    let cond = false; let extra = '';
+    try { const r = fn(); cond = r === true || (r && r.cond === true); extra = r && r.extra ? r.extra : ''; } catch (e) { extra = String((e && e.message) || e); }
+    results.push(cond);
+    console.log(`${cond ? '✓' : '✗'} ${name}${extra ? ' — ' + extra : ''}`);
+  }
+  const bad = results.filter((x) => !x).length;
+  console.log(`\n${results.length - bad}/${results.length} ${label} assertions passed`);
+  process.exit(bad ? 1 : 0);
+}
+
+module.exports = { suite, read, gone, viewKeys, boardKeys, PM };

package/workspace/first-paint-audit.js

@@ -0,0 +1,145 @@
+'use strict';
+/* first-paint-audit.js — the first-paint instrument, shared by every first-paint suite (pm-os-absorb seams).
+ *
+ * Not a suite: first-paint-count.test.js (the Breakdown, Run 1) and each destination's first-paint suite (Initiatives
+ * 2D, Today 3B, Board 4D, Reports 5C) require it, so every surface is counted with ONE instrument: shoot.js's audit(),
+ * the one the PM's numbers came from. A "control" is a visible button, link, input, select, textarea, [role=button] or
+ * [draggable=true] inside the viewport on first paint.
+ *
+ *   EXPECT                      PRD Q5's budgets at 1280×800, counted outside the dock and the terminal
+ *   audit(phone)                shoot.js's audit, verbatim; runs in the page (page.evaluate(audit, false))
+ *   countIn([scope, exclude])   the same selector and visibility test, inside `scope` and outside `exclude`; in the page
+ *   stableCount([scope, exclude, minus])   countIn once the screen is still (two animation frames apart); in the page,
+ *                               after installCounter(page)
+ *   installCounter(page)        the init script stableCount needs (window.__countIn); call it before page.goto
+ *
+ * Do not tune the selector or the visibility test for one surface: change them here, for all, or not at all.
+ */
+
+const EXPECT = Object.freeze({ today: 17, initiatives: 24, board: 33, reports: 14 });
+
+/* ── shoot.js audit(), copied verbatim (scratchpad/specimens2/shoot.js, 2026-10-05) ─────────────────────────────── */
+// runs in the page
+function audit(phone) {
+  const SEL = 'button, a[href], a[role], input:not([type="hidden"]), select, textarea, [role="button"], [draggable="true"]';
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const visible = (el) => {
+    if (el.closest("dialog:not([open])")) return false;
+    const pop = el.closest("[popover]");
+    if (pop && !pop.matches(":popover-open")) return false;
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return false;
+    }
+    return r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw;
+  };
+  const describe = (el) => {
+    const t = (el.getAttribute("aria-label") || el.textContent || el.value || "").trim().replace(/\s+/g, " ");
+    const r = el.getBoundingClientRect();
+    return `${el.tagName.toLowerCase()}${el.className && typeof el.className === "string" ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : ""} "${t.slice(0, 28)}" ${Math.round(r.width)}x${Math.round(r.height)}`;
+  };
+  const all = [...document.querySelectorAll(SEL)].filter(visible);
+  const notBar = all.filter((el) => !el.closest(".specbar"));
+  const small = phone
+    ? notBar.filter((el) => {
+        const r = el.getBoundingClientRect();
+        // inline text links inside prose are exempt from the 44px rule
+        if (el.tagName === "A" && !el.className && getComputedStyle(el).display === "inline") return false;
+        return r.width < 43.5 || r.height < 43.5;
+      })
+    : [];
+  const sw = document.documentElement.scrollWidth;
+  const offenders = [];
+  if (sw > vw) {
+    for (const el of document.querySelectorAll("body *")) {
+      const r = el.getBoundingClientRect();
+      if (r.right > vw + 0.5 && r.width > 0) {
+        let clipped = false;
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+          const o = getComputedStyle(p).overflowX;
+          if (o === "auto" || o === "scroll" || o === "hidden" || o === "clip") {
+            clipped = true;
+            break;
+          }
+        }
+        if (!clipped) offenders.push({ el: describe(el), right: Math.round(r.right) });
+      }
+    }
+    offenders.sort((a, b) => b.right - a.right);
+  }
+  return {
+    title: document.title,
+    controlsInViewport: all.length,
+    controlsExcludingSpecbar: notBar.length,
+    smallTargets: small.length,
+    smallTargetExamples: small.slice(0, 8).map(describe),
+    scrollWidth: sw,
+    innerWidth: vw,
+    horizontalOverflow: sw > vw,
+    overflowOffenders: offenders.slice(0, 6),
+    pageHeight: document.documentElement.scrollHeight
+  };
+}
+
+/**
+ * The same selector and the same visibility test as audit(), counted inside `scope` and outside every `exclude`.
+ * Runs in the page. Returns { n, names }.
+ */
+function countIn([scope, exclude]) {
+  const SEL = 'button, a[href], a[role], input:not([type="hidden"]), select, textarea, [role="button"], [draggable="true"]';
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const visible = (el) => {
+    if (el.closest("dialog:not([open])")) return false;
+    const pop = el.closest("[popover]");
+    if (pop && !pop.matches(":popover-open")) return false;
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return false;
+    }
+    return r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw;
+  };
+  const roots = scope ? [...document.querySelectorAll(scope)] : [document];
+  const seen = new Set();
+  for (const root of roots) for (const el of root.querySelectorAll(SEL)) {
+    if (seen.has(el) || !visible(el)) continue;
+    if (exclude && el.closest(exclude)) continue;
+    seen.add(el);
+  }
+  const names = [...seen].map((el) => `${el.tagName.toLowerCase()} "${(el.getAttribute('aria-label') || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 24)}"`);
+  return { n: seen.size, names };
+}
+
+/**
+ * countIn, but only once the screen is still: the count of `scope` minus `exclude` must be the same two animation
+ * frames apart (up to 60 tries). With `minus`, the controls inside `minus` are counted out in the SAME task, so the two
+ * numbers of a difference come from one paint. Runs in the page; needs window.__countIn (an init script).
+ */
+async function stableCount([scope, exclude, minus]) {
+  const frame = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+  const both = () => {
+    const a = window.__countIn([scope, exclude]);
+    const b = minus ? window.__countIn([scope, exclude ? exclude + ', ' + minus : minus]) : null;
+    return { n: a.n, names: a.names, without: b ? b.n : null };
+  };
+  let prev = both();
+  for (let k = 0; k < 60; k++) {
+    await frame();
+    const cur = both();
+    if (cur.n === prev.n && cur.without === prev.without) return { ...cur, still: true, tries: k + 1 };
+    prev = cur;
+  }
+  return { ...prev, still: false, tries: 60 };
+}
+
+/** Add the init script that stableCount calls. Call it once per page, before the first goto. */
+function installCounter(page) {
+  return page.addInitScript({ content: 'window.__countIn = ' + countIn.toString() + ';' });
+}
+
+module.exports = { EXPECT, audit, countIn, stableCount, installCounter };

package/workspace/fixtures/capture/requirements/capture-2026-10-04-1.md

@@ -0,0 +1,10 @@
+---
+type: Reference
+title: "Capture 2026-10-04 1"
+timestamp: 2026-10-04T08:12:00Z
+source: capture
+by: pm:wawan
+synthetic: true
+---
+
+Partner admins want to export the audit log as CSV before the quarterly review.