rcf-lite 0.28.1 → 0.28.4

package/src/cli/readiness.js

@@ -0,0 +1,280 @@
+// `rcf define readiness` subcommand handler (REQ-175; proposal
+// 2026-09-22 §2.4, §6.2 v3).
+//
+// Prints the readiness object (§2.4) or its JSON envelope. `--check
+// <stage>` narrows the output to one stage; blocking stages exit 4 on
+// failure (matching `coverage`'s per-AC refusal exit); warn-with-ack
+// stages exit 0 with a visible `[warn]` line on unacknowledged
+// failure. The producer is wrapped with `runWithAdmissibilityGate`
+// (NV-BL-SR-03 addendum) so a chain that refuses admissibility short-
+// circuits with the same refusal envelope every other query verb has.
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveTestPointers, walkTree } from '#core/store';
+import { checkCodeNodeResolution } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+import { loadFreezeRecord } from '../define/freeze-record.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  STAGE_ALIASES,
+  STAGE_GATES,
+  STAGE_ORDER,
+  STAGE_SHORT_NAMES,
+  stagePolicy,
+} from '../query/gates.js';
+import { computeReadiness, formatTreeLine } from '../query/readiness.js';
+import { runWithAdmissibilityGate } from '../query/index.js';
+
+const OPTION_SPEC = {
+  json: { type: 'boolean' },
+  check: { type: 'string' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf define readiness [options]
+
+Compute and print the DEFINE readiness view: whether the tree is
+freezeable, which stage gate blocks, what the delta and its fan-out
+look like, and what the CLI recommends as the next action.
+
+The compute is pure: it composes the freeze delta, per-id impact,
+eight stage-gate checks (D1..D8), tree coverage and open decisions
+into one object. The viewer's Readiness tab (slice 5) will render the
+same object with no schema translation.
+
+Options:
+  --json                    Emit the full readiness object as JSON.
+  --check <stage>           Narrow the output to one stage. Accepts a
+                            stage id (D1..D8) or its short name:
+                            brief | skeleton | shapes | stories |
+                            crosscut | consistency | decisions |
+                            freeze. Exits 4 on a blocking-stage
+                            failure (D1 / D2 / D4 / D7 / D8); exits 0
+                            with a visible '[warn]' line on an
+                            unacknowledged warn-with-ack failure
+                            (D3 / D5 / D6). Use --check all to print
+                            every stage under this exit-code policy.
+  --help                    Print this help.
+`;
+
+/** Text label per stage state, for the chip line. */
+const STATE_LABEL = {
+  passed: 'passed',
+  failing: 'failing',
+  acknowledged: 'acknowledged',
+  notApplicable: 'notApplicable',
+};
+
+/**
+ * Read `rcf/.identity/profile.md` when it exists; return null on
+ * ENOENT. Any other read error surfaces as null so the profile
+ * markers just fail to appear (the D1 check treats absence as a
+ * finding, not a runtime error).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function readProfileText(projectRoot) {
+  try {
+    return await readFile(join(projectRoot, 'rcf', '.identity', 'profile.md'), 'utf8');
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  const checkArg = flags.check;
+  let checkStage = null;
+  if (typeof checkArg === 'string') {
+    if (checkArg === 'all') {
+      checkStage = 'all';
+    } else if (STAGE_ALIASES[checkArg]) {
+      checkStage = STAGE_ALIASES[checkArg];
+    } else {
+      stderr.write(`[error] usage readiness: unknown --check ${checkArg} (expected D1..D8, one of ${Object.values(STAGE_SHORT_NAMES).join(' | ')}, or 'all')\n`);
+      return 2;
+    }
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  const { tree, errors } = await walkTree({ projectRoot });
+  const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+  const validateErrors = [...errors, ...staleErrors];
+
+  const [freeze, ledgers, testPointers, profileText] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+    resolveTestPointers({ projectRoot, tree }),
+    readProfileText(projectRoot),
+  ]);
+
+  const startedAt = Date.now();
+  const chainRulesetVersion = typeof tree.manifest?.rulesetVersion === 'string'
+    ? tree.manifest.rulesetVersion
+    : null;
+
+  // Readiness is a diagnostic: even a chain that refuses admissibility
+  // wants to know which stage gate blocks it. The wrap runs first so
+  // the ruleset toolScope guard is honoured (NV-BL-SR-03 addendum);
+  // on refuse the refusal envelope is threaded through as informational
+  // context and the compute still runs (ADR-4123).
+  const gated = await runWithAdmissibilityGate({
+    tree,
+    chainRulesetVersion,
+    produce: () => computeReadiness(tree, {
+      freeze,
+      ledgers,
+      profile: undefined,
+      profileText,
+      testPointers,
+      validateErrors,
+    }),
+  });
+
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const result = gated.status === 'refused-admissibility'
+    ? computeReadiness(tree, {
+      freeze, ledgers, profile: undefined, profileText, testPointers, validateErrors,
+    })
+    : gated.payload;
+  const wallMs = Date.now() - startedAt;
+
+  if (gated.status === 'refused-admissibility') {
+    stderr.write(`[warn] readiness: chain admissibility refused (informational; the readiness compute still ran). ${gated.refusal}\n`);
+  }
+
+  if (flags.json) {
+    // JSON emission carries the full object plus the wall-time hint
+    // as a stable side-band on `_meta` so consumers can spot
+    // regressions without changing shape.
+    const envelope = { ...result, _meta: { wallMs } };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    return checkStage ? decideExitCode(result, checkStage, stderr) : 0;
+  }
+
+  renderText(stdout, result, wallMs, checkStage);
+  if (checkStage) {
+    return decideExitCode(result, checkStage, stderr);
+  }
+  return 0;
+}
+
+/**
+ * Emit the text summary: tree line, next action, chip line, then a
+ * per-stage failing-items block. When `--check <stage>` names a
+ * stage, only that stage's block is rendered.
+ *
+ * @param {NodeJS.WritableStream} stdout
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {number} wallMs
+ * @param {string | null} checkStage
+ */
+function renderText(stdout, result, wallMs, checkStage) {
+  stdout.write(`${formatTreeLine(result)}\n`);
+  if (!checkStage || checkStage === 'all') {
+    if (result.nextAction) {
+      const ids = result.nextAction.ids.length > 0 ? `; ids: ${result.nextAction.ids.join(', ')}` : '';
+      stdout.write(`Next action: ${result.nextAction.stage} / ${result.nextAction.check}${ids}. Run \`${result.nextAction.command}\` after editing.\n`);
+    } else {
+      stdout.write('Next action: none; every gate passed, acknowledged or notApplicable. Freezeable.\n');
+    }
+    stdout.write(`Chips: ${formatChipLine(result)}\n`);
+    stdout.write(`Delta: changed ${result.delta.changed.length}, added ${result.delta.added.length}, removed ${result.delta.removed.length}, briefSince ${result.delta.briefSince.length}, impacted ${result.delta.impacted.length}, impactedFbs ${result.delta.impactedFbs.length}.\n`);
+    stdout.write(`Coverage: tree ${result.coverage.tree.totals.covered}/${result.coverage.tree.totals.requirements} covered (strict), ${result.coverage.delta.length} REQ ancestor(s) scoped from the delta.\n`);
+    stdout.write(`Decisions open: ${result.decisions.length}.\n`);
+    stdout.write(`Freezeable: ${result.freezeable ? 'yes' : 'no'}. Compute: ${wallMs} ms.\n`);
+  }
+
+  for (const stage of result.stages) {
+    if (checkStage && checkStage !== 'all' && stage.stage !== checkStage) continue;
+    stdout.write(`\n${stage.stage} (${stage.gate}) -- ${STATE_LABEL[stage.state] ?? stage.state}${stage.reason ? ` (${stage.reason})` : ''}\n`);
+    for (const c of stage.checks) {
+      const mark = c.ok ? 'ok' : 'FAIL';
+      stdout.write(`  [${mark}] ${c.name} (${c.over}): ${c.pass}/${c.total}\n`);
+      for (const f of c.failing.slice(0, 20)) {
+        stdout.write(`      - ${f.id}: ${f.why}\n`);
+      }
+      if (c.failing.length > 20) {
+        stdout.write(`      ... ${c.failing.length - 20} more suppressed\n`);
+      }
+    }
+  }
+}
+
+/**
+ * Compose the chip line: "D1:passed D2:failing D3:acknowledged ..."
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @returns {string}
+ */
+function formatChipLine(result) {
+  return result.stages.map((s) => `${s.stage}:${s.state}`).join(' ');
+}
+
+/**
+ * Decide the exit code for a `--check <stage>` invocation:
+ * - passed / acknowledged / notApplicable -> 0
+ * - failing on a blocking stage (D1/D2/D4/D7/D8) -> 4
+ * - failing on a warn-with-ack stage (D3/D5/D6) -> 0 with a stderr [warn]
+ *
+ * The 'all' target folds the individual codes: if any blocking stage
+ * is failing, exit 4; otherwise 0 (warn lines print for each
+ * warn-with-ack failure).
+ *
+ * @param {import('../query/readiness.js').ReadinessResult} result
+ * @param {string} checkStage
+ * @param {NodeJS.WritableStream} stderr
+ * @returns {number}
+ */
+function decideExitCode(result, checkStage, stderr) {
+  const stages = checkStage === 'all'
+    ? result.stages
+    : result.stages.filter((s) => s.stage === checkStage);
+  let exitCode = 0;
+  for (const s of stages) {
+    if (s.state !== 'failing') continue;
+    const policy = stagePolicy(s.stage);
+    if (policy === 'blocking') {
+      exitCode = 4;
+    } else {
+      stderr.write(`[warn] readiness: ${s.stage} (${s.gate}) is failing without an acknowledgement at the current tree hash. Run \`rcf define freeze --ack ${s.gate} --reason "<text>"\` to acknowledge, or edit the tree to clear the failure.\n`);
+    }
+  }
+  return exitCode;
+}
+
+// Re-export the gate map so consumers importing this module (help,
+// slice 3) share one seam.
+export { STAGE_GATES, STAGE_ORDER, STAGE_SHORT_NAMES };

package/src/cli/review.js

@@ -21,7 +21,7 @@ import { parseArgs } from 'node:util';
 import process from 'node:process';
 
 import { rcfError, writeUnexpectedFailure } from '#core/errors';
-import { resolveTestPointers, validateDocument, walkTree } from '#core/store';
+import { resolveTestPointers, validateDocument, validateComposedRecord, walkTree } from '#core/store';
 
 import { findProjectRoot } from '../view/index.js';
 import {
@@ -170,6 +170,14 @@ export async function main(argv, deps = {}) {
   if (flags.json) stdout.write(`${JSON.stringify(record, null, 2)}\n`);
 
   if (flags['dry-run']) {
+    // 0.28.2 (folded into #230, per Barry ruling 2026-09-21):
+    // dry-run runs the same schema pass the writer runs so a preview
+    // reports the same validation error the write path would refuse.
+    const dryValidation = validateComposedRecord({ tree, record, verb: 'review' });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     if (!flags.quiet) {
       stdout.write(`[dry-run] review ${fbsId}: ${findings.length} finding(s); verdict=${record.verdict}\n`);
       for (const f of findings) {

package/src/cli/ui-baseline.js

@@ -21,7 +21,7 @@ import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import process from 'node:process';
 
-import { walkTree } from '#core/store';
+import { walkTree, validateComposedRecord } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
@@ -250,6 +250,19 @@ async function runInit({ tree, projectRoot, stdin, stdout, stderr, flags, now })
   });
 
   if (flags['dry-run']) {
+    // 0.28.2 (folded into #230): dry-run runs the same schema pass
+    // the writer runs so a preview reports the same validation error
+    // the write path would refuse.
+    const dryValidation = validateComposedRecord({
+      tree,
+      record,
+      verb: 'uiBaselineInit',
+      options: { reset: Boolean(flags.reset) },
+    });
+    if (dryValidation) {
+      stderr.write(`[error] ${dryValidation.kind} ${dryValidation.message}\n`);
+      return 3;
+    }
     stdout.write(`${JSON.stringify(record, null, 2)}\n`);
     if (!flags.quiet) stdout.write(`[dry-run] ui-baseline init: would write ${record.id} (${session.optOuts.length} opt-outs).\n`);
     return 0;

package/src/core/store/index.js

@@ -18,3 +18,8 @@ export { checkCodeNodeResolution, splitCnPath } from './cn-resolve.js';
 // never counted as covering an AC.
 export { resolveTestPointers, splitTestPointer, testCaseKey } from './tp-resolve.js';
 export { nextIdForKind, createDocument, updateDocument, deleteDocument, deriveSlug } from './writer.js';
+// 0.28.2 (issues #230/#232 + review/ui-baseline init/browser-verify):
+// shared "compose then schema-validate without writing" helper the
+// dry-run branches of the five discover verbs run so a preview reports
+// the same schema error the writer would refuse on.
+export { validateComposedRecord, buildNextManifest } from './validate-composed-record.js';

package/src/core/store/validate-composed-record.js

@@ -0,0 +1,95 @@
+// Shared validate-composed-record helper (0.28.2, issues #230 / #232
+// and the three folded verbs review / ui-baseline init / browser-verify,
+// per Barry's 2026-09-21 ruling).
+//
+// The bug: five discover verbs shipped a `--dry-run` branch that
+// composed a manifest record and printed it without ever running the
+// same schema pass the write path runs. A `--dry-run` that passed and
+// a real run that failed on schema made the preview untrustworthy for
+// exactly the non-interactive case it exists to serve.
+//
+// The fix: this helper synthesises the "next manifest" for each verb
+// the same way the writer would, then runs `validateDocument` without
+// touching disk. The dry-run branch of each CLI calls this helper and
+// exits 3 on a validation miss, matching the exit code the write path
+// returns today.
+
+import { validateDocument } from './validator.js';
+
+/**
+ * @typedef {'intake' | 'preflight' | 'review' | 'uiBaselineInit' | 'browserVerify'} DryRunVerb
+ */
+
+/**
+ * @param {object} args
+ * @param {object} args.tree                     the walked tree (carries `manifest`)
+ * @param {object} args.record                   the composed record to be written
+ * @param {DryRunVerb} args.verb                 which verb is composing
+ * @param {object[]} [args.extraRecords]         preflight-only: the composed opt-outs
+ * @param {object} [args.options]                per-verb write options (e.g. `{ reset }` for uiBaselineInit)
+ * @returns {import('../errors/index.js').RcfError | null}
+ *   Returns the same shape `validateDocument` returns, so the CLI can
+ *   forward the error to stderr as it would on the write path.
+ */
+export function validateComposedRecord({ tree, record, verb, extraRecords = [], options = {} }) {
+  const manifest = tree?.manifest ?? {};
+  const nextManifest = buildNextManifest({ manifest, record, verb, extraRecords, options });
+  return validateDocument({ doc: nextManifest, kind: 'manifest', filePath: 'rcf/manifest.json' });
+}
+
+/**
+ * Return the next-manifest shape each writer synthesises before its own
+ * `validateDocument` call. Kept in this module so a single test can
+ * assert the dry-run branch and the write branch stay in step across
+ * every verb.
+ *
+ * @param {object} args
+ * @param {object} args.manifest
+ * @param {object} args.record
+ * @param {DryRunVerb} args.verb
+ * @param {object[]} [args.extraRecords]
+ * @param {object} [args.options]
+ * @returns {object}
+ */
+export function buildNextManifest({ manifest, record, verb, extraRecords = [], options = {} }) {
+  const base = { ...(manifest ?? {}) };
+  switch (verb) {
+    case 'intake': {
+      return { ...base, intakeClassification: record };
+    }
+    case 'preflight': {
+      const existing = Array.isArray(base.preFlightConfig) ? base.preFlightConfig : [];
+      const next = { ...base, preFlightConfig: [...existing, record] };
+      if (Array.isArray(extraRecords) && extraRecords.length > 0) {
+        const existingOptOuts = Array.isArray(next.baselineAcOptOuts) ? next.baselineAcOptOuts : [];
+        next.baselineAcOptOuts = [...existingOptOuts, ...extraRecords];
+      }
+      return next;
+    }
+    case 'review': {
+      const existing = Array.isArray(base.reviewAudit) ? base.reviewAudit : [];
+      return { ...base, reviewAudit: [...existing, record] };
+    }
+    case 'uiBaselineInit': {
+      // Mirror writeUiBaselineRecord: on `--reset` the prior
+      // uiBaseline moves into uiBaselineHistory. Without --reset the
+      // prior is replaced in place. The dry-run path calls this
+      // helper without options and matches the reset=false branch.
+      const next = { ...base };
+      const prior = next.uiBaseline ?? null;
+      const reset = Boolean(options && options.reset);
+      if (prior && reset) {
+        const history = Array.isArray(next.uiBaselineHistory) ? next.uiBaselineHistory : [];
+        next.uiBaselineHistory = [...history, prior];
+      }
+      next.uiBaseline = record;
+      return next;
+    }
+    case 'browserVerify': {
+      const existing = Array.isArray(base.browserVerification) ? base.browserVerification : [];
+      return { ...base, browserVerification: [...existing, record] };
+    }
+    default:
+      throw new Error(`validateComposedRecord: unknown verb ${verb}`);
+  }
+}

package/src/core/store/writer.js

@@ -200,18 +200,98 @@ export function nextIdForKind(tree, kind, opts = {}) {
       // one numbering group.
       const groupNum = Number(normaliseId(match[1]));
       const groupLabel = String(groupNum);
+      // Occupancy is every US id in the tree. Each id is classified as
+      // ENCODED (`US-<reqNum><localTwoDigit>` where the reqNum names an
+      // existing REQ and local is 01..99) or FLAT (a bare sequential
+      // number that carries no parent-encoded suffix, as produced by
+      // legacy trees migrated in from WESPA v1). Classification decides
+      // the allocation rule:
+      //   - all-encoded tree (or empty): the historical rule, extend
+      //     `US-<groupLabel><nextLocal>`.
+      //   - all-flat tree: extend the flat sequence past the highest
+      //     existing US number (issue #256 / w-2026-09-29-dave-005).
+      //   - mixed tree: refuse the mint with an explicit error naming
+      //     both schemes, so an operator normalises the tree before a
+      //     new id is issued (Dave disposition 2026-09-30).
+      // AC minting is unchanged; #256 was reproduced against USes only.
+      // Classification prefers the doc's declared reqId (unambiguous) over
+      // the id-only heuristic. Without that, a legacy US-163 filed under
+      // REQ-053 would decompose as parent=1/local=63 and look encoded
+      // whenever REQ-001 happened to exist, defeating the whole rule.
+      const usIds = occupiedIdsOfKind(tree, 'userStory');
+      const reqNums = new Set();
+      for (const rId of occupiedIdsOfKind(tree, 'req')) {
+        const rn = idNumber(rId, 'REQ');
+        if (rn !== null) reqNums.add(rn);
+      }
+      const encoded = [];
+      const flat = [];
+      const seenUsNums = new Set();
+      for (const usId of usIds) {
+        const num = idNumber(usId, 'US');
+        if (num === null) continue;
+        // occupiedIdsOfKind emits both the on-disk id and the doc's
+        // declared id field, so the same numeric id appears twice.
+        // Dedupe on the numeric value to avoid double-counting.
+        if (seenUsNums.has(num)) continue;
+        seenUsNums.add(num);
+        const localPart = num % 100;
+        const parentPart = Math.floor(num / 100);
+        const doc = tree.byId.get(usId);
+        let declaredReqNum = null;
+        if (doc && typeof doc.reqId === 'string') {
+          const mReq = /^REQ-(\d+)$/.exec(doc.reqId);
+          if (mReq) declaredReqNum = Number(normaliseId(mReq[1]));
+        }
+        let isEncoded;
+        if (declaredReqNum !== null) {
+          // Encoded iff the id decomposes as <declaredReqNum><two-digit
+          // local in 01..99>. Any other shape is flat.
+          isEncoded = (localPart >= 1 && localPart <= 99 && parentPart === declaredReqNum);
+        } else {
+          // Invalid / unloadable doc: fall back to the id-only heuristic
+          // (matches historical behaviour when the parent-part names an
+          // existing REQ).
+          isEncoded = (localPart >= 1 && localPart <= 99 && reqNums.has(parentPart));
+        }
+        if (isEncoded) {
+          encoded.push({ id: usId, num, parentPart, localPart });
+        } else {
+          flat.push({ id: usId, num });
+        }
+      }
+
+      if (encoded.length > 0 && flat.length > 0) {
+        const encodedExample = encoded[0].id;
+        const flatExample = flat[0].id;
+        throw new TypeError(
+          'nextIdForKind us: refusing to mint - the tree mixes '
+          + `encoded US ids (e.g. ${encodedExample}, shape US-<reqNum><localTwoDigit>) `
+          + `and flat US ids (e.g. ${flatExample}, shape US-<seq>). `
+          + 'Normalise every US id to one scheme (rename the outliers, '
+          + 'update every reference) and retry, or ask HQ for a bulk '
+          + 're-mint. Auto-mint intentionally refuses on ambiguous trees.',
+        );
+      }
+
+      if (flat.length > 0 && encoded.length === 0) {
+        let maxFlat = 0;
+        for (const f of flat) {
+          if (f.num > maxFlat) maxFlat = f.num;
+        }
+        return `US-${maxFlat + 1}`;
+      }
+
+      // All-encoded (or empty) tree: keep the historical behaviour.
       // Occupancy is every US id that numerically falls in this group,
       // whatever `reqId` string it names. Filtering on an exact reqId
       // string match was the bug: a US filed under `REQ-0001` was
       // invisible when allocating for `REQ-001`, so US-101 got re-issued
       // on top of the existing US-101.
-      const usIds = occupiedIdsOfKind(tree, 'userStory');
       let maxLocal = 0;
-      for (const usId of usIds) {
-        const num = idNumber(usId, 'US');
-        if (num === null) continue;
-        const local = num - groupNum * 100;
-        if (local >= 1 && local <= 99 && local > maxLocal) maxLocal = local;
+      for (const e of encoded) {
+        if (e.parentPart !== groupNum) continue;
+        if (e.localPart > maxLocal) maxLocal = e.localPart;
       }
       const nextLocal = maxLocal + 1;
       return `US-${groupLabel}${String(nextLocal).padStart(2, '0')}`;