create-pmos 0.51.0 → 0.53.0

package/workspace/lib/report-needs.js

@@ -0,0 +1,213 @@
+'use strict';
+/* report-needs.js — the needs-you rows that Reports makes: a report to issue, the monthly kill-condition check, a
+ * schedule that left no output (pm-os-absorb Run 5, slice 5C; PRD R12 kinds 1, 7 and 8, R22.5, R29).
+ *
+ *   kinds · rowsFor(w, { lead }) · sig(w)        the needs-provider contract (lib/needs-providers.js)
+ *   rowsAt(w, { lead, now, schedules })          rowsFor with the clock and the schedules injected, for tests
+ *   reportsOf(root)                              → { ok, reports: [{ cadence, slot, path, status, bytes, mtimeMs, issued, edited }],
+ *                                                    flags, sig }   the report files joined to issues.jsonl; the routes read it too
+ *   cadenceOfSkill(skill)                        'report-biweekly' → 'biweekly', else null
+ *
+ * THE THREE ROW KINDS (rows are held to fixtures/today-api/provider-rows.json):
+ *   report-issue        kind 1. The newest draft of a cadence that the report script wrote, that is not issued, and that is
+ *                       newer than the cadence's last issued slot. Needs `lead`: a report belongs to the repository, not to
+ *                       one working tree. The script's own frontmatter marks its draft (isScriptDraft below): `cadence`,
+ *                       `slot` and `window`. Run 5A's drafter writes no `status` key, because an issued file is frozen byte
+ *                       for byte and a `status: draft` would lie once it is issued; the issues ledger says what is issued.
+ *                       `status: draft` still counts, for a file an earlier drafter wrote. A draft a skill wrote by hand
+ *                       has neither, so it never makes a card; the Reports page still lists it and can issue it (X36).
+ *   cycle-kill-check    kind 7. Once a month, from the 1st: planning/okrs/kill-conditions.md has not been touched this
+ *                       month. The file's own `timestamp` is the record of the check (D64: file mode, "this file").
+ *                       2D draws it with the one kind-7 card; this file supplies the row only.
+ *   schedule-no-output  kind 8. An enabled report schedule fired and no report file for its cadence is newer than the
+ *                       fire, after a grace period for an agent that is still writing.
+ *
+ * A SCHEDULE JOINS ITS REPORT BY ITS `skill` FIELD, NEVER BY ITS `cadence`. The schedule's cadence is how often it runs
+ * ('bi-weekly'); the report's cadence is the skill id's suffix ('report-biweekly' → 'biweekly'). The two spellings
+ * differ, and a schedule whose cadence says weekly may feed the monthly report.
+ *
+ * Local files only (D70): the repository's report folders and ledger, and the schedules store the app already reads.
+ * Nothing here calls out, and nothing here writes. Every read answers; a ledger that cannot be read throws, which
+ * needs-providers turns into one row that names it, never an empty list (R10).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const issues = require('./issues.js');
+const ledgers = require('./plan-ledgers.js');
+const stateRoot = require('./state-root.js');
+
+const kinds = ['report-issue', 'cycle-kill-check', 'schedule-no-output'];
+const KILL_FILE = 'planning/okrs/kill-conditions.md';
+const SLOT_FILE = /^(\d{4}-\d{2}-\d{2})\.md$/;
+const CADENCE_DIR = /^[a-z][a-z0-9-]{0,39}$/;
+const GRACE_MS = 2 * 3600 * 1000;       // an agent report session needs time to write its draft
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * The one folder this repository keeps its report files in: `pmos/state/reports` in a kit repository, `planning/reports` in
+ * PMOS-self. It is the folder report-draft.js writes to, and the only path the issues writer accepts, so a file in the other
+ * folder is not listed: it would offer Issue and every press would be refused.
+ */
+function reportsDir(root) {
+  try { return /[\\/]pmos[\\/]state$/.test(ledgers.runsDir(path.resolve(String(root)))) ? 'pmos/state/reports' : 'planning/reports'; } catch { return 'planning/reports'; }
+}
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const short = (ymd) => { const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(ymd || '')); return m ? `${Number(m[3])} ${MONTHS[Number(m[2]) - 1]}` : String(ymd || ''); };
+const cadenceOfSkill = (skill) => { const m = /^report-([a-z][a-z0-9-]{0,39})$/.exec(String(skill || '')); return m ? m[1] : null; };
+/** What `git hash-object` prints for these bytes, without running git: the sha issues.jsonl records. */
+const blobSha = (buf) => crypto.createHash('sha1').update(`blob ${buf.length}\0`).update(buf).digest('hex');
+
+/** The first frontmatter block of a file, as { key: value }. Only the leading 4 KB are read. */
+function frontmatter(file) {
+  let head = '';
+  try {
+    const fd = fs.openSync(file, 'r');
+    try { const b = Buffer.alloc(4096); head = b.toString('utf8', 0, fs.readSync(fd, b, 0, 4096, 0)); } finally { fs.closeSync(fd); }
+  } catch { return {}; }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(head);
+  const out = {};
+  if (!m) return out;
+  for (const line of m[1].split(/\r?\n/)) { const kv = /^([A-Za-z_][\w-]*):\s*(.*?)\s*$/.exec(line); if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, ''); }
+  return out;
+}
+
+/** The report script's own mark: its frontmatter names the cadence, the slot and the window. `status: draft` is the older mark. */
+const isScriptDraft = (fm) => fm.status === 'draft' || !!(fm.cadence && fm.slot && fm.window);
+
+/* ── the report files, joined to the issues ledger ─────────────────────────────────────────────────────────────────── */
+
+function reportsOf(root) {
+  const abs = path.resolve(String(root));
+  const out = { ok: true, reports: [], flags: [], sig: '' };
+  // The signature is taken BEFORE the ledger is read (F2): a line appended in between shows on the next read.
+  const ledgerSig = ledgers.ledgerSig(abs, 'issues');
+  let iss;
+  try { iss = issues.readIssues(abs); } catch (e) { iss = { ok: false, issues: [], flags: [{ kind: 'unreadable', eid: null, why: String((e && e.message) || e).slice(0, 160) }] }; }
+  out.flags = Array.isArray(iss.flags) ? iss.flags.slice() : [];
+  const issuedOf = new Map((iss.issues || []).map((i) => [`${i.cadence}\u0000${i.slot}`, i]));
+  const rel = reportsDir(abs);
+  const base = path.join(abs, rel);
+  if (isDir(base)) {
+    let cadences = [];
+    try { cadences = fs.readdirSync(base); } catch { cadences = []; }
+    for (const cadence of cadences.sort()) {
+      if (!CADENCE_DIR.test(cadence) || cadence === 'definitions' || !isDir(path.join(base, cadence))) continue;
+      let files = [];
+      try { files = fs.readdirSync(path.join(base, cadence)); } catch { files = []; }
+      for (const f of files.sort()) {
+        const m = SLOT_FILE.exec(f);
+        if (!m) continue;
+        const file = path.join(base, cadence, f);
+        let st; try { st = fs.statSync(file); } catch { continue; }
+        if (!st.isFile()) continue;
+        const slot = m[1];
+        const hit = issuedOf.get(`${cadence}\u0000${slot}`) || null;
+        let edited = false;
+        if (hit && hit.sha) { try { edited = blobSha(fs.readFileSync(file)) !== hit.sha; } catch { edited = false; } }
+        out.reports.push({
+          cadence, slot, path: `${rel}/${cadence}/${f}`, status: isScriptDraft(frontmatter(file)) ? 'draft' : null,
+          bytes: st.size, mtimeMs: st.mtimeMs, issued: hit ? { at: hit.at, by: hit.by, via: hit.via, sha: hit.sha, path: hit.path } : null, edited,
+        });
+      }
+    }
+  }
+  out.reports.sort((a, b) => (a.slot < b.slot ? 1 : a.slot > b.slot ? -1 : a.cadence < b.cadence ? -1 : a.cadence > b.cadence ? 1 : 0));
+  out.sig = crypto.createHash('sha1').update(ledgerSig + '|' + out.reports.map((r) => `${r.path}:${r.bytes}:${r.mtimeMs}`).join(',')).digest('hex');
+  return out;
+}
+
+/* ── the schedules store ───────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The app's own schedules.json, read-only: the per-user state root, else the legacy workspace/state (as server.js does). */
+function schedulesFile() {
+  const here = path.join(stateRoot.defaultRoot({ env: process.env }), 'schedules.json');
+  if (fs.existsSync(here)) return here;
+  const legacy = path.join(__dirname, '..', 'state', 'schedules.json');
+  return fs.existsSync(legacy) ? legacy : here;
+}
+function readSchedules() {
+  try { const a = JSON.parse(fs.readFileSync(schedulesFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
+}
+const schedulesStamp = () => { try { const st = fs.statSync(schedulesFile()); return `${st.size}:${st.mtimeMs}`; } catch { return 'none'; } };
+
+/* ── the rows ──────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const row = (run_id, kind, question, today) => ({ run_id, initiative_id: null, kind, question, doc: null, today: { source: 'report-needs', ...today } });
+
+function issueRows(root) {
+  const r = reportsOf(root);
+  const unreadable = r.flags.find((f) => f.kind === 'unreadable' && /^line 0:/.test(f.why));
+  if (unreadable) throw new Error('the issues ledger cannot be read: ' + unreadable.why);
+  const lastSlot = {};
+  for (const x of r.reports) if (x.issued && (!lastSlot[x.cadence] || x.slot > lastSlot[x.cadence])) lastSlot[x.cadence] = x.slot;
+  const seen = new Set();
+  const out = [];
+  for (const x of r.reports) {            // newest slot first
+    if (seen.has(x.cadence)) continue;
+    if (x.status !== 'draft' || x.issued || (lastSlot[x.cadence] && x.slot <= lastSlot[x.cadence])) continue;
+    seen.add(x.cadence);
+    out.push(row(`report-needs:issue:${x.cadence}:${x.slot}`, 'report-issue', `The ${x.cadence} of ${short(x.slot)} is ready to issue`,
+      { kind: 1, cause: 'A draft is ready to issue', evidence: x.path, act: { label: 'Issue', cli: `pmos report issue ${x.cadence} ${x.slot}` } }));
+  }
+  return out;
+}
+
+function killRow(root, now) {
+  const file = path.join(path.resolve(String(root)), KILL_FILE);
+  if (!fs.existsSync(file)) return [];
+  const month = new Date(now).toISOString().slice(0, 7);
+  const stamp = String(frontmatter(file).timestamp || '').slice(0, 10);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(stamp) && stamp.slice(0, 7) >= month) return [];     // touched this month: the check is recorded
+  return [row(`report-needs:cycle:kill-check:${month}`, 'cycle-kill-check', `The kill-condition check for ${month} is due`,
+    { kind: 7, cause: 'The month ended', evidence: KILL_FILE, act: { label: 'Review', cli: null } })];
+}
+
+/** The newest modification time of any report file of `cadence`, or 0. */
+function newestOutput(root, cadence) {
+  return reportsOf(root).reports.filter((x) => x.cadence === cadence).reduce((m, x) => Math.max(m, x.mtimeMs), 0);
+}
+
+function noOutputRows(w, now, schedules) {
+  const out = [];
+  const seen = new Set();
+  for (const s of schedules) {
+    const cadence = cadenceOfSkill(s && s.skill);
+    if (!cadence || s.ws !== w.id || s.enabled === false || !s.lastRun) continue;
+    const fired = Date.parse(s.lastRun);
+    if (!Number.isFinite(fired)) continue;
+    const failed = s.lastStatus === 'fail';
+    if (!failed && now - fired < GRACE_MS) continue;
+    if (newestOutput(w.root, cadence) + 1000 >= fired) continue;
+    const day = new Date(fired).toISOString().slice(0, 10);
+    const id = `report-needs:no-output:${cadence}:${day}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const dir = reportsDir(w.root);
+    out.push(row(id, 'schedule-no-output', `The ${cadence} schedule ran on ${short(day)} and left no report`,
+      { kind: 8, cause: `No draft for the slot of ${short(day)}`, evidence: `${dir}/${cadence}`, act: { label: 'Draft now', cli: `pmos report draft ${cadence}` } }));
+  }
+  return out;
+}
+
+function rowsAt(w, { lead = true, now = Date.now(), schedules } = {}) {
+  if (!w || !w.root) return [];
+  const rows = [];
+  if (lead) { rows.push(...issueRows(w.root)); rows.push(...killRow(w.root, now)); }
+  rows.push(...noOutputRows(w, now, Array.isArray(schedules) ? schedules : readSchedules()));
+  return rows;
+}
+
+const rowsFor = (w, { lead } = {}) => rowsAt(w, { lead: !!lead });
+
+/** Everything the rows read, so /api/needs is never stale: the issues ledger, the report files, the schedules, the kill-condition file and the hour. */
+function sig(w) {
+  if (!w || !w.root) return '';
+  const hour = Math.floor(Date.now() / 3600000);
+  let kill = 'none';
+  try { const st = fs.statSync(path.join(path.resolve(String(w.root)), KILL_FILE)); kill = `${st.size}:${st.mtimeMs}`; } catch { /* no file, no row */ }
+  return [reportsOf(w.root).sig, schedulesStamp(), kill, hour].join(':');
+}
+
+module.exports = { kinds, rowsFor, sig, rowsAt, reportsOf, cadenceOfSkill, blobSha, reportsDir, KILL_FILE, GRACE_MS };

package/workspace/lib/route-modules.js

@@ -0,0 +1,128 @@
+'use strict';
+/* route-modules.js — where the planning layer's HTTP routes plug into server.js (pm-os-absorb Runs 2 to 5).
+ *
+ *   dispatch(req, res, url, ctx) → Promise<boolean>   true when a module answered the request
+ *   MODULES · status() · ownerOf(pathname)
+ *
+ * server.js answers requests with one long if-chain. Four runs adding blocks to it at once would collide on the same
+ * lines, so each run's routes live in ONE file of their own, workspace/lib/routes-<name>.js, named in MODULES below
+ * before it exists. server.js calls dispatch() once, as the last step before its 404, so a module can never shadow a
+ * route above it.
+ *
+ * A ROUTE MODULE exports:
+ *   module.exports = {
+ *     prefixes: ['/api/initiatives', '/api/placements'],      // paths it owns: the prefix itself or prefix + '/…'
+ *     handle: async (req, res, url, ctx) => boolean,          // true when it wrote the response
+ *   };
+ * `ctx` is what server.js hands over, plus `readJson`:
+ *   { json(res, obj, code), readBody(req), readJson(req) → { ok, body } | { ok: false },
+ *     getWs(id), invalidateNeedsAgg(id), boardCache, consoleState, stateDirFor(w), sessionList() }
+ * A module needs nothing else from server.js; it requires the lib/ modules it uses itself (spelled with `.js` when the
+ * module is a ledger writer, so scripts/check-separation.js lists the caller).
+ *
+ * A module file that is not on disk yet is skipped. One that fails to load, or claims a prefix another module claims,
+ * answers its prefixes with 500 and says why: a broken module must not read as a missing route.
+ *
+ * Built in: GET /api/pm-modules?want=a.js,b.js → { ok, present: [...], grantScopes: [...] }, which of the named public/pm modules exist,
+ * so public/pm/registry.js imports only those (a missing optional module then costs no 404 in the console).
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MODULES = Object.freeze([
+  'routes-initiatives',   // Run 2 (2C): Roadmap, List, placements, new initiative, measurements
+  'routes-today',         // Run 3 (3B): GET /api/today
+  'routes-capture',       // Run 3 (3C): ⌘K capture
+  'routes-timeline',      // Run 4 (4C): GET /api/timeline
+  'routes-board',         // Run 4 (4D): the cross-initiative Board, Release
+  'routes-reports',       // Run 5 (5C): drafts, Issue, notes
+]);
+const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
+const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;
+
+let table = null;   // { owners: [{ prefix, name }], broken: { [name]: error }, loaded: [name] }
+function load() {
+  if (table) return table;
+  const owners = [];
+  const broken = {};
+  const loaded = [];
+  const mods = {};
+  for (const name of MODULES) {
+    const full = path.join(__dirname, name + '.js');
+    let mod;
+    try { mod = require(full); }
+    catch (e) {
+      if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(full)) continue;   // not built yet
+      broken[name] = `${name}.js failed to load: ${String((e && e.message) || e).slice(0, 200)}`;
+      continue;
+    }
+    const prefixes = mod && Array.isArray(mod.prefixes) ? mod.prefixes.filter((x) => typeof x === 'string' && /^\/api\/[a-z0-9/-]+[a-z0-9]$/.test(x)) : [];
+    if (!mod || typeof mod.handle !== 'function' || !prefixes.length || prefixes.length !== mod.prefixes.length) {
+      broken[name] = `${name}.js must export prefixes (each "/api/…") and a handle function`;
+      continue;
+    }
+    mods[name] = mod;
+    loaded.push(name);
+    for (const prefix of prefixes) owners.push({ prefix, name });
+  }
+  owners.push({ prefix: '/api/pm-modules', name: '(built in)' });
+  for (const o of owners) {
+    const twin = owners.find((x) => x !== o && x.prefix === o.prefix);
+    if (twin) broken[o.name] = `${o.prefix} is claimed by both ${o.name} and ${twin.name}`;
+  }
+  table = { owners, broken, loaded, mods };
+  return table;
+}
+
+/** The module that owns `pathname`: the longest prefix it equals or begins with, on a segment boundary. */
+function ownerOf(pathname) {
+  let best = null;
+  for (const o of load().owners) {
+    if (pathname !== o.prefix && !pathname.startsWith(o.prefix + '/')) continue;
+    if (!best || o.prefix.length > best.prefix.length) best = o;
+  }
+  return best;
+}
+
+function status() {
+  const t = load();
+  return { loaded: t.loaded.slice(), broken: { ...t.broken }, prefixes: t.owners.map((o) => ({ ...o })) };
+}
+
+function pmModules(url) {
+  const want = String(url.searchParams.get('want') || '').split(',').map((s) => s.trim()).filter(Boolean).slice(0, 40);
+  const present = [];
+  for (const name of want) {
+    if (!MODULE_NAME.test(name)) continue;
+    try { if (fs.statSync(path.join(PM_DIR, name)).isFile()) present.push(name); } catch { /* absent */ }
+  }
+  // grantScopes: the D81 scopes a press can mint now (lib/grant-mint.js mintableScopes; [] until Run 2's 2B).
+  let grantScopes = [];
+  try { grantScopes = require('./grant-mint.js').mintableScopes(); } catch { /* none */ }
+  return { ok: true, present, grantScopes };
+}
+
+async function dispatch(req, res, url, ctx) {
+  const p = url.pathname;
+  if (!p.startsWith('/api/')) return false;
+  const owner = ownerOf(p);
+  if (!owner) return false;
+  const t = load();
+  if (t.broken[owner.name]) { ctx.json(res, { ok: false, error: t.broken[owner.name] }, 500); return true; }
+  if (owner.name === '(built in)') {
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    ctx.json(res, pmModules(url));
+    return true;
+  }
+  const readJson = async (r) => {
+    try { return { ok: true, body: JSON.parse((await ctx.readBody(r)) || '{}') }; } catch { return { ok: false }; }
+  };
+  try { return (await t.mods[owner.name].handle(req, res, url, { ...ctx, readJson })) === true; }
+  catch (e) {
+    if (res.headersSent) { try { res.end(); } catch { /* already closed */ } return true; }
+    ctx.json(res, { ok: false, error: `${owner.name} failed: ${String((e && e.message) || e).slice(0, 200)}` }, 500);
+    return true;
+  }
+}
+
+module.exports = { MODULES, dispatch, ownerOf, status };

package/workspace/lib/routes-board.js

@@ -0,0 +1,91 @@
+'use strict';
+/* routes-board.js — the Board destination's two routes (pm-os-absorb Run 4, slice 4D; PRD R9, R19, R12 kind 4, R25).
+ *
+ *   GET  /api/board?ws=<id>&filter=active|mine|init:<initiative>
+ *        → { ok, ws, filter, now, sig, initiatives, items, board, counts, releases }  lib/board-fold.js, one fold for all
+ *   GET  /api/board?ws=<id>&only=sig   → { ok, ws, sig }   the hash alone, which the page's watcher reads
+ *   POST /api/board/release   { ws, initiative, batch }
+ *        → { ok: true, grant_id, scope, target, items }   or the refusal of the guard, the batch check or the grant mint
+ *
+ * THE PAGE WATCHES `sig` (public/pm/sig-watch.js watchSig): it is a hash of the plan-items and placements ledgers and of
+ * the factory join, taken before they are read (lib/board-fold.js). Nothing is cached (D33).
+ *
+ * RELEASE IS A PM-ONLY ACT (R25, D86 point 2). `requirePmPress` runs first, with act `release`, so a press with no
+ * Origin, a foreign Origin, a missing nonce or a writer field in the body is refused before the batch is looked at. The
+ * batch must exist in the factory join (lib/factory-join.js) and be ready: every item passed its checks. ONE grant covers
+ * the whole batch: lib/grant-mint.js mintFromPress mints a `release` grant with target `<initiative>:<batch id>`, and the
+ * route never writes grants.jsonl itself. Until Run 2 fills the mint, its 501 is passed through unchanged, and the page
+ * says "arrives in Run 2" from /api/pm-modules grantScopes before the press. The factory stays propose-only: this route
+ * grants the PM's permission; it merges and pushes nothing. A batch that already holds a release grant (unexpired, or used)
+ * is 409 "already released" with that grant's id, and the Board and Today list no card for it: one batch, one grant.
+ */
+const guard = require('./pm-guard.js');
+const grantMint = require('./grant-mint.js');
+const factoryJoin = require('./factory-join.js');
+const planItems = require('./plan-items.js');
+const boardFold = require('./board-fold.js');
+
+const BATCH_RE = /^[A-Za-z0-9][\w.-]{0,79}$/;
+const text = (v) => (typeof v === 'string' ? v : '');
+
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || '');
+  return w && (!id || w.id === id) ? w : null;
+}
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  if (p === '/api/board') {
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    if (url.searchParams.get('only') === 'sig') {
+      // the page's watcher reads this every 10 seconds: the hash alone, with no item read
+      try { ctx.json(res, { ok: true, ws: w.id, sig: boardFold.sigFor({ id: w.id, root: w.root }) }); }
+      catch (e) { ctx.json(res, { ok: false, error: 'the Board could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }, 500); }
+      return true;
+    }
+    let out;
+    try { out = boardFold.boardFor({ id: w.id, root: w.root }, { filter: url.searchParams.get('filter') || 'active' }); }
+    catch (e) { ctx.json(res, { ok: false, error: 'the Board could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }, 500); return true; }
+    if (!out.ok) { ctx.json(res, { ok: false, error: out.error }, out.status || 400); return true; }
+    ctx.json(res, { ...out, ws: w.id });
+    return true;
+  }
+  if (p === '/api/board/release') {
+    if (req.method !== 'POST') { ctx.json(res, { ok: false, error: 'POST only' }, 405); return true; }
+    const read = await ctx.readJson(req);
+    if (!read.ok) { ctx.json(res, { ok: false, error: 'the body is not JSON' }, 400); return true; }
+    const body = read.body;
+    const g = guard.requirePmPress(req, body, { act: 'release' });
+    if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+    const w = wsOf(ctx, text(body.ws));
+    if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    const initiative = text(body.initiative);
+    const batchId = text(body.batch);
+    if (!planItems.INIT_RE.test(initiative) || !BATCH_RE.test(batchId)) { ctx.json(res, { ok: false, error: 'initiative and batch are required' }, 400); return true; }
+    let works;
+    try { works = boardFold.workInitiatives(w.root); } catch (e) { ctx.json(res, { ok: false, error: 'the initiatives could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }, 500); return true; }
+    if (!works.some((i) => i.id === initiative)) { ctx.json(res, { ok: false, error: `no initiative ${initiative} on the Board` }, 404); return true; }
+    const join = factoryJoin.joinFactory(w.root, { initiative });
+    const entry = factoryJoin.factoryOf(join, initiative);
+    const batch = entry && (entry.batches || []).find((b) => b && b.id === batchId);
+    if (!batch) { ctx.json(res, { ok: false, error: `${initiative} has no batch ${batchId} to release` }, 404); return true; }
+    if (!batch.ready) { ctx.json(res, { ok: false, error: `batch ${batchId} is not ready: an item has not passed its checks` }, 409); return true; }
+    // ONE release grant covers a batch (D86 point 2): a batch that holds a grant is not minted again
+    const held = boardFold.releaseGrants(w.root).get(`${initiative}:${batchId}`);
+    if (held) { ctx.json(res, { ok: false, error: `batch ${batchId} is already released`, grant_id: held.grant_id, scope: 'release', target: `${initiative}:${batchId}` }, 409); return true; }
+    const n = (batch.items || []).length;
+    const r = grantMint.mintFromPress(w.root, {
+      scope: 'release', target: `${initiative}:${batchId}`, initiative,
+      instruction: `Release ${n === 1 ? '1 work item' : n + ' work items'} of ${initiative}, batch ${batchId}`,
+    }, { actor: g.actor });
+    if (!r.ok) { ctx.json(res, { ok: false, error: r.error, scope: 'release', target: `${initiative}:${batchId}` }, r.status || 500); return true; }
+    ctx.invalidateNeedsAgg(w.id);
+    ctx.json(res, { ok: true, grant_id: r.grant_id, scope: r.scope, target: r.target, items: n });
+    return true;
+  }
+  return false;
+}
+
+module.exports = { prefixes: ['/api/board'], handle };

package/workspace/lib/routes-capture.js

@@ -0,0 +1,52 @@
+'use strict';
+/* routes-capture.js — POST /api/capture, the ⌘K "Capture as note" press (pm-os-absorb Run 3, slice 3C; lib/route-modules.js).
+ *
+ *   POST /api/capture   { ws, text }   →   { ok: true, id, file, written: 1 }
+ *
+ * `id` is `capture-YYYY-MM-DD-<n>` and `file` is `requirements/<id>.md`, relative to the repository's state folder; the
+ * answer never carries an absolute path. A write that is not a PM-only act goes through pm-guard `requirePagePress`
+ * (a body that is not an object or carries a writer field: 400; no Origin, a foreign Origin or a wrong nonce: 403), and
+ * the note's `by` comes from the actor that call returns, never from the body (lib/capture.js).
+ *
+ * The state folder is the one Run 2's triage reads: the folder that holds the initiatives' folder in the workflow engine's
+ * layout (`pmos/state/` in a kit repository, else `planning/`; none is made). It is NOT server.js `stateDirFor`, which also
+ * picks `state/` and `.pmos/` and would file a note where triage never looks. A body with no `ws` is 400 and a `ws` the server
+ * does not know is 404, so a capture is never filed in another repository.
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+const capture = require('./capture.js');
+
+const prefixes = ['/api/capture'];
+
+/** The folder that holds the initiatives' folder (the layout rule triage.js `stateDir` uses); the same rule by hand when the engine is absent. */
+function captureStateDir(ctx, root) {
+  try {
+    const loaded = ctx.consoleState && ctx.consoleState.loadEngine();
+    if (loaded && loaded.ok) return path.dirname(loaded.engine.layout(root).initiatives);
+  } catch { /* fall through to the same rule by hand */ }
+  const kit = !fs.existsSync(path.join(root, 'planning', 'initiatives')) && fs.existsSync(path.join(root, 'pmos', 'state', 'initiatives'));
+  return kit ? path.join(root, 'pmos', 'state') : path.join(root, 'planning');
+}
+
+async function handle(req, res, url, ctx) {
+  if (url.pathname !== '/api/capture') return false;
+  if (req.method !== 'POST') { ctx.json(res, { ok: false, error: 'POST only' }, 405); return true; }
+  const parsed = await ctx.readJson(req);
+  if (!parsed.ok) { ctx.json(res, { ok: false, error: 'The body is not valid JSON.' }, 400); return true; }
+  const body = parsed.body;
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+  const wsId = body && typeof body.ws === 'string' ? body.ws : '';
+  if (!wsId) { ctx.json(res, { ok: false, error: 'Select a repository first. A note is kept in one repository.' }, 400); return true; }
+  const w = ctx.getWs(wsId);
+  if (!w || w.id !== wsId) { ctx.json(res, { ok: false, error: 'This repository is not registered.' }, 404); return true; }
+  const stateDir = captureStateDir(ctx, w.root);
+  const r = capture.write(stateDir, { text: body.text, actor: g.actor });
+  if (!r.ok) { ctx.json(res, { ok: false, error: r.error }, r.status); return true; }
+  ctx.json(res, { ok: true, id: r.id, file: `${capture.DIR}/${r.file}`, written: 1 });
+  return true;
+}
+
+module.exports = { prefixes, handle };