@rigour-labs/core 6.7.6 → 6.7.8

package/dist/review/reviewer/api-judge.d.ts

@@ -0,0 +1,28 @@
+import type { RunTrace } from './adapters.js';
+export type Reasoning = 'low' | 'medium' | 'high';
+export interface ApiJudgeOptions {
+    /** The API's base URL; `/chat/completions` is appended. */
+    url: string;
+    model: string;
+    key: string;
+    maxTurns: number;
+    timeoutMs: number;
+    cwd: string;
+    /** Where the tools may read: the checkout and the review's input folder. */
+    roots: string[];
+    reasoning?: Reasoning;
+    fetchImpl?: typeof fetch;
+}
+export interface ApiJudgeRun {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** What a run's stdout carries on success, for the adapter to read. */
+export interface ApiJudgeAnswer {
+    result: string;
+    usage: RunTrace['usage'];
+    cost_usd?: number;
+    trace: RunTrace;
+}
+export declare function runApiJudge(prompt: string, o: ApiJudgeOptions): Promise<ApiJudgeRun>;

package/dist/review/reviewer/api-judge.js

@@ -0,0 +1,161 @@
+/**
+ * A judge reached through a model API instead of an agent CLI, so any model a team can call works as
+ * a reviewer: OpenAI-compatible chat completions with tools (OpenAI, OpenRouter, a local server, other
+ * vendors through a gateway). Rigour runs the loop itself: the model asks for a read-only tool, Rigour
+ * runs it inside the checkout (and the review's own input folder) and hands the result back, until
+ * the model answers. The same prompt, the same evidence contract and the same trace as a CLI judge;
+ * the key comes from an environment variable named in rigour.yml, never from the file.
+ */
+import fs from 'fs';
+import path from 'path';
+import { execa } from 'execa';
+const SYSTEM = 'You review code with read-only tools. Read the files the task names with read_file (the review inputs are named by absolute path), search the repository with search, read history with git. When you are done, reply with the final answer the task asks for and nothing else.';
+const MAX_RESULT_CHARS = 60_000;
+const GIT_ALLOWED = new Set(['log', 'show', 'diff', 'blame', 'grep', 'ls-files', 'rev-parse', 'merge-base']);
+/** Git options that write, or point git at another repository. */
+const GIT_REFUSED = /^(--output|-o$|--git-dir|--work-tree|-C$|--exec-path|-c$|--config-env)/;
+const TOOLS = [
+    { type: 'function', function: { name: 'read_file', description: 'Read a file in the repository or the review inputs, or a line range of it.', parameters: { type: 'object', properties: { path: { type: 'string' }, start_line: { type: 'integer' }, end_line: { type: 'integer' } }, required: ['path'] } } },
+    { type: 'function', function: { name: 'search', description: 'Search the tracked files for a regular expression (git grep -n), optionally under one path.', parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' } }, required: ['pattern'] } } },
+    { type: 'function', function: { name: 'list_dir', description: 'List a directory in the repository or the review inputs.', parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } } },
+    { type: 'function', function: { name: 'git', description: 'Run a read-only git command in the repository: log, show, diff, blame, grep, ls-files, rev-parse, merge-base.', parameters: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' } } }, required: ['args'] } } },
+];
+const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+export async function runApiJudge(prompt, o) {
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const deadline = Date.now() + o.timeoutMs;
+    const messages = [{ role: 'system', content: SYSTEM }, { role: 'user', content: prompt }];
+    const usage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+    const calls = [];
+    let cost;
+    const fail = (why) => ({ exitCode: 1, stdout: '', stderr: `api judge (${o.model}): ${why}` });
+    for (let turn = 1; turn <= o.maxTurns; turn++) {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return fail(`timed out after ${o.timeoutMs} ms`);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), left);
+        let response;
+        try {
+            response = await fetchImpl(`${o.url.replace(/\/$/, '')}/chat/completions`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${o.key}` },
+                body: JSON.stringify({ model: o.model, messages, tools: TOOLS, tool_choice: 'auto', ...(o.reasoning ? { reasoning_effort: o.reasoning } : {}) }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            return fail(`request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok)
+            return fail(`HTTP ${response.status}: ${(await response.text()).slice(0, 300)}`);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return fail('the answer was not JSON');
+        }
+        const u = body.usage ?? {};
+        const cached = n(u.prompt_tokens_details?.cached_tokens);
+        usage.input += Math.max(0, n(u.prompt_tokens) - cached);
+        usage.cacheRead += cached;
+        usage.output += n(u.completion_tokens);
+        if (typeof u.cost === 'number')
+            cost = (cost ?? 0) + u.cost;
+        const message = body.choices?.[0]?.message;
+        if (!message)
+            return fail('no choices in the answer');
+        messages.push(message);
+        const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+        if (toolCalls.length === 0) {
+            const answer = { result: String(message.content ?? ''), usage, ...(cost !== undefined ? { cost_usd: cost } : {}), trace: { turns: turn, usage, calls } };
+            return { exitCode: 0, stdout: JSON.stringify(answer), stderr: '' };
+        }
+        for (const call of toolCalls) {
+            const ran = await runTool(call, o);
+            calls.push({ turn, tool: ran.tool, target: ran.target, resultChars: ran.result.length });
+            messages.push({ role: 'tool', tool_call_id: call.id, content: ran.result });
+        }
+    }
+    return fail(`no answer within ${o.maxTurns} turns`);
+}
+/** One tool call, inside the allowed roots only; the trace names tools as the CLI judges do (Read, Grep, Glob, Bash). */
+async function runTool(call, o) {
+    const name = String(call?.function?.name ?? '');
+    let args = {};
+    try {
+        args = JSON.parse(call?.function?.arguments || '{}');
+    }
+    catch {
+        return { tool: name, target: '', result: 'refused: the arguments were not JSON' };
+    }
+    const clip = (text) => (text.length > MAX_RESULT_CHARS ? `${text.slice(0, MAX_RESULT_CHARS)}\n…[truncated at ${MAX_RESULT_CHARS} characters]` : text);
+    if (name === 'read_file') {
+        const target = inside(String(args.path ?? ''), o);
+        if (!target)
+            return { tool: 'Read', target: String(args.path ?? ''), result: 'refused: outside the repository and the review inputs' };
+        try {
+            const lines = fs.readFileSync(target, 'utf8').split('\n');
+            const start = Math.max(1, Number(args.start_line) || 1);
+            const end = Math.min(lines.length, Number(args.end_line) || lines.length);
+            return { tool: 'Read', target, result: clip(lines.slice(start - 1, end).map((l, i) => `${start + i}: ${l}`).join('\n')) };
+        }
+        catch (error) {
+            return { tool: 'Read', target, result: `error: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    if (name === 'list_dir') {
+        const target = inside(String(args.path ?? '.'), o);
+        if (!target)
+            return { tool: 'Glob', target: String(args.path ?? ''), result: 'refused: outside the repository and the review inputs' };
+        try {
+            return { tool: 'Glob', target, result: clip(fs.readdirSync(target, { withFileTypes: true }).map(e => (e.isDirectory() ? `${e.name}/` : e.name)).join('\n')) };
+        }
+        catch (error) {
+            return { tool: 'Glob', target, result: `error: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    if (name === 'search') {
+        const pattern = String(args.pattern ?? '');
+        const under = args.path ? inside(String(args.path), o) : undefined;
+        if (args.path && !under)
+            return { tool: 'Grep', target: pattern, result: 'refused: outside the repository' };
+        const run = await execa('git', ['grep', '-n', '-I', '-e', pattern, ...(under ? ['--', path.relative(o.cwd, under) || '.'] : [])], { cwd: o.cwd, reject: false, maxBuffer: 16 * 1024 * 1024 });
+        return { tool: 'Grep', target: pattern, result: clip(run.stdout || (run.exitCode === 1 ? '(no match)' : run.stderr)) };
+    }
+    if (name === 'git') {
+        const gitArgs = Array.isArray(args.args) ? args.args.map(String) : [];
+        if (!GIT_ALLOWED.has(gitArgs[0] ?? '') || gitArgs.some(a => GIT_REFUSED.test(a)))
+            return { tool: 'Bash', target: `git ${gitArgs.join(' ')}`, result: 'refused: only read-only git commands, without options that write or point elsewhere' };
+        const run = await execa('git', ['--no-pager', ...gitArgs], { cwd: o.cwd, reject: false, maxBuffer: 16 * 1024 * 1024 });
+        return { tool: 'Bash', target: `git ${gitArgs.join(' ')}`, result: clip(run.stdout || run.stderr) };
+    }
+    return { tool: name, target: '', result: `refused: no tool named ${name}` };
+}
+/** The real path of `p` when it lies under one of the roots; undefined otherwise (a symlink out is outside). */
+function inside(p, o) {
+    const resolved = path.resolve(o.cwd, p);
+    let real;
+    try {
+        real = fs.realpathSync(resolved);
+    }
+    catch {
+        return undefined;
+    }
+    for (const root of o.roots) {
+        let base;
+        try {
+            base = fs.realpathSync(root);
+        }
+        catch {
+            continue;
+        }
+        if (real === base || real.startsWith(base + path.sep))
+            return real;
+    }
+    return undefined;
+}

package/dist/review/reviewer/api-judge.test.d.ts

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

package/dist/review/reviewer/api-judge.test.js

@@ -0,0 +1,87 @@
+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 { runApiJudge } from './api-judge.js';
+let repo;
+let work;
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'api-judge-'));
+    work = fs.mkdtempSync(path.join(os.tmpdir(), 'api-judge-inputs-'));
+    execFileSync('git', ['-C', repo, 'init', '-q']);
+    fs.mkdirSync(path.join(repo, 'src'));
+    fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export function job() {\n    return 1;\n}\n');
+    execFileSync('git', ['-C', repo, 'add', '-A']);
+    execFileSync('git', ['-C', repo, '-c', 'user.email=t@x', '-c', 'user.name=t', 'commit', '-qm', 'init']);
+    fs.writeFileSync(path.join(work, 'full.diff'), '+++ b/src/job.ts\n');
+});
+afterEach(() => { for (const d of [repo, work])
+    fs.rmSync(d, { recursive: true, force: true }); });
+/** A model that plays a scripted conversation: each entry is what it answers to the next request. */
+function model(turns) {
+    const seen = [];
+    let i = 0;
+    const fetchImpl = (async (_url, init) => {
+        const body = JSON.parse(init.body);
+        seen.push(body);
+        const turn = turns[i++] ?? { text: 'done' };
+        if (turn.status)
+            return new Response('nope', { status: turn.status });
+        const message = turn.tools
+            ? { role: 'assistant', content: null, tool_calls: turn.tools.map((t, k) => ({ id: `c${i}-${k}`, type: 'function', function: { name: t.name, arguments: JSON.stringify(t.args) } })) }
+            : { role: 'assistant', content: turn.text };
+        return new Response(JSON.stringify({ choices: [{ message }], usage: turn.usage ?? { prompt_tokens: 100, completion_tokens: 10, prompt_tokens_details: { cached_tokens: 60 } } }), { status: 200, headers: { 'content-type': 'application/json' } });
+    });
+    return { fetchImpl, seen };
+}
+const options = (fetchImpl, extra = {}) => ({ url: 'https://example.test/v1', model: 'some-model', key: 'k', maxTurns: 10, timeoutMs: 30_000, cwd: repo, roots: [repo, work], fetchImpl, ...extra });
+describe('the API judge', () => {
+    it('runs the tools the model asks for inside the checkout and the inputs, then returns its answer with the usage and the trace', async () => {
+        const { fetchImpl, seen } = model([
+            { tools: [{ name: 'read_file', args: { path: path.join(work, 'full.diff') } }, { name: 'read_file', args: { path: 'src/job.ts', start_line: 2, end_line: 2 } }] },
+            { tools: [{ name: 'search', args: { pattern: 'return' } }, { name: 'git', args: { args: ['log', '-1', '--format=%s'] } }, { name: 'list_dir', args: { path: 'src' } }] },
+            { text: '{"prior_points":[]}', usage: { prompt_tokens: 50, completion_tokens: 5, cost: 0.01 } },
+        ]);
+        const run = await runApiJudge('review this', options(fetchImpl));
+        expect(run.exitCode).toBe(0);
+        const answer = JSON.parse(run.stdout);
+        expect(answer.result).toBe('{"prior_points":[]}');
+        expect(answer.usage).toEqual({ input: 130, cacheRead: 120, cacheWrite: 0, output: 25 });
+        expect(answer.cost_usd).toBe(0.01);
+        expect(answer.trace.turns).toBe(3);
+        expect(answer.trace.calls.map(c => c.tool)).toEqual(['Read', 'Read', 'Grep', 'Bash', 'Glob']);
+        const toolResults = (request) => request.messages.filter((m) => m.role === 'tool').map((m) => m.content);
+        expect(toolResults(seen[1])).toEqual(['1: +++ b/src/job.ts\n2: ', '2:     return 1;']); // turn 1's reads, as the model got them
+        expect(toolResults(seen[2]).slice(2)).toEqual(['src/job.ts:2:    return 1;', 'init', 'job.ts']); // turn 2's search, git and listing
+        expect(seen[0].messages[0].role).toBe('system');
+        expect(seen[0].tools.map((t) => t.function.name)).toEqual(['read_file', 'search', 'list_dir', 'git']);
+    });
+    it('refuses to read outside the roots, a symlink out included, and refuses git that writes or points elsewhere', async () => {
+        fs.symlinkSync(os.homedir(), path.join(repo, 'out'));
+        const { fetchImpl, seen } = model([
+            { tools: [{ name: 'read_file', args: { path: '/etc/hosts' } }, { name: 'read_file', args: { path: 'out/.bashrc' } }, { name: 'git', args: { args: ['log', '--output=/tmp/x'] } }, { name: 'git', args: { args: ['push'] } }, { name: 'nope', args: {} }] },
+            { text: 'ok' },
+        ]);
+        await runApiJudge('p', options(fetchImpl));
+        const results = seen[1].messages.filter((m) => m.role === 'tool').map((m) => m.content);
+        expect(results).toEqual([
+            'refused: outside the repository and the review inputs', 'refused: outside the repository and the review inputs',
+            'refused: only read-only git commands, without options that write or point elsewhere', 'refused: only read-only git commands, without options that write or point elsewhere',
+            'refused: no tool named nope',
+        ]);
+    });
+    it('fails closed on a turn cap, an HTTP error and a timeout, saying why', async () => {
+        const loop = model(Array.from({ length: 5 }, () => ({ tools: [{ name: 'list_dir', args: { path: '.' } }] })));
+        expect(await runApiJudge('p', options(loop.fetchImpl, { maxTurns: 3 }))).toMatchObject({ exitCode: 1, stderr: expect.stringContaining('no answer within 3 turns') });
+        expect(await runApiJudge('p', options(model([{ status: 429 }]).fetchImpl))).toMatchObject({ exitCode: 1, stderr: expect.stringContaining('HTTP 429') });
+        const slow = (async (_u, init) => new Promise((_r, reject) => init.signal.addEventListener('abort', () => reject(new Error('aborted')))));
+        expect(await runApiJudge('p', options(slow, { timeoutMs: 50 }))).toMatchObject({ exitCode: 1, stderr: expect.stringContaining('request failed') });
+    });
+    it('passes the reasoning effort when asked', async () => {
+        const { fetchImpl, seen } = model([{ text: 'ok' }]);
+        await runApiJudge('p', options(fetchImpl, { reasoning: 'low' }));
+        expect(seen[0].reasoning_effort).toBe('low');
+        expect(seen[0].model).toBe('some-model');
+    });
+});

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

@@ -31,6 +31,8 @@ export interface ContextInput {
     router: RouterPolicy | undefined;
     /** Which of the team's review lessons the judges see (gates.deep.review_lessons): verified by default, all, or off. */
     lessons?: LessonMode;
+    /** The pull request under review: lessons learned only from it are its own reviews, which the judge already reads. */
+    pr?: number;
     /** The previous verdict's panel decisions, and the files changed since it. */
     previousPanel: PanelItem[] | undefined;
     touched: Set<string>;

package/dist/review/reviewer/context.js

@@ -24,6 +24,9 @@ export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.js
 const MAX_DOCS = 10;
 /** Team standards a judge is shown with the lessons about the changed files. */
 const JUDGE_STANDARDS = 15;
+/** File lessons a judge is shown: on a pull request touching a hundred files, enough for every file, at most this many per file. */
+const JUDGE_FILE_LESSONS = 30;
+const JUDGE_LESSONS_PER_FILE = 3;
 /** Rules from the repository's own rules files a judge is asked to answer, most relevant first. */
 const JUDGE_RULES = 15;
 const MAX_SETTLED = 40;
@@ -78,7 +81,7 @@ export function buildContext(input) {
         task = undefined;
     }
     // A judge reads the whole pull request: more of what the team taught fits than an agent's one question at the stop.
-    const lessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS).map(lessonView);
+    const lessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS, JUDGE_FILE_LESSONS, JUDGE_LESSONS_PER_FILE, input.pr).map(lessonView);
     if (lessons.length)
         sections.push(`## Lessons this team taught on earlier reviews, for what this change touches (context: a lesson never blocks on its own; a finding still needs its quote)\n${lessons.map(l => `- ${describeLesson(l)}`).join('\n')}`);
     // The repository's own rules, always: the reviewer is the boundary, and what the team wrote is the standard it checks.

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

@@ -35,6 +35,16 @@ export interface ResolvedReviewer {
     judges: 2 | 3;
     escalate: 'always' | 'risk';
     cross_models: Record<string, string>;
+    /** Reasoning effort per reviewer name (codex, api). */
+    reasoning: Record<string, 'low' | 'medium' | 'high'>;
+    /** The API judge, when the team configured one (review.reviewer.api). */
+    api?: {
+        url: string;
+        model: string;
+        key_env: string;
+        vendor?: 'anthropic' | 'openai' | 'google' | 'other';
+        max_turns: number;
+    };
     /** Environment variables each judge's CLI must not see (the team's, never a person's). */
     judge_env: Record<string, {
         unset: string[];

package/dist/review/reviewer/settings.js

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

package/dist/review/reviewer/verdict.js

@@ -224,7 +224,8 @@ export function account(verdict, previousOpen, verify) {
     for (const r of verdict.rules ?? []) {
         if (r.status !== 'broken' || !r.rule)
             continue;
-        const item = { id: id('repo-rule', r.file, r.id), kind: 'rule', class: 'repo-rule', file: r.file, line: r.line, issue: `breaks a rule this repository wrote for itself (${r.source}): ${r.rule}`, consequence: r.requirement ? 'the team wrote this rule as a requirement' : 'the team wrote this rule as guidance', ...(r.quote ? { quote: r.quote } : {}), evidence: r.evidence, reviewer: r.reviewer };
+        // The rule's own words are the issue, so the same point found as a finding reads alike; where it came from is the evidence.
+        const item = { id: id('repo-rule', r.file, r.id), kind: 'rule', class: 'repo-rule', file: r.file, line: r.line, issue: r.rule, consequence: r.requirement ? 'the team wrote this rule as a requirement' : 'the team wrote this rule as guidance', ...(r.quote ? { quote: r.quote } : {}), evidence: `breaks a rule this repository wrote for itself (${r.source})${r.evidence ? `: ${r.evidence}` : ''}`, reviewer: r.reviewer };
         if (r.requirement)
             add(item);
         else
@@ -274,8 +275,10 @@ export function account(verdict, previousOpen, verify) {
     }
     return { open: onePerRootCause(open), unverified, resolved, answerInReply, notes, advisory: onePerRootCause(advisory) };
 }
-/** How alike two items' words must be to be the same point made in two places. */
+/** How alike two items' words must be to be the same point made in two places; and, on the same lines, to be one point said two ways. */
 const SAME_POINT = 0.6;
+const SAME_PLACE = 0.3;
+const SAME_LINES = 3;
 /**
  * The same point found in several places is one item carrying every location, so a person reads one
  * line, not one per file. Blocking is unchanged: the item blocks until every location is fixed.
@@ -283,7 +286,9 @@ const SAME_POINT = 0.6;
 function onePerRootCause(items) {
     const kept = [];
     for (const item of items) {
-        const same = item.kind === 'prior' ? undefined : kept.find(k => k.kind !== 'prior' && k.class === item.class && textSimilarity(k, item) >= SAME_POINT);
+        // The same class in the same words anywhere, or any two non-human items on the same lines that read alike (a rule break and the finding it caused).
+        const nearby = (k) => !!k.file && k.file === item.file && k.line !== undefined && item.line !== undefined && Math.abs(k.line - item.line) <= SAME_LINES;
+        const same = item.kind === 'prior' ? undefined : kept.find(k => k.kind !== 'prior' && ((k.class === item.class && textSimilarity(k, item) >= SAME_POINT) || (nearby(k) && textSimilarity(k, item) >= SAME_PLACE)));
         if (!same) {
             kept.push(item);
             continue;

package/dist/review/reviewer.d.ts

@@ -9,6 +9,8 @@ export { defaultExec, githubEnv, githubToken, parseJsonArrays, type Exec, type P
 export { itemLine, type OpenItem } from './reviewer/verdict.js';
 export type ReviewerOutcome = 'passed' | 'findings' | 'unavailable' | 'skipped';
 export interface ReviewerOptions {
+    /** For tests: what the API judge calls instead of fetch. */
+    fetch?: typeof fetch;
     /** The pull request to read when the checkout is detached (a backtest). */
     pr?: number;
     /** ISO time: a review or comment posted from then on is not shown to the reviewer (a backtest). */

package/dist/review/reviewer.js

@@ -21,7 +21,8 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { ADAPTERS, isReviewerName, resolveAdapter, selectReviewers, vendorsOf } from './reviewer/adapters.js';
+import { runApiJudge } from './reviewer/api-judge.js';
+import { ADAPTERS, apiVendor, isReviewerName, resolveAdapter, selectReviewers, vendorsOf } from './reviewer/adapters.js';
 import { defaultExec, GH_TIMEOUT_MS, githubEnv } from './reviewer/exec.js';
 import { bodyAsOf, findPullRequest, ghFor, humanReviews, linesChanged, mergesBaseIn, rulesText, sha } from './reviewer/inputs.js';
 import { mergeImpact } from './reviewer/merge-impact.js';
@@ -76,13 +77,20 @@ async function review(cwd, base, config, exec, progress, options) {
     const candidates = settings.reviewers.filter(isReviewerName);
     const installed = new Map();
     for (const name of candidates) {
+        if (name === 'api') {
+            // The API judge is installed when the team configured it and the key it names is set.
+            if (settings.api && process.env[settings.api.key_env])
+                installed.set('api', { binary: 'api', version: settings.api.model });
+            continue;
+        }
         const found = await resolveAdapter(ADAPTERS[name], cwd, exec);
         if (found)
             installed.set(name, found);
     }
+    const vendorOf = (name) => (name === 'api' ? apiVendor(settings.api) : ADAPTERS[name].vendor);
     const authors = vendorsOf(await git(['log', '--format=%(trailers:key=Co-Authored-By,valueonly)%(trailers:key=Co-authored-by,valueonly)', `${baseSha}..HEAD`]));
     const mode = settings.mode;
-    let reviewers = selectReviewers(candidates, mode, authors, new Set(installed.keys()), settings.judges);
+    let reviewers = selectReviewers(candidates, mode, authors, new Set(installed.keys()), settings.judges, vendorOf);
     if (reviewers.length === 0)
         return none('unavailable', `no reviewer installed: ${candidates.map(n => ADAPTERS[n].binary).join(', ') || 'review.reviewer.reviewers is empty'}`);
     modeRecord = modeRan(settings, reviewers, candidates, installed);
@@ -133,7 +141,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, lessons: config.gates.deep?.review_lessons, touched: sincePrevious, checks: options.checks ?? [],
+        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, ...(pr ? { pr: pr.number } : {}), touched: sincePrevious, checks: options.checks ?? [],
         previousPanel: previousIsAncestor ? store.readJson(previous.verdict)?.panel?.items : undefined,
         docs: await relatedDocs(cwd, changedFiles, exec),
     });
@@ -199,6 +207,10 @@ async function review(cwd, base, config, exec, progress, options) {
     if (over)
         return none(settings.required.panel || settings.required.mode ? 'unavailable' : 'skipped', over, { reviewers, scope, why, pr: pr?.number });
     const work = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-reviewer-'));
+    // One judge run, by CLI or by API: the same prompt, the same cost accounting, the same trace.
+    const runJudge = (name, prompt, model) => name === 'api'
+        ? runApiJudge(prompt, { url: settings.api.url, model: settings.api.model, key: process.env[settings.api.key_env] ?? '', maxTurns: settings.api.max_turns, timeoutMs: settings.timeout_ms, cwd, roots: [cwd, work], ...(settings.reasoning[name] ? { reasoning: settings.reasoning[name] } : {}), ...(options.fetch ? { fetchImpl: options.fetch } : {}) })
+        : exec(installed.get(name).binary, ADAPTERS[name].args(prompt, model, { reasoning: settings.reasoning[name] }), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
     try {
         const file = (name, text) => {
             const target = path.join(work, name);
@@ -239,7 +251,7 @@ async function review(cwd, base, config, exec, progress, options) {
             const answers = await Promise.all(reviewers.map(async (name) => {
                 const adapter = ADAPTERS[name];
                 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) });
+                    const run = await runJudge(name, prompt, modelFor(name));
                     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
@@ -293,7 +305,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, unset: judgeUnset(name, settings.judge_env) });
+                    const run = await runJudge(name, crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name));
                     const answer = ADAPTERS[name].answer(run.stdout);
                     store.addSpend(1, answer.costUsd);
                     reserved--;

package/dist/review/reviewer.test.js

@@ -256,6 +256,33 @@ describe('the reviewer', () => {
         expect(again.cached).toBe(true);
         expect(again.record?.integrity).toBe(first.record?.integrity);
     });
+    it('reviews through the API judge when the team configured one and its key is set, with the same prompt and accounting', async () => {
+        const seen = seenNow();
+        const calls = [];
+        const fetchImpl = (async (_url, init) => {
+            const body = JSON.parse(init.body);
+            calls.push(body);
+            const last = body.messages.at(-1);
+            const message = last.role === 'user'
+                ? { role: 'assistant', content: null, tool_calls: [{ id: 't1', type: 'function', function: { name: 'read_file', arguments: JSON.stringify({ path: /(\S+full\.diff)/.exec(last.content)[1] }) } }] }
+                : { role: 'assistant', content: JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', input: 'two runs', consequence: 'two emails', quote: 'return 1;', severity: 'blocking' }] }) };
+            return new Response(JSON.stringify({ choices: [{ message }], usage: { prompt_tokens: 100, completion_tokens: 20, cost: 0.05 } }), { status: 200 });
+        });
+        const apiConfig = ConfigSchema.parse({ version: 1, review: { reviewer: { enabled: true, reviewers: ['api'], api: { url: 'https://example.test/v1', model: 'qwen3-coder', key_env: 'TEST_JUDGE_KEY' }, reasoning: { api: 'low' } } } });
+        const without = await runReviewer(repo, 'main', apiConfig, fakes(() => '', seen), () => undefined, { fetch: fetchImpl });
+        expect(without).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no reviewer installed') }); // the key is not set
+        process.env.TEST_JUDGE_KEY = 'secret';
+        try {
+            const result = await runReviewer(repo, 'main', apiConfig, fakes(() => '', seen), () => undefined, { fetch: fetchImpl, force: true });
+            expect(result).toMatchObject({ outcome: 'findings', reviewers: ['api'], costUsd: 0.1, items: [expect.objectContaining({ issue: 'returns before the lock', reviewer: 'api' })] });
+            expect(calls[0].reasoning_effort).toBe('low');
+            expect(calls[0].messages[1].content).toContain('full.diff'); // the same prompt a CLI judge gets
+            expect(result.record?.judges).toEqual([{ reviewer: 'api', version: 'qwen3-coder', cost_usd: 0.1, turns: 2 }]);
+        }
+        finally {
+            delete process.env.TEST_JUDGE_KEY;
+        }
+    });
     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;
@@ -393,7 +420,7 @@ describe('verdicts', () => {
             return { verdict, ...account(verdict, undefined, verify) };
         };
         const broken = judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', evidence: 'no lock before the read' }]);
-        expect(broken.open.map(i => [i.kind, i.class, i.issue])).toEqual([['rule', 'repo-rule', 'breaks a rule this repository wrote for itself (AGENTS.md): Every job must take the lock before its first read.']]);
+        expect(broken.open.map(i => [i.kind, i.class, i.issue, i.evidence])).toEqual([['rule', 'repo-rule', 'Every job must take the lock before its first read.', 'breaks a rule this repository wrote for itself (AGENTS.md): no lock before the read']]);
         expect(judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2 }])).toMatchObject({ open: [], unverified: [expect.objectContaining({ kind: 'rule' })] }); // no quote: not shown as a block
         expect(judged([{ id: 'r2', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;' }])).toMatchObject({ open: [], advisory: [expect.objectContaining({ class: 'repo-rule' })] }); // guidance: shown, never a block
         expect(judged([{ id: 'r1', status: 'followed' }, { id: 'r1', status: 'not-applicable' }])).toMatchObject({ open: [], notes: [], advisory: [], unverified: [] });
@@ -410,9 +437,14 @@ describe('verdicts', () => {
         const { open } = account(verdict, undefined, checkoutVerifier(repo));
         expect(open.map(i => [i.kind, i.class, i.locations ?? []])).toEqual([
             ['prior', 'prior point', []], ['prior', 'prior point', []],
-            ['finding', 'production-cost', [{ file: 'a.ts', line: 1 }]], // the same point in another file: one item, both places
-            ['finding', 'correctness', []], // a different class is a different point
+            // The same point in another file, and the same point said as another class on the next line: one item, every place.
+            ['finding', 'production-cost', [{ file: 'a.ts', line: 1 }, { file: 'src/job.ts', line: 2 }]],
         ]);
+        // A rule break and the finding it caused, on the same lines and in like words, are one item.
+        const twice = account({ ...EMPTY, prior_points: [], findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'the raw table name is inlined instead of the JOBS_TABLE constant', input: 'any run', consequence: 'a rename misses it', quote: 'return 1;' }],
+            rules: [{ id: 'r', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', rule: 'Import the JOBS_TABLE constant; do not inline the raw table name again.', source: 'AGENTS.md', requirement: true }] }, undefined, checkoutVerifier(repo));
+        expect(twice.open.map(i => i.class)).toEqual(['repo-rule']);
+        expect(twice.open[0].locations).toEqual([{ file: 'src/job.ts', line: 2 }]);
     });
     it('keeps reads, scans, redundancy and merge impact as notes with stable ids, and answers non-blocking points in the reply', () => {
         const verdict = {

package/dist/review-learning/lessons.d.ts

@@ -94,6 +94,8 @@ export declare function matchLessons(lessons: ReviewLesson[], change: ChangeShap
     includeCandidates?: boolean;
     limit?: number;
     standards?: number;
+    perFile?: number;
+    excludePr?: number;
 }): ReviewLesson[];
 /** RIGOUR_REVIEW_LESSONS points at a lessons file outside the clone (CI, or a team's shared copy). */
 export declare function lessonsPath(cwd: string): string;

package/dist/review-learning/lessons.js

@@ -179,6 +179,9 @@ export function mergeLessons(existing, incoming) {
  * change; the best-evidenced few follow the file lessons.
  */
 export function matchLessons(lessons, change, options = {}) {
+    // A lesson whose only evidence is the pull request under review is already in front of the judge as the reviewer's own points.
+    if (options.excludePr !== undefined)
+        lessons = lessons.filter(l => !l.evidence.length || l.evidence.some(e => e.pr !== options.excludePr));
     const dirs = new Set(change.files.map(f => path.posix.dirname(f)));
     const scored = lessons
         .filter(l => !!l.file && (l.state === 'verified' || (options.includeCandidates && l.state === 'candidate')) && !NOT_CODE.test(l.file))
@@ -199,7 +202,20 @@ export function matchLessons(lessons, change, options = {}) {
         .sort((a, b) => b.shared - a.shared || b.lesson.evidence.length - a.lesson.evidence.length)
         .slice(0, options.standards ?? MAX_STANDARDS)
         .map(s => s.lesson);
-    return [...scored.slice(0, options.limit ?? 5).map(s => s.lesson), ...standards];
+    // On a large change, one file's many lessons must not crowd out another file's only one: a cap per file, then the total.
+    const perFile = options.perFile ?? Infinity;
+    const taken = [];
+    const perFileCount = new Map();
+    for (const { lesson } of scored) {
+        if (taken.length >= (options.limit ?? 5))
+            break;
+        const n = perFileCount.get(lesson.file) ?? 0;
+        if (n >= perFile)
+            continue;
+        perFileCount.set(lesson.file, n + 1);
+        taken.push(lesson);
+    }
+    return [...taken, ...standards];
 }
 /** RIGOUR_REVIEW_LESSONS points at a lessons file outside the clone (CI, or a team's shared copy). */
 export function lessonsPath(cwd) {

package/dist/review-learning/repo-rules.test.js

@@ -29,6 +29,9 @@ describe('repository rules', () => {
         expect(rules[1]).toMatchObject({ paths: ['src/lib/delivery.ts'], symbols: ['deliverOrder'] });
         expect(rules[0].paths).toEqual(['migrations/']);
         expect(rules.map(r => r.requirement)).toEqual([true, true, false]); // "never", "every"; "prefer" is guidance
+        // A section that only describes an exception, with no imperative, is guidance; one that ends in an imperative is a requirement.
+        const [exceptionOnly, withImperative] = splitRules('AGENTS.md', '- **One narrow exception:** the queue table is still literally named `study_jobs`, not renamed with the feature.\n\n- **One narrow exception:** the queue table is still literally named `study_jobs`. Import the `JOBS_TABLE` constant; do not inline the raw table name again.\n');
+        expect([exceptionOnly.requirement, withImperative.requirement]).toEqual([false, true]);
         expect(rules[0].id).toMatch(/^[0-9a-f]{10}$/);
         expect(splitRules('AGENTS.md', AGENTS)[0].id).toBe(rules[0].id); // stable across runs
     });

package/dist/review-learning/review-learning.test.js

@@ -95,6 +95,15 @@ describe('lessons', () => {
         const change = { files: ['src/orders.ts'], symbols: new Set(['insert', 'insertOrder', 'orderId']) };
         expect(matchLessons(lessons, change).map(l => l.id)).toEqual(['2', '1']); // two specific shared names outrank a same-file lesson with only generic ones
         expect(matchLessons(lessons, change, { includeCandidates: true }).map(l => l.id)).toEqual(['2', '1', '3']);
+        // A lesson learned only from the pull request under review is its own reviews, already in front of the judge.
+        const own = { ...base, id: '7', text: 'from this very pull request', file: 'src/orders.ts', state: 'verified', evidence: [{ pr: 42, comment: 'c', author: 'r' }] };
+        const also = { ...own, id: '8', text: 'from this and another', evidence: [{ pr: 42, comment: 'c', author: 'r' }, { pr: 3, comment: 'd', author: 'r' }] };
+        expect(matchLessons([...lessons, own, also], change, { excludePr: 42 }).map(l => l.id).sort()).toEqual(['1', '2', '8']); // '7' is left out; '8' has evidence elsewhere too
+        // One file's many lessons never crowd out another file's only one.
+        const many = Array.from({ length: 6 }, (_, i) => ({ ...base, id: `m${i}`, text: `orders lesson ${i}`, file: 'src/orders.ts', state: 'verified', symbols: ['insertOrder', 'orderId'] }));
+        const lone = { ...base, id: 'lone', text: 'the only lesson about the manifest', file: 'src/manifest.sha', state: 'verified' };
+        const served = matchLessons([...many, lone], { files: ['src/orders.ts', 'src/manifest.sha'], symbols: new Set(['insertOrder', 'orderId']) }, { limit: 4, perFile: 3 });
+        expect(served.map(l => l.id)).toEqual(['m0', 'm1', 'm2', 'lone']);
     });
 });
 describe('learning from one pull request as it goes', () => {

package/dist/review-learning/team-lessons.d.ts

@@ -4,8 +4,8 @@ export type LessonMode = 'verified' | 'all' | 'off';
 export declare const DEFAULT_LESSON_MODE: LessonMode;
 /** The team's review lessons in play for this mode: none when off, verified ones by default. */
 export declare function activeLessons(cwd: string, mode?: LessonMode): ReviewLesson[];
-/** `standards`: how many team standards may come with the file lessons (a judge reading a whole pull request takes more than an agent's one question). */
-export declare function lessonsForDiff(cwd: string, diff: string, mode?: LessonMode, standards?: number): ReviewLesson[];
+/** `standards`, `limit`, `perFile`: how many team standards and file lessons may come, and how many per file (a judge reading a whole pull request takes more than an agent's one question). */
+export declare function lessonsForDiff(cwd: string, diff: string, mode?: LessonMode, standards?: number, limit?: number, perFile?: number, excludePr?: number): ReviewLesson[];
 /** The points this team rejected that a change touches: what the judges are told is settled. */
 export declare function rejectedForDiff(cwd: string, diff: string): ReviewLesson[];
 /** A lesson as a judge or agent sees it, in one place. */