@rigour-labs/core 6.9.0-rc.3 → 6.9.0-rc.4

package/dist/index.d.ts

@@ -20,7 +20,8 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSpli
 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 { localOutcomeMetrics, runOutcomes, type OutcomesRun } from './outcomes/run.js';
+export type { OutcomeMetrics, Share } from './outcomes/metrics.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';
@@ -46,7 +47,7 @@ export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsRe
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH, type LastReport } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact, type ReviewRecord } from './review/reviewer/record.js';
-export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';

package/dist/index.js

@@ -19,7 +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 { localOutcomeMetrics, 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';
@@ -45,7 +45,7 @@ export { learnFromReviews } from './review-learning/learn-from-reviews.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact } from './review/reviewer/record.js';
-export { readLessons, writeLessons, decideLesson, lessonState, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';

package/dist/outcomes/metrics.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The outcome loop's numbers: the one place they are counted (Studio, `rigour outcomes --json` and telemetry read this,
+ * never their own count). The shape is versioned and documented in docs/OUTCOMES.md, "Numbers".
+ *
+ * Counts only, over what this machine read. A rate is given only when at least MIN_FOR_RATE records are behind it;
+ * below that it is null with the reason. Pull requests a review by Rigour saw and pull requests it did not are counted
+ * side by side and never compared: teams choose which pull requests get reviewed, so the two groups differ, and a gap
+ * between them is not Rigour's effect.
+ */
+import type { ReviewLesson } from '../review-learning/lessons.js';
+import type { PrOutcome } from './outcome.js';
+export interface Share {
+    count: number;
+    of: number;
+    /** count / of, two decimals; null when `of` is under MIN_FOR_RATE. */
+    rate: number | null;
+    reason?: string;
+}
+export interface OutcomeMetrics {
+    version: 1;
+    records: {
+        merged: number;
+        settled: number;
+        unsettled: number;
+    };
+    /** Over settled records only: an open window can still change. */
+    settled: {
+        /** Over settled records whose CI result is known (passed or failed): one with no CI to read never dilutes it. */
+        ciRegressed: Share;
+        /** Settled records with no CI result to read. */
+        ciUnknown: number;
+        reverted: Share;
+        /** A later commit on its files, inside the window, that says it fixes something. */
+        fixedLater: Share;
+        /** Side by side, never compared (see above). */
+        reviewed: {
+            prs: number;
+            fixedLater: Share;
+        };
+        notReviewed: {
+            prs: number;
+            fixedLater: Share;
+        };
+    };
+    lessons: {
+        /** Candidates waiting on a person: a later fix on their lines, back to candidate, or taken back. */
+        awaitingDecision: number;
+        /** Promoted by a person after such evidence. */
+        promotedFromEvidence: number;
+        dismissed: number;
+        /** Taken back by evidence and not promoted again since. */
+        takenBack: number;
+    };
+}
+/** `reviewed`: the pull requests a review by Rigour ran on (the threads' review events). */
+export declare function outcomeMetrics(records: PrOutcome[], lessons: ReviewLesson[], reviewed: Set<number>): OutcomeMetrics;

package/dist/outcomes/metrics.js

@@ -0,0 +1,38 @@
+import { pendingDecision } from '../review-learning/lessons.js';
+/** Fewer records than this give a count, never a percentage. */
+const MIN_FOR_RATE = 10;
+/** `reviewed`: the pull requests a review by Rigour ran on (the threads' review events). */
+export function outcomeMetrics(records, lessons, reviewed) {
+    const settled = records.filter(r => r.settled);
+    const fixed = (r) => r.followUps.some(f => f.fix);
+    const inReview = settled.filter(r => reviewed.has(r.pr));
+    const notInReview = settled.filter(r => !reviewed.has(r.pr));
+    return {
+        version: 1,
+        records: { merged: records.length, settled: settled.length, unsettled: records.length - settled.length },
+        settled: {
+            ciRegressed: share(settled.filter(r => r.ci === 'failure').length, settled.filter(r => r.ci === 'success' || r.ci === 'failure').length),
+            ciUnknown: settled.filter(r => r.ci !== 'success' && r.ci !== 'failure').length,
+            reverted: share(settled.filter(r => !!r.reverted).length, settled.length),
+            fixedLater: share(settled.filter(fixed).length, settled.length),
+            reviewed: { prs: inReview.length, fixedLater: share(inReview.filter(fixed).length, inReview.length) },
+            notReviewed: { prs: notInReview.length, fixedLater: share(notInReview.filter(fixed).length, notInReview.length) },
+        },
+        lessons: {
+            awaitingDecision: lessons.filter(l => pendingDecision(l)).length,
+            promotedFromEvidence: lessons.filter(promotedAfterEvidence).length,
+            dismissed: lessons.filter(l => l.evidence.some(e => e.kind === 'dismissed')).length,
+            takenBack: lessons.filter(l => pendingDecision(l)?.kind === 'demoted').length,
+        },
+    };
+}
+function share(count, of) {
+    return of >= MIN_FOR_RATE
+        ? { count, of, rate: Math.round((count / of) * 100) / 100 }
+        : { count, of, rate: null, reason: `fewer than ${MIN_FOR_RATE} records: a count, not a rate` };
+}
+/** A person's promotion that came after a later fix on its lines, a reclassification or a take-back. */
+function promotedAfterEvidence(lesson) {
+    const evidenceAt = lesson.evidence.findIndex(e => e.kind === 'lines' || e.kind === 'reclassified' || e.kind === 'demoted');
+    return evidenceAt >= 0 && lesson.evidence.slice(evidenceAt + 1).some(e => e.kind === 'accepted') && lesson.state === 'verified';
+}

package/dist/outcomes/run.d.ts

@@ -8,6 +8,7 @@ import { type Exec } from '../review/reviewer/exec.js';
 import { type ResolvedSwitch } from '../switches.js';
 import { type PrOutcome } from './outcome.js';
 import { type OutcomeEvidenceResult } from '../review-learning/outcome-evidence.js';
+import { type OutcomeMetrics } from './metrics.js';
 export interface OutcomesRun {
     switch: ResolvedSwitch;
     outcomes: PrOutcome[];
@@ -17,6 +18,8 @@ export interface OutcomesRun {
     stopped?: string;
     /** What the records did to the team's review lessons (review-learning/outcome-evidence.ts). */
     lessons?: OutcomeEvidenceResult;
+    /** The outcome numbers over every record kept (metrics.ts). */
+    metrics?: OutcomeMetrics;
 }
 export declare function runOutcomes(cwd: string, config: Config, options: {
     flag?: boolean;
@@ -24,3 +27,5 @@ export declare function runOutcomes(cwd: string, config: Config, options: {
     last?: number;
     exec?: Exec;
 }): Promise<OutcomesRun>;
+/** The outcome numbers for this checkout (metrics.ts), over every record it keeps; undefined when it keeps none. Read-only. */
+export declare function localOutcomeMetrics(cwd: string): OutcomeMetrics | undefined;

package/dist/outcomes/run.js

@@ -7,6 +7,7 @@ import { applyOutcomeEvidence } from '../review-learning/outcome-evidence.js';
 import { readLessons, writeLessons } from '../review-learning/lessons.js';
 import { gitIn } from '../review-learning/acted-on.js';
 import { eventsOfKind } from '../task/thread.js';
+import { outcomeMetrics } from './metrics.js';
 /** How long one run may read before it stops and keeps what it has. */
 const READ_DEADLINE_MS = 2 * 60_000;
 /** How long one run may follow points' lines through history; the next run carries on. */
@@ -30,16 +31,28 @@ export async function runOutcomes(cwd, config, options) {
     const incomplete = listed.incomplete ? 'the list of merged pull requests may be incomplete (gh listed too many updates to prove it)' : undefined;
     const stopped = [run.stopped, incomplete].filter(Boolean).join('; ');
     const lessons = lessonEvidence(cwd, mainRef, config.learning?.outcomes?.demote_after ?? 2);
-    return { switch: resolved, outcomes: run.outcomes, read: run.read, ...(lessons ? { lessons } : {}), ...(stopped ? { stopped } : {}) };
+    const metrics = localOutcomeMetrics(cwd);
+    return { switch: resolved, outcomes: run.outcomes, read: run.read, ...(lessons ? { lessons } : {}), ...(metrics ? { metrics } : {}), ...(stopped ? { stopped } : {}) };
 }
 /** Every record kept (not only this run's) against the team's lessons, and the reviews that found a lesson repeated; written only when something changed. */
 function lessonEvidence(cwd, mainRef, demoteAfter) {
     const lessons = readLessons(cwd);
     if (lessons.length === 0)
         return undefined;
+    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), reviews(cwd).applied, { demoteAfter, git: gitIn(cwd), mainRef, deadline: Date.now() + LESSON_DEADLINE_MS });
+    if (result.added)
+        writeLessons(cwd, lessons);
+    return result;
+}
+/** Per pull request, the lessons a review of it recorded as applying, and every pull request a review by Rigour ran on: from the threads. */
+function reviews(cwd) {
     const applied = new Map();
+    const reviewed = new Set();
     for (const e of eventsOfKind(cwd, 'review')) {
-        if (typeof e.pr !== 'number' || !Array.isArray(e.lessons_applied))
+        if (typeof e.pr !== 'number')
+            continue;
+        reviewed.add(e.pr);
+        if (!Array.isArray(e.lessons_applied))
             continue;
         const ids = applied.get(e.pr) ?? new Set();
         for (const id of e.lessons_applied)
@@ -47,10 +60,12 @@ function lessonEvidence(cwd, mainRef, demoteAfter) {
                 ids.add(id);
         applied.set(e.pr, ids);
     }
-    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), applied, { demoteAfter, git: gitIn(cwd), mainRef, deadline: Date.now() + LESSON_DEADLINE_MS });
-    if (result.added)
-        writeLessons(cwd, lessons);
-    return result;
+    return { applied, reviewed };
+}
+/** The outcome numbers for this checkout (metrics.ts), over every record it keeps; undefined when it keeps none. Read-only. */
+export function localOutcomeMetrics(cwd) {
+    const records = Object.values(readPrOutcomes(cwd).outcomes);
+    return records.length ? outcomeMetrics(records, readLessons(cwd), reviews(cwd).reviewed) : undefined;
 }
 async function onePr(cwd, pr, exec, env) {
     const view = await exec('gh', ['pr', 'view', String(pr), '--json', 'number,mergedAt,mergeCommit,headRefName,author,state'], { cwd, timeoutMs: GH_TIMEOUT_MS, ...(env ? { env } : {}) });

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

@@ -109,6 +109,12 @@ export declare function matchLessons(lessons: ReviewLesson[], change: ChangeShap
 /** RIGOUR_REVIEW_LESSONS points at a lessons file outside the clone (CI, or a team's shared copy). */
 export declare function lessonsPath(cwd: string): string;
 export declare function readLessons(cwd: string): ReviewLesson[];
+/**
+ * What a person is asked to decide on a candidate, from the last of its evidence and decisions: taken back by evidence
+ * (`demoted`), back to a candidate when outcomes stopped promoting (`reclassified`), or a later fix on its lines
+ * (`lines`); undefined when nothing waits on a person. Studio and the outcome numbers read it, so they never disagree.
+ */
+export declare function pendingDecision(lesson: ReviewLesson): LessonEvidence | undefined;
 export declare function writeLessons(cwd: string, lessons: ReviewLesson[]): void;
 /** A person's decision on a lesson, kept as evidence: accepted makes it a lesson, rejected an anti-lesson. Undefined for an unknown id. */
 export declare function decideLesson(cwd: string, id: string, decision: 'accepted' | 'rejected' | 'dismissed', by: string, why?: string): ReviewLesson | undefined;

package/dist/review-learning/lessons.js

@@ -233,6 +233,17 @@ export function readLessons(cwd) {
         return [];
     }
 }
+/**
+ * What a person is asked to decide on a candidate, from the last of its evidence and decisions: taken back by evidence
+ * (`demoted`), back to a candidate when outcomes stopped promoting (`reclassified`), or a later fix on its lines
+ * (`lines`); undefined when nothing waits on a person. Studio and the outcome numbers read it, so they never disagree.
+ */
+export function pendingDecision(lesson) {
+    if (lesson.state !== 'candidate')
+        return undefined;
+    const last = lesson.evidence.filter(e => e.kind === 'demoted' || e.kind === 'lines' || e.kind === 'reclassified' || e.kind === 'accepted' || e.kind === 'rejected' || e.kind === 'dismissed').at(-1);
+    return last?.kind === 'demoted' || last?.kind === 'lines' || last?.kind === 'reclassified' ? last : undefined;
+}
 /** Why a lesson an outcome alone had promoted is a candidate again. */
 const RECLASSIFIED = 'promoted by the exact-line rule, which no longer promotes on its own';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.9.0-rc.3",
+  "version": "6.9.0-rc.4",
   "description": "Rigour's review engine: deterministic gates on changed lines, rules and lessons learned from your team's fixes, and per-check precision from what you fix versus dismiss, across TypeScript, JavaScript, Python, Go, Ruby and C#.",
   "engines": {
     "node": ">=22.13"
@@ -75,11 +75,11 @@
     "@anthropic-ai/sdk": "^0.132.1",
     "pg": "^8.16.3",
     "openai": "^5.23.2",
-    "@rigour-labs/brain-darwin-arm64": "6.9.0-rc.3",
-    "@rigour-labs/brain-darwin-x64": "6.9.0-rc.3",
-    "@rigour-labs/brain-linux-arm64": "6.9.0-rc.3",
-    "@rigour-labs/brain-win-x64": "6.9.0-rc.3",
-    "@rigour-labs/brain-linux-x64": "6.9.0-rc.3"
+    "@rigour-labs/brain-darwin-arm64": "6.9.0-rc.4",
+    "@rigour-labs/brain-darwin-x64": "6.9.0-rc.4",
+    "@rigour-labs/brain-win-x64": "6.9.0-rc.4",
+    "@rigour-labs/brain-linux-arm64": "6.9.0-rc.4",
+    "@rigour-labs/brain-linux-x64": "6.9.0-rc.4"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",