@rigour-labs/core 6.5.3 → 6.6.0

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/check-outcomes.d.ts

@@ -19,7 +19,8 @@ export declare function checkId(finding: {
 }): string;
 export declare function precisionOf(outcome: CheckOutcome): number;
 export declare function isMuted(outcome: CheckOutcome | undefined): boolean;
-export declare function readOutcomes(cwd: string): Record<string, CheckOutcome>;
+/** Outcomes in the working tree, or at `ref` for an independent review (trusted-state.ts). */
+export declare function readOutcomes(cwd: string, ref?: string): Record<string, CheckOutcome>;
 export declare function recordOutcome(cwd: string, check: string, kind: keyof CheckOutcome): void;
 /** Every check with an outcome, most dismissed first. */
 export declare function checkPrecisions(cwd: string): CheckPrecision[];

package/dist/review/check-outcomes.js

@@ -13,6 +13,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { readStateFile } from './trusted-state.js';
 const OUTCOMES_FILE = path.join('.rigour', 'check-outcomes.json');
 const REPORTED_FILE = path.join('.rigour', 'reported-findings.json');
 const MAX_REPORTED = 2000;
@@ -32,8 +33,16 @@ export function isMuted(outcome) {
         return false;
     return outcome.fixed + outcome.dismissed >= MUTE_MIN_OUTCOMES && precisionOf(outcome) < MUTE_BELOW;
 }
-export function readOutcomes(cwd) {
-    return readJson(path.join(cwd, OUTCOMES_FILE)) ?? {};
+/** Outcomes in the working tree, or at `ref` for an independent review (trusted-state.ts). */
+export function readOutcomes(cwd, ref) {
+    if (!ref)
+        return readJson(path.join(cwd, OUTCOMES_FILE)) ?? {};
+    try {
+        return JSON.parse(readStateFile(cwd, OUTCOMES_FILE, ref) ?? '{}');
+    }
+    catch {
+        return {};
+    }
 }
 export function recordOutcome(cwd, check, kind) {
     const outcomes = readOutcomes(cwd);

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/git-diff.d.ts

@@ -3,6 +3,9 @@ export type DiffSource = {
 } | {
     mode: 'base';
     base: string;
+} | {
+    mode: 'since';
+    commit: string;
 };
 export declare class GitDiffError extends Error {
 }

package/dist/review/git-diff.js

@@ -5,6 +5,8 @@
  *   git does not track yet (what an agent has just written).
  * - base: everything on this branch since it left `base` (the merge-base),
  *   including uncommitted changes (what a pull request contains).
+ * - since: everything after `commit`, committed or not, plus untracked files
+ *   (what an agent session wrote, even if it committed along the way).
  */
 import { spawnSync } from 'child_process';
 export class GitDiffError extends Error {
@@ -14,6 +16,9 @@ export function diffFromGit(cwd, source = { mode: 'working' }) {
         const mergeBase = git(cwd, ['merge-base', source.base, 'HEAD']).trim();
         return git(cwd, ['diff', '--no-color', '--no-ext-diff', mergeBase]);
     }
+    if (source.mode === 'since') {
+        return git(cwd, ['diff', '--no-color', '--no-ext-diff', source.commit]) + untrackedFiles(cwd).map(file => newFileDiff(cwd, file)).join('');
+    }
     const tracked = hasHead(cwd) ? git(cwd, ['diff', '--no-color', '--no-ext-diff', 'HEAD']) : '';
     return tracked + untrackedFiles(cwd).map(file => newFileDiff(cwd, file)).join('');
 }

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/migration-order.js

@@ -18,7 +18,7 @@ export function migrationOrderFailures(cwd, diff, source, config) {
     const settings = config.gates.migration_order;
     if (!settings?.enabled)
         return [];
-    const base = source?.mode === 'base' ? source.base : 'HEAD';
+    const base = source?.mode === 'base' ? source.base : source?.mode === 'since' ? source.commit : 'HEAD';
     const byDirectory = new Map();
     for (const file of addedFiles(diff)) {
         const directory = path.posix.dirname(file);

package/dist/review/quiet.d.ts

@@ -12,7 +12,8 @@ export interface QuietSplit {
     /** Which gates the dismissed findings came from: where Rigour is wrong for this team. */
     dismissedByGate: Record<string, number>;
 }
-export declare function quietSplit(cwd: string, findings: Failure[], includeHeuristics?: boolean): QuietSplit;
-export declare function dismissedKeys(cwd: string): Set<string>;
+/** `trustedRef`: read dismissals and outcomes as of that commit, not as the change left them. */
+export declare function quietSplit(cwd: string, findings: Failure[], includeHeuristics?: boolean, trustedRef?: string): QuietSplit;
+export declare function dismissedKeys(cwd: string, ref?: string): Set<string>;
 /** Record "not a bug" for a finding key; idempotent. */
 export declare function dismissFinding(cwd: string, key: string, reason: string, at?: string): boolean;

package/dist/review/quiet.js

@@ -11,12 +11,15 @@
  * blocking. A team that wants them back sets review.include_heuristics.
  *
  * A finding a person judged "not a bug" is dismissed by its key and never
- * reported again (.rigour/dismissed.json, meant to be committed).
+ * reported again (.rigour/dismissed.json, meant to be committed). An
+ * independent review reads it from the base (trusted-state.ts), so a change
+ * cannot dismiss its own findings.
  */
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { checkId, isMuted, readOutcomes, recordOutcome, reportedCheck } from './check-outcomes.js';
+import { readStateFile } from './trusted-state.js';
 const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests']);
 export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');
 export function isProven(failure) {
@@ -26,9 +29,10 @@ export function isProven(failure) {
 export function findingKey(failure) {
     return crypto.createHash('sha256').update(`${failure.id}\u0000${failure.files?.[0] ?? ''}\u0000${failure.details}`).digest('hex').slice(0, 16);
 }
-export function quietSplit(cwd, findings, includeHeuristics = false) {
-    const dismissed = dismissedKeys(cwd);
-    const outcomes = readOutcomes(cwd);
+/** `trustedRef`: read dismissals and outcomes as of that commit, not as the change left them. */
+export function quietSplit(cwd, findings, includeHeuristics = false, trustedRef) {
+    const dismissed = dismissedKeys(cwd, trustedRef);
+    const outcomes = readOutcomes(cwd, trustedRef);
     const split = { speaking: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {} };
     for (const finding of findings) {
         if (dismissed.has(findingKey(finding))) {
@@ -44,9 +48,9 @@ export function quietSplit(cwd, findings, includeHeuristics = false) {
     }
     return split;
 }
-export function dismissedKeys(cwd) {
+export function dismissedKeys(cwd, ref) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, DISMISSED_FILE), 'utf8'));
+        const parsed = JSON.parse(readStateFile(cwd, DISMISSED_FILE, ref) ?? '');
         return new Set(Array.isArray(parsed?.entries) ? parsed.entries.map((e) => e?.key).filter((k) => typeof k === 'string') : []);
     }
     catch {

package/dist/review/review.d.ts

@@ -12,6 +12,8 @@ export interface ReviewInput {
     diffTests?: boolean;
     /** Deep analysis; `focusLines` and `removedLines` are filled from the diff. */
     deep?: Omit<DeepOptions, 'focusLines' | 'removedLines' | 'diff'>;
+    /** Read dismissals and check outcomes at this commit (the base), not as the change left them. */
+    trustedRef?: string;
 }
 export interface ReviewResult {
     status: 'PASS' | 'FAIL' | 'ERROR';
@@ -33,6 +35,8 @@ export interface ReviewResult {
     deepError?: string;
     /** Gates that crashed instead of running; a proven one makes the result ERROR. */
     gateErrors: string[];
+    /** rigour.yml or .rigour/ files this change edits: they steer the review, so they are called out. */
+    controlFilesChanged: string[];
 }
 export interface ReviewFinding {
     id: string;

package/dist/review/review.js

@@ -19,12 +19,13 @@ import { checkId, rememberReported } from './check-outcomes.js';
 import { diffFromGit } from './git-diff.js';
 import { diffTestFailures } from './diff-test-findings.js';
 import { migrationOrderFailures } from './migration-order.js';
+import { isControlFile } from './trusted-state.js';
 export async function reviewChange(input) {
     const diff = input.diff ?? diffFromGit(input.cwd, input.source);
     const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null, gateErrors: [] };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff) };
     }
     const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
     const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
@@ -33,7 +34,7 @@ export async function reviewChange(input) {
     report.failures.push(...migrationOrderFailures(input.cwd, diff, input.source, input.config));
     const split = splitByChangedLines(report.failures, changedLines, deep ? changedFunctionSpans(input.cwd, changedLines) : {}, removedByFile(diff));
     const deepError = deepAnalysisError(report);
-    const quiet = quietSplit(input.cwd, split.findings, input.config.review?.include_heuristics);
+    const quiet = quietSplit(input.cwd, split.findings, input.config.review?.include_heuristics, input.trustedRef);
     rememberReported(input.cwd, [...quiet.speaking, ...quiet.advisory].map(f => ({ key: findingKey(f), check: checkId(f) })));
     const gateErrors = crashedGates(report);
     const provenCrashed = gateErrors.some(id => isProven({ id }));
@@ -51,9 +52,20 @@ export async function reviewChange(input) {
         changedLines,
         report,
         gateErrors,
+        controlFilesChanged: controlFiles(diff),
         ...(deepError ? { deepError } : {}),
     };
 }
+/** Every path the diff touches (including deletions, which parseDiff drops) that steers Rigour itself. */
+function controlFiles(diff) {
+    const files = new Set();
+    for (const match of diff.matchAll(/^diff --git a\/(\S+) b\/(\S+)$/gm)) {
+        for (const file of [match[1], match[2]])
+            if (isControlFile(file))
+                files.add(file);
+    }
+    return [...files].sort();
+}
 function crashedGates(report) {
     return Object.entries(report.summary).filter(([, status]) => status === 'ERROR').map(([id]) => id);
 }

package/dist/review/review.test.js

@@ -10,6 +10,7 @@ import { splitByChangedLines } from './changed-lines.js';
 import { anchorInChangedFunction, changedFunctionSpans } from './changed-function-spans.js';
 import { diffFromGit } from './git-diff.js';
 import { reviewChange, toReviewFinding } from './review.js';
+import { findingKey } from './quiet.js';
 const LEAKY = [
     'export async function notify(endpoint: string, signature: string) {',
     "  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });",
@@ -114,6 +115,24 @@ describe('git-backed review', () => {
         expect(semantic.map(f => [f.files?.[0], f.line])).toEqual([['src/notify.ts', 2]]);
         expect(toReviewFinding(semantic[0])).toMatchObject({ id: 'semantic-bugs', file: 'src/notify.ts', line: 2, severity: 'high' });
     });
+    it('lets a change dismiss its own finding only when the review trusts the working tree', async () => {
+        write('src/old.ts', 'export const a = 1;\n');
+        write('.gitignore', '.rigour/*\n!.rigour/dismissed.json\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        git('checkout', '-q', '-b', 'pr');
+        write('src/notify.ts', LEAKY);
+        const config = ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: true } } });
+        const key = findingKey((await reviewChange({ cwd: repo, config })).findings[0]);
+        write('.rigour/dismissed.json', JSON.stringify({ version: 1, entries: [{ key, reason: 'trust me', at: 'now' }] }));
+        git('add', '-A');
+        git('commit', '-qm', 'pr');
+        const trusting = await reviewChange({ cwd: repo, config, source: { mode: 'base', base: 'main' } });
+        expect([trusting.status, trusting.dismissed]).toEqual(['PASS', 1]);
+        expect(trusting.controlFilesChanged).toEqual(['.rigour/dismissed.json']);
+        const independent = await reviewChange({ cwd: repo, config, source: { mode: 'base', base: 'main' }, trustedRef: 'main' });
+        expect([independent.status, independent.dismissed]).toEqual(['FAIL', 0]);
+    });
     it('runs every gate in a git worktree, where .git is a file', async () => {
         write('src/a.ts', 'export const a = 1;\n');
         git('add', '-A');

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[];

package/dist/review/stories.js

@@ -0,0 +1,75 @@
+/**
+ * What Rigour stopped, as people read it: one entry per problem an agent fixed after Rigour
+ * reported it, with the stage that caught it and the code change that fixed it.
+ *
+ * agent-fixes.ts keeps the before and after only until `rigour learn` turns them into rules;
+ * this log keeps a small, permanent summary for Studio. It never holds whole files: only the
+ * changed lines with a little context, capped.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+export const STORIES_FILE = path.join('.rigour', 'stories.jsonl');
+/** Kept on disk; older entries are dropped when the log is rewritten. */
+const MAX_STORIES = 500;
+const CONTEXT_LINES = 2;
+const MAX_DIFF_LINES = 40;
+const MAX_LINE_CHARS = 200;
+export function appendStory(cwd, story) {
+    const entry = { id: crypto.createHash('sha256').update(`${story.at}\0${story.file}\0${story.rule}`).digest('hex').slice(0, 16), ...story };
+    const file = path.join(cwd, STORIES_FILE);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        trim(file);
+    }
+    catch {
+        // Stories are a view; failing to keep one must never break a review or a hook.
+    }
+}
+/** Every story, oldest first; `since` keeps those at or after it. */
+export function readStories(cwd, since) {
+    let lines;
+    try {
+        lines = fs.readFileSync(path.join(cwd, STORIES_FILE), 'utf8').split('\n');
+    }
+    catch {
+        return [];
+    }
+    const stories = lines.flatMap(line => {
+        try {
+            return line.trim() ? [JSON.parse(line)] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    return since ? stories.filter(s => Date.parse(s.at) >= since.getTime()) : stories;
+}
+/**
+ * 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 function compactDiff(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head++;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail++;
+    const clip = (line) => (line.length > MAX_LINE_CHARS ? line.slice(0, MAX_LINE_CHARS) + '…' : line);
+    const lines = [
+        ...a.slice(Math.max(0, head - CONTEXT_LINES), head).map(l => ' ' + clip(l)),
+        ...a.slice(head, a.length - tail).map(l => '-' + clip(l)),
+        ...b.slice(head, b.length - tail).map(l => '+' + clip(l)),
+        ...a.slice(a.length - tail, Math.min(a.length, a.length - tail + CONTEXT_LINES)).map(l => ' ' + clip(l)),
+    ];
+    return lines.length > MAX_DIFF_LINES ? [...lines.slice(0, MAX_DIFF_LINES), ' …'] : lines;
+}
+function trim(file) {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > MAX_STORIES * 1.2)
+        fs.writeFileSync(file, lines.slice(-MAX_STORIES).join('\n') + '\n');
+}

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

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

package/dist/review/stories.test.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { recordReviewOutcome } from './agent-fixes.js';
+import { readAgentEvents } from './effectiveness.js';
+import { recordLessonsServed, recordPrCatches } from './learning-events.js';
+import { compactDiff, readStories } from './stories.js';
+let cwd;
+beforeEach(() => { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'stories-')); fs.mkdirSync(path.join(cwd, 'src')); });
+afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));
+const finding = (id, title) => ({ id, title, details: `${title}.`, severity: 'high', files: ['src/a.ts'], line: 2 });
+describe('compactDiff', () => {
+    it('keeps only the changed lines and two lines of context', () => {
+        const before = ['a', 'b', 'c', 'old', 'd', 'e', 'f'].join('\n');
+        const after = ['a', 'b', 'c', 'new', 'd', 'e', 'f'].join('\n');
+        expect(compactDiff(before, after)).toEqual([' b', ' c', '-old', '+new', ' d', ' e']);
+    });
+});
+describe('stories from fixes', () => {
+    it('credits a fix to the stage that first reported it, with the code change', () => {
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), "fetch(url, { headers });\n");
+        recordReviewOutcome(cwd, [finding('semantic-bugs', 'Credential header follows redirects')], ['src/a.ts'], 'edit');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), "fetch(url, { headers, redirect: 'error' });\n");
+        recordReviewOutcome(cwd, [], ['src/a.ts'], 'stop');
+        const [story] = readStories(cwd);
+        expect(story).toMatchObject({ stage: 'edit', file: 'src/a.ts', rule: 'semantic-bugs', title: 'Credential header follows redirects' });
+        expect(story.diff).toEqual(['-fetch(url, { headers });', "+fetch(url, { headers, redirect: 'error' });", ' ']);
+    });
+    it('writes no story for a finding someone dismissed, even after its file changed', async () => {
+        const { dismissFinding, findingKey } = await import('./quiet.js');
+        const f = finding('semantic-bugs', 'Looks risky');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'x\n');
+        recordReviewOutcome(cwd, [f], ['src/a.ts'], 'review');
+        dismissFinding(cwd, findingKey(f), 'intended');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'y\n');
+        recordReviewOutcome(cwd, [], ['src/a.ts'], 'review');
+        expect(readStories(cwd)).toEqual([]);
+    });
+    it('writes no story while the finding is still open', () => {
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'x\n');
+        recordReviewOutcome(cwd, [finding('semantic-bugs', 'X')], ['src/a.ts'], 'review');
+        expect(readStories(cwd)).toEqual([]);
+    });
+});
+describe('learning events', () => {
+    it('records lessons served and PR catches, and nothing when there are none', () => {
+        recordLessonsServed(cwd, 'recall', []);
+        recordPrCatches(cwd, []);
+        expect(readAgentEvents(cwd)).toEqual([]);
+        recordLessonsServed(cwd, 'review', ['Never follow redirects with credentials', 'Never follow redirects with credentials']);
+        recordPrCatches(cwd, [finding('semantic-bugs', 'Unbounded query')]);
+        expect(readAgentEvents(cwd)).toEqual([
+            expect.objectContaining({ type: 'lessons_served', via: 'review', lessons: ['Never follow redirects with credentials'] }),
+            expect.objectContaining({ type: 'pr_catches', findings: [{ rule: 'semantic-bugs', title: 'Unbounded query', file: 'src/a.ts' }] }),
+        ]);
+    });
+});

package/dist/review/trusted-state.d.ts

@@ -0,0 +1,6 @@
+/** Paths that steer Rigour itself; a change touching them is called out in the review. */
+export declare function isControlFile(file: string): boolean;
+/** A repository file's content at `ref`, or in the working tree when no ref is given; null when absent. */
+export declare function readStateFile(cwd: string, rel: string, ref?: string): string | null;
+/** The commit a branch left `base` at: the state a pull request is judged against. */
+export declare function mergeBaseOf(cwd: string, base: string): string;

package/dist/review/trusted-state.js

@@ -0,0 +1,35 @@
+/**
+ * Which copy of Rigour's own settings a review trusts.
+ *
+ * Dismissals, check outcomes and rigour.yml decide what a review reports. In the working tree they
+ * are whatever the change under review wrote, so a pull request could dismiss its own critical
+ * finding. An independent review reads them from the base instead (`ref`): a dismissal or setting
+ * added by the change takes effect once it is merged, the same rule CODEOWNERS follows.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+/** Paths that steer Rigour itself; a change touching them is called out in the review. */
+export function isControlFile(file) {
+    return file === 'rigour.yml' || file.startsWith('.rigour/');
+}
+/** A repository file's content at `ref`, or in the working tree when no ref is given; null when absent. */
+export function readStateFile(cwd, rel, ref) {
+    if (!ref) {
+        try {
+            return fs.readFileSync(path.join(cwd, rel), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    const result = spawnSync('git', ['show', `${ref}:${rel.split(path.sep).join('/')}`], { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+    return result.status === 0 ? result.stdout : null;
+}
+/** The commit a branch left `base` at: the state a pull request is judged against. */
+export function mergeBaseOf(cwd, base) {
+    const result = spawnSync('git', ['merge-base', base, 'HEAD'], { cwd, encoding: 'utf8' });
+    if (result.status !== 0)
+        throw new Error(`git merge-base ${base} HEAD failed: ${result.stderr.trim()}`);
+    return result.stdout.trim();
+}