create-pmos 0.188.0 → 0.189.0

package/workspace/lib/scan.js

@@ -1,10 +1,30 @@
 'use strict';
-/* scan.js — the Horizon scan's ledger and rules (initiative horizon-scan, PRD sections 1 to 5).
+/* scan.js — the Horizon scan's ledger and rules (initiatives horizon-scan and horizon-scan-portfolio).
  *
  * 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.
+ * repository run that sees the repository. Since horizon-scan-portfolio the scan covers the whole workspace (the portfolio): ONE watch
+ * list, whose items name the boards they relate to, ONE setting (cadence, repository on or off, report types), and an output that is
+ * a set of report documents (benchmark, competitive, insight, productivity) with proposals for what to do next. A proposal is a line
+ * the PM approves, changes or dismisses; nothing happens without that press. This file is the pure core: the shape of every line in
+ * <state folder>/scan.jsonl, the fold, the schedule, the limits and the duplicate test. It reads the clock only through the `now` its
+ * callers pass. Its I/O is the read/append pair, and writeReports(), which assembles a report document from the section lines.
+ *
+ * PORTFOLIO LEDGER (horizon-scan-portfolio, PRD sections 1 to 6). One ledger is one workspace. A watch line carries `boards` (the
+ * boards the item relates to; empty means the whole portfolio) and may still carry the old `board`. The per-board lists of the first
+ * Horizon scan fold into the one list: the same name on two boards is one item with both boards. A `cadence` line (the first scan's
+ * per-board press) folds into the workspace setting, the latest line of either kind winning.
+ *   setting         { cadence?, repo?, types? }              PM only. Each key is applied alone; the latest wins
+ *   scan-start      adds { manual, by?, select?, repo, types, plan: { web, repo }, research? }   `research` = { question, depth, sources, parent, proposal }
+ *   run-start       { scan, run, origin }                    a run began (so the open scan can show its steps)
+ *   scan-stop       { scan }                                 PM only: the PM pressed Stop. The runs end, what was filed stays
+ *   report          { scan, id, type, title, path, origin: web|repo|both, parent? }    path = the file, relative to the repository. A later
+ *                   line with the same id and `written: true` says the file exists (and its final origin and path)
+ *   section         { scan, report, heading, body, origin: web|repo, sources, run? }    one part of a report; lib/scan.js writes the file from them
+ *   proposal        { scan, report, id, kind: create|research|attach, title, why, finding, evidence: [{ label, ref }], fields }
+ *   proposal-change { id, fields }   proposal-approve { id, result? }   proposal-dismiss { id, why }      PM only
+ *   proposal-undo   { id }                   PM only. Takes back a dismissal (the proposal is open again) or a change (the fields and title go back to what the
+ *                   agent filed). It is a new line, never a rewrite. An approved proposal cannot be undone: approve made an initiative or started runs.
+ *   evidence        { initiative, report, proposal }         PM only (the approve press writes it): the report is evidence of that initiative
  *
  *   LEDGER · KINDS · CADENCES · DEFAULT_CADENCE · EVENTS · LIMITS · SLOT
  *   ledgerFile(stateDir)                    → <state folder>/scan.jsonl
@@ -46,16 +66,26 @@ 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 EVENTS = Object.freeze(['watch-suggest', 'watch-keep', 'watch-edit', 'watch-remove', 'watch-add', 'cadence', 'scan-start', 'scan-end', 'finding', 'skip', 'pages', 'run-end',
+  'setting', 'run-start', 'scan-stop', 'report', 'section', 'proposal', 'proposal-change', 'proposal-approve', 'proposal-dismiss', 'proposal-undo', 'evidence']);
+const LIMITS = Object.freeze({ suggestions: 8, web: 5, repo: 3, sources: 6, items: 40, manual: 3, sections: 6, proposals: 5, body: 6000 });
+const REPORT_TYPES = Object.freeze(['benchmark', 'competitive', 'insight', 'productivity']);
+const WEB_TYPES = Object.freeze(['benchmark', 'competitive', 'insight']);   // the productivity report comes from the repository run only
+const REPORT_LABEL = Object.freeze({ benchmark: 'Benchmark report', competitive: 'Competitive analysis', insight: 'Insight report', productivity: 'Productivity report' });
+const PROPOSAL_KINDS = Object.freeze(['create', 'research', 'attach']);
+const DEPTHS = Object.freeze(['quick', 'standard', 'deep']);
+const PORTFOLIO = 'portfolio';
 const SLOT = '09:00';
 const ORIGINS = Object.freeze(['web', 'repo']);
-const MODES = Object.freeze(['scan', 'suggest']);
+const MODES = Object.freeze(['scan', 'suggest', 'research']);
+const REPORT_ORIGINS = Object.freeze(['web', 'repo', 'both']);
 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 REPORT_RE = /^r-[0-9a-f]{10}$/;
+const PROPOSAL_RE = /^p-[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:');
@@ -152,12 +182,13 @@ function sameWords(a, b) {
   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. */
+/** The earlier finding on the same board that this one repeats (the same public page, or the same significant title words), or null.
+ * `board` null means the whole portfolio (every scan of the workspace). */
 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 (!f || (board && 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;
   }
@@ -166,67 +197,93 @@ function duplicateOf(state, board, { title, sources } = {}) {
 
 // ── 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: [] });
+  if (!s.boards.has(id)) s.boards.set(id, { id, items: new Map(), order: [] });
   return s.boards.get(id);
 }
-const emptyState = () => ({ boards: new Map(), scans: new Map(), scanOrder: [], findings: new Map(), findingOrder: [] });
+const emptyState = () => ({ boards: new Map(), scans: new Map(), scanOrder: [], findings: new Map(), findingOrder: [],
+  itemById: new Map(), itemOrder: [], setting: { cadence: DEFAULT_CADENCE, repo: true, types: REPORT_TYPES.slice(), at: null },
+  reports: new Map(), reportOrder: [], proposals: new Map(), proposalOrder: [], evidence: [] });
+const validBoard = (b) => typeof b === 'string' && ID_RE.test(b);
+/** The boards a watch line names: its `boards` and its old `board`, valid ids only, once each. */
+function boardsIn(l) {
+  const out = [];
+  for (const b of [].concat(Array.isArray(l.boards) ? l.boards : [], l.board ? [l.board] : [])) if (validBoard(b) && !out.includes(b)) out.push(b);
+  return out;
+}
+const typesOf = (v) => (Array.isArray(v) ? REPORT_TYPES.filter((t) => v.includes(t)) : null);
 
 /** 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();
+  const addItem = (l, added) => {
+    if (!WATCH_RE.test(String(l.id)) || s.itemById.has(l.id) || !KINDS.includes(l.kind) || !oneLine(l.name, 80)) return;
+    const boards = boardsIn(l);
+    const it = { id: l.id, kind: l.kind, name: l.name, why: typeof l.why === 'string' ? l.why : '', ini: added ? null : (typeof l.ini === 'string' ? l.ini : null), added,
+      state: added ? 'kept' : 'suggested', prev: null, boards, scan: typeof l.scan === 'string' ? l.scan : null, at: l.at || null };
+    const b = boardState(s, boards[0] || PORTFOLIO);
+    b.items.set(it.id, it); b.order.push(it.id);
+    s.itemById.set(it.id, it); s.itemOrder.push(it.id);
+  };
   for (const l of lines || []) {
-    if (!isObj(l) || typeof l.board !== 'string' || !ID_RE.test(l.board)) continue;
-    const b = boardState(s, l.board);
+    if (!isObj(l)) continue;
     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-suggest': addItem(l, false); break;
+      case 'watch-add': if (pm(l.by)) addItem(l, true); break;
       case 'watch-keep': {
-        const it = b.items.get(l.id);
+        const it = s.itemById.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);
+        const it = s.itemById.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();
+        if (Array.isArray(l.boards)) it.boards = boardsIn({ boards: l.boards });
         it.state = 'kept';
         break;
       }
       case 'watch-remove': {
-        const it = b.items.get(l.id);
+        const it = s.itemById.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 'cadence': if (pm(l.by) && CADENCES.includes(l.cadence)) { s.setting.cadence = l.cadence; s.setting.at = l.at || null; } break;
+      case 'setting': {
+        if (!pm(l.by)) break;
+        if (CADENCES.includes(l.cadence)) s.setting.cadence = l.cadence;
+        if (typeof l.repo === 'boolean') s.setting.repo = l.repo;
+        const t = typesOf(l.types); if (t) s.setting.types = t;
+        s.setting.at = l.at || null;
+        break;
+      }
       case 'scan-start': {
-        if (!SCAN_RE.test(String(l.scan)) || s.scans.has(l.scan) || !MODES.includes(l.mode)) break;
+        if (!validBoard(l.board) || !SCAN_RE.test(String(l.scan)) || s.scans.has(l.scan) || !MODES.includes(l.mode)) break;
+        const r = isObj(l.research) ? l.research : null;
+        const plan = isObj(l.plan) ? { web: l.plan.web === true, repo: l.plan.repo === true }
+          : { web: l.mode === 'scan' && Array.isArray(l.watch) && l.watch.length > 0, repo: true };
         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: [] });
+          findings: [], skips: 0, pagesSaid: 0, pages: 0, found: 0, skipped: 0, runs: 0, runLines: [],
+          manual: l.manual === true, by: typeof l.by === 'string' ? l.by : null, select: isObj(l.select) ? l.select : null, repo: l.repo !== false, types: typesOf(l.types) || [],
+          plan, research: r ? { question: String(r.question || ''), depth: DEPTHS.includes(r.depth) ? r.depth : 'standard', sources: Array.isArray(r.sources) ? r.sources : [],
+            parent: REPORT_RE.test(String(r.parent)) ? r.parent : null, proposal: PROPOSAL_RE.test(String(r.proposal)) ? r.proposal : null } : null,
+          reports: [], runStarts: [], stopped: false, stopAt: null });
         s.scanOrder.push(l.scan);
         break;
       }
+      case 'run-start': { const sc = s.scans.get(l.scan); if (sc && RUN_RE.test(String(l.run))) sc.runStarts.push({ run: l.run, origin: l.origin, at: l.at || null }); break; }
+      case 'scan-stop': { const sc = s.scans.get(l.scan); if (sc && pm(l.by) && !sc.stopped) { sc.stopped = true; sc.stopAt = l.at || null; } 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 : [],
+        const f = { id: l.id, board: validBoard(l.board) ? l.board : sc.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;
@@ -242,6 +299,72 @@ function fold(lines) {
         sc.skipped = Number.isFinite(l.skipped) ? l.skipped : sc.skips; sc.runs = Number.isFinite(l.runs) ? l.runs : sc.runLines.length;
         break;
       }
+      case 'report': {
+        const sc = s.scans.get(l.scan);
+        if (!sc || !REPORT_RE.test(String(l.id))) break;
+        const had = s.reports.get(l.id);
+        if (had) {
+          if (l.written === true) {
+            had.written = true; had.writtenAt = l.at || null;
+            if (REPORT_ORIGINS.includes(l.origin)) had.origin = l.origin;
+            if (typeof l.path === 'string' && l.path) had.path = l.path;
+          }
+          break;
+        }
+        if (!REPORT_TYPES.includes(l.type) || !oneLine(l.title, 200) || typeof l.path !== 'string' || !l.path) break;
+        s.reports.set(l.id, { id: l.id, scan: l.scan, board: sc.board, type: l.type, title: l.title, path: l.path, origin: REPORT_ORIGINS.includes(l.origin) ? l.origin : 'repo',
+          parent: REPORT_RE.test(String(l.parent)) ? l.parent : null, at: l.at || null, written: false, writtenAt: null, sections: [] });
+        s.reportOrder.push(l.id); sc.reports.push(l.id);
+        break;
+      }
+      case 'section': {
+        const r = s.reports.get(l.report);
+        if (!r || r.scan !== l.scan || !ORIGINS.includes(l.origin) || !oneLine(l.heading, 120) || typeof l.body !== 'string') break;
+        r.sections.push({ heading: l.heading.trim(), body: l.body, origin: l.origin, sources: Array.isArray(l.sources) ? l.sources : [], run: RUN_RE.test(String(l.run)) ? l.run : null, by: l.by || null, at: l.at || null });
+        break;
+      }
+      case 'proposal': {
+        const r = s.reports.get(l.report);
+        if (!r || r.scan !== l.scan || !PROPOSAL_RE.test(String(l.id)) || s.proposals.has(l.id) || !PROPOSAL_KINDS.includes(l.kind) || !oneLine(l.title, 160)) break;
+        s.proposals.set(l.id, { id: l.id, report: r.id, scan: r.scan, kind: l.kind, title: l.title.trim(), why: typeof l.why === 'string' ? l.why : '', finding: typeof l.finding === 'string' ? l.finding : '',
+          evidence: Array.isArray(l.evidence) ? l.evidence : [], fields: isObj(l.fields) ? { ...l.fields } : {}, state: 'open', changed: false, dismissWhy: null, result: null,
+          by: l.by || null, run: RUN_RE.test(String(l.run)) ? l.run : null, at: l.at || null, decidedAt: null, filed: null });
+        { const q = s.proposals.get(l.id); q.filed = { title: q.title, fields: { ...q.fields } }; }
+        s.proposalOrder.push(l.id);
+        break;
+      }
+      case 'proposal-change': {
+        const p = s.proposals.get(l.id);
+        if (!p || !pm(l.by) || p.state !== 'open' || !isObj(l.fields)) break;
+        const { title, ...rest } = l.fields;
+        if (oneLine(title, 160)) p.title = title.trim();
+        p.fields = { ...p.fields, ...rest }; p.changed = true;
+        break;
+      }
+      case 'proposal-approve': {
+        const p = s.proposals.get(l.id);
+        if (!p || !pm(l.by) || p.state !== 'open') break;
+        p.state = 'approved'; p.result = isObj(l.result) ? { ...l.result } : {}; p.decidedAt = l.at || null;
+        break;
+      }
+      case 'proposal-dismiss': {
+        const p = s.proposals.get(l.id);
+        if (!p || !pm(l.by) || p.state !== 'open' || !oneLine(l.why, 500)) break;
+        p.state = 'dismissed'; p.dismissWhy = l.why.trim(); p.decidedAt = l.at || null;
+        break;
+      }
+      case 'proposal-undo': {
+        const p = s.proposals.get(l.id);
+        if (!p || !pm(l.by)) break;
+        if (p.state === 'dismissed') { p.state = 'open'; p.dismissWhy = null; p.decidedAt = null; }
+        else if (p.state === 'open' && p.changed) { p.title = p.filed.title; p.fields = { ...p.filed.fields }; p.changed = false; }
+        break;
+      }
+      case 'evidence': {
+        if (!pm(l.by) || !ID_RE.test(String(l.initiative)) || !REPORT_RE.test(String(l.report))) break;
+        s.evidence.push({ initiative: l.initiative, report: l.report, proposal: PROPOSAL_RE.test(String(l.proposal)) ? l.proposal : null, note: typeof l.note === 'string' ? l.note : '', at: l.at || null });
+        break;
+      }
       default: break;
     }
   }
@@ -254,27 +377,47 @@ function fold(lines) {
   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);
+// ── the portfolio watch list ─────────────────────────────────────────────────────────────────────────
+/** The workspace setting: { cadence, repo, types }. */
+const settingOf = (state) => ({ cadence: state.setting.cadence, repo: state.setting.repo, types: state.setting.types.slice() });
+const cadenceOf = (state) => state.setting.cadence;   // the one cadence of the workspace; the old per-board argument is ignored
+/** The one watch list. The same name (any case) on two boards is ONE item: the first id leads, `ids` lists every id, `boards` is the union. `board` filters to the
+ * items that relate to that board; an item that names no board relates to the whole portfolio and is in every board's list. */
+function portfolioView(state, board = null) {
+  const groups = new Map();
+  for (const id of state.itemOrder) {
+    const it = state.itemById.get(id);
+    if (!it || it.state === 'removed') continue;
+    const key = it.name.toLowerCase();
+    const g = groups.get(key);
+    if (!g) { groups.set(key, { id: it.id, kind: it.kind, name: it.name, why: it.why, ini: it.ini, added: it.added, state: it.state, boards: it.boards.slice(), ids: [it.id], at: it.at }); continue; }
+    g.ids.push(it.id);
+    for (const b of it.boards) if (!g.boards.includes(b)) g.boards.push(b);
+    if (it.state === 'kept') g.state = 'kept';
+    if (it.added) g.added = true;
+    if (!g.ini && it.ini) g.ini = it.ini;
+  }
+  const out = [...groups.values()];
+  return board ? out.filter((g) => !g.boards.length || g.boards.includes(board)) : out;
+}
+/** The live items of a board's list (or of the portfolio, board null): { suggested: [], kept: [] }. */
+function watchOf(state, board = null) {
   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); }
+  for (const it of portfolioView(state, board)) (it.state === 'kept' ? out.kept : out.suggested).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 itemsOf = (state, board = null) => portfolioView(state, board);
+const keptItems = (state, board = null) => watchOf(state, board).kept;
+/** Was any item ever filed (even one the PM removed)? Then the suggest run has done its part. */
+const hasWatchList = (state, board = null) => state.itemOrder.some((id) => { const it = state.itemById.get(id); return !board || !it.boards.length || it.boards.includes(board); });
+const scansOf = (state, board, mode) => state.scanOrder.map((id) => state.scans.get(id)).filter((x) => (!board || 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. */
+/** The scans that started on a local day (YYYY-MM-DD). A scan that failed or was stopped still counts: one scan 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 manual scans (Scan now) that started on a local day. Research runs are not counted. */
+const manualToday = (state, day) => scansOf(state, null, 'scan').filter((x) => x.manual && x.start && D.localDay(Date.parse(x.start)) === day);
 
 // ── the schedule ─────────────────────────────────────────────────────────────────────────────────────
 const hhmm = (ms) => { const d = new Date(ms); return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`; };
@@ -286,26 +429,37 @@ function isWorkingDay(ms, cadence) {
   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');
+const scheduleText = (cadence) => (cadence === 'daily' ? 'Every working day, 09:00' : cadence === 'weekly' ? 'Every Monday, 09:00' : 'Off. No scan runs');
 
-/** 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. */
+/** The report types a scan can write, given the repository switch and the number of web items it will search. Web reports (benchmark, competitive, insight)
+ * need an item or the repository; the productivity report needs the repository. */
+function effectiveTypes(types, { repo, items }) {
+  const want = REPORT_TYPES.filter((t) => (types || []).includes(t));
+  return want.filter((t) => (t === 'productivity' ? !!repo : !!repo || items > 0));
+}
+
+/** May a scheduled scan start now? `open` is the day-check window and quiet hours as one boolean (lib/driver-run.js dayCheckOpen). `board` null = the portfolio.
+ * → { 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.
+ * One scan per day across the portfolio, whoever started it: a manual scan today is today's scan. */
 function dueNow(state, board, now, { open = true } = {}) {
-  const cadence = cadenceOf(state, board);
+  const cadence = cadenceOf(state);
   if (cadence === 'off') return { ok: false, why: 'off' };
-  if (!keptItems(state, board).length) return { ok: false, why: 'no-watch-list' };
+  const kept = keptItems(state, board);
+  if (!kept.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' };
+  if (openScans(state).some((x) => !board || x.board === board)) return { ok: false, why: 'running' };
+  if (!effectiveTypes(state.setting.types, { repo: state.setting.repo, items: kept.length }).length) return { ok: false, why: 'no-reports' };
   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. */
+/** May the one suggest run start now? A portfolio with no watch list at all, whose cadence is not off and whose repository switch is on, 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 (cadenceOf(state) === 'off') return { ok: false, why: 'off' };
+  if (!state.setting.repo) return { ok: false, why: 'repo-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' };
@@ -316,10 +470,10 @@ function suggestDue(state, board, now, { open = true, initiatives = 0 } = {}) {
   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
+/** When the next scan 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);
+  const cadence = cadenceOf(state);
   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++) {
@@ -337,60 +491,450 @@ function nextScan(state, board, now, { dayEnd = '18:00' } = {}) {
   return null;
 }
 
+/** May a manual scan start now? A manual scan may start outside the working hours but never inside quiet hours; at most LIMITS.manual a day; one scan at a time.
+ * `quiet` is whether quiet hours hold at `now`; `running` is a scan alive in the process that the ledger may not show yet.
+ * → { ok, used, left } | { ok: false, status, why, error } */
+function manualCheck(state, now, { quiet = false, running = false } = {}) {
+  const used = manualToday(state, D.localDay(now)).length;
+  const left = Math.max(0, LIMITS.manual - used);
+  if (running || openScans(state).length) return { ok: false, status: 409, why: 'running', error: 'A scan is running. Wait for it to end, or stop it.', used, left };
+  if (quiet) return { ok: false, status: 409, why: 'quiet-hours', error: 'Quiet hours hold. A manual scan does not start inside them.', used, left };
+  if (used >= LIMITS.manual) return { ok: false, status: 429, why: 'manual-limit', error: `At most ${LIMITS.manual} manual scans a day. Today's ${LIMITS.manual} are used.`, used, left };
+  return { ok: true, used, left };
+}
+
+/** What a scan will do, from the PM's picks (or the setting, for a scheduled scan). `input`: { items?: [watch item id], repo?: boolean, types?: [type] }.
+ * → { ok, items: [item], repo, types, plan: { web, repo } } | { ok: false, status, error } */
+function selectScan(state, input) {
+  const x = isObj(input) ? input : {};
+  const kept = keptItems(state, null);
+  let items = kept;
+  if (x.items !== undefined) {
+    if (!Array.isArray(x.items) || x.items.length > LIMITS.items) return refuse(400, 'items is a list of watch list item ids');
+    items = [];
+    for (const id of x.items) {
+      if (typeof id !== 'string' || !WATCH_RE.test(id)) return refuse(400, 'each item is a watch list item id');
+      const g = portfolioView(state, null).find((it) => it.ids.includes(id));
+      if (!g) return refuse(404, `no watch list item ${id}`);
+      if (g.state !== 'kept') return refuse(400, `"${g.name}" is a suggestion. Keep it before it is scanned`);
+      if (!items.some((i) => i.id === g.id)) items.push(g);
+    }
+  }
+  if (x.repo !== undefined && typeof x.repo !== 'boolean') return refuse(400, 'repo is true or false');
+  const repo = x.repo === undefined ? state.setting.repo : x.repo;
+  let types = state.setting.types;
+  if (x.types !== undefined) {
+    if (!Array.isArray(x.types) || x.types.some((t) => !REPORT_TYPES.includes(t))) return refuse(400, `types are a list of ${REPORT_TYPES.join(', ')}`);
+    types = REPORT_TYPES.filter((t) => x.types.includes(t));
+  }
+  const eff = effectiveTypes(types, { repo, items: items.length });
+  if (!eff.length) return refuse(400, 'Nothing to write. Pick a report type that the picks can fill: a web report needs an item or the repository, and the productivity report needs the repository');
+  const plan = { web: items.length > 0 && eff.some((t) => WEB_TYPES.includes(t)), repo: !!repo };
+  return { ok: true, items, repo: !!repo, types: eff, plan };
+}
+
+// ── steps of a scan, for the page ────────────────────────────────────────────────────────────────────
+const STEP_LABEL = Object.freeze({ web: 'Searching the public web', repo: 'Reading the repository', reports: 'Writing the reports' });
+/** The steps of a scan: web, repo and reports, each with a state (pending | running | done | failed | skipped). */
+function stepsOf(sc) {
+  const one = (origin, planned) => {
+    if (!planned) return 'skipped';
+    const end = sc.runLines.find((r) => r.origin === origin);
+    if (end) return end.ok ? 'done' : 'failed';
+    if (sc.runStarts.some((r) => r.origin === origin)) return sc.end ? 'failed' : 'running';
+    return sc.end ? 'skipped' : 'pending';
+  };
+  const web = one('web', sc.plan.web);
+  const repo = one('repo', sc.mode === 'suggest' ? false : sc.plan.repo);
+  const settled = (st) => st === 'done' || st === 'failed' || st === 'skipped';
+  const reports = sc.mode === 'suggest' ? 'skipped' : sc.end ? (sc.reports.length ? 'done' : 'skipped') : (settled(web) && settled(repo) ? 'running' : 'pending');
+  return [{ id: 'web', label: STEP_LABEL.web, state: web }, { id: 'repo', label: STEP_LABEL.repo, state: repo }, { id: 'reports', label: STEP_LABEL.reports, state: reports }];
+}
+
 // ── 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 };
+  if (board != null && (typeof board !== 'string' || !ID_RE.test(board))) return refuse(400, 'board must be a board id');
+  append(file, { ev: 'cadence', ...(board ? { board } : {}), cadence, by: actor.by }, { now });
+  return { ok: true, ...(board ? { board } : {}), cadence };
+}
+
+/** The workspace setting: any of cadence, repo, types. Each key sent is written and nothing else is.
+ * → { ok, setting } | { ok: false, status, error } */
+function setSetting(file, input, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can change the scan setting');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  const x = isObj(input) ? input : {};
+  const line = { ev: 'setting', by: actor.by };
+  if (x.cadence !== undefined) { if (!CADENCES.includes(x.cadence)) return refuse(400, `cadence must be one of ${CADENCES.join(', ')}`); line.cadence = x.cadence; }
+  if (x.repo !== undefined) { if (typeof x.repo !== 'boolean') return refuse(400, 'repo is true or false'); line.repo = x.repo; }
+  if (x.types !== undefined) {
+    if (!Array.isArray(x.types) || x.types.some((t) => !REPORT_TYPES.includes(t))) return refuse(400, `types are a list of ${REPORT_TYPES.join(', ')}`);
+    line.types = REPORT_TYPES.filter((t) => x.types.includes(t));
+  }
+  if (line.cadence === undefined && line.repo === undefined && line.types === undefined) return refuse(400, 'say what changes: cadence, repo or types');
+  append(file, line, { now });
+  return { ok: true, setting: settingOf(fold(readLines(file))) };
 }
 
-/** 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. */
+/** keep | edit | remove | add on the portfolio watch list. `board` is the board a press came from (the per-board routes) or null.
+ * `input`: { id } for keep, edit and remove; { id, name?, kind?, why?, boards? } for edit; { kind, name, why?, boards? } for add.
+ * A press on an item that was folded from several boards (the same name) writes one line for each id, so the item stays one item. */
 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 (board != null && (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 : {};
+  let boards = null;
+  if (x.boards !== undefined) {
+    if (!Array.isArray(x.boards) || x.boards.length > 20 || x.boards.some((b) => !validBoard(b))) return refuse(400, 'boards is a list of board ids');
+    boards = boardsIn({ boards: x.boards });
+  }
+  const live = portfolioView(state, null);
   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');
+    if (live.length >= LIMITS.items) return refuse(409, `a watch list holds at most ${LIMITS.items} items`);
+    if (live.some((i) => 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 } };
+    const on = boards || (board ? [board] : []);
+    append(file, { ev: 'watch-add', ...(board ? { board } : {}), boards: on, id, ...c.item, by: actor.by }, { now });
+    return { ok: true, id, item: { id, ...c.item, state: 'kept', added: true, boards: on } };
   }
   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`);
+  const raw = state.itemById.get(x.id);
+  const group = live.find((g) => g.ids.includes(x.id));
+  const it = group || (raw && raw.state === 'removed' ? { ...raw, ids: [raw.id], state: 'removed' } : null);
+  const here = !!it && (!board || !it.boards || !it.boards.length || it.boards.includes(board) || (raw && raw.state === 'removed'));
+  if (!it || !here) return refuse(404, `no watch list item ${x.id.slice(0, 20)} on this ${board ? 'board' : 'list'}`);
+  const ids = it.ids;
   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 });
+    for (const id of ids) append(file, { ev: 'watch-keep', ...(board ? { board } : {}), 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 }; }
+  if (op === 'remove') { for (const id of ids) append(file, { ev: 'watch-remove', ...(board ? { board } : {}), id, by: actor.by }, { now }); return { ok: true, id: it.id }; }
   // edit
-  const line = { ev: 'watch-edit', board, id: it.id, by: actor.by };
+  const line = { ev: 'watch-edit', ...(board ? { board } : {}), 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 });
+  if (boards) line.boards = boards;
+  if (line.name === undefined && line.kind === undefined && line.why === undefined && !line.boards) return refuse(400, 'say what changes: name, kind, why or boards');
+  if (line.name && live.some((i) => i.id !== it.id && i.name.toLowerCase() === line.name.toLowerCase())) return refuse(409, 'the watch list has that item already');
+  for (const id of ids) append(file, { ...line, id }, { now });
   return { ok: true, id: it.id };
 }
 
+// ── reports: sections, proposals ─────────────────────────────────────────────────────────────────────
+const URL_IN_TEXT = /https?:\/\/[^\s<>"'`)\]]+/gi;
+const urlsIn = (text) => (String(text || '').match(URL_IN_TEXT) || []).map((u) => u.replace(/[.,;:!?]+$/, ''));
+/** The public pages the web run of a scan has said it read: the sources of its findings and of its web sections. A repository section may cite these, no others. */
+function readUrls(state, scanId) {
+  const out = new Set();
+  const sc = state.scans.get(scanId);
+  if (!sc) return out;
+  for (const id of sc.findings) { const f = state.findings.get(id); if (f.origin === 'web') for (const x of f.sources) if (isUrl(x.ref)) out.add(normUrl(x.ref)); }
+  for (const rid of sc.reports) for (const sec of state.reports.get(rid).sections) if (sec.origin === 'web') for (const x of sec.sources) if (isUrl(x.ref)) out.add(normUrl(x.ref));
+  return out;
+}
+function sourcesIn(list, max = LIMITS.sources) {
+  if (!Array.isArray(list) || !list.length) return { error: 'at least one source is needed' };
+  if (list.length > max) return { error: `at most ${max} sources` };
+  const sources = [];
+  for (const s of list) {
+    if (!isObj(s) || !oneLine(s.label, 80) || !oneLine(s.ref, 500)) return { 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() });
+  }
+  return { sources };
+}
+
+/** One section of a report as an agent files it. A web section: every source is a public page the run read, and every address in the text is one of the pages
+ * the run declared (here or earlier). A repository section: every source is a pointer (a path, a Jira key or a note), and an address in it must be a page the
+ * web run read. → { ok, section } | { ok: false, error } */
+function checkSection(input, origin, { state, scanId } = {}) {
+  const x = isObj(input) ? input : {};
+  if (!ORIGINS.includes(origin)) return { ok: false, error: 'origin is web or repo' };
+  if (!oneLine(x.heading, 100) || /^#/.test(String(x.heading).trim())) return { ok: false, error: 'heading is one line of 1 to 100 characters, with no # in front' };
+  const body = typeof x.body === 'string' ? x.body.replace(/\r\n?/g, '\n').trim() : '';
+  if (!body) return { ok: false, error: 'the section has no text: give it on stdin or with --body' };
+  if (body.length > LIMITS.body) return { ok: false, error: `a section is at most ${LIMITS.body} characters` };
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(body)) return { ok: false, error: 'the section holds a control character' };
+  const src = sourcesIn(x.sources);
+  if (src.error) return { ok: false, error: origin === 'web' ? 'a web section needs at least one source: the public page you read (--source "label=https://…")' : 'a repository section needs at least one pointer (--source "label=path, Jira key or note")' };
+  const read = state && scanId ? readUrls(state, scanId) : new Set();
+  const own = new Set(src.sources.filter((s) => isUrl(s.ref)).map((s) => normUrl(s.ref)));
+  if (origin === 'web') {
+    if (src.sources.some((s) => !isUrl(s.ref))) return { ok: false, error: 'every source of a web section is a public page address (https://…) that you read' };
+    const allowed = new Set([...read, ...own]);
+    const stray = urlsIn(body).find((u) => !allowed.has(normUrl(u)));
+    if (stray) return { ok: false, error: `the text names ${stray.slice(0, 80)}, which is not a page you declared. Add it as a --source, or take it out` };
+  } else {
+    const badSrc = src.sources.find((s) => isUrl(s.ref) && !read.has(normUrl(s.ref)));
+    if (badSrc) return { ok: false, error: 'a repository section cites a path, a Jira key or a note. A public page only when the web run read it' };
+    const stray = urlsIn(body).find((u) => !read.has(normUrl(u)));
+    if (stray) return { ok: false, error: `the text names ${stray.slice(0, 80)}, which the web run did not read. Take it out` };
+  }
+  return { ok: true, section: { heading: x.heading.trim(), body, sources: src.sources, origin } };
+}
+
+const LANE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+/** The fields a proposal of each kind carries. `base` holds the fields it has now (a change merges onto them). → { ok, fields } | { ok: false, error } */
+function checkFields(kind, input, base = {}) {
+  const x = { ...base, ...(isObj(input) ? input : {}) };
+  if (kind === 'create') {
+    if (!validBoard(x.board)) return { ok: false, error: 'board is the board id the initiative goes on' };
+    if (typeof x.lane !== 'string' || !LANE_RE.test(x.lane)) return { ok: false, error: 'lane is a lane name such as feature or chore' };
+    if (!oneLine(x.anchor, 120)) return { ok: false, error: 'anchor is a KR, or health:<id>' };
+    if (!oneLine(x.intent, 400)) return { ok: false, error: 'intent is one paragraph of at most 400 characters' };
+    return { ok: true, fields: { board: x.board, lane: x.lane, anchor: x.anchor.trim(), intent: x.intent.trim() } };
+  }
+  if (kind === 'research') {
+    if (!oneLine(x.question, 300)) return { ok: false, error: 'question is one line of at most 300 characters' };
+    const depth = x.depth === undefined || x.depth === '' ? 'standard' : x.depth;
+    if (!DEPTHS.includes(depth)) return { ok: false, error: `depth is one of ${DEPTHS.join(', ')}` };
+    return { ok: true, fields: { question: x.question.trim(), depth } };
+  }
+  if (kind === 'attach') {
+    if (typeof x.initiative !== 'string' || !ID_RE.test(x.initiative)) return { ok: false, error: 'initiative is the id of the initiative the finding is attached to' };
+    return { ok: true, fields: { initiative: x.initiative } };
+  }
+  return { ok: false, error: `kind is one of ${PROPOSAL_KINDS.join(', ')}` };
+}
+
+/** One proposal as the repository run files it. → { ok, proposal } | { ok: false, error } */
+function checkProposal(input) {
+  const x = isObj(input) ? input : {};
+  if (!PROPOSAL_KINDS.includes(x.kind)) return { ok: false, error: `kind is one of ${PROPOSAL_KINDS.join(', ')}` };
+  if (!oneLine(x.title, x.kind === 'create' ? 120 : 160)) return { ok: false, error: `title is one line of 1 to ${x.kind === 'create' ? 120 : 160} characters` };
+  if (!oneLine(x.why, 300)) return { ok: false, error: 'why is one line of 1 to 300 characters' };
+  if (!oneLine(x.finding, 160)) return { ok: false, error: 'finding names the finding or section it came from, in one line' };
+  const src = sourcesIn(x.evidence);
+  if (src.error) return { ok: false, error: `a proposal needs evidence: ${src.error} (--source "label=ref")` };
+  const f = checkFields(x.kind, x.fields);
+  if (!f.ok) return f;
+  return { ok: true, proposal: { kind: x.kind, title: x.title.trim(), why: x.why.trim(), finding: x.finding.trim(), evidence: src.sources, fields: f.fields } };
+}
+
+/** The earlier proposal that this title repeats: one the PM dismissed, or one still waiting. A dismissed title is not raised again. */
+function duplicateProposal(state, title) {
+  for (const id of state.proposalOrder) {
+    const p = state.proposals.get(id);
+    if ((p.state === 'dismissed' || p.state === 'open') && sameWords(p.title, title)) return p;
+  }
+  return null;
+}
+const proposalsOf = (state, reportId) => state.proposalOrder.map((id) => state.proposals.get(id)).filter((p) => !reportId || p.report === reportId);
+const waitingProposals = (state) => state.proposalOrder.map((id) => state.proposals.get(id)).filter((p) => p.state === 'open');
+
+/** The PM edits an open proposal's fields. → { ok, proposal } | { ok: false, status, error } */
+function proposalChange(file, id, fields, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can change a proposal');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  const state = fold(readLines(file));
+  const p = state.proposals.get(id);
+  if (!p) return refuse(404, `no proposal ${String(id).slice(0, 20)}`);
+  if (p.state !== 'open') return refuse(409, `the proposal is ${p.state} already`);
+  if (!isObj(fields)) return refuse(400, 'fields is an object');
+  const { title, ...rest } = fields;
+  const keys = p.kind === 'create' ? ['board', 'lane', 'anchor', 'intent'] : p.kind === 'research' ? ['question', 'depth'] : ['initiative'];
+  const extra = Object.keys(rest).find((k) => !keys.includes(k));
+  if (extra) return refuse(400, `a ${p.kind} proposal has no field ${extra.slice(0, 30)}`);
+  if (title !== undefined && !oneLine(title, p.kind === 'create' ? 120 : 160)) return refuse(400, 'title is one line');
+  const c = checkFields(p.kind, rest, p.fields);
+  if (!c.ok) return refuse(400, c.error);
+  append(file, { ev: 'proposal-change', id, fields: { ...c.fields, ...(title !== undefined ? { title: title.trim() } : {}) }, by: actor.by }, { now });
+  return { ok: true, proposal: fold(readLines(file)).proposals.get(id) };
+}
+
+/** The PM dismisses an open proposal, with a one-line why. The caller writes the correction line. → { ok, proposal } | { ok: false, status, error } */
+function proposalDismiss(file, id, why, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can dismiss a proposal');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  const p = fold(readLines(file)).proposals.get(id);
+  if (!p) return refuse(404, `no proposal ${String(id).slice(0, 20)}`);
+  if (p.state !== 'open') return refuse(409, `the proposal is ${p.state} already`);
+  if (!oneLine(why, 500)) return refuse(400, 'a dismissal needs a reason (why) of 1 to 500 characters');
+  append(file, { ev: 'proposal-dismiss', id, why: why.trim(), by: actor.by }, { now });
+  return { ok: true, proposal: fold(readLines(file)).proposals.get(id) };
+}
+
+/** The PM takes back a dismissal (the proposal is open again) or a change (the fields go back to what the agent filed). An approved proposal cannot be
+ * undone. The line is appended; no earlier line changes. → { ok, proposal } | { ok: false, status, error } */
+function proposalUndo(file, id, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can undo a proposal press');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  const p = fold(readLines(file)).proposals.get(id);
+  if (!p) return refuse(404, `no proposal ${String(id).slice(0, 20)}`);
+  if (p.state === 'approved') return refuse(409, 'an approved proposal cannot be undone: it made an initiative or started a run');
+  if (p.state === 'open' && !p.changed) return refuse(409, 'the proposal has nothing to undo');
+  append(file, { ev: 'proposal-undo', id, by: actor.by }, { now });
+  return { ok: true, proposal: fold(readLines(file)).proposals.get(id) };
+}
+
+/** The PM approves an open proposal; `result` says what it started or made. → { ok } | { ok: false, status, error } */
+function proposalApprove(file, id, result, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can approve a proposal');
+  if (!file) return refuse(409, 'this repository has no state folder for the scan');
+  const p = fold(readLines(file)).proposals.get(id);
+  if (!p) return refuse(404, `no proposal ${String(id).slice(0, 20)}`);
+  if (p.state !== 'open') return refuse(409, `the proposal is ${p.state} already`);
+  append(file, { ev: 'proposal-approve', id, result: isObj(result) ? result : {}, by: actor.by }, { now });
+  return { ok: true };
+}
+
+/** The PM's approve press links the report to an initiative as evidence. */
+function addEvidence(file, { initiative, report, proposal, note }, actor, { now } = {}) {
+  if (!isPm(actor)) return refuse(403, 'only the PM can attach evidence');
+  append(file, { ev: 'evidence', initiative, report, proposal, ...(note ? { note: String(note).slice(0, 300) } : {}), by: actor.by }, { now });
+  return { ok: true };
+}
+const evidenceOf = (state, initiative) => state.evidence.filter((e) => e.initiative === initiative);
+
+// ── starting a scan, and its report documents ────────────────────────────────────────────────────────
+/** The file a report will have: <reports folder>/scan-<type>/<day>.md, and -2, -3 … for a later scan on the same day. `rel` is the folder, relative to the repository.
+ * The reports folder is the report-workspace store (lib/report-needs.js reportsDir): the Documents list reads it with no change to its code. */
+function planPath(state, reports, type, day) {
+  const taken = new Set([...state.reports.values()].map((r) => r.path));
+  for (let n = 1; n < 1000; n++) {
+    const name = n === 1 ? `${day}.md` : `${day}-${n}.md`;
+    const rel = `${reports.rel}/scan-${type}/${name}`;
+    if (taken.has(rel)) continue;
+    if (fs.existsSync(path.join(reports.abs, `scan-${type}`, name))) continue;
+    return rel;
+  }
+  return `${reports.rel}/scan-${type}/${day}-${crypto.randomBytes(3).toString('hex')}.md`;
+}
+const longDay = (ms) => D.localDay(ms);
+function researchTitle(question) { const q = String(question || '').replace(/\s+/g, ' ').trim(); return `Research: ${q.length > 90 ? q.slice(0, 89).trimEnd() + '…' : q}`; }
+
+/** Write the scan-start line and one `report` line for each document the scan will write. `spec`:
+ *   { board, mode, manual?, by?, select?, watch?, repo, types, plan: { web, repo }, research?: { question, depth, sources, parent, proposal } }
+ * `reports` is { abs, rel }: the report-workspace folder. A research scan writes ONE document, an insight report linked to its parent.
+ * → { scan, reports: [{ id, type, title, path, origin }] } */
+function beginScan(file, spec, { now, reports } = {}) {
+  const state = fold(readLines(file));
+  const scan = newId('scan', 5);
+  const day = longDay(now == null ? Date.now() : now);
+  const planned = [];
+  if (spec.mode === 'scan' && reports) {
+    for (const type of spec.types || []) {
+      const origin = WEB_TYPES.includes(type) ? (spec.plan.web && spec.plan.repo ? 'both' : spec.plan.web ? 'web' : 'repo') : 'repo';
+      planned.push({ id: newId('r', 5), type, title: `${REPORT_LABEL[type]} · ${day}`, origin });
+    }
+  } else if (spec.mode === 'research' && reports) {
+    planned.push({ id: newId('r', 5), type: 'insight', title: researchTitle(spec.research && spec.research.question), origin: spec.plan.web && spec.plan.repo ? 'both' : spec.plan.web ? 'web' : 'repo',
+      parent: spec.research && spec.research.parent });
+  }
+  const line = { ev: 'scan-start', board: spec.board, scan, mode: spec.mode, watch: (spec.watch || []).map((i) => ({ id: i.id, kind: i.kind, name: i.name, why: i.why })),
+    manual: !!spec.manual, repo: !!spec.repo, types: spec.types || [], plan: spec.plan || { web: false, repo: true } };
+  if (spec.by) line.by = spec.by;
+  if (spec.select) line.select = spec.select;
+  if (spec.research) line.research = spec.research;
+  append(file, line, { now });
+  const taken = [];
+  for (const r of planned) {
+    const rel = planPath({ reports: new Map([...state.reports, ...taken.map((t) => [t.id, t])]) }, reports, r.type, day);
+    const out = { ...r, path: rel };
+    taken.push(out);
+    append(file, { ev: 'report', board: spec.board, scan, id: r.id, type: r.type, title: r.title, path: rel, origin: r.origin, ...(r.parent ? { parent: r.parent } : {}) }, { now });
+  }
+  return { scan, reports: taken.map(({ id, type, title, path: p, origin }) => ({ id, type, title, path: p, origin })) };
+}
+
+/** The report-workspace folder of a repository: { abs, rel }, or null when this checkout has no lib/report-needs.js. It is lib/report-needs.js reportsDir(root) — `pmos/state/reports` in
+ * a kit repository (the state folder's own `reports`), `planning/reports` in PMOS-self — the folder the Documents list reads. A caller without it falls back to
+ * <state folder>/reports, which is the same folder in a kit repository. */
+function reportsFolder(root) {
+  try {
+    const rel = require('./report-needs.js').reportsDir(root);
+    return rel ? { abs: path.join(path.resolve(String(root)), rel), rel } : null;
+  } catch { return null; }
+}
+/** Is `rel` a report file this scan wrote: <folder>/scan-<type>/<day>[-n].md, with no way out of the folder. */
+const isReportPath = (rel) => typeof rel === 'string' && !rel.split('/').some((p) => p === '..' || p === '.' || p === '')
+  && /^(?:[A-Za-z0-9._-]+\/)*scan-(?:benchmark|competitive|insight|productivity)\/\d{4}-\d{2}-\d{2}(?:-\d{1,3})?\.md$/.test(rel);
+
+const yamlQ = (s) => '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/[\r\n]+/g, ' ') + '"';
+/** Keep an agent's text from making headings of its own at the levels the document uses (# and ##). */
+const calm = (body) => String(body).split('\n').map((l) => (/^#{1,2}\s/.test(l) ? '###' + l.replace(/^#+/, '') : l)).join('\n');
+const sourceLine = (x) => (isUrl(x.ref) ? `- [${x.label}](${x.ref})` : `- ${x.label}: ${x.ref}`);
+const PROPOSAL_WORD = Object.freeze({ create: 'Create an initiative', research: 'Do more research', attach: 'Add as evidence' });
+
+/** The markdown of one report: frontmatter (one key per line), the title, its sections with their sources, and a final "What next" section that lists the
+ * report's proposals. → { text, origin } */
+function renderReport(state, rep, { at, stopped = false } = {}) {
+  const origins = new Set(rep.sections.map((x) => x.origin));
+  const origin = origins.size === 2 ? 'both' : origins.has('web') ? 'web' : origins.has('repo') ? 'repo' : rep.origin;
+  const stamp = new Date(at == null ? Date.now() : at).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const fm = ['---', 'type: Reference', `title: ${yamlQ(rep.title)}`, `timestamp: ${stamp}`, 'source: scan:portfolio', 'made_by: agent', 'output: google-doc', `scan: ${rep.scan}`, `report: ${rep.id}`, `origin: ${origin}`];
+  if (rep.parent) fm.push(`parent: ${rep.parent}`);
+  fm.push('---', '');
+  const body = [`# ${rep.title}`, '', `_Made by the agent from the Horizon scan ${rep.scan}. Every claim names its source. The PM has not reviewed it._`, ''];
+  if (!rep.sections.length) body.push('## Findings', '', stopped ? 'The scan was stopped before it filed anything for this report.' : 'The scan filed nothing for this report.', '');
+  for (const sec of rep.sections) {
+    body.push(`## ${sec.heading}`, '', calm(sec.body), '');
+    if (sec.sources.length) body.push('Sources:', ...sec.sources.map(sourceLine), '');
+  }
+  const props = proposalsOf(state, rep.id);
+  body.push('## What next', '');
+  if (!props.length) body.push('The scan raised no proposals for this report.', '');
+  else {
+    for (const p of props) {
+      const f = p.fields || {};
+      const extra = p.kind === 'create' ? ` (board ${f.board}, lane ${f.lane})` : p.kind === 'attach' ? ` (${f.initiative})` : p.kind === 'research' ? ` (${f.depth})` : '';
+      body.push(`- **${PROPOSAL_WORD[p.kind]}:** ${p.title}${extra}. ${p.why} _From: ${p.finding}._`);
+    }
+    body.push('', 'The PM approves, changes or dismisses each proposal in the document sheet. Nothing happens until then.', '');
+  }
+  return { text: fm.join('\n') + body.join('\n'), origin };
+}
+
+/** Write the report documents of a scan that has not written them yet, and append a `report` line (written: true) for each. Safe to call twice.
+ * `reports` is { abs, rel }. → [{ id, path }] */
+function writeReports(file, scanId, { now, reports } = {}) {
+  const out = [];
+  if (!reports) return out;
+  const state = fold(readLines(file));
+  const sc = state.scans.get(scanId);
+  if (!sc) return out;
+  const fileOf = (rel) => path.join(reports.abs, ...rel.split('/').slice(-2));   // scan-<type>/<name>.md inside the reports folder
+  for (const rid of sc.reports) {
+    const rep = state.reports.get(rid);
+    if (!rep || rep.written) continue;
+    // The path was planned when the scan began. A file that appeared since (a second server, the PM) is never overwritten: take the next free name.
+    let rel = rep.path;
+    let abs = fileOf(rel);
+    for (let n = 2; fs.existsSync(abs) && n < 1000; n++) {
+      const parts = rep.path.split('/');
+      parts[parts.length - 1] = parts[parts.length - 1].replace(/\.md$/, '') + `-${n}.md`;
+      rel = parts.join('/');
+      abs = fileOf(rel);
+    }
+    const r = renderReport(state, rep, { at: now, stopped: sc.stopped });
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const tmp = abs + '.tmp-' + process.pid;
+    fs.writeFileSync(tmp, r.text);
+    fs.renameSync(tmp, abs);
+    append(file, { ev: 'report', board: sc.board, scan: sc.scan, id: rep.id, written: true, origin: r.origin, path: rel, sections: rep.sections.length }, { now });
+    out.push({ id: rep.id, path: rel });
+  }
+  return out;
+}
+
 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,
+  LEDGER, KINDS, CADENCES, DEFAULT_CADENCE, EVENTS, LIMITS, SLOT, ORIGINS, MODES, ID_RE, WATCH_RE, SCAN_RE, FINDING_RE, RUN_RE, REPORT_RE, PROPOSAL_RE,
+  REPORT_TYPES, WEB_TYPES, REPORT_LABEL, PROPOSAL_KINDS, DEPTHS, REPORT_ORIGINS, PORTFOLIO,
+  ledgerFile, append, readLines, newId, fold, cadenceOf, settingOf, watchOf, itemsOf, portfolioView, keptItems, hasWatchList, scansOf, openScans, scanDay, lastScan, manualToday,
+  checkWatchItem, checkFinding, checkSection, checkProposal, checkFields, sourceOf, isUrl, urlsIn, words, normUrl, sameWords, duplicateOf, duplicateProposal, readUrls,
+  proposalsOf, waitingProposals, evidenceOf,
+  isWorkingDay, effectiveTypes, dueNow, suggestDue, nextScan, scheduleText, manualCheck, selectScan, stepsOf, setCadence, setSetting, watchOp, hhmm,
+  proposalChange, proposalDismiss, proposalUndo, proposalApprove, addEvidence, beginScan, planPath, renderReport, writeReports, reportsFolder, isReportPath,
 };