rcf-lite 0.28.4 → 0.29.0

package/rcf/test-suites/ts-229.json

@@ -0,0 +1,83 @@
+{
+  "createdAt": "2026-10-03T09:55:00Z",
+  "updatedAt": "2026-10-03T10:00:00Z",
+  "purpose": "Cover US-206 (wespa's embedding contract is proved by a CI host fixture): the fixture renders a 56px header + resizable sidebar around an iframe pointed at ./?embed=1&theme=light with no inline script (AC-206-1), theme flips via postMessage without a reload (AC-206-2, source invariants + Playwright live proof in the lane evidence), embed and theme survive a hash-only in-iframe navigation (AC-206-3, source invariants + Playwright live proof), cross-origin messages are ignored by the viewer listener (AC-206-4), the three lints keep framing headers, target=_top and localStorage namespace in place (AC-206-5), and no new outbound postMessage shape is introduced by the viewer or the fixture (AC-206-6). All TCs resolve to node tests under test/view/wespa-host-fixture.test.js.",
+  "testLevel": "unit",
+  "acIds": [
+    "AC-206-1",
+    "AC-206-2",
+    "AC-206-3",
+    "AC-206-4",
+    "AC-206-5",
+    "AC-206-6"
+  ],
+  "id": "TS-229",
+  "usId": "US-206",
+  "title": "Wespa host fixture: iframe shell, theme postMessage, hash-nav embed preservation, cross-origin refusal, three lints, no new outbound postMessage shape",
+  "testCases": [
+    {
+      "id": "TC-229-fixture-shell",
+      "acId": "AC-206-1",
+      "description": "renderTestHostPage returns an HTML5 document with a 56px wespa-header, data-rcf-host-sidebar + data-rcf-host-sidebar-drag markers, data-rcf-host-theme light/dark toggles, an iframe whose src is literally './?embed=1&theme=light' (HTML-entity encoded), a '<script src=./test-host.js defer>' line and zero inline <script> blocks.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::renderTestHostPage: HTML5 document, no inline script, iframe src is ./?embed=1&theme=light"
+    },
+    {
+      "id": "TC-229-test-host-http-roundtrip",
+      "acId": "AC-206-1",
+      "description": "The router serves /test-host.html with the fixture body (iframe src + script tag) and /test-host.js with application/javascript when testHost: true; both routes return 404 by default so wespa's reverse-proxy allow-list is unaffected.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::/test-host.html is served when testHost: true; iframe src and no inline script round-trip over HTTP"
+    },
+    {
+      "id": "TC-229-theme-postmessage-source",
+      "acId": "AC-206-2",
+      "description": "src/view/test-host/embed-client.js posts { type: 'rcf-view-theme', theme } to iframe.contentWindow targeting window.location.origin, and its code (comments stripped) contains no localStorage/sessionStorage write (ADR-4136 does-not-persist invariant). The live postMessage round-trip is captured in Playwright evidence (agents/dave/remote-lane/inbox/r-20261002-161325-e2a2/output/evidence/test-host-dark-iframe-flipped.png).",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::AC-206-2: embed-client posts { type: rcf-view-theme, theme } to the iframe targeting window.location.origin"
+    },
+    {
+      "id": "TC-229-hash-nav-embed-preserved",
+      "acId": "AC-206-3",
+      "description": "src/view/page-init.js exposes writeHash (reassigns location.hash only, preserving the search string by construction) and stamps data-embed + data-theme on load. Live hash-nav proof lives in Playwright evidence (hash-nav-proof.txt + test-host-iframe-hash-nav-embed-preserved.png).",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::AC-206-3: page-init preserves embed=1 and theme= across hash writes (urlWithHash + writeHash)"
+    },
+    {
+      "id": "TC-229-cross-origin-ignored",
+      "acId": "AC-206-4",
+      "description": "src/view/page-init.js registers an addEventListener('message', ...) whose first guard returns early when ev.origin !== window.location.origin; cross-origin messages never reach the applyTheme path and <html data-theme> is unchanged.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::AC-206-4: page-init theme message listener rejects messages whose origin differs from window.location.origin"
+    },
+    {
+      "id": "TC-229-lint-framing",
+      "acId": "AC-206-5",
+      "description": "assertFramingHeaders over GET / returns ok: true (no X-Frame-Options; no CSP frame-ancestors forbidding same-origin). Positive + negative unit cases also pass (refuses on X-Frame-Options present, refuses on frame-ancestors 'none', accepts frame-ancestors 'self').",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::lint 1 (framing): GET / carries no X-Frame-Options and no CSP frame-ancestors that forbids same-origin"
+    },
+    {
+      "id": "TC-229-lint-no-target-top",
+      "acId": "AC-206-5",
+      "description": "assertNoTargetTop returns count: 0 across every rendered page (renderPage shell, renderComponentsFixturePage, renderTestHostPage). Also lints the populated dogfood tree render (renderModelToPage) so per-document conditional output cannot smuggle a target=\"_top\" past the test. Positive + negative unit cases cover target=\"_top\" / target='_top' / target=_top.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::lint 2 (target=\"_top\"): zero occurrences across every rendered page (shell, components fixture, test-host fixture, populated dogfood tree)"
+    },
+    {
+      "id": "TC-229-lint-localstorage-namespace",
+      "acId": "AC-206-5",
+      "description": "assertLocalStorageNamespace over the src/view tree returns ok: true; every localStorage/sessionStorage call site resolves to a key starting with 'rcf-view:v1:'.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::lint 3 (localStorage namespace): every storage call site under src/view uses an rcf-view:v1: key"
+    },
+    {
+      "id": "TC-229-no-new-outbound-postmessage-shape",
+      "acId": "AC-206-6",
+      "description": "A grep over src/view/** (excluding test-host/embed-client.js, the sanctioned emitter) finds zero .postMessage( call sites; the embed-client itself posts exactly one shape, 'rcf-view-theme'.",
+      "status": "pending",
+      "testPointer": "test/view/wespa-host-fixture.test.js::AC-206-6: no outbound postMessage shape beyond rcf-view-theme is introduced by the viewer or the fixture"
+    }
+  ],
+  "status": "draft"
+}

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

@@ -0,0 +1,50 @@
+{
+  "usId": "US-17302",
+  "prdId": "PRD-001",
+  "reqId": "REQ-173",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "update and the pointer grammar",
+  "description": "User story under REQ-173. Every ledger supports `update <id>` with field patches validated as `add` validates; `resolvedBy` on a brief statement is a closed pointer grammar validated by D2.",
+  "asA": "harness",
+  "iWant": "to patch a statement's kind, text or resolution",
+  "soThat": "a correction does not mint a duplicate",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17302-1",
+      "description": "[happy] given statement 7, when rcf define ledger brief update 7 --kind constraint --resolved-by REQ-003 runs, then the statement carries kind constraint and resolvedBy REQ-003 and its id and addedAt are unchanged.",
+      "testable": true
+    },
+    {
+      "id": "AC-17302-2",
+      "description": "[happy] given decision 2 with one option, when rcf define ledger decisions update 2 --option a:x --option b:y --default a runs, then decisions:wellFormed passes it.",
+      "testable": true
+    },
+    {
+      "id": "AC-17302-3",
+      "description": "[happy] given each pointer form REQ-nnn, TAD.entity:<name>, PRD.user:<name>, TAD.system:<name>, TAC-nnnn and omitted:<reason> resolving on the fixture, when D2 runs, then skeleton:resolvedBy passes the statement.",
+      "testable": true
+    },
+    {
+      "id": "AC-17302-4",
+      "description": "[failure] given --resolved-by \"loan thing\", when update runs, then it exits 2 naming the grammar and writes nothing.",
+      "testable": true
+    },
+    {
+      "id": "AC-17302-5",
+      "description": "[failure] given --resolved-by REQ-999 on a tree with no REQ-999, when D2 runs, then skeleton:resolvedBy fails the statement with \"pointer does not resolve\".",
+      "testable": true
+    },
+    {
+      "id": "AC-17302-6",
+      "description": "[must-not] given a statement whose text contains an existing REQ title and no resolvedBy, when D2 runs in 0.30.0, then skeleton:resolvedBy does not pass it on the title hit.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4121-define-ledgers"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-02T16:40:00Z",
+  "updatedAt": "2026-10-02T16:40:00Z"
+}

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

@@ -49,10 +49,22 @@
       "id": "AC-17401-8",
       "description": "checkD8Freeze enforces the tree-wide gate: every prior stage state (D1..D7 as computeReadiness composes them) is passed or acknowledged at the current hash; every AC id in the tree is bound by exactly one FBS (walker's fbsByAcId map has length 1); the queue head (computeQueue.nextActionable) is not null; validateErrors is empty. The stage is never notApplicable.",
       "testable": true
+    },
+    {
+      "id": "AC-17401-9",
+      "description": "checkD2Skeleton reads tad.dataArchitecture.dataStores and tad.dataArchitecture.coreEntities (not top-level) when evaluating skeleton:tadPersistence; a tree whose TAD places both arrays under dataArchitecture per rcf-schemas 0.6.3 passes the check and a tree with the arrays missing or empty under dataArchitecture fails with { id: 'TAD.dataArchitecture.dataStores' } / { id: 'TAD.dataArchitecture.coreEntities' }.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-10",
+      "description": "src/setup/identity-seed.js IDENTITY_TEMPLATE seeds a '## Surface' section containing one line that is one of 'viewer' | 'runningApp' | 'prDiff' (default 'prDiff' with explanatory text matching the Register section's style) so that a project immediately after 'rcf init' passes checkD1Brief's profile:surface check without further operator action. The seed stays idempotent (an existing profile.md is left byte-identical, per the slice-1 'kept' contract).",
+      "testable": true
     }
   ],
-  "tacIds": ["TAC-4122-define-gates"],
+  "tacIds": [
+    "TAC-4122-define-gates"
+  ],
   "tags": [],
   "createdAt": "2026-09-24T14:30:00Z",
-  "updatedAt": "2026-09-24T14:30:00Z"
+  "updatedAt": "2026-10-01T13:03:38Z"
 }

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

@@ -0,0 +1,55 @@
+{
+  "usId": "US-17402",
+  "prdId": "PRD-001",
+  "reqId": "REQ-174",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Persona tag on every gate check",
+  "description": "User story under REQ-174. Every entry in stages[].checks[] carries an owning persona (productOwner | engineer) declared in code next to the check, so readiness consumers (the CLI, the viewer tab, delivery-stream artefacts) can route a failing check to whoever is actually blocked.",
+  "asA": "an engineer reading a readiness report",
+  "iWant": "every failing check to say whose question it is",
+  "soThat": "product-owner questions reach the product owner and engineering gaps stay with me",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17402-1",
+      "description": "[happy] Given any tree, when readiness is computed, then every entry in stages[].checks[] carries persona equal to 'productOwner' or 'engineer' and a non-empty question string.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-2",
+      "description": "[happy] Given the D1 checks, when readiness is computed, then brief:sinceFreeze, brief:kinds, brief:openQuestions and brief:profile carry persona 'productOwner'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-3",
+      "description": "[happy] Given the D2 checks, when readiness is computed, then skeleton:resolvedBy and skeleton:reqIntent carry persona 'productOwner' and skeleton:reqShape, skeleton:tadPersistence and skeleton:deployAdr carry persona 'engineer'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-4",
+      "description": "[happy] Given the D4 and D7 checks, when readiness is computed, then stories:reqHasUs and decisions:wellFormed carry persona 'productOwner' and stories:usFloors and decisions:allAnswered carry persona 'engineer'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-5",
+      "description": "[happy] Given the D3, D5, D6 and D8 checks, when readiness is computed, then every check carries persona 'engineer'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-6",
+      "description": "[must-not] Given any check, when readiness is computed, then no check carries a persona value other than 'productOwner' or 'engineer', and no failing item carries its own persona.",
+      "testable": true
+    },
+    {
+      "id": "AC-17402-7",
+      "description": "[failure] Given a notApplicable stage, when readiness is computed, then its stage:<D>:scope placeholder check carries the stage's STAGE_FALLBACK_PERSONA and ok true.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4122-define-gates"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,60 @@
+{
+  "usId": "US-17403",
+  "prdId": "PRD-001",
+  "reqId": "REQ-174",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Split heterogeneous checks and detect the D3 draft marker",
+  "description": "User story under REQ-174. skeleton:reqFields and decisions:allAnswered split into homogeneous checks (per persona), and a new D3 shapes:draftSettled flags any interface whose description still carries the leading [draft] marker. L1 pre-populated shapes stay distinguishable from engineer-settled ones.",
+  "asA": "an engineer",
+  "iWant": "the mixed checks split and a draft interface distinguishable from a settled one",
+  "soThat": "a shape the L1 agent pre-populated never reads as my finished work",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17403-1",
+      "description": "[happy] Given a REQ in scope with a TODO description and no shapeClassification, when D2 runs, then skeleton:reqIntent fails the REQ for the description and skeleton:reqShape fails the same REQ for the missing shapes.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-2",
+      "description": "[happy] Given a REQ in scope with a description and shapes but no domain, when D2 runs, then skeleton:reqIntent fails the REQ with 'domain missing' and skeleton:reqShape passes it.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-3",
+      "description": "[happy] Given a TAC in scope whose only interface description starts with [draft], when D3 runs, then shapes:tacHasInterface passes the TAC and shapes:draftSettled fails <tacId>:<name> with 'draft interface pre-populated at L1, not yet settled'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-4",
+      "description": "[happy] Given the same TAC after the [draft] marker is removed, when D3 runs, then shapes:draftSettled passes it.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-5",
+      "description": "[failure] Given a [draft] interface whose kind is not in INTERFACE_KINDS, when D3 runs, then shapes:kindVocabulary fails it exactly as it would a settled interface.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-6",
+      "description": "[happy] Given a decisions ledger with one open entry that has a question, two options and a default, when D7 runs, then decisions:wellFormed passes and decisions:allAnswered fails the entry.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-7",
+      "description": "[failure] Given a decisions ledger entry with one option and no default, when D7 runs, then decisions:wellFormed fails it with 'decision is not enumerated (question, two or more options, a default)'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17403-8",
+      "description": "[must-not] Given any tree, when D2 or D7 runs, then no check named skeleton:reqFields is emitted and the stage envelope shape (stage, gate, state, checks) is unchanged.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4122-define-gates"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,60 @@
+{
+  "usId": "US-17502",
+  "prdId": "PRD-001",
+  "reqId": "REQ-175",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Two levels folded on one readiness object",
+  "description": "User story under REQ-175. computeReadiness folds levels (intentComplete, readyToBuild) and personas (productOwner, engineer) from stages[].checks[] on every read; nothing new is written. The `rcf define readiness --level intent --json` output at a tree hash is the artefact a delivery stream picks up.",
+  "asA": "a delivery stream",
+  "iWant": "`rcf define readiness --level intent --json` at a tree hash to be the artefact that says the product owner's part is done",
+  "soThat": "I can pick a tree up without a hand-over meeting",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17502-1",
+      "description": "[happy] Given a tree where every productOwner check is ok and at least one engineer check fails, when readiness is computed, then levels.intentComplete.ok is true and levels.readyToBuild.ok is false.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-2",
+      "description": "[happy] Given a tree where freezeable is true, when readiness is computed, then levels.readyToBuild.ok is true and levels.intentComplete.ok is true.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-3",
+      "description": "[failure] Given a tree where brief:profile fails, when readiness is computed, then levels.intentComplete.ok is false and levels.intentComplete.blockedBy holds one blocker for D1 brief:profile with persona productOwner and ids profile:surface and profile:register.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-4",
+      "description": "[happy] Given a D3 stage acknowledged at the current hash with a failing engineer check, when readiness is computed, then that check is absent from levels.readyToBuild.blockedBy.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-5",
+      "description": "[happy] Given any tree, when readiness is computed, then personas.productOwner.blockers deep-equals levels.intentComplete.blockedBy and levels.readyToBuild.nextAction deep-equals nextAction.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-6",
+      "description": "[happy] Given failing engineer checks in D2 and D4 and a failing productOwner check in D4 only, when readiness is computed, then personas.productOwner.nextAction names D4 and personas.engineer.nextAction names D2.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-7",
+      "description": "[must-not] Given any invocation of `rcf define readiness`, when it completes, then no file under rcf/ has been created or modified.",
+      "testable": true
+    },
+    {
+      "id": "AC-17502-8",
+      "description": "[must-not] Given the 0.28.4 JSON consumer fields (tree, delta, stages, nextAction, coverage, decisions, freezeable), when readiness is emitted under 0.29.0, then every one of them is present with its 0.28.4 type.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4123-define-readiness"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,65 @@
+{
+  "usId": "US-17503",
+  "prdId": "PRD-001",
+  "reqId": "REQ-175",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Level and persona flags on rcf define readiness",
+  "description": "User story under REQ-175. The verb exposes the two levels folded in US-17502 through --level intent|build and groups the text report by persona via --persona productOwner|engineer. --level drives the exit code against levels.<which>.ok (stricter than --check all on warn-with-ack failures per ADR-4126 and decision 4 of the step 2 spec); --persona is a display filter and never affects the exit code or JSON content. The JSON gains a _meta.level marker when --level is set; both verdict lines always print at the top of the text report. See the DEFINE step 2 persona-levels spec dated 2026-10-01 (section 3) for the full flag table and exit matrix.",
+  "asA": "an operator",
+  "iWant": "--level intent|build and --persona on rcf define readiness",
+  "soThat": "a script exits on the verdict it cares about and a person sees their own questions first",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17503-1",
+      "description": "[happy] Given no --level and no --check, when the verb runs on a failing tree, then it prints both verdict lines and exits 0.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-2",
+      "description": "[happy] Given --level intent on a tree where only engineer checks fail, when the verb runs, then it prints 'Intent-complete: yes.' and exits 0.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-3",
+      "description": "[failure] Given --level intent on a tree where a productOwner check fails, when the verb runs, then it exits 4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-4",
+      "description": "[failure] Given --level build on a tree with an unacknowledged D3 failure and every blocking stage passed, when the verb runs, then it prints the [warn] line and exits 4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-5",
+      "description": "[happy] Given --check all on the same tree, when the verb runs, then it exits 0, unchanged from 0.28.4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-6",
+      "description": "[happy] Given --persona productOwner, when the verb runs in text mode, then the engineer block is one line with its check count and the exit code is the same as without the flag.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-7",
+      "description": "[failure] Given --level ship or --persona architect, when the verb runs, then it exits 2 with a usage line naming the accepted values.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-8",
+      "description": "[happy] Given --json --level intent, when the verb runs, then _meta.level is 'intent' and the object carries levels and personas.",
+      "testable": true
+    },
+    {
+      "id": "AC-17503-9",
+      "description": "[happy] Given the text report on a failing tree, when it renders, then the product-owner block precedes the engineer block and each failing check line carries its persona inside the parenthesis after over.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4123-define-readiness"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T16:00:00Z",
+  "updatedAt": "2026-10-01T16:00:00Z"
+}

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

@@ -0,0 +1,58 @@
+{
+  "usId": "US-17601",
+  "prdId": "PRD-001",
+  "reqId": "REQ-176",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf define freeze runs readiness, refuses on failing, writes freeze.json and prints the section 2.5 summary",
+  "description": "User story under REQ-176. The freeze verb is the only close verb: no change-object is minted, nothing else changes state. It reads the live tree via computeReadiness, refuses on any failing stage (accepting acks only on the three warn-with-ack gates), and writes the freeze record slice 4's bundle --next and slice 5's viewer will read.",
+  "asA": "an operator wrapping up a change on the tree",
+  "iWant": "one command that says 'yes freezeable and I have written the record' or 'no here is the gate that blocks and its first failing ids', accepts --ack on the three warn-first gates with a mandatory reason, and prints a summary line I can paste into a commit message",
+  "soThat": "the freeze record is authoritative for slice 4's bundle --next and slice 5's viewer, and the same rules that gate readiness also gate the freeze",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17601-1",
+      "description": "[happy] rcf define freeze runs computeReadiness once over walkTree(projectRoot) plus loadFreezeRecord and loadAllLedgers. When result.freezeable is true, it writes rcf/define/freeze.json via saveFreezeRecord with these fields: frozenAt (ISO UTC now), treeHash (result.tree.currentTreeHash), docHashes (delta.js currentHashes over the live tree plus 'ledger:<name>' for each ledger present), briefStatements (the count of statements in the brief ledger, ledgers.brief.statements.length or 0), gates (one entry per stage-gate with { state, at: { hash, at, reason?, by? } | null, failing: [{ id, why }] } from the live readiness plus any --ack entries), counts { req, us, ac, acByClass: { happy, edge, failure, mustNot, nonFunctional, unclassified }, tac, interfaces: { <kind>: n, ... }, adr, fbs }, litmus { attestedAt, readers: 0 }, versions { rcfLite, ruleset, schemas } read from package.json, src/ruleset/ruleset.json and node_modules/@stravica-ai/rcf-schemas/package.json, note (--note argument or null), override (always null on a fresh freeze). The verb exits 0. Immediately after the write, calling computeDelta over the live tree + the new freeze reports every list empty (changed / added / removed / briefSince).",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-2",
+      "description": "[failure] When result.freezeable is false and no --ack argument covers the failing stage, the verb exits 4 without writing the freeze record. It prints the failing gates (one per line: '<stage> (<gate>): failing (<first check name>); failing ids: <id1>, <id2>, ...' capped at 20 ids per gate) to stderr, followed by the exact rcf define readiness --check <shortName> command that will re-print the same block for each failing stage. The file at rcf/define/freeze.json is not created or modified (a pre-existing file is byte-identical after the refusal).",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-3",
+      "description": "[failure] --ack <gate> --reason <text> is accepted only for the three warn-with-ack gates: define.shapes / D3 / shapes, define.crosscut / D5 / crosscut, define.consistency / D6 / consistency (the same STAGE_ALIASES readiness accepts). --ack on any other gate name is a usage refusal (exit 2) with a stderr message naming the accepted set. --ack without a matching --reason argument is a usage refusal (exit 2). Multiple --ack / --reason pairs may be passed together (parseArgs multiple: true) as long as the count matches; a mismatch is a usage refusal. An acked gate lands in the written freeze.gates entry as { state: 'acknowledged', at: { hash: <currentTreeHash>, at: <frozenAt>, reason: <text>, by: <freezerId or null> }, failing: [<id>, ...] } and its acknowledgement carries into the next computeReadiness run (which reports the stage state as 'acknowledged').",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-4",
+      "description": "[happy] The stdout summary derived from the delta BEFORE the freeze matches proposal section 2.5: 'frozen at <shortHash>: <n> REQ, <n> stories, <n> criteria, <n> interfaces added; <ids> amended; <impactedFbs> re-execute.' Counts of added come from delta.added grouped by tree.kindById; amended is delta.changed (US ids in the amended list per the proposal's example wording); impactedFbs is delta.impactedFbs. On the first freeze (freeze record absent before the run), the summary is 'first freeze at <shortHash>: <req> REQ, <us> stories, <ac> criteria, <interfaces> interfaces, <tac> TAC, <adr> ADR, <fbs> FBS.' --json emits { record, summary, delta } where record is the just-written freeze record body and delta is the pre-freeze DeltaResult.",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-5",
+      "description": "[happy] --status prints the current record and the live delta summary, exit 0. Text: 'Frozen at <short> on <frozenAt>. Note: <note|(none)>. Counts: <req> REQ / <us> US / <ac> AC / <tac> TAC / <adr> ADR / <fbs> FBS. Acknowledged: <gate1> (\"<reason>\"); <gate2> ...(none). Litmus: attestedAt [<D3>, <D6>], readers <n>. Versions: rcfLite <v> / ruleset <v> / schemas <v>. Override: <null|<reason by at>>.' followed by the live delta summary line: '<changed> changed, <added> added, <removed> removed, <impacted> impacted, <impactedFbs> FBS re-execute.' --status --json emits { record: <freeze body>, delta: <computeDelta output> }. --status when no record exists prints 'never frozen' and exits 0 (--json: { record: null, delta: <computeDelta output over unfrozen tree> }). --status never runs the gates and never writes anything.",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-6",
+      "description": "[happy] The freeze producer is wrapped with runWithAdmissibilityGate the same way readiness is (ADR-4124 carrying ADR-4123): the wrap runs first so the ruleset toolScope guard is honoured, and on a refused-admissibility verdict the CLI prints the refusal envelope to stderr as a [warn] line and the freeze compute still runs and writes if freezeable. The verb never exits 4 solely because of a refused-admissibility verdict.",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-7",
+      "description": "[must-not] src/define/freeze-record.js is updated so validateFreezeRecord REQUIRES the override key (nullable): a body without override throws FreezeRecordError with field 'override'. loadFreezeRecord tolerates older records that lack the key by defaulting to null (never fails on ENOKEY). saveFreezeRecord validates first and refuses to write a body that omits override. Every existing test fixture that omits override still loads (either the loader default fills it in, or a targeted fixture update writes override: null; no legacy fixture becomes unreadable).",
+      "testable": true
+    },
+    {
+      "id": "AC-17601-8",
+      "description": "[non-functional] The src/cli/readiness.js stage header line no longer contains a double-dash: it uses a colon between the stage id and the state label ('D1 (define.brief): failing'). The CHANGELOG.md line 'The regex is now `/\\bTODO:/` -- case-sensitive uppercase `TODO`' is likewise rewritten to a colon. Any golden fixture that captured the old header text is updated. `grep -R ' -- ' src/ test/ CHANGELOG.md` returns no matches under text this slice added or edited (the grep is scoped to added lines; unrelated pre-existing occurrences elsewhere in the tree stay out of scope of the AC).",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4124-define-freeze"],
+  "tags": [],
+  "createdAt": "2026-09-24T16:33:15Z",
+  "updatedAt": "2026-09-24T16:33:15Z"
+}

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

@@ -0,0 +1,55 @@
+{
+  "usId": "US-18001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-180",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Readiness as the first tab in the viewer",
+  "description": "User story under REQ-180. Opening the viewer puts Readiness first (default active tab), the former Overview tab is renamed PRD with its content preserved, the two level verdict pills carry the formatVerdictLines strings as labels, blockers group by persona ordered by the profile.md register (the non-register group collapses with its count visible, never omitted), and the Freeze now control is enabled iff levels.readyToBuild.ok. See the DEFINE step 2 spec dated 2026-10-01 (section 5) for the layout.",
+  "asA": "an operator opening the viewer",
+  "iWant": "Readiness as the first tab with the two verdict pills and persona-grouped blockers",
+  "soThat": "the first thing I see is whether I can build and whose questions stand in the way",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-18001-1",
+      "description": "[happy] Given any project, when the viewer renders, then the first tab is Readiness and the second is PRD with the former Overview content unchanged.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-2",
+      "description": "[happy] Given a failing tree, when the Readiness tab renders, then it shows two verdict pills whose labels equal the formatVerdictLines strings for the same tree.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-3",
+      "description": "[happy] Given personas.productOwner.blockers non-empty, when the tab renders, then each blocker is a findings list headed by its question with its ids as anchor links into the document tabs.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-4",
+      "description": "[happy] Given a profile register of productOwner, when the tab renders, then the product-owner group is expanded first and the engineer group is collapsed with its count visible.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-5",
+      "description": "[must-not] Given any profile register, when the tab renders, then no blocker id of either persona is omitted from the DOM.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-6",
+      "description": "[failure] Given a tree where levels.readyToBuild.ok is false, when the tab renders, then the Freeze now control is disabled and names the failing gates from levels.readyToBuild.blockedBy.",
+      "testable": true
+    },
+    {
+      "id": "AC-18001-7",
+      "description": "[happy] Given the tab and the CLI --json output for the same tree hash, when compared, then every id rendered on the tab appears in the JSON for that hash.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4127-readiness-view"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T18:00:00Z",
+  "updatedAt": "2026-10-01T18:00:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "US-18002",
+  "prdId": "PRD-001",
+  "reqId": "REQ-180",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "the Readiness tab renders question cards grouped by source span",
+  "description": "User story under REQ-180, reserved by DEFINE step 3 spec section 11.8 and authored here by the viewer UI refresh PR 8. The Readiness tab leads with the product owner's three questions in plain words: two VerdictCards from `levels` (Ready for engineers, Ready to build, each with its chain term `intent-complete` or `ready-to-build` muted beside the plain label; both cards rendered at equal height), QuestionCards grouped by source span (one group per blocker; one card per failing item, phrasebook-sourced today, swapping to `readiness.questions[]` when DEFINE step 3 PR 2 ships `computeQuestions`), a what-happens-next paragraph, and a Requirements that still need work table. Every engineer-level finding stays on the page one level down in one collapsed `For engineers` DocRow (closed in the productOwner register, open in engineer; never removed from the DOM). The adapter seam `toQuestions(readiness)` is a pure module reading blockers today and feature-detecting `readiness.questions` tomorrow.",
+  "asA": "a product owner opening the Readiness tab",
+  "iWant": "the questions waiting on me in plain words, grouped by their source span, without ids or stage codes",
+  "soThat": "I can answer them in my own session and see the hand-over state update as I go",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-18002-1",
+      "description": "[happy] given questions[] non-empty, when the tab renders, then the block lists each group with its asks and every id is in the JSON.",
+      "testable": true
+    },
+    {
+      "id": "AC-18002-2",
+      "description": "[failure] given questions[] empty, when the tab renders, then the block shows the intent-complete verdict line.",
+      "testable": true
+    },
+    {
+      "id": "AC-18002-3",
+      "description": "[must-not] given any register, when the tab renders, then the engineer blockers are not removed from the DOM.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4133-readiness-po-layer"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-02T19:30:00Z",
+  "updatedAt": "2026-10-02T19:30:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "US-18101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-181",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Shared pill, findings-list and diff components",
+  "description": "User story under REQ-181. Three view modules land under src/view/components/: pill, findings-list, diff. Readiness is their first consumer; existing Product Map and Requirements rendering keeps its markup where the swap is not mechanical, and no existing test expectation changes in that case. See the DEFINE step 2 spec dated 2026-10-01 (section 5) for the component contract.",
+  "asA": "a maintainer of the viewer",
+  "iWant": "one pill, one findings list and one diff component",
+  "soThat": "gate state, persona, level verdict and AC class read the same on every tab",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-18101-1",
+      "description": "[happy] Given the pill component, when rendered with a gate state, a level verdict, a persona or an AC class, then it emits the same markup shape with a vocabulary class per value.",
+      "testable": true
+    },
+    {
+      "id": "AC-18101-2",
+      "description": "[happy] Given the findings-list component, when called with the same inputs from the Readiness and Product Map callers, then the two call sites produce byte-identical markup.",
+      "testable": true
+    },
+    {
+      "id": "AC-18101-3",
+      "description": "[must-not] Given the shared components, when introduced, then no existing Product Map or Requirements test changes its expected output except where this PR explicitly re-points that tab.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4127-readiness-view"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-01T18:00:00Z",
+  "updatedAt": "2026-10-01T18:00:00Z"
+}