sawbuck 0.1.46 → 0.1.48

package/rank.mjs

@@ -77,11 +77,10 @@ const normMult = (p, kind) => {
 // The "slider": debt rises on its own, but gently. A disabled test or an undocumented suppression
 // on a touched file always surfaces; a file that is churning (hot / reverted) surfaces any debt;
 // a stable file's routine documented suppressions stay quiet until they pile past DEBT_MIN. Tune
-// with SAWBUCK_DEBT_MIN. This is how debt rises by itself in the per-turn context, no command run.
+// with SAWBUCK_DEBT_MIN. This is how debt shows up in `sawbuck context` with no command of its own.
 const DEBT_MIN = Math.max(1, +(process.env.SAWBUCK_DEBT_MIN) || 6);
 
-// Still-live filter + ambient debt, via the memory adapter (the Memory Contract's `debt`
-// capability), scoped to the touched paths so the per-turn hook stays cheap. A suppression on a path
+// Still-live filter + ambient debt, via the Logbook adapter, scoped to the touched paths so the read stays cheap. A suppression on a path
 // now CLEAN of suppressions is churn, not current risk (the study: AutoMapper carries 4 live
 // `[Ignore]` vs ~158/repo across C# history). The adapter runs Logbook's own detection + gating
 // and returns classified suppressions, so the glue never imports its pattern. null = the

package/reflect.mjs

@@ -16,14 +16,11 @@
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 import { record as memRecord } from './memory.mjs';
 import { PW } from './bins.mjs';
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-// The MEMORY engine is reached only through memory.mjs (the Memory Contract seam), never
-// resolved or shelled directly here.
+// Logbook is reached only through memory.mjs, never resolved or shelled directly here.
 
 const flag = (name, def) => { const i = process.argv.indexOf(name); return i > -1 ? process.argv[i + 1] : def; };
 const repo = flag('--repo', process.cwd());
@@ -35,9 +32,10 @@ const noAuto = process.argv.includes('--no-auto');   // user-level wiring: measu
 const git = (...a) => execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim();
 // backstop so the check can never hang a commit/turn; generous default, overridable.
 const CHECK_TIMEOUT = +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 600000;
-// a commit an agent made: its own Promptwheel-Allow trailer does not clear the verdict. An agent can write a
-// commit message, so the override for its work is a person running `sawbuck check --allow "<reason>"`.
-const childEnv = by ? { ...process.env, PROMPTWHEEL_NO_ALLOW_TRAILER: '1' } : process.env;
+// A Sawbuck-Allow or Promptwheel-Allow trailer never clears the verdict, whichever hook ran this: the git hook cannot
+// tell who made a commit, and an agent can write a commit message. The override is a person running
+// `sawbuck check --allow "<reason>"`.
+const childEnv = { ...process.env, PROMPTWHEEL_NO_ALLOW_TRAILER: '1' };
 const runNode = (file, a) => execFileSync(process.execPath, [file, ...a], { cwd: repo, encoding: 'utf8', env: childEnv, stdio: ['ignore', 'pipe', 'pipe'], timeout: CHECK_TIMEOUT, killSignal: 'SIGKILL' });
 
 // --- 1) the check: measure the commit, parse the structured result ----------
@@ -83,6 +81,9 @@ if (standing) {
   process.exit(0);
 }
 if (verdict !== 'gamed' && verdict !== 'fail') process.exit(0);   // only breakage is worth recording
+// A fail that is only a protected path, under the Claude hooks: the Stop hook's wall counts it and sends the turn
+// back, so counting it here too would show two catches for one change. The git hook has no wall, so it records it.
+if (verdict === 'fail' && by && (report.mandates || []).length && !(report.metrics || []).some((m) => m.guard && m.ok === false)) process.exit(0);
 
 // map the engine verdict to Sawbuck's plain outcome words
 const kind = verdict === 'gamed' ? 'gamed' : 'regression';
@@ -92,45 +93,53 @@ const sha = git('rev-parse', head);
 const changed = git('diff', '--name-only', base, head).split('\n').filter(Boolean);
 const testish = (f) => /(\.test\.|\.spec\.|__tests__|\/tests?\/|\.config\.|golden|fixture|snapshot)/i.test(f);
 const srcFiles = changed.filter((f) => !testish(f));
-const evidenceFile = srcFiles[0] || changed[0];
+// a gamed win is named by the goalpost that moved (a test first, then config or a golden file); a regression by the source
+const isTest = (f) => /(\.test\.|\.spec\.|__tests__|(^|\/)tests?\/)/i.test(f);
+// a protected path that was touched is the finding, whatever else the change did: name the rule and the file
+const hit = kind === 'regression' ? protectedHit(report) : null;
+const evidenceFile = kind === 'gamed' ? (changed.find(isTest) || changed.find(testish) || changed[0]) : hit ? hit.file : (srcFiles[0] || changed[0]);
 if (!evidenceFile) process.exit(0);
 
 const gamedMetric = (report.metrics || []).find((m) => m.gamed === true);
 const reason = kind === 'gamed'
   ? `sawbuck: a change here was gamed, ${gamedMetric?.gamingReason || 'a metric "improved" by weakening its test, not the source'}`
+  : hit ? `sawbuck: a change here ${hit.why}`
   : `sawbuck: a change here regressed a guarded metric beyond noise`;
 
 // --- 3) record the finding in memory (unreviewed, machine-authored note) ----
-// The Memory Contract's `record` capability, through the adapter (no direct engine shell here).
-// Kept simple: a commit-attached digest note. A later pass could add --span grounding
-// and true coupling (the fix diff -> "change X also needs Y"). A gamed verdict still standing
-// over the same span is the same catch, not a new one: no second note, no second tick.
-const repeatOfStanding = standing && kind === 'gamed';
-if (!repeatOfStanding) memRecord(repo, { sha, reason: reason.slice(0, 280), side: 'diff', evidenceFile, by: 'sawbuck' });
+// A note on the commit, through the Logbook adapter. A gamed verdict still standing over the same span never
+// gets here (it exited above), so one catch is one note and one tick.
+memRecord(repo, { sha, reason: reason.slice(0, 280), by: 'sawbuck' });
 
 // --- 4) tick the results record (the visible proof-of-work) -----------------
-if (!repeatOfStanding) { if (kind === 'gamed') rec.gamed += 1; else rec.regressions += 1; }
+if (kind === 'gamed') rec.gamed += 1; else rec.regressions += 1;
 rec.latest = { sha: sha.slice(0, 8), kind, base: baseSha || null, file: evidenceFile, reason: reason.replace(/^sawbuck: /, '').slice(0, 140), at: new Date().toISOString(), by: by || null };
 writeRec();
 
 // --- 5) quiet by default; one line to stderr -
 process.stderr.write(`sawbuck: ${kind} recorded on ${evidenceFile}\n`);
 
+// the first protected path (mandate) the engine reports as touched, in words
+function protectedHit(rep) {
+  const m = (rep.mandates || []).find((x) => x && (x.files || []).length);
+  return m ? { file: m.files[0], why: `touched the protected path "${m.name}": ${m.files.slice(0, 3).join(', ')}${m.files.length > 3 ? `, and ${m.files.length - 3} more` : ''}` } : null;
+}
+
 // --- the activity feed: one line per check so you can watch it work, verified
 // included, not only catches. Capped, lives in the git-excluded .sawbuck/, opt
-// out with SAWBUCK_NO_LOG=1. `sawbuck log` reads it.
+// out with SAWBUCK_NO_LOG=1. `sawbuck status --log` reads it.
 function appendActivity(v, rep, standing = false) {
   if (process.env.SAWBUCK_NO_LOG) return;
   const map = { pass: 'verified', gamed: 'gamed', fail: 'regression', inconclusive: 'inconclusive' };
-  const k = (v === 'pass' && rep.allowed) ? 'allowed' : map[v];   // a declared override is logged distinctly, for the audit trail
+  const k = map[v];   // no hook passes --allow and a trailer clears nothing, so there is no "allowed" to log here
   if (!k) return;
   let sha = '', file = '';
   try { sha = git('rev-parse', head).slice(0, 8); } catch {}
-  try { file = git('diff', '--name-only', base, head).split('\n').filter(Boolean)[0] || ''; } catch {}
+  const hit = k === 'regression' ? protectedHit(rep) : null;
+  try { file = (hit && hit.file) || git('diff', '--name-only', base, head).split('\n').filter(Boolean)[0] || ''; } catch {}
   const gm = (rep.metrics || []).find((m) => m.gamed === true);
   const why = k === 'gamed' ? (gm?.gamingReason || 'the win came from editing the goalposts')
-    : k === 'regression' ? 'a guarded metric regressed beyond noise'
-    : k === 'allowed' ? ('declared intentional: ' + (rep.allowed?.reason || ''))
+    : k === 'regression' ? (hit ? `the change ${hit.why}` : 'a guarded metric regressed beyond noise')
     : k === 'verified' ? 'the check passed'
     : 'could not certify a pass';
   // `standing`: this check re-proved the span of a gamed verdict that is still up, not a new catch

package/repo-state.mjs

@@ -1,9 +1,25 @@
 // 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.
+// state: watching (hooks wired for this repo), ready (checkable, not wired), memory (history only), or empty.
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 
 const WEEK = 7 * 864e5;
+export const OURS = /sawbuck\.mjs|npx -y sawbuck@/;   // a hook of ours: the baked path, or the portable form --shared writes
+export const S_START = '# >>> sawbuck >>>';
+const text = (f) => { try { return readFileSync(f, 'utf8'); } catch { return ''; } };
+// our hooks in a Claude Code settings file: under "hooks", so a permission that names sawbuck is not wiring
+export const hooksIn = (f) => { try { return OURS.test(JSON.stringify(JSON.parse(readFileSync(f, 'utf8')).hooks || {})); } catch { return false; } };
+
+// Which hooks are wired for this repo: ours in the project settings, our block in the post-commit hook, or ours in
+// the user-level settings. '' when none are, whatever record an earlier attach left on disk.
+export function wiredBy(repo, home = homedir()) {
+  if (['settings.local.json', 'settings.json'].some((f) => hooksIn(join(repo, '.claude', f)))) return 'project';
+  // .git is a file in a submodule or a linked worktree. A linked worktree has no hooks of its own, and its commits are not checked.
+  const m = /^gitdir: (.+)$/m.exec(text(join(repo, '.git')));
+  if (text(join(m ? resolve(repo, m[1].trim()) : join(repo, '.git'), 'hooks', 'post-commit')).includes(S_START)) return 'git';
+  return hooksIn(join(home, '.claude', 'settings.json')) ? 'user' : '';
+}
 
 export function repoState(repo) {
   const record = (f) => { try { return JSON.parse(readFileSync(join(repo, '.sawbuck', f), 'utf8')); } catch { return null; } };
@@ -12,11 +28,12 @@ export function repoState(repo) {
   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' : '';
+  const wired = wiredBy(repo);
+  const state = wired ? '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: the judge was turned off, or the plugin is not running.
   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 };
+  return { results, caught, hasConfig, armed, wired, state, steer };
 }

package/rules.mjs

@@ -1,8 +1,9 @@
 // Find the rules you keep enforcing and never wrote down. `prepare` gathers what you typed to Claude Code, on this
 // machine, with copies and likely secrets removed. The agent proposes rules from it, each with quotes. `check` proves
 // every quote is really yours: a rule with fewer than two real quotes is dropped. Nothing is added to any file here.
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+// Once the check has run, the gathered messages and the candidates are deleted: they were for that one read.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, chmodSync, rmSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { readHistory, typedText } from './history.mjs';
 
@@ -10,6 +11,11 @@ const MAX_LINES = 3000;
 export const SECRET = /(sk-[a-z0-9_-]{16,}|gh[pousr]_[a-z0-9]{20,}|github_pat_\w{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[\w-]{10,}|eyJ[\w-]{20,}\.[\w-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY|\b[a-f0-9]{40,}\b|(password|passwd|secret|token|api[_-]?key)\s*[:=]\s*\S+)/i;
 const norm = (s) => s.toLowerCase().replace(/\s+/g, ' ').trim();
 const paths = (home) => ({ dir: join(home, '.sawbuck'), input: join(home, '.sawbuck', 'rule-input.txt') });
+// remove what one read gathered. A file the model wrote counts only when it sits in ~/.sawbuck: anywhere else it is the person's own.
+export function forget(home, ...files) {
+  const dir = resolve(paths(home).dir);
+  for (const f of files) if (f && dirname(resolve(f)) === dir) rmSync(f, { force: true });
+}
 
 export function prepareRules({ home = homedir() } = {}) {
   const found = [];
@@ -32,6 +38,7 @@ export function prepareRules({ home = homedir() } = {}) {
   const { dir, input } = paths(home);
   mkdirSync(dir, { recursive: true });
   writeFileSync(input, lines.join('\n') + '\n', { mode: 0o600 });
+  chmodSync(input, 0o600);   // the mode above only applies to a new file
   return { input, lines: lines.length, secrets };
 }
 
@@ -59,6 +66,7 @@ export function rulesCli(args, { home = homedir() } = {}) {
     if (!file || !existsSync(file) || !statSync(file).isFile()) return '🐴 sawbuck: --check needs the candidates file.';
     if (!existsSync(paths(home).input)) return '🐴 sawbuck: run sawbuck rules --prepare first.';
     const { kept, dropped } = checkRules(file, { home });
+    forget(home, paths(home).input, file);
     const out = [`🐴 ${kept.length} rules have at least 2 quotes that are really yours${dropped.length ? `, ${dropped.length} dropped` : ''}.`];
     kept.forEach((r, n) => { out.push('', `${n + 1}. ${r.rule}`); for (const q of r.quotes.slice(0, 3)) out.push(`     "${q.slice(0, 110)}"`); });
     return out.join('\n');

package/sawbuck-hook.mjs

@@ -6,11 +6,11 @@ import { ensureExcluded } from './exclude.mjs';
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-import { mandateHits, hashOf, protectedDirty, protectedAmong, lockState } from './contract.mjs';
+import { mandateHits, hashOf, protectedAmong, lockState } from './contract.mjs';
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 const by = flag('--by', '');   // attribution from the harness wiring: the Claude hook passes 'claude', the raw-git hook passes nothing
 const stop = process.argv.includes('--stop');   // wired as the Claude Code Stop hook: enforce the contract on a gamed turn
@@ -182,8 +182,3 @@ if (total > (st.shownTotal || 0)) {
   st.shownTotal = total;
 }
 saveState();
-
-// Keep the record dirs out of `git status` via .git/info/exclude, so Sawbuck never
-// dirties the worktree, including under `attach --user`, which is global and cannot
-// set this up per-repo at attach time. Idempotent; markers match the CLI's so a
-// per-repo `detach` removes them.