Release v0.5.0 — Receipt

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Torque Loop — a single-plugin marketplace.",
-    "version": "0.4.0"
+    "version": "0.5.0"
   },
   "plugins": [
     {
       "name": "ratchet",
       "source": "./",
       "description": "Torque Loop: turns ambiguous work into shipped artifacts through target locking, adversarial validation, patching, and state serialization, plus a bounded /ratchet:evolve loop.",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "author": {
         "name": "Danny Gillespie"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ratchet",
   "displayName": "Torque Loop",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Torque Loop turns ambiguous work into shipped artifacts through target locking, adversarial validation, patching, and state serialization — plus a bounded /ratchet:evolve loop. A stateful advancement engine, not a prompt library. Not affiliated with Anthropic.",
   "author": {
     "name": "Danny Gillespie"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "torque-loop",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Torque Loop evolves ambiguous work into shipped, tested, serialized artifacts through evidence-gated loops.",
   "author": {
     "name": "Danny Gillespie",

CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-04 — Receipt
+
+0.2 gated proof; 0.3 gated the *seam* of that proof; 0.4 metered the *depth* of the loop.
+0.5 gives the loop a single cockpit: **one read — `ratchet receipt` — that says what is
+true, what changed, what was proven, what is at risk, whether it is safe to ship, and
+whether the receipt's own steering can be trusted.**
+
+### Added
+
+- **The receipt (`ratchet receipt`)** — one stable, always-same-shape read with eight fixed
+  sections (TARGET · DELTA · PROOF · VERDICT · RISK · AUTHORITY · STATE · NEXT), joining session
+  state, the evolve journal, the QA ledger, and git. Emptiness is stated, never omitted, so the
+  shape never shifts between commands or sessions. `--json` emits the same structure for
+  consumers; `--save` writes `.ratchet/current.json` + `current.md` as a gitignored
+  source-of-truth index.
+- **Three-layer confidence** — `ratchet score confidence` scores artifact · session · ledger
+  independently, each naming its scope. A verified artifact stays ship-ready even when unrelated
+  debt tanks session confidence — killing the "verified green but reported blocked" gaslight.
+- **Cold-start control-plane scan** — the receipt runs the cold-start poison scan inline and
+  renders `Control-plane scan: FAIL|WARN|clean` under STATE (also exposed as a top-level
+  `controlPlane` field in `--json`), surfacing stale steering (retracted work still being pointed
+  at) and misleading configured operator surfaces (e.g. unqualified git counts) in the one cold
+  read — no separate doctor run. Project surfaces are an opt-in adapter declared in
+  `.ratchet/cold-start.json`; no workspace path is hardcoded.
+
+### Changed
+
+- **`state reset` now requires `--force`** — an ungated canonical wipe is refused; the receipt
+  AUTHORITY card renders the gates in force.
+- **Agents are propose-only** — only the scribe writes canonical state; the builder and auditor
+  are refused mutating verbs at the CLI boundary via `RATCHET_AGENT` (they read and propose).
+
 ## [0.4.0] - 2026-07-03 — Aperture
 
 0.2 gated proof; 0.3 gated the *seam* of that proof. 0.4 adds the dial that decides how

CLAUDE.md

@@ -0,0 +1,56 @@
+<role>
+You are the continuation maintainer of Torque Loop, resuming it in a fresh context. Torque Loop is a zero-dependency Claude Code + Codex plugin (Node ≥ 18) that turns ambiguous work into shipped, tested, serialized artifacts through evidence-gated loops. Operate the project by its own discipline: frame → choose → build → attack → patch → serialize → advance.
+</role>
+
+<prime_directive>
+No proof → no keep. No keep → no progress claim. Every change you keep is justified by evidence, not assertion, and the diff is the smallest one that clears the defect.
+</prime_directive>
+
+<context>
+- Repo: the Torque Loop plugin itself (skills/, agents/, hooks/, bin/, src/, test/, templates/).
+- Current release: v0.4.0 "Aperture". Version is aligned across package.json and every manifest; `npm test` runs three zero-dependency suites (cli, evolve, plugin-shape) and MUST stay green.
+- Already shipped: 0.2 proof gate ("no proof → no keep"), 0.3 seam gate ("wrong proof → no ship"), 0.4 aperture dial (meter loop depth to the uncertainty it earns).
+- IGNORE the `.ratchet/current.json` and `current.md` in the tree: that is dogfooding residue from running ratchet on an unrelated project ("lucidia" / F4 prepare-turn), NOT Torque Loop's roadmap. Do not adopt its open defect or next-action as ours.
+</context>
+
+<constraints>
+- Zero new runtime dependencies; adding one requires an explicit, stated justification.
+- Every behavior change ships with a test that would fail without it.
+- Keep diffs minimal — REMOVE / ADD / CHANGE only what the change requires; never rewrite working code for elegance.
+- Match the surrounding voice: terse, concrete, active, no filler. CommonJS, Node ≥ 18, no build step.
+</constraints>
+
+<task>
+1. Establish Torque Loop's own locked target for this session (not the borrowed lucidia state). If I have not named one, infer the highest-leverage next refinement from CHANGELOG's [Unreleased] section plus the current source, state your assumption, and proceed.
+2. Run one full evidence-gated loop on that target:
+   - LOCK it (object, outcome, proof-of-done, forbidden scope).
+   - Read ground truth first (relevant SKILL.md, src/*.js, test/*.js) before editing.
+   - BUILD the smallest change → ATTACK with the five-voice hostile board → PATCH only what failed → VERIFY with `npm test` (or the narrowest relevant suite), never self-grade.
+   - Keep only if proven; otherwise revert and record the lesson.
+3. SERIALIZE the result into a compact handoff the next fresh context can resume from with zero re-derivation.
+</task>
+
+<what_to_read_first>
+- reference/PROMPTS.md — canonical intent each skill implements (source of truth over the skills).
+- CHANGELOG.md [Unreleased] — where the roadmap points next.
+- src/scoring.js, src/evolve/schema.js, src/receipt.js — load-bearing logic and the gates.
+- test/*.test.js — the falsifiable contract you must keep green.
+</what_to_read_first>
+
+<output_format>
+Return exactly:
+
+LOCKED TARGET: <one line — object → outcome, proof-of-done>
+GROUND TRUTH READ: <files inspected + the one constraint that changes the plan>
+CHANGE: <the minimal REMOVE/ADD/CHANGE diff>
+ATTACK: <n critical / n high — top failure mode>
+VERIFY: <command run + pass/fail>
+VERDICT: KEEP | REVERT | REVERTED_AND_LEARNED — <why, tied to the evidence>
+REMAINING RISK: <what must not be trusted yet>
+NEXT EDGE: <the single next small, testable refinement on this same repo>
+HANDOFF SENTENCE: <one load-bearing line to prime the next fresh context>
+</output_format>
+
+<success_criteria>
+The turn is complete only when an artifact exists, `npm test` is green (or a failure is honestly reported), and the handoff sentence would let a cold agent take the correct next action without asking you anything.
+</success_criteria>

README.md

@@ -297,6 +297,33 @@ builder's own search method is rejected as not independent.
 | `ratchet git status-refs` | Ahead/behind vs every base ref — each one named. |
 | `ratchet doctor cold-start` | Scan for stale steering (opt-in surfaces via `.ratchet/cold-start.json`). |
 
+### The receipt — one control surface (`ratchet receipt`)
+
+`ratchet receipt` is the cockpit: one stable read a cold human or agent can parse in under a
+minute, so state never lives only in the transcript. Eight fixed sections, same order every
+time, emptiness stated rather than omitted:
+
+```text
+TARGET · DELTA · PROOF · VERDICT · RISK · AUTHORITY · STATE · NEXT
+```
+
+- **PROOF** carries the KEEP evidence card and the seam (tested → ships). If the seam is a
+  proxy and not waived, it says **"Cannot justify ship decision"** out loud — proxy proof
+  never masquerades as ship proof.
+- **VERDICT** splits confidence into three independently-scoped layers so a verified patch is
+  never gaslit to *blocked* by unrelated debt:
+
+  | Layer | Answers | Scope |
+  | --- | --- | --- |
+  | Artifact confidence | Is *this* patch good? | the current artifact's own holes, attached defects, and verification evidence |
+  | Session confidence | Can the loop stop? | active open defects, untested assumptions, next action |
+  | Ledger health | Is the record clean? | historical open/stale defects and failing tests |
+
+- **AUTHORITY** names where the work sits on the ladder — `uncommitted → committed-local →
+  pushed → released` — plus every irreversible action's owner and the gates in force.
+- `ratchet receipt --save` writes `.ratchet/current.json` + `.ratchet/current.md` — the
+  always-current source-of-truth index a new agent reads first.
+
 ---
 
 ## How it works
@@ -316,10 +343,11 @@ The skills carry the reasoning; the CLI carries the state. A skill loads context
 the CLI, does its work, and writes the result back:
 
 ```bash
+ratchet receipt                    # one stable resume read: target·delta·proof·seam·verdict·authority·state·next
 ratchet status                     # what the ratchet knows right now
 ratchet snapshot repo              # cheap ground-truth read of the codebase
 ratchet score friction '[...]'     # rank obstacles: Leverage × Certainty × Time × Risk (1–10)
-ratchet score confidence           # session confidence + whether the loop may stop
+ratchet score confidence           # three scoped layers: artifact · session · ledger health
 ratchet artifact add '{...}'       # record an artifact
 ratchet defect add '{...}'         # record a defect (also lands in the QA ledger)
 ratchet export markdown            # the full compile / handoff
@@ -333,6 +361,13 @@ Run `ratchet --help` for the complete surface.
 - **`ratchet-auditor`** — attacks artifacts, assumptions, and self-serving reasoning.
 - **`ratchet-scribe`** — serializes state, decisions, defects, and next moves.
 
+**Memory isolation by role.** The registered agents have isolated memory enforced at the CLI
+boundary: only the scribe writes canonical state. Builder and auditor are *propose-only* —
+run under `RATCHET_AGENT=<name>`, their mutating verbs are refused, so they emit the exact
+`ratchet …` command for the caller (or the scribe) to run instead of clobbering the shared
+record. Read verbs (`ratchet receipt`, `status`, `snapshot`, `score`) stay open to every
+agent. One writer, many proposers — agents cannot overwrite each other's memory.
+
 ### The hooks (conservative by design)
 
 Ratchet creates pressure, not surprise. The hooks never run tests or edits on their own:

agents/ratchet-auditor.md

@@ -36,6 +36,12 @@ Run the artifact past five reviewers. Speak in each voice; do not blur them.
 5. **Kill false confidence.** If the artifact is genuinely fine on a dimension, say so in
    one word and move on. Do not manufacture findings, but default to skepticism.
 
+6. **Propose, never write.** You have **propose-only memory**: emit the exact
+   `ratchet defect add '{...}'` line for each real defect and let the caller (or the
+   `ratchet-scribe`) serialize it. Run under `RATCHET_AGENT=ratchet-auditor` and the CLI
+   enforces this — mutating verbs are refused, so your audit cannot mutate the record it is
+   auditing. Read verbs stay open.
+
 ## Output shape
 
 ```

agents/ratchet-builder.md

@@ -26,8 +26,12 @@ or produce plans-about-plans. You produce the thing.
 5. **Match the surrounding code.** When editing a repo, read neighbors first and mirror
    their idiom, naming, and comment density. Never introduce a new style.
 
-6. **Record it.** When done, propose the exact `ratchet artifact add '{...}'` line so the
-   caller can serialize the artifact into state.
+6. **Record it — propose, never write.** When done, propose the exact
+   `ratchet artifact add '{...}'` line so the caller (or the `ratchet-scribe`) can serialize
+   it. You have **propose-only memory**: you do not run canonical-state mutations yourself.
+   Run under `RATCHET_AGENT=ratchet-builder` and the CLI enforces this — mutating verbs are
+   refused so you cannot clobber the shared record or another agent's work. Read verbs
+   (`ratchet receipt`, `status`, `snapshot`, `score`) stay open to you.
 
 ## Output shape
 

agents/ratchet-scribe.md

@@ -14,9 +14,12 @@ re-deriving anything. You are precise and you never embellish.
    defects actually found, loops actually left open. If it was discussed but not decided,
    it is an open loop, not a decision.
 
-2. **Write through the CLI.** Persist via `ratchet state set`, `ratchet state append`,
-   `ratchet artifact add`, and `ratchet defect add`. Read current state first with
-   `ratchet status --json` so you extend rather than overwrite.
+2. **Write through the CLI — you are the sole writer.** Persist via `ratchet state set`,
+   `ratchet state append`, `ratchet artifact add`, and `ratchet defect add`. Read current
+   state first with `ratchet status --json` so you extend rather than overwrite. Among the
+   registered agents, only you mutate canonical state (builder and auditor are propose-only,
+   enforced by the CLI). Run unnamespaced, or set `RATCHET_AGENT=scribe` — either way the
+   guard lets you write; that single-writer rule is what keeps agent memory from colliding.
 
 3. **Every compile ends with a single next action and a single next command.** If you
    cannot name the next action, that itself is the finding — say the objective is unclear.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torque-loop/plugin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Torque Loop — a Claude Code and Codex plugin that evolves ambiguity into shipped, tested, serialized artifacts through evidence-gated loops.",
   "license": "MIT",
   "author": "Danny Gillespie",

skills/handoff/SKILL.md

@@ -12,11 +12,15 @@ start acting immediately — no re-reading the session, no re-deriving decisions
 ## Step 0 — Load state
 
 ```
+ratchet receipt
 ratchet export markdown
 ratchet score confidence
 ```
 
-Delegate to the `ratchet-scribe` subagent for a long or high-stakes session.
+Start from `ratchet receipt` — its eight fixed sections (target · delta · proof · seam ·
+verdict · authority · state · next) are already the handoff spine; the steps below expand
+each one for the receiver. Delegate to the `ratchet-scribe` subagent for a long or
+high-stakes session.
 
 ## Procedure
 

skills/status/SKILL.md

@@ -10,15 +10,21 @@ where the ratchet sits, so you resume instead of restart.
 
 ## Procedure
 
-Read the serialized state and render it:
+Lead with the **receipt** — one stable read that answers *what is true, what changed, what
+is safe, what is blocked, and what happens next* without transcript archaeology:
 
 ```
-ratchet status
+ratchet receipt
 ```
 
-Add the confidence read and repo ground-truth when useful:
+The receipt always shows the same eight sections in the same order — **target · delta ·
+proof · seam · verdict · authority · state · next** — so a cold human or agent can resume in
+under a minute. Emptiness is stated, never omitted.
+
+For the detailed state view or a specific read, add:
 
 ```
+ratchet status          # the full state summary
 ratchet score confidence
 ratchet snapshot repo
 ```
@@ -27,7 +33,8 @@ ratchet snapshot repo
 
 - **Current objective** — the locked target.
 - **Bottleneck** — the chosen blocker.
-- **Confidence** — score/100 + band, and whether the loop is clear to stop.
+- **Confidence** — three scoped layers (artifact · session · ledger health), so a verified
+  patch is never shown as blocked because of unrelated debt.
 - **Active / last artifact** — what exists now.
 - **Last decision** — the most recent commitment.
 - **Open defects** — unresolved failures, by severity.
@@ -37,7 +44,7 @@ ratchet snapshot repo
 
 ## Output contract
 
-Return the rendered state verbatim, then one line of interpretation:
+Return the rendered receipt verbatim, then one line of interpretation:
 
 ```
 READ: <one sentence — where the ratchet is and the single most useful next move>