create-pmos 0.52.0 → 0.53.0

package/workspace/lib/today.js

@@ -0,0 +1,333 @@
+'use strict';
+/* today.js — what needs the PM, ranked as Today shows it (pm-os-absorb Run 3, slice 3B, PRD R12, D86 point 5).
+ *
+ *   todayFor(w, { stateDir, sessions })      → { ok, ws, count, cards, banner, next, stall_days, sig }
+ *   rank(cards)                              → the cards in Today's order
+ *   rowKind(row)                             → the R12 kind (1 to 8) of one needs row, or null for a row that is no card
+ *   gather(w, { stateDir, sessions })        → { rows, banner }   every source's rows, before they are ranked
+ *   nextDraft(root)                          → { cadence, slot, label } | null   what the empty state names
+ *   KINDS · KIND_LABEL
+ *
+ * ONE LIST. Today, GET /api/today and `pmos today` all show this list: the page draws the cards of each source and puts
+ * them in this order (public/pm/today-cards.js rankNodes), and lib/today-cli.js prints it. A card has one of the eight
+ * kinds of R12 and no other:
+ *    1 a gate is owed: an acceptance, a due outcome check, a report to issue     5 an agent breakdown to keep
+ *    2 a session is waiting                                                       6 a triaged capture
+ *    3 a step was returned to you                                                 7 cycle review
+ *    4 work to check: an item in Review, an item with no evidence, a Release      8 needs repair
+ * The order is the kind, then the card id. A card is never a status: nothing here changes a record.
+ *
+ * WHAT IS NOT A CARD. A stalled initiative is a health reason (lib/health.js, `stall_days` from lib/plan-rules.js), so
+ * the proactive engine's `stalled` candidates never reach this list. A source that could not be read is a `banner`
+ * entry, never an empty list and never a card (R10: a broken source does not read as "nothing needs you").
+ *
+ * WHERE THE ROWS COME FROM. The needs rows of a repository are made in server.js deriveNeeds, and a route module does
+ * not get that function (seams §5.1 ctx). So gather() reads the same sources with the same rules and tests/routes-today
+ * compares the two answers row by row. The rows are: lib/plan-items.js needsFor (Keep, no evidence, a line with no
+ * effect), every needs provider (lib/needs-providers.js), an open Acceptance Gate, a due outcome check, the queue file
+ * the harness writes, an acceptance returned and not accepted since, and the live sessions that wait for the PM.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const planItems = require('./plan-items.js');
+const needsProviders = require('./needs-providers.js');
+const fmParse = require('./file-mode-parse.js');
+const planRules = require('./plan-rules.js');
+const issues = require('./issues.js');
+
+const KINDS = Object.freeze([1, 2, 3, 4, 5, 6, 7, 8]);
+const KIND_LABEL = Object.freeze({
+  1: 'gate', 2: 'session', 3: 'returned', 4: 'check', 5: 'keep', 6: 'capture', 7: 'cycle', 8: 'repair',
+});
+// The row kinds this module owns (the source says `today`): kinds 1 to 3 of R12.
+const OWN = Object.freeze({ accept: 1, outcome: 1, question: 2, session: 2, returned: 3 });
+// Run 1's breakdown rows (lib/plan-items.js needsFor).
+const PLAN = Object.freeze({ keep: 5, evidence: 4, 'plan-flag': 8 });
+const STOPPED = ['closed', 'on-hold', 'cancelled'];
+
+const WEEKDAY = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTH = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+/** The R12 kind of a needs row (the `today.kind` a provider set, else the kind of the row), or null when it is no card. */
+function rowKind(row) {
+  if (!row || typeof row !== 'object') return null;
+  if (row.kind === 'provider-error') return null;
+  if (row.run_id === 'plan-items:unreadable') return null;
+  const t = row.today && typeof row.today === 'object' ? row.today : null;
+  if (t && Number.isInteger(t.kind) && t.kind >= 1 && t.kind <= 8) return t.kind;
+  if (Object.prototype.hasOwnProperty.call(OWN, row.kind)) return OWN[row.kind];
+  if (Object.prototype.hasOwnProperty.call(PLAN, row.kind)) return PLAN[row.kind];
+  return 8;   // a row that names no kind needs repair: it is shown, not dropped
+}
+
+/* ── the cards ──────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const CARD_KEYS = ['id', 'run_id', 'ws', 'kind', 'source', 'row_kind', 'initiative_id', 'cause', 'evidence', 'act'];
+
+function make(ws, kind, source, row, p) {
+  return {
+    id: `${ws}|${row.run_id}`, run_id: row.run_id, ws, kind, source, row_kind: row.kind,
+    initiative_id: row.initiative_id || null, cause: clip(p.cause, 200), evidence: clip(p.evidence, 240),
+    act: { label: clip(p.act && p.act.label, 24) || 'Open', ...(p.act && p.act.cli ? { cli: clip(p.act.cli, 200) } : {}) },
+    ...(p.detail ? { detail: p.detail } : {}),
+  };
+}
+
+/** One needs row as a card, or null when it is no card. `row.provider` names the source of a provider's row. */
+function cardOf(ws, row) {
+  const kind = rowKind(row);
+  if (kind === null) return null;
+  const t = row.today && typeof row.today === 'object' ? row.today : {};
+  const source = typeof row.provider === 'string' ? row.provider : (Object.prototype.hasOwnProperty.call(PLAN, row.kind) ? 'plan-items' : 'today');
+  if (typeof row.provider === 'string' || (row.today && typeof row.today === 'object')) {
+    return make(ws, kind, t.source || source, row, {
+      cause: t.cause || row.question || row.kind, evidence: t.evidence || row.doc || '', act: t.act || { label: 'Open' } });
+  }
+  if (row.kind === 'accept') {
+    const d = row.detail || {};
+    return make(ws, 1, 'today', row, {
+      cause: d.verdict ? `Acceptance is owed. The evaluator says ${d.verdict}${d.score != null ? ` (${d.score})` : ''}.` : (row.question || 'Acceptance is owed.'),
+      evidence: row.doc || `run ${row.run_id}`, act: { label: 'Accept' }, detail: d.verdict || d.score != null ? { verdict: d.verdict || null, score: d.score != null ? d.score : null } : undefined });
+  }
+  if (row.kind === 'outcome') return make(ws, 1, 'today', row, { cause: row.question, evidence: row.doc || '', act: { label: 'Check' } });
+  if (row.kind === 'returned') return make(ws, 3, 'today', row, { cause: row.question, evidence: row.doc || '', act: { label: 'Open' } });
+  if (row.kind === 'session') return make(ws, 2, 'today', row, { cause: row.question, evidence: row.doc || '', act: { label: 'Open' } });
+  if (row.kind === 'question') return make(ws, 2, 'today', row, { cause: row.question, evidence: row.doc || 'the needs queue', act: { label: 'Open' } });
+  if (row.kind === 'keep') {
+    const b = row.batch || {};
+    return make(ws, 5, 'plan-items', row, {
+      cause: `${row.question} proposed by ${b.byLabel || b.by || 'an agent'}`, evidence: row.initiative_id || '', act: { label: 'Keep', cli: null } });
+  }
+  if (row.kind === 'evidence') return make(ws, 4, 'plan-items', row, { cause: row.question, evidence: row.initiative_id || '', act: { label: 'Open' } });
+  if (row.kind === 'plan-flag') return make(ws, 8, 'plan-items', row, { cause: row.question, evidence: row.initiative_id || 'plan-items.jsonl', act: { label: 'Open' } });
+  return make(ws, kind, source, row, { cause: row.question || row.kind, evidence: row.doc || '', act: { label: 'Open' } });
+}
+
+/** The cards of every row, ranked: the R12 kind first, then the card id (so two lists of the same rows always agree). */
+function rank(cards) {
+  return (cards || []).slice().sort((a, b) => a.kind - b.kind || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/* ── gathering the rows ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The PMOS checkout this library lives in, as server.js knows it (EMBEDDED_SELF, SELF_ROOT, LEGACY_STATE). Only there is the
+ * checkout's own workspace/state/ the file-mode mirror. `SELF` is a plain object so a suite can point it at a scratch tree.
+ */
+const SELF = (() => {
+  const appDir = path.resolve(__dirname, '..');
+  const root = path.resolve(appDir, '..');
+  const installed = /[\\/]node_modules[\\/]/.test(__dirname);
+  const named = process.env.PMOS_SELF_ROOT ? path.resolve(process.env.PMOS_SELF_ROOT) === root : true;
+  const embedded = !installed && named && (fs.existsSync(path.join(root, 'DECISIONS.md')) || fs.existsSync(path.join(root, 'AGENTS.md')));
+  return { appDir, root, embedded };
+})();
+
+function isDir(d) { try { return fs.statSync(d).isDirectory(); } catch { return false; } }
+
+/** The state directory of a tree, as server.js stateDirFor finds it (the route passes the server's own answer). */
+function stateDirOf(root) {
+  for (const rel of [['pmos', 'state'], ['state'], ['.pmos']]) {
+    const d = path.join(root, ...rel);
+    if (isDir(d)) return d;
+  }
+  // PMOS-self with no pmos/state/: the checkout's own workspace/state/ (server.js returns LEGACY_STATE for the same tree)
+  if (SELF.embedded && path.resolve(root) === SELF.root) return path.join(SELF.appDir, 'state');
+  return null;
+}
+
+/** A tree that carries PMOS records (a PMOS repository), so that a missing state directory is a fault and not an empty list. */
+function carriesPmos(root) {
+  return fs.existsSync(path.join(root, 'DECISIONS.md')) || fs.existsSync(path.join(root, 'AGENTS.md'));
+}
+
+// A ledger lives in the state directory and in the runs directory of the tree: both are read, as server.js readLedger does.
+function readLedger(w, stateDir, name) {
+  const out = [];
+  const files = [];
+  if (stateDir) files.push(path.join(stateDir, name));
+  if (w && w.root) files.push(path.join(w.root, 'planning', 'runs', name));
+  for (const f of files) for (const r of fmParse.readJsonlRows(f)) out.push(r);
+  return out;
+}
+
+// workspaces.json names a tree by this id (server.js wsId); the route asks the server whether a tree is registered by it.
+function wsIdOf(root) { return crypto.createHash('sha1').update(path.resolve(root)).digest('hex').slice(0, 10); }
+
+// The linked worktrees of a repository, from its main tree's own `.git/worktrees/<name>/gitdir` files (no git process).
+function linkedTrees(main) {
+  const dir = path.join(main, '.git', 'worktrees');
+  let names = [];
+  try { names = fs.readdirSync(dir).sort(); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    try { out.push(path.dirname(fs.readFileSync(path.join(dir, n, 'gitdir'), 'utf8').trim())); } catch { /* a stale entry */ }
+  }
+  return out;
+}
+
+/**
+ * The tree that speaks for its repository's ledgers: a second tree does not, or every row would show twice. server.js
+ * isPlanNeedsTree picks it among the REGISTERED trees: the main tree, else the first registered linked worktree.
+ * `registered(root)` says whether the server holds a workspace at that root; a route module cannot list the server's
+ * workspaces (seams §5.1 ctx), so the linked trees come from the repository itself and the first by path stands in for
+ * the first registered (runs/issues/run3-b.md). Without `registered` the tree is read alone, so it speaks.
+ */
+function isLead(root, registered) {
+  if (typeof registered !== 'function') return true;
+  const me = path.resolve(root);
+  let main;
+  try { main = planItems.ledgerRoot(me); } catch { return true; }
+  if (main === me) return true;
+  if (registered(main)) return false;
+  const first = linkedTrees(main).map((t) => path.resolve(t)).filter((t) => registered(t)).sort()[0];
+  return !first || first === me;
+}
+
+function acceptancesOf(w, stateDir) {
+  const acc = new Map();   // initiative_id -> { action, at, run_id }
+  for (const r of readLedger(w, stateDir, 'acceptances.jsonl')) {
+    if (!r || !r.initiative_id) continue;
+    const label = String(r.action || '').toLowerCase();
+    const action = r.accepted === true ? 'accept' : r.accepted === false ? 'return' : label === 'return' ? 'return'
+      : ['accept', 'approve', 'merge', 'publish'].includes(label) ? 'accept' : null;
+    const at = r.at || r.date || null;
+    const prev = acc.get(r.initiative_id);
+    if (prev && prev.at && (!at || at < prev.at)) continue;
+    acc.set(r.initiative_id, { action, at, run_id: r.run_id || null, note: r.note || '' });
+  }
+  return acc;
+}
+
+function stoppedOf(w, stateDir) {
+  const latest = new Map();
+  for (const r of readLedger(w, stateDir, 'lifecycle.jsonl')) {
+    if (!r || typeof r.initiative_id !== 'string') continue;
+    if (r.state !== 'active' && !STOPPED.includes(r.state)) continue;
+    latest.set(r.initiative_id, r.state);
+  }
+  return new Set([...latest].filter(([, s]) => STOPPED.includes(s)).map(([id]) => id));
+}
+
+function queueRows(w, stateDir, banner) {
+  let f = path.join(w.root, '.pmos', 'needs.json');
+  if (!fs.existsSync(f)) f = stateDir ? path.join(stateDir, 'needs.json') : null;
+  if (!f || !fs.existsSync(f)) return [];
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(f, 'utf8')); }
+  catch { banner.push({ source: 'needs queue', error: 'the needs-you queue file is unreadable or not valid JSON' }); return []; }
+  if (!Array.isArray(parsed)) { banner.push({ source: 'needs queue', error: 'the needs-you queue file is not a JSON array' }); return []; }
+  return parsed.filter((n) => n && typeof n === 'object').map((n) => ({
+    run_id: n.run_id || null, kind: n.kind || 'question', initiative_id: n.initiative_id || null, derived: !!n.derived,
+    question: n.question || n.t || '(unstated)', doc: n.doc || null, ...(n.today && typeof n.today === 'object' ? { today: n.today } : {}),
+  })).filter((n) => n.run_id);
+}
+
+/** A 4D `item-no-evidence` row for an item Run 1's `evidence` row already names (R12 kind 4, one fact, one card). */
+function isDuplicateNoEvidence(row, evidenceIds) {
+  if (!row || row.kind !== 'item-no-evidence') return false;
+  const m = /^work-check-needs:no-evidence:(.+)$/.exec(String(row.run_id || ''));
+  return !!m && evidenceIds.has(m[1]);
+}
+
+/**
+ * Every source's rows for workspace `w`, and the sources that could not be read.
+ *   w          { id, root }, a registered workspace
+ *   stateDir   the workspace's state directory (the route passes ctx.stateDirFor(w)); null reads none
+ *   sessions   the live sessions (ctx.sessionList()); a session whose `shown` is "needs" is a waiting session
+ *   registered (root) → boolean   whether the server holds a workspace at that root; decides which tree of a repository leads
+ */
+function gather(w, { stateDir = stateDirOf(w.root), sessions = [], registered } = {}) {
+  const banner = [];
+  const rows = [];
+  const lead = isLead(w.root, registered);
+  if (!stateDir && carriesPmos(w.root)) banner.push({ source: 'state directory', error: 'this repository has PMOS records but no state directory was found, so acceptances and checks were not read' });
+  if (lead) {
+    try { for (const r of planItems.needsFor(w.root)) rows.push({ ...r, ws: w.id }); }
+    catch (e) { banner.push({ source: 'plan-items', error: `the plan-items ledger could not be read: ${clip((e && e.message) || 'error', 160)}` }); }
+  }
+  // Run 1's `evidence:<item>` row and 4D's `work-check-needs:no-evidence:<item>` row say the same thing about the same item:
+  // the item is counted once, by Run 1's row (provider-cards.js drops the same rows on the page)
+  const evidenceOf = new Set(rows.filter((r) => r.kind === 'evidence').map((r) => String(r.run_id).replace(/^evidence:/, '')));
+  for (const r of needsProviders.rowsFor(w, { lead })) {
+    if (r.kind === 'provider-error') banner.push({ source: r.provider || 'a needs source', error: clip(r.question, 240) });
+    else if (isDuplicateNoEvidence(r, evidenceOf)) continue;
+    else rows.push(r);
+  }
+  for (const b of needsProviders.bannersFor(w, { lead })) banner.push({ source: b.source, error: clip(b.error, 240) });
+  const stopped = stoppedOf(w, stateDir);
+  const queue = queueRows(w, stateDir, banner);
+  const seen = new Set(queue.map((n) => n.run_id));
+  for (const n of queue) rows.push(n);
+  if (stateDir) {
+    const settled = new Set();
+    for (const a of readLedger(w, stateDir, 'acceptances.jsonl')) if (a && a.run_id) settled.add(a.run_id);
+    for (const e of readLedger(w, stateDir, 'evals.jsonl')) {
+      if (!e || !e.run_id || settled.has(e.run_id) || seen.has(e.run_id)) continue;
+      rows.push({ run_id: e.run_id, initiative_id: e.initiative_id || null, kind: 'accept', derived: true,
+        question: 'Acceptance Gate open', doc: e.rubric_path || e.rubric || null,
+        detail: { verdict: e.verdict ? String(e.verdict) : null, score: e.score != null ? e.score : null } });
+    }
+    const disposed = new Set();
+    for (const c of readLedger(w, stateDir, 'outcome_checks.jsonl')) if (c && c.initiative_id) disposed.add(c.initiative_id);
+    const today = new Date().toISOString().slice(0, 10);
+    let files = [];
+    try { files = fs.readdirSync(path.join(stateDir, 'initiatives')).filter((f) => f.endsWith('.md')).sort(); } catch { /* none */ }
+    for (const f of files) {
+      const fm = fmParse.leadingFrontmatter(path.join(stateDir, 'initiatives', f));
+      if (!fm.id || !fm.outcome_metric || disposed.has(fm.id) || !fmParse.outcomeDue(fm, today)) continue;
+      const run_id = `outcome:${fm.id}`;
+      if (seen.has(run_id)) continue;
+      rows.push({ run_id, initiative_id: fm.id, kind: 'outcome', derived: true,
+        question: `An outcome check is due: "${fm.outcome_metric}" (horizon ${fm.outcome_horizon || 'none declared'})`, doc: null });
+    }
+    // an initiative stopped by a lifecycle line is not waiting for a returned step, as the proactive engine also holds
+    for (const [id, a] of acceptancesOf(w, stateDir)) {
+      if (a.action !== 'return' || stopped.has(id)) continue;
+      rows.push({ run_id: `returned:${id}`, initiative_id: id, kind: 'returned', derived: true,
+        question: 'You returned this at the Acceptance Gate and it has not been accepted since.', doc: a.note || null });
+    }
+  }
+  for (const s of sessions || []) {
+    if (!s || s.ws !== w.id || s.shown !== 'needs') continue;
+    rows.push({ run_id: `session:${s.id}`, initiative_id: s.initiative || planItems.initiativeOf(s.plan_item) || null, kind: 'session', derived: true,
+      question: 'A session is waiting for you.', doc: [s.name, s.label].filter(Boolean).join(' · ') || null });
+  }
+  return { rows, banner };
+}
+
+/* ── the empty state ────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The next report draft: the last issue of the biweekly plus `report_cycle_days`, or null when nothing was issued yet. */
+function nextDraft(root) {
+  let last = null;
+  try { last = issues.lastIssue(issues.readIssues(root), 'biweekly'); } catch { return null; }
+  if (!last || !/^\d{4}-\d{2}-\d{2}$/.test(String(last.slot))) return null;
+  const days = planRules.readRules(root).report_cycle_days;
+  const [y, m, d] = last.slot.split('-').map(Number);
+  const due = new Date(Date.UTC(y, m - 1, d + days));
+  const slot = due.toISOString().slice(0, 10);
+  return { cadence: 'biweekly', slot, label: `biweekly draft ${WEEKDAY[due.getUTCDay()]} ${due.getUTCDate()} ${MONTH[due.getUTCMonth()]}` };
+}
+
+/* ── the answer ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The ranked list for one workspace: the answer of GET /api/today?ws=, and what `pmos today` prints. */
+function todayFor(w, { stateDir, sessions, registered } = {}) {
+  if (!w || !w.root) return { ok: false, error: 'no workspace resolved for Today' };
+  let g;
+  try { g = gather(w, { stateDir: stateDir === undefined ? stateDirOf(w.root) : stateDir, sessions, registered }); }
+  catch (e) { return { ok: false, error: `Today could not be read: ${clip((e && e.message) || 'error', 160)}` }; }
+  const cards = rank(g.rows.map((r) => cardOf(w.id, r)).filter(Boolean));
+  const next = cards.length ? null : nextDraft(w.root);
+  // what the page shows: each card's id, kind, words and act, and the notice. A change to any of them moves the sig.
+  const sig = crypto.createHash('sha1').update(JSON.stringify([cards.map((c) => [c.id, c.kind, c.cause, c.evidence, c.act.label]), g.banner, next && next.label])).digest('hex').slice(0, 16);
+  return {
+    ok: true, ws: w.id, count: cards.length, cards, banner: g.banner,
+    next, stall_days: planRules.readRules(w.root).stall_days, sig,
+  };
+}
+
+module.exports = { isDuplicateNoEvidence, KINDS, KIND_LABEL, CARD_KEYS, SELF, rowKind, cardOf, rank, gather, stateDirOf, wsIdOf, isLead, nextDraft, todayFor };

package/workspace/lib/triage.js

@@ -0,0 +1,163 @@
+'use strict';
+/* triage.js — what a captured idea would become as an initiative: "Proposed: <title> · <lane> · <anchor>", and
+ * whether it matches an earlier rejection (pm-os-absorb Run 2, PRD R16, R12 kind 6; map-spec X16).
+ *
+ *   captures(root)                 → [{ id, path, title, timestamp, by, text }]   every capture note, oldest first
+ *   triage(root, { since } = {})   → { ok, proposals: [proposal], flags: [{ kind, path, why }] }
+ *   proposal = { capture, path, title, lane, laneLabel, anchor, anchorTitle, rejection: { path, title } | null, by }
+ *
+ * WHERE A CAPTURE IS. ⌘K (Run 3, slice 3C) writes each capture as a note `<state>/requirements/capture-YYYY-MM-DD-<n>.md`
+ * (`<state>` is `planning/` for PMOS-self, `pmos/state/` in a kit repository: the folder that holds the initiatives),
+ * frontmatter `type: Reference`, `title`, `timestamp`, `source: capture`, `by`; the body is the captured text. No new
+ * ledger (X16).
+ *
+ * WHICH CAPTURES ARE PROPOSED. A note is triaged until an initiative is created from it: the initiative writer's
+ * `created` line in placements.jsonl names it in `from` (lib/placements.js createdFrom). A Dismiss is the needs queue's
+ * own dismissal of the row (its run_id), so triage keeps no state of its own. `since` (an ISO time) narrows the run to
+ * the notes newer than a caller's last run, compared with the note's `timestamp`.
+ *
+ * WHAT IS PROPOSED, and how — deterministic, no model call. The title is the first sentence of the text (at most 60
+ * characters). The lane is the profile's first work lane that builds something new (`feature`, or `new-feature` in a
+ * document repository). The anchor is the KR or health budget whose name shares the most words with the text (at least
+ * two), or none: the Add then asks for one, because the writer refuses an initiative with no anchor. This is a first
+ * guess for the PM to correct, not a judgement; the pmos-router skill is the judgement.
+ *
+ * THE EARLIER-REJECTION CHECK (the router's prior-rejection step, R12 kind 6). Each file under `planning/out-of-scope/`
+ * (except README.md) is read for its title. A capture matches when it holds at least two of the title's words and at
+ * least half of them (words of 3 or more letters that are not common words). A match names the file; it does not
+ * stop the Add: the concept returns only if the PM overrides the recorded reasoning.
+ */
+const fs = require('fs');
+const path = require('path');
+const consoleState = require('./console-state');
+const placements = require('./placements.js');
+const rowsLib = require('./initiative-rows.js');
+
+const NOTE_RE = /^capture-(\d{4}-\d{2}-\d{2})-([1-9]\d{0,3})\.md$/;
+const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'want', 'wants', 'before', 'after', 'into', 'each',
+  'what', 'when', 'have', 'has', 'are', 'was', 'were', 'not', 'but', 'our', 'your', 'their', 'they', 'them', 'can', 'should',
+  'would', 'could', 'will', 'all', 'any', 'out', 'one', 'two', 'its', 'than', 'then', 'there', 'here', 'also', 'via', 'per']);
+
+function engine() {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded.engine;
+}
+const words = (s) => [...new Set(String(s || '').toLowerCase().replace(/[`*_#>[\]()]/g, ' ').split(/[^a-z0-9]+/).filter((w) => w.length >= 3 && !STOP.has(w)))];
+
+/** The folder that holds the initiatives' folder: `planning/` or `pmos/state/`. */
+function stateDir(root) { return path.dirname(engine().layout(root).initiatives); }
+
+function readNote(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  const fm = engine().parseLeadingFrontmatter(text) || {};
+  const m = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(text);
+  return { fm, body: (m ? text.slice(m[0].length) : text).trim() };
+}
+
+function captures(root) {
+  const dir = path.join(stateDir(root), 'requirements');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => NOTE_RE.test(n)); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    const file = path.join(dir, n);
+    let note;
+    try { if (!fs.lstatSync(file).isFile()) continue; note = readNote(file); } catch { continue; }
+    if (String(note.fm.source || '').trim() !== 'capture') continue;
+    out.push({ id: n.replace(/\.md$/, ''), path: path.relative(root, file).split(path.sep).join('/'), title: String(note.fm.title || '').trim(),
+      timestamp: String(note.fm.timestamp || '').trim(), by: String(note.fm.by || '').trim() || null, text: note.body });
+  }
+  const key = (c) => { const m = NOTE_RE.exec(c.id + '.md'); return `${m[1]}-${m[2].padStart(4, '0')}`; };
+  return out.sort((a, b) => (key(a) < key(b) ? -1 : 1));
+}
+
+function rejections(root) {
+  const dir = path.join(root, 'planning', 'out-of-scope');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'README.md' && n !== 'index.md').sort(); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    try {
+      const { fm, body } = readNote(path.join(dir, n));
+      const heading = /^#\s+(.+)$/m.exec(body);
+      const title = String(fm.title || (heading && heading[1]) || n.replace(/\.md$/, '').replace(/-/g, ' ')).trim();
+      out.push({ path: `planning/out-of-scope/${n}`, title, words: words(title) });
+    } catch { /* an unreadable file is skipped */ }
+  }
+  return out;
+}
+
+function firstSentence(text) {
+  const one = String(text || '').replace(/\s+/g, ' ').trim();
+  const m = /^(.+?[.!?])(\s|$)/.exec(one);
+  let s = (m ? m[1] : one).replace(/[.!?]+$/, '').trim();
+  if (s.length > 60) s = s.slice(0, 60).replace(/\s+\S*$/, '').trim();
+  return s ? s[0].toUpperCase() + s.slice(1) : '';
+}
+
+/** The anchor whose name shares the most words with the text (two at least), from the OKR files and the budgets. */
+function guessAnchor(root, text) {
+  const want = new Set(words(text));
+  const cands = [];
+  try {
+    const loaded = consoleState.loadEngine();
+    const A = require(path.join(path.dirname(loaded.from), 'anchor-resolve.js'));
+    const index = A.parseOkrIndex(root);
+    if (index.ok) for (const o of index.objectives) for (const k of o.krs) cands.push({ token: k.token, title: k.name || k.token, words: words(k.name) });
+    const L = loaded.engine.layout(root);
+    const budgets = fs.readFileSync(L.budgets, 'utf8');
+    for (const line of budgets.split('\n')) {
+      const m = /^\|\s*`?(health:[a-z0-9-]+)`?\s*\|\s*([^|]*)\|/.exec(line);
+      if (m) cands.push({ token: m[1], title: m[1], words: words(m[1].slice(7) + ' ' + m[2]) });
+    }
+  } catch { /* no resolver or no budgets: no guess */ }
+  let best = null;
+  for (const c of cands) {
+    const score = c.words.filter((w) => want.has(w)).length;
+    if (score >= 2 && (!best || score > best.score)) best = { ...c, score };
+  }
+  return best;
+}
+
+function triage(root, { since } = {}) {
+  const flags = [];
+  let all;
+  try { all = captures(root); } catch (e) { return { ok: false, proposals: [], flags: [{ kind: 'unreadable', path: null, why: String((e && e.message) || e).slice(0, 160) }] }; }
+  let done = {};
+  try { done = placements.createdFrom(root); } catch { done = {}; }
+  const sinceMs = since ? Date.parse(since) : NaN;
+  let groups = {};
+  try { groups = rowsLib.workGroupOf(root); } catch { groups = {}; }
+  const lane = ['feature', 'new-feature'].find((l) => groups[l] === 'work') || Object.keys(groups).find((l) => groups[l] === 'work') || 'feature';
+  const rej = rejections(root);
+  const proposals = [];
+  for (const c of all) {
+    if (done[c.id]) continue;
+    if (Number.isFinite(sinceMs) && !(Date.parse(c.timestamp) > sinceMs)) continue;
+    if (!c.text) { flags.push({ kind: 'empty', path: c.path, why: `${c.path} holds no text` }); continue; }
+    const title = firstSentence(c.text) || c.title;
+    const anchor = guessAnchor(root, c.text);
+    const have = new Set(words(c.text));
+    const hit = rej.find((r) => { const shared = r.words.filter((w) => have.has(w)).length; return shared >= 2 && shared * 2 >= r.words.length; });
+    proposals.push({ capture: c.id, path: c.path, title, lane, laneLabel: lane.replace(/-/g, ' '), anchor: anchor ? anchor.token : null,
+      anchorTitle: anchor ? anchor.title : null, rejection: hit ? { path: hit.path, title: hit.title } : null, by: c.by });
+  }
+  return { ok: true, proposals, flags };
+}
+
+/** The proposal of one capture, whatever its state (`pmos initiative new --from`). `done: true` only when an
+ *  initiative was created from it; `empty: true` when the note holds no text (triage flags it and proposes nothing). */
+function proposalFor(root, captureId) {
+  const p = triage(root).proposals.find((x) => x.capture === captureId);
+  if (p) return p;
+  const c = captures(root).find((x) => x.id === captureId);
+  if (!c) return null;
+  let made = {};
+  try { made = placements.createdFrom(root); } catch { made = {}; }
+  const base = { capture: c.id, path: c.path, title: firstSentence(c.text) || c.title, lane: null, anchor: null, rejection: null };
+  if (made[c.id]) return { ...base, done: true, initiative: made[c.id] };
+  return { ...base, empty: !c.text };
+}
+
+module.exports = { captures, triage, proposalFor, rejections, words, firstSentence, stateDir, NOTE_RE };

package/workspace/lib/verify-work-cli.js

@@ -0,0 +1,81 @@
+'use strict';
+/* verify-work-cli.js — `pmos verify-work`: mark work items integrated from the default branch (pm-os-absorb Run 4,
+ * PRD R7 and R24, map-spec X26, D70). Guide page: guide/integrated-work.md.
+ *
+ *   pmos verify-work [--branch <ref>] [--dry-run] [--json] [--root <dir>]
+ *
+ * The verb runs the repository's OWN scripts/verify-work.js in a child process, in that repository. The factory
+ * ledger (planning/work-items.jsonl) has one writer, scripts/work-item.js, and that writer appends only to the ledger
+ * of the repository it sits in. So the copy that runs must be the repository's: a copy shipped with the workspace
+ * would write nowhere. A repository with no factory writer is told so, and nothing runs.
+ *
+ * Local refs only: the script runs `git rev-parse`, `git log` and `git merge-base`, never `git fetch` (D70). A
+ * `--branch` ref must be on the default branch, or the script refuses it. Pull first (Sync) to see newer commits.
+ * Not a PM-only act: `integrated` is a factory event, and the writer decides what may be appended.
+ * Exit codes: 0 done, 1 refused (or no writer), 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+
+const COMMANDS = { 'verify-work': [] };
+const USAGE = [
+  'usage: pmos verify-work [--branch <ref>] [--dry-run] [--json] [--root <dir>]',
+  'Marks a work item integrated when a commit on the default branch has the trailer "Work-Item: <id>".',
+  'It reads local refs only and never fetches. Pull first to see newer commits.',
+  'Run it again at any time: an item that is already integrated is not written twice.',
+];
+const BOOL = new Set(['json', 'dry-run', 'help']);
+const VALUE = new Set(['branch', 'root']);
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+
+function parse(args) {
+  const flags = {}; const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '-h') { flags.help = true; continue; }
+    if (!a.startsWith('--')) { pos.push(a); continue; }
+    const k = a.slice(2);
+    if (BOOL.has(k)) { flags[k] = true; continue; }
+    if (VALUE.has(k)) {
+      const v = args[i + 1];
+      if (v === undefined || v.startsWith('--')) return { error: `--${k} needs a value` };
+      flags[k] = v; i++; continue;
+    }
+    return { error: `unknown option --${k}` };
+  }
+  return { flags, pos };
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd() } = {}) {
+  const args = argv[0] === 'verify-work' ? argv.slice(1) : argv.slice();
+  if (args[0] === 'help') { for (const l of USAGE) say(l); return 0; }
+  const p = parse(args);
+  if (p.error) { say(`✗ ${p.error}`); for (const l of USAGE) say(l); return 2; }
+  if (p.flags.help) { for (const l of USAGE) say(l); return 0; }
+  if (p.pos.length) { say(`✗ pmos verify-work takes no argument "${p.pos[0]}"`); for (const l of USAGE) say(l); return 2; }
+
+  // The main working tree: its ledger is the one the views read, also when this runs in a linked worktree.
+  const root = require('./plan-tree.js').mainTree(p.flags.root ? path.resolve(cwd, p.flags.root) : repoRoot(cwd));
+  const script = path.join(root, 'scripts', 'verify-work.js');
+  if (!fs.existsSync(script)) {
+    const why = `${root} has no factory writer (scripts/verify-work.js), so there is no work item to mark`;
+    say(p.flags.json ? JSON.stringify({ ok: false, error: why }) : `✗ ${why}.`);
+    return 1;
+  }
+  const pass = [];
+  if (p.flags.branch) pass.push('--branch', p.flags.branch);
+  if (p.flags['dry-run']) pass.push('--dry-run');
+  if (p.flags.json) pass.push('--json');
+  const r = spawnSync(process.execPath, [script, ...pass], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  for (const line of String(r.stdout || '').split('\n')) if (line) say(line);
+  if (r.status === null) { say(`✗ scripts/verify-work.js stopped: ${(r.error && r.error.message) || r.signal}`); return 1; }
+  if (r.status !== 0 && r.stderr && r.stderr.trim()) say(r.stderr.trim().split('\n').slice(-3).join('\n'));
+  return r.status === 0 ? 0 : r.status === 2 ? 2 : 1;
+}
+
+module.exports = { run, COMMANDS, USAGE };