@rigour-labs/core 6.7.5 → 6.7.6

package/dist/index.d.ts

@@ -39,6 +39,7 @@ export { routeFiles, type RouterPolicy, type RouterStats } from './deep/router.j
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns, type DeepRun, type DeepRunSummary } from './review/deep-runs.js';
 export { learnFromReviews, type LearnFromReviewsOptions, type LearnFromReviewsResult } from './review-learning/learn-from-reviews.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { buildRecord, recordLines, recordIntact, type ReviewRecord } from './review/reviewer/record.js';
 export { readLessons, writeLessons, decideLesson, lessonState, 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';

package/dist/index.js

@@ -39,6 +39,7 @@ export { routeFiles } from './deep/router.js';
 export { appendDeepRun, readDeepRuns, summarizeDeepRuns } from './review/deep-runs.js';
 export { learnFromReviews } from './review-learning/learn-from-reviews.js';
 export { ruleWriterFor } from './review/reviewer/rule-writer.js';
+export { buildRecord, recordLines, recordIntact } from './review/reviewer/record.js';
 export { readLessons, writeLessons, decideLesson, lessonState, 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';

package/dist/review/backtest-judges.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { formatJudges, judgedFrom } from './backtest-judges.js';
-const base = { outcome: 'findings', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reviewers: ['claude', 'codex'], cached: false };
+const base = { outcome: 'findings', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [], dropped: [], dismissed: [], reviewers: ['claude', 'codex'], cached: false };
 describe('measuring each judge', () => {
     it('computes Cohen\'s kappa between two judges: 1 in full agreement, 0 at chance, and says when they share blind spots', () => {
         const round = (claude, codex) => ({ judges: { judges: ['claude', 'codex'], caught: { claude, codex }, points: ['p1', 'p2', 'p3', 'p4'], runs: 2 }, points: [] });

package/dist/review/backtest.js

@@ -197,7 +197,7 @@ async function collectItems(worktree, round, config, reviewer, exec, progress) {
         return { items, reviewerError: result.reason ?? result.outcome };
     // The reviewer behind each catch is part of the score, so the gate is `reviewer:<name>`.
     const asReviewerItem = (item, blocking) => ({ gate: `reviewer:${item.reviewer ?? result.reviewers[0]}`, file: item.file ?? '', line: item.line, text: [item.issue, item.consequence, item.evidence].filter(Boolean).join(' '), blocking });
-    items.push(...result.items.map(i => asReviewerItem(i, true)), ...[...result.unverified, ...result.notes, ...result.disputed].map(i => asReviewerItem(i, false)));
+    items.push(...result.items.map(i => asReviewerItem(i, true)), ...[...result.advisory, ...result.unverified, ...result.notes, ...result.disputed].map(i => asReviewerItem(i, false)));
     const judged = judgedFrom(result);
     return { items, ...(judged ? { judged } : {}) };
 }

package/dist/review/reviewer/background.js

@@ -44,7 +44,7 @@ export async function backgroundReview(cwd, job, config, exec = defaultExec, log
         store.recordAttempt(job.branch, { head: job.head, outcome: 'skipped', reason: skip, at: new Date().toISOString() });
         log(`review of ${job.head.slice(0, 9)}: skipped (${skip})`);
         clearPid(store, job.branch);
-        return { outcome: 'skipped', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason: skip, reviewers: [], cached: false };
+        return { outcome: 'skipped', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [], dropped: [], dismissed: [], reason: skip, reviewers: [], cached: false };
     }
     const worktree = store.worktreeDir(job.head);
     const added = await exec('git', ['worktree', 'add', '--detach', worktree, job.head], { cwd, timeoutMs: 5 * GH_TIMEOUT_MS });

package/dist/review/reviewer/context.d.ts

@@ -2,7 +2,7 @@ import { type LessonMode } from '../../review-learning/team-lessons.js';
 import type { RouterPolicy } from '../../deep/router.js';
 import type { PanelItem } from './panel.js';
 import { type Exec } from './exec.js';
-import type { OpenItem } from './verdict.js';
+import type { OpenItem, ServedRule } from './verdict.js';
 export declare const REVIEW_DISMISSALS: string;
 export interface ReviewDismissal {
     id: string;
@@ -59,6 +59,8 @@ export declare function buildContext(input: ContextInput): {
     text: string;
     key: string;
     risky: number | undefined;
+    rules: ServedRule[];
+    lessons: number;
 };
 /**
  * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one

package/dist/review/reviewer/context.js

@@ -15,6 +15,7 @@ import path from 'path';
 import { createHash } from 'crypto';
 import { buildReviewTask } from '../review-task.js';
 import { describeLesson, lessonsForDiff, lessonView, rejectedForDiff } from '../../review-learning/team-lessons.js';
+import { rulesForDiff } from '../../review-learning/repo-rules.js';
 import { reviewedKeys } from '../ledger.js';
 import { textSimilarity } from './consensus.js';
 import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
@@ -23,6 +24,8 @@ export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.js
 const MAX_DOCS = 10;
 /** Team standards a judge is shown with the lessons about the changed files. */
 const JUDGE_STANDARDS = 15;
+/** Rules from the repository's own rules files a judge is asked to answer, most relevant first. */
+const JUDGE_RULES = 15;
 const MAX_SETTLED = 40;
 export function readReviewDismissals(cwd) {
     try {
@@ -78,8 +81,10 @@ export function buildContext(input) {
     const lessons = input.lessons === 'off' ? [] : lessonsForDiff(input.cwd, input.diff, input.lessons, JUDGE_STANDARDS).map(lessonView);
     if (lessons.length)
         sections.push(`## Lessons this team taught on earlier reviews, for what this change touches (context: a lesson never blocks on its own; a finding still needs its quote)\n${lessons.map(l => `- ${describeLesson(l)}`).join('\n')}`);
-    if (task?.rules.length)
-        sections.push(`## Repository rules that name what this change touches\n${task.rules.map(r => `- ${r.source}: ${r.text}`).join('\n')}`);
+    // The repository's own rules, always: the reviewer is the boundary, and what the team wrote is the standard it checks.
+    const rules = rulesForDiff(input.cwd, input.diff, true, JUDGE_RULES).map((r) => ({ id: r.id, source: r.source, text: r.text, requirement: r.requirement }));
+    if (rules.length)
+        sections.push(`## Rules this repository wrote for itself that apply to this change (answer every one in rules, by id)\n${rules.map(r => `- [${r.id}] (${r.source}, ${r.requirement ? 'requirement' : 'guidance'}) ${r.text}`).join('\n')}`);
     if (input.checks.length)
         sections.push(`## Already found by Rigour's checks: they block on their own, so do not report them again\n${input.checks.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}`);
     const rejected = input.lessons === 'off' ? [] : rejectedForDiff(input.cwd, input.diff).map(l => {
@@ -95,7 +100,7 @@ export function buildContext(input) {
     if (docs.length)
         sections.push(`## Docs that describe the changed code (read one when its claim matters to a finding)\n${docs.map(d => `- ${d.doc} (names ${d.names.join(', ')})`).join('\n')}`);
     const text = sections.length ? `# What this team already knows\n\n${sections.join('\n\n')}\n` : 'none\n';
-    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined };
+    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined, rules, lessons: lessons.length };
 }
 function where(x) {
     return x.file ? `${x.file}${x.line ? `:${x.line}` : ''}` : '(no file)';

package/dist/review/reviewer/context.test.js

@@ -35,6 +35,8 @@ describe('what the judges are told the team knows', () => {
             expect(told()).not.toContain('Log the save id');
             expect(told('all')).toContain('Log the save id on failure.');
             expect(told('off')).not.toContain('idempotent');
+            fs.writeFileSync(path.join(repo, 'AGENTS.md'), '- Every call to `save` in `src/a.ts` must be idempotent on retry.\n');
+            expect(told()).toMatch(/## Rules this repository wrote for itself[^\n]*\n- \[[0-9a-f]{10}\] \(AGENTS\.md, requirement\) Every call to `save` in `src\/a\.ts` must be idempotent on retry\./);
         }
         finally {
             fs.rmSync(repo, { recursive: true, force: true });

package/dist/review/reviewer/prompt.js

@@ -111,12 +111,18 @@ Do these steps in order. Report only what you verified in the code, with file:li
    reviewers asked for before; it is not a finding by itself. When the change does repeat it, write
    the finding as for any other miss (input, consequence, quote), naming the lesson in why.
 
-10. Review the diff the way the human reviewers do: correctness, production cost, dead code and
+10. Repository rules. For EVERY rule listed under "Rules this repository wrote for itself" in the
+   team knowledge file, say in rules, by the rule's id, whether this change follows it, breaks it,
+   or does not apply to it. For a break give file, line and quote: the code that breaks it, copied
+   exactly. Judge each rule as written, never widened. A rule marked requirement, broken, with its
+   quote verified, blocks; guidance broken is shown as a should-fix.
+
+11. Review the diff the way the human reviewers do: correctness, production cost, dead code and
    unreferenced exports (a test is not a consumer), code duplicated across sibling routes or
    runners, links or ids built outside the helper that owns them, and the repository's rules.
 
-The lists from steps 2-9 are your working notes: people see them, and they never block on their
-own. A miss blocks only when you also put it in findings, with all three of:
+The lists from steps 2-10 are your working notes: people see them, and they never block on their
+own, with one exception: a requirement rule you mark broken, with its quote verified, blocks. A miss blocks only when you also put it in findings, with all three of:
 - input: the concrete input, state or sequence that goes wrong (a user edits, a retry, two runs at once);
 - consequence: what goes wrong for that input, or the cost (reads, calls or memory per what);
 - quote: the code at file:line that does it, copied exactly from the file (one to three lines).
@@ -155,6 +161,7 @@ Your final message must be ONLY this JSON, starting with { and ending with }, no
  "siblings":[{"changed":"file:line","sibling":"file:line","needs_same_change":true|false,"has_it":true|false,"why":"..."}],
  "claims":[{"source":"comment"|"description","claim":"...","file":"<code that contradicts it>","line":0,"holds":true|false,"evidence":"..."}],
  "lessons":[{"lesson":"<the lesson as listed>","applies":true|false,"file":"...","line":0,"evidence":"..."}],
+ "rules":[{"id":"<the rule's id as listed>","status":"followed"|"broken"|"not-applicable","file":"...","line":0,"quote":"<when broken: the code that breaks it, copied exactly>","evidence":"..."}],
  "findings":[{"class":"...","severity":"blocking"|"should","file":"...","line":0,"issue":"...","why":"...","input":"...","consequence":"<wrong outcome for that input, or the cost; empty for an opinion>","quote":"<the code at file:line, copied exactly>","absent":"<for a missing call or check: the exact text that is missing>"}],
  "carried":["<delta mode: ids of previous open items that still stand>"],
  "resolved_previous":[{"id":"<delta mode: id of a previous open item now fixed>","evidence":"file:line and the fix"}]}`;
@@ -162,7 +169,7 @@ Your final message must be ONLY this JSON, starting with { and ending with }, no
 export function deltaBlock(previousHead, previousVerdict, previousOpenFile, commitsFile, deltaDiffFile, settledFile) {
     return `- DELTA MODE. The previous verdict on ${previousHead.slice(0, 9)} is at ${previousVerdict}; its open
   items, each with an id, are in ${previousOpenFile}. Only the commits in ${commitsFile} are new;
-  their diff is ${deltaDiffFile}. Do steps 1-10 on that diff and on every file an open item names.
+  their diff is ${deltaDiffFile}. Do steps 1-11 on that diff and on every file an open item names.
   Then, for EVERY previous open item: put its id in "carried" if it still stands, or in
   "resolved_previous" with the fix quoted at file:line. An id you leave out is treated as still open.
   Human points the previous verdict resolved, whose files these commits do not touch, are in

package/dist/review/reviewer/record.d.ts

@@ -0,0 +1,71 @@
+import type { Accounting, OpenItem, Verdict } from './verdict.js';
+export interface ReviewRecord {
+    version: 1;
+    head: string;
+    base: string;
+    scope: 'full' | 'delta';
+    at: string;
+    judges: Array<{
+        reviewer: string;
+        version?: string;
+        model?: string;
+        cost_usd?: number;
+        turns?: number;
+    }>;
+    /** Checked by Rigour against the checkout. */
+    verified: {
+        blocking: OpenItem[];
+        should_fix: OpenItem[];
+        /** The repository's own rules served to the judge, and its answers. */
+        rules: {
+            served: number;
+            followed: number;
+            broken: number;
+            not_applicable: number;
+        };
+        /** The team's lessons served, and how many the judge found the change repeats. */
+        lessons: {
+            served: number;
+            applied: number;
+        };
+        prior_points: {
+            open: number;
+            resolved: number;
+            answer_in_reply: number;
+        };
+        unverified: number;
+        notes: number;
+        disputed: number;
+    };
+    /** Recorded as reported, not checked by Rigour. */
+    reported: {
+        human_reviews: number;
+    };
+    /** Decisions people made. */
+    people: {
+        dismissed: number;
+    };
+    /** sha256 of everything above, keys sorted, so a copy can be checked against the original. */
+    integrity: string;
+}
+export interface RecordInput {
+    head: string;
+    base: string;
+    scope: 'full' | 'delta';
+    verdict: Verdict;
+    accounted: Accounting & {
+        disputed: OpenItem[];
+        dismissed: OpenItem[];
+    };
+    judges: ReviewRecord['judges'];
+    lessonsServed: number;
+    humanReviews: number;
+    at?: string;
+}
+export declare function buildRecord(input: RecordInput): ReviewRecord;
+/** The hash a record's integrity field must equal; a record whose hash differs was changed after Rigour wrote it. */
+export declare function integrityOf(body: Omit<ReviewRecord, 'integrity'>): string;
+/** Checks that a record's contents hash to its integrity field. */
+export declare function recordIntact(record: ReviewRecord): boolean;
+/** The record as a pull request summary shows it: blocks in full, a few should-fixes, the counts, the judges, the hash. */
+export declare function recordLines(r: ReviewRecord, shouldFixShown?: number): string[];

package/dist/review/reviewer/record.js

@@ -0,0 +1,69 @@
+/**
+ * The record of one review: what Rigour checked against the checkout, what it could only record as
+ * reported, who decided what, and who judged, with an integrity hash so a copy can be checked against
+ * the original. Nothing in it rests on a judge's word alone: every blocking or should-fix item here
+ * passed the quote check, and every rule and lesson count comes from what Rigour served and the
+ * answers it kept. The receipt a pull request carries is built from this.
+ */
+import { createHash } from 'crypto';
+export function buildRecord(input) {
+    const rules = input.verdict.rules ?? [];
+    const lessons = input.verdict.lessons ?? [];
+    const body = {
+        version: 1,
+        head: input.head,
+        base: input.base,
+        scope: input.scope,
+        at: input.at ?? new Date().toISOString(),
+        judges: input.judges,
+        verified: {
+            blocking: input.accounted.open,
+            should_fix: input.accounted.advisory,
+            rules: { served: rules.length, followed: rules.filter(r => r.status === 'followed').length, broken: rules.filter(r => r.status === 'broken').length, not_applicable: rules.filter(r => r.status === 'not-applicable').length },
+            lessons: { served: input.lessonsServed, applied: lessons.filter(l => l.applies === true).length },
+            prior_points: { open: input.accounted.open.filter(i => i.kind === 'prior').length, resolved: input.accounted.resolved.length, answer_in_reply: input.accounted.answerInReply.length },
+            unverified: input.accounted.unverified.length,
+            notes: input.accounted.notes.length,
+            disputed: input.accounted.disputed.length,
+        },
+        reported: { human_reviews: input.humanReviews },
+        people: { dismissed: input.accounted.dismissed.length },
+    };
+    return { ...body, integrity: integrityOf(body) };
+}
+/** The hash a record's integrity field must equal; a record whose hash differs was changed after Rigour wrote it. */
+export function integrityOf(body) {
+    return createHash('sha256').update(canonical(body)).digest('hex');
+}
+/** Checks that a record's contents hash to its integrity field. */
+export function recordIntact(record) {
+    const { integrity, ...body } = record;
+    return integrityOf(body) === integrity;
+}
+/** JSON with every object's keys sorted and, as JSON itself does, no undefined members: a record read back from disk hashes the same. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(v => canonical(v === undefined ? null : v)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).filter(k => object[k] !== undefined).sort().map(k => `${JSON.stringify(k)}:${canonical(object[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** The record as a pull request summary shows it: blocks in full, a few should-fixes, the counts, the judges, the hash. */
+export function recordLines(r, shouldFixShown = 5) {
+    const where = (i) => `${i.file ? `\`${i.file}${i.line ? `:${i.line}` : ''}\` ` : ''}${i.issue}${i.locations?.length ? ` (also ${i.locations.map(l => `\`${l.file}${l.line ? `:${l.line}` : ''}\``).join(', ')})` : ''}`;
+    const v = r.verified;
+    const lines = [`**Review record** · ${v.blocking.length} blocking · ${v.should_fix.length} should-fix · rules ${v.rules.followed} followed, ${v.rules.broken} broken, ${v.rules.not_applicable} not applicable of ${v.rules.served} · lessons ${v.lessons.applied} of ${v.lessons.served} apply · prior points ${v.prior_points.open} open, ${v.prior_points.resolved} resolved`];
+    for (const i of v.blocking)
+        lines.push(`- **Blocking** ${where(i)}`);
+    for (const i of v.should_fix.slice(0, shouldFixShown))
+        lines.push(`- Should fix: ${where(i)}`);
+    if (v.should_fix.length > shouldFixShown)
+        lines.push(`- …and ${v.should_fix.length - shouldFixShown} more should-fix in the record.`);
+    const folded = [[v.notes, 'working note'], [v.disputed, 'disputed'], [v.unverified, 'unverified'], [r.people.dismissed, 'dismissed']].filter(([n]) => n > 0);
+    if (folded.length)
+        lines.push(`Also seen, never blocking: ${folded.map(([n, w]) => `${n} ${w}${n === 1 || w === 'disputed' || w === 'unverified' || w === 'dismissed' ? '' : 's'}`).join(', ')}.`);
+    lines.push(`Judged by ${r.judges.map(j => `${j.reviewer}${j.version ? ` ${j.version}` : ''}${j.model ? ` (${j.model})` : ''}${typeof j.cost_usd === 'number' ? ` $${j.cost_usd.toFixed(2)}` : ''}`).join(', ') || 'no judge'} on \`${r.head.slice(0, 9)}\` against \`${r.base.slice(0, 9)}\` (${r.scope}); ${r.reported.human_reviews} human review(s) seen. Integrity \`${r.integrity.slice(0, 16)}\`.`);
+    return lines;
+}

package/dist/review/reviewer/record.test.d.ts

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

package/dist/review/reviewer/record.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { buildRecord, recordIntact, recordLines } from './record.js';
+const item = (over) => ({ id: 'i1', kind: 'finding', class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'return 1;', ...over });
+const input = () => ({
+    head: 'abcdef0123456789', base: '0123456789abcdef', scope: 'full',
+    verdict: { prior_points: [], redundant: [], reads: [], scans: [], merge_impact: [], findings: [], carried: [], resolved_previous: [],
+        rules: [{ id: 'r1', status: 'followed' }, { id: 'r2', status: 'broken' }, { id: 'r3', status: 'not-applicable' }], lessons: [{ lesson: 'bound the window', applies: true }, { lesson: 'keyset', applies: false }] },
+    accounted: { open: [item({}), item({ id: 'p1', kind: 'prior', class: 'prior point', issue: 'take the lock' })], advisory: [item({ id: 's1', issue: 'could log the id' })], unverified: [item({ id: 'u1' })], notes: [item({ id: 'n1' }), item({ id: 'n2' })], resolved: [{ item: item({ id: 'old' }), evidence: 'fixed' }], answerInReply: [], disputed: [], dismissed: [item({ id: 'd1' })] },
+    judges: [{ reviewer: 'claude', version: '2.1.0', model: 'opus', cost_usd: 1.25, turns: 19 }],
+    lessonsServed: 4, humanReviews: 2, at: '2026-10-08T00:00:00Z',
+});
+describe('the review record', () => {
+    it('counts what was verified, what was reported and what people decided, and hashes it', () => {
+        const record = buildRecord(input());
+        expect(record.verified).toMatchObject({ rules: { served: 3, followed: 1, broken: 1, not_applicable: 1 }, lessons: { served: 4, applied: 1 }, prior_points: { open: 1, resolved: 1, answer_in_reply: 0 }, unverified: 1, notes: 2, disputed: 0 });
+        expect(record.verified.blocking).toHaveLength(2);
+        expect(record.verified.should_fix).toHaveLength(1);
+        expect(record).toMatchObject({ reported: { human_reviews: 2 }, people: { dismissed: 1 }, judges: [{ reviewer: 'claude', turns: 19 }] });
+        expect(record.integrity).toMatch(/^[0-9a-f]{64}$/);
+        expect(buildRecord(input()).integrity).toBe(record.integrity); // the same review hashes the same
+        expect(recordIntact(record)).toBe(true);
+        expect(recordIntact({ ...record, verified: { ...record.verified, blocking: [] } })).toBe(false); // a block removed after the fact shows
+    });
+    it('renders for a pull request: blocks in full, a few should-fixes, the counts, the judges and the hash', () => {
+        const lines = recordLines(buildRecord(input()), 1);
+        expect(lines[0]).toBe('**Review record** · 2 blocking · 1 should-fix · rules 1 followed, 1 broken, 1 not applicable of 3 · lessons 1 of 4 apply · prior points 1 open, 1 resolved');
+        expect(lines).toContain('- **Blocking** `src/job.ts:2` returns before the lock');
+        expect(lines).toContain('- Should fix: `src/job.ts:2` could log the id');
+        expect(lines.at(-2)).toBe('Also seen, never blocking: 2 working notes, 1 unverified, 1 dismissed.');
+        expect(lines.at(-1)).toMatch(/^Judged by claude 2\.1\.0 \(opus\) \$1\.25 on `abcdef012` against `012345678` \(full\); 2 human review\(s\) seen\. Integrity `[0-9a-f]{16}`\.$/);
+    });
+});

package/dist/review/reviewer/store.d.ts

@@ -37,6 +37,8 @@ export declare class VerdictStore {
     /** Adds runs and reported dollars to today's log: an append, so the background reviewer and a person's run never lose each other's count. */
     addSpend(runs: number, usd: number | undefined, day?: string): void;
     private spendFile;
+    /** The record of the review (record.ts), beside its verdict. */
+    recordPath(verdictPath: string): string;
     /** The decision a verdict led to (what blocks, what is disputed or a note), kept so the same commit is not decided again. */
     decidedPath(verdictPath: string): string;
     /** A review on the branch that ended without a verdict, and why: what the status shows instead of "no verdict yet". */

package/dist/review/reviewer/store.js

@@ -77,6 +77,10 @@ export class VerdictStore {
     spendFile(day) {
         return path.join(this.dir, 'spend', `${day}.jsonl`);
     }
+    /** The record of the review (record.ts), beside its verdict. */
+    recordPath(verdictPath) {
+        return verdictPath.replace(/\.json$/, '.record.json');
+    }
     /** The decision a verdict led to (what blocks, what is disputed or a note), kept so the same commit is not decided again. */
     decidedPath(verdictPath) {
         return verdictPath.replace(/\.json$/, '.decided.json');

package/dist/review/reviewer/usage.test.js

@@ -3,7 +3,7 @@ import { reviewerUsage } from './usage.js';
 const item = { id: 'abcdef0123', kind: 'finding', class: 'correctness', file: 'src/secret-path.ts', line: 2, issue: 'private text' };
 describe('reviewer usage telemetry', () => {
     it('reports counts and buckets only: never file names, finding text or ids', () => {
-        const result = { outcome: 'findings', items: [item], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [item, item], dropped: [], dismissed: [], reviewers: ['claude', 'codex', 'cursor'], scope: 'delta', cached: false, costUsd: 0.7, runs: 5,
+        const result = { outcome: 'findings', items: [item], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [item, item], dropped: [], dismissed: [], reviewers: ['claude', 'codex', 'cursor'], scope: 'delta', cached: false, costUsd: 0.7, runs: 5,
             mode: { asked: 'panel', ran: 'panel', source: 'team', escalation: '2 risky changed function(s)' } };
         const usage = reviewerUsage(result, 'push');
         expect(usage).toEqual({ outcome: 'findings', trigger: 'push', scope: 'delta', asked: 'panel', ran: 'panel', source: 'team', degraded: false, escalation: 'all-judges', refused: 0, judges: 3, cached: false, confirmed: 1, disputed: 2, dropped: 0, notes: 0, dismissed: 0, runs: 5, cost_bucket: '$0.50-2' });

package/dist/review/reviewer/verdict.d.ts

@@ -94,6 +94,29 @@ interface LessonCheck {
     evidence?: string;
     reviewer?: string;
 }
+/** A rule Rigour served to the judge from the repository's own rules files, by id. */
+export interface ServedRule {
+    id: string;
+    source: string;
+    text: string;
+    requirement: boolean;
+}
+/**
+ * The judge's answer for one served rule: followed, broken (with the code that breaks it) or not applicable.
+ * `rule`, `source` and `requirement` are filled in by Rigour from what it served, never taken from the judge.
+ */
+export interface RuleCheck {
+    id: string;
+    status: 'followed' | 'broken' | 'not-applicable';
+    file?: string;
+    line?: number;
+    quote?: string;
+    evidence?: string;
+    reviewer?: string;
+    rule?: string;
+    source?: string;
+    requirement?: boolean;
+}
 export interface Finding {
     class: string;
     file: string;
@@ -118,6 +141,7 @@ export interface Verdict {
     siblings?: Sibling[];
     claims?: Claim[];
     lessons?: LessonCheck[];
+    rules?: RuleCheck[];
     findings: Finding[];
     carried: string[];
     resolved_previous: Array<{
@@ -143,7 +167,7 @@ export interface Verdict {
 }
 export interface OpenItem {
     id: string;
-    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'journey' | 'sibling' | 'claim' | 'lesson' | 'finding';
+    kind: 'prior' | 'redundant' | 'read' | 'scan' | 'merge' | 'journey' | 'sibling' | 'claim' | 'lesson' | 'rule' | 'finding';
     class: string;
     file?: string;
     line?: number;
@@ -157,6 +181,11 @@ export interface OpenItem {
     reviewer?: string;
     /** In delta mode, how the item reached this verdict. */
     status?: 'carried' | 'not accounted for';
+    /** The same point made elsewhere: one item per root cause, every place it was found. */
+    locations?: Array<{
+        file: string;
+        line?: number;
+    }>;
 }
 /** Checks a file (and a line, and a quote of the code there) against the checkout; an item that fails cannot block. */
 export type Verify = (file: string, line: number | undefined, quote?: string) => boolean;
@@ -196,8 +225,12 @@ export interface Accounting {
     answerInReply: PriorPoint[];
     /** Findings with no wrong outcome and no cost (an opinion): shown, never a block, however many judges agree. */
     notes: OpenItem[];
+    /** Should-fixes the judge could show (a verified quote): worth a person's time, never a block. */
+    advisory: OpenItem[];
 }
 /** Everything the reviewers reported blocks; in delta mode, previous open items carry unless resolved with evidence. */
 export declare function account(verdict: Verdict, previousOpen: OpenItem[] | undefined, verify: Verify): Accounting;
 export declare function itemLine(item: OpenItem): string;
+/** The rules Rigour served, onto the judge's answers by id: an answer naming no served rule is dropped. */
+export declare function attachServedRules(verdict: Verdict, served: ServedRule[]): void;
 export {};

package/dist/review/reviewer/verdict.js

@@ -49,7 +49,7 @@ const ACCEPTED_SIMILARITY = 0.4;
 /** The reviewer's working steps: shown so a person can follow the reasoning, never a block on their own. */
 const WORKING_NOTES = new Set(['redundant', 'read', 'scan', 'merge', 'journey', 'sibling', 'claim', 'lesson']);
 const SHAPE = ['prior_points', 'reads', 'findings'];
-const LISTS = ['redundant', 'scans', 'merge_impact', 'journey', 'siblings', 'claims', 'lessons', 'carried', 'resolved_previous'];
+const LISTS = ['redundant', 'scans', 'merge_impact', 'journey', 'siblings', 'claims', 'lessons', 'rules', 'carried', 'resolved_previous'];
 /** The verdict in a reviewer's answer, or why it is not one. `needsPriorPoints`: a human review exists and none of its points is carried. */
 export function parseVerdict(text, needsPriorPoints, reviewer, spend) {
     const parsed = verdictIn(text);
@@ -106,6 +106,7 @@ export function mergeVerdicts(parts) {
         siblings: tagged(part => part.siblings ?? []),
         claims: tagged(part => part.claims ?? []),
         lessons: tagged(part => part.lessons ?? []),
+        rules: tagged(part => part.rules ?? []),
         findings: tagged(part => part.findings),
         carried: parts.flatMap(part => part.carried),
         resolved_previous: parts.length === 1 ? parts[0].resolved_previous : parts[0].resolved_previous.filter(x => parts.every(part => part.resolved_previous.some(y => y.id === x.id))),
@@ -138,8 +139,16 @@ export function account(verdict, previousOpen, verify) {
     const open = [];
     const unverified = [];
     const notes = [];
+    const advisory = [];
     const seen = new Set();
     const accepted = verdict.prior_points.filter(p => p.severity === 'non-blocking');
+    // A should-fix is shown only when the judge could show it: a quote Rigour finds. One that cannot be checked is not a claim worth a person's time.
+    const advise = (item) => {
+        if (seen.has(item.id))
+            return;
+        seen.add(item.id);
+        (!!item.file && !!item.quote?.trim() && verify(item.file, item.line, item.quote) ? advisory : unverified).push(item);
+    };
     // A prior point is the human's and needs no file. A finding blocks only when the code it quotes is at the line it
     // names: any model's claim is checked, never trusted. What the working steps turned up is a note: the reasoning,
     // shown, and a block only when the judge also makes it a finding it can quote.
@@ -210,6 +219,17 @@ export function account(verdict, previousOpen, verify) {
             continue;
         add({ id: id('team-lesson', l.file, l.lesson), kind: 'lesson', class: 'team-lesson', file: l.file, line: l.line, issue: `repeats a team lesson: ${l.lesson}`, evidence: l.evidence, reviewer: l.reviewer });
     }
+    // A rule the repository wrote for itself, broken: a requirement blocks where the judge quotes the code that
+    // breaks it (checked like any quote); guidance broken is shown. The rule's words and weight are Rigour's, not the judge's.
+    for (const r of verdict.rules ?? []) {
+        if (r.status !== 'broken' || !r.rule)
+            continue;
+        const item = { id: id('repo-rule', r.file, r.id), kind: 'rule', class: 'repo-rule', file: r.file, line: r.line, issue: `breaks a rule this repository wrote for itself (${r.source}): ${r.rule}`, consequence: r.requirement ? 'the team wrote this rule as a requirement' : 'the team wrote this rule as guidance', ...(r.quote ? { quote: r.quote } : {}), evidence: r.evidence, reviewer: r.reviewer };
+        if (r.requirement)
+            add(item);
+        else
+            advise(item);
+    }
     const stillOpen = new Set((previousOpen ?? []).map(item => item.id));
     for (const f of verdict.findings) {
         const item = { id: id(f.class, f.file, f.issue), kind: 'finding', class: f.class, file: f.file, line: f.line, issue: f.issue, evidence: f.why, ...(f.consequence?.trim() ? { consequence: f.consequence.trim() } : {}), ...(f.input?.trim() ? { input: f.input.trim() } : {}), ...(f.quote?.trim() ? { quote: f.quote } : {}), reviewer: f.reviewer };
@@ -225,10 +245,14 @@ export function account(verdict, previousOpen, verify) {
                 unverified.push(item);
             seen.add(item.id);
         }
-        else if (!opinion && !should)
+        else if (opinion) {
+            if (!notes.some(n => n.id === item.id))
+                notes.push(item);
+        }
+        else if (should)
+            advise(item);
+        else
             add(item);
-        else if (!notes.some(n => n.id === item.id))
-            notes.push(item);
     }
     const resolved = [];
     if (previousOpen) {
@@ -248,11 +272,39 @@ export function account(verdict, previousOpen, verify) {
             }
         }
     }
-    return { open, unverified, resolved, answerInReply, notes };
+    return { open: onePerRootCause(open), unverified, resolved, answerInReply, notes, advisory: onePerRootCause(advisory) };
+}
+/** How alike two items' words must be to be the same point made in two places. */
+const SAME_POINT = 0.6;
+/**
+ * The same point found in several places is one item carrying every location, so a person reads one
+ * line, not one per file. Blocking is unchanged: the item blocks until every location is fixed.
+ */
+function onePerRootCause(items) {
+    const kept = [];
+    for (const item of items) {
+        const same = item.kind === 'prior' ? undefined : kept.find(k => k.kind !== 'prior' && k.class === item.class && textSimilarity(k, item) >= SAME_POINT);
+        if (!same) {
+            kept.push(item);
+            continue;
+        }
+        if (item.file)
+            (same.locations ??= []).push({ file: item.file, ...(item.line ? { line: item.line } : {}) });
+    }
+    return kept;
 }
 export function itemLine(item) {
     const where = item.file ? ` ${item.file}${item.line ? `:${item.line}` : ''}` : '';
     const by = item.reviewer ? ` (${item.reviewer})` : '';
     const status = item.status ? `, ${item.status}` : '';
-    return `[${item.class}${status}]${by}${where} ${item.issue}${item.input ? `\n      input: ${item.input}` : ''}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.quote ? `\n      code: ${item.quote.trim().split('\n')[0].slice(0, 160)}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
+    const also = item.locations?.length ? `\n      also at ${item.locations.map(l => `${l.file}${l.line ? `:${l.line}` : ''}`).join(', ')}` : '';
+    return `[${item.class}${status}]${by}${where} ${item.issue}${also}${item.input ? `\n      input: ${item.input}` : ''}${item.consequence ? `\n      consequence: ${item.consequence}` : ''}${item.quote ? `\n      code: ${item.quote.trim().split('\n')[0].slice(0, 160)}` : ''}${item.evidence ? `\n      ${item.evidence}` : ''}`;
+}
+/** The rules Rigour served, onto the judge's answers by id: an answer naming no served rule is dropped. */
+export function attachServedRules(verdict, served) {
+    const byId = new Map(served.map(r => [r.id, r]));
+    verdict.rules = (verdict.rules ?? []).flatMap(r => {
+        const rule = byId.get(String(r.id));
+        return rule ? [{ ...r, id: rule.id, rule: rule.text, source: rule.source, requirement: rule.requirement }] : [];
+    });
 }

package/dist/review/reviewer.d.ts

@@ -3,6 +3,7 @@ import { type ReviewerName, type Tokens } from './reviewer/adapters.js';
 import { type Exec, type Progress } from './reviewer/exec.js';
 import { type PanelItem } from './reviewer/panel.js';
 import { type RunChoice, type Source } from './reviewer/settings.js';
+import { type ReviewRecord } from './reviewer/record.js';
 import { type Accounting, type OpenItem, type PriorPoint } from './reviewer/verdict.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays, type Exec, type Progress } from './reviewer/exec.js';
 export { itemLine, type OpenItem } from './reviewer/verdict.js';
@@ -43,6 +44,8 @@ export interface ReviewerResult {
     answerInReply: PriorPoint[];
     /** Findings with no wrong outcome and no cost: shown, never a block. */
     notes: OpenItem[];
+    /** Should-fixes with a verified quote: shown, capped, never a block. */
+    advisory: OpenItem[];
     /** Panel findings without a majority: shown, never a block, not carried to the next round. */
     disputed: OpenItem[];
     /** Panel findings refuted with evidence: logged, never a block. */
@@ -57,6 +60,16 @@ export interface ReviewerResult {
     scope?: 'full' | 'delta';
     why?: string;
     costUsd?: number;
+    /** The repository's own rules the judge answered, and how. */
+    rules?: {
+        checked: number;
+        followed: number;
+        broken: number;
+        notApplicable: number;
+    };
+    /** The record of this review (record.ts) and where it is kept, beside the verdict. */
+    record?: ReviewRecord;
+    recordPath?: string;
     /** Tokens every run reported, summed: the only measure of a CLI that reports no dollars (Codex). */
     tokens?: Tokens;
     /** Whether the team lets people dismiss these findings (review.reviewer.dismissals). */

package/dist/review/reviewer.js

@@ -32,7 +32,8 @@ import { VerdictStore } from './reviewer/store.js';
 import { trackUsage } from '../telemetry/telemetry.js';
 import { reviewerUsage } from './reviewer/usage.js';
 import { buildContext, dismissedAs, readReviewDismissals, relatedDocs } from './reviewer/context.js';
-import { account, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { buildRecord } from './reviewer/record.js';
+import { account, attachServedRules, checkoutVerifier, carryResolved, evidenceTouched, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 import { judgeUnset } from './reviewer/judge-env.js';
 export { defaultExec, githubEnv, githubToken, parseJsonArrays } from './reviewer/exec.js';
 export { itemLine } from './reviewer/verdict.js';
@@ -64,7 +65,7 @@ async function review(cwd, base, config, exec, progress, options) {
     const none = (outcome, reason, extra = {}) => {
         if (attempts && branch !== 'HEAD')
             attempts.recordAttempt(branch, { head, outcome, reason, at: new Date().toISOString() });
-        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra, mode: { ...modeRecord, ...extra.mode, ran: 'none' } };
+        return { outcome, items: [], unverified: [], resolved: [], answerInReply: [], notes: [], advisory: [], disputed: [], dropped: [], dismissed: [], reason, reviewers: [], cached: false, ...extra, mode: { ...modeRecord, ...extra.mode, ran: 'none' } };
     };
     if (!head || !baseSha)
         return none('unavailable', `not a repository, or ${base} is unknown`);
@@ -119,8 +120,12 @@ async function review(cwd, base, config, exec, progress, options) {
     if (!options.force && previous?.head === head && previous.inputsKey === inputsKey && fs.existsSync(store.decidedPath(previous.verdict))) {
         const verdict = store.readJson(previous.verdict);
         const decided = store.readJson(store.decidedPath(previous.verdict));
-        if (verdict && decided)
-            return result(redismiss(decided, dismissals), verdict, verdict.inputs?.reviewers ?? reviewers, previous.mode, 'same commit and inputs as the last verdict', true, reviews, pr, verdict.inputs?.mode ?? modeRecord, settings.dismissals);
+        if (verdict && decided) {
+            // The record written with that verdict; a verdict from before records has none.
+            const recordPath = store.recordPath(previous.verdict);
+            const record = store.readJson(recordPath);
+            return { ...result(redismiss(decided, dismissals), verdict, verdict.inputs?.reviewers ?? reviewers, previous.mode, 'same commit and inputs as the last verdict', true, reviews, pr, verdict.inputs?.mode ?? modeRecord, settings.dismissals), ...(record ? { record, recordPath } : {}) };
+        }
     }
     // What the team already knows, for every judge; built once, and its risk count decides escalation.
     const fullDiff = (await exec('git', ['diff', `${baseSha}...HEAD`], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout;
@@ -174,9 +179,20 @@ async function review(cwd, base, config, exec, progress, options) {
     const openFile = store.openPath(verdictFile);
     const previousOpen = scope === 'delta' ? store.readJson(store.openPath(previous.verdict)) ?? [] : undefined;
     const verify = checkoutVerifier(cwd);
+    const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
+    // The record of the review, written beside the verdict once and rebuilt from the same verdict on a cached read.
+    const withRecord = (accounted, verdict, cached) => {
+        const res = result(accounted, verdict, reviewers, scope, why, cached, reviews, pr, modeRecord, settings.dismissals);
+        const judges = (verdict.reviewers ?? []).map(r => ({ reviewer: r.reviewer, ...(installed.get(r.reviewer)?.version ? { version: installed.get(r.reviewer).version } : {}), ...(modelFor(r.reviewer) ? { model: modelFor(r.reviewer) } : {}), ...(typeof r.cost_usd === 'number' ? { cost_usd: r.cost_usd } : {}), ...(r.trace?.turns ? { turns: r.trace.turns } : {}) }));
+        const recordPath = store.recordPath(verdictFile);
+        const record = (cached && store.readJson(recordPath)) || buildRecord({ head, base: baseSha, scope, verdict, accounted, judges, lessonsServed: context.lessons, humanReviews: reviews.count });
+        if (!cached || !fs.existsSync(recordPath))
+            store.writeJson(recordPath, record);
+        return { ...res, record, recordPath };
+    };
     if (!options.force && fs.existsSync(verdictFile) && fs.existsSync(openFile)) {
         const verdict = store.readJson(verdictFile);
-        return result(decide(verdict, previousOpen, verify, dismissals), verdict, reviewers, scope, why, true, reviews, pr, modeRecord, settings.dismissals);
+        return withRecord(decide(verdict, previousOpen, verify, dismissals), verdict, true);
     }
     // The daily caps, before any judge starts: a cached or reused verdict above cost nothing and never reaches here.
     const over = overBudget(store.spend(), settings, reviewers.length);
@@ -216,7 +232,6 @@ async function review(cwd, base, config, exec, progress, options) {
         }
         const prompt = renderPrompt({ repoRoot, branch, head: head.slice(0, 9), base, baseSha, mode: scope, reviewsFile, humanCount: reviews.count, prBodyFile, diffstatFile, diffFile, hintsFile, contextFile, deltaBlock: delta, mergeBlock: merge });
         progress(`Rigour reviewer: reviewing ${head.slice(0, 9)} against ${base} (${scope}: ${why}; ${reviews.count} human review(s), written by ${[...authors].join(', ') || 'a person'}) with ${reviewers.join(', ')}`);
-        const modelFor = (name) => settings.models[name] ?? (name === 'claude' ? settings.model : undefined);
         const started = Date.now();
         const ticker = setInterval(() => progress(`Rigour reviewer: still working (${Math.round((Date.now() - started) / 60_000)} min)`), PROGRESS_EVERY_MS);
         let parts;
@@ -242,9 +257,11 @@ async function review(cwd, base, config, exec, progress, options) {
             if (failed && 'error' in failed)
                 return none('unavailable', failed.error, { reviewers, scope, why, pr: pr?.number });
             parts = answers.map(a => a.verdict);
-            for (const part of parts)
+            for (const part of parts) {
                 if (part.trace)
                     labelReads(part.trace, work, changedFiles);
+                attachServedRules(part, context.rules);
+            }
         }
         finally {
             clearInterval(ticker);
@@ -293,7 +310,7 @@ async function review(cwd, base, config, exec, progress, options) {
         store.writeJson(store.decidedPath(verdictFile), accounted);
         if (branch !== 'HEAD')
             store.recordBranch(branch, { head, verdict: verdictFile, mode: scope, rulesHash, reviewsKey: reviews.key, inputsKey });
-        return result(accounted, verdict, reviewers, scope, why, false, reviews, pr, modeRecord, settings.dismissals);
+        return withRecord(accounted, verdict, false);
     }
     finally {
         fs.rmSync(work, { recursive: true, force: true });
@@ -397,6 +414,7 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         resolved: accounted.resolved,
         answerInReply: accounted.answerInReply,
         notes: accounted.notes,
+        advisory: accounted.advisory,
         disputed: accounted.disputed,
         dropped: accounted.dropped,
         dismissed: accounted.dismissed,
@@ -407,6 +425,7 @@ function result(accounted, verdict, reviewers, scope, why, cached, reviews, pr,
         ...(cost.length ? { costUsd: cost.reduce((a, b) => a + b, 0) } : {}),
         ...(used.length ? { tokens: used.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output }), { input: 0, output: 0 }) } : {}),
         runs: (verdict.reviewers ?? []).length,
+        ...(verdict.rules?.length ? { rules: { checked: verdict.rules.length, followed: verdict.rules.filter(r => r.status === 'followed').length, broken: verdict.rules.filter(r => r.status === 'broken').length, notApplicable: verdict.rules.filter(r => r.status === 'not-applicable').length } } : {}),
         mode,
         dismissable,
         cached,

package/dist/review/reviewer.test.js

@@ -8,7 +8,8 @@ import { reviewerBlocks, runReviewer } from './reviewer.js';
 import { dismissReviewerFinding } from './reviewer/context.js';
 import { reviewStatus } from './reviewer/background.js';
 import { selectReviewers, vendorsOf } from './reviewer/adapters.js';
-import { account, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { account, attachServedRules, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { recordIntact } from './reviewer/record.js';
 let repo;
 const config = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'] } } });
 const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
@@ -231,6 +232,30 @@ describe('the reviewer', () => {
         expect(verdict.reviewers[0].trace).toMatchObject({ turns: 5, usage: { input: 5, cacheRead: 500, cacheWrite: 50, output: 25 } });
         expect(verdict.reviewers[0].trace.calls.map((c) => c.category)).toEqual(['rigour-input', 'changed-file', 'other-file', 'git', 'search']);
     });
+    it('serves the repository\'s own rules to the judge with ids, and blocks on a requirement the judge shows broken', async () => {
+        fs.writeFileSync(path.join(repo, 'AGENTS.md'), '# Rules\n\n- `src/job.ts` must take the lock before its first read.\n- Prefer early returns.\n');
+        const seen = seenNow();
+        const answer = () => {
+            const id = /- \[([0-9a-f]{10})\] \(AGENTS\.md, requirement\)/.exec(seen.files['team-knowledge.md'] ?? '')?.[1];
+            return JSON.stringify({ ...EMPTY, rules: [{ id, status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', evidence: 'reads before any lock' }] });
+        };
+        const result = await runReviewer(repo, 'main', config, fakes(answer, seen), () => undefined, { force: true });
+        expect(seen.files['team-knowledge.md']).toContain('(AGENTS.md, requirement) `src/job.ts` must take the lock before its first read.');
+        expect(result.items.map(i => [i.class, i.file, i.line])).toEqual([['repo-rule', 'src/job.ts', 2]]);
+        expect(result.rules).toEqual({ checked: 1, followed: 0, broken: 1, notApplicable: 0 });
+    });
+    it('writes the record of the review beside the verdict, intact, and returns the same record on a cached read', async () => {
+        const seen = seenNow();
+        const answer = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', input: 'two runs', consequence: 'two emails', quote: 'return 1;', severity: 'blocking' }] });
+        const first = await runReviewer(repo, 'main', config, fakes(() => answer, seen), () => undefined);
+        expect(first.record).toMatchObject({ scope: 'full', verified: { blocking: [expect.objectContaining({ issue: 'returns before the lock' })], should_fix: [] }, reported: { human_reviews: 1 }, judges: [expect.objectContaining({ reviewer: 'claude', cost_usd: 1.5 })] });
+        expect(first.recordPath).toMatch(/\.record\.json$/);
+        const onDisk = JSON.parse(fs.readFileSync(first.recordPath, 'utf8'));
+        expect(recordIntact(onDisk)).toBe(true);
+        const again = await runReviewer(repo, 'main', config, fakes(() => { throw new Error('a cached read never runs a judge'); }, seen), () => undefined);
+        expect(again.cached).toBe(true);
+        expect(again.record?.integrity).toBe(first.record?.integrity);
+    });
     it('asks a judge once more after an answer that is not a verdict, and is unavailable only when the second is not one either', async () => {
         const seen = seenNow();
         let calls = 0;
@@ -351,9 +376,43 @@ describe('verdicts', () => {
         const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'job never closes the connection', input: 'every run', consequence: 'one connection leaks per run', quote: 'return 1;' };
         expect(decide({ findings: [{ ...finding, absent: 'return 1' }] })).toMatchObject({ open: [], unverified: [expect.anything()] }); // "missing", but the file has it
         expect(decide({ findings: [{ ...finding, absent: 'conn.close(' }] }).open).toHaveLength(1);
-        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], notes: [expect.anything()] });
+        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], advisory: [expect.anything()], unverified: [] }); // a verified should-fix: shown
+        expect(decide({ findings: [{ ...finding, severity: 'should', quote: 'return 99;' }] })).toMatchObject({ open: [], advisory: [], unverified: [expect.anything()] }); // a should-fix it cannot show: not a claim worth time
         const accepted = { point: 'job never closes the connection after the read', severity: 'non-blocking', resolved: false };
-        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], notes: [expect.anything()] }); // a human raised it and accepted it
+        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], advisory: [expect.anything()] }); // a human raised it and accepted it
+    });
+    it('blocks on a broken requirement rule only with its quote, shows broken guidance, and takes the rule\'s words from what Rigour served', () => {
+        const verify = checkoutVerifier(repo);
+        const served = [
+            { id: 'r1', source: 'AGENTS.md', text: 'Every job must take the lock before its first read.', requirement: true },
+            { id: 'r2', source: 'AGENTS.md', text: 'Prefer small functions.', requirement: false },
+        ];
+        const judged = (answers) => {
+            const verdict = { ...EMPTY, prior_points: [], rules: answers };
+            attachServedRules(verdict, served);
+            return { verdict, ...account(verdict, undefined, verify) };
+        };
+        const broken = judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', evidence: 'no lock before the read' }]);
+        expect(broken.open.map(i => [i.kind, i.class, i.issue])).toEqual([['rule', 'repo-rule', 'breaks a rule this repository wrote for itself (AGENTS.md): Every job must take the lock before its first read.']]);
+        expect(judged([{ id: 'r1', status: 'broken', file: 'src/job.ts', line: 2 }])).toMatchObject({ open: [], unverified: [expect.objectContaining({ kind: 'rule' })] }); // no quote: not shown as a block
+        expect(judged([{ id: 'r2', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;' }])).toMatchObject({ open: [], advisory: [expect.objectContaining({ class: 'repo-rule' })] }); // guidance: shown, never a block
+        expect(judged([{ id: 'r1', status: 'followed' }, { id: 'r1', status: 'not-applicable' }])).toMatchObject({ open: [], notes: [], advisory: [], unverified: [] });
+        const unknown = judged([{ id: 'made-up', status: 'broken', file: 'src/job.ts', line: 2, quote: 'return 1;', rule: 'a rule the judge invented', requirement: true }]);
+        expect(unknown.verdict.rules).toEqual([]); // an answer naming no served rule is dropped, whatever it claims
+        expect(unknown.open).toEqual([]);
+    });
+    it('shows the same point found in several places as one item with every location, and never merges human points', () => {
+        const scan = (file, line, quote) => ({ class: 'production-cost', file, line, issue: `the ${file.split('/').pop()} scan has no upper bound on updated_at`, input: 'a week of rows', consequence: 'rows read grow with time', quote });
+        const verdict = { ...EMPTY, prior_points: [
+                { point: 'bound the window', severity: 'blocking', resolved: false, file: 'src/job.ts', line: 1, quote: 'export function job() {' },
+                { point: 'bound the window again', severity: 'blocking', resolved: false, file: 'src/job.ts', line: 1, quote: 'export function job() {' },
+            ], findings: [scan('src/job.ts', 1, 'export function job() {'), scan('a.ts', 1, 'export const a = 1;'), { ...scan('src/job.ts', 2, 'return 1;'), class: 'correctness' }] };
+        const { open } = account(verdict, undefined, checkoutVerifier(repo));
+        expect(open.map(i => [i.kind, i.class, i.locations ?? []])).toEqual([
+            ['prior', 'prior point', []], ['prior', 'prior point', []],
+            ['finding', 'production-cost', [{ file: 'a.ts', line: 1 }]], // the same point in another file: one item, both places
+            ['finding', 'correctness', []], // a different class is a different point
+        ]);
     });
     it('keeps reads, scans, redundancy and merge impact as notes with stable ids, and answers non-blocking points in the reply', () => {
         const verdict = {

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

@@ -103,3 +103,5 @@ export declare function writeLessons(cwd: string, lessons: ReviewLesson[]): void
 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;
+/** The meaningful words of a text or an identifier: `hasLaterAttempt` and "a later attempt" share later and attempt. */
+export declare function meaningfulWords(text: string): string[];

package/dist/review-learning/lessons.js

@@ -191,10 +191,10 @@ export function matchLessons(lessons, change, options = {}) {
         .sort((a, b) => b.score - a.score || b.lesson.evidence.length - a.lesson.evidence.length);
     // 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 changeWords = new Set([...change.files.flatMap(f => f.split(/[/._-]+/)), ...change.symbols].flatMap(meaningfulWords));
     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 }))
+        .map(l => ({ lesson: l, shared: new Set(meaningfulWords(l.text)).size === 0 ? 0 : [...new Set(meaningfulWords(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)
@@ -251,7 +251,7 @@ function sameWords(a, b) {
     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) {
+export function meaningfulWords(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. */

package/dist/review-learning/repo-rules.d.ts

@@ -1,16 +1,18 @@
 export interface RepoRule {
+    /** Stable across runs: the source file and the rule's words. */
+    id: string;
     source: string;
     text: string;
     /** Paths the rule names (files or directories). */
     paths: string[];
     /** Identifiers the rule names. */
     symbols: string[];
+    /** Worded as a requirement: a break can block. Guidance otherwise: a break is shown. */
+    requirement: boolean;
 }
 export declare function readRepoRules(cwd: string): RepoRule[];
 /** One rule per top-level bullet or paragraph; headings and import lines are not rules. */
 export declare function splitRules(source: string, text: string): RepoRule[];
-/** Rules that name a path the change touches, or a specific identifier in it; most specific first. */
-export declare function rulesForChange(rules: RepoRule[], files: string[], symbols: Set<string>): RepoRule[];
 export declare function rulesSection(rules: RepoRule[]): string;
-/** The rules that apply to a diff's changed files and added identifiers. */
-export declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean): RepoRule[];
+/** The rules that apply to a diff's changed files and added identifiers, the top `limit`. */
+export declare function rulesForDiff(cwd: string, diff: string, enabled?: boolean, limit?: number): RepoRule[];

package/dist/review-learning/repo-rules.js

@@ -10,11 +10,16 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { isSpecific } from './lessons.js';
+import crypto from 'crypto';
+import { isSpecific, meaningfulWords } from './lessons.js';
 const RULE_FILES = ['AGENTS.md', 'CLAUDE.md', '.github/copilot-instructions.md'];
 const RULE_DIRS = ['.cursor/rules'];
 const MAX_RULE_CHARS = 600;
 const MAX_RULES = 5;
+/** A paragraph that continues the rule before it (its reason, how to apply it, an example) rather than a rule of its own. */
+const CONTINUES = /^\**\s*(why|how to apply|example|examples|evidence|exception|exceptions|fix|note)\b\s*:?\**\s*:?/i;
+/** Worded as a requirement: the team said must, never, always, only, every, do not. A rule without these is guidance. */
+const REQUIREMENT = /\b(must|never|always|only|every|do not|don't|forbidden|required|non-negotiable)\b/i;
 export function readRepoRules(cwd) {
     const files = [
         ...RULE_FILES.filter(f => fs.existsSync(path.join(cwd, f))),
@@ -45,21 +50,39 @@ export function splitRules(source, text) {
         }
     }
     flush();
-    return blocks.map(block => ({
+    // A "Why:" or "How to apply:" paragraph belongs to the rule above it: alone it is not checkable.
+    const merged = [];
+    for (const block of blocks) {
+        if (CONTINUES.test(block) && merged.length)
+            merged[merged.length - 1] = `${merged[merged.length - 1]} ${block}`;
+        else
+            merged.push(block);
+    }
+    return merged.map(block => ({
+        id: crypto.createHash('sha256').update(`${source}\u0000${block.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim()}`).digest('hex').slice(0, 10),
         source,
         text: block.length > MAX_RULE_CHARS ? `${block.slice(0, MAX_RULE_CHARS)}…` : block,
+        requirement: REQUIREMENT.test(block),
         paths: [...new Set([...block.matchAll(/`([\w@.~-]+\/[\w./@*-]*)`/g)].map(m => m[1].replace(/\*.*$/, '').replace(/^\.\//, '')))].filter(Boolean),
         symbols: [...new Set([...block.matchAll(/`([A-Za-z_$][\w$]*)(?:\(\))?`/g)].map(m => m[1]))].filter(isSpecific),
     }));
 }
-/** Rules that name a path the change touches, or a specific identifier in it; most specific first. */
-export function rulesForChange(rules, files, symbols) {
+/**
+ * The rules most likely to apply to a change, most specific first: a rule naming a path the change
+ * touches or an identifier in it ranks above one that only shares words with it (the change's paths
+ * and added names, split into words), and a rule sharing fewer than two words is left out. Ranking,
+ * not filtering: on a large change most rules share some words, so the judge decides applicability
+ * rule by rule from the top `limit`.
+ */
+function rulesForChange(rules, files, symbols, limit = MAX_RULES) {
+    const changeWords = new Set([...files.flatMap(f => f.split(/[/._-]+/)), ...symbols].flatMap(meaningfulWords));
     const scored = rules.map(rule => {
         const pathHits = rule.paths.filter(p => files.some(f => f === p || f.startsWith(p.endsWith('/') ? p : `${p}/`) || f.endsWith(`/${p}`))).length;
         const symbolHits = rule.symbols.filter(s => symbols.has(s)).length;
-        return { rule, score: 3 * pathHits + 2 * symbolHits };
+        const shared = new Set(meaningfulWords(rule.text).filter(w => changeWords.has(w))).size;
+        return { rule, named: 3 * pathHits + 2 * symbolHits, shared };
     });
-    return scored.filter(s => s.score > 0).sort((a, b) => b.score - a.score).slice(0, MAX_RULES).map(s => s.rule);
+    return scored.filter(s => s.named > 0 || s.shared >= 2).sort((a, b) => b.named - a.named || b.shared - a.shared).slice(0, limit).map(s => s.rule);
 }
 export function rulesSection(rules) {
     if (rules.length === 0)
@@ -74,11 +97,11 @@ function listRuleFiles(cwd, dir) {
         return [];
     }
 }
-/** The rules that apply to a diff's changed files and added identifiers. */
-export function rulesForDiff(cwd, diff, enabled = false) {
+/** The rules that apply to a diff's changed files and added identifiers, the top `limit`. */
+export function rulesForDiff(cwd, diff, enabled = false, limit = MAX_RULES) {
     if (!enabled)
         return [];
     const files = [...diff.matchAll(/^\+\+\+ b\/(.+)$/gm)].map(m => m[1].trim());
     const added = diff.split('\n').filter(line => line.startsWith('+') && !line.startsWith('+++')).join('\n');
-    return rulesForChange(readRepoRules(cwd), files, new Set(added.match(/[A-Za-z_$][\w$]*/g) ?? []));
+    return rulesForChange(readRepoRules(cwd), files, new Set(added.match(/[A-Za-z_$][\w$]*/g) ?? []), limit);
 }

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

@@ -28,6 +28,19 @@ describe('repository rules', () => {
         expect(rules.map(r => r.text.slice(0, 30))).toEqual(['**Migrations are append-only.*', 'Every outbound send goes throu', 'Prefer `fetchWithTimeout` over']);
         expect(rules[1]).toMatchObject({ paths: ['src/lib/delivery.ts'], symbols: ['deliverOrder'] });
         expect(rules[0].paths).toEqual(['migrations/']);
+        expect(rules.map(r => r.requirement)).toEqual([true, true, false]); // "never", "every"; "prefer" is guidance
+        expect(rules[0].id).toMatch(/^[0-9a-f]{10}$/);
+        expect(splitRules('AGENTS.md', AGENTS)[0].id).toBe(rules[0].id); // stable across runs
+    });
+    it('keeps a rule\'s "Why" and "How to apply" paragraphs with it, and ranks a rule naming the change above one that only shares its words', () => {
+        const text = '- **Use the design system.** Every control comes from `src/lib/ui`.\n\n**Why:** one source of styling.\n\n**How to apply:** import from `$lib/ui`, never a raw `<button>`.\n\n- Bound both ends of every time window a scheduled job reads.\n\n- Name the index a new query relies on in the migrations.\n';
+        const rules = splitRules('AGENTS.md', text);
+        expect(rules.map(r => r.text.slice(0, 24))).toEqual(['**Use the design system.', 'Bound both ends of every', 'Name the index a new que']);
+        expect(rules[0].text).toContain('**How to apply:**');
+        fs.writeFileSync(path.join(repo, 'AGENTS.md'), text);
+        const change = diff('src/lib/ui/Button.svelte', 'const timeWindow = scheduledJob.readsRows();');
+        expect(rulesForDiff(repo, change, true, 10).map(r => r.text.slice(0, 12))).toEqual(['**Use the de', 'Bound both e']); // the path hit first, then shared words; the index rule shares nothing
+        expect(rulesForDiff(repo, change, true, 1)).toHaveLength(1);
     });
     it('shows only the rules that name what the change touches, and nothing when disabled', () => {
         expect(rulesForDiff(repo, diff('migrations/2026_add.sql', 'alter table x;'), true).map(r => r.text.slice(0, 20))).toEqual(['**Migrations are app']);

package/dist/types/index.js

@@ -324,7 +324,7 @@ export const GatesSchema = z.object({
         timeout_ms: z.number().optional(), // per model call; default: cloud 120s, local 60s, local --max 240s
         budget_ms: z.number().optional(), // whole deep run; files not started in time are reported as skipped
         agentic: z.boolean().optional(), // cloud tier: the model may read the repository while it reviews (default true)
-        repo_rules: z.boolean().optional(), // show the reviewer the rules in AGENTS.md / CLAUDE.md / Cursor rules that name what the change touches (default false)
+        repo_rules: z.boolean().optional(), // show the model review, the agent review list and the stop hook the rules in AGENTS.md / CLAUDE.md / Cursor rules that name what the change touches (default false); the reviewer always checks them
         review_lessons: z.enum(['verified', 'all', 'off']).optional(), // the team's past review lessons: they raise a function's risk and are shown to the reviewer. verified (default), all, or off
         router: z.object({
             enabled: z.boolean().optional(), // default true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.7.5",
+  "version": "6.7.6",
   "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"
@@ -72,11 +72,11 @@
     "@anthropic-ai/sdk": "^0.30.1",
     "pg": "^8.16.3",
     "openai": "^5.23.2",
-    "@rigour-labs/brain-darwin-x64": "6.7.5",
-    "@rigour-labs/brain-linux-arm64": "6.7.5",
-    "@rigour-labs/brain-win-x64": "6.7.5",
-    "@rigour-labs/brain-darwin-arm64": "6.7.5",
-    "@rigour-labs/brain-linux-x64": "6.7.5"
+    "@rigour-labs/brain-darwin-arm64": "6.7.6",
+    "@rigour-labs/brain-darwin-x64": "6.7.6",
+    "@rigour-labs/brain-linux-arm64": "6.7.6",
+    "@rigour-labs/brain-linux-x64": "6.7.6",
+    "@rigour-labs/brain-win-x64": "6.7.6"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",