sawbuck 0.1.7 → 0.1.9

package/CONTRACT.md

@@ -81,6 +81,8 @@ A win is **`gamed`** when it does not survive a **source-only re-run**: revert e
 
 **Protected terms (declared, optionally enforced).** `evaluatorPaths` is also the declaration surface for immutability: the files a repo names there are its fixed terms, the goalposts the agent does not get to move. The baseline is detection (a win that depended on changing a protected term reads `gamed`). A stronger conformance level *enforces* it: the audit gate (CI, or a hook the agent cannot bypass) fails any change to a protected term unless a human signs off, so the terms cannot be moved mid-game. Note the honest limit: a file cannot be made truly immutable to an agent that has write access to the repo. The guarantee comes from the un-bypassable gate, not from the filesystem.
 
+**Declared override (an intentional test change).** The check flags a win that came only from moving the goalposts, not from the source. Sometimes that move is legitimate: a test that asserted the wrong thing, an obsolete test removed, a guard intentionally retired. The sanctioned way through is to DECLARE it, not to silently weaken the gate. A `Sawbuck-Allow: <reason>` trailer on the commit (or `--allow "<reason>"` for a working-tree or CI run) acknowledges the change, so a would-be `gamed` reads `pass` with the acknowledgment recorded in `allowed` (the reason, and the metric or gate names it cleared). The check does not judge intent; it forces intent to be explicit and auditable. An UNdeclared test-only win is still `gamed`; a declared one is on the record, so a reviewer sees the reason instead of a silent green. It covers the edit, the delete, and the new file alike. The declaration lives in the commit, so it is immutable and attributable: revoking it is a review act, not a deletion, and a reasonless trailer does not override.
+
 ## 4. The context record (the trail knowledge)
 
 A conforming saddle also carries the repo's history as deterministic memory: a ledger derived from git (hotspots, reverted approaches, suppressed or weakened tests, fragile areas), surfaced per turn as a ranked slice for the files being touched. It is a projection of git, never a second source of truth, so it is always reconstructable and never drifts from what actually happened.

package/dispatch.mjs

@@ -22,7 +22,7 @@ const L = rec.latest;
 // Attribute the latest catch to the agent that made it (the Claude hook passes 'claude').
 let head;
 if (L && L.kind === 'gamed') head = L.by ? `🐴 Sawbuck caught ${L.by} gaming a metric` : `🐴 Sawbuck caught a gamed change`;
-else if (L && L.kind === 'regression') head = L.by ? `🐴 Sawbuck flagged a regression from ${L.by}` : `🐴 Sawbuck flagged a regression`;
+else if (L && L.kind === 'regression') head = L.by ? `🐴 Sawbuck caught a regression from ${L.by}` : `🐴 Sawbuck caught a regression`;
 else head = `🐴 Sawbuck`;
 let line = head;
 if (L) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Sign your agent to a contract so it does what you want: a deterministic, zero-LLM check that re-proves every win from the agent's source edits alone, so a green that came from editing the test is caught and reverted. A saddle for your coding harness.",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,7 @@
     "sawbuck": "sawbuck.mjs"
   },
   "dependencies": {
-    "promptwheel": "^0.6.0",
+    "promptwheel": "^0.7.0",
     "@promptwheel/logbook": "^0.9.0"
   },
   "files": [

package/rank.mjs

@@ -56,6 +56,10 @@ const recency = (d) => 1 / (1 + Math.max(0, (now - Date.parse(d)) / 86400000) /
 // weaken/suppress are commit-level signals; only credit them to code/test files,
 // not the README/config that merely rode along in the same commit.
 const codeish = (p) => /\.(m?[jt]sx?|cjs|py|go|rs|rb|java|kt|c|cc|cpp|h|hpp|php|swift|scala|clj|ex|exs)$/i.test(p);
+// a suppression or assertion drop on a TEST path is a hidden-failure risk (a skipped
+// or weakened test), so it outranks the same marker in app code (a lone style
+// eslint-disable). The relevance lead: sharpen the signal, don't flatten it.
+const isTest = (p) => /(^|\/)(tests?|__tests__|specs?)\//i.test(p) || /[._-](test|spec)\.[a-z0-9]+$/i.test(p) || /(^|\/)test_[^/]+\.py$/i.test(p);
 
 const DAY = 86400000;
 const ranked = paths.map((p) => {
@@ -67,7 +71,10 @@ const ranked = paths.map((p) => {
     if (e.revert) { w = 3; kind = 'revert (do-not-retry)'; }
     // "weakened" only on a NET assertion drop (logbook's own rule: del > add + 2), 
     // a rewrite that removes some asserts but adds more is not a weakening.
-    else if (codeish(p) && ((e.suppressions && e.suppressions.length) || ((e.del_asserts || 0) > (e.add_asserts || 0) + 2) || e.downgrades > 0)) { w = 2; kind = 'test weakened / suppressed'; }
+    else if (codeish(p) && ((e.suppressions && e.suppressions.length) || ((e.del_asserts || 0) > (e.add_asserts || 0) + 2) || e.downgrades > 0)) {
+      if (isTest(p)) { w = 2.5; kind = 'test disabled / weakened'; }
+      else { w = 2; kind = 'suppression in source'; }
+    }
     else if (e.fix) { w = 1.2; kind = 'bugfix here'; }
     else continue;
     const weighted = w * recency(e.date);

package/reflect.mjs

@@ -107,7 +107,7 @@ process.stderr.write(`sawbuck: ${kind} recorded on ${evidenceFile}\n`);
 function appendActivity(v, rep) {
   if (process.env.SAWBUCK_NO_LOG) return;
   const map = { pass: 'verified', gamed: 'gamed', fail: 'regression', inconclusive: 'inconclusive' };
-  const k = map[v];
+  const k = (v === 'pass' && rep.allowed) ? 'allowed' : map[v];   // a declared override is logged distinctly, for the audit trail
   if (!k) return;
   let sha = '', file = '';
   try { sha = git('rev-parse', head).slice(0, 8); } catch {}
@@ -115,6 +115,7 @@ function appendActivity(v, rep) {
   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 === 'verified' ? 'the source earned the green'
     : 'could not certify a pass';
   const ev = { at: new Date().toISOString(), kind: k, sha, file, reason: String(why).slice(0, 160), by: by || null };

package/sawbuck.mjs

@@ -124,7 +124,7 @@ switch (cmd) {
     if (rep.verdict === 'pass') out(`🐴 ✓ verified: your ${where} change earned it. ${m ? '"' + m.name + '"' : 'The metric'} held, and the source carried the win (it survives a source-only re-run).`);
     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') out(`🐴 ✗ regression: a guarded metric got worse (${(rep.metrics || []).filter((x) => x.guard && !x.ok).map((x) => x.name).join(', ') || 'a guard'}).`);
-    else out('🐴 ≈ couldn\'t measure: the check ran but your metric is inert (it did not actually run in isolation). Point it at your real test command: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json.');
+    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.');
     process.exit(code);
   }
   case 'log': {
@@ -135,7 +135,7 @@ switch (cmd) {
     if (!lines.length) { out('sawbuck: no activity recorded yet (the check logs here on each commit/turn).'); break; }
     const ni = rest.indexOf('-n');
     const n = ni > -1 ? (parseInt(rest[ni + 1], 10) || 20) : 20;
-    const icon = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive: '≈' };
+    const icon = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive: '≈', allowed: '✎' };
     const recent = lines.slice(-n).reverse();
     out(`sawbuck activity (last ${recent.length}):`);
     for (const l of recent) {
@@ -155,14 +155,19 @@ switch (cmd) {
     // the read face: ranked relevant history for what you're working on right now.
     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) break;   // silent: safe as an every-turn hook
+    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);   // only speak when there is something
+    if (/relevant history/.test(o)) out(o);
+    else if (speak) out('🐴 sawbuck: no notable history for the files you are touching (a clean trail).');
     break;
   }
   case 'run': {
@@ -205,11 +210,13 @@ switch (cmd) {
         try { const r = JSON.parse(readFileSync(join(repo, '.sawbuck', 'results.json'), 'utf8')); caught = (r.regressions || 0) + (r.gamed || 0); } catch {}
         // the last verdict from the activity feed (includes verified passes), so you see it working each turn
         let last = '';
-        try { const L = readFileSync(join(repo, '.sawbuck', 'activity.jsonl'), 'utf8').trim().split('\n'); const e = JSON.parse(L[L.length - 1]); last = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive: '≈' }[e.kind] || ''; } catch {}
-        // profile readout: watching (something to check, incl. zero-config via a test command) vs memory-only
+        try { const L = readFileSync(join(repo, '.sawbuck', 'activity.jsonl'), 'utf8').trim().split('\n'); const e = JSON.parse(L[L.length - 1]); last = { verified: '✓', gamed: '🚩', regression: '✗', inconclusive: '≈', allowed: '✎' }[e.kind] || ''; } catch {}
+        // one state model, shared with the Reins band: watching (wired in) / ready (checkable, not wired yet) / memory (history only)
+        const active = existsSync(join(repo, '.sawbuck', 'state.json'));
         const armed = existsSync(join(repo, 'promptwheel.config.json')) || existsSync(join(repo, 'package.json'));
-        const seg = caught > 0 ? `🐴 sawbuck · ${caught} caught` : armed ? `🐴 sawbuck · watching` : `🐴 sawbuck · memory`;
-        process.stdout.write(last ? `${seg} · ${last}` : seg);
+        const mem = existsSync(join(repo, 'LOGBOOK.md')) || existsSync(join(repo, 'events.jsonl'));
+        const seg = caught > 0 ? `🐴 sawbuck · ${caught} caught` : active ? `🐴 sawbuck · watching` : armed ? `🐴 sawbuck · ready` : mem ? `🐴 sawbuck · memory` : '';
+        if (seg) process.stdout.write(last ? `${seg} · ${last}` : seg);
       }
     } catch {}
     break;