@rigour-labs/core 2.22.0 → 3.0.0

package/src/gates/checkpoint.ts

@@ -1,311 +0,0 @@
-/**
- * Checkpoint Supervision Gate
- * 
- * Monitors agent quality during extended execution for frontier models
- * like GPT-5.3-Codex "coworking mode" that run autonomously for long periods.
- * 
- * Features:
- * - Time-based checkpoint triggers
- * - Quality score tracking
- * - Drift detection (quality degradation over time)
- * - Auto-save on failure
- * 
- * @since v2.14.0
- */
-
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { Logger } from '../utils/logger.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-export interface CheckpointEntry {
-    checkpointId: string;
-    timestamp: Date;
-    progressPct: number;
-    filesChanged: string[];
-    summary: string;
-    qualityScore: number;
-    warnings: string[];
-}
-
-export interface CheckpointSession {
-    sessionId: string;
-    startedAt: Date;
-    lastCheckpoint?: Date;
-    checkpoints: CheckpointEntry[];
-    status: 'active' | 'completed' | 'aborted';
-}
-
-export interface CheckpointConfig {
-    enabled?: boolean;
-    interval_minutes?: number;
-    quality_threshold?: number;
-    drift_detection?: boolean;
-    auto_save_on_failure?: boolean;
-}
-
-// In-memory checkpoint store (persisted to .rigour/checkpoint-session.json)
-let currentCheckpointSession: CheckpointSession | null = null;
-
-/**
- * Generate unique checkpoint ID
- */
-function generateCheckpointId(): string {
-    return `cp-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`;
-}
-
-/**
- * Get or create checkpoint session
- */
-export function getOrCreateCheckpointSession(cwd: string): CheckpointSession {
-    if (!currentCheckpointSession) {
-        loadCheckpointSession(cwd);
-    }
-    if (!currentCheckpointSession) {
-        currentCheckpointSession = {
-            sessionId: `chk-session-${Date.now()}`,
-            startedAt: new Date(),
-            checkpoints: [],
-            status: 'active',
-        };
-        persistCheckpointSession(cwd);
-    }
-    return currentCheckpointSession;
-}
-
-/**
- * Record a checkpoint with quality evaluation
- */
-export function recordCheckpoint(
-    cwd: string,
-    progressPct: number,
-    filesChanged: string[],
-    summary: string,
-    qualityScore: number
-): { continue: boolean; warnings: string[]; checkpoint: CheckpointEntry } {
-    const session = getOrCreateCheckpointSession(cwd);
-    const warnings: string[] = [];
-
-    // Default threshold
-    const qualityThreshold = 80;
-
-    // Check if quality is below threshold
-    const shouldContinue = qualityScore >= qualityThreshold;
-    if (!shouldContinue) {
-        warnings.push(`Quality score ${qualityScore}% is below threshold ${qualityThreshold}%`);
-    }
-
-    // Detect drift (quality degradation over recent checkpoints)
-    if (session.checkpoints.length >= 2) {
-        const recentScores = session.checkpoints.slice(-3).map(cp => cp.qualityScore);
-        const avgRecent = recentScores.reduce((a, b) => a + b, 0) / recentScores.length;
-
-        if (qualityScore < avgRecent - 10) {
-            warnings.push(`Drift detected: quality dropped from avg ${avgRecent.toFixed(0)}% to ${qualityScore}%`);
-        }
-    }
-
-    const checkpoint: CheckpointEntry = {
-        checkpointId: generateCheckpointId(),
-        timestamp: new Date(),
-        progressPct,
-        filesChanged,
-        summary,
-        qualityScore,
-        warnings,
-    };
-
-    session.checkpoints.push(checkpoint);
-    session.lastCheckpoint = new Date();
-    persistCheckpointSession(cwd);
-
-    return { continue: shouldContinue, warnings, checkpoint };
-}
-
-/**
- * Get current checkpoint session
- */
-export function getCheckpointSession(cwd: string): CheckpointSession | null {
-    if (!currentCheckpointSession) {
-        loadCheckpointSession(cwd);
-    }
-    return currentCheckpointSession;
-}
-
-/**
- * Complete checkpoint session
- */
-export function completeCheckpointSession(cwd: string): void {
-    if (currentCheckpointSession) {
-        currentCheckpointSession.status = 'completed';
-        persistCheckpointSession(cwd);
-    }
-}
-
-/**
- * Abort checkpoint session (quality too low)
- */
-export function abortCheckpointSession(cwd: string, reason: string): void {
-    if (currentCheckpointSession) {
-        currentCheckpointSession.status = 'aborted';
-        // Add final checkpoint with abort reason
-        currentCheckpointSession.checkpoints.push({
-            checkpointId: generateCheckpointId(),
-            timestamp: new Date(),
-            progressPct: currentCheckpointSession.checkpoints.length > 0
-                ? currentCheckpointSession.checkpoints[currentCheckpointSession.checkpoints.length - 1].progressPct
-                : 0,
-            filesChanged: [],
-            summary: `Session aborted: ${reason}`,
-            qualityScore: 0,
-            warnings: [reason],
-        });
-        persistCheckpointSession(cwd);
-    }
-}
-
-/**
- * Clear checkpoint session
- */
-export function clearCheckpointSession(cwd: string): void {
-    currentCheckpointSession = null;
-    const sessionPath = path.join(cwd, '.rigour', 'checkpoint-session.json');
-    if (fs.existsSync(sessionPath)) {
-        fs.unlinkSync(sessionPath);
-    }
-}
-
-function persistCheckpointSession(cwd: string): void {
-    const rigourDir = path.join(cwd, '.rigour');
-    if (!fs.existsSync(rigourDir)) {
-        fs.mkdirSync(rigourDir, { recursive: true });
-    }
-    const sessionPath = path.join(rigourDir, 'checkpoint-session.json');
-    fs.writeFileSync(sessionPath, JSON.stringify(currentCheckpointSession, null, 2));
-}
-
-function loadCheckpointSession(cwd: string): void {
-    const sessionPath = path.join(cwd, '.rigour', 'checkpoint-session.json');
-    if (fs.existsSync(sessionPath)) {
-        try {
-            const data = JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
-            currentCheckpointSession = {
-                ...data,
-                startedAt: new Date(data.startedAt),
-                lastCheckpoint: data.lastCheckpoint ? new Date(data.lastCheckpoint) : undefined,
-                checkpoints: data.checkpoints.map((cp: any) => ({
-                    ...cp,
-                    timestamp: new Date(cp.timestamp),
-                })),
-            };
-        } catch (err) {
-            Logger.warn('Failed to load checkpoint session, starting fresh');
-            currentCheckpointSession = null;
-        }
-    }
-}
-
-/**
- * Calculate time since last checkpoint
- */
-function timeSinceLastCheckpoint(session: CheckpointSession): number {
-    const lastTime = session.lastCheckpoint || session.startedAt;
-    return (Date.now() - lastTime.getTime()) / 1000 / 60; // minutes
-}
-
-/**
- * Detect quality drift pattern
- */
-function detectDrift(checkpoints: CheckpointEntry[]): { hasDrift: boolean; trend: 'improving' | 'stable' | 'degrading' } {
-    if (checkpoints.length < 3) {
-        return { hasDrift: false, trend: 'stable' };
-    }
-
-    const recent = checkpoints.slice(-5);
-    const scores = recent.map(cp => cp.qualityScore);
-
-    // Calculate trend using simple linear regression
-    const n = scores.length;
-    const sumX = (n * (n - 1)) / 2;
-    const sumY = scores.reduce((a, b) => a + b, 0);
-    const sumXY = scores.reduce((sum, y, x) => sum + x * y, 0);
-    const sumX2 = (n * (n - 1) * (2 * n - 1)) / 6;
-
-    const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX);
-
-    if (slope < -2) {
-        return { hasDrift: true, trend: 'degrading' };
-    } else if (slope > 2) {
-        return { hasDrift: false, trend: 'improving' };
-    }
-    return { hasDrift: false, trend: 'stable' };
-}
-
-export class CheckpointGate extends Gate {
-    private config: CheckpointConfig;
-
-    constructor(config: CheckpointConfig = {}) {
-        super('checkpoint', 'Checkpoint Supervision');
-        this.config = {
-            enabled: config.enabled ?? false,
-            interval_minutes: config.interval_minutes ?? 15,
-            quality_threshold: config.quality_threshold ?? 80,
-            drift_detection: config.drift_detection ?? true,
-            auto_save_on_failure: config.auto_save_on_failure ?? true,
-        };
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        if (!this.config.enabled) {
-            return [];
-        }
-
-        const failures: Failure[] = [];
-        const session = getCheckpointSession(context.cwd);
-
-        if (!session || session.checkpoints.length === 0) {
-            // No checkpoints yet, skip
-            return [];
-        }
-
-        Logger.info(`Checkpoint Gate: ${session.checkpoints.length} checkpoints in session`);
-
-        // Check 1: Time since last checkpoint
-        const minutesSinceLast = timeSinceLastCheckpoint(session);
-        if (minutesSinceLast > (this.config.interval_minutes ?? 15) * 2) {
-            failures.push(this.createFailure(
-                `No checkpoint in ${minutesSinceLast.toFixed(0)} minutes (expected every ${this.config.interval_minutes} min)`,
-                undefined,
-                'Ensure agent is reporting checkpoints via rigour_checkpoint MCP tool',
-                'Missing Checkpoint'
-            ));
-        }
-
-        // Check 2: Quality threshold
-        const lastCheckpoint = session.checkpoints[session.checkpoints.length - 1];
-        if (lastCheckpoint.qualityScore < (this.config.quality_threshold ?? 80)) {
-            failures.push(this.createFailure(
-                `Quality score ${lastCheckpoint.qualityScore}% is below threshold ${this.config.quality_threshold}%`,
-                lastCheckpoint.filesChanged,
-                'Review recent changes and address quality issues before continuing',
-                'Quality Below Threshold'
-            ));
-        }
-
-        // Check 3: Drift detection
-        if (this.config.drift_detection) {
-            const { hasDrift, trend } = detectDrift(session.checkpoints);
-            if (hasDrift && trend === 'degrading') {
-                failures.push(this.createFailure(
-                    `Quality drift detected: scores are degrading over time`,
-                    undefined,
-                    'Agent performance is declining. Consider pausing and reviewing recent work.',
-                    'Quality Drift Detected'
-                ));
-            }
-        }
-
-        return failures;
-    }
-}

package/src/gates/content.ts

@@ -1,51 +0,0 @@
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { FileScanner } from '../utils/scanner.js';
-
-export interface ContentGateConfig {
-    forbidTodos: boolean;
-    forbidFixme: boolean;
-}
-
-export class ContentGate extends Gate {
-    constructor(private config: ContentGateConfig) {
-        super('content-check', 'Forbidden Content');
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        const patterns: RegExp[] = [];
-        if (this.config.forbidTodos) patterns.push(/TODO/i);
-        if (this.config.forbidFixme) patterns.push(/FIXME/i);
-
-        if (patterns.length === 0) return [];
-
-        const files = await FileScanner.findFiles({
-            cwd: context.cwd,
-            ignore: context.ignore,
-            patterns: context.patterns
-        });
-        const contents = await FileScanner.readFiles(context.cwd, files);
-
-        const failures: Failure[] = [];
-        for (const [file, content] of contents) {
-            const lines = content.split('\n');
-            lines.forEach((line, index) => {
-                for (const pattern of patterns) {
-                    if (pattern.test(line)) {
-                        failures.push(this.createFailure(
-                            `Forbidden placeholder '${pattern.source}' found`,
-                            [file],
-                            'Remove forbidden comments. address the root cause or create a tracked issue.',
-                            undefined,
-                            index + 1,
-                            index + 1,
-                            'info'
-                        ));
-                    }
-                }
-            });
-        }
-
-        return failures;
-    }
-}

package/src/gates/context-window-artifacts.ts

@@ -1,277 +0,0 @@
-/**
- * Context Window Artifacts Gate
- *
- * Detects quality degradation patterns within a single file that emerge
- * when AI loses context mid-generation. The telltale sign: clean,
- * well-structured code at the top of a file that gradually degrades
- * toward the bottom.
- *
- * Detection signals:
- * 1. Comment density drops sharply (top half vs bottom half)
- * 2. Function complexity increases toward end of file
- * 3. Variable naming quality degrades (shorter names, more single-letter vars)
- * 4. Error handling becomes sparser toward the bottom
- * 5. Code style inconsistencies emerge (indentation, spacing)
- *
- * @since v2.16.0
- */
-
-import { Gate, GateContext } from './base.js';
-import { Failure } from '../types/index.js';
-import { FileScanner } from '../utils/scanner.js';
-import { Logger } from '../utils/logger.js';
-import fs from 'fs-extra';
-import path from 'path';
-
-interface FileQualityMetrics {
-    file: string;
-    totalLines: number;
-    topHalf: HalfMetrics;
-    bottomHalf: HalfMetrics;
-    degradationScore: number;  // 0-1, higher = more degradation
-    signals: string[];
-}
-
-interface HalfMetrics {
-    commentDensity: number;         // comments per code line
-    avgFunctionLength: number;      // average lines per function
-    singleCharVarCount: number;     // number of single-char variables
-    errorHandlingDensity: number;   // try/catch per function
-    emptyBlockCount: number;        // empty {} blocks
-    todoCount: number;              // TODO/FIXME/HACK comments
-    avgIdentifierLength: number;    // average variable/function name length
-}
-
-export interface ContextWindowArtifactsConfig {
-    enabled?: boolean;
-    min_file_lines?: number;           // Only analyze files with 100+ lines
-    degradation_threshold?: number;    // 0-1, flag if degradation > this, default 0.4
-    signals_required?: number;         // How many signals needed to flag, default 2
-}
-
-export class ContextWindowArtifactsGate extends Gate {
-    private config: Required<ContextWindowArtifactsConfig>;
-
-    constructor(config: ContextWindowArtifactsConfig = {}) {
-        super('context-window-artifacts', 'Context Window Artifact Detection');
-        this.config = {
-            enabled: config.enabled ?? true,
-            min_file_lines: config.min_file_lines ?? 100,
-            degradation_threshold: config.degradation_threshold ?? 0.4,
-            signals_required: config.signals_required ?? 2,
-        };
-    }
-
-    async run(context: GateContext): Promise<Failure[]> {
-        if (!this.config.enabled) return [];
-
-        const failures: Failure[] = [];
-
-        const files = await FileScanner.findFiles({
-            cwd: context.cwd,
-            patterns: ['**/*.{ts,js,tsx,jsx,py}'],
-            ignore: [...(context.ignore || []), '**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*', '**/*.min.*'],
-        });
-
-        Logger.info(`Context Window Artifacts: Scanning ${files.length} files`);
-
-        for (const file of files) {
-            try {
-                const content = await fs.readFile(path.join(context.cwd, file), 'utf-8');
-                const lines = content.split('\n');
-
-                if (lines.length < this.config.min_file_lines) continue;
-
-                const metrics = this.analyzeFile(content, file);
-                if (metrics && metrics.signals.length >= this.config.signals_required &&
-                    metrics.degradationScore >= this.config.degradation_threshold) {
-
-                    const signalList = metrics.signals.map(s => `  • ${s}`).join('\n');
-                    const midpoint = Math.floor(metrics.totalLines / 2);
-
-                    failures.push(this.createFailure(
-                        `Context window artifact detected in ${file} (${metrics.totalLines} lines, degradation: ${(metrics.degradationScore * 100).toFixed(0)}%):\n${signalList}`,
-                        [file],
-                        `This file shows quality degradation from top to bottom, a pattern typical of AI context window exhaustion. Consider refactoring the bottom half or splitting the file. The quality drop begins around line ${midpoint}.`,
-                        'Context Window Artifacts',
-                        midpoint,
-                        undefined,
-                        'high'
-                    ));
-                }
-            } catch (e) { }
-        }
-
-        return failures;
-    }
-
-    private analyzeFile(content: string, file: string): FileQualityMetrics | null {
-        const lines = content.split('\n');
-        const midpoint = Math.floor(lines.length / 2);
-
-        const topContent = lines.slice(0, midpoint).join('\n');
-        const bottomContent = lines.slice(midpoint).join('\n');
-
-        const topMetrics = this.measureHalf(topContent);
-        const bottomMetrics = this.measureHalf(bottomContent);
-
-        const signals: string[] = [];
-        let degradationScore = 0;
-
-        // Signal 1: Comment density drops
-        if (topMetrics.commentDensity > 0) {
-            const commentRatio = bottomMetrics.commentDensity / topMetrics.commentDensity;
-            if (commentRatio < 0.5) {
-                signals.push(`Comment density drops ${((1 - commentRatio) * 100).toFixed(0)}% in bottom half`);
-                degradationScore += 0.25;
-            }
-        }
-
-        // Signal 2: Function length increases
-        if (topMetrics.avgFunctionLength > 0 && bottomMetrics.avgFunctionLength > 0) {
-            const lengthRatio = bottomMetrics.avgFunctionLength / topMetrics.avgFunctionLength;
-            if (lengthRatio > 1.5) {
-                signals.push(`Average function length ${lengthRatio.toFixed(1)}x longer in bottom half`);
-                degradationScore += 0.2;
-            }
-        }
-
-        // Signal 3: Variable naming quality degrades
-        if (bottomMetrics.singleCharVarCount > topMetrics.singleCharVarCount * 2 &&
-            bottomMetrics.singleCharVarCount >= 3) {
-            signals.push(`${bottomMetrics.singleCharVarCount} single-char variables in bottom half vs ${topMetrics.singleCharVarCount} in top`);
-            degradationScore += 0.2;
-        }
-
-        // Signal 3b: Average identifier length shrinks
-        if (topMetrics.avgIdentifierLength > 0 && bottomMetrics.avgIdentifierLength > 0) {
-            const nameRatio = bottomMetrics.avgIdentifierLength / topMetrics.avgIdentifierLength;
-            if (nameRatio < 0.7) {
-                signals.push(`Identifier names ${((1 - nameRatio) * 100).toFixed(0)}% shorter in bottom half`);
-                degradationScore += 0.15;
-            }
-        }
-
-        // Signal 4: Error handling becomes sparser
-        if (topMetrics.errorHandlingDensity > 0) {
-            const errorRatio = bottomMetrics.errorHandlingDensity / topMetrics.errorHandlingDensity;
-            if (errorRatio < 0.3) {
-                signals.push(`Error handling ${((1 - errorRatio) * 100).toFixed(0)}% less frequent in bottom half`);
-                degradationScore += 0.2;
-            }
-        }
-
-        // Signal 5: Empty blocks increase
-        if (bottomMetrics.emptyBlockCount > topMetrics.emptyBlockCount + 2) {
-            signals.push(`${bottomMetrics.emptyBlockCount} empty blocks in bottom half vs ${topMetrics.emptyBlockCount} in top`);
-            degradationScore += 0.15;
-        }
-
-        // Signal 6: TODO/FIXME/HACK density increases at bottom
-        if (bottomMetrics.todoCount > topMetrics.todoCount + 1) {
-            signals.push(`${bottomMetrics.todoCount} TODO/FIXME/HACK in bottom half vs ${topMetrics.todoCount} in top`);
-            degradationScore += 0.1;
-        }
-
-        // Cap at 1.0
-        degradationScore = Math.min(1.0, degradationScore);
-
-        return {
-            file,
-            totalLines: lines.length,
-            topHalf: topMetrics,
-            bottomHalf: bottomMetrics,
-            degradationScore,
-            signals,
-        };
-    }
-
-    private measureHalf(content: string): HalfMetrics {
-        const lines = content.split('\n');
-        const codeLines = lines.filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('#') && !l.trim().startsWith('*'));
-        const commentLines = lines.filter(l => {
-            const trimmed = l.trim();
-            return trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('*') || trimmed.startsWith('/*');
-        });
-
-        // Comment density
-        const commentDensity = codeLines.length > 0 ? commentLines.length / codeLines.length : 0;
-
-        // Function lengths
-        const funcLengths = this.measureFunctionLengths(content);
-        const avgFunctionLength = funcLengths.length > 0
-            ? funcLengths.reduce((a, b) => a + b, 0) / funcLengths.length
-            : 0;
-
-        // Single-char variables (excluding common loop vars i, j, k in for loops)
-        const singleCharMatches = content.match(/\b(?:const|let|var)\s+([a-z])\b/g) || [];
-        const singleCharVarCount = singleCharMatches.length;
-
-        // Error handling density
-        const tryCount = (content.match(/\btry\s*\{/g) || []).length;
-        const funcCount = Math.max(1, funcLengths.length);
-        const errorHandlingDensity = tryCount / funcCount;
-
-        // Empty blocks
-        const emptyBlockCount = (content.match(/\{\s*\}/g) || []).length;
-
-        // TODO/FIXME/HACK count
-        const todoCount = (content.match(/\b(TODO|FIXME|HACK|XXX)\b/gi) || []).length;
-
-        // Average identifier length
-        const identifiers = content.match(/\b(?:const|let|var|function)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g) || [];
-        const identNames = identifiers.map(m => {
-            const parts = m.split(/\s+/);
-            return parts[parts.length - 1];
-        });
-        const avgIdentifierLength = identNames.length > 0
-            ? identNames.reduce((sum, n) => sum + n.length, 0) / identNames.length
-            : 0;
-
-        return {
-            commentDensity,
-            avgFunctionLength,
-            singleCharVarCount,
-            errorHandlingDensity,
-            emptyBlockCount,
-            todoCount,
-            avgIdentifierLength,
-        };
-    }
-
-    private measureFunctionLengths(content: string): number[] {
-        const lines = content.split('\n');
-        const lengths: number[] = [];
-
-        const funcStarts = [
-            /^(?:export\s+)?(?:async\s+)?function\s+\w+/,
-            /^(?:export\s+)?(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?(?:\([^)]*\)|\w+)\s*=>/,
-            /^\s+(?:async\s+)?\w+\s*\([^)]*\)\s*\{/,
-        ];
-
-        for (let i = 0; i < lines.length; i++) {
-            for (const pattern of funcStarts) {
-                if (pattern.test(lines[i])) {
-                    // Count function body length
-                    let braceDepth = 0;
-                    let started = false;
-                    let bodyLines = 0;
-
-                    for (let j = i; j < lines.length; j++) {
-                        for (const ch of lines[j]) {
-                            if (ch === '{') { braceDepth++; started = true; }
-                            if (ch === '}') braceDepth--;
-                        }
-                        if (started) bodyLines++;
-                        if (started && braceDepth === 0) break;
-                    }
-
-                    if (bodyLines > 0) lengths.push(bodyLines);
-                    break;
-                }
-            }
-        }
-
-        return lengths;
-    }
-}