sawbuck 0.1.19 → 0.1.20

package/CONTRACT.md

@@ -8,6 +8,8 @@ This is an open interface for making an AI coding harness trustworthy. It define
 
 The contract has one property that holds all of it together: a verdict is **deterministic and reproducible from `(base, head, config)` alone**. No LLM is in the path, and nothing is read from the agent's trajectory, so the result cannot be obfuscated against and does not change when you ask it twice.
 
+A corollary worth stating as an invariant: **the gate is defined only by in-repo, versioned config.** External systems (a dashboard, an issue tracker, a memory provider) may *report on* a verdict, but they must never *define* the guardrail. A guardrail that lives outside the repo is one the check cannot see in the diff, so it cannot be fingerprinted, so loosening it leaves no trace to catch as gamed. Memory (the input) is a pluggable socket; the gate (the output) stays in-repo and fingerprinted.
+
 > This contract covers the check. Sawbuck pairs it with the other half, **memory** (the relevant history for what you touch, plus the live debt), as the mirror idea: where the check is a standard others *conform to*, memory is a socket others *fill*. The default memory provider is @promptwheel/logbook, carried along so it works out of the box, but it is swappable; logbook is a default, not a requirement of the idea.
 >
 > Both halves nest with your folders, so policy and memory flow top-down and isolate across siblings. A parent `promptwheel.config.json` passes its guardrails down via `extends` (repos inherit the base gate; local metrics override by name), and memory inherits a parent folder's shared scope the same way (a repo sees itself and its ancestors, never a sibling). One model for both: the directory tree is the scope.

package/README.md

@@ -77,7 +77,7 @@ Debt also rises on its own: once attached, the per-turn `context` hook surfaces
 Sawbuck is thin glue over two roles, each behind an open interface that points in opposite directions:
 
 - **the check** : the deterministic outcome gate, a published standard (the [Verified-Outcome Contract](CONTRACT.md)) that others conform to. Reference implementation: **promptwheel**. You plug in *what* to measure (your tests, lint, coverage, an eval); the un-gameable source re-proof is the fixed part. Embed it with `import { check }`, or check any tool's verdict with `promptwheel conformance`.
-- **the memory** : the relevant history for the files you touch, plus the live debt. A socket you can fill. Default provider: **@promptwheel/logbook** (git history as agent memory; also ships an MCP server). Sawbuck reads it through one adapter, so you can *compose in your own* memory: `SAWBUCK_MEMORY=logbook,obsidian` keeps logbook as the git-truth + debt provider and adds your notes, then `sawbuck recall`. Two reference providers ship in `providers/`: **obsidian** (local notes, offline; set `OBSIDIAN_VAULT`) and **mem0** (semantic memory; the one that reaches the network, so it needs a `MEM0_API_KEY` or a `~/.mem0` key file, unlike the offline default; verified against Mem0's v3 API). Any bin that speaks the three contract verbs works; `sawbuck memory-conformance <bin>` checks one. Composed providers are **folder-scoped and isolated by default**: each repo sees only its own memory, never a sibling's. Drop a `.sawbuck-root` marker (or set `SAWBUCK_MEMORY_ROOT`) in a parent folder to let repos under it inherit that folder's shared memory, top down. logbook is the default, not a hard requirement of the idea.
+- **the memory** : the relevant history for the files you touch, plus the live debt. A socket you can fill. Default provider: **@promptwheel/logbook** (git history as agent memory; also ships an MCP server). Sawbuck reads it through one adapter, so you can *compose in your own* memory: `SAWBUCK_MEMORY=logbook,obsidian` keeps logbook as the git-truth + debt provider and adds your notes, then `sawbuck recall`. Four reference providers ship in `providers/`: **obsidian** (local notes vault; set `OBSIDIAN_VAULT`), **local** (a plain JSON file, zero setup), **claude** (read-only: your project's `CLAUDE.md` / `.claude` memory, already there, nothing to configure), and **mem0** (semantic memory; the one that reaches the network, so it needs a `MEM0_API_KEY` or a `~/.mem0` key file, unlike the offline default; verified against Mem0's v3 API). Any bin that speaks the three contract verbs works; `sawbuck memory-conformance <bin>` checks one. Composed providers are **folder-scoped and isolated by default**: each repo sees only its own memory, never a sibling's. Drop a `.sawbuck-root` marker (or set `SAWBUCK_MEMORY_ROOT`) in a parent folder to let repos under it inherit that folder's shared memory, top down. logbook is the default, not a hard requirement of the idea.
 
 In one line: the check is a standard we publish for others to meet; the memory is a socket we expose for others to fill. Sawbuck composes the two.
 

package/memory.mjs

@@ -31,7 +31,7 @@ function logbookBin() {
 }
 const envKey = (name) => 'SAWBUCK_MEMORY_' + name.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_BIN';
 // the ordered provider list. Each: { name, bin, dialect: 'logbook' | 'contract' }.
-const SHIPPED = new Set(['obsidian', 'mem0']); // reference contract providers that ship in providers/
+const SHIPPED = new Set(['obsidian', 'mem0', 'local', 'claude']); // reference contract providers that ship in providers/
 export function providers() {
   const spec = (process.env.SAWBUCK_MEMORY || 'logbook').split(',').map((s) => s.trim()).filter(Boolean);
   return spec.map((name) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "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",
@@ -30,6 +30,8 @@
     "memory.mjs",
     "providers/obsidian.mjs",
     "providers/mem0.mjs",
+    "providers/local.mjs",
+    "providers/claude.mjs",
     "run.mjs",
     "README.md",
     "GLOSSARY.md",

package/providers/claude.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// claude.mjs, a REFERENCE read-only memory provider: your project's Claude Code memory (CLAUDE.md,
+// AGENTS.md, and top-level .claude/*.md) as a recall source. It is the most UBIQUITOUS local memory -
+// a Claude Code repo already has it - so it is zero-setup. READ-ONLY by design: recall only; debt and
+// record EXIT NONZERO (unsupported). This is a view of memory you already keep, not a write target
+// (writing findings into CLAUDE.md would bloat the always-loaded project context), and the contract
+// lets a provider implement a subset. Inherently leaf-scoped (reads only this repo's files, so no
+// cross-repo leak). Zero-dep, offline, local-notes axis.
+//
+//   recall --file P [--file Q] --json   relevant lines from your project memory -> Finding[] (kind note)
+//   debt | record                        EXIT NONZERO (unsupported)
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const die = (m, c = 2) => { process.stderr.write(`claude provider: ${m}\n`); process.exit(c); };
+const CWD = process.cwd();
+
+if (cmd === 'debt' || cmd === 'record') die(`${cmd} is unsupported (claude memory is a read-only recall source)`, 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const matches = (l) => paths.find((p) => l.includes(p) || (basename(p).length > 2 && l.includes(basename(p)))) || null;
+  // the project's Claude Code memory: CLAUDE.md / AGENTS.md at the root, plus top-level .claude/*.md.
+  const sources = [];
+  for (const f of ['CLAUDE.md', 'AGENTS.md']) { const p = join(CWD, f); if (existsSync(p)) sources.push(p); }
+  try { for (const e of readdirSync(join(CWD, '.claude'))) if (extname(e).toLowerCase() === '.md') sources.push(join(CWD, '.claude', e)); } catch {}
+  const out = [];
+  for (const src of sources) {
+    let text = ''; try { if (statSync(src).size > 512 * 1024) continue; text = readFileSync(src, 'utf8'); } catch { continue; }
+    const lines = text.split('\n');
+    let heading = basename(src);
+    for (let i = 0; i < lines.length; i++) {
+      const h = lines[i].match(/^#{1,6}\s+(.+)/);
+      if (h) { heading = h[1].trim(); continue; }
+      const hit = matches(lines[i]);
+      if (!hit) continue;
+      out.push({ kind: 'note', path: hit, ref: `${basename(src)}:${i + 1}`, date: null, summary: `${heading}: ${lines[i].trim()}`.slice(0, 280), score: 0.4 });
+    }
+  }
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/local.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// local.mjs, a REFERENCE minimal local-file memory provider: the simplest way to fill the socket with
+// no external tool. Findings live as JSON in <repo>/.sawbuck/memory-notes.json (git-excluded by attach).
+// It is the cleanest conformance target and a "bring your own, just a file" option. Zero-dep, offline,
+// in the local-notes axis alongside obsidian. Folder-scoped like the others.
+//
+//   recall --file P [--scope ID ...] --json   -> Finding[] (kind note)
+//   record --ref SHA --summary S [--scope ID] [--side X] [--evidence-file F] --by WHO
+//   debt   --json                              EXITS NONZERO (a note store is not git-aware)
+//
+// Store: SAWBUCK_LOCAL_MEMORY, else <cwd>/.sawbuck/memory-notes.json.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const flag = (n, d) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? true) : d; };
+const die = (m, c = 2) => { process.stderr.write(`local provider: ${m}\n`); process.exit(c); };
+
+const STORE = process.env.SAWBUCK_LOCAL_MEMORY || join(process.cwd(), '.sawbuck', 'memory-notes.json');
+const load = () => { try { const v = JSON.parse(readFileSync(STORE, 'utf8')); return Array.isArray(v) ? v : []; } catch { return []; } };
+
+if (cmd === 'debt') die('debt is unsupported by a note store (git-truth lives in a git provider like logbook)', 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const scopes = new Set(flagAll('--scope'));            // self + ancestors; empty (direct call) = match any
+  const bases = paths.map((p) => basename(p));
+  const out = [];
+  for (const f of load()) {
+    if (scopes.size && f.scope != null && !scopes.has(f.scope)) continue;   // isolation: a sibling scope is excluded
+    const hit = (f.path && paths.includes(f.path)) || (f.summary && bases.some((b) => f.summary.includes(b)));
+    if (!hit) continue;
+    out.push({ kind: 'note', path: f.path ?? null, ref: f.ref ?? null, date: f.date ?? null, summary: String(f.summary || '').slice(0, 280), scope: f.scope ?? '', score: 0.5 });
+  }
+  out.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+if (cmd === 'record') {
+  const ref = String(flag('--ref', '')), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
+  const scope = flagAll('--scope')[0] ?? '';
+  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
+  const notes = load();
+  if (notes.some((f) => f.ref === ref && f.summary === summary && f.scope === scope)) { console.log('recorded (already present)'); process.exit(0); }
+  notes.push({ ref, summary, path: evidence || null, scope, by, ...(side ? { side: String(side) } : {}), date: new Date().toISOString().slice(0, 10) });
+  try { mkdirSync(dirname(STORE), { recursive: true }); writeFileSync(STORE, JSON.stringify(notes, null, 2) + '\n'); console.log('recorded'); process.exit(0); }
+  catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/obsidian.mjs

@@ -103,7 +103,16 @@ if (cmd === 'record') {
   // a [[wikilink]] to the evidence path so Obsidian's graph connects the finding to the code note.
   const link = evidence ? `\n- evidence: [[${String(evidence).replace(/[[\]]/g, '')}]]` : '';
   const body = `---\nsawbuck: finding\nref: ${ref}\nby: ${by}\ndate: ${date}\nscope: ${leaf}\n---\n\n# ${summary.slice(0, 80)}\n\n${summary}\n\n- ref: \`${ref}\`${side ? `\n- side: ${side}` : ''}${link}\n`;
-  try { writeFileSync(join(dir, `${safeRef}.md`), body); console.log('recorded'); process.exit(0); }
+  // no-clobber + dedupe: if this exact finding is already noted, skip; if a DIFFERENT note shares the
+  // ref, write a suffixed sibling instead of overwriting the earlier one.
+  let target = join(dir, `${safeRef}.md`);
+  if (existsSync(target)) {
+    let prev = ''; try { prev = readFileSync(target, 'utf8'); } catch {}
+    if (prev.includes(summary)) { console.log('recorded (already present)'); process.exit(0); }
+    let i = 2; while (existsSync(join(dir, `${safeRef}-${i}.md`))) i++;
+    target = join(dir, `${safeRef}-${i}.md`);
+  }
+  try { writeFileSync(target, body); console.log('recorded'); process.exit(0); }
   catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
 }