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

package/dist/outcomes/metrics.d.ts

@@ -42,6 +42,33 @@ export interface OutcomeMetrics {
             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, over pull requests whose every review
+         * event counts every run. Median only from MIN_FOR_RATE. Pull requests with an earlier event are counted apart in
+         * `prsEarlierBasis`, never pooled: their dollars are on another basis.
+         */
+        costPerPr: {
+            prs: number;
+            totalUsd: number;
+            medianUsd: number | null;
+            reason?: string;
+            prsEarlierBasis: number;
+        };
+    };
     lessons: {
         /** Candidates waiting on a person: a later fix on their lines, back to candidate, or taken back. */
         awaitingDecision: number;
@@ -52,5 +79,17 @@ export interface OutcomeMetrics {
         takenBack: number;
     };
 }
-/** `reviewed`: the pull requests a review by Rigour ran on (the threads' review events). */
-export declare function outcomeMetrics(records: PrOutcome[], lessons: ReviewLesson[], reviewed: Set<number>): OutcomeMetrics;
+/** 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;
+    /** A review event from before cost_usd counted every run (no `cost_basis: 'runs'`): its dollars are on another basis. */
+    earlierBasis: boolean;
+}
+/** `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

@@ -1,7 +1,7 @@
 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 (the threads' review events). */
+/** `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);
@@ -18,6 +18,7 @@ export function outcomeMetrics(records, lessons, reviewed) {
             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,
@@ -26,6 +27,24 @@ export function outcomeMetrics(records, lessons, reviewed) {
         },
     };
 }
+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.filter(p => !p.earlierBasis).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),
+            prsEarlierBasis: prs.filter(p => p.earlierBasis).length,
+        },
+    };
+}
 function share(count, of) {
     return of >= MIN_FOR_RATE
         ? { count, of, rate: Math.round((count / of) * 100) / 100 }

package/dist/outcomes/run.js

@@ -44,14 +44,21 @@ function lessonEvidence(cwd, mainRef, demoteAfter) {
         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: from the threads. */
+/** 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 Set();
+    const reviewed = new Map();
+    const count = (v) => typeof v === 'number' ? v : 0;
     for (const e of eventsOfKind(cwd, 'review')) {
         if (typeof e.pr !== 'number')
             continue;
-        reviewed.add(e.pr);
+        const pr = reviewed.get(e.pr) ?? { usd: 0, earlierBasis: false };
+        pr.usd += count(e.cost_usd);
+        if (e.cost_basis !== 'runs')
+            pr.earlierBasis = true;
+        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();

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`);
     }

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

@@ -0,0 +1,62 @@
+/**
+ * The orchestrator's router: which specialists a change needs, hunk by hunk, decided without a model, and the passes
+ * that takes. One combined pass is the plan at every size; a change over the judge's limit (orchestrator.ts passLimit)
+ * also gets a split by hunk, each part within the limit, which runs only when the savings ledger covers it. A change
+ * with nothing for a model to review (only lockfiles, generated files) gets no pass at all.
+ */
+import type { Specialist } from './orchestrator.js';
+export interface Hunk {
+    file: string;
+    /** The hunk as it appears in the diff, its file header included, so a slice is itself a diff. */
+    text: string;
+    added: string[];
+    removed: string[];
+    newFile: boolean;
+    /** Names the hunk defines on an added line (function, const, class, type). */
+    defines: Set<string>;
+    /** Every identifier on its added and removed lines. */
+    references: Set<string>;
+}
+/** The most parts a split runs: a change that needs more is one combined pass. */
+export declare const MAX_PARTS = 3;
+/** The diff's hunks, each with its file header. */
+export declare function parseHunks(diff: string): Hunk[];
+export interface TriageContext {
+    /** Human reviews on the pull request: the prior-points specialist is for them. */
+    humanReviews: number;
+    /** Rules and lessons the team's knowledge serves for this change. */
+    rulesAndLessons: number;
+    /** The goal step has items for a model to judge. */
+    goal: boolean;
+}
+/** 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 no model reviews this file (SKIP). */
+export declare function skipped(file: string): boolean;
+export interface Pass {
+    specialists: string[];
+    /** The hunks triage picked for it. */
+    hunks: number[];
+    /** What it is given: its hunks and the hunks defining what they use. */
+    sliced: number[];
+    diff: string;
+}
+export interface Plan {
+    /** One pass with every picked specialist; undefined when triage picked nothing. */
+    combined?: Pass;
+    /** Present only when the combined pass is over `limit`: the picked hunks in parts, each within it where one hunk allows. */
+    split?: Pass[];
+    /** The parts a change over `limit` would need, when that is more than MAX_PARTS: no split, one combined pass. */
+    needsParts?: number;
+}
+/**
+ * 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 declare function planPasses(hunks: Hunk[], picked: Map<string, number[]>, order: readonly Specialist[], limit: number): Plan;
+/** Characters of the reviewable diff (no lockfiles or generated files) and its changed lines: both modes are measured on this. */
+export declare function reviewable(hunks: Hunk[]): {
+    chars: number;
+    lines: number;
+};