@rigour-labs/core 6.10.1 → 6.11.0-rc.2

package/dist/deep/pr-review.d.ts

@@ -1,6 +1,6 @@
 import type { DeepFinding, InferenceOptions, InferenceProvider } from '../inference/types.js';
 import type { CodeContext } from './code-context.js';
-import { type SettledCheck } from '../review/settled-checks.js';
+import { type CoveredLesson, type SettledCheck } from '../review/settled-checks.js';
 import type { RelatedChange } from './related-changes.js';
 export interface FocusItem {
     file: string;
@@ -22,6 +22,8 @@ export interface PrReviewInput {
     prBody?: string;
     /** What Rigour's checks already found on the change: listed as settled; a finding of the same kind at one of their lines is dropped. */
     settled?: SettledCheck[];
+    /** Lessons the team's compiled checks covered on this change, left out of `lessons`: the prompt says so. */
+    covered?: CoveredLesson[];
 }
 export interface PrReviewResult {
     findings: DeepFinding[];

package/dist/deep/pr-review.js

@@ -14,7 +14,7 @@ import { REVIEW_CATEGORIES } from './code-review-prompt.js';
 import { parseFindings } from './parse-findings.js';
 import { diffSections } from './pr-diff.js';
 import { runToolLoop } from './tool-loop.js';
-import { againstSettled, settledLine, settledSection } from '../review/settled-checks.js';
+import { againstSettled, coveredSection, settledLine, settledSection } from '../review/settled-checks.js';
 const BUDGET = { maxToolCalls: 24, maxTurns: 14 };
 const MAX_DIFF_CHARS = 80_000;
 const MAX_FINDINGS = 5;
@@ -67,6 +67,7 @@ export function buildPrPrompt(input) {
         input.prBody ? `PR DESCRIPTION (what the author intended):\n${input.prBody.slice(0, PR_BODY_CHARS)}` : '',
         input.rules ?? '',
         input.lessons ?? '',
+        coveredSection(input.covered ?? []),
         settledSection((input.settled ?? []).map(settledLine)),
         contracts ? `BOTH SIDES OF A CALL CHANGED (check these contracts first):\n${contracts}` : '',
         focus ? `LOOK FIRST (riskiest changed functions, and what to check):\n${focus}` : '',

package/dist/gates/deep-analysis.js

@@ -31,6 +31,7 @@ import { checkLocalPatterns } from '../storage/local-memory.js';
 import { isScoped } from '../utils/scope.js';
 import { Logger } from '../utils/logger.js';
 import path from 'path';
+import { withoutCovered } from '../review/settled-checks.js';
 /** Cloud setup (API connection) must not hang a check. Local setup is bounded by download stall timeouts instead. */
 const CLOUD_SETUP_TIMEOUT_MS = 120_000;
 /**
@@ -158,7 +159,7 @@ export class DeepAnalysisGate extends Gate {
         const related = relatedChanges(cwd, changedFiles, rankChangedFunctions(cwd, options.focusLines ?? {}, options.removedLines));
         this.config.onProgress?.(`  Reviewing the PR as a whole (${focus.length} risky function(s) first)...`);
         try {
-            const result = await reviewPullRequest(this.provider, { cwd, diff: options.diff, focus, related, lessons: lessonsSection(lessonsForDiff(cwd, options.diff, this.config.reviewLessons)),
+            const result = await reviewPullRequest(this.provider, { cwd, diff: options.diff, focus, related, lessons: lessonsSection(withoutCovered(lessonsForDiff(cwd, options.diff, this.config.reviewLessons), options.covered ?? [])), covered: options.covered,
                 rules: rulesSection(rulesForDiff(cwd, options.diff, this.config.repoRules)), prBody: options.prBody, settled: options.settled }, inferenceOptions(this.config));
             this.recordPass({ findings: [], chunksTotal: 1, chunksFailed: 0 });
             this.outcome.findingsProposed = result.findings.length;

package/dist/gates/runner.js

@@ -215,7 +215,7 @@ export class GateRunner {
         let deepStats = undefined;
         if (deepOptions?.enabled) {
             // What the checks found on the change's lines is settled: the model is told so and never reports it again.
-            const deep = await runDeepAnalysis(this.config, { cwd, ignore, patterns }, { ...deepOptions, settled: settledChecks(onChangedLines(failures, deepOptions.focusLines)) });
+            const deep = await runDeepAnalysis(this.config, { cwd, ignore, patterns }, { ...deepOptions, settled: [...(deepOptions.settled ?? []), ...settledChecks(onChangedLines(failures, deepOptions.focusLines))] });
             failures.push(...deep.failures);
             summary['deep-analysis'] = deep.summary;
             deepStats = deep.stats;

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest
 export { scaffoldLedger } from './review/backtest-init.js';
 export type { CiResult, FollowUp, PrOutcome } from './outcomes/outcome.js';
 export { localOutcomeMetrics, runOutcomes, type OutcomesRun } from './outcomes/run.js';
+export { learningUsage } from './telemetry/learning-usage.js';
 export type { OutcomeMetrics, Share } from './outcomes/metrics.js';
 export { fixScope, type FixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
@@ -44,6 +45,7 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction, type Funct
 export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
 export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
+export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspension, type CompiledCheck } from './review-learning/compiled-lessons.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH, type LastReport } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact, type ReviewRecord } from './review/reviewer/record.js';

package/dist/index.js

@@ -20,6 +20,7 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSpli
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
 export { localOutcomeMetrics, runOutcomes } from './outcomes/run.js';
+export { learningUsage } from './telemetry/learning-usage.js';
 export { fixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
 export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
@@ -42,6 +43,7 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction } from './d
 export { routeFiles } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
 export { learnFromReviews } from './review-learning/learn-from-reviews.js';
+export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspension } from './review-learning/compiled-lessons.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact } from './review/reviewer/record.js';

package/dist/outcomes/run.d.ts

@@ -8,7 +8,7 @@ import { type Exec } from '../review/reviewer/exec.js';
 import { type ResolvedSwitch } from '../switches.js';
 import { type PrOutcome } from './outcome.js';
 import { type OutcomeEvidenceResult } from '../review-learning/outcome-evidence.js';
-import { type OutcomeMetrics } from './metrics.js';
+import { type OutcomeMetrics, type PrReviews } from './metrics.js';
 export interface OutcomesRun {
     switch: ResolvedSwitch;
     outcomes: PrOutcome[];
@@ -27,5 +27,10 @@ export declare function runOutcomes(cwd: string, config: Config, options: {
     last?: number;
     exec?: Exec;
 }): Promise<OutcomesRun>;
+/** Per pull request, the lessons a review of it recorded as applying, and every pull request a review by Rigour ran on with its rounds' dollars and its first review's findings: from the threads. */
+export declare function threadReviews(cwd: string): {
+    applied: Map<number, Set<string>>;
+    reviewed: Map<number, PrReviews>;
+};
 /** The outcome numbers for this checkout (metrics.ts), over every record it keeps; undefined when it keeps none. Read-only. */
 export declare function localOutcomeMetrics(cwd: string): OutcomeMetrics | undefined;

package/dist/outcomes/run.js

@@ -39,13 +39,13 @@ function lessonEvidence(cwd, mainRef, demoteAfter) {
     const lessons = readLessons(cwd);
     if (lessons.length === 0)
         return undefined;
-    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), reviews(cwd).applied, { demoteAfter, git: gitIn(cwd), mainRef, deadline: Date.now() + LESSON_DEADLINE_MS });
+    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), threadReviews(cwd).applied, { demoteAfter, git: gitIn(cwd), mainRef, deadline: Date.now() + LESSON_DEADLINE_MS });
     if (result.added)
         writeLessons(cwd, lessons);
     return result;
 }
 /** Per pull request, the lessons a review of it recorded as applying, and every pull request a review by Rigour ran on with its rounds' dollars and its first review's findings: from the threads. */
-function reviews(cwd) {
+export function threadReviews(cwd) {
     const applied = new Map();
     const reviewed = new Map();
     const count = (v) => typeof v === 'number' ? v : 0;
@@ -72,7 +72,7 @@ function reviews(cwd) {
 /** The outcome numbers for this checkout (metrics.ts), over every record it keeps; undefined when it keeps none. Read-only. */
 export function localOutcomeMetrics(cwd) {
     const records = Object.values(readPrOutcomes(cwd).outcomes);
-    return records.length ? outcomeMetrics(records, readLessons(cwd), reviews(cwd).reviewed) : undefined;
+    return records.length ? outcomeMetrics(records, readLessons(cwd), threadReviews(cwd).reviewed) : undefined;
 }
 async function onePr(cwd, pr, exec, env) {
     const view = await exec('gh', ['pr', 'view', String(pr), '--json', 'number,mergedAt,mergeCommit,headRefName,author,state'], { cwd, timeoutMs: GH_TIMEOUT_MS, ...(env ? { env } : {}) });

package/dist/review/check-outcomes.js

@@ -13,6 +13,8 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { telemetryCheckId } from '../telemetry/check-ids.js';
+import { countUsage } from '../telemetry/telemetry.js';
 import { readStateFile } from './trusted-state.js';
 const OUTCOMES_FILE = path.join('.rigour', 'check-outcomes.json');
 const REPORTED_FILE = path.join('.rigour', 'reported-findings.json');
@@ -49,6 +51,12 @@ export function recordOutcome(cwd, check, kind) {
     const current = outcomes[check] ?? { fixed: 0, dismissed: 0 };
     outcomes[check] = { ...current, [kind]: current[kind] + 1 };
     writeJson(path.join(cwd, OUTCOMES_FILE), outcomes);
+    // The same outcome, counted for opt-in telemetry by the check's gate id only, and only if it is one of Rigour's own.
+    countUsage(`finding_${kind}:${telemetryCheckId(gateOf(check))}`);
+}
+/** A check id's gate: `semantic-bugs` of `semantic-bugs: Credential header follows redirects`. */
+function gateOf(check) {
+    return check.split(':')[0].trim();
 }
 /** Every check with an outcome, most dismissed first. */
 export function checkPrecisions(cwd) {

package/dist/review/learning-events.js

@@ -1,4 +1,6 @@
 import { appendAgentEvent } from './effectiveness.js';
+import { countUsage } from '../telemetry/telemetry.js';
+import { telemetryCheckId } from '../telemetry/check-ids.js';
 const MAX_LISTED = 20;
 /** Lessons an agent was given before or while writing code. Nothing is written when none were. */
 export function recordLessonsServed(cwd, via, subjects) {
@@ -10,6 +12,9 @@ export function recordLessonsServed(cwd, via, subjects) {
 export function recordPrCatches(cwd, findings) {
     if (findings.length === 0)
         return;
+    // A finding that reached a pull request's review: counted for opt-in telemetry by its gate id only, if one of Rigour's own.
+    for (const finding of findings)
+        countUsage(`finding_pushed:${telemetryCheckId(finding.id)}`);
     appendAgentEvent(cwd, {
         type: 'pr_catches',
         findings: findings.slice(0, MAX_LISTED).map(f => ({ rule: f.id, title: f.title, file: f.files?.[0] ?? '' })),

package/dist/review/quiet.js

@@ -20,7 +20,7 @@ import fs from 'fs';
 import path from 'path';
 import { checkId, isMuted, readOutcomes, recordOutcome, reportedCheck } from './check-outcomes.js';
 import { readStateFile } from './trusted-state.js';
-const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'migration-order',
+const PROVEN_GATES = new Set(['compiled-lesson', 'semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'migration-order',
     'duplicate-null-filter', 'nullable-filtered-column', 'optional-always-supplied', 'write-only-property', 'typed-checks-unavailable',
     'goal-scope', 'goal-done-when']);
 export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');

package/dist/review/review.d.ts

@@ -1,5 +1,6 @@
 import type { Config, DeepOptions, Failure, Report } from '../types/index.js';
 import { type DiffSource } from './git-diff.js';
+import { type CoveredLesson } from './settled-checks.js';
 import { type Goal } from '../goal/goal.js';
 export interface ReviewInput {
     cwd: string;
@@ -52,6 +53,8 @@ export interface ReviewResult {
     typedError?: string;
     /** The goal the description declared, when the goal check ran on one with something to check. */
     goal?: Goal;
+    /** The lessons the team's compiled checks covered on this change: a model reviewer is told so instead of the lesson. */
+    covered: CoveredLesson[];
 }
 export interface ReviewFinding {
     id: string;

package/dist/review/review.js

@@ -20,6 +20,8 @@ import { checkId, rememberReported } from './check-outcomes.js';
 import { diffFromGit } from './git-diff.js';
 import { diffTestFailures } from './diff-test-findings.js';
 import { migrationOrderFailures } from './migration-order.js';
+import { compiledChecksOn } from '../review-learning/compiled-lessons.js';
+import { settledChecks } from './settled-checks.js';
 import { orphanFileFailures } from './orphan-files.js';
 import { unusedExportFailures } from './unused-exports.js';
 import { queryPatternFailures } from './query-patterns.js';
@@ -37,9 +39,11 @@ export async function reviewChange(input) {
     const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff), hints: [] };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff), hints: [], covered: [] };
     }
-    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
+    // The team's compiled checks run before the deep review, so it is told what they found and which lessons they covered.
+    const compiled = compiledChecksOn(input.cwd, changedLines, input.config);
+    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff, settled: settledChecks(compiled.failures), covered: compiled.covered } : undefined;
     // The team's `commands:` run at push (toolchain.ts), where a failure blocks; here they would only cost time.
     const report = await new GateRunner({ ...input.config, commands: {} }).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
     const { preexisting, baseUnknown } = await dropPreexisting(input, report, targets);
@@ -54,6 +58,7 @@ export async function reviewChange(input) {
     reviewCheck('migration-order', 'migration_order', migrationOrderFailures(input.cwd, diff, input.source, input.config));
     reviewCheck('unused-exports', 'unused_exports', unusedExportFailures(input.cwd, diff, input.config));
     reviewCheck('orphan-files', 'orphan_files', orphanFileFailures(input.cwd, diff, input.config));
+    reviewCheck('compiled-lessons', 'compiled_lessons', compiled.failures);
     reviewCheck('query-patterns', 'query_patterns', queryPatternFailures(input.cwd, changedLines, input.config));
     reviewCheck('optional-params', 'optional_params', optionalParamFailures(input.cwd, changedLines, input.config));
     reviewCheck('duplicate-functions', 'duplicate_functions', duplicateFunctionFailures(input.cwd, changedLines, input.config));
@@ -97,6 +102,7 @@ export async function reviewChange(input) {
         gateErrors,
         controlFilesChanged: controlFiles(diff),
         hints: typed.hints,
+        covered: compiled.covered,
         ...(deepError ? { deepError } : {}),
         ...(typed.error ? { typedError: typed.error } : {}),
         ...(checkedGoal ? { goal: checkedGoal } : {}),

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

@@ -3,6 +3,7 @@ import type { RouterPolicy } from '../../deep/router.js';
 import type { PanelItem } from './panel.js';
 import { type Exec } from './exec.js';
 import type { OpenItem, ServedRule } from './verdict.js';
+import { type CoveredLesson } from '../settled-checks.js';
 export declare const REVIEW_DISMISSALS: string;
 export interface ReviewDismissal {
     id: string;
@@ -43,18 +44,29 @@ export interface ContextInput {
     }>;
     /** Findings Rigour's checks already report on this change, one line each. */
     checks: string[];
+    /** Lessons the team's compiled checks covered on this change: left out of the lessons, and said so. */
+    covered?: CoveredLesson[];
 }
 /** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
 export declare function reviewerInputs(review: {
     hints: string[];
     findings: Array<{
+        id?: string;
         files?: string[];
         line?: number;
         title: string;
     }>;
+    advisory?: Array<{
+        id?: string;
+        files?: string[];
+        line?: number;
+        title: string;
+    }>;
+    covered?: CoveredLesson[];
 }): {
     hints: string;
     checks: string[];
+    covered: CoveredLesson[];
 };
 /** A lesson as the judge was shown it: its id, and the line it was listed as (the judge answers by that line). */
 export interface ServedLesson {

package/dist/review/reviewer/context.js

@@ -20,7 +20,7 @@ import { reviewedKeys } from '../ledger.js';
 import { textSimilarity } from './consensus.js';
 import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
 import { VerdictStore } from './store.js';
-import { MAX_SETTLED, settledChecks, settledLine, settledSection } from '../settled-checks.js';
+import { coveredSection, MAX_SETTLED, settledChecks, settledLine, settledSection, withoutCovered } from '../settled-checks.js';
 export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.json');
 const MAX_DOCS = 10;
 /** Team standards a judge is shown with the lessons about the changed files. */
@@ -68,7 +68,9 @@ export function dismissedAs(item, dismissals) {
 }
 /** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
 export function reviewerInputs(review) {
-    return { hints: review.hints.join('\n'), checks: settledChecks(review.findings).map(settledLine) };
+    // A compiled check's findings are notes, and settled too: the judge no longer has the lesson, so it must have them.
+    const compiled = (review.advisory ?? []).filter(f => f.id === 'compiled-lesson');
+    return { hints: review.hints.join('\n'), checks: settledChecks([...review.findings, ...compiled]).map(settledLine), covered: review.covered ?? [] };
 }
 /** The ids of the served lessons the judge said this change repeats; an answer that names no served lesson says nothing. */
 export function lessonsApplied(answers, served) {
@@ -87,13 +89,15 @@ 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 servedLessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS, JUDGE_FILE_LESSONS, JUDGE_LESSONS_PER_FILE, input.pr).map(l => ({ id: l.id, listed: describeLesson(lessonView(l)) }));
+    const servedLessons = input.lessons === 'off' ? [] : withoutCovered(lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS, JUDGE_FILE_LESSONS, JUDGE_LESSONS_PER_FILE, input.pr), input.covered ?? []).map(l => ({ id: l.id, listed: describeLesson(lessonView(l)) }));
     if (servedLessons.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${servedLessons.map(l => `- ${l.listed}`).join('\n')}`);
     // The repository's own rules, always: the reviewer is the boundary, and what the team wrote is the standard it checks.
     const rules = rulesForDiff(input.cwd, input.diff, true, JUDGE_RULES).map((r) => ({ id: r.id, source: r.source, text: r.text, requirement: r.requirement }));
     if (rules.length)
         sections.push(`## Rules this repository wrote for itself that apply to this change (answer every one in rules, by id)\n${rules.map(r => `- [${r.id}] (${r.source}, ${r.requirement ? 'requirement' : 'guidance'}) ${r.text}`).join('\n')}`);
+    if (input.covered?.length)
+        sections.push(coveredSection(input.covered));
     if (input.checks.length)
         sections.push(settledSection(input.checks));
     const rejected = input.lessons === 'off' ? [] : rejectedForDiff(input.cwd, input.diff).map(l => {

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

@@ -35,6 +35,8 @@ export interface ResolvedReviewer {
     judges: 2 | 3;
     escalate: 'always' | 'risk';
     cross_models: Record<string, string>;
+    /** The cheap model per reviewer name for cheap-model-first tiering; empty when it is off (team only). */
+    tiers: Record<string, string>;
     /** Reasoning effort per reviewer name (codex, api). */
     reasoning: Record<string, 'low' | 'medium' | 'high'>;
     /** The API judge, when the team configured one (review.reviewer.api). */

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, orchestrator: 'off', judges: 2, escalate: 'always', cross_models: {}, judge_env: {}, reasoning: {} };
+    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, orchestrator: 'off', judges: 2, escalate: 'always', cross_models: {}, tiers: { cheap: {} }, judge_env: {}, reasoning: {} };
     const refused = [];
     const envMode = parseMode(env.RIGOUR_REVIEWER_MODE);
     const envPanel = parseSwitch(env.RIGOUR_REVIEWER_PANEL);
@@ -78,6 +78,7 @@ export function resolveReviewer(config, choice = {}, user = loadSettings().revie
         judges: floor ? Math.max(team.judges, user?.judges ?? team.judges) : user?.judges ?? team.judges,
         escalate: requiredEscalation(team, user, refused),
         cross_models: team.cross_models,
+        tiers: team.tiers?.cheap ?? {},
         judge_env: team.judge_env ?? {},
         reasoning: team.reasoning ?? {},
         ...(team.api ? { api: team.api } : {}),

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

@@ -43,6 +43,8 @@ export interface ReviewCost {
     runs: number;
     /** A verdict reused instead of run: for the same content on another commit (`content`). Runs and actual cost are 0. */
     cache?: 'content';
+    /** The tier the review ran at, when cheap-model-first tiering is on (reviewer/tiering.ts). */
+    tier?: 'cheap' | 'strong';
 }
 /**
  * A verdict, findable by the content it reviewed rather than its commit: a rebase, an amend, a cherry-pick or the same

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

@@ -0,0 +1,38 @@
+/**
+ * Cheap-model-first tiering (off by default; review.reviewer.tiers.cheap names a cheaper model per judge). Which model
+ * reviews a change is decided BEFORE any run, from facts about the change only: never by a model, and never from a
+ * model's findings. A change with something a cheaper model may miss gets the team's model:
+ *
+ *   a required floor, human reviews to check, open items carried from the last verdict, a migration, a security
+ *   finding from the checks, a declared goal, or a risky changed function (the router's score)
+ *
+ * Anything else gets the cheap model. After the run, the only escalation is an answer that is not a valid verdict: the
+ * one retry the reviewer already makes uses the team's model. What blocks is unchanged: the same evidence contract.
+ *
+ * The rule a tier must keep: on average, a review costs no more than one judge would have. Over the last
+ * TIER_WINDOW reviews tiering ran on, actual cost against what one judge would have been given (the frozen baseline's
+ * dollars per character, else characters); above it, tiering turns itself off and the review record says so.
+ */
+import type { CostBaseline, ReviewCost } from './store.js';
+export interface TierDecision {
+    tier: 'cheap' | 'strong';
+    /** The cheap model, when the tier is cheap. */
+    model?: string;
+    why: string;
+    /** Why tiering turned itself off, when it did. */
+    disabled?: string;
+    /** Why the cheap model's run was retried on the team's model: its answer was not a valid verdict. */
+    escalated?: string;
+}
+export interface TierFacts {
+    required: boolean;
+    humanReviews: number;
+    carried: number;
+    migration: boolean;
+    securityChecks: number;
+    goal: boolean;
+    /** Risky changed functions (the router's score); undefined when it could not score the change. */
+    risky: number | undefined;
+}
+/** The tier for one judge's review; undefined when no cheap model is set for it (tiering is off). */
+export declare function chooseTier(cheap: Record<string, string>, judge: string, facts: TierFacts, costs: ReviewCost[], baseline: CostBaseline | undefined): TierDecision | undefined;

package/dist/review/reviewer/tiering.js

@@ -0,0 +1,43 @@
+/** Recent tiered reviews the self-disable rule reads. */
+const TIER_WINDOW = 20;
+/** Tiered reviews needed before the rule can turn tiering off. */
+const TIER_MIN = 5;
+/** The tier for one judge's review; undefined when no cheap model is set for it (tiering is off). */
+export function chooseTier(cheap, judge, facts, costs, baseline) {
+    const model = cheap[judge];
+    if (!model)
+        return undefined;
+    const disabled = overBudget(costs, baseline);
+    if (disabled)
+        return { tier: 'strong', why: 'tiering turned itself off', disabled };
+    const strong = (why) => ({ tier: 'strong', why });
+    if (facts.required)
+        return strong('a required floor');
+    if (facts.humanReviews > 0)
+        return strong(`${facts.humanReviews} human review(s) to check`);
+    if (facts.carried > 0)
+        return strong(`${facts.carried} open item(s) carried from the last verdict`);
+    if (facts.migration)
+        return strong('the change adds or edits a migration');
+    if (facts.securityChecks > 0)
+        return strong(`${facts.securityChecks} security finding(s) from the checks`);
+    if (facts.goal)
+        return strong('the description declares a goal to check');
+    if (facts.risky === undefined)
+        return strong('the risk router could not score the change');
+    if (facts.risky > 0)
+        return strong(`${facts.risky} risky changed function(s)`);
+    return { tier: 'cheap', model, why: 'no risk signal: the cheap model' };
+}
+/** Why tiering must turn itself off: its recent reviews cost more, on average, than one judge would have. */
+function overBudget(costs, baseline) {
+    const tiered = costs.filter(c => c.tier).slice(-TIER_WINDOW);
+    if (tiered.length < TIER_MIN)
+        return undefined;
+    const rate = baseline?.usdPerChar ?? null;
+    const single = tiered.reduce((sum, c) => sum + c.projectedSingleChars * (rate ?? 1), 0);
+    const actual = tiered.reduce((sum, c) => sum + (rate === null ? c.actualChars : c.actualUsd > 0 ? c.actualUsd : c.actualChars * rate), 0);
+    if (single <= 0 || actual <= single)
+        return undefined;
+    return `the last ${tiered.length} tiered reviews cost ${(actual / single).toFixed(2)}x what one judge would have (${rate === null ? 'characters' : 'dollars'})`;
+}

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

@@ -31,6 +31,8 @@ export interface TriageContext {
 }
 /** Per specialist, the hunks it is for (by index); a specialist absent from the map is not needed. Prior points take the whole change. */
 export declare function triage(hunks: Hunk[], context: TriageContext): Map<string, number[]>;
+/** Whether a file is a migration or a schema (a change a cheaper model may miss the cost of). */
+export declare function isMigration(file: string): boolean;
 /** Whether no model reviews this file (SKIP). */
 export declare function skipped(file: string): boolean;
 export interface Pass {

package/dist/review/reviewer/triage.js

@@ -79,6 +79,10 @@ export function triage(hunks, context) {
         picked.set('prior-points', hunks.map((_, i) => i).filter(i => !skipped(hunks[i].file)));
     return picked;
 }
+/** Whether a file is a migration or a schema (a change a cheaper model may miss the cost of). */
+export function isMigration(file) {
+    return MIGRATION.test(file);
+}
 /** Whether no model reviews this file (SKIP). */
 export function skipped(file) {
     return SKIP.some(pattern => pattern.test(file));

package/dist/review/reviewer/usage.js

@@ -18,6 +18,7 @@ export function reviewerUsage(result, trigger) {
         judges: result.reviewers.length,
         cached: result.cached,
         ...(result.cache ? { cache: result.cache } : {}),
+        ...(mode?.tier ? { tier: mode.tier.tier, tier_disabled: !!mode.tier.disabled, tier_escalated: !!mode.tier.escalated } : {}),
         confirmed: result.items.length,
         disputed: result.disputed.length,
         dropped: result.dropped.length,

package/dist/review/reviewer.d.ts

@@ -2,9 +2,11 @@ import type { Config } from '../types/index.js';
 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 TierDecision } from './reviewer/tiering.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';
+import type { CoveredLesson } from './settled-checks.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';
@@ -29,6 +31,8 @@ export interface ReviewerOptions {
     hints?: string;
     /** What Rigour's checks already found on this change: settled, so no judge spends a turn finding it again. */
     checks?: string[];
+    /** Lessons the team's compiled checks covered on this change (review.ts): left out of the judge's lessons, and said so. */
+    covered?: CoveredLesson[];
     /** Where the team's state lives (.rigour: dismissals, reviewed functions) when cwd is a worktree that lacks it. */
     stateRoot?: string;
     /** The branch the commit was pushed from, when reviewing it in a detached worktree (background.ts). */
@@ -133,6 +137,8 @@ export interface ModeRecord {
     refused?: string[];
     /** With escalate: risk, why this review got one judge or all of them. */
     escalation?: string;
+    /** With cheap-model-first tiering on: the tier, why, and whether it turned itself off or escalated (reviewer/tiering.ts). */
+    tier?: TierDecision;
 }
 /** Findings and no verdict stop a push; a skipped review does not, and is reported as owed. */
 export declare function reviewerBlocks(result: ReviewerResult): boolean;

package/dist/review/reviewer.js

@@ -29,7 +29,8 @@ import { mergeImpact } from './reviewer/merge-impact.js';
 import { applyPanel, parseAnswers, runPanel } from './reviewer/panel.js';
 import { crossExamPrompt, deltaBlock, goalStep, mergeBlock, PROMPT_VERSION, renderPrompt } from './reviewer/prompt.js';
 import { BASELINE_MIN_SINGLES, focusBlock, formatLedger, ledger, passLimit, runPasses, SPECIALISTS, SPECIALISTS_KEY, splitNeeds } from './reviewer/orchestrator.js';
-import { MAX_PARTS, parseHunks, planPasses, reviewable, skipped, triage } from './reviewer/triage.js';
+import { isMigration, MAX_PARTS, parseHunks, planPasses, reviewable, skipped, triage } from './reviewer/triage.js';
+import { chooseTier } from './reviewer/tiering.js';
 import { modelGoalItems, parseGoal } from '../goal/goal.js';
 import { resolveSwitch } from '../switches.js';
 import { resolveReviewer } from './reviewer/settings.js';
@@ -177,7 +178,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, ...(pr ? { pr: pr.number } : {}), 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 ?? [], covered: options.covered ?? [],
         previousPanel: previousIsAncestor ? store.readJson(previous.verdict)?.panel?.items : undefined,
         docs: await relatedDocs(cwd, changedFiles, exec),
     });
@@ -224,7 +225,17 @@ async function review(cwd, base, config, exec, progress, options) {
     const previousOpen = scope === 'delta' ? store.readJson(store.openPath(previous.verdict)) ?? [] : undefined;
     const verify = checkoutVerifier(cwd);
     const prior = { approvals: reviews.approvals, inCheckout: checkoutSearch(cwd), changed: changedLinesOf(fullDiff), labels: reviews.labels };
-    const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
+    // Cheap-model-first (reviewer/tiering.ts): decided before any run, from facts about the change only, for one judge.
+    let tier = reviewers.length === 1 && (modeRecord.ran === 'single' || modeRecord.ran === 'orchestrator')
+        ? chooseTier(settings.tiers, reviewers[0], {
+            required: settings.required.mode || settings.required.panel || orchestrator.required, humanReviews: reviews.count, carried: previousOpen?.length ?? 0,
+            migration: changedFiles.some(isMigration), securityChecks: (options.checks ?? []).filter(c => /\bsecurity\b/i.test(c)).length, goal: goalItems.length > 0, risky: context.risky,
+        }, store.costs(), store.baseline())
+        : undefined;
+    if (tier)
+        modeRecord = { ...modeRecord, tier };
+    const cheapModel = () => (tier?.tier === 'cheap' && !tier.escalated ? tier.model : undefined);
+    const modelFor = (name) => (name === reviewers[0] ? cheapModel() : undefined) ?? 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.
     // What a judge reads besides the repository and Rigour's inputs, on this machine: on the record, so "the same judge" is a claim it can check.
     const outsideOf = (reviewer) => {
@@ -323,7 +334,7 @@ async function review(cwd, base, config, exec, progress, options) {
         store.recordCost({
             at: new Date().toISOString(), mode: orchestrated ? 'orchestrator' : 'single', lines: size.lines, projectedSingleChars: projectedSingle,
             ...(orchestrated ? { projectedChars: passes.reduce((sum, pass) => sum + shared + pass.diff.length, 0) } : {}),
-            actualChars: tally.chars, actualUsd: spentUsd(), runs: tally.runs,
+            actualChars: tally.chars, actualUsd: spentUsd(), runs: tally.runs, ...(tier ? { tier: tier.tier } : {}),
         });
     };
     // One judge run, by CLI or by API: the same prompt, the same cost accounting, the same trace.
@@ -438,6 +449,11 @@ async function review(cwd, base, config, exec, progress, options) {
                     // No verdict, whether a malformed answer or a run that died, is a slip, not a decision: asked once more, inside the caps.
                     if (!once && (!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`);
+                        // The cheap model's slip is the one escalation: the retry runs on the team's model.
+                        if (cheapModel()) {
+                            tier = { ...tier, escalated: 'no valid verdict from the cheap model: retried on the team\'s model' };
+                            modeRecord = { ...modeRecord, tier };
+                        }
                         first = await ask();
                     }
                     return first.verdict ?? { error: `${name}: no answer (exit ${first.run.exitCode}): ${first.run.stderr.trim().slice(-200)}` };

package/dist/review/settled-checks.d.ts

@@ -1,6 +1,5 @@
 /**
- * What Rigour's checks already found on a change, as a model reviewer is told it: settled, blocking on their own, never
- * to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
+ * What Rigour's checks already found on a change, as a model reviewer is told it: settled, never to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
  * so neither spends a model's turn on what a free check proves.
  */
 /** A check's finding where it sits; `kind` is the check's id. */
@@ -37,3 +36,15 @@ export declare function settledChecks(findings: Array<{
 export declare function settledLine(check: SettledCheck): string;
 /** The prompt section; empty when there is nothing settled. */
 export declare function settledSection(lines: string[]): string;
+/** A lesson a compiled check covered on this change: the check ran on its files, and its findings are settled. */
+export interface CoveredLesson {
+    checkId: string;
+    lessonId: string;
+    message: string;
+}
+/** A model reviewer's lessons without those a compiled check covered on this change: the check said them for free. */
+export declare function withoutCovered<L extends {
+    id: string;
+}>(lessons: L[], covered: CoveredLesson[]): L[];
+/** The prompt section saying which lessons a compiled check covered instead; empty when none did. */
+export declare function coveredSection(covered: CoveredLesson[]): string;