verderer 0.2.0 → 0.3.0

package/README.md

@@ -16,6 +16,8 @@ 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)
 ```
 
@@ -58,6 +60,8 @@ For tools without a detection adapter yet, `verderer checkpoint --model <id>` re
 
 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verderer",
-  "version": "0.2.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,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, 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:
@@ -125,6 +132,27 @@ function cmdCheckpoint(dir, modelId) {
   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

@@ -70,6 +70,34 @@ export function staleVerdicts(ledger) {
   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;
 }