create-pmos 0.52.0 → 0.53.1

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-05T21:40:45Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T01:59: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/README.md

@@ -33,6 +33,8 @@ pmos status          # is it running? which sessions?
 pmos stop            # shut it down (scrollback is preserved; sessions respawn next time)
 pmos doctor          # diagnose the environment (node-pty arch, PTY spawn test, ports)
 ```
+**Without a terminal.** `pmos launcher on` (once, from the repository you want) writes a PMOS app — `~/Applications/PMOS.app` on macOS, an app-menu entry on Linux — and a login item that starts the server at login without opening a browser. Both run `pmos up <repo>` with the PATH your terminal had at setup. `pmos launcher status` checks it, `pmos launcher off` removes it. Guide: [`guide/launcher.md`](guide/launcher.md).
+
 **The port is found, not assumed.** A running server records the port it serves, so `pmos` in a second repo joins the workspace you already have open — whatever port it ended up on, and however it was started. If another program holds the default port (7433), `pmos` starts on the next free one and says so; `PMOS_WS_PORT=7500 pmos` pins it by hand. `pmos stop` shuts down every workspace server it finds, which is how you collapse two back into one.
 
 <details><summary>Without the global install (running from the repo)</summary>

package/workspace/REMOTE.md

@@ -1,32 +1,23 @@
 ---
 type: Reference
 title: "Workspace remote access over a private tailnet (Tailscale)"
-timestamp: 2026-07-26
+timestamp: 2026-10-06
 ---
 
 # Reaching the workspace from your phone — over a private tailnet, never the public internet
 
-The workspace server owns **real terminal sessions (PTYs)** running your `claude` on **your own
-subscription**. By default it binds `127.0.0.1` only, so it is reachable solely from the machine it
-runs on. This runbook enables reaching **the same local server** from another of your own devices —
-a phone, a laptop — over a **private Tailscale tailnet**. It never exposes a public endpoint.
+The workspace server owns **real terminal sessions (PTYs)** running your `claude` on **your own subscription**. By default it binds `127.0.0.1` only, so it is reachable solely from the machine it runs on. This runbook enables reaching **the same local server** from another of your own devices — a phone, a laptop — over a **private Tailscale tailnet**. It never exposes a public endpoint.
 
 ## Why a tailnet, and why no public endpoint (D62)
 
-A [Tailscale](https://tailscale.com) tailnet is a private [WireGuard](https://www.wireguard.com/)
-mesh between **your own devices**. Every device is authenticated and encrypted end-to-end; addresses
-live in the CGNAT range `100.64.0.0/10` and are routable **only** between devices on your tailnet —
-never from the public internet.
+A [Tailscale](https://tailscale.com) tailnet is a private [WireGuard](https://www.wireguard.com/) mesh between **your own devices**. Every device is authenticated and encrypted end-to-end; addresses live in the CGNAT range `100.64.0.0/10` and are routable **only** between devices on your tailnet — never from the public internet.
 
 PMOS's locked decision **D62** rejects, permanently:
 
 - **any public endpoint** for the workspace server, and
 - **any hosted PTY bridge** (proxying the terminal through a hosted, browser-reachable surface).
 
-A public server that owns a PTY running your Claude subscription is severe exposure. The tailnet path
-sidesteps that entirely: the phone attaches to the *same local server* across your own private
-network. Accordingly, this feature will **only ever** bind loopback plus your machine's own tailnet
-address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it **refuses to start**.
+A public server that owns a PTY running your Claude subscription is severe exposure. The tailnet path sidesteps that entirely: the phone attaches to the *same local server* across your own private network. Accordingly, this feature will **only ever** bind loopback plus your machine's own tailnet address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it **refuses to start**.
 
 ## Setup
 
@@ -52,16 +43,15 @@ address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it
      loopback requests are token-free; every tailnet request must present the token.
    ```
 
-   **Copy the token now** — it is shown only once and never logged again.
+   Under those lines it prints the phone URL as a **QR code**, and the same URL as text (`http://100.x.y.z:7433/?token=<token>`). The token is shown only at startup and never logged again. A token you supply with `PMOS_TOKEN` is never printed, so that mode prints no QR code.
 
-3. **Open it from your phone.** In the phone's browser (on the same tailnet), open:
+3. **Open it from your phone.** Point the phone camera at the QR code and open the link. Or type the URL into the phone's browser. The server sets a sign-in cookie (7 days) and redirects to `http://100.x.y.z:7433/`, so the token does not stay in the address bar or the history.
 
-   ```
-   http://100.x.y.z:7433/?token=<token>
-   ```
+   If the phone has no valid cookie, it shows a **sign-in page**. Paste the token there. The field is a password field, so the phone's password manager can save it. This is also what you see after the cookie expires, or after a restart that generated a new token.
+
+   The client attaches to the **same live sessions** the desktop sees. Requests from the machine itself (`127.0.0.1`) never need the token.
 
-   The client attaches to the **same live sessions** the desktop sees; the token authorizes both the
-   page and its WebSocket. Requests from the machine itself (`127.0.0.1`) never need the token.
+4. **Optional: put it on the home screen.** In Safari, tap Share › Add to Home Screen. In Chrome on Android, tap ⋮ › Add to Home screen. The PMOS icon then opens the workspace full screen, without the browser bar. On iOS the home-screen app has its own cookies, so it asks for the token once. On Android, Chrome opens a home-screen app full screen only from an HTTPS origin. Over the plain `http://100.x.y.z` address it adds a shortcut that opens in a normal browser tab. There is no offline mode: the workspace shows live state, and it needs the server to be running.
 
 ## Configuration
 
@@ -76,56 +66,27 @@ address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it
 
 ## Security model (what is guaranteed)
 
-- **Never public.** The only addresses the server will ever bind are loopback and a
-  `100.64.0.0/10` tailnet address. `0.0.0.0`, `::`, LAN, and public IPs are refused — the server
-  exits with a clear error rather than binding them. There is no code path to a public bind.
-- **Token beyond loopback.** With remote mode on, every non-loopback HTTP request and WebSocket
-  upgrade must present the bearer token, or it is rejected (`401` / socket closed). Loopback requests
-  stay token-free for local development. The comparison is constant-time.
-- **Origin/Host allowlist (D64).** Both the HTTP guard and the WebSocket-upgrade handshake reject any
-  request whose `Origin` is foreign (not same-origin with the `Host` it arrived on) or whose `Host`
-  hostname is not loopback/localhost or your tailnet address. This closes the cross-origin-localhost /
-  DNS-rebinding vector: without it, **any website open in your browser** could open a WebSocket to
-  `ws://127.0.0.1:<port>` and spawn a shell + type into it, because loopback peers are token-exempt.
-  A same-origin page served by the workspace passes; a cross-site page is rejected `403`. Native
-  clients / `curl` (which send no `Origin`) still pass this check and are then gated by the token.
-- **No header/token logging (D08).** The request-guard path logs nothing about the request. The
-  token is printed at most once at startup (only when generated); a token you supply is never echoed.
-- **Rate-limited control channel (D64).** The WS messages that spawn shells (`new`/`respawn`) and
-  feed a PTY (`input`) are per-connection rate-limited, bounding abuse if the socket is ever reached.
-- **Independent layers.** The tailnet (WireGuard device auth), the bearer token, and the origin/host
-  allowlist all gate access — a device must be *on your tailnet*, *hold the token*, **and** present a
-  same-origin request from an allowed host.
+- **Never public.** The only addresses the server will ever bind are loopback and a `100.64.0.0/10` tailnet address. `0.0.0.0`, `::`, LAN, and public IPs are refused — the server exits with a clear error rather than binding them. There is no code path to a public bind.
+- **Token beyond loopback.** With remote mode on, every non-loopback HTTP request and WebSocket upgrade must present the bearer token, or it is rejected (`401` / socket closed). A browser page load gets the sign-in page with that `401`. The one exception is `POST /auth`, the sign-in form's target: it only compares the posted token and, on a match, sets the session cookie. It still sits behind the Origin/Host allowlist. Loopback requests stay token-free for local development. The comparison is constant-time.
+- **Origin/Host allowlist (D64).** Both the HTTP guard and the WebSocket-upgrade handshake reject any request whose `Origin` is foreign (not same-origin with the `Host` it arrived on) or whose `Host` hostname is not loopback/localhost or your tailnet address. This closes the cross-origin-localhost / DNS-rebinding vector: without it, **any website open in your browser** could open a WebSocket to `ws://127.0.0.1:<port>` and spawn a shell + type into it, because loopback peers are token-exempt. A same-origin page served by the workspace passes; a cross-site page is rejected `403`. Native clients / `curl` (which send no `Origin`) still pass this check and are then gated by the token.
+- **No header/token logging (D08).** The request-guard path logs nothing about the request. The token is printed at most once at startup (only when generated); a token you supply is never echoed.
+- **Rate-limited control channel (D64).** The WS messages that spawn shells (`new`/`respawn`) and feed a PTY (`input`) are per-connection rate-limited, bounding abuse if the socket is ever reached.
+- **Independent layers.** The tailnet (WireGuard device auth), the bearer token, and the origin/host allowlist all gate access — a device must be *on your tailnet*, *hold the token*, **and** present a same-origin request from an allowed host.
 
 ## Exposing to the internet — the required hardening (D64)
 
-The workspace is **tailnet-first**. The tailnet path above is the supported way to reach it from
-another of your own devices and needs no internet exposure. If you nonetheless expose an instance to
-the internet, D64 permits it **only after all three of the following are in place — never before, and
-never as a raw public bind**:
+The workspace is **tailnet-first**. The tailnet path above is the supported way to reach it from another of your own devices and needs no internet exposure. If you nonetheless expose an instance to the internet, D64 permits it **only after all three of the following are in place — never before, and never as a raw public bind**:
 
 1. **The bearer token for every non-loopback peer** (already enforced in remote mode).
 2. **The Origin/Host allowlist** (already enforced — see above).
-3. **TLS termination at the exposure boundary.** **The workspace server does not terminate TLS.** It
-   speaks plain HTTP/WS and must sit behind something that terminates TLS for it — Tailscale's own
-   HTTPS (`tailscale serve` / `tailscale funnel`) or a reverse proxy (Caddy, nginx, a tunnel) that
-   holds the certificate and forwards to the loopback/tailnet listener. Do **not** put the raw HTTP
-   port on a public interface — the server refuses non-loopback/non-tailnet binds precisely so this
-   stays a conscious proxy decision, not an accident.
+3. **TLS termination at the exposure boundary.** **The workspace server does not terminate TLS.** It speaks plain HTTP/WS and must sit behind something that terminates TLS for it — Tailscale's own HTTPS (`tailscale serve` / `tailscale funnel`) or a reverse proxy (Caddy, nginx, a tunnel) that holds the certificate and forwards to the loopback/tailnet listener. Do **not** put the raw HTTP port on a public interface — the server refuses non-loopback/non-tailnet binds precisely so this stays a conscious proxy decision, not an accident.
 
-When a reverse proxy forwards to the workspace, keep the forwarded `Host` set to the loopback/tailnet
-host the server actually binds, so the Origin/Host allowlist still recognises same-origin requests.
+When a reverse proxy forwards to the workspace, keep the forwarded `Host` set to the loopback/tailnet host the server actually binds, so the Origin/Host allowlist still recognises same-origin requests.
 
 ## Troubleshooting
 
-- **"refusing to bind … only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted"**
-  — you passed `PMOS_BIND_ADDR` (or `PMOS_TAILNET_IP`) that isn't loopback or tailnet. Use your real
-  `tailscale ip -4` value.
-- **"no Tailscale tailnet address … was found"** — Tailscale isn't up on this machine. Run
-  `tailscale up`, or set `PMOS_TAILNET_IP`.
-- **"cannot bind 100.x.y.z:PORT — that address is not present on this machine"** — the pinned
-  `PMOS_TAILNET_IP` isn't actually assigned to this machine. Check `tailscale ip -4`.
-- **Phone gets 401** — the token is missing or wrong. Re-open with `?token=<token>` (or send
-  `Authorization: Bearer <token>`). Restarting the server without `PMOS_TOKEN` mints a new token.
-- **Phone can't connect at all** — confirm both devices show each other in the Tailscale app, and
-  that you used the `100.x.y.z` address, not a LAN IP.
+- **"refusing to bind … only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted"** — you passed `PMOS_BIND_ADDR` (or `PMOS_TAILNET_IP`) that isn't loopback or tailnet. Use your real `tailscale ip -4` value.
+- **"no Tailscale tailnet address … was found"** — Tailscale isn't up on this machine. Run `tailscale up`, or set `PMOS_TAILNET_IP`.
+- **"cannot bind 100.x.y.z:PORT — that address is not present on this machine"** — the pinned `PMOS_TAILNET_IP` isn't actually assigned to this machine. Check `tailscale ip -4`.
+- **Phone shows the sign-in page** — the cookie is missing, expired, or from an older token. Paste the token, or scan the QR code again. Restarting the server without `PMOS_TOKEN` mints a new token, so every phone must sign in again. (API clients without a browser still get a JSON `401`.)
+- **Phone can't connect at all** — confirm both devices show each other in the Tailscale app, and that you used the `100.x.y.z` address, not a LAN IP.

package/workspace/bin/pmos.js

@@ -45,7 +45,9 @@ const pidFile = (port) => path.join(STATE, D.pidFileName(port));
 const logFile = (port) => path.join(STATE, `server-${port}.log`);
 const APP_VERSION = (() => { try { return require('../package.json').version || null; } catch { return null; } })();
 const urlOf = (port) => `http://127.0.0.1:${port}`;
-const NO_OPEN = process.env.PMOS_NO_OPEN === '1';      // tests set this
+// Tests set PMOS_NO_OPEN. `--no-open` is the login item's (`pmos launcher on`): a flag, not the env var, so the
+// server it starts does not hand PMOS_NO_OPEN to every session, where a `pmos` typed later would open nothing.
+const NO_OPEN = process.env.PMOS_NO_OPEN === '1' || process.argv.includes('--no-open');
 
 const say = (s) => console.log(s);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -406,6 +408,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,18 +431,20 @@ 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') {
     // `pmos open ../other-repo` — the path is the argument AFTER the verb
-    code = await up(process.argv[3] ? path.resolve(process.argv[3]) : process.cwd());
+    code = await up(process.argv[3] && !process.argv[3].startsWith('-') ? path.resolve(process.argv[3]) : process.cwd());
   } else if (arg && !arg.startsWith('-')) {
     code = await up(path.resolve(arg));                 // `pmos ../other-repo`
   } else {