@rigour-labs/core 6.8.1 → 6.9.0-rc.2

package/dist/goal/goal.d.ts

@@ -0,0 +1,34 @@
+import type { Failure } from '../types/index.js';
+export interface DoneItem {
+    text: string;
+    /** What the item names in backticks: files or paths, and symbols. */
+    paths: string[];
+    symbols: string[];
+}
+export interface Goal {
+    doneWhen: DoneItem[];
+    scope: string[];
+    outOfScope: string[];
+    invariants: string[];
+}
+/**
+ * The goal a pull request's description declares; empty when it declares none. `exists` tells a bare file name from a
+ * member access (isPath); without it, every bare name with a known file extension is a file.
+ */
+export declare function parseGoal(description: string, exists?: (name: string) => boolean): Goal;
+/** Whether the description declares anything the deterministic checks can check. */
+export declare function hasCheckableGoal(goal: Goal): boolean;
+/**
+ * The goal's deterministic findings for a change. `changedLines` is the review's changed lines per file (generated files
+ * already left out); a deleted file has none and is read from the diff's headers, left out too when `isGenerated` says
+ * so. A named symbol must appear on an added or removed line.
+ */
+export declare function goalFailures(goal: Goal, changedLines: Record<string, Set<number>>, diff: string, isGenerated?: (file: string) => boolean): Failure[];
+/**
+ * What only a reader of the code can judge: the "Done when" items that name no file (prose, or a symbol) and the
+ * invariants. An item that names a file is proven or broken by goalFailures, without a model.
+ */
+export declare function modelGoalItems(goal: Goal): Array<{
+    kind: 'done' | 'invariant';
+    text: string;
+}>;

package/dist/goal/goal.js

@@ -0,0 +1,188 @@
+/**
+ * The goal of a change, as its author declared it, and the deterministic checks of the change against it.
+ *
+ * The goal is read from the pull request's description, from headings the author writes on purpose:
+ *
+ *   ## Done when       a checklist; an item that names a file, path, symbol or migration in backticks is checkable
+ *   ## Scope           the paths the change may touch (globs or folders, in backticks or one per bullet)
+ *   ## Out of scope    paths it must not touch
+ *   ## Invariants      what must stay true (recorded with the goal; not checked here)
+ *
+ * Only what the author declared is checked: a description without these headings has no goal to check against, and
+ * nothing here ever blocks it. The checks are deterministic (no model): a changed file outside the declared scope, a
+ * changed file inside the declared out-of-scope, and a "done when" item whose named files the change never touches. A
+ * named symbol the change never touches is a note, never a block: an item can state a property the change keeps. Tests,
+ * snapshots, lockfiles, changelogs and release notes are exempt from the scope check (they follow the code they belong
+ * to), and so is a file a "Done when" item names.
+ */
+import micromatch from 'micromatch';
+const HEADINGS = [
+    // The headings teams already write a goal under; a checklist of procedure ("Test plan", "Review checklist") is not one.
+    [/^(?:done when|acceptance criteria|definition of done|success criteria)$/, 'doneWhen'],
+    [/^(?:scope|boundary|in scope)$/, 'scope'],
+    [/^(?:out of scope|not in scope|out-of-scope)$/, 'outOfScope'],
+    [/^invariants?$/, 'invariants'],
+];
+/** The section a line opens, if it is a heading (`## Scope`, `**Scope**`, `Scope:` alone on a line); `null` for another heading. */
+function headingOf(line) {
+    const markdown = /^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/.exec(line);
+    const bold = /^\s{0,3}(?:\*\*|__)(.+?)(?:\*\*|__)\s*:?\s*$/.exec(line);
+    const label = /^\s{0,3}([A-Za-z][A-Za-z -]{1,30}):\s*$/.exec(line);
+    const text = (markdown ?? bold ?? label)?.[1];
+    if (!text)
+        return undefined;
+    const name = text.replace(/[:*_`]/g, '').trim().toLowerCase();
+    for (const [pattern, section] of HEADINGS)
+        if (pattern.test(name))
+            return section;
+    return markdown || bold ? null : undefined; // another heading ends the section; a stray "Label:" line does not
+}
+const ITEM = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.+?)\s*$/;
+const TICKED = /`([^`\n]+)`/g;
+const FILE_EXTENSIONS = new Set(['ts', 'tsx', 'mts', 'cts', 'js', 'mjs', 'cjs', 'jsx', 'json', 'jsonc', 'md', 'mdx', 'yml', 'yaml', 'sql', 'py', 'go', 'rs', 'java', 'rb', 'kt', 'kts',
+    'swift', 'svelte', 'vue', 'css', 'scss', 'sass', 'less', 'html', 'htm', 'toml', 'lock', 'sh', 'bash', 'zsh', 'sha256', 'txt', 'csv', 'xml', 'graphql', 'gql', 'proto',
+    'ini', 'cfg', 'conf', 'c', 'h', 'cc', 'cpp', 'hpp', 'cs', 'php', 'scala', 'ex', 'exs', 'dart', 'lua', 'tf', 'hcl', 'snap']);
+/**
+ * A token that names a file or path: has a folder separator or a glob, or ends in a known file extension. Member
+ * access (`JSON.parse`, `order.customerId`, `res.status`) is a symbol, not a file. A bare `name.ext` is a file only when
+ * `exists` (the repository's file names) knows it, so `package.json` is a file and `res.json` is a member access. A URL
+ * or an app route (`https://host/checkout?x=1`, `/app/dashboard`) is never a file of the repository.
+ */
+function isPath(token, exists) {
+    if (/:\/\//.test(token) || token.startsWith('/') || !/^[\w.@/*?[\]{}!,+()$~-]+$/.test(token))
+        return false;
+    if (/[/*?[\]{}]/.test(token))
+        return true;
+    const extension = /\.([A-Za-z0-9]{1,8})$/.exec(token)?.[1];
+    return !!extension && FILE_EXTENSIONS.has(extension) && (!exists || exists(token));
+}
+/** A token that names a symbol: an identifier, optionally dotted, optionally called. */
+function symbolOf(token) {
+    const m = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)(?:\(\))?$/.exec(token.trim());
+    return m && m[1].length >= 3 ? m[1] : undefined;
+}
+/**
+ * The goal a pull request's description declares; empty when it declares none. `exists` tells a bare file name from a
+ * member access (isPath); without it, every bare name with a known file extension is a file.
+ */
+export function parseGoal(description, exists) {
+    const path = (token) => isPath(token, exists);
+    const goal = { doneWhen: [], scope: [], outOfScope: [], invariants: [] };
+    let section;
+    for (const line of description.replace(/\r\n/g, '\n').split('\n')) {
+        const heading = headingOf(line);
+        if (heading !== undefined) {
+            section = heading ?? undefined;
+            continue;
+        }
+        if (!section)
+            continue;
+        const item = ITEM.exec(line)?.[1];
+        if (!item)
+            continue;
+        const ticked = [...item.matchAll(TICKED)].map(m => m[1].trim());
+        if (section === 'doneWhen') {
+            goal.doneWhen.push({ text: item, paths: ticked.filter(path), symbols: ticked.filter(t => !path(t)).map(symbolOf).filter((s) => !!s) });
+        }
+        else if (section === 'invariants') {
+            goal.invariants.push(item);
+        }
+        else {
+            // A scope entry is what it names in backticks, or the bullet itself when it is a bare path.
+            const paths = ticked.length ? ticked.filter(path) : path(item) && !/\s/.test(item) ? [item] : [];
+            goal[section].push(...paths.map(p => p.replace(/^\.\//, '')));
+        }
+    }
+    return goal;
+}
+/** Whether the description declares anything the deterministic checks can check. */
+export function hasCheckableGoal(goal) {
+    return goal.scope.length > 0 || goal.outOfScope.length > 0 || goal.doneWhen.some(item => item.paths.length + item.symbols.length > 0);
+}
+/** Whether a file is covered by a declared path: a glob, a folder (with or without a trailing slash), or the file itself. */
+function covers(pattern, file) {
+    if (/[*?[\]{}]/.test(pattern))
+        return micromatch.isMatch(file, pattern, { dot: true });
+    const folder = pattern.replace(/\/+$/, '');
+    return file === folder || file.startsWith(`${folder}/`);
+}
+/** Tests, snapshots, lockfiles, changelogs and release notes follow the code they belong to: never scope drift on their own. */
+const EXEMPT = [/(^|\/)(__tests__|tests?|spec|__snapshots__)\//, /\.(test|spec)\.[A-Za-z0-9]+$/, /\.snap$/,
+    /(^|\/)(CHANGELOG|CHANGES|HISTORY|RELEASE_NOTES)(\.md)?$/i, /(^|\/)(releases|release-notes)\/[^/]+\.md$/, /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|go\.sum|Gemfile\.lock|composer\.lock|bun\.lockb)$/];
+/**
+ * The goal's deterministic findings for a change. `changedLines` is the review's changed lines per file (generated files
+ * already left out); a deleted file has none and is read from the diff's headers, left out too when `isGenerated` says
+ * so. A named symbol must appear on an added or removed line.
+ */
+export function goalFailures(goal, changedLines, diff, isGenerated = () => false) {
+    const changed = {};
+    for (const [file, lines] of Object.entries(changedLines))
+        changed[file] = lines.size ? Math.min(...lines) : undefined;
+    for (const m of diff.matchAll(/^--- a\/(.+)\n\+\+\+ \/dev\/null$/gm))
+        if (!(m[1] in changed) && !isGenerated(m[1]))
+            changed[m[1]] = undefined;
+    const touched = diff.split('\n').filter(line => /^[+-]/.test(line) && !/^(\+\+\+|---) /.test(line)).map(line => line.slice(1)).join('\n');
+    const failures = [];
+    const files = Object.keys(changed).sort();
+    // A file a "Done when" item names is part of the goal, whatever Scope lists.
+    const inScope = [...goal.scope, ...goal.doneWhen.flatMap(item => item.paths)];
+    for (const file of files) {
+        if (EXEMPT.some(pattern => pattern.test(file)))
+            continue;
+        const excluded = goal.outOfScope.find(pattern => covers(pattern, file));
+        const outside = !excluded && goal.scope.length > 0 && !inScope.some(pattern => covers(pattern, file));
+        if (!excluded && !outside)
+            continue;
+        failures.push({
+            id: 'goal-scope',
+            title: excluded ? `Changes ${file}, which the description declares out of scope (\`${excluded}\`)` : `Changes ${file}, outside the scope the description declares`,
+            details: excluded
+                ? `The pull request's description lists \`${excluded}\` under "Out of scope", and this change edits ${file}.`
+                : `The pull request's description limits the change to ${goal.scope.map(s => `\`${s}\``).join(', ')}, and this change edits ${file}.`,
+            severity: 'high',
+            provenance: 'ai-drift',
+            files: [file],
+            ...(changed[file] ? { line: changed[file] } : {}),
+            hint: 'Move this change to its own pull request, or add the path to the description\'s Scope if it belongs to this goal.',
+        });
+    }
+    for (const item of goal.doneWhen) {
+        const missingPaths = item.paths.filter(p => !files.some(file => covers(p.replace(/^\.\//, ''), file) || file.endsWith(`/${p}`)));
+        const missingSymbols = item.symbols.filter(symbol => !new RegExp(`(^|[^\\w$])${symbol.replace(/[.$]/g, m => `\\${m}`)}([^\\w$]|$)`, 'm').test(touched));
+        // A file the change never touches is proof the item is not done; a symbol is not: an item can name one it keeps as is ("still the only check").
+        if (missingPaths.length)
+            failures.push({
+                id: 'goal-done-when',
+                title: `"Done when" names ${missingPaths.map(m => `\`${m}\``).join(', ')}, and the change never touches ${missingPaths.length === 1 ? 'it' : 'them'}`,
+                details: `The description's "Done when" says: ${item.text}`,
+                severity: 'high',
+                provenance: 'ai-drift',
+                files: [],
+                hint: 'Make the change the item asks for, or correct the item if the goal changed.',
+            });
+        if (missingSymbols.length)
+            failures.push({
+                id: 'goal-done-when',
+                title: `${missingSymbols.map(m => `\`${m}\``).join(', ')} named in "Done when", not changed by this pull request: check it's met`,
+                details: `The description's "Done when" says: ${item.text}`,
+                severity: 'medium',
+                provenance: 'ai-drift',
+                files: [],
+                advisory: true,
+                hint: 'If the item asks for a change, make it; if it states something the change keeps true, nothing to do.',
+            });
+    }
+    return failures;
+}
+/** The most declared items a judge is asked about: a goal is a few lines, and each item is a judge's turn. */
+const MODEL_GOAL_MAX_ITEMS = 12;
+/**
+ * What only a reader of the code can judge: the "Done when" items that name no file (prose, or a symbol) and the
+ * invariants. An item that names a file is proven or broken by goalFailures, without a model.
+ */
+export function modelGoalItems(goal) {
+    return [
+        ...goal.doneWhen.filter(item => item.paths.length === 0).map(item => ({ kind: 'done', text: item.text })),
+        ...goal.invariants.map(text => ({ kind: 'invariant', text })),
+    ].slice(0, MODEL_GOAL_MAX_ITEMS);
+}

package/dist/goal/hook.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from '../types/index.js';
+import type { ReviewResult } from '../review/review.js';
+import { type Exec } from '../review/reviewer/exec.js';
+/** The open pull request's description for this branch, when the goal check is on; undefined otherwise or when it cannot be read. */
+export declare function hookGoalDescription(cwd: string, config: Config, exec?: Exec): Promise<string | undefined>;
+/** Records on the task's thread what the goal check did at a stop or a push; nothing when it had no description to check. */
+export declare function recordGoal(cwd: string, moment: 'stop' | 'push', description: string | undefined, result: Pick<ReviewResult, 'goal' | 'findings'>): void;

package/dist/goal/hook.js

@@ -0,0 +1,100 @@
+/**
+ * The goal at the stop hook and the push gate: the description of the branch's open pull request, read with one `gh`
+ * call, cached per branch and HEAD unless that commit was blocked by it (the author may have fixed the description, not
+ * the code), and skipped silently when there is none or gh cannot answer. Only the deterministic
+ * checks run there (goal/goal.ts): no model at a stop or a push. The same switch and floor as `rigour review --goal`.
+ */
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { defaultExec } from '../review/reviewer/exec.js';
+import { appendTaskEvent, threadsDir } from '../task/thread.js';
+import { resolveSwitch } from '../switches.js';
+/** A stop or a push waits at most this long for GitHub in all: the goal is worth a check, not a stall. */
+const HOOK_GH_TIMEOUT_MS = 5_000;
+/** The open pull request's description for this branch, when the goal check is on; undefined otherwise or when it cannot be read. */
+export async function hookGoalDescription(cwd, config, exec = defaultExec) {
+    if (!resolveSwitch('goal', config).enabled)
+        return undefined;
+    const branch = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const head = git(cwd, ['rev-parse', 'HEAD']);
+    const dir = threadsDir(cwd);
+    if (!branch || branch === 'HEAD' || !head || !dir)
+        return undefined;
+    const file = cacheFile(dir);
+    const cache = readCache(file);
+    if (cache[branch]?.head === head && !cache[branch].blocked)
+        return cache[branch].body ?? undefined;
+    const body = await openDescription(cwd, branch, config, exec);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ ...cache, [branch]: { head, body: body ?? null } }));
+    }
+    catch {
+        // a cache that cannot be written costs one more gh call next time, never the check
+    }
+    return body;
+}
+/** Records on the task's thread what the goal check did at a stop or a push; nothing when it had no description to check. */
+export function recordGoal(cwd, moment, description, result) {
+    if (description === undefined)
+        return;
+    const blocks = result.findings.filter(f => f.id.startsWith('goal-')).length;
+    appendTaskEvent(cwd, { kind: 'goal', moment, declared: !!result.goal, blocks });
+    // A block's fix may be the description itself ("add the path to Scope"): never serve this commit's copy again.
+    const branch = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const dir = threadsDir(cwd);
+    if (!blocks || !branch || !dir)
+        return;
+    const file = cacheFile(dir);
+    const cache = readCache(file);
+    if (!cache[branch])
+        return;
+    try {
+        fs.writeFileSync(file, JSON.stringify({ ...cache, [branch]: { ...cache[branch], blocked: true } }));
+    }
+    catch {
+        // unwritten, the next attempt serves the cached copy; never a failure of the stop or the push
+    }
+}
+function cacheFile(threads) {
+    return path.join(path.dirname(threads), 'goal-cache.json');
+}
+async function openDescription(cwd, branch, config, exec) {
+    try {
+        // One budget for every call: the token, when an account is named, and the pull request.
+        const deadline = Date.now() + HOOK_GH_TIMEOUT_MS;
+        const account = config.review?.github_account ?? process.env.RIGOUR_GITHUB_ACCOUNT;
+        let env;
+        if (account && !process.env.GH_TOKEN) {
+            const token = await exec('gh', ['auth', 'token', '--user', account], { cwd, timeoutMs: HOOK_GH_TIMEOUT_MS });
+            if (token.exitCode !== 0 || !token.stdout.trim())
+                return undefined;
+            env = { GH_TOKEN: token.stdout.trim() };
+        }
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return undefined;
+        const view = await exec('gh', ['pr', 'view', branch, '--json', 'state,body'], { cwd, timeoutMs: left, ...(env ? { env } : {}) });
+        if (view.exitCode !== 0)
+            return undefined;
+        const pr = JSON.parse(view.stdout);
+        return pr?.state === 'OPEN' && typeof pr.body === 'string' ? pr.body : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 5_000 });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}

package/dist/hooks/stop-review.js

@@ -20,6 +20,7 @@ import { diffFromGit } from '../review/git-diff.js';
 import { branchBase } from '../gates/logic-drift-git-base.js';
 import { branchFailures } from '../review/branch-checks.js';
 import { describeLesson } from '../review-learning/team-lessons.js';
+import { hookGoalDescription, recordGoal } from '../goal/hook.js';
 export const STOP_MAX_ATTEMPTS = 3;
 const MAX_LISTED = 8;
 /** The branch since it left main; on main, what the session changed since its baseline (session-state.ts). */
@@ -36,7 +37,9 @@ function stopSource(cwd, sessionBaseline) {
 export async function stopReview(cwd, config, attempt, sessionBaseline) {
     const { source, against } = stopSource(cwd, sessionBaseline);
     const diff = diffFromGit(cwd, source);
-    const result = await reviewChange({ cwd, config, diff, source });
+    const goalDescription = await hookGoalDescription(cwd, config);
+    const result = await reviewChange({ cwd, config, diff, source, ...(goalDescription !== undefined ? { goalDescription } : {}) });
+    recordGoal(cwd, 'stop', goalDescription, result);
     const branch = branchBase(cwd);
     const whole = branch && !branch.onMain ? branchFailures(cwd, branch.base, branch.mainRef, config) : [];
     // A check that could not run is never a pass; the attempt cap keeps a broken environment from looping forever.

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { isControlFile, mergeBaseOf, readStateFile } from './review/trusted-stat
 export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSplit, DISMISSED_FILE } from './review/quiet.js';
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH, type Ledger, type RoundResult } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
+export type { CiResult, FollowUp, PrOutcome } from './outcomes/outcome.js';
+export { runOutcomes, type OutcomesRun } from './outcomes/run.js';
 export { fixScope, type FixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
 export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
@@ -29,6 +31,9 @@ export { branchFailures, mergeConflicts, staleReferences } from './review/branch
 export { runReviewer, reviewerBlocks, itemLine, defaultExec, githubToken, type ReviewerOptions, type ReviewerResult, type ReviewerOutcome, type OpenItem } from './review/reviewer.js';
 export { startBackgroundReview, backgroundReview, reviewStatus, type ReviewStatus } from './review/reviewer/background.js';
 export { dismissReviewerFinding, REVIEW_DISMISSALS, reviewerInputs } from './review/reviewer/context.js';
+export { goalFailures, hasCheckableGoal, parseGoal, type DoneItem, type Goal } from './goal/goal.js';
+export { resolveSwitch, saveUserSwitch, SWITCHES, type ResolvedSwitch, type SwitchName, type TeamSwitch } from './switches.js';
+export { hookGoalDescription, recordGoal } from './goal/hook.js';
 export { resolveReviewer, saveUserReviewer, type ResolvedReviewer, type RunChoice, type UserReviewerPatch } from './review/reviewer/settings.js';
 export { reviewerAvailability } from './review/reviewer/adapters.js';
 export { branchBase, type BranchBase } from './gates/logic-drift-git-base.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export { isControlFile, mergeBaseOf, readStateFile } from './review/trusted-stat
 export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSplit, DISMISSED_FILE } from './review/quiet.js';
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
+export { runOutcomes } from './outcomes/run.js';
 export { fixScope } from './review/fix-scope.js';
 export { isGeneratedFile } from './review/generated-files.js';
 export { costBucket, countUsage, doNotTrack, durationBucket, flushDailyUsage, isTelemetryEnabled, readTelemetryState, setTelemetryEnabled, shouldAskTelemetry, telemetryToken, trackUsage } from './telemetry/telemetry.js';
@@ -29,6 +30,9 @@ export { branchFailures, mergeConflicts, staleReferences } from './review/branch
 export { runReviewer, reviewerBlocks, itemLine, defaultExec, githubToken } from './review/reviewer.js';
 export { startBackgroundReview, backgroundReview, reviewStatus } from './review/reviewer/background.js';
 export { dismissReviewerFinding, REVIEW_DISMISSALS, reviewerInputs } from './review/reviewer/context.js';
+export { goalFailures, hasCheckableGoal, parseGoal } from './goal/goal.js';
+export { resolveSwitch, saveUserSwitch, SWITCHES } from './switches.js';
+export { hookGoalDescription, recordGoal } from './goal/hook.js';
 export { resolveReviewer, saveUserReviewer } from './review/reviewer/settings.js';
 export { reviewerAvailability } from './review/reviewer/adapters.js';
 export { branchBase } from './gates/logic-drift-git-base.js';

package/dist/outcomes/outcome.d.ts

@@ -0,0 +1,80 @@
+import { type Exec } from '../review/reviewer/exec.js';
+/**
+ * failure: a check that passed on the commit before the merge failed on the merge commit (the merge broke it; a check
+ * already failing on main says nothing about this pull request); success: none did; pending while one runs; none when
+ * there are no runs; unavailable when GitHub could not say.
+ */
+export type CiResult = 'success' | 'failure' | 'pending' | 'none' | 'unavailable';
+export interface FollowUp {
+    sha: string;
+    at: string;
+    subject: string;
+    /** The pull request's files this commit touched. */
+    files: string[];
+    /** Its subject says it fixed something (the same words review-learning reads). */
+    fix: boolean;
+}
+export interface PrOutcome {
+    pr: number;
+    mergeSha: string;
+    mergedAt: string;
+    branch: string;
+    /** Who wrote the pull request: independence between pull requests is judged by it. */
+    author: string;
+    /** What the merge changed on main: its first-parent diff. */
+    files: string[];
+    ci: CiResult;
+    followUps: FollowUp[];
+    /** The commit that reverted it, when one did. */
+    reverted?: {
+        sha: string;
+        subject: string;
+    };
+    /** The end of the window: later commits count up to here. */
+    windowEnd: string;
+    /** The window has closed and CI has an answer: the record never changes again. */
+    settled: boolean;
+    checkedAt: string;
+}
+export interface OutcomeOptions {
+    mainRef: string;
+    windowDays: number;
+    /** Only history before this time (a backtest); now when unset. */
+    until?: string;
+    /** The CI result for the merge commit against the commit before it on main (gh); `unavailable` when it cannot be read. */
+    ci: (sha: string, parent: string) => Promise<CiResult>;
+    /** How git is run (tests count the calls); `spawnSync` by default. */
+    git?: (args: string[]) => string;
+}
+type MergedRef = {
+    number: number;
+    mergeSha: string;
+    mergedAt: string;
+    branch: string;
+    author: string;
+};
+/**
+ * The CI result for a merge commit from all its check runs, every page (a big matrix runs more than 100: a failure on
+ * page two must not read as success). A run that failed is counted only when the same check did not fail on the commit
+ * before the merge, read only then: on a main branch where a check is often red, "any run failed" says nothing about the
+ * pull request. Any error is `unavailable`, never a throw.
+ */
+export declare function checkRunsCi(cwd: string, exec: Exec, env?: Record<string, string>): (sha: string, parent: string) => Promise<CiResult>;
+interface OutcomeStore {
+    version: 1;
+    outcomes: Record<string, PrOutcome>;
+}
+export declare function readPrOutcomes(cwd: string): OutcomeStore;
+/**
+ * Brings the store up to date for these merged pull requests: a settled record is kept as it is, anything else is read
+ * again. The branch's thread (when this machine has one) gets a `merge` event the first time and an `outcome` event when
+ * the record settles. Stops at `deadline` (ms since epoch) and says so: what was read is kept.
+ */
+export declare function updatePrOutcomes(cwd: string, prs: MergedRef[], options: OutcomeOptions & {
+    deadline?: number;
+}): Promise<{
+    outcomes: PrOutcome[];
+    read: number;
+    stopped?: string;
+}>;
+export {};

package/dist/outcomes/outcome.js

@@ -0,0 +1,161 @@
+/**
+ * What happened after a pull request merged: the CI result on its merge commit, the later commits on main that touched
+ * its files within the window, and whether it was reverted. One record per merge commit, computed from git and one
+ * GitHub read, and kept in `.rigour/outcomes.json`. Once the window has closed and CI has an answer, the record is
+ * settled: it never changes and is never read from GitHub again.
+ *
+ * Follow-ups are read on main's first-parent history, by file, so a merge commit and a squash merge are read the same
+ * way. Nothing here changes a lesson: lessons read these records as evidence (review-learning).
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { FIX, revertsPr } from '../review-learning/outcomes.js';
+import { GH_TIMEOUT_MS } from '../review/reviewer/exec.js';
+import { appendBranchEvent } from '../task/thread.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** An unsettled record read this recently is kept as it is: its window is open, and reading it again every run starves the older ones. */
+const RECHECK_MS = 12 * 60 * 60 * 1000;
+const OUTCOMES_FILE = path.join('.rigour', 'outcomes.json');
+/** The outcome of one merged pull request as of now (or `until`), its follow-ups taken from main's log read once for the run. */
+async function prOutcome(pr, options, run, log) {
+    const now = options.until ? Date.parse(options.until) : Date.now();
+    const windowEnd = new Date(Math.min(Date.parse(pr.mergedAt) + options.windowDays * DAY_MS, now)).toISOString();
+    const closed = Date.parse(pr.mergedAt) + options.windowDays * DAY_MS <= now;
+    const files = lines(run(['diff', '--name-only', `${pr.mergeSha}^1`, pr.mergeSha]));
+    const followUps = followUpsOf(log, pr, files, windowEnd);
+    const revert = followUps.find(f => revertsPr(f.subject, pr));
+    const ci = await options.ci(pr.mergeSha, `${pr.mergeSha}^1`);
+    return {
+        pr: pr.number, mergeSha: pr.mergeSha, mergedAt: pr.mergedAt, branch: pr.branch, author: pr.author, files, ci, followUps,
+        ...(revert ? { reverted: { sha: revert.sha, subject: revert.subject } } : {}),
+        windowEnd,
+        settled: closed && (ci === 'success' || ci === 'failure' || ci === 'none'),
+        checkedAt: new Date(now).toISOString(),
+    };
+}
+/** The commits after the merge on main's first-parent history, up to the window's end, that touched any of the pull request's files. */
+function followUpsOf(log, pr, files, windowEnd) {
+    const wanted = new Set(files);
+    const merged = log.findIndex(c => c.sha === pr.mergeSha);
+    // The merge itself is in the log (it is read from a day before the earliest merge); without it, time decides.
+    const after = merged >= 0 ? log.slice(merged + 1) : log.filter(c => c.at > pr.mergedAt);
+    return after.filter(c => c.at <= windowEnd).flatMap(c => {
+        const touched = c.files.filter(file => wanted.has(file));
+        return touched.length ? [{ sha: c.sha, at: c.at, subject: c.subject, files: touched, fix: FIX.test(c.subject) }] : [];
+    });
+}
+/**
+ * Main's first-parent history between two times, oldest first, with each commit's files: read once for every pull
+ * request a run brings up to date (their windows overlap). The files are matched in code, not passed to git: a large
+ * pull request's paths would pass the command-line limit (about 32 KB on Windows).
+ */
+function mainLog(run, mainRef, since, until) {
+    const out = run(['log', '--first-parent', '--name-only', '--format=%x00%H%x09%cI%x09%s', `--since=${since}`, `--until=${until}`, mainRef]);
+    return out.split('\0').filter(Boolean).flatMap(block => {
+        const [header, ...rest] = block.split('\n');
+        const [sha, at, ...subject] = header.split('\t');
+        return sha && at ? [{ sha, at, subject: subject.join('\t'), files: rest.map(line => line.trim()).filter(Boolean) }] : [];
+    }).reverse();
+}
+/**
+ * The CI result for a merge commit from all its check runs, every page (a big matrix runs more than 100: a failure on
+ * page two must not read as success). A run that failed is counted only when the same check did not fail on the commit
+ * before the merge, read only then: on a main branch where a check is often red, "any run failed" says nothing about the
+ * pull request. Any error is `unavailable`, never a throw.
+ */
+export function checkRunsCi(cwd, exec, env) {
+    const runs = async (sha) => {
+        try {
+            const read = await exec('gh', ['api', '--paginate', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`, '--jq', '[.check_runs[] | {name, status, conclusion}]'], { cwd, timeoutMs: GH_TIMEOUT_MS, ...(env ? { env } : {}) });
+            if (read.exitCode !== 0)
+                return undefined;
+            // One array per page; unlike parseJsonArrays, output that does not parse is unavailable here, never an empty "none" that would settle.
+            return JSON.parse(`[${read.stdout.trim().replace(/\]\s*\[/g, '],[')}]`).flat();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return async (sha, parent) => {
+        const merge = await runs(sha);
+        if (!merge)
+            return 'unavailable';
+        const failed = merge.filter(failedRun);
+        if (failed.length === 0)
+            return ciFrom(merge);
+        const before = await runs(parent);
+        if (!before)
+            return 'unavailable';
+        const redBefore = new Set(before.filter(failedRun).map(r => r.name));
+        return failed.some(r => !redBefore.has(r.name)) ? 'failure' : ciFrom(merge.filter(r => !failedRun(r)));
+    };
+}
+function failedRun(run) {
+    return run.conclusion === 'failure' || run.conclusion === 'timed_out';
+}
+/** With no new failure: a run still going keeps it pending; cancelled and skipped runs say nothing. */
+function ciFrom(runs) {
+    if (!Array.isArray(runs) || runs.length === 0)
+        return 'none';
+    if (runs.some(r => r.status !== 'completed'))
+        return 'pending';
+    return runs.some(r => r.conclusion === 'success') ? 'success' : 'none';
+}
+export function readPrOutcomes(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, OUTCOMES_FILE), 'utf8'));
+        return parsed?.version === 1 && parsed.outcomes && typeof parsed.outcomes === 'object' ? parsed : { version: 1, outcomes: {} };
+    }
+    catch {
+        return { version: 1, outcomes: {} };
+    }
+}
+/**
+ * Brings the store up to date for these merged pull requests: a settled record is kept as it is, anything else is read
+ * again. The branch's thread (when this machine has one) gets a `merge` event the first time and an `outcome` event when
+ * the record settles. Stops at `deadline` (ms since epoch) and says so: what was read is kept.
+ */
+export async function updatePrOutcomes(cwd, prs, options) {
+    const store = readPrOutcomes(cwd);
+    const result = [];
+    const run = options.git ?? ((args) => git(cwd, args));
+    let read = 0;
+    let stopped;
+    const now = options.until ? Date.parse(options.until) : Date.now();
+    const fresh = (outcome) => !!outcome && (outcome.settled || now - Date.parse(outcome.checkedAt) < RECHECK_MS);
+    // Oldest merge first: those are the ones whose windows close, so a run cut short by the deadline still moves records
+    // towards settled instead of reading the newest, still-open ones again and again.
+    const pending = prs.filter(pr => pr.mergeSha && !fresh(store.outcomes[pr.mergeSha])).sort((a, b) => (a.mergedAt < b.mergedAt ? -1 : 1));
+    // Main's log once, across every pull request to read: from a day before the earliest merge (so each merge commit is in
+    // it) to the latest window's end, bounded at both ends.
+    const log = pending.length ? mainLog(run, options.mainRef, new Date(Math.min(...pending.map(pr => Date.parse(pr.mergedAt))) - DAY_MS).toISOString(), new Date(Math.min(now, Math.max(...pending.map(pr => Date.parse(pr.mergedAt))) + options.windowDays * DAY_MS)).toISOString()) : [];
+    for (const pr of pending) {
+        if (options.deadline !== undefined && Date.now() > options.deadline) {
+            stopped = `read deadline reached after ${read} pull request(s); run again to read the rest`;
+            break;
+        }
+        const known = store.outcomes[pr.mergeSha];
+        const outcome = await prOutcome(pr, options, run, log);
+        read++;
+        if (!known)
+            appendBranchEvent(cwd, pr.branch, { kind: 'merge', pr: pr.number, merge_sha: pr.mergeSha, merged_at: pr.mergedAt });
+        if (outcome.settled)
+            appendBranchEvent(cwd, pr.branch, { kind: 'outcome', pr: pr.number, ci: outcome.ci, follow_ups: outcome.followUps.length, fixes: outcome.followUps.filter(f => f.fix).length, reverted: !!outcome.reverted });
+        store.outcomes[pr.mergeSha] = outcome;
+    }
+    // In the order asked for: every record known for these pull requests, read now or kept.
+    for (const pr of prs)
+        if (pr.mergeSha && store.outcomes[pr.mergeSha])
+            result.push(store.outcomes[pr.mergeSha]);
+    fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, OUTCOMES_FILE), JSON.stringify(store, null, 2) + '\n');
+    return { outcomes: result, read, ...(stopped ? { stopped } : {}) };
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 60_000 });
+    return result.status === 0 ? result.stdout : '';
+}
+function lines(text) {
+    return text.split('\n').map(line => line.trim()).filter(Boolean);
+}