create-pmos 0.188.0 → 0.189.0

package/workspace/guide/horizon-scan.md

@@ -1,73 +1,82 @@
 ---
 type: Guide
-title: "The Horizon scan: the agent looks outside your initiatives"
-description: "What the Horizon scan does, how often it runs, the watch list you keep, where its findings land, what it can and cannot do, and the pmos scan commands."
-timestamp: 2026-10-12
+title: "The Horizon scan: reports and proposals for the whole portfolio"
+description: "What the portfolio Horizon scan does, its settings and schedule, Scan now and its limits, the report documents, the proposals you approve, what it can and cannot do, and the pmos scan commands."
+timestamp: 2026-10-13
 ---
 
-# The Horizon scan: the agent looks outside your initiatives
+# The Horizon scan: reports and proposals for the whole portfolio
 
-The Initiative Driver works on initiatives that already exist. The Horizon scan looks the other way. It looks for opportunities you have not asked for yet. It reads the public web for similar products, changes in your domain and approaches other teams use. It reads your repository for what keeps coming up and no initiative covers.
+The Initiative Driver works on initiatives that already exist. The Horizon scan looks the other way. It reads the public web for similar products, changes in your domain and approaches other teams use. It reads your repository for what keeps coming up and no initiative covers.
 
-Every finding is an ask in Triage. A scan never creates an initiative. You accept or decline each ask, as you do for any ask.
+One scan covers the whole portfolio. It writes **report documents** and then **proposals** for what to do next. A scan never creates an initiative on its own. Nothing happens until you press Approve.
 
-## How often it runs
+## Settings and schedule
 
-Each board has its own setting: **Daily**, **Weekly** or **Off**. Daily is the default.
+The settings belong to the workspace, not to a board:
 
-- **Daily.** Every working day, Monday to Friday, at 09:00 local time.
-- **Weekly.** Every Monday at 09:00.
-- **Off.** No scan runs on that board.
+- **Cadence.** **Daily** (the default), **Weekly** or **Off**.
+- **Repository.** On or off. When off, a scan reads the web only.
+- **Report types.** Benchmark, competitive, insight and productivity. All are on by default.
 
-If the workspace was not running at 09:00, the scan starts at the first check that day inside your working hours. It never starts outside your working hours or inside your quiet hours. A board gets at most one scan a day. Only one scan runs at a time across the workspace. `PMOS_DRIVER=off` or `PMOS_SCAN=off` starts no scan at all.
-
-Open the board, press **Board settings**, and find **Horizon scan** below Agent. The block shows the last scan and the next one.
+A scheduled scan runs at most once a day, inside your working hours, never inside your quiet hours. Only one scan runs at a time. `PMOS_DRIVER=off` or `PMOS_SCAN=off` starts no scan at all. Board settings only show that the scan runs for the whole portfolio, with a link to the setup.
 
 ## The watch list
 
-The web part of a scan searches for what is on the watch list of the board, and for nothing else. An item has a kind and a name:
+One watch list serves all boards. An item has a kind (`product`, `domain` or `approach`), a name, a reason and the boards it relates to. An old per-board list is folded into this list, and its board stays on its items.
+
+The suggest run reads the initiatives of all boards and files up to 8 suggestions. For each one, press **Keep**, **Edit** or **Remove**. You can also add your own item. Only kept items are scanned.
 
-- **product.** A similar product or a reference product.
-- **domain.** A topic that changes often.
-- **approach.** A way of working that other teams use.
+## Scan now
 
-A board that has no watch list gets one **suggest run**. The agent reads the initiatives of the board and files up to 8 suggestions. Each one names the initiative it came from. Suggestions appear in Board settings. For each one, press **Keep**, **Edit** or **Remove**. You can also add your own item.
+**Scan now** starts a scan by hand. A picker lets you choose the kept items, the repository and the report types.
 
-Only items you kept or added are scanned. A board with no kept item is not scanned.
+- At most 3 manual scans a day, and one scan at a time.
+- A manual scan may start outside working hours. It never starts inside quiet hours.
+- A running scan shows its steps (web, repository, reports). **Stop** ends the runs and keeps what was already filed.
 
 ## What a scan does
 
 A scan is two short background runs, in this order.
 
-1. **The web run.** It gets the kept watch list and nothing else. It cannot read your repository, your initiatives or your notes. It searches the public web and reads public pages. It files up to 5 findings. Each one has a title, a one-line reason and the public page the agent read.
-2. **The repository run.** It reads your repository, your notes and the Jira themes in them. It has no way to reach the web. It files up to 3 findings of its own: recurring friction, an ask repeated in notes or meetings, a Jira theme with no initiative, or a stalled bet. It also marks which findings, from both runs, match an initiative that already exists.
+1. **The web run.** It gets the selected items and the report types, and nothing else. It cannot read your repository, your initiatives or your notes. It writes the web sections of the benchmark, competitive and insight reports. Each claim carries the URL the run read.
+2. **The repository run.** It reads your repository, your notes and the initiatives, and the web sections. It has no way to reach the web. It writes the repository sections and the productivity report (which is repository only), and files the proposals.
+
+## The report documents
+
+Each selected type gives one markdown document at `<state>/reports/scan-<type>/<YYYY-MM-DD>.md`. A second scan on the same day adds `-2`, then `-3`. The frontmatter has `type: Reference`, `title`, `timestamp`, `source: scan:portfolio`, `made_by: agent`, `output: google-doc`, `scan`, `report` and `origin`. The Documents list in Reports reads them with no change.
+
+Every claim cites a source: a URL the web run read, a path, a Jira key or a note. Each document ends with a **What next** section that lists its proposals.
+
+## Proposals
+
+The repository run files up to 5 proposals for each report. Each one names the finding it came from and its evidence.
 
-The agent skips a finding it already filed on this board. A finding repeats an earlier one when it has the same source page, or when its title has the same significant words. The scan counts the skips.
+- **create.** A title, a board, a lane, an anchor and an intent. Approve makes the initiative through the initiative writer in the first stage of the board's workflow, and adds the report as evidence.
+- **research.** A question, its sources and a depth. Approve starts a research run: a web run, then a repository run. It writes a follow-up report linked to its parent, with its own proposals.
+- **attach.** Names an existing initiative. Approve adds the finding to it as evidence.
 
-## Where the findings land
+You can **Approve**, **Change** the fields first, or **Dismiss** with a one-line reason. A dismissal counts as a correction, and a later scan does not raise a proposal whose title has the same significant words. **Undo** takes back a dismissal or a change: the proposal waits for you again, and a new line in the scan ledger records it. The correction a dismissal wrote stays. Approve has no Undo, because it made a real initiative or started runs.
 
-- **Triage.** Each new finding is an ask on its board. The row says **Found by agent**. It shows the reason, the sources and either "matches" an initiative or "no initiative yet". Accept, Ask for more and Decline work as for any ask. A declined scan ask counts as a correction.
-- **Briefing.** The **Horizon scan** card shows the scan of the day: when it ran, which boards, how many asks were found, how many match an initiative and how many are new. Each finding has **Open in Triage**. The card says how many public pages the agent read and how many findings it skipped.
+If the initiatives are still being read, Approve for attach and research answers that and you press it again.
 
 ## What it can and cannot do
 
 - It can search and read public web pages, and read your repository.
-- It can file a finding. That is the only thing it writes.
+- It can write report documents and file proposals. Those are the only things it writes.
 - It cannot send anything: no mail, no message, no comment, no ticket.
 - It cannot read a page behind a login.
-- It cannot create an initiative, accept an ask or change a record. Only you can.
+- It cannot create an initiative or change a record. Only you can.
 - The run that reads the web never sees your repository. The run that reads your repository never reaches the web.
-- It cannot be started from the page. It runs on its schedule.
 
-Findings are proposals. The agent can be wrong. Check the sources before you accept.
+The agent can be wrong. Check the sources before you approve.
 
 ## The commands
 
-The agent uses `pmos scan file` to file one finding, `pmos scan match` to mark a finding that matches an initiative, `pmos scan suggest` to file a watch list suggestion and `pmos scan list` to read the findings of one scan. `pmos scan status` shows the cadence, the watch list and the last scan of each board. The other commands are yours, at an interactive terminal:
+The agent uses `pmos scan file`, `pmos scan section`, `pmos scan match`, `pmos scan propose`, `pmos scan suggest` and `pmos scan list`. `pmos scan status` shows the setting, the watch list and the last scan. The other commands are yours, at an interactive terminal:
 
-- `pmos scan cadence <daily|weekly|off> --board <id>` sets how often a board is scanned.
-- `pmos scan watch keep <item> --board <id>` keeps a suggestion. `pmos scan watch remove <item> --board <id>` removes an item.
-- `pmos scan watch edit <item> --board <id> --name "<new name>"` changes an item.
-- `pmos scan watch add --board <id> --kind product --name "<what to watch>"` adds an item.
+- `pmos scan cadence <daily|weekly|off>` sets how often the portfolio is scanned.
+- `pmos scan setting` changes the repository switch and the report types.
+- `pmos scan watch keep|remove|edit|add ...` manages the watch list. `--boards a,b` sets the boards of an item.
 
-The ledger is `scan.jsonl` in the state folder of the repository (`pmos/state`, `state` or `.pmos`). Each action adds one line. Nothing is changed or removed.
+The ledger is `scan.jsonl` in the state folder (`pmos/state`, `state` or `.pmos`). Each action adds one line. Nothing is changed or removed.

package/workspace/lib/headless.js

@@ -3,7 +3,7 @@
  * (initiative workspace-headless-jobs; PM decision 2026-10-11: keep Jev, no direct Claude API, background
  * jobs that need no human run headless).
  *
- *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | 'scan-web' | 'scan-repo' | 'report-setup' | 'report-find' | null   (null: open a pane, as before)
+ *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | 'scan-web' | 'scan-repo' | 'scan-research-web' | 'scan-research-repo' | 'report-setup' | 'report-find' | null   (null: open a pane, as before)
  *   argsFor(kind, { modelArgs, addDirs })          → the argv after `claude`
  *   parseResult(stdout)                            → { ok, text, isError, turns, durationMs, costUsd, denied[] }
  *   logLines(result, exitCode)                     → the lines the read-only log pane shows at the end
@@ -51,6 +51,13 @@ const DRIVE_ORIGINS = Object.freeze(['drive:']);
 // the repository and fetches nothing. Neither has both untrusted input and a way out (PRD: trust boundary).
 const SCAN_WEB_ORIGINS = Object.freeze(['scan-web:']);
 const SCAN_REPO_ORIGINS = Object.freeze(['scan-repo:', 'scan-suggest:']);
+// horizon-scan-portfolio: an approved research proposal is a second, smaller scan with the same split. Its web run (origin `scan-research-web:<ws>:<scan>`)
+// gets the approved question and the public sources only. Its repository run (origin `scan-research-repo:<ws>:<scan>`) writes the follow-up's repository
+// sections and files its proposals. The kinds are separate so the research web run holds one verb less than the scan web run (no findings) and so a test can
+// read the argv of each.
+const SCAN_RESEARCH_WEB_ORIGINS = Object.freeze(['scan-research-web:']);
+const SCAN_RESEARCH_REPO_ORIGINS = Object.freeze(['scan-research-repo:']);
+const WEB_KINDS = Object.freeze(['scan-web', 'scan-research-web']);   // kinds that read untrusted pages: no directory, no Read, Glob or Grep
 // report-workspace: the Ask box run (origin `report-setup:<ask>`) and the weekly finder run (origin `report-find:<run>`).
 const REPORT_SETUP_ORIGINS = Object.freeze(['report-setup:']);
 const REPORT_FIND_ORIGINS = Object.freeze(['report-find:']);
@@ -63,10 +70,15 @@ const TOOLS = Object.freeze({
   drive: Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos driver *)', 'Bash(pmos initiative list *)', 'Bash(pmos initiative export *)',
     'Bash(git log *)', 'Bash(ls *)', 'Bash(date *)']),
   // The web run: WebSearch, WebFetch and the one verb that files a finding. No Read, no Glob, no Grep, no repository path in its prompt or its add-dirs.
-  'scan-web': Object.freeze(['WebSearch', 'WebFetch', 'Bash(pmos scan file *)']),
+  // `pmos scan section` writes a section of a report document; the web run gives each web claim a URL it read.
+  'scan-web': Object.freeze(['WebSearch', 'WebFetch', 'Bash(pmos scan file *)', 'Bash(pmos scan section *)']),
   // The repository run: read and search the repository, `pmos scan` (its PM-only verbs refuse an agent session), the initiative list and git log.
   // No WebSearch, no WebFetch, no curl, no git push: it reads the web run's findings, which are untrusted text, so it has nothing that sends or fetches.
   'scan-repo': Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos scan *)', 'Bash(pmos initiative list *)', 'Bash(git log *)']),
+  // The research web run: the approved question and its public sources. WebSearch, WebFetch and the one verb that writes a section. No Read, Glob or Grep, no directory.
+  'scan-research-web': Object.freeze(['WebSearch', 'WebFetch', 'Bash(pmos scan section *)']),
+  // The research repository run: the same tools as the scan repository run. It has no web tool and nothing that sends.
+  'scan-research-repo': Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos scan *)', 'Bash(pmos initiative list *)', 'Bash(git log *)']),
   // The Ask box run: read and search, the one verb that files a proposal, the read-only list of definitions and git log. No Write, no Edit, no web,
   // nothing that sends. The PM's earlier copies are read through a connector only where the PM's own settings allow it (as for `drive`).
   'report-setup': Object.freeze(['Read', 'Glob', 'Grep', 'Bash(pmos report propose *)', 'Bash(pmos report definitions *)', 'Bash(git log *)']),
@@ -91,6 +103,8 @@ function kindFor({ agent, origin, skill, env } = {}) {
   if (DRIVE_ORIGINS.some((p) => o.startsWith(p))) return 'drive';
   if (SCAN_WEB_ORIGINS.some((p) => o.startsWith(p))) return 'scan-web';
   if (SCAN_REPO_ORIGINS.some((p) => o.startsWith(p))) return 'scan-repo';
+  if (SCAN_RESEARCH_WEB_ORIGINS.some((p) => o.startsWith(p))) return 'scan-research-web';
+  if (SCAN_RESEARCH_REPO_ORIGINS.some((p) => o.startsWith(p))) return 'scan-research-repo';
   if (REPORT_SETUP_ORIGINS.some((p) => o.startsWith(p))) return 'report-setup';
   if (REPORT_FIND_ORIGINS.some((p) => o.startsWith(p))) return 'report-find';
   if (skill && HEADLESS_SKILLS.includes(String(skill))) return 'skill';
@@ -101,8 +115,8 @@ function argsFor(kind, { modelArgs = [], addDirs = [] } = {}) {
   const tools = TOOLS[kind];
   if (!tools) throw new Error('unknown headless kind: ' + kind);
   const argv = ['-p', '--output-format', 'json', '--no-session-persistence', ...modelArgs, '--allowedTools', tools.join(',')];
-  // The web run gets no directory at all, whatever the caller passes: it must not be able to read the repository.
-  if (kind !== 'scan-web') for (const d of addDirs) if (d) argv.push('--add-dir', String(d));
+  // A web run gets no directory at all, whatever the caller passes: it must not be able to read the repository.
+  if (!WEB_KINDS.includes(kind)) for (const d of addDirs) if (d) argv.push('--add-dir', String(d));
   return argv;
 }
 
@@ -144,4 +158,4 @@ function logLines(r, exitCode) {
   return out;
 }
 
-module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };
+module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, SCAN_RESEARCH_WEB_ORIGINS, SCAN_RESEARCH_REPO_ORIGINS, WEB_KINDS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };

package/workspace/lib/pmos-verbs.js

@@ -59,9 +59,9 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): initiative initiative-driver added it through the same table.
   driver: Object.freeze({ module: 'driver-cli.js', run: null, guide: 'initiative-driver.md',
     help: 'pmos driver propose|status|keep|return|drop|pause|resume|mode … — the Initiative Driver: drafts for you to keep, send back or drop (pmos driver help)' }),
-  // Not a pm-os-absorb verb (run: null): initiative horizon-scan added it through the same table.
+  // Not a pm-os-absorb verb (run: null): initiative horizon-scan added it through the same table; horizon-scan-portfolio added section, propose, setting and --boards.
   scan: Object.freeze({ module: 'scan-cli.js', run: null, guide: 'horizon-scan.md',
-    help: 'pmos scan file|list|match|suggest|status|cadence|watch … — the Horizon scan: what the agent found outside the initiatives, and the watch list (pmos scan help)' }),
+    help: 'pmos scan file|section|propose|list [--sections]|match|suggest [--boards]|status|setting|cadence|watch [--boards] … — the Horizon scan: the portfolio watch list, the findings, the report sections and the proposals the PM approves, changes or dismisses (pmos scan help)' }),
   launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
     help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });

package/workspace/lib/route-modules.js

@@ -69,7 +69,7 @@ const MODULES = Object.freeze([
   'routes-meeting-focus', // console3 Meeting focus: the meeting, its note's talk, the companion's notes (GET); topic corrections and Ask PMOS quietly (page press)
   'routes-stage-tools',   // stage-tools-records: the records the PM edits per stage, what PMOS holds per stage, the sprint burndown
   'routes-driver',        // initiative-driver: the Agent strip's data, Keep, Send back, Drop, Pause and the board mode (driver.jsonl)
-  'routes-scan',          // horizon-scan: a board's watch list, cadence and last scan, the day's scan for the Briefing, the PM's watch and cadence presses (scan.jsonl)
+  'routes-scan',          // horizon-scan-portfolio: one scan for the workspace: the watch list and setting, Scan now and Stop, report documents and their proposals (approve, change, dismiss, undo), plus the first scan's per-board and Briefing reads (scan.jsonl)
   'routes-report-setups', // report-workspace: recurring reports, the Ask box, the finder, the report documents and their export (report-setups.jsonl)
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');

package/workspace/lib/routes-boards.js

@@ -128,6 +128,30 @@ function appendScanAsk(ctx, w, boardId, f, by) {
   return { ok: true, existing: false, id };
 }
 
+/** A new initiative on a board: initiative-writer makes the record (the only writer of one), then `tie` appends the boards-ledger line that puts it in the FIRST stage
+ * of the board's workflow, and the initiative's own workflow line when its default template differs from the board's. Triage's accept (asks/accept) and the Horizon
+ * scan's approved proposals (lib/routes-scan.js) both come through here, so the placement is one piece of code.
+ * `tie({ file, board, initiative, stage })` appends the line that names the initiative on the board (ask-accept, or assign and move).
+ * → { ok, initiative: { id, path }, stage, board } | { ok: false, status, error, field } */
+function createAndPlace(ctx, w, boardId, input, actor, tie) {
+  const fr = frameFor(ctx, w);
+  const board = fr.boards.find((b) => b.id === boardId);
+  if (!board) return { ok: false, status: 404, error: `no board ${boardId} in this workspace` };
+  const file = ledgerFile(ctx, w);
+  if (!file) return { ok: false, status: 409, error: NO_STATE };
+  const r = writer.createInitiative(w.root, input, { actor });
+  if (!r.ok) return { ok: false, status: r.status || 400, error: r.error, field: r.field || null };
+  const tpl = board.defTpl && B.INI_TEMPLATES[board.defTpl] ? board.defTpl : null;
+  const ownWf = tpl && tpl !== board.template ? B.INI_TEMPLATES[tpl].stages.map((x) => ({ name: x.name, cat: x.cat, hint: x.hint || '' })) : null;
+  const stage = (ownWf || board.workflow)[0].name;
+  tie({ file, board, initiative: r.id, stage });
+  if (ownWf) append(file, actor, { kind: 'ini-workflow', board: board.id, id: r.id, template: tpl, stages: ownWf, moved: null });
+  rowsLib.invalidate(w.root);
+  rowCache.delete(w.root);
+  if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id);
+  return { ok: true, initiative: { id: r.id, path: r.path }, stage, board: board.id };
+}
+
 // ── boards of a workspace ─────────────────────────────────────────────────────────────────────────
 const isSelf = (ctx, w) => !!(ctx.selfRoot && w && path.resolve(w.root) === path.resolve(ctx.selfRoot));
 
@@ -677,17 +701,10 @@ const WRITES = {
     if (!p.file) return fail(ctx, res, 409, NO_STATE);
     const input = { title: body.title, lane: body.lane, anchor: body.anchor };
     for (const k of ['intent', 'id']) if (body[k] != null && body[k] !== '') input[k] = body[k];
-    const r = writer.createInitiative(p.w.root, input, { actor: g.actor });
-    if (!r.ok) return fail(ctx, res, r.status || 400, r.error, { field: r.field || null });
-    const tpl = p.board.defTpl && B.INI_TEMPLATES[p.board.defTpl] ? p.board.defTpl : null;
-    const ownWf = tpl && tpl !== p.board.template ? B.INI_TEMPLATES[tpl].stages.map((x) => ({ name: x.name, cat: x.cat, hint: x.hint || '' })) : null;
-    const stage = (ownWf || p.board.workflow)[0].name;
-    append(p.file, g.actor, { kind: 'ask-accept', board: p.board.id, ask: a.id, initiative: r.id, stage });
-    if (ownWf) append(p.file, g.actor, { kind: 'ini-workflow', board: p.board.id, id: r.id, template: tpl, stages: ownWf, moved: null });
-    rowsLib.invalidate(p.w.root);
-    rowCache.delete(p.w.root);
-    if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(p.w.id);
-    ctx.json(res, { ok: true, initiative: { id: r.id, path: r.path }, stage });
+    const made = createAndPlace(ctx, p.w, p.board.id, input, g.actor,
+      ({ file, initiative, stage }) => append(file, g.actor, { kind: 'ask-accept', board: p.board.id, ask: a.id, initiative, stage }));
+    if (!made.ok) return fail(ctx, res, made.status || 400, made.error, { field: made.field || null });
+    ctx.json(res, { ok: true, initiative: made.initiative, stage: made.stage });
   },
   '/api/boards/asks/more': (ctx, res, body, g) => {
     const p = postFrame(ctx, res, body);
@@ -992,4 +1009,4 @@ function meetingBoards(ctx) {
   return { list, detail };
 }
 
-module.exports = { prefixes: ['/api/boards'], handle, move, boardIndex, appendScanAsk, frameFor, boardIdOf, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };
+module.exports = { prefixes: ['/api/boards'], handle, move, boardIndex, appendScanAsk, scanDeclineSignal, createAndPlace, ledgerFile, append, frameFor, boardIdOf, meetingBoards, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };