codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14.1

package/src/lifecycle/corrective-replan.ts

@@ -0,0 +1,847 @@
+import { createHash } from 'node:crypto';
+import { renderPlan } from '../artifacts.js';
+import type {
+  CorrectiveDecisionEvent,
+  RemediationEvent,
+  StepStatus,
+  TaskPlanInput,
+  TaskState,
+  TaskStatus,
+} from '../contracts.js';
+import { definitionManifestHash, runtimeSemanticFingerprint } from './fingerprint.js';
+import { deepFreeze } from './immutable.js';
+import { evaluateTransition } from './evaluator.js';
+import type {
+  BlockedTransitionNavigation,
+  ExecutableTransitionDefinition,
+  HumanGateTransitionNavigation,
+  TransitionDefinitionMetadata,
+  TransitionEvaluation,
+  TransitionGuard,
+  TransitionGuardMetadata,
+  TransitionGuardPhase,
+  TransitionGuardReasonClass,
+  TransitionGuardResult,
+  TransitionGuardStage,
+} from './types.js';
+import { correctiveReplanBindingManifest } from './corrective-replan-binding-manifest.js';
+import {
+  LIFECYCLE_EPOCH,
+  TRANSITION_DEFINITION_FORMAT_VERSION,
+} from './types.js';
+
+export const TASK_CORRECTIVE_REPLAN_TRANSITION_ID = 'task.plan.corrective-replan' as const;
+
+export interface CorrectiveReplanPosture {
+  readonly posture: string;
+  readonly stepId: string;
+  readonly attemptCount: number;
+  readonly correctiveDecision: CorrectiveDecisionEvent | null;
+}
+
+export function identifyCorrectiveReplanPosture(
+  task: Readonly<TaskState>,
+  guardedStepIds: readonly string[],
+  decisions: readonly CorrectiveDecisionEvent[],
+  remediations: readonly RemediationEvent[],
+): CorrectiveReplanPosture | null {
+  const matches = decisions.filter((decision) =>
+    decision.taskId === task.id
+    && decision.decision === 'replan-required'
+    && decision.planHash === task.planHash
+    && guardedStepIds.includes(decision.stepId));
+  if (matches.length !== 1) return null;
+  const decision = matches[0]!;
+  return {
+    posture: 'replan-required',
+    stepId: decision.stepId,
+    attemptCount: remediations.filter((event) => event.stepId === decision.stepId).length,
+    correctiveDecision: decision,
+  };
+}
+
+export interface PreparedCorrectiveReplanCandidate {
+  readonly planBytes: string;
+  readonly planHash: string;
+  readonly stepIds: readonly string[];
+}
+
+export interface CorrectiveReplanSnapshot {
+  readonly taskId: string;
+  readonly taskRevision: number;
+  readonly taskStatus: TaskStatus;
+  readonly currentPlanHash: string | null;
+  readonly stepId: string;
+  readonly stepStatus: StepStatus | null;
+  readonly inProgressStepIds: readonly string[];
+  readonly remediationAttemptCount: number;
+  readonly correctivePosture: string;
+  readonly correctiveDecision: CorrectiveDecisionEvent | null;
+  readonly candidatePlanHash: string | null;
+  readonly candidateStepIds: readonly string[] | null;
+  readonly actorRoleEligible: boolean;
+  readonly c1ClaimAbsent: boolean;
+  readonly writerLeaseAbsent: boolean;
+  readonly planValidationPassed: boolean;
+  readonly receiptValid: boolean;
+  readonly riskAuditPassed: boolean;
+}
+
+export interface CorrectiveReplanAdmissionFacts {
+  readonly actorRoleEligible: boolean;
+  readonly c1ClaimAbsent: boolean;
+  readonly writerLeaseAbsent: boolean;
+  readonly planValidationPassed: boolean;
+  readonly receiptValid: boolean;
+  readonly riskAuditPassed: boolean;
+}
+
+export interface CorrectiveReplanAvailabilityBindings {
+  readonly taskId: string;
+  readonly expectedRevision: number;
+  readonly currentPlanHash: string;
+  readonly stepId: string;
+  readonly correctiveDecisionEventId: string;
+}
+
+export interface CorrectiveReplanExecutionBindings extends CorrectiveReplanAvailabilityBindings {
+  readonly candidatePlanHash: string;
+  readonly candidateStepIds: readonly string[];
+}
+
+export type CorrectiveReplanBindings =
+  | CorrectiveReplanAvailabilityBindings
+  | CorrectiveReplanExecutionBindings;
+
+const bindingGuardMetadata = guardMetadata(
+  'task.corrective-replan.bindings-current',
+  'Task, revision, Plan, Step, and corrective-decision bindings match the evaluated snapshot.',
+  'availability',
+  'observation',
+  ['field.corrective-decision-event-id', 'field.current-plan-hash', 'field.step-id', 'field.task-id', 'field.task-revision'],
+  ['input.expected-revision', 'input.task-id'],
+  'external-race',
+);
+const sourceGuardMetadata = guardMetadata(
+  'task.corrective-replan.source-posture',
+  'The exact guarded Step is failed and its Task is in a corrective replan source posture.',
+  'availability',
+  'observation',
+  ['field.step-status', 'field.task-status'],
+  [],
+  'lifecycle-blocker',
+);
+const noStepInProgressGuardMetadata = guardMetadata(
+  'task.corrective-replan.no-step-in-progress',
+  'No Step in the Task is in progress while its Plan semantics are being replaced.',
+  'availability',
+  'observation',
+  ['field.in-progress-step-ids'],
+  [],
+  'lifecycle-blocker',
+);
+const decisionGuardMetadata = guardMetadata(
+  'task.corrective-replan.active-decision',
+  'One active replan-required decision is bound to the current Plan and guarded Step.',
+  'availability',
+  'observation',
+  ['field.corrective-decision-decision', 'field.corrective-decision-plan-hash', 'field.corrective-decision-step-id', 'field.corrective-posture'],
+  [],
+  'lifecycle-blocker',
+);
+const attemptGuardMetadata = guardMetadata(
+  'task.corrective-replan.attempt-threshold',
+  'The decision binds a proven first-failure Plan-integrity or rebound planning-obstruction route, or the ordinary two-failure threshold.',
+  'availability',
+  'observation',
+  ['field.corrective-decision-triggering-attempt-count', 'field.remediation-attempt-count'],
+  [],
+  'lifecycle-blocker',
+);
+const semanticPlanChangeGuardMetadata = guardMetadata(
+  'task.corrective-replan.semantic-plan-change',
+  'The rendered candidate Plan has a new content-addressed semantic binding.',
+  'execution',
+  'candidate',
+  ['field.candidate-plan-hash', 'field.current-plan-hash'],
+  ['input.corrective-replacement-plan'],
+  'candidate-blocker',
+);
+const guardedStepRetainedGuardMetadata = guardMetadata(
+  'task.corrective-replan.guarded-step-retained',
+  'The candidate Plan retains the exact guarded Step identity.',
+  'execution',
+  'candidate',
+  ['field.candidate-step-ids', 'field.step-id'],
+  ['input.corrective-replacement-plan'],
+  'candidate-blocker',
+);
+const actorRoleEligibleGuardMetadata = guardMetadata(
+  'task.corrective-replan.actor-role-eligible', 'The receipt-bound actor has an eligible planning/coordinator role.',
+  'execution', 'authority', ['field.actor-role-eligible'], ['input.corrective-execution-receipt'], 'authority-blocker',
+);
+const noC1ClaimGuardMetadata = guardMetadata(
+  'task.corrective-replan.no-c1-claim', 'No C1 claim remains when the exact Task operation lock is acquired.',
+  'execution', 'authority', ['field.c1-claim-absent'], ['input.corrective-execution-receipt'], 'external-race',
+);
+const noWriterLeaseGuardMetadata = guardMetadata(
+  'task.corrective-replan.no-writer-lease', 'No Writer lease remains when the exact Task operation lock is acquired.',
+  'execution', 'authority', ['field.writer-lease-absent'], ['input.corrective-execution-receipt'], 'external-race',
+);
+const planValidationPassedGuardMetadata = guardMetadata(
+  'task.corrective-replan.plan-validation-passed', 'A fresh independent Plan Validation is bound to the replacement candidate.',
+  'execution', 'candidate', ['field.plan-validation-passed'], ['input.corrective-plan-validation'], 'candidate-blocker',
+);
+const receiptValidGuardMetadata = guardMetadata(
+  'task.corrective-replan.receipt-valid', 'The Human-confirmed or explicitly delegated receipt matches every current execution binding.',
+  'execution', 'authority', ['field.receipt-valid'], ['input.corrective-execution-receipt'], 'authority-blocker',
+);
+const riskAuditPassedGuardMetadata = guardMetadata(
+  'task.corrective-replan.risk-audit-passed', 'The replacement Plan Risk Audit is approved and candidate-bound.',
+  'execution', 'candidate', ['field.risk-audit-passed'], ['input.corrective-plan-risk-audit'], 'candidate-blocker',
+);
+
+const guards: readonly TransitionGuard<CorrectiveReplanSnapshot, CorrectiveReplanBindings>[] = [
+  {
+    metadata: bindingGuardMetadata,
+    evaluate(snapshot, bindings) {
+      const decision = snapshot.correctiveDecision;
+      const passed = snapshot.taskId === bindings.taskId
+        && snapshot.taskRevision === bindings.expectedRevision
+        && snapshot.currentPlanHash === bindings.currentPlanHash
+        && snapshot.stepId === bindings.stepId
+        && decision?.eventId === bindings.correctiveDecisionEventId;
+      return verdict(bindingGuardMetadata, passed, 'BINDINGS_STALE', 'Corrective replan bindings no longer match current state.');
+    },
+  },
+  {
+    metadata: sourceGuardMetadata,
+    evaluate(snapshot) {
+      const taskAllowed = ['ready', 'needs_fix', 'blocked', 'awaiting_execution_authorization'].includes(snapshot.taskStatus);
+      const passed = taskAllowed && snapshot.stepStatus === 'failed';
+      return verdict(
+        sourceGuardMetadata,
+        passed,
+        'SOURCE_POSTURE_BLOCKED',
+        `Corrective replan requires the exact guarded Step to be failed; Task is ${snapshot.taskStatus} and Step is ${snapshot.stepStatus ?? 'missing'}.`,
+      );
+    },
+  },
+  {
+    metadata: noStepInProgressGuardMetadata,
+    evaluate(snapshot) {
+      return verdict(
+        noStepInProgressGuardMetadata,
+        snapshot.inProgressStepIds.length === 0,
+        'STEP_IN_PROGRESS',
+        `Corrective replan is blocked while Steps are in progress: ${snapshot.inProgressStepIds.join(', ')}.`,
+      );
+    },
+  },
+  {
+    metadata: decisionGuardMetadata,
+    evaluate(snapshot) {
+      const decision = snapshot.correctiveDecision;
+      const passed = snapshot.correctivePosture === 'replan-required'
+        && decision?.decision === 'replan-required'
+        && decision.stepId === snapshot.stepId
+        && decision.planHash === snapshot.currentPlanHash;
+      return verdict(
+        decisionGuardMetadata,
+        passed,
+        'ACTIVE_REPLAN_DECISION_MISSING',
+        'The exact guarded Step does not have a replan-required decision for the current Plan.',
+      );
+    },
+  },
+  {
+    metadata: attemptGuardMetadata,
+    evaluate(snapshot) {
+      const decision = snapshot.correctiveDecision;
+      const ordinaryThreshold = snapshot.remediationAttemptCount >= 2
+        && decision?.triggeringAttemptCount === snapshot.remediationAttemptCount + 1;
+      const boundedPlanIntegrity = snapshot.remediationAttemptCount === 1
+        && decision?.triggeringAttemptCount === 2
+        && decision.recoveryBasis === 'plan-integrity'
+        && decision.planIntegrityEvidence !== undefined;
+      const boundedPlanningObstruction = snapshot.remediationAttemptCount === 1
+        && decision?.triggeringAttemptCount === 2
+        && decision.recoveryBasis === 'planning-obstruction'
+        && decision.planningObstructionEvidence !== undefined;
+      const passed = ordinaryThreshold || boundedPlanIntegrity || boundedPlanningObstruction;
+      return verdict(
+        attemptGuardMetadata,
+        passed,
+        'ATTEMPT_BINDING_INVALID',
+        'Corrective replan requires one bounded Plan-integrity/planning-obstruction failure or two ordinary failed attempts, with an exact next-ordinal decision.',
+      );
+    },
+  },
+  {
+    metadata: semanticPlanChangeGuardMetadata,
+    evaluate(snapshot, bindings) {
+      const candidateBindings = executionBindings(bindings);
+      const passed = candidateBindings !== null
+        && snapshot.candidatePlanHash !== null
+        && candidateBindings.candidatePlanHash === snapshot.candidatePlanHash
+        && snapshot.currentPlanHash !== snapshot.candidatePlanHash;
+      return verdict(
+        semanticPlanChangeGuardMetadata,
+        passed,
+        'SEMANTIC_PLAN_UNCHANGED',
+        'Corrective replan requires candidate Plan bytes whose semantic hash differs from the current Plan.',
+      );
+    },
+  },
+  {
+    metadata: guardedStepRetainedGuardMetadata,
+    evaluate(snapshot, bindings) {
+      const candidateBindings = executionBindings(bindings);
+      const passed = candidateBindings !== null
+        && snapshot.candidateStepIds !== null
+        && sameStrings(candidateBindings.candidateStepIds, snapshot.candidateStepIds)
+        && snapshot.candidateStepIds.includes(snapshot.stepId);
+      return verdict(
+        guardedStepRetainedGuardMetadata,
+        passed,
+        'GUARDED_STEP_REMOVED',
+        `Candidate Plan must retain guarded Step ${snapshot.stepId}.`,
+      );
+    },
+  },
+  booleanGuard(actorRoleEligibleGuardMetadata, 'actorRoleEligible', 'ROLE_NOT_ELIGIBLE'),
+  booleanGuard(noC1ClaimGuardMetadata, 'c1ClaimAbsent', 'C1_CLAIM_ACTIVE'),
+  booleanGuard(noWriterLeaseGuardMetadata, 'writerLeaseAbsent', 'WRITER_LEASE_ACTIVE'),
+  booleanGuard(planValidationPassedGuardMetadata, 'planValidationPassed', 'PLAN_VALIDATION_REQUIRED'),
+  booleanGuard(receiptValidGuardMetadata, 'receiptValid', 'RECEIPT_INVALID'),
+  booleanGuard(riskAuditPassedGuardMetadata, 'riskAuditPassed', 'RISK_AUDIT_REQUIRED'),
+];
+
+const metadata: TransitionDefinitionMetadata = {
+  definitionFormatVersion: TRANSITION_DEFINITION_FORMAT_VERSION,
+  transitionId: TASK_CORRECTIVE_REPLAN_TRANSITION_ID,
+  guardNamespace: 'task.corrective-replan',
+  lifecycleEpoch: LIFECYCLE_EPOCH,
+  entity: 'task',
+  scope: 'task-step',
+  command: { command: 'task corrective-replan-execute', noun: 'task', action: 'corrective-replan-execute' },
+  sourcePosture: {
+    taskStatuses: ['ready', 'needs_fix', 'blocked', 'awaiting_execution_authorization'],
+    milestoneStatuses: [],
+    stepStatuses: ['failed'],
+    correctivePostures: ['replan-required'],
+  },
+  inputContract: [
+    { input: v1('input.task-id'), phase: 'availability', required: true, sensitivity: 'public' },
+    { input: v1('input.expected-revision'), phase: 'availability', required: true, sensitivity: 'public' },
+    { input: v1('input.corrective-replacement-plan'), phase: 'execution', required: true, sensitivity: 'public' },
+    { input: v1('input.corrective-plan-validation'), phase: 'execution', required: true, sensitivity: 'public' },
+    { input: v1('input.corrective-plan-risk-audit'), phase: 'execution', required: true, sensitivity: 'public' },
+    { input: v1('input.corrective-execution-receipt'), phase: 'execution', required: true, sensitivity: 'public' },
+  ],
+  snapshotContract: v1('projection.corrective-replan.snapshot'),
+  bindingContract: v1('projection.corrective-replan.bindings'),
+  outputContract: [
+    { outputId: 'output.navigation', channel: 'navigation', sensitivity: 'public', required: true },
+    { outputId: 'output.corrective-execution-receipt', channel: 'credential-receipt', sensitivity: 'redacted', required: true },
+    { outputId: 'output.task-state', channel: 'result', sensitivity: 'public', required: true },
+  ],
+  guards: guards.map((guard) => guard.metadata),
+  authority: {
+    eligibleRoles: ['delivery-coordinator', 'technical-planner'],
+    actor: {
+      identity: v1('identity.actor'),
+      principalBasis: v1('principal-basis.bound-corrective-authority'),
+      required: true,
+    },
+    principal: {
+      identity: v1('identity.human-principal'),
+      principalBasis: v1('principal-basis.bound-corrective-authority'),
+      issuer: v1('identity.human-principal'),
+      allowedKinds: ['human', 'delegation-grant'],
+    },
+    capabilities: [{ capability: v1('capability.task.corrective-replan'), source: 'credential', required: true }],
+    credentials: [v1('credential-policy.corrective-execution-receipt')],
+    delegation: v1('delegation.corrective-execution-exact'),
+    ownership: v1('ownership.corrective-replan-clear'),
+    executionBoundaries: ['human', 'coordinator', 'workflow-core'],
+    separationOfDuty: [
+      {
+        constraintId: 'sod.plan-author-plan-validator-distinct', left: v1('identity.plan-author'), right: v1('identity.plan-validator'),
+        relation: 'distinct', missingIdentity: 'block', comparator: v1('identity-comparator.corrective-replan.author-validator'),
+        enforcement: { kind: 'credential-verifier', verifier: v1('credential-verifier.corrective-replan.receipt') },
+      },
+      {
+        constraintId: 'sod.plan-author-risk-auditor-distinct', left: v1('identity.plan-author'), right: v1('identity.risk-auditor'),
+        relation: 'distinct', missingIdentity: 'block', comparator: v1('identity-comparator.corrective-replan.author-risk-auditor'),
+        enforcement: { kind: 'credential-verifier', verifier: v1('credential-verifier.corrective-replan.receipt') },
+      },
+    ],
+    forbiddenCombinations: [{
+      constraintId: 'forbidden.plan-author-human-principal-self-authorize',
+      subjects: [v1('identity.plan-author'), v1('identity.human-principal')], rule: 'cannot-authorize',
+      missingIdentity: 'block', comparator: v1('identity-comparator.corrective-replan.author-human-principal'),
+      enforcement: { kind: 'credential-verifier', verifier: v1('credential-verifier.corrective-replan.receipt') },
+    }],
+  },
+  effects: {
+    graphId: 'effect-graph.task-corrective-replan-journaled',
+    graphVersion: 2,
+    taskStatus: { from: ['ready', 'needs_fix', 'blocked', 'awaiting_execution_authorization'], to: 'awaiting_execution_authorization' },
+    milestoneStatus: { from: [], to: 'preserved' },
+    stepStatus: { from: ['failed'], to: 'input-dependent' },
+    supersession: {
+      executionAuthorization: 'supersede-approved',
+      finalAcceptance: 'preserve',
+      delegationGrants: 'preserve',
+      c1Claim: 'invalidate',
+      writerLease: 'invalidate',
+    },
+    orderedNodes: [
+      {
+        effectId: 'effect.task-state-write',
+        ordinal: 0,
+        adapter: v1('effect-adapter.journaled-corrective-replan'),
+        resource: v1('resource.task-state'),
+        operation: 'write',
+        conditions: [{ kind: 'guard-passed', guardId: 'task.corrective-replan.receipt-valid' }],
+        dependsOn: [],
+      },
+      {
+        effectId: 'effect.plan-artifact-publish',
+        ordinal: 1,
+        adapter: v1('effect-adapter.journaled-corrective-replan'),
+        resource: v1('resource.plan-artifact'),
+        operation: 'publish',
+        conditions: [],
+        dependsOn: ['effect.task-state-write'],
+      },
+      {
+        effectId: 'effect.plan-validation-append',
+        ordinal: 2,
+        adapter: v1('effect-adapter.journaled-corrective-replan'),
+        resource: v1('resource.plan-validation-sidecar'),
+        operation: 'append',
+        conditions: [{ kind: 'input-present', input: v1('input.corrective-plan-validation') }],
+        dependsOn: ['effect.plan-artifact-publish'],
+      },
+      {
+        effectId: 'effect.plan-risk-audit-append',
+        ordinal: 3,
+        adapter: v1('effect-adapter.journaled-corrective-replan'),
+        resource: v1('resource.plan-risk-audit-sidecar'),
+        operation: 'append',
+        conditions: [{ kind: 'input-present', input: v1('input.corrective-plan-risk-audit') }],
+        dependsOn: ['effect.plan-validation-append'],
+      },
+      {
+        effectId: 'effect.corrective-replan-execution-append',
+        ordinal: 4,
+        adapter: v1('effect-adapter.journaled-corrective-replan'),
+        resource: v1('resource.corrective-replan-execution-sidecar'),
+        operation: 'append',
+        conditions: [{ kind: 'input-present', input: v1('input.corrective-execution-receipt') }],
+        dependsOn: ['effect.plan-risk-audit-append'],
+      },
+    ],
+    postconditions: [
+      {
+        postconditionId: 'postcondition.plan-hash-equals-candidate',
+        assertion: 'hash-equals',
+        reads: [
+          slice('projection.corrective-replan.candidate', ['field.candidate-plan-hash']),
+          slice('projection.task-state.readback', ['field.task-plan-hash']),
+        ],
+        effectNodeIds: ['effect.task-state-write', 'effect.plan-artifact-publish'],
+      },
+      {
+        postconditionId: 'postcondition.task-revision-advanced',
+        assertion: 'revision-advanced',
+        reads: [
+          slice('projection.corrective-replan.state', ['field.task-revision']),
+          slice('projection.task-state.readback', ['field.task-revision']),
+        ],
+        effectNodeIds: ['effect.task-state-write'],
+      },
+      {
+        postconditionId: 'postcondition.task-status-awaits-authorization',
+        assertion: 'status-equals',
+        reads: [slice('projection.task-state.readback', ['field.task-status'])],
+        effectNodeIds: ['effect.task-state-write'],
+      },
+      {
+        postconditionId: 'postcondition.plan-validation-appended', assertion: 'event-appended',
+        reads: [slice('projection.corrective-replan.terminal-readback', ['field.plan-validation-hash'])],
+        effectNodeIds: ['effect.plan-validation-append'],
+      },
+      {
+        postconditionId: 'postcondition.plan-risk-audit-appended', assertion: 'event-appended',
+        reads: [slice('projection.corrective-replan.terminal-readback', ['field.risk-audit-hash'])],
+        effectNodeIds: ['effect.plan-risk-audit-append'],
+      },
+      {
+        postconditionId: 'postcondition.execution-evidence-appended', assertion: 'event-appended',
+        reads: [slice('projection.corrective-replan.terminal-readback', ['field.runtime-fingerprint', 'field.catalog-hash'])],
+        effectNodeIds: ['effect.corrective-replan-execution-append'],
+      },
+    ],
+  },
+  admissionBoundary: {
+    lock: {
+      policy: v1('lock-policy.corrective-replan-task-exclusive'),
+      scope: slice('projection.corrective-replan.state', ['field.task-id']),
+    },
+    orderedRevalidations: [
+      { revalidationId: 'revalidation.corrective-replan.state', ordinal: 0, raceId: 'race.corrective-replan.state',
+        guardId: bindingGuardMetadata.guardId, evaluator: bindingGuardMetadata.evaluator,
+        reads: [slice('projection.corrective-replan.state', manifestProjectionFields('projection.corrective-replan.state'))], underLock: true },
+      { revalidationId: 'revalidation.corrective-replan.authority', ordinal: 1, raceId: 'race.corrective-replan.authority',
+        guardId: receiptValidGuardMetadata.guardId, evaluator: receiptValidGuardMetadata.evaluator,
+        reads: [slice('projection.corrective-replan.authority', manifestProjectionFields('projection.corrective-replan.authority'))], underLock: true },
+      { revalidationId: 'revalidation.corrective-replan.protocol', ordinal: 2, raceId: 'race.corrective-replan.protocol',
+        guardId: noWriterLeaseGuardMetadata.guardId, evaluator: noWriterLeaseGuardMetadata.evaluator,
+        reads: [slice('projection.corrective-replan.protocol', manifestProjectionFields('projection.corrective-replan.protocol'))], underLock: true },
+    ],
+    firstEffectAfterRevalidation: true,
+    release: 'finally-after-readback',
+  },
+  atomicity: {
+    classification: 'journaled-multi-write',
+    nonMutatingFailureGuarantee: 'all-guards-before-effects',
+    executionKey: {
+      policy: v1('execution-key-policy.corrective-replan-exact'),
+      fields: correctiveReplanBindingManifest.rows.map(({ projection, fieldId }) => ({ projection, fieldId })),
+      hashPolicy: v1('hash-policy.canonical-json-sha256'),
+    },
+    replay: {
+      identicalCompleted: 'return-recorded-result',
+      identicalInProgress: 'resume-journal',
+      conflicting: 'reject-state-conflict',
+    },
+    journal: {
+      mode: 'required', schema: v1('journal-schema.corrective-replan-task'),
+      adapter: v1('journal-adapter.corrective-replan-task'), digestPolicy: v1('hash-policy.canonical-json-sha256'),
+      orderedPhases: [
+        { phaseId: 'journal-phase.corrective-replan.intent', ordinal: 0, allowedNextPhaseIds: ['journal-phase.corrective-replan.applying'], terminal: false, durable: true, effectNodeIds: [], digestFields: [] },
+        { phaseId: 'journal-phase.corrective-replan.applying', ordinal: 1, allowedNextPhaseIds: ['journal-phase.corrective-replan.published-pending-readback'], terminal: false, durable: true,
+          effectNodeIds: ['effect.task-state-write', 'effect.plan-artifact-publish', 'effect.plan-validation-append', 'effect.plan-risk-audit-append', 'effect.corrective-replan-execution-append'],
+          digestFields: correctiveReplanBindingManifest.rows.map(({ projection, fieldId }) => ({ projection, fieldId })) },
+        { phaseId: 'journal-phase.corrective-replan.published-pending-readback', ordinal: 2, allowedNextPhaseIds: ['journal-phase.corrective-replan.completed'], terminal: false, durable: true, effectNodeIds: [], digestFields: [] },
+        { phaseId: 'journal-phase.corrective-replan.completed', ordinal: 3, allowedNextPhaseIds: [], terminal: true, durable: true, effectNodeIds: [], digestFields: [] },
+      ],
+    },
+    recovery: {
+      mode: 'automatic-roll-forward', trigger: 'explicit-repair', adapter: v1('recovery-adapter.corrective-replan-roll-forward'),
+      fromPhaseIds: ['journal-phase.corrective-replan.intent', 'journal-phase.corrective-replan.applying', 'journal-phase.corrective-replan.published-pending-readback'],
+      orderedSteps: [
+        { stepId: 'recovery-step.corrective-replan.intent-to-applying', ordinal: 0, fromPhaseId: 'journal-phase.corrective-replan.intent', toPhaseId: 'journal-phase.corrective-replan.applying' },
+        { stepId: 'recovery-step.corrective-replan.applying-to-readback', ordinal: 1, fromPhaseId: 'journal-phase.corrective-replan.applying', toPhaseId: 'journal-phase.corrective-replan.published-pending-readback' },
+        { stepId: 'recovery-step.corrective-replan.readback-to-completed', ordinal: 2, fromPhaseId: 'journal-phase.corrective-replan.published-pending-readback', toPhaseId: 'journal-phase.corrective-replan.completed' },
+      ],
+    },
+    readback: {
+      adapter: v1('readback-adapter.corrective-replan-terminal'),
+      wiring: 'invoked-post-effect',
+      checkpoints: {
+        preCompletion: 'domain-readback',
+        postTerminal: 'terminal-readback',
+      },
+      projection: v1('projection.corrective-replan.terminal-readback'),
+      postconditionIds: [
+        'postcondition.plan-hash-equals-candidate',
+        'postcondition.task-revision-advanced',
+        'postcondition.task-status-awaits-authorization',
+        'postcondition.plan-validation-appended',
+        'postcondition.plan-risk-audit-appended',
+        'postcondition.execution-evidence-appended',
+      ],
+      resultDigestPolicy: v1('hash-policy.canonical-json-sha256'),
+    },
+  },
+  racePreconditions: [
+    { raceId: 'race.corrective-replan.state', reasonClass: 'external-race', guardId: bindingGuardMetadata.guardId,
+      revalidationId: 'revalidation.corrective-replan.state', reads: [slice('projection.corrective-replan.state', manifestProjectionFields('projection.corrective-replan.state'))],
+      allowedFailureCodes: ['STATE_CONFLICT', 'GIT_PRECONDITION_FAILED'] },
+    { raceId: 'race.corrective-replan.authority', reasonClass: 'external-race', guardId: receiptValidGuardMetadata.guardId,
+      revalidationId: 'revalidation.corrective-replan.authority', reads: [slice('projection.corrective-replan.authority', manifestProjectionFields('projection.corrective-replan.authority'))],
+      allowedFailureCodes: ['STATE_CONFLICT', 'CREDENTIAL_EXPIRED'] },
+    { raceId: 'race.corrective-replan.protocol', reasonClass: 'integrity-failure', guardId: noWriterLeaseGuardMetadata.guardId,
+      revalidationId: 'revalidation.corrective-replan.protocol', reads: [slice('projection.corrective-replan.protocol', manifestProjectionFields('projection.corrective-replan.protocol'))],
+      allowedFailureCodes: ['STATE_CONFLICT', 'STATE_CORRUPT'] },
+  ],
+  navigation: { kind: 'human-gate', mode: 'exact', priority: 800 },
+  executorAdapter: v1('effect-adapter.journaled-corrective-replan'),
+  readinessManifest: {
+    developmentStage: 'candidate',
+    releaseProfile: v1('release-profile.exact-mutation'),
+    coverageProfile: v1('coverage-profile.exact-transition'),
+    limitations: [v1('limitation.release-profile.verified-evidence-external')],
+    evidence: [],
+  },
+  traceability: {
+    defectIds: ['WF-STABLE-024', 'WF-REG-005'],
+    invariantIds: ['advertised-exact-transition-is-executable', 'journaled-corrective-replan-replay-safe', 'protocol-v2-human-gate'],
+    positiveEvidence: ['tests/transition-catalog.test.ts', 'tests/corrective-yield-executor-model.test.ts'],
+    hostileEvidence: ['tests/lifecycle-model.test.ts', 'tests/corrective-replan-executor-model.test.ts'],
+  },
+  documentation: {
+    summary: 'Protocol-v2 Human-gated, receipt-bound, journaled corrective Plan replacement.',
+  },
+};
+
+const frozenMetadata = deepFreeze(metadata);
+const frozenGuards = deepFreeze(guards);
+const runtimeFingerprint = runtimeSemanticFingerprint(frozenMetadata);
+
+export const taskCorrectiveReplanDefinition: ExecutableTransitionDefinition<
+  CorrectiveReplanSnapshot,
+  CorrectiveReplanBindings
+> = deepFreeze({
+  metadata: frozenMetadata,
+  runtimeSemanticFingerprint: runtimeFingerprint,
+  semanticFingerprint: runtimeFingerprint,
+  definitionManifestHash: definitionManifestHash(frozenMetadata, runtimeFingerprint),
+  guards: frozenGuards,
+});
+
+export function prepareCorrectiveReplanCandidate(
+  task: Readonly<TaskState>,
+  plan: Readonly<TaskPlanInput>,
+): PreparedCorrectiveReplanCandidate {
+  const rendered = renderPlan(task as TaskState, plan as TaskPlanInput);
+  const planBytes = rendered.endsWith('\n') ? rendered : `${rendered}\n`;
+  return {
+    planBytes,
+    planHash: hashCorrectivePlanBytes(planBytes),
+    stepIds: plan.steps.map((step) => step.id),
+  };
+}
+
+export function hashCorrectivePlanBytes(planBytes: string): string {
+  return createHash('sha256').update(planBytes).digest('hex');
+}
+
+export function evaluateTaskCorrectiveReplanAvailability(
+  task: Readonly<TaskState>,
+  posture: Readonly<CorrectiveReplanPosture>,
+): TransitionEvaluation<CorrectiveReplanAvailabilityBindings> {
+  const bindings = availabilityBindings(task, posture);
+  return evaluateTransition(
+    taskCorrectiveReplanDefinition,
+    correctiveReplanSnapshot(task, posture, null),
+    bindings,
+    'availability',
+  ) as TransitionEvaluation<CorrectiveReplanAvailabilityBindings>;
+}
+
+export function evaluateTaskCorrectiveReplanCandidate(
+  task: Readonly<TaskState>,
+  posture: Readonly<CorrectiveReplanPosture>,
+  candidate: Readonly<PreparedCorrectiveReplanCandidate>,
+): TransitionEvaluation<CorrectiveReplanExecutionBindings> {
+  const bindings: CorrectiveReplanExecutionBindings = {
+    ...availabilityBindings(task, posture),
+    candidatePlanHash: candidate.planHash,
+    candidateStepIds: [...candidate.stepIds],
+  };
+  return evaluateGuardSubset(task, posture, candidate, bindings, 7);
+}
+
+export function evaluateTaskCorrectiveReplanAdmission(
+  task: Readonly<TaskState>,
+  posture: Readonly<CorrectiveReplanPosture>,
+  candidate: Readonly<PreparedCorrectiveReplanCandidate>,
+  facts: Readonly<CorrectiveReplanAdmissionFacts>,
+): TransitionEvaluation<CorrectiveReplanExecutionBindings> {
+  const bindings: CorrectiveReplanExecutionBindings = {
+    ...availabilityBindings(task, posture), candidatePlanHash: candidate.planHash, candidateStepIds: [...candidate.stepIds],
+  };
+  return evaluateTransition(
+    taskCorrectiveReplanDefinition, correctiveReplanSnapshot(task, posture, candidate, facts), bindings, 'execution',
+  ) as TransitionEvaluation<CorrectiveReplanExecutionBindings>;
+}
+
+export const evaluateTaskCorrectiveReplan = evaluateTaskCorrectiveReplanAvailability;
+
+export function correctiveReplanNavigation(
+  evaluation: TransitionEvaluation<CorrectiveReplanAvailabilityBindings>,
+): HumanGateTransitionNavigation<CorrectiveReplanAvailabilityBindings> {
+  if (!evaluation.allowed || evaluation.phase !== 'availability') {
+    throw new TypeError(`Cannot advertise blocked transition ${evaluation.transitionId}.`);
+  }
+  return {
+    kind: 'human-gate',
+    transitionId: evaluation.transitionId,
+    semanticFingerprint: evaluation.semanticFingerprint,
+    command: 'task corrective-replan-prepare',
+    bindings: evaluation.bindings,
+    evaluationPhase: 'availability',
+    pendingInputGuardIds: evaluation.pendingGuardIds,
+  };
+}
+
+export function correctiveReplanBlockedNavigation(
+  evaluation: TransitionEvaluation<CorrectiveReplanAvailabilityBindings>,
+): BlockedTransitionNavigation {
+  if (evaluation.allowed || evaluation.phase !== 'availability') {
+    throw new TypeError(`Transition ${evaluation.transitionId} is not blocked during availability evaluation.`);
+  }
+  return {
+    kind: 'blocked',
+    transitionId: evaluation.transitionId,
+    semanticFingerprint: evaluation.semanticFingerprint,
+    command: 'task corrective-replan-prepare',
+    blockingGuardIds: evaluation.blockingGuardIds,
+    pendingInputGuardIds: evaluation.pendingGuardIds,
+    reasonCode: evaluation.blockingGuardIds.includes(noStepInProgressGuardMetadata.guardId)
+      ? 'RUNNING_STEP_BLOCKS_REPLAN'
+      : 'CORRECTIVE_REPLAN_UNAVAILABLE',
+  };
+}
+
+function correctiveReplanSnapshot(
+  task: Readonly<TaskState>,
+  posture: Readonly<CorrectiveReplanPosture>,
+  candidate: Readonly<PreparedCorrectiveReplanCandidate> | null,
+  facts: Readonly<CorrectiveReplanAdmissionFacts> = {
+    actorRoleEligible: false, c1ClaimAbsent: false, writerLeaseAbsent: false,
+    planValidationPassed: false, receiptValid: false, riskAuditPassed: false,
+  },
+): CorrectiveReplanSnapshot {
+  return {
+    taskId: task.id,
+    taskRevision: task.revision,
+    taskStatus: task.status,
+    currentPlanHash: task.planHash,
+    stepId: posture.stepId,
+    stepStatus: task.steps.find((step) => step.id === posture.stepId)?.status ?? null,
+    inProgressStepIds: task.steps.filter((step) => step.status === 'in_progress').map((step) => step.id),
+    remediationAttemptCount: posture.attemptCount,
+    correctivePosture: posture.posture,
+    correctiveDecision: posture.correctiveDecision,
+    candidatePlanHash: candidate?.planHash ?? null,
+    candidateStepIds: candidate ? [...candidate.stepIds] : null,
+    ...facts,
+  };
+}
+
+function evaluateGuardSubset(
+  task: Readonly<TaskState>, posture: Readonly<CorrectiveReplanPosture>, candidate: Readonly<PreparedCorrectiveReplanCandidate>,
+  bindings: CorrectiveReplanExecutionBindings, count: number,
+): TransitionEvaluation<CorrectiveReplanExecutionBindings> {
+  const snapshot = correctiveReplanSnapshot(task, posture, candidate);
+  const guardResults = taskCorrectiveReplanDefinition.guards.slice(0, count).map((guard) => guard.evaluate(snapshot, bindings));
+  const blockingGuardIds = guardResults.filter((result) => result.status === 'failed').map((result) => result.guardId);
+  return {
+    transitionId: TASK_CORRECTIVE_REPLAN_TRANSITION_ID,
+    semanticFingerprint: taskCorrectiveReplanDefinition.semanticFingerprint,
+    phase: 'execution', allowed: blockingGuardIds.length === 0, bindings,
+    guardResults, blockingGuardIds, pendingGuardIds: [],
+  };
+}
+
+function availabilityBindings(
+  task: Readonly<TaskState>,
+  posture: Readonly<CorrectiveReplanPosture>,
+): CorrectiveReplanAvailabilityBindings {
+  return {
+    taskId: task.id,
+    expectedRevision: task.revision,
+    currentPlanHash: task.planHash ?? '',
+    stepId: posture.stepId,
+    correctiveDecisionEventId: posture.correctiveDecision?.eventId ?? '',
+  };
+}
+
+function executionBindings(
+  bindings: Readonly<CorrectiveReplanBindings>,
+): Readonly<CorrectiveReplanExecutionBindings> | null {
+  return 'candidatePlanHash' in bindings && 'candidateStepIds' in bindings
+    ? bindings
+    : null;
+}
+
+function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function guardMetadata(
+  guardId: TransitionGuardMetadata['guardId'],
+  description: string,
+  phase: TransitionGuardPhase = 'availability',
+  stage: TransitionGuardStage = 'observation',
+  snapshotFieldIds: TransitionGuardMetadata['reads'][number]['fieldIds'] = [],
+  requiredInputIds: readonly TransitionGuardMetadata['requiredInputs'][number]['id'][] = [],
+  reasonClass: TransitionGuardReasonClass = 'lifecycle-blocker',
+): TransitionGuardMetadata {
+  const suffix = guardId.slice('task.corrective-replan.'.length);
+  return {
+    guardId,
+    semanticVersion: 1,
+    phase,
+    stage,
+    reasonClass,
+    evaluator: v1(`guard-evaluator.task.corrective-replan.${suffix}`),
+    reads: [slice('projection.corrective-replan.snapshot', snapshotFieldIds)],
+    requiredInputs: requiredInputIds.map((id) => v1(id)),
+    description,
+  };
+}
+
+function v1<TId extends string>(id: TId): { readonly id: TId; readonly version: 1 } {
+  return { id, version: 1 };
+}
+
+function slice<TProjection extends `projection.${string}`>(
+  projection: TProjection,
+  fieldIds: TransitionGuardMetadata['reads'][number]['fieldIds'],
+): {
+  readonly projection: { readonly id: TProjection; readonly version: 1 };
+  readonly fieldIds: TransitionGuardMetadata['reads'][number]['fieldIds'];
+} {
+  return { projection: v1(projection), fieldIds };
+}
+
+function field<TProjection extends `projection.${string}`, TField extends `field.${string}`>(
+  projection: TProjection,
+  fieldId: TField,
+): {
+  readonly projection: { readonly id: TProjection; readonly version: 1 };
+  readonly fieldId: TField;
+} {
+  return { projection: v1(projection), fieldId };
+}
+
+function manifestProjectionFields(projectionId: string): TransitionGuardMetadata['reads'][number]['fieldIds'] {
+  return correctiveReplanBindingManifest.rows
+    .filter((entry) => entry.projection.id === projectionId)
+    .map((entry) => entry.fieldId);
+}
+
+function verdict(
+  metadata: TransitionGuardMetadata,
+  passed: boolean,
+  reasonCode: string,
+  message: string,
+): TransitionGuardResult {
+  return {
+    guardId: metadata.guardId,
+    status: passed ? 'passed' : 'failed',
+    passed,
+    reasonCode: passed ? 'PASS' : reasonCode,
+    message: passed ? 'Guard passed.' : message,
+  };
+}
+
+function booleanGuard(
+  metadata: TransitionGuardMetadata,
+  fieldName: keyof CorrectiveReplanAdmissionFacts,
+  reasonCode: string,
+): TransitionGuard<CorrectiveReplanSnapshot, CorrectiveReplanBindings> {
+  return {
+    metadata,
+    evaluate(snapshot) {
+      return verdict(metadata, snapshot[fieldName] === true, reasonCode, `${metadata.description}`);
+    },
+  };
+}