verderer 0.1.0 → 0.3.0

package/README.md

@@ -13,9 +13,12 @@ Validated on a real repo before a line of this tool existed: of 3 long-standing
 ## 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)
+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 verdict 9f2c dead --evidence "derived it from neighboring code"
+                                         # record an inquest (id prefix is enough)
+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.
@@ -27,6 +30,17 @@ 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:
@@ -40,17 +54,19 @@ Verderer checks how git sees each harness file and adapts:
   "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" }
+  "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.
 
+`verderer verdict` records one: it stamps today's date and the ledger's current model, so the next model change flags it as stale. Evidence is required.
+
 ## 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.
+- 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verderer",
-  "version": "0.1.0",
+  "version": "0.3.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": {

package/src/cli.js

@@ -1,13 +1,20 @@
 import { resolve } from 'node:path';
 import { scan } from './scan.js';
-import { loadLedger, ledgerPath } from './ledger.js';
+import { loadLedger, saveLedger, ledgerPath, staleVerdicts, recordVerdict, 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 probe          print the manual ablation recipe (automation is the roadmap)
+  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 verdict <id> <result> [dir] --evidence <text>
+                                         record an inquest: dead | derivable | needed (id prefix is enough)
+  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
@@ -15,14 +22,28 @@ The ledger adapts to how git sees each harness file:
 `;
 
 export async function run(argv) {
-  const [cmd, dirArg] = argv;
-  const dir = resolve(dirArg ?? '.');
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--model') flags.model = argv[++i];
+    else if (argv[i] === '--evidence') flags.evidence = argv[++i];
+    else positional.push(argv[i]);
+  }
+
+  const [cmd, ...args] = positional;
+  const dir = resolve(args[0] ?? '.');
 
   switch (cmd) {
     case 'scan':
       return cmdScan(dir);
     case 'status':
       return cmdStatus(dir);
+    case 'checkpoint':
+      return cmdCheckpoint(dir, flags.model);
+    case 'verdict': {
+      const [id, result, dirArg] = args;
+      return cmdVerdict(resolve(dirArg ?? '.'), id, result, flags.evidence);
+    }
     case 'probe':
       return cmdProbe();
     case undefined:
@@ -38,7 +59,7 @@ export async function run(argv) {
 }
 
 function cmdScan(dir) {
-  const { counts, modes, path } = scan(dir);
+  const { ledger, counts, modes, path, modelChange, stale } = scan(dir);
   const sources = Object.entries(modes);
 
   if (sources.length === 0) {
@@ -51,6 +72,16 @@ function cmdScan(dir) {
   }
   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.');
   }
@@ -66,9 +97,13 @@ function cmdStatus(dir) {
     return 1;
   }
 
-  console.log(`scanned ${ledger.scannedAt} · ${ledger.rules.length} rules\n`);
+  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) {
-    const verdict = rule.lastVerdict ? `${rule.lastVerdict.result} (${rule.lastVerdict.date})` : 'unexamined';
+    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)}`);
@@ -77,6 +112,47 @@ function cmdStatus(dir) {
   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 cmdVerdict(dir, id, result, evidence) {
+  const prior = loadLedger(dir);
+
+  if (prior.rules.length === 0) {
+    console.error(`no ledger at ${ledgerPath(dir)} — run \`verderer scan\` first`);
+    return 1;
+  }
+
+  try {
+    const { ledger, rule } = recordVerdict(prior, id, result, { evidence });
+    saveLedger(dir, ledger);
+    console.log(`${rule.id}  ${result} on ${rule.lastVerdict.model}`);
+    console.log(`  ${truncate(rule.text, 100)}`);
+    return 0;
+  } catch (err) {
+    console.error(err.message);
+    console.error('usage: verderer verdict <id> <dead|derivable|needed> [dir] --evidence <text>');
+    return 1;
+  }
+}
+
 function cmdProbe() {
   console.log(`probe automation is on the roadmap. The manual recipe (validated on a real repo):
 
@@ -88,7 +164,8 @@ function cmdProbe() {
      - 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.
+5. Record it: verderer verdict <id> <dead|derivable|needed> --evidence "..."
+   then prune with evidence.
 
 Verdicts are judgment calls on blast radius — verderer reports, you decide. It never auto-deletes.`);
   return 0;

package/src/ledger.js

@@ -24,7 +24,7 @@ export function saveLedger(dir, 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() } = {}) {
+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 = [];
@@ -58,11 +58,46 @@ export function mergeScan(ledger, scanned, { modes, today = isoToday() } = {}) {
   }
 
   return {
-    ledger: { version: LEDGER_VERSION, scannedAt: today, modes, rules: rules.map(stripBlame) },
+    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);
+}
+
+export const VERDICTS = ['dead', 'derivable', 'needed'];
+
+// Stamp a verdict on one rule, found by id prefix (like a git sha).
+// The verdict records the ledger's current model so a later model change
+// can flag it as stale; without a model there is nothing to judge against.
+export function recordVerdict(ledger, prefix, result, { evidence, today = isoToday() } = {}) {
+  if (!VERDICTS.includes(result)) {
+    throw new Error(`verdict must be one of: ${VERDICTS.join(', ')}`);
+  }
+
+  if (!evidence) throw new Error('a verdict needs --evidence');
+
+  const model = ledger.model?.id;
+  if (!model) throw new Error('no model recorded — run `verderer scan` or `verderer checkpoint --model <id>` first');
+
+  const matches = prefix ? ledger.rules.filter((r) => r.id.startsWith(prefix)) : [];
+  if (matches.length === 0) throw new Error(`no rule matches id ${prefix ?? '(none)'}`);
+  if (matches.length > 1) throw new Error(`id ${prefix} is ambiguous: ${matches.map((r) => r.id).join(', ')}`);
+
+  const [rule] = matches;
+  const verdict = { date: today, result, model, evidence };
+
+  return {
+    ledger: { ...ledger, rules: ledger.rules.map((r) => (r === rule ? { ...r, lastVerdict: verdict } : r)) },
+    rule: { ...rule, lastVerdict: verdict },
+  };
+}
+
 function stripBlame({ blame, ...rule }) {
   return rule;
 }

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/scan.js

@@ -2,7 +2,8 @@ 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';
+import { detectModel } from './model.js';
+import { loadLedger, saveLedger, mergeScan, staleVerdicts, isoToday } from './ledger.js';
 
 export const SOURCES = ['CLAUDE.md', 'AGENTS.md'];
 
@@ -25,8 +26,19 @@ export function scan(dir) {
     }
   }
 
-  const { ledger, counts } = mergeScan(loadLedger(dir), scanned, { modes });
+  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 };
+  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),
+  };
 }