sawbuck 0.1.38 → 0.1.39

package/README.md

@@ -84,6 +84,8 @@ Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `
     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.
 
+**After you sign.** A new contract starts by watching: protected paths, new install scripts and sources outside the registry block from day one, and new dependencies and structure changes show as notes. `sawbuck contract --strict` blocks them all. When something fails, the check says what changed in words. To accept it on a pull request, someone with write access comments `sawbuck-allow: <reason>` and re-runs the check; the reason stays on the record. An agent signed in as that person could post the same comment, so branch protection and review still matter. Locally, use `--allow "<reason>"`.
+
 **Rewritten history.** Logbook reads git, so a squash or a rebase takes a revert with it. `sawbuck context` also reads the reflog for commits no branch reaches any more and shows them for the files in hand, and once attached it keeps them in `.sawbuck/rewritten.jsonl` after the reflog expires. It stays local: a clone does not get it, nothing older than the reflog comes back, and work that was never committed is not in git at all. Your steering is separate: `reins` reads your agent transcripts, not git.
 
 **Tested claims.** Every claim above, and every limit, is a test in [`test/claims.test.mjs`](test/claims.test.mjs), run on a clean account.

package/contract-cmd.mjs

@@ -14,6 +14,23 @@ import { PW } from './bins.mjs';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const repo = process.argv[2] || process.cwd();
 const dry = process.argv.includes('--dry-run');
+const strict = process.argv.includes('--strict');
+const noCi = process.argv.includes('--no-ci');
+// a new contract starts by watching: everyday change shows as a note. Protected paths, install scripts and sources
+// outside the registry still fail from day one. --strict holds them all, and an existing contract is left as it is.
+const REPORT = new Set(['dependency_entries', 'lock_drift', 'pins_changed', 'unpinned_execution', 'install_policy_gaps']);
+const WORKFLOW = `# Written by sawbuck contract. Checks every pull request against the contract in promptwheel.config.json.
+name: Sawbuck
+on: pull_request
+permissions: { contents: read, pull-requests: write }
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with: { fetch-depth: 0 }
+      - uses: promptwheel-ai/promptwheel@v0
+`;
 const cfgPath = join(repo, 'promptwheel.config.json');
 const run = (args, cwd, stdio = ['ignore', 'pipe', 'pipe']) => execFileSync(process.execPath, args, { cwd, encoding: 'utf8', stdio });
 
@@ -34,7 +51,7 @@ try {
     const names = (l) => new Set((l || []).map((x) => x && x.name));
     const hasM = names(cfg.mandates), hasG = names(cfg.metrics);
     cfg.mandates = [...(cfg.mandates || []), ...preset.mandates.filter((m) => !hasM.has(m.name))];
-    cfg.metrics = [...(cfg.metrics || []), ...preset.metrics.filter((m) => !hasG.has(m.name))];
+    cfg.metrics = [...(cfg.metrics || []), ...preset.metrics.filter((m) => !hasG.has(m.name)).map((m) => (!strict && REPORT.has(m.name) ? { ...m, report: true } : m))];
     cfg.evaluatorPaths = [...new Set([...(cfg.evaluatorPaths || []), ...(preset.evaluatorPaths || [])])];
     cfg.allowTrailer = false;
     writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
@@ -50,10 +67,17 @@ try {
       if (next !== text) writeFileSync(f, next);
     }
     ensureExcluded(repo);
+    // CI goes in here, before the rules take hold: afterwards the contract itself would refuse an agent the file.
+    // Only for a GitHub repo with a real test command: a placeholder would fail every pull request.
+    const wf = join(repo, '.github', 'workflows', 'sawbuck.yml');
+    let remote = ''; try { remote = execFileSync('git', ['-C', repo, 'remote', 'get-url', 'origin'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch {}
+    const realTests = !(cfg.metrics || []).some((m) => /set your test command/.test(String(m.cmd)));
+    let ci = '';
+    if (!noCi && /github\.com/.test(remote) && realTests && !existsSync(wf)) { mkdirSync(dirname(wf), { recursive: true }); writeFileSync(wf, WORKFLOW); ci = wf; }
     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` : '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.\n' : ''}` : 'sawbuck: already signed, nothing changed.\n');
   }
 } finally { rmSync(scratch, { recursive: true, force: true }); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "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 support in beta.",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,11 +34,12 @@
   },
   "dependencies": {
     "@promptwheel/logbook": "0.9.10",
-    "promptwheel": "0.7.13"
+    "promptwheel": "0.7.14"
   },
   "files": [
     "sawbuck.mjs",
     "rewrites.mjs",
+    "steers.mjs",
     "exclude.mjs",
     "contract-cmd.mjs",
     "bins.mjs",

package/sawbuck.mjs

@@ -14,6 +14,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { erasedBlock } from './rewrites.mjs';
+import { steersReport } from './steers.mjs';
 import { ensureExcluded } from './exclude.mjs';
 import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, unlinkSync, rmdirSync, rmSync, readdirSync } from 'node:fs';
 import { basename, join, dirname, resolve } from 'node:path';
@@ -93,6 +94,7 @@ Usage:
   sawbuck doctor [repo]     Check the attachment still resolves to a live sawbuck; --all for every repo
   sawbuck where             List every repo Sawbuck is attached to
   sawbuck contract          Sign this repo: tests, tripwires, protected paths, and the architecture lock (--dry-run to preview)
+  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 recall [repo]     Related notes for your changes from extra memory providers
@@ -116,13 +118,22 @@ function gitDir(repo) { try { return resolve(repo, execFileSync('git', ['-C', re
 const out = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
 
 if (cmd === '--version' || cmd === '-v') { console.log(version); process.exit(0); }
-if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { out(help); process.exit(0); }
+if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  out(flags.has('--all') ? help : `sawbuck ${version}: sign your agent to a contract
+
+  sawbuck contract   sign this repo: protected paths, your tests, CI
+  sawbuck check      verify your latest change right now
+  sawbuck status     what it has caught here
+
+  sawbuck help --all   everything else`);
+  process.exit(0);
+}
 
 switch (cmd) {
   case 'contract': {
     const top = gitTop(repoArg());
     if (!top) usage(`${repoArg()} is not a git repository (a contract signs one; run it inside your project)`);
-    try { execFileSync(process.execPath, [join(HERE, 'contract-cmd.mjs'), top, ...rest.filter((a) => a === '--dry-run')], { stdio: 'inherit' }); }
+    try { execFileSync(process.execPath, [join(HERE, 'contract-cmd.mjs'), top, ...rest.filter((a) => ['--dry-run', '--strict', '--no-ci'].includes(a))], { stdio: 'inherit' }); }
     catch (e) { process.exit(e.status || 1); }
     break;
   }
@@ -177,9 +188,10 @@ switch (cmd) {
     else if (rep.verdict === 'pass') out(`🐴 ✓ held: nothing got worse in your ${where} change, and there was no win to re-prove.`);
     else if (rep.verdict === 'gamed') out('🐴 🚩 gamed: a win here came from editing the test, config, or grader, not the source. It does NOT survive a source-only re-run, so it does not count.');
     else if (rep.verdict === 'fail' && (rep.mandates || []).length) out('🐴 ✗ sent back: a hard rule in the contract was broken, however green the rest is.');
-    else if (rep.verdict === 'fail') out(`🐴 ✗ regression: a guarded metric got worse (${(rep.metrics || []).filter((x) => x.guard && !x.ok).map((x) => x.name).join(', ') || 'a guard'}).`);
+    else if (rep.verdict === 'fail') out('🐴 ✗ sent back: this change made something worse.');
     else out('🐴 ≈ inconclusive: the check ran but could not measure your metric (it did not run in isolation). Point it at your real test command: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json.');
     if ((rep.metrics || []).some((x) => x.heldByTestEdit)) out('🐴 ⚠ your tests changed too, and the old tests fail on this source. Fine for an intended change. Otherwise check the tests were not weakened: a green that stays green is not proved.');
+    for (const x of rep.explained || []) out(`🐴 ${x.noted ? 'note' : 'needs a look'}: ${x.what}${x.items ? ': ' + x.items.join(', ') : ''}${!x.noted && x.allowable ? '. If you meant this: --allow "<reason>", or on a pull request comment sawbuck-allow: <reason>' : ''}`);
     if (rep.gate && rep.gate.changed) out(`🐴 ⚠ the gate definition changed in this change (fingerprint ${rep.gate.fingerprint.base} -> ${rep.gate.fingerprint.head}): a metric, guard, evaluatorPath or mandate was added, removed or edited.`);
     process.exit(code);
   }
@@ -343,6 +355,7 @@ switch (cmd) {
   case 'trace': { traceRepo(repoRoot()); break; }
   case 'doctor': { if (flags.has('--all')) doctorAll(); else doctorRepo(repoRoot()); break; }
   case 'where': { whereAttached(); break; }
+  case 'steers': { out(steersReport({ json: flags.has('--json') })); break; }
   case 'statusline': {
     // compact status-line segment for the cwd repo. Never throws; fast.
     try {

package/steers.mjs

@@ -0,0 +1,48 @@
+// The steer scratchpad, for the person: what you keep correcting, read from Claude Code's plugin store on this
+// machine. Reads only. Counts here are measured; nothing is projected. The grouping matches the plugin's.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const STOP = new Set(['the', 'a', 'an', 'to', 'of', 'and', 'or', 'it', 'this', 'that', 'do', 'not', 'dont', 'use', 'be', 'in', 'on', 'for', 'with', 'is', 'are', 'your', 'you']);
+export const steerKey = (n) => String(n).toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter((w) => w && !STOP.has(w)).slice(0, 3).sort().join(' ');
+
+export function readSteers(home = homedir()) {
+  const dir = join(home, '.claude', 'plugins', 'store');
+  const out = { steers: [], stats: { scored: 0, lost: 0 } };
+  let files = []; try { files = readdirSync(dir).filter((f) => f.startsWith('sawbuck-reins_') && f.endsWith('.json')); } catch { return out; }
+  for (const f of files) {
+    try {
+      const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      if (Array.isArray(d.steers)) out.steers.push(...d.steers);
+      if (d.steerStats) { out.stats.scored += d.steerStats.scored || 0; out.stats.lost += d.steerStats.lost || 0; }
+    } catch {}
+  }
+  return out;
+}
+
+export function groupSteers(list) {
+  const g = new Map();
+  for (const e of list) {
+    const key = steerKey(e.nudge); if (!key) continue;
+    const x = g.get(key) || { key, nudge: e.nudge, n: 0, sessions: new Set(), repos: new Set() };
+    x.n++; x.sessions.add(e.session); x.repos.add(e.repo || 'no repo'); g.set(key, x);
+  }
+  return [...g.values()].map((x) => ({ key: x.key, nudge: x.nudge, n: x.n, sessions: x.sessions.size, repos: [...x.repos] }))
+    .sort((a, b) => b.n - a.n || b.repos.length - a.repos.length);
+}
+
+export function steersReport({ json = false, home } = {}) {
+  const { steers, stats } = readSteers(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.';
+  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:');
+    for (const g of repeated.slice(0, 10)) out.push(`  ${String(g.n).padStart(3)}x  ${g.nudge}  (${g.repos.join(', ')})`);
+    out.push('', 'If one of these is a rule, write it down: a protected path in promptwheel.config.json, or a line in CLAUDE.md.');
+  } else out.push('', 'Nothing repeats yet: a steer shows here after 3 times across 2 sessions.');
+  return out.join('\n');
+}