@rigour-labs/core 6.3.1 → 6.4.0

package/README.md

@@ -26,7 +26,7 @@ The core library powering [Rigour](https://rigour.run) — 27+ quality gates, fi
 - **Dependency bloat** — unused deps, heavy alternatives (moment→dayjs), duplicate purpose packages.
 - **Context-window artifacts**, inconsistent error handling, promise safety, deprecated APIs.
 
-**Semantic Bugs (type-aware, opt-in):** a TypeScript program with the checker and cross-file value tracing proves a defect before reporting it: credentials forwarded on redirect, paged reads aggregated in memory, cached responses that can carry a failure fallback. Rules learned from fixes (`rigour learn`) run alongside them from `.rigour/rules/`.
+**Semantic Bugs (type-aware, on by default):** a TypeScript program with the checker and cross-file value tracing proves a defect before reporting it: credentials forwarded on redirect, paged reads aggregated in memory, cached responses that can carry a failure fallback. Rules learned from fixes (`rigour learn`) run alongside them from `.rigour/rules/`.
 
 **Agent Governance:** Multi-agent scope isolation, EWMA-based checkpoint supervision, context drift, retry loop breaker, memory & skills governance with DLP scanning.
 

package/dist/gates/hallucinated-imports/js-resolver.d.ts

@@ -29,6 +29,13 @@ export interface JsImportContext {
  * Check JavaScript/TypeScript imports in a source file and add hallucinated findings.
  */
 export declare function checkJSImports(content: string, file: string, ctx: JsImportContext): Promise<void>;
+/**
+ * Bundler conventions: a query on a relative import (`./logo.svg?raw`, `./worker.ts?worker`)
+ * names a transform of that file, so the file is what must exist; a `virtual:` module or a
+ * bare specifier with a query (`page.tsx?tsr-split=component`) is produced by a plugin at
+ * build time and cannot be checked. Returns the path to check, or null to skip.
+ */
+export declare function bundlerSpecifier(importPath: string): string | null;
 /**
  * Collect all import statements from JavaScript/TypeScript file content.
  * Handles import, export, require(), and dynamic import() statements.

package/dist/gates/hallucinated-imports/js-resolver.js

@@ -21,7 +21,9 @@ import { loadTsPathConfig } from './tsconfig-paths.js';
 export async function checkJSImports(content, file, ctx) {
     const depsForFile = await resolveJSDepsForFile(file, ctx.cwd, ctx.rootDeps, ctx.depCacheByDir);
     const kitRoot = await ctx.kitRoots.rootFor(file);
-    for (const { importPath, line } of collectJSImportSpecs(content, file)) {
+    for (const spec of collectJSImportSpecs(content, file)) {
+        const { line } = spec;
+        const importPath = bundlerSpecifier(spec.importPath);
         if (!importPath || ctx.shouldIgnore(importPath))
             continue;
         if (kitRoot && isSvelteKitProvided(importPath))
@@ -38,6 +40,20 @@ export async function checkJSImports(content, file, ctx) {
         }
     }
 }
+/**
+ * Bundler conventions: a query on a relative import (`./logo.svg?raw`, `./worker.ts?worker`)
+ * names a transform of that file, so the file is what must exist; a `virtual:` module or a
+ * bare specifier with a query (`page.tsx?tsr-split=component`) is produced by a plugin at
+ * build time and cannot be checked. Returns the path to check, or null to skip.
+ */
+export function bundlerSpecifier(importPath) {
+    if (!importPath || importPath.startsWith('virtual:') || importPath.startsWith('\0'))
+        return null;
+    const query = importPath.search(/[?#]/);
+    if (query < 0)
+        return importPath;
+    return importPath.startsWith('.') ? importPath.slice(0, query) : null;
+}
 async function checkRelativeImport(file, importPath, ctx) {
     if (ctx.resolveRelativeImport(file, importPath, ctx.projectFiles))
         return null;

package/dist/gates/hallucinated-imports-sveltekit.test.js

@@ -106,3 +106,27 @@ describe('HallucinatedImportsGate — tsconfig inheritance and rootDirs', () =>
         expect(await missingImports(cwd)).toContain("'./nowhere'");
     });
 });
+describe('HallucinatedImportsGate — bundler query and virtual imports', () => {
+    let cwd;
+    beforeEach(() => {
+        cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'bundler-imports-'));
+        write(cwd, 'package.json', JSON.stringify({ dependencies: { '@tanstack/react-router': '1.0.0' } }));
+        write(cwd, 'src/logo.svg', '<svg/>');
+        write(cwd, 'src/worker.ts', 'export {};\n');
+    });
+    afterEach(() => { fs.rmSync(cwd, { recursive: true, force: true }); });
+    it('checks the file behind a query and skips plugin-provided modules', async () => {
+        write(cwd, 'src/route.tsx', [
+            "import raw from './logo.svg?raw';",
+            "import Worker from './worker.ts?worker&inline';",
+            "const split = () => import('route.tsx?tsr-split=component');",
+            "import { registerSW } from 'virtual:pwa-register';",
+            'export default { raw, Worker, split, registerSW };',
+        ].join('\n'));
+        expect(await missingImports(cwd)).toBe('');
+    });
+    it('still reports a missing module behind a query', async () => {
+        write(cwd, 'src/route.tsx', "import Worker from './missing-worker.ts?worker';\nexport default Worker;\n");
+        expect(await missingImports(cwd)).toContain('./missing-worker.ts');
+    });
+});

package/dist/gates/semantic-bugs.test.js

@@ -4,6 +4,7 @@ import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { SemanticBugsGate } from './semantic-bugs.js';
 import { GateRunner } from './runner.js';
+import { ConfigSchema } from '../types/index.js';
 const LEAKY = [
     'export async function notify(endpoint: string, signature: string) {',
     "  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });",
@@ -59,12 +60,11 @@ describe('SemanticBugsGate', () => {
         expect(failure.title).toContain('[learned/require-option-redirect-abcd1234]');
         expect(failure.hint).toContain('fix abcdef01 in src/http.ts (post)');
     });
-    it('is off unless enabled in rigour.yml', async () => {
+    it('is on by default and can be turned off in rigour.yml', async () => {
         write('src/notify.ts', LEAKY);
-        const base = { version: 1, commands: {}, gates: { max_file_lines: 500 } };
-        const off = await new GateRunner(base).run(cwd);
-        expect(off.failures.some(f => f.id === 'semantic-bugs')).toBe(false);
-        const on = await new GateRunner({ ...base, gates: { ...base.gates, semantic_bugs: { enabled: true } } }).run(cwd);
+        const on = await new GateRunner(ConfigSchema.parse({ version: 1 })).run(cwd);
         expect(on.failures.some(f => f.id === 'semantic-bugs')).toBe(true);
+        const off = await new GateRunner(ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: false } } })).run(cwd);
+        expect(off.failures.some(f => f.id === 'semantic-bugs')).toBe(false);
     });
 });

package/dist/hooks/index.d.ts

@@ -12,3 +12,5 @@ export { recordDLPFeedback, allowLastDLPBlock, writeDLPBlockManifest, getLearned
 export type { DLPFeedbackEntry, DLPFeedbackStore, DLPBlockManifest } from './dlp-feedback.js';
 export { generateDLPHookFiles } from './dlp-templates.js';
 export type { GeneratedDLPHookFile } from './dlp-templates.js';
+export { stopReview, stopMessage, blocksStop, STOP_MAX_ATTEMPTS } from './stop-review.js';
+export type { StopDecision } from './stop-review.js';

package/dist/hooks/index.js

@@ -9,3 +9,5 @@ export { DEFAULT_HOOK_CONFIG, FAST_GATE_IDS } from './types.js';
 export { scanInputForCredentials, formatDLPAlert, createDLPAuditEntry } from './input-validator.js';
 export { recordDLPFeedback, allowLastDLPBlock, writeDLPBlockManifest, getLearnedAllowCount, loadDLPFeedbackStore, loadDLPFeedbackStoreSync, fingerprintDetection, } from './dlp-feedback.js';
 export { generateDLPHookFiles } from './dlp-templates.js';
+// Stop review ("before you say done")
+export { stopReview, stopMessage, blocksStop, STOP_MAX_ATTEMPTS } from './stop-review.js';

package/dist/hooks/stop-review.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The "before you say done" review: when an agent is about to stop, review the
+ * uncommitted change and, if it introduced serious findings, tell the agent
+ * what to fix instead of letting it finish.
+ *
+ * Only findings that deserve it block: critical ones, and high ones that are
+ * proven (the semantic engine traced them) or security findings. A high
+ * heuristic (a regex that sees `fetch` without `.catch`) is not enough to hold
+ * an agent back; callers also cap the number of attempts.
+ */
+import type { Config, Failure } from '../types/index.js';
+export declare const STOP_MAX_ATTEMPTS = 3;
+export interface StopDecision {
+    block: boolean;
+    /** What the agent is told when blocked; empty otherwise. */
+    message: string;
+    blocking: number;
+    /** Every finding on changed lines, and the files the review covered (for fix capture). */
+    findings: Failure[];
+    reviewedFiles: string[];
+}
+export declare function stopReview(cwd: string, config: Config, attempt: number): Promise<StopDecision>;
+/** Critical, or high and either proven by the semantic engine or a security finding. */
+export declare function blocksStop(finding: Failure): boolean;
+export declare function stopMessage(findings: Failure[], attempt: number): string;

package/dist/hooks/stop-review.js

@@ -0,0 +1,31 @@
+import { reviewChange } from '../review/review.js';
+export const STOP_MAX_ATTEMPTS = 3;
+const MAX_LISTED = 8;
+export async function stopReview(cwd, config, attempt) {
+    const result = await reviewChange({ cwd, config, source: { mode: 'working' } });
+    const blocking = result.findings.filter(blocksStop);
+    const reviewed = { findings: result.findings, reviewedFiles: Object.keys(result.changedLines) };
+    if (blocking.length === 0)
+        return { block: false, message: '', blocking: 0, ...reviewed };
+    return { block: true, message: stopMessage(blocking, attempt), blocking: blocking.length, ...reviewed };
+}
+/** Critical, or high and either proven by the semantic engine or a security finding. */
+export function blocksStop(finding) {
+    const severity = (finding.severity || 'medium');
+    if (severity === 'critical')
+        return true;
+    return severity === 'high' && (finding.verified === true || finding.provenance === 'security');
+}
+export function stopMessage(findings, attempt) {
+    const listed = findings.slice(0, MAX_LISTED).map(f => {
+        const where = `${f.files?.[0] ?? '?'}:${f.line ?? '?'}`;
+        return `- [${(f.severity || 'medium').toUpperCase()}] ${where} ${f.title}${f.hint ? `\n  Fix: ${f.hint}` : ''}`;
+    });
+    const more = findings.length > MAX_LISTED ? [`- …and ${findings.length - MAX_LISTED} more (run \`rigour review\`).`] : [];
+    return [
+        `Rigour review found ${findings.length} serious issue(s) on the lines you changed (attempt ${attempt} of ${STOP_MAX_ATTEMPTS}).`,
+        'Fix them before finishing, or explain why a finding is wrong:',
+        ...listed,
+        ...more,
+    ].join('\n');
+}

package/dist/index.d.ts

@@ -11,6 +11,11 @@ export { FrontendSecretExposureGate } from './gates/frontend-secret-exposure.js'
 export * from './utils/logger.js';
 export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
+export { reviewChange, toReviewFinding, type ReviewInput, type ReviewResult, type ReviewFinding } from './review/review.js';
+export { splitByChangedLines, type ChangedLineSplit } from './review/changed-lines.js';
+export { diffFromGit, GitDiffError, type DiffSource } from './review/git-diff.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
+export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys, type AgentEvent, type ReviewEffectiveness } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
@@ -51,7 +56,7 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
-export { learnFromFix, type LearnReport, type Rejection } from './semantic/learn/learn.js';
+export { learnFromFix, learnFromFileChange, type LearnReport, type Rejection } from './semantic/learn/learn.js';
 export { extractFixTrees, type FixTrees } from './semantic/learn/git-trees.js';
 export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
 export type { LearnedRule, LearnedPattern } from './semantic/learn/types.js';

package/dist/index.js

@@ -11,6 +11,11 @@ export { FrontendSecretExposureGate } from './gates/frontend-secret-exposure.js'
 export * from './utils/logger.js';
 export { normalizeScopePatterns, isScoped } from './utils/scope.js';
 export { deepAnalysisError } from './utils/deep-status.js';
+export { reviewChange, toReviewFinding } from './review/review.js';
+export { splitByChangedLines } from './review/changed-lines.js';
+export { diffFromGit, GitDiffError } from './review/git-diff.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount } from './review/agent-fixes.js';
+export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
@@ -50,7 +55,7 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
-export { learnFromFix } from './semantic/learn/learn.js';
+export { learnFromFix, learnFromFileChange } from './semantic/learn/learn.js';
 export { extractFixTrees } from './semantic/learn/git-trees.js';
 export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';

package/dist/review/agent-fixes.d.ts

@@ -0,0 +1,18 @@
+import type { Failure } from '../types/index.js';
+export interface ResolvedFix {
+    id: string;
+    file: string;
+    rule: string;
+    before: string;
+    after: string;
+    resolvedAt: string;
+}
+export interface FixCapture {
+    opened: number;
+    resolved: number;
+}
+/** Record a review's findings: open new ones, resolve open ones the review no longer reports. */
+export declare function recordReviewOutcome(cwd: string, findings: Failure[], reviewedFiles: string[]): FixCapture;
+export declare function listResolvedFixes(cwd: string): ResolvedFix[];
+export declare function removeResolvedFix(cwd: string, id: string): void;
+export declare function openFindingCount(cwd: string): number;

package/dist/review/agent-fixes.js

@@ -0,0 +1,118 @@
+/**
+ * Fixes agents make to Rigour findings, captured so they can become rules.
+ *
+ * Capture is cheap and happens in the review loop (MCP review, stop hook):
+ * a finding's file content is kept when the finding appears, and when a later
+ * review of that file no longer reports it, the before and after are stored as
+ * a resolved fix. Learning is expensive and happens later, outside the loop
+ * (`rigour learn --agent-fixes`), with the same validation as any learned rule.
+ *
+ * A finding only counts as resolved when its file was part of the review that
+ * no longer reports it: a file committed out of the working tree was not fixed.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+const DIR = path.join('.rigour', 'agent-fixes');
+const MAX_FILE_BYTES = 200_000;
+const OPEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Record a review's findings: open new ones, resolve open ones the review no longer reports. */
+export function recordReviewOutcome(cwd, findings, reviewedFiles) {
+    const open = readOpen(cwd);
+    const current = new Map(findings.flatMap(f => (f.files?.[0] ? [[`${f.id}:${f.files[0]}`, f]] : [])));
+    const capture = { resolved: resolveGone(cwd, open, current, new Set(reviewedFiles)), opened: openNew(cwd, open, current) };
+    writeOpen(cwd, open);
+    return capture;
+}
+/** Open findings this review no longer reports: resolved when their file was reviewed and changed. */
+function resolveGone(cwd, open, current, reviewed) {
+    let resolved = 0;
+    for (const [key, entry] of Object.entries(open)) {
+        if (current.has(key))
+            continue;
+        if (!reviewed.has(entry.file)) {
+            if (Date.now() - Date.parse(entry.openedAt) > OPEN_TTL_MS)
+                delete open[key];
+            continue;
+        }
+        const after = readSmall(cwd, entry.file);
+        if (after !== null && after !== entry.before) {
+            writeResolved(cwd, entry, after);
+            resolved++;
+        }
+        delete open[key];
+    }
+    return resolved;
+}
+function openNew(cwd, open, current) {
+    let opened = 0;
+    for (const [key, finding] of current) {
+        if (open[key])
+            continue;
+        const file = finding.files[0];
+        const before = readSmall(cwd, file);
+        if (before === null)
+            continue;
+        open[key] = { file, rule: finding.id, before, openedAt: new Date().toISOString() };
+        opened++;
+    }
+    return opened;
+}
+export function listResolvedFixes(cwd) {
+    const dir = path.join(cwd, DIR, 'resolved');
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter(n => n.endsWith('.json')).sort().flatMap(name => {
+        try {
+            return [JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function removeResolvedFix(cwd, id) {
+    fs.rmSync(path.join(cwd, DIR, 'resolved', `${id}.json`), { force: true });
+}
+export function openFindingCount(cwd) {
+    return Object.keys(readOpen(cwd)).length;
+}
+function readOpen(cwd) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(cwd, DIR, 'open.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeOpen(cwd, open) {
+    try {
+        fs.mkdirSync(path.join(cwd, DIR), { recursive: true });
+        fs.writeFileSync(path.join(cwd, DIR, 'open.json'), JSON.stringify(open));
+    }
+    catch {
+        // Capture is best-effort; it must never break a review.
+    }
+}
+function writeResolved(cwd, entry, after) {
+    const id = crypto.createHash('sha256').update(`${entry.rule}\0${entry.file}\0${entry.before}\0${after}`).digest('hex').slice(0, 16);
+    const fix = { id, file: entry.file, rule: entry.rule, before: entry.before, after, resolvedAt: new Date().toISOString() };
+    try {
+        fs.mkdirSync(path.join(cwd, DIR, 'resolved'), { recursive: true });
+        fs.writeFileSync(path.join(cwd, DIR, 'resolved', `${id}.json`), JSON.stringify(fix));
+    }
+    catch {
+        // Best-effort, as above.
+    }
+}
+function readSmall(cwd, file) {
+    try {
+        const full = path.join(cwd, file);
+        if (fs.statSync(full).size > MAX_FILE_BYTES)
+            return null;
+        return fs.readFileSync(full, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/review/agent-fixes.test.d.ts

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

package/dist/review/agent-fixes.test.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { listResolvedFixes, openFindingCount, recordReviewOutcome } from './agent-fixes.js';
+const finding = (file) => ({ id: 'semantic-bugs', title: 't', details: 'd', files: [file], line: 2 });
+describe('recordReviewOutcome', () => {
+    let cwd;
+    beforeEach(() => {
+        cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-fixes-'));
+        fs.writeFileSync(path.join(cwd, 'a.ts'), 'before\n');
+    });
+    afterEach(() => { fs.rmSync(cwd, { recursive: true, force: true }); });
+    it('stores the before and after once a reviewed file no longer has the finding', () => {
+        expect(recordReviewOutcome(cwd, [finding('a.ts')], ['a.ts'])).toEqual({ opened: 1, resolved: 0 });
+        fs.writeFileSync(path.join(cwd, 'a.ts'), 'after\n');
+        expect(recordReviewOutcome(cwd, [], ['a.ts'])).toEqual({ opened: 0, resolved: 1 });
+        const [fix] = listResolvedFixes(cwd);
+        expect(fix).toMatchObject({ file: 'a.ts', rule: 'semantic-bugs', before: 'before\n', after: 'after\n' });
+        expect(openFindingCount(cwd)).toBe(0);
+    });
+    it('keeps a finding open when its file was not part of the review (committed, not fixed)', () => {
+        recordReviewOutcome(cwd, [finding('a.ts')], ['a.ts']);
+        expect(recordReviewOutcome(cwd, [], ['other.ts'])).toEqual({ opened: 0, resolved: 0 });
+        expect(openFindingCount(cwd)).toBe(1);
+    });
+    it('does not count a finding that vanished without an edit as a fix', () => {
+        recordReviewOutcome(cwd, [finding('a.ts')], ['a.ts']);
+        expect(recordReviewOutcome(cwd, [], ['a.ts'])).toEqual({ opened: 0, resolved: 0 });
+        expect(listResolvedFixes(cwd)).toEqual([]);
+    });
+});

package/dist/review/changed-lines.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which findings belong to a change.
+ *
+ * - findings: on a changed line; these decide PASS/FAIL.
+ * - fileFindings: about a changed file as a whole (no line); shown as context.
+ * - unlocated: no file at all; counted, never shown as a changed-line finding.
+ * - outside: on an unchanged line; counted.
+ *
+ * The CLI, the MCP tool and the GitHub integration all use this, so the same
+ * change gets the same verdict everywhere.
+ */
+import type { Failure } from '../types/index.js';
+export interface ChangedLineSplit {
+    findings: Failure[];
+    fileFindings: Failure[];
+    unlocated: number;
+    outside: number;
+}
+export declare function splitByChangedLines(failures: Failure[], changedLines: Record<string, Set<number>>): ChangedLineSplit;

package/dist/review/changed-lines.js

@@ -0,0 +1,22 @@
+export function splitByChangedLines(failures, changedLines) {
+    const split = { findings: [], fileFindings: [], unlocated: 0, outside: 0 };
+    for (const failure of failures) {
+        const files = failure.files ?? [];
+        if (files.length === 0) {
+            split.unlocated++;
+        }
+        else if (failure.line === undefined) {
+            if (files.some(file => changedLines[file]))
+                split.fileFindings.push(failure);
+            else
+                split.outside++;
+        }
+        else if (files.some(file => changedLines[file]?.has(failure.line))) {
+            split.findings.push(failure);
+        }
+        else {
+            split.outside++;
+        }
+    }
+    return split;
+}

package/dist/review/effectiveness.d.ts

@@ -0,0 +1,34 @@
+export interface AgentEvent {
+    type: string;
+    timestamp?: string;
+    tool?: string;
+    status?: string;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    session?: string;
+    blocked?: boolean;
+    /** Findings that blocked a stop. */
+    blocking?: number;
+}
+export interface ReviewEffectiveness {
+    toolCalls: Record<string, number>;
+    reviews: number;
+    failedReviews: number;
+    findingsReported: number;
+    findingsResolved: number;
+    stopChecks: number;
+    stopBlocks: number;
+    blockedStopsFollowedThrough: number;
+    stopsWithSelfReview: number;
+}
+export declare function readAgentEvents(cwd: string): AgentEvent[];
+/** Append an event in the same format the MCP server writes; never throws. */
+export declare function appendAgentEvent(cwd: string, event: AgentEvent): void;
+/** `rule:file` keys, so a finding that moved lines is still the same finding. */
+export declare function findingKeys(findings: Array<{
+    id?: string;
+    file?: string;
+}>): string[];
+export declare function computeEffectiveness(events: AgentEvent[]): ReviewEffectiveness;

package/dist/review/effectiveness.js

@@ -0,0 +1,114 @@
+/**
+ * Is the review loop working? Computed from the local event log
+ * (`.rigour/events.jsonl`, written by the MCP server and the stop hook), so
+ * nothing leaves the machine.
+ *
+ * - a finding is resolved when a later review no longer reports it (same rule, same file);
+ * - a blocked stop is followed through when the same session later stops cleanly;
+ * - a self-review is a rigour_review call made before an attempt to stop.
+ */
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+const EVENTS = path.join('.rigour', 'events.jsonl');
+export function readAgentEvents(cwd) {
+    let text = '';
+    try {
+        text = fs.readFileSync(path.join(cwd, EVENTS), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return text.split('\n').filter(Boolean).flatMap(line => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Append an event in the same format the MCP server writes; never throws. */
+export function appendAgentEvent(cwd, event) {
+    try {
+        fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+        fs.appendFileSync(path.join(cwd, EVENTS), JSON.stringify({ id: randomUUID(), timestamp: new Date().toISOString(), ...event }) + '\n');
+    }
+    catch {
+        // The event log is best-effort; it must never break a hook or a tool call.
+    }
+}
+/** `rule:file` keys, so a finding that moved lines is still the same finding. */
+export function findingKeys(findings) {
+    return findings.map(f => `${f.id ?? '?'}:${f.file ?? '?'}`);
+}
+export function computeEffectiveness(events) {
+    const stats = {
+        toolCalls: {}, reviews: 0, failedReviews: 0, findingsReported: 0, findingsResolved: 0,
+        stopChecks: 0, stopBlocks: 0, blockedStopsFollowedThrough: 0, stopsWithSelfReview: 0,
+    };
+    const open = new Set();
+    const blockedSessions = new Set();
+    let reviewedSinceStop = false;
+    for (const event of events) {
+        if (event.type === 'tool_call' && event.tool) {
+            stats.toolCalls[event.tool] = (stats.toolCalls[event.tool] ?? 0) + 1;
+            if (event.tool === 'rigour_review')
+                reviewedSinceStop = true;
+        }
+        else if (event.type === 'tool_response' && event.tool === 'rigour_review') {
+            countReview(stats, open, reviewKeys(event));
+        }
+        else if (event.type === 'stop_review') {
+            countStop(stats, blockedSessions, event, reviewedSinceStop);
+            reviewedSinceStop = false;
+        }
+    }
+    return stats;
+}
+function countReview(stats, open, keys) {
+    if (keys === null)
+        return;
+    stats.reviews++;
+    if (keys.length)
+        stats.failedReviews++;
+    const now = new Set(keys);
+    for (const key of [...open]) {
+        if (!now.has(key)) {
+            open.delete(key);
+            stats.findingsResolved++;
+        }
+    }
+    for (const key of now) {
+        if (!open.has(key)) {
+            open.add(key);
+            stats.findingsReported++;
+        }
+    }
+}
+function countStop(stats, blockedSessions, event, selfReviewed) {
+    const session = event.session ?? 'default';
+    stats.stopChecks++;
+    if (selfReviewed)
+        stats.stopsWithSelfReview++;
+    if (event.blocked) {
+        stats.stopBlocks++;
+        blockedSessions.add(session);
+    }
+    else if (blockedSessions.delete(session)) {
+        stats.blockedStopsFollowedThrough++;
+    }
+}
+/** Finding keys from a rigour_review response, or null when it is not a review result. */
+function reviewKeys(event) {
+    const text = event.content?.find(c => c.type === 'text')?.text;
+    if (!text)
+        return null;
+    try {
+        const body = JSON.parse(text);
+        return Array.isArray(body.failures) ? findingKeys(body.failures) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/review/effectiveness.test.d.ts

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

package/dist/review/effectiveness.test.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { appendAgentEvent, computeEffectiveness, readAgentEvents } from './effectiveness.js';
+const review = (failures) => [
+    { type: 'tool_call', tool: 'rigour_review' },
+    { type: 'tool_response', tool: 'rigour_review', content: [{ type: 'text', text: JSON.stringify({ status: failures.length ? 'FAIL' : 'PASS', failures }) }] },
+];
+describe('computeEffectiveness', () => {
+    it('counts reviews, findings resolved by later reviews, and tool calls', () => {
+        const events = [
+            { type: 'tool_call', tool: 'rigour_recall' },
+            ...review([{ id: 'semantic-bugs', file: 'a.ts' }, { id: 'promise-safety', file: 'b.ts' }]),
+            ...review([{ id: 'promise-safety', file: 'b.ts' }]),
+            ...review([]),
+        ];
+        expect(computeEffectiveness(events)).toMatchObject({
+            reviews: 3, failedReviews: 2, findingsReported: 2, findingsResolved: 2,
+            toolCalls: { rigour_recall: 1, rigour_review: 3 },
+        });
+    });
+    it('follows a blocked stop through to a clean stop in the same session, and counts self-reviews', () => {
+        const events = [
+            { type: 'stop_review', session: 's1', blocked: true },
+            ...review([]),
+            { type: 'stop_review', session: 's1', blocked: false },
+            { type: 'stop_review', session: 's2', blocked: false },
+        ];
+        expect(computeEffectiveness(events)).toMatchObject({
+            stopChecks: 3, stopBlocks: 1, blockedStopsFollowedThrough: 1, stopsWithSelfReview: 1,
+        });
+    });
+    it('reads the log it writes and skips malformed lines', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'effectiveness-'));
+        appendAgentEvent(dir, { type: 'stop_review', blocked: true });
+        fs.appendFileSync(path.join(dir, '.rigour', 'events.jsonl'), 'not json\n');
+        expect(readAgentEvents(dir).map(e => e.type)).toEqual(['stop_review']);
+        expect(readAgentEvents(path.join(dir, 'missing'))).toEqual([]);
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+});

package/dist/review/git-diff.d.ts

@@ -0,0 +1,9 @@
+export type DiffSource = {
+    mode: 'working';
+} | {
+    mode: 'base';
+    base: string;
+};
+export declare class GitDiffError extends Error {
+}
+export declare function diffFromGit(cwd: string, source?: DiffSource): string;

package/dist/review/git-diff.js

@@ -0,0 +1,42 @@
+/**
+ * The diff to review, taken from git so callers do not have to build one.
+ *
+ * - working: uncommitted changes against HEAD, staged or not, plus new files
+ *   git does not track yet (what an agent has just written).
+ * - base: everything on this branch since it left `base` (the merge-base),
+ *   including uncommitted changes (what a pull request contains).
+ */
+import { spawnSync } from 'child_process';
+export class GitDiffError extends Error {
+}
+export function diffFromGit(cwd, source = { mode: 'working' }) {
+    if (source.mode === 'base') {
+        const mergeBase = git(cwd, ['merge-base', source.base, 'HEAD']).trim();
+        return git(cwd, ['diff', '--no-color', '--no-ext-diff', mergeBase]);
+    }
+    const tracked = hasHead(cwd) ? git(cwd, ['diff', '--no-color', '--no-ext-diff', 'HEAD']) : '';
+    return tracked + untrackedFiles(cwd).map(file => newFileDiff(cwd, file)).join('');
+}
+function untrackedFiles(cwd) {
+    return git(cwd, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean);
+}
+/** `git diff --no-index` exits 1 when the files differ, which for a new file is always. */
+function newFileDiff(cwd, file) {
+    const result = spawnSync('git', ['diff', '--no-color', '--no-ext-diff', '--no-index', '--', '/dev/null', file], {
+        cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status !== 0 && result.status !== 1)
+        throw new GitDiffError(`git diff for new file ${file} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+function hasHead(cwd) {
+    return spawnSync('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd }).status === 0;
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (result.error)
+        throw new GitDiffError(`git is not available: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new GitDiffError(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}

package/dist/review/review.d.ts

@@ -0,0 +1,36 @@
+import type { Config, DeepOptions, Failure, Report } from '../types/index.js';
+import { type DiffSource } from './git-diff.js';
+export interface ReviewInput {
+    cwd: string;
+    config: Config;
+    /** A unified diff; when omitted, it is taken from git (`source`). */
+    diff?: string;
+    source?: DiffSource;
+    /** Review exactly these files instead of the ones the diff touches. */
+    files?: string[];
+    /** Deep analysis; `focusLines` is filled from the diff. */
+    deep?: Omit<DeepOptions, 'focusLines'>;
+}
+export interface ReviewResult {
+    status: 'PASS' | 'FAIL' | 'ERROR';
+    findings: Failure[];
+    fileFindings: Failure[];
+    unlocated: number;
+    excludedOutsideChangedLines: number;
+    changedLines: Record<string, Set<number>>;
+    report: Report | null;
+    deepError?: string;
+}
+export interface ReviewFinding {
+    id: string;
+    gate: string;
+    severity: string;
+    provenance: string;
+    message: string;
+    file: string;
+    line: number | null;
+    suggestion?: string;
+}
+export declare function reviewChange(input: ReviewInput): Promise<ReviewResult>;
+/** The JSON shape of a finding, shared by the CLI's --json and the MCP tool. */
+export declare function toReviewFinding(failure: Failure): ReviewFinding;

package/dist/review/review.js

@@ -0,0 +1,49 @@
+/**
+ * reviewChange: the one review engine behind `rigour review`, the MCP
+ * `rigour_review` tool and the GitHub integration.
+ *
+ * Runs the configured gates on the files a change touches and keeps what
+ * belongs to the change (see changed-lines.ts). A deep run that was asked for
+ * but could not analyze anything makes the result ERROR, never a clean PASS.
+ */
+import { GateRunner } from '../gates/runner.js';
+import { changedLinesByFile, parseDiff } from '../utils/diff.js';
+import { normalizeScopePatterns } from '../utils/scope.js';
+import { deepAnalysisError } from '../utils/deep-status.js';
+import { splitByChangedLines } from './changed-lines.js';
+import { diffFromGit } from './git-diff.js';
+export async function reviewChange(input) {
+    const diff = input.diff ?? diffFromGit(input.cwd, input.source);
+    const changedLines = parseDiff(diff);
+    const targets = input.files?.length ? input.files : Object.keys(changedLines);
+    if (targets.length === 0) {
+        return { status: 'PASS', findings: [], fileFindings: [], unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null };
+    }
+    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines) } : undefined;
+    const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
+    const split = splitByChangedLines(report.failures, changedLines);
+    const deepError = deepAnalysisError(report);
+    return {
+        status: deepError ? 'ERROR' : split.findings.length > 0 ? 'FAIL' : 'PASS',
+        findings: split.findings,
+        fileFindings: split.fileFindings,
+        unlocated: split.unlocated,
+        excludedOutsideChangedLines: split.outside,
+        changedLines,
+        report,
+        ...(deepError ? { deepError } : {}),
+    };
+}
+/** The JSON shape of a finding, shared by the CLI's --json and the MCP tool. */
+export function toReviewFinding(failure) {
+    return {
+        id: failure.id,
+        gate: failure.title,
+        severity: failure.severity || 'medium',
+        provenance: failure.provenance || 'traditional',
+        message: failure.details,
+        file: failure.files?.[0] || '',
+        line: failure.line ?? null,
+        ...(failure.hint ? { suggestion: failure.hint } : {}),
+    };
+}

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

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

package/dist/review/review.test.js

@@ -0,0 +1,87 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../types/index.js';
+import { parseDiff } from '../utils/diff.js';
+import { splitByChangedLines } from './changed-lines.js';
+import { diffFromGit } from './git-diff.js';
+import { reviewChange, toReviewFinding } from './review.js';
+const LEAKY = [
+    'export async function notify(endpoint: string, signature: string) {',
+    "  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });",
+    '}',
+    '',
+].join('\n');
+function failure(file, line) {
+    return { id: 'x', title: 'X', details: 'd', files: file ? [file] : [], ...(line !== undefined ? { line } : {}) };
+}
+describe('splitByChangedLines', () => {
+    it('separates changed-line, file-level, unlocated and outside findings', () => {
+        const changed = { 'a.ts': new Set([3]) };
+        const split = splitByChangedLines([failure('a.ts', 3), failure('a.ts', 9), failure('a.ts'), failure('b.ts'), failure(undefined)], changed);
+        expect(split.findings.map(f => f.line)).toEqual([3]);
+        expect(split.fileFindings).toHaveLength(1);
+        expect(split.unlocated).toBe(1);
+        expect(split.outside).toBe(2);
+    });
+});
+describe('git-backed review', () => {
+    let repo;
+    const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+    const write = (rel, body) => {
+        fs.mkdirSync(path.dirname(path.join(repo, rel)), { recursive: true });
+        fs.writeFileSync(path.join(repo, rel), body);
+    };
+    beforeEach(() => {
+        repo = fs.mkdtempSync(path.join(os.tmpdir(), 'review-core-'));
+        git('init', '-q', '-b', 'main');
+        git('config', 'user.email', 't@example.com');
+        git('config', 'user.name', 't');
+        git('config', 'commit.gpgsign', 'false');
+    });
+    afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+    it('works in a repository with no commits yet', () => {
+        write('src/new.ts', 'export const a = 1;\n');
+        expect(parseDiff(diffFromGit(repo))).toEqual({ 'src/new.ts': new Set([1]) });
+    });
+    it('takes uncommitted edits and untracked files from the working tree', () => {
+        write('src/a.ts', 'export const a = 1;\nexport const b = 2;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        write('src/a.ts', 'export const a = 1;\nexport const b = 3;\n');
+        write('src/new.ts', 'export const c = 1;\nexport const d = 2;\n');
+        expect(parseDiff(diffFromGit(repo))).toEqual({ 'src/a.ts': new Set([2]), 'src/new.ts': new Set([1, 2]) });
+    });
+    it('takes a branch against its merge-base, committed and uncommitted', () => {
+        write('src/a.ts', 'export const a = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        git('checkout', '-q', '-b', 'feature');
+        write('src/b.ts', 'export const b = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'feature');
+        write('src/a.ts', 'export const a = 1;\nexport const z = 2;\n');
+        expect(parseDiff(diffFromGit(repo, { mode: 'base', base: 'main' }))).toEqual({ 'src/a.ts': new Set([2]), 'src/b.ts': new Set([1]) });
+    });
+    it('fails a change that introduces a bug and ignores the same bug in untouched code', async () => {
+        write('src/old.ts', LEAKY);
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        write('src/notify.ts', LEAKY);
+        const config = ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: true } } });
+        const result = await reviewChange({ cwd: repo, config });
+        const semantic = result.findings.filter(f => f.id === 'semantic-bugs');
+        expect(result.status).toBe('FAIL');
+        expect(semantic.map(f => [f.files?.[0], f.line])).toEqual([['src/notify.ts', 2]]);
+        expect(toReviewFinding(semantic[0])).toMatchObject({ id: 'semantic-bugs', file: 'src/notify.ts', line: 2, severity: 'high' });
+    });
+    it('passes when nothing changed', async () => {
+        write('src/a.ts', 'export const a = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        const result = await reviewChange({ cwd: repo, config: ConfigSchema.parse({ version: 1 }) });
+        expect(result).toMatchObject({ status: 'PASS', findings: [], report: null });
+    });
+});

package/dist/semantic/learn/learn.d.ts

@@ -23,3 +23,5 @@ export interface LearnReport {
     }>;
 }
 export declare function learnFromFix(input: LearnInput): Promise<LearnReport>;
+/** Learn from one file's before and after (e.g. an agent's fix), validated against the repository at `repoDir`. */
+export declare function learnFromFileChange(repoDir: string, file: string, before: string, after: string, maxHits?: number): Promise<LearnReport>;

package/dist/semantic/learn/learn.js

@@ -8,6 +8,8 @@
  * reported with the reason the most specific one failed.
  */
 import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { globby } from 'globby';
 import { analyzeFiles } from '../engine.js';
@@ -47,6 +49,22 @@ export async function learnFromFix(input) {
     }
     return report;
 }
+/** Learn from one file's before and after (e.g. an agent's fix), validated against the repository at `repoDir`. */
+export async function learnFromFileChange(repoDir, file, before, after, maxHits) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-learn-'));
+    try {
+        const place = (tree, content) => {
+            const target = path.join(root, tree, file);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, content);
+            return path.join(root, tree);
+        };
+        return await learnFromFix({ beforeDir: place('before', before), afterDir: place('after', after), repoDir, files: [file], maxHits });
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
 function openTree(cwd, file) {
     const root = path.join(cwd, file);
     const [program] = [...programBatches([root], loadProjectConfig(cwd).options)];

package/dist/templates/universal-config.js

@@ -235,7 +235,7 @@ export const UNIVERSAL_CONFIG = {
             track_returns: true,
         },
         semantic_bugs: {
-            enabled: false,
+            enabled: true,
         },
         side_effect_analysis: {
             enabled: true,

package/dist/types/index.js

@@ -266,8 +266,9 @@ export const GatesSchema = z.object({
         audit_log: z.boolean().optional().default(true),
     }).optional().default({}),
     // v4.3+ Side-Effect Safety Analysis
+    // On by default: full scans of three real repositories reported no finding that was not a real defect.
     semantic_bugs: z.object({
-        enabled: z.boolean().optional().default(false),
+        enabled: z.boolean().optional().default(true),
         rules: z.array(z.string()).optional(),
     }).optional().default({}),
     side_effect_analysis: z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.3.1",
+  "version": "6.4.0",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -67,11 +67,11 @@
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-x64": "6.3.1",
-    "@rigour-labs/brain-darwin-arm64": "6.3.1",
-    "@rigour-labs/brain-linux-x64": "6.3.1",
-    "@rigour-labs/brain-linux-arm64": "6.3.1",
-    "@rigour-labs/brain-win-x64": "6.3.1"
+    "@rigour-labs/brain-darwin-arm64": "6.4.0",
+    "@rigour-labs/brain-linux-arm64": "6.4.0",
+    "@rigour-labs/brain-darwin-x64": "6.4.0",
+    "@rigour-labs/brain-linux-x64": "6.4.0",
+    "@rigour-labs/brain-win-x64": "6.4.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",