create-pmos 0.168.0 → 0.170.0

package/workspace/lib/scan.js

@@ -0,0 +1,396 @@
+'use strict';
+/* scan.js — the Horizon scan's ledger and rules (initiative horizon-scan, PRD sections 1 to 5).
+ *
+ * The agent looks outward on a schedule. A scan is two headless runs: a web run that sees only the watch list the PM kept, and a
+ * repository run that sees the repository and files up to 3 findings of its own. Each finding becomes a Triage ask that the PM
+ * accepts or declines. This file is the pure core: the shape of every line in <state folder>/scan.jsonl, the fold, the schedule and
+ * the duplicate test. It reads the clock only through the `now` its callers pass. The only I/O is the read/append pair at the bottom.
+ *
+ *   LEDGER · KINDS · CADENCES · DEFAULT_CADENCE · EVENTS · LIMITS · SLOT
+ *   ledgerFile(stateDir)                    → <state folder>/scan.jsonl
+ *   append(file, line, { now })             → the line written. THE SINGLE WRITER of scan.jsonl.
+ *   readLines(file)                         → every line that parses, in file order
+ *   fold(lines)                             → the current state (boards with cadence and watch list, scans, findings)
+ *   watchOf(state, board) · keptItems(state, board) · cadenceOf(state, board)
+ *   checkWatchItem(input) · checkFinding(input) · sourceOf(ref)
+ *   words(title) · normUrl(url) · duplicateOf(state, board, { title, sources })     the duplicate test (PRD section 3)
+ *   isWorkingDay(ms, cadence) · scanDay(state, board, day) · dueNow(...) · suggestDue(...) · nextScan(...)
+ *   setCadence(file, board, cadence, actor) · watchOp(file, op, board, input, actor)   the PM's presses (routes and CLI)
+ *   scheduleText(cadence)                   → the plain sentence the settings block shows
+ *
+ * THE LINES. Every line is { v: 1, ev, …, at }. Who wrote a decision is the call path (lib/actor.js), never a field:
+ *   watch-suggest { board, id, kind, name, why, ini }       the suggest run files up to 8; `ini` names the initiative it came from
+ *   watch-keep    { board, id, restore? }                   PM only. `restore` brings a removed item back as it was (the Undo)
+ *   watch-edit    { board, id, name?, kind?, why? }         PM only; an edited item is kept
+ *   watch-remove  { board, id }                             PM only
+ *   watch-add     { board, id, kind, name, why? }           PM only; an added item is kept
+ *   cadence       { board, cadence }                        PM only: daily | weekly | off
+ *   scan-start    { board, scan, mode: 'scan'|'suggest', watch: [{ id, kind, name, why }] }
+ *   scan-end      { board, scan, ok, reason?, pages, found, skipped, runs }
+ *   finding       { board, scan, id, origin: 'web'|'repo', title, why, sources: [{ label, ref }], match, by, run? }   `run` is the scan run that filed it
+ *                 A later line with the same `id` and a `match` sets the match (the repository run marks the web findings).
+ * Three lines the PRD does not list, each needed by one rule it does:
+ *   skip          { board, scan, origin, of }               a finding the duplicate test refused: "the skip count is recorded on the scan"
+ *   pages         { board, scan, pages }                    the number of public pages the web run says it read
+ *   run-end       { board, scan, run, origin: 'web'|'repo'|'suggest', ok, reason?, agent_run }   "each scan run writes an agent-runs line"
+ *
+ * THE FACTORY NEVER WRITES HERE (D65): this ledger is not an initiative, an acceptance or an anchor. A finding is a proposal: the
+ * Triage ask it becomes (lib/routes-boards.js appendScanAsk) turns into an initiative only when the PM accepts it.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const D = require('./driver.js');
+
+const LEDGER = 'scan.jsonl';
+const KINDS = Object.freeze(['product', 'domain', 'approach']);
+const CADENCES = Object.freeze(['daily', 'weekly', 'off']);
+const DEFAULT_CADENCE = 'daily';
+const EVENTS = Object.freeze(['watch-suggest', 'watch-keep', 'watch-edit', 'watch-remove', 'watch-add', 'cadence', 'scan-start', 'scan-end', 'finding', 'skip', 'pages', 'run-end']);
+const LIMITS = Object.freeze({ suggestions: 8, web: 5, repo: 3, sources: 6, items: 40 });
+const SLOT = '09:00';
+const ORIGINS = Object.freeze(['web', 'repo']);
+const MODES = Object.freeze(['scan', 'suggest']);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const WATCH_RE = /^w-[0-9a-f]{8}$/;
+const SCAN_RE = /^scan-[0-9a-f]{10}$/;
+const FINDING_RE = /^f-[0-9a-f]{10}$/;
+const RUN_RE = /^srun-[0-9a-f]{10}$/;
+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 newId = (prefix, bytes = 4) => `${prefix}-${crypto.randomBytes(bytes).toString('hex')}`;
+const refuse = (status, error) => ({ ok: false, status, error });
+
+// ── the one writer, and the read ─────────────────────────────────────────────────────────────────────
+const ledgerFile = (stateDir) => (stateDir ? path.join(stateDir, LEDGER) : null);
+/** THE SINGLE WRITER of scan.jsonl. `v` and `at` are set here; a caller never chooses them. */
+function append(file, line, { now } = {}) {
+  if (!file) throw new Error('scan: no ledger file');
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`scan: 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;
+}
+
+// ── shapes ───────────────────────────────────────────────────────────────────────────────────────────
+const isUrl = (s) => /^https?:\/\/[^\s/$.?#][^\s]*$/i.test(String(s || ''));
+const JIRA_RE = /^[A-Z][A-Z0-9_]+-\d+$/;
+/** The kind of a source pointer: a public page, a Jira key, or a path or note. */
+const sourceOf = (ref) => (isUrl(ref) ? 'web' : JIRA_RE.test(String(ref || '').trim()) ? 'jira' : 'note');
+
+function checkWatchItem(i) {
+  const x = isObj(i) ? i : {};
+  if (!KINDS.includes(x.kind)) return { ok: false, error: `kind must be one of ${KINDS.join(', ')}` };
+  if (!oneLine(x.name, 80)) return { ok: false, error: 'name is one line of 1 to 80 characters' };
+  if (x.why != null && x.why !== '' && !oneLine(x.why, 200)) return { ok: false, error: 'why is one line of at most 200 characters' };
+  return { ok: true, item: { kind: x.kind, name: x.name.trim(), why: typeof x.why === 'string' ? x.why.trim() : '' } };
+}
+
+/** The shape of one finding as an agent files it. A web finding needs a public page it read; a repository finding needs a pointer. */
+function checkFinding(i, origin) {
+  const x = isObj(i) ? i : {};
+  if (!ORIGINS.includes(origin)) return { ok: false, error: 'origin is web or repo' };
+  if (!oneLine(x.title, 160)) return { ok: false, error: 'title is one line of 1 to 160 characters' };
+  if (!oneLine(x.why, 300)) return { ok: false, error: 'why is one line of 1 to 300 characters' };
+  const list = Array.isArray(x.sources) ? x.sources : [];
+  if (!list.length) return { ok: false, error: origin === 'web' ? 'a web finding needs at least one source: the public page you read' : 'a repository finding needs at least one pointer (a path, a Jira key or a note)' };
+  if (list.length > LIMITS.sources) return { ok: false, error: `at most ${LIMITS.sources} sources` };
+  const sources = [];
+  for (const s of list) {
+    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 (up to 500)' };
+    sources.push({ label: s.label.trim(), ref: s.ref.trim() });
+  }
+  if (origin === 'web' && !sources.some((s) => isUrl(s.ref))) return { ok: false, error: 'a web finding needs at least one source that is a public page address (https://…)' };
+  if (x.match != null && x.match !== '' && !(typeof x.match === 'string' && ID_RE.test(x.match))) return { ok: false, error: 'match is an initiative id' };
+  return { ok: true, finding: { origin, title: x.title.trim(), why: x.why.trim(), sources, match: x.match ? x.match : null } };
+}
+
+// ── the duplicate test ───────────────────────────────────────────────────────────────────────────────
+const STOP = new Set(['a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'can', 'do', 'for', 'from', 'get', 'has', 'have', 'how', 'in', 'into', 'is', 'it', 'its', 'of', 'on', 'or', 'our', 'so', 'that', 'the',
+  'their', 'them', 'they', 'this', 'to', 'up', 'us', 'we', 'what', 'when', 'with', 'you', 'your', 'before', 'after', 'than', 'then', 'new', 'make', 'give', 'show', 'let', 'use', 'using']);
+/** The significant words of a title: lower case, no stop words, a light plural stem. */
+function words(title) {
+  const out = new Set();
+  for (const raw of String(title || '').toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < 3 && !/\d/.test(raw)) continue;
+    if (STOP.has(raw)) continue;
+    let w = raw;
+    if (w.length > 4 && w.endsWith('ies')) w = w.slice(0, -3) + 'y';
+    else if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss')) w = w.slice(0, -1);
+    if (!STOP.has(w)) out.add(w);
+  }
+  return out;
+}
+/** The same page by another spelling: no scheme, no www, no fragment, no tracking query, no trailing slash. */
+function normUrl(u) {
+  try {
+    const x = new URL(String(u).trim());
+    const q = [...x.searchParams.entries()].filter(([k]) => !/^(utm_|fbclid$|gclid$|ref$)/i.test(k)).sort(([a], [b]) => a.localeCompare(b));
+    const query = q.length ? '?' + q.map(([k, v]) => `${k}=${v}`).join('&') : '';
+    return (x.hostname.toLowerCase().replace(/^www\./, '') + x.pathname.replace(/\/+$/, '') + query).toLowerCase();
+  } catch { return String(u || '').trim().toLowerCase(); }
+}
+/** Two titles with the same significant words: equal sets, or (from three words up) four in five shared. */
+function sameWords(a, b) {
+  const wa = words(a); const wb = words(b);
+  if (!wa.size || !wb.size) return false;
+  let both = 0;
+  for (const w of wa) if (wb.has(w)) both++;
+  if (both === wa.size && both === wb.size) return true;
+  if (Math.min(wa.size, wb.size) < 3) return false;
+  return both / (wa.size + wb.size - both) >= 0.75;
+}
+/** The earlier finding on the same board that this one repeats (the same public page, or the same significant title words), or null. */
+function duplicateOf(state, board, { title, sources } = {}) {
+  const urls = new Set((sources || []).filter((s) => s && isUrl(s.ref)).map((s) => normUrl(s.ref)));
+  for (const id of state.findingOrder) {
+    const f = state.findings.get(id);
+    if (!f || f.board !== board) continue;
+    if (urls.size && (f.sources || []).some((s) => isUrl(s.ref) && urls.has(normUrl(s.ref)))) return f;
+    if (sameWords(f.title, title)) return f;
+  }
+  return null;
+}
+
+// ── the fold ─────────────────────────────────────────────────────────────────────────────────────────
+function boardState(s, id) {
+  if (!s.boards.has(id)) s.boards.set(id, { id, cadence: DEFAULT_CADENCE, cadenceAt: null, items: new Map(), order: [] });
+  return s.boards.get(id);
+}
+const emptyState = () => ({ boards: new Map(), scans: new Map(), scanOrder: [], findings: new Map(), findingOrder: [] });
+
+/** The current state of one ledger. A decision line from anything but the PM is ignored; the first line for an id wins. */
+function fold(lines) {
+  const s = emptyState();
+  for (const l of lines || []) {
+    if (!isObj(l) || typeof l.board !== 'string' || !ID_RE.test(l.board)) continue;
+    const b = boardState(s, l.board);
+    switch (l.ev) {
+      case 'watch-suggest': {
+        if (!WATCH_RE.test(String(l.id)) || b.items.has(l.id) || !KINDS.includes(l.kind) || !oneLine(l.name, 80)) break;
+        b.items.set(l.id, { id: l.id, kind: l.kind, name: l.name, why: typeof l.why === 'string' ? l.why : '', ini: typeof l.ini === 'string' ? l.ini : null, added: false, state: 'suggested', prev: null, at: l.at || null });
+        b.order.push(l.id);
+        break;
+      }
+      case 'watch-add': {
+        if (!pm(l.by) || !WATCH_RE.test(String(l.id)) || b.items.has(l.id) || !KINDS.includes(l.kind) || !oneLine(l.name, 80)) break;
+        b.items.set(l.id, { id: l.id, kind: l.kind, name: l.name, why: typeof l.why === 'string' ? l.why : '', ini: null, added: true, state: 'kept', prev: null, at: l.at || null });
+        b.order.push(l.id);
+        break;
+      }
+      case 'watch-keep': {
+        const it = b.items.get(l.id);
+        if (!it || !pm(l.by)) break;
+        if (it.state === 'suggested') it.state = 'kept';
+        else if (it.state === 'removed' && l.restore === true) { it.state = it.prev || 'kept'; it.prev = null; }
+        break;
+      }
+      case 'watch-edit': {
+        const it = b.items.get(l.id);
+        if (!it || !pm(l.by) || it.state === 'removed') break;
+        if (oneLine(l.name, 80)) it.name = l.name.trim();
+        if (KINDS.includes(l.kind)) it.kind = l.kind;
+        if (typeof l.why === 'string') it.why = l.why.trim();
+        it.state = 'kept';
+        break;
+      }
+      case 'watch-remove': {
+        const it = b.items.get(l.id);
+        if (!it || !pm(l.by) || it.state === 'removed') break;
+        it.prev = it.state; it.state = 'removed';
+        break;
+      }
+      case 'cadence': if (pm(l.by) && CADENCES.includes(l.cadence)) { b.cadence = l.cadence; b.cadenceAt = l.at || null; } break;
+      case 'scan-start': {
+        if (!SCAN_RE.test(String(l.scan)) || s.scans.has(l.scan) || !MODES.includes(l.mode)) break;
+        s.scans.set(l.scan, { scan: l.scan, board: l.board, mode: l.mode, start: l.at || null, end: null, ok: null, reason: null, watch: Array.isArray(l.watch) ? l.watch : [],
+          findings: [], skips: 0, pagesSaid: 0, pages: 0, found: 0, skipped: 0, runs: 0, runLines: [] });
+        s.scanOrder.push(l.scan);
+        break;
+      }
+      case 'finding': {
+        const sc = s.scans.get(l.scan);
+        if (!sc || !FINDING_RE.test(String(l.id))) break;
+        const had = s.findings.get(l.id);
+        if (had) { if (typeof l.match === 'string' && ID_RE.test(l.match) && !l.title) had.match = l.match; break; }
+        if (!ORIGINS.includes(l.origin) || !oneLine(l.title, 160)) break;
+        const f = { id: l.id, board: l.board, scan: l.scan, origin: l.origin, title: l.title, why: typeof l.why === 'string' ? l.why : '', sources: Array.isArray(l.sources) ? l.sources : [],
+          match: typeof l.match === 'string' && ID_RE.test(l.match) ? l.match : null, by: l.by || null, run: RUN_RE.test(String(l.run)) ? l.run : null, at: l.at || null };
+        s.findings.set(l.id, f); s.findingOrder.push(l.id); sc.findings.push(l.id);
+        break;
+      }
+      case 'skip': { const sc = s.scans.get(l.scan); if (sc) sc.skips++; break; }
+      case 'pages': { const sc = s.scans.get(l.scan); if (sc && Number.isFinite(l.pages) && l.pages >= 0) sc.pagesSaid = Math.max(sc.pagesSaid, Math.floor(l.pages)); break; }
+      case 'run-end': { const sc = s.scans.get(l.scan); if (sc && RUN_RE.test(String(l.run))) sc.runLines.push({ run: l.run, origin: l.origin, ok: l.ok === true, reason: typeof l.reason === 'string' ? l.reason : null, agent_run: isObj(l.agent_run) ? l.agent_run : null, at: l.at || null }); break; }
+      case 'scan-end': {
+        const sc = s.scans.get(l.scan);
+        if (!sc || sc.end) break;
+        sc.end = l.at || null; sc.ok = l.ok === true; sc.reason = typeof l.reason === 'string' ? l.reason : null;
+        sc.pages = Number.isFinite(l.pages) ? l.pages : sc.pagesSaid; sc.found = Number.isFinite(l.found) ? l.found : sc.findings.length;
+        sc.skipped = Number.isFinite(l.skipped) ? l.skipped : sc.skips; sc.runs = Number.isFinite(l.runs) ? l.runs : sc.runLines.length;
+        break;
+      }
+      default: break;
+    }
+  }
+  // The page count of a scan still open, and of one whose end line has none: what the agent said, else the public pages its findings cite.
+  for (const sc of s.scans.values()) {
+    const cited = new Set();
+    for (const id of sc.findings) for (const x of s.findings.get(id).sources) if (isUrl(x.ref)) cited.add(normUrl(x.ref));
+    if (!sc.end) sc.pages = Math.max(sc.pagesSaid, cited.size);
+  }
+  return s;
+}
+
+const cadenceOf = (state, board) => (state.boards.get(board) ? state.boards.get(board).cadence : DEFAULT_CADENCE);
+/** The items of a board's watch list that are not removed: { suggested: [], kept: [] }. */
+function watchOf(state, board) {
+  const b = state.boards.get(board);
+  const out = { suggested: [], kept: [] };
+  if (!b) return out;
+  for (const id of b.order) { const it = b.items.get(id); if (it.state === 'suggested') out.suggested.push(it); else if (it.state === 'kept') out.kept.push(it); }
+  return out;
+}
+/** The same items in the order they were filed, each with its state: [{ …item, state: 'suggested'|'kept' }]. */
+function itemsOf(state, board) {
+  const b = state.boards.get(board);
+  return b ? b.order.map((id) => b.items.get(id)).filter((it) => it.state !== 'removed') : [];
+}
+const keptItems = (state, board) => watchOf(state, board).kept;
+const hasWatchList = (state, board) => { const b = state.boards.get(board); return !!(b && b.order.length); };
+const scansOf = (state, board, mode) => state.scanOrder.map((id) => state.scans.get(id)).filter((x) => x.board === board && (!mode || x.mode === mode));
+const openScans = (state) => state.scanOrder.map((id) => state.scans.get(id)).filter((x) => !x.end);
+/** The scans of a board that started on a local day (YYYY-MM-DD). A scan that failed still counts: one scan per board per day. */
+const scanDay = (state, board, day) => scansOf(state, board, 'scan').filter((x) => x.start && D.localDay(Date.parse(x.start)) === day);
+const lastScan = (state, board) => scansOf(state, board, 'scan').filter((x) => x.end).pop() || null;
+
+// ── the schedule ─────────────────────────────────────────────────────────────────────────────────────
+const hhmm = (ms) => { const d = new Date(ms); return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`; };
+/** Daily: Monday to Friday. Weekly: Monday. Off: no day. */
+function isWorkingDay(ms, cadence) {
+  const d = new Date(ms).getDay();
+  if (cadence === 'daily') return d >= 1 && d <= 5;
+  if (cadence === 'weekly') return d === 1;
+  return false;
+}
+const slotMs = (ms) => { const d = new Date(ms); const [h, m] = SLOT.split(':').map(Number); d.setHours(h, m, 0, 0); return d.getTime(); };
+const scheduleText = (cadence) => (cadence === 'daily' ? 'Every working day, 09:00' : cadence === 'weekly' ? 'Every Monday, 09:00' : 'Off. No scan runs on this board');
+
+/** May a scan of this board start now? `open` is the day-check window and quiet hours as one boolean (lib/driver-run.js dayCheckOpen).
+ * → { ok } | { ok: false, why }. A scan that missed 09:00 starts at the first tick inside the working hours of that day, never outside them. */
+function dueNow(state, board, now, { open = true } = {}) {
+  const cadence = cadenceOf(state, board);
+  if (cadence === 'off') return { ok: false, why: 'off' };
+  if (!keptItems(state, board).length) return { ok: false, why: 'no-watch-list' };
+  if (!isWorkingDay(now, cadence)) return { ok: false, why: 'not-a-scan-day' };
+  if (now < slotMs(now)) return { ok: false, why: 'before-09' };
+  if (!open) return { ok: false, why: 'outside-working-hours' };
+  if (scanDay(state, board, D.localDay(now)).length) return { ok: false, why: 'done-today' };
+  if (openScans(state).some((x) => x.board === board)) return { ok: false, why: 'running' };
+  return { ok: true };
+}
+
+/** May the one suggest run of this board start now? A board with no watch list at all, whose cadence is not off, with no successful suggest run
+ * and none today. Without a kept item nothing is scanned, so the suggestions are what the PM decides on first. */
+function suggestDue(state, board, now, { open = true, initiatives = 0 } = {}) {
+  if (cadenceOf(state, board) === 'off') return { ok: false, why: 'off' };
+  if (hasWatchList(state, board)) return { ok: false, why: 'has-watch-list' };
+  if (!initiatives) return { ok: false, why: 'no-initiatives' };
+  if (!open) return { ok: false, why: 'outside-working-hours' };
+  const runs = scansOf(state, board, 'suggest');
+  if (runs.some((x) => !x.end)) return { ok: false, why: 'running' };
+  if (runs.some((x) => x.ok === true)) return { ok: false, why: 'asked-already' };
+  if (runs.some((x) => x.start && D.localDay(Date.parse(x.start)) === D.localDay(now))) return { ok: false, why: 'tried-today' };
+  return { ok: true };
+}
+
+/** When the next scan of a board starts, in ms, or null (off, or nothing kept). `dayEnd` is the day-check end ('18:00'). A scan that is due
+ * now and has not started starts at the next tick, so the answer is `now`. */
+function nextScan(state, board, now, { dayEnd = '18:00' } = {}) {
+  const cadence = cadenceOf(state, board);
+  if (cadence === 'off' || !keptItems(state, board).length) return null;
+  const doneToday = scanDay(state, board, D.localDay(now)).length > 0;
+  for (let k = 0; k < 8; k++) {
+    const d = new Date(now); d.setDate(d.getDate() + k);
+    const day = d.getTime();
+    if (!isWorkingDay(day, cadence)) continue;
+    if (k === 0) {
+      if (doneToday) continue;
+      if (now < slotMs(day)) return slotMs(day);
+      if (hhmm(now) < dayEnd) return now;
+      continue;
+    }
+    return slotMs(day);
+  }
+  return null;
+}
+
+// ── the PM's presses ─────────────────────────────────────────────────────────────────────────────────
+const isPm = (actor) => !!actor && pm(actor.by);
+function setCadence(file, board, cadence, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can change the scan cadence');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  if (!CADENCES.includes(cadence)) return refuse(400, `cadence must be one of ${CADENCES.join(', ')}`);
+  if (typeof board !== 'string' || !ID_RE.test(board)) return refuse(400, 'board must be a board id');
+  append(file, { ev: 'cadence', board, cadence, by: actor.by }, { now });
+  return { ok: true, board, cadence };
+}
+
+/** keep | edit | remove | add on a board's watch list. `input`: { id } for keep, edit and remove; { id, name?, kind?, why? } for edit; { kind, name, why? } for add. */
+function watchOp(file, op, board, input, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can change the watch list');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  if (typeof board !== 'string' || !ID_RE.test(board)) return refuse(400, 'board must be a board id');
+  if (!['keep', 'edit', 'remove', 'add'].includes(op)) return refuse(400, 'op must be keep, edit, remove or add');
+  const state = fold(readLines(file));
+  const b = state.boards.get(board);
+  const x = isObj(input) ? input : {};
+  if (op === 'add') {
+    const c = checkWatchItem(x);
+    if (!c.ok) return refuse(400, c.error);
+    if (b && [...b.items.values()].filter((i) => i.state !== 'removed').length >= LIMITS.items) return refuse(409, `a watch list holds at most ${LIMITS.items} items`);
+    if (b && [...b.items.values()].some((i) => i.state !== 'removed' && i.name.toLowerCase() === c.item.name.toLowerCase())) return refuse(409, 'the watch list has that item already');
+    const id = newId('w');
+    append(file, { ev: 'watch-add', board, id, ...c.item, by: actor.by }, { now });
+    return { ok: true, id, item: { id, ...c.item, state: 'kept', added: true } };
+  }
+  if (typeof x.id !== 'string' || !WATCH_RE.test(x.id)) return refuse(400, 'id must be a watch list item id');
+  const it = b && b.items.get(x.id);
+  if (!it) return refuse(404, `no watch list item ${x.id.slice(0, 20)} on this board`);
+  if (op === 'keep') {
+    if (it.state === 'kept') return refuse(409, 'the item is kept already');
+    if (it.state === 'removed' && x.restore !== true) return refuse(409, 'the item was removed');
+    append(file, { ev: 'watch-keep', board, id: it.id, ...(x.restore === true ? { restore: true } : {}), by: actor.by }, { now });
+    return { ok: true, id: it.id };
+  }
+  if (it.state === 'removed') return refuse(409, 'the item was removed');
+  if (op === 'remove') { append(file, { ev: 'watch-remove', board, id: it.id, by: actor.by }, { now }); return { ok: true, id: it.id }; }
+  // edit
+  const line = { ev: 'watch-edit', board, id: it.id, by: actor.by };
+  if (x.name !== undefined) { if (!oneLine(x.name, 80)) return refuse(400, 'name is one line of 1 to 80 characters'); line.name = x.name.trim(); }
+  if (x.kind !== undefined) { if (!KINDS.includes(x.kind)) return refuse(400, `kind must be one of ${KINDS.join(', ')}`); line.kind = x.kind; }
+  if (x.why !== undefined) { if (x.why !== '' && !oneLine(x.why, 200)) return refuse(400, 'why is one line of at most 200 characters'); line.why = String(x.why).trim(); }
+  if (line.name === undefined && line.kind === undefined && line.why === undefined) return refuse(400, 'say what changes: name, kind or why');
+  if (line.name && b && [...b.items.values()].some((i) => i.id !== it.id && i.state !== 'removed' && i.name.toLowerCase() === line.name.toLowerCase())) return refuse(409, 'the watch list has that item already');
+  append(file, line, { now });
+  return { ok: true, id: it.id };
+}
+
+module.exports = {
+  LEDGER, KINDS, CADENCES, DEFAULT_CADENCE, EVENTS, LIMITS, SLOT, ORIGINS, MODES, ID_RE, WATCH_RE, SCAN_RE, FINDING_RE, RUN_RE,
+  ledgerFile, append, readLines, newId, fold, cadenceOf, watchOf, itemsOf, keptItems, hasWatchList, scansOf, openScans, scanDay, lastScan,
+  checkWatchItem, checkFinding, sourceOf, isUrl, words, normUrl, sameWords, duplicateOf,
+  isWorkingDay, dueNow, suggestDue, nextScan, scheduleText, setCadence, watchOp, hhmm,
+};

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.168.0",
+  "version": "0.170.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.168.0",
+      "version": "0.170.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.168.0",
+  "version": "0.170.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/c3-brief-needs.js

@@ -15,11 +15,12 @@ import { el } from './dom.js';
 import { c3ic } from './pm-work-view.js';
 import { pmPost } from './http.js';
 import { makeXp, attachExpand } from './c3-expand.js';
-import { needRow, belowLine, BX, toast } from './c3-brief.js';
+import { needRow, belowLine, BX, toast, hooks } from './c3-brief.js';
 import { onBriefing, loadBriefing } from './shell-ticker.js';
 import { cardView, TAG_STYLE } from './briefing-model.js';
 import { onBriefPage } from './c3-brief-data.js';
 import { button, ensureComponentsCss } from './primitives.js';
+import { loadDriverNeeds, needsRow as driverRow } from './c3-driver.js';
 
 const reduced = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 const post = (path, body) => pmPost(path, body).catch(() => ({ ok: false }));
@@ -104,11 +105,12 @@ export function needsSection(S) {
   const sumState = { dec: 0, own: 0, late: 0, quick: 0 };
   const own = el('ul', { class: 'list', role: 'list', 'data-needs-own': '' });
   const ownNote = el('div');
+  const agent = el('ul', { class: 'list', role: 'list', 'data-needs-agent': '' });   // the Initiative Driver's rows (c3-driver.js)
   const list = el('ul', { class: 'list', role: 'list' });
   const extra = el('div');
   const alertHost = el('div');
   const box = el('section', { class: 'card sect', 'data-c3pg': 'needs', 'aria-label': 'Needs you' },
-    el('div', { class: 'sh2' }, el('h2', null, c3ic('inbox', 'sm'), 'Needs you ', count)), alertHost, ownNote, own, list, extra);
+    el('div', { class: 'sh2' }, el('h2', null, c3ic('inbox', 'sm'), 'Needs you ', count)), alertHost, ownNote, own, agent, list, extra);
   let sig = ''; let last = null; let ownSig = ''; let page = null;
   const nothing = () => el('li', { class: 'fold' }, c3ic('check', 'sm'), 'Nothing needs you right now.');
   /* the header line: "3 decisions · 4 of yours · 2 overdue", then how many take under 2 minutes */
@@ -118,6 +120,8 @@ export function needsSection(S) {
     if (!quick.isConnected) box.querySelector('.sh2').append(quick);
     quick.replaceChildren(document.createTextNode(dec + (dec === 1 ? ' decision' : ' decisions') + ' · ' + ownRows.length + ' of yours'));
     if (late) quick.append(' · ', el('span', { class: 'tag bad' }, late + ' overdue'));
+    const ag = agent.children.length;
+    if (ag) quick.append(' · ' + ag + ' from the agent');
     if (sumState.quick) quick.append(' · ', c3ic('bolt', 'sm'), sumState.quick + ' under 2 min');
   };
   const recount = () => {
@@ -168,9 +172,21 @@ export function needsSection(S) {
     extra.replaceChildren();
     recount();
   };
+  /* the agent's rows: drafts waiting on the PM, a target the PM is blocking. A press opens the initiative (its Overview holds the strip) or Work. */
+  let agentSig = '';
+  const goAgent = (n) => {
+    if (n.initiative_id) { try { const u = new URL(location.href); u.searchParams.set('init', 'ini:' + encodeURIComponent(n.ws) + ':' + encodeURIComponent(n.initiative_id) + ':overview'); history.replaceState(history.state, '', u); } catch { /* no history */ } }
+    if (hooks.go) hooks.go({ action: n.initiative_id ? 'goinit' : 'gowork' });
+  };
+  const fillAgent = () => loadDriverNeeds().then((rows) => {
+    const g = JSON.stringify(rows.map((r) => [r.run_id, r.question]));
+    if (g === agentSig) return; agentSig = g;
+    agent.replaceChildren(...rows.map((r) => driverRow(r, goAgent)));
+    recount();
+  }, () => {});
   S.refreshNeeds = () => { sig = ''; if (last) fill(last); };
   S.needsFill = fill;
-  onBriefing((b) => { S.brief = b; fill(b); });
+  onBriefing((b) => { S.brief = b; fill(b); fillAgent(); });
   onBriefPage(fillOwn);
   loadBriefing();
   return box;

package/workspace/public/pm/c3-driver-work.js

@@ -0,0 +1,110 @@
+/* pm/c3-driver-work.js — the Initiative Driver on a Work task (PRD section 5; mockup 39-driver.js workNote and openDraft).
+ * One agent line under the title of a task that has an open driver proposal, and the sheet behind its Review.
+ *
+ *   loadDriverOpen(ws)        GET /api/driver/open?target_kind=work → { ok, ws, mode, targets: { <task id>: [proposal] } }, or null
+ *   workNote(o)               the line: o = { item, props, ws, mode, done } → a node, or null (Shadow and Off draw no line, PRD section 5)
+ *   openDraftSheet(o)         the sheet: the draft text, the line that the agent sent nothing, Keep (copies the text), Send back, Drop
+ *
+ * A kept follow-up is copied to the clipboard and recorded. When the browser refuses the clipboard, the text is selected and the
+ * sheet stays open so Ctrl+C works. Presses: POST /api/driver/keep, return, drop (the server takes the PM from the call path).
+ * `done()` runs after a press so the Work list reads again. Nothing here sends anything to a person.
+ */
+import { el } from './dom.js';
+import { SEL } from './primitives.js';
+import { pmGet, pmPost } from './http.js';
+import { c3ic } from './pm-work-view.js';
+import { openSheet } from './c3-sheet.js';
+import { toast } from './c3-toast.js';
+import { pbtn, chip, tag, put } from './c3-ini-ui.js';
+import { whenLabel, dueLabel, titleOf, ensureDriverCss } from './c3-driver.js';
+
+export async function loadDriverOpen(ws) {
+  const r = await pmGet('/api/driver/open?target_kind=work' + (ws ? '&ws=' + encodeURIComponent(ws) : ''));
+  return r && r.ok ? r : null;
+}
+
+const press = async (ws, route, body, what) => {
+  const r = await pmPost('/api/driver/' + route, { ws, ...body });
+  if (!r || !r.ok) { toast({ text: what + ' did not work: ' + ((r && r.error) || 'the workspace did not answer') + '.', tone: 'error', timeout: 6000 }); return null; }
+  return r;
+};
+const short = (s, n) => { s = String(s || ''); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
+const lead = (props) => props.find((p) => p.what === 'follow-up') || props[0];
+const who = (item, p) => (p.data && typeof p.data.to === 'string' && p.data.to) || item.waiting_on || '';
+
+/** The words of the line, by what the agent filed. Pure. */
+export function lineOf(item, props) {
+  const p = lead(props || []);
+  if (!p) return null;
+  const more = props.length > 1 ? ' (+' + (props.length - 1) + ' more)' : '';
+  const t = p.data && typeof p.data.text === 'string' ? p.data.text : '';
+  if (p.what === 'follow-up') return { p, text: 'Agent drafted a follow-up' + (who(item, p) ? ' to ' + who(item, p) : '') + '. Nothing is sent.' + more, act: 'review' };
+  if (p.what === 'next-step') return { p, text: 'Agent suggests ' + (p.data && p.data.due && !t ? 'a new due date: ' + dueLabel(p.data.due) : 'a next step: ' + short(t, 70) + (p.data && p.data.due ? ', due ' + dueLabel(p.data.due) : '')) + '.' + more, act: 'keepdrop' };
+  return { p, text: 'Agent left a note: ' + short(t, 70) + more, act: 'review' };
+}
+
+export function workNote({ item, props, ws, mode, done }) {
+  if (mode !== 'approve') return null;
+  ensureDriverCss();
+  const l = lineOf(item, props);
+  if (!l) return null;
+  const lk = (label, attrs, fn) => pbtn('ghost', label, null, { ...attrs, class: 'lk', onclick: (e) => { e.stopPropagation(); fn(); } });
+  const decide = async (route) => {
+    const r = await press(ws, route, { proposal: l.p.id }, route === 'keep' ? 'Keep' : 'Drop');
+    if (!r) return;
+    toast(route === 'keep' ? 'Kept: ' + titleOf(l.p) + '.' : 'Dropped the suggestion.');
+    done();
+  };
+  return el('span', { class: 'drv-note', 'data-drv-wnote': item.id, 'data-drv-what': l.p.what }, c3ic('spark', 'sm'), l.text, ' ',
+    l.act === 'review' ? lk('Review', { 'data-drv-wnote-act': 'review' }, () => openDraftSheet({ item, props, ws, done }))
+      : [lk('Keep', { 'data-drv-wnote-act': 'keep' }, () => decide('keep')), lk('Drop', { 'data-drv-wnote-act': 'drop' }, () => decide('drop'))]);
+}
+
+/** Copy `text`. The clipboard first; when the browser refuses, select the node's text so Ctrl+C works. Returns 'copied' or 'selected'. */
+export async function copyText(text, node) {
+  try { if (navigator.clipboard && navigator.clipboard.writeText) { await navigator.clipboard.writeText(text); return 'copied'; } } catch { /* fall back to the selection */ }
+  try { const r = document.createRange(); r.selectNodeContents(node); const s = window.getSelection(); s.removeAllRanges(); s.addRange(r); } catch { /* the PM selects by hand */ }
+  return 'selected';
+}
+
+export function openDraftSheet({ item, props, ws, done }) {
+  ensureDriverCss();
+  const p = lead(props);
+  const text = (p.data && typeof p.data.text === 'string' && p.data.text) || '';
+  const isDraft = p.what === 'follow-up';
+  const to = who(item, p);
+  const draft = el('p', { class: 'sit drv-pre', 'data-drv': 'draft' }, text || 'The agent filed no text.');
+  const backBox = el('div', { class: 'form', hidden: true, 'data-drv': 'back-box' }, el('input', { type: 'text', placeholder: 'Tell the agent what to change', 'aria-label': 'Note to the agent', 'data-drv': 'note', maxlength: '500', autocomplete: 'off' }));
+  const status = el('div', { class: 'fold', 'data-drv': 'sheet-note' }, c3ic('info', 'sm'), isDraft ? 'The agent sent nothing and cannot send. Keep copies this text so you can send it yourself.' : 'The agent sent nothing. Keep records that you rely on this note.');
+  const sayStatus = (t, warn) => { status.className = 'fold' + (warn ? ' w' : ''); put(status, c3ic(warn ? 'alert' : 'info', 'sm'), t); };
+  let sh = null; let backOpen = false;
+  const keepBtn = pbtn('primary', isDraft ? 'Keep (copy to send yourself)' : 'Keep', 'check', { 'data-drv': 'sheet-keep', onclick: async () => {
+    const r = await press(ws, 'keep', { proposal: p.id }, 'Keep');
+    if (!r) return;
+    const how = isDraft && text ? await copyText(text, draft) : 'none';
+    done();
+    if (how === 'selected') { sayStatus('Kept. The browser did not allow copying, so the text is selected: press Ctrl+C. Nothing was sent.', true); keepBtn.disabled = true; return; }
+    sh.close();
+    toast(how === 'copied' ? 'Draft copied. Nothing was sent: send it yourself.' : 'Kept.');
+  } });
+  const backBtn = pbtn('outline', 'Send back', 'reply', { 'data-drv': 'sheet-back', onclick: async () => {
+    const inp = backBox.querySelector('input');
+    if (!backOpen) { backOpen = true; backBox.hidden = false; inp.focus(); backBtn.querySelector(SEL.btnLabel).textContent = 'Send back with note'; return; }
+    const n = inp.value.trim();
+    if (!n) { sayStatus('Write one line for the agent. A note starts its next run.', true); inp.focus(); return; }
+    const r = await press(ws, 'return', { proposal: p.id, note: n }, 'Send back');
+    if (!r) return;
+    sh.close(); toast('Sent back with your note. The agent redrafts it.'); done();
+  } });
+  const dropBtn = pbtn('ghost', 'Drop', null, { 'data-drv': 'sheet-drop', onclick: async () => {
+    const r = await press(ws, 'drop', { proposal: p.id }, 'Drop');
+    if (!r) return;
+    sh.close(); toast('Dropped the draft.'); done();
+  } });
+  sh = openSheet({ title: isDraft ? 'Draft follow-up' + (to ? ' to ' + to : '') : titleOf(p), icon: 'mail', body: el('div', { class: 'drv-sheet', 'data-drv': 'work-sheet' },
+    el('div', { class: 'chips' }, tag(isDraft ? 'draft' : p.what), to ? chip(c3ic('user', 'sm'), to) : null, p.at ? chip(c3ic('clock', 'sm'), whenLabel(p.at)) : null, chip(c3ic('check', 'sm'), short(item.title, 48))),
+    el('div', { class: 'case' }, draft),
+    p.why ? el('div', { class: 'dim drv-small' }, 'Why: ' + p.why) : null, status, backBox,
+    el('div', { class: 'iacts chips2' }, keepBtn, backBtn, dropBtn)) });
+  return sh;
+}

package/workspace/public/pm/c3-driver.css

@@ -0,0 +1,18 @@
+/* pm/c3-driver.css — the few rules the Initiative Driver needs beyond console3.css (c3-driver.js, c3-driver-work.js). The mockup's
+ * 39-driver.css under the `drv-` prefix: the Agent strip on an initiative's Overview, the Agent board setting, the agent line on a Work
+ * row and the sheets. Held to the R28 rules: tokens only, no inline style, corners 0, 6px or 8px, font sizes from the --fs tokens. */
+.c3 .drv .nrow .acts{flex-wrap:wrap;justify-content:flex-end}
+.c3 .drv-src{display:flex;gap:8px;align-items:baseline;flex-wrap:wrap}
+.c3 .drv-src .drv-ref{font-size:var(--fs-1);color:var(--muted-foreground);overflow-wrap:anywhere}
+.c3 .drv-src a.drv-ref{color:var(--acc)}
+.c3 .drv-pre{margin:0;white-space:pre-line;overflow-wrap:anywhere}
+.c3 .drv-small{font-size:var(--fs-2);line-height:1.45}
+.c3 .drv-sub{margin-top:2px}
+.c3 .drv-set{display:grid;gap:var(--sp-2)}
+.c3 .drv-set .seg{max-width:100%;overflow-x:auto}
+.c3 .drv-note{display:block}
+.c3 .drv-note .ic{vertical-align:-2px;margin-right:6px}
+.c3 .drv-note .lk{margin-left:4px}
+.c3 .drv-sheet{display:grid;gap:var(--sp-3)}
+.c3 .drv-sheet .sit{white-space:pre-line;overflow-wrap:anywhere}
+.c3 .drv-sheet input[type=text]{width:100%}