create-pmos 0.166.0 → 0.168.0

package/workspace/lib/driver-cli.js

@@ -0,0 +1,207 @@
+'use strict';
+/* driver-cli.js — `pmos driver …`: the Initiative Driver from a terminal (initiative initiative-driver, PRD sections 4 and 5).
+ *
+ *   pmos driver propose <initiative|work> <id> --what <what> (--file <json|md> | --data "<text>") --why "<one line>"
+ *                       [--source label=ref …] [--ws <id>]     an agent session files a proposal (anyone may; the PM seldom does)
+ *   pmos driver status <initiative|work> <id>                  proposals, pause, mode and the day's runs (read)
+ *   pmos driver keep <proposal>                                PM only: type the proposal id to confirm
+ *   pmos driver return <proposal> --note "<what to change>"    PM only: send back; the note wakes a run
+ *   pmos driver drop <proposal> [--note "<why>"]               PM only
+ *   pmos driver pause|resume <initiative|work> <id>            PM only
+ *   pmos driver mode <off|shadow|approve> [--board <id>]       PM only; with no --board it sets every board
+ *   every command: [--json] [--root <dir>]
+ *
+ * Who wrote a line is the call path (lib/actor.js), never an argument. `keep` goes through lib/pm-guard.js requirePmCli, which
+ * refuses an agent session without asking; `return`, `drop`, `pause`, `resume` and `mode` refuse any actor that is not the PM
+ * at an interactive terminal. The agent-facing verbs are `propose` and `status` only. Keep writes through the existing writers
+ * (lib/driver-decide.js); a kept move is pressed on the workspace page, where the board move route runs.
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const D = require('./driver.js');
+const decideLib = require('./driver-decide.js');
+const stageTools = require('./stage-tools.js');
+const stateRoot = require('./state-root.js');
+
+const COMMANDS = { driver: ['propose', 'status', 'keep', 'return', 'drop', 'pause', 'resume', 'mode'] };
+const USAGE = [
+  'usage: pmos driver propose|status|keep|return|drop|pause|resume|mode — the Initiative Driver',
+  '  pmos driver propose <initiative|work> <id> --what <what> (--file <json|md> | --data "<text>") --why "<one line>" [--source label=ref …]',
+  '      what: problem, evidence, sizing, assumption, stakeholders, move, note (initiative) · next-step, follow-up, note (Work task)',
+  '  pmos driver status <initiative|work> <id>',
+  '  pmos driver keep <proposal>                                  PM only',
+  '  pmos driver return <proposal> --note "<what to change>"      PM only',
+  '  pmos driver drop <proposal> [--note "<why>"]                 PM only',
+  '  pmos driver pause|resume <initiative|work> <id>              PM only',
+  '  pmos driver mode <off|shadow|approve> [--board <id>]         PM only',
+  '  every command: [--json] [--root <dir>]',
+  'Every claim in a proposal carries a pointer (--source label=ref). The driver sends nothing and edits no record: Keep is the PM\'s.',
+];
+const BOOL = new Set(['json', 'help']);
+const VALUE = new Set(['what', 'file', 'data', 'why', 'source', 'ws', 'note', 'board', 'root']);
+
+function parse(argv) {
+  const pos = []; const flags = {}; const sources = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h') { flags.help = true; continue; }
+    if (!a.startsWith('--')) { pos.push(a); continue; }
+    const eq = a.indexOf('=');
+    const key = eq > 0 ? a.slice(2, eq) : a.slice(2);
+    if (BOOL.has(key)) { flags[key] = true; continue; }
+    let val;
+    if (eq > 0) val = a.slice(eq + 1);
+    else { const next = argv[i + 1]; if (next === undefined || (next.startsWith('--') && next.length > 2)) val = ''; else { val = next; i++; } }
+    if (key === 'source') sources.push(val); else flags[key] = val;
+  }
+  return { pos, flags, sources };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+
+/** The data of a proposal from --file (JSON by extension or by content, else the text) or --data. */
+function dataFrom(flags, cwd) {
+  let raw;
+  if (flags.file) {
+    try { raw = fs.readFileSync(path.resolve(cwd, flags.file), 'utf8'); } catch (e) { return { error: `cannot read ${flags.file}: ${String(e.code || e.message)}` }; }
+  } else raw = flags.data;
+  if (typeof raw !== 'string' || !raw.trim()) return { error: 'give the proposal body with --file <json|md> or --data "<text>"' };
+  const t = raw.trim();
+  if (t.startsWith('{') || (flags.file && /\.json$/i.test(flags.file))) {
+    try { const j = JSON.parse(t); if (j && typeof j === 'object' && !Array.isArray(j)) return { data: j }; } catch { if (/\.json$/i.test(flags.file || '')) return { error: `${flags.file} is not valid JSON` }; }
+  }
+  return { data: { text: t } };
+}
+function sourcesFrom(list) {
+  const out = [];
+  for (const s of list) {
+    const eq = s.indexOf('=');
+    if (eq < 1 || eq === s.length - 1) return { error: `--source needs label=ref, not "${s.slice(0, 60)}"` };
+    out.push({ label: s.slice(0, eq).trim(), ref: s.slice(eq + 1).trim() });
+  }
+  return { sources: out };
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now, ask } = {}) {
+  const args = argv[0] === 'driver' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags, sources } = parse(args.slice(1));
+  const json = !!flags.json;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) { for (const l of USAGE) say(l); return verb ? 0 : 1; }
+  if (!COMMANDS.driver.includes(verb)) { say(`unknown driver command "${verb}" — one of ${COMMANDS.driver.join(', ')}`); return 2; }
+  if ('by' in flags || 'via' in flags) { say(`attribution is set from the call path; --${'by' in flags ? 'by' : 'via'} is not accepted`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const who = { isTTY: isTTY === undefined ? !!(process.stdin.isTTY && process.stdout.isTTY) : isTTY, env: env === undefined ? process.env : env };
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const done = (obj, line) => { if (json) say(JSON.stringify({ ok: true, ...obj })); else say(line); return 0; };
+  const stateDir = D.stateDirOf(root);
+  const file = D.ledgerFile(stateDir);
+  const noState = () => fail('this repository has no PMOS state folder (pmos/state, state or .pmos), so the driver has nowhere to keep its ledger');
+  const ws = flags.ws || D.wsIdOf(root);
+  const target = () => ({ kind: pos[0], ws, id: pos[1] });
+  const needTarget = () => {
+    if (!pos[0] || !pos[1]) { say(`usage: pmos driver ${verb} <initiative|work> <id>`); return false; }
+    return true;
+  };
+  const pmOnly = (act) => {
+    const a = actorLib.fromCli(who);
+    if (!actorLib.isPm(a)) return { ok: false, error: `only the PM can ${act}, at an interactive terminal${actorLib.isAgent(a) && a.by !== 'agent:unknown' ? '; an agent session cannot' : ''}` };
+    return { ok: true, actor: a };
+  };
+
+  if (verb === 'propose') {
+    if (!needTarget()) return 2;
+    if (!file) return noState();
+    if (!flags.what) { say('usage: pmos driver propose <initiative|work> <id> --what <what> (--file <json|md> | --data "<text>") --why "<one line>"'); return 2; }
+    const d = dataFrom(flags, cwd);
+    if (d.error) return fail(d.error, 2);
+    const s = sourcesFrom(sources);
+    if (s.error) return fail(s.error, 2);
+    const c = D.checkProposal({ ...target(), what: flags.what, data: d.data, why: flags.why, sources: s.sources });
+    if (!c.ok) return fail(c.error);
+    const actor = actorLib.fromCli(who);
+    const state = D.fold(D.readLines(file));
+    const same = JSON.stringify(c.proposal.data);
+    const dup = [...state.proposals.values()].find((p) => D.targetKey(p.target) === D.targetKey(c.proposal.target) && p.what === c.proposal.what && JSON.stringify(p.data) === same);
+    if (dup) return done({ filed: false, duplicate: dup.id, state: dup.state }, `${dup.id} holds this already (${dup.state}); nothing new was filed`);
+    const token = actorLib.isAgent(actor) && actor.by !== 'agent:unknown' ? actor.by.slice('agent:'.length) : null;
+    const id = D.newId('p');
+    const line = D.append(file, { ev: 'proposal', id, ...c.proposal, run: D.runOfSession(state, token), by: actor.by }, { now });
+    return done({ filed: true, id, proposal: { ...line, by: actorLib.pageName(line.by) } }, `✓ filed ${id}: ${c.proposal.what} for ${c.proposal.target.kind} ${c.proposal.target.id}. The PM keeps, sends back or drops it.`);
+  }
+
+  if (verb === 'status') {
+    if (!needTarget()) return 2;
+    if (!file) return noState();
+    const t = D.checkTarget(target());
+    if (!t.ok) return fail(t.error);
+    const state = D.fold(D.readLines(file));
+    const mine = [...state.proposals.values()].filter((p) => D.targetKey(p.target) === D.targetKey(t.target));
+    const day = D.localDay(now == null ? Date.now() : now);
+    const used = D.runsOnDay(state, t.target, day);
+    const limit = t.target.kind === 'work' ? D.BUDGET.workPerDay : D.BUDGET.initiativePerDay;
+    const out = { target: t.target, paused: D.isPaused(state, t.target), mode: D.modeOf(state, t.target.kind === 'work' ? 'work' : null), runs_today: used, runs_limit: limit,
+      proposals: mine.map((p) => ({ id: p.id, what: p.what, state: p.state, why: p.why, note: p.note, at: p.at })) };
+    if (json) { say(JSON.stringify({ ok: true, ...out })); return 0; }
+    say(`${t.target.kind} ${t.target.id} · mode ${out.mode}${out.paused ? ' · paused' : ''} · ${used} of ${limit} runs today`);
+    for (const p of out.proposals) say(`  ${p.id} · ${p.what} · ${p.state}${p.note ? ` · "${p.note}"` : ''} — ${p.why}`);
+    if (!out.proposals.length) say('  no proposals');
+    return 0;
+  }
+
+  // ── the PM's verbs ────────────────────────────────────────────────────────────────────────────────
+  if (verb === 'keep' || verb === 'return' || verb === 'drop') {
+    const pid = pos[0];
+    if (!pid) { say(`usage: pmos driver ${verb} <proposal>${verb === 'return' ? ' --note "<what to change>"' : ''}`); return 2; }
+    let actor;
+    if (verb === 'keep') {
+      const g = await guard.requirePmCli({ act: 'keep', expect: pid, isTTY: who.isTTY, env: who.env, ask: ask || guard.askAtTerminal });
+      if (!g.ok) return fail(g.error);
+      actor = g.actor;
+    } else {
+      const g = pmOnly(verb === 'return' ? 'send a proposal back' : 'drop a proposal');
+      if (!g.ok) return fail(g.error);
+      actor = g.actor;
+    }
+    if (!file) return noState();
+    const p = D.fold(D.readLines(file)).proposals.get(pid);
+    if (p && verb === 'keep' && p.what === 'move') return fail('keep a move on the workspace page: the board move route checks the stage and its warnings');
+    const ctx = { stageFile: path.join(stateDir, stageTools.LEDGER), itemsDir: path.join(stateRoot.defaultRoot(), 'pm-items'),
+      correctionsFile: path.join(stateRoot.defaultRoot(), 'corrections.jsonl') };
+    const r = await decideLib.decide(verb, { file, proposal: pid, note: flags.note, actor, ctx, now });
+    if (!r.ok) return fail(r.error);
+    return done({ proposal: pid, state: r.proposal.state, wrote: r.wrote }, `✓ ${pid} ${r.proposal.state}${r.wrote ? ` (written to the ${r.wrote} record as you)` : ''}`);
+  }
+
+  if (verb === 'pause' || verb === 'resume') {
+    if (!needTarget()) return 2;
+    const g = pmOnly(`${verb} the driver`);
+    if (!g.ok) return fail(g.error);
+    if (!file) return noState();
+    const r = decideLib.setPause(file, verb, target(), g.actor, { now });
+    if (!r.ok) return fail(r.error);
+    return done({ target: r.target, paused: r.paused }, `✓ the driver is ${r.paused ? 'paused' : 'resumed'} for ${r.target.kind} ${r.target.id}`);
+  }
+
+  // mode
+  const mode = pos[0];
+  if (!mode) { say('usage: pmos driver mode <off|shadow|approve> [--board <id>]'); return 2; }
+  const g = pmOnly('set the driver mode');
+  if (!g.ok) return fail(g.error);
+  if (!file) return noState();
+  const r = decideLib.setMode(file, flags.board || '*', mode, g.actor, { now });
+  if (!r.ok) return fail(r.error);
+  return done({ board: r.board, mode: r.mode }, `✓ driver mode ${r.mode} for ${r.board === '*' ? 'every board' : 'board ' + r.board}`);
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/driver-decide.js

@@ -0,0 +1,118 @@
+'use strict';
+/* driver-decide.js — what the PM does with a driver proposal, and with the driver itself (initiative initiative-driver,
+ * PRD sections 4 and 5). The CLI (lib/driver-cli.js) and the routes (lib/routes-driver.js) both call it, so a terminal and
+ * a page press cannot differ.
+ *
+ *   decide(verb, { file, proposal, note, actor, ctx, now }) → Promise of { ok, proposal, wrote } | { ok: false, status, error }
+ *        verb: keep | return | drop. ctx: { stageFile, itemsDir, move(proposal) → { status, body }, correctionsFile? }
+ *   setPause(file, verb, target, actor, { now })        verb: pause | resume
+ *   setMode(file, board, mode, actor, { now })          mode: off | shadow | approve; board '*' is every board
+ *
+ * The caller has already proved the actor is the PM (pm-guard requirePagePress on a route, lib/actor.js on the CLI). These
+ * functions still refuse a non-PM actor: a run cannot keep its own proposals.
+ *
+ * KEEP WRITES THE PM'S RECORD THROUGH THE EXISTING WRITERS, so the record says the PM made it (PRD section 4):
+ *   problem    → lib/stage-tools.js appendTool, tool `problem`, `by` the PM
+ *   move       → the board move route's own function (lib/routes-boards.js move): its validation and warnings apply
+ *   next-step  → lib/pm-items.js appendEvent: a step (lib/item-steps.js) and, when the proposal names a date, an `edited` due
+ * Every other kind (evidence, sizing, assumption, stakeholders, follow-up, note) is kept as a decision only: the PM's choice to
+ * rely on it. A follow-up is never sent: the PM sends it from their own session. The driver never moves a stage by itself (D3).
+ * RETURN needs a note and DROP may carry one; each logs one correction (the north star counts it) and a return wakes a run.
+ */
+const fs = require('fs');
+const path = require('path');
+const actorLib = require('./actor.js');
+const D = require('./driver.js');
+const stageTools = require('./stage-tools.js');
+const pmItems = require('./pm-items.js');
+
+const refuse = (status, error) => ({ ok: false, status, error });
+const isPm = (a) => !!a && actorLib.isPm(a);
+
+function itemsPaths(dir) { return { items: path.join(dir, 'items.jsonl'), steps: path.join(dir, 'steps.jsonl') }; }
+
+/** The record write of a Keep. → { ok, wrote } | { ok: false, status, error }. */
+async function writeRecord(p, actor, ctx, now) {
+  if (p.what === 'problem') {
+    if (!ctx.stageFile) return refuse(409, 'this repository has no state folder to keep the problem statement in');
+    const c = stageTools.checkData('problem', { text: p.data && p.data.text });
+    if (!c.ok) return refuse(400, c.error);
+    stageTools.appendTool(ctx.stageFile, { initiative: p.target.id, tool: 'problem', data: c.data }, actor, { now });
+    return { ok: true, wrote: 'problem' };
+  }
+  if (p.what === 'move') {
+    if (typeof ctx.move !== 'function') return refuse(409, 'a move is kept from the workspace page');
+    const r = await ctx.move(p);
+    if (!r || !r.body || r.body.ok !== true) return refuse((r && r.status) || 500, (r && r.body && r.body.error) || 'the move was refused');
+    return { ok: true, wrote: 'move', warnings: r.body.warnings || [] };
+  }
+  if (p.what === 'next-step') {
+    if (!ctx.itemsDir) return refuse(409, 'no folder for the Work items');
+    const paths = itemsPaths(ctx.itemsDir);
+    const lines = pmItems.readLines(paths.items);
+    const item = pmItems.fold(lines).find((i) => i.id === p.target.id);
+    if (!item) return refuse(404, `no Work task ${p.target.id}`);
+    const stepsLib = require('./item-steps.js');
+    const id = `step-${require('crypto').randomBytes(6).toString('hex')}`;
+    const r = stepsLib.addStep(p.target.id, p.data.text, 'you', id);
+    if (!r.ok) return refuse(400, r.error);
+    pmItems.appendEvent(paths.steps, r.event, new Date(now));
+    if (p.data.due) pmItems.appendEvent(paths.items, { event: 'edited', id: p.target.id, fields: { due: p.data.due } }, new Date(now));
+    return { ok: true, wrote: 'next-step' };
+  }
+  return { ok: true, wrote: null };
+}
+
+async function decide(verb, { file, proposal, note, actor, ctx = {}, now } = {}) {
+  if (!['keep', 'return', 'drop'].includes(verb)) return refuse(500, `driver: ${JSON.stringify(verb)} is not a decision`);
+  if (!isPm(actor)) return refuse(403, 'only the PM can keep, send back or drop a driver proposal');
+  if (!file) return refuse(409, 'this repository has no state folder for the driver');
+  const t = now == null ? Date.now() : now;
+  const state = D.fold(D.readLines(file));
+  const p = state.proposals.get(proposal);
+  if (!p) return refuse(404, `no driver proposal ${String(proposal).slice(0, 40)}`);
+  if (p.state !== 'open') return refuse(409, `the proposal is ${p.state} already`);
+  const text = typeof note === 'string' ? note.trim() : '';
+  if (text.length > 500 || /[\r\n]/.test(text)) return refuse(400, 'the note is one line of at most 500 characters');
+  if (verb === 'return' && !text) return refuse(400, 'say what to change: sending a proposal back needs a note');
+  let wrote = null; let warnings = [];
+  if (verb === 'keep') {
+    const w = await writeRecord(p, actor, ctx, t);
+    if (!w.ok) return w;
+    wrote = w.wrote; warnings = w.warnings || [];
+  }
+  D.append(file, { ev: verb, proposal: p.id, ...(text ? { note: text } : {}), by: actor.by }, { now: t });
+  if (verb !== 'keep') {
+    D.append(file, { ev: 'correction', proposal: p.id, run: p.run, kind: verb, by: actor.by }, { now: t });
+    if (ctx.correctionsFile) {
+      try {
+        const reason = `driver:${verb}`;
+        fs.mkdirSync(path.dirname(ctx.correctionsFile), { recursive: true });
+        fs.appendFileSync(ctx.correctionsFile, JSON.stringify({ type: 'correction', kind: 'reject', reason, run: p.run, counted: true, at: new Date(t).toISOString(),
+          record: { kind: 'correction', run: p.run, reason, by: 'pm' } }) + '\n');
+      } catch { /* the driver ledger already holds the correction */ }
+    }
+  }
+  return { ok: true, proposal: D.fold(D.readLines(file)).proposals.get(p.id), wrote, warnings };
+}
+
+function setPause(file, verb, target, actor, { now } = {}) {
+  if (!['pause', 'resume'].includes(verb)) return refuse(500, `driver: ${JSON.stringify(verb)} is not pause or resume`);
+  if (!isPm(actor)) return refuse(403, 'only the PM can pause or resume the driver');
+  if (!file) return refuse(409, 'this repository has no state folder for the driver');
+  const c = D.checkTarget(target);
+  if (!c.ok) return refuse(400, c.error);
+  D.append(file, { ev: verb, target: c.target, by: actor.by }, { now });
+  return { ok: true, paused: verb === 'pause', target: c.target };
+}
+
+function setMode(file, board, mode, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can set the driver mode');
+  if (!file) return refuse(409, 'this repository has no state folder for the driver');
+  if (!D.MODES.includes(mode)) return refuse(400, `mode must be one of ${D.MODES.join(', ')}`);
+  if (typeof board !== 'string' || !/^[A-Za-z0-9*][A-Za-z0-9._*-]{0,79}$/.test(board)) return refuse(400, 'board must be a board id (or * for every board)');
+  D.append(file, { ev: 'mode', board, mode, by: actor.by }, { now });
+  return { ok: true, board, mode };
+}
+
+module.exports = { decide, setPause, setMode, writeRecord };

package/workspace/lib/driver-facts.js

@@ -0,0 +1,113 @@
+'use strict';
+/* driver-facts.js — what the unblock sweep reads (initiative initiative-driver, PRD section 3).
+ *
+ *   gather(w, ctx, { now, includeWork, runtimeDir, driverState }) → { ok: true, facts } | { pending: true } | { ok: false, error }
+ *
+ * `facts` is the shape lib/driver.js detect() documents. This file only READS: the cached workflow rows and the boards ledger
+ * (lib/routes-boards.js), the stage-tool records (lib/stage-tools.js), the cached Jira readings (lib/jira-status.js), the
+ * placements ledger and the Work items. It starts no derivation of its own: while the rows are still being read it answers
+ * pending and the sweep tries again at the next tick. `ctx` is what route modules get (stateDirFor, selfRoot, getWs …).
+ *
+ * WHAT IS ACTIVE. An initiative that is not done, not stopped by a lifecycle line and not dormant. A dormant initiative (Later,
+ * untouched for dormant_days) is folded away on the Roadmap and starts no driver run.
+ * LIMITS, NAMED. The Jira readings keep no status-change time, so `last_ticket_move` is the latest resolved date of the
+ * initiative's tickets (null when none: the Do rule then stays quiet instead of guessing). `has_evidence` counts kept driver
+ * evidence only. `has_done_criteria` is a PRD that names done-criteria, acceptance criteria or a rubric, or a rubric file.
+ */
+const fs = require('fs');
+const path = require('path');
+const D = require('./driver.js');
+const stageTools = require('./stage-tools.js');
+const pmItems = require('./pm-items.js');
+const itemSteps = require('./item-steps.js');
+
+const ms = (iso) => { const t = Date.parse(iso); return Number.isFinite(t) ? t : null; };
+
+function fmOf(root, rel) {
+  if (!rel) return {};
+  let text = '';
+  try { text = fs.readFileSync(path.isAbsolute(rel) ? rel : path.join(root, rel), 'utf8'); } catch { return {}; }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const out = {};
+  if (m) for (const line of m[1].split(/\r?\n/)) { const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/.exec(line); if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, ''); }
+  return out;
+}
+function doneCriteriaOf(root, fm) {
+  if (fm.rubric_path && fs.existsSync(path.join(root, fm.rubric_path))) return true;
+  if (!fm.prd_path) return false;
+  try { return /done[- ]criteria|acceptance criteria|rubric/i.test(fs.readFileSync(path.join(root, fm.prd_path), 'utf8')); } catch { return false; }
+}
+function outcomeChecked(stateDir, id) {
+  try {
+    return fs.readFileSync(path.join(stateDir, 'outcome_checks.jsonl'), 'utf8').split('\n').some((l) => { try { const c = JSON.parse(l); return c && c.initiative_id === id; } catch { return false; } });
+  } catch { return false; }
+}
+
+function initiativeFacts(w, ctx, { driverState, stateDir }) {
+  const boards = require('./routes-boards.js');
+  const got = boards.baseRows(w);
+  if (got.pending) return { pending: true };
+  if (!got.ok) return { ok: false, error: got.error };
+  const fr = boards.frameFor(ctx, w);
+  const tools = stageTools.readLedger(path.join(stateDir, stageTools.LEDGER));
+  let placed = null;
+  try { placed = require('./placements.js').readPlacements(w.root); } catch { placed = null; }
+  let jiraStatus = null;
+  try { jiraStatus = require('./jira-status.js'); } catch { jiraStatus = null; }
+  const keptEvidence = new Set();
+  for (const p of driverState.proposals.values()) if (p.state === 'kept' && p.what === 'evidence' && p.target.kind === 'initiative') keptEvidence.add(p.target.id);
+  const out = [];
+  for (const base of got.rows) {
+    if (base.status === 'done' || base.lifecycle || base.dormant) continue;
+    const boardId = boards.boardIdOf(base, fr.boards, fr.folded, w);
+    const board = fr.boards.find((b) => b.id === boardId) || fr.boards[0];
+    const row = boards.boardRow(board, base, fr.folded);
+    const fm = fmOf(w.root, base.record);
+    const rec = stageTools.recordsOf(tools, base.id);
+    let snap = null;
+    try { snap = jiraStatus ? jiraStatus.readSnapshot(w.root, base.id) : null; } catch { snap = null; }
+    const tickets = snap ? [...snap.tickets.values()] : [];
+    const resolved = tickets.map((t) => ms(t.resolved)).filter((x) => x != null);
+    out.push({
+      ws: w.id, board: board.id, id: base.id, title: base.title || base.id, cat: row.cat, active: true,
+      last_activity: ms(base.updated),
+      has_problem: !!rec.problem, has_evidence: keptEvidence.has(base.id),
+      has_prd: !!base.hasSpec, has_done_criteria: doneCriteriaOf(w.root, fm), has_anchor: !!(base.anchor && String(base.anchor).trim()),
+      has_tickets: tickets.length > 0, last_ticket_move: resolved.length ? Math.max(...resolved) : null,
+      blocked_tickets: tickets.filter((t) => t.flagged).map((t) => t.key),
+      check_by: placed && placed.ok && placed.byInit[base.id] ? placed.byInit[base.id].check_by || null : null,
+      outcome_checked: outcomeChecked(stateDir, base.id),
+      kill_tripped: !!(rec.kill && rec.kill.data && (rec.kill.data.items || []).some((i) => i.status === 'tripped')),
+    });
+  }
+  return { ok: true, list: out };
+}
+
+function workFacts(w, { runtimeDir, now }) {
+  const dir = path.join(runtimeDir, 'pm-items');
+  const items = pmItems.fold(pmItems.readLines(path.join(dir, 'items.jsonl')));
+  const steps = itemSteps.foldSteps(pmItems.readLines(path.join(dir, 'steps.jsonl')));
+  const today = new Date(Date.UTC(new Date(now).getFullYear(), new Date(now).getMonth(), new Date(now).getDate()));
+  const stale = new Set(pmItems.reviewQueue(items, new Date(now)).map((i) => i.id));
+  return items.filter((i) => !i.done).map((i) => ({
+    ws: w.id, id: i.id, title: i.title || i.id, done: false, placement: pmItems.workPlacement(i, today), due: i.due || null,
+    waiting_on: i.waiting_on || null, waiting_since: i.waiting_since || null, touched_at: i.touched_at || null,
+    untouched: stale.has(i.id), steps: (steps.byItem[i.id] || []).length,
+  }));
+}
+
+function gather(w, ctx, { now = Date.now(), includeWork = false, runtimeDir, driverState } = {}) {
+  const stateDir = ctx.stateDirFor ? ctx.stateDirFor(w) : null;
+  if (!stateDir) return { ok: false, error: 'no state folder' };
+  const facts = { day: D.localDay(now), now, initiatives: [], work: [] };
+  const ini = initiativeFacts(w, ctx, { driverState: driverState || D.fold([]), stateDir });
+  if (ini.pending) return { pending: true };
+  if (ini.ok === false) return ini;
+  facts.initiatives = ini.list;
+  if (includeWork) {
+    try { facts.work = workFacts(w, { runtimeDir, now }); } catch (e) { return { ok: false, error: `the Work items could not be read: ${String((e && e.message) || e).slice(0, 120)}` }; }
+  }
+  return { ok: true, facts };
+}
+
+module.exports = { gather, initiativeFacts, workFacts };

package/workspace/lib/driver-needs.js

@@ -0,0 +1,107 @@
+'use strict';
+/* driver-needs.js — the needs provider of the Initiative Driver (initiative initiative-driver, PRD sections 3 to 5).
+ * lib/needs-providers.js folds these rows into server.js deriveNeeds, and from there into /api/needs and Today.
+ *
+ *   kinds: driver-drafts, driver-blocked
+ *   rowsFor(w, { lead }) → rows · sig(w) → string · titlesOf(w) · rowsOf(state, { titleOf, now, ledgerRel })
+ *
+ *   driver-drafts   one row per initiative or Work task with open proposals: "Agent has 3 drafts on <title>".
+ *   driver-blocked  one row for a target the PM is blocking: its drafts have waited more than a day, and today's sweep raised
+ *                   the finding again. The sweep starts no run for it; the row is the reminder.
+ *
+ * SHADOW MODE raises no row (PRD section 5): the board mode, taken from the board of the target's latest run, decides. The
+ * rows are repository-wide, so a tree that is not the lead returns []. A row never carries a session token.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const D = require('./driver.js');
+
+const NAME = 'driver-needs';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const KIND_WORD = { initiative: 'the initiative', work: 'the Work task' };
+
+/** Titles for the targets of a workspace: initiative titles from the cached workflow rows, Work titles from the Work items. */
+function titlesOf(w) {
+  const out = new Map();
+  try {
+    const r = require('./initiative-rows.js').peek(w.root);
+    if (r && r.ok) for (const x of r.rows) out.set(`initiative:${x.id}`, x.title || x.id);
+  } catch { /* the id stands in */ }
+  try {
+    const pmItems = require('./pm-items.js');
+    const f = path.join(require('./state-root.js').defaultRoot(), 'pm-items', 'items.jsonl');
+    for (const i of pmItems.fold(pmItems.readLines(f))) out.set(`work:${i.id}`, i.title || i.id);
+  } catch { /* the id stands in */ }
+  return out;
+}
+
+function rowsOf(state, { titleOf = () => null, now = Date.now(), ledgerRel = 'pmos/state/driver.jsonl' } = {}) {
+  const rows = [];
+  const open = new Map();
+  for (const p of D.openProposals(state)) {
+    const k = D.targetKey(p.target);
+    if (!open.has(k)) open.set(k, { target: p.target, list: [] });
+    open.get(k).list.push(p);
+  }
+  const shadow = (target) => {
+    let board = target.kind === 'work' ? 'work' : null;
+    if (target.kind !== 'work') {
+      const runs = [...state.runs.values()].filter((r) => D.targetKey(r.target) === D.targetKey(target) && r.board);
+      if (runs.length) board = runs[runs.length - 1].board;
+    }
+    return D.modeOf(state, board) === 'shadow';
+  };
+  for (const [k, g] of open) {
+    if (shadow(g.target)) continue;
+    const title = titleOf(g.target) || g.target.id;
+    const whats = [...new Set(g.list.map((p) => p.what))].join(', ');
+    rows.push({
+      run_id: `${NAME}:drafts:${k}`, kind: 'driver-drafts', initiative_id: g.target.kind === 'initiative' ? g.target.id : null,
+      question: `Agent has ${plural(g.list.length, 'draft', 'drafts')} on ${title}`, doc: null,
+      today: { kind: 7, source: NAME, cause: `The agent filed ${plural(g.list.length, 'draft', 'drafts')} for ${KIND_WORD[g.target.kind]}: ${whats}`, evidence: ledgerRel, act: { label: 'Review', cli: null } },
+    });
+  }
+  const today = D.localDay(now);
+  const seen = new Set();
+  for (const b of state.blockers) {
+    if (b.owner !== 'pm' || b.day !== today || !b.target) continue;
+    const k = D.targetKey(b.target);
+    if (seen.has(k) || !open.has(k) || shadow(b.target)) continue;
+    const g = open.get(k);
+    const oldest = g.list.map((p) => Date.parse(p.at)).filter(Number.isFinite).sort((a, c) => a - c)[0];
+    if (!(now - oldest >= D.PM_WAIT_MS)) continue;
+    seen.add(k);
+    const days = Math.max(1, Math.floor((now - oldest) / D.DAY));
+    const title = titleOf(g.target) || g.target.id;
+    rows.push({
+      run_id: `${NAME}:blocked:${k}`, kind: 'driver-blocked', initiative_id: g.target.kind === 'initiative' ? g.target.id : null,
+      question: `${title} is waiting on you: the drafts are ${plural(days, 'day', 'days')} old`, doc: null,
+      today: { kind: 7, source: NAME, cause: 'The agent starts no new run on this until you keep, send back or drop its drafts', evidence: ledgerRel, act: { label: 'Review', cli: null } },
+    });
+  }
+  return rows;
+}
+
+function rowsFor(w, { lead } = {}) {
+  if (!lead || !w || !w.root) return [];
+  const dir = D.stateDirOf(w.root);
+  if (!dir) return [];
+  const file = D.ledgerFile(dir);
+  const state = D.fold(D.readLines(file));
+  if (!state.proposals.size) return [];
+  const titles = titlesOf(w);
+  let rel = 'driver.jsonl';
+  try { rel = path.relative(w.root, file).split(path.sep).join('/'); } catch { /* the plain name stands */ }
+  return rowsOf(state, { titleOf: (t) => titles.get(`${t.kind}:${t.id}`) || null, now: Date.now(), ledgerRel: rel });
+}
+
+function sig(w) {
+  if (!w || !w.root) return 'none';
+  const dir = D.stateDirOf(w.root);
+  let st = 'none';
+  try { const s = fs.statSync(D.ledgerFile(dir)); st = `${s.size}:${s.mtimeMs}:${s.ino}`; } catch { /* no ledger yet */ }
+  return crypto.createHash('sha1').update(`${st}|${D.localDay(Date.now())}`).digest('hex');
+}
+
+module.exports = { kinds: ['driver-drafts', 'driver-blocked'], rowsFor, sig, titlesOf, rowsOf };