rcf-lite 0.28.4 → 0.30.0

package/guidance/define-litmus.md

@@ -0,0 +1,102 @@
+# Litmus: landing n fresh-context readings at the current hash
+
+This document is the content of the `rcf_define_litmus` MCP prompt
+served argument-free by the server. The agent reads it once per
+session and runs the litmus pass when the operator or the readiness
+verb asks for it.
+
+## What a litmus reading is
+
+A litmus reading is a probe-ledger entry whose `finding` field begins
+`litmus:<reader>:` and whose text includes the current litmus hash.
+It is written by `rcf define ledger probes add` just like any other
+probe-ledger entry; the `litmus:` prefix is what the verb reads back
+when it counts "distinct readers at this hash".
+
+The litmus hash is the current tree hash computed with the probes
+ledger excluded (ADR-4131 extended, 0.30.0 PR 7 R9). The probes
+ledger is inside `tree.currentTreeHash` by ADR-4120, so a reader
+writing an entry that references `currentTreeHash` would shift the
+hash the reader just attested to. The litmus hash is the content-
+stable version: writing to the probes ledger does not change it, so n
+readers can land their entries at the same hash. Writes to the brief,
+decisions or concerns ledgers do change the litmus hash the same way
+they change `currentTreeHash`; those changes mean the content under
+review has changed and stale litmus readings fall out of the count.
+This trade-off is intentional: litmus readings do not attest to
+probe findings written after them, because probe entries are
+themselves readings.
+
+The number of distinct readers is counted across the probe ledger; a
+reader id appears at most once in the count regardless of how many
+`litmus:<reader>:*` entries it has written.
+
+## When to run
+
+Run this prompt whenever a verb reports the shortfall:
+
+- `rcf define readiness --litmus <n>` exits 4 and prints a `[warn]`
+  line naming the current hash and the number of distinct readers
+  found. The shortfall is the number of fresh-context readers you
+  still owe before the verb will exit 0.
+- `rcf define freeze --litmus <n>` refuses (exit 4) with the same
+  reason and writes nothing. The freeze is only legal when n distinct
+  readers have attested at the hash the verb was asked to freeze.
+
+The harness is the runner. rcf-lite does not spawn processes and does
+not make network calls at runtime. You spawn the readers; they land
+the entries.
+
+## The shape
+
+Each reading is one `rcf define ledger probes add` call:
+
+```
+rcf define ledger probes add \
+  --req <reqId> \
+  --finding "litmus:<reader>: <one-line observation at hash <hash>>" \
+  --severity low
+```
+
+Fill in:
+
+- `<reader>` is a short id for this reader. Make it unique per fresh
+  context (for example `reader-01`, `reader-02`). The verb counts
+  distinct readers by this id.
+- `<reqId>` is the REQ the reader is probing. On a readiness pass this
+  is typically the first failing REQ or a REQ the operator named; on a
+  freeze the ids come from the brief.
+- `<hash>` is the current litmus hash. Read it from
+  `rcf define readiness --json` under `tree.litmusHash` (or from the
+  `[warn]` line the verb printed; the warn line names the litmus hash
+  explicitly).
+
+A reading is "at the hash" when the `hash` substring appears anywhere
+in the finding text, not in a separate field. Keep the hash in the
+finding text so the entry is self-describing.
+
+## The loop
+
+1. Read `tree.litmusHash` from `rcf define readiness --json`.
+2. Spawn n fresh-context readers (one claude session per reader is
+   enough; a reader must not share context with another).
+3. Each reader lands one `litmus:<reader>:` probe-ledger entry at the
+   litmus hash. The entry's finding text includes the litmus hash and
+   one observation; the reader does not edit the tree.
+4. Re-run the verb that asked for `--litmus <n>`. The count is now
+   n and the verb exits 0 (readiness) or writes the freeze record
+   (freeze).
+
+Writes to the probes ledger (adding litmus readings is itself one)
+do not shift the litmus hash, so n readers landing their entries in
+sequence all pin to the same hash and all count. A write to the
+brief, decisions or concerns ledgers (changing the content under
+review) does shift the litmus hash and makes earlier readings stale.
+Hand the readers a hash that will still be current when the last
+reading lands; a short freeze-prep window is the common case.
+
+## When n distinct readers have attested
+
+The verb exits 0. Nothing else is said; the readings stay in the probe
+ledger. A later tree change makes them stale and the next invocation
+of the verb will require fresh readings at the new hash.

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,19 @@
     {"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."},
+    {"name": "rcf_define_litmus", "file": "define-litmus.md", "description": "Spawn n fresh-context readers at the current tree hash and land their readings as probe-ledger entries whose finding begins litmus:<reader>:. Required by rcf define readiness --litmus and rcf define freeze --litmus. Argument-free."}
   ],
   "platformInvariants": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rcf-lite",
-  "version": "0.28.4",
+  "version": "0.30.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-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."
+    }
+  ]
+}

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

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

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

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

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

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

package/rcf/adrs/adr-4131-gates-bite-ack-recorded-override.json

@@ -0,0 +1,30 @@
+{
+  "createdAt": "2026-10-03T10:50:00Z",
+  "updatedAt": "2026-10-03T10:50:00Z",
+  "adrId": "ADR-4131-gates-bite-ack-recorded-override",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "accepted",
+  "title": "The gates bite with --ack as the recorded override for D3, D5, D6",
+  "context": "DEFINE step 3 train (spec 2026-10-01) brings the substantive checks of proposal 3.2 into D3, D5 and D6 across PRs 5, 6 and 7. The 0.29.0 posture left those stages warn-with-ack: --check exits 0 with a stderr [warn] line, --ack as the recorded override. The spec section 4 gates-bite intro and decision 9 both pin the biting posture: --check exits 4 on D3, D5 and D6 as it does on blocking stages; --ack stays as the recorded override for those three because the ruleset's recordedInChain channel needs it (decision 8's pattern applied to gates, not retired with the verb). The compute remains pure; readiness.js collects candidate paths and the CLI resolves them on disk so the gate functions see a resolvedPaths map in the stage context. PR 5 lands the three D3 bite checks (shapes:templateMarkers, shapes:entityJoin, shapes:pathsResolve), the ackable(stage) companion to stagePolicy, and the --check shapes exit 4 policy; PRs 6 and 7 bite D5 and D6 on the same shape.",
+  "decision": "The gates bite with --ack as the recorded override for D3, D5 and D6. stagePolicy keeps returning blocking for every stage (ADR-4122 posture) and gains a sibling helper ackable(stage) that returns true for exactly D3, D5 and D6 and false otherwise. The readiness CLI --check <stage> policy follows that split: on a blocking stage without ackable, a failing state exits 4 (today's behaviour); on a stage with ackable, a failing state exits 4 unless the freeze record acknowledges that gate at the current tree hash, in which case it exits 0. --ack on any stage without ackable stays a usage refusal with exit 2 (D1, D2, D4, D7, D8). The three D3 bite checks ship as pure engineer checks on src/query/gates.js: shapes:templateMarkers over delta (per-kind marker presence on interfaces[].description, ids <tacId>:<name>, why names the missing marker, drafts included), shapes:entityJoin over tree (every coreEntities[].name named by exactly one recordShape, ids TAD.entity:<name>), shapes:pathsResolve over delta (any path:-like token resolves on disk against the resolvedPaths map in the stage context or the description carries authoredAt: D3). Validate findings only where a legacy tree can comply; the dogfood tree records any residual failure in KNOWN GAPS rather than weakening the check.",
+  "consequences": "A failing D3 bite now blocks CI unless the engineer either fixes the tree or writes a recorded override with --ack --reason at the current hash; the record stays visible in the freeze record (the chain of recordedInChain the ruleset reads). The ackable companion keeps stagePolicy legible: the policy stays 'blocking' for every stage (the readyToBuild fold is unchanged), with ackable the separate signal the CLI reads to decide whether a failing stage honours an acknowledgement. The gate functions stay pure: the CLI is the module that resolves candidate paths on disk and the stage context carries the resolved map. The D3 bite surfaces three new engineer checks on the readiness tab and the text report; nothing on the productOwner side moves. --level intent and --level build exits are unchanged because the levels fold is already a derived view. The dogfood tree keeps CI green by scoping its own readiness call as it already does; the three new checks pass on the dogfood chain because the shipped TACs name their markers truthfully.",
+  "alternativesConsidered": [
+    {
+      "name": "Retire --ack (make D3, D5, D6 plain blocking)",
+      "summary": "Drop the --ack verb everywhere and let a failing D3, D5 or D6 simply block CI with no override.",
+      "reasonNotChosen": "The ruleset's recordedInChain channel exists so a refuse at a hash can be acknowledged with a reason that becomes part of the chain. The gates bite is decision 8's pattern applied to gates (refuse with a recorded override), and retiring --ack removes the channel the ruleset depends on. The spec decision 9 pins this; this ADR records it in-chain."
+    },
+    {
+      "name": "Keep warn-with-ack: --check exits 0 with a [warn] on D3, D5, D6",
+      "summary": "Leave the 0.29.0 posture in place; let the bite only surface in validate and the viewer.",
+      "reasonNotChosen": "The whole point of the DEFINE step 3 train is to make D3, D5 and D6 bite: the substantive checks of proposal 3.2 land here, and CI must refuse on them for the engineer to feel the gate. Warn-with-ack kept them a soft signal; the spec moves them to blocking with --ack as the recorded override."
+    },
+    {
+      "name": "Make the gate functions impure and resolve paths inline",
+      "summary": "Let shapes:pathsResolve open the filesystem directly so the gate module decides path existence on its own.",
+      "reasonNotChosen": "gates.js is the one pure module every surface composes; folding I/O into it would re-couple the viewer and the CLI through disk access. The CLI already owns the project-root resolve for the walker and the ledgers; adding one more resolve step for candidate paths is a one-pass walk, and the stage context grows by one map. The viewer uses the same seam when it renders the Readiness tab server-side."
+    }
+  ]
+}

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

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