promptwheel 0.7.12 → 0.7.14

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/promptwheel-ai/promptwheel/actions/workflows/ci.yml/badge.svg)](https://github.com/promptwheel-ai/promptwheel/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) ![Node ≥18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![deps: zero](https://img.shields.io/badge/deps-zero-blue)
 
-**A deterministic, zero-LLM check for your coding loop.** A green test should mean your agent *fixed the code*, not that it edited the test to match the bug. PromptWheel re-proves every win from the agent's source edits alone, so a green that came from editing the test, grader or config reads `GAMED`. The code being checked never gets to grade itself.
+**A deterministic, zero-LLM check for your coding loop.** A green test should mean your agent *fixed the code*, not that it edited the test to match the bug. PromptWheel re-proves every win from the agent's source edits alone, so a test that went from red to green because the test, grader or declared config changed reads `GAMED`. The code being checked never gets to grade itself.
 
 ![PromptWheel catching an agent game the metric, then passing an honest fix](demo/promptwheel.gif)
 
@@ -177,14 +177,14 @@ Then `/promptwheel:setup` (write a config) · `/promptwheel:gate` (gate uncommit
 
 ## Trust model
 
-**What it catches.** After the normal gate, every *win* is re-proven using the agent's source edits alone. If the win only survived by skipping or deleting a test, mocking the grader, editing a golden, relaxing a config, or touching zero source files, the verdict is `GAMED` (exit 2). On top of that:
+**What it catches.** After the normal gate, every *win* is re-proven using the agent's source edits alone. If the win only survived by skipping or deleting a test, mocking the grader, editing a golden, relaxing a declared config, or touching zero source files, the verdict is `GAMED` (exit 2). On top of that:
 
 - **Tripwire guards** (`test_count`, `skipped_tests`, `suppressions`, `assertions`, written by the plain `init` default) catch the quieter shapes: an inline suppression (`@ts-nocheck`, `eslint-disable`, `# noqa`) or a suite gutted while the metric stays flat.
 - **Gate integrity.** The gate is resolved as of the base commit too. A change that disables a guard or deletes a guarded metric in the same diff it passes is re-measured under the base definition and reads `GAMED` if that guard would have failed. The gate definition (metrics, guards, `evaluatorPaths`, `gamingThreshold`, `mandates`) is fingerprinted at both refs; a difference is recorded as `gate.changed` and printed.
 - **A sanctioned override.** A commit trailer can be written by whoever writes the commit, including an agent, so `"allowTrailer": false` in the contract turns trailers off and only the `--allow` flag counts (the supply-chain preset sets this; the contract at the base ref decides, so a change cannot turn trailers back on for itself). When you *do* mean to change a test, config, or grader, declare it: a `Promptwheel-Allow: <reason>` trailer on the commit (`Sawbuck-Allow:` is accepted as an alias), `--allow "<reason>"` on the CLI, or the `allow` option on `check()`, turns what would read `GAMED` into a `pass` with the reason recorded in `report.allowed`. It covers a win whose source-only re-run could not be applied (`unprovable`, otherwise `inconclusive`) the same way. An undeclared test-only win is still `gamed`, and a reasonless declaration does not override. The check never judges intent; it forces intent to be explicit and auditable.
 - **A provenance receipt** on every verdict (`report.provenance`: base and head SHAs, a config hash, a verdict hash), so a skeptic can re-run `(base, head, config)` and get the same hash.
 
-**The honest limit.** This is one layer, not a silver bullet. It catches the evaluator-tampering class (test, grader, golden and config edits) deterministically and for free. It is blind, by construction, to a cheat that lives in the source file itself (a hardcoded answer, behavior that differs under test): that needs held-out tests, an LLM judge, or a human, and those expensive layers should be reserved for the calls only they can make. The coverage matrix and the in/out-of-scope boundary are in [docs/DETECTION-LAYERS.md](docs/DETECTION-LAYERS.md); the measured numbers are in [bench/RESULTS.md](bench/RESULTS.md) (`node bench/gaming-bench.mjs` to reproduce). Another gameable thing, an LLM judge asking "did you cheat?", is deliberately not part of the check.
+**The honest limit.** This is one layer, not a silver bullet. It catches the evaluator-tampering class (test, grader, golden and config edits) deterministically and for free. A suite weakened while it stays green is not proved: there is no win to re-run. Tripwires catch skips and removed assertions in a signed repo. It is blind, by construction, to a cheat that lives in the source file itself (a hardcoded answer, behavior that differs under test): that needs held-out tests, an LLM judge, or a human, and those expensive layers should be reserved for the calls only they can make. The coverage matrix and the in/out-of-scope boundary are in [docs/DETECTION-LAYERS.md](docs/DETECTION-LAYERS.md); the measured numbers are in [bench/RESULTS.md](bench/RESULTS.md) (`node bench/gaming-bench.mjs` to reproduce). Another gameable thing, an LLM judge asking "did you cheat?", is deliberately not part of the check.
 
 **Noise.** A number that jumps around between runs is worthless as a signal, and PromptWheel does not pretend otherwise: `--repeat N` measures each metric N times at both refs and uses the median; the noise band is the observed spread; a delta inside the band is `inconclusive` with `low` confidence and does not fail a guard (no flaky CI failures). Confidence reads `high` (deterministic extract, or zero observed noise), `medium` (delta clears the noise band), `low` (delta inside noise), or `unverified` (single read; run `--repeat` to earn trust). A guard whose command never ran (same value at both refs) makes the verdict `inconclusive`, never a fake pass.
 

package/bin/promptwheel.d.ts

@@ -336,3 +336,6 @@ export declare function judgeGaming(
 
 /** Truncated SHA-256 of the verdict content (everything but `provenance`), the reproducible half of the receipt. */
 export declare function verdictFingerprint(report: Pick<Report, 'verdict'> & Partial<Pick<Report, 'metrics' | 'gate'>>): string;
+
+/** The newest `sawbuck-allow: <reason>` comment from someone with write access, or ''. */
+export declare function allowFromComments(comments: unknown[]): string;

package/bin/promptwheel.mjs

@@ -330,7 +330,7 @@ function checkMandates(repo, base, head, cfg, baseMandates) {
   const mandates = [...headList.filter((m) => m && baseNames.has(m.name)), ...kept];
   if (!mandates.length) return [];
   let changed = [];
-  try { changed = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean); } catch { return []; }
+  try { changed = git(['diff', '--name-only', '--no-renames', base, head], repo).split('\n').filter(Boolean); } catch { return []; }   // --no-renames: a move out of a protected path also touches it
   const out = [];
   for (const m of mandates) {
     const pats = (Array.isArray(m.paths) ? m.paths : []).filter((s) => typeof s === 'string' && s.trim());
@@ -355,7 +355,7 @@ function checkMandates(repo, base, head, cfg, baseMandates) {
 // `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.
 function changedSourcePaths(repo, base, head, isEval = () => false) {
-  const all = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean);
+  const all = git(['diff', '--name-only', '--no-renames', base, head], repo).split('\n').filter(Boolean);
   const nonSrc = (p) => isNonSource(p) || isEval(p);
   return { source: all.filter((p) => !nonSrc(p)), nonSource: all.filter(nonSrc) };
 }
@@ -363,6 +363,37 @@ function changedSourcePaths(repo, base, head, isEval = () => false) {
 // measure the given metric defs in ONE worktree at `base` with ONLY the source slice of base→head
 // applied (checked out once, patched once, set up once), so re-proving three improved metrics costs
 // one checkout, not three. Returns { [name]: { samples, hadSourceChange, applyFailed? } }.
+// package.json and pyproject.toml are source and goalposts in one file: dependencies belong to the
+// change, the test command and the test runner's options do not. The source-only tree keeps the change's
+// file but puts those keys back as they were at base, so `"test": "true"` or `addopts = "-k mul"` cannot
+// carry a win. A test command that really had to change is a declared change: --allow.
+const JS_TEST_KEYS = ['scripts', 'jest', 'ava', 'mocha', 'nyc', 'c8', 'vitest', 'tap'];
+const PY_TEST_TABLE = /^\[\s*tool\.(pytest|coverage|tox)[\].]/;
+function tomlTables(text) {   // [header, lines] pairs in file order; the first has no header
+  const out = [[null, []]];
+  for (const line of text.split('\n')) { if (/^\s*\[/.test(line)) out.push([line.trim(), [line]]); else out[out.length - 1][1].push(line); }
+  return out;
+}
+function holdGoalposts(repo, base, wt, source) {
+  for (const p of source) {
+    const name = p.split('/').pop();
+    if (name !== 'package.json' && name !== 'pyproject.toml') continue;
+    let before; try { before = git(['show', `${base}:${p}`], repo); } catch { continue; }   // a new file has no base to hold
+    const f = join(wt, p);
+    try {
+      if (name === 'package.json') {
+        const a = JSON.parse(before), b = JSON.parse(readFileSync(f, 'utf8'));
+        for (const k of JS_TEST_KEYS) { if (k in a) b[k] = a[k]; else delete b[k]; }
+        writeFileSync(f, JSON.stringify(b, null, 2) + '\n');
+      } else {
+        const held = tomlTables(before).filter(([h]) => h && PY_TEST_TABLE.test(h));
+        const kept = tomlTables(readFileSync(f, 'utf8')).filter(([h]) => !h || !PY_TEST_TABLE.test(h));
+        writeFileSync(f, [...kept, ...held].map(([, l]) => l.join('\n')).join('\n') + '\n');
+      }
+    } catch { /* an unreadable manifest stays as the change left it */ }
+  }
+}
+
 function measureSourceOnlyAll(repo, base, head, defs, cfg, repeat) {
   const out = {};
   if (!defs.length) return out;
@@ -383,6 +414,7 @@ function measureSourceOnlyAll(repo, base, head, defs, cfg, repeat) {
       try { tryApply(['--3way']); }
       catch { try { tryApply([]); } catch { for (const m of defs) out[m.name] = { samples: [], hadSourceChange: true, applyFailed: true }; return out; } }
     }
+    holdGoalposts(repo, base, wt, source);   // the parts of a mixed file that define the tests stay as they were at base
     runSetup(wt, cfg, env); // build the patched tree, so a build-gated metric measures the source edit
     for (const m of defs) {
       const samples = [];
@@ -576,7 +608,7 @@ function blobHashAt(repo, ref, path) {
 function changedEvaluatorPaths(repo, base, head, cfg) {
   const isEval = evaluatorMatcher(cfg);
   let changed = [];
-  try { changed = git(['diff', '--name-only', base, head], repo).split('\n').filter(Boolean).filter(isEval); }
+  try { changed = git(['diff', '--name-only', '--no-renames', base, head], repo).split('\n').filter(Boolean).filter(isEval); }
   catch { return []; }
   return changed.map((p) => ({ path: p, base: blobHashAt(repo, base, p), head: blobHashAt(repo, head, p) }))
     .filter((e) => e.base !== e.head);
@@ -648,6 +680,16 @@ function detectGamingPass(repo, base, head, cfg, metrics, repeat) {
     m.gamed = j.gamed; m.sourceOnly = j.sourceOnly; m.retained = j.retained; m.gamingReason = j.reason;
     if (j.unprovable) m.unprovable = true;
   }
+  // A green that stays green proves nothing about the tests. When a change edits the source and the tests
+  // together, run the old tests on the new source: if they fail, say so. Only a note, never a verdict: an
+  // intended API change does this too, and no deterministic check can tell the two apart.
+  const split = changedSourcePaths(repo, base, head, evaluatorMatcher(cfg));
+  if (split.source.length && split.nonSource.length) {
+    const held = metrics.filter((m) => m.status === 'unchanged' && m.direction === 'pass' && m.after === 1 && !m.tripwire);
+    const defs = held.map((m) => cfg.metrics.find((c) => c.name === m.name)).filter(Boolean);
+    const res = measureSourceOnlyAll(repo, base, head, defs, cfg, repeat);
+    for (const m of held) { const r = res[m.name]; if (r && r.samples && r.samples.length && median(r.samples) !== 1) m.heldByTestEdit = true; }
+  }
   const evalChanged = changedEvaluatorPaths(repo, base, head, cfg);
   if (evalChanged.length) {
     for (const m of metrics) {
@@ -695,7 +737,7 @@ function detectGamingPass(repo, base, head, cfg, metrics, repeat) {
 export function deriveVerdict(metrics, gateInfo = null, mandated = false) {
   const failed = metrics.some((m) => m.guard && !m.ok);
   const gamed = metrics.some((m) => m.gamed === true) || !!(gateInfo && gateInfo.weakened && !gateInfo.allowed);
-  const inertNoWin = metrics.some((m) => m.inert) && !metrics.some((m) => m.status === 'improved');
+  const inertNoWin = metrics.some((m) => m.inert) && !metrics.some((m) => m.status === 'improved' && !m.tripwire);   // a tripwire moving is not a measured win
   const unprovable = metrics.some((m) => m.unprovable === true);
   const inconclusive = !failed && !gamed && (inertNoWin || unprovable);
   return (mandated || failed) ? 'fail' : gamed ? 'gamed' : inconclusive ? 'inconclusive' : 'pass';
@@ -732,7 +774,9 @@ function gate(repo, opts) {
   const metrics = cfg.metrics.map((m) => {
     const ev = evaluate(m, before[m.name], after[m.name], repeat);
     if (ev.status === 'unmeasurable' && ev.before == null && ev.after != null && adopted(m.name)) { ev.ok = true; ev.adopted = true; }
-    return { name: m.name, direction: m.direction || 'up', guard: !!m.guard, ...ev };
+    // a `report` guard tells you and does not fail: a contract can start by watching and tighten later
+    if (m.report && !ev.ok && ev.status === 'regressed') { ev.ok = true; ev.noted = true; }
+    return { name: m.name, direction: m.direction || 'up', guard: !!m.guard, ...(m.gamingCheck === false ? { tripwire: true } : {}), ...ev };
   });
   // 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;
@@ -793,7 +837,9 @@ function gate(repo, opts) {
   }
   const mandated = mandateViolations.length > 0;
   const verdict = deriveVerdict(metrics, gateInfo, mandated);
+  const explained = explainMetrics(repo, metrics);
   const report = {
+    ...(explained ? { explained } : {}),
     base: short(repo, base), head: short(repo, head), repeat, mode: opts.working ? 'working' : 'refs',
     verdict, metrics,
     ...(mandateViolations.length ? { mandates: mandateViolations } : {}),
@@ -945,10 +991,12 @@ const PRESETS = {
   // edit (a lifecycle script, a new dependency, a non-registry lock source, a workflow or publish
   // config). Paths and counts, checked deterministically: three guarded counts that must not rise
   // without a declared reason (`allowable`), plus mandates that freeze the paths. The contract itself is
-  // an evaluatorPath, not a mandate, so a person can still retire a rule in a change that only edits it.
+  // one of those paths, lifted only by a person's --allow: otherwise a change that only weakens a rule
+  // passes, and the next change is judged by the weakened contract.
   'supply-chain': { allowTrailer: false, desc: 'gate: no new lifecycle scripts, dependencies, or non-registry lock sources without a recorded reason; the agent cannot touch workflows, registries, publish scripts, or the contract',
     evaluatorPaths: ['promptwheel.config.json', 'sawbuck.config.json'],
     mandates: [
+      { name: 'contract-frozen', paths: ['promptwheel.config.json', 'sawbuck.config.json'], allowable: 'flag', reason: 'the contract changes with a reason from a person (--allow), never as a side effect of a change' },
       { name: 'workflows-frozen', paths: ['.github/workflows/**'], reason: 'workflows run with the repository secrets; change them in a separate, reviewed change' },
       { name: 'registry-config-frozen', paths: ['.npmrc', '.yarnrc', '.yarnrc.yml'], reason: 'registry and token configuration decides where packages come from and where credentials go' },
       { name: 'build-images-frozen', paths: ['Dockerfile*', 'docker-compose*'], reason: 'what runs at build and deploy time is not an agent decision' },
@@ -1182,6 +1230,34 @@ function printHuman(r) {
 }
 
 // PR-comment markdown (rendering lives in the tool so the GitHub Action stays thin)
+// What a person needs when a check speaks: what changed, in words, and how to accept it.
+const PLAIN = {
+  lifecycle_scripts: 'a new install script', dependency_entries: 'a new dependency', lock_nonregistry_sources: 'a dependency from outside the registry',
+  unpinned_execution: 'something that runs without a pinned version', install_policy_gaps: 'a weaker install policy', lock_drift: 'the shape of the repo changed',
+  pins_changed: 'resolved dependency versions changed', tests_pass: 'tests stopped passing', test_count: 'fewer tests', skipped_tests: 'more skipped tests',
+  suppressions: 'more silenced checks', assertions: 'fewer assertions',
+};
+function explainMetrics(repo, metrics) {
+  const hit = metrics.filter((m) => m.noted || (m.guard && !m.ok));
+  if (!hit.length) return null;
+  let items = [];
+  if (hit.some((m) => m.name === 'lock_drift')) {
+    try { items = JSON.parse(execFileSync(process.execPath, ['.promptwheel/packs/supply-chain/lock.mjs', 'drift', '.', '--json'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })).slice(0, 8); } catch { /* words without the list */ }
+  }
+  return hit.map((m) => ({ metric: m.name, noted: !!m.noted, what: PLAIN[m.name] || m.name, ...(m.name === 'lock_drift' && items.length ? { items } : {}), ...(m.allowable ? { allowable: true } : {}) }));
+}
+// A reason a person left on a pull request. The newest `sawbuck-allow: <reason>` comment from someone with write
+// access wins. A bot never counts. An agent signed in as that person can still post one: the record shows it.
+export function allowFromComments(comments) {
+  const trusted = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+  for (const c of [...(comments || [])].reverse()) {
+    if (!c || !c.user || c.user.type !== 'User' || !trusted.has(c.author_association)) continue;
+    const m = String(c.body || '').match(/^\s*sawbuck-allow:[ \t]*(\S.*?)[ \t]*$/m);
+    if (m) return `${m[1].slice(0, 280)} (approved by ${String(c.user.login).slice(0, 39)})`;
+  }
+  return '';
+}
+
 function renderMarkdown(r) {
   const icon = r.verdict === 'pass' ? '✅' : r.verdict === 'gamed' ? '🚩' : r.verdict === 'inconclusive' ? '🟡' : '❌';
   const sIcon = { improved: '🟢', regressed: '🔴', unchanged: '⚪', inconclusive: '🟡', unmeasurable: '⚫' };
@@ -1196,6 +1272,7 @@ 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)' : md.edited ? ' (edited in this same change; the version before the change stays in force for the change that edits it)' : ''}`).join('\n'), ''] : []),
+    ...(r.explained ? [...r.explained.map((x) => `> ${x.noted ? 'ℹ️ **Note:**' : '✋ **Needs a look:**'} ${x.what}${x.items ? ': `' + x.items.join('`, `') + '`' : ''}`), ...(r.explained.some((x) => !x.noted && x.allowable) ? ['>', '> To accept this, comment `sawbuck-allow: <your reason>` on this PR and re-run the check.'] : []), ''] : []),
     '| metric | before | after | Δ | status | confidence |',
     '|---|--:|--:|--:|---|---|',
     rows,
@@ -1470,6 +1547,7 @@ function dispatch() {
   if (cmd in COMMAND_FLAGS) checkFlags(cmd, rest);
   if (cmd === 'run') run(rest);
   else if (cmd === 'improve') improve(rest);
+  else if (cmd === 'pr-allow') { let c = []; try { c = JSON.parse(readFileSync(0, 'utf8') || '[]'); } catch { /* no comments, no approval */ } process.stdout.write(allowFromComments(c)); }
   else if (cmd === 'insights') insights(rest);
   else if (cmd === 'init') init(rest);
   else if (cmd === 'guards') guards(rest);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "promptwheel",
-  "version": "0.7.12",
-  "description": "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. Runs in CI or a Claude Code hook, or import { check } in process.",
+  "version": "0.7.14",
+  "description": "A deterministic, zero-LLM check for your coding loop. A win must survive a re-run from the agent's source edits alone, so a test that went green by editing the test reads GAMED. Runs in CI or a Claude Code plugin.",
   "type": "module",
   "bin": {
     "promptwheel": "bin/promptwheel.mjs"

package/packs/supply-chain/README.md

@@ -28,7 +28,9 @@ clean git worktrees, so a pack that is not in git is absent at both refs and the
 - **unpinned_execution**: code run from a reference that can move. A GitHub Action not pinned to a full commit SHA (a local `./action` does not count), `npx`, `bunx` or `dlx` with no exact version, `npm install -g` with no exact version, and a remote script piped into a shell. Read from workflows, `action.yml`, package.json scripts, `scripts/*.sh` and Dockerfiles. In package.json scripts, a tool the manifest declares does not count: the lockfile already pins it.
 - **install_policy_gaps**: 0, 1 or 2. Are install scripts disabled, and is a release-age cooldown set (`ignore-scripts=true` and `min-release-age` in `.npmrc`, or the pnpm or yarn equivalents)? The cooldown is enforced by the package manager, not by this pack: a registry lookup here would make the verdict depend on the clock.
 - **lock_drift**: structural items the tree has that `promptwheel.lock.json` does not. `promptwheel lock` reads the repo once and writes its shape: dependencies, install scripts, workflows, modules, import edges between modules, routes, public entry points, and the network hosts the source names. It also records each script's body, native binaries, and what a module can do (network, process spawning, eval), so a new capability shows even when the host is built at runtime. Ordinary edits never touch it. A new route is reported but not held by default; add `--routes` to hold it. On 1,403 commits across eight repositories this guard would have stopped 5.1%, about one in 20. JS and TS only for edges, routes, hosts and capabilities today.
-- **pins_changed**: a fingerprint of the resolved dependency tree, compared base to head, because a new version under an old name is how a worm arrives. It covers every package, version, source and integrity, not the file's bytes, so a release of your own project does not count. Any change needs a reason. Nothing is stored, so the lock does not change across updates and an approved update does not blind the next check. On the same commits this stopped 8.7%, all real dependency changes; use the CI path below for those.
+- **pins_changed**: a fingerprint of the resolved dependency tree, compared base to head, because a new version under an old name is how a worm arrives. It covers every package, version, source and integrity, not the file's bytes, so a release of your own project does not count. Any change needs a reason. Nothing is stored, so the lock does not change across updates and an approved update does not blind the next check. On the same commits this stopped 8.7%, dependency changes; use the CI path below for those.
+
+**On a pull request.** Someone with write access comments `sawbuck-allow: <reason>` and re-runs the check. `sawbuck contract` marks everyday guards `report: true`, so they note a change without failing until you tighten them; this preset on its own holds them all.
 
 **Dependency updates in CI.** Give the reason from a step the agent cannot reach. Workflows are a frozen path, so an agent cannot edit this:
 
@@ -77,13 +79,12 @@ and a mandate deleted or narrowed in the same change that violates it stays in f
 | build-images-frozen | `Dockerfile*`, `docker-compose*` | what runs at build and deploy time |
 | publish-scripts-frozen | `scripts/release*`, `scripts/publish*` | the publish path is how a compromise spreads |
 | codeowners-frozen | `CODEOWNERS` | review ownership is set by people |
+| contract-frozen | `promptwheel.config.json`, `sawbuck.config.json` | the contract changes with a reason from a person (`--allow`) |
 | hooks-frozen | `.claude/settings.json`, `.claude/settings.local.json`, `.sawbuck/**` | the hooks that enforce the contract are wired by a person |
 
-The contract itself (`promptwheel.config.json`, `sawbuck.config.json`) is protected as an
-`evaluatorPaths` entry rather than a mandate: a change that edits it alongside a win is `GAMED` by
-declaration unless the change carries a declared reason, while a change that only edits the
-contract (a person retiring a rule) still passes. A mandate there would make the contract
-un-editable through the gate.
+The contract itself (`promptwheel.config.json`, `sawbuck.config.json`) is frozen too, and it is also an
+`evaluatorPaths` entry. A change to it needs `--allow "<reason>"` from a person. Without that, a change that
+only weakens a rule would pass, and the next change would be judged by the weakened contract.
 
 A person who needs to change a frozen path does it in a separate change that only touches that
 path, reviewed as such.