@rigour-labs/core 6.7.1 → 6.7.4

package/dist/review-learning/lessons.js

@@ -1,22 +1,70 @@
 /**
- * Review lessons: what a team's acted-on review comments taught, ready to
- * hand to the next agent before it opens a PR.
+ * Review lessons: what a team's reviews taught, ready to hand to the next agent
+ * and judge.
  *
- * A lesson starts as a candidate with its evidence (PR, comment, author). It
- * becomes verified only when the same lesson was acted on in two or more PRs,
- * or a person promotes it. Lessons stay in the repository's .rigour/ folder
- * (ignored by git) and are sent nowhere except to the user's own model.
+ * Evidence only. Every review point, a person's, an AI's posted under a person's
+ * login, or a bot's, is a candidate; who wrote it is recorded, never the gate. A
+ * candidate becomes a lesson on evidence (lessonState): an outcome (a later fix
+ * to the lines it pointed at), a person accepting it, or, weak alone, the same
+ * point recurring across pull requests by different authors. Counter-evidence (the
+ * lines shipped unchanged and nothing needed fixing within a window) holds it
+ * back, and a person rejecting it makes it an anti-lesson the judges are told is
+ * settled. Every piece of evidence stays on the lesson. Lessons stay in the
+ * repository's .rigour/ folder and are sent nowhere except to the user's own model.
  */
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
+import { bodyPoints } from './review-points.js';
 const STORE = path.join('.rigour', 'review-lessons.json');
 const MAX_TEXT = 220;
 const MAX_SYMBOLS = 8;
-const VERIFY_AT_PRS = 2;
+/**
+ * Recurrence is weak evidence, and only when independent: the same point on this many pull requests,
+ * by this many different authors, raised by different reviewers or by one reviewer in different words
+ * (a senior re-raising a standard counts; a bot pasting its template on every pull request does not).
+ */
+const RECUR_PRS = 2;
+const RECUR_AUTHORS = 2;
+/** Team standards served with a change, on top of the lessons about its files (an agent's question; a judge takes more), and the words they must share with it. */
+const MAX_STANDARDS = 3;
+const STANDARD_WORDS = 2;
+/** Words that say nothing about what a rule or a change is about. */
+const PLAIN_WORDS = new Set(['when', 'that', 'this', 'with', 'from', 'before', 'after', 'every', 'their', 'them', 'than', 'each', 'only', 'into', 'rather', 'instead', 'should', 'make', 'keep', 'sure', 'does', 'what', 'which', 'there', 'these', 'those', 'such', 'more', 'other', 'same', 'then', 'also', 'both', 'must', 'never', 'always', 'once', 'been', 'have', 'will', 'your', 'about', 'over', 'under', 'change', 'changes', 'code', 'value', 'values', 'data', 'true', 'false', 'null', 'undefined', 'return', 'const', 'function', 'export', 'import', 'await', 'async', 'string', 'number', 'type']);
 /** Lessons from these teach about one document, test or config file, not about code that will change again. */
 const NOT_CODE = /(\.(md|mdx|txt|ya?ml|json|lock|snap)$)|(\.(test|spec)\.[cm]?[jt]sx?$)|(^|\/)(__tests__|docs?|migrations|\.github)\//i;
 const NOT_SYMBOLS = new Set(['this', 'that', 'with', 'from', 'return', 'const', 'await', 'async', 'function', 'true', 'false', 'null', 'undefined', 'string', 'number', 'boolean', 'export', 'import', 'type', 'interface', 'else', 'when', 'then', 'should', 'line', 'lines']);
+/**
+ * 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 function lessonState(lesson) {
+    const kinds = new Set(lesson.evidence.map(e => e.kind));
+    if (!lesson.evidence.some(e => e.kind))
+        return lesson.state === 'verified' ? { state: 'verified', promotedBy: lesson.promotedBy ?? 'legacy' } : { state: lesson.state };
+    const decisions = lesson.evidence.filter(e => e.kind === 'accepted' || e.kind === 'rejected');
+    const last = decisions.at(-1);
+    if (last?.kind === 'rejected')
+        return { state: 'rejected' };
+    if (last?.kind === 'accepted')
+        return { state: 'verified', promotedBy: 'person' };
+    if (kinds.has('norule'))
+        return { state: 'candidate' };
+    if (kinds.has('correction'))
+        return { state: 'verified', promotedBy: 'correction' };
+    if (kinds.has('outcome'))
+        return { state: 'verified', promotedBy: 'outcome' };
+    if (kinds.has('counter'))
+        return { state: 'candidate' };
+    const points = lesson.evidence.filter(e => (e.kind ?? 'point') === 'point');
+    const prs = new Set(points.map(e => e.pr)).size;
+    const authors = new Set(points.map(e => e.prAuthor).filter(Boolean)).size;
+    const reviewers = new Set(points.map(e => e.author).filter(Boolean)).size;
+    const wordings = new Set(points.map(e => normalize(e.text ?? '')).filter(Boolean)).size;
+    const independent = reviewers >= 2 || wordings >= 2;
+    return prs >= RECUR_PRS && authors >= RECUR_AUTHORS && independent ? { state: 'verified', promotedBy: 'recurrence' } : { state: 'candidate' };
+}
 /** The point of a review comment: its bold title, else its first sentence, without tool output or markup. */
 export function lessonText(body) {
     const cleaned = body
@@ -58,9 +106,30 @@ export function lessonFromComment(git, comment, at = new Date().toISOString()) {
     return {
         id: crypto.createHash('sha256').update(`${comment.path}\u0000${normalize(text)}`).digest('hex').slice(0, 12),
         text, file: comment.path, symbols: lessonSymbols(comment.body, codeLines), state: 'candidate',
-        evidence: [{ pr: comment.prNumber, comment: comment.id, author: comment.author }], createdAt: at, updatedAt: at,
+        evidence: [{ kind: 'point', pr: comment.prNumber, comment: comment.id, author: comment.author, ...pointMeta(comment), text, at }],
+        at: { commit: comment.commit, start: comment.start, end: comment.end }, createdAt: at, updatedAt: at,
     };
 }
+/**
+ * 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 function lessonsFromReview(review, changedAfter, at = new Date().toISOString()) {
+    return bodyPoints(review.body).flatMap((point, i) => {
+        const text = point.replace(/[*_]/g, '').slice(0, MAX_TEXT).trim();
+        if (text.length < 12)
+            return [];
+        const named = /(?:^|[\s`(])((?:[\w.-]+\/)+[\w.-]+\.\w+)/.exec(point)?.[1];
+        const file = named ?? changedAfter.find(f => text.includes(path.posix.basename(f))) ?? '';
+        return [{
+                id: crypto.createHash('sha256').update(`${file}\u0000${normalize(text)}`).digest('hex').slice(0, 12),
+                text, file, symbols: lessonSymbols(point, []), state: 'candidate',
+                evidence: [{ kind: 'point', pr: review.prNumber, comment: `review-${review.id}-${i}`, author: review.author, ...pointMeta(review), actedOn: changedAfter.length > 0, text, at }], createdAt: at, updatedAt: at,
+            }];
+    });
+}
 /**
  * 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
@@ -70,23 +139,26 @@ export function mergeLessons(existing, incoming) {
     const lessons = existing.map(l => ({ ...l, evidence: [...l.evidence] }));
     let added = 0;
     for (const lesson of incoming) {
-        const same = lessons.find(l => l.id === lesson.id || (l.file === lesson.file && shared(l.symbols, lesson.symbols) >= 2));
+        // Shared names find the same point made again on another pull request; two points on one pull request are two points.
+        const otherPr = (l) => !l.evidence.some(e => lesson.evidence.some(x => x.pr === e.pr));
+        const same = lessons.find(l => l.id === lesson.id || (l.file === lesson.file && shared(l.symbols, lesson.symbols) >= 2 && otherPr(l))
+            || (!l.file && !lesson.file && sameWords(l.text, lesson.text)));
         if (!same) {
-            lessons.push(lesson);
+            lessons.push({ ...lesson, evidence: [...lesson.evidence] });
             added++;
             continue;
         }
         for (const e of lesson.evidence)
-            if (!same.evidence.some(x => x.comment === e.comment))
+            if (!same.evidence.some(x => x.comment === e.comment && x.kind === e.kind))
                 same.evidence.push(e);
         same.updatedAt = lesson.updatedAt;
     }
     let verified = 0;
     for (const lesson of lessons) {
-        if (lesson.state === 'candidate' && new Set(lesson.evidence.map(e => e.pr)).size >= VERIFY_AT_PRS) {
-            lesson.state = 'verified';
+        const before = lesson.state;
+        Object.assign(lesson, lessonState(lesson));
+        if (lesson.state === 'verified' && before !== 'verified')
             verified++;
-        }
     }
     return { lessons, added, verified };
 }
@@ -94,12 +166,13 @@ export function mergeLessons(existing, incoming) {
  * 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 function matchLessons(lessons, change, options = {}) {
     const dirs = new Set(change.files.map(f => path.posix.dirname(f)));
     const scored = lessons
-        .filter(l => (options.includeCandidates || l.state === 'verified') && !NOT_CODE.test(l.file))
+        .filter(l => !!l.file && (l.state === 'verified' || (options.includeCandidates && l.state === 'candidate')) && !NOT_CODE.test(l.file))
         .map(l => ({
         lesson: l,
         score: (change.files.includes(l.file) ? 3 : 0) + (dirs.has(path.posix.dirname(l.file)) ? 0.5 : 0)
@@ -107,7 +180,17 @@ export function matchLessons(lessons, change, options = {}) {
     }))
         .filter(s => s.score >= 3)
         .sort((a, b) => b.score - a.score || b.lesson.evidence.length - a.lesson.evidence.length);
-    return scored.slice(0, options.limit ?? 5).map(s => s.lesson);
+    // A team standard (no file) applies when its words are the change's: its paths and the names on its added lines,
+    // split into words. A rule about keyboard shortcuts says nothing to a change to a database job.
+    const changeWords = new Set([...change.files.flatMap(f => f.split(/[/._-]+/)), ...change.symbols].flatMap(words));
+    const standards = lessons
+        .filter(l => !l.file && (l.state === 'verified' || (options.includeCandidates && l.state === 'candidate')))
+        .map(l => ({ lesson: l, shared: new Set(words(l.text)).size === 0 ? 0 : [...new Set(words(l.text))].filter(w => changeWords.has(w)).length }))
+        .filter(s => s.shared >= STANDARD_WORDS)
+        .sort((a, b) => b.shared - a.shared || b.lesson.evidence.length - a.lesson.evidence.length)
+        .slice(0, options.standards ?? MAX_STANDARDS)
+        .map(s => s.lesson);
+    return [...scored.slice(0, options.limit ?? 5).map(s => s.lesson), ...standards];
 }
 /** RIGOUR_REVIEW_LESSONS points at a lessons file outside the clone (CI, or a team's shared copy). */
 export function lessonsPath(cwd) {
@@ -127,13 +210,15 @@ export function writeLessons(cwd, lessons) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify({ version: 1, lessons }, null, 2) + '\n');
 }
-export function promoteLesson(cwd, id) {
+/** 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 function decideLesson(cwd, id, decision, by, why = '') {
     const lessons = readLessons(cwd);
     const lesson = lessons.find(l => l.id === id);
     if (!lesson)
         return undefined;
-    lesson.state = 'verified';
-    lesson.updatedAt = new Date().toISOString();
+    const at = new Date().toISOString();
+    lesson.evidence.push({ kind: decision, pr: lesson.evidence[0]?.pr ?? 0, comment: `${decision}-${at}`, author: by, detail: why, at });
+    Object.assign(lesson, lessonState(lesson), { updatedAt: at });
     writeLessons(cwd, lessons);
     return lesson;
 }
@@ -147,3 +232,20 @@ function normalize(text) {
 function shared(a, b) {
     return a.filter(s => b.includes(s)).length;
 }
+/** Two team standards are the same point when most of their words are: a reviewer rarely repeats a sentence exactly. */
+function sameWords(a, b) {
+    const words = (t) => new Set(normalize(t).split(' ').filter(w => w.length >= 4));
+    const x = words(a), y = words(b);
+    if (x.size === 0 || y.size === 0)
+        return false;
+    const common = [...x].filter(w => y.has(w)).length;
+    return common / Math.max(x.size, y.size) >= 0.6;
+}
+/** The meaningful words of a text or an identifier: `hasLaterAttempt` and "a later attempt" share later and attempt. */
+function words(text) {
+    return text.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z]+/).filter(w => w.length >= 4 && !PLAIN_WORDS.has(w));
+}
+/** Who made a point and on whose pull request: recorded with it, never a filter. */
+function pointMeta(x) {
+    return { ...(x.source ? { source: x.source } : {}), ...(x.prAuthor ? { prAuthor: x.prAuthor } : {}), ...(x.actedOn !== undefined ? { actedOn: x.actedOn } : {}) };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Outcome evidence from git, free and deterministic: what happened to the lines a review point named
+ * after the pull request merged. A point the pull request did not act on, whose lines a later commit
+ * on main changed with a fix, was right (outcome). One whose lines shipped and stayed unchanged for the
+ * whole window was not needed (counter). A revert of the pull request is an outcome for every point it
+ * left unaddressed. With `until`, only history before it counts, so a backtest never sees the future.
+ */
+import type { Git } from './acted-on.js';
+import type { LessonEvidence, ReviewLesson } from './lessons.js';
+export interface OutcomeOptions {
+    /** The main branch the pull request merged into. */
+    mainRef: string;
+    /** Only history before this time (ISO); now when unset. */
+    until?: string;
+    /** How long unchanged lines must ship before that counts against the point. */
+    windowDays?: number;
+}
+export interface MergedAt {
+    number: number;
+    mergeSha: string;
+    mergedAt: string;
+}
+/** The outcome or counter evidence for an inline point the pull request did not act on, or undefined when there is none yet. */
+export declare function outcomeFor(git: Git, lesson: ReviewLesson, pr: MergedAt, options: OutcomeOptions): LessonEvidence | undefined;
+/** A revert of the pull request on main, before `until`: an outcome for every point it left unaddressed. */
+export declare function revertOf(git: Git, pr: MergedAt, options: OutcomeOptions): LessonEvidence | undefined;

package/dist/review-learning/outcomes.js

@@ -0,0 +1,73 @@
+import { changedHunks } from './acted-on.js';
+/** Commit subjects that say the commit fixed something. */
+const FIX = /\b(fix(e[sd])?|bug|hotfix|regression|revert|broke|broken)\b/i;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The outcome or counter evidence for an inline point the pull request did not act on, or undefined when there is none yet. */
+export function outcomeFor(git, lesson, pr, options) {
+    const point = lesson.evidence.find(e => (e.kind ?? 'point') === 'point' && e.pr === pr.number);
+    if (!point || point.actedOn || !lesson.at || !lesson.file || !pr.mergedAt)
+        return undefined;
+    let range = shift(changedHunks(git, lesson.at.commit, pr.mergeSha, lesson.file), [lesson.at.start, lesson.at.end]);
+    if (!range)
+        return undefined; // the pull request changed them after all
+    const before = options.until ? [`--before=${options.until}`] : [];
+    let commits = [];
+    try {
+        commits = git(['rev-list', '--reverse', '--first-parent', ...before, `${pr.mergeSha}..${options.mainRef}`, '--', lesson.file]).split('\n').filter(Boolean);
+    }
+    catch {
+        return undefined;
+    }
+    for (const sha of commits) {
+        const hunks = changedHunks(git, `${sha}^`, sha, lesson.file);
+        const next = shift(hunks, range);
+        if (next) {
+            range = next;
+            continue;
+        }
+        const [subject, date] = git(['log', '-1', '--format=%s%x09%cI', sha]).trim().split('\t');
+        // Changed by a commit that says it fixed something: the point was right. Changed otherwise: no verdict.
+        return FIX.test(subject) ? { kind: 'outcome', pr: pr.number, comment: `outcome-${sha.slice(0, 12)}`, author: '', detail: `fixed later by ${sha.slice(0, 9)} "${subject}"`, at: date } : undefined;
+    }
+    const now = options.until ? Date.parse(options.until) : Date.now();
+    const days = Math.floor((now - Date.parse(pr.mergedAt)) / DAY_MS);
+    if (days < (options.windowDays ?? 30))
+        return undefined;
+    return { kind: 'counter', pr: pr.number, comment: `counter-${pr.number}-${lesson.at.start}`, author: '', detail: `the lines shipped unchanged for ${days} days after the merge`, at: options.until ?? new Date().toISOString() };
+}
+/** A revert of the pull request on main, before `until`: an outcome for every point it left unaddressed. */
+export function revertOf(git, pr, options) {
+    let log = '';
+    try {
+        log = git(['log', '--first-parent', '--format=%H%x09%cI%x09%s', ...(options.until ? [`--before=${options.until}`] : []), `${pr.mergeSha}..${options.mainRef}`]);
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of log.split('\n')) {
+        const [sha, date, subject] = line.split('\t');
+        if (sha && /^revert\b/i.test(subject ?? '') && (subject.includes(`#${pr.number}`) || subject.includes(pr.mergeSha.slice(0, 7)))) {
+            return { kind: 'outcome', pr: pr.number, comment: `revert-${sha.slice(0, 12)}`, author: '', detail: `the pull request was reverted by ${sha.slice(0, 9)} "${subject}"`, at: date };
+        }
+    }
+    return undefined;
+}
+/** The range after a commit's hunks, or undefined when a hunk touched it. */
+function shift(hunks, [start, end]) {
+    let offset = 0;
+    for (const [s, e, removed, added] of hunks) {
+        if (removed === 0) {
+            // An insertion after line s: inside the range touches it, before it moves it down.
+            if (s >= start && s < end)
+                return undefined;
+            if (s < start)
+                offset += added;
+            continue;
+        }
+        if (s <= end && start <= e)
+            return undefined;
+        if (e < start)
+            offset += added - removed;
+    }
+    return [start + offset, end + offset];
+}

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

@@ -3,9 +3,12 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { actedOn, gitIn } from './acted-on.js';
+import { gitIn, withActedOn } from './acted-on.js';
 import { learnFromReviews } from './learn-from-reviews.js';
-import { isSpecific, lessonText, matchLessons, mergeLessons, readLessons } from './lessons.js';
+import { outcomeFor } from './outcomes.js';
+import { rulesFromReviews } from './rules-from-reviews.js';
+import { describeLesson, lessonView } from './team-lessons.js';
+import { decideLesson, isSpecific, lessonState, lessonText, matchLessons, mergeLessons, readLessons, writeLessons } from './lessons.js';
 import { lessonsForDiff, lessonsSection } from './team-lessons.js';
 let repo;
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
@@ -23,17 +26,17 @@ beforeEach(() => {
 });
 afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
 const comment = (id, sha, start, body, prNumber = 7) => ({ id, prNumber, path: 'src/orders.ts', start, end: start, commit: sha, body, author: 'reviewer' });
-describe('actedOn', () => {
-    it('keeps a comment whose lines changed before merge, and drops one nobody acted on', () => {
+describe('acted on', () => {
+    it('marks a comment whose lines changed before merge, and one nobody acted on, keeping both', () => {
         write(V1);
         const reviewed = commit('pr head');
         write(V2);
         const merged = commit('address review');
-        const acted = actedOn(gitIn(repo), { number: 7, mergeSha: merged, mergedAt: '', comments: [
+        const marked = withActedOn(gitIn(repo), { number: 7, mergeSha: merged, mergedAt: '', comments: [
                 comment('a', reviewed, 2, '**Use an upsert keyed on `id` so a retry does not duplicate the order.**'),
                 comment('b', reviewed, 3, 'Nit: return the whole order?'),
-            ] });
-        expect(acted.map(c => c.id)).toEqual(['a']);
+            ], reviews: [] });
+        expect(marked.map(c => [c.id, c.actedOn])).toEqual([['a', true], ['b', false]]);
     });
 });
 describe('lessons', () => {
@@ -43,16 +46,32 @@ describe('lessons', () => {
         expect(lessonText('Callers retry on timeout, so this insert duplicates orders. Please use upsert.')).toBe('Callers retry on timeout, so this insert duplicates orders.');
         expect(lessonText('### Medium Severity\n\nThe retry loop never resets `attempt`, so a second failure gives up at once.')).toBe('The retry loop never resets `attempt`, so a second failure gives up at once.');
     });
-    it('verifies a lesson only when it was acted on in two PRs', () => {
-        const lesson = (pr, comment) => ({
-            id: 'x', text: 'Use upsert', file: 'src/orders.ts', symbols: ['save', 'insert'], state: 'candidate',
-            evidence: [{ pr, comment, author: 'r' }], createdAt: '', updatedAt: '',
-        });
-        const once = mergeLessons([], [lesson(1, 'c1'), lesson(1, 'c2')]);
-        expect(once.lessons[0].state).toBe('candidate');
-        const twice = mergeLessons(once.lessons, [lesson(2, 'c3')]);
-        expect(twice).toMatchObject({ added: 0, verified: 1 });
-        expect(twice.lessons[0].evidence).toHaveLength(3);
+    it('makes a candidate a lesson only on evidence, and keeps every piece of it', () => {
+        const point = (pr, prAuthor, source = 'person', reviewer = `reviewer-of-${pr}`) => ({ kind: 'point', pr, comment: `c${pr}${prAuthor}`, author: reviewer, source, prAuthor });
+        const lesson = (...evidence) => ({ id: 'x', text: 'Use upsert', file: 'src/orders.ts', symbols: [], state: 'candidate', evidence, createdAt: '', updatedAt: '' });
+        expect(lessonState(lesson(point(1, 'ann')))).toEqual({ state: 'candidate' });
+        expect(lessonState(lesson(point(1, 'ann'), point(2, 'ann')))).toEqual({ state: 'candidate' }); // two PRs, one author: weak, not enough
+        expect(lessonState(lesson(point(1, 'ann'), point(2, 'bob', 'bot')))).toEqual({ state: 'verified', promotedBy: 'recurrence' }); // a bot's point counts the same
+        const said = (e, text) => ({ ...e, text });
+        expect(lessonState(lesson(said(point(1, 'ann', 'bot', 'helper[bot]'), 'Consider more tests.'), said(point(2, 'bob', 'bot', 'helper[bot]'), 'Consider more tests.')))).toEqual({ state: 'candidate' }); // one bot's template on every PR is one source
+        expect(lessonState(lesson(said(point(1, 'ann', 'person', 'lead'), 'Regenerate the API client after changing the schema.'), said(point(2, 'bob', 'person', 'lead'), 'The generated client is stale again.')))).toEqual({ state: 'verified', promotedBy: 'recurrence' }); // a senior re-raising it in their own words
+        expect(lessonState(lesson(point(1, 'ann'), point(2, 'bob'), { kind: 'norule', pr: 1, comment: 'n', author: '' }))).toEqual({ state: 'candidate' }); // no rule in it: never promoted again
+        const outcome = { kind: 'outcome', pr: 1, comment: 'o', author: '', detail: 'fixed later by abc' };
+        const counter = { kind: 'counter', pr: 1, comment: 'k', author: '', detail: 'unchanged 40 days' };
+        expect(lessonState(lesson(point(1, 'ann', 'bot'), outcome))).toEqual({ state: 'verified', promotedBy: 'outcome' });
+        expect(lessonState(lesson(point(1, 'ann'), point(2, 'bob'), counter))).toEqual({ state: 'candidate' }); // counter-evidence holds recurrence back
+        const accepted = { kind: 'accepted', pr: 1, comment: 'y', author: 'lead@x' };
+        const rejected = { kind: 'rejected', pr: 1, comment: 'n', author: 'lead@x' };
+        expect(lessonState(lesson(point(1, 'ann'), outcome, rejected))).toEqual({ state: 'rejected' }); // a person's decision wins
+        expect(lessonState(lesson(point(1, 'ann'), rejected, accepted))).toEqual({ state: 'verified', promotedBy: 'person' }); // the latest decision
+        expect(lessonState({ ...lesson({ pr: 1, comment: 'old', author: 'r' }), state: 'verified' })).toEqual({ state: 'verified', promotedBy: 'legacy' }); // a record from before evidence keeps its state
+    });
+    it('records a person accepting or rejecting a lesson as evidence, with who and why', () => {
+        writeLessons(repo, [{ id: 'x', text: 'Use upsert', file: 'src/orders.ts', symbols: [], state: 'candidate', evidence: [{ kind: 'point', pr: 1, comment: 'c', author: 'r' }], createdAt: '', updatedAt: '' }]);
+        expect(decideLesson(repo, 'x', 'rejected', 'lead@x', 'we accept duplicates here')).toMatchObject({ state: 'rejected' });
+        expect(readLessons(repo)[0].evidence.at(-1)).toMatchObject({ kind: 'rejected', author: 'lead@x', detail: 'we accept duplicates here' });
+        expect(matchLessons(readLessons(repo), { files: ['src/orders.ts'], symbols: new Set() }, { includeCandidates: true })).toEqual([]); // never served as a lesson
+        expect(decideLesson(repo, 'nope', 'accepted', 'lead@x')).toBeUndefined();
     });
     it('matches lessons by file, symbols and directory, verified only unless asked', () => {
         const base = { symbols: ['insert'], evidence: [{ pr: 1, comment: 'c', author: 'r' }], createdAt: '', updatedAt: '' };
@@ -69,6 +88,93 @@ describe('lessons', () => {
         expect(matchLessons(lessons, change, { includeCandidates: true }).map(l => l.id)).toEqual(['2', '1', '3']);
     });
 });
+describe('learning from one pull request as it goes', () => {
+    it('reads its reviews up to a time, and counts a point acted on by the head as of then', async () => {
+        write(V1);
+        const reviewed = commit('pr head');
+        write(V2);
+        const fixed = commit('address review');
+        const api = 'https://api.github.com/repos/acme/app';
+        const pages = {
+            [`${api}/pulls/42`]: { number: 42, user: { login: 'dev' }, head: { sha: fixed } },
+            [`${api}/pulls/42/commits?per_page=100&page=1`]: [
+                { sha: reviewed, commit: { committer: { date: '2026-09-01T00:00:00Z' } } },
+                { sha: fixed, commit: { committer: { date: '2026-09-02T00:00:00Z' } } },
+            ],
+            [`${api}/pulls/42/comments?per_page=100&page=1`]: [],
+            [`${api}/pulls/42/reviews?per_page=100&page=1`]: [
+                { id: 1, commit_id: reviewed, submitted_at: '2026-09-01T12:00:00Z', user: { login: 'priya' }, body: '- In src/orders.ts make the insert idempotent on retry.' },
+                { id: 2, commit_id: fixed, submitted_at: '2026-09-06T00:00:00Z', user: { login: 'priya' }, body: '- A later point the learner must not see yet.' },
+            ],
+        };
+        const fetchImpl = async (url) => ({ ok: url in pages, status: url in pages ? 200 : 404, json: async () => pages[url] });
+        const early = await learnFromReviews(repo, { token: 't', repo: 'acme/app', fetch: fetchImpl, pr: 42, until: '2026-09-01T18:00:00Z' });
+        expect(early).toMatchObject({ prs: 1, reviewBodies: 1, total: 1 }); // the later review is not seen yet
+        expect(readLessons(repo)[0]).toMatchObject({ file: 'src/orders.ts', text: 'In src/orders.ts make the insert idempotent on retry.', evidence: [{ pr: 42, author: 'priya', actedOn: false }] });
+        fs.rmSync(path.join(repo, '.rigour', 'review-lessons.json'));
+        await learnFromReviews(repo, { token: 't', repo: 'acme/app', fetch: fetchImpl, pr: 42, until: '2026-09-03T00:00:00Z' });
+        expect(readLessons(repo)[0].evidence[0]).toMatchObject({ actedOn: true }); // the fix landed before this cut
+    });
+});
+describe('outcome evidence from git', () => {
+    it('finds a later fix to the lines a point named, counts lines left alone against it, and never looks past the cut', () => {
+        write('export function total(order) {\n  return order.items.length;\n}\n');
+        commit('base');
+        git('checkout', '-qb', 'feature');
+        write('export function total(order) {\n  const n = order.items.length;\n  return n;\n}\n');
+        const reviewed = commit('pr head');
+        git('checkout', '-q', 'main');
+        git('merge', '-q', '--no-ff', '--no-edit', 'feature');
+        const merge = git('rev-parse', 'HEAD');
+        write('// header\nexport function total(order) {\n  const n = order.items?.length ?? 0;\n  return n;\n}\n');
+        execFileSync('git', ['-C', repo, 'commit', '-qam', 'fix: total crashes on an order with no items'], { env: { ...process.env, GIT_COMMITTER_DATE: '2026-09-20T00:00:00Z' } });
+        const point = (start, actedOn = false) => ({ id: `p${start}`, text: 'Guard a missing items list.', file: 'src/orders.ts', symbols: [], state: 'candidate', at: { commit: reviewed, start, end: start }, evidence: [{ kind: 'point', pr: 7, comment: `c${start}`, author: 'bot', source: 'bot', actedOn }], createdAt: '', updatedAt: '' });
+        const pr = { number: 7, mergeSha: merge, mergedAt: '2026-09-01T00:00:00Z' };
+        const later = outcomeFor(gitIn(repo), point(2), pr, { mainRef: 'main' });
+        expect(later).toMatchObject({ kind: 'outcome', detail: expect.stringContaining('fix: total crashes on an order with no items') });
+        expect(outcomeFor(gitIn(repo), point(2), pr, { mainRef: 'main', until: '2026-09-10T00:00:00Z' })).toBeUndefined(); // before the fix, within the window: no verdict yet
+        expect(outcomeFor(gitIn(repo), point(3), pr, { mainRef: 'main' })).toMatchObject({ kind: 'counter' }); // `return n;` shipped and stayed, past the window
+        expect(outcomeFor(gitIn(repo), point(2, true), pr, { mainRef: 'main' })).toBeUndefined(); // acted on in the PR: no outcome to read
+    });
+});
+describe('team standards', () => {
+    it('verifies a standard when the same point recurs in another author\'s PR, and serves it only to a change it is about', () => {
+        const standard = (pr, text) => ({ id: `s${pr}`, text, file: '', symbols: [], state: 'candidate', evidence: [{ kind: 'point', pr, comment: `r${pr}`, author: `reviewer${pr}`, prAuthor: `dev${pr}` }], createdAt: '', updatedAt: '' });
+        const merged = mergeLessons([], [standard(1, 'Bound both ends of every time window a job reads.'), standard(2, 'Bound both ends of the time window this job reads.')]);
+        expect(merged.lessons).toHaveLength(1);
+        expect(merged.lessons[0].state).toBe('verified');
+        const unrelated = mergeLessons(merged.lessons, [standard(3, 'Log the request id on every error.')]);
+        expect(unrelated.lessons).toHaveLength(2);
+        expect(matchLessons(unrelated.lessons, { files: ['src/jobs/scan.ts'], symbols: new Set(['timeWindowStart', 'readRows']) }).map(l => l.text)).toEqual(['Bound both ends of every time window a job reads.']);
+        expect(matchLessons(unrelated.lessons, { files: ['src/ui/Dialog.svelte'], symbols: new Set(['onKeydown']) })).toEqual([]); // nothing in common: not served
+    });
+});
+describe('turning reviews into rules', () => {
+    const point = (id, text, file = '') => ({ id, text, file, symbols: [], state: 'candidate', evidence: [{ pr: 7, comment: `c-${id}`, author: 'priya' }], createdAt: '', updatedAt: '' });
+    it('keeps the rule behind a point, drops a status note, keeps an unanswered point as said, and keeps the words beside the rule', async () => {
+        const prompts = [];
+        const write = async (prompt) => {
+            prompts.push(prompt);
+            return 'Here you go:\n{"rules":[{"id":"a","rule":"Apply discounts before computing an invoice total.","file":null},{"id":"b","rule":null,"file":null}]}';
+        };
+        const points = [point('a', 'The invoice total is computed before the discount is applied.'), point('b', 'npm run check: 0 errors, lint clean.'), point('c', 'A retry posts the payment twice.')];
+        const out = await rulesFromReviews(points, write);
+        expect(out).toMatchObject({ rules: 1, dropped: 1, unanswered: 1 });
+        expect(out.lessons.map(l => [l.text, l.evidence.at(-1)?.kind])).toEqual([
+            ['Apply discounts before computing an invoice total.', undefined], ['npm run check: 0 errors, lint clean.', 'norule'], ['A retry posts the payment twice.', undefined],
+        ]); // the no-rule point is kept and marked, never sent again
+        expect(out.lessons[0].evidence[0].said).toBe('The invoice total is computed before the discount is applied.');
+        expect(prompts[0]).toContain('"said": "npm run check: 0 errors, lint clean."');
+        expect(describeLesson(lessonView({ ...out.lessons[0], evidence: [...out.lessons[0].evidence, { pr: 9, comment: 'x', author: 'sam' }] })))
+            .toBe('team standard: Apply discounts before computing an invoice total. (in their words: "The invoice total is computed before the discount is applied.") (acted on in PR #7, #9)');
+    });
+    it('never loses a point when the model cannot run, and keeps a file only when the point was about it', async () => {
+        const out = await rulesFromReviews([point('a', 'In src/run.ts the flag is read last.', 'src/run.ts')], async () => undefined);
+        expect(out.lessons.map(l => [l.text, l.file])).toEqual([['In src/run.ts the flag is read last.', 'src/run.ts']]);
+        const moved = await rulesFromReviews([point('a', 'A point about one place.', 'src/a.ts')], async () => '{"rules":[{"id":"a","rule":"A rule the model placed in another file.","file":"src/b.ts"}]}');
+        expect(moved.lessons[0].file).toBe('');
+    });
+});
 describe('isSpecific', () => {
     it('counts identifiers that name something, not common words', () => {
         expect(['orderId', 'max_rows', 'renderTransactionalMessage'].map(isSpecific)).toEqual([true, true, true]);
@@ -84,21 +190,42 @@ describe('learnFromReviews', () => {
         const api = 'https://api.github.com/repos/acme/app';
         const pages = {
             [`${api}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=1`]: [
-                { number: 7, merged_at: '2026-09-01T00:00:00Z', merge_commit_sha: merged },
+                { number: 7, merged_at: '2026-09-01T00:00:00Z', merge_commit_sha: merged, user: { login: 'dev' } },
                 { number: 8, merged_at: null, merge_commit_sha: null },
             ],
             [`${api}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=2`]: [],
             [`${api}/pulls/7/comments?per_page=100`]: [
                 { id: 11, path: 'src/orders.ts', original_line: 2, original_commit_id: reviewed, body: '**Use an upsert keyed on `id` so retries do not duplicate orders.**', user: { login: 'priya' } },
                 { id: 12, path: 'src/orders.ts', original_line: 2, original_commit_id: reviewed, body: 'agreed', in_reply_to_id: 11, user: { login: 'sam' } },
+                { id: 13, path: 'src/orders.ts', original_line: 2, original_commit_id: reviewed, body: '**Rename the variable to orderRow for clarity.**', user: { login: 'review-helper[bot]', type: 'Bot' } },
+                { id: 14, path: 'src/orders.ts', original_line: 2, original_commit_id: reviewed, body: '**Self note: tidy this later.**', user: { login: 'dev' } },
+            ],
+            [`${api}/pulls/7/reviews?per_page=100`]: [
+                { id: 21, commit_id: reviewed, user: { login: 'priya' }, body: '## Review\n\n- Bound both ends of every time window a scheduled job reads.\n- In src/orders.ts the insert needs the idempotency key.\nThanks!' },
+                { id: 22, commit_id: reviewed, user: { login: 'review-helper[bot]', type: 'Bot' }, body: '- Consider adding more unit tests for orders.' },
+                { id: 23, commit_id: reviewed, user: { login: 'dev' }, body: '- Addressed every point in the next commit.' },
             ],
         };
         const fetchImpl = async (url) => ({ ok: url in pages, status: url in pages ? 200 : 404, json: async () => pages[url] });
         const result = await learnFromReviews(repo, { token: 't', repo: 'acme/app', fetch: fetchImpl });
-        expect(result).toMatchObject({ prs: 1, comments: 1, actedOn: 1, added: 1, total: 1 });
-        expect(readLessons(repo)[0]).toMatchObject({ file: 'src/orders.ts', text: 'Use an upsert keyed on `id` so retries do not duplicate orders.', evidence: [{ pr: 7, author: 'priya' }] });
+        // Every point is a candidate, the bot's too; the author's own comments are not review points.
+        expect(result).toMatchObject({ prs: 1, comments: 2, actedOn: 2, reviewBodies: 2, candidates: { person: 3, bot: 2 }, verified: 0 });
+        const lessons = readLessons(repo);
+        expect(lessons.every(l => l.state === 'candidate')).toBe(true); // nothing is a lesson without evidence
+        const sources = new Set(lessons.flatMap(l => l.evidence.map(e => `${e.author}/${e.source}/${e.prAuthor}`)));
+        expect([...sources].sort()).toEqual(['priya/person/dev', 'review-helper[bot]/bot/dev']);
+        expect(lessons.map(l => l.text)).toEqual(expect.arrayContaining(['Bound both ends of every time window a scheduled job reads.', 'Consider adding more unit tests for orders.']));
         const diff = '+++ b/src/orders.ts\n@@ -1,0 +1,1 @@\n+  await db.insert(other);\n';
-        expect(lessonsForDiff(repo, diff, 'verified')).toEqual([]); // one PR is not enough to verify
-        expect(lessonsSection(lessonsForDiff(repo, diff, 'all'))).toContain('src/orders.ts: Use an upsert keyed on `id` so retries do not duplicate orders. (acted on in PR #7)');
+        expect(lessonsForDiff(repo, diff, 'verified')).toEqual([]); // candidates are not served by default
+        expect(lessonsSection(lessonsForDiff(repo, diff, 'all'))).toContain('src/orders.ts: Use an upsert keyed on `id` so retries do not duplicate orders.');
+        const again = await learnFromReviews(repo, { token: 't', repo: 'acme/app', fetch: fetchImpl, writeRules: async () => { throw new Error('nothing promoted: no rule is written'); } });
+        expect(again).toMatchObject({ added: 0, total: lessons.length });
+        const upsert = lessons.find(l => l.text.startsWith('Use an upsert'));
+        decideLesson(repo, upsert.id, 'accepted', 'lead@acme');
+        const ruled = await learnFromReviews(repo, { token: 't', repo: 'acme/app', fetch: fetchImpl, writeRules: async (prompt) => JSON.stringify({ rules: [...prompt.matchAll(/"id": "(\w+)"/g)].map(m => ({ id: m[1], rule: 'Make every write idempotent on retry.', file: 'src/orders.ts' })) }) });
+        expect(ruled).toMatchObject({ rules: 1, notRules: 0, promoted: { person: 1 } }); // written only for the promoted lesson
+        expect(readLessons(repo).find(l => l.state === 'verified')).toMatchObject({ text: 'Make every write idempotent on retry.', promotedBy: 'person' });
+        const audit = fs.readFileSync(path.join(repo, '.rigour', 'review-rules-log.jsonl'), 'utf8').trim().split('\n').map(l => JSON.parse(l));
+        expect(audit.map(a => [a.said, a.rule])).toEqual([[upsert.text, 'Make every write idempotent on retry.']]);
     });
 });

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

@@ -0,0 +1,4 @@
+/** The bullet and numbered lines of a review body: the points a reviewer makes outside any one line. */
+export declare function bodyPoints(body: string): string[];
+/** A comment's first non-empty line, markup removed, at most 140 characters. */
+export declare function firstLine(text: string): string;

package/dist/review-learning/review-points.js

@@ -0,0 +1,14 @@
+/**
+ * The points a person makes in a review body: its bullet and numbered lines, each cut to its first
+ * line. One reader for the backtest's ledger and the learner, so both see the same points.
+ */
+const BULLET = /^\s*(?:[-*]|\d+[.)])\s+(.{8,})$/;
+/** The bullet and numbered lines of a review body: the points a reviewer makes outside any one line. */
+export function bodyPoints(body) {
+    return body.split('\n').map(l => BULLET.exec(l)?.[1]).filter((l) => !!l).map(firstLine);
+}
+/** A comment's first non-empty line, markup removed, at most 140 characters. */
+export function firstLine(text) {
+    const line = text.split('\n').find(l => l.trim())?.replace(/[*_`#]/g, '').trim() ?? '';
+    return line.length > 140 ? `${line.slice(0, 137)}...` : line;
+}

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

@@ -0,0 +1,14 @@
+import type { ReviewLesson } from './lessons.js';
+/** One model call: the prompt in, the answer text out, or undefined when it could not run (learning never fails on it). */
+export type RuleWriter = (prompt: string) => Promise<string | undefined>;
+/**
+ * The points as the rules the model wrote: a point it called no rule is kept and marked so (never
+ * promoted again), a point it did not answer is kept as it was (a failed call never loses evidence), and
+ * the person's words stay in the evidence. A rule about a file keeps that file only when the point was already about it.
+ */
+export declare function rulesFromReviews(lessons: ReviewLesson[], write: RuleWriter): Promise<{
+    lessons: ReviewLesson[];
+    rules: number;
+    dropped: number;
+    unanswered: number;
+}>;