@rigour-labs/core 6.7.2 → 6.7.5

package/dist/review/reviewer/rule-writer.test.js

@@ -0,0 +1,52 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../../types/index.js';
+import { ruleWriterFor } from './rule-writer.js';
+let repo;
+let bin;
+const originalPath = process.env.PATH;
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'rule-writer-'));
+    execFileSync('git', ['-C', repo, 'init', '-q', '-b', 'main']);
+    bin = fs.mkdtempSync(path.join(os.tmpdir(), 'rule-writer-bin-'));
+    fs.writeFileSync(path.join(bin, process.platform === 'win32' ? 'claude.cmd' : 'claude'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+    process.env.PATH = [bin, originalPath ?? ''].join(path.delimiter);
+});
+afterEach(() => {
+    process.env.PATH = originalPath;
+    for (const dir of [repo, bin])
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+/** Answers git for real, the fake claude with a priced reply, and any other copy of claude as not installed. */
+function fake(calls) {
+    return async (command, args, options) => {
+        if (command === 'git')
+            return { exitCode: 0, stdout: execFileSync('git', args, { cwd: options.cwd, encoding: 'utf8' }), stderr: '' };
+        if (!command.startsWith(bin))
+            return { exitCode: 127, stdout: '', stderr: 'not found' };
+        if (args[0] === '--version')
+            return { exitCode: 0, stdout: '2.1.0 (Claude Code)\n', stderr: '' };
+        calls.push({ args, unset: options.unset });
+        return { exitCode: 0, stdout: JSON.stringify({ result: '{"rules":[]}', total_cost_usd: 0.6 }), stderr: '' };
+    };
+}
+describe('the rule writer', () => {
+    it('runs the team reviewer CLI isolated like a judge, counts its cost, and stops at the daily cap', async () => {
+        const calls = [];
+        const config = ConfigSchema.parse({ version: 1, review: { reviewer: { reviewers: ['claude'], max_usd_per_day: 1 } } });
+        const write = (await ruleWriterFor(repo, config, fake(calls)));
+        expect(await write('first')).toBe('{"rules":[]}');
+        expect(await write('second')).toBe('{"rules":[]}'); // $0.60 spent: under the $1 cap
+        expect(await write('third')).toBeUndefined(); // $1.20: the cap is reached, no call made
+        expect(calls).toHaveLength(2);
+        expect(calls[0].args).toEqual(expect.arrayContaining(['--strict-mcp-config', '--disallowedTools', 'Edit', 'Write']));
+        expect(calls[0].unset).toContain('RIGOUR_API_KEY');
+    });
+    it('is not available when no reviewer CLI is installed', async () => {
+        const config = ConfigSchema.parse({ version: 1, review: { reviewer: { reviewers: ['codex'] } } });
+        expect(await ruleWriterFor(repo, config, fake([]))).toBeUndefined();
+    });
+});

package/dist/review/reviewer/settings.d.ts

@@ -35,6 +35,10 @@ export interface ResolvedReviewer {
     judges: 2 | 3;
     escalate: 'always' | 'risk';
     cross_models: Record<string, string>;
+    /** Environment variables each judge's CLI must not see (the team's, never a person's). */
+    judge_env: Record<string, {
+        unset: string[];
+    }>;
     /** Where the mode and the panel choice came from. */
     source: {
         mode: Source;

package/dist/review/reviewer/settings.js

@@ -13,7 +13,7 @@ const RANK = { single: 0, cross: 1, full: 2 };
 /** How near a layer is to this run: the nearer wins. */
 const NEAR = { flag: 0, env: 1, user: 2, team: 3 };
 export function resolveReviewer(config, choice = {}, user = loadSettings().reviewer, env = process.env) {
-    const team = config.review?.reviewer ?? { enabled: false, on_push: 'background', reviewers: ['claude'], mode: 'single', models: {}, timeout_ms: 15 * 60_000, panel: 'off', mode_required: false, panel_max_items: 20, dismissals: false, judges: 2, escalate: 'always', cross_models: {} };
+    const team = config.review?.reviewer ?? { enabled: false, on_push: 'background', reviewers: ['claude'], mode: 'single', models: {}, timeout_ms: 15 * 60_000, panel: 'off', mode_required: false, panel_max_items: 20, dismissals: false, judges: 2, escalate: 'always', cross_models: {}, judge_env: {} };
     const refused = [];
     const envMode = parseMode(env.RIGOUR_REVIEWER_MODE);
     const envPanel = parseSwitch(env.RIGOUR_REVIEWER_PANEL);
@@ -78,6 +78,7 @@ export function resolveReviewer(config, choice = {}, user = loadSettings().revie
         judges: floor ? Math.max(team.judges, user?.judges ?? team.judges) : user?.judges ?? team.judges,
         escalate: requiredEscalation(team, user, refused),
         cross_models: team.cross_models,
+        judge_env: team.judge_env ?? {},
         source: { mode: modeSource, panel: panelSource },
         required: { mode: team.mode_required, panel: requirePanel },
         refused,

package/dist/review/reviewer/verdict.d.ts

@@ -1,4 +1,4 @@
-import type { Spend, Tokens } from './adapters.js';
+import type { RunTrace, Spend, Tokens } from './adapters.js';
 import type { PanelItem } from './panel.js';
 export interface PriorPoint {
     point: string;
@@ -8,6 +8,9 @@ export interface PriorPoint {
     evidence?: string;
     checked_siblings?: string[];
     reviewer?: string;
+    file?: string;
+    line?: number;
+    quote?: string;
 }
 interface Redundant {
     file: string;
@@ -27,11 +30,7 @@ interface Read {
         applied_before_read: boolean;
     }>;
     narrower_source?: string | null;
-    keys?: Array<{
-        name: string;
-        inputs: string;
-        stable_under_edit: boolean;
-    }>;
+    keys?: Key[];
     window_bounded?: boolean | null;
     keyset?: boolean | null;
     reviewer?: string;
@@ -53,6 +52,48 @@ interface MergeImpactItem {
     why: string;
     reviewer?: string;
 }
+interface Key {
+    name: string;
+    inputs: string;
+    stable_under_edit: boolean;
+}
+interface JourneyItem {
+    file: string;
+    line?: number;
+    what: string;
+    cleared_by?: string | null;
+    retry_safe?: boolean | null;
+    overlap_safe?: boolean | null;
+    can_move_back?: boolean | null;
+    keys?: Key[];
+    reviewer?: string;
+}
+interface Sibling {
+    changed: string;
+    sibling: string;
+    needs_same_change: boolean;
+    has_it: boolean;
+    why?: string;
+    reviewer?: string;
+}
+interface Claim {
+    source: 'comment' | 'description';
+    claim: string;
+    file?: string;
+    line?: number;
+    holds: boolean;
+    evidence?: string;
+    reviewer?: string;
+}
+/** The judge's answer for one team lesson it was shown: does this change repeat it. */
+interface LessonCheck {
+    lesson: string;
+    applies: boolean;
+    file?: string;
+    line?: number;
+    evidence?: string;
+    reviewer?: string;
+}
 export interface Finding {
     class: string;
     file: string;
@@ -60,7 +101,11 @@ export interface Finding {
     issue: string;
     why?: string;
     consequence?: string;
+    input?: string;
+    quote?: string;
     reviewer?: string;
+    severity?: 'blocking' | 'should';
+    absent?: string;
 }
 export interface Verdict {
     prior_points: PriorPoint[];
@@ -68,6 +113,11 @@ export interface Verdict {
     reads: Read[];
     scans: Scan[];
     merge_impact: MergeImpactItem[];
+    /** Optional: a verdict cached before these steps existed has none. */
+    journey?: JourneyItem[];
+    siblings?: Sibling[];
+    claims?: Claim[];
+    lessons?: LessonCheck[];
     findings: Finding[];
     carried: string[];
     resolved_previous: Array<{
@@ -77,10 +127,13 @@ export interface Verdict {
     reviewer?: string;
     cost_usd?: number;
     tokens?: Tokens;
+    /** Where the run's tokens went and what it read (measurement only). */
+    trace?: RunTrace;
     reviewers?: Array<{
         reviewer: string;
         cost_usd?: number;
         tokens?: Tokens;
+        trace?: RunTrace;
     }>;
     /** With a panel: every judge's own item ids, and the panel's decision on each finding (reviewer/panel.ts). */
     panel?: {
@@ -90,7 +143,7 @@ export interface Verdict {
 }
 export interface OpenItem {
     id: string;
-    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'finding';
+    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'journey' | 'sibling' | 'claim' | 'lesson' | 'finding';
     class: string;
     file?: string;
     line?: number;
@@ -98,12 +151,21 @@ export interface OpenItem {
     evidence?: string;
     /** For a finding: the wrong outcome or the cost. A finding without one is a note, never a block. */
     consequence?: string;
+    /** For a finding: the input that goes wrong, and the code it quotes at file:line (checked against the checkout). */
+    input?: string;
+    quote?: string;
     reviewer?: string;
     /** In delta mode, how the item reached this verdict. */
     status?: 'carried' | 'not accounted for';
 }
-/** Checks a file (and a line) against the checkout; an item that fails cannot block. */
-export type Verify = (file: string, line: number | undefined) => boolean;
+/** Checks a file (and a line, and a quote of the code there) against the checkout; an item that fails cannot block. */
+export type Verify = (file: string, line: number | undefined, quote?: string) => boolean;
+/**
+ * A file in the checkout, and a line it has: an item naming anything else is a reviewer's slip. With a quote, the
+ * quoted code must also be there, within QUOTE_WINDOW lines of the line named (whitespace aside): a claim about code
+ * that is not where the judge says it is never blocks, whichever model made it.
+ */
+export declare function checkoutVerifier(cwd: string): Verify;
 /** The verdict in a reviewer's answer, or why it is not one. `needsPriorPoints`: a human review exists and none of its points is carried. */
 export declare function parseVerdict(text: string, needsPriorPoints: boolean, reviewer: string, spend: Spend): {
     verdict: Verdict;

package/dist/review/reviewer/verdict.js

@@ -8,8 +8,48 @@
  * its end, is a reviewer's slip, reported apart and never a block.
  */
 import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { textSimilarity } from './consensus.js';
+/**
+ * A file in the checkout, and a line it has: an item naming anything else is a reviewer's slip. With a quote, the
+ * quoted code must also be there, within QUOTE_WINDOW lines of the line named (whitespace aside): a claim about code
+ * that is not where the judge says it is never blocks, whichever model made it.
+ */
+export function checkoutVerifier(cwd) {
+    const files = new Map();
+    const squash = (text) => text.replace(/\s+/g, ' ').trim();
+    return (file, line, quote) => {
+        if (!files.has(file)) {
+            try {
+                files.set(file, fs.readFileSync(path.join(cwd, file), 'utf8').split('\n'));
+            }
+            catch {
+                files.set(file, undefined);
+            }
+        }
+        const lines = files.get(file);
+        if (!lines || (line !== undefined && line > lines.length))
+            return false;
+        if (quote === undefined)
+            return true;
+        const wanted = squash(quote);
+        if (!wanted)
+            return false;
+        const span = quote.split('\n').length;
+        const from = line === undefined ? 0 : Math.max(0, line - 1 - QUOTE_WINDOW);
+        const to = line === undefined ? lines.length : line - 1 + span + QUOTE_WINDOW;
+        return squash(lines.slice(from, to).join('\n')).includes(wanted);
+    };
+}
+/** How far from the line it names a finding's quote may sit: judges count lines loosely. */
+const QUOTE_WINDOW = 3;
+/** How alike a finding and a point a human accepted as non-blocking must read to be that point again. */
+const ACCEPTED_SIMILARITY = 0.4;
+/** The reviewer's working steps: shown so a person can follow the reasoning, never a block on their own. */
+const WORKING_NOTES = new Set(['redundant', 'read', 'scan', 'merge', 'journey', 'sibling', 'claim', 'lesson']);
 const SHAPE = ['prior_points', 'reads', 'findings'];
-const LISTS = ['redundant', 'scans', 'merge_impact', 'carried', 'resolved_previous'];
+const LISTS = ['redundant', 'scans', 'merge_impact', 'journey', 'siblings', 'claims', 'lessons', 'carried', 'resolved_previous'];
 /** The verdict in a reviewer's answer, or why it is not one. `needsPriorPoints`: a human review exists and none of its points is carried. */
 export function parseVerdict(text, needsPriorPoints, reviewer, spend) {
     const parsed = verdictIn(text);
@@ -20,7 +60,7 @@ export function parseVerdict(text, needsPriorPoints, reviewer, spend) {
     for (const key of LISTS)
         if (!Array.isArray(parsed[key]))
             parsed[key] = [];
-    return { verdict: { ...parsed, reviewer, ...(spend.costUsd !== undefined ? { cost_usd: spend.costUsd } : {}), ...(spend.tokens ? { tokens: spend.tokens } : {}) } };
+    return { verdict: { ...parsed, reviewer, ...(spend.costUsd !== undefined ? { cost_usd: spend.costUsd } : {}), ...(spend.tokens ? { tokens: spend.tokens } : {}), ...(spend.trace ? { trace: spend.trace } : {}) } };
 }
 /** The whole answer, a fenced block, or the last object that starts with "prior_points" (a model sometimes writes a summary around it). */
 function verdictIn(text) {
@@ -62,10 +102,14 @@ export function mergeVerdicts(parts) {
         reads: tagged(part => part.reads),
         scans: tagged(part => part.scans),
         merge_impact: tagged(part => part.merge_impact),
+        journey: tagged(part => part.journey ?? []),
+        siblings: tagged(part => part.siblings ?? []),
+        claims: tagged(part => part.claims ?? []),
+        lessons: tagged(part => part.lessons ?? []),
         findings: tagged(part => part.findings),
         carried: parts.flatMap(part => part.carried),
         resolved_previous: parts.length === 1 ? parts[0].resolved_previous : parts[0].resolved_previous.filter(x => parts.every(part => part.resolved_previous.some(y => y.id === x.id))),
-        reviewers: parts.map(part => ({ reviewer: part.reviewer ?? '?', ...(part.cost_usd !== undefined ? { cost_usd: part.cost_usd } : {}), ...(part.tokens ? { tokens: part.tokens } : {}) })),
+        reviewers: parts.map(part => ({ reviewer: part.reviewer ?? '?', ...(part.cost_usd !== undefined ? { cost_usd: part.cost_usd } : {}), ...(part.tokens ? { tokens: part.tokens } : {}), ...(part.trace ? { trace: part.trace } : {}) })),
     };
 }
 /**
@@ -93,13 +137,19 @@ const id = (...parts) => createHash('sha1').update(parts.map(p => String(p ?? ''
 export function account(verdict, previousOpen, verify) {
     const open = [];
     const unverified = [];
+    const notes = [];
     const seen = new Set();
-    // A prior point is the human's and needs no file; anything else must name code the checkout has.
+    const accepted = verdict.prior_points.filter(p => p.severity === 'non-blocking');
+    // A prior point is the human's and needs no file. A finding blocks only when the code it quotes is at the line it
+    // names: any model's claim is checked, never trusted. What the working steps turned up is a note: the reasoning,
+    // shown, and a block only when the judge also makes it a finding it can quote.
     const add = (item) => {
         if (seen.has(item.id))
             return;
         seen.add(item.id);
-        const placed = item.kind === 'prior' || (!!item.file && verify(item.file, item.line));
+        if (WORKING_NOTES.has(item.kind))
+            return void notes.push(item);
+        const placed = !!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote);
         (placed ? open : unverified).push(item);
     };
     const answerInReply = [];
@@ -108,8 +158,9 @@ export function account(verdict, previousOpen, verify) {
             continue;
         if (p.severity === 'non-blocking')
             answerInReply.push(p);
+        // Still open only where the judge quotes the code that keeps it open: a point a later commit already fixed never blocks.
         else
-            add({ id: id('prior', p.review, p.point), kind: 'prior', class: 'prior point', issue: p.point, evidence: p.evidence, reviewer: p.reviewer });
+            add({ id: id('prior', p.review, p.point), kind: 'prior', class: 'prior point', issue: p.point, evidence: p.evidence, reviewer: p.reviewer, ...(p.file ? { file: p.file } : {}), ...(p.line ? { line: p.line } : {}), ...(p.quote ? { quote: p.quote } : {}) });
     }
     for (const r of verdict.redundant) {
         if (r.removed === false)
@@ -132,14 +183,49 @@ export function account(verdict, previousOpen, verify) {
         if (m.holds === false)
             add({ id: id('correctness', m.call_site, m.symbol), kind: 'merge', class: 'correctness', file: m.call_site.split(':')[0], line: Number(m.call_site.split(':')[1]) || undefined, issue: `${m.symbol} from ${m.main_file} changed in main: ${m.why}`, reviewer: m.reviewer });
     }
-    const notes = [];
+    for (const j of verdict.journey ?? []) {
+        const problems = [
+            ...(j.retry_safe === false ? ['a retry of the same request leaves it wrong'] : []),
+            ...(j.overlap_safe === false ? ['two overlapping runs leave it wrong'] : []),
+            ...(j.can_move_back === true ? ['can move a record back to an earlier status'] : []),
+            ...(j.keys ?? []).filter(k => k.stable_under_edit === false).map(k => `key ${k.name} changes when the user edits: ${k.inputs}`),
+        ];
+        for (const text of problems)
+            add({ id: id('correctness', j.file, j.what, text), kind: 'journey', class: 'correctness', file: j.file, line: j.line, issue: `${j.what}: ${text}`, reviewer: j.reviewer });
+    }
+    for (const sib of verdict.siblings ?? []) {
+        if (!sib.needs_same_change || sib.has_it)
+            continue;
+        const [file, line] = sib.sibling.split(':');
+        add({ id: id('correctness', sib.sibling, sib.changed), kind: 'sibling', class: 'correctness', file, line: Number(line) || undefined, issue: `needs the same change as ${sib.changed}${sib.why ? `: ${sib.why}` : ''}`, reviewer: sib.reviewer });
+    }
+    for (const c of verdict.claims ?? []) {
+        if (c.holds !== false)
+            continue;
+        add({ id: id('stale-claim', c.file, c.claim), kind: 'claim', class: 'stale-claim', file: c.file, line: c.line, issue: `the ${c.source} says "${c.claim}", and the code no longer does that`, evidence: c.evidence, reviewer: c.reviewer });
+    }
+    // A team lesson the change repeats: shown with the code, never a block on its own (the judge's finding, quoted, is).
+    for (const l of verdict.lessons ?? []) {
+        if (l.applies !== true)
+            continue;
+        add({ id: id('team-lesson', l.file, l.lesson), kind: 'lesson', class: 'team-lesson', file: l.file, line: l.line, issue: `repeats a team lesson: ${l.lesson}`, evidence: l.evidence, reviewer: l.reviewer });
+    }
     const stillOpen = new Set((previousOpen ?? []).map(item => item.id));
     for (const f of verdict.findings) {
-        const item = { id: id(f.class, f.file, f.issue), kind: 'finding', class: f.class, file: f.file, line: f.line, issue: f.issue, evidence: f.why, ...(f.consequence?.trim() ? { consequence: f.consequence.trim() } : {}), reviewer: f.reviewer };
+        const item = { id: id(f.class, f.file, f.issue), kind: 'finding', class: f.class, file: f.file, line: f.line, issue: f.issue, evidence: f.why, ...(f.consequence?.trim() ? { consequence: f.consequence.trim() } : {}), ...(f.input?.trim() ? { input: f.input.trim() } : {}), ...(f.quote?.trim() ? { quote: f.quote } : {}), reviewer: f.reviewer };
         // An opinion is a finding the judge said has no consequence: an empty one. A missing field fails closed, and an
         // item already open from the last round stays open until it is resolved with evidence.
         const opinion = typeof f.consequence === 'string' && !f.consequence.trim() && !stillOpen.has(item.id);
-        if (!opinion)
+        // Narrower than blocking by the judge's own severity, or a point a human already raised and accepted: shown, never a block.
+        const should = f.severity === 'should' || accepted.some(p => textSimilarity(item, { id: '', kind: 'prior', class: item.class, issue: p.point }) >= ACCEPTED_SIMILARITY);
+        // A claim that something is missing, about something the file has.
+        const present = !!f.absent?.trim() && !!f.file && verify(f.file, undefined, f.absent);
+        if (present) {
+            if (!seen.has(item.id))
+                unverified.push(item);
+            seen.add(item.id);
+        }
+        else if (!opinion && !should)
             add(item);
         else if (!notes.some(n => n.id === item.id))
             notes.push(item);
@@ -150,6 +236,12 @@ export function account(verdict, previousOpen, verify) {
         for (const item of previousOpen) {
             if (evidence.has(item.id))
                 resolved.push({ item, evidence: evidence.get(item.id) });
+            else if (WORKING_NOTES.has(item.kind)) {
+                // Open under the earlier rule that blocked on working notes: a note now, never carried as a block.
+                if (!seen.has(item.id))
+                    notes.push(item);
+                seen.add(item.id);
+            }
             else if (!seen.has(item.id)) {
                 seen.add(item.id);
                 open.push({ ...item, status: verdict.carried.includes(item.id) ? 'carried' : 'not accounted for' });
@@ -162,5 +254,5 @@ export function itemLine(item) {
     const where = item.file ? ` ${item.file}${item.line ? `:${item.line}` : ''}` : '';
     const by = item.reviewer ? ` (${item.reviewer})` : '';
     const status = item.status ? `, ${item.status}` : '';
-    return `[${item.class}${status}]${by}${where} ${item.issue}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
+    return `[${item.class}${status}]${by}${where} ${item.issue}${item.input ? `\n      input: ${item.input}` : ''}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.quote ? `\n      code: ${item.quote.trim().split('\n')[0].slice(0, 160)}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
 }

package/dist/review/reviewer.d.ts

@@ -4,7 +4,7 @@ import { type Exec, type Progress } from './reviewer/exec.js';
 import { type PanelItem } from './reviewer/panel.js';
 import { type RunChoice, type Source } from './reviewer/settings.js';
 import { type Accounting, type OpenItem, type PriorPoint } from './reviewer/verdict.js';
-export { defaultExec, githubEnv, parseJsonArrays, type Exec, type Progress } from './reviewer/exec.js';
+export { defaultExec, githubEnv, githubToken, parseJsonArrays, type Exec, type Progress } from './reviewer/exec.js';
 export { itemLine, type OpenItem } from './reviewer/verdict.js';
 export type ReviewerOutcome = 'passed' | 'findings' | 'unavailable' | 'skipped';
 export interface ReviewerOptions {
@@ -12,6 +12,8 @@ export interface ReviewerOptions {
     pr?: number;
     /** ISO time: a review or comment posted from then on is not shown to the reviewer (a backtest). */
     reviewsBefore?: string;
+    /** No pull request at all: the commit is reviewed alone, with no human review or description, and GitHub is never asked (a backtest round that names no pull request). */
+    blind?: boolean;
     /** At push the ready-pull-request rule applies; a review command or a backtest always reviews. */
     trigger?: 'push' | 'review' | 'backtest';
     /** Two vendors over the whole branch, never a delta: the step before requesting a human review. */
@@ -70,7 +72,8 @@ export interface ReviewerResult {
 }
 export interface ModeRecord {
     asked: 'single' | 'cross' | 'full' | 'panel';
-    ran: 'single' | 'cross' | 'full' | 'panel';
+    /** `none` when the review ended before any judge ran (unavailable or skipped); `degraded` or the reason says why. */
+    ran: 'single' | 'cross' | 'full' | 'panel' | 'none';
     source: Source;
     /** Why fewer judges ran than were asked for. */
     degraded?: string;

package/dist/review/reviewer.js

@@ -23,7 +23,7 @@ import os from 'os';
 import path from 'path';
 import { ADAPTERS, isReviewerName, resolveAdapter, selectReviewers, vendorsOf } from './reviewer/adapters.js';
 import { defaultExec, GH_TIMEOUT_MS, githubEnv } from './reviewer/exec.js';
-import { findPullRequest, ghFor, humanReviews, linesChanged, mergesBaseIn, rulesText, sha } from './reviewer/inputs.js';
+import { bodyAsOf, findPullRequest, ghFor, humanReviews, linesChanged, mergesBaseIn, rulesText, sha } from './reviewer/inputs.js';
 import { mergeImpact } from './reviewer/merge-impact.js';
 import { applyPanel, parseAnswers, runPanel } from './reviewer/panel.js';
 import { crossExamPrompt, deltaBlock, mergeBlock, PROMPT_VERSION, renderPrompt } from './reviewer/prompt.js';
@@ -32,8 +32,9 @@ import { VerdictStore } from './reviewer/store.js';
 import { trackUsage } from '../telemetry/telemetry.js';
 import { reviewerUsage } from './reviewer/usage.js';
 import { buildContext, dismissedAs, readReviewDismissals, relatedDocs } from './reviewer/context.js';
-import { account, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
-export { defaultExec, githubEnv, parseJsonArrays } from './reviewer/exec.js';
+import { account, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { judgeUnset } from './reviewer/judge-env.js';
+export { defaultExec, githubEnv, githubToken, parseJsonArrays } from './reviewer/exec.js';
 export { itemLine } from './reviewer/verdict.js';
 /** Findings and no verdict stop a push; a skipped review does not, and is reported as owed. */
 export function reviewerBlocks(result) {
@@ -57,11 +58,13 @@ async function review(cwd, base, config, exec, progress, options) {
     const branch = options.branch ?? await git(['rev-parse', '--abbrev-ref', 'HEAD']);
     const repoRoot = (await git(['rev-parse', '--show-toplevel'])) || cwd;
     let attempts;
+    // What was asked, from the first line: every verdict, a review that never ran included, says what was asked and what ran.
+    let modeRecord = askedOnly(settings);
     // A review that ends without a verdict says why where the person looks (status, Studio, MCP), not only in a log.
     const none = (outcome, reason, extra = {}) => {
         if (attempts && branch !== 'HEAD')
             attempts.recordAttempt(branch, { head, outcome, reason, at: new Date().toISOString() });
-        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra };
+        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra, mode: { ...modeRecord, ...extra.mode, ran: 'none' } };
     };
     if (!head || !baseSha)
         return none('unavailable', `not a repository, or ${base} is unknown`);
@@ -81,12 +84,12 @@ async function review(cwd, base, config, exec, progress, options) {
     let reviewers = selectReviewers(candidates, mode, authors, new Set(installed.keys()), settings.judges);
     if (reviewers.length === 0)
         return none('unavailable', `no reviewer installed: ${candidates.map(n => ADAPTERS[n].binary).join(', ') || 'review.reviewer.reviewers is empty'}`);
-    let modeRecord = modeRan(settings, reviewers, candidates, installed);
+    modeRecord = modeRan(settings, reviewers, candidates, installed);
     if (reviewers.length < 2 && mode === 'full' && (settings.required.panel || settings.required.mode)) {
         return none('unavailable', `rigour.yml requires two reviewers from different vendors, and ${modeRecord.degraded}`, { reviewers, mode: modeRecord });
     }
-    const gh = ghFor(cwd, exec, await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec));
-    const found = await findPullRequest(gh, branch, head, options.pr);
+    const gh = options.blind ? undefined : ghFor(cwd, exec, await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec));
+    const found = gh ? await findPullRequest(gh, branch, head, options.pr) : {};
     if (found.error)
         return none('unavailable', found.error, { reviewers });
     const pr = found.pr;
@@ -96,7 +99,7 @@ async function review(cwd, base, config, exec, progress, options) {
             return none('skipped', skip, { reviewers, pr: pr?.number });
     }
     let reviews = { markdown: 'none\n', key: '', count: 0 };
-    if (pr) {
+    if (gh && pr) {
         const read = await humanReviews(gh, pr, options.reviewsBefore);
         if (read.error)
             return none('unavailable', read.error, { reviewers, pr: pr.number });
@@ -105,7 +108,10 @@ async function review(cwd, base, config, exec, progress, options) {
     const stateRoot = options.stateRoot ?? cwd;
     // Dismissals count only where the team allows them; otherwise the file, if any, is ignored.
     const dismissals = settings.dismissals ? readReviewDismissals(stateRoot) : [];
-    const body = pr?.body || '(no pull request description)\n';
+    // A backtest sees the description as it read at the review, never a later edit describing later code.
+    const body = gh && pr && options.reviewsBefore
+        ? (await bodyAsOf(gh, pr.number, options.reviewsBefore)) ?? '(the description as of this review could not be recovered: judge claims against the code and its comments only)\n'
+        : pr?.body || '(no pull request description)\n';
     const rules = rulesText(cwd);
     const previous = branch !== 'HEAD' ? store.branchState(branch) : undefined;
     // The same commit, asked again with the same settings and reviews (the background run, then the person): the verdict it already has.
@@ -122,7 +128,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const sincePrevious = previousIsAncestor ? new Set((await git(['diff', '--name-only', `${previous.head}..HEAD`])).split('\n').filter(Boolean)) : new Set();
     const changedFiles = [...fullDiff.matchAll(/^diff --git a\/.* b\/(.*)$/gm)].map(m => m[1]);
     const context = buildContext({
-        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, touched: sincePrevious, checks: options.checks ?? [],
+        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, touched: sincePrevious, checks: options.checks ?? [],
         previousPanel: previousIsAncestor ? store.readJson(previous.verdict)?.panel?.items : undefined,
         docs: await relatedDocs(cwd, changedFiles, exec),
     });
@@ -167,7 +173,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const verdictFile = store.verdictPath(head, fingerprint);
     const openFile = store.openPath(verdictFile);
     const previousOpen = scope === 'delta' ? store.readJson(store.openPath(previous.verdict)) ?? [] : undefined;
-    const verify = verifier(cwd);
+    const verify = checkoutVerifier(cwd);
     if (!options.force && fs.existsSync(verdictFile) && fs.existsSync(openFile)) {
         const verdict = store.readJson(verdictFile);
         return result(decide(verdict, previousOpen, verify, dismissals), verdict, reviewers, scope, why, true, reviews, pr, modeRecord, settings.dismissals);
@@ -217,18 +223,28 @@ async function review(cwd, base, config, exec, progress, options) {
         try {
             const answers = await Promise.all(reviewers.map(async (name) => {
                 const adapter = ADAPTERS[name];
-                const run = await exec(installed.get(name).binary, adapter.args(prompt, modelFor(name)), { cwd, timeoutMs: settings.timeout_ms });
-                progress(`Rigour reviewer: ${name} finished in ${Math.round((Date.now() - started) / 1000)}s (exit ${run.exitCode})`);
-                const answer = adapter.answer(run.stdout);
-                store.addSpend(1, answer.costUsd); // every run counts against the caps, an answer or not
-                return run.exitCode === 0 || answer.text.trim()
-                    ? parseVerdict(answer.text, needsPriorPoints, name, answer)
-                    : { error: `${name}: no answer (exit ${run.exitCode}): ${run.stderr.trim().slice(-200)}` };
+                const ask = async () => {
+                    const run = await exec(installed.get(name).binary, adapter.args(prompt, modelFor(name)), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
+                    progress(`Rigour reviewer: ${name} finished in ${Math.round((Date.now() - started) / 1000)}s (exit ${run.exitCode})`);
+                    const answer = adapter.answer(run.stdout);
+                    store.addSpend(1, answer.costUsd); // every run counts against the caps, an answer or not
+                    return { run, answer, verdict: run.exitCode === 0 || answer.text.trim() ? parseVerdict(answer.text, needsPriorPoints, name, answer) : undefined };
+                };
+                let first = await ask();
+                // An answer that is not a verdict is a slip, not a decision: asked once more, inside the caps, before the review is unavailable.
+                if (first.verdict && 'error' in first.verdict && !overBudget(store.spend(), settings, 1)) {
+                    progress(`Rigour reviewer: ${name} gave no valid verdict; asking once more`);
+                    first = await ask();
+                }
+                return first.verdict ?? { error: `${name}: no answer (exit ${first.run.exitCode}): ${first.run.stderr.trim().slice(-200)}` };
             }));
             const failed = answers.find(a => 'error' in a);
             if (failed && 'error' in failed)
                 return none('unavailable', failed.error, { reviewers, scope, why, pr: pr?.number });
             parts = answers.map(a => a.verdict);
+            for (const part of parts)
+                if (part.trace)
+                    labelReads(part.trace, work, changedFiles);
         }
         finally {
             clearInterval(ticker);
@@ -260,7 +276,7 @@ async function review(cwd, base, config, exec, progress, options) {
                 },
                 ask: async (judge, asked) => {
                     const name = judge;
-                    const run = await exec(installed.get(name).binary, ADAPTERS[name].args(crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name)), { cwd, timeoutMs: settings.timeout_ms });
+                    const run = await exec(installed.get(name).binary, ADAPTERS[name].args(crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name)), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
                     const answer = ADAPTERS[name].answer(run.stdout);
                     store.addSpend(1, answer.costUsd);
                     reserved--;
@@ -320,16 +336,20 @@ function escalationFor(humanReviews, risky) {
         ? { escalate: true, why: `${risky} risky changed function(s)` }
         : { escalate: false, why: 'no risky changed function and no human review: one judge (review.reviewer.escalate: risk)' };
 }
-/** The mode asked for and the one the installed reviewers allow: a panel or full review needs two vendors. */
-function modeRan(settings, reviewers, candidates, installed) {
+/** What was asked and where the choice came from, before anything has run. */
+function askedOnly(settings) {
     const asked = settings.panel ? 'panel' : settings.mode;
-    const refused = settings.refused.length ? { refused: settings.refused } : {};
     const source = settings.panel ? settings.source.panel : settings.source.mode;
+    return { asked, ran: asked, source, ...(settings.refused.length ? { refused: settings.refused } : {}) };
+}
+/** The mode asked for and the one the installed reviewers allow: a panel or full review needs two vendors. */
+function modeRan(settings, reviewers, candidates, installed) {
+    const record = askedOnly(settings);
     if (settings.mode !== 'full' || reviewers.length >= settings.judges)
-        return { asked, ran: asked, source, ...refused };
+        return record;
     const missing = candidates.filter(name => !installed.has(name)).map(name => ADAPTERS[name].binary);
     const degraded = `${settings.judges} judges asked, ${reviewers.join(' and ')} could run (${missing.length ? `not installed: ${missing.join(', ')}` : 'no other vendor in review.reviewer.reviewers'})`;
-    return { asked, ran: reviewers.length > 1 ? asked : 'single', source, degraded, ...refused };
+    return { ...record, ran: reviewers.length > 1 ? record.asked : 'single', degraded };
 }
 /**
  * Before any checkout or typed review: whether this push gets a model review at all (an open, ready
@@ -344,6 +364,18 @@ export async function pushReviewSkip(cwd, branch, head, config, exec = defaultEx
     return skipReason(settings.on_push, branch, found.pr);
 }
 /** Why no model is asked at this push: `review.reviewer.on_push` and whether someone will read the push (an open, non-draft pull request). */
+/** What each tool call of a run read: one of Rigour's own input files, a file the change touched, another file, git, or a search. */
+function labelReads(trace, work, changed) {
+    const touched = new Set(changed);
+    for (const call of trace.calls) {
+        const target = call.target.replace(/\\/g, '/');
+        call.category = target.startsWith(work.replace(/\\/g, '/')) ? 'rigour-input'
+            : call.tool === 'Bash' && /^git\b/.test(target) ? 'git'
+                : call.tool === 'Grep' || call.tool === 'Glob' ? 'search'
+                    : call.tool === 'Read' ? ([...touched].some(f => target.endsWith(`/${f}`) || target === f) ? 'changed-file' : 'other-file')
+                        : 'other';
+    }
+}
 function skipReason(onPush, branch, pr) {
     if (onPush === 'off')
         return 'review.reviewer.on_push is off: run `rigour review --reviewer`';
@@ -355,23 +387,6 @@ function skipReason(onPush, branch, pr) {
         return `pull request #${pr.number} is ${pr.state}`;
     return undefined;
 }
-/** A file in the checkout, and a line it has: an item naming anything else is a reviewer's slip. */
-function verifier(cwd) {
-    const lengths = new Map();
-    return (file, line) => {
-        const target = path.join(cwd, file);
-        if (!lengths.has(file)) {
-            try {
-                lengths.set(file, fs.readFileSync(target, 'utf8').split('\n').length);
-            }
-            catch {
-                lengths.set(file, -1);
-            }
-        }
-        const length = lengths.get(file);
-        return length >= 0 && (line === undefined || line <= length);
-    };
-}
 function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr, mode, dismissable) {
     const cost = (verdict.reviewers ?? []).map(r => r.cost_usd).filter((c) => typeof c === 'number');
     const used = (verdict.reviewers ?? []).map(r => r.tokens).filter((t) => !!t);