codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/src/alpha6/milestone.js

@@ -2,9 +2,11 @@ import { existsSync, lstatSync, readFileSync, realpathSync, readdirSync, rmSync
 import path from 'node:path';
 import { WorkflowError } from '../errors.js';
 import { createEntityId } from '../ulid.js';
+import { readMilestoneAutonomyEvents } from '../alpha7/autonomy.js';
 import { createJournalSnapshotFromContent, captureJournalTargetSnapshot, listMilestoneTransactionJournals, readJournalSnapshotContent, removeMilestoneTransactionJournal, resolveMilestoneTransactionTargetPath, updateMilestoneTransactionJournalPhase, writeMilestoneTransactionJournal, } from './journal.js';
 import { assertHash64, assertNoSymlinkPathComponents, canonicalJsonStringify, computeSidecarEventHash, prepareSidecarAppend, sha256Hex, } from './store-sidecars.js';
 const SCOPE_CHANGE_SIDECAR = 'scope-change-events.jsonl';
+const INITIAL_PLAN_TARGETS = ['state.json', 'plan.json'];
 const MILESTONE_TARGETS = ['state.json', 'plan.json', SCOPE_CHANGE_SIDECAR];
 const SCOPE_CHANGE_ALLOWED_STATUSES = new Set([
     'planning',
@@ -67,22 +69,172 @@ export function prepareMilestoneScopeChangeBundle(options) {
     };
 }
 export function normalizeMilestonePlan(plan) {
-    return {
+    const normalized = {
         outcome: plan.outcome.trim(),
         successSignal: plan.successSignal.trim(),
         acceptance: [...plan.acceptance],
-        memberships: plan.memberships.map((membership) => ({
-            ...membership,
-            reason: membership.reason.trim(),
-        })),
+        memberships: plan.memberships.map((membership, index) => {
+            if (!membership || typeof membership !== 'object' || Array.isArray(membership)) {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Milestone membership must be an object.', {
+                    membershipIndex: index,
+                });
+            }
+            if (typeof membership.taskId !== 'string' || !membership.taskId.trim()) {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Milestone membership requires a Task ID.', {
+                    membershipIndex: index,
+                });
+            }
+            if (typeof membership.reason !== 'string') {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Milestone membership reason must be a string.', {
+                    membershipIndex: index,
+                    taskId: membership.taskId,
+                });
+            }
+            if (!Array.isArray(membership.dependsOnTaskIds)) {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Every Milestone membership must declare dependsOnTaskIds explicitly.', {
+                    membershipIndex: index,
+                    taskId: membership.taskId,
+                });
+            }
+            if (membership.dependsOnTaskIds.some((taskId) => typeof taskId !== 'string' || !taskId.trim())) {
+                throw new WorkflowError('INVALID_ARGUMENT', 'Milestone dependency IDs must be non-empty strings.', {
+                    membershipIndex: index,
+                    taskId: membership.taskId,
+                });
+            }
+            return {
+                taskId: membership.taskId.trim(),
+                disposition: membership.disposition,
+                reason: membership.reason.trim(),
+                dependsOnTaskIds: [...membership.dependsOnTaskIds].map((taskId) => taskId.trim()).sort(),
+            };
+        }),
         checks: [...plan.checks],
-        taskIds: plan.memberships.map((membership) => membership.taskId),
+        taskIds: plan.memberships.map((membership) => membership.taskId.trim()),
+    };
+    assertCanonicalMilestoneDependencyGraph(normalized.memberships, 'INVALID_ARGUMENT', 'Milestone Plan');
+    return normalized;
+}
+export function assessMilestoneTaskDependencies(milestone, taskId, readTask) {
+    const membership = milestone.memberships.find((candidate) => candidate.taskId === taskId);
+    if (!membership) {
+        return {
+            dependencyState: milestone.memberships.every((candidate) => Array.isArray(candidate.dependsOnTaskIds))
+                ? 'canonical'
+                : 'legacy-unknown',
+            dependsOnTaskIds: [],
+            unsatisfiedPredecessors: [],
+            runnable: false,
+            blockReason: `Task ${taskId} is not a Milestone member.`,
+        };
+    }
+    if (milestone.memberships.some((candidate) => !Array.isArray(candidate.dependsOnTaskIds))) {
+        return {
+            dependencyState: 'legacy-unknown',
+            dependsOnTaskIds: [],
+            unsatisfiedPredecessors: [],
+            runnable: false,
+            blockReason: 'Milestone dependency graph is unknown for this legacy nonterminal Plan.',
+        };
+    }
+    assertCanonicalMilestoneDependencyGraph(milestone.memberships, 'STATE_CORRUPT', `Milestone ${milestone.id}`);
+    const dependsOnTaskIds = [...(membership.dependsOnTaskIds ?? [])];
+    const unsatisfiedPredecessors = dependsOnTaskIds.flatMap((predecessorTaskId) => {
+        const predecessorMembership = milestone.memberships.find((candidate) => candidate.taskId === predecessorTaskId);
+        let predecessor = null;
+        try {
+            predecessor = readTask(predecessorTaskId);
+        }
+        catch (error) {
+            if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND')
+                throw error;
+        }
+        if (predecessorMembership?.disposition === 'required' && predecessor?.status === 'merged')
+            return [];
+        return [{
+                taskId: predecessorTaskId,
+                disposition: predecessorMembership?.disposition ?? 'missing',
+                status: predecessor?.status ?? 'missing',
+            }];
+    });
+    const runnable = membership.disposition === 'required' && unsatisfiedPredecessors.length === 0;
+    return {
+        dependencyState: 'canonical',
+        dependsOnTaskIds,
+        unsatisfiedPredecessors,
+        runnable,
+        blockReason: membership.disposition !== 'required'
+            ? `Milestone membership is ${membership.disposition}, not required.`
+            : unsatisfiedPredecessors.length > 0
+                ? 'Required predecessor Tasks have not all merged.'
+                : null,
     };
 }
+export function assertMilestoneDependenciesDeclared(milestone) {
+    if (milestone.memberships.some((membership) => !Array.isArray(membership.dependsOnTaskIds))) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} has no canonical dependency graph.`, {
+            diagnosticCode: 'MILESTONE_DEPENDENCIES_UNKNOWN',
+            milestoneId: milestone.id,
+            membershipRevision: milestone.membershipRevision,
+            requiredAction: 'Apply an explicit Milestone scope change containing dependsOnTaskIds for every membership.',
+        });
+    }
+    assertCanonicalMilestoneDependencyGraph(milestone.memberships, 'STATE_CORRUPT', `Milestone ${milestone.id}`);
+}
+export function assertMilestoneTaskRunnable(milestone, taskId, readTask) {
+    const assessment = assessMilestoneTaskDependencies(milestone, taskId, readTask);
+    if (milestone.status !== 'active' || !assessment.runnable) {
+        const diagnosticCode = assessment.dependencyState === 'legacy-unknown'
+            ? 'MILESTONE_DEPENDENCIES_UNKNOWN'
+            : milestone.status !== 'active'
+                ? 'MILESTONE_NOT_ACTIVE'
+                : assessment.unsatisfiedPredecessors.length > 0
+                    ? 'MILESTONE_PREDECESSORS_UNSATISFIED'
+                    : 'MILESTONE_MEMBERSHIP_NOT_REQUIRED';
+        throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not runnable in Milestone ${milestone.id}.`, {
+            diagnosticCode,
+            milestoneId: milestone.id,
+            milestoneStatus: milestone.status,
+            taskId,
+            ...assessment,
+            requiredAction: assessment.dependencyState === 'legacy-unknown'
+                ? 'Apply an explicit Milestone scope change containing dependsOnTaskIds for every membership.'
+                : milestone.status !== 'active'
+                    ? 'Authorize the current Milestone Plan before continuing this Task.'
+                    : assessment.unsatisfiedPredecessors.length > 0
+                        ? 'Merge every required predecessor Task before continuing this Task.'
+                        : 'Restore a required Milestone membership before continuing this Task.',
+        });
+    }
+    return assessment;
+}
 export function readMilestoneWithIntegrity(store, projectId, milestoneId, readTask, listTasks) {
     recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask);
     const milestone = store.readMilestone(projectId, milestoneId);
     assertMilestonePlanAgreement(store, milestone);
+    const initialAssembly = assessMilestoneInitialAssembly({
+        store,
+        projectId,
+        milestone,
+        ...(listTasks ? { listTasks } : {}),
+    });
+    if (initialAssembly.eligible)
+        return milestone;
+    assertMilestoneMembershipIntegrity(milestone, readTask, {}, listTasks);
+    return milestone;
+}
+/** Read-only integrity validation for observation APIs. Pending journals must be assessed first. */
+export function inspectMilestoneWithIntegrity(store, projectId, milestoneId, readTask, listTasks) {
+    const milestone = store.readMilestone(projectId, milestoneId);
+    assertMilestonePlanAgreement(store, milestone);
+    const initialAssembly = assessMilestoneInitialAssembly({
+        store,
+        projectId,
+        milestone,
+        ...(listTasks ? { listTasks } : {}),
+    });
+    if (initialAssembly.eligible)
+        return milestone;
     assertMilestoneMembershipIntegrity(milestone, readTask, {}, listTasks);
     return milestone;
 }
@@ -90,6 +242,14 @@ export function readMilestoneForScopeChange(store, projectId, milestoneId, readT
     recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask);
     const milestone = store.readMilestone(projectId, milestoneId);
     assertMilestonePlanAgreement(store, milestone);
+    const initialAssembly = assessMilestoneInitialAssembly({
+        store,
+        projectId,
+        milestone,
+        ...(listTasks ? { listTasks } : {}),
+    });
+    if (initialAssembly.eligible)
+        return milestone;
     assertMilestoneMembershipIntegrity(milestone, readTask, { allowRepairableRequiredCancelled: true, allowRepairableReverseOrphans: true }, listTasks);
     return milestone;
 }
@@ -102,6 +262,37 @@ export function listMilestonesWithIntegrity(store, projectId, readTask, listTask
         .map((entry) => readMilestoneWithIntegrity(store, projectId, entry.name, readTask, listTasks))
         .sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
 }
+export function assessMilestoneInitialAssembly(options) {
+    const { milestone, listTasks } = options;
+    if (!listTasks)
+        return { eligible: false, orphanTaskIds: [] };
+    if (milestone.status !== 'planning'
+        || milestone.planHash !== null
+        || milestone.membershipRevision !== 0
+        || milestone.memberships.length !== 0
+        || milestone.taskIds.length !== 0
+        || milestone.successSignal !== ''
+        || milestone.checks.length !== 0
+        || milestone.authorizations.length !== 0
+        || milestone.resultHash !== null
+        || milestone.evidenceHash !== null
+        || milestone.acceptedHead !== null
+        || milestone.cancellationReason !== null) {
+        return { eligible: false, orphanTaskIds: [] };
+    }
+    const reverseOrphans = listTasks().filter((task) => task.milestoneId === milestone.id);
+    if (hasActiveMilestoneScopeChangeTransaction(options.store, options.projectId, milestone.id)) {
+        return { eligible: false, orphanTaskIds: reverseOrphans.map((task) => task.id) };
+    }
+    if (readMilestoneScopeChangeEvents(options.store, options.projectId, milestone.id).length > 0) {
+        return { eligible: false, orphanTaskIds: reverseOrphans.map((task) => task.id) };
+    }
+    if (hasMilestoneAutonomyAuthority(options.store, options.projectId, milestone.id)) {
+        return { eligible: false, orphanTaskIds: reverseOrphans.map((task) => task.id) };
+    }
+    const eligible = reverseOrphans.every((task) => isPristineInitialAssemblyTask(task));
+    return { eligible, orphanTaskIds: reverseOrphans.map((task) => task.id) };
+}
 export function assertMilestoneMembershipIntegrity(milestone, readTask, options = {}, listTasks) {
     if (!Number.isInteger(milestone.membershipRevision) || milestone.membershipRevision < 0) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} has invalid membershipRevision.`, {
@@ -129,6 +320,17 @@ export function assertMilestoneMembershipIntegrity(milestone, readTask, options
             membershipTaskIds,
         });
     }
+    const dependencyArraysPresent = milestone.memberships.filter((membership) => Array.isArray(membership.dependsOnTaskIds)).length;
+    if (dependencyArraysPresent > 0 && dependencyArraysPresent !== milestone.memberships.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} mixes canonical and legacy dependency memberships.`, {
+            diagnosticCode: 'MILESTONE_DEPENDENCY_GRAPH_PARTIAL',
+            canonicalMemberships: dependencyArraysPresent,
+            totalMemberships: milestone.memberships.length,
+        });
+    }
+    if (dependencyArraysPresent === milestone.memberships.length && milestone.memberships.length > 0) {
+        assertCanonicalMilestoneDependencyGraph(milestone.memberships, 'STATE_CORRUPT', `Milestone ${milestone.id}`);
+    }
     for (const membership of milestone.memberships) {
         const task = readTask(membership.taskId);
         if (task.milestoneId !== milestone.id) {
@@ -169,6 +371,113 @@ export function assertMilestoneMembershipIntegrity(milestone, readTask, options
         }
     }
 }
+function assertCanonicalMilestoneDependencyGraph(memberships, code, label) {
+    const byTaskId = new Map(memberships.map((membership) => [membership.taskId, membership]));
+    if (byTaskId.size !== memberships.length) {
+        throw new WorkflowError(code, `${label} memberships contain duplicate Task IDs.`);
+    }
+    for (const membership of memberships) {
+        if (!Array.isArray(membership.dependsOnTaskIds)) {
+            throw new WorkflowError(code, `${label} membership ${membership.taskId} is missing dependsOnTaskIds.`);
+        }
+        if (new Set(membership.dependsOnTaskIds).size !== membership.dependsOnTaskIds.length) {
+            throw new WorkflowError(code, `${label} membership ${membership.taskId} contains duplicate dependencies.`, {
+                taskId: membership.taskId,
+                dependsOnTaskIds: membership.dependsOnTaskIds,
+            });
+        }
+        if (membership.dependsOnTaskIds.some((taskId) => !taskId)) {
+            throw new WorkflowError(code, `${label} membership ${membership.taskId} contains an empty dependency.`);
+        }
+        const sorted = [...membership.dependsOnTaskIds].sort();
+        if (canonicalJsonStringify(sorted) !== canonicalJsonStringify(membership.dependsOnTaskIds)) {
+            throw new WorkflowError(code, `${label} membership ${membership.taskId} dependencies are not canonical.`, {
+                taskId: membership.taskId,
+                expected: sorted,
+                actual: membership.dependsOnTaskIds,
+            });
+        }
+        if (membership.dependsOnTaskIds.includes(membership.taskId)) {
+            throw new WorkflowError(code, `${label} membership ${membership.taskId} cannot depend on itself.`);
+        }
+        for (const predecessorTaskId of membership.dependsOnTaskIds) {
+            const predecessor = byTaskId.get(predecessorTaskId);
+            if (!predecessor) {
+                throw new WorkflowError(code, `${label} membership ${membership.taskId} has a dangling dependency.`, {
+                    taskId: membership.taskId,
+                    predecessorTaskId,
+                });
+            }
+            if (membership.disposition === 'required' && predecessor.disposition !== 'required') {
+                throw new WorkflowError(code, `${label} required membership ${membership.taskId} depends on a non-required provider.`, {
+                    taskId: membership.taskId,
+                    predecessorTaskId,
+                    predecessorDisposition: predecessor.disposition,
+                });
+            }
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (taskId, path) => {
+        if (visiting.has(taskId)) {
+            const cycleStart = path.indexOf(taskId);
+            throw new WorkflowError(code, `${label} dependency graph contains a cycle.`, {
+                cycle: [...path.slice(Math.max(cycleStart, 0)), taskId],
+            });
+        }
+        if (visited.has(taskId))
+            return;
+        visiting.add(taskId);
+        const membership = byTaskId.get(taskId);
+        for (const predecessorTaskId of membership.dependsOnTaskIds) {
+            visit(predecessorTaskId, [...path, taskId]);
+        }
+        visiting.delete(taskId);
+        visited.add(taskId);
+    };
+    for (const membership of memberships)
+        visit(membership.taskId, []);
+}
+function hasActiveMilestoneScopeChangeTransaction(store, projectId, milestoneId) {
+    const milestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+    return listMilestoneTransactionJournals(milestoneRoot, { expectedMilestoneId: milestoneId })
+        .some((journal) => journal.phase === 'prepared' || journal.phase === 'applying');
+}
+function hasMilestoneAutonomyAuthority(store, projectId, milestoneId) {
+    return readMilestoneAutonomyEvents(store, projectId, milestoneId).length > 0;
+}
+function isPristineInitialAssemblyTask(task) {
+    return task.status === 'planning'
+        && task.workspaceOwner === null
+        && task.taskBranch === null
+        && task.baseCommit === null
+        && task.planHash === null
+        && task.planObjective === null
+        && task.resultHash === null
+        && task.evidenceHash === null
+        && task.knowledgeImpact === null
+        && task.knowledgeImpactReason === null
+        && task.knowledgeTargets.length === 0
+        && task.knowledgeMapRevision === null
+        && task.knowledgeMapHash === null
+        && task.graphUse === null
+        && task.steps.length === 0
+        && task.authorizations.length === 0
+        && task.knowledgeRebinds.length === 0
+        && task.review.status === 'pending'
+        && task.review.reviewer === ''
+        && task.review.recordedAt === null
+        && task.review.headCommit === null
+        && task.review.briefHash === null
+        && task.review.planHash === null
+        && task.review.evidenceHash === null
+        && task.review.summary === ''
+        && task.review.findings.length === 0
+        && task.blockReason === null
+        && task.mergedCommit === null
+        && task.systemCommits.length === 0;
+}
 export function assertMilestoneScopeChangeStatusAllowed(milestone) {
     if (!SCOPE_CHANGE_ALLOWED_STATUSES.has(milestone.status)) {
         throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} cannot change scope while ${milestone.status}.`, {
@@ -381,6 +690,90 @@ export function applyMilestoneScopeChangeTransaction(options) {
         expectedRevisionAfterApply: expectedRevision + 1,
     });
 }
+export function applyInitialMilestonePlanTransaction(options) {
+    const { store, milestone, expectedRevision, normalizedPlan, now, readTask, listTasks } = options;
+    if (milestone.status !== 'planning'
+        || milestone.planHash !== null
+        || milestone.membershipRevision !== 0
+        || milestone.taskIds.length > 0
+        || milestone.memberships.length > 0) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} is not in the initial Plan posture.`);
+    }
+    const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
+    const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, milestone.projectId, milestone.id);
+    const planText = renderMilestonePlanArtifact(normalizedPlan);
+    const stagedPlan = store.stageArtifact(milestoneRoot, 'plan.json', planText);
+    const authorizations = milestone.authorizations.map((authorization) => authorization.kind === 'execution' && authorization.decision === 'approved'
+        ? { ...authorization, decision: 'superseded' }
+        : authorization);
+    const candidateState = {
+        ...milestone,
+        revision: milestone.revision + 1,
+        updatedAt: now.toISOString(),
+        status: 'awaiting_execution_authorization',
+        outcome: normalizedPlan.outcome,
+        successSignal: normalizedPlan.successSignal,
+        acceptance: normalizedPlan.acceptance,
+        taskIds: normalizedPlan.taskIds,
+        memberships: normalizedPlan.memberships,
+        checks: normalizedPlan.checks,
+        membershipRevision: 1,
+        authorizations,
+        planHash: stagedPlan.hash,
+        resultHash: null,
+        evidenceHash: null,
+        acceptedHead: null,
+        cancellationReason: null,
+    };
+    assertMilestoneMembershipIntegrity(candidateState, readTask, {}, listTasks);
+    const stagedState = store.stageArtifact(milestoneRoot, 'state.json', `${JSON.stringify(candidateState, null, 2)}\n`);
+    const transactionId = `tx-${createEntityId('MS', now.getTime())}`;
+    const actor = 'workflow:milestone-plan-set';
+    const confirmationCodeBindingHash = sha256Hex(canonicalJsonStringify({
+        kind: 'milestone-initial-plan-v1',
+        milestoneId: milestone.id,
+        expectedRevision,
+        planHash: stagedPlan.hash,
+        membershipRevision: candidateState.membershipRevision,
+    }));
+    const journal = {
+        transactionId,
+        milestoneId: milestone.id,
+        expectedMilestoneRevision: milestone.revision,
+        actor,
+        confirmationCodeBindingHash,
+        phase: 'prepared',
+        targetFiles: [
+            {
+                path: 'state.json',
+                preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, 'state.json'),
+                staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedState.stagedFile), { mode: 'inline' }),
+            },
+            {
+                path: 'plan.json',
+                preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, 'plan.json'),
+                staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedPlan.stagedFile), { mode: 'inline' }),
+            },
+        ],
+        preparedAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+    };
+    writeMilestoneTransactionJournal(alpha6MilestoneRoot, journal);
+    try {
+        updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, transactionId, 'applying', now.toISOString(), {
+            expectedMilestoneId: milestone.id,
+        });
+        store.publishArtifact(stagedPlan);
+        store.publishArtifact(stagedState);
+    }
+    catch (error) {
+        rollbackMilestoneTransaction(store, milestone.projectId, milestone.id, journal, readTask);
+        throw error;
+    }
+    return finalizeCompletedMilestoneTransaction(store, milestone.projectId, milestone.id, journal, readTask, {
+        expectedRevisionAfterApply: expectedRevision + 1,
+    });
+}
 function recoverMilestoneScopeChangeTransactions(store, projectId, milestoneId, readTask) {
     const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
     const transactionDir = path.join(alpha6MilestoneRoot, '.transactions');
@@ -406,7 +799,17 @@ function assertMilestonePlanAgreement(store, milestone) {
     if (milestone.planHash === null)
         return;
     const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
-    const currentPlanHash = store.hashArtifact(milestoneRoot, 'plan.json');
+    let currentPlanHash;
+    try {
+        currentPlanHash = store.hashArtifact(milestoneRoot, 'plan.json');
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} declares a planHash but plan.json is unavailable.`, {
+            milestoneId: milestone.id,
+            expectedPlanHash: milestone.planHash,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
     if (currentPlanHash !== milestone.planHash) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} planHash does not match plan.json.`, {
             expectedPlanHash: milestone.planHash,
@@ -531,12 +934,13 @@ function validateMilestoneScopeChangeEvent(event, expectedMilestoneId) {
 function validateMilestoneTransactionTargets(journal) {
     const paths = journal.targetFiles.map((target) => target.path);
     const unique = new Set(paths);
-    if (unique.size !== MILESTONE_TARGETS.length || paths.length !== MILESTONE_TARGETS.length) {
+    const expectedTargets = unique.has(SCOPE_CHANGE_SIDECAR) ? MILESTONE_TARGETS : INITIAL_PLAN_TARGETS;
+    if (unique.size !== expectedTargets.length || paths.length !== expectedTargets.length) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} target set is invalid.`, {
             paths,
         });
     }
-    for (const target of MILESTONE_TARGETS) {
+    for (const target of expectedTargets) {
         if (!unique.has(target)) {
             throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing ${target}.`);
         }
@@ -647,7 +1051,7 @@ function readStagedMilestoneTransactionBundle(store, projectId, milestoneId, jou
     const stateSnapshot = journal.targetFiles.find((target) => target.path === 'state.json')?.staged;
     const planSnapshot = journal.targetFiles.find((target) => target.path === 'plan.json')?.staged;
     const sidecarSnapshot = journal.targetFiles.find((target) => target.path === SCOPE_CHANGE_SIDECAR)?.staged;
-    if (!stateSnapshot || !planSnapshot || !sidecarSnapshot) {
+    if (!stateSnapshot || !planSnapshot) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing a staged bundle.`);
     }
     const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
@@ -659,26 +1063,27 @@ function readStagedMilestoneTransactionBundle(store, projectId, milestoneId, jou
         expectedMilestoneId: milestoneId,
         transactionId: journal.transactionId,
     });
-    const sidecarBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, sidecarSnapshot, {
-        expectedMilestoneId: milestoneId,
-        transactionId: journal.transactionId,
-    });
-    if (!stateBuffer || !planBuffer || !sidecarBuffer) {
+    const sidecarBuffer = sidecarSnapshot
+        ? readJournalSnapshotContent(alpha6MilestoneRoot, sidecarSnapshot, {
+            expectedMilestoneId: milestoneId,
+            transactionId: journal.transactionId,
+        })
+        : null;
+    if (!stateBuffer || !planBuffer || (sidecarSnapshot && !sidecarBuffer)) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} has an incomplete staged bundle.`);
     }
     const state = parseStagedMilestoneStateArtifact(stateBuffer.toString('utf8'), projectId, journal.milestoneId, journal.transactionId);
     const plan = parseMilestonePlanArtifact(planBuffer.toString('utf8'), journal.milestoneId);
-    const events = parseMilestoneScopeChangeEvents(sidecarBuffer.toString('utf8'), journal.milestoneId);
-    const latestEvent = events.at(-1);
-    if (!latestEvent) {
-        throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} has no staged scope-change event.`);
-    }
-    if (latestEvent.candidatePlanHash !== state.planHash
-        || latestEvent.candidateMembershipRevision !== state.membershipRevision
-        || canonicalJsonStringify(latestEvent.after) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
-        || canonicalJsonStringify(milestoneScopeSnapshotFromPlan(plan)) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
-        || latestEvent.actor !== journal.actor
-        || latestEvent.confirmationCodeBindingHash !== journal.confirmationCodeBindingHash) {
+    const events = sidecarBuffer
+        ? parseMilestoneScopeChangeEvents(sidecarBuffer.toString('utf8'), journal.milestoneId)
+        : [];
+    const latestEvent = events.at(-1) ?? null;
+    if (canonicalJsonStringify(milestoneScopeSnapshotFromPlan(plan)) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
+        || (latestEvent !== null && (latestEvent.candidatePlanHash !== state.planHash
+            || latestEvent.candidateMembershipRevision !== state.membershipRevision
+            || canonicalJsonStringify(latestEvent.after) !== canonicalJsonStringify(milestoneScopeSnapshotFromState(state))
+            || latestEvent.actor !== journal.actor
+            || latestEvent.confirmationCodeBindingHash !== journal.confirmationCodeBindingHash))) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} staged bundle is inconsistent.`);
     }
     if (state.revision !== journal.expectedMilestoneRevision + 1) {
@@ -687,7 +1092,7 @@ function readStagedMilestoneTransactionBundle(store, projectId, milestoneId, jou
             actualRevision: state.revision,
         });
     }
-    if (latestEvent.previousMilestoneRevision !== journal.expectedMilestoneRevision) {
+    if (latestEvent && latestEvent.previousMilestoneRevision !== journal.expectedMilestoneRevision) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} latest event revision does not match journal precondition.`, {
             expectedPreviousMilestoneRevision: journal.expectedMilestoneRevision,
             actualPreviousMilestoneRevision: latestEvent.previousMilestoneRevision,
@@ -725,13 +1130,21 @@ function parseMilestonePlanArtifact(content, milestoneId) {
     const acceptance = parseStringArray(record.acceptance, `Milestone ${milestoneId} plan.json acceptance`);
     const checks = parseStringArray(record.checks, `Milestone ${milestoneId} plan.json checks`);
     const memberships = parseMilestoneMembershipArray(record.memberships, milestoneId);
-    return normalizeMilestonePlan({
-        outcome: record.outcome,
-        successSignal: record.successSignal,
+    const canonicalMembershipCount = memberships.filter((membership) => Array.isArray(membership.dependsOnTaskIds)).length;
+    if (canonicalMembershipCount > 0 && canonicalMembershipCount !== memberships.length) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json mixes canonical and legacy dependency memberships.`);
+    }
+    if (canonicalMembershipCount === memberships.length) {
+        assertCanonicalMilestoneDependencyGraph(memberships, 'STATE_CORRUPT', `Milestone ${milestoneId} plan.json`);
+    }
+    return {
+        outcome: record.outcome.trim(),
+        successSignal: record.successSignal.trim(),
         acceptance,
         memberships,
         checks,
-    });
+        taskIds: memberships.map((membership) => membership.taskId),
+    };
 }
 function parseMilestoneScopeChangeEvents(content, milestoneId) {
     if (content.length === 0) {
@@ -949,7 +1362,7 @@ function parseMilestoneMembership(value, milestoneId, index, line) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership at index ${index} must be an object.`, line !== undefined ? { line, index } : { index });
     }
     const record = value;
-    const allowedKeys = new Set(['taskId', 'disposition', 'reason']);
+    const allowedKeys = new Set(['taskId', 'disposition', 'reason', 'dependsOnTaskIds']);
     const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
     if (extraKeys.length > 0) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership contains unexpected fields.`, line !== undefined ? { line, index, extraKeys } : { index, extraKeys });
@@ -964,7 +1377,33 @@ function parseMilestoneMembership(value, milestoneId, index, line) {
     if (disposition !== 'required' && reason.length === 0) {
         throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership ${disposition} requires a reason.`, line !== undefined ? { line, index } : { index });
     }
-    return { taskId, disposition, reason };
+    const dependsOnTaskIds = record.dependsOnTaskIds === undefined
+        ? undefined
+        : parseTaskDependencyArray(record.dependsOnTaskIds, `Milestone ${milestoneId} membership.dependsOnTaskIds`, line !== undefined ? { line, index } : { index });
+    return {
+        taskId,
+        disposition,
+        reason,
+        ...(dependsOnTaskIds === undefined ? {} : { dependsOnTaskIds }),
+    };
+}
+function parseTaskDependencyArray(value, label, details = {}) {
+    if (!Array.isArray(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be an array.`, details);
+    }
+    const taskIds = value.map((entry, index) => {
+        if (typeof entry !== 'string' || !entry.trim()) {
+            throw new WorkflowError('STATE_CORRUPT', `${label}[${index}] must be a non-empty Task ID.`, {
+                ...details,
+                index,
+            });
+        }
+        return entry.trim();
+    });
+    if (new Set(taskIds).size !== taskIds.length) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} contains duplicate Task IDs.`, { ...details, taskIds });
+    }
+    return taskIds;
 }
 function parseStringArray(value, label, details = {}) {
     if (!Array.isArray(value) || value.length === 0) {