create-pmos 0.22.0 → 0.23.0

package/payload/scripts/workflow-sweep.js

@@ -0,0 +1,764 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS workflow sweep — find the state that misreports, and repair only what is mechanical.
+ *
+ *   node scripts/workflow-sweep.js                 the sweep, human-readable
+ *   node scripts/workflow-sweep.js --json          machine-readable
+ *   node scripts/workflow-sweep.js --fix           apply every repairable finding
+ *   node scripts/workflow-sweep.js --fix --dry-run print what --fix would write, write nothing
+ *   node scripts/workflow-sweep.js --gate          exit 1 while any DEFECT remains
+ *   node scripts/workflow-sweep.js --owed          the PM worklist only
+ *   node scripts/workflow-sweep.js --root <dir>    sweep another repo (tenant, kit, fixture)
+ *   node scripts/workflow-sweep.js <id>            one initiative
+ *
+ * WHY THIS EXISTS. The workflow surfaces are derived, which makes them self-maintaining and does
+ * NOT make them self-correcting. A derivation is only as true as what it reads, and nothing audited
+ * what it reads. On this repository that meant four manufactured acceptance rows written by a test
+ * suite into the file that records the non-delegable D12 gate; two colliding `run_id`s in a ledger
+ * whose readers build id→row maps; a merged branch with no record; and twenty-four records whose
+ * `parent_kr` prose was truncated mid-write. Every one of those is invisible on every surface,
+ * because a surface derived from damaged inputs reports confidently from the damage.
+ *
+ * ── THE ONE DISTINCTION THIS TOOL IS BUILT AROUND ────────────────────────────────────────────
+ *
+ *   A DEFECT is state that CONTRADICTS REALITY or cannot be read. The board is lying. This is the
+ *   sweep's business, and where the repair is mechanical, its repair.
+ *
+ *   An OWED finding is work that HONESTLY HAS NOT HAPPENED. 53 of this repository's 65 merged
+ *   initiative branches have no run row and 49 have no acceptance. That is not corrupt data — it is
+ *   an open loop, and it is the largest population here by an order of magnitude.
+ *
+ * They never share a bucket. Collapsing them fails in both directions at once: it buries four real
+ * defects inside fifty-three ordinary open items, and it licenses the tool to "fix" the fifty-three
+ * by writing the missing rows.
+ *
+ * ── WHAT THIS TOOL WILL NOT DO, EVER ─────────────────────────────────────────────────────────
+ *
+ * It will not write a run, an eval verdict, an acceptance, a `pre_run_contract` approval, a
+ * `specimen_test` answer, a `surface_check` answer, or a `delivered_by`. Those are judgements — the
+ * PM's or the evaluator's — and a tool that manufactures them produces a perfectly green board out
+ * of evidence nobody produced. That is not a hypothetical failure mode: it is the single most
+ * attractive shortcut available to this program, it would satisfy every count in the PRD, and it
+ * would be the most complete watermelon PMOS has ever shipped.
+ *
+ * What it repairs is POINTERS AND DAMAGED TEXT — facts about where a file is and what a truncated
+ * line said. A repair that requires choosing between two plausible candidates is not mechanical, and
+ * is reported rather than guessed. `--fix` writes only to initiative records; it never touches a
+ * `.jsonl`, because the ledgers are append-only and a sweep that edits history is not a sweep.
+ *
+ * Zero dependencies, stock Node. It runs in CI, in a terminal, and against a vendored kit.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const engine = require('./workflow-state');
+const anchors = require('./anchor-resolve');
+const delivery = require('./delivery-index');
+
+// ── severity ───────────────────────────────────────────────────────────────────────────────────
+const DEFECT = 'defect';
+const OWED = 'owed';
+
+/*
+ * The finding classes, in one table, so the split cannot drift into the code that produces them.
+ * `repairable` is a property of the CLASS, not of an individual finding: a class either has a
+ * mechanical repair or it does not, and adding one is a decision rather than a convenience.
+ */
+const CLASSES = {
+  'torn-ledger-line': { severity: DEFECT, repairable: false, why: 'a ledger line that does not parse is dropped by every reader — a truncated acceptance reads as "never accepted"' },
+  'orphan-ledger-row': { severity: DEFECT, repairable: false, why: 'a row naming no record reports state for an initiative that does not exist' },
+  'duplicate-run-id': { severity: DEFECT, repairable: false, why: 'both the contract and priors rungs build id→row maps; a collision silently loses a row, and append-only has no rule for which supersedes' },
+  'dangling-path': { severity: DEFECT, repairable: true, why: 'the record points at a file that is not there, so the rung reading it reports on nothing' },
+  'damaged-field': { severity: DEFECT, repairable: true, why: 'a frontmatter value truncated mid-write renders cut off wherever it is shown; only git can restore the lost text, and where it cannot this is a human\'s line to finish' },
+  'missing-record': { severity: DEFECT, repairable: true, why: 'work merged with no record is invisible to every board and to the gate' },
+  'unresolvable-anchor': { severity: DEFECT, repairable: false, why: 'the anchor names something the OKR documents do not declare (D59)' },
+  'unverifiable-delivery': { severity: DEFECT, repairable: false, why: 'delivered_by names a commit the trunk cannot reach, or one that changes no build path (R-2b)' },
+  'delivered-unlogged': { severity: OWED, repairable: false, why: 'the trunk attributes work to this initiative and no run was ever logged (AGENTS.md step 7)' },
+  'delivered-unreviewed': { severity: OWED, repairable: false, why: 'delivered against a rubric with no Review-Gate verdict recorded — a skipped gate is recorded as skipped, never left absent' },
+  'delivered-unaccepted': { severity: OWED, repairable: false, why: 'delivered with no acceptance row — the D12 gate is open' },
+  'unexplained-run': { severity: OWED, repairable: false, why: 'a logged run with no explainer; raw-transcript vigilance degrades within ~30 min (O6)' },
+};
+
+function finding(cls, o) {
+  const meta = CLASSES[cls];
+  if (!meta) throw new Error(`workflow-sweep: unknown finding class '${cls}' — add it to CLASSES with its severity and whether it is repairable`);
+  return {
+    class: cls,
+    severity: meta.severity,
+    repairable: meta.repairable,
+    id: o.id || null,
+    file: o.file || null,
+    line: o.line == null ? null : o.line,
+    what: o.what,
+    evidence: o.evidence || null,
+    // Every finding says either how it is repaired or why it cannot be. A finding with neither is a
+    // dead end presented as information.
+    repair: o.repair || null,
+    hand: o.hand || (meta.repairable ? null : meta.why),
+  };
+}
+
+// ── reading ────────────────────────────────────────────────────────────────────────────────────
+
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+/** Every non-blank line of a ledger, parsed or reported. Never both, never neither. */
+function readLedger(abs) {
+  const rel = abs;
+  let text;
+  try { text = fs.readFileSync(abs, 'utf8'); } catch { return { present: false, rows: [], torn: [] }; }
+  const rows = [];
+  const torn = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (!t) continue;
+    try { rows.push({ row: JSON.parse(t), line: i + 1 }); }
+    catch (e) { torn.push({ file: rel, line: i + 1, reason: String((e && e.message) || 'not valid JSON').slice(0, 120), text: t.slice(0, 160) }); }
+  }
+  return { present: true, rows, torn };
+}
+
+/*
+ * A frontmatter value is DAMAGED when it was truncated mid-write: an opening bracket or quote that
+ * never closes on the same value.
+ *
+ * The test is deliberately narrow. Prose in these fields is normal and encouraged — the router's
+ * answers are reasoning, not enum tokens — so "looks unfinished" is not something to guess at. An
+ * unbalanced delimiter is different: it is a fact about the text, decidable without judgement, and
+ * it is what the twenty-four damaged records in this repository actually have.
+ */
+function damagedValue(v) {
+  const s = String(v == null ? '' : v);
+  if (!s.trim()) return null;
+  const opens = (s.match(/\(/g) || []).length;
+  const closes = (s.match(/\)/g) || []).length;
+  if (opens > closes) return { kind: 'paren', missing: opens - closes };
+  // A value that opens with a quote and does not close it — the YAML would have swallowed the rest.
+  if (/^"/.test(s.trim()) && !/"\s*$/.test(s.trim())) return { kind: 'quote', missing: 1 };
+  return null;
+}
+
+/** The conventional locations a lane's spec artifact is written to, for the dangling-path repair. */
+function candidatesFor(root, L, key, id) {
+  const kitish = L.kit;
+  const dirs = {
+    prd_path: kitish ? ['planning/prd'] : ['planning/prd', 'planning/briefs', 'planning/research'],
+    rubric_path: ['planning/evals'],
+    explainer_path: kitish ? ['pmos/state/explainers'] : ['planning/explainers', 'planning/evals/explainers'],
+  }[key] || [];
+  const names = {
+    prd_path: [`${id}-prd.md`, `${id}-spec.md`, `${id}-brief.md`, `${id}.md`],
+    rubric_path: [`${id}-eval-rubric.md`, `${id}-rubric.md`],
+    explainer_path: [`${id}-surface-explainer.md`, `${id}-explainer.md`],
+  }[key] || [];
+  const out = [];
+  for (const d of dirs) for (const n of names) {
+    const rel = `${d}/${n}`;
+    if (fs.existsSync(path.join(root, rel))) out.push(rel);
+  }
+  return [...new Set(out)];
+}
+
+// ── the sweep ──────────────────────────────────────────────────────────────────────────────────
+
+function sweep(opts) {
+  const root = path.resolve((opts && opts.root) || process.cwd());
+  const L = engine.layout(root);
+  const only = opts && opts.id;
+  const findings = [];
+  const notes = [];
+
+  const ids = engine.listInitiatives(root);
+  /*
+   * ABSENT and EMPTY are different facts and must not share an answer — the same rule the workspace
+   * applies to a ladder read. A freshly vendored kit HAS a `state/initiatives/` directory with
+   * nothing in it yet, and telling that adopter "is this a PMOS repo?" on their first run is the
+   * tool being wrong about a repository that is perfectly correct. A missing directory is the real
+   * "you pointed me somewhere else" case, and only it gets the error.
+   */
+  if (!ids.length) {
+    if (!fs.existsSync(L.initiatives)) {
+      return { ok: false, root, error: `no initiatives directory at ${path.relative(root, L.initiatives) || L.initiatives} — this does not look like a PMOS repo (use --root to point at one)`, findings: [], notes: [] };
+    }
+    return {
+      ok: true, root, lane_layout: L.kit ? 'kit' : 'pmos-self', initiatives: 0, empty: true,
+      findings: [], defects: [], owed: [], repairable: 0, delivery_read: null,
+      notes: [`no initiative records yet under ${path.relative(root, L.initiatives)} — nothing to sweep, which is a clean result rather than a failed read`],
+    };
+  }
+  const idset = new Set(ids);
+
+  // ── the ledgers, read once ────────────────────────────────────────────────────────────────────
+  const ledgerFiles = {
+    runs: path.join(L.runsDir, L.runsFile),
+    evals: path.join(L.runsDir, 'evals.jsonl'),
+    acceptances: path.join(L.runsDir, 'acceptances.jsonl'),
+  };
+  const ledgers = {};
+  for (const [name, abs] of Object.entries(ledgerFiles)) {
+    const led = readLedger(abs);
+    ledgers[name] = led;
+    const rel = path.relative(root, abs);
+    if (!led.present) { notes.push(`${rel} is not present — no rows to sweep`); continue; }
+
+    for (const t of led.torn) {
+      findings.push(finding('torn-ledger-line', {
+        file: rel, line: t.line,
+        what: `${rel}:${t.line} does not parse and is silently dropped by every reader`,
+        evidence: `${t.reason} — ${t.text}`,
+      }));
+    }
+    // A row naming an initiative with no record. Reported, never removed: the ledgers are
+    // append-only, and a sweep that deletes rows to make its own output clean is the worst possible
+    // version of this tool.
+    for (const { row, line } of led.rows) {
+      const iid = row && row.initiative_id;
+      if (iid && !idset.has(iid)) {
+        findings.push(finding('orphan-ledger-row', {
+          id: iid, file: rel, line,
+          what: `${rel}:${line} records ${name === 'acceptances' ? 'an acceptance' : name === 'evals' ? 'an eval' : 'a run'} for '${iid}', which has no initiative record`,
+          evidence: JSON.stringify(row).slice(0, 200),
+          hand: name === 'acceptances'
+            ? 'an acceptance naming no initiative records the non-delegable D12 gate against nothing — the PM decides whether it is annotated or the record is created'
+            : CLASSES['orphan-ledger-row'].why,
+        }));
+      }
+    }
+  }
+  // Duplicate run ids — checked across the runs ledger only, where run_id is the identity every
+  // other rung dereferences.
+  {
+    const seen = new Map();
+    for (const { row, line } of ledgers.runs.rows) {
+      const rid = row && row.run_id;
+      if (!rid) continue;
+      if (seen.has(rid)) {
+        findings.push(finding('duplicate-run-id', {
+          id: row.initiative_id || null, file: path.relative(root, ledgerFiles.runs), line,
+          what: `run_id '${rid}' appears twice (lines ${seen.get(rid)} and ${line})`,
+          evidence: 'the contract and priors rungs dereference run_id through a Map — last write wins, so one of these rows is invisible to both',
+        }));
+      } else seen.set(rid, line);
+    }
+  }
+
+  const runsBy = new Map();
+  for (const { row } of ledgers.runs.rows) {
+    if (!row || !row.initiative_id) continue;
+    if (!runsBy.has(row.initiative_id)) runsBy.set(row.initiative_id, []);
+    runsBy.get(row.initiative_id).push(row);
+  }
+  const evalIds = new Set(ledgers.evals.rows.map(({ row }) => row && row.initiative_id).filter(Boolean));
+  const acceptedIds = new Set(ledgers.acceptances.rows
+    .filter(({ row }) => row && (row.accepted === true || row.action === 'approve'))
+    .map(({ row }) => row.initiative_id).filter(Boolean));
+
+  // ── delivery, read once ───────────────────────────────────────────────────────────────────────
+  const del = delivery.deliveryIndex(root, ids);
+  if (!del.ok) {
+    // Not silence, and not a wall of false findings either: without the trunk, every delivery-derived
+    // class is undecidable, so they are skipped and the skip is REPORTED. A sweep that reported
+    // "0 delivered-unlogged" here would be claiming the loop is closed on evidence it never read.
+    notes.push(`delivery could not be derived — ${del.reason}. The delivered-* classes were NOT evaluated; this is not a clean result for them.`);
+  }
+
+  // ── merged branches with no record ────────────────────────────────────────────────────────────
+  // `mergedBranches`, NOT the attribution index's `byBranch`. This finding RE-CREATES something from
+  // its match, and the attribution set is deliberately broad enough to include ids quoted inside a
+  // commit body — which on this repository would have written records for `foo`, `save_okr` and
+  // `pmos-operating-guide.`, three tokens that appear in prose and name nothing. A repair tool that
+  // invents initiatives out of code examples is worse than one that misses a real gap.
+  if (!only) {
+    const merged = delivery.mergedBranches(root);
+    if (!merged.ok) notes.push(`merged branches could not be read — ${merged.reason}. The missing-record class was NOT evaluated.`);
+    for (const [b, m] of merged.ids || []) {
+      if (idset.has(b)) continue;
+      const when = m.at ? new Date(m.at * 1000).toISOString().slice(0, 10) : null;
+      findings.push(finding('missing-record', {
+        id: b,
+        what: `an initiative/${b} branch merged to the trunk and there is no record at ${path.relative(root, path.join(L.initiatives, `${b}.md`))}`,
+        evidence: `${(m.sha || '').slice(0, 8)} ${m.subject}`.trim().slice(0, 160),
+        // `back` travels with the repair so the record can say which evidence it had. A back-merge
+        // subject describes housekeeping, not the work, and quoting it as an initiative's title
+        // would put a sentence about merging main into the title slot of the thing that shipped.
+        repair: {
+          kind: 'reconstruct-record', id: b, merged: when,
+          sha: m.sha ? m.sha.slice(0, 8) : null,
+          title: m.back ? null : (m.subject || null),
+          evidence_kind: m.back ? 'back-merge' : 'landing-merge',
+          subject: m.subject || null,
+        },
+      }));
+    }
+  }
+
+  // ── per record ────────────────────────────────────────────────────────────────────────────────
+  for (const id of ids) {
+    if (only && id !== only) continue;
+    const recAbs = path.join(L.initiatives, `${id}.md`);
+    const recRel = path.relative(root, recAbs);
+    let text;
+    try { text = fs.readFileSync(recAbs, 'utf8'); } catch { continue; }
+    const fm = engine.parseLeadingFrontmatter(text);
+    const lane = (fm.lane || 'feature').trim() || 'feature';
+
+    // dangling declared paths
+    for (const key of ['prd_path', 'rubric_path', 'explainer_path']) {
+      const v = String(fm[key] || '').trim();
+      if (!v) continue;
+      if (fs.existsSync(path.join(root, v))) continue;
+      const cands = candidatesFor(root, L, key, id);
+      findings.push(finding('dangling-path', {
+        id, file: recRel,
+        what: `${key} points at '${v}', which is not in the repository`,
+        evidence: cands.length ? `candidate(s) at the conventional location: ${cands.join(', ')}` : 'no file at any conventional location for this key',
+        // Exactly one candidate is mechanical. Two is a choice, and a choice is not this tool's.
+        repair: cands.length === 1 ? { kind: 'repoint', file: recRel, key, from: v, to: cands[0] } : null,
+        hand: cands.length > 1
+          ? `${cands.length} candidates exist (${cands.join(', ')}) — choosing between them is a judgement, so it is reported rather than guessed`
+          : cands.length === 0
+            ? 'no candidate exists — the artifact was never written, or lives somewhere no convention names. Write it, or clear the key: optional never means dangling'
+            : null,
+      }));
+    }
+
+    // damaged frontmatter values
+    for (const [key, v] of Object.entries(fm)) {
+      const dmg = damagedValue(v);
+      if (!dmg) continue;
+      // The repair is a RESTORATION or it is nothing. Closing the bracket would balance the YAML and
+      // assert an ending the text does not have — `…the meta-watermelon made computab)` reads as a
+      // finished sentence that is missing its last four words. Only git can say what the value used
+      // to be, so only git may supply it; where it cannot, this is a human's line to finish.
+      const restored = recoverFromHistory(root, recRel, key, String(v));
+      findings.push(finding('damaged-field', {
+        id, file: recRel,
+        what: `${key} is truncated — ${dmg.kind === 'paren' ? `${dmg.missing} unclosed parenthes${dmg.missing > 1 ? 'es' : 'is'}` : 'an unclosed quote'}`,
+        evidence: String(v).slice(0, 120),
+        repair: restored ? { kind: 'restore-from-git', file: recRel, key, from: String(v), to: restored.value, sha: restored.sha } : null,
+        hand: restored ? null
+          : 'the intact value is not in this file\'s git history, so the lost text cannot be recovered mechanically. Closing the bracket alone would assert an ending the sentence does not have — finish the line yourself',
+      }));
+    }
+
+    // the anchor
+    {
+      const raw = String(fm.parent_kr || '').trim();
+      const r = anchors.resolveAnchor(raw, engineOkrIndex(root), budgetsFor(root, L));
+      if (r.status === 'unresolvable' || r.status === 'empty') {
+        findings.push(finding('unresolvable-anchor', {
+          id, file: recRel,
+          what: r.status === 'empty' ? 'parent_kr is empty — unanchored work is rejected (D59)' : `parent_kr '${raw.slice(0, 60)}' resolves to nothing`,
+          evidence: r.reason || null,
+        }));
+      }
+    }
+
+    // a declared delivery that does not check out
+    {
+      const dd = delivery.declaredDelivery(root, fm.delivered_by);
+      if (dd.declared && !dd.ok && !dd.unknown) {
+        findings.push(finding('unverifiable-delivery', {
+          id, file: recRel,
+          what: dd.reason,
+          evidence: `delivered_by: ${String(fm.delivered_by).slice(0, 100)}`,
+        }));
+      }
+    }
+
+    // ── owed ────────────────────────────────────────────────────────────────────────────────────
+    // Everything below is real work that has not happened. None of it is repairable, by design, and
+    // the reason is written on each finding rather than only in this file's header — the person
+    // reading the output is the one who needs to know why the tool stopped.
+    const signal = del.ok ? delivery.attribution(del, id) : 'unknown';
+    const declaredOk = delivery.declaredDelivery(root, fm.delivered_by).ok === true;
+    const delivered = del.ok && (!!signal || declaredOk);
+    const runs = runsBy.get(id) || [];
+
+    if (delivered) {
+      const how = declaredOk ? 'declared' : signal;
+      if (!runs.length) {
+        findings.push(finding('delivered-unlogged', {
+          id, file: recRel,
+          what: 'work is attributable to this initiative on the trunk and no run was ever logged',
+          evidence: delivery.attributionEvidence(how, id),
+          hand: 'append the run to the ledger yourself (AGENTS.md step 7). The sweep will not write it: a run row carries a pre_run_contract and a human_corrections count, and inventing either fabricates the north-star signal it feeds',
+        }));
+      }
+      if (String(fm.rubric_path || '').trim() && !evalIds.has(id)) {
+        findings.push(finding('delivered-unreviewed', {
+          id, file: recRel,
+          what: 'delivered against a rubric with no Review-Gate verdict recorded',
+          evidence: `rubric_path: ${fm.rubric_path}`,
+          hand: 'score it (build-skills/evaluator.skill) or record it as SKIPPED — a gate that was skipped is recorded as skipped, and the sweep cannot score anything without being the evaluator it is auditing',
+        }));
+      }
+      if (!acceptedIds.has(id)) {
+        findings.push(finding('delivered-unaccepted', {
+          id, file: recRel,
+          what: 'delivered with no acceptance row — the D12 gate is open',
+          evidence: delivery.attributionEvidence(how, id),
+          hand: 'the Acceptance Gate is the PM\'s and is non-delegable (D12). This is the one finding the sweep is structurally forbidden from closing',
+        }));
+      }
+    }
+
+    for (const r of runs) {
+      if (!r.run_id) continue;
+      const expl = path.join(L.explainers, `${r.run_id}-explainer.md`);
+      if (fs.existsSync(expl)) continue;
+      findings.push(finding('unexplained-run', {
+        id, file: recRel,
+        what: `run ${r.run_id} has no explainer at ${path.relative(root, expl)}`,
+        evidence: 'O6 — the explainer is what the PM reviews; raw-transcript vigilance degrades within ~30 min',
+      }));
+    }
+  }
+
+  const defects = findings.filter((f) => f.severity === DEFECT);
+  const owed = findings.filter((f) => f.severity === OWED);
+  return {
+    ok: true, root, lane_layout: L.kit ? 'kit' : 'pmos-self',
+    initiatives: ids.length,
+    findings, defects, owed, notes,
+    repairable: defects.filter((f) => f.repair).length,
+    delivery_read: del.ok ? null : del.reason,
+  };
+}
+
+// Cached the same way the engine caches them — the sweep derives over every record in one pass.
+const _okr = new Map();
+function engineOkrIndex(root) {
+  if (!_okr.has(root)) _okr.set(root, anchors.parseOkrIndex(root));
+  return _okr.get(root);
+}
+const _bud = new Map();
+function budgetsFor(root, L) {
+  if (!_bud.has(root)) {
+    try { _bud.set(root, { ok: true, text: fs.readFileSync(L.budgets, 'utf8'), path: path.relative(root, L.budgets) }); }
+    catch { _bud.set(root, { ok: false, text: '', path: path.relative(root, L.budgets) }); }
+  }
+  return _bud.get(root);
+}
+
+/*
+ * The intact value, if this file's own history holds one — the only mechanical repair for truncated
+ * text that is a FACT rather than a guess.
+ *
+ * The test is strict and one-directional: an earlier version of the same key, in the same file,
+ * whose text STARTS WITH the damaged text and is longer, and which is not itself damaged. A value
+ * that merely differs is a rewrite, not a restoration, and reverting a deliberate edit under the
+ * banner of "repair" would be the tool overwriting the PM.
+ *
+ * On this repository it finds nothing: the 26 damaged values were truncated by whatever wrote them,
+ * so no intact version was ever committed. That is the correct outcome and the sweep says so on each
+ * finding, rather than reaching for the delimiter it could balance instead.
+ */
+function recoverFromHistory(root, rel, key, damaged) {
+  const dmg = damaged.trim();
+  if (!dmg) return null;
+  const log = git(root, ['log', '--format=%H', '--', rel]);
+  if (!log) return null;
+  const shas = log.split('\n').map((s) => s.trim()).filter(Boolean).slice(0, 40);
+  for (const sha of shas) {
+    const text = git(root, ['show', `${sha}:${rel}`]);
+    if (!text) continue;
+    const past = engine.parseLeadingFrontmatter(text)[key];
+    if (past == null) continue;
+    const p = String(past).trim();
+    if (p === dmg || p.length <= dmg.length) continue;
+    if (!p.startsWith(dmg)) continue;
+    if (damagedValue(p)) continue;                 // an earlier damaged version is not a restoration
+    return { value: p, sha };
+  }
+  return null;
+}
+
+// ── repair ─────────────────────────────────────────────────────────────────────────────────────
+/*
+ * The closed repair set. Three kinds, and each is a fact rather than a judgement:
+ *   repoint            — the file is at the conventional location and the pointer is stale
+ *   close-delimiter    — the text was truncated mid-write and the missing character is decidable
+ *   reconstruct-record — a merge exists with no record; the record states it was reconstructed
+ *
+ * Nothing here writes a `.jsonl`, and nothing writes a value that expresses an opinion. The
+ * reconstructed record carries `lane: chore` with a stated intent rather than a guessed lane and a
+ * pointer at a spec that does not exist, and `reconstructed_from` rather than a backdated timestamp,
+ * so it can never read as though it followed the loop.
+ */
+function applyRepairs(res, opts) {
+  const dry = !!(opts && opts.dryRun);
+  const root = res.root;
+  const L = engine.layout(root);
+  const applied = [];
+  const skipped = [];
+
+  // Group by file so multiple field repairs on one record are a single read/write.
+  const byFile = new Map();
+  for (const f of res.defects) {
+    if (!f.repair) continue;
+    const key = f.repair.kind === 'reconstruct-record' ? `__new__${f.repair.id}` : f.repair.file;
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(f);
+  }
+
+  for (const [key, group] of byFile) {
+    if (key.startsWith('__new__')) {
+      for (const f of group) {
+        const r = f.repair;
+        const abs = path.join(L.initiatives, `${r.id}.md`);
+        const rel = path.relative(root, abs);
+        if (fs.existsSync(abs)) { skipped.push({ finding: f, why: 'a record now exists at that path' }); continue; }
+        const body = reconstructedRecord(r);
+        if (!dry) fs.writeFileSync(abs, body, 'utf8');
+        applied.push({ class: f.class, file: rel, before: '(no file)', after: `a reconstructed record, lane chore, reconstructed_from: ${r.merged || 'unknown'}` });
+      }
+      continue;
+    }
+    const abs = path.join(root, key);
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); }
+    catch { for (const f of group) skipped.push({ finding: f, why: `${key} could not be read` }); continue; }
+    let next = text;
+    for (const f of group) {
+      const r = f.repair;
+      const before = frontmatterValue(next, r.key);
+      if (before === null) { skipped.push({ finding: f, why: `${r.key} is no longer in the frontmatter` }); continue; }
+      let after;
+      if (r.kind === 'repoint') {
+        if (before.trim() !== r.from) { skipped.push({ finding: f, why: `${r.key} changed since the sweep ran` }); continue; }
+        after = r.to;
+      } else if (r.kind === 'restore-from-git') {
+        if (before.trim() !== r.from.trim()) { skipped.push({ finding: f, why: `${r.key} changed since the sweep ran` }); continue; }
+        after = r.to;
+      } else { skipped.push({ finding: f, why: `unknown repair kind '${r.kind}'` }); continue; }
+      next = setFrontmatterValue(next, r.key, after);
+      applied.push({ class: f.class, file: key, key: r.key, before: before.slice(0, 90), after: after.slice(0, 90) });
+    }
+    if (next !== text && !dry) fs.writeFileSync(abs, next, 'utf8');
+  }
+  return { applied, skipped, dry };
+}
+
+/** The LEADING frontmatter only, matching every other reader in this repo. */
+function frontmatterValue(text, key) {
+  const lines = String(text).split('\n');
+  for (const line of lines) {
+    const m = line.match(/^([a-z_]+):\s*(.*?)\s*$/);
+    if (m && m[1] === key) return m[2];
+    if (line.trim() && !line.startsWith('---') && !m) break;
+  }
+  return null;
+}
+function setFrontmatterValue(text, key, value) {
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^([a-z_]+):\s*(.*?)\s*$/);
+    if (m && m[1] === key) { lines[i] = `${key}: ${value}`; return lines.join('\n'); }
+    if (lines[i].trim() && !lines[i].startsWith('---') && !m) break;
+  }
+  return text;
+}
+
+/*
+ * A record for work that merged without one. It is deliberately the MINIMUM that makes the work
+ * visible, and it states its own provenance in three places — `reconstructed_from`, the `status`
+ * intent, and the body — because the one thing a reconstruction must never do is read as though
+ * somebody wrote it at intake.
+ *
+ * `lane: chore` is not a guess about how large the work was. It is the only lane whose spec artifact
+ * is a sentence in the record itself, so it is the only lane a reconstruction can satisfy honestly:
+ * every other lane would need a `prd_path` pointing at a document nobody wrote.
+ */
+function reconstructedRecord(r) {
+  const back = r.evidence_kind === 'back-merge';
+  // With no landing-merge subject there is no honest title to quote, so the record says what it
+  // knows instead of borrowing a sentence about something else.
+  const title = (r.title || `${r.id} — reconstructed from git; no landing-merge subject exists`)
+    .replace(/"/g, '\'').slice(0, 160);
+  const when = r.merged || 'unknown';
+  const evidenceLine = back
+    ? `- evidence: a **back-merge** (\`${(r.subject || '').replace(/`/g, '').slice(0, 90)}\`) reachable from the trunk. That commit is only
+  reachable at all because this branch was later merged in, so it proves the branch landed — but it
+  describes merging main INTO the branch, so its subject is not this work's title and its date is
+  the housekeeping's, not the delivery's. A squash merge left no landing subject to read.`
+    : `- evidence: the landing merge's own subject, quoted verbatim above`;
+  return `---
+type: Initiative
+title: "${title}"
+timestamp: ${new Date().toISOString().slice(0, 10)}
+id: ${r.id}
+lane: chore
+parent_kr: health:tech
+reconstructed_from: ${when}
+status: "RECONSTRUCTED by scripts/workflow-sweep.js from the merge, not authored at intake. No spec artifact was ever written for this work; the chore lane records that rather than pointing at a document which does not exist. The anchor is the D59 tech budget because no honest KR can be inferred after the fact — correct it here if you know better."
+---
+
+# Initiative: ${r.id}
+
+**This record was reconstructed from git, not written at intake.** An \`initiative/${r.id}\` branch
+merged to the trunk with no record in the repository, so the work was invisible to the Initiative
+Gate, to [\`scripts/workflow-state.js\`](/scripts/workflow-state.js), and to every board.
+
+- merged: **${when}**${r.sha ? ` (\`${r.sha}\`)` : ''}${back ? ' — the back-merge\'s date; the landing date is not recoverable' : ''}
+- anchor: \`health:tech\` — reconstructed after the fact, D59 tech budget, no honest KR
+- lane: \`chore\` — the only lane whose spec artifact is a sentence in this record; every other lane
+  would need a \`prd_path\` pointing at a document nobody wrote
+${evidenceLine}
+
+*Nothing here has been reconstructed from memory, and no run, eval or acceptance was written on this
+initiative's behalf. Set \`delivered_by:\` to the commit this work actually landed in if you know it —
+the ladder checks that against the trunk.*
+`;
+}
+
+// ── rendering ──────────────────────────────────────────────────────────────────────────────────
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+const brief = (s, n) => {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+function render(res, opts) {
+  if (!res.ok) return c(31, `✗ ${res.error}`);
+  const out = [''];
+  const D = res.defects.length;
+  const O = res.owed.length;
+  out.push(`  ${c(1, 'PMOS workflow sweep')} · ${res.initiatives} initiatives · ${res.lane_layout} layout`);
+  out.push(`  ${D ? c(31, `${D} defect${D === 1 ? '' : 's'}`) : c(32, 'no defects')} — state that contradicts reality or cannot be read${res.repairable ? c(33, ` · ${res.repairable} repairable with --fix`) : ''}`);
+  out.push(`  ${O ? c(33, `${O} owed`) : c(32, 'nothing owed')} — work that honestly has not happened. ${c(90, 'Never repaired: see --owed')}`);
+  out.push(`  ${c(90, '─'.repeat(94))}`);
+
+  const show = (list, heading, colour) => {
+    if (!list.length) return;
+    out.push('');
+    out.push(`  ${c(colour, heading)}`);
+    const byClass = new Map();
+    for (const f of list) {
+      if (!byClass.has(f.class)) byClass.set(f.class, []);
+      byClass.get(f.class).push(f);
+    }
+    for (const [cls, group] of byClass) {
+      out.push(`  ${c(1, cls)} ${c(90, `× ${group.length}`)} ${c(90, `— ${CLASSES[cls].why}`)}`);
+      const cap = opts && opts.all ? group.length : 6;
+      for (const f of group.slice(0, cap)) {
+        out.push(`    ${c(colour, '•')} ${c(1, (f.id || f.file || '').padEnd(34))} ${brief(f.what, 96)}`);
+        if (f.evidence) out.push(`      ${c(90, brief(f.evidence, 108))}`);
+        if (f.repair) out.push(`      ${c(32, '→ repairable')} ${c(90, repairSentence(f.repair))}`);
+        else if (f.hand) out.push(`      ${c(33, '→ by hand')} ${c(90, brief(f.hand, 104))}`);
+      }
+      // Never a silent cap — a truncated list that does not say so reads as "that is everything".
+      if (group.length > cap) out.push(`    ${c(33, `+ ${group.length - cap} more ${cls}, not shown`)} ${c(90, '— --all')}`);
+    }
+  };
+
+  if (!(opts && opts.owedOnly)) show(res.defects, 'DEFECTS — the board is lying about these', 31);
+  if (!(opts && opts.defectsOnly)) show(res.owed, 'OWED — real work, honestly not done. The sweep reports these and will not close them.', 33);
+
+  for (const n of res.notes) out.push(`\n  ${c(33, '!')} ${n}`);
+  out.push('');
+  if (!D && !O) out.push(`  ${c(32, 'nothing to sweep — every record and every ledger row checks out.')}`);
+  else if (!D) out.push(`  ${c(32, 'no defects.')} ${c(90, `${O} owed item(s) are work, not damage.`)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+function repairSentence(r) {
+  if (r.kind === 'repoint') return `${r.key}: ${r.from} → ${r.to}`;
+  if (r.kind === 'restore-from-git') return `${r.key}: restore the intact value from ${String(r.sha).slice(0, 8)}`;
+  if (r.kind === 'reconstruct-record') return `write a reconstructed record (lane chore, reconstructed_from: ${r.merged || 'unknown'})`;
+  return r.kind;
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────────────
+function main(argv) {
+  const args = argv.slice(2);
+  let root = process.cwd();
+  let json = false; let fix = false; let dryRun = false; let gate = false;
+  let owedOnly = false; let defectsOnly = false; let all = false;
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--root') { root = args[++i]; continue; }
+    if (a === '--json') { json = true; continue; }
+    if (a === '--fix') { fix = true; continue; }
+    if (a === '--dry-run') { dryRun = true; continue; }
+    if (a === '--gate') { gate = true; continue; }
+    if (a === '--owed') { owedOnly = true; continue; }
+    if (a === '--defects') { defectsOnly = true; continue; }
+    if (a === '--all') { all = true; continue; }
+    if (a === '--help' || a === '-h') {
+      process.stdout.write([
+        '', '  node scripts/workflow-sweep.js [<initiative-id>] [--json] [--fix [--dry-run]] [--gate] [--owed|--defects] [--all] [--root <dir>]', '',
+        '    (no id)     sweep every initiative and every ledger row',
+        '    <id>        sweep one initiative',
+        '    --fix       apply the repairable DEFECTS. Never writes a .jsonl, never writes a judgement.',
+        '    --dry-run   with --fix: print what would be written, write nothing',
+        '    --gate      CI mode — exit 1 while any defect remains. Owed findings never fail it.',
+        '    --owed      the PM worklist: real work, honestly not done',
+        '    --defects   only state that contradicts reality',
+        '    --all       do not cap each class at 6 rows',
+        '    --json      machine-readable', '',
+        '  defect = the board is lying · owed = the loop is open. They never share a bucket.', '',
+      ].join('\n') + '\n');
+      return 0;
+    }
+    rest.push(a);
+  }
+
+  const res = sweep({ root, id: rest[0] });
+  if (!res.ok) {
+    process.stdout.write((json ? JSON.stringify(res, null, 2) : render(res, {})) + '\n');
+    return 1;
+  }
+
+  let repairs = null;
+  if (fix) {
+    repairs = applyRepairs(res, { dryRun });
+    if (!json) {
+      const head = dryRun ? '  --fix --dry-run — nothing was written:' : '  --fix applied:';
+      process.stdout.write(`\n${c(1, head)}\n`);
+      if (!repairs.applied.length) process.stdout.write(`  ${c(90, 'no repairable defect found.')}\n`);
+      for (const a of repairs.applied) {
+        process.stdout.write(`  ${c(32, '✓')} ${a.file}${a.key ? ` [${a.key}]` : ''}\n      ${c(90, 'before:')} ${brief(a.before, 90)}\n      ${c(90, 'after: ')} ${brief(a.after, 90)}\n`);
+      }
+      for (const s of repairs.skipped) process.stdout.write(`  ${c(33, '·')} skipped ${s.finding.class} on ${s.finding.file || s.finding.id} — ${s.why}\n`);
+      process.stdout.write(`\n  ${c(90, 'repairs land as working-tree edits. Review the diff — the sweep never commits.')}\n`);
+    }
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ ...res, repairs }, null, 2) + '\n');
+  } else if (!fix || owedOnly || defectsOnly) {
+    process.stdout.write(render(res, { owedOnly, defectsOnly, all }));
+  } else {
+    process.stdout.write(render(res, { owedOnly, defectsOnly, all }));
+  }
+
+  // Owed findings NEVER fail the gate. 53 open loops is a worklist, and a gate that fails on a
+  // worklist is a gate everyone learns to bypass — which would cost the 4 real defects their alarm.
+  if (gate) return res.defects.length ? 1 : 0;
+  return 0;
+}
+
+module.exports = { sweep, applyRepairs, render, CLASSES, damagedValue, readLedger, frontmatterValue, setFrontmatterValue, DEFECT, OWED };
+
+/*
+ * `exitCode`, not `process.exit()`. `process.exit` tears the process down without waiting for stdout
+ * to drain, and when stdout is a PIPE — every CI invocation, every `| jq`, every test harness —
+ * writes larger than the pipe buffer are asynchronous. `--json` on this repository is ~65 KB, so it
+ * arrived TRUNCATED MID-STRING and parsed as invalid JSON, while an interactive run to a TTY looked
+ * perfect. Setting the code and letting the process end naturally flushes first.
+ */
+if (require.main === module) process.exitCode = main(process.argv);