verderer 0.0.0-stage → 0.1.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,69 @@
-# 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 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.
+
+## 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", "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-upgrade trigger: re-examine `unexamined`/`needed` rules when the configured model changes.
+- More sources: `.claude/agents/*.md`, 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.1.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,100 @@
+import { resolve } from 'node:path';
+import { scan } from './scan.js';
+import { loadLedger, ledgerPath } 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 probe          print the manual ablation recipe (automation is the roadmap)
+
+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 [cmd, dirArg] = argv;
+  const dir = resolve(dirArg ?? '.');
+
+  switch (cmd) {
+    case 'scan':
+      return cmdScan(dir);
+    case 'status':
+      return cmdStatus(dir);
+    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 { counts, modes, path } = 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 (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;
+  }
+
+  console.log(`scanned ${ledger.scannedAt} · ${ledger.rules.length} rules\n`);
+  for (const rule of ledger.rules) {
+    const verdict = rule.lastVerdict ? `${rule.lastVerdict.result} (${rule.lastVerdict.date})` : 'unexamined';
+    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 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,72 @@
+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, 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, rules: rules.map(stripBlame) },
+    counts,
+  };
+}
+
+function stripBlame({ blame, ...rule }) {
+  return rule;
+}
+
+export function isoToday() {
+  return new Date().toISOString().slice(0, 10);
+}

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,32 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseRules } from './parse.js';
+import { fileMode, blameDates } from './git.js';
+import { loadLedger, saveLedger, mergeScan } 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 { ledger, counts } = mergeScan(loadLedger(dir), scanned, { modes });
+  const path = saveLedger(dir, ledger);
+
+  return { ledger, counts, modes, path };
+}