sawbuck 0.1.20 → 0.1.21

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).
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.20",
+  "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",

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); }