@rigour-labs/core 6.6.5 → 6.7.0

package/dist/hooks/types.js

@@ -5,18 +5,4 @@
  * has its own hook format. These types unify the config generation.
  *
  */
-/** The fast gates that can run per-file in <200ms */
-export const FAST_GATE_IDS = [
-    'file-guard',
-    'governance',
-    'hallucinated-imports',
-    'promise-safety',
-    'security-patterns',
-    'file-size',
-];
-export const DEFAULT_HOOK_CONFIG = {
-    tools: ['claude'],
-    fast_gates: [...FAST_GATE_IDS],
-    timeout_ms: 5000,
-    block_on_failure: false,
-};
+export {};

package/dist/index.d.ts

@@ -12,17 +12,25 @@ export * from './utils/logger.js';
 export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
 export { rigourUserDir, repoStateDir } from './utils/user-state.js';
+export { locateTransformers, semanticRuntimeDir, semanticRuntimeInstalled, TRANSFORMERS_SPEC } from './pattern-index/semantic-runtime.js';
 export { reviewChange, toReviewFinding, type ReviewInput, type ReviewResult, type ReviewFinding } from './review/review.js';
 export { splitByChangedLines, type ChangedLineSplit } from './review/changed-lines.js';
 export { isControlFile, mergeBaseOf, readStateFile } from './review/trusted-state.js';
-export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
+export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSplit, DISMISSED_FILE } from './review/quiet.js';
+export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH, type Ledger, type RoundResult } from './review/backtest.js';
+export { scaffoldLedger } from './review/backtest-init.js';
+export { fixScope, type FixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
-export { countUsage, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
+export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
 export { buildReviewTask, type ReviewTask, type ReviewTaskItem } from './review/review-task.js';
 export { buildQualityReceipt, receiptReport, type QualityReceipt, type ReceiptGap, type ReceiptOptions } from './review/receipt.js';
 export { runToolchain, type ToolResult, type ToolStatus } from './review/toolchain.js';
 export { branchFailures, mergeConflicts, staleReferences } from './review/branch-checks.js';
-export { runReviewer, reviewerBlocks, type ReviewerResult, type ReviewerVerdict } from './review/reviewer.js';
+export { runReviewer, reviewerBlocks, itemLine, type ReviewerOptions, type ReviewerResult, type ReviewerOutcome, type OpenItem } from './review/reviewer.js';
+export { startBackgroundReview, backgroundReview, reviewStatus, type ReviewStatus } from './review/reviewer/background.js';
+export { dismissReviewerFinding, REVIEW_DISMISSALS, reviewerInputs } from './review/reviewer/context.js';
+export { resolveReviewer, saveUserReviewer, type ResolvedReviewer, type RunChoice, type UserReviewerPatch } from './review/reviewer/settings.js';
+export { reviewerAvailability } from './review/reviewer/adapters.js';
 export { branchBase, type BranchBase } from './gates/logic-drift-git-base.js';
 export { acknowledgeReview, type ReviewAck, type AckResult } from './review/review-ack.js';
 export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE, type LedgerEntry, type ReviewedKey, type ReviewVerdict } from './review/ledger.js';

package/dist/index.js

@@ -12,17 +12,25 @@ export * from './utils/logger.js';
 export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
 export { rigourUserDir, repoStateDir } from './utils/user-state.js';
+export { locateTransformers, semanticRuntimeDir, semanticRuntimeInstalled, TRANSFORMERS_SPEC } from './pattern-index/semantic-runtime.js';
 export { reviewChange, toReviewFinding } from './review/review.js';
 export { splitByChangedLines } from './review/changed-lines.js';
 export { isControlFile, mergeBaseOf, readStateFile } from './review/trusted-state.js';
-export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMISSED_FILE } from './review/quiet.js';
+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 { fixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
-export { countUsage, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
+export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
 export { buildReviewTask } from './review/review-task.js';
 export { buildQualityReceipt, receiptReport } from './review/receipt.js';
 export { runToolchain } from './review/toolchain.js';
 export { branchFailures, mergeConflicts, staleReferences } from './review/branch-checks.js';
-export { runReviewer, reviewerBlocks } from './review/reviewer.js';
+export { runReviewer, reviewerBlocks, itemLine } from './review/reviewer.js';
+export { startBackgroundReview, backgroundReview, reviewStatus } from './review/reviewer/background.js';
+export { dismissReviewerFinding, REVIEW_DISMISSALS, reviewerInputs } from './review/reviewer/context.js';
+export { resolveReviewer, saveUserReviewer } from './review/reviewer/settings.js';
+export { reviewerAvailability } from './review/reviewer/adapters.js';
 export { branchBase } from './gates/logic-drift-git-base.js';
 export { acknowledgeReview } from './review/review-ack.js';
 export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE } from './review/ledger.js';

package/dist/inference/cloud-provider.d.ts

@@ -41,5 +41,7 @@ export declare class CloudProvider implements InferenceProvider {
     /** OpenRouter forwards Anthropic's cache_control to Claude models. */
     private cachesPrompts;
     private isOpenRouter;
+    /** The API base URL: the one given, else the provider's own. */
+    private endpoint;
     dispose(): void;
 }

package/dist/inference/cloud-provider.js

@@ -1,8 +1,8 @@
 import { priceTokens } from './pricing.js';
 /** Default models per provider (user can override via model_name) */
 const DEFAULT_MODELS = {
-    claude: 'claude-opus-4-6',
-    anthropic: 'claude-sonnet-4-6',
+    claude: 'claude-sonnet-5-5',
+    anthropic: 'claude-sonnet-5-5',
     openai: 'gpt-5-mini',
     gemini: 'gemini-2.5-flash',
     groq: 'llama-3.3-70b-versatile',
@@ -24,6 +24,7 @@ const DEFAULT_BASE_URLS = {
     fireworks: 'https://api.fireworks.ai/inference/v1',
     deepseek: 'https://api.deepseek.com/v1',
     perplexity: 'https://api.perplexity.ai',
+    openrouter: 'https://openrouter.ai/api/v1',
     ollama: 'http://localhost:11434/v1',
     lmstudio: 'http://localhost:1234/v1',
 };
@@ -43,7 +44,11 @@ export class CloudProvider {
         this.providerName = providerName.toLowerCase();
         this.apiKey = apiKey.trim();
         this.baseUrl = options?.baseUrl;
-        this.modelName = options?.modelName || DEFAULT_MODELS[this.providerName] || 'gpt-4o-mini';
+        const model = options?.modelName || DEFAULT_MODELS[this.providerName];
+        // No guessed model: a default that does not exist on this provider fails every call, or bills the wrong one.
+        if (!model)
+            throw new Error(`No default model for provider "${this.providerName}": pass --model-name (for example rigour settings set deep.defaultModel <name>).`);
+        this.modelName = model;
         this.isClaude = this.providerName === 'claude' || this.providerName === 'anthropic';
         this.name = `cloud-${this.providerName}`;
     }
@@ -54,7 +59,8 @@ export class CloudProvider {
         if (this.isClaude) {
             try {
                 const { default: Anthropic } = await import('@anthropic-ai/sdk');
-                this.client = new Anthropic({ apiKey: this.apiKey });
+                // A base URL given for Claude (a proxy, a gateway) is honoured like any other provider's.
+                this.client = new Anthropic({ apiKey: this.apiKey, ...(this.baseUrl ? { baseURL: this.baseUrl } : {}) });
                 onProgress?.(`✓ ${this.providerName} API connected (model: ${this.modelName})`);
             }
             catch {
@@ -68,7 +74,7 @@ export class CloudProvider {
             // No limitations. User's key, user's choice.
             try {
                 const { default: OpenAI } = await import('openai');
-                const baseURL = this.baseUrl || DEFAULT_BASE_URLS[this.providerName] || undefined;
+                const baseURL = this.endpoint() || undefined;
                 this.client = new OpenAI({
                     apiKey: this.apiKey,
                     ...(baseURL ? { baseURL } : {}),
@@ -187,7 +193,11 @@ export class CloudProvider {
         return this.isOpenRouter() && /(^|\/)(anthropic\/|claude)/i.test(this.modelName);
     }
     isOpenRouter() {
-        return /(^|\.)openrouter\.ai(\/|$)/.test((this.baseUrl || '').replace(/^https?:\/\//, ''));
+        return /(^|\.)openrouter\.ai(\/|$)/.test(this.endpoint().replace(/^https?:\/\//, ''));
+    }
+    /** The API base URL: the one given, else the provider's own. */
+    endpoint() {
+        return this.baseUrl || DEFAULT_BASE_URLS[this.providerName] || '';
     }
     dispose() {
         this.client = null;

package/dist/inference/cloud-provider.test.js

@@ -8,6 +8,10 @@ vi.mock('openai', () => ({
 }));
 vi.mock('@anthropic-ai/sdk', () => ({
     default: class {
+        options;
+        constructor(options) {
+            this.options = options;
+        }
         messages = { create: anthropicCreate };
     },
 }));
@@ -18,6 +22,23 @@ beforeEach(() => {
     anthropicCreate.mockReset();
 });
 describe('CloudProvider', () => {
+    it('names no model it cannot know: a provider without a default needs one', () => {
+        expect(() => new CloudProvider('somecloud', 'k')).toThrow(/pass --model-name/);
+        expect(() => new CloudProvider('somecloud', 'k', { modelName: 'x' })).not.toThrow();
+    });
+    it('sends Claude calls to a base URL when one is given', async () => {
+        anthropicCreate.mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], usage: { input_tokens: 1, output_tokens: 1 } });
+        const provider = new CloudProvider('claude', 'k', { modelName: 'claude-sonnet-5-5', baseUrl: 'https://gateway.example/anthropic' });
+        await provider.setup();
+        expect(provider.client.options).toMatchObject({ baseURL: 'https://gateway.example/anthropic' });
+    });
+    it('sends OpenRouter calls to OpenRouter, asking it to report their cost', async () => {
+        openaiCreate.mockResolvedValue({ choices: [{ message: { content: 'ok' } }], usage: { prompt_tokens: 1, completion_tokens: 1 } });
+        const provider = new CloudProvider('openrouter', 'k', { modelName: 'anthropic/claude-sonnet-5.5' });
+        await provider.setup();
+        await provider.analyze('prompt');
+        expect(openaiCreate.mock.calls[0][0]).toMatchObject({ usage: { include: true } });
+    });
     it('passes the per-call timeout to the SDK request', async () => {
         anthropicCreate.mockResolvedValue({ content: [{ type: 'text', text: 'ok' }], usage: { input_tokens: 10, output_tokens: 2 } });
         const provider = new CloudProvider('claude', 'k', { modelName: 'claude-sonnet-5-5' });

package/dist/pattern-index/embeddings.d.ts

@@ -1,8 +1,3 @@
-/**
- * Semantic Embedding Service
- *
- * Uses Transformers.js for local vector embeddings.
- */
 /**
  * Generate an embedding for a piece of text.
  */

package/dist/pattern-index/embeddings.js

@@ -1,8 +1,10 @@
 /**
  * Semantic Embedding Service
  *
- * Uses Transformers.js for local vector embeddings.
+ * Uses Transformers.js for local vector embeddings, loaded from wherever it is installed
+ * (semantic-runtime.ts). Without it, embeddings are empty and callers fall back to keywords.
  */
+import { loadTransformers } from './semantic-runtime.js';
 /**
  * Singleton for the embedding pipeline to avoid re-loading the model.
  */
@@ -26,10 +28,15 @@ async function getPipeline() {
         return null;
     if (!embeddingPipeline) {
         try {
-            // Dynamic import to isolate native dependency issues (like sharp)
-            const { pipeline } = await import('@xenova/transformers');
+            // Loaded where it is installed; never a dependency of the npm package (semantic-runtime.ts).
+            const transformers = await loadTransformers();
+            if (!transformers) {
+                // Not installed: keyword matching, said once by `rigour doctor`, not on every run.
+                embeddingUnavailable = true;
+                return null;
+            }
             // Using a compact but high-quality model for local embeddings
-            embeddingPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+            embeddingPipeline = await transformers.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
         }
         catch (error) {
             embeddingUnavailable = true;

package/dist/pattern-index/semantic-runtime.d.ts

@@ -0,0 +1,10 @@
+/** The version installed by `rigour setup`; the model it loads is fetched once on first use. */
+export declare const TRANSFORMERS_SPEC = "@xenova/transformers@2.17.2";
+/** Rigour's own copy, shared by every Rigour version on the machine (per profile home). */
+export declare function semanticRuntimeDir(): string;
+/** Where the library resolves from, or undefined when it is not installed anywhere Rigour looks. */
+export declare function locateTransformers(cwd?: string): string | undefined;
+/** The library's module, loaded from wherever it is installed. */
+export declare function loadTransformers(cwd?: string): Promise<any | undefined>;
+/** Whether Rigour's home has its own copy (what `rigour setup` installs). */
+export declare function semanticRuntimeInstalled(): boolean;

package/dist/pattern-index/semantic-runtime.js

@@ -0,0 +1,46 @@
+/**
+ * Where the local embedding library (`@xenova/transformers`, with its ONNX runtime about 230 MB)
+ * comes from. It is not a dependency of the npm package: npm installed it again for every
+ * version a hook pinned, so a machine kept one copy per Rigour version. `rigour setup` installs it
+ * once into Rigour's home, where every version finds it.
+ *
+ * Search order: next to Rigour itself (a checkout, or a project that installs Rigour and the
+ * library as devDependencies), the project being worked on, then Rigour's home. Without it,
+ * recall and pattern matching fall back to keywords, which find far less (on the committed eval
+ * sets, 6% of memories and 20% of existing helpers, against 81% and 93% by meaning).
+ */
+import { createRequire } from 'module';
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { rigourUserDir } from '../utils/user-state.js';
+/** The version installed by `rigour setup`; the model it loads is fetched once on first use. */
+export const TRANSFORMERS_SPEC = '@xenova/transformers@2.17.2';
+const PACKAGE = '@xenova/transformers';
+/** Rigour's own copy, shared by every Rigour version on the machine (per profile home). */
+export function semanticRuntimeDir() {
+    return path.join(rigourUserDir(), 'runtime', 'semantic');
+}
+/** Where the library resolves from, or undefined when it is not installed anywhere Rigour looks. */
+export function locateTransformers(cwd = process.cwd()) {
+    for (const base of [import.meta.url, path.join(cwd, 'package.json'), path.join(semanticRuntimeDir(), 'package.json')]) {
+        try {
+            return createRequire(base).resolve(PACKAGE);
+        }
+        catch {
+            // not there
+        }
+    }
+    return undefined;
+}
+/** The library's module, loaded from wherever it is installed. */
+export async function loadTransformers(cwd = process.cwd()) {
+    const entry = locateTransformers(cwd);
+    if (!entry)
+        return undefined;
+    return import(pathToFileURL(entry).href);
+}
+/** Whether Rigour's home has its own copy (what `rigour setup` installs). */
+export function semanticRuntimeInstalled() {
+    return fs.existsSync(path.join(semanticRuntimeDir(), 'node_modules', ...PACKAGE.split('/'), 'package.json'));
+}

package/dist/pattern-index/semantic-runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pattern-index/semantic-runtime.test.js

@@ -0,0 +1,31 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { locateTransformers, semanticRuntimeDir, semanticRuntimeInstalled } from './semantic-runtime.js';
+let home;
+const original = process.env.RIGOUR_HOME;
+beforeEach(() => {
+    home = fs.mkdtempSync(path.join(os.tmpdir(), 'semantic-home-'));
+    process.env.RIGOUR_HOME = home;
+});
+afterEach(() => {
+    process.env.RIGOUR_HOME = original;
+    fs.rmSync(home, { recursive: true, force: true });
+});
+describe('the semantic runtime', () => {
+    it('lives in Rigour\'s home, shared by every Rigour version, and is seen there once installed', () => {
+        expect(semanticRuntimeDir()).toBe(path.join(home, '.rigour', 'runtime', 'semantic'));
+        expect(semanticRuntimeInstalled()).toBe(false);
+        const pkg = path.join(semanticRuntimeDir(), 'node_modules', '@xenova', 'transformers');
+        fs.mkdirSync(pkg, { recursive: true });
+        fs.writeFileSync(path.join(pkg, 'package.json'), JSON.stringify({ name: '@xenova/transformers', main: 'index.js' }));
+        fs.writeFileSync(path.join(pkg, 'index.js'), 'module.exports = {};');
+        expect(semanticRuntimeInstalled()).toBe(true);
+        expect(locateTransformers(home)).toBeDefined();
+    });
+    it('is not a dependency of the published package: the 240 MB is installed once, never per version', () => {
+        const manifest = JSON.parse(fs.readFileSync(path.join(__dirname, '../../package.json'), 'utf8'));
+        expect({ ...manifest.dependencies, ...manifest.optionalDependencies }).not.toHaveProperty('@xenova/transformers');
+    });
+});

package/dist/review/backtest-init.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from '../types/index.js';
+import { type LedgerRound } from './backtest.js';
+import { type Exec } from './reviewer.js';
+export declare function scaffoldLedger(cwd: string, pr: number, config: Config, exec?: Exec): Promise<{
+    file: string;
+    rounds: LedgerRound[];
+    incomplete: number;
+}>;

package/dist/review/backtest-init.js

@@ -0,0 +1,87 @@
+/**
+ * `rigour backtest init --pr <n>`: a ledger scaffolded from a pull request's human reviews, one
+ * round per review. An inline comment gives a point its file and a line window for free; a point
+ * made in the review's body has neither, so it is written with `needs` set and a person adds the
+ * text pattern once. The base of each round is the main branch as it was when the review was
+ * posted, so a later merge does not change what the round measures.
+ */
+import fs from 'fs';
+import path from 'path';
+import { branchBase } from '../gates/logic-drift-git-base.js';
+import { LEDGER_PATH, LedgerSchema } from './backtest.js';
+import { defaultExec, githubEnv, parseJsonArrays } from './reviewer.js';
+const GH_TIMEOUT_MS = 60_000;
+/** Lines either side of an inline comment that a finding for the same point may land on. */
+const LINE_SLACK = 10;
+const BULLET = /^\s*(?:[-*]|\d+[.)])\s+(.{8,})$/;
+export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
+    const env = await githubEnv(cwd, config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT, exec);
+    const gh = (args) => exec('gh', args, { cwd, timeoutMs: GH_TIMEOUT_MS, env });
+    const view = await gh(['pr', 'view', String(pr), '--json', 'author', '-q', '.author.login']);
+    if (view.exitCode !== 0)
+        throw new Error(`could not read pull request ${pr}: ${view.stderr.trim() || 'is gh signed in?'}`);
+    const author = view.stdout.trim();
+    const reviews = await gh(['api', `repos/{owner}/{repo}/pulls/${pr}/reviews`, '--paginate']);
+    if (reviews.exitCode !== 0)
+        throw new Error(`could not read the reviews of pull request ${pr}: ${reviews.stderr.trim()}`);
+    const humans = parseJsonArrays(reviews.stdout)
+        .filter((r) => r?.user && r.user.type !== 'Bot' && !/bot/i.test(r.user.login) && r.user.login !== author && (r.body?.trim() || r.state === 'CHANGES_REQUESTED'));
+    if (humans.length === 0)
+        throw new Error(`pull request ${pr} has no review by a person yet`);
+    const mainRef = branchBase(cwd)?.mainRef ?? 'origin/main';
+    const rounds = [];
+    for (const [index, review] of humans.entries()) {
+        const comments = await gh(['api', `repos/{owner}/{repo}/pulls/${pr}/reviews/${review.id}/comments`, '--paginate']);
+        const inline = comments.exitCode === 0 ? parseJsonArrays(comments.stdout) : [];
+        const round = index + 1;
+        const points = inline.map((c, i) => inlinePoint(`R${round}-${i + 1}`, c));
+        for (const [i, line] of bodyPoints(String(review.body ?? '')).entries()) {
+            points.push({ id: `R${round}-B${i + 1}`, point: line, file: '', needs: 'a file pattern and a text pattern (this point was made in the review body, not on a line)' });
+        }
+        const base = await exec('git', ['rev-list', '-1', `--before=${review.submitted_at}`, mainRef], { cwd, timeoutMs: GH_TIMEOUT_MS });
+        rounds.push({
+            id: `pr${pr}-r${round}`,
+            commit: String(review.commit_id),
+            base: base.stdout.trim() || mainRef,
+            reviewed_at: String(review.submitted_at),
+            pr,
+            points,
+            must_not_flag: [],
+        });
+    }
+    const file = path.join(cwd, LEDGER_PATH);
+    const existing = existingLedger(file);
+    const merged = { rounds: [...existing.rounds.filter(r => !rounds.some(n => n.id === r.id)), ...rounds] };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(merged, null, 2) + '\n');
+    return { file, rounds, incomplete: rounds.flatMap(r => r.points).filter(p => p.needs).length };
+}
+function inlinePoint(id, comment) {
+    const line = Number(comment.line ?? comment.original_line ?? 0);
+    const body = String(comment.body ?? '').trim();
+    return {
+        id,
+        point: firstLine(body),
+        file: escape(String(comment.path ?? '')),
+        ...(line > 0 ? { lines: [Math.max(1, line - LINE_SLACK), line + LINE_SLACK] } : { needs: 'a line window or a text pattern (the comment has no line)' }),
+    };
+}
+/** The bullet and numbered lines of a review body: the points a reviewer makes outside any one line. */
+function bodyPoints(body) {
+    return body.split('\n').map(l => BULLET.exec(l)?.[1]).filter((l) => !!l).map(firstLine);
+}
+function firstLine(text) {
+    const line = text.split('\n').find(l => l.trim())?.replace(/[*_`#]/g, '').trim() ?? '';
+    return line.length > 140 ? `${line.slice(0, 137)}...` : line;
+}
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function existingLedger(file) {
+    if (!fs.existsSync(file))
+        return { rounds: [] };
+    const parsed = LedgerSchema.safeParse(JSON.parse(fs.readFileSync(file, 'utf8')));
+    if (!parsed.success)
+        throw new Error(`${LEDGER_PATH} exists but is not a ledger; fix or remove it first`);
+    return parsed.data;
+}

package/dist/review/backtest-init.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/backtest-init.test.js

@@ -0,0 +1,74 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../types/index.js';
+import { ledgerProblems, loadLedger, LEDGER_PATH, LedgerSchema } from './backtest.js';
+import { scaffoldLedger } from './backtest-init.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const config = ConfigSchema.parse({ version: 1 });
+const REVIEWS = [
+    { id: 1, user: { login: 'ci-bot', type: 'Bot' }, body: 'automated', state: 'COMMENTED', submitted_at: '2026-04-12T10:00:00Z', commit_id: 'c1c1c1c1c1' },
+    { id: 2, user: { login: 'senior', type: 'User' }, body: '## Review\n\n- A retry posts the invoice twice.\n- **Quadratic** scan in `latestPayment`.\nlooks good otherwise', state: 'CHANGES_REQUESTED', submitted_at: '2026-04-12T12:00:00Z', commit_id: 'c2c2c2c2c2' },
+];
+const INLINE = [
+    { path: 'src/lib/server/invoices.ts', line: 40, body: 'The export reads every line item for ids.\n\nNarrow it.', created_at: '2026-04-12T12:00:00Z' },
+    { path: 'src/checkout/total.ts', line: null, original_line: null, body: 'Drops the currency', created_at: '2026-04-12T12:00:00Z' },
+];
+function fakeExec(calls) {
+    return async (command, args, options) => {
+        calls.push([command, ...args]);
+        if (command === 'git')
+            return { exitCode: 0, stdout: execFileSync('git', args, { cwd: options.cwd, encoding: 'utf8' }), stderr: '' };
+        if (args[0] === 'auth')
+            return { exitCode: 0, stdout: 'token\n', stderr: '' };
+        if (args[0] === 'pr')
+            return { exitCode: 0, stdout: 'author\n', stderr: '' };
+        if (args[1].endsWith('/reviews'))
+            return { exitCode: 0, stdout: JSON.stringify(REVIEWS), stderr: '' };
+        return { exitCode: 0, stdout: JSON.stringify(INLINE), stderr: '' };
+    };
+}
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'backtest-init-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    fs.writeFileSync(path.join(repo, 'a.ts'), 'export const a = 1;\n');
+    git('add', '-A');
+    execFileSync('git', ['-C', repo, 'commit', '-qm', 'main as of the review'], { env: { ...process.env, GIT_COMMITTER_DATE: '2026-04-12T09:00:00Z', GIT_AUTHOR_DATE: '2026-04-12T09:00:00Z' } });
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('rigour backtest init', () => {
+    it('writes one round per human review: inline comments become file-and-window points, body bullets need a pattern', async () => {
+        const calls = [];
+        const mainAtReview = git('rev-parse', 'HEAD');
+        const { rounds, incomplete } = await scaffoldLedger(repo, 212, config, fakeExec(calls));
+        expect(rounds).toHaveLength(1);
+        expect(rounds[0]).toMatchObject({ id: 'pr212-r1', commit: 'c2c2c2c2c2', base: mainAtReview, reviewed_at: '2026-04-12T12:00:00Z', pr: 212 });
+        expect(rounds[0].points).toEqual([
+            { id: 'R1-1', point: 'The export reads every line item for ids.', file: 'src/lib/server/invoices\\.ts', lines: [30, 50] },
+            { id: 'R1-2', point: 'Drops the currency', file: 'src/checkout/total\\.ts', needs: 'a line window or a text pattern (the comment has no line)' },
+            { id: 'R1-B1', point: 'A retry posts the invoice twice.', file: '', needs: 'a file pattern and a text pattern (this point was made in the review body, not on a line)' },
+            { id: 'R1-B2', point: 'Quadratic scan in latestPayment.', file: '', needs: 'a file pattern and a text pattern (this point was made in the review body, not on a line)' },
+        ]);
+        expect(incomplete).toBe(3);
+        expect(calls.find(c => c[0] === 'gh' && c[1] === 'pr')).toContain('212');
+        const written = LedgerSchema.parse(JSON.parse(fs.readFileSync(path.join(repo, LEDGER_PATH), 'utf8')));
+        expect(ledgerProblems(written)).toHaveLength(3);
+        expect(() => loadLedger(repo)).toThrow('rows a person still has to complete');
+    });
+    it('keeps rounds already in the ledger and replaces its own', async () => {
+        fs.mkdirSync(path.join(repo, '.rigour'));
+        fs.writeFileSync(path.join(repo, LEDGER_PATH), JSON.stringify({ rounds: [
+                { id: 'pr212-r1', commit: 'old0000', base: 'main', points: [], must_not_flag: [] },
+                { id: 'pr7-r1', commit: 'other00', base: 'main', points: [{ id: 'P', point: 'p', file: 'x', text: 'x' }], must_not_flag: [] },
+            ] }));
+        await scaffoldLedger(repo, 212, config, fakeExec([]));
+        const written = LedgerSchema.parse(JSON.parse(fs.readFileSync(path.join(repo, LEDGER_PATH), 'utf8')));
+        expect(written.rounds.map(r => [r.id, r.commit])).toEqual([['pr7-r1', 'other00'], ['pr212-r1', 'c2c2c2c2c2']]);
+    });
+});

package/dist/review/backtest-judges.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The panel measured against the ledger, per judge: which human points each judge raised on its
+ * own, how often two judges agree (Cohen's kappa over the ledger's points, where the set of items
+ * is fixed, so agreeing on "not raised" is meaningful), and what a caught point cost. A high kappa
+ * means the judges share blind spots and a second one adds little; a judge whose catches the others
+ * always make too is not earning its runs. This decides one, two or three judges with data.
+ */
+import type { ReviewerResult } from './reviewer.js';
+/** What each judge raised unprompted in one round, with what the round cost. */
+export interface JudgeRun {
+    judges: string[];
+    raised: Array<{
+        judge: string;
+        file: string;
+        line: number | undefined;
+        text: string;
+    }>;
+    costUsd?: number;
+    runs: number;
+}
+export interface JudgeCatches {
+    judges: string[];
+    /** Ledger point ids each judge raised. */
+    caught: Record<string, string[]>;
+    points: string[];
+    costUsd?: number;
+    runs: number;
+}
+/** Each judge's own raises: the panel's record when there was one, else the items tagged with the judge who found them. */
+export declare function judgedFrom(result: ReviewerResult): JudgeRun | undefined;
+/** Across rounds: each judge's catches, every pair's kappa, and the cost of a caught point. */
+export declare function formatJudges(rounds: Array<{
+    judges?: JudgeCatches;
+    points: Array<{
+        id: string;
+        caught: boolean;
+    }>;
+}>): string;

package/dist/review/backtest-judges.js

@@ -0,0 +1,63 @@
+/** Each judge's own raises: the panel's record when there was one, else the items tagged with the judge who found them. */
+export function judgedFrom(result) {
+    if (result.reviewers.length < 2)
+        return undefined;
+    const raised = [];
+    if (result.panel) {
+        for (const d of result.panel) {
+            for (const judge of d.judges) {
+                const own = d.members?.find(m => m.judge === judge)?.item ?? d.item;
+                raised.push({ judge, file: own.file ?? '', line: own.line, text: [own.issue, own.consequence, own.evidence].filter(Boolean).join(' ') });
+            }
+        }
+    }
+    else {
+        for (const item of [...result.items, ...result.unverified, ...result.notes]) {
+            if (item.kind === 'prior' || !item.reviewer)
+                continue;
+            for (const judge of item.reviewer.split('+'))
+                raised.push({ judge, file: item.file ?? '', line: item.line, text: [item.issue, item.consequence, item.evidence].filter(Boolean).join(' ') });
+        }
+    }
+    return { judges: result.reviewers, raised, ...(result.costUsd !== undefined ? { costUsd: result.costUsd } : {}), runs: result.runs ?? result.reviewers.length };
+}
+/** Cohen's kappa for two raters' yes/no calls on the same items; 1 when they agree on everything, 0 at chance. */
+function cohensKappa(a, b) {
+    const n = a.length;
+    if (n === 0 || n !== b.length)
+        return Number.NaN;
+    const agree = a.filter((x, i) => x === b[i]).length / n;
+    const pa = a.filter(Boolean).length / n;
+    const pb = b.filter(Boolean).length / n;
+    const chance = pa * pb + (1 - pa) * (1 - pb);
+    return chance === 1 ? (agree === 1 ? 1 : 0) : (agree - chance) / (1 - chance);
+}
+/** Across rounds: each judge's catches, every pair's kappa, and the cost of a caught point. */
+export function formatJudges(rounds) {
+    const judged = rounds.map(r => r.judges).filter((j) => !!j);
+    if (!judged.length)
+        return '';
+    const names = [...new Set(judged.flatMap(j => j.judges))];
+    const total = judged.reduce((sum, j) => sum + j.points.length, 0);
+    const lines = ['', `Judges (${judged.length} round(s), ${total} human point(s))`];
+    for (const name of names) {
+        const caught = judged.reduce((sum, j) => sum + (j.caught[name]?.length ?? 0), 0);
+        const only = judged.reduce((sum, j) => sum + (j.caught[name] ?? []).filter(id => j.judges.filter(o => o !== name).every(o => !(j.caught[o] ?? []).includes(id))).length, 0);
+        lines.push(`  ${name}: raised ${caught}/${total}; ${only} that no other judge raised`);
+    }
+    for (let i = 0; i < names.length; i++) {
+        for (let k = i + 1; k < names.length; k++) {
+            const both = judged.filter(j => j.judges.includes(names[i]) && j.judges.includes(names[k]));
+            const a = both.flatMap(j => j.points.map(p => (j.caught[names[i]] ?? []).includes(p)));
+            const b = both.flatMap(j => j.points.map(p => (j.caught[names[k]] ?? []).includes(p)));
+            const kappa = cohensKappa(a, b);
+            if (a.length)
+                lines.push(`  ${names[i]} and ${names[k]}: kappa ${Number.isNaN(kappa) ? 'n/a' : kappa.toFixed(2)} over ${a.length} point(s)${kappa > 0.8 ? ' (they share blind spots: a second judge adds little)' : ''}`);
+        }
+    }
+    const cost = judged.reduce((sum, j) => sum + (j.costUsd ?? 0), 0);
+    const runs = judged.reduce((sum, j) => sum + j.runs, 0);
+    const caughtPoints = rounds.filter(r => r.judges).reduce((sum, r) => sum + r.points.filter(p => p.caught).length, 0);
+    lines.push(`  ${runs} agent run(s)${cost ? `, $${cost.toFixed(2)} recorded` : ''}${cost && caughtPoints ? `, $${(cost / caughtPoints).toFixed(2)} per caught point` : ''}`);
+    return lines.join('\n');
+}

package/dist/review/backtest-judges.test.d.ts

@@ -0,0 +1 @@
+export {};