@rigour-labs/core 6.7.2 → 6.7.5

package/dist/review/reviewer/adapters.js

@@ -21,27 +21,14 @@ export const ADAPTERS = {
         args: (prompt, model) => [
             '-p', prompt,
             ...(model ? ['--model', model] : []),
-            '--output-format', 'json',
+            '--output-format', 'stream-json', '--verbose', // every turn's usage and tool calls, for the run's trace
             '--max-turns', '80',
             '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
             '--setting-sources', 'project', '--settings', '{"hooks":{},"outputStyle":"default"}',
             '--allowedTools', ...READ_ONLY_TOOLS,
             '--disallowedTools', 'Edit', 'Write', 'NotebookEdit', 'Bash(git push:*)', 'Bash(git commit:*)',
         ],
-        answer: stdout => {
-            try {
-                const parsed = JSON.parse(stdout);
-                const usage = parsed.usage;
-                return {
-                    text: String(parsed.result ?? ''),
-                    ...(typeof parsed.total_cost_usd === 'number' ? { costUsd: parsed.total_cost_usd } : {}),
-                    ...(usage ? { tokens: { input: n(usage.input_tokens) + n(usage.cache_read_input_tokens) + n(usage.cache_creation_input_tokens), output: n(usage.output_tokens) } } : {}),
-                };
-            }
-            catch {
-                return { text: stdout };
-            }
-        },
+        answer: stdout => claudeAnswer(stdout),
     },
     cursor: {
         vendor: 'cursor',
@@ -179,3 +166,71 @@ export async function reviewerAvailability(cwd, exec = defaultExec) {
         return { name, vendor: ADAPTERS[name].vendor, binary: ADAPTERS[name].binary, installed: !!found, ...(found ? { version: found.version } : {}) };
     }));
 }
+/** Claude Code's answer: a stream of JSON events (the final `result` one carries the text and cost), or one JSON object from older runs. */
+function claudeAnswer(stdout) {
+    const events = stdout.split('\n').map(line => line.trim()).filter(line => line.startsWith('{')).flatMap(line => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const result = events.filter(e => e?.type === 'result').at(-1) ?? (events.length === 1 ? events[0] : undefined);
+    if (!result)
+        return { text: stdout };
+    const usage = result.usage;
+    const trace = traceOf(events);
+    return {
+        text: String(result.result ?? ''),
+        ...(typeof result.total_cost_usd === 'number' ? { costUsd: result.total_cost_usd } : {}),
+        ...(usage ? { tokens: { input: n(usage.input_tokens) + n(usage.cache_read_input_tokens) + n(usage.cache_creation_input_tokens), output: n(usage.output_tokens) } } : {}),
+        ...(trace ? { trace } : {}),
+    };
+}
+/** The turns, their usage and the tool calls of a stream, or undefined for a single-object answer. */
+function traceOf(events) {
+    const assistant = events.filter(e => e?.type === 'assistant' && e.message);
+    if (assistant.length === 0)
+        return undefined;
+    const usage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+    const calls = [];
+    const byId = new Map();
+    let turn = 0;
+    const seen = new Set();
+    for (const e of events) {
+        if (e?.type === 'assistant' && e.message) {
+            // One model call can arrive as several events (one per content block) sharing its id: count its usage once.
+            const id = String(e.message.id ?? `turn-${turn}`);
+            if (!seen.has(id)) {
+                seen.add(id);
+                turn++;
+                const u = e.message.usage ?? {};
+                usage.input += n(u.input_tokens);
+                usage.cacheRead += n(u.cache_read_input_tokens);
+                usage.cacheWrite += n(u.cache_creation_input_tokens);
+                usage.output += n(u.output_tokens);
+            }
+            for (const block of e.message.content ?? []) {
+                if (block?.type !== 'tool_use')
+                    continue;
+                const input = block.input ?? {};
+                const call = { turn, tool: String(block.name ?? ''), target: String(input.file_path ?? input.path ?? input.pattern ?? input.command ?? '').slice(0, 300), resultChars: 0 };
+                calls.push(call);
+                byId.set(String(block.id), call);
+            }
+        }
+        else if (e?.type === 'user' && e.message) {
+            for (const block of e.message.content ?? []) {
+                if (block?.type !== 'tool_result')
+                    continue;
+                const call = byId.get(String(block.tool_use_id));
+                if (!call)
+                    continue;
+                const content = block.content;
+                call.resultChars = typeof content === 'string' ? content.length : Array.isArray(content) ? content.reduce((sum, c) => sum + String(c?.text ?? '').length, 0) : 0;
+            }
+        }
+    }
+    return { turns: turn, usage, calls };
+}

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

@@ -20,4 +20,26 @@ describe('reading an agent CLI\'s answer', () => {
         expect(ADAPTERS.claude.answer('not json')).toEqual({ text: 'not json' });
         expect(ADAPTERS.codex.answer('plain text')).toEqual({ text: 'plain text' });
     });
+    it("reads Claude Code's event stream: the answer and cost from its result, each turn's usage once, and what every tool call read", () => {
+        const events = [
+            { type: 'system', subtype: 'init' },
+            { type: 'assistant', message: { id: 'm1', usage: { input_tokens: 10, cache_read_input_tokens: 0, cache_creation_input_tokens: 4000, output_tokens: 50 }, content: [{ type: 'tool_use', id: 't1', name: 'Read', input: { file_path: '/work/full.diff' } }] } },
+            { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 't1', content: 'x'.repeat(1200) }] } },
+            { type: 'assistant', message: { id: 'm2', usage: { input_tokens: 5, cache_read_input_tokens: 4000, cache_creation_input_tokens: 300, output_tokens: 20 }, content: [{ type: 'text', text: 'checking' }] } },
+            { type: 'assistant', message: { id: 'm2', usage: { input_tokens: 5, cache_read_input_tokens: 4000, cache_creation_input_tokens: 300, output_tokens: 20 }, content: [{ type: 'tool_use', id: 't2', name: 'Grep', input: { pattern: 'preloadAll' } }] } },
+            { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 't2', content: [{ type: 'text', text: 'src/a.ts:3' }] }] } },
+            { type: 'result', result: '{"prior_points":[]}', total_cost_usd: 0.31, usage: { input_tokens: 15, cache_read_input_tokens: 4000, cache_creation_input_tokens: 4300, output_tokens: 70 } },
+        ];
+        const answer = ADAPTERS.claude.answer(events.map(e => JSON.stringify(e)).join('\n'));
+        expect(answer).toMatchObject({ text: '{"prior_points":[]}', costUsd: 0.31, tokens: { input: 8315, output: 70 } });
+        expect(answer.trace).toEqual({
+            turns: 2, // m2 arrived as two events: one turn, counted once
+            usage: { input: 15, cacheRead: 4000, cacheWrite: 4300, output: 70 },
+            calls: [
+                { turn: 1, tool: 'Read', target: '/work/full.diff', resultChars: 1200 },
+                { turn: 2, tool: 'Grep', target: 'preloadAll', resultChars: 10 },
+            ],
+        });
+        expect(ADAPTERS.claude.args('p', undefined)).toEqual(expect.arrayContaining(['--output-format', 'stream-json', '--verbose']));
+    });
 });

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

@@ -12,7 +12,7 @@ const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding:
 const config = ConfigSchema.parse({ version: 1, review: { reviewer: { enabled: true } } });
 const originalPath = process.env.PATH;
 let PR = { number: 7, state: 'OPEN', isDraft: false, author: { login: 'author' }, body: 'desc' };
-const VERDICT = JSON.stringify({ prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [{ class: 'correctness', file: 'src/job.ts', line: 1, issue: 'never locks', consequence: 'a second run reads stale rows' }], carried: [], resolved_previous: [] });
+const VERDICT = JSON.stringify({ prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [{ class: 'correctness', file: 'src/job.ts', line: 1, issue: 'never locks', quote: 'export const job = 1;', consequence: 'a second run reads stale rows' }], carried: [], resolved_previous: [] });
 /** Real git; a pull request on the branch; a claude that answers one finding. */
 const exec = async (command, args, options) => {
     if (command === 'git') {

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

@@ -1,3 +1,4 @@
+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';
@@ -28,6 +29,8 @@ export interface ContextInput {
     dismissals: ReviewDismissal[];
     diff: string;
     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 previous verdict's panel decisions, and the files changed since it. */
     previousPanel: PanelItem[] | undefined;
     touched: Set<string>;

package/dist/review/reviewer/context.js

@@ -14,12 +14,15 @@ import fs from 'fs';
 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 { reviewedKeys } from '../ledger.js';
 import { textSimilarity } from './consensus.js';
 import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
 import { VerdictStore } from './store.js';
 export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.json');
 const MAX_DOCS = 10;
+/** Team standards a judge is shown with the lessons about the changed files. */
+const JUDGE_STANDARDS = 15;
 const MAX_SETTLED = 40;
 export function readReviewDismissals(cwd) {
     try {
@@ -66,22 +69,28 @@ export function buildContext(input) {
     const sections = [];
     let task;
     try {
-        task = buildReviewTask(input.cwd, input.diff, input.router, undefined, undefined, reviewedKeys(input.stateRoot));
+        task = buildReviewTask(input.cwd, input.diff, input.router, input.lessons, undefined, reviewedKeys(input.stateRoot));
     }
     catch {
         task = undefined;
     }
-    if (task?.lessons.length)
-        sections.push(`## Lessons this team verified on earlier reviews, for the files this change touches\n${task.lessons.map(l => `- ${l.file}: ${l.text}${l.prs.length ? ` (PR ${l.prs.join(', ')})` : ''}`).join('\n')}`);
+    // 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);
+    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')}`);
     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 => {
+        const no = l.evidence.filter(e => e.kind === 'rejected').at(-1);
+        return `- this team decided against: ${l.text}${no?.author ? ` (rejected by ${no.author}${no.detail ? `: ${no.detail}` : ''})` : ''}`;
+    });
     const dismissed = input.dismissals.slice(-MAX_SETTLED).map(d => `- dismissed as not a bug${d.by ? ` by ${d.by}` : ''}: ${where(d)} [${d.class}] ${d.issue} (reason: ${d.reason})`);
     const refuted = (input.previousPanel ?? []).filter(p => p.status === 'dropped' && !!p.item.file && !input.touched.has(p.item.file)).slice(0, MAX_SETTLED)
         .map(p => `- refuted with evidence in the last round: ${where(p.item)} [${p.item.class}] ${p.item.issue} (${(p.cross ?? []).find(c => c.call === 'refute')?.evidence ?? 'evidence in the previous verdict'})`);
-    if (dismissed.length || refuted.length)
-        sections.push(`## Settled: do not raise these again unless the code now shows something new\n${[...dismissed, ...refuted].join('\n')}`);
+    if (dismissed.length || refuted.length || rejected.length)
+        sections.push(`## Settled: do not raise these again unless the code now shows something new\n${[...rejected, ...dismissed, ...refuted].join('\n')}`);
     const docs = input.docs;
     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')}`);

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

@@ -1,5 +1,8 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 import { describe, expect, it } from 'vitest';
-import { dismissedAs } from './context.js';
+import { buildContext, dismissedAs } from './context.js';
 const dismissal = { id: 'abcdef0123', file: 'src/x.ts', line: 40, class: 'correctness', issue: 'cache key built from user id may collide', reason: 'ids are unique per tenant', at: '2026-10-06' };
 const finding = (over) => ({ id: 'ffff000011', kind: 'finding', class: 'correctness', file: 'src/x.ts', line: 40, issue: 'cache key built from the user id may collide', consequence: 'two users share an entry', ...over });
 describe('a dismissal', () => {
@@ -16,3 +19,25 @@ describe('a dismissal', () => {
         expect(dismissedAs({ ...finding({}), kind: 'prior' }, [dismissal])).toBeUndefined(); // a human's point is never dismissed this way
     });
 });
+describe('what the judges are told the team knows', () => {
+    it('shows verified lessons by default, candidates too with all, none when off, each with the words it came from', () => {
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'context-'));
+        try {
+            const lesson = { file: 'src/a.ts', symbols: ['save'], createdAt: '', updatedAt: '' };
+            fs.mkdirSync(path.join(repo, '.rigour'));
+            fs.writeFileSync(path.join(repo, '.rigour', 'review-lessons.json'), JSON.stringify({ version: 1, lessons: [
+                    { ...lesson, id: 'v', text: 'Make every save idempotent on retry.', state: 'verified', evidence: [{ pr: 3, comment: 'a', author: 'p', said: 'A retry here saves twice.' }, { pr: 4, comment: 'b', author: 'p' }] },
+                    { ...lesson, id: 'c', text: 'Log the save id on failure.', state: 'candidate', evidence: [{ pr: 5, comment: 'c', author: 'p' }] },
+                ] }));
+            const diff = 'diff --git a/src/a.ts b/src/a.ts\n--- a/src/a.ts\n+++ b/src/a.ts\n@@ -0,0 +1,1 @@\n+export const save = 1;\n';
+            const told = (lessons) => buildContext({ cwd: repo, stateRoot: repo, dismissals: [], diff, router: undefined, lessons, previousPanel: undefined, touched: new Set(), docs: [], checks: [] }).text;
+            expect(told()).toContain('src/a.ts: Make every save idempotent on retry. (in their words: "A retry here saves twice.") (acted on in PR #3, #4)');
+            expect(told()).not.toContain('Log the save id');
+            expect(told('all')).toContain('Log the save id on failure.');
+            expect(told('off')).not.toContain('idempotent');
+        }
+        finally {
+            fs.rmSync(repo, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -1,7 +1,9 @@
+/** `env` adds variables to the inherited environment; `unset` removes inherited ones the command must not see. */
 export type Exec = (command: string, args: string[], options: {
     cwd: string;
     timeoutMs: number;
     env?: Record<string, string>;
+    unset?: string[];
 }) => Promise<{
     exitCode: number;
     stdout: string;
@@ -13,5 +15,12 @@ export type Progress = (message: string) => void;
 export declare const GH_TIMEOUT_MS = 60000;
 /** The named GitHub account's token for `gh`, when the person keeps several; otherwise gh's own. */
 export declare function githubEnv(cwd: string, account: string | undefined, exec: Exec): Promise<Record<string, string> | undefined>;
+/**
+ * The token to read GitHub with: an explicit one first (GH_TOKEN, GITHUB_TOKEN: CI, or a person's
+ * own choice), then the named account's (review.github_account / RIGOUR_GITHUB_ACCOUNT), and the
+ * gh CLI's active account only when no account is named, so a machine signed in to several
+ * accounts never reads as the wrong one.
+ */
+export declare function githubToken(cwd: string, account: string | undefined, exec: Exec): Promise<string>;
 /** `gh --paginate` prints one JSON array per page. */
 export declare function parseJsonArrays(text: string): any[];

package/dist/review/reviewer/exec.js

@@ -3,11 +3,20 @@ import { execa } from 'execa';
 export const defaultExec = async (command, args, options) => {
     // stdin is /dev/null, not an empty pipe: an agent CLI that reads stdin sees its end at once, and a command that exits
     // before an empty write lands (git rev-parse) cannot fail the run with EPIPE, as it did on Linux.
-    const result = await execa(command, args, { cwd: options.cwd, reject: false, timeout: options.timeoutMs, stdin: 'ignore', env: options.env ? { ...process.env, ...options.env } : undefined, maxBuffer: 64 * 1024 * 1024 });
+    const result = await execa(command, args, { cwd: options.cwd, reject: false, timeout: options.timeoutMs, stdin: 'ignore', ...childEnv(options), maxBuffer: 64 * 1024 * 1024 });
     const stderr = String(result.stderr ?? '');
     // A command that could not start, timed out or was killed writes nothing itself: say which, never an empty failure.
     return { exitCode: result.exitCode ?? 1, stdout: String(result.stdout ?? ''), stderr: stderr || (result.failed && 'shortMessage' in result ? String(result.shortMessage) : '') };
 };
+/** The environment a command runs with: the inherited one plus `env`, minus `unset` (then nothing is inherited implicitly). */
+function childEnv(options) {
+    if (!options.unset?.length)
+        return options.env ? { env: { ...process.env, ...options.env } } : {};
+    const env = { ...process.env, ...options.env };
+    for (const name of options.unset)
+        delete env[name];
+    return { env, extendEnv: false };
+}
 export const GH_TIMEOUT_MS = 60_000;
 /** The named GitHub account's token for `gh`, when the person keeps several; otherwise gh's own. */
 export async function githubEnv(cwd, account, exec) {
@@ -16,6 +25,24 @@ export async function githubEnv(cwd, account, exec) {
     const token = await exec('gh', ['auth', 'token', '--user', account], { cwd, timeoutMs: GH_TIMEOUT_MS });
     return token.exitCode === 0 && token.stdout.trim() ? { GH_TOKEN: token.stdout.trim() } : undefined;
 }
+/**
+ * The token to read GitHub with: an explicit one first (GH_TOKEN, GITHUB_TOKEN: CI, or a person's
+ * own choice), then the named account's (review.github_account / RIGOUR_GITHUB_ACCOUNT), and the
+ * gh CLI's active account only when no account is named, so a machine signed in to several
+ * accounts never reads as the wrong one.
+ */
+export async function githubToken(cwd, account, exec) {
+    const explicit = process.env.GH_TOKEN?.trim() || process.env.GITHUB_TOKEN?.trim();
+    if (explicit)
+        return explicit;
+    const named = account?.trim();
+    const read = await exec('gh', named ? ['auth', 'token', '--user', named] : ['auth', 'token'], { cwd, timeoutMs: GH_TIMEOUT_MS });
+    if (read.exitCode === 0 && read.stdout.trim())
+        return read.stdout.trim();
+    throw new Error(named
+        ? `GitHub account ${named} is named for reading, but \`gh auth token --user ${named}\` gave no token: sign in to it with \`gh auth login\`, or set GITHUB_TOKEN.`
+        : 'Set GITHUB_TOKEN or sign in with `gh auth login` (read access to the repository is enough).');
+}
 /** `gh --paginate` prints one JSON array per page. */
 export function parseJsonArrays(text) {
     try {

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

@@ -1,6 +1,6 @@
 import os from 'os';
-import { describe, expect, it } from 'vitest';
-import { defaultExec } from './exec.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defaultExec, githubToken } from './exec.js';
 describe('running a command', () => {
     it('passes the command\'s own output through', async () => {
         const result = await defaultExec(process.execPath, ['-e', 'process.stdout.write("out"); process.stderr.write("err"); process.exit(3)'], { cwd: os.tmpdir(), timeoutMs: 30_000 });
@@ -12,6 +12,21 @@ describe('running a command', () => {
         const runs = await Promise.all(Array.from({ length: 50 }, () => defaultExec(process.execPath, ['-e', 'process.stdout.write("ok")'], { cwd: os.tmpdir(), timeoutMs: 30_000 })));
         expect(runs.every(r => r.exitCode === 0 && r.stdout === 'ok')).toBe(true);
     });
+    it('keeps a variable the command must not see out of its environment, and passes the rest through', async () => {
+        process.env.RIGOUR_TEST_SECRET = 'gateway-key';
+        process.env.RIGOUR_TEST_KEPT = 'kept';
+        try {
+            const print = ['-e', 'process.stdout.write(JSON.stringify({ secret: process.env.RIGOUR_TEST_SECRET ?? null, kept: process.env.RIGOUR_TEST_KEPT ?? null, added: process.env.RIGOUR_TEST_ADDED ?? null }))'];
+            const hidden = await defaultExec(process.execPath, print, { cwd: os.tmpdir(), timeoutMs: 30_000, env: { RIGOUR_TEST_ADDED: 'added' }, unset: ['RIGOUR_TEST_SECRET'] });
+            expect(JSON.parse(hidden.stdout)).toEqual({ secret: null, kept: 'kept', added: 'added' });
+            const inherited = await defaultExec(process.execPath, print, { cwd: os.tmpdir(), timeoutMs: 30_000 });
+            expect(JSON.parse(inherited.stdout)).toEqual({ secret: 'gateway-key', kept: 'kept', added: null });
+        }
+        finally {
+            delete process.env.RIGOUR_TEST_SECRET;
+            delete process.env.RIGOUR_TEST_KEPT;
+        }
+    });
     it('says why a command that never answered failed: not started, or timed out', async () => {
         const missing = await defaultExec('rigour-no-such-command', [], { cwd: os.tmpdir(), timeoutMs: 30_000 });
         expect(missing.exitCode).not.toBe(0);
@@ -21,3 +36,24 @@ describe('running a command', () => {
         expect(slow.stderr).toMatch(/timed out/i);
     });
 });
+describe('the token GitHub is read with', () => {
+    afterEach(() => { vi.unstubAllEnvs(); });
+    const gh = (tokens, asked) => async (_command, args) => {
+        asked.push(args);
+        const user = args[args.indexOf('--user') + 1];
+        const token = args.includes('--user') ? tokens[user] : tokens.active;
+        return token ? { exitCode: 0, stdout: `${token}\n`, stderr: '' } : { exitCode: 1, stdout: '', stderr: 'no account' };
+    };
+    it('is an explicit token first, then the named account, and the active account only when none is named', async () => {
+        vi.stubEnv('GH_TOKEN', '');
+        vi.stubEnv('GITHUB_TOKEN', '');
+        const asked = [];
+        const tokens = { active: 'other-employer', work: 'work-token' };
+        expect(await githubToken(os.tmpdir(), 'work', gh(tokens, asked))).toBe('work-token');
+        expect(await githubToken(os.tmpdir(), undefined, gh(tokens, asked))).toBe('other-employer');
+        await expect(githubToken(os.tmpdir(), 'missing', gh(tokens, asked))).rejects.toThrow('GitHub account missing is named for reading');
+        expect(asked).toEqual([['auth', 'token', '--user', 'work'], ['auth', 'token'], ['auth', 'token', '--user', 'missing']]); // a named account never falls back to the active one
+        vi.stubEnv('GITHUB_TOKEN', 'ci-token');
+        expect(await githubToken(os.tmpdir(), 'work', gh(tokens, asked))).toBe('ci-token');
+    });
+});

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

@@ -17,6 +17,12 @@ export interface HumanReviews {
 }
 type Gh = (args: string[]) => ReturnType<Exec>;
 export declare function ghFor(cwd: string, exec: Exec, env: Record<string, string> | undefined): Gh;
+/**
+ * The description as it read at `at` (a backtest's review time): GitHub keeps every version in
+ * `userContentEdits`, the first being the text at creation. Undefined when it cannot be read, so a
+ * caller never falls back to today's text, which may describe code written after the review.
+ */
+export declare function bodyAsOf(gh: Gh, pr: number, at: string): Promise<string | undefined>;
 /** The pull request for the branch (or the one named, or the one the commit is on), or none, or why it could not be read. */
 export declare function findPullRequest(gh: Gh, branch: string, head: string, named: number | undefined): Promise<{
     pr?: PullRequest;

package/dist/review/reviewer/inputs.js

@@ -14,6 +14,32 @@ export function ghFor(cwd, exec, env) {
     return args => exec('gh', args, { cwd, timeoutMs: GH_TIMEOUT_MS, env });
 }
 const PR_FIELDS = 'number,state,isDraft,author,body';
+/**
+ * The description as it read at `at` (a backtest's review time): GitHub keeps every version in
+ * `userContentEdits`, the first being the text at creation. Undefined when it cannot be read, so a
+ * caller never falls back to today's text, which may describe code written after the review.
+ */
+export async function bodyAsOf(gh, pr, at) {
+    const query = 'query($owner:String!,$repo:String!,$pr:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$pr){body lastEditedAt userContentEdits(first:100){totalCount nodes{editedAt diff}}}}}';
+    const read = await gh(['api', 'graphql', '-f', `query=${query}`, '-F', 'owner={owner}', '-F', 'repo={repo}', '-F', `pr=${pr}`]);
+    if (read.exitCode !== 0)
+        return undefined;
+    try {
+        const node = JSON.parse(read.stdout)?.data?.repository?.pullRequest;
+        if (!node)
+            return undefined;
+        if (!node.lastEditedAt || node.lastEditedAt < at)
+            return String(node.body ?? '');
+        const edits = node.userContentEdits?.nodes ?? [];
+        if ((node.userContentEdits?.totalCount ?? 0) > edits.length)
+            return undefined; // older versions beyond the page: unknown
+        const before = edits.filter(e => e.editedAt < at && typeof e.diff === 'string').sort((a, b) => (a.editedAt < b.editedAt ? 1 : -1))[0];
+        return before?.diff ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The pull request for the branch (or the one named, or the one the commit is on), or none, or why it could not be read. */
 export async function findPullRequest(gh, branch, head, named) {
     if (named !== undefined)

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

@@ -0,0 +1,3 @@
+export declare function judgeUnset(name: string, judgeEnv: Record<string, {
+    unset: string[];
+}>): string[];

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

@@ -0,0 +1,10 @@
+/**
+ * What a judge's CLI must not see. A judge runs with the person's environment, because that is how
+ * an agent CLI finds its login or its API key; but a key meant for something else must not reach
+ * it. RIGOUR_API_KEY (Rigour's own model-review key) never does, and a team names any other
+ * variable per judge in review.reviewer.judge_env (e.g. OPENAI_API_KEY holding a gateway key).
+ */
+const NEVER_TO_JUDGES = ['RIGOUR_API_KEY'];
+export function judgeUnset(name, judgeEnv) {
+    return [...new Set([...NEVER_TO_JUDGES, ...(judgeEnv[name]?.unset ?? [])])];
+}

package/dist/review/reviewer/prompt.js

@@ -3,7 +3,7 @@
  * is sandboxed can still read all of it. The structure is what turned noted issues into caught
  * blocking ones on a real multi-round review: every prior point first (siblings included), then
  * what a fix made redundant, then a trace of every read, then nested scans, then merge impact,
- * then the diff as a person reads it. Blocking is decided by the kind of finding, never by how
+ * then the journey past the request, sibling parity and every claim, then the diff as a person reads it. Blocking is decided by the kind of finding, never by how
  * severe it feels.
  */
 import { createHash } from 'crypto';
@@ -36,7 +36,10 @@ Do these steps in order. Report only what you verified in the code, with file:li
    site, check the others that mount or call the same thing and list them in checked_siblings. A
    point an earlier review raised and a later review called fixed must still be fixed: look for the
    same class coming back in new code. Judge the code, not commit messages, replies or the
-   description. Give each point the severity its reviewer gave it.
+   description. Give each point the severity its reviewer gave it. For a point you say is NOT
+   resolved, give file, line and quote: the code at this commit that shows it is still open, copied
+   exactly. Rigour checks the quote; a point you cannot show still open that way is not open. Check the
+   code at THIS commit: a later commit may already have done what the point asked.
 
 2. Redundancy. A fix often leaves behind what it made unnecessary. For every hunk in the reviewed
    range that moves a condition into a query (.not, .gte, .lte, .gt, .lt, .in, .like, .eq added),
@@ -81,32 +84,85 @@ Do these steps in order. Report only what you verified in the code, with file:li
    against the new definition and the new tests. A call site that no longer holds is a
    correctness finding.
 
-6. Review the diff the way the human reviewers do: correctness, production cost, dead code and
+6. Journey. Follow what the change does to a user, a job or a record past this one request. For
+   every write the reviewed range adds or changes, record in journey:
+   - state that outlives the request (a row, a cache entry, a queued job, a sent message, a
+     stamped flag): what clears or expires it (cleared_by, null when nothing does), and whether a
+     retry of the same request (retry_safe) and two runs overlapping (overlap_safe) leave it right.
+   - every status or stage it sets: can_move_back is true when the write can move a record to an
+     earlier status, or overwrite a terminal one, with no guard in the query or before it.
+   - every event id, dedupe key or idempotency key it writes, with its inputs and
+     stable_under_edit, as in step 3.
+   A false retry_safe, overlap_safe or stable_under_edit, a true can_move_back, or a null
+   cleared_by on state that should end is a correctness finding.
+
+7. Sibling parity. For every route, runner, handler, job or page the range changes, find the
+   siblings that do the same job (the same folder, the same shape, the same caller) and say whether
+   each needs the same change and has it. One that needs it and lacks it is a correctness finding.
+
+8. Claims. Read every comment in every file the range touches and every sentence of the pull
+   request description that states what the code does ("every link goes through X", "at worst one
+   email", "runs once a day"). Report each claim the code at this commit no longer makes true,
+   with the code that contradicts it as file:line. A false claim is a stale-claim finding.
+
+9. Team lessons. For EVERY lesson listed under "Lessons this team taught" in the team knowledge
+   file, decide whether this change repeats the mistake it names or skips what it asks for, and say
+   so in lessons, with the file:line that shows it either way. A lesson is what this team's
+   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
    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, every comment and every claim
-   in the description still true of the code, and the repository's rules.
+   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:
+- 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).
+The quote is checked against the checkout: a finding whose quote is not at the line it names never
+blocks. A miss you cannot show that way stays in your notes. When a finding is that something is
+MISSING (a call, a check, a guard, a cleanup), also put the exact text that is missing in absent
+("conn.close("): Rigour searches the file for it, and a finding about something that is there
+never blocks.
+
+Give every finding a severity, by how the wrong outcome is reached. blocking: it happens on the
+feature's normal path (every run, every user of the feature, growing with the data), even when the
+feature sits behind a flag or a rollout: wrong data, a lost or duplicated write or event, a crash, a
+security hole, or a material cost. should: it needs an unusual combination of inputs or failures to
+happen, or it is brief or cosmetic, or it is a comment or description that drifted. For a scheduled
+or background job, the flag-off, kill-switch or lock-held path is a normal path: work done before
+checking it is paid on every run. A point a human reviewer already raised and called non-blocking, or approved with it
+present, is answered in prior_points and is never a blocking finding unless you show a wrong outcome
+they did not know about.
 
 Classes: correctness, production-cost, dead-code, duplication, stale-claim, helper-bypass,
 repo-rule. Every finding needs a consequence: the wrong outcome it causes (an input and what
-goes wrong) or the cost it adds (reads, calls or memory per what). A finding with no wrong outcome
-and no cost (faster, simpler or cleaner code) is an opinion: leave consequence empty and it is
-shown, never blocking. Do not report style preferences or trade-offs you would not request
-changes for.
+goes wrong) or a material cost: one that grows with the data or the traffic (an extra query or
+round trip, rows read that scale with users or time, a missing index, an unbounded window, memory
+per item). A cost that does not grow (one more column on rows already read, a second copy of a
+small check, code that could be shorter or shared) is not material. A finding with no wrong outcome
+and no material cost is an opinion: leave consequence empty and it is shown, never blocking. Do not
+report style preferences or trade-offs you would not request changes for.
 
 Your final message must be ONLY this JSON, starting with { and ending with }, nothing before or after it:
-{"prior_points":[{"point":"...","review":"<login> <submitted_at>","severity":"blocking"|"should-fix"|"non-blocking","resolved":true|false,"evidence":"file:line ...","checked_siblings":["file:line"]}],
+{"prior_points":[{"point":"...","review":"<login> <submitted_at>","severity":"blocking"|"should-fix"|"non-blocking","resolved":true|false,"evidence":"file:line ...","file":"<when not resolved>","line":0,"quote":"<when not resolved: the code that shows it still open>","checked_siblings":["file:line"]}],
  "redundant":[{"file":"...","line":0,"what":"...","made_redundant_by":"file:line","removed":true|false}],
  "reads":[{"file":"...","line":0,"read":"...","rules":[{"rule":"...","known_before_read":true|false,"applied_before_read":true|false}],"consumer":{"file":"...","line":0,"uses":"ids-only"|"rows"|"aggregate"},"narrower_source":null|"...","keys":[{"name":"...","inputs":"...","stable_under_edit":true|false}],"window_bounded":true|false|null,"keyset":true|false|null,"index":"..."}],
  "scans":[{"file":"...","line":0,"function":"...","outer":"...","inner":"...","fix":"..."}],
  "merge_impact":[{"symbol":"...","main_file":"...","call_site":"file:line","holds":true|false,"why":"..."}],
- "findings":[{"class":"...","file":"...","line":0,"issue":"...","why":"...","consequence":"<wrong outcome for an input, or the cost; empty for an opinion>"}],
+ "journey":[{"file":"...","line":0,"what":"...","cleared_by":null|"...","retry_safe":true|false|null,"overlap_safe":true|false|null,"can_move_back":true|false|null,"keys":[{"name":"...","inputs":"...","stable_under_edit":true|false}]}],
+ "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":"..."}],
+ "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"}]}`;
 }
 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-6 on that diff and on every file an open item names.
+  their diff is ${deltaDiffFile}. Do steps 1-10 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/rule-writer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The model call behind turning reviews into rules (review-learning/rules-from-reviews.ts): the
+ * team's first installed reviewer CLI, isolated and read-only exactly as a judge is, its spend
+ * counted with the reviewer's and stopped at review.reviewer.max_usd_per_day. No CLI, or the cap
+ * reached: undefined, and the points stay as the person wrote them.
+ */
+import type { Config } from '../../types/index.js';
+import type { RuleWriter } from '../../review-learning/rules-from-reviews.js';
+import type { Exec } from './exec.js';
+export declare function ruleWriterFor(cwd: string, config: Config, exec: Exec, progress?: (line: string) => void): Promise<RuleWriter | undefined>;

package/dist/review/reviewer/rule-writer.js

@@ -0,0 +1,30 @@
+import { ADAPTERS, isReviewerName, resolveAdapter } from './adapters.js';
+import { judgeUnset } from './judge-env.js';
+import { resolveReviewer } from './settings.js';
+import { VerdictStore } from './store.js';
+export async function ruleWriterFor(cwd, config, exec, progress = () => undefined) {
+    const settings = resolveReviewer(config);
+    let chosen;
+    for (const name of settings.reviewers.filter(isReviewerName)) {
+        const found = await resolveAdapter(ADAPTERS[name], cwd, exec);
+        if (found) {
+            chosen = { name, binary: found.binary };
+            break;
+        }
+    }
+    const store = await VerdictStore.open(cwd, exec);
+    if (!chosen || !store)
+        return undefined;
+    const { name, binary } = chosen;
+    const model = settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
+    return async (prompt) => {
+        if (settings.max_usd_per_day !== undefined && store.spend().usd >= settings.max_usd_per_day) {
+            progress(`rules from reviews: the daily cost cap ($${settings.max_usd_per_day}) is reached; the rest stay as people wrote them`);
+            return undefined;
+        }
+        const run = await exec(binary, ADAPTERS[name].args(prompt, model), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
+        const answer = ADAPTERS[name].answer(run.stdout);
+        store.addSpend(1, answer.costUsd);
+        return run.exitCode === 0 ? answer.text : undefined;
+    };
+}

package/dist/review/reviewer/rule-writer.test.d.ts

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