create-pmos 0.132.0 → 0.134.0

package/workspace/lib/vendor/scripts/delivery-index.js

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS delivery evidence — the one place git's history answers "did THIS initiative ship?".
+ *
+ *   const D = require('./delivery-index');
+ *   const idx = D.deliveryIndex(root, ids);     // { ok, reason?, byBranch:Set, byMention:Set }
+ *   D.attribution(idx, id)                      // 'branch' | 'mention' | 'change' | null | 'unknown'
+ *   D.isDeliveryPath('workspace/server.js')     // true — a build path, not planning prose
+ *
+ * WHY THIS EXISTS. This derivation shipped inside `workspace/server.js` as a module-private
+ * function, so it answered for exactly one surface. The engine — `scripts/workflow-state.js`, which
+ * CI, the CLI and the workspace ladder all run — could not see it, and derived its `build` rung from
+ * a signal carrying no attribution at all: `buildCommits` counted every commit in a range that
+ * touched a build path, with no idea which initiative it was answering about. Over a pull-request
+ * range that is correct, because the range IS one initiative's work. Over the trunk it reported the
+ * same 488 commits as evidence for all 177 initiatives, including ones that shipped nothing.
+ *
+ * So the GUI's initiative board and the engine's ladder held two different opinions about the same
+ * question, in the same process, three hundred lines apart — one attributed, one not. That is the
+ * shape `scripts/anchor-resolve.js` was extracted to end for `parent_kr`, stated in its own header,
+ * and delivery is the same kind of fact. See
+ * planning/explainers/workflow-status-sweep-surface-explainer.md.
+ *
+ * TWO SIGNALS, because one is not enough (board-delivery-truth R-2):
+ *
+ *   1. THE BRANCH CONVENTION is precise and incomplete. A merge whose subject names
+ *      `initiative/<id>` is unambiguous — but 31% of this repository's merged pull requests shipped
+ *      on `claude/*` branches, which match no id, and a convention nothing enforces cannot be the
+ *      only signal.
+ *
+ *   2. A COMMIT THAT MENTIONS THE ID AND TOUCHES A BUILD PATH. The build-path requirement is what
+ *      keeps the mention signal honest: `feat(planning): add <id> PRD` mentions the id while
+ *      delivering nothing, and without the path test every SPECIFIED initiative would read as
+ *      shipped — which is the same class of false green this module exists to remove.
+ *
+ * HONESTY BY CONSTRUCTION. `ok:false` is a real answer and never degrades into "nothing was
+ * delivered". A caller that cannot read the history must say so; silently reporting `planning` for
+ * every shipped initiative is precisely the failure being fixed. `attribution()` returns the string
+ * `'unknown'` for that case, and it is deliberately not `null` — "I cannot tell" and "I looked and
+ * there is nothing" call for opposite responses from every caller.
+ *
+ * Zero dependencies, stock Node. It runs in CI, in a terminal, inside the workspace server, and
+ * inside an adopter's vendored kit.
+ */
+
+const { spawnSync } = require('child_process');
+
+/*
+ * A path counts as DELIVERY when it is neither a planning artifact nor governance prose.
+ *
+ * This is deliberately a SEPARATE rule from the engine's `isBuildPath`, and the difference is not an
+ * oversight. `isBuildPath` answers "is this commit implementation work for the lane under review?"
+ * and therefore lane-gates `prototype/` — in the prototype lane the specimen IS the deliverable
+ * (D60), in every other lane it is somebody else's leg-A work. This answers a coarser question
+ * asked of the whole trunk at once, where no single lane is under review, so `prototype/` is always
+ * excluded: a prototype never ships (D01), so a commit touching only `prototype/` is never evidence
+ * that something was delivered. Merging the two rules would force one of the two questions to be
+ * answered wrongly. They are kept apart, and each says why in the place it is written.
+ */
+const EXCLUDED_PREFIX = /^(planning|okf|prototype)\//;
+function isDeliveryPath(f) {
+  if (!f) return false;
+  if (EXCLUDED_PREFIX.test(f)) return false;
+  // Root-level governance prose (DECISIONS.md, CLAUDE.md, AGENTS.md…) is not a build. A markdown
+  // file deeper in the tree may well be — `workspace/docs/*.md` ships with the app — so the test is
+  // on the shape of the path, not on the extension alone.
+  return !/^[^/]+\.md$/.test(f);
+}
+
+function gitCap(root, args) {
+  try {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status !== 0) {
+      return { ok: false, out: '', err: (r.stderr || (r.error && r.error.message) || '').trim() };
+    }
+    return { ok: true, out: r.stdout || '' };
+  } catch (e) { return { ok: false, out: '', err: String((e && e.message) || e) }; }
+}
+
+function trunkRef(root) {
+  for (const c of ['origin/main', 'main', 'origin/master', 'master']) {
+    const r = gitCap(root, ['rev-parse', '--verify', '--quiet', c]);
+    if (r.ok && r.out.trim()) return { ref: c, head: r.out.trim() };
+  }
+  return null;
+}
+
+// ONE `git log` per trunk head, memoised on that sha — ~0.3 s and ~800 KB on this repository's
+// 1,200 commits, paid once and reused by every caller until the trunk moves. The cache key is the
+// head sha rather than the root, so a fetch that advances the trunk invalidates it by construction
+// rather than by anyone remembering to.
+const deliveryCache = new Map();      // root -> { head, index }
+
+/**
+ * Which initiatives the trunk's own history says were delivered.
+ *
+ * @param {string} root  repository root
+ * @param {Iterable<string>} ids  the known initiative ids — the mention signal can only recognise
+ *                                ids it was told about, and matching arbitrary tokens would turn
+ *                                any commit subject into a delivery claim
+ * @returns {{ok:boolean, reason?:string, byBranch:Set<string>, byMention:Set<string>}}
+ */
+function deliveryIndex(root, ids, opts) {
+  const t = trunkRef(root);
+  if (!t) {
+    return {
+      ok: false,
+      reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived',
+      byBranch: new Set(), byMention: new Set(), byChange: new Set(),
+    };
+  }
+  const hit = deliveryCache.get(root);
+  if (hit && hit.head === t.head) return hit.index;
+
+  // %x1e separates commits, %x1f separates the message from --name-only's file list.
+  const r = gitCap(root, ['log', '--format=%x1e%s %b%x1f', '--name-only', t.head]);
+  if (!r.ok) {
+    return {
+      ok: false,
+      reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`,
+      byBranch: new Set(), byMention: new Set(), byChange: new Set(),
+    };
+  }
+  const byBranch = new Set();
+  const byMention = new Set();
+  const known = Array.isArray(ids) ? ids : [...(ids || [])];
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const msg = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    for (const m of msg.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) byBranch.add(m[1]);
+    if (!files.some(isDeliveryPath)) continue;
+    // `id.length > 3` guards against a short id matching incidentally inside an unrelated word.
+    // It is a heuristic and is named as one in the PRD's risks; a miss reads as `pending`, which is
+    // the safe direction and the one the surface already errs in.
+    for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
+  }
+  // 3. THE CHANGE THAT CARRIED THE SPEC (scan-consistency R1). See changeSignal below.
+  const byChange = changeSignal(root, t.head, known, opts);
+  const index = { ok: true, byBranch, byMention, byChange };
+  deliveryCache.set(root, { head: t.head, index });
+  return index;
+}
+
+/*
+ * THE THIRD SIGNAL — a change on the trunk that touched this initiative's OWN documents and build
+ * paths together (scan-consistency R1).
+ *
+ * Signals 1 and 2 both need the id spelled in a commit message. On this repository most pull
+ * requests ship on `claude/<slug>-<suffix>` branches and their commits name the area (`feat(workspace):
+ * …`), not the id, so 102 of 283 initiatives read `build pending` although their PRD, record and code
+ * merged in one pull request. The tie is concrete and git holds it: the pull request that changed
+ * `planning/initiatives/<id>.md` (or the PRD the record names) ALSO changed build files.
+ *
+ * A UNIT is one first-parent commit of the trunk: a merge commit (its diff against the first parent
+ * is the whole pull request), a squash merge, or a direct commit. Two guards keep it from becoming a
+ * similarity score:
+ *   · the unit must change at least one build path (isDeliveryPath) — a docs-only pull request
+ *     delivers nothing;
+ *   · the unit may touch the documents of at most MAX_CO_INITIATIVES initiatives. A sweep that edits
+ *     forty records while changing a script is evidence for none of them.
+ * A merged branch whose name, less its random suffix, IS a known id (`claude/jira-wbs-kpamaz`) counts
+ * too, when its pull request changed build paths.
+ */
+const MAX_CO_INITIATIVES = 2;
+const RECORD_DIRS = ['planning/initiatives', 'pmos/state/initiatives', 'state/initiatives'];
+/** { [repo-relative path]: Set<id> } — each record and every `*_path` its frontmatter names. */
+function documentOwners(root, ids, recordsDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const dirs = recordsDir ? [recordsDir] : RECORD_DIRS.map((d) => path.join(root, d));
+  const owners = new Map();
+  const add = (rel, id) => {
+    const k = String(rel || '').trim().replace(/^["']|["']$/g, '').replace(/^\.?\//, '');
+    if (!k || /\s/.test(k) || k.includes('..')) return;
+    if (!owners.has(k)) owners.set(k, new Set());
+    owners.get(k).add(id);
+  };
+  for (const id of ids) {
+    for (const dir of dirs) {
+      const file = path.join(dir, id + '.md');
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+      add(path.relative(root, file).split(path.sep).join('/'), id);
+      const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+      if (fm) for (const m of fm[1].matchAll(/^[a-z_]*_path[ \t]*:[ \t]*(\S.*?)[ \t]*$/gm)) add(m[1], id);
+      break;
+    }
+  }
+  return owners;
+}
+function changeSignal(root, head, known, opts) {
+  const out = new Set();
+  if (!known.length) return out;
+  const owners = documentOwners(root, known, opts && opts.recordsDir);
+  const ids = new Set(known);
+  const r = gitCap(root, ['log', '--first-parent', '--diff-merges=first-parent', '--format=%x1e%s%x1f', '--name-only', head]);
+  if (!r.ok) return out;
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const subject = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    if (!files.some(isDeliveryPath)) continue;
+    const touched = new Set();
+    for (const f of files) for (const id of owners.get(f) || []) touched.add(id);
+    if (touched.size && touched.size <= MAX_CO_INITIATIVES) for (const id of touched) out.add(id);
+    const b = /^Merge (?:pull request #\d+ from|branch ')\s*(?:[^/\s]+\/)?(?:claude|feature|feat|fix|chore)\/([A-Za-z0-9][\w.-]*?)'?(?:\s|$)/.exec(subject.trim());
+    if (b) {
+      const slug = b[1];
+      const bare = slug.replace(/-[a-z0-9]{4,8}$/, '');
+      if (ids.has(slug)) out.add(slug);
+      else if (bare !== slug && ids.has(bare)) out.add(bare);
+    }
+  }
+  return out;
+}
+
+/*
+ * The branches that actually MERGED — a strictly narrower signal than `byBranch`, and the two are
+ * kept apart on purpose.
+ *
+ * `deliveryIndex` scans every commit's subject AND body, because a squash-merged pull request often
+ * names its branch only in the body. That breadth is right for ATTRIBUTION, where the question is
+ * "is there evidence this initiative's work landed" and a stray match against an id that already has
+ * a record costs nothing.
+ *
+ * It is wrong for any caller that RE-CREATES something from the match. A commit body quoting
+ * `initiative/foo` inside a code example is a real occurrence in this repository's history, and a
+ * caller that wrote a record for every token it found would manufacture initiatives named `foo`,
+ * `save_okr` and `pmos-operating-guide.` out of prose. So this reads MERGE SUBJECTS only, and
+ * requires the id to have the shape ids actually have. On this repository that is the difference
+ * between 4 fabricated records and the 1 that is genuinely missing.
+ */
+const ID_SHAPE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function mergedBranches(root) {
+  const t = trunkRef(root);
+  if (!t) return { ok: false, reason: 'no trunk branch (main/master) is reachable from this repository', ids: new Map() };
+  const r = gitCap(root, ['log', '--merges', '--format=%x1e%H %ct%x1f%s', t.head]);
+  if (!r.ok) return { ok: false, reason: `git could not read the merge history at ${t.ref}`, ids: new Map() };
+  const ids = new Map();               // id -> { sha, at (unix s), subject }
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const [head, subject] = chunk.split('\x1f');
+    const [sha, ct] = String(head || '').trim().split(/\s+/);
+    const subj = String(subject || '').replace(/\s+/g, ' ').trim();
+    /*
+     * A BACK-merge — `merge: main into initiative/x` — merges the trunk INTO the branch, and it is
+     * still EVIDENCE THE BRANCH LANDED: it is only reachable from the trunk at all because the
+     * branch was subsequently merged in. What it must not do is supply the record's title and date,
+     * because it describes mid-flight housekeeping rather than the work, and its date is the
+     * housekeeping's. So it counts, and a landing merge outranks it whenever one exists. The
+     * direction is stated in the subject, so this is a fact rather than a guess.
+     */
+    const back = /\binto\s+\S*initiative\//i.test(subj);
+    for (const m of subj.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) {
+      const id = m[1].replace(/[.,;`'")\]]+$/, '');
+      if (!ID_SHAPE.test(id)) continue;
+      const held = ids.get(id);
+      // The log runs newest-first, so the first LANDING merge seen is the most recent one — and it
+      // always wins over a back-merge, whenever it is found.
+      if (held && (!held.back || back)) continue;
+      ids.set(id, { sha: sha || null, at: Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null, subject: subj, back });
+    }
+  }
+  return { ok: true, ids };
+}
+
+/*
+ * `delivered_by:` — the PM's lever, and the check that keeps it from becoming a status field (R-2b).
+ *
+ * Both signals above are CONVENTIONS. Work delivered under a neighbouring initiative's branch and
+ * commit names satisfies neither, and on this repository that is not hypothetical: the initiative the
+ * PM opened has a PRD, a rubric and shipped code, and no commit on the trunk names it. `null` is the
+ * honest reading of the evidence and it leaves the PM holding a true statement with no way to correct
+ * it.
+ *
+ * So a record may name the commit its work landed in. The reason this does not reintroduce the
+ * declared status that D64 and the engine's own header forbid: `delivered_by` declares a **fact git
+ * can check**, in the shape `reconstructed_from:` already established for a merge date — not a
+ * verdict about where the work stands. The check is the whole point, and it is deliberately strict in
+ * BOTH directions:
+ *
+ *   · reachable from the trunk AND touching at least one build path → `{ok:true}`; the caller
+ *     attributes with signal `declared` and shows the sha it verified.
+ *   · unreachable, unparseable, or reachable while touching nothing that counts as a build →
+ *     `{ok:false, reason}`. The caller renders that BLOCKED, never `done`. A declaration that fails
+ *     its own check is worse than no declaration, because a reader takes it for evidence.
+ */
+function declaredDelivery(root, declared) {
+  const raw = String(declared == null ? '' : declared).trim();
+  if (!raw) return { declared: false };
+  // Take the leading token: the field is `<commit-ish> — free prose`, in the same shape as the
+  // record's other declared keys, so the prose stays available to the PM without breaking the check.
+  const token = raw.split(/[\s,]/)[0].replace(/[.,;]+$/, '');
+  if (!token) return { declared: true, ok: false, reason: 'delivered_by is present but names nothing' };
+  const t = trunkRef(root);
+  if (!t) {
+    return { declared: true, ok: false, unknown: true, reason: 'no trunk branch (main/master) is reachable — delivered_by cannot be verified here' };
+  }
+  const rev = gitCap(root, ['rev-parse', '--verify', '--quiet', `${token}^{commit}`]);
+  if (!rev.ok || !rev.out.trim()) {
+    return { declared: true, ok: false, token, reason: `delivered_by names '${token}', which is not a commit in this repository` };
+  }
+  const sha = rev.out.trim();
+  const anc = gitCap(root, ['merge-base', '--is-ancestor', sha, t.head]);
+  if (!anc.ok) {
+    return { declared: true, ok: false, token, sha, reason: `delivered_by names ${sha.slice(0, 8)}, which is not reachable from ${t.ref} — it has not landed on the trunk` };
+  }
+  const files = gitCap(root, ['show', '--format=', '--name-only', sha]);
+  const touched = files.ok ? files.out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  if (!touched.some(isDeliveryPath)) {
+    return {
+      declared: true, ok: false, token, sha,
+      reason: `delivered_by names ${sha.slice(0, 8)}, which changes no build path — naming a planning commit as the delivery is the false green this check exists to catch`,
+    };
+  }
+  return { declared: true, ok: true, token, sha };
+}
+
+/**
+ * Which signal — if any — attributes a delivery to this initiative.
+ *
+ * `'unknown'` is returned when the index could not be built, and is deliberately NOT `null`. A
+ * caller that collapses the two reports "nothing was delivered" for a repository whose history it
+ * failed to read, which is a claim the missing evidence cannot support.
+ *
+ * @returns {'branch'|'mention'|'change'|'unknown'|null}
+ */
+function attribution(index, id) {
+  if (!index || !index.ok) return 'unknown';
+  if (index.byBranch.has(id)) return 'branch';
+  if (index.byMention.has(id)) return 'mention';
+  if (index.byChange && index.byChange.has(id)) return 'change';
+  return null;
+}
+
+/** The sentence a surface shows for an attribution, so no caller writes its own wording. */
+function attributionEvidence(signal, id, extra) {
+  if (signal === 'branch') return `an initiative/${id} branch merged to the trunk`;
+  if (signal === 'mention') return 'a commit on the trunk names this initiative and changes build files';
+  if (signal === 'change') return 'a change merged to the trunk carried this initiative\'s own documents and build files together';
+  if (signal === 'declared') return `delivered_by ${String(extra || '').slice(0, 8)} — verified on the trunk, and it changes build paths`;
+  if (signal === 'unknown') return 'the trunk history could not be read — delivery cannot be derived here';
+  return 'no commit on the trunk is attributable to this initiative';
+}
+
+// Exported for tests that need a clean read after mutating a fixture's history in place.
+function _resetCache() { deliveryCache.clear(); }
+
+module.exports = {
+  deliveryIndex, attribution, attributionEvidence, declaredDelivery, mergedBranches,
+  isDeliveryPath, trunkRef, documentOwners, _resetCache,
+};

package/workspace/lib/vendor/scripts/intake.js

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

package/workspace/lib/vendor/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 };