fraim 2.0.306 → 2.0.308

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.306",
+  "version": "2.0.308",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {