rcf-lite 0.28.1 → 0.28.4

package/CHANGELOG.md

@@ -6,6 +6,316 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.28.4] - 2026-09-30
+
+Note: 0.28.3 (2026-09-22 below) was never tagged or published; its entries ship in 0.28.4 together with the ones here.
+### Added
+
+- **Product Map tab on the review surface (#238).** Merged on `main` at
+  `ab35dd7d`; grouped by shape, component, trace coverage, capability,
+  blueprint. This entry backfills the changelog now that the following
+  DEFINE-train slice rides on top of it.
+- **DEFINE workflow: delta detection foundation (REQ-172, slice 1 of
+  the 0.29.0 train).** New pure module `src/query/delta.js` exports
+  `hashDocument`, `computeTreeHash` and `computeDelta`. `hashDocument`
+  is SHA-256 over the canonical JSON of the parsed document (keys
+  sorted recursively, no whitespace), so a hand reformat is not a
+  change; the tree hash is over the sorted `(id, docHash)` pairs.
+  `computeDelta(tree, freeze, ledgers)` returns the exact
+  `frozen / frozenAt / treeHash / currentTreeHash / changed / added /
+  removed / briefSince / unchanged` shape proposal 2026-09-22 v3
+  section 2.2 pins. Before the first freeze the delta is the whole
+  tree (`frozen: false`, everything in `added`). Reused unchanged:
+  `computeImpact`, `computeTrace`, `computeCoverage`.
+- **DEFINE workflow: freeze record I/O (REQ-172, slice 1).** New
+  module `src/define/freeze-record.js` owns `rcf/define/freeze.json`
+  with a small local schema (until schemas 0.7 promotes it to
+  `manifest.freeze` per ADR-4121). `loadFreezeRecord` returns `null`
+  on a missing file; a malformed body raises `FreezeRecordError` with
+  a coded reason (`parseFailure | schemaFailure | ioFailure`) and a
+  named field. `saveFreezeRecord` validates first, so a bad
+  in-memory record never lands on disk; extension fields survive a
+  save / load round trip. The `rcf define freeze` verb is a
+  later-slice consumer; this slice ships the writer so the verb can
+  be built without a second refactor.
+- **DEFINE workflow: four sidecar ledgers and `rcf define ledger`
+  (REQ-173, slice 1).** Four ledgers live under `rcf/define/`, one
+  JSON file each, each with one numbered sequence per project:
+  `brief-ledger.json` (D1 statements, kinded from the closed set
+  `capability | constraint | actor | entity | externalSystem |
+  surface | outOfScope | openQuestion | amendment`),
+  `decisions-ledger.json` (D7, printed in the numbered #241 format),
+  `concern-ledger.json` (D5, `applied | waived`),
+  `probe-ledger.json` (D6, `low | medium | high`).
+  `rcf define ledger <name> <verb>` covers `add`, `resolve` and
+  `list`; `brief add --from <file>` splits statements one per
+  non-empty line and mints sequential ids (the
+  intake-scan-against-frozen-statements hook is a named seam this
+  slice leaves for slice 2). `decisions list` prints the #241
+  numbered format. `list --json` emits `{ ledger, <arrayKey>: [...] }`.
+  A dedicated test proves the walker never surfaces any `rcf/define/`
+  path in `walkTree` errors or `tree.byId`.
+- **DEFINE workflow: stage gates D1..D8 (REQ-174, slice 2 of the
+  0.29.0 train).** New pure module `src/query/gates.js` exports one
+  check function per stage (`checkD1Brief`..`checkD8Freeze`) plus
+  the `STAGE_ORDER`, `STAGE_GATES`, `STAGE_SHORT_NAMES` and
+  `INTERFACE_KINDS` constants. Every function returns the exact
+  `{ stage, gate, state, checks[] }` shape proposal 2026-09-22 v3
+  section 2.4 specifies, with `checks[i]` in the `{ name, ok, over,
+  pass, total, failing }` form. Blocking in 0.29.0: D1 (define.brief),
+  D2 (define.skeleton), D4 floors (define.stories), D7
+  (define.decisions), D8 (define.freeze). Warn-with-ack in 0.29.0:
+  D3 (define.shapes), D5 (define.crosscut), D6 (define.consistency)
+  \- the state folds to `acknowledged` when the freeze record's
+  `gates[<gate>]` entry names `acknowledged` at the current tree
+  hash (ADR-4122). D4 per-class opt-outs reuse the existing
+  `manifest.baselineAcOptOuts[]` array with a baselineKey of
+  `'defineD4:failure'` or `'defineD4:mustNot'`; no new sidecar is
+  introduced. The template parser, entity join, D5 catalogue, D6
+  contradiction / unsatisfiable scans and probe runner remain as
+  named seams for 0.30.
+- **DEFINE workflow: readiness compute and `rcf define readiness`
+  CLI (REQ-175, slice 2).** New pure module `src/query/readiness.js`
+  exports `computeReadiness(tree, { freeze, ledgers, profile,
+  testPointers })` returning the section 2.4 object exactly:
+  `{ tree, delta, stages, nextAction, coverage, decisions,
+  freezeable }`. The composer runs `computeDelta` once, calls
+  `computeImpact` per id in the union of changed and added (skipping
+  the fan-out on the unfrozen whole-tree case where the delta IS the
+  tree), runs the eight gate check functions over
+  `scope = changed union added union impacted`, calls
+  `computeCoverage` tree-wide plus once per REQ ancestor of the
+  delta, lists open decisions, and folds to `freezeable` and
+  `nextAction`. New verb `rcf define readiness [--json] [--check
+  <stage>|all]` (stage accepts D1..D8 or the short names
+  `brief | skeleton | shapes | stories | crosscut | consistency |
+  decisions | freeze`); text output = tree line, next action, chip
+  line, delta list, failing items; `--check` exits 4 on a
+  blocking-stage failure, exits 0 with a visible `[warn]` line on an
+  unacknowledged warn-with-ack failure. The producer is wrapped with
+  `runWithAdmissibilityGate` per the NV-BL-SR-03 addendum; on
+  admissibility refusal the CLI prints a `[warn]` note and still
+  runs the compute, because readiness is a diagnostic and refusing
+  to render is the opposite of what it exists to say (ADR-4123).
+  Slice 3's `rcf define freeze` will read `freezeable` and refuse
+  on any failing stage.
+
+### Fixed
+
+- **US auto-mint extends flat legacy sequences instead of jumping to
+  the encoded slot (#256).** `nextIdForKind(tree, 'userStory', ...)`
+  in `src/core/store/writer.js` assumed every US id encodes
+  `US-<reqNum><localTwoDigit>`. On a legacy tree whose USes carry
+  flat sequential ids (`US-1`, ..., `US-163`, migrated in from a
+  WESPA v1 project) that decode failed and the allocator fell back
+  to `US-<reqNumLabel>01`, minting shapes like `US-5301` under
+  `REQ-053` next to the existing `US-163`. Classification now runs
+  before allocation: every US id is labelled ENCODED (id decomposes
+  as `<declaredReqNum><local in 01..99>`) or FLAT. An all-flat tree
+  extends past the tree-wide high-water mark (`US-164`), an
+  all-encoded tree preserves the historical rule, and a mixed tree
+  refuses with a message that names both example ids and asks the
+  operator to normalise one shape before retrying. AC auto-mint is
+  unchanged.
+- **Slice-1 P3: `loadAllLedgers` omits absent ledger files
+  (AC-17501-6).** The `LedgerBundle` typedef on `computeDelta` said
+  "if a project has not authored any decisions, the caller passes
+  no `decisions` key and the delta records no `ledger:decisions`
+  docHash"; the previous implementation always returned the four
+  empty bodies. `loadAllLedgers` now `stat`s each ledger file first
+  and omits the key on ENOENT, so a project with no ledgers gets
+  zero `ledger:<name>` docHashes in the delta and a project with
+  only a brief ledger gets exactly one. `loadLedger` still returns
+  an empty ledger on ENOENT so single-ledger callers keep the
+  ergonomic default.
+- **Slice-2 P3: D2 / D4 scaffold-TODO matcher narrowed to the literal
+  `TODO:` placeholder.** `src/query/gates.js`'s `TODO_RE` used to be
+  the whole-word `/\btodo\b/i`, which false-positived on prose
+  mentioning the word ("no AC description contains the scaffold TODO
+  placeholder" on US-17401 / AC-17401-4 tripped D4 against itself).
+  The regex is now `/\bTODO:/` -- case-sensitive uppercase `TODO`
+  followed by a colon, matching every scaffold string
+  `src/core/store/init.js` and `src/core/store/writer.js` write for a
+  fresh `rcf init` / `rcf define create`. `src/cli/validate.js` keeps
+  its broader `\btodo\b/i` matcher for the informational tree-wide
+  notice, so incidental prose still surfaces there without failing
+  the D2 / D4 gates.
+
+## [0.28.3] - 2026-09-22
+
+Batched fix release for the residuals Dex's 0.28.2 round-trip surfaced
+and one HQ-side viewer bug caught the same day. Ships one chain
+amendment (three design amendments on the same redactor AC) and four
+build diffs behind it, plus one viewer-side snapshot fix.
+
+### Fixed
+
+- **Feedback redactor no longer folds the git protocol sentinel
+  `git@<host>` inside git+ssh, ssh or git URLs as an email (#243).**
+  A `--evidence` pointer copied verbatim from a git remote or a clone
+  URL survives verbatim, so the operator can re-run the exact command
+  they hit. The bare-remote shape `git@<host>:<owner>/<repo>` is
+  covered by the same guard. Real emails in surrounding prose still
+  fold to `<email>`. The URL rule 4 also now handles git+ssh, ssh and
+  git schemes with optional userinfo, so a non-allowlisted host inside
+  a clone URL still folds to `<host>` while the sentinel is preserved.
+- **Feedback redactor now treats single-letter trailing labels as
+  filename fragments, not hostnames (#247, Codex P1-5 deferred from
+  PR #242).** Tokens like `a.b.c` survive verbatim. Single-letter TLDs
+  are not registrable domains in normal prose; folding them yields
+  more false positives on short identifiers and abbreviated references
+  than legitimate redactions.
+- **Feedback redactor emits a visible stderr warning when identity
+  folding is disabled (#246).** When `rcf/.identity/profile.md` is
+  missing, has no `## Name` heading, has a blank or placeholder Name
+  line, or the Name contains only reserved-noun tokens, one line on
+  stderr names the file and states that folding is disabled. The
+  operator is no longer left thinking their identity is in force when
+  it silently is not. Folding still skips per AC-15601-5.
+- **`rcf feedback status --json` and text now expose the destination
+  resolution `source` field, matching preview (#244).** Programmatic
+  verifiers can now assert which resolver path picked the destination
+  (`library-manifest`, `package-bugs-url`, `derived`,
+  `sourceRef-derivation`, `library-slug-inference`) without parsing
+  preview text. The field is null when the resolver did not attach
+  one, e.g. for an unresolved library.
+- **`rcf feedback add --evidence` pointers now render with the label
+  matching their shape, not always `(command)` (#245).** The help
+  text promises three labels (`command / path:line / id`); the
+  classifier now recognises `path:line` and bare paths ending in a
+  known file extension as `file`, canonical RCF ids
+  (`AC-15601-6`, `REQ-155`, `FBS-181`, `US-15701`) as `id`, and
+  everything else as `command`. Whitespace anywhere in the pointer
+  is a hard signal for `command`.
+- **`rcf audit view` snapshots its shipped static assets at server
+  startup (#248).** The live-view server rendered the HTML body from
+  a tree walk captured at startup, but `/style.css`, `/mermaid.min.js`
+  and `/live-client.js` were `readFile`-d per request against the
+  on-disk file. A checkout branch switch during the server's lifetime
+  silently changed what got served; the 2026-09-22 Product Map
+  preview rendered unstyled for exactly this reason. All three
+  assets are now read once at startup into memory and served from
+  there. The tree walker remains the only path that re-reads disk on
+  `rcf/` change.
+
+### Chain
+
+- AC-15601-6 amended with design amendments R5e (single-letter TLDs
+  are filename fragments), R5f (git protocol sentinel protection on
+  rule 3, extended URL rule 4 for git+ssh/ssh/git schemes) and R5g
+  (visible stderr warning when identity folding is disabled). All
+  three land on the same story so operators see one AC that names
+  the redactor's full posture.
+- `rcf define validate`: clean. `rcf audit coverage --strict`: clean
+  (103 requirements, 0 uncovered).
+
+### Release mechanics
+
+- Version bumped: `packages/rcf-lite/package.json` 0.28.2 -> 0.28.3.
+- Changelog entry under `## [0.28.3]` (this section).
+- Feed entry added under `releases/releases.yaml`; `latest` set to
+  0.28.3.
+- Tag / publish: Dave (not this PR).
+
+## [0.28.2] - 2026-09-22
+
+Batched fix release for the seven defects Barry's WSD-lens dogfood on
+0.28.1 surfaced (issues #229-#235), plus the three unreported dry-run
+gaps Barry folded into the same release on 2026-09-21 (review,
+ui-baseline init, browser-verify). Ships two chain amendments (the fold
+rule on submit and a filename-token narrowing on the redactor's rule 4)
+and five build diffs behind them.
+
+### Fixed
+
+- **Submit no longer folds unrelated findings into one issue and no
+  longer replaces the report with a "+1" stub (#234).** Barry's
+  round-trip filed five distinct findings with four distinct
+  fingerprints; every one folded to a single pre-existing issue whose
+  fingerprint matched none of them, and every comment carried
+  `+1 from another reporter.` with no title, body or evidence. The
+  fix, per Barry's 2026-09-21 ruling on the fold rule: submit no
+  longer treats a `gh search issues` hit as a fold decision. For
+  every returned candidate it now re-reads the issue body via a new
+  `ghIssueGetBody` gh-adapter function and folds only when the body
+  carries `rcf-feedback-fingerprint: <fp>` on its own line AND the
+  anchor / kind / target markers agree with the entry's. The retired
+  `+1 from another reporter.` payload is gone: every fold comment
+  now carries the full report prefaced with "Apparent duplicate of
+  the issue subject; posting the full report so a human can judge."
+  Submit's stdout row names the outcome and the matched title so a
+  wrong fold is visible on the same line a human already sees
+  (`created #N <url>` vs `commented on #N (fingerprint match:
+  <title>) <url>`). Chain: US-15701 AC-15701-2 amended.
+
+- **Redactor no longer rewrites `.md` filenames as hostnames (#233).**
+  Barry's evidence pointer
+  `rcf discover intake --artefact rcf/knowledge/docs/brief/Backstory-product-brief.md,...`
+  was rendered as `Backstory-<host>`, destroying the exact evidence
+  the verb asks for. Rule 4 gets two narrowings per design amendment
+  R5d: the bare-hostname regex's negative lookbehind now includes
+  `-` (so `product-brief.md` can never start a match after the
+  hyphen), and a candidate hostname whose trailing dot-label is on a
+  bundled `extensions` shortlist in `src/feedback/redact-allowlist.json`
+  is left intact with no ledger row. Bundled list covers the file
+  types rcf-lite feedback sees as evidence (md, mdx, json, yml,
+  yaml, txt, js, mjs, cjs, ts, tsx, html, css, png, svg, sh, csv,
+  log, lock). Operator overlay merges via `allowExtensions` on the
+  redact context. Chain: US-15601 AC-15601-6 added; TAC-4103
+  responsibility updated.
+
+- **Dry-run and write now share one schema pass across the five
+  discover verbs (#230 and #232, folding review / ui-baseline init /
+  browser-verify per Barry's 2026-09-21 ruling).** Two direct
+  reproductions: `intake --input <file> --dry-run` accepted
+  `fidelity: briefRich` that the real run refused (#230); `preflight
+  --input <file> --dry-run` accepted a kebab-case service id that
+  the real run refused (#232). Same class in the three unreported
+  verbs. Fix: a shared `validateComposedRecord({ tree, record, verb
+  })` helper in `src/core/store/validate-composed-record.js`
+  synthesises the same nextManifest each writer builds, runs
+  `validateDocument`, and returns null or the same error the writer
+  would refuse on. Wired into every dry-run branch; exit code 3 on a
+  validation miss in every path. `intake --help` now advertises the
+  fidelity enum (`FIDELITY_LEVELS`); `preflight --help` names the
+  service id pattern (`^[a-z][a-zA-Z0-9]*$`).
+
+- **`discover intake` no longer emits the same finding once per
+  artefact (#229).** Two artefacts that both trip the same branch
+  (`impliedButNotStated` on a web UI with no sign-in surface) landed
+  as two byte-identical findings in the record. Findings are now
+  material-scoped (deduped by `<kind>::<detail>` before timestamping)
+  and operator-supplied `validationFindings` on `--input` survive
+  regardless of kind (previously only `otherDeclared` was folded,
+  silently dropping `impliedButNotStated` / `contradiction` /
+  `missingLoadBearingConstraint`). A scan hit and an operator-authored
+  finding of the same (kind, detail) coalesce with the operator's
+  response preserved. Build-only per the RCA.
+
+- **`req-baseline sweep --yes` no longer assigns duplicate AC ids
+  across a batch (#231).** Accepting two or more baseline candidates
+  for one user story in one sweep refused the write with
+  `Duplicate id AC-<usNum>-<N>`. Fix: extract the ordinal allocator
+  into `makeAcIdAllocator(usDoc)`; `applySweepDecisions` creates one
+  allocator per US and passes each allocated id into
+  `composeBaselineAc` via a new optional `idOverride` parameter.
+  `nextAcId` and the single-candidate call shape stay
+  backwards-compatible. Build-only per the RCA.
+
+- **TAD renderer no longer dumps `JSON.stringify(x)` for structured
+  fields (#235).** Barry's review surface showed 14 raw single-line
+  JSON blobs across `dataStores`, `coreEntities` and
+  `externalSystems`. A new `fieldObjectTable(label, rows, columns)`
+  helper renders each schema-known structured field as a table with
+  the columns the TAD schema documents. Empty columns are dropped so
+  schema-optional fields do not surface as blank columns; every cell
+  is escaped. `renderOptionalSections` picks the table renderer for
+  `dataArchitecture.dataStores`, `dataArchitecture.coreEntities`,
+  `integrationArchitecture.externalSystems`; everything else keeps
+  the scalar / array-of-string treatment. `style.css` gets a
+  lightweight `.field-list table.field-table` rule matching the
+  existing cadence. Build-only per the RCA.
+
 ## [0.28.1] - 2026-09-17
 
 Feedback defects surfaced by the first WSD-lens round-trip on 0.28.0. Fixes both a destination bug that silently misrouted library-owned findings to `Stravica/rcf-lite`, and a redactor over-fold that mangled the docs URL and any prose using the canonical noun `agent`. Includes a package-rename disclosure banner in the README so a colleague hitting `npm i -g @stravica-ai/rcf-build-lite` on the retired scoped name knows what to do.

package/bin/rcf.js

@@ -51,6 +51,8 @@ import { main as reqClassifyMain } from '../src/cli/req-classify.js';
 import { main as reqBaselineMain } from '../src/cli/req-baseline.js';
 import { main as intakeMain } from '../src/cli/intake.js';
 import { main as evalMain } from '../src/cli/eval.js';
+import { main as ledgerMain } from '../src/cli/ledger.js';
+import { main as readinessMain } from '../src/cli/readiness.js';
 
 // Verify group members are handled by the verify-suite dispatch tree.
 import { main as verifyRunMain } from '../src/verify/cli/run.js';
@@ -95,6 +97,8 @@ export const GROUPS = {
     design: designMain,
     blueprint: blueprintMain,
     standards: standardsMain,
+    ledger: ledgerMain,
+    readiness: readinessMain,
   },
   build: {
     // build sub-verbs are dispatched by build.js internally (queue |

package/fixtures/canary-manifest.json

@@ -1,9 +1,9 @@
 {
   "registerCanary": [
     {
-      "id": "rc-2026-09-17-001",
-      "createdAt": "2026-09-17T14:42:00.660Z",
-      "buildVersion": "0.28.1-mockdriver",
+      "id": "rc-2026-09-30-001",
+      "createdAt": "2026-09-30T15:30:02.583Z",
+      "buildVersion": "0.28.4-mockdriver",
       "fixturePromptId": "canary-prompt-01",
       "responseWordCount": 55,
       "grades": {
@@ -34,9 +34,9 @@
       "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
     },
     {
-      "id": "rc-2026-09-17-002",
-      "createdAt": "2026-09-17T14:42:00.661Z",
-      "buildVersion": "0.28.1-mockdriver",
+      "id": "rc-2026-09-30-002",
+      "createdAt": "2026-09-30T15:30:02.584Z",
+      "buildVersion": "0.28.4-mockdriver",
       "fixturePromptId": "canary-prompt-02",
       "responseWordCount": 55,
       "grades": {
@@ -67,9 +67,9 @@
       "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
     },
     {
-      "id": "rc-2026-09-17-003",
-      "createdAt": "2026-09-17T14:42:00.661Z",
-      "buildVersion": "0.28.1-mockdriver",
+      "id": "rc-2026-09-30-003",
+      "createdAt": "2026-09-30T15:30:02.584Z",
+      "buildVersion": "0.28.4-mockdriver",
       "fixturePromptId": "canary-prompt-03",
       "responseWordCount": 55,
       "grades": {

package/package.json

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

package/rcf/adrs/adr-4120-canonical-json-hashing.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z",
+  "adrId": "ADR-4120-canonical-json-hashing",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Delta detection hashes the parsed document under canonical JSON, at standalone-document granularity",
+  "context": "The DEFINE workflow proposal (2026-09-22 v3, section 2.1) has to pick both a hashing scheme and a granularity for docHashes on the freeze record. Two choices matter and are named as residual (proposal section 2 penultimate paragraph): raw bytes versus the parsed canonical form, and criterion-level versus document-level. Raw bytes are the smallest amount of code (one hash per file read); the parsed form costs one canonicalise per document per read (milliseconds at 700 criteria). Criterion granularity gives a finer delta; document granularity keeps the model small and lets git supply the criterion-level diff. Both choices had to be recorded because the detection model is what every later slice (readiness, freeze, bundle, viewer) reads.",
+  "decision": "Hash the parsed document under canonical JSON: keys sorted recursively, no whitespace, JSON.stringify escaping. Compute the tree hash as SHA-256 over the sorted (id, docHash) pairs canonically encoded. The docHashes map has one entry per standalone document the walker exposes on tree.byId (PRD, TAD, BS, REQ, US, TAC, ADR, FBS, TS, CN, EVAL) plus one ledger:<name> entry per sidecar the caller passes; inline AC and TC ride inside their parent's hash. Granularity for the delta list is the standalone document.",
+  "consequences": "A hand reformat of a document (rewritten by rcf define update, opened in an editor and re-saved) does not surface as a change, which is what an operator expects. An edit to a criterion surfaces as its owning story changed; Readiness renders the criterion-level diff by reading the frozen story out of git (proposal section 2.2). The cost is one canonicalise per document per read; at the backstory scale of 700 criteria that is milliseconds and is only paid on readiness / freeze / bundle --next reads. If document granularity turns out too coarse in practice, ADR replacement or schemas 0.7's criterion-hash extension is the migration path; the change would not affect the wire shape of computeDelta because inline granularity would simply expand tree.byId, not the return shape.",
+  "alternativesConsidered": [
+    {
+      "name": "Hash the raw file bytes",
+      "summary": "SHA-256 over readFile output directly; skip canonical JSON entirely.",
+      "reasonNotChosen": "A CLI edit that rewrites the file (rcf define update reserialises the object every write) would report drift on a file it did not semantically touch. The operator would learn to ignore the delta list, which is the one signal the freeze exists to give."
+    },
+    {
+      "name": "Criterion granularity: one docHash per AC / TC on top of the document ones",
+      "summary": "Add inline-AC and inline-TC entries to docHashes so an edit to AC-207-4 shows in the delta at criterion granularity.",
+      "reasonNotChosen": "Doubles the size of docHashes for no readiness improvement: Readiness already renders the criterion-level diff by reading the frozen story from git. The size cost is real (a backstory tree has 700 criteria plus 40 stories); the render cost is not."
+    },
+    {
+      "name": "Hash the pretty-printed JSON body the writer produced",
+      "summary": "Hash JSON.stringify(doc, null, 2) plus a trailing newline; the same bytes the writer wrote.",
+      "reasonNotChosen": "Whitespace-only reformats (a hand edit that reorders keys or drops a trailing newline) then surface as changes. Canonical hashing is the same code with the whitespace stripped and the keys sorted; the operator sees fewer false-positive deltas."
+    }
+  ]
+}

package/rcf/adrs/adr-4121-define-sidecars.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z",
+  "adrId": "ADR-4121-define-sidecars",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Ledgers as rcf-lite-owned sidecars under rcf/define/ with a local schema; promote to manifest records at schemas 0.7",
+  "context": "The DEFINE proposal (2026-09-22 v3, section 2.5 and decision 5) needs a place to put four things the workflow reads and writes but the shared schema does not yet know about: brief statements (D1), decisions (D7), (concern, REQ) dispositions (D5), probe findings (D6). @stravica-ai/rcf-schemas 0.6.3 has no manifest.ledgers[] shape and adding one is a schema-package bump; the train's non-goal (train-context: 'no schema change') is to ship the workflow without touching @stravica-ai/rcf-schemas. Precedent already exists in this codebase: .rcf/preflight-secrets.local.json is an rcf-lite-owned file outside the shared schema; the loader reads only its named collection directories, so a directory the walker was not told about is invisible.",
+  "decision": "Ledgers live under rcf/define/, one JSON file each (brief-ledger.json, decisions-ledger.json, concern-ledger.json, probe-ledger.json), validated by a local schema inside src/define/ledgers.js. The freeze record sits at rcf/define/freeze.json under the same directory. rcf-lite owns the shape until @stravica-ai/rcf-schemas 0.7, at which point the sidecars promote to a manifest.freeze and manifest.ledgers[] records and the local schema is retired. The walker never reads rcf/define/ (src/core/store/loader.js's subdirFor returns null for anything not in its child-kind list), and a walker-invisibility invariant test proves it stays that way.",
+  "consequences": "A DEFINE change lands with no @stravica-ai/rcf-schemas bump: the train ships as 0.29.0 against the shipped 0.6.3 schema. The sidecars are committed alongside the rest of the rcf tree (they carry durable state: the freeze hash, brief statement ids, resolved decisions), so git supplies the history the proposal section 2.1 relies on. Second source of truth is the honest downside: until schemas 0.7 there are two places the DEFINE workflow reads (the shared tree and rcf/define/); the promotion path documented in the proposal (section 5.3) is straightforward because the local shapes were designed to line up with the manifest.freeze and manifest.ledgers[] fields the schema promotion adds. If schemas 0.7 slips past the 0.30 train, the sidecars keep working: the local schema is the contract every DEFINE gate consumes.",
+  "alternativesConsidered": [
+    {
+      "name": "Land the manifest.freeze and manifest.ledgers[] records at schemas 0.6.4 now",
+      "summary": "Bump @stravica-ai/rcf-schemas to 0.6.4 as part of this train; add manifest.freeze and manifest.ledgers[] optional records; write to the manifest instead of a sidecar.",
+      "reasonNotChosen": "The train-context ('no schema change') is a deliberate constraint on this train, ratified 2026-09-22, so the workflow can ship without another WSD-side schema round trip. Schemas 0.7 is on the roadmap for the 0.30 train; landing the sidecar first proves the shape at zero schema cost, then the promotion carries the same fields."
+    },
+    {
+      "name": "One combined ledger file (rcf/define/ledger.json) with four sections",
+      "summary": "Collapse the four ledgers into one file with four top-level keys; the CLI still gates on the name.",
+      "reasonNotChosen": "The four ledgers grow independently (a probe-heavy pass writes ten probes with no decisions changed) and merge conflicts on a shared file would surface constantly. Four files with distinct id sequences is the cheaper long-term shape, and it lines up with the four manifest.ledgers[] records schemas 0.7 is expected to add."
+    },
+    {
+      "name": "Sidecars under .rcf/ (like preflight-secrets.local.json)",
+      "summary": "Put the four ledgers under .rcf/ so they inherit the preflight-secrets convention.",
+      "reasonNotChosen": "The preflight sidecar is gitignored on purpose (credential name-metadata). DEFINE ledgers hold durable state the workflow re-reads on every gate; they must be committed. rcf/define/ keeps them visible to the operator, alongside the tree they annotate."
+    }
+  ]
+}

package/rcf/adrs/adr-4122-define-gates-blocking-and-optout.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T14:30:00Z",
+  "adrId": "ADR-4122-define-gates-blocking-and-optout",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Blocking-vs-warn-with-ack per stage; D4 per-class opt-out reuses manifest.baselineAcOptOuts[]",
+  "context": "The DEFINE workflow proposal (2026-09-22 v3, section 3.2, decision 2) blocks where the data exists and warns-with-acknowledgement for D3, D5, D6 until the release that lands the 0.30 (renumbered from 0.31 per Baz 2026-09-24) contradiction-lite, unsatisfiable-lite, template parser and probe runner. Proposal section 3.2 also says D4's failure and must-not floors accept a 'reasoned opt-out per class, as the baseline ledger works (#239)'. The train has to decide whether the D4 opt-out reuses the existing manifest.baselineAcOptOuts[] machinery (nextOptOutId, composeOptOutRecord under src/req-baseline/opt-out.js, boo-YYYY-MM-DD-NNN ids) or gets a new sidecar under rcf/define/. Second decision that had to be recorded because slice 2's gates read it and slice 3's freeze verb writes it: how does the freeze record acknowledge a warn-with-ack gate?",
+  "decision": "Blocking in 0.29.0: D1 (define.brief), D2 (define.skeleton), D4 floors (define.stories), D7 (define.decisions), D8 (define.freeze). Warn-with-ack in 0.29.0: D3 (define.shapes), D5 (define.crosscut), D6 (define.consistency). Blocking-vs-warn-with-ack is a stage property, hard-coded in src/query/gates.js. The state fold: a stage is 'passed' when every check.ok is true; 'failing' otherwise. For D3/D5/D6 the fold flips to 'acknowledged' when the freeze record's gates[<gate>] entry names state 'acknowledged' AND at.hash === currentTreeHash. D4 per-class opt-outs reuse manifest.baselineAcOptOuts[]: baselineKey is 'defineD4:failure' or 'defineD4:mustNot'; scope is 'req' (opt-out applies to every US whose reqId matches the record's reqId) or 'project' (applies tree-wide). Slice-3 writes acknowledgements via the freeze verb; the write path is out of scope for slice 2. The opt-out records are authored by an operator through the existing req-baseline surface (or, in slice 3, an optional --optout flag on freeze); slice 2 only reads them.",
+  "consequences": "One place to author opt-outs (the existing baselineAcOptOuts array), one place to read them (the same array). No new sidecar until D4's class opt-outs mature (schemas 0.7 will move them if the shape stabilises). The freeze record's gates map becomes the single source of truth for acknowledgements, which is what slice-3's freeze verb writes and every consumer reads. The honest downside: the baselineKey field is loosely typed (free-string convention rather than an enum), so a typo lands silently (the D4 gate simply does not honour the opt-out). Mitigation: the checker prints a stderr [warn] when it sees a record with a baselineKey starting with 'defineD4:' but not matching the two known values, and the CLI docs (slice 3 / slice 6) list the accepted keys. If the shape ever needs to move, existing records can be migrated by rewriting the manifest under the same array without a schema change.",
+  "alternativesConsidered": [
+    {
+      "name": "New sidecar rcf/define/class-optout-ledger.json for D4 per-class opt-outs",
+      "summary": "Fifth sidecar under rcf/define/ with entries { id, scope, reqId?, usId?, class: 'failure'|'mustNot', reason, addedAt }; add --class flag to rcf define ledger.",
+      "reasonNotChosen": "Adds a fifth sidecar to a proposal (decision 5) that ratified four. Proposal section 3.2 D4 explicitly says 'as the baseline ledger works (#239)', pointing at the existing surface. A fifth ledger costs a schema, a CLI branch and a walker-invisibility test for zero gain over reusing the shape."
+    },
+    {
+      "name": "Block D3, D5, D6 in 0.29.0 (drop warn-with-ack)",
+      "summary": "Every stage blocks; --ack is not a thing until 0.30.",
+      "reasonNotChosen": "Baz's decision 2 ratifies warn-with-ack for D3/D5/D6 until the template parser, catalogue and scans land. Blocking on cheap presence-only checks (an unknown interface kind, or a probe finding still open) refuses freezes on tree state that 0.30's richer checks would tolerate; the acknowledgement channel is what lets an operator move without inventing the check they need is not there."
+    },
+    {
+      "name": "Encode blocking-vs-warn-with-ack on each check rather than on the stage",
+      "summary": "Every check[i] carries a policy tag; the fold reads the tags rather than the stage.",
+      "reasonNotChosen": "The proposal is stage-scoped, not check-scoped. Per-check policy tags land as future noise for zero present gain: today every check inside a stage shares a policy. If a stage grows a check with a different policy the fold moves back to per-stage anyway (a 'failing' check on any policy is still 'failing' in the current model)."
+    }
+  ]
+}

package/rcf/adrs/adr-4123-readiness-single-object.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-09-24T15:48:40Z",
+  "adrId": "ADR-4123-readiness-single-object",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Readiness is one computed object; no stored stage state, no stored 'stale'",
+  "context": "The DEFINE workflow proposal (2026-09-22 v3, section 2.4, section 6, decision 4) is explicit that the CLI and the viewer tab render the same object so they cannot disagree, and that stage state is one of passed | failing | acknowledged | notApplicable with no 'stale' and no 'notStarted' because nothing is stored: every chip is the truth at the moment of the read. The Product Map (PR #238) precedent already ships this pattern for a related surface. Slice 2 has to pick both the computation shape (one pass or many; where the impact fan-out sits) and the storage shape (nothing stored, or a small cache in the freeze record).",
+  "decision": "computeReadiness returns one plain-data object per call over the tree, the freeze record and the four ledgers; nothing is stored between calls, and no per-stage 'stale' flag exists. The stage state is a pure fold over the checks[] of that stage: 'passed' when every check.ok is true, 'failing' otherwise, unless the stage is one of the three warn-with-ack stages and the freeze record's gates[<gate>] entry names 'acknowledged' at the current tree hash. The CLI (rcf define readiness) prints the object; slice-5's viewer renders the same JSON envelope over the existing tab wire (proposal section 6.3). runWithAdmissibilityGate wraps the CLI's producer, matching the ruleset toolScope { traceabilityAndQueryTools: true } switch; slice 2 records this decision because the wrap changes the shipping exit path. On refuse the wrap runs first (so the ruleset toolScope guard is honoured, NV-BL-SR-03 addendum), then the readiness compute runs anyway and the CLI prints an informational [warn] on stderr naming the refusal, because readiness is a diagnostic and refusing to report which stage blocks is the opposite of what the verb exists to do; the process still exits 0 (or the --check <stage> code) and never exits 4 solely on refuse.",
+  "consequences": "One shape, two renderers: whatever the CLI prints, the viewer prints. Absence of stored state means Readiness is stateless: git carries the history, the freeze record carries the acknowledgements, everything else is derived. The compute cost is one canonicalise per document per read (already ratified in ADR-4120) plus one computeImpact per delta id, which on the dogfood chain (~700 documents, ~30 delta ids on a small feature) is measured in single-digit seconds. If the compute ever costs too much, the mitigation is a per-render cache in the CLI or the viewer (not in the freeze record), so the shape stays the same. Honest downside: the whole-tree unfrozen case (no freeze record; every doc is 'added') computes computeImpact over every id, which on very large trees may be quadratic in fan-out size. Slice 2 mitigates by skipping the per-id fan-out when the delta is the whole tree (the delta IS the fan-out), and the CLI prints wall time so an operator can spot a regression before it becomes a defect.",
+  "alternativesConsidered": [
+    {
+      "name": "Cache the last stage[] under freeze.gates[]; only re-run gates whose delta touches their scope",
+      "summary": "Store per-stage checks + fold under freeze.gates[]; readiness reads the cache and only re-runs gates the delta invalidates.",
+      "reasonNotChosen": "Two sources of truth: the tree and the cache. Every operator correction to a story would have to invalidate the cache correctly, and any bug in the invalidation would show up as a false green. Proposal section 2.4 explicitly rules this out: 'no stale, no not-started'. Recompute is cheap enough not to earn the complexity."
+    },
+    {
+      "name": "Skip runWithAdmissibilityGate on the readiness verb",
+      "summary": "Readiness is a diagnostic; run it even when admissibility refuses so the operator can see what to fix.",
+      "reasonNotChosen": "The ruleset toolScope switch { traceabilityAndQueryTools: true } is a runtime-read guard (NV-BL-SR-03 addendum) and matches every other query verb's expected posture; skipping it would be an exception the checker cannot see. Slice 2 wraps the producer; a future train can add an explicit --show-anyway flag if the diagnostic case wins the argument, and record it as an ADR replacement."
+    },
+    {
+      "name": "Compute stages fully in parallel with Promise.all",
+      "summary": "Every stage check runs in parallel via Promise.all against a shared context.",
+      "reasonNotChosen": "The gate check functions are pure and CPU-bound (no I/O); Promise.all does not parallelise CPU on Node without workers, and worker-thread overhead is far larger than the compute cost. Sequential composition is honest about what the code does."
+    }
+  ]
+}

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

@@ -6,11 +6,12 @@
     "AC-15601-2",
     "AC-15601-3",
     "AC-15601-4",
-    "AC-15601-5"
+    "AC-15601-5",
+    "AC-15601-6"
   ],
   "dependencies": [],
   "version": "0.1.0",
   "status": "draft",
   "createdAt": "2026-09-16T15:27:35Z",
-  "updatedAt": "2026-09-17T14:14:49Z"
+  "updatedAt": "2026-09-22T00:00:00Z"
 }

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

@@ -0,0 +1,23 @@
+{
+  "cnId": "CN-700",
+  "path": "src/view/product-map.js",
+  "title": "Product Map re-bucketing over the review-surface tree model",
+  "description": "Pure functions groupByShape, groupByComponent, groupByTraceCoverage, groupByCapability, groupByBlueprint plus the panel renderer that composes them. No schema change; consumes shapeClassification.shapes[], usByTacId, tsByAcId/tcsByAcId, REQ.tags[] for capability:<slug> tags, and manifest.blueprints[].contributions[] for blueprint attribution (fallback: reqId kebab-slug prefix). Emits a pm-blueprint-badge on every REQ row an applied blueprint contributed.",
+  "implementsAcIds": [
+    "AC-17001-1",
+    "AC-17001-2",
+    "AC-17002-1",
+    "AC-17003-1",
+    "AC-17004-1",
+    "AC-17005-1",
+    "AC-17006-1",
+    "AC-17008-1"
+  ],
+  "dependencies": [
+    "CN-017"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-22T11:59:39Z"
+}

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

@@ -0,0 +1,14 @@
+{
+  "cnId": "CN-701",
+  "path": "scripts/apply-capability-tags.mjs",
+  "title": "Apply capability:<slug> tags to every dogfood REQ",
+  "description": "One authoritative REQ id -> slugs mapping applied to every requirement file under rcf/requirements/. Idempotent; overwrites existing capability:<slug> tags while preserving non-capability tags. Ships as the tool of record until a rcf discover req-capability-classify verb lands.",
+  "implementsAcIds": [
+    "AC-17101-1"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,14 @@
+{
+  "cnId": "CN-702",
+  "path": "docs/capability-tags.md",
+  "title": "Capability tag convention and taxonomy for the rcf-lite chain",
+  "description": "Documents the capability:<slug> convention, the initial twelve-slug taxonomy and the rule for adding a new capability. Linked from docs/README.md; consumed by the Product Map by-capability grouping.",
+  "implementsAcIds": [
+    "AC-17102-1"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-21T17:00:00.000Z",
+  "updatedAt": "2026-09-21T17:00:00.000Z"
+}

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

@@ -0,0 +1,16 @@
+{
+  "cnId": "CN-703",
+  "path": "src/server/routes.js",
+  "implementsAcIds": [
+    "AC-17007-1"
+  ],
+  "dependencies": [
+    "CN-700"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-21T19:44:46.452Z",
+  "updatedAt": "2026-09-21T19:44:52.245Z",
+  "title": "Product Map partial-render endpoint",
+  "description": "Adds a /product-map/<group> HTTP route that serves the pre-rendered non-lazy panel body for the named grouping. Consumed by the inline scripts hydrateLazyGroup which fetches on first activation and caches the response in memory; the live-client invalidates the cache on every SSE tree-update swap."
+}

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

@@ -0,0 +1,15 @@
+{
+  "cnId": "CN-720",
+  "path": "src/query/delta.js",
+  "title": "Delta detection: canonical-JSON hashing and computeDelta",
+  "description": "Pure module. canonicaliseJson (recursive key sort, no whitespace), hashDocument (sha256:<hex> over the canonical form of a parsed document), computeTreeHash (over sorted (id, docHash) pairs), and computeDelta (returns the proposal 2026-09-22 section 2.2 shape: frozen, frozenAt, treeHash, currentTreeHash, changed, added, removed, briefSince, unchanged). Ledger docHashes are added under ledger:<name> ids per sidecar the caller passes.",
+  "implementsAcIds": [
+    "AC-17201-1",
+    "AC-17201-2"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}