@rigour-labs/core 6.7.9 → 6.8.0

package/dist/brief/briefing.d.ts

@@ -0,0 +1,59 @@
+import { type LessonMode } from '../review-learning/team-lessons.js';
+/** The most items a briefing gives: past about ten, a briefing is a wall nobody reads. */
+export declare const BRIEFING_MAX_ITEMS = 10;
+/** The most items a briefing for one file gives, the first time an agent edits it: a word in passing, not a wall. */
+export declare const FILE_BRIEFING_MAX_ITEMS = 3;
+export interface BriefingItem {
+    kind: 'rule' | 'lesson' | 'settled';
+    /** What to do, in the team's words (a rule's text, a lesson's rule). */
+    text: string;
+    /** Where it came from: the rules file, or the pull requests the lesson was learned and proven on. */
+    cite: string;
+    /** A rule the team worded as a requirement: a break blocks at review. */
+    requirement?: boolean;
+    id: string;
+}
+export interface Briefing {
+    task?: string;
+    goal: string;
+    files: string[];
+    items: BriefingItem[];
+}
+export interface BriefingInput {
+    /** What the task is for: the agent's first prompt, a ticket's summary, the pull request's title. The branch name when absent. */
+    goal?: string;
+    /** The files the task will touch, when known; otherwise the branch's own changes and the files the goal names. */
+    files?: string[];
+    lessons?: LessonMode;
+    limit?: number;
+}
+/**
+ * The briefing for a task in this checkout: requirement rules first (a break of one blocks later), then the team's
+ * verified lessons, then the points the team settled against, then guidance rules; `limit` items at most.
+ */
+export declare function buildBriefing(cwd: string, input?: BriefingInput): Briefing;
+/** The briefing as an agent reads it: short, numbered, each item with where it came from. Empty when there is nothing to say. */
+export declare function briefingText(briefing: Briefing): string;
+/**
+ * The briefing for one file, the first time an agent edits it: the requirement rules that name it (or its folder), the
+ * lessons the team learned on it, and the points the team settled against on it; at most three. At session start the
+ * task's files are often unknown; the first edit of a file is when they are, and when a briefing can be specific.
+ */
+export declare function buildFileBriefing(cwd: string, file: string, input?: {
+    lessons?: LessonMode;
+    limit?: number;
+}): Briefing;
+/** A file's briefing as an agent reads it, just before it edits that file. Empty when there is nothing to say. */
+export declare function fileBriefingText(briefing: Briefing): string;
+/** Builds a file's briefing and records it on the task's thread, with the file. */
+export declare function briefFile(cwd: string, file: string, input?: {
+    lessons?: LessonMode;
+    limit?: number;
+    session?: string;
+    agent?: string;
+}): Briefing;
+/** Builds the briefing and records it on the task's thread (what was briefed, by id, so a later review can be read against it). */
+export declare function briefTask(cwd: string, input: BriefingInput & {
+    session?: string;
+    agent?: string;
+}): Briefing;

package/dist/brief/briefing.js

@@ -0,0 +1,126 @@
+/**
+ * The briefing: before an agent writes, what a senior on this team would tell it about the task. The repository's own
+ * rules and the team's verified lessons for the files the task will likely touch, and the points the team settled
+ * against (so the agent does not re-raise or re-do them), at most `limit` items, each cited to where it came from.
+ *
+ * Nothing here is new knowledge: the same rules and lessons the reviewer checks a change against, selected by the same
+ * matchers, before the code exists instead of after. It is deterministic (no model call), local, and it never blocks.
+ */
+import { spawnSync } from 'child_process';
+import { rulesForDiff } from '../review-learning/repo-rules.js';
+import { describeLesson, lessonsForDiff, lessonView, rejectedForDiff } from '../review-learning/team-lessons.js';
+import { appendTaskEvent, taskOf } from '../task/thread.js';
+/** The most items a briefing gives: past about ten, a briefing is a wall nobody reads. */
+export const BRIEFING_MAX_ITEMS = 10;
+/** The most items a briefing for one file gives, the first time an agent edits it: a word in passing, not a wall. */
+export const FILE_BRIEFING_MAX_ITEMS = 3;
+/** The most files a briefing reads the task's likely reach from. */
+const LIKELY_FILES = 20;
+/**
+ * The briefing for a task in this checkout: requirement rules first (a break of one blocks later), then the team's
+ * verified lessons, then the points the team settled against, then guidance rules; `limit` items at most.
+ */
+export function buildBriefing(cwd, input = {}) {
+    const task = taskOf(cwd);
+    const goal = (input.goal?.trim() || (task ? task.branch.replace(/[/_-]+/g, ' ') : '')).slice(0, 2000);
+    const files = (input.files?.length ? input.files : likelyFiles(cwd, goal)).slice(0, LIKELY_FILES);
+    const limit = Math.max(0, Math.min(input.limit ?? BRIEFING_MAX_ITEMS, BRIEFING_MAX_ITEMS));
+    // The rule and lesson matchers read a change: the task's files and the goal's words stand in for the code to come.
+    const shape = shapeOf(files, goal);
+    // Only rules that name a path or identifier of the task: the reviewer can judge a rule against code; a briefing cannot.
+    const rules = rulesForDiff(cwd, shape, true, limit, true);
+    const lessons = lessonsForDiff(cwd, shape, input.lessons ?? 'verified', 5, limit, 3).filter(l => l.state === 'verified' || input.lessons === 'all');
+    const settled = rejectedForDiff(cwd, shape);
+    const cited = (prs) => (prs.length ? `learned in PR ${prs.map(p => `#${p}`).join(', ')}` : 'the team\'s decision');
+    const items = [
+        ...rules.filter(r => r.requirement).map(r => ({ kind: 'rule', text: r.text, cite: ruleCite(r.source, r.scope), requirement: true, id: `rule:${r.id}` })),
+        ...lessons.map(l => {
+            const view = lessonView(l);
+            return { kind: 'lesson', text: describeLesson({ ...view, prs: [] }), cite: cited(view.prs), id: `lesson:${l.id}` };
+        }),
+        ...settled.map(l => ({ kind: 'settled', text: `settled against, do not do or raise it: ${lessonView(l).text}`, cite: cited(lessonView(l).prs), id: `settled:${l.id}` })),
+        ...rules.filter(r => !r.requirement).map(r => ({ kind: 'rule', text: r.text, cite: ruleCite(r.source, r.scope), id: `rule:${r.id}` })),
+    ];
+    return { ...(task ? { task: task.key } : {}), goal, files, items: items.slice(0, limit) };
+}
+/** The briefing as an agent reads it: short, numbered, each item with where it came from. Empty when there is nothing to say. */
+export function briefingText(briefing) {
+    if (briefing.items.length === 0)
+        return '';
+    const lines = briefing.items.map((item, i) => `${i + 1}. ${item.requirement ? '[must] ' : item.kind === 'settled' ? '[settled] ' : ''}${item.text} (${item.cite})`);
+    return [`Rigour briefing${briefing.task ? ` for ${briefing.task}` : ''}: how this team builds the code this task will likely touch. Follow these; a [must] broken in your change blocks at review.`, ...lines].join('\n');
+}
+/**
+ * The briefing for one file, the first time an agent edits it: the requirement rules that name it (or its folder), the
+ * lessons the team learned on it, and the points the team settled against on it; at most three. At session start the
+ * task's files are often unknown; the first edit of a file is when they are, and when a briefing can be specific.
+ */
+export function buildFileBriefing(cwd, file, input = {}) {
+    const task = taskOf(cwd);
+    const limit = Math.max(0, Math.min(input.limit ?? FILE_BRIEFING_MAX_ITEMS, FILE_BRIEFING_MAX_ITEMS));
+    const shape = shapeOf([file], '');
+    const mode = input.lessons ?? 'verified';
+    const rules = rulesForDiff(cwd, shape, true, BRIEFING_MAX_ITEMS, true).filter(r => r.requirement);
+    const lessons = lessonsForDiff(cwd, shape, mode, 0, BRIEFING_MAX_ITEMS, BRIEFING_MAX_ITEMS).filter(l => l.file === file && (l.state === 'verified' || mode === 'all'));
+    const settled = rejectedForDiff(cwd, shape).filter(l => l.file === file);
+    const cited = (prs) => (prs.length ? `learned in PR ${prs.map(p => `#${p}`).join(', ')}` : 'the team\'s decision');
+    const items = [
+        ...rules.map(r => ({ kind: 'rule', text: r.text, cite: ruleCite(r.source, r.scope), requirement: true, id: `rule:${r.id}` })),
+        ...lessons.map(l => ({ kind: 'lesson', text: lessonView(l).text, cite: cited(lessonView(l).prs), id: `lesson:${l.id}` })),
+        ...settled.map(l => ({ kind: 'settled', text: `settled against, do not do or raise it: ${lessonView(l).text}`, cite: cited(lessonView(l).prs), id: `settled:${l.id}` })),
+    ];
+    return { ...(task ? { task: task.key } : {}), goal: '', files: [file], items: items.slice(0, limit) };
+}
+/** A file's briefing as an agent reads it, just before it edits that file. Empty when there is nothing to say. */
+export function fileBriefingText(briefing) {
+    if (briefing.items.length === 0)
+        return '';
+    const lines = briefing.items.map((item, i) => `${i + 1}. ${item.requirement ? '[must] ' : item.kind === 'settled' ? '[settled] ' : ''}${item.text} (${item.cite})`);
+    return [`Rigour, before you edit ${briefing.files[0]}: what this team asks of this file.`, ...lines].join('\n');
+}
+/** Builds a file's briefing and records it on the task's thread, with the file. */
+export function briefFile(cwd, file, input = {}) {
+    const briefing = buildFileBriefing(cwd, file, input);
+    appendTaskEvent(cwd, { kind: 'brief', file, ...(input.session ? { session: input.session } : {}), ...(input.agent ? { agent: input.agent } : {}), items: briefing.items.length, ids: briefing.items.map(i => i.id), files: [file] });
+    return briefing;
+}
+/** Builds the briefing and records it on the task's thread (what was briefed, by id, so a later review can be read against it). */
+export function briefTask(cwd, input) {
+    const briefing = buildBriefing(cwd, input);
+    appendTaskEvent(cwd, { kind: 'brief', ...(input.session ? { session: input.session } : {}), ...(input.agent ? { agent: input.agent } : {}), items: briefing.items.length, ids: briefing.items.map(i => i.id), files: briefing.files });
+    return briefing;
+}
+function ruleCite(source, scope) {
+    return scope ? `${source}, for ${scope}` : source;
+}
+/** A stand-in change for the matchers: each file as touched, the goal's words as the added line. */
+function shapeOf(files, goal) {
+    const words = goal.replace(/\s+/g, ' ');
+    const touched = files.length ? files : ['.'];
+    return touched.map(f => `diff --git a/${f} b/${f}\n--- a/${f}\n+++ b/${f}\n@@ -0,0 +1,1 @@\n+${words}\n`).join('');
+}
+/** The files a task will likely touch: what the branch already changed, then tracked files whose path names a word of the goal. */
+function likelyFiles(cwd, goal) {
+    const files = [];
+    const main = ['origin/main', 'main', 'origin/master', 'master'].find(ref => git(cwd, ['rev-parse', '--verify', '-q', ref]) !== undefined);
+    const base = main ? git(cwd, ['merge-base', 'HEAD', main]) : undefined;
+    if (base)
+        files.push(...(git(cwd, ['diff', '--name-only', `${base}...HEAD`]) ?? '').split('\n').filter(Boolean));
+    const words = [...new Set(goal.toLowerCase().match(/[a-z][a-z0-9]{3,}/g) ?? [])].filter(w => !STOP.has(w));
+    if (words.length) {
+        const tracked = (git(cwd, ['ls-files']) ?? '').split('\n').filter(Boolean);
+        for (const file of tracked) {
+            if (files.length >= LIKELY_FILES)
+                break;
+            const name = file.toLowerCase();
+            if (!files.includes(file) && words.some(w => name.includes(w)))
+                files.push(file);
+        }
+    }
+    return files;
+}
+const STOP = new Set(['this', 'that', 'with', 'from', 'into', 'when', 'then', 'than', 'have', 'make', 'should', 'would', 'could', 'please', 'there', 'their', 'what', 'which', 'about', 'feat', 'test', 'tests', 'code', 'file', 'files', 'change', 'update']);
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 5000, maxBuffer: 16 * 1024 * 1024 });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}

package/dist/brief/briefing.test.d.ts

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

package/dist/brief/briefing.test.js

@@ -0,0 +1,107 @@
+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 { writeLessons } from '../review-learning/lessons.js';
+import { readThread } from '../task/thread.js';
+import { BRIEFING_MAX_ITEMS, briefFile, briefingText, briefTask, buildBriefing, buildFileBriefing, fileBriefingText } from './briefing.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const write = (file, text) => {
+    fs.mkdirSync(path.dirname(path.join(repo, file)), { recursive: true });
+    fs.writeFileSync(path.join(repo, file), text);
+};
+const lesson = (id, state, file, text, symbols, pr) => ({
+    id, text, file, symbols, state, evidence: [{ kind: 'outcome', pr, comment: 'c', author: 'senior', source: 'person' }],
+});
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'brief-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('AGENTS.md', [
+        '- Every job in `src/jobs/` must take `withLock()` before its first read; a job that reads first double-sends.',
+        '',
+        'Prefer `fetchWithTimeout()` over a bare call in `src/jobs/` when talking to partner APIs; a hung request blocks the queue.',
+        '',
+    ].join('\n'));
+    write('services/billing/AGENTS.md', '- Every amount in `services/billing/` must be integer cents via `toCents()`; never a float.\n');
+    write('src/jobs/retry.ts', 'export async function retryJob() {}\n');
+    write('services/billing/charge.ts', 'export const charge = 1;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+    writeLessons(repo, [
+        lesson('v1', 'verified', 'src/jobs/retry.ts', 'Bound the retry window at both ends: `updated_at` between since and until.', ['retryJob'], 12),
+        lesson('c1', 'candidate', 'src/jobs/retry.ts', 'Log every retry at debug level in `retryJob`.', ['retryJob'], 13),
+        lesson('r1', 'rejected', 'src/jobs/retry.ts', 'Wrap `retryJob` in a second try/catch.', ['retryJob'], 14),
+    ]);
+});
+afterEach(() => fs.rmSync(repo, { recursive: true, force: true }));
+describe('the briefing', () => {
+    it("gives the files' requirement rules first, then verified lessons, settled points, then guidance, each cited; never a candidate", () => {
+        const briefing = buildBriefing(repo, { goal: 'retry the partner job with backoff', files: ['src/jobs/retry.ts'] });
+        expect(briefing.items.map(i => [i.kind, i.requirement ?? false, i.cite])).toEqual([
+            ['rule', true, 'AGENTS.md'],
+            ['lesson', false, 'learned in PR #12'],
+            ['settled', false, 'learned in PR #14'],
+            ['rule', false, 'AGENTS.md'],
+        ]);
+        expect(briefing.items[1].text).toContain('Bound the retry window at both ends');
+        expect(briefing.items.some(i => i.text.includes('debug level'))).toBe(false); // a candidate is not the team's yet
+        // A team whose reviewer is shown candidates (review_lessons: all) is briefed with them too.
+        expect(buildBriefing(repo, { goal: 'retry the partner job with backoff', files: ['src/jobs/retry.ts'], lessons: 'all' }).items.some(i => i.text.includes('debug level'))).toBe(true);
+        expect(briefing.items.some(i => i.text.includes('integer cents'))).toBe(false); // billing's rule, not this task's folder
+        // A rule that only shares words with the task, naming none of its paths or identifiers, is not briefed.
+        write('AGENTS.md', fs.readFileSync(path.join(repo, 'AGENTS.md'), 'utf8') + '\nEvery partner retry job must log its backoff and the partner it retried for, always.\n');
+        expect(buildBriefing(repo, { goal: 'retry the partner job with backoff', files: ['src/jobs/retry.ts'] }).items.some(i => i.text.includes('log its backoff'))).toBe(false);
+        const text = briefingText(briefing);
+        expect(text.split('\n')[1]).toMatch(/^1\. \[must\] Every job in `src\/jobs\/` must take `withLock\(\)`.* \(AGENTS\.md\)$/);
+        expect(text).toContain('[settled] settled against, do not do or raise it: Wrap `retryJob` in a second try/catch. (learned in PR #14)');
+    });
+    it("serves a folder's own rules to a task in that folder, cited with the folder", () => {
+        const briefing = buildBriefing(repo, { goal: 'charge in cents', files: ['services/billing/charge.ts'] });
+        expect(briefing.items.map(i => i.cite)).toContain('services/billing/AGENTS.md, for services/billing/');
+    });
+    it('never gives more than ten items, and says nothing when nothing applies', () => {
+        write('AGENTS.md', Array.from({ length: 30 }, (_, i) => `- Every job in \`src/jobs/\` must call \`step${i}()\` before \`retryJob\` reads.\n`).join('\n'));
+        expect(buildBriefing(repo, { goal: 'retry job', files: ['src/jobs/retry.ts'], limit: 50 }).items).toHaveLength(BRIEFING_MAX_ITEMS);
+        expect(buildBriefing(repo, { goal: 'retry job', files: ['src/jobs/retry.ts'], limit: 3 }).items).toHaveLength(3);
+        const nothing = buildBriefing(repo, { goal: 'update the readme wording', files: ['README.md'] });
+        expect(nothing.items).toEqual([]);
+        expect(briefingText(nothing)).toBe('');
+    });
+    it("reads the task's likely files from the branch's own changes and the goal's words, and the goal from the branch when none is given", () => {
+        git('checkout', '-qb', 'feat/retry-backoff');
+        write('src/jobs/retry.ts', 'export async function retryJob() { return 1; }\n');
+        git('commit', '-qam', 'work');
+        const briefing = buildBriefing(repo);
+        expect(briefing.goal).toBe('feat retry backoff');
+        expect(briefing.files).toEqual(['src/jobs/retry.ts']);
+        expect(buildBriefing(repo, { goal: 'charge the customer' }).files).toEqual(['src/jobs/retry.ts', 'services/billing/charge.ts']);
+    });
+    it("records what was briefed on the task's thread, by id", () => {
+        git('checkout', '-qb', 'feat/retry');
+        const briefing = briefTask(repo, { goal: 'retry', files: ['src/jobs/retry.ts'], session: 's1', agent: 'claude' });
+        const [event] = readThread(repo).events;
+        expect(event).toMatchObject({ kind: 'brief', session: 's1', agent: 'claude', items: briefing.items.length, ids: briefing.items.map(i => i.id), files: ['src/jobs/retry.ts'] });
+    });
+});
+describe("a file's briefing, on the agent's first edit of it", () => {
+    it("gives at most three items: the file's requirement rules, its lessons and settled points; never guidance or another file's", () => {
+        const briefing = buildFileBriefing(repo, 'src/jobs/retry.ts');
+        expect(briefing.items.map(i => [i.kind, i.cite])).toEqual([['rule', 'AGENTS.md'], ['lesson', 'learned in PR #12'], ['settled', 'learned in PR #14']]);
+        expect(briefing.items.some(i => i.text.includes('fetchWithTimeout'))).toBe(false); // guidance waits for review
+        expect(fileBriefingText(briefing).split('\n')[0]).toBe('Rigour, before you edit src/jobs/retry.ts: what this team asks of this file.');
+        expect(buildFileBriefing(repo, 'services/billing/charge.ts').items.map(i => i.cite)).toEqual(['services/billing/AGENTS.md, for services/billing/']);
+        expect(buildFileBriefing(repo, 'README.md').items).toEqual([]);
+        expect(fileBriefingText(buildFileBriefing(repo, 'README.md'))).toBe('');
+        expect(buildFileBriefing(repo, 'src/jobs/retry.ts', { lessons: 'all' }).items.length).toBe(3); // still three, with candidates in play
+    });
+    it('records the file it briefed on the thread', () => {
+        git('checkout', '-qb', 'feat/retry');
+        briefFile(repo, 'src/jobs/retry.ts', { session: 's9', agent: 'claude' });
+        expect(readThread(repo).events[0]).toMatchObject({ kind: 'brief', file: 'src/jobs/retry.ts', session: 's9', items: 3, files: ['src/jobs/retry.ts'] });
+    });
+});

package/dist/index.d.ts

@@ -119,3 +119,5 @@ export type { SemanticFinding } from './semantic/types.js';
 export type { ModelUsage } from './storage/index.js';
 export type { CheckpointMetric } from './storage/index.js';
 export type { CursorUsageSyncOptions } from './services/cursor-usage-client.js';
+export { appendTaskEvent, readThread, taskOf, threadText, threadsDir, THREADS_DIR, type TaskEvent, type TaskEventKind, type ThreadEvent } from './task/thread.js';
+export { briefFile, briefingText, briefTask, buildBriefing, buildFileBriefing, fileBriefingText, BRIEFING_MAX_ITEMS, FILE_BRIEFING_MAX_ITEMS, type Briefing, type BriefingInput, type BriefingItem } from './brief/briefing.js';

package/dist/index.js

@@ -101,3 +101,5 @@ export { learnFromFix, learnFromFileChange } from './semantic/learn/learn.js';
 export { extractFixTrees } from './semantic/learn/git-trees.js';
 export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';
+export { appendTaskEvent, readThread, taskOf, threadText, threadsDir, THREADS_DIR } from './task/thread.js';
+export { briefFile, briefingText, briefTask, buildBriefing, buildFileBriefing, fileBriefingText, BRIEFING_MAX_ITEMS, FILE_BRIEFING_MAX_ITEMS } from './brief/briefing.js';

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

@@ -11,11 +11,14 @@ export interface PrRounds {
 export declare function roundsForPr(cwd: string, pr: number, config: Config, exec?: Exec, options?: {
     approvedHead?: boolean;
 }): Promise<PrRounds>;
-/** The last `n` merged pull requests, newest merge first. */
-export declare function mergedPrs(cwd: string, n: number, config: Config, exec?: Exec): Promise<Array<{
-    number: number;
-    mergedAt: string;
-}>>;
+/** The last `n` merged pull requests, newest merge first; `incomplete` when the listing could not prove it has them all. */
+export declare function mergedPrs(cwd: string, n: number, config: Config, exec?: Exec): Promise<{
+    prs: Array<{
+        number: number;
+        mergedAt: string;
+    }>;
+    incomplete: boolean;
+}>;
 export declare function scaffoldLedger(cwd: string, pr: number, config: Config, exec?: Exec): Promise<{
     file: string;
     rounds: LedgerRound[];

package/dist/review/backtest-init.js

@@ -40,23 +40,41 @@ export async function roundsForPr(cwd, pr, config, exec = defaultExec, options =
     }
     const approval = options.approvedHead ? byPerson.find((r) => r.state === 'APPROVED' && r.commit_id) : undefined;
     const approved = approval
-        ? { id: `pr${pr}-approved`, commit: String(approval.commit_id), base: await baseAt(cwd, String(approval.commit_id), approval.submitted_at, mainRef, exec), reviewed_at: String(approval.submitted_at), pr, points: [], must_not_flag: [] }
+        ? { id: `pr${pr}-approved`, commit: String(approval.commit_id), base: await baseAt(cwd, String(approval.commit_id), approval.submitted_at, mainRef, exec), reviewed_at: String(approval.submitted_at), approved: true, pr, points: [], must_not_flag: [] }
         : undefined;
     if (rounds.length === 0 && !approved)
         throw new Error(`pull request ${pr} has no review by a person yet`);
     return { rounds, ...(approved ? { approved } : {}) };
 }
-/** The last `n` merged pull requests, newest merge first. */
+/** How many merged pull requests to list per one wanted, first: gh applies its limit before any sort of ours. */
+const MERGED_OVERFETCH = 4;
+/** The most merged pull requests listed per one wanted before Rigour stops and says the list may be incomplete. */
+const MERGED_OVERFETCH_MAX = 32;
+/** The last `n` merged pull requests, newest merge first; `incomplete` when the listing could not prove it has them all. */
 export async function mergedPrs(cwd, n, config, exec = defaultExec) {
     const env = await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec);
-    const list = await exec('gh', ['pr', 'list', '--state', 'merged', '--limit', String(n), '--json', 'number,mergedAt'], { cwd, timeoutMs: GH_TIMEOUT_MS, env });
-    if (list.exitCode !== 0)
-        throw new Error(`could not list merged pull requests: ${list.stderr.trim() || 'is gh signed in?'}`);
-    try {
-        return JSON.parse(list.stdout).sort((a, b) => (a.mergedAt < b.mergedAt ? 1 : -1)).slice(0, n);
-    }
-    catch {
-        throw new Error('could not read the list of merged pull requests');
+    // Listed by last update and sorted by merge date here. A merged pull request is updated at or after its merge, so once the
+    // oldest update listed is no later than the Nth merge kept, nothing unlisted can be among the last N (its merge is no later
+    // than its update, which is no later than that). Until then the listing doubles: bots that touch old pull requests after
+    // merge (backports, labels, stale comments) can crowd a window.
+    for (let limit = n * MERGED_OVERFETCH;; limit *= 2) {
+        const list = await exec('gh', ['pr', 'list', '--state', 'merged', '--limit', String(limit), '--search', 'sort:updated-desc', '--json', 'number,mergedAt,updatedAt'], { cwd, timeoutMs: GH_TIMEOUT_MS, env });
+        if (list.exitCode !== 0)
+            throw new Error(`could not list merged pull requests: ${list.stderr.trim() || 'is gh signed in?'}`);
+        let listed;
+        try {
+            listed = JSON.parse(list.stdout);
+        }
+        catch {
+            throw new Error('could not read the list of merged pull requests');
+        }
+        const prs = [...listed].sort((a, b) => (a.mergedAt < b.mergedAt ? 1 : -1)).slice(0, n).map(({ number, mergedAt }) => ({ number, mergedAt }));
+        const oldestUpdate = listed.reduce((min, p) => (p.updatedAt < min ? p.updatedAt : min), listed[0]?.updatedAt ?? '');
+        const complete = listed.length < limit || (prs.length === n && oldestUpdate <= prs[n - 1].mergedAt);
+        if (complete)
+            return { prs, incomplete: false };
+        if (limit >= n * MERGED_OVERFETCH_MAX)
+            return { prs, incomplete: true };
     }
 }
 /** Lines either side of an inline comment that a finding for the same point may land on. */

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

@@ -5,7 +5,7 @@ import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ConfigSchema } from '../types/index.js';
 import { ledgerProblems, loadLedger, LEDGER_PATH, LedgerSchema } from './backtest.js';
-import { scaffoldLedger } from './backtest-init.js';
+import { mergedPrs, scaffoldLedger } from './backtest-init.js';
 let repo;
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
 const config = ConfigSchema.parse({ version: 1 });
@@ -96,3 +96,41 @@ describe('rigour backtest init', () => {
         expect(written.rounds.map(r => [r.id, r.commit])).toEqual([['pr7-r1', 'other00'], ['pr212-r1', 'c2c2c2c2c2']]);
     });
 });
+describe('the last N merged pull requests', () => {
+    const run = async (pages) => {
+        const limits = [];
+        const exec = async (command, args, options) => {
+            if (command === 'gh' && args[0] === 'auth')
+                return { exitCode: 0, stdout: 'token\n', stderr: '' };
+            if (command === 'gh' && args[0] === 'pr') {
+                expect(args).toEqual(expect.arrayContaining(['--search', 'sort:updated-desc', '--json', 'number,mergedAt,updatedAt']));
+                const limit = Number(args[args.indexOf('--limit') + 1]);
+                limits.push(limit);
+                return { exitCode: 0, stdout: JSON.stringify(pages(limit).slice(0, limit)), stderr: '' };
+            }
+            return fakeExec([])(command, args, options);
+        };
+        return { ...(await mergedPrs(repo, 2, config, exec)), limits };
+    };
+    const pr = (number, mergedAt, updatedAt = mergedAt) => ({ number, mergedAt: `2026-04-${mergedAt}T00:00:00Z`, updatedAt: `2026-04-${updatedAt}T00:00:00Z` });
+    it('keeps the N most recently merged: a long-lived pull request merged last is in, one merged first is out', async () => {
+        const { prs, incomplete, limits } = await run(() => [pr(3, '12'), pr(6, '10'), pr(5, '05'), pr(7, '01')]);
+        expect(prs.map(p => p.number)).toEqual([3, 6]);
+        expect(incomplete).toBe(false);
+        expect(limits).toEqual([8]); // fewer listed than asked for: that is everything
+    });
+    it('lists more when old pull requests touched after merge crowd the window, until the result is provably complete', async () => {
+        // Eight old pull requests a bot touched on the 20th, then the two real latest merges.
+        const all = [...Array.from({ length: 8 }, (_, i) => pr(100 + i, '02', '20')), pr(3, '12'), pr(6, '10'), pr(5, '05')];
+        const { prs, incomplete, limits } = await run(() => all);
+        expect(limits).toEqual([8, 16]); // the first page held only crowding bots' touches: its oldest update (the 20th) is after the merges kept
+        expect(prs.map(p => p.number)).toEqual([3, 6]);
+        expect(incomplete).toBe(false);
+    });
+    it('stops at the cap and says the result may be incomplete', async () => {
+        const crowd = Array.from({ length: 200 }, (_, i) => pr(1000 + i, '01', '28'));
+        const { incomplete, limits } = await run(() => crowd);
+        expect(limits).toEqual([8, 16, 32, 64]);
+        expect(incomplete).toBe(true);
+    });
+});

package/dist/review/backtest-last.js

@@ -17,7 +17,9 @@ const GIT_TIMEOUT_MS = 5 * 60_000;
 export async function backtestLast(cwd, config, options) {
     const exec = options.exec ?? defaultExec;
     const progress = options.progress ?? (() => undefined);
-    const prs = await mergedPrs(cwd, options.last, config, exec);
+    const { prs, incomplete } = await mergedPrs(cwd, options.last, config, exec);
+    if (incomplete)
+        progress(`backtest: warning: the listing could not prove these are the last ${options.last} merged pull requests (many old pull requests were updated after merge); the result may miss recent ones`);
     const rounds = [];
     const skipped = [];
     for (const pr of prs) {

package/dist/review/backtest.d.ts

@@ -55,6 +55,8 @@ declare const Round: z.ZodObject<{
     base: z.ZodString;
     /** When the human review was posted: the reviewer sees nothing from then on. */
     reviewed_at: z.ZodOptional<z.ZodString>;
+    /** The head a person approved: `reviewed_at` is the approval, and the reviewer sees it (it closes the points before it). */
+    approved: z.ZodOptional<z.ZodBoolean>;
     pr: z.ZodOptional<z.ZodNumber>;
     points: z.ZodArray<z.ZodObject<{
         /** A regular expression over the finding's file path. */
@@ -123,6 +125,7 @@ declare const Round: z.ZodObject<{
     }[];
     pr?: number | undefined;
     reviewed_at?: string | undefined;
+    approved?: boolean | undefined;
 }, {
     id: string;
     commit: string;
@@ -137,6 +140,7 @@ declare const Round: z.ZodObject<{
     }[];
     pr?: number | undefined;
     reviewed_at?: string | undefined;
+    approved?: boolean | undefined;
     must_not_flag?: {
         file: string;
         text?: string | undefined;
@@ -151,6 +155,8 @@ export declare const LedgerSchema: z.ZodObject<{
         base: z.ZodString;
         /** When the human review was posted: the reviewer sees nothing from then on. */
         reviewed_at: z.ZodOptional<z.ZodString>;
+        /** The head a person approved: `reviewed_at` is the approval, and the reviewer sees it (it closes the points before it). */
+        approved: z.ZodOptional<z.ZodBoolean>;
         pr: z.ZodOptional<z.ZodNumber>;
         points: z.ZodArray<z.ZodObject<{
             /** A regular expression over the finding's file path. */
@@ -219,6 +225,7 @@ export declare const LedgerSchema: z.ZodObject<{
         }[];
         pr?: number | undefined;
         reviewed_at?: string | undefined;
+        approved?: boolean | undefined;
     }, {
         id: string;
         commit: string;
@@ -233,6 +240,7 @@ export declare const LedgerSchema: z.ZodObject<{
         }[];
         pr?: number | undefined;
         reviewed_at?: string | undefined;
+        approved?: boolean | undefined;
         must_not_flag?: {
             file: string;
             text?: string | undefined;
@@ -261,6 +269,7 @@ export declare const LedgerSchema: z.ZodObject<{
         }[];
         pr?: number | undefined;
         reviewed_at?: string | undefined;
+        approved?: boolean | undefined;
     }[];
 }, {
     rounds: {
@@ -277,6 +286,7 @@ export declare const LedgerSchema: z.ZodObject<{
         }[];
         pr?: number | undefined;
         reviewed_at?: string | undefined;
+        approved?: boolean | undefined;
         must_not_flag?: {
             file: string;
             text?: string | undefined;

package/dist/review/backtest.js

@@ -35,6 +35,8 @@ const Round = z.object({
     base: z.string().min(1),
     /** When the human review was posted: the reviewer sees nothing from then on. */
     reviewed_at: z.string().optional(),
+    /** The head a person approved: `reviewed_at` is the approval, and the reviewer sees it (it closes the points before it). */
+    approved: z.boolean().optional(),
     pr: z.number().int().positive().optional(),
     points: z.array(Point),
     must_not_flag: z.array(Match).default([]),
@@ -91,7 +93,7 @@ export async function runBacktest(cwd, config, ledger, options = {}) {
         const started = Date.now();
         const worktree = await worktreeFor(cwd, round.commit, exec);
         const head = (await exec('git', ['rev-parse', 'HEAD'], { cwd: worktree, timeoutMs: GIT_TIMEOUT_MS })).stdout.trim();
-        progress(`backtest ${round.id}: ${head.slice(0, 9)} against ${round.base}${round.reviewed_at ? `, reviews hidden from ${round.reviewed_at}` : ''}`);
+        progress(`backtest ${round.id}: ${head.slice(0, 9)} against ${round.base}${round.reviewed_at ? `, reviews hidden from ${reviewsHiddenFrom(round)}` : ''}`);
         const stale = await staleBase(worktree, head, round.base, exec);
         if (stale)
             progress(`backtest ${round.id}: warning: ${stale}`);
@@ -192,7 +194,7 @@ async function collectItems(worktree, round, config, reviewer, exec, progress) {
     ];
     if (!reviewer)
         return { items };
-    const result = await runReviewer(worktree, round.base, config, exec, progress, { pr: round.pr, reviewsBefore: round.reviewed_at, blind: round.pr === undefined, trigger: 'backtest', force: true, ...reviewerInputs(review) });
+    const result = await runReviewer(worktree, round.base, config, exec, progress, { pr: round.pr, reviewsBefore: reviewsHiddenFrom(round), blind: round.pr === undefined, trigger: 'backtest', force: true, ...reviewerInputs(review) });
     if (result.outcome === 'unavailable' || result.outcome === 'skipped')
         return { items, reviewerError: result.reason ?? result.outcome };
     // The reviewer behind each catch is part of the score, so the gate is `reviewer:<name>`.
@@ -237,3 +239,10 @@ function byGate(result) {
             counts.set(p.by.split(' ')[0], (counts.get(p.by.split(' ')[0]) ?? 0) + 1);
     return counts.size ? `; caught by ${[...counts].map(([gate, n]) => `${gate} ${n}`).join(', ')}` : '';
 }
+/** The moment the reviewer sees nothing from: the review itself for a round, and just after the approval for an approved head. */
+function reviewsHiddenFrom(round) {
+    if (!round.reviewed_at || !round.approved)
+        return round.reviewed_at;
+    const at = Date.parse(round.reviewed_at);
+    return Number.isNaN(at) ? round.reviewed_at : new Date(at + 1000).toISOString();
+}

package/dist/review/backtest.test.js

@@ -92,6 +92,18 @@ describe('rigour backtest on a repository', () => {
         catch { /* the repository may be gone */ }
         fs.rmSync(repo, { recursive: true, force: true });
     });
+    it('hides the review itself for a round, and shows the approval for an approved head', async () => {
+        const commit = git('rev-parse', 'HEAD');
+        const base = git('rev-parse', 'main');
+        const lines = [];
+        const ledger = { rounds: [
+                { id: 'r1', commit, base, reviewed_at: '2026-09-28T15:12:53Z', points: [], must_not_flag: [] },
+                { id: 'pr1-approved', commit, base, reviewed_at: '2026-09-28T15:12:53Z', approved: true, points: [], must_not_flag: [] },
+                { id: 'odd', commit, base, reviewed_at: 'not a date', approved: true, points: [], must_not_flag: [] },
+            ] };
+        await runBacktest(repo, ConfigSchema.parse({ version: 1 }), ledger, { progress: line => lines.push(line), collect: async () => ({ items: [] }) });
+        expect(lines.filter(l => l.includes('reviews hidden from')).map(l => l.replace(/^.*reviews hidden from /, ''))).toEqual(['2026-09-28T15:12:53Z', '2026-09-28T15:12:54.000Z', 'not a date']);
+    }, 60_000);
     it('reviews the reviewed commit in a worktree with the review hidden, scores it, and leaves the checkout alone', async () => {
         const reviewed = git('rev-parse', 'HEAD');
         const base = git('rev-parse', 'main');

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

@@ -13,6 +13,10 @@ export interface Adapter {
     answer(stdout: string): {
         text: string;
     } & Spend;
+    /** Variables the judge runs with, on top of what it inherits: what keeps a person's own instructions out of it. */
+    env?: Record<string, string>;
+    /** What this judge still reads from outside the repository on this machine (a person's own config), or undefined: said on the record, never hidden. */
+    outsideRepo?(home: string, version: string | undefined): string | undefined;
 }
 /** What a run used: dollars when the CLI reports them (Claude Code), tokens otherwise (Codex reports only tokens). */
 export interface Spend {