fraim 2.0.227 → 2.0.228

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

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Handoff Contract Validation (Issue #916)
+ *
+ * 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.nextJobRecommendations  (retrospective phase completion)
+ *   - evidence.delegationLedger  (create-delegation-graph phase)
+ *
+ * Lives in src/core so both the local MCP proxy and evals can import the same
+ * contract without cross-layer dependencies — same pattern as quality-evidence.ts.
+ *
+ * Primary call site: src/local-mcp-server/stdio-server.ts seekMentoring handler,
+ * after the existing quality enforcement block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSubmitPhase = isSubmitPhase;
+exports.isRetrospectivePhase = isRetrospectivePhase;
+exports.isDelegationGraphPhase = isDelegationGraphPhase;
+exports.validateReviewHandoff = validateReviewHandoff;
+exports.validateNextJobRecommendations = validateNextJobRecommendations;
+exports.validateDelegationLedger = validateDelegationLedger;
+exports.validateHandoffContracts = validateHandoffContracts;
+exports.buildHandoffRejectionMessage = buildHandoffRejectionMessage;
+// ---------------------------------------------------------------------------
+// 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.
+ */
+function isSubmitPhase(currentPhase, status) {
+    return status === 'awaiting_mentor';
+}
+/**
+ * Returns true when a seekMentoring call is a retrospective completion.
+ * Retrospective jobs emit nextJobRecommendations at this boundary.
+ */
+function isRetrospectivePhase(currentPhase, status) {
+    return currentPhase === 'retrospective' && status === 'complete';
+}
+/**
+ * Returns true when a seekMentoring call is the delegation graph phase.
+ * This matches the existing Hub test fixture for the delegation board.
+ */
+function isDelegationGraphPhase(currentPhase) {
+    return currentPhase === 'create-delegation-graph';
+}
+// ---------------------------------------------------------------------------
+// Individual validators
+// ---------------------------------------------------------------------------
+/**
+ * Validates evidence.reviewHandoff. Returns null if valid, or an array of
+ * human-readable error strings describing what is wrong.
+ *
+ * Required minimum shape:
+ * {
+ *   reviewRequired: boolean,
+ *   reviewTarget: object | null,
+ *   artifacts: array,
+ * }
+ */
+function validateReviewHandoff(value) {
+    if (value === undefined || value === null) {
+        return ['evidence.reviewHandoff is missing'];
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        return ['evidence.reviewHandoff must be an object'];
+    }
+    const obj = value;
+    const errors = [];
+    if (typeof obj.reviewRequired !== 'boolean') {
+        errors.push(`evidence.reviewHandoff.reviewRequired must be a boolean (got ${obj.reviewRequired === undefined ? 'missing' : typeof obj.reviewRequired})`);
+    }
+    if (obj.reviewRequired === true) {
+        if (!Array.isArray(obj.reviewActions) || obj.reviewActions.length === 0) {
+            errors.push('evidence.reviewHandoff.reviewActions must be a non-empty array when reviewRequired is true');
+        }
+        else {
+            const actions = obj.reviewActions;
+            const hasApprove = actions.some((a) => a.kind === 'approve');
+            const hasRequestChanges = actions.some((a) => a.kind === 'request_changes');
+            if (!hasApprove) {
+                errors.push('evidence.reviewHandoff.reviewActions must include an entry with kind: "approve"');
+            }
+            if (!hasRequestChanges) {
+                errors.push('evidence.reviewHandoff.reviewActions must include an entry with kind: "request_changes"');
+            }
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}
+/**
+ * Validates evidence.nextJobRecommendations. Returns null if valid, or an
+ * array of error strings.
+ *
+ * Required minimum shape: an array (may be empty) of entries, each with:
+ *   { jobId: string, label: string, reason?: string, contextSummary?: string }
+ */
+function validateNextJobRecommendations(value) {
+    if (value === undefined || value === null) {
+        return ['evidence.nextJobRecommendations is missing'];
+    }
+    if (!Array.isArray(value)) {
+        return ['evidence.nextJobRecommendations must be an array'];
+    }
+    const errors = [];
+    value.forEach((entry, i) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            errors.push(`evidence.nextJobRecommendations[${i}] must be an object`);
+            return;
+        }
+        const rec = entry;
+        if (typeof rec.jobId !== 'string' || !rec.jobId.trim()) {
+            errors.push(`evidence.nextJobRecommendations[${i}].jobId must be a non-empty string`);
+        }
+        if (typeof rec.label !== 'string' || !rec.label.trim()) {
+            errors.push(`evidence.nextJobRecommendations[${i}].label must be a non-empty string`);
+        }
+    });
+    return errors.length > 0 ? errors : null;
+}
+/**
+ * Validates evidence.delegationLedger. Returns null if valid, or an array
+ * of error strings.
+ *
+ * Required minimum shape:
+ * {
+ *   delegationRequired: boolean,
+ *   tasks: array,
+ * }
+ */
+function validateDelegationLedger(value) {
+    if (value === undefined || value === null) {
+        return ['evidence.delegationLedger is missing'];
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        return ['evidence.delegationLedger must be an object'];
+    }
+    const obj = value;
+    const errors = [];
+    if (typeof obj.delegationRequired !== 'boolean') {
+        errors.push(`evidence.delegationLedger.delegationRequired must be a boolean (got ${obj.delegationRequired === undefined ? 'missing' : typeof obj.delegationRequired})`);
+    }
+    if (!('tasks' in obj)) {
+        errors.push('evidence.delegationLedger.tasks is missing');
+    }
+    else if (!Array.isArray(obj.tasks)) {
+        errors.push('evidence.delegationLedger.tasks must be an array');
+    }
+    return errors.length > 0 ? errors : null;
+}
+// ---------------------------------------------------------------------------
+// Orchestrator: called from the seekMentoring handler
+// ---------------------------------------------------------------------------
+/**
+ * Validates all handoff contracts that apply to the given seekMentoring call.
+ * Returns an empty array when no contract is violated; otherwise returns the
+ * error strings from whichever applicable validator(s) failed.
+ */
+function validateHandoffContracts(args) {
+    const phase = args.currentPhase ?? '';
+    const status = args.status ?? '';
+    const evidence = args.evidence ?? {};
+    if (isSubmitPhase(phase, status)) {
+        const errors = validateReviewHandoff(evidence.reviewHandoff);
+        if (errors)
+            return errors;
+    }
+    if (isRetrospectivePhase(phase, status)) {
+        const errors = validateNextJobRecommendations(evidence.nextJobRecommendations);
+        if (errors)
+            return errors;
+    }
+    if (isDelegationGraphPhase(phase)) {
+        const errors = validateDelegationLedger(evidence.delegationLedger);
+        if (errors)
+            return errors;
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Rejection message builder
+// ---------------------------------------------------------------------------
+const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
+evidence: {
+  reviewHandoff: {
+    reviewRequired: true,
+    reviewTarget: { kind: "pull_request", url: "<PR URL>" } | { kind: "artifact_set", files: ["<path>"] } | null,
+    artifacts: [{ label: "<label>", path: "<path>", kind: "<kind>" }],
+    summary: "<optional summary>",
+    reviewActions: [
+      { kind: "approve", label: "Approve" },
+      { kind: "request_changes", label: "Request Changes" }
+    ]
+  }
+}
+\`\`\``;
+const NEXT_JOB_RECOMMENDATIONS_SCHEMA = `\`\`\`javascript
+evidence: {
+  nextJobRecommendations: [
+    {
+      jobId: "<job-slug>",
+      label: "<human-readable label>",
+      reason: "<optional: why this job is recommended>",
+      contextSummary: "<optional: one sentence context for the next agent>"
+    }
+    // 0–3 entries; an empty array [] is valid
+  ]
+}
+\`\`\``;
+const DELEGATION_LEDGER_SCHEMA = `\`\`\`javascript
+evidence: {
+  delegationLedger: {
+    delegationRequired: true,
+    objective: "<optional objective string>",
+    tasks: [
+      { jobId: "<job-slug>", personaKey: "<persona key or null>", briefing: "<optional briefing>" }
+    ]
+  }
+}
+\`\`\``;
+const FIELD_SCHEMAS = {
+    reviewHandoff: REVIEW_HANDOFF_SCHEMA,
+    nextJobRecommendations: NEXT_JOB_RECOMMENDATIONS_SCHEMA,
+    delegationLedger: DELEGATION_LEDGER_SCHEMA,
+};
+/**
+ * Builds the rejection message returned to the agent when a handoff contract
+ * is violated. The message names the missing field and provides the required
+ * minimum schema so the agent can fix everything in one retry.
+ */
+function buildHandoffRejectionMessage(currentPhase, field, errors) {
+    const errorBullets = errors.map((e) => `- ${e}`).join('\n');
+    const schemaHint = FIELD_SCHEMAS[field] ?? '';
+    return [
+        `❌ **seekMentoring rejected** at phase \`${currentPhase}\`.`,
+        '',
+        `This call requires \`evidence.${field}\` to be present and valid so the Hub can render the correct management surface. The following problems were found:`,
+        '',
+        errorBullets,
+        '',
+        `Required minimum schema for \`evidence.${field}\`:`,
+        '',
+        schemaHint,
+        '',
+        `The job is **not** marked complete. Add the \`evidence.${field}\` object and resubmit this phase.`,
+    ].join('\n');
+}

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

@@ -63,6 +63,7 @@ const object_utils_1 = require("../core/utils/object-utils");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 const ai_mentor_1 = require("../core/ai-mentor");
 const quality_evidence_1 = require("../core/quality-evidence");
+const handoff_contracts_1 = require("../core/handoff-contracts");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
 const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
@@ -2151,6 +2152,26 @@ class FraimLocalMCPServer {
                             this.log(`⚠️ Quality score emission failed: ${err?.message || err}`);
                         });
                     }
+                    // Handoff contract enforcement (Issue #916).
+                    //
+                    // The proxy is the primary enforcement point for reviewHandoff,
+                    // nextJobRecommendations, and delegationLedger evidence fields.
+                    // The Hub cannot render review bars, next-job chips, or the
+                    // delegation board when these fields are absent.
+                    const handoffErrors = (0, handoff_contracts_1.validateHandoffContracts)({
+                        jobName: args.jobName,
+                        currentPhase: args.currentPhase,
+                        status: args.status,
+                        evidence: args.evidence,
+                    });
+                    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);
+                    }
                     return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
                 }
                 catch (error) {

package/package.json

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