rcf-lite 0.29.0 → 0.31.0

package/rcf/user-stories/us-17702.json

@@ -0,0 +1,51 @@
+{
+  "usId": "US-17702",
+  "prdId": "PRD-001",
+  "reqId": "REQ-177",
+  "version": "0.1.1",
+  "status": "draft",
+  "title": "bundle refuses and skips",
+  "description": "User story under REQ-177 for DEFINE step 3 PR 8 (spec section 4 bundle row, section 11.7 US-17702). `rcf build bundle --next` refuses on an unfrozen tree (exit 4, message naming `rcf define readiness`); `--override \"<reason>\"` writes `freeze.override { reason, by, at }` and proceeds; on a non-empty delta the next-item compute skips re-execute FBS impacted by the delta with the reason and hands out the next unimpacted FBS; when every actionable FBS is impacted and no override is given the verb refuses with exit 4.",
+  "asA": "an operator closing a change",
+  "iWant": "`rcf build bundle --next` to refuse without a freeze record, to accept a recorded override, to skip FBS impacted by a non-empty delta and hand out the next unimpacted one, and to refuse when every actionable item is impacted and no override is given",
+  "soThat": "I cannot bundle a stale next item against an unfrozen tree, a hotfix path exists with a recorded reason, and the 0.29.0 output on a frozen tree with an empty delta is unchanged",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17702-1",
+      "description": "[failure] given no freeze record, when rcf build bundle --next runs, then it exits 4 naming rcf define readiness.",
+      "testable": true
+    },
+    {
+      "id": "AC-17702-2",
+      "description": "[happy] given --override \"hotfix\", when bundle --next runs on an unfrozen tree, then freeze.override records reason, by and at and the bundle is produced.",
+      "testable": true
+    },
+    {
+      "id": "AC-17702-3",
+      "description": "[happy] given a delta impacting FBS-018, when bundle --next runs, then FBS-018 is skipped with the reason and the next unimpacted FBS is handed out.",
+      "testable": true
+    },
+    {
+      "id": "AC-17702-4",
+      "description": "[failure] given every actionable FBS impacted and no override, when bundle --next runs, then it exits 4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17702-5",
+      "description": "[must-not] given a frozen tree with an empty delta, when bundle --next runs, then its output is unchanged from 0.29.0.",
+      "testable": true
+    },
+    {
+      "id": "AC-17702-6",
+      "description": "[happy] (PR 9, TAC-4125) given a project with `git config user.email` set, when bundle --next --override \"...\" runs, then freeze.override.by is the git identity; when it is absent, GITHUB_ACTOR wins; then USER; then USERNAME; then the literal `operator` as a never-null fallback.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4125-build-bundle-refuse-override-skip",
+    "TAC-4120-define-delta-and-freeze"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-03T18:30:00Z",
+  "updatedAt": "2026-10-03T20:30:00Z"
+}

package/rcf/user-stories/us-17802.json

@@ -0,0 +1,40 @@
+{
+  "usId": "US-17802",
+  "prdId": "PRD-001",
+  "reqId": "REQ-178",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "validate findings",
+  "description": "User story under REQ-178 for DEFINE step 3 PR 8 (spec section 4 validate row, section 11.7 US-17802). `rcf define validate` reports a finding and exits non-zero for an interface kind outside the closed vocabulary, a bracketed AC prefix outside the known classes, a `tacIds` naming a non-TAC and an unresolving `ownerRef` or `deliveredBy`. Absence of an AC class marker is NOT a validate finding (decision 10): the dogfood tree and every legacy tree would otherwise fail CI; D4 reports absence as the floor.",
+  "asA": "an author of chain documents",
+  "iWant": "validate to catch misuse of the four closed vocabularies (interface kind, AC class, tacIds, ownerRef / deliveredBy) at the one surface everyone runs today",
+  "soThat": "a typo or a wrong vocabulary value fails fast and is not left to the gates",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17802-1",
+      "description": "[failure] given an interface kind \"widget\", when validate runs, then it reports a finding and exits non-zero.",
+      "testable": true
+    },
+    {
+      "id": "AC-17802-2",
+      "description": "[failure] given an AC description starting \"[sometimes]\", when validate runs, then it reports a finding.",
+      "testable": true
+    },
+    {
+      "id": "AC-17802-3",
+      "description": "[happy] given the rcf-lite dogfood tree, when validate runs, then it is clean.",
+      "testable": true
+    },
+    {
+      "id": "AC-17802-4",
+      "description": "[must-not] given an AC with no bracketed prefix, when validate runs, then no finding is raised.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4126-define-validate-findings"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-03T18:30:00Z",
+  "updatedAt": "2026-10-03T18:30:00Z"
+}

package/rcf/user-stories/us-17902.json

@@ -0,0 +1,46 @@
+{
+  "usId": "US-17902",
+  "prdId": "PRD-001",
+  "reqId": "REQ-179",
+  "version": "0.1.1",
+  "status": "draft",
+  "title": "NV-DL enforced",
+  "description": "User story under REQ-179 for DEFINE step 3 PR 8 (spec section 4 NV-DL row, section 11.7 US-17902). The rcf-lite ruleset carries NV-DL-ADM-01..05 with `refuseByDefault: true` and `overrideChannel: recordedInChain`. ADM-01 is the bundle refusal on an unfrozen tree; ADM-05 is the bundle skip of impacted FBS; ADM-02..04 are D4 and D3 findings surfaced through the admissibility wrap. `freeze.override` (bundle --override) and an `--ack` reason (readiness / freeze) satisfy `recordedInChain`. readiness compute still runs and prints under refusal; 0.29.0 informational posture on the compute is unchanged (ADR-4123).",
+  "asA": "an operator of the DEFINE stage gates",
+  "iWant": "the five NV-DL rules to refuse by default with a recorded-in-chain override channel so a build verb cannot proceed on an unfrozen tree without a documented reason",
+  "soThat": "the ruleset's intent (ruling-sheet item 1) is enforced in code and the readiness compute still prints its diagnostics under a refusal",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17902-1",
+      "description": "[happy] given ruleset.json, when read, then NV-DL-ADM-01 to 05 carry refuseByDefault true and overrideChannel recordedInChain.",
+      "testable": true
+    },
+    {
+      "id": "AC-17902-2",
+      "description": "[failure] given an unfrozen tree, when a build verb runs under the admissibility gate, then it refuses citing NV-DL-ADM-01.",
+      "testable": true
+    },
+    {
+      "id": "AC-17902-3",
+      "description": "[happy] given freeze.override present, when the same verb runs, then it proceeds and names the override.",
+      "testable": true
+    },
+    {
+      "id": "AC-17902-4",
+      "description": "[must-not] given readiness, when the gate refuses, then the compute still runs and prints (0.29.0 informational posture unchanged).",
+      "testable": true
+    },
+    {
+      "id": "AC-17902-5",
+      "description": "[happy] (PR 9, REQ-179 enforcement locus) given a readiness result with D4 state `failing` and a non-empty validateErrors array, when `runWithAdmissibilityGate` composes its envelope, then NV-DL-ADM-02 and NV-DL-ADM-04 appear in `defineRules` and in the refusal line alongside the NV-BL rules; a stage acknowledged at the current tree hash (freeze.gates with hash match) is not cited.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4125-build-bundle-refuse-override-skip",
+    "TAC-4126-define-validate-findings"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-03T18:30:00Z",
+  "updatedAt": "2026-10-03T20:30:00Z"
+}

package/rcf/user-stories/us-205.json

@@ -49,6 +49,11 @@
       "id": "AC-205-8",
       "description": "[must-not] Given the LookupModal, when the user types a query, picks a result or closes the modal, then no `postMessage` is sent to the parent window, no outbound network request beyond the `./index.json` fetch is made, and no search term is written to `localStorage` / `sessionStorage` / cookies.",
       "testable": true
+    },
+    {
+      "id": "AC-205-9",
+      "description": "[happy] Given the SearchButton (`.rcf-search-btn`) in the shell's `.tools` group, when it is rendered in either theme and in each of its states (default, `:hover`, `:focus-visible`, `:active`), then the computed foreground / background contrast ratio for the button text, the icon stroke against the background and the focus-ring colour against the adjacent surface meets WCAG 2.1 AA (>= 4.5:1 for the text, >= 3:1 for the icon and the focus-ring boundary) in both the light (`:root`) and dark (`:root[data-theme=\"dark\"]`) token sets.",
+      "testable": true
     }
   ],
   "tacIds": [
@@ -60,5 +65,5 @@
     "navigation"
   ],
   "createdAt": "2026-10-02T19:00:00Z",
-  "updatedAt": "2026-10-02T19:00:00Z"
+  "updatedAt": "2026-10-04T14:00:00Z"
 }

package/rcf/user-stories/us-206.json

@@ -5,10 +5,10 @@
   "version": "0.1.0",
   "status": "draft",
   "title": "wespa's embedding contract is proved by a CI host fixture",
-  "description": "A same-origin test-host fixture served by the viewer's dev server (route `/test-host.html` behind a `--test-host` flag or an env guard; off by default so wespa's proxy allow-list is unaffected) mimics the wespa shell: a 56px header, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying an `<iframe src=\"./?embed=1&theme=light\">`. The host posts `{ type: \"rcf-view-theme\", theme: \"light\"|\"dark\" }` on a toggle control; it stores no theme itself so a passing run proves the iframe reads the message. The viewer sends no outbound postMessage. Three lints run in the test suite: (1) framing lint (`GET /` returns no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin, and the fixture loads the iframe without a browser error); (2) target lint (no `target=\"_top\"` string in the server-rendered HTML); (3) localStorage namespace lint (every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site in `src/view/**` uses a key starting with `rcf-view:v1:`). See viewer UI refresh design doc section 9 and Dex's wespa requirements of 2026-10-02.",
+  "description": "A same-origin test-host fixture served by the viewer's dev server (route `/test-host.html` behind a `--test-host` flag or an env guard; off by default so wespa's proxy allow-list is unaffected) mimics the wespa shell: a 56px header, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying an `<iframe src=\"./?embed=1&theme=light\">`. The host posts `{ type: \"rcf-view-theme\", theme: \"light\"|\"dark\" }` on a toggle control; it stores no theme itself so a passing run proves the iframe reads the message. The viewer sends no outbound postMessage. Three lints run in the test suite: (1) framing lint (`GET /` returns no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin, and the fixture loads the iframe without a browser error); (2) target lint (no `target=\"_top\"` string in the server-rendered HTML); (3) localStorage namespace lint (every `localStorage.{setItem,getItem,removeItem}` and shared `storage.*` call site in `src/view/**` uses a key starting with `rcf-view:v1:`). Amended 2026-10-04 (w-2026-10-04-dave-001): the viewer's own three-state theme control (Light|Dark|Auto) sits right of the SearchButton in non-embed mode, is hidden entirely under `embed=1` and in non-embed mode persists its setting under `rcf-view:v1:theme` per ADR-4137 (Dave's storage ruling 2026-10-04). See viewer UI refresh design doc section 9 and section 11 recommendation 6, and Dex's wespa requirements of 2026-10-02.",
   "asA": "Dex integrating the rcf-lite viewer behind wespa's reverse proxy",
-  "iWant": "a CI host fixture that proves the viewer honours the embedding contract and three lints that keep framing, target='_top' and localStorage namespace in place over time",
-  "soThat": "regressions in the embedding contract are caught in the viewer's own suite before they reach wespa",
+  "iWant": "a CI host fixture that proves the viewer honours the embedding contract and three lints that keep framing, target='_top' and localStorage namespace in place over time; and a visible three-state theme control in the standalone viewer that is hidden under embed=1",
+  "soThat": "regressions in the embedding contract are caught in the viewer's own suite before they reach wespa, and standalone viewer users can switch theme without a URL edit",
   "acceptanceCriteria": [
     {
       "id": "AC-206-1",
@@ -39,6 +39,26 @@
       "id": "AC-206-6",
       "description": "[must-not] Given the test-host fixture and the viewer page, when either is loaded, then neither posts any outbound message beyond the host's `rcf-view-theme`; the viewer sends no `postMessage` of any shape, and the test-host adds no new postMessage shape.",
       "testable": true
+    },
+    {
+      "id": "AC-206-7",
+      "description": "[happy] Given the standalone viewer loaded without `embed=1`, when the shell paints, then a three-state theme control (`role=\"group\"`, three buttons Light|Dark|Auto with `aria-pressed`) renders in the header's `.tools` group right of the SearchButton; when a button is pressed, `<html data-theme>` is set to `light` or `dark` (or the attribute is removed for Auto so the `prefers-color-scheme` media query decides) live without a reload, and the pressed button's `aria-pressed` becomes `true` while the others become `false`.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-8",
+      "description": "[happy] Given the standalone (non-embed) viewer, when a theme button is pressed, then the chosen value (`light`, `dark` or `auto`) is written to `localStorage['rcf-view:v1:theme']`; on the next page load the stored value is reapplied; the boot precedence is `?theme=` wins first, then the stored value, then the default (`auto`); and the postMessage `rcf-view-theme` listener still applies live but writes nothing to the stored key.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-9",
+      "description": "[must-not] Given the viewer loaded with `?embed=1`, when the shell paints, then the three-state theme control is absent from the DOM entirely (no `[data-rcf-theme-control]` element rendered, not merely hidden by CSS), and no read or write of `localStorage['rcf-view:v1:theme']` happens on load, on a postMessage theme change, or on any user action inside the viewer.",
+      "testable": true
+    },
+    {
+      "id": "AC-206-10",
+      "description": "[happy] Given the standalone viewer with a stored value `rcf-view:v1:theme = dark`, when the URL carries `?theme=light`, then on load `<html data-theme>` is `light` (the explicit query wins) and the Light button is pressed; the stored value is left as `dark` and is reused on the next load without a `?theme=` query.",
+      "testable": true
     }
   ],
   "tacIds": [
@@ -47,8 +67,9 @@
   "tags": [
     "view",
     "embedding",
+    "theme",
     "lint"
   ],
   "createdAt": "2026-10-02T20:00:00Z",
-  "updatedAt": "2026-10-02T20:00:00Z"
+  "updatedAt": "2026-10-04T14:00:00Z"
 }

package/rcf/user-stories/us-207.json

@@ -0,0 +1,36 @@
+{
+  "usId": "US-207",
+  "prdId": "PRD-001",
+  "reqId": "REQ-002",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Every viewer text and control colour pair meets WCAG 2.1 AA in both themes",
+  "description": "A static CSS-contrast audit test parses `packages/rcf-lite/src/view/style.css`, resolves the `--sv-*` custom properties for the light (`:root`) and dark (`:root[data-theme=\"dark\"]`) token blocks, and enumerates every rule that sets `color` together with a reachable `background` / `background-color` (own rule, then the nearest ancestor surface token, default `--sv-canvas` page background). Each pair is enumerated in both themes and across every reachable state variant: default, `:hover`, `:focus`, `:focus-visible`, `:active`, `[aria-pressed=\"true\"]`, `[aria-selected=\"true\"]`, `.is-active`, `:disabled`. For each pair the WCAG relative-luminance contrast ratio is computed and asserted against the WCAG 2.1 AA thresholds (>= 4.5:1 for normal text, >= 3:1 for large text and non-text UI boundaries per WCAG 1.4.3 and 1.4.11). Pairs that cannot be resolved statically (gradients, rgba over an unknown background) are computed against the two most likely surfaces (`--sv-canvas` and the ancestor surface token) and recorded as approximate rather than skipped. The test emits a BEFORE/AFTER table under `./output/contrast-report.md` and refuses the suite on any failing pair. Scope covers the whole viewer shell, every tab, components, SearchButton and LookupModal, Readiness, Requirements, Architecture, Build (Specs and DAG), ID lookup; Mermaid and Product Map themed palettes are audited on a best-effort basis and anything bound to a third-party default is listed as a known gap with its ratio. See viewer UI refresh design doc section 9 (theme) and Baz's 2026-10-04 review (`w-2026-10-04-dave-001`).",
+  "asA": "an engineer or reviewer looking at the review surface in either theme",
+  "iWant": "every text and control colour pair in the viewer to meet WCAG 2.1 AA in both themes, pinned by a test that fails the suite when a new rule breaks the floor",
+  "soThat": "the review surface stays readable in both themes and nobody has to re-do the audit by hand on every CSS change",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-207-1",
+      "description": "[happy] Given the viewer stylesheet `src/view/style.css` and the two token blocks (`:root` and `:root[data-theme=\"dark\"]`), when the contrast test runs, then it enumerates every CSS rule that sets `color` (and every state rule merged over its base selector, so a state that changes only the background is paired with the inherited colour) paired with every reachable background (own rule, nearest ancestor surface token, page background `--sv-canvas`) and every state variant (default, `:hover`, `:focus`, `:focus-visible`, `:active`, `[aria-pressed=\"true\"]`, `[aria-selected=\"true\"]`, `.is-active`, `:disabled`), computes the WCAG relative-luminance contrast ratio for each, and asserts >= 4.5:1 for text, >= 3:1 for large text (>= 18.66px bold or >= 24px) and for non-text UI boundaries (control borders and outlines, focus rings against the adjacent colour, each enumerated as its own pair) per WCAG 1.4.3 and 1.4.11 in both the light and dark token sets.",
+      "testable": true
+    },
+    {
+      "id": "AC-207-2",
+      "description": "[failure] Given a contrast pair that falls below the applicable threshold, when the test runs, then the failure message names the selector, state, theme, foreground colour, background colour, computed ratio and the threshold applied, and the test exits non-zero so the suite blocks a merge that drops a pair below AA.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4134-wespa-host-fixture"
+  ],
+  "tags": [
+    "view",
+    "contrast",
+    "accessibility",
+    "a11y",
+    "theme"
+  ],
+  "createdAt": "2026-10-04T14:00:00Z",
+  "updatedAt": "2026-10-05T12:30:00Z"
+}

package/releases/releases.yaml

@@ -40,8 +40,28 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.29.0"
+latest: "0.31.0"
 releases:
+  - version: "0.31.0"
+    date: "2026-10-05"
+    breaking: true
+    headlines:
+      - "rcf-lite 0.31.0 gives the viewer a Light, Dark and Auto theme control in standalone mode and brings its text and control colours up to WCAG AA contrast in both themes, with a test that blocks any regression. Under embed=1 the control is absent, nothing is stored and the rcf-view-theme message contract is unchanged."
+      - "DEFINE step 3 rulings R1 to R13 land: tree-wide readiness checks now run before any scope short-circuit, so a narrowed scope still reports a draft marker, an unjoined core entity, an uncited standards pack, a missing Deploy ADR or an empty security or operational section anywhere in the tree. A stage whose scope is empty but whose tree-wide check fails now reads failing rather than not applicable, and the draft-settled check is tree-wide."
+      - "Write-backs that carry an id are idempotent: rcf define create <kind> --id and rcf define ledger <name> add --id exit 0 and write nothing when the same id is replayed with the same content, and exit 3 naming the differing fields when the content differs."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.30.0"
+    date: "2026-10-03"
+    breaking: true
+    headlines:
+      - "rcf-lite 0.30.0 lands the DEFINE step 3 gates bite in one release. Readiness --check now exits 4 on a failing D3, D5 or D6 at the current tree hash and clears with --ack <gate>=<reason> on freeze.gates (D3/D5/D6 only; decision 9). rcf build bundle --next now refuses on an unfrozen tree with exit 4 and clears with --override \"<reason>\" writing freeze.override { reason, by, at }; freeze.override.by is resolved by the preference order git user.email -> GITHUB_ACTOR -> USER -> USERNAME -> operator. Impacted re-execute FBS are skipped with the reason on stderr; when every actionable FBS is impacted and no override is given the verb also exits 4."
+      - "rcf define validate now exits 3 on four new finding kinds: an interface kind outside the closed vocabulary, a bracketed AC class prefix outside the five known classes, a tacIds naming a non-TAC, and an unresolving ownerRef or object-form deliveredBy. R11 widens the ownerRef and object-form deliveredBy field grammar to every bracket path on the owning TAC or ADR (interfaces[<name>], responsibilities[<n>], dependencies[<name>], alternativesConsidered[<n>]) plus a bare schema field name; dotted grammar is refused and the finding names the dotted field. The pre-PR 9 validate silently skipped the object form of deliveredBy; it is now checked. Absence of an AC class marker is not a finding (D4 reports absence as the floor)."
+      - "NV-DL-ADM-01 through 05 flip to refuseByDefault with overrideChannel: recordedInChain. Per-rule enforcement locus and override channel: ADM-01 bundle refuses without a freeze (override: --override); ADM-02 D4 stories floor findings (override: freeze.override only; D4 is not ackable per decision 9; ruling R12 2026-10-03); ADM-03 D3 shapes bite findings (override: --ack on freeze.gates); ADM-04 validate finding set (override: a chain-document correction committed to git); ADM-05 bundle all-impacted refusal (override: --override). The admissibility wrap surfaces ADM-02, ADM-03 and ADM-04 alongside the NV-BL rules on readiness and freeze, which stay informational on the compute. The blueprint shelf is clean under R11 after the sweep (31 dotted-to-bracket rewrites, 493 dead-bracket collapses, 12 ownerRef / deliveredBy drops); the sweep script is re-runnable in dry-run mode on a consumer's own tree."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.29.0"
     date: "2026-10-03"
     breaking: true

package/src/blueprint/consistency-lint.js

@@ -319,9 +319,16 @@ export function runPass2(input) {
         continue;
       }
       const carried = collectTacSurfaceText(target).toLowerCase();
-      const field = typeof delivery.field === 'string' ? delivery.field.toLowerCase() : '';
-      const fieldTail = field ? field.split('.').pop() : '';
-      if (fieldTail && !carried.includes(fieldTail)) {
+      const field = typeof delivery.field === 'string' ? delivery.field : '';
+      const fieldTail = extractDeliveryFieldTail(field);
+      // R11 (spec section 17, PR 9): a bare schema field name
+      // (`responsibilities`, `interfaces`, `purpose`, `decision`,
+      // etc.) resolves on the owner by presence; the lint treats
+      // these as covered by the surface text when the owner carries
+      // a non-empty value under that key. Bracket forms
+      // (`interfaces[<name>]`, `responsibilities[<n>]`) are parsed
+      // to their inner key for the carried-text match.
+      if (fieldTail && !carried.includes(fieldTail.toLowerCase())) {
         findings.push({
           id: `pass2-delivery-field-missing-${rid}-${delivery.tacId}`, pass: 'pass2', kind: 'reqDeliveryNotCarried',
           subject: rid, refs: [rid, delivery.tacId, fieldTail],
@@ -347,6 +354,68 @@ function collectTacSurfaceText(tac) {
   return parts.join(' ');
 }
 
+/**
+ * R11 (spec section 17, PR 9): parse `deliveredBy.field` into the
+ * tail the carried-text match should see.
+ *
+ *   - `interfaces[loan]`           -> `loan`           (bracket inner)
+ *   - `responsibilities[verify]`   -> `verify`         (bracket inner)
+ *   - `responsibilities[0]`        -> ``               (bare integer index
+ *                                                       resolves on the array;
+ *                                                       nothing to match)
+ *   - bare `responsibilities`,
+ *     `interfaces`, `purpose`,
+ *     `decision`, `internalStructure`, ...  -> ``       (bare schema field;
+ *                                                       covered by the
+ *                                                       owner's presence
+ *                                                       alone -- the
+ *                                                       pre-PR 9 `.pop()`
+ *                                                       on a dotted form
+ *                                                       is preserved for
+ *                                                       legacy dotted
+ *                                                       pointers that have
+ *                                                       not yet been
+ *                                                       swept)
+ *   - legacy dotted `interfaces.loan`
+ *     or `decision.retryBackoff`   -> `loan` / `retryBackoff`
+ *
+ * The returned tail is empty when nothing meaningful remains to
+ * match; callers skip the carried-text check in that case.
+ *
+ * @param {string} field
+ * @returns {string}
+ */
+function extractDeliveryFieldTail(field) {
+  if (typeof field !== 'string' || field.length === 0) return '';
+  // Bracket form: `<root>[<inner>]`.
+  const bracket = field.match(/^[A-Za-z0-9_]+\[([^\]]+)\]$/);
+  if (bracket) {
+    const inner = bracket[1];
+    // A bare integer index on responsibilities / alternativesConsidered
+    // resolves by position; there is nothing semantic to match on the
+    // surface text, so skip the check (the resolver has already
+    // confirmed the index exists).
+    if (/^\d+$/.test(inner)) return '';
+    return inner;
+  }
+  // Legacy dotted form (`interfaces.loan`, `decision.retryBackoff`,
+  // `responsibilities.verify`): the tail is the last dotted segment.
+  if (field.includes('.')) return field.split('.').pop();
+  // Bare schema field name: resolves on the owner by presence; no
+  // tail to match.
+  const KNOWN_BARE_FIELDS = new Set([
+    'purpose', 'internalStructure', 'tradeoffs', 'notes', 'name',
+    'responsibilities', 'interfaces', 'dependencies',
+    'decision', 'context', 'consequences', 'title',
+    'alternativesConsidered', 'description',
+  ]);
+  if (KNOWN_BARE_FIELDS.has(field)) return '';
+  // Anything else: fall through to the pre-PR 9 behaviour and match
+  // the whole thing against the carried text. This covers composite
+  // free-form tokens the sweep may not have reached.
+  return field;
+}
+
 /**
  * Load a blueprint from disk into the shape the passes consume.
  *

package/src/cli/build.js

@@ -18,6 +18,10 @@
 
 import { writeFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 import { formatErrors, isRcfError, rcfError, writeUnexpectedFailure } from '#core/errors';
 import { updateDocument, walkTree } from '#core/store';
@@ -41,6 +45,14 @@ import { firstBaselineDisagreement } from '../design/index.js';
 import { writeBrowserVerificationAck } from '../browser-verify/index.js';
 // Track C+D §5.4 Stage-1 refusal gate.
 import { fbsRefusalForOpenSweep } from '../req-baseline/gate.js';
+// 0.30.0 PR 8 (REQ-177 / TAC-4125): bundle --next freeze gate.
+import { computeDelta } from '../query/delta.js';
+import { computeImpact } from '../query/impact.js';
+import { loadAllLedgers } from '../define/ledgers.js';
+import {
+  applyOverrideToFreezeRecord,
+  loadFreezeRecord,
+} from '../define/freeze-record.js';
 
 const OPTION_SPEC = {
   next: { type: 'boolean' },
@@ -60,6 +72,12 @@ const OPTION_SPEC = {
   // browserVerification record.
   'accept-block': { type: 'boolean' },
   reason: { type: 'string' },
+  // 0.30.0 PR 8 (REQ-177, AC-17702-2 / AC-17702-4). Bundle --next with
+  // --override "<reason>" writes freeze.override { reason, by, at } and
+  // proceeds; without --override the verb refuses on an unfrozen tree
+  // (AC-17702-1) and when every actionable FBS is impacted by the
+  // delta (AC-17702-4).
+  override: { type: 'string' },
 };
 
 export const HELP = `Usage: rcf build <verb> [options]
@@ -96,6 +114,11 @@ Options (bundle):
   --strict                  Refuse (exit 4) a bundle for a blocked item;
                             no effect with --next (it never selects
                             blocked items)
+  --override "<reason>"     With --next: proceed on an unfrozen tree or
+                            an all-impacted delta, recording
+                            freeze.override { reason, by, at } (REQ-177,
+                            0.30.0 PR 8). The reason must be a
+                            non-empty string.
 
 Options (queue):
   --format <format>         md (default) | json
@@ -292,7 +315,10 @@ export async function main(argv, deps = {}) {
     return 0;
   }
   if (mode === 'next') {
-    return await emitNext({ tree, format, io });
+    return await emitNext({
+      tree, projectRoot, format, io,
+      overrideReason: typeof flags.override === 'string' ? flags.override : null,
+    });
   }
   return await emitBundle({
     tree, fbsId: positional, format, strict: Boolean(flags.strict), io,
@@ -356,9 +382,186 @@ async function emitBundle({ tree, fbsId, format, strict, io }) {
   return await emitToSink(output, io);
 }
 
-async function emitNext({ tree, format, io }) {
+/**
+ * 0.30.0 PR 9 (TAC-4125; AC-17702-6): resolve the author identity for
+ * `freeze.override.by`. Preference order (first non-empty wins):
+ *
+ *   1. `git config user.email` under `projectRoot` (the identity git
+ *      itself would attribute an override commit to; CI usually sets
+ *      this through its own git config step).
+ *   2. `GITHUB_ACTOR` (set by GitHub Actions on every run so a CI
+ *      override is attributed to the actor who triggered the workflow,
+ *      even when no git identity is configured).
+ *   3. `USER` or `USERNAME` (local shell identity on Unix / Windows).
+ *   4. The literal string `operator` (never-null fallback so the write
+ *      path cannot blow up on a stripped-down container).
+ *
+ * Pure of side effects beyond the one `git config` read; the git call
+ * is bounded to a short argv and never writes. Errors from `git
+ * config` (no `.git`, no git binary, missing key) fall through to the
+ * next arm silently; the resolution's shape is a single string.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @returns {Promise<string>}
+ */
+export async function resolveOverrideBy({ projectRoot }) {
+  // 1. git config user.email (bounded; refuses to log on failure).
+  try {
+    const { stdout } = await execFileAsync(
+      'git', ['config', '--get', 'user.email'],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 2000 },
+    );
+    const email = stdout.trim();
+    if (email.length > 0) return email;
+  } catch {
+    // Fall through to the environment arms.
+  }
+  // Env arms are trimmed so a whitespace-only value does not win
+  // over the next arm (codex review 2026-10-03, P2).
+  const envArm = (key) => {
+    const v = process.env[key];
+    if (typeof v !== 'string') return null;
+    const t = v.trim();
+    return t.length > 0 ? t : null;
+  };
+  // 2. GITHUB_ACTOR (GitHub Actions).
+  const actor = envArm('GITHUB_ACTOR');
+  if (actor) return actor;
+  // 3. USER or USERNAME.
+  const user = envArm('USER');
+  if (user) return user;
+  const username = envArm('USERNAME');
+  if (username) return username;
+  // 4. Never-null fallback.
+  return 'operator';
+}
+
+/**
+ * 0.30.0 PR 8 (REQ-177, TAC-4125): freeze gate for `bundle --next`.
+ * Loads the freeze record and the computed delta, writes
+ * freeze.override when --override "<reason>" is given, computes the
+ * set of re-execute FBS impacted by the delta, and returns a refusal
+ * when the tree is unfrozen and no override is given.
+ *
+ * Pure of CLI I/O: it writes freeze.override through the freeze-record
+ * module (which is the normal write path) but prints no output; the
+ * caller surfaces the refusal and the override line.
+ *
+ * @param {object} args
+ * @param {object} args.tree - walker tree.
+ * @param {string} args.projectRoot
+ * @param {string|null} args.overrideReason - the --override flag value, or null when absent.
+ * @returns {Promise<{ ok: true, impactedFbsIds: Set<string>, override: {reason:string, by:string, at:string}|null } | { ok: false, exitCode: 2|4, message: string }>}
+ */
+async function enforceBundleNextFreezeGate({ tree, projectRoot, overrideReason }) {
+  if (overrideReason !== null && (typeof overrideReason !== 'string' || overrideReason.length === 0)) {
+    return {
+      ok: false,
+      exitCode: 2,
+      message: 'build bundle --next: --override requires a non-empty reason (e.g. --override "hotfix")',
+    };
+  }
+  const [freeze, ledgers] = await Promise.all([
+    loadFreezeRecord({ projectRoot }),
+    loadAllLedgers({ projectRoot }),
+  ]);
+  const delta = computeDelta(tree, freeze, ledgers);
+  if (!delta.frozen && overrideReason === null) {
+    return {
+      ok: false,
+      exitCode: 4,
+      message:
+        'build bundle --next: refused on an unfrozen tree. Run `rcf define readiness` and close the change with `rcf define freeze`, '
+        + 'or re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-01).',
+    };
+  }
+  let appliedOverride = null;
+  if (overrideReason !== null) {
+    const at = new Date().toISOString();
+    const by = await resolveOverrideBy({ projectRoot });
+    const { record } = await applyOverrideToFreezeRecord({
+      projectRoot,
+      reason: overrideReason,
+      by,
+      at,
+      docHashes: delta.currentDocHashes ?? {},
+      treeHash: delta.currentTreeHash,
+      briefStatements: ledgers?.brief?.statements?.length ?? 0,
+    });
+    appliedOverride = record.override;
+  }
+  // Compute impacted FBS set when the tree is frozen (unfrozen trees
+  // have no base to compare against; AC-17702-5 governs that path).
+  // "Impacted" means an FBS that must be re-executed because its own
+  // definition changed OR because it fans out from a changed/added
+  // pivot (REQ, US, AC, TAC, ADR) via expandFbsDependents.
+  const impactedFbsIds = new Set();
+  if (delta.frozen) {
+    const pivotIds = [
+      ...delta.changed.filter((id) => !id.startsWith('ledger:')),
+      ...delta.added.filter((id) => !id.startsWith('ledger:')),
+    ];
+    // A changed/added FBS is itself impacted.
+    for (const id of pivotIds) {
+      if (typeof id === 'string' && id.startsWith('FBS-')) impactedFbsIds.add(id);
+    }
+    const seen = new Set();
+    for (const id of pivotIds) {
+      const impact = computeImpact(tree, { id });
+      if (!impact.found || !Array.isArray(impact.nodes)) continue;
+      for (const node of impact.nodes) {
+        if (seen.has(node.id)) continue;
+        seen.add(node.id);
+        if (node.kind === 'fbs' && node.role !== 'pivot' && node.actionNeeded === 're-execute') {
+          impactedFbsIds.add(node.id);
+        }
+      }
+    }
+  }
+  return { ok: true, impactedFbsIds, override: appliedOverride };
+}
+
+async function emitNext({ tree, projectRoot, format, io, overrideReason = null }) {
+  // 0.30.0 PR 8 (REQ-177 / TAC-4125): refuse without a freeze record,
+  // write freeze.override on --override "<reason>" and proceed, skip
+  // impacted FBS from the next-item selection.
+  const gate = await enforceBundleNextFreezeGate({
+    tree, projectRoot, overrideReason,
+  });
+  if (!gate.ok) {
+    io.stderr.write(`[error] ${gate.message}\n`);
+    return gate.exitCode;
+  }
+  if (gate.override) {
+    const o = gate.override;
+    io.stderr.write(`[info] build bundle --next: freeze.override recorded (reason=${JSON.stringify(o.reason)}, by=${o.by}, at=${o.at}).\n`);
+  }
+  // Skip FBS impacted by a non-empty delta; the next-item compute
+  // walks the queue from the top and the first unimpacted actionable
+  // FBS wins. Every skipped FBS is named on stderr with the reason.
   const queue = computeQueue(tree);
-  const next = selectNext(queue);
+  let next = null;
+  if (gate.impactedFbsIds.size === 0) {
+    next = selectNext(queue);
+  } else {
+    for (const item of queue.items) {
+      if (item.state !== 'actionable') continue;
+      if (gate.impactedFbsIds.has(item.fbsId)) {
+        io.stderr.write(`[info] build bundle --next: skipping ${item.fbsId} (impacted by the delta; re-freeze or re-execute first).\n`);
+        continue;
+      }
+      next = { fbsId: item.fbsId };
+      break;
+    }
+  }
+  if (!next && gate.impactedFbsIds.size > 0 && overrideReason === null) {
+    io.stderr.write(
+      '[error] build bundle --next: refused because every actionable FBS is impacted by the delta. '
+      + 'Re-run with --override "<reason>" to record `freeze.override { reason, by, at }` and proceed (NV-DL-ADM-05).\n',
+    );
+    return 4;
+  }
   if (next) {
     // Track C+D §5.4: Stage-1 (Define) refuses to enter Build for any
     // FBS binding an AC on a US that still has open baseline sweep