create-pmos 0.193.0 → 0.194.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.193.0",
+  "version": "0.194.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@1e4f936
+kernel-source: pmos@dcb0b7b
 assembled: 2026-10-13
 mode: vendor

package/payload/okf/core/concepts/frontmatter-format.md

@@ -3,7 +3,7 @@ type: Concept
 title: Repo-wide frontmatter format
 description: The PMOS house convention — every tracked .md carries OKF-format YAML frontmatter with a required type + title (timestamp optional since D74), so agents and the harness classify and route a file by reading it, not by guessing from its path.
 tags: [frontmatter, okf, format, harness, aci, convention]
-timestamp: 2026-07-24
+timestamp: 2026-10-13
 ---
 
 # Repo-wide frontmatter format
@@ -46,10 +46,11 @@ OKF's reserved filenames carry **no** frontmatter and are skipped by both the mi
 The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontmatter_registry.txt) — the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
 
 - **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
-- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`, `Handover`
+- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`, `Handover`, `Review`
   - `Initiative` is the repo-native initiative record in [`planning/initiatives/`](/planning/initiatives/), read by the [Initiative Gate](/.github/scripts/initiative-gate.sh). Its D56 **work-type lane** rides a separate `lane:` key — not `type:` — so the lane vocabulary and this registry never collide.
   - `Story` is a **user-story document** — the decomposition of a spec into the units of work handed to whoever builds them. It is the one type in this registry that is also **checked positionally** (see below), and it may carry an optional `jira:` / `confluence:` / `google_doc:` key naming the tracker record it corresponds to. That key is a *declaration* the workspace displays, never a lookup: PMOS holds no credential and makes no outbound request.
   - `Handover` is the note the cockpit mod's `/pmos-handover` writes (`planning/handovers/<id>.md`, or `pmos/state/handovers/<id>.md` in a kit): one per initiative, replaced on each handover, with checked fields (`id`, `head_sha`, `branch`, `stage`, `next`, `commits`, `files`, `handover_at`) read back by the resume summary ([D81](/okf/products/pmos/adr/d81-cockpit-mod-and-grants.md)).
+  - `Review` is an initiative's **outcome review**, a core document the workspace drafts and the PM issues (`<state>/core-docs/initiative-<id>/outcome/<slot>.md`, initiative core-documents): did the work move its key result, and what was learned. The other core documents are `Reference`.
 - **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
 
 ### When the path decides the type

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-13T08:02:12Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T08:20:29Z"}
 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-13T08:02:12Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T08:20:29Z"}
 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-13T08:02:12Z"}
+generated: {by: process:create-pmos, at: "2026-10-13T08:20:29Z"}
 status: stable
 ---
 

package/workspace/c3-core-docs-test.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/* PMOS workspace — the core documents of each level on the console3 Initiatives page (initiative core-documents; the approved mockup
+ * 43-doc-levels.js), in demo mode (browser). c3-demo-coredocs.js answers GET /api/core-docs and the POSTs. It drives:
+ *   Portfolio > Documents (Overview | Documents), a board's Docs tab (core documents, then "Other documents") and an initiative's Docs tab
+ *   (categories that fold), the rows (state chips, Draft it, Review the draft), the draft panel of the document sheet (Issue it, Ask PMOS to
+ *   change it), the Briefing row core-doc-drafts, and no horizontal scroll at 400 px.
+ *
+ * The files it drives (named so `run-tests.js --changed` traces a change in any of them to this suite): public/pm/c3-core-docs.js,
+ * c3-core-docs.css, c3-demo-coredocs.js, c3-demo.js, c3-ib-docs.js, c3-ii-tabs.js, c3-initiatives.js, c3-ini-ui.js, c3-doc-sheet.js,
+ * c3-driver.js, c3-brief-needs.js and c3-ini-harness.js. At 400 px it keeps the desktop layout the way lib/c3-full-console.js does. Its list fragment is test-lists/c3-core-docs.json.
+ */
+'use strict';
+const { harness } = require('./c3-ini-harness');
+
+(async () => {
+  const H = await harness('c3-core-docs');
+  const { page, ok, until, st, open, toast, sleep } = H;
+  const rows = (sel) => st((s) => [...document.querySelectorAll(s)].map((n) => n.dataset.cdRow).join(','), sel || '[data-cd-row]');
+  const rowState = (k) => st((key) => { const n = document.querySelector('[data-cd-row="' + key + '"]'); return n ? n.dataset.cdSt : ''; }, k);
+  const waitToast = (re) => until(async () => { const t = await toast(); return re.test(t) && t; });
+  const noScroll = () => st(() => document.documentElement.scrollWidth <= window.innerWidth + 1 && [...document.querySelectorAll('.c3 .calwrap, .c3 .brief')].every((n) => n.scrollWidth <= n.clientWidth + 1));
+  const sheetOpen = () => st(() => !!document.querySelector('[data-shell="sheet"] [role="dialog"]'));
+  const settle = async (sel) => { await until(() => st((s) => !!document.querySelector(s), sel)); await sleep(120); };
+
+  /* ── Portfolio > Documents ── */
+  await open('docs');
+  await settle('[data-cd="core"]');
+  ok('P1 the Portfolio has an Overview | Documents control, Documents pressed', await st(() => { const b = [...document.querySelectorAll('[data-ini="pf-tabs"] [data-ini-tab]')]; return b.map((x) => x.dataset.iniTab + ':' + x.getAttribute('aria-pressed')).join(',') === 'overview:false,docs:true'; }));
+  ok('P2 the Documents badge counts the drafts and the due documents', (await st(() => (document.querySelector('[data-cd="seg-badge"]') || {}).textContent)) === '3');
+  const pf = await rows();
+  ok('P3 the core set lists 11 documents, strategy first', pf.split(',').length === 11 && pf.startsWith('strategy,okrs,roadmap,invest'), pf);
+  ok('P4 states: up to date, draft ready, due, comes later where it applies', (await rowState('strategy')) === 'ok' && (await rowState('roadmap')) === 'draft' && (await rowState('status')) === 'due');
+  ok('P5 a row shows its question, cadence, reader and who writes it', await st(() => { const t = document.querySelector('[data-cd-row="strategy"]').textContent; return /Yearly, reviewed each quarter/.test(t) && /Leadership, every PM/.test(t) && /You write it/.test(t) && /new/.test(t) && /2 key results do not trace to it/.test(t); }));
+  ok('P6 the right column says what the level is for, lists the drafts and how the levels connect', await st(() => { const l = document.querySelector('[data-cd="level"]'); return !!l && /Are we betting on the right things\?/.test(l.textContent) && document.querySelectorAll('[data-cd="drafts"] [data-cd-wait]').length === 2 && !!document.querySelector('[data-cd="connect"]'); }));
+  ok('P7 the address holds the Documents view', await st(() => /init=docs/.test(location.search)));
+  ok('P8 the summary line counts the drafts and what is due', await st(() => /2 drafts to review, 1 due/.test(document.querySelector('[data-cd="core"]').textContent)));
+  await H.shot('portfolio-docs');
+  await page.click('[data-ini="pf-tabs"] [data-ini-tab="overview"]');
+  ok('P9 Overview brings the boards back', await until(() => st(() => !!document.querySelector('[data-ini="boards"]') && !document.querySelector('[data-cd="core"]'))));
+  await page.click('[data-ini="pf-tabs"] [data-ini-tab="docs"]');
+  ok('P10 Documents opens again', await until(() => st(() => !!document.querySelector('[data-cd="core"]'))));
+
+  /* ── Review the draft, Issue it (Portfolio) ── */
+  await page.click('[data-cd-review="invest"]');
+  ok('R1 Review the draft opens the draft in the document sheet', await until(() => st(() => !!document.querySelector('[data-shell="sheet"] [data-cd="draft-panel"]'))));
+  ok('R2 the sheet shows the draft, with Issue it and Ask PMOS to change it', await st(() => { const d = document.querySelector('[data-shell="sheet"]'); return /Investment mix/.test(d.textContent) && !!d.querySelector('[data-cd-issue="invest"]') && !!d.querySelector('[data-cd-redraft="invest"]'); }));
+  await H.shot('portfolio-sheet');
+  await page.click('[data-cd-issue="invest"]');
+  ok('R3 Issue it says nothing was sent and closes the sheet', await until(async () => /Issued\. Nothing was sent/.test(await toast()) && !(await sheetOpen())));
+  ok('R4 the row is up to date and the draft is gone from the waiting list', await until(async () => (await rowState('invest')) === 'ok' && (await st(() => document.querySelectorAll('[data-cd="drafts"] [data-cd-wait]').length)) === 1));
+
+  /* ── a board: IDPF ── */
+  await open('board:idpf:docs');
+  await settle('[data-cd="core"]');
+  const bd = await rows();
+  ok('B1 the board set lists 10 documents, the charter first', bd.split(',').length === 10 && bd.startsWith('charter,backlog,intake,bstatus,capacity'), bd);
+  ok('B2 Core documents comes before "Other documents"', await st(() => { const c = document.querySelector('[data-cd="core"]'); const o = document.querySelector('[data-inb="docs-title"]'); return !!c && !!o && /Other documents/.test(o.textContent) && !!(c.compareDocumentPosition(o) & Node.DOCUMENT_POSITION_FOLLOWING); }));
+  ok('B3 the existing documents list is still there, grouped by initiative', await until(() => st(() => document.querySelectorAll('[data-inb-docgrp]').length > 0)));
+  ok('B4 the right column: what the level is for, and the initiative documents', await st(() => /Is this area moving, and what comes next\?/.test(document.querySelector('[data-cd="level"]').textContent) && /Build and deliver is on, so the set adds the sprint review and release notes from Jira IDPF/.test(document.querySelector('[data-cd="level"]').textContent) && /documents? across \d+ initiatives?/.test(document.querySelector('[data-cd="ini-docs"]').textContent)));
+  ok('B5 a live row opens the tab it names', await (async () => { await page.click('[data-cd-open="intake"]'); return until(() => st(() => /board:idpf:triage/.test(decodeURIComponent(location.search)))); })());
+  await open('board:idpf:docs');
+  await settle('[data-cd="core"]');
+  await H.shot('board-docs');
+
+  /* Redraft from the sheet */
+  await page.click('[data-cd-review="sprint"]');
+  await until(() => st(() => !!document.querySelector('[data-shell="sheet"] [data-cd-redraft="sprint"]')));
+  await page.click('[data-cd-redraft="sprint"]');
+  ok('RD1 Ask PMOS to change it asks for a new draft and closes the sheet', await until(async () => /drafting it again/.test(await toast()) && !(await sheetOpen())));
+  ok('RD2 the row shows the agent drafting', await until(async () => (await rowState('sprint')) === 'running' && (await st(() => /Agent drafting/.test(document.querySelector('[data-cd-row="sprint"]').textContent)))));
+
+  /* ── a board with Build and deliver off ── */
+  await open('board:office:docs');
+  await settle('[data-cd="core"]');
+  const off = await rows();
+  ok('O1 Build and deliver off drops the sprint review and release notes (8 documents)', off.split(',').length === 8 && !/sprint|release/.test(off), off);
+  ok('O2 the charter is not started and offers Draft it', (await rowState('charter')) === 'missing' && await st(() => !!document.querySelector('[data-cd-row="charter"] [data-cd-draft="charter"]')));
+  ok('O3 the level card says there is no Jira', await st(() => /Build and deliver is off, so there is no sprint review or release notes/.test(document.querySelector('[data-cd="level"]').textContent)));
+  await H.shot('board-off-docs');
+  await page.click('[data-cd-draft="charter"]');
+  ok('D1 Draft it says PMOS is drafting', await waitToast(/PMOS is drafting the board charter/));
+  ok('D2 the row shows "Agent drafting" and no button', await until(async () => (await rowState('charter')) === 'running' && await st(() => !document.querySelector('[data-cd-row="charter"] [data-cd-draft]') && /Agent drafting/.test(document.querySelector('[data-cd-row="charter"]').textContent))));
+  ok('D3 the draft arrives and offers Review the draft', await until(() => st(() => !!document.querySelector('[data-cd-row="charter"] [data-cd-review="charter"]')), 15000));
+  await page.click('[data-cd-review="charter"]');
+  await until(() => st(() => !!document.querySelector('[data-shell="sheet"] [data-cd="draft-panel"]')));
+  ok('D4 the draft opens in the sheet with its own text', await st(() => /Jakarta office/.test(document.querySelector('[data-shell="sheet"]').textContent)));
+  await page.click('[data-cd-issue="charter"]');
+  ok('D5 Issue it turns the row up to date', await until(async () => (await rowState('charter')) === 'ok'));
+
+  /* ── an initiative in Build: IDPF-12 ── */
+  await open('ini:idpf:IDPF-12:docs');
+  await settle('[data-cd-fold]');
+  const folds = await st(() => [...document.querySelectorAll('[data-cd-cat]')].map((n) => n.dataset.cdCat + ':' + n.dataset.cdFold).join(','));
+  ok('I1 Discover and Plan fold to one line, Do is the current one, Learn comes later', folds === 'Discover:done,Plan:done,Do:open,Learn:later', folds);
+  ok('I2 the folded category says "All 3 up to date" and keeps its documents as chips', await st(() => { const s = document.querySelector('[data-cd-cat="Discover"]'); return /All 3 up to date/.test(s.textContent) && s.querySelectorAll('[data-cd-chip]').length === 3 && !s.querySelector('.nrow'); }));
+  ok('I3 the current category is marked "now" and lists its rows', await st(() => { const s = document.querySelector('[data-cd-cat="Do"]'); return /Do · now/.test(s.textContent) && s.querySelectorAll('[data-cd-row]').length === 4 && /1 of 4 done/.test(s.textContent); }));
+  ok('I4 the right column: level, order rules, other documents', await st(() => !!document.querySelector('[data-cd="level"]') && !!document.querySelector('[data-cd="order"]') && /Other documents/.test(document.body.textContent)));
+  await H.shot('ini-docs');
+  await page.click('[data-cd-chip="prd"]');
+  ok('I5 a chip of a folded category opens the document in the sheet', await until(() => sheetOpen()));
+  await page.keyboard.press('Escape');
+  await until(async () => !(await sheetOpen()));
+  await page.click('[data-cd-row="risks"] [data-cd-open="risks"]');
+  ok('I6 a row with a stage tool opens the initiative Overview on that tool', await until(() => st(() => /ini:idpf:IDPF-12:overview:risks/.test(decodeURIComponent(location.search)))));
+
+  /* ── an initiative on research only, early: IDPF-21 ── */
+  await open('ini:idpf:IDPF-21:docs');
+  await settle('[data-cd-fold]');
+  const early = await st(() => [...document.querySelectorAll('[data-cd-cat]')].map((n) => n.dataset.cdCat + ':' + n.dataset.cdFold).join(','));
+  ok('E1 Discover is open, the later categories wait', early === 'Discover:open,Plan:later,Do:later,Learn:later', early);
+  ok('E2 the set has no PRD, rubric, design or launch checklist', await st(() => !document.querySelector('[data-cd-open="prd"], [data-cd-open="rubric"], [data-cd-open="design"], [data-cd-open="launch"]') && /Research only: nothing gets built/.test(document.querySelector('[data-cd="level"]').textContent)));
+  ok('E3 a draft problem statement offers Review the draft; research notes are due', await st(() => !!document.querySelector('[data-cd-row="problem"] [data-cd-review]')) && (await rowState('research')) === 'due');
+  await H.shot('ini-early-docs');
+
+  /* ── an initiative in Evaluate with an outcome review draft ── */
+  await open('ini:idpf:IDPF-62:docs');
+  await settle('[data-cd-fold]');
+  ok('V1 the outcome review is a draft to review', await st(() => !!document.querySelector('[data-cd-row="outcome"] [data-cd-review="outcome"]')));
+  await page.click('[data-cd-review="outcome"]');
+  await until(() => st(() => !!document.querySelector('[data-shell="sheet"] [data-cd-issue="outcome"]')));
+  ok('V2 the sheet shows the review and Issue it', await st(() => /Did it move the key result/.test(document.querySelector('[data-shell="sheet"]').textContent)));
+  await H.shot('outcome-sheet');
+  await page.click('[data-shell="sheet"] button[aria-label="Close"]');
+  await until(async () => !(await sheetOpen()));
+
+  /* ── the Briefing row opens the Docs view ── */
+  await page.route('**/api/needs*', (r) => r.fulfill({ contentType: 'application/json', body: JSON.stringify({ ok: true, needs: [{ run_id: 'core-docs:drafts:board:idpf', kind: 'core-doc-drafts', provider: 'core-docs', derived: true, scope: 'board:idpf', question: '1 IDPF draft to review', initiative_id: null }] }) }));
+  await page.goto(H.BASE + '/c3.html?demo=1&tab=brief', { waitUntil: 'load' });
+  await until(() => st(() => !!document.querySelector('[data-drv-need="core-doc-drafts"]')));
+  ok('N1 the Briefing shows the core-doc-drafts row', await st(() => /1 IDPF draft to review/.test(document.querySelector('[data-drv-need="core-doc-drafts"]').textContent)));
+  await page.click('[data-drv-need="core-doc-drafts"] .tt');
+  ok('N2 a press opens that board\'s Docs view', await until(() => st(() => !!document.querySelector('[data-ini-board-page="idpf"] [data-cd="core"]'))));
+  await page.unroute('**/api/needs*');
+
+  /* ── 400 px: no horizontal scroll ── */
+  await page.evaluate(() => { try { localStorage.setItem('pmos.c3.testDesk', 'desk'); } catch { /* no storage */ } });   // at 400 px the phone companion shows; the suites that test the desktop layout keep it (lib/c3-full-console.js)
+  await page.setViewportSize({ width: 400, height: 900 });
+  for (const [loc, label] of [['docs', 'Portfolio'], ['board:idpf:docs', 'board'], ['board:office:docs', 'board with Build and deliver off'], ['ini:idpf:IDPF-12:docs', 'initiative'], ['ini:idpf:IDPF-21:docs', 'early initiative']]) {
+    await open(loc);
+    await settle('[data-cd-row], [data-cd-fold]');
+    ok('W ' + label + ' Docs has no horizontal scroll at 400 px', await noScroll(), await st(() => document.documentElement.scrollWidth + ' > ' + window.innerWidth));
+    await H.shot('w400-' + label.replace(/\W+/g, '-'));
+  }
+  await open('board:idpf:docs');
+  await settle('[data-cd="core"]');
+  await page.click('[data-cd-review="bstatus"]');
+  await until(() => st(() => !!document.querySelector('[data-shell="sheet"] [data-cd="draft-panel"]')));
+  ok('W the draft sheet has no horizontal scroll at 400 px', await noScroll());
+  await H.shot('w400-sheet');
+
+  await H.finish();
+})();

package/workspace/guide/core-documents.md

@@ -0,0 +1,49 @@
+---
+type: Guide
+title: "Core documents: what each level keeps"
+description: "The core documents of the portfolio, a board and an initiative, what each state means, how PMOS drafts them on a schedule and when you ask, how you issue a draft, and pmos coredoc write."
+timestamp: 2026-10-13
+---
+
+# Core documents: what each level keeps
+
+Each level answers one question for one reader:
+
+- **Portfolio**: "Are we betting on the right things?" Leadership reads it. It changes each quarter, with a monthly pulse.
+- **Board**: "Is this area moving, and what comes next?" The board owner, the team and the engineering lead read it. It changes every sprint or two weeks.
+- **Initiative**: "What are we building, why, and did it work?" You, the builders and the reviewers read it. It changes at each stage.
+
+The Docs view of each level starts with its core set. Each row tells you what the document is for, who reads it, how often it changes, who keeps it, and its state now.
+
+## Where each document lives
+
+Some core documents are documents of their own. PMOS keeps them in the state folder, under `core-docs/<scope>/<key>/<date>.md`. The others are read from a source that PMOS already keeps: the initiative record and the files it names, the stage tools (problem statement, RICE, launch checklist, kill conditions), the Initiatives and Triage tabs, the releases, and the recurring reports on a dashboard. PMOS never copies these sources.
+
+Risks are written once, on the initiative. Board risks and cross-board risks collect them. Each outcome review feeds the board retro and the quarterly review.
+
+## The states
+
+| State | What it means |
+|---|---|
+| Up to date | The document is issued and its cadence has not passed. |
+| Due | The cadence passed, or the current stage needs the document and it is not there. |
+| Draft ready | PMOS drafted it. It waits for you. |
+| Not started | Nothing is there, and the level needs it now. |
+| Comes later | The initiative has not reached the stage that needs it. |
+| Stale | It was issued before a change it depends on: a stage move (initiative risks, launch checklist, status update), a newer risk list or outcome review (rolled-up documents), or a change to the board settings (board charter). |
+
+A row with no source and no document is "Not started" and has no date. PMOS does not guess a date or a warning.
+
+## How PMOS drafts a document
+
+- **When you ask.** Press **Draft it** on a row, or **Ask PMOS to change it** on a draft. PMOS starts one background run. The run reads the sources of that document and writes one draft. It has no tool that sends, posts or edits.
+- **On a schedule.** Every 30 minutes inside your working hours, PMOS drafts each portfolio and board document whose cadence has passed and that has no draft. It drafts a document at most once a day, and it runs at most 3 drafts at once. It never drafts a document that you write (the product strategy).
+- **The Initiative Driver.** When the current stage of an initiative needs a document that is not there or is stale, the driver drafts it and files a proposal. **Keep** issues the draft. The driver does not propose a stage move while a document of the current stage is due.
+
+## Issue a draft
+
+Open the draft from its row (**Review the draft**). Read it and change what you like. Then press **Issue it**. Only you can issue or drop a draft. Nothing is sent to anyone: to share an issued document, use the copy action of the document sheet.
+
+## The command
+
+`pmos coredoc write --scope <scope> --key <key> --file <path>` writes one draft of a core document. The scope is `portfolio`, `board:<id>` or `initiative:<id>`. With `--file -` the command reads the document from standard input. The command refuses a scope it does not know, a key that is not a document of that level, and a document that PMOS reads from another source. A background run can write only the document it was started for. The command writes a draft and nothing else: you issue it on the page.

package/workspace/guide/index.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Guide: start here"
-timestamp: 2026-10-12
+timestamp: 2026-10-13
 ---
 
 # Guide: start here
@@ -63,6 +63,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
 - [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
 - [The Initiative Driver: drafts the agent files for you](initiative-driver.md): when the driver runs, the unblock sweep, the limits, Keep, Send back and Drop, the board modes, and `pmos driver`.
+- [Core documents: what each level keeps](core-documents.md): the core documents of the portfolio, a board and an initiative, their states, how PMOS drafts them, Issue it, and `pmos coredoc write`.
 - [The Horizon scan: the agent looks outside your initiatives](horizon-scan.md): how often it runs, the watch list you keep, what a scan does, where findings land, what it cannot do, and `pmos scan`.
 - [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
 - [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.

package/workspace/guide/initiative-boards.md

@@ -97,6 +97,20 @@ The **Overview** shows the stage records of the current stage:
 
 A project workflow has the launch checklist and the learnings only. If the workspace server cannot store stage records yet, the cards say "Nothing recorded yet." and nothing is saved.
 
+## Core documents
+
+Each level has a set of core documents. A level answers one question for one reader: the Portfolio asks "Are we betting on the right things?", a board asks "Is this area moving, and what comes next?", and an initiative asks "What are we building, why, and did it work?".
+
+- **Portfolio:** press **Documents** next to **Overview**. The number on the button counts the drafts and the documents that are due.
+- **Board:** the **Docs** tab starts with the core documents. The sprint review and the release notes show only when Build and deliver is on. The documents linked to the board follow under **Other documents**.
+- **Initiative:** the **Docs** tab has one section for each of Discover, Plan, Do and Learn. The current section lists its documents. A finished section, or one not reached yet, folds to one line.
+
+Each row shows what the document is for, its state, how often it changes, who reads it and who writes it. The states are Up to date, Due, Draft ready, Not started, Out of date and Comes later. Press a row to open the document, the tab, the stage tool or Reports that holds it.
+
+- **Draft it:** on a document that is not started, PMOS drafts it. The row shows "Agent drafting" until the draft is ready.
+- **Review the draft:** opens the draft in the document sheet. Above the draft, **Issue it** makes the draft the current document. **Ask PMOS to change it** asks for a new draft. PMOS sends nothing to anyone.
+- The Briefing shows one row for each level that has drafts waiting. Press the row to open that Docs view.
+
 ## Demo mode
 
 Open `/?demo=1` to see five sample boards and about 310 initiatives. In demo mode nothing is saved, and a reload starts again.

package/workspace/lib/core-docs-needs.js

@@ -0,0 +1,86 @@
+'use strict';
+/* core-docs-needs.js — the needs provider of the core documents (initiative core-documents, PRD section 5).
+ * lib/needs-providers.js folds these rows into server.js deriveNeeds, and from there into /api/needs and the Briefing.
+ *
+ *   kinds: core-doc-drafts
+ *   rowsFor(w, { lead }) → rows · sig(w) → string · rowsOf(store, { boardName, titleOf, boardOf, ws, ledgerRel })
+ *
+ *   core-doc-drafts   one row per scope with drafts waiting for the PM: "2 portfolio drafts to review", "1 IDPF draft to review",
+ *                     "1 draft to review on <initiative title>". `go` is the Docs view of that scope:
+ *                     { view: 'portfolio', tab: 'docs' } · { view: 'board', board, tab: 'docs' } · { view: 'initiative', id, tab: 'docs' }.
+ *                     Each row also carries scope ('portfolio' | 'board:<id>' | 'initiative:<id>'), board (the board id; for an initiative its
+ *                     board, null when it cannot be read; null for the portfolio) and ws (the workspace id).
+ *
+ * The rows are repository-wide (the ledger is one per repository), so a tree that is not the lead returns []. Nothing here writes.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const CD = require('./core-docs.js');
+
+const NAME = 'core-docs-needs';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+/** The rows of one folded store. Pure: names come from the two lookups. */
+function rowsOf(store, { boardName = (id) => id, titleOf = (id) => id, boardOf = () => null, ws = null, ledgerRel = 'core-docs.jsonl' } = {}) {
+  const by = new Map();
+  for (const x of store.values()) {
+    if (!x.draft) continue;
+    if (!by.has(x.scope)) by.set(x.scope, []);
+    by.get(x.scope).push(x);
+  }
+  const rows = [];
+  for (const [scope, list] of by) {
+    const p = CD.parseScope(scope);
+    if (!p) continue;
+    const n = list.length;
+    const titles = list.map((x) => (CD.entryOf(p.level, x.key) || { title: x.key }).title).join(', ');
+    let question; let go; let ini = null; let board = null;
+    if (p.level === 'portfolio') { question = `${plural(n, 'portfolio draft', 'portfolio drafts')} to review`; go = { view: 'portfolio', tab: 'docs' }; }
+    else if (p.level === 'board') { question = `${n} ${boardName(p.id) || p.id} ${n === 1 ? 'draft' : 'drafts'} to review`; go = { view: 'board', board: p.id, tab: 'docs' }; board = p.id; }
+    else { question = `${plural(n, 'draft', 'drafts')} to review on ${titleOf(p.id) || p.id}`; go = { view: 'initiative', id: p.id, tab: 'docs' }; ini = p.id; board = boardOf(p.id) || null; }
+    rows.push({
+      run_id: `${NAME}:${scope}`, kind: 'core-doc-drafts', initiative_id: ini, question, doc: list[list.length - 1].draft.path, go, scope, board, ws,
+      today: { kind: 1, source: NAME, cause: `PMOS drafted ${titles}. Nothing is sent until you issue it`, evidence: ledgerRel, act: { label: 'Review', cli: null } },
+    });
+  }
+  return rows;
+}
+
+function rowsFor(w, { lead } = {}) {
+  if (!lead || !w || !w.root) return [];
+  const file = CD.ledgerFile(w.root);
+  if (!fs.existsSync(file)) return [];
+  const store = CD.fold(CD.readLines(file));
+  if (![...store.values()].some((x) => x.draft)) return [];
+  const names = new Map();
+  let fr = null;
+  try {
+    const D = require('./driver.js');
+    const dir = D.stateDirOf(w.root);
+    fr = require('./routes-boards.js').frameFor({ stateDirFor: () => dir }, w);
+    for (const b of fr.boards) names.set(b.id, b.name);
+  } catch { /* the id stands in */ }
+  const titles = new Map();
+  const boardOfIni = new Map();
+  try { const r = require('./initiative-rows.js').peek(w.root); if (r && r.ok) for (const x of r.rows) titles.set(x.id, x.title || x.id); } catch { /* the id stands in */ }
+  if (fr) {
+    try {
+      const RB = require('./routes-boards.js');
+      const b = RB.baseRows(w);
+      if (b && b.ok) for (const x of b.rows) { try { boardOfIni.set(x.id, RB.boardIdOf(x, fr.boards, fr.folded, w)); } catch { /* no board */ } }
+    } catch { /* board stays null */ }
+  }
+  let rel = 'core-docs.jsonl';
+  try { rel = path.relative(w.root, file).split(path.sep).join('/'); } catch { /* the plain name stands */ }
+  return rowsOf(store, { boardName: (id) => names.get(id) || id, titleOf: (id) => titles.get(id) || id, boardOf: (id) => boardOfIni.get(id) || null, ws: w.id || null, ledgerRel: rel });
+}
+
+function sig(w) {
+  if (!w || !w.root) return 'none';
+  let st = 'none';
+  try { const s = fs.statSync(CD.ledgerFile(w.root)); st = `${s.size}:${s.mtimeMs}:${s.ino}`; } catch { /* no ledger yet */ }
+  return crypto.createHash('sha1').update(st).digest('hex');
+}
+
+module.exports = { kinds: ['core-doc-drafts'], rowsFor, sig, rowsOf };