sawbuck 0.1.4 → 0.1.7

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/README.md

@@ -7,13 +7,19 @@ A saddle for your coding harness. You write the contract (what a real win looks
 > Sawbuck is the reference implementation of the [Verified-Outcome Contract](CONTRACT.md): the open interface for a coding loop you can trust.
 
 ```sh
-npm i -g sawbuck         # also pulls the promptwheel + @promptwheel/logbook engines
-cd your-repo
-sawbuck attach           # wire it into the repo (a git post-commit hook)
-# or, once, for every project in Claude Code:
-sawbuck attach --user    # user-level hooks that profile-switch by cwd
+# 1 · try it (no install, no commitment): verify your latest change right now
+npx sawbuck check
+
+# 2 · watch it live: attach once to this repo (a project-scoped Claude Code hook)
+npm i -g sawbuck
+sawbuck attach --claude
 ```
 
+**Zero-config:** it auto-detects your test command, so there is nothing to write to start.
+On attach it tells you exactly what it can measure here (and how to fix it if it can't).
+`sawbuck init` is only for *customizing* what it measures (coverage, latency, a cost budget).
+In CI instead of a local hook? use the GitHub Action. For every project at once: `sawbuck attach --user`.
+
 On each change:
 
 ```

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.7",
   "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.6.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

@@ -17,10 +17,26 @@ import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, unlinkSy
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
 const HOOK = join(HERE, 'sawbuck-hook.mjs');
+const require = createRequire(import.meta.url);
+// resolve the promptwheel engine bin: env override, installed package, then the dev sibling
+const PW = process.env.PW_BIN
+  || ['promptwheel/bin/promptwheel.mjs', 'promptwheel'].reduce((r, s) => { try { return r || require.resolve(s); } catch { return r; } }, '')
+  || join(HERE, '..', 'referee', 'bin', 'promptwheel.mjs');
+// run the engine and parse its JSON verdict (it prints JSON even when it exits nonzero)
+function gateReport(repo, a) {
+  let o = '', code = 0;
+  try { o = execFileSync(process.execPath, [PW, ...a, '--no-record', '--json'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 120000 }); }
+  catch (e) { o = (e.stdout || '').toString(); code = e.status || 0; }
+  let rep = null; try { rep = JSON.parse(o.slice(o.indexOf('{'))); } catch {}
+  return { rep, code };
+}
+// is the metric live (actually ran), or inert (never ran in isolation)?
+const metricLive = (m) => !!m && !m.inert && m.status !== 'unmeasurable' && m.before != null;
 const S_START = '# >>> sawbuck >>>';
 const S_END = '# <<< sawbuck <<<';
 const BLOCK_RE = new RegExp(`\\n?${S_START}[\\s\\S]*?${S_END}\\n?`, 'g');
@@ -64,8 +80,8 @@ Usage:
   sawbuck statusline        One-line segment for your status line (🐴 watching | N caught)
   sawbuck status [repo]     Show the results receipt (what the check has caught)
   sawbuck log [repo] [-n N] Recent activity, newest first: every check (verified / gamed / regression)
-  sawbuck check [--base R --head R]
-                            Run the check on a commit and record the outcome
+  sawbuck check [repo]      Try it: verify your latest change right now (working tree if dirty, else the
+                            last commit). Zero-config, no attach, no hook. The fastest way to see it work.
   sawbuck rank [--base R --head R] [--file P ...]
                             Show the relevant past findings for the paths a change touches
   sawbuck context [repo]    Ranked relevant history for your current working changes (the read face)
@@ -95,9 +111,21 @@ switch (cmd) {
     break;
   }
   case 'check': {
-    try { execFileSync(process.execPath, [join(HERE, 'reflect.mjs'), ...rest], { stdio: 'inherit' }); }
-    catch (e) { process.exit(e.status || 1); }
-    break;
+    // one-shot: gate your latest change right now (working tree if dirty, else the last commit),
+    // zero-config (the engine auto-detects your test command), and say plainly whether the win was
+    // earned. No attach, no hook, no record. The try-it-first on-ramp.
+    const repo = repoArg();
+    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
+    const dirty = g('status', '--porcelain').length > 0;
+    const where = dirty ? 'working' : 'last';
+    const { rep, code } = gateReport(repo, dirty ? ['run', '--working'] : ['run', '--base', 'HEAD~1', '--head', 'HEAD']);
+    if (!rep || !rep.verdict) { out('🐴 sawbuck: could not run the check here. Make sure this is a git repo with a commit, and a test command (or run `sawbuck init`).'); process.exit(2); }
+    const m = (rep.metrics || [])[0];
+    if (rep.verdict === 'pass') out(`🐴 ✓ verified: your ${where} change earned it. ${m ? '"' + m.name + '"' : 'The metric'} held, and the source carried the win (it survives a source-only re-run).`);
+    else if (rep.verdict === 'gamed') out('🐴 🚩 gamed: a win here came from editing the test, config, or grader, not the source. It does NOT survive a source-only re-run, so it does not count.');
+    else if (rep.verdict === 'fail') out(`🐴 ✗ regression: a guarded metric got worse (${(rep.metrics || []).filter((x) => x.guard && !x.ok).map((x) => x.name).join(', ') || 'a guard'}).`);
+    else out('🐴 ≈ couldn\'t measure: the check ran but your metric is inert (it did not actually run in isolation). Point it at your real test command: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json.');
+    process.exit(code);
   }
   case 'log': {
     // the event feed: a running log of what the check did, so you can watch it work.
@@ -148,9 +176,10 @@ switch (cmd) {
   }
   case 'attach': {
     const repo = repoArg();
-    if (flags.has('--user')) { wireClaude(repo, { user: true }); break; }
-    if (flags.has('--claude')) { wireClaude(repo, { shared: flags.has('--shared') }); break; }
+    if (flags.has('--user')) { wireClaude(repo, { user: true }); if (!dry) verifyAttach(repo); break; }
+    if (flags.has('--claude')) { wireClaude(repo, { shared: flags.has('--shared') }); if (!dry) verifyAttach(repo); break; }
     wireGit(repo);
+    if (!dry) verifyAttach(repo);
     break;
   }
   case 'detach': {
@@ -174,9 +203,13 @@ switch (cmd) {
       if (existsSync(join(repo, '.git'))) {
         let caught = 0;
         try { const r = JSON.parse(readFileSync(join(repo, '.sawbuck', 'results.json'), 'utf8')); caught = (r.regressions || 0) + (r.gamed || 0); } catch {}
-        // profile readout: armed (a contract to check) vs memory-only (history live, no contract yet)
-        const armed = existsSync(join(repo, 'promptwheel.config.json'));
-        process.stdout.write(caught > 0 ? `🐴 sawbuck · ${caught} caught` : armed ? `🐴 sawbuck · watching` : `🐴 sawbuck · memory`);
+        // the last verdict from the activity feed (includes verified passes), so you see it working each turn
+        let last = '';
+        try { const L = readFileSync(join(repo, '.sawbuck', 'activity.jsonl'), 'utf8').trim().split('\n'); const e = JSON.parse(L[L.length - 1]); last = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive: '≈' }[e.kind] || ''; } catch {}
+        // profile readout: watching (something to check, incl. zero-config via a test command) vs memory-only
+        const armed = existsSync(join(repo, 'promptwheel.config.json')) || existsSync(join(repo, 'package.json'));
+        const seg = caught > 0 ? `🐴 sawbuck · ${caught} caught` : armed ? `🐴 sawbuck · watching` : `🐴 sawbuck · memory`;
+        process.stdout.write(last ? `${seg} · ${last}` : seg);
       }
     } catch {}
     break;
@@ -184,6 +217,20 @@ switch (cmd) {
   default: die(`unknown command '${cmd}'\n\n${help}`);
 }
 
+// after attach, prove the check can actually measure something here (the inert-metric trap):
+// run the gate on the last commit and say what it can or cannot measure, so you never attach
+// into silent nothing. Best-effort and bounded; the wire already succeeded regardless.
+function verifyAttach(repo) {
+  const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
+  if (!g('rev-parse', 'HEAD')) { out('   attached. Make a commit, then run `sawbuck check` to see it work.'); return; }
+  out('   verifying I can measure here (one-time)...');
+  const base = g('rev-parse', '--verify', 'HEAD~1') ? 'HEAD~1' : 'HEAD';
+  const { rep } = gateReport(repo, ['run', '--base', base, '--head', 'HEAD']);
+  const m = rep && (rep.metrics || [])[0];
+  if (metricLive(m)) out(`   ✓ I can measure "${m.name}" here. On each commit I'll verify a win survived a source-only re-run, and flag it if it did not.`);
+  else out('   ⚠ I could not measure anything here yet (your test command did not run in isolation). Point me at it: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json. I stay quiet until then.');
+}
+
 // --- the attach receipt (out of the worktree, inside .git) ------------------
 function manifestPath(repo) { return join(repo, '.git', 'sawbuck', 'attach.json'); }
 function userManifestPath() { return join(homedir(), '.sawbuck', 'user-attach.json'); }
@@ -291,7 +338,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)`,
@@ -458,8 +505,7 @@ function detachAll(purge) {
 
 // --- shared helpers ---------------------------------------------------------
 function dryText(plan) { return ['sawbuck --dry-run: would leave this footprint (writing nothing):', ...plan.map((p) => '  ' + p), '  all of it reversible with `detach`.'].join('\n'); }
-function warnNoConfig(repo) {
-  if (!existsSync(join(repo, 'promptwheel.config.json'))) {
-    out(`note: no promptwheel.config.json in ${repo}, the check needs one to know what to measure. Run: sawbuck init`);
-  }
+function warnNoConfig() {
+  // superseded by verifyAttach, which runs after every attach and reports exactly what the check
+  // can measure (zero-config now auto-detects your test command, so a missing config is not an error).
 }