create-pmos 0.51.0 → 0.53.0

package/workspace/lib/initiative-rows.js

@@ -0,0 +1,206 @@
+'use strict';
+/* initiative-rows.js — the workflow rows of every initiative record, and what each anchor names (pm-os-absorb Run 2,
+ * slice 2C: the Initiatives API, `pmos initiative` and initiative-needs read them from here).
+ *
+ *   deriveSync(root)          → { ok, rows } | { ok: false, error }     every record, derived now (the CLI, the tests)
+ *   rowsFor(root)             → { pending: true } | { ok, rows, sig, as_of, stale } | { ok: false, error }
+ *                               the request path: never derives in the server process (see below)
+ *   peek(root)                → the same answer from the cache alone; it never starts a derivation. The needs provider
+ *                               reads this, so the Today poll never pays for a derivation: only a read of the
+ *                               Initiatives API (rowsFor) starts one.
+ *   answerSig(r)              → the records part of a GET's sig, from the answer used (a stale answer is marked)
+ *   cachedSig(root)           → the cache entry as a string; it changes each time a derivation lands
+ *   recordsSig(root)          → sha1 of lib/board-cache.js signature (HEAD, the records, lifecycle and acceptances)
+ *   anchorsOf(root)           → { resolve(raw) → anchor info, period, error }
+ *   workGroupOf(root)         → { [lane]: group }    from scripts/lane-defs.js through the engine (never a list here)
+ *
+ * A ROW is one line of `node scripts/workflow-state.js --json` (every record, uncapped), narrowed to what the planning
+ * layer reads: { ok, id, title, lane, group, anchor, stage, accepted, stopped, last_activity (ISO), profile, record,
+ * next }. `stopped` is the lifecycle fold ({ state, reason, at }) or null.
+ *
+ * WHY A CHILD PROCESS. The engine resolves each artifact's first appearance by running git: about 260 ms per record,
+ * so a repository of 100 records takes half a minute (lib/board-cache.js measured it). The board cache is capped at
+ * the in-flight rows and has no last activity, so it cannot answer the Roadmap. rowsFor() runs the engine's own CLI in
+ * a child, keyed by the board cache's signature, and answers `pending` until the first derivation lands, like the
+ * board cache does. The CLI and the tests call deriveSync(), the same command, synchronously.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn, execFileSync } = require('child_process');
+const consoleState = require('./console-state');
+const boardCache = require('./board-cache');
+
+const MAX_AGE_MS = 10 * 60 * 1000;
+const TIMEOUT_MS = 180000;
+const cache = new Map();     // root -> { sig, at, value, error }
+const inflight = new Map();  // root -> true
+let background = true;       // false in a one-shot process (`pmos today` with no server): nothing would read the answer
+
+function enginePath() {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded;
+}
+
+/** { [lane]: 'work' | 'document' | … } for the repository's profile. */
+function workGroupOf(root) {
+  const { engine } = enginePath();
+  const { defs } = engine.lanesFor(root);
+  const out = {};
+  for (const [lane, d] of Object.entries(defs || {})) out[lane] = (d && d.group) || null;
+  return out;
+}
+
+const iso = (v) => {
+  if (typeof v === 'number' && Number.isFinite(v)) return new Date(v < 1e11 ? v * 1000 : v).toISOString();
+  const t = Date.parse(String(v || ''));
+  return Number.isFinite(t) ? new Date(t).toISOString() : null;
+};
+
+/** The engine's JSON rows → the narrowed rows, each with its lane group. */
+function narrow(root, raw) {
+  let groups = {};
+  try { groups = workGroupOf(root); } catch { groups = {}; }
+  return (Array.isArray(raw) ? raw : []).map((r) => (r && r.ok !== false ? {
+    ok: true, id: r.id, title: r.title || r.id, lane: r.lane, group: groups[r.lane] || null, anchor: r.anchor || null,
+    stage: r.stage || null, accepted: !!r.accepted,
+    stopped: r.stopped ? { state: r.stopped.state, reason: r.stopped.reason || '', at: r.stopped.at || null } : null,
+    last_activity: iso(r.last_activity), profile: r.profile || null, record: r.record || null, next: r.next || null,
+  } : { ok: false, id: r && r.id, error: (r && r.error) || 'the row could not be derived' }));
+}
+
+function deriveSync(root) {
+  try {
+    const { from } = enginePath();
+    const out = execFileSync(process.execPath, [from, '--json', '--root', root], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], timeout: TIMEOUT_MS });
+    return { ok: true, rows: narrow(root, JSON.parse(out || '[]')) };
+  } catch (e) {
+    return { ok: false, error: 'the initiative records could not be read: ' + String((e && e.message) || e).slice(0, 160) };
+  }
+}
+
+const sha1 = (s) => crypto.createHash('sha1').update(String(s)).digest('hex');
+function recordsSig(root) {
+  try { return sha1(boardCache.signature(root)); } catch { return sha1('unreadable'); }
+}
+
+function refresh(root, sig) {
+  if (inflight.get(root)) return;
+  inflight.set(root, true);
+  let child;
+  let out = '';
+  const done = (entry) => {
+    inflight.delete(root);
+    // a failed re-derivation keeps the last good answer (it is stale, so the next read tries again): rows read from it
+    // must not vanish from Today for one poll and come back on the next
+    const prev = cache.get(root);
+    if (entry.error && prev && prev.value) return;
+    cache.set(root, { sig, at: Date.now(), ...entry });
+  };
+  try {
+    const { from } = enginePath();
+    child = spawn(process.execPath, [from, '--json', '--root', root], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (e) { done({ value: null, error: 'could not start reading the initiative records: ' + String((e && e.message) || e).slice(0, 120) }); return; }
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, TIMEOUT_MS);
+  if (timer.unref) timer.unref();
+  // the child never holds its parent open: `pmos today` reads the cache and exits, whatever is still being derived
+  try { child.unref(); if (child.stdout && child.stdout.unref) child.stdout.unref(); } catch { /* still runs */ }
+  child.stdout.on('data', (c) => { out += c; });
+  child.on('error', (e) => { clearTimeout(timer); done({ value: null, error: 'reading the initiative records failed: ' + (e.code || e.message) }); });
+  child.on('close', (code) => {
+    clearTimeout(timer);
+    if (code !== 0 && !out) { done({ value: null, error: 'reading the initiative records stopped without a result' }); return; }
+    try { done({ value: narrow(root, JSON.parse(out || '[]')), error: null }); }
+    catch { done({ value: null, error: 'the initiative records came back unreadable' }); }
+  });
+}
+
+/** The request path's read. Always returns at once; see the header. */
+function rowsFor(root) { return read(root, true); }
+/** Whether a read may start a background derivation. `pmos today` without a server turns it off: the process exits
+ *  before the child would land, so the child is pure cost. Returns the previous setting. */
+function setBackground(on) { const was = background; background = !!on; return was; }
+/** Whether a background derivation of `root` is running now. */
+function isDeriving(root) { return !!inflight.get(root); }
+/** Derive `root` now, synchronously, into the cache (`pmos today --wait`): about 260 ms per record. */
+function deriveNow(root) {
+  const sig = recordsSig(root);
+  const d = deriveSync(root);
+  cache.set(root, { sig, at: Date.now(), value: d.ok ? d.rows : null, error: d.ok ? null : d.error });
+  return d;
+}
+/** The same answer from the cache alone: it never starts a derivation (the needs provider; see peek in the header). */
+function peek(root) { return read(root, false); }
+function read(root, derive) {
+  const sig = recordsSig(root);
+  const hit = cache.get(root);
+  const fresh = hit && hit.sig === sig && Date.now() - hit.at < MAX_AGE_MS;
+  if (!fresh && derive && background) refresh(root, sig);
+  if (!hit) return { pending: true };
+  if (hit.error) return { ok: false, error: hit.error };
+  return { ok: true, rows: hit.value, sig: hit.sig, as_of: new Date(hit.at).toISOString(), stale: !fresh };
+}
+/** The records part of a GET's `sig`, from the answer actually used: a stale answer reads differently from the fresh
+ *  one that replaces it, so a poll sees the derivation land even when the records did not change again. */
+function answerSig(r) {
+  if (!r || r.pending) return 'pending';
+  if (!r.ok) return 'error';
+  return r.stale ? `${r.sig}~stale` : r.sig;
+}
+/** The cache entry of a repository as a string: it changes each time a derivation lands. Starts nothing. */
+function cachedSig(root) {
+  const hit = cache.get(root);
+  return hit ? `${hit.sig}@${hit.at}${hit.error ? '!' : ''}` : 'none';
+}
+/** Test and maintenance seam. */
+function invalidate(root) { if (root) { cache.delete(root); inflight.delete(root); } else { cache.clear(); inflight.clear(); } }
+
+// ── anchors ──────────────────────────────────────────────────────────────────────────────────────
+function anchorLib(from) {
+  try { return require(path.join(path.dirname(from), 'anchor-resolve.js')); } catch { return null; }
+}
+const cap = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+/** "q4-2026" → "Q4 2026". */
+const periodLabel = (p) => { const m = /^(q[1-4])-(\d{4})$/i.exec(String(p || '')); return m ? `${m[1].toUpperCase()} ${m[2]}` : (p || null); };
+
+/**
+ * What each anchor names, read from the OKR files and the health budgets (scripts/anchor-resolve.js, the gate's own
+ * resolver). resolve(raw) → { anchor, kind: 'kr'|'objective'|'health'|'domain'|'none', key, objective: { id, title,
+ * period } | null, title, token }. `key` groups two spellings of one KR together. Never throws.
+ */
+function anchorsOf(root) {
+  let from = null; let engine = null;
+  try { ({ from, engine } = enginePath()); } catch { /* no engine: every anchor reads as written */ }
+  const A = from ? anchorLib(from) : null;
+  let index = null; let budgets = null; let error = null;
+  if (A) {
+    try { index = A.parseOkrIndex(root); } catch (e) { error = String((e && e.message) || e); }
+    try {
+      const file = engine.layout(root).budgets;
+      budgets = { ok: true, text: fs.readFileSync(file, 'utf8'), path: path.relative(root, file) };
+    } catch { budgets = A.readBudgets(root); }
+  } else error = 'the anchor resolver is not present in this install';
+  const period = index && index.ok ? periodLabel(index.period) : null;
+  function resolve(raw) {
+    const text = raw == null ? '' : String(raw).trim();
+    if (!text) return { anchor: null, kind: 'none', key: 'none', objective: null, title: 'No anchor', token: null };
+    const r = A ? A.resolveAnchor(text, index, budgets) : null;
+    if (r && r.kind === 'health') return { anchor: `health:${r.budget}`, kind: 'health', key: `health:${r.budget}`, objective: null, title: `${cap(r.budget)} health`, token: `health:${r.budget}`, status: r.status };
+    if (r && r.kind === 'domain') return { anchor: `domain:${r.domain}`, kind: 'domain', key: `domain:${r.domain}`, objective: null, title: r.domain_goal || `${cap(r.domain)} domain`, token: `domain:${r.domain}`, status: r.status };
+    if (r && r.kind === 'okr' && r.status === 'resolved' && index && index.ok) {
+      const o = index.objectives.find((x) => x.id === r.objective);
+      const objective = o ? { id: o.token, title: o.name || o.token, period } : null;
+      if (r.kr) {
+        const k = o ? o.krs.find((x) => x.id === r.kr) : null;
+        return { anchor: k ? k.token : text, kind: 'kr', key: `${r.objective}::${r.kr}`, objective, title: (k && k.name) || text, token: k ? k.token : text, status: r.status };
+      }
+      return { anchor: o ? o.token : text, kind: 'objective', key: r.objective, objective, title: (o && o.name) || text, token: o ? o.token : text, status: r.status };
+    }
+    // Written but not resolved (or no resolver): shown as written, in a group of its own, never dropped.
+    return { anchor: text, kind: /^health:/i.test(text) ? 'health' : 'kr', key: `raw:${text}`, objective: null, title: text, token: text, status: r ? r.status : 'unknown' };
+  }
+  return { resolve, period, error, ok: !!(index && index.ok) };
+}
+
+module.exports = { deriveSync, rowsFor, peek, setBackground, isDeriving, deriveNow, answerSig, cachedSig, recordsSig, invalidate, anchorsOf, workGroupOf, periodLabel, narrow };

package/workspace/lib/initiative-writer.js

@@ -0,0 +1,141 @@
+'use strict';
+/* initiative-writer.js — THE ONE WRITER of a new initiative record (pm-os-absorb Run 2, PRD R16, R23; D59).
+ *
+ *   createInitiative(root, input, { actor, now }) → { ok: true, id, path, written }
+ *                                                 | { ok: false, status, error, field }
+ *   input = { title, lane, anchor, id?, intent?, specimen_test?, surface_check?, from? }
+ *   slugOf(title) → the id a title gives
+ *
+ * THREE CALLERS: the page's New initiative form (POST /api/initiatives, lib/routes-initiatives.js, behind
+ * pm-guard.requirePagePress), `pmos initiative new` (lib/initiative-cli.js, actor.fromCli) and the triage card's Add
+ * (the same route, `from: capture-…`). Agents reach it only through `pmos initiative new`. Every require of this file
+ * is spelled with `.js`, so scripts/check-separation.js lists each caller; pmos/graph-membership.json names it as the
+ * writer of `planning/initiatives/`.
+ *
+ * WHAT IT WRITES. One file, `<initiatives>/<id>.md` in the tree of `root` (planning/initiatives/ for PMOS-self,
+ * pmos/state/initiatives/ in a kit repository, from the engine's layout): the frontmatter the gates read (`type`,
+ * `title`, `timestamp`, `lane`, `parent_kr`, and `status` — the chore lane's intent — plus the router's
+ * `specimen_test` and `surface_check` when the caller has them). No new frontmatter field (R24). Then ONE `created`
+ * line in placements.jsonl (lib/placements.js): the initiative lands at the top of Later, whoever made it (R16, R23).
+ * The record is not committed: a commit is the caller's (the PM's) act.
+ *
+ * WHAT IT REFUSES, whoever calls:
+ *   - no anchor, or an anchor that the OKR files and the health budgets do not declare (400; D59: unanchored work is
+ *     rejected, and the gate's anchor rung would reject it later anyway);
+ *   - a lane that is not a WORK lane of the repository's profile (400; D86 point 4: document lanes are files);
+ *   - a chore with no intent (400; the Initiative Gate reads it from `status:`);
+ *   - an id that is not `^[a-z0-9][a-z0-9._-]*$`, or that contains `..` (400; the gate's own rule), or a record that
+ *     exists already (409);
+ *   - a writer field (`by`, `via`, `at`, …) in the input (400), and a call without an actor (500).
+ * The file is opened O_CREAT|O_EXCL|O_NOFOLLOW inside the resolved initiatives folder, so an existing file or a
+ * symlink is never written through. When the placement line cannot be written, the new record is removed again and
+ * the refusal is returned: a record never lands without its place in Later.
+ */
+const fs = require('fs');
+const path = require('path');
+const consoleState = require('./console-state');
+const placements = require('./placements.js');
+const rows = require('./initiative-rows.js');
+const actorLib = require('./actor.js');
+
+const ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const MAX_ID = 60;
+const WRITER_SET = Object.freeze(['v', 'eid', 'by', 'via', 'at', 'override', 'pm', 'actor', 'nonce', 'timestamp', 'type']);
+const INPUT_KEYS = Object.freeze(['id', 'title', 'lane', 'anchor', 'intent', 'specimen_test', 'surface_check', 'from']);
+const ONE_LINE = (v, max) => typeof v === 'string' && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n\x00-\x08\x0b-\x1f]/.test(v);
+
+const refuse = (status, error, field) => ({ ok: false, status, error, field: field || null });
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+/** One YAML double-quoted scalar on one line. */
+// A value that is a plain YAML scalar as written: no `: ` or ` #`, no quote, bracket, brace or other indicator at the
+// start, no quote anywhere. The resolver accepts text after a declared anchor, so anything else is written quoted.
+const PLAIN = (s) => !/: |:$| #|["\\]/.test(s) && !/^[-?:,[\]{}#&*!|>'%@`]/.test(s);
+const q = (s) => '"' + String(s).trim().replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+
+function slugOf(title) {
+  return String(title || '').toLowerCase().normalize('NFKD').replace(/[^\x00-\x7f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, MAX_ID).replace(/-+$/, '');
+}
+
+function createInitiative(root, input, { actor, now } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'initiative-writer: the caller must pass the actor from pm-guard.js or actor.js');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return refuse(400, 'the initiative must be a JSON object');
+  const sent = WRITER_SET.find((k) => has(input, k));
+  if (sent) return refuse(400, `the writer sets "${sent}"; do not send it`, sent);
+  const extra = Object.keys(input).filter((k) => !INPUT_KEYS.includes(k));
+  if (extra.length) return refuse(400, `an initiative has no field ${extra.join(', ')}`, extra[0]);
+
+  if (!ONE_LINE(input.title, 120)) return refuse(400, 'give a title of 1 to 120 characters on one line', 'title');
+  const title = input.title.trim();
+  const anchorText = typeof input.anchor === 'string' ? input.anchor.trim() : '';
+  if (!anchorText) return refuse(400, 'an initiative needs an anchor: a KR, or health:<id> from the health budgets (D59)', 'anchor');
+  if (!ONE_LINE(anchorText, 120)) return refuse(400, 'the anchor must be one line', 'anchor');
+
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) return refuse(500, loaded.error);
+  const engine = loaded.engine;
+  let groups;
+  try { groups = rows.workGroupOf(root); } catch (e) { return refuse(500, 'the lanes could not be read: ' + String((e && e.message) || e).slice(0, 120)); }
+  const lane = typeof input.lane === 'string' ? input.lane.trim() : '';
+  if (!has(groups, lane)) return refuse(400, `lane must be one of ${Object.keys(groups).filter((l) => groups[l] === 'work').join(', ')}`, 'lane');
+  if (groups[lane] !== 'work') return refuse(400, `${lane} is a document lane: a document is a file, not an initiative row (D86)`, 'lane');
+
+  const anchor = rows.anchorsOf(root).resolve(anchorText);
+  if (anchor.status !== 'resolved') return refuse(400, `the anchor "${anchorText}" is not declared in the OKR files or the health budgets (D59)`, 'anchor');
+
+  const intent = has(input, 'intent') && input.intent != null ? String(input.intent) : '';
+  if (intent && !ONE_LINE(intent, 400)) return refuse(400, 'the intent must be one paragraph of at most 400 characters', 'intent');
+  if (lane === 'chore' && !intent.trim()) return refuse(400, 'a chore needs a one-paragraph intent', 'intent');
+  for (const k of ['specimen_test', 'surface_check']) {
+    if (has(input, k) && input[k] != null && !ONE_LINE(input[k], 200)) return refuse(400, `${k} must be one line of at most 200 characters`, k);
+  }
+  if (has(input, 'from') && input.from != null && !(typeof input.from === 'string' && placements.CAPTURE_RE.test(input.from))) {
+    return refuse(400, 'from must name a capture note, like capture-2026-10-04-1', 'from');
+  }
+
+  const id = has(input, 'id') && input.id != null && input.id !== '' ? String(input.id) : slugOf(title);
+  if (!id || !ID_RE.test(id) || id.includes('..') || id.length > MAX_ID || id === 'readme' || id === 'index') {
+    return refuse(400, 'the id must be lower-case letters, digits, dot, underscore or hyphen, start with a letter or digit, and be at most 60 characters', 'id');
+  }
+
+  let dir;
+  try { dir = engine.layout(root).initiatives; fs.mkdirSync(dir, { recursive: true }); }
+  catch { return refuse(500, 'the initiatives folder could not be made — nothing was saved'); }
+  let realDir;
+  try { realDir = fs.realpathSync(dir); } catch { return refuse(500, 'the initiatives folder could not be resolved — nothing was saved'); }
+  const realRoot = fs.realpathSync(path.resolve(root));
+  if (realDir !== realRoot && !realDir.startsWith(realRoot + path.sep)) return refuse(500, 'the initiatives folder resolves outside the repository — nothing was saved');
+  const file = path.join(realDir, `${id}.md`);
+
+  const at = new Date(Number.isFinite(now) ? now : Date.now()).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const fm = ['---', 'type: Initiative', `title: ${q(title)}`, `timestamp: ${at}`, `lane: ${lane}`, `parent_kr: ${PLAIN(anchorText) ? anchorText : q(anchorText)}`];
+  if (intent.trim()) fm.push(`status: ${q(intent)}`);
+  if (input.specimen_test) fm.push(`specimen_test: ${q(input.specimen_test)}`);
+  if (input.surface_check) fm.push(`surface_check: ${q(input.surface_check)}`);
+  fm.push('---', '', `# ${title}`, '');
+  if (intent.trim()) fm.push(intent.trim(), '');
+  const text = fm.join('\n');
+
+  let fd;
+  try { fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o644); }
+  catch (e) {
+    if (e && e.code === 'EEXIST') return refuse(409, `an initiative ${id} exists already`, 'id');
+    return refuse(500, 'the record could not be written — nothing was saved');
+  }
+  try { fs.writeSync(fd, text); } catch {
+    try { fs.closeSync(fd); fs.unlinkSync(file); } catch { /* best effort */ }
+    return refuse(500, 'the record could not be written — nothing was saved');
+  }
+  fs.closeSync(fd);
+
+  const landing = { ev: 'created', initiative: id };
+  if (input.from) landing.from = input.from;
+  const placed = (actor.via === 'ui' ? placements.appendFromUi : placements.appendFromCli)(root, [landing], { actor, now });
+  if (!placed.ok) {
+    try { fs.unlinkSync(file); } catch { /* best effort */ }
+    return refuse(placed.status || 500, `the initiative was not created: ${placed.error}`);
+  }
+  return { ok: true, id, path: path.relative(realRoot, file).split(path.sep).join('/'), written: 1 + placed.written };
+}
+
+module.exports = { createInitiative, slugOf, ID_RE, INPUT_KEYS };

package/workspace/lib/issues.js

@@ -0,0 +1,206 @@
+'use strict';
+/* issues.js — THE ONE WRITER and THE ONE FOLD of issues.jsonl: which report was issued, when, and the git blob sha
+ * of the file as issued (pm-os-absorb, PRD R22.5, R24, R25; D86 point 3).
+ *
+ *   readIssues(root) → {
+ *     ok: true,
+ *     issues: [{ cadence, slot, path, sha, at, by, via }],   oldest first; `slot` is the report date YYYY-MM-DD
+ *     flags: [{ kind, eid, why }],                           unreadable, unknown-event, malformed, invalid, not-pm,
+ *                                                            duplicate-slot: each line named has no effect
+ *     sig,                                                   ledgerSig taken BEFORE the read (F2)
+ *   }
+ *   lastIssue(result, cadence)                   → the newest issue of that cadence, or null
+ *   isIssued(result, cadence, slot)              → true when that slot is frozen (Redraft is refused)
+ *   appendFromUi(root, events, { actor, now })   → { ok, written } | { ok: false, status, error, index }
+ *   appendFromCli(root, events, { actor, now })  → the same
+ *
+ * Issue is a PM-only act (R25): the route takes its actor from pm-guard.js requirePmPress({ act: 'issue' }), and the
+ * CLI from pm-guard.js requirePmCli({ act: 'issue' }). The biweekly's window is `since_last_issue`: from lastIssue's
+ * `at`, or `report_cycle_days` back (lib/plan-rules.js) when there is none.
+ *
+ * THE `issued` LINE (the shared contract):
+ *   { v: 1, eid, ev: 'issued', cadence: 'biweekly'|…, slot: 'YYYY-MM-DD', path: '<repo-relative path of the report>',
+ *     sha: '<git blob sha of the file as issued, 40 hex>', by, via, at }
+ *   pmOnly(rec) → true for every `issued` line (R25).
+ *
+ * THE WRITER (Run 5, slice 5A; the sink guard and the refusal shape are lib/plan-items.js's). It refuses, writing
+ * nothing: an actor that is not the PM or not on its own call path (403); a writer field or an unknown field (400); a
+ * bad cadence, slot or sha, or a path that is not the slot's own draft file (report-draft.js draftPath) (400); a slot
+ * already issued (409); a file that does not exist (404) or whose blob sha is not the one sent (409), so an issue
+ * always freezes the bytes the PM read. `at` is strictly increasing.
+ *   blobSha(buf) → what `git hash-object` prints for those bytes; scripts/check-issues.js and report-draft.js use it.
+ *   lineErr(rec) → why a line breaks the schema, or null; the checker's schema is this one.
+ * The ledger is one per repository: lib/plan-ledgers.js ledgerPath(root, 'issues'). The issued FILE is read in
+ * `root`, the tree the report was drafted in.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { createSinkGuard } = require('./sink.js');
+const ledgers = require('./plan-ledgers.js');
+const actorLib = require('./actor.js');
+
+const MAX_LINES = 10;
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const EID_RE = /^[0-9a-z]{12}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+const EVENT_FIELDS = ['ev', 'cadence', 'slot', 'path', 'sha'];
+const WRITER_FIELDS = ['v', 'eid', 'by', 'via', 'at'];
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+const isStr = (v) => typeof v === 'string';
+const refuse = (status, error, index) => ({ ok: false, status, error, index: index == null ? null : index });
+/** A real calendar day, not only the shape of one. */
+const isDate = (s) => isStr(s) && DATE_RE.test(s) && new Date(s + 'T00:00:00Z').toISOString().slice(0, 10) === s;
+
+/** The git blob sha of a file's bytes (what `git hash-object` prints), without running git. */
+function blobSha(buf) {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(String(buf), 'utf8');
+  return crypto.createHash('sha1').update(`blob ${b.length}\0`).update(b).digest('hex');
+}
+
+/** A repository-relative path a report can have: `…/reports/<cadence>/<slot>.md`, inside the tree, no `..`. */
+function reportPathOk(rel, cadence, slot) {
+  if (!isStr(rel) || !rel || rel.startsWith('/') || rel.includes('\\') || rel.split('/').some((p) => p === '..' || p === '.' || p === '')) return false;
+  const tail = `reports/${cadence}/${slot}.md`;
+  return rel === tail || rel.endsWith(`/${tail}`);
+}
+
+/** The schema of one ledger line, as the fold and the checker read it. null when it is valid, else why. */
+function lineErr(rec) {
+  if (!rec || typeof rec !== 'object' || Array.isArray(rec)) return 'not a JSON object';
+  if (rec.v !== 1) return 'v must be 1';
+  if (!isStr(rec.eid) || !EID_RE.test(rec.eid)) return 'eid must be 12 characters of [0-9a-z]';
+  if (rec.ev !== 'issued') return `unknown event ${JSON.stringify(rec.ev)}`;
+  if (!isStr(rec.cadence) || !CADENCE_RE.test(rec.cadence)) return 'cadence must be a report id such as biweekly';
+  if (!isDate(rec.slot)) return 'slot must be a date, YYYY-MM-DD';
+  if (!reportPathOk(rec.path, rec.cadence, rec.slot)) return `path must be the report file …/reports/${rec.cadence}/${rec.slot}.md`;
+  if (!isStr(rec.sha) || !SHA_RE.test(rec.sha)) return 'sha must be the 40-character git blob sha';
+  if (!isStr(rec.by) || !actorLib.BY_RE.test(rec.by)) return 'by must be pm:<slug>, agent:unknown or agent:<session>';
+  if (!actorLib.VIA.includes(rec.via)) return 'via must be ui or cli';
+  if (!isStr(rec.at) || !AT_RE.test(rec.at) || !Number.isFinite(Date.parse(rec.at))) return 'at must be an ISO UTC time';
+  return null;
+}
+
+function readIssues(root) {
+  // F2: the signature is taken BEFORE the read, so a line appended during the read costs one more read, never a missed one.
+  const sig = ledgers.ledgerSig(root, 'issues');
+  const out = { ok: true, issues: [], flags: [], sig };
+  const { lines, bad } = ledgers.readLines(root, 'issues');
+  for (const b of bad) out.flags.push({ kind: 'unreadable', eid: null, why: `line ${b.n}: ${b.why}` });
+  const seen = new Map();
+  for (const { n, rec } of lines) {
+    if (rec.ev !== 'issued') { out.flags.push({ kind: 'unknown-event', eid: rec.eid || null, why: `line ${n}: ${JSON.stringify(rec.ev)} is not an event of this ledger` }); continue; }
+    if (typeof rec.cadence !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(String(rec.slot)) || typeof rec.path !== 'string') {
+      out.flags.push({ kind: 'malformed', eid: rec.eid || null, why: 'an issued line needs a cadence, a slot date and a path' });
+      continue;
+    }
+    const why = lineErr(rec);
+    if (why) { out.flags.push({ kind: 'invalid', eid: rec.eid || null, why: `line ${n}: ${why}` }); continue; }
+    if (!actorLib.isPm({ by: rec.by, via: rec.via })) { out.flags.push({ kind: 'not-pm', eid: rec.eid, why: `line ${n}: ${rec.by} issued ${rec.cadence} ${rec.slot}; only the PM issues a report (R25), so the line has no effect` }); continue; }
+    const key = `${rec.cadence}\u0000${rec.slot}`;
+    if (seen.has(key)) { out.flags.push({ kind: 'duplicate-slot', eid: rec.eid, why: `line ${n}: ${rec.cadence} ${rec.slot} was issued on line ${seen.get(key)}; the later line has no effect` }); continue; }
+    seen.set(key, n);
+    out.issues.push({ cadence: rec.cadence, slot: rec.slot, path: rec.path, sha: rec.sha || null, at: rec.at, by: rec.by, via: rec.via });
+  }
+  return out;
+}
+
+const pmOnly = (rec) => !!rec && rec.ev === 'issued';
+
+function lastIssue(result, cadence) {
+  const rows = (result && Array.isArray(result.issues) ? result.issues : []).filter((r) => r && r.cadence === cadence);
+  return rows.length ? rows.reduce((a, b) => (String(b.at) >= String(a.at) ? b : a)) : null;
+}
+
+function isIssued(result, cadence, slot) {
+  return (result && Array.isArray(result.issues) ? result.issues : []).some((r) => r && r.cadence === cadence && r.slot === slot);
+}
+
+// ── the writer ──────────────────────────────────────────────────────────────────────────────────────
+function randomChars(n) {
+  let out = '';
+  while (out.length < n) {
+    for (const b of crypto.randomBytes(n * 2)) {
+      if (b >= 252) continue;                    // 252 = 7 × 36: keep the modulo unbiased
+      out += ALPHABET[b % 36];
+      if (out.length === n) break;
+    }
+  }
+  return out;
+}
+
+/**
+ * One `issued` line per event. The actor is the caller's guard result (pm-guard.js), never a field; only the PM
+ * issues, and the call path must match the actor (`ui` from the page, `cli` from a terminal). Each event names a file
+ * that exists in `root` with exactly the sha sent, so a line can never freeze bytes nobody read.
+ */
+function append(root, events, actor, via, { now } = {}) {
+  if (!actorLib.isPm(actor) || actor.via !== via) return refuse(403, `only the PM issues a report, from the ${via === 'ui' ? 'page' : 'terminal'}; nothing was written`, null);
+  if (!Array.isArray(events) || !events.length) return refuse(400, 'send at least one line', null);
+  if (events.length > MAX_LINES) return refuse(413, `send at most ${MAX_LINES} lines at once`, null);
+  let read;
+  try { read = readIssues(root); } catch (e) { return refuse(500, 'could not read the issues ledger; nothing was written: ' + String((e && e.message) || e).slice(0, 160), null); }
+  if (read.flags.some((f) => f.kind === 'unreadable' && /^line 0:/.test(f.why))) return refuse(500, 'the workflow engine is missing, so the issues ledger cannot be found; nothing was written', null);
+  const clock = now == null ? Date.now() : (typeof now === 'number' ? now : Date.parse(now));
+  if (!Number.isFinite(clock)) return refuse(400, 'now must be a time', null);
+  let last = 0;
+  for (const r of read.issues) { const t = Date.parse(r.at); if (Number.isFinite(t) && t <= clock + 1000 && t > last) last = t; }
+  const taken = new Set(read.issues.map((r) => `${r.cadence}\u0000${r.slot}`));
+  const recs = [];
+  for (let i = 0; i < events.length; i++) {
+    const ev = events[i];
+    if (!ev || typeof ev !== 'object' || Array.isArray(ev)) return refuse(400, 'each line must be a JSON object', i);
+    const sent = WRITER_FIELDS.find((k) => Object.prototype.hasOwnProperty.call(ev, k));
+    if (sent) return refuse(400, `the writer sets "${sent}"; do not send it`, i);
+    const extra = Object.keys(ev).find((k) => !EVENT_FIELDS.includes(k));
+    if (extra) return refuse(400, `an issued line has no field "${extra}"`, i);
+    if (ev.ev !== 'issued') return refuse(400, 'the only event is issued', i);
+    if (!isStr(ev.cadence) || !CADENCE_RE.test(ev.cadence)) return refuse(400, 'cadence must be a report id such as biweekly', i);
+    if (!isDate(ev.slot)) return refuse(400, 'slot must be a date, YYYY-MM-DD', i);
+    if (!reportPathOk(ev.path, ev.cadence, ev.slot)) return refuse(400, `path must be the report file …/reports/${ev.cadence}/${ev.slot}.md`, i);
+    // The writer pins the path to the slot's own draft file (report-draft.js draftPath, the one layout rule), so the
+    // sha it records guards the bytes of that draft and no other file. Required here: report-draft.js requires this file.
+    let own;
+    try { own = require('./report-draft.js').draftPath(root, ev.cadence, ev.slot); }
+    catch { return refuse(500, 'the workflow engine is missing, so the report file cannot be found; nothing was written', i); }
+    if (ev.path !== own) return refuse(400, `path must be ${own}, the draft file of ${ev.cadence} ${ev.slot}`, i);
+    if (!isStr(ev.sha) || !SHA_RE.test(ev.sha)) return refuse(400, 'sha must be the 40-character git blob sha of the report', i);
+    const key = `${ev.cadence}\u0000${ev.slot}`;
+    if (taken.has(key)) return refuse(409, `${ev.cadence} ${ev.slot} is already issued; an issued report is frozen`, i);
+    let buf;
+    try { buf = fs.readFileSync(path.join(path.resolve(String(root)), ev.path)); }
+    catch { return refuse(404, `${ev.path} does not exist; draft the report first`, i); }
+    if (blobSha(buf) !== ev.sha) return refuse(409, `${ev.path} changed after it was read; read it again, then issue`, i);
+    taken.add(key);
+    const t = Math.max(clock, last + 1);
+    last = t;
+    recs.push({ v: 1, eid: randomChars(12), ev: 'issued', cadence: ev.cadence, slot: ev.slot, path: ev.path, sha: ev.sha,
+      by: actor.by, via, at: new Date(t).toISOString() });
+  }
+  let file;
+  try { file = ledgers.ledgerPath(root, 'issues'); fs.mkdirSync(path.dirname(file), { recursive: true }); }
+  catch { return refuse(500, 'could not record; nothing was written', null); }
+  const guard = createSinkGuard({ sink: file, what: 'report issues' });
+  let wrote = 0;
+  for (const rec of recs) {
+    try { guard.appendLine(file, rec); wrote++; }
+    catch {
+      return refuse(500, wrote ? `could not record; ${wrote} of ${recs.length} lines were written before the write failed` : 'could not record; nothing was written', wrote);
+    }
+  }
+  return { ok: true, written: recs.map((r) => ({ eid: r.eid, ev: r.ev, cadence: r.cadence, slot: r.slot, path: r.path, sha: r.sha, at: r.at })) };
+}
+
+/** POST /api/report/issue (5C), after pm-guard.js requirePmPress({ act: 'issue' }) passed: `actor` is its result. */
+function appendFromUi(root, events, { actor, now } = {}) {
+  return append(root, events, actor, 'ui', { now });
+}
+/** `pmos report issue` (lib/report-cli.js), after pm-guard.js requirePmCli({ act: 'issue' }) passed. */
+function appendFromCli(root, events, { actor, now } = {}) {
+  return append(root, events, actor, 'cli', { now });
+}
+
+module.exports = { readIssues, lastIssue, isIssued, pmOnly, appendFromUi, appendFromCli, lineErr, blobSha, reportPathOk, MAX_LINES };