@equilateral_ai/mindmeld 3.0.0

package/src/core/AlertEngine.js

@@ -0,0 +1,813 @@
+/**
+ * Rapport v3 - Alert Engine
+ *
+ * Purpose: Identifies struggling developers and generates attention alerts
+ *
+ * Alert Types:
+ * - stale_commits: No commits in X days (had previous activity)
+ * - low_conversion: Low session-to-commit conversion rate
+ * - no_ai_usage: Active committer not using AI assistance
+ * - high_violation_rate: Developer frequently violating standards
+ * - stalled_patterns: Developer's patterns not maturing/being used
+ * - declining_activity: Activity trending downward
+ *
+ * Severity Levels:
+ * - info: Informational, no action required
+ * - warning: Attention recommended
+ * - critical: Immediate attention required
+ *
+ * Based on: /Users/jamesford/Source/rapport/docs/PHASE_7_ENGINEERING_INTELLIGENCE.md
+ */
+
+/**
+ * Database operations are injected at runtime.
+ * When used from Lambda handlers, executeQuery comes from helpers.
+ * When used from CLI/scripts, it can be provided via constructor.
+ */
+let executeQuery = null;
+
+/**
+ * Set the database query function
+ * @param {Function} queryFn - Function that executes database queries
+ */
+function setExecuteQuery(queryFn) {
+    executeQuery = queryFn;
+}
+
+/**
+ * Get the database query function, throwing if not set
+ */
+function getExecuteQuery() {
+    if (!executeQuery) {
+        throw new Error('AlertEngine: executeQuery not initialized. Call setExecuteQuery() first.');
+    }
+    return executeQuery;
+}
+
+// Lazy-load AlertNotifier to avoid circular dependencies
+let AlertNotifierModule = null;
+function getAlertNotifierModule() {
+    if (!AlertNotifierModule) {
+        AlertNotifierModule = require('./AlertNotifier');
+    }
+    return AlertNotifierModule;
+}
+
+/**
+ * Default threshold configuration
+ */
+const DEFAULT_THRESHOLDS = {
+    // Stale commits thresholds (days)
+    staleCommits: {
+        enabled: true,
+        infoDays: 7,
+        warningDays: 10,
+        criticalDays: 14,
+        requirePreviousActivity: true
+    },
+
+    // Session-to-commit conversion thresholds (percentage)
+    lowConversion: {
+        enabled: true,
+        minSessions: 5,          // Minimum sessions to evaluate
+        infoThreshold: 30,       // Below 30% = info
+        warningThreshold: 15,    // Below 15% = warning
+        criticalThreshold: 5     // Below 5% = critical
+    },
+
+    // No AI usage thresholds
+    noAiUsage: {
+        enabled: true,
+        minCommits: 5,           // Minimum commits to trigger (active developer)
+        lookbackDays: 30
+    },
+
+    // High violation rate thresholds (percentage of sessions with violations)
+    highViolationRate: {
+        enabled: true,
+        minSessions: 5,          // Minimum sessions to evaluate
+        infoThreshold: 30,       // Above 30% violation rate = info
+        warningThreshold: 50,    // Above 50% = warning
+        criticalThreshold: 70    // Above 70% = critical
+    },
+
+    // Stalled patterns thresholds
+    stalledPatterns: {
+        enabled: true,
+        minPatterns: 3,          // Minimum patterns discovered
+        staleDays: 30,           // No usage/promotion in X days
+        minProvisionalDays: 14   // Provisional for too long
+    },
+
+    // Declining activity thresholds
+    decliningActivity: {
+        enabled: true,
+        lookbackWeeks: 4,        // Compare 4 weeks
+        declineThreshold: 50     // 50% decline triggers alert
+    },
+
+    // Alert aggregation settings
+    aggregation: {
+        cooldownHours: 24,       // Don't create duplicate alerts within cooldown
+        maxAlertsPerUser: 5,     // Maximum active alerts per user
+        expirationDays: 7        // Auto-expire alerts after X days
+    }
+};
+
+class AlertEngine {
+    constructor(config = {}) {
+        this.thresholds = this.mergeThresholds(DEFAULT_THRESHOLDS, config.thresholds || {});
+        this.dryRun = config.dryRun || false;
+        this.enableNotifications = config.enableNotifications !== false; // Default to enabled
+        this.alertNotifier = null; // Lazy-initialized
+    }
+
+    /**
+     * Get or create AlertNotifier instance
+     */
+    getNotifier() {
+        if (!this.alertNotifier && this.enableNotifications) {
+            const module = getAlertNotifierModule();
+            // Ensure AlertNotifier has access to executeQuery
+            module.setExecuteQuery(executeQuery);
+            this.alertNotifier = new module.AlertNotifier();
+        }
+        return this.alertNotifier;
+    }
+
+    /**
+     * Deep merge threshold configurations
+     */
+    mergeThresholds(defaults, overrides) {
+        const result = { ...defaults };
+        for (const key of Object.keys(overrides)) {
+            if (typeof overrides[key] === 'object' && !Array.isArray(overrides[key])) {
+                result[key] = { ...defaults[key], ...overrides[key] };
+            } else {
+                result[key] = overrides[key];
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Generate all alerts for a company or all companies
+     *
+     * @param {string|null} companyId - Optional company ID to filter
+     * @returns {Promise<Object>} Alert generation summary
+     */
+    async generateAlerts(companyId = null) {
+        const summary = {
+            startedAt: new Date().toISOString(),
+            alertsCreated: 0,
+            alertsSkipped: 0,
+            alertsExpired: 0,
+            byType: {},
+            errors: []
+        };
+
+        try {
+            console.log('[AlertEngine] Starting alert generation...');
+
+            // Refresh activity views first
+            await this.refreshActivityViews();
+
+            // Generate each alert type
+            if (this.thresholds.staleCommits.enabled) {
+                const count = await this.generateStaleCommitAlerts(companyId);
+                summary.byType.stale_commits = count;
+                summary.alertsCreated += count;
+            }
+
+            if (this.thresholds.lowConversion.enabled) {
+                const count = await this.generateLowConversionAlerts(companyId);
+                summary.byType.low_conversion = count;
+                summary.alertsCreated += count;
+            }
+
+            if (this.thresholds.noAiUsage.enabled) {
+                const count = await this.generateNoAiUsageAlerts(companyId);
+                summary.byType.no_ai_usage = count;
+                summary.alertsCreated += count;
+            }
+
+            if (this.thresholds.highViolationRate.enabled) {
+                const count = await this.generateHighViolationAlerts(companyId);
+                summary.byType.high_violation_rate = count;
+                summary.alertsCreated += count;
+            }
+
+            if (this.thresholds.stalledPatterns.enabled) {
+                const count = await this.generateStalledPatternAlerts(companyId);
+                summary.byType.stalled_patterns = count;
+                summary.alertsCreated += count;
+            }
+
+            if (this.thresholds.decliningActivity.enabled) {
+                const count = await this.generateDecliningActivityAlerts(companyId);
+                summary.byType.declining_activity = count;
+                summary.alertsCreated += count;
+            }
+
+            // Auto-expire old alerts
+            summary.alertsExpired = await this.expireOldAlerts();
+
+            // Send notifications for new alerts
+            if (summary.alertsCreated > 0 && this.enableNotifications && !this.dryRun) {
+                try {
+                    const notificationResults = await this.sendAlertNotifications(companyId);
+                    summary.notifications = notificationResults;
+                } catch (error) {
+                    console.error('[AlertEngine] Failed to send notifications:', error);
+                    summary.notifications = { error: error.message };
+                    // Don't fail the whole operation if notifications fail
+                }
+            }
+
+            summary.completedAt = new Date().toISOString();
+            console.log(`[AlertEngine] Generated ${summary.alertsCreated} alerts, expired ${summary.alertsExpired}`);
+
+        } catch (error) {
+            console.error('[AlertEngine] Error generating alerts:', error);
+            summary.errors.push(error.message);
+        }
+
+        return summary;
+    }
+
+    /**
+     * Send notifications for newly created alerts
+     *
+     * @param {string|null} companyId - Optional company filter
+     * @returns {Promise<Object>} Notification results
+     */
+    async sendAlertNotifications(companyId = null) {
+        const notifier = this.getNotifier();
+        if (!notifier) {
+            return { skipped: true, reason: 'notifications_disabled' };
+        }
+
+        // Get alerts created in the last minute (newly generated)
+        const query = `
+            SELECT
+                aa.alert_id,
+                aa.email_address,
+                aa.company_id,
+                u."User_Display_Name" as user_name,
+                aa.alert_type,
+                aa.severity,
+                aa.details,
+                aa.created_at
+            FROM rapport.attention_alerts aa
+            JOIN "Users" u ON aa.email_address = u."Email_Address"
+            WHERE aa.created_at > NOW() - INTERVAL '1 minute'
+                AND aa.status = 'active'
+                ${companyId ? 'AND aa.company_id = $1' : ''}
+            ORDER BY aa.created_at DESC
+        `;
+
+        const params = companyId ? [companyId] : [];
+        const result = await executeQuery(query, params);
+
+        if (result.rows.length === 0) {
+            return { notified: 0, skipped: 0, failed: 0 };
+        }
+
+        return await notifier.notifyForAlerts(result.rows);
+    }
+
+    /**
+     * Refresh materialized views for accurate data
+     */
+    async refreshActivityViews() {
+        try {
+            await executeQuery('SELECT rapport.refresh_developer_activity()');
+            console.log('[AlertEngine] Developer activity view refreshed');
+        } catch (error) {
+            // View might not exist yet, that's OK
+            console.log('[AlertEngine] Could not refresh activity view:', error.message);
+        }
+    }
+
+    /**
+     * Generate stale commits alerts
+     * Developers who haven't committed in X days
+     */
+    async generateStaleCommitAlerts(companyId = null) {
+        const config = this.thresholds.staleCommits;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        const query = `
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                email_address,
+                company_id,
+                'stale_commits',
+                CASE
+                    WHEN days_since_commit >= $1 THEN 'critical'
+                    WHEN days_since_commit >= $2 THEN 'warning'
+                    ELSE 'info'
+                END,
+                jsonb_build_object(
+                    'days_since_commit', days_since_commit,
+                    'last_commit', last_commit,
+                    'commits_30d', commits_30d,
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM rapport.mv_developer_activity
+            WHERE days_since_commit >= $3
+            ${config.requirePreviousActivity ? 'AND commits_30d > 0' : ''}
+            ${companyId ? 'AND company_id = $4' : ''}
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = mv_developer_activity.email_address
+                AND aa.alert_type = 'stale_commits'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [
+            config.criticalDays,
+            config.warningDays,
+            config.infoDays
+        ];
+        if (companyId) params.push(companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate stale_commits alerts');
+            return 0;
+        }
+
+        const result = await executeQuery(query, params);
+        console.log(`[AlertEngine] Generated ${result.rowCount} stale_commits alerts`);
+        return result.rowCount;
+    }
+
+    /**
+     * Generate low conversion alerts
+     * Developers with low session-to-commit conversion rate
+     */
+    async generateLowConversionAlerts(companyId = null) {
+        const config = this.thresholds.lowConversion;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        const query = `
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                email_address,
+                company_id,
+                'low_conversion',
+                CASE
+                    WHEN session_to_commit_conversion_pct < $1 THEN 'critical'
+                    WHEN session_to_commit_conversion_pct < $2 THEN 'warning'
+                    ELSE 'info'
+                END,
+                jsonb_build_object(
+                    'sessions_30d', sessions_30d,
+                    'commits_30d', commits_30d,
+                    'conversion_pct', session_to_commit_conversion_pct,
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM rapport.mv_developer_activity
+            WHERE sessions_30d >= $3
+            AND session_to_commit_conversion_pct < $4
+            ${companyId ? 'AND company_id = $5' : ''}
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = mv_developer_activity.email_address
+                AND aa.alert_type = 'low_conversion'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [
+            config.criticalThreshold,
+            config.warningThreshold,
+            config.minSessions,
+            config.infoThreshold
+        ];
+        if (companyId) params.push(companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate low_conversion alerts');
+            return 0;
+        }
+
+        const result = await executeQuery(query, params);
+        console.log(`[AlertEngine] Generated ${result.rowCount} low_conversion alerts`);
+        return result.rowCount;
+    }
+
+    /**
+     * Generate no AI usage alerts
+     * Developers actively committing but not using AI sessions
+     */
+    async generateNoAiUsageAlerts(companyId = null) {
+        const config = this.thresholds.noAiUsage;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        const query = `
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                email_address,
+                company_id,
+                'no_ai_usage',
+                'info',
+                jsonb_build_object(
+                    'sessions_30d', sessions_30d,
+                    'commits_30d', commits_30d,
+                    'note', 'Developer has commits but no AI sessions',
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM rapport.mv_developer_activity
+            WHERE sessions_30d = 0
+            AND commits_30d >= $1
+            ${companyId ? 'AND company_id = $2' : ''}
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = mv_developer_activity.email_address
+                AND aa.alert_type = 'no_ai_usage'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [config.minCommits];
+        if (companyId) params.push(companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate no_ai_usage alerts');
+            return 0;
+        }
+
+        const result = await executeQuery(query, params);
+        console.log(`[AlertEngine] Generated ${result.rowCount} no_ai_usage alerts`);
+        return result.rowCount;
+    }
+
+    /**
+     * Generate high violation rate alerts
+     * Developers with high rate of standards violations
+     */
+    async generateHighViolationAlerts(companyId = null) {
+        const config = this.thresholds.highViolationRate;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        // First, calculate violation rates per developer
+        const query = `
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                s.email_address,
+                da.company_id,
+                'high_violation_rate',
+                CASE
+                    WHEN (COUNT(*) FILTER (WHERE ss.violated = true)::decimal / NULLIF(COUNT(*), 0) * 100) >= $1 THEN 'critical'
+                    WHEN (COUNT(*) FILTER (WHERE ss.violated = true)::decimal / NULLIF(COUNT(*), 0) * 100) >= $2 THEN 'warning'
+                    ELSE 'info'
+                END,
+                jsonb_build_object(
+                    'total_sessions', COUNT(DISTINCT s.session_id),
+                    'standards_shown', COUNT(*),
+                    'violations', COUNT(*) FILTER (WHERE ss.violated = true),
+                    'violation_rate', ROUND((COUNT(*) FILTER (WHERE ss.violated = true)::decimal / NULLIF(COUNT(*), 0) * 100), 1),
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM rapport.sessions s
+            JOIN rapport.session_standards ss ON s.session_id = ss.session_id
+            LEFT JOIN rapport.mv_developer_activity da ON s.email_address = da.email_address
+            WHERE s.started_at > NOW() - INTERVAL '30 days'
+            ${companyId ? 'AND da.company_id = $4' : ''}
+            GROUP BY s.email_address, da.company_id
+            HAVING COUNT(DISTINCT s.session_id) >= $3
+            AND (COUNT(*) FILTER (WHERE ss.violated = true)::decimal / NULLIF(COUNT(*), 0) * 100) >= $5
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = s.email_address
+                AND aa.alert_type = 'high_violation_rate'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [
+            config.criticalThreshold,
+            config.warningThreshold,
+            config.minSessions,
+            config.infoThreshold
+        ];
+        if (companyId) params.splice(3, 0, companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate high_violation_rate alerts');
+            return 0;
+        }
+
+        try {
+            const result = await executeQuery(query, params);
+            console.log(`[AlertEngine] Generated ${result.rowCount} high_violation_rate alerts`);
+            return result.rowCount;
+        } catch (error) {
+            // session_standards table might not have data yet
+            console.log('[AlertEngine] Could not generate violation alerts:', error.message);
+            return 0;
+        }
+    }
+
+    /**
+     * Generate stalled pattern alerts
+     * Developers with patterns that aren't maturing or being used
+     */
+    async generateStalledPatternAlerts(companyId = null) {
+        const config = this.thresholds.stalledPatterns;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        const query = `
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                p.discovered_by as email_address,
+                proj.company_id,
+                'stalled_patterns',
+                'warning',
+                jsonb_build_object(
+                    'total_patterns', COUNT(*),
+                    'provisional_patterns', COUNT(*) FILTER (WHERE p.maturity = 'provisional'),
+                    'stale_patterns', COUNT(*) FILTER (WHERE p.last_used < NOW() - INTERVAL '${config.staleDays} days' OR p.last_used IS NULL),
+                    'oldest_provisional_days', EXTRACT(DAY FROM NOW() - MIN(p.discovered_at) FILTER (WHERE p.maturity = 'provisional')),
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM rapport.patterns p
+            JOIN rapport.projects proj ON p.project_id = proj.project_id
+            WHERE p.discovered_by IS NOT NULL
+            ${companyId ? 'AND proj.company_id = $2' : ''}
+            GROUP BY p.discovered_by, proj.company_id
+            HAVING COUNT(*) >= $1
+            AND (
+                -- Too many provisional patterns that haven't matured
+                COUNT(*) FILTER (
+                    WHERE p.maturity = 'provisional'
+                    AND p.discovered_at < NOW() - INTERVAL '${config.minProvisionalDays} days'
+                ) > COUNT(*) / 2
+                OR
+                -- Patterns not being used
+                COUNT(*) FILTER (
+                    WHERE p.last_used < NOW() - INTERVAL '${config.staleDays} days'
+                    OR p.last_used IS NULL
+                ) > COUNT(*) / 2
+            )
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = p.discovered_by
+                AND aa.alert_type = 'stalled_patterns'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [config.minPatterns];
+        if (companyId) params.push(companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate stalled_patterns alerts');
+            return 0;
+        }
+
+        try {
+            const result = await executeQuery(query, params);
+            console.log(`[AlertEngine] Generated ${result.rowCount} stalled_patterns alerts`);
+            return result.rowCount;
+        } catch (error) {
+            console.log('[AlertEngine] Could not generate stalled pattern alerts:', error.message);
+            return 0;
+        }
+    }
+
+    /**
+     * Generate declining activity alerts
+     * Developers whose activity is trending downward
+     */
+    async generateDecliningActivityAlerts(companyId = null) {
+        const config = this.thresholds.decliningActivity;
+        const cooldownHours = this.thresholds.aggregation.cooldownHours;
+
+        // Compare current week to average of previous weeks
+        const query = `
+            WITH weekly_sessions AS (
+                SELECT
+                    email_address,
+                    DATE_TRUNC('week', started_at) as week,
+                    COUNT(*) as session_count
+                FROM rapport.sessions
+                WHERE started_at > NOW() - INTERVAL '${config.lookbackWeeks} weeks'
+                GROUP BY email_address, DATE_TRUNC('week', started_at)
+            ),
+            developer_trends AS (
+                SELECT
+                    email_address,
+                    AVG(session_count) FILTER (
+                        WHERE week < DATE_TRUNC('week', NOW())
+                    ) as avg_previous_weeks,
+                    SUM(session_count) FILTER (
+                        WHERE week = DATE_TRUNC('week', NOW())
+                    ) as current_week
+                FROM weekly_sessions
+                GROUP BY email_address
+                HAVING AVG(session_count) FILTER (WHERE week < DATE_TRUNC('week', NOW())) > 0
+            )
+            INSERT INTO rapport.attention_alerts (
+                email_address, company_id, alert_type, severity, details, expires_at
+            )
+            SELECT
+                dt.email_address,
+                da.company_id,
+                'declining_activity',
+                CASE
+                    WHEN COALESCE(dt.current_week, 0) = 0 THEN 'warning'
+                    ELSE 'info'
+                END,
+                jsonb_build_object(
+                    'avg_previous_weeks', ROUND(dt.avg_previous_weeks, 1),
+                    'current_week', COALESCE(dt.current_week, 0),
+                    'decline_pct', ROUND((1 - COALESCE(dt.current_week, 0)::decimal / dt.avg_previous_weeks) * 100, 1),
+                    'generated_by', 'AlertEngine'
+                ),
+                NOW() + INTERVAL '${this.thresholds.aggregation.expirationDays} days'
+            FROM developer_trends dt
+            LEFT JOIN rapport.mv_developer_activity da ON dt.email_address = da.email_address
+            WHERE (1 - COALESCE(dt.current_week, 0)::decimal / dt.avg_previous_weeks) * 100 >= $1
+            ${companyId ? 'AND da.company_id = $2' : ''}
+            AND NOT EXISTS (
+                SELECT 1 FROM rapport.attention_alerts aa
+                WHERE aa.email_address = dt.email_address
+                AND aa.alert_type = 'declining_activity'
+                AND (aa.status = 'active' OR aa.created_at > NOW() - INTERVAL '${cooldownHours} hours')
+            )
+            RETURNING alert_id
+        `;
+
+        const params = [config.declineThreshold];
+        if (companyId) params.push(companyId);
+
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would generate declining_activity alerts');
+            return 0;
+        }
+
+        try {
+            const result = await executeQuery(query, params);
+            console.log(`[AlertEngine] Generated ${result.rowCount} declining_activity alerts`);
+            return result.rowCount;
+        } catch (error) {
+            console.log('[AlertEngine] Could not generate declining activity alerts:', error.message);
+            return 0;
+        }
+    }
+
+    /**
+     * Expire old alerts that have passed their expiration date
+     */
+    async expireOldAlerts() {
+        if (this.dryRun) {
+            console.log('[AlertEngine] [DRY RUN] Would expire old alerts');
+            return 0;
+        }
+
+        const result = await executeQuery(`
+            UPDATE rapport.attention_alerts
+            SET status = 'resolved', resolved_at = NOW()
+            WHERE expires_at < NOW()
+            AND status = 'active'
+            RETURNING alert_id
+        `);
+
+        console.log(`[AlertEngine] Expired ${result.rowCount} old alerts`);
+        return result.rowCount;
+    }
+
+    /**
+     * Get alert statistics for a company
+     *
+     * @param {string} companyId - Company ID
+     * @returns {Promise<Object>} Alert statistics
+     */
+    async getAlertStats(companyId) {
+        const result = await executeQuery(`
+            SELECT
+                alert_type,
+                severity,
+                status,
+                COUNT(*) as count
+            FROM rapport.attention_alerts
+            WHERE company_id = $1
+            AND created_at > NOW() - INTERVAL '30 days'
+            GROUP BY alert_type, severity, status
+            ORDER BY alert_type, severity, status
+        `, [companyId]);
+
+        const stats = {
+            byType: {},
+            bySeverity: { info: 0, warning: 0, critical: 0 },
+            byStatus: { active: 0, acknowledged: 0, resolved: 0 },
+            total: 0
+        };
+
+        for (const row of result.rows) {
+            // By type
+            if (!stats.byType[row.alert_type]) {
+                stats.byType[row.alert_type] = 0;
+            }
+            stats.byType[row.alert_type] += parseInt(row.count);
+
+            // By severity
+            if (stats.bySeverity[row.severity] !== undefined) {
+                stats.bySeverity[row.severity] += parseInt(row.count);
+            }
+
+            // By status
+            if (stats.byStatus[row.status] !== undefined) {
+                stats.byStatus[row.status] += parseInt(row.count);
+            }
+
+            stats.total += parseInt(row.count);
+        }
+
+        return stats;
+    }
+
+    /**
+     * Get struggling developers for a company
+     *
+     * @param {string} companyId - Company ID
+     * @returns {Promise<Array>} List of developers with alert summaries
+     */
+    async getStrugglingDevelopers(companyId) {
+        const result = await executeQuery(`
+            SELECT
+                aa.email_address,
+                u."User_Display_Name" as display_name,
+                array_agg(DISTINCT aa.alert_type) as alert_types,
+                MAX(aa.severity) as max_severity,
+                COUNT(*) as active_alert_count,
+                MIN(aa.created_at) as first_alert_at
+            FROM rapport.attention_alerts aa
+            JOIN "Users" u ON aa.email_address = u."Email_Address"
+            WHERE aa.company_id = $1
+            AND aa.status = 'active'
+            GROUP BY aa.email_address, u."User_Display_Name"
+            ORDER BY
+                CASE MAX(aa.severity)
+                    WHEN 'critical' THEN 1
+                    WHEN 'warning' THEN 2
+                    ELSE 3
+                END,
+                COUNT(*) DESC
+        `, [companyId]);
+
+        return result.rows.map(row => ({
+            email: row.email_address,
+            displayName: row.display_name,
+            alertTypes: row.alert_types,
+            maxSeverity: row.max_severity,
+            activeAlertCount: parseInt(row.active_alert_count),
+            firstAlertAt: row.first_alert_at
+        }));
+    }
+
+    /**
+     * Get configuration (for debugging/admin)
+     */
+    getConfiguration() {
+        return {
+            thresholds: this.thresholds,
+            dryRun: this.dryRun
+        };
+    }
+
+    /**
+     * Update thresholds at runtime
+     *
+     * @param {Object} newThresholds - New threshold values
+     */
+    updateThresholds(newThresholds) {
+        this.thresholds = this.mergeThresholds(this.thresholds, newThresholds);
+        console.log('[AlertEngine] Thresholds updated:', this.thresholds);
+    }
+}
+
+module.exports = { AlertEngine, DEFAULT_THRESHOLDS, setExecuteQuery };