fraim 2.0.362-next.2 → 2.0.362-next.3

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

@@ -72,7 +72,7 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
         personaKey: 'qasm',
         bundleId: 'persona-qasm-core',
         catalogMetadata: buildCatalogMetadata('qasm', ['test-authoring', 'iterative-quality-improvement', 'ui-polish-validation']),
-        protectedJobs: ['test-authoring', 'ui-polish-validation', 'codebase-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'stress-test-app-under-load', 'performance-quality-assessment'],
+        protectedJobs: ['test-authoring', 'mutation-testing', 'ui-polish-validation', 'codebase-quality-assessment', 'test-quality-assessment', 'user-testing-and-bug-bash', 'iterative-quality-improvement', 'accessibility-audit', 'api-testing', 'stress-test-app-under-load', 'performance-quality-assessment'],
         protectedAliases: ['qa', 'quality-assurance'],
         defaultHireMode: 'job',
         lockCopy: 'Hire QAsm to unlock QA validation for this request.'

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

@@ -2,12 +2,13 @@
 /**
  * Handoff Contract Validation (Issue #916)
  *
- * Pure helpers for validating the three evidence fields that FRAIM jobs must
+ * Pure helpers for validating evidence fields that FRAIM jobs
  * 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  (optional at submission, or completion for jobs without submission)
+ *   - evidence.nextJobRecommendations  (optional at submission or an explicit standalone recommendation step)
+ *   - evidence.finalizationOutcome (explicit result of the approved assignment)
  *   - evidence.delegationLedger  (create-delegation-graph phase)
  *
  * Lives in src/core so both the local MCP proxy and evals can import the same
@@ -18,7 +19,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSubmitPhase = isSubmitPhase;
-exports.isRetrospectivePhase = isRetrospectivePhase;
 exports.isAddressFeedbackCompletion = isAddressFeedbackCompletion;
 exports.isDelegationGraphPhase = isDelegationGraphPhase;
 exports.validateAddressFeedbackApproval = validateAddressFeedbackApproval;
@@ -33,6 +33,7 @@ exports.reviewHandoffNormalizationError = reviewHandoffNormalizationError;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
+exports.validateFinalizationOutcome = validateFinalizationOutcome;
 exports.validateHandoffContracts = validateHandoffContracts;
 exports.buildHandoffRejectionMessage = buildHandoffRejectionMessage;
 const resolve_phase_edge_1 = require("./resolve-phase-edge");
@@ -66,13 +67,6 @@ function isSubmitPhase(currentPhase, status, phases) {
     }
     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).
@@ -594,6 +588,24 @@ function validateDelegationLedger(value) {
     }
     return errors.length > 0 ? errors : null;
 }
+/** Validate an explicitly supplied whole-assignment report, never infer one. */
+function validateFinalizationOutcome(value, phaseStatus) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return ['evidence.finalizationOutcome must be an object'];
+    }
+    const result = value;
+    const errors = [];
+    if (!['success', 'failure', 'incomplete'].includes(result.status)) {
+        errors.push('evidence.finalizationOutcome.status must be success, failure, or incomplete');
+    }
+    else if (phaseStatus !== undefined && phaseStatus !== (result.status === 'success' ? 'complete' : result.status)) {
+        errors.push('evidence.finalizationOutcome.status must match the reporting phase status (success uses complete)');
+    }
+    if (typeof result.summary !== 'string' || !result.summary.trim()) {
+        errors.push('evidence.finalizationOutcome.summary must describe the actual result');
+    }
+    return errors.length ? errors : null;
+}
 // ---------------------------------------------------------------------------
 // Orchestrator: called from the seekMentoring handler
 // ---------------------------------------------------------------------------
@@ -610,8 +622,10 @@ function validateHandoffContracts(args) {
     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 (Object.prototype.hasOwnProperty.call(evidence, 'finalizationOutcome')) {
+        const errors = validateFinalizationOutcome(evidence.finalizationOutcome, status);
+        if (errors)
+            return errors;
     }
     if (isSubmitPhase(phase, status, args.phases)) {
         const structuralErrors = validateReviewHandoff(evidence.reviewHandoff);
@@ -628,7 +642,11 @@ function validateHandoffContracts(args) {
         if (actionCompletenessErrors)
             return actionCompletenessErrors;
     }
-    if (isRetrospectivePhase(phase, status)) {
+    // Reviewed jobs own candidates at submission. Retrospective must neither
+    // require nor reinterpret a historical candidate payload. Standalone jobs
+    // can still validate an explicitly supplied recommendation at their own step.
+    if (phase !== 'retrospective' && !isSubmitPhase(phase, status, args.phases)
+        && Object.prototype.hasOwnProperty.call(evidence, 'nextJobRecommendations')) {
         const errors = validateNextJobRecommendations(evidence.nextJobRecommendations);
         if (errors)
             return errors;
@@ -727,6 +745,7 @@ const FIELD_SCHEMAS = {
     approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,
     reviewHandoff: REVIEW_HANDOFF_SCHEMA,
     nextJobRecommendations: NEXT_JOB_RECOMMENDATIONS_SCHEMA,
+    finalizationOutcome: 'evidence: { finalizationOutcome: { status: "success" | "failure" | "incomplete", summary: "<actual result of the approved assignment>" } }. Use phase status "complete" for success, and the matching phase status for failure or incomplete. No transport identifiers or receipt are required.',
     delegationLedger: DELEGATION_LEDGER_SCHEMA,
 };
 /**

package/dist/src/core/review-lifecycle.js

@@ -4,12 +4,12 @@ exports.reviewDigest = reviewDigest;
 exports.createReviewLifecycle = createReviewLifecycle;
 exports.activateReviewJob = activateReviewJob;
 exports.activeReview = activeReview;
-exports.currentReviewTerminalReceipt = currentReviewTerminalReceipt;
-exports.obligationDigest = obligationDigest;
 exports.submitReviewRevision = submitReviewRevision;
 exports.decideReviewRevision = decideReviewRevision;
-exports.acceptReviewReceipt = acceptReviewReceipt;
-exports.unsupportedReviewDeliveryActions = unsupportedReviewDeliveryActions;
+exports.recordReviewOutcome = recordReviewOutcome;
+exports.reserveOutcomeReportRequest = reserveOutcomeReportRequest;
+exports.recommendationsVisible = recommendationsVisible;
+exports.upgradeReviewLifecycle = upgradeReviewLifecycle;
 exports.projectReviewLifecycle = projectReviewLifecycle;
 exports.normalizeReviewCandidates = normalizeReviewCandidates;
 exports.candidateReadiness = candidateReadiness;
@@ -20,60 +20,36 @@ function reviewDigest(value) {
     return (0, crypto_1.createHash)('sha256').update(JSON.stringify(canonical(value))).digest('hex');
 }
 function createReviewLifecycle(source) {
-    return { version: 1, sequence: 0, source, jobs: {}, reviewsByJobInstance: {}, operations: {}, consumedReceipts: [] };
+    return { version: 2, sequence: 0, source, jobs: {}, reviewsByJobInstance: {}, operations: {} };
 }
 function activateReviewJob(state, job) {
     state.jobs[job.jobInstanceId] = { ...job, ...(state.jobs[job.jobInstanceId]?.manualClosure ? { manualClosure: state.jobs[job.jobInstanceId].manualClosure } : {}) };
     state.activeJob = state.jobs[job.jobInstanceId];
 }
 function activeReview(state) {
-    return state?.activeJob ? state.reviewsByJobInstance[state.activeJob.jobInstanceId] : undefined;
+    return state && (state.version === 1 || state.version === 2) && state.activeJob
+        ? state.reviewsByJobInstance[state.activeJob.jobInstanceId] : undefined;
 }
-function currentReviewTerminalReceipt(state) {
-    const job = state?.activeJob;
-    const review = activeReview(state);
-    const receipt = review?.terminalReceipt;
-    return receipt && job && receipt.sourceRunId === state?.source.runId && receipt.jobInstanceId === job.jobInstanceId
-        && receipt.jobName === job.jobName && receipt.workflowDigest === review?.workflowDigest
-        && receipt.sessionId === job.sessionId && receipt.executionEpoch === job.executionEpoch
-        && receipt.revisionId === review?.revisionId && receipt.obligationSetDigest === obligationDigest(review.obligations)
-        ? receipt : undefined;
-}
-function obligationDigest(obligations) {
-    // Verification outcomes change as delivery completes; membership and identity do not.
-    return reviewDigest(obligations.map(({ id, kind, subject, issueNumber, childRunId, childJobName, childJobInstanceId, childRevisionId }) => ({ id, kind, subject, issueNumber, childRunId, childJobName, childJobInstanceId, childRevisionId })).sort((a, b) => a.id.localeCompare(b.id)));
-}
-function submitReviewRevision(state, input, resubmission = false) {
-    const manifest = [...input.manifest].sort((a, b) => a.id.localeCompare(b.id));
-    const target = input.handoff.reviewTarget;
-    const revisionId = reviewDigest({ source: state.source, owner: input.jobInstanceId, jobName: input.jobName, workflowDigest: input.workflowDigest,
-        target: target ? { type: target.type, url: target.url || undefined } : undefined, manifest });
+function submitReviewRevision(state, input) {
     const old = state.reviewsByJobInstance[input.jobInstanceId];
+    const submissionEventId = input.submissionEventId || (0, crypto_1.randomUUID)();
+    if (old && (old.submissionEventId === submissionEventId || old.history.some(item => item.submissionEventId === submissionEventId)))
+        return old;
+    const manifest = [...(input.manifest || [])];
+    const revisionId = reviewDigest({ conversation: state.source.conversationId, owner: input.jobInstanceId, submissionEventId });
     const actionSetDigest = reviewDigest(input.handoff.reviewActions || []);
     const candidates = input.candidates.map(c => {
         const candidateId = reviewDigest({ revisionId, ...candidateIdentity(c) });
         return { ...c, candidateId, revisionId, sourceRunId: state.source.runId, sourceConversationId: state.source.conversationId };
     }).filter((c, index, all) => all.findIndex(other => other.candidateId === c.candidateId) === index).slice(0, 3);
-    if (old?.revisionId === revisionId && old.actionSetDigest === actionSetDigest) {
-        if (resubmission && old.decision?.status === 'changes_requested') {
-            old.history.push({ revisionId: old.revisionId, decision: old.decision, manifest: old.manifest, handoff: old.handoff });
-            delete old.decision;
-            delete old.terminalReceipt;
-            old.obligations = [];
-        }
-        old.handoff = input.handoff;
-        old.candidates = candidates.map(candidate => ({ ...candidate,
-            ...(old.candidates.find(prior => prior.candidateId === candidate.candidateId)?.startedRunId
-                ? { startedRunId: old.candidates.find(prior => prior.candidateId === candidate.candidateId).startedRunId } : {}),
-        }));
-        return old;
-    }
     const review = {
-        jobInstanceId: input.jobInstanceId, jobName: input.jobName, workflowDigest: input.workflowDigest,
+        jobInstanceId: input.jobInstanceId, jobName: input.jobName, workflowDigest: input.workflowDigest || '', submissionEventId,
         handoff: input.handoff, manifest, revisionId, actionSetDigest, candidates, obligations: [],
-        history: old ? [...old.history, { revisionId: old.revisionId, decision: old.decision, terminalReceipt: old.terminalReceipt, manifest: old.manifest, handoff: old.handoff }] : [],
+        history: old ? [...old.history, { revisionId: old.revisionId, submissionEventId: old.submissionEventId, decision: old.decision, outcome: old.outcome, terminalReceipt: old.terminalReceipt, manifest: old.manifest, handoff: old.handoff }] : [],
     };
     state.reviewsByJobInstance[input.jobInstanceId] = review;
+    if (state.jobs[input.jobInstanceId])
+        state.jobs[input.jobInstanceId].state = 'working';
     return review;
 }
 function decideReviewRevision(state, input, obligations = []) {
@@ -98,60 +74,101 @@ function decideReviewRevision(state, input, obligations = []) {
     review.decision = { ...input, status: action.kind === 'request_changes' ? 'changes_requested' : 'approved', at: new Date().toISOString(), action };
     review.obligations = obligations;
     delete review.terminalReceipt;
+    delete review.outcome;
+    delete review.reportRequest;
+    delete review.legacyCompletion;
+    if (state.activeJob)
+        state.activeJob.state = 'working';
     const operation = { id: input.decisionId, kind: 'approval', payloadDigest: reviewDigest(input), state: 'reserved', jobInstanceId: review.jobInstanceId, revisionId: review.revisionId };
     state.operations[operation.id] = operation;
     return { duplicate: false, review, operation };
 }
-function acceptReviewReceipt(state, receipt) {
-    if (state.consumedReceipts.includes(receipt.acceptanceId))
+function boundReview(state, binding) {
+    const review = state.reviewsByJobInstance[binding.jobInstanceId];
+    const job = state.jobs[binding.jobInstanceId];
+    if (!job || job.manualClosure || !review || review.revisionId !== binding.revisionId
+        || review.decision?.status !== 'approved' || review.decision.decisionId !== binding.decisionId
+        || binding.attemptId !== undefined && binding.attemptId !== job.executionEpoch)
+        return undefined;
+    return review;
+}
+/** The server supplies this binding from the captured launch, never from employee arguments. */
+function recordReviewOutcome(state, input) {
+    const review = boundReview(state, input);
+    if (!review || !input.eventId || !input.outcome || !['success', 'failure', 'incomplete'].includes(input.outcome.status)
+        || typeof input.outcome.summary !== 'string' || !input.outcome.summary.trim())
         return false;
-    const review = state.reviewsByJobInstance[receipt.jobInstanceId];
-    const job = state.jobs[receipt.jobInstanceId];
-    if (!review || !job || receipt.sourceRunId !== state.source.runId || receipt.jobName !== review.jobName
-        || receipt.sessionId !== job.sessionId || receipt.executionEpoch !== job.executionEpoch
-        || receipt.workflowDigest !== review.workflowDigest || receipt.revisionId !== review.revisionId)
+    if (review.outcome?.eventId === input.eventId || review.outcomeHistory?.some(item => item.eventId === input.eventId))
         return false;
-    if (receipt.requestedStatus === 'complete' && receipt.outcome === 'terminal'
-        && receipt.obligationSetDigest === obligationDigest(review.obligations)) {
-        review.terminalReceipt = receipt;
-        state.consumedReceipts.push(receipt.acceptanceId);
-        return true;
-    }
-    return false;
+    if (review.outcome)
+        (review.outcomeHistory ||= []).push(review.outcome);
+    review.outcome = { ...input.outcome, summary: input.outcome.summary.trim(), eventId: input.eventId,
+        at: input.at || new Date().toISOString(), ...(input.attemptId ? { attemptId: input.attemptId } : {}) };
+    return true;
+}
+function reserveOutcomeReportRequest(state, binding) {
+    const review = boundReview(state, binding);
+    if (!review || review.outcome || review.legacyCompletion || review.reportRequest && review.reportRequest.state !== 'unrequested')
+        return false;
+    review.reportRequest = { state: 'reserved', revisionId: binding.revisionId, decisionId: binding.decisionId,
+        attemptId: binding.attemptId, at: new Date().toISOString() };
+    return true;
 }
-function unsupportedReviewDeliveryActions(subject) {
-    return subject.split('+').filter(action => !['merge_pr', 'merge_pr_work_completion', 'cleanup_branch'].includes(action));
+function recommendationsVisible(review) {
+    return review?.decision?.status === 'approved' && (!review.outcome || review.outcome.status === 'success');
+}
+/** Version-one facts are retained as history; they no longer authorize future completion. */
+function upgradeReviewLifecycle(state) {
+    if (state.version !== 1)
+        return state;
+    for (const review of Object.values(state.reviewsByJobInstance)) {
+        const job = state.jobs[review.jobInstanceId];
+        const receipt = review.terminalReceipt;
+        const legacyMembership = reviewDigest(review.obligations.map(({ id, kind, subject, issueNumber, childRunId, childJobName, childJobInstanceId, childRevisionId }) => ({ id, kind, subject, issueNumber, childRunId, childJobName, childJobInstanceId, childRevisionId })).sort((a, b) => a.id.localeCompare(b.id)));
+        if (job && !['error', 'waiting', 'scheduled'].includes(job.state) && !job.manualClosure && review.decision?.status === 'approved' && !review.verificationError
+            && receipt?.sessionId === job.sessionId && receipt.executionEpoch === job.executionEpoch
+            && receipt.revisionId === review.revisionId && receipt.obligationSetDigest === legacyMembership
+            && review.obligations.every(item => item.state === 'succeeded'))
+            review.legacyCompletion = { provenance: 'version-1' };
+        if (review.verificationError) {
+            review.outcomeErrors = [...(review.outcomeErrors || []), review.verificationError];
+            delete review.verificationError;
+        }
+    }
+    state.version = 2;
+    return state;
 }
 function projectReviewLifecycle(state) {
+    upgradeReviewLifecycle(state);
+    // Unknown versions are opaque: even their active-job/review layout may differ.
+    // The presentation schema remains supported so clients can display the error.
+    if (state.version !== 2)
+        return { version: 2,
+            sequence: typeof state.sequence === 'number' && Number.isFinite(state.sequence) && state.sequence >= 0 ? state.sequence : 0,
+            displayState: 'error', recommendationsVisible: false, unsupportedVersion: state.version,
+            attentionReason: 'This review was saved by a newer version of Hub.' };
     const job = state.activeJob;
     const review = activeReview(state);
-    const view = { version: 1, sequence: state.sequence, jobInstanceId: job?.jobInstanceId,
+    const view = { version: state.version, sequence: state.sequence, jobInstanceId: job?.jobInstanceId,
         revisionId: review?.revisionId, actionSetDigest: review?.actionSetDigest,
-        decisionStatus: review ? review.decision?.status || 'pending' : undefined, displayState: 'working' };
+        decisionStatus: review ? review.decision?.status || 'pending' : undefined, displayState: 'working',
+        ...(review?.outcome ? { outcomeStatus: review.outcome.status } : {}), recommendationsVisible: recommendationsVisible(review) };
     if (job?.manualClosure)
-        return { ...view, displayState: 'closed_manually', attentionReason: 'Closed manually. Delivery and unresolved obligations remain unverified.' };
+        return { ...view, displayState: 'closed_manually', attentionReason: 'Closed manually; no employee success was inferred.' };
     if (job?.state === 'error')
         return { ...view, displayState: 'error', attentionReason: 'The active job needs recovery.' };
     if (job?.state === 'scheduled')
         return { ...view, displayState: 'scheduled' };
-    if (job?.state === 'waiting')
-        return { ...view, displayState: 'waiting', attentionReason: 'The active job needs a decision.' };
     if (!review)
         return { ...view, displayState: job?.state === 'complete' ? 'complete' : 'working' };
-    if (review.verificationError)
-        return { ...view, displayState: 'error', attentionReason: review.verificationError };
     if (!review.decision || review.decision.status === 'changes_requested')
         return { ...view, displayState: 'waiting', attentionReason: review.decision ? 'Changes requested.' : 'Review the current result.' };
-    if (review.obligations.some(o => o.state === 'failed'))
-        return { ...view, displayState: 'error', attentionReason: 'Required delivery failed.' };
-    if (review.terminalReceipt && review.terminalReceipt.sessionId === job?.sessionId
-        && review.terminalReceipt.executionEpoch === job?.executionEpoch && review.terminalReceipt.revisionId === review.revisionId
-        && review.terminalReceipt.obligationSetDigest === obligationDigest(review.obligations)
-        && review.obligations.every(o => o.state === 'succeeded'))
+    if (review.outcome?.status === 'failure' || review.outcome?.status === 'incomplete')
+        return { ...view, displayState: 'waiting', attentionReason: review.outcome.summary };
+    if (review.outcome?.status === 'success' || review.legacyCompletion)
         return { ...view, displayState: 'complete' };
-    const unsupported = review.obligations.filter(o => o.kind === 'delivery' && o.state !== 'succeeded')
-        .flatMap(o => unsupportedReviewDeliveryActions(o.subject));
-    return { ...view, displayState: 'finalizing', ...(unsupported.length ? { attentionReason: `Cannot automatically verify ${[...new Set(unsupported)].join(', ')}. Mark complete can close the job manually without confirming delivery.` } : {}) };
+    return { ...view, displayState: 'finalizing', ...(review.reportRequest && review.reportRequest.state !== 'unrequested'
+            ? { attentionReason: 'Waiting for the employee to report the final result.' } : {}) };
 }
 function candidateIdentity(candidate) {
     return { jobId: candidate.jobId,
@@ -170,30 +187,28 @@ function normalizeReviewCandidates(value) {
         .slice(0, 3).map(c => ({ jobId: c.jobId, label: c.label, reason: typeof c.reason === 'string' ? c.reason : undefined,
         contextSummary: typeof c.contextSummary === 'string' ? c.contextSummary : undefined, artifactIds: c.artifactIds, prerequisites: c.prerequisites }));
 }
-function candidateReadiness(review, candidate, available) {
+function candidateReadiness(review, candidate, available, context = {}) {
     if (!available)
         return { readiness: 'unavailable', readinessReason: 'Unavailable in this project.' };
-    if (review.verificationError)
-        return { readiness: 'unavailable', readinessReason: review.verificationError };
-    if (review.decision?.status !== 'approved')
-        return { readiness: 'waiting', readinessReason: 'Waiting for approval of this result.' };
+    if (!recommendationsVisible(review))
+        return { readiness: 'waiting', readinessReason: review.outcome?.summary || 'Waiting for approval of this result.' };
     for (const p of candidate.prerequisites || []) {
-        const artifact = review.manifest.find(a => a.id === p.reference);
-        const obligation = review.obligations.find(o => o.id === p.reference || o.subject === p.reference);
-        const met = p.kind === 'approved_artifact' ? !!artifact
-            : p.kind === 'delivered_artifact' ? !!artifact
-                && review.obligations.some(o => o.kind === 'artifact' && o.subject === artifact.id && o.state === 'succeeded')
-                // Matching local bytes prove integrity, not publication or receipt at a destination.
-                // Delivery remains unknown until the selected action's owning verifier supplies proof.
-                && review.obligations.some(o => o.kind === 'delivery')
-                && review.obligations.filter(o => o.kind === 'delivery').every(o => o.state === 'succeeded' && !!o.evidenceRef)
-                : p.kind === 'selected_action_success' ? obligation?.kind === 'delivery' && obligation.state === 'succeeded'
-                    : p.kind === 'required_child_success' ? obligation?.kind === 'child' && obligation.state === 'succeeded'
-                        : false; // External facts require an owning provider verifier; absence is never Ready.
+        const artifact = hasArtifactReference(review, p.reference);
+        const reportedSuccess = review.outcome?.status === 'success';
+        const met = p.kind === 'approved_artifact' ? artifact
+            : p.kind === 'delivered_artifact' ? artifact && reportedSuccess
+                : p.kind === 'selected_action_success' ? reportedSuccess && !!review.decision?.action.deliveryActionId
+                    && [review.decision.action.id, review.decision.action.deliveryActionId, `delivery:${review.decision.action.deliveryActionId}`].includes(p.reference)
+                    : (context.reportedPrerequisites || []).some(reported => reported.kind === p.kind && reported.reference === p.reference);
         if (!met)
             return { readiness: 'waiting', readinessReason: `Waiting for ${p.kind.replace(/_/g, ' ')}: ${p.reference}.` };
     }
-    if (candidate.artifactIds?.some(id => !review.manifest.some(a => a.id === id)))
+    if (candidate.artifactIds?.some(id => !hasArtifactReference(review, id)))
         return { readiness: 'unavailable', readinessReason: 'A referenced artifact is unavailable.' };
     return { readiness: 'ready', readinessReason: 'Ready' };
 }
+function hasArtifactReference(review, reference) {
+    return review.manifest.some(item => item.id === reference || item.locator === reference)
+        || review.handoff.artifacts.some(item => item.path === reference || item.url === reference || item.label === reference)
+        || review.handoff.reviewTarget?.url === reference;
+}

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -72,11 +72,15 @@ function activeReviewReferences() {
         }
         const complete = (record) => {
             const state = record.reviewLifecycle;
-            if (state && state.version !== 1)
+            if (state && state.version !== 1 && state.version !== 2)
                 throw new Error('Unknown review version');
             return state ? (0, review_lifecycle_1.projectReviewLifecycle)(state).displayState === 'complete'
                 : record.status === 'completed' && record.pauseReason === 'done';
         };
+        const handoffReferences = (handoff) => [
+            ...(handoff?.artifacts || []).flatMap(artifact => artifact.path ? [{ locator: artifact.path }] : []),
+            ...(handoff?.reviewTarget?.url ? [{ locator: handoff.reviewTarget.url }] : []),
+        ];
         const protect = (manifest, home) => {
             if (!Array.isArray(manifest) || !home || !node_path_1.default.isAbsolute(home))
                 throw new Error('Unresolved input references');
@@ -92,17 +96,20 @@ function activeReviewReferences() {
             }
         };
         for (const { bucket, record } of records) {
-            if (record.recommendationInput && !complete(record))
-                protect(record.recommendationInput.manifest, record.projectPath);
+            if (record.recommendationInput && !complete(record)) {
+                protect([...record.recommendationInput.manifest, ...(record.recommendationInput.artifacts || [])
+                        .flatMap(artifact => artifact.path ? [{ locator: artifact.path }] : [])], record.projectPath);
+            }
             const state = record.reviewLifecycle;
             if (!state)
                 continue;
-            if (state.version !== 1)
+            if (state.version !== 1 && state.version !== 2)
                 throw new Error('Unknown review version');
             for (const review of Object.values(state.reviewsByJobInstance)) {
                 const job = state.jobs[review.jobInstanceId];
-                if (!job || (0, review_lifecycle_1.projectReviewLifecycle)({ ...state, activeJob: job }).displayState !== 'complete')
-                    protect(review.manifest, state.source.projectPath);
+                if (!job || (0, review_lifecycle_1.projectReviewLifecycle)({ ...state, activeJob: job }).displayState !== 'complete') {
+                    protect([...review.manifest, ...handoffReferences(review.handoff)], state.source.projectPath);
+                }
             }
             for (const operation of Object.values(state.operations)) {
                 if (operation.kind !== 'recommendation')
@@ -111,9 +118,11 @@ function activeReviewReferences() {
                 if (child && complete(child))
                     continue;
                 const review = state.reviewsByJobInstance[operation.jobInstanceId];
-                const manifest = operation.input?.manifest || (review?.revisionId === operation.revisionId
-                    ? review.manifest : review?.history.find(previous => previous.revisionId === operation.revisionId)?.manifest);
-                protect(manifest, state.source.projectPath);
+                const submitted = review?.revisionId === operation.revisionId ? review
+                    : review?.history.find(previous => previous.revisionId === operation.revisionId);
+                const manifest = operation.input?.manifest || submitted?.manifest;
+                protect(manifest && [...manifest, ...(operation.input?.artifacts || []).flatMap(artifact => artifact.path ? [{ locator: artifact.path }] : []),
+                    ...handoffReferences(submitted?.handoff)], state.source.projectPath);
             }
         }
         return { paths, unknown: false };

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

@@ -2903,7 +2903,8 @@ class FraimLocalMCPServer {
                     });
                     // Submission candidates are optional; the Hub filters unavailable jobs.
                     // A malformed suggestion must not reject an otherwise valid review.
-                    if (!args.currentPhase.includes('submit') && !args.currentPhase.includes('submission')) {
+                    if (args.currentPhase !== 'retrospective' && !(0, handoff_contracts_1.isSubmitPhase)(args.currentPhase, args.status, handoffPhaseMap)
+                        && !args.currentPhase.includes('submit') && !args.currentPhase.includes('submission')) {
                         handoffErrors.push(...await this.validateNextJobRecommendationJobIds(args.evidence?.nextJobRecommendations, mentor));
                     }
                     // Issue #1857: enforced on its own terms rather than folded into
@@ -2919,8 +2920,9 @@ class FraimLocalMCPServer {
                     if (handoffErrors.length > 0) {
                         const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                             : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'
-                                : handoffErrors[0].includes('evidence.approved') ? 'approved'
-                                    : 'delegationLedger';
+                                : handoffErrors[0].includes('finalizationOutcome') ? 'finalizationOutcome'
+                                    : 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
@@ -3146,12 +3148,6 @@ class FraimLocalMCPServer {
                 }
                 processedResponse.result.structuredContent = { ...processedResponse.result.structuredContent, ...(acceptedReceipt ? { acceptedReceipt } : {}) };
             }
-            else if (process.env.FRAIM_REVIEW_BINDING && !(args.status === 'starting' && args.requestInstructions === true)) {
-                const binding = (0, run_recovery_state_1.parseReviewExecutionBinding)(process.env.FRAIM_REVIEW_BINDING);
-                if (binding?.revisionId && binding.jobInstanceId === args.jobId) {
-                    return { jsonrpc: '2.0', id: request.id, result: { isError: true, content: [{ type: 'text', text: 'Remote phase acceptance lacks a supported workflow receipt.' }] } };
-                }
-            }
             const textBlock = processedResponse.result?.content?.find((item) => item.type === 'text');
             if (textBlock) {
                 const remoteWarning = metadata.phaseStartWarning;

package/dist/src/mcp/tool-schemas.js

@@ -369,6 +369,18 @@ Do not use this tool for other repositories or external project issue trackers.`
                     },
                     evidence: {
                         type: 'object',
+                        properties: {
+                            finalizationOutcome: {
+                                type: 'object',
+                                description: 'Explicit outcome of the whole approved assignment after selected work and required closure. Report success with phase status complete, or failure/incomplete with the matching phase status. Ordinary phase completion is not an assignment outcome. No job/run identifiers or receipt are required.',
+                                properties: {
+                                    status: { type: 'string', enum: ['success', 'failure', 'incomplete'] },
+                                    summary: { type: 'string', minLength: 1, description: 'Actual result, or the reason work failed or remains incomplete.' }
+                                },
+                                required: ['status', 'summary'],
+                                additionalProperties: false
+                            }
+                        },
                         description: 'Structured evidence or data collected (e.g., prospect counts, test results). Submit phases should put review artifacts in evidence.reviewHandoff rather than printing raw JSON to the user. Prepare optional follow-on candidates at submission in evidence.nextJobRecommendations (0-3 entries with jobId, label, reason?, contextSummary?, artifactIds?: string[], prerequisites?: {kind, reference}[]); Standalone jobs with an explicit recommendation step may emit there; the Hub retains submitted candidates through finalization. Prerequisite kinds: approved_artifact, delivered_artifact, selected_action_success, required_child_success, external_result. Reference actual artifacts/actions/children/provider evidence. Do not emit readiness or server-owned candidate/revision/source/start identities. Candidates are revealed only after persisted approval; selecting one prepares a draft, and only explicit Send starts a follow-on.',
                         additionalProperties: true
                     },

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

@@ -759,8 +759,9 @@ class McpService {
         if (handoffErrors.length > 0) {
             const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                 : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'
-                    : handoffErrors[0].includes('evidence.approved') ? 'approved'
-                        : 'delegationLedger';
+                    : handoffErrors[0].includes('finalizationOutcome') ? 'finalizationOutcome'
+                        : 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.

package/package.json

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