create-pmos 0.188.0 → 0.189.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.188.0",
+  "version": "0.189.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@856b541
+kernel-source: pmos@372629f
 assembled: 2026-10-13
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-13T06:02:00Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T06:07:37Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-13T06:02:00Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T06:07:37Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-13T06:02:00Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T06:07:37Z"}
 status: stable
 ---
 

package/workspace/c3-report-setup-test.js

@@ -51,7 +51,7 @@ const TAB = '[data-rs-tab]';
   /* two reads of other initiatives (Horizon scan, Settings) have no demo answer: a 404 on them is not this suite's */
   const watch = (page) => {
     page.on('pageerror', (e) => errors.push('pageerror: ' + String((e && e.message) || e)));
-    page.on('response', (r) => { if (r.status() >= 400 && !/\/api\/(scan\/today|settings)\b/.test(r.url())) errors.push('http ' + r.status() + ' ' + r.url()); });
+    page.on('response', (r) => { if (r.status() >= 400 && !/\/api\/(scan\/(?:today|portfolio)|settings)\b/.test(r.url())) errors.push('http ' + r.status() + ' ' + r.url()); });
     page.on('dialog', (d) => d.dismiss().catch(() => {}));
   };
   const ctx = await browser.newContext({ viewport: { width: 1440, height: 1000 } });

package/workspace/c3-scan-fixture.js

@@ -3,9 +3,27 @@
  * Not a suite: it asserts nothing. The server runs with PMOS_DRIVER=off, so no scan and no suggest run starts: every suggestion, scan and
  * finding the page shows is a line this file wrote with lib/scan.js (the single writer) and the boards ledger.
  *
- *   const F = await start({ name })  -> { BASE, ws, board, team, ledger, boards, post, get, seedScan, stop, S }
+ *   const F = await start({ name })  -> { BASE, ws, board, team, ledger, boards, post, get, seedScan, portfolio, stop, S }
  *   at start: the board holds three suggestions from the agent (a product, a domain, an approach) and no scan has run
  *   seedScan() writes one finished scan of today: 2 web findings and 1 repository finding, each already an open Triage ask
+ *
+ * THE PORTFOLIO SCAN (initiative horizon-scan-portfolio). The page reads and presses /api/scan/portfolio, /report, /watch, /setting, /now, /stop
+ * and /proposal. Two ways to answer them, both over lib/scan.js:
+ *   - the model (portfolioStub): the page's /api/scan/** calls are routed in the browser to a ledger of its own. The answers are the REAL view
+ *     functions (lib/routes-scan.js portfolioAnswer and reportAnswer, over lib/scan.js fold) and the presses are the real lib/scan.js functions
+ *     (watchOp, setSetting, selectScan, manualCheck, proposalChange, proposalDismiss, proposalUndo, proposalApprove), so every field is the
+ *     server's. What it does not do is run a headless agent: a test moves the open scan with advance(). Create does not make a real initiative.
+ *   - the real server (seedPortfolio): the server's own ledger seeded with the same lines, no routing, for the end-to-end section.
+ * The report documents are real markdown files in the scratch repository's report folder, read by the document sheet through GET /api/doc.
+ *
+ *   const P = F.portfolio()                 a fresh model: 4 suggested watch items, cadence daily, no scan yet
+ *   await P.install(page)                   route /api/scan/** of this page to the model; P.calls lists every request { method, path, body }
+ *   P.advance()                             the open scan moves one step (web, repository, then the end: reports written, proposals filed)
+ *   P.seed()                                a finished scan: the list kept, the reports written, the proposals filed
+ *   P.research()                            the research scan of an approved research proposal ends; its follow-up document is written
+ *   P.reportOf(type)                        the latest written top-level report of a type (id, path, title)
+ *   P.fail = { path, status?, why?, error } the next request to that path answers { ok:false, error, why? } with that status
+ *   const T = F.tools({ file, team, ws })   the ledger lines of a scan (suggest, begin, finish, seedFinished)
  */
 const fs = require('fs');
 const path = require('path');
@@ -20,7 +38,7 @@ async function call(base, method, p, body, headers) {
   return { status: r.status, body: j, raw };
 }
 
-async function start({ name = 'c3-scan' } = {}) {
+async function start({ name = 'c3-scan', clean = false, guard = false } = {}) {
   const R = makeRepos(name);
   const team = codeRepo(path.join(R.base, 'team'));
   fs.mkdirSync(path.join(team, 'pmos', 'state'), { recursive: true });
@@ -29,8 +47,12 @@ async function start({ name = 'c3-scan' } = {}) {
   const ledger = path.join(team, 'pmos', 'state', 'scan.jsonl');
   const boards = path.join(team, 'pmos', 'state', 'boards.jsonl');
   const BASE = T.BASE;
+  // guard: a `claude` on the PATH that only records that it was called, for the end-to-end section. The server also runs with PMOS_DRIVER=off, so none is ever called.
+  const rec = path.join(R.base, 'claude-calls'); fs.mkdirSync(rec, { recursive: true });
+  const bin = path.join(R.base, 'bin'); fs.mkdirSync(bin, { recursive: true });
+  fs.writeFileSync(path.join(bin, 'claude'), `#!/bin/sh\ndate +%s%N > "${rec}/call.$$"\nprintf '%s\\n' "$@" >> "${rec}/call.$$"\necho '{"type":"result","subtype":"success","is_error":false,"result":"Done.","num_turns":1,"duration_ms":1,"permission_denials":[]}'\n`, { mode: 0o755 });
   const srv = spawn(process.execPath, [path.join(__dirname, 'server.js')], { cwd: __dirname, stdio: 'ignore',
-    env: T.env({ PMOS_WS_PORT: String(T.PORT), PMOS_SELF_ROOT: team, PMOS_NO_OPEN: '1', PMOS_DRIVER: 'off' }) });
+    env: T.env({ PMOS_WS_PORT: String(T.PORT), PMOS_SELF_ROOT: team, PMOS_NO_OPEN: '1', PMOS_DRIVER: 'off', ...(guard ? { PATH: bin + path.delimiter + process.env.PATH } : {}) }) });
   await T.waitForServer(BASE);
   const press = await T.pressHeaders(BASE);
   const post = (p, body) => call(BASE, 'POST', p, body, press);
@@ -41,11 +63,13 @@ async function start({ name = 'c3-scan' } = {}) {
   if (made.status !== 200) throw new Error('could not create the initiative: ' + made.raw);
   const now = Date.now();
   const w = (line, at) => S.append(ledger, line, { now: at });
+  if (!clean) {
   w({ ev: 'scan-start', board: ws, scan: 'scan-0000000001', mode: 'suggest', watch: [] }, now - 3600000 * 30);
   w({ ev: 'watch-suggest', board: ws, id: 'w-00000001', kind: 'product', name: 'Rival Notes', why: 'A direct rival in partner onboarding', ini: 'scan-ui' }, now - 3600000 * 30);
   w({ ev: 'watch-suggest', board: ws, id: 'w-00000002', kind: 'domain', name: 'Data privacy law', why: 'We store partner emails', ini: 'scan-ui' }, now - 3600000 * 30);
   w({ ev: 'watch-suggest', board: ws, id: 'w-00000003', kind: 'approach', name: 'Eval-first delivery', why: 'How other teams write the test before the build', ini: 'scan-ui' }, now - 3600000 * 30);
   w({ ev: 'scan-end', board: ws, scan: 'scan-0000000001', ok: true, pages: 0, found: 3, skipped: 0, runs: 1 }, now - 3600000 * 30 + 60000);
+  }
 
   /** One finished scan of today, with its three findings as open Triage asks. */
   function seedScan() {
@@ -72,7 +96,225 @@ async function start({ name = 'c3-scan' } = {}) {
     w({ ev: 'scan-end', board: ws, scan, ok: true, pages: 12, found: 3, skipped: 1, runs: 2 }, t + 60000);
     return { scan, findings: F.map((f) => f.id), asks: F.map((f) => 'ask-' + f.id.slice(2)) };
   }
+  const portfolio = () => portfolioStub({ team, ws });
+  /** The real server's ledger, seeded for the end-to-end section: three suggestions, one of them kept and scanned in a finished scan of today (four reports, five proposals). */
+  function seedPortfolio() {
+    const L = tools({ file: ledger, team, ws });
+    const items = [
+      { id: 'w-00000021', kind: 'product', name: 'Stripe Connect', why: 'Partner onboarding looks like platform onboarding.', ini: 'scan-ui', boards: [ws] },
+      { id: 'w-00000022', kind: 'domain', name: 'API rate limits and quotas', why: 'Partners ask about limits.', ini: 'scan-ui', boards: [ws] },
+      { id: 'w-00000023', kind: 'approach', name: 'Self-serve sandbox keys', why: 'Partners wait days for access.', ini: 'scan-ui', boards: [] }];
+    L.suggest(items, now - 3600000 * 30);
+    const b = L.seedFinished(2, { items: [{ ...items[0], state: 'suggested' }], at: now - 600000, ini: 'scan-ui' });
+    return { items, scan: b.scan, reports: b.reports };
+  }
   const stop = () => { try { srv.kill('SIGKILL'); } catch { /* gone */ } T.killTmux(); R.cleanup(); };
-  return { BASE, ws, board: ws, team, ledger, boards, post, get, seedScan, stop, T, S };
+  const calls = () => fs.readdirSync(rec).filter((f) => f.startsWith('call.'));
+  return { BASE, ws, board: ws, team, ledger, boards, post, get, seedScan, seedPortfolio, portfolio, calls, stop, T, S };
+}
+
+/* ── the ledger tools: every line below is written by lib/scan.js append (the single writer) and read back by its fold and view functions ── */
+const AG = 'agent:sess-4.0a1b2c3d';
+const PM = { by: 'pm:wawan' };
+const hex = (n, w = 10) => n.toString(16).padStart(w, '0');
+/** The agent's work as ledger lines: a finished portfolio scan with its report documents and proposals. `file` is the ledger, `team` the repository root. */
+function tools({ file, team, ws }) {
+  const reports = S.reportsFolder(team);
+  const w = (line, at) => S.append(file, line, { now: at });
+  const day = (at) => require('./lib/driver.js').localDay(at);
+  const TYPES = ['benchmark', 'competitive', 'insight', 'productivity'];
+  const TITLE = { benchmark: 'Benchmark report: partner onboarding', competitive: 'Competitive analysis: identity and login', insight: 'Insight report: themes across boards', productivity: 'Productivity report: portfolio delivery' };
+  const idOf = (n, type, kind) => `${kind}-${hex(n, 8)}${hex(TYPES.indexOf(type) + 1, 2)}`;
+  const EV = (label, ref) => ({ label, ref });
+  /** What the repository run files for a report type: its sections, and its proposals. Proposals name the board of the portfolio and an initiative that exists. */
+  const FILED = (type, n, ini) => ({
+    benchmark: { sections: [
+      ['Summary', 'web', 'We compared partner onboarding at Stripe Connect and Twilio with ours on four points. We are behind on two.'],
+      ['Gaps', 'repo', '- Gap 1: 9 days to first API call (IDPF-1177).\n- Gap 2: no changelog. Partners ask support what changed (IDPF-1402).'],
+      ['Where we stand', 'repo', '- Level on rate-limit visibility since Tue 6 Oct.']],
+    proposals: [
+      { id: idOf(n, type, 'p'), kind: 'create', title: 'Publish a subscribable API changelog and change notices', why: 'All benchmarks publish a dated changelog. Four Jira tickets and one Slack thread here ask what changed.', finding: 'Gap 2: no changelog',
+        evidence: [EV('Stripe changelog', 'https://docs.stripe.com/changelog'), EV('Jira', 'IDPF-1402'), EV('Support thread', '#partner-support, 7 Oct')],
+        fields: { board: ws, lane: 'feature', anchor: 'health:tech', intent: 'Partners learn about API changes from one dated page and an email they can subscribe to.' } },
+      { id: idOf(n + 1000, type, 'p'), kind: 'research', title: 'Deep dive: rate-limit headers across 6 API vendors', why: 'The benchmark cannot say which header set partners expect.', finding: 'Where we stand: level on rate-limit visibility',
+        evidence: [EV('Stripe rate limits', 'https://docs.stripe.com/rate-limits'), EV('Jira', 'IDPF-1214'), EV('Options paper', 'docs/options/IDPF-07.md')],
+        fields: { question: 'Which rate-limit headers do 6 API vendors send, and which set should the Partner API adopt?', depth: 'standard' } },
+      { id: idOf(n + 2000, type, 'p'), kind: 'attach', title: `Attach the first-call benchmark to ${ini} as evidence`, why: 'The initiative targets 5 days to first API call. All benchmarks reach a first call the same day.', finding: 'Gap 1: 9 days to first API call',
+        evidence: [EV('Stripe testing', 'https://docs.stripe.com/connect/testing'), EV('DSU note', 'IDPF DSU, 8 Oct')], fields: { initiative: ini } }] },
+    competitive: { sections: [['Summary', 'web', 'Passkeys are the one gap that could cost deals.'], ['Openings', 'web', '- Opening: partner-centric accounts.']],
+      proposals: [{ id: idOf(n, type, 'p'), kind: 'create', title: 'Organisation accounts and SSO for partner admins', why: 'Cognito and Firebase leave organisation accounts to the customer.', finding: 'Opening: partner-centric accounts',
+        evidence: [EV('Auth0 organizations', 'https://auth0.com/docs/manage-users/organizations'), EV('Partner council', 'Partner council, 1 Oct')],
+        fields: { board: ws, lane: 'discovery', anchor: 'health:tech', intent: 'Find out whether partner admins need organisation accounts and SSO.' } }] },
+    insight: { sections: [['Summary', 'repo', 'Four themes repeat across boards.']], proposals: [] },
+    productivity: { sections: [['Summary', 'repo', 'Delivery slowed on IDPF. Most of it is one shared QA environment.']], proposals: [] },
+  })[type];
+  const planFor = (types, items, repo) => ({ web: items > 0 && types.some((t) => t !== 'productivity'), repo: !!repo });
+
+  /** A suggest run that filed the given watch items (each { id, kind, name, why, ini, boards }). */
+  function suggest(items, at) {
+    const scan = 'scan-' + hex(1);
+    w({ ev: 'scan-start', board: S.PORTFOLIO, scan, mode: 'suggest', watch: [], manual: false, repo: true, types: [], plan: { web: false, repo: true } }, at);
+    items.forEach((it, i) => w({ ev: 'watch-suggest', scan, boards: it.boards || [], id: it.id, kind: it.kind, name: it.name, why: it.why, ini: it.ini, by: AG }, at + 1000 * (i + 1)));
+    w({ ev: 'scan-end', board: S.PORTFOLIO, scan, ok: true, pages: 0, found: items.length, skipped: 0, runs: 1 }, at + 60000);
+    return scan;
+  }
+  /** The scan-start and report lines of a scan. → { scan, reports: [{ id, type, title, path }] } */
+  function begin(n, { types, items, repo, manual = false, at, research = null }) {
+    const scan = 'scan-' + hex(0xa0 + n, 10);
+    const select = { items: items.map((i) => i.id), repo, types };
+    w({ ev: 'scan-start', board: S.PORTFOLIO, scan, mode: research ? 'research' : 'scan', watch: items.map((i) => ({ id: i.id, kind: i.kind, name: i.name, why: i.why || '' })), manual, repo, types, plan: planFor(types, items.length, repo),
+      ...(manual ? { by: PM.by, select } : {}), ...(research ? { research } : {}) }, at);
+    const out = [];
+    const list = research ? ['insight'] : types;
+    list.forEach((type, i) => {
+      const id = idOf(n, type, 'r');
+      let name = day(at) + '.md'; let k = 2;
+      while (fs.existsSync(path.join(reports.abs, 'scan-' + type, name)) || out.some((o) => o.path.endsWith('/scan-' + type + '/' + name))) name = day(at) + '-' + (k++) + '.md';
+      const rel = `${reports.rel}/scan-${type}/${name}`;
+      const title = research ? 'Research: ' + String(research.question).slice(0, 80) : TITLE[type];
+      w({ ev: 'report', board: S.PORTFOLIO, scan, id, type, title, path: rel, origin: type === 'productivity' ? 'repo' : 'both', ...(research ? { parent: research.parent } : {}) }, at + 100 + i);
+      out.push({ id, type, title, path: rel });
+    });
+    return { scan, reports: out };
+  }
+  const runStart = (scan, origin, at) => w({ ev: 'run-start', board: S.PORTFOLIO, scan, run: 'srun-' + hex(origin === 'web' ? 1 : 2), origin }, at);
+  const runEnd = (scan, origin, at) => w({ ev: 'run-end', board: S.PORTFOLIO, scan, run: 'srun-' + hex(origin === 'web' ? 1 : 2), origin, ok: true }, at);
+  /** The sections and proposals the runs filed, the report files, and the scan-end line. */
+  function finish(n, b, { at, ini, pages = 31, skipped = 2, ok = true, reason = null, stopped = false } = {}) {
+    if (!stopped) {
+      for (const r of b.reports) {
+        if (b.research) break;
+        const f = FILED(r.type, n, ini);
+        f.sections.forEach(([heading, origin, body], i) => w({ ev: 'section', scan: b.scan, report: r.id, heading, body, origin, sources: origin === 'web' ? [{ label: 'Stripe', ref: 'https://docs.stripe.com/changelog' }] : [], by: AG }, at + 200 + i));
+        f.proposals.forEach((p, i) => w({ ev: 'proposal', scan: b.scan, report: r.id, ...p, by: AG }, at + 300 + i));
+      }
+    }
+    S.writeReports(file, b.scan, { now: at + 400, reports });
+    w({ ev: 'scan-end', board: S.PORTFOLIO, scan: b.scan, ok, ...(reason ? { reason } : {}), pages, found: stopped ? 0 : b.reports.length, skipped, runs: 2, reports: b.reports.length }, at + 500);
+  }
+  /** A whole finished scan in the ledger: the watch list kept, both runs, the reports and their proposals. */
+  function seedFinished(n, { items, at, ini, types = TYPES }) {
+    items.forEach((i) => { if (i.state !== 'kept') w({ ev: 'watch-keep', id: i.id, by: PM.by }, at - 60000); });
+    const b = begin(n, { types, items, repo: true, at });
+    runStart(b.scan, 'web', at + 10); runEnd(b.scan, 'web', at + 20); runStart(b.scan, 'repo', at + 30); runEnd(b.scan, 'repo', at + 40);
+    finish(n, b, { at: at + 50, ini });
+    return b;
+  }
+  return { reports, TYPES, TITLE, suggest, begin, runStart, runEnd, finish, seedFinished, w, day };
+}
+
+/* ── the portfolio model: a ledger of its own, read through lib/routes-scan.js (the answers) and written through lib/scan.js (the presses) ── */
+function portfolioStub({ team, ws }) {
+  const RS = require('./lib/routes-scan.js');
+  const dir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'c3-scan-stub-'));
+  const file = path.join(dir, 'scan.jsonl');
+  const T0 = Date.now();
+  const L = tools({ file, team, ws });
+  const wnow = { id: ws, root: team };
+  const ctx = { scanner: { active: () => [] }, proSettings: () => null, scanClock: () => ({}) };
+  const M = { calls: [], fail: null, n: 1, cur: null, file, tools: L };
+  L.suggest([
+    { id: 'w-00000011', kind: 'product', name: 'Stripe Connect', why: 'Partner onboarding looks like platform onboarding. This is the usual reference.', ini: 'IDPF-12', boards: [ws] },
+    { id: 'w-00000012', kind: 'product', name: 'Twilio developer onboarding', why: 'They set the bar for sign-up to first API call.', ini: 'IDPF-12', boards: [ws] },
+    { id: 'w-00000013', kind: 'domain', name: 'API rate limits and quotas', why: 'Partners ask about limits.', ini: 'IDPF-07', boards: [ws] },
+    { id: 'w-00000014', kind: 'approach', name: 'Self-serve sandbox keys', why: 'Partners wait days for access.', ini: 'IDPF-12', boards: [ws] }], T0 - 3600000 * 30);
+  const state = () => S.fold(S.readLines(file));
+  M.seq = 0;
+  const tick = () => T0 - 300000 + (++M.seq) * 100;   // each line a moment after the one before, all in the past
+  const view = () => ({ ok: true, ws, ledger: true, ...RS.portfolioAnswer(ctx, wnow, file, Date.now()) });
+  const open = () => S.openScans(state()).find((x) => x.mode !== 'suggest') || null;
+  const kept = () => S.keptItems(state(), null);
+  /** The open scan moves one step: web ends and the repository run starts, the repository run ends, then the scan finishes. */
+  function advance() {
+    const sc = open(); if (!sc || sc.mode === 'research') return;
+    const b = M.cur; const st = S.stepsOf(sc);
+    if (st[0].state === 'running') { L.runEnd(sc.scan, 'web', tick()); if (sc.plan.repo) L.runStart(sc.scan, 'repo', tick()); } else if (st[1].state === 'running') L.runEnd(sc.scan, 'repo', tick());
+    else finishScan(b);
+  }
+  function finishScan(b, o = {}) { L.finish(b.n, b, { at: tick(), ini: 'scan-ui', ...o }); M.cur = null; }
+  const press = {
+    watch(body) {
+      const r = S.watchOp(file, body.op, null, { id: body.id, name: body.name, kind: body.kind, why: body.why, restore: body.restore === true, ...(body.boards !== undefined ? { boards: body.boards } : {}) }, PM, { now: tick() });
+      return r.ok ? { status: 200, body: { ok: true, id: r.id, ...(r.item ? { item: r.item } : {}) } } : { status: r.status, body: { ok: false, error: r.error } };
+    },
+    setting(body) {
+      const r = S.setSetting(file, { cadence: body.cadence, repo: body.repo, types: body.types }, PM, { now: tick() });
+      return r.ok ? { status: 200, body: { ok: true, setting: r.setting, schedule: S.scheduleText(r.setting.cadence) } } : { status: r.status, body: { ok: false, error: r.error } };
+    },
+    now(body) {
+      const st = state();
+      const chk = S.manualCheck(st, Date.now(), { quiet: false, running: false });
+      if (!chk.ok) return { status: chk.status, body: { ok: false, error: chk.error, why: chk.why, used: chk.used, left: chk.left } };
+      const sel = S.selectScan(st, { items: body.items, repo: body.repo, types: body.types });
+      if (!sel.ok) return { status: sel.status, body: { ok: false, error: sel.error } };
+      const at = tick();
+      const b = L.begin(++M.n, { types: sel.types, items: sel.items, repo: sel.repo, manual: true, at });
+      b.n = M.n; M.cur = b;
+      if (sel.plan.web) L.runStart(b.scan, 'web', tick()); else L.runStart(b.scan, 'repo', tick());
+      const sc = state().scans.get(b.scan);
+      return { status: 200, body: { ok: true, scan: b.scan, reports: b.reports, steps: S.stepsOf(sc), left: chk.left - 1 } };
+    },
+    stop() {
+      const sc = open(); if (!sc) return { status: 409, body: { ok: false, error: 'No scan is running.' } };
+      S.append(file, { ev: 'scan-stop', board: sc.board, scan: sc.scan, by: PM.by }, { now: tick() });
+      if (M.cur && M.cur.scan === sc.scan) finishScan(M.cur, { ok: false, reason: 'stopped by the PM', stopped: true }); else L.w({ ev: 'scan-end', board: sc.board, scan: sc.scan, ok: false, reason: 'stopped by the PM', pages: 0, found: 0, skipped: 0, runs: 1 }, tick());
+      return { status: 200, body: { ok: true, scans: [sc.scan] } };
+    },
+    proposal(body) {
+      const st = state(); const p = st.proposals.get(body.id);
+      const view1 = () => { const s2 = state(); return RS.reportAnswer(ctx, wnow, file, s2.proposals.get(body.id).report, Date.now()).body.proposals.find((x) => x.id === body.id); };
+      if (!p) return { status: 404, body: { ok: false, error: 'no proposal ' + body.id } };
+      if (body.action === 'undo') { const r = S.proposalUndo(file, body.id, PM, { now: tick() }); return r.ok ? { status: 200, body: { ok: true, proposal: view1() } } : { status: r.status, body: { ok: false, error: r.error } }; }
+      if (p.state !== 'open') return { status: 409, body: { ok: false, error: `the proposal is ${p.state} already` } };
+      if (body.action === 'dismiss') { const r = S.proposalDismiss(file, body.id, body.why, PM, { now: tick() }); return r.ok ? { status: 200, body: { ok: true, proposal: view1() } } : { status: r.status, body: { ok: false, error: r.error } }; }
+      if (body.fields !== undefined || body.action === 'change') {
+        const r = S.proposalChange(file, body.id, body.fields, PM, { now: tick() });
+        if (!r.ok) return { status: r.status, body: { ok: false, error: r.error } };
+        if (body.action === 'change') return { status: 200, body: { ok: true, proposal: view1() } };
+      }
+      const q = state().proposals.get(body.id);
+      if (q.kind === 'create') {
+        const id = 'idpf-' + (97 + (++M.made)); const result = { initiative: id, path: 'planning/initiatives/' + id + '.md', board: q.fields.board, stage: 'Discover' };
+        S.proposalApprove(file, body.id, result, PM, { now: tick() }); S.addEvidence(file, { initiative: id, report: q.report, proposal: body.id, note: q.finding }, PM, { now: tick() });
+        return { status: 200, body: { ok: true, proposal: view1(), result: { initiative: { id, path: result.path }, board: result.board, stage: result.stage } } };
+      }
+      if (q.kind === 'attach') { S.proposalApprove(file, body.id, { initiative: q.fields.initiative }, PM, { now: tick() }); S.addEvidence(file, { initiative: q.fields.initiative, report: q.report, proposal: body.id, note: q.finding }, PM, { now: tick() }); return { status: 200, body: { ok: true, proposal: view1(), result: { initiative: q.fields.initiative } } }; }
+      // research: a follow-up scan whose one report is linked to the report the proposal came from
+      const b = L.begin(++M.n, { types: ['insight'], items: [], repo: true, at: tick(), research: { question: q.fields.question, depth: q.fields.depth, sources: [], parent: q.report, proposal: q.id } });
+      b.n = M.n; b.research = true; M.follow = b; L.runStart(b.scan, 'web', tick());
+      S.proposalApprove(file, body.id, { scan: b.scan, report: b.reports[0].id, parent: q.report }, PM, { now: tick() });
+      return { status: 200, body: { ok: true, proposal: view1(), result: { scan: b.scan, report: b.reports[0].id, parent: q.report, steps: S.stepsOf(state().scans.get(b.scan)) } } };
+    },
+  };
+  M.made = 0;
+  const j = (route, status, body) => route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });
+  async function handle(route, request) {
+    const u = new URL(request.url()); const p = u.pathname; const method = request.method();
+    let body = {}; try { body = JSON.parse(request.postData() || '{}'); } catch { /* none */ }
+    M.calls.push({ method, path: p, body, query: Object.fromEntries(u.searchParams) });
+    if (M.fail && M.fail.path === p) { const f = M.fail; M.fail = null; return j(route, f.status || 200, { ok: false, error: f.error, ...(f.why ? { why: f.why } : {}) }); }
+    if (method === 'GET' && p === '/api/scan/portfolio') return j(route, 200, view());
+    if (method === 'GET' && p === '/api/scan/report') { const r = RS.reportAnswer(ctx, wnow, file, u.searchParams.get('id') || '', Date.now()); return j(route, r.status, r.body); }
+    if (method !== 'POST') return route.fallback();
+    const verb = p.replace('/api/scan/', '');
+    if (press[verb]) { const r = press[verb](body); return j(route, r.status, r.body); }
+    return j(route, 404, { ok: false, error: 'no such route' });
+  }
+  return Object.assign(M, {
+    view, advance, state,
+    /** The first scan, finished: the watch list kept, both runs, the reports written and the proposals filed. */
+    seed() { const st = state(); kept(); const items = S.itemsOf(st, null).map((i) => ({ ...i })); const b = L.seedFinished(++M.n, { items, at: tick(), ini: 'scan-ui' }); b.n = M.n; return b; },
+    /** The research scan of an approved research proposal ends: its follow-up document is written, linked to its parent. */
+    research() {
+      const b = M.follow; const at = tick();
+      L.w({ ev: 'section', scan: b.scan, report: b.reports[0].id, heading: 'Question', body: 'Which headers?', origin: 'web', sources: [{ label: 'Stripe', ref: 'https://docs.stripe.com/rate-limits' }], by: AG }, at);
+      L.runEnd(b.scan, 'web', at + 1); L.runStart(b.scan, 'repo', at + 2); L.runEnd(b.scan, 'repo', at + 3);
+      L.finish(b.n, b, { at: at + 10, ini: 'scan-ui' });
+      return b.reports[0];
+    },
+    reportOf: (type) => [...state().reports.values()].filter((r) => r.type === type && !r.parent && r.written).pop(),
+    async install(page) { await page.route('**/api/scan/**', handle); },
+    close() { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* gone */ } },
+  });
 }
-module.exports = { start };
+module.exports = { start, tools };