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

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[];
@@ -297,6 +301,9 @@ export declare const SWITCHES: {
                     judges: 2 | 3;
                     escalate: "always" | "risk";
                     cross_models: Record<string, string>;
+                    tiers: {
+                        cheap: Record<string, string>;
+                    };
                     reasoning: Record<string, "high" | "medium" | "low">;
                     judge_env: Record<string, {
                         unset: string[];
@@ -536,6 +543,10 @@ export declare const SWITCHES: {
                     allow: string[];
                     block: boolean;
                 };
+                compiled_lessons: {
+                    enabled: boolean;
+                    block: boolean;
+                };
                 migration_order: {
                     enabled: boolean;
                     dirs: string[];
@@ -606,6 +617,9 @@ export declare const SWITCHES: {
                     judges: 2 | 3;
                     escalate: "always" | "risk";
                     cross_models: Record<string, string>;
+                    tiers: {
+                        cheap: Record<string, string>;
+                    };
                     reasoning: Record<string, "high" | "medium" | "low">;
                     judge_env: Record<string, {
                         unset: string[];
@@ -845,6 +859,10 @@ export declare const SWITCHES: {
                     allow: string[];
                     block: boolean;
                 };
+                compiled_lessons: {
+                    enabled: boolean;
+                    block: boolean;
+                };
                 migration_order: {
                     enabled: boolean;
                     dirs: string[];
@@ -915,6 +933,9 @@ export declare const SWITCHES: {
                     judges: 2 | 3;
                     escalate: "always" | "risk";
                     cross_models: Record<string, string>;
+                    tiers: {
+                        cheap: Record<string, string>;
+                    };
                     reasoning: Record<string, "high" | "medium" | "low">;
                     judge_env: Record<string, {
                         unset: 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,
         },
@@ -301,6 +305,7 @@ export const UNIVERSAL_CONFIG = {
             judges: 2,
             escalate: 'always',
             cross_models: {},
+            tiers: { cheap: {} },
             judge_env: {},
             reasoning: {},
         },