@rigour-labs/core 6.7.1 → 6.7.4

package/dist/review-learning/human-edits.d.ts

@@ -0,0 +1,7 @@
+/** Each file as the agent just left it (repository-relative paths). */
+export declare function recordAgentWrites(cwd: string, files: string[]): void;
+/**
+ * The files a person changed since the agent last wrote them, stored as candidate lessons with correction
+ * evidence (the rule writer turns each into the rule behind it, or finds none). Returns how many were taken.
+ */
+export declare function captureHumanEdits(cwd: string, by?: string): number;

package/dist/review-learning/human-edits.js

@@ -0,0 +1,99 @@
+/**
+ * A person editing what an agent wrote is the strongest lesson there is: they corrected the work
+ * toward what the team wants. The after-edit hook records each file as the agent left it
+ * (recordAgentWrites); at the stop and the push, a recorded file that now reads differently was
+ * changed by someone else (captureHumanEdits), and that change becomes a candidate lesson with
+ * correction evidence. A change that came from git (a checkout, a pull) or only moved whitespace
+ * is not a correction. Each edit is taken once. Everything stays in the repository's .rigour/.
+ */
+import crypto from 'crypto';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { compactDiff } from '../review/stories.js';
+import { mergeLessons, readLessons, writeLessons } from './lessons.js';
+const DIR = path.join('.rigour', 'agent-writes');
+const MAX_FILE_BYTES = 200_000;
+/** Lines of the change kept as the lesson's words. */
+const MAX_DIFF_LINES = 12;
+const recordPath = (cwd, file) => path.join(cwd, DIR, `${crypto.createHash('sha256').update(file).digest('hex').slice(0, 16)}.json`);
+const squash = (text) => text.replace(/\s+/g, '');
+function headOf(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function atHead(cwd, file) {
+    try {
+        return execFileSync('git', ['show', `HEAD:${file}`], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 4 * MAX_FILE_BYTES });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each file as the agent just left it (repository-relative paths). */
+export function recordAgentWrites(cwd, files) {
+    const head = headOf(cwd);
+    for (const file of files) {
+        try {
+            const content = fs.readFileSync(path.join(cwd, file), 'utf8');
+            if (content.length > MAX_FILE_BYTES)
+                continue;
+            fs.mkdirSync(path.join(cwd, DIR), { recursive: true });
+            fs.writeFileSync(recordPath(cwd, file), JSON.stringify({ file, content, ...(head ? { head } : {}), at: new Date().toISOString() }));
+        }
+        catch {
+            // a file the agent deleted or cannot be read: nothing to compare later
+        }
+    }
+}
+/**
+ * The files a person changed since the agent last wrote them, stored as candidate lessons with correction
+ * evidence (the rule writer turns each into the rule behind it, or finds none). Returns how many were taken.
+ */
+export function captureHumanEdits(cwd, by = 'a person') {
+    let entries = [];
+    try {
+        entries = fs.readdirSync(path.join(cwd, DIR));
+    }
+    catch {
+        return 0;
+    }
+    const at = new Date().toISOString();
+    const lessons = [];
+    const head = headOf(cwd);
+    for (const entry of entries) {
+        const record = path.join(cwd, DIR, entry);
+        let write;
+        let now;
+        try {
+            write = JSON.parse(fs.readFileSync(record, 'utf8'));
+            now = fs.readFileSync(path.join(cwd, write.file), 'utf8');
+        }
+        catch {
+            fs.rmSync(record, { force: true });
+            continue;
+        }
+        if (now === write.content)
+            continue;
+        fs.rmSync(record, { force: true }); // taken once, whatever it was
+        if (squash(now) === squash(write.content))
+            continue; // whitespace only
+        if (head && head !== write.head && atHead(cwd, write.file) === now)
+            continue; // came from git: a checkout, a pull, a merge
+        const diff = compactDiff(write.content, now).slice(0, MAX_DIFF_LINES).join('\n');
+        const text = `In ${write.file}, a person changed what the agent wrote:\n${diff}`;
+        lessons.push({
+            id: crypto.createHash('sha256').update(`${write.file}\u0000${diff}`).digest('hex').slice(0, 12),
+            text, file: write.file, symbols: [], state: 'candidate',
+            evidence: [{ kind: 'correction', pr: 0, comment: `edit-${crypto.createHash('sha256').update(`${write.file}${write.at}`).digest('hex').slice(0, 12)}`, author: by, text, detail: `edited after the agent's write of ${write.at}`, at }],
+            createdAt: at, updatedAt: at,
+        });
+    }
+    if (lessons.length)
+        writeLessons(cwd, mergeLessons(readLessons(cwd), lessons).lessons);
+    return lessons.length;
+}

package/dist/review-learning/human-edits.test.d.ts

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

package/dist/review-learning/human-edits.test.js

@@ -0,0 +1,47 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { captureHumanEdits, recordAgentWrites } from './human-edits.js';
+import { readLessons } from './lessons.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const write = (body) => fs.writeFileSync(path.join(repo, 'src/job.ts'), body);
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'human-edits-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    fs.mkdirSync(path.join(repo, 'src'));
+    write('export function job(rows) {\n  return rows.map(r => r.id);\n}\n');
+    git('add', '-A');
+    git('commit', '-qm', 'base');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('a person editing what the agent wrote', () => {
+    it('becomes a lesson with correction evidence, taken once', () => {
+        write('export function job(rows) {\n  return rows.slice(0, 10000).map(r => r.id);\n}\n'); // the agent's write
+        recordAgentWrites(repo, ['src/job.ts']);
+        write('export function job(rows, after) {\n  return rows.filter(r => r.id > after).slice(0, 500).map(r => r.id);\n}\n'); // the person's fix
+        expect(captureHumanEdits(repo, 'lead@acme')).toBe(1);
+        const [lesson] = readLessons(repo);
+        expect(lesson).toMatchObject({ file: 'src/job.ts', state: 'verified', promotedBy: 'correction' });
+        expect(lesson.text).toContain('a person changed what the agent wrote');
+        expect(lesson.text).toContain('+  return rows.filter(r => r.id > after).slice(0, 500).map(r => r.id);');
+        expect(lesson.evidence[0]).toMatchObject({ kind: 'correction', author: 'lead@acme' });
+        expect(captureHumanEdits(repo, 'lead@acme')).toBe(0); // taken once
+    });
+    it('is not a correction when only whitespace moved, or the change came from git', () => {
+        recordAgentWrites(repo, ['src/job.ts']);
+        write('export function job(rows) {\n    return rows.map(r => r.id);\n}\n'); // a formatter
+        expect(captureHumanEdits(repo)).toBe(0);
+        recordAgentWrites(repo, ['src/job.ts']);
+        git('checkout', '-q', '-b', 'other');
+        write('export const job = (rows) => rows.map(r => r.id);\n');
+        git('commit', '-qam', 'someone else\'s branch');
+        expect(captureHumanEdits(repo)).toBe(0); // a checkout brought it, not a person correcting the agent
+        expect(readLessons(repo)).toEqual([]);
+    });
+});

package/dist/review-learning/learn-from-reviews.d.ts

@@ -1,9 +1,17 @@
 /**
- * `rigour learn --from-reviews`: turn a repository's acted-on review comments
- * into review lessons. Reads GitHub (merged PRs and their review comments) and
- * the local clone; writes only .rigour/review-lessons.json.
+ * `rigour learn-reviews`: turn a repository's review points into lessons, on evidence. Reads GitHub
+ * (merged PRs, their review comments and review bodies) and the local clone; writes only
+ * .rigour/review-lessons.json (and, with rules, the audit log beside it).
+ *
+ * Every point is a candidate, whoever wrote it: a person, an AI posting under a person's login, a
+ * review bot. Who wrote it, and whether the pull request changed those lines, are recorded and never
+ * decide anything: agents apply review comments on their own, and people paste AI text. Evidence
+ * decides (lessons.ts lessonState): what later happened to the lines (outcomes.ts), a person's
+ * decision, or the same point recurring across pull requests by different authors. The pull
+ * request's author commenting on their own pull request is not a review point.
  */
 import { type Git } from './acted-on.js';
+import { type RuleWriter } from './rules-from-reviews.js';
 type Fetch = (url: string, init?: any) => Promise<{
     ok: boolean;
     status: number;
@@ -15,9 +23,20 @@ export interface LearnFromReviewsOptions {
     repo: string;
     /** Only PRs merged on or after this ISO date. */
     since?: string;
-    /** Only PRs merged before this ISO date (a time split for measuring). */
+    /** Only PRs merged before this ISO date (a time split for measuring); with `pr`, only reviews posted before it. */
     until?: string;
+    /**
+     * Learn from this one pull request, open or merged: its reviews up to `until`, acted on when files
+     * changed after a review by its head as of `until`. A long-running pull request teaches as it goes.
+     */
+    pr?: number;
     limit?: number;
+    /** The main branch, for outcome evidence (what later happened to the lines); none is gathered without it. */
+    mainRef?: string;
+    /** How long a point's unchanged lines must ship before that counts against it. */
+    windowDays?: number;
+    /** Rewrite each newly promoted lesson as the rule behind it, or drop it as no rule (rules-from-reviews.ts); off: the words as they are. */
+    writeRules?: RuleWriter;
     apiUrl?: string;
     fetch?: Fetch;
     git?: Git;
@@ -26,6 +45,20 @@ export interface LearnFromReviewsResult {
     prs: number;
     comments: number;
     actedOn: number;
+    /** Review bodies read (each point in one is a candidate). */
+    reviewBodies: number;
+    /** Candidate points read this run, by who wrote them. */
+    candidates: {
+        person: number;
+        bot: number;
+    };
+    /** Lessons now promoted, by the evidence that promoted them; anti-lessons; candidates held back by counter-evidence. */
+    promoted: Record<'outcome' | 'correction' | 'person' | 'recurrence' | 'legacy', number>;
+    rejected: number;
+    heldBack: number;
+    /** With writeRules: points rewritten as rules, and points the model called no rule (dropped). */
+    rules?: number;
+    notRules?: number;
     added: number;
     verified: number;
     total: number;

package/dist/review-learning/learn-from-reviews.js

@@ -1,28 +1,89 @@
 /**
- * `rigour learn --from-reviews`: turn a repository's acted-on review comments
- * into review lessons. Reads GitHub (merged PRs and their review comments) and
- * the local clone; writes only .rigour/review-lessons.json.
+ * `rigour learn-reviews`: turn a repository's review points into lessons, on evidence. Reads GitHub
+ * (merged PRs, their review comments and review bodies) and the local clone; writes only
+ * .rigour/review-lessons.json (and, with rules, the audit log beside it).
+ *
+ * Every point is a candidate, whoever wrote it: a person, an AI posting under a person's login, a
+ * review bot. Who wrote it, and whether the pull request changed those lines, are recorded and never
+ * decide anything: agents apply review comments on their own, and people paste AI text. Evidence
+ * decides (lessons.ts lessonState): what later happened to the lines (outcomes.ts), a person's
+ * decision, or the same point recurring across pull requests by different authors. The pull
+ * request's author commenting on their own pull request is not a review point.
  */
-import { actedOn, gitIn } from './acted-on.js';
-import { lessonFromComment, mergeLessons, readLessons, writeLessons } from './lessons.js';
+import { changedSince, gitIn, withActedOn } from './acted-on.js';
+import { outcomeFor, revertOf } from './outcomes.js';
+import fs from 'fs';
+import path from 'path';
+import { lessonFromComment, lessonsFromReview, lessonsPath, lessonState, mergeLessons, readLessons, writeLessons } from './lessons.js';
+import { rulesFromReviews } from './rules-from-reviews.js';
 export async function learnFromReviews(cwd, options) {
     const git = options.git ?? gitIn(cwd);
     const prs = await mergedPrs(options);
     const lessons = [];
     let comments = 0;
     let acted = 0;
+    let bodies = 0;
     for (const pr of prs) {
         comments += pr.comments.length;
-        for (const comment of actedOn(git, pr)) {
-            acted++;
+        for (const comment of withActedOn(git, pr)) {
+            if (comment.actedOn)
+                acted++;
             const lesson = lessonFromComment(git, comment);
             if (lesson)
                 lessons.push(lesson);
         }
+        for (const review of pr.reviews) {
+            bodies++;
+            lessons.push(...lessonsFromReview(review, changedSince(git, review.commit, pr.mergeSha)));
+        }
+    }
+    const known = new Set(readLessons(cwd).flatMap(l => l.evidence.map(e => e.comment)));
+    const points = lessons.flatMap(l => l.evidence).filter(e => e.kind === 'point' && !known.has(e.comment));
+    const fresh = lessons.filter(l => !l.evidence.every(e => known.has(e.comment)));
+    const merged = mergeLessons(readLessons(cwd), fresh);
+    // Outcomes accrue after the merge: every candidate whose pull request was read this run is checked again.
+    if (options.mainRef) {
+        const byNumber = new Map(prs.filter(pr => pr.mergedAt).map(pr => [pr.number, pr]));
+        const reverts = new Map([...byNumber.values()].map(pr => [pr.number, revertOf(git, pr, { mainRef: options.mainRef, until: options.until })]));
+        for (const lesson of merged.lessons) {
+            if (lesson.state !== 'candidate' || lesson.evidence.some(e => e.kind === 'outcome' || e.kind === 'counter'))
+                continue;
+            for (const point of lesson.evidence.filter(e => (e.kind ?? 'point') === 'point')) {
+                const pr = byNumber.get(point.pr);
+                if (!pr)
+                    continue;
+                const found = (point.actedOn === false ? reverts.get(pr.number) : undefined) ?? outcomeFor(git, lesson, pr, { mainRef: options.mainRef, until: options.until, windowDays: options.windowDays });
+                if (found) {
+                    lesson.evidence.push(found);
+                    break;
+                }
+            }
+        }
+        for (const lesson of merged.lessons)
+            Object.assign(lesson, lessonState(lesson));
+    }
+    // Rules are written for what evidence promoted, once: the model is paid only for lessons that will be served.
+    let written;
+    const unwritten = merged.lessons.filter(l => l.state === 'verified' && !l.evidence.some(e => e.said));
+    if (options.writeRules && unwritten.length) {
+        written = await rulesFromReviews(unwritten, options.writeRules);
+        auditRules(cwd, unwritten, written.lessons);
+        const replaced = new Set(unwritten.map(l => l.id));
+        merged.lessons = [...merged.lessons.filter(l => !replaced.has(l.id)), ...written.lessons.map(l => ({ ...l, ...lessonState(l) }))];
     }
-    const merged = mergeLessons(readLessons(cwd), lessons);
     writeLessons(cwd, merged.lessons);
-    return { prs: prs.length, comments, actedOn: acted, added: merged.added, verified: merged.verified, total: merged.lessons.length };
+    const promoted = { outcome: 0, correction: 0, person: 0, recurrence: 0, legacy: 0 };
+    for (const l of merged.lessons)
+        if (l.state === 'verified' && l.promotedBy)
+            promoted[l.promotedBy]++;
+    return {
+        prs: prs.length, comments, actedOn: acted, reviewBodies: bodies,
+        candidates: { person: points.filter(e => e.source !== 'bot').length, bot: points.filter(e => e.source === 'bot').length },
+        promoted, rejected: merged.lessons.filter(l => l.state === 'rejected').length,
+        heldBack: merged.lessons.filter(l => l.state === 'candidate' && l.evidence.some(e => e.kind === 'counter')).length,
+        ...(written ? { rules: written.rules, notRules: written.dropped } : {}),
+        added: merged.added, verified: merged.lessons.filter(l => l.state === 'verified').length, total: merged.lessons.length,
+    };
 }
 async function mergedPrs(options) {
     const fetchImpl = options.fetch ?? fetch;
@@ -33,6 +94,8 @@ async function mergedPrs(options) {
             throw new Error(`GitHub ${url.replace(base, '')}: HTTP ${response.status}`);
         return response.json();
     };
+    if (options.pr !== undefined)
+        return [await onePr(options, base, get)];
     const limit = options.limit ?? 100;
     const prs = [];
     for (let page = 1; prs.length < limit && page <= 20; page++) {
@@ -46,20 +109,73 @@ async function mergedPrs(options) {
                 continue;
             if (options.until && pr.merged_at >= options.until)
                 continue;
+            const author = String(pr.user?.login ?? '');
+            const reviewer = (user) => !!user?.login && user.login !== author;
             const raw = await get(`${base}/pulls/${pr.number}/comments?per_page=100`);
-            prs.push({ number: pr.number, mergeSha: pr.merge_commit_sha, mergedAt: pr.merged_at, comments: raw.flatMap(c => toComment(pr.number, c)) });
+            const reviews = await get(`${base}/pulls/${pr.number}/reviews?per_page=100`);
+            prs.push({
+                number: pr.number, mergeSha: pr.merge_commit_sha, mergedAt: pr.merged_at,
+                comments: raw.filter(c => reviewer(c.user)).flatMap(c => toComment(pr.number, c, author)),
+                reviews: reviews.filter(r => reviewer(r.user) && r.commit_id && String(r.body ?? '').trim()).map((r) => ({ id: String(r.id), prNumber: pr.number, commit: r.commit_id, body: String(r.body), author: String(r.user.login), source: sourceOf(r.user), prAuthor: author })),
+            });
             if (prs.length >= limit)
                 break;
         }
     }
     return prs;
 }
+/** One pull request as of `until`: its head then, and the reviews by people posted before it. */
+async function onePr(options, base, get) {
+    const pr = await get(`${base}/pulls/${options.pr}`);
+    const before = (at) => !options.until || (typeof at === 'string' && at < options.until);
+    // Every page: a long-running pull request has hundreds of commits and comments.
+    const all = async (url) => {
+        const items = [];
+        for (let page = 1; page <= 30; page++) {
+            const batch = await get(`${url}?per_page=100&page=${page}`);
+            items.push(...batch);
+            if (batch.length < 100)
+                break;
+        }
+        return items;
+    };
+    const commits = await all(`${base}/pulls/${options.pr}/commits`);
+    const atUntil = commits.filter(c => before(c.commit?.committer?.date)).at(-1)?.sha;
+    const head = atUntil ?? pr.head?.sha;
+    const author = String(pr.user?.login ?? '');
+    const reviewer = (user) => !!user?.login && user.login !== author;
+    const raw = await all(`${base}/pulls/${options.pr}/comments`);
+    const reviews = await all(`${base}/pulls/${options.pr}/reviews`);
+    return {
+        number: Number(options.pr), mergeSha: head, mergedAt: pr.merged_at ?? '',
+        comments: raw.filter(c => reviewer(c.user) && before(c.created_at)).flatMap(c => toComment(Number(options.pr), c, author)),
+        reviews: reviews.filter(r => reviewer(r.user) && before(r.submitted_at) && r.commit_id && String(r.body ?? '').trim())
+            .map((r) => ({ id: String(r.id), prNumber: Number(options.pr), commit: r.commit_id, body: String(r.body), author: String(r.user.login), source: sourceOf(r.user), prAuthor: author })),
+    };
+}
 /** A review comment where it was written: its original commit and lines. */
-function toComment(prNumber, c) {
+function toComment(prNumber, c, prAuthor) {
     const end = c.original_line ?? c.line;
     const commit = c.original_commit_id ?? c.commit_id;
     if (!c.path || !end || !commit || c.in_reply_to_id)
         return [];
     const start = c.original_start_line ?? c.start_line ?? end;
-    return [{ id: String(c.id), prNumber, path: c.path, start: Math.min(start, end), end, commit, body: String(c.body ?? ''), author: String(c.user?.login ?? '') }];
+    return [{ id: String(c.id), prNumber, path: c.path, start: Math.min(start, end), end, commit, body: String(c.body ?? ''), author: String(c.user?.login ?? ''), source: sourceOf(c.user), prAuthor }];
+}
+/** A GitHub App or a bot account (`type: Bot`, or a login like `name[bot]`), else a person's login, whose text may itself be an AI's. */
+function sourceOf(user) {
+    return user?.type === 'Bot' || /\[bot\]$|bot$/i.test(String(user?.login ?? '')) ? 'bot' : 'person';
+}
+/** Every point the model judged, with the person's words and what it made of them (a rule, or none), beside the lessons for audit. */
+function auditRules(cwd, points, kept) {
+    const at = new Date().toISOString();
+    const byComment = new Map(kept.flatMap(l => l.evidence.map(e => [e.comment, l])));
+    const lines = points.map(p => {
+        const e = p.evidence[0];
+        const rule = byComment.get(e.comment);
+        return JSON.stringify({ at, pr: e.pr, author: e.author, said: p.text, rule: rule && rule.text !== p.text ? rule.text : rule ? '(kept as said)' : null });
+    });
+    const file = path.join(path.dirname(lessonsPath(cwd)), 'review-rules-log.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${lines.join('\n')}\n`);
 }

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

@@ -1,23 +1,73 @@
-import type { Git, ReviewComment } from './acted-on.js';
+import type { Git, ReviewBody, ReviewComment } from './acted-on.js';
+/**
+ * One piece of a lesson's evidence trail:
+ *   point     a review point making it (the candidate's own source; weak, but it can recur);
+ *   outcome   a later commit fixed the lines the point named, or the pull request was reverted;
+ *   counter   the lines shipped unchanged and nothing needed fixing within the window;
+ *   correction  a person changed what an agent wrote (human-edits.ts): heavily weighted, it makes a lesson;
+ *   accepted / rejected   a person decided (`rigour learn-reviews --promote / --reject`);
+ *   norule    the rule writer found no rule in it (a report, a template, a one-off): never promoted again.
+ * A record from before evidence kinds has none: it is a `point`.
+ */
+export type EvidenceKind = 'point' | 'outcome' | 'counter' | 'correction' | 'accepted' | 'rejected' | 'norule';
+export interface LessonEvidence {
+    kind?: EvidenceKind;
+    pr: number;
+    /** The review comment or review-body point (or, for a decision, what decided it). */
+    comment: string;
+    /** Who wrote the point, or who decided. */
+    author: string;
+    /** A review bot's login (a GitHub App), or a person's (whose text may itself be an AI's): metadata, never a gate. */
+    source?: 'person' | 'bot';
+    /** Who wrote the pull request: recurrence counts only across different authors. */
+    prAuthor?: string;
+    /** Whether the pull request changed the lines before merging: not evidence (agents apply comments on their own), recorded. */
+    actedOn?: boolean;
+    /** The person's own words, kept when a rule was written from them (rules-from-reviews.ts). */
+    said?: string;
+    /** A point's own words, as it was made (each point merged into a lesson keeps its own). */
+    text?: string;
+    /** What the evidence was: the fixing commit, the window, who decided and why. */
+    detail?: string;
+    at?: string;
+}
 export interface ReviewLesson {
     id: string;
     text: string;
     file: string;
     symbols: string[];
-    state: 'candidate' | 'verified';
-    evidence: Array<{
-        pr: number;
-        comment: string;
-        author: string;
-    }>;
+    /** `rejected`: an anti-lesson, a point the team decided against. */
+    state: 'candidate' | 'verified' | 'rejected';
+    /** Which evidence made it a lesson. */
+    promotedBy?: 'outcome' | 'correction' | 'person' | 'recurrence' | 'legacy';
+    evidence: LessonEvidence[];
+    /** Where the point sits in the commit it was made on, for outcome evidence (inline comments only). */
+    at?: {
+        commit: string;
+        start: number;
+        end: number;
+    };
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * A lesson's state from its evidence trail. A person's decision wins; then an outcome; counter-evidence
+ * holds a candidate back; recurrence across pull requests and authors is enough only without it. A record
+ * from before evidence kinds keeps the state it had.
+ */
+export declare function lessonState(lesson: ReviewLesson): Pick<ReviewLesson, 'state' | 'promotedBy'>;
 /** The point of a review comment: its bold title, else its first sentence, without tool output or markup. */
 export declare function lessonText(body: string): string;
 /** Identifiers a lesson is about: those the comment names, then those on the lines it pointed at. */
 export declare function lessonSymbols(body: string, codeLines: string[]): string[];
 export declare function lessonFromComment(git: Git, comment: ReviewComment, at?: string): ReviewLesson | undefined;
+/**
+ * Candidate lessons from a review body's points. A point naming a path is about that file; one naming
+ * only a file the PR changed after the review (by its name) is about that file; a point naming none is
+ * a team standard (file ''), served with any change it is about once evidence makes it a lesson.
+ * Whether files changed after it is recorded, not required.
+ */
+export declare function lessonsFromReview(review: ReviewBody, changedAfter: string[], at?: string): ReviewLesson[];
 /**
  * Add lessons to the store. The same lesson again (same text, or the same
  * file with two shared symbols) adds evidence; acted on in enough PRs, it is
@@ -37,16 +87,19 @@ export interface ChangeShape {
  * Lessons that apply to a change, best first. A lesson applies when the change
  * touches its file, or shares at least two specific identifiers with it; a
  * shared directory only breaks ties. Lessons about docs, tests or config never
- * apply to other files.
+ * apply to other files. A team standard (a lesson with no file) applies to every
+ * change; the best-evidenced few follow the file lessons.
  */
 export declare function matchLessons(lessons: ReviewLesson[], change: ChangeShape, options?: {
     includeCandidates?: boolean;
     limit?: number;
+    standards?: number;
 }): ReviewLesson[];
 /** RIGOUR_REVIEW_LESSONS points at a lessons file outside the clone (CI, or a team's shared copy). */
 export declare function lessonsPath(cwd: string): string;
 export declare function readLessons(cwd: string): ReviewLesson[];
 export declare function writeLessons(cwd: string, lessons: ReviewLesson[]): void;
-export declare function promoteLesson(cwd: string, id: string): ReviewLesson | undefined;
+/** A person's decision on a lesson, kept as evidence: accepted makes it a lesson, rejected an anti-lesson. Undefined for an unknown id. */
+export declare function decideLesson(cwd: string, id: string, decision: 'accepted' | 'rejected', by: string, why?: string): ReviewLesson | undefined;
 /** An identifier specific enough to link two pieces of code: camelCase, snake_case, or long. */
 export declare function isSpecific(symbol: string): boolean;