rcf-lite 0.0.1 → 0.7.1

package/src/cli/fbs.js

@@ -0,0 +1,171 @@
+// `rcf fbs <fbs-id> <verb> [options]` subcommand handler
+// (verification-integrity-cluster-spec §3.1, §5.2).
+//
+// One verb in Track A:
+//   depends-on   append or replace a dependsOnServices[] entry
+//
+// Written at Define stage (build-cycle §3, spec §5.1) with the
+// attestation mode drawn from the pre-flight config record. Never
+// invented mid-Test to justify a green suite. The verb refuses to
+// write an entry whose acIds are not on the FBS.
+
+import { parseArgs } from 'node:util';
+
+import { isRcfError, writeUnexpectedFailure } from '#core/errors';
+import { updateDocument, walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+
+const VALID_MODES = new Set(['live', 'sandboxed', 'mocked', 'declaredMockOnly', 'notShipped']);
+
+const DEPENDS_ON_OPTION_SPEC = {
+  service: { type: 'string' },
+  mode: { type: 'string' },
+  acs: { type: 'string' },
+  display: { type: 'string' },
+  purpose: { type: 'string' },
+  preflight: { type: 'string' },
+  force: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf fbs <fbs-id> <verb> [options]
+
+Verbs:
+  depends-on              Record a third-party service dependency on this FBS
+
+rcf fbs <fbs-id> depends-on --service <id> --mode <live|sandboxed|mocked|declaredMockOnly|notShipped>
+    --acs <acId>[,<acId>...] [--display "..."] [--purpose "..."] [--preflight <pfc-id>]
+
+Writes a dependsOnServices[] entry keyed by --service. Idempotent by
+service id: an existing entry with the same id is replaced (silent
+overwrite is intentional here — the entry is derived from the same
+pre-flight ruling every time). --acs must reference ACs the FBS
+already binds via its acIds.
+
+Options common:
+  --force                   Bypass the AC-in-FBS check (for repair only)
+  --quiet                   Suppress non-error stdout
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `fbs`
+ * @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();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    stdout.write(HELP);
+    return argv[0] ? 0 : 2;
+  }
+
+  const fbsId = argv[0];
+  const verb = argv[1];
+  const rest = argv.slice(2);
+  if (!verb) {
+    stderr.write('[error] usage fbs: verb required (depends-on)\n');
+    return 2;
+  }
+  if (!/^FBS-\d{3,}$/.test(fbsId)) {
+    stderr.write(`[error] usage fbs: expected an FBS id like FBS-011, got '${fbsId}'\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).\n');
+    return 2;
+  }
+  const walkResult = await walkTree({ projectRoot });
+  const tree = walkResult.tree;
+  const fbs = tree.byId.get(fbsId);
+  if (!fbs || tree.kindById.get(fbsId) !== 'fbs') {
+    stderr.write(`[error] usage fbs: ${fbsId} not found or not an FBS\n`);
+    return 2;
+  }
+
+  if (verb === 'depends-on') return runDependsOn({ fbsId, fbs, rest, projectRoot, tree, walkResult, stdout, stderr });
+  stderr.write(`[error] usage fbs: unknown verb '${verb}' (expected depends-on)\n`);
+  return 2;
+}
+
+async function runDependsOn({ fbsId, fbs, rest, projectRoot, tree, walkResult, stdout, stderr }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: DEPENDS_ON_OPTION_SPEC, allowPositionals: false, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  if (!flags.service) return usageErr(stderr, 'fbs depends-on: --service required');
+  if (!/^[a-z][a-zA-Z0-9]*$/.test(flags.service)) {
+    return usageErr(stderr, `fbs depends-on: --service must be camelCase (got '${flags.service}')`);
+  }
+  if (!flags.mode) return usageErr(stderr, 'fbs depends-on: --mode required');
+  if (!VALID_MODES.has(flags.mode)) {
+    return usageErr(stderr, `fbs depends-on: unknown --mode '${flags.mode}' (expected ${[...VALID_MODES].join(' | ')})`);
+  }
+  if (!flags.acs) return usageErr(stderr, 'fbs depends-on: --acs required (comma-separated AC ids)');
+  const acIds = flags.acs.split(',').map((s) => s.trim()).filter(Boolean);
+  if (acIds.length === 0) return usageErr(stderr, 'fbs depends-on: --acs is empty');
+
+  if (!flags.force) {
+    const fbsAcIds = new Set(fbs.acIds ?? []);
+    const outside = acIds.filter((ac) => !fbsAcIds.has(ac));
+    if (outside.length > 0) {
+      stderr.write(`[error] refused fbs depends-on: ${fbsId} does not bind AC(s): ${outside.join(', ')}; add them to the FBS first (or pass --force for a repair path).\n`);
+      return 4;
+    }
+  }
+
+  const entry = {
+    id: flags.service,
+    displayName: flags.display ?? flags.service,
+    purpose: flags.purpose ?? `${flags.service} dependency`,
+    attestationMode: flags.mode,
+    acIds,
+  };
+  if (typeof flags.preflight === 'string' && flags.preflight.length > 0) {
+    // If the operator passed a bare pfc id, expand to the full ref; if
+    // they passed the composite (`pfc-...#services.<id>`) keep it.
+    entry.preFlightRef = flags.preflight.includes('#')
+      ? flags.preflight
+      : `${flags.preflight}#services.${flags.service}`;
+  }
+
+  const existing = Array.isArray(fbs.dependsOnServices) ? fbs.dependsOnServices : [];
+  const nextEntries = existing.filter((e) => e.id !== flags.service);
+  nextEntries.push(entry);
+
+  const sets = [{ path: 'dependsOnServices', value: nextEntries }];
+  const result = await updateDocument({
+    projectRoot, tree, id: fbsId, patch: null, sets, options: {}, walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) return handleWriterError(result, stderr);
+  if (!flags.quiet) {
+    stdout.write(`fbs ${fbsId} depends-on: ${flags.service} (${flags.mode}) covers ${acIds.length} AC(s).\n`);
+  }
+  return 0;
+}
+
+function usageErr(stderr, message) {
+  stderr.write(`[error] usage ${message}\n`);
+  return 2;
+}
+
+function handleWriterError(err, stderr) {
+  if (err.kind === 'ioFailure') { writeUnexpectedFailure(err, stderr); return 1; }
+  stderr.write(`[error] ${err.kind} ${err.message}\n`);
+  if (err.kind === 'usage') return 2;
+  if (err.kind === 'validation' || err.kind === 'brokenReference') return 3;
+  return 1;
+}

package/src/cli/finalise.js

@@ -0,0 +1,377 @@
+// `rcf finalise` subcommand handler (spec §8, amendments 4 + 5). The build-side
+// home of the finalise-gate integration contract: the ship gate that promotes
+// an FBS from `complete` to `verified` ONLY when an independent rcf-verify run
+// against the deployed app passes.
+//
+//   rcf finalise <fbs-id> --url <deploy-url> [options]
+//
+// The spec (§8.2) offers two homes for this: overloading `rcf build --mark
+// complete`, or "a dedicated finalise verb". This is the dedicated verb.
+// `rcf build --mark` is a deterministic-only, pure transition path that runs
+// PRE-deploy; the finalise gate spawns a subprocess, hits the network, and may
+// prompt - it does not belong on the mark path. The `complete -> verified`
+// transition is the exact semantic home: `verified` means "independently
+// verified against the running deploy", which is precisely what rcf-verify
+// stamps.
+//
+// Hard contract points (spec §8.2 / §9):
+//   - verify is a FRESH SUBPROCESS with the isolation env, never an in-process
+//     import (§8.2 / §9: the verifier agent must start cold, zero build context);
+//   - the gate is the subprocess exit code AND the report's ship authority
+//     (spec §4): exit 0 with verdictAuthority 'ship' -> promote to verified;
+//     exit 0 with correctness-only authority -> HOLD (stay put, no promotion);
+//     non-zero -> stay put, surface findings;
+//   - findings flow via the --out report file, not stdout scraping;
+//   - if rcf-verify is absent, PROMPT to install (or accept an explicit
+//     --install-verify flag) - NEVER silently skip the gate (§8.3).
+
+import { resolve as resolvePath } from 'node:path';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+
+import { isRcfError, rcfError, writeUnexpectedFailure } from '#core/errors';
+import { updateDocument, walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import { kindOf } from '../query/index.js';
+import {
+  buildVerifyArgs,
+  composeShipWithoutVerifiedRecord,
+  detectVerify,
+  findMockOnlyDeclaredAcs,
+  loadReport,
+  reportHasMockOnlyDeclared,
+  resolveAbsentVerify,
+  spawnVerify,
+  summariseReport,
+  writeShipWithoutVerifiedRecord,
+} from '../finalise/index.js';
+
+// Kept in sync with verify's own sets by contract (build never imports verify -
+// that would break the §9 independence guarantee). Profiles: spec §4.
+// Severities: spec §5.1 finding taxonomy.
+const PROFILES = new Set(['deployed', 'ci', 'local-dev']);
+const SEVERITIES = new Set(['PASS', 'COSMETIC', 'DEGRADED', 'BROKEN']);
+const DEFAULT_PROFILE = 'deployed';
+const DEFAULT_GATE = 'BROKEN';
+const DEFAULT_REPORT = '.rcf-verify-report.json';
+// The finalise gate only makes sense on a built item; verified re-verify is
+// allowed (the §5.4 loop re-runs the gate on a previously-verified item).
+const FINALISABLE_STATUSES = new Set(['complete', 'verified']);
+
+const OPTION_SPEC = {
+  url: { type: 'string' },
+  profile: { type: 'string' },
+  'parity-env': { type: 'boolean' },
+  provision: { type: 'string' },
+  'severity-gate': { type: 'string' },
+  out: { type: 'string' },
+  chain: { type: 'string' },
+  persona: { type: 'string' },
+  'install-verify': { type: 'boolean' },
+  // 0.7.0 verification-integrity: acknowledge MOCK-ONLY-DECLARED /
+  // BLOCKED-BY-DECLARATION per-AC verdicts on the verify report and
+  // ship the FBS 'complete' without promoting to 'verified'. Records
+  // the operator's ack on the manifest.
+  'ship-without-verified': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf finalise <fbs-id> --url <deploy-url> [options]
+
+The ship gate. Promotes an FBS at status complete to verified ONLY when an
+independent rcf-verify run passes AND carries ship authority.
+
+rcf-verify is launched as a FRESH SUBPROCESS (never in-process) so the
+verifier agent starts cold, with zero build context - its only inputs are the
+RCF chain (the acceptance contract) and the live URL. The gate is the
+subprocess exit code AND the report's ship authority: a run must both pass and
+carry SHIP authority (a 'deployed'-profile run, or a 'ci'/'local-dev' run with
+--parity-env) to promote. A correctness-only PASS holds without promoting.
+Findings flow back via the --out report file.
+
+If rcf-verify is not installed, finalise PROMPTS to install it (install-together
+posture) - it never silently skips the gate. Off a TTY, pass --install-verify.
+
+Required:
+  <fbs-id>                  The FBS item to finalise (must be 'complete')
+  --url <deploy-url>        The running deployed app to verify against
+
+Options:
+  --profile <p>             deployed | ci | local-dev (default: deployed)
+  --parity-env              Assert a ci/local-dev runtime is edge-identical to
+                            prod - the only path to a SHIP verdict off 'deployed'
+  --provision <file>        Provisioning / prerequisite-credentials FILE
+                            (never inline; secrets never echoed)
+  --severity-gate <sev>     Block at/above this severity:
+                            PASS | COSMETIC | DEGRADED | BROKEN (default: BROKEN)
+  --out <path>              Where verify writes its report artifact
+                            (default: ${DEFAULT_REPORT})
+  --chain <PRD/ref>         Which PRD/chain to verify against (default: repo's)
+  --persona <name>          Adversarial persona flavour
+  --install-verify          If rcf-verify is absent, install it without
+                            prompting (the sanctioned non-interactive path)
+  --ship-without-verified   Acknowledge MOCK-ONLY-DECLARED /
+                            BLOCKED-BY-DECLARATION per-AC verdicts on
+                            the verify report and ship the FBS
+                            'complete' without promoting to 'verified'
+                            (verification-integrity 0.7.0 §5.2). Reads
+                            the disclosed verdicts and leaves the FBS at
+                            'complete'. Without this flag, the gate
+                            refuses to promote when any AC lands in
+                            those verdicts.
+  --quiet                   Suppress non-error confirmations
+  --help                    Print this help
+
+Exit codes:
+  0  gate passed - FBS marked verified
+  1  IO / unexpected runtime failure
+  2  usage error (bad flags, unknown / non-FBS id)
+  3  schema validation or broken references (tree unreadable, or write refused)
+  4  gate NOT passed - verify blocked ship, OR verify passed but the run lacks
+     ship authority (a correctness-only HOLD), OR rcf-verify absent and install
+     declined/unavailable - the FBS is left unchanged, findings surfaced
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `finalise`
+ * @param {object} [deps] - injectable seams (detect / spawn / prompt / install /
+ *   loadReport) for testing the gate without a real rcf-verify + live app.
+ * @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: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+
+  const usage = (message) => {
+    stderr.write(`[error] usage finalise: ${message}\n`);
+    return 2;
+  };
+
+  if (positionals.length === 0) return usage('an <fbs-id> positional is required');
+  if (positionals.length > 1) return usage('multiple positional ids are not supported');
+  const fbsId = positionals[0];
+  if (fbsId.includes('*') || fbsId.includes('?')) {
+    return usage('wildcard / glob positional not supported');
+  }
+
+  if (!flags.url) return usage('--url <deploy-url> is required');
+
+  const profile = flags.profile ?? DEFAULT_PROFILE;
+  if (!PROFILES.has(profile)) {
+    return usage(`unknown --profile ${profile} (expected deployed | ci | local-dev)`);
+  }
+  const gate = flags['severity-gate'] ?? DEFAULT_GATE;
+  if (!SEVERITIES.has(gate)) {
+    return usage(`unknown --severity-gate ${gate} (expected PASS | COSMETIC | DEGRADED | BROKEN)`);
+  }
+  // Dash-footgun (mirrors build's --body-file / verify's --provision discipline):
+  // a --provision that looks like a flag is a swallowed next option or an inline
+  // credential. Credentials are FILE-only, never inline, never echoed.
+  if (typeof flags.provision === 'string' && flags.provision.startsWith('-')) {
+    return usage('--provision takes a file path, not a flag or inline value (credentials are never accepted inline)');
+  }
+
+  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;
+  }
+
+  // Walker errors block finalise entirely - no gate runs against a tree that
+  // fails validation, and no status write lands (mirrors build --mark, §D6).
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write('[error] validation the RCF tree does not validate; fix it before finalising.\n');
+    return 3;
+  }
+
+  // The positional must be an FBS at a finalisable status.
+  const kind = kindOf(tree, fbsId);
+  if (kind !== 'fbs') {
+    if (!kind) return usage(`id ${fbsId} not found`);
+    return usage(`${fbsId} is a ${kind} id; finalise addresses FBS items only`);
+  }
+  const fbs = tree.byId.get(fbsId);
+  const currentStatus = fbs.executionStatus;
+  if (!FINALISABLE_STATUSES.has(currentStatus)) {
+    stderr.write(`[error] refused finalise: ${fbsId} is '${currentStatus}'; the finalise gate promotes 'complete' -> 'verified'. `
+      + `Mark it complete first: rcf build ${fbsId} --mark complete\n`);
+    return 4;
+  }
+
+  const quiet = Boolean(flags.quiet);
+  const io = { stdout, stderr, input: deps.input ?? process.stdin, output: deps.output ?? process.stdout };
+
+  // --- rcf-verify install detection (§8.3) --------------------------------
+  let detection = deps.detectVerify
+    ? await deps.detectVerify({ cwd: projectRoot })
+    : await detectVerify({ cwd: projectRoot });
+  if (!detection.installed) {
+    const isTty = deps.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const outcome = await resolveAbsentVerify(
+      { installFlag: Boolean(flags['install-verify']), isTty },
+      io,
+      deps,
+    );
+    if (outcome.action === 'abort') {
+      stderr.write(`[error] refused ${outcome.reason}\n`);
+      return outcome.code;
+    }
+    // Installed - re-detect to get a concrete invocation.
+    detection = deps.detectVerify
+      ? await deps.detectVerify({ cwd: projectRoot })
+      : await detectVerify({ cwd: projectRoot });
+    if (!detection.installed) {
+      stderr.write('[error] unexpected rcf-verify still not resolvable after install; install it manually and re-run.\n');
+      return 1;
+    }
+  }
+
+  // --- spawn the fresh verify subprocess (§8.2) ---------------------------
+  const outPath = resolvePath(projectRoot, flags.out ?? DEFAULT_REPORT);
+  const verifyArgs = buildVerifyArgs({
+    repo: projectRoot,
+    url: flags.url,
+    profile,
+    out: outPath,
+    severityGate: gate,
+    parityEnv: Boolean(flags['parity-env']),
+    provision: flags.provision,
+    chain: flags.chain,
+    persona: flags.persona,
+  });
+
+  if (!quiet) {
+    stdout.write(`[finalise] launching rcf-verify (fresh subprocess) against ${flags.url} [profile=${profile}]...\n`);
+  }
+
+  let spawnResult;
+  try {
+    spawnResult = deps.spawnVerify
+      ? await deps.spawnVerify({ invocation: detection.invocation, verifyArgs, cwd: projectRoot }, deps)
+      : await spawnVerify({ invocation: detection.invocation, verifyArgs, cwd: projectRoot }, deps);
+  } catch (err) {
+    writeUnexpectedFailure(
+      rcfError({ kind: 'ioFailure', message: `finalise: could not launch rcf-verify: ${err.message}`, stack: err.stack }),
+      stderr,
+    );
+    return 1;
+  }
+
+  // --- gate on the subprocess exit code (§8.2) + ship authority (§4) ------
+  if (spawnResult.code === 0) {
+    // Gate passed on exit code. Promote to verified (idempotent if a re-verify
+    // of an already-verified item).
+    if (currentStatus === 'verified') {
+      if (!quiet) stdout.write(`[finalise] gate passed; ${fbsId} already verified (re-verify) -> ${outPath}\n`);
+      return 0;
+    }
+    // Ship-authority gate (spec §4, w-2026-07-22-004): exit 0 is necessary but
+    // not sufficient to write `verified`. Only a run that carries SHIP authority
+    // may promote - a `deployed`-profile run, or a `ci`/`local-dev` run with an
+    // explicit --parity-env parity assertion. A correctness-only PASS (e.g. a
+    // bare `--profile ci` run) is a real regression pass but carries no ship
+    // authority, so it must HOLD rather than promote. We read the authority from
+    // the report verify stamped (never re-derive it here - that would break the
+    // §9 independence guarantee). An unreadable report on a pass is treated as a
+    // HOLD, never a silent promotion (mirrors ingest's "unreadable is not a pass").
+    const passLoaded = await (deps.loadReport ? deps.loadReport(outPath, deps) : loadReport(outPath, deps));
+    const authority = passLoaded.ok ? passLoaded.report.verdictAuthority : undefined;
+    if (authority !== 'ship') {
+      stderr.write(`[finalise] HOLD: rcf-verify passed but this run carries '${authority ?? 'unknown'}' authority, `
+        + `not 'ship'; ${fbsId} left '${currentStatus}'.\n`);
+      stderr.write('Only a \'deployed\'-profile run - or a \'ci\'/\'local-dev\' run with --parity-env asserting the '
+        + 'runtime is edge-identical to prod - carries ship authority and can promote to verified. '
+        + `Report: ${outPath}\n`);
+      if (!passLoaded.ok) stderr.write(`[finalise] (the verify report could not be read: ${passLoaded.reason})\n`);
+      return 4;
+    }
+    // 0.7.0 verification-integrity §5.2: the finalise gate reads the
+    // verify report's per-AC verdicts and refuses to promote to
+    // 'verified' on MOCK-ONLY-DECLARED / BLOCKED-BY-DECLARATION unless
+    // the operator has explicitly shipped-without-verified. Graceful
+    // when the report carries no perAcVerdicts field (verify's train
+    // car is later; older reports are silent on this axis).
+    if (passLoaded.ok && reportHasMockOnlyDeclared(passLoaded.report)) {
+      const declared = findMockOnlyDeclaredAcs(passLoaded.report);
+      if (flags['ship-without-verified']) {
+        // B-1 (spec section 5.2, review 2026-07-31): the ack is
+        // recorded on the manifest so it is durable and greppable at
+        // ship time. Stdout alone is neither. Written BEFORE the
+        // success confirmation so a manifest-write failure surfaces
+        // to the operator as a hard failure rather than a silent
+        // stdout-only ack.
+        const ackRecord = composeShipWithoutVerifiedRecord({
+          manifest: tree.manifest,
+          fbsId,
+          declaredAcs: declared,
+          reportPath: outPath,
+        });
+        const ackResult = await writeShipWithoutVerifiedRecord({
+          projectRoot, tree, record: ackRecord,
+        });
+        if (isRcfError(ackResult)) {
+          if (ackResult.kind === 'ioFailure') { writeUnexpectedFailure(ackResult, stderr); return 1; }
+          stderr.write(`[error] ${ackResult.kind} ${ackResult.message}\n`);
+          if (ackResult.kind === 'validation' || ackResult.kind === 'brokenReference') return 3;
+          return 1;
+        }
+        if (!quiet) {
+          stdout.write(`[finalise] gate passed and ${declared.length} AC(s) came back with declared mock-only verdicts; --ship-without-verified acknowledged (${ackRecord.id} on rcf/manifest.json); ${fbsId} left '${currentStatus}'. Report: ${outPath}\n`);
+          stdout.write(summariseReport(passLoaded.report));
+        }
+        return 0;
+      }
+      stderr.write(`[finalise] gate NOT promoted: ${declared.length} AC(s) came back MOCK-ONLY-DECLARED / BLOCKED-BY-DECLARATION on the report; ${fbsId} left '${currentStatus}'.\n`);
+      stderr.write('Only a run where every service-bound AC verifies with a live-attested profile promotes to verified. To ship the FBS at complete anyway, re-run with --ship-without-verified (the ack lands on the record).\n');
+      stderr.write(summariseReport(passLoaded.report));
+      stderr.write(`Report: ${outPath}\n`);
+      return 4;
+    }
+    const result = await updateDocument({
+      projectRoot, tree, id: fbsId, sets: [{ path: 'executionStatus', value: 'verified' }], options: {},
+    });
+    if (isRcfError(result)) {
+      if (result.kind === 'ioFailure') { writeUnexpectedFailure(result, stderr); return 1; }
+      stderr.write(`[error] ${result.kind} ${result.message}\n`);
+      if (result.kind === 'usage') return 2;
+      if (result.kind === 'validation' || result.kind === 'brokenReference') return 3;
+      return 1;
+    }
+    if (!quiet) stdout.write(`[finalise] gate passed; marked ${fbsId} complete -> verified. Report: ${outPath}\n`);
+    return 0;
+  }
+
+  // Gate NOT passed. The FBS stays put; surface the findings from the report
+  // (the §5.4 verify -> fix -> re-verify seam), then fail non-zero.
+  stderr.write(`[finalise] gate NOT passed (rcf-verify exit ${spawnResult.code}); ${fbsId} left '${currentStatus}'.\n`);
+  const loaded = await (deps.loadReport ? deps.loadReport(outPath, deps) : loadReport(outPath, deps));
+  if (loaded.ok) {
+    stderr.write(summariseReport(loaded.report));
+    stderr.write(`Full report (build-lite ingestible, chain-node-addressed): ${outPath}\n`);
+  } else {
+    stderr.write(`[finalise] could not read the verify report: ${loaded.reason}\n`);
+  }
+  // Map verify's exit-code convention to finalise's. Verify: 2 usage, 3 chain
+  // load, 5 gate/NOT-DEPLOYED/BLOCKED/LAUNCH-FAILURE, 1 io. A tripped ship gate
+  // is a refusal to finalise -> 4; a verify usage/chain error surfaces as-is.
+  if (spawnResult.code === 2) return 2;
+  if (spawnResult.code === 3) return 3;
+  if (spawnResult.code === 5) return 4;
+  return 1;
+}