@rigour-labs/core 4.3.6 → 5.0.0

package/dist/services/adaptive-thresholds.js

@@ -1,21 +1,59 @@
 /**
- * Adaptive Thresholds Service
+ * Adaptive Thresholds Service (v2)
  *
  * Dynamically adjusts quality gate thresholds based on:
  * - Project maturity (age, commit count, file count)
- * - Historical failure rates
+ * - Historical failure rates with Z-score anomaly detection
  * - Complexity tier (hobby/startup/enterprise)
- * - Recent trends (improving/degrading)
+ * - Per-provenance trend analysis (ai-drift, structural, security separate)
  *
- * This enables Rigour to be "strict but fair" - new projects get
- * more lenient thresholds while mature codebases are held to higher standards.
+ * v2 upgrades:
+ * - Z-score replaces naive delta comparison for trend detection
+ * - Per-provenance failure tracking (AI drift vs structural vs security)
+ * - Statistical anomaly detection normalizes across project sizes
  *
- * @since v2.14.0
+ * @since v2.14.0 (original)
+ * @since v5.0.0 (Z-score + provenance-aware trends)
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { Logger } from '../utils/logger.js';
 let cachedHistory = null;
+// ─── Statistical Utilities ──────────────────────────────────────────
+/**
+ * Compute mean and standard deviation of an array of numbers.
+ * Returns { mean: 0, std: 0 } for empty arrays.
+ */
+function meanAndStd(values) {
+    if (values.length === 0)
+        return { mean: 0, std: 0 };
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    return { mean, std: Math.sqrt(variance) };
+}
+/**
+ * Calculate Z-score for a value against a population.
+ * Z > 2.0 → statistically abnormal HIGH (degrading)
+ * Z < -2.0 → statistically abnormal LOW (improving)
+ * Returns 0 if std is 0 (all values identical).
+ */
+function zScore(value, mean, std) {
+    if (std === 0)
+        return 0;
+    return Math.round(((value - mean) / std) * 100) / 100;
+}
+/**
+ * Determine trend from Z-score.
+ * For failure counts: positive Z = more failures = degrading.
+ */
+function trendFromZScore(z) {
+    if (z > 2.0)
+        return 'degrading';
+    if (z < -2.0)
+        return 'improving';
+    return 'stable';
+}
+// ─── History Persistence ────────────────────────────────────────────
 /**
  * Load failure history from disk
  */
@@ -47,16 +85,19 @@ function saveHistory(cwd, history) {
     fs.writeFileSync(historyPath, JSON.stringify(history, null, 2));
     cachedHistory = history;
 }
+// ─── Public API ─────────────────────────────────────────────────────
 /**
- * Record a gate run for historical tracking
+ * Record a gate run for historical tracking.
+ * v5: accepts optional per-provenance breakdown.
  */
-export function recordGateRun(cwd, passedGates, failedGates, totalFailures) {
+export function recordGateRun(cwd, passedGates, failedGates, totalFailures, provenance) {
     const history = loadHistory(cwd);
     history.runs.push({
         timestamp: new Date().toISOString(),
         passedGates,
         failedGates,
         totalFailures,
+        provenance,
     });
     // Keep last 100 runs
     if (history.runs.length > 100) {
@@ -66,24 +107,82 @@ export function recordGateRun(cwd, passedGates, failedGates, totalFailures) {
     saveHistory(cwd, history);
 }
 /**
- * Get quality trend from historical data
+ * Get quality trend using Z-score analysis (v5).
+ *
+ * How it works:
+ * 1. Take the last N runs (baseline window, default 20)
+ * 2. Compute mean and std of failure counts
+ * 3. Take the most recent window (last 5 runs)
+ * 4. Compute the average failure count in the recent window
+ * 5. Z-score = (recent_avg - baseline_mean) / baseline_std
+ *
+ * Z > 2.0 → statistically abnormal spike → DEGRADING
+ * Z < -2.0 → statistically abnormal drop → IMPROVING
+ *
+ * Why better than delta: A project with 100 failures/run and a spike to 108
+ * is stable (Z ≈ 0.5). A project with 2 failures/run and a spike to 8
+ * is degrading (Z ≈ 3.0). Z-score normalizes for project size.
  */
 export function getQualityTrend(cwd) {
     const history = loadHistory(cwd);
-    if (history.runs.length < 5)
+    const RECENT_WINDOW = 5;
+    const MIN_BASELINE = 5;
+    // Need enough data for both a baseline and a separate recent window
+    if (history.runs.length < RECENT_WINDOW + MIN_BASELINE)
         return 'stable';
-    const recent = history.runs.slice(-10);
-    const older = history.runs.slice(-20, -10);
-    if (older.length === 0)
-        return 'stable';
-    const recentFailRate = recent.reduce((sum, r) => sum + r.totalFailures, 0) / recent.length;
-    const olderFailRate = older.reduce((sum, r) => sum + r.totalFailures, 0) / older.length;
-    const delta = recentFailRate - olderFailRate;
-    if (delta < -2)
-        return 'improving';
-    if (delta > 2)
-        return 'degrading';
-    return 'stable';
+    // Non-overlapping windows: baseline excludes recent to avoid Z-score compression.
+    // When recent data is part of the baseline, Z-scores are mathematically bounded
+    // at ~1.73 for a 5-of-20 overlap, which never exceeds the 2.0 threshold.
+    const recent = history.runs.slice(-RECENT_WINDOW);
+    const baseline = history.runs.slice(0, -RECENT_WINDOW);
+    const baselineFailures = baseline.map(r => r.totalFailures);
+    const { mean, std } = meanAndStd(baselineFailures);
+    const recentAvg = recent.reduce((sum, r) => sum + r.totalFailures, 0) / recent.length;
+    const z = zScore(recentAvg, mean, std);
+    return trendFromZScore(z);
+}
+/**
+ * Get per-provenance trend analysis (v5).
+ *
+ * Runs separate Z-score analysis for each provenance category.
+ * This is the core differentiator: Rigour can tell you
+ * "your AI is getting worse" separately from "your code quality is dropping."
+ *
+ * Falls back gracefully for legacy history data without provenance.
+ */
+export function getProvenanceTrends(cwd) {
+    const history = loadHistory(cwd);
+    // Filter to runs that have provenance data (v5+ only)
+    const withProvenance = history.runs.filter(r => r.provenance);
+    const RECENT_WINDOW = 5;
+    const MIN_BASELINE = 5;
+    if (withProvenance.length < RECENT_WINDOW + MIN_BASELINE) {
+        return {
+            aiDrift: 'stable', structural: 'stable', security: 'stable',
+            aiDriftZScore: 0, structuralZScore: 0, securityZScore: 0,
+        };
+    }
+    // Non-overlapping windows (consistent with getQualityTrend)
+    const recent = withProvenance.slice(-RECENT_WINDOW);
+    const baseline = withProvenance.slice(0, -RECENT_WINDOW);
+    const computeForField = (field) => {
+        const baselineValues = baseline.map(r => r.provenance[field]);
+        const { mean, std } = meanAndStd(baselineValues);
+        const recentAvg = recent.reduce((sum, r) => sum + r.provenance[field], 0) / recent.length;
+        const z = zScore(recentAvg, mean, std);
+        return { trend: trendFromZScore(z), z: Math.round(z * 100) / 100 };
+    };
+    const ai = computeForField('aiDriftFailures');
+    const structural = computeForField('structuralFailures');
+    const security = computeForField('securityFailures');
+    return {
+        aiDrift: ai.trend,
+        structural: structural.trend,
+        security: security.trend,
+        aiDriftZScore: ai.z,
+        structuralZScore: structural.z,
+        securityZScore: security.z,
+    };
 }
 /**
  * Detect project complexity tier based on metrics
@@ -101,7 +200,8 @@ export function detectComplexityTier(metrics) {
     return 'hobby';
 }
 /**
- * Calculate adaptive thresholds based on project state
+ * Calculate adaptive thresholds based on project state.
+ * v5: Uses Z-score trending and per-provenance analysis.
  */
 export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
     const reasoning = [];
@@ -109,9 +209,20 @@ export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
     const tier = config.forced_tier ??
         (config.auto_detect_tier !== false ? detectComplexityTier(metrics) : 'startup');
     reasoning.push(`Complexity tier: ${tier} (files: ${metrics.fileCount})`);
-    // Get trend
+    // Get overall trend (Z-score based)
     const trend = getQualityTrend(cwd);
-    reasoning.push(`Quality trend: ${trend}`);
+    reasoning.push(`Quality trend: ${trend} (Z-score analysis)`);
+    // Get per-provenance trends
+    const provenanceTrends = getProvenanceTrends(cwd);
+    if (provenanceTrends.aiDrift !== 'stable') {
+        reasoning.push(`AI drift trend: ${provenanceTrends.aiDrift} (Z=${provenanceTrends.aiDriftZScore})`);
+    }
+    if (provenanceTrends.structural !== 'stable') {
+        reasoning.push(`Structural trend: ${provenanceTrends.structural} (Z=${provenanceTrends.structuralZScore})`);
+    }
+    if (provenanceTrends.security !== 'stable') {
+        reasoning.push(`Security trend: ${provenanceTrends.security} (Z=${provenanceTrends.securityZScore})`);
+    }
     // Base thresholds
     let coverageThreshold = config.base_coverage_threshold ?? 80;
     let qualityThreshold = config.base_quality_threshold ?? 80;
@@ -120,15 +231,13 @@ export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
     // Adjust by tier
     switch (tier) {
         case 'hobby':
-            // Lenient for small/new projects
             coverageThreshold = Math.max(50, coverageThreshold - 30);
             qualityThreshold = Math.max(60, qualityThreshold - 20);
-            securityBlockLevel = 'critical'; // Only block on critical
+            securityBlockLevel = 'critical';
             leniencyFactor = 0.8;
             reasoning.push('Hobby tier: relaxed thresholds, only critical security blocks');
             break;
         case 'startup':
-            // Moderate strictness
             coverageThreshold = Math.max(60, coverageThreshold - 15);
             qualityThreshold = Math.max(70, qualityThreshold - 10);
             securityBlockLevel = 'high';
@@ -136,7 +245,6 @@ export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
             reasoning.push('Startup tier: moderate thresholds, high+ security blocks');
             break;
         case 'enterprise':
-            // Strict standards
             coverageThreshold = coverageThreshold;
             qualityThreshold = qualityThreshold;
             securityBlockLevel = 'medium';
@@ -144,30 +252,40 @@ export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
             reasoning.push('Enterprise tier: strict thresholds, medium+ security blocks');
             break;
     }
-    // Adjust by trend
+    // Adjust by overall trend
     if (trend === 'improving') {
-        // Reward improvement with slightly relaxed thresholds
         coverageThreshold = Math.max(50, coverageThreshold - 5);
         qualityThreshold = Math.max(60, qualityThreshold - 5);
         leniencyFactor = Math.min(1, leniencyFactor + 0.1);
         reasoning.push('Improving trend: bonus threshold relaxation (+5%)');
     }
     else if (trend === 'degrading') {
-        // Tighten thresholds to encourage recovery
         coverageThreshold = Math.min(95, coverageThreshold + 5);
         qualityThreshold = Math.min(95, qualityThreshold + 5);
         leniencyFactor = Math.max(0, leniencyFactor - 0.1);
         reasoning.push('Degrading trend: tightened thresholds (-5%)');
     }
+    // v5: Per-provenance adjustments
+    // If AI drift is degrading but structural is stable, tighten AI-specific gates
+    if (provenanceTrends.aiDrift === 'degrading' && provenanceTrends.structural !== 'degrading') {
+        leniencyFactor = Math.max(0, leniencyFactor - 0.15);
+        reasoning.push('AI drift degrading while structural stable: AI is the problem, tightening AI gates');
+    }
+    // If security is degrading, escalate security block level
+    if (provenanceTrends.security === 'degrading') {
+        if (securityBlockLevel === 'critical')
+            securityBlockLevel = 'high';
+        else if (securityBlockLevel === 'high')
+            securityBlockLevel = 'medium';
+        reasoning.push(`Security trend degrading: escalated block level to ${securityBlockLevel}+`);
+    }
     // Recent failure rate adjustment
     if (metrics.recentFailureRate !== undefined) {
         if (metrics.recentFailureRate > 50) {
-            // High failure rate - be more lenient to avoid discouragement
             leniencyFactor = Math.min(1, leniencyFactor + 0.2);
             reasoning.push(`High failure rate (${metrics.recentFailureRate.toFixed(0)}%): increased leniency`);
         }
         else if (metrics.recentFailureRate < 10) {
-            // Low failure rate - team is mature, can handle stricter gates
             leniencyFactor = Math.max(0, leniencyFactor - 0.1);
             reasoning.push(`Low failure rate (${metrics.recentFailureRate.toFixed(0)}%): stricter enforcement`);
         }
@@ -180,6 +298,7 @@ export function calculateAdaptiveThresholds(cwd, metrics, config = {}) {
         securityBlockLevel,
         leniencyFactor: Math.round(leniencyFactor * 100) / 100,
         reasoning,
+        provenanceTrends,
     };
 }
 /**
@@ -196,9 +315,16 @@ export function clearAdaptiveHistory(cwd) {
  * Get summary of adaptive thresholds for logging
  */
 export function getAdaptiveSummary(adjustments) {
-    return `[${adjustments.tier.toUpperCase()}] ` +
+    let summary = `[${adjustments.tier.toUpperCase()}] ` +
         `Coverage: ${adjustments.coverageThreshold}%, ` +
         `Quality: ${adjustments.qualityThreshold}%, ` +
         `Security: ${adjustments.securityBlockLevel}+, ` +
         `Trend: ${adjustments.trend}`;
+    if (adjustments.provenanceTrends) {
+        const pt = adjustments.provenanceTrends;
+        if (pt.aiDrift !== 'stable' || pt.structural !== 'stable' || pt.security !== 'stable') {
+            summary += ` | AI:${pt.aiDrift}(Z=${pt.aiDriftZScore}) Struct:${pt.structural}(Z=${pt.structuralZScore}) Sec:${pt.security}(Z=${pt.securityZScore})`;
+        }
+    }
+    return summary;
 }

package/dist/services/adaptive-thresholds.test.js

@@ -69,23 +69,25 @@ describe('AdaptiveThresholds', () => {
             expect(trend).toBe('stable');
         });
         it('should detect improving trend', () => {
-            // Record 20 runs: older ones with high failures, recent with low
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 3, 5, 20);
+            // Baseline: 15 runs with high failures (with variance for valid std dev)
+            for (let i = 0; i < 15; i++) {
+                recordGateRun(testDir, 3, 5, 15 + (i % 5) * 3); // 15,18,21,24,27 repeating
             }
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 7, 1, 5);
+            // Recent: 5 runs with very low failures (clear improvement)
+            for (let i = 0; i < 5; i++) {
+                recordGateRun(testDir, 7, 0, 1);
             }
             const trend = getQualityTrend(testDir);
             expect(trend).toBe('improving');
         });
         it('should detect degrading trend', () => {
-            // Record 20 runs: older ones with low failures, recent with high
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 7, 1, 3);
+            // Baseline: 15 runs with low failures (with variance for valid std dev)
+            for (let i = 0; i < 15; i++) {
+                recordGateRun(testDir, 7, 1, 1 + (i % 3)); // 1,2,3 repeating
             }
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 3, 5, 20);
+            // Recent: 5 runs with high failures (clear degradation)
+            for (let i = 0; i < 5; i++) {
+                recordGateRun(testDir, 3, 5, 25);
             }
             const trend = getQualityTrend(testDir);
             expect(trend).toBe('degrading');
@@ -93,24 +95,26 @@ describe('AdaptiveThresholds', () => {
     });
     describe('trend-based adjustments', () => {
         it('should relax thresholds for improving trend', () => {
-            // Create improving history
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 3, 5, 20);
+            // Baseline: 15 runs with high failures (with variance)
+            for (let i = 0; i < 15; i++) {
+                recordGateRun(testDir, 3, 5, 15 + (i % 5) * 3);
             }
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 7, 1, 5);
+            // Recent: 5 runs with very low failures
+            for (let i = 0; i < 5; i++) {
+                recordGateRun(testDir, 7, 0, 1);
             }
             const adjustments = calculateAdaptiveThresholds(testDir, { fileCount: 100 });
             expect(adjustments.trend).toBe('improving');
             expect(adjustments.reasoning.some(r => r.includes('bonus'))).toBe(true);
         });
         it('should tighten thresholds for degrading trend', () => {
-            // Create degrading history
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 7, 1, 3);
+            // Baseline: 15 runs with low failures (with variance)
+            for (let i = 0; i < 15; i++) {
+                recordGateRun(testDir, 7, 1, 1 + (i % 3));
             }
-            for (let i = 0; i < 10; i++) {
-                recordGateRun(testDir, 3, 5, 20);
+            // Recent: 5 runs with high failures
+            for (let i = 0; i < 5; i++) {
+                recordGateRun(testDir, 3, 5, 25);
             }
             const adjustments = calculateAdaptiveThresholds(testDir, { fileCount: 100 });
             expect(adjustments.trend).toBe('degrading');

package/dist/services/filesystem-cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * FileSystemCache — Shared file content cache across gates
+ *
+ * Solves the memory problem: each gate was independently loading ALL files
+ * into a Map<string, string>. With 25+ gates, a 5000-file repo would
+ * allocate ~500MB+ (50MB per gate × 10 gates reading files).
+ *
+ * Now: one cache per scan, all gates share it. LRU eviction keeps
+ * memory bounded. Hit rate >70% by the 2nd gate.
+ *
+ * @since v5.0.0
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    entries: number;
+    estimatedSizeBytes: number;
+}
+export declare class FileSystemCache {
+    private readonly maxEntries;
+    private readonly maxSizeBytes;
+    private cache;
+    private accessOrder;
+    private stats;
+    constructor(maxEntries?: number, maxSizeBytes?: number);
+    /**
+     * Get a single file's content. Reads from disk on cache miss.
+     */
+    getFile(absolutePath: string): Promise<string>;
+    /**
+     * Get multiple files. Compatible with FileScanner.readFiles() return type.
+     */
+    getFiles(cwd: string, files: string[]): Promise<Map<string, string>>;
+    /**
+     * Invalidate a specific file or the entire cache.
+     */
+    invalidate(absolutePath?: string): void;
+    /**
+     * Get cache statistics for monitoring.
+     */
+    getStats(): CacheStats;
+    /**
+     * Hit rate as a percentage (0-100).
+     */
+    get hitRate(): number;
+    private put;
+    private touch;
+    private evictLRU;
+}

package/dist/services/filesystem-cache.js

@@ -0,0 +1,124 @@
+/**
+ * FileSystemCache — Shared file content cache across gates
+ *
+ * Solves the memory problem: each gate was independently loading ALL files
+ * into a Map<string, string>. With 25+ gates, a 5000-file repo would
+ * allocate ~500MB+ (50MB per gate × 10 gates reading files).
+ *
+ * Now: one cache per scan, all gates share it. LRU eviction keeps
+ * memory bounded. Hit rate >70% by the 2nd gate.
+ *
+ * @since v5.0.0
+ */
+import fs from 'fs-extra';
+import path from 'path';
+export class FileSystemCache {
+    maxEntries;
+    maxSizeBytes;
+    cache = new Map();
+    accessOrder = [];
+    stats = { hits: 0, misses: 0, evictions: 0, entries: 0, estimatedSizeBytes: 0 };
+    constructor(maxEntries = 2000, maxSizeBytes = 200 * 1024 * 1024 // 200MB default
+    ) {
+        this.maxEntries = maxEntries;
+        this.maxSizeBytes = maxSizeBytes;
+    }
+    /**
+     * Get a single file's content. Reads from disk on cache miss.
+     */
+    async getFile(absolutePath) {
+        const cached = this.cache.get(absolutePath);
+        if (cached !== undefined) {
+            this.stats.hits++;
+            this.touch(absolutePath);
+            return cached;
+        }
+        this.stats.misses++;
+        const content = await fs.readFile(absolutePath, 'utf-8');
+        this.put(absolutePath, content);
+        return content;
+    }
+    /**
+     * Get multiple files. Compatible with FileScanner.readFiles() return type.
+     */
+    async getFiles(cwd, files) {
+        const contents = new Map();
+        for (const file of files) {
+            const normalizedFile = file.replace(/\//g, path.sep);
+            const filePath = path.isAbsolute(normalizedFile) ? normalizedFile : path.join(cwd, normalizedFile);
+            try {
+                contents.set(file, await this.getFile(filePath));
+            }
+            catch {
+                // File not readable — skip (same behavior as original scanner)
+            }
+        }
+        return contents;
+    }
+    /**
+     * Invalidate a specific file or the entire cache.
+     */
+    invalidate(absolutePath) {
+        if (absolutePath) {
+            const content = this.cache.get(absolutePath);
+            if (content) {
+                this.stats.estimatedSizeBytes -= content.length * 2; // UTF-16
+                this.cache.delete(absolutePath);
+                this.accessOrder = this.accessOrder.filter(k => k !== absolutePath);
+                this.stats.entries--;
+            }
+        }
+        else {
+            this.cache.clear();
+            this.accessOrder = [];
+            this.stats.entries = 0;
+            this.stats.estimatedSizeBytes = 0;
+        }
+    }
+    /**
+     * Get cache statistics for monitoring.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Hit rate as a percentage (0-100).
+     */
+    get hitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        return total === 0 ? 0 : Math.round((this.stats.hits / total) * 100);
+    }
+    // ─── Internal LRU Logic ─────────────────────────────────────────
+    put(key, content) {
+        const sizeBytes = content.length * 2; // UTF-16 estimate
+        // Evict if over limits
+        while ((this.cache.size >= this.maxEntries || this.stats.estimatedSizeBytes + sizeBytes > this.maxSizeBytes) &&
+            this.accessOrder.length > 0) {
+            this.evictLRU();
+        }
+        this.cache.set(key, content);
+        this.accessOrder.push(key);
+        this.stats.entries = this.cache.size;
+        this.stats.estimatedSizeBytes += sizeBytes;
+    }
+    touch(key) {
+        // Move to end of access order (most recently used)
+        const idx = this.accessOrder.indexOf(key);
+        if (idx !== -1) {
+            this.accessOrder.splice(idx, 1);
+            this.accessOrder.push(key);
+        }
+    }
+    evictLRU() {
+        const oldest = this.accessOrder.shift();
+        if (oldest) {
+            const content = this.cache.get(oldest);
+            if (content) {
+                this.stats.estimatedSizeBytes -= content.length * 2;
+            }
+            this.cache.delete(oldest);
+            this.stats.evictions++;
+            this.stats.entries = this.cache.size;
+        }
+    }
+}

package/dist/services/temporal-drift.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Temporal Drift Engine (v5)
+ *
+ * The "bank statement" for code quality.
+ * Reads from SQLite scan history and computes:
+ *
+ * 1. Cross-session temporal trends — how is quality changing over weeks/months?
+ * 2. Per-provenance EWMA streams — is AI getting worse? Structural? Security?
+ * 3. Anomaly detection — is today's scan statistically unusual?
+ *
+ * This is Rigour's core differentiator:
+ * No other tool can tell a CTO "your AI contributions are degrading
+ * your codebase at 3x the rate of human contributions."
+ *
+ * Data source: ~/.rigour/rigour.db (scans + findings tables)
+ * All computation is read-only — no writes to DB.
+ *
+ * @since v5.0.0
+ */
+export type DriftDirection = 'improving' | 'stable' | 'degrading';
+/** A single data point in a time series. */
+export interface TrendPoint {
+    timestamp: number;
+    value: number;
+    ewma: number;
+}
+/** Per-provenance EWMA stream. */
+export interface ProvenanceStream {
+    direction: DriftDirection;
+    zScore: number;
+    /** EWMA time series (oldest first) */
+    series: TrendPoint[];
+    /** Current EWMA value */
+    currentEWMA: number;
+    /** Average over the full history */
+    historicalAvg: number;
+}
+/** Monthly aggregation for the "3 months trend" view. */
+export interface MonthlyBucket {
+    month: string;
+    avgScore: number;
+    avgAiHealth: number;
+    avgStructural: number;
+    scanCount: number;
+    totalFailures: number;
+    provenanceBreakdown: {
+        aiDrift: number;
+        structural: number;
+        security: number;
+    };
+}
+/** Weekly aggregation for more granular view. */
+export interface WeeklyBucket {
+    weekStart: string;
+    avgScore: number;
+    avgAiHealth: number;
+    scanCount: number;
+}
+/** Complete temporal drift report for a project. */
+export interface TemporalDriftReport {
+    repo: string;
+    totalScans: number;
+    timeSpanDays: number;
+    /** Overall quality trend direction */
+    overallDirection: DriftDirection;
+    overallZScore: number;
+    /** Per-provenance EWMA streams — the core differentiator */
+    streams: {
+        aiDrift: ProvenanceStream;
+        structural: ProvenanceStream;
+        security: ProvenanceStream;
+        overall: ProvenanceStream;
+    };
+    /** Monthly rollups for executive dashboard */
+    monthly: MonthlyBucket[];
+    /** Weekly rollups for team dashboard */
+    weekly: WeeklyBucket[];
+    /** Anomaly flag: is the latest scan statistically unusual? */
+    latestScanAnomaly: {
+        isAnomaly: boolean;
+        direction: 'spike' | 'dip' | 'normal';
+        zScore: number;
+        message: string;
+    };
+    /** Human-readable narrative for the CTO question */
+    narrative: string;
+}
+/**
+ * Generate a complete temporal drift report for a project.
+ *
+ * Reads from SQLite: scans (scores over time) + findings (provenance counts).
+ * Computes EWMA streams, Z-scores, monthly/weekly rollups, and a narrative.
+ *
+ * @param cwd - Project root path (used to derive repo name)
+ * @param maxScans - Max scans to analyze (default 200)
+ */
+export declare function generateTemporalDriftReport(cwd: string, maxScans?: number): TemporalDriftReport | null;
+/**
+ * Get a formatted summary string for CLI/MCP output.
+ */
+export declare function formatDriftSummary(report: TemporalDriftReport): string;