@rigour-labs/core 6.7.6 → 6.7.8

package/dist/index.d.ts

@@ -39,6 +39,7 @@ export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.j
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
 export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH, type LastReport } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact, type ReviewRecord } from './review/reviewer/record.js';
 export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';

package/dist/index.js

@@ -39,6 +39,7 @@ export { routeFiles } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
 export { learnFromReviews } from './review-learning/learn-from-reviews.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact } from './review/reviewer/record.js';
 export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';

package/dist/review/backtest-init.d.ts

@@ -1,6 +1,21 @@
 import type { Config } from '../types/index.js';
 import { type LedgerRound } from './backtest.js';
 import { type Exec } from './reviewer.js';
+export interface PrRounds {
+    /** One round per review by a person, oldest first. */
+    rounds: LedgerRound[];
+    /** When asked: the head a person approved, with no points, so a block on it is a false block. */
+    approved?: LedgerRound;
+}
+/** The ledger rounds a pull request's human reviews give, and the commit a person approved. */
+export declare function roundsForPr(cwd: string, pr: number, config: Config, exec?: Exec, options?: {
+    approvedHead?: boolean;
+}): Promise<PrRounds>;
+/** The last `n` merged pull requests, newest merge first. */
+export declare function mergedPrs(cwd: string, n: number, config: Config, exec?: Exec): Promise<Array<{
+    number: number;
+    mergedAt: string;
+}>>;
 export declare function scaffoldLedger(cwd: string, pr: number, config: Config, exec?: Exec): Promise<{
     file: string;
     rounds: LedgerRound[];

package/dist/review/backtest-init.js

@@ -12,9 +12,8 @@ import { bodyPoints, firstLine } from '../review-learning/review-points.js';
 import { LEDGER_PATH, LedgerSchema } from './backtest.js';
 import { defaultExec, githubEnv, parseJsonArrays } from './reviewer.js';
 const GH_TIMEOUT_MS = 60_000;
-/** Lines either side of an inline comment that a finding for the same point may land on. */
-const LINE_SLACK = 10;
-export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
+/** The ledger rounds a pull request's human reviews give, and the commit a person approved. */
+export async function roundsForPr(cwd, pr, config, exec = defaultExec, options = {}) {
     const env = await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec);
     const gh = (args) => exec('gh', args, { cwd, timeoutMs: GH_TIMEOUT_MS, env });
     const view = await gh(['pr', 'view', String(pr), '--json', 'author', '-q', '.author.login']);
@@ -24,10 +23,8 @@ export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
     const reviews = await gh(['api', `repos/{owner}/{repo}/pulls/${pr}/reviews`, '--paginate']);
     if (reviews.exitCode !== 0)
         throw new Error(`could not read the reviews of pull request ${pr}: ${reviews.stderr.trim()}`);
-    const humans = parseJsonArrays(reviews.stdout)
-        .filter((r) => r?.user && r.user.type !== 'Bot' && !/bot/i.test(r.user.login) && r.user.login !== author && (r.body?.trim() || r.state === 'CHANGES_REQUESTED'));
-    if (humans.length === 0)
-        throw new Error(`pull request ${pr} has no review by a person yet`);
+    const byPerson = parseJsonArrays(reviews.stdout).filter((r) => r?.user && r.user.type !== 'Bot' && !/bot/i.test(r.user.login) && r.user.login !== author);
+    const humans = byPerson.filter((r) => r.body?.trim() || r.state === 'CHANGES_REQUESTED');
     const mainRef = branchBase(cwd)?.mainRef ?? 'origin/main';
     const rounds = [];
     for (const [index, review] of humans.entries()) {
@@ -39,16 +36,33 @@ export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
             points.push({ id: `R${round}-B${i + 1}`, point: line, file: '', needs: 'a file pattern and a text pattern (this point was made in the review body, not on a line)' });
         }
         const base = await baseAt(cwd, String(review.commit_id), review.submitted_at, mainRef, exec);
-        rounds.push({
-            id: `pr${pr}-r${round}`,
-            commit: String(review.commit_id),
-            base,
-            reviewed_at: String(review.submitted_at),
-            pr,
-            points,
-            must_not_flag: [],
-        });
+        rounds.push({ id: `pr${pr}-r${round}`, commit: String(review.commit_id), base, reviewed_at: String(review.submitted_at), pr, points, must_not_flag: [] });
     }
+    const approval = options.approvedHead ? byPerson.find((r) => r.state === 'APPROVED' && r.commit_id) : undefined;
+    const approved = approval
+        ? { id: `pr${pr}-approved`, commit: String(approval.commit_id), base: await baseAt(cwd, String(approval.commit_id), approval.submitted_at, mainRef, exec), reviewed_at: String(approval.submitted_at), pr, points: [], must_not_flag: [] }
+        : undefined;
+    if (rounds.length === 0 && !approved)
+        throw new Error(`pull request ${pr} has no review by a person yet`);
+    return { rounds, ...(approved ? { approved } : {}) };
+}
+/** The last `n` merged pull requests, newest merge first. */
+export async function mergedPrs(cwd, n, config, exec = defaultExec) {
+    const env = await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec);
+    const list = await exec('gh', ['pr', 'list', '--state', 'merged', '--limit', String(n), '--json', 'number,mergedAt'], { cwd, timeoutMs: GH_TIMEOUT_MS, env });
+    if (list.exitCode !== 0)
+        throw new Error(`could not list merged pull requests: ${list.stderr.trim() || 'is gh signed in?'}`);
+    try {
+        return JSON.parse(list.stdout).sort((a, b) => (a.mergedAt < b.mergedAt ? 1 : -1)).slice(0, n);
+    }
+    catch {
+        throw new Error('could not read the list of merged pull requests');
+    }
+}
+/** Lines either side of an inline comment that a finding for the same point may land on. */
+const LINE_SLACK = 10;
+export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
+    const { rounds } = await roundsForPr(cwd, pr, config, exec);
     const file = path.join(cwd, LEDGER_PATH);
     const existing = existingLedger(file);
     const merged = { rounds: [...existing.rounds.filter(r => !rounds.some(n => n.id === r.id)), ...rounds] };

package/dist/review/backtest-last.d.ts

@@ -0,0 +1,40 @@
+import type { Config } from '../types/index.js';
+import { type BacktestItem, type BacktestOptions, type Ledger, type RoundResult } from './backtest.js';
+export declare const LAST_LEDGER_PATH = ".rigour/backtest-last.json";
+export interface EarlyCatch {
+    pr: number;
+    round: string;
+    point: string;
+    by: string;
+    roundsEarlier: number;
+}
+export interface LastReport {
+    prs: number;
+    rounds: number;
+    approvedHeads: number;
+    /** Blocking items on heads a person approved: every one is a false block. */
+    blocksOnApproved: Array<{
+        pr: number;
+        round: string;
+        item: BacktestItem;
+    }>;
+    /** Points a person raised in a later round that an earlier round had already blocked. */
+    early: EarlyCatch[];
+    /** Points caught in the round they were raised. */
+    sameRound: number;
+    /** Points raised after a pull request's first review: the pool `early` is drawn from. */
+    pointsLater: number;
+    /** Rounds whose commit is no longer reachable (a force-push), with why. */
+    skipped: string[];
+    costUsd?: number;
+    durationMs: number;
+    results: RoundResult[];
+}
+export interface LastOptions extends Pick<BacktestOptions, 'reviewer' | 'exec' | 'progress' | 'collect'> {
+    last: number;
+}
+export declare function backtestLast(cwd: string, config: Config, options: LastOptions): Promise<LastReport>;
+/** The report's numbers from a ledger and its results: pure, so a change to the scoring is measured by tests. */
+export declare function scoreLast(ledger: Ledger, results: RoundResult[]): Omit<LastReport, 'skipped'>;
+/** The two numbers first, the worse one on top; then what they rest on. */
+export declare function formatLast(r: LastReport): string;

package/dist/review/backtest-last.js

@@ -0,0 +1,116 @@
+/**
+ * `rigour backtest --last N`: the front door. The last N merged pull requests become a ledger on
+ * their own (one round per review by a person, from the inline comments, plus the head a person
+ * approved), the review runs on each with that review hidden, and the report leads with the two
+ * numbers a team needs before trusting a reviewer: blocks on heads the seniors approved (must be
+ * about none, and said first when it is not), and points people raised later that the review had
+ * already blocked, with how many rounds earlier. Then cost and time. Nothing is published; the
+ * ledger it built is written beside the hand-made one for a person to read.
+ */
+import fs from 'fs';
+import path from 'path';
+import { defaultExec } from './reviewer/exec.js';
+import { matches, runBacktest } from './backtest.js';
+import { mergedPrs, roundsForPr } from './backtest-init.js';
+export const LAST_LEDGER_PATH = '.rigour/backtest-last.json';
+const GIT_TIMEOUT_MS = 5 * 60_000;
+export async function backtestLast(cwd, config, options) {
+    const exec = options.exec ?? defaultExec;
+    const progress = options.progress ?? (() => undefined);
+    const prs = await mergedPrs(cwd, options.last, config, exec);
+    const rounds = [];
+    const skipped = [];
+    for (const pr of prs) {
+        // The reviewed commits must be here: a pull request's head is fetched once; a round force-pushed away is skipped, not guessed.
+        await exec('git', ['fetch', '-q', 'origin', `pull/${pr.number}/head`], { cwd, timeoutMs: GIT_TIMEOUT_MS });
+        let found;
+        try {
+            found = await roundsForPr(cwd, pr.number, config, exec, { approvedHead: true });
+        }
+        catch (error) {
+            skipped.push(`pull request ${pr.number}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        for (const round of [...found.rounds, ...(found.approved ? [found.approved] : [])]) {
+            const present = await exec('git', ['rev-parse', '--verify', '-q', `${round.commit}^{commit}`], { cwd, timeoutMs: GIT_TIMEOUT_MS });
+            if (present.exitCode !== 0) {
+                skipped.push(`${round.id}: commit ${round.commit.slice(0, 9)} is not reachable (force-pushed away)`);
+                continue;
+            }
+            // Unattended: only points with a file and a line window; a body point would need a person's pattern.
+            rounds.push({ ...round, points: round.points.filter(p => !p.needs && p.file && p.lines) });
+        }
+    }
+    if (rounds.length === 0)
+        throw new Error(`none of the last ${options.last} merged pull requests has a review by a person whose commits are reachable${skipped.length ? `:\n  ${skipped.join('\n  ')}` : ''}`);
+    const ledger = { rounds };
+    fs.mkdirSync(path.join(cwd, path.dirname(LAST_LEDGER_PATH)), { recursive: true });
+    fs.writeFileSync(path.join(cwd, LAST_LEDGER_PATH), JSON.stringify(ledger, null, 2));
+    progress(`backtest: ${rounds.length} round(s) from ${prs.length} merged pull request(s), ledger written to ${LAST_LEDGER_PATH}`);
+    const results = await runBacktest(cwd, config, ledger, { reviewer: options.reviewer, exec, progress, collect: options.collect });
+    return { ...scoreLast(ledger, results), skipped };
+}
+/** The report's numbers from a ledger and its results: pure, so a change to the scoring is measured by tests. */
+export function scoreLast(ledger, results) {
+    const byPr = new Map();
+    for (const round of ledger.rounds)
+        if (round.pr !== undefined)
+            byPr.set(round.pr, [...(byPr.get(round.pr) ?? []), round]);
+    const resultOf = new Map(results.map(r => [r.round, r]));
+    const early = [];
+    let pointsLater = 0;
+    for (const [pr, prRounds] of byPr) {
+        const reviews = prRounds.filter(r => !r.id.endsWith('-approved')).sort((a, b) => ((a.reviewed_at ?? '') < (b.reviewed_at ?? '') ? -1 : 1));
+        for (let j = 1; j < reviews.length; j++) {
+            for (const point of reviews[j].points) {
+                pointsLater++;
+                for (let i = 0; i < j; i++) {
+                    const hit = resultOf.get(reviews[i].id)?.items.find(item => item.blocking && matches(point, item));
+                    if (hit) {
+                        early.push({ pr, round: reviews[i].id, point: point.point, by: `${hit.gate} ${hit.file}${hit.line ? `:${hit.line}` : ''}`, roundsEarlier: j - i });
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    const approvedRounds = ledger.rounds.filter(r => r.id.endsWith('-approved'));
+    const blocksOnApproved = approvedRounds.flatMap(r => (resultOf.get(r.id)?.items ?? []).filter(i => i.blocking).map(item => ({ pr: r.pr ?? 0, round: r.id, item })));
+    const costs = results.map(r => r.costUsd).filter((c) => typeof c === 'number');
+    return {
+        prs: byPr.size,
+        rounds: ledger.rounds.length,
+        approvedHeads: approvedRounds.length,
+        blocksOnApproved,
+        early,
+        sameRound: results.reduce((n, r) => n + r.points.filter(p => p.caught).length, 0),
+        pointsLater,
+        ...(costs.length ? { costUsd: costs.reduce((a, b) => a + b, 0) } : {}),
+        durationMs: results.reduce((n, r) => n + r.durationMs, 0),
+        results,
+    };
+}
+/** The two numbers first, the worse one on top; then what they rest on. */
+export function formatLast(r) {
+    const lines = [];
+    const approved = r.blocksOnApproved.length === 0
+        ? `0 blocking items on ${r.approvedHeads} approved head(s).`
+        : `${r.blocksOnApproved.length} blocking item(s) on ${r.approvedHeads} approved head(s): every one is a block the team would have overridden.`;
+    const earlyLine = `${r.early.length} of ${r.pointsLater} point(s) people raised in a later round were already blocked${r.early.length ? `, ${(r.early.reduce((n, e) => n + e.roundsEarlier, 0) / r.early.length).toFixed(1)} round(s) earlier on average` : ''}.`;
+    if (r.blocksOnApproved.length) {
+        lines.push(approved);
+        for (const b of r.blocksOnApproved)
+            lines.push(`  ${b.round}: ${b.item.gate} ${b.item.file}${b.item.line ? `:${b.item.line}` : ''} ${b.item.text.slice(0, 140)}`);
+        lines.push(earlyLine);
+    }
+    else {
+        lines.push(earlyLine, approved);
+    }
+    for (const e of r.early)
+        lines.push(`  pr ${e.pr}, ${e.round}: "${e.point.slice(0, 100)}" blocked ${e.roundsEarlier} round(s) earlier by ${e.by}`);
+    lines.push(`${r.sameRound} point(s) caught in the round they were raised. ${r.prs} pull request(s), ${r.rounds} round(s)${r.costUsd !== undefined ? `, $${r.costUsd.toFixed(2)}` : ''}, ${Math.round(r.durationMs / 1000)} s.`);
+    for (const s of r.skipped)
+        lines.push(`skipped ${s}`);
+    lines.push(`The ledger it ran is in ${LAST_LEDGER_PATH}; nothing was sent anywhere.`);
+    return lines.join('\n');
+}

package/dist/review/backtest-last.test.d.ts

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

package/dist/review/backtest-last.test.js

@@ -0,0 +1,109 @@
+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 { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH } from './backtest-last.js';
+import { roundsForPr } from './backtest-init.js';
+const config = ConfigSchema.parse({ version: 1 });
+const item = (file, line, blocking = true, gate = 'reviewer:claude') => ({ gate, file, line, text: `${file} scan has no upper bound`, blocking });
+const result = (round, items, caught = 0, costUsd) => ({ round, head: 'h', base: 'b', points: Array.from({ length: caught }, (_, i) => ({ id: `p${i}`, point: 'p', caught: true, noted: false })), falseBlocks: [], items, durationMs: 1000, ...(costUsd !== undefined ? { costUsd } : {}) });
+describe('the front door report', () => {
+    const ledger = { rounds: [
+            { id: 'pr7-r1', commit: 'c', base: 'b', reviewed_at: '2026-04-12T12:00:00Z', pr: 7, points: [{ id: 'R1-1', point: 'drops the currency', file: 'src/b\\.ts', lines: [1, 11] }], must_not_flag: [] },
+            { id: 'pr7-r2', commit: 'c', base: 'b', reviewed_at: '2026-04-12T13:00:00Z', pr: 7, points: [{ id: 'R2-1', point: 'the export reads every line item', file: 'src/a\\.ts', lines: [1, 11] }], must_not_flag: [] },
+            { id: 'pr7-r3', commit: 'c', base: 'b', reviewed_at: '2026-04-12T14:00:00Z', pr: 7, points: [{ id: 'R3-1', point: 'still unbounded', file: 'src/a\\.ts', lines: [1, 11] }], must_not_flag: [] },
+            { id: 'pr7-approved', commit: 'c', base: 'b', reviewed_at: '2026-04-12T15:00:00Z', pr: 7, points: [], must_not_flag: [] },
+            { id: 'pr8-approved', commit: 'c', base: 'b', reviewed_at: '2026-04-13T15:00:00Z', pr: 8, points: [], must_not_flag: [] },
+        ] };
+    it('counts points raised later that an earlier round blocked, with how many rounds earlier, and every block on an approved head', () => {
+        const results = [result('pr7-r1', [item('src/a.ts', 3)]), result('pr7-r2', [item('src/a.ts', 3)], 1, 1.5), result('pr7-r3', [], 0, 0.5), result('pr7-approved', [item('src/a.ts', 3)]), result('pr8-approved', [item('src/z.ts', 9, false)])];
+        const r = scoreLast(ledger, results);
+        expect(r).toMatchObject({ prs: 2, rounds: 5, approvedHeads: 2, pointsLater: 2, sameRound: 1, costUsd: 2 });
+        expect(r.early).toEqual([
+            { pr: 7, round: 'pr7-r1', point: 'the export reads every line item', by: 'reviewer:claude src/a.ts:3', roundsEarlier: 1 },
+            { pr: 7, round: 'pr7-r1', point: 'still unbounded', by: 'reviewer:claude src/a.ts:3', roundsEarlier: 2 }, // the earliest round that blocked it counts
+        ]);
+        expect(r.blocksOnApproved).toEqual([{ pr: 7, round: 'pr7-approved', item: item('src/a.ts', 3) }]); // an advisory item on pr8 is not a block
+        const text = formatLast({ ...r, skipped: ['pr9-r1: commit abcdef012 is not reachable (force-pushed away)'] });
+        expect(text.split('\n')[0]).toBe('1 blocking item(s) on 2 approved head(s): every one is a block the team would have overridden.'); // the worse number first
+        expect(text).toContain('2 of 2 point(s) people raised in a later round were already blocked, 1.5 round(s) earlier on average.');
+        expect(text).toContain('skipped pr9-r1: commit abcdef012');
+        const clean = formatLast({ ...scoreLast(ledger, results.map(x => (x.round.endsWith('-approved') ? { ...x, items: [] } : x))), skipped: [] });
+        expect(clean.split('\n')[0]).toContain('point(s) people raised in a later round were already blocked'); // nothing on approved heads: the catches lead
+        expect(clean).toContain('0 blocking items on 2 approved head(s).');
+    });
+});
+describe('rigour backtest --last', () => {
+    let repo;
+    const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+    const commit = (message, date) => { git('add', '-A'); execFileSync('git', ['-C', repo, 'commit', '-qm', message], { env: { ...process.env, GIT_COMMITTER_DATE: date, GIT_AUTHOR_DATE: date } }); return git('rev-parse', 'HEAD'); };
+    let reviewed;
+    const fake = (calls) => async (command, args, options) => {
+        calls.push([command, ...args]);
+        if (command === 'git') {
+            if (args[0] === 'fetch')
+                return { exitCode: 0, stdout: '', stderr: '' }; // the head is already here
+            try {
+                return { exitCode: 0, stdout: execFileSync('git', args, { cwd: options.cwd, encoding: 'utf8', stdio: 'pipe' }), stderr: '' };
+            }
+            catch (error) {
+                return { exitCode: error.status ?? 1, stdout: '', stderr: String(error.stderr ?? '') };
+            }
+        }
+        if (args[0] === 'auth')
+            return { exitCode: 0, stdout: 'token\n', stderr: '' };
+        if (args[0] === 'pr' && args[1] === 'list')
+            return { exitCode: 0, stdout: JSON.stringify([{ number: 7, mergedAt: '2026-04-12T16:00:00Z' }, { number: 6, mergedAt: '2026-04-11T16:00:00Z' }]), stderr: '' };
+        if (args[0] === 'pr')
+            return { exitCode: 0, stdout: 'author\n', stderr: '' };
+        const pr = /pulls\/(\d+)\//.exec(args[1])?.[1];
+        if (args[1].endsWith('/reviews')) {
+            if (pr === '6')
+                return { exitCode: 0, stdout: JSON.stringify([{ id: 60, user: { login: 'author', type: 'User' }, body: 'self note', state: 'COMMENTED', submitted_at: '2026-04-11T12:00:00Z', commit_id: reviewed }]), stderr: '' };
+            return { exitCode: 0, stdout: JSON.stringify([
+                    { id: 1, user: { login: 'senior', type: 'User' }, body: 'first pass', state: 'CHANGES_REQUESTED', submitted_at: '2026-04-12T12:00:00Z', commit_id: reviewed },
+                    { id: 2, user: { login: 'senior', type: 'User' }, body: 'second pass', state: 'CHANGES_REQUESTED', submitted_at: '2026-04-12T13:00:00Z', commit_id: reviewed },
+                    { id: 3, user: { login: 'senior', type: 'User' }, body: '', state: 'APPROVED', submitted_at: '2026-04-12T14:00:00Z', commit_id: reviewed },
+                ]), stderr: '' };
+        }
+        if (args[1].includes('/reviews/1/'))
+            return { exitCode: 0, stdout: JSON.stringify([{ path: 'b.ts', line: 1, body: 'Drops the currency', created_at: '2026-04-12T12:00:00Z' }]), stderr: '' };
+        if (args[1].includes('/reviews/2/'))
+            return { exitCode: 0, stdout: JSON.stringify([{ path: 'a.ts', line: 1, body: 'The export reads every line item.', created_at: '2026-04-12T13:00:00Z' }]), stderr: '' };
+        return { exitCode: 0, stdout: '[]', stderr: '' };
+    };
+    beforeEach(() => {
+        repo = fs.mkdtempSync(path.join(os.tmpdir(), 'backtest-last-'));
+        git('init', '-q', '-b', 'main');
+        git('config', 'user.email', 't@example.com');
+        git('config', 'user.name', 't');
+        git('config', 'commit.gpgsign', 'false');
+        fs.writeFileSync(path.join(repo, 'a.ts'), 'export const a = 1;\n');
+        commit('main', '2026-04-12T09:00:00Z');
+        git('checkout', '-q', '-b', 'feature');
+        fs.writeFileSync(path.join(repo, 'b.ts'), 'export const b = 1;\n');
+        reviewed = commit('the branch', '2026-04-12T09:30:00Z');
+    });
+    afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+    it('builds the ledger from the last merged pull requests, the approved head included, runs it and leads with the two numbers', async () => {
+        const calls = [];
+        const report = await backtestLast(repo, config, { last: 2, exec: fake(calls), collect: async () => ({ items: [item('a.ts', 1)], costUsd: 0.25 }) });
+        expect(report).toMatchObject({ prs: 1, rounds: 3, approvedHeads: 1, pointsLater: 1, sameRound: 1, costUsd: 0.75 });
+        expect(report.early).toEqual([{ pr: 7, round: 'pr7-r1', point: 'The export reads every line item.', by: 'reviewer:claude a.ts:1', roundsEarlier: 1 }]);
+        expect(report.blocksOnApproved.map(b => b.round)).toEqual(['pr7-approved']);
+        expect(report.skipped).toEqual(['pull request 6: pull request 6 has no review by a person yet']); // the author's own note is not a review
+        expect(calls.filter(c => c[0] === 'git' && c[1] === 'fetch').map(c => c.at(-1))).toEqual(['pull/7/head', 'pull/6/head']);
+        const written = JSON.parse(fs.readFileSync(path.join(repo, LAST_LEDGER_PATH), 'utf8'));
+        expect(written.rounds.map(r => [r.id, r.points.length])).toEqual([['pr7-r1', 1], ['pr7-r2', 1], ['pr7-approved', 0]]);
+        expect(formatLast(report).split('\n')[0]).toContain('1 blocking item(s) on 1 approved head(s)');
+    });
+    it('gives the scaffolder the approved head only when asked, with no points', async () => {
+        const calls = [];
+        const without = await roundsForPr(repo, 7, config, fake(calls));
+        expect(without.approved).toBeUndefined();
+        const withHead = await roundsForPr(repo, 7, config, fake(calls), { approvedHead: true });
+        expect(withHead.approved).toMatchObject({ id: 'pr7-approved', commit: reviewed, reviewed_at: '2026-04-12T14:00:00Z', points: [] });
+    });
+});

package/dist/review/backtest.d.ts

@@ -2,6 +2,26 @@ import { z } from 'zod';
 import type { Config } from '../types/index.js';
 import { type Exec, type Progress } from './reviewer.js';
 import { type JudgeCatches, type JudgeRun } from './backtest-judges.js';
+declare const Match: z.ZodObject<{
+    /** A regular expression over the finding's file path. */
+    file: z.ZodString;
+    /** A line window at the reviewed commit: a finding inside it matches. */
+    lines: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    /** A regular expression over the finding's text; the alternative for a point with no line. */
+    text: z.ZodOptional<z.ZodString>;
+    /** Left by `rigour backtest init` on a row a person still has to complete. */
+    needs: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    text?: string | undefined;
+    lines?: [number, number] | undefined;
+    needs?: string | undefined;
+}, {
+    file: string;
+    text?: string | undefined;
+    lines?: [number, number] | undefined;
+    needs?: string | undefined;
+}>;
 declare const Point: z.ZodObject<{
     /** A regular expression over the finding's file path. */
     file: z.ZodString;
@@ -268,6 +288,7 @@ export declare const LedgerSchema: z.ZodObject<{
 export type Ledger = z.infer<typeof LedgerSchema>;
 export type LedgerRound = z.infer<typeof Round>;
 export type LedgerPoint = z.infer<typeof Point>;
+type LedgerMatch = z.infer<typeof Match>;
 export declare const LEDGER_PATH = ".rigour/backtest.json";
 /** A finding as the score sees it, from a gate or the reviewer. */
 export interface BacktestItem {
@@ -293,6 +314,8 @@ export interface RoundResult {
     durationMs: number;
     /** Why the reviewer gave no verdict, when it ran. */
     reviewerError?: string;
+    /** What the reviewer's runs cost, when it ran and reported dollars. */
+    costUsd?: number;
     /** With two or more judges: the ledger points each raised on its own, and the round's runs and cost. */
     judges?: JudgeCatches;
 }
@@ -311,10 +334,13 @@ export declare function runBacktest(cwd: string, config: Config, ledger: Ledger,
 /** Every point caught, nothing the reviewer called good flagged, and a verdict when the reviewer ran. */
 export declare function backtestPassed(results: RoundResult[]): boolean;
 export declare function score(round: LedgerRound, head: string, items: BacktestItem[], durationMs: number, reviewerError: string | undefined): RoundResult;
+/** The file pattern must match, then either the line window holds the finding's line or the text pattern matches its text. */
+export declare function matches(row: LedgerMatch, item: BacktestItem): boolean;
 interface Collected {
     items: BacktestItem[];
     reviewerError?: string;
     judged?: JudgeRun;
+    costUsd?: number;
 }
 export declare function formatBacktest(results: RoundResult[]): string;
 export {};

package/dist/review/backtest.js

@@ -96,8 +96,8 @@ export async function runBacktest(cwd, config, ledger, options = {}) {
         if (stale)
             progress(`backtest ${round.id}: warning: ${stale}`);
         const collect = options.collect ?? ((tree, r, c) => collectItems(tree, r, c, !!options.reviewer, exec, progress));
-        const { items, reviewerError, judged } = await collect(worktree, round, config);
-        const result = { ...score(round, head, items, Date.now() - started, reviewerError), ...(judged ? { judges: judgeCatches(round, judged) } : {}) };
+        const { items, reviewerError, judged, costUsd } = await collect(worktree, round, config);
+        const result = { ...score(round, head, items, Date.now() - started, reviewerError), ...(judged ? { judges: judgeCatches(round, judged) } : {}), ...(costUsd !== undefined ? { costUsd } : {}) };
         record(cwd, result);
         results.push(result);
     }
@@ -136,7 +136,7 @@ export function score(round, head, items, durationMs, reviewerError) {
     return { round: round.id, head, base: round.base, points, falseBlocks, items, durationMs, ...(reviewerError ? { reviewerError } : {}) };
 }
 /** The file pattern must match, then either the line window holds the finding's line or the text pattern matches its text. */
-function matches(row, item) {
+export function matches(row, item) {
     if (!new RegExp(row.file, 'i').test(item.file))
         return false;
     const inWindow = !!row.lines && item.line !== undefined && item.line >= row.lines[0] && item.line <= row.lines[1];
@@ -199,7 +199,7 @@ async function collectItems(worktree, round, config, reviewer, exec, progress) {
     const asReviewerItem = (item, blocking) => ({ gate: `reviewer:${item.reviewer ?? result.reviewers[0]}`, file: item.file ?? '', line: item.line, text: [item.issue, item.consequence, item.evidence].filter(Boolean).join(' '), blocking });
     items.push(...result.items.map(i => asReviewerItem(i, true)), ...[...result.advisory, ...result.unverified, ...result.notes, ...result.disputed].map(i => asReviewerItem(i, false)));
     const judged = judgedFrom(result);
-    return { items, ...(judged ? { judged } : {}) };
+    return { items, ...(judged ? { judged } : {}), ...(result.costUsd !== undefined ? { costUsd: result.costUsd } : {}) };
 }
 function asItem(failure, blocking) {
     return { gate: failure.id, file: failure.files?.[0] ?? '', line: failure.line, text: [failure.title, failure.details, failure.hint].filter(Boolean).join(' '), blocking };

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

@@ -1,12 +1,14 @@
 import { type Exec } from './exec.js';
-export type ReviewerName = 'claude' | 'cursor' | 'codex';
-export type Vendor = 'anthropic' | 'cursor' | 'openai';
+export type ReviewerName = 'claude' | 'cursor' | 'codex' | 'api';
+export type Vendor = 'anthropic' | 'cursor' | 'openai' | 'google' | 'other';
 export type ReviewMode = 'single' | 'cross' | 'full';
 export interface Adapter {
     vendor: Vendor;
     binary: string;
     /** The command line for one review: the prompt is passed as text, never through a shell. */
-    args(prompt: string, model: string | undefined): string[];
+    args(prompt: string, model: string | undefined, options?: {
+        reasoning?: 'low' | 'medium' | 'high';
+    }): string[];
     /** The reviewer's final message and, when the CLI reports them, what the run cost and the tokens it used. */
     answer(stdout: string): {
         text: string;
@@ -61,7 +63,12 @@ export declare function vendorsOf(trailers: string): Set<Vendor>;
  * whose vendor is not on the trailers, else the first available. full: that one plus the next
  * available of each other vendor, up to `judges`. Empty when none is installed.
  */
-export declare function selectReviewers(candidates: ReviewerName[], mode: ReviewMode, authors: Set<Vendor>, available: Set<ReviewerName>, judges?: number): ReviewerName[];
+export declare function selectReviewers(candidates: ReviewerName[], mode: ReviewMode, authors: Set<Vendor>, available: Set<ReviewerName>, judges?: number, vendorOf?: (name: ReviewerName) => Vendor): ReviewerName[];
+/** The maker of an API judge's model: what the team said, else what the model's name says, else other. */
+export declare function apiVendor(api: {
+    model: string;
+    vendor?: Vendor;
+} | undefined): Vendor;
 /** Every reviewer Rigour can run, and whether this machine has it: what bounds the judges of a panel. */
 export declare function reviewerAvailability(cwd: string, exec?: Exec): Promise<Array<{
     name: ReviewerName;

package/dist/review/reviewer/adapters.js

@@ -48,7 +48,7 @@ export const ADAPTERS = {
     codex: {
         vendor: 'openai',
         binary: 'codex',
-        args: (prompt, model) => ['exec', '--sandbox', 'read-only', '--json', ...(model ? ['--model', model] : []), '-c', 'model_reasoning_effort=high', prompt],
+        args: (prompt, model, options) => ['exec', '--sandbox', 'read-only', '--json', ...(model ? ['--model', model] : []), '-c', `model_reasoning_effort=${options?.reasoning ?? 'high'}`, prompt],
         // `codex exec --json` streams events; the last text-bearing one carries the answer.
         // Warnings arrive as `error` items with a `message`, not `text`, so they are never taken for the answer.
         // `turn.completed` carries the tokens (Codex reports no dollars).
@@ -71,6 +71,27 @@ export const ADAPTERS = {
             return { text: text || stdout, ...(tokens ? { tokens } : {}) };
         },
     },
+    api: {
+        // A model API, not a CLI: reviewer.ts runs the loop (api-judge.ts); the answer is the loop's JSON.
+        vendor: 'other',
+        binary: 'api',
+        args: () => [],
+        answer: stdout => {
+            try {
+                const parsed = JSON.parse(stdout);
+                const u = parsed.usage ?? {};
+                return {
+                    text: String(parsed.result ?? ''),
+                    ...(typeof parsed.cost_usd === 'number' ? { costUsd: parsed.cost_usd } : {}),
+                    tokens: { input: n(u.input) + n(u.cacheRead) + n(u.cacheWrite), output: n(u.output) },
+                    ...(parsed.trace ? { trace: parsed.trace } : {}),
+                };
+            }
+            catch {
+                return { text: stdout };
+            }
+        },
+    },
 };
 export function isReviewerName(name) {
     return name in ADAPTERS;
@@ -83,6 +104,8 @@ const EXTRA_BIN_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', path.join(os.home
  * refuses current models, so the version decides, not PATH order.
  */
 export async function resolveAdapter(adapter, cwd, exec) {
+    if (adapter.binary === 'api')
+        return undefined; // never a binary: reviewer.ts installs it from review.reviewer.api
     const names = process.platform === 'win32' ? [`${adapter.binary}.cmd`, `${adapter.binary}.exe`, adapter.binary] : [adapter.binary];
     const dirs = [...(process.env.PATH ?? '').split(path.delimiter), ...EXTRA_BIN_DIRS].filter(Boolean);
     const candidates = new Set();
@@ -141,27 +164,43 @@ export function vendorsOf(trailers) {
  * whose vendor is not on the trailers, else the first available. full: that one plus the next
  * available of each other vendor, up to `judges`. Empty when none is installed.
  */
-export function selectReviewers(candidates, mode, authors, available, judges = 2) {
+export function selectReviewers(candidates, mode, authors, available, judges = 2, vendorOf = name => ADAPTERS[name].vendor) {
     const installed = candidates.filter(name => available.has(name));
     if (installed.length === 0)
         return [];
     let first = installed[0];
     if (mode !== 'single')
-        first = installed.find(name => !authors.has(ADAPTERS[name].vendor)) ?? first;
+        first = installed.find(name => !authors.has(vendorOf(name))) ?? first;
     if (mode !== 'full')
         return [first];
     const chosen = [first];
     for (const name of installed) {
         if (chosen.length >= judges)
             break;
-        if (!chosen.some(c => ADAPTERS[c].vendor === ADAPTERS[name].vendor))
+        if (!chosen.some(c => vendorOf(c) === vendorOf(name)))
             chosen.push(name);
     }
     return chosen;
 }
+/** The maker of an API judge's model: what the team said, else what the model's name says, else other. */
+export function apiVendor(api) {
+    if (!api)
+        return 'other';
+    if (api.vendor)
+        return api.vendor;
+    const model = api.model.toLowerCase();
+    if (/claude|anthropic/.test(model))
+        return 'anthropic';
+    if (/gpt|openai|^o[1-9]/.test(model))
+        return 'openai';
+    if (/gemini|google/.test(model))
+        return 'google';
+    return 'other';
+}
 /** Every reviewer Rigour can run, and whether this machine has it: what bounds the judges of a panel. */
 export async function reviewerAvailability(cwd, exec = defaultExec) {
-    return Promise.all(Object.keys(ADAPTERS).map(async (name) => {
+    // The CLIs only: the api judge is configured, not installed (reviewer.ts).
+    return Promise.all(Object.keys(ADAPTERS).filter(name => ADAPTERS[name].binary !== 'api').map(async (name) => {
         const found = await resolveAdapter(ADAPTERS[name], cwd, exec);
         return { name, vendor: ADAPTERS[name].vendor, binary: ADAPTERS[name].binary, installed: !!found, ...(found ? { version: found.version } : {}) };
     }));

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { ADAPTERS } from './adapters.js';
+import { ADAPTERS, apiVendor, selectReviewers } from './adapters.js';
 /** A real `codex exec --json` run (codex-cli 0.160.1), the warning's path shortened: the shape the adapter must read. */
 const CODEX = [
     '{"type":"thread.started","thread_id":"01a11477-f9fd-7472-8d31-5863de4cbbdb"}',
@@ -43,3 +43,18 @@ describe('reading an agent CLI\'s answer', () => {
         expect(ADAPTERS.claude.args('p', undefined)).toEqual(expect.arrayContaining(['--output-format', 'stream-json', '--verbose']));
     });
 });
+describe('a judge reached through an API', () => {
+    it('is told apart by its model\'s maker, so cross and full modes pair it with a different vendor', () => {
+        expect(apiVendor({ model: 'anthropic/claude-sonnet-4.5' })).toBe('anthropic');
+        expect(apiVendor({ model: 'gpt-5' })).toBe('openai');
+        expect(apiVendor({ model: 'google/gemini-2.5-pro' })).toBe('google');
+        expect(apiVendor({ model: 'qwen3-coder' })).toBe('other');
+        expect(apiVendor({ model: 'qwen3-coder', vendor: 'openai' })).toBe('openai');
+        const vendorOf = (name) => (name === 'api' ? 'openai' : ADAPTERS[name].vendor);
+        expect(selectReviewers(['claude', 'api'], 'cross', new Set(['anthropic']), new Set(['claude', 'api']), 2, vendorOf)).toEqual(['api']); // the author's vendor is skipped
+        expect(selectReviewers(['claude', 'api'], 'full', new Set(), new Set(['claude', 'api']), 2, vendorOf)).toEqual(['claude', 'api']);
+        expect(ADAPTERS.api.answer(JSON.stringify({ result: '{"prior_points":[]}', usage: { input: 10, cacheRead: 5, cacheWrite: 0, output: 3 }, cost_usd: 0.02, trace: { turns: 2, usage: {}, calls: [] } }))).toMatchObject({ text: '{"prior_points":[]}', costUsd: 0.02, tokens: { input: 15, output: 3 }, trace: { turns: 2 } });
+        expect(ADAPTERS.codex.args('p', undefined, { reasoning: 'medium' })).toContain('model_reasoning_effort=medium');
+        expect(ADAPTERS.codex.args('p', undefined)).toContain('model_reasoning_effort=high');
+    });
+});