@equilateral_ai/mindmeld 3.0.0

package/src/core/CurationEngine.js

@@ -0,0 +1,688 @@
+/**
+ * Rapport v3 - Curation Engine
+ *
+ * Purpose: Promotes validated patterns to .equilateral-standards/
+ *
+ * Promotion Criteria:
+ * - correlation >= 0.90 (90% success rate)
+ * - projectCount >= 5 (proven across 5+ projects)
+ * - developerCount >= 3 (used by 3+ developers)
+ * - sessionCount >= 10 (reinforced 10+ times)
+ * - hasMeasurableBenefit = true (cost/performance gain)
+ *
+ * Based on: /Users/jamesford/Source/rapport/docs/RAPPORT_STANDARDS_INTEGRATION_DESIGN.md
+ */
+
+const { executeQuery } = require('../handlers/helpers/dbOperations');
+const { NotificationService } = require('./NotificationService');
+
+class CurationEngine {
+    constructor(config = {}) {
+        this.config = {
+            minCorrelation: config.minCorrelation || 0.90,
+            minProjects: config.minProjects || 5,
+            minDevelopers: config.minDevelopers || 3,
+            minSessions: config.minSessions || 10,
+            requireMeasurableBenefit: config.requireMeasurableBenefit !== false,
+            ...config
+        };
+
+        // Initialize notification service
+        this.notificationService = config.notificationService || new NotificationService();
+    }
+
+    /**
+     * Evaluate if a pattern meets promotion criteria
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Object|null>} Curation candidate or null
+     */
+    async evaluateForPromotion(patternId) {
+        try {
+            // Get pattern metrics from materialized view
+            const metrics = await this.getPatternMetrics(patternId);
+
+            if (!metrics) {
+                console.log(`[CurationEngine] Pattern ${patternId} not found in metrics`);
+                return null;
+            }
+
+            // Check if pattern meets all criteria
+            if (!this.meetsAllCriteria(metrics)) {
+                console.log(`[CurationEngine] Pattern ${patternId} does not meet promotion criteria`);
+                return null;
+            }
+
+            // Create curation candidate
+            const candidate = await this.createCurationCandidate(patternId, metrics);
+
+            console.log(`[CurationEngine] Pattern ${patternId} promoted to curation candidate`);
+            return candidate;
+        } catch (error) {
+            console.error('[CurationEngine] Error evaluating pattern for promotion:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Get pattern metrics from materialized view
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Object|null>} Pattern metrics
+     */
+    async getPatternMetrics(patternId) {
+        const query = `
+            SELECT
+                pattern_id,
+                element,
+                project_count,
+                developer_count,
+                session_count,
+                success_correlation,
+                last_used
+            FROM rapport.pattern_metrics
+            WHERE pattern_id = $1
+        `;
+
+        const result = await executeQuery(query, [patternId]);
+        return result.rows.length > 0 ? result.rows[0] : null;
+    }
+
+    /**
+     * Check if metrics meet all promotion criteria
+     *
+     * @param {Object} metrics - Pattern metrics
+     * @returns {boolean} True if all criteria met
+     */
+    meetsAllCriteria(metrics) {
+        // PostgreSQL returns numeric values as strings - parse them
+        const correlation = parseFloat(metrics.success_correlation) || 0;
+        const projectCount = parseInt(metrics.project_count) || 0;
+        const developerCount = parseInt(metrics.developer_count) || 0;
+        const sessionCount = parseInt(metrics.session_count) || 0;
+
+        const checks = {
+            correlation: correlation >= this.config.minCorrelation,
+            projects: projectCount >= this.config.minProjects,
+            developers: developerCount >= this.config.minDevelopers,
+            sessions: sessionCount >= this.config.minSessions
+        };
+
+        const allMet = Object.values(checks).every(check => check === true);
+
+        if (!allMet) {
+            console.log('[CurationEngine] Criteria check:', {
+                pattern: metrics.pattern_id,
+                correlation: `${correlation.toFixed(2)} (required: ${this.config.minCorrelation})`,
+                projects: `${projectCount} (required: ${this.config.minProjects})`,
+                developers: `${developerCount} (required: ${this.config.minDevelopers})`,
+                sessions: `${sessionCount} (required: ${this.config.minSessions})`,
+                passed: checks
+            });
+        }
+
+        return allMet;
+    }
+
+    /**
+     * Create a curation candidate for human review
+     *
+     * @param {string} patternId - Pattern identifier
+     * @param {Object} metrics - Pattern metrics
+     * @returns {Promise<Object>} Curation candidate
+     */
+    async createCurationCandidate(patternId, metrics) {
+        // Get pattern details
+        const patternDetails = await this.getPatternDetails(patternId);
+
+        // Infer category based on pattern characteristics
+        const category = await this.inferCategory(patternDetails);
+
+        // Gather best examples from successful usage
+        const examples = await this.gatherBestExamples(patternId);
+
+        // Gather anti-patterns from failed usage
+        const antiPatterns = await this.gatherAntiPatterns(patternId);
+
+        // Get measurable benefit data
+        const benefit = await this.getMeasurableBenefit(patternId);
+
+        // Build proposed standard
+        const proposedStandard = {
+            name: metrics.element,
+            category: category,
+            status: 'candidate',
+            evidence: {
+                correlation: parseFloat(metrics.success_correlation),
+                projectCount: metrics.project_count,
+                developerCount: metrics.developer_count,
+                sessionCount: metrics.session_count,
+                benefit: benefit
+            },
+            pattern: patternDetails,
+            examples: examples,
+            antiPatterns: antiPatterns,
+            proposedEnforcement: this.generateEnforcementRule(patternDetails)
+        };
+
+        // Generate standard document
+        const standardDocument = this.generateStandardDocument(proposedStandard);
+
+        // Save to curation database
+        const candidateId = await this.saveCurationCandidate(
+            patternId,
+            category,
+            proposedStandard.evidence,
+            standardDocument
+        );
+
+        // Notify for human review
+        await this.notifyForReview(candidateId, proposedStandard);
+
+        return {
+            candidateId,
+            patternId,
+            ...proposedStandard
+        };
+    }
+
+    /**
+     * Get detailed pattern information
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Object>} Pattern details
+     */
+    async getPatternDetails(patternId) {
+        const query = `
+            SELECT
+                pattern_id,
+                project_id,
+                intent,
+                constraints,
+                outcome_criteria,
+                maturity,
+                handoff_count,
+                successful_handoffs,
+                failed_handoffs,
+                discovered_by,
+                discovered_at,
+                last_used,
+                pattern_data
+            FROM rapport.patterns
+            WHERE pattern_id = $1
+        `;
+
+        const result = await executeQuery(query, [patternId]);
+        return result.rows[0];
+    }
+
+    /**
+     * Infer category for the pattern based on content analysis
+     *
+     * @param {Object} pattern - Pattern details
+     * @returns {Promise<string>} Inferred category
+     */
+    async inferCategory(pattern) {
+        const intent = pattern.intent.toLowerCase();
+        const constraints = JSON.stringify(pattern.constraints).toLowerCase();
+        const data = JSON.stringify(pattern.pattern_data).toLowerCase();
+
+        // Category detection based on keywords
+        const categories = {
+            'serverless-saas-aws': ['lambda', 'api gateway', 'sam', 'serverless', 'handler', 'aws'],
+            'database-patterns': ['database', 'query', 'postgresql', 'sql', 'schema'],
+            'multi-agent-orchestration': ['agent', 'orchestration', 'workflow', 'task', 'team'],
+            'frontend-development': ['react', 'component', 'ui', 'frontend', 'tsx', 'jsx'],
+            'compliance-security': ['security', 'compliance', 'audit', 'gdpr', 'encryption'],
+            'cost-optimization': ['cost', 'performance', 'optimization', 'billing', 'pricing']
+        };
+
+        const allText = `${intent} ${constraints} ${data}`;
+
+        for (const [category, keywords] of Object.entries(categories)) {
+            if (keywords.some(keyword => allText.includes(keyword))) {
+                return category;
+            }
+        }
+
+        return 'general'; // Default category
+    }
+
+    /**
+     * Gather best examples from successful pattern usage
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Array>} Best examples
+     */
+    async gatherBestExamples(patternId) {
+        const query = `
+            SELECT
+                pu.context,
+                pu.used_at,
+                u."User_Display_Name" as user_name,
+                p.project_name
+            FROM rapport.pattern_usage pu
+            JOIN "Users" u ON pu.email_address = u."Email_Address"
+            JOIN rapport.patterns pat ON pu.pattern_id = pat.pattern_id
+            JOIN rapport.projects p ON pat.project_id = p.project_id
+            WHERE pu.pattern_id = $1
+                AND pu.success = true
+            ORDER BY pu.used_at DESC
+            LIMIT 5
+        `;
+
+        const result = await executeQuery(query, [patternId]);
+
+        return result.rows.map(row => ({
+            code: row.context.code || 'No code example available',
+            description: row.context.description || 'Successful pattern application',
+            project: row.project_name,
+            user: row.user_name,
+            timestamp: row.used_at
+        }));
+    }
+
+    /**
+     * Gather anti-patterns from failed usage
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Array>} Anti-patterns
+     */
+    async gatherAntiPatterns(patternId) {
+        const query = `
+            SELECT
+                pu.context,
+                pu.used_at,
+                u."User_Display_Name" as user_name
+            FROM rapport.pattern_usage pu
+            JOIN "Users" u ON pu.email_address = u."Email_Address"
+            WHERE pu.pattern_id = $1
+                AND pu.success = false
+            ORDER BY pu.used_at DESC
+            LIMIT 5
+        `;
+
+        const result = await executeQuery(query, [patternId]);
+
+        return result.rows.map(row => ({
+            description: row.context.error || 'Pattern application failed',
+            context: row.context.failureReason || 'Unknown failure reason',
+            user: row.user_name,
+            timestamp: row.used_at
+        }));
+    }
+
+    /**
+     * Get measurable benefit data (cost savings, performance improvements)
+     *
+     * @param {string} patternId - Pattern identifier
+     * @returns {Promise<Object>} Measurable benefit
+     */
+    async getMeasurableBenefit(patternId) {
+        const query = `
+            SELECT
+                pattern_data->'benefit' as benefit_data
+            FROM rapport.patterns
+            WHERE pattern_id = $1
+        `;
+
+        const result = await executeQuery(query, [patternId]);
+
+        if (result.rows.length > 0 && result.rows[0].benefit_data) {
+            return result.rows[0].benefit_data;
+        }
+
+        // Default benefit if not recorded
+        return {
+            type: 'team_efficiency',
+            description: 'Proven pattern with high success rate across multiple teams',
+            quantified: false
+        };
+    }
+
+    /**
+     * Generate proposed enforcement rule for the pattern
+     *
+     * @param {Object} pattern - Pattern details
+     * @returns {string} Enforcement rule
+     */
+    generateEnforcementRule(pattern) {
+        const constraints = Array.isArray(pattern.constraints) ? pattern.constraints : [];
+        const outcomeCriteria = Array.isArray(pattern.outcome_criteria) ? pattern.outcome_criteria : [];
+
+        let enforcement = `## Enforcement Rule\n\n`;
+        enforcement += `**Intent**: ${pattern.intent}\n\n`;
+
+        if (constraints.length > 0) {
+            enforcement += `### Required Constraints\n\n`;
+            constraints.forEach((constraint, idx) => {
+                enforcement += `${idx + 1}. ${constraint}\n`;
+            });
+            enforcement += `\n`;
+        }
+
+        if (outcomeCriteria.length > 0) {
+            enforcement += `### Success Criteria\n\n`;
+            outcomeCriteria.forEach((criteria, idx) => {
+                enforcement += `${idx + 1}. ${criteria}\n`;
+            });
+            enforcement += `\n`;
+        }
+
+        enforcement += `### Validation\n\n`;
+        enforcement += `This pattern should be automatically validated during code review and CI/CD pipeline.\n`;
+
+        return enforcement;
+    }
+
+    /**
+     * Generate markdown standard document
+     *
+     * @param {Object} candidate - Curation candidate
+     * @returns {string} Standard document in markdown
+     */
+    generateStandardDocument(candidate) {
+        const { name, category, evidence, pattern, examples, antiPatterns, proposedEnforcement } = candidate;
+
+        let doc = `# ${name}\n\n`;
+        doc += `**Status**: Candidate (from Rapport curation)\n`;
+        doc += `**Category**: ${category}\n`;
+        doc += `**Date**: ${new Date().toISOString()}\n\n`;
+
+        doc += `## Evidence\n\n`;
+        doc += `- **Correlation**: ${(evidence.correlation * 100).toFixed(1)}%\n`;
+        doc += `- **Projects**: ${evidence.projectCount}\n`;
+        doc += `- **Developers**: ${evidence.developerCount}\n`;
+        doc += `- **Sessions**: ${evidence.sessionCount}\n`;
+        doc += `- **Benefit**: ${evidence.benefit.description || JSON.stringify(evidence.benefit)}\n\n`;
+
+        doc += `## Pattern\n\n`;
+        doc += `**Intent**: ${pattern.intent}\n\n`;
+
+        if (pattern.constraints && pattern.constraints.length > 0) {
+            doc += `**Constraints**:\n`;
+            pattern.constraints.forEach((constraint, idx) => {
+                doc += `${idx + 1}. ${constraint}\n`;
+            });
+            doc += `\n`;
+        }
+
+        if (pattern.outcome_criteria && pattern.outcome_criteria.length > 0) {
+            doc += `**Outcome Criteria**:\n`;
+            pattern.outcome_criteria.forEach((criteria, idx) => {
+                doc += `${idx + 1}. ${criteria}\n`;
+            });
+            doc += `\n`;
+        }
+
+        doc += `## Examples\n\n`;
+        if (examples.length > 0) {
+            examples.forEach((example, idx) => {
+                doc += `### Example ${idx + 1}: ${example.description}\n\n`;
+                doc += `**Project**: ${example.project}\n`;
+                doc += `**User**: ${example.user}\n\n`;
+                doc += `\`\`\`javascript\n${example.code}\n\`\`\`\n\n`;
+            });
+        } else {
+            doc += `No examples available.\n\n`;
+        }
+
+        doc += `## Anti-Patterns\n\n`;
+        if (antiPatterns.length > 0) {
+            antiPatterns.forEach((antiPattern, idx) => {
+                doc += `${idx + 1}. ❌ **${antiPattern.description}**\n`;
+                doc += `   - Context: ${antiPattern.context}\n`;
+                doc += `   - Observed by: ${antiPattern.user}\n\n`;
+            });
+        } else {
+            doc += `No anti-patterns recorded.\n\n`;
+        }
+
+        doc += proposedEnforcement;
+        doc += `\n---\n\n`;
+        doc += `**Generated by**: Rapport Curation Engine\n`;
+        doc += `**Requires**: Human review before promotion to .equilateral-standards/\n`;
+
+        return doc;
+    }
+
+    /**
+     * Save curation candidate to database
+     *
+     * @param {string} patternId - Pattern identifier
+     * @param {string} category - Proposed category
+     * @param {Object} evidence - Evidence data
+     * @param {string} standardDocument - Generated standard document
+     * @returns {Promise<number>} Candidate ID
+     */
+    async saveCurationCandidate(patternId, category, evidence, standardDocument) {
+        const query = `
+            INSERT INTO rapport.curation_candidates
+                (pattern_id, proposed_category, evidence, standard_document, status)
+            VALUES
+                ($1, $2, $3, $4, 'pending')
+            RETURNING candidate_id
+        `;
+
+        const result = await executeQuery(query, [
+            patternId,
+            category,
+            JSON.stringify(evidence),
+            standardDocument
+        ]);
+
+        return result.rows[0].candidate_id;
+    }
+
+    /**
+     * Notify stakeholders for human review
+     *
+     * @param {number} candidateId - Candidate ID
+     * @param {Object} candidate - Curation candidate
+     */
+    async notifyForReview(candidateId, candidate) {
+        console.log(`\n========================================`);
+        console.log(`[CurationEngine] NEW CURATION CANDIDATE`);
+        console.log(`========================================`);
+        console.log(`Candidate ID: ${candidateId}`);
+        console.log(`Pattern: ${candidate.name}`);
+        console.log(`Category: ${candidate.category}`);
+        console.log(`Evidence:`);
+        console.log(`  - Correlation: ${(candidate.evidence.correlation * 100).toFixed(1)}%`);
+        console.log(`  - Projects: ${candidate.evidence.projectCount}`);
+        console.log(`  - Developers: ${candidate.evidence.developerCount}`);
+        console.log(`  - Sessions: ${candidate.evidence.sessionCount}`);
+        console.log(`\nAction Required: Review candidate for promotion to .equilateral-standards/`);
+        console.log(`========================================\n`);
+
+        // Send notifications to curators (admins with curation permissions)
+        try {
+            const curators = await this.getCurators();
+
+            for (const curator of curators) {
+                const preferences = await this.getUserPreferences(curator.email_address);
+
+                await this.notificationService.sendNotification({
+                    type: 'curation_candidate',
+                    email: curator.email_address,
+                    preferences: preferences,
+                    data: {
+                        candidateId: candidateId,
+                        patternName: candidate.name,
+                        category: candidate.category,
+                        evidence: candidate.evidence,
+                        referenceType: 'curation_candidate',
+                        referenceId: String(candidateId)
+                    }
+                });
+            }
+
+            console.log(`[CurationEngine] Notified ${curators.length} curators`);
+        } catch (error) {
+            console.error('[CurationEngine] Failed to send notifications:', error);
+            // Don't throw - notification failure shouldn't block curation
+        }
+    }
+
+    /**
+     * Get users with curation permissions (Super Admins and Admins)
+     *
+     * @returns {Promise<Array>} List of curator emails
+     */
+    async getCurators() {
+        const query = `
+            SELECT DISTINCT u."Email_Address" as email_address
+            FROM "Users" u
+            LEFT JOIN "UserEntitlements" ue ON u."Email_Address" = ue."Email_Address"
+            WHERE u."Super_Admin" = true OR ue."Admin" = true
+            AND u."active" = true
+        `;
+
+        const result = await executeQuery(query);
+        return result.rows;
+    }
+
+    /**
+     * Get user notification preferences
+     *
+     * @param {string} email - User email
+     * @returns {Promise<Object>} User preferences
+     */
+    async getUserPreferences(email) {
+        const query = `SELECT rapport.get_notification_preferences($1) as preferences`;
+        const result = await executeQuery(query, [email]);
+        return result.rows[0]?.preferences || null;
+    }
+
+    /**
+     * Refresh pattern metrics materialized view
+     *
+     * @returns {Promise<void>}
+     */
+    async refreshMetrics() {
+        try {
+            await executeQuery('REFRESH MATERIALIZED VIEW rapport.pattern_metrics');
+            console.log('[CurationEngine] Pattern metrics refreshed');
+        } catch (error) {
+            console.error('[CurationEngine] Error refreshing metrics:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Get all pending curation candidates
+     *
+     * @returns {Promise<Array>} Pending candidates
+     */
+    async getPendingCandidates() {
+        const query = `
+            SELECT
+                candidate_id,
+                pattern_id,
+                proposed_category,
+                evidence,
+                standard_document,
+                created_at
+            FROM rapport.curation_candidates
+            WHERE status = 'pending'
+            ORDER BY created_at DESC
+        `;
+
+        const result = await executeQuery(query);
+        return result.rows;
+    }
+
+    /**
+     * Approve a curation candidate
+     *
+     * @param {number} candidateId - Candidate ID
+     * @param {string} reviewedBy - Reviewer email
+     * @returns {Promise<Object>} Approved candidate
+     */
+    async approveCandidate(candidateId, reviewedBy) {
+        const query = `
+            UPDATE rapport.curation_candidates
+            SET
+                status = 'approved',
+                reviewed_by = $2,
+                reviewed_at = NOW()
+            WHERE candidate_id = $1
+            RETURNING *
+        `;
+
+        const result = await executeQuery(query, [candidateId, reviewedBy]);
+        return result.rows[0];
+    }
+
+    /**
+     * Reject a curation candidate
+     *
+     * @param {number} candidateId - Candidate ID
+     * @param {string} reviewedBy - Reviewer email
+     * @returns {Promise<Object>} Rejected candidate
+     */
+    async rejectCandidate(candidateId, reviewedBy) {
+        const query = `
+            UPDATE rapport.curation_candidates
+            SET
+                status = 'rejected',
+                reviewed_by = $2,
+                reviewed_at = NOW()
+            WHERE candidate_id = $1
+            RETURNING *
+        `;
+
+        const result = await executeQuery(query, [candidateId, reviewedBy]);
+        return result.rows[0];
+    }
+
+    /**
+     * Evaluate all patterns for promotion
+     *
+     * @returns {Promise<Array>} Created candidates
+     */
+    async evaluateAllPatterns() {
+        try {
+            // Refresh metrics first
+            await this.refreshMetrics();
+
+            // Get all patterns that meet criteria
+            const query = `
+                SELECT pattern_id
+                FROM rapport.pattern_metrics
+                WHERE success_correlation >= $1
+                    AND project_count >= $2
+                    AND developer_count >= $3
+                    AND session_count >= $4
+                    AND pattern_id NOT IN (
+                        SELECT pattern_id
+                        FROM rapport.curation_candidates
+                        WHERE status IN ('pending', 'approved')
+                    )
+            `;
+
+            const result = await executeQuery(query, [
+                this.config.minCorrelation,
+                this.config.minProjects,
+                this.config.minDevelopers,
+                this.config.minSessions
+            ]);
+
+            const candidates = [];
+            for (const row of result.rows) {
+                const candidate = await this.evaluateForPromotion(row.pattern_id);
+                if (candidate) {
+                    candidates.push(candidate);
+                }
+            }
+
+            console.log(`[CurationEngine] Evaluated ${result.rows.length} patterns, created ${candidates.length} candidates`);
+            return candidates;
+        } catch (error) {
+            console.error('[CurationEngine] Error evaluating all patterns:', error);
+            throw error;
+        }
+    }
+}
+
+module.exports = { CurationEngine };