@rigour-labs/core 6.7.2 → 6.7.5

package/dist/hooks/index.d.ts

@@ -13,6 +13,6 @@ export { recordDLPFeedback, allowLastDLPBlock, writeDLPBlockManifest, getLearned
 export type { DLPFeedbackEntry, DLPFeedbackStore, DLPBlockManifest } from './dlp-feedback.js';
 export { generateDLPHookFiles } from './dlp-templates.js';
 export type { GeneratedDLPHookFile } from './dlp-templates.js';
-export { stopReview, stopMessage, STOP_MAX_ATTEMPTS } from './stop-review.js';
-export type { StopDecision } from './stop-review.js';
-export { recordSessionBaseline, sessionBaseline, nextStopAttempt, clearStopAttempts, workFingerprint, alreadyReviewed, recordReviewed } from './session-state.js';
+export { stopReview, stopMessage, teamMessage, STOP_MAX_ATTEMPTS } from './stop-review.js';
+export type { StopDecision, TeamGuidance } from './stop-review.js';
+export { recordSessionBaseline, sessionBaseline, nextStopAttempt, clearStopAttempts, workFingerprint, alreadyReviewed, recordReviewed, untaught, recordTaught } from './session-state.js';

package/dist/hooks/index.js

@@ -9,5 +9,5 @@ export { scanInputForCredentials, formatDLPAlert, createDLPAuditEntry } from './
 export { recordDLPFeedback, allowLastDLPBlock, writeDLPBlockManifest, getLearnedAllowCount, loadDLPFeedbackStore, loadDLPFeedbackStoreSync, fingerprintDetection, } from './dlp-feedback.js';
 export { generateDLPHookFiles } from './dlp-templates.js';
 // Stop review ("before you say done")
-export { stopReview, stopMessage, STOP_MAX_ATTEMPTS } from './stop-review.js';
-export { recordSessionBaseline, sessionBaseline, nextStopAttempt, clearStopAttempts, workFingerprint, alreadyReviewed, recordReviewed } from './session-state.js';
+export { stopReview, stopMessage, teamMessage, STOP_MAX_ATTEMPTS } from './stop-review.js';
+export { recordSessionBaseline, sessionBaseline, nextStopAttempt, clearStopAttempts, workFingerprint, alreadyReviewed, recordReviewed, untaught, recordTaught } from './session-state.js';

package/dist/hooks/session-state.d.ts

@@ -15,3 +15,6 @@ export declare function recordReviewed(cwd: string, session: string, fingerprint
 export declare function nextStopAttempt(cwd: string, session: string): number;
 /** The agent finished cleanly: the next stop starts counting again. The baseline stays. */
 export declare function clearStopAttempts(cwd: string, session: string): void;
+/** Of these team-knowledge keys, the ones this session has not been shown yet. */
+export declare function untaught(cwd: string, session: string, keys: string[]): string[];
+export declare function recordTaught(cwd: string, session: string, keys: string[]): void;

package/dist/hooks/session-state.js

@@ -4,6 +4,7 @@
  *   - baseline: the commit HEAD was at when the session first edited a file. The stop review
  *     covers everything since then, so committing mid-session hides nothing.
  *   - attempts: how many times the stop review has blocked this session.
+ *   - taught: the team lessons and rules the stop review already put to the agent, so each is asked once.
  */
 import { spawnSync } from 'child_process';
 import { createHash } from 'crypto';
@@ -96,3 +97,12 @@ export function clearStopAttempts(cwd, session) {
     if (readStore(cwd)[session]?.attempts)
         update(cwd, session, entry => ({ ...entry, attempts: 0 }));
 }
+/** Of these team-knowledge keys, the ones this session has not been shown yet. */
+export function untaught(cwd, session, keys) {
+    const taught = new Set(readStore(cwd)[session]?.taught ?? []);
+    return keys.filter(key => !taught.has(key));
+}
+export function recordTaught(cwd, session, keys) {
+    if (keys.length)
+        update(cwd, session, entry => ({ ...entry, taught: [...new Set([...(entry.taught ?? []), ...keys])] }));
+}

package/dist/hooks/stop-review.d.ts

@@ -1,18 +1,3 @@
-/**
- * The "before you say done" review: when an agent is about to stop, review the
- * whole branch against the commit it left main at (committed, uncommitted and new
- * files alike; on main itself, what the session changed since its baseline) and,
- * if it introduced serious findings, tell the agent what to fix instead of
- * letting it finish. A review with nothing to look at says so; it is never
- * reported as a clean pass.
- *
- * What blocks is what the review itself reports (review/quiet.ts `mustFix`: proven, critical, or
- * high and verified or from a security gate), plus on a branch a merge conflict with main or a
- * mention of a file the branch deleted (review/branch-checks.ts). The same rule decides the push
- * gate, so a stop, a review and a push never disagree about a finding. A high heuristic (a regex
- * that sees `fetch` without `.catch`) is not enough to hold an agent back; callers also cap the
- * number of attempts.
- */
 import type { Config, Failure } from '../types/index.js';
 import { type ReviewTaskItem } from '../review/review-task.js';
 export declare const STOP_MAX_ATTEMPTS = 3;
@@ -26,8 +11,16 @@ export interface StopDecision {
     reviewedFiles: string[];
     /** What the review was measured against, e.g. `origin/main @ 1a2b3c4` or `uncommitted work`. */
     against: string;
+    /** What this team learned that applies to the change (verified lessons; rules when `gates.deep.repo_rules` is on), keyed for asking once. */
+    guidance: TeamGuidance[];
+}
+export interface TeamGuidance {
+    key: string;
+    text: string;
 }
 /** `sessionBaseline`: the commit the session started from, used on main (session-state.ts). */
 export declare function stopReview(cwd: string, config: Config, attempt: number, sessionBaseline?: string): Promise<StopDecision>;
+/** Asked once per new lesson or rule: the senior's question at the end of the task, never a loop. */
+export declare function teamMessage(guidance: TeamGuidance[]): string;
 export declare function reviewAckMessage(items: ReviewTaskItem[], attempt: number): string;
 export declare function stopMessage(findings: Failure[], attempt: number): string;

package/dist/hooks/stop-review.js

@@ -1,8 +1,25 @@
+/**
+ * The "before you say done" review: when an agent is about to stop, review the
+ * whole branch against the commit it left main at (committed, uncommitted and new
+ * files alike; on main itself, what the session changed since its baseline) and,
+ * if it introduced serious findings, tell the agent what to fix instead of
+ * letting it finish. A review with nothing to look at says so; it is never
+ * reported as a clean pass.
+ *
+ * What blocks is what the review itself reports (review/quiet.ts `mustFix`: proven, critical, or
+ * high and verified or from a security gate), plus on a branch a merge conflict with main or a
+ * mention of a file the branch deleted (review/branch-checks.ts). The same rule decides the push
+ * gate, so a stop, a review and a push never disagree about a finding. A high heuristic (a regex
+ * that sees `fetch` without `.catch`) is not enough to hold an agent back; callers also cap the
+ * number of attempts.
+ */
+import { createHash } from 'crypto';
 import { reviewChange } from '../review/review.js';
 import { buildReviewTask } from '../review/review-task.js';
 import { diffFromGit } from '../review/git-diff.js';
 import { branchBase } from '../gates/logic-drift-git-base.js';
 import { branchFailures } from '../review/branch-checks.js';
+import { describeLesson } from '../review-learning/team-lessons.js';
 export const STOP_MAX_ATTEMPTS = 3;
 const MAX_LISTED = 8;
 /** The branch since it left main; on main, what the session changed since its baseline (session-state.ts). */
@@ -27,8 +44,9 @@ export async function stopReview(cwd, config, attempt, sessionBaseline) {
         ? result.gateErrors.map(id => ({ id, title: 'A check could not run', details: id === 'typed-checks-unavailable' && result.typedError ? result.typedError : `${id} crashed instead of running`, severity: 'high', files: [], hint: 'Fix the environment (dependencies, generated config), then try again.' }))
         : [];
     const blocking = [...result.findings, ...whole, ...crashed];
-    const unreviewed = config.hooks?.require_review_ack ? buildReviewTask(cwd, diff, config.gates.deep?.router).items : [];
-    const reviewed = { findings: result.findings, reviewedFiles: Object.keys(result.changedLines), against };
+    const task = buildReviewTask(cwd, diff, config.gates.deep?.router, config.gates.deep?.review_lessons, config.gates.deep?.repo_rules ?? false);
+    const unreviewed = config.hooks?.require_review_ack ? task.items : [];
+    const reviewed = { findings: result.findings, reviewedFiles: Object.keys(result.changedLines), against, guidance: teamGuidance(task) };
     if (blocking.length === 0 && unreviewed.length === 0)
         return { block: false, message: '', blocking: 0, ...reviewed };
     const message = [
@@ -37,6 +55,22 @@ export async function stopReview(cwd, config, attempt, sessionBaseline) {
     ].join('\n\n');
     return { block: true, message, blocking: blocking.length + unreviewed.length, ...reviewed };
 }
+/** Each lesson and rule once, keyed by its text so the same one is never asked twice in a session. */
+function teamGuidance(task) {
+    const key = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
+    return [
+        ...task.lessons.map(l => ({ key: key(`lesson\u0000${l.file}\u0000${l.text}`), text: describeLesson(l) })),
+        ...task.rules.map(r => ({ key: key(`rule\u0000${r.source}\u0000${r.text}`), text: `${r.source}: ${r.text}` })),
+    ];
+}
+/** Asked once per new lesson or rule: the senior's question at the end of the task, never a loop. */
+export function teamMessage(guidance) {
+    return [
+        'Before you finish, check this change against what this team learned on earlier work that applies to it.',
+        'If the change repeats one, fix it; if none applies, say so in one line and finish:',
+        ...guidance.slice(0, MAX_LISTED).map(g => `- ${g.text}`),
+    ].join('\n');
+}
 export function reviewAckMessage(items, attempt) {
     const listed = items.slice(0, MAX_LISTED).map(i => `- ${i.file}:${i.start} \`${i.function}\`: ${i.questions[0]}`);
     return [

package/dist/index.d.ts

@@ -26,7 +26,7 @@ export { buildReviewTask, type ReviewTask, type ReviewTaskItem } from './review/
 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, itemLine, type ReviewerOptions, type ReviewerResult, type ReviewerOutcome, type OpenItem } from './review/reviewer.js';
+export { runReviewer, reviewerBlocks, itemLine, defaultExec, githubToken, 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';
@@ -38,8 +38,10 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction, type Funct
 export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
 export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
-export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, lessonsPath, type ReviewLesson } from './review-learning/lessons.js';
+export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { readLessons, writeLessons, decideLesson, lessonState, 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';
 export { diffFromGit, GitDiffError, type DiffSource } from './review/git-diff.js';
 export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';

package/dist/index.js

@@ -26,7 +26,7 @@ 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, itemLine } from './review/reviewer.js';
+export { runReviewer, reviewerBlocks, itemLine, defaultExec, githubToken } 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';
@@ -38,8 +38,10 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction } from './d
 export { routeFiles } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
 export { learnFromReviews } from './review-learning/learn-from-reviews.js';
-export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
+export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { readLessons, writeLessons, decideLesson, lessonState, 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';
 export { diffFromGit, GitDiffError } from './review/git-diff.js';
 export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';

package/dist/review/backtest-init.js

@@ -8,12 +8,12 @@
 import fs from 'fs';
 import path from 'path';
 import { branchBase } from '../gates/logic-drift-git-base.js';
+import { bodyPoints, firstLine } from '../review-learning/review-points.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 });
@@ -38,11 +38,11 @@ export async function scaffoldLedger(cwd, pr, config, exec = defaultExec) {
         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 });
+        const base = await baseAt(cwd, String(review.commit_id), review.submitted_at, mainRef, exec);
         rounds.push({
             id: `pr${pr}-r${round}`,
             commit: String(review.commit_id),
-            base: base.stdout.trim() || mainRef,
+            base,
             reviewed_at: String(review.submitted_at),
             pr,
             points,
@@ -66,14 +66,6 @@ function inlinePoint(id, comment) {
         ...(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, '\\$&');
 }
@@ -85,3 +77,13 @@ function existingLedger(file) {
         throw new Error(`${LEDGER_PATH} exists but is not a ledger; fix or remove it first`);
     return parsed.data;
 }
+/**
+ * What the reviewer saw the change against: the merge-base of the reviewed commit and main as of the review.
+ * Not main itself: a branch that merged main in already has main's newer commits, and diffing from an older
+ * main would review them as the branch's own. Main as of the review when the commit is not fetched here.
+ */
+async function baseAt(cwd, commit, reviewedAt, mainRef, exec) {
+    const main = (await exec('git', ['rev-list', '-1', `--before=${reviewedAt}`, mainRef], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim() || mainRef;
+    const mergeBase = await exec('git', ['merge-base', commit, main], { cwd, timeoutMs: GH_TIMEOUT_MS });
+    return (mergeBase.exitCode === 0 && mergeBase.stdout.trim()) || main;
+}

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

@@ -20,8 +20,14 @@ const INLINE = [
 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 (command === 'git') {
+            try {
+                return { exitCode: 0, stdout: execFileSync('git', args, { cwd: options.cwd, encoding: 'utf8', stdio: 'pipe' }), stderr: '' };
+            }
+            catch (error) {
+                return { exitCode: error.status ?? 1, stdout: '', stderr: String(error.stderr ?? '') };
+            }
+        }
         if (args[0] === 'auth')
             return { exitCode: 0, stdout: 'token\n', stderr: '' };
         if (args[0] === 'pr')
@@ -43,6 +49,24 @@ beforeEach(() => {
 });
 afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
 describe('rigour backtest init', () => {
+    it('takes the base from where the reviewed commit left main, not from main as of the review', async () => {
+        const forked = git('rev-parse', 'HEAD');
+        git('checkout', '-q', '-b', 'feature');
+        fs.writeFileSync(path.join(repo, 'b.ts'), 'export const b = 1;\n');
+        git('add', '-A');
+        execFileSync('git', ['-C', repo, 'commit', '-qm', 'the branch'], { env: { ...process.env, GIT_COMMITTER_DATE: '2026-04-12T09:30:00Z', GIT_AUTHOR_DATE: '2026-04-12T09:30:00Z' } });
+        const reviewed = git('rev-parse', 'HEAD');
+        git('checkout', '-q', 'main');
+        fs.writeFileSync(path.join(repo, 'c.ts'), 'export const c = 1;\n');
+        git('add', '-A');
+        execFileSync('git', ['-C', repo, 'commit', '-qm', 'main moves on before the review'], { env: { ...process.env, GIT_COMMITTER_DATE: '2026-04-12T11:00:00Z', GIT_AUTHOR_DATE: '2026-04-12T11:00:00Z' } });
+        const realCommit = (calls) => async (command, args, options) => {
+            const answer = await fakeExec(calls)(command, args, options);
+            return command === 'gh' && args[1]?.endsWith('/reviews') ? { ...answer, stdout: JSON.stringify(REVIEWS.map(r => ({ ...r, commit_id: reviewed }))) } : answer;
+        };
+        const { rounds } = await scaffoldLedger(repo, 212, config, realCommit([]));
+        expect(rounds[0].base).toBe(forked);
+    });
     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');

package/dist/review/backtest.js

@@ -13,6 +13,7 @@
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
+import { branchBase } from '../gates/logic-drift-git-base.js';
 import { reviewChange } from './review.js';
 import { defaultExec, runReviewer } from './reviewer.js';
 import { reviewerInputs } from './reviewer/context.js';
@@ -91,6 +92,9 @@ export async function runBacktest(cwd, config, ledger, options = {}) {
         const worktree = await worktreeFor(cwd, round.commit, exec);
         const head = (await exec('git', ['rev-parse', 'HEAD'], { cwd: worktree, timeoutMs: GIT_TIMEOUT_MS })).stdout.trim();
         progress(`backtest ${round.id}: ${head.slice(0, 9)} against ${round.base}${round.reviewed_at ? `, reviews hidden from ${round.reviewed_at}` : ''}`);
+        const stale = await staleBase(worktree, head, round.base, exec);
+        if (stale)
+            progress(`backtest ${round.id}: warning: ${stale}`);
         const collect = options.collect ?? ((tree, r, c) => collectItems(tree, r, c, !!options.reviewer, exec, progress));
         const { items, reviewerError, judged } = await collect(worktree, round, config);
         const result = { ...score(round, head, items, Date.now() - started, reviewerError), ...(judged ? { judges: judgeCatches(round, judged) } : {}) };
@@ -99,6 +103,25 @@ export async function runBacktest(cwd, config, ledger, options = {}) {
     }
     return results;
 }
+/**
+ * Why a round's base would review main's own commits as the branch's: the head already contains a newer
+ * main than the base (the branch merged main in), so the diff from the base carries everything main did since.
+ */
+async function staleBase(worktree, head, base, exec) {
+    const mainRef = branchBase(worktree)?.mainRef;
+    if (!mainRef)
+        return undefined;
+    const git = async (...args) => (await exec('git', args, { cwd: worktree, timeoutMs: GIT_TIMEOUT_MS })).stdout.trim();
+    const [mergeBase, baseSha] = await Promise.all([git('merge-base', head, mainRef), git('rev-parse', `${base}^{commit}`)]);
+    // A merged head is on main already: its merge-base with main is itself, and says nothing about the base.
+    if (!mergeBase || !baseSha || mergeBase === baseSha || mergeBase === head)
+        return undefined;
+    // Only a base strictly older than that main is stale; a newer one means the local main ref is the stale thing.
+    const older = await exec('git', ['merge-base', '--is-ancestor', baseSha, mergeBase], { cwd: worktree, timeoutMs: GIT_TIMEOUT_MS });
+    if (older.exitCode !== 0)
+        return undefined;
+    return `the head already contains ${mainRef} up to ${mergeBase.slice(0, 9)}, so diffing from ${base} reviews main's own commits as the branch's; set the base to ${mergeBase.slice(0, 9)}`;
+}
 /** Every point caught, nothing the reviewer called good flagged, and a verdict when the reviewer ran. */
 export function backtestPassed(results) {
     return results.every(r => r.points.every(p => p.caught) && r.falseBlocks.length === 0 && !r.reviewerError);
@@ -131,13 +154,22 @@ async function worktreeFor(cwd, commit, exec) {
         const reason = resolved.stderr.trim().split('\n').at(-1);
         throw new Error(`commit ${commit} is not in this repository (fetch the branch it was reviewed on)${reason ? `: git said "${reason}"` : ''}`);
     }
-    const dir = path.join(common, 'rigour-backtest', resolved.stdout.trim().slice(0, 12));
+    // One worktree, moved from round to round: a checkout per commit filled the disk on a backtest of dozens of pull requests.
+    const dir = path.join(common, 'rigour-backtest', 'checkout');
+    const sha = resolved.stdout.trim();
     if (!fs.existsSync(path.join(dir, '.git'))) {
         fs.mkdirSync(path.dirname(dir), { recursive: true });
-        const added = await exec('git', ['worktree', 'add', '--detach', dir, resolved.stdout.trim()], { cwd, timeoutMs: 5 * GIT_TIMEOUT_MS });
+        const added = await exec('git', ['worktree', 'add', '--detach', dir, sha], { cwd, timeoutMs: 5 * GIT_TIMEOUT_MS });
         if (added.exitCode !== 0)
             throw new Error(`could not check out ${commit} for the backtest: ${added.stderr.trim()}`);
     }
+    else {
+        const moved = await exec('git', ['checkout', '-q', '--detach', '--force', sha], { cwd: dir, timeoutMs: 5 * GIT_TIMEOUT_MS });
+        if (moved.exitCode !== 0)
+            throw new Error(`could not check out ${commit} for the backtest: ${moved.stderr.trim()}`);
+        // What the last round left behind (untracked files) must not reach this one; the linked dependencies stay.
+        await exec('git', ['clean', '-q', '-fdx', '-e', 'node_modules'], { cwd: dir, timeoutMs: GIT_TIMEOUT_MS });
+    }
     shareDependencies(cwd, dir);
     return dir;
 }
@@ -160,7 +192,7 @@ async function collectItems(worktree, round, config, reviewer, exec, progress) {
     ];
     if (!reviewer)
         return { items };
-    const result = await runReviewer(worktree, round.base, config, exec, progress, { pr: round.pr, reviewsBefore: round.reviewed_at, trigger: 'backtest', force: true, ...reviewerInputs(review) });
+    const result = await runReviewer(worktree, round.base, config, exec, progress, { pr: round.pr, reviewsBefore: round.reviewed_at, blind: round.pr === undefined, trigger: 'backtest', force: true, ...reviewerInputs(review) });
     if (result.outcome === 'unavailable' || result.outcome === 'skipped')
         return { items, reviewerError: result.reason ?? result.outcome };
     // The reviewer behind each catch is part of the score, so the gate is `reviewer:<name>`.

package/dist/review/backtest.test.js

@@ -104,7 +104,7 @@ describe('rigour backtest on a repository', () => {
                     ],
                     must_not_flag: [{ file: 'app\\.ts', lines: [1, 1] }],
                 }] }));
-        const config = ConfigSchema.parse({ version: 1 });
+        const config = ConfigSchema.parse({ version: 1, gates: { unused_exports: { block: true } } });
         const results = await runBacktest(repo, config, loadLedger(repo), { progress: () => undefined });
         expect(results).toHaveLength(1);
         expect(results[0].points).toMatchObject([{ id: 'R1-1', caught: true, by: 'unused-export src/lib/util.ts:1' }, { id: 'R1-2', caught: false, noted: false }]);
@@ -113,12 +113,54 @@ describe('rigour backtest on a repository', () => {
         expect(backtestPassed(results)).toBe(false);
         expect(git('branch', '--show-current')).toBe('main');
         expect(fs.existsSync(path.join(repo, 'src/lib/util.ts'))).toBe(false); // the checkout did not move
-        expect(fs.existsSync(path.join(repo, '.git/rigour-backtest', reviewed.slice(0, 12), 'src/lib/util.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(repo, '.git/rigour-backtest/checkout/src/lib/util.ts'))).toBe(true);
         expect(fs.readdirSync(path.join(repo, '.rigour/backtest'))).toEqual([`r1-${reviewed.slice(0, 12)}.json`]);
         // The worktree is reused on the next run.
         const again = await runBacktest(repo, config, loadLedger(repo), { round: 'r1', progress: () => undefined });
         expect(again[0].points[0].caught).toBe(true);
     }, 60_000); // a real worktree and a typed review: over 10s on a Windows runner
+    it('warns when the base is older than the main the head already merged in', async () => {
+        const forked = git('rev-parse', 'main');
+        git('checkout', '-q', 'main');
+        write('src/main-only.ts', 'export const later = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'main moves on');
+        const merged = git('rev-parse', 'HEAD');
+        git('checkout', '-q', 'feature');
+        git('merge', '-q', '--no-edit', 'main');
+        const reviewed = git('rev-parse', 'HEAD');
+        const config = ConfigSchema.parse({ version: 1 });
+        const run = async (base) => {
+            const lines = [];
+            const ledger = { rounds: [{ id: 'r1', commit: reviewed, base, points: [], must_not_flag: [] }] };
+            await runBacktest(repo, config, ledger, { progress: line => lines.push(line), collect: async () => ({ items: [] }) });
+            return lines.filter(line => line.includes('warning'));
+        };
+        expect(await run(forked)).toEqual([expect.stringContaining(`set the base to ${merged.slice(0, 9)}`)]);
+        expect(await run(merged)).toEqual([]);
+        git('update-ref', 'refs/heads/main', forked); // a local main older than the round's base: the ref is stale, not the base
+        expect(await run(merged)).toEqual([]);
+        git('update-ref', 'refs/heads/main', merged);
+        git('checkout', '-q', 'main');
+        git('merge', '-q', '--no-edit', 'feature'); // the pull request is merged: its head is on main now
+        expect(await run(merged)).toEqual([]);
+    }, 60_000);
+    it('moves one worktree from round to round, leaving nothing of the last round behind', async () => {
+        const reviewed = git('rev-parse', 'HEAD');
+        const base = git('rev-parse', 'main');
+        const seen = [];
+        const ledger = { rounds: [
+                { id: 'after', commit: reviewed, base, points: [], must_not_flag: [] },
+                { id: 'before', commit: base, base, points: [], must_not_flag: [] },
+            ] };
+        await runBacktest(repo, ConfigSchema.parse({ version: 1 }), ledger, { progress: () => undefined, collect: async (tree) => {
+                seen.push({ tree, util: fs.existsSync(path.join(tree, 'src/lib/util.ts')), leftover: fs.existsSync(path.join(tree, 'scratch.txt')) });
+                fs.writeFileSync(path.join(tree, 'scratch.txt'), 'left by a round');
+                return { items: [] };
+            } });
+        expect(seen.map(s => s.tree)).toEqual([seen[0].tree, seen[0].tree]);
+        expect(seen.map(s => [s.util, s.leftover])).toEqual([[true, false], [false, false]]);
+    }, 60_000);
     it('names a round or a commit it cannot find', async () => {
         const config = ConfigSchema.parse({ version: 1 });
         const ledger = { rounds: [{ id: 'r1', commit: '0000000000000000000000000000000000000000', base: 'main', points: [{ id: 'P', point: 'p', file: 'x', text: 'x' }], must_not_flag: [] }] };

package/dist/review/dead-code.test.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ConfigSchema } from '../types/index.js';
 import { diffFromGit } from './git-diff.js';
+import { mustFix } from './quiet.js';
 import { orphanFileFailures } from './orphan-files.js';
 import { unusedExportFailures } from './unused-exports.js';
 let repo;
@@ -87,6 +88,18 @@ describe('unused exports', () => {
         write('rigour-report.json', '{"failures":[{"details":"orphanName"}]}\n');
         expect(unusedExportFailures(repo, diffFromGit(repo), config())).toHaveLength(1);
     });
+    it('reports dead code as a note unless the team blocks on it', () => {
+        write('src/app.ts', 'export function start() {}\nexport function lonely() { return 1; }\n');
+        write('src/new-tool.ts', 'export const tool = 1;\n');
+        const found = (gates = {}) => [
+            ...unusedExportFailures(repo, diffFromGit(repo), config(gates)),
+            ...orphanFileFailures(repo, diffFromGit(repo), config(gates)),
+        ];
+        expect(found().map(f => [f.id, mustFix(f)])).toEqual(expect.arrayContaining([['unused-export', false], ['orphan-file', false]]));
+        const strict = found({ unused_exports: { block: true }, orphan_files: { block: true } });
+        expect(strict.length).toBeGreaterThan(0);
+        expect(strict.every(mustFix)).toBe(true);
+    });
     it('is off when disabled', () => {
         write('src/app.ts', 'export function start() {}\nexport const x = 1;\n');
         expect(unusedExportFailures(repo, diffFromGit(repo), config({ unused_exports: { enabled: false } }))).toEqual([]);

package/dist/review/orphan-files.js

@@ -41,7 +41,7 @@ export function orphanFileFailures(cwd, diff, config) {
     if (!files)
         return []; // git could not answer: say nothing rather than guess
     const referrers = referrersOf(cwd, added, files);
-    return [...unreferenced(added, referrers)].map(orphan);
+    return [...unreferenced(added, referrers)].map(file => orphan(file, !settings.block));
 }
 /** Tracked and new (untracked, not ignored) files. */
 function repositoryFiles(cwd) {
@@ -116,9 +116,10 @@ function unreferenced(added, referrers) {
     }
     return suspects;
 }
-function orphan(file) {
+function orphan(file, advisory) {
     return {
         id: 'orphan-file',
+        ...(advisory ? { advisory } : {}),
         title: 'Orphaned file',
         details: `\`${file}\` is new, but nothing outside the change's new files imports or runs it.`,
         severity: 'medium',

package/dist/review/quiet.d.ts

@@ -3,7 +3,7 @@ export declare const DISMISSED_FILE: string;
 export declare function isProven(failure: Failure): boolean;
 /**
  * What a change must fix: a proven finding, a critical one, or a high one the semantic engine
- * verified or a security gate found. The one rule behind the review's verdict, the stop hook and
+ * verified or a security gate found. Never one the team keeps as a note (`advisory`, from a check's `block: false`). The one rule behind the review's verdict, the stop hook and
  * the push gate, so the three never disagree about the same finding.
  */
 export declare function mustFix(failure: Failure): boolean;

package/dist/review/quiet.js

@@ -28,10 +28,12 @@ export function isProven(failure) {
 }
 /**
  * What a change must fix: a proven finding, a critical one, or a high one the semantic engine
- * verified or a security gate found. The one rule behind the review's verdict, the stop hook and
+ * verified or a security gate found. Never one the team keeps as a note (`advisory`, from a check's `block: false`). The one rule behind the review's verdict, the stop hook and
  * the push gate, so the three never disagree about the same finding.
  */
 export function mustFix(failure) {
+    if (failure.advisory)
+        return false;
     const severity = failure.severity ?? 'medium';
     return isProven(failure) || severity === 'critical' || (severity === 'high' && (failure.verified === true || failure.provenance === 'security'));
 }

package/dist/review/review-task.d.ts

@@ -10,7 +10,7 @@
  */
 import { type RouterPolicy } from '../deep/router.js';
 import { type ReviewedKey } from './ledger.js';
-import { type LessonMode } from '../review-learning/team-lessons.js';
+import { type LessonMode, type LessonView } from '../review-learning/team-lessons.js';
 export interface ReviewTaskItem {
     file: string;
     function: string;
@@ -26,11 +26,7 @@ export interface ReviewTask {
     /** Risky functions already reviewed at their current content. */
     alreadyReviewed: number;
     /** The team's past review lessons that apply to this change. */
-    lessons: Array<{
-        file: string;
-        text: string;
-        prs: number[];
-    }>;
+    lessons: LessonView[];
     /** The repository's own rules (AGENTS.md, …) that name what this change touches. */
     rules: Array<{
         source: string;

package/dist/review/review-task.js

@@ -12,7 +12,7 @@ import { DEFAULT_MAX_FUNCTIONS, DEFAULT_MIN_SCORE } from '../deep/router.js';
 import { rankChangedFunctions } from '../deep/risk.js';
 import { changedLinesByFile, parseDiff, removedByFile } from '../utils/diff.js';
 import { isReviewed, reviewedKeys } from './ledger.js';
-import { activeLessons, DEFAULT_LESSON_MODE, lessonsForDiff } from '../review-learning/team-lessons.js';
+import { activeLessons, DEFAULT_LESSON_MODE, lessonsForDiff, lessonView } from '../review-learning/team-lessons.js';
 import { rulesForDiff } from '../review-learning/repo-rules.js';
 const QUESTIONS = {
     'data-write': 'Is the write safe under concurrent calls (no check-then-act), idempotent on retry, and does an upsert/conflict clause do what the caller expects?',
@@ -28,7 +28,7 @@ export function buildReviewTask(cwd, diff, policy = {}, lessonMode = DEFAULT_LES
     const ranked = rankChangedFunctions(cwd, changedLinesByFile(changed), removedByFile(diff), activeLessons(cwd, lessonMode));
     const risky = ranked.filter(f => f.score >= (policy.min_score ?? DEFAULT_MIN_SCORE)).slice(0, policy.max_functions ?? DEFAULT_MAX_FUNCTIONS);
     const pending = risky.filter(f => !isReviewed(reviewed, { file: f.file, function: f.name, hash: f.hash }));
-    const lessons = lessonsForDiff(cwd, diff, lessonMode).map(l => ({ file: l.file, text: l.text, prs: [...new Set(l.evidence.map(e => e.pr))] }));
+    const lessons = lessonsForDiff(cwd, diff, lessonMode).map(lessonView);
     return {
         items: pending.map(toItem),
         alreadyReviewed: risky.length - pending.length,

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

@@ -16,6 +16,27 @@ export interface Adapter {
 export interface Spend {
     costUsd?: number;
     tokens?: Tokens;
+    trace?: RunTrace;
+}
+/**
+ * Where a run's tokens went, turn by turn, and what each tool call read: measurement only, never a
+ * decision. `category` is filled in by the reviewer, which knows its own input files and the change.
+ */
+export interface RunTrace {
+    turns: number;
+    usage: {
+        input: number;
+        cacheRead: number;
+        cacheWrite: number;
+        output: number;
+    };
+    calls: Array<{
+        turn: number;
+        tool: string;
+        target: string;
+        resultChars: number;
+        category?: 'rigour-input' | 'changed-file' | 'other-file' | 'git' | 'search' | 'other';
+    }>;
 }
 export interface Tokens {
     input: number;