promptwheel 0.7.3 → 0.7.5

package/bin/promptwheel.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-// PromptWheel, the per-turn reward for AI coding loops (a.k.a. the outcome gate for AI code).
+// PromptWheel: a deterministic, zero-LLM check for your coding loop. It proves every change
+// earned its win by re-running the result from the agent's source edits alone, so a green
+// that came from editing the test reads GAMED.
 //
-// For any change (base ref → head ref), measure each configured metric in an
+// For any change (base ref -> head ref), measure each configured metric in an
 // isolated git worktree BEFORE and AFTER, enforce regression guards, and refuse
 // to trust a delta that sits inside the measurement noise band. Emits a
 // structured {verdict, metric, delta, confidence}. The thing base agents don't do:
@@ -29,9 +31,14 @@ const median = (xs) => {
 };
 const spread = (xs) => { const a = xs.filter((x) => x != null); return a.length ? Math.max(...a) - Math.min(...a) : 0; };
 
+// usage / config errors exit 64 (EX_USAGE), so they can never be confused with a verdict
+// (0 pass, 1 fail, 2 gamed, 3 inconclusive): in CI a config typo must not read as GAMED.
+const EX_USAGE = 64;
+function die(msg) { console.error(msg); process.exit(EX_USAGE); }
+
 function readConfigFile(p) {
   try { return JSON.parse(readFileSync(p, 'utf8')); }
-  catch (e) { console.error(`invalid config ${p}: ${e.message}`); process.exit(2); }
+  catch (e) { die(`invalid config ${p}: ${e.message}`); }
 }
 
 const relOf = (repo, p) => { try { return relative(repo, p) || p; } catch { return p; } };
@@ -41,42 +48,42 @@ const relOf = (repo, p) => { try { return relative(repo, p) || p; } catch { retu
 // 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); }
+  if (seen.has(abs)) die(`config inheritance cycle at ${relOf(repo, p)}`);
   seen.add(abs);
   try {
     const cfg = readConfigFile(p);
     const byName = new Map();
+    const mandatesByName = new Map();   // hard rules accumulate down the extends chain (a parent's holds)
     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); }
+      if (!existsSync(bp)) die(`extends target not found: ${ref} (from ${relOf(repo, p)})`);
       const base = resolveConfig(bp, repo, relOf(repo, bp), seen);
       for (const m of base.metrics) byName.set(m.name, m);
+      for (const md of (base.mandates || [])) if (md && md.name) mandatesByName.set(md.name, md);
       for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths']) 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 md of (cfg.mandates || [])) if (md && md.name) mandatesByName.set(md.name, { ...md, __src: label });
     for (const k of ['repeat', 'linkNodeModules', 'linkDirs', 'env', 'setup', 'record', 'gamingThreshold', 'evaluatorPaths']) if (cfg[k] !== undefined) scalars[k] = cfg[k];
-    return { ...scalars, metrics: [...byName.values()] };
+    return { ...scalars, metrics: [...byName.values()], mandates: [...mandatesByName.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 p = join(repo, 'promptwheel.config.json');
+  if (!existsSync(p)) die('no promptwheel.config.json, run: promptwheel init   (writes one for your stack)');
   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);
-  }
+  if (!Array.isArray(cfg.metrics) || cfg.metrics.length === 0) die('config.metrics must be a non-empty array');
   return cfg;
 }
 
 // does the repo have a committed gate config?
-const hasConfigFile = (repo) => ['promptwheel.config.json', 'outcome-gate.config.json'].some((f) => existsSync(join(repo, f)));
+const hasConfigFile = (repo) => existsSync(join(repo, 'promptwheel.config.json'));
 
 // the zero-config default: the gate `init` would write, built in memory from stack detection.
 // It gates the detected test command (gaming detection on) with the stack's env/linkDirs so the
@@ -89,8 +96,13 @@ function autoConfig(repo) {
 
 function resolveBase(repo, base) {
   if (base) return base;
+  const head = git(['rev-parse', 'HEAD'], repo);
   for (const b of ['origin/main', 'origin/master', 'main', 'master']) {
-    try { return git(['merge-base', 'HEAD', b], repo); } catch { /* keep trying */ }
+    let mb = '';
+    try { mb = git(['merge-base', 'HEAD', b], repo); } catch { continue; }
+    // on the trunk itself the merge-base IS HEAD; comparing a commit to itself would be a
+    // trivial PASS that verified nothing, so fall through to the last commit instead.
+    if (mb && mb !== head) return mb;
   }
   return git(['rev-parse', 'HEAD~1'], repo);
 }
@@ -267,6 +279,33 @@ function evaluatorMatcher(cfg) {
   return (p) => res.some((re) => re.test(p));
 }
 
+// mandates: named hard rules that compile to a deterministic gate. A protected-path mandate
+// forbids ANY change to its paths (same glob semantics as evaluatorPaths). A hit fails the gate
+// regardless of metrics and rides at the top of the report; mandates inherit through `extends`,
+// so a parent scope's rule holds for every repo beneath it.
+// The mandates in force are the UNION of the head config's and the base ref's (`baseMandates`,
+// resolved by gateDefAtRef): deleting a mandate in the same change that violates it does not
+// clear it. A mandate removed at head but violated in the diff is reported with `removed: true`.
+// The honest way to retire one is a separate change that only edits the config.
+function checkMandates(repo, base, head, cfg, baseMandates) {
+  const headList = Array.isArray(cfg.mandates) ? cfg.mandates : [];
+  const headNames = new Set(headList.map((m) => m && m.name).filter(Boolean));
+  const removed = (Array.isArray(baseMandates) ? baseMandates : []).filter((m) => m && m.name && !headNames.has(m.name));
+  const mandates = [...headList, ...removed.map((m) => ({ ...m, __removed: true }))];
+  if (!mandates.length) return [];
+  let changed = [];
+  try { changed = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean); } catch { return []; }
+  const out = [];
+  for (const m of mandates) {
+    const pats = (Array.isArray(m.paths) ? m.paths : []).filter((s) => typeof s === 'string' && s.trim());
+    if (!pats.length) continue;
+    const res = pats.map(globToRe);
+    const hit = changed.filter((f) => res.some((re) => re.test(f)));
+    if (hit.length) out.push({ name: String(m.name || 'mandate'), reason: m.reason ? String(m.reason).slice(0, 300) : '', files: hit.slice(0, 20), ...(m.__removed ? { removed: true } : {}) });
+  }
+  return out;
+}
+
 // split the agent's changed files into production-source vs test/config/grader/golden.
 // `isEval` is the repo's opt-in evaluator-path matcher, treated as non-source alongside
 // the built-in classifier, so a cheat that only edits a declared gate file is caught.
@@ -276,18 +315,6 @@ function changedSourcePaths(repo, base, head, isEval = () => false) {
   return { source: all.filter((p) => !nonSrc(p)), nonSource: all.filter(nonSrc) };
 }
 
-// coarse change-location fingerprint for the outcome record: top source dirs of the diff
-function subsystemsOf(repo, base, head, cfg) {
-  try {
-    const counts = {};
-    for (const p of changedSourcePaths(repo, base, head, evaluatorMatcher(cfg)).source) {
-      const d = p.includes('/') ? p.slice(0, p.indexOf('/')) : '(root)';
-      counts[d] = (counts[d] || 0) + 1;
-    }
-    return Object.entries(counts).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([d]) => d);
-  } catch { return []; }
-}
-
 // measure `metric` in a worktree at `base` with ONLY the source slice of base→head applied.
 function measureSourceOnly(repo, base, head, metric, cfg, repeat) {
   const { source } = changedSourcePaths(repo, base, head, evaluatorMatcher(cfg));
@@ -298,7 +325,9 @@ function measureSourceOnly(repo, base, head, metric, cfg, repeat) {
     const env = bridgeEnv(repo, wt, cfg);
     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' }); };
+      // stdio stderr 'ignore': git apply --3way prints "Applied patch ... cleanly" to stderr; that
+      // is noise on an otherwise-quiet run (and corrupts --json for callers that fold in stderr).
+      const tryApply = (extra) => { execFileSync('git', ['apply', '--whitespace=nowarn', ...extra], { cwd: wt, input: patch + '\n', encoding: 'utf8', stdio: ['pipe', 'ignore', 'ignore'] }); };
       try { tryApply(['--3way']); }
       catch { try { tryApply([]); } catch { return { samples: [], hadSourceChange: true, applyFailed: true }; } }
     }
@@ -389,8 +418,9 @@ function selfHeal(repo) {
 // Python editable installs (src-layout `pip install -e .`) can pin imports to the ORIGINAL
 // checkout: the worktree's tests then import your current tree at BOTH refs and every delta
 // reads 0, the gate is structurally blind on that repo shape. Undetectable from the verdict
-// (it looks like "unchanged"), so detect the editable install itself and warn. Verified by a
-// controlled repro (CHANGELOG 0.2.2).
+// (it looks like "unchanged"), so `init` detects the editable install itself and warns once.
+// Verified by a controlled repro (CHANGELOG 0.2.2). Deliberately NOT run by gate(): it spawns
+// python3 with a 5 s timeout and prints, and the library path (check) must do neither.
 function warnEditableInstall(repo) {
   if (!existsSync(join(repo, 'pyproject.toml')) && !existsSync(join(repo, 'setup.py'))) return;
   try {
@@ -403,7 +433,7 @@ function warnEditableInstall(repo) {
       'print("HIT" if hit else "")',
     ].join('\n');
     const out = execFileSync('python3', ['-c', probe, repo], { encoding: 'utf8', timeout: 5000 }).trim();
-    if (out === 'HIT') console.error('⚠ editable install of this repo detected (pip install -e): worktree measurements may import your ORIGINAL checkout, not the measured ref, deltas can read 0. Use a non-editable install in the measuring venv, or put the worktree src on PYTHONPATH.');
+    if (out === 'HIT') console.error('⚠ editable install of this repo detected (pip install -e): worktree measurements could import your ORIGINAL checkout instead of the measured ref, so deltas would read 0. The written config puts the worktree first on PYTHONPATH to counter this; if deltas still read 0, use a non-editable install in the measuring venv.');
   } catch { /* no python / cannot tell, stay quiet */ }
 }
 
@@ -415,10 +445,12 @@ function warnEditableInstall(repo) {
 // that guard WOULD HAVE FAILED at head (a real regression hidden by moving the goalposts).
 const GATE_SCALARS = ['gamingThreshold', 'evaluatorPaths'];
 
-// Resolve the gate definition as of `ref` (metrics + scalars), following `extends` by reading
-// every file from that ref via `git show`. Returns { metrics:Map, scalars } or null when there
-// is no config at `ref` (a gate ADDED in this range is not a weakening). Never exits: any
-// missing/unreadable file or parse error yields null (that branch simply contributes nothing).
+// Resolve the gate definition as of `ref` (metrics + mandates + scalars), following `extends` by
+// reading every file from that ref via `git show`, mirroring resolveConfig (a parent's mandates
+// hold beneath it; a local mandate of the same name overrides). Returns { metrics:Map, scalars }
+// with scalars.mandates, or null when there is no config at `ref` (a gate ADDED in this range is
+// not a weakening). Never exits: any missing/unreadable file or parse error yields null (that
+// branch simply contributes nothing).
 function gateDefAtRef(repo, ref) {
   // quiet: a missing path makes `git show` exit nonzero and print "fatal:" to stderr; swallow it
   const readAt = (p) => { try { return execFileSync('git', ['show', `${ref}:${p}`], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch { return null; } };
@@ -429,20 +461,22 @@ function gateDefAtRef(repo, ref) {
     const raw = readAt(p);
     if (raw == null) return null;
     let cfg; try { cfg = JSON.parse(raw); } catch { return null; }
-    const byName = new Map(); const scalars = {};
+    const byName = new Map(); const mandatesByName = new Map(); const scalars = {};
     for (const ext of [].concat(cfg.extends || [])) {
       if (isAbsolute(ext)) continue;                 // outside the repo, cannot git-show; unchanged anyway
       const base = resolve(join(dirname(p), ext).split('\\').join('/'));
       if (!base) continue;
       for (const m of base.metrics.values()) byName.set(m.name, m);
+      for (const md of base.scalars.mandates) mandatesByName.set(md.name, md);
       for (const k of GATE_SCALARS) if (base.scalars[k] !== undefined) scalars[k] = base.scalars[k];
     }
     for (const m of (cfg.metrics || [])) if (m && m.name) byName.set(m.name, m);
+    for (const md of (cfg.mandates || [])) if (md && md.name) mandatesByName.set(md.name, md);
     for (const k of GATE_SCALARS) if (cfg[k] !== undefined) scalars[k] = cfg[k];
+    scalars.mandates = [...mandatesByName.values()];
     return { metrics: byName, scalars };
   };
-  for (const p of ['promptwheel.config.json', 'outcome-gate.config.json']) { const r = resolve(p); if (r) return r; } // first hit only: no spurious probe of the alias
-  return null;
+  return resolve('promptwheel.config.json');
 }
 
 // an order-independent SHA-256 (truncated) fingerprint of a gate definition, for the audit record
@@ -454,6 +488,7 @@ function gateFingerprint(metricsList, scalars) {
     })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
     gamingThreshold: scalars.gamingThreshold ?? null,
     evaluatorPaths: Array.isArray(scalars.evaluatorPaths) ? [...scalars.evaluatorPaths].sort() : [],
+    mandates: Array.isArray(scalars.mandates) ? scalars.mandates.map((m) => ({ name: String(m.name || ''), paths: [...(Array.isArray(m.paths) ? m.paths : [])].sort() })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) : [],
   };
   return createHash('sha256').update(JSON.stringify(norm)).digest('hex').slice(0, 16);
 }
@@ -512,8 +547,8 @@ function gateWeakenings(baseGate, headMetrics) {
 }
 
 // A declared, auditable override (CONTRACT Section 3). The head commit can acknowledge an
-// intentional test/config/grader change - an edit, a delete, or a new file - or an intentional
-// gate change, with a trailer:   Sawbuck-Allow: <reason>
+// intentional test/config/grader change (an edit, a delete, or a new file) or an intentional
+// gate change, with a trailer:   Promptwheel-Allow: <reason>   (Sawbuck-Allow: is an alias)
 // so a change that would read GAMED reads PASS instead, with the acknowledgment RECORDED in
 // report.allowed. The check does not judge intent; it forces intent to be explicit. An UNdeclared
 // test-only win is still gamed. `--allow "<reason>"` (CLI) / `allow` (check) supplies the same for
@@ -521,13 +556,67 @@ function gateWeakenings(baseGate, headMetrics) {
 function readAllowTrailer(repo, ref) {
   let msg = '';
   try { msg = execFileSync('git', ['log', '-1', '--format=%B', ref], { cwd: repo, encoding: 'utf8' }); } catch { return null; }
-  const m = msg.match(/^[ \t]*(?:Sawbuck-Allow|Allow-Gamed|Promptwheel-Allow)[ \t]*:[ \t]*(\S.*?)[ \t]*$/im);
+  const m = msg.match(/^[ \t]*(?:Promptwheel-Allow|Sawbuck-Allow)[ \t]*:[ \t]*(\S.*?)[ \t]*$/im);
   return m && m[1].trim() ? { reason: m[1].trim().slice(0, 300) } : null;
 }
 
+// The three Section 3 checks, run only with detectGaming, in order: (1) re-prove every actual
+// win with the agent's source edits alone; (2) content-hash auto-fail: a declared evaluatorPath
+// gate file edited in this diff is a moved goalpost, so a metric that improved alongside it is
+// gamed by declaration, deterministic even if the source-only re-run read inert; (3) gate
+// integrity: resolve the gate as of BASE, re-measure any guard HEAD dropped under its base
+// definition (it only counts as tampering if it WOULD HAVE FAILED at head), and fingerprint the
+// gate definition at both refs (metrics, evaluatorPaths, gamingThreshold, mandates) so a quietly
+// deleted guard or mandate is tamper-evident: base != head is recorded as gate.changed and
+// printed, whatever the verdict. Mutates `metrics` in place (gamed/sourceOnly/retained/
+// gamingReason) and returns the report.gate record. An allow trailer can still clear a gamed
+// metric afterwards, in gate().
+function detectGamingPass(repo, base, head, cfg, metrics, repeat) {
+  for (const m of metrics) {
+    if (m.status !== 'improved') continue;
+    const cm = cfg.metrics.find((c) => c.name === m.name);
+    if (cm.gamingCheck === false) continue;   // tripwire / test-side guards aren't re-proven from source (their gain legitimately lives in test files)
+    const j = judgeGaming(m, measureSourceOnly(repo, base, head, cm, cfg, repeat), cm.gamingThreshold ?? cfg.gamingThreshold ?? 0.5);
+    m.gamed = j.gamed; m.sourceOnly = j.sourceOnly; m.retained = j.retained; m.gamingReason = j.reason;
+  }
+  const evalChanged = changedEvaluatorPaths(repo, base, head, cfg);
+  if (evalChanged.length) {
+    for (const m of metrics) {
+      if (m.status !== 'improved' || m.gamed === true) continue;
+      const cm = cfg.metrics.find((c) => c.name === m.name);
+      if (cm && cm.gamingCheck === false) continue; // tripwire/test-side guards legitimately live in gate files
+      m.gamed = true;
+      m.gamingReason = `a declared evaluatorPath gate file changed in this diff (${evalChanged.map((e) => e.path).join(', ')}); a win alongside a goalpost edit is gamed by declaration`;
+    }
+  }
+  const baseGate = gateDefAtRef(repo, base);
+  const weak = gateWeakenings(baseGate, cfg.metrics);
+  const weakened = [];
+  if (weak.length) {
+    const defs = weak.map((w) => w.def);
+    const b = measureAt(repo, base, { ...cfg, metrics: defs }, repeat);
+    const a = measureAt(repo, head, { ...cfg, metrics: defs }, repeat);
+    for (const w of weak) {
+      const ev = evaluate(w.def, b[w.name], a[w.name], repeat);
+      if (!ev.ok) weakened.push({ name: w.name, change: w.change, status: ev.status });
+    }
+  }
+  const fpBase = baseGate ? gateFingerprint([...baseGate.metrics.values()], baseGate.scalars) : null;
+  const fpHead = gateFingerprint(cfg.metrics, cfg);
+  const info = {
+    fingerprint: { base: fpBase, head: fpHead },
+    ...(fpBase && fpBase !== fpHead ? { changed: true } : {}),
+    ...(weakened.length ? { weakened } : {}),
+    ...(evalChanged.length ? { evaluatorChanged: evalChanged } : {}),
+  };
+  // hand the base ref's mandates to gate() (not part of the record) so checkMandates can hold a
+  // change to a mandate it deleted in the same diff.
+  Object.defineProperty(info, 'baseMandates', { value: baseGate ? baseGate.scalars.mandates || [] : null, enumerable: false });
+  return info;
+}
+
 function gate(repo, opts) {
   selfHeal(repo);
-  warnEditableInstall(repo);
   const cfg = opts.config ?? loadConfig(repo);
   const repeat = Math.max(1, opts.repeat ?? cfg.repeat ?? 1);
 
@@ -537,7 +626,7 @@ function gate(repo, opts) {
     // 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); }
+    catch { die('no commits yet, make an initial commit before gating --working changes'); }
     base = 'HEAD';
     head = workingSnapshot(repo);
   } else {
@@ -551,59 +640,9 @@ 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 };
   });
-  // 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);
-      if (cm.gamingCheck === false) continue;   // tripwire / test-side guards aren't re-proven from source (their gain legitimately lives in test files)
-      const j = judgeGaming(m, measureSourceOnly(repo, base, head, cm, cfg, repeat), cm.gamingThreshold ?? cfg.gamingThreshold ?? 0.5);
-      m.gamed = j.gamed; m.sourceOnly = j.sourceOnly; m.retained = j.retained; m.gamingReason = j.reason;
-    }
-  }
-  // content-hash auto-fail (Section 3): a declared evaluatorPath gate file edited in this diff is a
-  // moved goalpost, so a metric that improved alongside it is gamed by declaration - deterministic,
-  // even if the source-only re-run above read inert. An allow-trailer can still clear it, below.
-  let evalChanged = [];
-  if (opts.detectGaming) {
-    evalChanged = changedEvaluatorPaths(repo, base, head, cfg);
-    if (evalChanged.length) {
-      for (const m of metrics) {
-        if (m.status !== 'improved' || m.gamed === true) continue;
-        const cm = cfg.metrics.find((c) => c.name === m.name);
-        if (cm && cm.gamingCheck === false) continue; // tripwire/test-side guards legitimately live in gate files
-        m.gamed = true;
-        m.gamingReason = `a declared evaluatorPath gate file changed in this diff (${evalChanged.map((e) => e.path).join(', ')}); a win alongside a goalpost edit is gamed by declaration`;
-      }
-    }
-  }
-  // gate integrity (Section 3): did HEAD weaken the gate it is judged by? Resolve the gate as
-  // of BASE; a guard HEAD dropped is re-measured under its base definition and only counts as
-  // tampering if it WOULD HAVE FAILED at head (a real regression hidden by dropping the guard).
-  let gateInfo = null;
-  if (opts.detectGaming) {
-    const baseGate = gateDefAtRef(repo, base);
-    const weak = gateWeakenings(baseGate, cfg.metrics);
-    const weakened = [];
-    if (weak.length) {
-      const defs = weak.map((w) => w.def);
-      const b = measureAt(repo, base, { ...cfg, metrics: defs }, repeat);
-      const a = measureAt(repo, head, { ...cfg, metrics: defs }, repeat);
-      for (const w of weak) {
-        const ev = evaluate(w.def, b[w.name], a[w.name], repeat);
-        if (!ev.ok) weakened.push({ name: w.name, change: w.change, status: ev.status });
-      }
-    }
-    gateInfo = {
-      fingerprint: {
-        base: baseGate ? gateFingerprint([...baseGate.metrics.values()], baseGate.scalars) : null,
-        head: gateFingerprint(cfg.metrics, cfg),
-      },
-      ...(weakened.length ? { weakened } : {}),
-      ...(evalChanged.length ? { evaluatorChanged: evalChanged } : {}),
-    };
-  }
-  // declared override: a Sawbuck-Allow trailer (or --allow) acknowledges an intentional
+  // Section 3 (gaming detection), on by default: mutates `metrics` and yields the gate record
+  const gateInfo = opts.detectGaming ? detectGamingPass(repo, base, head, cfg, metrics, repeat) : null;
+  // declared override: a Promptwheel-Allow trailer (or --allow) acknowledges an intentional
   // goalpost/gate change, so a would-be GAMED becomes PASS, recorded in report.allowed for review.
   const allow = opts.allow ? { reason: String(opts.allow).slice(0, 300) } : (opts.working ? null : readAllowTrailer(repo, head));
   let allowed = null;
@@ -616,6 +655,12 @@ function gate(repo, opts) {
       if (gw) gateInfo.allowed = true;
     }
   }
+  // mandates run first: a protected-path hard rule fails the gate no matter what the metrics say.
+  // The base ref's mandates count too (resolved through `extends` by gateDefAtRef), so a change
+  // cannot clear a mandate by deleting it in the same diff that violates it.
+  const baseMandates = (gateInfo && gateInfo.baseMandates) || (!opts.detectGaming ? ((gateDefAtRef(repo, base) || {}).scalars || {}).mandates : null);
+  const mandateViolations = checkMandates(repo, base, head, cfg, baseMandates);
+  const mandated = mandateViolations.length > 0;
   const failed = metrics.some((m) => m.guard && !m.ok);
   const gamed = metrics.some((m) => m.gamed === true) || !!(gateInfo && gateInfo.weakened && !gateInfo.allowed);
   // a guard that never runs (inert: a pass/fail metric stuck at 0 across both refs) verifies
@@ -623,15 +668,11 @@ function gate(repo, opts) {
   // BUT scope it to a bare no-op run: an inert guard must NOT bury a genuine, measured win
   // elsewhere (that would make `improve` revert good changes and misread them as a plateau).
   const inconclusive = !failed && !gamed && metrics.some((m) => m.inert) && !metrics.some((m) => m.status === 'improved');
-  const verdict = failed ? 'fail' : gamed ? 'gamed' : inconclusive ? 'inconclusive' : 'pass';
+  const verdict = (mandated || failed) ? 'fail' : gamed ? 'gamed' : inconclusive ? 'inconclusive' : 'pass';
   const report = {
     base: short(repo, base), head: short(repo, head), repeat, mode: opts.working ? 'working' : 'refs',
-    // learning-substrate fields (Phase 5): cohort segments reliability by environment,
-    // label attributes a change-type, subsystems fingerprint WHERE the change landed.
-    cohort: opts.cohort ?? (process.env.CI ? 'ci' : 'local'),
-    ...(opts.label ? { label: opts.label } : {}),
-    subsystems: subsystemsOf(repo, base, head, cfg),
     verdict, metrics,
+    ...(mandateViolations.length ? { mandates: mandateViolations } : {}),
     ...(gateInfo ? { gate: gateInfo } : {}),
     ...(allowed ? { allowed } : {}),
   };
@@ -655,7 +696,7 @@ function run(argv) {
     config = autoConfig(repo);
     console.error(`no promptwheel.config.json, auto-gating the detected test command: ${config.metrics[0].cmd}  (promptwheel init to customize; --no-auto to require a config)`);
   }
-  const report = gate(repo, { base: args.base, head: args.head, working: args.working, repeat: args.repeat, noRecord: args.noRecord, detectGaming: args.detectGaming, label: args.label, allow: args.allow, config });
+  const report = gate(repo, { base: args.base, head: args.head, working: args.working, repeat: args.repeat, noRecord: args.noRecord, detectGaming: args.detectGaming, allow: args.allow, config });
   if (args.json) console.log(JSON.stringify(report, null, 2));
   else if (args.markdown) console.log(renderMarkdown(report));
   else printHuman(report);
@@ -674,24 +715,25 @@ function recordOutcome(repo, report) {
 // 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); }
+  if (!args.attempt) die('improve requires --attempt "<command that changes the repo>"');
   const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
   const dirty = git(['status', '--porcelain'], repo).split('\n').filter((l) => l.trim() && !l.includes('.promptwheel'));
-  if (dirty.length) { console.error('working tree not clean, commit or stash first (improve needs a clean base to revert to)'); process.exit(2); }
+  if (dirty.length) die('working tree not clean, commit or stash first (improve needs a clean base to revert to)');
 
   console.error(`▶ attempt: ${args.attempt}`);
   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, detectGaming: args.detectGaming, label: args.label ?? args.attempt });
+  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);
 
-  // result + exit code express loop progress so `while improve; do :; done` converges:
-  //   0 = kept a real win · 1 = guarded regression (reverted) · 3 = plateau/no-op OR inconclusive (reverted)
+  // result + exit code express loop progress so `while improve; do :; done` converges, with the
+  // same codes as `run`: 0 = kept a real win · 1 = guarded regression (reverted) · 2 = gamed
+  // (reverted) · 3 = plateau/no-op OR inconclusive (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 (report.verdict === 'gamed') { result = 'gamed'; exit = 2; revert(repo); note = '🚩 gamed, a metric "improved" by editing tests/config, not source, reverted'; }
   else if (report.verdict === 'inconclusive') { result = 'inconclusive'; exit = 3; revert(repo); note = '≈ inconclusive, a guard measured nothing (inert); reverted'; }
   else if (noChange || improvedNames.length === 0) {
     result = 'plateau'; exit = 3; revert(repo);
@@ -717,14 +759,14 @@ function revert(repo) {
   try { git(['clean', '-fd', '-e', '.promptwheel'], repo); } catch { /* best effort */ }
 }
 
-// Phase-5 seed: turn the accumulated reward stream into signal. Thin on purpose, 
-// this is the substrate a future outcome-curated playbook / UCB work-discovery loop trains on,
-// NOT that loop itself. Just honest aggregation, no model.
+// insights: honest aggregation of the per-repo outcome record (.promptwheel/outcomes.jsonl)
+// into per-metric counts. No model, no decay, no claims: just which metrics actually respond.
+// The reader is tolerant of older records that carry extra fields (cohort, label, subsystems).
 function insights(argv) {
   const args = parseArgs(argv);
   const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
   const f = join(repo, '.promptwheel', 'outcomes.jsonl');
-  if (!existsSync(f)) { console.error('no outcome record yet, run the gate a few times first (.promptwheel/outcomes.jsonl)'); process.exit(2); }
+  if (!existsSync(f)) die('no outcome record yet, run the gate a few times first (.promptwheel/outcomes.jsonl)');
   const runs = readFileSync(f, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
   const agg = {};
   for (const r of runs) for (const m of (r.metrics || [])) {
@@ -746,149 +788,6 @@ function insights(argv) {
   console.log('  highest-lever metrics are where an agent loop should spend its attempts.\n');
 }
 
-// ---------------------------------------------------------------------------
-// Phase 5, outcome-curated playbook + UCB work-discovery.
-// Unfrozen 2026-07-02 by explicit founder decision overriding D7 (see docs/LEARNING.md).
-// Design constraints that survive the unfreeze:
-//   - PURE VIEW: the append-only ledger (.promptwheel/outcomes.jsonl) is the only store;
-//     the playbook is re-derived on every read (decay at read time, no curator state to rot).
-//   - EVIDENCE-GATED: a key renders a claim only past MIN_MOVED weighted observations;
-//     everything below that is counted, not asserted.
-//   - CLAIM-GATED: no public compounding claim until bench/compounding-ab.mjs passes on
-//     real usage data. The gate on the CLAIM outlived the gate on the CODE.
-// ---------------------------------------------------------------------------
-const HALF_LIFE = 20;   // runs, an entry's weight halves every HALF_LIFE runs unless re-earned
-const MIN_MOVED = 3;    // weighted moved-observations before a key earns a rendered claim
-const EXPLORE_C = 1.0;  // UCB exploration constant
-
-function readLedger(repo) {
-  const f = join(repo, '.promptwheel', 'outcomes.jsonl');
-  if (!existsSync(f)) return [];
-  return readFileSync(f, 'utf8').split('\n').filter(Boolean)
-    .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-}
-
-// fold the ledger into decayed per-key stats. keys: `metric` · `metric @ subsystem` · `metric # label`
-function foldOutcomes(runs) {
-  const keys = new Map();
-  const N = runs.length;
-  runs.forEach((r, idx) => {
-    const w = Math.pow(0.5, (N - 1 - idx) / HALF_LIFE);   // idx N-1 = newest → weight 1
-    for (const m of (r.metrics || [])) {
-      const tags = [m.name];
-      for (const s of (r.subsystems || [])) tags.push(`${m.name} @ ${s}`);
-      if (r.label) tags.push(`${m.name} # ${r.label}`);
-      for (const key of tags) {
-        const k = keys.get(key) ?? { key, metric: m.name, w: 0, n: 0, imp: 0, reg: 0, moved: 0, effects: [], cohorts: {}, last: null };
-        k.n += 1; k.w += w;
-        const coh = (k.cohorts[r.cohort || 'unknown'] ??= { imp: 0, reg: 0 });
-        if (m.status === 'improved') {
-          k.imp += w; k.moved += w; coh.imp += 1;
-          if (typeof m.delta === 'number' && m.delta !== 0) k.effects.push(Math.abs(m.delta));
-        } else if (m.status === 'regressed') { k.reg += w; k.moved += w; coh.reg += 1; }
-        k.last = r.ts || k.last;
-        keys.set(key, k);
-      }
-    }
-  });
-  return [...keys.values()];
-}
-
-const betaMean = (imp, reg) => (1 + imp) / (2 + imp + reg);   // Beta(1,1)-smoothed helpfulness
-
-// composite lever = smoothed helpfulness × responsiveness; UCB adds an exploration bonus
-function scoreKey(k, totalW) {
-  const p = betaMean(k.imp, k.reg);
-  const move = k.w ? k.moved / k.w : 0;
-  const lever = p * move;
-  const ucb = lever + EXPLORE_C * Math.sqrt(Math.log(Math.max(Math.E, totalW)) / Math.max(1e-6, k.w));
-  return { p: +p.toFixed(3), move: +move.toFixed(3), lever: +lever.toFixed(3), ucb: +ucb.toFixed(3), effect: +(median(k.effects) ?? 0).toFixed(6) };
-}
-
-// cohorts that disagree in sign are flagged, never averaged into a lie
-function cohortNote(k) {
-  const cs = Object.entries(k.cohorts).filter(([, c]) => c.imp + c.reg > 0);
-  if (cs.length < 2) return '';
-  const signs = new Set(cs.map(([, c]) => Math.sign(c.imp - c.reg)));
-  return signs.size > 1 ? ' · ⚠ cohort-dependent (ci vs local disagree)' : '';
-}
-
-function loadEntries(repo) {
-  const runs = readLedger(repo);
-  if (!runs.length) { console.error('no outcome record yet, run the gate a few times first (.promptwheel/outcomes.jsonl)'); process.exit(2); }
-  const keys = foldOutcomes(runs);
-  const totalW = keys.filter((k) => k.key === k.metric).reduce((s, k) => s + k.w, 0);
-  const entries = keys.map((k) => ({ ...k, ...scoreKey(k, totalW), sufficient: k.moved >= MIN_MOVED }))
-    .sort((a, b) => b.lever - a.lever || b.w - a.w);
-  return { runs, entries };
-}
-
-// the distilled, execution-earned context an agent (or CLAUDE.md) can consume
-function playbook(argv) {
-  const args = parseArgs(argv);
-  const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
-  const { runs, entries } = loadEntries(repo);
-  if (args.json) { console.log(JSON.stringify({ runs: runs.length, halfLife: HALF_LIFE, minMoved: MIN_MOVED, entries }, null, 2)); return; }
-  const suff = entries.filter((e) => e.sufficient);
-  const pct = (x) => `${Math.round(x * 100)}%`;
-  const out = [];
-  out.push(`## Earned playbook, ${runs.length} gated runs, decay half-life ${HALF_LIFE} runs`);
-  out.push('*(every line below was measured by the gate, not asserted; entries decay unless re-earned)*', '');
-  if (!suff.length) {
-    out.push(`_Nothing has earned a claim yet, a key needs ≥${MIN_MOVED} weighted moved-observations. Keep gating; ${entries.length} keys are accumulating._`);
-  } else {
-    for (const e of suff.slice(0, 20)) {
-      out.push(`- **${e.key}**, helpful ${pct(e.p)} when it moves (${e.imp.toFixed(1)}✓/${e.reg.toFixed(1)}✗ weighted), responds in ${pct(e.move)} of runs, median effect ${e.effect}${cohortNote(e)}`);
-    }
-    const hidden = entries.length - suff.length;
-    if (hidden > 0) out.push('', `_${hidden} more keys below the evidence threshold, counted, not asserted._`);
-  }
-  console.log(out.join('\n'));
-}
-
-// UCB work-discovery: where should the loop spend its NEXT attempt? Proposes measured
-// targets (metric/subsystem arms), never code advice; the measurement stays the message.
-function suggest(argv) {
-  const args = parseArgs(argv);
-  const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
-  const { runs, entries } = loadEntries(repo);
-  const arms = entries.filter((e) => e.key === e.metric || e.key.includes(' @ ')).sort((a, b) => b.ucb - a.ucb);
-  if (args.json) { console.log(JSON.stringify({ runs: runs.length, thin: runs.length < 10, arms: arms.slice(0, 10) }, null, 2)); return; }
-  console.log(`\nPromptWheel suggest, UCB over ${runs.length} gated runs${runs.length < 10 ? '  (thin record: exploration dominates, treat as a coin with opinions)' : ''}\n`);
-  for (const a of arms.slice(0, 5)) {
-    console.log(`  ${a.ucb.toFixed(3)}  ${a.key.padEnd(28)} lever ${a.lever.toFixed(3)} (helpful ${a.p}, responds ${a.move}) · evidence ${a.moved.toFixed(1)} moved / ${a.n} runs${a.sufficient ? '' : ' · below claim threshold'}`);
-  }
-  console.log('\n  score = lever + exploration bonus, high scores are either proven levers or under-explored arms.\n');
-}
-
-// backfill, seed the ledger from git history: replay past commits through the CURRENT
-// metrics (LEARNING.md harvest path 1). Deterministic, no LLM. Rows are cohort-tagged
-// 'backfill', historical human commits are NOT live agent-loop evidence; the cohort
-// machinery segments them and flags disagreement rather than averaging it away. The
-// conventional-commit type (fix/feat/refactor/…) becomes the change-type label for free.
-function backfill(argv) {
-  const args = parseArgs(argv);
-  const repo = git(['rev-parse', '--show-toplevel'], process.cwd());
-  const listArgs = ['rev-list', '--no-merges'];
-  if (args.since) listArgs.push(`${args.since}..HEAD`); else listArgs.push('-n', String(args.n ?? 30), 'HEAD');
-  const commits = git(listArgs, repo).split('\n').filter(Boolean).reverse(); // oldest first → ledger stays chronological, decay stays honest
-  if (!commits.length) { console.error('no commits to backfill'); process.exit(2); }
-  const seen = new Set(readLedger(repo).filter((r) => r.cohort === 'backfill').map((r) => r.head));
-  let done = 0, skipped = 0;
-  console.log(`\nbackfilling ${commits.length} commits through the current metrics (gaming detection ${args.dgExplicit && args.detectGaming ? 'ON' : 'off, pass --detect-gaming to audit history too'})\n`);
-  for (const c of commits) {
-    try { git(['rev-parse', `${c}~1`], repo); } catch { skipped++; continue; }        // root commit
-    if (seen.has(short(repo, c))) { skipped++; continue; }                            // already recorded
-    const subj = git(['log', '-1', '--format=%s', c], repo);
-    const type = /^(feat|fix|docs|test|chore|refactor|perf|ci|build|style)\b/i.exec(subj)?.[1]?.toLowerCase();
-    const report = gate(repo, { base: `${c}~1`, head: c, repeat: args.repeat, detectGaming: args.dgExplicit ? args.detectGaming : false, label: type, cohort: 'backfill' });
-    console.log(`  ${report.head} ${report.verdict.toUpperCase().padEnd(6)} ${type ? `#${type}`.padEnd(10) : ''.padEnd(10)} ${subj.slice(0, 56)}`);
-    done++;
-  }
-  console.log(`\n  backfilled ${done}${skipped ? ` (skipped ${skipped}: root or already recorded)` : ''}, old commits that no longer build record as unmeasurable, never faked.`);
-  console.log('  next:  promptwheel playbook   ·   promptwheel suggest\n');
-}
-
 // ---------------------------------------------------------------------------
 // init, write a starter config so a newcomer isn't staring at a blank page
 // ---------------------------------------------------------------------------
@@ -993,15 +892,13 @@ function init(argv) {
   }
   const repo = (() => { try { return git(['rev-parse', '--show-toplevel'], process.cwd()); } catch { return process.cwd(); } })();
   const out = join(repo, 'promptwheel.config.json');
-  if (existsSync(out) && !argv.includes('--force')) {
-    console.error('promptwheel.config.json already exists, pass --force to overwrite'); process.exit(2);
-  }
+  if (existsSync(out) && !argv.includes('--force')) die('promptwheel.config.json already exists, pass --force to overwrite');
   const pi = argv.indexOf('--preset');
   const presetName = pi >= 0 ? argv[pi + 1] : null;
   let metrics, note, evaluatorPaths;
   if (presetName) {
     const p = PRESETS[presetName];
-    if (!p) { console.error(`unknown preset "${presetName}", try: promptwheel init --list`); process.exit(2); }
+    if (!p) die(`unknown preset "${presetName}", try: promptwheel init --list`);
     evaluatorPaths = p.evaluatorPaths;   // a preset may ship a starter evaluator allowlist (e.g. security-antihack)
     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
@@ -1034,6 +931,7 @@ function init(argv) {
   if (envCfg.linkDirs) note += ` · linking ${envCfg.linkDirs.join(', ')}`;
   writeFileSync(out, JSON.stringify({ repeat: 1, ...envCfg, ...(evaluatorPaths ? { evaluatorPaths } : {}), metrics }, null, 2) + '\n');
   console.log(`✓ wrote promptwheel.config.json, ${note}`);
+  warnEditableInstall(repo);   // one-time advice at setup, never on the per-turn path
   if (!argv.includes('--no-agent-block')) {
     const wrote = writeAgentBlock(repo);
     if (wrote.length) console.log(`✓ wrote the agent guide (when to run the gate) to ${wrote.join(', ')}`);
@@ -1095,6 +993,7 @@ const short = (repo, ref) => { try { return git(['rev-parse', '--short', ref], r
 function printHuman(r) {
   const arrowFor = (m) => (m.delta == null ? '?' : m.delta > 0 ? '▲' : m.delta < 0 ? '▼' : '=');
   console.log(`\nPromptWheel  ${r.base} → ${r.head}${r.repeat > 1 ? `  (×${r.repeat})` : ''}\n`);
+  if (r.mandates) for (const md of r.mandates) console.log(`  ⛔ MANDATE "${md.name}" violated${md.reason ? ': ' + md.reason : ''}  (touched: ${md.files.join(', ')})${md.removed ? '  [deleted in this same change; a mandate stays in force for the change that removes it]' : ''}`);
   for (const m of r.metrics) {
     const tag = m.guard ? (m.ok ? 'guard✓' : 'GUARD✗') : 'info';
     const d = m.delta == null ? 'n/a' : (m.delta > 0 ? `+${m.delta}` : `${m.delta}`);
@@ -1103,9 +1002,12 @@ function printHuman(r) {
     if (m.gamed === true) console.log(`      🚩 GAMED, ${m.gamingReason}`);
   }
   if (r.gate && r.gate.weakened) for (const w of r.gate.weakened) console.log(`  🚩 GATE WEAKENED, the guard "${w.name}" was ${w.change === 'guard-removed' ? 'removed' : 'disabled'} in this change and it would have ${w.status} at head (goalpost moved, not earned)`);
-  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' : r.verdict === 'inconclusive' ? ', a guard is inert (measured nothing); a pass cannot be certified' : ''}`);
-  if (r.verdict === 'fail') console.log('  intentional? loosen that guard locally in promptwheel.config.json (guard:false, or override the inherited metric by name), `promptwheel guards` shows the effective set');
-  if (r.allowed) console.log(`  ✓ allowed: ${r.allowed.cleared.join(', ')} acknowledged as an intentional change, recorded (Sawbuck-Allow: ${r.allowed.reason})`);
+  if (r.gate && r.gate.changed) console.log(`  ⚠ gate definition changed in this change (fingerprint ${r.gate.fingerprint.base} -> ${r.gate.fingerprint.head}): a metric, guard, evaluatorPath or mandate was added, removed or edited; review promptwheel.config.json as part of the diff`);
+  const failReason = r.mandates ? ', a mandate was violated (a protected path changed)' : ', a guarded metric regressed (beyond noise)';
+  console.log(`\n  VERDICT: ${r.verdict.toUpperCase()}${r.verdict === 'fail' ? failReason : r.verdict === 'gamed' ? ', a metric "improved" by editing the goalposts, not the source' : r.verdict === 'inconclusive' ? ', a guard is inert (measured nothing); a pass cannot be certified' : ''}`);
+  if (r.verdict === 'fail' && r.mandates) console.log('  a mandate is a hard rule; if the change is truly intended, edit the mandate in promptwheel.config.json (a tracked, tamper-evident change), do not work around it');
+  else if (r.verdict === 'fail') console.log('  intentional? loosen that guard locally in promptwheel.config.json (guard:false, or override the inherited metric by name), `promptwheel guards` shows the effective set');
+  if (r.allowed) console.log(`  ✓ allowed: ${r.allowed.cleared.join(', ')} acknowledged as an intentional change, recorded (Promptwheel-Allow: ${r.allowed.reason})`);
   console.log('');
 }
 
@@ -1123,12 +1025,14 @@ function renderMarkdown(r) {
     '',
     `\`${r.base} → ${r.head}\` · ${r.mode} mode${r.repeat > 1 ? ` · ×${r.repeat}` : ''}`,
     '',
+    ...(r.mandates ? [r.mandates.map((md) => `> ⛔ **Mandate violated:** \`${md.name}\`${md.reason ? ': ' + md.reason : ''} (touched \`${md.files.join('`, `')}\`)${md.removed ? ' (deleted in this same change; it stays in force for the change that removes it)' : ''}`).join('\n'), ''] : []),
     '| metric | before | after | Δ | status | confidence |',
     '|---|--:|--:|--:|---|---|',
     rows,
     '',
-    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.' : r.verdict === 'inconclusive' ? '> 🟡 A 🛡️ guarded check is **inert**, it never runs, so nothing was actually verified. Fix its command before trusting a pass.' : '> ✅ 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' ? (r.mandates ? '> ⛔ A mandate was violated: a protected path changed. This is a hard rule, enforced before any metric.' : '> ❌ A 🛡️ guarded metric regressed beyond the noise band.') : r.verdict === 'inconclusive' ? '> 🟡 A 🛡️ guarded check is **inert**, it never runs, so nothing was actually verified. Fix its command before trusting a pass.' : '> ✅ No guarded metric regressed.',
     ...(r.gate && r.gate.weakened ? ['', `> 🚩 **Gate weakened:** ${r.gate.weakened.map((w) => `\`${w.name}\` ${w.change === 'guard-removed' ? 'removed' : 'disabled'} (would have ${w.status} at head)`).join('; ')}. The pass was bought by dropping a guard, not by earning it.`] : []),
+    ...(r.gate && r.gate.changed ? ['', `> ⚠ **Gate definition changed** in this diff (fingerprint \`${r.gate.fingerprint.base}\` -> \`${r.gate.fingerprint.head}\`): a metric, guard, evaluatorPath or mandate was added, removed or edited. Review the config change with the code.`] : []),
     '',
     '<sub>🛡️ = guard · _prove every change moved a metric_ · [PromptWheel](https://github.com/promptwheel-ai/promptwheel)</sub>',
   ].join('\n');
@@ -1144,21 +1048,18 @@ function parseArgs(argv) {
     else if (argv[i] === '--no-record') a.noRecord = true;
     else if (argv[i] === '--no-auto') a.noAuto = true;
     else if (argv[i] === '--allow') a.allow = argv[++i];
-    else if (argv[i] === '--detect-gaming' || argv[i] === '--antihack') { a.detectGaming = true; a.dgExplicit = true; }
-    else if (argv[i] === '--no-detect-gaming' || argv[i] === '--no-antihack') { a.detectGaming = false; a.dgExplicit = true; }
-    else if (argv[i] === '--since') a.since = argv[++i];
-    else if (argv[i] === '-n' || argv[i] === '--limit') a.n = parseInt(argv[++i], 10);
+    else if (argv[i] === '--detect-gaming') a.detectGaming = true;
+    else if (argv[i] === '--no-detect-gaming') a.detectGaming = false;
     else if (argv[i] === '--attempt') a.attempt = argv[++i];
-    else if (argv[i] === '--label') a.label = argv[++i];
     else if (argv[i] === '--json') a.json = true;
-    else if (argv[i] === '--markdown' || argv[i] === '--md') a.markdown = true;
+    else if (argv[i] === '--markdown') a.markdown = true;
   }
   return a;
 }
 
 // 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, isNonSource, evaluatorMatcher, gain, judgeGaming, foldOutcomes, betaMean, scoreKey, verdictFingerprint };
+export { extract, evaluate, median, spread, renderMarkdown, isNonSource, evaluatorMatcher, gain, judgeGaming, verdictFingerprint };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Public library API: the Verified-Outcome Contract, in process.
@@ -1201,8 +1102,7 @@ export function verdictExitCode(verdict) {
 //   auto          boolean  allow the zero-config auto-detect fallback (default true; false throws if no config)
 //   repeat        number   measurement repeats for the noise band (default: config.repeat ?? 1)
 //   detectGaming  boolean  run the Section 3 source-only re-proof (default: true)
-//   cohort        string   cohort tag for the record (default: CI ? 'ci' : 'local')
-//   label         string   change-type label
+//   allow         string   a declared override reason (same as --allow / a Promptwheel-Allow: trailer)
 //   record        boolean  append the run to .promptwheel/outcomes.jsonl (default: false)
 export function check(options = {}) {
   let repo;
@@ -1227,8 +1127,6 @@ export function check(options = {}) {
     config,
     repeat: options.repeat,
     detectGaming: options.detectGaming ?? true,
-    cohort: options.cohort,
-    label: options.label,
     allow: options.allow,
     noRecord: options.record !== true,
   });
@@ -1283,6 +1181,7 @@ export function conformsToContract(report) {
     if (!report.gate || typeof report.gate !== 'object' || Array.isArray(report.gate)) E('gate must be an object');
     else {
       if (report.gate.fingerprint !== undefined && (typeof report.gate.fingerprint !== 'object' || report.gate.fingerprint === null)) E('gate.fingerprint must be an object { base, head }');
+      if (report.gate.changed !== undefined && typeof report.gate.changed !== 'boolean') E('gate.changed must be a boolean');
       if (report.gate.weakened !== undefined && !Array.isArray(report.gate.weakened)) E('gate.weakened must be an array');
     }
   }
@@ -1363,40 +1262,40 @@ function conformance(argv) {
 
 function main() {
   const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === '--version' || cmd === '-v') { console.log(TOOL_VERSION ?? 'unknown'); process.exit(0); }
   if (cmd === 'run') run(rest);
   else if (cmd === 'improve') improve(rest);
   else if (cmd === 'insights') insights(rest);
-  else if (cmd === 'playbook') playbook(rest);
-  else if (cmd === 'suggest') suggest(rest);
-  else if (cmd === 'backfill') backfill(rest);
   else if (cmd === 'init') init(rest);
   else if (cmd === 'guards') guards(rest);
   else if (cmd === 'conformance') conformance(rest);
   else {
+    const help = !cmd || cmd === '--help' || cmd === '-h' || cmd === 'help';
+    if (!help) console.error(`unknown command: ${cmd}`);
     console.log([
-      '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: a deterministic, zero-LLM check for your coding loop. It proves every change earned its win by re-running the result from the agent\'s source edits alone, so a green that came from editing the test reads GAMED.',
       '',
+      '  promptwheel --version | -v                   print the version',
+      '  promptwheel --help | -h                      this banner',
       '  promptwheel init [--preset <name> | --list] [--no-agent-block]  write a starter config + an AGENTS.md guide so your agent runs the gate (OPTIONAL: run works zero-config, auto-detecting your test command)',
       '  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 --allow "<reason>"           acknowledge an intentional test/config change (or a `Sawbuck-Allow: <reason>` commit trailer): recorded, not flagged GAMED',
+      '  promptwheel run --allow "<reason>"           acknowledge an intentional test/config change (or a `Promptwheel-Allow: <reason>` commit trailer; `Sawbuck-Allow:` is an alias): recorded, not flagged GAMED',
       '  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 (raw counts)',
-      '  promptwheel playbook [--json]                the earned playbook: decayed, evidence-gated claims distilled from the record',
-      '  promptwheel suggest [--json]                 UCB work-discovery: where the next attempt should go (experimental)',
-      '  promptwheel backfill [-n N | --since <ref>]  seed the ledger from git history (cohort-tagged; commit types become labels)',
-      '  promptwheel guards                           show the effective guardrails (incl. inherited) + flag record',
+      '                                               exit 0=kept · 1=regression · 2=gamed · 3=plateau/inconclusive (all but 0 reverted) · add --json',
+      '  promptwheel insights [--json]                which metrics actually respond (raw counts from .promptwheel/outcomes.jsonl)',
+      '  promptwheel guards [--json]                  show the effective guardrails (incl. inherited) + flag record',
       '  promptwheel conformance [file|-] [--cmd C]   check a verdict JSON (or a command) against the Contract (exit 0 = conforms)',
       '',
+      'Exit codes: 0 pass · 1 fail (a guarded metric regressed, or a mandate was violated) · 2 gamed · 3 inconclusive · 64 usage or config error (never a verdict).',
       'Integrate (library / conform / shell / MCP): see INTEGRATE.md. Import: `import { check } from \'promptwheel\'`.',
       'Loop it:  while promptwheel improve --attempt "$AGENT"; do :; done   # stops on plateau/regression',
       '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);
+    process.exit(help ? 0 : EX_USAGE);
   }
 }