create-pmos 0.38.4 → 0.38.5

package/workspace/lib/engine/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,
 };
 
 /*