create-pmos 0.187.0 → 0.189.0

package/workspace/lib/routes-scan.js

@@ -1,29 +1,49 @@
 'use strict';
-/* routes-scan.js — the Horizon scan's routes (initiative horizon-scan, PRD section 6).
+/* routes-scan.js — the Horizon scan's routes (initiatives horizon-scan and horizon-scan-portfolio, PRD section 7).
  *
- *   GET  /api/scan/board?ws&board   → { ok, ws, board, ledger, cadence, schedule, items: [item], suggested: [item], kept: [item], suggesting, suggest_failed, running, last, next, switched_off }
- *   GET  /api/scan/today?ws         → { ok, ws, ledger, scan: null | { day, at, boards: [{ id, name }], found, matches, fresh, pages, skipped, findings: [finding], failed: [{ board, reason }] } }
- *   POST /api/scan/watch   { ws, board, op: keep | edit | remove | add, id?, name?, kind?, why?, restore? }   → { ok, id, item? }
- *   POST /api/scan/cadence { ws, board, cadence: daily | weekly | off }                                       → { ok, board, cadence }
+ * THE PORTFOLIO ROUTES (horizon-scan-portfolio). One scan for the whole workspace.
+ *   GET  /api/scan/portfolio?ws → { ok, ws, ledger, switched_off, setting, schedule, boards, items, suggested, kept, suggesting, suggest_failed,
+ *                                   last, next, manual, open, reports, proposals_waiting, proposals }
+ *   GET  /api/scan/report?ws&id → { ok, ws, report, markdown, body, written, proposals }
+ *   POST /api/scan/watch    { ws, op: keep | edit | remove | add, id?, name?, kind?, why?, boards?, restore?, board? }   → { ok, id, item? }
+ *   POST /api/scan/setting  { ws, cadence?, repo?, types? }                                      → { ok, setting, schedule }
+ *   POST /api/scan/now      { ws, items?, repo?, types? }                                        → { ok, scan, reports, steps, left }
+ *   POST /api/scan/stop     { ws }                                                               → { ok, scans }
+ *   POST /api/scan/proposal { ws, id, action: approve | change | dismiss | undo, fields?, why? }        → { ok, proposal, result }
  *
- * An item is { id, kind, name, why, ini, added, state: suggested | kept }; `ini` is the initiative a suggestion came from (null for one the PM added). A finding is
- * { id, ask, board, title, match, origin, state } where `state` is the Triage ask's state (open, accepted or declined). `next` is an ISO time or null.
- * `scan` of today is the day's scans across the boards of the workspace read as one: the time of the latest, the boards scanned, the counts and the findings.
+ *   item     { id, kind, name, why, ini, added, state: suggested | kept, boards: [board id] }      `boards` empty = the whole portfolio
+ *   setting  { cadence: daily | weekly | off, repo: boolean, types: [benchmark | competitive | insight | productivity] }
+ *   manual   { limit: 3, used, left, ok, why?, error? }                       `ok` = a manual scan may start now (`why`: running | quiet-hours | manual-limit)
+ *   open     null | { scan, mode: scan | research, manual, start, stopping, steps: [{ id: web | repo | reports, label, state }], reports: [{ id, type, title }], research? }
+ *   report   { id, scan, type, label, title, path, origin: web | repo | both, parent, at, written, sections, proposals: { open, total } }
+ *   proposal { id, report, report_title, kind: create | research | attach, title, why, finding, evidence: [{ label, ref }], fields, state: open | approved | dismissed,
+ *              changed, dismissed_why, result, at, decided_at }
  *
- * WHO WRITES. Both POSTs pass pm-guard requirePagePress, and a request that carries an agent session header is refused first (403), as the driver routes
+ * THE FIRST SCAN'S ROUTES, kept for compatibility and mapped onto the portfolio list:
+ *   GET  /api/scan/board?ws&board   → the portfolio's items that relate to that board, with the workspace cadence, the last scan and the next one
+ *   GET  /api/scan/today?ws         → the day's scan for the Briefing
+ *   POST /api/scan/watch   { ws, board, op, … }       a press from a board lands on the one list, with that board on the item
+ *   POST /api/scan/cadence { ws, board, cadence }     sets the workspace cadence
+ *
+ * WHO WRITES. Every POST passes pm-guard requirePagePress, and a request that carries an agent session header is refused first (403), as the driver routes
  * do. `by` of every line is the guard's actor; the page sends none. The agent writes through `pmos scan` (lib/scan-cli.js) and the scan run, never here.
- * State: <state folder>/scan.jsonl, one per repository (lib/scan.js). Nothing here sends anything outward.
+ * Approve acts only on a PM press: create goes through initiative-writer (lib/routes-boards.js createAndPlace) into the first stage of the board's workflow;
+ * research starts a research scan; attach writes an evidence line. State: <state folder>/scan.jsonl, one per repository (lib/scan.js). The report documents
+ * sit in the report-workspace store (lib/scan.js reportsFolder). Nothing here sends anything outward.
  */
+const fs = require('fs');
+const path = require('path');
 const guard = require('./pm-guard.js');
 const D = require('./driver.js');
 const S = require('./scan.js');
 const scanRun = require('./scan-run.js');
+const proactive = require('./proactive.js');
 
 const text = (v) => (typeof v === 'string' ? v : '');
-const bad = (status, error) => ({ status, body: { ok: false, error } });
-const GETS = ['board', 'today'];
-const POSTS = ['watch', 'cadence'];
-const itemOut = (i) => ({ id: i.id, kind: i.kind, name: i.name, why: i.why, ini: i.ini, added: !!i.added, state: i.state });
+const bad = (status, error, extra) => ({ status, body: { ok: false, error, ...(extra || {}) } });
+const GETS = ['board', 'today', 'portfolio', 'report'];
+const POSTS = ['watch', 'cadence', 'setting', 'now', 'stop', 'proposal'];
+const itemOut = (i) => ({ id: i.id, kind: i.kind, name: i.name, why: i.why, ini: i.ini, added: !!i.added, state: i.state, boards: (i.boards || []).slice() });
 
 function wsOf(ctx, id) {
   const w = ctx.getWs(id || '');
@@ -35,21 +55,84 @@ function ledgerOf(ctx, w) {
 }
 const boardsOf = (ctx, w) => { try { return require('./routes-boards.js').frameFor(ctx, w); } catch { return null; } };
 const settingsOf = (ctx) => { try { return ctx.proSettings ? ctx.proSettings() : null; } catch { return null; } };
+/** The scan's clock: PMOS_SCAN_NOW fixes it in the suites (server.js). */
+const clockOf = (ctx) => { try { const c = ctx.scanClock ? ctx.scanClock() : null; return c && Number.isFinite(c.now) ? c.now : Date.now(); } catch { return Date.now(); } };
+const quietNow = (ctx, now) => { const st = settingsOf(ctx); try { return !!proactive.inQuietHours(now, st && st.quiet); } catch { return false; } };
+
+const reportOut = (state, r) => {
+  const props = S.proposalsOf(state, r.id);
+  return { id: r.id, scan: r.scan, type: r.type, label: S.REPORT_LABEL[r.type], title: r.title, path: r.path, origin: r.origin, parent: r.parent, at: r.writtenAt || r.at, written: r.written,
+    sections: r.sections.length, proposals: { open: props.filter((p) => p.state === 'open').length, total: props.length } };
+};
+const proposalOut = (state, p) => {
+  const r = state.reports.get(p.report);
+  return { id: p.id, report: p.report, report_title: r ? r.title : '', kind: p.kind, title: p.title, why: p.why, finding: p.finding, evidence: p.evidence, fields: p.fields, state: p.state,
+    changed: p.changed, dismissed_why: p.dismissWhy, result: p.result, at: p.at, decided_at: p.decidedAt };
+};
+const openOut = (state, sc) => ({ scan: sc.scan, mode: sc.mode, manual: sc.manual, start: sc.start, stopping: sc.stopped, steps: S.stepsOf(sc),
+  reports: sc.reports.map((id) => { const r = state.reports.get(id); return { id: r.id, type: r.type, title: r.title }; }),
+  ...(sc.research ? { research: { question: sc.research.question, depth: sc.research.depth, parent: sc.research.parent } } : {}) });
+const lastOut = (last) => (last ? { scan: last.scan, at: last.start, end: last.end, ok: last.ok, reason: last.reason, found: last.found, skipped: last.skipped, pages: last.pages, manual: last.manual, stopped: last.stopped } : null);
+
+function manualOut(state, ctx, now) {
+  const chk = S.manualCheck(state, now, { quiet: quietNow(ctx, now), running: !!(ctx.scanner && ctx.scanner.active().length) });
+  return { limit: S.LIMITS.manual, used: chk.used, left: chk.left, ok: !!chk.ok, ...(chk.ok ? {} : { why: chk.why, error: chk.error }) };
+}
+
+function portfolioAnswer(ctx, w, file, now) {
+  const state = S.fold(file ? S.readLines(file) : []);
+  const fr = boardsOf(ctx, w);
+  const dc = (settingsOf(ctx) || {}).dayCheck || {};
+  const wl = S.watchOf(state, null);
+  const last = S.lastScan(state, null);
+  const cadence = S.cadenceOf(state);
+  const next = file ? S.nextScan(state, null, now, { dayEnd: dc.end || '18:00' }) : null;
+  const sug = S.scansOf(state, null, 'suggest');
+  const lastSug = sug.filter((x) => x.end).pop() || null;
+  const open = S.openScans(state).find((x) => x.mode !== 'suggest') || null;
+  const reports = state.reportOrder.map((id) => state.reports.get(id)).reverse().slice(0, 40).map((r) => reportOut(state, r));
+  const waiting = S.waitingProposals(state);
+  return {
+    setting: S.settingOf(state), schedule: S.scheduleText(cadence), boards: ((fr && fr.boards) || []).map((b) => ({ id: b.id, name: b.name })),
+    items: S.itemsOf(state, null).map(itemOut), suggested: wl.suggested.map(itemOut), kept: wl.kept.map(itemOut),
+    suggesting: sug.some((x) => !x.end), suggest_failed: !!(lastSug && lastSug.ok === false && !wl.suggested.length && !wl.kept.length),
+    last: lastOut(last), next: next == null ? null : new Date(next).toISOString(), switched_off: !!scanRun.off(process.env),
+    manual: manualOut(state, ctx, now), open: open ? openOut(state, open) : null, reports,
+    proposals_waiting: waiting.length, proposals: waiting.map((p) => proposalOut(state, p)),
+  };
+}
+
+function reportAnswer(ctx, w, file, id, now) {
+  const state = S.fold(file ? S.readLines(file) : []);
+  const rep = state.reports.get(id);
+  if (!rep) return bad(404, `no report ${String(id).slice(0, 30)} in this workspace`);
+  let markdown = '';
+  if (rep.written && S.isReportPath(rep.path)) {
+    try {
+      const abs = path.resolve(w.root, rep.path);
+      if (abs.startsWith(path.resolve(w.root) + path.sep)) markdown = fs.readFileSync(abs, 'utf8');
+    } catch { markdown = ''; }
+  }
+  // A report still being written has no file yet: show what the runs have filed so far.
+  if (!markdown) { try { markdown = S.renderReport(state, rep, { at: now }).text; } catch { markdown = ''; } }
+  const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  return { status: 200, body: { ok: true, ws: w.id, report: reportOut(state, rep), markdown, body, written: rep.written, proposals: S.proposalsOf(state, rep.id).map((p) => proposalOut(state, p)) } };
+}
 
+/** The first scan's per-board read, mapped onto the portfolio list. */
 function boardAnswer(ctx, w, file, board, now) {
   const state = S.fold(file ? S.readLines(file) : []);
   const wl = S.watchOf(state, board);
-  const last = S.lastScan(state, board);
-  const cadence = S.cadenceOf(state, board);
+  const last = S.lastScan(state, null);
+  const cadence = S.cadenceOf(state);
   const dc = (settingsOf(ctx) || {}).dayCheck || {};
-  const next = file ? S.nextScan(state, board, now, { dayEnd: dc.end || '18:00' }) : null;
-  const sug = S.scansOf(state, board, 'suggest');
-  const openSug = sug.find((x) => !x.end);
+  const next = file ? S.nextScan(state, null, now, { dayEnd: dc.end || '18:00' }) : null;
+  const sug = S.scansOf(state, null, 'suggest');
   const lastSug = sug.filter((x) => x.end).pop() || null;
   return {
     cadence, schedule: S.scheduleText(cadence), items: S.itemsOf(state, board).map(itemOut), suggested: wl.suggested.map(itemOut), kept: wl.kept.map(itemOut),
-    suggesting: !!openSug, suggest_failed: !!(lastSug && lastSug.ok === false && !wl.suggested.length && !wl.kept.length),
-    running: S.openScans(state).some((x) => x.board === board && x.mode === 'scan'),
+    suggesting: sug.some((x) => !x.end), suggest_failed: !!(lastSug && lastSug.ok === false && !wl.suggested.length && !wl.kept.length),
+    running: S.openScans(state).some((x) => x.mode === 'scan'),
     last: last ? { scan: last.scan, at: last.start, end: last.end, ok: last.ok, reason: last.reason, found: last.found, skipped: last.skipped, pages: last.pages } : null,
     next: next == null ? null : new Date(next).toISOString(), switched_off: !!scanRun.off(process.env),
   };
@@ -60,25 +143,21 @@ function todayAnswer(ctx, w, file, now) {
   const day = D.localDay(now);
   const done = state.scanOrder.map((id) => state.scans.get(id)).filter((x) => x.mode === 'scan' && x.end && x.start && D.localDay(Date.parse(x.start)) === day);
   if (!done.length) return null;
-  const fr = boardsOf(ctx, w);
-  const names = new Map(((fr && fr.boards) || []).map((b) => [b.id, b.name]));
-  let asks = new Map();
-  try { asks = fr ? fr.folded.asks : new Map(); } catch { asks = new Map(); }
-  const boards = []; const findings = []; const failed = [];
+  const findings = []; const failed = []; const reports = [];
   let pages = 0; let skipped = 0; let latest = done[0];
   for (const sc of done) {
     if (Date.parse(sc.start) >= Date.parse(latest.start)) latest = sc;
-    if (!boards.some((b) => b.id === sc.board)) boards.push({ id: sc.board, name: names.get(sc.board) || sc.board });
     pages += sc.pages || 0; skipped += sc.skipped || 0;
     if (sc.ok === false && sc.reason) failed.push({ board: sc.board, reason: sc.reason });
     for (const fid of sc.findings) {
       const f = state.findings.get(fid);
-      const ask = asks.get('ask-' + fid.replace(/^f-/, ''));
-      findings.push({ id: f.id, ask: ask ? ask.id : null, board: f.board, title: f.title, match: f.match, origin: f.origin, state: ask ? ask.state : null });
+      findings.push({ id: f.id, ask: null, board: f.board, title: f.title, match: f.match, origin: f.origin, state: null });
     }
+    for (const rid of sc.reports) reports.push(reportOut(state, state.reports.get(rid)));
   }
   const matches = findings.filter((f) => f.match).length;
-  return { day, at: latest.start, boards, found: findings.length, matches, fresh: findings.length - matches, pages, skipped, findings, failed };
+  return { day, at: latest.start, boards: [{ id: latest.board, name: 'Portfolio' }], found: findings.length, matches, fresh: findings.length - matches, pages, skipped, findings, failed,
+    reports, proposals_waiting: S.waitingProposals(state).length };
 }
 
 async function handle(req, res, url, ctx) {
@@ -92,10 +171,14 @@ async function handle(req, res, url, ctx) {
     const w = wsOf(ctx, url.searchParams.get('ws'));
     if (!w) return send(bad(404, 'no such workspace'));
     const file = ledgerOf(ctx, w);
-    // the same clock the scheduler uses: PMOS_SCAN_NOW (server.js scanClock) fixes it, so a suite's scan is "today" on any date
-    const fixed = Date.parse(process.env.PMOS_SCAN_NOW || '');
-    const now = Number.isFinite(fixed) ? fixed : Date.now();
+    const now = clockOf(ctx);
     if (sub === 'today') return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, scan: todayAnswer(ctx, w, file, now) } });
+    if (sub === 'portfolio') return send({ status: 200, body: { ok: true, ws: w.id, ledger: !!file, ...portfolioAnswer(ctx, w, file, now) } });
+    if (sub === 'report') {
+      const id = text(url.searchParams.get('id'));
+      if (!S.REPORT_RE.test(id)) return send(bad(400, 'id must be a report id'));
+      return send(reportAnswer(ctx, w, file, id, now));
+    }
     const board = text(url.searchParams.get('board')) || w.id;
     if (!S.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
     const fr = boardsOf(ctx, w);
@@ -107,26 +190,123 @@ async function handle(req, res, url, ctx) {
   const read = await ctx.readJson(req);
   if (!read.ok) return send(bad(400, 'the body is not JSON'));
   const body = read.body;
-  if (req.headers && req.headers['x-pmos-session']) return send(bad(403, 'an agent session cannot change the watch list or the scan cadence'));
+  if (req.headers && req.headers['x-pmos-session']) return send(bad(403, 'an agent session cannot change the watch list, the scan setting or a proposal, start a scan or stop one'));
   const g = guard.requirePagePress(req, body);
   if (!g.ok) return send(bad(g.status, g.error));
   const w = wsOf(ctx, text(body.ws));
   if (!w) return send(bad(404, 'no such workspace'));
   const file = ledgerOf(ctx, w);
   if (!file) return send(bad(409, 'this repository has no state folder (pmos/state, state or .pmos), so the scan has nowhere to keep its ledger'));
-  const board = text(body.board);
-  if (!board || !S.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
-  const fr = boardsOf(ctx, w);
-  if (fr && !fr.boards.some((b) => b.id === board)) return send(bad(404, `no board ${board.slice(0, 40)} in this workspace`));
+  const now = clockOf(ctx);
 
+  // An optional board (the first scan's presses name one). When it is named it must exist.
+  const boardGiven = body.board !== undefined && body.board !== null && body.board !== '';
+  let board = null;
+  if (boardGiven && (sub === 'watch' || sub === 'cadence')) {
+    board = text(body.board);
+    if (!S.ID_RE.test(board)) return send(bad(400, 'board must be a board id'));
+    const fr = boardsOf(ctx, w);
+    if (fr && !fr.boards.some((b) => b.id === board)) return send(bad(404, `no board ${board.slice(0, 40)} in this workspace`));
+  }
   if (sub === 'cadence') {
-    const r = S.setCadence(file, board, text(body.cadence), g.actor);
+    const r = S.setCadence(file, board, text(body.cadence), g.actor, { now });
+    if (!r.ok) return send(bad(r.status, r.error));
+    return send({ status: 200, body: { ok: true, ...(board ? { board } : {}), cadence: r.cadence, schedule: S.scheduleText(r.cadence) } });
+  }
+  if (sub === 'watch') {
+    const r = S.watchOp(file, text(body.op), board, { id: body.id, name: body.name, kind: body.kind, why: body.why, restore: body.restore === true, ...(body.boards !== undefined ? { boards: body.boards } : {}) }, g.actor, { now });
     if (!r.ok) return send(bad(r.status, r.error));
-    return send({ status: 200, body: { ok: true, board: r.board, cadence: r.cadence, schedule: S.scheduleText(r.cadence) } });
+    return send({ status: 200, body: { ok: true, id: r.id, ...(r.item ? { item: r.item } : {}) } });
+  }
+  if (sub === 'setting') {
+    const r = S.setSetting(file, { cadence: body.cadence, repo: body.repo, types: body.types }, g.actor, { now });
+    if (!r.ok) return send(bad(r.status, r.error));
+    return send({ status: 200, body: { ok: true, setting: r.setting, schedule: S.scheduleText(r.setting.cadence) } });
+  }
+
+  // The runs live in the server's scanner; a context without one cannot start or stop a scan.
+  if (sub === 'now' || sub === 'stop') {
+    if (!ctx.scanner) return send(bad(503, 'the scanner is not running in this server'));
+    if (sub === 'now') {
+      const r = ctx.scanner.startNow(w, { items: body.items, repo: body.repo, types: body.types }, { now, by: g.actor.by });
+      if (!r.ok) return send(bad(r.status || 409, r.error, { ...(r.why ? { why: r.why } : {}), ...(r.left !== undefined ? { left: r.left, used: r.used } : {}) }));
+      return send({ status: 200, body: { ok: true, scan: r.scan, reports: r.reports, steps: r.steps, left: r.left } });
+    }
+    const r = ctx.scanner.stop(w, { now, by: g.actor.by });
+    if (!r.ok) return send(bad(r.status || 409, r.error));
+    return send({ status: 200, body: { ok: true, scans: r.scans } });
+  }
+
+  return send(proposalPress(ctx, w, file, body, g, now));
+}
+
+/** POST /api/scan/proposal. Nothing happens without this press. */
+function proposalPress(ctx, w, file, body, g, now) {
+  const id = text(body.id);
+  if (!S.PROPOSAL_RE.test(id)) return bad(400, 'id must be a proposal id');
+  const action = text(body.action);
+  if (!['approve', 'change', 'dismiss', 'undo'].includes(action)) return bad(400, 'action must be approve, change, dismiss or undo');
+  let state = S.fold(S.readLines(file));
+  const p0 = state.proposals.get(id);
+  if (!p0) return bad(404, `no proposal ${id}`);
+  // Undo takes back a dismissal or a change. Approve cannot be undone (it made an initiative or started runs), so the proposal is not open then.
+  if (action === 'undo') {
+    const r = S.proposalUndo(file, id, g.actor, { now });
+    if (!r.ok) return bad(r.status, r.error);
+    const st = S.fold(S.readLines(file));
+    return { status: 200, body: { ok: true, proposal: proposalOut(st, st.proposals.get(id)) } };
+  }
+  if (p0.state !== 'open') return bad(409, `the proposal is ${p0.state} already`);
+  const answer = (extra) => { const st = S.fold(S.readLines(file)); return { status: 200, body: { ok: true, proposal: proposalOut(st, st.proposals.get(id)), ...extra } }; };
+
+  if (action === 'dismiss') {
+    const r = S.proposalDismiss(file, id, body.why, g.actor, { now });
+    if (!r.ok) return bad(r.status, r.error);
+    // A dismissed proposal is a correction signal, as a declined scan ask is. A later scan does not raise the same title again (lib/scan.js duplicateProposal).
+    require('./routes-boards.js').scanDeclineSignal(ctx, { found: { run: p0.run, scan: p0.scan } });
+    return answer({});
+  }
+  if (body.fields !== undefined || action === 'change') {
+    const r = S.proposalChange(file, id, body.fields, g.actor, { now });
+    if (!r.ok) return bad(r.status, r.error);
+    if (action === 'change') return answer({});
+    state = S.fold(S.readLines(file));
+  }
+  const p = state.proposals.get(id);
+  const rep = state.reports.get(p.report);
+
+  if (p.kind === 'create') {
+    const boards = require('./routes-boards.js');
+    const f = p.fields;
+    const input = { title: p.title, lane: f.lane, anchor: f.anchor, intent: f.intent };
+    const made = boards.createAndPlace(ctx, w, f.board, input, g.actor, ({ file: bfile, board: b, initiative, stage }) => {
+      boards.append(bfile, g.actor, { kind: 'assign', board: b.id, id: initiative, to: b.id });
+      boards.append(bfile, g.actor, { kind: 'move', board: b.id, id: initiative, from: null, to: stage, why: 'proposed by the Horizon scan', warnings: [] });
+    });
+    if (!made.ok) return bad(made.status || 400, made.error, { field: made.field || null });
+    S.proposalApprove(file, id, { initiative: made.initiative.id, path: made.initiative.path, board: made.board, stage: made.stage }, g.actor, { now });
+    S.addEvidence(file, { initiative: made.initiative.id, report: p.report, proposal: id, note: p.finding }, g.actor, { now });
+    return answer({ result: { initiative: made.initiative, board: made.board, stage: made.stage } });
+  }
+  if (p.kind === 'attach') {
+    // The initiative must exist: evidence for an id that is not there is a dead link. While the rows are still being read, the PM presses again.
+    let known = null;
+    try {
+      const rows = require('./routes-boards.js').baseRows(w);
+      if (rows.pending) return bad(409, 'The initiatives are being read. Ask again in a few seconds.');
+      known = rows.ok ? rows.rows.some((x) => x.id === p.fields.initiative) : null;
+    } catch { known = null; }
+    if (known === false) return bad(404, `no initiative ${String(p.fields.initiative).slice(0, 60)} in this workspace`);
+    S.proposalApprove(file, id, { initiative: p.fields.initiative }, g.actor, { now });
+    S.addEvidence(file, { initiative: p.fields.initiative, report: p.report, proposal: id, note: p.finding }, g.actor, { now });
+    return answer({ result: { initiative: p.fields.initiative } });
   }
-  const r = S.watchOp(file, text(body.op), board, { id: body.id, name: body.name, kind: body.kind, why: body.why, restore: body.restore === true }, g.actor);
-  if (!r.ok) return send(bad(r.status, r.error));
-  return send({ status: 200, body: { ok: true, id: r.id, ...(r.item ? { item: r.item } : {}) } });
+  // research: a web run that gets only the approved question and the public sources, then a repository run that files the follow-up's proposals.
+  if (!ctx.scanner) return bad(503, 'the scanner is not running in this server');
+  const r = ctx.scanner.startResearch(w, p, { now, by: g.actor.by });
+  if (!r.ok) return bad(r.status || 409, r.error);
+  S.proposalApprove(file, id, { scan: r.scan, report: r.reports[0].id, parent: rep ? rep.id : null }, g.actor, { now });
+  return answer({ result: { scan: r.scan, report: r.reports[0].id, parent: rep ? rep.id : null, steps: r.steps } });
 }
 
-module.exports = { prefixes: ['/api/scan'], handle, boardAnswer, todayAnswer };
+module.exports = { prefixes: ['/api/scan'], handle, boardAnswer, todayAnswer, portfolioAnswer, reportAnswer };