fraim 2.0.154 → 2.0.160

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFraimMcpLatestLauncherPath = getFraimMcpLatestLauncherPath;
+exports.ensureFraimMcpLatestLauncher = ensureFraimMcpLatestLauncher;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const LAUNCHER_VERSION = 1;
+const launcherSource = `#!/usr/bin/env node
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const LAUNCHER_VERSION = ${LAUNCHER_VERSION};
+const USER_DIR = process.env.FRAIM_USER_DIR || path.join(os.homedir(), '.fraim');
+const STATE_DIR = path.join(USER_DIR, 'mcp-launcher');
+const STATE_PATH = path.join(STATE_DIR, 'latest.json');
+const CACHE_ROOT = path.join(USER_DIR, 'npm-cache', 'mcp');
+
+const commandName = (name) => process.platform === 'win32' ? name + '.cmd' : name;
+const npmCommand = commandName('npm');
+const npxCommand = commandName('npx');
+const cliArgs = process.argv.slice(2).length > 0 ? process.argv.slice(2) : ['mcp'];
+
+function quoteCmdArg(arg) {
+  const value = String(arg);
+  return /[\\s"&|<>^]/.test(value) ? '"' + value.replace(/"/g, '""') + '"' : value;
+}
+
+function runCommand(command, args, options) {
+  if (process.platform !== 'win32') {
+    return spawnSync(command, args, options);
+  }
+
+  return spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', [command, ...args.map(quoteCmdArg)].join(' ')], options);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state) {
+  ensureDir(STATE_DIR);
+  fs.writeFileSync(STATE_PATH, JSON.stringify({ ...state, launcherVersion: LAUNCHER_VERSION, updatedAt: new Date().toISOString() }, null, 2));
+}
+
+function resolveLatest(packageName) {
+  const result = runCommand(npmCommand, ['view', packageName, 'version', '--silent'], {
+    encoding: 'utf8',
+    env: process.env
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const version = String(result.stdout || '').trim();
+  return /^\\d+\\.\\d+\\.\\d+/.test(version) ? version : null;
+}
+
+function resolvePackage() {
+  const fraimVersion = resolveLatest('fraim');
+  if (fraimVersion) {
+    const state = { packageName: 'fraim', binName: 'fraim', version: fraimVersion, fromCache: false };
+    writeState(state);
+    return state;
+  }
+
+  const cached = readState();
+  if (cached && cached.packageName === 'fraim' && cached.binName === 'fraim' && cached.version) {
+    console.error('[fraim-mcp-launcher] Could not resolve npm latest; using cached fraim@' + cached.version + '.');
+    return { packageName: 'fraim', binName: 'fraim', version: cached.version, fromCache: true };
+  }
+
+  console.error('[fraim-mcp-launcher] Could not resolve fraim latest from npm and no cached fraim version exists.');
+  process.exit(1);
+}
+
+function runPackage(plan, cacheDir) {
+  ensureDir(cacheDir);
+  const env = { ...process.env, npm_config_cache: cacheDir };
+  const result = runCommand(npxCommand, ['--yes', '--package', plan.packageName + '@' + plan.version, plan.binName, ...cliArgs], {
+    stdio: 'inherit',
+    env
+  });
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+const plan = resolvePackage();
+const versionCacheDir = path.join(CACHE_ROOT, plan.packageName + '-' + plan.version.replace(/[^a-zA-Z0-9._-]/g, '_'));
+let status = runPackage(plan, versionCacheDir);
+
+if (status !== 0 && process.platform === 'win32') {
+  const retryCache = path.join(CACHE_ROOT, 'retry-' + Date.now() + '-' + process.pid);
+  console.error('[fraim-mcp-launcher] Package execution failed; retrying once with a fresh npm cache.');
+  status = runPackage(plan, retryCache);
+}
+
+process.exit(status);
+`;
+function getFraimMcpLatestLauncherPath() {
+    return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'bin', 'fraim-mcp-latest.js');
+}
+function ensureFraimMcpLatestLauncher() {
+    const launcherPath = getFraimMcpLatestLauncherPath();
+    const launcherDir = path_1.default.dirname(launcherPath);
+    fs_1.default.mkdirSync(launcherDir, { recursive: true });
+    if (!fs_1.default.existsSync(launcherPath) || fs_1.default.readFileSync(launcherPath, 'utf8') !== launcherSource) {
+        fs_1.default.writeFileSync(launcherPath, launcherSource, 'utf8');
+        if (process.platform !== 'win32') {
+            try {
+                fs_1.default.chmodSync(launcherPath, 0o755);
+            }
+            catch {
+                // Best effort only. IDE configs invoke this through node, so chmod is not required.
+            }
+        }
+    }
+    return {
+        command: process.execPath,
+        args: [launcherPath],
+        path: launcherPath
+    };
+}

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -10,6 +10,7 @@ exports.isHTTPServer = isHTTPServer;
 exports.buildAllBaseServers = buildAllBaseServers;
 const provider_registry_1 = require("../providers/provider-registry");
 const command_resolution_1 = require("./command-resolution");
+const fraim_mcp_latest_launcher_1 = require("./fraim-mcp-latest-launcher");
 exports.BASE_MCP_SERVERS = [
     {
         id: 'git',
@@ -33,16 +34,19 @@ exports.BASE_MCP_SERVERS = [
         id: 'fraim',
         name: 'FRAIM',
         description: 'FRAIM job orchestration and mentoring',
-        buildServer: (fraimKey) => ({
-            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
-            args: ['-y', 'fraim-framework@latest', 'mcp'],
-            env: {
-                // Include API key for IDE configs (Codex, VSCode, etc.)
-                // The stdio-server will use this if set, otherwise falls back to ~/.fraim/config.json
-                FRAIM_API_KEY: fraimKey,
-                FRAIM_REMOTE_URL: 'https://fraim.wellnessatwork.me'
-            }
-        })
+        buildServer: (fraimKey) => {
+            const launcher = (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            return {
+                command: launcher.command,
+                args: launcher.args,
+                env: {
+                    // Include API key for IDE configs (Codex, VSCode, etc.)
+                    // The stdio-server will use this if set, otherwise falls back to ~/.fraim/config.json
+                    FRAIM_API_KEY: fraimKey,
+                    FRAIM_REMOTE_URL: 'https://fraim.wellnessatwork.me'
+                }
+            };
+        }
     }
 ];
 // ============================================================================

package/dist/src/cli/setup/auto-mcp-setup.js

@@ -338,7 +338,7 @@ const autoConfigureMCP = async (fraimKey, tokenInput, selectedIDEs, providerConf
         console.log(chalk_1.default.blue('\n🎯 Next steps:'));
         console.log(chalk_1.default.cyan('   1. Restart your configured IDEs'));
         console.log(chalk_1.default.cyan('   2. Go to any project directory'));
-        console.log(chalk_1.default.cyan('   3. Run: npx fraim-framework@latest init-project'));
+        console.log(chalk_1.default.cyan('   3. Run: npx fraim@latest init-project'));
         console.log(chalk_1.default.cyan('   4. Tell your AI agent: "Onboard this project"'));
     }
 };

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -56,10 +56,10 @@ function buildFraimInvocationBody(profile = 'none') {
     return `Follow this process:
 
 ${buildDeferredToolBootstrapSection(profile)}1. **If the user did not specify a FRAIM job or topic**:
-   Call \`list_fraim_jobs()\` to discover available jobs. Present the results grouped by the categories returned by the server. For each group, list 3-5 of the most relevant jobs with a one-line description.
+   If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 2. **Find the match**:
-   Match the user's request to a FRAIM job from \`list_fraim_jobs()\`. If no job matches, try a likely FRAIM skill with \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` and confirm the match with the user.
+   Match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no job matches, try a likely FRAIM skill with \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` and confirm the match with the user.
 
 3. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.

package/dist/src/cli/utils/fraim-gitignore.js

@@ -12,6 +12,7 @@ exports.FRAIM_SYNC_GITIGNORE_ENTRIES = [
     'fraim/ai-employee/',
     'fraim/ai-manager/',
     'fraim/docs/',
+    'fraim/.sync-metadata.json',
 ];
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const managedBlockPattern = new RegExp(`\\n?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_START)}[\\s\\S]*?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_END)}\\n?`, 'm');
@@ -43,6 +44,16 @@ function resolveGitInfoExcludePath(projectRoot) {
     const gitDir = path_1.default.isAbsolute(match[1])
         ? match[1]
         : path_1.default.resolve(projectRoot, match[1]);
+    const commonDirPath = path_1.default.join(gitDir, 'commondir');
+    if (fs_1.default.existsSync(commonDirPath)) {
+        const commonDirRaw = fs_1.default.readFileSync(commonDirPath, 'utf8').trim();
+        if (commonDirRaw.length > 0) {
+            const commonDir = path_1.default.isAbsolute(commonDirRaw)
+                ? commonDirRaw
+                : path_1.default.resolve(gitDir, commonDirRaw);
+            return path_1.default.join(commonDir, 'info', 'exclude');
+        }
+    }
     return path_1.default.join(gitDir, 'info', 'exclude');
 }
 const removeFraimSyncedContentGitignoreBlock = (projectRoot) => {

package/dist/src/cli/utils/github-workflow-sync.js

@@ -0,0 +1,231 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_WORKFLOW_ASSET_PREFIX = exports.GITHUB_WORKFLOW_HEADER = exports.GITHUB_WORKFLOW_MANIFEST_RELATIVE_PATH = void 0;
+exports.isGitHubWorkflowAutomationEnabled = isGitHubWorkflowAutomationEnabled;
+exports.decorateManagedGitHubWorkflow = decorateManagedGitHubWorkflow;
+exports.isFraimManagedGitHubWorkflow = isFraimManagedGitHubWorkflow;
+exports.loadGitHubWorkflowManifest = loadGitHubWorkflowManifest;
+exports.loadLocalGitHubWorkflowBundle = loadLocalGitHubWorkflowBundle;
+exports.fetchGitHubWorkflowBundle = fetchGitHubWorkflowBundle;
+exports.reconcileGitHubWorkflowAssets = reconcileGitHubWorkflowAssets;
+exports.formatGitHubWorkflowSyncSummary = formatGitHubWorkflowSyncSummary;
+const axios_1 = __importDefault(require("axios"));
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_loader_1 = require("../../core/config-loader");
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+exports.GITHUB_WORKFLOW_MANIFEST_RELATIVE_PATH = path_1.default.join('fraim', 'managed-assets', 'github-workflows.json');
+exports.GITHUB_WORKFLOW_HEADER = '# FRAIM-MANAGED: github-workflow';
+exports.GITHUB_WORKFLOW_ASSET_PREFIX = '# FRAIM-ASSET-ID: ';
+function sha256(content) {
+    return `sha256:${crypto_1.default.createHash('sha256').update(content).digest('hex')}`;
+}
+function getManifestPath(projectRoot) {
+    return path_1.default.join(projectRoot, exports.GITHUB_WORKFLOW_MANIFEST_RELATIVE_PATH);
+}
+function isGitHubWorkflowAutomationEnabled(config) {
+    return config?.customizations?.githubWorkflows?.enabled === true;
+}
+function decorateManagedGitHubWorkflow(assetId, content) {
+    const normalized = content.replace(/^\uFEFF/, '');
+    const assetHeader = `${exports.GITHUB_WORKFLOW_HEADER}\n${exports.GITHUB_WORKFLOW_ASSET_PREFIX}${assetId}`;
+    if (normalized.includes(exports.GITHUB_WORKFLOW_HEADER) && normalized.includes(`${exports.GITHUB_WORKFLOW_ASSET_PREFIX}${assetId}`)) {
+        return normalized;
+    }
+    return `${assetHeader}\n${normalized}`;
+}
+function isFraimManagedGitHubWorkflow(content, assetId) {
+    if (!content.includes(exports.GITHUB_WORKFLOW_HEADER)) {
+        return false;
+    }
+    if (!assetId) {
+        return true;
+    }
+    return content.includes(`${exports.GITHUB_WORKFLOW_ASSET_PREFIX}${assetId}`);
+}
+function loadGitHubWorkflowManifest(projectRoot) {
+    const manifestPath = getManifestPath(projectRoot);
+    if (!fs_1.default.existsSync(manifestPath)) {
+        return {
+            version: 1,
+            enabled: true,
+            provider: 'github',
+            managedFiles: []
+        };
+    }
+    return JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
+}
+function writeGitHubWorkflowManifest(projectRoot, manifest) {
+    const manifestPath = getManifestPath(projectRoot);
+    fs_1.default.mkdirSync(path_1.default.dirname(manifestPath), { recursive: true });
+    fs_1.default.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+function loadLocalGitHubWorkflowBundle(registryRoot) {
+    const workflowsRoot = path_1.default.join(registryRoot, 'github', 'workflows');
+    if (!fs_1.default.existsSync(workflowsRoot)) {
+        return [];
+    }
+    const files = fs_1.default.readdirSync(workflowsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.yml'))
+        .map((entry) => {
+        const fullPath = path_1.default.join(workflowsRoot, entry.name);
+        const content = fs_1.default.readFileSync(fullPath, 'utf8');
+        return {
+            path: entry.name,
+            content,
+            type: 'github-workflow',
+            digest: sha256(content)
+        };
+    });
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function fetchGitHubWorkflowBundle(options) {
+    const response = await axios_1.default.get(`${options.remoteUrl}/api/registry/github-workflows`, {
+        headers: {
+            'x-api-key': options.apiKey
+        },
+        timeout: 30000
+    });
+    return (response.data.files || []);
+}
+function readProjectConfig(projectRoot, config) {
+    if (config) {
+        return config;
+    }
+    return (0, config_loader_1.loadFraimConfig)((0, project_fraim_paths_1.getWorkspaceConfigPath)(projectRoot));
+}
+function reconcileGitHubWorkflowAssets(options) {
+    const config = readProjectConfig(options.projectRoot, options.config);
+    const provider = config.repository?.provider || null;
+    if (provider !== 'github') {
+        return {
+            enabled: false,
+            provider,
+            skippedReason: 'non-GitHub repo',
+            results: []
+        };
+    }
+    if (!isGitHubWorkflowAutomationEnabled(config)) {
+        return {
+            enabled: false,
+            provider,
+            skippedReason: 'GitHub workflow automation disabled',
+            results: []
+        };
+    }
+    const manifest = loadGitHubWorkflowManifest(options.projectRoot);
+    const manifestEntries = new Map(manifest.managedFiles.map((entry) => [entry.path, entry]));
+    const workflowsDir = path_1.default.join(options.projectRoot, '.github', 'workflows');
+    fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+    const results = [];
+    const nextManagedFiles = [];
+    for (const file of options.files) {
+        const assetId = path_1.default.basename(file.path);
+        const relativeWorkflowPath = path_1.default.join('.github', 'workflows', file.path).replace(/[\\/]/g, '/');
+        const destinationPath = path_1.default.join(options.projectRoot, '.github', 'workflows', file.path);
+        const desiredContent = decorateManagedGitHubWorkflow(assetId, file.content);
+        const desiredInstalledDigest = sha256(desiredContent);
+        const previousEntry = manifestEntries.get(relativeWorkflowPath);
+        if (!fs_1.default.existsSync(destinationPath)) {
+            fs_1.default.mkdirSync(path_1.default.dirname(destinationPath), { recursive: true });
+            fs_1.default.writeFileSync(destinationPath, desiredContent, 'utf8');
+            nextManagedFiles.push({
+                path: relativeWorkflowPath,
+                assetId,
+                sourceDigest: file.digest,
+                installedDigest: desiredInstalledDigest
+            });
+            results.push({
+                path: relativeWorkflowPath,
+                assetId,
+                status: 'installed'
+            });
+            continue;
+        }
+        const currentContent = fs_1.default.readFileSync(destinationPath, 'utf8');
+        const currentDigest = sha256(currentContent);
+        const ownedByFraim = isFraimManagedGitHubWorkflow(currentContent, assetId) || Boolean(previousEntry);
+        if (!ownedByFraim) {
+            if (previousEntry) {
+                nextManagedFiles.push(previousEntry);
+            }
+            results.push({
+                path: relativeWorkflowPath,
+                assetId,
+                status: 'conflict',
+                reason: 'same-named file exists without FRAIM ownership marker'
+            });
+            continue;
+        }
+        if (currentDigest === desiredInstalledDigest) {
+            nextManagedFiles.push({
+                path: relativeWorkflowPath,
+                assetId,
+                sourceDigest: file.digest,
+                installedDigest: desiredInstalledDigest
+            });
+            results.push({
+                path: relativeWorkflowPath,
+                assetId,
+                status: 'already current'
+            });
+            continue;
+        }
+        if (previousEntry && currentDigest === previousEntry.installedDigest) {
+            fs_1.default.writeFileSync(destinationPath, desiredContent, 'utf8');
+            nextManagedFiles.push({
+                path: relativeWorkflowPath,
+                assetId,
+                sourceDigest: file.digest,
+                installedDigest: desiredInstalledDigest
+            });
+            results.push({
+                path: relativeWorkflowPath,
+                assetId,
+                status: 'updated'
+            });
+            continue;
+        }
+        nextManagedFiles.push(previousEntry || {
+            path: relativeWorkflowPath,
+            assetId,
+            sourceDigest: file.digest,
+            installedDigest: currentDigest
+        });
+        results.push({
+            path: relativeWorkflowPath,
+            assetId,
+            status: 'conflict',
+            reason: previousEntry
+                ? 'managed file has local edits that do not match the last installed digest'
+                : 'FRAIM-managed header exists without manifest baseline'
+        });
+    }
+    writeGitHubWorkflowManifest(options.projectRoot, {
+        version: 1,
+        enabled: true,
+        provider: 'github',
+        managedFiles: nextManagedFiles.sort((a, b) => a.path.localeCompare(b.path))
+    });
+    return {
+        enabled: true,
+        provider,
+        results
+    };
+}
+function formatGitHubWorkflowSyncSummary(result) {
+    if (!result.enabled) {
+        return [`GitHub workflow reconciliation skipped: ${result.skippedReason || 'not enabled'}`];
+    }
+    if (result.results.length === 0) {
+        return ['GitHub workflow reconciliation: no workflow assets found'];
+    }
+    return result.results.map((item) => {
+        const suffix = item.reason ? ` (${item.reason})` : '';
+        return `GitHub workflow ${item.status}: ${item.path}${suffix}`;
+    });
+}

package/dist/src/cli/utils/managed-agent-paths.js

@@ -34,7 +34,7 @@ function getManagedAgentBinDirs() {
     const portableNodeBin = getPortableNodeBinPath();
     const candidates = process.platform === 'win32'
         ? [nodeRoot, portableNodeBin]
-        : [path_1.default.join(nodeRoot, 'bin'), portableNodeBin];
+        : [nodeRoot, path_1.default.join(nodeRoot, 'bin'), portableNodeBin];
     return [...new Set(candidates.filter(Boolean))];
 }
 function buildPathWithManagedAgentBins(basePath) {

package/dist/src/cli/utils/project-bootstrap.js

@@ -22,7 +22,7 @@ function formatModeLabel(mode) {
 function getModeSpecificNextStep(mode) {
     switch (mode) {
         case 'conversational':
-            return `The agent will create fraim/config.json during onboarding, then focus on project context, validation commands, and durable repo rules. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
+            return `The agent will create fraim/config.json during onboarding, then focus on project context, validation commands, and durable project rules. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
         case 'split':
             return `The agent will create fraim/config.json during onboarding, confirm the code-host and issue-tracker split, then ask only for the missing project details. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
         default:
@@ -70,12 +70,15 @@ function buildInitProjectSummary(result) {
 }
 function printInitProjectSummary(result) {
     const summary = buildInitProjectSummary(result);
+    const showRepositoryDetails = result.mode !== 'conversational';
     console.log(chalk_1.default.green(`\n${summary.status}`));
     console.log(chalk_1.default.blue('Project summary:'));
     console.log(chalk_1.default.gray(`   Mode: ${summary.fields.mode}`));
     console.log(chalk_1.default.gray(`   Project: ${summary.fields.project}`));
-    console.log(chalk_1.default.gray(`   Repository detection: ${summary.fields.repositoryDetection}`));
-    console.log(chalk_1.default.gray(`   Issue tracking: ${summary.fields.issueTracking}`));
+    if (showRepositoryDetails) {
+        console.log(chalk_1.default.gray(`   Repository detection: ${summary.fields.repositoryDetection}`));
+        console.log(chalk_1.default.gray(`   Issue tracking: ${summary.fields.issueTracking}`));
+    }
     console.log(chalk_1.default.gray(`   Sync: ${summary.fields.sync}`));
     if (summary.fields.createdPaths.length > 0) {
         console.log(chalk_1.default.gray(`   Created: ${summary.fields.createdPaths.join(', ')}`));

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

@@ -31,8 +31,8 @@ function shouldLockSyncedContent() {
 }
 function getSyncedContentLockTargets(projectRoot) {
     return fraim_gitignore_1.FRAIM_SYNC_GITIGNORE_ENTRIES
+        .filter((entry) => /[\\/]$/.test(entry))
         .map((entry) => entry.replace(/[\\/]+$/, ''))
-        .filter((entry) => entry.length > 0)
         .map((entry) => (0, path_1.join)(projectRoot, entry));
 }
 function setFileWriteLockRecursively(dirPath, readOnly) {

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

@@ -28,7 +28,6 @@ class AIMentor {
                 throw new Error(`Phase "${args.currentPhase}" not found in job "${args.jobName}".`);
             }
         }
-        // Handle different statuses
         if (args.status === 'starting') {
             return await this.generateStartingMessage(workflow, args.currentPhase, args.skipIncludes);
         }
@@ -63,27 +62,17 @@ class AIMentor {
     buildReportBackFooter(jobName, phaseId, phaseFlow) {
         if (!phaseFlow)
             return '';
-        const base = `seekMentoring({
-  jobName: "${jobName}",
-  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;
+        const completionCall = `seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete" })`;
+        if (!onSuccess || typeof onSuccess === 'string') {
+            const finalPhaseNote = onSuccess ? '' : ' This is the final phase.';
+            return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`${completionCall}\`.${finalPhaseNote}`;
+        }
+        const validOutcomes = Object.keys(onSuccess)
+            .filter((key) => key !== 'default')
+            .map((key) => `"${key}"`)
+            .join(' | ');
+        return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete", findings: { issueType: "<outcome>" } })\` with one of: ${validOutcomes}.`;
     }
     /** Phase-authority content injected for all phased workflows. Loaded from orchestration/phase-authority.md. */
     async getPhaseAuthorityContent() {
@@ -95,18 +84,32 @@ class AIMentor {
             return '';
         }
     }
+    getCompactPhaseAuthority() {
+        return AIMentor.COMPACT_PHASE_AUTHORITY;
+    }
     async prependPhaseAuthority(message, isPhased) {
         if (!isPhased)
             return message;
-        const block = await this.getPhaseAuthorityContent();
-        if (!block)
-            return message;
-        return `${block}\n\n---\n\n${message}`;
+        return `${this.getCompactPhaseAuthority()}\n\n${message}`;
+    }
+    buildPhasedJobOverview(workflow) {
+        const metadataPhases = Object.keys(workflow.metadata.phases || {});
+        const initialPhase = workflow.metadata.initialPhase || metadataPhases[0] || Array.from(workflow.phases.keys())[0] || 'starting';
+        const overview = workflow.overview.trim();
+        return [
+            overview,
+            '',
+            '---',
+            '',
+            '## Start Here',
+            `- Initial phase: \`${initialPhase}\``,
+            '- Call `seekMentoring` to load the instructions for this phase.'
+        ].join('\n');
     }
     async generateStartingMessage(workflow, phaseId, skipIncludes) {
         const entityType = 'Job';
         if (workflow.isSimple) {
-            const message = `🚀 **Starting ${entityType}: ${workflow.metadata.name}**\n\n${workflow.overview}`;
+            const message = `Starting ${entityType}: ${workflow.metadata.name}\n\n${workflow.overview}`;
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (starting)`);
             return {
                 message,
@@ -116,17 +119,14 @@ class AIMentor {
         }
         const isVeryFirstCall = phaseId === 'starting';
         const targetPhase = isVeryFirstCall ? (workflow.metadata.initialPhase || 'starting') : phaseId;
-        let message = '';
-        if (isVeryFirstCall && workflow.overview) {
-            message += `${workflow.overview}\n\n---\n\n`;
-        }
+        let message = `### Current Phase: ${targetPhase}\n\n`;
         let instructions = workflow.phases.get(targetPhase);
         if (instructions) {
             instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
-            message += `${instructions}`;
+            message += instructions;
         }
         else {
-            message += `⚠️ No specific instructions found for phase: ${targetPhase}`;
+            message += `No specific instructions found for phase: ${targetPhase}`;
         }
         const phaseFlow = workflow.metadata.phases?.[targetPhase];
         message += this.buildReportBackFooter(workflow.metadata.name, targetPhase, phaseFlow);
@@ -142,7 +142,7 @@ class AIMentor {
     async generateCompletionMessage(workflow, phaseId, findings, evidence, skipIncludes) {
         const entityType = 'Job';
         if (workflow.isSimple) {
-            const message = `✅ **${entityType} Complete: ${workflow.metadata.name}**\n\n🎉 Great work! You have completed the ${workflow.metadata.name} ${entityType.toLowerCase()}.`;
+            const message = `${entityType} Complete: ${workflow.metadata.name}\n\nYou have completed the ${workflow.metadata.name} ${entityType.toLowerCase()}.`;
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (complete)`);
             return {
                 message,
@@ -158,12 +158,12 @@ class AIMentor {
             }
             else {
                 const outcome = findings?.phaseOutcome ?? findings?.issueType ?? evidence?.issueType ?? evidence?.phaseOutcome ?? 'default';
-                nextPhaseId = phaseFlow.onSuccess[outcome] ?? phaseFlow.onSuccess['default'] ?? null;
+                nextPhaseId = phaseFlow.onSuccess[outcome] ?? phaseFlow.onSuccess.default ?? null;
             }
         }
         let message = '';
         if (nextPhaseId) {
-            message += `Great work. Moving to the next phase: **${nextPhaseId}**.\n\n`;
+            message += `Moving to the next phase: **${nextPhaseId}**.\n\n`;
             let nextInstructions = workflow.phases.get(nextPhaseId);
             if (nextInstructions) {
                 nextInstructions = skipIncludes ? nextInstructions : await this.resolveIncludes(nextInstructions, workflow.path);
@@ -187,7 +187,7 @@ class AIMentor {
     async generateHelpMessage(workflow, phaseId, status, skipIncludes) {
         const entityType = 'Job';
         if (workflow.isSimple) {
-            const message = `**${entityType}: ${workflow.metadata.name}**\n\n${workflow.overview}`;
+            const message = `${entityType}: ${workflow.metadata.name}\n\n${workflow.overview}`;
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name} (${status})`);
             return {
                 message,
@@ -214,7 +214,15 @@ class AIMentor {
     }
     async getJobOverview(jobName) {
         const job = await this.getOrLoadJob(jobName);
-        return job ? { overview: job.overview, isSimple: job.isSimple } : null;
+        if (!job)
+            return null;
+        if (job.isSimple) {
+            return { overview: job.overview, isSimple: true };
+        }
+        return {
+            overview: this.buildPhasedJobOverview(job),
+            isSimple: false
+        };
     }
     async getAllJobMetadata() {
         const items = await this.resolver.listItems('job');
@@ -228,3 +236,4 @@ class AIMentor {
     }
 }
 exports.AIMentor = AIMentor;
+AIMentor.COMPACT_PHASE_AUTHORITY = '**Use only the phases defined in this workflow.**';