rcf-lite 0.29.0 → 0.31.0

package/src/query/index.js

@@ -26,6 +26,7 @@ export {
   STAGE_FALLBACK_PERSONA,
   stagePolicy,
   parseAcClass,
+  resolveOwnerRefField,
   parseInterfaceDraft,
   parseTacPurposeDraft,
   parseCoreEntityDraft,
@@ -60,4 +61,8 @@ export { formatMermaid } from './formatters/mermaid.js';
 // 0.8.0 slug-train car 3: NV-BL-SR-03 addendum (ruling-sheet item 1)
 // -- traceability / query tools share the refuse-first posture that
 // gates rcf build. Callers wrap their query producer with this.
-export { runWithAdmissibilityGate } from './refuse-on-admissibility.js';
+export {
+  runWithAdmissibilityGate,
+  evaluateDefineAdmissibility,
+  evaluateDefineStageAdmissibility,
+} from './refuse-on-admissibility.js';

package/src/query/readiness.js

@@ -15,8 +15,9 @@
 
 import { computeQueue } from '../build/queue.js';
 import { computeCoverage } from './coverage.js';
-import { computeDelta } from './delta.js';
+import { computeDelta, computeTreeHash, hashDocument } from './delta.js';
 import { computeImpact } from './impact.js';
+import { isProbeRunner } from '../define/probe-runner.js';
 import {
   STAGE_GATES,
   STAGE_ORDER,
@@ -37,6 +38,23 @@ import {
  * @property {string | null} frozenAt
  * @property {string | null} treeHash
  * @property {string} currentTreeHash
+ * @property {string} litmusHash
+ *   The current tree hash computed with the probes ledger excluded
+ *   (ADR-4131 extended, 0.30.0 PR 7 R9, w-2026-10-03-dave-011). The
+ *   probes ledger is inside `currentTreeHash` (ADR-4120), so a litmus
+ *   reading referencing `currentTreeHash` can never match the hash
+ *   recomputed after the write that landed the reading. `litmusHash`
+ *   is the content-stable hash the harness pins litmus readings to:
+ *   writing to the probes ledger does not change it, so n readers can
+ *   land `litmus:<reader>:` entries at the same hash and the --litmus
+ *   check matches them deterministically. Writes to the brief,
+ *   decisions or concerns ledgers do change `litmusHash` the same way
+ *   they change `currentTreeHash`: those changes shift the content
+ *   the readers were attesting to and stale readings fall out of the
+ *   count. The trade-off is intentional: litmus readings do not
+ *   attest to probe findings written after them (probe entries are
+ *   themselves readings, so the attestation applies to the stable
+ *   content, not to its own body).
  * @property {string | null} buildAt   fbsId at the queue head, or null
  * @property {number} fbsTotal
  */
@@ -151,6 +169,16 @@ import {
  * @param {string | null | undefined} [args.profileText]  rcf/.identity/profile.md contents
  * @param {Map<string, unknown> | undefined} [args.testPointers]
  * @param {Array<unknown> | undefined} [args.validateErrors]  tree-wide validate + walker errors
+ * @param {Set<string> | undefined} [args.resolvedPaths]  ADR-4131 (0.30.0 PR 5): set of repo-relative paths the
+ *   caller already resolved on disk; threaded into the stage context so
+ *   `shapes:pathsResolve` can decide the D3 bite without I/O. Undefined
+ *   means no paths are known-resolved.
+ * @param {import('../define/probe-runner.js').ProbeRunner | null | undefined} [args.probeRunner]  ADR-4131 extended
+ *   (0.30.0 PR 7, spec section 11.6): injectable `({ reqId, tree }) => findings[]`
+ *   seam called once per REQ in scope; returned findings are merged into
+ *   `ledgers.probes.probes[]` as open probe entries so `consistency:probeCount`
+ *   reports them. Default null: the result equals the 0.29.0 result on the
+ *   same fixture (AC-17504-2). No runner ships; the harness is the runner.
  * @returns {ReadinessResult}
  */
 export function computeReadiness(tree, args = {}) {
@@ -161,6 +189,8 @@ export function computeReadiness(tree, args = {}) {
     profileText = null,
     testPointers = undefined,
     validateErrors = [],
+    resolvedPaths = undefined,
+    probeRunner = null,
   } = args;
 
   // 1. Delta.
@@ -207,6 +237,59 @@ export function computeReadiness(tree, args = {}) {
     ...impactedSeen,
   ]);
 
+  // 3b. Probe seam (ADR-4131 extended, 0.30.0 PR 7). Call the runner
+  // once per REQ in scope and merge the returned findings into the
+  // probe ledger the gate reads. With no runner (the default) nothing
+  // changes and the result equals the 0.29.0 result on the same
+  // fixture (AC-17504-2). The merge is additive and does not mutate
+  // the caller's ledgers object: a new object with a cloned
+  // probes.probes[] is passed down to the gates and surfaces on the
+  // final result through the same ledger consumer.
+  let activeLedgers = ledgers;
+  if (isProbeRunner(probeRunner)) {
+    const reqIdsInScope = [...scopeSet].filter((id) => id.startsWith('REQ-'));
+    /** @type {Array<Record<string, unknown>>} */
+    const injected = [];
+    const priorProbes = /** @type {any} */ (ledgers?.probes);
+    const priorList = Array.isArray(priorProbes?.probes) ? [...priorProbes.probes] : [];
+    const nextId = (() => {
+      let max = 0;
+      for (const entry of priorList) {
+        const n = Number(entry?.id);
+        if (Number.isFinite(n) && n > max) max = n;
+      }
+      return () => { max += 1; return max; };
+    })();
+    for (const reqId of reqIdsInScope) {
+      let findings;
+      try {
+        findings = probeRunner({ reqId, tree });
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(findings)) continue;
+      for (const finding of findings) {
+        if (!finding || typeof finding !== 'object') continue;
+        const text = typeof finding.finding === 'string' ? finding.finding : null;
+        if (!text) continue;
+        injected.push({
+          id: nextId(),
+          reqId: typeof finding.reqId === 'string' ? finding.reqId : reqId,
+          finding: text,
+          severity: typeof finding.severity === 'string' ? finding.severity : 'medium',
+          status: typeof finding.status === 'string' ? finding.status : 'open',
+          addedAt: typeof finding.hash === 'string' ? finding.hash : delta.currentTreeHash,
+        });
+      }
+    }
+    if (injected.length > 0) {
+      activeLedgers = {
+        ...ledgers,
+        probes: { ...(priorProbes ?? {}), probes: [...priorList, ...injected] },
+      };
+    }
+  }
+
   // 4. Coverage: tree-wide plus per REQ ancestor of the delta.
   const coverageTree = computeCoverage(tree, { testPointers, strict: true });
   const deltaReqIds = collectDeltaReqAncestors(tree, pivotIds);
@@ -223,7 +306,7 @@ export function computeReadiness(tree, args = {}) {
   /** @type {import('./gates.js').StageContext} */
   const ctx = {
     tree,
-    ledgers,
+    ledgers: activeLedgers,
     delta,
     freeze,
     scope: scopeSet,
@@ -236,6 +319,7 @@ export function computeReadiness(tree, args = {}) {
     profile,
     currentTreeHash,
     priorStages: undefined,
+    resolvedPaths,
   };
   stages.push(checkD1Brief(ctx));
   stages.push(checkD2Skeleton(ctx));
@@ -274,6 +358,13 @@ export function computeReadiness(tree, args = {}) {
       frozenAt: delta.frozenAt,
       treeHash: delta.treeHash,
       currentTreeHash: delta.currentTreeHash,
+      // ADR-4131 extended, 0.30.0 PR 7 R9 (w-2026-10-03-dave-011).
+      // The content-stable hash the harness pins litmus readings to:
+      // computed over the tree + brief / decisions / concerns ledgers,
+      // excluding the probes ledger so a reader write does not shift
+      // the hash it pins its own entry to. See computeLitmusHash
+      // JSDoc above for the full rationale and trade-off.
+      litmusHash: computeLitmusHash(tree, activeLedgers),
       buildAt: queue.nextActionable ?? null,
       fbsTotal,
     },
@@ -502,6 +593,92 @@ export function parsePersonaFlag(raw) {
   throw new Error(`unknown --persona ${raw} (expected productOwner | engineer)`);
 }
 
+/**
+ * Parse a `--litmus <n>` flag value as a positive integer. Returns
+ * null when the flag is absent, the parsed integer otherwise, or
+ * throws a usage error for a non-integer or non-positive value
+ * (ADR-4131 extended, 0.30.0 PR 7).
+ *
+ * @param {string | undefined} raw
+ * @returns {number | null}
+ */
+export function parseLitmusFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`unknown --litmus ${raw} (expected a positive integer)`);
+  }
+  return n;
+}
+
+/**
+ * Count distinct litmus readers who have landed a probe-ledger entry
+ * at a given tree hash. A litmus reading is a probe-ledger entry
+ * whose `finding` begins `litmus:<reader>:` and whose text includes
+ * the given `hash`. Returns the set of reader ids (deduplicated) that
+ * attest at that hash (ADR-4131 extended, 0.30.0 PR 7). Pure.
+ *
+ * @param {object | undefined | null} ledgers
+ * @param {string | null | undefined} hash
+ * @returns {Set<string>}
+ */
+/**
+ * Compute the litmus hash of a tree + ledger bundle: the tree hash
+ * recomputed with the probes ledger excluded (ADR-4131 extended,
+ * 0.30.0 PR 7 R9, w-2026-10-03-dave-011). The returned string is a
+ * `sha256:<hex>` that is stable under writes to the probes ledger
+ * (so n readers can land `litmus:<reader>:` entries at the same
+ * hash) and that shifts the same way `currentTreeHash` shifts under
+ * writes to the brief, decisions or concerns ledgers (which do
+ * change what the readers were attesting to).
+ *
+ * The function reuses `hashDocument` and `computeTreeHash` from the
+ * delta module; it never touches the filesystem. The brief, decisions
+ * and concerns ledgers contribute their `ledger:<name>` docHash as
+ * they do in `currentTreeHash`; the probes ledger is omitted. The
+ * tree document ids and their hashes are unchanged from the delta
+ * computation.
+ *
+ * Pure.
+ *
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @param {import('./delta.js').LedgerBundle | null | undefined} [ledgers]
+ * @returns {string}
+ */
+export function computeLitmusHash(tree, ledgers) {
+  /** @type {Record<string, string>} */
+  const docHashes = {};
+  if (tree && tree.byId) {
+    for (const id of [...tree.byId.keys()].sort()) {
+      docHashes[id] = hashDocument(tree.byId.get(id));
+    }
+  }
+  const bundle = ledgers ?? {};
+  for (const [name, body] of Object.entries(bundle)) {
+    if (name === 'probes') continue;
+    if (body === undefined || body === null) continue;
+    docHashes[`ledger:${name}`] = hashDocument(body);
+  }
+  return computeTreeHash(docHashes);
+}
+
+export function countLitmusReadersAtHash(ledgers, hash) {
+  const readers = new Set();
+  if (typeof hash !== 'string' || hash.length === 0) return readers;
+  const probes = /** @type {any} */ (ledgers?.probes);
+  const list = Array.isArray(probes?.probes) ? probes.probes : [];
+  for (const entry of list) {
+    const text = typeof entry?.finding === 'string' ? entry.finding : '';
+    if (!text.startsWith('litmus:')) continue;
+    const m = text.match(/^litmus:([^:]+):/);
+    if (!m) continue;
+    const combined = typeof entry.hash === 'string' ? `${text} ${entry.hash}` : text;
+    if (!combined.includes(hash)) continue;
+    readers.add(m[1]);
+  }
+  return readers;
+}
+
 /**
  * Format the two verdict lines shared by the CLI text report and
  * the Readiness tab (proposal section 2.3). The strings are built

package/src/query/refuse-on-admissibility.js

@@ -14,8 +14,32 @@
 // REFUSE the wrapper returns a refusal envelope naming the unresolved
 // findings. On PASS or PASS-WITH-OVERRIDES the query's own result flows
 // through unchanged.
+//
+// 0.30.0 PR 9 (REQ-179 enforcement locus, spec section 17): the wrap
+// also cites the three DEFINE-stage NV-DL rules the review found
+// enforced only by the gates themselves (ADM-02 for D4 stories floor,
+// ADM-03 for D3 shapes bite, ADM-04 for the `rcf define validate`
+// finding set). Callers pass the computed readiness result (or the
+// stage envelopes they already carry) and the validate-errors array;
+// the wrap evaluates each rule against the current tree hash and the
+// freeze.gates acknowledgement map, cites the rule ids in the refusal
+// envelope, and leaves the enforcement posture of each caller intact
+// (readiness stays informational; freeze still exits 4 on an unfrozen
+// tree via its own freezeableAfterAck check). A stage that is
+// 'passed', 'acknowledged' or 'notApplicable' at the current hash
+// never cites a rule. Override channels differ by rule (R12 ruling
+// 2026-10-03): ADM-03 (D3) is cleared by an `--ack <gate>=<reason>`
+// recorded on freeze.gates at the current tree hash (D3 is ackable
+// per decision 9); ADM-02 (D4) is NOT ackable (decision 9 keeps D4
+// blocking) and its only recordedInChain channel is `freeze.override`
+// written by `rcf build bundle --next --override "<reason>"` -- in
+// the normal case the author fixes the failing D4 findings. ADM-04
+// has no gate ack either: the override is a chain correction
+// committed to git (NV-DL-ADM-04's recordedInChain shape).
 
 import { enforceAdmissibility, getRulesetToolScope } from '#admissibility';
+// 0.30.0 PR 8 (REQ-179 / TAC-4125): NV-DL admissibility.
+import { loadFreezeRecord } from '../define/freeze-record.js';
 
 /**
  * @typedef {import('../admissibility/enforce.js').AdmissibilityVerdict} AdmissibilityVerdict
@@ -30,19 +54,83 @@ import { enforceAdmissibility, getRulesetToolScope } from '#admissibility';
  * @property {string} [refusal] - human-readable summary on 'refused-admissibility'.
  */
 
+/**
+ * 0.30.0 PR 9 (REQ-179 enforcement locus): evaluate the three
+ * DEFINE-stage NV-DL rules against a readiness result plus a
+ * validate-errors array. Returns the set of refuseByDefault rule ids
+ * that bite at the current tree hash, after `--ack` reasons on
+ * freeze.gates are honoured. The caller composes this with the
+ * NV-BL admissibility verdict in `runWithAdmissibilityGate`.
+ *
+ * A stage counts as biting when:
+ *   - ADM-02: the D4 `stage.state` is `'failing'` (fix the failing
+ *     D4 findings; `freeze.override` written by
+ *     `rcf build bundle --next --override "<reason>"` is the only
+ *     recordedInChain override channel -- D4 is not ackable per
+ *     decision 9).
+ *   - ADM-03: the D3 `stage.state` is `'failing'` (D3 is ackable;
+ *     the override channel is `--ack <gate>=<reason>` on
+ *     `rcf define readiness` / `rcf define freeze`).
+ *   - ADM-04: `validateErrors.length > 0` (override is a chain
+ *     correction committed to git, not a gate ack).
+ *
+ * For ADM-03 the readiness compose folds a current-hash
+ * `--ack <gate>=<reason>` into `state: 'acknowledged'` via
+ * `foldState`, and a stale ack never masks a current failure.
+ * D4 is not folded (decision 9 keeps `ackable` to D3/D5/D6 only), so
+ * an ADM-02 citation only clears when the author fixes the findings
+ * or records `freeze.override`.
+ *
+ * @param {object} args
+ * @param {Array<{ stage: string, gate: string, state: string }>} [args.stages]
+ * @param {Array<unknown>} [args.validateErrors]
+ * @returns {{ bitingRules: string[], d3State: string|null, d4State: string|null, validateCount: number }}
+ */
+export function evaluateDefineStageAdmissibility({ stages = [], validateErrors = [] } = {}) {
+  const stageByName = new Map();
+  for (const s of stages) {
+    if (s && typeof s.stage === 'string') stageByName.set(s.stage, s);
+  }
+  const d3 = stageByName.get('D3');
+  const d4 = stageByName.get('D4');
+  const bitingRules = [];
+  if (d4 && d4.state === 'failing') bitingRules.push('NV-DL-ADM-02');
+  if (d3 && d3.state === 'failing') bitingRules.push('NV-DL-ADM-03');
+  const validateCount = Array.isArray(validateErrors) ? validateErrors.length : 0;
+  if (validateCount > 0) bitingRules.push('NV-DL-ADM-04');
+  return {
+    bitingRules,
+    d3State: d3?.state ?? null,
+    d4State: d4?.state ?? null,
+    validateCount,
+  };
+}
+
 /**
  * Wrap a query producer with the refuse-first posture. The producer is
  * only called when admissibility passes (or passes-with-overrides);
  * on refusal, its produce function does NOT run and the wrapper
  * returns a refusal envelope naming the unresolved rules.
  *
+ * 0.30.0 PR 9: callers may also pass `defineStages` (the computed
+ * readiness `stages[]`) and `defineValidateErrors` so the wrap can
+ * cite NV-DL-ADM-02/03/04 alongside the NV-BL rules. The producer
+ * STILL runs when the NV-BL verdict is pass or passWithOverrides,
+ * even when the NV-DL rules bite: the wrap's refusal shape is reserved
+ * for the hard NV-BL refusal (readiness is informational per
+ * AC-17902-4; freeze keeps its own freezeableAfterAck check). The
+ * biting NV-DL rule ids appear on the returned envelope so callers can
+ * log them in a single consistent line.
+ *
  * @param {object} args
  * @param {object} args.tree
  * @param {string|null} [args.chainRulesetVersion]
  * @param {AdmissibilityOverride[]} [args.overrides]
  * @param {() => (Promise<*> | *)} args.produce - the underlying query
  * @param {object} [args.opts] - passed through to enforceAdmissibility
- * @returns {Promise<QueryResult>}
+ * @param {Array<{ stage: string, gate: string, state: string }>} [args.defineStages]
+ * @param {Array<unknown>} [args.defineValidateErrors]
+ * @returns {Promise<QueryResult & { defineRules?: string[] }>}
  */
 export async function runWithAdmissibilityGate({
   tree,
@@ -50,6 +138,8 @@ export async function runWithAdmissibilityGate({
   overrides = [],
   produce,
   opts = {},
+  defineStages = [],
+  defineValidateErrors = [],
 } = {}) {
   const toolScope = await getRulesetToolScope();
   if (!toolScope.traceabilityAndQueryTools) {
@@ -60,14 +150,57 @@ export async function runWithAdmissibilityGate({
     return { status: 'ok', payload };
   }
   const verdict = await enforceAdmissibility({ tree, chainRulesetVersion, overrides, opts });
+  const defineEval = evaluateDefineStageAdmissibility({
+    stages: defineStages,
+    validateErrors: defineValidateErrors,
+  });
   if (verdict.verdict === 'refuse') {
-    const ruleIds = [...new Set(verdict.unresolved.map((f) => f.rule).filter(Boolean))].sort();
+    const nvBlRuleIds = [...new Set(verdict.unresolved.map((f) => f.rule).filter(Boolean))].sort();
+    const combinedRuleIds = [...new Set([...nvBlRuleIds, ...defineEval.bitingRules])].sort();
     return {
       status: 'refused-admissibility',
       admissibility: verdict,
-      refusal: `traceability/query tool refused (NV-BL-SR-03 addendum): unresolved admissibility rules [${ruleIds.join(', ')}]. Fix or record a NV-BL-ADM-05 override before re-querying.`,
+      defineRules: defineEval.bitingRules,
+      refusal: `traceability/query tool refused (NV-BL-SR-03 addendum): unresolved admissibility rules [${combinedRuleIds.join(', ')}]. Fix or record a NV-BL-ADM-05 override; for NV-DL-ADM-03 an --ack reason on freeze.gates clears the gate; for NV-DL-ADM-02 fix the D4 findings or record freeze.override via \`rcf build bundle --next --override "<reason>"\`; for NV-DL-ADM-04 correct the chain document.`,
     };
   }
   const payload = await Promise.resolve(produce());
-  return { status: 'ok', admissibility: verdict, payload };
+  return {
+    status: 'ok',
+    admissibility: verdict,
+    defineRules: defineEval.bitingRules,
+    payload,
+  };
+}
+
+/**
+ * 0.30.0 PR 8 (REQ-179, TAC-4125; AC-17902-2 / AC-17902-3). Evaluate
+ * NV-DL-ADM-01 against the project's freeze record: an unfrozen tree
+ * without `freeze.override` set is a refusal; `freeze.override`
+ * present satisfies the recordedInChain channel so the caller may
+ * proceed and name the override.
+ *
+ * Pure of walker I/O: it reads the freeze record only. Callers wrap
+ * their own tool / verb refusal path around the returned verdict.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<{ verdict: 'ok' | 'refuse-nv-dl-adm-01', rule?: 'NV-DL-ADM-01', override?: {reason:string, by:string, at:string}|null, message?: string }>}
+ */
+export async function evaluateDefineAdmissibility({ projectRoot }) {
+  const freeze = await loadFreezeRecord({ projectRoot });
+  if (freeze && typeof freeze === 'object' && freeze.override) {
+    const o = freeze.override;
+    return { verdict: 'ok', override: { reason: o.reason, by: o.by, at: o.at } };
+  }
+  if (freeze && typeof freeze === 'object' && freeze.docHashes) {
+    return { verdict: 'ok', override: null };
+  }
+  return {
+    verdict: 'refuse-nv-dl-adm-01',
+    rule: 'NV-DL-ADM-01',
+    message:
+      'NV-DL-ADM-01: refused on an unfrozen tree. Close the change with `rcf define readiness` and `rcf define freeze`, '
+      + 'or record `freeze.override { reason, by, at }` via `rcf build bundle --next --override "<reason>"`.',
+  };
 }

package/src/ruleset/ruleset.json

@@ -53,6 +53,41 @@
       "refuseByDefault": true,
       "overrideChannel": "recordedInChain",
       "notes": "At build start, build-lite compares the ruleset version the chain declares it was authored against with the version the shipping lint enforces. Behaviour-changing drift refuses; additive-only drift warns. Ratified 2026-08-11 ruling-sheet item 7: define-stage drift is a warning-with-acknowledgement; build-stage drift is a refusal."
+    },
+    {
+      "id": "NV-DL-ADM-01",
+      "title": "rcf build bundle --next refuses without a freeze record",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-177, spec section 4 bundle row). The verb exits 4 and names rcf define readiness; --override \"<reason>\" writes freeze.override { reason, by, at } and proceeds. The override is the recordedInChain channel for this rule."
+    },
+    {
+      "id": "NV-DL-ADM-02",
+      "title": "D4 stories floor failing items are findings (closed sets, ownerRef)",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-179, spec section 4 NV-DL row). Surfaced through the admissibility wrap as a D4 finding. D4 is not ackable (decision 9 keeps `ackable` to D3/D5/D6); the only recordedInChain override channel is `freeze.override` written by `rcf build bundle --next --override \"<reason>\"`. The normal path is to fix the failing D4 findings. Ruling R12 (2026-10-03) corrects an earlier description that named --ack as the ADM-02 override."
+    },
+    {
+      "id": "NV-DL-ADM-03",
+      "title": "D3 shapes bite failing items are findings (template markers, entity join, paths)",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-179, spec section 4 NV-DL row). Surfaced through the admissibility wrap as a D3 finding; the override channel is the --ack reason on freeze.gates (D3 is ackable)."
+    },
+    {
+      "id": "NV-DL-ADM-04",
+      "title": "rcf define validate finding set refuses with exit 3",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-178, spec section 4 validate row). The four findings (interface kind outside the vocabulary, bracketed AC class prefix outside the known classes, tacIds naming a non-TAC, unresolving ownerRef or deliveredBy) exit 3; the override is a chain-document correction recorded in git history."
+    },
+    {
+      "id": "NV-DL-ADM-05",
+      "title": "rcf build bundle --next skips FBS impacted by a non-empty delta",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "0.30.0 PR 8 (REQ-177, spec section 4 bundle row). On a non-empty delta the next-item selection filters re-execute FBS impacted by the delta out of the actionable queue with a stderr reason; when every actionable FBS is impacted and no override is given the verb exits 4. --override \"<reason>\" writes freeze.override and lets the verb proceed."
     }
   ],
   "gateRules": [

package/src/view/html-page.js

@@ -59,7 +59,7 @@ import { renderEntitySelector } from './components/entity-selector.js';
 import { renderSubTabStrip } from './components/sub-tab-strip.js';
 import { buildDagLayout, buildDagInspectorPayload, renderBuildDag } from './build-dag.js';
 import { computeReqNeedsWorkIds, needsWorkReasonFor } from './needs-work.js';
-import { renderLookupModal, renderSearchButton } from './view-index.js';
+import { renderLookupModal, renderSearchButton, renderThemeControl } from './view-index.js';
 
 // Umbrella version stamped at module load (same pattern as src/ruleset/index.js).
 // Used by the shell footer so the muted "RCF Lite X.Y.Z" line tracks the
@@ -81,10 +81,21 @@ const LIVE_WRAPPER_CLOSE = '</div>';
  * Render the complete index.html string. Phase 3.8: always includes the
  * live-content wrapper and the live-client script tag.
  *
+ * `opts.embed = true` strips the three-state theme control from the
+ * emitted HTML entirely (ADR-4137 server-side layer). The production
+ * server path at `renderModelToPage` serves one page to every client,
+ * so it never passes `embed`; the client-side layer in `page-init.js`
+ * removes `[data-rcf-theme-control]` from the DOM when `?embed=1` is
+ * on the URL. The option is here so `renderPage({ embed: true })` is
+ * a one-call proof that the control markup can be absent (used by
+ * `test/view/theme-control.test.js` for AC-206-9).
+ *
  * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @param {{ embed?: boolean }} [opts]
  * @returns {string}
  */
-export function renderPage(model) {
+export function renderPage(model, opts) {
+  const embed = Boolean(opts && opts.embed);
   const header = resolveProductHeader(model);
   const projectName = header.projectName ?? 'RCF project';
   const contentHtml = renderContent(model);
@@ -124,6 +135,7 @@ export function renderPage(model) {
       </nav>
       <div class="tools" aria-label="Viewer tools">
         ${renderSearchButton()}
+        ${embed ? '' : renderThemeControl()}
       </div>
     </div>
   </header>