agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/core/constants.ts

@@ -1,10 +1,12 @@
-export const DEFAULT_FEATURE_STATUS = 'planning' as const;
+export const DEFAULT_FEATURE_STATUS = 'intake' as const;
 
 export const STATUS = {
+  INTAKE: 'intake',
   PLANNING: 'planning',
   BUILDING: 'building',
   QA: 'qa',
   BLOCKED: 'blocked',
+  AWAITING_INPUT: 'awaiting_input',
   READY_TO_MERGE: 'ready_to_merge',
   MERGED: 'merged',
   FAILED: 'failed',
@@ -24,6 +26,7 @@ export const TOOLS = {
   FEATURE_DISCOVER_SPECS: 'feature.discover_specs',
   FEATURE_INIT: 'feature.init',
   FEATURE_GET_CONTEXT: 'feature.get_context',
+  FEATURE_INTAKE_SUBMIT: 'feature.intake_submit',
   FEATURE_STATE_GET: 'feature.state_get',
   FEATURE_STATE_PATCH: 'feature.state_patch',
   FEATURE_LOG_APPEND: 'feature.log_append',
@@ -37,6 +40,10 @@ export const TOOLS = {
   REPO_READ_FILE: 'repo.read_file',
   REPO_SEARCH: 'repo.search',
   REPO_DIFF_BUNDLE: 'repo.diff_bundle',
+  REPO_RECONCILE_MAINLINE: 'repo.reconcile_mainline',
+  REPO_CONFLICT_FILES: 'repo.conflict_files',
+  REPO_RESOLVE_CONFLICT: 'repo.resolve_conflict',
+  REPO_CONFLICT_ABORT: 'repo.conflict_abort',
   FEATURE_READY_TO_MERGE: 'feature.ready_to_merge',
   FEATURE_DELETE: 'feature.delete',
   GATES_LIST: 'gates.list',
@@ -49,11 +56,19 @@ export const TOOLS = {
   COLLISIONS_SCAN: 'collisions.scan',
   REPORT_DASHBOARD: 'report.dashboard',
   REPORT_FEATURE_SUMMARY: 'report.feature_summary',
+  RUNTIME_EXECUTION_REQUEST_SUBMIT: 'runtime.execution_request_submit',
+  RUNTIME_EXECUTION_REQUEST_LIST: 'runtime.execution_request_list',
   FEATURE_SEND_MESSAGE: 'feature.send_message',
+  FEATURE_QUESTION_CREATE: 'feature.question_create',
+  FEATURE_QUESTION_LIST: 'feature.question_list',
+  FEATURE_QUESTION_ANSWER: 'feature.question_answer',
   COST_RECORD: 'cost.record',
   COST_GET: 'cost.get',
   PERFORMANCE_RECORD_OUTCOME: 'performance.record_outcome',
   PERFORMANCE_GET_ANALYTICS: 'performance.get_analytics',
+  REPLAY_TIMELINE_GET: 'replay.timeline_get',
+  EVIDENCE_VERIFY_CHAIN: 'evidence.verify_chain',
+  DOCTOR_RUN: 'doctor.run',
 } as const;
 
 export const DEFAULT_CLUSTER = {
@@ -61,6 +76,7 @@ export const DEFAULT_CLUSTER = {
   planner_session_id: 'unknown',
   builder_session_id: 'unknown',
   qa_session_id: 'unknown',
+  reconciler_session_id: 'unknown',
 };
 
 export const DEFAULT_ROLE_STATUS = {
@@ -80,5 +96,6 @@ export const ALLOWED_ACTORS = new Set<string>([
   'planner',
   'builder',
   'qa',
+  'reconciler',
   'system',
 ]);

package/apps/control-plane/src/core/error-codes.ts

@@ -13,11 +13,25 @@ export const ERROR_CODES = {
   LOCK_CONFLICT: 'lock_conflict',
   STALE_LOCK_RECLAIMED: 'stale_lock_reclaimed',
   RUN_ALREADY_ACTIVE: 'run_already_active',
+  RUN_NOT_ACTIVE: 'run_not_active',
   RUN_LEASE_NOT_OWNED: 'run_lease_not_owned',
+  EXECUTION_REQUEST_TARGET_MISMATCH: 'execution_request_target_mismatch',
+  DUPLICATE_EXECUTION_REQUEST: 'duplicate_execution_request',
   COLLISION_DETECTED: 'collision_detected',
   BLOCKED_BY_COLLISION_POLICY: 'blocked_by_collision_policy',
+  COLLISION_OVERRIDE_NOT_FOUND: 'collision_override_not_found',
+  COLLISION_OVERRIDE_NOT_APPLICABLE: 'collision_override_not_applicable',
+  COLLISION_OVERRIDE_CONTRACT_FORBIDDEN: 'collision_override_contract_forbidden',
+  COLLISION_OVERRIDE_STALE: 'collision_override_stale',
+  COLLISION_RECORD_NOT_FOUND: 'collision_record_not_found',
   COMMIT_DISABLED: 'commit_disabled',
   MERGE_DISABLED: 'merge_disabled',
+  MERGE_NO_CHANGES: 'merge_no_changes',
+  MERGE_BASE_NOT_FOUND: 'merge_base_not_found',
+  RECONCILIATION_FAILED: 'reconciliation_failed',
+  UNRESOLVABLE_CONFLICT: 'unresolvable_conflict',
+  UNCOMMITTED_CHANGES: 'uncommitted_changes',
+  REMOTE_LOCAL_DIVERGENCE: 'remote_local_divergence',
   USER_APPROVAL_REQUIRED: 'user_approval_required',
   MISSING_ROLE_PROMPT: 'missing_role_prompt',
   QA_INDEX_VERSION_CONFLICT: 'qa_index_version_conflict',
@@ -38,9 +52,24 @@ export const ERROR_CODES = {
   PROVIDER_HARD_TIMEOUT: 'provider_hard_timeout',
   PROVIDER_PROCESS_KILLED: 'provider_process_killed',
   PROVIDER_OUTPUT_INVALID: 'provider_output_invalid',
+  INTERACTIVE_CHECKPOINT_INVALID: 'interactive_checkpoint_invalid',
+  INTERACTIVE_NO_NEW_WORK: 'interactive_no_new_work',
+  STALE_GATE_EVIDENCE: 'stale_gate_evidence',
   PROVIDER_NO_PROGRESS: 'provider_no_progress',
+  PROVIDER_CONTEXT_STALL: 'provider_context_stall',
   PROVIDER_OUTPUT_LOOP: 'provider_output_loop',
   PROVIDER_PLAN_CONFORMANCE_STALL: 'provider_plan_conformance_stall',
+  QUESTION_AWAITING_INPUT: 'question_awaiting_input',
+  QUESTION_NOT_FOUND: 'question_not_found',
+  QUESTION_ALREADY_CLOSED: 'question_already_closed',
+  QUESTION_ALREADY_ANSWERED: 'question_already_closed',
+  QUESTION_ANSWER_INVALID: 'question_answer_invalid',
+  QUESTION_INVALID_ANSWER: 'question_answer_invalid',
+  QUESTION_CONFLICT_OPEN: 'question_conflict_open',
+  QUESTION_ANSWER_NOT_ALLOWED_IN_TERMINAL_STATE: 'question_answer_not_allowed_in_terminal_state',
+  VERIFIED_MANIFEST_REQUIRED: 'verified_manifest_required',
+  INTAKE_SUBMISSION_INVALID: 'intake_submission_invalid',
+  PLAN_TRACE_INVALID: 'plan_trace_invalid',
   UNAUTHENTICATED: 'unauthenticated',
   INVALID_ACTOR_CLAIM: 'invalid_actor_claim',
   OPERATION_ID_REQUIRED: 'operation_id_required',
@@ -57,6 +86,16 @@ export const ERROR_CODES = {
   INTERNAL_ERROR: 'internal_error',
   DEPENDENCY_UNRESOLVED: 'dependency_unresolved',
   DEPENDENCY_CIRCULAR: 'dependency_circular',
+  REPLAY_RUN_NOT_FOUND: 'replay_run_not_found',
+  REPLAY_TIMELINE_CORRUPT: 'replay_timeline_corrupt',
+  REPLAY_TIMELINE_WRITE_FAILED: 'replay_timeline_write_failed',
+  EVIDENCE_CHAIN_MISSING: 'evidence_chain_missing',
+  EVIDENCE_CHAIN_ARTIFACT_MISSING: 'evidence_chain_artifact_missing',
+  EVIDENCE_CHAIN_HASH_MISMATCH: 'evidence_chain_hash_mismatch',
+  EVIDENCE_CHAIN_DISCONTINUITY: 'evidence_chain_discontinuity',
+  EVIDENCE_INTEGRITY_WRITE_FAILED: 'evidence_integrity_write_failed',
+  DOCTOR_CHECK_FAILED: 'doctor_check_failed',
+  DOCTOR_REPORT_WRITE_FAILED: 'doctor_report_write_failed',
 } as const;
 
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/apps/control-plane/src/core/execution-control.ts

@@ -0,0 +1,56 @@
+export type ExecutionRequestType = 'add_features';
+export type ExecutionRequestStatus = 'pending' | 'applied' | 'rejected';
+
+export interface ExecutionRequestFeature {
+  feature_id: string;
+  spec_path: string;
+}
+
+export interface ExecutionRequestSkippedFeature {
+  feature_id: string;
+  reason: string;
+}
+
+export interface PendingExecutionRequestProgress {
+  detected_at: string | null;
+  last_evaluated_at: string | null;
+  queued: string[];
+  skipped: ExecutionRequestSkippedFeature[];
+  deferred: ExecutionRequestSkippedFeature[];
+}
+
+export interface AppliedExecutionRequestOutcome {
+  queued: string[];
+  skipped: ExecutionRequestSkippedFeature[];
+}
+
+export interface RejectedExecutionRequestOutcome {
+  code: string;
+  message: string;
+}
+
+export type ExecutionRequestOutcome =
+  | AppliedExecutionRequestOutcome
+  | RejectedExecutionRequestOutcome
+  | null;
+
+export interface ExecutionRequestItem {
+  request_id: string;
+  request_type: ExecutionRequestType;
+  status: ExecutionRequestStatus;
+  requested_at: string;
+  processed_at: string | null;
+  requested_by: string;
+  operation_id: string;
+  features: ExecutionRequestFeature[];
+  progress: PendingExecutionRequestProgress | null;
+  outcome: ExecutionRequestOutcome;
+}
+
+export interface ExecutionControlSnapshot {
+  version: 1;
+  run_id: string;
+  owner_instance_id: string;
+  updated_at: string;
+  items: ExecutionRequestItem[];
+}

package/apps/control-plane/src/core/feature-resume-phase.ts

@@ -0,0 +1,118 @@
+import { STATUS } from './constants.js';
+import { normalizeMergeRepairState } from './merge-repair.js';
+
+type AnyRecord = Record<string, unknown>;
+
+export type ResumableFeaturePhase =
+  | typeof STATUS.INTAKE
+  | typeof STATUS.PLANNING
+  | typeof STATUS.BUILDING
+  | typeof STATUS.QA
+  | typeof STATUS.READY_TO_MERGE;
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asResumablePhase(value: unknown): ResumableFeaturePhase | null {
+  return value === STATUS.INTAKE ||
+    value === STATUS.PLANNING ||
+    value === STATUS.BUILDING ||
+    value === STATUS.QA ||
+    value === STATUS.READY_TO_MERGE
+    ? value
+    : null;
+}
+
+function readPendingMainlineResumePhase(frontMatter: AnyRecord): ResumableFeaturePhase | null {
+  const conflicts = Array.isArray(frontMatter.conflicts) ? frontMatter.conflicts : [];
+  for (let index = conflicts.length - 1; index >= 0; index -= 1) {
+    const entry = asRecord(conflicts[index]);
+    if (entry.type !== 'mainline_divergence') {
+      continue;
+    }
+    if (entry.resolution_status !== 'pending' && entry.resolution_status !== 'in_progress') {
+      continue;
+    }
+    const resumePhase = asResumablePhase(entry.resume_status);
+    if (resumePhase) {
+      return resumePhase;
+    }
+  }
+  return null;
+}
+
+function deriveBlockedResumePhase(frontMatter: AnyRecord): ResumableFeaturePhase {
+  const humanInput = asRecord(frontMatter.human_input);
+  const explicitResumePhase =
+    asResumablePhase(humanInput.resume_status) ?? readPendingMainlineResumePhase(frontMatter);
+  if (explicitResumePhase) {
+    return explicitResumePhase;
+  }
+
+  const intake = asRecord(frontMatter.intake);
+  const intakeStatus = asString(intake.status);
+  if (
+    intakeStatus === 'not_started' ||
+    intakeStatus === 'in_progress' ||
+    intakeStatus === 'awaiting_input'
+  ) {
+    return STATUS.INTAKE;
+  }
+
+  const gates = asRecord(frontMatter.gates);
+  const evidence = asRecord(frontMatter.evidence);
+  const lastGateMode = asString(evidence.last_gate_mode);
+  const statusReason = asString(frontMatter.status_reason) ?? '';
+  const mergeRepair = normalizeMergeRepairState(frontMatter);
+
+  if (
+    mergeRepair.active ||
+    lastGateMode === 'merge' ||
+    gates.merge === 'fail' ||
+    statusReason.includes('merge_gate_repair:') ||
+    statusReason.includes('blocked:gate_retry_waiting_for_new_work:merge')
+  ) {
+    return STATUS.READY_TO_MERGE;
+  }
+
+  if (lastGateMode === 'full' || gates.full === 'fail') {
+    return STATUS.QA;
+  }
+
+  if (
+    lastGateMode === 'fast' ||
+    gates.fast === 'fail' ||
+    gates.fast === 'pass' ||
+    gates.plan === 'pass'
+  ) {
+    return STATUS.BUILDING;
+  }
+
+  return STATUS.PLANNING;
+}
+
+export function deriveFeatureResumePhase(frontMatter: unknown): ResumableFeaturePhase {
+  const normalizedFrontMatter = asRecord(frontMatter);
+  const humanInput = asRecord(normalizedFrontMatter.human_input);
+  const currentStatus = asString(normalizedFrontMatter.status);
+  const explicitResumePhase = asResumablePhase(humanInput.resume_status);
+
+  if (currentStatus === STATUS.AWAITING_INPUT && explicitResumePhase) {
+    return explicitResumePhase;
+  }
+
+  if (currentStatus === STATUS.BLOCKED || currentStatus === STATUS.AWAITING_INPUT) {
+    return deriveBlockedResumePhase(normalizedFrontMatter);
+  }
+
+  return asResumablePhase(currentStatus) ?? STATUS.PLANNING;
+}

package/apps/control-plane/src/core/gate-freshness.ts

@@ -0,0 +1,359 @@
+type AnyRecord = Record<string, unknown>;
+
+export const EMPTY_WORKTREE_DIFF_HASH =
+  'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+
+export type ParsedCheckpointValidity = 'valid' | 'invalid' | 'skipped' | 'missing';
+export type ParsedCheckpointSeverity = 'info' | 'warning' | 'error' | 'critical' | null;
+export type GateEvidenceFreshness = 'current' | 'stale' | 'missing' | 'unknown';
+
+export interface ParsedCheckpointSummary {
+  checkpointId: string;
+  validationStatus: ParsedCheckpointValidity;
+  severity: ParsedCheckpointSeverity;
+  diffHash: string | null;
+  headSha: string | null;
+  workspaceFingerprint: string | null;
+  netNewWorktreeChange: boolean;
+  violations: string[];
+}
+
+export interface ParsedGateEvidenceSummary {
+  mode: string | null;
+  overall: string | null;
+  inputDiffHash: string | null;
+  inputCheckpointId: string | null;
+  inputHeadSha?: string | null;
+  inputWorkspaceFingerprint?: string | null;
+  inputWorktreeValidity: 'valid' | 'invalid' | 'unknown';
+  finishedAt: string | null;
+}
+
+export interface GateFreshnessAssessment {
+  mode: string;
+  checkpoint: ParsedCheckpointSummary | null;
+  checkpointValidity: ParsedCheckpointValidity;
+  gateEvidence: ParsedGateEvidenceSummary | null;
+  freshness: GateEvidenceFreshness;
+  shouldRerunGate: boolean;
+  currentDiffHash: string | null;
+  latestGateOverall: string | null;
+  reasons: string[];
+}
+
+function asRecord(value: unknown): AnyRecord | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as AnyRecord;
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => asString(item)).filter((item): item is string => item !== null);
+}
+
+function asBoolean(value: unknown): boolean {
+  return value === true;
+}
+
+function parseCheckpointValidationStatus(value: unknown): ParsedCheckpointValidity {
+  const validationStatusValue = asString(value);
+  return validationStatusValue === 'valid' ||
+    validationStatusValue === 'invalid' ||
+    validationStatusValue === 'skipped'
+    ? validationStatusValue
+    : 'missing';
+}
+
+function parseCheckpointSeverity(value: unknown): ParsedCheckpointSeverity {
+  const severityValue = asString(value);
+  return severityValue === 'info' ||
+    severityValue === 'warning' ||
+    severityValue === 'error' ||
+    severityValue === 'critical'
+    ? severityValue
+    : null;
+}
+
+function parseCheckpointSummary(value: unknown): ParsedCheckpointSummary | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const checkpointId = asString(record.checkpoint_id);
+  const validationStatus = parseCheckpointValidationStatus(record.validation_status);
+  if (!checkpointId || validationStatus === 'missing') {
+    return null;
+  }
+
+  return {
+    checkpointId,
+    validationStatus,
+    severity: parseCheckpointSeverity(record.severity),
+    diffHash: asString(record.diff_hash),
+    headSha: asString(record.head_sha),
+    workspaceFingerprint: asString(record.workspace_fingerprint),
+    netNewWorktreeChange: asBoolean(record.net_new_worktree_change),
+    violations: asStringArray(record.violations),
+  };
+}
+
+export function resolveCheckpointValidity(
+  checkpoint: ParsedCheckpointSummary | null,
+): ParsedCheckpointValidity {
+  if (!checkpoint) {
+    return 'missing';
+  }
+  if (checkpoint.validationStatus === 'invalid') {
+    return 'skipped';
+  }
+  return checkpoint.validationStatus;
+}
+
+function checkpointAllowsGateRerun(checkpoint: ParsedCheckpointSummary | null): boolean {
+  const checkpointValidity = resolveCheckpointValidity(checkpoint);
+  return checkpointValidity === 'valid' || checkpointValidity === 'skipped';
+}
+
+export function readLatestCheckpoint(
+  frontMatter: Record<string, unknown>,
+): ParsedCheckpointSummary | null {
+  const checkpoints = Array.isArray(frontMatter.checkpoints) ? frontMatter.checkpoints : [];
+  return parseCheckpointSummary(checkpoints.at(-1));
+}
+
+export function readLatestEffectiveCheckpoint(
+  frontMatter: Record<string, unknown>,
+): ParsedCheckpointSummary | null {
+  const checkpoints = Array.isArray(frontMatter.checkpoints) ? frontMatter.checkpoints : [];
+  const parsed: ParsedCheckpointSummary[] = [];
+  for (const checkpoint of checkpoints) {
+    const summary = parseCheckpointSummary(checkpoint);
+    if (summary) {
+      parsed.push(summary);
+    }
+  }
+  const latest = parsed.at(-1) ?? null;
+  if (!latest || resolveCheckpointValidity(latest) !== 'skipped' || !latest.diffHash) {
+    return latest;
+  }
+  const latestSnapshotFingerprint = latest.workspaceFingerprint;
+
+  for (let index = parsed.length - 2; index >= 0; index -= 1) {
+    const candidate = parsed[index];
+    const sameSnapshot =
+      latestSnapshotFingerprint != null
+        ? candidate.workspaceFingerprint === latestSnapshotFingerprint
+        : candidate.diffHash === latest.diffHash;
+    if (!sameSnapshot) {
+      break;
+    }
+    const candidateValidity = resolveCheckpointValidity(candidate);
+    if (candidateValidity === 'valid' || candidateValidity === 'invalid') {
+      return candidate;
+    }
+  }
+
+  return latest;
+}
+
+export function readCheckpointValidity(
+  frontMatter: Record<string, unknown>,
+): ParsedCheckpointValidity {
+  return resolveCheckpointValidity(readLatestCheckpoint(frontMatter));
+}
+
+export function readGateEvidenceByMode(
+  contextOrMap: unknown,
+): Record<string, ParsedGateEvidenceSummary | null> {
+  const context = asRecord(contextOrMap);
+  if (!context) {
+    return {};
+  }
+
+  const explicitMap = asRecord(context.gate_evidence_by_mode);
+  if (!explicitMap) {
+    return {};
+  }
+
+  const normalized: Record<string, ParsedGateEvidenceSummary | null> = {};
+  for (const [mode, value] of Object.entries(explicitMap)) {
+    normalized[mode] = parseGateEvidence(value);
+  }
+  return normalized;
+}
+
+export function parseGateEvidence(value: unknown): ParsedGateEvidenceSummary | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const validity = asString(record.input_worktree_validity);
+  return {
+    mode: asString(record.mode),
+    overall: asString(record.overall),
+    inputDiffHash: asString(record.input_diff_hash),
+    inputCheckpointId: asString(record.input_checkpoint_id),
+    inputHeadSha: asString(record.input_head_sha),
+    inputWorkspaceFingerprint: asString(record.input_workspace_fingerprint),
+    inputWorktreeValidity: validity === 'valid' || validity === 'invalid' ? validity : 'unknown',
+    finishedAt: asString(record.finished_at),
+  };
+}
+
+export function hasMaterialWorktreeDiffHash(diffHash: string | null): boolean {
+  return (
+    typeof diffHash === 'string' && diffHash.length > 0 && diffHash !== EMPTY_WORKTREE_DIFF_HASH
+  );
+}
+
+export function assessGateFreshness(input: {
+  frontMatter: Record<string, unknown>;
+  mode: string;
+  gateEvidenceByMode?: Record<string, ParsedGateEvidenceSummary | null> | null;
+  latestEvidence?: unknown;
+}): GateFreshnessAssessment {
+  const latestCheckpoint = readLatestCheckpoint(input.frontMatter);
+  const checkpoint = readLatestEffectiveCheckpoint(input.frontMatter);
+  const latestCheckpointValidity = resolveCheckpointValidity(latestCheckpoint);
+  const checkpointValidity = resolveCheckpointValidity(checkpoint);
+  const currentDiffHash = checkpoint?.diffHash ?? latestCheckpoint?.diffHash ?? null;
+  const currentWorkspaceFingerprint =
+    checkpoint?.workspaceFingerprint ?? latestCheckpoint?.workspaceFingerprint ?? null;
+  const evidenceFromModeMap = input.gateEvidenceByMode?.[input.mode] ?? null;
+  const latestEvidence = parseGateEvidence(input.latestEvidence);
+  const gateEvidence =
+    evidenceFromModeMap ?? (latestEvidence?.mode === input.mode ? latestEvidence : null);
+
+  const reasons: string[] = [];
+  if (!latestCheckpoint) {
+    reasons.push('checkpoint_missing');
+  } else if (
+    latestCheckpointValidity === 'skipped' &&
+    checkpoint &&
+    checkpointValidity !== 'skipped'
+  ) {
+    reasons.push(`checkpoint_effective_${checkpoint.validationStatus}`);
+  } else if (checkpointValidity === 'invalid') {
+    reasons.push('checkpoint_invalid');
+  } else if (
+    latestCheckpoint.validationStatus === 'invalid' &&
+    latestCheckpointValidity === 'skipped'
+  ) {
+    reasons.push('checkpoint_invalid_nonblocking');
+  } else if (latestCheckpointValidity === 'skipped') {
+    reasons.push('checkpoint_skipped');
+  }
+
+  if (!gateEvidence) {
+    const shouldRerunGate = checkpointAllowsGateRerun(checkpoint) && currentDiffHash !== null;
+    if (shouldRerunGate) {
+      reasons.push(`gate_evidence_missing:${input.mode}`);
+    }
+    return {
+      mode: input.mode,
+      checkpoint,
+      checkpointValidity,
+      gateEvidence: null,
+      freshness: 'missing',
+      shouldRerunGate,
+      currentDiffHash,
+      latestGateOverall: null,
+      reasons,
+    };
+  }
+
+  if (currentDiffHash === null) {
+    reasons.push('checkpoint_diff_hash_missing');
+    return {
+      mode: input.mode,
+      checkpoint,
+      checkpointValidity,
+      gateEvidence,
+      freshness: 'unknown',
+      shouldRerunGate: false,
+      currentDiffHash,
+      latestGateOverall: gateEvidence.overall,
+      reasons,
+    };
+  }
+
+  if (!gateEvidence.inputDiffHash) {
+    const shouldRerunGate = checkpointAllowsGateRerun(checkpoint);
+    if (shouldRerunGate) {
+      reasons.push(`gate_evidence_unscoped:${input.mode}`);
+    }
+    return {
+      mode: input.mode,
+      checkpoint,
+      checkpointValidity,
+      gateEvidence,
+      freshness: 'stale',
+      shouldRerunGate,
+      currentDiffHash,
+      latestGateOverall: gateEvidence.overall,
+      reasons,
+    };
+  }
+
+  if (
+    currentWorkspaceFingerprint &&
+    gateEvidence.inputWorkspaceFingerprint &&
+    gateEvidence.inputWorkspaceFingerprint === currentWorkspaceFingerprint
+  ) {
+    reasons.push(`gate_evidence_current:${input.mode}`);
+    return {
+      mode: input.mode,
+      checkpoint,
+      checkpointValidity,
+      gateEvidence,
+      freshness: 'current',
+      shouldRerunGate: false,
+      currentDiffHash,
+      latestGateOverall: gateEvidence.overall,
+      reasons,
+    };
+  }
+
+  if (gateEvidence.inputDiffHash === currentDiffHash) {
+    reasons.push(`gate_evidence_current:${input.mode}`);
+    return {
+      mode: input.mode,
+      checkpoint,
+      checkpointValidity,
+      gateEvidence,
+      freshness: 'current',
+      shouldRerunGate: false,
+      currentDiffHash,
+      latestGateOverall: gateEvidence.overall,
+      reasons,
+    };
+  }
+
+  const shouldRerunGate = checkpointAllowsGateRerun(checkpoint);
+  reasons.push(`gate_evidence_stale:${input.mode}`);
+  return {
+    mode: input.mode,
+    checkpoint,
+    checkpointValidity,
+    gateEvidence,
+    freshness: 'stale',
+    shouldRerunGate,
+    currentDiffHash,
+    latestGateOverall: gateEvidence.overall,
+    reasons,
+  };
+}