verderer 0.1.0 → 0.2.0

package/README.md

@@ -13,9 +13,10 @@ 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 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 +28,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,7 +52,7 @@ 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" }
 }
 ```
 
@@ -49,8 +61,8 @@ Verdicts are three-valued on purpose: **dead** (the model does it unaided), **de
 ## 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.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": {

package/src/cli.js

@@ -1,13 +1,18 @@
 import { resolve } from 'node:path';
 import { scan } from './scan.js';
-import { loadLedger, ledgerPath } from './ledger.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 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 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,7 +20,14 @@ The ledger adapts to how git sees each harness file:
 `;
 
 export async function run(argv) {
-  const [cmd, dirArg] = 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) {
@@ -23,6 +35,8 @@ export async function run(argv) {
       return cmdScan(dir);
     case 'status':
       return cmdStatus(dir);
+    case 'checkpoint':
+      return cmdCheckpoint(dir, flags.model);
     case 'probe':
       return cmdProbe();
     case undefined:
@@ -38,7 +52,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 +65,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 +90,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 +105,26 @@ 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 cmdProbe() {
   console.log(`probe automation is on the roadmap. The manual recipe (validated on a real repo):
 

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,18 @@ 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);
+}
+
 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),
+  };
 }