fraim 2.0.305 → 2.0.307

package/dist/src/cli/commands/sync.js

@@ -293,8 +293,11 @@ const runSync = async (options) => {
         });
         if (result.success) {
             // Local-dev sync bypasses Layer 1 (machine-level sync) below, but scripts
-            // still need to land in ~/.fraim/scripts/ or the reported count is a lie.
+            // and docs still need to land in ~/.fraim/ or the reported counts are a lie.
             await (0, remote_sync_1.syncScriptsToUserDir)(localRegistryFiles);
+            await (0, remote_sync_1.syncDocsToUserDir)(localRegistryFiles);
+            const { ensureUserLevelDependencies: ensureLocalUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+            ensureLocalUserLevelDependencies();
             console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
             const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
             removeLegacyVersionFromConfig(fraimDir);
@@ -354,6 +357,12 @@ const runSync = async (options) => {
     if (scriptsSynced > 0) {
         console.log(chalk_1.default.green(`  Synced ${scriptsSynced} scripts to ~/.fraim/scripts/`));
     }
+    // 1b2. Sync docs to ~/.fraim/docs/ (Issue #1508: machine-level docs, e.g.
+    // TROUBLESHOOTING.md, must exist on disk the same way scripts do)
+    const docsSynced = await (0, remote_sync_1.syncDocsToUserDir)(registryFiles);
+    if (docsSynced > 0) {
+        console.log(chalk_1.default.green(`  Synced ${docsSynced} docs to ~/.fraim/docs/`));
+    }
     // 1c. Refresh org home
     await refreshOrgCache(remoteUrl, apiKey);
     // 1d. Refresh manager home
@@ -361,9 +370,12 @@ const runSync = async (options) => {
     // 1e. Refresh MCP proxy launcher
     const { ensureFraimMcpLatestLauncher } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
     ensureFraimMcpLatestLauncher();
-    // 1f. Ensure user-level directories
-    const { ensureUserLevelDirectories } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+    // 1f. Ensure user-level directories and runtime dependencies (Issue #1508:
+    // synced scripts like the DOCX review layer require npm deps such as
+    // adm-zip; a plain sync must install them, not just create directories)
+    const { ensureUserLevelDirectories, ensureUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
     ensureUserLevelDirectories();
+    ensureUserLevelDependencies();
     // 1g. Write sync metadata
     writeSyncMetadata('remote', remoteUrl);
     console.log(chalk_1.default.green('✅ Machine-level sync complete.'));

package/dist/src/cli/doctor/checks/scripts-checks.js

@@ -12,8 +12,73 @@ exports.getScriptsChecks = getScriptsChecks;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const module_1 = __importDefault(require("module"));
 const child_process_1 = require("child_process");
 const SCRIPTS_DIR = path_1.default.join(os_1.default.homedir(), '.fraim', 'scripts');
+// Conservative static-require extractor: only matches literal
+// require('name') / require("name") calls, not dynamic requires or imports.
+const STATIC_REQUIRE_PATTERN = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+/**
+ * Recursively list .js/.cjs files under a directory.
+ */
+function listNodeScripts(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip vendored dependency trees. A script that ships its own bundled
+            // library (e.g. ~/.fraim/scripts/lib/node_modules/@scope/pkg/...) is
+            // not itself a FRAIM script requiring dependency resolution — it IS a
+            // resolved dependency. Recursing into it produces false-positive
+            // warnings about that library's own devDependency-only files (e.g. a
+            // benchmark/test file requiring a module never meant to be installed
+            // under ~/.fraim/node_modules). Confirmed against a real machine: see
+            // issue #1508 manual validation.
+            if (entry.name === 'node_modules')
+                continue;
+            results.push(...listNodeScripts(fullPath));
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.cjs'))) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Extract external (non-relative, non-absolute, non-builtin) module names
+ * statically required by a script, using its own directory for resolution.
+ */
+function extractExternalRequires(scriptPath) {
+    let content;
+    try {
+        content = fs_1.default.readFileSync(scriptPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const modules = new Set();
+    let match;
+    STATIC_REQUIRE_PATTERN.lastIndex = 0;
+    while ((match = STATIC_REQUIRE_PATTERN.exec(content)) !== null) {
+        const moduleName = match[1];
+        if (moduleName.startsWith('.') ||
+            moduleName.startsWith('/') ||
+            /^[a-zA-Z]:[\\/]/.test(moduleName) ||
+            moduleName.startsWith('node:') ||
+            module_1.default.builtinModules.includes(moduleName)) {
+            continue;
+        }
+        modules.add(moduleName);
+    }
+    return Array.from(modules);
+}
 /**
  * Check if scripts directory exists
  */
@@ -211,6 +276,73 @@ function checkPythonAvailability() {
         }
     };
 }
+/**
+ * Check that synced Node scripts can resolve their external runtime
+ * dependencies (e.g. `require('adm-zip')`) from their own directory.
+ *
+ * Distinguishes delivery (the script file exists) from executability (the
+ * script's require statements actually resolve). Issue #1508: `doctor`
+ * reported the DOCX review scripts healthy while all six threw
+ * `Cannot find module 'adm-zip'` at require time.
+ *
+ * Does not execute the scripts — only statically parses `require(...)`
+ * calls and resolves them the way Node would from the script's directory.
+ */
+function checkNodeScriptDependencies() {
+    return {
+        name: 'Node script dependencies available',
+        category: 'scripts',
+        critical: false,
+        run: async () => {
+            if (!fs_1.default.existsSync(SCRIPTS_DIR)) {
+                return {
+                    status: 'passed',
+                    message: 'No scripts synced — Node dependency check skipped'
+                };
+            }
+            const scripts = listNodeScripts(SCRIPTS_DIR);
+            if (scripts.length === 0) {
+                return {
+                    status: 'passed',
+                    message: 'No Node scripts synced — Node dependency check skipped'
+                };
+            }
+            const unresolved = {};
+            for (const scriptPath of scripts) {
+                const externalModules = extractExternalRequires(scriptPath);
+                const relativeScriptPath = path_1.default.relative(SCRIPTS_DIR, scriptPath);
+                for (const moduleName of externalModules) {
+                    try {
+                        require.resolve(moduleName, { paths: [path_1.default.dirname(scriptPath)] });
+                    }
+                    catch {
+                        if (!unresolved[moduleName])
+                            unresolved[moduleName] = [];
+                        unresolved[moduleName].push(relativeScriptPath);
+                    }
+                }
+            }
+            const unresolvedModules = Object.keys(unresolved);
+            if (unresolvedModules.length === 0) {
+                return {
+                    status: 'passed',
+                    message: `All Node script dependencies resolve (${scripts.length} scripts checked)`,
+                    details: { scriptCount: scripts.length }
+                };
+            }
+            const summary = unresolvedModules
+                .map((moduleName) => `${moduleName} (${unresolved[moduleName].join(', ')})`)
+                .join('; ');
+            return {
+                status: 'warning',
+                message: `Unresolved Node script dependencies: ${summary}`,
+                suggestion: 'Run fraim sync to install user-level runtime dependencies.',
+                command: 'fraim sync',
+                details: { unresolved }
+            };
+        }
+    };
+}
 /**
  * Get all scripts checks
  */
@@ -219,6 +351,7 @@ function getScriptsChecks() {
         checkScriptsDirectoryExists(),
         checkScriptsSynced(),
         checkScriptsExecutable(),
+        checkNodeScriptDependencies(),
         checkPythonAvailability()
     ];
 }

package/dist/src/cli/setup/user-level-sync.js

@@ -69,6 +69,7 @@ const script_sync_utils_1 = require("../utils/script-sync-utils");
  */
 const USER_LEVEL_RUNTIME_DEPS = {
     'node-edge-tts': '*', // used by scripts/author-audio.js
+    'adm-zip': '^0.6.0', // used by scripts/communication/*.js (DOCX review layer) — matches root/packages/* manifests
 };
 /**
  * Ensure the user-level FRAIM directory structure exists.

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

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYNCED_CONTENT_BANNER_MARKER = void 0;
 exports.fetchRegistryFiles = fetchRegistryFiles;
 exports.syncScriptsToUserDir = syncScriptsToUserDir;
+exports.syncDocsToUserDir = syncDocsToUserDir;
 exports.syncFromRemote = syncFromRemote;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
@@ -188,32 +189,51 @@ async function fetchRegistryFiles(remoteUrl, apiKey) {
     return response.data.files || [];
 }
 /**
- * Sync script files to the user-level ~/.fraim/scripts/ directory.
- * Extracted from syncFromRemote so it can run without a project root.
+ * Sync a registry file subset (filtered by `type`) into a machine-level
+ * `~/.fraim/<subdir>/` directory: clean that directory, then write each
+ * matching file. Shared by syncScriptsToUserDir and syncDocsToUserDir so the
+ * clean-then-write and path-safety logic exists in exactly one place.
  */
-async function syncScriptsToUserDir(files) {
-    const scriptFiles = files.filter(f => f.type === 'script');
-    if (scriptFiles.length === 0)
+async function syncTypedFilesToUserDir(files, type, subdir, label) {
+    const matchingFiles = files.filter(f => f.type === type);
+    if (matchingFiles.length === 0)
         return 0;
     const userDir = (0, script_sync_utils_1.getUserFraimDir)();
-    const scriptsDir = (0, path_1.join)(userDir, 'scripts');
-    if (!(0, fs_1.existsSync)(scriptsDir)) {
-        (0, fs_1.mkdirSync)(scriptsDir, { recursive: true });
+    const targetDir = (0, path_1.join)(userDir, subdir);
+    if (!(0, fs_1.existsSync)(targetDir)) {
+        (0, fs_1.mkdirSync)(targetDir, { recursive: true });
     }
-    cleanDirectory(scriptsDir, (candidatePath) => {
-        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(scriptsDir)) {
-            assertPathInsideDirectory(scriptsDir, candidatePath, 'script directory');
+    cleanDirectory(targetDir, (candidatePath) => {
+        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(targetDir)) {
+            assertPathInsideDirectory(targetDir, candidatePath, `${label} directory`);
         }
     });
-    for (const file of scriptFiles) {
-        const { filePath } = resolveUserRegistryFile(scriptsDir, file.path, 'script file');
+    for (const file of matchingFiles) {
+        const { filePath } = resolveUserRegistryFile(targetDir, file.path, `${label} file`);
         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');
     }
-    return scriptFiles.length;
+    return matchingFiles.length;
+}
+/**
+ * Sync script files to the user-level ~/.fraim/scripts/ directory.
+ * Extracted from syncFromRemote so it can run without a project root.
+ */
+async function syncScriptsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'script', 'scripts', 'script');
+}
+/**
+ * Sync docs files to the user-level ~/.fraim/docs/ directory.
+ * Mirrors syncScriptsToUserDir so machine-level docs (e.g. TROUBLESHOOTING.md)
+ * are materialized on disk the same way machine-level scripts are.
+ * Issue #1508: agent guidance promises ~/.fraim/docs/TROUBLESHOOTING.md exists
+ * after sync, but only project-level fraim/docs/ was ever written.
+ */
+async function syncDocsToUserDir(files) {
+    return syncTypedFilesToUserDir(files, 'docs', 'docs', 'docs');
 }
 /**
  * Sync jobs and scripts from remote FRAIM server

package/dist/src/config/persona-capability-bundles.js

@@ -179,8 +179,8 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
     sam: {
         personaKey: 'sam',
         bundleId: 'persona-sam-core',
-        catalogMetadata: buildCatalogMetadata('sam', ['crm-pipeline-review', 'outbound-sales-strategy', 'discovery-coaching']),
-        protectedJobs: ['crm-pipeline-review', 'outbound-sales-strategy', 'discovery-coaching', 'deal-strategy', 'proposal-development', 'account-strategy', 'sales-coaching'],
+        catalogMetadata: buildCatalogMetadata('sam', ['crm-pipeline-review', 'outbound-sales-strategy', 'sales-discovery-preparation']),
+        protectedJobs: ['crm-pipeline-review', 'outbound-sales-strategy', 'sales-discovery-preparation', 'deal-strategy', 'proposal-development', 'account-strategy', 'sales-coaching'],
         protectedAliases: ['sales', 'sales-manager', 'account-manager', 'pipeline'],
         defaultHireMode: 'job',
         lockCopy: 'Hire SAM to unlock full-cycle sales work for this request.'

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

@@ -17,11 +17,16 @@
  * after the existing quality enforcement block.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHASE_START_WARN_PHASES = void 0;
 exports.isSubmitPhase = isSubmitPhase;
 exports.isRetrospectivePhase = isRetrospectivePhase;
 exports.isAddressFeedbackCompletion = isAddressFeedbackCompletion;
 exports.isDelegationGraphPhase = isDelegationGraphPhase;
 exports.validateAddressFeedbackApproval = validateAddressFeedbackApproval;
+exports.validateReviewActionCompleteness = validateReviewActionCompleteness;
+exports.hasPhaseStarted = hasPhaseStarted;
+exports.upsertPhaseStarted = upsertPhaseStarted;
+exports.buildPhaseStartWarning = buildPhaseStartWarning;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
@@ -96,6 +101,123 @@ function validateAddressFeedbackApproval(evidence) {
     }
     return null;
 }
+// ---------------------------------------------------------------------------
+// Issue #1590 — shape enforcement for review-action completeness
+//
+// #916/#1463 (above) validate that a reviewHandoff payload is internally
+// well-formed (an enum'd reviewTarget.type, pull_request <=> empty artifacts,
+// well-shaped artifact_set entries). It does not check whether the claimed
+// pull_request target's reviewActions are actually complete enough to be
+// useful given the repository state it describes — a structurally valid
+// reviewActions array can still leave out the specific provider action the
+// manager needs (issue #1541: a PR handoff shipped only the generic
+// approve/request_changes pair, with no merge action of any kind). This
+// validator is pure: the proxy (src/local-mcp-server/stdio-server.ts) does
+// the I/O (git branch state) and passes plain data in.
+//
+// (Choosing artifact_set vs. pull_request for the review target itself is
+// not mechanized: registry/delivery/submit.md's own Contract rules already
+// state that rule in prose, and the fix for a model missing it is a
+// tighter, more direct instruction plus eval coverage proving compliance,
+// not a second code path re-deriving the same fact from job content.)
+// ---------------------------------------------------------------------------
+/** A composed `deliveryActionId` accepts a bare id or a `<domain>+<id>` suffix (registry/providers/delivery-pr.json). */
+function deliveryActionIdMatches(actions, id) {
+    return actions.some((a) => {
+        const deliveryActionId = a.deliveryActionId;
+        return typeof deliveryActionId === 'string'
+            && (deliveryActionId === id || deliveryActionId.endsWith(`+${id}`));
+    });
+}
+/**
+ * Review-action-completeness.
+ *
+ * Only applies to a `pull_request` reviewTarget with a configured repository
+ * (repo: null means no repository is configured, e.g. a non-repo-backed
+ * job — gate does not apply). A self-consistency check against the proxy's
+ * own locally-observed git branch state (`detectRepoInfo()`), not a live
+ * GitHub/GitLab API call: it does not confirm the PR is actually open on the
+ * provider, only that the claimed pull_request target is backed by the
+ * provider actions local branch state implies it should carry.
+ *
+ * - currentBranch === defaultBranch: requires a `push_default_branch`
+ *   deliveryActionId (bare or composed `<domain>+push_default_branch`).
+ * - Otherwise (feature branch, i.e. an open-PR review claimed): requires
+ *   both `merge_pr` and `merge_pr_work_completion` (bare or composed).
+ */
+function validateReviewActionCompleteness(reviewTarget, reviewActions, repo) {
+    if (!reviewTarget || reviewTarget.type !== 'pull_request')
+        return null;
+    if (!repo)
+        return null;
+    const actions = Array.isArray(reviewActions) ? reviewActions : [];
+    const errors = [];
+    if (repo.currentBranch === repo.defaultBranch) {
+        if (!deliveryActionIdMatches(actions, 'push_default_branch')) {
+            errors.push(`evidence.reviewHandoff.reviewActions must include an approve_push_default_branch action (an ` +
+                `approve_delivery entry whose deliveryActionId is "push_default_branch", or ends with ` +
+                `"+push_default_branch") — the current branch is the default branch ("${repo.defaultBranch}"), so ` +
+                `the manager needs a one-click way to push it.`);
+        }
+    }
+    else {
+        if (!deliveryActionIdMatches(actions, 'merge_pr')) {
+            errors.push(`evidence.reviewHandoff.reviewActions must include an approve_merge_pr action (an approve_delivery ` +
+                `entry whose deliveryActionId is "merge_pr", or ends with "+merge_pr") — an open pull request is ` +
+                `the claimed review target, so the manager needs a one-click way to merge it.`);
+        }
+        if (!deliveryActionIdMatches(actions, 'merge_pr_work_completion')) {
+            errors.push(`evidence.reviewHandoff.reviewActions must include an approve_merge_pr_work_completion action (an ` +
+                `approve_delivery entry whose deliveryActionId is "merge_pr_work_completion", or ends with ` +
+                `"+merge_pr_work_completion") — the manager also needs a one-click way to merge the PR and ` +
+                `complete the issue.`);
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}
+/**
+ * True when `marker` records a "starting" timestamp for `phaseId`. Fails
+ * open (false, never throws) for a missing file (marker: undefined), a
+ * missing key, or a malformed shape — this is a warn-only signal, not a
+ * required artifact.
+ */
+function hasPhaseStarted(marker, phaseId) {
+    if (!marker || typeof marker !== 'object' || Array.isArray(marker))
+        return false;
+    const startedPhases = marker.startedPhases;
+    if (!startedPhases || typeof startedPhases !== 'object' || Array.isArray(startedPhases))
+        return false;
+    const value = startedPhases[phaseId];
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Returns a new marker with `phaseId` upserted to `timestamp`, preserving
+ * every other phase already recorded. Tolerates a missing or malformed
+ * existing marker by starting from an empty `startedPhases`.
+ */
+function upsertPhaseStarted(marker, phaseId, timestamp) {
+    const existing = marker && typeof marker === 'object' && !Array.isArray(marker)
+        ? marker.startedPhases
+        : undefined;
+    const startedPhases = existing && typeof existing === 'object' && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
+    startedPhases[phaseId] = timestamp;
+    return { startedPhases };
+}
+/** The single phase this gate covers today (RFC: scoped, not universal — see Risk Assessment). */
+exports.PHASE_START_WARN_PHASES = ['address-feedback'];
+/**
+ * Builds the warning prepended to an otherwise-valid address-feedback
+ * response when this run never called seekMentoring(status: "starting") for
+ * that phase. Warn-only, never a rejection: a lost marker (disk cleanup, a
+ * first-ever run before this shipped) must not strand a legitimate resume.
+ */
+function buildPhaseStartWarning(phaseId) {
+    return (`⚠️ **Phase-start notice**: this run did not call \`seekMentoring({ currentPhase: "${phaseId}", status: "starting" })\` ` +
+        `before this call. If you resumed after context compaction, re-read \`registry/delivery/address-feedback.md\` now — ` +
+        `Step 4 (write the standalone feedback file) is easy to skip when acting from remembered context.\n\n`);
+}
 function isAbsoluteHttpUrl(url) {
     if (typeof url !== 'string' || !url)
         return false;
@@ -354,9 +476,19 @@ function validateHandoffContracts(args) {
         return ['nextJobRecommendations was found in findings but must be nested under evidence. Move nextJobRecommendations out of findings and into the top-level evidence object.'];
     }
     if (isSubmitPhase(phase, status, args.phases)) {
-        const errors = validateReviewHandoff(evidence.reviewHandoff);
-        if (errors)
-            return errors;
+        const structuralErrors = validateReviewHandoff(evidence.reviewHandoff);
+        if (structuralErrors)
+            return structuralErrors;
+        // Issue #1590: a structurally valid reviewHandoff can still leave out
+        // the specific provider action the claimed repository state requires
+        // (issue #1541). Shares reviewHandoff's FRAIM_HANDOFF_ENFORCEMENT_MODE
+        // escape hatch (see stdio-server.ts). No-ops when repo is absent.
+        const reviewHandoff = evidence.reviewHandoff;
+        const reviewTarget = reviewHandoff?.reviewTarget;
+        const reviewActions = reviewHandoff?.reviewActions;
+        const actionCompletenessErrors = validateReviewActionCompleteness(reviewTarget, reviewActions, args.repo ?? null);
+        if (actionCompletenessErrors)
+            return actionCompletenessErrors;
     }
     if (isRetrospectivePhase(phase, status)) {
         const errors = validateNextJobRecommendations(evidence.nextJobRecommendations);

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

@@ -1057,6 +1057,58 @@ class FraimLocalMCPServer {
             return null;
         return (0, path_1.join)(homeDir, '.fraim', 'cache', 'registry', 'providers', filename);
     }
+    /**
+     * Issue #1590, Gate 4 — path to the per-run phase-start marker.
+     * ~/.fraim/run-state/{jobId}.json, keyed by the jobId seekMentoring already
+     * carries on every call, so no new identifier or collision risk across the
+     * user's concurrent multi-issue fleet.
+     */
+    getRunStateMarkerPath(jobId) {
+        const homeDir = this.getHomeDir();
+        if (!homeDir)
+            return null;
+        return (0, path_1.join)(homeDir, '.fraim', 'run-state', `${jobId}.json`);
+    }
+    /** Reads and parses the run-state marker, tolerating a missing/corrupt file (warn-only signal, never throws). */
+    readRunStateMarker(jobId) {
+        try {
+            const markerPath = this.getRunStateMarkerPath(jobId);
+            if (!markerPath || !(0, fs_1.existsSync)(markerPath))
+                return undefined;
+            return JSON.parse((0, fs_1.readFileSync)(markerPath, 'utf8'));
+        }
+        catch (error) {
+            this.log(`⚠️ [phase-start] failed to read run-state marker for jobId=${jobId}: ${error.message}`);
+            return undefined;
+        }
+    }
+    /** Upserts one phase's started timestamp into the run-state marker. Best-effort: a write failure only degrades Gate 4 to always-warn for this run. */
+    writeRunStateMarker(jobId, phaseId, timestamp) {
+        try {
+            const markerPath = this.getRunStateMarkerPath(jobId);
+            if (!markerPath)
+                return;
+            const existing = this.readRunStateMarker(jobId);
+            const updated = (0, handoff_contracts_1.upsertPhaseStarted)(existing, phaseId, timestamp);
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(markerPath), { recursive: true });
+            (0, fs_1.writeFileSync)(markerPath, JSON.stringify(updated), 'utf8');
+        }
+        catch (error) {
+            this.log(`⚠️ [phase-start] failed to write run-state marker for jobId=${jobId}: ${error.message}`);
+        }
+    }
+    /** Deletes the run-state marker at job completion so the directory does not grow unbounded across a user's history of completed jobs. */
+    deleteRunStateMarker(jobId) {
+        try {
+            const markerPath = this.getRunStateMarkerPath(jobId);
+            if (markerPath && (0, fs_1.existsSync)(markerPath)) {
+                (0, fs_1.unlinkSync)(markerPath);
+            }
+        }
+        catch (error) {
+            this.log(`⚠️ [phase-start] failed to delete run-state marker for jobId=${jobId}: ${error.message}`);
+        }
+    }
     readCachedTemplateFile(filename) {
         try {
             const cachePath = this.getProviderCachePath(filename);
@@ -2238,6 +2290,29 @@ class FraimLocalMCPServer {
                         nextPhase: tutoringResponse.nextPhase,
                         jobId: args.jobId || requestSessionId // Use jobId from args, fallback to sessionId
                     });
+                    // Phase-start marker (Issue #1590 — warn-only).
+                    //
+                    // Detects a resumed address-feedback turn that never called
+                    // seekMentoring(status: "starting") for this run: the mentoring
+                    // response cache above is in-memory, keyed by request.id, and does
+                    // not survive the process restart a Hub resume performs, so a
+                    // durable per-jobId marker on disk is the only signal that
+                    // survives it. Scoped to address-feedback only (PHASE_START_WARN_PHASES);
+                    // never rejects — a lost marker (disk cleanup, first-ever run
+                    // before this shipped) must not strand a legitimate resume.
+                    let phaseStartWarning = '';
+                    if (args.jobId && handoff_contracts_1.PHASE_START_WARN_PHASES.includes(args.currentPhase)) {
+                        if (args.status === 'starting') {
+                            this.writeRunStateMarker(args.jobId, args.currentPhase, new Date().toISOString());
+                        }
+                        else if (args.status === 'complete' || args.status === 'failure') {
+                            const marker = this.readRunStateMarker(args.jobId);
+                            if (!(0, handoff_contracts_1.hasPhaseStarted)(marker, args.currentPhase)) {
+                                this.log(`⚠️ [phase-start] ${args.currentPhase} entered without a starting call this run: jobId=${args.jobId}`);
+                                phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase);
+                            }
+                        }
+                    }
                     // Quality enforcement (Issue #251).
                     //
                     // The local proxy owns seekMentoring for personalized-job support.
@@ -2293,6 +2368,15 @@ class FraimLocalMCPServer {
                     // The Hub cannot render review bars, next-job chips, or the
                     // delegation board when these fields are absent.
                     const handoffPhaseMap = await mentor.getJobPhaseMap(args.jobName);
+                    // Issue #1590: locally-observed git branch state for the
+                    // review-action-completeness check. A repository is "configured"
+                    // for this purpose only when a defaultBranch reference point
+                    // exists; without it the check cannot classify default-vs-feature
+                    // branch, so it must not apply (repo: null).
+                    const handoffRepoInfo = this.detectRepoInfo();
+                    const handoffRepoState = handoffRepoInfo?.defaultBranch
+                        ? { currentBranch: handoffRepoInfo.branch || '', defaultBranch: handoffRepoInfo.defaultBranch }
+                        : null;
                     const handoffErrors = (0, handoff_contracts_1.validateHandoffContracts)({
                         jobName: args.jobName,
                         currentPhase: args.currentPhase,
@@ -2300,6 +2384,7 @@ class FraimLocalMCPServer {
                         evidence: args.evidence,
                         findings: args.findings,
                         phases: handoffPhaseMap,
+                        repo: handoffRepoState,
                     });
                     handoffErrors.push(...await this.validateNextJobRecommendationJobIds(args.evidence?.nextJobRecommendations, mentor));
                     if (handoffErrors.length > 0) {
@@ -2367,7 +2452,7 @@ class FraimLocalMCPServer {
                         const rejection = (0, test_evidence_contract_1.buildTestEvidenceRejectionMessage)(args.currentPhase, testEvidenceErrors);
                         return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
                     }
-                    return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
+                    return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, phaseStartWarning + tutoringResponse.message);
                 }
                 catch (error) {
                     this.log(`⚠️ Local seekMentoring failed: ${error.message}. Falling back to remote.`);
@@ -2763,6 +2848,10 @@ class FraimLocalMCPServer {
                     catch (err) {
                         this.log(`📊 ⚠️ Job complete event failed (non-blocking): ${err.message}`);
                     }
+                    // Issue #1590, Gate 4: clean up the per-run phase-start marker so
+                    // ~/.fraim/run-state/ does not grow unbounded across a user's
+                    // history of completed jobs.
+                    this.deleteRunStateMarker(args.jobId);
                 }
             }
             catch (error) {

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

@@ -45,6 +45,7 @@ const semver = __importStar(require("semver"));
 const compat_1 = require("../config/compat");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const quality_evidence_1 = require("../core/quality-evidence");
+const handoff_contracts_1 = require("../core/handoff-contracts");
 const feature_flags_1 = require("../config/feature-flags");
 const persona_entitlement_service_1 = require("./persona-entitlement-service");
 exports.DEFAULT_LAUNCH_PHRASE_MAPPINGS = {
@@ -706,6 +707,47 @@ class McpService {
             evidence: args.evidence,
             findings: args.findings
         });
+        // Handoff contract enforcement (Issue #916/#1157/#1276) fall-through
+        // safety net, matching the quality-enforcement note just below.
+        //
+        // The local MCP proxy (stdio-server.ts) is the primary enforcement
+        // point for reviewHandoff/nextJobRecommendations/delegationLedger/
+        // approved, but that entire check lives inside one try/catch around
+        // the local seekMentoring handler: any exception there falls through
+        // to this remote path with no re-check, and any client that calls
+        // this endpoint directly (bypassing the local proxy) never goes
+        // through the local check at all (issue #1590 investigation). Only
+        // the structural/shape gates run here, not the git-branch-state Gate
+        // 2 check — this service has no local repository to inspect, and
+        // that gate already no-ops when `repo` is absent.
+        const handoffPhaseMap = await this.aiMentor.getJobPhaseMap(args.jobName);
+        const handoffErrors = (0, handoff_contracts_1.validateHandoffContracts)({
+            jobName: args.jobName,
+            currentPhase: args.currentPhase,
+            status: args.status,
+            evidence: args.evidence,
+            findings: args.findings,
+            phases: handoffPhaseMap
+        });
+        if (handoffErrors.length > 0) {
+            const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
+                : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'
+                    : handoffErrors[0].includes('evidence.approved') ? 'approved'
+                        : 'delegationLedger';
+            // Same content-scoped applicability as the local proxy: a job whose
+            // submission phase never promises evidence.reviewHandoff is not
+            // gated on it here either.
+            const reviewHandoffApplies = missingField !== 'reviewHandoff'
+                || await this.aiMentor.phasePromisesReviewHandoff(args.jobName, args.currentPhase);
+            const enforcementMode = missingField === 'reviewHandoff'
+                ? (process.env.FRAIM_HANDOFF_ENFORCEMENT_MODE || 'enforce')
+                : 'enforce';
+            if (reviewHandoffApplies && enforcementMode === 'enforce') {
+                return {
+                    content: [{ type: 'text', text: (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors) }]
+                };
+            }
+        }
         // Quality enforcement (Issue #251): quality-producing jobs MUST emit
         // a valid `evidence.quality` object on their final completion call.
         //

package/package.json

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