rcf-lite 0.28.4 → 0.29.0

package/CHANGELOG.md

@@ -6,11 +6,117 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+
+## [0.29.0] - 2026-10-03
+
+0.29.0 lands the viewer UI refresh train (nine PRs that rebuild the shell, add shared components, redesign the Requirements, Architecture, Build and Readiness tabs, ship a Build DAG sub-tab, add fast ID lookup, and prove the embedding contract with a same-origin test-host fixture), the DEFINE readiness persona split (two readiness levels, `--level` and `--persona` on `rcf define readiness`, a Readiness tab as tab 1), and the first three DEFINE step 3 PRs (document intake into the brief ledger with the closed `resolvedBy` grammar, a `rcf define questions` verb with three new MCP tools and two argument-free prompts for the harness loop, and the `[draft]` shapes gate across TAC purpose, interface and core-entity homes with a DISCOVERY prototypes doctrine). The brief said 0.29.0 was never tagged; it is tagged here, and the spec sections that referred to those D2 behaviours as "0.30.0" now read 0.29.0.
+
+Scope note: DEFINE step 3 PR 5 (D3 bite) is still on the cloud at cut time and is NOT included; it rides a later minor. Spec amendment note: `projects/rcf-lite-wsd/specs/2026-10-01_define-step3-po-elicitation-spec.md` section 16 and every "0.30.0" reference to the D2 `skeleton:resolvedBy` tightening, the `rcf define ledger <name> update <id>` subverb and the `resolvedBy` closed grammar should read "0.29.0" at the next amendment pass.
+
+### Added
+
+- **Viewer UI refresh PR 1 of 9: shell, brand tokens, theme contract, embed contract, Router and relative asset refs (`#263` + `#265`; w-2026-10-02-dave-017).** AppShell with a compact header (icon mark, product block, sticky tabstrip, tools well) and a one-line footer carrying version, GitHub, docs links and the live-update pill. Full `--sv-*` Stravica brand token set under `:root[data-theme="light"]` and `:root[data-theme="dark"]` with a `prefers-color-scheme` fallback; pre-PR-1 `--colour-*` names kept as aliases so doc-renderer, Mermaid and Product Map rules get dark theme for free. `theme=light|dark|auto` and `embed=1` on `/`; live theme switch via same-origin `postMessage({ type: "rcf-view-theme", theme })` (origin checked). Router (`#tab=&sub=&entity=`) with bare-id compatibility and query-string preservation on every hash write. Relative asset and stream refs for embedding: `./style.css`, `./mermaid.min.js`, `./page-init.js`, `./live-client.js`, `./events`, `./scope.json`, `./product-map/<group>`. Inline-script-free shell: the former inline IIFE lives in `src/view/page-init.js` served by a new relative route (see "For embedders" below).
+- **Viewer UI refresh PR 2 of 9: shared components layer and shell polish (#266; w-2026-10-02-dave-010).** Six shared component helpers under `src/view/components/` land for the per-tab cutover PRs: `DocRow`, `FilterBar`, `Badge`, `EmptyState`, `Toast`, `SubTabStrip`, with matching `.rcf-*` CSS. Toast container mounted once in the shell outside `#rcf-live-content` so the SSE innerHTML swap cannot blow it away. `/_fixtures/components` route renders every shared component in isolation with sample data. Shell polish per decision 17: `resolveProductHeader()` returns the project name only; no technology chip under any register.
+- **Viewer UI refresh PR 3 of 9: Requirements tab and PRD EntitySelector (#268; w-2026-10-02-dave-025).** Requirements tab under `#tab=requirements` ships a FilterBar (text, Area, Priority, Status, Needs-work toggle), Expand/Collapse all and a live count; FilterBar state mirrors into the hash. DocRow per REQ carries `data-domain`, `data-priority`, `data-status`, `data-needswork`, `data-text`; row body has nested per-US DocRows with the full renderUserStory body, slice diagram and raw-JSON disclosure as collapsed `<details>` so first-paint stays cheap. `#entity=US-304` resolves to REQ-003 and US-304; bare `#entity=<id>` works. Needs-work set sourced from `model.readiness.levels.intentComplete.blockedBy` filtered to the engineer-plain reasons (viewer never re-runs gates). PRD tab (`#tab=overview` for hash backwards compatibility) collapses the five lists into `<details>` with count badges, drops the 109 inline requirement links, and mounts a shared EntitySelector below the article (bold total line, type-ahead jump input, 21 area chips deep-linking into `#tab=requirements&domain=<area>`). Component payload data rides on `data-*` attributes, never inline `<script>` bodies.
+- **Viewer UI refresh PR 4 of 9: Architecture tab with TAD sections and TAC/ADR filters (#269; w-2026-10-02-dave-026).** Six TAD sections (`systemOverview`, `architecturePrinciples`, `integrationArchitecture`, `operationalConcerns`, `dataArchitecture`, `securityArchitecture`) render as shared `DocRow` with a one-line preview, closed by default. Absent sections keep their heading, read "Nothing written yet" with an `empty` badge, and name the exact authoring command `rcf define update TAD-001 --set <section>.<field>="..."`. Components (TAC) and Decisions (ADR) panels each use shared `FilterBar` plus `DocRow` list; TAC rows carry interface and dependency count badges, ADR rows carry a status pill sized against the dogfood vocabulary. Hash scheme extends: `#tab=architecture[&cq=...][&cstatus=...][&dq=...][&dstatus=...][&open=<tad-section-keys>]`. Raw TAD JSON kept as a muted collapsed disclosure at the foot of the tab.
+- **Viewer UI refresh PR 5 of 9: Build tab with Specs and sub-tab strip (#271; w-2026-10-02-dave-027).** SubTabStrip "Specs | DAG" inside the Build tab (DAG is a placeholder empty state at PR 5; PR 6 wires it). BuildStats card with six totals read from `computeQueue({ fbsItems })` (items, verified, complete, in progress, not started, buildable now = `queue.totals.actionable`). Specs FilterBar (text, status, area, size, Buildable-now toggle) over a shared DocRow list. Expanded Spec body: summary, approach, AC and dep links, deliverables, context links (TACs, ADRs, TAD sections), "Show in the DAG" pointer, raw JSON disclosure. Hash scheme extends: `#tab=build[&sub=specs|dag][&q=][&status=][&domain=][&size=][&buildable=1]`.
+- **Viewer UI refresh PR 6 of 9: Build/DAG sub-tab (#272; w-2026-10-02-dave-031).** Lands DagCanvas, DagInspector, DagToolbar and the unconnected lane: depth-by-`dependsOnFbsIds` columns, buildOrder rows, node-count critical path (longest chain), hidden unconnected lane with a visible count. Click-to-highlight closure (upstream outlined in link colour, downstream in warning, rest dimmed); inspector lists direct needs and waits-on with Open-in-Specs; `#tab=build&sub=dag&entity=FBS-<n>` deep-links. Inspector payload rides on a `data-rcf-dag-inspector-data` attribute, never an inline `<script>` body. Chain: REQ-002 amended, US-204 new (seven ACs), TAC-4131, ADR-4133.
+- **Viewer UI refresh PR 7 of 9: ID lookup over `./index.json` (#275; REQ-002 / US-205; TAC-4132; ADR-4134).** The viewer serves a new relative route `./index.json` built from `BuiltTreeModel` on every rewalk, one row per document id plus one per AC, carrying `{ id, kind, title, snippet, parent, tab }` (`src/view/view-index.js` + `src/server/routes.js` + `src/server/index.js`). A SearchButton renders to the right of the tabstrip and a LookupModal mounts outside `#rcf-live-content` so the SSE innerHTML swap cannot blow it away; Cmd/Ctrl+F opens the modal from any tab (Cmd/Ctrl+Shift+F stays the browser's in-page find). Type-ahead ranks id matches first (exact > prefix > contains); then every query word must match title or snippet, title above snippet; a single character searches ids only; 20 results; matches marked. The index is fetched lazily on first open and refreshed when the next SSE `tree-update` event lands (`__rcfLookupDirty` is set in `src/view/live-client.js`). A pick writes `#tab=<tab>&entity=<id>` through the existing writeHash so `?embed=` and `?theme=` survive every navigation. Keyboard: up/down/Enter/Esc; the modal is a `role="dialog"` with `aria-modal`, labelled live-region status, and the SearchButton is `aria-label`-ed as `Find any document or AC (Cmd/Ctrl+F)`. The new relative viewer route is `./index.json` (released alongside PR 1's `./page-init.js`; wespa's reverse-proxy allow-list is extended before the version pin bump).
+- **Viewer UI refresh PR 8 of 9: Readiness tab Product Owner redesign (#277; REQ-180 / US-18002 / TAC-4133 / ADR-4135; w-2026-10-02-dave-033).** PO layer with two equal-height VerdictCards (muted chain term on both), QuestionCards grouped by source span, Requirements-that-still-need-work table, and a "For engineers" DocRow at the foot that collapses the pre-PR-8 engineer rendering (never removed from the DOM in any register, per AC-18002-3). Readiness phrasebook ships now. Feature-detected adapter seam consumes DEFINE step 3 PR 2's `computeQuestions` output on the real path and falls back to the blockers path with phrasebook asks when it is absent. `src/view/index.js` folds `computeQuestions(readiness, { tree, ledgers, profileText, persona: 'productOwner' })` onto `readiness.{questions,questionGroups,questionOptional,questionEngineer}` before the view reads it, so the two sources render identical labels on the dogfood tree.
+- **Viewer UI refresh PR 9 of 9: embedding proof via a same-origin test-host fixture (#279; REQ-002 / US-206; TAC-4134; ADR-4136; w-2026-10-02-dave-034).** `src/view/test-host/` (`fixture.js`, `embed-client.js`, `lints.js`) and routes `GET /test-host.html` and `GET /test-host.js` served ONLY behind `--test-host` (CLI) or `RCF_VIEW_TEST_HOST=1` (env), 404 by default so wespa's reverse-proxy allow-list is unaffected. The fixture ships a 56 px header, a resizable sidebar (64 to 400 px) and a toggle posting `rcf-view-theme`. Three in-suite guards pin the embedding contract: framing headers absent (no `X-Frame-Options`, no CSP), zero `target="_top"` across all served responses, and every `src/view` storage key under the `rcf-view:v1:` namespace.
+- **DEFINE viewer: Readiness tab as tab 1 and Overview-to-PRD rename (#262; REQ-180 / REQ-181 / US-18001 / US-18101; TAC-4127; ADR-4127; w-2026-10-01-dave-003 PR C).** `src/view/readiness.js` lands and `src/view/html-page.js` wires it as the first tab of the HTML review surface. The former Overview tab is renamed PRD (label-only; the `data-tab="overview"` identifier and `id="tab-overview"` are preserved so every existing `#tab-overview` hash link still resolves). The tab renders the `computeReadiness` object top-to-bottom in the layout spec section 5 pins: tree line, two verdict pills with `formatVerdictLines` strings as labels, two per-persona next-action lines, D1 to D8 state chips, blockers grouped by persona (register orders the pair; the non-register group collapses with its count visible, never omitted), delta list grouped by REQ ancestor with a document-level `diff` on changed items, per-stage check detail, coverage tree-versus-delta, decisions outstanding, a Freeze now control enabled iff `levels.readyToBuild.ok`, and the loaded freeze record. The renderer is pure: it never recomputes readiness or hits disk. Three shared view components (`src/view/components/{pill,findings-list,diff}.js`) land as additive modules.
+- **DEFINE readiness CLI: `--level` and `--persona` flags, persona-grouped text report (#261; ADR-4126; REQ-175 / US-17503; TAC-4123; w-2026-10-01-dave-003 PR B).** `rcf define readiness` gains `--level intent|build` and `--persona productOwner|engineer`. `--level intent` exits 4 iff `levels.intentComplete.ok === false`, `--level build` exits 4 iff `levels.readyToBuild.ok === false` (stricter than `--check all` on unacknowledged warn-with-ack failures; the `[warn]` line still prints). When both `--check` and `--level` are given, the invocation exits 4 if either policy says 4. With neither flag the exit code stays 0. `--persona` is a display filter only: it never affects the exit code or `--json` content, and is ignored under `--json`. Unknown values exit 2 with a usage line naming the accepted set. The text report prints both verdict lines at the top, then groups blockers into a `Product owner: N question(s)` section and an `Engineer: N check(s) blocking` section ordered by the `profile.md` register (PO first when `register: productOwner` or when the marker is `unstated`/absent; engineer first when `register: engineer`). The JSON gains `_meta.level` reflecting the invocation (`"intent"`, `"build"` or `null`).
+- **DEFINE readiness: persona tags on every gate check, two readiness levels (#260; ADR-4126; REQ-174 / US-17402 / US-17403 and REQ-175 / US-17502; TAC-4122 and TAC-4123; w-2026-10-01-dave-003 PR A).** Every entry in `stages[].checks[]` carries `persona` (`productOwner` | `engineer`) and a one-sentence `question` heading, declared in `CHECK_PERSONA` / `CHECK_QUESTION` maps in `src/query/gates.js`. The `notApplicable` placeholder (`stage:<D>:scope`) carries the `STAGE_FALLBACK_PERSONA` for its stage so the per-check vocabulary is total. `skeleton:reqFields` splits into `skeleton:reqIntent` (productOwner: description without TODO + domain) and `skeleton:reqShape` (engineer: shapeClassification.shapes), each evaluating every REQ independently. `decisions:allAnswered` splits into `decisions:wellFormed` (productOwner) and `decisions:allAnswered` (engineer). A new D3 check `shapes:draftSettled` fails any interface whose `description` starts with `[draft]` (leading whitespace tolerated). `computeReadiness` folds `levels.intentComplete`, `levels.readyToBuild`, `personas.productOwner.blockers` and `personas.engineer.blockers` on every read. `deriveNextAction(stages, persona?)` gains an optional persona filter. New shared helper `formatVerdictLines(result)` builds the two verdict strings. All additions are strictly additive; `rcf define freeze` is untouched and remains L2-only.
+- **DEFINE step 3 PR 1: document intake into the brief ledger, `rcf define ledger <name> update <id>` subverb, closed `resolvedBy` grammar (#270; REQ-187 / US-18701 / US-18702; REQ-173 amended / US-17302; TAC-4121 amended, TAC-4130 new).** `rcf define ledger brief add` grows `--from <statement-file>`, `--scan` / `--no-scan`, `--findings <path>`, `--dry-run` and `--json`; the parser recognises `[kind]` and `(source: ...)` text markers (with `--kind` and `--source` defaults) and promotes `?` / `TBC` / `TBD` / `Open:` / `Question:` to `openQuestion`; unknown `[kind]` exits 2 before any write. The mechanical intake scans run over new statements against existing ones and append `openQuestion` statements per finding (`--no-scan` with `--findings` exits 2). A new `rcf define ledger <name> update <id>` subverb lands on every ledger with the add-side validation; `brief --resolved-by` validates the closed pointer grammar before any write. The D2 `skeleton:resolvedBy` check now parses the pointer against the closed grammar (`REQ-nnn`, `TAD.entity:<name>`, `PRD.user:<name>`, `TAD.system:<name>`, `TAC-nnnn`, `omitted:<reason>`); see Changed for the dropped title-hit fallback. Chain: FBS-202 new (holds the new ACs with `executionStatus: notStarted`; the CN axis is deferred); `docs/capability-tags.md` grows a `define-intake` slug.
+- **DEFINE step 3 PR 2: `rcf define questions` verb, three MCP tools and two argument-free prompts (#274; REQ-186 / US-18601 / US-18602 / US-18603; TAC-4128, TAC-4129; ADR-4129, ADR-4130).** `rcf define questions` turns every failing product-owner check into one plain question carrying its exact write-back (real three-step `create req; define update <REQ-id> --set description=... --set domain=...; ledger brief update ... --resolved-by <REQ-id>` for new REQ; real `create us --parent --title`, `define update <US-id> --json --set story='{...}'` and `create ac --parent --description "[happy] ..."` sequence for new US; `decisions add ...; ledger brief resolve <N> --answer "decision <id>"` for `brief:openQuestions`). Three new MCP tools expose the same compute: `rcf_define_questions`, `rcf_define_readiness`, `rcf_define_ledger`; two argument-free prompts (`rcf_define_intent`, `rcf_define_intake`) steer the harness through the loop. The question extractor reads the full `readiness.stages[].checks[].failing[]` so a check with 25 failing items yields 25 questions (not 20). Termination under `--stage` is `result.ok` alone (not `result.ok || result.remaining === 0`). Stable sort of questions by `(stageIndex, sourceSpan, originalIndex)`.
+- **DEFINE step 3 PR 3: `[draft]` shapes across TAC purpose, interface and core-entity homes; DISCOVERY prototypes doctrine; two new argument-free prompts (#278; REQ-188 / US-18801; REQ-182 / US-18202; ADR-4132).** `parseInterfaceDraft` becomes a thin wrapper over a shared `hasDraftMarker` string test; two sibling readers `parseTacPurposeDraft` and `parseCoreEntityDraft` cover the new homes. `checkD3Shapes` enumerates all three draft homes and emits `shapes:draftSettled` findings with ids `<tacId>:<name>`, `<tacId>` and `TAD.entity:<name>`. D3 `notApplicable` widens to include any tree-wide `[draft]` core entity so a draft-only tree reports under D3 rather than being skipped. `guidance/discovery-prototypes.md` (slug `discovery-prototypes`, `rcf://docs/discovery-prototypes`) lands the doctrine (prototype as elicitation instrument; outputs as `prototype:<name>:<observation>` statements; code burned by a single `constraint`; salvage by re-derivation only). `guidance/discover-prototype.md` wraps it as the argument-free `rcf_discover_prototype` prompt. `guidance/define-draft-shapes.md` lands the argument-free `rcf_define_draft_shapes` prompt. `guidance/manifest.json` registers the slug and the two prompts; the managed block gains the "Prototypes in DISCOVERY (ADR-4132)" rule beside the existing "Prototype rule". `docs/capability-tags.md` grows a `define-drafts` slug.
+
+### Changed
+
+- **DEFINE D2 `skeleton:resolvedBy` tightens to the closed pointer grammar (PR #270, breaking under the pre-1.0 convention; spec amendment: this behaviour was previously named "0.30.0" in the DEFINE step 3 spec section 16 and now ships at 0.29.0).** The 0.28.4 title-hit fallback (a brief statement with `resolvedBy` left as free-form title text was quietly accepted if the title matched any downstream document) is dropped. A pointer that does not parse against the closed grammar (`REQ-nnn`, `TAD.entity:<name>`, `PRD.user:<name>`, `TAD.system:<name>`, `TAC-nnnn`, `omitted:<reason>`) now fails `skeleton:resolvedBy` on D2. Operators with brief ledgers written against 0.28.4 must rewrite non-conforming `resolvedBy` values to the closed grammar; `rcf define ledger brief update <id> --resolved-by <pointer>` validates before write.
+- **Managed agent-instructions block regenerated: adds the "Prototypes in DISCOVERY (ADR-4132)" rule and registers the four argument-free DEFINE/DISCOVERY prompts (PRs #274 and #278).** `scripts/gen-managed-artefacts.mjs` reran on PR 2 and PR 3 of DEFINE step 3; the block hash changed. Agents update their copy of the managed block by rerunning `rcf init` (`minAgentAction: rerun-init`).
+
+### Removed
+
+- **Viewer Build tab: the "FBS slots" ordered list and the "Test suites" section are gone (PR #271).** The Build tab's "Specs" sub-tab replaces both. Suites stay reachable via AC links and PR 7's ID lookup (Cmd/Ctrl+F). Consumers that embedded a deep link into the old Build-tab FBS-slots list need to update to `#tab=build&sub=specs&entity=FBS-<n>` or to the DAG sub-tab `#tab=build&sub=dag&entity=FBS-<n>`.
+
+### Fixed
+
+- **DEFINE D2 skeleton gate reads TAD at the schema-authorised path (#259; w-2026-09-25-dave-004 defect A, REQ-174 / US-17401 / TAC-4122).** `checkD2Skeleton` in `src/query/gates.js` now reads `tad.dataArchitecture.dataStores` and `tad.dataArchitecture.coreEntities` instead of the top-level `tad.dataStores` / `tad.coreEntities` that slice-2 drifted onto. The authority is rcf-schemas 0.6.3 (`tad.schema.json` requires both arrays under `dataArchitecture`), so the previous top-level reads failed `skeleton:tadPersistence` on every valid tree carrying a persistence REQ. The `failing` entry ids tracked the move to `TAD.dataArchitecture.dataStores` and `TAD.dataArchitecture.coreEntities`.
+- **DEFINE D1 brief gate: a fresh `rcf init` tree now satisfies the review-surface marker without operator edits (#259; w-2026-09-25-dave-004 defect B, REQ-174 / US-17401 / TAC-4122).** `src/setup/identity-seed.js` IDENTITY_TEMPLATE now carries a `## Surface` section between `## Register` and `## Project-scoped notes`, mirroring the Register section's shape: a short italicised explanation, one bullet each for `viewer` / `runningApp` / `prDiff`, and a bare `prDiff` line as the default. `checkD1Brief`'s `profile:surface` check now passes on a clean post-init tree. The slice-1 idempotency contract (an existing profile.md is left byte-identical) is preserved.
+
+### For embedders (wespa reverse-proxy)
+
+- **New relative routes shipped since 0.28.4.** `GET /page-init.js` (PR 1), `GET ./index.json` (PR 7). Both must be allow-listed on the wespa reverse-proxy for `/rcf-viewer/*` before the version pin bump, or the proxy returns 404 for `/rcf-viewer/page-init.js` (losing tab wiring, Mermaid lazy render, product-map interactivity, theme boot, embed stamp, origin-checked `postMessage` listener and the hash router) and `/rcf-viewer/index.json` (losing the Cmd/Ctrl+F ID lookup).
+- **No new allow-list routes from PR 9.** `GET /test-host.html` and `GET /test-host.js` are served ONLY when `--test-host` (CLI) or `RCF_VIEW_TEST_HOST=1` (env) is set, and return 404 otherwise. Production wespa does not set the flag, so the allow-list is unchanged by PR 9.
+- **Removed inline script in the viewer shell (PR 1).** CSP hash pin for the inline shell IIFE is no longer needed; the IIFE lives in `src/view/page-init.js` (served by `GET /page-init.js`). Wespa's CSP for `/rcf-viewer/*` should allow the external script in place of the previous inline hash pin.
+- **Live update pill in the footer (PR 1).** Carries connection state (connecting, open, retrying, closed); styled through the `--sv-*` tokens so it tracks the theme.
+- **`embed=1` and `theme=light|dark|auto` query params (PR 1).** `embed=1` stamps `data-embed="1"` on `<html>`, suppresses the title block and footer, and left-aligns the tabstrip; the icon mark and project name remain. `theme` on `/` either stamps `data-theme` (explicit value), clears it (`auto`), or leaves the default light (absent).
+- **Live theme switch via `postMessage({ type: "rcf-view-theme", theme })` (PR 1).** Same-origin only; the viewer's listener checks `event.origin`.
+- **Hash contract (PR 1, extended by PRs 3 to 9).** `#tab=<name>&sub=<name>&entity=<id>` is the canonical hash form; bare `#<id>` and `#entity=<id>` keep working. `?embed=` and `?theme=` and unknown query params survive every in-viewer navigation.
+- **`./index.json` (PR 7).** Lazy JSON index served from the viewer root; refreshed on every SSE `tree-update`.
+
 ## [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
 
+- **DEFINE workflow: `rcf define freeze` CLI verb (REQ-176, first slice of the 0.29.0 train; slices 1 and 2 shipped in 0.28.4 on 2026-09-30).** New module `src/cli/freeze.js` is the only
+  writer of `rcf/define/freeze.json` in the shipped product. It runs
+  `computeReadiness` once (REQ-175) over the live tree, freeze record
+  and four ledgers; refuses (exit 4) on any stage state `failing`
+  after applying any `--ack` acknowledgements; and, on success, writes
+  the freeze record via `saveFreezeRecord` (REQ-172) plus the
+  proposal 2026-09-22 v3 §2.5 summary line the operator signs off.
+  `--ack <gate> --reason <text>` is accepted only for the three
+  warn-with-ack gates (`define.shapes` / D3 / shapes,
+  `define.crosscut` / D5 / crosscut, `define.consistency` / D6 /
+  consistency); `--ack` on any other gate is a usage refusal
+  (exit 2) with a stderr message naming the accepted set. Ack pairs
+  are folded in-memory at the current tree hash and the readiness
+  compute runs with a synthesised freeze context so D8's
+  `priorGates` check sees the acked stages as `acknowledged`. On
+  success the record carries `frozenAt` (ISO UTC now), `treeHash`
+  (from `computeDelta`), `docHashes`, `briefStatements`,
+  `gates` (per-stage envelope including acked entries),
+  `counts` (`req` / `us` / `ac` / `acByClass` / `tac` /
+  `interfaces` by kind / `adr` / `fbs`), `litmus`
+  (`{ attestedAt: [], readers: 0 }` default; `--litmus-attested
+  D3,D6` records the agent's attestation per proposal §9 decision
+  7), `versions` (`rcfLite` / `ruleset` / `schemas` read from
+  package.json, `src/ruleset/ruleset.json` and the installed
+  `@stravica-ai/rcf-schemas`), `note` and `override: null`. The
+  producer is wrapped with `runWithAdmissibilityGate` per ADR-4124;
+  refused admissibility is informational (a stderr `[warn]` line)
+  and never a freeze refusal (ADR-4123 carried). `--status` prints
+  the current record and the live delta summary without running any
+  gates and without writing; `--status --json` emits
+  `{ record, delta }`. `--json` on a freeze success emits
+  `{ record, summary, delta }`. The `--litmus <n>` real-dispatch
+  runner is a named 0.30 seam.
+
+### Changed
+
+- **Freeze record `override` is now a required-nullable field
+  (slice 3, resolves the slice-1 P3).** `validateFreezeRecord` in
+  `src/define/freeze-record.js` throws `FreezeRecordError` with
+  `field: 'override'` when the key is missing; `saveFreezeRecord`
+  refuses to write a body that omits override. `loadFreezeRecord`
+  defaults a missing key to `null` on read so pre-slice-3
+  freeze.json records survive without a migration step. Every
+  fresh freeze written by the new CLI stamps `override: null`, so
+  the on-disk shape converges on the current schema the next time
+  a project freezes.
+
+### Fixed
+
+- **DEFINE hygiene: the ` -- ` double-dash is gone from the
+  readiness CLI stage header and the CHANGELOG's TODO-regex line
+  (slice 3).** The readiness `rcf define readiness` stage block
+  now uses `: ` between the stage id / gate and the state label
+  (`D1 (define.brief): failing`); the CHANGELOG's `The regex is
+  now /\bTODO:/` line likewise uses a colon.
+
 - **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
@@ -133,7 +239,7 @@ Note: 0.28.3 (2026-09-22 below) was never tagged or published; its entries ship
   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`
+  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

package/bin/rcf.js

@@ -53,6 +53,8 @@ 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';
+import { main as questionsMain } from '../src/cli/questions.js';
+import { main as freezeMain } from '../src/cli/freeze.js';
 
 // Verify group members are handled by the verify-suite dispatch tree.
 import { main as verifyRunMain } from '../src/verify/cli/run.js';
@@ -99,6 +101,8 @@ export const GROUPS = {
     standards: standardsMain,
     ledger: ledgerMain,
     readiness: readinessMain,
+    questions: questionsMain,
+    freeze: freezeMain,
   },
   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-30-001",
-      "createdAt": "2026-09-30T15:30:02.583Z",
-      "buildVersion": "0.28.4-mockdriver",
+      "id": "rc-2026-10-03-001",
+      "createdAt": "2026-10-03T12:16:10.630Z",
+      "buildVersion": "0.29.0-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-30-002",
-      "createdAt": "2026-09-30T15:30:02.584Z",
-      "buildVersion": "0.28.4-mockdriver",
+      "id": "rc-2026-10-03-002",
+      "createdAt": "2026-10-03T12:16:10.631Z",
+      "buildVersion": "0.29.0-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-30-003",
-      "createdAt": "2026-09-30T15:30:02.584Z",
-      "buildVersion": "0.28.4-mockdriver",
+      "id": "rc-2026-10-03-003",
+      "createdAt": "2026-10-03T12:16:10.631Z",
+      "buildVersion": "0.29.0-mockdriver",
       "fixturePromptId": "canary-prompt-03",
       "responseWordCount": 55,
       "grades": {

package/guidance/define-draft-shapes.md

@@ -0,0 +1,89 @@
+# Drafting the engineer's entry shapes
+
+This document is the content of the `rcf_define_draft_shapes` MCP
+prompt served argument-free by the server. The agent reads it once
+per session and runs the draft pass after L1 is green. The product
+owner is not in the room; the agent populates `[draft]`-marked
+entities, components and interfaces so the engineer walks into a tree
+whose shape is honest about what is still owed.
+
+## When to run
+
+Run this pass once `rcf define readiness --level intent` prints
+`levels.intentComplete.ok === true` and the product owner has stepped
+back. Not before. The draft pass reads only the brief ledger, the
+decisions ledger and the current tree; it writes only `[draft]`-marked
+content. `shapes:draftSettled` then lists exactly what the engineer
+has yet to own.
+
+Nothing in the draft pass can fail a product-owner check. That is the
+property that keeps L1 and the draft pass independent. If an edit
+would fail any check in the `productOwner` persona, stop and raise it
+back to the intent loop (it was not an engineer-only question).
+
+## The three homes
+
+The `[draft]` marker lives on three homes in 0.30.0. The agent writes
+to all three; `shapes:draftSettled` reads back from all three.
+
+- `TAD.dataArchitecture.coreEntities[].description` begins `[draft]`
+  for every entity minted from an `entity` statement. The marker
+  reports under id `TAD.entity:<name>`.
+- `TAC.purpose` begins `[draft]` for every TAC stub minted from a
+  `surface` or `externalSystem` cluster. The marker reports under id
+  `<tacId>`.
+- `TAC.interfaces[].description` begins `[draft]` for every interface
+  pre-populated inside a draft stub. The marker reports under id
+  `<tacId>:<name>`.
+
+Each marker is `[draft]` followed by a space and the one-sentence
+seed body. Leading whitespace is tolerated by the reader; keep the
+marker at the start of the string regardless.
+
+## The four writes
+
+Walk the brief in this order; each step writes `[draft]` content only.
+
+1. One `TAD.dataArchitecture.coreEntities[]` entry per `entity`
+   statement. `description` begins `[draft]` and quotes the
+   statement's source so the engineer can trace it. Use the statement
+   text to pick a name in UpperCamel; the engineer renames when the
+   entity is owned.
+2. One TAC stub per `surface` or `externalSystem` cluster when no
+   TAC exists for it. `purpose` begins `[draft]`; `responsibilities`
+   lists the statements the surface or external system serves (one
+   bullet per statement, in the brief's words). Pick a `tacId` of the
+   next free number and a descriptive slug; the engineer renames when
+   the TAC is owned.
+3. On each draft TAC, `[draft]` interfaces with real kinds from the
+   closed vocabulary (`recordShape`, `httpRoute`, `event`,
+   `cliCommand`, `uiRoute`, `port`, `fileFormat`, `fixture`,
+   `other`). Draft one of each kind the surface uses:
+   - a `recordShape` per entity the surface owns, with `fields:`
+     guessed from the brief;
+   - a `uiRoute` per surface;
+   - an `httpRoute` per exchange with an external system.
+   `description` begins `[draft]` with the one-line what-this-is.
+4. `rcf discover req-classify` over every REQ created in the loop, so
+   `skeleton:reqShape` passes where the classifier is confident and
+   the engineer sees only the rest. The classifier is already
+   available under `src/review/` or `src/discover/`; this prompt only
+   invokes it.
+
+## The read-back
+
+After the pass, run `rcf define readiness --json` and read
+`stages[].checks[]`. `shapes:draftSettled` is the engineer's entry
+list: every id it names is a shape the agent pre-populated and the
+engineer still has to settle. `shapes:tacHasInterface` and
+`shapes:kindVocabulary` have already applied to drafts, so an empty
+`shapes:tacHasInterface` finding means every stub carries at least
+one interface and an empty `shapes:kindVocabulary` finding means
+every interface's kind is in the closed vocabulary. The template
+marker check and the entity join arrive in a later PR; the draft
+pass does not need them to be honest about what is drafted.
+
+Hand over by naming the three id forms the engineer will see
+(`<tacId>:<name>`, `<tacId>`, `TAD.entity:<name>`) and the one verb
+they will run to walk them (`rcf define readiness`). Nothing further
+is said; the engineer owns the ladder from here.

package/guidance/define-intake.md

@@ -0,0 +1,97 @@
+# Document intake into the brief ledger
+
+This document is the content of the `rcf_define_intake` MCP prompt
+served argument-free by the server. It walks the harness through
+intake and lands every finding as an open-question statement the
+intent loop then asks.
+
+## What intake is
+
+The owner hands over a folder. One file is the brief (short, prose,
+the "what we are building" document); the rest are supporting
+documents (ADRs, spec sketches, old READMEs, OpenAPI YAML, meeting
+notes). The split that reaches the brief ledger is the harness's
+work; the mechanical scans and the follow-up questions are
+rcf-lite's.
+
+Intake is harness-split and tool-scanned. The harness writes
+`<source>.statements.md` beside each source; rcf-lite mints the
+statements, runs the three mechanical scans against the existing
+body, and appends one `openQuestion` statement per finding. The loop
+then reads one check (`brief:openQuestions`) and the owner answers
+in one place (ADR-4130).
+
+## The walk
+
+Walk the folder brief-first. For each source, in this order:
+
+1. Open the source.
+2. Split it into one statement per line. A statement is a sentence
+   that stands on its own: a capability (something the product must
+   do), a constraint (a rule it must obey), an actor (a person or
+   role), an entity (a thing it keeps track of), an externalSystem
+   (another system), a surface (a screen or channel), outOfScope
+   (something explicitly not in), an openQuestion (a question still
+   to answer), or an amendment (a correction to an earlier
+   statement).
+3. Write `<source>.statements.md` next to the source. Each line is
+   one statement with a leading `[kind]` marker and a trailing
+   `(source: <path>:<line-span>)` marker.
+4. Show the file to the owner in one message. Correct based on their
+   reply.
+5. Run `rcf define ledger brief add --from <path>` (or the
+   `rcf_define_ledger` MCP tool with `verb: add`, `from: <path>`).
+   The mechanical scans run by default; findings are appended as
+   openQuestion statements. Report the scan findings as plain
+   questions.
+6. Move to the next source.
+
+Never add two sources through one `brief add --from`. Each `add`
+scans the new ids against the existing body, and the scan source
+marker `scan:<name>:<ids>` names the ids from both sides.
+
+## The line grammar
+
+Each line of a statement file is a statement. The grammar:
+
+```
+[<kind>] <text> (source: <path>:<line-span>)
+```
+
+- `[<kind>]` is one of the nine kinds above. When absent, the kind
+  defaults to the harness's `--kind` flag (default `capability`), or
+  to `openQuestion` when the line ends with `?` or begins with
+  `TBC`, `TBD`, `Open:` or `Question:`.
+- `(source: ...)` names the file and the line range in the source.
+  When absent, the harness's `--source` flag or the file path itself
+  is used.
+- Everything between the two markers is the statement text,
+  verbatim.
+
+## What the owner sees
+
+A statement file is operator prose. The owner reads it; the harness
+corrects based on their reply. Example:
+
+```
+[capability] Officers can put a loan on hold for up to 30 days. (source: briefs/loans.md:12-14)
+[constraint] A loan on hold must not accrue late fees. (source: briefs/loans.md:15)
+[openQuestion] Who approves a hold longer than 30 days? (source: briefs/loans.md:16)
+```
+
+After `brief add --from` runs, the loop will ask about each of these
+through `rcf define questions --persona productOwner`.
+
+## After intake
+
+Run `rcf define questions --persona productOwner`. The next set is
+the `resolvedBy` questions for every capability, constraint, entity,
+actor, externalSystem and surface statement, suggesting existing
+REQ titles that share two or more words of 4+ characters. The owner
+decides which become new REQs, which point at existing REQs, and
+which are omitted.
+
+At L1 (`levels.intentComplete.ok === true`) the agent pre-populates
+`[draft]` entities, components and interfaces as engineer entry
+material. These are drafts the engineer refines; they are never a
+product-owner blocker.

package/guidance/define-intent.md

@@ -0,0 +1,107 @@
+# The product-owner intent loop
+
+This document is the operator-side reference for the DEFINE step 3
+intent-complete loop. It is the content of the `rcf_define_intent` MCP
+prompt and the `rcf://docs/define-intent` resource. The agent reads it
+once per session and drives the loop; the product owner never sees any
+of it.
+
+## The shape of a turn
+
+A turn is four steps and nothing else.
+
+1. Run `rcf define questions --persona productOwner` (or
+   `rcf_define_questions` over MCP). The call returns the next question
+   set from the readiness object. Nothing is stored for the loop; the
+   tree, the four ledgers (`rcf/define/`) and the profile
+   (`rcf/.identity/profile.md`) are the state.
+2. Ask the first one to three questions in one group, in plain words,
+   with the passage from the document quoted exactly. Never show more
+   than one group at a time; never show ids, verbs or stage names
+   unless the owner asks.
+3. Run the write-back the question carries. Every question's
+   `writeBack[]` names one command per answer kind; pick the one that
+   matches the owner's reply and run it. The write-back is idempotent:
+   running it twice does not change the tree.
+4. Re-run `rcf define readiness --level intent` (or
+   `rcf_define_readiness`). On exit 0 the loop is finished and you
+   print the verdict (section below). On exit 4 the loop continues:
+   go back to step 1.
+
+The loop is monotone. Each answer removes its item or converts it into
+at most two further product-owner items (an openQuestion promoted to a
+decision asks `wellFormed` once if the harness under-fills it; a
+statement resolved to a new REQ asks `reqHasUs` once). No engineer
+edit can re-open the PO loop.
+
+## The register
+
+The first turn's first act is replacing the Register choice list in
+`rcf/.identity/profile.md` with `productOwner` when the person
+driving is the product owner. The profile is operator prose; you edit
+it directly (no verb owns it). The same holds for the Surface choice
+list.
+
+The PO register has three wording rules.
+
+- Plain sentences. No method terms. "What this is for" beats
+  "capability statement". "Who uses this" beats "AC-18602-4 user story
+  elicitation".
+- Quote the passage. When the question is about a brief statement,
+  quote the statement text in double quotes. The owner recognises their
+  own words. "Your document says 'Officers can put a loan on hold.'"
+  beats "statement 7".
+- One group at a time. The question object groups by source span so
+  the owner thinks about one passage before moving on. Never collapse
+  two groups into one prompt.
+
+## Starting a session
+
+A product-owner session starts with `rcf define questions --persona
+productOwner`. If the brief is empty, the only question the loop
+returns is `brief:sinceFreeze`: hand me your document, or tell me in a
+few sentences what this is for. Walk the folder with the intake prompt
+(`rcf_define_intake`) first when the owner has supplied one; otherwise
+take their sentences and feed them in through `rcf define ledger brief
+add --text "<text>"`.
+
+## Ending a session
+
+When `rcf define readiness --level intent` returns ok, print exactly
+these lines:
+
+```
+Intent-complete: yes.
+Your document has been turned into N requirements with M user stories.
+The engineer blockers remaining are K.
+```
+
+Then run `rcf define readiness --level intent --json` and save the
+output beside the source folder as `<folder>.intent-complete.json`
+(outside `rcf/`; readiness writes nothing itself). Commit the tree.
+The Readiness tab URL is the artefact a delivery stream attaches.
+
+## The engineer register
+
+The same compute runs with `--persona engineer`: the question set is
+the engineer blockers in failing stages, and its exit is
+`levels.readyToBuild.ok`. Per-check question templates and per-check
+write-backs for the engineer register are NOT part of DEFINE step 3
+PR 2 (spec §1.1: "The engineer register is the same mechanism with
+`--persona engineer`; it is not designed here beyond that flag and
+is what step 4 inherits."). Until step 4 lands, the engineer-persona
+questions return the shared compute shape with empty `writeBack` and
+`answerKinds`; the harness reads the raw blocker and runs the
+engineer verb that matches the check by hand.
+
+## What the loop does NOT do
+
+- No conversation state in rcf-lite. The tree, the ledgers and the
+  profile are the state (ADR-4129).
+- No separate findings list. Intake scan findings become
+  `openQuestion` statements and the loop reads one check
+  (`brief:openQuestions`) rather than two surfaces (ADR-4130).
+- No stale title-hit fallback. A statement whose `resolvedBy` is a
+  REQ id outside the closed grammar fails `skeleton:resolvedBy`; the
+  question returns the title hit as a suggestion rather than the
+  compute accepting it silently.

package/guidance/discover-prototype.md

@@ -0,0 +1,67 @@
+# Recording a prototype in DISCOVERY
+
+This document is the content of the `rcf_discover_prototype` MCP
+prompt served argument-free by the server. It walks the agent
+through the only path a prototype takes into the chain: as evidence,
+with code burned, and with salvage by re-derivation.
+
+The posture is ADR-4132. The code of a prototype is reference only;
+no shape in the project tree is promoted from it. The whole worth of
+the method is that every requirement, story, AC and shape has a
+known origin, and a promotion path would smuggle unowned choices
+past the chain.
+
+## What a prototype is
+
+An elicitation instrument built in DISCOVERY to learn what to ask.
+It is recorded in the intake classification as an artefact of kind
+`other` with the prototype's name.
+
+## What is recorded
+
+The prototype's outputs are brief statements with source spans
+`prototype:<name>:<observation>`:
+
+- Capabilities: what people did with it.
+- Constraints: what they refused or asked for; what they would not
+  do without.
+- Open questions: what the prototype raised that the brief had not.
+- Out of scope: what the prototype was never allowed to do.
+
+Reactions that need a ruling become decisions with options and a
+default (the enumerated form D7 reads).
+
+## What is burned
+
+The code. The burn is one brief statement, kind `constraint`:
+
+> Prototype <name> (commit <sha>, burned <date>) is reference only;
+> no code from it is promoted.
+
+The build that follows starts from the tree, never from the
+prototype. The constraint sits beside the capabilities and open
+questions the prototype produced; the chain reads them all through
+the same `brief:openQuestions` / `skeleton:resolvedBy` loop as any
+document.
+
+## Salvage by re-derivation
+
+The only middle path. Extract requirements from a promising
+prototype as evidence (statements sourced to its files and lines),
+run them through intake and the PO loop like any document, and
+rebuild from the tree. The prototype is a quarry.
+
+"Grow the prototype" is rejected. The provenance reason is the one
+Dex's note gives: a shape reaching the project tree without the PO
+loop that owns every settled shape is a shape without a known
+origin, and no amount of auditing after the fact can restore the
+owner.
+
+## The managed-block rule
+
+A statement sourced to `prototype:` is evidence. A document that
+cites prototype code as its implementation is a D2 finding the
+engineer resolves by re-deriving. That rule is prose; no check is
+added in 0.30.0, and the engineer running D2 sees the finding
+through the same `skeleton:resolvedBy` surface that reports every
+other pointer.

package/guidance/discovery-prototypes.md

@@ -0,0 +1,69 @@
+# DISCOVERY home for prototypes
+
+This document is the doctrine and the ledger conventions for
+prototypes. It is served under the slug `discovery-prototypes`,
+through `rcf://docs/discovery-prototypes`, and through the
+`rcf_discover_prototype` prompt that wraps it with the walk.
+
+The posture is ADR-4132: prototypes live in DISCOVERY as evidence;
+code is burned; salvage is re-derivation.
+
+## What a prototype is
+
+An elicitation instrument built in DISCOVERY to learn what to ask.
+It is recorded in the intake classification as an artefact of kind
+`other` with the prototype's name. The prototype belongs to
+DISCOVERY, not DEFINE: it is a tool for learning, not a draft of
+what gets built.
+
+## What is recorded
+
+Its outputs are brief statements with source spans
+`prototype:<name>:<observation>`:
+
+- Capabilities: what people did with it.
+- Constraints: what they refused or asked for.
+- Open questions: what it raised that the brief had not.
+- Out of scope: what it was never allowed to do.
+
+Reactions that need a ruling become decisions with options and a
+default. The intent-complete loop then reads one check
+(`brief:openQuestions`) and the owner answers in one place; the
+prototype's observations ride the same ladder as every other brief
+statement.
+
+## What is burned
+
+The code. The burn is one brief statement, kind `constraint`:
+
+> Prototype <name> (commit <sha>, burned <date>) is reference only;
+> no code from it is promoted.
+
+The build that follows starts from the tree, never from the
+prototype. The brief ledger holds the burn statement alongside the
+other statements the prototype produced; nothing further is said in
+code or in configuration.
+
+## Salvage by re-derivation
+
+The only middle path. Extract requirements from a promising
+prototype as evidence (statements sourced to its files and lines),
+run them through intake and the PO loop like any document, and
+rebuild from the tree. The prototype is a quarry.
+
+"Grow the prototype" is named here as rejected, with the provenance
+reason from Dex's note: a shape reaching the project tree without
+the PO loop that owns every settled shape is a shape without a known
+origin, and no amount of auditing after the fact can restore the
+owner.
+
+## The managed-block rule
+
+The managed block gains one rule the harness picks up through
+`rcf doctor`:
+
+> A statement sourced to `prototype:` is evidence. A document that
+> cites prototype code as its implementation is a D2 finding the
+> engineer resolves by re-deriving.
+
+That rule is prose; no check is added in 0.30.0.