sawbuck 0.1.33 → 0.1.35

package/README.md

@@ -60,6 +60,7 @@ Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `
 | `sawbuck turn` | frame + context in one block: what `attach --claude` runs on every prompt and again right after a compaction |
 | `sawbuck recall` | related notes for your current change from extra memory providers you compose in (bring your own) |
 | `sawbuck trace` · `sawbuck doctor` · `detach --verify` | show the footprint; check the attachment resolves; prove a clean removal |
+| `sawbuck contract` | one command to sign a repo: keeps your contract, adds tests and tripwires if there are none, protected paths, the supply-chain guards, and the architecture lock. `--dry-run` previews it. |
 | `sawbuck where` · `sawbuck statusline` | list every repo it is attached to; a one-line status-line segment (🐴 watching / N caught / steer %) |
 
 ## Give your agent the contract

package/contract-cmd.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// sawbuck contract: one command that signs a repo to a working contract. Keeps whatever contract is already
+// here, adds your tests and tripwires if there is none, then the supply-chain protections and the architecture
+// lock. Zero-LLM. Re-running changes nothing. Protected product code (auth, billing) is suggested, never added:
+// freezing those is a person's decision.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, cpSync, mkdirSync } 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));
+const repo = process.argv[2] || process.cwd();
+const dry = process.argv.includes('--dry-run');
+const cfgPath = join(repo, 'promptwheel.config.json');
+const run = (args, cwd, stdio = ['ignore', 'pipe', 'pipe']) => execFileSync(process.execPath, args, { cwd, encoding: 'utf8', stdio });
+
+// the preset as the engine writes it, in a scratch repo, so the contract and the engine cannot drift apart
+const scratch = mkdtempSync(join(tmpdir(), 'sawbuck-contract-'));
+try {
+  execFileSync('git', ['init', '-q'], { cwd: scratch, stdio: 'ignore' });
+  writeFileSync(join(scratch, 'package.json'), '{"name":"scratch"}\n');
+  run([PW, 'init', '--preset', 'supply-chain', '--no-agent-block'], scratch);
+  const preset = JSON.parse(readFileSync(join(scratch, 'promptwheel.config.json'), 'utf8'));
+  const had = existsSync(cfgPath);
+  if (dry) {
+    process.stdout.write(`sawbuck contract would ${had ? 'add to' : 'write'} ${cfgPath}: ${preset.metrics.length} guards and ${preset.mandates.length} protected-path rules, the scanners under .promptwheel/packs/, and promptwheel.lock.json.\n`);
+  } else {
+    if (!had) run([join(HERE, 'init.mjs'), '-y', '--no-investigate'], repo);
+    const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, 'utf8')) : { repeat: 1, metrics: [] };
+    const before = { m: (cfg.mandates || []).length, g: (cfg.metrics || []).length };
+    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.evaluatorPaths = [...new Set([...(cfg.evaluatorPaths || []), ...(preset.evaluatorPaths || [])])];
+    cfg.allowTrailer = false;
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    const pack = join(repo, '.promptwheel', 'packs', 'supply-chain');
+    mkdirSync(pack, { recursive: true });
+    cpSync(join(scratch, '.promptwheel', 'packs', 'supply-chain'), pack, { recursive: true });
+    // the gate measures in clean worktrees, so the scanners must reach git. A repo attached earlier, or one that
+    // ignores .promptwheel/ for the outcome record, would hide them and every guard would read unmeasurable.
+    for (const f of [join(repo, '.gitignore'), resolve(repo, execFileSync('git', ['-C', repo, 'rev-parse', '--git-path', 'info/exclude'], { encoding: 'utf8' }).trim())]) {
+      if (!existsSync(f)) continue;
+      const text = readFileSync(f, 'utf8');
+      const next = text.replace(/^\.promptwheel\/?[ \t]*$/gm, '.promptwheel/*\n!.promptwheel/packs/');
+      if (next !== text) writeFileSync(f, next);
+    }
+    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');
+  }
+} finally { rmSync(scratch, { recursive: true, force: true }); }
+
+// a suggestion, not a rule: only a person should freeze product code
+let files = [];
+try { files = execFileSync('git', ['-C', repo, 'ls-files'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }).split('\n'); } catch { /* not a repo: attach says so */ }
+const seen = new Set();
+for (const f of files) { const m = f.match(/^(.*?(?:^|\/)(?:auth|authentication|billing|payments?|migrations))\//); if (m && !/(^|\/)(node_modules|test|tests|docs?)\//.test(m[1])) seen.add(m[1]); }
+if (seen.size) process.stdout.write(`\n  To protect product code too, add these to "mandates" in promptwheel.config.json:\n${[...seen].slice(0, 5).map((d) => `    { "name": "${d.replace(/\W+/g, '-')}", "paths": ["${d}/**"], "reason": "changed by a person" }`).join('\n')}\n`);
+if (!dry) process.stdout.write('\n  Commit promptwheel.config.json, promptwheel.lock.json and .promptwheel/packs/. Then /sawbuck-reins:watch or sawbuck attach --claude arms it.\n');

package/contract.mjs

@@ -99,7 +99,7 @@ export function globToRe(glob) {
 // which changed paths violate which mandate: [{ name, reason, files, committed? }]. The rules are the
 // working tree's plus the committed ones (mandatesInForce); pass { ref: null } for the working tree alone.
 export function mandateHits(repo, changedPaths, opts = {}) {
-  const list = opts.ref === null ? resolvedMandates(repo) : mandatesInForce(repo, opts.ref || 'HEAD');
+  const list = opts.list || (opts.ref === null ? resolvedMandates(repo) : mandatesInForce(repo, opts.ref || 'HEAD'));
   const out = [];
   for (const m of list) {
     const res = pathsOf(m).map(globToRe);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sawbuck",
-  "version": "0.1.33",
-  "description": "Sign your agent to a contract: a deterministic, zero-LLM check re-proves every win from the agent's source edits alone, so a green that came from editing the test, grader, or config is caught and sent back. Works in Claude Code, Codex, git hooks, and CI.",
+  "version": "0.1.35",
+  "description": "Sign your agent to a contract: a deterministic, zero-LLM check re-proves every win from the agent's source edits alone, so a green that came from editing the test, grader, or config is caught and sent back. Works in Claude Code, git hooks, and CI, with Codex support in beta.",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
@@ -34,10 +34,11 @@
   },
   "dependencies": {
     "@promptwheel/logbook": "0.9.10",
-    "promptwheel": "0.7.11"
+    "promptwheel": "0.7.12"
   },
   "files": [
     "sawbuck.mjs",
+    "contract-cmd.mjs",
     "bins.mjs",
     "contract.mjs",
     "init.mjs",

package/sawbuck-hook.mjs

@@ -89,7 +89,9 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
   const untouched = (f) => Object.prototype.hasOwnProperty.call(baseline, f) && hashNow[f] === baseline[f];
   const changed = [...new Set([...dirty.filter((f) => !untouched(f)), ...committedSince])];
   const leftAlone = dirty.filter(untouched);
-  const hits = changed.length ? mandateHits(repo, changed) : [];
+  // the rules in force when the turn began: a rule this turn adds does not apply to it, so signing a contract does
+  // not block itself, and one it deletes or narrows still holds
+  const hits = changed.length ? mandateHits(repo, changed, base && Array.isArray(base.rules) ? { list: base.rules } : {}) : [];
   st.lastStopAt = now;   // the next prompt may take a fresh baseline only because this stop happened
   st.lastStopHead = head || null;   // and where HEAD stood: a commit between turns is the person's, not the agent's
   if (hits.length) {
@@ -197,7 +199,7 @@ function ensureExcluded(r) {
     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.sawbuck/\n.promptwheel/\nevents.jsonl\nannotations.jsonl\nannotation-reviews.jsonl\ndecision-cards.jsonl\nLOGBOOK.md\nJOURNEY.md\n# <<< sawbuck <<<\n';
+    const WANT = '# >>> sawbuck >>>\n.sawbuck/\n.promptwheel/*\n!.promptwheel/packs/\nevents.jsonl\nannotations.jsonl\nannotation-reviews.jsonl\ndecision-cards.jsonl\nLOGBOOK.md\nJOURNEY.md\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;

package/sawbuck.mjs

@@ -43,7 +43,7 @@ const BLOCK_RE = new RegExp(`\\n?${S_START}[\\s\\S]*?${S_END}\\n?`, 'g');
 // plus the logbook's root working-set (ledger cache, digests, annotation planes). It is
 // memory, not the user's source, a user who wants LOGBOOK.md committed still can explicitly
 // (exclude only affects UNtracked files).
-const RECORD_DIRS = ['.sawbuck/', '.promptwheel/', 'events.jsonl', 'annotations.jsonl', 'annotation-reviews.jsonl', 'decision-cards.jsonl', 'LOGBOOK.md', 'JOURNEY.md'];
+const RECORD_DIRS = ['.sawbuck/', '.promptwheel/*', '!.promptwheel/packs/', 'events.jsonl', 'annotations.jsonl', 'annotation-reviews.jsonl', 'decision-cards.jsonl', 'LOGBOOK.md', 'JOURNEY.md'];
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -90,6 +90,7 @@ Usage:
   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
   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 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,6 +117,13 @@ if (cmd === '--version' || cmd === '-v') { console.log(version); process.exit(0)
 if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { out(help); 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' }); }
+    catch (e) { process.exit(e.status || 1); }
+    break;
+  }
   case 'init': {
     try { execFileSync(process.execPath, [join(HERE, 'init.mjs'), ...rest], { stdio: 'inherit' }); }
     catch (e) { process.exit(e.status || 1); }
@@ -235,7 +243,7 @@ switch (cmd) {
         const stDir = join(repo, '.sawbuck'); const stPath = join(stDir, 'state.json');
         let st = {}; try { st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
         const now = new Date().toISOString();
-        if (mandatesInForce(repo).length) {
+        {   // a baseline even with no rules yet: a turn that signs a contract is judged by the contract it began with
           const prev = st.turnBaseline && typeof st.turnBaseline === 'object' ? st.turnBaseline : null;
           const stoppedSince = st.lastStopAt && st.lastPromptAt && Date.parse(st.lastStopAt) >= Date.parse(st.lastPromptAt);
           const unfinished = !!prev && !!st.lastPromptAt && !stoppedSince;
@@ -256,7 +264,7 @@ switch (cmd) {
             const stillInHead = moved && Object.entries(flagged).some(([f, h]) => { const b = blobAt(repo, sha, f); return h === 'deleted' ? b === '' : (!!h && b === h); });
             const pin = !!(st.lastViolation && st.lastViolation.sha);
             if (moved && !stillInHead && st.lastViolation) delete st.lastViolation.sha;
-            st.turnBaseline = { at: now, sha: ((!moved || stillInHead) && pin && st.lastViolation.sha) || sha, files, lock: lockState(repo) };
+            st.turnBaseline = { at: now, sha: ((!moved || stillInHead) && pin && st.lastViolation.sha) || sha, files, lock: lockState(repo), rules: mandatesInForce(repo) };
           }
         }
         st.lastPromptAt = now;   // every prompt, mandates or not: the walls key their block budgets on it when the harness sends no prompt_id
@@ -634,7 +642,8 @@ function onPath() {
   if (process.env.SAWBUCK_NO_PATH_CHECK) return false;
   try { execFileSync('sh', ['-c', 'command -v sawbuck'], { stdio: 'ignore' }); return true; } catch { return false; }
 }
-function extractBaked(text) { const m = text.match(/node "([^"]+)"/); return m ? m[1] : null; }
+// the path a hook bakes in: the quoted one ending in sawbuck.mjs, in a shell hook or in JSON, where the quotes are escaped
+function extractBaked(text) { const m = text.match(/"([^"]*sawbuck\.mjs)\\?"/); return m ? m[1] : null; }
 function doctorRepo(repo) {
   const checks = [];
   const pc = gitPath(repo, 'hooks/post-commit');