create-pmos 0.38.4 → 0.38.5

package/payload/scripts/workflow-sweep.js

@@ -76,6 +76,11 @@ const CLASSES = {
   '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)' },
+  'unpointed-artifact': { severity: DEFECT, repairable: true, why: 'a document names this initiative and no path key in the record points at it, so the ladder reads the step as open over finished work (D77)' },
+  'lane-outside-profile': { severity: DEFECT, repairable: false, why: 'the record names a lane its repository profile does not offer, so the engine applies a different lane than the one written (D68, D77)' },
+  'acceptance-not-counted': { severity: DEFECT, repairable: false, why: 'an acceptances.jsonl row names an initiative and the ladder does not count it, so the ladder shows the gate open over a row that looks like an approval (D12)' },
+  'done-without-basis': { severity: DEFECT, repairable: false, why: 'a step reads done and names no file, ledger or commit history, so the pane has nothing to open (D77)' },
+  'status-claims-ahead': { severity: OWED, repairable: false, why: 'the record\'s status says accepted or complete while the ladder shows the acceptance step open' },
   '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' },
@@ -169,6 +174,43 @@ function candidatesFor(root, L, key, id) {
   return [...new Set(out)];
 }
 
+/*
+ * D77 — documents that name an initiative. The engine reads only the paths a record points at and
+ * never searches, so a finished PRD that no record points at leaves its step open. This is the search
+ * the engine does not do. It reads Markdown under the conventional document folders, skips the
+ * folders that hold control records, ledgers, rubrics and explainers, and matches on the file's
+ * `initiative_id` (frontmatter or a leading bullet) or on a name that starts with the id.
+ */
+const DOC_ROOTS = ['planning', 'docs', 'doc', 'prd', 'prds', 'briefs', 'specs', 'strategy', 'plans', 'reports', 'decisions', 'requirements', 'product'];
+const DOC_SKIP = new Set(['node_modules', '.git', 'initiatives', 'runs', 'state', 'explainers', 'evals', 'okf']);
+function buildDocIndex(root) {
+  const out = [];
+  const walk = (dirRel, depth) => {
+    if (depth > 4 || out.length > 5000) return;
+    let ents;
+    try { ents = fs.readdirSync(path.join(root, dirRel), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const rel = dirRel ? `${dirRel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (!DOC_SKIP.has(e.name)) walk(rel, depth + 1); continue; }
+      if (!/\.md$/i.test(e.name) || /^(index|log)\.md$/i.test(e.name)) continue;
+      let head = '';
+      try {
+        const fd = fs.openSync(path.join(root, rel), 'r');
+        const buf = Buffer.alloc(3000); const n = fs.readSync(fd, buf, 0, 3000, 0); fs.closeSync(fd);
+        head = buf.slice(0, n).toString('utf8');
+      } catch { continue; }
+      const m = head.match(/^[-\s]*initiative_id:\s*["']?([\w.-]+)/m);
+      out.push({ rel, base: e.name, iid: m ? m[1] : null });
+    }
+  };
+  for (const d of DOC_ROOTS) walk(d, 0);
+  return out;
+}
+function documentsNaming(index, id) {
+  return index.filter((f) => f.iid === id || f.base === `${id}.md` || f.base.startsWith(`${id}-`)).map((f) => f.rel);
+}
+const isBriefName = (rel) => /brief/i.test(path.basename(rel));
+
 // ── the sweep ──────────────────────────────────────────────────────────────────────────────────
 
 function sweep(opts) {
@@ -197,6 +239,11 @@ function sweep(opts) {
     };
   }
   const idset = new Set(ids);
+  const profileInfo = engine.lanesFor(root);
+  const pmProfile = profileInfo.profile === 'pm-artifacts';
+  let docIndex = null;
+  let wfRange = null;
+  try { wfRange = engine.historyRange(root); } catch { wfRange = null; }
 
   // ── the ledgers, read once ────────────────────────────────────────────────────────────────────
   const ledgerFiles = {
@@ -260,9 +307,23 @@ function sweep(opts) {
   }
   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'))
+    .filter(({ row }) => row && row.accepted === true)
     .map(({ row }) => row.initiative_id).filter(Boolean));
 
+  // D77 — a row that looks like an approval and that the ladder does not count
+  for (const { row, line } of ledgers.acceptances.rows) {
+    if (!row || !row.initiative_id || !idset.has(row.initiative_id)) continue;
+    if (only && row.initiative_id !== only) continue;
+    if (row.accepted === true) continue;
+    if (row.action !== 'approve') continue;
+    findings.push(finding('acceptance-not-counted', {
+      id: row.initiative_id, file: path.relative(root, ledgerFiles.acceptances), line,
+      what: `an acceptances.jsonl row has action 'approve' and accepted '${row.accepted}' — the ladder counts only accepted: true`,
+      evidence: JSON.stringify(row).slice(0, 140),
+      hand: 'the sweep never writes a ledger: if this was an acceptance, the PM records it with scripts/record-acceptance.js; if it was something else, no action',
+    }));
+  }
+
   // ── delivery, read once ───────────────────────────────────────────────────────────────────────
   const del = delivery.deliveryIndex(root, ids);
   if (!del.ok) {
@@ -313,11 +374,18 @@ function sweep(opts) {
     const lane = (fm.lane || 'feature').trim() || 'feature';
 
     // dangling declared paths
-    for (const key of ['prd_path', 'rubric_path', 'explainer_path']) {
+    for (const key of pmProfile
+      ? ['prd_path', 'brief_path', 'doc_path', 'rubric_path', 'explainer_path']
+      : ['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);
+      let cands;
+      if (key === 'brief_path' || key === 'doc_path') {
+        if (!docIndex) docIndex = buildDocIndex(root);
+        const named = documentsNaming(docIndex, id);
+        cands = named.filter((f) => (key === 'brief_path') === isBriefName(f));
+      } else 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`,
@@ -332,6 +400,72 @@ function sweep(opts) {
       }));
     }
 
+    // D77 — a lane the profile does not offer
+    {
+      const declared = String(fm.lane || '').trim();
+      if (declared && !profileInfo.lanes.includes(declared)) {
+        const applied = pmProfile ? 'prd' : 'feature';
+        findings.push(finding('lane-outside-profile', {
+          id, file: recRel,
+          what: `lane '${declared}' is not a ${profileInfo.profile} lane`,
+          evidence: `the engine applies '${applied}' instead; this repository offers: ${profileInfo.lanes.join(', ')}`,
+          hand: `choose one of: ${profileInfo.lanes.join(', ')} — the lane is the PM's choice, so it is reported and never rewritten`,
+        }));
+      }
+    }
+
+    // D77 — a finished document that no record points at (document profile)
+    if (pmProfile) {
+      if (!docIndex) docIndex = buildDocIndex(root);
+      const named = documentsNaming(docIndex, id);
+      const declaredKeys = ['brief_path', 'prd_path', 'doc_path'].map((k) => String(fm[k] || '').trim()).filter(Boolean);
+      const unref = named.filter((f) => !declaredKeys.includes(f));
+      const briefEmpty = !String(fm.brief_path || fm.prd_path || '').trim();
+      const docEmpty = !String(fm.doc_path || '').trim();
+      if (unref.length && (briefEmpty || docEmpty)) {
+        let repair = null;
+        let hand = null;
+        if (unref.length === 1) {
+          const key = isBriefName(unref[0]) ? (briefEmpty ? 'brief_path' : null) : (docEmpty ? 'doc_path' : null);
+          if (key) repair = { kind: 'add-key', file: recRel, key, from: '', to: unref[0] };
+          else hand = `${unref[0]} names this initiative, but the key it would fill is already set — decide by hand`;
+        } else hand = `${unref.length} documents name this initiative (${unref.join(', ')}) — choosing which is the brief and which the deliverable is a judgement, so it is reported rather than guessed`;
+        findings.push(finding('unpointed-artifact', {
+          id, file: recRel,
+          what: `${unref.length} document${unref.length > 1 ? 's name' : ' names'} this initiative and no path key points at ${unref.length > 1 ? 'them' : 'it'}: ${unref.join(', ')}`,
+          evidence: `brief_path/prd_path ${briefEmpty ? 'is empty' : 'is set'}; doc_path ${docEmpty ? 'is empty' : 'is set'}`,
+          repair, hand,
+        }));
+      }
+    }
+
+    // D77 — what the ladder says against the record's own words, and against its own basis rule
+    if (wfRange) {
+      let wf = null;
+      try { wf = engine.computeWorkflow(id, { root, range: wfRange }); } catch { wf = null; }
+      if (wf && wf.ok && Array.isArray(wf.steps)) {
+        for (const st of wf.steps) {
+          if (st.status === 'done' && st.basis && st.basis.source === 'none' && st.key !== 'quality') {
+            findings.push(finding('done-without-basis', {
+              id, file: recRel,
+              what: `step '${st.key}' reads done and names no file, ledger or commit history`,
+              evidence: String(st.evidence || '').slice(0, 120),
+              hand: `the engine decided '${st.key}' from something the detail pane cannot open — fix the rung to name what it read`,
+            }));
+          }
+        }
+        const claim = String(fm.status || '').trim();
+        const gate = wf.steps.find((st) => st.key === 'accept' || st.key === 'approved');
+        if (/^(accepted|approved|complete|completed|done|delivered|shipped)\b/i.test(claim) && gate && gate.status !== 'done' && gate.status !== 'na') {
+          findings.push(finding('status-claims-ahead', {
+            id, file: recRel,
+            what: `status says '${claim.slice(0, 60)}' while the ${gate.key} step is ${gate.status}`,
+            evidence: String(gate.evidence || '').slice(0, 120),
+          }));
+        }
+      }
+    }
+
     // damaged frontmatter values
     for (const [key, v] of Object.entries(fm)) {
       const dmg = damagedValue(v);
@@ -553,6 +687,15 @@ function applyRepairs(res, opts) {
     for (const f of group) {
       const r = f.repair;
       const before = frontmatterValue(next, r.key);
+      if (r.kind === 'add-key') {
+        // One key, only when it is still absent or empty. A value the PM wrote since the sweep ran wins.
+        if (before !== null && before.trim() !== '') { skipped.push({ finding: f, why: `${r.key} was set since the sweep ran` }); continue; }
+        const edited = before === null ? insertFrontmatterKey(next, r.key, r.to) : setFrontmatterValue(next, r.key, r.to);
+        if (edited === next) { skipped.push({ finding: f, why: `${key} has no frontmatter to add ${r.key} to` }); continue; }
+        next = edited;
+        applied.push({ class: f.class, file: key, key: r.key, before: '(not set)', after: r.to.slice(0, 90) });
+        continue;
+      }
       if (before === null) { skipped.push({ finding: f, why: `${r.key} is no longer in the frontmatter` }); continue; }
       let after;
       if (r.kind === 'repoint') {
@@ -580,6 +723,15 @@ function frontmatterValue(text, key) {
   }
   return null;
 }
+/** Insert `key: value` as the last line of the leading frontmatter; the text is returned unchanged when there is none. */
+function insertFrontmatterKey(text, key, value) {
+  const lines = String(text).split('\n');
+  if (lines[0] !== '---') return text;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { lines.splice(i, 0, `${key}: ${value}`); return lines.join('\n'); }
+  }
+  return text;
+}
 function setFrontmatterValue(text, key, value) {
   const lines = String(text).split('\n');
   for (let i = 0; i < lines.length; i++) {

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-02T08:57:21Z"}
+generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
 status: stable
 ---
 

package/workspace/lib/audit.js

@@ -0,0 +1,54 @@
+'use strict';
+/* audit.js — the workspace's door to the workflow sweep (D77).
+ *
+ * The sweep is ONE file, scripts/workflow-sweep.js, shared with the CLI an agent runs. It is loaded the
+ * way the workflow engine is: from the checkout two directories up, or from the copy the packaging step
+ * vendors into lib/engine/. This door only READS: it runs the sweep and reports. Repairs are made by
+ * `node scripts/workflow-sweep.js --fix`, on the PM's word, because they write the repository.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const PATHS = [
+  path.join(__dirname, '..', '..', 'scripts', 'workflow-sweep.js'),
+  path.join(__dirname, 'engine', 'workflow-sweep.js'),
+];
+function core() {
+  for (const p of PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return { ok: true, core: require(p) }; }
+    catch (e) { return { ok: false, error: `the workflow sweep at ${p} failed to load — ${String((e && e.message) || e).slice(0, 160)}` }; }
+  }
+  return { ok: false, error: 'the workflow sweep is not present in this install' };
+}
+
+const DEFECT_CAP = 40;
+const OWED_CAP = 12;
+
+/* Run the sweep on `root` and return a compact report. Defects are listed in full up to a cap, owed work as
+ * counts per class plus the first few, because a defect is the board lying and owed work is an open loop. */
+function run(root) {
+  const c = core(); if (!c.ok) return c;
+  let res;
+  try { res = c.core.sweep({ root }); }
+  catch (e) { return { ok: false, error: 'the sweep could not run — ' + String((e && e.message) || e).slice(0, 160) }; }
+  if (!res || res.ok === false) return { ok: false, error: (res && res.error) || 'the sweep could not read this repository' };
+  const pick = (f) => ({
+    class: f.class, id: f.id || null, file: f.file || null, what: f.what, evidence: f.evidence || null,
+    repair: f.repair ? { key: f.repair.key || null, to: f.repair.to || null } : null,
+    hand: f.hand || null,
+    command: f.repair ? 'node scripts/workflow-sweep.js --fix' : null,
+  });
+  const owedBy = {};
+  for (const f of res.owed || []) owedBy[f.class] = (owedBy[f.class] || 0) + 1;
+  return {
+    ok: true, root, initiatives: res.initiatives,
+    counts: { defects: (res.defects || []).length, owed: (res.owed || []).length, repairable: res.repairable || 0 },
+    defects: (res.defects || []).slice(0, DEFECT_CAP).map(pick),
+    owed_by_class: owedBy,
+    owed: (res.owed || []).slice(0, OWED_CAP).map(pick),
+    notes: res.notes || [],
+  };
+}
+
+module.exports = { run, core, PATHS };

package/workspace/lib/engine/lane-defs.js

@@ -0,0 +1,226 @@
+'use strict';
+/*
+ * Lane definitions — the one place a workflow is defined (D77).
+ *
+ * A lane is a kind of work. This file says, for each lane: what it is for, what goes in, which
+ * rungs the work passes, what comes out, and when it is done. The workflow engine, the lane
+ * picker, the lane write and the workspace detail pane all read THIS file. Change a lane here and
+ * every one of them changes; there is no second list to keep in step.
+ *
+ * Two kinds of field:
+ *   · prose (label, when, input, output, done) — shown to the PM, never read by the engine's rules;
+ *   · rules (track, rungs, labels) — read by the engine, so a change here changes the ladder.
+ *
+ * The engine runs under stock Node with no dependencies, and the kit vendors it by walking its
+ * relative requires, so this is a plain CommonJS module rather than a JSON file.
+ *
+ * `rungs` lists the pm-artifacts rungs a lane passes through. A rung left out reads `n/a` with the
+ * lane named as the reason, so a lane that skips a rung says so instead of showing it pending.
+ * The code profile's ladder is fixed by D56/D58/D60; its definitions here are descriptive.
+ */
+
+const PM_ALL_RUNGS = ['brief', 'draft', 'review', 'approved', 'handoff'];
+const PM_NO_HANDOFF = ['brief', 'draft', 'review', 'approved'];
+
+const PM_ARTIFACTS = {
+  'new-feature': {
+    label: 'New feature',
+    group: 'work',
+    when: 'A capability that does not exist yet.',
+    input: 'The problem, who has it, and the evidence that it is real.',
+    output: 'A product requirements document (PRD).',
+    done: 'The PRD exists, a reviewer has judged it, the PM has accepted it, and it is handed to the team or tracker.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'problem brief', draft_label: 'PRD',
+  },
+  improvement: {
+    label: 'Feature improvement',
+    group: 'work',
+    when: 'A change to a feature that already exists.',
+    input: 'The feature as it is now, what is wrong or missing, and the measure the change should move.',
+    output: 'A change specification: what changes, what stays the same, and how to tell it worked.',
+    done: 'The change specification exists, a reviewer has judged it, the PM has accepted it, and it is handed off.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'change brief', draft_label: 'change specification',
+  },
+  'bug-fix': {
+    label: 'Bug fix',
+    group: 'work',
+    when: 'Behaviour that is wrong against what was promised.',
+    input: 'A bug report: steps to reproduce, expected result, actual result, severity.',
+    output: 'A fix specification: the cause, the behaviour after the fix, and the check that proves it.',
+    done: 'The fix specification exists, a reviewer has judged it, the PM has accepted it, and it is handed off.',
+    track: 'light', rungs: PM_ALL_RUNGS, brief_label: 'bug report', draft_label: 'fix specification',
+  },
+  discovery: {
+    label: 'New product discovery',
+    group: 'work',
+    when: 'A question that must be answered before anyone commits to build.',
+    input: 'The question, what is unknown, and the evidence that would make this worth picking up or dropping.',
+    output: 'Findings and a recommendation: go, drop, or learn more.',
+    done: 'The findings exist, a reviewer has judged them, the PM has accepted them, and the recommendation is handed off.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'question brief', draft_label: 'findings',
+  },
+  chore: {
+    label: 'Chore',
+    group: 'work',
+    when: 'Upkeep that needs no requirements document.',
+    input: 'One paragraph that states the intent.',
+    output: 'The change itself, with the paragraph in the record.',
+    done: 'The change is made and the PM has accepted it. Nothing is handed off.',
+    track: 'light', rungs: PM_NO_HANDOFF, brief_label: 'intent', draft_label: 'change',
+  },
+  prd: {
+    label: 'PRD (document)',
+    group: 'document',
+    when: 'A standalone requirements document that is not a new feature, an improvement or a bug fix.',
+    input: 'The brief: the question, the reader, the decision it informs.',
+    output: 'A product requirements document.',
+    done: 'The PRD exists, a reviewer has judged it, the PM has accepted it, and it is handed off.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'brief', draft_label: 'PRD',
+  },
+  strategy: {
+    label: 'Strategy (document)',
+    group: 'document',
+    when: 'A statement of direction: where to play, how to win, what not to do.',
+    input: 'The brief: the question, the reader, the decision it informs.',
+    output: 'A strategy document.',
+    done: 'The document exists, a reviewer has judged it, the PM has accepted it, and it is handed off.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'brief', draft_label: 'strategy document',
+  },
+  'project-plan': {
+    label: 'Project plan (document)',
+    group: 'document',
+    when: 'Who does what, by when, in what order.',
+    input: 'The scope, the people and the dates that are fixed.',
+    output: 'A project plan.',
+    done: 'The plan exists, a reviewer has judged it, the PM has accepted it, and it is handed off.',
+    track: 'governed', rungs: PM_ALL_RUNGS, brief_label: 'brief', draft_label: 'project plan',
+  },
+  'decision-record': {
+    label: 'Decision record (document)',
+    group: 'document',
+    when: 'A decision that was made and must not be re-argued.',
+    input: 'The options, the choice, and the reason.',
+    output: 'A decision record.',
+    done: 'The record exists, a reviewer has judged it, and the PM has accepted it. Nothing is handed off.',
+    track: 'light', rungs: PM_NO_HANDOFF, brief_label: 'brief', draft_label: 'decision record',
+  },
+  report: {
+    label: 'Report (document)',
+    group: 'document',
+    when: 'An account of what happened or where things stand.',
+    input: 'The period or subject, and the reader.',
+    output: 'A report.',
+    done: 'The report exists, a reviewer has judged it, and the PM has accepted it. Nothing is handed off.',
+    track: 'light', rungs: PM_NO_HANDOFF, brief_label: 'brief', draft_label: 'report',
+  },
+};
+
+/*
+ * The code profile's lanes. They share ONE ladder; a lane changes only the artifact the spec rung
+ * requires (`requires`), whether a rubric is needed, the prototype rule, and the build-path rule. Those
+ * rules are fixed by D56/D58/D60 and live in workflow-state.js; what is here is what the PM reads.
+ */
+const PRODUCT_CODE = {
+  feature: {
+    label: 'Feature',
+    group: 'work',
+    when: 'New or changed behaviour in the product.',
+    input: 'A product requirements document and an evaluation rubric, written before the build.',
+    requires: 'A PRD and a rubric, both written before the build.',
+    output: 'A pull request that satisfies the rubric.',
+    done: 'The build passes the rubric, an explainer is written, and the PM has accepted it.',
+  },
+  discovery: {
+    label: 'Discovery',
+    group: 'work',
+    when: 'A question to answer before building.',
+    input: 'A spike brief: the question and the evidence that would end the spike.',
+    requires: 'A spike brief.',
+    output: 'Findings that answer the question.',
+    done: 'The findings answer the brief and the PM has accepted them.',
+  },
+  chore: {
+    label: 'Chore',
+    group: 'work',
+    when: 'Upkeep that needs no requirements document.',
+    input: 'One paragraph that states the intent.',
+    requires: 'One paragraph of intent, written in the record\'s status.',
+    output: 'The change.',
+    done: 'The change is made and the PM has accepted it.',
+  },
+  incident: {
+    label: 'Incident',
+    group: 'work',
+    when: 'Something broke and was fixed first.',
+    input: 'A record written after the fix: what broke, the cause, the repair.',
+    requires: 'An incident record.',
+    output: 'The fix and its post-hoc record.',
+    done: 'The record states the cause and the repair, and the PM has accepted it.',
+  },
+  content: {
+    label: 'Content',
+    group: 'work',
+    when: 'Writing or media that ships with the product.',
+    input: 'A content brief. A rubric is recommended.',
+    requires: 'A content brief. A rubric is optional.',
+    output: 'The content.',
+    done: 'The content meets the brief and the PM has accepted it.',
+  },
+  prototype: {
+    label: 'Prototype',
+    group: 'work',
+    when: 'An idea the PM cannot judge from a description.',
+    input: 'A quick brief.',
+    requires: 'A quick prototype brief.',
+    output: '2–3 specimens the PM can look at. A prototype is never scored.',
+    done: 'The PM has looked at the specimens and chosen what to do with them.',
+  },
+};
+
+/*
+ * What decides each rung. This is the answer to "how does PMOS know this step is done" — one
+ * sentence per rung, shown beside the evidence in the detail pane. It restates the engine's test;
+ * the engine remains the authority, and the suite checks that every rung the engine emits has a
+ * sentence here.
+ */
+const RUNG_RULES = {
+  'pm-artifacts': {
+    route: 'The lane named in the record is one this repository offers.',
+    anchor: 'parent_kr names a KR, a declared health budget, or a domain goal that resolves.',
+    brief: 'The file named in brief_path (or prd_path) exists.',
+    draft: 'The file named in doc_path exists. On the governed track it did not first appear before the brief.',
+    review: 'evals.jsonl holds a verdict for this initiative, or the record names a reviewer in reviewed_by.',
+    approved: 'acceptances.jsonl holds an accepted line for this initiative. The PM records it; it is never automatic.',
+    handoff: 'handed_off in the record names where the work went.',
+  },
+  'product-code': {
+    route: 'The lane is one this repository offers, and its specimen and surface questions are answered.',
+    anchor: 'parent_kr names a KR, a declared health budget, or a domain goal that resolves.',
+    prototype: 'A prototype brief first appeared before the PRD, where the specimen test calls for one.',
+    understand: 'An explainer for the existing surface first appeared before the PRD.',
+    spec: 'The PRD and rubric named in the record exist and first appeared at or before the first build commit.',
+    priors: 'The record cites a prior run or states that none applies.',
+    contract: 'A run in agent-runs.jsonl holds done criteria and a test method with PM_approved set.',
+    build: 'Commits attributed to this initiative change a build path.',
+    quality: 'CI decides on the pull request. The engine never claims a test result it did not run.',
+    review: 'evals.jsonl holds a Review-Gate verdict for this initiative, or a skip.',
+    explain: 'An explainer exists for the run.',
+    accept: 'acceptances.jsonl holds an accepted line for this initiative. The PM records it.',
+    outcome: 'outcome_checks holds a validated, refuted or inconclusive disposition with evidence.',
+  },
+};
+
+function defsFor(profile) {
+  return profile === 'pm-artifacts' ? PM_ARTIFACTS : PRODUCT_CODE;
+}
+function laneNames(profile) {
+  return Object.keys(defsFor(profile));
+}
+function laneDef(profile, lane) {
+  return defsFor(profile)[lane] || null;
+}
+function rungRule(profile, key) {
+  return (RUNG_RULES[profile] || {})[key] || null;
+}
+
+module.exports = { PM_ARTIFACTS, PRODUCT_CODE, RUNG_RULES, defsFor, laneNames, laneDef, rungRule };