create-pmos 0.167.0 → 0.169.0

package/workspace/extension/panel.js

@@ -0,0 +1,67 @@
+/* panel.js — the page the content script frames over a Meet call (panel.html).
+ * It reads the PMOS address from chrome.storage.sync (pmosAddress, default http://localhost:7433) and asks whether anything answers there.
+ * When PMOS answers, the page becomes one frame: ${address}/c3.html?focus=now&pop=1&meet=…&mtitle=… (PMOS's compact meeting focus). When it does not,
+ * the page says where it looked and links to the options. Nothing else is fetched. The frame's { pmosFocus } message (fold or open, no data) is passed
+ * up to the content script. */
+(function () {
+  'use strict';
+  var A = window.PMOS_ADDRESS;
+  var CHECK_MS = 4000;     // how long to wait for PMOS to answer
+  var RETRY_MS = 5000;     // looked again while it does not answer, so a PMOS started later fills the panel
+  var MEET_ORIGIN = 'https://meet.google.com';
+  var params = new URLSearchParams(location.search);
+  var meet = params.get('meet') || '';
+  var title = params.get('title') || '';
+  var msg = document.getElementById('msg');
+  var frame = null;
+  var frameOrigin = '';
+  var timer = null;
+
+  function readAddress(done) {
+    var fallback = A.DEFAULT_ADDRESS;
+    try {
+      var o = {}; o[A.KEY] = fallback;
+      chrome.storage.sync.get(o, function (v) { done(A.normalizeAddress(v && v[A.KEY]) || fallback); });
+    } catch (e) { done(fallback); }
+  }
+  /** Resolves when something answers at the address (an opaque no-cors reply is enough), rejects when nothing listens. */
+  function answers(addr) {
+    var ctl = typeof AbortController === 'function' ? new AbortController() : null;
+    var t = ctl ? setTimeout(function () { ctl.abort(); }, CHECK_MS) : null;
+    return fetch(addr + '/c3.html', { mode: 'no-cors', cache: 'no-store', signal: ctl ? ctl.signal : undefined })
+      .then(function (r) { if (t) clearTimeout(t); return r; }, function (e) { if (t) clearTimeout(t); throw e; });
+  }
+  function showMissing(addr) {
+    msg.textContent = '';
+    msg.className = 'msg';
+    msg.appendChild(document.createTextNode('PMOS is not running at ' + addr + '. '));
+    var a = document.createElement('a');
+    a.href = '#';
+    a.textContent = 'Set the address';
+    a.addEventListener('click', function (e) { e.preventDefault(); try { chrome.runtime.openOptionsPage(); } catch (x) { /* no options page */ } });
+    msg.appendChild(a);
+    msg.appendChild(document.createTextNode('.'));
+  }
+  function showFrame(addr) {
+    var q = new URLSearchParams({ focus: 'now', pop: '1', meet: meet, mtitle: title });
+    frame = document.createElement('iframe');
+    frame.title = 'PMOS meeting helper';
+    frame.src = addr + '/c3.html?' + q.toString();
+    frameOrigin = new URL(addr).origin;
+    msg.remove();
+    document.body.appendChild(frame);
+  }
+  function start() {
+    readAddress(function (addr) {
+      answers(addr).then(function () { showFrame(addr); }, function () { showMissing(addr); timer = setTimeout(start, RETRY_MS); });
+    });
+  }
+
+  window.addEventListener('message', function (e) {
+    if (!frame || e.source !== frame.contentWindow || e.origin !== frameOrigin) return;
+    var m = e.data && e.data.pmosFocus;
+    if (m !== 'fold' && m !== 'open') return;
+    if (window.parent !== window) window.parent.postMessage({ pmosFocus: m }, MEET_ORIGIN);
+  });
+  start();
+})();

package/workspace/guide/console-calendar.md

@@ -137,6 +137,20 @@ To fix the topic, press **Topics**. Press **Not this topic** and pick the topic
 
 The companion starts only while the meeting is recorded. It reads the new lines of the transcript at most every 40 seconds. It writes the sentence, the chips, the topic and the notes. If the answer is not usable, PMOS drops it and shows nothing. To stop the companion, set `PMOS_FOCUS_AGENT` to `off`. The page then shows the transcript and a quiet line, and it adds no notes. In the last 5 minutes, and after the meeting, the page shows the captured items under the material. You confirm them in the note after the meeting. Nothing goes to other people.
 
+### Meeting focus over Google Meet
+
+The PMOS Chrome extension shows a small panel over a Google Meet call, so you do not need to switch to the PMOS tab. The panel is the Meeting focus page in a compact form. It has a head with the topic the room is on (or "Starts in" before the start) and the time left, the **What's being said** line, the conversation with PMOS, and **Ask PMOS quietly**. Only you see it. It is not part of the screen you share. The extension reads the address and the title of the Meet tab only. It does not read the call's audio or captions, and it talks only to the PMOS on your computer.
+
+To add the extension:
+
+1. Run `pmos extension`. It prints the folder of the extension and these steps.
+2. In Chrome, open `chrome://extensions` and turn on **Developer mode**.
+3. Press **Load unpacked** and pick the folder that `pmos extension` printed.
+
+PMOS must run while you use the panel. The extension looks for PMOS at `http://localhost:7433`. If `pmos` started on another port, open the extension's **Options**, type that address and press **Save**, then reload the Meet tab.
+
+To use it, open a Meet call. The panel shows at the bottom right of the call, and not on the Meet home page. PMOS finds the meeting on your calendar by the Meet link in the invite. If no invite has that link, it uses the title of the tab, and then the meeting that is under way now (from 10 minutes before the start to 10 minutes after the end). If none fits, the panel says "No meeting right now" and lists today's meetings. Press the one this call is. **Fold** shrinks the panel to a pill that shows the head only, and the same button opens it again. **Open focus in PMOS** opens the full Meeting focus page in a new tab, with the material, the topics and the captured items. If PMOS does not answer, the panel says "PMOS is not running at" and the address, with a link to the Options.
+
 ## Free time
 
 Press **Free time** to show the free blocks. A free block is a gap inside your working hours that is long enough to use. On Day and Week, each block is a dashed purple window on the timeline, with its length, for example "1.5 h focus". The side column lists the blocks, up to 8, with the suggestion for each. On Month, Quarter and Year the list says that free time shows in the Day and Week views, and the chip still shows the number of blocks.

package/workspace/guide/index.md

@@ -61,6 +61,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.
 - [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
 - [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
+- [The Initiative Driver: drafts the agent files for you](initiative-driver.md): when the driver runs, the unblock sweep, the limits, Keep, Send back and Drop, the board modes, and `pmos driver`.
 - [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
 - [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.
 - [Breakdown › Timeline](timeline.md): an initiative's items on a time axis, split by stage, with milestones, today, and the at-risk flag when an item starts before its predecessor ends.

package/workspace/guide/initiative-driver.md

@@ -0,0 +1,87 @@
+---
+type: Guide
+title: "The Initiative Driver: drafts the agent files for you"
+description: "What the Initiative Driver does when an initiative is created or moved, what stops it, how it files proposals you keep, send back or drop, the board modes, and the pmos driver commands."
+timestamp: 2026-10-12
+---
+
+# The Initiative Driver: drafts the agent files for you
+
+The Initiative Driver is a short background agent run for one initiative or one Work task. It reads the record, decides the next useful step, files the result as a **proposal**, and ends. It never decides for you. You keep a proposal, send it back with a note, or drop it.
+
+## When a run starts
+
+A run starts for one of four reasons:
+
+- **Created.** An initiative is created from the page, from Triage (accept), or with `pmos initiative new`. The run starts within one tick of the server (about one minute).
+- **Moved.** You move the initiative to another stage on the board.
+- **Answered.** You send a proposal back with a note.
+- **Stuck.** The unblock sweep finds a blocker the agent can work on.
+
+An initiative that existed before you first ran this version does not start a run. Only events after the first scan count.
+
+## The unblock sweep
+
+The sweep reads every active initiative and every open Work task. It uses no model. It runs every 30 minutes, inside the working hours of the daytime check (09:00 to 18:00 by default) and outside your quiet hours.
+
+| Where | What it finds |
+| --- | --- |
+| You are the blocker | An open proposal is more than one day old. No run starts. The row comes back in Needs you once a day. |
+| Discover | No kept problem statement, or no kept evidence. |
+| Plan | No PRD, no done-criteria, or no anchor. |
+| Do | No Jira ticket moved for the stall threshold, or a ticket is flagged blocked. |
+| Learn | The check-by date passed with no outcome check, or a kill condition tripped. |
+| Any stage | Nothing changed for the stall threshold (5 days by default). |
+| Work task | Overdue, waiting on someone for 3 days or more, untouched for 7 days, or no next step. |
+
+The sweep starts a run for a blocker the agent can work on, at most once per blocker per day. A dormant initiative starts no run.
+
+## The limits
+
+- At most 3 runs per initiative per day, and 1 per Work task per day.
+- At most 3 runs at the same time. The others wait.
+- A run that fails or times out counts against the day. Its reason is in the ledger.
+- A paused initiative or Work task starts no run.
+- `PMOS_DRIVER=off` in the environment of the server starts none.
+
+## What the agent can and cannot do
+
+The agent reads, and it files proposals with `pmos driver propose`. It has no Write or Edit tool, no `git push`, and no tool that sends anything. Every claim in a proposal carries a pointer: a Jira key, a link or a path. A follow-up to a person is draft text only. You send it from your own session.
+
+In Discover, the agent writes the problem statement, the evidence, the opportunity sizing, the riskiest assumption and the stakeholders. When you have kept the first three, it proposes the move to Plan. In the other stages, it names the blocker and proposes what would clear it.
+
+## Where you see the agent
+
+- **The Agent strip.** Open an initiative and stay on Overview. The Agent section is at the top. It shows the state of the agent (working, idle, waiting on you, paused or off), the last thing it did, and what stops it ("Stopped by: ..."). Each open proposal is one row with Keep, Send back and Drop. Press a row to read its text and its sources. A source that is a link opens in a new tab. Pause and Resume are in the header. The text "1 of 3 runs used today" opens the list of today's runs.
+- **Keep, Send back and Drop on a row.** A kept row stays in the strip, marked "Kept by you", until you leave the page. Send back asks for a one-line note. A kept stage move changes the stage on the page at once. These three acts cannot be undone: each adds one line to the ledger.
+- **One line in Work.** A Work task with an open proposal shows one line under its title, for example "Agent drafted a follow-up to Dana. Nothing is sent." Press Review to read the draft. Keep copies the text so you can send it yourself, and records your decision. If the browser does not allow copying, the text is selected and you press Ctrl+C. A suggested next step shows Keep and Drop in the line. Shadow and Off show no line.
+- **Needs you.** In Briefing, the agent has two kinds of row: "Agent has 3 drafts on ..." and "... is waiting on you". Press a row to open the initiative.
+- **The Agent setting.** Open the board, press Board settings, and find Agent. Choose Off, Shadow or Approve. The setting is saved when you press it.
+
+## Keep, send back, drop
+
+Open proposals appear in Needs you as one row for each initiative or task: "Agent has 3 drafts on the initiative".
+
+- **Keep** writes the record as you. A problem statement goes into the problem record of the initiative. A move goes through the board move, with its warnings. A Work next step goes into the steps of the task. Other kinds are kept as your decision to rely on them.
+- **Send back** needs a note. The note starts a new run. It counts as a correction.
+- **Drop** closes the proposal. It counts as a correction.
+
+The agent cannot keep, send back, drop, pause or change the mode. Those acts need your page or your terminal.
+
+## Board modes
+
+- **Approve** is the default. The agent runs and drafts, and Needs you shows the rows.
+- **Shadow.** The agent runs and drafts, and raises no Needs you rows.
+- **Off.** No run starts.
+
+## The commands
+
+The agent uses `pmos driver propose` to file a proposal and `pmos driver status` to read what exists. The other commands are yours, at an interactive terminal:
+
+- `pmos driver keep <proposal>` asks you to type the proposal id. A kept move is pressed on the page.
+- `pmos driver return <proposal> --note "<what to change>"` sends it back.
+- `pmos driver drop <proposal>` drops it.
+- `pmos driver pause <initiative|work> <id>` and `pmos driver resume <initiative|work> <id>` stop and restart the runs for one target.
+- `pmos driver mode <off|shadow|approve> [--board <id>]` sets the board mode. Without `--board` it sets every board.
+
+The ledger is `driver.jsonl` in the state folder of the repository (`pmos/state`, `state` or `.pmos`). Each action adds one line. Nothing is changed or removed.

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 };