@rigour-labs/core 6.6.5 → 6.7.0

package/dist/review/reviewer/background.test.js

@@ -0,0 +1,118 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../../types/index.js';
+import { backgroundReview, reviewStatus, startBackgroundReview } from './background.js';
+import { VerdictStore } from './store.js';
+let repo;
+let bin;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const config = ConfigSchema.parse({ version: 1, review: { reviewer: { enabled: true } } });
+const originalPath = process.env.PATH;
+let PR = { number: 7, state: 'OPEN', isDraft: false, author: { login: 'author' }, body: 'desc' };
+const VERDICT = JSON.stringify({ prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [{ class: 'correctness', file: 'src/job.ts', line: 1, issue: 'never locks', consequence: 'a second run reads stale rows' }], carried: [], resolved_previous: [] });
+/** Real git; a pull request on the branch; a claude that answers one finding. */
+const exec = async (command, args, options) => {
+    if (command === 'git') {
+        try {
+            return { exitCode: 0, stdout: execFileSync('git', args, { cwd: options.cwd, encoding: 'utf8' }), stderr: '' };
+        }
+        catch (error) {
+            return { exitCode: 1, stdout: '', stderr: String(error.message) };
+        }
+    }
+    if (command === 'gh') {
+        if (args[0] === 'pr')
+            return { exitCode: 0, stdout: JSON.stringify(PR), stderr: '' };
+        return { exitCode: 0, stdout: '[]', stderr: '' };
+    }
+    if (args[0] === '--version')
+        return { exitCode: 0, stdout: '1.0.0\n', stderr: '' };
+    return { exitCode: 0, stdout: JSON.stringify({ result: VERDICT }), stderr: '' };
+};
+beforeEach(() => {
+    bin = fs.mkdtempSync(path.join(os.tmpdir(), 'bin-'));
+    fs.writeFileSync(path.join(bin, process.platform === 'win32' ? 'claude.cmd' : 'claude'), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+    process.env.PATH = [bin, originalPath ?? ''].join(path.delimiter);
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'background-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    fs.writeFileSync(path.join(repo, 'a.ts'), 'export const a = 1;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+    git('checkout', '-qb', 'feature');
+    fs.mkdirSync(path.join(repo, 'src'));
+    fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export const job = 1;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'job');
+});
+afterEach(() => {
+    process.env.PATH = originalPath;
+    try {
+        git('worktree', 'prune');
+    }
+    catch { /* gone */ }
+    for (const dir of [repo, bin])
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe('the background review', () => {
+    it('reviews the pushed commit in a worktree of its own, records the verdict under the branch, and leaves the checkout alone', async () => {
+        const head = git('rev-parse', 'HEAD');
+        fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export const job = 2; // edited after the push\n'); // must not be what the reviewer reads
+        const lines = [];
+        const result = await backgroundReview(repo, { head, branch: 'feature', base: 'main' }, config, exec, line => lines.push(line));
+        expect(result).toMatchObject({ outcome: 'findings', pr: 7 });
+        expect(result.items).toEqual([expect.objectContaining({ file: 'src/job.ts', issue: 'never locks' })]);
+        expect(lines.at(-1)).toContain('never locks');
+        expect(fs.readFileSync(path.join(repo, 'src/job.ts'), 'utf8')).toContain('edited after the push');
+        const store = (await VerdictStore.open(repo, exec));
+        expect(store.branchState('feature')).toMatchObject({ head, mode: 'full' });
+        expect(fs.existsSync(store.worktreeDir(head))).toBe(false); // removed when done
+        const status = await reviewStatus(repo, 'feature', exec);
+        expect(status).toMatchObject({ branch: 'feature', last: { head, mode: 'full', open: [expect.objectContaining({ issue: 'never locks' })] } });
+        expect(status?.running).toBeUndefined();
+    });
+    it('asks whether a review is due before checking anything out, and the status says why it was skipped', async () => {
+        PR = { ...PR, isDraft: true };
+        try {
+            const head = git('rev-parse', 'HEAD');
+            const result = await backgroundReview(repo, { head, branch: 'feature', base: 'main' }, config, exec, () => undefined);
+            expect(result).toMatchObject({ outcome: 'skipped', reason: expect.stringContaining('is a draft') });
+            const store = (await VerdictStore.open(repo, exec));
+            expect(fs.existsSync(store.worktreeDir(head))).toBe(false); // never checked out
+            expect((await reviewStatus(repo, 'feature', exec))?.attempt).toMatchObject({ head, outcome: 'skipped', reason: expect.stringContaining('is a draft') });
+        }
+        finally {
+            PR = { ...PR, isDraft: false };
+        }
+    });
+    it('starts detached with a pid the status reports, and a newer start for the branch ends the older one', async () => {
+        const head = git('rev-parse', 'HEAD');
+        const sleeper = [process.execPath, '-e', 'setTimeout(() => {}, 20000)'];
+        const log = await startBackgroundReview(repo, { head, branch: 'feature', base: 'main' }, sleeper, exec);
+        expect(log).toMatch(/feature\.log$/);
+        const first = (await reviewStatus(repo, 'feature', exec))?.running;
+        expect(first).toMatchObject({ head });
+        expect(alive(first.pid)).toBe(true);
+        await startBackgroundReview(repo, { head: 'b'.repeat(40), branch: 'feature', base: 'main' }, sleeper, exec);
+        const second = (await reviewStatus(repo, 'feature', exec))?.running;
+        expect(second?.pid).not.toBe(first.pid);
+        for (let waited = 0; alive(first.pid) && waited < 3000; waited += 50)
+            await new Promise(resolve => setTimeout(resolve, 50)); // under load the signal lands later
+        expect(alive(first.pid)).toBe(false);
+        process.kill(second.pid);
+    });
+});
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * How a panel agrees, as pure functions: when two judges' items are the same finding (similarity),
+ * the minimum-cost one-to-one assignment (the Hungarian algorithm), the grouping of every judge's
+ * items into findings, and the majority rule that decides a finding from every judge's call.
+ * Deterministic: inputs sorted, ties broken on file, line and id. panel.ts runs the judges around it.
+ */
+import type { OpenItem } from './verdict.js';
+export type Call = 'raised' | 'confirm' | 'refute' | 'unsure' | 'not asked';
+export type PanelStatus = 'confirmed' | 'disputed' | 'dropped';
+/** Similarity at or above which two items are the same finding. */
+export declare const MATCH_THRESHOLD = 0.5;
+export declare const order: (a: OpenItem, b: OpenItem) => number;
+/** Shared words over all words (Jaccard) of two items' issue and consequence. */
+export declare function textSimilarity(a: OpenItem, b: OpenItem): number;
+/** 0 for different files; otherwise wording, line distance and class, weighted. A far-apart pair needs close wording. */
+export declare function similarity(a: OpenItem, b: OpenItem): number;
+/** One finding as the panel sees it: the item each judge who raised it wrote, in judge order. */
+export interface Cluster {
+    members: Array<{
+        judge: string;
+        item: OpenItem;
+    }>;
+}
+/**
+ * The judges' items grouped into findings. Judges are taken in order; each judge's items are
+ * assigned one-to-one to the findings so far by the Hungarian algorithm (a finding scores as its
+ * closest member), never first-fit. An item left over that a finding already holding this judge
+ * resembles joins it (one judge split what another named once); any other leftover is a new finding.
+ */
+export declare function clusterItems(judges: string[], items: OpenItem[][]): Cluster[];
+/**
+ * Status from every judge's call. Confirmed: a strict majority raised it or confirmed it with
+ * evidence. Dropped: refutations with evidence at least match the support and no judge is unsure.
+ * Disputed otherwise. With two judges: both raised it, or the other confirmed it; refuted, dropped.
+ */
+export declare function statusOf(calls: Record<string, Call>, judges: number): PanelStatus;

package/dist/review/reviewer/consensus.js

@@ -0,0 +1,144 @@
+/** Similarity at or above which two items are the same finding. */
+export const MATCH_THRESHOLD = 0.5;
+/** Below this share of words, two items are the same finding only on the same line and in the same class. */
+const MIN_SHARED_WORDS = 0.15;
+const LINE_WINDOW = 5;
+const STOP = new Set(['the', 'and', 'for', 'that', 'this', 'with', 'from', 'when', 'into', 'are', 'not', 'but', 'its', 'has', 'have', 'every', 'each', 'one', 'can']);
+export const order = (a, b) => (a.file ?? '').localeCompare(b.file ?? '') || (a.line ?? 0) - (b.line ?? 0) || a.id.localeCompare(b.id);
+/** Shared words over all words (Jaccard) of two items' issue and consequence. */
+export function textSimilarity(a, b) {
+    const wa = words(a);
+    const wb = words(b);
+    const shared = [...wa].filter(w => wb.has(w)).length;
+    return wa.size + wb.size - shared ? shared / (wa.size + wb.size - shared) : 0;
+}
+function words(item) {
+    const text = `${item.issue} ${item.consequence ?? ''}`.toLowerCase();
+    return new Set((text.match(/[a-z_][a-z0-9_]{2,}/g) ?? []).filter(w => !STOP.has(w)));
+}
+/** 0 for different files; otherwise wording, line distance and class, weighted. A far-apart pair needs close wording. */
+export function similarity(a, b) {
+    if (!a.file || a.file !== b.file)
+        return 0;
+    const text = textSimilarity(a, b);
+    const distance = a.line !== undefined && b.line !== undefined ? Math.abs(a.line - b.line) : undefined;
+    const line = distance === undefined ? 0.5 : distance <= LINE_WINDOW ? 1 - distance / (LINE_WINDOW + 1) : 0;
+    if (line === 0 && text < 0.5)
+        return 0;
+    if (text < MIN_SHARED_WORDS && !(distance === 0 && a.class === b.class))
+        return 0;
+    return 0.4 * text + 0.35 * line + 0.25 * (a.class === b.class ? 1 : 0);
+}
+/**
+ * Minimum-cost assignment of rows to columns (Hungarian algorithm with potentials, O(n²m)).
+ * `cost` is rows × columns with rows ≤ columns; returns the column of each row.
+ */
+function assign(cost) {
+    const n = cost.length;
+    const m = n ? cost[0].length : 0;
+    const u = new Array(n + 1).fill(0);
+    const v = new Array(m + 1).fill(0);
+    const p = new Array(m + 1).fill(0);
+    const way = new Array(m + 1).fill(0);
+    for (let i = 1; i <= n; i++) {
+        p[0] = i;
+        let j0 = 0;
+        const minv = new Array(m + 1).fill(Infinity);
+        const used = new Array(m + 1).fill(false);
+        do {
+            used[j0] = true;
+            const i0 = p[j0];
+            let delta = Infinity;
+            let j1 = 0;
+            for (let j = 1; j <= m; j++) {
+                if (used[j])
+                    continue;
+                const cur = cost[i0 - 1][j - 1] - u[i0] - v[j];
+                if (cur < minv[j]) {
+                    minv[j] = cur;
+                    way[j] = j0;
+                }
+                if (minv[j] < delta) {
+                    delta = minv[j];
+                    j1 = j;
+                }
+            }
+            for (let j = 0; j <= m; j++) {
+                if (used[j]) {
+                    u[p[j]] += delta;
+                    v[j] -= delta;
+                }
+                else
+                    minv[j] -= delta;
+            }
+            j0 = j1;
+        } while (p[j0] !== 0);
+        do {
+            const j1 = way[j0];
+            p[j0] = p[j1];
+            j0 = j1;
+        } while (j0);
+    }
+    const column = new Array(n).fill(-1);
+    for (let j = 1; j <= m; j++)
+        if (p[j])
+            column[p[j] - 1] = j - 1;
+    return column;
+}
+const clusterSimilarity = (cluster, item) => Math.max(...cluster.members.map(m => similarity(m.item, item)));
+/**
+ * The judges' items grouped into findings. Judges are taken in order; each judge's items are
+ * assigned one-to-one to the findings so far by the Hungarian algorithm (a finding scores as its
+ * closest member), never first-fit. An item left over that a finding already holding this judge
+ * resembles joins it (one judge split what another named once); any other leftover is a new finding.
+ */
+export function clusterItems(judges, items) {
+    const clusters = [];
+    judges.forEach((judge, j) => {
+        const mine = [...items[j]].sort(order);
+        const open = clusters.map((c, i) => ({ c, i })).filter(x => !x.c.members.some(m => m.judge === judge));
+        const sims = mine.map(item => open.map(x => clusterSimilarity(x.c, item)));
+        const placed = new Set();
+        if (mine.length && open.length) {
+            const transpose = mine.length > open.length;
+            const matrix = transpose ? open.map((_, k) => mine.map((__, i) => sims[i][k])) : sims;
+            const column = assign(matrix.map(row => row.map(s => (s >= MATCH_THRESHOLD ? 1 - s : 1))));
+            column.forEach((col, row) => {
+                if (col < 0)
+                    return;
+                const [i, k] = transpose ? [col, row] : [row, col];
+                if (sims[i][k] < MATCH_THRESHOLD)
+                    return;
+                open[k].c.members.push({ judge, item: mine[i] });
+                placed.add(i);
+            });
+        }
+        mine.forEach((item, i) => {
+            if (placed.has(i))
+                return;
+            // Only a finding another judge also holds: a judge's own two findings are never merged into one.
+            const home = clusters.filter(c => c.members.some(m => m.judge === judge) && c.members.some(m => m.judge !== judge)).map(c => ({ c, s: clusterSimilarity(c, item) }))
+                .filter(x => x.s >= MATCH_THRESHOLD).sort((a, b) => b.s - a.s || order(a.c.members[0].item, b.c.members[0].item))[0];
+            if (home)
+                home.c.members.push({ judge, item });
+            else
+                clusters.push({ members: [{ judge, item }] });
+        });
+    });
+    return clusters;
+}
+/**
+ * Status from every judge's call. Confirmed: a strict majority raised it or confirmed it with
+ * evidence. Dropped: refutations with evidence at least match the support and no judge is unsure.
+ * Disputed otherwise. With two judges: both raised it, or the other confirmed it; refuted, dropped.
+ */
+export function statusOf(calls, judges) {
+    const values = Object.values(calls);
+    const support = values.filter(c => c === 'raised' || c === 'confirm').length;
+    const refuted = values.filter(c => c === 'refute').length;
+    if (support > judges / 2)
+        return 'confirmed';
+    if (refuted && refuted >= support && !values.includes('unsure') && !values.includes('not asked'))
+        return 'dropped';
+    return 'disputed';
+}

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

@@ -0,0 +1,75 @@
+import type { RouterPolicy } from '../../deep/router.js';
+import type { PanelItem } from './panel.js';
+import { type Exec } from './exec.js';
+import type { OpenItem } from './verdict.js';
+export declare const REVIEW_DISMISSALS: string;
+export interface ReviewDismissal {
+    id: string;
+    file?: string;
+    line?: number;
+    class: string;
+    issue: string;
+    reason: string;
+    at: string;
+    by?: string;
+}
+export declare function readReviewDismissals(cwd: string): ReviewDismissal[];
+/**
+ * The dismissal an item repeats: the same id, or the same finding re-worded: the same file and
+ * class, within a few lines, and mostly the same words. A different bug on the same line, or a
+ * finding that only shares the file and class, is not dismissed.
+ */
+export declare function dismissedAs(item: OpenItem, dismissals: ReviewDismissal[]): ReviewDismissal | undefined;
+export interface ContextInput {
+    cwd: string;
+    /** Where .rigour lives: the main checkout when cwd is the background reviewer's worktree. */
+    stateRoot: string;
+    /** The team's dismissals, when it allows them (empty otherwise). */
+    dismissals: ReviewDismissal[];
+    diff: string;
+    router: RouterPolicy | undefined;
+    /** The previous verdict's panel decisions, and the files changed since it. */
+    previousPanel: PanelItem[] | undefined;
+    touched: Set<string>;
+    /** Docs that name the changed code (relatedDocs). */
+    docs: Array<{
+        doc: string;
+        names: string[];
+    }>;
+    /** Findings Rigour's checks already report on this change, one line each. */
+    checks: string[];
+}
+/** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
+export declare function reviewerInputs(review: {
+    hints: string[];
+    findings: Array<{
+        files?: string[];
+        line?: number;
+        title: string;
+    }>;
+}): {
+    hints: string;
+    checks: string[];
+};
+/** The context pack as Markdown, its hash for the fingerprint, and the router's count of risky changed functions (undefined when it could not score). */
+export declare function buildContext(input: ContextInput): {
+    text: string;
+    key: string;
+    risky: number | undefined;
+};
+/**
+ * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one
+ * `git grep` over the docs, never a read of every one, stopping at the first few.
+ */
+export declare function relatedDocs(cwd: string, changedFiles: string[], exec?: Exec): Promise<Array<{
+    doc: string;
+    names: string[];
+}>>;
+/**
+ * `rigour dismiss <id>` on a reviewer finding: only where the team allows it (`review.reviewer.dismissals`), with a
+ * reason, recorded with who dismissed it. The item is found in this branch's latest verdict.
+ */
+export declare function dismissReviewerFinding(cwd: string, id: string, reason: string, allowed: boolean, exec?: Exec): Promise<{
+    item?: OpenItem;
+    error?: string;
+}>;

package/dist/review/reviewer/context.js

@@ -0,0 +1,140 @@
+/**
+ * What the team already knows, handed to every judge so a review starts from it instead of from
+ * nothing: the verified review lessons and the repository rules for the files the change touches,
+ * the findings the team settled (dismissed as not a bug, or refuted with evidence in an earlier
+ * round on a file nothing has changed since), and the docs that name the changed code. Built
+ * deterministically, without a model; its hash is part of the verdict's fingerprint, so a new
+ * lesson or dismissal is never answered by a verdict cached before it.
+ *
+ * The reviewer dismissal store lives here too: `rigour dismiss <id>` on a reviewer finding records
+ * the finding itself, so the same finding re-worded on the same file is recognised and never
+ * blocks again.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { buildReviewTask } from '../review-task.js';
+import { reviewedKeys } from '../ledger.js';
+import { textSimilarity } from './consensus.js';
+import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
+import { VerdictStore } from './store.js';
+export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.json');
+const MAX_DOCS = 10;
+const MAX_SETTLED = 40;
+export function readReviewDismissals(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, REVIEW_DISMISSALS), 'utf8'));
+        return Array.isArray(parsed?.entries) ? parsed.entries.filter((e) => typeof e?.id === 'string' && typeof e?.issue === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Records "not a bug" for a reviewer finding; idempotent. A human's own review point is never dismissed this way. */
+function dismissReviewItem(cwd, item, reason, by, at = new Date().toISOString()) {
+    if (item.kind === 'prior')
+        return false;
+    const entries = readReviewDismissals(cwd);
+    if (entries.some(e => e.id === item.id))
+        return true;
+    entries.push({ id: item.id, ...(item.file ? { file: item.file } : {}), ...(item.line ? { line: item.line } : {}), class: item.class, issue: item.issue, reason, at, ...(by ? { by } : {}) });
+    fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, REVIEW_DISMISSALS), JSON.stringify({ entries }, null, 2));
+    return true;
+}
+/** Close enough in place and wording that a dismissal of one is a dismissal of the other; a different bug nearby never is. */
+const DISMISSAL_LINES = 3;
+const DISMISSAL_WORDS = 0.6;
+/**
+ * The dismissal an item repeats: the same id, or the same finding re-worded: the same file and
+ * class, within a few lines, and mostly the same words. A different bug on the same line, or a
+ * finding that only shares the file and class, is not dismissed.
+ */
+export function dismissedAs(item, dismissals) {
+    if (item.kind === 'prior')
+        return undefined;
+    return dismissals.find(d => d.id === item.id) ?? dismissals.find(d => d.file === item.file && d.class === item.class
+        && (d.line === undefined || item.line === undefined || Math.abs(d.line - item.line) <= DISMISSAL_LINES)
+        && textSimilarity({ ...item, consequence: undefined }, { id: d.id, kind: 'finding', class: d.class, issue: d.issue }) >= DISMISSAL_WORDS);
+}
+/** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
+export function reviewerInputs(review) {
+    return { hints: review.hints.join('\n'), checks: review.findings.map(f => `${f.files?.[0] ?? '?'}${f.line ? `:${f.line}` : ''} ${f.title}`) };
+}
+/** The context pack as Markdown, its hash for the fingerprint, and the router's count of risky changed functions (undefined when it could not score). */
+export function buildContext(input) {
+    const sections = [];
+    let task;
+    try {
+        task = buildReviewTask(input.cwd, input.diff, input.router, undefined, undefined, reviewedKeys(input.stateRoot));
+    }
+    catch {
+        task = undefined;
+    }
+    if (task?.lessons.length)
+        sections.push(`## Lessons this team verified on earlier reviews, for the files this change touches\n${task.lessons.map(l => `- ${l.file}: ${l.text}${l.prs.length ? ` (PR ${l.prs.join(', ')})` : ''}`).join('\n')}`);
+    if (task?.rules.length)
+        sections.push(`## Repository rules that name what this change touches\n${task.rules.map(r => `- ${r.source}: ${r.text}`).join('\n')}`);
+    if (input.checks.length)
+        sections.push(`## Already found by Rigour's checks: they block on their own, so do not report them again\n${input.checks.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}`);
+    const dismissed = input.dismissals.slice(-MAX_SETTLED).map(d => `- dismissed as not a bug${d.by ? ` by ${d.by}` : ''}: ${where(d)} [${d.class}] ${d.issue} (reason: ${d.reason})`);
+    const refuted = (input.previousPanel ?? []).filter(p => p.status === 'dropped' && !!p.item.file && !input.touched.has(p.item.file)).slice(0, MAX_SETTLED)
+        .map(p => `- refuted with evidence in the last round: ${where(p.item)} [${p.item.class}] ${p.item.issue} (${(p.cross ?? []).find(c => c.call === 'refute')?.evidence ?? 'evidence in the previous verdict'})`);
+    if (dismissed.length || refuted.length)
+        sections.push(`## Settled: do not raise these again unless the code now shows something new\n${[...dismissed, ...refuted].join('\n')}`);
+    const docs = input.docs;
+    if (docs.length)
+        sections.push(`## Docs that describe the changed code (read one when its claim matters to a finding)\n${docs.map(d => `- ${d.doc} (names ${d.names.join(', ')})`).join('\n')}`);
+    const text = sections.length ? `# What this team already knows\n\n${sections.join('\n\n')}\n` : 'none\n';
+    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined };
+}
+function where(x) {
+    return x.file ? `${x.file}${x.line ? `:${x.line}` : ''}` : '(no file)';
+}
+/**
+ * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one
+ * `git grep` over the docs, never a read of every one, stopping at the first few.
+ */
+export async function relatedDocs(cwd, changedFiles, exec = defaultExec) {
+    const names = [...new Set(changedFiles.flatMap(file => {
+            const stem = path.posix.basename(file).replace(/\.[^.]+$/, '');
+            return stem.length >= 5 && !/^(index|types|utils|helpers|config|main)$/.test(stem) ? [file, stem] : [file];
+        }))];
+    if (!names.length)
+        return [];
+    const grep = await exec('git', ['grep', '-I', '-F', '-o', ...names.flatMap(name => ['-e', name]), '--', '*.md'], { cwd, timeoutMs: GH_TIMEOUT_MS });
+    const found = new Map();
+    for (const line of grep.stdout.split('\n')) {
+        const at = line.indexOf(':');
+        if (at <= 0)
+            continue;
+        const doc = line.slice(0, at);
+        if (!found.has(doc) && found.size >= MAX_DOCS)
+            continue;
+        found.set(doc, (found.get(doc) ?? new Set()).add(line.slice(at + 1)));
+    }
+    return [...found].map(([doc, hits]) => ({ doc, names: [...hits].slice(0, 3) }));
+}
+/**
+ * `rigour dismiss <id>` on a reviewer finding: only where the team allows it (`review.reviewer.dismissals`), with a
+ * reason, recorded with who dismissed it. The item is found in this branch's latest verdict.
+ */
+export async function dismissReviewerFinding(cwd, id, reason, allowed, exec = defaultExec) {
+    if (!allowed)
+        return { error: 'this team does not dismiss reviewer findings (review.reviewer.dismissals is off): fix the code, or improve the reviewer (its prompt, rules or the reviewers it runs) so the finding is not raised' };
+    if (reason.trim().length < 5)
+        return { error: 'say why it is not a bug, in a few words' };
+    const store = await VerdictStore.open(cwd, exec);
+    if (!store)
+        return { error: 'not a git repository' };
+    const branch = (await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim();
+    const state = store.branchState(branch);
+    const open = state ? store.readJson(store.openPath(state.verdict)) ?? [] : [];
+    const item = open.find(i => i.id === id);
+    if (!item)
+        return { error: `no open reviewer finding ${id} on ${branch}: run \`rigour review --reviewer\` and copy the id it shows` };
+    const who = (await exec('git', ['config', 'user.email'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim() || (await exec('git', ['config', 'user.name'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim();
+    if (!dismissReviewItem(cwd, item, reason, who))
+        return { error: `${id} is a human review point: answer it in the reply, it cannot be dismissed here` };
+    return { item };
+}

package/dist/review/reviewer/context.test.d.ts

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

package/dist/review/reviewer/context.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { dismissedAs } from './context.js';
+const dismissal = { id: 'abcdef0123', file: 'src/x.ts', line: 40, class: 'correctness', issue: 'cache key built from user id may collide', reason: 'ids are unique per tenant', at: '2026-10-06' };
+const finding = (over) => ({ id: 'ffff000011', kind: 'finding', class: 'correctness', file: 'src/x.ts', line: 40, issue: 'cache key built from the user id may collide', consequence: 'two users share an entry', ...over });
+describe('a dismissal', () => {
+    it('covers the same finding re-worded nearby', () => {
+        expect(dismissedAs(finding({}), [dismissal])).toBe(dismissal);
+        expect(dismissedAs(finding({ line: 42, issue: 'the cache key built from user id may collide' }), [dismissal])).toBe(dismissal);
+        expect(dismissedAs(finding({ id: 'abcdef0123', issue: 'anything at all' }), [dismissal])).toBe(dismissal); // its own id
+    });
+    it('never hides a different bug, even on the same line and in the same class', () => {
+        expect(dismissedAs(finding({ issue: 'cache entry never invalidated when the user changes' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs(finding({ line: 42, issue: 'cache entry never invalidated when user id changes' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs(finding({ line: 80 }), [dismissal])).toBeUndefined(); // far away
+        expect(dismissedAs(finding({ class: 'production-cost' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs({ ...finding({}), kind: 'prior' }, [dismissal])).toBeUndefined(); // a human's point is never dismissed this way
+    });
+});

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

@@ -0,0 +1,17 @@
+export type Exec = (command: string, args: string[], options: {
+    cwd: string;
+    timeoutMs: number;
+    env?: Record<string, string>;
+}) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const defaultExec: Exec;
+/** Called while the reviewer works, so a slow run and a stuck one look different. */
+export type Progress = (message: string) => void;
+export declare const GH_TIMEOUT_MS = 60000;
+/** The named GitHub account's token for `gh`, when the person keeps several; otherwise gh's own. */
+export declare function githubEnv(cwd: string, account: string | undefined, exec: Exec): Promise<Record<string, string> | undefined>;
+/** `gh --paginate` prints one JSON array per page. */
+export declare function parseJsonArrays(text: string): any[];

package/dist/review/reviewer/exec.js

@@ -0,0 +1,27 @@
+/** How the reviewer runs commands (git, gh, the agent CLIs); tests replace it. */
+import { execa } from 'execa';
+export const defaultExec = async (command, args, options) => {
+    // stdin is /dev/null, not an empty pipe: an agent CLI that reads stdin sees its end at once, and a command that exits
+    // before an empty write lands (git rev-parse) cannot fail the run with EPIPE, as it did on Linux.
+    const result = await execa(command, args, { cwd: options.cwd, reject: false, timeout: options.timeoutMs, stdin: 'ignore', env: options.env ? { ...process.env, ...options.env } : undefined, maxBuffer: 64 * 1024 * 1024 });
+    const stderr = String(result.stderr ?? '');
+    // A command that could not start, timed out or was killed writes nothing itself: say which, never an empty failure.
+    return { exitCode: result.exitCode ?? 1, stdout: String(result.stdout ?? ''), stderr: stderr || (result.failed && 'shortMessage' in result ? String(result.shortMessage) : '') };
+};
+export const GH_TIMEOUT_MS = 60_000;
+/** The named GitHub account's token for `gh`, when the person keeps several; otherwise gh's own. */
+export async function githubEnv(cwd, account, exec) {
+    if (!account || process.env.GH_TOKEN)
+        return undefined;
+    const token = await exec('gh', ['auth', 'token', '--user', account], { cwd, timeoutMs: GH_TIMEOUT_MS });
+    return token.exitCode === 0 && token.stdout.trim() ? { GH_TOKEN: token.stdout.trim() } : undefined;
+}
+/** `gh --paginate` prints one JSON array per page. */
+export function parseJsonArrays(text) {
+    try {
+        return JSON.parse(`[${text.trim().replace(/\]\s*\[/g, '],[')}]`).flat();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/review/reviewer/exec.test.d.ts

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

package/dist/review/reviewer/exec.test.js

@@ -0,0 +1,23 @@
+import os from 'os';
+import { describe, expect, it } from 'vitest';
+import { defaultExec } from './exec.js';
+describe('running a command', () => {
+    it('passes the command\'s own output through', async () => {
+        const result = await defaultExec(process.execPath, ['-e', 'process.stdout.write("out"); process.stderr.write("err"); process.exit(3)'], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(result).toEqual({ exitCode: 3, stdout: 'out', stderr: 'err' });
+    });
+    it('gives the command an ended stdin, so one that reads it never waits and one that exits at once never fails', async () => {
+        const reader = await defaultExec(process.execPath, ['-e', 'let n = 0; process.stdin.on("data", d => n += d.length).on("end", () => process.stdout.write(`read ${n}`))'], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(reader).toEqual({ exitCode: 0, stdout: 'read 0', stderr: '' });
+        const runs = await Promise.all(Array.from({ length: 50 }, () => defaultExec(process.execPath, ['-e', 'process.stdout.write("ok")'], { cwd: os.tmpdir(), timeoutMs: 30_000 })));
+        expect(runs.every(r => r.exitCode === 0 && r.stdout === 'ok')).toBe(true);
+    });
+    it('says why a command that never answered failed: not started, or timed out', async () => {
+        const missing = await defaultExec('rigour-no-such-command', [], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(missing.exitCode).not.toBe(0);
+        expect(missing.stderr).toContain('rigour-no-such-command'); // ENOENT on Unix, "is not recognized" on Windows
+        const slow = await defaultExec(process.execPath, ['-e', 'setTimeout(() => {}, 10_000)'], { cwd: os.tmpdir(), timeoutMs: 200 });
+        expect(slow.exitCode).not.toBe(0);
+        expect(slow.stderr).toMatch(/timed out/i);
+    });
+});

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

@@ -0,0 +1,39 @@
+import { type Exec } from './exec.js';
+export interface PullRequest {
+    number: number;
+    state: 'open' | 'closed' | 'merged';
+    draft: boolean;
+    author: string;
+    body: string;
+}
+export interface HumanReviews {
+    /** As the reviewer reads them, oldest first, inline comments after; `none` when there are none. */
+    markdown: string;
+    /** Changes when a review or comment is added or edited: part of the verdict fingerprint. */
+    key: string;
+    count: number;
+    /** `<login>, <date> (<n> reviews)` of the latest, for the report. */
+    label?: string;
+}
+type Gh = (args: string[]) => ReturnType<Exec>;
+export declare function ghFor(cwd: string, exec: Exec, env: Record<string, string> | undefined): Gh;
+/** The pull request for the branch (or the one named, or the one the commit is on), or none, or why it could not be read. */
+export declare function findPullRequest(gh: Gh, branch: string, head: string, named: number | undefined): Promise<{
+    pr?: PullRequest;
+    error?: string;
+}>;
+/** Written by a person: not a bot, and not the pull request's author answering their own review. */
+export declare function isHuman(item: any, author: string): boolean;
+/** Every review by a person and every inline comment by a person, hidden from `reviewsBefore` on. */
+export declare function humanReviews(gh: Gh, pr: PullRequest, reviewsBefore: string | undefined): Promise<{
+    reviews?: HumanReviews;
+    error?: string;
+}>;
+/** The repository's rules as the reviewer must read them. */
+export declare function rulesText(cwd: string): string;
+export declare function sha(parts: string[]): string;
+/** True when HEAD is a merge whose second parent is on the base: the branch merged main in. */
+export declare function mergesBaseIn(cwd: string, baseSha: string, exec: Exec): Promise<boolean>;
+/** Added and removed lines between two commits. */
+export declare function linesChanged(cwd: string, from: string, to: string, exec: Exec): Promise<number>;
+export {};