Release/v0.2.0 proof gate

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Torque Loop — a single-plugin marketplace.",
-    "version": "0.1.0"
+    "version": "0.2.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.1.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.",
+      "version": "0.2.0",
       "author": {
         "name": "Danny Gillespie"
       },

.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "ratchet",
   "displayName": "Torque Loop",
-  "version": "0.1.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.",
+  "version": "0.2.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"
   },

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -41,7 +41,7 @@ body:
       options:
         - A /ratchet:* slash command (plugin)
         - The `ratchet` CLI
-        - The `ratchet-evolve` CLI / loop
+        - The `ratchet-evolve` CLI / `/ratchet:evolve` loop
         - A hook (SessionStart / PostToolUse / Stop)
         - Install / marketplace
         - Docs / README
@@ -53,7 +53,7 @@ body:
     attributes:
       label: Versions
       description: Output of `node --version` and `ratchet --version`, plus your OS.
-      placeholder: node v20.11.0 · ratchet 0.1.0 · Windows 11
+      placeholder: node v20.11.0 · ratchet 0.2.0 · Windows 11
     validations:
       required: true
   - type: textarea

.github/workflows/ci.yml

@@ -34,4 +34,6 @@ jobs:
         run: |
           node bin/ratchet --version
           node bin/ratchet --help
+          node bin/ratchet doctor
           node bin/ratchet-evolve --help
+          node bin/ratchet-evolve status

CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-03 — Proof Gate
+
+Hardening, not expansion. This release makes the loop's philosophy mechanically true:
+a cleaner command surface, an enforced proof gate, trustworthy state, and a verified
+plugin shape. **No proof → no keep** is now enforced by code, not just by convention.
+
+### Added
+
+- **Proof gate.** `ratchet-evolve log append` now rejects a `KEEP` verdict that lacks
+  verification evidence: a failed result, or no command/manual checks, or a `manual`
+  result with no explicit checks, all throw before anything is written. `REVERT` and
+  `ASK` are exempt by design.
+- **`ratchet compile done`** — atomically stamps `lastCompileAt`, clears the dirty flag,
+  and records a `compile.done` history event, so the Stop hook stops nagging after a
+  compile.
+- **`ratchet doctor`** — a plugin health check: Node version, manifest parsing, version
+  alignment, required directories, every `SKILL.md` frontmatter/description, `hooks.json`,
+  bin targets, state-dir writability, and a live repo-snapshot probe. Exits non-zero on
+  any failure.
+- **`ratchet-evolve next`** — reads the last recorded next edge (`--json` supported).
+- **Manual-evidence templates** — `templates/evolve-event.json`,
+  `templates/evolve-manual-checks.md`, and `templates/evolve-report.md`.
+- **Plugin-shape test suite** (`test/plugin-shape.test.js`) — asserts manifests parse and
+  align, CLI version constants match `package.json`, every skill has a valid `SKILL.md`,
+  agents have frontmatter, bin targets exist, and the README command list matches the
+  skill folders (and mentions no removed command names). Wired into `npm test` and CI.
+
+### Changed
+
+- **Renamed the evolution command** from `/ratchet:ratchet-evolve` to `/ratchet:evolve`
+  (skill folder `skills/ratchet-evolve/` → `skills/evolve/`). The helper CLI binary stays
+  `ratchet-evolve`. No compatibility alias is kept.
+- `ratchet-evolve status` now reports kept / reverted / **asks** / active targets / last
+  verdict / next edge.
+- CLI version strings are now derived from `package.json`, making it the single source of
+  truth for the plugin, both CLIs, and the marketplace manifest.
+- The compile flow (`/ratchet:compile`, `ratchet-scribe`) now calls `ratchet compile done`
+  instead of setting `lastCompileAt` by hand.
+- Bumped package, plugin, and marketplace manifests to `0.2.0`.
+- CI smoke-checks now include `ratchet doctor` and `ratchet-evolve status`.
+
+### Fixed
+
+- `--version` printed the full help text instead of the version, on both CLIs.
+- The dirty-state Stop-hook reminder persisted after a compile; `ratchet compile done`
+  now clears it.
+- The evolution journal accepted `KEEP` events with no verification evidence.
+- Repo snapshots hid plugin-critical dot directories (`.claude-plugin`, `.github`,
+  `.claude`, `.ratchet`) via a blanket dot-dir skip; an allowlist now surfaces them while
+  still ignoring `.git`, `node_modules`, and caches.
+- Malformed `state.json` / `ledger.json` were silently discarded; they are now backed up
+  to `<file>.corrupt.<timestamp>.json` before a fresh file is created.
+
+### Removed
+
+- `/ratchet:ratchet-evolve` (renamed to `/ratchet:evolve`).
+
 ## [0.1.0] - 2026-07-03
 
 Initial public release.
@@ -31,5 +88,6 @@ Initial public release.
 - Single-plugin marketplace manifest so the repo installs directly as a Claude Code plugin.
 - Zero-dependency smoke test suites for the state engine and the evolution helpers.
 
-[Unreleased]: https://github.com/TheLucidTech/torque-loop/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/TheLucidTech/torque-loop/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/TheLucidTech/torque-loop/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/TheLucidTech/torque-loop/releases/tag/v0.1.0

README.md

@@ -21,7 +21,7 @@ It bundles two things:
 
 - **The Ratchet command family** (`/ratchet:*`) — a consequence engine that turns ambiguity
   into shipped, falsifiable artifacts through adversarial execution loops.
-- **`/ratchet-evolve`** — a narrower, bounded loop that mutates one artifact, tests it, and
+- **`/ratchet:evolve`** — a narrower, bounded loop that mutates one artifact, tests it, and
   keeps only proven improvement.
 
 Every command produces *pressure*, not just insight. Each one forces a choice, creates an
@@ -113,7 +113,7 @@ node bin/ratchet --help
 Verify:
 
 ```bash
-ratchet --version      # -> ratchet 0.1.0
+ratchet --version      # -> ratchet 0.2.0
 ratchet init
 ratchet status
 ```
@@ -175,15 +175,15 @@ artifact (code file, prompt, skill, README, spec, workflow):
 
 | Command | Purpose |
 | --- | --- |
-| `/ratchet:ratchet-evolve` | Mutate → test → keep only proven improvement → serialize the next edge. |
+| `/ratchet:evolve` | Mutate → test → keep only proven improvement → serialize the next edge. |
 
 ```
 LOCK → SNAPSHOT → PRESSURE → MUTATE → JUDGE → APPLY → VERIFY → KEEP/REVERT/ASK → RECORD → NEXT EDGE
 ```
 
 ```bash
-/ratchet:ratchet-evolve src/auth/session.js --goal "reduce login-state race conditions" --test "npm test -- auth" --mode code
-/ratchet:ratchet-evolve README.md --goal "make install impossible to misunderstand" --mode docs
+/ratchet:evolve src/auth/session.js --goal "reduce login-state race conditions" --test "npm test -- auth" --mode code
+/ratchet:evolve README.md --goal "make install impossible to misunderstand" --mode docs
 ```
 
 It defaults to `--iterations 2` and **proposes** patches without `--write`. Its rule is
@@ -192,8 +192,30 @@ this better" — it evolves along one chosen pressure vector and records every v
 `.ratchet/evolve-log.jsonl` via the `ratchet-evolve` helper CLI.
 
 > Note: because plugin skills are namespaced by the plugin, the command is invoked as
-> `/ratchet:ratchet-evolve`. Drop the `SKILL.md` into `~/.claude/skills/ratchet-evolve/` to
-> use it as a bare `/ratchet-evolve` outside the plugin.
+> `/ratchet:evolve` (renamed from the older `ratchet-evolve` skill in v0.2.0 — no alias is
+> kept). Drop the `SKILL.md` into `~/.claude/skills/evolve/` to use it as a bare `/evolve`
+> outside the plugin.
+
+#### One run, end to end
+
+```text
+Before:    README install path is ambiguous — global vs. project vs. CLI-only blur together.
+
+Command:   /ratchet:evolve README.md --goal "make install impossible to misunderstand" --mode docs
+
+Mutation:  Split install into three labelled paths (global plugin, project-local, CLI-only),
+           each with its own verify step. No other section touched.
+
+Verify:    Manual docs checks — first-use path unambiguous, no contradiction, no missing step
+           between install and first success. All passed.
+
+Verdict:   KEEP        ← allowed only because evidence exists; the proof gate rejects a bare KEEP
+
+Next edge: Add a 60-second GIF of the plugin install.  (readable later via `ratchet-evolve next`)
+```
+
+Every verdict lands in `.ratchet/evolve-log.jsonl`. A `KEEP` without verification evidence is
+refused at write time — the loop cannot record progress it did not prove.
 
 ---
 

agents/ratchet-scribe.md

@@ -24,8 +24,9 @@ re-deriving anything. You are precise and you never embellish.
 4. **One-sentence memory.** Produce a single sentence that captures the session's state
    well enough to prime a cold start. This is the highest-value line; make it load-bearing.
 
-5. **Stamp the compile.** After writing, set `lastCompileAt` and clear the dirty flag by
-   running `ratchet state set lastCompileAt "<now>"` so the Stop hook stops nagging.
+5. **Stamp the compile.** After writing everything else, run `ratchet compile done` — it
+   stamps `lastCompileAt`, clears the dirty flag, and records a `compile.done` event in one
+   atomic move so the Stop hook stops nagging. Run it last, or a later `state set` re-dirties.
 
 ## Output shape
 

bin/ratchet-evolve

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
-// Deterministic helpers for the /ratchet-evolve loop. The reasoning lives in
-// skills/ratchet-evolve/SKILL.md; this binary provides snapshot, scoring,
+// Deterministic helpers for the /ratchet:evolve loop. The reasoning lives in
+// skills/evolve/SKILL.md; this binary provides snapshot, scoring,
 // verification, and the evolution journal.
 
 try {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torque-loop/plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Torque Loop — a Claude Code plugin that evolves ambiguity into shipped, tested, serialized artifacts through evidence-gated loops. Not affiliated with Anthropic.",
   "license": "MIT",
   "author": "Danny Gillespie",
@@ -14,7 +14,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/cli.test.js && node test/evolve.test.js",
+    "test": "node test/cli.test.js && node test/evolve.test.js && node test/plugin-shape.test.js",
     "ratchet": "node bin/ratchet",
     "ratchet-evolve": "node bin/ratchet-evolve"
   },

skills/compile/SKILL.md

@@ -46,10 +46,12 @@ ratchet artifact add '{"title":"...","kind":"...","status":"...","holes":["..."]
 ratchet defect add '{"severity":"...","summary":"...","status":"..."}'                 # if any new
 ratchet state append openLoops '{"text":"...","status":"open"}'                        # if any
 ratchet state set phase compile
-ratchet state set lastCompileAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+ratchet compile done
 ```
 
-Setting `lastCompileAt` clears the Stop-hook nag. Then emit the record:
+`ratchet compile done` clears the dirty flag, stamps `lastCompileAt`, and records a
+`compile.done` history event in one atomic move — which silences the Stop-hook nag. (Run it
+last: a `state set` after it would re-dirty the session.) Then emit the record:
 
 ```
 ratchet export markdown

skills/ratchet-evolve/SKILL.md → skills/evolve/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ratchet-evolve
+name: evolve
 description: "Evolve one artifact through a bounded, evidence-gated mutation loop — lock target, snapshot baseline, apply one pressure, generate candidate deltas, judge, patch, verify, keep or revert, record state, and name the next edge. Not brainstorming and not a general 'make this better': every kept change must be proven. Use to harden a specific code file, prompt, skill, test suite, README, spec, or workflow along a chosen pressure vector."
 argument-hint: "<target> --goal \"<improvement>\" [--iterations 2] [--test \"<cmd>\"] [--mode code|prompt|docs|workflow|auto] [--write]"
 allowed-tools:
@@ -35,7 +35,7 @@ No state → no loop continuity.
 ## Invocation
 
 ```
-/ratchet-evolve <target> --goal "<improvement>" [--iterations 2] [--test "<cmd>"] [--mode code|prompt|docs|workflow|auto] [--write]
+/ratchet:evolve <target> --goal "<improvement>" [--iterations 2] [--test "<cmd>"] [--mode code|prompt|docs|workflow|auto] [--write]
 ```
 
 Parse from `$ARGUMENTS`: the target artifact, the `--goal`, `--iterations` (default **2**),
@@ -114,7 +114,13 @@ ratchet-evolve log append '{"target":"...","goal":"...","iteration":1,"pressure"
 Appends to `<project>/.ratchet/evolve-log.jsonl`.
 
 ### 10. NEXT EDGE
-Name the next mutation: small, specific, testable, attached to the **same** artifact.
+Name the next mutation: small, specific, testable, attached to the **same** artifact. It is
+persisted with the event and readable next session via `ratchet-evolve next`. Check
+`ratchet-evolve status` for the running kept/reverted/asked tally.
+
+Copy-paste shapes live in `templates/`: `evolve-event.json` (the log-append payload),
+`evolve-manual-checks.md` (manual evidence when there is no test command), and
+`evolve-report.md` (the output contract below).
 
 ## Stop rules