create-agdf 0.14.2 → 0.14.4

package/generated/plugins/agdf/runtime/create-agdf/lib/control-evaluation/doctor.js

@@ -130,6 +130,19 @@ export function evaluateDoctor(targetDir, selection = {}) {
           "Add at least one evidence row or explicitly document that no evidence exists yet.",
         );
       }
+
+      for (const identityFinding of selectedRunState.identity_findings ?? []) {
+        addFinding(
+          findings,
+          "revise",
+          identityFinding.code,
+          identityFinding.code === "AGDF_RUN_ID_INVALID"
+            ? "The selected run state has a missing or invalid run_id; interaction cards cannot be rendered for it."
+            : "The selected run state has a missing or invalid revision_id; approval interactions cannot be rendered for it.",
+          runPath,
+          "Run run-migrate to repair the run identity, or migrate the legacy state to a canonical run record.",
+        );
+      }
     }
 
     const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");

package/generated/plugins/agdf/runtime/create-agdf/lib/control-evaluation/gate-check.js

@@ -1,4 +1,4 @@
-import { attachApprovalOrientationSnapshot, buildArtefactRefs, buildQualityReadiness, gateTitle, localePack, renderApprovalOrientationSnapshot, renderOperationalStatusCard, resolveHumanRunTitle } from '../interaction-presentation.js';
+import { attachApprovalOrientationSnapshot, buildArtefactRefs, buildQualityReadiness, gateTitle, localePack, renderApprovalOrientationSnapshot, renderOperationalStatusCard, resolveHumanRunTitle, validateApprovalOrientationPreconditions, validateApprovalOrientationSnapshot, validateOperationalStatusCardPreconditions } from '../interaction-presentation.js';
 import { interactionLocales, resolveConfiguredChatLanguage } from '../cli/runtime-context.js';
 import { evaluateDoctor } from './doctor.js';
 import { analyzeDeliveryMap, deriveQualityOutlook } from './delivery-map.js';
@@ -300,8 +300,9 @@ export function evaluateGateCheck(targetDir, selection = {}) {
     humanPresentation,
     revisionId,
   });
+  const readyForApproval = isReadyUserGateApproval({ status, currentGate, missingApproval });
   const approvalOrientation = attachApprovalOrientationSnapshot(statusCard, {
-    ready: isReadyUserGateApproval({ status, currentGate, missingApproval }),
+    ready: readyForApproval,
     humanPresentation,
     revisionId,
     registry: interactionLocales,
@@ -312,6 +313,50 @@ export function evaluateGateCheck(targetDir, selection = {}) {
     enumerable: false,
   });
 
+  const approvalPresentation = renderApprovalOrientationSnapshot(approvalOrientation, {
+    registry: interactionLocales,
+    expectedIdentity: {
+      run_id: statusCard.run_id,
+      revision_id: revisionId,
+      current_gate: currentGate,
+      presentation_language: statusCard.presentation_language,
+    },
+  });
+  const presentationDiagnostics = {};
+  if (!statusPresentation) {
+    presentationDiagnostics.status_presentation_errors = [
+      ...validateOperationalStatusCardPreconditions(statusCard, {
+        registry: interactionLocales,
+        humanPresentation,
+      }).errors,
+    ];
+  }
+  if (readyForApproval && !approvalPresentation) {
+    presentationDiagnostics.approval_presentation_errors = approvalOrientation
+      ? [
+          ...validateApprovalOrientationSnapshot(approvalOrientation, {
+            registry: interactionLocales,
+            expectedIdentity: {
+              run_id: statusCard.run_id,
+              revision_id: revisionId,
+              current_gate: currentGate,
+              presentation_language: statusCard.presentation_language,
+            },
+          }).errors,
+        ]
+      : [
+          ...validateApprovalOrientationPreconditions({
+            statusCard,
+            humanPresentation,
+            registry: interactionLocales,
+            requestedLocale: presentationLocale,
+          }).errors,
+        ];
+    if (!presentationDiagnostics.approval_presentation_errors.length) {
+      presentationDiagnostics.approval_presentation_errors = ["snapshot_unavailable"];
+    }
+  }
+
   return {
     schema_version: "1",
     status,
@@ -332,15 +377,8 @@ export function evaluateGateCheck(targetDir, selection = {}) {
     candidate_runs: runState.candidate_runs ?? [],
     status_card: statusCard,
     status_presentation: statusPresentation,
-    approval_presentation: renderApprovalOrientationSnapshot(approvalOrientation, {
-      registry: interactionLocales,
-      expectedIdentity: {
-        run_id: statusCard.run_id,
-        revision_id: revisionId,
-        current_gate: currentGate,
-        presentation_language: statusCard.presentation_language,
-      },
-    }),
+    approval_presentation: approvalPresentation,
+    ...(Object.keys(presentationDiagnostics).length ? { presentation_diagnostics: presentationDiagnostics } : {}),
     delivery_map: {
       relationships: deliveryMap.relationships,
       mode_slice_decision: runState.mode_slice_decision,
@@ -368,6 +406,14 @@ export function printApprovalEnvelope(report, { io = console, reEvaluate } = {})
   if (report?.approval_presentation) {
     io.log(report.approval_presentation.blocks.run_status_card.markdown);
     io.log("");
+    if (report.status_presentation?.markdown) {
+      io.log(report.status_presentation.markdown);
+    } else {
+      const pack = localePack(interactionLocales, report.approval_presentation.presentation_language || "en");
+      const codes = report.presentation_diagnostics?.status_presentation_errors ?? [];
+      io.log(codes.length ? `${pack.interaction.statusPresentationFailure} (${codes.join(", ")})` : pack.interaction.statusPresentationFailure);
+    }
+    io.log("");
     io.log(report.approval_presentation.blocks.gate_transition_card.markdown);
     io.log("");
     io.log(report.approval_presentation.approval_interaction.exact_text_fallback);
@@ -386,7 +432,10 @@ export function printApprovalEnvelope(report, { io = console, reEvaluate } = {})
   const pack = localePack(interactionLocales, refreshed?.status_card?.presentation_language || report?.status_card?.presentation_language || "en");
   const refreshedApproval = canonicalApprovalForReport(refreshed);
   if (initialApproval && refreshedApproval) {
-    io.log(pack.interaction.presentationFailure);
+    const codes = refreshed?.presentation_diagnostics?.approval_presentation_errors
+      ?? report?.presentation_diagnostics?.approval_presentation_errors
+      ?? [];
+    io.log(codes.length ? `${pack.interaction.presentationFailure} (${codes.join(", ")})` : pack.interaction.presentationFailure);
     io.log(pack.interaction.exactTextRequest.replace("{approval}", refreshedApproval));
     return Object.freeze({ outcome: "exact_text_recovery", requested_decision: true, status: refreshed.status });
   }
@@ -404,7 +453,9 @@ export function printApprovalEnvelope(report, { io = console, reEvaluate } = {})
 function printGateCheckStatusCard(report, io) {
   const card = report.status_card;
   if (!report.status_presentation?.markdown) {
-    io.log(localePack(interactionLocales, card?.presentation_language || "en").interaction.statusPresentationFailure);
+    const failure = localePack(interactionLocales, card?.presentation_language || "en").interaction.statusPresentationFailure;
+    const codes = report.presentation_diagnostics?.status_presentation_errors ?? [];
+    io.log(codes.length ? `${failure} (${codes.join(", ")})` : failure);
     return false;
   }
   io.log(report.status_presentation.markdown);

package/generated/plugins/agdf/runtime/create-agdf/lib/control-evaluation/run-state.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import process from "node:process";
 import { parseControlState, resolveRuns } from "../control-state/index.js";
+import { validateRunIdentity } from "../control-state/run-identity.js";
 import { buildRunCandidates } from "../interaction-presentation.js";
 import { cleanStatusCell, filled, isPlaceholderValue, readTargetFile } from "./shared.js";
 import { extractField, isSafeRepoRelativePath, readVerifiedChangeRecord } from "./verified-change.js";
@@ -87,6 +88,7 @@ export function readRunState(targetDir, selection = {}) {
       memory: {},
       candidate_runs: candidateRuns,
       resolution_error: resolutionError,
+      identity_findings: [],
     };
   }
 
@@ -101,6 +103,10 @@ export function readRunState(targetDir, selection = {}) {
     path: runPath,
     content,
     ...parsed,
+    identity_findings: validateRunIdentity({
+      runId: extractField(content, "run_id").replace(/^`|`$/g, ""),
+      revisionId: extractField(content, "revision_id").replace(/^`|`$/g, ""),
+    }),
   };
 }
 

package/generated/plugins/agdf/runtime/create-agdf/lib/control-state/run-identity.js

@@ -0,0 +1,9 @@
+export const RUN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+export const REVISION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function validateRunIdentity({ runId, revisionId } = {}) {
+  const findings = [];
+  if (!RUN_ID_PATTERN.test(String(runId ?? ""))) findings.push({ code: "AGDF_RUN_ID_INVALID" });
+  if (!REVISION_ID_PATTERN.test(String(revisionId ?? ""))) findings.push({ code: "AGDF_RUN_REVISION_ID_INVALID" });
+  return findings;
+}

package/generated/plugins/agdf/runtime/create-agdf/lib/control-state/run-state-parser.js

@@ -1,4 +1,6 @@
-export const RUN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
+
+export { RUN_ID_PATTERN } from "./run-identity.js";
 export const LIFECYCLES = new Set([
   "active",
   "completed",
@@ -34,7 +36,7 @@ export function parseRunState(content, expected) {
     findings.push({ code: "AGDF_RUN_LIFECYCLE_INVALID" });
   if (!/^[1-9]\d*$/.test(values.get("revision") ?? ""))
     findings.push({ code: "AGDF_RUN_REVISION_INVALID" });
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(values.get("revision_id") ?? ""))
+  if (!REVISION_ID_PATTERN.test(values.get("revision_id") ?? ""))
     findings.push({ code: "AGDF_RUN_REVISION_ID_INVALID" });
   return {
     content,

package/generated/plugins/agdf/runtime/create-agdf/lib/delivery-path-search/contracts.js

@@ -68,6 +68,10 @@ export function validateSearchInput(value) {
   }
   requireString(input.objective, "objective");
   requireString(input.current_gate, "current_gate");
+  optionalBoundedString(input.scope_revision, "scope_revision", 200);
+  optionalBoundedString(input.input_failure_code, "input_failure_code", 200);
+  optionalBoundedString(input.input_failure_detail, "input_failure_detail", 1000);
+  optionalBoundedString(input.input_recovery_action, "input_recovery_action", 1000);
   stringArray(input.allowed_actions, "allowed_actions");
   stringArray(input.forbidden_actions, "forbidden_actions");
   stringArray(input.evidence_refs ?? [], "evidence_refs");
@@ -81,6 +85,39 @@ export function validateSearchInput(value) {
   return structuredClone(input);
 }
 
+const RESULT_PHASE_BY_STATUS = new Map([
+  ["input_unavailable", "input"],
+  ["no_legal_candidates", "candidate"],
+  ["evaluator_unavailable", "evaluation"],
+  ["evaluator_error", "evaluation"],
+  ["recommendation", "search"],
+  ["no_safe_recommendation", "search"],
+]);
+
+export function validateSearchResult(value) {
+  const result = requireObject(value, "search result");
+  if (result.contract_version !== CONTRACT_VERSION) throw new Error(`unsupported search result contract_version: ${result.contract_version}`);
+  const status = requireString(result.status, "result.status");
+  const expectedPhase = RESULT_PHASE_BY_STATUS.get(status);
+  if (!expectedPhase) throw new Error(`unsupported search result status: ${status}`);
+  if (result.outcome_phase !== expectedPhase) throw new Error(`${status} requires outcome_phase ${expectedPhase}`);
+  requireString(result.scope_key, "result.scope_key");
+  optionalBoundedString(result.scope_revision, "result.scope_revision", 200);
+  const provenance = requireObject(result.provenance, "result.provenance");
+  for (const key of ["baseline_candidates", "generated_candidates", "legal_candidates", "rejected_candidates", "evaluation_attempts", "valid_evaluations", "invalid_evaluations"]) {
+    if (!Number.isInteger(provenance[key]) || provenance[key] < 0) throw new Error(`result.provenance.${key} must be a non-negative integer`);
+  }
+  if (provenance.evaluation_attempts !== provenance.valid_evaluations + provenance.invalid_evaluations) throw new Error("result evaluation provenance counts are inconsistent");
+  const recommendationFacing = status === "recommendation" || status === "no_safe_recommendation";
+  if (recommendationFacing && provenance.valid_evaluations < 1) throw new Error(`${status} requires at least one valid evaluation`);
+  if (status === "recommendation" && !result.recommendation) throw new Error("recommendation status requires recommendation content");
+  if (status !== "recommendation" && result.recommendation != null) throw new Error(`${status} must not contain recommendation content`);
+  if (status === "no_legal_candidates" && (provenance.legal_candidates !== 0 || provenance.evaluation_attempts !== 0)) throw new Error("no_legal_candidates requires zero legal candidates and evaluation attempts");
+  if (status === "input_unavailable" && provenance.evaluation_attempts !== 0) throw new Error("input_unavailable requires zero evaluation attempts");
+  if ((status === "evaluator_unavailable" || status === "evaluator_error") && provenance.valid_evaluations !== 0) throw new Error(`${status} requires zero valid evaluations`);
+  return structuredClone(result);
+}
+
 export function validateCandidate(value) {
   const candidate = requireObject(value, "candidate");
   requireString(candidate.id, "candidate.id");

package/generated/plugins/agdf/runtime/create-agdf/lib/delivery-path-search/persistence.js

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { validateSearchResult } from "./contracts.js";
 
 function safeResult(result) {
   return JSON.parse(JSON.stringify(result, (key, value) => {
@@ -9,22 +10,33 @@ function safeResult(result) {
 }
 
 export function persistSearchResult(targetDir, result) {
-  const root = join(targetDir, ".agdf", "control", "artefacts", result.scope_key);
+  const validated = validateSearchResult(result);
+  if (!["recommendation", "no_safe_recommendation"].includes(validated.status)) {
+    throw new Error(`search result status ${validated.status} is not persistable`);
+  }
+  if (validated.provenance.valid_evaluations < 1) {
+    throw new Error("search result requires at least one valid evaluation before persistence");
+  }
+  const root = join(targetDir, ".agdf", "control", "artefacts", validated.scope_key);
   const jsonPath = join(root, "DELIVERY_PATH_SEARCH.json");
   const markdownPath = join(root, "DELIVERY_PATH_SEARCH.md");
   mkdirSync(dirname(jsonPath), { recursive: true });
-  const safe = safeResult(result);
+  const safe = safeResult(validated);
   writeFileSync(jsonPath, `${JSON.stringify(safe, null, 2)}\n`, "utf8");
   const recommendation = safe.recommendation?.action ?? "No safe recommendation";
   writeFileSync(markdownPath, [
     "# Delivery Path Search Decision",
     "",
     `- status: ${safe.status}`,
+    `- outcome_phase: ${safe.outcome_phase}`,
+    `- scope_revision: ${safe.scope_revision}`,
     `- current_gate: ${safe.current_gate}`,
     `- enforcement: ${safe.enforcement.level}`,
     `- recommendation: ${recommendation}`,
     `- stopping_reason: ${safe.stopping_reason}`,
     `- evaluations: ${safe.budgets.evaluations}`,
+    `- evaluation_attempts: ${safe.provenance.evaluation_attempts}`,
+    `- invalid_evaluations: ${safe.provenance.invalid_evaluations}`,
     `- generation_status: ${safe.generation?.status ?? "legacy_deterministic"}`,
     `- generated_candidates: ${safe.generation ? `${safe.generation.accepted}/${safe.generation.returned}` : "0/0"}`,
     `- generation_cost_units: ${safe.generation?.cost_units ?? 0}`,

package/generated/plugins/agdf/runtime/create-agdf/lib/delivery-path-search/search-engine.js

@@ -1,4 +1,4 @@
-import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput } from "./contracts.js";
+import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput, validateSearchResult } from "./contracts.js";
 import { candidateLegality, candidatesFromInput, generatedCandidatesFromResponse } from "./candidate-policy.js";
 import { scoreEvaluation } from "./scoring.js";
 import { generatorRequestFromInput } from "./state-adapter.js";
@@ -14,6 +14,30 @@ function generatorFailureCode(error) {
   return "generator_schema_invalid";
 }
 
+function evaluatorFailureCode(error) {
+  if (error?.code === "ENOENT") return "evaluator_unavailable";
+  if (/auth/i.test(error?.message ?? "")) return "evaluator_authentication_failed";
+  if (/unavailable|not found|not configured/i.test(error?.message ?? "")) return "evaluator_unavailable";
+  return "evaluator_output_invalid";
+}
+
+export function classifyTerminalOutcome({
+  inputUnavailable = false,
+  legalCandidates = 0,
+  evaluationAttempts = 0,
+  validEvaluations = 0,
+  invalidEvaluations = 0,
+  evaluatorUnavailable = false,
+  leader = null,
+}) {
+  if (inputUnavailable) return { status: "input_unavailable", outcome_phase: "input" };
+  if (legalCandidates === 0) return { status: "no_legal_candidates", outcome_phase: "candidate" };
+  if (validEvaluations === 0 && evaluatorUnavailable) return { status: "evaluator_unavailable", outcome_phase: "evaluation" };
+  if (validEvaluations === 0 && legalCandidates > 0) return { status: "evaluator_error", outcome_phase: "evaluation" };
+  if (leader) return { status: "recommendation", outcome_phase: "search" };
+  return { status: "no_safe_recommendation", outcome_phase: "search" };
+}
+
 export async function runDeliveryPathSearch(inputValue, evaluator, options = {}) {
   const input = validateSearchInput(inputValue);
   const startedAt = Date.now();
@@ -22,12 +46,18 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
   const rejected = [];
   const evaluated = [];
   let evaluations = 0;
+  let evaluationAttempts = 0;
+  let invalidEvaluations = 0;
+  let legalCandidates = 0;
+  let rejectedCandidates = 0;
+  let evaluatorUnavailable = false;
+  let evaluationFailureCode = null;
   let costUnits = 0;
   let lastLeaderId = null;
   let stableComparisons = 0;
   let stoppingReason = "candidate_queue_exhausted";
   const generation = {
-    status: input.generation?.enabled ? "failed" : "disabled",
+    status: input.generation?.enabled ? "not_run" : "disabled",
     adapter: options.generator?.metadata ?? null,
     budgets: input.generation ?? null,
     returned: 0,
@@ -38,7 +68,66 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
     failure_code: null,
   };
 
+  const finish = ({ leader = null, outcome, failureCode = null, recoveryAction = null }) => {
+    evaluated.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+    const result = {
+      contract_version: CONTRACT_VERSION,
+      scoring_policy_version: SCORING_POLICY_VERSION,
+      scope_key: input.scope_key,
+      scope_revision: input.scope_revision ?? "unversioned",
+      objective: input.objective,
+      current_gate: input.current_gate,
+      outcome_phase: outcome.outcome_phase,
+      status: outcome.status,
+      recommendation: outcome.status === "recommendation" && leader ? {
+        candidate_id: leader.candidate.id,
+        action: leader.candidate.action,
+        score: leader.score,
+        rationale: leader.evaluation.rationale,
+        expected_evidence: leader.candidate.expected_evidence,
+        tests: leader.candidate.tests,
+        risks: leader.evaluation.risks,
+        assumptions: leader.evaluation.assumptions,
+      } : null,
+      alternatives: outcome.outcome_phase === "search" ? evaluated.slice(1).map((item) => ({
+        candidate_id: item.candidate.id,
+        action: item.candidate.action,
+        score: item.score,
+        rejection_reason: `ranked_below_${leader?.candidate.id ?? "search_policy"}`,
+      })) : [],
+      rejected,
+      provenance: {
+        baseline_candidates: baseline.length,
+        generated_candidates: generation.accepted,
+        legal_candidates: legalCandidates,
+        rejected_candidates: rejectedCandidates + generation.rejected.length,
+        evaluation_attempts: evaluationAttempts,
+        valid_evaluations: evaluations,
+        invalid_evaluations: invalidEvaluations,
+      },
+      enforcement: input.enforcement,
+      evaluator: evaluator?.metadata ?? { name: evaluator?.name ?? "unknown" },
+      generation,
+      budgets: { configured: input.budgets, evaluations, cost_units: costUnits, stable_comparisons: stableComparisons, duration_ms: Date.now() - startedAt },
+      stopping_reason: stoppingReason,
+      failure_code: failureCode,
+      next_action: recoveryAction ?? "Run canonical AGDF gate-check; search does not grant permission.",
+      next_gate_action: recoveryAction ?? "Run canonical AGDF gate-check; search does not grant permission.",
+    };
+    return validateSearchResult(result);
+  };
+
+  if (input.input_failure_code || input.allowed_actions.length === 0) {
+    stoppingReason = input.input_failure_code || "canonical_actions_unavailable";
+    return finish({
+      outcome: classifyTerminalOutcome({ inputUnavailable: true }),
+      failureCode: input.input_failure_code || "canonical_actions_unavailable",
+      recoveryAction: input.input_recovery_action || "Run canonical AGDF gate-check and repair the selected control state.",
+    });
+  }
+
   if (input.generation?.enabled) {
+    generation.status = "failed";
     if (!options.generator) {
       generation.failure_code = "generator_unavailable";
     } else {
@@ -75,17 +164,20 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
   }
 
   while (queue.length > 0) {
-    if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; break; }
-    if (costUnits >= input.budgets.max_cost_units) { stoppingReason = "cost_budget_exhausted"; break; }
-    if (Date.now() - startedAt >= input.budgets.max_duration_ms) { stoppingReason = "duration_budget_exhausted"; break; }
     const candidate = queue.shift();
     const legality = candidateLegality(candidate, input);
     if (!legality.legal) {
+      rejectedCandidates += 1;
       rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: legality.reason });
       continue;
     }
+    legalCandidates += 1;
+    if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; evaluationFailureCode = stoppingReason; break; }
+    if (costUnits >= input.budgets.max_cost_units) { stoppingReason = "cost_budget_exhausted"; evaluationFailureCode = stoppingReason; break; }
+    if (Date.now() - startedAt >= input.budgets.max_duration_ms) { stoppingReason = "duration_budget_exhausted"; evaluationFailureCode = stoppingReason; break; }
 
     try {
+      evaluationAttempts += 1;
       const evaluation = validateEvaluation(await evaluator.evaluate(input, candidate), candidate.id);
       evaluations += 1;
       costUnits += evaluation.cost;
@@ -115,41 +207,39 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
       }
     } catch (error) {
       if (error?.fatalEvaluator === true) throw error;
+      invalidEvaluations += 1;
+      evaluationFailureCode = evaluatorFailureCode(error);
+      evaluatorUnavailable ||= evaluationFailureCode === "evaluator_unavailable" || evaluationFailureCode === "evaluator_authentication_failed";
       rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: `invalid_evaluation: ${error.message}` });
+      if (evaluatorUnavailable) break;
     }
   }
 
   evaluated.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
   const leader = evaluated[0];
-  if (!leader) stoppingReason = rejected.length ? "no_safe_candidate" : stoppingReason;
-  return {
-    contract_version: CONTRACT_VERSION,
-    scoring_policy_version: SCORING_POLICY_VERSION,
-    scope_key: input.scope_key,
-    current_gate: input.current_gate,
-    status: leader ? "recommendation" : "no_safe_recommendation",
-    recommendation: leader ? {
-      candidate_id: leader.candidate.id,
-      action: leader.candidate.action,
-      score: leader.score,
-      rationale: leader.evaluation.rationale,
-      expected_evidence: leader.candidate.expected_evidence,
-      tests: leader.candidate.tests,
-      risks: leader.evaluation.risks,
-      assumptions: leader.evaluation.assumptions,
-    } : null,
-    alternatives: evaluated.slice(1).map((item) => ({
-      candidate_id: item.candidate.id,
-      action: item.candidate.action,
-      score: item.score,
-      rejection_reason: `ranked_below_${leader?.candidate.id ?? "safety_threshold"}`,
-    })),
-    rejected,
-    enforcement: input.enforcement,
-    evaluator: evaluator.metadata ?? { name: evaluator.name ?? "unknown" },
-    generation,
-    budgets: { configured: input.budgets, evaluations, cost_units: costUnits, stable_comparisons: stableComparisons, duration_ms: Date.now() - startedAt },
-    stopping_reason: stoppingReason,
-    next_gate_action: "Run canonical AGDF gate-check; search does not grant permission.",
-  };
+  const outcome = classifyTerminalOutcome({
+    legalCandidates,
+    evaluationAttempts,
+    validEvaluations: evaluations,
+    invalidEvaluations,
+    evaluatorUnavailable,
+    leader,
+  });
+  if (!leader) {
+    stoppingReason = outcome.status === "no_legal_candidates"
+      ? "no_legal_candidates"
+      : outcome.status === "evaluator_unavailable"
+        ? "evaluator_unavailable"
+        : outcome.status === "evaluator_error"
+          ? "evaluator_error"
+          : stoppingReason;
+  }
+  return finish({
+    leader,
+    outcome,
+    failureCode: outcome.outcome_phase === "evaluation" ? evaluationFailureCode : null,
+    recoveryAction: outcome.outcome_phase === "evaluation"
+      ? "Repair the declared evaluator capability and retry from a fresh canonical control snapshot."
+      : null,
+  });
 }