create-pmos 0.167.0 → 0.169.0

package/workspace/lib/driver.js

@@ -0,0 +1,408 @@
+'use strict';
+/* driver.js — the Initiative Driver's ledger and rules (initiative initiative-driver, PRD sections 1 to 5).
+ *
+ * The driver is a short headless run for one initiative or one Work task. It reads the record, files what it found as
+ * PROPOSALS, and ends. The PM keeps, sends back or drops each proposal. This file is the pure core: the shape of every
+ * line in <state folder>/driver.jsonl, the fold, the budget, the modes, the wake queue and the unblock sweep. It reads the
+ * clock only through the `now` its callers pass. The only I/O is the thin read/append pair at the bottom.
+ *
+ *   LEDGER · KINDS · WHATS · MODES · DEFAULT_MODE · WAKES · BUDGET
+ *   stateDirOf(root, { create })        → the repository's state folder (pmos/state, state or .pmos), else null
+ *   ledgerFile(stateDir)                → <state folder>/driver.jsonl
+ *   append(file, line, { now })         → the line written. THE SINGLE WRITER of driver.jsonl.
+ *   readLines(file)                     → every line that parses, in file order
+ *   checkProposal(input)                → { ok, proposal } | { ok: false, error }   the shape of one proposal
+ *   fold(lines)                         → the current state (proposals, decisions, runs, wakes, pauses, modes, blockers)
+ *   modeOf(state, board) · isPaused(state, target) · openProposals(state, target?)
+ *   admit(state, { target, board }, { now, running }) → { ok } | { ok: false, refuse: reason } | { ok: false, wait: reason }
+ *   plan(state, { now, running })       → { start: [{ target, board, wakes[] }], refused: [{ target, wakes[], reason }] }
+ *   detect(facts, state, { now, stalledDays }) → the blockers, each { key, target, board, title, code, owner, cat, text }
+ *   sweepLines(facts, state, { now, stalledDays }) → { blockers, lines } the lines to append (once per blocker per day)
+ *   wakesFromLedgers({ created, moved }, state, { ws, epoch }) → wake lines for creations and moves not yet woken
+ *   answeredWakes(state)                → wake lines for proposals the PM sent back with a note
+ *   localDay(ms) · targetKey(target) · wsIdOf(root)
+ *
+ * THE LINES. Every line is { v: 1, ev, …, at }. Who wrote a decision is the call path (lib/actor.js), never a field:
+ *   proposal   { id, target: { kind, ws, id }, what, data, why, sources: [{ label, ref }], run, by }   by an agent session
+ *   keep|return|drop  { proposal, note?, by }           PM only: the fold ignores one whose `by` is not pm:*
+ *   correction { proposal, run, kind: 'return'|'drop', by }   one per return or drop; the north star counts it
+ *   pause|resume { target, by } · mode { board, mode, by }     PM only, as above. `board` '*' is every board.
+ *   wake       { key, target, board, reason: created|moved|answered|stuck, blocker? }   queued: a run should start
+ *   run-start  { run, target, board, wakes: [key], session }   one per run; counts against the day's budget
+ *   run-end    { run, ok, reason?, agent_run }                  agent_run is the run record the correction rate reads
+ *   refused    { target, wakes: [key], reason }                 a wake the rules turned away, recorded
+ *   blocker    { key, day, target, board, code, owner: 'pm'|'agent', text }   the sweep's finding, once per key per day
+ *   epoch      { }                                              the first scan of this ledger: older events do not wake
+ *
+ * BUDGET (PM decision 4): 3 runs per initiative per local day, 1 per Work task per day, 3 at once, no daily total. A run
+ * that fails or times out still counts. A wake the budget turns away is recorded as `refused`; a wake that only waits for
+ * a free slot stays queued. Several wakes of one target are answered by ONE run.
+ *
+ * THE FACTORY NEVER WRITES HERE (D65): the CLI and the routes pass the actor from the call path. This ledger is not an
+ * initiative record, an acceptance, an anchor or a stage move; Keep writes those through their own writers.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const LEDGER = 'driver.jsonl';
+const KINDS = Object.freeze(['initiative', 'work']);
+const WHATS = Object.freeze({
+  initiative: Object.freeze(['problem', 'evidence', 'sizing', 'assumption', 'stakeholders', 'move', 'note']),
+  work: Object.freeze(['next-step', 'follow-up', 'note']),
+});
+// A claim without a pointer is not a proposal (PRD section 2: "Nothing without a pointer").
+const NEEDS_SOURCE = Object.freeze(['evidence', 'sizing', 'assumption', 'stakeholders']);
+const MODES = Object.freeze(['off', 'shadow', 'approve']);
+const DEFAULT_MODE = 'approve';
+const WAKES = Object.freeze(['created', 'moved', 'answered', 'stuck']);
+const EVENTS = Object.freeze(['proposal', 'keep', 'return', 'drop', 'correction', 'pause', 'resume', 'mode', 'wake', 'run-start', 'run-end', 'refused', 'blocker', 'epoch']);
+const BUDGET = Object.freeze({ initiativePerDay: 3, workPerDay: 1, concurrent: 3 });
+const DAY = 86400000;
+const PM_WAIT_MS = DAY;                 // an open proposal older than this makes the PM the blocker
+const SWEEP_EVERY_MS = 30 * 60 * 1000;  // the sweep's cadence inside the day-check window
+const DEFAULT_STALLED_DAYS = 5;
+const WORK_WAIT_DAYS = 3;
+const WORK_UNTOUCHED_DAYS = 7;          // lib/pm-items.js REVIEW_DAYS
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const WS_RE = /^[A-Za-z0-9._-]{1,80}$/;
+const PROPOSAL_RE = /^p-[0-9a-f]{10}$/;
+const RUN_RE = /^run-[0-9a-f]{10}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_DATA = 8000;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const oneLine = (v, max) => typeof v === 'string' && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n\x00-\x08\x0b-\x1f]/.test(v);
+const pm = (by) => typeof by === 'string' && by.startsWith('pm:');
+
+const targetKey = (t) => `${t.kind}:${t.ws}:${t.id}`;
+const wsIdOf = (root) => crypto.createHash('sha1').update(path.resolve(root)).digest('hex').slice(0, 10);
+/** The local calendar day of a time in ms, YYYY-MM-DD. The budget counts per local day. */
+function localDay(ms) {
+  const d = new Date(ms);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+// ── where the ledger lives ───────────────────────────────────────────────────────────────────────────
+const isDir = (d) => { try { return fs.statSync(d).isDirectory(); } catch { return false; } };
+/** The repository's state folder, by the rule server.js stateDirFor uses; the checkout this file ships in falls back to
+ * workspace/state, as the server does for PMOS-self. Null when there is none (and `create` is off). */
+function stateDirOf(root, { create = false } = {}) {
+  if (!root) return null;
+  for (const rel of [['pmos', 'state'], ['state'], ['.pmos']]) {
+    const d = path.join(root, ...rel);
+    if (isDir(d)) return d;
+  }
+  if (path.resolve(root) === path.resolve(__dirname, '..', '..') && isDir(path.join(__dirname, '..', 'state'))) return path.join(__dirname, '..', 'state');
+  if (create) {
+    const d = path.join(root, 'pmos', 'state');
+    try { fs.mkdirSync(d, { recursive: true }); return d; } catch { return null; }
+  }
+  return null;
+}
+const ledgerFile = (stateDir) => (stateDir ? path.join(stateDir, LEDGER) : null);
+
+// ── the one writer, and the read ─────────────────────────────────────────────────────────────────────
+/** THE SINGLE WRITER of driver.jsonl. `v` and `at` are set here; a caller never chooses them. */
+function append(file, line, { now } = {}) {
+  if (!file) throw new Error('driver: no ledger file');
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`driver: unknown event ${JSON.stringify(line && line.ev)}`);
+  const out = { ...line, v: 1, at: new Date(now == null ? Date.now() : now).toISOString() };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(out) + '\n');
+  return out;
+}
+function readLines(file) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (!raw.trim()) continue;
+    try { const l = JSON.parse(raw); if (isObj(l) && EVENTS.includes(l.ev)) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+const newId = (prefix) => `${prefix}-${crypto.randomBytes(5).toString('hex')}`;
+
+// ── a proposal ───────────────────────────────────────────────────────────────────────────────────────
+function checkTarget(t) {
+  if (!isObj(t)) return { ok: false, error: 'target must be { kind, ws, id }' };
+  if (!KINDS.includes(t.kind)) return { ok: false, error: `target kind must be one of ${KINDS.join(', ')}` };
+  if (typeof t.ws !== 'string' || !WS_RE.test(t.ws)) return { ok: false, error: 'target ws must be a workspace id' };
+  if (typeof t.id !== 'string' || !ID_RE.test(t.id)) return { ok: false, error: 'target id must be an initiative or Work task id (letters, digits, . _ -)' };
+  return { ok: true, target: { kind: t.kind, ws: t.ws, id: t.id } };
+}
+
+/** The shape of one proposal as an agent files it. Returns the line fields the writer adds `id`, `run`, `by` to. */
+function checkProposal(input) {
+  const i = isObj(input) ? input : {};
+  const t = checkTarget({ kind: i.kind, ws: i.ws, id: i.id });
+  if (!t.ok) return t;
+  if (!WHATS[t.target.kind].includes(i.what)) return { ok: false, error: `what must be one of ${WHATS[t.target.kind].join(', ')} for ${t.target.kind === 'work' ? 'a Work task' : 'an initiative'}` };
+  if (!oneLine(i.why, 500)) return { ok: false, error: 'why is one line of 1 to 500 characters' };
+  let data = i.data;
+  if (typeof data === 'string') data = { text: data };
+  if (!isObj(data)) return { ok: false, error: 'data must be an object or text' };
+  if (JSON.stringify(data).length > MAX_DATA) return { ok: false, error: `data is too long (at most ${MAX_DATA} characters)` };
+  const sources = [];
+  if (i.sources !== undefined && i.sources !== null) {
+    if (!Array.isArray(i.sources) || i.sources.length > 20) return { ok: false, error: 'sources is a list of at most 20 { label, ref }' };
+    for (const s of i.sources) {
+      if (!isObj(s) || !oneLine(s.label, 80) || !oneLine(s.ref, 500)) return { ok: false, error: 'each source needs a label (up to 80 characters) and a ref (a Jira key, link or path, up to 500)' };
+      sources.push({ label: s.label.trim(), ref: s.ref.trim() });
+    }
+  }
+  if (NEEDS_SOURCE.includes(i.what) && !sources.length) return { ok: false, error: `${/^[aeiou]/.test(i.what) ? 'an' : 'a'} ${i.what} proposal needs at least one source with a pointer (--source label=ref); nothing without a pointer` };
+  if (i.what === 'evidence' && Array.isArray(data.items) && data.items.some((x) => !isObj(x) || !oneLine(x.text, 500) || !oneLine(x.ref, 500))) {
+    return { ok: false, error: 'every evidence item needs text and a ref (the pointer to where you read it)' };
+  }
+  if (i.what === 'problem') {
+    const c = require('./stage-tools.js').checkData('problem', { text: data.text });
+    if (!c.ok) return { ok: false, error: c.error };
+    data = { text: c.data.text };
+  } else if (i.what === 'move') {
+    if (!oneLine(data.to, 120)) return { ok: false, error: 'a move needs data.to: the name of the stage' };
+    data = { to: data.to.trim(), ...(oneLine(data.board, 120) ? { board: data.board.trim() } : {}) };
+  } else if (i.what === 'next-step') {
+    if (!oneLine(data.text, 500)) return { ok: false, error: 'a next step needs data.text: one line of up to 500 characters' };
+    if (data.due != null && !(typeof data.due === 'string' && DATE_RE.test(data.due))) return { ok: false, error: 'data.due is YYYY-MM-DD' };
+    data = { text: data.text.trim(), ...(data.due ? { due: data.due } : {}) };
+  }
+  return { ok: true, proposal: { target: t.target, what: i.what, data, why: i.why.trim(), sources } };
+}
+
+// ── the fold ─────────────────────────────────────────────────────────────────────────────────────────
+function emptyState() {
+  return { epoch: null, proposals: new Map(), order: [], paused: new Map(), modes: new Map(), runs: new Map(), bySession: new Map(),
+    wakes: [], wakeKeys: new Set(), blockers: [], blockerDays: new Set(), refusals: [], corrections: [] };
+}
+
+/** The current state of one ledger. Order matters only inside a kind; a decision line from anything but the PM is ignored. */
+function fold(lines) {
+  const s = emptyState();
+  const wakeBy = new Map();
+  for (const l of lines || []) {
+    if (!isObj(l)) continue;
+    switch (l.ev) {
+      case 'epoch': if (!s.epoch) s.epoch = l.at || null; break;
+      case 'proposal': {
+        if (!PROPOSAL_RE.test(String(l.id)) || s.proposals.has(l.id) || !checkTarget(l.target).ok) break;
+        s.proposals.set(l.id, { id: l.id, target: { kind: l.target.kind, ws: l.target.ws, id: l.target.id }, what: l.what, data: l.data, why: l.why,
+          sources: Array.isArray(l.sources) ? l.sources : [], run: l.run || null, by: l.by || null, at: l.at || null, state: 'open', note: null, decided_at: null, decided_by: null });
+        s.order.push(l.id);
+        break;
+      }
+      case 'keep': case 'return': case 'drop': {
+        const p = s.proposals.get(l.proposal);
+        if (!p || p.state !== 'open' || !pm(l.by)) break;
+        p.state = l.ev === 'keep' ? 'kept' : l.ev === 'return' ? 'returned' : 'dropped';
+        p.note = typeof l.note === 'string' && l.note ? l.note : null; p.decided_at = l.at || null; p.decided_by = l.by;
+        break;
+      }
+      case 'correction': s.corrections.push({ proposal: l.proposal || null, run: l.run || null, kind: l.kind, at: l.at || null }); break;
+      case 'pause': case 'resume': if (pm(l.by) && checkTarget(l.target).ok) s.paused.set(targetKey(l.target), l.ev === 'pause'); break;
+      case 'mode': if (pm(l.by) && MODES.includes(l.mode) && typeof l.board === 'string' && l.board) s.modes.set(l.board, l.mode); break;
+      case 'wake': {
+        if (typeof l.key !== 'string' || s.wakeKeys.has(l.key) || !checkTarget(l.target).ok) break;
+        s.wakeKeys.add(l.key);
+        const w = { key: l.key, target: l.target, board: l.board || null, reason: l.reason, blocker: l.blocker || null, at: l.at || null, state: 'queued' };
+        s.wakes.push(w); wakeBy.set(l.key, w);
+        break;
+      }
+      case 'run-start': {
+        if (typeof l.run !== 'string' || s.runs.has(l.run) || !checkTarget(l.target).ok) break;
+        const r = { run: l.run, target: l.target, board: l.board || null, wakes: Array.isArray(l.wakes) ? l.wakes : [], session: l.session || null, start: l.at || null, end: null, ok: null, reason: null, agent_run: null };
+        s.runs.set(l.run, r);
+        if (r.session) s.bySession.set(String(r.session).replace(/\.[0-9a-f]{8}$/, ''), l.run);
+        for (const k of r.wakes) { const w = wakeBy.get(k); if (w) w.state = 'started'; }
+        break;
+      }
+      case 'run-end': {
+        const r = s.runs.get(l.run);
+        if (!r || r.end) break;
+        r.end = l.at || null; r.ok = l.ok === true; r.reason = typeof l.reason === 'string' ? l.reason : null; r.agent_run = isObj(l.agent_run) ? l.agent_run : null;
+        break;
+      }
+      case 'refused': {
+        s.refusals.push({ target: l.target, wakes: l.wakes || [], reason: l.reason, at: l.at || null });
+        for (const k of l.wakes || []) { const w = wakeBy.get(k); if (w) w.state = 'refused'; }
+        break;
+      }
+      case 'blocker': if (typeof l.key === 'string' && typeof l.day === 'string') { s.blockers.push(l); s.blockerDays.add(`${l.key}|${l.day}`); } break;
+      default: break;
+    }
+  }
+  return s;
+}
+
+const modeOf = (state, board) => (board && state.modes.get(board)) || state.modes.get('*') || DEFAULT_MODE;
+const isPaused = (state, target) => state.paused.get(targetKey(target)) === true;
+function openProposals(state, target) {
+  const want = target ? targetKey(target) : null;
+  return state.order.map((id) => state.proposals.get(id)).filter((p) => p.state === 'open' && (!want || targetKey(p.target) === want));
+}
+const runsOnDay = (state, target, day) => [...state.runs.values()].filter((r) => targetKey(r.target) === targetKey(target) && r.start && localDay(Date.parse(r.start)) === day).length;
+const budgetFor = (target) => (target.kind === 'work' ? BUDGET.workPerDay : BUDGET.initiativePerDay);
+
+/** May a run start for this target now? `running` is the number of driver runs alive. A closed rule refuses (and the
+ * caller records it); a full house only waits. */
+function admit(state, { target, board }, { now, running = 0 } = {}) {
+  if (modeOf(state, board) === 'off') return { ok: false, refuse: 'mode-off' };
+  if (isPaused(state, target)) return { ok: false, refuse: 'paused' };
+  if (runsOnDay(state, target, localDay(now)) >= budgetFor(target)) return { ok: false, refuse: 'budget' };
+  if (running >= BUDGET.concurrent) return { ok: false, wait: 'concurrency' };
+  return { ok: true };
+}
+
+/** What to do with the queued wakes now. Wakes of one target are answered by one run. `running` counts the runs alive;
+ * `activeTargets` (target keys) holds the targets that have one, so a target never has two at once. */
+function plan(state, { now, running = 0, activeTargets = [] } = {}) {
+  const groups = new Map();
+  for (const w of state.wakes) {
+    if (w.state !== 'queued') continue;
+    const k = targetKey(w.target);
+    if (!groups.has(k)) groups.set(k, { target: w.target, board: w.board, wakes: [] });
+    groups.get(k).wakes.push(w.key);
+  }
+  const start = []; const refused = [];
+  const active = new Set(activeTargets);
+  // Plan on a scratch copy of the run counts so four wakes of one target never plan four runs.
+  const planned = new Map();
+  let live = running;
+  for (const g of groups.values()) {
+    if (active.has(targetKey(g.target))) continue;
+    const verdict = admit(state, g, { now, running: live });
+    if (verdict.refuse) { refused.push({ target: g.target, wakes: g.wakes, reason: verdict.refuse }); continue; }
+    if (verdict.wait) continue;
+    const day = localDay(now);
+    const used = runsOnDay(state, g.target, day) + (planned.get(targetKey(g.target)) || 0);
+    if (used >= budgetFor(g.target)) { refused.push({ target: g.target, wakes: g.wakes, reason: 'budget' }); continue; }
+    planned.set(targetKey(g.target), (planned.get(targetKey(g.target)) || 0) + 1);
+    live++;
+    start.push(g);
+  }
+  return { start, refused };
+}
+
+// ── the unblock sweep ────────────────────────────────────────────────────────────────────────────────
+/* FACTS (the server gathers them; this file never reads a repository):
+ *   facts.day            'YYYY-MM-DD', local                    facts.now   ms
+ *   facts.initiatives[]  { ws, board, id, title, cat: Discover|Plan|Do|Learn, active, last_activity (ms|null),
+ *                          has_problem, has_evidence, has_prd, has_done_criteria, has_anchor,
+ *                          has_tickets, last_ticket_move (ms|null), blocked_tickets: [key], check_by ('YYYY-MM-DD'|null),
+ *                          outcome_checked, kill_tripped }
+ *   facts.work[]         { ws, id, title, done, placement: inbox|today|upcoming|waiting|someday, due, waiting_on, waiting_since (ISO|null),
+ *                          touched_at (ISO|null), untouched (bool: the Review queue holds it), steps (count) }
+ * A blocker is { key, target, board, title, code, owner: 'pm'|'agent', cat, text }. */
+const iniKey = (i, code) => `initiative:${i.ws}:${i.id}:${code}`;
+const workKey = (w, code) => `work:${w.ws}:${w.id}:${code}`;
+
+function detect(facts, state, { now, stalledDays } = {}) {
+  const t = now == null ? facts.now : now;
+  const day = facts.day || localDay(t);
+  const stall = (stalledDays || DEFAULT_STALLED_DAYS) * DAY;
+  const out = [];
+  const add = (target, board, title, code, owner, cat, text, key) => out.push({ key, target, board, title, code, owner, cat: cat || null, text });
+  for (const i of facts.initiatives || []) {
+    if (!i || !i.active) continue;
+    const target = { kind: 'initiative', ws: i.ws, id: i.id };
+    const title = i.title || i.id;
+    const b = (code, owner, cat, text) => add(target, i.board || null, title, code, owner, cat, text, iniKey(i, code));
+    const oldest = openProposals(state, target).filter((p) => p.at && t - Date.parse(p.at) >= PM_WAIT_MS).sort((a, c) => Date.parse(a.at) - Date.parse(c.at))[0];
+    if (oldest) b('pm-open', 'pm', null, `The agent's drafts have waited on you since ${oldest.at.slice(0, 10)}`);
+    if (i.cat === 'Discover') {
+      if (!i.has_problem) b('no-problem', 'agent', 'Discover', 'No kept problem statement');
+      if (!i.has_evidence) b('no-evidence', 'agent', 'Discover', 'No evidence is kept');
+    } else if (i.cat === 'Plan') {
+      if (!i.has_prd) b('no-prd', 'agent', 'Plan', 'No PRD');
+      if (!i.has_done_criteria) b('no-done-criteria', 'agent', 'Plan', 'No done-criteria');
+      if (!i.has_anchor) b('no-anchor', 'agent', 'Plan', 'No anchor (a KR or a health budget)');
+    } else if (i.cat === 'Do') {
+      if (i.has_tickets && i.last_ticket_move != null && t - i.last_ticket_move >= stall) b('no-ticket-movement', 'agent', 'Do', `No Jira ticket moved for ${Math.floor((t - i.last_ticket_move) / DAY)} days`);
+      if (Array.isArray(i.blocked_tickets) && i.blocked_tickets.length) b('ticket-blocked', 'agent', 'Do', `Blocked ticket: ${i.blocked_tickets.join(', ')}`);
+    } else if (i.cat === 'Learn') {
+      if (i.check_by && i.check_by < day && !i.outcome_checked) b('check-by-passed', 'agent', 'Learn', `The check-by date ${i.check_by} passed with no outcome check`);
+      if (i.kill_tripped) b('kill-tripped', 'agent', 'Learn', 'A kill condition tripped');
+    }
+    if (i.last_activity != null && t - i.last_activity >= stall) b('stalled', 'agent', null, `Nothing changed for ${Math.floor((t - i.last_activity) / DAY)} days`);
+  }
+  for (const w of facts.work || []) {
+    if (!w || w.done) continue;
+    const target = { kind: 'work', ws: w.ws, id: w.id };
+    const title = w.title || w.id;
+    const b = (code, owner, text) => add(target, 'work', title, code, owner, null, text, workKey(w, code));
+    const oldest = openProposals(state, target).filter((p) => p.at && t - Date.parse(p.at) >= PM_WAIT_MS).sort((a, c) => Date.parse(a.at) - Date.parse(c.at))[0];
+    if (oldest) b('pm-open', 'pm', `The agent's drafts have waited on you since ${oldest.at.slice(0, 10)}`);
+    if (w.due && w.due < day) b('work-overdue', 'agent', `Overdue since ${w.due}`);
+    if (w.waiting_on && w.waiting_since && Number.isFinite(Date.parse(w.waiting_since)) && t - Date.parse(w.waiting_since) >= WORK_WAIT_DAYS * DAY) {
+      b('work-waiting', 'agent', `Waiting on ${w.waiting_on} for ${Math.floor((t - Date.parse(w.waiting_since)) / DAY)} days`);
+    }
+    if (w.untouched) b('work-untouched', 'agent', `Untouched for ${WORK_UNTOUCHED_DAYS} days or more`);
+    if (['today', 'upcoming', 'waiting'].includes(w.placement) && !(w.steps > 0)) b('work-no-next-step', 'agent', 'No next step');
+  }
+  return out;
+}
+
+/** The lines the sweep appends now: one `blocker` per blocker per day, and for an agent blocker one `wake`. A target the PM
+ * is blocking (an open proposal older than a day) starts no run, so its other blockers wake nothing; the pm-open blocker is
+ * written once a day, which is what raises its Needs you row again. */
+function sweepLines(facts, state, { now, stalledDays } = {}) {
+  const t = now == null ? facts.now : now;
+  const day = facts.day || localDay(t);
+  const blockers = detect(facts, state, { now: t, stalledDays });
+  const pmBlocked = new Set(blockers.filter((b) => b.owner === 'pm').map((b) => targetKey(b.target)));
+  const lines = [];
+  for (const b of blockers) {
+    if (state.blockerDays.has(`${b.key}|${day}`)) continue;
+    lines.push({ ev: 'blocker', key: b.key, day, target: b.target, board: b.board, code: b.code, owner: b.owner, text: b.text });
+    if (b.owner === 'agent' && !pmBlocked.has(targetKey(b.target))) {
+      const key = `stuck:${b.key}:${day}`;
+      if (!state.wakeKeys.has(key)) lines.push({ ev: 'wake', key, target: b.target, board: b.board, reason: 'stuck', blocker: b.code });
+    }
+  }
+  return { blockers, lines };
+}
+
+// ── the wakes ────────────────────────────────────────────────────────────────────────────────────────
+/** `created`: placements lines { ev: 'created', initiative, at }. `moved`: boards ledger lines { kind: 'move', id, to, at, board }.
+ * Only events after the ledger's epoch wake a run: the first scan of a ledger marks what already happened as history. */
+function wakesFromLedgers({ created = [], moved = [] } = {}, state, { ws, epoch, boardOf = () => null } = {}) {
+  const lines = [];
+  const after = (at) => Number.isFinite(Date.parse(at)) && Number.isFinite(Date.parse(epoch)) && Date.parse(at) >= Date.parse(epoch);
+  for (const c of created) {
+    if (!c || c.ev !== 'created' || typeof c.initiative !== 'string' || !ID_RE.test(c.initiative) || !after(c.at)) continue;
+    const key = `created:${ws}:${c.initiative}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: { kind: 'initiative', ws, id: c.initiative }, board: boardOf(c.initiative), reason: 'created' });
+  }
+  for (const m of moved) {
+    if (!m || m.kind !== 'move' || typeof m.id !== 'string' || !ID_RE.test(m.id) || !after(m.at)) continue;
+    const key = `moved:${ws}:${m.id}:${m.at}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: { kind: 'initiative', ws, id: m.id }, board: m.board || boardOf(m.id), reason: 'moved' });
+  }
+  return lines;
+}
+/** A proposal the PM sent back with a note wakes a run for its target (once per proposal). */
+function answeredWakes(state, { boardOf = () => null } = {}) {
+  const lines = [];
+  for (const p of state.proposals.values()) {
+    if (p.state !== 'returned') continue;
+    const key = `answered:${p.id}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: p.target, board: p.target.kind === 'work' ? 'work' : boardOf(p.target.id), reason: 'answered' });
+  }
+  return lines;
+}
+
+/** The run that was alive for an agent session token (its session id part), or null. */
+function runOfSession(state, token) {
+  if (typeof token !== 'string') return null;
+  return state.bySession.get(token.replace(/\.[0-9a-f]{8}$/, '')) || null;
+}
+
+module.exports = {
+  LEDGER, KINDS, WHATS, NEEDS_SOURCE, MODES, DEFAULT_MODE, WAKES, EVENTS, BUDGET, DAY, PM_WAIT_MS, SWEEP_EVERY_MS, DEFAULT_STALLED_DAYS, ID_RE, WS_RE, PROPOSAL_RE, RUN_RE,
+  stateDirOf, ledgerFile, append, readLines, newId, checkTarget, checkProposal, fold, modeOf, isPaused, openProposals, runsOnDay, admit, plan,
+  detect, sweepLines, wakesFromLedgers, answeredWakes, runOfSession, localDay, targetKey, wsIdOf,
+};

package/workspace/lib/extension-cli.js

@@ -0,0 +1,39 @@
+'use strict';
+/* extension-cli.js — `pmos extension`: where the Chrome extension for Google Meet is, and how to load it (initiative c3-meet-extension).
+ *
+ *   pmos extension    print the absolute path of workspace/extension and the steps to load it in Chrome
+ *
+ * The extension is a folder of plain files that ships in the workspace package. Chrome loads it unpacked, so nothing is installed or written here.
+ * It reads nothing and starts nothing; it does not need a running server. */
+const fs = require('fs');
+const path = require('path');
+
+const COMMANDS = { extension: [] };
+const FOLDER = path.resolve(__dirname, '..', 'extension');
+const USAGE = ['usage: pmos extension — the Chrome extension that shows the meeting companion over a Google Meet call'];
+
+/** The lines `pmos extension` prints for a folder. Pure. */
+function lines(folder, exists = true) {
+  const out = [];
+  if (!exists) { out.push(`✗ the extension folder is not here: ${folder}`, '  Reinstall the workspace with `pmos upgrade`.'); return out; }
+  out.push('PMOS for Google Meet (Chrome)', '', `  folder  ${folder}`, '',
+    'Load it in three steps:',
+    '  1. In Chrome, open chrome://extensions',
+    '  2. Turn on Developer mode (top right)',
+    '  3. Press Load unpacked, then pick the folder above',
+    '',
+    'PMOS is looked for at http://localhost:7433. If pmos printed another port, open the extension\'s Options and set that address.',
+    'Then open a Google Meet call: the panel shows at the bottom right.');
+  return out;
+}
+
+function run(argv, { say = console.log } = {}) {
+  const rest = (argv || []).slice(1);
+  if (rest.includes('--help') || rest.includes('-h') || rest[0] === 'help') { for (const l of USAGE) say(l); return 0; }
+  if (rest.length) { say(`✗ pmos extension takes no arguments (got "${rest[0]}")`); for (const l of USAGE) say(l); return 2; }
+  const exists = fs.existsSync(path.join(FOLDER, 'manifest.json'));
+  for (const l of lines(FOLDER, exists)) say(l);
+  return exists ? 0 : 1;
+}
+
+module.exports = { run, lines, COMMANDS, USAGE, FOLDER };

package/workspace/lib/headless.js

@@ -3,7 +3,7 @@
  * (initiative workspace-headless-jobs; PM decision 2026-10-11: keep Jev, no direct Claude API, background
  * jobs that need no human run headless).
  *
- *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | null   (null: open a pane, as before)
+ *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | null   (null: open a pane, as before)
  *   argsFor(kind, { modelArgs, addDirs })          → the argv after `claude`
  *   parseResult(stdout)                            → { ok, text, isError, turns, durationMs, costUsd, denied[] }
  *   logLines(result, exitCode)                     → the lines the read-only log pane shows at the end
@@ -14,6 +14,12 @@
  * It cannot ask for permission, so each kind gets a FIXED tool list here; a connector tool runs only where the
  * PM's own Claude Code settings already allow it, and anything else is denied and reported. No bypass flag is
  * ever passed. `PMOS_HEADLESS=off` sends every job back to a pane.
+ *
+ * The `drive` kind is the Initiative Driver (initiative initiative-driver): origin `drive:<kind>:<id>`. It reads, and it files
+ * proposals with `pmos driver propose`. It has no Write, no Edit, no `git push`, no web fetch and no connector write tool: no
+ * connector tool is named in its list, so a connector read runs only where the PM's own Claude Code settings already allow it,
+ * and a connector write is denied and reported like any other tool outside the list. The PM-only `pmos driver` verbs refuse an
+ * agent session by themselves. The driver never runs in a pane (server.js refuses to start it when PMOS_HEADLESS=off).
  */
 
 // The skills whose every start runs headless: they read, file a result for PMOS, and send nothing out.
@@ -25,12 +31,16 @@ const HEADLESS_SKILLS = Object.freeze([
 const HEADLESS_ORIGINS = Object.freeze(['notes-bullets:', 'notes-summary:']);
 // page-starts-agent: Ask the agent on a document. The run reads and answers with the revised text; it writes nothing.
 const ASK_ORIGINS = Object.freeze(['doc-ask:', 'focus-companion:']);   // focus-companion: the Meeting focus page's quiet companion and its private questions (read-only, nothing sent)
+// initiative-driver: one short run for one initiative or one Work task. Its origin is `drive:<kind>:<id>`.
+const DRIVE_ORIGINS = Object.freeze(['drive:']);
 
 // What each kind may use. Read-only search is always allowed. The notes passes write their JSON (and rename the .tmp
 // file) in their notes folder, which --add-dir opens to them; the skills also run `pmos` verbs and repository scripts.
 const TOOLS = Object.freeze({
   notes: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(mv *)']),
   ask: Object.freeze(['Read', 'Glob', 'Grep']),
+  drive: Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos driver *)', 'Bash(pmos initiative list *)', 'Bash(pmos initiative export *)',
+    'Bash(git log *)', 'Bash(ls *)', 'Bash(date *)']),
   skill: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(pmos *)', 'Bash(node *)',
     'Bash(git log *)', 'Bash(git status *)', 'Bash(git diff *)', 'Bash(ls *)', 'Bash(date *)']),
 });
@@ -46,6 +56,7 @@ function kindFor({ agent, origin, skill, env } = {}) {
   const o = String(origin || '');
   if (HEADLESS_ORIGINS.some((p) => o.startsWith(p))) return 'notes';
   if (ASK_ORIGINS.some((p) => o.startsWith(p))) return 'ask';
+  if (DRIVE_ORIGINS.some((p) => o.startsWith(p))) return 'drive';
   if (skill && HEADLESS_SKILLS.includes(String(skill))) return 'skill';
   return null;
 }
@@ -96,4 +107,4 @@ function logLines(r, exitCode) {
   return out;
 }
 
-module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };
+module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };

package/workspace/lib/meeting-focus.js

@@ -9,6 +9,7 @@
  *   foldState(lines, { topics, startMs, nowMs }) → the page's state    the append-only focus/<id>.jsonl folded
  *   outLine(parsed, at) · moveLine(...)   → the lines the state file takes
  *   shouldRun(now, state, note, opts)     → { run, reason }            the rules of when the companion may run
+ *   pickNow(events, { now, meet, title }) → { ok, event, date, by } | { ok:false, status:404, error, choices }   which meeting a Google Meet call is (the Chrome extension, c3-meet-extension)
  *
  * Nothing here reads a file or starts a process; lib/routes-meeting-focus.js does both.
  *
@@ -289,4 +290,50 @@ function shouldRun(now, state, note, opts = {}) {
   return { run: true, reason: 'new lines' };
 }
 
-module.exports = { CATS, REF_TYPES, MIN_GAP_MS, TAIL_MINUTES, TAIL_MAX, topicsFrom, tailOf, capturedFrom, companionPrompt, parseCompanion, foldState, outLine, moveLine, shouldRun, norm, str, off };
+/* ── which meeting is this Google Meet call (c3-meet-extension) ───────────────────────────────────────────────────── */
+
+const MEET_CODE = /\b[a-z]{3}-[a-z]{4}-[a-z]{3}\b/i;
+const NOW_SLACK_MS = 10 * 60000;   // a call may start 10 minutes early and run 10 minutes over
+const DEFAULT_LEN_MS = 60 * 60000;
+const CHOICES_MAX = 6;
+const localDayOf = (ms) => { const d = new Date(ms); return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0'); };
+const startOf = (e) => Date.parse(e && (e.at || e.start));
+const endOf = (e) => { const s = startOf(e); const t = Date.parse(e && e.end); return Number.isFinite(t) && t > s ? t : s + DEFAULT_LEN_MS; };
+/** Every text of an event that may carry the Meet address: its links, and the fields a calendar reader may fill. */
+const meetTextsOf = (e) => [].concat((Array.isArray(e.links) ? e.links : []).map((l) => (l && typeof l === 'object' ? l.url : l)), e.hangoutLink, e.hangout_link, e.meet_url, e.conference, e.location)
+  .filter((x) => typeof x === 'string').map((x) => x.toLowerCase());
+/** The tab title of a Meet call without its "Meet - " lead, in a form two titles can be compared in. A bare Meet code is no title. */
+function meetTitle(title) {
+  const raw = String(title == null ? '' : title).replace(/^\s*meet\s*[-\u2013\u2014]\s*/i, '').trim();
+  return /^[a-z]{3}-[a-z]{4}-[a-z]{3}$/i.test(raw) ? '' : norm(raw);
+}
+const titleFits = (a, b) => !!a && !!b && (a === b || (Math.min(a.length, b.length) >= 4 && (a.includes(b) || b.includes(a))));
+
+/**
+ * Which meeting on the calendar is the Google Meet call the browser shows. In order: the meeting whose links carry the Meet code, the meeting whose
+ * title is the tab's title, the meeting under way now (from 10 minutes before the start to 10 minutes after the end; of several, the one that
+ * started last). Only today's meetings, and any meeting under way now, are looked at. Several that fit one rule: the one under way, else the nearest start.
+ * When none fits: { ok:false, status:404, error, choices } with today's meetings nearest now (at most 6, in time order). Pure.
+ */
+function pickNow(events, { now = Date.now(), meet = '', title = '' } = {}) {
+  const day = localDayOf(now);
+  const pool = (events || []).filter((e) => e && e.id && Number.isFinite(startOf(e)) && (localDayOf(startOf(e)) === day || (startOf(e) <= now && now <= endOf(e))));
+  const near = (e) => (now < startOf(e) ? startOf(e) - now : now > endOf(e) ? now - endOf(e) : 0);
+  const best = (list) => list.slice().sort((a, b) => near(a) - near(b) || startOf(b) - startOf(a))[0] || null;
+  const hit = (e, by) => ({ ok: true, by, date: String(e.at || e.start || '').slice(0, 10), event: { id: e.id, title: e.title || '', at: e.at || e.start, end: e.end || null } });
+  const code = (String(meet || '').match(MEET_CODE) || [''])[0].toLowerCase();
+  if (code) { const e = best(pool.filter((x) => meetTextsOf(x).some((t) => t.includes(code)))); if (e) return hit(e, 'meet'); }
+  const want = meetTitle(title);
+  if (want) {
+    const exact = pool.filter((x) => norm(x.title) === want);
+    const e = best(exact.length ? exact : pool.filter((x) => titleFits(norm(x.title), want)));
+    if (e) return hit(e, 'title');
+  }
+  const under = pool.filter((e) => startOf(e) - NOW_SLACK_MS <= now && now <= endOf(e) + NOW_SLACK_MS);
+  if (under.length) return hit(under.slice().sort((a, b) => startOf(b) - startOf(a))[0], 'time');
+  const choices = pool.slice().sort((a, b) => near(a) - near(b) || startOf(a) - startOf(b)).slice(0, CHOICES_MAX).sort((a, b) => startOf(a) - startOf(b))
+    .map((e) => ({ id: e.id, title: e.title || '', at: e.at || e.start, end: e.end || null }));
+  return { ok: false, status: 404, error: 'No meeting on the calendar fits this call.', choices };
+}
+
+module.exports = { CATS, REF_TYPES, MIN_GAP_MS, TAIL_MINUTES, TAIL_MAX, topicsFrom, tailOf, capturedFrom, companionPrompt, parseCompanion, foldState, outLine, moveLine, shouldRun, pickNow, meetTitle, norm, str, off };

package/workspace/lib/needs-providers.js

@@ -33,6 +33,7 @@ const PROVIDERS = Object.freeze([
   'initiative-needs',   // Run 2 (2C): day one, agent proposals, passed check-by (kind 7); a record with no anchor (kind 8)
   'work-check-needs',   // Run 4 (4D): a person's item in Review, a batched Release (kind 4)
   'report-needs',       // Run 5 (5C): a report to issue (kind 1), cycle rows (kind 7), a schedule left no output (kind 8)
+  'driver-needs',       // initiative-driver: drafts the agent filed (kind 7), a target the PM is blocking (kind 7)
 ]);
 /** Kinds that already mean something in the needs queue. A provider may not reuse one. */
 const RESERVED_KINDS = Object.freeze(['question', 'accept', 'outcome', 'keep', 'evidence', 'plan-flag', 'provider-error']);

package/workspace/lib/pmos-verbs.js

@@ -53,6 +53,12 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): tracker-read-freshness added it through the same table.
   tracker: Object.freeze({ module: 'tracker-cli.js', run: null, guide: 'data-freshness.md',
     help: 'pmos tracker done|status — record when the tracker-refresh skill finished a read of this repository (pmos tracker help)' }),
+  // Not a pm-os-absorb verb (run: null): c3-meet-extension added it through the same table.
+  extension: Object.freeze({ module: 'extension-cli.js', run: null, guide: 'console-calendar.md',
+    help: 'pmos extension — the folder of the Chrome extension for Google Meet, and the three steps to load it' }),
+  // Not a pm-os-absorb verb (run: null): initiative initiative-driver added it through the same table.
+  driver: Object.freeze({ module: 'driver-cli.js', run: null, guide: 'initiative-driver.md',
+    help: 'pmos driver propose|status|keep|return|drop|pause|resume|mode … — the Initiative Driver: drafts for you to keep, send back or drop (pmos driver help)' }),
   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' }),
 });

package/workspace/lib/route-modules.js

@@ -68,6 +68,7 @@ const MODULES = Object.freeze([
   'routes-sources',       // workspace-data-freshness: how old each source is, Refresh now, the change detector switch
   'routes-meeting-focus', // console3 Meeting focus: the meeting, its note's talk, the companion's notes (GET); topic corrections and Ask PMOS quietly (page press)
   'routes-stage-tools',   // stage-tools-records: the records the PM edits per stage, what PMOS holds per stage, the sprint burndown
+  'routes-driver',        // initiative-driver: the Agent strip's data, Keep, Send back, Drop, Pause and the board mode (driver.jsonl)
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

package/workspace/lib/routes-boards.js

@@ -776,6 +776,16 @@ async function handle(req, res, url, ctx) {
   return true;
 }
 
+/** The PM's move of one initiative, by the same function POST /api/boards/move runs (initiative initiative-driver: Keep on a
+ * driver proposal). `g` is the guard's answer ({ ok, actor }); nothing is chosen by the caller. Answers { status, body } with the
+ * body the route would send ({ ok, row, warnings } or { ok: false, error }); the route's validation and warnings apply. */
+function move(ctx, body, g) {
+  let out = { status: 500, body: { ok: false, error: 'the move was not answered' } };
+  const cap = { ...ctx, json: (_res, obj, code) => { out = { status: code || 200, body: obj }; } };
+  WRITES['/api/boards/move'](cap, null, body, g);
+  return out;
+}
+
 /** The board of each initiative of a workspace, for other routes (Reports): { boards: [{ id, title }], of(id) → board id }.
  * Rows still being read fall back to the ledger's assignment, else the default board. */
 function boardIndex(ctx, w) {
@@ -836,4 +846,4 @@ function meetingBoards(ctx) {
   return { list, detail };
 }
 
-module.exports = { prefixes: ['/api/boards'], handle, boardIndex, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };
+module.exports = { prefixes: ['/api/boards'], handle, move, boardIndex, frameFor, boardIdOf, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };