@rigour-labs/core 6.7.2 → 6.7.4

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;

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;