rcf-lite 0.26.0 → 0.28.0

package/src/cli/finalise.js

@@ -25,6 +25,7 @@
 //   - if rcf-verify is absent, PROMPT to install (or accept an explicit
 //     --install-verify flag) - NEVER silently skip the gate (§8.3).
 
+import { spawn } from 'node:child_process';
 import { resolve as resolvePath } from 'node:path';
 import process from 'node:process';
 import { parseArgs } from 'node:util';
@@ -39,11 +40,17 @@ import {
   composeShipWithoutVerifiedRecord,
   composeShipWithoutEvalRecord,
   detectVerify,
+  findBrowserVerificationMissingAcs,
   findEvalRefusalAcs,
   findMockOnlyDeclaredAcs,
+  findScopeMismatchAcs,
+  findUiBaselineUnmetAcs,
   loadReport,
+  reportHasBrowserVerificationMissing,
   reportHasEvalRefusal,
   reportHasMockOnlyDeclared,
+  reportHasScopeMismatch,
+  reportHasUiBaselineUnmet,
   resolveAbsentVerify,
   spawnVerify,
   summariseReport,
@@ -51,6 +58,17 @@ import {
   writeShipWithoutVerifiedRecord,
 } from '../finalise/index.js';
 
+// Referee-guarantee train (REQ-165 / US-16502, docs claim C-26): the
+// merge-state precondition. Finalise refuses to promote to verified
+// when the git working tree is not on one of these default branches.
+// Kept small and conventional (git init and every hosted git provider
+// default to `main` or `master`); projects on a non-default trunk
+// (rare in modern repos) either rename the trunk to a listed name or
+// pass --allow-pre-merge on every finalise run. The alternative --
+// reading the git remote's default-branch symbolic ref -- adds a
+// network round-trip on every finalise and fails offline; the small
+// name list is deliberately the safer default.
+const DEFAULT_BRANCH_NAMES = new Set(['main', 'master']);
 // 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.
@@ -83,6 +101,16 @@ const OPTION_SPEC = {
   // string (spec section 8: missing reason exits 2). Shape mirrors
   // `--provision`: a value that looks like a flag is refused.
   'ship-without-eval': { type: 'string' },
+  // Referee-guarantee train (REQ-165 / US-16502, docs claim C-26):
+  // finalise refuses promotion when the git working tree is not on
+  // the default branch (main / master) so `verified` traces to an
+  // actual post-merge runtime check by construction. --allow-pre-merge
+  // is the deliberate opt-out for pre-merge dev-loop dry runs; the
+  // decision is logged in the finalise stdout so the operator sees
+  // it. Absent a git working tree (e.g. verify against a bare tarball
+  // deploy), the check is skipped and a warn line records that
+  // finalise could not resolve the branch state.
+  'allow-pre-merge': { type: 'boolean' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -139,6 +167,15 @@ Options:
                             string is mandatory; a missing reason exits
                             2. The ack lands on the manifest under
                             shipWithoutEval[] with a monotonic id.
+  --allow-pre-merge         Referee-guarantee train (C-26): finalise
+                            refuses to promote when the git working
+                            tree is not on the default branch
+                            (main / master), so verified traces to an
+                            actual post-merge runtime check. This flag
+                            is the deliberate opt-out for pre-merge
+                            dev-loop dry runs; the decision is logged
+                            on stdout. Absent a git checkout the check
+                            degrades to a warn line.
   --quiet                   Suppress non-error confirmations
   --help                    Print this help
 
@@ -152,6 +189,58 @@ Exit codes:
      declined/unavailable - the FBS is left unchanged, findings surfaced
 `;
 
+/**
+ * Referee-guarantee train (REQ-165 / US-16502, docs claim C-26).
+ * Resolve the current git branch as an out-of-band read so finalise
+ * can refuse promotion when the working tree is not on the default
+ * branch. Returns `{ ok: true, branch }` on success, `{ ok: false,
+ * reason }` when git is absent or the working tree is not a git
+ * checkout (bare tarball deploys, container ephemeral CWD). Never
+ * throws; the caller degrades to a warn line rather than a hard fail.
+ *
+ * Kept out of `#core/store` deliberately: this is a build-lite CLI
+ * concern (the ship gate reads the working tree state), not a document
+ * store concern. It also keeps the store free of a `spawn` seam.
+ *
+ * @param {object} args
+ * @param {string} args.cwd
+ * @param {{ spawn?: typeof spawn }} [args.deps]
+ * @returns {Promise<{ ok: true, branch: string } | { ok: false, reason: string }>}
+ */
+async function resolveGitBranch({ cwd, deps = {} }) {
+  const spawnFn = deps.spawn ?? spawn;
+  return new Promise((resolveP) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawnFn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        cwd, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolveP({ ok: false, reason: `git spawn failed: ${err.message}` });
+      return;
+    }
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+    child.on('error', (err) => {
+      resolveP({ ok: false, reason: `git spawn failed: ${err.message}` });
+    });
+    child.on('close', (code) => {
+      if (code !== 0) {
+        resolveP({ ok: false, reason: `git rev-parse exited ${code}: ${stderr.trim() || 'no output'}` });
+        return;
+      }
+      const branch = stdout.trim();
+      if (!branch) {
+        resolveP({ ok: false, reason: 'git rev-parse returned empty branch name' });
+        return;
+      }
+      resolveP({ ok: true, branch });
+    });
+  });
+}
+
 /**
  * @param {string[]} argv - argv slice after `finalise`
  * @param {object} [deps] - injectable seams (detect / spawn / prompt / install /
@@ -409,8 +498,76 @@ export async function main(argv, deps = {}) {
       stderr.write(`Report: ${outPath}\n`);
       return 4;
     }
+    // Referee-guarantee train (REQ-165 / US-16501, docs claims C-28,
+    // C-29, C-30, C-36): three further per-AC verdicts join the
+    // finalise refusal list. UI-BASELINE-UNMET (a browserVerification
+    // record whose verdict came back `block`, including the aggregate
+    // for a block-severity probe-pack failure, C-36), BROWSER-VERIFICATION-MISSING
+    // (a UI-bearing FBS with no bound browserVerification record), and
+    // SCOPE-MISMATCH (a bound TC narrower than the AC scope, per NV-BL-GATE-01).
+    // The docs page does not spell a named sister opt-out for these three;
+    // the refusal is honest and there is no ack path here. Graceful on the
+    // older report shape (no perAcVerdicts field): behaviour matches the
+    // MOCK-ONLY branch above.
+    if (passLoaded.ok && reportHasUiBaselineUnmet(passLoaded.report)) {
+      const uiUnmet = findUiBaselineUnmetAcs(passLoaded.report);
+      const acList = uiUnmet.map((a) => a.acId).filter(Boolean).join(', ');
+      stderr.write(`[finalise] gate NOT promoted: ${uiUnmet.length} AC(s) came back UI-BASELINE-UNMET on the report (${acList}); ${fbsId} left '${currentStatus}'.\n`);
+      stderr.write('The deployed UI failed at least one bound baseline invariant; a block-severity probe-pack failure aggregates into the same verdict. Fix the UI or the baseline, re-run rcf verify browser, then re-run finalise. Referee-guarantees claims C-28 and C-36.\n');
+      stderr.write(summariseReport(passLoaded.report));
+      stderr.write(`Report: ${outPath}\n`);
+      return 4;
+    }
+    if (passLoaded.ok && reportHasBrowserVerificationMissing(passLoaded.report)) {
+      const bvMissing = findBrowserVerificationMissingAcs(passLoaded.report);
+      const acList = bvMissing.map((a) => a.acId).filter(Boolean).join(', ');
+      stderr.write(`[finalise] gate NOT promoted: ${bvMissing.length} AC(s) came back BROWSER-VERIFICATION-MISSING on the report (${acList}); ${fbsId} left '${currentStatus}'.\n`);
+      stderr.write('A UI-bearing FBS has no browserVerification record on the manifest; verify has nothing to read for the baseline check. Run rcf verify browser <fbs-id> to lay the record down, then re-run finalise. Referee-guarantees claim C-29.\n');
+      stderr.write(summariseReport(passLoaded.report));
+      stderr.write(`Report: ${outPath}\n`);
+      return 4;
+    }
+    if (passLoaded.ok && reportHasScopeMismatch(passLoaded.report)) {
+      const scopeMismatch = findScopeMismatchAcs(passLoaded.report);
+      const acList = scopeMismatch.map((a) => a.acId).filter(Boolean).join(', ');
+      stderr.write(`[finalise] gate NOT promoted: ${scopeMismatch.length} AC(s) came back SCOPE-MISMATCH on the report (${acList}); ${fbsId} left '${currentStatus}'.\n`);
+      stderr.write('A bound TC is narrower than the AC scope (NV-BL-GATE-01). Widen the TC or narrow the AC scope in define, then re-run verify and finalise. Referee-guarantees claim C-30.\n');
+      stderr.write(summariseReport(passLoaded.report));
+      stderr.write(`Report: ${outPath}\n`);
+      return 4;
+    }
+    // Referee-guarantee train (REQ-165 / US-16502, docs claim C-26):
+    // the merge-state precondition. `verified` promises "an actual
+    // post-merge runtime check" and the way finalise proves that is
+    // by refusing when the working tree is not on the default branch
+    // (main / master), so a mid-branch dev-loop run cannot stamp
+    // verified. --allow-pre-merge is the deliberate opt-out for
+    // pre-merge dry runs; the decision is logged in the finalise
+    // stdout so the operator sees it. Absent a git working tree the
+    // check degrades to a warn line rather than a hard fail: verify
+    // against a bare tarball deploy is legitimate and should not be
+    // refused by a git-shape check.
+    const gitBranch = await resolveGitBranch({ cwd, deps });
+    if (!gitBranch.ok) {
+      stderr.write(`[warn] finalise: could not resolve git branch (${gitBranch.reason}); skipping the post-merge precondition. Referee-guarantees claim C-26.\n`);
+    } else if (!DEFAULT_BRANCH_NAMES.has(gitBranch.branch)) {
+      if (flags['allow-pre-merge']) {
+        if (!quiet) {
+          stdout.write(`[finalise] --allow-pre-merge: promoting on branch '${gitBranch.branch}' (not a default trunk). Referee-guarantees claim C-26 records the pre-merge decision here.\n`);
+        }
+      } else {
+        stderr.write(`[finalise] gate NOT promoted: git working tree is on branch '${gitBranch.branch}', not a default trunk (${[...DEFAULT_BRANCH_NAMES].join(' / ')}); ${fbsId} left '${currentStatus}'.\n`);
+        stderr.write('The referee-guarantees page promises that verified traces to an actual post-merge runtime check. Merge the branch and re-run finalise, or pass --allow-pre-merge for a deliberate pre-merge dry run (the decision is logged on stdout). Referee-guarantees claim C-26.\n');
+        return 4;
+      }
+    }
     const result = await updateDocument({
-      projectRoot, tree, id: fbsId, sets: [{ path: 'executionStatus', value: 'verified' }], options: {},
+      projectRoot, tree, id: fbsId, sets: [{ path: 'executionStatus', value: 'verified' }],
+      // Referee-guarantee train (REQ-165 / US-16502, docs claim C-22):
+      // the writer refuses executionStatus=verified on FBS by default.
+      // Finalise is the only path the docs promise can write it, so
+      // this call carries the override flag through.
+      options: { allowVerifiedOverride: true },
     });
     if (isRcfError(result)) {
       if (result.kind === 'ioFailure') { writeUnexpectedFailure(result, stderr); return 1; }

package/src/cli/help.js

@@ -19,6 +19,7 @@ import { HELP as AUDIT_EVAL_HELP } from './eval.js';
 import { HELP as CREATE_HELP } from './create.js';
 import { HELP as DELETE_HELP } from './delete.js';
 import { HELP as DOCTOR_HELP } from './doctor.js';
+import { HELP as FEEDBACK_HELP } from './feedback.js';
 import { HELP as FINALISE_HELP } from './finalise.js';
 import { HELP as GUIDANCE_HELP } from './guidance.js';
 import { HELP as IMPACT_HELP } from './impact.js';
@@ -68,6 +69,8 @@ core         Platform plumbing that predates any RCF stage.
   mcp                      Serve the project over MCP (local stdio).
   version [--check]        Print installed version; --check compares
                            against the release feed.
+  feedback <verb>          Log a blueprint or core finding locally, and
+                           (later slices) ask once, submit or bundle.
   help [group] [verb]      Print help for a group or a verb.
 
 discover     Learn what is already true for this project.
@@ -143,6 +146,8 @@ Verbs:
   mcp                      Serve the project over MCP (local stdio).
   version [--check]        Print installed version; --check compares
                            against the release feed.
+  feedback <verb>          Log a blueprint or core finding locally, and
+                           (later slices) ask once, submit or bundle.
   help [group] [verb]      Print help for a group or a verb.
 
 Run 'rcf help <verb>' for per-verb help.
@@ -313,6 +318,7 @@ export const CORE_HELP = {
   guidance: GUIDANCE_HELP,
   mcp: MCP_HELP,
   version: VERSION_HELP,
+  feedback: FEEDBACK_HELP,
 };
 
 /**

package/src/cli/init.js

@@ -38,6 +38,10 @@ import {
 import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
 import { writeKnowledgeSeed } from '../setup/knowledge-seed.js';
 import { writeIdentityTemplate } from '../setup/identity-seed.js';
+import {
+  writeClaudeFeedbackHooks,
+  writeCodexFeedbackHooks,
+} from '../setup/feedback-hooks.js';
 import {
   composeGitignoreBlock,
   computeGitignoreBlockHash,
@@ -52,6 +56,8 @@ const OPTION_SPEC = {
   'non-interactive': { type: 'boolean' },
   'no-agent-setup': { type: 'boolean' },
   'no-playwright-mcp': { type: 'boolean' },
+  'no-feedback-hooks': { type: 'boolean' },
+  'bin-path': { type: 'string' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
 };
@@ -81,6 +87,13 @@ Options:
                             init writes no Playwright entry and touches no
                             existing one. Use when a user-scope Playwright
                             entry is declared in a harness init cannot probe.
+  --no-feedback-hooks       Skip the feedback hook install step
+                            (.claude/settings.json + .codex/hooks.json).
+                            RULE 17 in the managed instructions block still
+                            covers the ask via the belt-and-braces path.
+  --bin-path <path>         Absolute path to the rcf binary. When set, hook
+                            and MCP entries use 'node <path> ...' instead of
+                            'npx rcf-lite ...' (pinned deployments).
   --quiet                   Suppress non-error stdout
   --help                    Print this help
 `;
@@ -222,6 +235,29 @@ export async function main(argv, deps = {}) {
   // refreshed in place; operator content outside preserved byte-for-byte.
   const gitignoreResult = await ensureManagedGitignore({ projectRoot: cwd });
 
+  // Step 6: feedback hooks (ADR-4108). Writes the three Stop /
+  // SessionEnd / SessionStart entries into .claude/settings.json and
+  // .codex/hooks.json unless --no-feedback-hooks is set. Merge
+  // discipline mirrors writeMcpConfig: parse, refuse on invalid JSON,
+  // add ours only when absent, never clobber. --bin-path pins the
+  // hook command to `node <path>` for pinned-bin deployments.
+  const feedbackOptOut = Boolean(flags['no-feedback-hooks']);
+  const feedbackBinPath = typeof flags['bin-path'] === 'string' ? flags['bin-path'] : undefined;
+  let claudeHookResult = null;
+  let codexHookResult = null;
+  if (!feedbackOptOut) {
+    claudeHookResult = await writeClaudeFeedbackHooks({ projectRoot: cwd, binPath: feedbackBinPath });
+    if (claudeHookResult && 'kind' in claudeHookResult && 'message' in claudeHookResult) {
+      stderr.write(`[error] ${claudeHookResult.kind} ${claudeHookResult.message}\n`);
+      return 2;
+    }
+    codexHookResult = await writeCodexFeedbackHooks({ projectRoot: cwd, binPath: feedbackBinPath });
+    if (codexHookResult && 'kind' in codexHookResult && 'message' in codexHookResult) {
+      stderr.write(`[error] ${codexHookResult.kind} ${codexHookResult.message}\n`);
+      return 2;
+    }
+  }
+
   // High-level completion summary: what was set up and what to do next -
   // not a developer file list (operator review 2026-07-16, comment 3a).
   if (!flags.quiet) {
@@ -248,6 +284,10 @@ export async function main(argv, deps = {}) {
     stdout.write(`  Knowledge space    ${knowledgeVerbAndTarget(knowledgeResult)}.\n`);
     stdout.write(`  Operator profile   ${identityVerbAndTarget(identityResult)}.\n`);
     stdout.write(`  Gitignore          ${gitignoreVerbAndTarget(gitignoreResult)}.\n`);
+    stdout.write(`  Feedback hooks     ${feedbackHooksVerbAndTarget(feedbackOptOut, claudeHookResult, codexHookResult)}.\n`);
+    if (feedbackOptOut) {
+      stdout.write('    (no-feedback-hooks) RULE 17 in the managed instructions block still covers the ask via the belt-and-braces path.\n');
+    }
     stdout.write('\nNext: start your agent session in this directory and tell it what you want to build. '
       + 'It elicits the requirements and drives the build from there - you do not fill in the document chain by hand.\n');
     stdout.write('\nRun `rcf doctor` to confirm the wiring stays clean over time '
@@ -268,6 +308,29 @@ function identityVerbAndTarget(result) {
   return 'template at rcf/.identity/profile.md (gitignored by default; fill in what is useful)';
 }
 
+function feedbackHooksVerbAndTarget(optOut, claudeResult, codexResult) {
+  if (optOut) return 'skipped (--no-feedback-hooks; RULE 17 fallback in the managed instructions block still applies)';
+  const claudeVerb = claudeResult
+    ? (claudeResult.action === 'kept'
+      ? 'already present in .claude/settings.json'
+      : (claudeResult.action === 'created'
+        ? 'written to .claude/settings.json'
+        : (claudeResult.action === 'foreign'
+          ? 'foreign entry present in .claude/settings.json (rcf doctor --check feedback-hooks reports the details; no clobber)'
+          : 'merged into .claude/settings.json')))
+    : 'not touched';
+  const codexVerb = codexResult
+    ? (codexResult.action === 'kept'
+      ? 'already present in .codex/hooks.json'
+      : (codexResult.action === 'created'
+        ? 'written to .codex/hooks.json'
+        : (codexResult.action === 'foreign'
+          ? 'foreign entry present in .codex/hooks.json (rcf doctor --check feedback-hooks reports the details; no clobber)'
+          : 'merged into .codex/hooks.json')))
+    : 'not touched';
+  return `${claudeVerb}; ${codexVerb}`;
+}
+
 function gitignoreVerbAndTarget(result) {
   if (result.action === 'noop') return 'managed block already up to date in .gitignore';
   if (result.action === 'created') return 'managed block written to .gitignore (rcf/.identity/ ignored)';

package/src/cli/update.js

@@ -24,6 +24,12 @@ const OPTION_SPEC = {
   // Phase 10 (X2 CodeNode bridge, D5): re-derive a CN's file-level
   // dependencies via dependency-cruiser, merged into dependencies[].
   'derive-deps': { type: 'boolean' },
+  // Referee-guarantee train (REQ-165 / US-16502, docs claim C-22):
+  // the writer refuses executionStatus=verified on FBS by default so
+  // finalise is the only path that promotes to verified. This flag
+  // is the deliberate manual override: a logged operator decision
+  // that skips the post-merge runtime check finalise runs.
+  'acknowledge-verified-override': { type: 'boolean' },
 };
 
 export const HELP = `Usage: rcf define update <id> [options]
@@ -38,6 +44,14 @@ Options:
   --derive-deps             CN only: re-derive file-level dependencies via
                             dependency-cruiser and merge into dependencies[]
                             (dev-time assist; never a runtime dependency)
+  --acknowledge-verified-override
+                            FBS only: acknowledge writing
+                            executionStatus=verified without a finalise
+                            run. The writer refuses this write by
+                            default so finalise (rcf build finalise) is
+                            the sole path to verified; the override is
+                            a deliberate, logged operator decision that
+                            skips the post-merge runtime check.
   --help                    Print this help
 `;
 
@@ -138,7 +152,13 @@ export async function main(argv, deps = {}) {
   }
   const result = await updateDocument({
     projectRoot, tree: walkResult.tree, id, patch, sets,
-    options: { dryRun: Boolean(flags['dry-run']) },
+    options: {
+      dryRun: Boolean(flags['dry-run']),
+      // Referee-guarantee train (REQ-165 / US-16502, docs claim C-22):
+      // the writer's default refuses executionStatus=verified on FBS;
+      // this flag routes the operator's deliberate override through.
+      allowVerifiedOverride: Boolean(flags['acknowledge-verified-override']),
+    },
     walkErrors: walkResult.errors,
   });
   if (isRcfError(result)) return handleWriterError(result, stderr);

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/core/store/walker.js

@@ -817,6 +817,39 @@ function collectBrokenReferences(tree, errors) {
       filePath: `rcf/adrs/${(adr.adrId ?? '').toLowerCase()}.json`,
       message: `ADR ${adr.adrId} references unknown TAD ${adr.tadId}`,
     });
+    // Referee-guarantee train (REQ-163 / US-16301, docs claim C-7):
+    // the "every reference in every document resolves" promise on the
+    // referee-guarantees page needs the ADR-schema-declared cross-links
+    // walked here. `supersededBy` is the strong, chain-of-decisions
+    // reference: an ADR that points at an unknown successor is a broken
+    // history record. Walk it under the same check helper as every other
+    // cross-link so a bad target fails validate with a brokenReference
+    // named to the ADR file and the field.
+    //
+    // `relatedAdrs` (the soft, "see also" back-reference) is intentionally
+    // NOT walked here. The `rcf define blueprint supersede` verb writes
+    // a project ruling ADR whose relatedAdrs lists BOTH the applied
+    // blueprint ADR (present on disk) AND the incoming blueprint ADR
+    // (not yet on disk: the incoming blueprint add is the closing step
+    // of the option-3 workflow the conflict message prints). Walking
+    // relatedAdrs would refuse that ratified workflow between the
+    // supersede write and the re-add. Escalation-clause carry: the docs
+    // claim held by `supersededBy` alone matches the strong-reference
+    // half of the referee promise; the soft `relatedAdrs` half is a
+    // schemas follow-up (either "value-narrowed to already-applied ADR
+    // ids" or "walked but with a workflow-aware exception on the
+    // supersede write path").
+    if (typeof adr.supersededBy === 'string' && adr.supersededBy.length > 0) {
+      check({
+        docId: adr.adrId,
+        docKind: 'adr',
+        fromField: 'supersededBy',
+        targetId: adr.supersededBy,
+        expectedKind: 'adr',
+        filePath: `rcf/adrs/${(adr.adrId ?? '').toLowerCase()}.json`,
+        message: `ADR ${adr.adrId} references unknown ADR ${adr.supersededBy} in supersededBy`,
+      });
+    }
   }
 
   // FBS parent + cross-link + dependency checks. `buildOrder` uniqueness

package/src/core/store/writer.js

@@ -1115,6 +1115,29 @@ export async function updateDocument({ projectRoot, tree, id, patch, sets = [],
     return rcfError({ kind: 'usage', message: `update: id ${id} not found`, documentId: id });
   }
 
+  // Referee-guarantee train (REQ-165 / US-16502, docs claim C-22):
+  // `rcf build finalise` is the only path that writes FBS
+  // executionStatus=verified. The manifest / FBS schema admits
+  // `verified` as an executionStatus value (the finalise writer
+  // depends on that), so `validateDocument` would silently accept a
+  // manual override on the update path. Refuse it here unless the
+  // caller passed `options.allowVerifiedOverride: true` (finalise
+  // sets that flag; the define-update CLI sets it only when the
+  // operator passes `--acknowledge-verified-override`, per the
+  // escalation clause on this train). The docs promise is that a
+  // chain that says `verified` traces to an actual post-merge
+  // runtime check by construction; this refusal is the gate.
+  if (kind === 'fbs' && !options.allowVerifiedOverride) {
+    const touchesVerified = (patch && patch.executionStatus === 'verified')
+      || sets.some((s) => s.path === 'executionStatus' && s.value === 'verified');
+    if (touchesVerified) {
+      return rcfError({
+        kind: 'usage',
+        message: `update: refusing to write executionStatus=verified on ${id}; verified is written only by the finalise gate (rcf build finalise <fbs-id> --url <deploy-url>). For a deliberate manual override use --acknowledge-verified-override on rcf define update; the override is a logged operator decision that skips the post-merge runtime check.`,
+        documentId: id,
+      });
+    }
+  }
   // Build patched body: start from doc, apply --from-file deep merge,
   // then apply each --set dot-path assignment.
   let next = deepClone(doc);