@rigour-labs/core 6.3.0 → 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/inference/model-download.test.js

@@ -9,7 +9,7 @@ const home = vi.hoisted(() => {
     return p.join(o.tmpdir(), `rigour-models-${process.pid}-${Date.now()}`);
 });
 vi.mock('../storage/db.js', () => ({ RIGOUR_DIR: home }));
-const { downloadModel, getCachedModel } = await import('./model-manager.js');
+const { checkForUpdates, downloadModel, getCachedModel, normalizeModelVersion } = await import('./model-manager.js');
 const { FALLBACK_MODELS, MODELS } = await import('./types.js');
 const modelsDir = path.join(home, 'models');
 const PAYLOAD = Buffer.from('gguf-model-bytes');
@@ -22,7 +22,7 @@ describe('downloadModel', () => {
     beforeEach(async () => {
         await fs.remove(home);
         // A fresh version check: no network call to Hugging Face.
-        await fs.outputJson(path.join(modelsDir, '.latest_version.json'), { version: '2.0.0', checkedAt: new Date().toISOString() });
+        await fs.outputJson(path.join(modelsDir, '.latest_version.json'), { format: 2, version: '5', checkedAt: new Date().toISOString() });
     });
     afterAll(async () => { await fs.remove(home); });
     it('falls back to the stock model when the fine-tuned model is unavailable, and says so', async () => {
@@ -39,6 +39,19 @@ describe('downloadModel', () => {
         const meta = await fs.readJson(`${modelPath}.meta.json`);
         expect(meta).toMatchObject({ sha256: PAYLOAD_SHA, sizeBytes: PAYLOAD.length, sourceUrl: FALLBACK_MODELS.lite.url });
     });
+    it('retries the fine-tuned model once a day when only the stock fallback is cached', async () => {
+        const failing = (url) => (url.includes('rigour-labs/') ? unauthorized : ok(PAYLOAD, PAYLOAD_SHA));
+        const stockPath = await downloadModel('lite', undefined, failing);
+        const requested = [];
+        const again = await downloadModel('lite', undefined, (url) => { requested.push(url); return unauthorized; });
+        expect(requested).toEqual([]); // failed less than a day ago: keep the fallback, no request
+        expect(again).toBe(stockPath);
+        await fs.writeJson(path.join(modelsDir, '.fine-tuned-unavailable-lite.json'), { failedAt: '2000-01-01T00:00:00Z', url: MODELS.lite.url });
+        const fineTuned = await downloadModel('lite', undefined, (url) => { requested.push(url); return ok(PAYLOAD, PAYLOAD_SHA); });
+        expect(requested).toEqual([MODELS.lite.url]);
+        expect(path.basename(fineTuned)).toBe(MODELS.lite.filename);
+        expect(await fs.pathExists(path.join(modelsDir, '.fine-tuned-unavailable-lite.json'))).toBe(false);
+    });
     it('rejects a checksum mismatch and deletes the partial download', async () => {
         const get = () => ok(PAYLOAD, 'f'.repeat(64));
         await expect(downloadModel('lite', undefined, get)).rejects.toThrow('Checksum mismatch');
@@ -65,9 +78,48 @@ describe('getCachedModel', () => {
         const cached = await getCachedModel('deep');
         expect(cached).toMatchObject({ fallback: true, info: { filename: FALLBACK_MODELS.deep.filename } });
     });
+    it('accepts a verified fine-tuned file smaller than the size estimate', async () => {
+        await cacheFile(MODELS.lite.filename, 397_807_360); // the published v5 lite model
+        expect(await getCachedModel('lite')).toMatchObject({ fallback: false, info: { filename: MODELS.lite.filename } });
+    });
+    it('accepts a file verified within the same millisecond it was written', async () => {
+        const file = path.join(modelsDir, FALLBACK_MODELS.deep.filename);
+        await cacheFile(FALLBACK_MODELS.deep.filename, 10);
+        const written = new Date('2026-01-01T00:00:00.000Z');
+        await fs.utimes(file, written, written.getTime() / 1000 + 0.0007); // mtime 0.7 ms into the same millisecond
+        await fs.writeJson(`${file}.meta.json`, { sha256: 'a'.repeat(64), sizeBytes: 10, verifiedAt: written.toISOString(), sourceUrl: 'https://x' });
+        expect(await getCachedModel('deep')).toMatchObject({ fallback: true });
+    });
+    it('rejects a file modified after it was verified', async () => {
+        const file = path.join(modelsDir, FALLBACK_MODELS.deep.filename);
+        await cacheFile(FALLBACK_MODELS.deep.filename, 10);
+        await fs.writeJson(`${file}.meta.json`, { sha256: 'a'.repeat(64), sizeBytes: 10, verifiedAt: '2000-01-01T00:00:00.000Z', sourceUrl: 'https://x' });
+        expect(await getCachedModel('deep')).toBeNull();
+    });
     it('ignores a file without verified metadata', async () => {
         await fs.ensureDir(modelsDir);
         await fs.writeFile(path.join(modelsDir, FALLBACK_MODELS.deep.filename), 'partial');
         expect(await getCachedModel('deep')).toBeNull();
     });
 });
+describe('model versions', () => {
+    beforeEach(async () => { await fs.remove(home); vi.unstubAllGlobals(); });
+    it('keeps published version strings as they are', () => {
+        expect(normalizeModelVersion(5)).toBe('5');
+        expect(normalizeModelVersion('5')).toBe('5');
+        expect(normalizeModelVersion('v2.1.0')).toBe('2.1.0');
+        expect(normalizeModelVersion('5.0')).toBeNull();
+        expect(normalizeModelVersion({})).toBeNull();
+    });
+    it('names the published v5 repositories by default', () => {
+        expect(MODELS.lite.url).toBe('https://huggingface.co/rigour-labs/rigour-lite-v5-gguf/resolve/main/rigour-lite-v5-q4_k_m.gguf');
+        expect(MODELS.deep.url).toBe('https://huggingface.co/rigour-labs/rigour-deep-v5-gguf/resolve/main/rigour-deep-v5-q4_k_m.gguf');
+    });
+    it('ignores a version cache from the old SemVer conversion and re-reads the published version', async () => {
+        await fs.outputJson(path.join(modelsDir, '.latest_version.json'), { version: '5.0.0', checkedAt: new Date().toISOString() });
+        vi.stubGlobal('fetch', vi.fn(async () => ({ ok: true, json: async () => ({ version: 5 }) })));
+        expect(await checkForUpdates()).toBe('5');
+        expect(await fs.readJson(path.join(modelsDir, '.latest_version.json'))).toMatchObject({ format: 2, version: '5' });
+        expect(MODELS.deep.filename).toBe('rigour-deep-v5-q4_k_m.gguf');
+    });
+});

package/dist/inference/model-manager.d.ts

@@ -26,6 +26,12 @@ export declare function getModelPath(tier: ModelTier): string;
  * Get model info for a tier.
  */
 export declare function getModelInfo(tier: ModelTier): ModelInfo;
+/**
+ * The version exactly as published. Integer versions (the RLAIF pipeline
+ * before SemVer) are published as `v5`, SemVer versions as `v2.1.0`; either
+ * way the string goes into the repository and file names unchanged.
+ */
+export declare function normalizeModelVersion(raw: unknown): string | null;
 /**
  * Check HuggingFace for a newer model version (like antivirus signature updates).
  * Reads latest_version.json from the RLAIF dataset repo. Non-blocking — if the

package/dist/inference/model-manager.js

@@ -8,6 +8,7 @@ import { createHash } from 'crypto';
 import { RIGOUR_DIR } from '../storage/db.js';
 import { downloadToFile } from './http-download.js';
 import { MODELS, FALLBACK_MODELS, VERSION_CHECK_URL, BUNDLED_MODEL_VERSION, updateModelVersion } from './types.js';
+import { Logger } from '../utils/logger.js';
 const MODELS_DIR = path.join(RIGOUR_DIR, 'models');
 const VERSION_CACHE_PATH = path.join(MODELS_DIR, '.latest_version.json');
 const VERSION_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // Check once per day
@@ -63,13 +64,14 @@ async function isFileCached(model) {
     const metadata = await readModelMeta(model.filename);
     if (!metadata)
         return false;
+    // The metadata is written only after the checksum passed, so its exact size is
+    // the completeness check; ModelInfo sizes are display estimates that differ by version.
     const stat = await fs.stat(modelPath);
-    const tolerance = model.sizeBytes * 0.1;
-    if (stat.size <= model.sizeBytes - tolerance)
-        return false;
     if (metadata.sizeBytes !== stat.size)
         return false;
-    if (new Date(metadata.verifiedAt).getTime() < stat.mtimeMs)
+    // verifiedAt has millisecond precision and mtimeMs a sub-millisecond fraction: compare
+    // whole milliseconds, or a file verified within the same millisecond looks modified.
+    if (new Date(metadata.verifiedAt).getTime() < Math.floor(stat.mtimeMs))
         return false;
     return true;
 }
@@ -161,6 +163,27 @@ async function downloadFromUrl(model, onProgress, get) {
     onProgress?.(`Model ${model.name} ready`, 100);
     return destPath;
 }
+/**
+ * Version cache format. Format 1 turned a published integer version into
+ * SemVer ("5" -> "5.0.0"), which names repositories that were never published,
+ * so those caches are ignored.
+ */
+const VERSION_CACHE_FORMAT = 2;
+/** How long a failed fine-tuned download keeps the stock fallback before retrying. */
+const FINE_TUNED_RETRY_MS = 24 * 60 * 60 * 1000;
+/**
+ * The version exactly as published. Integer versions (the RLAIF pipeline
+ * before SemVer) are published as `v5`, SemVer versions as `v2.1.0`; either
+ * way the string goes into the repository and file names unchanged.
+ */
+export function normalizeModelVersion(raw) {
+    if (typeof raw === 'number' && Number.isInteger(raw) && raw > 0)
+        return String(raw);
+    if (typeof raw !== 'string')
+        return null;
+    const value = raw.trim().replace(/^v/, '');
+    return /^\d+$/.test(value) || /^\d+\.\d+\.\d+$/.test(value) ? value : null;
+}
 /**
  * Check HuggingFace for a newer model version (like antivirus signature updates).
  * Reads latest_version.json from the RLAIF dataset repo. Non-blocking — if the
@@ -175,8 +198,8 @@ export async function checkForUpdates(onProgress) {
         if (await fs.pathExists(VERSION_CACHE_PATH)) {
             const cached = await fs.readJson(VERSION_CACHE_PATH);
             const age = Date.now() - new Date(cached.checkedAt).getTime();
-            if (age < VERSION_CHECK_INTERVAL_MS && cached.version) {
-                const v = String(cached.version);
+            const v = cached.format === VERSION_CACHE_FORMAT ? normalizeModelVersion(cached.version) : null;
+            if (age < VERSION_CHECK_INTERVAL_MS && v) {
                 updateModelVersion(v);
                 return v;
             }
@@ -193,13 +216,10 @@ export async function checkForUpdates(onProgress) {
         clearTimeout(timeout);
         if (response.ok) {
             const data = await response.json();
-            // Handle both legacy integer versions (5 → "5.0.0") and SemVer strings ("2.0.0")
-            let rawVersion = data.version ?? BUNDLED_MODEL_VERSION;
-            const latestVersion = typeof rawVersion === 'number'
-                ? `${rawVersion}.0.0`
-                : String(rawVersion);
+            const latestVersion = normalizeModelVersion(data.version) ?? BUNDLED_MODEL_VERSION;
             // Cache the result locally
             await fs.writeJson(VERSION_CACHE_PATH, {
+                format: VERSION_CACHE_FORMAT,
                 version: latestVersion,
                 checkedAt: new Date().toISOString(),
                 source: 'huggingface',
@@ -226,22 +246,42 @@ export async function downloadModel(tier, onProgress, get) {
     // Check for newer model version (non-blocking, cached 24h)
     await checkForUpdates(onProgress);
     const cached = await getCachedModel(tier);
-    if (cached) {
+    if (cached && !cached.fallback) {
         onProgress?.(`Model ${cached.info.name} already cached`, 100);
         return cached.path;
     }
+    // Only the stock fallback is cached: try the fine-tuned model again, at most once a day,
+    // so one failed download does not pin a user to the stock model forever.
+    if (cached && !(await fineTunedRetryDue(tier)))
+        return cached.path;
     const model = MODELS[tier];
     onProgress?.(`Downloading ${model.name} (${model.sizeHuman})...`, 0);
     try {
-        return await downloadFromUrl(model, onProgress, get);
+        const downloaded = await downloadFromUrl(model, onProgress, get);
+        await fs.remove(retryMarker(tier)).catch(() => { });
+        return downloaded;
     }
     catch (error) {
         const fallback = FALLBACK_MODELS[tier];
-        if (fallback && fallback.url !== model.url) {
-            onProgress?.(`Fine-tuned model unavailable (${error?.message ?? 'unknown error'}); using stock ${fallback.name}`, 0);
-            return downloadFromUrl(fallback, onProgress, get);
-        }
-        throw error;
+        if (!fallback || fallback.url === model.url)
+            throw error;
+        const reason = error?.message ?? 'unknown error';
+        Logger.warn(`Fine-tuned model ${model.name} could not be downloaded from ${model.url} (${reason}); using the stock ${fallback.name}. Deep findings will be less accurate.`);
+        onProgress?.(`Fine-tuned model unavailable (${reason}); using stock ${fallback.name}`, 0);
+        await fs.writeJson(retryMarker(tier), { failedAt: new Date().toISOString(), url: model.url, reason }).catch(() => { });
+        return cached?.path ?? downloadFromUrl(fallback, onProgress, get);
+    }
+}
+function retryMarker(tier) {
+    return path.join(MODELS_DIR, `.fine-tuned-unavailable-${tier}.json`);
+}
+async function fineTunedRetryDue(tier) {
+    try {
+        const marker = await fs.readJson(retryMarker(tier));
+        return Date.now() - new Date(marker.failedAt).getTime() >= FINE_TUNED_RETRY_MS || marker.url !== MODELS[tier].url;
+    }
+    catch {
+        return true;
     }
 }
 /**

package/dist/inference/types.d.ts

@@ -86,12 +86,16 @@ export interface ModelInfo {
  * At startup, model-manager checks HF for the latest version and downloads
  * it automatically (like antivirus signature updates).
  *
- * Version format: SemVer (MAJOR.MINOR.PATCH)
+ * The fallback is the last version actually published: v5, from the RLAIF
+ * pipeline's integer versions. SemVer versions (MAJOR.MINOR.PATCH) are
+ * published under their SemVer names.
+ *
+ * Version format: SemVer (MAJOR.MINOR.PATCH), or a legacy integer
  *   - MAJOR: Training data format change, base model change, pipeline architecture
  *   - MINOR: New training repos, updated dataset, hyperparameter improvements
  *   - PATCH: Bug fixes, retraining with same data/format
  */
-export declare const BUNDLED_MODEL_VERSION = "2.0.0";
+export declare const BUNDLED_MODEL_VERSION = "5";
 /** HuggingFace dataset repo where latest_version.json lives */
 export declare const VERSION_CHECK_URL = "https://huggingface.co/datasets/rigour-labs/rigour-rlaif-data/resolve/main/latest_version.json";
 /** Build model info for a given tier and version */

package/dist/inference/types.js

@@ -5,19 +5,23 @@
  * At startup, model-manager checks HF for the latest version and downloads
  * it automatically (like antivirus signature updates).
  *
- * Version format: SemVer (MAJOR.MINOR.PATCH)
+ * The fallback is the last version actually published: v5, from the RLAIF
+ * pipeline's integer versions. SemVer versions (MAJOR.MINOR.PATCH) are
+ * published under their SemVer names.
+ *
+ * Version format: SemVer (MAJOR.MINOR.PATCH), or a legacy integer
  *   - MAJOR: Training data format change, base model change, pipeline architecture
  *   - MINOR: New training repos, updated dataset, hyperparameter improvements
  *   - PATCH: Bug fixes, retraining with same data/format
  */
-export const BUNDLED_MODEL_VERSION = '2.0.0';
+export const BUNDLED_MODEL_VERSION = '5';
 /** HuggingFace dataset repo where latest_version.json lives */
 export const VERSION_CHECK_URL = 'https://huggingface.co/datasets/rigour-labs/rigour-rlaif-data/resolve/main/latest_version.json';
 /** Build model info for a given tier and version */
 export function buildModelInfo(tier, version) {
     const meta = {
         deep: { base: 'Qwen2.5-Coder-1.5B', size: 900_000_000, sizeH: '900MB' },
-        lite: { base: 'Qwen2.5-Coder-0.5B', size: 500_000_000, sizeH: '500MB' },
+        lite: { base: 'Qwen2.5-Coder-0.5B', size: 400_000_000, sizeH: '400MB' },
         legacy: { base: 'Qwen2.5-Coder-0.5B', size: 350_000_000, sizeH: '350MB' },
     };
     const m = meta[tier];

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.0",
+  "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-arm64": "6.3.0",
-    "@rigour-labs/brain-darwin-x64": "6.3.0",
-    "@rigour-labs/brain-linux-arm64": "6.3.0",
-    "@rigour-labs/brain-win-x64": "6.3.0",
-    "@rigour-labs/brain-linux-x64": "6.3.0"
+    "@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",