create-pmos 0.52.0 → 0.53.1

package/workspace/lib/board-cli.js

@@ -0,0 +1,108 @@
+'use strict';
+/* board-cli.js — `pmos board`: the Board's items, by column, from a terminal (pm-os-absorb Run 4, slice 4D, PRD R24).
+ *
+ *   pmos board [--mine | --init <initiative>] [--json] [--root <dir>]
+ *
+ * The SAME fold the Board page reads (lib/board-fold.js, the one behind GET /api/board), so a terminal line and a card
+ * cannot disagree about an item. No server is needed: the command reads the ledgers of the repository. With no flag it
+ * prints the Active filter (an item with an event in the last stall_days, an open item under an initiative in Now, and
+ * your own items). `--mine` prints your own items. `--init <initiative>` prints one initiative. `--json` prints the same
+ * answer as GET /api/board for that filter, without the workspace id. The command only reads: it writes no line.
+ *
+ * Exit codes: 0 done, 1 refused (an initiative that is not on the Board, an unreadable repository), 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const consoleState = require('./console-state');
+const boardFold = require('./board-fold.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { board: [] };
+const USAGE = [
+  'usage: pmos board [--mine | --init <initiative>] [--json] [--root <dir>] — the items of every initiative, by column',
+  '  pmos board                      the Active filter: recent events, open items under Now, and your own items',
+  '  pmos board --mine               your own items',
+  '  pmos board --init <initiative>  one initiative',
+  '  pmos board --json               the answer of GET /api/board, for scripts',
+  'Done shows the last 14 days. A work initiative only: a document initiative has no item on the Board.',
+];
+const BOOL = new Set(['json', 'mine', 'help']);
+const VALUE = new Set(['init', 'root']);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const COLUMNS = [['todo', 'Todo'], ['doing', 'Doing'], ['review', 'Review'], ['done', 'Done']];
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+const shortDate = (d) => { const t = new Date(d + 'T00:00:00Z'); return `${t.getUTCDate()} ${MONTHS[t.getUTCMonth()]}`; };
+const ownerOf = (o) => (o === 'you' ? 'you' : o === 'agent' ? 'agent' : String(o).replace(/^[a-z]+:/, ''));
+
+/** One card as a line: initiative · stage · "title" · owner, then what a person must notice. */
+function line(it, titleOf) {
+  const bits = [titleOf[it.initiative] || it.initiative, it.stageLabel, `"${it.title}"`, ownerOf(it.owner)];
+  if (it.due) bits.push(`due ${shortDate(it.due)}`);
+  if (it.blocked) bits.push(`blocked: ${it.blocked.reason}`);
+  if (it.noEvidence) bits.push('no evidence');
+  if (it.late) bits.push('late');
+  if (it.overrideShown) bits.push('moved by you');
+  if (it.proposed) bits.push('proposed');
+  if (it.factory && it.factory.notMerged && it.factory.label) bits.push(it.factory.label);
+  return bits.join(' · ');
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), now } = {}) {
+  const args = argv[0] === 'board' ? argv.slice(1) : argv.slice();
+  const { pos, flags } = parse(args);
+  if (flags.help) { for (const l of USAGE) say(l); return 0; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  if (pos.length) { say(`pmos board takes no argument (${pos[0]}). To show one initiative, type: pmos board --init <initiative>`); return 2; }
+  if (flags.mine && flags.init) { say('--mine and --init cannot be used together. Choose one filter.'); return 2; }
+  const json = !!flags.json;
+  const filter = flags.mine ? 'mine' : flags.init ? 'init:' + flags.init : 'active';
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  // a root that is not a PMOS repository is refused: the fold would read it as a repository with no initiatives
+  try {
+    const loaded = consoleState.loadEngine();
+    if (!loaded.ok) return fail('the workflow engine is not installed: ' + loaded.error);
+    if (!fs.statSync(root).isDirectory() || !fs.statSync(loaded.engine.layout(root).initiatives).isDirectory()) throw new Error('no initiatives directory');
+  } catch (e) { return fail(`${root} is not a PMOS repository (no initiatives directory)`); }
+  let out;
+  try { out = boardFold.boardFor({ id: 'cli', root }, { filter, now }); }
+  catch (e) { return fail('the Board could not be read: ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!out.ok) return fail(out.error, out.status === 400 ? 2 : 1);
+  if (json) { say(JSON.stringify(out)); return 0; }
+  const titleOf = Object.fromEntries(out.initiatives.map((i) => [i.id, i.title]));
+  const label = out.filter === 'active' ? 'Active' : out.filter === 'mine' ? 'Mine' : out.filter.slice(5);
+  const n = COLUMNS.reduce((s, [k]) => s + out.board[k].length, 0);
+  say(`Board · ${label} · ${n === 1 ? '1 item' : n + ' items'}`);
+  for (const [k, name] of COLUMNS) {
+    const ids = out.board[k];
+    say(`${name} · ${ids.length}${k === 'done' && out.board.doneOlder ? ` · ${out.board.doneOlder} older in the Tree` : ''}`);
+    for (const id of ids) say('  ' + line(out.items[id], titleOf));
+  }
+  const rel = out.releases || [];
+  if (rel.length) {
+    say(`Release · ${rel.length}`);
+    for (const r of rel) say(`  ${r.initiativeTitle} · batch ${r.batch} · ${r.items.length === 1 ? '1 work item' : r.items.length + ' work items'} ready`);
+  }
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/board-fold.js

@@ -0,0 +1,232 @@
+'use strict';
+/* board-fold.js — the Board's ONE fold: every work item of every work-lane initiative, in its column (pm-os-absorb Run 4,
+ * slice 4D; PRD R9, R19, R12 kind 4; D86 points 1 and 4).
+ *
+ *   boardFor(w, { filter, now }) → { ok: true, filter, now, sig, initiatives, items, board, counts }
+ *                                | { ok: false, status, error }
+ *   parseFilter(text)            → { kind: 'active' | 'mine' | 'init', init? } | null
+ *   workInitiatives(root)        → [{ id, title, lane, laneLabel }]   the work lanes only (D86 point 4)
+ *   factoryView(entry, item)     → { item, state, pr, integrated, notMerged, label } | null
+ *
+ * THREE READERS, ONE ANSWER. GET /api/board (lib/routes-board.js), `pmos board` (lib/board-cli.js) and the Today rows of
+ * lib/work-check-needs.js all read through this file, so a card, a terminal line and a Today card cannot disagree about
+ * an item. The fold is lib/plan-items.js's: a card's column is its tree row's state, because both read the same fold and
+ * lib/plan-tree.js layout() builds each initiative's columns (R19, the same 14-day Done window).
+ *
+ * FILTERS (R9). `active` is the default: an item with an event in the last stall_days (planning/plan-rules.json), an open
+ * item under an initiative that is in Now, and the PM's own items (owner `you`). `mine` is the PM's own items. `init:<id>`
+ * is one initiative. Done shows the last 14 days under Active and under an initiative, however old the item's last event is
+ * (the layout's own window, lib/plan-tree.js DONE_WINDOW_MS); older Done items are counted, never listed. Under Mine, Done
+ * shows the PM's own items by the same window.
+ *
+ * WORK LANES ONLY. A document lane (scripts/lane-defs.js group 'document': prd, strategy, project-plan, decision-record,
+ * report) is a file, not a row: its initiative has no card, no option in the filter and no needs row. The group is read
+ * from the lane definitions, never from a list kept here.
+ *
+ * FACTORY. A work item that the factory materialized from a plan item carries `factory` (lib/factory-join.js): its state,
+ * its pull request, whether `pmos verify-work` saw it integrated. A card dragged to Done before that reads "Done · your
+ * call · not merged" (R7). Nothing here writes a factory record; the factory graph never writes the control graph.
+ *
+ * THE PAGE NEVER SEES A SESSION TOKEN (F5). Every `by` in the answer goes through actor.pageName, and so does every
+ * batch name. The signature is taken BEFORE the ledgers are read (the F2 fix): a line appended during the read leaves a
+ * signature older than the data at worst, which costs one more read and never hides a change.
+ */
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+const consoleState = require('./console-state');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const placements = require('./placements.js');
+const ledgers = require('./plan-ledgers.js');
+const factoryJoin = require('./factory-join.js');
+const planRules = require('./plan-rules.js');
+const actor = require('./actor.js');
+
+const DAY = 86400000;
+const HORIZON_RANK = { now: 0, next: 1, later: 2 };
+const STATES = ['todo', 'doing', 'review', 'done'];
+const NOT_MERGED = planTree.NOT_MERGED_LABEL || 'Done · your call · not merged';
+const TOKEN_TEXT_RE = /\b(sess-\d+)\.[0-9a-f]{8}\b/g;
+const scrub = (t) => (typeof t === 'string' ? t.replace(TOKEN_TEXT_RE, '$1') : t);
+
+function parseFilter(text) {
+  const f = text == null || text === '' ? 'active' : String(text);
+  if (f === 'active' || f === 'mine') return { kind: f };
+  const m = /^init:(.+)$/.exec(f);
+  if (m && planItems.INIT_RE.test(m[1])) return { kind: 'init', init: m[1] };
+  return null;
+}
+const canonical = (f) => (f.kind === 'init' ? 'init:' + f.init : f.kind);
+
+/** The initiatives of `root` whose lane is a work lane, with the title their record gives. */
+function workInitiatives(root) {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  const eng = loaded.engine;
+  const out = [];
+  for (const id of eng.listInitiatives(root)) {
+    let pl;
+    try { pl = planTree.profileAndLane(root, id); } catch { continue; }
+    if (pl.group !== 'work') continue;
+    const def = (pl.defs && pl.defs[pl.lane]) || {};
+    let title = id;
+    if (pl.record) {
+      try { title = String((eng.parseLeadingFrontmatter(fs.readFileSync(pl.record, 'utf8')) || {}).title || '').trim() || id; } catch { title = id; }
+    }
+    out.push({ id, title, lane: pl.lane, laneLabel: def.label || pl.lane });
+  }
+  return out;
+}
+
+/** One initiative's batches as the page names them: a repeated actor reads `agent:sess-3#2` (as the Breakdown names them). */
+function pageBatches(batches) {
+  const seen = new Map();
+  return (batches || []).map((b) => {
+    const shown = actor.pageName(b.by);
+    const n = (seen.get(shown) || 0) + 1;
+    seen.set(shown, n);
+    const name = n === 1 ? shown : `${shown}#${n}`;
+    return { ...b, key: name, by: name };
+  });
+}
+
+/** An item as the page is sent it: no session token in any actor or text. */
+function pageItem(it, extra) {
+  return {
+    ...it, ...extra,
+    createdBy: actor.pageName(it.createdBy), updatedBy: actor.pageName(it.updatedBy), movedBy: actor.pageName(it.movedBy),
+    note: scrub(it.note),
+    blocked: it.blocked ? { ...it.blocked, by: actor.pageName(it.blocked.by), reason: scrub(it.blocked.reason) } : it.blocked,
+    history: (it.history || []).map((h) => ({ ...h, by: actor.pageName(h.by), text: scrub(h.text) })),
+  };
+}
+
+/** The factory's view of one plan item: { item, state, pr, integrated, notMerged, label } or null. */
+function factoryView(entry, it) {
+  if (it.factory && typeof it.factory === 'object') return it.factory;   // lib/plan-tree.js already joined it
+  const w = entry && (entry.items || []).find((x) => x && x.plan_item === it.id);
+  if (!w) return null;
+  const notMerged = it.state === 'done' && w.integrated !== true;
+  return { item: w.id, state: w.state, pr: w.pr || null, integrated: w.integrated === true, notMerged, label: notMerged ? NOT_MERGED : null };
+}
+
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const statOf = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}`; } catch { return 'none'; } };
+
+/** The grants a release press made, by target `<initiative>:<batch>`: read only, and only the lines that still hold. A grant
+ *  holds while it is unexpired, or once it is used (the factory spent it). Expired and unused, it is gone: the PM may press again. */
+function releaseGrants(root, now = Date.now()) {
+  const out = new Map();
+  let text = '';
+  try { text = fs.readFileSync(path.join(ledgers.runsDir(root), 'grants.jsonl'), 'utf8'); } catch { return out; }
+  const rows = [];
+  for (const raw of text.split('\n')) { if (!raw.trim()) continue; try { rows.push(JSON.parse(raw)); } catch { /* a torn line is the writer's to name */ } }
+  const used = new Set(rows.filter((r) => r && r.type === 'use' && typeof r.grant_id === 'string').map((r) => r.grant_id));
+  for (const r of rows) {
+    if (!r || r.type !== 'grant' || r.scope !== 'release' || typeof r.target !== 'string') continue;
+    if (used.has(r.id) || !(Date.parse(r.expires_at) <= now)) out.set(r.target, { grant_id: r.id });
+  }
+  return out;
+}
+
+/** What the page's views read besides the two plan ledgers and the factory join: the initiative records (title, lane), the
+ *  rules file (stall_days) and the grants ledger (a pressed Release card goes). One stat each, so a write by the CLI shows. */
+function sideSig(root) {
+  const parts = [];
+  try {
+    const eng = consoleState.loadEngine();
+    if (eng.ok) for (const id of eng.engine.listInitiatives(root)) { const pl = planTree.profileAndLane(root, id); parts.push(id + '=' + (pl.record ? statOf(pl.record) : 'none') + ':' + pl.lane); }
+  } catch { parts.push('initiatives:unreadable'); }
+  try { const rp = planRules.rulesPath(root); parts.push('rules=' + (rp ? statOf(rp) : 'none')); } catch { parts.push('rules:unreadable'); }
+  try { parts.push('grants=' + statOf(path.join(ledgers.runsDir(root), 'grants.jsonl'))); } catch { parts.push('grants:unreadable'); }
+  return sha1(parts.join('|'));
+}
+
+/** The signature alone, for the page's watcher: the same hash boardFor puts in `sig`, taken without reading the items. */
+function sigFor(w) {
+  const root = w.root;
+  let itemsSig; let placeSig;
+  try { itemsSig = planItems.ledgerSigs([{ id: w.id, root }], '')[w.id].items; } catch { itemsSig = 'unreadable'; }
+  try { placeSig = ledgers.ledgerSig(root, 'placements'); } catch { placeSig = 'unreadable'; }
+  const join = factoryJoin.joinFactory(root);
+  return sha1([itemsSig, placeSig, JSON.stringify(join.byInit || {}), String((join.flags || []).length), sideSig(root)].join('|'));
+}
+
+function boardFor(w, { filter, now = Date.now() } = {}) {
+  const f = parseFilter(filter);
+  if (!f) return { ok: false, status: 400, error: 'the filter is active, mine or init:<initiative>' };
+  const root = w.root;
+  // the signature first (F2): the ledgers it names are read below
+  let itemsSig; let placeSig;
+  try { itemsSig = planItems.ledgerSigs([{ id: w.id, root }], '')[w.id].items; } catch { itemsSig = 'unreadable'; }
+  try { placeSig = ledgers.ledgerSig(root, 'placements'); } catch { placeSig = 'unreadable'; }
+
+  const sideSigAt = sideSig(root);
+  const inits = workInitiatives(root);
+  if (f.kind === 'init' && !inits.some((i) => i.id === f.init)) {
+    return { ok: false, status: 404, error: `no initiative ${f.init} on the Board` };
+  }
+  const rules = planRules.readRules(root);
+  const place = placements.readPlacements(root, { now, rules, records: inits.map((i) => ({ id: i.id, lane: i.lane })) });
+  const join = factoryJoin.joinFactory(root);
+  const fold = planItems.readFold(root, { now });
+  const stallMs = rules.stall_days * DAY;
+
+  const rows = inits.map((i) => {
+    const p = place.byInit && place.byInit[i.id];
+    return { ...i, horizon: placements.horizonOf(place, i.id), rank: p && Number.isFinite(p.rank) ? p.rank : 0 };
+  }).sort((a, b) => (HORIZON_RANK[a.horizon] - HORIZON_RANK[b.horizon]) || (a.rank - b.rank) || a.id.localeCompare(b.id));
+
+  const wanted = (it, row) => {
+    if (f.kind === 'init') return it.initiative === f.init;
+    if (it.owner === 'you') return true;
+    if (f.kind === 'mine') return false;
+    if (it.state === 'done') return true;   // plan-tree's 14-day window lists the recent ones; the rest are counted
+    if (row.horizon === 'now') return true;
+    return Date.parse(it.updatedAt) >= now - stallMs;
+  };
+
+  const items = {};
+  const board = { todo: [], doing: [], review: [], done: [], doneOlder: 0 };
+  const initiatives = [];
+  for (const row of rows) {
+    const lay = planTree.layout({ root, initiative: row.id, fold, ladder: null, now });
+    const entry = factoryJoin.factoryOf(join, row.id);
+    const keep = new Set(Object.keys(lay.items).filter((id) => wanted(lay.items[id], row)));
+    let listed = 0;
+    for (const st of STATES) for (const id of lay.board[st]) {
+      if (!keep.has(id)) continue;
+      listed++;
+      items[id] = pageItem(lay.items[id], { stageLabel: (lay.stages.find((s) => s.id === lay.items[id].stage) || {}).label || lay.items[id].stage, factory: factoryView(entry, lay.items[id]) });
+      board[st].push(id);
+    }
+    const doneAll = [...keep].filter((id) => lay.items[id].state === 'done').length;
+    board.doneOlder += doneAll - lay.board.done.filter((id) => keep.has(id)).length;
+    initiatives.push({
+      id: row.id, title: row.title, lane: row.lane, laneLabel: row.laneLabel, horizon: row.horizon, rank: row.rank,
+      stages: lay.stages.map((s) => ({ id: s.id, label: s.label })), batches: pageBatches(lay.batches), shown: listed,
+    });
+  }
+  const counts = { todo: board.todo.length, doing: board.doing.length, review: board.review.length, done: board.done.length, doneOlder: board.doneOlder };
+  const sig = sha1([itemsSig, placeSig, JSON.stringify(join.byInit || {}), String((join.flags || []).length), sideSigAt].join('|'));
+  const granted = releaseGrants(root, now);
+  // the ready batches a person can release: one card each (D86 point 2). Shown under every filter, for a work initiative.
+  const releases = [];
+  for (const row of rows) {
+    if (f.kind === 'init' && row.id !== f.init) continue;
+    const entry = factoryJoin.factoryOf(join, row.id);
+    for (const b of (entry && entry.batches) || []) {
+      if (!b || !b.ready || granted.has(`${row.id}:${b.id}`)) continue;
+      const ws = (b.items || []).map((wid) => {
+        const wi = (entry.items || []).find((x) => x && x.id === wid) || {};
+        const pi = wi.plan_item && items[wi.plan_item];
+        return { id: wid, plan_item: wi.plan_item || null, title: pi ? pi.title : wid, state: wi.state || null, pr: wi.pr || null, integrated: wi.integrated === true };
+      });
+      releases.push({ initiative: row.id, initiativeTitle: row.title, batch: b.id, items: ws });
+    }
+  }
+  return { ok: true, filter: canonical(f), now: new Date(now).toISOString(), sig, initiatives, items, board, counts, releases };
+}
+
+module.exports = { boardFor, sigFor, sideSig, releaseGrants, parseFilter, workInitiatives, factoryView, STATES, NOT_MERGED };

package/workspace/lib/breakdown-export.js

@@ -0,0 +1,75 @@
+'use strict';
+/* breakdown-export.js — an initiative's breakdown as markdown, for a document or a message (pm-os-absorb Run 2, D86
+ * point 4.3, map-spec X7).
+ *
+ *   exportBreakdown(root, id) → { ok: true, id, markdown } | { ok: false, status, error }
+ *
+ * D86 point 4: a project document is an EXPORT of the Breakdown tree, so the document and the board it describes have
+ * one source and cannot disagree. The output is deterministic — the same ledger gives the same bytes, with no clock
+ * and no random part — so two exports can be compared with diff. Stage headers come in the stage order of the
+ * initiative's lane (lib/plan-tree.js), each with "n of m"; under each header the items in tree order, each with its
+ * state, owner, dates and the milestone mark. Proposed items (an agent's batch not kept yet) are listed with
+ * "proposed"; withdrawn items are left out. Items whose stage the lane does not have are listed under "Other".
+ *
+ * Nothing is written: the CLI prints the markdown, the route answers it, and the PM saves it where they choose.
+ * Work lanes only (D86 point 4): a document-lane initiative is a file already, so it is refused with 404.
+ * No heading or label says "plan" (glossary rule `plan`).
+ */
+const fs = require('fs');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const consoleState = require('./console-state');
+
+const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done' };
+const refuse = (status, error) => ({ ok: false, status, error });
+
+function ownerLabel(owner) {
+  const s = String(owner || '');
+  if (s === 'you') return 'you';
+  if (s === 'agent') return 'agent';
+  const m = /^(person|tracker):(.+)$/.exec(s);
+  return m ? m[2] : (s || 'no owner');
+}
+
+function itemLine(it) {
+  const bits = [STATE_LABEL[it.state] || it.state, ownerLabel(it.owner)];
+  if (it.start && it.due) bits.push(`${it.start} → ${it.due}`);
+  else if (it.due) bits.push(`due ${it.due}`);
+  else if (it.start) bits.push(`from ${it.start}`);
+  if (it.milestone) bits.push('milestone');
+  if (it.blocked) bits.push(`blocked: ${String(it.blocked.reason || '').replace(/\s+/g, ' ').trim()}`);
+  if (it.proposed) bits.push('proposed');
+  return `- [${it.state === 'done' ? 'x' : ' '}] ${it.title.replace(/\s+/g, ' ').trim()} · ${bits.join(' · ')}`;
+}
+
+function exportBreakdown(root, id) {
+  if (typeof id !== 'string' || !planTree.INIT_RE.test(id)) return refuse(400, 'an initiative id is required');
+  const file = planTree.recordPath(root, id);
+  if (!file) return refuse(404, `no initiative ${id} in this repository`);
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) return refuse(500, loaded.error);
+  let fm = {};
+  try { fm = loaded.engine.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {}; } catch { fm = {}; }
+  if (planTree.profileAndLane(root, id).group !== 'work') {
+    return refuse(404, `${id} is not on a work lane; a document is a file and has no breakdown to export`);
+  }
+  const fold = planItems.readFold(root, { now: 0 });
+  const lay = planTree.layout({ root, initiative: id, fold, ladder: null, now: 0 });
+  const title = String(fm.title || id).replace(/\s+/g, ' ').trim();
+  const out = [`# ${title}`, '', `Initiative \`${id}\` · ${lay.lane} lane · anchor ${String(fm.parent_kr || 'none').trim()} · ${lay.progress.label}`, ''];
+  const section = (heading, ids) => {
+    out.push(heading, '');
+    if (!ids.length) out.push('No items.');
+    for (const itemId of ids) out.push(itemLine(lay.items[itemId]));
+    out.push('');
+  };
+  for (const st of lay.stages) {
+    if (!st.items.length) continue;
+    section(`## ${st.label}${st.count ? ` · ${st.count}` : ''}`, st.items);
+  }
+  if (lay.other.items.length) section('## Other', lay.other.items);
+  if (!lay.stages.some((s) => s.items.length) && !lay.other.items.length) out.push('No breakdown yet.', '');
+  return { ok: true, id, markdown: out.join('\n') };
+}
+
+module.exports = { exportBreakdown, itemLine };

package/workspace/lib/brief.js

@@ -10,12 +10,16 @@
  *   greeting(now, name)                   → the one line Today opens with
  *   localDate(now)                        → YYYY-MM-DD on this machine's clock
  *
+ * Goals (initiative `today-goals`, PRD G3): an item or an event may name one of the day's goals with `goal`. With
+ * `ctx.goalIds` given, a goal that is not in that day's record is refused. An item may say it is a `mention` of the PM
+ * (Slack, Jira, Confluence, mail): a boolean, nothing more.
+ *
  * The bucket is derived: an item under WORTH_ASKING confidence is "worth asking", whatever the session said. The order is
  * fixed and stated: higher confidence first, then PM-owned before agent-owned, then by title.
  */
 const crypto = require('crypto');
 
-const SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+const SOURCES = ['calendar', 'wispr', 'mail', 'slack', 'jira', 'confluence'];
 const ITEM_SOURCES = [...SOURCES, 'derived'];
 const SOURCE_STATES = ['read', 'not-reached', 'off'];
 const OWNERS = ['pm', 'agent'];
@@ -24,6 +28,7 @@ const WORTH_ASKING = 0.5;
 const MAX_ITEMS = 12;
 const MAX_EVENTS = 20;
 const INI_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+const GOAL_RE = /^g-[0-9a-f]{8}$/;
 const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
 
 const pad = (n) => String(n).padStart(2, '0');
@@ -40,6 +45,13 @@ const tooLong = (v, n) => typeof v === 'string' && v.trim().length > n;
 function validateBrief(raw, ctx = {}) {
   const now = ctx.now || Date.now();
   const settings = ctx.settings || {};
+  const goalIds = Array.isArray(ctx.goalIds) ? new Set(ctx.goalIds) : null;
+  const badGoal = (g, at) => {
+    if (g === undefined || g === null) return null;
+    if (typeof g !== 'string' || !GOAL_RE.test(g)) return `${at}: goal is not a goal id`;
+    if (goalIds && !goalIds.has(g)) return `${at}: goal ${g} is not one of the goals for that day`;
+    return null;
+  };
   const on = (src) => !settings.briefSources || settings.briefSources[src] !== false;
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'a brief is a JSON object' };
   const date = raw.date === undefined ? localDate(now) : raw.date;
@@ -68,7 +80,9 @@ function validateBrief(raw, ctx = {}) {
     if (typeof e.start !== 'string' || Number.isNaN(Date.parse(e.start))) return { ok: false, error: `calendar event ${i + 1}: start must be a date and time` };
     if (e.end !== undefined && (typeof e.end !== 'string' || Number.isNaN(Date.parse(e.end)))) return { ok: false, error: `calendar event ${i + 1}: end must be a date and time` };
     if (e.with !== undefined && tooLong(e.with, 120)) return { ok: false, error: `calendar event ${i + 1}: "with" is over 120 characters` };
-    calendar.push({ start: e.start, end: e.end || null, title: clip(e.title, 120), with: e.with ? clip(e.with, 120) : null });
+    const gErr = badGoal(e.goal, `calendar event ${i + 1}`);
+    if (gErr) return { ok: false, error: gErr };
+    calendar.push({ start: e.start, end: e.end || null, title: clip(e.title, 120), with: e.with ? clip(e.with, 120) : null, ...(e.goal ? { goal: e.goal } : {}) });
   }
   calendar.sort((a, b) => Date.parse(a.start) - Date.parse(b.start));
 
@@ -90,11 +104,15 @@ function validateBrief(raw, ctx = {}) {
     if (!EFFORTS.includes(x.effort)) return { ok: false, error: `${at}: effort must be one of ${EFFORTS.join(', ')}` };
     if (typeof x.confidence !== 'number' || !Number.isFinite(x.confidence) || x.confidence < 0 || x.confidence > 1) return { ok: false, error: `${at}: confidence must be a number from 0 to 1` };
     if (x.initiative_id !== undefined && x.initiative_id !== null && (typeof x.initiative_id !== 'string' || !INI_RE.test(x.initiative_id))) return { ok: false, error: `${at}: initiative_id is not an initiative id` };
+    const gErr = badGoal(x.goal, at);
+    if (gErr) return { ok: false, error: gErr };
+    if (x.mention !== undefined && typeof x.mention !== 'boolean') return { ok: false, error: `${at}: mention must be true or false` };
     const title = clip(x.title, 140);
     items.push({
       id: crypto.createHash('sha1').update(`${date}|${x.source}|${title}`).digest('hex').slice(0, 12),
       title, why_now: clip(x.why_now, 240), evidence: clip(x.evidence, 240), source: x.source, initiative_id: x.initiative_id || null,
       owner: x.owner, effort: x.effort, confidence: x.confidence, worth_asking: x.confidence < WORTH_ASKING,
+      ...(x.goal ? { goal: x.goal } : {}), ...(x.mention ? { mention: true } : {}),
     });
   }
   items.sort((a, b) => b.confidence - a.confidence || (a.owner === b.owner ? 0 : a.owner === 'pm' ? -1 : 1) || a.title.localeCompare(b.title));

package/workspace/lib/capture.js

@@ -0,0 +1,98 @@
+'use strict';
+/* capture.js — the ⌘K "Capture as note" writer (pm-os-absorb Run 3, PRD R11 and R16, X16).
+ *
+ *   write(stateDir, { text, actor, now? }) → { ok: true, id, file, path, n, day } | { ok: false, status, error }
+ *   list(stateDir)                         → [{ id, file, n, day, timestamp, by, text }], oldest first
+ *   render({ text, day, n, timestamp, by }) → the file's whole text
+ *
+ * A capture is ONE NOTE FILE, `<state>/requirements/capture-YYYY-MM-DD-<n>.md`, with `<n>` counting from 1 per UTC day.
+ * There is no ledger: the folder is the one the day's live-notes note and the report skill already read, and the next
+ * step (triage, Run 2, slice 2C) reads the notes newer than its last run and files each as a proposal. Capture itself
+ * decides nothing: it keeps the words, which is why it is the row ⌘K always offers (D71).
+ *
+ * The frontmatter is `type: Reference` (`Requirement` is not in scripts/frontmatter_registry.txt, and the Frontmatter
+ * Gate would refuse it), `title`, `timestamp` (ISO UTC), `source: capture` and `by`. `by` comes from the CALL PATH (the
+ * `actor` the route got from pm-guard), never from a field the caller sends. The body is the captured text, unchanged.
+ *
+ * THE FILE IS NEVER OVERWRITTEN. The write is exclusive (`wx`): when two captures race for one number, the loser takes
+ * the next. Nothing is read from outside the folder, and no capture is deleted or edited here.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DIR = 'requirements';
+const FILE_RE = /^capture-(\d{4}-\d{2}-\d{2})-(\d+)\.md$/;
+const MAX_TEXT = 8000;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+
+const refuse = (status, error) => ({ ok: false, status, error });
+
+/** The whole file. Pure, so the test can hold it to the fixture byte for byte. */
+function render({ text, day, n, timestamp, by }) {
+  const body = String(text).replace(/\r\n?/g, '\n').trim();
+  return `---\ntype: Reference\ntitle: "Capture ${day} ${n}"\ntimestamp: ${timestamp}\nsource: capture\nby: ${by}\n---\n\n${body}\n`;
+}
+
+/** The text a capture may carry: a non-empty string of at most MAX_TEXT characters, with no NUL. Null when it passes. */
+function textProblem(text) {
+  if (typeof text !== 'string') return 'The capture needs text.';
+  if (!text.trim()) return 'The capture is empty. Type the idea first.';
+  if (text.length > MAX_TEXT) return `The capture is too long. The limit is ${MAX_TEXT} characters.`;
+  if (text.includes('\u0000')) return 'The capture holds a character that a note cannot keep.';
+  return null;
+}
+
+/** The numbers already taken on `day`, from the file names in the folder. */
+function taken(dir, day) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const f of names) { const m = FILE_RE.exec(f); if (m && m[1] === day) out.push(Number(m[2])); }
+  return out;
+}
+
+function write(stateDir, { text, actor, now } = {}) {
+  if (!stateDir || typeof stateDir !== 'string') return refuse(409, 'This repository has no state folder to keep the capture in.');
+  const bad = textProblem(text);
+  if (bad) return refuse(400, bad);
+  if (!actor || typeof actor.by !== 'string' || !BY_RE.test(actor.by)) return refuse(500, 'capture: the writer needs the actor from the call path.');
+  const at = now instanceof Date && !Number.isNaN(now.getTime()) ? now : new Date();
+  const timestamp = at.toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const day = timestamp.slice(0, 10);
+  const dir = path.join(stateDir, DIR);
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { return refuse(500, 'The capture could not be saved: ' + String((e && e.message) || e).slice(0, 160)); }
+  let n = Math.max(0, ...taken(dir, day)) + 1;
+  for (let tries = 0; tries < 50; tries++, n++) {
+    const file = `capture-${day}-${n}.md`;
+    try {
+      fs.writeFileSync(path.join(dir, file), render({ text, day, n, timestamp, by: actor.by }), { flag: 'wx' });
+      return { ok: true, id: file.replace(/\.md$/, ''), file, path: path.join(dir, file), n, day, timestamp };
+    } catch (e) {
+      if (e && e.code === 'EEXIST') continue;   // another capture took this number first
+      return refuse(500, 'The capture could not be saved: ' + String((e && e.message) || e).slice(0, 160));
+    }
+  }
+  return refuse(500, 'The capture could not be saved: no free number today.');
+}
+
+/** Every capture note in the folder, oldest first. A file that does not parse as a capture is left out, not an error. */
+function list(stateDir) {
+  const dir = path.join(stateDir, DIR);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const rows = [];
+  for (const file of names) {
+    const m = FILE_RE.exec(file);
+    if (!m) continue;
+    let raw = '';
+    try { raw = fs.readFileSync(path.join(dir, file), 'utf8'); } catch { continue; }
+    const f = /^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/.exec(raw);
+    if (!f) continue;
+    const fm = {};
+    for (const line of f[1].split('\n')) { const k = /^([a-z_]+): ?(.*)$/.exec(line); if (k) fm[k[1]] = k[2].replace(/^"(.*)"$/, '$1'); }
+    rows.push({ id: file.replace(/\.md$/, ''), file, day: m[1], n: Number(m[2]), timestamp: fm.timestamp || '', by: fm.by || '', text: f[2].replace(/\n$/, '') });
+  }
+  return rows.sort((a, b) => (a.day === b.day ? a.n - b.n : a.day < b.day ? -1 : 1));
+}
+
+module.exports = { DIR, MAX_TEXT, FILE_RE, render, write, list, textProblem };