@rigour-labs/core 6.7.5 → 6.7.7

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');
+    });
+});

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/background.js

@@ -44,7 +44,7 @@ export async function backgroundReview(cwd, job, config, exec = defaultExec, log
         store.recordAttempt(job.branch, { head: job.head, outcome: 'skipped', reason: skip, at: new Date().toISOString() });
         log(`review of ${job.head.slice(0, 9)}: skipped (${skip})`);
         clearPid(store, job.branch);
-        return { outcome: 'skipped', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason: skip, reviewers: [], cached: false };
+        return { outcome: 'skipped', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [], dropped: [], dismissed: [], reason: skip, reviewers: [], cached: false };
     }
     const worktree = store.worktreeDir(job.head);
     const added = await exec('git', ['worktree', 'add', '--detach', worktree, job.head], { cwd, timeoutMs: 5 * GH_TIMEOUT_MS });

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

@@ -2,7 +2,7 @@ import { type LessonMode } from '../../review-learning/team-lessons.js';
 import type { RouterPolicy } from '../../deep/router.js';
 import type { PanelItem } from './panel.js';
 import { type Exec } from './exec.js';
-import type { OpenItem } from './verdict.js';
+import type { OpenItem, ServedRule } from './verdict.js';
 export declare const REVIEW_DISMISSALS: string;
 export interface ReviewDismissal {
     id: string;
@@ -59,6 +59,8 @@ export declare function buildContext(input: ContextInput): {
     text: string;
     key: string;
     risky: number | undefined;
+    rules: ServedRule[];
+    lessons: number;
 };
 /**
  * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one

package/dist/review/reviewer/context.js

@@ -15,6 +15,7 @@ import path from 'path';
 import { createHash } from 'crypto';
 import { buildReviewTask } from '../review-task.js';
 import { describeLesson, lessonsForDiff, lessonView, rejectedForDiff } from '../../review-learning/team-lessons.js';
+import { rulesForDiff } from '../../review-learning/repo-rules.js';
 import { reviewedKeys } from '../ledger.js';
 import { textSimilarity } from './consensus.js';
 import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
@@ -23,6 +24,8 @@ 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;
+/** 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;
 export function readReviewDismissals(cwd) {
     try {
@@ -78,8 +81,10 @@ export function buildContext(input) {
     const lessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS).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')}`);
-    if (task?.rules.length)
-        sections.push(`## Repository rules that name what this change touches\n${task.rules.map(r => `- ${r.source}: ${r.text}`).join('\n')}`);
+    // The repository's own rules, always: the reviewer is the boundary, and what the team wrote is the standard it checks.
+    const rules = rulesForDiff(input.cwd, input.diff, true, JUDGE_RULES).map((r) => ({ id: r.id, source: r.source, text: r.text, requirement: r.requirement }));
+    if (rules.length)
+        sections.push(`## Rules this repository wrote for itself that apply to this change (answer every one in rules, by id)\n${rules.map(r => `- [${r.id}] (${r.source}, ${r.requirement ? 'requirement' : 'guidance'}) ${r.text}`).join('\n')}`);
     if (input.checks.length)
         sections.push(`## Already found by Rigour's checks: they block on their own, so do not report them again\n${input.checks.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}`);
     const rejected = input.lessons === 'off' ? [] : rejectedForDiff(input.cwd, input.diff).map(l => {
@@ -95,7 +100,7 @@ export function buildContext(input) {
     if (docs.length)
         sections.push(`## Docs that describe the changed code (read one when its claim matters to a finding)\n${docs.map(d => `- ${d.doc} (names ${d.names.join(', ')})`).join('\n')}`);
     const text = sections.length ? `# What this team already knows\n\n${sections.join('\n\n')}\n` : 'none\n';
-    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined };
+    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined, rules, lessons: lessons.length };
 }
 function where(x) {
     return x.file ? `${x.file}${x.line ? `:${x.line}` : ''}` : '(no file)';

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

@@ -35,6 +35,8 @@ describe('what the judges are told the team knows', () => {
             expect(told()).not.toContain('Log the save id');
             expect(told('all')).toContain('Log the save id on failure.');
             expect(told('off')).not.toContain('idempotent');
+            fs.writeFileSync(path.join(repo, 'AGENTS.md'), '- Every call to `save` in `src/a.ts` must be idempotent on retry.\n');
+            expect(told()).toMatch(/## Rules this repository wrote for itself[^\n]*\n- \[[0-9a-f]{10}\] \(AGENTS\.md, requirement\) Every call to `save` in `src\/a\.ts` must be idempotent on retry\./);
         }
         finally {
             fs.rmSync(repo, { recursive: true, force: true });

package/dist/review/reviewer/prompt.js

@@ -111,12 +111,18 @@ Do these steps in order. Report only what you verified in the code, with file:li
    reviewers asked for before; it is not a finding by itself. When the change does repeat it, write
    the finding as for any other miss (input, consequence, quote), naming the lesson in why.
 
-10. Review the diff the way the human reviewers do: correctness, production cost, dead code and
+10. Repository rules. For EVERY rule listed under "Rules this repository wrote for itself" in the
+   team knowledge file, say in rules, by the rule's id, whether this change follows it, breaks it,
+   or does not apply to it. For a break give file, line and quote: the code that breaks it, copied
+   exactly. Judge each rule as written, never widened. A rule marked requirement, broken, with its
+   quote verified, blocks; guidance broken is shown as a should-fix.
+
+11. Review the diff the way the human reviewers do: correctness, production cost, dead code and
    unreferenced exports (a test is not a consumer), code duplicated across sibling routes or
    runners, links or ids built outside the helper that owns them, and the repository's rules.
 
-The lists from steps 2-9 are your working notes: people see them, and they never block on their
-own. A miss blocks only when you also put it in findings, with all three of:
+The lists from steps 2-10 are your working notes: people see them, and they never block on their
+own, with one exception: a requirement rule you mark broken, with its quote verified, blocks. A miss blocks only when you also put it in findings, with all three of:
 - input: the concrete input, state or sequence that goes wrong (a user edits, a retry, two runs at once);
 - consequence: what goes wrong for that input, or the cost (reads, calls or memory per what);
 - quote: the code at file:line that does it, copied exactly from the file (one to three lines).
@@ -155,6 +161,7 @@ Your final message must be ONLY this JSON, starting with { and ending with }, no
  "siblings":[{"changed":"file:line","sibling":"file:line","needs_same_change":true|false,"has_it":true|false,"why":"..."}],
  "claims":[{"source":"comment"|"description","claim":"...","file":"<code that contradicts it>","line":0,"holds":true|false,"evidence":"..."}],
  "lessons":[{"lesson":"<the lesson as listed>","applies":true|false,"file":"...","line":0,"evidence":"..."}],
+ "rules":[{"id":"<the rule's id as listed>","status":"followed"|"broken"|"not-applicable","file":"...","line":0,"quote":"<when broken: the code that breaks it, copied exactly>","evidence":"..."}],
  "findings":[{"class":"...","severity":"blocking"|"should","file":"...","line":0,"issue":"...","why":"...","input":"...","consequence":"<wrong outcome for that input, or the cost; empty for an opinion>","quote":"<the code at file:line, copied exactly>","absent":"<for a missing call or check: the exact text that is missing>"}],
  "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"}]}`;
@@ -162,7 +169,7 @@ Your final message must be ONLY this JSON, starting with { and ending with }, no
 export function deltaBlock(previousHead, previousVerdict, previousOpenFile, commitsFile, deltaDiffFile, settledFile) {
     return `- DELTA MODE. The previous verdict on ${previousHead.slice(0, 9)} is at ${previousVerdict}; its open
   items, each with an id, are in ${previousOpenFile}. Only the commits in ${commitsFile} are new;
-  their diff is ${deltaDiffFile}. Do steps 1-10 on that diff and on every file an open item names.
+  their diff is ${deltaDiffFile}. Do steps 1-11 on that diff and on every file an open item names.
   Then, for EVERY previous open item: put its id in "carried" if it still stands, or in
   "resolved_previous" with the fix quoted at file:line. An id you leave out is treated as still open.
   Human points the previous verdict resolved, whose files these commits do not touch, are in

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

@@ -0,0 +1,71 @@
+import type { Accounting, OpenItem, Verdict } from './verdict.js';
+export interface ReviewRecord {
+    version: 1;
+    head: string;
+    base: string;
+    scope: 'full' | 'delta';
+    at: string;
+    judges: Array<{
+        reviewer: string;
+        version?: string;
+        model?: string;
+        cost_usd?: number;
+        turns?: number;
+    }>;
+    /** Checked by Rigour against the checkout. */
+    verified: {
+        blocking: OpenItem[];
+        should_fix: OpenItem[];
+        /** The repository's own rules served to the judge, and its answers. */
+        rules: {
+            served: number;
+            followed: number;
+            broken: number;
+            not_applicable: number;
+        };
+        /** The team's lessons served, and how many the judge found the change repeats. */
+        lessons: {
+            served: number;
+            applied: number;
+        };
+        prior_points: {
+            open: number;
+            resolved: number;
+            answer_in_reply: number;
+        };
+        unverified: number;
+        notes: number;
+        disputed: number;
+    };
+    /** Recorded as reported, not checked by Rigour. */
+    reported: {
+        human_reviews: number;
+    };
+    /** Decisions people made. */
+    people: {
+        dismissed: number;
+    };
+    /** sha256 of everything above, keys sorted, so a copy can be checked against the original. */
+    integrity: string;
+}
+export interface RecordInput {
+    head: string;
+    base: string;
+    scope: 'full' | 'delta';
+    verdict: Verdict;
+    accounted: Accounting & {
+        disputed: OpenItem[];
+        dismissed: OpenItem[];
+    };
+    judges: ReviewRecord['judges'];
+    lessonsServed: number;
+    humanReviews: number;
+    at?: string;
+}
+export declare function buildRecord(input: RecordInput): ReviewRecord;
+/** The hash a record's integrity field must equal; a record whose hash differs was changed after Rigour wrote it. */
+export declare function integrityOf(body: Omit<ReviewRecord, 'integrity'>): string;
+/** Checks that a record's contents hash to its integrity field. */
+export declare function recordIntact(record: ReviewRecord): boolean;
+/** The record as a pull request summary shows it: blocks in full, a few should-fixes, the counts, the judges, the hash. */
+export declare function recordLines(r: ReviewRecord, shouldFixShown?: number): string[];

package/dist/review/reviewer/record.js

@@ -0,0 +1,69 @@
+/**
+ * The record of one review: what Rigour checked against the checkout, what it could only record as
+ * reported, who decided what, and who judged, with an integrity hash so a copy can be checked against
+ * the original. Nothing in it rests on a judge's word alone: every blocking or should-fix item here
+ * passed the quote check, and every rule and lesson count comes from what Rigour served and the
+ * answers it kept. The receipt a pull request carries is built from this.
+ */
+import { createHash } from 'crypto';
+export function buildRecord(input) {
+    const rules = input.verdict.rules ?? [];
+    const lessons = input.verdict.lessons ?? [];
+    const body = {
+        version: 1,
+        head: input.head,
+        base: input.base,
+        scope: input.scope,
+        at: input.at ?? new Date().toISOString(),
+        judges: input.judges,
+        verified: {
+            blocking: input.accounted.open,
+            should_fix: input.accounted.advisory,
+            rules: { served: rules.length, followed: rules.filter(r => r.status === 'followed').length, broken: rules.filter(r => r.status === 'broken').length, not_applicable: rules.filter(r => r.status === 'not-applicable').length },
+            lessons: { served: input.lessonsServed, applied: lessons.filter(l => l.applies === true).length },
+            prior_points: { open: input.accounted.open.filter(i => i.kind === 'prior').length, resolved: input.accounted.resolved.length, answer_in_reply: input.accounted.answerInReply.length },
+            unverified: input.accounted.unverified.length,
+            notes: input.accounted.notes.length,
+            disputed: input.accounted.disputed.length,
+        },
+        reported: { human_reviews: input.humanReviews },
+        people: { dismissed: input.accounted.dismissed.length },
+    };
+    return { ...body, integrity: integrityOf(body) };
+}
+/** The hash a record's integrity field must equal; a record whose hash differs was changed after Rigour wrote it. */
+export function integrityOf(body) {
+    return createHash('sha256').update(canonical(body)).digest('hex');
+}
+/** Checks that a record's contents hash to its integrity field. */
+export function recordIntact(record) {
+    const { integrity, ...body } = record;
+    return integrityOf(body) === integrity;
+}
+/** JSON with every object's keys sorted and, as JSON itself does, no undefined members: a record read back from disk hashes the same. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(v => canonical(v === undefined ? null : v)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).filter(k => object[k] !== undefined).sort().map(k => `${JSON.stringify(k)}:${canonical(object[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** The record as a pull request summary shows it: blocks in full, a few should-fixes, the counts, the judges, the hash. */
+export function recordLines(r, shouldFixShown = 5) {
+    const where = (i) => `${i.file ? `\`${i.file}${i.line ? `:${i.line}` : ''}\` ` : ''}${i.issue}${i.locations?.length ? ` (also ${i.locations.map(l => `\`${l.file}${l.line ? `:${l.line}` : ''}\``).join(', ')})` : ''}`;
+    const v = r.verified;
+    const lines = [`**Review record** · ${v.blocking.length} blocking · ${v.should_fix.length} should-fix · rules ${v.rules.followed} followed, ${v.rules.broken} broken, ${v.rules.not_applicable} not applicable of ${v.rules.served} · lessons ${v.lessons.applied} of ${v.lessons.served} apply · prior points ${v.prior_points.open} open, ${v.prior_points.resolved} resolved`];
+    for (const i of v.blocking)
+        lines.push(`- **Blocking** ${where(i)}`);
+    for (const i of v.should_fix.slice(0, shouldFixShown))
+        lines.push(`- Should fix: ${where(i)}`);
+    if (v.should_fix.length > shouldFixShown)
+        lines.push(`- …and ${v.should_fix.length - shouldFixShown} more should-fix in the record.`);
+    const folded = [[v.notes, 'working note'], [v.disputed, 'disputed'], [v.unverified, 'unverified'], [r.people.dismissed, 'dismissed']].filter(([n]) => n > 0);
+    if (folded.length)
+        lines.push(`Also seen, never blocking: ${folded.map(([n, w]) => `${n} ${w}${n === 1 || w === 'disputed' || w === 'unverified' || w === 'dismissed' ? '' : 's'}`).join(', ')}.`);
+    lines.push(`Judged by ${r.judges.map(j => `${j.reviewer}${j.version ? ` ${j.version}` : ''}${j.model ? ` (${j.model})` : ''}${typeof j.cost_usd === 'number' ? ` $${j.cost_usd.toFixed(2)}` : ''}`).join(', ') || 'no judge'} on \`${r.head.slice(0, 9)}\` against \`${r.base.slice(0, 9)}\` (${r.scope}); ${r.reported.human_reviews} human review(s) seen. Integrity \`${r.integrity.slice(0, 16)}\`.`);
+    return lines;
+}

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

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

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { buildRecord, recordIntact, recordLines } from './record.js';
+const item = (over) => ({ id: 'i1', kind: 'finding', class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'return 1;', ...over });
+const input = () => ({
+    head: 'abcdef0123456789', base: '0123456789abcdef', scope: 'full',
+    verdict: { prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [], carried: [], resolved_previous: [],
+        rules: [{ id: 'r1', status: 'followed' }, { id: 'r2', status: 'broken' }, { id: 'r3', status: 'not-applicable' }], lessons: [{ lesson: 'bound the window', applies: true }, { lesson: 'keyset', applies: false }] },
+    accounted: { open: [item({}), item({ id: 'p1', kind: 'prior', class: 'prior point', issue: 'take the lock' })], advisory: [item({ id: 's1', issue: 'could log the id' })], unverified: [item({ id: 'u1' })], notes: [item({ id: 'n1' }), item({ id: 'n2' })], resolved: [{ item: item({ id: 'old' }), evidence: 'fixed' }], answerInReply: [], disputed: [], dismissed: [item({ id: 'd1' })] },
+    judges: [{ reviewer: 'claude', version: '2.1.0', model: 'opus', cost_usd: 1.25, turns: 19 }],
+    lessonsServed: 4, humanReviews: 2, at: '2026-10-08T00:00:00Z',
+});
+describe('the review record', () => {
+    it('counts what was verified, what was reported and what people decided, and hashes it', () => {
+        const record = buildRecord(input());
+        expect(record.verified).toMatchObject({ rules: { served: 3, followed: 1, broken: 1, not_applicable: 1 }, lessons: { served: 4, applied: 1 }, prior_points: { open: 1, resolved: 1, answer_in_reply: 0 }, unverified: 1, notes: 2, disputed: 0 });
+        expect(record.verified.blocking).toHaveLength(2);
+        expect(record.verified.should_fix).toHaveLength(1);
+        expect(record).toMatchObject({ reported: { human_reviews: 2 }, people: { dismissed: 1 }, judges: [{ reviewer: 'claude', turns: 19 }] });
+        expect(record.integrity).toMatch(/^[0-9a-f]{64}$/);
+        expect(buildRecord(input()).integrity).toBe(record.integrity); // the same review hashes the same
+        expect(recordIntact(record)).toBe(true);
+        expect(recordIntact({ ...record, verified: { ...record.verified, blocking: [] } })).toBe(false); // a block removed after the fact shows
+    });
+    it('renders for a pull request: blocks in full, a few should-fixes, the counts, the judges and the hash', () => {
+        const lines = recordLines(buildRecord(input()), 1);
+        expect(lines[0]).toBe('**Review record** · 2 blocking · 1 should-fix · rules 1 followed, 1 broken, 1 not applicable of 3 · lessons 1 of 4 apply · prior points 1 open, 1 resolved');
+        expect(lines).toContain('- **Blocking** `src/job.ts:2` returns before the lock');
+        expect(lines).toContain('- Should fix: `src/job.ts:2` could log the id');
+        expect(lines.at(-2)).toBe('Also seen, never blocking: 2 working notes, 1 unverified, 1 dismissed.');
+        expect(lines.at(-1)).toMatch(/^Judged by claude 2\.1\.0 \(opus\) \$1\.25 on `abcdef012` against `012345678` \(full\); 2 human review\(s\) seen\. Integrity `[0-9a-f]{16}`\.$/);
+    });
+});

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[];