sawbuck 0.1.20 → 0.1.22

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.22",
   "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",
@@ -28,6 +28,7 @@
     "debt.mjs",
     "status.mjs",
     "memory.mjs",
+    "yank.mjs",
     "providers/obsidian.mjs",
     "providers/mem0.mjs",
     "providers/local.mjs",

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

@@ -19,6 +19,7 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { recall as memRecall, conform as memConform } from './memory.mjs';
+import { tally, resolveSessionPath } from './yank.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
@@ -27,7 +28,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 +64,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)
@@ -97,6 +99,10 @@ Usage:
                             shows only the debt a branch adds; --fail-on exits nonzero for a CI gate
   sawbuck run --attempt '<cmd>' [--loops N]
                             Thin harness: load context, run one attempt through the keep-if-verified gate
+  sawbuck yank [--session <path>] [--json]
+                            The steering meter: how much you had to steer (yank the reins) this session,
+                            read from your Claude Code transcript. The check guards the turns you did not
+                            steer — a miss there is the risk. Yank rate falling = the reins getting looser.
   sawbuck --help | --version
 
 Rides two engines: promptwheel (the check) + @promptwheel/logbook (memory).`;
@@ -125,8 +131,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); }
@@ -258,11 +269,41 @@ switch (cmd) {
         const armed = existsSync(join(repo, 'promptwheel.config.json')) || existsSync(join(repo, 'package.json'));
         const mem = existsSync(join(repo, 'LOGBOOK.md')) || existsSync(join(repo, 'events.jsonl'));
         const seg = caught > 0 ? `🐴 sawbuck · ${caught} caught` : active ? `🐴 sawbuck · watching` : armed ? `🐴 sawbuck · ready` : mem ? `🐴 sawbuck · memory` : '';
-        if (seg) process.stdout.write(last ? `${seg} · ${last}` : seg);
+        const base = seg ? (last ? `${seg} · ${last}` : seg) : '';
+        // the live steering readout, when the wrapper forwards the session transcript path
+        let yk = '';
+        const ti = rest.findIndex((a) => a === '--transcript' || a === '--session');
+        if (ti > -1 && rest[ti + 1]) { try { const { yanks, turns } = tally(readFileSync(rest[ti + 1], 'utf8')); if (turns) yk = `🤠 ${yanks}/${turns} yanks`; } catch {} }
+        // live steering % from the reins engine's file (OFFLINE read; reins does the LLM work, never sawbuck)
+        let st = '';
+        try { const sj = JSON.parse(readFileSync(join(repo, '.sawbuck', 'steer.json'), 'utf8')); if (sj && sj.scored) st = `🤠 steer ${Math.round((sj.steeringRate || 0) * 100)}%`; } catch {}
+        const outp = [base, yk, st].filter(Boolean).join(' · ');
+        if (outp) process.stdout.write(outp);
       }
     } catch {}
     break;
   }
+  case 'yank': {
+    // the live steering meter (the reins hook): how much did you have to steer this session?
+    // A MIRROR read from the Claude Code transcript; the check guards the turns you did NOT steer.
+    const si = rest.findIndex((a) => a === '--session' || a === '--transcript');
+    const sess = resolveSessionPath(si > -1 ? rest[si + 1] : null, process.cwd());
+    if (!sess) { out('🐴 sawbuck: no session transcript found to read (pass --session <path.jsonl>).'); process.exit(2); }
+    let text = ''; try { text = readFileSync(sess, 'utf8'); } catch { out('🐴 sawbuck: could not read the session transcript.'); process.exit(2); }
+    const { turns, yanks, rate, recent } = tally(text);
+    if (flags.has('--json')) { out(JSON.stringify({ turns, yanks, rate, recent })); break; }
+    const pct = Math.round(rate * 100);
+    out('🐴 reins: steering this session');
+    if (yanks === 0) {
+      out(`   0 hard yanks across ${turns} turns — you did not have to pull the reins hard.`);
+    } else {
+      out(`   ${yanks} hard yank${yanks === 1 ? '' : 's'} across ${turns} turns (${pct}%) — times you pulled me back hard.`);
+      if (turns - yanks > 0) out(`   the check guards the other ${turns - yanks} turns you trusted me with — a miss there is the risk.`);
+      if (recent.length) out(`   recent: ${recent.map((r) => '"' + r + '"').join(' · ')}`);
+    }
+    out('   (terse course-corrections only; the full steer rate, incl. discursive redirects, is the harvest layer.)');
+    break;
+  }
   default: die(`unknown command '${cmd}'\n\n${help}`);
 }
 

package/yank.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// yank.mjs — the live steering meter (the "reins" hook). Reads the current Claude
+// Code session transcript and counts YANKS: turns where you corrected or redirected
+// the agent. Deterministic, zero-dep, with a transparent definition shown in the
+// output. It is a MIRROR — a number about how much you had to steer this session —
+// and it pairs with the check: the check guards the turns you did NOT steer, where
+// a miss is the real risk. The yank rate falling over time is the reins getting
+// looser (the agent learning your cues).
+//
+// A yank is counted CONSERVATIVELY (precision over recall): a human turn, after the
+// agent has acted, that OPENS by correcting or redirecting ("no", "don't",
+// "actually", "stop", "undo", "instead", ...). Discursive steers buried mid-
+// paragraph are deliberately NOT counted here — that is the LLM-harvest layer's job;
+// this stays cheap, instant, and honest (an undercount with a clear definition beats
+// an inflated guess).
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// leading correction/redirect markers at the START of the turn (case-insensitive)
+const LEAD = /^\s*["'(]?\s*(no\b|no,|nope\b|don'?t\b|do not\b|actually\b|wait\b|stop\b|undo\b|revert\b|instead\b|nah\b|hold on|rather\b|not (that|like|quite|what|really)|that'?s (not|wrong)|hmm,? ?no|why (did|are) you|you (shouldn'?t|weren'?t))/i;
+
+function humanText(o) {
+  if (!o || o.type !== 'user' || o.isMeta) return null;
+  if (o.userType && o.userType !== 'external') return null;
+  const c = o.message && o.message.content;
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) {
+    if (c.some((b) => b && b.type === 'tool_result')) return null;      // tool output, not you
+    const t = c.filter((b) => b && b.type === 'text').map((b) => b.text || '').join(' ');
+    return t || null;
+  }
+  return null;
+}
+const isNoise = (t) => {
+  const s = t.trim();
+  if (s.includes('<task-notification>') || s.startsWith('<task-id>')) return true; // injected
+  if (s.replace(/\[Image #\d+\]/g, '').trim().length < 3) return true;             // image-only
+  return false;
+};
+
+// tally(transcriptText) -> { turns, yanks, rate, recent } over YOUR typed turns.
+export function tally(text) {
+  let turns = 0, yanks = 0, seenHuman = false, prevAssistantActed = false;
+  const recent = [];
+  for (const line of String(text).split('\n')) {
+    if (!line.trim()) continue;
+    let o; try { o = JSON.parse(line); } catch { continue; }
+    if (o.type === 'assistant') { prevAssistantActed = true; continue; }
+    const t = humanText(o);
+    if (t === null || isNoise(t)) continue;
+    const opener = !seenHuman; seenHuman = true;
+    turns++;
+    if (!opener && prevAssistantActed && LEAD.test(t)) {
+      yanks++;
+      recent.push(t.replace(/\s+/g, ' ').trim().slice(0, 48));
+    }
+    prevAssistantActed = false;
+  }
+  return { turns, yanks, rate: turns ? yanks / turns : 0, recent: recent.slice(-5) };
+}
+
+// Resolve the newest session transcript for a cwd. Claude Code stores transcripts
+// under ~/.claude/projects/<encoded-cwd>/<id>.jsonl (path separators -> dashes).
+// Best-effort: prefer the dir matching this cwd, else the newest across all. Never throws.
+export function resolveSessionPath(explicit, cwd = process.cwd()) {
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const root = join(homedir(), '.claude', 'projects');
+  if (!existsSync(root)) return null;
+  const key = cwd.replace(/[^A-Za-z0-9]/g, '-');
+  let dirs = [];
+  try { dirs = readdirSync(root).map((d) => join(root, d)).filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } }); }
+  catch { return null; }
+  const matched = dirs.filter((p) => p.endsWith('/' + key));
+  const pool = matched.length ? matched : dirs;
+  let best = null, bestT = 0;
+  for (const full of pool) {
+    let files = []; try { files = readdirSync(full); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue;
+      const p = join(full, f);
+      try { const st = statSync(p); if (st.mtimeMs > bestT) { bestT = st.mtimeMs; best = p; } } catch {}
+    }
+  }
+  return best;
+}