@rigour-labs/core 6.5.4 → 6.6.1

package/dist/gates/deep-analysis.js

@@ -23,7 +23,7 @@ import { buildReviewTask } from '../review/review-task.js';
 import { reviewPullRequest } from '../deep/pr-review.js';
 import { relatedChanges } from '../deep/related-changes.js';
 import { rankChangedFunctions } from '../deep/risk.js';
-import { lessonsForDiff, lessonsSection } from '../review-learning/team-lessons.js';
+import { activeLessons, lessonsForDiff, lessonsSection } from '../review-learning/team-lessons.js';
 import { rulesForDiff, rulesSection } from '../review-learning/repo-rules.js';
 import { verifyCodeFindings } from '../deep/code-verifier.js';
 import { runIntentChecks } from './deep-intent.js';
@@ -153,7 +153,7 @@ export class DeepAnalysisGate extends Gate {
             this.config.onProgress?.('  Router: no risky change for the model; the gates cover this PR.');
             return [];
         }
-        const focus = buildReviewTask(cwd, options.diff, this.config.router).items;
+        const focus = buildReviewTask(cwd, options.diff, this.config.router, this.config.reviewLessons, false, trustedReviews(cwd, options)).items;
         const changedFiles = Object.keys(options.focusLines ?? {});
         const related = relatedChanges(cwd, changedFiles, rankChangedFunctions(cwd, options.focusLines ?? {}, options.removedLines));
         this.config.onProgress?.(`  Reviewing the PR as a whole (${focus.length} risky function(s) first)...`);
@@ -179,7 +179,7 @@ export class DeepAnalysisGate extends Gate {
         const { options } = this.config;
         if (!isCloud(options) || this.config.router?.enabled === false || !options.focusLines)
             return facts;
-        const routed = routeFiles(cwd, facts.map(f => f.path), options.focusLines, options.removedLines, this.config.router, trustedReviews(cwd, options));
+        const routed = routeFiles(cwd, facts.map(f => f.path), options.focusLines, options.removedLines, this.config.router, trustedReviews(cwd, options), activeLessons(cwd, this.config.reviewLessons));
         this.outcome.router = routed.stats;
         if (routed.stats.files_skipped > 0) {
             this.config.onProgress?.(`  Router: ${routed.stats.routed} of ${routed.stats.functions} changed function(s) to the model; ${routed.stats.files_skipped} file(s) left to the gates.`);

package/dist/hooks/checker.js

@@ -249,6 +249,24 @@ function checkSecurityPatterns(lines, relPath, failures) {
         checkHardcodedSecrets(line, i, relPath, isTestFile, failures);
         checkCommandInjection(line, i, relPath, failures);
     }
+    if (!isTestFile)
+        checkVendorKeys(lines.join('\n'), relPath, failures);
+}
+/** Credential formats a vendor issues: unambiguous in code, unlike entropy or variable-name guesses. */
+const VENDOR_KEYS = new Set(['aws_access_key', 'openai_key', 'anthropic_key', 'github_token', 'stripe_key', 'slack_token', 'sendgrid_key', 'private_key', 'private_key_full']);
+/** A real vendor key written into code, whatever the variable is called. */
+function checkVendorKeys(content, relPath, failures) {
+    for (const detection of scanInputForCredentials(content).detections) {
+        if (!VENDOR_KEYS.has(detection.type) || !detection.position)
+            continue;
+        const raw = content.slice(detection.position.start, detection.position.end);
+        if (/^pk_|_test_/.test(raw))
+            continue; // publishable and test keys are meant to be shared
+        const line = content.slice(0, detection.position.start).split('\n').length;
+        if (failures.some(f => f.gate === 'security-patterns' && f.line === line))
+            continue;
+        failures.push({ gate: 'security-patterns', file: relPath, message: `${detection.description} in code`, severity: 'critical', line });
+    }
 }
 function checkHardcodedSecrets(line, i, relPath, isTestFile, failures) {
     if (isTestFile) {

package/dist/hooks/checker.test.js

@@ -51,6 +51,16 @@ describe('runHookChecker', () => {
         expect(result.status).toBe('fail');
         expect(result.failures[0]).toMatchObject({ gate: 'file-guard', severity: 'critical' });
     });
+    it('catches a real vendor key whatever it is named, and leaves publishable and test keys alone', async () => {
+        // Built at runtime: a key-shaped literal in this source would be (rightly) refused by secret scanning.
+        const fake = (prefix) => `${prefix}_${'51HxQ'}${'abcdefghijklmnopqrstuv'}`;
+        fs.writeFileSync(path.join(testDir, 'pay.ts'), `export const stripe = {\n  value: "${fake('sk_live')}",\n};\n`);
+        fs.writeFileSync(path.join(testDir, 'public.ts'), `export const key = "${fake('pk_live')}";\nexport const t = "${fake('sk_test')}";\n`);
+        const leaked = await runHookChecker({ cwd: testDir, files: ['pay.ts'] });
+        expect(leaked.failures).toEqual([expect.objectContaining({ gate: 'security-patterns', line: 2, severity: 'critical', message: 'Stripe API key detected in code' })]);
+        const fine = await runHookChecker({ cwd: testDir, files: ['public.ts'] });
+        expect(fine.failures.filter(f => f.gate === 'security-patterns')).toEqual([]);
+    });
     it('should detect file size violations', async () => {
         const filePath = path.join(testDir, 'big.ts');
         const lines = Array.from({ length: 100 }, (_, i) => `export const v${i} = ${i};`);

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMIS
 export { isGeneratedFile } from './review/generated-files.js';
 export { countUsage, 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 { 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';
 export { rankChangedFunctions, scoreRisk, functionHash, findFunction, type FunctionRisk, type RiskSignals } from './deep/risk.js';
@@ -29,8 +30,10 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.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, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';
-export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, listOpenFindings, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
+export { appendStory, readStories, compactDiff, STORIES_FILE, type Story, type CatchStage } from './review/stories.js';
+export { recordLessonsServed, recordPrCatches, recordReuseSuggested, type LessonChannel } from './review/learning-events.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys, type AgentEvent, type ReviewEffectiveness } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
@@ -46,6 +49,7 @@ export { isModelCached, getModelsDir, getModelInfo, getCachedModel, ensureModel
 export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './inference/llama-engine.js';
 export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
+export { cleanContextCache, deadCacheRows, type CacheCleanupReport } from './storage/index.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 export type { RigourDB, CompactResult } from './storage/index.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, quietSplit, DISMIS
 export { isGeneratedFile } from './review/generated-files.js';
 export { countUsage, 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 { acknowledgeReview } from './review/review-ack.js';
 export { exportReviewed, readLedger, reviewedKeys, isReviewed, recordReview, REVIEWED_FILE } from './review/ledger.js';
 export { rankChangedFunctions, scoreRisk, functionHash, findFunction } from './deep/risk.js';
@@ -29,8 +30,10 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.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, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';
-export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount } from './review/agent-fixes.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, listOpenFindings } from './review/agent-fixes.js';
+export { appendStory, readStories, compactDiff, STORIES_FILE } from './review/stories.js';
+export { recordLessonsServed, recordPrCatches, recordReuseSuggested } from './review/learning-events.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
@@ -47,6 +50,7 @@ export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG }
 export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 // Storage (SQLite Brain)
+export { cleanContextCache, deadCacheRows } from './storage/index.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';

package/dist/review/agent-fixes.d.ts

@@ -1,4 +1,18 @@
 import type { Failure } from '../types/index.js';
+import { type CatchStage } from './stories.js';
+interface OpenFinding {
+    file: string;
+    rule: string;
+    /** What the finding said; absent in entries captured before it was kept. */
+    title?: string;
+    details?: string;
+    before: string;
+    openedAt: string;
+    /** The stage that first reported it; absent in entries captured before stages were kept. */
+    stage?: CatchStage;
+    /** Its dismissal key (quiet.ts): a finding someone dismissed was not fixed. */
+    key?: string;
+}
 export interface ResolvedFix {
     id: string;
     file: string;
@@ -8,6 +22,9 @@ export interface ResolvedFix {
     before: string;
     after: string;
     resolvedAt: string;
+    stage?: CatchStage;
+    /** When the finding was first reported, for time to fix. */
+    openedAt?: string;
 }
 export interface FixCapture {
     opened: number;
@@ -15,8 +32,14 @@ export interface FixCapture {
     /** The fixes this review resolved, for turning into lessons (storage/fix-lessons.ts). */
     fixes: ResolvedFix[];
 }
-/** Record a review's findings: open new ones, resolve open ones the review no longer reports. */
-export declare function recordReviewOutcome(cwd: string, findings: Failure[], reviewedFiles: string[]): FixCapture;
+/**
+ * Record a review's findings: open new ones, resolve open ones the review no longer reports.
+ * Each resolved fix is also kept as a story, credited to the stage that first reported it.
+ */
+export declare function recordReviewOutcome(cwd: string, findings: Failure[], reviewedFiles: string[], stage?: CatchStage): FixCapture;
 export declare function listResolvedFixes(cwd: string): ResolvedFix[];
 export declare function removeResolvedFix(cwd: string, id: string): void;
 export declare function openFindingCount(cwd: string): number;
+/** Findings reported and not fixed yet, newest first: what still needs someone. */
+export declare function listOpenFindings(cwd: string): Array<Omit<OpenFinding, 'before'>>;
+export {};

package/dist/review/agent-fixes.js

@@ -14,24 +14,37 @@ import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { checkId, recordOutcome } from './check-outcomes.js';
+import { appendStory, compactDiff } from './stories.js';
+import { dismissedKeys, findingKey } from './quiet.js';
 const DIR = path.join('.rigour', 'agent-fixes');
 const MAX_FILE_BYTES = 200_000;
 const OPEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-/** Record a review's findings: open new ones, resolve open ones the review no longer reports. */
-export function recordReviewOutcome(cwd, findings, reviewedFiles) {
+/**
+ * Record a review's findings: open new ones, resolve open ones the review no longer reports.
+ * Each resolved fix is also kept as a story, credited to the stage that first reported it.
+ */
+export function recordReviewOutcome(cwd, findings, reviewedFiles, stage = 'review') {
     const open = readOpen(cwd);
     const current = new Map(findings.flatMap(f => (f.files?.[0] ? [[`${f.id}:${f.files[0]}`, f]] : [])));
     const fixes = resolveGone(cwd, open, current, new Set(reviewedFiles));
-    const opened = openNew(cwd, open, current);
+    for (const fix of fixes) {
+        appendStory(cwd, { at: fix.resolvedAt, openedAt: fix.openedAt, stage: fix.stage ?? stage, file: fix.file, rule: fix.rule, title: fix.title ?? fix.rule, details: fix.details, diff: compactDiff(fix.before, fix.after) });
+    }
+    const opened = openNew(cwd, open, current, stage);
     writeOpen(cwd, open);
     return { opened, resolved: fixes.length, fixes };
 }
 /** Open findings this review no longer reports: resolved when their file was reviewed and changed. */
 function resolveGone(cwd, open, current, reviewed) {
     const resolved = [];
+    const dismissed = dismissedKeys(cwd);
     for (const [key, entry] of Object.entries(open)) {
         if (current.has(key))
             continue;
+        if (entry.key && dismissed.has(entry.key)) {
+            delete open[key]; // gone because a person dismissed it, not because anyone fixed it
+            continue;
+        }
         if (!reviewed.has(entry.file)) {
             if (Date.now() - Date.parse(entry.openedAt) > OPEN_TTL_MS)
                 delete open[key];
@@ -46,7 +59,7 @@ function resolveGone(cwd, open, current, reviewed) {
     }
     return resolved;
 }
-function openNew(cwd, open, current) {
+function openNew(cwd, open, current, stage) {
     let opened = 0;
     for (const [key, finding] of current) {
         if (open[key])
@@ -55,7 +68,7 @@ function openNew(cwd, open, current) {
         const before = readSmall(cwd, file);
         if (before === null)
             continue;
-        open[key] = { file, rule: finding.id, title: finding.title, details: finding.details, before, openedAt: new Date().toISOString() };
+        open[key] = { file, rule: finding.id, title: finding.title, details: finding.details, before, openedAt: new Date().toISOString(), stage, key: findingKey(finding) };
         opened++;
     }
     return opened;
@@ -79,6 +92,14 @@ export function removeResolvedFix(cwd, id) {
 export function openFindingCount(cwd) {
     return Object.keys(readOpen(cwd)).length;
 }
+/** Findings reported and not fixed yet, newest first: what still needs someone. */
+export function listOpenFindings(cwd) {
+    const dismissed = dismissedKeys(cwd);
+    return Object.values(readOpen(cwd))
+        .filter(entry => !(entry.key && dismissed.has(entry.key)))
+        .map(({ before: _before, ...rest }) => rest)
+        .sort((a, b) => b.openedAt.localeCompare(a.openedAt));
+}
 function readOpen(cwd) {
     try {
         return JSON.parse(fs.readFileSync(path.join(cwd, DIR, 'open.json'), 'utf8'));
@@ -98,7 +119,7 @@ function writeOpen(cwd, open) {
 }
 function writeResolved(cwd, entry, after) {
     const id = crypto.createHash('sha256').update(`${entry.rule}\0${entry.file}\0${entry.before}\0${after}`).digest('hex').slice(0, 16);
-    const fix = { id, file: entry.file, rule: entry.rule, title: entry.title, details: entry.details, before: entry.before, after, resolvedAt: new Date().toISOString() };
+    const fix = { id, file: entry.file, rule: entry.rule, title: entry.title, details: entry.details, before: entry.before, after, resolvedAt: new Date().toISOString(), ...(entry.stage ? { stage: entry.stage } : {}), openedAt: entry.openedAt };
     try {
         fs.mkdirSync(path.join(cwd, DIR, 'resolved'), { recursive: true });
         fs.writeFileSync(path.join(cwd, DIR, 'resolved', `${id}.json`), JSON.stringify(fix));

package/dist/review/effectiveness.d.ts

@@ -11,6 +11,19 @@ export interface AgentEvent {
     blocked?: boolean;
     /** Findings that blocked a stop. */
     blocking?: number;
+    /** lessons_served: where the agent got them, and their subjects (learning-events.ts). */
+    via?: string;
+    lessons?: string[];
+    /** pr_catches: what a branch review reported. */
+    findings?: Array<{
+        rule: string;
+        title: string;
+        file: string;
+    }>;
+    /** reuse_suggested: what the agent was about to write, what already exists, and BLOCK or WARN. */
+    planned?: string;
+    existing?: string;
+    action?: string;
 }
 export interface ReviewEffectiveness {
     toolCalls: Record<string, number>;

package/dist/review/learning-events.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The two events the learning loop is measured by, written to the same local event log as every
+ * agent event: a lesson put in front of an agent, and findings a PR-scope review reported.
+ * Studio joins them with stories (stories.ts) to show each lesson's path from where it was
+ * learned to whether the same mistake still reaches a PR.
+ */
+import type { Failure } from '../types/index.js';
+export type LessonChannel = 'recall' | 'context' | 'review';
+/** Lessons an agent was given before or while writing code. Nothing is written when none were. */
+export declare function recordLessonsServed(cwd: string, via: LessonChannel, subjects: string[]): void;
+/** Findings a review of a whole branch (what a PR contains) reported. Nothing is written when clean. */
+export declare function recordPrCatches(cwd: string, findings: Failure[]): void;
+/** The agent was about to write something that already exists, and was pointed to it. */
+export declare function recordReuseSuggested(cwd: string, planned: string, existing: string, action: 'BLOCK' | 'WARN'): void;

package/dist/review/learning-events.js

@@ -0,0 +1,21 @@
+import { appendAgentEvent } from './effectiveness.js';
+const MAX_LISTED = 20;
+/** Lessons an agent was given before or while writing code. Nothing is written when none were. */
+export function recordLessonsServed(cwd, via, subjects) {
+    const unique = [...new Set(subjects.filter(Boolean))].slice(0, MAX_LISTED);
+    if (unique.length)
+        appendAgentEvent(cwd, { type: 'lessons_served', via, lessons: unique });
+}
+/** Findings a review of a whole branch (what a PR contains) reported. Nothing is written when clean. */
+export function recordPrCatches(cwd, findings) {
+    if (findings.length === 0)
+        return;
+    appendAgentEvent(cwd, {
+        type: 'pr_catches',
+        findings: findings.slice(0, MAX_LISTED).map(f => ({ rule: f.id, title: f.title, file: f.files?.[0] ?? '' })),
+    });
+}
+/** The agent was about to write something that already exists, and was pointed to it. */
+export function recordReuseSuggested(cwd, planned, existing, action) {
+    appendAgentEvent(cwd, { type: 'reuse_suggested', planned, existing, action });
+}

package/dist/review/receipt.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The quality receipt for a change: for every changed function outside tests, what is known about
+ * it before a model looks at anything.
+ *
+ * - reviewed: risky, and reviewed at its current code during development (the ledger or a
+ *   committed reviewed.json, keyed by the function's exact source);
+ * - changed since review: risky, reviewed once, then edited, so that review no longer counts;
+ * - low risk: below the router's bar, left to the deterministic checks;
+ * - not covered: risky with no review of this code. These are what a PR review should spend on.
+ *
+ * Reviews are agents' and people's own records. An independent (enforcing) review does not count
+ * them, and the receipt says how many it set aside rather than hiding them.
+ */
+import { type RouterPolicy } from '../deep/router.js';
+import { type LessonMode } from '../review-learning/team-lessons.js';
+export interface ReceiptGap {
+    file: string;
+    function: string;
+    start: number;
+    score: number;
+    /** Reviewed once, then edited. */
+    changedSinceReview: boolean;
+    /** The team lesson that made it risky, when one did. */
+    lesson?: string;
+}
+export interface QualityReceipt {
+    functions: number;
+    reviewed: number;
+    changedSinceReview: number;
+    lowRisk: number;
+    notCovered: ReceiptGap[];
+    /** Who reviewed the functions counted as reviewed: agent, human, or byok:<model>. */
+    reviewers: Record<string, number>;
+    /** Changed files Rigour cannot split into functions (other languages, config): rules only. */
+    otherFiles: number;
+    /** Self-reported reviews an independent review did not count. */
+    setAside: number;
+}
+export interface ReceiptOptions {
+    policy?: RouterPolicy;
+    lessonMode?: LessonMode;
+    /** Trust nothing the change itself recorded (enforce mode). */
+    independent?: boolean;
+}
+export declare function buildQualityReceipt(cwd: string, diff: string, options?: ReceiptOptions): QualityReceipt;
+/** The receipt as reports carry it (snake_case, like the rest of `rigour review --json` and the MCP tool). */
+export declare function receiptReport(r: QualityReceipt): {
+    functions: number;
+    reviewed: number;
+    changed_since_review: number;
+    low_risk: number;
+    not_covered: {
+        lesson?: string | undefined;
+        file: string;
+        function: string;
+        line: number;
+        score: number;
+        changed_since_review: boolean;
+    }[];
+    reviewers: Record<string, number>;
+    other_files: number;
+    set_aside: number;
+};

package/dist/review/receipt.js

@@ -0,0 +1,73 @@
+/**
+ * The quality receipt for a change: for every changed function outside tests, what is known about
+ * it before a model looks at anything.
+ *
+ * - reviewed: risky, and reviewed at its current code during development (the ledger or a
+ *   committed reviewed.json, keyed by the function's exact source);
+ * - changed since review: risky, reviewed once, then edited, so that review no longer counts;
+ * - low risk: below the router's bar, left to the deterministic checks;
+ * - not covered: risky with no review of this code. These are what a PR review should spend on.
+ *
+ * Reviews are agents' and people's own records. An independent (enforcing) review does not count
+ * them, and the receipt says how many it set aside rather than hiding them.
+ */
+import { DEFAULT_MIN_SCORE } from '../deep/router.js';
+import { rankChangedFunctions } from '../deep/risk.js';
+import { activeLessons, DEFAULT_LESSON_MODE } from '../review-learning/team-lessons.js';
+import { changedLinesByFile, parseDiff, removedByFile } from '../utils/diff.js';
+import { isReviewed, readLedger, reviewedKeys } from './ledger.js';
+const PARSEABLE = /\.(?:[cm]?[jt]sx?)$/i;
+export function buildQualityReceipt(cwd, diff, options = {}) {
+    const changed = changedLinesByFile(parseDiff(diff));
+    const ranked = rankChangedFunctions(cwd, changed, removedByFile(diff), activeLessons(cwd, options.lessonMode ?? DEFAULT_LESSON_MODE));
+    const minScore = options.policy?.min_score ?? DEFAULT_MIN_SCORE;
+    const risky = ranked.filter(f => f.score >= minScore);
+    const recorded = reviewedKeys(cwd);
+    const trusted = options.independent ? [] : recorded;
+    const reviewedNow = risky.filter(f => isReviewed(trusted, keyOf(f)));
+    const gaps = risky.filter(f => !isReviewed(trusted, keyOf(f)));
+    return {
+        functions: ranked.length,
+        reviewed: reviewedNow.length,
+        changedSinceReview: gaps.filter(f => reviewedBefore(recorded, f)).length,
+        lowRisk: ranked.length - risky.length,
+        notCovered: gaps.map(f => ({
+            file: f.file, function: f.name, start: f.start, score: f.score,
+            changedSinceReview: reviewedBefore(recorded, f),
+            ...(f.signals.lesson ? { lesson: f.signals.lesson } : {}),
+        })),
+        reviewers: reviewersOf(cwd, reviewedNow),
+        otherFiles: Object.keys(changed).filter(file => !PARSEABLE.test(file)).length,
+        setAside: options.independent ? risky.filter(f => isReviewed(recorded, keyOf(f))).length : 0,
+    };
+}
+function keyOf(f) {
+    return { file: f.file, function: f.name, hash: f.hash };
+}
+/** Some version of this function was reviewed, just not the code it has now. */
+function reviewedBefore(recorded, f) {
+    return recorded.some(r => r.file === f.file && r.function === f.name && r.hash !== f.hash);
+}
+function reviewersOf(cwd, reviewed) {
+    const ledger = readLedger(cwd);
+    const counts = {};
+    for (const f of reviewed) {
+        const entry = [...ledger].reverse().find(e => e.file === f.file && e.function === f.name && e.hash === f.hash);
+        const who = entry ? (entry.reviewer.startsWith('byok:') ? 'model' : entry.reviewer) : 'recorded';
+        counts[who] = (counts[who] ?? 0) + 1;
+    }
+    return counts;
+}
+/** The receipt as reports carry it (snake_case, like the rest of `rigour review --json` and the MCP tool). */
+export function receiptReport(r) {
+    return {
+        functions: r.functions,
+        reviewed: r.reviewed,
+        changed_since_review: r.changedSinceReview,
+        low_risk: r.lowRisk,
+        not_covered: r.notCovered.map(g => ({ file: g.file, function: g.function, line: g.start, score: g.score, changed_since_review: g.changedSinceReview, ...(g.lesson ? { lesson: g.lesson } : {}) })),
+        reviewers: r.reviewers,
+        other_files: r.otherFiles,
+        set_aside: r.setAside,
+    };
+}

package/dist/review/receipt.test.d.ts

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

package/dist/review/receipt.test.js

@@ -0,0 +1,60 @@
+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 { findFunction } from '../deep/risk.js';
+import { diffFromGit } from './git-diff.js';
+import { recordReview } from './ledger.js';
+import { buildQualityReceipt } from './receipt.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+const write = (rel, body) => { fs.mkdirSync(path.dirname(path.join(repo, rel)), { recursive: true }); fs.writeFileSync(path.join(repo, rel), body); };
+const review = (file, fn, reviewer = 'agent') => {
+    const found = findFunction(repo, file, fn);
+    recordReview(repo, { file, function: fn, hash: found.hash, reviewer, verdict: 'no_issue', note: 'checked' });
+};
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'receipt-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('.gitignore', '.rigour/\n');
+    write('src/pay.ts', 'export const x = 1;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+});
+afterEach(() => fs.rmSync(repo, { recursive: true, force: true }));
+// Risky: a data write. Low risk: a formatter. Each in its own function.
+const RISKY = (n) => `export async function saveRefund${n}(db: any, cents: number) {\n  return db.insert({ cents: cents + ${n} });\n}\n`;
+const PLAIN = 'export function label(name: string) {\n  return name.trim();\n}\n';
+describe('buildQualityReceipt', () => {
+    it('says what was reviewed at its current code, what changed after review, what is low risk, and what is not covered', () => {
+        write('src/pay.ts', RISKY(1) + RISKY(2) + RISKY(3) + PLAIN);
+        write('config/app.yml', 'a: 1\n');
+        review('src/pay.ts', 'saveRefund1');
+        review('src/pay.ts', 'saveRefund2');
+        write('src/pay.ts', RISKY(1) + RISKY(2).replace('cents + 2', 'cents + 20') + RISKY(3) + PLAIN); // edited after its review
+        const receipt = buildQualityReceipt(repo, diffFromGit(repo));
+        expect(receipt).toMatchObject({ functions: 4, reviewed: 1, changedSinceReview: 1, lowRisk: 1, otherFiles: 1, setAside: 0, reviewers: { agent: 1 } });
+        expect(receipt.notCovered.map(g => [g.function, g.changedSinceReview])).toEqual([['saveRefund2', true], ['saveRefund3', false]]);
+    });
+    it('counts no self-reported review when independent, and says how many it set aside', () => {
+        write('src/pay.ts', RISKY(1) + RISKY(2));
+        review('src/pay.ts', 'saveRefund1');
+        const receipt = buildQualityReceipt(repo, diffFromGit(repo), { independent: true });
+        expect(receipt).toMatchObject({ reviewed: 0, setAside: 1 });
+        expect(receipt.notCovered).toHaveLength(2);
+    });
+    it('treats a function matching a verified team lesson as risky, and says which lesson', () => {
+        write('src/pay.ts', 'export function formatTotal(totalCents: number) {\n  return (totalCents / 100).toFixed(2);\n}\n');
+        write('.rigour/review-lessons.json', JSON.stringify({ version: 1, lessons: [{
+                    id: 'l1', text: 'Format money from integer cents, never floats.', file: 'src/pay.ts', symbols: ['totalCents'],
+                    state: 'verified', evidence: [{ pr: 12, comment: 'c', author: 'reviewer' }], createdAt: '', updatedAt: '',
+                }] }));
+        const withLesson = buildQualityReceipt(repo, diffFromGit(repo));
+        expect(withLesson.notCovered).toEqual([expect.objectContaining({ function: 'formatTotal', lesson: 'Format money from integer cents, never floats.' })]);
+        expect(buildQualityReceipt(repo, diffFromGit(repo), { lessonMode: 'off' }).notCovered).toEqual([]);
+    });
+});

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

@@ -9,6 +9,7 @@
  * pre-empted four times as many acted-on review comments as chunked prompts.
  */
 import { type RouterPolicy } from '../deep/router.js';
+import { type ReviewedKey } from './ledger.js';
 import { type LessonMode } from '../review-learning/team-lessons.js';
 export interface ReviewTaskItem {
     file: string;
@@ -37,4 +38,5 @@ export interface ReviewTask {
     }>;
     instructions: string;
 }
-export declare function buildReviewTask(cwd: string, diff: string, policy?: RouterPolicy, lessonMode?: LessonMode, repoRules?: boolean): ReviewTask;
+/** `reviewed`: the reviews to trust; an independent (enforcing) review passes none, so self-reported reviews skip nothing. */
+export declare function buildReviewTask(cwd: string, diff: string, policy?: RouterPolicy, lessonMode?: LessonMode, repoRules?: boolean, reviewed?: ReviewedKey[]): ReviewTask;

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 { lessonsForDiff } from '../review-learning/team-lessons.js';
+import { activeLessons, DEFAULT_LESSON_MODE, lessonsForDiff } 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?',
@@ -22,11 +22,11 @@ const QUESTIONS = {
     concurrency: 'What happens if two calls overlap, or one step fails half-way through?',
     network: 'Are timeouts, aborts and non-2xx responses handled, and does a retry repeat a side effect?',
 };
-export function buildReviewTask(cwd, diff, policy = {}, lessonMode = 'off', repoRules = false) {
+/** `reviewed`: the reviews to trust; an independent (enforcing) review passes none, so self-reported reviews skip nothing. */
+export function buildReviewTask(cwd, diff, policy = {}, lessonMode = DEFAULT_LESSON_MODE, repoRules = false, reviewed = reviewedKeys(cwd)) {
     const changed = parseDiff(diff);
-    const ranked = rankChangedFunctions(cwd, changedLinesByFile(changed), removedByFile(diff));
+    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 reviewed = reviewedKeys(cwd);
     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))] }));
     return {
@@ -42,6 +42,7 @@ export function buildReviewTask(cwd, diff, policy = {}, lessonMode = 'off', repo
 }
 function toItem(f) {
     const questions = [
+        ...(f.signals.lesson ? [`Your team flagged this before: "${f.signals.lesson}" Does this change repeat it?`] : []),
         ...(f.signals.removedGuard ? ['The change removed a condition, return or throw here: which inputs did it guard against, and are they still handled?'] : []),
         ...f.signals.sensitive.map(kind => QUESTIONS[kind]).filter(Boolean),
         `Do the callers of \`${f.name}\` still get what they assume (types, empty and error cases)?`,

package/dist/review/review-task.test.js

@@ -8,6 +8,7 @@ import { acknowledgeReview } from './review-ack.js';
 import { buildReviewTask } from './review-task.js';
 import { exportReviewed, readLedger, REVIEWED_FILE } from './ledger.js';
 import { reviewAckMessage } from '../hooks/stop-review.js';
+import { writeLessons } from '../review-learning/lessons.js';
 let repo;
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
 const write = (body) => fs.writeFileSync(path.join(repo, 'sync.ts'), body);
@@ -51,6 +52,14 @@ describe('review task and acknowledgements', () => {
         expect(task.items[0].questions[0]).toMatch(/concurrent calls/);
         expect(task.items[0].questions.at(-1)).toContain('`syncOrders`');
     });
+    it('sends a function a verified team lesson names to review, and asks whether the change repeats it', () => {
+        write(AFTER.replace('name.trim()', 'name.toLocaleUpperCase()'));
+        writeLessons(repo, [{ id: 'l1', text: 'Locale casing breaks Turkish names.', file: 'sync.ts', symbols: ['toLocaleUpperCase'], state: 'verified', evidence: [{ pr: 7, comment: 'c1', author: 'r' }], createdAt: '', updatedAt: '' }]);
+        const task = buildReviewTask(repo, diffFromGit(repo));
+        const label = task.items.find(i => i.function === 'label');
+        expect(label?.questions[0]).toContain('Locale casing breaks Turkish names.');
+        expect(buildReviewTask(repo, diffFromGit(repo), {}, 'off').items.map(i => i.function)).toEqual(['syncOrders']);
+    });
     it('drops an acknowledged function from the task until its code changes again', () => {
         const ack = acknowledgeReview(repo, { file: 'sync.ts', function: 'syncOrders', verdict: 'no_issue', note: 'upsert key is the unique order id; callers retry safely' });
         expect(ack.ok).toBe(true);

package/dist/review/stories.d.ts

@@ -0,0 +1,25 @@
+/** Where a problem was caught: while the agent wrote, when it asked to review, when it tried to finish, at the PR. */
+export type CatchStage = 'edit' | 'review' | 'stop' | 'pr';
+export interface Story {
+    id: string;
+    /** When the agent fixed it. */
+    at: string;
+    /** When Rigour first reported it; absent in stories kept before this was recorded. */
+    openedAt?: string;
+    stage: CatchStage;
+    file: string;
+    rule: string;
+    title: string;
+    details?: string;
+    /** Changed lines with context, each prefixed ' ', '-' or '+'. */
+    diff: string[];
+}
+export declare const STORIES_FILE: string;
+export declare function appendStory(cwd: string, story: Omit<Story, 'id'>): void;
+/** Every story, oldest first; `since` keeps those at or after it. */
+export declare function readStories(cwd: string, since?: Date): Story[];
+/**
+ * The lines that changed between two versions of a file, with context: the common head and
+ * tail are trimmed and what is left between them is shown as removed then added.
+ */
+export declare function compactDiff(before: string, after: string): string[];