fraim 2.0.280 → 2.0.281

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

@@ -230,6 +230,41 @@ class AIMentor {
             status
         };
     }
+    /**
+     * The job's declared phase graph (onSuccess/onFailure edges), or undefined
+     * for a simple/bootstrap-style job with no phases. Lets a caller derive
+     * graph facts (e.g. "which phase is this job's submission phase", issue
+     * #1276) without hardcoding phase names or duplicating job loading.
+     */
+    async getJobPhaseMap(jobName) {
+        const job = await this.getOrLoadJob(jobName);
+        return job?.metadata.phases;
+    }
+    /**
+     * True when a job's phase, with its includes resolved, itself instructs
+     * the agent to emit `evidence.reviewHandoff` (issue #1318 follow-up).
+     *
+     * The #1276 reviewHandoff gate fires for any job's graph-derived
+     * submission phase, but not every job family promises reviewHandoff at
+     * that phase — jobs built on `rich-review-artifact-contract.md`,
+     * `author-docx.md`, or `reporting-standards.md` (analysis reports, DOCX
+     * deliverables, operational setup jobs) use a different, legitimate
+     * completion contract and never mention the field, even resolved. Gating
+     * those unconditionally would reject a call the job's own instructions
+     * never told the agent to satisfy. This check reads the phase's actual
+     * resolved instructions rather than a hardcoded skill/job allowlist, so
+     * a new reviewHandoff-emitting skill (or a new non-reviewHandoff one)
+     * needs no update here — same "derive, don't hardcode" reasoning as
+     * `derivePredecessorPhase`.
+     */
+    async phasePromisesReviewHandoff(jobName, phaseId) {
+        const job = await this.getOrLoadJob(jobName);
+        const raw = job?.phases.get(phaseId);
+        if (!raw)
+            return false;
+        const resolved = await this.resolveIncludes(raw, job.path);
+        return resolved.includes('evidence.reviewHandoff');
+    }
     async getJobOverview(jobName) {
         const job = await this.getOrLoadJob(jobName);
         if (!job)

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

@@ -5,7 +5,8 @@
  * Pure helpers for validating the three evidence fields that FRAIM jobs must
  * emit on key seekMentoring calls so the Hub can render its review surfaces:
  *
- *   - evidence.reviewHandoff   (submit phase, status === "awaiting_mentor")
+ *   - evidence.reviewHandoff   (job's submission phase, status === "complete";
+ *                               see isSubmitPhase for how that phase is found)
  *   - evidence.nextJobRecommendations  (retrospective phase completion)
  *   - evidence.delegationLedger  (create-delegation-graph phase)
  *
@@ -26,17 +27,36 @@ exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
 exports.validateHandoffContracts = validateHandoffContracts;
 exports.buildHandoffRejectionMessage = buildHandoffRejectionMessage;
+const resolve_phase_edge_1 = require("./resolve-phase-edge");
 // ---------------------------------------------------------------------------
 // Phase detection
 // ---------------------------------------------------------------------------
 /**
  * Returns true when a seekMentoring call is a submit-phase handoff requiring
- * a reviewHandoff evidence field. The canonical signal is status === "awaiting_mentor"
- * — set only by submit-phase jobs requesting a review gate — rather than a
- * hardcoded phase name list, which is fragile for personalized jobs.
+ * a reviewHandoff evidence field.
+ *
+ * Two triggers, either is sufficient:
+ *  - `status === "awaiting_mentor"`: the original #916 signal. No published
+ *    `seekMentoring` status permits this value today (confirmed by
+ *    `spike/1157-approval-gate/s5-dead-submit-gate.js`), so this branch is
+ *    provably unreachable in production — kept so a future status value, or a
+ *    job that still emits it, is not silently unenforced.
+ *  - `status === "complete"` at the job's own submission phase, derived from
+ *    its real phase graph (issue #1276, gating-only rebuild of #1157 Change
+ *    1): the unique phase whose `onSuccess` targets `address-feedback`. This
+ *    is the trigger that actually fires. No hardcoded phase-name list — a
+ *    personalized job with a differently-named submission phase is still
+ *    caught, and a job whose graph doesn't uniquely name one (`phases`
+ *    omitted, or the derivation is ambiguous) is not gated at all rather than
+ *    guessed at.
  */
-function isSubmitPhase(currentPhase, status) {
-    return status === 'awaiting_mentor';
+function isSubmitPhase(currentPhase, status, phases) {
+    if (status === 'awaiting_mentor')
+        return true;
+    if (status === 'complete' && phases) {
+        return (0, resolve_phase_edge_1.derivePredecessorPhase)(phases, resolve_phase_edge_1.FEEDBACK_PHASE_ID) === currentPhase;
+    }
+    return false;
 }
 /**
  * Returns true when a seekMentoring call is a retrospective completion.
@@ -221,7 +241,14 @@ function validateHandoffContracts(args) {
     const phase = args.currentPhase ?? '';
     const status = args.status ?? '';
     const evidence = args.evidence ?? {};
-    if (isSubmitPhase(phase, status)) {
+    const findings = args.findings ?? {};
+    if (isSubmitPhase(phase, status, args.phases) && !evidence.reviewHandoff && findings.reviewHandoff) {
+        return ['reviewHandoff was found in findings but must be nested under evidence. Move reviewHandoff out of findings and into the top-level evidence object.'];
+    }
+    if (isRetrospectivePhase(phase, status) && !evidence.nextJobRecommendations && findings.nextJobRecommendations) {
+        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;

package/dist/src/core/resolve-phase-edge.js

@@ -15,9 +15,11 @@
  * change inert for every job that authors no map.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_PHASE_ID = void 0;
 exports.resolvePhaseEdge = resolvePhaseEdge;
 exports.resolveDiscriminant = resolveDiscriminant;
 exports.discriminantKeys = discriminantKeys;
+exports.derivePredecessorPhase = derivePredecessorPhase;
 /** The default discriminant, and the mandatory key on every authored map. */
 const DEFAULT_DISCRIMINANT = 'default';
 /**
@@ -73,3 +75,34 @@ function discriminantKeys(edge) {
         return [];
     return Object.keys(edge).filter((key) => key !== DEFAULT_DISCRIMINANT);
 }
+/** The framework's one review/decision phase; every reviewable job routes into it. */
+exports.FEEDBACK_PHASE_ID = 'address-feedback';
+/**
+ * Finds the unique phase in a job's phase map whose `onSuccess` edge can
+ * resolve to `targetPhaseId` for some discriminant (including `default`).
+ *
+ * Gating-only rebuild of #1157 Change 1 ("graph-derived phase identity"),
+ * scoped per #1276: that change also added routing behavior and was reverted
+ * before merge because the two were bundled. Only the lookup survives here —
+ * it answers "which phase is this job's submission phase" without changing
+ * how any phase transition resolves. No hardcoded phase-name list: the
+ * derivation reads whatever the job's own graph declares, so it is correct
+ * for every current and future job without per-job edits.
+ *
+ * Returns `null` when zero or multiple phases match, so a caller can fail
+ * safe (treat as "unknown") rather than guess at an ambiguous graph.
+ */
+function derivePredecessorPhase(phases, targetPhaseId) {
+    const predecessors = [];
+    for (const [phaseId, edges] of Object.entries(phases ?? {})) {
+        if (phaseId === targetPhaseId || !edges)
+            continue;
+        const edge = edges.onSuccess;
+        const targets = typeof edge === 'string'
+            ? [edge]
+            : (edge && typeof edge === 'object' ? Object.values(edge) : []);
+        if (targets.includes(targetPhaseId))
+            predecessors.push(phaseId);
+    }
+    return predecessors.length === 1 ? predecessors[0] : null;
+}

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

@@ -2209,19 +2209,58 @@ class FraimLocalMCPServer {
                     // nextJobRecommendations, and delegationLedger evidence fields.
                     // 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);
                     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'
-                                : 'delegationLedger';
-                        this.log(`⚠️ Handoff contract enforcement rejected seekMentoring for ${args.jobName}:${args.currentPhase}: ${handoffErrors.join('; ')}`);
-                        const rejection = (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors);
-                        return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
+                                : handoffErrors[0].includes('evidence.approved') ? 'approved'
+                                    : 'delegationLedger';
+                        // Content-scoped applicability (issue #1318 follow-up on #1276): not every
+                        // job's submission phase promises evidence.reviewHandoff. Jobs built on
+                        // rich-review-artifact-contract.md, author-docx.md, or reporting-standards.md
+                        // (analysis reports, DOCX deliverables, operational setup jobs) use a
+                        // different, legitimate completion contract and never instruct the field.
+                        // Enforcing the gate on them would reject a call their own phase text never
+                        // told the agent to satisfy — a genuine stuck-agent risk, not a hypothetical
+                        // one (grep-verified against the registry: ~16 of 183 reviewable jobs). This
+                        // is not a violation at all when the phase never promised the field, so it is
+                        // skipped entirely rather than logged. Escape hatch for the promised case:
+                        // FRAIM_HANDOFF_ENFORCEMENT_MODE=off disables rejection (still logs);
+                        // =warn logs without rejecting; default is unconditional rejection, matching
+                        // how the other three handoff contracts already behave.
+                        const isReviewHandoffField = missingField === 'reviewHandoff';
+                        const reviewHandoffApplies = !isReviewHandoffField
+                            || await mentor.phasePromisesReviewHandoff(args.jobName, args.currentPhase);
+                        // Escape hatch scoped to reviewHandoff only: the other three contracts
+                        // (nextJobRecommendations, delegationLedger, approved) have shipped
+                        // unconditional, uncapped enforcement since #916/#1157 with no reported
+                        // issue, so they keep that behavior — FRAIM_HANDOFF_ENFORCEMENT_MODE never
+                        // relaxes them.
+                        const enforcementMode = isReviewHandoffField
+                            ? (process.env.FRAIM_HANDOFF_ENFORCEMENT_MODE || 'enforce')
+                            : 'enforce';
+                        if (!reviewHandoffApplies) {
+                            // Not gated: this job's submission phase never promised reviewHandoff.
+                        }
+                        else if (enforcementMode === 'off') {
+                            this.log(`⚠️ [reviewHandoff enforcement: off] seekMentoring for ${args.jobName}:${args.currentPhase} would be rejected: ${handoffErrors.join('; ')}`);
+                        }
+                        else if (enforcementMode === 'warn') {
+                            this.log(`⚠️ [reviewHandoff enforcement: warn-only] seekMentoring for ${args.jobName}:${args.currentPhase} would be rejected: ${handoffErrors.join('; ')}`);
+                        }
+                        else {
+                            this.log(`⚠️ Handoff contract enforcement rejected seekMentoring for ${args.jobName}:${args.currentPhase}: ${handoffErrors.join('; ')}`);
+                            const rejection = (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors);
+                            return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
+                        }
                     }
                     return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
                 }

package/package.json

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