rcf-lite 0.28.2 → 0.28.4

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

@@ -0,0 +1,62 @@
+{
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14:30:00Z",
+  "purpose": "Cover computeReadiness and the rcf define readiness CLI (AC-17501-1..6) with unit tests over fixture trees + a CLI spawn, plus a targeted test of the P3 loadAllLedgers fix.",
+  "testLevel": "unit",
+  "acIds": [
+    "AC-17501-1",
+    "AC-17501-2",
+    "AC-17501-3",
+    "AC-17501-4",
+    "AC-17501-5",
+    "AC-17501-6"
+  ],
+  "id": "TS-217",
+  "usId": "US-17501",
+  "title": "computeReadiness and rcf define readiness CLI",
+  "testCases": [
+    {
+      "id": "TC-217-shape",
+      "acId": "AC-17501-1",
+      "description": "computeReadiness returns { tree, delta, stages, nextAction, coverage, decisions, freezeable } and freezeable is true when every stage state is in { passed, acknowledged, notApplicable }.",
+      "status": "pending",
+      "testPointer": "test/query/readiness.test.js::readiness: returns the section 2.4 shape and freezeable folds correctly"
+    },
+    {
+      "id": "TC-217-fanout",
+      "acId": "AC-17501-2",
+      "description": "Fan-out: computeImpact runs once per id in changed union added; impacted is the deduplicated union; impactedFbs is the subset with kind 'fbs' AND actionNeeded 're-execute'.",
+      "status": "pending",
+      "testPointer": "test/query/readiness.test.js::readiness: fan-out impacted / impactedFbs (frozen delta)"
+    },
+    {
+      "id": "TC-217-coverage",
+      "acId": "AC-17501-3",
+      "description": "coverage.tree is a tree-wide CoverageResult; coverage.delta is one CoverageResult per unique REQ ancestor of the delta ids.",
+      "status": "pending",
+      "testPointer": "test/query/readiness.test.js::readiness: coverage tree-wide and per REQ ancestor"
+    },
+    {
+      "id": "TC-217-next-action",
+      "acId": "AC-17501-4",
+      "description": "nextAction picks the first failing stage in D1..D8 order and the first failing check inside it, listing ids and a rcf define readiness --check <short-name> command; null when no stage is failing.",
+      "status": "pending",
+      "testPointer": "test/query/readiness.test.js::readiness: nextAction picks first failing stage and check"
+    },
+    {
+      "id": "TC-217-cli",
+      "acId": "AC-17501-5",
+      "description": "The CLI prints text summary by default and JSON with --json; --check <stage> exits 4 on blocking failure, 0 with a [warn] on warn-with-ack unacknowledged failure, 0 otherwise; admissibility refusal exits 4.",
+      "status": "pending",
+      "testPointer": "test/cli/readiness.test.js::readiness cli: text output shape and --check exit codes"
+    },
+    {
+      "id": "TC-217-load-all-ledgers",
+      "acId": "AC-17501-6",
+      "description": "loadAllLedgers omits ledgers whose files are absent so computeDelta records no docHash for absent ledgers; a project with only brief-ledger.json sees exactly one ledger:brief docHash.",
+      "status": "pending",
+      "testPointer": "test/define/ledgers.test.js::ledgers: loadAllLedgers omits absent ledger files"
+    }
+  ],
+  "status": "draft"
+}

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

@@ -56,14 +56,14 @@
     },
     {
       "id": "AC-15601-6",
-      "description": "The rule-4 bare-hostname redactor treats filename tokens carrying a known file extension as NOT hostnames. A candidate hostname match whose trailing dot-label is in a bundled FILE_EXTENSIONS set (initially md, mdx, json, yml, yaml, txt, js, mjs, cjs, ts, tsx, html, css, png, svg, sh, csv, log, lock) is left intact and no ledger row is written for it (design amendment R5d). The negative lookbehind on the hostname regex additionally excludes '-' so that filename fragments embedded in a larger identifier (`Backstory-product-brief.md`) cannot start a match after a hyphen. The extension shortlist is merged at call time from an `extensions` array on src/feedback/redact-allowlist.json alongside the existing `hosts` field, so operators can extend it the same way they extend hosts.",
-      "given": "a fixture project with a body containing the tokens 'Backstory-product-brief.md', 'intake.json', 'report.log', 'foo.example.com', 'foo.example.com/path', 'Backstory-example.com', and 'a.b.c'",
+      "description": "The rule-4 bare-hostname redactor treats filename tokens carrying a known file extension as NOT hostnames. A candidate hostname match whose trailing dot-label is in a bundled FILE_EXTENSIONS set (initially md, mdx, json, yml, yaml, txt, js, mjs, cjs, ts, tsx, html, css, png, svg, sh, csv, log, lock) is left intact and no ledger row is written for it (design amendment R5d). The negative lookbehind on the hostname regex additionally excludes '-' so that filename fragments embedded in a larger identifier (`Backstory-product-brief.md`) cannot start a match after a hyphen. The extension shortlist is merged at call time from an `extensions` array on src/feedback/redact-allowlist.json alongside the existing `hosts` field, so operators can extend it the same way they extend hosts. Design amendment R5e (added 0.28.3 per HQ 2026-09-22 ruling on Codex P1-5 deferred from PR #242): candidate hostnames whose trailing dot-label is a single letter are also treated as filename fragments, not hostnames. Rationale: single-letter TLDs are not registrable domains in normal prose and folding them yields more false positives (short identifiers, abbreviated references) than legitimate hostname redactions. Design amendment R5f (added 0.28.3, #243): the rule-3 email regex is bounded so it does not consume the git protocol sentinel `git@<host>` inside a URL whose scheme is `git+ssh://`, `ssh://` or `git://`, nor the bare git-remote shape `git@<host>:<owner>/<repo>` (colon followed by a non-space path). Rationale: `git@<host>` is a URI userinfo construct, not an email; folding it destroys evidence pointers copied from git remotes and clone URLs. Real email addresses in surrounding prose still fold. Design amendment R5g (added 0.28.3, #246): when the operator identity Name (rcf/.identity/profile.md ## Name) is empty, whitespace only, or contains only reserved-noun tokens (RESERVED_IDENTITY_TOKENS from AC-15601-5), buildRedactionContext emits a one-line visible warning to stderr naming the file and stating that identity folding is disabled. The warning is emitted once per redaction context build. Folding still skips (per AC-15601-5) but the operator is no longer left thinking their identity is in force.",
+      "given": "a fixture project with a body containing the tokens 'Backstory-product-brief.md', 'intake.json', 'report.log', 'foo.example.com', 'foo.example.com/path', 'Backstory-example.com', 'a.b.c', the URL 'git+ssh://git@github.com/owner/repo.git#v1.0.0', the URL 'ssh://git@example.internal/owner/repo.git', the bare git remote 'git@github.com:owner/repo.git', and a prose email 'alice@example.com'; and a rcf/.identity/profile.md whose ## Name line is either absent, whitespace only, or reads 'The Agent Operator' (stopword-only)",
       "when": "the redactor runs over the body with the default allowlist",
-      "then": "'Backstory-product-brief.md', 'intake.json' and 'report.log' survive verbatim with no ledger row for a hostname substitution on their basename; 'foo.example.com' folds to <host> via rule 4; 'foo.example.com/path' folds via the URL rule; 'Backstory-example.com' folds to '<host>' (the trailing label is not in the extension set); 'a.b.c' folds to <host>. Extending the allowlist with `extensions: [\"xyz\"]` in redact-allowlist.json (or the operator overlay) makes 'file.xyz' also survive.",
+      "then": "'Backstory-product-brief.md', 'intake.json' and 'report.log' survive verbatim with no ledger row for a hostname substitution on their basename; 'foo.example.com' folds to <host> via rule 4; 'foo.example.com/path' folds via rule 4 bare-host (the URL rule requires a scheme; the token here has none); 'Backstory-example.com' folds to '<host>' (the trailing label is not in the extension set); 'a.b.c' survives verbatim with no hostname ledger row (single-letter trailing label per R5e); 'git+ssh://git@github.com/owner/repo.git#v1.0.0' survives verbatim - the `git@` sentinel is NOT rewritten by the email rule (R5f) and github.com is on the allowlist; 'ssh://git@example.internal/owner/repo.git' has the `git@` sentinel preserved (R5f stash) and the host `example.internal` folded to '<host>' by the extended URL rule 4 which now matches ssh/git+ssh/git schemes with optional userinfo; 'git@github.com:owner/repo.git' has the `git@` sentinel preserved (R5f) and github.com is on the allowlist so it survives verbatim; 'alice@example.com' in surrounding prose still folds to '<email>' (rule 3 email); and when the identity Name is empty/whitespace/stopword-only, stderr carries exactly one visible warning line naming rcf/.identity/profile.md and stating that identity folding is disabled. Extending the allowlist with `extensions: [\"xyz\"]` in redact-allowlist.json (or the operator overlay) makes 'file.xyz' also survive.",
       "testable": true,
       "scope": "runtime"
     }
   ],
   "createdAt": "2026-09-16T13:45:23.000Z",
-  "updatedAt": "2026-09-17T13:47:03Z"
+  "updatedAt": "2026-09-22T13:07:00Z"
 }

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

@@ -0,0 +1,27 @@
+{
+  "usId": "US-17001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: shape grouping",
+  "description": "User story under REQ-170. a product reader reviewing the requirements chain the Product Map tab to bucket requirements by shapeClassification.shapes[], with an \"Unclassified\" bucket for REQs missing the classification and a \"Business rules\" bucket for the \"none\" shape",
+  "asA": "a product reader reviewing the requirements chain",
+  "iWant": "the Product Map tab to bucket requirements by shapeClassification.shapes[], with an \"Unclassified\" bucket for REQs missing the classification and a \"Business rules\" bucket for the \"none\" shape",
+  "soThat": "I can see at a glance which requirements sit in each surface area (webUi, httpApi, auth, persistence, notifications, business rules) without reading every REQ body",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17001-1",
+      "description": "The rendered review-surface HTML carries a \"product-map\" tab (data-tab=\"product-map\") in tab order after Build sequence, with a hidden tabpanel id \"tab-product-map\" containing a shape-grouping section whose bucket headings enumerate every shape the classified REQs use plus \"Unclassified\" and \"Business rules\". A REQ classified into two shapes appears in both buckets. Rendering does not require a schema change.",
+      "testable": true
+    },
+    {
+      "id": "AC-17001-2",
+      "description": "Selecting the shape grouping drills each bucket to its REQs (rendered with the same doc-details helper and status pill as the Requirements tab), each REQ to its user stories, and each user story to its acceptance criteria, so the reader can go from a shape bucket to an AC in the same tab. Grouping button clicks and status filter changes push a new history entry (Back/Forward traverse them); top-level tab clicks keep their existing behaviour.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:43:06.307Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17002",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: status filter",
+  "description": "User story under REQ-170. a reviewer preparing a sign-off pass a status filter (all, draft, review, needsRevision, approved, superseded) on the Product Map tab that applies to whichever grouping is active",
+  "asA": "a reviewer preparing a sign-off pass",
+  "iWant": "a status filter (all, draft, review, needsRevision, approved, superseded) on the Product Map tab that applies to whichever grouping is active",
+  "soThat": "I can narrow the tab to just the \"approved\" or just the \"needsRevision\" REQs without switching tabs or scanning by hand",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17002-1",
+      "description": "The Product Map tab carries a status filter control whose options are the five authoring statuses plus \"all\", and applies to every grouping on the tab. When \"approved\" is selected the tab renders only REQs whose status is approved. Buckets that become empty under the current filter are hidden by default with a summary line (\"N empty\" - clicking reveals them), so the map keeps its shape without rendering a wall of empty headings.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T18:36:17.135Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17003",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: component-first grouping",
+  "description": "User story under REQ-170. a technical reviewer wanting to see requirements from the architecture down a component grouping rooted at the TAD, showing each TAC (with its dependencies) at level 1, the user stories linked to that TAC at level 2, each story's parent REQ at level 3, and its ACs at level 4, plus an \"Unmapped\" bucket for REQs no component reaches",
+  "asA": "a technical reviewer wanting to see requirements from the architecture down",
+  "iWant": "a component grouping rooted at the TAD, showing each TAC (with its dependencies) at level 1, the user stories linked to that TAC at level 2, each story's parent REQ at level 3, and its ACs at level 4, plus an \"Unmapped\" bucket for REQs no component reaches",
+  "soThat": "I can pivot from a component to the requirements it delivers without leaving the tab",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17003-1",
+      "description": "When the Product Map is grouped by component, the tab renders the TAD as the root, one section per TAC (with a short dependencies[] list drawn from the TAC document), then the user stories under that TAC (from usByTacId), then their parent REQs (from us.reqId), then the ACs. REQs reachable by no TAC are collected under an \"Unmapped\" bucket with a count in its heading.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17004",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: trace-coverage grouping",
+  "description": "User story under REQ-170. a reviewer about to sign a chain off a trace-coverage grouping that buckets each REQ by chain completeness (complete, missing stories, missing AC scope or owner, missing component owner, missing tests)",
+  "asA": "a reviewer about to sign a chain off",
+  "iWant": "a trace-coverage grouping that buckets each REQ by chain completeness (complete, missing stories, missing AC scope or owner, missing component owner, missing tests)",
+  "soThat": "I can see which requirements are safe to sign off and which still need work",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17004-1",
+      "description": "The trace-coverage grouping buckets each REQ into one of complete | missing-stories | missing-ac-scope | missing-component | missing-tests, computed from the tree-model maps (storiesByReqId, acIdsByUsId, usByTacId, tsByAcId / tcsByAcId / fbsByAcId). Each REQ row states in plain text exactly what is missing, and links to its own doc anchor so the reader can jump to it.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,22 @@
+{
+  "usId": "US-17005",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: capability grouping",
+  "description": "User story under REQ-170. a product reader thinking in capabilities rather than technical shape a capability grouping that reads capability:<slug> entries from REQ.tags[] and buckets requirements per capability",
+  "asA": "a product reader thinking in capabilities rather than technical shape",
+  "iWant": "a capability grouping that reads capability:<slug> entries from REQ.tags[] and buckets requirements per capability",
+  "soThat": "I can see the product as a set of capabilities and drill into each capability's REQs, stories and ACs",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17005-1",
+      "description": "The capability grouping enumerates one bucket per distinct capability:<slug> value present on any REQ across the tree. A REQ carrying multiple capability tags appears under each. REQs whose tags carry no capability:<slug> entry are collected under an \"Unclassified\" bucket. Slugs are rendered as their kebab form in the heading; named capability buckets are ordered by REQ count desc, then alphabetically, and the Unclassified bucket is always pinned last.",
+      "testable": true
+    }
+  ],
+  "tags": [],
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:43:06.511Z"
+}

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

@@ -0,0 +1,21 @@
+{
+  "createdAt": "2026-09-21T18:36:23.922Z",
+  "updatedAt": "2026-09-21T18:36:52.280Z",
+  "description": "a product reader who returns to the tab across sessions collapsed-by-default buckets, a jump-nav index across the top, per-bucket status mini-counts, hash-encoded open buckets so a bookmarked URL restores tab plus grouping plus filter plus open buckets, and compact REQ cards with drill-down (raw JSON stays on the Requirements tab), so the tab scans in under a minute and survives a live-refresh with open state intact",
+  "usId": "US-17006",
+  "prdId": "PRD-001",
+  "reqId": "REQ-170",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Product Map: usable interaction model",
+  "asA": "a product reader who returns to the Product Map across sessions",
+  "iWant": "collapsed-by-default buckets, a jump-nav index across the top, per-bucket status mini-counts, hash-encoded open-bucket state and compact REQ cards with drill-down (raw JSON stays on the Requirements tab)",
+  "soThat": "the tab scans in under a minute and a bookmarked URL restores tab, grouping, filter and the buckets I had open, and my open state survives a live refresh",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17006-1",
+      "description": "The Product Map tab renders every bucket collapsed by default, with a summary row carrying the bucket label, its total REQ count and a mini count per authoring status (draft / review / needsRevision / approved / superseded). A jump-nav rail across the top of the panel lists every bucket in the active grouping with its count; clicking a chip scrolls to that bucket and opens it. The hash schema `#tab=product-map&group=<g>&status=<s>&open=<id1>,<id2>` restores tab, grouping, status filter AND the set of open buckets on return, and every bucket-toggle pushes a new history entry so Back/Forward traverse them. Per-bucket <details> nodes carry a stable data-doc-id (\"pm-bucket:<group>:<id>\") so the live-client persists their open state across SSE refreshes.",
+      "testable": true
+    }
+  ]
+}

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-17401.json

@@ -0,0 +1,58 @@
+{
+  "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
+    }
+  ],
+  "tacIds": ["TAC-4122-define-gates"],
+  "tags": [],
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14: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/releases/releases.yaml

@@ -40,8 +40,28 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.28.2"
+latest: "0.28.4"
 releases:
+  - version: "0.28.4"
+    date: "2026-09-30"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.4 fixes user story minting on legacy trees that carry flat sequential ids. On a tree migrated in from a v1 project, minting a new user story under a requirement now extends the flat sequence (US-163 to US-164) instead of jumping to an encoded slot such as US-5301; a tree that mixes both id shapes is refused with a message naming one example of each so the operator can normalise it first. Acceptance criteria minting is unchanged."
+      - "The 0.28.3 fixes ship in this release, because 0.28.3 was written up on 22 September but never tagged or published. Those are the feedback redactor no longer folding git protocol sentinels as emails, a visible warning when identity folding is disabled, and the live-view server snapshotting its static assets at startup."
+      - "The DEFINE workflow foundations arrive ahead of the 0.29.0 train: delta detection, freeze records, four sidecar ledgers with rcf define ledger, stage gates D1 to D8, and rcf define readiness, plus the Product Map tab on the review surface."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.28.3"
+    date: "2026-09-22"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.28.3 is a small batched fix release for the residuals Dex's 0.28.2 round-trip surfaced and one HQ-side viewer bug caught the same day. The feedback redactor no longer folds the git protocol sentinel git@<host> inside git+ssh, ssh or git URLs as an email, so an evidence pointer copied verbatim from a git remote or clone URL survives as evidence. Bare git remotes and single-letter trailing labels like a.b.c are also protected as URI userinfo and filename fragments; real emails in surrounding prose still fold."
+      - "The redactor emits a visible stderr warning when identity folding is disabled, so an operator whose rcf/.identity/profile.md is missing, empty, a placeholder, or contains only reserved nouns is no longer left thinking their identity is in force when it silently is not. Feedback status --json now exposes the destination source field the preview surface already prints, and --evidence pointers now render with the label matching their shape (command / path:line / id) rather than always (command)."
+      - "The live-view server snapshots its shipped static assets (style.css, mermaid.min.js, live-client.js) at startup instead of reading them from disk per request, so a checkout branch switch during the server's lifetime can no longer silently change the served CSS."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.28.2"
     date: "2026-09-22"
     breaking: false