codex-workflow-v2 2.0.0-alpha.7.2 → 2.0.0-beta.1

package/dist/src/workflow.js

@@ -8,12 +8,13 @@ import { assessDiscovery, mergeUnique } from './domain/discovery.js';
 import { pathAllowed, validatePlan } from './domain/validation.js';
 import { WorkflowError } from './errors.js';
 import { bindGraphEvidence, createGraphRefreshRequest, fallbackGraphBinding, inspectGraphBinding, validateGraphRequestCurrent, } from './graph.js';
-import { inspectLocalDependency } from './diagnostics.js';
+import { inspectLocalDependency, inspectWorkflowVersions } from './diagnostics.js';
 import { appendTaskClaim, appendTaskHandback, appendTaskHandoff, assertTaskMutationAllowedByC1, defaultTaskWorkerActor, readTaskC1Posture, } from './alpha6/handoff.js';
 import { applyAdoptionPosture, assertAdoptionBaselinePreserved, buildAdoptionPreparation, initializeProjectRegistrationAdoption, readCurrentAdoptionPosture, } from './alpha6/adoption.js';
 import { appendCurrentPlanRiskAudit, appendReboundPlanRiskAudit, readCurrentPlanRiskAudit, validatePlanRiskAuditCandidate, } from './alpha6/plan-risk.js';
-import { appendCorrectiveDecisionEvent, appendRemediationEvent, assertCorrectiveAuditorIndependence, assertGuardedRemediationAttemptAllowed, defaultCorrectiveAuditorActor, findCurrentGuardedRemediationPosture, findFailedGuardedStepRequiringCorrectiveDecision, readGuardedRemediationPostureForStep, readCorrectiveDecisionEvents, readRemediationEvents, } from './alpha6/remediation.js';
-import { applyMilestoneScopeChangeTransaction, assertMilestoneMembershipIntegrity, assertMilestoneScopeChangeStatusAllowed, normalizeMilestonePlan, prepareMilestoneScopeChangeCandidate, readMilestoneForScopeChange, readMilestoneWithIntegrity, } from './alpha6/milestone.js';
+import { appendCorrectiveDecisionEvent, appendRemediationEvent, appendRemediationModeRecovery, assertCorrectiveAuditorIndependence, assertGuardedRemediationAttemptAllowed, defaultCorrectiveAuditorActor, findCurrentGuardedRemediationPosture, findRemediationModeRecoveryCandidate, findFailedGuardedStepRequiringCorrectiveDecision, readGuardedRemediationPostureForStep, readCorrectiveDecisionEvents, readRemediationEvents, } from './alpha6/remediation.js';
+import { applyMilestoneScopeChangeTransaction, assertMilestoneMembershipIntegrity, assertMilestoneScopeChangeStatusAllowed, normalizeMilestonePlan, prepareMilestoneScopeChangeCandidate, prepareMilestoneScopeChangeBundle, readMilestoneForScopeChange, readMilestoneWithIntegrity, } from './alpha6/milestone.js';
+import { applyProjectTransaction, recoverProjectTransactions, runRollbackProjectTransaction, } from './beta1/project-transaction.js';
 import { buildCurrentStrictStepReviewCycle, ensurePendingStrictStepReview, isStepReviewRequired, recordStrictStepReview, } from './alpha6/review.js';
 import { applyMilestoneAutonomyContract, assertAutonomousPlanEvolution, prepareMilestoneAutonomyContract, readMilestoneAutonomyEvents, requireActiveMilestoneAutonomy, } from './alpha7/autonomy.js';
 import { appendCorrectiveDecisionRecovery, readValidatedCorrectiveDecisionRecoveryForNavigation, requireCorrectiveDecisionRecoveryForRun, } from './alpha7/corrective-recovery.js';
@@ -35,7 +36,9 @@ export class WorkflowService {
     }
     context(repository) {
         const identity = resolveRepositoryIdentity(repository);
-        const projectFile = path.join(this.store.projectRoot(identity.projectId), 'project.json');
+        const projectRoot = this.store.projectRoot(identity.projectId);
+        recoverProjectTransactions(projectRoot, identity.projectId);
+        const projectFile = path.join(projectRoot, 'project.json');
         const projectAlreadyRegistered = existsSync(projectFile);
         if (!projectAlreadyRegistered) {
             initializeProjectRegistrationAdoption(this.store, {
@@ -249,6 +252,257 @@ export class WorkflowService {
         const savedDiscovery = this.store.writeDiscovery({ ...discovery, status: 'materialized', materializedEntityId: taskId }, expectedRevision);
         return { discovery: savedDiscovery, task: savedTask, taskRoot };
     }
+    replaceSplitRequiredTask(repository, oldTaskId, expectedOldTaskRevision, discoveryId, expectedDiscoveryRevision, expectedMilestoneRevision, title, actor) {
+        const { identity, locks } = this.context(repository);
+        const oldTask = this.store.readTask(identity.projectId, oldTaskId);
+        assertExpectedRevision(oldTask, expectedOldTaskRevision);
+        if (!oldTask.milestoneId) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'A split-required replacement requires a Milestone-linked Task.');
+        }
+        const milestone = this.readMilestoneScopeChangeCurrent(identity.projectId, oldTask.milestoneId);
+        assertExpectedRevision(milestone, expectedMilestoneRevision);
+        assertMilestoneScopeChangeStatusAllowed(milestone);
+        const membership = milestone.memberships.find((candidate) => candidate.taskId === oldTask.id);
+        if (membership?.disposition !== 'required') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'The terminal Task must still be a required Milestone member.', {
+                taskId: oldTask.id,
+                milestoneId: milestone.id,
+                disposition: membership?.disposition ?? null,
+            });
+        }
+        const riskAudit = readCurrentPlanRiskAudit(this.store, oldTask);
+        if (!riskAudit)
+            throw new WorkflowError('STATE_CORRUPT', 'The terminal Task has no current Plan Risk Audit.');
+        const posture = findCurrentGuardedRemediationPosture(this.store, oldTask, riskAudit);
+        if (posture?.posture !== 'split-required' || posture.correctiveDecision?.decision !== 'split-required') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Task replacement is available only for the exact split-required posture.', {
+                taskId: oldTask.id,
+                posture: posture?.posture ?? null,
+                decision: posture?.correctiveDecision?.decision ?? null,
+            });
+        }
+        const discovery = this.store.readDiscovery(identity.projectId, discoveryId);
+        assertExpectedRevision(discovery, expectedDiscoveryRevision);
+        const readiness = assessDiscovery(discovery);
+        if (!readiness.ready || discovery.status !== 'ready_to_materialize') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Replacement Discovery is not ready to materialize.', {
+                discoveryId,
+                missing: readiness.missing,
+            });
+        }
+        const normalizedTitle = title.trim();
+        const normalizedActor = actor.trim();
+        if (!normalizedTitle)
+            throw new WorkflowError('INVALID_ARGUMENT', 'Replacement Task title is required.');
+        if (!normalizedActor)
+            throw new WorkflowError('INVALID_ARGUMENT', 'Replacement actor is required.');
+        let autonomyContractEventHash;
+        let activeAutonomy = null;
+        if (normalizedActor.startsWith('agent:')) {
+            activeAutonomy = requireActiveMilestoneAutonomy({
+                store: this.store,
+                projectId: identity.projectId,
+                milestone,
+                actor: normalizedActor,
+                now: this.now(),
+            });
+            autonomyContractEventHash = activeAutonomy.contract.eventHash;
+        }
+        const now = this.now();
+        const timestamp = now.toISOString();
+        const replacementTaskId = createEntityId('TASK', now.getTime());
+        const briefContent = renderBrief(discovery, normalizedTitle);
+        const normalizedBriefContent = briefContent.endsWith('\n') ? briefContent : `${briefContent}\n`;
+        const briefHash = sha256Hex(normalizedBriefContent);
+        const replacementTask = {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 1,
+            id: replacementTaskId,
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'task',
+            status: 'planning',
+            title: normalizedTitle,
+            slug: slugify(normalizedTitle),
+            discoveryId,
+            milestoneId: milestone.id,
+            repositoryRoot: identity.repositoryRoot,
+            baseBranch: milestone.baseBranch,
+            baseCommit: null,
+            taskBranch: null,
+            workspaceOwner: null,
+            briefHash,
+            planHash: null,
+            planObjective: null,
+            resultHash: null,
+            evidenceHash: null,
+            requirements: discovery.acceptance.map((_, index) => `REQ-${String(index + 1).padStart(3, '0')}`),
+            acceptance: discovery.acceptance.map((_, index) => `AC-${String(index + 1).padStart(3, '0')}`),
+            risks: discovery.assumptions,
+            knowledgeImpact: null,
+            knowledgeImpactReason: null,
+            knowledgeTargets: [],
+            knowledgeMapRevision: null,
+            knowledgeMapHash: null,
+            graphUse: null,
+            steps: [],
+            authorizations: [],
+            knowledgeRebinds: [],
+            review: emptyReview(),
+            blockReason: null,
+            mergedCommit: null,
+            systemCommits: [],
+            replacementForTaskId: oldTask.id,
+            replacedByTaskId: null,
+        };
+        const cancelledOldTask = {
+            ...oldTask,
+            revision: oldTask.revision + 1,
+            updatedAt: timestamp,
+            status: 'cancelled',
+            blockReason: `Replaced after split-required by ${replacementTaskId}.`,
+            replacedByTaskId: replacementTaskId,
+        };
+        const consumedDiscovery = {
+            ...discovery,
+            revision: discovery.revision + 1,
+            updatedAt: timestamp,
+            status: 'materialized',
+            materializedEntityId: replacementTaskId,
+        };
+        const replacementReason = `Replacement for ${oldTask.id} after split-required decision ${posture.correctiveDecision.eventId}.`;
+        const plan = {
+            outcome: milestone.outcome,
+            successSignal: milestone.successSignal,
+            acceptance: milestone.acceptance,
+            checks: milestone.checks,
+            memberships: [
+                ...milestone.memberships.map((candidate) => candidate.taskId === oldTask.id
+                    ? { ...candidate, disposition: 'cancelled', reason: replacementReason }
+                    : candidate),
+                { taskId: replacementTaskId, disposition: 'required', reason: replacementReason },
+            ],
+        };
+        if (autonomyContractEventHash) {
+            const autonomy = requireActiveMilestoneAutonomy({
+                store: this.store,
+                projectId: identity.projectId,
+                milestone,
+                actor: normalizedActor,
+                now,
+            });
+            assertAutonomousPlanEvolution(milestone, plan, autonomy.contract);
+        }
+        const readCandidateTask = (taskId) => {
+            if (taskId === oldTask.id)
+                return cancelledOldTask;
+            if (taskId === replacementTaskId)
+                return replacementTask;
+            return this.store.readTask(identity.projectId, taskId);
+        };
+        const prepared = prepareMilestoneScopeChangeCandidate({
+            milestone,
+            plan,
+            readTask: readCandidateTask,
+            actor: normalizedActor,
+            ...(autonomyContractEventHash ? { autonomyContractEventHash } : {}),
+        });
+        const bundle = prepareMilestoneScopeChangeBundle({
+            store: this.store,
+            milestone,
+            prepared,
+            now,
+            readTask: readCandidateTask,
+        });
+        const currentKnowledgeMap = this.store.readKnowledgeMap(identity.projectId);
+        const scannedKnowledgeMap = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, now);
+        const inspectedKnowledgeMap = inspectKnowledgeMap(currentKnowledgeMap, scannedKnowledgeMap);
+        let refreshedKnowledgeMap = null;
+        if (activeAutonomy
+            && currentKnowledgeMap.status === 'active'
+            && currentKnowledgeMap.approval
+            && (inspectedKnowledgeMap.status !== 'active' || !inspectedKnowledgeMap.approval)) {
+            const refreshAssessment = assessDelegatedKnowledgeRefresh(currentKnowledgeMap, inspectedKnowledgeMap, oldTask, oldTask.planHash
+                ? this.store.hashArtifact(this.store.taskRoot(identity.projectId, oldTask.id), 'plan.md')
+                : null);
+            if (refreshAssessment.eligible) {
+                if (refreshAssessment.mode === 'delegated-plan-bounded-supporting-source') {
+                    this.assertPlanBoundedSupportingSourceGrant(identity.projectId, activeAutonomy.grant.id, normalizedActor, oldTask);
+                }
+                const delegation = this.delegatedAuthorization(identity.projectId, activeAutonomy.grant.id, 'project_memory.approve', normalizedActor, inspectedKnowledgeMap, oldTask.id);
+                if (!delegation) {
+                    throw new WorkflowError('TRANSITION_BLOCKED', 'Replacement Knowledge refresh requires delegated approval evidence.');
+                }
+                const reconciled = reconcileKnowledgeMap(currentKnowledgeMap, scannedKnowledgeMap);
+                const approved = applyKnowledgeSelections(reconciled, [], normalizedActor, now);
+                if (!approved.approval) {
+                    throw new WorkflowError('STATE_CORRUPT', 'Replacement Knowledge refresh did not produce approval evidence.');
+                }
+                refreshedKnowledgeMap = {
+                    ...approved,
+                    revision: currentKnowledgeMap.revision + 2,
+                    approval: {
+                        ...approved.approval,
+                        authorizationMode: 'delegated',
+                        delegation,
+                    },
+                };
+            }
+        }
+        const projectRoot = this.store.projectRoot(identity.projectId);
+        const relative = (absolute) => path.relative(projectRoot, absolute).split(path.sep).join('/');
+        applyProjectTransaction({
+            projectRoot,
+            projectId: identity.projectId,
+            transactionId: `tx-${createEntityId('TASK', now.getTime()).toLowerCase()}`,
+            kind: 'split-required-task-replacement',
+            now,
+            targets: [
+                { path: relative(path.join(this.store.discoveryRoot(identity.projectId, discovery.id), 'state.json')), content: `${JSON.stringify(consumedDiscovery, null, 2)}\n` },
+                { path: relative(path.join(this.store.taskRoot(identity.projectId, replacementTaskId), 'brief.md')), content: normalizedBriefContent },
+                { path: relative(path.join(this.store.taskRoot(identity.projectId, replacementTaskId), 'state.json')), content: `${JSON.stringify(replacementTask, null, 2)}\n` },
+                { path: relative(path.join(this.store.taskRoot(identity.projectId, oldTask.id), 'state.json')), content: `${JSON.stringify(cancelledOldTask, null, 2)}\n` },
+                { path: relative(path.join(this.store.lockRoot(identity.projectId), `${oldTask.id}.json`)), content: null },
+                ...(refreshedKnowledgeMap
+                    ? [{ path: relative(path.join(projectRoot, 'knowledge-map.json')), content: `${JSON.stringify(refreshedKnowledgeMap, null, 2)}\n` }]
+                    : []),
+                { path: relative(path.join(this.store.milestoneRoot(identity.projectId, milestone.id), 'plan.json')), content: bundle.planContent },
+                { path: relative(path.join(this.store.milestoneRoot(identity.projectId, milestone.id), 'scope-change-events.jsonl')), content: bundle.sidecarContent },
+                { path: relative(path.join(this.store.milestoneRoot(identity.projectId, milestone.id), 'state.json')), content: bundle.stateContent },
+            ],
+            validate: () => {
+                const savedDiscovery = this.store.readDiscovery(identity.projectId, discovery.id);
+                const savedOldTask = this.store.readTask(identity.projectId, oldTask.id);
+                const savedReplacement = this.store.readTask(identity.projectId, replacementTaskId);
+                const savedMilestone = this.store.readMilestone(identity.projectId, milestone.id);
+                if (savedDiscovery.materializedEntityId !== replacementTaskId
+                    || savedOldTask.status !== 'cancelled'
+                    || savedOldTask.replacedByTaskId !== replacementTaskId
+                    || savedReplacement.replacementForTaskId !== oldTask.id) {
+                    throw new WorkflowError('STATE_CORRUPT', 'Replacement transaction relationship validation failed.');
+                }
+                if (locks.inspect(oldTask.id)) {
+                    throw new WorkflowError('STATE_CORRUPT', 'Replacement transaction retained authority for the cancelled Task.');
+                }
+                if (refreshedKnowledgeMap) {
+                    const savedKnowledgeMap = this.store.readKnowledgeMap(identity.projectId);
+                    if (savedKnowledgeMap.revision !== refreshedKnowledgeMap.revision
+                        || savedKnowledgeMap.status !== 'active'
+                        || savedKnowledgeMap.approval?.authorizationMode !== 'delegated') {
+                        throw new WorkflowError('STATE_CORRUPT', 'Replacement transaction Knowledge refresh validation failed.');
+                    }
+                }
+                assertMilestoneMembershipIntegrity(savedMilestone, (taskId) => this.store.readTask(identity.projectId, taskId));
+            },
+        });
+        return {
+            oldTask: this.store.readTask(identity.projectId, oldTask.id),
+            replacementTask: this.store.readTask(identity.projectId, replacementTaskId),
+            discovery: this.store.readDiscovery(identity.projectId, discovery.id),
+            milestone: this.readMilestoneCurrent(identity.projectId, milestone.id),
+        };
+    }
     materializeMilestone(repository, discoveryId, expectedRevision, title, baseBranch = 'main') {
         const { identity } = this.context(repository);
         const discovery = this.store.readDiscovery(identity.projectId, discoveryId);
@@ -784,6 +1038,7 @@ export class WorkflowService {
         const { identity } = this.context(repository);
         const task = this.store.readTask(identity.projectId, taskId);
         assertExpectedRevision(task, expectedRevision);
+        this.assertTaskContextChangeAllowed(task);
         if (!taskCanRebindKnowledge(task)) {
             throw new WorkflowError('TRANSITION_BLOCKED', `Cannot rebind Task Plan knowledge while Task is ${task.status}.`);
         }
@@ -870,6 +1125,7 @@ export class WorkflowService {
         const currentMap = this.store.readKnowledgeMap(identity.projectId);
         assertExpectedRevision(task, expectedTaskRevision);
         assertExpectedRevision(currentMap, expectedKnowledgeMapRevision);
+        this.assertTaskContextChangeAllowed(task);
         if (!taskCanRebindKnowledge(task)) {
             throw new WorkflowError('TRANSITION_BLOCKED', `Cannot refresh Task context while Task is ${task.status}.`);
         }
@@ -887,45 +1143,72 @@ export class WorkflowService {
         // Validate every delegated transition before the first write so a narrow grant cannot
         // leave the composite operation half-applied.
         this.delegatedAuthorization(identity.projectId, delegationGrantId, 'task.execution_authorize', actor, task);
-        let knowledgeMap = currentMap;
-        if (inspectedMap.status !== 'active' || !inspectedMap.approval) {
-            if (currentMap.status !== 'active' || !currentMap.approval) {
-                throw new WorkflowError('TRANSITION_BLOCKED', 'Automatic Task context refresh requires a previously approved map with safe delegated drift.', { currentStatus: currentMap.status, inspectedStatus: inspectedMap.status });
-            }
-            assertDelegatedKnowledgeRefresh(refreshAssessment);
-            if (inspectedMap.status !== 'stale') {
-                throw new WorkflowError('TRANSITION_BLOCKED', 'Safe delegated Knowledge drift must reconcile to a stale candidate before approval.', { currentStatus: currentMap.status, inspectedStatus: inspectedMap.status });
-            }
-            if (refreshAssessment.mode === 'delegated-plan-bounded-supporting-source') {
-                this.assertPlanBoundedSupportingSourceGrant(identity.projectId, delegationGrantId, actor, task);
-            }
-            this.delegatedAuthorization(identity.projectId, delegationGrantId, 'project_memory.approve', actor, inspectedMap, task.id);
-            knowledgeMap = this.reconcileKnowledgeMap(repository, currentMap.revision);
-            transitions.push('project-memory reconcile');
-            knowledgeMap = this.approveKnowledgeMapForTaskRefresh(repository, knowledgeMap.revision, [], actor, delegationGrantId, task.id);
-            transitions.push('project-memory approve');
-        }
-        const knowledgeMapHash = hashKnowledgeMap(knowledgeMap);
-        if (task.knowledgeMapRevision === knowledgeMap.revision
-            && task.knowledgeMapHash === knowledgeMapHash) {
-            throw new WorkflowError('TRANSITION_BLOCKED', 'Task context is already current; refresh is a no-op.');
-        }
-        let refreshedTask = this.rebindTaskKnowledge(repository, taskId, task.revision);
-        if (currentPlanRiskAudit) {
-            appendReboundPlanRiskAudit(this.store, task, refreshedTask, currentPlanRiskAudit, this.now());
-        }
-        transitions.push('task knowledge-rebind');
-        refreshedTask = this.authorizeTask(repository, taskId, refreshedTask.revision, actor, refreshAssessment.mode === 'delegated-plan-bounded-supporting-source'
-            ? 'Delegated Plan-bounded supporting-source context refresh.'
-            : 'Delegated content-only context refresh.', delegationGrantId);
-        transitions.push('task execution authorize');
-        return {
-            mode: refreshAssessment.mode,
-            transitions,
-            addedSources: refreshAssessment.addedSources,
-            knowledgeMap,
-            task: refreshedTask,
-        };
+        const projectRoot = this.store.projectRoot(identity.projectId);
+        const relative = (absolute) => path.relative(projectRoot, absolute).split(path.sep).join('/');
+        return runRollbackProjectTransaction({
+            projectRoot,
+            projectId: identity.projectId,
+            transactionId: `tx-${createEntityId('TASK', this.now().getTime()).toLowerCase()}`,
+            kind: 'delegated-task-context-refresh',
+            now: this.now(),
+            targetPaths: [
+                relative(path.join(projectRoot, 'knowledge-map.json')),
+                relative(path.join(this.store.taskRoot(identity.projectId, task.id), 'state.json')),
+                relative(path.join(this.store.taskRoot(identity.projectId, task.id), 'plan.md')),
+                relative(path.join(this.store.taskRoot(identity.projectId, task.id), 'plan-risk-audits.jsonl')),
+            ],
+            mutate: () => {
+                let knowledgeMap = currentMap;
+                if (inspectedMap.status !== 'active' || !inspectedMap.approval) {
+                    if (currentMap.status !== 'active' || !currentMap.approval) {
+                        throw new WorkflowError('TRANSITION_BLOCKED', 'Automatic Task context refresh requires a previously approved map with safe delegated drift.', { currentStatus: currentMap.status, inspectedStatus: inspectedMap.status });
+                    }
+                    assertDelegatedKnowledgeRefresh(refreshAssessment);
+                    if (inspectedMap.status !== 'stale') {
+                        throw new WorkflowError('TRANSITION_BLOCKED', 'Safe delegated Knowledge drift must reconcile to a stale candidate before approval.', { currentStatus: currentMap.status, inspectedStatus: inspectedMap.status });
+                    }
+                    if (refreshAssessment.mode === 'delegated-plan-bounded-supporting-source') {
+                        this.assertPlanBoundedSupportingSourceGrant(identity.projectId, delegationGrantId, actor, task);
+                    }
+                    this.delegatedAuthorization(identity.projectId, delegationGrantId, 'project_memory.approve', actor, inspectedMap, task.id);
+                    knowledgeMap = this.reconcileKnowledgeMap(repository, currentMap.revision, true);
+                    transitions.push('project-memory reconcile');
+                    knowledgeMap = this.approveKnowledgeMapForTaskRefresh(repository, knowledgeMap.revision, [], actor, delegationGrantId, task.id);
+                    transitions.push('project-memory approve');
+                }
+                const knowledgeMapHash = hashKnowledgeMap(knowledgeMap);
+                if (task.knowledgeMapRevision === knowledgeMap.revision
+                    && task.knowledgeMapHash === knowledgeMapHash) {
+                    throw new WorkflowError('TRANSITION_BLOCKED', 'Task context is already current; refresh is a no-op.');
+                }
+                let refreshedTask = this.rebindTaskKnowledge(repository, taskId, task.revision);
+                if (currentPlanRiskAudit) {
+                    appendReboundPlanRiskAudit(this.store, task, refreshedTask, currentPlanRiskAudit, this.now());
+                }
+                transitions.push('task knowledge-rebind');
+                refreshedTask = this.authorizeTask(repository, taskId, refreshedTask.revision, actor, refreshAssessment.mode === 'delegated-plan-bounded-supporting-source'
+                    ? 'Delegated Plan-bounded supporting-source context refresh.'
+                    : 'Delegated content-only context refresh.', delegationGrantId);
+                transitions.push('task execution authorize');
+                return {
+                    mode: refreshAssessment.mode,
+                    transitions,
+                    addedSources: refreshAssessment.addedSources,
+                    knowledgeMap,
+                    task: refreshedTask,
+                };
+            },
+            validate: (result) => {
+                const currentTask = this.store.readTask(identity.projectId, task.id);
+                if (currentTask.revision !== result.task.revision || currentTask.status !== 'ready') {
+                    throw new WorkflowError('STATE_CORRUPT', 'Context refresh transaction did not commit an authorized Task.');
+                }
+                const currentKnowledgeMap = this.store.readKnowledgeMap(identity.projectId);
+                if (currentKnowledgeMap.revision !== result.knowledgeMap.revision) {
+                    throw new WorkflowError('STATE_CORRUPT', 'Context refresh transaction Knowledge Map revision mismatch.');
+                }
+            },
+        });
     }
     authorizeTask(repository, taskId, expectedRevision, actor, reason = '', delegationGrantId = null) {
         const { identity } = this.context(repository);
@@ -1166,7 +1449,6 @@ export class WorkflowService {
             throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} cannot run a Step while ${task.status}.`);
         }
         this.assertExecutionAuthorizationFresh(task);
-        const knowledgeMap = this.assertTaskKnowledgeBinding(context.identity.repositoryRoot, task);
         const currentPlanBlockingDecisions = readCorrectiveDecisionEvents(this.store, task)
             .filter((event) => event.planHash === task.planHash && event.decision !== 'continue-fix');
         if (currentPlanBlockingDecisions.length > 0) {
@@ -1207,6 +1489,7 @@ export class WorkflowService {
                 : null;
             assertGuardedRemediationAttemptAllowed(this.store, task, stepId, planRiskAudit, recovery?.correctiveDecisionEventId ?? null);
         }
+        const knowledgeMap = this.assertTaskKnowledgeBinding(context.identity.repositoryRoot, task);
         const dirty = changedFiles(context.identity.repositoryRoot);
         if (step.status === 'planned' && dirty.length > 0) {
             throw new WorkflowError('GIT_PRECONDITION_FAILED', `${stepId} must start from a clean checkout.`, {
@@ -1670,6 +1953,13 @@ export class WorkflowService {
         this.assertTaskKnowledgeBinding(context.identity.repositoryRoot, task);
         return appendCorrectiveDecisionRecovery(this.store, task, stepId, expectedRevision, actor, writerToken, this.now());
     }
+    recoverRemediationMode(repository, taskId, stepId, expectedRevision, actor, writerToken) {
+        const context = this.context(repository);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        this.requireExecutionAdoptionPosture(context.identity, taskId);
+        return appendRemediationModeRecovery(this.store, task, stepId, expectedRevision, actor, writerToken, this.now());
+    }
     recordStepCorrectiveDecision(repository, taskId, stepId, expectedRevision, correctiveAudit, actor, writerToken = null) {
         const { identity } = this.context(repository);
         this.readCurrentAdoptionPostureStrict(identity.projectId);
@@ -1914,11 +2204,34 @@ export class WorkflowService {
         const now = this.now().getTime();
         const activeLeases = leases.filter((lease) => Date.parse(lease.expiresAt) > now);
         const staleLeases = leases.filter((lease) => Date.parse(lease.expiresAt) <= now);
+        const activeMilestones = milestones.filter((milestone) => !['accepted', 'cancelled'].includes(milestone.status));
+        const inspectedVersions = inspectWorkflowVersions(context.identity.repositoryRoot, activeMilestones.map((milestone) => milestone.baseBranch));
+        const milestoneBases = inspectedVersions.milestoneBases.map((base) => ({
+            ...base,
+            milestoneIds: activeMilestones.filter((milestone) => milestone.baseBranch === base.branch).map((milestone) => milestone.id),
+        }));
+        const dependencyPresent = inspectedVersions.declared !== null
+            || inspectedVersions.locked !== null
+            || inspectedVersions.installed !== null;
+        const versionValues = dependencyPresent
+            ? [
+                inspectedVersions.declared,
+                inspectedVersions.locked,
+                inspectedVersions.installed,
+                inspectedVersions.currentBranch,
+                ...milestoneBases.map((base) => base.version),
+            ]
+            : [];
+        const versionsAligned = versionValues.every((version) => version === PACKAGE_VERSION);
+        const versionBlockers = dependencyPresent && !versionsAligned
+            ? ['Workflow dependency versions diverge across declared, locked, installed, current-branch, or active Milestone base state.']
+            : [];
         const blockers = [
             ...(dirty.length > 0 ? ['Repository checkout is not clean.'] : []),
             ...(runningSteps.length > 0 ? ['At least one Worker Step is in progress.'] : []),
             ...(activeLeases.length > 0 ? ['At least one writer lease is active.'] : []),
             ...(staleLeases.length > 0 ? ['At least one stale writer lease requires explicit repair.'] : []),
+            ...versionBlockers,
         ];
         const adoption = buildAdoptionPreparation({
             projectId: context.identity.projectId,
@@ -1945,6 +2258,20 @@ export class WorkflowService {
             activeLeases,
             staleLeases,
             blockers,
+            workflowVersions: {
+                runtime: inspectedVersions.runtime,
+                declared: inspectedVersions.declared,
+                locked: inspectedVersions.locked,
+                installed: inspectedVersions.installed,
+                currentBranch: inspectedVersions.currentBranch,
+                milestoneBases,
+            },
+            dependencyTransport: {
+                safe: versionBlockers.length === 0,
+                requiredAction: versionBlockers.length === 0
+                    ? null
+                    : 'Land only package.json/package-lock.json dependency changes on every active Milestone base; do not transport unrelated product commits.',
+            },
             adoption,
         };
     }
@@ -2094,11 +2421,30 @@ export class WorkflowService {
         };
         return this.store.writeKnowledgeMap(approved, expectedRevision);
     }
-    reconcileKnowledgeMap(repository, expectedRevision) {
+    reconcileKnowledgeMap(repository, expectedRevision, allowAtomicTaskRefresh = false) {
         const { identity } = this.context(repository);
         const current = this.store.readKnowledgeMap(identity.projectId);
         assertExpectedRevision(current, expectedRevision);
         const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
+        if (!allowAtomicTaskRefresh && current.status === 'active' && current.approval) {
+            const milestonesById = new Map(this.listMilestonesCurrent(identity.projectId).map((milestone) => [milestone.id, milestone]));
+            const activeTask = this.store
+                .listTasks(identity.projectId)
+                .find((task) => taskIsActionableFromRepositoryNext(task, milestonesById));
+            if (activeTask?.planHash
+                && taskCanRebindKnowledge(activeTask)
+                && !this.taskHasTerminalCorrectiveDecision(activeTask)) {
+                const inspected = inspectKnowledgeMap(current, scanned);
+                const assessment = assessDelegatedKnowledgeRefresh(current, inspected, activeTask, this.store.hashArtifact(this.store.taskRoot(identity.projectId, activeTask.id), 'plan.md'));
+                if (assessment.eligible
+                    && this.delegatedContextRefreshOptions(identity.projectId, activeTask, inspected, assessment.mode).length > 0) {
+                    throw new WorkflowError('TRANSITION_BLOCKED', 'Standalone Project Knowledge reconcile would strand an authorized Task context refresh.', {
+                        taskId: activeTask.id,
+                        requiredAction: 'Run the exact task context-refresh action returned by next.',
+                    });
+                }
+            }
+        }
         return this.store.writeKnowledgeMap(reconcileKnowledgeMap(current, scanned), expectedRevision);
     }
     graphRefreshRequest(repository, graphKind, mode = 'moderate') {
@@ -2157,10 +2503,17 @@ export class WorkflowService {
             const taskNext = activeTask.status === 'planning'
                 ? null
                 : this.nextForTaskWithDelegation(status.projectId, activeTask, activePlanRiskAudit);
-            // Pending strict review is completion work for the already-recorded commit. It must
-            // outrank Project Knowledge refresh/rebind; otherwise the active Step makes the rebind
-            // returned by `next` impossible to execute.
-            if (taskNext?.action === 'task step-review') {
+            // Active Step work must outrank Project Knowledge refresh/rebind. Both completion and
+            // strict review are executable while context refresh correctly remains forbidden.
+            const hardStop = taskNext?.action === 'task corrective-decision'
+                && taskNext.correctiveDecisionGate?.hardStop === true;
+            const terminalCorrectiveDecision = taskNext?.correctiveDecisionGate?.decision;
+            if (taskNext?.action === 'task step-complete'
+                || taskNext?.action === 'task step-review'
+                || taskNext?.action === 'task remediation-mode-recover'
+                || hardStop
+                || terminalCorrectiveDecision === 'split-required'
+                || terminalCorrectiveDecision === 'stop-escalate') {
                 return withAdoption(taskNext);
             }
             if (!taskCanRebindKnowledge(activeTask) && activeTask.status !== 'planning') {
@@ -2183,11 +2536,17 @@ export class WorkflowService {
                     ? this.delegatedContextRefreshOptions(status.projectId, activeTask, knowledgeMap, refreshAssessment.mode)
                     : [];
                 return withAdoption({
-                    scope: 'project-memory',
+                    scope: contextRefreshOptions.length > 0 ? 'task' : 'project-memory',
                     status: knowledgeMap.status,
-                    action,
+                    action: contextRefreshOptions.length > 0 ? 'task context-refresh' : action,
                     revision: knowledgeMap.revision,
-                    taskId: activeTask.id,
+                    ...(contextRefreshOptions.length > 0
+                        ? { taskId: activeTask.id }
+                        : {
+                            stalenessOriginTaskId: activeTask.id,
+                            authorizesTask: false,
+                            provenanceNotice: 'This Task identifier is diagnostic provenance only; the Project Knowledge action does not authorize or resume it.',
+                        }),
                     ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
                     ...(contextRefreshOptions.length > 0
                         ? {
@@ -2423,9 +2782,18 @@ export class WorkflowService {
             ? this.delegatedApprovalOptions(projectId, transition, task)
             : [];
         const failedReviewAttempts = countFailedReviewAttempts(this.store.taskRoot(projectId, task.id));
-        const guardedCorrectivePosture = planRiskAudit
-            ? findCurrentGuardedRemediationPosture(this.store, task, planRiskAudit)
-            : null;
+        let remediationModeRecovery = null;
+        let guardedCorrectivePosture = null;
+        if (planRiskAudit) {
+            try {
+                guardedCorrectivePosture = findCurrentGuardedRemediationPosture(this.store, task, planRiskAudit);
+            }
+            catch (error) {
+                remediationModeRecovery = findRemediationModeRecoveryCandidate(this.store, task);
+                if (!remediationModeRecovery)
+                    throw error;
+            }
+        }
         const next = nextForTask(task);
         const handoffPosture = readTaskC1Posture(this.store, task);
         const strictStepReviewStep = planRiskAudit
@@ -2469,7 +2837,24 @@ export class WorkflowService {
                     }
                     : {};
         let guardedCorrectiveOverlay = {};
-        if (!strictStepReviewStep && guardedCorrectivePosture) {
+        if (remediationModeRecovery) {
+            guardedCorrectiveOverlay = {
+                action: 'task remediation-mode-recover',
+                stepId: remediationModeRecovery.remediation.stepId,
+                remediationModeRecovery: {
+                    state: 'required',
+                    remediationEventId: remediationModeRecovery.remediation.eventId,
+                    remediationEventHash: remediationModeRecovery.remediation.eventHash,
+                    correctiveDecisionEventId: remediationModeRecovery.decision.eventId,
+                    correctiveDecisionRecoveryEventId: remediationModeRecovery.correctiveRecovery.eventId,
+                    attemptOrdinal: remediationModeRecovery.remediation.attemptOrdinal,
+                    fromMode: 'ordinary',
+                    toMode: 'corrective',
+                    requiredActor: remediationModeRecovery.actor,
+                },
+            };
+        }
+        if (!remediationModeRecovery && !strictStepReviewStep && guardedCorrectivePosture) {
             switch (guardedCorrectivePosture.posture) {
                 case 'decision-required':
                     if (guardedCorrectivePosture.correctiveDecision
@@ -2556,6 +2941,56 @@ export class WorkflowService {
                     };
                     break;
                 case 'split-required':
+                    {
+                        const replacementDiscoveries = this.store.listDiscoveries(projectId)
+                            .filter((discovery) => discovery.status === 'ready_to_materialize');
+                        const replacementDiscovery = replacementDiscoveries.length === 1 ? replacementDiscoveries[0] : null;
+                        const replacementMilestone = task.milestoneId
+                            ? this.store.readMilestone(projectId, task.milestoneId)
+                            : null;
+                        guardedCorrectiveOverlay = {
+                            action: replacementDiscovery ? 'task replacement-materialize' : 'discovery start',
+                            ...(replacementDiscovery ? {} : { blockedAction: 'task replacement-materialize' }),
+                            stepId: guardedCorrectivePosture.stepId,
+                            correctiveDecisionGate: {
+                                attemptCount: guardedCorrectivePosture.attemptCount,
+                                decision: guardedCorrectivePosture.correctiveDecision?.decision ?? null,
+                                decisionEventId: guardedCorrectivePosture.correctiveDecision?.eventId ?? null,
+                                humanApprovalRequired: false,
+                            },
+                            replacementGate: {
+                                milestoneId: task.milestoneId,
+                                oldTaskId: task.id,
+                                requiredDiscoveryStatus: 'ready_to_materialize',
+                                oldMembershipDisposition: 'cancelled',
+                                replacementMembershipDisposition: 'required',
+                                transaction: 'journal-recoverable',
+                                discoveryCandidates: replacementDiscoveries.map((discovery) => ({
+                                    id: discovery.id,
+                                    revision: discovery.revision,
+                                    goal: discovery.goal,
+                                })),
+                                ...(replacementDiscovery && replacementMilestone
+                                    ? {
+                                        exactTransition: {
+                                            command: 'task replacement-materialize',
+                                            taskId: task.id,
+                                            expectedTaskRevision: task.revision,
+                                            discoveryId: replacementDiscovery.id,
+                                            expectedDiscoveryRevision: replacementDiscovery.revision,
+                                            milestoneId: replacementMilestone.id,
+                                            expectedMilestoneRevision: replacementMilestone.revision,
+                                        },
+                                    }
+                                    : {
+                                        requiredAction: replacementDiscoveries.length === 0
+                                            ? 'Create and complete one thin replacement Discovery, then run next again.'
+                                            : 'Select exactly one ready replacement Discovery explicitly; next will not guess between candidates.',
+                                    }),
+                            },
+                        };
+                    }
+                    break;
                 case 'stop-escalate':
                     guardedCorrectiveOverlay = {
                         action: 'doctor',
@@ -2624,6 +3059,34 @@ export class WorkflowService {
         }
         return result;
     }
+    assertTaskContextChangeAllowed(task) {
+        const posture = this.taskTerminalCorrectivePosture(task);
+        if (!posture)
+            return;
+        throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} has terminal corrective decision ${posture.posture}; Project Knowledge cannot rebind or refresh this Task.`, {
+            taskId: task.id,
+            stepId: posture.stepId,
+            decision: posture.posture,
+            decisionEventId: posture.correctiveDecision?.eventId ?? null,
+            requiredAction: posture.posture === 'split-required'
+                ? 'Materialize an atomic replacement Task through the exact replacement route.'
+                : 'Escalate outside this Task; stop-escalate cannot be resumed or rebound.',
+        });
+    }
+    taskHasTerminalCorrectiveDecision(task) {
+        return this.taskTerminalCorrectivePosture(task) !== null;
+    }
+    taskTerminalCorrectivePosture(task) {
+        if (!task.planHash)
+            return null;
+        const planRiskAudit = readCurrentPlanRiskAudit(this.store, task);
+        if (!planRiskAudit)
+            return null;
+        const posture = findCurrentGuardedRemediationPosture(this.store, task, planRiskAudit);
+        return posture?.posture === 'split-required' || posture?.posture === 'stop-escalate'
+            ? posture
+            : null;
+    }
     delegatedApprovalOptions(projectId, transition, target) {
         return this.store.listDelegations(projectId)
             .filter((grant) => {