create-pmos 0.38.3 → 0.38.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.38.3",
+  "version": "0.38.5",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@58c817d
+kernel-source: pmos@f5daae8
 assembled: 2026-10-02
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-02T06:19:09Z"}
+generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-02T06:19:09Z"}
+generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
 status: stable
 ---
 

package/payload/scripts/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 };

package/payload/scripts/workflow-state.js

@@ -532,9 +532,9 @@ function surfaceRoute(v) {
 // A repository declares `pm-artifacts` (a PM's documents, strategy and specifications — no code) or
 // `product-code` (PMOS-self and code repositories) in a one-line `.pmos-profile` file at its root.
 // No file, or anything else in it, is `product-code`: every existing repository behaves as before.
-const PM_LANES = ['strategy', 'prd', 'project-plan', 'discovery', 'decision-record', 'report', 'chore'];
-const PM_LIGHT_BY_DEFAULT = ['decision-record', 'report', 'chore'];
-const PM_NO_HANDOFF = ['decision-record', 'report', 'chore'];
+// D77 — the lane lists, tracks and rung sets are DATA in scripts/lane-defs.js. This file reads them;
+// it holds no lane list of its own, so editing a definition changes the ladder with no edit here.
+const laneDefs = require('./lane-defs');
 function profileOf(root) {
   try {
     const line = fs.readFileSync(path.join(root, '.pmos-profile'), 'utf8')
@@ -544,9 +544,10 @@ function profileOf(root) {
 }
 
 /** The lanes a repository's initiatives may declare — what the lane picker offers and the lane write accepts. */
+function laneNames(profile) { return laneDefs.laneNames(profile === 'pm-artifacts' ? 'pm-artifacts' : 'product-code'); }
 function lanesFor(root) {
   const profile = profileOf(path.resolve(root || process.cwd()));
-  return { profile, lanes: profile === 'pm-artifacts' ? PM_LANES.slice() : ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'] };
+  return { profile, lanes: laneNames(profile), defs: laneDefs.defsFor(profile) };
 }
 
 // ── Step model ─────────────────────────────────────────────────────────────────────────────────
@@ -561,6 +562,60 @@ function step(key, label, status, evidence, next, opts) {
   };
 }
 
+/*
+ * D77 — the basis of every step: the rule that decides it, and what it read.
+ *
+ * `rule` is one sentence from lane-defs.js (the engine's test, restated for a PM). `file` is a
+ * repository path the step read, and is set ONLY when that file exists — a path the engine did not
+ * find is never offered as a basis. `source` says what kind of thing decided the step: a `file`, a
+ * `ledger` (a .jsonl row), `git` (commit history) or `none`. `first_seen` is the date the file first
+ * appeared, read from the range's own index where it holds one; it is null rather than guessed.
+ */
+function attachBasis(steps, c) {
+  const { profile, root, L, fm, recRel, range, hasEvals, hasAcceptance } = c;
+  const rel = (abs) => path.relative(root, abs);
+  const runs = rel(path.join(L.runsDir, L.runsFile));
+  const evalsLedger = rel(path.join(L.runsDir, 'evals.jsonl'));
+  const acceptLedger = rel(path.join(L.runsDir, 'acceptances.jsonl'));
+  const outcomeLedger = rel(path.join(L.runsDir, 'outcome_checks.jsonl'));
+  const exists = (p) => !!p && fs.existsSync(path.join(root, p));
+  const inEvidence = (st) => {
+    const m = String(st.evidence || '').match(/[\w./-]+\.(?:md|jsonl)\b/);
+    return m && exists(m[0]) ? m[0] : null;
+  };
+  const prd = String(fm.prd_path || '').trim();
+  const pick = {
+    'pm-artifacts': {
+      route: [recRel], anchor: [recRel],
+      brief: [String(fm.brief_path || fm.prd_path || '').trim()], draft: [String(fm.doc_path || '').trim()],
+      review: [hasEvals ? evalsLedger : recRel], approved: [acceptLedger], handoff: [recRel],
+    },
+    'product-code': {
+      route: [recRel], anchor: [recRel], prototype: [prd], understand: [String(fm.explainer_path || '').trim()],
+      spec: [prd, fm.lane === 'chore' ? recRel : null], priors: [runs], contract: [runs], build: [], quality: [],
+      review: [hasEvals ? evalsLedger : null], explain: [], accept: [hasAcceptance ? acceptLedger : null],
+      outcome: [outcomeLedger],
+    },
+  }[profile] || {};
+  for (const st of steps) {
+    let file = null;
+    for (const cand of (pick[st.key] || [])) if (exists(cand)) { file = cand; break; }
+    if (!file && st.status === 'done') file = inEvidence(st);
+    if (st.status === 'na') file = null;
+    let source = 'none';
+    if (file) source = file.endsWith('.jsonl') ? 'ledger' : 'file';
+    else if (st.key === 'build' && st.status === 'done') source = 'git';
+    let firstSeen = null;
+    if (file && source === 'file' && range && range.ok && range.dates) {
+      const idx = firstAppearance(root, range, file);
+      const t = typeof idx === 'number' && idx >= 0 ? range.dates[idx] : null;
+      if (t) firstSeen = new Date(t * 1000).toISOString().slice(0, 10);
+    }
+    st.basis = { rule: laneDefs.rungRule(profile, st.key), file, source, first_seen: firstSeen };
+  }
+  return steps;
+}
+
 // D74 — `generated: {by: x, at: "2026-10-02T01:00:00Z"}` on one line (the only form PMOS writes). Returns the `at`, or ''.
 function generatedAt(v) {
   const m = /\bat:\s*["']?([^"',}\s]+)/.exec(String(v || ''));
@@ -578,8 +633,8 @@ function computeWorkflowDerived(id, opts) {
   const profile = profileOf(root);
   const pmProfile = profile === 'pm-artifacts';
   const lane = (fm.lane || (pmProfile ? 'prd' : 'feature')).trim() || (pmProfile ? 'prd' : 'feature');
-  const knownLane = pmProfile ? PM_LANES.includes(lane)
-    : ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'].includes(lane);
+  const knownLane = pmProfile ? laneNames('pm-artifacts').includes(lane)
+    : laneNames('product-code').includes(lane);
   // unknown lane = the profile's strictest (feature in product-code, a governed prd in pm-artifacts)
   const effLane = knownLane ? lane : (pmProfile ? 'prd' : 'feature');
   const range = (opts && opts.range) || commitRange(root);
@@ -1163,6 +1218,8 @@ function computeWorkflowDerived(id, opts) {
     }
   }
 
+  attachBasis(steps, { profile: 'product-code', root, L, fm, recRel, range, hasEvals: evals.length > 0, hasAcceptance: accepted.length > 0 });
+
   // ── stage, derived from what the steps found ─────────────────────────────────────────────────
   const by = Object.fromEntries(steps.map((s) => [s.key, s]));
   let stage = 'intake';
@@ -1208,51 +1265,60 @@ function computeWorkflowDerived(id, opts) {
 function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity }) {
   const declared = String(fm.track || '').trim().toLowerCase();
   const track = declared === 'light' || declared === 'governed' ? declared
-    : (PM_LIGHT_BY_DEFAULT.includes(effLane) ? 'light' : 'governed');
+    : (laneDefs.laneDef('pm-artifacts', effLane) || laneDefs.laneDef('pm-artifacts', 'prd')).track;
   const enforce = track === 'governed' && !legacy;
   const exists = (p) => !!p && fs.existsSync(path.join(root, p));
+  // D77 — the lane's own definition decides which rungs it passes and what it calls them.
+  const def = laneDefs.laneDef('pm-artifacts', effLane) || laneDefs.laneDef('pm-artifacts', 'prd');
+  const flows = (k) => def.rungs.includes(k);
+  const skipped = (key, label) => step(key, label, 'na', `${effLane} lane — ${label} is not part of this flow`);
 
   // route — the lane is a pm-artifacts lane
   steps[0] = knownLane
     ? step('route', 'route', 'done', `${lane} lane · ${track} track (pm-artifacts profile, D68)`)
     : step('route', 'route', 'done', `unknown lane '${lane}' — treated as a governed prd, the profile's strictest (D68)`,
-      `set lane: to one of ${PM_LANES.join(', ')}`);
+      `set lane: to one of ${laneNames('pm-artifacts').join(', ')}`);
 
   const briefPath = String(fm.brief_path || fm.prd_path || '').trim();
   const docPath = String(fm.doc_path || '').trim();
   const briefIdx = briefPath ? firstAppearance(root, range, briefPath) : null;
   const docIdx = docPath ? firstAppearance(root, range, docPath) : null;
 
-  if (exists(briefPath)) steps.push(step('brief', 'brief', 'done', `${briefPath} present`));
-  else steps.push(step('brief', 'brief', enforce ? 'blocked' : 'pending',
-    briefPath ? `brief_path '${briefPath}' does not exist` : 'no brief yet',
-    `write a short brief (the question, the reader, the decision it informs) and set brief_path in ${recRel}`,
+  if (!flows('brief')) steps.push(skipped('brief', def.brief_label));
+  else if (exists(briefPath)) steps.push(step('brief', def.brief_label, 'done', `${briefPath} present`));
+  else steps.push(step('brief', def.brief_label, enforce ? 'blocked' : 'pending',
+    briefPath ? `brief_path '${briefPath}' does not exist` : `no ${def.brief_label} yet`,
+    `write the ${def.brief_label} (${def.input}) and set brief_path in ${recRel}`,
     { blocking: enforce, rule: 'P1' }));
 
-  if (exists(docPath)) {
+  if (!flows('draft')) steps.push(skipped('draft', def.draft_label));
+  else if (exists(docPath)) {
     const inOrder = briefIdx == null || docIdx == null ? null : docIdx >= briefIdx;
     if (enforce && inOrder === false) {
-      steps.push(step('draft', 'draft', 'blocked', `${docPath} appeared before its brief ${briefPath}`,
+      steps.push(step('draft', def.draft_label, 'blocked', `${docPath} appeared before its brief ${briefPath}`,
         'a governed document is briefed before it is drafted — the brief must land first', { blocking: true, rule: 'P2' }));
-    } else steps.push(step('draft', 'draft', 'done', `${docPath} present`));
-  } else steps.push(step('draft', 'draft', enforce && docPath ? 'blocked' : 'pending',
-    docPath ? `doc_path '${docPath}' does not exist` : 'no draft yet',
-    `write the document and set doc_path in ${recRel}`, { blocking: enforce && !!docPath, rule: 'P2' }));
+    } else steps.push(step('draft', def.draft_label, 'done', `${docPath} present`));
+  } else steps.push(step('draft', def.draft_label, enforce && docPath ? 'blocked' : 'pending',
+    docPath ? `doc_path '${docPath}' does not exist` : `no ${def.draft_label} yet`,
+    `write the ${def.draft_label} (${def.output}) and set doc_path in ${recRel}`, { blocking: enforce && !!docPath, rule: 'P2' }));
 
   const evals = cachedJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
   const reviewer = String(fm.reviewed_by || '').trim();
-  if (evals.length) steps.push(step('review', 'review', 'done', `${evals[evals.length - 1].verdict || 'verdict'} recorded in evals.jsonl`));
+  if (!flows('review')) steps.push(skipped('review', 'review'));
+  else if (evals.length) steps.push(step('review', 'review', 'done', `${evals[evals.length - 1].verdict || 'verdict'} recorded in evals.jsonl`));
   else if (reviewer) steps.push(step('review', 'review', 'done', `reviewed by ${reviewer}`));
   else steps.push(step('review', 'review', 'pending', 'not reviewed yet',
     'name the reviewer in reviewed_by: (a person, an agent, or a rubric verdict in evals.jsonl)'));
 
   const accepted = cachedJsonl(path.join(L.runsDir, 'acceptances.jsonl'))
     .filter((a) => a && a.initiative_id === id && a.accepted === true);
-  steps.push(accepted.length
-    ? step('approved', 'approved', 'done', `accepted by the PM${accepted[accepted.length - 1].accepted_at ? ' on ' + String(accepted[accepted.length - 1].accepted_at).slice(0, 10) : ''}`)
+  const acceptedOn = accepted.length ? (accepted[accepted.length - 1].accepted_at || accepted[accepted.length - 1].at) : null;
+  steps.push(!flows('approved') ? skipped('approved', 'approved')
+    : accepted.length
+    ? step('approved', 'approved', 'done', `accepted by the PM${acceptedOn ? ' on ' + String(acceptedOn).slice(0, 10) : ''}`)
     : step('approved', 'approved', 'pending', 'awaiting the PM\'s acceptance (D12)', 'the PM accepts the document — never automatic'));
 
-  if (PM_NO_HANDOFF.includes(effLane)) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));
+  if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));
   else {
     const to = String(fm.handed_off || '').trim();
     steps.push(to ? step('handoff', 'handed off', 'done', `handed off — ${to}`)
@@ -1260,6 +1326,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
         'record where it went in handed_off: (a tracker link, the team, or "accepted as the deliverable")'));
   }
 
+  attachBasis(steps, { profile: 'pm-artifacts', root, L, fm, recRel, range, hasEvals: evals.length > 0, hasAcceptance: accepted.length > 0 });
   const by = Object.fromEntries(steps.map((x) => [x.key, x]));
   let stage = 'intake';
   if (by.brief.status === 'done') stage = 'brief';
@@ -1425,7 +1492,7 @@ function listInitiatives(root) {
 // ── CLI ────────────────────────────────────────────────────────────────────────────────────────
 function main(argv) {
   const args = argv.slice(2);
-  let root = process.cwd(); let json = false; let gate = false; let all = false;
+  let root = process.cwd(); let json = false; let gate = false; let all = false; let lanes = false;
   const rest = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -1433,6 +1500,7 @@ function main(argv) {
     if (a === '--json') { json = true; continue; }
     if (a === '--gate') { gate = true; continue; }
     if (a === '--all') { all = true; continue; }
+    if (a === '--lanes') { lanes = true; continue; }
     if (a === '--open') { continue; }          // the board is in-flight-only by default now
     if (a === '--help' || a === '-h') {
       process.stdout.write([
@@ -1441,12 +1509,28 @@ function main(argv) {
         '    <id>           the ladder for one initiative: where you are, what is next, what blocks',
         '    --gate <id>    CI mode — exit 1 on a blocking order violation, with the next action',
         '    --all          the board without the 12-row cap',
+        '    --lanes        every lane this repository offers: when to use it, input, output, done',
         '    --json         machine-readable (what an agent reads at session start)', '',
       ].join('\n') + '\n');
       return 0;
     }
     rest.push(a);
   }
+  if (lanes) {
+    const info = lanesFor(root);
+    if (json) { process.stdout.write(JSON.stringify(info, null, 2) + '\n'); return 0; }
+    const out = ['', `  ${info.profile} — ${info.lanes.length} lanes`, ''];
+    for (const name of info.lanes) {
+      const d = info.defs[name];
+      out.push(`  ${c(1, name)}${d.label ? ` — ${d.label}` : ''}${d.track ? c(90, `  [${d.track} track]`) : ''}`);
+      out.push(`    when    ${d.when}`);
+      out.push(`    input   ${d.requires || d.input}`);
+      out.push(`    output  ${d.output}`);
+      out.push(`    done    ${d.done}`, '');
+    }
+    process.stdout.write(out.join('\n') + '\n');
+    return 0;
+  }
   const self = path.relative(root, __filename) || 'scripts/workflow-state.js';
   const id = rest[0];
 
@@ -1505,7 +1589,7 @@ module.exports = {
   // under BOTH ranges, and `in this change` is false under the trunk one.
   historyRange,
   ENFORCED_FROM,
-  lanesFor,
+  lanesFor, laneNames,
 };
 
 /*