rcf-lite 0.28.2 → 0.29.0

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.

package/guidance/harness-template.md

@@ -406,6 +406,40 @@ queue orchestration, PR authoring and bug triage. The
 for elicitation, AC coverage depth and conversation integrity. Run `rcf
 guidance` with no arguments to list every method document the installed
 package ships.
+
+### Product-owner intent sessions
+
+A product-owner session starts with `rcf define questions --persona
+productOwner` (or the `rcf_define_questions` MCP tool) and ends at
+`Intent-complete: yes`. Every answer lands through the write-back the
+question carries, then readiness recomputes; nothing about the owner's
+intent lives only in a chat. The full loop content is in `rcf guidance
+define-intent` and the `rcf_define_intent` prompt. Never improvise a
+PO loop; the questions and their write-backs are the method.
+
+### Prototype rule
+
+A prototype is engineer entry material, not a product-owner blocker.
+When the tree reaches `levels.intentComplete.ok`, the agent may
+pre-populate `[draft]` entities, TAC stubs and interfaces so the
+engineer has a starting point; those drafts never re-open the PO
+loop and never block a freeze. If the owner asks for a visible
+prototype before intent-complete, say so (the method is finished the
+intent first) and offer to continue the intent loop; never produce a
+prototype that bypasses the readiness verdict.
+
+### Prototypes in DISCOVERY (ADR-4132)
+
+A statement sourced to `prototype:<name>:<observation>` is evidence,
+not implementation. A document that cites prototype code as its
+implementation is a D2 finding the engineer resolves by re-deriving:
+extract requirements from the prototype as evidence, run them through
+intake and the PO loop like any document, and rebuild from the tree.
+The prototype's code is burned (one brief statement, kind
+`constraint`); the build that follows starts from the tree, never
+from the prototype. "Grow the prototype" is rejected on provenance
+grounds. The full doctrine is in `rcf guidance discovery-prototypes`
+and the `rcf_discover_prototype` prompt.
 ```
 
 ## Customisation points

package/guidance/managed/agent-instructions-block.hash

@@ -1 +1 @@
-b13d34856570798bf8cced82f5d79998408fe6b30d41a65ba3d3a356c46beef5
+31dc2627d2a73f5f051a6560dd1c81eac91a87c3a2339c46720648708285e4be

package/guidance/managed/agent-instructions-block.md

@@ -393,3 +393,37 @@ queue orchestration, PR authoring and bug triage. The
 for elicitation, AC coverage depth and conversation integrity. Run `rcf
 guidance` with no arguments to list every method document the installed
 package ships.
+
+### Product-owner intent sessions
+
+A product-owner session starts with `rcf define questions --persona
+productOwner` (or the `rcf_define_questions` MCP tool) and ends at
+`Intent-complete: yes`. Every answer lands through the write-back the
+question carries, then readiness recomputes; nothing about the owner's
+intent lives only in a chat. The full loop content is in `rcf guidance
+define-intent` and the `rcf_define_intent` prompt. Never improvise a
+PO loop; the questions and their write-backs are the method.
+
+### Prototype rule
+
+A prototype is engineer entry material, not a product-owner blocker.
+When the tree reaches `levels.intentComplete.ok`, the agent may
+pre-populate `[draft]` entities, TAC stubs and interfaces so the
+engineer has a starting point; those drafts never re-open the PO
+loop and never block a freeze. If the owner asks for a visible
+prototype before intent-complete, say so (the method is finished the
+intent first) and offer to continue the intent loop; never produce a
+prototype that bypasses the readiness verdict.
+
+### Prototypes in DISCOVERY (ADR-4132)
+
+A statement sourced to `prototype:<name>:<observation>` is evidence,
+not implementation. A document that cites prototype code as its
+implementation is a D2 finding the engineer resolves by re-deriving:
+extract requirements from the prototype as evidence, run them through
+intake and the PO loop like any document, and rebuild from the tree.
+The prototype's code is burned (one brief statement, kind
+`constraint`); the build that follows starts from the tree, never
+from the prototype. "Grow the prototype" is rejected on provenance
+grounds. The full doctrine is in `rcf guidance discovery-prototypes`
+and the `rcf_discover_prototype` prompt.

package/guidance/manifest.json

@@ -5,11 +5,18 @@
     {"slug": "build-cycle", "file": "build-cycle.md", "title": "The RCF 5-stage build cycle"},
     {"slug": "harness-template", "file": "harness-template.md", "title": "Drop-in harness template"},
     {"slug": "managed/agent-instructions-block", "file": "managed/agent-instructions-block.md", "title": "The rcf doctor managed CLAUDE.md/AGENTS.md block (0.6.0 canonical text)"},
-    {"slug": "persona-programme", "file": "persona-programme.md", "title": "Persona programme: tail-interview template"}
+    {"slug": "persona-programme", "file": "persona-programme.md", "title": "Persona programme: tail-interview template"},
+    {"slug": "define-intent", "file": "define-intent.md", "title": "The product-owner intent loop (DEFINE step 3)"},
+    {"slug": "define-intake", "file": "define-intake.md", "title": "Document intake into the brief ledger (DEFINE step 3)"},
+    {"slug": "discovery-prototypes", "file": "discovery-prototypes.md", "title": "DISCOVERY home for prototypes (DEFINE step 3)"}
   ],
   "prompts": [
     {"name": "rcf_execute_build_cycle", "file": "build-cycle-playbook.md", "description": "How to execute the RCF 5-stage build cycle well: per-stage guidance, referee commands, failure modes, escalation rules. Fetch once per session, then drive rcf build bundle --next."},
-    {"name": "rcf_elicit_requirements", "file": "elicitation-playbook.md", "description": "How to draw a valid RCF tree out of a conversation: question frames for PRD / REQ / US / AC, the testable-AC quality bar, TAC / ADR capture, FBS queue construction, and when to stop."}
+    {"name": "rcf_elicit_requirements", "file": "elicitation-playbook.md", "description": "How to draw a valid RCF tree out of a conversation: question frames for PRD / REQ / US / AC, the testable-AC quality bar, TAC / ADR capture, FBS queue construction, and when to stop."},
+    {"name": "rcf_define_intent", "file": "define-intent.md", "description": "Drive the product-owner intent-complete loop with rcf_define_questions, write-backs through existing verbs, and the readiness verdict. Argument-free; starts with --persona productOwner and ends at levels.intentComplete.ok."},
+    {"name": "rcf_define_intake", "file": "define-intake.md", "description": "Walk a document folder brief-first, write one statement file per source with [kind] and (source: ...) markers, run brief add --from once per source, and report the scan findings as open questions. Argument-free."},
+    {"name": "rcf_define_draft_shapes", "file": "define-draft-shapes.md", "description": "Run the draft pass after L1 is green: pre-populate [draft] core entities per entity statement, [draft] TAC stubs per surface or externalSystem cluster, [draft] interfaces with real kinds inside each stub, and rcf discover req-classify over every REQ created in the loop. Argument-free."},
+    {"name": "rcf_discover_prototype", "file": "discover-prototype.md", "description": "Record a prototype in DISCOVERY as evidence: classification, brief statements with prototype:<name>:<observation> source spans, the burn statement, and the salvage-by-re-derivation path. Argument-free."}
   ],
   "platformInvariants": [
     {

package/package.json

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

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

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

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

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

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

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

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

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

package/rcf/adrs/adr-4124-define-freeze-verb.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-09-24T16:33:15Z",
+  "updatedAt": "2026-09-24T16:33:15Z",
+  "adrId": "ADR-4124-define-freeze-verb",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "rcf define freeze refuses on any failing stage and only D3/D5/D6 accept an --ack override",
+  "context": "Proposal 2026-09-22 v3 section 2.5 defines the freeze verb as the only close verb: it runs readiness, refuses on any failing gate, accepts --ack <gate> --reason on the three warn-first gates, and writes the freeze record. Section 3.2 lists five blocking gates in 0.29.0 (D1, D2, D4 floors, D7, D8) and three warn-with-ack gates (D3, D5, D6). Baz ruling 2026-09-24 (Baz decision 2 in section 9): warn-with-ack ack is accepted only on D3 / D5 / D6, never on the blocking gates. Slice 3 has to pick (a) whether ack on a non-warn gate is a usage refusal or a runtime refusal; (b) whether the freeze verb re-runs readiness after ack (or applies acks in-memory); (c) whether admissibility refusal counts as a freeze refusal or a warning. Slice 1 shipped a freeze-record writer with override as an optional nullable field, and the P3 review note flagged the local-schema mismatch (JSDoc said required-nullable, validator said optional).",
+  "decision": "The freeze verb refuses (exit 4) on any stage state 'failing' after applying --ack acknowledgements in-memory. --ack is a compile-time contract: unknown gate names (anything outside define.shapes / define.crosscut / define.consistency and their aliases) are usage refusals (exit 2), and every --ack must be paired with a matching --reason (exit 2 on mismatched arities). Acknowledgements are applied to an in-memory freeze.gates map keyed by gate id, and each warn-with-ack stage's state is recomputed with the same fold gates.js foldState uses (WARN_WITH_ACK + at.hash === currentTreeHash). freeze then writes the freeze record with these acknowledgements persisted so slice 5's viewer and a future computeReadiness call render the stage as 'acknowledged' at that hash. Admissibility refusal is informational (ADR-4123 carried): the wrap runs first so the ruleset toolScope guard is honoured, and on refuse the CLI prints a stderr [warn] and the freeze compute continues. The freeze verb never exits 4 solely for a refused-admissibility verdict. Slice 3 also fixes the slice-1 P3 by making validateFreezeRecord require override as a nullable field, and by making saveFreezeRecord always stamp override: null on a fresh freeze so the schema surface is single-sourced before slice 4 reads it. Older records that omit the key are tolerated by loadFreezeRecord defaulting to null on read.",
+  "consequences": "One verb, one contract, one exit code path. Operators cannot silently ack a blocking gate: the ack fails at parseArgs time with a message naming the accepted set, which is easier to reason about than a runtime refusal deep in the compute. The in-memory ack recomputation keeps the write path a pure function of the tree + the acks: nothing partial is written if the compute later rejects. Persisted acks show up on the next readiness run because the freeze.gates entry stores { state: 'acknowledged', at: { hash, at, reason } } and gates.js folds against the current tree hash. Honest downside: an operator who acks a warn-with-ack gate and then edits the tree without re-freezing sees the ack disappear on the next readiness run (the hash changed, so foldState drops back to 'failing'). This matches proposal section 2.5 ('closing a change is freezing again') and is the same posture the readiness verb has today. Override-nullable-required means every existing freeze fixture (in tests, in dogfood chains) is expected to carry override: null; the loader tolerates a missing key on read (fills in null) so older records survive, but writing a record without override is a validator failure. The double-dash hygiene is a one-line change per file with a targeted golden-fixture update.",
+  "alternativesConsidered": [
+    {
+      "name": "Accept --ack on any gate; refuse at runtime with a message",
+      "summary": "Let --ack take any gate name; the freeze compute checks the ack list against the warn-with-ack set and exits 4 with an error when a blocking gate is acked.",
+      "reasonNotChosen": "Slower feedback (parseArgs is instant, the readiness compute takes seconds on a large tree), and it lets an ack land in the ack map that will never be honoured. A usage refusal at parseArgs time matches the rest of the CLI's contract (unknown --check gates are refused there too)."
+    },
+    {
+      "name": "Re-run computeReadiness after applying acks",
+      "summary": "Persist an intermediate freeze record with the acks, re-run computeReadiness against it, decide the exit code from the second run.",
+      "reasonNotChosen": "Two writes and two computes; the second compute reads the same tree so the only difference is the freeze.gates map. Folding in-memory with gates.js foldState is one function call and matches what a slice-5 viewer would render if it were doing the same thing."
+    },
+    {
+      "name": "Refuse the freeze on refused-admissibility",
+      "summary": "Treat a refused-admissibility verdict as a fatal freeze failure; exit 4 with the refusal envelope on stderr.",
+      "reasonNotChosen": "ADR-4123 already ruled that readiness is a diagnostic and refuses to hide the block. The freeze verb is the write half of the same object; refusing the freeze solely because admissibility refused means an operator with a valid freezeable tree cannot close the change until the admissibility rules unblock. The refusal is still surfaced as a [warn] on stderr so it is not silent."
+    }
+  ]
+}

package/rcf/adrs/adr-4126-persona-tagged-blockers-two-levels.json

@@ -0,0 +1,40 @@
+{
+  "createdAt": "2026-10-01T14:30:00Z",
+  "updatedAt": "2026-10-01T14:30:00Z",
+  "adrId": "ADR-4126-persona-tagged-blockers-two-levels",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "Intent-complete is a persona cut, computed, never recorded",
+  "context": "WSD needs a product-owner exit from DEFINE that a delivery stream can pick up without a hand-over meeting. Dex proposed early-stage gates; the design-spec review (2026-10-01) walked a middle path. D2 and D4 each hold both PO and engineer checks today; a single-persona tag per check would misread both. Operators also need a way to pre-populate shapes at L1 without those shapes reading as the engineer's finished work. The gate table has 20 checks in 0.29.0; two are heterogeneous and one is missing. The train is 4.5 days across three PRs; PR A owns the compute.",
+  "decision": "Every gate check in src/query/gates.js declares an owning persona (productOwner | engineer) via a code-side CHECK_PERSONA map and a one-sentence CHECK_QUESTION heading in the persona's register. The two heterogeneous checks are split: skeleton:reqFields becomes skeleton:reqIntent (productOwner: description + domain) + skeleton:reqShape (engineer: shapeClassification.shapes); decisions:allAnswered becomes decisions:wellFormed (productOwner: enumerated per #241 format) + decisions:allAnswered (engineer: zero open). A new D3 check shapes:draftSettled fails every interface whose description still carries the leading [draft] marker, so an L1-pre-populated interface is distinguishable from a settled one; shapes:tacHasInterface counts a draft as present, and shapes:kindVocabulary applies to drafts. L1 intent-complete is 'every productOwner check ok across every stage', computed by computeReadiness and folded into readiness.levels.intentComplete alongside the existing freezeable-equivalent readiness.levels.readyToBuild. Nothing is written; both levels fall out of stages[].checks[] on every read. The notApplicable placeholder (stage:<D>:scope) carries a per-stage fallback persona (STAGE_FALLBACK_PERSONA map) so every check has a persona for the table test and downstream renderers; the placeholder is always ok so it never affects a level. There is no either / shared / both persona; a check that would need both is split instead. Per-item persona override is not introduced; a failing item inherits its check's persona. Open decisions do not block L1 in 0.29.0: an enumerated decision with a default is enough for an engineer to proceed (Baz direction doc, open question 1 answered Dave-recommended). The [draft] marker lives on TAC.interfaces[].description only in 0.29.0, mirroring decision 6's AC-class bracket convention; rcf-schemas 0.6.3 is untouched and the marker migrates with AC.kind to a structured field at schemas 0.7.",
+  "consequences": "One ladder, two verdicts. Intent-complete is the ticket artefact a delivery stream reads from `rcf define readiness --level intent --json`; it is not recorded, so no second register of truth and nothing to invalidate on tree change. The persona split in gates.js is one map plus two straightforward loops (reqIntent / reqShape each evaluates every REQ independently; wellFormed / allAnswered each loop decisionEntries); every existing test except the two renamed checks keeps passing unchanged, and the dogfood tree reports two extra findings on reqIntent that were previously masked by the first-failure continue (true findings, not regressions). The notApplicable placeholder carrying a persona is a small schema surface addition that keeps the per-check vocabulary total true. The [draft] marker as a text convention is the same posture AC class carries today (decision 6); the migration cost at schemas 0.7 is one more lift. L1 pre-population is explicit: the L1 agent writes [draft] interfaces as it learns entities and routes from the brief, which makes shapes:tacHasInterface pass earlier for the engineer and leaves shapes:draftSettled as the honest list of what the engineer has yet to own. L2 draft handling is unchanged: a failing shapes:draftSettled keeps D3 failing unless acknowledged at the current hash through the existing --ack define.shapes path (0.29.0 warn-with-ack posture; step 4 makes D3 bite). The levels object cannot disagree with the CLI or the Readiness tab because all three render from the same computeReadiness output. The CLI flags that expose levels (--level, --persona) and the viewer tab land in PRs B and C respectively; this ADR only covers the compute.",
+  "alternativesConsidered": [
+    {
+      "name": "Stage-prefix persona (every check on D1/D2/D4/D7 is productOwner; D3/D5/D6/D8 is engineer)",
+      "summary": "Pin persona by stage, skip the per-check tag; no splits.",
+      "reasonNotChosen": "Blocks the PO on skeleton:tadPersistence (data stores) and skeleton:deployAdr (which hosting), both engineering decisions. Also passes with unresolved brief statements under an engineer-only D5 even though resolution is a PO question. The per-check map is the source of truth because the owner is a property of the rule, not of the stage."
+    },
+    {
+      "name": "Recorded L1 (freeze-at-intent)",
+      "summary": "Write an intent-complete freeze record parallel to the build freeze, with its own hash and ledger.",
+      "reasonNotChosen": "Reintroduces stored state the detection model (REQ-172) removed. Two freeze records on one tree are two chances for them to disagree, and the delivery stream's artefact is already the --json output at a tree hash. L1 is a verdict, not a commit."
+    },
+    {
+      "name": "either / shared / both persona value",
+      "summary": "Allow a check to be owned by both personas when it reads both ways.",
+      "reasonNotChosen": "Hides whose question it is, which was the point of the tag. A heterogeneous check is almost always two checks under one name; splitting is clearer and cheap."
+    },
+    {
+      "name": "[draft] on a new TAC.interfaces[].status field instead of description",
+      "summary": "Introduce a structured status enum on the interface shape.",
+      "reasonNotChosen": "Schema change for one piece of 0.29.0 metadata; AC class already lives on description as a bracket prefix (decision 6); the two migrate together at schemas 0.7. The 0.29.0 cost is one regex."
+    },
+    {
+      "name": "Per-item persona override on failing[]",
+      "summary": "Let a failing { id, why } carry its own persona so one check can fail into both personas.",
+      "reasonNotChosen": "A failing item carries no new information its check does not already carry; the operator reads the question heading, not the item. Keeps the API surface narrower and avoids forcing every consumer to fold two persona fields."
+    }
+  ]
+}