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

package/dist/index.d.ts

@@ -49,7 +49,7 @@ export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspens
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH, type LastReport } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact, type ReviewRecord } from './review/reviewer/record.js';
-export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, acceptSuggestedText, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath, type ReviewLesson, type LessonEvidence } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';

package/dist/index.js

@@ -47,7 +47,7 @@ export { decideCompiledCheck, proposeCompiledChecks, readCompiledChecks, suspens
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
 export { backtestLast, formatLast, scoreLast, LAST_LEDGER_PATH } from './review/backtest-last.js';
 export { buildRecord, recordLines, recordIntact } from './review/reviewer/record.js';
-export { readLessons, writeLessons, decideLesson, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
+export { readLessons, writeLessons, decideLesson, acceptSuggestedText, lessonState, pendingDecision, matchLessons, lessonText, lessonsPath } from './review-learning/lessons.js';
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
 export { recordAgentWrites, captureHumanEdits } from './review-learning/human-edits.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';

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

@@ -39,8 +39,9 @@ export async function learnFromReviews(cwd, options) {
     }
     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);
+    // Comments read before go through too: each lands on its own lesson (mergeLessons matches the comment), which
+    // takes the text this version derives from it. Nothing is added twice.
+    const merged = mergeLessons(readLessons(cwd), lessons);
     // 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]));

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

@@ -18,7 +18,7 @@ import type { Git, ReviewBody, ReviewComment } from './acted-on.js';
  *             until a person promotes it.
  * A record from before evidence kinds has none: it is a `point`.
  */
-export type EvidenceKind = 'point' | 'outcome' | 'counter' | 'correction' | 'accepted' | 'rejected' | 'norule' | 'followup' | 'lines' | 'dismissed' | 'against' | 'demoted' | 'reclassified' | 'compiled';
+export type EvidenceKind = 'point' | 'outcome' | 'counter' | 'correction' | 'accepted' | 'rejected' | 'norule' | 'followup' | 'lines' | 'dismissed' | 'against' | 'demoted' | 'reclassified' | 'compiled' | 'reworded';
 export interface LessonEvidence {
     kind?: EvidenceKind;
     pr: number;
@@ -50,6 +50,13 @@ export interface ReviewLesson {
     /** Which evidence made it a lesson. */
     promotedBy?: 'outcome' | 'correction' | 'person' | 'recurrence' | 'legacy';
     evidence: LessonEvidence[];
+    /**
+     * A corrected wording a newer version derived from the lesson's own comment, waiting for a person. A lesson
+     * a person decided keeps the wording they decided on until they take this one (acceptSuggestedText).
+     */
+    suggestedText?: string;
+    /** Why there is a suggestion: `parser fix`, a newer version reading the comment better. */
+    suggestedWhy?: string;
     /** Where the point sits in the commit it was made on, for outcome evidence (inline comments only). */
     at?: {
         commit: string;
@@ -65,7 +72,10 @@ export interface ReviewLesson {
  * evidence, never a promotion. 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. */
+/**
+ * The point of a review comment: its bold title, else its first sentence and, when that only says what is
+ * wrong, the first later sentence that says what to do. 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[];
@@ -78,8 +88,8 @@ export declare function lessonFromComment(git: Git, comment: ReviewComment, at?:
  */
 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
+ * Add lessons to the store. The same lesson again (isSameLesson: the same text, the same review
+ * comment, or the same file with two shared symbols) adds evidence; acted on in enough PRs, it is
  * verified.
  */
 export declare function mergeLessons(existing: ReviewLesson[], incoming: ReviewLesson[]): {
@@ -118,6 +128,8 @@ export declare function pendingDecision(lesson: ReviewLesson): LessonEvidence |
 export declare function writeLessons(cwd: string, lessons: ReviewLesson[]): void;
 /** 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' | 'dismissed', by: string, why?: string): ReviewLesson | undefined;
+/** A person takes a decided lesson's suggested wording; who and the wording it replaced are kept as evidence. */
+export declare function acceptSuggestedText(cwd: string, id: string, by: 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;
 /** The meaningful words of a text or an identifier: `hasLaterAttempt` and "a later attempt" share later and attempt. */

package/dist/review-learning/lessons.js

@@ -15,7 +15,7 @@
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
-import { bodyPoints } from './review-points.js';
+import { bodyPoints, withoutEmphasis } from './review-points.js';
 const STORE = path.join('.rigour', 'review-lessons.json');
 const MAX_TEXT = 220;
 const MAX_SYMBOLS = 8;
@@ -69,7 +69,12 @@ export function lessonState(lesson) {
     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. */
+/** A sentence that tells the author what to do, not only what is wrong. */
+const INSTRUCTION = /^(?:please\s+)?(?:use|pick|avoid|don'?t|do not|never|always|make|keep|move|read|filter|check|change|drop|add|remove|pass|split|prefer|replace|rename|derive|select|return|validate|extract|bound|lock)\b|\b(?:should|must|instead)\b/i;
+/**
+ * The point of a review comment: its bold title, else its first sentence and, when that only says what is
+ * wrong, the first later sentence that says what to do. Without tool output or markup.
+ */
 export function lessonText(body) {
     const cleaned = body
         .replace(/<!--[\s\S]*?-->/g, '')
@@ -80,8 +85,10 @@ export function lessonText(body) {
         .filter(line => !/^\s*#*\s*\**\s*(low|medium|high|critical)\s+severity\s*\**\s*$/i.test(line))
         .join('\n');
     const bold = /\*\*(.+?)\*\*/.exec(cleaned)?.[1]?.trim();
-    const text = bold || cleaned.replace(/\s+/g, ' ').trim().split(/(?<=[.!?])\s/)[0] || '';
-    return pointText(text.replace(/[*_]/g, '')).slice(0, MAX_TEXT).trim();
+    const sentences = cleaned.replace(/\s+/g, ' ').trim().split(/(?<=[.!?])\s/);
+    const instruction = INSTRUCTION.test(sentences[0] ?? '') ? undefined : sentences.slice(1).find(s => INSTRUCTION.test(s));
+    const text = bold || [sentences[0] ?? '', instruction ?? ''].filter(Boolean).join(' ');
+    return pointText(withoutEmphasis(text)).slice(0, MAX_TEXT).trim();
 }
 /**
  * A point's words without a review bot's scaffolding (`In src/a.ts around lines 10-12:`), or '' when
@@ -130,7 +137,7 @@ export function lessonFromComment(git, comment, at = new Date().toISOString()) {
  */
 export function lessonsFromReview(review, changedAfter, at = new Date().toISOString()) {
     return bodyPoints(review.body).flatMap((point, i) => {
-        const text = pointText(point.replace(/[*_]/g, '')).slice(0, MAX_TEXT).trim();
+        const text = pointText(withoutEmphasis(point)).slice(0, MAX_TEXT).trim();
         if (text.length < 12)
             return [];
         const named = /(?:^|[\s`(])((?:[\w.-]+\/)+[\w.-]+\.\w+)/.exec(point)?.[1];
@@ -143,18 +150,15 @@ export function lessonsFromReview(review, changedAfter, at = new Date().toISOStr
     });
 }
 /**
- * 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
+ * Add lessons to the store. The same lesson again (isSameLesson: the same text, the same review
+ * comment, or the same file with two shared symbols) adds evidence; acted on in enough PRs, it is
  * verified.
  */
 export function mergeLessons(existing, incoming) {
     const lessons = existing.map(l => ({ ...l, evidence: [...l.evidence] }));
     let added = 0;
     for (const lesson of incoming) {
-        // 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)));
+        const same = lessons.find(l => isSameLesson(l, lesson));
         if (!same) {
             lessons.push({ ...lesson, evidence: [...lesson.evidence] });
             added++;
@@ -163,6 +167,7 @@ export function mergeLessons(existing, incoming) {
         for (const e of lesson.evidence)
             if (!same.evidence.some(x => x.comment === e.comment && x.kind === e.kind))
                 same.evidence.push(e);
+        refreshText(same, lesson);
         same.updatedAt = lesson.updatedAt;
     }
     let verified = 0;
@@ -174,6 +179,49 @@ export function mergeLessons(existing, incoming) {
     }
     return { lessons, added, verified };
 }
+/** Whether a lesson carries the review point `point` (the same comment on the same pull request). */
+function hasPoint(lesson, point) {
+    return lesson.evidence.some(x => x.kind === 'point' && x.pr === point.pr && x.comment === point.comment);
+}
+/** A person accepted, rejected or dismissed it, or approved or took back a check compiled from it. */
+function decidedByPerson(lesson) {
+    return lesson.evidence.some(e => e.kind === 'accepted' || e.kind === 'rejected' || e.kind === 'dismissed' || e.kind === 'compiled');
+}
+/**
+ * Re-read from the comment it was learned from, an undecided lesson takes the text this version derives; its id
+ * and evidence stay. One a person decided keeps the wording they decided on, and the new one waits as a
+ * suggestion for them. A later comment merged into a lesson never rewrites it.
+ */
+function refreshText(stored, lesson) {
+    const origin = stored.evidence.find(e => e.kind === 'point');
+    if (stored.id === lesson.id || !origin || !hasPoint(lesson, origin))
+        return;
+    if (lesson.text === stored.text) {
+        delete stored.suggestedText;
+        delete stored.suggestedWhy;
+    }
+    else if (decidedByPerson(stored)) {
+        stored.suggestedText = lesson.text;
+        stored.suggestedWhy = 'parser fix';
+    }
+    else
+        stored.text = lesson.text;
+}
+/**
+ * The same lesson: the same id; the same review comment read again, whatever text an earlier version took from it;
+ * shared names on another pull request (two points on one pull request are two points); or a team standard in the
+ * same words.
+ */
+function isSameLesson(stored, lesson) {
+    if (stored.id === lesson.id)
+        return true;
+    if (stored.evidence.some(e => e.kind === 'point' && hasPoint(lesson, e)))
+        return true;
+    const otherPr = !stored.evidence.some(e => lesson.evidence.some(x => x.pr === e.pr));
+    if (stored.file === lesson.file && shared(stored.symbols, lesson.symbols) >= 2 && otherPr)
+        return true;
+    return !stored.file && !lesson.file && sameWords(stored.text, lesson.text);
+}
 /**
  * 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
@@ -278,6 +326,21 @@ export function decideLesson(cwd, id, decision, by, why = '') {
     writeLessons(cwd, lessons);
     return lesson;
 }
+/** A person takes a decided lesson's suggested wording; who and the wording it replaced are kept as evidence. */
+export function acceptSuggestedText(cwd, id, by) {
+    const lessons = readLessons(cwd);
+    const lesson = lessons.find(l => l.id === id);
+    if (!lesson?.suggestedText)
+        return undefined;
+    const at = new Date().toISOString();
+    lesson.evidence.push({ kind: 'reworded', pr: lesson.evidence[0]?.pr ?? 0, comment: `reworded-${at}`, author: by, detail: `${lesson.suggestedWhy ?? 'reworded'}; was: ${lesson.text}`, at });
+    lesson.text = lesson.suggestedText;
+    delete lesson.suggestedText;
+    delete lesson.suggestedWhy;
+    lesson.updatedAt = at;
+    writeLessons(cwd, lessons);
+    return lesson;
+}
 /** An identifier specific enough to link two pieces of code: camelCase, snake_case, or long. */
 export function isSpecific(symbol) {
     return /[a-z][A-Z]|[A-Za-z]_[A-Za-z]/.test(symbol) || symbol.length >= 10;

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

@@ -1,4 +1,6 @@
 /** 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. */
+/** Markdown emphasis off, never the underscores of an identifier (`RESTOCK_CHUNK`) or anything inside a code span. */
+export declare function withoutEmphasis(text: string): string;
+/** A comment's first non-empty line, heading marks and emphasis removed, at most 140 characters. */
 export declare function firstLine(text: string): string;

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

@@ -7,8 +7,13 @@ const BULLET = /^\s*(?:[-*]|\d+[.)])\s+(.{8,})$/;
 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. */
+/** Markdown emphasis off, never the underscores of an identifier (`RESTOCK_CHUNK`) or anything inside a code span. */
+export function withoutEmphasis(text) {
+    return text.split(/(`[^`]*`)/).map(part => part.startsWith('`') ? part
+        : part.replace(/\*+/g, '').replace(/(^|[^\w])__?(?=\S)(.*?\S)__?(?=[^\w]|$)/g, '$1$2')).join('');
+}
+/** A comment's first non-empty line, heading marks and emphasis removed, at most 140 characters. */
 export function firstLine(text) {
-    const line = text.split('\n').find(l => l.trim())?.replace(/[*_`#]/g, '').trim() ?? '';
+    const line = withoutEmphasis(text.split('\n').find(l => l.trim())?.replace(/^\s*#+\s*/, '') ?? '').trim();
     return line.length > 140 ? `${line.slice(0, 137)}...` : line;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.11.0",
+  "version": "6.11.1-rc.1",
   "description": "Rigour's review engine: deterministic gates on changed lines, rules and lessons learned from your team's fixes, and per-check precision from what you fix versus dismiss, across TypeScript, JavaScript, Python, Go, Ruby and C#.",
   "engines": {
     "node": ">=22.13"
@@ -75,11 +75,11 @@
     "@anthropic-ai/sdk": "^0.132.1",
     "pg": "^8.16.3",
     "openai": "^5.23.2",
-    "@rigour-labs/brain-darwin-arm64": "6.11.0",
-    "@rigour-labs/brain-darwin-x64": "6.11.0",
-    "@rigour-labs/brain-linux-arm64": "6.11.0",
-    "@rigour-labs/brain-win-x64": "6.11.0",
-    "@rigour-labs/brain-linux-x64": "6.11.0"
+    "@rigour-labs/brain-darwin-arm64": "6.11.1-rc.1",
+    "@rigour-labs/brain-darwin-x64": "6.11.1-rc.1",
+    "@rigour-labs/brain-linux-x64": "6.11.1-rc.1",
+    "@rigour-labs/brain-linux-arm64": "6.11.1-rc.1",
+    "@rigour-labs/brain-win-x64": "6.11.1-rc.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",