promptwheel 0.1.1 → 0.1.2

package/README.md

@@ -29,12 +29,12 @@ PromptWheel  a1b2c3d → e4f5g6h  (×5)
 
 Exit `0` on pass, `1` on fail (CI-friendly). No build step, zero dependencies, Node 18+.
 
-## Catch your agent cheating — `--detect-gaming`
+## Catch your agent cheating — on by default
 
-The headline feature. After the normal gate, every *win* is re-proven using the agent's source edits **alone**: PromptWheel splits the diff into production source vs. `{test, config, grader, golden}` files, rebuilds a clean worktree at the base with **only the source slice** applied, and re-runs the gate. If the win doesn't survive — because it only passed by skipping/deleting a test, mocking the grader, editing a golden, relaxing a config, or the "win" touched zero source files — the verdict is **`GAMED` (exit 2)**:
+The headline feature, and it runs **by default** (in both `run` and `improve`; pass `--no-detect-gaming` for the bare outcome gate). After the normal gate, every *win* is re-proven using the agent's source edits **alone**: PromptWheel splits the diff into production source vs. `{test, config, grader, golden}` files, rebuilds a clean worktree at the base with **only the source slice** applied, and re-runs the gate. If the win doesn't survive — because it only passed by skipping/deleting a test, mocking the grader, editing a golden, relaxing a config, or the "win" touched zero source files — the verdict is **`GAMED` (exit 2)**:
 
 ```
-$ promptwheel run --detect-gaming
+$ promptwheel run
 
 PromptWheel  base → head
   ▲ tests_pass    0 → 1  (+1, improved) [guard✓, high]
@@ -46,7 +46,8 @@ Inline source-file suppressions (`@ts-nocheck`, `eslint-disable`, `# noqa`) are
 
 ```bash
 npx promptwheel init --preset antihack    # target + tripwire guards
-npx promptwheel run --detect-gaming       # exit 0 = real win · 1 = regression · 2 = GAMED
+npx promptwheel run                       # detection ON by default · exit 0 win · 1 regression · 2 GAMED
+                                          #   (add --no-detect-gaming for just the outcome gate)
 ```
 
 Deterministic, zero-LLM, zero-network: an LLM judge asking "did you cheat?" is itself gameable; this is a diff partition plus a re-run, so a flag is trustworthy without a human in the loop. The 50%-of-gain-survives threshold is the default and is tunable.
@@ -61,7 +62,7 @@ npx promptwheel init                      # detects stack → guarded test metri
 npx promptwheel init --list               # presets: tests-pass · lint · bundle-size · llm-eval · antihack
 
 # measure a change
-npx promptwheel run                       # base = merge-base with main, head = HEAD
+npx promptwheel run                       # base = merge-base with main, head = HEAD · reward-hack detection ON
 npx promptwheel run --working             # measure UNCOMMITTED changes (incl. newly added files)
 npx promptwheel run --repeat 5 --json     # measure 5× to establish a noise band, emit JSON
 
@@ -89,6 +90,8 @@ npx promptwheel run --working --json    # branch on .verdict / per-metric .statu
 
 The exit code is the contract — `0` kept · `1` regression · `3` plateau — so any driver (`/loop`, a Ralph `while`, a Beads pull-loop) converges without parsing anything. PromptWheel never drives the loop; it only says whether the turn counted.
 
+**Two callers, by design.** Your *agent* consumes the verdict — it's the loop's per-turn reward (`improve` / `run --working --json`; exit `0` kept · `1`/`2` reverted · `3` plateau). The *harness* (a Stop-hook or CI) runs `--detect-gaming` — the audit the agent **can't self-clear**, because a contestant can't referee itself (see [docs/ENFORCEMENT.md](docs/ENFORCEMENT.md)). Same tool; *who calls it* is the difference between a reward and an audit.
+
 ## In Claude Code — plugin
 
 Bring the gate into Claude Code as slash commands:
@@ -158,6 +161,8 @@ Teams keep one shared base config and have every repo inherit it via `extends`:
 
 `extends` takes a path (or array of paths) to base configs: a repo **inherits** their guardrails, and a local metric of the same name **overrides** the inherited one (tighten, loosen, or disable). `promptwheel guards` shows the effective set with provenance — `inherited ← base.json`, `local`, or `local override` — plus each guard's flag record from the outcome stream.
 
+Read this way, `extends` is **the shared invariants — the "business rules" — your agents inherit and are held to**: enforced as *measured guards* (a trusted regression fails the gate / reverts the commit), not advisory text an agent can quietly ignore. (Natural-language conventions belong in `AGENTS.md`; only deterministic, measurable guards belong here.)
+
 ## Trust model — the point of the whole thing
 
 A number that jumps around between runs is worthless as a signal. PromptWheel won't pretend otherwise:

package/bin/promptwheel.mjs

@@ -334,7 +334,7 @@ function run(argv) {
   process.exit(report.verdict === 'pass' ? 0 : report.verdict === 'gamed' ? 2 : 1);
 }
 
-// the moat: append every gated run to a per-repo outcome record (best-effort, never fails the gate)
+// persisted record: append every gated run to a per-repo outcome record (best-effort, never fails the gate)
 function recordOutcome(repo, report) {
   try {
     const dir = join(repo, '.promptwheel');
@@ -343,7 +343,7 @@ function recordOutcome(repo, report) {
   } catch { /* recording must never break the gate */ }
 }
 
-// the flywheel: run any agent/script, gate the result, keep the change ONLY if a metric improved
+// keep-if-improved: run any agent/script, gate the result, keep the change ONLY if a metric improved
 function improve(argv) {
   const args = parseArgs(argv);
   if (!args.attempt) { console.error('improve requires --attempt "<command that changes the repo>"'); process.exit(2); }
@@ -553,7 +553,7 @@ function renderMarkdown(r) {
 }
 
 function parseArgs(argv) {
-  const a = { json: false };
+  const a = { json: false, detectGaming: true };   // reward-hack detection is ON by default; --no-detect-gaming opts out
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--base') a.base = argv[++i];
     else if (argv[i] === '--head') a.head = argv[++i];
@@ -561,6 +561,7 @@ function parseArgs(argv) {
     else if (argv[i] === '--working') a.working = true;
     else if (argv[i] === '--no-record') a.noRecord = true;
     else if (argv[i] === '--detect-gaming' || argv[i] === '--antihack') a.detectGaming = true;
+    else if (argv[i] === '--no-detect-gaming' || argv[i] === '--no-antihack') a.detectGaming = false;
     else if (argv[i] === '--attempt') a.attempt = argv[++i];
     else if (argv[i] === '--json') a.json = true;
     else if (argv[i] === '--markdown') a.markdown = true;
@@ -581,13 +582,13 @@ function main() {
   else if (cmd === 'guards') guards(rest);
   else {
     console.log([
-      'PromptWheel — the per-turn reward for AI coding loops. Prove a change moved a metric.',
+      'PromptWheel — catch your agent cheating. Prove a change moved a real metric (and that the agent earned it, not gamed it). The per-turn reward + source-only audit for AI coding loops.',
       '',
       '  promptwheel init [--preset <name> | --list]  write a starter config for your stack',
       '  promptwheel run [--base R] [--head R] [--repeat N] [--json|--markdown]',
+      '       catches reward-hacking BY DEFAULT — re-proves each win from SOURCE edits alone (verdict GAMED,',
+      '       exit 2, when a metric only moved by editing tests/config/grader). Use --no-detect-gaming for the bare gate.',
       '  promptwheel run --working                    gate uncommitted changes (incl. newly added files)',
-      '  promptwheel run --detect-gaming              re-prove each win with SOURCE edits alone — catch reward-hacking',
-      '                                               (verdict GAMED, exit 2, when a metric only moved by editing tests/config/grader)',
       '  promptwheel improve --attempt "<cmd>"        run an agent/script; keep only if a metric improved',
       '                                               exit 0=kept · 1=regression · 3=plateau · add --json',
       '  promptwheel insights                         which metrics actually respond (loop memory)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptwheel",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Catch your agent cheating — a deterministic, zero-LLM CLI that flags when an AI coding agent gamed its own metric (re-proves the win from the agent's source edits alone). Built on an outcome gate; runs in CI or a Claude Code hook.",
   "type": "module",
   "bin": {