verderer 0.3.0 → 0.4.0

package/README.md

@@ -23,6 +23,8 @@ npx verderer probe                       # the ablation recipe (automation is th
 
 `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:
@@ -54,13 +56,13 @@ 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 and the ledger's current model, so the next model change flags it as stale. Evidence is required.
+`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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verderer",
-  "version": "0.3.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, recordVerdict, 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
 
@@ -70,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})`);
@@ -79,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')) {
@@ -100,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)}`);
@@ -126,7 +126,7 @@ 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;

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,32 @@ 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'];
@@ -90,7 +121,7 @@ export function recordVerdict(ledger, prefix, result, { evidence, today = isoTod
   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 };
+  const verdict = { date: today, result, model, evidence, ruleId: rule.id };
 
   return {
     ledger: { ...ledger, rules: ledger.rules.map((r) => (r === rule ? { ...r, lastVerdict: verdict } : r)) },

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) ?? []);
+}