@rigour-labs/core 6.5.4 → 6.6.0

package/dist/context/automatic-index-cache.test.d.ts

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

package/dist/context/automatic-index-cache.test.js

@@ -0,0 +1,30 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const writes = vi.hoisted(() => ({ count: 0 }));
+vi.mock('../storage/context-telemetry.js', async (importOriginal) => ({
+    ...(await importOriginal()),
+    setContextCacheRecord: async () => { writes.count++; },
+}));
+const { ensureAutomaticIndex, updateAutomaticIndexForFiles } = await import('./automatic-index.js');
+let cwd;
+beforeEach(() => {
+    writes.count = 0;
+    cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'auto-index-'));
+    fs.mkdirSync(path.join(cwd, 'src'));
+    fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'export function alpha() { return 1; }\n');
+    fs.writeFileSync(path.join(cwd, 'src/b.ts'), 'export function beta() { return 2; }\n');
+});
+afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));
+describe('automatic indexing', () => {
+    it('writes nothing to the context cache, however many edits it sees', async () => {
+        await ensureAutomaticIndex(cwd, { backgroundSemantic: false });
+        for (let edit = 0; edit < 5; edit++) {
+            fs.writeFileSync(path.join(cwd, 'src/a.ts'), `export function alpha() { return ${edit}; }\n`);
+            await updateAutomaticIndexForFiles(cwd, ['src/a.ts']);
+        }
+        expect(writes.count).toBe(0);
+        expect(fs.existsSync(path.join(cwd, '.rigour', 'patterns.json'))).toBe(true);
+    });
+});

package/dist/context/automatic-index.js

@@ -3,7 +3,6 @@ import path from 'path';
 import { PatternIndexer, getDefaultIndexPath, loadPatternIndex, savePatternIndex } from '../pattern-index/indexer.js';
 import { EMBEDDING_TEXT_VERSION } from '../pattern-index/embeddings.js';
 import { affectedDependents, buildDependencyGraph, updateDependencyGraph } from './dependency-graph.js';
-import { syncIndexToContextCache } from './index-bridge.js';
 const enrichmentJobs = new Map();
 function projectRelativeFiles(cwd, files) {
     const root = path.resolve(cwd);
@@ -78,7 +77,6 @@ async function enrichSemantic(cwd, index) {
         const merged = mergeSemanticEmbeddings(latest, enriched);
         const embedded = merged.patterns.filter((pattern) => (pattern.embedding?.length ?? 0) > 0).length;
         await savePatternIndex(merged, indexPath);
-        await syncIndexToContextCache(cwd, merged);
         await writeStatus(cwd, {
             structural: 'ready',
             graph: 'ready',
@@ -114,7 +112,6 @@ export async function ensureAutomaticIndex(cwd, options = {}) {
     const index = existing ?? await indexer.buildIndex();
     if (!existing)
         await savePatternIndex(index, indexPath);
-    await syncIndexToContextCache(cwd, index);
     if (!(await fs.pathExists(path.join(cwd, '.rigour', 'dependency-graph.json')))) {
         await buildDependencyGraph(cwd, index);
     }
@@ -144,7 +141,6 @@ export async function updateAutomaticIndexForFiles(cwd, changedFiles) {
     const indexer = new PatternIndexer(cwd, { useEmbeddings: false });
     const index = await indexer.updateFiles(existing, affectedFiles);
     await savePatternIndex(index, getDefaultIndexPath(cwd));
-    await syncIndexToContextCache(cwd, index);
     if (graph)
         await updateDependencyGraph(cwd, index, graph, affectedFiles);
     else

package/dist/context/cache-engine.d.ts

@@ -1,32 +1,11 @@
 /**
- * 4-Layer Context Caching Engine for Rigour
+ * Context caching for Rigour: the two layers something reads.
+ * - Semantic-query cache: the edit and validation scope resolved for a task query.
+ * - Task checkpoint cache: compact handoff packets between agents.
  *
- * Implements:
- * 1. Content-addressed static cache (AST, exports, imports, dependencies, patterns by content SHA)
- * 2. Component context cache (Compact dossiers per component scope)
- * 3. Semantic-query cache (Intent embeddings & edit/validation scopes)
- * 4. Task checkpoint cache (Subagent handoff packets)
+ * The static (per-file) and component layers were removed: nothing read them, and the index sync
+ * that wrote them added a fresh row per component on every edit (millions of rows in real use).
  */
-export interface StaticCacheEntry {
-    astSummary?: any;
-    exports?: string[];
-    imports?: string[];
-    dependencies?: string[];
-    ownership?: string;
-    schemas?: any[];
-    endpoints?: string[];
-    eventRelationships?: any[];
-    styleFingerprint?: string;
-    rigourPatterns?: string[];
-}
-export interface ComponentDossier {
-    component: string;
-    responsibility: string;
-    canonicalFiles: string[];
-    contracts: string[];
-    directConsumers: string[];
-    validationCommands: string[];
-}
 export interface SemanticQueryEntry {
     query: string;
     intentEmbedding?: number[];
@@ -78,17 +57,7 @@ export interface TaskCheckpointPacket {
  */
 export declare function hashContent(content: string): string;
 /**
- * Layer 1: Content-Addressed Static Cache
- */
-export declare function getStaticCache(repo: string, branch: string, filePath: string, fileContent: string, cwd?: string): Promise<StaticCacheEntry | null>;
-export declare function setStaticCache(repo: string, branch: string, filePath: string, fileContent: string, entry: StaticCacheEntry, cwd?: string): Promise<void>;
-/**
- * Layer 2: Component Context Cache
- */
-export declare function getComponentCache(componentName: string, commitSha: string, profileVersion?: string, cwd?: string): Promise<ComponentDossier | null>;
-export declare function setComponentCache(componentName: string, commitSha: string, dossier: ComponentDossier, dependencyFingerprint: string, profileVersion?: string, cwd?: string): Promise<void>;
-/**
- * Layer 3: Semantic-Query Cache
+ * Semantic-Query Cache
  */
 export declare function normalizeQuery(query: string): string;
 export declare function getSemanticQueryCache(query: string, commitSha: string, cwd?: string): Promise<SemanticQueryEntry | null>;
@@ -119,7 +88,7 @@ export declare function filterExistingEditScope(editScope: string[], cwd: string
     missing: string[];
 }>;
 /**
- * Layer 4: Task Checkpoint Cache
+ * Task Checkpoint Cache
  */
 export declare function setTaskCheckpointCache(packet: TaskCheckpointPacket, rawStateTokens: number, cwd?: string): Promise<void>;
 export declare function getTaskCheckpointCache(taskId: string, agentId: string, phase: string, cwd?: string): Promise<TaskCheckpointPacket | null>;

package/dist/context/cache-engine.js

@@ -1,11 +1,10 @@
 /**
- * 4-Layer Context Caching Engine for Rigour
+ * Context caching for Rigour: the two layers something reads.
+ * - Semantic-query cache: the edit and validation scope resolved for a task query.
+ * - Task checkpoint cache: compact handoff packets between agents.
  *
- * Implements:
- * 1. Content-addressed static cache (AST, exports, imports, dependencies, patterns by content SHA)
- * 2. Component context cache (Compact dossiers per component scope)
- * 3. Semantic-query cache (Intent embeddings & edit/validation scopes)
- * 4. Task checkpoint cache (Subagent handoff packets)
+ * The static (per-file) and component layers were removed: nothing read them, and the index sync
+ * that wrote them added a fresh row per component on every edit (millions of rows in real use).
  */
 import { createHash } from 'crypto';
 import fs from 'fs-extra';
@@ -18,69 +17,7 @@ export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex').slice(0, 16);
 }
 /**
- * Layer 1: Content-Addressed Static Cache
- */
-export async function getStaticCache(repo, branch, filePath, fileContent, cwd) {
-    const contentSha = hashContent(fileContent);
-    const cacheKey = `static:${repo}:${branch}:${filePath}:${contentSha}:v1`;
-    const record = await getContextCacheRecord(cacheKey, cwd);
-    if (!record)
-        return null;
-    try {
-        return JSON.parse(record.payloadJson);
-    }
-    catch {
-        return null;
-    }
-}
-export async function setStaticCache(repo, branch, filePath, fileContent, entry, cwd) {
-    const contentSha = hashContent(fileContent);
-    const cacheKey = `static:${repo}:${branch}:${filePath}:${contentSha}:v1`;
-    const payloadJson = JSON.stringify(entry);
-    const payloadTokens = Math.ceil(payloadJson.length / 4);
-    await setContextCacheRecord({
-        cacheKey,
-        cacheType: 'static',
-        repo,
-        branch,
-        commitSha: contentSha,
-        dependencyFingerprint: `sha-${contentSha}`,
-        payloadJson,
-        payloadTokens,
-    }, cwd);
-}
-/**
- * Layer 2: Component Context Cache
- */
-export async function getComponentCache(componentName, commitSha, profileVersion = '3', cwd) {
-    const cacheKey = `component:${componentName}:${commitSha}:v${profileVersion}`;
-    const record = await getContextCacheRecord(cacheKey, cwd);
-    if (!record)
-        return null;
-    try {
-        return JSON.parse(record.payloadJson);
-    }
-    catch {
-        return null;
-    }
-}
-export async function setComponentCache(componentName, commitSha, dossier, dependencyFingerprint, profileVersion = '3', cwd) {
-    const cacheKey = `component:${componentName}:${commitSha}:v${profileVersion}`;
-    const payloadJson = JSON.stringify(dossier);
-    const payloadTokens = Math.ceil(payloadJson.length / 4);
-    await setContextCacheRecord({
-        cacheKey,
-        cacheType: 'component',
-        repo: dossier.component,
-        branch: 'main',
-        commitSha,
-        dependencyFingerprint,
-        payloadJson,
-        payloadTokens,
-    }, cwd);
-}
-/**
- * Layer 3: Semantic-Query Cache
+ * Semantic-Query Cache
  */
 export function normalizeQuery(query) {
     return query.toLowerCase().trim().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ');
@@ -193,7 +130,7 @@ export async function filterExistingEditScope(editScope, cwd) {
     return { valid, missing };
 }
 /**
- * Layer 4: Task Checkpoint Cache
+ * Task Checkpoint Cache
  */
 export async function setTaskCheckpointCache(packet, rawStateTokens, cwd) {
     const cacheKey = `checkpoint:${packet.taskId}:${packet.agentId}:${packet.phase}`;

package/dist/context/cache-engine.test.js

@@ -8,8 +8,8 @@ vi.mock('./db.js', () => ({
     DB_PATH: '/tmp/rigour-test.db',
     RIGOUR_DIR: '/tmp/.rigour',
 }));
-import { getStaticCache, setStaticCache, getComponentCache, setComponentCache, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, queryTokenOverlap, distinctiveTokenAgreement, filterExistingEditScope, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
-describe('4-Layer Context Cache Engine', () => {
+import { getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, queryTokenOverlap, distinctiveTokenAgreement, filterExistingEditScope, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
+describe('Context cache engine', () => {
     const testCwd = path.join(os.tmpdir(), `rigour-cache-test-${Date.now()}`);
     beforeEach(async () => {
         await fs.ensureDir(testCwd);
@@ -26,35 +26,6 @@ describe('4-Layer Context Cache Engine', () => {
         expect(normalizeQuery('  Add priority to task!! ')).toBe('add priority to task');
         expect(normalizeQuery('Task SHOULD Support Priority.')).toBe('task should support priority');
     });
-    it('Layer 1: should store and retrieve content-addressed static cache', async () => {
-        const fileContent = 'export function processTask() { return true; }';
-        const entry = {
-            exports: ['processTask'],
-            imports: [],
-            ownership: 'platform-team',
-            endpoints: ['/api/task']
-        };
-        await setStaticCache('rigour-repo', 'main', 'services/task.ts', fileContent, entry, testCwd);
-        const cached = await getStaticCache('rigour-repo', 'main', 'services/task.ts', fileContent, testCwd);
-        expect(cached).not.toBeNull();
-        expect(cached?.exports).toEqual(['processTask']);
-        expect(cached?.ownership).toBe('platform-team');
-    });
-    it('Layer 2: should store and retrieve component context dossier', async () => {
-        const dossier = {
-            component: 'services/task',
-            responsibility: 'Task lifecycle and persistence',
-            canonicalFiles: ['services/task.ts'],
-            contracts: ['TaskContract'],
-            directConsumers: ['controllers/task'],
-            validationCommands: ['npm test']
-        };
-        await setComponentCache('services/task', 'abc123commit', dossier, 'dep-fingerprint-v1', '3', testCwd);
-        const retrieved = await getComponentCache('services/task', 'abc123commit', '3', testCwd);
-        expect(retrieved).not.toBeNull();
-        expect(retrieved?.responsibility).toBe('Task lifecycle and persistence');
-        expect(retrieved?.canonicalFiles).toContain('services/task.ts');
-    });
     it('Layer 3: should store and retrieve semantic query scope', async () => {
         const entry = {
             query: 'task priority persistence',
@@ -125,19 +96,4 @@ describe('4-Layer Context Cache Engine', () => {
         expect(result.valid).toEqual(['alive.ts']);
         expect(result.missing).toEqual(['gone.ts']);
     });
-    it('Layer 1: invalidates static cache when file content changes', async () => {
-        const originalContent = 'export function processTask() { return true; }';
-        const entry = {
-            exports: ['processTask'],
-            imports: [],
-            ownership: 'platform-team',
-            endpoints: ['/api/task'],
-        };
-        await setStaticCache('rigour-repo', 'main', 'services/task.ts', originalContent, entry, testCwd);
-        const cached = await getStaticCache('rigour-repo', 'main', 'services/task.ts', originalContent, testCwd);
-        expect(cached?.exports).toEqual(['processTask']);
-        const changedContent = 'export function processTask() { return false; }';
-        const stale = await getStaticCache('rigour-repo', 'main', 'services/task.ts', changedContent, testCwd);
-        expect(stale).toBeNull();
-    });
 });

package/dist/context/index-bridge.d.ts

@@ -1,8 +1,6 @@
 /**
- * Bridge between Pattern Index and 4-Layer Context Cache.
- * Syncs indexed patterns into static cache entries and component dossiers.
+ * Health of the pattern index (.rigour/patterns.json): present, readable, fresh.
  */
-import type { PatternIndex } from '../pattern-index/types.js';
 export interface IndexHealthReport {
     indexPath: string;
     exists: boolean;
@@ -14,10 +12,6 @@ export interface IndexHealthReport {
     totalFiles?: number;
     message: string;
 }
-/**
- * Sync pattern index entries into static cache and component dossier layers.
- */
-export declare function syncIndexToContextCache(cwd: string, index: PatternIndex): Promise<number>;
 /**
  * Check patterns.json freshness relative to the project directory.
  */

package/dist/context/index-bridge.js

@@ -1,90 +1,12 @@
 /**
- * Bridge between Pattern Index and 4-Layer Context Cache.
- * Syncs indexed patterns into static cache entries and component dossiers.
+ * Health of the pattern index (.rigour/patterns.json): present, readable, fresh.
  */
 import fs from 'fs-extra';
 import path from 'path';
-import { setStaticCache, setComponentCache, hashContent } from './cache-engine.js';
-import { getRepositoryId } from '../storage/lessons.js';
 function getIndexPath(cwd) {
     return path.join(cwd, '.rigour', 'patterns.json');
 }
 const DEFAULT_STALE_MS = 24 * 60 * 60 * 1000;
-async function resolveGitBranch(cwd) {
-    try {
-        let gitDir = path.join(cwd, '.git');
-        const gitStat = await fs.stat(gitDir);
-        if (gitStat.isFile()) {
-            const pointer = await fs.readFile(gitDir, 'utf8');
-            const match = pointer.match(/^gitdir:\s*(.+)$/m);
-            if (!match)
-                return 'workspace';
-            gitDir = path.resolve(cwd, match[1].trim());
-        }
-        const head = (await fs.readFile(path.join(gitDir, 'HEAD'), 'utf8')).trim();
-        return head.startsWith('ref: refs/heads/') ? head.slice('ref: refs/heads/'.length) : head.slice(0, 12);
-    }
-    catch {
-        return 'workspace';
-    }
-}
-function groupByComponent(patterns) {
-    const groups = new Map();
-    for (const p of patterns) {
-        const key = p.type === 'component' ? p.name : p.category || 'uncategorized';
-        const list = groups.get(key) ?? [];
-        list.push(p);
-        groups.set(key, list);
-    }
-    return groups;
-}
-function buildDossier(component, patterns) {
-    const canonicalFiles = [...new Set(patterns.map(p => p.file))];
-    const contracts = patterns
-        .filter(p => p.signature)
-        .map(p => p.signature)
-        .slice(0, 20);
-    const descriptions = patterns.map(p => p.description).filter(Boolean);
-    const responsibility = descriptions[0] || `Indexed ${patterns.length} patterns for ${component}`;
-    return {
-        component,
-        responsibility,
-        canonicalFiles,
-        contracts,
-        directConsumers: [],
-        validationCommands: [],
-    };
-}
-/**
- * Sync pattern index entries into static cache and component dossier layers.
- */
-export async function syncIndexToContextCache(cwd, index) {
-    const resolved = path.resolve(cwd);
-    const repo = await getRepositoryId(resolved);
-    const branch = await resolveGitBranch(resolved);
-    const commitSha = hashContent(index.lastUpdated);
-    let synced = 0;
-    for (const file of index.files) {
-        const filePatterns = index.patterns.filter(p => p.file === file.path);
-        if (filePatterns.length === 0)
-            continue;
-        const payload = {
-            rigourPatterns: filePatterns.map(p => `${p.type}:${p.name}`),
-            exports: filePatterns.filter(p => p.exported).map(p => p.name),
-        };
-        const fileContent = JSON.stringify(payload);
-        await setStaticCache(repo, branch, file.path, fileContent, payload, resolved);
-        synced++;
-    }
-    const componentGroups = groupByComponent(index.patterns);
-    for (const [component, patterns] of componentGroups) {
-        const dossier = buildDossier(component, patterns);
-        const fingerprint = hashContent(JSON.stringify(patterns.map(p => p.id)));
-        await setComponentCache(component, commitSha, dossier, fingerprint, '3', resolved);
-        synced++;
-    }
-    return synced;
-}
 /**
  * Check patterns.json freshness relative to the project directory.
  */

package/dist/firewall/execution-receipt.d.ts

@@ -1,4 +1,9 @@
 import type { ExecutionReceipt } from './types.js';
+/**
+ * Another append holds the lock. On Windows, creating a file another process is still deleting
+ * fails with EPERM (or EACCES/EBUSY) rather than EEXIST; elsewhere those are real permission errors.
+ */
+export declare function isLockContention(code: unknown, platform?: NodeJS.Platform): boolean;
 export declare function appendExecutionReceipt(cwd: string, input: Omit<ExecutionReceipt, 'version' | 'id' | 'repositoryId' | 'createdAt' | 'previousReceipt' | 'digest' | 'signature'>, controlRoot?: string): Promise<ExecutionReceipt>;
 export declare function listExecutionReceipts(cwd: string, limit?: number, controlRoot?: string): Promise<ExecutionReceipt[]>;
 export declare function verifyExecutionReceiptChain(cwd: string, controlRoot?: string): Promise<{

package/dist/firewall/execution-receipt.js

@@ -17,6 +17,15 @@ async function receiptKey(cwd, controlRoot) {
     await fs.writeFile(keyPath, key, { mode: 0o600 });
     return key;
 }
+/**
+ * Another append holds the lock. On Windows, creating a file another process is still deleting
+ * fails with EPERM (or EACCES/EBUSY) rather than EEXIST; elsewhere those are real permission errors.
+ */
+export function isLockContention(code, platform = process.platform) {
+    if (code === 'EEXIST')
+        return true;
+    return platform === 'win32' && (code === 'EPERM' || code === 'EACCES' || code === 'EBUSY');
+}
 async function acquireReceiptLock(logPath) {
     const lockPath = `${logPath}.append-lock`;
     for (let attempt = 0; attempt < 100; attempt += 1) {
@@ -24,7 +33,7 @@ async function acquireReceiptLock(logPath) {
             return await fs.promises.open(lockPath, 'wx', 0o600);
         }
         catch (error) {
-            if (error?.code !== 'EEXIST')
+            if (!isLockContention(error?.code))
                 throw error;
             await delay(10);
         }

package/dist/firewall/trusted-control.test.js

@@ -176,3 +176,13 @@ describe('action normalization and receipts', () => {
         expect(await verifyExecutionReceiptChain(cwd, root)).toMatchObject({ valid: true, count: 1 });
     });
 });
+describe('receipt lock contention', () => {
+    it('retries while another append releases the lock, including Windows delete-pending errors', async () => {
+        const { isLockContention } = await import('./execution-receipt.js');
+        expect(isLockContention('EEXIST', 'linux')).toBe(true);
+        expect(isLockContention('EPERM', 'win32')).toBe(true);
+        expect(isLockContention('EBUSY', 'win32')).toBe(true);
+        expect(isLockContention('EPERM', 'linux')).toBe(false); // a real permission error elsewhere
+        expect(isLockContention('ENOENT', 'win32')).toBe(false);
+    });
+});

package/dist/hooks/checker.js

@@ -249,6 +249,24 @@ function checkSecurityPatterns(lines, relPath, failures) {
         checkHardcodedSecrets(line, i, relPath, isTestFile, failures);
         checkCommandInjection(line, i, relPath, failures);
     }
+    if (!isTestFile)
+        checkVendorKeys(lines.join('\n'), relPath, failures);
+}
+/** Credential formats a vendor issues: unambiguous in code, unlike entropy or variable-name guesses. */
+const VENDOR_KEYS = new Set(['aws_access_key', 'openai_key', 'anthropic_key', 'github_token', 'stripe_key', 'slack_token', 'sendgrid_key', 'private_key', 'private_key_full']);
+/** A real vendor key written into code, whatever the variable is called. */
+function checkVendorKeys(content, relPath, failures) {
+    for (const detection of scanInputForCredentials(content).detections) {
+        if (!VENDOR_KEYS.has(detection.type) || !detection.position)
+            continue;
+        const raw = content.slice(detection.position.start, detection.position.end);
+        if (/^pk_|_test_/.test(raw))
+            continue; // publishable and test keys are meant to be shared
+        const line = content.slice(0, detection.position.start).split('\n').length;
+        if (failures.some(f => f.gate === 'security-patterns' && f.line === line))
+            continue;
+        failures.push({ gate: 'security-patterns', file: relPath, message: `${detection.description} in code`, severity: 'critical', line });
+    }
 }
 function checkHardcodedSecrets(line, i, relPath, isTestFile, failures) {
     if (isTestFile) {

package/dist/hooks/checker.test.js

@@ -51,6 +51,16 @@ describe('runHookChecker', () => {
         expect(result.status).toBe('fail');
         expect(result.failures[0]).toMatchObject({ gate: 'file-guard', severity: 'critical' });
     });
+    it('catches a real vendor key whatever it is named, and leaves publishable and test keys alone', async () => {
+        // Built at runtime: a key-shaped literal in this source would be (rightly) refused by secret scanning.
+        const fake = (prefix) => `${prefix}_${'51HxQ'}${'abcdefghijklmnopqrstuv'}`;
+        fs.writeFileSync(path.join(testDir, 'pay.ts'), `export const stripe = {\n  value: "${fake('sk_live')}",\n};\n`);
+        fs.writeFileSync(path.join(testDir, 'public.ts'), `export const key = "${fake('pk_live')}";\nexport const t = "${fake('sk_test')}";\n`);
+        const leaked = await runHookChecker({ cwd: testDir, files: ['pay.ts'] });
+        expect(leaked.failures).toEqual([expect.objectContaining({ gate: 'security-patterns', line: 2, severity: 'critical', message: 'Stripe API key detected in code' })]);
+        const fine = await runHookChecker({ cwd: testDir, files: ['public.ts'] });
+        expect(fine.failures.filter(f => f.gate === 'security-patterns')).toEqual([]);
+    });
     it('should detect file size violations', async () => {
         const filePath = path.join(testDir, 'big.ts');
         const lines = Array.from({ length: 100 }, (_, i) => `export const v${i} = ${i};`);

package/dist/index.d.ts

@@ -29,8 +29,10 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection, type LessonMode } from './review-learning/team-lessons.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules, type RepoRule } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError, type DiffSource } from './review/git-diff.js';
-export { checkPrecisions, checkId, precisionOf, isMuted, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';
-export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW, type CheckPrecision, type CheckOutcome } from './review/check-outcomes.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, listOpenFindings, type ResolvedFix, type FixCapture } from './review/agent-fixes.js';
+export { appendStory, readStories, compactDiff, STORIES_FILE, type Story, type CatchStage } from './review/stories.js';
+export { recordLessonsServed, recordPrCatches, recordReuseSuggested, type LessonChannel } from './review/learning-events.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';
@@ -46,6 +48,7 @@ export { isModelCached, getModelsDir, getModelInfo, getCachedModel, ensureModel
 export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './inference/llama-engine.js';
 export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
+export { cleanContextCache, deadCacheRows, type CacheCleanupReport } from './storage/index.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 export type { RigourDB, CompactResult } from './storage/index.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';

package/dist/index.js

@@ -29,8 +29,10 @@ export { readLessons, writeLessons, promoteLesson, matchLessons, lessonText, les
 export { lessonsForDiff, lessonsSection } from './review-learning/team-lessons.js';
 export { readRepoRules, rulesForDiff, rulesSection, splitRules } from './review-learning/repo-rules.js';
 export { diffFromGit, GitDiffError } from './review/git-diff.js';
-export { checkPrecisions, checkId, precisionOf, isMuted, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';
-export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount } from './review/agent-fixes.js';
+export { checkPrecisions, checkId, precisionOf, isMuted, readOutcomes, MUTE_MIN_OUTCOMES, MUTE_BELOW } from './review/check-outcomes.js';
+export { recordReviewOutcome, listResolvedFixes, removeResolvedFix, openFindingCount, listOpenFindings } from './review/agent-fixes.js';
+export { appendStory, readStories, compactDiff, STORIES_FILE } from './review/stories.js';
+export { recordLessonsServed, recordPrCatches, recordReuseSuggested } from './review/learning-events.js';
 export { computeEffectiveness, readAgentEvents, appendAgentEvent, findingKeys } from './review/effectiveness.js';
 export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
@@ -47,6 +49,7 @@ export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG }
 export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 // Storage (SQLite Brain)
+export { cleanContextCache, deadCacheRows } from './storage/index.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';

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

@@ -1,4 +1,18 @@
 import type { Failure } from '../types/index.js';
+import { type CatchStage } from './stories.js';
+interface OpenFinding {
+    file: string;
+    rule: string;
+    /** What the finding said; absent in entries captured before it was kept. */
+    title?: string;
+    details?: string;
+    before: string;
+    openedAt: string;
+    /** The stage that first reported it; absent in entries captured before stages were kept. */
+    stage?: CatchStage;
+    /** Its dismissal key (quiet.ts): a finding someone dismissed was not fixed. */
+    key?: string;
+}
 export interface ResolvedFix {
     id: string;
     file: string;
@@ -8,6 +22,9 @@ export interface ResolvedFix {
     before: string;
     after: string;
     resolvedAt: string;
+    stage?: CatchStage;
+    /** When the finding was first reported, for time to fix. */
+    openedAt?: string;
 }
 export interface FixCapture {
     opened: number;
@@ -15,8 +32,14 @@ export interface FixCapture {
     /** The fixes this review resolved, for turning into lessons (storage/fix-lessons.ts). */
     fixes: ResolvedFix[];
 }
-/** 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;
+/**
+ * Record a review's findings: open new ones, resolve open ones the review no longer reports.
+ * Each resolved fix is also kept as a story, credited to the stage that first reported it.
+ */
+export declare function recordReviewOutcome(cwd: string, findings: Failure[], reviewedFiles: string[], stage?: CatchStage): FixCapture;
 export declare function listResolvedFixes(cwd: string): ResolvedFix[];
 export declare function removeResolvedFix(cwd: string, id: string): void;
 export declare function openFindingCount(cwd: string): number;
+/** Findings reported and not fixed yet, newest first: what still needs someone. */
+export declare function listOpenFindings(cwd: string): Array<Omit<OpenFinding, 'before'>>;
+export {};

package/dist/review/agent-fixes.js

@@ -14,24 +14,37 @@ import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { checkId, recordOutcome } from './check-outcomes.js';
+import { appendStory, compactDiff } from './stories.js';
+import { dismissedKeys, findingKey } from './quiet.js';
 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) {
+/**
+ * Record a review's findings: open new ones, resolve open ones the review no longer reports.
+ * Each resolved fix is also kept as a story, credited to the stage that first reported it.
+ */
+export function recordReviewOutcome(cwd, findings, reviewedFiles, stage = 'review') {
     const open = readOpen(cwd);
     const current = new Map(findings.flatMap(f => (f.files?.[0] ? [[`${f.id}:${f.files[0]}`, f]] : [])));
     const fixes = resolveGone(cwd, open, current, new Set(reviewedFiles));
-    const opened = openNew(cwd, open, current);
+    for (const fix of fixes) {
+        appendStory(cwd, { at: fix.resolvedAt, openedAt: fix.openedAt, stage: fix.stage ?? stage, file: fix.file, rule: fix.rule, title: fix.title ?? fix.rule, details: fix.details, diff: compactDiff(fix.before, fix.after) });
+    }
+    const opened = openNew(cwd, open, current, stage);
     writeOpen(cwd, open);
     return { opened, resolved: fixes.length, fixes };
 }
 /** Open findings this review no longer reports: resolved when their file was reviewed and changed. */
 function resolveGone(cwd, open, current, reviewed) {
     const resolved = [];
+    const dismissed = dismissedKeys(cwd);
     for (const [key, entry] of Object.entries(open)) {
         if (current.has(key))
             continue;
+        if (entry.key && dismissed.has(entry.key)) {
+            delete open[key]; // gone because a person dismissed it, not because anyone fixed it
+            continue;
+        }
         if (!reviewed.has(entry.file)) {
             if (Date.now() - Date.parse(entry.openedAt) > OPEN_TTL_MS)
                 delete open[key];
@@ -46,7 +59,7 @@ function resolveGone(cwd, open, current, reviewed) {
     }
     return resolved;
 }
-function openNew(cwd, open, current) {
+function openNew(cwd, open, current, stage) {
     let opened = 0;
     for (const [key, finding] of current) {
         if (open[key])
@@ -55,7 +68,7 @@ function openNew(cwd, open, current) {
         const before = readSmall(cwd, file);
         if (before === null)
             continue;
-        open[key] = { file, rule: finding.id, title: finding.title, details: finding.details, before, openedAt: new Date().toISOString() };
+        open[key] = { file, rule: finding.id, title: finding.title, details: finding.details, before, openedAt: new Date().toISOString(), stage, key: findingKey(finding) };
         opened++;
     }
     return opened;
@@ -79,6 +92,14 @@ export function removeResolvedFix(cwd, id) {
 export function openFindingCount(cwd) {
     return Object.keys(readOpen(cwd)).length;
 }
+/** Findings reported and not fixed yet, newest first: what still needs someone. */
+export function listOpenFindings(cwd) {
+    const dismissed = dismissedKeys(cwd);
+    return Object.values(readOpen(cwd))
+        .filter(entry => !(entry.key && dismissed.has(entry.key)))
+        .map(({ before: _before, ...rest }) => rest)
+        .sort((a, b) => b.openedAt.localeCompare(a.openedAt));
+}
 function readOpen(cwd) {
     try {
         return JSON.parse(fs.readFileSync(path.join(cwd, DIR, 'open.json'), 'utf8'));
@@ -98,7 +119,7 @@ function writeOpen(cwd, open) {
 }
 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, title: entry.title, details: entry.details, before: entry.before, after, resolvedAt: new Date().toISOString() };
+    const fix = { id, file: entry.file, rule: entry.rule, title: entry.title, details: entry.details, before: entry.before, after, resolvedAt: new Date().toISOString(), ...(entry.stage ? { stage: entry.stage } : {}), openedAt: entry.openedAt };
     try {
         fs.mkdirSync(path.join(cwd, DIR, 'resolved'), { recursive: true });
         fs.writeFileSync(path.join(cwd, DIR, 'resolved', `${id}.json`), JSON.stringify(fix));

package/dist/review/effectiveness.d.ts

@@ -11,6 +11,19 @@ export interface AgentEvent {
     blocked?: boolean;
     /** Findings that blocked a stop. */
     blocking?: number;
+    /** lessons_served: where the agent got them, and their subjects (learning-events.ts). */
+    via?: string;
+    lessons?: string[];
+    /** pr_catches: what a branch review reported. */
+    findings?: Array<{
+        rule: string;
+        title: string;
+        file: string;
+    }>;
+    /** reuse_suggested: what the agent was about to write, what already exists, and BLOCK or WARN. */
+    planned?: string;
+    existing?: string;
+    action?: string;
 }
 export interface ReviewEffectiveness {
     toolCalls: Record<string, number>;

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

@@ -0,0 +1,14 @@
+/**
+ * The two events the learning loop is measured by, written to the same local event log as every
+ * agent event: a lesson put in front of an agent, and findings a PR-scope review reported.
+ * Studio joins them with stories (stories.ts) to show each lesson's path from where it was
+ * learned to whether the same mistake still reaches a PR.
+ */
+import type { Failure } from '../types/index.js';
+export type LessonChannel = 'recall' | 'context' | 'review';
+/** Lessons an agent was given before or while writing code. Nothing is written when none were. */
+export declare function recordLessonsServed(cwd: string, via: LessonChannel, subjects: string[]): void;
+/** Findings a review of a whole branch (what a PR contains) reported. Nothing is written when clean. */
+export declare function recordPrCatches(cwd: string, findings: Failure[]): void;
+/** The agent was about to write something that already exists, and was pointed to it. */
+export declare function recordReuseSuggested(cwd: string, planned: string, existing: string, action: 'BLOCK' | 'WARN'): void;

package/dist/review/learning-events.js

@@ -0,0 +1,21 @@
+import { appendAgentEvent } from './effectiveness.js';
+const MAX_LISTED = 20;
+/** Lessons an agent was given before or while writing code. Nothing is written when none were. */
+export function recordLessonsServed(cwd, via, subjects) {
+    const unique = [...new Set(subjects.filter(Boolean))].slice(0, MAX_LISTED);
+    if (unique.length)
+        appendAgentEvent(cwd, { type: 'lessons_served', via, lessons: unique });
+}
+/** Findings a review of a whole branch (what a PR contains) reported. Nothing is written when clean. */
+export function recordPrCatches(cwd, findings) {
+    if (findings.length === 0)
+        return;
+    appendAgentEvent(cwd, {
+        type: 'pr_catches',
+        findings: findings.slice(0, MAX_LISTED).map(f => ({ rule: f.id, title: f.title, file: f.files?.[0] ?? '' })),
+    });
+}
+/** The agent was about to write something that already exists, and was pointed to it. */
+export function recordReuseSuggested(cwd, planned, existing, action) {
+    appendAgentEvent(cwd, { type: 'reuse_suggested', planned, existing, action });
+}

package/dist/review/stories.d.ts

@@ -0,0 +1,25 @@
+/** Where a problem was caught: while the agent wrote, when it asked to review, when it tried to finish, at the PR. */
+export type CatchStage = 'edit' | 'review' | 'stop' | 'pr';
+export interface Story {
+    id: string;
+    /** When the agent fixed it. */
+    at: string;
+    /** When Rigour first reported it; absent in stories kept before this was recorded. */
+    openedAt?: string;
+    stage: CatchStage;
+    file: string;
+    rule: string;
+    title: string;
+    details?: string;
+    /** Changed lines with context, each prefixed ' ', '-' or '+'. */
+    diff: string[];
+}
+export declare const STORIES_FILE: string;
+export declare function appendStory(cwd: string, story: Omit<Story, 'id'>): void;
+/** Every story, oldest first; `since` keeps those at or after it. */
+export declare function readStories(cwd: string, since?: Date): Story[];
+/**
+ * The lines that changed between two versions of a file, with context: the common head and
+ * tail are trimmed and what is left between them is shown as removed then added.
+ */
+export declare function compactDiff(before: string, after: string): string[];

package/dist/review/stories.js

@@ -0,0 +1,75 @@
+/**
+ * What Rigour stopped, as people read it: one entry per problem an agent fixed after Rigour
+ * reported it, with the stage that caught it and the code change that fixed it.
+ *
+ * agent-fixes.ts keeps the before and after only until `rigour learn` turns them into rules;
+ * this log keeps a small, permanent summary for Studio. It never holds whole files: only the
+ * changed lines with a little context, capped.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+export const STORIES_FILE = path.join('.rigour', 'stories.jsonl');
+/** Kept on disk; older entries are dropped when the log is rewritten. */
+const MAX_STORIES = 500;
+const CONTEXT_LINES = 2;
+const MAX_DIFF_LINES = 40;
+const MAX_LINE_CHARS = 200;
+export function appendStory(cwd, story) {
+    const entry = { id: crypto.createHash('sha256').update(`${story.at}\0${story.file}\0${story.rule}`).digest('hex').slice(0, 16), ...story };
+    const file = path.join(cwd, STORIES_FILE);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        trim(file);
+    }
+    catch {
+        // Stories are a view; failing to keep one must never break a review or a hook.
+    }
+}
+/** Every story, oldest first; `since` keeps those at or after it. */
+export function readStories(cwd, since) {
+    let lines;
+    try {
+        lines = fs.readFileSync(path.join(cwd, STORIES_FILE), 'utf8').split('\n');
+    }
+    catch {
+        return [];
+    }
+    const stories = lines.flatMap(line => {
+        try {
+            return line.trim() ? [JSON.parse(line)] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    return since ? stories.filter(s => Date.parse(s.at) >= since.getTime()) : stories;
+}
+/**
+ * The lines that changed between two versions of a file, with context: the common head and
+ * tail are trimmed and what is left between them is shown as removed then added.
+ */
+export function compactDiff(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head++;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail++;
+    const clip = (line) => (line.length > MAX_LINE_CHARS ? line.slice(0, MAX_LINE_CHARS) + '…' : line);
+    const lines = [
+        ...a.slice(Math.max(0, head - CONTEXT_LINES), head).map(l => ' ' + clip(l)),
+        ...a.slice(head, a.length - tail).map(l => '-' + clip(l)),
+        ...b.slice(head, b.length - tail).map(l => '+' + clip(l)),
+        ...a.slice(a.length - tail, Math.min(a.length, a.length - tail + CONTEXT_LINES)).map(l => ' ' + clip(l)),
+    ];
+    return lines.length > MAX_DIFF_LINES ? [...lines.slice(0, MAX_DIFF_LINES), ' …'] : lines;
+}
+function trim(file) {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > MAX_STORIES * 1.2)
+        fs.writeFileSync(file, lines.slice(-MAX_STORIES).join('\n') + '\n');
+}

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

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

package/dist/review/stories.test.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { recordReviewOutcome } from './agent-fixes.js';
+import { readAgentEvents } from './effectiveness.js';
+import { recordLessonsServed, recordPrCatches } from './learning-events.js';
+import { compactDiff, readStories } from './stories.js';
+let cwd;
+beforeEach(() => { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'stories-')); fs.mkdirSync(path.join(cwd, 'src')); });
+afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));
+const finding = (id, title) => ({ id, title, details: `${title}.`, severity: 'high', files: ['src/a.ts'], line: 2 });
+describe('compactDiff', () => {
+    it('keeps only the changed lines and two lines of context', () => {
+        const before = ['a', 'b', 'c', 'old', 'd', 'e', 'f'].join('\n');
+        const after = ['a', 'b', 'c', 'new', 'd', 'e', 'f'].join('\n');
+        expect(compactDiff(before, after)).toEqual([' b', ' c', '-old', '+new', ' d', ' e']);
+    });
+});
+describe('stories from fixes', () => {
+    it('credits a fix to the stage that first reported it, with the code change', () => {
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), "fetch(url, { headers });\n");
+        recordReviewOutcome(cwd, [finding('semantic-bugs', 'Credential header follows redirects')], ['src/a.ts'], 'edit');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), "fetch(url, { headers, redirect: 'error' });\n");
+        recordReviewOutcome(cwd, [], ['src/a.ts'], 'stop');
+        const [story] = readStories(cwd);
+        expect(story).toMatchObject({ stage: 'edit', file: 'src/a.ts', rule: 'semantic-bugs', title: 'Credential header follows redirects' });
+        expect(story.diff).toEqual(['-fetch(url, { headers });', "+fetch(url, { headers, redirect: 'error' });", ' ']);
+    });
+    it('writes no story for a finding someone dismissed, even after its file changed', async () => {
+        const { dismissFinding, findingKey } = await import('./quiet.js');
+        const f = finding('semantic-bugs', 'Looks risky');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'x\n');
+        recordReviewOutcome(cwd, [f], ['src/a.ts'], 'review');
+        dismissFinding(cwd, findingKey(f), 'intended');
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'y\n');
+        recordReviewOutcome(cwd, [], ['src/a.ts'], 'review');
+        expect(readStories(cwd)).toEqual([]);
+    });
+    it('writes no story while the finding is still open', () => {
+        fs.writeFileSync(path.join(cwd, 'src/a.ts'), 'x\n');
+        recordReviewOutcome(cwd, [finding('semantic-bugs', 'X')], ['src/a.ts'], 'review');
+        expect(readStories(cwd)).toEqual([]);
+    });
+});
+describe('learning events', () => {
+    it('records lessons served and PR catches, and nothing when there are none', () => {
+        recordLessonsServed(cwd, 'recall', []);
+        recordPrCatches(cwd, []);
+        expect(readAgentEvents(cwd)).toEqual([]);
+        recordLessonsServed(cwd, 'review', ['Never follow redirects with credentials', 'Never follow redirects with credentials']);
+        recordPrCatches(cwd, [finding('semantic-bugs', 'Unbounded query')]);
+        expect(readAgentEvents(cwd)).toEqual([
+            expect.objectContaining({ type: 'lessons_served', via: 'review', lessons: ['Never follow redirects with credentials'] }),
+            expect.objectContaining({ type: 'pr_catches', findings: [{ rule: 'semantic-bugs', title: 'Unbounded query', file: 'src/a.ts' }] }),
+        ]);
+    });
+});

package/dist/storage/cache-cleanup.d.ts

@@ -0,0 +1,19 @@
+/** Layers no reader uses (context/cache-engine.ts keeps only semantic and checkpoint). */
+export declare const DEAD_CACHE_TYPES: readonly ["static", "component"];
+export interface CacheCleanupReport {
+    removed: number;
+    kept: number;
+    sizeBefore: number;
+    sizeAfter: number;
+    vacuumed: boolean;
+    /** Why the file was not shrunk, when it was not. */
+    vacuumSkipped?: string;
+}
+/** How many dead rows the database holds, and its size on disk; null when there is no database. */
+export declare function deadCacheRows(dbPath?: string): Promise<{
+    rows: number;
+    bytes: number;
+} | null>;
+export declare function cleanContextCache(dbPath?: string, freeBytes?: typeof freeSpace): Promise<CacheCleanupReport>;
+declare function freeSpace(dir: string): number;
+export {};

package/dist/storage/cache-cleanup.js

@@ -0,0 +1,90 @@
+/**
+ * Removing context-cache rows nothing reads: the static and component layers that index sync wrote
+ * on every edit until it was removed (millions of rows, gigabytes, in real use).
+ *
+ * Built for a database that is large and a disk that is nearly full. Deleting the rows one by one
+ * would copy every changed page into the write-ahead log (as much again on disk); instead the rows
+ * worth keeping are set aside, the table is dropped (its pages are freed, not rewritten) and
+ * recreated. VACUUM, which hands the freed space back to the disk, needs room for a copy of what
+ * remains, so it runs only when that room exists.
+ */
+import fs from 'fs';
+import path from 'path';
+import { DB_PATH, openDatabase } from './db.js';
+/** Layers no reader uses (context/cache-engine.ts keeps only semantic and checkpoint). */
+export const DEAD_CACHE_TYPES = ['static', 'component'];
+const DEAD_LIST = DEAD_CACHE_TYPES.map(t => `'${t}'`).join(', ');
+/** VACUUM writes a copy of the live data; ask for that much free space, with headroom. */
+const VACUUM_HEADROOM = 1.2;
+/** How many dead rows the database holds, and its size on disk; null when there is no database. */
+export async function deadCacheRows(dbPath = DB_PATH) {
+    if (!fs.existsSync(dbPath))
+        return null;
+    const db = await openDatabase(dbPath);
+    if (!db)
+        return null;
+    try {
+        const row = await db.get(`SELECT COUNT(*) AS n FROM context_cache WHERE cache_type IN (${DEAD_LIST})`);
+        return { rows: Number(row?.n ?? 0), bytes: fileBytes(dbPath) };
+    }
+    finally {
+        await db.close();
+    }
+}
+export async function cleanContextCache(dbPath = DB_PATH, freeBytes = freeSpace) {
+    const sizeBefore = fileBytes(dbPath);
+    const db = await openDatabase(dbPath);
+    if (!db)
+        return { removed: 0, kept: 0, sizeBefore, sizeAfter: sizeBefore, vacuumed: false, vacuumSkipped: 'SQLite is not available' };
+    try {
+        const { removed, kept } = await dropDeadRows(db);
+        if (removed === 0)
+            return { removed, kept, sizeBefore, sizeAfter: sizeBefore, vacuumed: false, vacuumSkipped: 'nothing to remove' };
+        const live = await liveBytes(db);
+        const available = freeBytes(path.dirname(dbPath));
+        if (available < live * VACUUM_HEADROOM) {
+            return { removed, kept, sizeBefore, sizeAfter: fileBytes(dbPath), vacuumed: false,
+                vacuumSkipped: `needs about ${mb(live * VACUUM_HEADROOM)} free to shrink the file, ${mb(available)} available; the space is reused by Rigour either way` };
+        }
+        await db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        await db.exec('VACUUM');
+        await db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        return { removed, kept, sizeBefore, sizeAfter: fileBytes(dbPath), vacuumed: true };
+    }
+    finally {
+        await db.close();
+    }
+}
+/** Set the readable rows aside, drop the table, recreate it with its indexes, put them back. */
+async function dropDeadRows(db) {
+    return db.transaction(async (tx) => {
+        const removed = Number((await tx.get(`SELECT COUNT(*) AS n FROM context_cache WHERE cache_type IN (${DEAD_LIST})`))?.n ?? 0);
+        if (removed === 0)
+            return { removed, kept: 0 };
+        const schema = await tx.all(`SELECT sql FROM sqlite_master WHERE tbl_name = 'context_cache' AND sql IS NOT NULL ORDER BY type DESC`);
+        await tx.exec(`CREATE TEMP TABLE context_cache_keep AS SELECT * FROM context_cache WHERE cache_type NOT IN (${DEAD_LIST})`);
+        await tx.exec('DROP TABLE context_cache');
+        for (const { sql } of schema)
+            await tx.exec(sql); // the table first (type 'table' sorts after 'index' descending), then its indexes
+        await tx.exec('INSERT INTO context_cache SELECT * FROM context_cache_keep');
+        const kept = Number((await tx.get('SELECT COUNT(*) AS n FROM context_cache'))?.n ?? 0);
+        await tx.exec('DROP TABLE context_cache_keep');
+        return { removed, kept };
+    });
+}
+async function liveBytes(db) {
+    const pages = Number((await db.get('PRAGMA page_count'))?.page_count ?? 0);
+    const free = Number((await db.get('PRAGMA freelist_count'))?.freelist_count ?? 0);
+    const size = Number((await db.get('PRAGMA page_size'))?.page_size ?? 4096);
+    return (pages - free) * size;
+}
+function fileBytes(dbPath) {
+    return [dbPath, `${dbPath}-wal`].reduce((n, f) => n + (fs.existsSync(f) ? fs.statSync(f).size : 0), 0);
+}
+function freeSpace(dir) {
+    const stats = fs.statfsSync(dir);
+    return Number(stats.bavail) * Number(stats.bsize);
+}
+function mb(bytes) {
+    return bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(bytes / 1024 ** 2)} MB`;
+}

package/dist/storage/cache-cleanup.test.d.ts

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

package/dist/storage/cache-cleanup.test.js

@@ -0,0 +1,54 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { cleanContextCache, deadCacheRows } from './cache-cleanup.js';
+import { openDatabase } from './db.js';
+let dir;
+let dbPath;
+async function seed(rows) {
+    const db = (await openDatabase(dbPath));
+    // One transaction: row-at-a-time commits are slow enough on Windows to time the test out.
+    await db.exec('BEGIN');
+    for (const [key, type] of rows) {
+        await db.run(`INSERT INTO context_cache (cache_key, cache_type, repo, branch, dependency_fingerprint, payload_json, payload_tokens, created_at)
+             VALUES (?, ?, 'r', 'main', 'f', ?, 1, 0)`, key, type, JSON.stringify({ padding: 'x'.repeat(2000) }));
+    }
+    await db.exec('COMMIT');
+    await db.close();
+}
+beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cache-cleanup-')); // a temporary database: never ~/.rigour
+    dbPath = path.join(dir, 'rigour.db');
+});
+// Windows keeps a just-closed SQLite file locked for a moment: retry the removal instead of failing.
+afterEach(() => fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));
+// Real SQLite files on disk: slower on Windows runners than the 5 s default allows.
+describe('cleanContextCache', { timeout: 30_000 }, () => {
+    it('removes the unread layers, keeps the readable rows and the indexes, and shrinks the file', async () => {
+        await seed([
+            ...Array.from({ length: 200 }, (_, i) => [`static:${i}`, 'static']),
+            ...Array.from({ length: 200 }, (_, i) => [`component:${i}`, 'component']),
+            ['semantic:a', 'semantic'], ['checkpoint:b', 'checkpoint'],
+        ]);
+        expect(await deadCacheRows(dbPath)).toMatchObject({ rows: 400 });
+        const report = await cleanContextCache(dbPath, () => Number.MAX_SAFE_INTEGER);
+        expect(report).toMatchObject({ removed: 400, kept: 2, vacuumed: true });
+        expect(report.sizeAfter).toBeLessThan(report.sizeBefore);
+        const db = (await openDatabase(dbPath));
+        expect((await db.all('SELECT cache_key FROM context_cache ORDER BY cache_key')).map(r => r.cache_key)).toEqual(['checkpoint:b', 'semantic:a']);
+        expect((await db.all("SELECT name FROM sqlite_master WHERE tbl_name = 'context_cache' AND type = 'index'")).map(r => r.name)).toContain('idx_context_cache_type');
+        await db.close();
+        expect(await deadCacheRows(dbPath)).toMatchObject({ rows: 0 });
+    });
+    it('still removes the rows but leaves the file size alone when the disk lacks room to shrink it', async () => {
+        await seed([['static:1', 'static'], ['semantic:a', 'semantic']]);
+        const report = await cleanContextCache(dbPath, () => 0);
+        expect(report).toMatchObject({ removed: 1, kept: 1, vacuumed: false });
+        expect(report.vacuumSkipped).toContain('free to shrink the file');
+    });
+    it('does nothing when there is nothing to remove', async () => {
+        await seed([['semantic:a', 'semantic']]);
+        expect(await cleanContextCache(dbPath, () => 0)).toMatchObject({ removed: 0, vacuumed: false, vacuumSkipped: 'nothing to remove' });
+    });
+});

package/dist/storage/db.js

@@ -10,6 +10,7 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs-extra';
 import { createRequire } from 'module';
+import { rigourUserDir } from '../utils/user-state.js';
 // ---------------------------------------------------------------------------
 // Optional dynamic import of sqlite3
 // ---------------------------------------------------------------------------
@@ -42,7 +43,8 @@ function loadSqlite3() {
     sqlite3Module = null;
     return sqlite3Module;
 }
-const RIGOUR_DIR = path.join(os.homedir(), '.rigour');
+// RIGOUR_HOME when set (tests, sandboxes) so nothing but a real run touches ~/.rigour.
+const RIGOUR_DIR = rigourUserDir();
 const DB_PATH = path.join(RIGOUR_DIR, 'rigour.db');
 /** Current schema version — bump when adding migrations. */
 const SCHEMA_VERSION = 7;

package/dist/storage/index.d.ts

@@ -3,6 +3,7 @@
  * Everything in one file: ~/.rigour/rigour.db
  */
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, RIGOUR_DIR, DB_PATH } from './db.js';
+export { cleanContextCache, deadCacheRows, DEAD_CACHE_TYPES, type CacheCleanupReport } from './cache-cleanup.js';
 export type { RigourDB, CompactResult } from './db.js';
 export { insertScan, getRecentScans, getScoreTrendFromDB, getTopIssues } from './scans.js';
 export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.js';

package/dist/storage/index.js

@@ -3,6 +3,7 @@
  * Everything in one file: ~/.rigour/rigour.db
  */
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, RIGOUR_DIR, DB_PATH } from './db.js';
+export { cleanContextCache, deadCacheRows, DEAD_CACHE_TYPES } from './cache-cleanup.js';
 export { insertScan, getRecentScans, getScoreTrendFromDB, getTopIssues } from './scans.js';
 export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.js';
 export { reinforcePattern, decayPatterns, getStrongPatterns, getPatterns, getHardRules } from './patterns.js';

package/dist/storage/local-encryption.js

@@ -1,9 +1,9 @@
 import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
 import { chmod, link, readFile, unlink, writeFile } from 'node:fs/promises';
 import fs from 'fs-extra';
-import os from 'os';
 import path from 'path';
-const KEY_PATH = path.join(os.homedir(), '.rigour', 'team-cache.key');
+import { rigourUserDir } from '../utils/user-state.js';
+const KEY_PATH = path.join(rigourUserDir(), 'team-cache.key');
 let fileKeyPromise;
 function decodeKey(value, source) {
     const normalized = value.trim();

package/dist/storage/team-store.js

@@ -1,17 +1,17 @@
 import fs from 'fs-extra';
-import os from 'os';
 import path from 'path';
 import { openDatabase } from './db.js';
 import { decryptLocalPayload, encryptLocalPayload } from './local-encryption.js';
 import { TEAM_SCHEMA } from './team-schema.js';
 import { diagnoseMissingMembership, explainTeamConnectionError } from './team-diagnostics.js';
+import { rigourUserDir } from '../utils/user-state.js';
 import { TEAM_VECTOR_SCHEMA, backfillConfiguredTeamEmbeddings, getTeamSemanticHealth, searchConfiguredTeamKnowledge, upsertTeamLessonEmbedding, } from './team-vector-store.js';
 const DEFAULT_SEMANTIC = {
     provider: 'pgvector',
     model: 'Xenova/all-MiniLM-L6-v2',
     dimensions: 384,
 };
-export const TEAM_CONFIG_PATH = path.join(os.homedir(), '.rigour', 'team.json');
+export const TEAM_CONFIG_PATH = path.join(rigourUserDir(), 'team.json');
 function nonEmpty(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }

package/dist/utils/user-state.js

@@ -13,7 +13,7 @@ export function rigourUserDir() {
 export function repoStateDir(cwd) {
     let root = path.resolve(cwd);
     try {
-        root = fs.realpathSync(root);
+        root = fs.realpathSync.native(root);
     }
     catch { /* not created yet: the resolved path is the key */ }
     const key = crypto.createHash('sha256').update(root).digest('hex').slice(0, 16);

package/package.json

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