sawbuck 0.1.49 → 0.1.50

package/README.md

@@ -27,10 +27,10 @@ sawbuck contract          # --full adds supply-chain guards, a repo lock and, on
 sawbuck attach            # watch every Claude Code turn (--shared for a team file, --git for any other agent)
 ```
 
-**Zero-config:** it finds npm, pytest, cargo and go tests on its own, so in those repos there is nothing to write to start. Anything else (a Makefile target, say) reads inconclusive until you set the command in `promptwheel.config.json`.
+**Zero-config:** it finds npm, pytest, cargo and go tests on its own, so in those repos there is nothing to write to start. That includes npm, yarn and pnpm workspaces: each workspace's own `node_modules` is linked into the clean copy the check runs in, and a sibling package is read at the commit being measured. If the tests import a sibling package's built output, they need the build first: `sawbuck init` adds it as `setup`. Anything else (a Makefile target, say) reads inconclusive until you set the command in `promptwheel.config.json`. When it cannot measure, it says which it was: tests that fail before and after, a dependency the clean copy is missing, or a `setup` command that failed.
 On attach it tells you exactly what it can measure here (and how to fix it if it can't).
 `sawbuck init` writes that config: your detected tests and the tripwires, with notes from your history. Coverage, latency or a cost budget you add to it by hand.
-In CI, the same check runs as the [promptwheel GitHub Action](https://github.com/promptwheel-ai/promptwheel#in-ci-and-in-claude-code) (`uses: promptwheel-ai/promptwheel@v0`); the debt gate below is this repo's own Action. For every project at once: `sawbuck attach --user`. Under `--user` the check runs only in repos that have a `promptwheel.config.json`.
+In CI, the same check runs as the [promptwheel GitHub Action](https://github.com/promptwheel-ai/promptwheel#in-ci-and-in-claude-code) (`uses: promptwheel-ai/promptwheel@v0`, or pin it by commit: `sawbuck contract --full` writes the workflow with every action pinned by commit, its own included); the debt gate below is this repo's own Action. For every project at once: `sawbuck attach --user`. Under `--user` the check runs only in repos that have a `promptwheel.config.json`.
 
 One entry point each: a person types `sawbuck`; CI and libraries use `promptwheel` (the engine underneath, `import { check }`). `sawbuck check` passes every `promptwheel run` flag through, so you never need both.
 
@@ -57,6 +57,7 @@ Exit codes: `0` pass (verified, held, or allowed) · `1` sent back (a regression
 - **Rides on, does not replace.** Sawbuck is the verify + memory layer. Your agent and your loop stay yours.
 - **Clean on and off.** `attach` writes a git-excluded `.claude/settings.local.json`, the lines in `.git/info/exclude` that keep its files out of `git status`, a receipt under `.git/sawbuck/`, a line in `~/.sawbuck/registry.json` (the list `detach --all` reads), and in a signed repo `.sawbuck/state.json` (`attach --git` writes the post-commit hook and `.sawbuck/state.json` in place of the settings file); `attach --dry-run` lists all of it. `detach` removes the hooks and the receipt, and still removes the hooks when the receipt is lost; `detach --dry-run` lists what would go. A post-commit hook that was there before `attach --git` is put back byte for byte. Signed contract files stay because they are yours to review. The record (`.sawbuck/`, the logbook files) stays too, still out of `git status`, until `detach --purge` deletes it and the exclude lines. `detach --verify` proves the wiring is gone and names what is left.
 - **A limit of the hooks file.** `.claude/settings.local.json` is kept out of git, so taking the hooks out of it shows in no diff, and the check cannot see it. `sawbuck doctor` can: it reads the receipt and says the hooks are gone, or that the set is incomplete (a missing Stop hook, say). `sawbuck attach --shared` avoids it: the hooks go in a tracked file, and a removal shows in git.
+- **What a check costs.** It runs your test command, and your `setup` command if the config has one, in a clean copy at each commit it compares, and once more when a test went from red to green. Under the Claude hooks that happens when a turn made a commit, not on every turn. If `setup` is a full production build, narrow it to what the tests need.
 - **A limit of the turn hook.** The hook re-runs your tests on commits, not on uncommitted work. A test edited to go green and left uncommitted is not sent back at the end of that turn. It is caught when it is committed, and `sawbuck check` reads it on demand, which is what the written rule tells the agent to run before finishing.
 - **A limit of the git hook.** `attach --git` pins the hook to the checkout it was attached from, so a commit made in a linked git worktree is not checked. A hooks folder inside the work tree (`core.hooksPath`, as husky sets it) is refused, and attach prints the line to add by hand; `detach`, `doctor` and `status` do not know about a line added that way.
 
@@ -105,7 +106,7 @@ To remove a rule, delete its entry under `mandates` in `promptwheel.config.json`
     files before (reverts, weakened tests, fragile spots). Never skip, weaken, or delete a
     test to go green.
 
-**With `--full`.** It 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. If your tests can't run in CI, the check says so and doesn't fail the job, and protected paths are still enforced. 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>"`. A commit trailer is not a person, so Sawbuck does not read one.
+**With `--full`.** `pins_changed` is a fingerprint of the resolved dependency tree, not a count, so its value is a long number that only means changed or unchanged. The supply-chain guards read `unmeasurable` on the commit that adds them, because their scanners did not exist before it, and count from the next change. It 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. If your tests can't run in CI, the check says so and doesn't fail the job, and protected paths are still enforced. 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>"`. A commit trailer is not a person, so Sawbuck does not read one.
 
 **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.
 

package/contract-cmd.mjs

@@ -7,13 +7,17 @@ import './pipe.mjs';
 import { ensureExcluded } from './exclude.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 { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, cpSync, mkdirSync, readdirSync, statSync, symlinkSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { PW } from './bins.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
+// The check's own action is pinned by commit, like GitHub's: the commit the engine's release tag points at. A moving
+// tag with write access to pull requests is the kind of thing the unpinned_execution guard exists to flag.
+const PKG = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'));
+const ACTION = `promptwheel-ai/promptwheel@${PKG.promptwheelAction} # v${PKG.dependencies.promptwheel}`;
 const repo = process.argv[2] || process.cwd();
 const dry = process.argv.includes('--dry-run');
 const strict = process.argv.includes('--strict');
@@ -36,7 +40,7 @@ jobs:
 ${npm ? `      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with: { node-version: 22 }
       - run: npm ci --ignore-scripts
-` : ''}      - uses: promptwheel-ai/promptwheel@v0
+` : ''}      - uses: ${ACTION}
         with: { inconclusive: pass }
 `;
 const cfgPath = join(repo, 'promptwheel.config.json');
@@ -57,9 +61,46 @@ try {
   const names = (l) => new Set((l || []).map((x) => x && x.name));
   const counts = (c) => `${new Set([...names(c.mandates), ...names(mandates)]).size} protected paths${full ? `, ${preset.metrics.length} supply-chain guards` : ''}`;
   if (dry) {
-    let now = {}; try { if (had) now = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {}
-    const notes = strict ? (now.metrics || []).filter((m) => m && m.report && REPORT.has(m.name)).length : 0;
-    process.stdout.write(`sawbuck contract would ${had ? 'update' : 'write'} ${cfgPath}: ${counts(now)}${full ? ', the scanners under .promptwheel/packs/, and promptwheel.lock.json' : ''}${notes ? `, and make ${notes} guards that are notes block` : ''}.\n`);
+    // The preview is the real run, done in a throwaway copy of what signing reads, so the two cannot drift apart:
+    // the files in the repo's top folder, an existing workflow, the scanners, the remote and the exclude file.
+    const shadow = mkdtempSync(join(tmpdir(), 'sawbuck-preview-'));
+    try {
+      const g = (...a) => execFileSync('git', ['-c', 'user.name=sawbuck', '-c', 'user.email=sawbuck@local', ...a], { cwd: shadow, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      g('init', '-q');
+      for (const e of readdirSync(repo, { withFileTypes: true })) if (e.isFile() && statSync(join(repo, e.name)).size < 32 * 1024 * 1024) cpSync(join(repo, e.name), join(shadow, e.name));
+      for (const rel of [join('.github', 'workflows', 'sawbuck.yml'), join('.promptwheel', 'packs')]) if (existsSync(join(repo, rel))) cpSync(join(repo, rel), join(shadow, rel), { recursive: true });
+      if (existsSync(join(repo, 'node_modules'))) { try { symlinkSync(join(repo, 'node_modules'), join(shadow, 'node_modules')); } catch { /* the lint check may not be offered in the preview */ } }
+      const exclude = (root) => resolve(root, execFileSync('git', ['-C', root, 'rev-parse', '--git-path', 'info/exclude'], { encoding: 'utf8' }).trim());
+      let remote = ''; try { remote = execFileSync('git', ['-C', repo, 'remote', 'get-url', 'origin'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+      if (remote) g('remote', 'add', 'origin', remote);
+      try { if (existsSync(exclude(repo))) { mkdirSync(dirname(exclude(shadow)), { recursive: true }); cpSync(exclude(repo), exclude(shadow)); } } catch {}
+      const read = (f) => { try { return readFileSync(f, 'utf8'); } catch { return ''; } };
+      const exWas = read(exclude(shadow));
+      g('add', '-A'); g('commit', '-q', '--allow-empty', '-m', 'as it is now');
+      run([fileURLToPath(import.meta.url), shadow, ...process.argv.slice(3).filter((a) => a !== '--dry-run')], shadow);
+      const rows = new Map();
+      for (const l of g('status', '--porcelain', '-uall').split('\n').filter(Boolean)) {
+        const f = l.slice(3).replace(/^(\.promptwheel\/packs\/supply-chain\/).*/, '$1');
+        if (f !== 'node_modules') rows.set(f, l.startsWith('??') ? 'new' : 'changed');
+      }
+      const after = existsSync(join(shadow, 'promptwheel.config.json')) ? JSON.parse(read(join(shadow, 'promptwheel.config.json'))) : { metrics: [], mandates: [] };
+      let now = {}; try { if (had) now = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch {}
+      const notes = strict ? (now.metrics || []).filter((m) => m && m.report && REPORT.has(m.name)).length : 0;
+      const what = {
+        'promptwheel.config.json': `${counts(now)}, ${(after.metrics || []).length} checks in all (${(after.metrics || []).map((m) => m.name).join(', ')})${notes ? `, and ${notes} guards that are notes would block` : ''}`,
+        'AGENTS.md': 'the written rule', 'CLAUDE.md': 'the written rule', '.cursorrules': 'the written rule',
+        '.github/workflows/sawbuck.yml': 'a CI check on pull requests',
+        'promptwheel.lock.json': 'the shape of this repo',
+        '.promptwheel/packs/supply-chain/': 'the two scanners the supply-chain guards run',
+        '.gitignore': 'so the scanners reach git',
+      };
+      if (!rows.size) process.stdout.write('sawbuck contract --dry-run: already signed, nothing would change.\n');
+      else {
+        process.stdout.write('sawbuck contract --dry-run: nothing was written. A real run would write:\n');
+        for (const [f, how] of rows) process.stdout.write(`  ${f.padEnd(34)} ${how}${what[f] ? ': ' + what[f] : ''}\n`);
+        if (read(exclude(shadow)) !== exWas) process.stdout.write('  and lines in .git/info/exclude that keep Sawbuck\'s record out of git status (local, never committed)\n');
+      }
+    } finally { rmSync(shadow, { recursive: true, force: true }); }
   } else {
     if (!had) run([join(HERE, 'init.mjs'), '-y', '--no-investigate'], repo);
     const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, 'utf8')) : { repeat: 1, metrics: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Write down the rules your agent follows, and prove they held. 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",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@promptwheel/logbook": "0.11.0",
-    "promptwheel": "0.8.1"
+    "promptwheel": "0.8.2"
   },
   "files": [
     "sawbuck.mjs",
@@ -59,5 +59,6 @@
     "memory.mjs",
     "README.md",
     "CONTRACT.md"
-  ]
+  ],
+  "promptwheelAction": "3558f779fc26d7fdf948ec06a1a3ae47ac55e742"
 }

package/sawbuck.mjs

@@ -39,17 +39,25 @@ function gateReport(repo, a) {
 }
 // why nothing could be measured, in words that match the case: no test command, tests red on both sides, or a
 // win the source-only re-run could not apply. `sawbuck init` only where there is no config to edit yet.
+// a setup command that failed, in words: "(exit 7) at the base and head refs: <its last line>". '' when setup worked.
+const setupFailure = (rep) => { const s = rep && rep.setup; if (!s) return ''; const at = Object.keys(s), f = s[at[0]]; return `(exit ${f.exit}) at the ${at.join(' and ')} ref${at.length > 1 ? 's' : ''}${f.lastLine ? ': ' + f.lastLine : ''}`; };
 function inconclusiveWhy(rep, repo) {
   const ms = (rep && rep.metrics) || [];
   const m = ms.find((x) => x.inert) || ms[0];
   if (ms.some((x) => x.unprovable)) return 'a win here could not be re-proved, because the source-only re-run did not apply. Do not trust this green on its own.';
+  if (setupFailure(rep)) return `the setup command failed ${setupFailure(rep)}. Fix "setup" in promptwheel.config.json, then check again.`;
   const hasCfg = existsSync(join(repo, 'promptwheel.config.json'));
   let cmd = '';
   try { cmd = String((JSON.parse(readFileSync(join(repo, 'promptwheel.config.json'), 'utf8')).metrics || []).find((x) => x && x.name === (m && m.name))?.cmd || ''); } catch {}
   const placeholder = /set your test command/.test(cmd) || (!hasCfg && !detectedTests(repo));
   const where = hasCfg ? 'in promptwheel.config.json' : 'with `sawbuck init`, then in promptwheel.config.json';
   if (placeholder) return `there is no test command here, so nothing was measured. It finds npm, pytest, cargo and go tests on its own. Set yours ${where} (the cmd of "${(m && m.name) || 'tests_pass'}").`;
-  return `"${(m && m.name) || 'tests_pass'}" failed before and after this change, so there was no win or loss to measure. If your tests are red, fix them first. If they pass for you, the clean copy the check runs in is missing something: set setup or linkDirs ${where}.`;
+  // tests that import a built folder (dist, build) or a sibling package's built output need the build to run first
+  let build = false; try { build = !!JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8')).scripts?.build; } catch {}
+  const needsBuild = !build ? '' : hasCfg ? ' This repo has a build script: if your tests need it, set "setup" to it in promptwheel.config.json.' : ' This repo has a build script, and tests often need it first: `sawbuck init` writes a config that runs it.';
+  if (m && m.cause === 'too-much-output') return `your test command was stopped: ${m.detail}. Make it quieter, or point the check at a smaller command ${where}.`;
+  if (m && m.cause === 'missing-dependency') return `the clean copy the check runs in is missing something your tests need: ${m.detail}. Link it with linkDirs, or install it with setup, ${where}.${needsBuild}`;
+  return `your tests fail before and after this change, so there was no win or loss to measure ("${(m && m.name) || 'tests_pass'}"). Fix the failing tests first. If they pass for you, the clean copy the check runs in is missing something: set setup or linkDirs ${where}.${needsBuild}`;
 }
 // the test commands the engine finds with no config (promptwheel's detectTestCmd)
 function detectedTests(repo) {
@@ -238,6 +246,7 @@ 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.');
+      if (((rep.gate && rep.gate.weakened) || []).some((w) => w.change === 'measurement-edited')) out('🐴 this change also edits how the check measures (setup, env or linkDirs in promptwheel.config.json), and a change is judged by the settings in force before it. Commit that edit on its own first, then check your fix again.');
       if (!dirty && /^(Sawbuck|Promptwheel)-Allow:/im.test(g('log', '--format=%B', `${base || 'HEAD~1'}..${head || 'HEAD'}`))) out('🐴 note: a Sawbuck-Allow trailer does not clear this, because an agent can write a commit message. A person passes --allow "<reason>".');
     }
     else if (rep.verdict === 'fail' && (rep.mandates || []).length) {
@@ -250,6 +259,7 @@ switch (cmd) {
     }
     else if (rep.verdict === 'fail') out('🐴 ✗ sent back: this change made something worse.');
     else out(`🐴 ≈ inconclusive: ${inconclusiveWhy(rep, repo)}`);
+    if (rep.verdict !== 'inconclusive' && setupFailure(rep)) out(`🐴 ⚠ the setup command failed ${setupFailure(rep)}. The check still ran, so see whether "setup" in promptwheel.config.json is still right.`);
     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.`);
@@ -266,7 +276,13 @@ switch (cmd) {
     catch (e) { process.exit(e.status || 1); }
     break;
   }
-  case 'context': { const o = contextBlock(repoRoot(), flags.has('--speak')); if (o) out(o); break; }
+  case 'context': {
+    // Nothing to show stays off stdout: an older attach runs this on every prompt and adds its stdout to the prompt.
+    // A person or an agent who ran it still learns why, on stderr.
+    const root = repoRoot(); const o = contextBlock(root, flags.has('--speak'));
+    if (o) out(o); else process.stderr.write(contextBlock(root, true) + '\n');
+    break;
+  }
   case 'frame': {
     // the prompt face of the contract: re-impress the hard rules (mandates, resolved through `extends`)
     // as one compact block at the live end of the context, so a deep or freshly compacted session
@@ -811,7 +827,7 @@ function doctorAll() {
   const r = regRead();
   if (!r.repos.length) { out('sawbuck: not attached anywhere.'); return; }
   out('sawbuck is attached to:');
-  for (const x of r.repos) out(`  ${x.mode.padEnd(14)} ${x.repo}`);
+  for (const x of r.repos) out(`  ${x.mode.padEnd(14)} ${x.mode === 'user' ? 'every repo you open in Claude Code (hooks in ~/.claude/settings.json; the check runs where a promptwheel.config.json exists)' : x.repo}`);
   for (const repo of new Set(r.repos.map((x) => x.repo))) doctorRepo(repo);
 }