rcf-lite 0.0.1 → 0.7.1

package/guidance/harness-template.md

@@ -0,0 +1,246 @@
+# Drop-in harness template
+
+## What this is
+
+The block that wires an agent into the RCF loop. **The golden path is `rcf init`**: it writes this fragment into your project's agent-instructions files automatically - **both `CLAUDE.md` and `AGENTS.md` on a fresh project** (vendor-neutral by default), or an existing instructions file refreshed in place - inside `<!-- rcf:managed:begin -->` / `<!-- rcf:managed:end -->` markers so re-running init or `rcf doctor --fix` refreshes it in place. Paste it by hand only if you skipped the bootstrap (`rcf init --no-agent-setup`) or your harness reads instructions from somewhere non-standard. The fragment is complete as shipped and names no specific harness.
+
+The `<!-- rcf:managed:begin -->` / `<!-- rcf:managed:end -->` marker convention was introduced in 0.6.0 (previously `<!-- rcf:begin -->` / `<!-- rcf:end -->`). If you are looking at an older repo whose file still carries the legacy pair, `rcf doctor --fix` migrates it in place; the MCP setup-funnel gate accepts either generation, so a legacy-inited repo is not spammed with setup notices while it waits to be migrated.
+
+These are operating rules for the agent, not suggestions. They exist because the failure modes are known: agents fabricate documents single-shot instead of asking, silently drop the tech or test layer, declare scaffold TODOs "done", stop after one build item instead of driving the queue, patch a reported bug in code without fixing the spec that let it through, commit a technology stack the owner's hosting cannot run before anyone asked where the app would run, push an undecided owner into standing up accounts and billing for a thing nobody has committed to building, ship with nothing the owner can actually run without a deploy, claim a result is "verified" against a runtime the check never touched, and open the session by reciting rule numbers and document ids at a non-technical owner who needed three sentences and one question. The fragment forecloses each.
+
+## The fragment
+
+```markdown
+## RCF
+
+This project uses RCF. The tree under `rcf/` is the requirements spine and
+the `rcf` CLI plus the `rcf_*` MCP tools are the referee. The rules below
+are hard rules, not suggestions. Work is defined by FBS spec bundles, not
+by improvised task lists.
+
+This block is managed by `rcf doctor`. Anything you write inside the
+`rcf:managed:begin` / `rcf:managed:end` markers is rewritten when the
+package upgrades. Add your own project rules outside the markers.
+
+How to talk to your operator. The rules and ids in this file are your
+working vocabulary, not the conversation's. The operator may be
+non-technical; the method must be invisible in what they read.
+- Plain language. Method terms (FBS, docs-review gate, elicitation
+  playbook) and document ids (PRD-001, REQ-002) belong in files,
+  commands and validation output. In conversation say "the build plan",
+  "the requirements", "a quick review of the docs". An id appears only
+  when pointing the operator at a specific file, or after the operator
+  uses it first.
+- Never cite a rule. The rules below shape what you do, silently.
+  "Per RULE 1" means nothing to the operator and reads as bureaucracy.
+- Concise and decision-led. Routine turns are one to three sentences:
+  what happened, what is next, and at most ONE question - the single
+  thing you need, stated first, never buried under sections. No
+  multi-section essays for routine turns.
+- Self-serve before asking. Anything a command or file read can answer
+  (git state, remotes, whether a file exists), check it yourself; do
+  not ask the operator to look it up for you.
+- Never re-ask a granted permission. Track what the operator has
+  authorised and act on it. Asking again reads as not listening.
+- Tone: it is in hand. The operator steers; you drive. Confident
+  without hedging, and plainly honest when something is genuinely
+  blocked or ambiguous.
+
+Before / after - the same first status after project setup:
+
+  Too much: four sections walking the operator through PRD-001,
+  TAD-001, BS-001, REQ-001 and US-101, quoting RULE 1 and RULE 5,
+  explaining the docs-review gate, asking whether a git remote exists,
+  re-asking for push permission already granted, with the one real
+  question (the product's name) at the bottom.
+
+  Right: "Brief read - good shape. I'm committing the scaffold and
+  pushing now; the remote's already wired. Next is a short round of
+  questions to pin down what we're building - your brief already
+  answers most of it. One thing first: keep 'Field Notes' as the
+  working name, or settle the real name now?"
+
+### RULE 1: Elicit first; never fabricate.
+
+Before authoring or rewriting any RCF document, run the elicitation
+playbook (`rcf guidance elicitation-playbook` on the CLI or the
+`rcf_elicit_requirements` MCP prompt). Ask the stakeholder its questions
+and wait for answers. Document content comes from stakeholder answers. If
+a fact was not given to you, do not invent it. Ask. A chain written in
+one shot without stakeholder input is a method violation, not a
+deliverable.
+
+### RULE 2: The full chain is the deliverable.
+
+All layers: PRD, REQ, US, AC, TS, TC, plus the tech side (TAD, TAC, ADR).
+Do not drop a layer silently. Init-scaffold TODO placeholders are not a
+finished state. Every scaffolded doc is either authored with the
+stakeholder or its removal is explicitly agreed with them. If a layer
+seems inapplicable, say so and get the stakeholder's agreement before
+leaving it out.
+
+### RULE 3: The test layer is mandatory.
+
+Author TS and TC documents and run `rcf coverage --strict`. Do not
+declare the work done while coverage fails, unless the stakeholder has
+explicitly accepted the gap.
+
+### RULE 4: A reported bug is a spec gap first.
+
+When a bug is reported, do not jump to the code. First find the AC that
+should have required the correct behaviour and the test that should have
+caught it. Add or strengthen that AC (and its TS and TC) so the chain
+catches this class of bug, then fix the code against the corrected spec.
+
+### RULE 5: Deploy target before stack; never commit a stack blind.
+
+A technology stack must not be committed before the deploy target is
+established, and the stack is constrained to what that target can host.
+Choosing a stack the owner's hosting cannot run is a method violation,
+not a technical preference. This is an ordering rule: it forbids a stack
+ahead of the target. It does not require the owner to have a target, or
+to want one.
+
+Raise the question when a stack decision is actually due. If the owner
+names a target, constrain the stack to it. If the owner does not know
+and wants to settle it, run the hosting-choice walkthrough in the
+elicitation playbook and isolate the sign-up, billing, token and
+CLI-auth steps as the human account-holder's to do. Do not perform or
+pretend them.
+
+If the owner defers, is still exploring, or is not deploying, that is an
+answer, not a blocker. Do not press for a provider and do not stand an
+account up. Record the deferral as the ADR, hold back the live half of
+what was deferred, and build to RULE 6's local preview. A deferred
+capability's acceptance criteria are deferred with it, visibly, or
+scoped to a stub the owner explicitly agreed to.
+
+Capture the deploy target, or its deferral, and any stack constraint it
+implies as an ADR on the project's own tree.
+
+### RULE 6: Every build lands a local preview.
+
+A build is not done until it leaves a working, documented local preview
+as its default outcome: a dev server, seeded data where the app needs
+it, ideally started with one documented command. This holds whether or
+not a host was named and whether or not a deploy happened. Remote
+deployment is an addition on top of local preview, never a replacement
+for it.
+
+### RULE 7: Verification claims name their runtime.
+
+Every "verified" or "tested" claim, in the Test and Finalise stages and
+in the PR body's verification section, names the runtime it was checked
+against (for example, "verified against wrangler dev on localhost, not
+the deployed Worker runtime"). A claim with no named runtime is
+incomplete.
+
+Never state or imply verification on a deployed runtime that was not
+exercised. A green test suite is evidence about the runtime it ran on
+and nothing more. A ship verdict comes only from the deployed runtime
+or a declared runtime-parity claim.
+
+### RULE 8: Never skip the method for speed.
+
+If a bug fix, polish item, or "small thing" would move faster by
+bypassing RCF, that is the moment the method matters most. Do not offer
+the operator a "skip the spec and just push a fix branch" option. If the
+work is genuinely too small to warrant a full chain touch, say so and
+propose the minimum spec update that keeps the chain honest. The
+operator can choose to accept a shortcut. Offering one first is the
+defect.
+
+### RULE 9: Write what you learn.
+
+`rcf/knowledge/` is this project's memory. Every session, if you
+learned something the next session should not have to relearn, write it
+there. `notes/` for internal facts (decisions, gotchas, runtime facts,
+"the CI matrix uses Node 22 not 24"). `docs/` for user-facing prose the
+project surfaces. One topic per file. Grep the tree before asking the
+stakeholder something you might already know. See
+`rcf/knowledge/README.md` for the convention.
+
+### RULE 10: Read the operator profile.
+
+If `rcf/.identity/profile.md` exists, read it at session start. It
+describes the operator: name, role, working style, project-scoped
+preferences. It is per-clone (gitignored by default), so it may hold
+things the operator does not want in the shared repo. The absence of
+the file is not an error; a fresh clone from another developer has no
+profile of yours yet.
+
+### Session start
+
+Run `rcf validate`. A broken tree is fixed or reported before anything
+else. Run `rcf build` for queue state: what is done, in progress,
+blocked. Run `rcf doctor` if the last upgrade of the package changed
+these rules. The block you are reading may be out of date; `rcf doctor
+--fix` rewrites it.
+
+### Build loop
+
+Docs-review gate: when the tree has just been elicited, offer the
+stakeholder a review of it before the first build. Do not roll from
+elicitation straight into building without the offer.
+
+Run `rcf build --next` to get the spec bundle for the next actionable
+item, then execute the five-stage runbook it prints: Define, Build,
+Review, Test, Finalise. Every stage ends in a commit. Drive the whole
+queue, not one item. After each item's Finalise, loop `rcf build --next`
+until it reports the queue complete. If your harness can spawn
+sub-agents, run each FBS in its own worker so the driving context stays
+clean across the queue: one write worker at a time.
+
+Record lifecycle transitions with the exact mark commands the bundle
+prints. Never mark backwards. Run `rcf validate` after any tree edit,
+and `rcf trace <id>` or `rcf impact <id>` before touching anything with
+dependents. PR bodies are evidence-first: lead with what was verified
+and how, traced to AC and FBS ids, not a diff walk.
+
+Run the fresh-context self-review every few FBS builds and once at the
+end: a reviewer that drives the running app against its ACs, not one
+that reads the code. Method: `rcf guidance build-cycle-playbook`,
+section 16. It is the cheap in-loop check between builds, and it is not
+the independent verification gate. `rcf finalise` runs that, and only
+that writes `verified`.
+
+If context gets unreliable on a large build, do not stall. Write a
+next-session handover doc (queue state, the in-progress item, the next
+actionable id), add a line to this file (outside the managed markers)
+pointing the next session at it, then stop. A fresh session must resume
+without re-elicitation.
+
+### Write discipline
+
+Prefer the `rcf` verbs (`create`, `update`, `delete`, `link`) for tree
+edits. After any hand edit to a file under `rcf/`, run `rcf validate`
+before proceeding.
+
+### Escalation
+
+If the bundle is ambiguous or contradicts the tree, stop and ask; do
+not interpret. Never mark a stage done without its referee output.
+
+### MCP-wired harnesses
+
+The same contract holds over the server's `rcf_*` tools and prompts.
+Method depth, either wiring: the `rcf_execute_build_cycle` prompt, or
+on the CLI `rcf guidance build-cycle-playbook`, for the build loop,
+queue orchestration, PR authoring and bug triage. The
+`rcf_elicit_requirements` prompt, or `rcf guidance elicitation-playbook`,
+for elicitation, AC coverage depth and conversation integrity. Run `rcf
+guidance` with no arguments to list every method document the installed
+package ships.
+```
+
+## Customisation points
+
+Two, and only two, are intended tuning: the optional PR-convention line at the end of the fragment, and your commit cadence if the driving workflow batches differently. Everything else is the method; editing it means running a different method. The RULE blocks in particular are load-bearing - they exist to stop observed failure modes.
+
+## Known limitation - the fragment has to be present
+
+These rules only govern a session that loads this fragment. A project that was never initialised with `rcf init`, or whose fragment was stripped from `CLAUDE.md` / `AGENTS.md`, gets neither the deploy-target elicitation surface nor the runtime-provenance rules, and nothing here will flag its absence. Re-running `rcf init` restores the fragment; a session that cannot find it under the `<!-- rcf:managed:begin -->` / `<!-- rcf:managed:end -->` markers should say so rather than proceed as if the method were in force.
+
+## Check it took
+
+Four checks. Ask the agent to state the loop; the answer should name the five stages and the mark commands. Ask what it does before authoring documents; the answer should name the elicitation playbook and stakeholder questions, not drafting. Watch its first `rcf build --next` cycle: the bundle's runbook should be followed stage by stage, with a commit at each stage end. And read its first message to the operator: it should be a few plain sentences ending in one clear question, with no rule numbers and no document-id inventory.

package/guidance/managed/README.md

@@ -0,0 +1,63 @@
+# Managed canonical assets
+
+This directory holds the canonical texts that `rcf init` seeds and
+`rcf doctor` maintains across upgrades. Each asset ships with the
+package, so a consumer project always renders against the version it
+installed. If you are reading this because you want to see what init or
+doctor writes into an installed project, see the files below.
+
+## What lives here
+
+- `agent-instructions-block.md`: the managed block that `rcf init`
+  writes into `CLAUDE.md` and `AGENTS.md` inside
+  `<!-- rcf:managed:begin -->` / `<!-- rcf:managed:end -->` markers, and
+  that `rcf doctor` maintains. This is user-facing product copy: read
+  it as if landing on a stranger's repo, because that is the reader
+  who sees it first. British English, no em-dashes, banned-tells
+  baseline honoured.
+- `agent-instructions-block.hash`: SHA-256 of the block text above,
+  generated at package build time by `scripts/gen-managed-artefacts.mjs`
+  and shipped in the tarball. `rcf doctor` reads this to decide whether
+  an installed project's block is stale.
+- `README.md`: this file. Explains the contract.
+
+## The managed-block contract
+
+- **Inside the markers** (managed): rewritten wholesale on every
+  `rcf init` and `rcf doctor --fix`. Operator hand-edits to this region
+  are discarded on --fix. The canonical text ships with the package
+  and can change between minor versions.
+- **Outside the markers** (operator): never touched by tooling. Any
+  operator prose, sections, imports or file additions are preserved
+  byte-for-byte. If the managed block is at the end of a file and the
+  operator adds a section beneath it, that section stays.
+- **Drift detection is warn-only.** `rcf doctor` never writes; it
+  reports and exits 0 clean, 3 dirty. `rcf doctor --fix` is the only
+  path that repairs.
+- **Never auto-repair.** No hook, no post-install script, no `rcf init`
+  or `rcf validate` sub-call invokes `--fix` implicitly. Init writes
+  the block on a fresh scaffold; doctor maintains an existing project.
+  Both are operator-typed.
+
+## Reading the canonical text from a consumer project
+
+The block is exposed through the existing `rcf guidance` verb:
+
+```
+rcf guidance managed/agent-instructions-block
+```
+
+The `.hash` file is deliberately not addressable through guidance; it
+is metadata the doctor reads, not prose an operator reads.
+
+## Contributing to the canonical text
+
+Edits to `agent-instructions-block.md` land through the normal RCF
+change flow (a spec that names the wording change, a rule that stays
+British English and honours the banned-tells baseline). The
+`scripts/gen-managed-artefacts.mjs` script regenerates
+`agent-instructions-block.hash` and the mirrored fragment inside
+`guidance/harness-template.md`; run it via the package build (the
+`prepublishOnly` hook wires it into a release). Test AC-1.14 asserts
+the harness-template fragment byte-matches this block after
+regeneration.

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

@@ -0,0 +1 @@
+24d596ffef22c1f55fdad901ce424e443caade9cd44e8d659f17f14f1ef1ac47

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

@@ -0,0 +1,220 @@
+## RCF
+
+This project uses RCF. The tree under `rcf/` is the requirements spine and
+the `rcf` CLI plus the `rcf_*` MCP tools are the referee. The rules below
+are hard rules, not suggestions. Work is defined by FBS spec bundles, not
+by improvised task lists.
+
+This block is managed by `rcf doctor`. Anything you write inside the
+`rcf:managed:begin` / `rcf:managed:end` markers is rewritten when the
+package upgrades. Add your own project rules outside the markers.
+
+How to talk to your operator. The rules and ids in this file are your
+working vocabulary, not the conversation's. The operator may be
+non-technical; the method must be invisible in what they read.
+- Plain language. Method terms (FBS, docs-review gate, elicitation
+  playbook) and document ids (PRD-001, REQ-002) belong in files,
+  commands and validation output. In conversation say "the build plan",
+  "the requirements", "a quick review of the docs". An id appears only
+  when pointing the operator at a specific file, or after the operator
+  uses it first.
+- Never cite a rule. The rules below shape what you do, silently.
+  "Per RULE 1" means nothing to the operator and reads as bureaucracy.
+- Concise and decision-led. Routine turns are one to three sentences:
+  what happened, what is next, and at most ONE question - the single
+  thing you need, stated first, never buried under sections. No
+  multi-section essays for routine turns.
+- Self-serve before asking. Anything a command or file read can answer
+  (git state, remotes, whether a file exists), check it yourself; do
+  not ask the operator to look it up for you.
+- Never re-ask a granted permission. Track what the operator has
+  authorised and act on it. Asking again reads as not listening.
+- Tone: it is in hand. The operator steers; you drive. Confident
+  without hedging, and plainly honest when something is genuinely
+  blocked or ambiguous.
+
+Before / after - the same first status after project setup:
+
+  Too much: four sections walking the operator through PRD-001,
+  TAD-001, BS-001, REQ-001 and US-101, quoting RULE 1 and RULE 5,
+  explaining the docs-review gate, asking whether a git remote exists,
+  re-asking for push permission already granted, with the one real
+  question (the product's name) at the bottom.
+
+  Right: "Brief read - good shape. I'm committing the scaffold and
+  pushing now; the remote's already wired. Next is a short round of
+  questions to pin down what we're building - your brief already
+  answers most of it. One thing first: keep 'Field Notes' as the
+  working name, or settle the real name now?"
+
+### RULE 1: Elicit first; never fabricate.
+
+Before authoring or rewriting any RCF document, run the elicitation
+playbook (`rcf guidance elicitation-playbook` on the CLI or the
+`rcf_elicit_requirements` MCP prompt). Ask the stakeholder its questions
+and wait for answers. Document content comes from stakeholder answers. If
+a fact was not given to you, do not invent it. Ask. A chain written in
+one shot without stakeholder input is a method violation, not a
+deliverable.
+
+### RULE 2: The full chain is the deliverable.
+
+All layers: PRD, REQ, US, AC, TS, TC, plus the tech side (TAD, TAC, ADR).
+Do not drop a layer silently. Init-scaffold TODO placeholders are not a
+finished state. Every scaffolded doc is either authored with the
+stakeholder or its removal is explicitly agreed with them. If a layer
+seems inapplicable, say so and get the stakeholder's agreement before
+leaving it out.
+
+### RULE 3: The test layer is mandatory.
+
+Author TS and TC documents and run `rcf coverage --strict`. Do not
+declare the work done while coverage fails, unless the stakeholder has
+explicitly accepted the gap.
+
+### RULE 4: A reported bug is a spec gap first.
+
+When a bug is reported, do not jump to the code. First find the AC that
+should have required the correct behaviour and the test that should have
+caught it. Add or strengthen that AC (and its TS and TC) so the chain
+catches this class of bug, then fix the code against the corrected spec.
+
+### RULE 5: Deploy target before stack; never commit a stack blind.
+
+A technology stack must not be committed before the deploy target is
+established, and the stack is constrained to what that target can host.
+Choosing a stack the owner's hosting cannot run is a method violation,
+not a technical preference. This is an ordering rule: it forbids a stack
+ahead of the target. It does not require the owner to have a target, or
+to want one.
+
+Raise the question when a stack decision is actually due. If the owner
+names a target, constrain the stack to it. If the owner does not know
+and wants to settle it, run the hosting-choice walkthrough in the
+elicitation playbook and isolate the sign-up, billing, token and
+CLI-auth steps as the human account-holder's to do. Do not perform or
+pretend them.
+
+If the owner defers, is still exploring, or is not deploying, that is an
+answer, not a blocker. Do not press for a provider and do not stand an
+account up. Record the deferral as the ADR, hold back the live half of
+what was deferred, and build to RULE 6's local preview. A deferred
+capability's acceptance criteria are deferred with it, visibly, or
+scoped to a stub the owner explicitly agreed to.
+
+Capture the deploy target, or its deferral, and any stack constraint it
+implies as an ADR on the project's own tree.
+
+### RULE 6: Every build lands a local preview.
+
+A build is not done until it leaves a working, documented local preview
+as its default outcome: a dev server, seeded data where the app needs
+it, ideally started with one documented command. This holds whether or
+not a host was named and whether or not a deploy happened. Remote
+deployment is an addition on top of local preview, never a replacement
+for it.
+
+### RULE 7: Verification claims name their runtime.
+
+Every "verified" or "tested" claim, in the Test and Finalise stages and
+in the PR body's verification section, names the runtime it was checked
+against (for example, "verified against wrangler dev on localhost, not
+the deployed Worker runtime"). A claim with no named runtime is
+incomplete.
+
+Never state or imply verification on a deployed runtime that was not
+exercised. A green test suite is evidence about the runtime it ran on
+and nothing more. A ship verdict comes only from the deployed runtime
+or a declared runtime-parity claim.
+
+### RULE 8: Never skip the method for speed.
+
+If a bug fix, polish item, or "small thing" would move faster by
+bypassing RCF, that is the moment the method matters most. Do not offer
+the operator a "skip the spec and just push a fix branch" option. If the
+work is genuinely too small to warrant a full chain touch, say so and
+propose the minimum spec update that keeps the chain honest. The
+operator can choose to accept a shortcut. Offering one first is the
+defect.
+
+### RULE 9: Write what you learn.
+
+`rcf/knowledge/` is this project's memory. Every session, if you
+learned something the next session should not have to relearn, write it
+there. `notes/` for internal facts (decisions, gotchas, runtime facts,
+"the CI matrix uses Node 22 not 24"). `docs/` for user-facing prose the
+project surfaces. One topic per file. Grep the tree before asking the
+stakeholder something you might already know. See
+`rcf/knowledge/README.md` for the convention.
+
+### RULE 10: Read the operator profile.
+
+If `rcf/.identity/profile.md` exists, read it at session start. It
+describes the operator: name, role, working style, project-scoped
+preferences. It is per-clone (gitignored by default), so it may hold
+things the operator does not want in the shared repo. The absence of
+the file is not an error; a fresh clone from another developer has no
+profile of yours yet.
+
+### Session start
+
+Run `rcf validate`. A broken tree is fixed or reported before anything
+else. Run `rcf build` for queue state: what is done, in progress,
+blocked. Run `rcf doctor` if the last upgrade of the package changed
+these rules. The block you are reading may be out of date; `rcf doctor
+--fix` rewrites it.
+
+### Build loop
+
+Docs-review gate: when the tree has just been elicited, offer the
+stakeholder a review of it before the first build. Do not roll from
+elicitation straight into building without the offer.
+
+Run `rcf build --next` to get the spec bundle for the next actionable
+item, then execute the five-stage runbook it prints: Define, Build,
+Review, Test, Finalise. Every stage ends in a commit. Drive the whole
+queue, not one item. After each item's Finalise, loop `rcf build --next`
+until it reports the queue complete. If your harness can spawn
+sub-agents, run each FBS in its own worker so the driving context stays
+clean across the queue: one write worker at a time.
+
+Record lifecycle transitions with the exact mark commands the bundle
+prints. Never mark backwards. Run `rcf validate` after any tree edit,
+and `rcf trace <id>` or `rcf impact <id>` before touching anything with
+dependents. PR bodies are evidence-first: lead with what was verified
+and how, traced to AC and FBS ids, not a diff walk.
+
+Run the fresh-context self-review every few FBS builds and once at the
+end: a reviewer that drives the running app against its ACs, not one
+that reads the code. Method: `rcf guidance build-cycle-playbook`,
+section 16. It is the cheap in-loop check between builds, and it is not
+the independent verification gate. `rcf finalise` runs that, and only
+that writes `verified`.
+
+If context gets unreliable on a large build, do not stall. Write a
+next-session handover doc (queue state, the in-progress item, the next
+actionable id), add a line to this file (outside the managed markers)
+pointing the next session at it, then stop. A fresh session must resume
+without re-elicitation.
+
+### Write discipline
+
+Prefer the `rcf` verbs (`create`, `update`, `delete`, `link`) for tree
+edits. After any hand edit to a file under `rcf/`, run `rcf validate`
+before proceeding.
+
+### Escalation
+
+If the bundle is ambiguous or contradicts the tree, stop and ask; do
+not interpret. Never mark a stage done without its referee output.
+
+### MCP-wired harnesses
+
+The same contract holds over the server's `rcf_*` tools and prompts.
+Method depth, either wiring: the `rcf_execute_build_cycle` prompt, or
+on the CLI `rcf guidance build-cycle-playbook`, for the build loop,
+queue orchestration, PR authoring and bug triage. The
+`rcf_elicit_requirements` prompt, or `rcf guidance elicitation-playbook`,
+for elicitation, AC coverage depth and conversation integrity. Run `rcf
+guidance` with no arguments to list every method document the installed
+package ships.

package/guidance/managed/legacy-fragment-hashes.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "description": "SHA-256 whitelist of the trimmed inner content between legacy `<!-- rcf:begin -->` / `<!-- rcf:end -->` markers, as written into CLAUDE.md/AGENTS.md by every pre-0.6.0 release. Doctor's `detectLegacyHandEdits` (packages/build/src/cli/doctor.js) hashes the extracted legacy inner content (trimmed) and treats any hash NOT in this whitelist as hand-edited. Fail-safe by default: unknown content requires the operator to pass `--force` in non-interactive mode. Spec §7.3 (packages/build/../specs/2026-07-30_init-hygiene-0.6.0-spec.md).",
+  "provenance": "Hashes derived deterministically from the repo's own git history. Each entry cites the release tag(s) whose `packages/build/guidance/harness-template.md` produced it. The pre-0.6.0 `agent-setup.js:loadHarnessFragment()` extracted `m[1].trim()` from the first ```markdown fence, then `writeAgentInstructions` wrote the block as `${MARKER_BEGIN}\\n${fragment}\\n${MARKER_END}`. Extraction via `fileText.slice(beginAt + MARKER_BEGIN.length, endAt)` returns `\\n${fragment}\\n`; `.trim()` recovers `fragment` verbatim. `sha256(fragment, utf8)` matches this whitelist. Regenerate with `node scripts/derive-legacy-fragment-hashes.mjs` if additional pre-0.6.0 revisions ever need coverage.",
+  "hashes": [
+    {
+      "hash": "3bc3c657f9b41b60bb3e0102e24c2f5e59baad96828e6647f02fbbbbea528f85",
+      "sources": ["build-v0.4.0"],
+      "fragmentLength": 5960
+    },
+    {
+      "hash": "607a8ce652e5a490726f7f5b4d56c4be0ec5682d18ba278c4642c31d0dc42ecd",
+      "sources": ["build-v0.5.0", "build-v0.5.1"],
+      "fragmentLength": 7044
+    },
+    {
+      "hash": "7e6402c683dadea9d77da8a5535bcedc49671f84531d1181c1c8a519ecf00929",
+      "sources": ["build-v0.5.2"],
+      "fragmentLength": 9147
+    }
+  ]
+}

package/guidance/manifest.json

@@ -0,0 +1,21 @@
+{
+  "docs": [
+    {"slug": "overview", "file": "overview.md", "title": "RCF overview"},
+    {"slug": "document-model", "file": "document-model.md", "title": "RCF document model"},
+    {"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"}
+  ],
+  "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 --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."}
+  ],
+  "platformInvariants": [
+    {
+      "id": "never-skip-rcf",
+      "title": "Never-skip-RCF",
+      "text": "**Never-skip-RCF.** The bug-fix loop uses the same five-stage cycle as the initial build (Define, Build, Review, Test, Finalise); there is no fast-path, and there is no operator ruling that opens one. Do not offer a shortcut. Do not phrase the choice as \"would you rather I skip the RCF wrapping\" or any wording that presents bypassing the chain as a legitimate option. The offer itself is the defect. The operator's refusal is not a sign the invariant held; it is a sign the invariant was tested and the guidance surface leaked. Fix the guidance surface."
+    }
+  ]
+}

package/guidance/overview.md

@@ -0,0 +1,48 @@
+# RCF overview
+
+The Requirements Confidence Framework (RCF) is a document model and a build method. It keeps every piece of shipped work connected, through explicit documents on disk, to the requirement that asked for it and the test that verifies it. The `rcf` CLI referees that structure mechanically; the agent and the human operating the loop supply the judgement.
+
+## The confidence gap
+
+AI-driven development produces working code faster than a human can check it against intent. The result is a gap: the code runs, the tests pass, and nobody can say with confidence which stated requirement each change serves or whether every requirement is actually verified. RCF closes that gap structurally. Requirements, stories, acceptance criteria and tests are documents with typed references, so "does this code serve a requirement?" becomes a query, not an act of faith.
+
+## The document hierarchy
+
+```
+PRD -> REQ -> US / AC -> TAC / ADR -> BS / FBS -> TS / TC
+```
+
+- **PRD** - the product intent: the problem, who has it, what changes when it is solved.
+- **REQ** - one testable capability the product must have.
+- **US / AC** - a user story under a requirement, carrying acceptance criteria: observable, testable statements of done.
+- **TAC / ADR** - the architecture as components (TAC) and decisions (ADR), referenced by the work that depends on them.
+- **BS / FBS** - the build sequence and its functional build specifications: the ordered queue of work items, each scoped to a set of acceptance criteria.
+- **TS / TC** - test suites and test cases, each pointing at the acceptance criteria they verify.
+
+The full per-type detail is in `rcf://docs/document-model`.
+
+## The three traceability questions
+
+Every RCF query is one of three questions:
+
+1. **Is it covered?** Does every acceptance criterion have a test case whose pointer resolves to a real test? (`rcf coverage`)
+2. **What does it trace to?** Which requirement asked for this; which stories, criteria and tests hang off it? (`rcf trace`)
+3. **What breaks if it changes?** Which documents and tests are invalidated by a change to this one? (`rcf impact`)
+
+## The build cycle in five lines
+
+1. **Define** - confirm the plan against every in-scope acceptance criterion in the spec bundle.
+2. **Build** - implement to those criteria and nothing beyond them.
+3. **Review** - validate the tree, then re-read the diff against every in-scope criterion.
+4. **Test** - write tests until strict coverage holds over the in-scope criteria.
+5. **Finalise** - CI green, merge, then record the lifecycle transition.
+
+Every stage ends in a commit. The normative statement is `rcf://docs/build-cycle`; the deep guidance is the `rcf_execute_build_cycle` prompt.
+
+## Mechanical, not semantic
+
+The tool referees structure, never adequacy. `rcf validate` proves every document matches its schema and every reference resolves; `rcf coverage` proves every acceptance criterion has a test case whose `testPointer` resolves to a real, named test in the tree - a test-case row with a dead or missing pointer is reported as `covered-unresolved`, never as coverage. Neither proves that the acceptance criteria capture the requirement's intent, or that a test asserts the right behaviour: a renamed test is caught, a gutted test that kept its name is not. That judgement belongs to the agent and the human operating the loop. The tool's contribution is to make the structural half of confidence mechanical, so judgement is spent only where judgement is needed.
+
+---
+
+Canonical reference: https://stravica.ai/rcf-methodology/overview