sawbuck 0.1.4 → 0.1.6

package/CONTRACT.md

@@ -46,10 +46,12 @@ The agent consumes this as a per-turn reward it cannot inflate. The harness cons
       "delta": 1,
       "status": "improved",
       "ok": true,
-      "noise": { "band": 0, "runs": 3 },
+      "confidence": "high",
+      "noise": 0,
       "gamed": true,
+      "sourceOnly": null,
       "retained": 0.0,
-      "gamingReason": "the win did not survive reverting the test changes"
+      "gamingReason": "the win changed zero production-source files, only test/config/grader/golden"
     }
   ]
 }
@@ -61,7 +63,9 @@ Fixed vocabularies (a conforming implementation uses exactly these):
 - `metric.status` ∈ `improved | regressed | unchanged | inconclusive | unmeasurable`
 - `direction` ∈ `up | down | pass` (the direction that counts as better; `pass` means a 0/1 gate)
 
-`retained` is the fraction of a metric's gain that survived the source-only re-run (§3). `noise` is the measured jitter band across `repeat` runs; a delta inside it is `inconclusive`, never a regression.
+`retained` is the fraction of a metric's gain that survived the source-only re-run (§3). `noise` is the measured jitter band as a single number, across the top-level `repeat` runs; a delta inside it is `inconclusive`, never a regression. `confidence` (`unverified | low | medium | high`) and `sourceOnly` (the metric's value when only source edits are replayed, §3) are informational fields the reference implementation adds; a minimal conforming report may omit them. A consumer validates a report with `conformsToContract()` from the `promptwheel` package (see INTEGRATE.md) or `promptwheel conformance`.
+
+`gate` (optional) is the gate-integrity record. `gate.fingerprint` is a truncated SHA-256 of the normalized gate definition at `base` and `head`, so a changed gate is visible in the audit record. `gate.weakened`, present only when it happened, lists guards the change dropped (removed, or set to `guard:false`) that would have failed at `head`. A non-empty `gate.weakened` forces `verdict: gamed`: an agent cannot earn a pass by disabling the guard it is being judged by.
 
 ## 3. The integrity boundary (what counts as gaming)
 

package/dispatch.mjs

@@ -18,8 +18,17 @@ if (!rec || (!total && !force)) process.exit(0);          // nothing recorded
 if (process.argv.includes('--json')) { console.log(JSON.stringify(rec)); process.exit(0); }
 
 const n = (x, s) => `${x} ${s}${x === 1 ? '' : 's'}`;
-const parts = ['Sawbuck', `${n(rec.regressions || 0, 'regression')} charted`];
-if (rec.gamed) parts.push(`${n(rec.gamed, 'gamed change')} caught`);
-let line = parts.join('  ·  ');
-if (rec.latest) line += `\n   🆕 just learned: ${rec.latest.reason || rec.latest.kind} (${rec.latest.file})`;
+const L = rec.latest;
+// Attribute the latest catch to the agent that made it (the Claude hook passes 'claude').
+let head;
+if (L && L.kind === 'gamed') head = L.by ? `🐴 Sawbuck caught ${L.by} gaming a metric` : `🐴 Sawbuck caught a gamed change`;
+else if (L && L.kind === 'regression') head = L.by ? `🐴 Sawbuck flagged a regression from ${L.by}` : `🐴 Sawbuck flagged a regression`;
+else head = `🐴 Sawbuck`;
+let line = head;
+if (L) {
+  const why = String(L.reason || L.kind).replace(/^a change here was gamed,\s*/i, '').replace(/^a change here\s+/i, '');
+  line += `\n   ${L.file}: ${why}`;
+}
+const tally = [rec.gamed ? n(rec.gamed, 'gamed change') : '', rec.regressions ? n(rec.regressions, 'regression') : ''].filter(Boolean).join(', ');
+if (tally) line += `\n   (${tally} caught here so far)`;
 console.log(line);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Sign your agent to a contract so it does what you want: a deterministic, zero-LLM check that re-proves every win from the agent's source edits alone, so a green that came from editing the test is caught and reverted. A saddle for your coding harness.",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,7 @@
     "sawbuck": "sawbuck.mjs"
   },
   "dependencies": {
-    "promptwheel": "^0.4.5",
+    "promptwheel": "^0.5.0",
     "@promptwheel/logbook": "^0.9.0"
   },
   "files": [

package/reflect.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // reflect.mjs, the Sawbuck feedback edge (M0).
 //
-// Run the check (packages/referee) on the latest commit; on an gamed or
+// Run the check (the promptwheel engine) on the latest commit; on a gamed or
 // regression result, deterministic ground truth, record a finding in the
-// memory (packages/logbook) on the touched source paths, and tick the results
+// memory (the logbook engine) on the touched source paths, and tick the results
 // record. Quiet by default; the dispatch surfaces catches on a cadence.
 //
 // Zero-dep, Node ESM. Orchestrates the engine CLIs behind a clean layer
@@ -39,6 +39,7 @@ const flag = (name, def) => { const i = process.argv.indexOf(name); return i > -
 const repo = flag('--repo', process.cwd());
 const base = flag('--base', 'HEAD~1');
 const head = flag('--head', 'HEAD');
+const by = flag('--by', '');   // the agent that authored the change (Claude-first: the Claude hook passes 'claude'); empty = unattributed (raw-git path)
 
 const git = (...a) => execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim();
 // backstop so the check can never hang a commit/turn; generous default, overridable.
@@ -94,7 +95,7 @@ const recPath = join(recDir, 'results.json');
 let rec = { regressions: 0, gamed: 0, latest: null };
 try { if (existsSync(recPath)) rec = JSON.parse(readFileSync(recPath, 'utf8')); } catch {}
 if (kind === 'gamed') rec.gamed += 1; else rec.regressions += 1;
-rec.latest = { sha: sha.slice(0, 8), kind, file: evidenceFile, reason: reason.replace(/^sawbuck: /, '').slice(0, 140), at: new Date().toISOString() };
+rec.latest = { sha: sha.slice(0, 8), kind, file: evidenceFile, reason: reason.replace(/^sawbuck: /, '').slice(0, 140), at: new Date().toISOString(), by: by || null };
 try { mkdirSync(recDir, { recursive: true }); writeFileSync(recPath, JSON.stringify(rec, null, 2) + '\n'); } catch {}
 
 // --- 5) quiet by default (dispatch surfaces on cadence); one line to stderr -
@@ -116,7 +117,7 @@ function appendActivity(v, rep) {
     : k === 'regression' ? 'a guarded metric regressed beyond noise'
     : k === 'verified' ? 'the source earned the green'
     : 'could not certify a pass';
-  const ev = { at: new Date().toISOString(), kind: k, sha, file, reason: String(why).slice(0, 160) };
+  const ev = { at: new Date().toISOString(), kind: k, sha, file, reason: String(why).slice(0, 160), by: by || null };
   const dir = join(repo, '.sawbuck');
   const p = join(dir, 'activity.jsonl');
   try {

package/sawbuck-hook.mjs

@@ -12,6 +12,10 @@ import { fileURLToPath } from 'node:url';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 const repo = flag('--repo', process.cwd());
+const by = flag('--by', '');   // attribution from the harness wiring: the Claude hook passes 'claude', the raw-git hook passes nothing
+const stop = process.argv.includes('--stop');   // wired as the Claude Code Stop hook: enforce the contract on a gamed turn
+let hookInput = {};
+if (stop) { try { hookInput = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch {} }   // the Stop hook's JSON on stdin (stop_hook_active, prompt_id, ...)
 ensureExcluded(repo);   // keep the record out of git status under ANY attach mode (incl. --user)
 
 const git = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
@@ -31,14 +35,41 @@ try { if (existsSync(stPath)) st = JSON.parse(readFileSync(stPath, 'utf8')); } c
 // 1) new commit(s) since last turn → run the check on them
 const head = git('rev-parse', 'HEAD');
 if (head && st.lastSha && head !== st.lastSha) {
-  node(join(HERE, 'reflect.mjs'), ['--repo', repo, '--base', st.lastSha, '--head', head]);
+  node(join(HERE, 'reflect.mjs'), ['--repo', repo, '--base', st.lastSha, '--head', head, ...(by ? ['--by', by] : [])]);
 }
 st.lastSha = head || st.lastSha;
 st.turns += 1;
 
-// 2) decide whether to speak, fresh catch always; cadence unless onlyOnCatch
-let total = 0;
-try { const r = JSON.parse(readFileSync(join(stDir, 'results.json'), 'utf8')); total = (r.regressions || 0) + (r.gamed || 0); } catch {}
+// 2) read the record of what the check has charted
+let rec = null;
+try { rec = JSON.parse(readFileSync(join(stDir, 'results.json'), 'utf8')); } catch {}
+const total = rec ? (rec.regressions || 0) + (rec.gamed || 0) : 0;
+const saveState = () => { try { mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n'); } catch {} };
+
+// 3) CONTRACT ENFORCEMENT (Claude Code Stop hook only): if THIS turn's commit was gamed,
+// block the stop and send the agent back to earn the green in the source. Bounded per
+// prompt, because Claude Code's built-in block cap resets on every tool call and so cannot
+// bound a tool-using agent on its own. Opt out with SAWBUCK_NO_ENFORCE=1 (falls back to a flag).
+const gamedThisTurn = rec && rec.latest && rec.latest.kind === 'gamed' && rec.latest.sha === (head || '').slice(0, 8);
+if (stop && gamedThisTurn && !process.env.SAWBUCK_NO_ENFORCE) {
+  const MAX_BLOCKS = +(cfg.enforce?.maxBlocks) || 3;
+  const promptId = hookInput.prompt_id || 'none';
+  if (st.blockPromptId !== promptId) { st.blockPromptId = promptId; st.blockCount = 0; }
+  st.shownTotal = total;
+  const where = rec.latest.file;
+  if ((st.blockCount || 0) < MAX_BLOCKS) {
+    st.blockCount = (st.blockCount || 0) + 1;
+    saveState();
+    const reason = `Sawbuck: the win on ${where} was gamed. It came from editing the test or config, not the source, so it did not survive a source-only re-run. The turn is not done: fix the source so the metric passes on its own, then finish.`;
+    process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+    process.exit(0);
+  }
+  saveState();   // budget spent: let the turn end, but warn loudly so it never loops forever
+  process.stdout.write(JSON.stringify({ systemMessage: `Sawbuck stopped blocking after ${MAX_BLOCKS} tries: the win on ${where} is still gamed and needs a real source fix.` }));
+  process.exit(0);
+}
+
+// 4) otherwise, surface a catch on a fresh catch or on cadence (a flag; never blocks)
 const freshCatch = total > (st.shownTotal || 0);
 const cadenceHit = everyTurns > 0 && st.turns % everyTurns === 0;
 if (freshCatch || (cadenceHit && !onlyOnCatch)) {
@@ -46,8 +77,7 @@ if (freshCatch || (cadenceHit && !onlyOnCatch)) {
   if (out.trim()) process.stdout.write(out.endsWith('\n') ? out : out + '\n');
   st.shownTotal = total;
 }
-
-try { mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n'); } catch {}
+saveState();
 
 // Keep the record dirs out of `git status` via .git/info/exclude, so Sawbuck never
 // dirties the worktree, including under `attach --user`, which is global and cannot

package/sawbuck.mjs

@@ -291,7 +291,7 @@ function wireClaude(repo, opts) {
   if (fileExisted) { try { cfg = JSON.parse(readFileSync(f, 'utf8')); } catch { die(`${f} exists but is not valid JSON; I will not overwrite it. Add the hooks by hand.`); } }
   if (JSON.stringify(cfg).includes('sawbuck.mjs')) { out(`sawbuck: already attached (${user ? 'user' : 'claude'}) in ${f}`); if (!user) warnNoConfig(repo); return; }
   const ctx = user ? `node ${JSON.stringify(SELF)} context` : `node ${JSON.stringify(SELF)} context ${JSON.stringify(repo)}`;
-  const chk = user ? `node ${JSON.stringify(SELF)} __hook` : `node ${JSON.stringify(SELF)} __hook --repo ${JSON.stringify(repo)}`;
+  const chk = user ? `node ${JSON.stringify(SELF)} __hook --by claude --stop` : `node ${JSON.stringify(SELF)} __hook --repo ${JSON.stringify(repo)} --by claude --stop`;
   if (dry) {
     out(dryText([
       `${fileExisted ? 'modify' : 'create'}  ${f}  (UserPromptSubmit + Stop hooks)`,