rcf-lite 0.28.2 → 0.29.0

package/rcf/adrs/adr-4127-readiness-tab-order-and-register.json

@@ -0,0 +1,40 @@
+{
+  "createdAt": "2026-10-01T18:00:00Z",
+  "updatedAt": "2026-10-01T18:00:00Z",
+  "adrId": "ADR-4127-readiness-tab-order-and-register",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Readiness is tab 1 always and renders the same object as the CLI; the register orders persona groups and never hides one",
+  "context": "DEFINE step 2 (0.29.0) exposes two verdicts on the one readiness ladder. The CLI prints them (PR B); the viewer must carry the same object so the two surfaces cannot disagree. Overview today is just the PRD body (phase 3.6 dropped the diagram), so it never earns first-tab status, and operators asked for a landing surface that leads with 'can I build and whose questions stand in the way'. The persona register from profile.md orders the CLI text report; the tab must honour the same register without ever hiding the non-register group.",
+  "decision": "Readiness is tab 1 of the HTML review surface, always, and renders the computeReadiness result directly. The former Overview tab is renamed PRD with no content change; the data-tab=overview and id=tab-overview identifiers are preserved so every existing `#tab-overview` hash link still resolves. The viewer's renderer is pure: it reads the result object and the profile text and emits HTML; it never recomputes readiness or hits disk. The profile register from pickRegister orders the persona groups (productOwner-first by default; engineer-first when the register says engineer; unstated prints the pair in default order). The non-register group is always rendered with its count visible; collapsed by default, never omitted from the DOM. The Freeze now control is enabled iff levels.readyToBuild.ok; disabled, it names the failing gates from levels.readyToBuild.blockedBy. There is no intent-complete button at L1 (nothing to record; ADR-4126). The 0.29.0 diff component in the delta list is document-level only; criterion-level before-and-after is deferred to the UX review (open question 7 of the step 2 spec).",
+  "consequences": "One readiness object renders three ways (CLI text, CLI JSON, viewer tab) with no second register of truth; AC-18001-7 asserts the identity by walking the rendered anchors and matching them to the --json for the same tree hash. The Overview-to-PRD rename is cosmetic for hash routing and content; existing anchors keep working. Shared components land once, pay down the drift between tabs, and are additive on the Product Map and Requirements tabs in 0.29.0 (re-pointing is a follow-up where the swap is not mechanical). Deferring the criterion-level diff keeps PR C small and leaves the AC-class before-and-after question to the UX review it belongs to.",
+  "alternativesConsidered": [
+    {
+      "name": "Readiness as the fifth tab, Overview stays first",
+      "summary": "Keep Overview as the landing tab and add Readiness at the end.",
+      "reasonNotChosen": "Overview is one block today (the PRD body); it does not earn the landing. Making an operator click to see the verdict is friction for the thing the surface exists to answer."
+    },
+    {
+      "name": "Rename to data-tab=prd and migrate hash anchors",
+      "summary": "Rename both the label and the identifier so the surface reads consistently.",
+      "reasonNotChosen": "Every existing `#tab-overview` link in documents and in commit messages breaks. The label is for humans; the identifier is for links. Keeping the identifier is cheaper than migrating every link."
+    },
+    {
+      "name": "Hide the non-register persona group",
+      "summary": "When the register is productOwner, omit the engineer group from the DOM entirely (and vice versa).",
+      "reasonNotChosen": "AC-18001-5 is must-not for a reason: hiding a persona breaks the parity the CLI --json offers. The tab is a diagnostic, not a filter; the collapse-with-count-visible pattern honours the register without losing visibility."
+    },
+    {
+      "name": "Recompute readiness in the browser",
+      "summary": "Ship the raw tree to the client and compute readiness there.",
+      "reasonNotChosen": "Two implementations of the same compute are two chances to disagree. The server already walks the tree; piping the computed object into the HTML keeps the no-recompute invariant and makes the live-SSE path trivial."
+    },
+    {
+      "name": "Ship criterion-level diff in 0.29.0",
+      "summary": "Render AC-level before-and-after inside the delta list, with a per-AC collapsible pane.",
+      "reasonNotChosen": "Open question 7 of the step 2 spec parks the AC-class before-and-after question for a UX review. Shipping without that review risks a design the review would reject; document-level diff carries the signal 0.29.0 needs."
+    }
+  ]
+}

package/rcf/adrs/adr-4129-questions-harness-driven-loop.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-4129-questions-harness-driven-loop",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The intent-complete loop is harness-driven; rcf-lite computes questions with write-backs and never holds conversation state",
+  "context": "DEFINE step 3 (spec 2026-10-01, section 1.1) requires a product owner to reach `levels.intentComplete.ok === true` without an engineer. The question is whether rcf-lite should hold a conversation state (a stored loop file, a conversation engine) or stay stateless and let the harness (Claude Code or any MCP-wired agent) drive.",
+  "decision": "the loop is harness-driven; rcf-lite computes questions with write-backs and never holds conversation state. computeQuestions is a pure function of (readiness, tree, ledgers, profileText, persona); the harness runs the write-back a question carries, calls readiness again and asks the next question.",
+  "consequences": "The loop is monotone (each answer removes its item), the compute is testable in isolation, and the harness can be swapped without changing rcf-lite. The cost is that the harness must run readiness and questions each turn, which is a cheap pure call.",
+  "alternativesConsidered": [
+    {
+      "name": "A conversation engine in rcf-lite",
+      "summary": "Hold an LLM-driven loop inside rcf-lite that elicits the PO directly.",
+      "reasonNotChosen": "An LLM dependency inside rcf-lite reverses the method's shape: rcf-lite is the referee the harness consults, not an agent of its own. It also forces a model and provider choice that the harness has already made."
+    },
+    {
+      "name": "A stored loop file",
+      "summary": "Keep a loop state file under rcf/define/ that tracks which question was asked last.",
+      "reasonNotChosen": "The stale state the detection model removed. A loop file would drift from the tree the moment any writer edits a ledger outside the loop, and would need its own validate pass; the four ledgers plus the profile already carry every state the loop needs."
+    }
+  ],
+  "createdAt": "2026-10-02T18:00:00Z",
+  "updatedAt": "2026-10-02T18:00:00Z"
+}

package/rcf/adrs/adr-4130-intake-harness-split-tool-scanned.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-4130-intake-harness-split-tool-scanned",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Intake is harness-split and tool-scanned; findings become open-question statements",
+  "context": "DEFINE step 3 (spec 2026-10-01, section 2.1) requires a document intake path where a product owner hands over a folder and reaches `Intent-complete: yes` without an engineer driving. Splitting a source into kinded statements is the agent's job (the harness writes one statement file per source, operator corrects); the mechanical scans and the follow-up questions are rcf-lite's. The question is how finding-level signals (duplicates, contradictions, ambiguities) reach the loop.",
+  "decision": "intake is harness-split and tool-scanned; findings become open-question statements. The harness writes `<source>.statements.md` beside each source; `brief add --from` mints the statements and `runIntakeScansOnDelta` runs over the new ids against the existing body; every finding is appended as one `openQuestion` statement whose source names the scan and the ids involved. The loop then reads one check (`brief:openQuestions`) and the owner answers in one place.",
+  "consequences": "The owner sees findings as questions, not a separate list. One place carries intent (the brief ledger) and one check reads it. The harness can be swapped: any agent that writes the statement file shape and runs `brief add --from` reaches the same loop. The cost is that a finding's full detail lives inside the openQuestion text and its `scan:` source marker; a reviewer who wants a flat findings list builds it from `kind === 'openQuestion' && source startsWith 'scan:'`.",
+  "alternativesConsidered": [
+    {
+      "name": "A separate findings list on the manifest",
+      "summary": "Keep an array of findings on rcf/manifest.json alongside the ledgers, read by the loop as a parallel surface.",
+      "reasonNotChosen": "A second place the loop would have to read, and a second place that could drift from the brief ledger. Making findings statements collapses two surfaces into the one the loop already needs."
+    }
+  ],
+  "createdAt": "2026-10-02T18:00:00Z",
+  "updatedAt": "2026-10-02T18:00:00Z"
+}

package/rcf/adrs/adr-4132-prototypes-in-discovery-as-evidence.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-4132-prototypes-in-discovery-as-evidence",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Prototypes live in DISCOVERY as evidence; code is burned; salvage is re-derivation",
+  "context": "DEFINE step 3 (spec 2026-10-01, section 5) asks where a learning prototype belongs. A prototype is useful for the questions it provokes; its code is a product of exploration under a different set of rules than the project proper, so promoting it would smuggle unowned decisions past the chain.",
+  "decision": "prototypes live in DISCOVERY as evidence; code is burned; salvage is re-derivation. The prototype is recorded in the intake classification as an artefact of kind `other`; its outputs are brief statements with source spans `prototype:<name>:<observation>`; the burn is a single `constraint` statement naming the prototype, its commit sha and burn date. The only middle path is salvage by re-derivation: extract requirements from the prototype as evidence, run them through intake and the PO loop like any document, rebuild from the tree.",
+  "consequences": "Provenance stays whole: every shape in the tree has a chain back to a PO-sanctioned statement, not a prototype's incidental choices. The cost is one managed-block rule the harness picks up, one guidance file (`guidance/discovery-prototypes.md`) and the honest message that a prototype's code is reference only; nothing in the build consumes a prototype directly.",
+  "alternativesConsidered": [
+    {
+      "name": "A prototype mode or promotion path (inverts provenance)",
+      "summary": "Keep the prototype as a privileged tree that can be promoted into the project tree, or run a prototype mode that bypasses parts of the chain while the prototype is live.",
+      "reasonNotChosen": "Promotion inverts provenance: a shape would reach the project tree without the PO loop that owns every settled shape. The method's whole worth is that every requirement, story, AC and shape has a known origin; a promotion path would let an incidental prototype choice bypass that trace, and no amount of auditing after the fact can restore the owner."
+    }
+  ],
+  "createdAt": "2026-10-03T00:00:00Z",
+  "updatedAt": "2026-10-03T00:00:00Z"
+}

package/rcf/adrs/adr-4133-dag-dependency-depth-layout.json

@@ -0,0 +1,40 @@
+{
+  "createdAt": "2026-10-02T18:00:00Z",
+  "updatedAt": "2026-10-02T18:00:00Z",
+  "adrId": "ADR-4133-dag-dependency-depth-layout",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The Build/DAG canvas lays FBS by dependency depth, orders rows by buildOrder, measures the critical path by node count and parks unconnected FBS in a hidden lane with a count",
+  "context": "The viewer UI refresh (design doc section 7) names a DAG for the Build tab's second sub-tab. The dogfood tree has 87 FBS: 46 declare no dependency, 36 are unconnected both ways, 1 is in progress and `estimatedHours` is sparse. A force-directed layout is unstable across reloads (the review surface is a diff-worthy artefact; identical trees must render identical pages), and grouping purely by `domain` hides the thing the DAG exists to show (which FBS feeds which). The v1 rcf-tools DAG proved the tiered layout works for the engineer audience the Build tab serves (decision 14); its gaps - dark-only palette, no inspector, orphan pile-up swamping the graph, no deep links, horizontal page scroll - are the ones this PR fixes.",
+  "decision": "Columns in the DAG are dependency-depth tiers computed from `dependsOnFbsIds` (0 for an FBS that declares no dependency; max over `depth(dep) + 1` otherwise). Rows inside a column are `buildOrder` ascending with `fbsId` lexicographic tie-break. Critical path is the longest chain by node count across the DAG, because `estimatedHours` is sparse on the dogfood tree (section 7 gap b); the critical-path chip highlights every member of that longest chain. Unconnected FBS - no incoming and no outgoing `dependsOnFbsIds` edge - sit in a lane below the main graph, hidden by default, with the count on the toggle. Cycle members (should any appear) are excluded from the depth layout and surfaced as a shared `findings-list` finding on the toolbar; non-cycle FBS still render so one bad edge never blocks the view (AC-204-6). The selection round-trips `#tab=build&sub=dag&entity=<id>` through the existing writeHash so a node is a link (decision 11, extended).",
+  "consequences": "The DAG is deterministic across reloads: same tree, same page. The depth tiers reflect what actually gates work, so the leftmost column is the \"start here\" set and buildable-now items concentrate on its right edge. Hiding unconnected FBS by default stops the 36-row pile-up swamping the dogfood tree - the toggle count makes them discoverable. Choosing node count for the critical path means the chip stays meaningful on the dogfood tree today and will only sharpen when `estimatedHours` fills in; the ADR explicitly leaves the hours-weighted critical path to a later change. Deep-link parity with Specs (`#tab=build&sub=specs&entity=<id>`) lets the inspector's Open-in-Specs link move cleanly across the two sub-tabs.",
+  "alternativesConsidered": [
+    {
+      "name": "Force-directed layout",
+      "summary": "Lay nodes with a physics simulation and let the dependency edges settle.",
+      "reasonNotChosen": "Position jitters across reloads so screenshots and visual diffs are noisy; the review surface is diff-worthy by contract, and a layout that is not deterministic cannot be screenshotted into design evidence or compared across runs."
+    },
+    {
+      "name": "Group by domain only",
+      "summary": "Columns are areas (view, cli, build, ...) and rows are FBS in each area.",
+      "reasonNotChosen": "Hides the dependency structure that the DAG exists to show. Area is already a FilterBar facet on the Specs sub-tab and a badge on each node; adding a second encoding of it costs the dependency axis."
+    },
+    {
+      "name": "Hours-weighted critical path",
+      "summary": "Measure critical path by sum of `estimatedHours` along a chain.",
+      "reasonNotChosen": "`estimatedHours` is sparse on the dogfood tree (section 7 gap b); a weight that is missing on most nodes would silently bias the chip toward whichever subtree happens to have estimates. Node count is the honest signal today; the hours-weighted path becomes an opt-in once estimates are populated across the tree."
+    },
+    {
+      "name": "Render unconnected FBS inline (no lane)",
+      "summary": "Lay unconnected FBS as a 36-row column 0 alongside the connected tier 0.",
+      "reasonNotChosen": "Doubles the visual height of the leftmost column with nodes that have no edges, swamping the dependency graph the DAG exists to show. The toggled lane with the count keeps them one click away without the pile-up."
+    },
+    {
+      "name": "Block the DAG on any cycle",
+      "summary": "If the tree carries a `dependsOnFbsIds` cycle, refuse to render the DAG and show an error.",
+      "reasonNotChosen": "A bad edge on a 90-node graph should not take the view down; the `rcf validate` CLI is the enforcement surface. The DAG reports the cycle as a shared finding and renders the rest so the engineer can see what still composes."
+    }
+  ]
+}

package/rcf/adrs/adr-4134-index-json-route.json

@@ -0,0 +1,35 @@
+{
+  "createdAt": "2026-10-02T19:00:00Z",
+  "updatedAt": "2026-10-02T19:00:00Z",
+  "adrId": "ADR-4134-index-json-route",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The ID lookup index is served as a new ./index.json route, built from BuiltTreeModel on every rewalk and fetched lazily on first open",
+  "context": "The viewer UI refresh (design doc section 6) adds a type-ahead ID lookup over every document id plus every AC. On the dogfood tree that is roughly 1,600 rows and well under 300 KB of JSON. The viewer is served through wespa's reverse proxy; new routes 404 until wespa's allow-list is extended (Dex, 2026-10-02; design section 9), so every new route must be named in the release notes alongside the version that introduces it. The viewer page is already live-updated through an SSE tree-update event, so an index that mirrors the tree needs to refresh on the same event. The alternatives considered were inlining the index into `./scope.json` or rebuilding the index in the browser; both have load-bearing downsides.",
+  "decision": "The index is a new `./index.json` route served from the viewer, built once per rewalk from BuiltTreeModel and returned as `{ rows: Array<{ id, kind, title, snippet, parent, tab }> }`. The route is fetched lazily on first LookupModal open and refreshed when the next SSE `tree-update` event lands (the client marks its cache dirty and refetches on the next open). The route is named in the release notes so wespa's proxy allow-list is extended before the version pin bump; it is the fourth or later such release-noted viewer route after PR 1's `./page-init.js`.",
+  "consequences": "The browser pays one small fetch on the first lookup and nothing on subsequent opens until the tree changes; the server owns the index projection once per rewalk, so the model-to-rows mapping cannot drift between the viewer's doc renderers and the lookup results. The release-notes contract means every new viewer route the embedding host must allow is discoverable from CHANGELOG. The index body is `{ rows }` rather than a bare array so a future field (version, generatedAt, counts) can be added without a breaking shape change.",
+  "alternativesConsidered": [
+    {
+      "name": "Inline the index into ./scope.json",
+      "summary": "Extend the existing deep-link scope endpoint to carry the lookup rows.",
+      "reasonNotChosen": "`./scope.json` is a hot path on every page load and is parsed by the deep-link client; bloating it with ~1,600 lookup rows pays the fetch cost even for sessions that never open the modal, and couples two independent features."
+    },
+    {
+      "name": "Rebuild the index in the browser from the rendered DOM",
+      "summary": "Walk the DOM after each SSE innerHTML swap to collect every data-doc-id and AC li.",
+      "reasonNotChosen": "Duplicates the BuiltTreeModel projection in the viewer client, misses the kind, parent and tab metadata the DOM does not carry in a canonical shape, and silently drifts when a renderer stops emitting a given document."
+    },
+    {
+      "name": "Inline the index into the shell HTML as a <script type=\"application/json\">",
+      "summary": "Server-render the rows directly inside the page so no second request is needed.",
+      "reasonNotChosen": "Grows every first paint by ~300 KB even when the lookup is never opened and leaks straight into the HTML stream the live client swaps on every SSE tree-update, so the cost is paid again per update. The modal is a cold path; the lazy fetch is cheaper."
+    },
+    {
+      "name": "Keep the index unversioned and refetch on a wall-clock timer",
+      "summary": "Have the client poll `./index.json` every N seconds instead of listening to the SSE event.",
+      "reasonNotChosen": "Breaks the viewer's live-swap discipline: the rest of the surface refreshes on `tree-update` with no polling anywhere, so an index that polls would be the only timer-driven feature and race the SSE swap during edits."
+    }
+  ]
+}

package/rcf/adrs/adr-4135-readiness-po-register-and-adapter.json

@@ -0,0 +1,35 @@
+{
+  "createdAt": "2026-10-02T19:30:00Z",
+  "updatedAt": "2026-10-02T19:30:00Z",
+  "adrId": "ADR-4135-readiness-po-register-and-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The Readiness tab fixes its two-audience split by the profile register and uses a feature-detected adapter seam for the PO question block",
+  "context": "The viewer UI refresh (design doc section 1 decision 1 and section 8) splits the Readiness tab into a product-owner-first layer and a For-engineers DocRow at the foot. The chain's DEFINE step 3 PR 2 reserves a new `readiness.questions[]` shape built by `computeQuestions`; until that lands the viewer still has to render the PO question block from today's `personas.productOwner.blockers`. The design doc section 11 recommendation 4 asks for the phrasebook now so the pilot does not wait on DEFINE step 3. Baz's amendment 12 of 2026-10-02T13:40Z requires both VerdictCards to render at equal height with the chain term muted beside the plain label on both cards (`intent-complete`, `ready-to-build`).",
+  "decision": "The Readiness tab fixes its two-audience split by the `profile.register`: `productOwner` or absent / unstated opens the four PO blocks and keeps the For-engineers DocRow closed; `engineer` opens the For-engineers DocRow at the foot. No tab changes shape or wording by where the tree sits in DEFINE (decision 14). The phrasebook ships now (one entry per row of design doc section 8's PO question table, keyed by check id) and the adapter seam `toQuestions(readiness)` is a pure module exported from src/view/readiness/question-adapter.js: it reads blockers today and switches to `readiness.questions` when the shape is present (feature-detected via `preferReadinessQuestions(readiness)`); the call site in the tab reads only the adapter output. The engineer DOM is never removed, only collapsed under the DocRow (AC-18002-3). The CLI verdict strings keep rendering inside the For-engineers DocRow verbatim.",
+  "consequences": "The pilot can land PR 8 ahead of DEFINE step 3 PR 2 without a second rewrite when the questions shape arrives; the switch is one feature-detect line and the shape is drop-in. The two-audience split is deterministic (the register alone decides opening state) so the Remi pilot never sees a tab that reshapes under its feet as the tree moves through DEFINE. The engineer DOM invariant guards parity with `rcf define readiness --json`: every id the CLI prints is still in the viewer's DOM, just one level down. Equal-height VerdictCards and the muted chain term land once, from CSS, so no scripted measurement is needed.",
+  "alternativesConsidered": [
+    {
+      "name": "Wait for DEFINE step 3 PR 2 to land `readiness.questions` before shipping PR 8",
+      "summary": "Postpone PR 8 until the questions compute is in place so the viewer never reads blockers directly.",
+      "reasonNotChosen": "Blocks the Remi pilot and the hand-over for a chain PR whose timing is not in this surface's control. The adapter seam is the smallest possible layer that lets both sources flow through one shape, so the extra module today is a one-day cost that buys weeks of parallel progress."
+    },
+    {
+      "name": "Re-render the tab by DEFINE progression state (open For-engineers once the PO blocks pass)",
+      "summary": "Have the Readiness tab change shape based on where the tree sits in DEFINE (so the engineer view only appears when the PO view is empty).",
+      "reasonNotChosen": "Contradicts decision 14 (`two audiences, fixed by tab, never by progression state`). An engineer looking at the tab mid-DEFINE loses the engineer view they rely on, and a product owner who reaches intent-complete suddenly sees a block that was never there before. The register is the audience; the state is not."
+    },
+    {
+      "name": "Remove the engineer blockers from the DOM in the productOwner register",
+      "summary": "Hide the engineer-level findings entirely when `profile.register === 'productOwner'` so the page is quieter.",
+      "reasonNotChosen": "AC-18002-3 is must-not for a reason: hiding a persona breaks parity with `rcf define readiness --json`. A collapsed DocRow carries the signal the diagnostic needs without crowding the PO view."
+    },
+    {
+      "name": "Script equal-height cards with ResizeObserver",
+      "summary": "Measure both VerdictCards after render and copy the taller height onto the shorter one.",
+      "reasonNotChosen": "The relative-script policy (PR 1) keeps the shell free of inline script and keeps the DOM a server render that the SSE path can swap wholesale. CSS grid or flex with `align-items: stretch` on a shared parent gives equal height for free and survives theme swaps."
+    }
+  ]
+}

package/rcf/adrs/adr-4136-embedding-host-fixture.json

@@ -0,0 +1,35 @@
+{
+  "createdAt": "2026-10-02T20:00:00Z",
+  "updatedAt": "2026-10-02T20:00:00Z",
+  "adrId": "ADR-4136-embedding-host-fixture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The embedding contract is pinned by a CI host fixture; three lints keep framing, target='_top' and localStorage namespace in place; the fixture does not persist theme itself so a passing run proves the iframe reads the message",
+  "context": "Dex's wespa requirements (2026-10-02; `docs/2026-10-02_dex-wespa-embedding-requirements.md`) and the viewer UI refresh design section 9 pin the viewer's embedding contract: same-origin iframe behind wespa's reverse proxy under `/rcf-viewer/`, `embed=1` suppresses the title block and footer, `theme=light|dark|auto` on first paint, `{ type: \"rcf-view-theme\", theme }` postMessage with `event.origin` checked for live changes, viewer fills 100% viewport height and owns its scrolling, no framing-blocking headers, no `target=\"_top\"` links, localStorage namespaced under `rcf-view:v1:`, no outbound postMessage from the viewer. Wespa smoke on the live wespa shell is Dex's side; a regression there would reach wespa before the viewer saw it, so the viewer needs its own proof in CI. Unit-testing the message handler without an iframe does not prove framing works (a `X-Frame-Options` or wrong CSP would break the live embed and pass the unit test).",
+  "decision": "Ship a same-origin test-host fixture served by the viewer's own dev server at `/test-host.html` (plus `/test-host.js` for the client-side wiring) that mimics the wespa shell: a 56px header carrying a Light/Dark/Auto theme toggle, a resizable sidebar (64px collapsed, 200-400px expanded, user-resizable live via a drag handle), a content pane carrying a single `<iframe src=\"./?embed=1&theme=light\">`. The fixture is off the default route surface - gated on a `--test-host` CLI flag or the `RCF_VIEW_TEST_HOST=1` env var and 404s otherwise - so wespa's proxy allow-list is unaffected. Three lints run in the test suite: (1) framing lint on `GET /` (no `X-Frame-Options`, no CSP `frame-ancestors` that forbids same-origin); (2) `target=\"_top\"` grep over every rendered page (zero occurrences); (3) localStorage namespace grep over `src/view/**` (every key starts with `rcf-view:v1:`). The fixture does not persist its theme choice to localStorage so a passing run proves the iframe reads the postMessage (and not the host's own storage).",
+  "consequences": "The viewer's suite catches a framing regression (headers, `target=\"_top\"`, un-namespaced localStorage key) before it reaches wespa. The fixture is the first production use of the test-host surface, so a `--test-host` flag plus env guard is established as the pattern for every future embedding-shell fixture (adding a `/test-host/<other>.html` becomes a one-liner on the router). Keeping the fixture off the default route surface means the release notes do not need to extend wespa's proxy allow-list for every lint test; a later PR that wants to ship the host alongside the viewer can do so without re-platforming the fixture itself. The lints run on the dogfood tree today and fail on main if a future PR adds a framing-blocking header or writes to localStorage with a non-namespaced key, so the viewer PR that introduces the regression carries the fix in the same commit.",
+  "alternativesConsidered": [
+    {
+      "name": "Wespa-side-only smoke",
+      "summary": "Let wespa test the viewer's embedding against the live wespa shell; the viewer ships no proof of its own.",
+      "reasonNotChosen": "A regression lands on main before wespa sees it; wespa's smoke runs on a different repo on a different cadence, so a viewer refactor that drops `embed=1` or writes an un-namespaced localStorage key breaks every embedder and the viewer's own CI is clean. The lints run in the viewer's suite catch the regression at the PR that introduces it."
+    },
+    {
+      "name": "Unit-test the message handler without an iframe",
+      "summary": "Drive the viewer's `rcf-view-theme` postMessage handler through `node:vm` or a jsdom shim and assert the handler flips `data-theme`.",
+      "reasonNotChosen": "Does not prove framing. A later PR that adds `X-Frame-Options: DENY` to `GET /` would pass the unit test and break every embedder. The host fixture exercises the whole stack: HTTP headers, iframe mount, postMessage, data-theme stamp."
+    },
+    {
+      "name": "Ship the test host under the default route surface",
+      "summary": "Serve `/test-host.html` unconditionally; a developer can hit it directly to eyeball the embed.",
+      "reasonNotChosen": "Wespa's proxy allow-lists routes; a new default-on route needs an allow-list extension and a release-note version pin. The fixture is a test-suite proof, not a shipped UI; keeping it behind `--test-host` / `RCF_VIEW_TEST_HOST=1` means the production route surface stays `/`, `/events`, `/live-client.js`, `/page-init.js`, `/style.css`, `/mermaid.min.js`, `/product-map/*`, `/scope.json`, `/index.json`, `/_fixtures/components`."
+    },
+    {
+      "name": "Persist the theme in the host fixture itself",
+      "summary": "Store the Light/Dark choice in `localStorage` on the host so a reload keeps the toggle state.",
+      "reasonNotChosen": "A passing run would then not prove the iframe honours the postMessage: the host could set `data-theme` on the iframe URL and the iframe would never need to read the message. By refusing to persist, the fixture forces every theme flip through the postMessage path."
+    }
+  ]
+}

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"
+}

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

@@ -0,0 +1,15 @@
+{
+  "cnId": "CN-721",
+  "path": "src/define/freeze-record.js",
+  "title": "Freeze record I/O: load, save, validate",
+  "description": "Owns rcf/define/freeze.json. FREEZE_RECORD_REL_PATH, FreezeRecordError (coded parseFailure | schemaFailure | ioFailure with a named field), validateFreezeRecord, loadFreezeRecord (returns null on ENOENT), saveFreezeRecord (validates first; refuses to persist an invalid record; creates rcf/define/ on demand; writes pretty JSON with a trailing newline). The record's local schema is documented at the top of this file and covered by test/define/freeze-record.test.js.",
+  "implementsAcIds": [
+    "AC-17201-3",
+    "AC-17201-4"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,15 @@
+{
+  "cnId": "CN-722",
+  "path": "src/define/ledgers.js",
+  "title": "Four sidecar ledgers: load, save, validate, add, resolve",
+  "description": "Pure module. LEDGER_NAMES (brief, decisions, concerns, probes), BRIEF_KINDS closed vocabulary, LedgerError with coded reason and named field, ledgerRelPath / ledgerPath, emptyLedger, loadLedger (empty on ENOENT), saveLedger (validates first), validateLedger, addEntry (mints next id, stamps addedAt, defaults status open, validates the whole body), resolveEntry (flips status to resolved, stamps resolvedAt, refuses unknown id), parseBriefFromFile (splits by non-empty lines, strips '- ', '* ', '<n>. ' bullets), loadAllLedgers (returns a LedgerBundle for computeDelta).",
+  "implementsAcIds": [
+    "AC-17301-1",
+    "AC-17301-3"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "cnId": "CN-723",
+  "path": "src/cli/ledger.js",
+  "title": "rcf define ledger CLI verb",
+  "description": "Wraps src/define/ledgers.js with parseArgs and per-verb usage text. Dispatches ledger <name> <verb> where name is brief | decisions | concerns | probes and verb is add | resolve | list. renderDecisionsList prints the numbered #241 format (one decision per item, letter) options, default:, blocks:). list --json emits { ledger, <arrayKey>: [...] }. bin/rcf.js registers this under GROUPS.define.ledger; src/cli/help.js wires HELP into HELP_MAP.define.ledger and extends the DEFINE_HELP and top-level listing blocks so 'rcf help define ledger' and 'rcf define ledger --help' render the same text by construction.",
+  "implementsAcIds": [
+    "AC-17301-1",
+    "AC-17301-2",
+    "AC-17301-3"
+  ],
+  "dependencies": [
+    "CN-722"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,14 @@
+{
+  "cnId": "CN-724",
+  "path": "test/store/walker-invisible-define.test.js",
+  "title": "Invariant test: walker never surfaces rcf/define/ files",
+  "description": "One-scenario test that seeds a fresh project (initProject), writes rcf/define/freeze.json, the four ledger files and a bug-bait req-999.json under rcf/define/, then runs walkTree and asserts no error path starts with rcf/define/ and no such file lands in tree.byId. The invariant is what keeps the sidecars out of every existing tree consumer (proposal 2026-09-22 section 2.1).",
+  "implementsAcIds": [
+    "AC-17301-4"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T12:00:00Z",
+  "updatedAt": "2026-09-24T12:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "cnId": "CN-725",
+  "path": "src/query/gates.js",
+  "title": "DEFINE stage gates D1..D8 pure check functions",
+  "description": "Pure module. One check function per stage D1..D8 (checkD1Brief..checkD8Freeze) plus STAGE_ORDER, STAGE_GATES, STAGE_SHORT_NAMES, INTERFACE_KINDS. Each takes (tree, context) and returns { stage, gate, state, checks[] } in the section 2.4 shape.",
+  "implementsAcIds": [
+    "AC-17401-1",
+    "AC-17401-2",
+    "AC-17401-3",
+    "AC-17401-4",
+    "AC-17401-5",
+    "AC-17401-6",
+    "AC-17401-7",
+    "AC-17401-8",
+    "AC-17401-9",
+    "AC-17402-1",
+    "AC-17402-2",
+    "AC-17402-3",
+    "AC-17402-4",
+    "AC-17402-5",
+    "AC-17402-6",
+    "AC-17402-7",
+    "AC-17403-1",
+    "AC-17403-2",
+    "AC-17403-3",
+    "AC-17403-4",
+    "AC-17403-5",
+    "AC-17403-6",
+    "AC-17403-7",
+    "AC-17403-8"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "cnId": "CN-726",
+  "path": "src/query/readiness.js",
+  "title": "computeReadiness composes delta + fan-out + gates + coverage + decisions",
+  "description": "Pure module. computeReadiness returns the section 2.4 object; internal composeStages calls TAC-4122's gate functions in D1..D8 order; deriveNextAction picks the first failing check; freezeable folds the eight stage states.",
+  "implementsAcIds": [
+    "AC-17501-1",
+    "AC-17501-2",
+    "AC-17501-3",
+    "AC-17501-4",
+    "AC-17502-1",
+    "AC-17502-2",
+    "AC-17502-3",
+    "AC-17502-4",
+    "AC-17502-5",
+    "AC-17502-6",
+    "AC-17502-7",
+    "AC-17502-8"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,23 @@
+{
+  "cnId": "CN-727",
+  "path": "src/cli/readiness.js",
+  "title": "rcf define readiness [--json] [--check <stage>|all] [--level intent|build] [--persona productOwner|engineer]",
+  "description": "CLI handler. Parses --json / --check / --level / --persona / --help; walks the tree; loads freeze + all four ledgers; resolves test pointers; wraps computeReadiness with runWithAdmissibilityGate; emits text (with the two verdict lines + persona-grouped blocker sections ordered by the profile.md register) or JSON (with _meta.level carrying the invocation); the exit matrix in spec section 3.2 folds --check and --level per decision 4.",
+  "implementsAcIds": [
+    "AC-17501-5",
+    "AC-17503-1",
+    "AC-17503-2",
+    "AC-17503-3",
+    "AC-17503-4",
+    "AC-17503-5",
+    "AC-17503-6",
+    "AC-17503-7",
+    "AC-17503-8",
+    "AC-17503-9"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-10-01T16:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "cnId": "CN-728",
+  "path": "test/query/gates.test.js",
+  "title": "Unit tests for stage gates D1..D8",
+  "description": "Covers AC-17401-1..8: return shape, blocking-vs-warn-with-ack fold, notApplicable rules, D4 floors + per-class opt-outs, D3 interface kind vocabulary, D5 cheap checks, D6 validate + probe count, D8 tree-wide freeze checks.",
+  "implementsAcIds": [
+    "AC-17401-1",
+    "AC-17401-2",
+    "AC-17401-3",
+    "AC-17401-4",
+    "AC-17401-5",
+    "AC-17401-6",
+    "AC-17401-7",
+    "AC-17401-8",
+    "AC-17401-9",
+    "AC-17402-1",
+    "AC-17402-2",
+    "AC-17402-3",
+    "AC-17402-4",
+    "AC-17402-5",
+    "AC-17402-6",
+    "AC-17402-7",
+    "AC-17403-1",
+    "AC-17403-2",
+    "AC-17403-3",
+    "AC-17403-4",
+    "AC-17403-5",
+    "AC-17403-6",
+    "AC-17403-7",
+    "AC-17403-8"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}

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

@@ -0,0 +1,26 @@
+{
+  "cnId": "CN-729",
+  "path": "test/query/readiness.test.js",
+  "title": "Unit tests for computeReadiness",
+  "description": "Covers AC-17501-1..4 and AC-17501-6: section 2.4 shape, fan-out impacted/impactedFbs, coverage tree + per-REQ, nextAction pick, loadAllLedgers-omits-absent.",
+  "implementsAcIds": [
+    "AC-17501-1",
+    "AC-17501-2",
+    "AC-17501-3",
+    "AC-17501-4",
+    "AC-17501-6",
+    "AC-17502-1",
+    "AC-17502-2",
+    "AC-17502-3",
+    "AC-17502-4",
+    "AC-17502-5",
+    "AC-17502-6",
+    "AC-17502-7",
+    "AC-17502-8"
+  ],
+  "dependencies": [],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-24T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z"
+}