sawbuck 0.1.25 → 0.1.26

package/README.md

@@ -56,6 +56,8 @@ Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `
 | `sawbuck status` · `sawbuck log` | the inventory (caught over time + debt now + armed state), in one view; and the recent per-check feed |
 | `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 frame` | the contract's hard rules (mandates, inherited ones included) as one compact block; silent without a contract |
+| `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 where` · `sawbuck statusline` | list every repo it is attached to; a one-line status-line segment (🐴 watching / N caught / steer %) |
@@ -70,6 +72,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.
 
+**Measured, not assumed.** On a scenario whose natural fix sits inside a protected module, driven past two forced compactions (and again on Haiku, and under "urgent hotfix" pressure): with no rule the agent edited the protected file 17 of 17 times; with a rule in any form, including a mandate, 0 of 45. The model honors a rule it was told. The gate is for the rule nobody told it, the session that outlived the summary, and the proof that it held: `attach --claude` re-reads the mandates from the repo on every turn, re-impresses them after a compaction (`sawbuck turn`), and blocks a turn that leaves a protected path changed. Numbers and method: [sawbuck.ai/contracts](https://sawbuck.ai/contracts).
+
 Without a `promptwheel.config.json` the check measures your detected test command. To make it count more (coverage, lint, latency, an eval) or to protect a path with a mandate, `sawbuck init` writes the config and explains each line with evidence from your history.
 
 ## Gate debt on pull requests

package/contract.mjs

@@ -0,0 +1,50 @@
+// contract.mjs: the contract's hard rules, read the way promptwheel reads them. Shared by the CLI
+// (frame / turn) and the Stop hook (the turn-level wall), so there is one resolver and one renderer.
+// Read-only, never throws, zero-dep.
+import { readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+
+// mandates accumulate down the `extends` chain; a local mandate of the same name overrides an inherited one
+export function resolvedMandates(repo) {
+  const seen = new Set(); const byName = new Map();
+  const load = (file) => {
+    const p = resolve(file); if (seen.has(p)) return; seen.add(p);
+    let cfg = null; try { cfg = JSON.parse(readFileSync(p, 'utf8')); } catch { return; }
+    if (!cfg || typeof cfg !== 'object') return;
+    const ext = cfg.extends == null ? [] : Array.isArray(cfg.extends) ? cfg.extends : [cfg.extends];
+    for (const e of ext) if (typeof e === 'string') load(resolve(dirname(p), e));
+    for (const m of (Array.isArray(cfg.mandates) ? cfg.mandates : [])) if (m && m.name) byName.set(String(m.name), m);
+  };
+  load(join(repo, 'promptwheel.config.json'));
+  return [...byName.values()].filter((m) => Array.isArray(m.paths) && m.paths.some((s) => typeof s === 'string' && s.trim()));
+}
+
+// the same glob dialect as promptwheel's evaluatorPaths / mandates (ported verbatim): a bare name
+// matches that basename at any depth; a pattern with "/" is anchored at the repo root; "*" stops at
+// "/", "**" crosses it, "?" is one char; a leading "/" anchors to the root explicitly.
+export function globToRe(glob) {
+  let g = glob; const anchored = g.startsWith('/'); if (anchored) g = g.slice(1);
+  const body = g.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\x00').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/\x00/g, '.*');
+  const pre = (anchored || glob.includes('/')) ? '^' : '(^|/)';
+  return new RegExp(`${pre}${body}$`);
+}
+
+// which changed paths violate which mandate: [{ name, reason, files }]
+export function mandateHits(repo, changedPaths) {
+  const out = [];
+  for (const m of resolvedMandates(repo)) {
+    const res = m.paths.filter((s) => typeof s === 'string' && s.trim()).map(globToRe);
+    const files = changedPaths.filter((f) => res.some((re) => re.test(f)));
+    if (files.length) out.push({ name: String(m.name), reason: m.reason ? String(m.reason).slice(0, 300) : '', files: files.slice(0, 20) });
+  }
+  return out;
+}
+
+// the prompt face of the contract: one compact block, or '' when there is no contract
+export function frameBlock(repo) {
+  const mandates = resolvedMandates(repo);
+  if (!mandates.length) return '';
+  const lines = mandates.map((m) => `  ${m.paths.filter((s) => typeof s === 'string' && s.trim()).join(' · ')}${m.reason ? `  (${String(m.reason).slice(0, 160)})` : ''}`);
+  return '▣ contract (sawbuck) · hard rules in force this session, enforced by the gate on every turn:\n  protected, do not touch:\n' + lines.join('\n');
+}

package/memory.mjs

@@ -96,7 +96,7 @@ const classify = (r, source) => ({
   file: r.file, line: r.line, kind: String(r.kind ?? '').trim(), content: r.content ?? '',
   since: r.since ?? null, sha: r.sha ?? null,
   documented: r.content ? isDocumented(r.content) : false,
-  testSkip: isTestSkip(r.kind ?? r.content ?? ''),
+  testSkip: typeof r.testSkip === 'boolean' ? r.testSkip : isTestSkip(r.kind ?? r.content ?? ''),   // logbook >=0.9.8 classifies it; the regex is the fallback for older providers
   source,
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "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.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,6 +39,7 @@
   "files": [
     "sawbuck.mjs",
     "bins.mjs",
+    "contract.mjs",
     "init.mjs",
     "reflect.mjs",
     "dispatch.mjs",

package/sawbuck-hook.mjs

@@ -5,11 +5,12 @@
 // Zero-dep. Usage (wired as a Stop hook): node sawbuck-hook.mjs --repo <path>
 
 import { execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
+import { mandateHits } from './contract.mjs';
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 const repo = flag('--repo', process.cwd());
 const by = flag('--by', '');   // attribution from the harness wiring: the Claude hook passes 'claude', the raw-git hook passes nothing
@@ -46,6 +47,31 @@ try { rec = JSON.parse(readFileSync(join(stDir, 'results.json'), 'utf8')); } cat
 const total = rec ? (rec.regressions || 0) + (rec.gamed || 0) : 0;
 const saveState = () => { try { mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n'); } catch {} };
 
+// 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
+// edits. A deterministic path match, milliseconds, no metric run. Block the stop (bounded per prompt)
+// and send the agent back to revert the protected files and make the fix elsewhere.
+if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
+  const changed = [...new Set([...git('diff', '--name-only', 'HEAD').split('\n'), ...git('ls-files', '--others', '--exclude-standard').split('\n')].filter(Boolean))];
+  const hits = changed.length ? mandateHits(repo, changed) : [];
+  if (hits.length) {
+    const MAX_BLOCKS = +(cfg.enforce?.maxBlocks) || 3;
+    const promptId = hookInput.prompt_id || '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(', ')}`).join('; ');
+    try { mkdirSync(stDir, { recursive: true }); appendFileSync(join(stDir, 'activity.jsonl'), JSON.stringify({ at: new Date().toISOString(), kind: 'mandate', file: hits[0].files[0], reason: `mandate ${hits[0].name} violated in the working tree`, by: by || 'hook' }) + '\n'); } catch {}
+    if ((st.mandateBlocks || 0) < MAX_BLOCKS) {
+      st.mandateBlocks = (st.mandateBlocks || 0) + 1;
+      saveState();
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: `Sawbuck: a mandate in the contract was violated, the turn is not done. Protected paths changed: ${desc}. Revert every change under the protected paths and make the fix elsewhere (the rule is a wall, not a reminder; the gate fails any change that touches them).` }));
+      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);
+  }
+}
+
 // 3) CONTRACT ENFORCEMENT (Claude Code Stop hook only): if THIS turn's commit was gamed,
 // block the stop and send the agent back to earn the green in the source. Bounded per
 // prompt, because Claude Code's built-in block cap resets on every tool call and so cannot

package/sawbuck.mjs

@@ -19,6 +19,7 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { recall as memRecall, conform as memConform } from './memory.mjs';
 import { PW } from './bins.mjs';
+import { frameBlock } from './contract.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
@@ -81,6 +82,9 @@ Usage:
                             The live suppression debt in HEAD, risk-ranked, undocumented flagged. --since REF
                             shows only what a branch adds; --fail-on exits nonzero (a CI gate)
   sawbuck context [repo]    Relevant history for the files you are changing (reverts, weakened tests, hot spots)
+  sawbuck frame [repo]      The contract's hard rules (mandates, 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 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
@@ -186,23 +190,23 @@ switch (cmd) {
     catch (e) { process.exit(e.status || 1); }
     break;
   }
-  case 'context': {
-    // the read face: ranked relevant history for what you're working on right now.
+  case 'context': { const o = contextBlock(repoArg(), flags.has('--speak')); if (o) out(o); 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
+    // cannot forget them. Silent without a contract; --speak explains instead.
+    const o = frameBlock(repoArg());
+    if (o) out(o);
+    else if (flags.has('--speak')) out('🐴 sawbuck frame: no mandates in promptwheel.config.json yet. Add one (a protected path) and this re-asserts it every turn and after every compaction, so a deep context cannot forget it.');
+    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.
     const repo = repoArg();
-    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
-    // 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 an explicit `sawbuck context` / the /sawbuck-context command.
-    const speak = flags.has('--speak');
-    let changed = g('diff', '--name-only', 'HEAD').split('\n').filter(Boolean);
-    if (!changed.length) changed = g('diff', '--name-only', 'HEAD~1', 'HEAD').split('\n').filter(Boolean);
-    if (!changed.length) { if (speak) out('🐴 sawbuck: nothing changed to look up (no working edits, and no previous commit to read).'); break; }
-    const fileArgs = changed.flatMap((f) => ['--file', f]);
-    let o = '';
-    try { o = execFileSync(process.execPath, [join(HERE, 'rank.mjs'), '--repo', repo, ...fileArgs, '--top', '3'], { encoding: 'utf8' }); }
-    catch (e) { o = (e.stdout || '').toString(); }
-    if (/relevant history/.test(o)) out(o);
-    else if (speak) out('🐴 sawbuck: no notable history for the files you are touching (a clean trail).');
+    const o = [frameBlock(repo), contextBlock(repo, false)].filter(Boolean).join('\n');
+    if (o) out(o);
     break;
   }
   case 'recall': {
@@ -304,6 +308,23 @@ switch (cmd) {
   default: die(`unknown command '${cmd}'\n\n${help}`);
 }
 
+// --- the per-turn block: frame (forward, from contract.mjs) + context (backward) ---------------
+// 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.
+function contextBlock(repo, speak) {
+  const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+  let changed = g('diff', '--name-only', 'HEAD').split('\n').filter(Boolean);
+  if (!changed.length) changed = g('diff', '--name-only', 'HEAD~1', 'HEAD').split('\n').filter(Boolean);
+  if (!changed.length) return speak ? '🐴 sawbuck: nothing changed to look up (no working edits, and no previous commit to read).' : '';
+  const fileArgs = changed.flatMap((f) => ['--file', f]);
+  let o = '';
+  try { o = execFileSync(process.execPath, [join(HERE, 'rank.mjs'), '--repo', repo, ...fileArgs, '--top', '3'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); }
+  catch (e) { o = (e.stdout || '').toString(); }
+  if (/relevant history/.test(o)) return o.trimEnd();
+  return speak ? '🐴 sawbuck: no notable history for the files you are touching (a clean trail).' : '';
+}
+
 // after attach, prove the check can actually measure something here (the inert-metric trap):
 // run the gate on the last commit and say what it can or cannot measure, so you never attach
 // into silent nothing. Best-effort and bounded; the wire already succeeded regardless.
@@ -423,22 +444,25 @@ function wireClaude(repo, opts) {
   let cfg = {};
   if (fileExisted) { try { cfg = JSON.parse(readFileSync(f, 'utf8')); } catch { die(`${f} exists but is not valid JSON; I will not overwrite it. Add the hooks by hand.`); } }
   if (JSON.stringify(cfg).includes('sawbuck.mjs')) { out(`sawbuck: already attached (${user ? 'user' : 'claude'}) in ${f}`); return; }
-  const ctx = user ? `node ${JSON.stringify(SELF)} context` : `node ${JSON.stringify(SELF)} context ${JSON.stringify(repo)}`;
+  const ctx = user ? `node ${JSON.stringify(SELF)} turn` : `node ${JSON.stringify(SELF)} turn ${JSON.stringify(repo)}`;
   const chk = user ? `node ${JSON.stringify(SELF)} __hook --by claude --stop` : `node ${JSON.stringify(SELF)} __hook --repo ${JSON.stringify(repo)} --by claude --stop`;
   if (dry) {
     out(dryText([
-      `${fileExisted ? 'modify' : 'create'}  ${f}  (UserPromptSubmit + Stop hooks)`,
+      `${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'})`,
       `create  ${user ? userManifestPath() : manifestPath(repo)}  (attach receipt)`,
     ].filter(Boolean)));
     return;
   }
   cfg.hooks = cfg.hooks || {};
-  const put = (event, command) => {
+  const put = (event, command, matcher) => {
     cfg.hooks[event] = (cfg.hooks[event] || []).filter((h) => !JSON.stringify(h).includes('sawbuck.mjs'));
-    cfg.hooks[event].push({ hooks: [{ type: 'command', command }] });
+    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).
+  put('SessionStart', ctx, 'compact');
   put('Stop', chk);
   mkdirSync(dir, { recursive: true });
   writeFileSync(f, JSON.stringify(cfg, null, 2) + '\n');
@@ -482,7 +506,7 @@ function unwireClaude(repo, { user }) {
 }
 function removeClaudeEntries(cfg) {
   if (!cfg.hooks) return;
-  for (const ev of ['UserPromptSubmit', 'Stop']) {
+  for (const ev of ['UserPromptSubmit', 'SessionStart', 'Stop']) {
     if (!Array.isArray(cfg.hooks[ev])) continue;
     cfg.hooks[ev] = cfg.hooks[ev].filter((h) => !JSON.stringify(h).includes('sawbuck.mjs'));
     if (!cfg.hooks[ev].length) delete cfg.hooks[ev];     // no empty [] residue