create-pmos 0.193.0 → 0.195.0

package/workspace/lib/route-modules.js

@@ -71,6 +71,7 @@ const MODULES = Object.freeze([
   'routes-driver',        // initiative-driver: the Agent strip's data, Keep, Send back, Drop, Pause and the board mode (driver.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)
+  'routes-core-docs',     // core-documents: the core documents of each level, Draft it (a core-doc run), Issue it and Drop (core-docs.jsonl)
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

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

@@ -0,0 +1,171 @@
+'use strict';
+/* routes-core-docs.js — the core documents of each level (initiative core-documents, PRD sections 3 to 5).
+ *
+ *   GET  /api/core-docs?ws&level=portfolio|board|initiative&board&id
+ *        → { ok, level, scope, question, reader, rhythm, build, wfTpl, stage, cat, summary: { draft, due, missing, stale }, docs: [entry + state] }
+ *          202 { ok: true, pending: true } while the initiatives are still being read (level=initiative only)
+ *   POST /api/core-docs/draft  { ws, scope, key }        → { ok, run }      starts a core-doc run; 409 when one runs for that entry
+ *   POST /api/core-docs/issue  { ws, scope, key, slot }  → { ok }           `state: issued` in the file and one `issue` line
+ *   POST /api/core-docs/drop   { ws, scope, key, slot }  → { ok }           one `drop` line
+ *
+ * WHO WRITES. Every POST refuses a request that carries an agent session header (403), as routes-scan.js does. Draft it passes pm-guard
+ * requirePagePress; Issue it and Drop pass requirePmPress (act `issue`): only the PM issues or drops a core document. A draft is never sent.
+ *
+ * THE RUN. A press on Draft it (and the schedule tick) starts ONE headless run, kind `core-doc` (lib/headless.js), origin
+ * `core-doc:<scope>:<key>`. Its tools are Read, Glob, Grep and `pmos coredoc write`; the server pins the entry it may write with
+ * PMOS_CORE_DOC_SCOPE and PMOS_CORE_DOC_KEY. At most RUN_CAP core-doc runs run at once.
+ *
+ * THE TICK (PRD section 4). tick(ctx, { now }) runs every 30 minutes inside the working hours (lib/driver-run.js dayCheckOpen: the day-check
+ * window and the quiet hours). For each repository (the lead tree) it drafts every `doc` entry of the portfolio and of each board whose cadence
+ * has passed (state `due`) and that has no open draft, at most once per entry per day; never an entry the PM writes (`by: you`). Initiative
+ * documents are the Initiative Driver's (lib/driver.js doc-due). ctx adds to the route ctx: { proSettings(), inQuiet(now, quiet), isLead(w) }.
+ */
+const guard = require('./pm-guard.js');
+const CD = require('./core-docs.js');
+const headless = require('./headless.js');
+
+const text = (v) => (typeof v === 'string' ? v : '');
+const bad = (status, error) => ({ status, body: { ok: false, error } });
+const POSTS = ['draft', 'issue', 'drop'];
+const RUN_CAP = 3;
+const TICK_EVERY_MS = 30 * 60 * 1000;
+
+const runs = new Map();     // `${ws}|${scope}|${key}` → session id, for the core-doc runs this server started
+const tried = new Map();    // `${ws}|${scope}|${key}` → the local day the tick last started a run for it
+let lastTick = null;
+
+const runKey = (ws, scope, key) => `${ws}|${scope}|${key}`;
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || null);
+  return w && (!id || w.id === id) ? w : null;
+}
+const isRunning = (ws) => (scope, key) => runs.has(runKey(ws, scope, key));
+
+/** The entry of a scope in this workspace: the level's facts must find the board or the initiative. → { ok, entry, facts } | refusal */
+function resolve(ctx, w, scope, key, now) {
+  const p = CD.parseScope(scope);
+  if (!p) return { ok: false, status: 400, error: 'scope must be portfolio, board:<id> or initiative:<id>' };
+  const entry = CD.entryOf(p.level, key);
+  if (!entry) return { ok: false, status: 400, error: `no core document ${String(key).slice(0, 40)} at the ${p.level} level` };
+  const g = CD.gather(ctx, w, { level: p.level, board: p.level === 'board' ? p.id : null, id: p.level === 'initiative' ? p.id : null, now });
+  if (g.pending) return { ok: false, status: 202, error: 'The initiatives are being read. Ask again in a few seconds.' };
+  if (!g.ok) return g;
+  return { ok: true, entry, facts: g.facts, level: p.level, id: p.id };
+}
+
+/** Start the run that drafts one entry. → { ok, run } | { ok: false, status, error } */
+function startRun(ctx, w, scope, entry, { label, now } = {}) {
+  if (typeof ctx.spawnSession !== 'function') return { ok: false, status: 409, error: 'this workspace cannot start sessions' };
+  const origin = `core-doc:${scope}:${entry.key}`;
+  if (headless.kindFor({ agent: 'claude', origin }) !== 'core-doc') return { ok: false, status: 409, error: 'Background runs are switched off here (PMOS_HEADLESS=off), so PMOS cannot draft this document.' };
+  const k = runKey(w.id, scope, entry.key);
+  if (runs.has(k)) return { ok: false, status: 409, error: `PMOS is drafting the ${entry.title.toLowerCase()} already` };
+  if (runs.size >= RUN_CAP) return { ok: false, status: 409, error: `${RUN_CAP} documents are being drafted already. Try again when one is done.` };
+  const prompt = CD.runPrompt(entry, scope, { today: CD.localDay(now == null ? Date.now() : now), label });
+  const s = ctx.spawnSession({ name: `Core document · ${entry.title}`, agent: 'claude', ws: w.id, origin, initialInput: prompt + '\r',
+    initiative: scope.startsWith('initiative:') ? scope.slice('initiative:'.length) : undefined,
+    extraEnv: { PMOS_CORE_DOC_SCOPE: scope, PMOS_CORE_DOC_KEY: entry.key },
+    onDone: () => { runs.delete(k); try { if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id); } catch { /* the next poll recounts */ } } });
+  if (!s || s.state === 'exited' || s.headless !== 'core-doc') {
+    if (s && s.headless !== 'core-doc' && s.state !== 'exited' && typeof ctx.stopSession === 'function') { try { ctx.stopSession(s.id); } catch { /* best effort */ } }
+    return { ok: false, status: 409, error: 'The draft could not start: ' + ((s && s.note) || 'no background run') };
+  }
+  runs.set(k, s.id);
+  return { ok: true, run: s.id };
+}
+
+const labelOf = (facts) => (facts.level === 'board' && facts.board ? facts.board.name : facts.level === 'initiative' && facts.row ? `${facts.row.id} ${facts.row.title || ''}`.trim() : null);
+
+// ── the tick ─────────────────────────────────────────────────────────────────────────────────────────
+/** Draft each due doc entry of the portfolio and the boards. → [{ ws, scope, key, ok, error? }] */
+function tick(ctx, { now = Date.now(), force = false } = {}) {
+  if (!ctx || typeof ctx.getWs !== 'function') return [];
+  if (!force && lastTick != null && now - lastTick < TICK_EVERY_MS) return [];
+  const settings = (() => { try { return ctx.proSettings ? ctx.proSettings() : null; } catch { return null; } })();
+  const open = require('./driver-run.js').dayCheckOpen(settings || {}, now, ctx.inQuiet || (() => false));
+  if (!open) return [];
+  lastTick = now;
+  if (headless.switchedOff(process.env)) return [];
+  const day = CD.localDay(now);
+  const out = [];
+  const list = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [ctx.getWs(null)].filter(Boolean);
+  for (const w of list) {
+    if (!w || !w.root) continue;
+    if (typeof ctx.isLead === 'function' && !ctx.isLead(w)) continue;
+    const levels = [{ level: 'portfolio' }];
+    try { for (const b of require('./routes-boards.js').frameFor(ctx, w).boards) levels.push({ level: 'board', board: b.id }); } catch { /* the portfolio still drafts */ }
+    for (const lv of levels) {
+      if (runs.size >= RUN_CAP) return out;
+      let g;
+      try { g = CD.gather(ctx, w, { ...lv, now }); } catch { continue; }
+      if (!g.ok) continue;
+      for (const entry of g.facts.entries) {
+        if (runs.size >= RUN_CAP) return out;
+        if (!CD.draftable(entry)) continue;
+        const st = CD.stateOf(entry, g.facts);
+        if (st.st !== 'due' || st.draft) continue;
+        const k = runKey(w.id, g.facts.scope, entry.key);
+        if (runs.has(k) || tried.get(k) === day) continue;
+        const x = g.facts.store.get(`${g.facts.scope}|${entry.key}`);
+        if (x && x.drafts.some((d) => CD.localDay(Date.parse(d.at)) === day)) continue;   // drafted today already (by a press, or before a restart)
+        tried.set(k, day);
+        const r = startRun(ctx, w, g.facts.scope, entry, { label: labelOf(g.facts), now });
+        out.push({ ws: w.id, scope: g.facts.scope, key: entry.key, ok: r.ok, ...(r.ok ? { run: r.run } : { error: r.error }) });
+      }
+    }
+  }
+  return out;
+}
+
+// ── the handler ──────────────────────────────────────────────────────────────────────────────────────
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  const send = (r) => { ctx.json(res, r.body, r.status); return true; };
+  const sub = p.replace(/^\/api\/core-docs\/?/, '');
+
+  if (sub === '') {
+    if (req.method !== 'GET') return send(bad(405, 'GET only'));
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    const level = text(url.searchParams.get('level')) || 'portfolio';
+    const g = CD.gather(ctx, w, { level, board: url.searchParams.get('board') || null, id: url.searchParams.get('id') || null, now: Date.now() });
+    if (g.pending) return send({ status: 202, body: { ok: true, pending: true } });
+    if (!g.ok) return send(bad(g.status || 400, g.error));
+    return send({ status: 200, body: CD.answer(g.facts, { running: isRunning(w.id) }) });
+  }
+  if (!POSTS.includes(sub)) return send(bad(404, 'no such core-docs route'));
+  if (req.method !== 'POST') return send(bad(405, 'POST only'));
+  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 draft, issue or drop a core document. Only a press on the page does'));
+  const g = sub === 'draft' ? guard.requirePagePress(req, body) : guard.requirePmPress(req, body, { act: 'issue' });
+  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 scope = text(body.scope);
+  const key = text(body.key);
+  const now = Date.now();
+  const refresh = () => { try { if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id); } catch { /* the next poll recounts */ } };
+
+  if (sub === 'draft') {
+    const r = resolve(ctx, w, scope, key, now);
+    if (!r.ok) return send(bad(r.status || 400, r.error));
+    if (r.entry.kind !== 'doc') return send(bad(400, `${r.entry.title} is read from its own source; there is nothing to draft here`));
+    if (r.entry.by === 'you') return send(bad(400, `You write the ${r.entry.title.toLowerCase()}. PMOS only checks it`));
+    if (r.level === 'board' && r.entry.build && !r.facts.board.build) return send(bad(400, `${r.entry.title} is only for a board with Build and deliver`));
+    if (r.level === 'initiative' && !r.facts.list.some((x) => x.entry.key === key)) return send(bad(400, `${r.entry.title} is not in this initiative's set`));
+    const s = startRun(ctx, w, scope, r.entry, { label: labelOf(r.facts), now });
+    if (!s.ok) return send(bad(s.status, s.error));
+    return send({ status: 200, body: { ok: true, run: s.run } });
+  }
+  const c = CD.checkEntry(scope, key);
+  if (!c.ok) return send(bad(c.status, c.error));
+  const fn = sub === 'issue' ? CD.issue : CD.drop;
+  const r = fn(w.root, { scope, key, slot: text(body.slot) }, g.actor, { now });
+  if (!r.ok) return send(bad(r.status, r.error));
+  refresh();
+  return send({ status: 200, body: { ok: true } });
+}
+
+module.exports = { prefixes: ['/api/core-docs'], handle, tick, startRun, RUN_CAP, TICK_EVERY_MS, _runs: runs, _reset: () => { runs.clear(); tried.clear(); lastTick = null; } };

package/workspace/lib/routes-driver.js

@@ -135,6 +135,7 @@ async function handle(req, res, url, ctx) {
       stageFile: path.join(stateDir, stageTools.LEDGER),
       itemsDir: path.join(runtimeOf(ctx), 'pm-items'),
       correctionsFile: path.join(runtimeOf(ctx), 'corrections.jsonl'),
+      root: w.root,   // core-documents: Keep of a doc proposal issues the draft (lib/core-docs.js)
       // The board move route's own function: its validation and its warnings apply, and `by` is the PM.
       move: async (pr) => {
         const routesBoards = require('./routes-boards.js');

package/workspace/lib/vendor/scripts/migrate-layout.js

@@ -67,7 +67,7 @@ function registry() {
   try {
     REGISTRY = new Set(fs.readFileSync(path.join(PMOS_ROOT, 'scripts', 'frontmatter_registry.txt'), 'utf8')
       .split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
-  } catch { REGISTRY = new Set(['Concept', 'ADR', 'Template', 'Playbook', 'Reference', 'Initiative', 'PRD', 'Story', 'Rubric', 'OKR', 'Radar', 'Checklist', 'Calibration', 'Research', 'Design', 'Prototype', 'Handover', 'Decision', 'Principle', 'Debt', 'Discovery', 'Guide']); }
+  } catch { REGISTRY = new Set(['Concept', 'ADR', 'Template', 'Playbook', 'Reference', 'Initiative', 'PRD', 'Story', 'Rubric', 'OKR', 'Radar', 'Checklist', 'Calibration', 'Research', 'Design', 'Prototype', 'Handover', 'Review', 'Decision', 'Principle', 'Debt', 'Discovery', 'Guide']); }
   return REGISTRY;
 }
 

package/workspace/lib/vendor/workspace/lib/doc-category.js

@@ -47,7 +47,7 @@ const TYPE_TO_CATEGORY = {
   Concept: 'knowledge', ADR: 'spec-artifact', Template: 'other', Playbook: 'knowledge', Reference: null,
   Initiative: 'spec-artifact', PRD: 'prd', Story: 'spec-artifact', Rubric: 'spec-artifact', OKR: 'spec-artifact',
   Radar: 'report', Checklist: 'other', Calibration: 'report', Research: null, Design: 'spec-artifact',
-  Prototype: 'other', Handover: 'report',
+  Prototype: 'other', Handover: 'report', Review: 'report',
   Decision: 'spec-artifact', Principle: 'knowledge', Debt: 'report', Discovery: 'report', Guide: 'knowledge',
 };
 

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.193.0",
+  "version": "0.195.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.193.0",
+      "version": "0.195.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.193.0",
+  "version": "0.195.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/c3-brief-needs.js

@@ -21,6 +21,7 @@ import { cardView, TAG_STYLE } from './briefing-model.js';
 import { onBriefPage } from './c3-brief-data.js';
 import { button, ensureComponentsCss } from './primitives.js';
 import { loadDriverNeeds, needsRow as driverRow } from './c3-driver.js';
+import { needsLoc } from './c3-core-docs.js';
 
 const reduced = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 const post = (path, body) => pmPost(path, body).catch(() => ({ ok: false }));
@@ -175,6 +176,8 @@ export function needsSection(S) {
   /* the agent's rows: drafts waiting on the PM, a target the PM is blocking. A press opens the initiative (its Overview holds the strip) or Work. */
   let agentSig = '';
   const goAgent = (n) => {
+    const docsLoc = n.kind === 'core-doc-drafts' ? needsLoc(n) : null;
+    if (docsLoc) { try { const u = new URL(location.href); u.searchParams.set('init', docsLoc); history.replaceState(history.state, '', u); } catch { /* no history */ } if (hooks.go) hooks.go({ action: 'goinit' }); try { window.dispatchEvent(new CustomEvent('pmos:ini-go', { detail: { loc: docsLoc } })); } catch { /* the page reads the address when it mounts */ } return; }
     if (n.initiative_id) { try { const u = new URL(location.href); u.searchParams.set('init', 'ini:' + encodeURIComponent(n.ws) + ':' + encodeURIComponent(n.initiative_id) + ':overview'); history.replaceState(history.state, '', u); } catch { /* no history */ } }
     if (hooks.go) hooks.go({ action: n.initiative_id ? 'goinit' : 'gowork' });
   };

package/workspace/public/pm/c3-core-docs.css

@@ -0,0 +1,18 @@
+/* pm/c3-core-docs.css — the core documents of a level (c3-core-docs.js): the agent colour for a draft, the actions under a row, the
+ * panel above a draft in the document sheet. Scoped to .cd-host and .cd-panel; tokens only. */
+.c3 .cd-host { display: contents; }
+.c3 .cd-host .nrow > .acts { grid-column: 2; display: flex; gap: 6px; flex-wrap: wrap; justify-content: flex-start; align-items: flex-start; }
+.c3 .cd-host .st.cd-ag, .c3 .cd-panel .st.cd-ag { color: var(--agent); border-color: color-mix(in oklab, var(--agent) 45%, transparent); background: color-mix(in oklab, var(--agent) 8%, transparent); }
+.c3 .cd-host .chip2.cd-agc { color: var(--agent); }
+.c3 .cd-panel { display: grid; gap: var(--sp-2); min-width: 0; }
+.c3 .cd-panel .fold { border-color: color-mix(in oklab, var(--agent) 45%, transparent); }
+.c3 .cd-oh { margin-top: var(--sp-3); }
+/* The quiet pages (c3-quiet.css) hide teaching sentences and every chip after the second. The approved mockup of the Docs views keeps both:
+ * a row says what the document is for, who reads it, how often it changes and who writes it. */
+.c3 .cd-host .ini-note, .c3 .cd-panel .ini-note { display: block !important; }
+.c3 .cd-host .nrow .nb > .chips > :nth-child(n+3) { display: inline-flex !important; }
+.c3 [data-ini="pf-docs"] .ini-lhm .dim { display: block !important; }
+.c3 .cd-host .sect .sh2 .ini-meta { display: inline !important; }
+/* the heading above the board's other documents: the look of a section heading, without a card around the search and the groups */
+.c3 .cd-host .cd-oh { display: flex; justify-content: space-between; align-items: center; gap: 8px; padding: var(--sp-3) 0 var(--sp-2); border-bottom: 1px solid var(--border); }
+.c3 .cd-host .cd-oh h2 { margin: 0; font: 500 var(--fs-2) var(--mono); color: var(--muted-foreground); text-transform: uppercase; letter-spacing: .06em; display: flex; gap: 8px; align-items: center; }

package/workspace/public/pm/c3-core-docs.js

@@ -0,0 +1,234 @@
+/* pm/c3-core-docs.js — the core documents of a level (initiative core-documents, PRD section 6; the approved mockup 43-doc-levels.js).
+ * Each level answers one question for one reader: Portfolio, Board, Initiative. Its Docs view starts with the level's core set, from
+ *   GET  /api/core-docs?ws&level=portfolio|board|initiative&board&id   { ok, level, scope, question, reader, rhythm, build, wfTpl, stage, cat,
+ *                                                                          summary, docs: [entry + state] }
+ *   POST /api/core-docs/draft { ws, scope, key }          { ok, run }   Draft it, and Redraft ("Ask PMOS to change it")
+ *   POST /api/core-docs/issue { ws, scope, key, slot }    { ok }        Issue it
+ * The server holds the sets, the states and the drafts; this file draws them and holds nothing.
+ *
+ *   coreDocs(env)    -> { left, right, dispose }   two hosts to put in the columns of cols(): the sections and the cards. env =
+ *                      { api, level, board?, id?, ws, today, toast, nav: { tab(tab), tool(tool), reports() }, boardRow?, iniDocs?: { docs, initiatives } }
+ *   needsLoc(row)    -> the `init=` address of the Docs view a Briefing row (kind core-doc-drafts) opens
+ *   segBadge(n)      the count badge of the Portfolio's Documents segment
+ * A press on a row opens `open`: { path } the document sheet, { tab } the board tab, { tool } the initiative's Overview tool, { reports } Reports.
+ * Review the draft opens the draft in the document sheet. The sheet holds the actions: a panel above the draft (docAbove, the sheet's own hook)
+ * with Issue it and Ask PMOS to change it, which asks for a new draft. Nothing is sent to anyone; the PM's press issues it. */
+import { el } from './dom.js';
+import { icon, pbtn, lk, chip, tag, st, note, sect, card, list, nrow, plural, day, ago, sw, chgl, mono, put, ensureIniCss } from './c3-ini-ui.js';
+
+const BY = { you: 'You write it', proposes: 'PMOS proposes', drafts: 'PMOS drafts it', files: 'PMOS files it', watches: 'PMOS watches it', keeps: 'PMOS keeps it current', live: 'Live view', reviews: 'PMOS reviews, you accept' };
+const AGENT_BY = ['drafts', 'proposes', 'files', 'watches', 'keeps', 'reviews'];
+const CAT_IC = { Discover: 'search', Plan: 'cal', Do: 'bolt', Learn: 'up' };
+const CAT_ORDER = ['Discover', 'Plan', 'Do', 'Learn'];
+const POLL_MS = 4000;
+const PENDING_MS = 1500;
+
+function ensureCss() {
+  if (typeof document === 'undefined' || document.querySelector('link[data-c3-cd]')) return;
+  ensureIniCss();
+  const l = document.createElement('link');
+  l.rel = 'stylesheet'; l.href = new URL('./c3-core-docs.css', import.meta.url).href; l.setAttribute('data-c3-cd', '');
+  document.head.appendChild(l);
+}
+
+/** The count badge of the Portfolio's Documents segment (hidden at 0). */
+export function segBadge(n) { return el('span', { class: 'bdg', 'data-cd': 'seg-badge', ...(n ? {} : { hidden: '' }) }, String(n || 0)); }
+
+/** The address of the Docs view a Briefing row opens, as the `init=` value (c3-initiatives.js parseLoc). Null when the row names no scope. */
+export function needsLoc(row) {
+  const r = row || {};
+  const raw = String(r.scope || (/(?:^|:)(portfolio|board:[^:|]+|ini(?:tiative)?:[^:|]+)$/.exec(String(r.run_id || '')) || [])[1] || '');
+  if (raw == 'portfolio') return 'docs';
+  let m = /^board:(.+)$/.exec(raw);
+  if (m) return 'board:' + encodeURIComponent(m[1]) + ':docs';
+  m = /^ini(?:tiative)?:(.+)$/.exec(raw);
+  const id = m ? m[1] : r.initiative_id;
+  if (id) return 'ini:' + encodeURIComponent(r.board || r.ws || '') + ':' + encodeURIComponent(id) + ':docs';
+  return null;
+}
+
+/* ── the sheet's draft panel ── */
+const DRAFTS = new Map();   // path -> { ws, api, scope, key, slot, toast, ui, done }
+const NODES = new WeakMap();
+let hooked = null;
+function hookSheet() {
+  if (!hooked) hooked = import('./c3-doc-sheet.js').then((m) => { m.docAbove.push(({ doc, key }) => { const e = DRAFTS.get(doc.path); if (!e) return null; if (!NODES.has(key)) NODES.set(key, draftPanel(e)); return NODES.get(key); }); return m; });
+  return hooked;
+}
+function draftPanel(e) {
+  const msg = el('div', { class: 'fold w', role: 'alert', hidden: '', 'data-cd': 'panel-error' });
+  const fail = (t) => { msg.textContent = t; msg.hidden = false; };
+  let busy = false;
+  const act = (path, body, done) => async () => {
+    if (busy) return; busy = true; msg.hidden = true;
+    const r = await e.api.post(path, { scope: e.scope, key: e.key, ...body }).catch(() => null);
+    busy = false;
+    if (!r || !r.ok) { fail((r && r.error) || 'no answer'); return; }
+    done(); if (e.ui && e.ui.close) e.ui.close();
+    if (e.done) e.done();
+  };
+  const issue = act('/api/core-docs/issue', { slot: e.slot }, () => { DRAFTS.delete(e.path); e.toast('Issued. Nothing was sent to anyone.'); });
+  const redraft = act('/api/core-docs/draft', {}, () => { e.toast('PMOS is drafting it again. The new draft replaces this one when it is ready.'); });
+  return el('div', { class: 'cd-panel', 'data-cd': 'draft-panel' },
+    el('div', { class: 'fold' }, icon('spark', 'sm'), el('span', null, ' PMOS drafted this from its sources. Nothing is sent. Read it, change what you like, then issue it.')),
+    el('div', { class: 'chips2' }, pbtn('primary', 'Issue it', 'check', { 'data-cd-issue': e.key, onclick: issue }), pbtn('outline', 'Ask PMOS to change it', 'spark', { 'data-cd-redraft': e.key, onclick: redraft })),
+    msg);
+}
+
+/* ── rows ── */
+const summaryLine = (docs) => {
+  const n = (s) => docs.filter((d) => d.st === s).length;
+  return [n('draft') ? plural(n('draft'), 'draft') + ' to review' : '', n('due') ? n('due') + ' due' : '', n('missing') ? n('missing') + ' not started' : ''].filter(Boolean).join(', ') || 'Everything is up to date';
+};
+const isAgent = (d) => d.running || d.st === 'draft';
+
+function stChip(d) {
+  if (d.running) return el('span', { class: 'st cd-ag', 'data-cd-state': 'running' }, icon('spark', 'sm'), 'Agent drafting');
+  const a = { 'data-cd-state': d.st };
+  switch (d.st) {
+    case 'ok': return st('ok', 'check', 'Up to date', a);
+    case 'due': return st('warn', 'clock', d.due ? 'Due ' + day(d.due) : 'Due now', a);
+    case 'draft': return el('span', { class: 'st cd-ag', ...a }, icon('spark', 'sm'), 'Draft ready' + (d.due ? ', due ' + day(d.due) : ''));
+    case 'missing': return st('bad', 'alert', 'Not started', a);
+    case 'stale': return st('warn', 'clock', 'Out of date', a);
+    default: return el('span', { class: 'chip2 dim', ...a }, 'Comes later');
+  }
+}
+const byChip = (k) => (AGENT_BY.includes(k) ? el('span', { class: 'chip2 cd-agc' }, icon('spark', 'sm'), BY[k]) : chip(icon(k === 'live' ? 'eye' : 'user', 'sm'), BY[k] || k));
+
+function pathNameOf(env, d) { return d.title + (env.scopeLabel ? ' · ' + env.scopeLabel : ''); }
+
+async function openSheetFor(env, d, path, draft) {
+  try {
+    const m = await hookSheet();
+    const ui = m.openDocSheet({ ws: env.ws, doc: { path, name: pathNameOf(env, d), ty: draft ? 'Draft' : 'Document', v: '', st: draft ? 'draft' : d.st, ini: env.level === 'initiative' ? env.id : '', iniName: '' },
+      library: () => env.api.get('/api/docs/library', env.board ? { board: env.board } : {}) });
+    if (draft) { const e = DRAFTS.get(path); if (e) e.ui = ui; }
+    return ui;
+  } catch { env.toast('The document sheet could not open. The file is ' + path + '.'); return null; }
+}
+
+function press(env, d, redraw) {
+  const o = d.open || null;
+  if (!o) return null;
+  if (o.path) return () => openSheetFor(env, d, o.path, false);
+  if (o.tab) return () => env.nav.tab(o.tab);
+  if (o.tool) return () => env.nav.tool(o.tool);
+  if (o.reports) return () => env.nav.reports();
+  return null;
+}
+
+function review(env, d, redraw) {
+  const p = d.draft && d.draft.path;
+  if (!p) return () => env.toast('The draft has no file yet. Try again in a moment.');
+  return () => {
+    DRAFTS.set(p, { path: p, ws: env.ws, api: env.api, scope: env.scope, key: d.key, slot: d.draft.slot, toast: env.toast, ui: null, done: redraw });
+    openSheetFor(env, d, p, true);
+  };
+}
+
+async function draftIt(env, d, redraw) {
+  const r = await env.api.post('/api/core-docs/draft', { scope: env.scope, key: d.key }).catch(() => null);
+  if (!r || !r.ok) { env.toast('The draft did not start: ' + ((r && r.error) || 'no answer') + '.'); return; }
+  env.toast('PMOS is drafting the ' + d.title.toLowerCase() + '. It lands here as a draft for you to review.');
+  redraw();
+}
+
+function coreRow(env, d, redraw) {
+  const open = press(env, d, redraw);
+  const meta = [d.when && !['later', 'missing'].includes(d.st) ? chip(icon('clock', 'sm'), (d.st === 'draft' ? 'drafted ' : 'updated ') + ago(d.when, env.today)) : null,
+    d.flag ? st('warn', 'alert', d.flag) : null, d.staleWhy && d.st === 'stale' ? chip(d.staleWhy) : null];
+  let action = null;
+  if (!d.running && d.st === 'draft') action = pbtn('primary', 'Review the draft', 'spark', { 'data-cd-review': d.key, onclick: review(env, d, redraw) });
+  else if (!d.running && d.kind === 'doc' && d.by !== 'you' && (d.st === 'missing' || d.st === 'stale')) action = pbtn('outline', 'Draft it', 'spark', { 'data-cd-draft': d.key, onclick: () => draftIt(env, d, redraw) });
+  return nrow({ ic: d.ic || 'doc', hot: isAgent(d) || d.st === 'missing', title: [d.title, d.isNew ? [' ', tag('new')] : null], onOpen: open || undefined, openLabel: open ? 'Open ' + d.title : undefined,
+    titleAttrs: { 'data-cd-open': d.key }, sub: d['for'] || '',
+    chips: [stChip(d), d.cadence ? chip(icon('cal', 'sm'), d.cadence) : null, d.reader ? chip(icon('user', 'sm'), d.reader) : null, byChip(d.by), ...meta],
+    right: [action], attrs: { 'data-cd-row': d.key, 'data-cd-st': d.running ? 'running' : d.st } });
+}
+
+/* ── the sections ── */
+function coreSection(env, data, redraw) {
+  return sect({ ic: 'doc', title: 'Core documents', count: data.docs.length, attrs: { 'data-cd': 'core' }, right: mono(summaryLine(data.docs)) },
+    list(data.docs.map((d) => coreRow(env, d, redraw)), { 'data-cd': 'core-list' }));
+}
+
+function iniSections(env, data, redraw) {
+  const cur = data.cat || 'Plan';
+  return CAT_ORDER.map((c) => {
+    const ds = data.docs.filter((d) => d.cat === c);
+    if (!ds.length) return null;
+    const ic = CAT_IC[c];
+    const a = (extra) => ({ 'data-cd-cat': c, ...extra });
+    if (ds.every((d) => d.st === 'later')) return sect({ ic, title: c, count: ds.length, attrs: a({ 'data-cd-fold': 'later' }), right: chip('Comes later') },
+      el('div', { class: 'chips2' }, ...ds.map((d) => el('span', { class: 'chip2 dim' }, icon(d.ic || 'doc', 'sm'), d.title))));
+    if (c !== cur && ds.every((d) => d.st === 'ok' && !d.running)) return sect({ ic, title: c, count: ds.length, attrs: a({ 'data-cd-fold': 'done' }), right: st('ok', 'check', 'All ' + ds.length + ' up to date') },
+      el('div', { class: 'chips2' }, ...ds.map((d) => { const o = press(env, d, redraw); return o ? lk({ onclick: o, 'data-cd-chip': d.key }, icon(d.ic || 'doc', 'sm'), d.title) : el('span', { class: 'chip2' }, icon(d.ic || 'doc', 'sm'), d.title); })));
+    return sect({ ic, title: c + (c === cur ? ' · now' : ''), count: ds.length, attrs: a({ 'data-cd-fold': 'open' }), right: chip(sw(c), ds.filter((d) => d.st === 'ok').length + ' of ' + ds.length + ' done') },
+      list(ds.map((d) => coreRow(env, d, redraw))));
+  }).filter(Boolean);
+}
+
+/* ── the cards of the right column ── */
+const levelCard = (data, extra) => card({ ic: 'info', title: 'What this level is for', attrs: { 'data-cd': 'level' } },
+  el('p', { class: 'ini-p' }, el('b', null, data.question || '')),
+  note('Read by ' + (data.reader || 'the team') + '. Changes ' + (data.rhythm || 'as it changes') + '.' + (data.level == 'portfolio' ? ' Boards and initiatives link up to it through their key result, so nothing here repeats what a board says.' : '')),
+  ...extra);
+
+function draftsCard(env, data, redraw) {
+  const ds = data.docs.filter((d) => d.st === 'draft' && !d.running);
+  return card({ ic: 'spark', title: 'Drafts waiting for you', attrs: { 'data-cd': 'drafts' } },
+    ds.length ? chgl(ds.map((d) => el('li', null, icon('spark', 'sm'), el('span', null, lk({ onclick: review(env, d, redraw), 'data-cd-wait': d.key }, d.title), d.due ? ' due ' + day(d.due) : ''), tag('Briefing'))))
+      : note('No draft is waiting.'),
+    note('Drafts also show as one Briefing card. Nothing is sent until you issue it.'));
+}
+const connectCard = () => card({ ic: 'init', title: 'How the levels connect', attrs: { 'data-cd': 'connect' } }, chgl([
+  el('li', null, icon('alert', 'sm'), el('span', null, 'Risks are written once, on the initiative. Board risks and cross-board risks collect them.')),
+  el('li', null, icon('up', 'sm'), el('span', null, 'Each initiative\'s outcome review feeds the board retro and the quarterly review.')),
+  el('li', null, icon('report', 'sm'), el('span', null, 'Status reports at every level come from the same dashboard, so they agree.'))]));
+
+function rightCards(env, data, redraw) {
+  if (data.level == 'portfolio') return [levelCard(data, []), draftsCard(env, data, redraw), connectCard()];
+  if (data.level === 'board') {
+    const b = env.boardRow || {};
+    const ini = env.iniDocs;
+    return [levelCard(data, [note(data.build ? 'Build and deliver is on, so the set adds the sprint review and release notes' + (b.jira ? ' from Jira ' + b.jira : '') + '.' : 'Build and deliver is off, so there is no sprint review or release notes. Progress comes from PMOS tasks.')]),
+      card({ ic: 'doc', title: 'Initiative documents', attrs: { 'data-cd': 'ini-docs' } },
+        note('Each initiative keeps its own PRD, rubric, risks and outcome review on its Docs tab.' + (ini ? ' ' + plural(ini.docs, 'document') + ' across ' + plural(ini.initiatives, 'initiative') + '.' : '')))];
+  }
+  return [levelCard(data, [note('The set grows with the workflow: each stage adds the documents it needs, and later stages wait.'), data.wfTpl === 'research' ? note('Research only: nothing gets built, so there is no PRD, rubric, design or launch checklist.') : null]),
+    card({ ic: 'alert', title: 'Order rules', attrs: { 'data-cd': 'order' } }, note('A missing PRD or rubric before Build shows as a warning on the initiative, never a block. The CI gate still needs a PRD and a rubric before a pull request merges.'))];
+}
+
+/** The two hosts of a level's core documents. Reads the set, draws it, and reads it again after a press and while an agent drafts. */
+export function coreDocs(env) {
+  ensureCss();
+  const left = el('div', { class: 'cd-host', 'data-cd-host': 'left' }, note('Reading the core documents'));
+  const right = el('div', { class: 'cd-host', 'data-cd-host': 'right' });
+  let dead = false; let timer = null; let seq = 0; let last = null;
+  const get = () => env.api.get('/api/core-docs', { level: env.level, board: env.level == 'portfolio' ? '' : env.board, id: env.level === 'initiative' ? env.id : '' });
+  async function load() {
+    const token = ++seq;
+    const r = await get().catch(() => null);
+    if (dead || token !== seq) return;
+    clearTimeout(timer);
+    if (r && r.pending) { // the initiative rows are still loading: say so and ask again
+      put(left, note('Reading the core documents')); put(right);
+      timer = setTimeout(() => { if (!dead && left.isConnected) load(); }, PENDING_MS); return;
+    }
+    if (!r || !r.ok || !Array.isArray(r.docs)) {
+      put(left, el('div', { class: 'fold w', role: 'alert', 'data-cd': 'error' }, icon('alert', 'sm'), 'The core documents could not be read: ' + ((r && r.error) || 'no answer') + '.'));
+      put(right); return;
+    }
+    const redraw = () => { load(); };
+    last = { r, redraw };
+    put(left, ...(env.level === 'initiative' ? iniSections({ ...env, scope: r.scope }, r, redraw) : [coreSection({ ...env, scope: r.scope }, r, redraw)]));
+    put(right, ...rightCards({ ...env, scope: r.scope }, r, redraw));
+    if (env.onData) env.onData(r);
+    if (r.docs.some((d) => d.running)) timer = setTimeout(() => { if (!dead && left.isConnected) load(); }, POLL_MS);
+  }
+  load();
+  return { left, right, dispose() { dead = true; clearTimeout(timer); }, reload: load,
+    /** The counts of the board's other documents, for the Initiative documents card. */
+    setIniDocs(v) { env.iniDocs = v; if (last) put(right, ...rightCards({ ...env, scope: last.r.scope }, last.r, last.redraw)); } };
+}