rcf-lite 0.28.4 → 0.30.0

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 a tree with an unacknowledged D3 bite failure, when the verb runs, then it exits 4 (ADR-4131 bite); given --check all on a tree where only D5 or D6 fail without an ack, then it exits 0 with a stderr [warn] line (warn-with-ack posture preserved until PRs 6 and 7). (Amended by DEFINE step 3 PR 5 under ADR-4131; superseded prior wording: '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-03T12:10:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "US-17504",
+  "prdId": "PRD-001",
+  "reqId": "REQ-175",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "probe seam and litmus",
+  "description": "User story under REQ-175 for DEFINE step 3 PR 7 (spec section 4 row 'D6 scans and the injectable probe runner' and section 11.6). computeReadiness(tree, { probeRunner }) accepts an injectable runner where probeRunner = ({ reqId, tree }) => findings[], default null; injected findings land as probe-ledger entries in the result and count toward consistency:probeCount. src/define/probe-runner.js is added as the seam only; no shipped runner (no LLM in rcf-lite; the harness is the runner through ledger probes add). With no probeRunner the result equals the 0.29.0 result on the same fixture. --litmus <n> on readiness and freeze requires at least n distinct litmus readings at the current LITMUS HASH, read from probe-ledger entries with finding beginning litmus:<reader>: and a hash matching tree.litmusHash; one reader exits 4 naming the shortfall. The litmus hash is the tree hash computed with the probes ledger excluded (ADR-4131 extended R9, w-2026-10-03-dave-011): the probes ledger is inside tree.currentTreeHash by ADR-4120, so a reader writing a probe-ledger entry that referenced currentTreeHash would shift the hash it just attested to; the litmus hash is the content-stable hash readers pin to so n readers can land their entries at the same hash. Writes to the brief, decisions or concerns ledgers do shift the litmus hash the same way they shift currentTreeHash. Trade-off: litmus readings do not attest to probe findings written after them, which is acceptable because probe entries are themselves readings. --litmus-attested remains the default attestation path. No process is spawned and no network call is made at runtime; the harness is the runner.",
+  "asA": "an engineer",
+  "iWant": "an injectable probeRunner seam on computeReadiness and a --litmus <n> flag on readiness and freeze that counts recorded litmus probe entries at the current litmus hash (the tree hash excluding the probes ledger)",
+  "soThat": "the harness can land fresh-context readings through the probe ledger and rcf-lite exits 4 until n distinct readers have attested at the current hash, without rcf-lite itself calling an LLM or spawning a process",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17504-1",
+      "description": "[happy] given a probeRunner returning two findings for REQ-003, when computeReadiness runs, then both appear as open probe entries in the result and consistency:probeCount fails.",
+      "testable": true
+    },
+    {
+      "id": "AC-17504-2",
+      "description": "[happy] given no probeRunner, when computeReadiness runs, then the result equals the 0.29.0 result on the same fixture.",
+      "testable": true
+    },
+    {
+      "id": "AC-17504-3",
+      "description": "[happy] given two probe entries litmus:<reader>: at the current litmus hash (the tree hash excluding the probes ledger) from distinct readers, when readiness --litmus 2 runs, then it passes the litmus requirement.",
+      "testable": true
+    },
+    {
+      "id": "AC-17504-4",
+      "description": "[failure] given one reader at the current litmus hash (the tree hash excluding the probes ledger), when readiness --litmus 2 runs, then it exits 4 naming the shortfall.",
+      "testable": true
+    },
+    {
+      "id": "AC-17504-5",
+      "description": "[must-not] given --litmus, when readiness runs, then no process is spawned and no network call is made.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4123-define-readiness",
+    "TAC-4128-define-guidance"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-03T16:10:00Z",
+  "updatedAt": "2026-10-03T16:10: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-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-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"
+}

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

@@ -0,0 +1,40 @@
+{
+  "usId": "US-18202",
+  "prdId": "PRD-001",
+  "reqId": "REQ-182",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "the DEFINE-stage guidance pack",
+  "description": "User story under REQ-182. The guidance pack prints its slugs through `rcf guidance`, the MCP server advertises every argument-free DEFINE prompt, the register scan protects every new file from em-dashes, and the managed block regeneration never removes an existing rule.",
+  "asA": "harness",
+  "iWant": "the DEFINE-stage guidance pack served through one surface",
+  "soThat": "the loop reads one slug per topic and the register scans and managed-block rules apply everywhere",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-18202-1",
+      "description": "[happy] given the pack, when rcf guidance define-intent and rcf guidance discovery-prototypes run, then each prints its file.",
+      "testable": true
+    },
+    {
+      "id": "AC-18202-2",
+      "description": "[happy] given the manifest, when the MCP server lists prompts, then rcf_define_intent, rcf_define_intake, rcf_define_draft_shapes, rcf_define_litmus and rcf_discover_prototype are present and argument-free.",
+      "testable": true
+    },
+    {
+      "id": "AC-18202-3",
+      "description": "[failure] given a new guidance file containing an em-dash, when the register scan runs, then it fails.",
+      "testable": true
+    },
+    {
+      "id": "AC-18202-4",
+      "description": "[must-not] given the managed block, when regenerated, then no existing rule is removed.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4128-define-guidance"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-03T00:00:00Z",
+  "updatedAt": "2026-10-03T00:00:00Z"
+}

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

@@ -0,0 +1,55 @@
+{
+  "usId": "US-18601",
+  "prdId": "PRD-001",
+  "reqId": "REQ-186",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "the question set",
+  "description": "User story under REQ-186. computeQuestions turns every failing product-owner item into one plain question with its write-back, so the harness can ask without reading gate internals.",
+  "asA": "harness serving a product owner",
+  "iWant": "computeQuestions to turn every failing product-owner item into one plain question with its write-back",
+  "soThat": "I can ask without reading gate internals",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-18601-1",
+      "description": "[happy] given a tree where brief:openQuestions, skeleton:resolvedBy and stories:reqHasUs each fail at least one item, when computeQuestions runs with persona productOwner, then questions[] holds exactly one entry per failing item with id, stage, check, itemId, heading, ask, answerKinds, writeBack and blocks intent.",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-2",
+      "description": "[happy] given the same tree, when computeQuestions runs twice, then the two questions[] arrays are deep-equal and ordered D1, D2, D4, D7 then by source span.",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-3",
+      "description": "[happy] given an open decision with two options and a default, when computeQuestions runs, then it appears in optional[] with blocks build and not in questions[].",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-4",
+      "description": "[happy] given a tree where levels.intentComplete.ok is true, when computeQuestions runs with persona productOwner, then questions[] is empty and ok is true.",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-5",
+      "description": "[happy] given persona engineer, when computeQuestions runs, then questions[] holds one entry per failing engineer item in failing stages and blocks is build.",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-6",
+      "description": "[failure] given a persona value outside productOwner and engineer, when computeQuestions runs, then it throws a usage error naming the accepted values.",
+      "testable": true
+    },
+    {
+      "id": "AC-18601-7",
+      "description": "[must-not] given any tree, when computeQuestions runs, then no file under rcf/ is created or modified and no question carries a writeBack command whose verb is not registered in the CLI help.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4129-define-questions"
+  ],
+  "tags": [],
+  "createdAt": "2026-10-02T18:00:00Z",
+  "updatedAt": "2026-10-02T18:00:00Z"
+}