fraim-framework 2.0.44 → 2.0.45

package/dist/src/ai-manager/ai-manager.js

@@ -1,162 +1,423 @@
 "use strict";
 /**
- * Simplified AI Manager
+ * AI Coach - Provides guidance and coaching for implementation phases
  *
- * Single AI manager integrated into fraim-mcp-server that reads validation rules
- * from pre-defined JSON files and provides structured review instructions.
+ * Handles coaching requests from agents, provides phase instructions,
+ * completion messages, and help when agents encounter challenges.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIManager = void 0;
+exports.AICoach = void 0;
 const fs_1 = require("fs");
-const path_1 = require("path");
-class AIManager {
-    constructor(rulesPath) {
-        // Default to rules directory - server-side only, not sent to client
-        this.rulesPath = rulesPath || (0, path_1.join)(__dirname, '..', '..', 'registry', 'ai-manager-rules');
+const phase_flow_js_1 = require("./phase-flow.js");
+class AICoach {
+    constructor(fileIndex) {
+        this.fileIndex = fileIndex;
     }
     /**
-     * Generate review instructions for a workflow phase
+     * Handle coaching request from agent
      */
-    generateReviewInstructions(context) {
-        console.log(`🤖 AI Manager: Generating review instructions for ${context.workflowType} phase`);
-        const rules = this.loadWorkflowRules(context.workflowType);
-        if (!rules) {
-            throw new Error(`No rules found for workflow type: ${context.workflowType}`);
+    async handleCoachingRequest(args) {
+        // console.log(`🤖 AI Coach: Providing guidance for ${args.workflowType} workflow, phase: ${args.currentPhase}, status: ${args.status}`);
+        // Validate required parameters
+        const requiredParams = ['workflowType', 'currentPhase', 'status'];
+        const missingParams = requiredParams.filter(param => !args[param]);
+        if (missingParams.length > 0) {
+            throw new Error(`Missing required parameters: ${missingParams.join(', ')}`);
+        }
+        // Handle missing or empty issue number gracefully
+        if (!args.issueNumber || args.issueNumber.trim() === '') {
+            return `⚠️ **Issue Number Missing**
+
+Please provide a valid issue number to get specific guidance for your workflow.
+
+**Current Request:**
+- Workflow: ${args.workflowType}
+- Phase: ${args.currentPhase}
+- Status: ${args.status}
+
+**Next Steps:**
+1. Identify the GitHub issue number you're working on
+2. Include the issue number in your coaching request
+3. Re-request guidance with complete information
+
+Example: \`seekCoachingOnNextStep({ workflowType: "${args.workflowType}", issueNumber: "123", currentPhase: "${args.currentPhase}", status: "${args.status}" })\``;
+        }
+        // Validate workflow type
+        const validWorkflowTypes = ['implement', 'spec', 'design', 'test'];
+        if (!validWorkflowTypes.includes(args.workflowType)) {
+            throw new Error(`Invalid workflow type: ${args.workflowType}. Valid types: ${validWorkflowTypes.join(', ')}`);
+        }
+        // Validate phase for workflow type
+        const issueType = this.extractIssueType(args.findings, args.evidence);
+        if (!(0, phase_flow_js_1.isPhaseValidForWorkflow)(args.currentPhase, args.workflowType, issueType)) {
+            // Special handling for implement workflow to provide better error messages
+            if (args.workflowType === 'implement') {
+                const hasIssueType = args.findings?.issueType || args.evidence?.issueType;
+                if (!hasIssueType) {
+                    throw new Error(`❌ Missing Required Field: issueType
+
+For implement workflow, you MUST specify issueType in your findings object:
+
+**Correct format:**
+\`\`\`javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "${args.issueNumber}",
+  currentPhase: "${args.currentPhase}",
+  status: "${args.status}",
+  findings: {
+    issueType: "bug" // or "feature" - REQUIRED!
+  },
+  evidence: {
+    // your evidence here
+  }
+})
+\`\`\`
+
+**Valid phases by issue type:**
+- **Bugs**: implement-scoping → implement-repro → implement-code → implement-validate → implement-smoke → implement-regression → implement-completeness-review → submit-pr → wait-for-pr-review
+- **Features**: implement-scoping → implement-spike → implement-code → implement-validate → implement-smoke → implement-regression → implement-completeness-review → submit-pr → wait-for-pr-review`);
+                }
+                else {
+                    throw new Error(`❌ Invalid Phase for Issue Type
+
+Phase "${args.currentPhase}" is not valid for ${issueType} issues.
+
+**Valid phases for ${issueType}s:**
+${this.getValidPhasesForIssueType(issueType).join(' → ')}
+
+**Your current request:**
+- Workflow: ${args.workflowType}
+- Issue Type: ${issueType}
+- Phase: ${args.currentPhase} ❌
+
+**Suggestion:** Use the correct phase name from the valid flow above.`);
+                }
+            }
+            else {
+                throw new Error(`Invalid phase "${args.currentPhase}" for workflow type "${args.workflowType}"`);
+            }
+        }
+        if (args.status === 'complete') {
+            return await this.generateCompletionMessage(args);
+        }
+        else if (args.status === 'incomplete') {
+            return await this.generateHelpMessage(args);
+        }
+        else if (args.status === 'failure') {
+            return await this.generateFailureMessage(args);
+        }
+        else {
+            return await this.getPhaseInstructions(args.currentPhase, args.workflowType);
         }
-        return this.formatReviewInstructions(rules, context);
     }
     /**
-     * Evaluate agent's review report and provide decision
+     * Generate completion message for completed phases
      */
-    evaluateReport(report, context) {
-        console.log(`🤖 AI Manager: Evaluating review report for ${context.workflowType} phase`);
-        const iterationCount = report.iterationCount || 1;
-        const maxIterations = 3;
-        if (report.pass) {
-            return {
-                action: 'PROCEED',
-                message: 'Review passed. Ready to submit PR to human for review.',
-                nextSteps: [
-                    'Update issue status to "status:needs-review"',
-                    'Remove "status:wip" label',
-                    'Include complete review results in evidence document',
-                    'Submit PR for human review with evidence'
-                ],
-                iterationCount
-            };
+    async generateCompletionMessage(args) {
+        // Handle workflow completion for wait-for-pr-review phase when PR is approved
+        if (args.currentPhase === 'wait-for-pr-review') {
+            return `# 🎉 ${args.workflowType.charAt(0).toUpperCase() + args.workflowType.slice(1)} Complete!
+
+**Congratulations!** You have successfully completed all ${args.workflowType} phases for issue #${args.issueNumber}.
+
+## 🏆 What You've Accomplished
+${this.getAccomplishmentsForWorkflow(args.workflowType)}
+
+## 📋 Final Evidence Summary
+${JSON.stringify(args.evidence || {}, null, 2)}
+
+`;
         }
         else {
-            // Check if max iterations reached
-            if (iterationCount >= maxIterations) {
-                return {
-                    action: 'ESCALATE',
-                    message: `Maximum iterations (${maxIterations}) reached. Escalating to human review despite failing validation.`,
-                    nextSteps: [
-                        'Update issue status to "status:needs-review"',
-                        'Add "ai-manager:max-iterations" label to indicate escalation reason',
-                        'Include all iteration attempts and failure reasons in evidence document',
-                        'Submit PR for human review with detailed iteration history',
-                        'Human reviewer should focus on the recurring validation failures'
-                    ],
-                    iterationCount,
-                    maxIterationsReached: true
-                };
-            }
-            else {
-                return {
-                    action: 'ITERATE',
-                    message: `Review failed. Address the identified issues before proceeding. (Iteration ${iterationCount}/${maxIterations})`,
-                    nextSteps: [
-                        'Fix all issues identified in the failure reasons',
-                        'Re-run validation steps to verify fixes',
-                        `Request new review instructions with iterationCount: ${iterationCount + 1}`,
-                        'Do not submit PR until review passes or max iterations reached'
-                    ],
-                    iterationCount
-                };
+            // Determine next phase and provide its instructions
+            const issueType = this.extractIssueType(args.findings, args.evidence);
+            const nextPhase = (0, phase_flow_js_1.getNextPhase)(args.currentPhase, args.workflowType, issueType);
+            if (!nextPhase) {
+                return `# 🎉 Phase Complete!
+
+**Phase:** ${args.currentPhase}
+**Status:** Complete
+
+Great work! You've completed the ${args.currentPhase} phase.
+
+## Evidence Summary
+${JSON.stringify(args.evidence || args.findings || {}, null, 2)}
+
+## 🚨 Error: No Next Phase Found
+Unable to determine the next phase. This might indicate an issue with the phase flow logic.
+Please check your workflow type and current phase.
+`;
             }
+            // Get instructions for the next phase
+            const nextPhaseInstructions = await this.getPhaseInstructions(nextPhase, args.workflowType);
+            return `# 🎉 Phase Complete!
+
+**Phase:** ${args.currentPhase}
+**Status:** Complete
+
+Great work! You've completed the ${args.currentPhase} phase.
+
+## Evidence Summary
+${JSON.stringify(args.evidence || args.findings || {}, null, 2)}
+
+## 🚀 Next Phase: ${nextPhase}
+
+Here are the instructions for your next phase:
+
+---
+
+${nextPhaseInstructions}
+`;
         }
     }
     /**
-     * Load workflow rules from JSON file (server-side only)
+     * Get accomplishments list for a workflow type
      */
-    loadWorkflowRules(workflowType) {
-        const rulesFile = (0, path_1.join)(this.rulesPath, `${workflowType}.json`);
-        if (!(0, fs_1.existsSync)(rulesFile)) {
-            console.warn(`⚠️ No rules file found for workflow: ${workflowType} at ${rulesFile}`);
-            return null;
+    getAccomplishmentsForWorkflow(workflowType) {
+        switch (workflowType) {
+            case 'implement':
+                return `- ✅ **Scoping**: Understood requirements and issue type
+- ✅ **Repro/Spike**: Created reproduction test or validated technical approach
+- ✅ **Implementation**: Built working solution with comprehensive tests
+- ✅ **Validation**: Verified functionality through manual and automated testing
+- ✅ **Smoke Tests**: Confirmed technical health (build, tests, git status)
+- ✅ **Regression Tests**: Ensured bug fixes work or features have proper test coverage
+- ✅ **Completeness Review**: Verified all design aspects implemented
+- ✅ **Submit PR**: Prepared work for human review
+- ✅ **PR Review**: Successfully completed code review process`;
+            case 'spec':
+                return `- ✅ **Specification**: Created comprehensive feature specification
+- ✅ **Validation**: Verified spec completeness and quality
+- ✅ **Submit PR**: Prepared specification for review
+- ✅ **PR Review**: Successfully completed specification review process`;
+            case 'design':
+                return `- ✅ **Design**: Created technical design and architecture
+- ✅ **Validation**: Verified design completeness and feasibility
+- ✅ **Submit PR**: Prepared design for implementation phase
+- ✅ **PR Review**: Successfully completed design review process`;
+            case 'test':
+                return `- ✅ **Testing**: Created comprehensive test suite
+- ✅ **Validation**: Verified test coverage and quality
+- ✅ **Submit PR**: Prepared tests for integration
+- ✅ **PR Review**: Successfully completed test review process`;
+            default:
+                return `- ✅ **${workflowType}**: Completed all phases successfully
+- ✅ **Validation**: Verified work quality and completeness
+- ✅ **Submit PR**: Prepared work for review
+- ✅ **PR Review**: Successfully completed review process`;
         }
-        try {
-            const content = (0, fs_1.readFileSync)(rulesFile, 'utf8');
-            return JSON.parse(content);
+    }
+    /**
+     * Get valid phases for a specific issue type
+     */
+    getValidPhasesForIssueType(issueType) {
+        if (issueType === 'bug') {
+            return ['implement-scoping', 'implement-repro', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
         }
-        catch (error) {
-            console.error(`❌ Error loading rules for ${workflowType}:`, error);
-            return null;
+        else {
+            return ['implement-scoping', 'implement-spike', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+        }
+    }
+    /**
+     * Extract issue type from findings or evidence
+     */
+    extractIssueType(findings, evidence) {
+        // Try to get issue type from findings first
+        if (findings?.issueType) {
+            return findings.issueType;
+        }
+        // Try to get from evidence
+        if (evidence?.issueType) {
+            return evidence.issueType;
         }
+        // Default to feature if not specified
+        return 'feature';
     }
     /**
-     * Format review instructions with proper template structure
+     * Generate failure message for failed phases
      */
-    formatReviewInstructions(rules, context) {
-        const instructions = `# AI Manager Review Instructions
+    async generateFailureMessage(args) {
+        // Standard failure handling for all phases
+        const issueType = this.extractIssueType(args.findings);
+        const { getPhaseOnFailure } = await Promise.resolve().then(() => __importStar(require('./phase-flow.js')));
+        const nextPhase = getPhaseOnFailure(args.currentPhase, args.workflowType, issueType);
+        const nextPhaseInstructions = await this.getPhaseInstructions(nextPhase, args.workflowType);
+        return `# ❌ Phase Failed
 
-## Workflow: ${rules.workflowType.toUpperCase()}
-**Issue:** #${context.issueNumber}
-**Phase:** ${context.phase}
+**Workflow:** ${args.workflowType}
+**Failed Phase:** ${args.currentPhase}
+**Issue:** ${args.issueNumber}
 
-## Description
-${rules.description}
+## Failure Details
+${args.findings ? JSON.stringify(args.findings, null, 2) : 'No specific failure details provided'}
 
-## Iteration Tracking
-**IMPORTANT**: You must track your iteration count for this phase. This is your attempt number for this specific workflow phase (spec, implement, test, etc.).
+## 🚀 Next Phase: ${nextPhase}
 
-- **First attempt**: Use iterationCount: 1
-- **After first failure**: Use iterationCount: 2  
-- **After second failure**: Use iterationCount: 3
-- **Maximum iterations**: 3 (after 3rd failure, work will be escalated to human review)
+You'll now return to the **${nextPhase}** phase to address the issues.
 
-## Validation Steps
-Complete each step below and evaluate whether you meet the pass criteria:
+---
 
-${rules.validationRules.map(rule => `
-### Step ${rule.step}: ${rule.description}
-${rule.command ? `**Command:** \`${rule.command.replace('{issue_number}', context.issueNumber)}\`` : ''}
-**Pass Criteria:** ${rule.passCriteria}
-**Weight:** ${rule.weight.toUpperCase()}${rule.weight === 'blocking' ? ' (Must pass to proceed)' : ' (Should pass for quality)'}
-**Category:** ${rule.category}
-`).join('')}
+${nextPhaseInstructions}
 
-## Grading Criteria
+---
 
-### Pass Requirements
-${rules.gradingCriteria.passRequirements.map(req => `- ${req}`).join('\n')}
+## Action Plan
+1. **Review the failure details above**
+2. **Follow the ${nextPhase} phase instructions**
+3. **Address the root cause of the failure**
+4. **Continue through the workflow**
+`;
+    }
+    /**
+     * Generate help message for incomplete phases
+     */
+    async generateHelpMessage(args) {
+        // Standard help message for all phases
+        const phaseInstructions = await this.getPhaseInstructions(args.currentPhase, args.workflowType);
+        return `# 🤝 AI Coach Assistance
 
-### Fail Requirements  
-${rules.gradingCriteria.failRequirements.map(req => `- ${req}`).join('\n')}
+**Workflow:** ${args.workflowType}
+**Phase:** ${args.currentPhase}
+**Status:** Incomplete - Need Help
 
-## Reporting Format
-${rules.reportingFormat.instructions}
+I understand you're encountering challenges with the ${args.currentPhase} phase. Let me provide you with the complete guidance for this phase.
 
-**Required Response Format:**
-\`\`\`json
-{
-  "pass": true/false,
-  "reasons": ["reason1", "reason2"], // Only required if pass=false
-  "iterationCount": 1 // REQUIRED: Your current iteration number for this phase
-}
-\`\`\`
+## Issues You Mentioned
+${args.findings?.uncertainties && Array.isArray(args.findings.uncertainties) ?
+            args.findings.uncertainties.map((issue) => `- ${issue}`).join('\n') :
+            'No specific issues mentioned'}
+
+## Complete Phase Guidance
+Here are the complete instructions for the ${args.currentPhase} phase:
 
-## Iteration Limits
-- **Maximum 3 iterations** per workflow phase
-- After 3 failed attempts, work will be **automatically escalated** to human review
-- Track your attempts carefully - include iterationCount in every report
-- Each workflow phase (spec, implement, test) has its own iteration counter
+---
+
+${phaseInstructions}
+
+---
 
 ## Next Steps
-After completing your review, report back with the JSON response above including your iteration count. The AI Manager will evaluate your report and provide next steps based on your progress and iteration count.
+1. Review the complete phase guidance above
+2. Address the specific issues you mentioned
+3. Follow the phase workflow step by step
+4. When ready, call seekCoachingOnNextStep again with status "complete"
+
+Remember: Take your time and follow each step carefully. The phase guidance contains everything you need to succeed.
+`;
+    }
+    /**
+     * Get phase instructions from .md files
+     */
+    async getPhaseInstructions(phase, workflowType) {
+        try {
+            // Read phase instructions from .md files based on workflow type
+            let phasePath;
+            if (workflowType === 'implement') {
+                phasePath = `ai-manager-rules/implement-phases/${phase}.md`;
+            }
+            else {
+                phasePath = `ai-manager-rules/${workflowType}-phases/${phase}.md`;
+            }
+            // Try to get from file index first
+            let phaseFile = this.fileIndex.get(phasePath);
+            if (phaseFile && (0, fs_1.existsSync)(phaseFile.fullPath)) {
+                return (0, fs_1.readFileSync)(phaseFile.fullPath, 'utf8');
+            }
+            // If not found in workflow-specific directory, try shared-phases
+            const sharedPhasePath = `ai-manager-rules/shared-phases/${phase}.md`;
+            phaseFile = this.fileIndex.get(sharedPhasePath);
+            if (phaseFile && (0, fs_1.existsSync)(phaseFile.fullPath)) {
+                return (0, fs_1.readFileSync)(phaseFile.fullPath, 'utf8');
+            }
+            // Fallback: try to read directly from filesystem
+            const { join } = require('path');
+            const possiblePaths = [
+                // Try workflow-specific paths first
+                join(process.cwd(), 'dist', 'registry', phasePath),
+                join(process.cwd(), 'registry', phasePath),
+                join(__dirname, '..', '..', 'registry', phasePath),
+                join(__dirname, '..', 'registry', phasePath),
+                // Try shared-phases paths
+                join(process.cwd(), 'dist', 'registry', sharedPhasePath),
+                join(process.cwd(), 'registry', sharedPhasePath),
+                join(__dirname, '..', '..', 'registry', sharedPhasePath),
+                join(__dirname, '..', 'registry', sharedPhasePath)
+            ];
+            for (const fullPath of possiblePaths) {
+                if ((0, fs_1.existsSync)(fullPath)) {
+                    console.log(`📖 AI Coach: Reading phase file from ${fullPath}`);
+                    return (0, fs_1.readFileSync)(fullPath, 'utf8');
+                }
+            }
+            return `# Phase: ${phase}
+
+**Error**: Phase instructions not found at ${phasePath} or ${sharedPhasePath}
+
+Tried paths:
+${possiblePaths.map(p => `- ${p}`).join('\n')}
+
+Please check that the phase name is correct and the phase file exists.
+
+Available phases for ${workflowType} workflow: ${this.getAvailablePhasesForWorkflow(workflowType)}
+`;
+        }
+        catch (error) {
+            return `# Phase: ${phase}
+
+**Error**: Failed to load phase instructions: ${error instanceof Error ? error.message : 'Unknown error'}
 `;
-        return instructions;
+        }
+    }
+    /**
+     * Get available phases for a workflow type
+     */
+    getAvailablePhasesForWorkflow(workflowType) {
+        switch (workflowType) {
+            case 'implement':
+                return 'implement-scoping, implement-repro, implement-spike, implement-code, implement-validate, implement-smoke, implement-regression, implement-completeness-review, submit-pr, wait-for-pr-review';
+            case 'spec':
+                return 'spec-spec, spec-completeness-review, submit-pr, wait-for-pr-review';
+            case 'design':
+                return 'design-design, design-completeness-review, submit-pr, wait-for-pr-review';
+            case 'test':
+                return 'test-test, test-validate, submit-pr, wait-for-pr-review';
+            default:
+                return 'unknown';
+        }
     }
 }
-exports.AIManager = AIManager;
+exports.AICoach = AICoach;