rcf-lite 0.29.0 → 0.31.0

package/src/cli/create.js

@@ -64,8 +64,11 @@ Options:
                             every non-root child carries a mandatory
                             parentId-style field). See the parent table
                             above for which id each kind expects.
-  --id <id>                 Override auto-assigned id (refuses on
-                            collision)
+  --id <id>                 Override auto-assigned id. Idempotent by id:
+                            an existing id with identical content is a
+                            no-op ('<id>: unchanged', exit 0); with
+                            different content it refuses (exit 3, names
+                            the differing fields). Use update to patch
   --title <string>          Required for req / us / tac / adr / fbs / ts
                             (ac / tc use --description)
   --description <string>    Body description; required for ac / tc
@@ -297,6 +300,15 @@ export async function main(argv, deps = {}) {
   if (isRcfError(result)) {
     return handleWriterError(result, stderr);
   }
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up, w-2026-10-05-dave-013):
+  // a same-id replay with identical content exits 0 with 'unchanged';
+  // the file is not rewritten. Mirrors `rcf define ledger add --id`.
+  if (result.status === 'unchanged') {
+    if (!flags.quiet) {
+      stdout.write(`${result.id}: unchanged (${result.filePath})\n`);
+    }
+    return 0;
+  }
   if (options.dryRun) {
     if (!flags.quiet) stdout.write(`[dry-run] would create ${result.id} at ${result.filePath}\n`);
     return 0;
@@ -358,6 +370,10 @@ const ERROR_KINDS = new Set([
   'parseFailure',
   'ioFailure',
   'usage',
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): a same-id
+  // create whose would-be body differs from the existing doc refuses
+  // with `kind: 'conflict'` and exits 3 (never silently overwrites).
+  'conflict',
 ]);
 
 function isRcfError(value) {
@@ -412,6 +428,10 @@ function handleWriterError(err, stderr) {
   stderr.write(`[error] ${kind} ${err.message}\n`);
   if (kind === 'usage') return 2;
   if (kind === 'validation' || kind === 'brokenReference') return 3;
+  // Ruling R1 extension 2026-10-05 (PR 292 follow-up): a same-id
+  // create with different content refuses with exit 3; `update` is
+  // the verb for patching.
+  if (kind === 'conflict') return 3;
   if (kind === 'missingFile' || kind === 'parseFailure') return 2;
   return 1;
 }

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,

package/src/cli/ledger.js

@@ -27,6 +27,7 @@ import { runIntakeScansOnDelta } from '../intake/orchestrator.js';
 import { findProjectRoot } from '../view/index.js';
 
 const OPTION_SPEC = {
+  id: { type: 'string' },
   kind: { type: 'string' },
   text: { type: 'string' },
   from: { type: 'string' },
@@ -74,6 +75,15 @@ Common flags:
   --help                    Print this help
 
 brief add flags:
+  --id <n>                  Optional positive integer. When set, the add
+                            is idempotent by id (ruling R1 2026-10-05):
+                            an entry at that id with identical content
+                            exits 0 printing 'unchanged' (--json emits
+                            {status:"unchanged",id:n}); different content
+                            at the same id exits 3 naming the differing
+                            fields; a free id is honoured as the override.
+                            The harness carries --id back when it replays
+                            a turn so the add is a no-op on replay.
   --kind <${BRIEF_KINDS.join('|')}>
                             Statement kind (default: capability)
   --text <text>             The statement text (mutually exclusive with --from)
@@ -193,6 +203,14 @@ export async function main(argv, deps = {}) {
     return await runResolve({ projectRoot, name, positionals, flags, stdout, stderr });
   } catch (err) {
     if (err instanceof LedgerError) {
+      // Ruling R1 2026-10-05: a same-id-different-content refusal
+      // exits 3 (not 1 and not 2) so a replaying harness can
+      // distinguish 'you tried to overwrite a prior answer' from a
+      // schema failure or a usage error. Update is the verb for that.
+      if (err.code === 'conflict') {
+        stderr.write(`[error] ledger: ${err.message}\n`);
+        return 3;
+      }
       stderr.write(`[error] ${err.code === 'usage' ? 'usage ' : ''}ledger: ${err.message}\n`);
       return err.code === 'usage' ? 2 : 1;
     }
@@ -285,6 +303,19 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
   const body = await loadLedger({ projectRoot, name });
   const now = new Date().toISOString();
 
+  // Ruling R1 2026-10-05: parse --id up front; a non-integer or negative
+  // value is a usage error BEFORE loading / scanning the ledger.
+  /** @type {number | undefined} */
+  let idOverride;
+  if (flags.id !== undefined) {
+    const parsed = Number(flags.id);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      stderr.write(`[error] usage ledger: --id must be a positive integer, got '${flags.id}'\n`);
+      return 2;
+    }
+    idOverride = parsed;
+  }
+
   if (name === 'brief') {
     const kind = /** @type {string} */ (flags.kind ?? 'capability');
     if (!BRIEF_KINDS.includes(/** @type {any} */ (kind))) {
@@ -299,6 +330,12 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       stderr.write('[error] usage ledger: brief add requires --text <text> or --from <path>\n');
       return 2;
     }
+    if (idOverride !== undefined && flags.from) {
+      // R1 identity is per entry; --from mints N entries, so --id has no
+      // single target. Refuse the combination to keep the harness honest.
+      stderr.write('[error] usage ledger: brief add --id applies to --text only (--from mints one entry per line and has no single id)\n');
+      return 2;
+    }
     if (flags['no-scan'] && flags.findings) {
       stderr.write('[error] usage ledger: brief add --no-scan and --findings cannot be combined\n');
       return 2;
@@ -336,10 +373,32 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
     // Compute what WOULD be minted (for both the real path and dry-run).
     let cur = body;
     const added = [];
+    /** @type {'added' | 'unchanged'} */
+    let primaryStatus = 'added';
     for (const d of drafts) {
-      const step = addEntry({ name: 'brief', body: cur, entry: d, now });
+      // Only the single --text path reaches here with an idOverride (we
+      // refused --id with --from above); a per-call idOverride is passed
+      // on the first and only draft.
+      const step = addEntry({
+        name: 'brief', body: cur, entry: d, now,
+        ...(idOverride !== undefined ? { id: idOverride } : {}),
+      });
       cur = step.body;
       added.push(step.entry);
+      if (step.status === 'unchanged') primaryStatus = 'unchanged';
+    }
+
+    // Ruling R1 2026-10-05 short-circuit: when --id landed on an entry
+    // that already carried identical content, exit 0 with the unchanged
+    // signal before any scan / finding work. A replayed turn is a no-op.
+    if (primaryStatus === 'unchanged' && added.length === 1) {
+      const existing = added[0];
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: existing.id, entry: existing }, null, 2)}\n`);
+      } else {
+        stdout.write(`brief-ledger: unchanged ${existing.id}\n`);
+      }
+      return 0;
     }
 
     // Convert operator-supplied --findings into openQuestion statements.
@@ -428,7 +487,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       default: flags.default ? String(flags.default) : null,
     };
     if (flags.blocks) entry.blocks = String(flags.blocks);
-    const step = addEntry({ name: 'decisions', body, entry, now });
+    const step = addEntry({
+      name: 'decisions', body, entry, now,
+      ...(idOverride !== undefined ? { id: idOverride } : {}),
+    });
+    if (step.status === 'unchanged') {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+      } else {
+        stdout.write(`decisions-ledger: unchanged ${step.entry.id}\n`);
+      }
+      return 0;
+    }
     await saveLedger({ projectRoot, name: 'decisions', body: step.body });
     stdout.write(`decisions-ledger: added decision ${step.entry.id}\n`);
     return 0;
@@ -449,7 +519,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
       disposition: String(flags.disposition),
     };
     if (flags.reason) entry.reason = String(flags.reason);
-    const step = addEntry({ name: 'concerns', body, entry, now });
+    const step = addEntry({
+      name: 'concerns', body, entry, now,
+      ...(idOverride !== undefined ? { id: idOverride } : {}),
+    });
+    if (step.status === 'unchanged') {
+      if (flags.json) {
+        stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+      } else {
+        stdout.write(`concern-ledger: unchanged ${step.entry.id}\n`);
+      }
+      return 0;
+    }
     await saveLedger({ projectRoot, name: 'concerns', body: step.body });
     stdout.write(`concern-ledger: added concern ${step.entry.id}\n`);
     return 0;
@@ -465,7 +546,18 @@ async function runAdd({ projectRoot, name, flags, stdout, stderr }) {
     finding: String(flags.finding),
     severity: flags.severity ? String(flags.severity) : 'medium',
   };
-  const step = addEntry({ name: 'probes', body, entry, now });
+  const step = addEntry({
+    name: 'probes', body, entry, now,
+    ...(idOverride !== undefined ? { id: idOverride } : {}),
+  });
+  if (step.status === 'unchanged') {
+    if (flags.json) {
+      stdout.write(`${JSON.stringify({ status: 'unchanged', id: step.entry.id, entry: step.entry }, null, 2)}\n`);
+    } else {
+      stdout.write(`probe-ledger: unchanged ${step.entry.id}\n`);
+    }
+    return 0;
+  }
   await saveLedger({ projectRoot, name: 'probes', body: step.body });
   stdout.write(`probe-ledger: added probe ${step.entry.id}\n`);
   return 0;