codex-workflow-v2 2.0.0-alpha.7.2.1 → 2.0.0-beta.2

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, appendRemediationModeRecovery, assertCorrectiveAuditorIndependence, assertGuardedRemediationAttemptAllowed, defaultCorrectiveAuditorActor, findCurrentGuardedRemediationPosture, findRemediationModeRecoveryCandidate, findFailedGuardedStepRequiringCorrectiveDecision, readGuardedRemediationPostureForStep, readCorrectiveDecisionEvents, readRemediationEvents, } from './alpha6/remediation.js';
-import { applyMilestoneScopeChangeTransaction, assertMilestoneMembershipIntegrity, assertMilestoneScopeChangeStatusAllowed, normalizeMilestonePlan, prepareMilestoneScopeChangeCandidate, readMilestoneForScopeChange, readMilestoneWithIntegrity, } from './alpha6/milestone.js';
+import { assessMilestoneInitialAssembly, 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);
@@ -1871,11 +2154,15 @@ export class WorkflowService {
         const tasks = this.store.listTasks(identity.projectId);
         const rawMilestones = this.store.listMilestones(identity.projectId);
         const adoption = this.inspectAdoptionPreparation(identity, tasks, rawMilestones);
+        const milestones = this.listMilestonesCurrent(identity.projectId, adoption.currentPosture);
         return {
             projectId: identity.projectId,
             discoveries: this.store.listDiscoveries(identity.projectId),
             tasks,
-            milestones: this.listMilestonesCurrent(identity.projectId, adoption.currentPosture),
+            milestones,
+            milestoneInitialAssembly: milestones
+                .map((milestone) => this.describeMilestoneInitialAssembly(identity.projectId, milestone, tasks))
+                .filter((value) => value !== null),
             delegations: this.store.listDelegations(identity.projectId),
             adoption,
         };
@@ -1921,11 +2208,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,
@@ -1952,6 +2262,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,
         };
     }
@@ -2101,11 +2425,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') {
@@ -2168,10 +2511,13 @@ export class WorkflowService {
             // 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) {
+                || hardStop
+                || terminalCorrectiveDecision === 'split-required'
+                || terminalCorrectiveDecision === 'stop-escalate') {
                 return withAdoption(taskNext);
             }
             if (!taskCanRebindKnowledge(activeTask) && activeTask.status !== 'planning') {
@@ -2194,11 +2540,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
                         ? {
@@ -2240,6 +2592,31 @@ export class WorkflowService {
         }
         const activeMilestone = status.milestones.find((milestone) => !['accepted', 'cancelled'].includes(milestone.status));
         if (activeMilestone) {
+            const initialAssembly = status.milestoneInitialAssembly
+                .find((candidate) => candidate.milestoneId === activeMilestone.id) ?? null;
+            if (initialAssembly) {
+                const activeDiscovery = status.discoveries.find((discovery) => !['materialized', 'abandoned'].includes(discovery.status));
+                if (activeDiscovery) {
+                    return withAdoption({
+                        scope: 'discovery',
+                        id: activeDiscovery.id,
+                        status: activeDiscovery.status,
+                        action: activeDiscovery.status === 'ready_to_materialize' ? 'discovery materialize' : 'discovery update',
+                        readiness: assessDiscovery(activeDiscovery),
+                        milestoneInitialAssembly: initialAssembly,
+                    });
+                }
+                return withAdoption({
+                    scope: 'milestone',
+                    id: activeMilestone.id,
+                    status: activeMilestone.status,
+                    action: 'milestone initial-assembly',
+                    revision: activeMilestone.revision,
+                    linkedTaskIds: initialAssembly.linkedTaskIds,
+                    executionAvailable: initialAssembly.executionAvailable,
+                    milestoneInitialAssembly: initialAssembly,
+                });
+            }
             if (activeMilestone.status === 'awaiting_final_acceptance') {
                 const root = this.store.milestoneRoot(activeMilestone.projectId, activeMilestone.id);
                 const evidence = JSON.parse(readFileSync(path.join(root, 'evidence.json'), 'utf8'));
@@ -2446,7 +2823,7 @@ export class WorkflowService {
                     throw error;
             }
         }
-        const next = nextForTask(task);
+        const next = this.taskGitNavigationOverride(task) ?? nextForTask(task);
         const handoffPosture = readTaskC1Posture(this.store, task);
         const strictStepReviewStep = planRiskAudit
             ? task.steps.find((step) => {
@@ -2593,6 +2970,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',
@@ -2653,13 +3080,59 @@ export class WorkflowService {
             ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
         };
         if (handoffPosture.state === 'pending') {
-            return {
+            return this.withTaskNavigationContracts(task, {
                 ...result,
                 action: 'task claim',
                 blockedAction: next.action,
-            };
+            });
         }
-        return result;
+        const navigableResult = ['task plan-set', 'task plan-set with independent corrective audit']
+            .includes(String(result.action))
+            ? {
+                ...result,
+                taskPlanContract: this.taskPlanContract(projectId, task),
+            }
+            : result;
+        return this.withTaskNavigationContracts(task, navigableResult);
+    }
+    taskPlanContract(projectId, task) {
+        const map = this.store.readKnowledgeMap(projectId);
+        return {
+            requiredRequirementIds: [...task.requirements],
+            requiredAcceptanceIds: [...task.acceptance],
+            currentRisks: [...task.risks],
+            exactInclusionRequired: true,
+            briefHash: task.briefHash,
+            knowledgeMap: knowledgeSummary(map),
+        };
+    }
+    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)
@@ -2779,6 +3252,70 @@ export class WorkflowService {
             ? milestone
             : readMilestoneWithIntegrity(this.store, projectId, milestone.id, (taskId) => this.store.readTask(projectId, taskId), () => this.store.listTasks(projectId))));
     }
+    taskGitNavigationOverride(task) {
+        if (task.status !== 'merging' || task.workspaceOwner !== 'local' || !task.baseCommit || !task.taskBranch) {
+            return null;
+        }
+        const currentBase = runGit(task.repositoryRoot, ['rev-parse', task.baseBranch]);
+        if (currentBase === task.baseCommit)
+            return null;
+        return {
+            scope: 'task',
+            id: task.id,
+            status: task.status,
+            action: 'task sync-base',
+            revision: task.revision,
+            baseSyncRequired: {
+                baseBranch: task.baseBranch,
+                recordedBaseCommit: task.baseCommit,
+                currentBaseCommit: currentBase,
+            },
+        };
+    }
+    withTaskNavigationContracts(task, next) {
+        const action = typeof next.action === 'string' ? next.action : null;
+        if (!action)
+            return next;
+        const policy = gitMutationPolicyForAction(task, action);
+        const claimedC1Posture = readTaskC1Posture(this.store, task).state === 'claimed';
+        const writerTokenContract = writerTokenContractForAction(action, claimedC1Posture);
+        return {
+            ...next,
+            ...(policy ? { gitMutationPolicy: policy } : {}),
+            ...(writerTokenContract ? { writerTokenContract } : {}),
+        };
+    }
+    describeMilestoneInitialAssembly(projectId, milestone, tasks) {
+        const assessment = assessMilestoneInitialAssembly({
+            store: this.store,
+            projectId,
+            milestone,
+            listTasks: () => tasks,
+        });
+        if (!assessment.eligible)
+            return null;
+        const options = [
+            {
+                action: 'linked-task-assembly',
+                commands: ['discovery start', 'discovery materialize'],
+                description: 'Start or materialize the next linked Task Discovery for this Milestone before closing the initial membership Plan.',
+            },
+        ];
+        if (assessment.orphanTaskIds.length > 0) {
+            options.push({
+                action: 'milestone plan-set',
+                commands: ['milestone plan-set'],
+                description: 'Record one complete initial Milestone Plan that classifies every currently linked Task.',
+            });
+        }
+        return {
+            milestoneId: milestone.id,
+            revision: milestone.revision,
+            linkedTaskIds: assessment.orphanTaskIds,
+            executionAvailable: false,
+            options,
+        };
+    }
     prepareMilestoneScopeChangeCandidate(projectId, milestone, plan, actor) {
         validateMilestonePlan(plan);
         return prepareMilestoneScopeChangeCandidate({
@@ -3434,13 +3971,13 @@ function nextForTask(task) {
         awaiting_execution_authorization: 'task authorize',
         ready: task.workspaceOwner ? (stepsComplete ? 'task submit' : 'task run') : 'task start',
         in_progress: activeStep ? 'task step-complete' : stepsComplete ? 'task submit' : 'task run',
-        validating: task.review.status === 'passed' ? 'task result-set' : 'task review-record',
+        validating: task.review.status === 'passed' ? 'task result-set' : 'task review-launch',
         needs_fix: task.steps.some((step) => step.status === 'failed') ? 'task run' : 'task plan-set',
         awaiting_final_acceptance: 'task accept',
         merging: 'task merge',
         ready_to_merge: 'task merge-confirm',
         merged: 'none',
-        blocked: task.review.status === 'unverified' ? 'task review-record' : 'doctor',
+        blocked: task.review.status === 'unverified' ? 'task review-launch' : 'doctor',
         cancelled: 'none',
     };
     const selectedStep = activeStep ?? failedStep ?? runnableStep;
@@ -3462,6 +3999,73 @@ function nextForTask(task) {
             : {}),
     };
 }
+function gitMutationPolicyForAction(task, action) {
+    const metadataWrites = ['.git/index', '.git/index.lock', '.git/HEAD', '.git/refs', '.git/logs'];
+    switch (action) {
+        case 'task start':
+            return {
+                permission: 'git-metadata-write',
+                requiredBeforeFirstCall: true,
+                boundedToTransition: true,
+                transition: 'task start',
+                appliesWhen: { workspaceOwner: 'local' },
+                metadataWrites,
+            };
+        case 'task step-complete':
+            return {
+                permission: 'git-metadata-write',
+                requiredBeforeFirstCall: true,
+                boundedToTransition: true,
+                transition: 'task step-complete',
+                metadataWrites,
+            };
+        case 'task merge':
+            if (task.workspaceOwner !== 'local')
+                return null;
+            return {
+                permission: 'git-metadata-write',
+                requiredBeforeFirstCall: true,
+                boundedToTransition: true,
+                transition: 'task merge',
+                metadataWrites,
+            };
+        case 'task sync-base':
+            return {
+                permission: 'git-metadata-write',
+                requiredBeforeFirstCall: true,
+                boundedToTransition: true,
+                transition: 'task sync-base',
+                metadataWrites,
+            };
+        default:
+            return null;
+    }
+}
+function writerTokenContractForAction(action, claimedC1Posture = false) {
+    const alwaysLeaseBound = ['task step-complete', 'task submit', 'task merge', 'task merge-confirm'];
+    const claimedC1LeaseBound = [
+        'task run',
+        'task step-review',
+        'task review-record',
+        'task review-launch',
+        'task corrective-decision-recover',
+        'task remediation-mode-recover',
+        'task corrective-decision',
+        'task handoff',
+        'task handoff-prepare',
+        'task handback',
+        'task handback-create',
+    ];
+    if (!alwaysLeaseBound.includes(action) && !(claimedC1Posture && claimedC1LeaseBound.includes(action))) {
+        return null;
+    }
+    return {
+        required: true,
+        option: '--writer-token',
+        source: 'active-writer-lease',
+        sensitive: true,
+    };
+}
 function knowledgeSummary(map) {
     return {
         revision: map.revision,