rcf-lite 0.28.2 → 0.29.0

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

@@ -0,0 +1,21 @@
+{
+  "createdAt": "2026-09-21T18:36:34.519Z",
+  "updatedAt": "2026-09-21T18:36:52.512Z",
+  "description": "a reviewer opening the review surface on a slow link the initial HTML payload well under 3 MB by rendering only the active grouping fully; the other three groupings emit only their bucket headings (label + count) and hydrate the REQ list on demand when the reader switches grouping or opens a bucket, so first paint is fast and the tab stays interactive on 100+ REQ trees",
+  "usId": "US-17007",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: lazy first-load payload",
+  "asA": "a reviewer opening the review surface on a slow link",
+  "iWant": "an initial HTML payload well under 3 MB by rendering only the active grouping fully and hydrating the other groupings on demand from a partial endpoint",
+  "soThat": "first paint is fast and the tab stays interactive on 100-plus REQ trees",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17007-1",
+      "description": "The Product Map first-load payload target is well under 3 MB. The server emits the shape (default) grouping fully; the other three groupings emit only their bucket headings (label + total count + per-status mini counts) and each bucket carries a data-pm-lazy marker naming its grouping and bucket id. When the reader switches to a lazy grouping OR opens a lazy bucket, the client fetches that grouping fully once (from a partial endpoint the server exposes) and hydrates the bucket into the DOM; subsequent switches use the cached partial. The pass doc states the before/after first-load bytes.",
+      "testable": true
+    }
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17008",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: blueprint badge and by-blueprint grouping",
+  "description": "User story under REQ-170. a product reader auditing what came from applied blueprints vs the project's own requirements a visible blueprint badge on every REQ row an applied blueprint contributed, plus a sixth grouping that buckets requirements by contributing blueprint (with an Application bucket for the project's own (non-blueprint) REQs) and a second-level capability split inside each bucket.",
+  "asA": "a product reader auditing what came from applied blueprints vs the project's own requirements",
+  "iWant": "a blueprint badge on every REQ row that was contributed by a blueprint plus a by-blueprint grouping (one bucket per applied blueprint plus an Application bucket) with capability as the second level inside each bucket",
+  "soThat": "I can see at a glance which parts of the tree ride on shared blueprints and which the project owns, and drill from a blueprint to the capabilities it contributed",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17008-1",
+      "description": "Every REQ row inside the Product Map tab that was contributed by an applied blueprint carries a compact blueprint badge (class pm-blueprint-badge) in its summary row, in every grouping (shape, component, trace coverage, capability, and the new by-blueprint grouping itself). The GROUPINGS list on the panel additionally includes 'blueprint'; the by-blueprint grouping enumerates one bucket per entry in manifest.blueprints[] (label: the blueprint's display name or slug, count: number of contributed REQs) plus an Application bucket for the project's own (non-blueprint) REQs (REQs with no blueprint attribution). Inside each blueprint or Application bucket, requirements are split by capability (existing capability:<slug> convention) as a second level, then the usual REQ->US->AC drill-down. The source of truth for blueprint attribution is manifest.blueprints[].contributions[] (parsed by scope.contributionsForBlueprint); the id-prefix fallback (kebab-slug prefix on reqId) is used only when the manifest carries no contributions record for a given blueprint. The hash schema round-trips as #tab=product-map&group=blueprint&status=<s>&open=<ids>, and the /product-map/blueprint partial endpoint serves the grouping body for the client's lazy-render fetch. A project with no applied blueprints renders a single Application bucket cleanly (not an error, not an empty tab).",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-22T11:59:39Z",
+  "updatedAt": "2026-09-22T15:00:00Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-171",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Dogfood chain carries capability tags on every requirement",
+  "description": "User story under REQ-171. the maintainer of the rcf-lite dogfood chain every REQ under rcf-lite/rcf to carry at least one capability:<slug> tag drawn from the documented taxonomy",
+  "asA": "the maintainer of the rcf-lite dogfood chain",
+  "iWant": "every REQ under rcf-lite/rcf to carry at least one capability:<slug> tag drawn from the documented taxonomy",
+  "soThat": "the by-capability Product Map view has something to bucket on, and the trial can be evaluated against real data rather than a fixture",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17101-1",
+      "description": "Every REQ under packages/rcf-lite/rcf/requirements/ carries at least one tag matching the regex ^capability:[a-z0-9]+(-[a-z0-9]+)*$, and every slug used maps to an entry in the documented capability taxonomy.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-171",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Capability taxonomy is documented in the rcf-lite docs",
+  "description": "User story under REQ-171. a reader of the rcf-lite docs deciding whether to adopt the convention the capability:<slug> convention, the initial taxonomy and the rule for adding a new capability documented alongside the rest of the rcf-lite docs",
+  "asA": "a reader of the rcf-lite docs deciding whether to adopt the convention",
+  "iWant": "the capability:<slug> convention, the initial taxonomy and the rule for adding a new capability documented alongside the rest of the rcf-lite docs",
+  "soThat": "a new capability is added deliberately rather than by drift, and a reader can look up what each slug means",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17102-1",
+      "description": "packages/rcf-lite/docs contains a capability tags section listing every slug in the initial taxonomy with a one-line meaning, plus the rule for adding a new capability (single-word verb or noun, kebab-case, must map to a product surface). The section is linked from docs/README.md so it is reachable from the docs entry point.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,38 @@
+{
+  "usId": "US-17201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-172",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Delta detection and freeze record land as reusable primitives",
+  "description": "User story under REQ-172. The detection-model foundation lands as pure, importable modules and one durable local record.",
+  "asA": "the maintainer of a rcf-lite tree",
+  "iWant": "hashDocument, computeTreeHash, computeDelta and the rcf/define/freeze.json reader/writer to land as pure modules exposed on the query surface, with a documented return shape that later DEFINE slices can call unchanged",
+  "soThat": "the gates, readiness view, freeze verb and bundle-side read all consume the same detection primitives, and a hand reformat of a document never surfaces as a change",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17201-1",
+      "description": "computeDelta(tree, freeze, ledgers) returns the exact object shape proposal 2026-09-22 v3 section 2.2 specifies (frozen, frozenAt, treeHash, currentTreeHash, changed, added, removed, briefSince, unchanged); given a matching freeze the delta reports empty changed / added / removed and unchanged equal to the number of docHashes; given divergent tree state changed / added / removed classify every id correctly against the freeze record.",
+      "testable": true
+    },
+    {
+      "id": "AC-17201-2",
+      "description": "hashDocument returns a sha256:<64-hex> string over the canonical JSON form of the parsed document (keys sorted recursively, no whitespace), and is invariant under a whitespace-only reformat or a key reorder: two documents that parse to the same object hash identically.",
+      "testable": true
+    },
+    {
+      "id": "AC-17201-3",
+      "description": "Loading rcf/define/freeze.json when the file is absent returns null; loading a malformed file (bad JSON, missing docHashes, non-sha256 hash value, negative briefStatements) raises FreezeRecordError with a code (parseFailure or schemaFailure) and a named field so a caller can log the exact failure.",
+      "testable": true
+    },
+    {
+      "id": "AC-17201-4",
+      "description": "Saving then loading a freeze record round-trips every documented field including extension fields the schema does not police (counts, litmus, versions, note), and saveFreezeRecord refuses to persist an invalid record: no file is written on validation failure.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4120-define-delta-and-freeze"],
+  "tags": [],
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,38 @@
+{
+  "usId": "US-17301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-173",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf define ledger reads and writes the four sidecars under rcf/define/",
+  "description": "User story under REQ-173. The operator-facing CLI for the four sidecar ledgers lands with add / resolve / list on every ledger name.",
+  "asA": "an operator staging or reviewing a DEFINE change",
+  "iWant": "rcf define ledger to author brief statements, decisions, concern dispositions and probe findings under rcf/define/ with numbered ids stable for the life of the project, and to leave every ledger invisible to the walker",
+  "soThat": "the freeze record's high-water mark, the D7 decisions list, D5 concern coverage and D6 probe findings all have a written record and every later DEFINE slice reads the same seam without discovering a second source of truth",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17301-1",
+      "description": "rcf define ledger brief add --kind <k> --text <t> appends a numbered statement to rcf/define/brief-ledger.json, mints the next id (highest current + 1), stamps status open and addedAt (ISO-8601), refuses an unknown kind with a usage-class error, and refuses --text combined with --from with a usage-class error.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-2",
+      "description": "rcf define ledger decisions list prints the numbered #241 format: one decision per item (id. question), options rendered as 'letter) text', the default letter labelled 'default:', and what it blocks labelled 'blocks:'. rcf define ledger <name> list --json emits the machine-readable envelope { ledger, <arrayKey>: [...] }.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-3",
+      "description": "rcf define ledger brief add --from <file> reads the file, splits it into one statement per non-empty line (stripping leading '- ', '* ' or '<n>. ' bullets), mints sequential ids for every statement, refuses if the file produced zero non-empty lines, and stamps the file path as source unless --source overrides it. The intake-scan-against-frozen-statements hook is a named seam in the writer, not called in this slice.",
+      "testable": true
+    },
+    {
+      "id": "AC-17301-4",
+      "description": "walkTree run over a project that carries rcf/define/freeze.json, all four ledger files, and a bug-bait file named req-999.json under rcf/define/ never surfaces any rcf/define/ file as a tree.byId document and reports no walker error naming a rcf/define/ path. The sidecar directory is invisible to every consumer of walkTree.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4121-define-ledgers"],
+  "tags": [],
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,70 @@
+{
+  "usId": "US-17401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-174",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Stage gates land as pure check functions with per-stage state",
+  "description": "User story under REQ-174. Eight stage-gate check functions land in src/query/gates.js with a stable per-stage return shape that computeReadiness and every later slice can consume unchanged.",
+  "asA": "a downstream consumer of DEFINE gates (readiness, freeze, viewer)",
+  "iWant": "gates.js to expose one pure check function per stage D1..D8, each returning a { stage, gate, state, checks[] } object with checks in the { name, ok, over: 'delta'|'tree', pass, total, failing: [{ id, why }] } shape",
+  "soThat": "computeReadiness composes the eight checks, the freeze verb refuses on any failing state, and the viewer's Readiness tab prints the same rows the CLI does with no schema translation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17401-1",
+      "description": "src/query/gates.js exports one check function per stage D1..D8 (checkD1Brief, checkD2Skeleton, checkD3Shapes, checkD4Stories, checkD5Crosscut, checkD6Consistency, checkD7Decisions, checkD8Freeze), each taking (tree, { ledgers, profile, scope, freeze, delta, validateErrors, probeOpenCount, coverageTree }) and returning { stage, gate, state, checks[] }; every entry in checks is { name, ok, over: 'delta'|'tree', pass, total, failing: [{ id, why }] } (failing empty on ok).",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-2",
+      "description": "Blocking stages in 0.29.0 (D1, D2, D4, D7, D8) report state 'passed' when every check ok is true, 'failing' when any check ok is false; warn-with-ack stages (D3, D5, D6) report 'passed' when every check ok is true, 'failing' when any check ok is false and the freeze record does NOT acknowledge that gate at the current tree hash, and 'acknowledged' when the freeze.gates[<gate>] entry names state 'acknowledged' and at.hash === currentTreeHash and any check ok is false.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-3",
+      "description": "notApplicable is decided per stage per proposal section 3.2: D2 notApplicable when no statement of a resolving kind (capability, constraint, entity, actor, externalSystem, surface) is in the delta AND no REQ, PRD or TAD is in scope; D3 notApplicable when no TAC and no shaped REQ (httpApi/persistence/auth) is in scope; D5 notApplicable when no REQ is in scope; D7 notApplicable when no open decisions exist AND the profile sets skipReviewFor: singleDocument AND the delta holds exactly one document; D4 and D6 use their own rules; D1 and D8 never notApplicable.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-4",
+      "description": "checkD4Stories enforces the D4 floors: every REQ in scope has a US (fail: 'no owning user story'), every US in scope has a testable AC ('missing testable AC'), a failure AC (parsed by the bracketed [failure] prefix on AC description) or a reasoned opt-out per class (manifest.baselineAcOptOuts[] entry with baselineKey 'defineD4:failure' and matching scope), a must-not AC (parsed by [must-not] prefix) or a reasoned opt-out per class (baselineKey 'defineD4:mustNot'), tacIds non-empty and every named tac resolving to a real TAC, and no AC description contains the scaffold TODO placeholder.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-5",
+      "description": "checkD3Shapes runs only cheap data-backed checks in 0.29.0: every TAC in scope has at least one interface (fail: 'no interfaces authored'), and every interface's kind is in the closed vocabulary { recordShape, httpRoute, event, cliCommand, uiRoute, port, fileFormat, fixture, other } (fail: 'unknown interface kind <k>'). The template parser, entity-name join, ownerRef and path resolution are named seams (not called this slice) and D3 stays warn-with-ack.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-6",
+      "description": "checkD5Crosscut runs only cheap data-backed checks in 0.29.0: TAD.securityArchitecture non-empty when the tree carries any REQ whose shapeClassification.shapes includes 'auth' or 'httpApi'; TAD.operationalConcerns non-empty when any AC description carries the '[deployed]' marker (a cheap presence signal proposal section 3.2 D5 lists as 'deployed-scope AC'); concern-ledger entries in scope disposed as 'applied' or 'waived' (no dangling 'open' concerns on REQs in scope). The full catalogue and per-pair enumeration are named seams for 0.30.",
+      "testable": true
+    },
+    {
+      "id": "AC-17401-7",
+      "description": "checkD6Consistency runs only cheap data-backed checks in 0.29.0: validate is clean tree-wide (validateErrors is empty; the caller passes the walker + validator's error list), and probe-ledger holds zero 'open' probe entries. Contradiction-lite, unsatisfiable-lite, duplicates and orphan-interface scans, plus the probe runner, are named seams for 0.30.",
+      "testable": true
+    },
+    {
+      "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"
+  ],
+  "tags": [],
+  "createdAt": "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-17501.json

@@ -0,0 +1,48 @@
+{
+  "usId": "US-17501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-175",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "computeReadiness and rcf define readiness render the same object",
+  "description": "User story under REQ-175. computeReadiness lands as a pure module and rcf define readiness as its CLI twin. The viewer's Readiness tab (slice 5) will render the same object with no schema translation.",
+  "asA": "an operator asking 'can I build, and if not what is in the way'",
+  "iWant": "one pure compute that composes delta, fan-out, gates, coverage and decisions into a single object, and one CLI that prints it in a compact form or emits it as JSON",
+  "soThat": "the tree line, next action, stage chips, delta list and failing items are the same wherever they are shown, and slice 3's rcf define freeze refuses on the same freezeable flag the CLI reports",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17501-1",
+      "description": "computeReadiness(tree, { freeze, ledgers, profile, testPointers }) returns the exact section 2.4 shape: tree { frozen, frozenAt, treeHash, currentTreeHash, buildAt, fbsTotal }, delta { changed, added, removed, briefSince, impacted, impactedFbs }, stages [{ stage, gate, state, checks }], nextAction { stage, check, ids, command } or null, coverage { tree, delta }, decisions [...open in #241 format], freezeable boolean. freezeable is true when every stage state is 'passed', 'acknowledged' or 'notApplicable'.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-2",
+      "description": "Fan-out is computed by calling computeImpact once per id in the union of changed and added; impacted is the union of every impact node id excluding the pivots; impactedFbs is the subset whose kind is 'fbs' and actionNeeded is 're-execute'. Gates run over scope = changed union added union impacted (with duplicates removed).",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-3",
+      "description": "Coverage is tree-wide plus per REQ ancestor of the delta: coverage.tree is computeCoverage(tree, { testPointers, strict: true }) once over the whole tree; coverage.delta is an array with one CoverageResult per unique REQ id reachable by walking back from every delta id (changed union added) through parentByChild until the reqId is found, using scopeId per invocation. testPointers is the map the CLI produced with resolveTestPointers.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-4",
+      "description": "nextAction picks the first stage in D1..D8 order whose state is 'failing', then the first failing check in that stage's checks[] (or the check with the largest failing.length when tie); it names the stage id, the check name, the failing ids (deduped), and a command string like 'rcf define readiness --check <stage-short-name> after editing'. nextAction is null when every stage is passed / acknowledged / notApplicable.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-5",
+      "description": "rcf define readiness prints a text summary: the tree line ('Frozen at <shortHash> on <frozenAt>. N documents changed since, M impacted. Build at <fbsId> of <total>; K FBS impacted.' or 'Unfrozen. N documents; the whole tree is the delta.'), the next action line, a chip line 'D1:passed D2:failing D3:acknowledged D4:notApplicable ...', and the failing-items list per stage. --json emits the full computeReadiness object under `${JSON.stringify(result, null, 2)}\\n`. --check <stage> (D1..D8 or short name brief|skeleton|shapes|stories|crosscut|consistency|decisions|freeze) prints only that stage and exits 0 when its state is 'passed' or 'acknowledged' or 'notApplicable', exit 4 on 'failing' for blocking stages (D1, D2, D4, D7, D8), exit 0 with a visible '[warn]' line on 'failing' for warn-with-ack stages (D3, D5, D6). The verb wraps its producer with runWithAdmissibilityGate and, on admissibility refusal, prints the refusal on stderr and exits 4.",
+      "testable": true
+    },
+    {
+      "id": "AC-17501-6",
+      "description": "loadAllLedgers({ projectRoot }) returns a LedgerBundle that OMITS a ledger key when the sidecar file does not exist (ENOENT), so computeDelta records no docHash for absent ledgers; the docstring on computeDelta (LedgerBundle typedef) and the loader implementation agree. A project that has authored a brief ledger and no others sees exactly one 'ledger:brief' entry in the delta docHashes; a project that has authored no ledgers sees zero 'ledger:*' entries.",
+      "testable": true
+    }
+  ],
+  "tacIds": ["TAC-4123-define-readiness"],
+  "tags": [],
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14: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"
+}