create-pmos 0.169.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.169.0",
+  "version": "0.170.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.169.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.169.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-ib-triage.js

@@ -15,6 +15,7 @@ import { el } from './dom.js';
 import { registerBoardTab } from './c3-initiatives.js';
 import { icon, pbtn, lk, chip, tag, st, note, noteA, lbl, sect, card, list, empty, nrow, cols, chgl, ago, put } from './c3-ini-ui.js';
 import { TEMPLATES } from './c3-ini-work.js';
+import { isScanAsk, scanAskParts } from './c3-scan.js';
 
 const LANES = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'];
 const ANCHOR_WHY = 'An initiative needs an anchor: a key result or a health budget. PMOS refuses to create one without it.';
@@ -52,16 +53,19 @@ registerBoardTab('triage', async (host, ctx) => {
   }
   function row(a, state) {
     const open = state === 'open';
+    // initiative horizon-scan: an ask the scan found shows its reason, "Found by agent", its sources and its match, with the usual three buttons.
+    const scan = isScanAsk(a) ? scanAskParts(a, { today: ctx.today, first: first.name, onAccept: open ? openAccept : null, onMore: openMore, onDecline: openDecline }) : null;
     const ini = a.initiative && (a.initiative.id || a.initiative);
     const sharp = a.draft && typeof a.draft.confidence === 'number' ? (a.draft.confidence >= 0.7 ? 'sharp' : a.draft.confidence < 0.5 ? 'needs detail' : 'readable') : 'no draft';
     return nrow({ ic: state === 'declined' ? 'x' : state === 'accepted' ? 'check' : 'bolt', hot: open, title: a.line, key: 'ask:' + a.id,
-      chips: [a.source ? chip(a.source) : null, a.by ? chip(icon('user', 'sm'), a.by) : null, a.at ? chip(ago(a.at, ctx.today)) : null,
+      sub: scan ? scan.sub : null, after: scan ? scan.after : null,
+      chips: [...(scan && open ? scan.chips : [a.source ? chip(a.source === 'scan' ? 'Horizon scan' : a.source) : null, a.by ? chip(icon('user', 'sm'), a.by) : null, a.at ? chip(ago(a.at, ctx.today)) : null]),
         open && a.needMore ? st('warn', 'alert', 'asked for more', { 'data-ibt': 'need-more', title: a.moreNote || '' }) : null,
         state === 'accepted' ? st('ok', 'check', 'Accepted') : null, state === 'accepted' && ini ? lk({ 'data-ibt-open': ini, onclick: () => ctx.openInitiative(ini) }, ini) : null,
         state === 'declined' ? tag('declined') : null],
       right: open ? [tag(sharp)] : [],
       xp: open ? [...draftNodes(a), a.needMore && a.moreNote ? note('You asked: ' + a.moreNote) : null,
-        el('div', { class: 'chips2' }, pbtn('primary', 'Accept', 'check', { 'data-ibt-accept': a.id, onclick: () => openAccept(a) }),
+        scan ? null : el('div', { class: 'chips2' }, pbtn('primary', 'Accept', 'check', { 'data-ibt-accept': a.id, onclick: () => openAccept(a) }),
           pbtn('outline', 'Ask for more', 'reply', { 'data-ibt-more': a.id, onclick: () => openMore(a) }),
           pbtn('ghost', 'Decline', 'x', { 'data-ibt-decline': a.id, onclick: () => openDecline(a) }))].filter(Boolean)
         : state === 'declined' && a.why ? [note('Declined: ' + a.why)] : null,

package/workspace/public/pm/c3-initiatives.js

@@ -49,6 +49,7 @@ import { TEMPLATES, BOARD_TEMPLATES, isBuildStage, templateBuilds, offered, wfOf
 import { timeline, tlInit, tlRange } from './c3-ini-timeline.js';
 import { RECORD_META, recordToolsFor } from './c3-ini-records.js';
 import { agentSetting, loadAgentMode, MODES as AGENT_MODES } from './c3-driver.js';
+import { scanSetting, takeSettingsFor } from './c3-scan.js';
 
 export { btn, geo };
 export { TEMPLATES, CATS };
@@ -160,6 +161,8 @@ export function mountInitiatives(pane, opts) {
   }
   const openBoard = (id, tab, filter) => go({ view: 'board', board: id, tab: tab || 'summary', filter: filter || {} });
   const refresh = () => { P.boards = null; P.ini = null; dropItems(); draw(); };
+  // The Briefing's Horizon scan card opens a board's Triage or settings (c3-scan.js goBoard). A page that is not built yet reads the address instead.
+  if (typeof window !== 'undefined') { if (window.__iniGo) window.removeEventListener('pmos:ini-go', window.__iniGo); window.__iniGo = (e) => { const d = (e && e.detail) || {}; if (d.board && root.isConnected) openBoard(d.board, d.tab || 'summary'); }; window.addEventListener('pmos:ini-go', window.__iniGo); }
   const redraw = () => draw();
 
   async function loadBoards() {
@@ -326,6 +329,7 @@ export function mountInitiatives(pane, opts) {
         segTabs(tabs, tab, (k) => openBoard(b.id, k), 'Board views', { 'data-ini': 'board-tabs' }),
         host));
     mountTab(host, tab === 'summary' ? mountSummary : null, (BOARD_TAB_LIST.find((t) => t[0] === tab) || [])[1], makeCtx(b, { tab, filter: P.loc.filter || {} }), token);
+    if (!opts.demo && takeSettingsFor(b.id)) openBoardSettings(b);   // "Scan settings" on the Briefing's Horizon scan card
   }
 
   /* Summary: initiatives at a glance, where they stand, what needs attention */
@@ -389,6 +393,8 @@ export function mountInitiatives(pane, opts) {
     loadItems(makeCtx(b, {})).then((r) => { usage = r; render(); });
     // The Agent setting (c3-driver.js): read once, and saved at once when a mode is pressed (POST /api/driver/mode). Not in demo mode.
     const A = { mode: null, err: '', busy: false };
+    // The Horizon scan block (c3-scan.js): one node that reads and presses by itself, so a redraw of this form keeps it. Not in demo mode.
+    const scanNode = opts.demo ? null : scanSetting({ api: apiFor(b.ws), board: b.id, boardName: b.name });
     if (!opts.demo) loadAgentMode(apiFor(b.ws), b.id).then((r) => { if (r.ok) A.mode = r.mode; else A.err = r.error; render(); });
     async function pickAgent(mode) {
       if (A.busy || mode === A.mode) return;
@@ -423,6 +429,7 @@ export function mountInitiatives(pane, opts) {
         tplSeg([...B.offer], B.def, (k) => { B.def = k; render('[data-ini-tpl="' + k + '"]'); }, 'Default workflow'),
         tplCase(B.def),
         opts.demo ? null : agentSetting(A, { onPick: pickAgent }),
+        scanNode,
         el('div', { class: 'chips2' }, el('span', { class: 'dim ini-note' }, 'Initiatives that do not run their own workflow run the board\'s: ' + workflowLabel(b) + '.'), lk({ 'data-ini': 'edit-board-workflow', onclick: () => openBoardWorkflow(b) }, 'Edit the board\'s workflow')),
         B.err ? errLine(B.err) : null,
         el('div', { class: 'chips2' }, pbtn('primary', B.busy ? 'Saving' : 'Save board settings', null, { 'data-ini': 'settings-save', disabled: B.busy, onclick: save }), pbtn('ghost', 'Cancel', null, { onclick: () => sh.close() })));

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

@@ -0,0 +1,25 @@
+/* pm/c3-scan.css — the few rules the Horizon scan needs beyond console3.css (c3-scan.js). The mockup's 40-scan.css under the `sc-` prefix: the
+ * Board settings block, the scan asks in Triage and the Briefing card. Held to the R28 rules: tokens only, no inline style, corners 0, 6px or 8px,
+ * font sizes from the --fs tokens. */
+.c3 .sc-set { display: grid; grid-template-columns: minmax(0, 1fr); gap: var(--sp-2); padding-top: var(--sp-3); border-top: 1px solid var(--border); }
+.c3 .sc-set > * { min-width: 0; overflow-wrap: anywhere; }
+.c3 .sc-set .seg { max-width: 100%; overflow-x: auto; }
+.c3 .sc-list { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--sp-2); }
+.c3 .sc-it { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 4px 8px; align-items: start; padding: var(--sp-2) 0; border-top: 1px solid var(--border); }
+.c3 .sc-it > .sc-main { min-width: 0; display: grid; gap: 4px; }
+.c3 .sc-it .sc-name { display: flex; gap: 6px; align-items: center; flex-wrap: wrap; overflow-wrap: anywhere; }
+.c3 .sc-it .sc-why { font-size: var(--fs-2); }
+.c3 .sc-it .sc-acts { display: flex; gap: 6px; flex-wrap: wrap; }
+.c3 .sc-it .form { margin: 0; }
+.c3 .sc-add { display: flex; gap: 6px; flex-wrap: wrap; align-items: center; }
+.c3 .sc-add input[type="text"] { flex: 1 1 160px; min-width: 0; }
+.c3 .sc-meta { display: grid; gap: 4px; font-size: var(--fs-2); }
+.c3 .sc-foot { font-size: var(--fs-2); }
+.c3 .nrow .sc-src { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 4px; align-items: center; }
+.c3 .nrow .sc-src .chip2 { max-width: 100%; }
+.c3 .sc-link { text-decoration: none; }
+.c3 .sc-card { display: grid; gap: var(--sp-2); }
+.c3 .sc-card ul.chgl li { flex-wrap: wrap; }
+
+.c3 .sc-card .sc-find { display: flex; flex-direction: column; min-width: 0; }
+.c3 .sc-card .sc-find .sc-sub { display: block; }