create-pmos 0.52.0 → 0.53.1

package/workspace/lib/pm-guard.js

@@ -0,0 +1,174 @@
+'use strict';
+/* pm-guard.js — THE GUARDED WRITER'S FRONT DOOR: every act only the PM may take passes here first (pm-os-absorb, PRD
+ * R25, D86 point 2).
+ *
+ *   requirePmPress(req, body, { act })               → { ok: true, actor } | { ok: false, status, error }
+ *   requirePmCli({ act, expect, isTTY, env, ask })   → Promise of the same shape
+ *   askAtTerminal(prompt, { input, output })         → Promise<string>, one line typed at the terminal
+ *   requirePagePress(req, body)                      → { ok: true, actor } | { ok: false, status, error }   (any other page write)
+ *   requirePmUpgrade(req, { act })                   → the same, for a WebSocket upgrade (the nonce in the query)
+ *   setLaunchNonce(v) · launchNonce()                → the per-launch nonce; server.js sets it once at start (2A)
+ *   NONCE_HEADER = 'x-pmos-nonce' · NONCE_META = 'pmos-nonce'
+ *   PM_ONLY_ACTS · WRITER_FIELDS
+ *
+ * THE NONCE WIRE CONTRACT (frozen in the base; 2A fills the mint, never the names):
+ *   - server.js calls setLaunchNonce(<random>) once at start and replaces the base placeholder
+ *     `<meta name="pmos-nonce" content="">` in public/index.html with the value when it serves `/`.
+ *   - public/pm/http.js pmHeaders() reads that meta once and sends it as the `x-pmos-nonce` header on every request.
+ *   - Check order in BOTH press functions: act → body shape → writer fields → Origin → nonce. So a 500 (unknown act)
+ *     and a 400 (writer field) never depend on the nonce.
+ *   - While launchNonce() is '' (the base, before 2A), the nonce step is skipped. Once it is set, a missing or wrong
+ *     `x-pmos-nonce` header is 403.
+ *   - Tests reach it through test-run.js: T.nonce(BASE) reads the meta from GET / ('' before 2A), and
+ *     T.pressHeaders(BASE) → { 'Content-Type', Origin: BASE, 'x-pmos-nonce' }. Every route test sends T.pressHeaders.
+ *
+ * A route that writes a PM-only line calls requirePmPress before its writer and passes the returned `actor` on; a CLI
+ * verb calls requirePmCli. The writer itself never decides that a caller is the PM. `act` must be one of PM_ONLY_ACTS,
+ * so a call site names what it guards and the list below stays the whole R25 surface.
+ *
+ * FILLED BY RUN 2 (slice 2A). The page side refuses, in this order:
+ *   - an unknown act: 500 (a programming error; an unguarded default is the defect this file exists to prevent);
+ *   - a body that is not an object, or that carries a writer field: 400;
+ *   - no Origin header, an Origin that is not http(s), or an Origin that is not this request's own Host (another site,
+ *     another port, so another launch): 403. A socket request with no Host header is refused too, because there is
+ *     nothing to match. Only a caller with no socket and no Host (a unit test's plain object) skips the Host match;
+ *   - once server.js has called setLaunchNonce, a missing or wrong x-pmos-nonce header: 403.
+ * The terminal side refuses an agent session (403, without asking), no interactive terminal (403), and a typed text
+ * that does not match `expect` (403). With no `ask` function there is no way to confirm, so the act is refused (X12).
+ *
+ * RESIDUAL (named, not closed). A process that runs as the PM's own user can read the nonce from GET / and send it with
+ * an Origin that matches. A process that fakes a terminal (`script`) and types the expected id is the PM to this file.
+ * The guard closes the paths an agent's tools take by default; CI detection (run2-b) is the backstop for the rest.
+ */
+const readline = require('readline');
+const actor = require('./actor.js');
+
+/** Every act only the PM may take. One word each; the R25 list plus D86 point 2. */
+const PM_ONLY_ACTS = Object.freeze([
+  'accept',     // the Acceptance Gate, the review approve and return, a document approval (/api/gate)
+  'lifecycle',  // hold, close, cancel, reopen (/api/lifecycle)
+  'keep',       // Keep on an agent batch (/api/plan-items kept)
+  'now',        // Move to Now (placements)
+  'adopt',      // adopt an agent's placement proposal
+  'anchor',     // change parent_kr (the record, /api/doc/save, /api/align/apply, /api/ingest/confirm)
+  'bind',       // bind a session to an initiative (/api/session/initiative)
+  'issue',      // Issue a report (issues.jsonl)
+  'release',    // the D65 Release of a factory batch (one grant per batch)
+]);
+/** What each act is, as the refusal says it: "only the PM can <phrase>". */
+const ACT_PHRASE = Object.freeze({
+  accept: 'accept or return work',
+  lifecycle: 'hold, close, cancel or reopen an initiative',
+  keep: 'keep an agent\'s items',
+  now: 'move an item to Now',
+  adopt: 'adopt a proposal',
+  anchor: 'change an anchor',
+  bind: 'bind a session to an initiative',
+  issue: 'issue a report',
+  release: 'release a batch',
+});
+/** Fields only a writer sets. A body that carries one is refused, even with the value the writer would choose. */
+const WRITER_FIELDS = Object.freeze(['v', 'eid', 'by', 'via', 'at', 'override', 'pm', 'actor', 'nonce', 'grant']);
+
+const NONCE_HEADER = 'x-pmos-nonce';
+const NONCE_META = 'pmos-nonce';
+let NONCE = '';
+/** server.js calls this once at start (2A). The value never goes into a PTY environment or a log (D08). */
+function setLaunchNonce(v) { NONCE = typeof v === 'string' ? v : ''; }
+function launchNonce() { return NONCE; }
+
+const refuse = (status, error) => ({ ok: false, status, error });
+const knownAct = (act) => typeof act === 'string' && PM_ONLY_ACTS.includes(act);
+
+function requirePmPress(req, body, { act } = {}) {
+  if (!knownAct(act)) return refuse(500, `pm-guard: ${JSON.stringify(act)} is not a PM-only act`);
+  const bad = bodyChecks(body);
+  if (bad) return bad;
+  return pageChecks(req, `only the PM can ${ACT_PHRASE[act]}, from the page`);
+}
+
+/** Body shape and writer fields; shared by both press functions. Null when the body passes. */
+function bodyChecks(body) {
+  const b = body == null ? {} : body;
+  if (typeof b !== 'object' || Array.isArray(b)) return refuse(400, 'the body must be a JSON object');
+  const sent = WRITER_FIELDS.find((k) => Object.prototype.hasOwnProperty.call(b, k));
+  if (sent) return refuse(400, `field ${sent} is set by the writer`);
+  return null;
+}
+
+/**
+ * Origin, then the nonce. ONE function for both press functions, so a page write and a PM-only press can never differ in
+ * what they accept. The Origin must name this request's own Host: the page this launch served sends exactly that.
+ */
+function pageChecks(req, who) {
+  const h = (req && req.headers) || {};
+  if (!h.origin) return refuse(403, `${who}; this request has no Origin header`);
+  if (!sameLaunchOrigin(h.origin, h.host, !!(req && req.socket))) return refuse(403, `${who}; this request comes from another origin`);
+  // A wrong value is almost always a page from an earlier start of the workspace; a missing one is not the page at all.
+  if (NONCE && !h[NONCE_HEADER]) return refuse(403, `${who}; this request does not come from the workspace page`);
+  if (NONCE && h[NONCE_HEADER] !== NONCE) return refuse(403, `${who}; the workspace restarted, so reload the page, then try again`);
+  return { ok: true, actor: actor.fromUi() };
+}
+
+/** True when `origin` is an http(s) origin and names `host` (the request's Host header). See the header for no Host. */
+function sameLaunchOrigin(origin, host, fromSocket) {
+  let u;
+  try { u = new URL(String(origin)); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  if (u.origin !== String(origin).replace(/\/$/, '')) return false;   // an origin has no path, query or user part
+  if (typeof host !== 'string' || !host) return !fromSocket;
+  return u.host === host.trim().toLowerCase();
+}
+
+/**
+ * Every page write that is NOT a PM-only act (capture, Next/Later placements, a new initiative, a measurement, a report
+ * note or draft): the same body, Origin and nonce checks, no act. Route modules call this and never hand-roll the checks.
+ */
+function requirePagePress(req, body) {
+  const bad = bodyChecks(body);
+  if (bad) return bad;
+  return pageChecks(req, 'this write comes from the page only');
+}
+
+/**
+ * The WebSocket form of requirePmPress. A browser WebSocket cannot set a header, so the page sends the nonce as the
+ * `pmos-nonce` query parameter of the upgrade URL. The Origin and nonce rules are pageChecks' own, so a socket and a
+ * press can never differ in what they accept. server.js calls it once per upgrade and keeps the answer on the socket.
+ */
+function requirePmUpgrade(req, { act } = {}) {
+  if (!knownAct(act)) return refuse(500, `pm-guard: ${JSON.stringify(act)} is not a PM-only act`);
+  const h = (req && req.headers) || {};
+  let q = '';
+  try { q = new URL(String((req && req.url) || '/'), 'http://upgrade.invalid').searchParams.get(NONCE_META) || ''; } catch { q = ''; }
+  return pageChecks({ headers: { ...h, [NONCE_HEADER]: q }, socket: req && req.socket }, `only the PM can ${ACT_PHRASE[act]}, from the page`);
+}
+
+async function requirePmCli({ act, expect, isTTY, env, ask } = {}) {
+  if (!knownAct(act)) return refuse(500, `pm-guard: ${JSON.stringify(act)} is not a PM-only act`);
+  if (typeof expect !== 'string' || !expect.trim()) return refuse(500, 'pm-guard: a PM-only verb needs the text the PM must type');
+  const who = actor.fromCli({ isTTY, env });
+  if (actor.isAgent(who) && who.by !== 'agent:unknown') return refuse(403, `an agent session cannot ${ACT_PHRASE[act]}; ask the PM to do it`);
+  if (!actor.isPm(who)) return refuse(403, `only the PM can ${ACT_PHRASE[act]}, at an interactive terminal`);
+  if (typeof ask !== 'function') return refuse(403, `to ${ACT_PHRASE[act]}, type a confirmation at the terminal`);
+  let typed;
+  try { typed = await ask(`Type ${expect} to ${ACT_PHRASE[act]}: `); } catch { typed = null; }
+  if (typeof typed !== 'string' || typed.trim() !== expect.trim()) return refuse(403, `the typed text did not match ${expect}; nothing was written`);
+  return { ok: true, actor: who };
+}
+
+/** One line from the terminal. The prompt goes to stderr, so `--json` output on stdout stays parseable. */
+function askAtTerminal(prompt, { input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output, terminal: false });
+    let done = false;
+    const finish = (v) => { if (done) return; done = true; rl.close(); resolve(v); };
+    rl.once('line', (line) => finish(String(line)));
+    rl.once('close', () => finish(null));
+    output.write(prompt);
+  });
+}
+
+module.exports = {
+  PM_ONLY_ACTS, WRITER_FIELDS, NONCE_HEADER, NONCE_META,
+  requirePmPress, requirePagePress, requirePmUpgrade, requirePmCli, askAtTerminal, setLaunchNonce, launchNonce,
+};

package/workspace/lib/pm-lines-needs.js

@@ -0,0 +1,331 @@
+'use strict';
+/* pm-lines-needs.js — a PM-only line that is not attested: the one rule, and its needs-repair rows on Today
+ * (pm-os-absorb Run 2, slice 2B; PRD R25(4), R12 kind 8; D86 point 2 item 6; map-spec X10).
+ *
+ *   scan(root, { runsDir, rules, rulesFile, now, arrival })
+ *     → { cutover, cutoverCommit, flags: [flag…], older: [{ ledger, rel, count }], shallow }
+ *   rowsFor(w, { lead })                         → [{ run_id, kind: 'pm-line', initiative_id, question, doc, today }]
+ *   sig(w)                                       → string
+ *   kinds = ['pm-line']                          SOURCES · AGENT_COMMIT · isAgentCommit(message, email)
+ *
+ * A flag is { kind, ledger, rel, n, initiative, cause, message }. The kinds:
+ *   no-via        a PM-only line at or after `via_required_from` (planning/plan-rules.json) that has no `via`;
+ *   unknown-grant a PM-only line that cites a grant (`grant`, or `via: 'grant'`) that grants.jsonl does not hold;
+ *   grant-mismatch a PM-only line that cites a grant that does not cover it: a lifecycle line needs a lifecycle-bulk
+ *                 grant whose target names its state and its initiative, and every line's `at` falls inside the grant's
+ *                 window (at to expires_at). A copied id of a merge grant, or of another batch, is flagged;
+ *   not-pm        a PM-only line in a D86 ledger whose `by` is not the PM's;
+ *   agent-commit  a PM-only line that arrived in an agent-authored commit (a Co-Authored-By trailer that names an agent,
+ *                 a session trailer, or an agent's address). This catches a line written by a script and then committed
+ *                 (bypass e) and a patch applied with `git apply` (bypass f).
+ *   agent-basis   an agent's acceptance (D87) that the Review Gate does not back: no eval row for its run, a verdict that
+ *                 is not PASS or PASS-WITH-FINDINGS, a score under the row's pass_threshold, a `basis` that does not match
+ *                 the latest row, a pm_label, no via, or an action other than accept.
+ * A line older than `via_required_from` is "older": it is counted once per ledger in `older` and never flagged. A line
+ * counts as older only when BOTH its own time is older AND the commit that added it does NOT DESCEND from the cut-over
+ * commit: the first commit whose rules file sets `via_required_from` (git history, not dates). A commit on a parallel
+ * branch that was merged in after the cut-over does not descend from it, so a merge alone does not make its lines new. A line's `at` and a
+ * commit's dates are the writer's to choose (GIT_COMMITTER_DATE), so neither alone makes a line older; a commit that is
+ * that descends from the cut-over commit is checked in full, whatever its dates say. A line's time is its `at` or
+ * `date`, or the `accepted_at`, `recorded_at` or `created_at` of a line written before Run 2; a line with none is older
+ * only when its commit is (an uncommitted line with no time is checked). While no commit sets the rules
+ * file (the value is set but not committed yet), every committed line comes before the cut-over. While
+ * `via_required_from` is null (before Run 2 merges), every line is older, and the arrival check does not run.
+ *
+ * SHALLOW HISTORY. In a shallow clone, `git blame` gives every line older than the clone's edge to the edge commit, so
+ * the arrival check cannot see who added it. `shallow` is true when `git rev-parse --is-shallow-repository` says so;
+ * scripts/check-pm-lines.js then FAILS (the gate needs fetch-depth: 0) while via_required_from is set. A root commit
+ * of a full clone is not an edge: blame runs with --root.
+ *
+ * WHICH LINES ARE PM-ONLY. Each D86 ledger's writer answers through its own `pmOnly(rec)`; this file never reads a
+ * ledger schema. Keep (`kept` in plan-items.jsonl) is PM-only; plan-items.js keeps its own rule for it, so a kept line is
+ * checked here for its arrival only, and scripts/check-plan-items.js fails a kept line that is not from the page or not
+ * by the PM. Every line of acceptances.jsonl (acceptance, review approve and return, document approval) and of
+ * lifecycle.jsonl is PM-only (R25), except an agent's acceptance of a run (D87): a line whose `by` is `agent:<session>`
+ * and which carries a `basis`. That line is not the PM's, so its arrival is not checked; the Review Gate row it names is
+ * (agentBasis below). An agent line WITHOUT a basis stays PM-only and is flagged as before.
+ *
+ * TWO CALLERS: the needs queue (lib/needs-providers.js, so Today shows a kind-8 card for each flag) and the CI checker
+ * scripts/check-pm-lines.js, which passes the runs directory of the tree it checks. Each reads the same rule here.
+ * The arrival check runs `git blame` and `git log` in the repository of the runs directory: local reads, no network.
+ *
+ * HONEST LIMIT. This is detection after the fact. A same-user process can still write a line with `via` and `by` set as
+ * the PM's and commit it without an agent trailer; nothing here can tell that line from a real one (R25 residual). An
+ * uncommitted line is checked for `via`, its grant and its `by`, and for its arrival only once it is committed.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const ledgers = require('./plan-ledgers.js');
+const planTree = require('./plan-tree.js');
+const planRules = require('./plan-rules.js');
+const placements = require('./placements.js');
+const measurements = require('./measurements.js');
+const issues = require('./issues.js');
+
+const KIND = 'pm-line';
+const QUESTION = 'A PM-only line is not attested';
+
+const what = {
+  'plan-items': () => 'A Keep line',
+  placements: (r) => `A placed line into ${r.horizon === 'now' ? 'Now' : String(r.horizon || 'a horizon')}`,
+  measurements: () => 'A measured line',
+  issues: () => 'An issued line',
+  acceptances: () => 'An acceptance line',
+  lifecycle: () => 'A lifecycle line',
+};
+/** The ledgers that hold PM-only lines, and the rule each one answers. */
+const SOURCES = Object.freeze([
+  { ledger: 'plan-items', file: ledgers.LEDGERS['plan-items'].file, pmOnly: (r) => r.ev === 'kept', viaChecked: false },
+  { ledger: 'placements', file: ledgers.LEDGERS.placements.file, pmOnly: placements.pmOnly, viaChecked: true },
+  { ledger: 'measurements', file: ledgers.LEDGERS.measurements.file, pmOnly: measurements.pmOnly, viaChecked: true },
+  { ledger: 'issues', file: ledgers.LEDGERS.issues.file, pmOnly: issues.pmOnly, viaChecked: true },
+  { ledger: 'acceptances', file: 'acceptances.jsonl', pmOnly: (r) => !isAgentAcceptance(r), viaChecked: true },
+  { ledger: 'lifecycle', file: 'lifecycle.jsonl', pmOnly: () => true, viaChecked: true },
+]);
+const D86 = new Set(['placements', 'measurements', 'issues']);
+
+// ── D87: an agent's acceptance of a run ─────────────────────────────────────────────────────────────────────────────
+/** An agent's acceptance (D87): written by an agent session, and naming the Review Gate result it rests on. */
+const isAgentAcceptance = (r) => !!r && typeof r.by === 'string' && r.by.startsWith('agent:') && !!r.basis && typeof r.basis === 'object';
+const PASSING = new Set(['PASS', 'PASS-WITH-FINDINGS']);
+/** Why the agent acceptance `rec` is not backed by `evalRows` (evals.jsonl, oldest first), or null when it is. */
+function agentBasisProblem(rec, evalRows) {
+  if (rec.accepted !== true || (rec.action !== undefined && rec.action !== 'accept')) return 'an agent may only accept; a return or a refusal is the PM\'s';
+  if (rec.pm_label !== undefined && rec.pm_label !== null) return 'an agent acceptance carries no pm_label: only the PM labels the evaluator (D40)';
+  if (typeof rec.via !== 'string' || !rec.via.trim()) return 'it has no via';
+  const rows = evalRows.filter((e) => e.run_id === rec.run_id);
+  if (!rows.length) return `evals.jsonl has no Review Gate row for run ${JSON.stringify(rec.run_id)}`;
+  const e = rows[rows.length - 1];   // the latest verdict for the run is the one that counts
+  if (!PASSING.has(e.verdict)) return `the latest Review Gate verdict for the run is ${JSON.stringify(e.verdict)}`;
+  if (typeof e.score !== 'number' || typeof e.pass_threshold !== 'number') return 'the latest Review Gate row names no score or pass_threshold';
+  if (e.score < e.pass_threshold) return `the latest Review Gate score ${e.score} is under its pass_threshold ${e.pass_threshold}`;
+  const b = rec.basis;
+  if (b.verdict !== e.verdict || b.score !== e.score || b.pass_threshold !== e.pass_threshold) return 'its basis does not match the latest Review Gate row for the run';
+  return null;
+}
+
+// An agent-authored commit: a trailer that names an agent, or an agent's address. One list, used by CI and by Today.
+const AGENT_COMMIT = /^(?:co-authored-by:[^\n]*\b(?:claude|copilot|codex|cursor|devin|gemini|aider|agent)\b|claude-session:|pmos-session:)/im;
+const AGENT_EMAIL = /noreply@anthropic\.com|\[bot\]@users\.noreply\.github\.com/i;
+const isAgentCommit = (message, email) => AGENT_COMMIT.test(String(message || '')) || AGENT_EMAIL.test(String(email || ''));
+
+function git(cwd, args) {
+  try { return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 }); }
+  catch { return null; }
+}
+
+function readJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  const out = [];
+  text.split('\n').forEach((raw, i) => {
+    if (!raw.trim()) return;
+    let rec = null;
+    try { rec = JSON.parse(raw); } catch { return; }   // a torn line is its own checker's defect
+    if (rec && typeof rec === 'object' && !Array.isArray(rec)) out.push({ n: i + 1, rec });
+  });
+  return out;
+}
+
+/**
+ * For each line number of `file`: the commit that added it, as { sha, time (ms), agent, boundary }, or null for a line
+ * that is not committed. One `git blame` and one `git log` per file. Null when the file is not in a git repository.
+ */
+function arrivals(file) {
+  const dir = path.dirname(file);
+  const out = git(dir, ['blame', '--root', '--line-porcelain', '--', path.basename(file)]);
+  if (out === null) return null;
+  const byLine = new Map();
+  const meta = new Map();
+  let cur = null;
+  for (const l of out.split('\n')) {
+    const h = /^([0-9a-f]{40}) \d+ (\d+)/.exec(l);
+    if (h) { cur = { sha: h[1], n: Number(h[2]) }; if (!meta.has(h[1])) meta.set(h[1], { boundary: false, time: null }); continue; }
+    if (!cur) continue;
+    if (l === 'boundary') meta.get(cur.sha).boundary = true;
+    else if (l.startsWith('committer-time ')) meta.get(cur.sha).time = Number(l.slice(15)) * 1000;
+    else if (l.startsWith('\t')) { byLine.set(cur.n, cur.sha); cur = null; }
+  }
+  const shas = [...meta.keys()].filter((s) => !/^0+$/.test(s));
+  if (shas.length) {
+    const log = git(dir, ['log', '--no-walk=unsorted', '--format=%H%x1f%ae%x1f%B%x1e', ...shas]) || '';
+    for (const rec of log.split('\x1e')) {
+      const [sha, email, body] = rec.replace(/^\n/, '').split('\x1f');
+      if (meta.has(sha)) meta.get(sha).agent = isAgentCommit(body, email);
+    }
+  }
+  const res = new Map();
+  for (const [n, sha] of byLine) res.set(n, /^0+$/.test(sha) ? null : { sha, ...meta.get(sha) });
+  return res;
+}
+
+/** Is the repository of `dir` a shallow clone? */
+const isShallow = (dir) => (git(dir, ['rev-parse', '--is-shallow-repository']) || '').trim() === 'true';
+
+/**
+ * The cut-over commit: the oldest commit whose `rulesFile` sets via_required_from, and the set of its descendants (itself
+ * included). { sha: null, descendants: null } when no commit sets it (every committed line comes before the cut-over) or
+ * when there is no git history to read.
+ */
+function cutoverCommit(rulesFile) {
+  const none = { sha: null, descendants: null };
+  if (!rulesFile) return none;
+  const dir = path.dirname(rulesFile);
+  const top = (git(dir, ['rev-parse', '--show-toplevel']) || '').trim();
+  if (!top) return none;
+  let rel;
+  try { rel = path.relative(top, fs.realpathSync(rulesFile)).split(path.sep).join('/'); } catch { return none; }
+  const shas = (git(top, ['log', '--format=%H', '--reverse', '--', rel]) || '').split('\n').filter(Boolean);
+  for (const sha of shas) {
+    let v = null;
+    try { v = JSON.parse(git(top, ['show', `${sha}:${rel}`]) || 'null'); } catch { v = null; }
+    if (v && typeof v.via_required_from === 'string') {
+      // Descendants of the cut-over commit (itself included). A commit that is not one is before the cut-over: an
+      // ancestor, or a commit on a parallel branch made before it and merged in later (a merge does not make it new).
+      const desc = (git(top, ['rev-list', '--ancestry-path', `${sha}..HEAD`]) || '').split('\n').filter(Boolean);
+      return { sha, descendants: new Set([sha, ...desc]) };
+    }
+  }
+  return none;
+}
+
+const BULK_STATE = /^(active|closed|on-hold|cancelled):(.+)$/;
+/** Why the grant `g` does not cover the PM-only line `rec` of `ledger`, or null when it does. */
+function grantMismatch(ledger, rec, g) {
+  const t = timeOf(rec);
+  const from = Date.parse(g.at || '');
+  const to = Date.parse(g.expires_at || '');
+  if (t === null || Number.isNaN(from) || Number.isNaN(to) || t < from || t > to) return `its at is outside the window of grant ${g.id} (${g.at} to ${g.expires_at})`;
+  if (ledger !== 'lifecycle') return null;
+  if (g.scope !== 'lifecycle-bulk') return `grant ${g.id} has scope ${JSON.stringify(g.scope)}, and a lifecycle line needs lifecycle-bulk`;
+  const m = BULK_STATE.exec(String(g.target || ''));
+  if (!m || m[1] !== rec.state || !m[2].split(',').includes(initiativeOf(rec))) return `grant ${g.id} covers ${JSON.stringify(g.target)}, not ${rec.state}:${initiativeOf(rec)}`;
+  return null;
+}
+
+// A line's own time. Lines written before Run 2 name it `created_at`, `recorded_at` or `accepted_at`.
+const TIME_KEYS = ['at', 'date', 'accepted_at', 'recorded_at', 'created_at'];
+const timeOf = (rec) => {
+  for (const k of TIME_KEYS) { const t = typeof rec[k] === 'string' ? Date.parse(rec[k]) : NaN; if (!Number.isNaN(t)) return t; }
+  return null;
+};
+const initiativeOf = (rec) => (typeof rec.initiative === 'string' ? rec.initiative : typeof rec.initiative_id === 'string' ? rec.initiative_id : null);
+
+/** The one rule. `runsDir` defaults to the runs directory of the main tree of `root` (lib/plan-ledgers.js). */
+function scan(root, { runsDir, rules, rulesFile, now = Date.now(), arrival = true } = {}) {
+  const dir = runsDir || ledgers.runsDir(root);
+  const r = rules || planRules.readRules(root);
+  const cutover = typeof r.via_required_from === 'string' ? Date.parse(r.via_required_from) : null;
+  const grantRows = readJsonl(path.join(dir, 'grants.jsonl')) || [];
+  const grants = new Map(grantRows.filter((g) => g.rec.type === 'grant' && typeof g.rec.id === 'string').map((g) => [g.rec.id, g.rec]));
+  const checkArrival = cutover !== null && arrival;
+  const shallow = checkArrival && isShallow(dir);
+  const cut = checkArrival ? cutoverCommit(rulesFile === undefined ? planRules.rulesPath(root) : rulesFile) : { sha: null, descendants: null };
+  const base = runsDir ? path.resolve(String(root)) : planTree.mainTree(path.resolve(String(root)));   // the paths a row names
+  const flags = [];
+  const older = [];
+  for (const src of SOURCES) {
+    const file = path.join(dir, src.file);
+    const lines = readJsonl(file);
+    if (!lines) continue;
+    const rel = path.relative(base, file).split(path.sep).join('/') || src.file;
+    const pm = lines.filter((l) => { try { return !!src.pmOnly(l.rec); } catch { return false; } });
+    if (!pm.length) continue;
+    const arr = checkArrival ? arrivals(file) : null;
+    let olderCount = 0;
+    for (const { n, rec } of pm) {
+      const t = timeOf(rec);
+      const a = arr ? arr.get(n) : null;
+      // Ancestry, not dates: an uncommitted line, a line at a shallow edge, and every commit while no commit sets the
+      // rules file come before the cut-over; any other commit must not descend from the cut-over commit.
+      const commitOld = cutover === null || !a || a.boundary || cut.descendants === null || !cut.descendants.has(a.sha);
+      // A line with no time of its own is older only when a commit before the cut-over added it: an uncommitted line
+      // with no time is a hand write, and is checked.
+      const lineOld = cutover === null || (t !== null ? t < cutover : !!(a && !a.boundary && commitOld));
+      const isOlder = lineOld && (commitOld || !arr);
+      const causes = [];
+      const say = (kind, cause, message) => causes.push({ kind, cause, message });
+      const viaMissing = typeof rec.via !== 'string' || !rec.via.trim();
+      if (src.viaChecked && viaMissing && !isOlder) say('no-via', `${what[src.ledger](rec)} has no via`, `written after via_required_from with no via`);
+      const cites = typeof rec.grant === 'string' ? rec.grant : rec.via === 'grant' ? '' : null;
+      if (cites !== null && !grants.has(cites)) {
+        say('unknown-grant', `${what[src.ledger](rec)} cites a grant that grants.jsonl does not hold`, `cites grant ${JSON.stringify(cites)}, which is not in grants.jsonl`);
+      } else if (cites !== null) {
+        const why = grantMismatch(src.ledger, rec, grants.get(cites));
+        if (why) say('grant-mismatch', `${what[src.ledger](rec)} cites a grant that does not cover it`, why);
+      }
+      if (D86.has(src.ledger) && typeof rec.by === 'string' && !rec.by.startsWith('pm:')) {
+        say('not-pm', `${what[src.ledger](rec)} is written by an agent`, 'a PM-only line whose by is not the PM');
+      }
+      if (a && !a.boundary && a.agent && !isOlder) {
+        say('agent-commit', `${what[src.ledger](rec)} arrived in an agent-authored commit`, `arrived in the agent-authored commit ${a.sha.slice(0, 8)}`);
+      }
+      if (isOlder && viaMissing && src.viaChecked) olderCount++;
+      for (const c of causes) flags.push({ ...c, ledger: src.ledger, rel, n, initiative: initiativeOf(rec), eid: typeof rec.eid === 'string' ? rec.eid : null });
+    }
+    if (olderCount) older.push({ ledger: src.ledger, rel, count: olderCount });
+  }
+  // D87: each agent acceptance must rest on a passing Review Gate row for its run
+  const accFile = path.join(dir, 'acceptances.jsonl');
+  const agentLines = (readJsonl(accFile) || []).filter((l) => isAgentAcceptance(l.rec));
+  if (agentLines.length) {
+    const evalRows = (readJsonl(path.join(dir, 'evals.jsonl')) || []).map((l) => l.rec);
+    const rel = path.relative(base, accFile).split(path.sep).join('/') || 'acceptances.jsonl';
+    for (const { n, rec } of agentLines) {
+      const why = agentBasisProblem(rec, evalRows);
+      if (why) flags.push({ kind: 'agent-basis', cause: 'An agent acceptance is not backed by the Review Gate', message: why, ledger: 'acceptances', rel, n, initiative: initiativeOf(rec), eid: null });
+    }
+  }
+  return { cutover: cutover === null ? null : new Date(cutover).toISOString(), cutoverCommit: cut.sha, flags, older, shallow, runsDir: dir, now };
+}
+
+// ── the needs provider (lib/needs-providers.js) ─────────────────────────────────────────────────────────────────────
+// A scan runs git (blame, rev-list) over the whole history. server.js asks for every registered tree on each needs
+// poll, so the rows are kept per root until `sig` (every input: ledgers, grants, rules, HEAD's reflog) changes.
+const rowsCache = new Map();   // root -> { sig, rows }
+function rowsFor(w, { lead = true } = {}) {
+  if (!w || !w.root || !lead) return [];   // repository-wide rows: only the lead tree speaks for the ledgers
+  let key = null;
+  try { key = sig(w); } catch { key = null; }
+  const hit = rowsCache.get(w.root);
+  if (key && hit && hit.sig === key) return hit.rows.map((r) => ({ ...r, today: { ...r.today } }));
+  const rows = rowsFresh(w);
+  if (key) rowsCache.set(w.root, { sig: key, rows });
+  return rows.map((r) => ({ ...r, today: { ...r.today } }));
+}
+function rowsFresh(w) {
+  const s = scan(w.root);
+  const byLine = new Map();
+  for (const f of s.flags) {
+    const key = `${f.rel}:${f.n}`;
+    if (!byLine.has(key)) byLine.set(key, { first: f, causes: [] });
+    byLine.get(key).causes.push(f.cause);
+  }
+  return [...byLine.values()].map(({ first, causes }) => ({
+    run_id: `pm-lines-needs:${first.eid || `${first.ledger}-${first.n}`}`,
+    kind: KIND,
+    initiative_id: first.initiative,
+    question: QUESTION,
+    doc: null,
+    today: { kind: 8, source: 'pm-lines-needs', cause: causes.join('; '), evidence: `${first.rel} line ${first.n}`, act: { label: 'Show line', cli: null } },
+  }));
+}
+
+/** Changes whenever a row may: every ledger read, grants.jsonl, the rules file and the git history (a commit). */
+function sig(w) {
+  if (!w || !w.root) return '';
+  const parts = [];
+  const stat = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}:${st.ino}`; } catch { return 'none'; } };
+  let dir = null;
+  try { dir = ledgers.runsDir(w.root); } catch { return 'engine-missing'; }
+  for (const src of SOURCES) parts.push(src.file + '=' + stat(path.join(dir, src.file)));
+  parts.push('evals=' + stat(path.join(dir, 'evals.jsonl')));
+  parts.push('grants=' + stat(path.join(dir, 'grants.jsonl')));
+  parts.push('rules=' + stat(planRules.rulesPath(w.root) || ''));
+  parts.push('head=' + stat(path.join(planTree.mainTree(path.resolve(String(w.root))), '.git', 'logs', 'HEAD')));
+  return crypto.createHash('sha1').update(parts.join('|')).digest('hex');
+}
+
+module.exports = { kinds: [KIND], rowsFor, sig, scan, SOURCES, AGENT_COMMIT, isAgentCommit, isAgentAcceptance, agentBasisProblem };

package/workspace/lib/pmos-verbs.js

@@ -0,0 +1,69 @@
+'use strict';
+/* pmos-verbs.js — the planning layer's `pmos` verbs: which module runs each, its help line and its guide page
+ * (pm-os-absorb Runs 2 to 5, PRD R24).
+ *
+ *   has(verb) · run(verb, argv, { say, call }) → Promise<exit code> · names() · helpLines()
+ *   VERBS
+ *
+ * bin/pmos.js asks has() and hands the call to run(), so the runs that add a verb add a module and never edit the
+ * launcher. A VERB MODULE is workspace/lib/<verb>-cli.js, in the shape of lib/item-cli.js:
+ *   module.exports = { run(argv, { say, call }) → exit code | Promise, COMMANDS: { <verb>: ['sub', …] }, USAGE };
+ * argv is process.argv.slice(2), so argv[0] is the verb. `say` prints a line. `call(method, path, body)` reaches the
+ * running workspace server, or answers null when none runs; it sends no Origin header, so a PM-only route refuses it.
+ * A PM-only act from the CLI goes through lib/pm-guard.js requirePmCli and the writer module directly, never over HTTP.
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ *
+ * guide.test.js G24 reads COMMANDS of every module present and requires each `pmos <verb> <sub>` in the `guide` page
+ * named here, so a verb cannot ship without its guide text.
+ *
+ * A listed verb is a verb from now on, built or not: `pmos board` no longer opens a folder named board (R24 says a
+ * path with a verb's name needs `./`). A verb whose module is not on disk yet says which run brings it and exits 2.
+ */
+const path = require('path');
+
+const VERBS = Object.freeze({
+  initiative: Object.freeze({ module: 'initiative-cli.js', run: 2, guide: 'initiatives-roadmap.md',
+    help: 'pmos initiative new|now|next|later|list|export … — initiatives and their place on the Roadmap (pmos initiative help)' }),
+  measure: Object.freeze({ module: 'measure-cli.js', run: 2, guide: 'initiatives-roadmap.md',
+    help: 'pmos measure … — record a measured value of a KR or a health budget, with its source (pmos measure help)' }),
+  today: Object.freeze({ module: 'today-cli.js', run: 3, guide: 'today.md',
+    help: 'pmos today — what needs you, ranked as Today shows it' }),
+  board: Object.freeze({ module: 'board-cli.js', run: 4, guide: 'board.md',
+    help: 'pmos board [--mine] [--init <id>] — the items of every initiative, by column' }),
+  'verify-work': Object.freeze({ module: 'verify-work-cli.js', run: 4, guide: 'integrated-work.md',
+    help: 'pmos verify-work — mark work items integrated from the default branch (local refs only)' }),
+  report: Object.freeze({ module: 'report-cli.js', run: 5, guide: 'reports.md',
+    help: 'pmos report draft|issue|list … — draft and issue reports (pmos report help)' }),
+  // Not a pm-os-absorb verb (run: null): the workspace-launcher initiative added it through the same table.
+  launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
+    help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
+});
+
+const has = (verb) => typeof verb === 'string' && Object.prototype.hasOwnProperty.call(VERBS, verb);
+const names = () => Object.keys(VERBS);
+const helpLines = () => names().map((v) => '  ' + VERBS[v].help);
+
+/** The verb's module, or null when its run has not built it. A module that is present and fails to load throws. */
+function load(verb) {
+  const full = path.join(__dirname, VERBS[verb].module);
+  try { return require(full); }
+  catch (e) {
+    if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(full)) return null;
+    throw e;
+  }
+}
+
+async function run(verb, argv, { say = console.log, call = async () => null } = {}) {
+  if (!has(verb)) { say(`✗ pmos ${verb} is not a verb`); return 2; }
+  let mod;
+  try { mod = load(verb); }
+  catch (e) { say(`✗ pmos ${verb} could not load: ${String((e && e.message) || e).slice(0, 200)}`); return 1; }
+  if (!mod || typeof mod.run !== 'function') {
+    say(`✗ pmos ${verb} arrives in Run ${VERBS[verb].run} of pm-os-absorb. To open a folder named ${verb}, type: pmos ./${verb}`);
+    return 2;
+  }
+  const code = await mod.run(argv, { say, call });
+  return Number.isInteger(code) ? code : 0;
+}
+
+module.exports = { VERBS, has, names, helpLines, load, run };