rcf-lite 0.29.0 → 0.31.0

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-008.json

@@ -17,6 +17,6 @@
   "updatedAt": "2026-08-30T00:00:00Z",
   "deliveredBy": {
     "tacId": "TAC-901-security-secrets-management-manager-client",
-    "field": "responsibilities.boot"
+    "field": "responsibilities"
   }
 }

package/blueprints/security-secrets-management/contributions/requirements/security-secrets-management-req-009.json

@@ -17,6 +17,6 @@
   "updatedAt": "2026-08-30T00:00:00Z",
   "deliveredBy": {
     "tacId": "TAC-904-security-secrets-management-rotation-gate",
-    "field": "responsibilities.rotationDays"
+    "field": "responsibilities"
   }
 }

package/blueprints/security-secrets-management/contributions/tacs/tac-901-security-secrets-management-manager-client.json

@@ -19,23 +19,23 @@
   "interfaces": [
     {
       "name": "vendorAdapter",
-      "kind": "read-write-api",
-      "description": "Project-supplied vendor binding implementing `readMany({ paths, credentials, environment })` returning `{ [name]: { value, lastRotatedAt } }` or an entry-level not-found marker, and `materialiseCredentials({ slicePaths, environment })` returning per-slice credentials the vendor deny-by-default enforces."
+      "kind": "other",
+      "description": "Project-supplied vendor binding implementing `readMany({ paths, credentials, environment })` returning `{ [name]: { value, lastRotatedAt } }` or an entry-level not-found marker, and `materialiseCredentials({ slicePaths, environment })` returning per-slice credentials the vendor deny-by-default enforces. (legacy kind: read-write-api)"
     },
     {
       "name": "manifest",
-      "kind": "read-api",
-      "description": "The manifest loader (TAC-902) resolving the current deployable's slice, per-environment paths, and `required` flags."
+      "kind": "other",
+      "description": "The manifest loader (TAC-902) resolving the current deployable's slice, per-environment paths, and `required` flags. (legacy kind: read-api)"
     },
     {
       "name": "auditSink",
-      "kind": "callback",
-      "description": "Structured-event sink invoked with `{ name, path, environment, principal, outcome, at }` on every fetch attempt; never invoked with the secret value."
+      "kind": "other",
+      "description": "Structured-event sink invoked with `{ name, path, environment, principal, outcome, at }` on every fetch attempt; never invoked with the secret value. (legacy kind: callback)"
     },
     {
       "name": "envSelector",
-      "kind": "read-api",
-      "description": "The boot-input resolver for the active environment: a process variable, a boot flag, or a project-authored selector. Returns exactly one environment string or refuses ambiguity."
+      "kind": "other",
+      "description": "The boot-input resolver for the active environment: a process variable, a boot flag, or a project-authored selector. Returns exactly one environment string or refuses ambiguity. (legacy kind: read-api)"
     }
   ],
   "dependencies": [

package/blueprints/security-secrets-management/contributions/tacs/tac-902-security-secrets-management-manifest.json

@@ -18,13 +18,13 @@
   "interfaces": [
     {
       "name": "fileSystem",
-      "kind": "read-api",
-      "description": "Project-supplied file reader accepting a repo-root-relative path and returning UTF-8 bytes; injected for test surface."
+      "kind": "other",
+      "description": "Project-supplied file reader accepting a repo-root-relative path and returning UTF-8 bytes; injected for test surface. (legacy kind: read-api)"
     },
     {
       "name": "yamlParser",
-      "kind": "read-api",
-      "description": "YAML parser accepting bytes and returning a plain object; injected so the project supplies its own dependency."
+      "kind": "other",
+      "description": "YAML parser accepting bytes and returning a plain object; injected so the project supplies its own dependency. (legacy kind: read-api)"
     }
   ],
   "dependencies": [],

package/blueprints/security-secrets-management/contributions/tacs/tac-903-security-secrets-management-env-reflector.json

@@ -17,13 +17,13 @@
   "interfaces": [
     {
       "name": "fileSystem",
-      "kind": "read-write-api",
-      "description": "Project-supplied file reader-writer supporting temp-file creation and atomic rename."
+      "kind": "other",
+      "description": "Project-supplied file reader-writer supporting temp-file creation and atomic rename. (legacy kind: read-write-api)"
     },
     {
       "name": "gitignoreCheck",
-      "kind": "read-api",
-      "description": "Project-supplied predicate answering whether a given path is gitignored (usually a shell-out to `git check-ignore`)."
+      "kind": "other",
+      "description": "Project-supplied predicate answering whether a given path is gitignored (usually a shell-out to `git check-ignore`). (legacy kind: read-api)"
     }
   ],
   "dependencies": [

package/blueprints/security-secrets-management/contributions/tacs/tac-904-security-secrets-management-rotation-gate.json

@@ -18,23 +18,23 @@
   "interfaces": [
     {
       "name": "vendorAdapter",
-      "kind": "read-api",
-      "description": "The same vendor binding the Secrets Manager client uses (TAC-901), scoped to a rotation-metadata read (no value fetch is required for the gate's own operation)."
+      "kind": "other",
+      "description": "The same vendor binding the Secrets Manager client uses (TAC-901), scoped to a rotation-metadata read (no value fetch is required for the gate's own operation). (legacy kind: read-api)"
     },
     {
       "name": "overrideStore",
-      "kind": "read-api",
-      "description": "Reads the operator-authored override file (project-authored path; a JSON or YAML file listing per-name `{ author, expiresAt, reason }` entries)."
+      "kind": "other",
+      "description": "Reads the operator-authored override file (project-authored path; a JSON or YAML file listing per-name `{ author, expiresAt, reason }` entries). (legacy kind: read-api)"
     },
     {
       "name": "clock",
-      "kind": "clock",
-      "description": "Injectable millisecond wall clock for the elapsed-days arithmetic."
+      "kind": "other",
+      "description": "Injectable millisecond wall clock for the elapsed-days arithmetic. (legacy kind: clock)"
     },
     {
       "name": "auditSink",
-      "kind": "callback",
-      "description": "The same sink shape TAC-901 uses; the gate emits override-applied and rotation-expired events through it."
+      "kind": "other",
+      "description": "The same sink shape TAC-901 uses; the gate emits override-applied and rotation-expired events through it. (legacy kind: callback)"
     }
   ],
   "dependencies": [

package/blueprints/security-secrets-management/contributions/tacs/tac-905-security-secrets-management-agent-cli.json

@@ -18,13 +18,13 @@
   "interfaces": [
     {
       "name": "process",
-      "kind": "read-api",
-      "description": "The host process's argv, stdin, stdout, stderr, and env; the CLI reads argv and stdin, writes to stdout and stderr, and reads a small allow-listed env slice (audit principal id, active environment)."
+      "kind": "other",
+      "description": "The host process's argv, stdin, stdout, stderr, and env; the CLI reads argv and stdin, writes to stdout and stderr, and reads a small allow-listed env slice (audit principal id, active environment). (legacy kind: read-api)"
     },
     {
       "name": "logSink",
-      "kind": "callback",
-      "description": "The CLI's own log destination (stderr by default; a file when `--log-file` is set); every write passes through the redactor."
+      "kind": "other",
+      "description": "The CLI's own log destination (stderr by default; a file when `--log-file` is set); every write passes through the redactor. (legacy kind: callback)"
     }
   ],
   "dependencies": [

package/fixtures/canary-manifest.json

@@ -1,9 +1,9 @@
 {
   "registerCanary": [
     {
-      "id": "rc-2026-10-03-001",
-      "createdAt": "2026-10-03T12:16:10.630Z",
-      "buildVersion": "0.29.0-mockdriver",
+      "id": "rc-2026-10-05-001",
+      "createdAt": "2026-10-05T15:28:27.972Z",
+      "buildVersion": "0.31.0-mockdriver",
       "fixturePromptId": "canary-prompt-01",
       "responseWordCount": 55,
       "grades": {
@@ -34,9 +34,9 @@
       "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
     },
     {
-      "id": "rc-2026-10-03-002",
-      "createdAt": "2026-10-03T12:16:10.631Z",
-      "buildVersion": "0.29.0-mockdriver",
+      "id": "rc-2026-10-05-002",
+      "createdAt": "2026-10-05T15:28:27.972Z",
+      "buildVersion": "0.31.0-mockdriver",
       "fixturePromptId": "canary-prompt-02",
       "responseWordCount": 55,
       "grades": {
@@ -67,9 +67,9 @@
       "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
     },
     {
-      "id": "rc-2026-10-03-003",
-      "createdAt": "2026-10-03T12:16:10.631Z",
-      "buildVersion": "0.29.0-mockdriver",
+      "id": "rc-2026-10-05-003",
+      "createdAt": "2026-10-05T15:28:27.972Z",
+      "buildVersion": "0.31.0-mockdriver",
       "fixturePromptId": "canary-prompt-03",
       "responseWordCount": 55,
       "grades": {

package/guidance/define-draft-shapes.md

@@ -2,19 +2,24 @@
 
 This document is the content of the `rcf_define_draft_shapes` MCP
 prompt served argument-free by the server. The agent reads it once
-per session and runs the draft pass after L1 is green. The product
-owner is not in the room; the agent populates `[draft]`-marked
-entities, components and interfaces so the engineer walks into a tree
-whose shape is honest about what is still owed.
+per session and runs the draft pass alongside the PO loop. The
+product owner may or may not be in the room; the agent populates
+`[draft]`-marked entities, components and interfaces so the engineer
+walks into a tree whose shape is honest about what is still owed.
 
 ## When to run
 
-Run this pass once `rcf define readiness --level intent` prints
-`levels.intentComplete.ok === true` and the product owner has stepped
-back. Not before. The draft pass reads only the brief ledger, the
-decisions ledger and the current tree; it writes only `[draft]`-marked
-content. `shapes:draftSettled` then lists exactly what the engineer
-has yet to own.
+Run this pass in parallel with the product-owner intent loop and
+reconcile when Intent completes (ruling R3 2026-10-05 under
+w-2026-10-05-dave-001). Nothing in the draft pass changes the PO
+question set, so drafting shapes while the owner answers questions
+cannot destabilise the loop or create a question that was not there.
+The draft pass reads only the brief ledger, the decisions ledger and
+the current tree; it writes only `[draft]`-marked content.
+`shapes:draftSettled` then lists exactly what the engineer has yet to
+own. When Intent completes (`rcf define readiness --level intent`
+prints `levels.intentComplete.ok === true`), the drafts are already
+in place and the engineer walks into them.
 
 Nothing in the draft pass can fail a product-owner check. That is the
 property that keeps L1 and the draft pass independent. If an edit

package/guidance/define-litmus.md

@@ -0,0 +1,102 @@
+# Litmus: landing n fresh-context readings at the current hash
+
+This document is the content of the `rcf_define_litmus` MCP prompt
+served argument-free by the server. The agent reads it once per
+session and runs the litmus pass when the operator or the readiness
+verb asks for it.
+
+## What a litmus reading is
+
+A litmus reading is a probe-ledger entry whose `finding` field begins
+`litmus:<reader>:` and whose text includes the current litmus hash.
+It is written by `rcf define ledger probes add` just like any other
+probe-ledger entry; the `litmus:` prefix is what the verb reads back
+when it counts "distinct readers at this hash".
+
+The litmus hash is the current tree hash computed with the probes
+ledger excluded (ADR-4131 extended, 0.30.0 PR 7 R9). The probes
+ledger is inside `tree.currentTreeHash` by ADR-4120, so a reader
+writing an entry that references `currentTreeHash` would shift the
+hash the reader just attested to. The litmus hash is the content-
+stable version: writing to the probes ledger does not change it, so n
+readers can land their entries at the same hash. Writes to the brief,
+decisions or concerns ledgers do change the litmus hash the same way
+they change `currentTreeHash`; those changes mean the content under
+review has changed and stale litmus readings fall out of the count.
+This trade-off is intentional: litmus readings do not attest to
+probe findings written after them, because probe entries are
+themselves readings.
+
+The number of distinct readers is counted across the probe ledger; a
+reader id appears at most once in the count regardless of how many
+`litmus:<reader>:*` entries it has written.
+
+## When to run
+
+Run this prompt whenever a verb reports the shortfall:
+
+- `rcf define readiness --litmus <n>` exits 4 and prints a `[warn]`
+  line naming the current hash and the number of distinct readers
+  found. The shortfall is the number of fresh-context readers you
+  still owe before the verb will exit 0.
+- `rcf define freeze --litmus <n>` refuses (exit 4) with the same
+  reason and writes nothing. The freeze is only legal when n distinct
+  readers have attested at the hash the verb was asked to freeze.
+
+The harness is the runner. rcf-lite does not spawn processes and does
+not make network calls at runtime. You spawn the readers; they land
+the entries.
+
+## The shape
+
+Each reading is one `rcf define ledger probes add` call:
+
+```
+rcf define ledger probes add \
+  --req <reqId> \
+  --finding "litmus:<reader>: <one-line observation at hash <hash>>" \
+  --severity low
+```
+
+Fill in:
+
+- `<reader>` is a short id for this reader. Make it unique per fresh
+  context (for example `reader-01`, `reader-02`). The verb counts
+  distinct readers by this id.
+- `<reqId>` is the REQ the reader is probing. On a readiness pass this
+  is typically the first failing REQ or a REQ the operator named; on a
+  freeze the ids come from the brief.
+- `<hash>` is the current litmus hash. Read it from
+  `rcf define readiness --json` under `tree.litmusHash` (or from the
+  `[warn]` line the verb printed; the warn line names the litmus hash
+  explicitly).
+
+A reading is "at the hash" when the `hash` substring appears anywhere
+in the finding text, not in a separate field. Keep the hash in the
+finding text so the entry is self-describing.
+
+## The loop
+
+1. Read `tree.litmusHash` from `rcf define readiness --json`.
+2. Spawn n fresh-context readers (one claude session per reader is
+   enough; a reader must not share context with another).
+3. Each reader lands one `litmus:<reader>:` probe-ledger entry at the
+   litmus hash. The entry's finding text includes the litmus hash and
+   one observation; the reader does not edit the tree.
+4. Re-run the verb that asked for `--litmus <n>`. The count is now
+   n and the verb exits 0 (readiness) or writes the freeze record
+   (freeze).
+
+Writes to the probes ledger (adding litmus readings is itself one)
+do not shift the litmus hash, so n readers landing their entries in
+sequence all pin to the same hash and all count. A write to the
+brief, decisions or concerns ledgers (changing the content under
+review) does shift the litmus hash and makes earlier readings stale.
+Hand the readers a hash that will still be current when the last
+reading lands; a short freeze-prep window is the common case.
+
+## When n distinct readers have attested
+
+The verb exits 0. Nothing else is said; the readings stay in the probe
+ledger. A later tree change makes them stale and the next invocation
+of the verb will require fresh readings at the new hash.

package/guidance/manifest.json

@@ -16,7 +16,8 @@
     {"name": "rcf_define_intent", "file": "define-intent.md", "description": "Drive the product-owner intent-complete loop with rcf_define_questions, write-backs through existing verbs, and the readiness verdict. Argument-free; starts with --persona productOwner and ends at levels.intentComplete.ok."},
     {"name": "rcf_define_intake", "file": "define-intake.md", "description": "Walk a document folder brief-first, write one statement file per source with [kind] and (source: ...) markers, run brief add --from once per source, and report the scan findings as open questions. Argument-free."},
     {"name": "rcf_define_draft_shapes", "file": "define-draft-shapes.md", "description": "Run the draft pass after L1 is green: pre-populate [draft] core entities per entity statement, [draft] TAC stubs per surface or externalSystem cluster, [draft] interfaces with real kinds inside each stub, and rcf discover req-classify over every REQ created in the loop. Argument-free."},
-    {"name": "rcf_discover_prototype", "file": "discover-prototype.md", "description": "Record a prototype in DISCOVERY as evidence: classification, brief statements with prototype:<name>:<observation> source spans, the burn statement, and the salvage-by-re-derivation path. Argument-free."}
+    {"name": "rcf_discover_prototype", "file": "discover-prototype.md", "description": "Record a prototype in DISCOVERY as evidence: classification, brief statements with prototype:<name>:<observation> source spans, the burn statement, and the salvage-by-re-derivation path. Argument-free."},
+    {"name": "rcf_define_litmus", "file": "define-litmus.md", "description": "Spawn n fresh-context readers at the current tree hash and land their readings as probe-ledger entries whose finding begins litmus:<reader>:. Required by rcf define readiness --litmus and rcf define freeze --litmus. Argument-free."}
   ],
   "platformInvariants": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rcf-lite",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "type": "module",
   "description": "One-install tooling for the Requirements Confidence Framework (RCF): the unified `rcf` CLI grouped into the five RCF tool groups (discover, define, build, verify, audit) plus a small core set (init, doctor, guidance, mcp), an MCP server, the live tree viewer and the fresh-context adversarial ship-gate verifier. Consumes @stravica-ai/rcf-schemas.",
   "license": "Apache-2.0",

package/rcf/adrs/adr-4131-gates-bite-ack-recorded-override.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-10-03T10:50:00Z",
+  "updatedAt": "2026-10-05T12:00:00Z",
+  "adrId": "ADR-4131-gates-bite-ack-recorded-override",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The gates bite with --ack as the recorded override for D3, D5, D6",
+  "context": "DEFINE step 3 train (spec 2026-10-01) brings the substantive checks of proposal 3.2 into D3, D5 and D6 across PRs 5, 6 and 7. The 0.29.0 posture left those stages warn-with-ack: --check exits 0 with a stderr [warn] line, --ack as the recorded override. The spec section 4 gates-bite intro and decision 9 both pin the biting posture: --check exits 4 on D3, D5 and D6 as it does on blocking stages; --ack stays as the recorded override for those three because the ruleset's recordedInChain channel needs it (decision 8's pattern applied to gates, not retired with the verb). The compute remains pure; readiness.js collects candidate paths and the CLI resolves them on disk so the gate functions see a resolvedPaths map in the stage context. PR 5 lands the three D3 bite checks (shapes:templateMarkers, shapes:entityJoin, shapes:pathsResolve), the ackable(stage) companion to stagePolicy, and the --check shapes exit 4 policy; PRs 6 and 7 bite D5 and D6 on the same shape.",
+  "decision": "The gates bite with --ack as the recorded override for D3, D5 and D6. stagePolicy returns warnWithAck for D3, D5 and D6 and blocking for D1, D2, D4, D7 and D8 (ruling R4 2026-10-05: the honest label for an ackable stage is warnWithAck, and the viewer pill vocabulary and the CLI text report both key off that; the pre-R4 wording that said stagePolicy returned blocking for every stage with a separate ackable() is retired because it was never true in code, and ackable(stage) stays only as the sibling helper that the CLI --check and freeze verbs read to decide whether a failing stage honours an acknowledgement at the current hash). The readiness CLI --check <stage> policy follows that split: on a blocking stage, a failing state exits 4 (today's behaviour); on a warnWithAck stage, a failing state exits 4 unless the freeze record acknowledges that gate at the current tree hash, in which case it exits 0. --ack on any blocking stage stays a usage refusal with exit 2 (D1, D2, D4, D7, D8). The three D3 bite checks ship as pure engineer checks on src/query/gates.js: shapes:templateMarkers over delta (per-kind marker presence on interfaces[].description, ids <tacId>:<name>, why names the missing marker, drafts included), shapes:entityJoin over tree (every coreEntities[].name named by exactly one recordShape, ids TAD.entity:<name>; ruling R5 2026-10-05: the check evaluates before any scope early-return, via the shared helper ADR-4138 lands), shapes:pathsResolve over delta (any path:-like token resolves on disk against the resolvedPaths map in the stage context or the description carries authoredAt: D3; ruling R6 2026-10-05: the token scanner also honours a short whitelist of known bare repo names -- Dockerfile, Makefile, LICENSE, Procfile, Containerfile, Justfile, Rakefile, Gemfile, CODEOWNERS -- so the slash-or-extension rule stops silently skipping them). Validate findings only where a legacy tree can comply; the dogfood tree records any residual failure in KNOWN GAPS rather than weakening the check.",
+  "consequences": "A failing D3 bite now blocks CI unless the engineer either fixes the tree or writes a recorded override with --ack --reason at the current hash; the record stays visible in the freeze record (the chain of recordedInChain the ruleset reads). stagePolicy returns warnWithAck for D3/D5/D6 and blocking for D1/D2/D4/D7/D8 (ruling R4): the viewer pill vocabulary reads that directly, and the CLI --check text output names the policy label alongside the stage state. The readyToBuild fold stays unchanged because the fold reads the stage state (passed | failing | acknowledged | notApplicable), not the stage policy. The gate functions stay pure: the CLI is the module that resolves candidate paths on disk and the stage context carries the resolved map. The D3 bite surfaces three new engineer checks on the readiness tab and the text report; nothing on the productOwner side moves. --level intent and --level build exits are unchanged because the levels fold is already a derived view. Ruling R5 (shapes:entityJoin unconditional) and ruling R7 (skeleton:standardsCited tree-wide regardless of D2 scope) land through ADR-4138's shared helper, so a narrowed D2 or D3 scope that excludes every item in the local scope still reports the tree-wide finding instead of returning notApplicable. The dogfood tree keeps CI green by scoping its own readiness call as it already does; the three new checks pass on the dogfood chain because the shipped TACs name their markers truthfully.",
+  "alternativesConsidered": [
+    {
+      "name": "Retire --ack (make D3, D5, D6 plain blocking)",
+      "summary": "Drop the --ack verb everywhere and let a failing D3, D5 or D6 simply block CI with no override.",
+      "reasonNotChosen": "The ruleset's recordedInChain channel exists so a refuse at a hash can be acknowledged with a reason that becomes part of the chain. The gates bite is decision 8's pattern applied to gates (refuse with a recorded override), and retiring --ack removes the channel the ruleset depends on. The spec decision 9 pins this; this ADR records it in-chain."
+    },
+    {
+      "name": "Keep warn-with-ack: --check exits 0 with a [warn] on D3, D5, D6",
+      "summary": "Leave the 0.29.0 posture in place; let the bite only surface in validate and the viewer.",
+      "reasonNotChosen": "The whole point of the DEFINE step 3 train is to make D3, D5 and D6 bite: the substantive checks of proposal 3.2 land here, and CI must refuse on them for the engineer to feel the gate. Warn-with-ack kept them a soft signal; the spec moves them to blocking with --ack as the recorded override."
+    },
+    {
+      "name": "Make the gate functions impure and resolve paths inline",
+      "summary": "Let shapes:pathsResolve open the filesystem directly so the gate module decides path existence on its own.",
+      "reasonNotChosen": "gates.js is the one pure module every surface composes; folding I/O into it would re-couple the viewer and the CLI through disk access. The CLI already owns the project-root resolve for the walker and the ledgers; adding one more resolve step for candidate paths is a one-pass walk, and the stage context grows by one map. The viewer uses the same seam when it renders the Readiness tab server-side."
+    }
+  ]
+}

package/rcf/adrs/adr-4137-standalone-theme-persistence.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-10-04T14:00:00Z",
+  "updatedAt": "2026-10-05T12:30:00Z",
+  "adrId": "ADR-4137-standalone-theme-persistence",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The in-viewer theme control persists its setting under `rcf-view:v1:theme` in standalone mode only; under `embed=1` the control is absent and the key is never read or written",
+  "context": "The viewer UI refresh design (`2026-10-02_viewer-ui-refresh-design.md`) section 9 and section 11 recommendation 6 called for a three-state Light|Dark|Auto theme control hidden under `embed=1` that stores nothing. PR 1 (0.29.0) shipped the `?theme=` query param and the `rcf-view-theme` postMessage listener but omitted the visible control. Baz's 2026-10-04 review (`w-2026-10-04-dave-001`) found three gaps: (a) no visible control in the standalone viewer, (b) the FIND SearchButton hover and focus states are unreadable in dark, (c) no systematic WCAG AA pass across the stylesheet. On (a) the design decision 'storing nothing' was written for the embedded case: the viewer shares `localStorage` with the wespa SPA under `rcf-view:v1:`, so any key the viewer writes there is a key wespa sees too. In the standalone case there is no shared SPA; a theme control that resets to the system default on every reload is a worse product than the design intended.",
+  "decision": "In non-embed mode the three-state theme control writes the user's choice to `localStorage['rcf-view:v1:theme']` (one of `light`, `dark`, `auto`) and reads it back on boot. Under `embed=1` the control is absent from the DOM entirely (not merely hidden by CSS) and the key is never read or written on load, on a `rcf-view-theme` postMessage, or on any user action inside the viewer. Boot precedence: an explicit `?theme=` query parameter wins first; then (in non-embed mode only) the stored `rcf-view:v1:theme` value, provided it is one of `light`/`dark`/`auto`; then the default (`auto`, which maps to the `prefers-color-scheme` media query via `:root:not([data-theme])`). A live `rcf-view-theme` postMessage still applies in both modes and never writes to the key. The key sits under the shared `rcf-view:v1:` namespace so the PR 9 localStorage namespace lint stays green.",
+  "consequences": "Standalone viewer users (the Readiness / Build / Review audience Baz is coaching Remi through) get a theme control that remembers their choice between reloads, matching every other dev-facing viewer. Wespa (and any other embedder) see no behavioural change: `embed=1` is still a pure-render contract, the viewer still writes nothing on their behalf and reads nothing of theirs. The one deviation from the design doc's 'storing nothing' line is named here and in the CHANGELOG so a future reader can trace it. The embed check is at the storage boundary, not at the render boundary alone, so a future refactor cannot accidentally start writing the key under embed by re-rendering the control: the control's event handler reads `document.documentElement.getAttribute('data-embed') === '1'` and refuses the write in that branch. The PR 9 lint continues to protect the shared namespace. Known transient under embed: the production server renders one page for every client and does not see the request query, so the theme control is briefly painted under `embed=1` until `page-init.js` strips it on boot; the follow-up is for the server to pass `embed` from the request query into `renderPage` so the markup is never emitted (not implemented here). The boot theme is resolved and applied once; a `rcfPage.init()` re-run after an SSE swap never overrides a host postMessage or a control choice (PR 291 landing review F1). Verification: test/view/theme-control.test.js (TC-229-theme-control-renders-non-embed, TC-229-theme-control-persists, TC-229-theme-control-absent-embed, TC-229-theme-control-query-wins, and the F1 regressions TC-229-reinit-keeps-host-theme and TC-229-reinit-keeps-control-choice).",
+  "alternativesConsidered": [
+    {
+      "name": "Never persist anywhere (literal design doc reading)",
+      "summary": "Keep the theme control stateless in both modes: every reload resets to the default (`auto`), the control only remembers the current session.",
+      "reasonNotChosen": "A worse product in standalone mode and the only reason to refuse the write (shared localStorage with wespa) does not exist outside the embedded case. The design doc's 'storing nothing' line was written against the embed hazard; in standalone there is nothing to share with."
+    },
+    {
+      "name": "Persist in both modes",
+      "summary": "Write `rcf-view:v1:theme` under `embed=1` too; the shared-localStorage hazard is accepted and wespa can inspect the key if it wants.",
+      "reasonNotChosen": "Breaks Dex's wespa contract: wespa pins the embed-mode behaviour by exact version, and a new key under the shared namespace is a surface change that needs a release-note bump and a wespa-side change. The storage boundary is cheap to guard and keeps the embedded case byte-identical to pre-amendment."
+    },
+    {
+      "name": "Persist under a non-shared key",
+      "summary": "Write the theme to `sessionStorage` or a key outside the `rcf-view:v1:` namespace in standalone mode.",
+      "reasonNotChosen": "`sessionStorage` does not survive a browser restart (the standalone user still re-picks on every new window), and a key outside `rcf-view:v1:` would break the PR 9 localStorage namespace lint. The embed-boundary branch above is the smaller change that keeps both constraints green."
+    }
+  ]
+}

package/rcf/adrs/adr-4138-tree-wide-checks-before-scope-shortcircuit.json

@@ -0,0 +1,35 @@
+{
+  "createdAt": "2026-10-05T12:00:00Z",
+  "updatedAt": "2026-10-05T19:00:00Z",
+  "adrId": "ADR-4138-tree-wide-checks-before-scope-shortcircuit",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.2",
+  "status": "accepted",
+  "title": "Tree-wide checks evaluate before any scope short-circuit",
+  "context": "DEFINE step 3 rulings R2 (draftSettled tree-wide), R5 (entityJoin unconditional) and R7 (standardsCited tree-wide) landed on the same shape: a stage whose scope narrows to nothing (D3 with no TAC and no shaped REQ, D2 with no resolving brief statement and no REQ/PRD/TAD) returns a `notApplicable` envelope before any check runs, which silently hides tree-wide findings. The hidden findings are real: a drafted TAD core entity is unjoined to any recordShape (R5), a registered standards pack is uncited (R7), or a `[draft]` marker sits on a TAC outside the narrowed scope (R2) even when the delta touched nothing in the stage's local scope. The pattern is the ruling, not the three instances: the review of rcf-lite PR 292 (d-2026-10-05-012, ruling R13 confirmed by Baz 2026-10-05) found three further tree-wide checks still hidden by the same short-circuit shape -- D5 `crosscut:securityArchitecture`, D5 `crosscut:operationalConcerns` and D2 `skeleton:deployAdr` -- all of which read tree-wide inputs (`tree.requirements`, `tree.userStories`, `tree.adrs`) and all of which disappear when the stage's own `reqInScope` / resolving-statement set is empty. D4 (`stories:closedSets`, `stories:ownerRefResolves` under their own `notApplicable` arm) and D6 (every check is tree-wide anyway, and the probe-ledger scan sits outside the scope early-return already) are unchanged. The fix is one shared helper the gates module applies at every stage with a tree-wide check.",
+  "decision": "A stage with a tree-wide check evaluates those checks before any scope-driven `notApplicable` early-return. `src/query/gates.js` has one shared module-internal helper `treeWideFailureEnvelope(stage, gate, treeWideChecks, freezeCtx)` that takes the already-computed per-check results as `[{ name, check }]` entries and returns either `null` (every tree-wide check ok -- the stage proceeds to its own scope early-return or full checks list) or the envelope `foldState(stage, gate, checks, freezeCtx)` returns over a `checks[]` carrying the `stage:<D>:scope` placeholder plus every tree-wide check: `{ stage, gate, state: 'failing' | 'acknowledged', checks }` with no `reason` field. The helper delegates the fold to `foldState` on every stage, so a single implementation owns the acknowledgement rule and the two cannot drift: a warn-with-ack stage (D3, D5, D6) acknowledged at the current tree hash folds to `acknowledged`, and a blocking stage (D2) always folds to `failing`. The stage function computes each tree-wide check once (so the viewer and the text report render the same check object), calls the helper first when the local scope is empty, and otherwise runs its full checks list with the tree-wide check(s) interleaved in the same slot in `checks[]`. The helper governs every tree-wide check: `shapes:draftSettled` (R2), `shapes:entityJoin` (R5), `skeleton:standardsCited` (R7), and the three R13 checks `crosscut:securityArchitecture` (D5), `crosscut:operationalConcerns` (D5), `skeleton:deployAdr` (D2). It does NOT govern delta-only checks: `shapes:templateMarkers`, `shapes:pathsResolve`, `stories:closedSets`, `stories:ownerRefResolves` and the D4 floors keep running against the stage scope and continue to short-circuit on an empty scope. R2 2026-10-05 flipped `shapes:draftSettled`'s `over` label from `delta` to `tree` to match the ruling; the other six tree-wide checks already carried `over: tree`. The CHECK_PERSONA and CHECK_QUESTION fields stay fixed to their spec section 4 values.",
+  "consequences": "A narrowed D2 scope that excludes every REQ/PRD/TAD/brief statement still reports an uncited standards pack through `skeleton:standardsCited` and a missing (or doubled) Deploy ADR through `skeleton:deployAdr`. A narrowed D3 scope that excludes every TAC and shaped REQ still reports a `[draft]` anywhere in the tree through `shapes:draftSettled` and an unjoined entity through `shapes:entityJoin`. A narrowed D5 scope that excludes every REQ still reports an empty `TAD.securityArchitecture` while an auth or httpApi REQ exists through `crosscut:securityArchitecture`, and an empty `TAD.operationalConcerns` while a deployed-scope AC exists through `crosscut:operationalConcerns`. The readiness compute stays pure (the helper is a function of the context, same shape as the stage functions). The `notApplicable` fold the viewer and CLI pills already read is unchanged in effect when nothing tree-wide fails. A failing envelope the helper returns carries no `reason`: the fold already lists the failing check names and the pre-R13 `reason` text (copied from the stage's `notApplicable` message) was misleading in the printed `readiness` line ('failing (no TAC ... in scope)'). The `over: tree` label flipped on `shapes:draftSettled` (R2); every other tree-wide check already carried it. Tests pin the ordering per newly governed check: a scope that excludes every item in the stage's local scope AND a tree-wide failure returns a `failing` envelope, not a `notApplicable` one.",
+  "alternativesConsidered": [
+    {
+      "name": "Keep the scope early-return and route tree-wide findings through D8 only",
+      "summary": "Let narrowed D2/D3/D5 scopes return `notApplicable` and surface the tree-wide failures only when D8 runs validate clean.",
+      "reasonNotChosen": "D8 is the freeze gate; a narrowed scope at D2/D3/D5 is used to triage work in flight, not to freeze. Making the engineer wait until the freeze pass to see an unjoined entity, an uncited standards pack, an empty securityArchitecture or a missing Deploy ADR hides the finding during the loop that should surface it. Spec section 4 names every tree-wide check with `over: tree`; the pre-R2/R5/R7/R13 ordering contradicted that."
+    },
+    {
+      "name": "Lift every tree-wide check to a new top-level pass before the stage dispatch",
+      "summary": "Add a `runTreeWideChecks(ctx)` compute at the readiness level that runs before every stage function and prepends its findings to the first failing stage.",
+      "reasonNotChosen": "Changes the readiness result shape and the viewer / CLI consumers that key off the per-stage `checks[]` array. The shared helper keeps every tree-wide check in its canonical stage so `stages[D2].checks[].name === 'skeleton:standardsCited'` still holds."
+    },
+    {
+      "name": "Duplicate the tree-wide check into D8",
+      "summary": "Mirror `shapes:entityJoin` and `skeleton:standardsCited` into D8's checks so a narrowed D2/D3 scope's miss still gets caught at freeze.",
+      "reasonNotChosen": "A failing D2 at freeze fails the freeze gate anyway (D8 `freeze:priorGates`). The duplication adds a second ownership for the same check and the viewer would need to pick which name wins. The helper preserves one owning stage per tree-wide check."
+    },
+    {
+      "name": "Limit the helper to the three checks R2/R5/R7 named and leave securityArchitecture / operationalConcerns / deployAdr behind the scope",
+      "summary": "Govern only the three checks the DEFINE step 3 spec section 18 named at R2/R5/R7 ship time and leave the three further checks the PR 292 review surfaced where they were.",
+      "reasonNotChosen": "The principle, not the inventory, is the ruling. Baz 2026-10-05 ratified every open ruling as recommended and confirmed R13 on the same cycle. Keeping half the tree-wide checks hidden by the scope would ship a half-fix; a narrowed D5 scope that excludes an auth REQ would still miss an empty securityArchitecture even though the whole stage computes it from the whole tree."
+    }
+  ]
+}

package/rcf/code-nodes/cn-753.json

@@ -0,0 +1,19 @@
+{
+  "cnId": "CN-753",
+  "path": "src/query/gates.js",
+  "title": "DEFINE step 3 PR 5: D3 bite checks, parseInterfaceTemplate and ackable on the gates module",
+  "description": "src/query/gates.js grows the three D3 bite checks (shapes:templateMarkers over delta with per-kind marker presence on interfaces[].description; shapes:entityJoin over tree asserting every coreEntities[].name is named by exactly one recordShape with ids TAD.entity:<name>; shapes:pathsResolve over delta asserting any path:-like token resolves against the resolvedPaths map in the stage context or carries authoredAt: D3), the parseInterfaceTemplate(iface) helper that computes per-kind marker presence (exported for validate's step 6 notice), and the ackable(stage) helper that returns true for D3, D5 and D6. The CHECK_PERSONA, CHECK_QUESTION and STAGE_FALLBACK_PERSONA maps grow in step so every new check carries a persona and a question. Drafts are included in templateMarkers. The gate functions stay pure: readiness.js threads the resolvedPaths map through the stage context; the CLI resolves candidate paths on disk.",
+  "implementsAcIds": [
+    "AC-17404-1",
+    "AC-17404-2",
+    "AC-17404-3",
+    "AC-17404-4"
+  ],
+  "dependencies": [
+    "CN-725"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T10:50:00Z",
+  "updatedAt": "2026-10-03T10:50:00Z"
+}

package/rcf/code-nodes/cn-754.json

@@ -0,0 +1,17 @@
+{
+  "cnId": "CN-754",
+  "path": "src/cli/readiness.js",
+  "title": "DEFINE step 3 PR 5: --check shapes exit 4 policy and resolvedPaths resolve-on-disk",
+  "description": "src/cli/readiness.js grows a bite-aware --check policy: --check shapes exits 4 on an unacknowledged D3 failure and 0 when the freeze record acknowledges define.shapes at the current tree hash; the warn-with-ack branch is kept for D5 and D6 until PRs 6 and 7 bite them. Before invoking computeReadiness the CLI collects candidate path tokens from in-scope TAC interface descriptions and passes a resolvedPaths map (local resolve on disk) through the stage context so the pure gate function shapes:pathsResolve can decide path existence without I/O. The decideExitCode helper reads ackable(stage) and the freeze.gates[<gate>] record to pick between 0 (warn-with-ack unacked or acked bite) and 4 (bite unacked at the current hash).",
+  "implementsAcIds": [
+    "AC-17404-5"
+  ],
+  "dependencies": [
+    "CN-727",
+    "CN-753"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T10:50:00Z",
+  "updatedAt": "2026-10-03T10:50:00Z"
+}

package/rcf/code-nodes/cn-755.json

@@ -0,0 +1,14 @@
+{
+  "cnId": "CN-755",
+  "path": "src/cli/freeze.js",
+  "title": "DEFINE step 3 PR 5: freeze --ack on D1, D2, D4, D7 or D8 keeps exiting 2",
+  "description": "src/cli/freeze.js already refuses --ack on any gate outside D3, D5 and D6 with exit 2 and the usage line ADR-4124 pins. PR 5 confirms the invariant with AC-17404-6: ackable(stage) in gates.js is the single source of truth for the three ackable gates (freeze reads ACKABLE_GATES = STAGE_GATES.D3 | D5 | D6, which lines up with ackable()). No code change in this PR; this CN anchors the AC against the file that enforces the invariant so a future refactor cannot drop the exit-2 behaviour without flagging the AC.",
+  "implementsAcIds": [
+    "AC-17404-6"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T10:50:00Z",
+  "updatedAt": "2026-10-03T10:50:00Z"
+}

package/rcf/code-nodes/cn-756.json

@@ -0,0 +1,15 @@
+{
+  "cnId": "CN-756",
+  "path": "src/define/concern-catalogue.js",
+  "title": "DEFINE step 3 PR 6: the eight-concern applicability map keyed by REQ shape",
+  "description": "src/define/concern-catalogue.js lands as a new pure module beside ledgers.js. Exports CONCERN_KEYS (the eight concern names in canonical order), CONCERN_APPLICABILITY (the map { concern -> [req-shapes] } that spec section 4 row 'D5 catalogue' pins), and applicableConcernsFor(reqShape) which returns the concern keys that apply to a REQ shape. No I/O, no state. Keys shared with the baseline catalogue where names coincide (auth; the rest are new because the baseline-AC catalog does not name per-concern crosscut keys). Read by crosscut:catalogue in src/query/gates.js (PR 6) to enumerate the applicable (reqShape, concern) pairs for every REQ in scope.",
+  "implementsAcIds": [
+    "AC-17405-3",
+    "AC-17405-4"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T13:30:00Z",
+  "updatedAt": "2026-10-03T13:30:00Z"
+}

package/rcf/code-nodes/cn-757.json

@@ -0,0 +1,21 @@
+{
+  "cnId": "CN-757",
+  "path": "src/query/gates.js",
+  "title": "DEFINE step 3 PR 6: D4 closed-set and ownerRef findings, D5 catalogue, standards citation on the gates module",
+  "description": "src/query/gates.js grows four new engineer checks: stories:closedSets (over delta; AC description with an enumeration cue and no bracketed list or ownerRef fails, honouring the quoted-cue guard shared with D6); stories:ownerRefResolves (over delta plus tree for ownerRef targets; every ownerRef { tacId, field: interfaces[<name>] } on an AC resolves on that TAC, else fails with 'ownerRef does not resolve'); crosscut:catalogue (over tree; for every REQ in scope, every applicable (reqShape, concern) pair via src/define/concern-catalogue.js has a concern-ledger entry keyed <REQ>:<concern> with disposition applied or waived, else fails <REQ>:<concern>); skeleton:standardsCited (over tree; every manifest.standards[].slug is cited in a REQ rationale or an ADR, or waived by a concern-ledger entry keyed standards:<pack>, else fails standards:<pack> with 'uncited and unwaived'). The CHECK_PERSONA and CHECK_QUESTION maps grow in step. parseAcClass is already exported; closedSets re-uses the quoted-cue guard pattern.",
+  "implementsAcIds": [
+    "AC-17405-1",
+    "AC-17405-2",
+    "AC-17405-3",
+    "AC-17405-4",
+    "AC-17405-5"
+  ],
+  "dependencies": [
+    "CN-753",
+    "CN-756"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T13:30:00Z",
+  "updatedAt": "2026-10-03T13:30:00Z"
+}

package/rcf/code-nodes/cn-758.json

@@ -0,0 +1,16 @@
+{
+  "cnId": "CN-758",
+  "path": "src/cli/readiness.js",
+  "title": "DEFINE step 3 PR 6: --check crosscut rides the D3 --ack fold with exit 4 unacked and 0 acked",
+  "description": "src/cli/readiness.js lifts the hard-coded D3-only bite branch so --check crosscut (and --check D5) honours the same --ack fold as --check shapes: an unacknowledged D5 failure exits 4; a D5 failure acknowledged at the current tree hash exits 0. The decision defers to gates.js's ackable(stage) rather than naming D5 inline, so a future bite on D6 is a one-line change. --check consistency keeps the 0.29.0 warn-with-ack posture until PR 7 bites D6; D1, D2, D4, D7, D8 keep exit 4 on a failure as blocking stages already do.",
+  "implementsAcIds": [
+    "AC-17405-3"
+  ],
+  "dependencies": [
+    "CN-754"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T13:30:00Z",
+  "updatedAt": "2026-10-03T13:30:00Z"
+}

package/rcf/code-nodes/cn-759.json

@@ -0,0 +1,21 @@
+{
+  "cnId": "CN-759",
+  "path": "src/query/gates.js",
+  "title": "DEFINE step 3 PR 7: four D6 scans (consistency:contradictions/unsatisfiable/duplicates/orphanInterfaces)",
+  "description": "src/query/gates.js gains four new engineer checks on checkD6Consistency: contradictions (two ACs on one story sharing a when clause with a negated then, honouring the shared quoted-substring guard with D4), unsatisfiable (a then naming a field no recordShape defines; a field defined in a [draft] recordShape counts as defined), duplicates (identical AC descriptions across stories fail both ACs), and orphanInterfaces (an interface on any TAC that no AC ownerRef points at and that no REQ deliveredBy reaches fails). The four checks are registered in CHECK_PERSONA and CHECK_QUESTION; they ride the existing D6 ackable fold.",
+  "implementsAcIds": [
+    "AC-17406-1",
+    "AC-17406-2",
+    "AC-17406-3",
+    "AC-17406-4",
+    "AC-17406-5",
+    "AC-17406-6"
+  ],
+  "dependencies": [
+    "CN-757"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-10-03T16:10:00Z",
+  "updatedAt": "2026-10-03T16:10:00Z"
+}