@rigour-labs/core 6.6.6 → 6.7.1

package/dist/review/reviewer/panel.js

@@ -0,0 +1,101 @@
+/**
+ * Two or three judges as a panel, run around the consensus rules (consensus.ts). The judges' own
+ * items are grouped into findings; a finding a strict majority raised is confirmed. Every other
+ * judge then cross-examines, in one batched call each, only the findings it did not raise: confirm
+ * or refute with file:line evidence; no evidence or no answer is unsure. The calls decide by
+ * majority; a disputed finding is shown and never blocks. A finding disputed before, on a file no
+ * commit has touched since, stays disputed without another call; past the item cap, disputed too.
+ *
+ * Every finding keeps what a later re-scoring needs (who raised it, every judge's call, the
+ * cross-examination answers, each judge's own item and the class), so a probabilistic truth model
+ * can be fitted to the ledger later without running anyone again.
+ */
+import { clusterItems, MATCH_THRESHOLD, order, similarity, statusOf } from './consensus.js';
+/** The panel's decision on every finding any judge raised. */
+export async function runPanel(input) {
+    const n = input.judges.length;
+    const clusters = clusterItems(input.judges, input.items);
+    const decided = clusters.map(c => {
+        const raisers = [...new Set(c.members.map(m => m.judge))];
+        const calls = Object.fromEntries(raisers.map(j => [j, 'raised']));
+        const item = { ...c.members[0].item, evidence: c.members.map(m => m.item.evidence).find(Boolean) };
+        return { item, judges: raisers, calls, status: statusOf(calls, n), ...(c.members.length > 1 ? { members: c.members } : {}) };
+    });
+    const undecided = decided.filter(d => d.status !== 'confirmed');
+    const disputedBefore = (item) => !!item.file && !input.touched.has(item.file) && input.previousDisputed.some(p => similarity(item, p) >= MATCH_THRESHOLD);
+    for (const d of undecided.filter(d => disputedBefore(d.item))) {
+        for (const judge of input.judges)
+            d.calls[judge] ??= 'not asked';
+        d.status = 'disputed';
+        d.note = 'disputed before; its file is unchanged since';
+    }
+    const toAsk = undecided.filter(d => !d.note).sort((a, b) => order(a.item, b.item));
+    for (const d of toAsk.slice(input.maxItems)) {
+        for (const judge of input.judges)
+            d.calls[judge] ??= 'not asked';
+        d.status = 'disputed';
+        d.note = `over review.reviewer.panel_max_items (${input.maxItems})`;
+    }
+    const asked = toAsk.slice(0, input.maxItems);
+    // One batched call per judge, about every asked finding it did not raise; the calls run together.
+    await Promise.all(input.judges.map(async (judge) => {
+        const mine = asked.filter(d => !d.judges.includes(judge));
+        if (!mine.length)
+            return;
+        const cap = input.capped?.();
+        if (cap) {
+            for (const d of mine) {
+                d.calls[judge] = 'not asked';
+                d.note = cap;
+            }
+            return;
+        }
+        let answers = [];
+        try {
+            answers = await input.ask(judge, mine.map(d => d.item));
+        }
+        catch {
+            answers = [];
+        }
+        for (const d of mine) {
+            const answer = answers.find(x => x.id === d.item.id);
+            const evidenced = !!answer?.evidence && input.evidenced(answer.evidence);
+            d.calls[judge] = answer && evidenced ? answer.call : 'unsure';
+            d.cross = [...(d.cross ?? []), { by: judge, call: d.calls[judge], ...(answer?.evidence ? { evidence: answer.evidence } : {}) }];
+        }
+    }));
+    for (const d of asked)
+        d.status = statusOf(d.calls, n);
+    return decided.sort((x, y) => order(x.item, y.item));
+}
+/** The answers in a judge's cross-examination reply; nothing usable is no answers (every item then disputed). */
+export function parseAnswers(text) {
+    const candidates = [text.trim(), ...[...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)].map(m => m[1].trim()), ...[...text.matchAll(/\{\s*"answers"/g)].map(m => text.slice(m.index))];
+    for (const candidate of candidates) {
+        for (let end = candidate.lastIndexOf('}'); end > 0; end = candidate.lastIndexOf('}', end - 1)) {
+            try {
+                const parsed = JSON.parse(candidate.slice(0, end + 1));
+                if (!Array.isArray(parsed?.answers))
+                    continue;
+                return parsed.answers.filter((a) => typeof a?.id === 'string' && ['confirm', 'refute', 'unsure'].includes(a.call))
+                    .map((a) => ({ id: a.id, call: a.call, ...(typeof a.evidence === 'string' ? { evidence: a.evidence } : {}) }));
+            }
+            catch {
+                // not a whole object yet: try a shorter one
+            }
+        }
+    }
+    return [];
+}
+/** The accounting with the panel's decision applied: the judges' own items leave, and only what it confirmed blocks. */
+export function applyPanel(accounted, judgeItemIds, decided) {
+    const withJudges = (d) => ({ ...d.item, reviewer: d.judges.join('+') });
+    const confirmed = decided.filter(d => d.status === 'confirmed').map(withJudges);
+    const open = [...accounted.open.filter(item => !judgeItemIds.has(item.id)), ...confirmed.filter(c => !accounted.open.some(o => o.id === c.id && !judgeItemIds.has(o.id)))];
+    return {
+        ...accounted,
+        open,
+        disputed: decided.filter(d => d.status === 'disputed').map(withJudges),
+        dropped: decided.filter(d => d.status === 'dropped').map(withJudges),
+    };
+}

package/dist/review/reviewer/panel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/reviewer/panel.test.js

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import { clusterItems, similarity, statusOf } from './consensus.js';
+import { applyPanel, parseAnswers, runPanel } from './panel.js';
+let n = 0;
+const item = (file, line, cls, issue, consequence = 'wrong rows') => ({ id: `i${++n}`, kind: 'finding', class: cls, file, line, issue, consequence });
+/** Evidence counts only as a real file:line: here, any src/q.ts line. */
+const evidenced = (text) => /src\/q\.ts:\d+/.test(text);
+const members = (judges, items) => clusterItems(judges, items).map(c => c.members.map(m => `${m.judge}:${m.item.issue}`));
+describe('matching findings across judges', () => {
+    it('needs the same file, and shared wording unless it is the same line and class', () => {
+        const a = item('src/a.ts', 10, 'correctness', 'window not bounded at both ends', 'scans every past event');
+        expect(similarity(a, { ...a, file: 'src/b.ts' })).toBe(0);
+        expect(similarity(a, item('src/a.ts', 11, 'correctness', 'dedupe key changes when the user edits', 'duplicate emails go out'))).toBe(0);
+        expect(similarity(a, item('src/a.ts', 10, 'correctness', 'something else entirely', 'duplicate emails go out'))).toBeGreaterThanOrEqual(0.5);
+    });
+    it('keeps two different findings on adjacent lines apart, even listed in a misleading order (first-fit by line would cross them)', () => {
+        const judgeA = [item('src/q.ts', 10, 'production-cost', 'time window not bounded at both ends'), item('src/q.ts', 11, 'correctness', 'dedupe key changes when the user edits')];
+        const judgeB = [item('src/q.ts', 10, 'correctness', 'dedupe key built from updated_at changes when the user edits'), item('src/q.ts', 11, 'production-cost', 'read window has no upper bound at either end')];
+        expect(members(['a', 'b'], [judgeA, judgeB])).toEqual([
+            ['a:time window not bounded at both ends', 'b:read window has no upper bound at either end'],
+            ['a:dedupe key changes when the user edits', 'b:dedupe key built from updated_at changes when the user edits'],
+        ]);
+    });
+    it('matches one bug two judges cite at different lines', () => {
+        const judgeA = [item('src/q.ts', 10, 'correctness', 'lock is checked after the first read of rows')];
+        const judgeB = [item('src/q.ts', 40, 'correctness', 'the first read of rows happens before the lock is checked')];
+        expect(members(['a', 'b'], [judgeA, judgeB])).toHaveLength(1);
+    });
+    it('puts what one judge split under the one item another judge wrote', () => {
+        const judgeA = [item('src/q.ts', 10, 'production-cost', 'both reads, rows and cards, are unbounded')];
+        const judgeB = [item('src/q.ts', 10, 'production-cost', 'rows read is unbounded'), item('src/q.ts', 14, 'production-cost', 'cards read is unbounded')];
+        expect(members(['a', 'b'], [judgeA, judgeB])).toEqual([['a:both reads, rows and cards, are unbounded', 'b:rows read is unbounded', 'b:cards read is unbounded']]);
+    });
+    it('never merges one judge\'s own two findings, however close', () => {
+        const judgeA = [item('src/x.ts', 10, 'correctness', 'session.user may be null when the token expired'), item('src/x.ts', 12, 'correctness', 'session.expires compared as a string, not a date')];
+        expect(members(['a', 'b'], [judgeA, []])).toEqual([['a:session.user may be null when the token expired'], ['a:session.expires compared as a string, not a date']]);
+    });
+    it('groups three judges, and is the same every run', () => {
+        const items = [
+            [item('src/q.ts', 10, 'correctness', 'lock checked after the read')],
+            [item('src/q.ts', 11, 'correctness', 'the read happens before the lock is checked'), item('src/r.ts', 3, 'dead-code', 'export unused')],
+            [item('src/q.ts', 10, 'correctness', 'lock checked only after the read')],
+        ];
+        const once = members(['a', 'b', 'c'], items);
+        expect(once).toEqual(members(['a', 'b', 'c'], items));
+        expect(once.map(c => c.length)).toEqual([3, 1]);
+    });
+});
+describe('deciding a finding', () => {
+    it('confirms on a strict majority, drops on evidence against with nobody unsure, else disputes', () => {
+        expect(statusOf({ a: 'raised', b: 'raised' }, 2)).toBe('confirmed');
+        expect(statusOf({ a: 'raised', b: 'confirm' }, 2)).toBe('confirmed');
+        expect(statusOf({ a: 'raised', b: 'refute' }, 2)).toBe('dropped');
+        expect(statusOf({ a: 'raised', b: 'unsure' }, 2)).toBe('disputed');
+        expect(statusOf({ a: 'raised', b: 'raised' }, 3)).toBe('confirmed');
+        expect(statusOf({ a: 'raised', b: 'confirm', c: 'refute' }, 3)).toBe('confirmed');
+        expect(statusOf({ a: 'raised', b: 'refute', c: 'refute' }, 3)).toBe('dropped');
+        expect(statusOf({ a: 'raised', b: 'refute', c: 'unsure' }, 3)).toBe('disputed');
+    });
+    it('asks each judge once about what it did not raise, needs file:line evidence, and caps what it asks', async () => {
+        const asked = {};
+        const lone = item('src/q.ts', 10, 'correctness', 'lock checked after the read');
+        const refuted = item('src/q.ts', 30, 'correctness', 'the cursor skips the last page');
+        const bare = item('src/q.ts', 50, 'correctness', 'an index is missing on created_at');
+        const overCap = item('src/z.ts', 1, 'correctness', 'retries forever on 429');
+        const answers = { b: [{ id: lone.id, call: 'confirm', evidence: 'src/q.ts:12 reads before lock()' }, { id: refuted.id, call: 'refute', evidence: 'src/q.ts:33 the loop runs once more' }, { id: bare.id, call: 'confirm' }] };
+        const decided = await runPanel({
+            judges: ['a', 'b'], items: [[lone, refuted, bare, overCap], []], previousDisputed: [], touched: new Set(), maxItems: 3, evidenced,
+            ask: async (judge, items) => { asked[judge] = items.map(i => i.issue); return answers[judge] ?? []; },
+        });
+        expect(asked).toEqual({ b: ['lock checked after the read', 'the cursor skips the last page', 'an index is missing on created_at'] });
+        const status = Object.fromEntries(decided.map(d => [d.item.issue, d.status]));
+        expect(status).toEqual({ 'lock checked after the read': 'confirmed', 'the cursor skips the last page': 'dropped', 'an index is missing on created_at': 'disputed', 'retries forever on 429': 'disputed' });
+        expect(decided.find(d => d.item.id === overCap.id)?.note).toContain('panel_max_items');
+        expect(decided.find(d => d.item.id === lone.id)).toMatchObject({ judges: ['a'], calls: { a: 'raised', b: 'confirm' }, cross: [{ by: 'b', call: 'confirm', evidence: 'src/q.ts:12 reads before lock()' }] });
+    });
+    it('does not ask again about a finding disputed before on a file nothing has touched since', async () => {
+        const again = item('src/q.ts', 10, 'correctness', 'lock checked after the read');
+        const asked = [];
+        const ask = async (_judge, items) => { asked.push(...items.map(i => i.id)); return []; };
+        const untouched = await runPanel({ judges: ['a', 'b'], items: [[again], []], previousDisputed: [{ ...again, id: 'old' }], touched: new Set(), maxItems: 20, evidenced, ask });
+        expect(untouched[0]).toMatchObject({ status: 'disputed', note: 'disputed before; its file is unchanged since' });
+        expect(asked).toEqual([]);
+        await runPanel({ judges: ['a', 'b'], items: [[again], []], previousDisputed: [{ ...again, id: 'old' }], touched: new Set(['src/q.ts']), maxItems: 20, evidenced, ask });
+        expect(asked).toEqual([again.id]);
+    });
+    it('a judge that fails to answer leaves the findings disputed, never confirmed', async () => {
+        const lone = item('src/q.ts', 10, 'correctness', 'lock checked after the read');
+        const decided = await runPanel({ judges: ['a', 'b'], items: [[lone], []], previousDisputed: [], touched: new Set(), maxItems: 20, evidenced, ask: async () => { throw new Error('timed out'); } });
+        expect(decided[0]).toMatchObject({ status: 'disputed', calls: { a: 'raised', b: 'unsure' } });
+    });
+});
+describe('the panel in the accounting', () => {
+    it('blocks only on what it confirmed, and lists the rest', () => {
+        const confirmed = item('src/q.ts', 10, 'correctness', 'lock checked after the read');
+        const disputed = item('src/q.ts', 30, 'correctness', 'cursor skips a page');
+        const human = { ...item('', 0, 'prior point', 'a human point'), kind: 'prior' };
+        const result = applyPanel({ open: [confirmed, disputed, human] }, new Set([confirmed.id, disputed.id]), [
+            { item: confirmed, judges: ['a', 'b'], calls: { a: 'raised', b: 'raised' }, status: 'confirmed' },
+            { item: disputed, judges: ['a'], calls: { a: 'raised', b: 'unsure' }, status: 'disputed' },
+        ]);
+        expect(result.open.map(i => i.issue)).toEqual(['a human point', 'lock checked after the read']);
+        expect(result.open[1].reviewer).toBe('a+b');
+        expect(result.disputed.map(i => i.issue)).toEqual(['cursor skips a page']);
+    });
+    it('reads the answers out of a reply with prose around them, and nothing from a reply without them', () => {
+        expect(parseAnswers('Checked.\n```json\n{"answers":[{"id":"x","call":"refute","evidence":"a.ts:3"},{"id":"y","call":"maybe"}]}\n```')).toEqual([{ id: 'x', call: 'refute', evidence: 'a.ts:3' }]);
+        expect(parseAnswers('I could not decide.')).toEqual([]);
+    });
+});

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

@@ -11,6 +11,8 @@ export interface PromptInputs {
     diffstatFile: string;
     diffFile: string;
     hintsFile: string;
+    /** What the team already knows (reviewer/context.ts). */
+    contextFile: string;
     deltaBlock: string;
     mergeBlock: string;
 }
@@ -19,3 +21,12 @@ export declare function deltaBlock(previousHead: string, previousVerdict: string
 export declare function mergeBlock(base: string, impactFile: string | undefined): string;
 /** Changes when the instructions change, so a cached verdict from older instructions is not reused. */
 export declare const PROMPT_VERSION: string;
+/** One judge's single call on the items the other judge raised alone: confirm or refute each, with the code that shows it. */
+export declare function crossExamPrompt(repoRoot: string, head: string, diffFile: string, items: Array<{
+    id: string;
+    class: string;
+    file?: string;
+    line?: number;
+    issue: string;
+    consequence?: string;
+}>): string;

package/dist/review/reviewer/prompt.js

@@ -22,6 +22,8 @@ Inputs:
 - The pull request description: ${v.prBodyFile}
 - What changed: ${v.diffstatFile}; the full diff is in ${v.diffFile} (the same as
   \`git diff ${v.baseSha}...${v.head}\`). Read the files themselves for context.
+- What this team already knows: verified lessons and rules for these files, findings it settled
+  (never raise one again unless the code now shows something new), docs about this code: ${v.contextFile}
 ${v.deltaBlock}${v.mergeBlock}- Deterministic hints already computed (candidates to confirm, never the full list): ${v.hintsFile}
 - The repository's rules: AGENTS.md (and CLAUDE.md). A violation of a rule there in changed code
   is a finding.
@@ -85,8 +87,11 @@ Do these steps in order. Report only what you verified in the code, with file:li
    in the description still true of the code, and the repository's rules.
 
 Classes: correctness, production-cost, dead-code, duplication, stale-claim, helper-bypass,
-repo-rule. Every finding blocks; do not report style preferences or trade-offs you would not
-request changes for.
+repo-rule. Every finding needs a consequence: the wrong outcome it causes (an input and what
+goes wrong) or the cost it adds (reads, calls or memory per what). A finding with no wrong outcome
+and no cost (faster, simpler or cleaner code) is an opinion: leave consequence empty and it is
+shown, never blocking. Do not report style preferences or trade-offs you would not request
+changes for.
 
 Your final message must be ONLY this JSON, starting with { and ending with }, nothing before or after it:
 {"prior_points":[{"point":"...","review":"<login> <submitted_at>","severity":"blocking"|"should-fix"|"non-blocking","resolved":true|false,"evidence":"file:line ...","checked_siblings":["file:line"]}],
@@ -94,7 +99,7 @@ Your final message must be ONLY this JSON, starting with { and ending with }, no
  "reads":[{"file":"...","line":0,"read":"...","rules":[{"rule":"...","known_before_read":true|false,"applied_before_read":true|false}],"consumer":{"file":"...","line":0,"uses":"ids-only"|"rows"|"aggregate"},"narrower_source":null|"...","keys":[{"name":"...","inputs":"...","stable_under_edit":true|false}],"window_bounded":true|false|null,"keyset":true|false|null,"index":"..."}],
  "scans":[{"file":"...","line":0,"function":"...","outer":"...","inner":"...","fix":"..."}],
  "merge_impact":[{"symbol":"...","main_file":"...","call_site":"file:line","holds":true|false,"why":"..."}],
- "findings":[{"class":"...","file":"...","line":0,"issue":"...","why":"..."}],
+ "findings":[{"class":"...","file":"...","line":0,"issue":"...","why":"...","consequence":"<wrong outcome for an input, or the cost; empty for an opinion>"}],
  "carried":["<delta mode: ids of previous open items that still stand>"],
  "resolved_previous":[{"id":"<delta mode: id of a previous open item now fixed>","evidence":"file:line and the fix"}]}`;
 }
@@ -119,5 +124,22 @@ export function mergeBlock(base, impactFile) {
 /** Changes when the instructions change, so a cached verdict from older instructions is not reused. */
 export const PROMPT_VERSION = createHash('sha256').update(renderPrompt({
     repoRoot: '<repo>', branch: '<branch>', head: '<head>', base: '<base>', baseSha: '<sha>', mode: 'full', reviewsFile: '<r>', humanCount: 0,
-    prBodyFile: '<b>', diffstatFile: '<s>', diffFile: '<d>', hintsFile: '<h>', deltaBlock: '', mergeBlock: '',
+    prBodyFile: '<b>', diffstatFile: '<s>', diffFile: '<d>', hintsFile: '<h>', contextFile: '<c>', deltaBlock: '', mergeBlock: '',
 })).digest('hex').slice(0, 12);
+/** One judge's single call on the items the other judge raised alone: confirm or refute each, with the code that shows it. */
+export function crossExamPrompt(repoRoot, head, diffFile, items) {
+    return `You are one of two independent reviewers of the branch at ${head} in ${repoRoot}. The other
+reviewer raised the items below, and you did not. Judge each one against the code, read-only: open
+the file, follow the callers and callees you need, and use the diff at ${diffFile}.
+
+For each item answer "confirm" when the code shows the problem is real, or "refute" when the code
+shows it is not, and quote the file:line that shows it in "evidence". When you cannot tell from
+the code, answer "unsure". An answer without file:line evidence counts as unsure. Do not raise
+new items.
+
+Items:
+${JSON.stringify(items, null, 2)}
+
+Your final message must be ONLY this JSON, starting with { and ending with }:
+{"answers":[{"id":"...","call":"confirm"|"refute"|"unsure","evidence":"file:line ..."}]}`;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The reviewer settings a run uses, and where each came from. Four layers, the nearest wins:
+ * a flag on this run, an environment variable (hooks and CI take no flags), the person's own
+ * settings (`reviewer` in the profile's settings.json, edited by hand or in Studio), and the team's
+ * rigour.yml (its defaults when there is none). The team can set a floor no nearer layer goes
+ * below: `panel: required` and `mode_required`. A nearer layer that asks for less is refused, and
+ * the refusal is reported, never silent. Under a floor, a person also cannot turn reviews off, lower
+ * the judges or escalate on risk only. A panel needs two vendors, so `panel` implies mode full,
+ * except that a nearer choice of one judge turns off a panel the team only turned on.
+ */
+import { type UserReviewerSettings } from '../../settings.js';
+import type { Config } from '../../types/index.js';
+type Mode = 'single' | 'cross' | 'full';
+export type Source = 'flag' | 'env' | 'user' | 'team';
+/** What a single run asks for: `rigour review --reviewer --full | --single | --panel | --no-panel`. */
+export interface RunChoice {
+    mode?: Mode;
+    panel?: boolean;
+}
+export interface ResolvedReviewer {
+    enabled: boolean;
+    on_push: 'background' | 'wait' | 'off';
+    reviewers: string[];
+    models: Record<string, string>;
+    model?: string;
+    timeout_ms: number;
+    mode: Mode;
+    panel: boolean;
+    panel_max_items: number;
+    /** Whether reviewer findings may be dismissed: the team's decision, never a person's. */
+    dismissals: boolean;
+    /** The daily caps that apply: the lower of the team's and the person's. */
+    max_runs_per_day?: number;
+    max_usd_per_day?: number;
+    judges: 2 | 3;
+    escalate: 'always' | 'risk';
+    cross_models: Record<string, string>;
+    /** Where the mode and the panel choice came from. */
+    source: {
+        mode: Source;
+        panel: Source;
+    };
+    /** The team's floor: a run that cannot meet it is unavailable, never a quieter review. */
+    required: {
+        mode: boolean;
+        panel: boolean;
+    };
+    /** Nearer choices that were not applied (the team's floor, an unknown value), one line each, for the report. */
+    refused: string[];
+}
+export declare function resolveReviewer(config: Config, choice?: RunChoice, user?: UserReviewerSettings | undefined, env?: NodeJS.ProcessEnv): ResolvedReviewer;
+/** A change to the person's own reviewer settings: a value sets it, `null` goes back to the team's. */
+export type UserReviewerPatch = {
+    [K in keyof UserReviewerSettings]?: UserReviewerSettings[K] | null;
+};
+/** Applies a validated patch to the person's settings (settings.json in the profile's home) and returns what is stored. */
+export declare function saveUserReviewer(patch: UserReviewerPatch): UserReviewerSettings;
+export {};

package/dist/review/reviewer/settings.js

@@ -0,0 +1,152 @@
+/**
+ * The reviewer settings a run uses, and where each came from. Four layers, the nearest wins:
+ * a flag on this run, an environment variable (hooks and CI take no flags), the person's own
+ * settings (`reviewer` in the profile's settings.json, edited by hand or in Studio), and the team's
+ * rigour.yml (its defaults when there is none). The team can set a floor no nearer layer goes
+ * below: `panel: required` and `mode_required`. A nearer layer that asks for less is refused, and
+ * the refusal is reported, never silent. Under a floor, a person also cannot turn reviews off, lower
+ * the judges or escalate on risk only. A panel needs two vendors, so `panel` implies mode full,
+ * except that a nearer choice of one judge turns off a panel the team only turned on.
+ */
+import { loadSettings, saveSettings } from '../../settings.js';
+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 refused = [];
+    const envMode = parseMode(env.RIGOUR_REVIEWER_MODE);
+    const envPanel = parseSwitch(env.RIGOUR_REVIEWER_PANEL);
+    if (env.RIGOUR_REVIEWER_MODE && !envMode)
+        refused.push(`RIGOUR_REVIEWER_MODE=${env.RIGOUR_REVIEWER_MODE} ignored: use single, cross or full`);
+    if (env.RIGOUR_REVIEWER_PANEL && envPanel === undefined)
+        refused.push(`RIGOUR_REVIEWER_PANEL=${env.RIGOUR_REVIEWER_PANEL} ignored: use on or off`);
+    const layers = [
+        { source: 'flag', mode: choice.mode, panel: choice.panel },
+        { source: 'env', mode: envMode, panel: envPanel },
+        { source: 'user', mode: user?.mode, panel: user?.panel },
+    ];
+    const pick = (key) => layers.find(layer => layer[key] !== undefined);
+    const requirePanel = team.panel === 'required';
+    let panel = team.panel !== 'off';
+    let panelSource = 'team';
+    const nearPanel = pick('panel');
+    if (nearPanel) {
+        if (requirePanel && nearPanel.panel === false)
+            refused.push(`panel off (${nearPanel.source}) refused: rigour.yml sets review.reviewer.panel: required`);
+        else
+            [panel, panelSource] = [nearPanel.panel, nearPanel.source];
+    }
+    let mode = team.mode;
+    let modeSource = 'team';
+    const nearMode = pick('mode');
+    if (nearMode) {
+        if (team.mode_required && RANK[nearMode.mode] < RANK[team.mode])
+            refused.push(`mode ${nearMode.mode} (${nearMode.source}) refused: rigour.yml sets review.reviewer.mode_required with mode ${team.mode}`);
+        else
+            [mode, modeSource] = [nearMode.mode, nearMode.source];
+    }
+    if (panel && mode !== 'full') {
+        // A panel needs two vendors. Asking for fewer judges at a nearer layer than the panel's turns the panel off, unless the team requires it.
+        const fewer = nearMode && RANK[nearMode.mode] < RANK.full;
+        if (fewer && NEAR[nearMode.source] < NEAR[panelSource] && !requirePanel)
+            panel = false;
+        else {
+            if (fewer)
+                refused.push(`mode ${nearMode.mode} (${nearMode.source}) refused: ${requirePanel ? 'rigour.yml sets review.reviewer.panel: required' : `the panel (${panelSource}) needs judges from two vendors`}`);
+            [mode, modeSource] = ['full', panelSource];
+        }
+    }
+    const floor = requirePanel || team.mode_required;
+    if (floor && team.enabled && user?.enabled === false)
+        refused.push('reviews off (user) refused: rigour.yml requires the reviewer');
+    if (floor && user?.judges !== undefined && user.judges < team.judges)
+        refused.push(`judges ${user.judges} (user) refused: rigour.yml requires ${team.judges}`);
+    return {
+        enabled: floor && team.enabled ? true : user?.enabled ?? team.enabled,
+        on_push: team.on_push,
+        reviewers: user?.reviewers?.length ? user.reviewers : team.reviewers,
+        models: { ...team.models, ...(user?.models ?? {}) },
+        ...(team.model ? { model: team.model } : {}),
+        timeout_ms: team.timeout_ms,
+        mode,
+        panel,
+        panel_max_items: team.panel_max_items,
+        dismissals: team.dismissals,
+        ...cap('max_runs_per_day', team.max_runs_per_day, user?.max_runs_per_day, refused),
+        ...cap('max_usd_per_day', team.max_usd_per_day, user?.max_usd_per_day, refused),
+        judges: floor ? Math.max(team.judges, user?.judges ?? team.judges) : user?.judges ?? team.judges,
+        escalate: requiredEscalation(team, user, refused),
+        cross_models: team.cross_models,
+        source: { mode: modeSource, panel: panelSource },
+        required: { mode: team.mode_required, panel: requirePanel },
+        refused,
+    };
+}
+/** A cap is the lower of the team's and the person's: a person can spend less than the team allows, never more. */
+function cap(key, team, user, refused) {
+    if (user !== undefined && team !== undefined && user > team)
+        refused.push(`${key} ${user} (user) refused: rigour.yml caps it at ${team}`);
+    const value = team === undefined ? user : user === undefined ? team : Math.min(team, user);
+    return value === undefined ? {} : { [key]: value };
+}
+/** A team that requires full or panel review wants it on every review: no user may escalate on risk only. */
+function requiredEscalation(team, user, refused) {
+    const required = team.panel === 'required' || team.mode_required;
+    if (required && user?.escalate === 'risk')
+        refused.push('escalate risk (user) refused: rigour.yml requires every review to be full');
+    return required ? 'always' : user?.escalate ?? team.escalate;
+}
+function parseMode(value) {
+    return value === 'single' || value === 'cross' || value === 'full' ? value : undefined;
+}
+function parseSwitch(value) {
+    if (/^(1|on|true|yes)$/i.test(value ?? ''))
+        return true;
+    if (/^(0|off|false|no)$/i.test(value ?? ''))
+        return false;
+    return undefined;
+}
+/** Applies a validated patch to the person's settings (settings.json in the profile's home) and returns what is stored. */
+export function saveUserReviewer(patch) {
+    const problem = patchProblem(patch);
+    if (problem)
+        throw new Error(problem);
+    const settings = loadSettings();
+    const next = { ...(settings.reviewer ?? {}) };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            delete next[key];
+        else if (value !== undefined)
+            next[key] = value;
+    }
+    saveSettings({ ...settings, reviewer: next });
+    return next;
+}
+function patchProblem(patch) {
+    const known = new Set(['enabled', 'mode', 'panel', 'judges', 'escalate', 'reviewers', 'models', 'max_runs_per_day', 'max_usd_per_day']);
+    const unknown = Object.keys(patch).find(key => !known.has(key));
+    if (unknown)
+        return `not a reviewer setting a person can change: ${unknown}`;
+    const ok = (value, test) => value === null || value === undefined || test(value);
+    if (!ok(patch.enabled, v => typeof v === 'boolean'))
+        return 'enabled is true or false';
+    if (!ok(patch.mode, v => v === 'single' || v === 'cross' || v === 'full'))
+        return 'mode is single, cross or full';
+    if (!ok(patch.panel, v => typeof v === 'boolean'))
+        return 'panel is true or false';
+    if (!ok(patch.judges, v => v === 2 || v === 3))
+        return 'judges is 2 or 3';
+    if (!ok(patch.escalate, v => v === 'always' || v === 'risk'))
+        return 'escalate is always or risk';
+    if (!ok(patch.max_runs_per_day, v => Number.isInteger(v) && v > 0))
+        return 'max_runs_per_day is a whole number above 0';
+    if (!ok(patch.max_usd_per_day, v => typeof v === 'number' && v > 0))
+        return 'max_usd_per_day is a number above 0';
+    if (!ok(patch.reviewers, v => Array.isArray(v) && v.every(x => x === 'claude' || x === 'cursor' || x === 'codex')))
+        return 'reviewers lists claude, cursor or codex';
+    // A model name is handed to an agent CLI as an argument: one that starts with "-" would be read as a flag.
+    if (!ok(patch.models, v => !!v && typeof v === 'object' && Object.values(v).every(x => typeof x === 'string' && /^[\w.:/@-]+$/.test(x) && !x.startsWith('-'))))
+        return 'models maps a reviewer to a model name (letters, digits and . : / @ -, not starting with -)';
+    return undefined;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/review/reviewer/settings.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../../types/index.js';
+import { resolveReviewer } from './settings.js';
+const team = (reviewer = {}) => ConfigSchema.parse({ version: 1, review: { reviewer } });
+describe('the reviewer settings a run uses', () => {
+    it('is one judge, no panel, until someone asks', () => {
+        expect(resolveReviewer(team(), {}, undefined, {})).toMatchObject({ enabled: false, mode: 'single', panel: false, judges: 2, escalate: 'always', source: { mode: 'team', panel: 'team' }, refused: [] });
+    });
+    it('takes the nearest layer: a flag, then the environment, then the person, then the team', () => {
+        const user = { enabled: true, mode: 'full', panel: true, judges: 3 };
+        expect(resolveReviewer(team({ mode: 'single' }), {}, user, {})).toMatchObject({ enabled: true, mode: 'full', panel: true, judges: 3, source: { mode: 'user', panel: 'user' } });
+        expect(resolveReviewer(team(), {}, user, { RIGOUR_REVIEWER_PANEL: 'off', RIGOUR_REVIEWER_MODE: 'cross' })).toMatchObject({ mode: 'cross', panel: false, source: { mode: 'env', panel: 'env' } });
+        expect(resolveReviewer(team(), { mode: 'single', panel: false }, user, { RIGOUR_REVIEWER_MODE: 'full' })).toMatchObject({ mode: 'single', source: { mode: 'flag' } });
+    });
+    it('turns a panel into a full review, since it needs two vendors', () => {
+        expect(resolveReviewer(team({ mode: 'single' }), { panel: true }, undefined, {})).toMatchObject({ mode: 'full', panel: true, source: { mode: 'flag', panel: 'flag' } });
+    });
+    it('keeps the team floor, and says what it refused', () => {
+        const floor = team({ mode: 'full', panel: 'required', mode_required: true });
+        const resolved = resolveReviewer(floor, { mode: 'single', panel: false }, { escalate: 'risk' }, {});
+        expect(resolved).toMatchObject({ mode: 'full', panel: true, escalate: 'always', required: { mode: true, panel: true } });
+        expect(resolved.refused).toEqual([
+            'panel off (flag) refused: rigour.yml sets review.reviewer.panel: required',
+            'mode single (flag) refused: rigour.yml sets review.reviewer.mode_required with mode full',
+            'escalate risk (user) refused: rigour.yml requires every review to be full',
+        ]);
+    });
+    it('reports an environment value it does not understand instead of ignoring it quietly', () => {
+        expect(resolveReviewer(team(), {}, undefined, { RIGOUR_REVIEWER_MODE: 'triple', RIGOUR_REVIEWER_PANEL: 'maybe' }).refused).toEqual([
+            'RIGOUR_REVIEWER_MODE=triple ignored: use single, cross or full',
+            'RIGOUR_REVIEWER_PANEL=maybe ignored: use on or off',
+        ]);
+    });
+    it('lets a nearer choice of one judge turn a panel off, unless the team requires it, and says when it refuses', () => {
+        expect(resolveReviewer(team({ mode: 'full', panel: 'on' }), { mode: 'single' }, undefined, {})).toMatchObject({ mode: 'single', panel: false, refused: [] });
+        expect(resolveReviewer(team(), { mode: 'single' }, { panel: true }, {})).toMatchObject({ mode: 'single', panel: false }); // the flag is nearer than your setting
+        const user = resolveReviewer(team(), {}, { mode: 'single', panel: true }, {});
+        expect(user).toMatchObject({ mode: 'full', panel: true });
+        expect(user.refused).toEqual(['mode single (user) refused: the panel (user) needs judges from two vendors']);
+        expect(resolveReviewer(team({ mode: 'full', panel: 'required' }), { mode: 'single' }, undefined, {}).refused).toEqual(['mode single (flag) refused: rigour.yml sets review.reviewer.panel: required']);
+    });
+    it('under a team floor a person cannot turn reviews off or lower the judges', () => {
+        const floor = team({ enabled: true, mode: 'full', judges: 3, mode_required: true });
+        const resolved = resolveReviewer(floor, {}, { enabled: false, judges: 2 }, {});
+        expect(resolved).toMatchObject({ enabled: true, judges: 3 });
+        expect(resolved.refused).toEqual(['reviews off (user) refused: rigour.yml requires the reviewer', 'judges 2 (user) refused: rigour.yml requires 3']);
+        expect(resolveReviewer(team({ enabled: true }), {}, { enabled: false, judges: 3 }, {})).toMatchObject({ enabled: false, judges: 3 }); // no floor: your choice
+    });
+    it('takes the lower daily cap: a person can spend less than the team allows, never more', () => {
+        expect(resolveReviewer(team({ max_runs_per_day: 20, max_usd_per_day: 5 }), {}, { max_runs_per_day: 6 }, {})).toMatchObject({ max_runs_per_day: 6, max_usd_per_day: 5, refused: [] });
+        const higher = resolveReviewer(team({ max_runs_per_day: 20 }), {}, { max_runs_per_day: 50 }, {});
+        expect(higher.max_runs_per_day).toBe(20);
+        expect(higher.refused).toEqual(['max_runs_per_day 50 (user) refused: rigour.yml caps it at 20']);
+        expect(resolveReviewer(team(), {}, { max_usd_per_day: 2 }, {})).toMatchObject({ max_usd_per_day: 2 }); // no team cap: yours
+        expect(resolveReviewer(team(), {}, undefined, {}).max_runs_per_day).toBeUndefined(); // unset by default
+    });
+});

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

@@ -1,4 +1,15 @@
 import type { Exec } from './exec.js';
+/** What the reviewer spent on one local day in this repository: agent runs, and the dollars the CLIs reported. */
+export interface DaySpend {
+    runs: number;
+    usd: number;
+}
+export interface ReviewAttempt {
+    head: string;
+    outcome: 'unavailable' | 'skipped';
+    reason: string;
+    at: string;
+}
 export interface BranchState {
     head: string;
     verdict: string;
@@ -6,6 +17,8 @@ export interface BranchState {
     chain: number;
     rulesHash: string;
     reviewsKey: string;
+    /** Everything but the commit that decides a verdict: the same commit with the same key reuses it. */
+    inputsKey?: string;
     at: string;
 }
 export declare class VerdictStore {
@@ -19,8 +32,18 @@ export declare class VerdictStore {
     writeJson(file: string, value: unknown): void;
     branchState(branch: string): BranchState | undefined;
     recordBranch(branch: string, state: Omit<BranchState, 'chain' | 'at'>): void;
-    /** The branch's record (`json`), the background reviewer's `pid` and `log`. */
-    branchFile(branch: string, kind?: 'json' | 'pid' | 'log'): string;
+    /** Today's spend, summed from the day's append-only log (one line per run or batch of runs). */
+    spend(day?: string): DaySpend;
+    /** Adds runs and reported dollars to today's log: an append, so the background reviewer and a person's run never lose each other's count. */
+    addSpend(runs: number, usd: number | undefined, day?: string): void;
+    private spendFile;
+    /** The decision a verdict led to (what blocks, what is disputed or a note), kept so the same commit is not decided again. */
+    decidedPath(verdictPath: string): string;
+    /** A review on the branch that ended without a verdict, and why: what the status shows instead of "no verdict yet". */
+    recordAttempt(branch: string, attempt: ReviewAttempt): void;
+    attempt(branch: string): ReviewAttempt | undefined;
+    /** The branch's record (`json`), its last attempt without a verdict (`attempt`), the background reviewer's `pid` and `log`. */
+    branchFile(branch: string, kind?: 'json' | 'attempt' | 'pid' | 'log'): string;
     /** Where the background reviewer checks a commit out: under the git directory, never the working tree. */
     worktreeDir(head: string): string;
 }