@rigour-labs/core 6.10.1-rc.1 → 6.11.0-rc.1

package/dist/deep/pr-review.d.ts

@@ -1,6 +1,6 @@
 import type { DeepFinding, InferenceOptions, InferenceProvider } from '../inference/types.js';
 import type { CodeContext } from './code-context.js';
-import { type SettledCheck } from '../review/settled-checks.js';
+import { type CoveredLesson, type SettledCheck } from '../review/settled-checks.js';
 import type { RelatedChange } from './related-changes.js';
 export interface FocusItem {
     file: string;
@@ -22,6 +22,8 @@ export interface PrReviewInput {
     prBody?: string;
     /** What Rigour's checks already found on the change: listed as settled; a finding of the same kind at one of their lines is dropped. */
     settled?: SettledCheck[];
+    /** Lessons the team's compiled checks covered on this change, left out of `lessons`: the prompt says so. */
+    covered?: CoveredLesson[];
 }
 export interface PrReviewResult {
     findings: DeepFinding[];

package/dist/deep/pr-review.js

@@ -14,7 +14,7 @@ import { REVIEW_CATEGORIES } from './code-review-prompt.js';
 import { parseFindings } from './parse-findings.js';
 import { diffSections } from './pr-diff.js';
 import { runToolLoop } from './tool-loop.js';
-import { againstSettled, settledLine, settledSection } from '../review/settled-checks.js';
+import { againstSettled, coveredSection, settledLine, settledSection } from '../review/settled-checks.js';
 const BUDGET = { maxToolCalls: 24, maxTurns: 14 };
 const MAX_DIFF_CHARS = 80_000;
 const MAX_FINDINGS = 5;
@@ -67,6 +67,7 @@ export function buildPrPrompt(input) {
         input.prBody ? `PR DESCRIPTION (what the author intended):\n${input.prBody.slice(0, PR_BODY_CHARS)}` : '',
         input.rules ?? '',
         input.lessons ?? '',
+        coveredSection(input.covered ?? []),
         settledSection((input.settled ?? []).map(settledLine)),
         contracts ? `BOTH SIDES OF A CALL CHANGED (check these contracts first):\n${contracts}` : '',
         focus ? `LOOK FIRST (riskiest changed functions, and what to check):\n${focus}` : '',

package/dist/gates/deep-analysis.js

@@ -31,6 +31,7 @@ import { checkLocalPatterns } from '../storage/local-memory.js';
 import { isScoped } from '../utils/scope.js';
 import { Logger } from '../utils/logger.js';
 import path from 'path';
+import { withoutCovered } from '../review/settled-checks.js';
 /** Cloud setup (API connection) must not hang a check. Local setup is bounded by download stall timeouts instead. */
 const CLOUD_SETUP_TIMEOUT_MS = 120_000;
 /**
@@ -158,7 +159,7 @@ export class DeepAnalysisGate extends Gate {
         const related = relatedChanges(cwd, changedFiles, rankChangedFunctions(cwd, options.focusLines ?? {}, options.removedLines));
         this.config.onProgress?.(`  Reviewing the PR as a whole (${focus.length} risky function(s) first)...`);
         try {
-            const result = await reviewPullRequest(this.provider, { cwd, diff: options.diff, focus, related, lessons: lessonsSection(lessonsForDiff(cwd, options.diff, this.config.reviewLessons)),
+            const result = await reviewPullRequest(this.provider, { cwd, diff: options.diff, focus, related, lessons: lessonsSection(withoutCovered(lessonsForDiff(cwd, options.diff, this.config.reviewLessons), options.covered ?? [])), covered: options.covered,
                 rules: rulesSection(rulesForDiff(cwd, options.diff, this.config.repoRules)), prBody: options.prBody, settled: options.settled }, inferenceOptions(this.config));
             this.recordPass({ findings: [], chunksTotal: 1, chunksFailed: 0 });
             this.outcome.findingsProposed = result.findings.length;

package/dist/gates/runner.js

@@ -215,7 +215,7 @@ export class GateRunner {
         let deepStats = undefined;
         if (deepOptions?.enabled) {
             // What the checks found on the change's lines is settled: the model is told so and never reports it again.
-            const deep = await runDeepAnalysis(this.config, { cwd, ignore, patterns }, { ...deepOptions, settled: settledChecks(onChangedLines(failures, deepOptions.focusLines)) });
+            const deep = await runDeepAnalysis(this.config, { cwd, ignore, patterns }, { ...deepOptions, settled: [...(deepOptions.settled ?? []), ...settledChecks(onChangedLines(failures, deepOptions.focusLines))] });
             failures.push(...deep.failures);
             summary['deep-analysis'] = deep.summary;
             deepStats = deep.stats;

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest
 export { scaffoldLedger } from './review/backtest-init.js';
 export type { CiResult, FollowUp, PrOutcome } from './outcomes/outcome.js';
 export { localOutcomeMetrics, runOutcomes, type OutcomesRun } from './outcomes/run.js';
+export { learningUsage } from './telemetry/learning-usage.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';
@@ -44,6 +45,7 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction, type Funct
 export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
 export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
+export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspension, type CompiledCheck } from './review-learning/compiled-lessons.js';
 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';

package/dist/index.js

@@ -20,6 +20,7 @@ export { dismissFinding, dismissedKeys, findingKey, isProven, mustFix, quietSpli
 export { loadLedger, ledgerProblems, runBacktest, backtestPassed, formatBacktest, LEDGER_PATH } from './review/backtest.js';
 export { scaffoldLedger } from './review/backtest-init.js';
 export { localOutcomeMetrics, runOutcomes } from './outcomes/run.js';
+export { learningUsage } from './telemetry/learning-usage.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';
@@ -42,6 +43,7 @@ export { rankChangedFunctions, scoreRisk, functionHash, findFunction } from './d
 export { routeFiles } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
 export { learnFromReviews } from './review-learning/learn-from-reviews.js';
+export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspension } from './review-learning/compiled-lessons.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';

package/dist/outcomes/run.d.ts

@@ -8,7 +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';
+import { type OutcomeMetrics, type PrReviews } from './metrics.js';
 export interface OutcomesRun {
     switch: ResolvedSwitch;
     outcomes: PrOutcome[];
@@ -27,5 +27,10 @@ export declare function runOutcomes(cwd: string, config: Config, options: {
     last?: number;
     exec?: Exec;
 }): Promise<OutcomesRun>;
+/** Per pull request, the lessons a review of it recorded as applying, and every pull request a review by Rigour ran on with its rounds' dollars and its first review's findings: from the threads. */
+export declare function threadReviews(cwd: string): {
+    applied: Map<number, Set<string>>;
+    reviewed: Map<number, PrReviews>;
+};
 /** 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

@@ -39,13 +39,13 @@ 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 });
+    const result = applyOutcomeEvidence(lessons, Object.values(readPrOutcomes(cwd).outcomes), threadReviews(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 with its rounds' dollars and its first review's findings: from the threads. */
-function reviews(cwd) {
+export function threadReviews(cwd) {
     const applied = new Map();
     const reviewed = new Map();
     const count = (v) => typeof v === 'number' ? v : 0;
@@ -72,7 +72,7 @@ function reviews(cwd) {
 /** 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;
+    return records.length ? outcomeMetrics(records, readLessons(cwd), threadReviews(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/check-outcomes.js

@@ -13,6 +13,8 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { telemetryCheckId } from '../telemetry/check-ids.js';
+import { countUsage } from '../telemetry/telemetry.js';
 import { readStateFile } from './trusted-state.js';
 const OUTCOMES_FILE = path.join('.rigour', 'check-outcomes.json');
 const REPORTED_FILE = path.join('.rigour', 'reported-findings.json');
@@ -49,6 +51,12 @@ export function recordOutcome(cwd, check, kind) {
     const current = outcomes[check] ?? { fixed: 0, dismissed: 0 };
     outcomes[check] = { ...current, [kind]: current[kind] + 1 };
     writeJson(path.join(cwd, OUTCOMES_FILE), outcomes);
+    // The same outcome, counted for opt-in telemetry by the check's gate id only, and only if it is one of Rigour's own.
+    countUsage(`finding_${kind}:${telemetryCheckId(gateOf(check))}`);
+}
+/** A check id's gate: `semantic-bugs` of `semantic-bugs: Credential header follows redirects`. */
+function gateOf(check) {
+    return check.split(':')[0].trim();
 }
 /** Every check with an outcome, most dismissed first. */
 export function checkPrecisions(cwd) {

package/dist/review/learning-events.js

@@ -1,4 +1,6 @@
 import { appendAgentEvent } from './effectiveness.js';
+import { countUsage } from '../telemetry/telemetry.js';
+import { telemetryCheckId } from '../telemetry/check-ids.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) {
@@ -10,6 +12,9 @@ export function recordLessonsServed(cwd, via, subjects) {
 export function recordPrCatches(cwd, findings) {
     if (findings.length === 0)
         return;
+    // A finding that reached a pull request's review: counted for opt-in telemetry by its gate id only, if one of Rigour's own.
+    for (const finding of findings)
+        countUsage(`finding_pushed:${telemetryCheckId(finding.id)}`);
     appendAgentEvent(cwd, {
         type: 'pr_catches',
         findings: findings.slice(0, MAX_LISTED).map(f => ({ rule: f.id, title: f.title, file: f.files?.[0] ?? '' })),

package/dist/review/quiet.js

@@ -20,7 +20,7 @@ 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', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'migration-order',
+const PROVEN_GATES = new Set(['compiled-lesson', 'semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'migration-order',
     'duplicate-null-filter', 'nullable-filtered-column', 'optional-always-supplied', 'write-only-property', 'typed-checks-unavailable',
     'goal-scope', 'goal-done-when']);
 export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');

package/dist/review/review.d.ts

@@ -1,5 +1,6 @@
 import type { Config, DeepOptions, Failure, Report } from '../types/index.js';
 import { type DiffSource } from './git-diff.js';
+import { type CoveredLesson } from './settled-checks.js';
 import { type Goal } from '../goal/goal.js';
 export interface ReviewInput {
     cwd: string;
@@ -52,6 +53,8 @@ export interface ReviewResult {
     typedError?: string;
     /** The goal the description declared, when the goal check ran on one with something to check. */
     goal?: Goal;
+    /** The lessons the team's compiled checks covered on this change: a model reviewer is told so instead of the lesson. */
+    covered: CoveredLesson[];
 }
 export interface ReviewFinding {
     id: string;

package/dist/review/review.js

@@ -20,6 +20,8 @@ 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 { compiledChecksOn } from '../review-learning/compiled-lessons.js';
+import { settledChecks } from './settled-checks.js';
 import { orphanFileFailures } from './orphan-files.js';
 import { unusedExportFailures } from './unused-exports.js';
 import { queryPatternFailures } from './query-patterns.js';
@@ -37,9 +39,11 @@ export async function reviewChange(input) {
     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, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff), hints: [] };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff), hints: [], covered: [] };
     }
-    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
+    // The team's compiled checks run before the deep review, so it is told what they found and which lessons they covered.
+    const compiled = compiledChecksOn(input.cwd, changedLines, input.config);
+    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff, settled: settledChecks(compiled.failures), covered: compiled.covered } : undefined;
     // The team's `commands:` run at push (toolchain.ts), where a failure blocks; here they would only cost time.
     const report = await new GateRunner({ ...input.config, commands: {} }).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
     const { preexisting, baseUnknown } = await dropPreexisting(input, report, targets);
@@ -54,6 +58,7 @@ export async function reviewChange(input) {
     reviewCheck('migration-order', 'migration_order', migrationOrderFailures(input.cwd, diff, input.source, input.config));
     reviewCheck('unused-exports', 'unused_exports', unusedExportFailures(input.cwd, diff, input.config));
     reviewCheck('orphan-files', 'orphan_files', orphanFileFailures(input.cwd, diff, input.config));
+    reviewCheck('compiled-lessons', 'compiled_lessons', compiled.failures);
     reviewCheck('query-patterns', 'query_patterns', queryPatternFailures(input.cwd, changedLines, input.config));
     reviewCheck('optional-params', 'optional_params', optionalParamFailures(input.cwd, changedLines, input.config));
     reviewCheck('duplicate-functions', 'duplicate_functions', duplicateFunctionFailures(input.cwd, changedLines, input.config));
@@ -97,6 +102,7 @@ export async function reviewChange(input) {
         gateErrors,
         controlFilesChanged: controlFiles(diff),
         hints: typed.hints,
+        covered: compiled.covered,
         ...(deepError ? { deepError } : {}),
         ...(typed.error ? { typedError: typed.error } : {}),
         ...(checkedGoal ? { goal: checkedGoal } : {}),

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

@@ -3,6 +3,7 @@ import type { RouterPolicy } from '../../deep/router.js';
 import type { PanelItem } from './panel.js';
 import { type Exec } from './exec.js';
 import type { OpenItem, ServedRule } from './verdict.js';
+import { type CoveredLesson } from '../settled-checks.js';
 export declare const REVIEW_DISMISSALS: string;
 export interface ReviewDismissal {
     id: string;
@@ -43,18 +44,29 @@ export interface ContextInput {
     }>;
     /** Findings Rigour's checks already report on this change, one line each. */
     checks: string[];
+    /** Lessons the team's compiled checks covered on this change: left out of the lessons, and said so. */
+    covered?: CoveredLesson[];
 }
 /** 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<{
+        id?: string;
         files?: string[];
         line?: number;
         title: string;
     }>;
+    advisory?: Array<{
+        id?: string;
+        files?: string[];
+        line?: number;
+        title: string;
+    }>;
+    covered?: CoveredLesson[];
 }): {
     hints: string;
     checks: string[];
+    covered: CoveredLesson[];
 };
 /** A lesson as the judge was shown it: its id, and the line it was listed as (the judge answers by that line). */
 export interface ServedLesson {

package/dist/review/reviewer/context.js

@@ -20,7 +20,7 @@ import { reviewedKeys } from '../ledger.js';
 import { textSimilarity } from './consensus.js';
 import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
 import { VerdictStore } from './store.js';
-import { MAX_SETTLED, settledChecks, settledLine, settledSection } from '../settled-checks.js';
+import { coveredSection, MAX_SETTLED, settledChecks, settledLine, settledSection, withoutCovered } from '../settled-checks.js';
 export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.json');
 const MAX_DOCS = 10;
 /** Team standards a judge is shown with the lessons about the changed files. */
@@ -68,7 +68,9 @@ export function dismissedAs(item, dismissals) {
 }
 /** 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: settledChecks(review.findings).map(settledLine) };
+    // A compiled check's findings are notes, and settled too: the judge no longer has the lesson, so it must have them.
+    const compiled = (review.advisory ?? []).filter(f => f.id === 'compiled-lesson');
+    return { hints: review.hints.join('\n'), checks: settledChecks([...review.findings, ...compiled]).map(settledLine), covered: review.covered ?? [] };
 }
 /** The ids of the served lessons the judge said this change repeats; an answer that names no served lesson says nothing. */
 export function lessonsApplied(answers, served) {
@@ -87,13 +89,15 @@ export function buildContext(input) {
         task = undefined;
     }
     // A judge reads the whole pull request: more of what the team taught fits than an agent's one question at the stop.
-    const servedLessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS, JUDGE_FILE_LESSONS, JUDGE_LESSONS_PER_FILE, input.pr).map(l => ({ id: l.id, listed: describeLesson(lessonView(l)) }));
+    const servedLessons = input.lessons === 'off' ? [] : withoutCovered(lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS, JUDGE_FILE_LESSONS, JUDGE_LESSONS_PER_FILE, input.pr), input.covered ?? []).map(l => ({ id: l.id, listed: describeLesson(lessonView(l)) }));
     if (servedLessons.length)
         sections.push(`## Lessons this team taught on earlier reviews, for what this change touches (context: a lesson never blocks on its own; a finding still needs its quote)\n${servedLessons.map(l => `- ${l.listed}`).join('\n')}`);
     // The repository's own rules, always: the reviewer is the boundary, and what the team wrote is the standard it checks.
     const rules = rulesForDiff(input.cwd, input.diff, true, JUDGE_RULES).map((r) => ({ id: r.id, source: r.source, text: r.text, requirement: r.requirement }));
     if (rules.length)
         sections.push(`## Rules this repository wrote for itself that apply to this change (answer every one in rules, by id)\n${rules.map(r => `- [${r.id}] (${r.source}, ${r.requirement ? 'requirement' : 'guidance'}) ${r.text}`).join('\n')}`);
+    if (input.covered?.length)
+        sections.push(coveredSection(input.covered));
     if (input.checks.length)
         sections.push(settledSection(input.checks));
     const rejected = input.lessons === 'off' ? [] : rejectedForDiff(input.cwd, input.diff).map(l => {

package/dist/review/reviewer.d.ts

@@ -5,6 +5,7 @@ import { type PanelItem } from './reviewer/panel.js';
 import { type RunChoice, type Source } from './reviewer/settings.js';
 import { type ReviewRecord } from './reviewer/record.js';
 import { type Accounting, type OpenItem, type PriorPoint } from './reviewer/verdict.js';
+import type { CoveredLesson } from './settled-checks.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays, type Exec, type Progress } from './reviewer/exec.js';
 export { itemLine, type OpenItem } from './reviewer/verdict.js';
 export type ReviewerOutcome = 'passed' | 'findings' | 'unavailable' | 'skipped';
@@ -29,6 +30,8 @@ export interface ReviewerOptions {
     hints?: string;
     /** What Rigour's checks already found on this change: settled, so no judge spends a turn finding it again. */
     checks?: string[];
+    /** Lessons the team's compiled checks covered on this change (review.ts): left out of the judge's lessons, and said so. */
+    covered?: CoveredLesson[];
     /** Where the team's state lives (.rigour: dismissals, reviewed functions) when cwd is a worktree that lacks it. */
     stateRoot?: string;
     /** The branch the commit was pushed from, when reviewing it in a detached worktree (background.ts). */

package/dist/review/reviewer.js

@@ -177,7 +177,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const sincePrevious = previousIsAncestor ? new Set((await git(['diff', '--name-only', `${previous.head}..HEAD`])).split('\n').filter(Boolean)) : new Set();
     const changedFiles = [...fullDiff.matchAll(/^diff --git a\/.* b\/(.*)$/gm)].map(m => m[1]);
     const context = buildContext({
-        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, ...(pr ? { pr: pr.number } : {}), touched: sincePrevious, checks: options.checks ?? [],
+        cwd, stateRoot, dismissals, diff: fullDiff, router: config.gates.deep?.router, lessons: config.gates.deep?.review_lessons, ...(pr ? { pr: pr.number } : {}), touched: sincePrevious, checks: options.checks ?? [], covered: options.covered ?? [],
         previousPanel: previousIsAncestor ? store.readJson(previous.verdict)?.panel?.items : undefined,
         docs: await relatedDocs(cwd, changedFiles, exec),
     });

package/dist/review/settled-checks.d.ts

@@ -1,6 +1,5 @@
 /**
- * What Rigour's checks already found on a change, as a model reviewer is told it: settled, blocking on their own, never
- * to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
+ * What Rigour's checks already found on a change, as a model reviewer is told it: settled, never to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
  * so neither spends a model's turn on what a free check proves.
  */
 /** A check's finding where it sits; `kind` is the check's id. */
@@ -37,3 +36,15 @@ export declare function settledChecks(findings: Array<{
 export declare function settledLine(check: SettledCheck): string;
 /** The prompt section; empty when there is nothing settled. */
 export declare function settledSection(lines: string[]): string;
+/** A lesson a compiled check covered on this change: the check ran on its files, and its findings are settled. */
+export interface CoveredLesson {
+    checkId: string;
+    lessonId: string;
+    message: string;
+}
+/** A model reviewer's lessons without those a compiled check covered on this change: the check said them for free. */
+export declare function withoutCovered<L extends {
+    id: string;
+}>(lessons: L[], covered: CoveredLesson[]): L[];
+/** The prompt section saying which lessons a compiled check covered instead; empty when none did. */
+export declare function coveredSection(covered: CoveredLesson[]): string;

package/dist/review/settled-checks.js

@@ -1,6 +1,5 @@
 /**
- * What Rigour's checks already found on a change, as a model reviewer is told it: settled, blocking on their own, never
- * to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
+ * What Rigour's checks already found on a change, as a model reviewer is told it: settled, never to be reported again. The judge (reviewer/context.ts) and the deep PR review (deep/pr-review.ts) both say it this way,
  * so neither spends a model's turn on what a free check proves.
  */
 /**
@@ -43,5 +42,14 @@ export function settledLine(check) {
 }
 /** The prompt section; empty when there is nothing settled. */
 export function settledSection(lines) {
-    return lines.length ? `## Already found by Rigour's checks: they block on their own, so do not report them again\n${lines.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}` : '';
+    return lines.length ? `## Already found by Rigour's checks on this change: do not report them again\n${lines.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}` : '';
+}
+/** A model reviewer's lessons without those a compiled check covered on this change: the check said them for free. */
+export function withoutCovered(lessons, covered) {
+    const ids = new Set(covered.map(c => c.lessonId));
+    return ids.size ? lessons.filter(l => !ids.has(l.id)) : lessons;
+}
+/** The prompt section saying which lessons a compiled check covered instead; empty when none did. */
+export function coveredSection(covered) {
+    return covered.length ? `## Lessons the team's compiled checks covered on this change (their findings are listed as already found)\n${covered.map(c => `- covered by compiled check ${c.checkId} for lesson ${c.lessonId}: ${c.message}`).join('\n')}` : '';
 }

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

@@ -0,0 +1,62 @@
+import type { Config, Failure } from '../types/index.js';
+import { type ReviewLesson } from './lessons.js';
+import type { CoveredLesson } from '../review/settled-checks.js';
+export interface CompiledCheck {
+    id: string;
+    lessonId: string;
+    /** The files it applies to: the lesson's file, or a glob a person widened it to. */
+    files: string;
+    kind: 'forbid' | 'require';
+    /** The symbol that triggers it. */
+    symbol: string;
+    /** For `require`: the symbol that must be near the trigger. */
+    with?: string;
+    message: string;
+    /** Proposed by `compileLesson`; runs only once `active` (a person approved it); `withdrawn` when taken back. */
+    state: 'proposed' | 'active' | 'withdrawn';
+    /** Who made the latest decision, and when (the full trail is `history`). */
+    by?: string;
+    at: string;
+    /** Every decision on it, oldest first: nothing a later decision overwrites is lost. */
+    history?: Array<{
+        state: 'active' | 'withdrawn';
+        by: string;
+        at: string;
+    }>;
+    /**
+     * The check run over the main branch's history, for the person who approves it: on merged pull requests a review
+     * found the lesson repeating in (it should fire), and on every other merged change to its files (each fire is a
+     * false one, or a catch the review missed). Counts, never a rate below RATE_MIN.
+     */
+    backtest?: {
+        repeating: BacktestShare;
+        other: BacktestShare;
+        commits: number;
+        at: string;
+    };
+}
+/** Fires out of n, with the rate computed here, the one place RATE_MIN applies: null below it. */
+export interface BacktestShare {
+    fired: number;
+    n: number;
+    rate: number | null;
+}
+/**
+ * Proposes a check for every compilable lesson that has none yet, each backtested against the main branch's history
+ * (new proposals only); returns them. A decided check is never re-proposed.
+ */
+export declare function proposeCompiledChecks(cwd: string): CompiledCheck[];
+/** A person's decision on a compiled check: approve it (it runs) or take it back (it stops). Undefined when there is no such check. */
+export declare function decideCompiledCheck(cwd: string, id: string, state: 'active' | 'withdrawn', by: string): CompiledCheck | undefined;
+/** Whether an approved check is suspended, and why: its lesson no longer qualifies. */
+export declare function suspension(check: CompiledCheck, lessons: Map<string, ReviewLesson>): string | undefined;
+export declare function readCompiledChecks(cwd: string): CompiledCheck[];
+/**
+ * The running compiled checks on a change: their findings on its changed lines (notes unless the team blocks), and the
+ * lessons they covered (each check whose files the change touched, whether or not it found anything). A model reviewer
+ * may leave a covered lesson out of its prompt; nothing else.
+ */
+export declare function compiledChecksOn(cwd: string, changedLines: Record<string, Set<number>>, config: Config): {
+    failures: Failure[];
+    covered: CoveredLesson[];
+};

package/dist/review-learning/compiled-lessons.js

@@ -0,0 +1,249 @@
+/**
+ * A verified lesson turned into a check that runs without a model. Only lessons a person confirmed (accepted, a
+ * correction) or that recurred across pull requests qualify, never one an outcome alone promoted. Compilation is a
+ * template, not a model: a lesson compiles only when it names its file and its symbols in backticks and says, in so many
+ * words, what is wrong:
+ *
+ *   forbid   "never `a`", "avoid `a`", "do not use `a`", "use `b` instead of `a`"  →  `a` on a changed line is reported
+ *   require  "always …", "must …", "every …" naming `a` then `b`                     →  `a` on a changed line with no `b`
+ *                                                                                    within REQUIRE_REACH lines is reported
+ *
+ * A compiled check is stored in .rigour/compiled-checks.json (committed and reviewed with the code) and runs only once a
+ * person approved it (`active`). It keeps its lesson's id, never blocks unless the team turns `block` on, and a person
+ * can take it back (`withdrawn`), which hands the lesson back to the model reviewer. Every decision is kept, on the
+ * check and as evidence on its lesson. An approved check whose lesson no longer qualifies (rejected, taken back) is
+ * suspended: it does not run, and the lesson goes back to the model reviewer.
+ */
+import fs from 'fs';
+import path from 'path';
+import micromatch from 'micromatch';
+import { execFileSync } from 'child_process';
+import { lessonState, readLessons, writeLessons } from './lessons.js';
+import { branchBase } from '../gates/logic-drift-git-base.js';
+import { threadReviews } from '../outcomes/run.js';
+import { parseDiff } from '../utils/diff.js';
+const STORE = path.join('.rigour', 'compiled-checks.json');
+/** How far from the trigger line the required symbol may sit for a `require` check. */
+const REQUIRE_REACH = 3;
+/** Fewer than this: a count, never a rate. */
+const RATE_MIN = 10;
+/** Merged changes to a check's files read back, newest first. */
+const BACKTEST_COMMITS = 100;
+/** Each backtest stops here and keeps what it counted. */
+const BACKTEST_DEADLINE_MS = 20_000;
+/** All of one proposal round's backtests stop here; a check not reached is proposed without its counts. */
+const PROPOSE_DEADLINE_MS = 30_000;
+const FORBID = [
+    /\b(?:use|prefer)\s+`([^`]+)`\s+(?:instead of|over|rather than)\s+`([^`]+)`/i, // the second is forbidden
+    // "never forget to call `x`" asks for `x`: a negation followed by one of these is not a ban.
+    /\b(?:never|avoid|don't|do not|must not|should not|no longer)\b(?!\s+(?:forget|remove|skip|miss|omit|drop|leave out|lose|stop)\b)[^.`]*`([^`]+)`/i,
+];
+const REQUIRE = /\b(?:always|must|every|needs? to|has to)\b/i;
+/** Whether a lesson may be compiled: verified by a person, a correction or recurrence, never by an outcome alone. */
+function compilable(lesson) {
+    if (!lesson)
+        return false;
+    const { state, promotedBy } = lessonState(lesson);
+    return state === 'verified' && (promotedBy === 'person' || promotedBy === 'correction' || promotedBy === 'recurrence') && !!lesson.file && lesson.symbols.length > 0;
+}
+/** The check a lesson compiles to, proposed for a person to approve; undefined when no template fits it. */
+function compileLesson(lesson, at = new Date().toISOString()) {
+    if (!compilable(lesson))
+        return undefined;
+    const named = (s) => (s && lesson.symbols.includes(s.replace(/\(\)$/, '')) ? s.replace(/\(\)$/, '') : undefined);
+    const base = { id: `c-${lesson.id}`, lessonId: lesson.id, files: lesson.file, message: lesson.text, state: 'proposed', at };
+    const instead = FORBID[0].exec(lesson.text);
+    const forbidden = instead ? named(instead[2]) : named(FORBID[1].exec(lesson.text)?.[1]);
+    if (forbidden)
+        return { ...base, kind: 'forbid', symbol: forbidden };
+    if (REQUIRE.test(lesson.text)) {
+        const ticked = [...lesson.text.matchAll(/`([^`]+)`/g)].map(m => named(m[1])).filter((s) => !!s);
+        if (ticked.length >= 2 && ticked[0] !== ticked[1])
+            return { ...base, kind: 'require', symbol: ticked[0], with: ticked[1] };
+    }
+    return undefined;
+}
+/**
+ * Proposes a check for every compilable lesson that has none yet, each backtested against the main branch's history
+ * (new proposals only); returns them. A decided check is never re-proposed.
+ */
+export function proposeCompiledChecks(cwd) {
+    const checks = readCompiledChecks(cwd);
+    const known = new Set(checks.map(c => c.lessonId));
+    const proposed = readLessons(cwd).filter(l => !known.has(l.id)).map(l => compileLesson(l)).filter((c) => !!c);
+    if (proposed.length === 0)
+        return [];
+    withBacktests(cwd, proposed); // only the new ones: a decided or earlier proposal keeps the counts it was shown with
+    writeCompiledChecks(cwd, [...checks, ...proposed]);
+    return proposed;
+}
+/** A person's decision on a compiled check: approve it (it runs) or take it back (it stops). Undefined when there is no such check. */
+export function decideCompiledCheck(cwd, id, state, by) {
+    if (!by.trim())
+        throw new Error('a compiled check is decided by a named person: their git email is committed with it');
+    const checks = readCompiledChecks(cwd);
+    const check = checks.find(c => c.id === id);
+    if (!check)
+        return undefined;
+    const lessons = readLessons(cwd);
+    const lesson = lessons.find(l => l.id === check.lessonId);
+    if (state === 'active' && !(lesson && compilable(lesson)))
+        throw new Error(`lesson ${check.lessonId} no longer qualifies (rejected, taken back, or gone): its check cannot run`);
+    const at = new Date().toISOString();
+    check.history = [...(check.history ?? []), { state, by, at }];
+    Object.assign(check, { state, by, at });
+    writeCompiledChecks(cwd, checks);
+    // The lesson keeps the decision too: what its check did is part of its trail.
+    if (lesson) {
+        lesson.evidence.push({ kind: 'compiled', pr: lesson.evidence[0]?.pr ?? 0, comment: `compiled-${check.id}-${at}`, author: by, detail: `${state === 'active' ? 'approved' : 'took back'} compiled check ${check.id}`, at });
+        writeLessons(cwd, lessons);
+    }
+    return check;
+}
+/**
+ * The approved checks that run: an approved check whose lesson no longer qualifies (a person rejected it, evidence
+ * took it back, it is gone) is suspended, and its lesson goes back to the model reviewer.
+ */
+function runningChecks(cwd) {
+    const lessons = new Map(readLessons(cwd).map(l => [l.id, l]));
+    return readCompiledChecks(cwd).filter(c => c.state === 'active' && compilable(lessons.get(c.lessonId)));
+}
+/** Whether an approved check is suspended, and why: its lesson no longer qualifies. */
+export function suspension(check, lessons) {
+    if (check.state !== 'active')
+        return undefined;
+    const lesson = lessons.get(check.lessonId);
+    if (!lesson)
+        return `lesson ${check.lessonId} is gone`;
+    return compilable(lesson) ? undefined : `lesson ${check.lessonId} no longer qualifies (${lessonState(lesson).state}): suspended, the lesson is back with the model reviewer`;
+}
+export function readCompiledChecks(cwd) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(cwd, STORE), 'utf8'));
+        return Array.isArray(data?.checks) ? data.checks : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeCompiledChecks(cwd, checks) {
+    fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, STORE), `${JSON.stringify({ version: 1, checks }, null, 2)}\n`);
+}
+const word = (symbol) => new RegExp(`(^|[^\\w$])${symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^\\w$]|$)`);
+/** Whether a check applies to a file: the file itself, or a glob it was widened to. */
+function covers(check, file) {
+    return /[*?[\]{}]/.test(check.files) ? micromatch.isMatch(file, check.files, { dot: true }) : check.files === file;
+}
+/**
+ * The running compiled checks on a change: their findings on its changed lines (notes unless the team blocks), and the
+ * lessons they covered (each check whose files the change touched, whether or not it found anything). A model reviewer
+ * may leave a covered lesson out of its prompt; nothing else.
+ */
+export function compiledChecksOn(cwd, changedLines, config) {
+    const settings = config.gates.compiled_lessons;
+    if (!settings?.enabled)
+        return { failures: [], covered: [] };
+    const checks = runningChecks(cwd);
+    if (checks.length === 0)
+        return { failures: [], covered: [] };
+    const failures = [];
+    const ran = new Set();
+    for (const [file, lines] of Object.entries(changedLines)) {
+        const applying = checks.filter(c => covers(c, file));
+        if (applying.length === 0)
+            continue;
+        applying.forEach(c => ran.add(c));
+        let text;
+        try {
+            text = fs.readFileSync(path.join(cwd, file), 'utf8').split('\n');
+        }
+        catch {
+            continue;
+        }
+        for (const check of applying) {
+            for (const line of firesOn(check, text, lines)) {
+                failures.push({
+                    id: 'compiled-lesson',
+                    ...(settings.block ? {} : { advisory: true }),
+                    title: check.kind === 'forbid' ? `\`${check.symbol}\`: the team's lesson says not to` : `\`${check.symbol}\` without \`${check.with}\`: the team's lesson says to pair them`,
+                    details: `${check.message} (compiled from lesson ${check.lessonId}; a person approved it)`,
+                    severity: 'medium',
+                    provenance: 'traditional',
+                    files: [file],
+                    line,
+                    hint: `Follow the lesson, or take the compiled check back in Studio if it no longer holds (lesson ${check.lessonId}).`,
+                });
+            }
+        }
+    }
+    return { failures, covered: [...ran].map(c => ({ checkId: c.id, lessonId: c.lessonId, message: c.message })) };
+}
+/** The changed lines a check fires on, in a file's text. */
+function firesOn(check, text, lines) {
+    const trigger = word(check.symbol);
+    return [...lines].sort((a, b) => a - b).filter(line => {
+        if (!trigger.test(text[line - 1] ?? ''))
+            return false;
+        if (check.kind === 'forbid')
+            return true;
+        return !word(check.with).test(text.slice(Math.max(0, line - 1 - REQUIRE_REACH), line + REQUIRE_REACH).join('\n'));
+    });
+}
+/**
+ * Runs a check over the main branch's last BACKTEST_COMMITS changes to its files: per change, whether it fires on the
+ * lines that change added, split by whether a review found the lesson repeating in that pull request. Read-only, no model.
+ */
+function backtestCheck(cwd, check, mainRef, applied) {
+    const git = (args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 10_000 });
+    const spec = /[*?[\]{}]/.test(check.files) ? `:(glob)${check.files}` : check.files;
+    const result = { repeating: { fired: 0, n: 0, rate: null }, other: { fired: 0, n: 0, rate: null }, commits: 0, at: new Date().toISOString() };
+    const deadline = Date.now() + BACKTEST_DEADLINE_MS;
+    let log = '';
+    try {
+        log = git(['log', '--first-parent', '-n', String(BACKTEST_COMMITS), '--format=%H %s', mainRef, '--', spec]);
+    }
+    catch {
+        return withRates(result);
+    }
+    for (const entry of log.split('\n').filter(Boolean)) {
+        if (Date.now() > deadline)
+            break;
+        const [sha, ...subject] = entry.split(' ');
+        const pr = Number(/\(#(\d+)\)\s*$|Merge pull request #(\d+)/.exec(subject.join(' '))?.slice(1).find(Boolean));
+        let fired = false;
+        try {
+            for (const [file, lines] of Object.entries(parseDiff(git(['diff', '-U0', `${sha}^1`, sha, '--', spec])))) {
+                if (firesOn(check, git(['show', `${sha}:${file}`]).split('\n'), lines).length)
+                    fired = true;
+            }
+        }
+        catch {
+            continue; // a root commit or a file the commit removed: nothing to count
+        }
+        const bucket = pr && applied.get(pr)?.has(check.lessonId) ? result.repeating : result.other;
+        bucket.n++;
+        if (fired)
+            bucket.fired++;
+        result.commits++;
+    }
+    return withRates(result);
+}
+function withRates(result) {
+    for (const share of [result.repeating, result.other])
+        share.rate = share.n >= RATE_MIN ? Math.round((share.fired / share.n) * 100) / 100 : null;
+    return result;
+}
+/** Backtests new proposals, all within PROPOSE_DEADLINE_MS: what the person approving each one reads. */
+function withBacktests(cwd, checks) {
+    const mainRef = branchBase(cwd)?.mainRef;
+    if (!mainRef)
+        return;
+    const { applied } = threadReviews(cwd);
+    const deadline = Date.now() + PROPOSE_DEADLINE_MS;
+    for (const check of checks) {
+        if (Date.now() > deadline)
+            break;
+        check.backtest = backtestCheck(cwd, check, mainRef, applied);
+    }
+}

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

@@ -18,7 +18,7 @@ import type { Git, ReviewBody, ReviewComment } from './acted-on.js';
  *             until a person promotes it.
  * A record from before evidence kinds has none: it is a `point`.
  */
-export type EvidenceKind = 'point' | 'outcome' | 'counter' | 'correction' | 'accepted' | 'rejected' | 'norule' | 'followup' | 'lines' | 'dismissed' | 'against' | 'demoted' | 'reclassified';
+export type EvidenceKind = 'point' | 'outcome' | 'counter' | 'correction' | 'accepted' | 'rejected' | 'norule' | 'followup' | 'lines' | 'dismissed' | 'against' | 'demoted' | 'reclassified' | 'compiled';
 export interface LessonEvidence {
     kind?: EvidenceKind;
     pr: number;

package/dist/switches.d.ts

@@ -227,6 +227,10 @@ export declare const SWITCHES: {
                     allow: string[];
                     block: boolean;
                 };
+                compiled_lessons: {
+                    enabled: boolean;
+                    block: boolean;
+                };
                 migration_order: {
                     enabled: boolean;
                     dirs: string[];
@@ -536,6 +540,10 @@ export declare const SWITCHES: {
                     allow: string[];
                     block: boolean;
                 };
+                compiled_lessons: {
+                    enabled: boolean;
+                    block: boolean;
+                };
                 migration_order: {
                     enabled: boolean;
                     dirs: string[];
@@ -845,6 +853,10 @@ export declare const SWITCHES: {
                     allow: string[];
                     block: boolean;
                 };
+                compiled_lessons: {
+                    enabled: boolean;
+                    block: boolean;
+                };
                 migration_order: {
                     enabled: boolean;
                     dirs: string[];

package/dist/telemetry/check-ids.d.ts

@@ -0,0 +1,2 @@
+/** A check id as telemetry may send it: one of Rigour's own, else `custom`. */
+export declare function telemetryCheckId(id: string): string;

package/dist/telemetry/check-ids.js

@@ -0,0 +1,23 @@
+/**
+ * The check ids opt-in telemetry may send: Rigour's own, and nothing else. A team's own check (a `commands:` entry, a
+ * plugin, anything named in config) can carry a product or customer name, so it is sent only as `custom`. The list is
+ * the gate registry's ids, the review's own checks and the hook's: check-ids.test.ts builds the registry and fails
+ * when a gate is missing here.
+ */
+const BUILT_IN = new Set([
+    // Gates (gates/runner.ts registers them)
+    'agent-team', 'ast-analysis', 'checkpoint', 'content-check', 'context-drift', 'context-window-artifacts', 'coverage-guard', 'deep-analysis',
+    'dependency-guardian', 'deprecated-apis', 'deprecated-dependencies', 'duplication-drift', 'environment-alignment', 'file-guard', 'file-size',
+    'frontend-secret-exposure', 'hallucinated-imports', 'inconsistent-error-handling', 'logic-drift', 'phantom-apis', 'promise-safety',
+    'retry_loop_breaker', 'security-patterns', 'semantic-bugs', 'side-effect-analysis', 'structure-check', 'style-drift', 'test-quality', 'unindexed-reads',
+    // The review's own checks (review/review.ts) and their typed checks
+    'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'quadratic-copy',
+    'migration-order', 'diff-tests', 'compiled-lesson', 'goal-scope', 'goal-done-when', 'duplicate-null-filter', 'nullable-filtered-column',
+    'optional-always-supplied', 'write-only-property', 'typed-checks-unavailable',
+    // The per-edit hook's (hooks/checker.ts)
+    'agent-scope', 'governance', 'governance-dlp', 'governance-skills',
+]);
+/** A check id as telemetry may send it: one of Rigour's own, else `custom`. */
+export function telemetryCheckId(id) {
+    return BUILT_IN.has(id) ? id : 'custom';
+}

package/dist/telemetry/learning-usage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What the learning loop did in a repository, for opt-in telemetry: read from the two places that already say it, the
+ * switches' resolver and the outcome numbers (outcomes/metrics.ts), never counted again here. Enums and counts only; a
+ * rate only where outcomeMetrics gives one (ten or more records), else none.
+ */
+import type { Config } from '../types/index.js';
+export declare function learningUsage(cwd: string, config: Config): Record<string, unknown>;

package/dist/telemetry/learning-usage.js

@@ -0,0 +1,33 @@
+import { resolveSwitch, SWITCHES } from '../switches.js';
+import { localOutcomeMetrics } from '../outcomes/run.js';
+export function learningUsage(cwd, config) {
+    const usage = {};
+    for (const name of Object.keys(SWITCHES)) {
+        const resolved = resolveSwitch(name, config);
+        usage[`switch_${name}`] = resolved.required ? 'required' : resolved.enabled ? 'on' : 'off';
+        usage[`switch_${name}_set_by`] = resolved.source; // team (rigour.yml), user (personal settings), env or flag
+    }
+    const metrics = localOutcomeMetrics(cwd);
+    if (!metrics)
+        return usage;
+    const share = (prefix, s) => {
+        usage[`${prefix}_count`] = s.count;
+        usage[`${prefix}_of`] = s.of;
+        if (s.rate !== null)
+            usage[`${prefix}_rate`] = s.rate;
+    };
+    usage.outcomes_merged = metrics.records.merged;
+    usage.outcomes_settled = metrics.records.settled;
+    share('outcomes_ci_regressed', metrics.settled.ciRegressed);
+    share('outcomes_reverted', metrics.settled.reverted);
+    share('outcomes_fixed_later', metrics.settled.fixedLater);
+    usage.outcomes_reviewed_prs = metrics.settled.reviewed.prs;
+    share('outcomes_reviewed_fixed_later', metrics.settled.reviewed.fixedLater);
+    usage.outcomes_not_reviewed_prs = metrics.settled.notReviewed.prs;
+    share('outcomes_not_reviewed_fixed_later', metrics.settled.notReviewed.fixedLater);
+    usage.lessons_awaiting_decision = metrics.lessons.awaitingDecision;
+    usage.lessons_promoted_from_evidence = metrics.lessons.promotedFromEvidence;
+    usage.lessons_dismissed = metrics.lessons.dismissed;
+    usage.lessons_taken_back = metrics.lessons.takenBack;
+    return usage;
+}

package/dist/telemetry/telemetry.d.ts

@@ -4,6 +4,8 @@ export interface TelemetryState {
     /** undefined until the person has been asked. */
     enabled?: boolean;
     installId: string;
+    /** When the person was first asked (ms): how old the install is, bucketed. Absent in files written before it was kept. */
+    firstAt?: number;
 }
 export interface TelemetryDeps {
     env?: Env;
@@ -11,7 +13,13 @@ export interface TelemetryDeps {
     fetch?: Fetch;
     version?: string;
     now?: number;
+    /** The agent a hook ran for, when the hook knows (its own tool name): wins over the environment. */
+    agent?: string;
+    /** More of the daily event, read only when it is sent (learning-usage.ts): the learning loop of the repository the command ran in. */
+    daily?: () => Record<string, unknown>;
 }
+/** The agent hosts telemetry names, and nothing else: anything unknown is `other`, no agent is `none`. */
+export type AgentHost = 'claude-code' | 'cursor' | 'cline' | 'windsurf' | 'codex' | 'other' | 'none';
 export declare function telemetryToken(env?: Env): string;
 export declare function readTelemetryState(home?: string): TelemetryState;
 export declare function setTelemetryEnabled(enabled: boolean, home?: string): TelemetryState;

package/dist/telemetry/telemetry.js

@@ -22,6 +22,44 @@ import { MIXPANEL_TOKEN } from './token.js';
 const ENDPOINT = 'https://api.mixpanel.com/track?ip=0';
 const TIMEOUT_MS = 2000;
 const DAY_MS = 24 * 60 * 60 * 1000;
+const HOOK_TOOLS = { claude: 'claude-code', 'claude-code': 'claude-code', cursor: 'cursor', cline: 'cline', windsurf: 'windsurf', codex: 'codex' };
+/**
+ * Which agent Rigour ran under: the hook's own tool name when it is one of the known; else the variable each sets in
+ * the processes it starts (CLAUDECODE=1 for Claude Code, CURSOR_TRACE_ID for Cursor's terminal, CODEX_SANDBOX for
+ * Codex); else `other` for a hint naming an agent not on the list, `none` without one. Cline and Windsurf are known
+ * only from their hooks.
+ */
+function agentHost(env, hint) {
+    const known = hint ? HOOK_TOOLS[hint.toLowerCase()] : undefined;
+    if (known)
+        return known;
+    if (env.CLAUDECODE === '1')
+        return 'claude-code';
+    if (env.CURSOR_TRACE_ID)
+        return 'cursor';
+    if (env.CODEX_SANDBOX)
+        return 'codex';
+    return hint ? 'other' : 'none';
+}
+const WEEK_MS = 7 * DAY_MS;
+/** When telemetry.json was first written, for a file from before `firstAt` was kept: its creation time, else its last write. */
+function firstWritten(home) {
+    try {
+        const stat = fs.statSync(file(home, 'telemetry.json'));
+        return stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How long ago the person was first asked, bucketed: 0, 1, 2-4, 5-12 or 13+ weeks; undefined before they were. */
+function installAgeWeeks(home, now) {
+    const first = readTelemetryState(home).firstAt ?? firstWritten(home);
+    if (first === undefined)
+        return undefined;
+    const weeks = Math.floor(Math.max(0, now - first) / WEEK_MS);
+    return weeks === 0 ? '0' : weeks === 1 ? '1' : weeks <= 4 ? '2-4' : weeks <= 12 ? '5-12' : '13+';
+}
 export function telemetryToken(env = process.env) {
     return env.RIGOUR_MIXPANEL_TOKEN?.trim() || MIXPANEL_TOKEN;
 }
@@ -32,7 +70,7 @@ export function readTelemetryState(home = rigourHome()) {
     try {
         const parsed = JSON.parse(fs.readFileSync(file(home, 'telemetry.json'), 'utf8'));
         if (typeof parsed?.installId === 'string')
-            return { installId: parsed.installId, enabled: typeof parsed.enabled === 'boolean' ? parsed.enabled : undefined };
+            return { installId: parsed.installId, enabled: typeof parsed.enabled === 'boolean' ? parsed.enabled : undefined, ...(typeof parsed.firstAt === 'number' ? { firstAt: parsed.firstAt } : {}) };
     }
     catch {
         // Not asked yet.
@@ -40,7 +78,8 @@ export function readTelemetryState(home = rigourHome()) {
     return { installId: crypto.randomUUID() };
 }
 export function setTelemetryEnabled(enabled, home = rigourHome()) {
-    const state = { ...readTelemetryState(home), enabled };
+    const current = readTelemetryState(home);
+    const state = { ...current, enabled, firstAt: current.firstAt ?? firstWritten(home) ?? Date.now() };
     writeJson(file(home, 'telemetry.json'), state);
     return state;
 }
@@ -87,6 +126,8 @@ export async function trackUsage(event, properties, deps = {}) {
                 os: process.platform,
                 node_major: Number(process.versions.node.split('.')[0]),
                 ci: isCi(env),
+                agent_host: agentHost(env, deps.agent),
+                install_age_weeks: installAgeWeeks(deps.home ?? rigourHome(), deps.now ?? Date.now()),
                 ...properties,
             },
         }];
@@ -110,6 +151,9 @@ export function countUsage(name, by = 1, deps = {}) {
         const home = deps.home ?? rigourHome();
         const counters = readCounters(home, deps.now ?? Date.now());
         counters.counts[name] = (counters.counts[name] ?? 0) + by;
+        // What each agent drives: one count per agent host, beside the thing counted.
+        const host = `agent_host:${agentHost(deps.env ?? process.env, deps.agent)}`;
+        counters.counts[host] = (counters.counts[host] ?? 0) + by;
         writeJson(file(home, 'telemetry-counters.json'), counters);
     }
     catch {
@@ -123,10 +167,20 @@ export async function flushDailyUsage(deps = {}) {
     const home = deps.home ?? rigourHome();
     const now = deps.now ?? Date.now();
     const counters = readCounters(home, now);
-    if (now - counters.since < DAY_MS || Object.keys(counters.counts).length === 0)
+    // The day starts the first time anything could be sent, so a day with no counts still ends.
+    if (deps.daily && !fs.existsSync(file(home, 'telemetry-counters.json')))
+        writeJson(file(home, 'telemetry-counters.json'), counters);
+    if (now - counters.since < DAY_MS || (Object.keys(counters.counts).length === 0 && !deps.daily))
         return false;
     writeJson(file(home, 'telemetry-counters.json'), { since: now, counts: {} });
-    await trackUsage('daily_usage', { ...counters.counts }, deps);
+    let daily = {};
+    try {
+        daily = deps.daily?.() ?? {};
+    }
+    catch {
+        // What the learning loop did is extra: the day's counts go out without it.
+    }
+    await trackUsage('daily_usage', { ...counters.counts, ...daily }, deps);
     return true;
 }
 function readCounters(home, now) {

package/dist/templates/universal-config.js

@@ -218,6 +218,10 @@ export const UNIVERSAL_CONFIG = {
             allow: [],
             block: false,
         },
+        compiled_lessons: {
+            enabled: true,
+            block: false,
+        },
         query_patterns: {
             enabled: true,
         },

package/dist/types/index.d.ts

@@ -503,6 +503,17 @@ export declare const GatesSchema: z.ZodObject<{
         allow?: string[] | undefined;
         block?: boolean | undefined;
     }>>>;
+    /** Verified lessons a person compiled into checks (review-learning/compiled-lessons.ts): notes unless `block`. */
+    compiled_lessons: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        block: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        block: boolean;
+    }, {
+        enabled?: boolean | undefined;
+        block?: boolean | undefined;
+    }>>>;
     migration_order: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         dirs: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
@@ -897,6 +908,10 @@ export declare const GatesSchema: z.ZodObject<{
         allow: string[];
         block: boolean;
     };
+    compiled_lessons: {
+        enabled: boolean;
+        block: boolean;
+    };
     migration_order: {
         enabled: boolean;
         dirs: string[];
@@ -1136,6 +1151,10 @@ export declare const GatesSchema: z.ZodObject<{
         allow?: string[] | undefined;
         block?: boolean | undefined;
     } | undefined;
+    compiled_lessons?: {
+        enabled?: boolean | undefined;
+        block?: boolean | undefined;
+    } | undefined;
     migration_order?: {
         enabled?: boolean | undefined;
         dirs?: string[] | undefined;
@@ -1717,6 +1736,17 @@ export declare const ConfigSchema: z.ZodObject<{
             allow?: string[] | undefined;
             block?: boolean | undefined;
         }>>>;
+        /** Verified lessons a person compiled into checks (review-learning/compiled-lessons.ts): notes unless `block`. */
+        compiled_lessons: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            block: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            block: boolean;
+        }, {
+            enabled?: boolean | undefined;
+            block?: boolean | undefined;
+        }>>>;
         migration_order: z.ZodDefault<z.ZodOptional<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
             dirs: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
@@ -2111,6 +2141,10 @@ export declare const ConfigSchema: z.ZodObject<{
             allow: string[];
             block: boolean;
         };
+        compiled_lessons: {
+            enabled: boolean;
+            block: boolean;
+        };
         migration_order: {
             enabled: boolean;
             dirs: string[];
@@ -2350,6 +2384,10 @@ export declare const ConfigSchema: z.ZodObject<{
             allow?: string[] | undefined;
             block?: boolean | undefined;
         } | undefined;
+        compiled_lessons?: {
+            enabled?: boolean | undefined;
+            block?: boolean | undefined;
+        } | undefined;
         migration_order?: {
             enabled?: boolean | undefined;
             dirs?: string[] | undefined;
@@ -2895,6 +2933,10 @@ export declare const ConfigSchema: z.ZodObject<{
             allow: string[];
             block: boolean;
         };
+        compiled_lessons: {
+            enabled: boolean;
+            block: boolean;
+        };
         migration_order: {
             enabled: boolean;
             dirs: string[];
@@ -3200,6 +3242,10 @@ export declare const ConfigSchema: z.ZodObject<{
             allow?: string[] | undefined;
             block?: boolean | undefined;
         } | undefined;
+        compiled_lessons?: {
+            enabled?: boolean | undefined;
+            block?: boolean | undefined;
+        } | undefined;
         migration_order?: {
             enabled?: boolean | undefined;
             dirs?: string[] | undefined;
@@ -3784,10 +3830,17 @@ export interface DeepOptions {
     independent?: boolean;
     /** The change's unified diff (from reviewChange): a cloud agentic review reads the PR as a whole. */
     diff?: string;
-    /** What Rigour's checks already found on the change's lines (the runner fills it): settled, never reported again. */
+    /** What Rigour's checks already found on the change's lines (the review and the runner fill it): settled, never reported again. */
     settled?: Array<{
         file: string;
         line?: number;
         title: string;
+        kind?: string;
+    }>;
+    /** The lessons the team's compiled checks covered on this change: the deep review is told so instead of the lesson. */
+    covered?: Array<{
+        checkId: string;
+        lessonId: string;
+        message: string;
     }>;
 }

package/dist/types/index.js

@@ -282,6 +282,11 @@ export const GatesSchema = z.object({
         // Block on them. Off by default, like unused_exports.block: a team whose reviewers block on dead files turns it on.
         block: z.boolean().optional().default(false),
     }).optional().default({}),
+    /** Verified lessons a person compiled into checks (review-learning/compiled-lessons.ts): notes unless `block`. */
+    compiled_lessons: z.object({
+        enabled: z.boolean().optional().default(true),
+        block: z.boolean().optional().default(false),
+    }).optional().default({}),
     migration_order: z.object({
         enabled: z.boolean().optional().default(false),
         dirs: z.array(z.string()).optional().default(['**/supabase/migrations']),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.10.1-rc.1",
+  "version": "6.11.0-rc.1",
   "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.10.1-rc.1",
-    "@rigour-labs/brain-darwin-x64": "6.10.1-rc.1",
-    "@rigour-labs/brain-linux-arm64": "6.10.1-rc.1",
-    "@rigour-labs/brain-linux-x64": "6.10.1-rc.1",
-    "@rigour-labs/brain-win-x64": "6.10.1-rc.1"
+    "@rigour-labs/brain-darwin-x64": "6.11.0-rc.1",
+    "@rigour-labs/brain-linux-arm64": "6.11.0-rc.1",
+    "@rigour-labs/brain-linux-x64": "6.11.0-rc.1",
+    "@rigour-labs/brain-darwin-arm64": "6.11.0-rc.1",
+    "@rigour-labs/brain-win-x64": "6.11.0-rc.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",