@rigour-labs/core 6.7.5 → 6.7.7

package/dist/review/reviewer/settings.js

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

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

@@ -37,6 +37,8 @@ export declare class VerdictStore {
     /** Adds runs and reported dollars to today's log: an append, so the background reviewer and a person's run never lose each other's count. */
     addSpend(runs: number, usd: number | undefined, day?: string): void;
     private spendFile;
+    /** The record of the review (record.ts), beside its verdict. */
+    recordPath(verdictPath: string): string;
     /** The decision a verdict led to (what blocks, what is disputed or a note), kept so the same commit is not decided again. */
     decidedPath(verdictPath: string): string;
     /** A review on the branch that ended without a verdict, and why: what the status shows instead of "no verdict yet". */

package/dist/review/reviewer/store.js

@@ -77,6 +77,10 @@ export class VerdictStore {
     spendFile(day) {
         return path.join(this.dir, 'spend', `${day}.jsonl`);
     }
+    /** The record of the review (record.ts), beside its verdict. */
+    recordPath(verdictPath) {
+        return verdictPath.replace(/\.json$/, '.record.json');
+    }
     /** The decision a verdict led to (what blocks, what is disputed or a note), kept so the same commit is not decided again. */
     decidedPath(verdictPath) {
         return verdictPath.replace(/\.json$/, '.decided.json');

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

@@ -3,7 +3,7 @@ import { reviewerUsage } from './usage.js';
 const item = { id: 'abcdef0123', kind: 'finding', class: 'correctness', file: 'src/secret-path.ts', line: 2, issue: 'private text' };
 describe('reviewer usage telemetry', () => {
     it('reports counts and buckets only: never file names, finding text or ids', () => {
-        const result = { outcome: 'findings', items: [item], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [item, item], dropped: [], dismissed: [], reviewers: ['claude', 'codex', 'cursor'], scope: 'delta', cached: false, costUsd: 0.7, runs: 5,
+        const result = { outcome: 'findings', items: [item], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [item, item], dropped: [], dismissed: [], reviewers: ['claude', 'codex', 'cursor'], scope: 'delta', cached: false, costUsd: 0.7, runs: 5,
             mode: { asked: 'panel', ran: 'panel', source: 'team', escalation: '2 risky changed function(s)' } };
         const usage = reviewerUsage(result, 'push');
         expect(usage).toEqual({ outcome: 'findings', trigger: 'push', scope: 'delta', asked: 'panel', ran: 'panel', source: 'team', degraded: false, escalation: 'all-judges', refused: 0, judges: 3, cached: false, confirmed: 1, disputed: 2, dropped: 0, notes: 0, dismissed: 0, runs: 5, cost_bucket: '$0.50-2' });

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

@@ -94,6 +94,29 @@ interface LessonCheck {
     evidence?: string;
     reviewer?: string;
 }
+/** A rule Rigour served to the judge from the repository's own rules files, by id. */
+export interface ServedRule {
+    id: string;
+    source: string;
+    text: string;
+    requirement: boolean;
+}
+/**
+ * The judge's answer for one served rule: followed, broken (with the code that breaks it) or not applicable.
+ * `rule`, `source` and `requirement` are filled in by Rigour from what it served, never taken from the judge.
+ */
+export interface RuleCheck {
+    id: string;
+    status: 'followed' | 'broken' | 'not-applicable';
+    file?: string;
+    line?: number;
+    quote?: string;
+    evidence?: string;
+    reviewer?: string;
+    rule?: string;
+    source?: string;
+    requirement?: boolean;
+}
 export interface Finding {
     class: string;
     file: string;
@@ -118,6 +141,7 @@ export interface Verdict {
     siblings?: Sibling[];
     claims?: Claim[];
     lessons?: LessonCheck[];
+    rules?: RuleCheck[];
     findings: Finding[];
     carried: string[];
     resolved_previous: Array<{
@@ -143,7 +167,7 @@ export interface Verdict {
 }
 export interface OpenItem {
     id: string;
-    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'journey' | 'sibling' | 'claim' | 'lesson' | 'finding';
+    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'journey' | 'sibling' | 'claim' | 'lesson' | 'rule' | 'finding';
     class: string;
     file?: string;
     line?: number;
@@ -157,6 +181,11 @@ export interface OpenItem {
     reviewer?: string;
     /** In delta mode, how the item reached this verdict. */
     status?: 'carried' | 'not accounted for';
+    /** The same point made elsewhere: one item per root cause, every place it was found. */
+    locations?: Array<{
+        file: string;
+        line?: number;
+    }>;
 }
 /** Checks a file (and a line, and a quote of the code there) against the checkout; an item that fails cannot block. */
 export type Verify = (file: string, line: number | undefined, quote?: string) => boolean;
@@ -196,8 +225,12 @@ export interface Accounting {
     answerInReply: PriorPoint[];
     /** Findings with no wrong outcome and no cost (an opinion): shown, never a block, however many judges agree. */
     notes: OpenItem[];
+    /** Should-fixes the judge could show (a verified quote): worth a person's time, never a block. */
+    advisory: OpenItem[];
 }
 /** Everything the reviewers reported blocks; in delta mode, previous open items carry unless resolved with evidence. */
 export declare function account(verdict: Verdict, previousOpen: OpenItem[] | undefined, verify: Verify): Accounting;
 export declare function itemLine(item: OpenItem): string;
+/** The rules Rigour served, onto the judge's answers by id: an answer naming no served rule is dropped. */
+export declare function attachServedRules(verdict: Verdict, served: ServedRule[]): void;
 export {};

package/dist/review/reviewer/verdict.js

@@ -49,7 +49,7 @@ const ACCEPTED_SIMILARITY = 0.4;
 /** The reviewer's working steps: shown so a person can follow the reasoning, never a block on their own. */
 const WORKING_NOTES = new Set(['redundant', 'read', 'scan', 'merge', 'journey', 'sibling', 'claim', 'lesson']);
 const SHAPE = ['prior_points', 'reads', 'findings'];
-const LISTS = ['redundant', 'scans', 'merge_impact', 'journey', 'siblings', 'claims', 'lessons', 'carried', 'resolved_previous'];
+const LISTS = ['redundant', 'scans', 'merge_impact', 'journey', 'siblings', 'claims', 'lessons', 'rules', 'carried', 'resolved_previous'];
 /** The verdict in a reviewer's answer, or why it is not one. `needsPriorPoints`: a human review exists and none of its points is carried. */
 export function parseVerdict(text, needsPriorPoints, reviewer, spend) {
     const parsed = verdictIn(text);
@@ -106,6 +106,7 @@ export function mergeVerdicts(parts) {
         siblings: tagged(part => part.siblings ?? []),
         claims: tagged(part => part.claims ?? []),
         lessons: tagged(part => part.lessons ?? []),
+        rules: tagged(part => part.rules ?? []),
         findings: tagged(part => part.findings),
         carried: parts.flatMap(part => part.carried),
         resolved_previous: parts.length === 1 ? parts[0].resolved_previous : parts[0].resolved_previous.filter(x => parts.every(part => part.resolved_previous.some(y => y.id === x.id))),
@@ -138,8 +139,16 @@ export function account(verdict, previousOpen, verify) {
     const open = [];
     const unverified = [];
     const notes = [];
+    const advisory = [];
     const seen = new Set();
     const accepted = verdict.prior_points.filter(p => p.severity === 'non-blocking');
+    // A should-fix is shown only when the judge could show it: a quote Rigour finds. One that cannot be checked is not a claim worth a person's time.
+    const advise = (item) => {
+        if (seen.has(item.id))
+            return;
+        seen.add(item.id);
+        (!!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote) ? advisory : unverified).push(item);
+    };
     // A prior point is the human's and needs no file. A finding blocks only when the code it quotes is at the line it
     // names: any model's claim is checked, never trusted. What the working steps turned up is a note: the reasoning,
     // shown, and a block only when the judge also makes it a finding it can quote.
@@ -210,6 +219,17 @@ export function account(verdict, previousOpen, verify) {
             continue;
         add({ id: id('team-lesson', l.file, l.lesson), kind: 'lesson', class: 'team-lesson', file: l.file, line: l.line, issue: `repeats a team lesson: ${l.lesson}`, evidence: l.evidence, reviewer: l.reviewer });
     }
+    // A rule the repository wrote for itself, broken: a requirement blocks where the judge quotes the code that
+    // breaks it (checked like any quote); guidance broken is shown. The rule's words and weight are Rigour's, not the judge's.
+    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 };
+        if (r.requirement)
+            add(item);
+        else
+            advise(item);
+    }
     const stillOpen = new Set((previousOpen ?? []).map(item => item.id));
     for (const f of verdict.findings) {
         const item = { id: id(f.class, f.file, f.issue), kind: 'finding', class: f.class, file: f.file, line: f.line, issue: f.issue, evidence: f.why, ...(f.consequence?.trim() ? { consequence: f.consequence.trim() } : {}), ...(f.input?.trim() ? { input: f.input.trim() } : {}), ...(f.quote?.trim() ? { quote: f.quote } : {}), reviewer: f.reviewer };
@@ -225,10 +245,14 @@ export function account(verdict, previousOpen, verify) {
                 unverified.push(item);
             seen.add(item.id);
         }
-        else if (!opinion && !should)
+        else if (opinion) {
+            if (!notes.some(n => n.id === item.id))
+                notes.push(item);
+        }
+        else if (should)
+            advise(item);
+        else
             add(item);
-        else if (!notes.some(n => n.id === item.id))
-            notes.push(item);
     }
     const resolved = [];
     if (previousOpen) {
@@ -248,11 +272,39 @@ export function account(verdict, previousOpen, verify) {
             }
         }
     }
-    return { open, unverified, resolved, answerInReply, notes };
+    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. */
+const SAME_POINT = 0.6;
+/**
+ * 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.
+ */
+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);
+        if (!same) {
+            kept.push(item);
+            continue;
+        }
+        if (item.file)
+            (same.locations ??= []).push({ file: item.file, ...(item.line ? { line: item.line } : {}) });
+    }
+    return kept;
 }
 export function itemLine(item) {
     const where = item.file ? ` ${item.file}${item.line ? `:${item.line}` : ''}` : '';
     const by = item.reviewer ? ` (${item.reviewer})` : '';
     const status = item.status ? `, ${item.status}` : '';
-    return `[${item.class}${status}]${by}${where} ${item.issue}${item.input ? `\n      input: ${item.input}` : ''}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.quote ? `\n      code: ${item.quote.trim().split('\n')[0].slice(0, 160)}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
+    const also = item.locations?.length ? `\n      also at ${item.locations.map(l => `${l.file}${l.line ? `:${l.line}` : ''}`).join(', ')}` : '';
+    return `[${item.class}${status}]${by}${where} ${item.issue}${also}${item.input ? `\n      input: ${item.input}` : ''}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.quote ? `\n      code: ${item.quote.trim().split('\n')[0].slice(0, 160)}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
+}
+/** The rules Rigour served, onto the judge's answers by id: an answer naming no served rule is dropped. */
+export function attachServedRules(verdict, served) {
+    const byId = new Map(served.map(r => [r.id, r]));
+    verdict.rules = (verdict.rules ?? []).flatMap(r => {
+        const rule = byId.get(String(r.id));
+        return rule ? [{ ...r, id: rule.id, rule: rule.text, source: rule.source, requirement: rule.requirement }] : [];
+    });
 }

package/dist/review/reviewer.d.ts

@@ -3,11 +3,14 @@ import { type ReviewerName, type Tokens } from './reviewer/adapters.js';
 import { type Exec, type Progress } from './reviewer/exec.js';
 import { type PanelItem } from './reviewer/panel.js';
 import { type RunChoice, type Source } from './reviewer/settings.js';
+import { type ReviewRecord } from './reviewer/record.js';
 import { type Accounting, type OpenItem, type PriorPoint } from './reviewer/verdict.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays, type Exec, type Progress } from './reviewer/exec.js';
 export { itemLine, type OpenItem } from './reviewer/verdict.js';
 export type ReviewerOutcome = 'passed' | 'findings' | 'unavailable' | 'skipped';
 export interface ReviewerOptions {
+    /** For tests: what the API judge calls instead of fetch. */
+    fetch?: typeof fetch;
     /** The pull request to read when the checkout is detached (a backtest). */
     pr?: number;
     /** ISO time: a review or comment posted from then on is not shown to the reviewer (a backtest). */
@@ -43,6 +46,8 @@ export interface ReviewerResult {
     answerInReply: PriorPoint[];
     /** Findings with no wrong outcome and no cost: shown, never a block. */
     notes: OpenItem[];
+    /** Should-fixes with a verified quote: shown, capped, never a block. */
+    advisory: OpenItem[];
     /** Panel findings without a majority: shown, never a block, not carried to the next round. */
     disputed: OpenItem[];
     /** Panel findings refuted with evidence: logged, never a block. */
@@ -57,6 +62,16 @@ export interface ReviewerResult {
     scope?: 'full' | 'delta';
     why?: string;
     costUsd?: number;
+    /** The repository's own rules the judge answered, and how. */
+    rules?: {
+        checked: number;
+        followed: number;
+        broken: number;
+        notApplicable: number;
+    };
+    /** The record of this review (record.ts) and where it is kept, beside the verdict. */
+    record?: ReviewRecord;
+    recordPath?: string;
     /** Tokens every run reported, summed: the only measure of a CLI that reports no dollars (Codex). */
     tokens?: Tokens;
     /** Whether the team lets people dismiss these findings (review.reviewer.dismissals). */

package/dist/review/reviewer.js

@@ -21,7 +21,8 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { ADAPTERS, isReviewerName, resolveAdapter, selectReviewers, vendorsOf } from './reviewer/adapters.js';
+import { runApiJudge } from './reviewer/api-judge.js';
+import { ADAPTERS, apiVendor, isReviewerName, resolveAdapter, selectReviewers, vendorsOf } from './reviewer/adapters.js';
 import { defaultExec, GH_TIMEOUT_MS, githubEnv } from './reviewer/exec.js';
 import { bodyAsOf, findPullRequest, ghFor, humanReviews, linesChanged, mergesBaseIn, rulesText, sha } from './reviewer/inputs.js';
 import { mergeImpact } from './reviewer/merge-impact.js';
@@ -32,7 +33,8 @@ import { VerdictStore } from './reviewer/store.js';
 import { trackUsage } from '../telemetry/telemetry.js';
 import { reviewerUsage } from './reviewer/usage.js';
 import { buildContext, dismissedAs, readReviewDismissals, relatedDocs } from './reviewer/context.js';
-import { account, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { buildRecord } from './reviewer/record.js';
+import { account, attachServedRules, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 import { judgeUnset } from './reviewer/judge-env.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays } from './reviewer/exec.js';
 export { itemLine } from './reviewer/verdict.js';
@@ -64,7 +66,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const none = (outcome, reason, extra = {}) => {
         if (attempts && branch !== 'HEAD')
             attempts.recordAttempt(branch, { head, outcome, reason, at: new Date().toISOString() });
-        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra, mode: { ...modeRecord, ...extra.mode, ran: 'none' } };
+        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra, mode: { ...modeRecord, ...extra.mode, ran: 'none' } };
     };
     if (!head || !baseSha)
         return none('unavailable', `not a repository, or ${base} is unknown`);
@@ -75,13 +77,20 @@ async function review(cwd, base, config, exec, progress, options) {
     const candidates = settings.reviewers.filter(isReviewerName);
     const installed = new Map();
     for (const name of candidates) {
+        if (name === 'api') {
+            // The API judge is installed when the team configured it and the key it names is set.
+            if (settings.api && process.env[settings.api.key_env])
+                installed.set('api', { binary: 'api', version: settings.api.model });
+            continue;
+        }
         const found = await resolveAdapter(ADAPTERS[name], cwd, exec);
         if (found)
             installed.set(name, found);
     }
+    const vendorOf = (name) => (name === 'api' ? apiVendor(settings.api) : ADAPTERS[name].vendor);
     const authors = vendorsOf(await git(['log', '--format=%(trailers:key=Co-Authored-By,valueonly)%(trailers:key=Co-authored-by,valueonly)', `${baseSha}..HEAD`]));
     const mode = settings.mode;
-    let reviewers = selectReviewers(candidates, mode, authors, new Set(installed.keys()), settings.judges);
+    let reviewers = selectReviewers(candidates, mode, authors, new Set(installed.keys()), settings.judges, vendorOf);
     if (reviewers.length === 0)
         return none('unavailable', `no reviewer installed: ${candidates.map(n => ADAPTERS[n].binary).join(', ') || 'review.reviewer.reviewers is empty'}`);
     modeRecord = modeRan(settings, reviewers, candidates, installed);
@@ -119,8 +128,12 @@ async function review(cwd, base, config, exec, progress, options) {
     if (!options.force && previous?.head === head && previous.inputsKey === inputsKey && fs.existsSync(store.decidedPath(previous.verdict))) {
         const verdict = store.readJson(previous.verdict);
         const decided = store.readJson(store.decidedPath(previous.verdict));
-        if (verdict && decided)
-            return result(redismiss(decided, dismissals), verdict, verdict.inputs?.reviewers ?? reviewers, previous.mode, 'same commit and inputs as the last verdict', true, reviews, pr, verdict.inputs?.mode ?? modeRecord, settings.dismissals);
+        if (verdict && decided) {
+            // The record written with that verdict; a verdict from before records has none.
+            const recordPath = store.recordPath(previous.verdict);
+            const record = store.readJson(recordPath);
+            return { ...result(redismiss(decided, dismissals), verdict, verdict.inputs?.reviewers ?? reviewers, previous.mode, 'same commit and inputs as the last verdict', true, reviews, pr, verdict.inputs?.mode ?? modeRecord, settings.dismissals), ...(record ? { record, recordPath } : {}) };
+        }
     }
     // What the team already knows, for every judge; built once, and its risk count decides escalation.
     const fullDiff = (await exec('git', ['diff', `${baseSha}...HEAD`], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout;
@@ -174,15 +187,30 @@ async function review(cwd, base, config, exec, progress, options) {
     const openFile = store.openPath(verdictFile);
     const previousOpen = scope === 'delta' ? store.readJson(store.openPath(previous.verdict)) ?? [] : undefined;
     const verify = checkoutVerifier(cwd);
+    const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
+    // The record of the review, written beside the verdict once and rebuilt from the same verdict on a cached read.
+    const withRecord = (accounted, verdict, cached) => {
+        const res = result(accounted, verdict, reviewers, scope, why, cached, reviews, pr, modeRecord, settings.dismissals);
+        const judges = (verdict.reviewers ?? []).map(r => ({ reviewer: r.reviewer, ...(installed.get(r.reviewer)?.version ? { version: installed.get(r.reviewer).version } : {}), ...(modelFor(r.reviewer) ? { model: modelFor(r.reviewer) } : {}), ...(typeof r.cost_usd === 'number' ? { cost_usd: r.cost_usd } : {}), ...(r.trace?.turns ? { turns: r.trace.turns } : {}) }));
+        const recordPath = store.recordPath(verdictFile);
+        const record = (cached && store.readJson(recordPath)) || buildRecord({ head, base: baseSha, scope, verdict, accounted, judges, lessonsServed: context.lessons, humanReviews: reviews.count });
+        if (!cached || !fs.existsSync(recordPath))
+            store.writeJson(recordPath, record);
+        return { ...res, record, recordPath };
+    };
     if (!options.force && fs.existsSync(verdictFile) && fs.existsSync(openFile)) {
         const verdict = store.readJson(verdictFile);
-        return result(decide(verdict, previousOpen, verify, dismissals), verdict, reviewers, scope, why, true, reviews, pr, modeRecord, settings.dismissals);
+        return withRecord(decide(verdict, previousOpen, verify, dismissals), verdict, true);
     }
     // The daily caps, before any judge starts: a cached or reused verdict above cost nothing and never reaches here.
     const over = overBudget(store.spend(), settings, reviewers.length);
     if (over)
         return none(settings.required.panel || settings.required.mode ? 'unavailable' : 'skipped', over, { reviewers, scope, why, pr: pr?.number });
     const work = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-reviewer-'));
+    // One judge run, by CLI or by API: the same prompt, the same cost accounting, the same trace.
+    const runJudge = (name, prompt, model) => name === 'api'
+        ? runApiJudge(prompt, { url: settings.api.url, model: settings.api.model, key: process.env[settings.api.key_env] ?? '', maxTurns: settings.api.max_turns, timeoutMs: settings.timeout_ms, cwd, roots: [cwd, work], ...(settings.reasoning[name] ? { reasoning: settings.reasoning[name] } : {}), ...(options.fetch ? { fetchImpl: options.fetch } : {}) })
+        : exec(installed.get(name).binary, ADAPTERS[name].args(prompt, model, { reasoning: settings.reasoning[name] }), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
     try {
         const file = (name, text) => {
             const target = path.join(work, name);
@@ -216,7 +244,6 @@ async function review(cwd, base, config, exec, progress, options) {
         }
         const prompt = renderPrompt({ repoRoot, branch, head: head.slice(0, 9), base, baseSha, mode: scope, reviewsFile, humanCount: reviews.count, prBodyFile, diffstatFile, diffFile, hintsFile, contextFile, deltaBlock: delta, mergeBlock: merge });
         progress(`Rigour reviewer: reviewing ${head.slice(0, 9)} against ${base} (${scope}: ${why}; ${reviews.count} human review(s), written by ${[...authors].join(', ') || 'a person'}) with ${reviewers.join(', ')}`);
-        const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
         const started = Date.now();
         const ticker = setInterval(() => progress(`Rigour reviewer: still working (${Math.round((Date.now() - started) / 60_000)} min)`), PROGRESS_EVERY_MS);
         let parts;
@@ -224,7 +251,7 @@ async function review(cwd, base, config, exec, progress, options) {
             const answers = await Promise.all(reviewers.map(async (name) => {
                 const adapter = ADAPTERS[name];
                 const ask = async () => {
-                    const run = await exec(installed.get(name).binary, adapter.args(prompt, modelFor(name)), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
+                    const run = await runJudge(name, prompt, modelFor(name));
                     progress(`Rigour reviewer: ${name} finished in ${Math.round((Date.now() - started) / 1000)}s (exit ${run.exitCode})`);
                     const answer = adapter.answer(run.stdout);
                     store.addSpend(1, answer.costUsd); // every run counts against the caps, an answer or not
@@ -242,9 +269,11 @@ async function review(cwd, base, config, exec, progress, options) {
             if (failed && 'error' in failed)
                 return none('unavailable', failed.error, { reviewers, scope, why, pr: pr?.number });
             parts = answers.map(a => a.verdict);
-            for (const part of parts)
+            for (const part of parts) {
                 if (part.trace)
                     labelReads(part.trace, work, changedFiles);
+                attachServedRules(part, context.rules);
+            }
         }
         finally {
             clearInterval(ticker);
@@ -276,7 +305,7 @@ async function review(cwd, base, config, exec, progress, options) {
                 },
                 ask: async (judge, asked) => {
                     const name = judge;
-                    const run = await exec(installed.get(name).binary, ADAPTERS[name].args(crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name)), { cwd, timeoutMs: settings.timeout_ms, unset: judgeUnset(name, settings.judge_env) });
+                    const run = await runJudge(name, crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name));
                     const answer = ADAPTERS[name].answer(run.stdout);
                     store.addSpend(1, answer.costUsd);
                     reserved--;
@@ -293,7 +322,7 @@ async function review(cwd, base, config, exec, progress, options) {
         store.writeJson(store.decidedPath(verdictFile), accounted);
         if (branch !== 'HEAD')
             store.recordBranch(branch, { head, verdict: verdictFile, mode: scope, rulesHash, reviewsKey: reviews.key, inputsKey });
-        return result(accounted, verdict, reviewers, scope, why, false, reviews, pr, modeRecord, settings.dismissals);
+        return withRecord(accounted, verdict, false);
     }
     finally {
         fs.rmSync(work, { recursive: true, force: true });
@@ -397,6 +426,7 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         resolved: accounted.resolved,
         answerInReply: accounted.answerInReply,
         notes: accounted.notes,
+        advisory: accounted.advisory,
         disputed: accounted.disputed,
         dropped: accounted.dropped,
         dismissed: accounted.dismissed,
@@ -407,6 +437,7 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         ...(cost.length ? { costUsd: cost.reduce((a, b) => a + b, 0) } : {}),
         ...(used.length ? { tokens: used.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output }), { input: 0, output: 0 }) } : {}),
         runs: (verdict.reviewers ?? []).length,
+        ...(verdict.rules?.length ? { rules: { checked: verdict.rules.length, followed: verdict.rules.filter(r => r.status === 'followed').length, broken: verdict.rules.filter(r => r.status === 'broken').length, notApplicable: verdict.rules.filter(r => r.status === 'not-applicable').length } } : {}),
         mode,
         dismissable,
         cached,

package/dist/review/reviewer.test.js

@@ -8,7 +8,8 @@ import { reviewerBlocks, runReviewer } from './reviewer.js';
 import { dismissReviewerFinding } from './reviewer/context.js';
 import { reviewStatus } from './reviewer/background.js';
 import { selectReviewers, vendorsOf } from './reviewer/adapters.js';
-import { account, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { account, attachServedRules, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { recordIntact } from './reviewer/record.js';
 let repo;
 const config = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'] } } });
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
@@ -231,6 +232,57 @@ describe('the reviewer', () => {
         expect(verdict.reviewers[0].trace).toMatchObject({ turns: 5, usage: { input: 5, cacheRead: 500, cacheWrite: 50, output: 25 } });
         expect(verdict.reviewers[0].trace.calls.map((c) => c.category)).toEqual(['rigour-input', 'changed-file', 'other-file', 'git', 'search']);
     });
+    it('serves the repository\'s own rules to the judge with ids, and blocks on a requirement the judge shows broken', async () => {
+        fs.writeFileSync(path.join(repo, 'AGENTS.md'), '# Rules\n\n- `src/job.ts` must take the lock before its first read.\n- Prefer early returns.\n');
+        const seen = seenNow();
+        const answer = () => {
+            const id = /- \[([0-9a-f]{10})\] \(AGENTS\.md, requirement\)/.exec(seen.files['team-knowledge.md'] ?? '')?.[1];
+            return JSON.stringify({ ...EMPTY, rules: [{ id, status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', evidence: 'reads before any lock' }] });
+        };
+        const result = await runReviewer(repo, 'main', config, fakes(answer, seen), () => undefined, { force: true });
+        expect(seen.files['team-knowledge.md']).toContain('(AGENTS.md, requirement) `src/job.ts` must take the lock before its first read.');
+        expect(result.items.map(i => [i.class, i.file, i.line])).toEqual([['repo-rule', 'src/job.ts', 2]]);
+        expect(result.rules).toEqual({ checked: 1, followed: 0, broken: 1, notApplicable: 0 });
+    });
+    it('writes the record of the review beside the verdict, intact, and returns the same record on a cached read', async () => {
+        const seen = seenNow();
+        const answer = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', input: 'two runs', consequence: 'two emails', quote: 'return 1;', severity: 'blocking' }] });
+        const first = await runReviewer(repo, 'main', config, fakes(() => answer, seen), () => undefined);
+        expect(first.record).toMatchObject({ scope: 'full', verified: { blocking: [expect.objectContaining({ issue: 'returns before the lock' })], should_fix: [] }, reported: { human_reviews: 1 }, judges: [expect.objectContaining({ reviewer: 'claude', cost_usd: 1.5 })] });
+        expect(first.recordPath).toMatch(/\.record\.json$/);
+        const onDisk = JSON.parse(fs.readFileSync(first.recordPath, 'utf8'));
+        expect(recordIntact(onDisk)).toBe(true);
+        const again = await runReviewer(repo, 'main', config, fakes(() => { throw new Error('a cached read never runs a judge'); }, seen), () => undefined);
+        expect(again.cached).toBe(true);
+        expect(again.record?.integrity).toBe(first.record?.integrity);
+    });
+    it('reviews through the API judge when the team configured one and its key is set, with the same prompt and accounting', async () => {
+        const seen = seenNow();
+        const calls = [];
+        const fetchImpl = (async (_url, init) => {
+            const body = JSON.parse(init.body);
+            calls.push(body);
+            const last = body.messages.at(-1);
+            const message = last.role === 'user'
+                ? { role: 'assistant', content: null, tool_calls: [{ id: 't1', type: 'function', function: { name: 'read_file', arguments: JSON.stringify({ path: /(\S+full\.diff)/.exec(last.content)[1] }) } }] }
+                : { role: 'assistant', content: JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', input: 'two runs', consequence: 'two emails', quote: 'return 1;', severity: 'blocking' }] }) };
+            return new Response(JSON.stringify({ choices: [{ message }], usage: { prompt_tokens: 100, completion_tokens: 20, cost: 0.05 } }), { status: 200 });
+        });
+        const apiConfig = ConfigSchema.parse({ version: 1, review: { reviewer: { enabled: true, reviewers: ['api'], api: { url: 'https://example.test/v1', model: 'qwen3-coder', key_env: 'TEST_JUDGE_KEY' }, reasoning: { api: 'low' } } } });
+        const without = await runReviewer(repo, 'main', apiConfig, fakes(() => '', seen), () => undefined, { fetch: fetchImpl });
+        expect(without).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no reviewer installed') }); // the key is not set
+        process.env.TEST_JUDGE_KEY = 'secret';
+        try {
+            const result = await runReviewer(repo, 'main', apiConfig, fakes(() => '', seen), () => undefined, { fetch: fetchImpl, force: true });
+            expect(result).toMatchObject({ outcome: 'findings', reviewers: ['api'], costUsd: 0.1, items: [expect.objectContaining({ issue: 'returns before the lock', reviewer: 'api' })] });
+            expect(calls[0].reasoning_effort).toBe('low');
+            expect(calls[0].messages[1].content).toContain('full.diff'); // the same prompt a CLI judge gets
+            expect(result.record?.judges).toEqual([{ reviewer: 'api', version: 'qwen3-coder', cost_usd: 0.1, turns: 2 }]);
+        }
+        finally {
+            delete process.env.TEST_JUDGE_KEY;
+        }
+    });
     it('asks a judge once more after an answer that is not a verdict, and is unavailable only when the second is not one either', async () => {
         const seen = seenNow();
         let calls = 0;
@@ -351,9 +403,43 @@ describe('verdicts', () => {
         const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'job never closes the connection', input: 'every run', consequence: 'one connection leaks per run', quote: 'return 1;' };
         expect(decide({ findings: [{ ...finding, absent: 'return 1' }] })).toMatchObject({ open: [], unverified: [expect.anything()] }); // "missing", but the file has it
         expect(decide({ findings: [{ ...finding, absent: 'conn.close(' }] }).open).toHaveLength(1);
-        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], notes: [expect.anything()] });
+        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], advisory: [expect.anything()], unverified: [] }); // a verified should-fix: shown
+        expect(decide({ findings: [{ ...finding, severity: 'should', quote: 'return 99;' }] })).toMatchObject({ open: [], advisory: [], unverified: [expect.anything()] }); // a should-fix it cannot show: not a claim worth time
         const accepted = { point: 'job never closes the connection after the read', severity: 'non-blocking', resolved: false };
-        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], notes: [expect.anything()] }); // a human raised it and accepted it
+        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], advisory: [expect.anything()] }); // a human raised it and accepted it
+    });
+    it('blocks on a broken requirement rule only with its quote, shows broken guidance, and takes the rule\'s words from what Rigour served', () => {
+        const verify = checkoutVerifier(repo);
+        const served = [
+            { id: 'r1', source: 'AGENTS.md', text: 'Every job must take the lock before its first read.', requirement: true },
+            { id: 'r2', source: 'AGENTS.md', text: 'Prefer small functions.', requirement: false },
+        ];
+        const judged = (answers) => {
+            const verdict = { ...EMPTY, prior_points: [], rules: answers };
+            attachServedRules(verdict, served);
+            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(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: [] });
+        const unknown = judged([{ id: 'made-up', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', rule: 'a rule the judge invented', requirement: true }]);
+        expect(unknown.verdict.rules).toEqual([]); // an answer naming no served rule is dropped, whatever it claims
+        expect(unknown.open).toEqual([]);
+    });
+    it('shows the same point found in several places as one item with every location, and never merges human points', () => {
+        const scan = (file, line, quote) => ({ class: 'production-cost', file, line, issue: `the ${file.split('/').pop()} scan has no upper bound on updated_at`, input: 'a week of rows', consequence: 'rows read grow with time', quote });
+        const verdict = { ...EMPTY, prior_points: [
+                { point: 'bound the window', severity: 'blocking', resolved: false, file: 'src/job.ts', line: 1, quote: 'export function job() {' },
+                { point: 'bound the window again', severity: 'blocking', resolved: false, file: 'src/job.ts', line: 1, quote: 'export function job() {' },
+            ], findings: [scan('src/job.ts', 1, 'export function job() {'), scan('a.ts', 1, 'export const a = 1;'), { ...scan('src/job.ts', 2, 'return 1;'), class: 'correctness' }] };
+        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
+        ]);
     });
     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

@@ -103,3 +103,5 @@ export declare function writeLessons(cwd: string, lessons: ReviewLesson[]): void
 export declare function decideLesson(cwd: string, id: string, decision: 'accepted' | 'rejected', by: string, why?: string): ReviewLesson | undefined;
 /** An identifier specific enough to link two pieces of code: camelCase, snake_case, or long. */
 export declare function isSpecific(symbol: string): boolean;
+/** The meaningful words of a text or an identifier: `hasLaterAttempt` and "a later attempt" share later and attempt. */
+export declare function meaningfulWords(text: string): string[];

package/dist/review-learning/lessons.js

@@ -191,10 +191,10 @@ export function matchLessons(lessons, change, options = {}) {
         .sort((a, b) => b.score - a.score || b.lesson.evidence.length - a.lesson.evidence.length);
     // A team standard (no file) applies when its words are the change's: its paths and the names on its added lines,
     // split into words. A rule about keyboard shortcuts says nothing to a change to a database job.
-    const changeWords = new Set([...change.files.flatMap(f => f.split(/[/._-]+/)), ...change.symbols].flatMap(words));
+    const changeWords = new Set([...change.files.flatMap(f => f.split(/[/._-]+/)), ...change.symbols].flatMap(meaningfulWords));
     const standards = lessons
         .filter(l => !l.file && (l.state === 'verified' || (options.includeCandidates && l.state === 'candidate')))
-        .map(l => ({ lesson: l, shared: new Set(words(l.text)).size === 0 ? 0 : [...new Set(words(l.text))].filter(w => changeWords.has(w)).length }))
+        .map(l => ({ lesson: l, shared: new Set(meaningfulWords(l.text)).size === 0 ? 0 : [...new Set(meaningfulWords(l.text))].filter(w => changeWords.has(w)).length }))
         .filter(s => s.shared >= STANDARD_WORDS)
         .sort((a, b) => b.shared - a.shared || b.lesson.evidence.length - a.lesson.evidence.length)
         .slice(0, options.standards ?? MAX_STANDARDS)
@@ -251,7 +251,7 @@ function sameWords(a, b) {
     return common / Math.max(x.size, y.size) >= 0.6;
 }
 /** The meaningful words of a text or an identifier: `hasLaterAttempt` and "a later attempt" share later and attempt. */
-function words(text) {
+export function meaningfulWords(text) {
     return text.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z]+/).filter(w => w.length >= 4 && !PLAIN_WORDS.has(w));
 }
 /** Who made a point and on whose pull request: recorded with it, never a filter. */

package/dist/review-learning/repo-rules.d.ts

@@ -1,16 +1,18 @@
 export interface RepoRule {
+    /** Stable across runs: the source file and the rule's words. */
+    id: string;
     source: string;
     text: string;
     /** Paths the rule names (files or directories). */
     paths: string[];
     /** Identifiers the rule names. */
     symbols: string[];
+    /** Worded as a requirement: a break can block. Guidance otherwise: a break is shown. */
+    requirement: boolean;
 }
 export declare function readRepoRules(cwd: string): RepoRule[];
 /** One rule per top-level bullet or paragraph; headings and import lines are not rules. */
 export declare function splitRules(source: string, text: string): RepoRule[];
-/** Rules that name a path the change touches, or a specific identifier in it; most specific first. */
-export declare function rulesForChange(rules: RepoRule[], files: string[], symbols: Set<string>): RepoRule[];
 export declare function rulesSection(rules: RepoRule[]): string;
-/** The rules that apply to a diff's changed files and added identifiers. */
-export declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean): RepoRule[];
+/** The rules that apply to a diff's changed files and added identifiers, the top `limit`. */
+export declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean, limit?: number): RepoRule[];