sawbuck 0.1.43 → 0.1.44

package/README.md

@@ -70,7 +70,7 @@ Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `
 | `sawbuck debt` | the whole-repo live suppression debt: what is still silenced in HEAD now, disabled tests first, heaviest files ranked |
 | `sawbuck context` | the ranked relevant history for the current change |
 | `sawbuck trace` · `sawbuck doctor` · `detach --verify` | show the footprint; check the attachment resolves; prove a clean removal |
-| `sawbuck statusline` | a one-line status-line segment (🐴 watching / N caught / steer %) |
+| `sawbuck statusline` | a one-line status-line segment (🐴 watching / N caught) |
 
 ## Give your agent the contract
 
@@ -111,15 +111,13 @@ jobs:
 
 `--fail-on` takes `undocumented` (a bare `# type: ignore` / `# noqa` with no code), `test` (a newly disabled test), `any`, or a number of new suppressions. Exit 1 fails the check; add `--json` for the machine-readable delta. This repo is also a composite action: `uses: sawbuck-ai/sawbuck@v0` with `base` and `fail-on` inputs.
 
-Debt also rises on its own: once attached, the per-turn `context` hook surfaces the live suppression debt on the files your agent is touching when it is the suspect kind (undocumented, a disabled test, or on code that keeps breaking), so you do not have to run anything.
+Debt is on demand: `sawbuck debt`, and `sawbuck context` for the files in hand. To have history added to every turn, set `{"turn":{"context":true}}` in `sawbuck.config.json`. It is off by default because a written rule did the work in every bench, and context spent on each prompt is context lost.
 
 ## The engines
 
 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 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`. 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.
+- **the memory** : the relevant history for the files you touch, plus the live debt, from **@promptwheel/logbook** (git history as agent memory; also ships an MCP server).
 
 Apache 2.0.

package/agent-block.mjs

@@ -1,15 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
-
-// Your standing rules, one per line, kept in ~/.sawbuck/rules.md: the rules you picked from /sawbuck-reins:rules. Signing
-// carries them into each repo, so they follow you. They are your words, and they land in a file you review before committing.
-export function standingRules(home = homedir()) {
-  try {
-    return readFileSync(join(home, '.sawbuck', 'rules.md'), 'utf8').split('\n').map((l) => l.replace(/^[-*\s]+/, '').trim()).filter((l) => l && !l.startsWith('#') && l.length <= 200).slice(0, 30);
-  } catch { return []; }
-}
-
 // 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
@@ -17,16 +7,19 @@ export function standingRules(home = homedir()) {
 export function writeAgentBlock(repo) {
   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 \`npx -y 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 \`npx -y sawbuck context\` after your first edit 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 mine = standingRules();
-  const body = mine.length ? block.replace(END, `\n### Standing rules\n\n${mine.map((r) => `- ${r}`).join('\n')}\n${END}`) : block;
   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) + body + text.slice(e + END.length).replace(/^\n+/, '\n') : text.slice(0, s) + body); }
-    else { text = (text.trim() ? text.replace(/\n*$/, '\n\n') : '') + body; }
+    if (s > -1) {
+      const e = text.indexOf(END, s);
+      // a section someone wrote inside the block stays: this refreshes our paragraph, never their words
+      const kept = e > -1 ? (text.slice(s, e).match(/\n### Standing rules[\s\S]*$/) || [''])[0].replace(/\n+$/, '\n') : '';
+      const body = kept ? block.replace(END, `${kept}${END}`) : block;
+      text = e > -1 ? text.slice(0, s) + body + text.slice(e + END.length).replace(/^\n+/, '\n') : text.slice(0, s) + body;
+    } else text = (text.trim() ? text.replace(/\n*$/, '\n\n') : '') + block;
     try { writeFileSync(p, text); done.push(f); } catch { /* best-effort */ }
   }
   return done;

package/contract-cmd.mjs

@@ -4,7 +4,7 @@
 // lock. Zero-LLM. Re-running changes nothing. Protected product code (auth, billing) is suggested, never added:
 // freezing those is a person's decision.
 import { ensureExcluded } from './exclude.mjs';
-import { writeAgentBlock, standingRules } from './agent-block.mjs';
+import { writeAgentBlock } from './agent-block.mjs';
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, cpSync, mkdirSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
@@ -86,7 +86,7 @@ try {
     const locked = existsSync(join(repo, 'promptwheel.lock.json'));
     if (!locked) run([join(pack, 'lock.mjs'), 'write', repo], repo);
     const added = (cfg.mandates.length - before.m) + (cfg.metrics.length - before.g);
-    process.stdout.write(added || !locked ? `sawbuck: signed. ${cfg.metrics.length} guards, ${cfg.mandates.length} protected-path rules, and the shape of this repo in promptwheel.lock.json.\n${strict ? '' : '  New dependencies and structure changes show as notes for now; protected paths and install scripts block. --strict blocks them all.\n'}${standingRules().length ? `  Added your ${standingRules().length} standing rules from ~/.sawbuck/rules.md to AGENTS.md.\n` : ''}${ci ? '  Added .github/workflows/sawbuck.yml, so pull requests are checked in CI. Commit it with the contract.\n' : ''}` : 'sawbuck: already signed, nothing changed.\n');
+    process.stdout.write(added || !locked ? `sawbuck: signed. ${cfg.metrics.length} guards, ${cfg.mandates.length} protected-path rules, and the shape of this repo in promptwheel.lock.json.\n${strict ? '' : '  New dependencies and structure changes show as notes for now; protected paths and install scripts block. --strict blocks them all.\n'}${ci ? '  Added .github/workflows/sawbuck.yml, so pull requests are checked in CI. Commit it with the contract.\n' : ''}` : 'sawbuck: already signed, nothing changed.\n');
   }
 } finally { rmSync(scratch, { recursive: true, force: true }); }
 

package/exclude.mjs

@@ -7,20 +7,26 @@ const sh = (r, ...a) => { try { return execFileSync('git', ['-C', r, ...a], { en
 
 export const RECORD_DIRS = ['.sawbuck/', '.promptwheel/*', '!.promptwheel/packs/', 'events.jsonl', 'annotations.jsonl', 'annotation-reviews.jsonl', 'decision-cards.jsonl', 'LOGBOOK.md', 'JOURNEY.md'];
 
-export function ensureExcluded(r) {
+// everything the block hides, under any attach mode
+export const EXCLUDED = [...RECORD_DIRS, '.claude/settings.local.json'];
+
+// The one writer of the block, in the repository's own exclude file wherever its git dir is (a worktree or
+// submodule keeps it elsewhere). Rewrites to the current set, so a grown set retrofits existing repos; no lines
+// strips it. Returns whether the file changed.
+function writeBlock(r, lines) {
   try {
-    // the repository's own exclude file, wherever its git dir is (a worktree or submodule keeps it elsewhere)
     const rel = sh(r, 'rev-parse', '--git-path', 'info/exclude');
-    if (!rel) return;
+    if (!rel) return false;
     const f = resolve(r, rel);
-    // the record dirs + the logbook's root ledger cache (events.jsonl). Rewrite the block to
-    // the CURRENT set rather than bail on presence, so a grown set retrofits existing repos.
-    const WANT = `# >>> sawbuck >>>\n${[...RECORD_DIRS, '.claude/settings.local.json'].join('\n')}\n# <<< sawbuck <<<\n`;
     const body = existsSync(f) ? readFileSync(f, 'utf8') : '';
     const stripped = body.replace(/# >>> sawbuck >>>[\s\S]*?# <<< sawbuck <<<\n?/g, '');
-    const next = (stripped && !stripped.endsWith('\n') ? stripped + '\n' : stripped) + WANT;
-    if (next === body) return;
+    const block = lines.length ? `# >>> sawbuck >>>\n${lines.join('\n')}\n# <<< sawbuck <<<\n` : '';
+    const next = (block && stripped && !stripped.endsWith('\n') ? stripped + '\n' : stripped) + block;
+    if (next === body) return false;
     mkdirSync(dirname(f), { recursive: true });
     writeFileSync(f, next);
-  } catch {}
+    return true;
+  } catch { return false; }
 }
+export const ensureExcluded = (r) => writeBlock(r, EXCLUDED);
+export const clearExcluded = (r) => writeBlock(r, []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Sign your agent to a contract: a deterministic, zero-LLM check re-proves each win from the agent's source edits alone, so a test that went green by editing the test, grader, or config is sent back. For Claude Code, with Codex untested.",
   "type": "module",
   "license": "Apache-2.0",
@@ -46,6 +46,7 @@
     "exposure.mjs",
     "agent-block.mjs",
     "exclude.mjs",
+    "repo-state.mjs",
     "contract-cmd.mjs",
     "bins.mjs",
     "contract.mjs",

package/repo-state.mjs

@@ -0,0 +1,22 @@
+// One read of what Sawbuck has here, shared by the statusline and `sawbuck status`. Files only, no git and no model.
+// state: watching (wired in), ready (checkable, not wired yet), memory (history only), or empty.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const WEEK = 7 * 864e5;
+
+export function repoState(repo) {
+  const record = (f) => { try { return JSON.parse(readFileSync(join(repo, '.sawbuck', f), 'utf8')); } catch { return null; } };
+  const has = (f) => existsSync(join(repo, f));
+  const results = record('results.json') || {};
+  const caught = (results.regressions || 0) + (results.gamed || 0) + (results.mandates || 0);
+  const hasConfig = has('promptwheel.config.json');
+  const armed = hasConfig || has('package.json');
+  const state = has('.sawbuck/state.json') ? 'watching' : armed ? 'ready' : (has('LOGBOOK.md') || has('events.jsonl')) ? 'memory' : '';
+  // the reins engine's file; reins does the model work, never sawbuck. A rate nobody has updated for a week is
+  // history, not a reading, and the judge is off unless someone turned it on.
+  const s = record('steer.json');
+  const live = s && s.scored && !(s.at && Date.now() - Date.parse(s.at) > WEEK);
+  const steer = live ? { rate: Math.round(((s.ema != null ? s.ema : s.steeringRate) || 0) * 100), scored: s.scored } : null;
+  return { results, caught, hasConfig, armed, state, steer };
+}

package/sawbuck-hook.mjs

@@ -72,6 +72,20 @@ st.turns += 1;
 // 2) the record of what the check has charted (read above, after any re-run)
 const total = rec ? (rec.regressions || 0) + (rec.gamed || 0) + (rec.mandates || 0) : 0;
 const saveState = () => { try { mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n'); } catch {} };
+// the budget is per prompt: prompt_id when the harness sends one, else the prompt's own timestamp (written by
+// `sawbuck turn --hook`), never a constant that would spend it for good
+const promptId = hookInput.prompt_id || st.lastPromptAt || 'none';
+// Send the turn back, at most enforce.maxBlocks times per prompt, then let it end with a warning: it can never
+// loop, because the harness's own block cap resets on every tool call.
+const sendBack = (idKey, countKey, reason, stillOpen) => {
+  const max = +(cfg.enforce?.maxBlocks) || 3;
+  if (st[idKey] !== promptId) { st[idKey] = promptId; st[countKey] = 0; }
+  const spent = (st[countKey] || 0) >= max;
+  if (!spent) st[countKey] = (st[countKey] || 0) + 1;
+  saveState();
+  process.stdout.write(JSON.stringify(spent ? { systemMessage: `Sawbuck stopped blocking after ${max} tries: ${stillOpen}` } : { decision: 'block', reason }));
+  process.exit(0);
+};
 
 // 2b) THE WALL AT TURN LEVEL (Claude Code Stop hook only): a mandate is checked against the WORKING
 // tree on every stop, not only on commits, because an agent usually ends a turn with uncommitted
@@ -112,11 +126,6 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
   } else if (st.lastViolation) { delete st.lastViolation; }
   saveState();
   if (hits.length) {
-    const MAX_BLOCKS = +(cfg.enforce?.maxBlocks) || 3;
-    // the budget is per prompt: prompt_id when the harness sends one, else the prompt's own timestamp
-    // (written by `sawbuck turn --hook`), never a constant that would spend the budget for good
-    const promptId = hookInput.prompt_id || st.lastPromptAt || 'none';
-    if (st.mandatePromptId !== promptId) { st.mandatePromptId = promptId; st.mandateBlocks = 0; }
     const desc = hits.map((h) => `"${h.name}"${h.reason ? ' (' + h.reason + ')' : ''}: ${h.files.join(', ')}${h.committed ? ' [this rule is in the committed contract; editing promptwheel.config.json in the working tree does not lift it]' : ''}`).join('; ');
     const spared = leftAlone.length ? ` Edits that were already there before this prompt were left out of this check and must stay as they are: ${leftAlone.join(', ')}.` : '';
     const before = (st.lastViolation && st.lastViolation.before) || {};
@@ -134,15 +143,7 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
       writeRec(r);
       logActivity({ kind: 'mandate', file: hits[0].files[0], reason: `mandate ${hits[0].name} violated in the working tree`, by: by || 'hook' });
     }
-    if ((st.mandateBlocks || 0) < MAX_BLOCKS) {
-      st.mandateBlocks = (st.mandateBlocks || 0) + 1;
-      saveState();
-      process.stdout.write(JSON.stringify({ decision: 'block', reason: `Sawbuck: a protected path in the contract was touched, the turn is not done. Protected paths changed in this turn: ${desc}. Undo the changes YOU made under the protected paths and make the fix elsewhere; do not revert anything you did not change (the rule is a wall, not a reminder; the gate fails any change that touches them).${spared}${restore}${accept}${upgrade}` }));
-      process.exit(0);
-    }
-    saveState();
-    process.stdout.write(JSON.stringify({ systemMessage: `Sawbuck stopped blocking after ${MAX_BLOCKS} tries: protected paths are still changed (${desc}).` }));
-    process.exit(0);
+    sendBack('mandatePromptId', 'mandateBlocks', `Sawbuck: a protected path in the contract was touched, the turn is not done. Protected paths changed in this turn: ${desc}. Undo the changes YOU made under the protected paths and make the fix elsewhere; do not revert anything you did not change (the rule is a wall, not a reminder; the gate fails any change that touches them).${spared}${restore}${accept}${upgrade}`, `protected paths are still changed (${desc}).`);
   }
 }
 
@@ -152,21 +153,9 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
 // 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 || st.lastPromptAt || '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);
+  sendBack('blockPromptId', 'blockCount', `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.`, `the win on ${where} is still gamed and needs a real source fix.`);
 }
 
 // 3b) THE LOCK AT TURN LEVEL: tell the person the moment a turn changes the repo's structure or its resolved

package/sawbuck.mjs

@@ -13,11 +13,12 @@
 // proves the repo came back clean; `doctor` checks the attachment still resolves.
 
 import { execFileSync } from 'node:child_process';
-import { erasedBlock } from './rewrites.mjs';
+import { erasedBlock, erasedCommits } from './rewrites.mjs';
 import { steersReport } from './steers.mjs';
 import { rulesCli } from './rules.mjs';
 import { shapeCli } from './shape.mjs';
-import { ensureExcluded, RECORD_DIRS } from './exclude.mjs';
+import { ensureExcluded, clearExcluded, EXCLUDED, RECORD_DIRS } from './exclude.mjs';
+import { repoState } from './repo-state.mjs';
 import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, unlinkSync, rmdirSync, rmSync, readdirSync } from 'node:fs';
 import { basename, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -73,11 +74,9 @@ Usage:
                             Customize the contract (promptwheel.config.json), with notes from what your
                             git history shows actually breaks, plus a short contract guide in AGENTS.md
                             (--no-agent-block to skip). Wizard in a terminal, non-interactive in a pipe/CI (or --yes).
-  sawbuck attach [repo]     Enforce the contract on every commit (a git post-commit hook)
-      --claude              instead on every Claude Code turn (project hooks in .claude/settings.local.json)
-      --shared              with --claude, write the tracked .claude/settings.json (team-shared, visible in git)
-      --user                user-level Claude hooks that follow your cwd (attach once, every project)
-      --dry-run             print the exact footprint it would leave, and write nothing
+  sawbuck attach --claude   Check every Claude Code turn in this repo. --dry-run prints the footprint and writes nothing
+                            Also: no flag for a git post-commit hook, --claude --shared for a tracked settings file,
+                            --user for every repo
   sawbuck detach [repo] [--claude | --user] [--all] [--verify] [--purge]
                             Remove it and restore the repo (no flag: whatever is attached here); --verify
                             proves it came back clean; --purge also deletes the record (.sawbuck/)
@@ -89,7 +88,7 @@ Usage:
   sawbuck context [repo]    Relevant history for the files you are changing (reverts, weakened tests, hot spots)
   sawbuck frame [repo]      The contract's protected paths, inherited ones included, as one compact block;
                             silent without a contract (--speak explains)
-  sawbuck turn [repo]       frame + context in one block: what attach --claude runs on every prompt
+  sawbuck turn [repo]       What attach --claude runs on a prompt: the frame, once a session and after a compaction
 
   sawbuck trace [repo]      Show every file Sawbuck has placed in this repo (the footprint)
   sawbuck doctor [repo]     Check the attachment still resolves to a live sawbuck; --all for every repo
@@ -98,14 +97,10 @@ Usage:
   sawbuck rules --prepare   Gather your messages on this machine so an agent can propose the rules you never wrote
   sawbuck rules --check F   Keep only proposed rules with 2 quotes that are really yours
   sawbuck shape --prepare   Gather a sample of your messages so an agent can label what you push on
-  sawbuck shape --check F   Draw your steering shape from the labels, keeping only the totals
+  sawbuck shape --check F   Draw your steering shape from the labels, keeping only the totals (--png for an image)
   sawbuck steers            What you keep correcting, from the plugin's scratchpad on this machine (--json)
-  sawbuck statusline        One-line segment for your status line (🐴 watching | N caught | steer %)
+  sawbuck statusline        One-line segment for your status line (🐴 watching | N caught)
 
-  sawbuck recall [repo]     Related notes for your changes from extra memory providers
-                            (SAWBUCK_MEMORY=logbook,obsidian + OBSIDIAN_VAULT), alongside context
-  sawbuck memory-conformance <bin>
-                            Check a provider bin speaks the Memory Contract (recall/debt/record)
   sawbuck --help | --version
 
 Engines: promptwheel (the check) + @promptwheel/logbook (memory). Zero-LLM, offline, free.`;
@@ -241,9 +236,10 @@ switch (cmd) {
     break;
   }
   case 'turn': {
-    // the ONE per-prompt hook: the contract frame (forward: what must hold) and the relevant history
-    // (backward: what broke here before) in a single block, one process per prompt. Silent when
-    // there is nothing to say. Wired by `attach --claude` on UserPromptSubmit and after a compaction.
+    // the ONE per-prompt hook. The agent gets the contract frame once a session and again after a compaction: one
+    // written statement held in every bench, so saying it on each prompt only spends context. The relevant history
+    // is on demand (`sawbuck context`), and per turn only with {"turn":{"context":true}} in sawbuck.config.json.
+    // Wired by `attach --claude` on UserPromptSubmit and after a compaction.
     // the repository the way the Stop hook sees it: the root of the cwd under user-level wiring (a
     // subdirectory belongs to its repo), the pinned path under project wiring; '' outside a repo
     const top = gitTop(repoArg());
@@ -258,8 +254,8 @@ switch (cmd) {
     // a file still carrying the content the last violation flagged is never baselined; and the
     // baseline's commit does not advance past a flagged commit until a clean stop or a commit the
     // person made between turns that no longer carries the flagged content.
-    let hookEvent = '';
-    if (flags.has('--hook') && !process.stdin.isTTY) { try { hookEvent = String(JSON.parse(readFileSync(0, 'utf8') || '{}').hook_event_name || ''); } catch {} }
+    let hookEvent = '', session = '', framed = false;
+    if (flags.has('--hook') && !process.stdin.isTTY) { try { const h = JSON.parse(readFileSync(0, 'utf8') || '{}'); hookEvent = String(h.hook_event_name || ''); session = String(h.session_id || ''); } catch {} }
     if (hookEvent === 'UserPromptSubmit' && top) {
       try {
         ensureExcluded(repo);   // before the first write: under user-level hooks nothing else has done it yet
@@ -290,11 +286,16 @@ switch (cmd) {
             st.turnBaseline = { at: now, sha: ((!moved || stillInHead) && pin && st.lastViolation.sha) || sha, files, lock: lockState(repo), rules: mandatesInForce(repo) };
           }
         }
+        framed = !!session && st.framedSession === session;
+        if (session) st.framedSession = session;
         st.lastPromptAt = now;   // every prompt, mandates or not: the walls key their block budgets on it when the harness sends no prompt_id
         mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
       } catch { /* the frame never fails a prompt */ }
     }
-    const o = [frameBlock(repo), contextBlock(repo, false)].filter(Boolean).join('\n');
+    let history = false;
+    try { history = JSON.parse(readFileSync(join(repo, 'sawbuck.config.json'), 'utf8')).turn?.context === true; } catch {}
+    if (!history && top) erasedCommits(repo);   // the ledger outlives the reflog whether or not it is printed
+    const o = [framed ? '' : frameBlock(repo), history ? contextBlock(repo, false) : ''].filter(Boolean).join('\n');
     if (o) out(o);
     break;
   }
@@ -370,22 +371,16 @@ switch (cmd) {
       if (!repo) process.stdout.write('🐴 sawbuck · no repo here');
       if (repo) {
         const name = basename(repo);
-        let caught = 0;
-        try { const r = JSON.parse(readFileSync(join(repo, '.sawbuck', 'results.json'), 'utf8')); caught = (r.regressions || 0) + (r.gamed || 0) + (r.mandates || 0); } catch {}
+        const { caught, state, steer } = repoState(repo);
         // 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: '≈', allowed: '✎' }[e.kind] || ''; } catch {}
-        // one state model, shared with the Reins band: watching (wired in) / ready (checkable, not wired yet) / memory (history only)
-        const active = existsSync(join(repo, '.sawbuck', 'state.json'));
-        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 label = caught > 0 ? `${caught} caught` : active ? 'watching' : armed ? 'ready' : mem ? 'memory' : '';
+        const label = caught > 0 ? `${caught} caught` : state;
         const seg = label ? `🐴 sawbuck · ${label}` : '';
         const named = label ? `🐴 sawbuck · ${name} · ${label}` : '';   // which repo it detected, in the default line
         const base = named ? (last ? `${named} · ${last}` : named) : '';
         // 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) { const p = Math.round(((sj.ema != null ? sj.ema : sj.steeringRate) || 0) * 100); st = `${p >= 50 ? '✊' : '🐎'} steer ${p}%`; } } catch {}
+        const st = steer ? `${steer.rate >= 50 ? '✊' : '🐎'} steer ${steer.rate}%` : '';
         // configurable template: SAWBUCK_STATUSLINE picks which segments show and in what order
         // (tokens {status} {sawbuck} {repo} {verdict} {steer} plus any literal text); empty tokens collapse
         // so you never get a dangling separator. Unset = the default composition. Mix in other
@@ -407,7 +402,7 @@ switch (cmd) {
   default: die(`unknown command '${cmd}'\n\n${help}`);
 }
 
-// --- the per-turn block: frame (forward, from contract.mjs) + context (backward) ---------------
+// --- context: the ranked history for the files in hand, on demand ---------------------------
 // the read face: ranked relevant history for what you're working on right now. Silent when there is
 // nothing to say, so it is safe on every UserPromptSubmit (that hook's stdout is injected into context;
 // "nothing notable" every turn would be noise). `speak` forces a reply for the explicit command.
@@ -456,26 +451,9 @@ function delFile(p) { try { if (existsSync(p)) unlinkSync(p); } catch {} }
 function rmIfEmptyDir(d) { try { if (existsSync(d) && readdirSync(d).length === 0) rmdirSync(d); } catch {} }
 
 // --- .git/info/exclude: keep the worktree clean without touching .gitignore --
-// Rewrites a single marked block to the union of excludes the current
-// attachments need. Never deletes the file (an empty one is git's own default).
+// Any attachment keeps the block, the last one out takes it. Returns whether the file changed.
 function excludeFile(repo) { return gitPath(repo, 'info/exclude'); }
-function syncExclude(repo, manifest) {
-  const need = new Set();
-  const a = manifest.attachments || {};
-  if (Object.keys(a).length) for (const d of RECORD_DIRS) need.add(d);     // any attach → the check may write the record dirs
-  if (a.claude) need.add('.claude/settings.local.json');                    // default claude settings are local; hide them too
-  const lines = [...need];
-  const f = excludeFile(repo);
-  let body = (existsSync(f) ? readFileSync(f, 'utf8') : '').replace(BLOCK_RE, '\n').replace(/\n{3,}/g, '\n\n');
-  if (lines.length) {
-    if (body && !body.endsWith('\n')) body += '\n';
-    body += `${S_START}\n${lines.join('\n')}\n${S_END}\n`;
-    mkdirSync(dirname(f), { recursive: true });
-    writeFileSync(f, body);
-  } else if (existsSync(f)) {
-    writeFileSync(f, body);                                                 // strip our block, leave the rest
-  }
-}
+function syncExclude(repo, manifest) { return Object.keys(manifest.attachments || {}).length ? ensureExcluded(repo) : clearExcluded(repo); }
 
 // --- git post-commit --------------------------------------------------------
 // The hook prefers a `sawbuck` on PATH (so it survives a reinstall/upgrade) and
@@ -498,7 +476,7 @@ function wireGit(repo) {
   if (dry) {
     out(dryText([
       `${existed ? 'modify' : 'create'}  ${pc}  (post-commit hook block)`,
-      `exclude ${excludeFile(repo)}  (${RECORD_DIRS.join(', ')})`,
+      `exclude ${excludeFile(repo)}  (${EXCLUDED.join(', ')})`,
       `create  ${manifestPath(repo)}  (attach receipt)`,
     ]));
     return;
@@ -516,7 +494,8 @@ function unwireGit(repo) {
   const pc = gitPath(repo, 'hooks/post-commit');
   const m = readManifest(manifestPath(repo));
   const hasReceipt = !!m.attachments?.git;
-  if (!existsSync(pc) && !hasReceipt) { out('sawbuck: nothing to detach'); return; }
+  // signing with no attach still hides the record, so a repo with no receipt can have a block to take back
+  if (!existsSync(pc) && !hasReceipt) { out(syncExclude(repo, m) ? `sawbuck: removed the record lines from ${excludeFile(repo)}` : 'sawbuck: nothing to detach'); return; }
   if (existsSync(pc)) {
     const stripped = readFileSync(pc, 'utf8').replace(BLOCK_RE, '\n').replace(/\n{3,}/g, '\n\n');
     const created = m.attachments?.git?.pc?.created;
@@ -578,7 +557,7 @@ function wireClaude(repo, opts) {
   if (dry) {
     out(dryText([
       `${upgrading ? 'update' : fileExisted ? 'modify' : 'create'}  ${f}  (UserPromptSubmit + SessionStart[compact] + Stop hooks: the per-turn block, and the check)`,
-      user ? null : `exclude ${excludeFile(repo)}  (${RECORD_DIRS.join(', ')}${shared ? '' : ', .claude/settings.local.json'})`,
+      user ? null : `exclude ${excludeFile(repo)}  (${EXCLUDED.join(', ')})`,
       `create  ${user ? userManifestPath() : manifestPath(repo)}  (attach receipt)`,
     ].filter(Boolean)));
     return;
@@ -589,8 +568,8 @@ function wireClaude(repo, opts) {
     cfg.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command }] });
   };
   put('UserPromptSubmit', ctx);
-  // right after a compaction the summary has just dropped detail: re-impress the contract frame and the
-  // relevant history there too (SessionStart with the `compact` source injects stdout into context).
+  // right after a compaction the summary has just dropped detail: re-impress the contract frame there too
+  // (SessionStart with the `compact` source injects stdout into context).
   put('SessionStart', ctx, 'compact');
   put('Stop', chk);
   mkdirSync(dir, { recursive: true });

package/shape.mjs

@@ -1,8 +1,9 @@
 // Your steering shape: what you push on, as 12 spokes in 4 groups. The model labels a sample of your messages; only the
 // totals are kept. Two models agree on single messages about half the time and on the shape at 0.93, so a single label is
 // never shown. It says what you pushed on, not how good you are. Each run is saved with its date to compare later.
-import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, rmSync, copyFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { prepareRules } from './rules.mjs';
 import { exposure, writtenRules } from './exposure.mjs';
@@ -39,6 +40,7 @@ export function tally(labels) {
 }
 
 // What was not said: each spoke we can measure from what the agent did, read against how often you push on it.
+const MIN_TURNS = 30;   // a pattern needs enough turns behind it: 1 of 3 is not one
 const HIGH_PUSH = 8, HIGH_DOING = 10, HIGH_FAULT = 5;   // a fault counts sooner than plain activity
 const SEEN = {
   proof: { fault: true, of: 'code', n: 'unverified', says: 'changed code and ran no check within 3 turns', rule: 'Run the tests before saying a change works.' },
@@ -57,7 +59,8 @@ export function patterns(t, c) {
     const push = t.shares[s], often = pct >= (m.fault ? HIGH_FAULT : HIGH_DOING), pushed = push >= HIGH_PUSH;
     // a fault you keep raising is a fight; activity you raise is just attention, since committing is not a failure
     const has = !!(c.written && c.written[s]);
-    const kind = often && pushed ? (m.fault ? 'fighting it' : 'watched') : often ? (has ? 'covered' : 'blind spot') : pushed ? 'handled' : 'quiet';
+    const enough = c[m.of] >= MIN_TURNS;
+    const kind = !enough ? 'too few' : often && pushed ? (m.fault ? 'fighting it' : 'watched') : often ? (has ? 'covered' : 'blind spot') : pushed ? 'handled' : 'quiet';
     return { spoke: s, kind, pct, count: c[m.n] || 0, of: c[m.of], push, says: m.says, rule: m.rule, has };
   });
 }
@@ -74,6 +77,25 @@ export function shapeSvg(t, found = []) {
   return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 1000" font-family="system-ui,sans-serif"><rect width="1000" height="1000" fill="#0b0e13"/><text x="50" y="70" fill="#e8e6e1" font-size="40" font-weight="700">My steering shape</text>${[0.25, 0.5, 0.75, 1].map((v) => `<polygon points="${ring(v)}" fill="none" stroke="#2a313b"/>`).join('')}<polygon points="${names.map((_, i) => pt(i, vals[i]).join(',')).join(' ')}" fill="#c9a24a" fill-opacity="0.35" stroke="#c9a24a" stroke-width="4"/>${seenPts.map(([x, y]) => `<circle cx="${x}" cy="${y}" r="9" fill="#4fb3a5"/>`).join('')}${labels}<text x="50" y="960" fill="#8d94a0" font-size="19">Gold: what I push on, from ${t.n} messages.${seenPts.length ? ' Teal dots: what the agent did.' : ''} Relative to my own top. Not a score. sawbuck.ai</text></svg>\n`;
 }
 
+// A PNG of the card, with what is already on the machine: sawbuck ships no image library. A snap browser sees neither
+// a hidden folder nor the real /tmp, so it works in a plain folder in home and the result is copied over.
+function pngCard(svg) {
+  const png = svg.replace(/\.svg$/, '.png');
+  rmSync(png, { force: true });
+  const run = (bin, args) => { try { execFileSync(bin, args, { stdio: 'ignore', timeout: 30000 }); return true; } catch { return false; } };
+  if (run('rsvg-convert', ['-w', '1200', '-o', png, svg]) && existsSync(png)) return png;
+  const tmp = join(dirname(dirname(svg)), `sawbuck-shape-${process.pid}`);
+  try {
+    mkdirSync(tmp, { recursive: true });
+    const a = join(tmp, 'shape.svg'), b = join(tmp, 'shape.png');
+    copyFileSync(svg, a);
+    for (const bin of ['google-chrome', 'chromium', 'chromium-browser']) {
+      if (run(bin, ['--headless', '--disable-gpu', '--hide-scrollbars', '--window-size=1000,1000', `--screenshot=${b}`, `file://${a}`]) && existsSync(b)) { copyFileSync(b, png); return png; }
+    }
+  } catch {} finally { rmSync(tmp, { recursive: true, force: true }); }
+  return '';
+}
+
 export function shapeCli(args, { home = homedir() } = {}) {
   if (args.includes('--prepare')) { const r = prepareShape({ home }); return `🐴 ${r.lines} of your messages are ready in ${r.input}${r.secrets ? `, ${r.secrets} that looked like secrets left out` : ''}.`; }
   const i = args.indexOf('--check');
@@ -104,7 +126,9 @@ export function shapeCli(args, { home = homedir() } = {}) {
   for (const f of blind) out.push(`    Not said: ${title(f.spoke)}. The agent ${f.says} in ${f.pct}% of turns (${f.count} of ${f.of}), and only ${f.push}% of your pushes touch it. Is that what you want?`, `      Try: ${f.rule}`);
   const covered = found.filter((f) => f.kind === 'covered');
   if (covered.length) out.push('', `  Written down already, so left out: ${covered.map((f) => title(f.spoke)).join(', ')}. Matched by keyword, so check they say what you mean.`);
+  if (found.some((f) => f.kind === 'too few')) out.push('', `  Not enough recent turns to name every pattern yet: each needs ${MIN_TURNS}.`);
   if (found.length) out.push('', '  What the agent did covers your last 90 days, not counting scratch work. Direction, scope, correctness and honesty have no behaviour signal, so they show only what you said.');
   out.push('', `  Card: ${p.svg}`);
+  if (args.includes('--png')) { const png = pngCard(p.svg); out.push(png ? `  Image to share: ${png}` : '  No image tool here (rsvg-convert or Chrome): open the card in a browser to save an image.'); }
   return out.join('\n');
 }

package/status.mjs

@@ -12,6 +12,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { repoState } from './repo-state.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? (process.argv[i + 1] ?? true) : d; };
@@ -27,26 +28,19 @@ const ICON = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive:
 // --- 1) the outcome record: what the check has done here -------------------
 // results.json holds the all-time catch tally (gamed + regression, never trimmed); activity.jsonl is
 // the recent per-check feed (verified included, capped ~200). We read both and keep each honest.
-const results = readJSON(join(repo, '.sawbuck', 'results.json')) || {};
+const { results, caught: catchesAllTime, state: kind, steer, armed, hasConfig } = repoState(repo);
 const feed = readLines(join(repo, '.sawbuck', 'activity.jsonl')).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
 const tally = { verified: 0, gamed: 0, regression: 0, inconclusive: 0, allowed: 0, mandate: 0 };
 for (const e of feed) if (e && tally[e.kind] != null) tally[e.kind]++;
 const seen = feed.length;
-const catchesAllTime = (results.regressions || 0) + (results.gamed || 0) + (results.mandates || 0);
 const latest = results.latest || (feed.length ? feed[feed.length - 1] : null);
 const since = feed.length ? (feed[0].at || '').slice(0, 10) : null;
-// the steer rate, if the reins judge has been scoring turns here (an OFFLINE read of its file; the
+// the steer rate, if the reins judge has been scoring turns here (an OFFLINE read of its file, in repoState; the
 // recent-window average over roughly the last twenty scored turns, as the band and statusline show it)
-const steerRec = readJSON(join(repo, '.sawbuck', 'steer.json'));
-const steer = steerRec && steerRec.scored ? { rate: Math.round(((steerRec.ema != null ? steerRec.ema : steerRec.steeringRate) || 0) * 100), scored: steerRec.scored } : null;
 
-// --- 2) the armed state: what it can measure here (mirror of statusline) ---
+// --- 2) the armed state: what it can measure here (shared with the statusline) ---
 const isGit = !!existsSync(join(repo, '.git'));
-const hasConfig = existsSync(join(repo, 'promptwheel.config.json'));
-const watching = existsSync(join(repo, '.sawbuck', 'state.json'));
-const armed = hasConfig || existsSync(join(repo, 'package.json'));
-const mem = existsSync(join(repo, 'LOGBOOK.md')) || existsSync(join(repo, 'events.jsonl'));
-const state = watching ? 'watching' : armed ? 'ready' : mem ? 'memory' : 'unarmed';
+const state = kind || 'unarmed';
 
 // --- 3) the live debt ledger: best-effort, bounded -------------------------
 // A full-repo HEAD grep + gating; fast on normal repos, can be heavy on a giant one. Bounded so

package/steers.mjs

@@ -37,7 +37,7 @@ export function steersReport({ json = false, home } = {}) {
   const groups = groupSteers(steers);
   const repeated = groups.filter((g) => g.n >= 3 && g.sessions >= 2);
   if (json) return JSON.stringify({ steers: steers.length, scored: stats.scored, unscored: stats.lost, repeated });
-  if (!steers.length && !stats.scored) return '🐴 sawbuck: no steers recorded yet. They appear here as you work with the plugin\'s judge on.';
+  if (!steers.length && !stats.scored) return '🐴 sawbuck: no steers recorded. The plugin\'s live judge is off by default; /sawbuck-reins:rules reads your history instead.';
   const out = [`🐴 ${steers.length} steers kept, from ${stats.scored} replies scored${stats.lost ? ` (${stats.lost} could not be scored, so this undercounts)` : ''}. Measured, not estimated.`];
   if (repeated.length) {
     out.push('', 'You keep saying:');