rcf-lite 0.28.4 → 0.30.0

package/src/query/readiness.js

@@ -15,8 +15,9 @@
 
 import { computeQueue } from '../build/queue.js';
 import { computeCoverage } from './coverage.js';
-import { computeDelta } from './delta.js';
+import { computeDelta, computeTreeHash, hashDocument } from './delta.js';
 import { computeImpact } from './impact.js';
+import { isProbeRunner } from '../define/probe-runner.js';
 import {
   STAGE_GATES,
   STAGE_ORDER,
@@ -37,6 +38,23 @@ import {
  * @property {string | null} frozenAt
  * @property {string | null} treeHash
  * @property {string} currentTreeHash
+ * @property {string} litmusHash
+ *   The current tree hash computed with the probes ledger excluded
+ *   (ADR-4131 extended, 0.30.0 PR 7 R9, w-2026-10-03-dave-011). The
+ *   probes ledger is inside `currentTreeHash` (ADR-4120), so a litmus
+ *   reading referencing `currentTreeHash` can never match the hash
+ *   recomputed after the write that landed the reading. `litmusHash`
+ *   is the content-stable hash the harness pins litmus readings to:
+ *   writing to the probes ledger does not change it, so n readers can
+ *   land `litmus:<reader>:` entries at the same hash and the --litmus
+ *   check matches them deterministically. Writes to the brief,
+ *   decisions or concerns ledgers do change `litmusHash` the same way
+ *   they change `currentTreeHash`: those changes shift the content
+ *   the readers were attesting to and stale readings fall out of the
+ *   count. The trade-off is intentional: litmus readings do not
+ *   attest to probe findings written after them (probe entries are
+ *   themselves readings, so the attestation applies to the stable
+ *   content, not to its own body).
  * @property {string | null} buildAt   fbsId at the queue head, or null
  * @property {number} fbsTotal
  */
@@ -49,6 +67,24 @@ import {
  * @property {number[]} briefSince
  * @property {import('./impact.js').ImpactNode[]} impacted
  * @property {string[]} impactedFbs
+ * @property {Record<string, string>} currentDocHashes
+ *   Live per-document hashes (ledgers keyed as `ledger:<name>`).
+ *   Threaded from `computeDelta` so the Readiness tab can render a
+ *   document-level hash diff for each changed / added id (spec §5
+ *   block 6; the frozen body is not persisted in the freeze record
+ *   in 0.29.0, so the diff is hash-only for now).
+ */
+
+/**
+ * @typedef {object} CheckResult
+ * @property {string} name
+ * @property {boolean} ok
+ * @property {'delta'|'tree'} over
+ * @property {number} pass
+ * @property {number} total
+ * @property {Array<{ id: string, why: string }>} failing
+ * @property {'productOwner'|'engineer'} persona
+ * @property {string} question
  */
 
 /**
@@ -56,10 +92,47 @@ import {
  * @property {string} stage
  * @property {string} gate
  * @property {'passed'|'failing'|'acknowledged'|'notApplicable'} state
- * @property {Array<{ name: string, ok: boolean, over: 'delta'|'tree', pass: number, total: number, failing: Array<{ id: string, why: string }> }>} checks
+ * @property {CheckResult[]} checks
  * @property {string} [reason]
  */
 
+/**
+ * @typedef {object} Blocker
+ * @property {string} stage
+ * @property {string} gate
+ * @property {string} check
+ * @property {'productOwner'|'engineer'} persona
+ * @property {'delta'|'tree'} over
+ * @property {number} failingCount
+ * @property {string[]} ids
+ * @property {string} question
+ */
+
+/**
+ * @typedef {object} LevelVerdict
+ * @property {boolean} ok
+ * @property {Blocker[]} blockedBy
+ * @property {NextAction | null} nextAction
+ */
+
+/**
+ * @typedef {object} ReadinessLevels
+ * @property {LevelVerdict} intentComplete
+ * @property {LevelVerdict} readyToBuild
+ */
+
+/**
+ * @typedef {object} PersonaGroup
+ * @property {Blocker[]} blockers
+ * @property {NextAction | null} nextAction
+ */
+
+/**
+ * @typedef {object} ReadinessPersonas
+ * @property {PersonaGroup} productOwner
+ * @property {PersonaGroup} engineer
+ */
+
 /**
  * @typedef {object} NextAction
  * @property {string} stage
@@ -77,6 +150,8 @@ import {
  * @property {{ tree: import('./coverage.js').CoverageResult, delta: import('./coverage.js').CoverageResult[] }} coverage
  * @property {Array<Record<string, unknown>>} decisions
  * @property {boolean} freezeable
+ * @property {ReadinessLevels} levels
+ * @property {ReadinessPersonas} personas
  */
 
 /**
@@ -94,6 +169,16 @@ import {
  * @param {string | null | undefined} [args.profileText]  rcf/.identity/profile.md contents
  * @param {Map<string, unknown> | undefined} [args.testPointers]
  * @param {Array<unknown> | undefined} [args.validateErrors]  tree-wide validate + walker errors
+ * @param {Set<string> | undefined} [args.resolvedPaths]  ADR-4131 (0.30.0 PR 5): set of repo-relative paths the
+ *   caller already resolved on disk; threaded into the stage context so
+ *   `shapes:pathsResolve` can decide the D3 bite without I/O. Undefined
+ *   means no paths are known-resolved.
+ * @param {import('../define/probe-runner.js').ProbeRunner | null | undefined} [args.probeRunner]  ADR-4131 extended
+ *   (0.30.0 PR 7, spec section 11.6): injectable `({ reqId, tree }) => findings[]`
+ *   seam called once per REQ in scope; returned findings are merged into
+ *   `ledgers.probes.probes[]` as open probe entries so `consistency:probeCount`
+ *   reports them. Default null: the result equals the 0.29.0 result on the
+ *   same fixture (AC-17504-2). No runner ships; the harness is the runner.
  * @returns {ReadinessResult}
  */
 export function computeReadiness(tree, args = {}) {
@@ -104,6 +189,8 @@ export function computeReadiness(tree, args = {}) {
     profileText = null,
     testPointers = undefined,
     validateErrors = [],
+    resolvedPaths = undefined,
+    probeRunner = null,
   } = args;
 
   // 1. Delta.
@@ -150,6 +237,59 @@ export function computeReadiness(tree, args = {}) {
     ...impactedSeen,
   ]);
 
+  // 3b. Probe seam (ADR-4131 extended, 0.30.0 PR 7). Call the runner
+  // once per REQ in scope and merge the returned findings into the
+  // probe ledger the gate reads. With no runner (the default) nothing
+  // changes and the result equals the 0.29.0 result on the same
+  // fixture (AC-17504-2). The merge is additive and does not mutate
+  // the caller's ledgers object: a new object with a cloned
+  // probes.probes[] is passed down to the gates and surfaces on the
+  // final result through the same ledger consumer.
+  let activeLedgers = ledgers;
+  if (isProbeRunner(probeRunner)) {
+    const reqIdsInScope = [...scopeSet].filter((id) => id.startsWith('REQ-'));
+    /** @type {Array<Record<string, unknown>>} */
+    const injected = [];
+    const priorProbes = /** @type {any} */ (ledgers?.probes);
+    const priorList = Array.isArray(priorProbes?.probes) ? [...priorProbes.probes] : [];
+    const nextId = (() => {
+      let max = 0;
+      for (const entry of priorList) {
+        const n = Number(entry?.id);
+        if (Number.isFinite(n) && n > max) max = n;
+      }
+      return () => { max += 1; return max; };
+    })();
+    for (const reqId of reqIdsInScope) {
+      let findings;
+      try {
+        findings = probeRunner({ reqId, tree });
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(findings)) continue;
+      for (const finding of findings) {
+        if (!finding || typeof finding !== 'object') continue;
+        const text = typeof finding.finding === 'string' ? finding.finding : null;
+        if (!text) continue;
+        injected.push({
+          id: nextId(),
+          reqId: typeof finding.reqId === 'string' ? finding.reqId : reqId,
+          finding: text,
+          severity: typeof finding.severity === 'string' ? finding.severity : 'medium',
+          status: typeof finding.status === 'string' ? finding.status : 'open',
+          addedAt: typeof finding.hash === 'string' ? finding.hash : delta.currentTreeHash,
+        });
+      }
+    }
+    if (injected.length > 0) {
+      activeLedgers = {
+        ...ledgers,
+        probes: { ...(priorProbes ?? {}), probes: [...priorList, ...injected] },
+      };
+    }
+  }
+
   // 4. Coverage: tree-wide plus per REQ ancestor of the delta.
   const coverageTree = computeCoverage(tree, { testPointers, strict: true });
   const deltaReqIds = collectDeltaReqAncestors(tree, pivotIds);
@@ -166,7 +306,7 @@ export function computeReadiness(tree, args = {}) {
   /** @type {import('./gates.js').StageContext} */
   const ctx = {
     tree,
-    ledgers,
+    ledgers: activeLedgers,
     delta,
     freeze,
     scope: scopeSet,
@@ -179,6 +319,7 @@ export function computeReadiness(tree, args = {}) {
     profile,
     currentTreeHash,
     priorStages: undefined,
+    resolvedPaths,
   };
   stages.push(checkD1Brief(ctx));
   stages.push(checkD2Skeleton(ctx));
@@ -198,6 +339,14 @@ export function computeReadiness(tree, args = {}) {
   const freezeable = stages.every((s) => s.state === 'passed' || s.state === 'acknowledged' || s.state === 'notApplicable');
   const nextAction = freezeable ? null : deriveNextAction(stages);
 
+  // 7b. Fold `levels` and `personas` from stages[].checks[] alone
+  // (ADR-4126, proposal section 2.1). Nothing is written. L1
+  // intent-complete is "every productOwner check ok across every
+  // stage"; L2 ready-to-build equals freezeable with blockers over
+  // failing stages only.
+  const levels = deriveLevels(stages, freezeable, nextAction);
+  const personas = derivePersonas(stages, levels);
+
   // 8. Build the tree summary line inputs.
   const queue = computeQueue(tree);
   const fbsTotal = (tree.fbsItems ?? []).length;
@@ -209,6 +358,13 @@ export function computeReadiness(tree, args = {}) {
       frozenAt: delta.frozenAt,
       treeHash: delta.treeHash,
       currentTreeHash: delta.currentTreeHash,
+      // ADR-4131 extended, 0.30.0 PR 7 R9 (w-2026-10-03-dave-011).
+      // The content-stable hash the harness pins litmus readings to:
+      // computed over the tree + brief / decisions / concerns ledgers,
+      // excluding the probes ledger so a reader write does not shift
+      // the hash it pins its own entry to. See computeLitmusHash
+      // JSDoc above for the full rationale and trade-off.
+      litmusHash: computeLitmusHash(tree, activeLedgers),
       buildAt: queue.nextActionable ?? null,
       fbsTotal,
     },
@@ -219,12 +375,15 @@ export function computeReadiness(tree, args = {}) {
       briefSince: delta.briefSince,
       impacted: impactedNodes,
       impactedFbs,
+      currentDocHashes: delta.currentDocHashes ?? {},
     },
     stages,
     nextAction,
     coverage: { tree: coverageTree, delta: coverageDelta },
     decisions: openDecisions,
     freezeable,
+    levels,
+    personas,
   };
 }
 
@@ -266,33 +425,292 @@ function collectDeltaReqAncestors(tree, pivotIds) {
 
 /**
  * Pick the first failing stage in D1..D8 order and the first failing
- * check inside it, then compose a `NextAction`.
+ * check inside it, then compose a `NextAction`. With no `persona`
+ * passed, behaves exactly as 0.28.4 did (first failing stage, first
+ * failing check, largest failing list). With a `persona` ('productOwner'
+ * | 'engineer'), picks the first failing stage that holds a failing
+ * check of that persona, then the largest failing-list check among
+ * them; the command carries `--level intent` on the productOwner
+ * variant and no `--level` flag otherwise (proposal section 2.1).
+ *
+ * The productOwner next action is defined over every stage holding a
+ * failing PO check (not just stages with state `failing`), because
+ * `levels.intentComplete.blockedBy` ignores stage state. In practice
+ * PO checks live on blocking stages (D1, D2, D4, D7) so any failing
+ * PO check also makes its stage `failing`, but the compute does not
+ * rely on that coincidence.
  *
  * @param {StageResult[]} stages
+ * @param {'productOwner' | 'engineer'} [persona]
  * @returns {NextAction | null}
  */
-export function deriveNextAction(stages) {
+export function deriveNextAction(stages, persona) {
   const byStage = new Map(stages.map((s) => [s.stage, s]));
   for (const stageId of STAGE_ORDER) {
     const s = byStage.get(stageId);
-    if (!s || s.state !== 'failing') continue;
+    if (!s) continue;
+    // Without a persona filter: today's rule (stage must be
+    // `failing`; this skips `acknowledged` warn-with-ack stages).
+    // With a persona filter: scan any stage that holds a failing
+    // check of that persona. PO checks only live on blocking stages
+    // so this coincides with "stage failing" in practice, but it
+    // keeps the compute honest if that ever changes.
+    if (!persona && s.state !== 'failing') continue;
+    const failing = s.checks.filter((c) => !c.ok && (persona ? c.persona === persona : true));
+    if (failing.length === 0) continue;
     // First failing check; tie-break by the largest failing list so
     // the operator sees the most impactful gap first.
-    const failing = s.checks.filter((c) => !c.ok);
-    if (failing.length === 0) continue;
     const check = failing.reduce((a, b) => (b.failing.length > a.failing.length ? b : a), failing[0]);
     const ids = [...new Set(check.failing.map((f) => f.id))].slice(0, 20);
     const shortName = STAGE_SHORT_NAMES[stageId] ?? stageId;
+    const command = persona === 'productOwner'
+      ? `rcf define readiness --level intent --check ${shortName}`
+      : `rcf define readiness --check ${shortName}`;
     return {
       stage: stageId,
       check: check.name,
       ids,
-      command: `rcf define readiness --check ${shortName}`,
+      command,
     };
   }
   return null;
 }
 
+/**
+ * Build a `Blocker` row from a stage + check pair. `ids` are
+ * deduplicated and capped at 20 to match the display convention
+ * `nextAction.ids` uses (proposal section 2.1).
+ *
+ * @param {StageResult} stage
+ * @param {CheckResult} check
+ * @returns {Blocker}
+ */
+function makeBlocker(stage, check) {
+  return {
+    stage: stage.stage,
+    gate: stage.gate,
+    check: check.name,
+    persona: check.persona,
+    over: check.over,
+    failingCount: check.failing.length,
+    ids: [...new Set(check.failing.map((f) => f.id))].slice(0, 20),
+    question: check.question,
+  };
+}
+
+/**
+ * Fold the two levels from `stages[].checks[]` (ADR-4126, proposal
+ * section 2.1). L1 ignores stage state and lists every failing PO
+ * check; L2 lists every failing check in a stage whose state is
+ * `failing` (checks inside an `acknowledged` stage are not blockers).
+ *
+ * @param {StageResult[]} stages
+ * @param {boolean} freezeable
+ * @param {NextAction | null} nextAction
+ * @returns {ReadinessLevels}
+ */
+export function deriveLevels(stages, freezeable, nextAction) {
+  /** @type {Blocker[]} */
+  const poBlockers = [];
+  /** @type {Blocker[]} */
+  const buildBlockers = [];
+  for (const stage of stages) {
+    for (const check of stage.checks) {
+      if (check.ok) continue;
+      if (check.persona === 'productOwner') {
+        poBlockers.push(makeBlocker(stage, check));
+      }
+      if (stage.state === 'failing') {
+        buildBlockers.push(makeBlocker(stage, check));
+      }
+    }
+  }
+  const intentOk = poBlockers.length === 0;
+  return {
+    intentComplete: {
+      ok: intentOk,
+      blockedBy: poBlockers,
+      nextAction: intentOk ? null : deriveNextAction(stages, 'productOwner'),
+    },
+    readyToBuild: {
+      ok: freezeable,
+      blockedBy: buildBlockers,
+      nextAction,
+    },
+  };
+}
+
+/**
+ * Fold the `personas` block (ADR-4126, proposal section 3.3).
+ * `productOwner.blockers` deep-equals `levels.intentComplete.blockedBy`;
+ * `engineer.blockers` is the failing engineer checks in failing stages
+ * (the L2 blockedBy minus the PO entries).
+ *
+ * @param {StageResult[]} stages
+ * @param {ReadinessLevels} levels
+ * @returns {ReadinessPersonas}
+ */
+export function derivePersonas(stages, levels) {
+  const engineerBlockers = levels.readyToBuild.blockedBy.filter((b) => b.persona === 'engineer');
+  return {
+    productOwner: {
+      blockers: levels.intentComplete.blockedBy,
+      nextAction: levels.intentComplete.nextAction,
+    },
+    engineer: {
+      blockers: engineerBlockers,
+      nextAction: deriveNextAction(stages, 'engineer'),
+    },
+  };
+}
+
+/**
+ * Validate a `--level` flag value against the closed set
+ * `intent | build`. Returns the value, `null` when the flag was
+ * absent, or throws a usage error whose message is formatted exactly
+ * like the `--check` usage line so the CLI can forward it verbatim.
+ *
+ * @param {string | undefined} raw
+ * @returns {'intent' | 'build' | null}
+ */
+export function parseLevelFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (raw === 'intent' || raw === 'build') return raw;
+  throw new Error(`unknown --level ${raw} (expected intent | build)`);
+}
+
+/**
+ * Validate a `--persona` flag value against the closed set
+ * `productOwner | engineer`. Returns the value, `null` when the flag
+ * was absent, or throws a usage error with the same shape.
+ *
+ * @param {string | undefined} raw
+ * @returns {'productOwner' | 'engineer' | null}
+ */
+export function parsePersonaFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  if (raw === 'productOwner' || raw === 'engineer') return raw;
+  throw new Error(`unknown --persona ${raw} (expected productOwner | engineer)`);
+}
+
+/**
+ * Parse a `--litmus <n>` flag value as a positive integer. Returns
+ * null when the flag is absent, the parsed integer otherwise, or
+ * throws a usage error for a non-integer or non-positive value
+ * (ADR-4131 extended, 0.30.0 PR 7).
+ *
+ * @param {string | undefined} raw
+ * @returns {number | null}
+ */
+export function parseLitmusFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`unknown --litmus ${raw} (expected a positive integer)`);
+  }
+  return n;
+}
+
+/**
+ * Count distinct litmus readers who have landed a probe-ledger entry
+ * at a given tree hash. A litmus reading is a probe-ledger entry
+ * whose `finding` begins `litmus:<reader>:` and whose text includes
+ * the given `hash`. Returns the set of reader ids (deduplicated) that
+ * attest at that hash (ADR-4131 extended, 0.30.0 PR 7). Pure.
+ *
+ * @param {object | undefined | null} ledgers
+ * @param {string | null | undefined} hash
+ * @returns {Set<string>}
+ */
+/**
+ * Compute the litmus hash of a tree + ledger bundle: the tree hash
+ * recomputed with the probes ledger excluded (ADR-4131 extended,
+ * 0.30.0 PR 7 R9, w-2026-10-03-dave-011). The returned string is a
+ * `sha256:<hex>` that is stable under writes to the probes ledger
+ * (so n readers can land `litmus:<reader>:` entries at the same
+ * hash) and that shifts the same way `currentTreeHash` shifts under
+ * writes to the brief, decisions or concerns ledgers (which do
+ * change what the readers were attesting to).
+ *
+ * The function reuses `hashDocument` and `computeTreeHash` from the
+ * delta module; it never touches the filesystem. The brief, decisions
+ * and concerns ledgers contribute their `ledger:<name>` docHash as
+ * they do in `currentTreeHash`; the probes ledger is omitted. The
+ * tree document ids and their hashes are unchanged from the delta
+ * computation.
+ *
+ * Pure.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {import('./delta.js').LedgerBundle | null | undefined} [ledgers]
+ * @returns {string}
+ */
+export function computeLitmusHash(tree, ledgers) {
+  /** @type {Record<string, string>} */
+  const docHashes = {};
+  if (tree && tree.byId) {
+    for (const id of [...tree.byId.keys()].sort()) {
+      docHashes[id] = hashDocument(tree.byId.get(id));
+    }
+  }
+  const bundle = ledgers ?? {};
+  for (const [name, body] of Object.entries(bundle)) {
+    if (name === 'probes') continue;
+    if (body === undefined || body === null) continue;
+    docHashes[`ledger:${name}`] = hashDocument(body);
+  }
+  return computeTreeHash(docHashes);
+}
+
+export function countLitmusReadersAtHash(ledgers, hash) {
+  const readers = new Set();
+  if (typeof hash !== 'string' || hash.length === 0) return readers;
+  const probes = /** @type {any} */ (ledgers?.probes);
+  const list = Array.isArray(probes?.probes) ? probes.probes : [];
+  for (const entry of list) {
+    const text = typeof entry?.finding === 'string' ? entry.finding : '';
+    if (!text.startsWith('litmus:')) continue;
+    const m = text.match(/^litmus:([^:]+):/);
+    if (!m) continue;
+    const combined = typeof entry.hash === 'string' ? `${text} ${entry.hash}` : text;
+    if (!combined.includes(hash)) continue;
+    readers.add(m[1]);
+  }
+  return readers;
+}
+
+/**
+ * Format the two verdict lines shared by the CLI text report and
+ * the Readiness tab (proposal section 2.3). The strings are built
+ * from `levels` alone so the two surfaces cannot disagree.
+ *
+ * @param {ReadinessResult} result
+ * @returns {{ intentComplete: string, readyToBuild: string }}
+ */
+export function formatVerdictLines(result) {
+  const l = result.levels;
+  const intentLine = l.intentComplete.ok
+    ? 'Intent-complete: yes. Every product-owner question is answered.'
+    : (() => {
+      const n = l.intentComplete.blockedBy.length;
+      const detail = l.intentComplete.blockedBy
+        .map((b) => `${b.stage}/${b.check}`)
+        .join(', ');
+      return `Intent-complete: no; ${n} question${n === 1 ? '' : 's'} for the product owner (${detail}).`;
+    })();
+  const buildLine = l.readyToBuild.ok
+    ? `Ready-to-build: yes. Freezeable at ${shortHash(result.tree.currentTreeHash)}.`
+    : (() => {
+      const blockers = l.readyToBuild.blockedBy;
+      const stages = [...new Set(blockers.map((b) => b.stage))].sort();
+      const total = blockers.length;
+      const p = blockers.filter((b) => b.persona === 'productOwner').length;
+      const e = blockers.filter((b) => b.persona === 'engineer').length;
+      return `Ready-to-build: no; blocked on ${stages.join(', ')} (${total} check${total === 1 ? '' : 's'}: ${p} product owner, ${e} engineer).`;
+    })();
+  return { intentComplete: intentLine, readyToBuild: buildLine };
+}
+
 /**
  * Short 8-character prefix of a `sha256:<hex>` string, or '(none)' when
  * absent. Kept exported so text formatters share one convention.