agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/supervisor/planning-wave-executor.ts

@@ -1,6 +1,22 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { STATUS, TOOLS } from '../core/constants.js';
 import { ERROR_CODES } from '../core/error-codes.js';
+import {
+  normalizeManifestConfidence,
+  obligationsMeetConfidenceThreshold,
+  validatePlanTraceAgainstObligationIds,
+  type PlanTraceContractValidation,
+} from '../core/intake-artifacts.js';
+import type { FeatureStatePayload } from '../core/tool-caller.js';
+import {
+  assessGateFreshness,
+  readCheckpointValidity,
+  readGateEvidenceByMode,
+} from '../core/gate-freshness.js';
+import { extractGateLog, type GateLogExtraction } from '../core/gate-log-extractor.js';
 import type { FeatureContextPayload, InitialPlanGenerator, SupervisorToolCaller } from './types.js';
+import { resolvePlannerPhaseFromContext } from './planner-phase.js';
 import {
   NOOP_WORKER_DECISION_RUNNER,
   type WorkerDecisionResult,
@@ -21,6 +37,9 @@ type AnyRecord = Record<string, unknown>;
 interface PlanningWaveExecutorDependencies {
   toolCaller: SupervisorToolCaller;
   planGenerator: InitialPlanGenerator;
+  plannerSessionSync?: {
+    syncPlannerSessions(featureIds: string[]): Promise<void>;
+  };
   workerDecisionRunner?: WorkerDecisionRunner;
   providerMode?: WorkerProviderMode;
   outputLoopDetector?: OutputLoopDetector;
@@ -35,10 +54,22 @@ interface PlanningWaveExecutorDependencies {
   runId?: string | (() => string);
   providerName?: string;
   modelName?: string;
+  safeCheckpointHook?: () => Promise<void>;
+  getPolicySnapshot?: () => Record<string, unknown>;
 }
 
 interface ReconciliationDecision {
-  action: 'update' | 'no_update';
+  planDecision: 'update_required' | 'unchanged';
+  executionDisposition:
+    | 'converged'
+    | 'retry_build'
+    | 'retry_qa'
+    | 'rerun_fast_gate'
+    | 'rerun_full_gate'
+    | 'blocked_checkpoint_invalid'
+    | 'blocked_provider_failure'
+    | 'blocked_stale_evidence'
+    | 'blocked_other';
   reasons: string[];
   acceptanceCriteriaAdditions: string[];
   edgeCaseChecklist: string[];
@@ -48,6 +79,10 @@ interface ReconciliationDecision {
     running: number;
   };
   latestGateOverall: string | null;
+  gateEvidenceFreshness: string;
+  checkpointValidity: string;
+  gateFailureContext: Record<string, unknown> | null;
+  planTraceContract: PlanTraceContractValidation | null;
 }
 
 function asRecord(value: unknown): AnyRecord {
@@ -85,6 +120,14 @@ function normalizeList(values: string[]): string[] {
   return normalized;
 }
 
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
 function readCount(summary: AnyRecord, key: string): number {
   const raw = summary[key];
   if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
@@ -97,6 +140,53 @@ function readStatus(value: unknown): string {
   return typeof value === 'string' ? value : 'unknown';
 }
 
+function readVerifiedManifestObligations(context: FeatureContextPayload): AnyRecord[] {
+  const intake = asRecord(context.intake);
+  const verifiedManifest = asRecord(intake.verified_manifest);
+  return Array.isArray(verifiedManifest.obligations)
+    ? verifiedManifest.obligations.map((item) => asRecord(item))
+    : [];
+}
+
+function readVerifiedManifestObligationIds(context: FeatureContextPayload): string[] {
+  const obligations = readVerifiedManifestObligations(context);
+  return normalizeList(
+    obligations
+      .map((item) => asString(item.obligation_id))
+      .filter((item): item is string => item !== null),
+  );
+}
+
+function readPlanTraceContractValidation(
+  context: FeatureContextPayload,
+  plan: AnyRecord,
+): PlanTraceContractValidation | null {
+  const verifiedObligationIds = readVerifiedManifestObligationIds(context);
+  if (verifiedObligationIds.length === 0) {
+    return null;
+  }
+  return validatePlanTraceAgainstObligationIds(plan, verifiedObligationIds);
+}
+
+function hasInvalidPlanTraceContract(
+  validation: PlanTraceContractValidation | null,
+): validation is PlanTraceContractValidation {
+  return validation !== null && !validation.valid;
+}
+
+interface IntakeRecoveryAmbiguity {
+  id: string;
+  summary: string;
+  obligationIds: string[];
+}
+
+interface IntakeRecoveryAnswer {
+  questionId: string;
+  ambiguityIds: string[];
+  answer: string;
+  answeredAt: string | null;
+}
+
 function deriveEdgeCaseChecklist(specText: string): string[] {
   const checklist = [
     'Edge-case: boundary values and size limits are covered.',
@@ -121,6 +211,39 @@ function deriveEdgeCaseChecklist(specText: string): string[] {
   return normalizeList(checklist);
 }
 
+function deriveEdgeCaseChecklistFromVerifiedManifest(obligations: AnyRecord[]): string[] {
+  const checklist: string[] = [];
+  const kinds = new Set(
+    obligations
+      .map((obligation) => asString(obligation.kind))
+      .filter((item): item is string => item !== null),
+  );
+  const verificationHints = new Set(
+    obligations
+      .map((obligation) => asString(obligation.verification_hint))
+      .filter((item): item is string => item !== null),
+  );
+
+  if (kinds.has('artifact') || kinds.has('workflow') || kinds.has('behavior')) {
+    checklist.push(
+      'Verified workflow and artifact obligations cover boundary values and phase transitions.',
+    );
+  }
+  if (kinds.has('endpoint') || kinds.has('contract')) {
+    checklist.push(
+      'Verified endpoint and contract obligations cover payload validation and negative-path handling.',
+    );
+  }
+  if (kinds.has('integration')) {
+    checklist.push('Verified integration obligations cover dependency failure and retry behavior.');
+  }
+  if (verificationHints.has('required') || kinds.has('verification')) {
+    checklist.push('Required verified-manifest obligations have explicit verification coverage.');
+  }
+
+  return normalizeList(checklist);
+}
+
 function readPlanVersion(plan: AnyRecord): number | null {
   const raw = plan.plan_version;
   if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
@@ -129,6 +252,14 @@ function readPlanVersion(plan: AnyRecord): number | null {
   return Math.floor(raw);
 }
 
+function readStateVersion(frontMatter: AnyRecord): number | null {
+  const raw = frontMatter.version;
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
+    return null;
+  }
+  return Math.floor(raw);
+}
+
 function isPostQaStatus(status: string): boolean {
   return status === STATUS.QA || status === STATUS.READY_TO_MERGE || status === STATUS.BLOCKED;
 }
@@ -143,9 +274,19 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
  * @fileoverview Planning phase wave executor.
  */
 
+/**
+ * Executes the planning phase for one supervisor iteration wave.
+ * Handles intake verification, plan generation, worker decision dispatch,
+ * and post-QA reconciliation of accepted plans.
+ */
 export class PlanningWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly planGenerator: InitialPlanGenerator;
+  private readonly plannerSessionSync:
+    | {
+        syncPlannerSessions(featureIds: string[]): Promise<void>;
+      }
+    | undefined;
   private readonly workerDecisionRunner: WorkerDecisionRunner;
   private readonly providerMode: WorkerProviderMode;
   private readonly outputLoopDetector: OutputLoopDetector | undefined;
@@ -160,12 +301,15 @@ export class PlanningWaveExecutor {
   private readonly runId: string | (() => string) | null;
   private readonly providerName: string;
   private readonly modelName: string;
+  private readonly safeCheckpointHook: (() => Promise<void>) | undefined;
+  private readonly getPolicySnapshot: (() => Record<string, unknown>) | undefined;
   private readonly noProgressByFeature = new Map<string, number>();
   private readonly lastStatusByFeature = new Map<string, string>();
 
   constructor(dependencies: PlanningWaveExecutorDependencies) {
     this.toolCaller = dependencies.toolCaller;
     this.planGenerator = dependencies.planGenerator;
+    this.plannerSessionSync = dependencies.plannerSessionSync;
     this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
     this.providerMode = dependencies.providerMode ?? 'stub';
     this.outputLoopDetector = dependencies.outputLoopDetector;
@@ -183,78 +327,262 @@ export class PlanningWaveExecutor {
     this.runId = dependencies.runId ?? null;
     this.providerName = dependencies.providerName ?? 'unknown';
     this.modelName = dependencies.modelName ?? 'unknown';
+    this.safeCheckpointHook = dependencies.safeCheckpointHook;
+    this.getPolicySnapshot = dependencies.getPolicySnapshot;
   }
 
+  /**
+   * Runs a single planning wave: resolves planner phase (intake vs. planning), invokes workers,
+   * normalizes accepted plan state, and falls back to stub plan generation when not in live mode.
+   * @param featureIds Feature IDs eligible for planning in this wave.
+   */
   async run(featureIds: string[]): Promise<void> {
+    await this.plannerSessionSync?.syncPlannerSessions(featureIds);
     for (const featureId of featureIds) {
-      const context = await this.toolCaller.callTool<FeatureContextPayload>(
-        'planner',
-        TOOLS.FEATURE_GET_CONTEXT,
-        {
-          feature_id: featureId,
-        },
-      );
+      try {
+        const context = await this.toolCaller.callTool<FeatureContextPayload>(
+          'planner',
+          TOOLS.FEATURE_GET_CONTEXT,
+          {
+            feature_id: featureId,
+          },
+        );
 
-      const state = context.data.state.front_matter;
-      const previousStatus = this.lastStatusByFeature.get(featureId);
-      if (previousStatus === STATUS.BLOCKED && state.status === STATUS.PLANNING) {
-        this.noProgressByFeature.delete(featureId);
-        this.outputLoopDetector?.reset(featureId);
-      }
-      this.lastStatusByFeature.set(featureId, state.status);
-      if (state.status !== STATUS.PLANNING && state.status !== STATUS.BLOCKED) {
-        continue;
-      }
+        const state = context.data.state.front_matter;
+        const plannerPhase = resolvePlannerPhaseFromContext(context.data);
+        const previousStatus = this.lastStatusByFeature.get(featureId);
+        if (previousStatus === STATUS.BLOCKED && state.status === STATUS.PLANNING) {
+          this.noProgressByFeature.delete(featureId);
+          this.outputLoopDetector?.reset(featureId);
+        }
+        this.lastStatusByFeature.set(featureId, state.status);
+        if (
+          state.status !== STATUS.INTAKE &&
+          state.status !== STATUS.PLANNING &&
+          state.status !== STATUS.BLOCKED
+        ) {
+          continue;
+        }
 
-      const existingPlan = context.data.plan;
-      let decision: WorkerDecisionResult;
-      try {
-        decision = await this.workerDecisionRunner.execute({
-          role: 'planner',
-          featureId,
-          contextBundle: asRecord(context.data),
-          instructions:
-            'Review feature context and emit PLAN_SUBMISSION/REQUEST/NOTE outputs to advance planning deterministically.',
-        });
-      } catch (error) {
-        const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId);
-        if (handledRuntimeFailure) {
+        const existingPlan = asRecord(context.data.plan);
+        const planTraceContract = readPlanTraceContractValidation(context.data, existingPlan);
+        if (
+          await this.normalizeAcceptedPlanState(
+            featureId,
+            asRecord(state),
+            existingPlan,
+            planTraceContract,
+          )
+        ) {
           continue;
         }
-        throw error;
-      }
+        if (
+          state.status === STATUS.BLOCKED &&
+          plannerPhase === 'planning' &&
+          readPlanVersion(existingPlan) !== null &&
+          !hasInvalidPlanTraceContract(planTraceContract)
+        ) {
+          continue;
+        }
+        let decision: WorkerDecisionResult;
+        try {
+          decision = await this.workerDecisionRunner.execute({
+            role: 'planner',
+            featureId,
+            contextBundle: asRecord(context.data),
+            instructions: this.instructionsForPlannerState(asRecord(context.data)),
+          });
+        } catch (error) {
+          const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId);
+          if (handledRuntimeFailure) {
+            continue;
+          }
+          throw error;
+        }
 
-      const loopStalled = await this.enforceOutputLoopPolicy(featureId, decision);
-      if (loopStalled) {
-        continue;
-      }
+        const loopStalled = await this.enforceOutputLoopPolicy(featureId, decision);
+        if (loopStalled) {
+          continue;
+        }
 
-      const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
-      if (shouldSkip) {
-        continue;
-      }
+        if (decision.questionRequested) {
+          this.noProgressByFeature.delete(featureId);
+          continue;
+        }
+        if (decision.intakeSubmission) {
+          this.noProgressByFeature.delete(featureId);
+          continue;
+        }
 
-      if (decision.planSubmission || existingPlan) {
-        continue;
-      }
+        const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
+        if (shouldSkip) {
+          continue;
+        }
 
-      if (this.providerMode === 'stub') {
-        const plan = await this.planGenerator.generateInitialPlan(featureId);
-        await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
-          feature_id: featureId,
-          plan_json: plan,
-        });
+        if (
+          decision.planSubmission ||
+          (readPlanVersion(existingPlan) !== null &&
+            !hasInvalidPlanTraceContract(planTraceContract))
+        ) {
+          continue;
+        }
+
+        if (this.providerMode === 'stub') {
+          if (plannerPhase === 'intake') {
+            const intake = asRecord(asRecord(context.data).intake);
+            const verifiedManifest = asRecord(intake.verified_manifest);
+            const bootstrapManifest = asRecord(intake.bootstrap_manifest);
+            if (
+              Object.keys(verifiedManifest).length === 0 &&
+              this.policyAllowsStubAutoPromotion(bootstrapManifest)
+            ) {
+              await this.toolCaller.callTool('planner', TOOLS.FEATURE_INTAKE_SUBMIT, {
+                feature_id: featureId,
+                intake_submission: {
+                  verified_manifest: {
+                    ...bootstrapManifest,
+                    artifact_type: 'verified',
+                    verification_basis: 'policy_approved_auto_promotion',
+                    verified_at: new Date().toISOString(),
+                    source_bootstrap_version:
+                      typeof bootstrapManifest.manifest_version === 'number'
+                        ? bootstrapManifest.manifest_version
+                        : null,
+                  },
+                  open_ambiguities: [],
+                  resolved_ambiguities: [],
+                  requires_user_input: false,
+                },
+              });
+              continue;
+            }
+            if (Object.keys(verifiedManifest).length === 0) {
+              continue;
+            }
+          }
+          const plan = await this.planGenerator.generateInitialPlan(featureId);
+          await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
+            feature_id: featureId,
+            plan_json: plan,
+          });
+        }
+      } finally {
+        if (this.safeCheckpointHook) {
+          await this.safeCheckpointHook();
+        }
       }
     }
   }
 
+  /**
+   * Clears all per-feature tracking state (progress counters, status cache, loop detector).
+   * Called when a feature is removed from the active execution set.
+   * @param featureId The feature whose tracking data should be purged.
+   */
   clearFeatureTracking(featureId: string): void {
     this.noProgressByFeature.delete(featureId);
     this.lastStatusByFeature.delete(featureId);
     this.outputLoopDetector?.delete(featureId);
   }
 
+  private instructionsForPlannerState(contextBundle: AnyRecord): string {
+    if (resolvePlannerPhaseFromContext(contextBundle) === 'intake') {
+      return [
+        'Review spec.md, the bootstrap manifest, verified manifest state, and intake review artifacts.',
+        'In intake mode, form or verify the requirements contract before execution planning begins.',
+        'Emit INTAKE_SUBMISSION when the verified manifest is ready.',
+        'Emit REQUEST action=ask_user_input only for blocking requirement clarification.',
+        'If you emit ask_user_input, stop there for the turn and wait for the persisted human answer before promoting intake.',
+        'Do not emit PLAN_SUBMISSION while the feature remains in intake.',
+      ].join(' ');
+    }
+    return 'Review the feature artifacts on disk, update plan.md so it reflects the current planning state and step-by-step implementation plan, and emit PLAN_SUBMISSION/REQUEST/NOTE outputs to advance planning.';
+  }
+
+  private policyAllowsStubAutoPromotion(bootstrapManifest: AnyRecord): boolean {
+    if (Object.keys(bootstrapManifest).length === 0) {
+      return false;
+    }
+    const planning = asRecord(this.getPolicySnapshot?.().planning);
+    const intake = asRecord(planning.intake);
+    if (intake.allow_auto_promotion !== true) {
+      return false;
+    }
+    const ambiguities = Array.isArray(bootstrapManifest.ambiguities)
+      ? bootstrapManifest.ambiguities
+      : [];
+    if (ambiguities.length > 0) {
+      return false;
+    }
+    const minimumConfidence =
+      normalizeManifestConfidence(intake.auto_promotion_min_confidence) ?? 'high';
+    const obligations = Array.isArray(bootstrapManifest.obligations)
+      ? bootstrapManifest.obligations.map((item) => asRecord(item))
+      : [];
+    return obligationsMeetConfidenceThreshold(
+      obligations
+        .map((obligation) => normalizeManifestConfidence(obligation.confidence))
+        .filter((confidence): confidence is 'high' | 'medium' | 'low' => confidence !== null)
+        .map((confidence) => ({ confidence })),
+      minimumConfidence,
+    );
+  }
+
+  private async normalizeAcceptedPlanState(
+    featureId: string,
+    frontMatter: AnyRecord,
+    plan: AnyRecord,
+    planTraceContract: PlanTraceContractValidation | null = null,
+  ): Promise<boolean> {
+    const planVersion = readPlanVersion(plan);
+    if (planVersion == null || hasInvalidPlanTraceContract(planTraceContract)) {
+      return false;
+    }
+
+    const status = readStatus(frontMatter.status);
+    const gates = asRecord(frontMatter.gates);
+    const needsStatusHeal = status === STATUS.PLANNING;
+    const needsPlanGateHeal = gates.plan !== 'pass';
+    if (!needsStatusHeal && !needsPlanGateHeal) {
+      return false;
+    }
+
+    const expectedVersion = readStateVersion(frontMatter);
+    if (expectedVersion == null) {
+      return false;
+    }
+
+    const nextFrontMatter: AnyRecord = {
+      gates: {
+        ...gates,
+        plan: 'pass',
+      },
+    };
+    if (needsStatusHeal) {
+      nextFrontMatter.status = STATUS.BUILDING;
+    }
+
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: featureId,
+      expected_version: expectedVersion,
+      patch: {
+        front_matter: nextFrontMatter,
+      },
+    });
+
+    this.lastStatusByFeature.set(featureId, needsStatusHeal ? STATUS.BUILDING : status);
+    return true;
+  }
+
+  /**
+   * Reconciles accepted plans against QA/gate findings after the QA wave completes.
+   * Evaluates gate freshness, plan-trace contract validity, and QA test summaries,
+   * then emits plan updates or invokes the planner worker for revisions when needed.
+   * @param featureIds Feature IDs in post-QA status to reconcile.
+   * @param iteration Current supervisor iteration number (used for decision logging).
+   */
   async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<void> {
+    await this.plannerSessionSync?.syncPlannerSessions(featureIds);
     for (const featureId of featureIds) {
       const context = await this.toolCaller.callTool<FeatureContextPayload>(
         'planner',
@@ -269,13 +597,17 @@ export class PlanningWaveExecutor {
       if (!isPostQaStatus(status)) {
         continue;
       }
+      if (status === STATUS.BLOCKED && resolvePlannerPhaseFromContext(context.data) === 'intake') {
+        continue;
+      }
 
       const existingPlan = asRecord(context.data.plan);
       if (Object.keys(existingPlan).length === 0) {
         await this.appendDecisionLog(featureId, {
           phase: 'post_qa_reconciliation',
           iteration,
-          decision: 'no_update',
+          plan_decision: 'unchanged',
+          execution_disposition: 'blocked_other',
           reasons: ['missing_plan'],
           status,
         });
@@ -287,24 +619,118 @@ export class PlanningWaveExecutor {
         await this.appendDecisionLog(featureId, {
           phase: 'post_qa_reconciliation',
           iteration,
-          decision: 'no_update',
+          plan_decision: 'unchanged',
+          execution_disposition: 'blocked_other',
           reasons: ['existing_plan_version_invalid'],
           status,
         });
         continue;
       }
 
-      const decision = this.evaluateReconciliationDecision(context.data, existingPlan, status);
-      if (decision.action === 'no_update') {
+      const decision = await this.evaluateReconciliationDecision(
+        context.data,
+        existingPlan,
+        status,
+      );
+      if (this.shouldInvokePlannerForPlanTraceContract(decision)) {
+        const plannerDecision = await this.workerDecisionRunner.execute({
+          role: 'planner',
+          featureId,
+          contextBundle: {
+            ...asRecord(context.data),
+            plan_trace_contract: structuredClone(decision.planTraceContract),
+          },
+          instructions:
+            'The accepted plan_trace no longer matches the verified manifest contract. Review plan_trace_contract, revise the accepted plan so every verified manifest obligation is correctly traced, remove obsolete obligation mappings, and emit PLAN_SUBMISSION or REQUEST.action=amend_plan. Do not leave the stale plan_trace unchanged.',
+        });
+
+        await this.appendDecisionLog(featureId, {
+          phase: 'post_qa_reconciliation',
+          iteration,
+          plan_decision:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? 'update_required'
+              : 'unchanged',
+          execution_disposition:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? 'retry_build'
+              : decision.executionDisposition,
+          status,
+          reasons:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? normalizeList([
+                  ...decision.reasons,
+                  'planner_verified_manifest_trace_revision_requested',
+                ])
+              : decision.reasons,
+          qa_summary: decision.qaSummary,
+          latest_gate_overall: decision.latestGateOverall,
+          gate_evidence_freshness: decision.gateEvidenceFreshness,
+          checkpoint_validity: decision.checkpointValidity,
+          gate_failure_context: decision.gateFailureContext,
+          edge_case_checklist: decision.edgeCaseChecklist,
+          plan_trace_contract: decision.planTraceContract,
+        });
+
+        continue;
+      }
+      if (this.shouldInvokePlannerForGateFailure(decision)) {
+        const plannerDecision = await this.workerDecisionRunner.execute({
+          role: 'planner',
+          featureId,
+          contextBundle: {
+            ...asRecord(context.data),
+            gate_failure_context: structuredClone(decision.gateFailureContext),
+          },
+          instructions:
+            'A required gate is currently failing with fresh evidence. Review gate_failure_context, revise the accepted plan as needed so the builder can legally investigate and fix the failure, and emit PLAN_SUBMISSION or REQUEST.action=amend_plan when a plan revision is required.',
+        });
+
         await this.appendDecisionLog(featureId, {
           phase: 'post_qa_reconciliation',
           iteration,
-          decision: 'no_update',
+          plan_decision:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? 'update_required'
+              : 'unchanged',
+          execution_disposition:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? 'retry_build'
+              : decision.executionDisposition,
+          status,
+          reasons:
+            plannerDecision.planSubmission || plannerDecision.requestHandled
+              ? normalizeList([...decision.reasons, 'planner_gate_failure_revision_requested'])
+              : decision.reasons,
+          qa_summary: decision.qaSummary,
+          latest_gate_overall: decision.latestGateOverall,
+          gate_evidence_freshness: decision.gateEvidenceFreshness,
+          checkpoint_validity: decision.checkpointValidity,
+          gate_failure_context: decision.gateFailureContext,
+          edge_case_checklist: decision.edgeCaseChecklist,
+          plan_trace_contract: decision.planTraceContract,
+        });
+
+        if (plannerDecision.planSubmission || plannerDecision.requestHandled) {
+          continue;
+        }
+      }
+
+      if (decision.planDecision === 'unchanged') {
+        await this.appendDecisionLog(featureId, {
+          phase: 'post_qa_reconciliation',
+          iteration,
+          plan_decision: decision.planDecision,
+          execution_disposition: decision.executionDisposition,
           status,
           reasons: decision.reasons,
           qa_summary: decision.qaSummary,
           latest_gate_overall: decision.latestGateOverall,
+          gate_evidence_freshness: decision.gateEvidenceFreshness,
+          checkpoint_validity: decision.checkpointValidity,
+          gate_failure_context: decision.gateFailureContext,
           edge_case_checklist: decision.edgeCaseChecklist,
+          plan_trace_contract: decision.planTraceContract,
         });
         continue;
       }
@@ -319,7 +745,8 @@ export class PlanningWaveExecutor {
       await this.appendDecisionLog(featureId, {
         phase: 'post_qa_reconciliation',
         iteration,
-        decision: 'plan_update',
+        plan_decision: decision.planDecision,
+        execution_disposition: decision.executionDisposition,
         status,
         expected_plan_version: planVersion,
         next_plan_version: nextPlan.plan_version,
@@ -327,20 +754,29 @@ export class PlanningWaveExecutor {
         reasons: decision.reasons,
         qa_summary: decision.qaSummary,
         latest_gate_overall: decision.latestGateOverall,
+        gate_evidence_freshness: decision.gateEvidenceFreshness,
+        checkpoint_validity: decision.checkpointValidity,
+        gate_failure_context: decision.gateFailureContext,
         edge_case_checklist: decision.edgeCaseChecklist,
+        plan_trace_contract: decision.planTraceContract,
       });
     }
   }
 
-  private evaluateReconciliationDecision(
+  private async evaluateReconciliationDecision(
     context: FeatureContextPayload,
     plan: AnyRecord,
     status: string,
-  ): ReconciliationDecision {
+  ): Promise<ReconciliationDecision> {
     const acceptanceCriteria = asStringArray(plan.acceptance_criteria);
     const riskItems = asStringArray(plan.risk);
+    const verifiedObligations = readVerifiedManifestObligations(context);
+    const planTraceContract = readPlanTraceContractValidation(context, plan);
     const specText = typeof context.spec === 'string' ? context.spec : '';
-    const edgeCaseChecklist = deriveEdgeCaseChecklist(specText);
+    const edgeCaseChecklist =
+      verifiedObligations.length > 0
+        ? deriveEdgeCaseChecklistFromVerifiedManifest(verifiedObligations)
+        : deriveEdgeCaseChecklist(specText);
     const qaSummary = asRecord(asRecord(context.qa_test_index).summary);
     const pending = readCount(qaSummary, 'pending');
     const failed = readCount(qaSummary, 'failed');
@@ -349,32 +785,146 @@ export class PlanningWaveExecutor {
       typeof asRecord(context.latest_evidence).overall === 'string'
         ? String(asRecord(context.latest_evidence).overall)
         : null;
+    const frontMatter = asRecord(asRecord(context.state).front_matter);
+    const statusReason =
+      typeof frontMatter.status_reason === 'string' ? frontMatter.status_reason : '';
+    const lastGateMode =
+      typeof asRecord(frontMatter.evidence).last_gate_mode === 'string'
+        ? String(asRecord(frontMatter.evidence).last_gate_mode)
+        : null;
+    const fastFreshness = assessGateFreshness({
+      frontMatter,
+      mode: 'fast',
+      gateEvidenceByMode: readGateEvidenceByMode(context),
+      latestEvidence: context.latest_evidence,
+    });
+    const fullFreshness = assessGateFreshness({
+      frontMatter,
+      mode: 'full',
+      gateEvidenceByMode: readGateEvidenceByMode(context),
+      latestEvidence: context.latest_evidence,
+    });
+    const checkpointValidity = readCheckpointValidity(frontMatter);
+    const gateEvidenceFreshness =
+      lastGateMode === 'full'
+        ? fullFreshness.freshness
+        : status === STATUS.BLOCKED || status === STATUS.BUILDING
+          ? fastFreshness.freshness
+          : fullFreshness.freshness;
+    let executionDisposition: ReconciliationDecision['executionDisposition'] =
+      status === STATUS.READY_TO_MERGE ? 'converged' : 'retry_qa';
+    const gateFailureContext = await this.extractGateFailureContext(context);
 
-    const reasons: string[] = [];
+    const planReasons: string[] = [];
+    const executionReasons: string[] = [];
     const acceptanceCriteriaAdditions: string[] = [];
 
     const missingEdgeCases = edgeCaseChecklist.filter((item) => !riskItems.includes(item));
     if (missingEdgeCases.length > 0) {
-      reasons.push(`edge_case_checklist_missing:${missingEdgeCases.length}`);
+      planReasons.push(`edge_case_checklist_missing:${missingEdgeCases.length}`);
       acceptanceCriteriaAdditions.push(
         'Planner edge-case checklist has been reviewed and incorporated into the execution plan.',
       );
     }
 
+    const planTraceRequiresRevision = hasInvalidPlanTraceContract(planTraceContract);
+    if (planTraceContract?.missing_obligation_ids.length) {
+      planReasons.push(
+        `verified_manifest_trace_missing:${planTraceContract.missing_obligation_ids.length}`,
+      );
+    }
+    if (planTraceContract?.unknown_obligation_ids.length) {
+      planReasons.push(
+        `verified_manifest_trace_unknown:${planTraceContract.unknown_obligation_ids.length}`,
+      );
+    }
+    if (planTraceContract?.duplicate_obligation_ids.length) {
+      planReasons.push(
+        `verified_manifest_trace_duplicate:${planTraceContract.duplicate_obligation_ids.length}`,
+      );
+    }
+    if (planTraceContract?.invalid_mappings.length) {
+      planReasons.push(
+        `verified_manifest_trace_invalid_mapping:${planTraceContract.invalid_mappings.length}`,
+      );
+    }
+    if (planTraceRequiresRevision) {
+      acceptanceCriteriaAdditions.push(
+        'plan_trace maps every verified manifest obligation_id into planned implementation and verification work.',
+      );
+    }
+
     const hasQaSignals =
       status === STATUS.BLOCKED || failed > 0 || pending > 0 || latestGateOverall === 'fail';
     const qaCheckpoint = `Planner reconciliation checkpoint [status=${status};failed=${failed};pending=${pending};latest=${latestGateOverall ?? 'unknown'}]`;
     if (hasQaSignals && !acceptanceCriteria.includes(qaCheckpoint)) {
-      reasons.push(`qa_signals_detected:${status}:failed=${failed}:pending=${pending}`);
+      planReasons.push(`qa_signals_detected:${status}:failed=${failed}:pending=${pending}`);
       acceptanceCriteriaAdditions.push(
         'Reconcile QA/gate findings against plan scope and apply corrective updates before merge.',
       );
       acceptanceCriteriaAdditions.push(qaCheckpoint);
     }
 
+    if (status === STATUS.BLOCKED) {
+      if (statusReason.includes(ERROR_CODES.PROVIDER_OUTPUT_INVALID)) {
+        executionReasons.push('provider_output_invalid');
+        executionDisposition = 'blocked_provider_failure';
+      } else if (
+        lastGateMode === 'full' &&
+        latestGateOverall === 'fail' &&
+        fullFreshness.freshness === 'current'
+      ) {
+        executionDisposition = 'blocked_other';
+      } else if (
+        lastGateMode === 'fast' &&
+        latestGateOverall === 'fail' &&
+        fastFreshness.freshness === 'current'
+      ) {
+        executionDisposition = 'blocked_other';
+      } else if (lastGateMode === 'full' && fullFreshness.shouldRerunGate) {
+        executionReasons.push(...fullFreshness.reasons);
+        executionDisposition =
+          latestGateOverall === 'pass' ? 'rerun_full_gate' : 'blocked_stale_evidence';
+      } else if (fastFreshness.shouldRerunGate) {
+        executionReasons.push(...fastFreshness.reasons);
+        executionDisposition = latestGateOverall === 'pass' ? 'retry_qa' : 'blocked_stale_evidence';
+      } else if (fullFreshness.shouldRerunGate) {
+        executionReasons.push(...fullFreshness.reasons);
+        executionDisposition =
+          latestGateOverall === 'pass' ? 'rerun_full_gate' : 'blocked_stale_evidence';
+      } else if (latestGateOverall === 'fail') {
+        executionDisposition = 'blocked_other';
+      }
+    } else if (status === STATUS.QA) {
+      if (fullFreshness.shouldRerunGate) {
+        executionReasons.push(...fullFreshness.reasons);
+        executionDisposition = 'rerun_full_gate';
+      } else if (failed > 0 || pending > 0 || running > 0) {
+        executionDisposition = 'retry_qa';
+      } else if (latestGateOverall === 'pass' && fullFreshness.freshness === 'current') {
+        executionDisposition = 'converged';
+      }
+    } else if (status === STATUS.READY_TO_MERGE) {
+      if (fullFreshness.shouldRerunGate) {
+        executionReasons.push(...fullFreshness.reasons);
+        executionDisposition = 'rerun_full_gate';
+      } else if (latestGateOverall !== 'pass' || fullFreshness.freshness !== 'current') {
+        executionReasons.push(...fullFreshness.reasons);
+        executionDisposition = 'blocked_stale_evidence';
+      } else {
+        executionDisposition = 'converged';
+      }
+    }
+
+    if (planTraceRequiresRevision && executionDisposition === 'converged') {
+      executionDisposition = 'retry_build';
+    }
+
+    const reasons = normalizeList([...planReasons, ...executionReasons]);
     if (reasons.length === 0) {
       return {
-        action: 'no_update',
+        planDecision: 'unchanged',
+        executionDisposition,
         reasons: ['reconciled_no_gaps'],
         acceptanceCriteriaAdditions: [],
         edgeCaseChecklist,
@@ -384,11 +934,16 @@ export class PlanningWaveExecutor {
           running,
         },
         latestGateOverall,
+        gateEvidenceFreshness,
+        checkpointValidity,
+        gateFailureContext,
+        planTraceContract,
       };
     }
 
     return {
-      action: 'update',
+      planDecision: acceptanceCriteriaAdditions.length > 0 ? 'update_required' : 'unchanged',
+      executionDisposition,
       reasons,
       acceptanceCriteriaAdditions: normalizeList(acceptanceCriteriaAdditions),
       edgeCaseChecklist,
@@ -398,6 +953,10 @@ export class PlanningWaveExecutor {
         running,
       },
       latestGateOverall,
+      gateEvidenceFreshness,
+      checkpointValidity,
+      gateFailureContext,
+      planTraceContract,
     };
   }
 
@@ -421,6 +980,88 @@ export class PlanningWaveExecutor {
     return nextPlan;
   }
 
+  private shouldInvokePlannerForGateFailure(decision: ReconciliationDecision): boolean {
+    return (
+      decision.gateFailureContext !== null &&
+      decision.latestGateOverall === 'fail' &&
+      decision.gateEvidenceFreshness === 'current' &&
+      decision.checkpointValidity !== 'invalid' &&
+      (decision.executionDisposition === 'blocked_other' ||
+        decision.executionDisposition === 'retry_qa')
+    );
+  }
+
+  private shouldInvokePlannerForPlanTraceContract(decision: ReconciliationDecision): boolean {
+    return hasInvalidPlanTraceContract(decision.planTraceContract);
+  }
+
+  private async extractGateFailureContext(
+    context: FeatureContextPayload,
+  ): Promise<Record<string, unknown> | null> {
+    const latestEvidence = asRecord(context.latest_evidence);
+    const stepResultsRaw = Array.isArray(latestEvidence.step_results)
+      ? latestEvidence.step_results
+      : [];
+    const stepResults = (stepResultsRaw as unknown[])
+      .map((item) => asRecord(item))
+      .filter((item): item is AnyRecord => Object.keys(item).length > 0);
+
+    const failingStep =
+      stepResults.find((item) => (asNumber(item.exit_code) ?? 0) !== 0 || item.timeout === true) ??
+      (typeof latestEvidence.overall === 'string' && latestEvidence.overall === 'fail'
+        ? (stepResults[0] ?? null)
+        : null);
+
+    if (!failingStep) {
+      return null;
+    }
+
+    const stepName = asString(failingStep.name) ?? 'unknown';
+    const stepCmd = Array.isArray(failingStep.cmd)
+      ? (failingStep.cmd as unknown[]).map((value) => String(value))
+      : [];
+    const exitCode = asNumber(failingStep.exit_code) ?? 1;
+    const rawLogPath = asString(failingStep.log_path);
+    const notes = Array.isArray(latestEvidence.notes)
+      ? latestEvidence.notes.filter((item): item is string => typeof item === 'string')
+      : [];
+
+    let failureAnalysis: GateLogExtraction | null = null;
+    if (rawLogPath) {
+      const logPath = path.isAbsolute(rawLogPath)
+        ? rawLogPath
+        : this.repoRoot
+          ? path.join(this.repoRoot, rawLogPath)
+          : rawLogPath;
+      try {
+        const logContent = await fs.readFile(logPath, 'utf8');
+        failureAnalysis = extractGateLog({
+          stepName,
+          cmd: stepCmd,
+          exitCode,
+          logContent,
+        });
+      } catch {
+        failureAnalysis = null;
+      }
+    }
+
+    return {
+      gate_name: asString(latestEvidence.mode) ?? 'unknown',
+      step_name: stepName,
+      cmd: stepCmd,
+      exit_code: exitCode,
+      timeout: failingStep.timeout === true,
+      affected_files: failureAnalysis?.affectedFiles ?? [],
+      error_lines: failureAnalysis?.errorLines ?? [],
+      summary_lines: failureAnalysis?.summaryLines ?? [],
+      error_count: failureAnalysis?.errorCount ?? null,
+      log_tail: failureAnalysis?.logTail ?? '',
+      notes,
+      evidence_overall: asString(latestEvidence.overall) ?? null,
+    };
+  }
+
   private async appendDecisionLog(featureId: string, note: AnyRecord): Promise<void> {
     await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
       feature_id: featureId,
@@ -568,6 +1209,10 @@ export class PlanningWaveExecutor {
     decision: {
       invalidOutput: boolean;
       noProgress: boolean;
+      contextStall?: boolean;
+      contextRequestCount?: number;
+      lastContextRequestAt?: string | null;
+      lastContextRequestRole?: string | null;
     },
   ): Promise<boolean> {
     if (this.providerMode !== 'live') {
@@ -575,7 +1220,24 @@ export class PlanningWaveExecutor {
       return false;
     }
 
+    const context = await this.toolCaller.callTool<FeatureContextPayload>(
+      'planner',
+      TOOLS.FEATURE_GET_CONTEXT,
+      {
+        feature_id: featureId,
+      },
+    );
+
     if (decision.invalidOutput) {
+      if (
+        await this.requestIntakeClarificationFallback(
+          featureId,
+          asRecord(context.data),
+          ERROR_CODES.PROVIDER_OUTPUT_INVALID,
+        )
+      ) {
+        return true;
+      }
       await this.applyWorkerPolicyAction(
         featureId,
         this.malformedOutputAction,
@@ -585,6 +1247,75 @@ export class PlanningWaveExecutor {
       return true;
     }
 
+    if (decision.contextStall) {
+      if (
+        await this.requestIntakeClarificationFallback(
+          featureId,
+          asRecord(context.data),
+          ERROR_CODES.PROVIDER_CONTEXT_STALL,
+        )
+      ) {
+        return true;
+      }
+      const state = await this.toolCaller.callTool<FeatureStatePayload>(
+        'orchestrator',
+        TOOLS.FEATURE_STATE_GET,
+        { feature_id: featureId },
+      );
+      const frontMatter = asRecord(state.data.front_matter);
+      const expectedVersion =
+        typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+          ? Math.floor(frontMatter.version)
+          : null;
+      const recovery = this.buildPlannerRecoveryFrontMatter(
+        frontMatter,
+        ERROR_CODES.PROVIDER_CONTEXT_STALL,
+        'planning',
+      );
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: expectedVersion,
+        patch: {
+          front_matter: {
+            status: STATUS.BLOCKED,
+            status_reason: `${ERROR_CODES.PROVIDER_CONTEXT_STALL}: repeated context refresh with no progress`,
+            recovery,
+            context_request_count: decision.contextRequestCount ?? 0,
+            last_context_request_at: decision.lastContextRequestAt ?? null,
+            last_context_request_role: decision.lastContextRequestRole ?? 'planner',
+          },
+        },
+      });
+      this.lastStatusByFeature.set(featureId, STATUS.BLOCKED);
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+        feature_id: featureId,
+        note: JSON.stringify({
+          phase: 'planning',
+          decision: 'blocked',
+          error_code: ERROR_CODES.PROVIDER_CONTEXT_STALL,
+          reason: 'repeated context refresh with no progress',
+          recovery_state: recovery.state,
+          recovery_attempt: recovery.attempt,
+          context_request_count: decision.contextRequestCount ?? 0,
+          last_context_request_at: decision.lastContextRequestAt ?? null,
+          last_context_request_role: decision.lastContextRequestRole ?? 'planner',
+        }),
+      });
+      return true;
+    }
+
+    if (
+      decision.noProgress &&
+      (await this.requestIntakeClarificationFallback(
+        featureId,
+        asRecord(context.data),
+        ERROR_CODES.PROVIDER_NO_PROGRESS,
+      ))
+    ) {
+      this.noProgressByFeature.delete(featureId);
+      return true;
+    }
+
     if (!decision.noProgress) {
       this.noProgressByFeature.delete(featureId);
       return false;
@@ -605,6 +1336,200 @@ export class PlanningWaveExecutor {
     return true;
   }
 
+  private readOpenIntakeAmbiguities(context: AnyRecord): IntakeRecoveryAmbiguity[] {
+    const review = asRecord(asRecord(context.intake).review);
+    const ambiguities = Array.isArray(review.ambiguities) ? review.ambiguities : [];
+    return ambiguities
+      .map((item) => asRecord(item))
+      .filter((item) => asString(item.status) === 'open')
+      .map((item) => ({
+        id: asString(item.id) ?? 'AMB-UNKNOWN',
+        summary: asString(item.summary) ?? 'Clarify the remaining intake ambiguity.',
+        obligationIds: asStringArray(item.obligation_ids),
+      }));
+  }
+
+  private async readAnsweredIntakeAmbiguityIds(featureId: string): Promise<Set<string>> {
+    const response = await this.toolCaller.callTool<{ items?: unknown[] }>(
+      'orchestrator',
+      TOOLS.FEATURE_QUESTION_LIST,
+      {
+        feature_id: featureId,
+        status: 'all',
+      },
+    );
+    const items = Array.isArray(response.data.items) ? response.data.items : [];
+    const ambiguityIds = items
+      .map((item) => asRecord(item))
+      .filter(
+        (item) =>
+          asString(item.status) === 'answered' &&
+          (asString(item.resume_status) === STATUS.INTAKE ||
+            asString(item.resume_phase) === STATUS.INTAKE ||
+            asString(item.phase) === STATUS.INTAKE),
+      )
+      .flatMap((item) => {
+        const details = asRecord(item.details);
+        const direct = asString(details.ambiguity_id);
+        const grouped = asStringArray(details.ambiguity_ids);
+        return direct ? [direct, ...grouped] : grouped;
+      });
+    return new Set(normalizeList(ambiguityIds));
+  }
+
+  private readAnsweredIntakeClarifications(context: AnyRecord): IntakeRecoveryAnswer[] {
+    const review = asRecord(asRecord(context.intake).review);
+    const answers = Array.isArray(review.clarification_answers) ? review.clarification_answers : [];
+    return answers
+      .map((item) => asRecord(item))
+      .filter((item) => asStringArray(item.ambiguity_ids).length > 0)
+      .map((item) => ({
+        questionId: asString(item.question_id) ?? 'unknown',
+        ambiguityIds: asStringArray(item.ambiguity_ids),
+        answer:
+          typeof item.answer === 'string'
+            ? item.answer
+            : JSON.stringify(asRecord(item.answer) ?? {}, null, 2),
+        answeredAt: asString(item.answered_at),
+      }));
+  }
+
+  private buildIntakeClarificationPrompt(
+    ambiguities: IntakeRecoveryAmbiguity[],
+    followUpAmbiguityIds: Set<string>,
+    priorAnswers: IntakeRecoveryAnswer[],
+  ): string {
+    const needsFollowUp = ambiguities.some((ambiguity) => followUpAmbiguityIds.has(ambiguity.id));
+    const intro =
+      needsFollowUp && ambiguities.length === 1
+        ? 'Planning still cannot continue because this intake ambiguity remains unresolved after the previous answer:'
+        : needsFollowUp
+          ? 'Planning still cannot continue because these intake ambiguities remain unresolved after the previous answer:'
+          : ambiguities.length === 1
+            ? 'Planning cannot continue until this remaining intake ambiguity is clarified:'
+            : 'Planning cannot continue until these remaining intake ambiguities are clarified:';
+    const items = ambiguities.map((ambiguity) => `- ${ambiguity.id}: ${ambiguity.summary}`);
+    const priorAnswerLines = ambiguities.flatMap((ambiguity) =>
+      priorAnswers
+        .filter((answer) => answer.ambiguityIds.includes(ambiguity.id))
+        .map(
+          (answer) =>
+            `- ${ambiguity.id} via ${answer.questionId}${
+              answer.answeredAt ? ` at ${answer.answeredAt}` : ''
+            }: ${answer.answer}`,
+        ),
+    );
+    const priorAnswersBlock =
+      priorAnswerLines.length > 0
+        ? `\nPrior answered clarification evidence:\n${priorAnswerLines.join('\n')}\nUse this prior answer evidence. Only ask a narrower follow-up if it is still insufficient to resolve the ambiguity.`
+        : '';
+    return `${intro}\n${items.join('\n')}${priorAnswersBlock}\nRespond in free text and explicitly address each ambiguity ID.`;
+  }
+
+  private async requestIntakeClarificationFallback(
+    featureId: string,
+    context: AnyRecord,
+    recoveryReason: string,
+  ): Promise<boolean> {
+    if (resolvePlannerPhaseFromContext(context) !== 'intake') {
+      return false;
+    }
+
+    const intake = asRecord(context.intake);
+    const verifiedManifest = asRecord(intake.verified_manifest);
+    if (Object.keys(verifiedManifest).length > 0) {
+      return false;
+    }
+
+    const humanInput = asRecord(context.human_input);
+    const openQuestions = Array.isArray(humanInput.open_questions) ? humanInput.open_questions : [];
+    if (openQuestions.length > 0) {
+      return false;
+    }
+
+    const ambiguities = this.readOpenIntakeAmbiguities(context);
+    const answeredAmbiguityIds = await this.readAnsweredIntakeAmbiguityIds(featureId);
+    const priorAnswers = this.readAnsweredIntakeClarifications(context);
+    if (ambiguities.length === 0) {
+      return false;
+    }
+
+    const frontMatter = asRecord(asRecord(context.state).front_matter);
+    const cluster = asRecord(frontMatter.cluster);
+    const question = await this.toolCaller.callTool<{ question_id?: string }>(
+      'orchestrator',
+      TOOLS.FEATURE_QUESTION_CREATE,
+      {
+        feature_id: featureId,
+        role: 'planner',
+        session_id: asString(cluster.planner_session_id) ?? `planner:intake-recovery:${featureId}`,
+        question_type: 'clarification',
+        prompt: this.buildIntakeClarificationPrompt(
+          ambiguities,
+          answeredAmbiguityIds,
+          priorAnswers,
+        ),
+        details: {
+          ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+          obligation_ids: normalizeList(
+            ambiguities.flatMap((ambiguity) => ambiguity.obligationIds),
+          ),
+          prior_answered_ambiguity_ids: ambiguities
+            .filter((ambiguity) => answeredAmbiguityIds.has(ambiguity.id))
+            .map((ambiguity) => ambiguity.id),
+          recovery_reason: recoveryReason,
+          recovery_source: 'planning_wave_executor',
+        },
+        expected_answer: {
+          kind: 'free_text',
+        },
+        blocking: true,
+        phase: STATUS.INTAKE,
+        request_action: 'ask_user_input',
+        resume_status: STATUS.INTAKE,
+        resume_phase: STATUS.INTAKE,
+      },
+    );
+
+    this.noProgressByFeature.delete(featureId);
+    this.lastStatusByFeature.set(featureId, STATUS.AWAITING_INPUT);
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+      feature_id: featureId,
+      note: JSON.stringify({
+        phase: 'planning',
+        action: 'ask_user_input',
+        decision: 'awaiting_input',
+        question_id: asRecord(question.data).question_id ?? null,
+        recovery_reason: recoveryReason,
+        ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+      }),
+    });
+    return true;
+  }
+
+  private buildPlannerRecoveryFrontMatter(
+    frontMatter: AnyRecord,
+    errorCode: string,
+    phase: 'planning',
+  ): AnyRecord {
+    const existingRecovery = asRecord(frontMatter.recovery);
+    const nextAttempt =
+      (typeof existingRecovery.attempt === 'number' && Number.isFinite(existingRecovery.attempt)
+        ? Math.max(0, Math.floor(existingRecovery.attempt))
+        : 0) + 1;
+    const now = new Date().toISOString();
+    return {
+      state: 'retrying',
+      cause: errorCode,
+      role: 'planner',
+      resume_phase: phase,
+      attempt: nextAttempt,
+      run_id: this.resolveRunId(),
+      started_at: asString(existingRecovery.started_at) ?? now,
+      last_attempt_at: now,
+    };
+  }
+
   private async applyWorkerPolicyAction(
     featureId: string,
     action:
@@ -638,6 +1563,7 @@ export class PlanningWaveExecutor {
       typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
         ? Math.floor(frontMatter.version)
         : null;
+    const recovery = this.buildPlannerRecoveryFrontMatter(frontMatter, errorCode, phase);
     await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
       feature_id: featureId,
       expected_version: expectedVersion,
@@ -645,6 +1571,7 @@ export class PlanningWaveExecutor {
         front_matter: {
           status: STATUS.BLOCKED,
           status_reason: `${errorCode}: ${message}`,
+          recovery,
         },
       },
     });
@@ -656,6 +1583,8 @@ export class PlanningWaveExecutor {
         decision: 'blocked',
         error_code: errorCode,
         reason: message,
+        recovery_state: recovery.state,
+        recovery_attempt: recovery.attempt,
       }),
     });
   }