agentic-orchestrator 0.1.28 → 0.2.1

package/dist/apps/control-plane/supervisor/planning-wave-executor.js

@@ -1,5 +1,11 @@
+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, } from '../core/intake-artifacts.js';
+import { assessGateFreshness, readCheckpointValidity, readGateEvidenceByMode, } from '../core/gate-freshness.js';
+import { extractGateLog } from '../core/gate-log-extractor.js';
+import { resolvePlannerPhaseFromContext } from './planner-phase.js';
 import { NOOP_WORKER_DECISION_RUNNER, } from './worker-decision-loop.js';
 import { appendWorkerRuntimeEvent } from './worker-event-journal.js';
 function asRecord(value) {
@@ -34,6 +40,12 @@ function normalizeList(values) {
     }
     return normalized;
 }
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
 function readCount(summary, key) {
     const raw = summary[key];
     if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
@@ -44,6 +56,29 @@ function readCount(summary, key) {
 function readStatus(value) {
     return typeof value === 'string' ? value : 'unknown';
 }
+function readVerifiedManifestObligations(context) {
+    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) {
+    const obligations = readVerifiedManifestObligations(context);
+    return normalizeList(obligations
+        .map((item) => asString(item.obligation_id))
+        .filter((item) => item !== null));
+}
+function readPlanTraceContractValidation(context, plan) {
+    const verifiedObligationIds = readVerifiedManifestObligationIds(context);
+    if (verifiedObligationIds.length === 0) {
+        return null;
+    }
+    return validatePlanTraceAgainstObligationIds(plan, verifiedObligationIds);
+}
+function hasInvalidPlanTraceContract(validation) {
+    return validation !== null && !validation.valid;
+}
 function deriveEdgeCaseChecklist(specText) {
     const checklist = [
         'Edge-case: boundary values and size limits are covered.',
@@ -65,6 +100,28 @@ function deriveEdgeCaseChecklist(specText) {
     }
     return normalizeList(checklist);
 }
+function deriveEdgeCaseChecklistFromVerifiedManifest(obligations) {
+    const checklist = [];
+    const kinds = new Set(obligations
+        .map((obligation) => asString(obligation.kind))
+        .filter((item) => item !== null));
+    const verificationHints = new Set(obligations
+        .map((obligation) => asString(obligation.verification_hint))
+        .filter((item) => 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) {
     const raw = plan.plan_version;
     if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
@@ -72,6 +129,13 @@ function readPlanVersion(plan) {
     }
     return Math.floor(raw);
 }
+function readStateVersion(frontMatter) {
+    const raw = frontMatter.version;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
+        return null;
+    }
+    return Math.floor(raw);
+}
 function isPostQaStatus(status) {
     return status === STATUS.QA || status === STATUS.READY_TO_MERGE || status === STATUS.BLOCKED;
 }
@@ -83,9 +147,15 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set([
 /**
  * @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 {
     toolCaller;
     planGenerator;
+    plannerSessionSync;
     workerDecisionRunner;
     providerMode;
     outputLoopDetector;
@@ -100,11 +170,14 @@ export class PlanningWaveExecutor {
     runId;
     providerName;
     modelName;
+    safeCheckpointHook;
+    getPolicySnapshot;
     noProgressByFeature = new Map();
     lastStatusByFeature = new Map();
     constructor(dependencies) {
         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;
@@ -122,65 +195,217 @@ 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) {
+        await this.plannerSessionSync?.syncPlannerSessions(featureIds);
         for (const featureId of featureIds) {
-            const context = await this.toolCaller.callTool('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 existingPlan = context.data.plan;
-            let decision;
             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.',
+                const context = await this.toolCaller.callTool('planner', TOOLS.FEATURE_GET_CONTEXT, {
+                    feature_id: featureId,
                 });
-            }
-            catch (error) {
-                const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId);
-                if (handledRuntimeFailure) {
+                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;
                 }
-                throw error;
-            }
-            const loopStalled = await this.enforceOutputLoopPolicy(featureId, decision);
-            if (loopStalled) {
-                continue;
-            }
-            const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
-            if (shouldSkip) {
-                continue;
-            }
-            if (decision.planSubmission || existingPlan) {
-                continue;
+                const existingPlan = asRecord(context.data.plan);
+                const planTraceContract = readPlanTraceContractValidation(context.data, existingPlan);
+                if (await this.normalizeAcceptedPlanState(featureId, asRecord(state), existingPlan, planTraceContract)) {
+                    continue;
+                }
+                if (state.status === STATUS.BLOCKED &&
+                    plannerPhase === 'planning' &&
+                    readPlanVersion(existingPlan) !== null &&
+                    !hasInvalidPlanTraceContract(planTraceContract)) {
+                    continue;
+                }
+                let decision;
+                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;
+                }
+                if (decision.questionRequested) {
+                    this.noProgressByFeature.delete(featureId);
+                    continue;
+                }
+                if (decision.intakeSubmission) {
+                    this.noProgressByFeature.delete(featureId);
+                    continue;
+                }
+                const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
+                if (shouldSkip) {
+                    continue;
+                }
+                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,
+                    });
+                }
             }
-            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,
-                });
+            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) {
         this.noProgressByFeature.delete(featureId);
         this.lastStatusByFeature.delete(featureId);
         this.outputLoopDetector?.delete(featureId);
     }
+    instructionsForPlannerState(contextBundle) {
+        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.';
+    }
+    policyAllowsStubAutoPromotion(bootstrapManifest) {
+        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 !== null)
+            .map((confidence) => ({ confidence })), minimumConfidence);
+    }
+    async normalizeAcceptedPlanState(featureId, frontMatter, plan, planTraceContract = null) {
+        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 = {
+            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, iteration) {
+        await this.plannerSessionSync?.syncPlannerSessions(featureIds);
         for (const featureId of featureIds) {
             const context = await this.toolCaller.callTool('planner', TOOLS.FEATURE_GET_CONTEXT, {
                 feature_id: featureId,
@@ -190,12 +415,16 @@ 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,
                 });
@@ -206,23 +435,100 @@ 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,
-                    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_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,
+                    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;
             }
@@ -235,7 +541,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,
@@ -243,15 +550,23 @@ 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,
             });
         }
     }
-    evaluateReconciliationDecision(context, plan, status) {
+    async evaluateReconciliationDecision(context, plan, status) {
         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');
@@ -259,23 +574,128 @@ export class PlanningWaveExecutor {
         const latestGateOverall = typeof asRecord(context.latest_evidence).overall === 'string'
             ? String(asRecord(context.latest_evidence).overall)
             : null;
-        const reasons = [];
+        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 = status === STATUS.READY_TO_MERGE ? 'converged' : 'retry_qa';
+        const gateFailureContext = await this.extractGateFailureContext(context);
+        const planReasons = [];
+        const executionReasons = [];
         const acceptanceCriteriaAdditions = [];
         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,
@@ -285,10 +705,15 @@ 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,
@@ -298,6 +723,10 @@ export class PlanningWaveExecutor {
                 running,
             },
             latestGateOverall,
+            gateEvidenceFreshness,
+            checkpointValidity,
+            gateFailureContext,
+            planTraceContract,
         };
     }
     buildUpdatedPlan(plan, planVersion, decision) {
@@ -314,6 +743,76 @@ export class PlanningWaveExecutor {
         nextPlan.risk = normalizeList([...riskItems, ...decision.edgeCaseChecklist]);
         return nextPlan;
     }
+    shouldInvokePlannerForGateFailure(decision) {
+        return (decision.gateFailureContext !== null &&
+            decision.latestGateOverall === 'fail' &&
+            decision.gateEvidenceFreshness === 'current' &&
+            decision.checkpointValidity !== 'invalid' &&
+            (decision.executionDisposition === 'blocked_other' ||
+                decision.executionDisposition === 'retry_qa'));
+    }
+    shouldInvokePlannerForPlanTraceContract(decision) {
+        return hasInvalidPlanTraceContract(decision.planTraceContract);
+    }
+    async extractGateFailureContext(context) {
+        const latestEvidence = asRecord(context.latest_evidence);
+        const stepResultsRaw = Array.isArray(latestEvidence.step_results)
+            ? latestEvidence.step_results
+            : [];
+        const stepResults = stepResultsRaw
+            .map((item) => asRecord(item))
+            .filter((item) => 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.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) => typeof item === 'string')
+            : [];
+        let failureAnalysis = 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,
+        };
+    }
     async appendDecisionLog(featureId, note) {
         await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
             feature_id: featureId,
@@ -433,10 +932,62 @@ export class PlanningWaveExecutor {
             this.noProgressByFeature.delete(featureId);
             return false;
         }
+        const context = await this.toolCaller.callTool('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, ERROR_CODES.PROVIDER_OUTPUT_INVALID, 'Planner emitted malformed worker outputs');
             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('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;
@@ -449,6 +1000,149 @@ export class PlanningWaveExecutor {
         await this.applyWorkerPolicyAction(featureId, this.noProgressAction, ERROR_CODES.PROVIDER_NO_PROGRESS, `Planner made no actionable progress in ${currentCount} consecutive iterations`);
         return true;
     }
+    readOpenIntakeAmbiguities(context) {
+        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),
+        }));
+    }
+    async readAnsweredIntakeAmbiguityIds(featureId) {
+        const response = await this.toolCaller.callTool('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));
+    }
+    readAnsweredIntakeClarifications(context) {
+        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),
+        }));
+    }
+    buildIntakeClarificationPrompt(ambiguities, followUpAmbiguityIds, priorAnswers) {
+        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.`;
+    }
+    async requestIntakeClarificationFallback(featureId, context, recoveryReason) {
+        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('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;
+    }
+    buildPlannerRecoveryFrontMatter(frontMatter, errorCode, phase) {
+        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,
+        };
+    }
     async applyWorkerPolicyAction(featureId, action, errorCode, message, phase = 'planning') {
         if (action === 'fail_run') {
             const error = new Error(message);
@@ -467,6 +1161,7 @@ export class PlanningWaveExecutor {
         const expectedVersion = 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,
@@ -474,6 +1169,7 @@ export class PlanningWaveExecutor {
                 front_matter: {
                     status: STATUS.BLOCKED,
                     status_reason: `${errorCode}: ${message}`,
+                    recovery,
                 },
             },
         });
@@ -485,6 +1181,8 @@ export class PlanningWaveExecutor {
                 decision: 'blocked',
                 error_code: errorCode,
                 reason: message,
+                recovery_state: recovery.state,
+                recovery_attempt: recovery.attempt,
             }),
         });
     }