@rigour-labs/core 6.7.1 → 6.7.4

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);

package/dist/review/reviewer.test.js

@@ -8,7 +8,7 @@ import { reviewerBlocks, runReviewer } from './reviewer.js';
 import { dismissReviewerFinding } from './reviewer/context.js';
 import { reviewStatus } from './reviewer/background.js';
 import { selectReviewers, vendorsOf } from './reviewer/adapters.js';
-import { account, carryResolved, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { account, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 let repo;
 const config = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'] } } });
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
@@ -49,6 +49,7 @@ function fakes(answer, seen, pr = PR) {
             return (seen.installed ?? ['claude', 'cursor-agent']).includes(binary) ? { exitCode: 0, stdout: `${seen.versions?.[command] ?? '1.0.0'}\n`, stderr: '' } : { exitCode: 127, stdout: '', stderr: 'not found' };
         seen.ran.push(command);
         (seen.args ??= []).push(args);
+        (seen.unset ??= []).push(options.unset);
         const name = binary === 'claude' ? 'claude' : binary === 'cursor-agent' ? 'cursor' : 'codex';
         const prompt = binary === 'claude' ? args[args.indexOf('-p') + 1] : args[args.length - 1];
         seen.prompts.push(prompt);
@@ -99,7 +100,7 @@ afterEach(() => {
 describe('the reviewer', () => {
     it('works from every human review with inline comments and the description, written to files, and blocks on an open point', async () => {
         const seen = seenNow();
-        const answer = JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: false, evidence: 'src/job.ts:2' }] });
+        const answer = JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: false, evidence: 'src/job.ts:2', file: 'src/job.ts', line: 2, quote: 'export function job() {' }] });
         const result = await runReviewer(repo, 'main', config, fakes(() => answer, seen), () => undefined);
         expect(seen.files['previous-reviews.md']).toContain('Review by senior');
         expect(seen.files['previous-reviews.md']).toContain('- 2026-10-03 src/job.ts:12: Check the lock before the first read.');
@@ -115,7 +116,7 @@ describe('the reviewer', () => {
     });
     it('caches the verdict per commit and inputs, so the same push is free, and the next commit gets a delta review that carries what is not accounted for', async () => {
         const seen = seenNow();
-        const open = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', consequence: 'a second run reads stale rows', why: 'x' }] });
+        const open = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'export function job() {', consequence: 'a second run reads stale rows', why: 'x' }] });
         const first = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined, { checks: ['src/job.ts:1 Unused export `job`'] });
         expect(first.items).toHaveLength(1);
         const again = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined, { checks: ['src/job.ts:1 Unused export `job`'] });
@@ -138,7 +139,7 @@ describe('the reviewer', () => {
     });
     it('resolves a previous item only with evidence, and never blocks on an item that names code the checkout does not have', async () => {
         const seen = seenNow();
-        const first = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: 'src/ghost.ts', line: 1, issue: 'unused', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: '', issue: 'somewhere, no file named', consequence: 'a second run reads stale rows' }] }), seen), () => undefined);
+        const first = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'export function job() {', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: 'src/ghost.ts', line: 1, issue: 'unused', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: '', issue: 'somewhere, no file named', consequence: 'a second run reads stale rows' }] }), seen), () => undefined);
         expect(first.items.map(i => i.file)).toEqual(['src/job.ts']);
         expect(first.unverified.map(i => i.file)).toEqual(['src/ghost.ts', '']); // a slip and a finding with no place to check: shown, never a block
         const id = first.items[0].id;
@@ -170,6 +171,32 @@ describe('the reviewer', () => {
         expect(seen.files['previous-reviews.md']).toContain('Review by senior');
         expect(shown).toMatchObject({ outcome: 'unavailable', reason: 'claude did not report on the human reviews' });
     });
+    it('for a backtest, gives the description as it read at the review, never a later edit', async () => {
+        const versions = { lastEditedAt: '2026-10-06T00:00:00Z', body: 'today: refunds are issued by the nightly job', userContentEdits: { totalCount: 3, nodes: [
+                    { editedAt: '2026-10-06T00:00:00Z', diff: 'today: refunds are issued by the nightly job' },
+                    { editedAt: '2026-10-02T00:00:00Z', diff: 'then: refunds are issued on request' },
+                    { editedAt: '2026-09-30T00:00:00Z', diff: 'first draft' },
+                ] } };
+        const withEdits = (answer, seen, graphql) => {
+            const base = fakes(answer, seen);
+            return async (command, args, options) => command === 'gh' && args[0] === 'api' && args[1] === 'graphql'
+                ? { exitCode: graphql ? 0 : 1, stdout: JSON.stringify({ data: { repository: { pullRequest: graphql } } }), stderr: '' }
+                : base(command, args, options);
+        };
+        const reply = () => JSON.stringify({ ...EMPTY, prior_points: [] });
+        const seen = seenNow();
+        await runReviewer(repo, 'main', config, withEdits(reply, seen, versions), () => undefined, { pr: 42, reviewsBefore: '2026-10-03T00:00:00Z', force: true });
+        expect(seen.files['pr-description.md']).toBe('then: refunds are issued on request');
+        await runReviewer(repo, 'main', config, withEdits(reply, seen, null), () => undefined, { pr: 42, reviewsBefore: '2026-10-03T00:00:00Z', force: true });
+        expect(seen.files['pr-description.md']).toContain('could not be recovered');
+    });
+    it('blind, reviews the commit alone and never asks GitHub', async () => {
+        const seen = seenNow();
+        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [] }), seen), () => undefined, { blind: true, trigger: 'backtest', force: true });
+        expect(result.outcome).toBe('passed');
+        expect(seen.ghArgs).toEqual([]);
+        expect(seen.files['previous-reviews.md']).toBe('none\n');
+    });
     it('never passes without a verdict: a crash, a malformed answer, an unreadable pull request or no installed reviewer', async () => {
         const crashed = await runReviewer(repo, 'main', config, fakes(() => ({ exitCode: 1, stdout: '', stderr: 'API error' }), seenNow()), () => undefined);
         expect(crashed).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('claude: no answer (exit 1)') });
@@ -182,9 +209,51 @@ describe('the reviewer', () => {
         for (const result of [crashed, prose])
             expect(reviewerBlocks(result)).toBe(true);
     });
+    it('keeps where each judge run spent its tokens and what it read, labelled, in the local verdict', async () => {
+        const seen = seenNow();
+        const base = fakes(() => JSON.stringify(EMPTY), seen);
+        const streaming = async (command, args, options) => {
+            if (path.basename(command).replace(/\.(cmd|exe)$/, '') !== 'claude' || args[0] === '--version')
+                return base(command, args, options); // claude.cmd on Windows
+            const prompt = args[args.indexOf('-p') + 1];
+            const diff = /(\S+full\.diff)/.exec(prompt)[1];
+            const call = (id, name, input) => ({ type: 'assistant', message: { id: `m-${id}`, usage: { input_tokens: 1, cache_read_input_tokens: 100, cache_creation_input_tokens: 10, output_tokens: 5 }, content: [{ type: 'tool_use', id, name, input }] } });
+            const events = [
+                call('1', 'Read', { file_path: diff }), call('2', 'Read', { file_path: path.join(repo, 'src/job.ts') }), call('3', 'Read', { file_path: path.join(repo, 'a.ts') }),
+                call('4', 'Bash', { command: 'git log -3' }), call('5', 'Grep', { pattern: 'job' }),
+                { type: 'result', result: JSON.stringify(EMPTY), total_cost_usd: 0.2, usage: { input_tokens: 5, output_tokens: 25 } },
+            ];
+            return { exitCode: 0, stdout: events.map(e => JSON.stringify(e)).join('\n'), stderr: '' };
+        };
+        await runReviewer(repo, 'main', config, streaming, () => undefined, { force: true });
+        const store = path.join(repo, '.git', 'rigour-reviewer');
+        const verdict = fs.readdirSync(store).filter(f => /^[0-9a-f]{40}\.[0-9a-f]{8}\.json$/.test(f)).map(f => JSON.parse(fs.readFileSync(path.join(store, f), 'utf8')))[0];
+        expect(verdict.reviewers[0].trace).toMatchObject({ turns: 5, usage: { input: 5, cacheRead: 500, cacheWrite: 50, output: 25 } });
+        expect(verdict.reviewers[0].trace.calls.map((c) => c.category)).toEqual(['rigour-input', 'changed-file', 'other-file', 'git', 'search']);
+    });
+    it('asks a judge once more after an answer that is not a verdict, and is unavailable only when the second is not one either', async () => {
+        const seen = seenNow();
+        let calls = 0;
+        const slipOnce = await runReviewer(repo, 'main', config, fakes(() => (++calls === 1 ? '{"prior_points":[], "findings":[{"class"' : JSON.stringify(EMPTY)), seen), () => undefined, { force: true });
+        expect(slipOnce.outcome).toBe('passed');
+        expect(seen.prompts).toHaveLength(2);
+        const twice = seenNow();
+        const slipTwice = await runReviewer(repo, 'main', config, fakes(() => 'not json', twice), () => undefined, { force: true });
+        expect(slipTwice).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no valid verdict') });
+        expect(twice.prompts).toHaveLength(2); // once more, never a loop
+    });
+    it('says what was asked and that nothing ran when a review ends early, with why a judge is missing', async () => {
+        const seen = { ...seenNow(), installed: ['claude'] }; // cursor is listed but not installed
+        const unreadable = async (command, args, options) => command === 'gh' && args[0] === 'pr' ? { exitCode: 1, stdout: '', stderr: 'gh auth login required' } : fakes(() => '', seen)(command, args, options);
+        const result = await runReviewer(repo, 'main', config, unreadable, () => undefined, { choice: { mode: 'full', panel: true } });
+        expect(result).toMatchObject({ outcome: 'unavailable', reviewers: ['claude'] });
+        expect(result.mode).toMatchObject({ asked: 'panel', ran: 'none', source: 'flag', degraded: expect.stringContaining('not installed: cursor-agent') });
+        const early = await runReviewer(repo, 'main', config, fakes(() => '', { ...seenNow(), installed: [] }), () => undefined, { choice: { mode: 'full', panel: true } });
+        expect(early).toMatchObject({ outcome: 'unavailable', mode: { asked: 'panel', ran: 'none', source: 'flag' } }); // before any judge was found
+    });
     it('in full mode runs two vendors and resolves a human point only when both say so', async () => {
         const seen = seenNow();
-        const by = (name) => JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: name === 'claude', evidence: 'src/job.ts:2' }], findings: name === 'cursor' ? [{ class: 'dead-code', file: 'a.ts', line: 1, issue: 'a is unused', consequence: 'a second run reads stale rows' }] : [] });
+        const by = (name) => JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: name === 'claude', evidence: 'src/job.ts:2', file: 'src/job.ts', line: 2, quote: 'export function job() {' }], findings: name === 'cursor' ? [{ class: 'dead-code', file: 'a.ts', line: 1, issue: 'a is unused', consequence: 'a second run reads stale rows', quote: 'export const a = 1;' }] : [] });
         const result = await runReviewer(repo, 'main', config, fakes(by, seen), () => undefined, { full: true });
         expect(result.reviewers).toEqual(['claude', 'cursor']);
         expect(result.items.map(i => [i.kind, i.reviewer])).toEqual([['prior', 'cursor'], ['finding', 'cursor']]);
@@ -221,7 +290,72 @@ describe('verdicts', () => {
         expect(parseVerdict('Looks good to me!', false, 'claude', {})).toMatchObject({ error: expect.stringContaining('no valid verdict') });
         expect(parseVerdict(JSON.stringify({ ...EMPTY, prior_points: [] }), true, 'claude', {})).toEqual({ error: 'claude did not report on the human reviews' });
     });
-    it('turns reads, scans, redundancy and merge impact into open items with stable ids, and answers non-blocking points in the reply', () => {
+    it('keeps the journey, sibling parity and claims as working notes, never blocks, and reads a verdict cached before they existed', () => {
+        const verdict = {
+            ...EMPTY,
+            journey: [
+                { file: 'src/w.ts', line: 4, what: 'stamps sent_at', cleared_by: null, retry_safe: false, overlap_safe: true, can_move_back: true, keys: [{ name: 'dedupeKey', inputs: 'updated_at', stable_under_edit: false }] },
+                { file: 'src/w.ts', line: 9, what: 'caches the token', cleared_by: 'ttl', retry_safe: true, overlap_safe: true, can_move_back: null },
+            ],
+            siblings: [
+                { changed: 'src/a/run.ts:3', sibling: 'src/b/run.ts:7', needs_same_change: true, has_it: false, why: 'same lock' },
+                { changed: 'src/a/run.ts:3', sibling: 'src/c/run.ts:2', needs_same_change: true, has_it: true },
+                { changed: 'src/a/run.ts:3', sibling: 'src/d/run.ts:2', needs_same_change: false, has_it: false },
+            ],
+            claims: [
+                { source: 'description', claim: 'at worst one email', file: 'src/w.ts', line: 12, holds: false, evidence: 'loop sends per row' },
+                { source: 'comment', claim: 'runs daily', file: 'src/cron.ts', line: 1, holds: true },
+            ],
+        };
+        const { open, notes } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.map(i => `${i.kind} ${i.class} ${i.file}:${i.line}`)).toEqual([
+            'journey correctness src/w.ts:4', 'journey correctness src/w.ts:4', 'journey correctness src/w.ts:4',
+            'sibling correctness src/b/run.ts:7', 'claim stale-claim src/w.ts:12',
+        ]);
+        expect(notes[3].issue).toContain('needs the same change as src/a/run.ts:3: same lock');
+        const cached = { ...EMPTY };
+        delete cached.journey;
+        delete cached.siblings;
+        delete cached.claims;
+        expect(account(cached, undefined, () => true).open).toEqual([]);
+        expect(mergeVerdicts([cached, { ...verdict, reviewer: 'codex' }]).claims).toHaveLength(2);
+    });
+    it('blocks on a finding only when the code it quotes is at the line it names, and never carries an old working note as a block', () => {
+        const verify = checkoutVerifier(repo);
+        const at = (quote, line = 2) => account({ ...EMPTY, prior_points: [], findings: [{ class: 'correctness', file: 'src/job.ts', line, issue: 'returns before the lock', input: 'two runs at once', consequence: 'two emails', ...(quote === undefined ? {} : { quote }) }] }, undefined, verify);
+        expect(at('    return 1;').open).toHaveLength(1);
+        expect(at('return   1;').open).toHaveLength(1); // whitespace aside
+        expect(at('return 1;', 9)).toMatchObject({ open: [], unverified: [expect.objectContaining({ issue: 'returns before the lock' })] }); // past the end
+        expect(at('return 99;')).toMatchObject({ open: [], unverified: [expect.anything()] }); // not in the file
+        expect(at()).toMatchObject({ open: [], unverified: [expect.anything()] }); // no quote at all
+        const old = { id: 'r1', kind: 'read', class: 'production-cost', file: 'src/q.ts', line: 3, issue: 'window not bounded' };
+        const carried = account({ ...EMPTY, prior_points: [] }, [old], verify);
+        expect(carried).toMatchObject({ open: [], notes: [expect.objectContaining({ id: 'r1' })] });
+    });
+    it('shows a team lesson the change repeats as a note, never a block on its own', () => {
+        const verdict = { ...EMPTY, lessons: [
+                { lesson: 'Regenerate the API client after changing the schema.', applies: true, file: 'src/schema.ts', line: 3, evidence: 'schema.ts changed, client not' },
+                { lesson: 'Paginate with keyset.', applies: false, file: 'src/scan.ts', line: 9 },
+            ] };
+        const { open, notes } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.map(n => [n.kind, n.class, n.issue])).toEqual([['lesson', 'team-lesson', 'repeats a team lesson: Regenerate the API client after changing the schema.']]);
+    });
+    it('blocks only on what it can show: a quoted open human point, a blocking finding, never a missing thing that is there or a point a human accepted', () => {
+        const verify = checkoutVerifier(repo);
+        const decide = (v) => account({ ...EMPTY, prior_points: [], ...v }, undefined, verify);
+        const open = { point: 'take the lock before the first read', severity: 'blocking', resolved: false };
+        expect(decide({ prior_points: [{ ...open, file: 'src/job.ts', line: 2, quote: 'return 1;' }] }).open).toHaveLength(1);
+        expect(decide({ prior_points: [open] })).toMatchObject({ open: [], unverified: [expect.objectContaining({ kind: 'prior' })] }); // a later commit may have done it: no quote, no block
+        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'job never closes the connection', input: 'every run', consequence: 'one connection leaks per run', quote: 'return 1;' };
+        expect(decide({ findings: [{ ...finding, absent: 'return 1' }] })).toMatchObject({ open: [], unverified: [expect.anything()] }); // "missing", but the file has it
+        expect(decide({ findings: [{ ...finding, absent: 'conn.close(' }] }).open).toHaveLength(1);
+        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], notes: [expect.anything()] });
+        const accepted = { point: 'job never closes the connection after the read', severity: 'non-blocking', resolved: false };
+        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], notes: [expect.anything()] }); // a human raised it and accepted it
+    });
+    it('keeps reads, scans, redundancy and merge impact as notes with stable ids, and answers non-blocking points in the reply', () => {
         const verdict = {
             ...EMPTY,
             prior_points: [{ point: 'nit: rename', severity: 'non-blocking', resolved: false }],
@@ -230,12 +364,13 @@ describe('verdicts', () => {
             redundant: [{ file: 'src/r.ts', line: 5, what: 'null guard', made_redundant_by: 'src/r.ts:2', removed: false }, { file: 'src/r.ts', line: 9, what: 'removed guard', removed: true }],
             merge_impact: [{ symbol: 'parseId', main_file: 'src/id.ts', call_site: 'src/link.ts:4', holds: false, why: 'band dropped' }],
         };
-        const { open, answerInReply } = account(verdict, undefined, () => true);
-        expect(open.map(i => `${i.class} ${i.file}:${i.line}`)).toEqual([
+        const { open, notes, answerInReply } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.map(i => `${i.class} ${i.file}:${i.line}`)).toEqual([
             'dead-code src/r.ts:5', 'production-cost src/q.ts:10', 'production-cost src/q.ts:10', 'production-cost src/q.ts:10', 'correctness src/q.ts:10', 'production-cost src/s.ts:3', 'correctness src/link.ts:4',
         ]);
-        expect(new Set(open.map(i => i.id)).size).toBe(open.length);
-        expect(account(verdict, undefined, () => true).open.map(i => i.id)).toEqual(open.map(i => i.id)); // stable
+        expect(new Set(notes.map(i => i.id)).size).toBe(notes.length);
+        expect(account(verdict, undefined, () => true).notes.map(i => i.id)).toEqual(notes.map(i => i.id)); // stable
         expect(answerInReply).toEqual([expect.objectContaining({ point: 'nit: rename' })]);
     });
     it('merges two verdicts: a point is resolved only when every reviewer resolves it', () => {
@@ -255,9 +390,27 @@ describe('verdicts', () => {
 });
 describe('a panel of judges', () => {
     const panelConfig = (reviewer) => ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor', 'codex'], mode: 'full', panel: 'on', ...reviewer } } });
-    const LOCK = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' };
-    const LONE = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', consequence: 'a reader treats it as the contract' };
-    const OPINION = { class: 'duplication', file: 'src/job.ts', line: 2, issue: 'could be one line shorter', consequence: '' };
+    const LOCK = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' };
+    const LONE = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', quote: 'export function job() {', consequence: 'a reader treats it as the contract' };
+    const OPINION = { class: 'duplication', file: 'src/job.ts', line: 2, issue: 'could be one line shorter', quote: 'export function job() {', consequence: '' };
+    it("keeps Rigour's own key from every judge, and a key the team names from that judge, in reviews and cross-examinations alike", async () => {
+        installFake(bins[0], 'codex');
+        const seen = { ...seenNow(), installed: ['claude', 'cursor-agent', 'codex'] };
+        const reply = (name) => {
+            const prompt = seen.prompts.at(-1) ?? '';
+            if (prompt.includes('The other\nreviewer raised')) {
+                const ids = [...prompt.matchAll(/"id": "([0-9a-f]+)"/g)].map(m => m[1]);
+                return JSON.stringify({ answers: ids.map(id => ({ id, call: 'refute', evidence: `src/job.ts:1 ${name}: job is imported by the runner` })) });
+            }
+            return JSON.stringify({ ...EMPTY, findings: name === 'codex' ? [LONE] : [] });
+        };
+        await runReviewer(repo, 'main', panelConfig({ judges: 3, judge_env: { codex: { unset: ['OPENAI_API_KEY'] } } }), fakes(reply, seen), () => undefined);
+        const runs = seen.ran.map((command, i) => ({ judge: path.basename(command).replace(/\.(cmd|exe)$/, ''), unset: seen.unset?.[i] ?? [] }));
+        expect(runs.length).toBe(5); // three reviews and two cross-examinations
+        for (const run of runs)
+            expect(run.unset).toContain('RIGOUR_API_KEY');
+        expect(runs.filter(r => r.unset.includes('OPENAI_API_KEY')).map(r => r.judge)).toEqual(['codex']);
+    });
     it('confirms what a majority raised, drops what the others refute with evidence, and never blocks on an opinion', async () => {
         installFake(bins[0], 'codex');
         const seen = { ...seenNow(), installed: ['claude', 'cursor-agent', 'codex'] };
@@ -303,7 +456,7 @@ describe('a panel of judges', () => {
     });
     it('counts every run, stops new reviews at the cost cap, and leaves a cross-examination past the run cap disputed', async () => {
         const seen = seenNow();
-        const lone = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', consequence: 'a reader treats it as the contract' };
+        const lone = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', quote: 'export function job() {', consequence: 'a reader treats it as the contract' };
         const reply = (name) => JSON.stringify({ ...EMPTY, findings: name === 'claude' ? [LOCK] : [{ ...LOCK, line: 3, issue: 'the lock is taken only after it returns' }, lone] });
         // Two judges fit in a cap of 2; the cross-examination of cursor's lone finding would be a third run.
         const result = await runReviewer(repo, 'main', panelConfig({ max_runs_per_day: 2 }), fakes(reply, seen), () => undefined);
@@ -326,7 +479,7 @@ describe('a panel of judges', () => {
 describe('what the team already knows', () => {
     const allowing = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'], dismissals: true } } });
     it('refuses a dismissal unless the team allows them: fix the code, or the reviewer', async () => {
-        const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' }] }), seenNow()), () => undefined);
+        const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' }] }), seenNow()), () => undefined);
         expect((await dismissReviewerFinding(repo, first.items[0].id, 'the runner holds a lock', false)).error).toContain('this team does not dismiss reviewer findings');
         expect(fs.existsSync(path.join(repo, '.rigour/dismissed-review-items.json'))).toBe(false);
     });
@@ -335,7 +488,7 @@ describe('what the team already knows', () => {
         fs.writeFileSync(path.join(repo, 'docs/jobs.md'), 'The job runner (src/job.ts) takes the lock first.\n');
         git('add', '-A');
         git('commit', '-qm', 'docs');
-        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' };
+        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' };
         const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [finding] }), seenNow()), () => undefined);
         expect(first.outcome).toBe('findings');
         expect(await dismissReviewerFinding(repo, 'abcdef0123', 'not one of ours', true)).toEqual({ error: 'no open reviewer finding abcdef0123 on feature: run `rigour review --reviewer` and copy the id it shows' });
@@ -358,7 +511,7 @@ describe('what the team already knows', () => {
         expect(told.files['team-knowledge.md']).toContain("## Already found by Rigour's checks: they block on their own, so do not report them again\n- src/job.ts:1 Unused export `job`");
     });
     it('fails closed: a finding whose judge left out the consequence still blocks', async () => {
-        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock' }] }), seenNow()), () => undefined);
+        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'export function job() {' }] }), seenNow()), () => undefined);
         expect(result.items.map(i => i.issue)).toEqual(['returns before the lock']);
         expect(result.notes).toEqual([]);
     });

package/dist/review/typed/constant-inputs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Inputs that never vary in production, so the code that handles other values is dead:
+ *
+ *   constant-member    a property every production object of the type sets to the same literal
+ *                      (`count: 0` in each), while code branches on it: the other branches never run.
+ *   constant-argument  a parameter every production call passes the same literal, while the body
+ *                      branches on it: the other branch never runs outside tests.
+ *
+ * Tests are not production: a test that passes other values is exactly the sign the generality
+ * exists only for them. Scoped like the other typed checks: the change declared the member or the
+ * function, or wrote every production host or call.
+ */
+import type * as TS from 'typescript';
+import type { TypedProgram } from './program.js';
+export interface DeclaredType {
+    node: TS.InterfaceDeclaration | TS.TypeAliasDeclaration;
+    name: string;
+    members: TS.PropertySignature[];
+}
+export interface ConstantHelpers {
+    hostsOf: (t: DeclaredType & {
+        sym: TS.Symbol;
+        type: TS.Type;
+    }) => TS.ObjectLiteralExpression[];
+    touched: (node: TS.Node) => boolean;
+    spanTouched: (node: TS.Node) => boolean;
+    at: (node: TS.Node) => string;
+    rel: (sf: TS.SourceFile) => string;
+    report: (id: string, title: string, node: TS.Node, details: string, hint: string) => void;
+    walk: (node: TS.Node, fn: (n: TS.Node) => void) => void;
+}
+export declare function constantInputs(typed: TypedProgram, changedSources: TS.SourceFile[], declared: Array<DeclaredType & {
+    sym: TS.Symbol;
+    type: TS.Type;
+}>, h: ConstantHelpers): void;