rcf-lite 0.25.0 → 0.27.0

package/src/blueprint/dispositions.js

@@ -0,0 +1,44 @@
+// `rcf define blueprint dispositions <slug> [--json]` sub-verb.
+// Read-only view over the per-slug disposition ledger written by
+// `disposition-ledger.js`. Emits either a human-readable table (one
+// AC per line) or a JSON dump.
+
+import { readLedger, ledgerRelPath } from './disposition-ledger.js';
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.slug
+ * @param {boolean} [args.asJson]
+ * @returns {Promise<{ output: string, exitCode: number }>}
+ */
+export async function renderDispositions({ projectRoot, slug, asJson = false }) {
+  const doc = await readLedger(projectRoot, slug);
+  if (!doc) {
+    if (asJson) {
+      return {
+        output: `${JSON.stringify({ slug, present: false, ledgerPath: ledgerRelPath(slug), records: [] }, null, 2)}\n`,
+        exitCode: 0,
+      };
+    }
+    return {
+      output: `[blueprint] no disposition ledger found for '${slug}' at ${ledgerRelPath(slug)}\n`,
+      exitCode: 0,
+    };
+  }
+  if (asJson) {
+    return {
+      output: `${JSON.stringify({ slug, present: true, ledgerPath: ledgerRelPath(slug), records: doc.records }, null, 2)}\n`,
+      exitCode: 0,
+    };
+  }
+  const lines = [`[blueprint] '${slug}' disposition ledger (${doc.records.length} record(s)) at ${ledgerRelPath(slug)}:`];
+  for (const rec of doc.records) {
+    const parts = [rec.acId, rec.storyId, rec.action];
+    if (rec.reason) parts.push(`reason: ${rec.reason}`);
+    if (rec.resolvedAt) parts.push(`resolvedAt: ${rec.resolvedAt}`);
+    if (rec.escalatedAt) parts.push(`escalatedAt: ${rec.escalatedAt}`);
+    lines.push(`  ${parts.join('  ')}`);
+  }
+  return { output: `${lines.join('\n')}\n`, exitCode: 0 };
+}

package/src/blueprint/index.js

@@ -62,3 +62,22 @@ export {
   parseUstar,
   sha256Hex,
 } from './library-fetcher-tarball.js';
+export {
+  loadForLint,
+  loadSuppressions,
+  runLint,
+  runPass1,
+  runPass2,
+} from './consistency-lint.js';
+export {
+  APPLY_DISPOSITION_PROMPT,
+  LEDGER_SCHEMA_NOTE,
+  initialiseLedger,
+  ledgerAbsPath,
+  ledgerExists,
+  ledgerRelPath,
+  readLedger,
+  upsertLedgerRecord,
+  writeLedger,
+} from './disposition-ledger.js';
+export { renderDispositions } from './dispositions.js';

package/src/browser-verify/manifest-writer.js

@@ -94,7 +94,10 @@ export function composeBrowserVerificationRecord({
   invariantChecks, authSmokeChecks = [], probePacks = [], notes, now = new Date(),
 }) {
   const id = nextBrowserVerificationId(manifest, fbsId);
-  const verdict = aggregateVerdict(invariantChecks, authSmokeChecks, probePacks);
+  const composedProbePacks = Array.isArray(probePacks)
+    ? probePacks.map(remapPackForPositiveEvidence)
+    : probePacks;
+  const verdict = aggregateVerdict(invariantChecks, authSmokeChecks, composedProbePacks);
   const record = {
     id,
     fbsId,
@@ -107,11 +110,59 @@ export function composeBrowserVerificationRecord({
     verdict,
   };
   if (authSmokeChecks && authSmokeChecks.length > 0) record.authSmokeChecks = authSmokeChecks;
-  if (Array.isArray(probePacks) && probePacks.length > 0) record.probePacks = probePacks;
+  if (Array.isArray(composedProbePacks) && composedProbePacks.length > 0) record.probePacks = composedProbePacks;
   if (typeof notes === 'string' && notes.length > 0) record.notes = notes;
   return record;
 }
 
+/**
+ * Positive-evidence remap (authoring standard section 7d / section 8c).
+ *
+ * A `checks[]` or `preChecks[]` record with `verdict: 'pass'` is legal
+ * only when it carries either an `evidence` field of one of the four
+ * shapes named in section 7d (a request id, a response body excerpt, a
+ * created-then-deleted resource id in an inventory diff, or a
+ * rendered-bytes hash), or an `accountBoundSkipped: true` field with a
+ * non-empty `reason`. A pass record with neither is remapped to
+ * `verdict: 'fail'` with `detail: 'positive-evidence-missing'` at
+ * record-composition time; the composed record is what the manifest
+ * carries so the fail surfaces at the ship gate.
+ *
+ * @param {object} pack
+ * @returns {object}
+ */
+function remapPackForPositiveEvidence(pack) {
+  if (!pack || typeof pack !== 'object') return pack;
+  const nextPack = { ...pack };
+  if (Array.isArray(pack.checks)) {
+    nextPack.checks = pack.checks.map(remapCheckForPositiveEvidence);
+  }
+  if (Array.isArray(pack.preChecks)) {
+    nextPack.preChecks = pack.preChecks.map(remapCheckForPositiveEvidence);
+  }
+  return nextPack;
+}
+
+function remapCheckForPositiveEvidence(check) {
+  if (!check || typeof check !== 'object') return check;
+  if (check.verdict !== 'pass') return check;
+  if (checkCarriesPositiveEvidence(check)) return check;
+  return { ...check, verdict: 'fail', detail: 'positive-evidence-missing' };
+}
+
+function checkCarriesPositiveEvidence(check) {
+  if (check.accountBoundSkipped === true) {
+    const reason = check.reason;
+    if (typeof reason === 'string' && reason.length > 0) return true;
+    return false;
+  }
+  if (check.evidence != null) {
+    if (typeof check.evidence === 'string') return check.evidence.length > 0;
+    if (typeof check.evidence === 'object') return true;
+  }
+  return false;
+}
+
 function stripSeverity(check) {
   const out = { invariant: check.invariant, verdict: check.verdict };
   if (typeof check.detail === 'string' && check.detail.length > 0) out.detail = check.detail;

package/src/browser-verify/pack-runner.js

@@ -81,10 +81,16 @@ export async function runProbePacksForFbs({
     for (const pre of pack.preChecks) {
       let verdict = 'pass';
       let detail;
+      let preEvidence;
+      let preAccountBoundSkipped;
+      let preReason;
       try {
         const outcome = await pre.run({ fbs, uiBaseline, manifest, runtimeUrl, fetch, browser });
         verdict = outcome?.verdict ?? 'pass';
         detail = outcome?.detail;
+        preEvidence = outcome?.evidence;
+        preAccountBoundSkipped = outcome?.accountBoundSkipped;
+        preReason = outcome?.reason;
       } catch (err) {
         verdict = 'fail';
         detail = `pre-check threw: ${err.message}`;
@@ -94,6 +100,9 @@ export async function runProbePacksForFbs({
         verdict,
         severity: pre.severity,
         ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+        ...(preEvidence != null ? { evidence: preEvidence } : {}),
+        ...(preAccountBoundSkipped === true ? { accountBoundSkipped: true } : {}),
+        ...(typeof preReason === 'string' && preReason.length > 0 ? { reason: preReason } : {}),
       });
       if (verdict === 'fail') failedPreCheckIds.add(pre.id);
       if (verdict === 'fail' && pre.severity === 'block') highest = 'block';
@@ -154,10 +163,16 @@ export async function runProbePacksForFbs({
         : { browser, fetch, runtimeUrl, route: primaryRoute, theme: primaryTheme, projectRoot };
       let verdict = 'pass';
       let detail;
+      let checkEvidence;
+      let checkAccountBoundSkipped;
+      let checkReason;
       try {
         const outcome = await check.run(context);
         verdict = outcome?.verdict ?? 'pass';
         detail = outcome?.detail;
+        checkEvidence = outcome?.evidence;
+        checkAccountBoundSkipped = outcome?.accountBoundSkipped;
+        checkReason = outcome?.reason;
       } catch (err) {
         verdict = 'fail';
         detail = `check threw: ${err.message}`;
@@ -167,6 +182,9 @@ export async function runProbePacksForFbs({
         verdict,
         severity: check.severity,
         ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+        ...(checkEvidence != null ? { evidence: checkEvidence } : {}),
+        ...(checkAccountBoundSkipped === true ? { accountBoundSkipped: true } : {}),
+        ...(typeof checkReason === 'string' && checkReason.length > 0 ? { reason: checkReason } : {}),
       });
       if (verdict === 'fail' && check.severity === 'block') highest = 'block';
       else if (verdict === 'fail' && check.severity === 'warn' && highest !== 'block') highest = 'warn';

package/src/cli/blueprint.js

@@ -36,6 +36,12 @@ import {
 } from '../blueprint/index.js';
 import { conflictReportJson, renderConflictReport } from '../blueprint/conflicts.js';
 import { handleLibraryVerb, LIBRARY_HELP } from './blueprint-library.js';
+import {
+  loadForLint,
+  loadSuppressions,
+  runLint,
+  renderDispositions,
+} from '../blueprint/index.js';
 
 export const HELP = `Usage: rcf define blueprint <verb> [options]
 
@@ -115,6 +121,23 @@ Verbs:
                          'rcf define blueprint library --help' for the
                          full surface. Phase 2b covers local sources;
                          network fetchers land in Phase 2c.
+  lint-consistency <source>
+                         Run the single-definition ownership and REQ
+                         delivery lint over one blueprint source (pass 1
+                         catches literals restated outside their owning
+                         TAC; pass 2 catches REQs promising properties
+                         with no delivering TAC or ADR). Exit 0 on
+                         clean, exit 3 on unsuppressed findings, exit 2
+                         on usage error. --json emits the machine
+                         envelope; pass-1 findings are suppressible via
+                         a "Known chain-consistency-lint suppressions"
+                         section in the blueprint README (see spec
+                         section 5.8).
+  dispositions <slug>    Read the per-slug disposition ledger at
+                         rcf/blueprints/<slug>.disposition.json. Prints
+                         one line per contributed AC with its recorded
+                         disposition; --json emits the raw ledger.
+                         Read-only.
 
 Options:
   --namespace <slug>     Override the blueprint's default namespace
@@ -204,6 +227,11 @@ const OPTION_SPEC = {
   'allow-no-queue-yet': { type: 'boolean' },
   answer: { type: 'string', multiple: true },
   answers: { type: 'string' },
+  // Integration and contradiction protocol (spec 2026-09-09 section
+  // 3.6 and 7.1): the operator (or the wrapping harness) can suppress
+  // the disposition prompt printed after a fresh apply. The ledger is
+  // still written; only the human-facing prompt line is skipped.
+  'no-disposition-prompt': { type: 'boolean' },
 };
 
 /**
@@ -244,6 +272,14 @@ export async function main(argv, deps = {}) {
     return handleLibraryVerb(parsed, rest, { stdout, stderr, cwd, now, stdin: deps.stdin });
   }
 
+  // `lint-consistency <source>` runs over a blueprint source directory
+  // and does not require an rcf/ tree; wire it before the projectRoot
+  // walk so it stays usable from a fresh clone (and from the shipping
+  // CI gate).
+  if (verb === 'lint-consistency') {
+    return handleLintConsistencyVerb({ rest, parsed, cwd, stdout, stderr });
+  }
+
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
     stderr.write('[error] no rcf/ tree found in this directory or any ancestor.\n');
@@ -433,6 +469,13 @@ export async function main(argv, deps = {}) {
     }
     if (!parsed.values.quiet) {
       stdout.write(`[blueprint] applied '${result.slug}' at ${result.version} (${result.contributions.length} contribution(s)).\n`);
+      // Disposition prompt (spec section 3.6 + 3.7). Printed once per
+      // fresh apply; a re-apply on the same slug omits it because the
+      // ledger is left untouched. Suppressible with the CLI flag
+      // --no-disposition-prompt.
+      if (result.dispositionPrompt && parsed.values['no-disposition-prompt'] !== true) {
+        stdout.write(`${result.dispositionPrompt}\n`);
+      }
     }
     // Companion-suggestion mechanism (spec 2.6). Runs AFTER the apply
     // writes so a failed apply never produces a suggestion block.
@@ -614,6 +657,17 @@ export async function main(argv, deps = {}) {
     });
   }
 
+  if (verb === 'dispositions') {
+    if (rest.length === 0) {
+      stderr.write('[error] blueprint dispositions: missing <slug>\n');
+      return 2;
+    }
+    const slug = rest[0];
+    const rendered = await renderDispositions({ projectRoot, slug, asJson: parsed.values.json === true });
+    stdout.write(rendered.output);
+    return rendered.exitCode;
+  }
+
   stderr.write(`[error] blueprint: unknown verb '${verb}'\n`);
   stderr.write(HELP);
   return 2;
@@ -850,6 +904,55 @@ function parseResolveOptions(rawList, reason) {
  * @param {{ stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream }} deps
  * @returns {Promise<(prompt: string) => Promise<string>>}
  */
+/**
+ * `rcf define blueprint lint-consistency <source>` handler. Resolves
+ * <source> (path or shelf slug), loads the blueprint via loadForLint,
+ * reads any suppressions in the blueprint's README, runs both passes,
+ * and prints either a human summary or a JSON envelope.
+ *
+ * Exit codes:
+ *   0 clean (or every finding suppressed)
+ *   2 usage error / cannot resolve source
+ *   3 unsuppressed findings
+ */
+async function handleLintConsistencyVerb({ rest, parsed, cwd, stdout, stderr }) {
+  if (rest.length === 0) {
+    stderr.write('[error] blueprint lint-consistency: missing <source>\n');
+    return 2;
+  }
+  const rawSource = rest[0];
+  // Reuse the shipping shelf resolver so a bare slug (edge-cloudflare-turnstile)
+  // or a @stock/<slug> reference resolves to the packaged shelf, and a
+  // path resolves relative to cwd.
+  const resolved = await resolveBlueprintSource(rawSource, { projectRoot: cwd });
+  if (isRcfError(resolved)) {
+    stderr.write(`[error] blueprint lint-consistency: ${resolved.message}\n`);
+    return 2;
+  }
+  const sourcePath = resolved.resolved;
+  const loaded = await loadForLint(sourcePath);
+  if ('error' in loaded) {
+    stderr.write(`[error] blueprint lint-consistency: ${loaded.error}\n`);
+    return 2;
+  }
+  const suppressions = await loadSuppressions(sourcePath);
+  const result = runLint(loaded, suppressions);
+  const asJson = parsed.values.json === true;
+  if (asJson) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    stdout.write(`[blueprint] lint-consistency '${result.blueprint}': ${result.verdict} `
+      + `(pass1=${result.passCounts.pass1}, pass2=${result.passCounts.pass2}, `
+      + `suppressed=${result.passCounts.suppressed})\n`);
+    for (const f of result.findings) {
+      const tag = f.suppressed ? '[suppressed]' : '[finding]';
+      stdout.write(`  ${tag} ${f.id} (${f.pass}, ${f.kind}): ${f.message}\n`);
+      if (f.suppressed && f.suppressionReason) stdout.write(`     reason: ${f.suppressionReason}\n`);
+    }
+  }
+  return result.verdict === 'pass' ? 0 : 3;
+}
+
 async function createCustomAuthReadLine({ stdin, stdout }) {
   const { createInterface } = await import('node:readline');
   const rl = createInterface({ input: stdin, output: stdout, terminal: true });

package/src/cli/view.js

@@ -305,17 +305,17 @@ export async function main(argv, deps = {}) {
     return 1;
   }
 
-  stdout.write(`rcf audit view server listening at ${server.url}\n`);
-  stdout.write('watching rcf/ - Ctrl-C to shut down\n');
-
-  maybeAutoOpen({
-    target: server.url,
-    noOpen: opts.noOpen,
-    stream: stdout,
-    env,
-    stderr,
-  });
-
+  // Install SIGINT and SIGTERM handlers BEFORE announcing readiness on
+  // stdout. A caller (test harness, script, operator watching for the
+  // "listening at" line) that sees the readiness line and immediately
+  // sends SIGINT must not race Node's default SIGINT disposition. If the
+  // handlers were installed AFTER the write, a slow scheduler on CI could
+  // deliver the signal in the window between the write flushing to the
+  // parent pipe and `process.on('SIGINT', ...)` calling into sigaction,
+  // and the child would be killed by the default disposition instead of
+  // running its own clean-shutdown path. Ordering is the contract; see
+  // the `SIGINT handler is installed before the "listening at" line`
+  // test in test/view/cli.test.js.
   return new Promise((resolve) => {
     let signalled = false;
     async function handle(sig) {
@@ -339,6 +339,17 @@ export async function main(argv, deps = {}) {
     }
     onSignal('SIGINT', () => { handle('SIGINT'); });
     onSignal('SIGTERM', () => { handle('SIGTERM'); });
+
+    stdout.write(`rcf audit view server listening at ${server.url}\n`);
+    stdout.write('watching rcf/ - Ctrl-C to shut down\n');
+
+    maybeAutoOpen({
+      target: server.url,
+      noOpen: opts.noOpen,
+      stream: stdout,
+      env,
+      stderr,
+    });
   });
 }
 

package/src/setup/identity-seed.js

@@ -57,6 +57,24 @@ _(how you like to work: casual or formal register, verbose or terse
 responses, willingness to be pushed back on, anything the agent should
 know before choosing its default posture)_
 
+## Register
+
+_(how the agent should frame decisions when it needs your ruling. One
+of the three values below on a single line; a line that reads only
+\`unstated\` is fine and reads as productOwner on the first
+escalation.)_
+
+- \`productOwner\`: escalations arrive as one plain-English sentence
+  naming the decision and its consequences, then two or three named
+  choices with what each costs. No method vocabulary, no document ids.
+- \`engineer\`: escalations name the AC id, quote the seed's assertion,
+  quote the project convention that conflicts, and ask a direct
+  question. Fluent in the method vocabulary.
+- \`unstated\`: the agent asks you which register on the first
+  exchange after init and holds \`productOwner\` in the meantime.
+
+unstated
+
 ## Project-scoped notes
 
 _(anything specific to this project that would be useful for the agent