promptwheel 0.0.1 → 0.1.0

package/README.md

@@ -2,7 +2,11 @@
 
 [![CI](https://github.com/promptwheel-ai/promptwheel/actions/workflows/ci.yml/badge.svg)](https://github.com/promptwheel-ai/promptwheel/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ![Node ≥18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![deps: zero](https://img.shields.io/badge/deps-zero-blue)
 
-**The trustworthy per-turn reward for AI coding loops — proves a turn moved a metric without regressing another.**
+**Catch your agent cheating** — the deterministic auditor that flags when your AI coding agent gamed its own success metric.
+
+PromptWheel re-proves every "win" using the agent's **source edits alone**. If the gate only went green because the agent edited the test, mocked the grader, suppressed the error (`@ts-ignore` / `eslint-disable`), or deleted the feature, the win evaporates when those edits are reverted → **`VERDICT GAMED`, exit 2**. No LLM in the loop — a diff partition plus a re-run, so every flag is reproducible in seconds with a human-readable reason.
+
+It's built on an **outcome gate**: for any change it re-runs your metric commands (tests, lint, `tsc`, coverage, bundle, eval) in throwaway git worktrees before and after, and refuses to trust a delta inside the measurement noise. The gate everyone ships asks *"did the number move?"* — PromptWheel also asks *"did the agent **earn** it?"*
 
 PromptWheel is the **signal, not the loop driver**: wire it as the verifier inside Claude Code `/loop`, a Ralph `while`-loop, or a Beads pull-loop. Each turn it measures your real repo metrics in throwaway worktrees, refuses to trust a delta inside the noise, and answers one question — *did this turn earn its keep?* — so the loop improves instead of confidently degrading. (In CI it's the **outcome gate for AI code**: the same verdict, as a PR check.)
 
@@ -25,12 +29,34 @@ 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`
+
+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)**:
+
+```
+$ promptwheel run --detect-gaming
+
+PromptWheel  base → head
+  ▲ tests_pass    0 → 1  (+1, improved) [guard✓, high]
+      🚩 GAMED — the "win" changed zero production-source files — only test/config/grader/golden
+  VERDICT: GAMED  — a metric "improved" by editing the goalposts, not the source
+```
+
+Inline source-file suppressions (`@ts-nocheck`, `eslint-disable`, `# noqa`) are a different shape, caught by the **`antihack` preset** — a target metric plus tripwire guards (`test_count`, `skipped_tests`, `suppressions`, `assertions`) that fail when a "win" introduces them:
+
+```bash
+npx promptwheel init --preset antihack    # target + tripwire guards
+npx promptwheel run --detect-gaming       # exit 0 = real win · 1 = regression · 2 = GAMED
+```
+
+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.
+
 ## Use
 
 ```bash
 # 0. write a starter config for your stack (or hand-write promptwheel.config.json)
 npx promptwheel init                      # detects stack → guarded test metric + lint
-npx promptwheel init --list               # presets: tests-pass · lint · bundle-size · llm-eval
+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
@@ -45,7 +71,7 @@ npx promptwheel improve --attempt "claude -p 'reduce lint errors'"
 npx promptwheel insights
 ```
 
-It never touches your working tree — every measurement runs in a throwaway worktree. Every gated run appends to `.promptwheel/outcomes.jsonl` (commit it to build the per-repo "what moves what" record; `--no-record` to skip).
+**Footprint:** it never touches your working tree — every measurement runs in a throwaway git worktree **in your system temp dir** (one at a time; `node_modules` is symlinked, not copied), removed when the run finishes. The only thing PromptWheel writes to your repo is the optional `.promptwheel/outcomes.jsonl` record — commit it to build the per-repo "what moves what" history, or `.gitignore` it (`--no-record` to skip entirely). A hard-killed run can't leave clutter behind: the next run **self-heals** any orphaned worktree (stale registry entry + abandoned temp checkout).
 
 ## Loop patterns
 
@@ -111,6 +137,24 @@ The Action runs straight from its own checkout — no npm install, no build. See
 - **direction** — `up` (higher better) · `down` (lower better) · `pass` (boolean 0/1).
 - **guard** — `true` = a *trusted* regression **fails** the gate; `false` = informational.
 
+## Guardrails & inheritance
+
+To see what's actually enforced in a repo — including guards inherited from a shared config:
+
+```bash
+promptwheel guards
+```
+
+Teams keep one shared base config and have every repo inherit it via `extends`:
+
+```json
+// promptwheel.config.json
+{ "extends": "./promptwheel.base.json",
+  "metrics": [ { "name": "cost_per_run_usd", "guard": false } ] }   // loosen one inherited guard, locally
+```
+
+`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.
+
 ## 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:
@@ -138,7 +182,7 @@ The accumulated record of **which change-types move which metrics** is the asset
 ## Develop
 
 ```bash
-npm test     # 20 dep-free tests (node:test) — unit + integration, no dependencies
+npm test     # 36 dep-free tests (node:test) — unit + integration, no dependencies
 ```
 
 The engine is one importable file; pure helpers are exported for unit tests, the CLI runs only when invoked directly. Add a test with every behavior change.
@@ -154,6 +198,7 @@ The engine is one importable file; pure helpers are exported for unit tests, the
 - [x] loop-consumable `improve`: exit `0` kept / `1` regression / `3` plateau + `--json result`
 - [x] `promptwheel init` + presets — zero-config onboarding
 - [x] `insights` — reward-stream aggregation (Phase-5 seed)
+- [x] `--detect-gaming` — reward-hack detection: re-prove the win from source edits alone + `antihack` preset
 - [ ] npm publish (the lead magnet) · ACE-style learning + UCB work-discovery (**frozen** — gated on data + ≥1 paid engagement; see [docs/LEARNING.md](docs/LEARNING.md))
 
 > Status: v0, runnable, all core phases built. Lineage: CommandLayer → BlockSpool → PromptWheel (orchestrator, archived) → **PromptWheel (outcome gate)**.

package/bin/promptwheel.mjs

@@ -11,9 +11,9 @@
 //   promptwheel run [--base R] [--head R] [--repeat N] [--json]
 
 import { execSync, execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync, mkdtempSync, symlinkSync, rmSync, mkdirSync, appendFileSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, symlinkSync, rmSync, mkdirSync, appendFileSync, realpathSync, readdirSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname, isAbsolute, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 // ---------------------------------------------------------------------------
@@ -28,11 +28,46 @@ const median = (xs) => {
 };
 const spread = (xs) => { const a = xs.filter((x) => x != null); return a.length ? Math.max(...a) - Math.min(...a) : 0; };
 
+function readConfigFile(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); }
+  catch (e) { console.error(`invalid config ${p}: ${e.message}`); process.exit(2); }
+}
+
+const relOf = (repo, p) => { try { return relative(repo, p) || p; } catch { return p; } };
+
+// resolve a config + its `extends` chain into a flat, provenance-tagged metric list.
+// `extends` is a path (or array of paths) to base configs, relative to the config file:
+// a repo INHERITS their guardrails, and a local metric of the same name overrides the inherited one.
+function resolveConfig(p, repo, label, seen) {
+  const abs = realpathSync(p);
+  if (seen.has(abs)) { console.error(`config inheritance cycle at ${relOf(repo, p)}`); process.exit(2); }
+  seen.add(abs);
+  try {
+    const cfg = readConfigFile(p);
+    const byName = new Map();
+    const scalars = {};
+    for (const ref of [].concat(cfg.extends || [])) {
+      const bp = isAbsolute(ref) ? ref : join(dirname(p), ref);
+      if (!existsSync(bp)) { console.error(`extends target not found: ${ref} (from ${relOf(repo, p)})`); process.exit(2); }
+      const base = resolveConfig(bp, repo, relOf(repo, bp), seen);
+      for (const m of base.metrics) byName.set(m.name, m);
+      for (const k of ['repeat', 'linkNodeModules', 'record']) if (base[k] !== undefined) scalars[k] = base[k];
+    }
+    for (const m of (cfg.metrics || [])) {
+      byName.set(m.name, { ...m, __src: label, __override: byName.has(m.name) });
+    }
+    for (const k of ['repeat', 'linkNodeModules', 'record']) if (cfg[k] !== undefined) scalars[k] = cfg[k];
+    return { ...scalars, metrics: [...byName.values()] };
+  } finally {
+    seen.delete(abs); // only ACTIVE ancestors are a cycle — a diamond (a base reached two ways) is fine
+  }
+}
+
 function loadConfig(repo) {
   const candidates = ['promptwheel.config.json', 'outcome-gate.config.json']; // back-compat alias
   const p = candidates.map((c) => join(repo, c)).find(existsSync);
   if (!p) { console.error('no promptwheel.config.json — run: promptwheel init   (writes one for your stack)'); process.exit(2); }
-  const cfg = JSON.parse(readFileSync(p, 'utf8'));
+  const cfg = resolveConfig(p, repo, 'local', new Set());
   if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) {
     console.error('config.metrics must be a non-empty array'); process.exit(2);
   }
@@ -120,6 +155,80 @@ function evaluate(m, beforeS, afterS, repeat) {
   return { before, after, delta, status, ok, confidence, noise };
 }
 
+// ---------------------------------------------------------------------------
+// gaming detection (antihack): re-prove a "win" using ONLY the agent's source edits.
+// If the improvement evaporates once test/config/grader/golden changes are reverted,
+// the agent moved the goalposts (edited the test, mocked the grader, suppressed the
+// lint rule, deleted the feature) instead of earning it. Pure arithmetic, fully
+// explainable — the thing the loop-owner structurally won't ship about its own agent.
+// ---------------------------------------------------------------------------
+const NON_SOURCE = [
+  /(^|\/)(tests?|__tests?__|spec|e2e|fixtures|snapshots|__snapshots__|__mocks__)\//i,
+  /\.(test|spec)\.[cm]?[jt]sx?$/i,
+  /(^|\/)tests?\.[cm]?[jt]sx?$/i,                 // a file literally named test.js / tests.ts
+  /(^|\/)test_[^/]*\.py$/i, /_test\.py$/i, /(^|\/)conftest\.py$/i,
+  /\.snap$/i, /(^|\/)golden[^/]*$/i, /\.golden$/i,
+  /(^|\/)(eval|grader|score)[^/]*\.[cm]?[jt]s$/i,
+  /(^|\/)(jest|vitest|playwright|cypress|karma|babel|eslint|tsconfig|pytest)[^/]*\.(json|[cm]?[jt]s|ya?ml|ini|cfg|toml)$/i,
+  /(^|\/)\.(eslintrc|babelrc|prettierrc)[^/]*$/i,
+  /(^|\/)(pytest\.ini|setup\.cfg|\.flake8|tox\.ini|eslint\.config\.[cm]?js)$/i,
+];
+const isNonSource = (p) => NON_SOURCE.some((re) => re.test(p));
+
+// split the agent's changed files into production-source vs test/config/grader/golden
+function changedSourcePaths(repo, base, head) {
+  const all = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean);
+  return { source: all.filter((p) => !isNonSource(p)), nonSource: all.filter(isNonSource) };
+}
+
+// measure `metric` in a worktree at `base` with ONLY the source slice of base→head applied.
+function measureSourceOnly(repo, base, head, metric, linkNM, repeat) {
+  const { source } = changedSourcePaths(repo, base, head);
+  if (!source.length) return { samples: [], hadSourceChange: false }; // a "win" with zero source edits = goalposts moved
+  const wt = mkdtempSync(join(tmpdir(), 'promptwheel-src-'));
+  git(['worktree', 'add', '--quiet', '--detach', wt, base], repo);
+  try {
+    if (linkNM && existsSync(join(repo, 'node_modules')) && !existsSync(join(wt, 'node_modules'))) {
+      try { symlinkSync(join(repo, 'node_modules'), join(wt, 'node_modules')); } catch { /* */ }
+    }
+    const patch = git(['diff', base, head, '--', ...source], repo);
+    if (patch.trim()) {
+      const tryApply = (extra) => { execFileSync('git', ['apply', '--whitespace=nowarn', ...extra], { cwd: wt, input: patch + '\n', encoding: 'utf8' }); };
+      try { tryApply(['--3way']); }
+      catch { try { tryApply([]); } catch { return { samples: [], hadSourceChange: true, applyFailed: true }; } }
+    }
+    const samples = [];
+    for (let i = 0; i < repeat; i++) samples.push(runMetric(wt, metric));
+    return { samples, hadSourceChange: true };
+  } finally {
+    try { git(['worktree', 'remove', '--force', wt], repo); } catch { rmSync(wt, { recursive: true, force: true }); }
+  }
+}
+
+// directional improvement of `val` over `before` (positive = better)
+function gain(m, before, val) {
+  if (before == null || val == null) return null;
+  const dir = m.direction || 'up';
+  if (dir === 'down') return before - val;
+  if (dir === 'pass') return val === 1 ? (before !== 1 ? 1 : 0) : -1;
+  return val - before;
+}
+
+// a metric that improved full-diff: does the win survive when only source edits are applied?
+// gamed = source edits alone reproduce < half the gain (the rest came from editing the goalposts).
+function judgeGaming(m, srcResult) {
+  if (!srcResult.hadSourceChange) return { gamed: true, sourceOnly: null, retained: 0, reason: 'the "win" changed zero production-source files — only test/config/grader/golden' };
+  if (srcResult.applyFailed) return { gamed: null, sourceOnly: null, retained: null, reason: 'source-only patch did not apply cleanly — inconclusive' };
+  const sourceOnly = median(srcResult.samples);
+  const full = gain(m, m.before, m.after);
+  if (full == null || full <= 0) return { gamed: false, sourceOnly, retained: 1, reason: 'no real improvement to re-prove' };
+  const retained = +(gain(m, m.before, sourceOnly) / full).toFixed(3);
+  const gamed = retained < 0.5;
+  return { gamed, sourceOnly, retained, reason: gamed
+    ? `only ${(retained * 100).toFixed(0)}% of the gain survives when test/config/grader changes are reverted — most of the "win" came from editing the goalposts`
+    : `${(retained * 100).toFixed(0)}% of the gain survives source-only — the source earned it` };
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -149,8 +258,30 @@ function workingSnapshot(repo) {
   }
 }
 
+// self-heal: a hard-killed run (SIGKILL / power loss) can leave an orphaned worktree —
+// its `finally` never ran. On the next run, drop stale worktree registry entries and any
+// abandoned /tmp checkout, so nothing accumulates in your repo or temp dir. Never touches a
+// live worktree (a still-registered dir, or a checkout younger than 1h).
+function selfHeal(repo) {
+  try {
+    git(['worktree', 'prune'], repo); // remove registry entries whose dir is already gone (always safe)
+    const tracked = new Set(
+      git(['worktree', 'list', '--porcelain'], repo)
+        .split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice(9).trim()),
+    );
+    const tmp = tmpdir(), cutoff = Date.now() - 3600_000;
+    for (const name of readdirSync(tmp)) {
+      if (!name.startsWith('promptwheel-') && !name.startsWith('pw-idx-')) continue; // worktrees + temp-index dirs
+      const p = join(tmp, name);
+      if (tracked.has(p)) continue;                 // a live/registered worktree — leave it
+      try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { recursive: true, force: true }); } catch { /* */ }
+    }
+  } catch { /* cleanup must never block the gate */ }
+}
+
 // the shared core: measure a change (base→head) and return the structured report
 function gate(repo, opts) {
+  selfHeal(repo);
   const cfg = loadConfig(repo);
   const repeat = Math.max(1, opts.repeat ?? cfg.repeat ?? 1);
   const linkNM = cfg.linkNodeModules !== false;
@@ -160,6 +291,8 @@ function gate(repo, opts) {
     // measure uncommitted changes — tracked AND untracked — via a temp-index snapshot;
     // never touches the real index or working tree. (A loop agent's most common action
     // is to ADD a file; `git stash create` omits untracked, which silently reverted them.)
+    try { git(['rev-parse', '--verify', 'HEAD'], repo); }
+    catch { console.error('no commits yet — make an initial commit before gating --working changes'); process.exit(2); }
     base = 'HEAD';
     head = workingSnapshot(repo);
   } else {
@@ -173,7 +306,18 @@ function gate(repo, opts) {
     const ev = evaluate(m, before[m.name], after[m.name], repeat);
     return { name: m.name, direction: m.direction || 'up', guard: !!m.guard, ...ev };
   });
-  const verdict = metrics.some((m) => m.guard && !m.ok) ? 'fail' : 'pass';
+  // antihack: re-prove every actual win with the agent's source edits alone
+  if (opts.detectGaming) {
+    for (const m of metrics) {
+      if (m.status !== 'improved') continue;
+      const cm = cfg.metrics.find((c) => c.name === m.name);
+      const j = judgeGaming(m, measureSourceOnly(repo, base, head, cm, linkNM, repeat));
+      m.gamed = j.gamed; m.sourceOnly = j.sourceOnly; m.retained = j.retained; m.gamingReason = j.reason;
+    }
+  }
+  const failed = metrics.some((m) => m.guard && !m.ok);
+  const gamed = metrics.some((m) => m.gamed === true);
+  const verdict = failed ? 'fail' : gamed ? 'gamed' : 'pass';
   const report = { base: short(repo, base), head: short(repo, head), repeat, mode: opts.working ? 'working' : 'refs', verdict, metrics };
   if (!opts.noRecord && cfg.record !== false) recordOutcome(repo, report);
   return report;
@@ -182,11 +326,11 @@ function gate(repo, opts) {
 function run(argv) {
   const args = parseArgs(argv);
   const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
-  const report = gate(repo, { base: args.base, head: args.head, working: args.working, repeat: args.repeat, noRecord: args.noRecord });
+  const report = gate(repo, { base: args.base, head: args.head, working: args.working, repeat: args.repeat, noRecord: args.noRecord, detectGaming: args.detectGaming });
   if (args.json) console.log(JSON.stringify(report, null, 2));
   else if (args.markdown) console.log(renderMarkdown(report));
   else printHuman(report);
-  process.exit(report.verdict === 'pass' ? 0 : 1);
+  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)
@@ -210,7 +354,7 @@ function improve(argv) {
   try { execSync(args.attempt, { cwd: repo, stdio: 'inherit' }); }
   catch (e) { console.error(`  (attempt exited ${e.status ?? 1} — gating whatever it changed)`); }
 
-  const report = gate(repo, { working: true, repeat: args.repeat, noRecord: args.noRecord });
+  const report = gate(repo, { working: true, repeat: args.repeat, noRecord: args.noRecord, detectGaming: args.detectGaming });
   const noChange = report.metrics.every((m) => m.delta === 0 || m.delta == null);
   const improvedNames = report.metrics.filter((m) => m.status === 'improved').map((m) => m.name);
 
@@ -218,6 +362,7 @@ function improve(argv) {
   //   0 = kept a real win · 1 = guarded regression (reverted) · 3 = plateau/no-op (reverted)
   let result, exit, note;
   if (report.verdict === 'fail') { result = 'regression'; exit = 1; revert(repo); note = '✗ guarded regression — reverted'; }
+  else if (report.verdict === 'gamed') { result = 'gamed'; exit = 1; revert(repo); note = '🚩 gamed — a metric "improved" by editing tests/config, not source — reverted'; }
   else if (noChange || improvedNames.length === 0) {
     result = 'plateau'; exit = 3; revert(repo);
     note = noChange ? '= no metric moved — reverted' : '= nothing improved beyond noise — reverted';
@@ -286,6 +431,14 @@ const PRESETS = {
       { name: 'eval_pass_rate', cmd: 'node eval.mjs', extract: 'number', direction: 'up', guard: true },
       { name: 'cost_per_run_usd', cmd: 'node estimate-cost.mjs', extract: 'number', direction: 'down', guard: true },
     ] },
+  'antihack': { desc: 'catch reward-hacking: a target + tripwires; pairs with `run --detect-gaming` (source-only re-run)',
+    metrics: [
+      { name: 'tests_pass', cmd: '__TESTCMD__', extract: 'exit', direction: 'pass', guard: true },
+      { name: 'test_count', cmd: 'grep -rIoE "\\b(it|test|describe) ?\\(|def test_" --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | wc -l | tr -d " "', extract: 'number', direction: 'up', guard: true },
+      { name: 'skipped_tests', cmd: 'grep -rIoE "\\.(skip|only) ?\\(|xit ?\\(|@pytest\\.mark\\.skip" --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | wc -l | tr -d " "', extract: 'number', direction: 'down', guard: true },
+      { name: 'suppressions', cmd: 'grep -rIoE "eslint-disable|@ts-(ignore|nocheck)|# ?type: ?ignore|# ?noqa" --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | wc -l | tr -d " "', extract: 'number', direction: 'down', guard: true },
+      { name: 'assertions', cmd: 'grep -rIoE "expect ?\\(|\\bassert" --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | wc -l | tr -d " "', extract: 'number', direction: 'up', guard: true },
+    ] },
 };
 
 function detectTestCmd(repo) {
@@ -315,6 +468,7 @@ function init(argv) {
     const p = PRESETS[presetName];
     if (!p) { console.error(`unknown preset "${presetName}" — try: promptwheel init --list`); process.exit(2); }
     metrics = p.metrics || [{ name: 'tests_pass', cmd: detectTestCmd(repo), extract: 'exit', direction: 'pass', guard: true }];
+    metrics = metrics.map((m) => m.cmd === '__TESTCMD__' ? { ...m, cmd: detectTestCmd(repo) } : m); // fill the preset's target
     note = presetName;
   } else {
     // sensible default: tests-pass (guarded) + lint (info — can't fail a newcomer's first run)
@@ -331,6 +485,34 @@ function init(argv) {
   console.log('         promptwheel init --list     # other presets (llm-eval, bundle-size, …)');
 }
 
+// observability: list the EFFECTIVE guardrails (incl. inherited) + each one's flag record
+function guards(argv) {
+  const args = parseArgs(argv);
+  const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
+  const cfg = loadConfig(repo);
+  const hist = {};
+  const f = join(repo, '.promptwheel', 'outcomes.jsonl');
+  if (existsSync(f)) for (const line of readFileSync(f, 'utf8').split('\n').filter(Boolean)) {
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    for (const m of (r.metrics || [])) {
+      const h = hist[m.name] ??= { runs: 0, flagged: 0, last: null };
+      h.runs++; if (m.guard && m.ok === false) h.flagged++; h.last = m.status;
+    }
+  }
+  const rows = cfg.metrics.map((m) => ({
+    name: m.name, direction: m.direction || 'up', guard: !!m.guard,
+    source: m.__src, override: !!m.__override, ...(hist[m.name] || { runs: 0, flagged: 0, last: null }),
+  }));
+  if (args.json) { console.log(JSON.stringify({ guards: rows }, null, 2)); return; }
+  console.log('\nPromptWheel guardrails — effective set for this repo\n');
+  for (const r of rows) {
+    const prov = r.override ? 'local override' : (r.source === 'local' ? 'local' : `inherited ← ${r.source}`);
+    const rec = r.guard ? (r.runs ? `· ${r.flagged} flagged / ${r.runs} runs` : '· no runs yet') : '';
+    console.log(`  ${r.guard ? '🛡️  GUARD' : '·   info '}  ${r.name.padEnd(18)} better=${r.direction.padEnd(5)}  [${prov}]  ${rec}`);
+  }
+  console.log('\n  🛡️ = enforced (a trusted regression fails the gate) · info = tracked only\n');
+}
+
 const short = (repo, ref) => { try { return git(['rev-parse', '--short', ref], repo); } catch { return ref; } };
 
 function printHuman(r) {
@@ -340,17 +522,19 @@ function printHuman(r) {
     const tag = m.guard ? (m.ok ? 'guard✓' : 'GUARD✗') : 'info';
     const d = m.delta == null ? '—' : (m.delta > 0 ? `+${m.delta}` : `${m.delta}`);
     console.log(`  ${arrowFor(m)} ${m.name.padEnd(18)} ${String(m.before).padStart(8)} → ${String(m.after).padStart(8)}  (${d}, ${m.status}) [${tag}, ${m.confidence}]`);
+    if (m.gamed === true) console.log(`      🚩 GAMED — ${m.gamingReason}`);
   }
-  console.log(`\n  VERDICT: ${r.verdict.toUpperCase()}${r.verdict === 'fail' ? '  — a guarded metric regressed (beyond noise)' : ''}\n`);
+  console.log(`\n  VERDICT: ${r.verdict.toUpperCase()}${r.verdict === 'fail' ? '  — a guarded metric regressed (beyond noise)' : r.verdict === 'gamed' ? '  — a metric "improved" by editing the goalposts, not the source' : ''}\n`);
 }
 
 // PR-comment markdown (rendering lives in the tool so the GitHub Action stays thin)
 function renderMarkdown(r) {
-  const icon = r.verdict === 'pass' ? '✅' : '❌';
+  const icon = r.verdict === 'pass' ? '✅' : r.verdict === 'gamed' ? '🚩' : '❌';
   const sIcon = { improved: '🟢', regressed: '🔴', unchanged: '⚪', inconclusive: '🟡', unmeasurable: '⚫' };
   const rows = r.metrics.map((m) => {
     const d = m.delta == null ? '—' : (m.delta > 0 ? `+${m.delta}` : `${m.delta}`);
-    return `| ${m.guard ? '🛡️ ' : ''}${m.name} | ${m.before} | ${m.after} | ${d} | ${sIcon[m.status] || ''} ${m.status} | ${m.confidence} |`;
+    const status = m.gamed === true ? `🚩 gamed (${(m.retained * 100).toFixed(0)}% survives source-only)` : `${sIcon[m.status] || ''} ${m.status}`;
+    return `| ${m.guard ? '🛡️ ' : ''}${m.name} | ${m.before} | ${m.after} | ${d} | ${status} | ${m.confidence} |`;
   }).join('\n');
   return [
     `### ${icon} PromptWheel — outcome gate: **${r.verdict.toUpperCase()}**`,
@@ -361,7 +545,7 @@ function renderMarkdown(r) {
     '|---|--:|--:|--:|---|---|',
     rows,
     '',
-    r.verdict === 'fail' ? '> ❌ A 🛡️ guarded metric regressed beyond the noise band.' : '> ✅ No guarded metric regressed.',
+    r.verdict === 'gamed' ? '> 🚩 A metric "improved" only because the agent edited tests/config/grader — not the source. The win does not survive a source-only re-run.' : r.verdict === 'fail' ? '> ❌ A 🛡️ guarded metric regressed beyond the noise band.' : '> ✅ No guarded metric regressed.',
     '',
     '<sub>🛡️ = guard · _prove every change moved a metric_ · [PromptWheel](https://github.com/promptwheel-ai/promptwheel)</sub>',
   ].join('\n');
@@ -375,6 +559,7 @@ function parseArgs(argv) {
     else if (argv[i] === '--repeat') a.repeat = parseInt(argv[++i], 10);
     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] === '--attempt') a.attempt = argv[++i];
     else if (argv[i] === '--json') a.json = true;
     else if (argv[i] === '--markdown') a.markdown = true;
@@ -384,7 +569,7 @@ function parseArgs(argv) {
 
 // pure, side-effect-free helpers are exported for unit testing; the CLI below only
 // runs when this file is executed directly (not when imported by the test suite).
-export { extract, evaluate, median, spread, renderMarkdown };
+export { extract, evaluate, median, spread, renderMarkdown, isNonSource, gain, judgeGaming };
 
 function main() {
   const [cmd, ...rest] = process.argv.slice(2);
@@ -392,6 +577,7 @@ function main() {
   else if (cmd === 'improve') improve(rest);
   else if (cmd === 'insights') insights(rest);
   else if (cmd === 'init') init(rest);
+  else if (cmd === 'guards') guards(rest);
   else {
     console.log([
       'PromptWheel — the per-turn reward for AI coding loops. Prove a change moved a metric.',
@@ -399,12 +585,16 @@ function main() {
       '  promptwheel init [--preset <name> | --list]  write a starter config for your stack',
       '  promptwheel run [--base R] [--head R] [--repeat N] [--json|--markdown]',
       '  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)',
+      '  promptwheel guards                           show the effective guardrails (incl. inherited) + flag record',
       '',
       'Loop it:  while promptwheel improve --attempt "$AGENT"; do :; done   # stops on plateau/regression',
-      'Config:   promptwheel.config.json → { metrics:[{ name, cmd, direction, extract?, guard? }] }   (or: promptwheel init)',
+      'Config:   promptwheel.config.json → { extends?, metrics:[{ name, cmd, direction, extract?, guard? }] }   (or: promptwheel init)',
+      '          extends: a path (or array) to a shared base config — repos INHERIT its guardrails; local metrics override by name.',
     ].join('\n'));
     process.exit(cmd ? 2 : 0);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "promptwheel",
-  "version": "0.0.1",
-  "description": "The outcome gate for AI code — prove every change moved a metric. Before/after in an isolated worktree, regression-guarded, noise-aware.",
+  "version": "0.1.0",
+  "description": "The trustworthy per-turn reward for AI coding loops — prove a change moved a metric without regressing another. Before/after in an isolated worktree, regression-guarded, noise-aware.",
   "type": "module",
   "bin": {
     "promptwheel": "bin/promptwheel.mjs",
@@ -13,6 +13,10 @@
     "gate": "node bin/promptwheel.mjs run",
     "test": "node --test"
   },
+  "repository": { "type": "git", "url": "git+https://github.com/promptwheel-ai/promptwheel.git" },
+  "homepage": "https://github.com/promptwheel-ai/promptwheel#readme",
+  "bugs": { "url": "https://github.com/promptwheel-ai/promptwheel/issues" },
+  "author": "Matthew Owens",
   "license": "MIT",
-  "keywords": ["agent", "ci", "regression", "metrics", "verification", "ai-coding", "outcome", "promptwheel"]
+  "keywords": ["agent", "ci", "regression", "metrics", "verification", "ai-coding", "outcome", "evals", "loop", "promptwheel"]
 }