sawbuck 0.1.44 → 0.1.46

package/exposure.mjs

@@ -1,104 +0,0 @@
-// What was not said. The shape records what you pushed on; this records what the agent did, from your transcripts, so a
-// spoke can be read against its opportunity: an agent that often changes code and runs nothing, in history where you
-// rarely ask for proof, is a blind spot. Plain counting of tool calls. No model, nothing leaves this machine.
-import { readdirSync, readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { readHistory, typedText } from './history.mjs';
-
-const VERIFY = /\b(test|tests|pytest|vitest|jest|mocha|ava|playwright|cargo (test|check)|go (test|vet)|tsc|eslint|lint|typecheck|npm run (build|check)|curl|sawbuck check|promptwheel run|make (test|check))\b/i;
-const RISKY_PATH = /(^|\/)(\.env[^/]*|\.npmrc|\.yarnrc(\.yml)?|\.github\/workflows\/[^/]+|Dockerfile[^/]*|docker-compose[^/]*|CODEOWNERS|\.claude\/settings(\.local)?\.json|[^/]*(secret|credential)[^/]*)$/i;
-const RISKY_CMD = /(git push[^|;&]*(--force|-f\b)|git reset --hard|curl[^|]*\|\s*(sh|bash)|sudo |drop table|chmod 777)/i;
-// deleting a temp or build folder is housekeeping, not risk: on real history two thirds of rm -rf were that
-const RM = /rm -rf\s+(\S+)/i, RM_SAFE = /tmp|scratch|\$|dist|build|node_modules|cache|\.next|coverage/i;
-const SHIP = /\b(git commit|git push|npm publish|gh pr (create|merge)|gh release|vercel|deploy)\b/i;
-const UI = /\.(css|scss|sass|less|tsx|jsx|vue|svelte|astro|html|svg)$/i;
-const COPY = /\.(md|mdx|txt|rst)$/i;
-const CODE = /\.(m?[jt]sx?|py|go|rs|rb|java|kt|cs|php|c|cc|cpp|h|swift|sh)$/i;
-const BIG = 200;
-const SCRATCH = /(^|\/)(tmp|scratchpad|scratch)\/|^\/tmp\/|\/\.claude\//;   // throwaway work does not need a test run
-const DAYS = 90;   // what to work on now, not what happened last year
-
-// Rules you have already written, by spoke. A plain keyword match on your own files, so it is a hint: it finds that a
-// rule on the subject exists, not that it says the right thing.
-const WRITTEN = {
-  proof: /\b(verify|verified|run the tests?|tests? pass|prove|proof|before claiming|before trusting)\b/i,
-  safety: /\b(secrets?|credentials?|force.?push|destructive|protected paths?|never delete|before deleting)\b/i,
-  simplicity: /\b(simple|simplify|bloat|smallest|minimal|keep it short|overengineer\w*)\b/i,
-  process: /\b(commit|push|publish|release|deploy)\b/i,
-  voice: /\b(em dash\w*|plain (words|language|voice)|tone|wording|ai tells?|voice)\b/i,
-  visual: /\b(design|layout|css|ui|colou?rs?|spacing)\b/i,
-  naming: /\b(naming|names?|rename)\b/i,
-  autonomy: /\b(do not ask|don't ask|ask first|ask before|proceed without|keep going)\b/i,
-};
-export function writtenRules({ home = homedir(), repo = process.cwd() } = {}) {
-  const files = [join(home, '.claude', 'CLAUDE.md'), join(home, '.sawbuck', 'rules.md'), join(repo, 'CLAUDE.md'), join(repo, 'AGENTS.md')];
-  const root = join(home, '.claude', 'projects');
-  try { for (const d of readdirSync(root)) { const m = join(root, d, 'memory'); if (existsSync(m)) for (const f of readdirSync(m)) if (/^feedback.*\.md$/.test(f)) files.push(join(m, f)); } } catch {}
-  let text = '';
-  for (const f of files) { try { text += '\n' + readFileSync(f, 'utf8'); } catch {} }
-  return Object.fromEntries(Object.entries(WRITTEN).map(([s, re]) => [s, re.test(text)]));
-}
-
-function lines(s) { return s ? String(s).split('\n').length : 0; }
-
-export function exposure({ root = join(homedir(), '.claude', 'projects'), days = DAYS } = {}) {
-  const since = days ? Date.now() - days * 864e5 : 0;
-  const WINDOW = 3;   // a check may come a turn or two later: count code as unchecked only if none ran in the next 3 turns
-  const c = { turns: 0, working: 0, code: 0, unverified: 0, risky: 0, big: 0, shipped: 0, ui: 0, copy: 0, renames: 0, asked: 0 };
-  let turn = null, T = [];
-  const close = () => {
-    if (!turn) return;
-    c.turns++; T.push(turn);
-    if (turn.tools) {
-      c.working++;
-      if (turn.code) c.code++;
-      if (turn.risky) c.risky++; if (turn.added >= BIG) c.big++; if (turn.ship) c.shipped++; if (turn.ui) c.ui++; if (turn.copy) c.copy++; if (turn.rename) c.renames++;
-      if (/\?\s*$/.test(turn.last)) c.asked++;
-    }
-    turn = null;
-  };
-  const endSession = () => {
-    close();
-    T.forEach((t, i) => { if (t.code && !T.slice(i, i + 1 + WINDOW).some((x) => x.verified)) c.unverified++; });
-    T = [];
-  };
-  const onTool = (b) => {
-    turn.tools++;
-    const i = b.input || {};
-    if (b.name === 'Bash') {
-      const cmd = String(i.command || '');
-      if (VERIFY.test(cmd)) turn.verified = true;
-      const rm = cmd.match(RM);
-      if (RISKY_CMD.test(cmd) || (rm && !RM_SAFE.test(rm[1]))) turn.risky = true;
-      if (SHIP.test(cmd)) turn.ship = true;
-      if (/\bgit mv\b/.test(cmd)) turn.rename = true;
-    } else if (b.name === 'Edit' || b.name === 'Write' || b.name === 'MultiEdit') {
-      const p = String(i.file_path || '');
-      if (CODE.test(p) && !SCRATCH.test(p)) turn.code++;
-      if (UI.test(p)) turn.ui = true;
-      if (COPY.test(p)) turn.copy = true;
-      if (RISKY_PATH.test(p)) turn.risky = true;
-      if (i.replace_all) turn.rename = true;
-      turn.added += Math.max(0, lines(i.content || i.new_string) - lines(i.old_string));
-    }
-  };
-  readHistory(root, {
-    onSession: endSession,
-    onEvent: (e) => {
-      if (since && e.timestamp && Date.parse(e.timestamp) < since) return;
-      if (e.type === 'user') {
-        if (typedText(e.message) === null) return;
-        close();
-        turn = { tools: 0, code: 0, verified: false, risky: false, added: 0, ship: false, ui: false, copy: false, rename: false, last: '' };
-      } else if (turn && Array.isArray(e.message && e.message.content)) {
-        for (const b of e.message.content) {
-          if (b.type === 'text') turn.last = b.text || turn.last;
-          if (b.type === 'tool_use') onTool(b);
-        }
-      }
-    },
-  });
-  return c;
-}
-if (import.meta.url === `file://${process.argv[1]}`) console.log(JSON.stringify(exposure()));

package/providers/claude.mjs

@@ -1,49 +0,0 @@
-#!/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

@@ -1,55 +0,0 @@
-#!/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/mem0.mjs

@@ -1,120 +0,0 @@
-#!/usr/bin/env node
-// mem0.mjs, a REFERENCE semantic memory provider for Sawbuck's Memory Contract: Mem0 (mem0.ai) as the
-// memory.
-//
-// STATUS: VERIFIED against the live Mem0 platform v3 API on 2026-10-31. /v3/memories/search/ and
-// /v3/memories/add/ both returned 200 with the documented shapes (search -> { results: [...] }, add ->
-// { event_id, ... }) using the Token auth header. Offline degrade (no key -> [], debt unsupported) is
-// also tested. Adapt the query/scoping to taste; the wire calls are known-good.
-//
-// It is the THIRD contract implementation and a deliberately DIFFERENT axis from the other two:
-// a networked, LLM-backed semantic store, where logbook is deterministic git-truth and obsidian is
-// local notes. Because of that it is the one provider that is NOT offline: it needs the NETWORK and a
-// MEM0_API_KEY. So it is an OPTIONAL provider isolated behind the socket, never part of the zero-network
-// glue. Zero npm deps (Node >= 18 global fetch).
-//
-// Opt in: SAWBUCK_MEMORY=logbook,mem0 and MEM0_API_KEY=... (compose it WITH logbook so logbook stays the
-// git-truth + debt provider and Mem0 adds recalled semantic context).
-//
-//   recall --file P [--file Q] --json   semantic search of your Mem0 memories -> Finding[] (kind note)
-//   record --ref SHA --summary S --by WHO [--side X] [--evidence-file F]   add the finding as a memory
-//   debt   --json                        EXITS NONZERO: a semantic store is not git-aware (git-truth
-//                                         lives in a git provider like logbook); the contract skips it.
-//
-// Config: MEM0_API_KEY, or a `~/.mem0` key file (a plain token, or JSON with api_key/key); without a
-// key recall degrades to [] and record errors. Also MEM0_USER_ID (scope override), MEM0_NAMESPACE
-// (id prefix), MEM0_BASE_URL (default https://api.mem0.ai), MEM0_TIMEOUT_MS (default 8000). NOTE:
-// record SENDS the finding text to Mem0's service (your opt-in).
-
-import { readFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { homedir } from 'node:os';
-
-// the API key: MEM0_API_KEY, else a ~/.mem0 file (a plain token, or JSON with api_key/apiKey/key).
-function mem0Key() {
-  if (process.env.MEM0_API_KEY) return process.env.MEM0_API_KEY;
-  try {
-    const raw = readFileSync(join(homedir(), '.mem0'), 'utf8').trim();
-    if (raw.startsWith('{')) { const j = JSON.parse(raw); return j.api_key || j.apiKey || j.key || ''; }
-    return raw.split(/\s+/)[0] || '';
-  } catch { return ''; }
-}
-
-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 = (msg, code = 2) => { process.stderr.write(`mem0 provider: ${msg}\n`); process.exit(code); };
-
-// FOLDER SCOPING: each folder scope maps to a Mem0 user_id. --scope carries the chain, leaf-first
-// (paths relative to the memory root; "" is the root/shared scope). recall queries self + ancestors
-// and merges; record writes to the LEAF scope. MEM0_NAMESPACE prefixes the ids (keep them from
-// colliding with other Mem0 usage in the same account); MEM0_USER_ID, if set, overrides to a single
-// flat scope. With no --scope (direct call), it falls back to the repo folder name.
-const NS = process.env.MEM0_NAMESPACE || '';
-const scopeUid = (id) => process.env.MEM0_USER_ID || [NS, id || 'root'].filter(Boolean).join(':');
-const scopeUids = (scopes) => {
-  if (process.env.MEM0_USER_ID) return [process.env.MEM0_USER_ID];
-  if (scopes.length) return [...new Set(scopes.map(scopeUid))];
-  return [basename(process.cwd()) || 'sawbuck']; // back-compat: no scope passed
-};
-
-// one bounded POST to the Mem0 platform; null on any network/HTTP/auth failure, so a read never hangs
-// or crashes the caller. (A semantic recall is on-demand, never per-turn, so the timeout is generous.)
-async function post(path, body, key) {
-  const base = (process.env.MEM0_BASE_URL || 'https://api.mem0.ai').replace(/\/$/, '');
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), +(process.env.MEM0_TIMEOUT_MS) || 8000);
-  try {
-    const r = await fetch(base + path, {
-      method: 'POST',
-      headers: { Authorization: `Token ${key}`, 'Content-Type': 'application/json', Accept: 'application/json' },
-      body: JSON.stringify(body),
-      signal: ctrl.signal,
-    });
-    if (!r.ok) return null;
-    return await r.json();
-  } catch { return null; } finally { clearTimeout(timer); }
-}
-
-if (cmd === 'debt') {
-  die('debt is unsupported by a semantic store (git-truth lives in a git provider like logbook)', 2);
-}
-
-if (cmd === 'recall') {
-  const key = mem0Key();
-  if (!key) { console.log('[]'); process.exit(0); }                 // no key -> no memories, not an error
-  const paths = flagAll('--file');
-  if (!paths.length) { console.log('[]'); process.exit(0); }
-  const query = `code, decisions, and gotchas related to: ${paths.map((p) => basename(p)).join(', ')}`;
-  const seen = new Set();
-  const findings = [];
-  // one search per scope's user_id (self + ancestors), merged; isolated from sibling scopes.
-  for (const uid of scopeUids(flagAll('--scope'))) {
-    const res = await post('/v3/memories/search/', { query, filters: { user_id: uid }, top_k: 8 }, key);
-    for (const m of (res && Array.isArray(res.results) ? res.results : [])) {
-      if (!m.memory || seen.has(m.id)) continue;
-      seen.add(m.id);
-      findings.push({ kind: 'note', path: null, ref: m.id || null, date: (m.created_at || '').slice(0, 10) || null, summary: String(m.memory).slice(0, 280), scope: uid, score: typeof m.score === 'number' ? m.score : null });
-    }
-  }
-  console.log(JSON.stringify(findings.slice(0, 8)));
-  process.exit(0);
-}
-
-if (cmd === 'record') {
-  const key = mem0Key();
-  if (!key) die('cannot record: MEM0_API_KEY is unset', 2);
-  const ref = String(flag('--ref', '')), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
-  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
-  const leaf = flagAll('--scope')[0];
-  const userId = process.env.MEM0_USER_ID || (leaf !== undefined ? scopeUid(leaf) : (basename(process.cwd()) || 'sawbuck'));
-  const metadata = { sawbuck: 'finding', ref, by, scope: leaf ?? '', ...(side ? { side: String(side) } : {}), ...(evidence ? { evidence: String(evidence) } : {}) };
-  // infer:false stores the finding verbatim (no LLM extraction); we want the exact note, not a paraphrase.
-  const res = await post('/v3/memories/add/', { messages: [{ role: 'user', content: summary }], user_id: userId, metadata, infer: false }, key);
-  if (res === null) die('record failed (network or auth)', 1);
-  console.log('recorded');
-  process.exit(0);
-}
-
-die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/obsidian.mjs

@@ -1,119 +0,0 @@
-#!/usr/bin/env node
-// obsidian.mjs, a REFERENCE memory provider for Sawbuck's Memory Contract: an Obsidian vault as the
-// memory. Shows how to fill the socket, and the second contract implementation. Zero-dep. Opt in with
-// SAWBUCK_MEMORY=logbook,obsidian and OBSIDIAN_VAULT=/path/to/vault (compose it WITH logbook: logbook
-// stays the git-truth + debt provider, this adds your written notes).
-//
-//   recall --file P [--file Q] [--scope ID ...] --json   notes relevant to those paths -> Finding[] (kind note)
-//   record --ref SHA --summary S --by WHO [--scope ID]   write a note into the vault
-//   debt   --json                        EXITS NONZERO: a note vault cannot know what is silenced in HEAD
-//
-// FOLDER SCOPING (isolation): --scope carries the folder scope chain, leaf-first, as paths relative to
-// the memory root (Sawbuck computes them; "" is the vault root = shared/global). The vault MIRRORS the
-// project tree: notes for scope "group/repo" live in `<vault>/group/repo/`. recall searches the LEAF
-// scope recursively (so the repo's own notes + its Sawbuck/ folder are found) and each ANCESTOR scope
-// TOP-LEVEL ONLY (so it never descends into a sibling repo's folder). With no --scope it searches the
-// whole vault (direct calls / back-compat). record writes to the LEAF scope's Sawbuck/ folder.
-
-import { readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, existsSync } from 'node:fs';
-import { join, basename, relative, extname, resolve, sep } 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 VAULT = process.env.OBSIDIAN_VAULT ? resolve(process.env.OBSIDIAN_VAULT) : '';
-const die = (msg, code = 2) => { process.stderr.write(`obsidian provider: ${msg}\n`); process.exit(code); };
-
-const MAX_FILES = +(process.env.OBSIDIAN_MAX_FILES) || 4000;
-const MAX_BYTES = 512 * 1024;
-
-// resolve a scope id to a dir INSIDE the vault; null if it would escape (path-traversal guard).
-function scopeDir(id) {
-  if (id === '' || id == null) return VAULT;
-  const p = resolve(VAULT, id);
-  return (p === VAULT || p.startsWith(VAULT + sep)) ? p : null;
-}
-// collect .md files; recursive for the leaf scope, top-level only for an ancestor (so an ancestor
-// search never descends into a sibling repo's folder).
-function walkMd(dir, recursive, out) {
-  let entries = [];
-  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
-  for (const e of entries) {
-    if (out.length >= MAX_FILES) return;
-    if (e.name.startsWith('.') || e.name === 'node_modules') continue;
-    const p = join(dir, e.name);
-    if (e.isDirectory()) { if (recursive) walkMd(p, true, out); }
-    else if (extname(e.name).toLowerCase() === '.md') out.push(p);
-  }
-}
-// the dirs to search, with their scope id and recursion, from the --scope chain (leaf-first).
-function searchScopes(scopes) {
-  if (!scopes.length) return [{ id: '', dir: VAULT, recursive: true }]; // no scope -> whole vault
-  const out = []; const seen = new Set();
-  scopes.forEach((id, i) => {
-    const dir = scopeDir(id);
-    if (!dir || seen.has(dir)) return; seen.add(dir);
-    out.push({ id, dir, recursive: i === 0 }); // leaf recursive; ancestors top-level only
-  });
-  if (!seen.has(VAULT)) out.push({ id: '', dir: VAULT, recursive: false }); // vault root is the shared scope
-  return out;
-}
-
-if (cmd === 'debt') {
-  die('debt is unsupported by a note vault (git-truth lives in a git provider like logbook)', 2);
-}
-
-if (cmd === 'recall') {
-  if (!VAULT || !existsSync(VAULT)) { console.log('[]'); process.exit(0); }
-  const paths = flagAll('--file');
-  if (!paths.length) { console.log('[]'); process.exit(0); }
-  const needles = [...new Set(paths.flatMap((p) => [p, basename(p)]).filter(Boolean))];
-  const findings = [];
-  for (const { id, dir, recursive } of searchScopes(flagAll('--scope'))) {
-    const files = []; walkMd(dir, recursive, files);
-    for (const file of files) {
-      let text = '';
-      try { if (statSync(file).size > MAX_BYTES) continue; text = readFileSync(file, 'utf8'); } catch { continue; }
-      const hitPath = paths.find((p) => text.includes(p) || text.includes(basename(p)));
-      if (!hitPath) continue;
-      let hits = 0; for (const n of needles) hits += text.split(n).length - 1;
-      const title = (text.match(/^#\s+(.+)$/m) || [, basename(file, '.md')])[1].trim();
-      const lineWith = (text.split('\n').find((l) => needles.some((n) => l.includes(n))) || '').trim().slice(0, 160);
-      let date = null; try { date = new Date(statSync(file).mtimeMs).toISOString().slice(0, 10); } catch {}
-      findings.push({ kind: 'note', path: hitPath, ref: relative(VAULT, file), date, summary: `${title}: ${lineWith}`.slice(0, 280), scope: id, score: Math.min(1, hits / 5), _hits: hits });
-    }
-  }
-  findings.sort((a, b) => b._hits - a._hits || String(b.date).localeCompare(String(a.date)));
-  console.log(JSON.stringify(findings.slice(0, 8).map(({ _hits, ...f }) => f)));
-  process.exit(0);
-}
-
-if (cmd === 'record') {
-  if (!VAULT || !existsSync(VAULT)) die('cannot record: OBSIDIAN_VAULT is unset or missing', 2);
-  const ref = flag('--ref', ''), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
-  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
-  const leaf = flagAll('--scope')[0] ?? '';
-  const base = scopeDir(leaf) || VAULT;                 // the finding belongs to its most-specific scope
-  const dir = join(base, 'Sawbuck');
-  try { mkdirSync(dir, { recursive: true }); } catch {}
-  const safeRef = String(ref || Date.now()).replace(/[^\w.-]/g, '_').slice(0, 40);
-  const date = new Date().toISOString();
-  // 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`;
-  // 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); }
-}
-
-die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);