fraim-hub 2.0.339 → 2.0.340

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

@@ -0,0 +1,617 @@
+"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   (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)
+ *
+ * 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.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.reviewHandoffNormalizationError = reviewHandoffNormalizationError;
+exports.validateReviewHandoff = validateReviewHandoff;
+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.
+ *
+ * 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, 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.
+ * Retrospective jobs emit nextJobRecommendations at this boundary.
+ */
+function isRetrospectivePhase(currentPhase, status) {
+    return currentPhase === 'retrospective' && status === 'complete';
+}
+/**
+ * Returns true when a seekMentoring call is address-feedback completing.
+ * Completing address-feedback requires manager approval (evidence.approved: true).
+ */
+function isAddressFeedbackCompletion(currentPhase, status) {
+    return currentPhase === 'address-feedback' && 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 that evidence.approved is true for address-feedback completion.
+ * Returns null if valid, or an array of error strings.
+ */
+function validateAddressFeedbackApproval(evidence) {
+    if (evidence.approved !== true) {
+        return [
+            `evidence.approved must be true when completing address-feedback. ` +
+                `Set evidence.approved: true only after the manager has explicitly approved the work. ` +
+                `If the manager has not yet approved, set status: "failure" to re-enter the review loop.`,
+        ];
+    }
+    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;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function validateReviewArtifactEntry(artifact, index) {
+    const errors = [];
+    const label = `evidence.reviewHandoff.artifacts[${index}]`;
+    if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+        errors.push(`${label} must be an object`);
+        return errors;
+    }
+    const entry = artifact;
+    if ('kind' in entry && !('type' in entry)) {
+        errors.push(`${label} uses kind but must use type — use type, not kind for artifact type (e.g. "markdown", "docx", "source_file")`);
+    }
+    else if (!entry.type || typeof entry.type !== 'string' || !entry.type.trim()) {
+        errors.push(`${label}.type must be a non-empty string (e.g. "markdown", "docx", "source_file")`);
+    }
+    if (!entry.label || typeof entry.label !== 'string' || !entry.label.trim()) {
+        errors.push(`${label}.label must be a non-empty string`);
+    }
+    if ('url' in entry) {
+        errors.push(`${label} must not include url — artifact_set artifacts are local files; use path`);
+    }
+    if (!entry.path || typeof entry.path !== 'string' || !entry.path.trim()) {
+        errors.push(`${label}.path must be a non-empty local path`);
+    }
+    return errors;
+}
+/**
+ * Reports payloads the Hub cannot normalize, including artifact_set entries it
+ * would silently drop. This deliberately preserves the Hub's legacy defaults;
+ * it does not impose the stronger, phase-dependent submission contract.
+ */
+function reviewHandoffNormalizationError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return 'reviewHandoff must be an object';
+    }
+    const handoff = value;
+    if (typeof handoff.reviewRequired !== 'boolean') {
+        return 'reviewHandoff.reviewRequired must be a boolean';
+    }
+    // This is renderability, not the stronger submission-phase contract below.
+    // In particular legacy handoffs need not supply actions or an artifacts array.
+    if (!handoff.reviewRequired)
+        return null;
+    const target = handoff.reviewTarget;
+    const targetType = typeof target?.type === 'string' ? target.type.trim() : '';
+    if (targetType !== 'pull_request' && targetType !== 'artifact_set') {
+        return 'reviewHandoff.reviewTarget.type must be pull_request or artifact_set';
+    }
+    if (targetType === 'pull_request' && !isAbsoluteHttpUrl(target?.url)) {
+        return 'reviewHandoff.reviewTarget.url must be an absolute http or https URL';
+    }
+    // Match the host parser's object-artifact selection and Hub's path/URL
+    // normalization. A missing label/type is filled in by the Hub, not rejected.
+    const artifacts = Array.isArray(handoff.artifacts)
+        ? handoff.artifacts.filter((artifact) => artifact && typeof artifact === 'object')
+        : [];
+    for (const [index, artifact] of artifacts.entries()) {
+        const hasPath = typeof artifact.path === 'string' && artifact.path.trim().length > 0;
+        const hasUrl = isAbsoluteHttpUrl(artifact.url);
+        if (targetType === 'pull_request') {
+            if (hasPath || hasUrl)
+                return 'reviewHandoff.artifacts must be empty for a pull_request target';
+        }
+        else if (!hasPath || hasUrl) {
+            return `reviewHandoff.artifacts[${index}] cannot be applied: an artifact_set requires a file path without an http or https URL`;
+        }
+    }
+    return null;
+}
+/** Validate the complete submission contract, including required actions. */
+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})`);
+    }
+    // artifacts must always be present and be an array
+    if (!('artifacts' in obj) || !Array.isArray(obj.artifacts)) {
+        errors.push('evidence.reviewHandoff.artifacts must be an array');
+    }
+    if (obj.reviewRequired === true) {
+        const target = obj.reviewTarget;
+        if (target === undefined || target === null) {
+            errors.push('evidence.reviewHandoff.reviewTarget must be a non-null object with type equal to "pull_request" or "artifact_set" when reviewRequired is true');
+        }
+        else if (typeof target !== 'object' || Array.isArray(target)) {
+            errors.push('evidence.reviewHandoff.reviewTarget must be an object with type equal to "pull_request" or "artifact_set"');
+        }
+        else {
+            const t = target;
+            if ('kind' in t && !('type' in t)) {
+                errors.push(`evidence.reviewHandoff.reviewTarget uses kind but must use type — use type, not kind (e.g. { type: "pull_request", label: "...", url: "https://..." })`);
+            }
+            else if (t.type !== 'pull_request' && t.type !== 'artifact_set') {
+                errors.push(`evidence.reviewHandoff.reviewTarget.type must be "pull_request" or "artifact_set" (got ${t.type === undefined ? 'missing' : JSON.stringify(t.type)})`);
+            }
+            else if (t.type === 'pull_request') {
+                if (!isAbsoluteHttpUrl(t.url)) {
+                    errors.push(`evidence.reviewHandoff.reviewTarget.url must be an absolute http or https URL for a pull_request target (got ${t.url === undefined ? 'missing' : JSON.stringify(t.url)})`);
+                }
+                if (Array.isArray(obj.artifacts) && obj.artifacts.length > 0) {
+                    errors.push('evidence.reviewHandoff.artifacts must be empty for a pull_request target — the PR is the complete review surface; set artifacts: []');
+                }
+            }
+            else if (t.type === 'artifact_set') {
+                if (Array.isArray(obj.artifacts)) {
+                    obj.artifacts.forEach((art, i) => {
+                        errors.push(...validateReviewArtifactEntry(art, i));
+                    });
+                }
+            }
+        }
+        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"');
+            }
+        }
+    }
+    else if (obj.reviewRequired === false && Array.isArray(obj.artifacts)) {
+        // For reviewRequired:false, validate any supplied artifact entries (no approval semantics required)
+        obj.artifacts.forEach((art, i) => {
+            errors.push(...validateReviewArtifactEntry(art, i));
+        });
+    }
+    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 = [];
+    if (value.length > 3) {
+        errors.push('evidence.nextJobRecommendations must contain at most 3 entries');
+    }
+    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 ('jobName' in rec && !('jobId' in rec)) {
+            errors.push(`evidence.nextJobRecommendations[${i}] uses jobName, but runnable recommendations must use jobId. Use jobId, not jobName.`);
+        }
+        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`);
+        }
+        if (typeof rec.label === 'string' && rec.label.length > 60) {
+            errors.push(`evidence.nextJobRecommendations[${i}].label must be 60 characters or fewer`);
+        }
+        if (rec.reason !== undefined && typeof rec.reason !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be a string when present`);
+        }
+        if (typeof rec.reason === 'string' && rec.reason.length > 200) {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be 200 characters or fewer`);
+        }
+        if (rec.contextSummary !== undefined && typeof rec.contextSummary !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be a string when present`);
+        }
+        if (typeof rec.contextSummary === 'string' && rec.contextSummary.length > 300) {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be 300 characters or fewer`);
+        }
+    });
+    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');
+    }
+    else {
+        // Issue #1021: validate each task, not just the array's existence. A task naming
+        // no job used to pass here and then be skipped by a bare `continue` in
+        // maybeStartDelegatedChildRuns, so a whole workstream could vanish with nothing
+        // manager-visible. Rejecting at emission lets the agent retry in one round.
+        //
+        // Deliberately NOT required: `taskId`. normalizeDelegationLedger synthesizes one
+        // from the title, so requiring it would reject ledgers the runtime handles fine.
+        // The title requirement accepts `briefing`/`instructions` because the group schema
+        // supplies those instead — this mirrors exactly what the normalizer needs to keep
+        // a task, so the contract can no longer be weaker than the parser.
+        obj.tasks.forEach((task, index) => {
+            const label = `evidence.delegationLedger.tasks[${index}]`;
+            if (!task || typeof task !== 'object' || Array.isArray(task)) {
+                errors.push(`${label} must be an object`);
+                return;
+            }
+            const entry = task;
+            const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0;
+            if (!nonEmpty(entry.title) && !nonEmpty(entry.briefing) && !nonEmpty(entry.instructions)) {
+                errors.push(`${label} needs a title (or briefing/instructions to derive one from)`);
+            }
+            if (!nonEmpty(entry.jobId) && !nonEmpty(entry.job) && !nonEmpty(entry.job_id)) {
+                errors.push(`${label}.jobId is missing; every delegated task must name an existing FRAIM job`);
+            }
+            const issueNumber = entry.issueNumber ?? entry.issue_number ?? entry.issue;
+            if (issueNumber !== undefined && issueNumber !== null
+                && typeof issueNumber !== 'string' && typeof issueNumber !== 'number') {
+                errors.push(`${label}.issueNumber must be a string or number when present (got ${typeof issueNumber})`);
+            }
+        });
+    }
+    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 ?? {};
+    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 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);
+        if (errors)
+            return errors;
+    }
+    if (isDelegationGraphPhase(phase)) {
+        const errors = validateDelegationLedger(evidence.delegationLedger);
+        if (errors)
+            return errors;
+    }
+    if (isAddressFeedbackCompletion(phase, status)) {
+        const errors = validateAddressFeedbackApproval(evidence);
+        if (errors)
+            return errors;
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Rejection message builder
+// ---------------------------------------------------------------------------
+const ADDRESS_FEEDBACK_APPROVAL_SCHEMA = `\`\`\`javascript
+evidence: {
+  approved: true  // Set only after the manager explicitly approves via the Hub review action
+}
+\`\`\``;
+const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
+evidence: {
+  reviewHandoff: {
+    reviewRequired: true,
+    // Pull request review (PR is the complete review surface -- set artifacts: []):
+    reviewTarget: { type: "pull_request", label: "Pull request", url: "https://github.com/org/repo/pull/N" },
+    artifacts: [],
+    // -- OR -- artifact set review (local generated files):
+    // reviewTarget: { type: "artifact_set", label: "Review bundle" },
+    // artifacts: [{ type: "markdown", label: "<label>", path: "<local-path>" }],
+    summary: "<optional summary>",
+    reviewActions: [
+      { kind: "approve", label: "Approve" },
+      { kind: "request_changes", label: "Request Changes" }
+    ]
+  }
+}
+\`\`\`
+Note: reviewTarget uses "type" (not "kind"). Action entries use "kind" -- these are different fields.`;
+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 = {
+    approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,
+    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,
+        '',
+        field === 'approved'
+            ? 'The job is **not** marked complete. Set `evidence.approved: true` (only after explicit manager approval) and resubmit.'
+            : `The job is **not** marked complete. Add the \`evidence.${field}\` object and resubmit this phase.`,
+    ].join('\n');
+}