verderer 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Velazquez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# verderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A rule ledger for AI agent harnesses.** Per-rule provenance for `CLAUDE.md` / `AGENTS.md`, plus ablation inquests that tell you which rules still earn their place — so a model upgrade retires rules with evidence instead of making you throw the harness away.
+
+A verderer was the officer of the royal forest: he kept its law, held inquests, and answered for what the law was still for. That's this tool's job for your harness.
+
+## The problem
+
+Every harness rule is a patch over a model weakness, frozen at the moment you wrote it. Models improve; the repo matures until the code itself carries the convention; the rules stay — costing tokens every session, and sometimes actively fighting a model that outgrew them. The common answer is ritual: delete everything every six months and see what breaks. Verderer replaces the ritual with a ledger and evidence.
+
+Validated on a real repo before a line of this tool existed: of 3 long-standing `CLAUDE.md` rules probed by ablation, 1 was dead (the model derived the convention from neighboring code and said so), 1 was derivable (kept as cheap insurance against an expensive miss), and 1 reduced to a single clause — everything else it stated, the model already did unaided. ~1 hour, 3 headless runs.
+
+## Usage
+
+```bash
+npx verderer scan                        # inventory harness rules into .claude/verderer.json
+npx verderer status                      # active/retired rules, provenance, verdicts
+npx verderer checkpoint --model <id>     # record the model by hand (tools without an adapter)
+npx verderer probe                       # the ablation recipe (automation is the roadmap)
+```
+
+`scan` is idempotent and append-only: known rules keep their provenance and verdicts, new rules are dated, rules that left the file are marked retired — never deleted. The ledger is the history of your harness's law.
+
+## Two modes, decided by git
+
+Verderer checks how git sees each harness file and adapts:
+
+- **tracked** — provenance comes free: `git blame` dates every rule (and the date tells you which model era it was written against). Pruning is a normal commit or PR; rollback is git.
+- **ignored** — a deliberate privacy choice some repos make. There is no history, so the ledger carries provenance itself: first scan records rules as `origin: unknown`, everything after is dated. Consider tracking `.claude/verderer.json` even while the harness stays private — the decisions get history without exposing the content.
+
+## Model changes
+
+Verderer never polls for releases. The question that matters is narrower: **is this repo running on a different model than the one your verdicts were judged against?** Every verdict records its model; `scan` reads the model id the repo actually ran on from the agent tool's own session logs (Claude Code transcripts today — concrete ids, so a stable `"opus"` alias doesn't hide an upgrade underneath) and flags verdicts judged on another model as stale:
+
+```
+model changed: claude-fable-5 → claude-fable-5-1
+3 verdict(s) rendered against another model are stale — re-run their inquests.
+```
+
+For tools without a detection adapter yet, `verderer checkpoint --model <id>` records it by hand.
+
+## The ledger
+
+`.claude/verderer.json` — one entry per rule:
+
+```json
+{
+  "id": "9f2c01ab34de",
+  "text": "ESM only; imports use `.js` extensions even in TS source.",
+  "source": "CLAUDE.md",
+  "section": "Conventions",
+  "firstSeen": "2026-03-17",
+  "origin": "git:da89e1b",
+  "status": "active",
+  "lastVerdict": { "date": "2026-10-31", "result": "dead", "model": "claude-fable-5", "evidence": "ablation probe: model derived it from neighboring code" }
+}
+```
+
+Verdicts are three-valued on purpose: **dead** (the model does it unaided), **derivable** (unaided but an expensive miss — keeping it is cheap insurance), **needed**. Blast radius is a judgment call, so verderer reports and you decide; it never auto-deletes a rule.
+
+## Roadmap
+
+- `probe` automation: per-rule ablation worktrees + headless runs + verdict recording (today it prints the validated manual recipe).
+- Model-detection adapters beyond Claude Code (Codex sessions next); the ledger core is already tool-agnostic.
+- More sources: `.claude/agents/*.md`, `GEMINI.md`, `.cursor/rules/`, skills.
+
+## Development
+
+```bash
+npm test   # node --test
+```
+
+No dependencies. Node ≥ 20.
+
+## Who built this
+
+Built by [Victor Velázquez](https://victorvelazquez.dev) — COO at [MagmaLabs](https://www.magmalabs.io) and author of [*The Agentic Engineer*](https://leanpub.com/theagenticengineer). Sibling of [banneret](https://github.com/vicmaster/banneret) (sub-agent pipeline) and [reeve](https://github.com/vicmaster/reeve) (MCP guardrails): banneret disciplines how agents work, verderer audits what you tell them.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/verderer.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "verderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A rule ledger for AI agent harnesses: per-rule provenance for CLAUDE.md/AGENTS.md, plus ablation inquests that tell you which rules still earn their place after a model upgrade.",
+  "type": "module",
+  "bin": {
+    "verderer": "bin/verderer.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude-code",
+    "agents",
+    "harness",
+    "claude-md",
+    "ablation",
+    "prompt-engineering"
+  ],
+  "author": "Victor Velázquez (https://victorvelazquez.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vicmaster/verderer.git"
+  }
+}

package/src/cli.js

@@ -0,0 +1,148 @@
+import { resolve } from 'node:path';
+import { scan } from './scan.js';
+import { loadLedger, saveLedger, ledgerPath, staleVerdicts, isoToday } from './ledger.js';
+
+const HELP = `verderer — a rule ledger for AI agent harnesses
+
+Usage:
+  verderer scan [dir]                    inventory harness rules (CLAUDE.md, AGENTS.md) into .claude/verderer.json
+  verderer status [dir]                  show the ledger: active/retired rules, provenance, verdicts
+  verderer checkpoint [dir] --model <id> record the model by hand (for tools without a detection adapter)
+  verderer probe                         print the manual ablation recipe (automation is the roadmap)
+
+Scan also records which model the repo is actually running on (read from the
+agent tool's own session logs — Claude Code today) and flags verdicts rendered
+against a different model as stale.
+
+The ledger adapts to how git sees each harness file:
+  tracked   → provenance comes free from git blame; prune via normal commits/PRs
+  ignored   → the ledger carries provenance itself; consider tracking the ledger file
+`;
+
+export async function run(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--model') flags.model = argv[++i];
+    else positional.push(argv[i]);
+  }
+
+  const [cmd, dirArg] = positional;
+  const dir = resolve(dirArg ?? '.');
+
+  switch (cmd) {
+    case 'scan':
+      return cmdScan(dir);
+    case 'status':
+      return cmdStatus(dir);
+    case 'checkpoint':
+      return cmdCheckpoint(dir, flags.model);
+    case 'probe':
+      return cmdProbe();
+    case undefined:
+    case '--help':
+    case '-h':
+      console.log(HELP);
+      return 0;
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      console.log(HELP);
+      return 1;
+  }
+}
+
+function cmdScan(dir) {
+  const { ledger, counts, modes, path, modelChange, stale } = scan(dir);
+  const sources = Object.entries(modes);
+
+  if (sources.length === 0) {
+    console.error('no harness files found (looked for CLAUDE.md, AGENTS.md)');
+    return 1;
+  }
+
+  for (const [source, mode] of sources) {
+    console.log(`${source} (${mode})`);
+  }
+  console.log(`${counts.active} active · ${counts.added} new · ${counts.retired} retired → ${path}`);
+
+  if (ledger.model) {
+    console.log(`model: ${ledger.model.id} (${ledger.model.source})`);
+  }
+  if (modelChange) {
+    console.log(`model changed: ${modelChange.from} → ${modelChange.to}`);
+  }
+  if (stale.length > 0) {
+    console.log(`${stale.length} verdict(s) rendered against another model are stale — re-run their inquests.`);
+  }
+
+  if (sources.some(([, mode]) => mode === 'ignored')) {
+    console.log('note: an ignored harness file has no git history — the ledger IS the provenance. Consider tracking .claude/verderer.json even if the harness stays private.');
+  }
+
+  return 0;
+}
+
+function cmdStatus(dir) {
+  const ledger = loadLedger(dir);
+
+  if (ledger.rules.length === 0) {
+    console.error(`no ledger at ${ledgerPath(dir)} — run \`verderer scan\` first`);
+    return 1;
+  }
+
+  const model = ledger.model ? ` · model ${ledger.model.id}` : '';
+  console.log(`scanned ${ledger.scannedAt}${model} · ${ledger.rules.length} rules\n`);
+
+  const stale = new Set(staleVerdicts(ledger).map((r) => r.id));
+  for (const rule of ledger.rules) {
+    let verdict = rule.lastVerdict ? `${rule.lastVerdict.result} (${rule.lastVerdict.date})` : 'unexamined';
+    if (stale.has(rule.id)) verdict += ' [stale: judged on ' + rule.lastVerdict.model + ']';
+    const flag = rule.status === 'retired' ? ' [retired]' : '';
+    console.log(`${rule.id}  ${rule.firstSeen}  ${verdict}${flag}`);
+    console.log(`  ${rule.section ? rule.section + ' · ' : ''}${truncate(rule.text, 100)}`);
+  }
+
+  return 0;
+}
+
+function cmdCheckpoint(dir, modelId) {
+  if (!modelId) {
+    console.error('usage: verderer checkpoint [dir] --model <id>');
+    return 1;
+  }
+
+  const ledger = loadLedger(dir);
+  const prior = ledger.model?.id;
+  ledger.model = { id: modelId, source: 'manual', detectedAt: isoToday() };
+  saveLedger(dir, ledger);
+
+  console.log(prior && prior !== modelId ? `model changed: ${prior} → ${modelId}` : `model: ${modelId}`);
+  const stale = staleVerdicts(ledger);
+  if (stale.length > 0) {
+    console.log(`${stale.length} verdict(s) rendered against another model are stale — re-run their inquests.`);
+  }
+
+  return 0;
+}
+
+function cmdProbe() {
+  console.log(`probe automation is on the roadmap. The manual recipe (validated on a real repo):
+
+1. git worktree add --detach <tmp>/probe <branch>   # one worktree per suspect rule
+2. Copy the harness file in and delete ONE rule.
+3. In the worktree, run a task that forces exactly that decision:
+     claude -p "<task>" --permission-mode acceptEdits
+4. Inspect the result: did the model do the right thing without the rule?
+     - yes, by reading the codebase → the rule is dead (the code now carries the convention)
+     - yes, but a miss would be expensive → derivable; keeping it is cheap insurance
+     - no → the rule still earns its place
+5. Record the verdict in the ledger, prune with evidence.
+
+Verdicts are judgment calls on blast radius — verderer reports, you decide. It never auto-deletes.`);
+  return 0;
+}
+
+function truncate(s, n) {
+  const flat = s.replace(/\s+/g, ' ');
+  return flat.length <= n ? flat : flat.slice(0, n - 1) + '…';
+}

package/src/git.js

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+
+function git(dir, args) {
+  return spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
+}
+
+// How git sees a harness file: that decides where provenance comes from.
+// 'tracked'   → git blame is the ledger's provenance, snapshots are free.
+// 'ignored'   → deliberate privacy; the ledger must carry provenance itself.
+// 'untracked' → in a repo but not committed (yet).
+// 'no-git'    → not a repository.
+export function fileMode(dir, relPath) {
+  const inRepo = git(dir, ['rev-parse', '--is-inside-work-tree']);
+  if (inRepo.status !== 0) return 'no-git';
+
+  if (git(dir, ['check-ignore', '-q', relPath]).status === 0) return 'ignored';
+  if (git(dir, ['ls-files', '--error-unmatch', relPath]).status === 0) return 'tracked';
+
+  return 'untracked';
+}
+
+// line number (1-based) → { sha, date } for a tracked file, null otherwise.
+export function blameDates(dir, relPath) {
+  const res = git(dir, ['blame', '--porcelain', '--', relPath]);
+  if (res.status !== 0) return null;
+
+  const byLine = new Map();
+  const timeBySha = new Map();
+  let sha = null;
+  let finalLine = null;
+
+  for (const line of res.stdout.split('\n')) {
+    const head = line.match(/^([0-9a-f]{40}) \d+ (\d+)(?: \d+)?$/);
+    if (head) {
+      sha = head[1];
+      finalLine = Number(head[2]);
+      byLine.set(finalLine, { sha: sha.slice(0, 7), date: timeBySha.get(sha) ?? null });
+      continue;
+    }
+
+    const time = line.match(/^author-time (\d+)$/);
+    if (time && sha !== null) {
+      const date = new Date(Number(time[1]) * 1000).toISOString().slice(0, 10);
+      timeBySha.set(sha, date);
+      byLine.set(finalLine, { sha: sha.slice(0, 7), date });
+    }
+  }
+
+  return byLine;
+}

package/src/ledger.js

@@ -0,0 +1,79 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export const LEDGER_VERSION = 1;
+
+export function ledgerPath(dir) {
+  return join(dir, '.claude', 'verderer.json');
+}
+
+export function loadLedger(dir) {
+  const path = ledgerPath(dir);
+  if (!existsSync(path)) return { version: LEDGER_VERSION, rules: [] };
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function saveLedger(dir, ledger) {
+  const path = ledgerPath(dir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(ledger, null, 2) + '\n');
+  return path;
+}
+
+// Merge a fresh scan into the existing ledger.
+// Known rules keep their provenance and verdicts; new ones get firstSeen
+// (from git blame when the file is tracked, else today); rules that left
+// the file are retired, never deleted — the ledger is append-only history.
+export function mergeScan(ledger, scanned, { modes, model, today = isoToday() } = {}) {
+  const existing = new Map(ledger.rules.map((r) => [r.id, r]));
+  const seen = new Set();
+  const rules = [];
+  const counts = { active: 0, added: 0, retired: 0 };
+
+  for (const rule of scanned) {
+    seen.add(rule.id);
+    const prior = existing.get(rule.id);
+
+    if (prior) {
+      rules.push({ ...prior, text: rule.text, source: rule.source, section: rule.section, line: rule.line, status: 'active', retiredAt: undefined });
+      counts.active++;
+      continue;
+    }
+
+    rules.push({
+      ...rule,
+      status: 'active',
+      firstSeen: rule.blame?.date ?? today,
+      origin: rule.blame?.sha ? `git:${rule.blame.sha}` : 'unknown',
+      lastVerdict: null,
+    });
+    counts.added++;
+  }
+
+  for (const prior of ledger.rules) {
+    if (seen.has(prior.id)) continue;
+    const alreadyRetired = prior.status === 'retired';
+    rules.push(alreadyRetired ? prior : { ...prior, status: 'retired', retiredAt: today });
+    if (!alreadyRetired) counts.retired++;
+  }
+
+  return {
+    ledger: { version: LEDGER_VERSION, scannedAt: today, modes, model: model ?? ledger.model, rules: rules.map(stripBlame) },
+    counts,
+  };
+}
+
+// A verdict was rendered against one model; a different model makes it stale.
+export function staleVerdicts(ledger) {
+  const current = ledger.model?.id;
+  if (!current) return [];
+  return ledger.rules.filter((r) => r.status === 'active' && r.lastVerdict?.model && r.lastVerdict.model !== current);
+}
+
+function stripBlame({ blame, ...rule }) {
+  return rule;
+}
+
+export function isoToday() {
+  return new Date().toISOString().slice(0, 10);
+}

package/src/model.js

@@ -0,0 +1,42 @@
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// What model is this repo actually running on? Not "what did the vendor
+// release" and not the settings alias ("opus" stays stable while the model
+// under it changes) — the concrete id recorded in the tool's own session
+// logs. Claude Code is the first adapter; others follow the same contract:
+// (dir) → { id, source } | null.
+export function detectModel(dir, { home = homedir() } = {}) {
+  return fromClaudeTranscripts(dir, home);
+}
+
+const RECENT_TRANSCRIPTS = 5;
+
+function fromClaudeTranscripts(dir, home) {
+  const slug = dir.replace(/[^a-zA-Z0-9]/g, '-');
+  const projectDir = join(home, '.claude', 'projects', slug);
+  if (!existsSync(projectDir)) return null;
+
+  const transcripts = readdirSync(projectDir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => join(projectDir, f))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+    .slice(0, RECENT_TRANSCRIPTS);
+
+  for (const file of transcripts) {
+    const id = lastModelIn(readFileSync(file, 'utf8'));
+    if (id) return { id, source: 'claude-transcripts' };
+  }
+
+  return null;
+}
+
+function lastModelIn(text) {
+  let last = null;
+  for (const match of text.matchAll(/"model":"([^"]+)"/g)) {
+    if (match[1].startsWith('<')) continue; // "<synthetic>" and friends
+    last = match[1];
+  }
+  return last;
+}

package/src/parse.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+
+// A "rule" is a top-level bullet in a harness file. Continuation lines
+// (indented 2+ spaces) belong to the bullet above; nested bullets too —
+// they qualify the rule, they are not rules of their own.
+export function parseRules(markdown, source) {
+  const rules = [];
+  let section = '';
+  let current = null;
+
+  const flush = () => {
+    if (!current) return;
+    const text = current.lines.join('\n').trim();
+    rules.push({
+      id: ruleId(text),
+      text,
+      source,
+      section,
+      line: current.line,
+    });
+    current = null;
+  };
+
+  const lines = markdown.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const heading = line.match(/^#{1,6}\s+(.*)/);
+
+    if (heading) {
+      flush();
+      section = heading[1].trim();
+      continue;
+    }
+
+    if (/^- /.test(line)) {
+      flush();
+      current = { lines: [line.slice(2)], line: i + 1 };
+      continue;
+    }
+
+    if (current && /^\s{2,}\S/.test(line)) {
+      current.lines.push(line.trim());
+      continue;
+    }
+
+    flush();
+  }
+  flush();
+
+  return rules;
+}
+
+// Stable across reformatting: whitespace collapses before hashing.
+export function ruleId(text) {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  return createHash('sha1').update(normalized).digest('hex').slice(0, 12);
+}

package/src/scan.js

@@ -0,0 +1,44 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseRules } from './parse.js';
+import { fileMode, blameDates } from './git.js';
+import { detectModel } from './model.js';
+import { loadLedger, saveLedger, mergeScan, staleVerdicts, isoToday } from './ledger.js';
+
+export const SOURCES = ['CLAUDE.md', 'AGENTS.md'];
+
+export function scan(dir) {
+  const modes = {};
+  const scanned = [];
+
+  for (const source of SOURCES) {
+    const path = join(dir, source);
+    if (!existsSync(path)) continue;
+
+    const mode = fileMode(dir, source);
+    modes[source] = mode;
+
+    const rules = parseRules(readFileSync(path, 'utf8'), source);
+    const blame = mode === 'tracked' ? blameDates(dir, source) : null;
+
+    for (const rule of rules) {
+      scanned.push(blame ? { ...rule, blame: blame.get(rule.line) ?? null } : rule);
+    }
+  }
+
+  const prior = loadLedger(dir);
+  const detected = detectModel(dir);
+  const model = detected ? { ...detected, detectedAt: isoToday() } : prior.model;
+
+  const { ledger, counts } = mergeScan(prior, scanned, { modes, model });
+  const path = saveLedger(dir, ledger);
+
+  return {
+    ledger,
+    counts,
+    modes,
+    path,
+    modelChange: prior.model?.id && model?.id && prior.model.id !== model.id ? { from: prior.model.id, to: model.id } : null,
+    stale: staleVerdicts(ledger),
+  };
+}