create-pmos 0.134.0 → 0.136.0

package/workspace/lib/engine/doc-health.js

@@ -0,0 +1,142 @@
+'use strict';
+/* doc-health.js — console3 wave B2: the six document health checks, a word diff, and a revision compare. Pure.
+ *
+ * healthOf(doc, context) is recomputed from the text on every call and is never stored.
+ *   doc     = { text, type?, changed? (ISO date of the last change) }
+ *   context = { now?, staleAfterDays?, sources?: [{ path, changed, kind? }], decisionIds?: [id], decisionChanges?: { id: ISO },
+ *               requiredHeadings?: { <type>: [heading] }, data?: { <name>: number }, readers?: [{ name, seen }], current? }
+ * A check whose input is not given returns { pass: null, reason: 'not enough input' }; it is neither passed nor failed,
+ * so `total` counts only the checks that could be answered.
+ */
+const { citedSummary, LABELS } = require('./releases.js');
+const V = require('./derived/derive.js');
+
+/* BACKED BY THE PM'S SAMPLE (derived/derive.js, from reader.js sections 3 and 4): the `complete` check below, and graphHealth()
+ * for a whole portfolio (document graph + six checks over frontmatter revisions). REPO-WRITTEN, because the sample derives
+ * health from frontmatter revs, not from text and git dates: the text/git-based fresh, decisions, data, traced and readers
+ * checks in healthOf, the six-check wording ('not enough input' reasons), wordDiff and historyCompare. */
+
+const NO_INPUT = 'not enough input';
+const na = (id) => ({ id, pass: null, reason: NO_INPUT });
+const day = 86400000;
+const ts = (v) => { const t = Date.parse(v); return Number.isNaN(t) ? null : t; };
+
+function fresh(doc, c) {
+  const at = ts(doc.changed);
+  if (at == null) return na('fresh');
+  const newer = (c.sources || []).filter((s) => ts(s.changed) != null && ts(s.changed) > at).map((s) => s.path);
+  if (newer.length) return { id: 'fresh', pass: false, reason: 'a cited source changed after this document: ' + newer.join(', ') };
+  if (c.staleAfterDays != null) {
+    const now = ts(c.now) != null ? ts(c.now) : Date.now();
+    const age = Math.floor((now - at) / day);
+    return age > c.staleAfterDays
+      ? { id: 'fresh', pass: false, reason: `last changed ${age} days ago; stale after ${c.staleAfterDays}` }
+      : { id: 'fresh', pass: true, reason: `changed ${age} days ago; stale after ${c.staleAfterDays}` };
+  }
+  if (!(c.sources || []).some((s) => ts(s.changed) != null)) return na('fresh');
+  return { id: 'fresh', pass: true, reason: 'no cited source changed after it' };
+}
+
+function matchesDecisions(doc, c) {
+  const at = ts(doc.changed);
+  if (at == null || !c.decisionChanges) return na('decisions');
+  const ids = c.decisionIds || Object.keys(c.decisionChanges);
+  const known = ids.filter((id) => ts(c.decisionChanges[id]) != null);
+  if (!known.length) return na('decisions');
+  const newer = known.filter((id) => ts(c.decisionChanges[id]) > at);
+  return newer.length
+    ? { id: 'decisions', pass: false, reason: 'decision updated after this document: ' + newer.join(', ') }
+    : { id: 'decisions', pass: true, reason: known.length + ' referenced decision(s), none newer' };
+}
+
+const numbersIn = (t) => (String(t).match(/\d[\d,]*(?:\.\d+)?/g) || []).map((n) => Number(n.replace(/,/g, '')));
+
+function matchesData(doc, c) {
+  if (!c.data || !Object.keys(c.data).length) return na('data');
+  const miss = [];
+  for (const [name, v] of Object.entries(c.data)) {
+    const line = String(doc.text).split('\n').find((l) => l.toLowerCase().includes(name.toLowerCase()));
+    if (!line) continue;                           // the figure is not quoted: nothing to compare
+    if (!numbersIn(line).includes(Number(v))) miss.push(`${name}: data says ${v}, text says ${numbersIn(line).join(' / ') || 'no number'}`);
+  }
+  return miss.length ? { id: 'data', pass: false, reason: miss.join('; ') } : { id: 'data', pass: true, reason: 'every quoted figure matches its data file' };
+}
+
+function complete(doc, c) {
+  const req = c.requiredHeadings && (c.requiredHeadings[doc.type] || (Array.isArray(c.requiredHeadings) ? c.requiredHeadings : null));
+  if (!req || !req.length) return na('complete');
+  // the sample's rule (reader.js section 4): each required section is a level-2 heading, "## <name>", case-sensitive
+  const ok = V.docHealth('x', { x: { type: 'x', rev: 1, _body: String(doc.text) } }, [], [], { x: req }, '').complete;
+  const missing = req.filter((h) => !String(doc.text).includes('## ' + h));
+  return ok ? { id: 'complete', pass: true, reason: 'all ' + req.length + ' required headings are present' }
+    : { id: 'complete', pass: false, reason: 'missing headings: ' + missing.join(', ') };
+}
+
+/** graphHealth(docs, findings, readers, need, now) → { edges, health: { id: { fresh, decisions, data, complete, traced, readers } } }.
+ *  The sample's whole-portfolio derivation: docs { id: { type, rev, sources:[{id,rev}], stale_after, tickets, _body } }. */
+function graphHealth(docs, findings, readers, need, now) {
+  const edges = V.docGraph(docs, findings);
+  const health = {};
+  for (const id of Object.keys(docs)) health[id] = V.docHealth(id, docs, edges, readers, need, now);
+  return { edges, health };
+}
+
+// A claim line is a body line with a figure in it. It is traced when it names a label or a ticket key.
+function sourceOf(line) {
+  const t = /\b[A-Z][A-Z0-9]+-\d+\b/.exec(line);
+  if (t) return t[0];
+  const l = new RegExp('[\\[(](' + LABELS.join('|') + ')[\\])]', 'i').exec(line);
+  return l ? l[1].toLowerCase() : null;
+}
+function traced(doc) {
+  const claims = String(doc.text).split('\n').filter((l) => l.trim() && !/^#/.test(l) && /\d/.test(l));
+  if (!claims.length) return { id: 'traced', pass: true, reason: 'no claim lines (a line with a figure)' };
+  const r = citedSummary(claims.map((l) => ({ text: l, source: sourceOf(l) })));
+  return r.ok ? { id: 'traced', pass: true, reason: claims.length + ' claim line(s), all cited' }
+    : { id: 'traced', pass: false, reason: r.refused.length + ' of ' + claims.length + ' claim line(s) carry no label or ticket: ' + r.refused.slice(0, 3).map((i) => `"${claims[i].trim().slice(0, 40)}"`).join(', ') };
+}
+
+function readersCurrent(doc, c) {
+  if (!Array.isArray(c.readers) || c.current == null) return na('readers');
+  if (!c.readers.length) return { id: 'readers', pass: true, reason: 'no readers listed' };
+  const behind = c.readers.filter((r) => r.seen !== c.current).map((r) => r.name);
+  return behind.length ? { id: 'readers', pass: false, reason: 'not on the current version: ' + behind.join(', ') }
+    : { id: 'readers', pass: true, reason: 'every reader has the current version' };
+}
+
+function healthOf(doc, context = {}) {
+  const d = doc || {};
+  const checks = [fresh(d, context), matchesDecisions(d, context), matchesData(d, context), complete(d, context), traced(d), readersCurrent(d, context)];
+  const answered = checks.filter((k) => k.pass !== null);
+  return { passed: answered.filter((k) => k.pass).length, total: answered.length, checks };
+}
+
+const words = (s) => String(s || '').split(/\s+/).filter(Boolean);
+
+function wordDiff(before, after) {
+  const a = words(before), b = words(after);
+  const n = a.length, m = b.length;
+  const L = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) L[i][j] = a[i] === b[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+  const out = [];
+  const push = (op, text) => { const last = out[out.length - 1]; if (last && last.op === op) last.text += ' ' + text; else out.push({ op, text }); };
+  let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) { push('same', a[i]); i++; j++; }
+    else if (L[i + 1][j] >= L[i][j + 1]) push('del', a[i++]);
+    else push('add', b[j++]);
+  }
+  while (i < n) push('del', a[i++]);
+  while (j < m) push('add', b[j++]);
+  return out;
+}
+
+// revisions: [{ id, text }]. a and b are revision ids.
+function historyCompare(revisions, a, b) {
+  const find = (id) => (revisions || []).find((r) => r.id === id);
+  const ra = find(a), rb = find(b);
+  if (!ra || !rb) return { ok: false, error: 'revision not found: ' + (!ra ? a : b) };
+  return { ok: true, from: a, to: b, diff: wordDiff(ra.text, rb.text) };
+}
+
+module.exports = { graphHealth, healthOf, wordDiff, historyCompare, NO_INPUT };

package/workspace/lib/engine/doc-sheet.js

@@ -0,0 +1,75 @@
+'use strict';
+/* doc-sheet.js — the document sheet's pure core (console3 wave E1c). No file, no clock beyond `at`, no network.
+ *
+ *   editWithWhy(before, after, why, by, opts?) → { rev, before_hash, after_hash, why, by, at, text }   refuses an empty why
+ *   revisions(events, path)                    → the ordered revision list for one path (text where stored)
+ *   foldAt(events, rev, path?)                 → the text at a revision (the fold of the revisions), or null
+ *   askAgentProposal({ before, after, prompt }) → { state:'proposed', prompt, diff, hash }   only a proposal; nothing is written
+ *   acceptProposal(proposal, { hash, by })      → { ok:true, event } | { ok:false, reason }   PM only, hash-bound
+ *   changeNote(doc, downstreamDocs)             → a DRAFT note for owners of documents whose source rev is behind; never sent
+ *
+ * The slide-to-accept is the same hash-bound confirm as the outbox: the hash covers the proposed text, so an edited
+ * proposal has a new hash and the PM's press on the old one is void. An agent can create a proposal and never accept it.
+ */
+const crypto = require('crypto');
+const { wordDiff } = require('./doc-health.js');
+
+const sha = (v) => crypto.createHash('sha256').update(typeof v === 'string' ? v : JSON.stringify(v)).digest('hex');
+const hashText = (t) => sha(String(t == null ? '' : t));
+
+function editWithWhy(before, after, why, by, opts = {}) {
+  if (typeof why !== 'string' || !why.trim()) throw new Error('a why is required: say why the document changes');
+  if (!by || typeof by !== 'string') throw new Error('by is required');
+  const ev = { rev: opts.rev == null ? 1 : opts.rev, before_hash: hashText(before), after_hash: hashText(after),
+    why: why.trim(), by, at: opts.at || new Date().toISOString(), text: String(after == null ? '' : after) };
+  if (opts.path) ev.path = opts.path;
+  return ev;
+}
+
+function revisions(events, path) {
+  return (events || []).filter((e) => e && typeof e.rev === 'number' && (path == null || e.path === path))
+    .slice().sort((a, b) => a.rev - b.rev);
+}
+
+function foldAt(events, rev, path) {
+  let text = null;
+  for (const e of revisions(events, path)) {
+    if (e.rev > rev) break;
+    if (typeof e.text === 'string') text = e.text;
+  }
+  return text;
+}
+
+function proposalHash(before_hash, after) { return sha({ before_hash, after: String(after == null ? '' : after) }); }
+
+function askAgentProposal({ before, after, prompt } = {}) {
+  if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('a prompt is required');
+  const before_hash = hashText(before);
+  return { state: 'proposed', prompt: prompt.trim(), before_hash, after: String(after == null ? '' : after),
+    diff: wordDiff(before, after), hash: proposalHash(before_hash, after) };
+}
+
+function acceptProposal(proposal, { hash, by, rev, at, path } = {}) {
+  if (!proposal) return { ok: false, reason: 'no such proposal' };
+  if (by !== 'pm') return { ok: false, reason: 'only the PM can accept a proposal, from the page' };
+  if (proposal.state && proposal.state !== 'proposed') return { ok: false, reason: 'the proposal is already ' + proposal.state };
+  const current = proposalHash(proposal.before_hash, proposal.after);
+  if (typeof hash !== 'string' || hash !== current) return { ok: false, reason: 'hash does not match the proposal as it stands' };
+  return { ok: true, hash: current, event: { ...editWithWhy(proposal.before_text == null ? '' : proposal.before_text, proposal.after, proposal.prompt, 'pm', { rev, at, path }), before_hash: proposal.before_hash } };
+}
+
+// doc: { path, rev, title? }. downstreamDocs: [{ path, owner?, sources: [{ path, rev }] }]; sources[].rev is the upstream rev last used.
+function changeNote(doc, downstreamDocs) {
+  const behind = [];
+  for (const d of downstreamDocs || []) {
+    const s = (d.sources || []).find((x) => x.path === doc.path);
+    if (s && Number(s.rev) < Number(doc.rev)) behind.push({ path: d.path, owner: d.owner || null, used_rev: s.rev, current_rev: doc.rev });
+  }
+  const lines = behind.map((b) => `- ${b.path}${b.owner ? ' (' + b.owner + ')' : ''}: built on rev ${b.used_rev}, now rev ${b.current_rev}`);
+  const body = behind.length
+    ? `${doc.path} changed to rev ${doc.rev}. These documents were built on an earlier rev:\n${lines.join('\n')}\nPlease check whether each needs an update.`
+    : `${doc.path} is at rev ${doc.rev}. No downstream document is behind.`;
+  return { draft: true, sent: false, path: doc.path, rev: doc.rev, behind, body };
+}
+
+module.exports = { editWithWhy, revisions, foldAt, askAgentProposal, acceptProposal, changeNote, hashText, proposalHash };

package/workspace/lib/engine/intake.js

@@ -0,0 +1,78 @@
+'use strict';
+/* intake.js — the one-line intake run (planning-flows run 4). Pure: reads planning/out-of-scope/, writes nothing.
+ * Honest by design: confidence counts matched lane signals, the anchor is never invented, a prior rejection refuses. */
+const fs = require('fs');
+const path = require('path');
+const { laneNames } = require('./lane-defs');
+
+const SIGNALS = {
+  incident: ['outage', 'incident', 'postmortem', 'broke', 'down', 'sev1', 'sev2', 'regression in prod'],
+  discovery: ['investigate', 'explore', 'research', 'spike', 'unknown', 'should we', 'whether', 'feasibility', 'discover'],
+  chore: ['chore', 'bump', 'upgrade', 'rename', 'cleanup', 'clean up', 'refactor', 'dependency', 'dependencies', 'lint'],
+  content: ['blog', 'copy', 'docs', 'documentation', 'announcement', 'article', 'landing page copy', 'newsletter'],
+  prototype: ['prototype', 'mockup', 'sketch', 'specimen', 'try out', 'what if'],
+  feature: ['add', 'build', 'new', 'support', 'allow', 'let users', 'enable', 'feature', 'create', 'implement'],
+};
+const STOP = new Set('a an the and or of to in on for with is are be as at by it this that from into we i our my your should can will new add use using make get'.split(' '));
+
+const words = (s) => String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9-]*/g) || [];
+const sig = (s) => new Set(words(s).filter((w) => w.length > 2 && !STOP.has(w)));
+
+function parseIntakeLine(text) {
+  const title = String(text || '').trim().replace(/\s+/g, ' ');
+  const low = ` ${title.toLowerCase()} `;
+  const valid = new Set(laneNames());
+  const hits = {};
+  for (const [lane, keys] of Object.entries(SIGNALS)) {
+    if (!valid.has(lane)) continue;
+    const n = keys.filter((k) => new RegExp(`(^|[^a-z0-9])${k.replace(/ /g, '\\s+')}([^a-z0-9]|$)`).test(low)).length;
+    if (n) hits[lane] = n;
+  }
+  const ranked = Object.entries(hits).sort((a, b) => b[1] - a[1]);
+  if (!ranked.length) return { title, lane_guess: null, confidence: 0.2 };
+  const total = ranked.reduce((s, [, n]) => s + n, 0);
+  const [lane, n] = ranked[0];
+  // Honest: more matches and less competition raise it; the ceiling is 0.85 because a keyword match is not a judgment.
+  const confidence = Math.min(0.85, Math.round((0.3 + 0.15 * n) * (n / total) * 100) / 100 || 0.2);
+  return { title, lane_guess: lane, confidence };
+}
+
+function priorRejections(root, text) {
+  const dir = path.join(root, 'planning', 'out-of-scope');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'README.md'); } catch (_) { return []; }
+  const want = sig(text);
+  const out = [];
+  for (const f of files) {
+    let body = '';
+    try { body = fs.readFileSync(path.join(dir, f), 'utf8'); } catch (_) { continue; }
+    const t = (body.match(/^title:\s*"?(.*?)"?\s*$/m) || [])[1] || f.replace(/\.md$/, '');
+    const topic = (body.match(/^topic:\s*"?(.*?)"?\s*$/m) || [])[1] || '';
+    const have = sig(`${t} ${topic} ${f.replace(/\.md$/, '').replace(/-/g, ' ')}`);
+    const shared = [...want].filter((w) => have.has(w));
+    if (shared.length >= 2) out.push({ file: `planning/out-of-scope/${f}`, title: t, shared });
+  }
+  return out;
+}
+
+// anchor: only an explicit `health:<id>` or `KR<n>` typed in the line; the caller must still confirm it.
+function suggestAnchor(line) {
+  const m = String(line || '').match(/\bhealth:[a-z0-9-]+\b/i) || String(line || '').match(/\bKR\d+\b/);
+  return m ? m[0] : null;
+}
+
+function intakeDraft({ line, root, acknowledged = false }) {
+  const p = parseIntakeLine(line);
+  const prior = priorRejections(root || process.cwd(), line);
+  const refused = prior.length > 0 && !acknowledged;
+  return {
+    title: p.title, lane: p.lane_guess, confidence: p.confidence,
+    anchor_suggestion: suggestAnchor(line),
+    prior_rejections: prior,
+    refused,
+    refused_reason: refused ? `Prior rejection on record: ${prior.map((r) => r.title).join('; ')}. Acknowledge it before you create.` : null,
+    stage: 'discover',
+  };
+}
+
+module.exports = { parseIntakeLine, priorRejections, intakeDraft, suggestAnchor };

package/workspace/lib/engine/outbox.js

@@ -0,0 +1,86 @@
+'use strict';
+// The outbox queue: pure functions over an entry, rebased on the PM's trust controls (scripts/trust/outbox.js, trust.js).
+// The content hash, the claim rules and the PM-only confirm come from scripts/trust. This file only adapts them to the
+// entry shape the workspace stores (channel, recipient, subject, body). Sends NOTHING: a channel is only a name until a
+// sender is registered.
+const fs = require('fs');
+const path = require('path');
+const T = require('./trust/outbox.js');
+const { checkReport } = require('./trust/trust.js');
+const RULES = require('./trust/claim-rules.json');
+
+const CHANNELS = ['jira-write', 'calendar-hold', 'customer-note'];
+const ORIGINS = ['agent', 'pm'];
+const SENDERS = {}; // channel -> function. Empty on purpose.
+const BASES = Object.keys(RULES.basis);
+const KEY = /^[A-Z][A-Z0-9]+-\d+$/;
+// The trust rules, for free text: the destination keeps the label rules (every claim labelled, allowed, an import only as
+// reported, a fact or cite names a source that exists) and drops the field-completeness rules, which prose cannot carry.
+const DEST = { ...RULES.destinations.leadership, incomplete: 'ok', stale: 'ok', overdue_assumption: 'ok' };
+
+const RULES_OUT = { ...RULES, destinations: { ...RULES.destinations, outbox: DEST } };
+
+// Sample hash inputs: [channel, to, subject, body]. `recipient` is the entry's name for `to`.
+const hashOf = ({ channel, recipient, to, subject, body }) =>
+  T.hashOf({ channel, to: recipient !== undefined ? recipient : to, subject: subject || '', body });
+
+const entryHash = (e) => hashOf({ channel: e.channel, recipient: e.recipient || null, subject: e.subject || '', body: e.body });
+
+// Claim lines are body lines starting with "- " or "* ". Each ends with [fact|cited|reported|estimate|assumption|judgement] or [KEY-123].
+// A [KEY-123] is a citation of that ticket. rows[i].line is the line text.
+function claimCheck(entry) {
+  const lines = String(entry.body).split('\n').filter((l) => /^\s*[-*]\s+/.test(l));
+  const docs = {};
+  const sections = lines.map((l, i) => {
+    const m = l.match(/\[([^\]]+)\]\s*$/);
+    const label = m ? m[1] : null;
+    const c = { id: i, claim: l.trim() };
+    if (label && KEY.test(label)) { c.basis = 'cited'; c.source = label; docs[label] = { rev: 0 }; }
+    else if (label && BASES.includes(label)) c.basis = label;
+    return c;
+  });
+  const verdict = checkReport({ sections }, RULES_OUT, { snaps: [], last: '', docs, now: new Date().toISOString().slice(0, 10), tripped: [] }, 'outbox');
+  const refused = verdict.rows.filter((r) => r.verdict === 'block').map((r) => lines[r.id].trim());
+  return { ok: refused.length === 0, refused, rows: verdict.rows, send: verdict.send };
+}
+
+function draftOutbox({ channel, recipient, subject, body, origin } = {}) {
+  if (!CHANNELS.includes(channel)) throw new Error('unknown channel: ' + channel);
+  if (!ORIGINS.includes(origin)) throw new Error("origin must be 'agent' or 'pm'");
+  if (typeof body !== 'string' || !body.trim()) throw new Error('body required');
+  const e = { channel, recipient: recipient || null, subject: subject || '', body, origin };
+  return { ...e, state: claimCheck(e).ok ? 'queued' : 'blocked', hash: entryHash(e) };
+}
+
+// New entry, new hash. The old hash is voided: confirmOutbox compares against the entry it is given.
+function editOutbox(entry, { body } = {}) {
+  if (typeof body !== 'string' || !body.trim()) throw new Error('body required');
+  const e = { ...entry, body };
+  return { ...e, state: claimCheck(e).ok ? 'queued' : 'blocked', hash: entryHash(e) };
+}
+
+// The PM's press. A blocked entry (a claim fails the trust rules) needs a written reason, which is the override.
+function confirmOutbox(entry, { hash, by, reason } = {}, senders = SENDERS) {
+  if (by !== 'pm') return { ok: false, reason: 'agent cannot confirm' };
+  if (hash !== entry.hash || entryHash(entry) !== entry.hash) return { ok: false, reason: 'hash does not match the content' };
+  const override = !claimCheck(entry).ok;
+  if (override && !String(reason || '').trim()) return { ok: false, reason: 'blocked by claims check: a written reason is required to override' };
+  if (typeof senders[entry.channel] !== 'function') return { ok: false, reason: 'no channel connected' };
+  return { ok: true, hash: entry.hash, override, reason: reason || null };
+}
+
+// Kept for older callers: true when every claim line passes the trust rules.
+const claimLabelsOK = (entry) => claimCheck(entry).ok;
+
+// The send step is a stub. No network, no connector. A real send goes through scripts/trust/outbox.js execute (see workspace/lib/outbox-store.js).
+function sendOutbox() {
+  return { sent: false, reason: 'no channel connected' };
+}
+
+// Generic append-only line writer shared by brakes.js, card-state and the run routes.
+function appendOutbox(file, event, now = new Date()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify({ ...event, at: now.toISOString() }) + '\n');
+}
+
+module.exports = { CHANNELS, hashOf, entryHash, claimCheck, draftOutbox, editOutbox, confirmOutbox, claimLabelsOK, sendOutbox, appendOutbox };