verderer 0.2.0 → 0.4.0

package/README.md

@@ -16,11 +16,15 @@ Validated on a real repo before a line of this tool existed: of 3 long-standing
 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.
 
+Rewording a rule doesn't reset it. A rule edited in place (same spot, mostly the same words, or a trim of them) keeps its provenance and verdict, and its old wording goes into `revisions`. The verdict judged the old wording, so it shows as stale until you re-run the inquest.
+
 ## Two modes, decided by git
 
 Verderer checks how git sees each harness file and adapts:
@@ -52,12 +56,14 @@ For tools without a detection adapter yet, `verderer checkpoint --model <id>` re
   "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" }
+  "lastVerdict": { "date": "2026-10-31", "result": "dead", "model": "claude-fable-5", "evidence": "ablation probe: model derived it from neighboring code", "ruleId": "9f2c01ab34de" }
 }
 ```
 
 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, the ledger's current model and the rule's wording, so a model change or a rewording 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verderer",
-  "version": "0.2.0",
+  "version": "0.4.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,6 +1,6 @@
 import { resolve } from 'node:path';
 import { scan } from './scan.js';
-import { loadLedger, saveLedger, ledgerPath, staleVerdicts, isoToday } from './ledger.js';
+import { loadLedger, saveLedger, ledgerPath, staleVerdicts, staleReason, recordVerdict, isoToday } from './ledger.js';
 
 const HELP = `verderer — a rule ledger for AI agent harnesses
 
@@ -8,6 +8,8 @@ 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 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
@@ -24,11 +26,12 @@ export async function run(argv) {
   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, dirArg] = positional;
-  const dir = resolve(dirArg ?? '.');
+  const [cmd, ...args] = positional;
+  const dir = resolve(args[0] ?? '.');
 
   switch (cmd) {
     case 'scan':
@@ -37,6 +40,10 @@ export async function run(argv) {
       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:
@@ -63,7 +70,7 @@ function cmdScan(dir) {
   for (const [source, mode] of sources) {
     console.log(`${source} (${mode})`);
   }
-  console.log(`${counts.active} active · ${counts.added} new · ${counts.retired} retired → ${path}`);
+  console.log(`${counts.active} active · ${counts.added} new · ${counts.reworded} reworded · ${counts.retired} retired → ${path}`);
 
   if (ledger.model) {
     console.log(`model: ${ledger.model.id} (${ledger.model.source})`);
@@ -72,7 +79,7 @@ function cmdScan(dir) {
     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.`);
+    console.log(`${stale.length} stale verdict(s): judged on another model or an earlier wording — re-run their inquests.`);
   }
 
   if (sources.some(([, mode]) => mode === 'ignored')) {
@@ -93,10 +100,10 @@ function cmdStatus(dir) {
   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 stale = staleReason(rule, ledger.model?.id);
+    if (stale) verdict += ` [stale: ${stale}]`;
     const flag = rule.status === 'retired' ? ' [retired]' : '';
     console.log(`${rule.id}  ${rule.firstSeen}  ${verdict}${flag}`);
     console.log(`  ${rule.section ? rule.section + ' · ' : ''}${truncate(rule.text, 100)}`);
@@ -119,12 +126,33 @@ function cmdCheckpoint(dir, modelId) {
   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.`);
+    console.log(`${stale.length} stale verdict(s): judged on another model or an earlier wording — 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):
 
@@ -136,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

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { pairRewordings } from './reword.js';
 
 export const LEDGER_VERSION = 1;
 
@@ -21,17 +22,18 @@ export function saveLedger(dir, ledger) {
 }
 
 // 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.
+// Known rules keep their provenance and verdicts; reworded rules too, with
+// the old wording kept in `revisions`; 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 seen = new Set(scanned.map((r) => r.id));
+  const rewordings = pairRewordings(ledger.rules, scanned);
   const rules = [];
-  const counts = { active: 0, added: 0, retired: 0 };
+  const counts = { active: 0, added: 0, reworded: 0, retired: 0 };
 
   for (const rule of scanned) {
-    seen.add(rule.id);
     const prior = existing.get(rule.id);
 
     if (prior) {
@@ -40,6 +42,14 @@ export function mergeScan(ledger, scanned, { modes, model, today = isoToday() }
       continue;
     }
 
+    const before = rewordings.get(rule.id);
+    if (before) {
+      rules.push(reword(before, rule, today));
+      seen.add(before.id);
+      counts.reworded++;
+      continue;
+    }
+
     rules.push({
       ...rule,
       status: 'active',
@@ -63,11 +73,60 @@ export function mergeScan(ledger, scanned, { modes, model, today = isoToday() }
   };
 }
 
-// A verdict was rendered against one model; a different model makes it stale.
+// The same rule in new words: new id and text, old provenance and verdict.
+// The verdict remembers which wording it judged, so it reads as stale now.
+function reword(before, rule, today) {
+  return {
+    ...before,
+    id: rule.id,
+    text: rule.text,
+    source: rule.source,
+    section: rule.section,
+    line: rule.line,
+    revisions: [...(before.revisions ?? []), { id: before.id, text: before.text, until: today }],
+    lastVerdict: before.lastVerdict && { ruleId: before.id, ...before.lastVerdict },
+  };
+}
+
+// A verdict judged one wording on one model; a change to either makes it stale.
+export function staleReason(rule, modelId) {
+  const verdict = rule.lastVerdict;
+  if (rule.status !== 'active' || !verdict) return null;
+  if (verdict.ruleId && verdict.ruleId !== rule.id) return 'judged an earlier wording';
+  if (modelId && verdict.model && verdict.model !== modelId) return `judged on ${verdict.model}`;
+  return null;
+}
+
 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);
+  return ledger.rules.filter((r) => staleReason(r, ledger.model?.id));
+}
+
+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, ruleId: rule.id };
+
+  return {
+    ledger: { ...ledger, rules: ledger.rules.map((r) => (r === rule ? { ...r, lastVerdict: verdict } : r)) },
+    rule: { ...rule, lastVerdict: verdict },
+  };
 }
 
 function stripBlame({ blame, ...rule }) {

package/src/reword.js

@@ -0,0 +1,71 @@
+// A rule's id is a hash of its text, so rewording a rule looks like one rule
+// leaving and another arriving. Pair them back up so the rule keeps its
+// provenance and verdict.
+//
+// Two checks, both calibrated on real harness files:
+// - same slot: a rewording is an edit in place, so both sit right after the
+//   same unchanged rule. This keeps rolling lists (add at top, drop at the
+//   bottom) and templated sibling bullets from pairing up.
+// - similar words: Dice over word sets >= 0.4, or a trim that keeps every
+//   word of the shorter wording ("ESM only; imports use .js" → "ESM only").
+const MIN_SIMILARITY = 0.4;
+const MIN_SHARED_WORDS = 2;
+
+// prior: every rule in the ledger; scanned: the rules in the files now.
+// Returns Map(new id → the prior rule it rewords).
+export function pairRewordings(prior, scanned) {
+  const known = new Set(prior.map((r) => r.id));
+  const current = new Set(scanned.map((r) => r.id));
+  const active = prior.filter((r) => r.status === 'active');
+  const unchanged = new Set(active.filter((r) => current.has(r.id)).map((r) => r.id));
+
+  const departed = slotted(active, unchanged).filter(({ rule }) => !current.has(rule.id));
+  const arrived = slotted(scanned, unchanged).filter(({ rule }) => !known.has(rule.id));
+
+  const candidates = [];
+  for (const before of departed) {
+    for (const after of arrived) {
+      if (before.slot !== after.slot) continue;
+      const score = similarity(before.rule.text, after.rule.text);
+      if (score !== null) candidates.push({ before: before.rule, after: after.rule, score });
+    }
+  }
+
+  const pairs = new Map();
+  const taken = new Set();
+  for (const { before, after } of candidates.sort((a, b) => b.score - a.score)) {
+    if (pairs.has(after.id) || taken.has(before.id)) continue;
+    pairs.set(after.id, before);
+    taken.add(before.id);
+  }
+
+  return pairs;
+}
+
+// Dice coefficient over word sets, or null when the texts don't look like
+// the same rule.
+export function similarity(a, b) {
+  const wordsA = words(a);
+  const wordsB = words(b);
+  const shared = [...wordsA].filter((w) => wordsB.has(w)).length;
+  const dice = (2 * shared) / (wordsA.size + wordsB.size || 1);
+  const trimmed = shared >= MIN_SHARED_WORDS && shared === Math.min(wordsA.size, wordsB.size);
+
+  return dice >= MIN_SIMILARITY || trimmed ? dice : null;
+}
+
+// Where a rule sits: its file and the nearest unchanged rule above it.
+// Rules are in file order (the ledger keeps scan order).
+function slotted(rules, unchanged) {
+  const anchors = new Map();
+
+  return rules.map((rule) => {
+    const slot = `${rule.source}:${anchors.get(rule.source) ?? ''}`;
+    if (unchanged.has(rule.id)) anchors.set(rule.source, rule.id);
+    return { rule, slot };
+  });
+}
+
+function words(text) {
+  return new Set(text.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+}