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

package/dist/index.d.ts

@@ -20,7 +20,8 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSpli
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH, type Ledger, type RoundResult } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
 export type { CiResult, FollowUp, PrOutcome } from './outcomes/outcome.js';
-export { runOutcomes, type OutcomesRun } from './outcomes/run.js';
+export { localOutcomeMetrics, runOutcomes, type OutcomesRun } from './outcomes/run.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';
 export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
@@ -46,7 +47,7 @@ export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsRe
 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';
-export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';

package/dist/index.js

@@ -19,7 +19,7 @@ export { isControlFile, mergeBaseOf, readStateFile } from './review/trusted-stat
 export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSplit, DISMISSED_FILE } from './review/quiet.js';
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
-export { runOutcomes } from './outcomes/run.js';
+export { localOutcomeMetrics, runOutcomes } from './outcomes/run.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';
@@ -45,7 +45,7 @@ export { learnFromReviews } from './review-learning/learn-from-reviews.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';
-export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';

package/dist/outcomes/metrics.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The outcome loop's numbers: the one place they are counted (Studio, `rigour outcomes --json` and telemetry read this,
+ * never their own count). The shape is versioned and documented in docs/OUTCOMES.md, "Numbers".
+ *
+ * Counts only, over what this machine read. A rate is given only when at least MIN_FOR_RATE records are behind it;
+ * below that it is null with the reason. Pull requests a review by Rigour saw and pull requests it did not are counted
+ * side by side and never compared: teams choose which pull requests get reviewed, so the two groups differ, and a gap
+ * between them is not Rigour's effect.
+ */
+import type { ReviewLesson } from '../review-learning/lessons.js';
+import type { PrOutcome } from './outcome.js';
+export interface Share {
+    count: number;
+    of: number;
+    /** count / of, two decimals; null when `of` is under MIN_FOR_RATE. */
+    rate: number | null;
+    reason?: string;
+}
+export interface OutcomeMetrics {
+    version: 1;
+    records: {
+        merged: number;
+        settled: number;
+        unsettled: number;
+    };
+    /** Over settled records only: an open window can still change. */
+    settled: {
+        /** Over settled records whose CI result is known (passed or failed): one with no CI to read never dilutes it. */
+        ciRegressed: Share;
+        /** Settled records with no CI result to read. */
+        ciUnknown: number;
+        reverted: Share;
+        /** A later commit on its files, inside the window, that says it fixes something. */
+        fixedLater: Share;
+        /** Side by side, never compared (see above). */
+        reviewed: {
+            prs: number;
+            fixedLater: Share;
+        };
+        notReviewed: {
+            prs: number;
+            fixedLater: Share;
+        };
+    };
+    /** What the model reviewer added on the settled pull requests a review by Rigour ran on. */
+    model: {
+        /**
+         * The model's findings (blocking and should-fix) out of all findings, the deterministic checks' included, at
+         * each pull request's first review that recorded both: before the review's own points changed the code. Rate
+         * only from MIN_FOR_RATE such pull requests.
+         */
+        share: {
+            model: number;
+            checks: number;
+            prs: number;
+            rate: number | null;
+            reason?: string;
+        };
+        /** Dollars of every review round on a pull request, summed per pull request. Median only from MIN_FOR_RATE. */
+        costPerPr: {
+            prs: number;
+            totalUsd: number;
+            medianUsd: number | null;
+            reason?: string;
+        };
+    };
+    lessons: {
+        /** Candidates waiting on a person: a later fix on their lines, back to candidate, or taken back. */
+        awaitingDecision: number;
+        /** Promoted by a person after such evidence. */
+        promotedFromEvidence: number;
+        dismissed: number;
+        /** Taken back by evidence and not promoted again since. */
+        takenBack: number;
+    };
+}
+/** One pull request's reviews by Rigour, from the threads' review events, oldest first. */
+export interface PrReviews {
+    /** The first review that recorded the deterministic checks' count: the model's findings and the checks' then. */
+    first?: {
+        model: number;
+        checks: number;
+    };
+    /** Every review round's dollars, summed. */
+    usd: number;
+}
+/** `reviewed`: the pull requests a review by Rigour ran on, each with its reviews (the threads' review events). */
+export declare function outcomeMetrics(records: PrOutcome[], lessons: ReviewLesson[], reviewed: Map<number, PrReviews>): OutcomeMetrics;

package/dist/outcomes/metrics.js

@@ -0,0 +1,56 @@
+import { pendingDecision } from '../review-learning/lessons.js';
+/** Fewer records than this give a count, never a percentage. */
+const MIN_FOR_RATE = 10;
+/** `reviewed`: the pull requests a review by Rigour ran on, each with its reviews (the threads' review events). */
+export function outcomeMetrics(records, lessons, reviewed) {
+    const settled = records.filter(r => r.settled);
+    const fixed = (r) => r.followUps.some(f => f.fix);
+    const inReview = settled.filter(r => reviewed.has(r.pr));
+    const notInReview = settled.filter(r => !reviewed.has(r.pr));
+    return {
+        version: 1,
+        records: { merged: records.length, settled: settled.length, unsettled: records.length - settled.length },
+        settled: {
+            ciRegressed: share(settled.filter(r => r.ci === 'failure').length, settled.filter(r => r.ci === 'success' || r.ci === 'failure').length),
+            ciUnknown: settled.filter(r => r.ci !== 'success' && r.ci !== 'failure').length,
+            reverted: share(settled.filter(r => !!r.reverted).length, settled.length),
+            fixedLater: share(settled.filter(fixed).length, settled.length),
+            reviewed: { prs: inReview.length, fixedLater: share(inReview.filter(fixed).length, inReview.length) },
+            notReviewed: { prs: notInReview.length, fixedLater: share(notInReview.filter(fixed).length, notInReview.length) },
+        },
+        model: modelNumbers(inReview.map(r => reviewed.get(r.pr)).filter((x) => !!x)),
+        lessons: {
+            awaitingDecision: lessons.filter(l => pendingDecision(l)).length,
+            promotedFromEvidence: lessons.filter(promotedAfterEvidence).length,
+            dismissed: lessons.filter(l => l.evidence.some(e => e.kind === 'dismissed')).length,
+            takenBack: lessons.filter(l => pendingDecision(l)?.kind === 'demoted').length,
+        },
+    };
+}
+function modelNumbers(prs) {
+    const firsts = prs.flatMap(p => p.first ? [p.first] : []);
+    const model = firsts.reduce((n, f) => n + f.model, 0);
+    const checks = firsts.reduce((n, f) => n + f.checks, 0);
+    const few = (n) => n < MIN_FOR_RATE ? { reason: `fewer than ${MIN_FOR_RATE} pull requests: a count, not a rate` } : {};
+    const usd = prs.map(p => p.usd).sort((a, b) => a - b);
+    const mid = usd.length >> 1;
+    return {
+        share: { model, checks, prs: firsts.length, rate: firsts.length >= MIN_FOR_RATE && model + checks > 0 ? Math.round((model / (model + checks)) * 100) / 100 : null, ...few(firsts.length) },
+        costPerPr: {
+            prs: usd.length,
+            totalUsd: Math.round(usd.reduce((a, b) => a + b, 0) * 100) / 100,
+            medianUsd: usd.length >= MIN_FOR_RATE ? Math.round((usd.length % 2 ? usd[mid] : (usd[mid - 1] + usd[mid]) / 2) * 100) / 100 : null,
+            ...few(usd.length),
+        },
+    };
+}
+function share(count, of) {
+    return of >= MIN_FOR_RATE
+        ? { count, of, rate: Math.round((count / of) * 100) / 100 }
+        : { count, of, rate: null, reason: `fewer than ${MIN_FOR_RATE} records: a count, not a rate` };
+}
+/** A person's promotion that came after a later fix on its lines, a reclassification or a take-back. */
+function promotedAfterEvidence(lesson) {
+    const evidenceAt = lesson.evidence.findIndex(e => e.kind === 'lines' || e.kind === 'reclassified' || e.kind === 'demoted');
+    return evidenceAt >= 0 && lesson.evidence.slice(evidenceAt + 1).some(e => e.kind === 'accepted') && lesson.state === 'verified';
+}

package/dist/outcomes/run.d.ts

@@ -8,6 +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';
 export interface OutcomesRun {
     switch: ResolvedSwitch;
     outcomes: PrOutcome[];
@@ -17,6 +18,8 @@ export interface OutcomesRun {
     stopped?: string;
     /** What the records did to the team's review lessons (review-learning/outcome-evidence.ts). */
     lessons?: OutcomeEvidenceResult;
+    /** The outcome numbers over every record kept (metrics.ts). */
+    metrics?: OutcomeMetrics;
 }
 export declare function runOutcomes(cwd: string, config: Config, options: {
     flag?: boolean;
@@ -24,3 +27,5 @@ export declare function runOutcomes(cwd: string, config: Config, options: {
     last?: number;
     exec?: Exec;
 }): Promise<OutcomesRun>;
+/** 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

@@ -7,6 +7,7 @@ import { applyOutcomeEvidence } from '../review-learning/outcome-evidence.js';
 import { readLessons, writeLessons } from '../review-learning/lessons.js';
 import { gitIn } from '../review-learning/acted-on.js';
 import { eventsOfKind } from '../task/thread.js';
+import { outcomeMetrics } from './metrics.js';
 /** How long one run may read before it stops and keeps what it has. */
 const READ_DEADLINE_MS = 2 * 60_000;
 /** How long one run may follow points' lines through history; the next run carries on. */
@@ -30,16 +31,33 @@ export async function runOutcomes(cwd, config, options) {
     const incomplete = listed.incomplete ? 'the list of merged pull requests may be incomplete (gh listed too many updates to prove it)' : undefined;
     const stopped = [run.stopped, incomplete].filter(Boolean).join('; ');
     const lessons = lessonEvidence(cwd, mainRef, config.learning?.outcomes?.demote_after ?? 2);
-    return { switch: resolved, outcomes: run.outcomes, read: run.read, ...(lessons ? { lessons } : {}), ...(stopped ? { stopped } : {}) };
+    const metrics = localOutcomeMetrics(cwd);
+    return { switch: resolved, outcomes: run.outcomes, read: run.read, ...(lessons ? { lessons } : {}), ...(metrics ? { metrics } : {}), ...(stopped ? { stopped } : {}) };
 }
 /** Every record kept (not only this run's) against the team's lessons, and the reviews that found a lesson repeated; written only when something changed. */
 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 });
+    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) {
     const applied = new Map();
+    const reviewed = new Map();
+    const count = (v) => typeof v === 'number' ? v : 0;
     for (const e of eventsOfKind(cwd, 'review')) {
-        if (typeof e.pr !== 'number' || !Array.isArray(e.lessons_applied))
+        if (typeof e.pr !== 'number')
+            continue;
+        const pr = reviewed.get(e.pr) ?? { usd: 0 };
+        pr.usd += count(e.cost_usd);
+        if (!pr.first && typeof e.checks === 'number')
+            pr.first = { model: count(e.blocking) + count(e.should_fix), checks: e.checks };
+        reviewed.set(e.pr, pr);
+        if (!Array.isArray(e.lessons_applied))
             continue;
         const ids = applied.get(e.pr) ?? new Set();
         for (const id of e.lessons_applied)
@@ -47,10 +65,12 @@ function lessonEvidence(cwd, mainRef, demoteAfter) {
                 ids.add(id);
         applied.set(e.pr, ids);
     }
-    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), applied, { demoteAfter, git: gitIn(cwd), mainRef, deadline: Date.now() + LESSON_DEADLINE_MS });
-    if (result.added)
-        writeLessons(cwd, lessons);
-    return result;
+    return { applied, reviewed };
+}
+/** 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;
 }
 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/reviewer/orchestrator.d.ts

@@ -0,0 +1,51 @@
+import type { ReviewerName } from './adapters.js';
+import type { CostBaseline, ReviewCost } from './store.js';
+import type { Verdict } from './verdict.js';
+export interface Specialist {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+}
+/** The set is fixed in v1: not configurable, so a backtest and a measurement can pin it. */
+export declare const SPECIALISTS: readonly Specialist[];
+/** What changes the orchestrated prompt: part of the verdict's fingerprint, so a single review's verdict is never reused for it. */
+export declare const SPECIALISTS_KEY: string;
+/** The block a pass's prompt ends with: its parts of the review and its slice of the diff; the rest is not its to report. */
+export declare function focusBlock(parts: Specialist[], sliceFile: string): string;
+export interface OrchestratedRun {
+    /** The passes' verdicts that came back, each tagged `<judge>:<specialist,specialist>`. */
+    parts: Verdict[];
+    /** The passes that returned and those that did not, by label (`correctness, cleanup`, or `part 2: correctness`). */
+    returned: string[];
+    missing: string[];
+    /** At least half of the passes returned: the result stands, partial when some are missing. */
+    stands: boolean;
+}
+/** Runs every planned pass at once through `ask` (one judge run each, counted by the caller) and keeps what came back. */
+export declare function runPasses<P extends {
+    specialists: string[];
+}>(judge: string, passes: P[], ask: (pass: P) => Promise<{
+    verdict: Verdict;
+} | {
+    error: string;
+}>): Promise<OrchestratedRun>;
+/** Single reviews the frozen baseline needs before it prices a character in dollars; with fewer, the ledger counts characters. */
+export declare const BASELINE_MIN_SINGLES = 5;
+export interface Ledger {
+    credit: number;
+    unit: 'usd' | 'chars';
+}
+/**
+ * The savings ledger: over the last LEDGER_WINDOW orchestrated reviews, what one judge would have been given minus what
+ * every run was given. In dollars when the frozen baseline prices a character (a run that reported dollars counts
+ * them, one that did not is priced at the baseline); otherwise in characters.
+ */
+export declare function ledger(costs: ReviewCost[], baseline: CostBaseline | undefined): Ledger;
+/** What a split needs from the ledger: its projected size minus one pass's (shared inputs + the reviewable diff), in the ledger's unit. */
+export declare function splitNeeds(splitChars: number, singleChars: number, unit: Ledger['unit'], baseline: CostBaseline | undefined): number;
+export declare function formatLedger(amount: number, unit: Ledger['unit']): string;
+/** The most diff one pass is given, from the judge's context window and its timeout. */
+export declare function passLimit(judge: ReviewerName, timeoutMs: number): number;

package/dist/review/reviewer/orchestrator.js

@@ -0,0 +1,96 @@
+/**
+ * The review orchestrator (opt-in, experimental): a router, not a fan-out. Triage (triage.ts) picks, without a model,
+ * which of a fixed set of specialists a change needs, hunk by hunk; they run as ONE combined pass at every size, split
+ * only when one pass would not fit the judge. The prompt and its input files are built once for the review; a pass adds
+ * only its focus block and its slice of the diff. Verdicts merge through the reviewer's own accounting, so the evidence
+ * contract, the quote check and what blocks are unchanged; an item two passes both raise is one item naming both.
+ *
+ * Fails safe: a pass with no verdict is named as not reviewed, never "passed". With at least half of the passes back
+ * the result stands; with fewer, the caller falls back to one judge, once, if the caps allow it, else the review is
+ * unavailable. A change with nothing for a model to review gets no pass.
+ *
+ * Cost: a split always costs more than one pass for that review (each pass re-reads the shared inputs), so a split
+ * spends only what the router already saved. The savings ledger is, over the last LEDGER_WINDOW orchestrated reviews,
+ * what one judge would have been given minus what every run was given. A change over the judge's limit is split by
+ * hunk only when the ledger covers the split's extra; an empty ledger (no history) never splits.
+ */
+import { createHash } from 'crypto';
+import { CLEANUP_V1 } from './specialists/cleanup.v1.js';
+import { CORRECTNESS_V1 } from './specialists/correctness.v1.js';
+import { PRIOR_POINTS_V1 } from './specialists/prior-points.v1.js';
+import { PRODUCTION_COST_V1 } from './specialists/production-cost.v1.js';
+import { RULES_AND_GOAL_V1 } from './specialists/rules-and-goal.v1.js';
+/** The set is fixed in v1: not configurable, so a backtest and a measurement can pin it. */
+export const SPECIALISTS = [PRIOR_POINTS_V1, CORRECTNESS_V1, PRODUCTION_COST_V1, CLEANUP_V1, RULES_AND_GOAL_V1];
+/** What changes the orchestrated prompt: part of the verdict's fingerprint, so a single review's verdict is never reused for it. */
+export const SPECIALISTS_KEY = createHash('sha256').update(JSON.stringify(SPECIALISTS)).digest('hex').slice(0, 12);
+/** The block a pass's prompt ends with: its parts of the review and its slice of the diff; the rest is not its to report. */
+export function focusBlock(parts, sliceFile) {
+    const steps = [...new Set(parts.flatMap(p => p.steps))].sort((a, b) => a - b);
+    const classes = [...new Set(parts.flatMap(p => p.classes))];
+    const priorPoints = parts.some(p => p.id === 'prior-points');
+    return `
+
+This review is split by part, and you do these: ${parts.map(p => p.title).join('; ')}. Your part of the diff is in
+${sliceFile} (the hunks for these parts, and the hunks defining what they use); read the full diff only where a line of
+yours needs it. Do step(s) ${steps.join(', ')} above, fully.${classes.length ? ` Report findings only of class ${classes.join(', ')}.` : ''}${priorPoints ? '' : ' Leave prior_points empty.'}
+${parts.map(p => p.focus).join(' ')} Leave every list in the JSON that is not your part empty ([]).`;
+}
+/** A pass's name in the record: its specialists, and its part when the change was split. */
+function passLabel(specialists, index, of) {
+    return of > 1 ? `part ${index + 1}: ${specialists.join(', ')}` : specialists.join(', ');
+}
+/** Runs every planned pass at once through `ask` (one judge run each, counted by the caller) and keeps what came back. */
+export async function runPasses(judge, passes, ask) {
+    const answers = await Promise.all(passes.map(async (pass) => ({ pass, answer: await ask(pass) })));
+    const parts = [];
+    const returned = [];
+    const missing = [];
+    answers.forEach(({ pass, answer }, i) => {
+        const label = passLabel(pass.specialists, i, passes.length);
+        if ('verdict' in answer) {
+            parts.push({ ...answer.verdict, reviewer: `${judge}:${pass.specialists.join(',')}` });
+            returned.push(label);
+        }
+        else
+            missing.push(label);
+    });
+    return { parts, returned, missing, stands: returned.length * 2 >= passes.length };
+}
+/** How many recent orchestrated reviews the savings ledger sums: older savings never fund a split. */
+const LEDGER_WINDOW = 20;
+/** Single reviews the frozen baseline needs before it prices a character in dollars; with fewer, the ledger counts characters. */
+export const BASELINE_MIN_SINGLES = 5;
+/**
+ * The savings ledger: over the last LEDGER_WINDOW orchestrated reviews, what one judge would have been given minus what
+ * every run was given. In dollars when the frozen baseline prices a character (a run that reported dollars counts
+ * them, one that did not is priced at the baseline); otherwise in characters.
+ */
+export function ledger(costs, baseline) {
+    const rate = baseline?.usdPerChar ?? null;
+    const recent = costs.filter(c => c.mode === 'orchestrator').slice(-LEDGER_WINDOW);
+    if (rate === null)
+        return { credit: recent.reduce((sum, c) => sum + c.projectedSingleChars - c.actualChars, 0), unit: 'chars' };
+    return { credit: recent.reduce((sum, c) => sum + c.projectedSingleChars * rate - (c.actualUsd > 0 ? c.actualUsd : c.actualChars * rate), 0), unit: 'usd' };
+}
+/** What a split needs from the ledger: its projected size minus one pass's (shared inputs + the reviewable diff), in the ledger's unit. */
+export function splitNeeds(splitChars, singleChars, unit, baseline) {
+    const extra = splitChars - singleChars;
+    return unit === 'usd' ? extra * baseline.usdPerChar : extra;
+}
+export function formatLedger(amount, unit) {
+    return unit === 'usd' ? `$${amount.toFixed(2)}` : `${Math.round(amount)} chars`;
+}
+/**
+ * Each judge's context window, in tokens: the defaults its CLI or API runs with. Unverified against every model a team
+ * may pick; a pass is held to half of it, so the prompt, the reads and the answer fit beside the diff.
+ */
+const CONTEXT_TOKENS = { claude: 200_000, codex: 200_000, cursor: 200_000, api: 128_000 };
+const CHARS_PER_TOKEN = 4;
+const DIFF_SHARE_OF_CONTEXT = 0.5;
+/** Diff a judge can read and reason over per second of its timeout: past this, the run times out before it answers. */
+const DIFF_CHARS_PER_SECOND = 500;
+/** The most diff one pass is given, from the judge's context window and its timeout. */
+export function passLimit(judge, timeoutMs) {
+    return Math.floor(Math.min(CONTEXT_TOKENS[judge] * CHARS_PER_TOKEN * DIFF_SHARE_OF_CONTEXT, (timeoutMs / 1000) * DIFF_CHARS_PER_SECOND));
+}

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: {}, 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: {}, judge_env: {}, reasoning: {} };
     const refused = [];
     const envMode = parseMode(env.RIGOUR_REVIEWER_MODE);
     const envPanel = parseSwitch(env.RIGOUR_REVIEWER_PANEL);

package/dist/review/reviewer/specialists/cleanup.v1.d.ts

@@ -0,0 +1,9 @@
+/** Specialist v1: what the change leaves behind (prompt step 2 and the dead-code, duplication and helper-bypass parts of 11). */
+export declare const CLEANUP_V1: {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+};

package/dist/review/reviewer/specialists/cleanup.v1.js

@@ -0,0 +1,9 @@
+/** Specialist v1: what the change leaves behind (prompt step 2 and the dead-code, duplication and helper-bypass parts of 11). */
+export const CLEANUP_V1 = {
+    id: 'cleanup',
+    version: 1,
+    title: 'what the change leaves behind: redundancy, dead code, duplication, helpers bypassed',
+    steps: [2, 11],
+    classes: ['dead-code', 'duplication', 'helper-bypass'],
+    focus: 'Find what a fix made unnecessary and whether it was removed, exports nothing consumes (a test is not a consumer), code copied across sibling routes or runners, and links or ids built outside the helper that owns them. Report only those classes.',
+};

package/dist/review/reviewer/specialists/correctness.v1.d.ts

@@ -0,0 +1,9 @@
+/** Specialist v1: correctness past the request (prompt steps 5, 6, 7 and the correctness part of 11). */
+export declare const CORRECTNESS_V1: {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+};

package/dist/review/reviewer/specialists/correctness.v1.js

@@ -0,0 +1,9 @@
+/** Specialist v1: correctness past the request (prompt steps 5, 6, 7 and the correctness part of 11). */
+export const CORRECTNESS_V1 = {
+    id: 'correctness',
+    version: 1,
+    title: 'correctness: merge impact, the journey past the request, sibling parity',
+    steps: [5, 6, 7, 11],
+    classes: ['correctness'],
+    focus: 'Trace what the change does to state that outlives the request: retries, two runs at once, statuses that can move back, keys that change on edit, and every sibling that needs the same change. Report only correctness findings.',
+};

package/dist/review/reviewer/specialists/prior-points.v1.d.ts

@@ -0,0 +1,9 @@
+/** Specialist v1: every earlier human review point (prompt step 1). A new version is a new file; the record names the version. */
+export declare const PRIOR_POINTS_V1: {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+};

package/dist/review/reviewer/specialists/prior-points.v1.js

@@ -0,0 +1,9 @@
+/** Specialist v1: every earlier human review point (prompt step 1). A new version is a new file; the record names the version. */
+export const PRIOR_POINTS_V1 = {
+    id: 'prior-points',
+    version: 1,
+    title: 'earlier human review points',
+    steps: [1],
+    classes: [],
+    focus: 'Judge every point of every human review as step 1 asks, siblings included. Report findings only when a point is unresolved and you can show it; leave every other list empty.',
+};

package/dist/review/reviewer/specialists/production-cost.v1.d.ts

@@ -0,0 +1,9 @@
+/** Specialist v1: production cost (prompt steps 3, 4 and the production-cost part of 11). */
+export declare const PRODUCTION_COST_V1: {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+};

package/dist/review/reviewer/specialists/production-cost.v1.js

@@ -0,0 +1,9 @@
+/** Specialist v1: production cost (prompt steps 3, 4 and the production-cost part of 11). */
+export const PRODUCTION_COST_V1 = {
+    id: 'production-cost',
+    version: 1,
+    title: 'production cost: every read and every nested scan',
+    steps: [3, 4, 11],
+    classes: ['production-cost'],
+    focus: 'Trace every read the change adds or alters: rules known before it, a narrower source, bounded windows, keyset paging, the index that serves it, and any collection scanned once per item of another. Report only production-cost findings.',
+};

package/dist/review/reviewer/specialists/rules-and-goal.v1.d.ts

@@ -0,0 +1,9 @@
+/** Specialist v1: what this team and this pull request asked for (prompt steps 8, 9, 10 and 12). */
+export declare const RULES_AND_GOAL_V1: {
+    id: string;
+    version: number;
+    title: string;
+    steps: number[];
+    classes: string[];
+    focus: string;
+};

package/dist/review/reviewer/specialists/rules-and-goal.v1.js

@@ -0,0 +1,9 @@
+/** Specialist v1: what this team and this pull request asked for (prompt steps 8, 9, 10 and 12). */
+export const RULES_AND_GOAL_V1 = {
+    id: 'rules-and-goal',
+    version: 1,
+    title: 'claims, team lessons, repository rules and the declared goal',
+    steps: [8, 9, 10, 12],
+    classes: ['stale-claim', 'repo-rule'],
+    focus: 'Check every claim in a touched comment or the description, every team lesson served, every repository rule served (by id), and every declared goal item if the goal step is present. Report only stale-claim and repo-rule findings.',
+};

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

@@ -21,6 +21,33 @@ export interface BranchState {
     inputsKey?: string;
     at: string;
 }
+/**
+ * A finished review's cost, for the orchestrator's savings ledger (orchestrator.ts). Sizes are characters of what the
+ * judge is given: `shared` (the input files every run reads, the diff left out) plus the reviewable diff (lockfiles and
+ * generated files left out), counted the same way in both modes.
+ */
+export interface ReviewCost {
+    at: string;
+    /** `single`: one judge, asked for and run (never an orchestrator's fallback). `orchestrator`: every run it made, its fallback included. */
+    mode: 'single' | 'orchestrator';
+    /** Changed lines in the reviewable diff. */
+    lines: number;
+    /** What one judge would be given for this change: shared inputs + the reviewable diff. */
+    projectedSingleChars: number;
+    /** What the orchestrator planned: per pass, shared inputs + its slice (0 when no pass). Orchestrator rows only. */
+    projectedChars?: number;
+    /** What every run was given, a failed pass, a fallback and a retry included. */
+    actualChars: number;
+    /** What every run reported costing; a judge that reports no dollars adds none. */
+    actualUsd: number;
+    runs: number;
+}
+/** What one judge cost per character here, frozen once, at the orchestrator's first review: `null` without enough single reviews. */
+export interface CostBaseline {
+    at: string;
+    usdPerChar: number | null;
+    singles: number;
+}
 export declare class VerdictStore {
     private readonly dir;
     private constructor();
@@ -36,6 +63,14 @@ export declare class VerdictStore {
     spend(day?: string): DaySpend;
     /** 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;
+    /** One line per finished review: how it ran, what one judge would have been given and what every run was (the savings ledger reads it). */
+    recordCost(entry: ReviewCost): void;
+    /** The last `n` reviews' costs, oldest first; lines that do not parse are skipped. */
+    costs(n?: number): ReviewCost[];
+    /** The frozen baseline; written by `freezeBaseline` once, and never again. */
+    baseline(): CostBaseline | undefined;
+    /** Freezes the baseline from the single reviews kept so far, unless it is already frozen; returns the frozen one. */
+    freezeBaseline(minSingles: number): CostBaseline;
     private spendFile;
     /** The record of the review (record.ts), beside its verdict. */
     recordPath(verdictPath: string): string;

package/dist/review/reviewer/store.js

@@ -12,6 +12,7 @@ import { GH_TIMEOUT_MS } from './exec.js';
 function localDay(at = new Date()) {
     return `${at.getFullYear()}-${String(at.getMonth() + 1).padStart(2, '0')}-${String(at.getDate()).padStart(2, '0')}`;
 }
+const COSTS_KEPT = 200;
 export class VerdictStore {
     dir;
     constructor(dir) {
@@ -74,6 +75,46 @@ export class VerdictStore {
         fs.mkdirSync(path.join(this.dir, 'spend'), { recursive: true });
         fs.appendFileSync(this.spendFile(day), `${JSON.stringify({ runs, ...(usd ? { usd } : {}), at: new Date().toISOString() })}\n`);
     }
+    /** One line per finished review: how it ran, what one judge would have been given and what every run was (the savings ledger reads it). */
+    recordCost(entry) {
+        fs.mkdirSync(this.dir, { recursive: true });
+        fs.appendFileSync(path.join(this.dir, 'costs.jsonl'), `${JSON.stringify(entry)}\n`);
+    }
+    /** The last `n` reviews' costs, oldest first; lines that do not parse are skipped. */
+    costs(n = COSTS_KEPT) {
+        let text = '';
+        try {
+            text = fs.readFileSync(path.join(this.dir, 'costs.jsonl'), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        return text.split('\n').flatMap(line => {
+            try {
+                const entry = JSON.parse(line);
+                return entry && typeof entry.actualChars === 'number' && typeof entry.projectedSingleChars === 'number' ? [entry] : [];
+            }
+            catch {
+                return [];
+            }
+        }).slice(-n);
+    }
+    /** The frozen baseline; written by `freezeBaseline` once, and never again. */
+    baseline() {
+        return this.readJson(path.join(this.dir, 'cost-baseline.json'));
+    }
+    /** Freezes the baseline from the single reviews kept so far, unless it is already frozen; returns the frozen one. */
+    freezeBaseline(minSingles) {
+        const frozen = this.baseline();
+        if (frozen)
+            return frozen;
+        const singles = this.costs().filter(c => c.mode === 'single' && c.actualUsd > 0 && c.actualChars > 0);
+        const chars = singles.reduce((sum, c) => sum + c.actualChars, 0);
+        const usd = singles.reduce((sum, c) => sum + c.actualUsd, 0);
+        const baseline = { at: new Date().toISOString(), usdPerChar: singles.length >= minSingles ? usd / chars : null, singles: singles.length };
+        this.writeJson(path.join(this.dir, 'cost-baseline.json'), baseline);
+        return baseline;
+    }
     spendFile(day) {
         return path.join(this.dir, 'spend', `${day}.jsonl`);
     }