fraim-framework 2.0.87 → 2.0.89

package/dist/src/cli/providers/local-provider-registry.js

@@ -51,7 +51,15 @@ const LOCAL_PROVIDERS = [
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://docs.microsoft.com/azure/devops',
         setupInstructions: 'Create a Personal Access Token in Azure DevOps',
-        hasAdditionalConfig: false
+        hasAdditionalConfig: true,
+        mcpServer: {
+            type: 'stdio',
+            command: 'npx',
+            args: ['-y', '@azure-devops/mcp', '{config.organization}', '--authentication', 'envvar'],
+            envTemplate: {
+                ADO_MCP_AUTH_TOKEN: '{token}'
+            }
+        }
     },
     {
         id: 'jira',
@@ -73,6 +81,16 @@ const LOCAL_PROVIDERS = [
         }
     }
 ];
+const ADO_CONFIG_REQUIREMENTS = [
+    {
+        key: 'organization',
+        displayName: 'Azure DevOps Organization',
+        description: 'Your Azure DevOps organization name (e.g., contoso)',
+        required: true,
+        type: 'string',
+        cliOptionName: 'organization'
+    }
+];
 const JIRA_CONFIG_REQUIREMENTS = [
     {
         key: 'baseUrl',
@@ -111,6 +129,9 @@ function getLocalProviderSetupInstructions(providerId) {
     return provider?.setupInstructions || '';
 }
 function getLocalProviderConfigRequirements(providerId) {
+    if (providerId === 'ado') {
+        return ADO_CONFIG_REQUIREMENTS;
+    }
     if (providerId === 'jira') {
         return JIRA_CONFIG_REQUIREMENTS;
     }

package/dist/src/cli/setup/provider-prompts.js

@@ -60,6 +60,10 @@ async function promptForProviders(client, preselectedIds) {
         value: provider.id,
         selected: preselectedIds?.includes(provider.id) ?? provider.id === defaultProviderId
     }));
+    if (process.env.FRAIM_NON_INTERACTIVE) {
+        console.log(chalk_1.default.yellow(`\nℹ️  Non-interactive mode: defaulting to ${integratedProviders[0]?.displayName || 'first available provider'}`));
+        return [defaultProviderId];
+    }
     const response = await (0, prompts_1.default)({
         type: 'multiselect',
         name: 'providers',
@@ -109,6 +113,10 @@ async function promptForSingleProvider(client, purpose, availableIds) {
         title: provider.displayName,
         value: provider.id
     }));
+    if (process.env.FRAIM_NON_INTERACTIVE) {
+        console.log(chalk_1.default.yellow(`\nℹ️  Non-interactive mode: defaulting to ${providers[0]?.displayName || 'first available provider'}`));
+        return defaultProviderId;
+    }
     const response = await (0, prompts_1.default)({
         type: 'select',
         name: 'provider',
@@ -145,6 +153,9 @@ async function promptForProviderToken(client, providerId) {
     }
     console.log(chalk_1.default.blue(`\n🔧 ${provider.displayName} Integration Setup`));
     console.log(`FRAIM requires a ${provider.displayName} token for integration.\n`);
+    if (process.env.FRAIM_NON_INTERACTIVE) {
+        throw new Error(`Non-interactive mode: ${provider.displayName} token is missing and cannot prompt.`);
+    }
     const hasToken = await (0, prompts_1.default)({
         type: 'confirm',
         name: 'hasToken',
@@ -152,6 +163,27 @@ async function promptForProviderToken(client, providerId) {
         initial: false
     });
     if (!hasToken.hasToken) {
+        if (providerId === 'github') {
+            const loginChoice = await (0, prompts_1.default)({
+                type: 'confirm',
+                name: 'login',
+                message: `Would you like to login to ${provider.displayName} now using your browser? (Recommended)`,
+                initial: true
+            });
+            if (loginChoice.login) {
+                const { DeviceFlowService } = await Promise.resolve().then(() => __importStar(require('../internal/device-flow-service')));
+                if (!provider.deviceFlowConfig) {
+                    throw new Error(`Device flow configuration not found for provider: ${providerId}`);
+                }
+                const deviceFlow = new DeviceFlowService(provider.deviceFlowConfig);
+                try {
+                    return await deviceFlow.login();
+                }
+                catch (e) {
+                    console.log(chalk_1.default.yellow('\nBrowser login failed or was cancelled. Fallback to manual token entry.'));
+                }
+            }
+        }
         console.log(chalk_1.default.yellow(`\n📝 To create a ${provider.displayName} token:`));
         console.log(chalk_1.default.gray(`   ${provider.setupInstructions}`));
         console.log(chalk_1.default.gray(`   Visit: ${provider.docsUrl}\n`));
@@ -225,6 +257,13 @@ async function promptForProviderConfig(client, providerId) {
     console.log(`Additional configuration required for ${provider.displayName}.\n`);
     const config = {};
     for (const req of requirements) {
+        if (process.env.FRAIM_NON_INTERACTIVE) {
+            if (req.required) {
+                throw new Error(`Non-interactive mode: Required configuration "${req.displayName}" for ${provider.displayName} is missing.`);
+            }
+            console.log(chalk_1.default.yellow(`\nℹ️  Non-interactive mode: skipping optional configuration "${req.displayName}"`));
+            continue;
+        }
         const response = await (0, prompts_1.default)({
             type: req.type === 'email' ? 'text' : req.type === 'url' ? 'text' : 'text',
             name: 'value',

package/dist/src/cli/utils/remote-sync.js

@@ -78,21 +78,18 @@ function insertAfterFrontmatter(content, banner) {
     const body = normalized.slice(frontmatter.length);
     return `${frontmatter}${banner}${body}`;
 }
-function buildSyncedContentBanner(typeLabel, registryPath) {
-    const overridePath = `.fraim/personalized-employee/${registryPath}`;
-    return `${SYNCED_CONTENT_BANNER_MARKER}
-> [!IMPORTANT]
-> This ${typeLabel} is synced from FRAIM and will be overwritten on the next \`fraim sync\`.
-> Do not edit this file.
-`;
+function buildSyncedContentBanner(typeLabel) {
+    return `${SYNCED_CONTENT_BANNER_MARKER}\r\n> [!IMPORTANT]\r\n> This ${typeLabel} is synced from FRAIM and will be overwritten on the next \`fraim sync\`.\r\n> Do not edit this file.\r\n`;
 }
 function applySyncedContentBanner(file) {
     const registryPath = getBannerRegistryPath(file);
     if (!registryPath) {
         return file.content;
     }
-    const typeLabel = file.type === 'job' ? 'job stub' : `${file.type} file`;
-    const banner = buildSyncedContentBanner(typeLabel, registryPath);
+    const typeLabel = file.type === 'job' || file.type === 'skill' || file.type === 'rule'
+        ? `${file.type} stub`
+        : `${file.type} file`;
+    const banner = buildSyncedContentBanner(typeLabel);
     return insertAfterFrontmatter(file.content, banner);
 }
 /**
@@ -146,23 +143,49 @@ async function syncFromRemote(options) {
                 setFileWriteLockRecursively(target, false);
             }
         }
-        // Sync workflows
-        const workflowFiles = files.filter(f => f.type === 'workflow');
-        const workflowsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'workflows');
-        if (!(0, fs_1.existsSync)(workflowsDir)) {
-            (0, fs_1.mkdirSync)(workflowsDir, { recursive: true });
+        // Sync workflows to role-specific folders under .fraim
+        const allWorkflowFiles = files.filter(f => f.type === 'workflow');
+        const managerWorkflowFiles = allWorkflowFiles.filter(f => f.path.startsWith('ai-manager/'));
+        const employeeWorkflowFiles = allWorkflowFiles.filter(f => !f.path.startsWith('ai-manager/'));
+        // Write employee workflows
+        const employeeWorkflowsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'workflows');
+        if (!(0, fs_1.existsSync)(employeeWorkflowsDir)) {
+            (0, fs_1.mkdirSync)(employeeWorkflowsDir, { recursive: true });
         }
-        // Clean existing workflows
-        cleanDirectory(workflowsDir);
-        // Write workflow files
-        for (const file of workflowFiles) {
-            const filePath = (0, path_1.join)(workflowsDir, file.path);
+        cleanDirectory(employeeWorkflowsDir);
+        for (const file of employeeWorkflowFiles) {
+            // Strip "workflows/" prefix and "ai-employee/" role prefix for cleaner local layout
+            let relPath = file.path;
+            if (relPath.startsWith('workflows/'))
+                relPath = relPath.substring('workflows/'.length);
+            relPath = relPath.replace(/^ai-employee\//, '');
+            const filePath = (0, path_1.join)(employeeWorkflowsDir, relPath);
             const fileDir = (0, path_1.dirname)(filePath);
             if (!(0, fs_1.existsSync)(fileDir)) {
                 (0, fs_1.mkdirSync)(fileDir, { recursive: true });
             }
             (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
-            console.log(chalk_1.default.gray(`  + ${file.path}`));
+            console.log(chalk_1.default.gray(`  + .fraim/ai-employee/workflows/${relPath}`));
+        }
+        // Write manager workflows
+        const managerWorkflowsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-manager', 'workflows');
+        if (!(0, fs_1.existsSync)(managerWorkflowsDir)) {
+            (0, fs_1.mkdirSync)(managerWorkflowsDir, { recursive: true });
+        }
+        cleanDirectory(managerWorkflowsDir);
+        for (const file of managerWorkflowFiles) {
+            // Strip "workflows/" prefix and "ai-manager/" role prefix
+            let relPath = file.path;
+            if (relPath.startsWith('workflows/'))
+                relPath = relPath.substring('workflows/'.length);
+            relPath = relPath.replace(/^ai-manager\//, '');
+            const filePath = (0, path_1.join)(managerWorkflowsDir, relPath);
+            const fileDir = (0, path_1.dirname)(filePath);
+            if (!(0, fs_1.existsSync)(fileDir)) {
+                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+            console.log(chalk_1.default.gray(`  + .fraim/ai-manager/workflows/${relPath}`));
         }
         // Sync job stubs to role-specific folders under .fraim
         const allJobFiles = files.filter(f => f.type === 'job');
@@ -174,13 +197,18 @@ async function syncFromRemote(options) {
         }
         cleanDirectory(employeeJobsDir);
         for (const file of jobFiles) {
-            const filePath = (0, path_1.join)(employeeJobsDir, file.path);
+            // Strip "jobs/" prefix and "ai-employee/" role prefix
+            let relPath = file.path;
+            if (relPath.startsWith('jobs/'))
+                relPath = relPath.substring('jobs/'.length);
+            relPath = relPath.replace(/^ai-employee\//, '');
+            const filePath = (0, path_1.join)(employeeJobsDir, relPath);
             const fileDir = (0, path_1.dirname)(filePath);
             if (!(0, fs_1.existsSync)(fileDir)) {
                 (0, fs_1.mkdirSync)(fileDir, { recursive: true });
             }
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
-            console.log(chalk_1.default.gray(`  + ai-employee/jobs/${file.path}`));
+            console.log(chalk_1.default.gray(`  + ai-employee/jobs/${relPath}`));
         }
         // Sync ai-manager job stubs to .fraim/ai-manager/jobs/
         const managerJobsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-manager', 'jobs');
@@ -189,16 +217,20 @@ async function syncFromRemote(options) {
         }
         cleanDirectory(managerJobsDir);
         for (const file of managerJobFiles) {
-            const managerRelativePath = file.path.replace(/^ai-manager\//, '');
-            const filePath = (0, path_1.join)(managerJobsDir, managerRelativePath);
+            // Strip "jobs/" prefix and "ai-manager/" role prefix
+            let relPath = file.path;
+            if (relPath.startsWith('jobs/'))
+                relPath = relPath.substring('jobs/'.length);
+            relPath = relPath.replace(/^ai-manager\//, '');
+            const filePath = (0, path_1.join)(managerJobsDir, relPath);
             const fileDir = (0, path_1.dirname)(filePath);
             if (!(0, fs_1.existsSync)(fileDir)) {
                 (0, fs_1.mkdirSync)(fileDir, { recursive: true });
             }
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
-            console.log(chalk_1.default.gray(`  + ai-manager/jobs/${managerRelativePath}`));
+            console.log(chalk_1.default.gray(`  + .fraim/ai-manager/jobs/${relPath}`));
         }
-        // Sync full skill files to .fraim/ai-employee/skills/
+        // Sync skill STUBS to .fraim/ai-employee/skills/
         const skillFiles = files.filter(f => f.type === 'skill');
         const skillsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'skills');
         if (!(0, fs_1.existsSync)(skillsDir)) {
@@ -206,15 +238,19 @@ async function syncFromRemote(options) {
         }
         cleanDirectory(skillsDir);
         for (const file of skillFiles) {
-            const filePath = (0, path_1.join)(skillsDir, file.path);
+            // Strip "skills/" prefix to avoid redundant nesting in .fraim/ai-employee/skills/
+            let relPath = file.path;
+            if (relPath.startsWith('skills/'))
+                relPath = relPath.substring('skills/'.length);
+            const filePath = (0, path_1.join)(skillsDir, relPath);
             const fileDir = (0, path_1.dirname)(filePath);
             if (!(0, fs_1.existsSync)(fileDir)) {
                 (0, fs_1.mkdirSync)(fileDir, { recursive: true });
             }
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
-            console.log(chalk_1.default.gray(`  + ai-employee/skills/${file.path}`));
+            console.log(chalk_1.default.gray(`  + ai-employee/skills/${file.path} (stub)`));
         }
-        // Sync full rule files to .fraim/ai-employee/rules/
+        // Sync rule STUBS to .fraim/ai-employee/rules/
         const ruleFiles = files.filter(f => f.type === 'rule');
         const rulesDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'rules');
         if (!(0, fs_1.existsSync)(rulesDir)) {
@@ -222,13 +258,17 @@ async function syncFromRemote(options) {
         }
         cleanDirectory(rulesDir);
         for (const file of ruleFiles) {
-            const filePath = (0, path_1.join)(rulesDir, file.path);
+            // Strip "rules/" prefix to avoid redundant nesting in .fraim/ai-employee/rules/
+            let relPath = file.path;
+            if (relPath.startsWith('rules/'))
+                relPath = relPath.substring('rules/'.length);
+            const filePath = (0, path_1.join)(rulesDir, relPath);
             const fileDir = (0, path_1.dirname)(filePath);
             if (!(0, fs_1.existsSync)(fileDir)) {
                 (0, fs_1.mkdirSync)(fileDir, { recursive: true });
             }
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
-            console.log(chalk_1.default.gray(`  + ai-employee/rules/${file.path}`));
+            console.log(chalk_1.default.gray(`  + ai-employee/rules/${file.path} (stub)`));
         }
         // Sync scripts to user directory
         const scriptFiles = files.filter(f => f.type === 'script');
@@ -273,7 +313,7 @@ async function syncFromRemote(options) {
         }
         return {
             success: true,
-            workflowsSynced: workflowFiles.length,
+            workflowsSynced: allWorkflowFiles.length,
             employeeJobsSynced: jobFiles.length,
             managerJobsSynced: managerJobFiles.length,
             skillsSynced: skillFiles.length,

package/dist/src/core/ai-mentor.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIMentor = void 0;
+const include_resolver_1 = require("./utils/include-resolver");
+class AIMentor {
+    constructor(resolver) {
+        this.workflowCache = new Map();
+        this.resolver = resolver;
+    }
+    /**
+     * Handle mentoring/coaching request from agent
+     */
+    async handleMentoringRequest(args) {
+        const workflow = await this.getOrLoadWorkflow(args.workflowType);
+        if (!workflow) {
+            throw new Error(`Workflow "${args.workflowType}" not found or invalid.`);
+        }
+        const validStatus = ['starting', 'complete', 'incomplete', 'failure'].includes(args.status);
+        if (!validStatus) {
+            throw new Error(`Invalid status: ${args.status}. Must be one of: starting, complete, incomplete, failure.`);
+        }
+        // For simple workflows, skip phase validation
+        if (!workflow.isSimple) {
+            const phases = workflow.metadata.phases || {};
+            const hasMetadata = !!phases[args.currentPhase];
+            const hasMarkdown = workflow.phases.has(args.currentPhase);
+            if (!hasMetadata && !hasMarkdown && args.currentPhase !== 'starting') {
+                throw new Error(`Phase "${args.currentPhase}" not found in workflow "${args.workflowType}".`);
+            }
+        }
+        // Handle different statuses
+        if (args.status === 'starting') {
+            return await this.generateStartingMessage(workflow, args.currentPhase, args.skipIncludes);
+        }
+        else if (args.status === 'complete') {
+            return await this.generateCompletionMessage(workflow, args.currentPhase, args.findings, args.evidence, args.skipIncludes);
+        }
+        else {
+            return await this.generateHelpMessage(workflow, args.currentPhase, args.status, args.skipIncludes);
+        }
+    }
+    async getOrLoadWorkflow(workflowType, preferredType) {
+        if (this.workflowCache.has(workflowType)) {
+            return this.workflowCache.get(workflowType);
+        }
+        const workflow = await this.resolver.getWorkflow(workflowType, preferredType);
+        if (workflow) {
+            this.workflowCache.set(workflowType, workflow);
+            return workflow;
+        }
+        return null;
+    }
+    async resolveIncludes(content, basePath) {
+        return (0, include_resolver_1.resolveIncludes)(content, this.resolver, basePath);
+    }
+    assertNoUnresolvedIncludes(content, context) {
+        const matches = content.match(/\{\{include:[^}]+\}\}/g);
+        if (!matches || matches.length === 0)
+            return;
+        const unique = Array.from(new Set(matches));
+        throw new Error(`Unresolved include directives in ${context}: ${unique.join(', ')}`);
+    }
+    buildReportBackFooter(workflowType, phaseId, phaseFlow) {
+        if (!phaseFlow)
+            return '';
+        const base = `seekMentoring({
+  workflowType: "${workflowType}",
+  issueNumber: "<issue_number>",
+  currentPhase: "${phaseId}",
+  status: "complete",`;
+        const onSuccess = phaseFlow.onSuccess;
+        let successBlock;
+        if (!onSuccess) {
+            successBlock = `\n\n---\n\n> **⚑ Phase Complete — Report Back**\n> When you have finished all steps above, call:\n> \`\`\`javascript\n> ${base}\n>   // This is the final phase.\n> })\n> \`\`\``;
+        }
+        else if (typeof onSuccess === 'string') {
+            successBlock = `\n\n---\n\n> **⚑ Phase Complete — Report Back**\n> When you have finished all steps above, call:\n> \`\`\`javascript\n> ${base}\n> })\n> \`\`\``;
+        }
+        else {
+            const validOutcomes = Object.keys(onSuccess)
+                .filter(k => k !== 'default')
+                .map(k => `"${k}"`)
+                .join(' | ');
+            successBlock = `\n\n---\n\n> **⚑ Phase Complete — Report Back**\n> The next phase depends on your outcome. Set \`findings.issueType\` (or \`findings.phaseOutcome\`) to one of: ${validOutcomes}\n>\n> Then call:\n> \`\`\`javascript\n> ${base}\n>   findings: { issueType: "<Outcome>" }\n> })\n> \`\`\``;
+        }
+        return successBlock;
+    }
+    /** Phase-authority content injected for all phased workflows. Loaded from orchestration/phase-authority.md. */
+    async getPhaseAuthorityContent() {
+        try {
+            const content = await this.resolver.getFile('orchestration/phase-authority.md');
+            return content?.trim() || '';
+        }
+        catch {
+            return '';
+        }
+    }
+    async prependPhaseAuthority(message, isPhased) {
+        if (!isPhased)
+            return message;
+        const block = await this.getPhaseAuthorityContent();
+        if (!block)
+            return message;
+        return `${block}\n\n---\n\n${message}`;
+    }
+    async generateStartingMessage(workflow, phaseId, skipIncludes) {
+        const isJob = workflow.metadata.type === 'job';
+        const entityType = isJob ? 'Job' : 'Workflow';
+        if (workflow.isSimple) {
+            const message = `🚀 **Starting ${entityType}: ${workflow.metadata.name}**\n\n${workflow.overview}`;
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (starting)`);
+            return {
+                message,
+                nextPhase: null,
+                status: 'starting'
+            };
+        }
+        const isVeryFirstCall = phaseId === 'starting';
+        const targetPhase = isVeryFirstCall ? (workflow.metadata.initialPhase || 'starting') : phaseId;
+        let message = '';
+        if (!isJob) {
+            message += `🚀 **Starting Workflow: ${workflow.metadata.name}**\n\n`;
+            if (isVeryFirstCall) {
+                message += `${workflow.overview}\n\n---\n\n`;
+            }
+        }
+        let instructions = workflow.phases.get(targetPhase);
+        if (instructions) {
+            instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
+            message += `${instructions}`;
+        }
+        else {
+            message += `⚠️ No specific instructions found for phase: ${targetPhase}`;
+        }
+        if (isJob) {
+            const phaseFlow = workflow.metadata.phases?.[targetPhase];
+            message += this.buildReportBackFooter(workflow.metadata.name, targetPhase, phaseFlow);
+        }
+        if (!skipIncludes) {
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${targetPhase} (starting)`);
+        }
+        return {
+            message: await this.prependPhaseAuthority(message, true),
+            nextPhase: targetPhase,
+            status: 'starting'
+        };
+    }
+    async generateCompletionMessage(workflow, phaseId, findings, evidence, skipIncludes) {
+        const isJob = workflow.metadata.type === 'job';
+        const entityType = isJob ? 'Job' : 'Workflow';
+        if (workflow.isSimple) {
+            const message = `✅ **${entityType} Complete: ${workflow.metadata.name}**\n\n🎉 Great work! You have completed the ${workflow.metadata.name} ${entityType.toLowerCase()}.`;
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (complete)`);
+            return {
+                message,
+                nextPhase: null,
+                status: 'complete'
+            };
+        }
+        const phaseFlow = workflow.metadata.phases?.[phaseId];
+        let nextPhaseId = null;
+        if (phaseFlow && phaseFlow.onSuccess) {
+            if (typeof phaseFlow.onSuccess === 'string') {
+                nextPhaseId = phaseFlow.onSuccess;
+            }
+            else {
+                const outcome = findings?.phaseOutcome ?? findings?.issueType ?? evidence?.issueType ?? evidence?.phaseOutcome ?? 'default';
+                nextPhaseId = phaseFlow.onSuccess[outcome] ?? phaseFlow.onSuccess['default'] ?? null;
+            }
+        }
+        let message = '';
+        if (nextPhaseId) {
+            if (isJob) {
+                message += `Great work. Moving to the next phase: **${nextPhaseId}**.\n\n`;
+            }
+            else {
+                message += `✅ **Phase Complete: ${phaseId}**\n\nMoving to the next phase: **${nextPhaseId}**.\n\n`;
+            }
+            let nextInstructions = workflow.phases.get(nextPhaseId);
+            if (nextInstructions) {
+                nextInstructions = skipIncludes ? nextInstructions : await this.resolveIncludes(nextInstructions, workflow.path);
+                message += nextInstructions;
+            }
+            if (isJob) {
+                const nextPhaseFlow = workflow.metadata.phases?.[nextPhaseId];
+                message += this.buildReportBackFooter(workflow.metadata.name, nextPhaseId, nextPhaseFlow);
+            }
+        }
+        else {
+            message += `🎉 **${entityType} Accomplished!** You have completed all phases of the ${workflow.metadata.name} ${entityType.toLowerCase()}.`;
+        }
+        if (!skipIncludes) {
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${phaseId} (complete)`);
+        }
+        return {
+            message: await this.prependPhaseAuthority(message, true),
+            nextPhase: nextPhaseId,
+            status: 'complete'
+        };
+    }
+    async generateHelpMessage(workflow, phaseId, status, skipIncludes) {
+        const entityType = workflow.metadata.type === 'job' ? 'Job' : 'Workflow';
+        if (workflow.isSimple) {
+            const message = `**${entityType}: ${workflow.metadata.name}**\n\n${workflow.overview}`;
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (${status})`);
+            return {
+                message,
+                nextPhase: null,
+                status
+            };
+        }
+        const phaseMeta = workflow.metadata.phases?.[phaseId];
+        const targetPhaseId = status === 'failure' ? (phaseMeta?.onFailure || phaseId) : phaseId;
+        let message = `### Current Phase: ${targetPhaseId}\n\n`;
+        let instructions = workflow.phases.get(targetPhaseId);
+        if (instructions) {
+            instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
+            message += instructions;
+        }
+        if (!skipIncludes) {
+            this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${targetPhaseId} (${status})`);
+        }
+        return {
+            message: await this.prependPhaseAuthority(message, true),
+            nextPhase: targetPhaseId,
+            status
+        };
+    }
+    async getWorkflowOverview(workflowType) {
+        const workflow = await this.getOrLoadWorkflow(workflowType, 'workflow');
+        return workflow ? { overview: workflow.overview, isSimple: workflow.isSimple } : null;
+    }
+    async getJobOverview(jobName) {
+        const job = await this.getOrLoadWorkflow(jobName, 'job');
+        return job ? { overview: job.overview, isSimple: job.isSimple } : null;
+    }
+    async getAllWorkflowMetadata() {
+        const items = await this.resolver.listItems('workflow');
+        const workflows = [];
+        for (const item of items) {
+            const wf = await this.resolver.getWorkflow(item.name, 'workflow');
+            if (wf)
+                workflows.push(wf);
+        }
+        return workflows;
+    }
+}
+exports.AIMentor = AIMentor;

package/dist/src/core/utils/git-utils.js

@@ -12,9 +12,9 @@ const child_process_1 = require("child_process");
  */
 function getPort() {
     try {
-        const branchName = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
-        // Match issue-123 or 123-feature-name
-        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/^(\d+)-/);
+        const branchName = process.env.FRAIM_BRANCH || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
+        // Match issue-123 or 123-feature-name or feature/123-name
+        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
         if (issueMatch) {
             const issueNum = parseInt(issueMatch[1], 10);
             // Ensure port is in a safe range (10000-65535)
@@ -31,8 +31,8 @@ function getPort() {
  */
 function determineDatabaseName() {
     try {
-        const branchName = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
-        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/^(\d+)-/);
+        const branchName = process.env.FRAIM_BRANCH || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
+        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
         if (issueMatch) {
             return `fraim_issue_${issueMatch[1]}`;
         }
@@ -60,7 +60,7 @@ function getCurrentGitBranch() {
  * Determines the database schema prefix based on the branch
  */
 function determineSchema(branchName) {
-    const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/^(\d+)-/);
+    const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
     if (issueMatch) {
         return `issue_${issueMatch[1]}`;
     }

package/dist/src/core/utils/include-resolver.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_INCLUDE_PASSES = void 0;
 exports.resolveIncludesWithIndex = resolveIncludesWithIndex;
+exports.resolveIncludes = resolveIncludes;
 const fs_1 = require("fs");
 /** Maximum resolution passes to prevent infinite loops from circular includes */
 exports.MAX_INCLUDE_PASSES = 10;
@@ -45,3 +46,47 @@ function resolveIncludesWithIndex(content, fileIndex) {
     }
     return result;
 }
+/**
+ * Asynchronously resolve {{include:path}} directives in content using a RegistryResolver.
+ *
+ * @param content - Raw content that may contain {{include:path}} directives
+ * @param resolver - RegistryResolver instance
+ * @returns Content with all resolvable includes inlined
+ */
+async function resolveIncludes(content, resolver, basePath) {
+    let result = content;
+    let pass = 0;
+    while (result.includes('{{include:') && pass < exports.MAX_INCLUDE_PASSES) {
+        // Collect all unique includes in this pass
+        const matches = result.match(/\{\{include:([^}]+)\}\}/g);
+        if (!matches)
+            break;
+        const uniqueMatches = Array.from(new Set(matches));
+        for (const match of uniqueMatches) {
+            const filePath = match.match(/\{\{include:([^}]+)\}\}/)[1].trim();
+            let targetPath = filePath;
+            if (filePath.startsWith('./') && basePath) {
+                // Resolve relative to the directory of the current file
+                const dir = basePath.includes('/') ? basePath.substring(0, basePath.lastIndexOf('/')) : '';
+                targetPath = dir ? `${dir}/${filePath.substring(2)}` : filePath.substring(2);
+            }
+            try {
+                const fileContent = await resolver.getFile(targetPath);
+                if (fileContent !== null) {
+                    // Recursively resolve includes in the newly fetched content
+                    const resolvedContent = await resolveIncludes(fileContent, resolver, targetPath);
+                    // Replace all occurrences of this specific include
+                    result = result.split(match).join(resolvedContent);
+                }
+                else {
+                    console.warn(`⚠️ Include file not found via resolver: ${targetPath} (original: ${filePath}, base: ${basePath})`);
+                }
+            }
+            catch (error) {
+                console.error(`❌ Failed to resolve include via resolver: ${targetPath}`, error);
+            }
+        }
+        pass++;
+    }
+    return result;
+}