rcf-lite 0.29.0 → 0.30.0

package/src/cli/build.js

@@ -18,6 +18,10 @@
 
 import { writeFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 import { formatErrors, isRcfError, rcfError, writeUnexpectedFailure } from '#core/errors';
 import { updateDocument, walkTree } from '#core/store';
@@ -41,6 +45,14 @@ import { firstBaselineDisagreement } from '../design/index.js';
 import { writeBrowserVerificationAck } from '../browser-verify/index.js';
 // Track C+D §5.4 Stage-1 refusal gate.
 import { fbsRefusalForOpenSweep } from '../req-baseline/gate.js';
+// 0.30.0 PR 8 (REQ-177 / TAC-4125): bundle --next freeze gate.
+import { computeDelta } from '../query/delta.js';
+import { computeImpact } from '../query/impact.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  applyOverrideToFreezeRecord,
+  loadFreezeRecord,
+} from '../define/freeze-record.js';
 
 const OPTION_SPEC = {
   next: { type: 'boolean' },
@@ -60,6 +72,12 @@ const OPTION_SPEC = {
   // browserVerification record.
   'accept-block': { type: 'boolean' },
   reason: { type: 'string' },
+  // 0.30.0 PR 8 (REQ-177, AC-17702-2 / AC-17702-4). Bundle --next with
+  // --override "<reason>" writes freeze.override { reason, by, at } and
+  // proceeds; without --override the verb refuses on an unfrozen tree
+  // (AC-17702-1) and when every actionable FBS is impacted by the
+  // delta (AC-17702-4).
+  override: { type: 'string' },
 };
 
 export const HELP = `Usage: rcf build <verb> [options]
@@ -96,6 +114,11 @@ Options (bundle):
   --strict                  Refuse (exit 4) a bundle for a blocked item;
                             no effect with --next (it never selects
                             blocked items)
+  --override "<reason>"     With --next: proceed on an unfrozen tree or
+                            an all-impacted delta, recording
+                            freeze.override { reason, by, at } (REQ-177,
+                            0.30.0 PR 8). The reason must be a
+                            non-empty string.
 
 Options (queue):
   --format <format>         md (default) | json
@@ -292,7 +315,10 @@ export async function main(argv, deps = {}) {
     return 0;
   }
   if (mode === 'next') {
-    return await emitNext({ tree, format, io });
+    return await emitNext({
+      tree, projectRoot, format, io,
+      overrideReason: typeof flags.override === 'string' ? flags.override : null,
+    });
   }
   return await emitBundle({
     tree, fbsId: positional, format, strict: Boolean(flags.strict), io,
@@ -356,9 +382,186 @@ async function emitBundle({ tree, fbsId, format, strict, io }) {
   return await emitToSink(output, io);
 }
 
-async function emitNext({ tree, format, io }) {
+/**
+ * 0.30.0 PR 9 (TAC-4125; AC-17702-6): resolve the author identity for
+ * `freeze.override.by`. Preference order (first non-empty wins):
+ *
+ *   1. `git config user.email` under `projectRoot` (the identity git
+ *      itself would attribute an override commit to; CI usually sets
+ *      this through its own git config step).
+ *   2. `GITHUB_ACTOR` (set by GitHub Actions on every run so a CI
+ *      override is attributed to the actor who triggered the workflow,
+ *      even when no git identity is configured).
+ *   3. `USER` or `USERNAME` (local shell identity on Unix / Windows).
+ *   4. The literal string `operator` (never-null fallback so the write
+ *      path cannot blow up on a stripped-down container).
+ *
+ * Pure of side effects beyond the one `git config` read; the git call
+ * is bounded to a short argv and never writes. Errors from `git
+ * config` (no `.git`, no git binary, missing key) fall through to the
+ * next arm silently; the resolution's shape is a single string.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<string>}
+ */
+export async function resolveOverrideBy({ projectRoot }) {
+  // 1. git config user.email (bounded; refuses to log on failure).
+  try {
+    const { stdout } = await execFileAsync(
+      'git', ['config', '--get', 'user.email'],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 2000 },
+    );
+    const email = stdout.trim();
+    if (email.length > 0) return email;
+  } catch {
+    // Fall through to the environment arms.
+  }
+  // Env arms are trimmed so a whitespace-only value does not win
+  // over the next arm (codex review 2026-10-03, P2).
+  const envArm = (key) => {
+    const v = process.env[key];
+    if (typeof v !== 'string') return null;
+    const t = v.trim();
+    return t.length > 0 ? t : null;
+  };
+  // 2. GITHUB_ACTOR (GitHub Actions).
+  const actor = envArm('GITHUB_ACTOR');
+  if (actor) return actor;
+  // 3. USER or USERNAME.
+  const user = envArm('USER');
+  if (user) return user;
+  const username = envArm('USERNAME');
+  if (username) return username;
+  // 4. Never-null fallback.
+  return 'operator';
+}
+
+/**
+ * 0.30.0 PR 8 (REQ-177, TAC-4125): freeze gate for `bundle --next`.
+ * Loads the freeze record and the computed delta, writes
+ * freeze.override when --override "<reason>" is given, computes the
+ * set of re-execute FBS impacted by the delta, and returns a refusal
+ * when the tree is unfrozen and no override is given.
+ *
+ * Pure of CLI I/O: it writes freeze.override through the freeze-record
+ * module (which is the normal write path) but prints no output; the
+ * caller surfaces the refusal and the override line.
+ *
+ * @param {object} args
+ * @param {object} args.tree - walker tree.
+ * @param {string} args.projectRoot
+ * @param {string|null} args.overrideReason - the --override flag value, or null when absent.
+ * @returns {Promise<{ ok: true, impactedFbsIds: Set<string>, override: {reason:string, by:string, at:string}|null } | { ok: false, exitCode: 2|4, message: string }>}
+ */
+async function enforceBundleNextFreezeGate({ tree, projectRoot, overrideReason }) {
+  if (overrideReason !== null && (typeof overrideReason !== 'string' || overrideReason.length === 0)) {
+    return {
+      ok: false,
+      exitCode: 2,
+      message: 'build bundle --next: --override requires a non-empty reason (e.g. --override "hotfix")',
+    };
+  }
+  const [freeze, ledgers] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+  ]);
+  const delta = computeDelta(tree, freeze, ledgers);
+  if (!delta.frozen && overrideReason === null) {
+    return {
+      ok: false,
+      exitCode: 4,
+      message:
+        'build bundle --next: refused on an unfrozen tree. Run `rcf define readiness` and close the change with `rcf define freeze`, '
+        + 'or re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-01).',
+    };
+  }
+  let appliedOverride = null;
+  if (overrideReason !== null) {
+    const at = new Date().toISOString();
+    const by = await resolveOverrideBy({ projectRoot });
+    const { record } = await applyOverrideToFreezeRecord({
+      projectRoot,
+      reason: overrideReason,
+      by,
+      at,
+      docHashes: delta.currentDocHashes ?? {},
+      treeHash: delta.currentTreeHash,
+      briefStatements: ledgers?.brief?.statements?.length ?? 0,
+    });
+    appliedOverride = record.override;
+  }
+  // Compute impacted FBS set when the tree is frozen (unfrozen trees
+  // have no base to compare against; AC-17702-5 governs that path).
+  // "Impacted" means an FBS that must be re-executed because its own
+  // definition changed OR because it fans out from a changed/added
+  // pivot (REQ, US, AC, TAC, ADR) via expandFbsDependents.
+  const impactedFbsIds = new Set();
+  if (delta.frozen) {
+    const pivotIds = [
+      ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+      ...delta.added.filter((id) => !id.startsWith('ledger:')),
+    ];
+    // A changed/added FBS is itself impacted.
+    for (const id of pivotIds) {
+      if (typeof id === 'string' && id.startsWith('FBS-')) impactedFbsIds.add(id);
+    }
+    const seen = new Set();
+    for (const id of pivotIds) {
+      const impact = computeImpact(tree, { id });
+      if (!impact.found || !Array.isArray(impact.nodes)) continue;
+      for (const node of impact.nodes) {
+        if (seen.has(node.id)) continue;
+        seen.add(node.id);
+        if (node.kind === 'fbs' && node.role !== 'pivot' && node.actionNeeded === 're-execute') {
+          impactedFbsIds.add(node.id);
+        }
+      }
+    }
+  }
+  return { ok: true, impactedFbsIds, override: appliedOverride };
+}
+
+async function emitNext({ tree, projectRoot, format, io, overrideReason = null }) {
+  // 0.30.0 PR 8 (REQ-177 / TAC-4125): refuse without a freeze record,
+  // write freeze.override on --override "<reason>" and proceed, skip
+  // impacted FBS from the next-item selection.
+  const gate = await enforceBundleNextFreezeGate({
+    tree, projectRoot, overrideReason,
+  });
+  if (!gate.ok) {
+    io.stderr.write(`[error] ${gate.message}\n`);
+    return gate.exitCode;
+  }
+  if (gate.override) {
+    const o = gate.override;
+    io.stderr.write(`[info] build bundle --next: freeze.override recorded (reason=${JSON.stringify(o.reason)}, by=${o.by}, at=${o.at}).\n`);
+  }
+  // Skip FBS impacted by a non-empty delta; the next-item compute
+  // walks the queue from the top and the first unimpacted actionable
+  // FBS wins. Every skipped FBS is named on stderr with the reason.
   const queue = computeQueue(tree);
-  const next = selectNext(queue);
+  let next = null;
+  if (gate.impactedFbsIds.size === 0) {
+    next = selectNext(queue);
+  } else {
+    for (const item of queue.items) {
+      if (item.state !== 'actionable') continue;
+      if (gate.impactedFbsIds.has(item.fbsId)) {
+        io.stderr.write(`[info] build bundle --next: skipping ${item.fbsId} (impacted by the delta; re-freeze or re-execute first).\n`);
+        continue;
+      }
+      next = { fbsId: item.fbsId };
+      break;
+    }
+  }
+  if (!next && gate.impactedFbsIds.size > 0 && overrideReason === null) {
+    io.stderr.write(
+      '[error] build bundle --next: refused because every actionable FBS is impacted by the delta. '
+      + 'Re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-05).\n',
+    );
+    return 4;
+  }
   if (next) {
     // Track C+D §5.4: Stage-1 (Define) refuses to enter Build for any
     // FBS binding an AC on a US that still has open baseline sweep

package/src/cli/freeze.js

@@ -43,7 +43,12 @@ import {
   parseAcClass,
 } from '../query/gates.js';
 import { computeDelta, hashDocument } from '../query/delta.js';
-import { computeReadiness, shortHash } from '../query/readiness.js';
+import {
+  computeReadiness,
+  countLitmusReadersAtHash,
+  parseLitmusFlag,
+  shortHash,
+} from '../query/readiness.js';
 import { runWithAdmissibilityGate } from '../query/index.js';
 
 const OPTION_SPEC = {
@@ -51,6 +56,7 @@ const OPTION_SPEC = {
   reason: { type: 'string', multiple: true },
   note: { type: 'string' },
   'litmus-attested': { type: 'string' },
+  litmus: { type: 'string' },
   status: { type: 'boolean' },
   json: { type: 'boolean' },
   help: { type: 'boolean' },
@@ -110,6 +116,17 @@ Options:
                             elicitation prompts in the current session
                             (proposal §9 decision 7). Recorded in
                             freeze.litmus.attestedAt.
+  --litmus <n>              Require n distinct litmus readings at the
+                            current tree hash before freezing (0.30.0
+                            PR 7, ADR-4131 extended). A litmus reading
+                            is a probe-ledger entry whose finding
+                            begins litmus:<reader>: and whose text
+                            includes the current tree hash. Fewer
+                            than n distinct readers exits 4 naming
+                            the shortfall and writes nothing. No
+                            process is spawned and no network call is
+                            made; the harness lands the readings
+                            through rcf define ledger probes add.
   --status                  Print the current freeze record and the
                             live delta summary; run no gates; write
                             nothing. Exits 0 even when unfrozen.
@@ -165,6 +182,16 @@ export async function main(argv, deps = {}) {
     return 2;
   }
 
+  // --litmus parsing (ADR-4131 extended, 0.30.0 PR 7).
+  /** @type {number | null} */
+  let litmus;
+  try {
+    litmus = parseLitmusFlag(flags.litmus);
+  } catch (err) {
+    stderr.write(`[error] usage freeze: ${/** @type {Error} */ (err).message}\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');
@@ -178,7 +205,7 @@ export async function main(argv, deps = {}) {
 
   // Freeze branch.
   return runFreeze({
-    projectRoot, flags, ackPairs, now, stdout, stderr,
+    projectRoot, flags, ackPairs, litmus, now, stdout, stderr,
   });
 }
 
@@ -298,13 +325,14 @@ function formatStatusLine(record) {
  * @param {string} args.projectRoot
  * @param {Record<string, unknown>} args.flags
  * @param {Array<{ gate: string, reason: string }>} args.ackPairs
+ * @param {number | null} args.litmus
  * @param {() => Date} args.now
  * @param {NodeJS.WritableStream} args.stdout
  * @param {NodeJS.WritableStream} args.stderr
  * @returns {Promise<number>}
  */
 async function runFreeze({
-  projectRoot, flags, ackPairs, now, stdout, stderr,
+  projectRoot, flags, ackPairs, litmus, now, stdout, stderr,
 }) {
   const { tree, errors } = await walkTree({ projectRoot });
   const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
@@ -335,26 +363,31 @@ async function runFreeze({
     ? priorFreeze
     : mergeAckedGates(priorFreeze, ackedReasons, currentTreeHash);
 
+  // Compute readiness up front so the admissibility wrap can cite
+  // NV-DL-ADM-02/03/04 alongside the NV-BL rules (PR 9). The
+  // freezeableAfterAck check below is the real gate (freeze still
+  // exits 4 on an unfrozen tree); the wrap's refusal is informational
+  // here as it is on readiness.
+  /** @type {import('../query/readiness.js').ReadinessResult} */
+  const readiness = computeReadiness(tree, {
+    freeze: freezeForCompute,
+    ledgers,
+    profileText,
+    testPointers,
+    validateErrors,
+  });
   const gated = await runWithAdmissibilityGate({
     tree,
     chainRulesetVersion,
-    produce: () => computeReadiness(tree, {
-      freeze: freezeForCompute,
-      ledgers,
-      profileText,
-      testPointers,
-      validateErrors,
-    }),
+    defineStages: readiness.stages,
+    defineValidateErrors: validateErrors,
+    produce: () => readiness,
   });
   if (gated.status === 'refused-admissibility') {
     stderr.write(`[warn] freeze: chain admissibility refused (informational; the freeze still ran). ${gated.refusal}\n`);
+  } else if (Array.isArray(gated.defineRules) && gated.defineRules.length > 0) {
+    stderr.write(`[warn] freeze: DEFINE-stage admissibility rules bite (informational; the freezeableAfterAck gate is the enforcement path): [${gated.defineRules.join(', ')}].\n`);
   }
-  /** @type {import('../query/readiness.js').ReadinessResult} */
-  const readiness = gated.status === 'refused-admissibility'
-    ? computeReadiness(tree, {
-      freeze: freezeForCompute, ledgers, profileText, testPointers, validateErrors,
-    })
-    : gated.payload;
 
   // The stages array already carries acknowledged states for any acked
   // gate at the current tree hash. Stamp the ack reasons onto the
@@ -376,6 +409,23 @@ async function runFreeze({
     return 4;
   }
 
+  // --litmus check (ADR-4131 extended, 0.30.0 PR 7; R9 clarified
+  // 2026-10-03, w-2026-10-03-dave-011). Count distinct readers who
+  // have landed a probe-ledger entry at the current LITMUS HASH whose
+  // finding begins litmus:<reader>:; refuse (exit 4 and write nothing)
+  // when fewer than n have attested. The litmus hash is the tree hash
+  // computed with the probes ledger excluded (see computeLitmusHash in
+  // src/query/readiness.js) so a reader's own write does not shift the
+  // hash it is attesting to.
+  if (typeof litmus === 'number' && litmus > 0) {
+    const hash = readiness.tree.litmusHash;
+    const readers = countLitmusReadersAtHash(ledgers, hash);
+    if (readers.size < litmus) {
+      stderr.write(`[error] freeze: --litmus ${litmus} requires ${litmus} distinct litmus reading(s) at litmus hash ${hash}; found ${readers.size}. Spawn ${litmus - readers.size} more fresh-context reader(s) and land their readings through \`rcf define ledger probes add --req <reqId> --finding "litmus:<reader>: ..." --severity low\` with the litmus hash in the finding text (read it from \`rcf define readiness --json\` under \`tree.litmusHash\`).\n`);
+      return 4;
+    }
+  }
+
   // Build the freeze record body.
   const frozenAt = now().toISOString();
   // Sanity: the tree hash the readiness compute reports must match the
@@ -391,7 +441,7 @@ async function runFreeze({
   const gates = buildGatesEntry(stagesAfterAck, currentTreeHash, frozenAt);
   const counts = deriveCounts(tree);
   const litmusAttested = parseLitmusAttested(flags['litmus-attested']);
-  const litmus = { attestedAt: litmusAttested, readers: 0 };
+  const litmusRecord = { attestedAt: litmusAttested, readers: 0 };
   const versions = await readVersions(projectRoot);
   const note = typeof flags.note === 'string' ? flags.note : null;
 
@@ -403,7 +453,7 @@ async function runFreeze({
     briefStatements,
     gates,
     counts,
-    litmus,
+    litmus: litmusRecord,
     versions,
     note,
     override: null,