@rigour-labs/core 6.9.0-rc.4 → 6.9.0-rc.5

package/dist/review/reviewer/triage.js

@@ -0,0 +1,147 @@
+/** Prose: its own words are for the rules and the goal, never a correctness pass. Matched by extension only: a `docs/` folder holds code too. */
+const PROSE = /\.(md|mdx|txt|rst|adoc)$/i;
+/**
+ * The only files no model reviews: lockfiles, snapshots, source maps, minified bundles and files a generator marks
+ * as its own (`__generated__/`, `.generated.`, protobuf output). Everything else gets a correctness pass, whatever
+ * its language: a missed skip costs a little, a wrong one leaves code unreviewed.
+ */
+const SKIP = [
+    /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|Pipfile\.lock|uv\.lock|go\.sum|Gemfile\.lock|composer\.lock|bun\.lockb?)$/,
+    /\.snap$/, /\.(js|css|d\.ts)\.map$/, /\.min\.(js|css)$/,
+    /(^|\/)__generated__\//, /\.generated\.[A-Za-z0-9]+$/, /\.pb\.go$/, /_pb2(_grpc)?\.pyi?$/, /_pb\.(js|ts|d\.ts)$/,
+];
+/** The most parts a split runs: a change that needs more is one combined pass. */
+export const MAX_PARTS = 3;
+const MIGRATION = /(^|\/)(migrations?|db\/migrate)\/|\.sql$|(^|\/)schema\.prisma$/i;
+/**
+ * Lines that read data, per language. Each names a query API, not a word any code uses: `Array.from`, `map.get`,
+ * `items.filter` and a `limit` variable are not reads.
+ */
+const READS = [
+    // SQL, in a .sql file or a string
+    /\bselect\s[\s\S]{0,80}?\bfrom\s+[A-Za-z_"`[]|\binsert\s+into\b|\bupdate\s+[A-Za-z_"`.]+\s+set\b|\bdelete\s+from\b|\bcreate\s+(unique\s+)?index\b|\balter\s+table\b|\bcreate\s+table\b|\blimit\s+\d+|\boffset\s+\d+/i,
+    // TS/JS: ORMs, query builders, Supabase, fetch
+    /\.(query|queryRaw|\$queryRaw|\$executeRaw|findMany|findFirst|findUnique|findOne|findAll|aggregate|groupBy|rpc)\s*\(|\.from\(\s*['"`]|\bfetch\s*\(|\.(range|limit|offset)\s*\(\s*\d/,
+    // Python: DB-API, SQLAlchemy, Django
+    /\.(execute|executemany|fetchall|fetchone|fetchmany)\s*\(|\bsession\.(query|execute|scalars)\s*\(|\.objects\.(filter|all|get|exclude|raw)\s*\(/,
+    // Go: database/sql, sqlx, GORM on a db/tx/conn value
+    /\.(Query|QueryRow|QueryContext|QueryRowContext|Exec|ExecContext)\s*\(|\b(db|tx|conn)\.(Get|Select|Find|First|Where)\s*\(|\brows\.Next\s*\(/,
+];
+/** A loop, and an await within the next few lines of it: one read per turn. */
+const LOOP = /\b(for|while)\b\s*[(\w]|\.(forEach|map|flatMap|reduce)\s*\(\s*async\b|\basync\s+for\b/;
+const AWAIT = /\bawait\b/;
+const LOOP_REACH = 3;
+const DEFINES = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|const|let|var|class|interface|type|enum|def|func)\s+(?:\([^)]*\)\s*)?([A-Za-z_$][\w$]*)/;
+const DECLARES = /^\s*(export\s|(async\s+)?function\s|def\s|func\s|class\s)/;
+const COMMENT = /^\s*(\/\/|#|\/\*|\*|<!--)/;
+const IDENTIFIER = /[A-Za-z_$][\w$]{2,}/g;
+/** The diff's hunks, each with its file header. */
+export function parseHunks(diff) {
+    const hunks = [];
+    for (const block of diff.split(/^(?=diff --git )/m)) {
+        const file = /^diff --git a\/.+? b\/(.+)$/m.exec(block)?.[1];
+        if (!file)
+            continue;
+        const headerEnd = block.search(/^@@/m);
+        const header = headerEnd >= 0 ? block.slice(0, headerEnd) : block;
+        const newFile = /^new file mode|^--- \/dev\/null$/m.test(header);
+        const bodies = headerEnd >= 0 ? block.slice(headerEnd).split(/^(?=@@)/m) : [];
+        for (const body of bodies) {
+            const lines = body.split('\n');
+            const added = lines.filter(l => l.startsWith('+') && !l.startsWith('+++')).map(l => l.slice(1));
+            const removed = lines.filter(l => l.startsWith('-') && !l.startsWith('---')).map(l => l.slice(1));
+            const defines = new Set(added.map(l => DEFINES.exec(l)?.[1]).filter((n) => !!n));
+            const references = new Set([...added, ...removed].flatMap(l => l.match(IDENTIFIER) ?? []));
+            hunks.push({ file, text: `${header}${body}`, added, removed, newFile, defines, references });
+        }
+    }
+    return hunks;
+}
+/** 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 function triage(hunks, context) {
+    const picked = new Map();
+    const pick = (id, index) => picked.set(id, [...(picked.get(id) ?? []), index]);
+    hunks.forEach((hunk, i) => {
+        if (skipped(hunk.file))
+            return;
+        const prose = PROSE.test(hunk.file);
+        const lines = [...hunk.added, ...hunk.removed];
+        if (!prose)
+            pick('correctness', i);
+        if (!prose && (MIGRATION.test(hunk.file) || READS.some(pattern => lines.some(line => pattern.test(line))) || awaitsInLoop(hunk.added)))
+            pick('production-cost', i);
+        if (!prose && (hunk.removed.length > 0 || hunk.newFile || hunk.added.some(l => DECLARES.test(l))))
+            pick('cleanup', i);
+        if (prose || hunk.added.some(l => COMMENT.test(l)) || context.rulesAndLessons > 0 || context.goal)
+            pick('rules-and-goal', i);
+    });
+    if (context.humanReviews > 0)
+        picked.set('prior-points', hunks.map((_, i) => i).filter(i => !skipped(hunks[i].file)));
+    return picked;
+}
+/** Whether no model reviews this file (SKIP). */
+export function skipped(file) {
+    return SKIP.some(pattern => pattern.test(file));
+}
+function awaitsInLoop(lines) {
+    return lines.some((line, i) => LOOP.test(line) && lines.slice(i, i + LOOP_REACH + 1).some(l => AWAIT.test(l)));
+}
+/**
+ * A pass's part of the diff: its hunks, and the hunk defining each name they use, in diff order. Only a name exactly one
+ * hunk defines is followed (a local `result` defined in ten files is no one definition), and a definition is added only
+ * while the part stays within `limit`.
+ */
+function sliceOf(hunks, definedIn, indices, limit) {
+    const chosen = new Set(indices);
+    let size = indices.reduce((sum, i) => sum + hunks[i].text.length, 0);
+    const referenced = new Set(indices.flatMap(i => [...hunks[i].references]));
+    for (const name of referenced) {
+        const at = definedIn.get(name);
+        if (at?.length !== 1 || chosen.has(at[0]) || size + hunks[at[0]].text.length > limit)
+            continue;
+        chosen.add(at[0]);
+        size += hunks[at[0]].text.length;
+    }
+    return [...chosen].sort((a, b) => a - b);
+}
+/**
+ * The passes for what triage picked. A split is by hunk, in diff order: each part takes the next hunks while they stay
+ * within `limit`, and runs every specialist that picked any of them. A single hunk over the limit is a part of its own.
+ * A change that needs more than MAX_PARTS parts is not split.
+ */
+export function planPasses(hunks, picked, order, limit) {
+    const ids = order.map(s => s.id).filter(id => picked.has(id));
+    if (ids.length === 0)
+        return {};
+    const definedIn = new Map();
+    hunks.forEach((hunk, i) => hunk.defines.forEach(name => definedIn.set(name, [...(definedIn.get(name) ?? []), i])));
+    const pickedBy = new Map(ids.map(id => [id, new Set(picked.get(id))]));
+    const pass = (indices) => {
+        const sliced = sliceOf(hunks, definedIn, indices, limit);
+        return { specialists: ids.filter(id => indices.some(i => pickedBy.get(id).has(i))), hunks: indices, sliced, diff: sliced.map(i => hunks[i].text).join('') };
+    };
+    const union = [...new Set(ids.flatMap(id => picked.get(id)))].sort((a, b) => a - b);
+    const combined = pass(union);
+    if (combined.diff.length <= limit || union.length === 1)
+        return { combined };
+    // By the hunks' own size: definitions join a part only within the limit (sliceOf), so they never push it over.
+    const parts = [[]];
+    let size = 0;
+    for (const index of union) {
+        const length = hunks[index].text.length;
+        if (parts.at(-1).length && size + length > limit) {
+            parts.push([]);
+            size = 0;
+        }
+        parts.at(-1).push(index);
+        size += length;
+    }
+    if (parts.length > MAX_PARTS)
+        return { combined, needsParts: parts.length };
+    return parts.length > 1 ? { combined, split: parts.map(pass) } : { combined };
+}
+/** Characters of the reviewable diff (no lockfiles or generated files) and its changed lines: both modes are measured on this. */
+export function reviewable(hunks) {
+    const kept = hunks.filter(h => !skipped(h.file));
+    return { chars: kept.reduce((sum, h) => sum + h.text.length, 0), lines: kept.reduce((sum, h) => sum + h.added.length + h.removed.length, 0) };
+}

package/dist/review/reviewer/usage.js

@@ -24,5 +24,19 @@ export function reviewerUsage(result, trigger) {
         dismissed: result.dismissed.length,
         runs: result.runs,
         cost_bucket: costBucket(result.costUsd),
+        ...orchestrated(mode?.specialists),
+    };
+}
+/** With the orchestrator: how many parts triage picked, how many passes ran, whether it split, fell back or had nothing to review, and how many passes read beyond their slice. */
+function orchestrated(specialists) {
+    if (!specialists)
+        return {};
+    return {
+        parts: specialists.selected.length,
+        passes: specialists.passes.length,
+        split: specialists.passes.length > 1,
+        fallback: !!specialists.fallback,
+        nothing_to_review: !!specialists.none,
+        beyond_slice: specialists.passes.filter(p => p.readBeyondSlice === true).length,
     };
 }

package/dist/review/reviewer/verdict.js

@@ -243,6 +243,17 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
     const notes = [];
     const advisory = [];
     const seen = new Set();
+    // Every item kept, by id: the same item from a second judge or specialist names it too instead of vanishing.
+    const kept = new Map();
+    const again = (item) => {
+        const first = kept.get(item.id);
+        if (first)
+            first.reviewer = bothReviewers(first.reviewer, item.reviewer);
+    };
+    const keep = (list, item) => {
+        list.push(item);
+        kept.set(item.id, item);
+    };
     // The reviewer's own label wins over the judge's reading of it: a judge that calls a blocker a should-fix would demote it silently.
     const read = verdict.prior_points.map(p => labelled(p, prior.labels ?? []));
     const points = read.map(r => r.point);
@@ -250,29 +261,29 @@ export function account(verdict, previousOpen, verify, prior = NO_PRIOR_CHECKS)
     // 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;
+            return void again(item);
         seen.add(item.id);
-        (!!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote) ? advisory : unverified).push(item);
+        keep(!!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote) ? advisory : unverified, 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.
     const add = (item) => {
         if (seen.has(item.id))
-            return;
+            return void again(item);
         seen.add(item.id);
         if (WORKING_NOTES.has(item.kind))
-            return void notes.push(item);
+            return void keep(notes, item);
         const placed = !!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote);
         if (!placed)
-            return void unverified.push(item);
+            return void keep(unverified, item);
         // A block is about this change. A finding or rule break in a touched file but on lines the change did not touch is
         // what the code already had: shown as a note, never a block on this change. A human's point is about the change by
         // definition. Without the diff (a judge's own items for a panel, a test) nothing is known and nothing is moved.
         if (item.kind !== 'prior' && prior.changed && (item.line === undefined || !nearChanged(prior.changed, item.file, item.line))) {
-            return void notes.push({ ...item, evidence: `${item.evidence ? `${item.evidence}; ` : ''}${item.line === undefined ? 'names no line' : 'on a line this change did not touch'}: what the code already had, never a block on this change` });
+            return void keep(notes, { ...item, evidence: `${item.evidence ? `${item.evidence}; ` : ''}${item.line === undefined ? 'names no line' : 'on a line this change did not touch'}: what the code already had, never a block on this change` });
         }
-        open.push(item);
+        keep(open, item);
     };
     const answerInReply = [];
     for (const p of points) {
@@ -441,11 +452,17 @@ function onePerRootCause(items) {
             kept.push(item);
             continue;
         }
+        same.reviewer = bothReviewers(same.reviewer, item.reviewer);
         if (item.file)
             (same.locations ??= []).push({ file: item.file, ...(item.line ? { line: item.line } : {}) });
     }
     return kept;
 }
+/** Who found an item, each once: `claude:correctness+claude:cleanup`, as the panel tags `claude+codex`. */
+function bothReviewers(a, b) {
+    const names = [...new Set([...(a ?? '').split('+'), ...(b ?? '').split('+')].filter(Boolean))];
+    return names.length ? names.join('+') : undefined;
+}
 export function itemLine(item) {
     const where = item.file ? ` ${item.file}${item.line ? `:${item.line}` : ''}` : '';
     const by = item.reviewer ? ` (${item.reviewer})` : '';

package/dist/review/reviewer.d.ts

@@ -35,6 +35,8 @@ export interface ReviewerOptions {
     branch?: string;
     /** This run's choice for the goal check (`--goal` / `--no-goal`), the nearest layer of switches.ts. */
     goal?: boolean;
+    /** This run's choice for the orchestrator (`--orchestrator` / `--no-orchestrator`), the nearest layer of switches.ts. */
+    orchestrator?: boolean;
 }
 export interface ReviewerResult {
     outcome: ReviewerOutcome;
@@ -64,6 +66,8 @@ export interface ReviewerResult {
     scope?: 'full' | 'delta';
     why?: string;
     costUsd?: number;
+    /** What every run of this fresh review reported costing, failed runs included: the number its cost row and its thread event carry. */
+    spentUsd?: number;
     /** The repository's own rules the judge answered, and how. */
     rules?: {
         checked: number;
@@ -92,9 +96,34 @@ export interface ReviewerResult {
     prTitle?: string;
 }
 export interface ModeRecord {
-    asked: 'single' | 'cross' | 'full' | 'panel';
+    asked: 'single' | 'cross' | 'full' | 'panel' | 'orchestrator';
     /** `none` when the review ended before any judge ran (unavailable or skipped); `degraded` or the reason says why. */
-    ran: 'single' | 'cross' | 'full' | 'panel' | 'none';
+    ran: 'single' | 'cross' | 'full' | 'panel' | 'orchestrator' | 'none';
+    /**
+     * With the orchestrator: the specialists triage picked, the passes that returned and those that did not (by label),
+     * each pass (its parts, its slice, whether it read beyond the slice: null without a trace), why the plan is what it
+     * is when the change was over the judge's limit or the caps, why it fell back to one judge if it did, and `none`
+     * when there was nothing for a model to review.
+     */
+    specialists?: {
+        selected: string[];
+        returned: string[];
+        missing: string[];
+        passes: Array<{
+            specialists: string[];
+            hunks: number;
+            chars: number;
+            readBeyondSlice: boolean | null;
+        }>;
+        /** The most diff one pass could be given, and the judge it came from (orchestrator.ts passLimit). */
+        limit: {
+            judge: ReviewerName;
+            chars: number;
+        };
+        plan?: string;
+        fallback?: string;
+        none?: string;
+    };
     source: Source;
     /** Why fewer judges ran than were asked for. */
     degraded?: string;

package/dist/review/reviewer.js

@@ -28,6 +28,8 @@ import { bodyAsOf, findPullRequest, ghFor, humanReviews, linesChanged, mergesBas
 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, triage } from './reviewer/triage.js';
 import { modelGoalItems, parseGoal } from '../goal/goal.js';
 import { resolveSwitch } from '../switches.js';
 import { resolveReviewer } from './reviewer/settings.js';
@@ -57,10 +59,13 @@ export async function runReviewer(cwd, base, config, exec = defaultExec, progres
     if (trigger !== 'backtest' && result.outcome !== 'skipped')
         appendTaskEvent(cwd, {
             kind: 'review', trigger, outcome: result.outcome, blocking: result.items.length, should_fix: result.advisory.length,
+            ...(options.checks ? { checks: options.checks.length } : {}),
             ...(result.pr ? { pr: result.pr } : {}),
             ...(result.prTitle ? { pr_title: result.prTitle } : {}),
             ...(result.lessonsApplied ? { lessons_applied: result.lessonsApplied } : {}),
-            ...(result.record ? { integrity: result.record.integrity, cost_usd: result.record.judges.reduce((sum, j) => sum + (j.cost_usd ?? 0), 0), judges: result.record.judges.map(j => j.reviewer) } : {}),
+            ...(result.record ? { integrity: result.record.integrity, judges: result.record.judges.map(j => j.reviewer) } : {}),
+            // Every run this review made, failed ones included: the same dollars as its cost row (the savings ledger).
+            ...(result.spentUsd !== undefined ? { cost_usd: result.spentUsd } : {}),
         });
     return result;
 }
@@ -110,6 +115,19 @@ async function review(cwd, base, config, exec, progress, options) {
     if (reviewers.length < 2 && mode === 'full' && (settings.required.panel || settings.required.mode)) {
         return none('unavailable', `rigour.yml requires two reviewers from different vendors, and ${modeRecord.degraded}`, { reviewers, mode: modeRecord });
     }
+    // The orchestrator runs the specialists on the first judge. A team floor on the panel or the mode wins over it.
+    const orchestrator = resolveSwitch('orchestrator', config, options.orchestrator);
+    let orchestrate = orchestrator.enabled;
+    if (orchestrator.refused.length)
+        modeRecord = { ...modeRecord, refused: [...(modeRecord.refused ?? []), ...orchestrator.refused] };
+    if (orchestrate && (settings.required.panel || settings.required.mode)) {
+        orchestrate = false;
+        modeRecord = { ...modeRecord, refused: [...(modeRecord.refused ?? []), 'orchestrator refused: rigour.yml requires the panel or the mode'] };
+    }
+    if (orchestrate) {
+        reviewers = reviewers.slice(0, 1);
+        modeRecord = { ...modeRecord, asked: 'orchestrator', ran: 'orchestrator', source: orchestrator.source };
+    }
     const gh = options.blind ? undefined : ghFor(cwd, exec, await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec));
     const found = gh ? await findPullRequest(gh, branch, head, options.pr) : {};
     if (found.error)
@@ -140,7 +158,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const goalText = goalItems.map(item => `- [${item.kind}] ${item.text}`).join('\n');
     const previous = branch !== 'HEAD' ? store.branchState(branch) : undefined;
     // The same commit, asked again with the same settings and reviews (the background run, then the person): the verdict it already has.
-    const inputsKey = sha([PROMPT_VERSION, rules, body, goalText, reviews.key, JSON.stringify([settings.mode, settings.panel, settings.judges, settings.escalate, settings.panel_max_items, settings.cross_models, settings.models, candidates]), [...installed].map(([n, i]) => `${n} ${i.version}`).join(';')]);
+    const inputsKey = sha([PROMPT_VERSION, rules, body, goalText, reviews.key, JSON.stringify([settings.mode, settings.panel, settings.judges, settings.escalate, settings.panel_max_items, settings.cross_models, settings.models, candidates, orchestrate ? SPECIALISTS_KEY : '']), [...installed].map(([n, i]) => `${n} ${i.version}`).join(';')]);
     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));
@@ -225,11 +243,66 @@ async function review(cwd, base, config, exec, progress, options) {
         const verdict = store.readJson(verdictFile);
         return withRecord(decide(verdict, previousOpen, verify, prior, 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);
+    // What one judge would be given: the shared input files and the reviewable diff. Both modes' cost rows measure this.
+    const hunks = parseHunks(fullDiff);
+    const size = reviewable(hunks);
+    const shared = reviews.markdown.length + body.length + context.text.length + (options.hints?.trim() || 'none\n').length + (goalText?.length ?? 0);
+    const projectedSingle = shared + size.chars;
+    // The orchestrator's plan: which specialists the change needs, hunk by hunk, as one combined pass. A change over the
+    // judge's limit is split by hunk only when the savings ledger covers the split's extra. Nothing to review: no pass.
+    const picked = orchestrate ? triage(hunks, { humanReviews: reviews.count, rulesAndLessons: context.rules.length + context.lessons, goal: goalItems.length > 0 }) : new Map();
+    const selected = SPECIALISTS.map(s => s.id).filter(id => picked.has(id));
+    let passes = [];
+    let planNote;
+    const limit = { judge: reviewers[0], chars: passLimit(reviewers[0], settings.timeout_ms) };
+    if (orchestrate) {
+        const baseline = store.freezeBaseline(BASELINE_MIN_SINGLES);
+        const plan = planPasses(hunks, picked, SPECIALISTS, limit.chars);
+        passes = plan.combined ? [plan.combined] : [];
+        if (plan.needsParts)
+            planNote = `over the judge's limit; needs ${plan.needsParts} parts > ${MAX_PARTS}: one pass`;
+        if (plan.split) {
+            const book = ledger(store.costs(), baseline);
+            const needs = splitNeeds(plan.split.reduce((sum, pass) => sum + shared + pass.diff.length, 0), projectedSingle, book.unit, baseline);
+            const said = `ledger ${formatLedger(book.credit, book.unit)}, split needs ${formatLedger(needs, book.unit)}`;
+            if (book.credit > 0 && book.credit >= needs) {
+                passes = plan.split;
+                planNote = `over the judge's limit; ${said}: ${plan.split.length} parts`;
+            }
+            else
+                planNote = `over the judge's limit; ${said}: one pass`;
+        }
+        // The daily caps, before any judge starts: room for one run but not every part is one combined pass.
+        if (passes.length > 1 && overBudget(store.spend(), settings, passes.length) && !overBudget(store.spend(), settings, 1)) {
+            planNote = `the caps leave one run, not ${passes.length}: one pass`;
+            passes = [plan.combined];
+        }
+    }
+    const over = orchestrate && passes.length === 0 ? undefined : overBudget(store.spend(), settings, orchestrate ? passes.length : reviewers.length);
+    // A team that requires the reviewer, or the orchestrator, gets no quieter review when the caps are reached: unavailable.
     if (over)
-        return none(settings.required.panel || settings.required.mode ? 'unavailable' : 'skipped', over, { reviewers, scope, why, pr: pr?.number });
+        return none(settings.required.panel || settings.required.mode || orchestrator.required ? 'unavailable' : 'skipped', over, { reviewers, scope, why, pr: pr?.number });
     const work = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-reviewer-'));
+    // Every run this review makes, failed ones included: the caps count each, and the review's cost row sums them.
+    const tally = { runs: 0, chars: 0, usd: 0 };
+    const spent = (usd, chars) => {
+        store.addSpend(1, usd);
+        tally.runs++;
+        tally.chars += chars;
+        tally.usd += usd ?? 0;
+    };
+    const spentUsd = () => Math.round(tally.usd * 10_000) / 10_000;
+    // One row per fresh review, for the savings ledger: one judge asked for and run, or orchestrated with everything it ran.
+    const recordReviewCost = () => {
+        const orchestrated = modeRecord.asked === 'orchestrator';
+        if (!orchestrated && !(modeRecord.asked === 'single' && modeRecord.ran === 'single'))
+            return;
+        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,
+        });
+    };
     // 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'
@@ -274,43 +347,102 @@ async function review(cwd, base, config, exec, progress, options) {
         const ticker = setInterval(() => progress(`Rigour reviewer: still working (${Math.round((Date.now() - started) / 60_000)} min)`), PROGRESS_EVERY_MS);
         let parts;
         try {
-            const answers = await Promise.all(reviewers.map(async (name) => {
-                const adapter = ADAPTERS[name];
-                const ask = async () => {
-                    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
-                    return { run, answer, verdict: run.exitCode === 0 || answer.text.trim() ? parseVerdict(answer.text, needsPriorPoints, name, answer) : undefined };
-                };
-                let first = await ask();
-                // 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();
+            // The single-judge fallback runs once: no retry, no spare judge.
+            let once = false;
+            if (orchestrate && passes.length === 0) {
+                // Nothing for a model to review (only lockfiles, generated files): no run, and that is the verdict.
+                parts = [];
+                modeRecord = { ...modeRecord, specialists: { selected: [], returned: [], missing: [], passes: [], limit, none: 'nothing for the model reviewer to review' } };
+            }
+            else if (orchestrate) {
+                const judge = reviewers[0];
+                const ran = [];
+                const run = await runPasses(judge, passes.map((pass, i) => ({ ...pass, file: file(`part-${i + 1}.diff`, pass.diff) })), async (pass) => {
+                    const assigned = pass.specialists.map(id => SPECIALISTS.find(s => s.id === id));
+                    const result = await runJudge(judge, `${prompt}${focusBlock(assigned, pass.file)}`, modelFor(judge));
+                    const answer = ADAPTERS[judge].answer(result.stdout);
+                    spent(answer.costUsd, shared + pass.diff.length); // every pass counts against the caps and the ledger, an answer or not
+                    progress(`Rigour reviewer: ${judge} (${pass.specialists.join(', ')}) finished in ${Math.round((Date.now() - started) / 1000)}s (exit ${result.exitCode})`);
+                    const verdict = result.exitCode === 0 || answer.text.trim()
+                        ? parseVerdict(answer.text, needsPriorPoints && pass.specialists.includes('prior-points'), judge, answer)
+                        : { error: `${judge} (${pass.specialists.join(', ')}): no answer (exit ${result.exitCode})` };
+                    // Whether slicing held: a pass that read the full diff, or read, searched or printed a changed file outside its slice.
+                    const sliceFiles = new Set(pass.sliced.map(i => hunks[i].file));
+                    const outside = changedFiles.filter(f => !sliceFiles.has(f));
+                    const trace = 'verdict' in verdict ? verdict.verdict.trace : undefined;
+                    const beyond = trace ? trace.calls.some(c => {
+                        const target = c.target.replace(/\\/g, '/');
+                        return target.endsWith('/full.diff') || outside.some(f => names(target, f));
+                    }) : null;
+                    ran.push({ specialists: pass.specialists, hunks: pass.hunks.length, chars: pass.diff.length, readBeyondSlice: beyond });
+                    return verdict;
+                });
+                const specialists = { selected, returned: run.returned, missing: run.missing, passes: ran, limit, ...(planNote ? { plan: planNote } : {}) };
+                if (orchestrator.required && run.missing.length) {
+                    // A required orchestrator reviews every part or gives no verdict: a partial review, or one judge instead, is a quieter one.
+                    recordReviewCost();
+                    const fallback = `${run.returned.length} of ${passes.length} passes returned`;
+                    return none('unavailable', `${fallback}, and rigour.yml requires the orchestrator: every part or no verdict (not reviewed: ${run.missing.join('; ')})`, { reviewers, scope, why, pr: pr?.number, spentUsd: spentUsd(), mode: { ...modeRecord, specialists: { ...specialists, fallback } } });
                 }
-                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)}` };
+                if (run.stands) {
+                    parts = run.parts;
+                    modeRecord = { ...modeRecord, specialists, ...(run.missing.length ? { degraded: `${modeRecord.degraded ? `${modeRecord.degraded}; ` : ''}not reviewed: ${run.missing.join('; ')} (no verdict)` } : {}) };
+                }
+                else {
+                    // Fewer than half of the passes came back: one judge instead, once, only if the caps still allow a run; it counts too.
+                    const short = overBudget(store.spend(), settings, 1);
+                    const fallback = `${run.returned.length} of ${passes.length} passes returned`;
+                    if (short) {
+                        recordReviewCost();
+                        return none('unavailable', `${fallback}, and the caps leave no run for one judge: ${short}`, { reviewers, scope, why, pr: pr?.number, spentUsd: spentUsd(), mode: { ...modeRecord, specialists: { ...specialists, fallback } } });
+                    }
+                    progress(`Rigour reviewer: ${fallback}; one judge reviews instead`);
+                    modeRecord = { ...modeRecord, ran: 'single', specialists: { ...specialists, fallback } };
+                    once = true;
                 }
-                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 });
-            parts = answers.map(a => a.verdict);
+            if (!parts) {
+                const answers = await Promise.all(reviewers.map(async (name) => {
+                    const adapter = ADAPTERS[name];
+                    const ask = async () => {
+                        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);
+                        spent(answer.costUsd, projectedSingle); // every run counts against the caps, an answer or not
+                        return { run, answer, verdict: run.exitCode === 0 || answer.text.trim() ? parseVerdict(answer.text, needsPriorPoints, name, answer) : undefined };
+                    };
+                    let first = await ask();
+                    // 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`);
+                        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 (!once && '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);
+                        spent(got.costUsd, projectedSingle);
+                        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) {
+                    if (once)
+                        recordReviewCost();
+                    return none('unavailable', failed.error, { reviewers, scope, why, pr: pr?.number, spentUsd: spentUsd() });
+                }
+                parts = answers.map(a => a.verdict);
+            }
             for (const part of parts) {
                 if (part.trace)
                     labelReads(part.trace, work, changedFiles);
@@ -320,7 +452,8 @@ async function review(cwd, base, config, exec, progress, options) {
         finally {
             clearInterval(ticker);
         }
-        const merged = mergeVerdicts(parts); // one part too: every item is tagged with who found it
+        // One part too: every item is tagged with who found it. No part (nothing for a model to review): an empty verdict.
+        const merged = parts.length ? mergeVerdicts(parts) : { prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [], carried: [], resolved_previous: [], reviewers: [] };
         const touched = scope === 'delta' ? sincePrevious : new Set();
         let verdict = scope === 'delta' ? carryResolved(merged, store.readJson(previous.verdict), touched) : merged;
         if (modeRecord.ran === 'panel' && parts.length > 1) {
@@ -347,9 +480,10 @@ async function review(cwd, base, config, exec, progress, options) {
                 },
                 ask: async (judge, asked) => {
                     const name = judge;
-                    const run = await runJudge(name, crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked), settings.cross_models[name] ?? modelFor(name));
+                    const examPrompt = crossExamPrompt(repoRoot, head.slice(0, 9), diffFile, asked);
+                    const run = await runJudge(name, examPrompt, settings.cross_models[name] ?? modelFor(name));
                     const answer = ADAPTERS[name].answer(run.stdout);
-                    store.addSpend(1, answer.costUsd);
+                    spent(answer.costUsd, examPrompt.length);
                     reserved--;
                     cross.push({ reviewer: `${name} cross-exam`, ...(answer.costUsd !== undefined ? { cost_usd: answer.costUsd } : {}), ...(answer.tokens ? { tokens: answer.tokens } : {}) });
                     progress(`Rigour reviewer: ${name} cross-examined ${asked.length} finding(s) (exit ${run.exitCode})`);
@@ -365,9 +499,10 @@ async function review(cwd, base, config, exec, progress, options) {
         store.writeJson(verdictFile, { ...verdict, inputs: { head, base: baseSha, scope, why, mode: modeRecord, reviewers, versions: reviewerVersions, authors: [...authors], fingerprint, human_reviews: reviews.count, reviews_before: options.reviewsBefore ?? null, since: previous?.head ?? null, at: new Date().toISOString() } });
         store.writeJson(openFile, accounted.open);
         store.writeJson(store.decidedPath(verdictFile), accounted);
+        recordReviewCost();
         if (branch !== 'HEAD')
             store.recordBranch(branch, { head, verdict: verdictFile, mode: scope, rulesHash, reviewsKey: reviews.key, inputsKey });
-        return withRecord(accounted, verdict, false);
+        return { ...withRecord(accounted, verdict, false), spentUsd: spentUsd() };
     }
     finally {
         fs.rmSync(work, { recursive: true, force: true });
@@ -491,3 +626,12 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         ...(pr?.title ? { prTitle: pr.title } : {}),
     };
 }
+/** Whether a tool call's target (a path, a glob, a shell command) names a repository file. */
+function names(target, file) {
+    const at = target.indexOf(file);
+    if (at < 0)
+        return false;
+    const before = target[at - 1];
+    const after = target[at + file.length];
+    return (before === undefined || /[\s/'"=]/.test(before)) && (after === undefined || /[\s'":)]/.test(after));
+}

package/dist/settings.d.ts

@@ -34,6 +34,7 @@ export interface RigourSettings {
     reviewer?: UserReviewerSettings;
     goal?: boolean;
     outcomes?: boolean;
+    orchestrator?: boolean;
     cursor?: {
         apiKey?: string;
     };