@rigour-labs/core 6.7.7 → 6.7.9

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

@@ -12,6 +12,11 @@ export interface ApiJudgeOptions {
     roots: string[];
     reasoning?: Reasoning;
     fetchImpl?: typeof fetch;
+    /** The review's input files, given inline in the first message: a model that never calls a tool still has what it needs. */
+    inputs?: Array<{
+        path: string;
+        text: string;
+    }>;
 }
 export interface ApiJudgeRun {
     exitCode: number;

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

@@ -11,6 +11,10 @@ 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;
+/** Output tokens a turn may use, reasoning included: a review verdict is long, and a reasoning model's thinking counts against the default budget. */
+const MAX_OUTPUT_TOKENS = 32_000;
+/** Characters of the inputs given inline in the first message; the rest stays in the files, for the tools. */
+const MAX_INLINE_CHARS = 240_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)/;
@@ -24,7 +28,7 @@ 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 messages = [{ role: 'system', content: SYSTEM }, { role: 'user', content: withInputs(prompt, o.inputs ?? []) }];
     const usage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
     const calls = [];
     let cost;
@@ -40,7 +44,7 @@ export async function runApiJudge(prompt, o) {
             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 } : {}) }),
+                body: JSON.stringify({ model: o.model, messages, tools: TOOLS, tool_choice: 'auto', max_tokens: MAX_OUTPUT_TOKENS, ...(o.reasoning ? { reasoning_effort: o.reasoning } : {}) }),
                 signal: controller.signal,
             });
         }
@@ -66,13 +70,22 @@ export async function runApiJudge(prompt, o) {
         usage.output += n(u.completion_tokens);
         if (typeof u.cost === 'number')
             cost = (cost ?? 0) + u.cost;
-        const message = body.choices?.[0]?.message;
+        const choice = body.choices?.[0];
+        // A gateway reports a provider's failure inside the choice, with the choice's finish_reason "error": say what it said.
+        if (choice?.error || body.error)
+            return fail(`the API reported an error: ${JSON.stringify(choice?.error ?? body.error).slice(0, 300)}`);
+        const message = choice?.message;
         if (!message)
             return fail('no choices in the answer');
-        messages.push(message);
+        // Echo back what the API needs to continue (reasoning_details carries a reasoning model's chain), not the reasoning prose.
+        messages.push({ role: 'assistant', content: message.content ?? null, ...(message.tool_calls ? { tool_calls: message.tool_calls } : {}), ...(message.reasoning_details ? { reasoning_details: message.reasoning_details } : {}) });
         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 } };
+            const text = String(message.content ?? '').trim();
+            // An empty final message is not an answer: say why (the output budget ran out, a refusal), never report it as one.
+            if (!text)
+                return fail(`an empty answer on turn ${turn} (finish_reason ${String(body.choices?.[0]?.finish_reason ?? 'unknown')}${message.refusal ? `, refusal: ${String(message.refusal).slice(0, 120)}` : ''})`);
+            const answer = { result: text, usage, ...(cost !== undefined ? { cost_usd: cost } : {}), trace: { turns: turn, usage, calls } };
             return { exitCode: 0, stdout: JSON.stringify(answer), stderr: '' };
         }
         for (const call of toolCalls) {
@@ -83,6 +96,22 @@ export async function runApiJudge(prompt, o) {
     }
     return fail(`no answer within ${o.maxTurns} turns`);
 }
+/**
+ * The prompt with the inputs it names appended inline, smallest first so the diff takes what budget is left: a judge
+ * is fed, not left to decide whether to read. What does not fit is cut with a note naming the file to read.
+ */
+function withInputs(prompt, inputs) {
+    if (inputs.length === 0)
+        return prompt;
+    const ordered = [...inputs].sort((a, b) => a.text.length - b.text.length);
+    let left = MAX_INLINE_CHARS;
+    const parts = ordered.map(input => {
+        const text = input.text.length > left ? `${input.text.slice(0, Math.max(0, left))}\n…[cut here: read ${input.path} with read_file for the rest]` : input.text;
+        left = Math.max(0, left - input.text.length);
+        return `### ${input.path}\n${text}`;
+    });
+    return `${prompt}\n\nThe inputs named above, inline (the files are also there for your tools):\n\n${parts.join('\n\n')}`;
+}
 /** 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 ?? '');

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

@@ -78,6 +78,27 @@ describe('the API judge', () => {
         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('fails closed on an empty final message, saying why, and echoes back only what the API needs to continue', async () => {
+        const empty = (async () => new Response(JSON.stringify({ choices: [{ message: { role: 'assistant', content: '', reasoning: 'thinking…' }, finish_reason: 'length' }], usage: {} }), { status: 200 }));
+        expect(await runApiJudge('p', options(empty))).toMatchObject({ exitCode: 1, stderr: expect.stringContaining('an empty answer on turn 1 (finish_reason length)') });
+        const providerError = (async () => new Response(JSON.stringify({ choices: [{ message: { role: 'assistant', content: '' }, finish_reason: 'error', error: { message: 'Provider returned error', code: 502 } }], usage: {} }), { status: 200 }));
+        expect(await runApiJudge('p', options(providerError))).toMatchObject({ exitCode: 1, stderr: expect.stringContaining('the API reported an error: {"message":"Provider returned error","code":502}') });
+        const { fetchImpl, seen } = model([{ tools: [{ name: 'list_dir', args: { path: '.' } }] }, { text: 'ok' }]);
+        await runApiJudge('p', options(fetchImpl));
+        const echoed = seen[1].messages.find((m) => m.role === 'assistant');
+        expect(Object.keys(echoed).sort()).toEqual(['content', 'role', 'tool_calls']); // no reasoning prose sent back
+        expect(seen[0].max_tokens).toBe(32000);
+    });
+    it('gives the judge its inputs inline, smallest first, the diff cut with a note when the budget runs out', async () => {
+        const { fetchImpl, seen } = model([{ text: 'ok' }]);
+        const inputs = [{ path: '/w/full.diff', text: 'x'.repeat(300_000) }, { path: '/w/pr-description.md', text: 'the description' }, { path: '/w/previous-reviews.md', text: 'the reviews' }];
+        await runApiJudge('review this', options(fetchImpl, { inputs }));
+        const first = seen[0].messages[1].content;
+        expect(first.startsWith('review this\n\nThe inputs named above, inline')).toBe(true);
+        expect(first.indexOf('### /w/previous-reviews.md')).toBeLessThan(first.indexOf('### /w/full.diff')); // smallest first
+        expect(first).toContain('…[cut here: read /w/full.diff with read_file for the rest]');
+        expect(first.length).toBeLessThan(241_000);
+    });
     it('passes the reasoning effort when asked', async () => {
         const { fetchImpl, seen } = model([{ text: 'ok' }]);
         await runApiJudge('p', options(fetchImpl, { reasoning: 'low' }));

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

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

package/dist/review/reviewer/context.js

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

package/dist/review/reviewer/verdict.js

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

package/dist/review/reviewer.js

@@ -141,7 +141,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const sincePrevious = previousIsAncestor ? new Set((await git(['diff', '--name-only', `${previous.head}..HEAD`])).split('\n').filter(Boolean)) : new Set();
     const changedFiles = [...fullDiff.matchAll(/^diff --git a\/.* b\/(.*)$/gm)].map(m => m[1]);
     const context = buildContext({
-        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, touched: sincePrevious, checks: options.checks ?? [],
+        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, ...(pr ? { pr: pr.number } : {}), touched: sincePrevious, checks: options.checks ?? [],
         previousPanel: previousIsAncestor ? store.readJson(previous.verdict)?.panel?.items : undefined,
         docs: await relatedDocs(cwd, changedFiles, exec),
     });
@@ -208,8 +208,9 @@ async function review(cwd, base, config, exec, progress, options) {
         return none(settings.required.panel || settings.required.mode ? 'unavailable' : 'skipped', over, { reviewers, scope, why, pr: pr?.number });
     const work = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-reviewer-'));
     // One judge run, by CLI or by API: the same prompt, the same cost accounting, the same trace.
+    let inlineInputs = [];
     const runJudge = (name, prompt, model) => name === 'api'
-        ? runApiJudge(prompt, { url: settings.api.url, model: settings.api.model, key: process.env[settings.api.key_env] ?? '', maxTurns: settings.api.max_turns, timeoutMs: settings.timeout_ms, cwd, roots: [cwd, work], ...(settings.reasoning[name] ? { reasoning: settings.reasoning[name] } : {}), ...(options.fetch ? { fetchImpl: options.fetch } : {}) })
+        ? runApiJudge(prompt, { url: settings.api.url, model: settings.api.model, key: process.env[settings.api.key_env] ?? '', maxTurns: settings.api.max_turns, timeoutMs: settings.timeout_ms, cwd, roots: [cwd, work], inputs: inlineInputs, ...(settings.reasoning[name] ? { reasoning: settings.reasoning[name] } : {}), ...(options.fetch ? { fetchImpl: options.fetch } : {}) })
         : exec(installed.get(name).binary, ADAPTERS[name].args(prompt, model, { reasoning: settings.reasoning[name] }), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
     try {
         const file = (name, text) => {
@@ -223,6 +224,7 @@ async function review(cwd, base, config, exec, progress, options) {
         const diffFile = file('full.diff', fullDiff);
         const contextFile = file('team-knowledge.md', context.text);
         const hintsFile = file('hints.txt', options.hints?.trim() || 'none\n');
+        inlineInputs = [[reviewsFile, reviews.markdown], [prBodyFile, body], [diffstatFile, await git(['diff', '--stat', `${baseSha}...HEAD`])], [diffFile, fullDiff], [contextFile, context.text], [hintsFile, options.hints?.trim() || 'none\n']].map(([p, text]) => ({ path: p, text }));
         let delta = '';
         // A reviewer must report on the human reviews, unless every point was settled by the previous verdict and is carried.
         let needsPriorPoints = reviews.count > 0;
@@ -258,13 +260,29 @@ async function review(cwd, base, config, exec, progress, options) {
                     return { run, answer, verdict: run.exitCode === 0 || answer.text.trim() ? parseVerdict(answer.text, needsPriorPoints, name, answer) : undefined };
                 };
                 let first = await ask();
-                // An answer that is not a verdict is a slip, not a decision: asked once more, inside the caps, before the review is unavailable.
-                if (first.verdict && 'error' in first.verdict && !overBudget(store.spend(), settings, 1)) {
-                    progress(`Rigour reviewer: ${name} gave no valid verdict; asking once more`);
+                // No verdict, whether a malformed answer or a run that died, is a slip, not a decision: asked once more, inside the caps.
+                if ((!first.verdict || 'error' in first.verdict) && !overBudget(store.spend(), settings, 1)) {
+                    progress(`Rigour reviewer: ${name} gave no ${first.verdict ? 'valid verdict' : 'answer'}; asking once more`);
                     first = await ask();
                 }
                 return first.verdict ?? { error: `${name}: no answer (exit ${first.run.exitCode}): ${first.run.stderr.trim().slice(-200)}` };
             }));
+            // A judge that gives nothing is replaced by the next one installed, so the boundary stays up: a review ends unavailable only when every judge failed.
+            const spare = candidates.filter(c => installed.has(c) && !reviewers.includes(c));
+            for (let i = 0; i < answers.length; i++) {
+                let answer = answers[i];
+                while ('error' in answer && spare.length && !overBudget(store.spend(), settings, 1)) {
+                    const next = spare.shift();
+                    progress(`Rigour reviewer: ${reviewers[i]} gave no verdict (${answer.error}); ${next} judges instead`);
+                    modeRecord = { ...modeRecord, degraded: `${modeRecord.degraded ? `${modeRecord.degraded}; ` : ''}${reviewers[i]} gave no verdict, ${next} judged instead` };
+                    reviewers[i] = next;
+                    const run = await runJudge(next, prompt, modelFor(next));
+                    const got = ADAPTERS[next].answer(run.stdout);
+                    store.addSpend(1, got.costUsd);
+                    answer = run.exitCode === 0 || got.text.trim() ? parseVerdict(got.text, needsPriorPoints, next, got) : { error: `${next}: no answer (exit ${run.exitCode}): ${run.stderr.trim().slice(-200)}` };
+                }
+                answers[i] = answer;
+            }
             const failed = answers.find(a => 'error' in a);
             if (failed && 'error' in failed)
                 return none('unavailable', failed.error, { reviewers, scope, why, pr: pr?.number });

package/dist/review/reviewer.test.js

@@ -170,7 +170,7 @@ describe('the reviewer', () => {
         expect(hidden.outcome).toBe('passed');
         const shown = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [] }), seen), () => undefined, { pr: 42, reviewsBefore: '2026-10-04', force: true });
         expect(seen.files['previous-reviews.md']).toContain('Review by senior');
-        expect(shown).toMatchObject({ outcome: 'unavailable', reason: 'claude did not report on the human reviews' });
+        expect(shown).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('did not report on the human reviews') });
     });
     it('for a backtest, gives the description as it read at the review, never a later edit', async () => {
         const versions = { lastEditedAt: '2026-10-06T00:00:00Z', body: 'today: refunds are issued by the nightly job', userContentEdits: { totalCount: 3, nodes: [
@@ -200,7 +200,7 @@ describe('the reviewer', () => {
     });
     it('never passes without a verdict: a crash, a malformed answer, an unreadable pull request or no installed reviewer', async () => {
         const crashed = await runReviewer(repo, 'main', config, fakes(() => ({ exitCode: 1, stdout: '', stderr: 'API error' }), seenNow()), () => undefined);
-        expect(crashed).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('claude: no answer (exit 1)') });
+        expect(crashed).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('cursor: no answer (exit 1)'), mode: { degraded: expect.stringContaining('claude gave no verdict, cursor judged instead') } }); // asked twice, then the spare judge, which failed too
         const prose = await runReviewer(repo, 'main', config, fakes(() => 'Looks good to me!', seenNow()), () => undefined);
         expect(prose).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no valid verdict') });
         const broken = async (command, args, options) => command === 'gh' && args[0] === 'pr' ? { exitCode: 1, stdout: '', stderr: 'HTTP 500' } : fakes(() => '', seenNow())(command, args, options);
@@ -283,16 +283,34 @@ describe('the reviewer', () => {
             delete process.env.TEST_JUDGE_KEY;
         }
     });
+    it('replaces a judge that gives nothing with the next one installed, and says so', async () => {
+        const seen = seenNow();
+        const silent = (async () => new Response(JSON.stringify({ choices: [{ message: { role: 'assistant', content: '' }, finish_reason: 'stop' }], usage: { prompt_tokens: 5, completion_tokens: 0 } }), { status: 200 }));
+        const twoJudges = ConfigSchema.parse({ version: 1, review: { reviewer: { enabled: true, reviewers: ['api', 'claude'], api: { url: 'https://example.test/v1', model: 'silent-model', key_env: 'TEST_JUDGE_KEY' } } } });
+        process.env.TEST_JUDGE_KEY = 'secret';
+        try {
+            const result = await runReviewer(repo, 'main', twoJudges, fakes(() => JSON.stringify(EMPTY), seen), () => undefined, { fetch: silent, force: true });
+            expect(result).toMatchObject({ outcome: 'passed', reviewers: ['claude'], mode: { degraded: expect.stringContaining('api gave no verdict, claude judged instead') } });
+            expect(seen.prompts).toHaveLength(1); // claude ran once, after the api judge's two empty answers
+        }
+        finally {
+            delete process.env.TEST_JUDGE_KEY;
+        }
+    });
     it('asks a judge once more after an answer that is not a verdict, and is unavailable only when the second is not one either', async () => {
         const seen = seenNow();
         let calls = 0;
         const slipOnce = await runReviewer(repo, 'main', config, fakes(() => (++calls === 1 ? '{"prior_points":[], "findings":[{"class"' : JSON.stringify(EMPTY)), seen), () => undefined, { force: true });
         expect(slipOnce.outcome).toBe('passed');
         expect(seen.prompts).toHaveLength(2);
+        let crashes = 0;
+        const crashOnce = seenNow();
+        const recovered = await runReviewer(repo, 'main', config, fakes(() => (++crashes === 1 ? { exitCode: 1, stdout: '', stderr: 'API error' } : JSON.stringify(EMPTY)), crashOnce), () => undefined, { force: true });
+        expect(recovered.outcome).toBe('passed'); // a run that died is asked once more too
         const twice = seenNow();
         const slipTwice = await runReviewer(repo, 'main', config, fakes(() => 'not json', twice), () => undefined, { force: true });
         expect(slipTwice).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no valid verdict') });
-        expect(twice.prompts).toHaveLength(2); // once more, never a loop
+        expect(twice.prompts).toHaveLength(3); // once more, then the spare judge once: never a loop
     });
     it('says what was asked and that nothing ran when a review ends early, with why a judge is missing', async () => {
         const seen = { ...seenNow(), installed: ['claude'] }; // cursor is listed but not installed
@@ -420,7 +438,7 @@ describe('verdicts', () => {
             return { verdict, ...account(verdict, undefined, verify) };
         };
         const broken = judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', evidence: 'no lock before the read' }]);
-        expect(broken.open.map(i => [i.kind, i.class, i.issue])).toEqual([['rule', 'repo-rule', 'breaks a rule this repository wrote for itself (AGENTS.md): Every job must take the lock before its first read.']]);
+        expect(broken.open.map(i => [i.kind, i.class, i.issue, i.evidence])).toEqual([['rule', 'repo-rule', 'Every job must take the lock before its first read.', 'breaks a rule this repository wrote for itself (AGENTS.md): no lock before the read']]);
         expect(judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2 }])).toMatchObject({ open: [], unverified: [expect.objectContaining({ kind: 'rule' })] }); // no quote: not shown as a block
         expect(judged([{ id: 'r2', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;' }])).toMatchObject({ open: [], advisory: [expect.objectContaining({ class: 'repo-rule' })] }); // guidance: shown, never a block
         expect(judged([{ id: 'r1', status: 'followed' }, { id: 'r1', status: 'not-applicable' }])).toMatchObject({ open: [], notes: [], advisory: [], unverified: [] });
@@ -437,9 +455,14 @@ describe('verdicts', () => {
         const { open } = account(verdict, undefined, checkoutVerifier(repo));
         expect(open.map(i => [i.kind, i.class, i.locations ?? []])).toEqual([
             ['prior', 'prior point', []], ['prior', 'prior point', []],
-            ['finding', 'production-cost', [{ file: 'a.ts', line: 1 }]], // the same point in another file: one item, both places
-            ['finding', 'correctness', []], // a different class is a different point
+            // The same point in another file, and the same point said as another class on the next line: one item, every place.
+            ['finding', 'production-cost', [{ file: 'a.ts', line: 1 }, { file: 'src/job.ts', line: 2 }]],
         ]);
+        // A rule break and the finding it caused, on the same lines and in like words, are one item.
+        const twice = account({ ...EMPTY, prior_points: [], findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'the raw table name is inlined instead of the JOBS_TABLE constant', input: 'any run', consequence: 'a rename misses it', quote: 'return 1;' }],
+            rules: [{ id: 'r', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', rule: 'Import the JOBS_TABLE constant; do not inline the raw table name again.', source: 'AGENTS.md', requirement: true }] }, undefined, checkoutVerifier(repo));
+        expect(twice.open.map(i => i.class)).toEqual(['repo-rule']);
+        expect(twice.open[0].locations).toEqual([{ file: 'src/job.ts', line: 2 }]);
     });
     it('keeps reads, scans, redundancy and merge impact as notes with stable ids, and answers non-blocking points in the reply', () => {
         const verdict = {

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

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

package/dist/review-learning/lessons.js

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

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

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

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

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

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

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

package/dist/review-learning/team-lessons.js

@@ -13,14 +13,14 @@ export function activeLessons(cwd, mode = DEFAULT_LESSON_MODE) {
         return [];
     return readLessons(cwd).filter(l => mode === 'all' || l.state === 'verified');
 }
-/** `standards`: how many team standards may come with the file lessons (a judge reading a whole pull request takes more than an agent's one question). */
-export function lessonsForDiff(cwd, diff, mode = DEFAULT_LESSON_MODE, standards) {
+/** `standards`, `limit`, `perFile`: how many team standards and file lessons may come, and how many per file (a judge reading a whole pull request takes more than an agent's one question). */
+export function lessonsForDiff(cwd, diff, mode = DEFAULT_LESSON_MODE, standards, limit, perFile, excludePr) {
     if (mode === 'off')
         return [];
     const lessons = readLessons(cwd);
     if (lessons.length === 0)
         return [];
-    return matchLessons(lessons, changeShape(diff), { includeCandidates: mode === 'all', ...(standards !== undefined ? { standards } : {}) });
+    return matchLessons(lessons, changeShape(diff), { includeCandidates: mode === 'all', ...(standards !== undefined ? { standards } : {}), ...(limit !== undefined ? { limit } : {}), ...(perFile !== undefined ? { perFile } : {}), ...(excludePr !== undefined ? { excludePr } : {}) });
 }
 /** The points this team rejected that a change touches: what the judges are told is settled. */
 export function rejectedForDiff(cwd, diff) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.7.7",
+  "version": "6.7.9",
   "description": "Rigour's review engine: deterministic gates on changed lines, rules and lessons learned from your team's fixes, and per-check precision from what you fix versus dismiss, across TypeScript, JavaScript, Python, Go, Ruby and C#.",
   "engines": {
     "node": ">=22.13"
@@ -72,11 +72,11 @@
     "@anthropic-ai/sdk": "^0.30.1",
     "pg": "^8.16.3",
     "openai": "^5.23.2",
-    "@rigour-labs/brain-darwin-arm64": "6.7.7",
-    "@rigour-labs/brain-darwin-x64": "6.7.7",
-    "@rigour-labs/brain-linux-arm64": "6.7.7",
-    "@rigour-labs/brain-win-x64": "6.7.7",
-    "@rigour-labs/brain-linux-x64": "6.7.7"
+    "@rigour-labs/brain-darwin-arm64": "6.7.9",
+    "@rigour-labs/brain-linux-arm64": "6.7.9",
+    "@rigour-labs/brain-linux-x64": "6.7.9",
+    "@rigour-labs/brain-darwin-x64": "6.7.9",
+    "@rigour-labs/brain-win-x64": "6.7.9"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",