fraim 2.0.341 → 2.0.343

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

@@ -69,7 +69,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    Use this process only when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job. For ordinary requests, answer or work normally; do not scan FRAIM stubs first.
 
 2. **If the user did not specify a FRAIM job or topic after activation**:
-   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.
+   If local FRAIM job stubs are present in the workspace, read that jobs directory's \`INDEX.md\` first (it lists every job's name, one-line intent, and category) and match the request against it; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no \`INDEX.md\` is present. Also check \`fraim/personalized-employee/jobs/\` (and its own \`INDEX.md\`, if present) 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.
 
 3. **Find the match**:
    If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, 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 exact or high-confidence job match exists, call \`get_fraim_job({ job: "adhoc-prompt" })\` directly and execute it with the user's instructions as the task input — no confirmation question, and do not pick the nearest catalog job.

package/dist/src/cli/utils/agent-adapters.js

@@ -72,7 +72,7 @@ This repository uses FRAIM.
 - Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.
 - For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.
 - If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly.
-- When FRAIM routing is active but the job is not exact, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections before using catalog tools.
+- When FRAIM routing is active but the job is not exact, read \`${employeeJobsPath}/INDEX.md\` and \`${managerJobsPath}/INDEX.md\` first (each lists every job's name, one-line intent, and category) to identify the most appropriate job; open an individual job stub only to confirm a shortlisted candidate. If an \`INDEX.md\` is missing or looks stale, fall back to scanning the job stubs under those directories directly. Also check \`${personalizedRootPath}/jobs/INDEX.md\` (or its stubs, if no index is present) for local overrides or repo-specific jobs.
 - Once you identify the relevant job, call \`get_fraim_job({ job: "<job-name>" })\` to get the full phased instructions.
 - If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.
 - For deeper capability detail, call \`get_fraim_file({ path: "skills/<category>/<skill-name>.md" })\` or \`get_fraim_file({ path: "rules/<category>/<rule-name>.md" })\`.
@@ -99,7 +99,7 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 - Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.
 - For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.
 - If the user names an exact FRAIM job, fetch that full job directly with FRAIM MCP tools.
-- When FRAIM routing is active but the job is not exact, use local stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- When FRAIM routing is active but the job is not exact, read the local jobs directory's \`INDEX.md\` first to identify which job to invoke (falling back to the individual stub files if no index is present) before fetching full content with FRAIM MCP tools.
 - If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.
 - **Job stubs are for discovery only.** Never execute a job from stub content - always call \`get_fraim_job({ job: "<job-name>" })\` first.
 - ${ide_invocation_surfaces_1.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
@@ -108,13 +108,13 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 
 This directory is the repository-visible FRAIM surface.
 
-- \`ai-employee/jobs/\`: employee job stubs
-- \`ai-manager/jobs/\`: manager job stubs
-- \`ai-employee/skills/\`: skill stubs
+- \`ai-employee/jobs/\`: employee job stubs (+ \`INDEX.md\`)
+- \`ai-manager/jobs/\`: manager job stubs (+ \`INDEX.md\`)
+- \`ai-employee/skills/\`: skill stubs (+ \`INDEX.md\`)
 - \`ai-employee/rules/\`: rule stubs
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
-When FRAIM routing is active and no exact FRAIM job is named, use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.
+When FRAIM routing is active and no exact FRAIM job is named, read the \`INDEX.md\` in the relevant directory first to discover which FRAIM job, skill, or rule is relevant (falling back to scanning the individual stubs if no index is present), then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.
 `;
     const vscodePrompt = `# FRAIM
 

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

@@ -23,6 +23,7 @@ const path_1 = require("path");
 const chalk_1 = __importDefault(require("chalk"));
 const script_sync_utils_1 = require("./script-sync-utils");
 const fraim_gitignore_1 = require("./fraim-gitignore");
+const capability_index_1 = require("../../core/utils/capability-index");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const LOCK_SYNCED_CONTENT_ENV = 'FRAIM_LOCK_SYNCED_CONTENT';
 exports.SYNCED_CONTENT_BANNER_MARKER = '<!-- FRAIM_SYNC_MANAGED_CONTENT -->';
@@ -268,6 +269,7 @@ async function syncRoleJobsToUserDir(roleFiles, role) {
         }
         (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
     }
+    (0, capability_index_1.writeCapabilityIndex)(targetDir, 'job');
     return roleFiles.length;
 }
 /**
@@ -353,6 +355,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/jobs/${relativePath}`)}`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(employeeJobsDir, 'job');
         // Sync ai-manager job stubs to fraim/ai-manager/jobs/
         const managerJobsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-manager', 'jobs');
         cleanWorkspaceDirectory(options.projectRoot, managerJobsDir, 'manager job directory', assertWorkspacePath, 'ai-manager', 'jobs');
@@ -370,6 +373,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-manager/jobs/${relativePath}`)}`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(managerJobsDir, 'job');
         // Sync skill STUBS to fraim/ai-employee/skills/
         const skillFiles = files.filter(f => f.type === 'skill');
         const skillsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'skills');
@@ -387,6 +391,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/skills/${relativePath}`)} (stub)`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(skillsDir, 'skill');
         // Sync rule STUBS to fraim/ai-employee/rules/
         const ruleFiles = files.filter(f => f.type === 'rule');
         const rulesDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'rules');

package/dist/src/config/persona-hiring.js

@@ -282,7 +282,13 @@ function buildPersonaAvatarUrl(personaKey) {
     return `https://api.dicebear.com/9.x/${avatar.style}/svg?${params.toString()}`;
 }
 function isPersonaHireKey(value) {
-    return value in exports.PERSONA_HIRE_CATALOG;
+    // Own properties only. `in` also answers true for every Object.prototype member,
+    // so 'constructor', 'toString', '__proto__' and friends passed this guard and then
+    // indexed the catalog to a prototype member rather than a persona. The guard is the
+    // input validation in front of the hire-checkout and entitlement reads, where the
+    // value is caller-supplied, and (issue #1925) in front of the employee-record reader,
+    // where it is file-supplied.
+    return Object.prototype.hasOwnProperty.call(exports.PERSONA_HIRE_CATALOG, value);
 }
 function getPersonaHireAmountCents(personaKey, mode) {
     const persona = exports.PERSONA_HIRE_CATALOG[personaKey];

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

@@ -65,6 +65,9 @@ class AIMentor {
         const unique = Array.from(new Set(matches));
         throw new Error(`Unresolved include directives in ${context}: ${unique.join(', ')}`);
     }
+    buildPhaseArrivalInstruction(jobName, phaseId) {
+        return `## On Arrival\nBefore starting any work in this phase, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "starting" })\`.\n\n`;
+    }
     buildReportBackFooter(jobName, phaseId, phaseFlow) {
         if (!phaseFlow)
             return '';
@@ -140,6 +143,9 @@ class AIMentor {
             targetPhase = isVeryFirstCall ? targetDefinition.setup.phase : targetDefinition.recur.phase;
         }
         let message = `### Current Phase: ${targetPhase}\n\n`;
+        if (isVeryFirstCall) {
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, targetPhase);
+        }
         let instructions = workflow.phases.get(targetPhase);
         if (instructions) {
             instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
@@ -229,6 +235,7 @@ class AIMentor {
         }
         else if (nextPhaseId) {
             message += `Moving to the next phase: **${nextPhaseId}**.\n\n`;
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, nextPhaseId);
             let nextInstructions = workflow.phases.get(nextPhaseId);
             if (nextInstructions) {
                 nextInstructions = skipIncludes ? nextInstructions : await this.resolveIncludes(nextInstructions, workflow.path);
@@ -275,6 +282,13 @@ class AIMentor {
                 ?? (!(0, resolve_phase_edge_1.isRecurrencePhase)(phaseMeta) ? phaseMeta?.onFailure : undefined), (0, resolve_phase_edge_1.resolveDiscriminant)(findings, evidence)) || phaseId)
             : phaseId;
         let message = `### Current Phase: ${targetPhaseId}\n\n`;
+        // Issue #1935: a `failure` commits a completion for the phase being left, so
+        // the phase resolved above is entered with no open instance and needs its own
+        // `status: "starting"` call, for a back-edge and for the self-retry alike.
+        // `incomplete` commits nothing and never leaves the phase, so it gets none.
+        if (status === 'failure') {
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, targetPhaseId);
+        }
         let instructions = workflow.phases.get(targetPhaseId);
         if (instructions) {
             instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);

package/dist/src/core/handoff-contracts.js

@@ -297,11 +297,16 @@ function upsertPhaseStarted(marker, phaseId, timestamp) {
     startedPhases[phaseId] = timestamp;
     return { startedPhases };
 }
-/** Builds the warn-only notice for any phase completed without an on-arrival start. */
-function buildPhaseStartWarning(phaseId) {
-    return (`⚠️ **Phase-start notice**: phase \`${phaseId}\` completed without an on-arrival ` +
+/** Builds the warn-only notice for any phase completed without an on-arrival start.
+ * When nextPhase is supplied, a forward-looking instruction is appended so the agent
+ * knows to call seekMentoring({status:"starting"}) before beginning the next phase. */
+function buildPhaseStartWarning(phaseId, nextPhase) {
+    const base = (`⚠️ **Phase-start notice**: phase \`${phaseId}\` completed without an on-arrival ` +
         `\`seekMentoring({ currentPhase: "${phaseId}", status: "starting" })\` call in this session. ` +
         `The missing call was flagged, but this completion remains accepted.\n\n`);
+    if (!nextPhase)
+        return base;
+    return base + `Before starting any work in **${nextPhase}**, call \`seekMentoring({ currentPhase: "${nextPhase}", status: "starting" })\` immediately.\n\n`;
 }
 function isAbsoluteHttpUrl(url) {
     if (typeof url !== 'string' || !url)

package/dist/src/core/utils/capability-index.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_INDEX_FILENAME = void 0;
+exports.buildCapabilityIndexContent = buildCapabilityIndexContent;
+exports.writeCapabilityIndex = writeCapabilityIndex;
+exports.refreshPersonalizedJobsIndex = refreshPersonalizedJobsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const stub_generator_1 = require("./stub-generator");
+exports.CAPABILITY_INDEX_FILENAME = 'INDEX.md';
+const CAPABILITY_INDEX_MARKER = '<!-- FRAIM_DISCOVERY_INDEX -->';
+const MAX_SUMMARY_LENGTH = 140;
+function oneLine(text, maxLength = MAX_SUMMARY_LENGTH) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function fetchHintFor(kind, entry) {
+    return kind === 'job'
+        ? `get_fraim_job({ job: "${entry.name}" })`
+        : `get_fraim_file({ path: "skills/${entry.category}/${entry.name}.md" })`;
+}
+/**
+ * Builds the compact index markdown for one stub layer (all job stubs, or all
+ * skill stubs, under a single jobs/ or skills/ root). Pure function so the
+ * content can be unit-tested without touching the filesystem.
+ */
+function buildCapabilityIndexContent(kind, entries) {
+    const noun = kind === 'job' ? 'Job' : 'Skill';
+    const sorted = [...entries].sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    const categorized = new Map();
+    for (const entry of sorted) {
+        const list = categorized.get(entry.category) ?? [];
+        list.push(entry);
+        categorized.set(entry.category, list);
+    }
+    const lines = [
+        CAPABILITY_INDEX_MARKER,
+        `# FRAIM ${noun} Index`,
+        '',
+        `Compact discovery index for this layer's ${kind} stubs — read this file first instead of opening every individual stub.`,
+    ];
+    for (const [category, categoryEntries] of categorized) {
+        lines.push('', `## ${category}`);
+        for (const entry of categoryEntries) {
+            lines.push(`- **${entry.name}**: ${entry.summary} (${fetchHintFor(kind, entry)})`);
+        }
+    }
+    lines.push('', '---', '', '> [!IMPORTANT]', `> This index is for discovery only. Once you have a candidate ${kind}, fetch its full content before acting on it — never execute from the one-line summary above.`);
+    return `${lines.join('\n')}\n`;
+}
+function readCategoryEntries(kind, rootDir) {
+    const entries = [];
+    const categoryDirents = fs_1.default.existsSync(rootDir)
+        ? fs_1.default.readdirSync(rootDir, { withFileTypes: true }).filter((d) => d.isDirectory())
+        : [];
+    for (const categoryDirent of categoryDirents) {
+        const categoryDir = path_1.default.join(rootDir, categoryDirent.name);
+        const fileNames = fs_1.default
+            .readdirSync(categoryDir, { withFileTypes: true })
+            .filter((d) => d.isFile() && d.name.endsWith('.md'))
+            .map((d) => d.name);
+        for (const fileName of fileNames) {
+            const filePath = path_1.default.join(categoryDir, fileName);
+            const content = fs_1.default.readFileSync(filePath, 'utf8');
+            const name = fileName.replace(/\.md$/, '');
+            const summary = kind === 'job'
+                ? oneLine((0, stub_generator_1.parseRegistryJob)(content).intent)
+                : oneLine((0, stub_generator_1.parseRegistrySkill)(content).skillInput);
+            entries.push({ category: categoryDirent.name, name, summary });
+        }
+    }
+    return entries;
+}
+/**
+ * Scans a jobs/ or skills/ root (one file per {category}/{name}.md, mirroring
+ * the layout every stub layer already uses) and (re)writes a compact INDEX.md
+ * at that root. Safe to call on a root with no category subfolders yet (writes
+ * nothing, since there is nothing to index).
+ */
+function writeCapabilityIndex(rootDir, kind) {
+    if (!fs_1.default.existsSync(rootDir))
+        return;
+    const entries = readCategoryEntries(kind, rootDir);
+    if (entries.length === 0)
+        return;
+    const indexPath = path_1.default.join(rootDir, exports.CAPABILITY_INDEX_FILENAME);
+    fs_1.default.writeFileSync(indexPath, buildCapabilityIndexContent(kind, entries), 'utf8');
+}
+/**
+ * Refreshes the job-stub index for the one layer `fraim sync` never writes:
+ * `fraim/personalized-employee/jobs/` and `.../manager-jobs/`. That layer is
+ * populated by agent writes (e.g. the evolve-employee job), not by sync, so
+ * there is no deterministic write path to hook — callers invoke this directly
+ * after writing or changing a personalized job overlay file.
+ */
+function refreshPersonalizedJobsIndex(projectRoot) {
+    writeCapabilityIndex(path_1.default.join(projectRoot, 'fraim', 'personalized-employee', 'jobs'), 'job');
+    writeCapabilityIndex(path_1.default.join(projectRoot, 'fraim', 'personalized-employee', 'manager-jobs'), 'job');
+}

package/dist/src/core/utils/local-registry-resolver.js

@@ -520,33 +520,60 @@ class LocalRegistryResolver {
             // publish or sync and resolves at all under `single-machine`).
             const managerLocalContent = this.readManagerLocalOverlayFile(path);
             if (managerLocalContent !== null) {
+                // Issue #1867: apply inheritance so an extends-based override merges with its parent.
+                let resolvedManagerLocal;
+                try {
+                    resolvedManagerLocal = await this.resolveInheritance(managerLocalContent, path);
+                }
+                catch {
+                    resolvedManagerLocal = { content: managerLocalContent, imports: [] };
+                }
                 return {
-                    content: managerLocalContent,
+                    content: resolvedManagerLocal.content,
                     source: 'local',
                     personalized: true,
-                    inherited: false,
+                    inherited: resolvedManagerLocal.imports.length > 0,
+                    imports: resolvedManagerLocal.imports.length > 0 ? resolvedManagerLocal.imports : undefined,
                     scope: 'manager'
                 };
             }
             // Issue #869: manager overlay (precedence 3 — the synced cross-machine copy)
             const managerOverlayContent = this.readManagerOverlayFile(path);
             if (managerOverlayContent !== null) {
+                // Issue #1867: apply inheritance so an extends-based override merges with its parent.
+                let resolvedManagerOverlay;
+                try {
+                    resolvedManagerOverlay = await this.resolveInheritance(managerOverlayContent, path);
+                }
+                catch {
+                    resolvedManagerOverlay = { content: managerOverlayContent, imports: [] };
+                }
                 return {
-                    content: managerOverlayContent,
+                    content: resolvedManagerOverlay.content,
                     source: 'local',
                     personalized: true,
-                    inherited: false,
+                    inherited: resolvedManagerOverlay.imports.length > 0,
+                    imports: resolvedManagerOverlay.imports.length > 0 ? resolvedManagerOverlay.imports : undefined,
                     scope: 'manager'
                 };
             }
             // Issue #869 Phase 2: org overlay (precedence 3 — after manager, before synced baseline)
             const orgOverlayContent = this.readOrgOverlayFile(path);
             if (orgOverlayContent !== null) {
+                // Issue #1867: apply inheritance so an extends-based override merges with its parent.
+                let resolvedOrgOverlay;
+                try {
+                    resolvedOrgOverlay = await this.resolveInheritance(orgOverlayContent, path);
+                }
+                catch {
+                    resolvedOrgOverlay = { content: orgOverlayContent, imports: [] };
+                }
                 return {
-                    content: orgOverlayContent,
+                    content: resolvedOrgOverlay.content,
                     source: 'local',
                     personalized: true,
-                    inherited: false,
+                    inherited: resolvedOrgOverlay.imports.length > 0,
+                    imports: resolvedOrgOverlay.imports.length > 0 ? resolvedOrgOverlay.imports : undefined,
                     scope: 'org'
                 };
             }

package/dist/src/local-mcp-server/stdio-server.js

@@ -1371,7 +1371,7 @@ class FraimLocalMCPServer {
             updated.phaseInstances = updated.phaseInstances?.filter((instance) => instance.jobId && instance.jobId !== args.jobId);
         }
         this.writeRunStateMarker(sessionId, args.jobName, updated);
-        return (inspection.missingStart ? (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase) : '')
+        return (inspection.missingStart ? (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase, nextPhase ?? undefined) : '')
             + (!args.jobId ? `Run-tracking notice: phase ${args.currentPhase} has no jobId; matching used the session, job name and phase.\n\n` : '');
     }
     readCachedTemplateFile(filename) {

package/dist/src/mcp/tool-schemas.js

@@ -343,7 +343,7 @@ Do not use this tool for other repositories or external project issue trackers.`
                     },
                     currentPhase: {
                         type: 'string',
-                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, use "starting".'
+                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, pass "starting" as a one-time bootstrap — this is distinct from the per-phase status:"starting" on-arrival call you make at the beginning of every phase.'
                     },
                     status: {
                         type: 'string',

package/dist/src/services/mcp-service.js

@@ -548,8 +548,8 @@ class McpService {
             '- Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.',
             '- For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.',
             '- If the user already named a job, call `get_fraim_job({ job: "<job-name>" })` directly.',
-            '- If routing is active and local FRAIM job stubs are present under `fraim/ai-employee/jobs/` or `fraim/ai-manager/jobs/`, inspect those first to choose the best job.',
-            '- Also inspect `fraim/personalized-employee/jobs/` for local job overrides or repo-specific jobs when routing is active.',
+            '- If routing is active and local FRAIM job stubs are present under `fraim/ai-employee/jobs/` or `fraim/ai-manager/jobs/`, read that directory\'s `INDEX.md` first (name, one-line intent, and category per job) to choose the best job; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no `INDEX.md` is present.',
+            '- Also check `fraim/personalized-employee/jobs/` (and its own `INDEX.md`, if present) for local job overrides or repo-specific jobs when routing is active.',
             '- If local stubs are missing, you cannot inspect workspace files, or the user asks for available jobs, call `list_fraim_jobs()` to view the full catalog.',
             '- If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.',
             '- Use `get_fraim_file(...)` only for the specific skills or rules needed for the current task.',
@@ -824,7 +824,7 @@ class McpService {
             else if (isPhaseCompletion) {
                 const inspection = (0, handoff_contracts_1.inspectPhaseCompletion)(marker, context);
                 if (inspection.missingStart)
-                    phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase);
+                    phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase, result.nextPhase ?? undefined);
                 const completed = (0, handoff_contracts_1.commitPhaseCompletion)(marker, inspection, { ...context, timestamp });
                 this.phaseStartMarkers.set(markerKey, completed);
                 if (args.status === 'complete' && result.nextPhase === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.341",
+  "version": "2.0.343",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {