sawbuck 0.1.19 → 0.1.21

package/CONTRACT.md

@@ -8,6 +8,8 @@ This is an open interface for making an AI coding harness trustworthy. It define
 
 The contract has one property that holds all of it together: a verdict is **deterministic and reproducible from `(base, head, config)` alone**. No LLM is in the path, and nothing is read from the agent's trajectory, so the result cannot be obfuscated against and does not change when you ask it twice.
 
+A corollary worth stating as an invariant: **the gate is defined only by in-repo, versioned config.** External systems (a dashboard, an issue tracker, a memory provider) may *report on* a verdict, but they must never *define* the guardrail. A guardrail that lives outside the repo is one the check cannot see in the diff, so it cannot be fingerprinted, so loosening it leaves no trace to catch as gamed. Memory (the input) is a pluggable socket; the gate (the output) stays in-repo and fingerprinted.
+
 > This contract covers the check. Sawbuck pairs it with the other half, **memory** (the relevant history for what you touch, plus the live debt), as the mirror idea: where the check is a standard others *conform to*, memory is a socket others *fill*. The default memory provider is @promptwheel/logbook, carried along so it works out of the box, but it is swappable; logbook is a default, not a requirement of the idea.
 >
 > Both halves nest with your folders, so policy and memory flow top-down and isolate across siblings. A parent `promptwheel.config.json` passes its guardrails down via `extends` (repos inherit the base gate; local metrics override by name), and memory inherits a parent folder's shared scope the same way (a repo sees itself and its ancestors, never a sibling). One model for both: the directory tree is the scope.

package/GLOSSARY.md

@@ -14,7 +14,7 @@ it is plain and scientific. The saddle is the brand and the architecture spine
 (the name, `attach`, `fit`); it is NOT a vocabulary for every concept.
 
 Why plain wins everywhere: an LLM has strong trained priors on words like
-`regression`, `verified`, `invalid`. Metaphor jargon in the model's context forces
+`regression`, `verified`, `gamed`. Metaphor jargon in the model's context forces
 a gloss every session (token cost) and risks a misread (trajectory drift). Plain,
 high-prior words serve the human reader and the agent equally, so we do not keep
 two vocabularies.
@@ -28,7 +28,7 @@ two vocabularies.
 | the verifier | **the check** (verb: *verify*) | runs the metrics on a change |
 | a change that improved and holds | **verified** | |
 | a change that made a guarded metric worse | **regression** | do-not-retry |
-| a change that passed by weakening its test | **invalid** | the test was weakened, not the metric improved (engine verdict: `gamed`) |
+| a change that passed by faking the metric | **gamed** | the win came from editing the test, config, or grader, not the source (the engine verdict, and the word every Sawbuck surface uses) |
 | the accumulated record of outcomes | **results** | `results.json` |
 | what Sawbuck leaves you | **verified history** | the findings you can trust |
 | a surfaced past outcome | **finding** | |
@@ -61,12 +61,13 @@ Findings are **leads, not conclusions**, verify against the diff before acting.
 ## Dispatch template
 
 ```
-Sawbuck · {N} regressions charted · {N} invalid changes caught
+Sawbuck · {N} regressions charted · {N} gamed changes caught
    🆕 just learned: {reason} ({file})
 ```
 
 ## Note on engine verdicts
 
-The check engine still emits its own verdicts (`gamed`, `fail`, `pass`); Sawbuck
-maps them to the plain outcome words above (`gamed` → **invalid**, `fail` →
-**regression**). Engine-internal names are not part of this surface.
+The check engine emits verdicts (`gamed`, `fail`, `pass`); the surface keeps **gamed**
+as-is (it is vivid and used on every surface) and maps `fail` → **regression** and
+`pass` → **verified**. ("Invalid" was an earlier softening of `gamed` that no surface
+adopted; `gamed` is canonical.)

package/README.md

@@ -48,6 +48,17 @@ sawbuck: gamed recorded on test.js       (the win came from editing the test, no
 | `sawbuck recall` | related notes for your current change from extra memory providers you compose in (bring your own) |
 | `sawbuck run --attempt '<agent cmd>'` | thin harness: load context, run one attempt through the keep-if-verified gate |
 | `sawbuck trace` · `sawbuck doctor` · `detach --verify` | show the footprint; check the attachment resolves; prove a clean removal |
+| `sawbuck where` · `sawbuck statusline` | list every repo it is attached to; a one-line status-line segment (🐴 watching / N caught) |
+
+## Give your agent the contract
+
+`sawbuck init` writes this block into your `AGENTS.md` for you (and `CLAUDE.md` / `.cursorrules` if present; `--no-agent-block` to skip), and `sawbuck attach --claude` enforces the same thing every turn via the hook. Here it is to paste yourself if you want:
+
+    This repo is under a Sawbuck contract: a change is done only when the win survives verification
+    from the source alone. Before finishing, run `sawbuck check`. If it reads `gamed`, the green came
+    from editing a test, config, or grader, not the source, so undo that and earn it in the source.
+    Run `sawbuck context` first to see what broke in these files before (reverts, weakened tests,
+    fragile spots). Never skip, weaken, or delete a test to go green.
 
 Each repo needs a `promptwheel.config.json` saying what to measure (your tests, lint, coverage, or an eval).
 
@@ -77,7 +88,7 @@ Debt also rises on its own: once attached, the per-turn `context` hook surfaces
 Sawbuck is thin glue over two roles, each behind an open interface that points in opposite directions:
 
 - **the check** : the deterministic outcome gate, a published standard (the [Verified-Outcome Contract](CONTRACT.md)) that others conform to. Reference implementation: **promptwheel**. You plug in *what* to measure (your tests, lint, coverage, an eval); the un-gameable source re-proof is the fixed part. Embed it with `import { check }`, or check any tool's verdict with `promptwheel conformance`.
-- **the memory** : the relevant history for the files you touch, plus the live debt. A socket you can fill. Default provider: **@promptwheel/logbook** (git history as agent memory; also ships an MCP server). Sawbuck reads it through one adapter, so you can *compose in your own* memory: `SAWBUCK_MEMORY=logbook,obsidian` keeps logbook as the git-truth + debt provider and adds your notes, then `sawbuck recall`. Two reference providers ship in `providers/`: **obsidian** (local notes, offline; set `OBSIDIAN_VAULT`) and **mem0** (semantic memory; the one that reaches the network, so it needs a `MEM0_API_KEY` or a `~/.mem0` key file, unlike the offline default; verified against Mem0's v3 API). Any bin that speaks the three contract verbs works; `sawbuck memory-conformance <bin>` checks one. Composed providers are **folder-scoped and isolated by default**: each repo sees only its own memory, never a sibling's. Drop a `.sawbuck-root` marker (or set `SAWBUCK_MEMORY_ROOT`) in a parent folder to let repos under it inherit that folder's shared memory, top down. logbook is the default, not a hard requirement of the idea.
+- **the memory** : the relevant history for the files you touch, plus the live debt. A socket you can fill. Default provider: **@promptwheel/logbook** (git history as agent memory; also ships an MCP server). Sawbuck reads it through one adapter, so you can *compose in your own* memory: `SAWBUCK_MEMORY=logbook,obsidian` keeps logbook as the git-truth + debt provider and adds your notes, then `sawbuck recall`. Four reference providers ship in `providers/`: **obsidian** (local notes vault; set `OBSIDIAN_VAULT`), **local** (a plain JSON file, zero setup), **claude** (read-only: your project's `CLAUDE.md` / `.claude` memory, already there, nothing to configure), and **mem0** (semantic memory; the one that reaches the network, so it needs a `MEM0_API_KEY` or a `~/.mem0` key file, unlike the offline default; verified against Mem0's v3 API). Any bin that speaks the three contract verbs works; `sawbuck memory-conformance <bin>` checks one. Composed providers are **folder-scoped and isolated by default**: each repo sees only its own memory, never a sibling's. Drop a `.sawbuck-root` marker (or set `SAWBUCK_MEMORY_ROOT`) in a parent folder to let repos under it inherit that folder's shared memory, top down. logbook is the default, not a hard requirement of the idea.
 
 In one line: the check is a standard we publish for others to meet; the memory is a socket we expose for others to fill. Sawbuck composes the two.
 

package/init.mjs

@@ -32,7 +32,7 @@ const engineBin = (envVar, pkgSubpath, devPath) => {
   for (const spec of [pkgSubpath, bare]) { try { return require.resolve(spec); } catch {} }
   return devPath;
 };
-const PW = engineBin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'referee', 'bin', 'promptwheel.mjs'));
+const PW = engineBin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'promptwheel', 'bin', 'promptwheel.mjs'));
 const LB = engineBin('LB_BIN', '@promptwheel/logbook/bin/logbook.mjs', join(HERE, '..', 'logbook', 'bin', 'logbook.mjs'));
 
 const argv = process.argv.slice(2);
@@ -44,6 +44,7 @@ const yes = has('--yes') || has('-y');
 const forceWizard = has('--wizard');
 const investigate = !has('--no-investigate');
 const force = has('--force');
+const noBlock = has('--no-agent-block');
 const presetIdx = argv.indexOf('--preset');
 const preset = presetIdx > -1 ? argv[presetIdx + 1] : null;
 
@@ -54,7 +55,9 @@ const prior = priorExisted ? readFileSync(cfgPath, 'utf8') : null;
 const restore = () => { try { if (prior != null) writeFileSync(cfgPath, prior); else if (existsSync(cfgPath)) unlinkSync(cfgPath); } catch {} };
 
 // 1) base contract from promptwheel init (stack-detected tests + antihack tripwires)
-const pwArgs = ['init', '--force'];
+// --no-agent-block: suppress promptwheel's own AGENTS.md gate block here; sawbuck writes its own
+// sawbuck-flavored contract block below, so the user does not get two overlapping agent guides.
+const pwArgs = ['init', '--force', '--no-agent-block'];
 if (preset) pwArgs.push('--preset', preset);
 try { execFileSync(process.execPath, [PW, ...pwArgs], { cwd: repo, stdio: 'ignore' }); }
 catch { restore(); out('sawbuck init: could not generate the base contract (promptwheel init failed).'); process.exit(1); }
@@ -115,8 +118,29 @@ function describeMetric(m) {
 
 function writeCfg() { writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n'); }
 
+// Write (or refresh) the agent-orienting contract block so a coding agent (or a loop not wired to the
+// `attach --claude` hook) knows the rules. AGENTS.md (the cross-tool convention; created if absent) +
+// CLAUDE.md / .cursorrules when present. Idempotent + safe: only the sentinel-delimited block is
+// touched. `--no-agent-block` skips it.
+function writeAgentBlock() {
+  const START = '<!-- sawbuck:contract -->', END = '<!-- /sawbuck:contract -->';
+  const block = `${START}\n## Sawbuck contract\n\nThis repo is under a Sawbuck contract: a change is done only when the win survives verification from the source alone. Before finishing, run \`sawbuck check\`. If it reads \`gamed\`, the green came from editing a test, config, or grader, not the source, so undo that and earn it in the source. Run \`sawbuck context\` first to see what broke in these files before (reverts, weakened tests, fragile spots). Never skip, weaken, or delete a test to go green.\n${END}\n`;
+  const targets = ['AGENTS.md', ...['CLAUDE.md', '.cursorrules'].filter((f) => existsSync(join(repo, f)))];
+  const done = [];
+  for (const f of targets) {
+    const p = join(repo, f);
+    let text = existsSync(p) ? readFileSync(p, 'utf8') : '';
+    const s = text.indexOf(START);
+    if (s > -1) { const e = text.indexOf(END, s); text = (e > -1 ? text.slice(0, s) + block + text.slice(e + END.length).replace(/^\n+/, '\n') : text.slice(0, s) + block); }
+    else { text = (text.trim() ? text.replace(/\n*$/, '\n\n') : '') + block; }
+    try { writeFileSync(p, text); done.push(f); } catch { /* best-effort */ }
+  }
+  return done;
+}
+
 function report() {
   out('sawbuck: wrote promptwheel.config.json');
+  if (!noBlock) { const w = writeAgentBlock(); if (w.length) out(`sawbuck: wrote the agent guide (the contract rules) to ${w.join(', ')}`); }
   out("\n  the contract (what a win must satisfy):");
   for (const m of cfg.metrics) out('    - ' + describeMetric(m));
   if (evidence) { out('\n  investigated this repo:'); for (const l of evidenceLines()) out(l); }

package/memory.mjs

@@ -31,7 +31,7 @@ function logbookBin() {
 }
 const envKey = (name) => 'SAWBUCK_MEMORY_' + name.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_BIN';
 // the ordered provider list. Each: { name, bin, dialect: 'logbook' | 'contract' }.
-const SHIPPED = new Set(['obsidian', 'mem0']); // reference contract providers that ship in providers/
+const SHIPPED = new Set(['obsidian', 'mem0', 'local', 'claude']); // reference contract providers that ship in providers/
 export function providers() {
   const spec = (process.env.SAWBUCK_MEMORY || 'logbook').split(',').map((s) => s.trim()).filter(Boolean);
   return spec.map((name) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "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",
@@ -30,6 +30,8 @@
     "memory.mjs",
     "providers/obsidian.mjs",
     "providers/mem0.mjs",
+    "providers/local.mjs",
+    "providers/claude.mjs",
     "run.mjs",
     "README.md",
     "GLOSSARY.md",

package/providers/claude.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// claude.mjs, a REFERENCE read-only memory provider: your project's Claude Code memory (CLAUDE.md,
+// AGENTS.md, and top-level .claude/*.md) as a recall source. It is the most UBIQUITOUS local memory -
+// a Claude Code repo already has it - so it is zero-setup. READ-ONLY by design: recall only; debt and
+// record EXIT NONZERO (unsupported). This is a view of memory you already keep, not a write target
+// (writing findings into CLAUDE.md would bloat the always-loaded project context), and the contract
+// lets a provider implement a subset. Inherently leaf-scoped (reads only this repo's files, so no
+// cross-repo leak). Zero-dep, offline, local-notes axis.
+//
+//   recall --file P [--file Q] --json   relevant lines from your project memory -> Finding[] (kind note)
+//   debt | record                        EXIT NONZERO (unsupported)
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const die = (m, c = 2) => { process.stderr.write(`claude provider: ${m}\n`); process.exit(c); };
+const CWD = process.cwd();
+
+if (cmd === 'debt' || cmd === 'record') die(`${cmd} is unsupported (claude memory is a read-only recall source)`, 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const matches = (l) => paths.find((p) => l.includes(p) || (basename(p).length > 2 && l.includes(basename(p)))) || null;
+  // the project's Claude Code memory: CLAUDE.md / AGENTS.md at the root, plus top-level .claude/*.md.
+  const sources = [];
+  for (const f of ['CLAUDE.md', 'AGENTS.md']) { const p = join(CWD, f); if (existsSync(p)) sources.push(p); }
+  try { for (const e of readdirSync(join(CWD, '.claude'))) if (extname(e).toLowerCase() === '.md') sources.push(join(CWD, '.claude', e)); } catch {}
+  const out = [];
+  for (const src of sources) {
+    let text = ''; try { if (statSync(src).size > 512 * 1024) continue; text = readFileSync(src, 'utf8'); } catch { continue; }
+    const lines = text.split('\n');
+    let heading = basename(src);
+    for (let i = 0; i < lines.length; i++) {
+      const h = lines[i].match(/^#{1,6}\s+(.+)/);
+      if (h) { heading = h[1].trim(); continue; }
+      const hit = matches(lines[i]);
+      if (!hit) continue;
+      out.push({ kind: 'note', path: hit, ref: `${basename(src)}:${i + 1}`, date: null, summary: `${heading}: ${lines[i].trim()}`.slice(0, 280), score: 0.4 });
+    }
+  }
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/local.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// local.mjs, a REFERENCE minimal local-file memory provider: the simplest way to fill the socket with
+// no external tool. Findings live as JSON in <repo>/.sawbuck/memory-notes.json (git-excluded by attach).
+// It is the cleanest conformance target and a "bring your own, just a file" option. Zero-dep, offline,
+// in the local-notes axis alongside obsidian. Folder-scoped like the others.
+//
+//   recall --file P [--scope ID ...] --json   -> Finding[] (kind note)
+//   record --ref SHA --summary S [--scope ID] [--side X] [--evidence-file F] --by WHO
+//   debt   --json                              EXITS NONZERO (a note store is not git-aware)
+//
+// Store: SAWBUCK_LOCAL_MEMORY, else <cwd>/.sawbuck/memory-notes.json.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const flag = (n, d) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? true) : d; };
+const die = (m, c = 2) => { process.stderr.write(`local provider: ${m}\n`); process.exit(c); };
+
+const STORE = process.env.SAWBUCK_LOCAL_MEMORY || join(process.cwd(), '.sawbuck', 'memory-notes.json');
+const load = () => { try { const v = JSON.parse(readFileSync(STORE, 'utf8')); return Array.isArray(v) ? v : []; } catch { return []; } };
+
+if (cmd === 'debt') die('debt is unsupported by a note store (git-truth lives in a git provider like logbook)', 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const scopes = new Set(flagAll('--scope'));            // self + ancestors; empty (direct call) = match any
+  const bases = paths.map((p) => basename(p));
+  const out = [];
+  for (const f of load()) {
+    if (scopes.size && f.scope != null && !scopes.has(f.scope)) continue;   // isolation: a sibling scope is excluded
+    const hit = (f.path && paths.includes(f.path)) || (f.summary && bases.some((b) => f.summary.includes(b)));
+    if (!hit) continue;
+    out.push({ kind: 'note', path: f.path ?? null, ref: f.ref ?? null, date: f.date ?? null, summary: String(f.summary || '').slice(0, 280), scope: f.scope ?? '', score: 0.5 });
+  }
+  out.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+if (cmd === 'record') {
+  const ref = String(flag('--ref', '')), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
+  const scope = flagAll('--scope')[0] ?? '';
+  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
+  const notes = load();
+  if (notes.some((f) => f.ref === ref && f.summary === summary && f.scope === scope)) { console.log('recorded (already present)'); process.exit(0); }
+  notes.push({ ref, summary, path: evidence || null, scope, by, ...(side ? { side: String(side) } : {}), date: new Date().toISOString().slice(0, 10) });
+  try { mkdirSync(dirname(STORE), { recursive: true }); writeFileSync(STORE, JSON.stringify(notes, null, 2) + '\n'); console.log('recorded'); process.exit(0); }
+  catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/obsidian.mjs

@@ -103,7 +103,16 @@ if (cmd === 'record') {
   // a [[wikilink]] to the evidence path so Obsidian's graph connects the finding to the code note.
   const link = evidence ? `\n- evidence: [[${String(evidence).replace(/[[\]]/g, '')}]]` : '';
   const body = `---\nsawbuck: finding\nref: ${ref}\nby: ${by}\ndate: ${date}\nscope: ${leaf}\n---\n\n# ${summary.slice(0, 80)}\n\n${summary}\n\n- ref: \`${ref}\`${side ? `\n- side: ${side}` : ''}${link}\n`;
-  try { writeFileSync(join(dir, `${safeRef}.md`), body); console.log('recorded'); process.exit(0); }
+  // no-clobber + dedupe: if this exact finding is already noted, skip; if a DIFFERENT note shares the
+  // ref, write a suffixed sibling instead of overwriting the earlier one.
+  let target = join(dir, `${safeRef}.md`);
+  if (existsSync(target)) {
+    let prev = ''; try { prev = readFileSync(target, 'utf8'); } catch {}
+    if (prev.includes(summary)) { console.log('recorded (already present)'); process.exit(0); }
+    let i = 2; while (existsSync(join(dir, `${safeRef}-${i}.md`))) i++;
+    target = join(dir, `${safeRef}-${i}.md`);
+  }
+  try { writeFileSync(target, body); console.log('recorded'); process.exit(0); }
   catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
 }
 

package/reflect.mjs

@@ -34,7 +34,7 @@ const engineBin = (envVar, pkgSubpath, devPath) => {
   for (const spec of [pkgSubpath, bare]) { try { return require.resolve(spec); } catch {} }
   return devPath;
 };
-const PW = engineBin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'referee', 'bin', 'promptwheel.mjs'));
+const PW = engineBin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'promptwheel', 'bin', 'promptwheel.mjs'));
 
 const flag = (name, def) => { const i = process.argv.indexOf(name); return i > -1 ? process.argv[i + 1] : def; };
 const repo = flag('--repo', process.cwd());

package/run.mjs

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 const bin = (envVar, pkg, dev) => { if (process.env[envVar]) return process.env[envVar]; const bare = pkg.replace(/\/bin\/[^/]*$/, ''); for (const s of [pkg, bare]) { try { return require.resolve(s); } catch {} } return dev; };
-const PW = bin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'referee', 'bin', 'promptwheel.mjs'));
+const PW = bin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'promptwheel', 'bin', 'promptwheel.mjs'));
 
 const arg = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 const repo = arg('--repo', process.cwd());

package/sawbuck.mjs

@@ -27,7 +27,7 @@ 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');
+  || join(HERE, '..', 'promptwheel', '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;
@@ -63,10 +63,11 @@ try { version = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8')).ver
 const help = `sawbuck ${version}: a saddle for your repo
 
 Usage:
-  sawbuck init [--yes] [--wizard] [--no-investigate]
+  sawbuck init [--yes] [--wizard] [--no-investigate] [--no-agent-block]
                             Generate the contract (promptwheel.config.json): a stack starter, tuned and
-                            explained by what your git history shows actually breaks. Wizard in a terminal,
-                            non-interactive in a pipe/CI/agent (or with --yes).
+                            explained by what your git history shows actually breaks. Also writes a short
+                            contract guide into AGENTS.md so your agent knows the rules (--no-agent-block
+                            to skip). Wizard in a terminal, non-interactive in a pipe/CI/agent (or --yes).
   sawbuck attach [repo]     Wire Sawbuck into a repo (default: a git post-commit hook)
       --claude              instead wire project Claude Code hooks (writes .claude/settings.local.json)
       --shared              with --claude, write the tracked .claude/settings.json (team-shared, visible in git)
@@ -125,8 +126,13 @@ switch (cmd) {
     // 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 ''; } };
+    // stderr ignored so a benign failing probe (e.g. rev-parse HEAD~1 on a one-commit repo) does not
+    // leak a scary "fatal:" line before sawbuck's own message.
+    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
     const dirty = g('status', '--porcelain').length > 0;
+    // nothing to verify yet: a clean tree with no previous commit to diff against (a fresh repo). Say so
+    // plainly instead of the generic "could not run" below, so the first run is not a dead end.
+    if (!dirty && !g('rev-parse', '--verify', 'HEAD~1')) { out('🐴 sawbuck: nothing to verify yet, the working tree is clean and this is the only commit. Make a change (or add one more commit), then `sawbuck check` re-proves the win from your source edits alone.'); process.exit(2); }
     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); }