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

package/src/alpha6/milestone.ts

@@ -0,0 +1,2192 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import type {
+  AuditedRemediationEvidence,
+  AuthorizationEvent,
+  MilestoneFinalAcceptanceGate,
+  MilestoneMembership,
+  MilestonePlanInput,
+  MilestonePlanMembershipInput,
+  MilestoneScopeChangeEvent,
+  MilestoneScopeSnapshot,
+  MilestoneState,
+  MilestoneTransactionJournal,
+  TaskState,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import type { FileStateStore } from '../state/store.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';
+
+type ReadTask = (taskId: string) => TaskState;
+type ListTasks = () => TaskState[];
+
+const SCOPE_CHANGE_SIDECAR = 'scope-change-events.jsonl';
+const INITIAL_PLAN_TARGETS = ['state.json', 'plan.json'] as const;
+const MILESTONE_TARGETS = ['state.json', 'plan.json', SCOPE_CHANGE_SIDECAR] as const;
+const SCOPE_CHANGE_ALLOWED_STATUSES = new Set<MilestoneState['status']>([
+  'planning',
+  'awaiting_execution_authorization',
+  'active',
+  'blocked',
+]);
+
+interface MembershipIntegrityOptions {
+  allowRepairableRequiredCancelled?: boolean;
+  allowRepairableReverseOrphans?: boolean;
+}
+
+export interface MilestoneInitialAssemblyAssessment {
+  eligible: boolean;
+  orphanTaskIds: string[];
+}
+
+export interface NormalizedMilestonePlan {
+  outcome: string;
+  successSignal: string;
+  acceptance: string[];
+  memberships: MilestonePlanMembershipInput[];
+  checks: string[];
+  taskIds: string[];
+}
+
+interface PersistedMilestonePlan {
+  outcome: string;
+  successSignal: string;
+  acceptance: string[];
+  memberships: MilestoneMembership[];
+  checks: string[];
+  taskIds: string[];
+}
+
+export interface MilestoneTaskDependencyAssessment {
+  dependencyState: 'canonical' | 'legacy-unknown';
+  dependsOnTaskIds: string[];
+  unsatisfiedPredecessors: Array<{
+    taskId: string;
+    disposition: MilestoneMembership['disposition'] | 'missing';
+    status: TaskState['status'] | 'missing';
+  }>;
+  runnable: boolean;
+  blockReason: string | null;
+}
+
+export interface PreparedMilestoneScopeChange {
+  milestoneId: string;
+  expectedRevision: number;
+  actor: string;
+  normalizedPlan: NormalizedMilestonePlan;
+  authorizations: AuthorizationEvent[];
+  candidatePlanHash: string;
+  candidateMembershipRevision: number;
+  after: MilestoneScopeSnapshot;
+  confirmationCodeBindingHash: string;
+  confirmationCode: string;
+  authorizationMode: 'human' | 'milestone-autonomy' | 'audited-remediation';
+  autonomyContractEventHash: string | null;
+  remediationEvidence: AuditedRemediationEvidence | null;
+  resultingStatus: MilestoneState['status'];
+}
+
+export interface PreparedMilestoneScopeChangeBundle {
+  state: MilestoneState;
+  stateContent: string;
+  planContent: string;
+  sidecarContent: string;
+}
+
+/**
+ * Produces the exact three-file Milestone commit without writing it. Beta transactions use this
+ * to couple a scope change to Task/Discovery changes under one outer recovery journal.
+ */
+export function prepareMilestoneScopeChangeBundle(options: {
+  store: FileStateStore;
+  milestone: MilestoneState;
+  prepared: PreparedMilestoneScopeChange;
+  now: Date;
+  readTask: ReadTask;
+}): PreparedMilestoneScopeChangeBundle {
+  const { store, milestone, prepared, now, readTask } = options;
+  const planContent = renderMilestonePlanArtifact(prepared.normalizedPlan);
+  const planHash = sha256Hex(planContent);
+  if (planHash !== prepared.candidatePlanHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change candidate drifted before bundle preparation.', {
+      expectedPlanHash: prepared.candidatePlanHash,
+      actualPlanHash: planHash,
+    });
+  }
+  const currentEvents = readMilestoneScopeChangeEvents(store, milestone.projectId, milestone.id);
+  const sidecar = prepareSidecarAppend<MilestoneScopeChangeEvent>(currentEvents, createMilestoneScopeChangeEvent({
+    milestone,
+    normalizedPlan: prepared.normalizedPlan,
+    actor: prepared.actor,
+    now,
+    previousEventHash: currentEvents.at(-1)?.eventHash ?? null,
+    candidatePlanHash: planHash,
+    candidateMembershipRevision: prepared.candidateMembershipRevision,
+    confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+    authorizationMode: prepared.authorizationMode,
+    autonomyContractEventHash: prepared.autonomyContractEventHash,
+    remediationEvidence: prepared.remediationEvidence,
+  }), { validateEvent: (candidate) => validateMilestoneScopeChangeEvent(candidate, milestone.id) });
+  const state: MilestoneState = {
+    ...milestone,
+    revision: milestone.revision + 1,
+    updatedAt: now.toISOString(),
+    status: prepared.resultingStatus,
+    outcome: prepared.normalizedPlan.outcome,
+    successSignal: prepared.normalizedPlan.successSignal,
+    acceptance: prepared.normalizedPlan.acceptance,
+    taskIds: prepared.normalizedPlan.taskIds,
+    memberships: prepared.normalizedPlan.memberships,
+    checks: prepared.normalizedPlan.checks,
+    membershipRevision: prepared.candidateMembershipRevision,
+    authorizations: prepared.authorizations,
+    planHash,
+    resultHash: null,
+    evidenceHash: null,
+    acceptedHead: null,
+    cancellationReason: null,
+  };
+  assertMilestoneMembershipIntegrity(state, readTask);
+  return {
+    state,
+    stateContent: `${JSON.stringify(state, null, 2)}\n`,
+    planContent,
+    sidecarContent: sidecar.content,
+  };
+}
+
+export function normalizeMilestonePlan(plan: MilestonePlanInput): NormalizedMilestonePlan {
+  const normalized: NormalizedMilestonePlan = {
+    outcome: plan.outcome.trim(),
+    successSignal: plan.successSignal.trim(),
+    acceptance: [...plan.acceptance],
+    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.trim()),
+  };
+  assertCanonicalMilestoneDependencyGraph(normalized.memberships, 'INVALID_ARGUMENT', 'Milestone Plan');
+  return normalized;
+}
+
+export function assessMilestoneTaskDependencies(
+  milestone: MilestoneState,
+  taskId: string,
+  readTask: ReadTask,
+): MilestoneTaskDependencyAssessment {
+  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 as MilestonePlanMembershipInput[],
+    '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: TaskState | null = 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' as const,
+      status: predecessor?.status ?? 'missing' as const,
+    }];
+  });
+  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: MilestoneState): void {
+  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 as MilestonePlanMembershipInput[],
+    'STATE_CORRUPT',
+    `Milestone ${milestone.id}`,
+  );
+}
+
+export function assertMilestoneTaskRunnable(
+  milestone: MilestoneState,
+  taskId: string,
+  readTask: ReadTask,
+): MilestoneTaskDependencyAssessment {
+  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: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  readTask: ReadTask,
+  listTasks?: ListTasks,
+): MilestoneState {
+  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: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  readTask: ReadTask,
+  listTasks?: ListTasks,
+): MilestoneState {
+  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, {
+    allowRepairableReverseOrphans: !['accepted', 'cancelled'].includes(milestone.status)
+      && milestone.planHash !== null && milestone.membershipRevision > 0 && milestone.memberships.length > 0,
+  }, listTasks);
+  return milestone;
+}
+
+/** Read-only gap assessment; observation has already verified all other integrity constraints. */
+export function assessMilestoneScopeCompletion(milestone: MilestoneState, tasks: TaskState[]): string[] {
+  const classified = new Set(milestone.memberships.map((membership) => membership.taskId));
+  return tasks.filter((task) => task.milestoneId === milestone.id && task.status !== 'cancelled'
+    && !classified.has(task.id)).map((task) => task.id);
+}
+
+export function readMilestoneForScopeChange(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  readTask: ReadTask,
+  listTasks?: ListTasks,
+): MilestoneState {
+  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;
+}
+
+export function listMilestonesWithIntegrity(
+  store: FileStateStore,
+  projectId: string,
+  readTask: ReadTask,
+  listTasks?: ListTasks,
+): MilestoneState[] {
+  const milestonesRoot = path.join(store.projectRoot(projectId), 'milestones');
+  if (!existsSync(milestonesRoot)) return [];
+  return readdirSync(milestonesRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .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: {
+  store: FileStateStore;
+  projectId: string;
+  milestone: MilestoneState;
+  listTasks?: ListTasks;
+}): MilestoneInitialAssemblyAssessment {
+  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: MilestoneState,
+  readTask: ReadTask,
+  options: MembershipIntegrityOptions = {},
+  listTasks?: ListTasks,
+): void {
+  if (!Number.isInteger(milestone.membershipRevision) || milestone.membershipRevision < 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} has invalid membershipRevision.`, {
+      membershipRevision: milestone.membershipRevision,
+    });
+  }
+  const membershipTaskIds = milestone.memberships.map((membership) => membership.taskId);
+  const uniqueMembershipTaskIds = new Set(membershipTaskIds);
+  const uniqueTaskIds = new Set(milestone.taskIds);
+  if (uniqueMembershipTaskIds.size !== membershipTaskIds.length) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} memberships contain duplicate Task IDs.`, {
+      taskIds: membershipTaskIds,
+    });
+  }
+  if (uniqueTaskIds.size !== milestone.taskIds.length) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} taskIds contain duplicates.`, {
+      taskIds: milestone.taskIds,
+    });
+  }
+  if (
+    membershipTaskIds.length !== milestone.taskIds.length
+    || membershipTaskIds.some((taskId) => !uniqueTaskIds.has(taskId))
+    || milestone.taskIds.some((taskId) => !uniqueMembershipTaskIds.has(taskId))
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} taskIds and memberships diverged.`, {
+      taskIds: milestone.taskIds,
+      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 as MilestonePlanMembershipInput[],
+      'STATE_CORRUPT',
+      `Milestone ${milestone.id}`,
+    );
+  }
+  for (const membership of milestone.memberships) {
+    const task = readTask(membership.taskId);
+    if (task.milestoneId !== milestone.id) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} is no longer linked to Milestone ${milestone.id}.`, {
+        milestoneId: milestone.id,
+        taskId: task.id,
+        taskMilestoneId: task.milestoneId,
+      });
+    }
+    if (membership.disposition === 'required' && task.status === 'cancelled' && !options.allowRepairableRequiredCancelled) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Required Milestone Task ${task.id} is cancelled.`, {
+        milestoneId: milestone.id,
+        taskId: task.id,
+        taskStatus: task.status,
+      });
+    }
+    if (membership.disposition === 'cancelled' && task.status !== 'cancelled') {
+      throw new WorkflowError(
+        'TRANSITION_BLOCKED',
+        `Cancelled Milestone membership requires Task ${task.id} to be cancelled.`,
+        {
+          milestoneId: milestone.id,
+          taskId: task.id,
+          disposition: membership.disposition,
+          taskStatus: task.status,
+        },
+      );
+    }
+  }
+  if (listTasks && !options.allowRepairableReverseOrphans) {
+    const reverseOrphans = listTasks()
+      .filter((task) => task.milestoneId === milestone.id)
+      .filter((task) => task.status !== 'cancelled')
+      .filter((task) => !uniqueMembershipTaskIds.has(task.id));
+    if (reverseOrphans.length > 0) {
+      throw new WorkflowError(
+        'TRANSITION_BLOCKED',
+        `Milestone ${milestone.id} has linked Tasks that are missing from its classified membership.`,
+        {
+          diagnosticCode: 'MILESTONE_SCOPE_INCOMPLETE',
+          milestoneId: milestone.id,
+          orphanTaskIds: reverseOrphans.map((task) => task.id),
+          requiredAction: 'Add every linked Task as required, waived, or cancelled through a scope change.',
+        },
+      );
+    }
+  }
+}
+
+function assertCanonicalMilestoneDependencyGraph(
+  memberships: readonly MilestonePlanMembershipInput[],
+  code: 'INVALID_ARGUMENT' | 'STATE_CORRUPT',
+  label: string,
+): void {
+  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<string>();
+  const visited = new Set<string>();
+  const visit = (taskId: string, path: string[]): void => {
+    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: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+): boolean {
+  const milestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  return listMilestoneTransactionJournals(milestoneRoot, { expectedMilestoneId: milestoneId })
+    .some((journal) => journal.phase === 'prepared' || journal.phase === 'applying');
+}
+
+function hasMilestoneAutonomyAuthority(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+): boolean {
+  return readMilestoneAutonomyEvents(store, projectId, milestoneId).length > 0;
+}
+
+function isPristineInitialAssemblyTask(task: TaskState): boolean {
+  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: MilestoneState): void {
+  if (!SCOPE_CHANGE_ALLOWED_STATUSES.has(milestone.status)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestone.id} cannot change scope while ${milestone.status}.`, {
+      milestoneId: milestone.id,
+      status: milestone.status,
+    });
+  }
+}
+
+export function prepareMilestoneScopeChangeCandidate(options: {
+  milestone: MilestoneState;
+  plan: MilestonePlanInput;
+  readTask: ReadTask;
+  actor: string;
+  autonomyContractEventHash?: string;
+  auditedRemediationEvidence?: AuditedRemediationEvidence;
+}): PreparedMilestoneScopeChange {
+  const { milestone, plan, readTask, actor } = options;
+  const trimmedActor = actor.trim();
+  if (!trimmedActor) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone scope change requires an explicit actor.');
+  }
+  if (
+    trimmedActor.startsWith('agent:')
+    && !options.autonomyContractEventHash
+    && !options.auditedRemediationEvidence
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change is human-only and rejects delegated agent actors.', {
+      actor: trimmedActor,
+    });
+  }
+  if (options.autonomyContractEventHash) {
+    assertHash64(options.autonomyContractEventHash, 'Milestone autonomy contract event hash');
+  }
+  if (options.autonomyContractEventHash && options.auditedRemediationEvidence) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone scope change cannot combine autonomy and audited-remediation authority.');
+  }
+  if (options.auditedRemediationEvidence && !trimmedActor.startsWith('agent:')) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Audited remediation requires an agent actor.');
+  }
+  const authorizationMode = options.auditedRemediationEvidence
+    ? 'audited-remediation' as const
+    : options.autonomyContractEventHash
+      ? 'milestone-autonomy' as const
+      : 'human' as const;
+  const autonomyContractEventHash = options.autonomyContractEventHash ?? null;
+  const remediationEvidence = options.auditedRemediationEvidence ?? null;
+  const normalizedPlan = normalizeMilestonePlan(plan);
+  const before = milestoneScopeSnapshotFromState(milestone);
+  const after = milestoneScopeSnapshotFromPlan(normalizedPlan);
+  if (canonicalJsonStringify(before) === canonicalJsonStringify(after)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change is a no-op.', {
+      milestoneId: milestone.id,
+      revision: milestone.revision,
+    });
+  }
+  const taskIds = normalizedPlan.taskIds;
+  if (new Set(taskIds).size !== taskIds.length) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone memberships must have unique Task IDs.');
+  }
+  const repairableCancelledRequired = new Set(
+    milestone.memberships
+      .filter((membership) => membership.disposition === 'required')
+      .map((membership) => membership.taskId)
+      .filter((taskId) => readTask(taskId).status === 'cancelled'),
+  );
+  for (const membership of normalizedPlan.memberships) {
+    const task = readTask(membership.taskId);
+    if (task.milestoneId !== milestone.id) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} is not linked to Milestone ${milestone.id}.`);
+    }
+    if (repairableCancelledRequired.has(task.id) && membership.disposition !== 'cancelled') {
+      throw new WorkflowError(
+        'TRANSITION_BLOCKED',
+        `Milestone scope change must repair cancelled required Task ${task.id} by marking its membership cancelled.`,
+        {
+          milestoneId: milestone.id,
+          taskId: task.id,
+          currentDisposition: 'required',
+          candidateDisposition: membership.disposition,
+        },
+      );
+    }
+  }
+  const nextIds = new Set(taskIds);
+  for (const existing of milestone.memberships) {
+    if (nextIds.has(existing.taskId)) continue;
+    const task = readTask(existing.taskId);
+    if (taskHasStarted(task)) {
+      throw new WorkflowError('TRANSITION_BLOCKED', `Started Task ${task.id} cannot be removed from a Milestone.`);
+    }
+  }
+  const authorizations = milestone.authorizations.map((authorization) =>
+    authorization.kind === 'execution' && authorization.decision === 'approved'
+      ? { ...authorization, decision: 'superseded' as const }
+      : authorization,
+  );
+  const candidatePlanHash = sha256Hex(renderMilestonePlanArtifact(normalizedPlan));
+  const candidateMembershipRevision = milestone.membershipRevision + 1;
+  const confirmationCodeBindingHash = computeMilestoneScopeChangeBindingHash({
+    milestoneId: milestone.id,
+    expectedRevision: milestone.revision,
+    previousPlanHash: milestone.planHash,
+    previousMembershipRevision: milestone.membershipRevision,
+    candidatePlanHash,
+    candidateMembershipRevision,
+    actor: trimmedActor,
+    after,
+    authorizationMode,
+    autonomyContractEventHash,
+    remediationEvidence,
+  });
+  return {
+    milestoneId: milestone.id,
+    expectedRevision: milestone.revision,
+    actor: trimmedActor,
+    normalizedPlan,
+    authorizations,
+    candidatePlanHash,
+    candidateMembershipRevision,
+    after,
+    confirmationCodeBindingHash,
+    confirmationCode: milestoneScopeChangeConfirmationCode(confirmationCodeBindingHash),
+    authorizationMode,
+    autonomyContractEventHash,
+    remediationEvidence,
+    resultingStatus: authorizationMode === 'audited-remediation'
+      ? 'active'
+      : 'awaiting_execution_authorization',
+  };
+}
+
+export function applyMilestoneScopeChangeTransaction(options: {
+  store: FileStateStore;
+  milestone: MilestoneState;
+  expectedRevision: number;
+  prepared: PreparedMilestoneScopeChange;
+  now: Date;
+  readTask: ReadTask;
+}): MilestoneState {
+  const { store, milestone, expectedRevision, prepared, now, readTask } = options;
+  const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, milestone.projectId, milestone.id);
+  const planText = renderMilestonePlanArtifact(prepared.normalizedPlan);
+  const stagedPlan = store.stageArtifact(milestoneRoot, 'plan.json', planText);
+  if (stagedPlan.hash !== prepared.candidatePlanHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone scope change candidate drifted before apply.', {
+      expectedPlanHash: prepared.candidatePlanHash,
+      actualPlanHash: stagedPlan.hash,
+    });
+  }
+  const currentEvents = readMilestoneScopeChangeEvents(store, milestone.projectId, milestone.id);
+  const preparedSidecar = prepareSidecarAppend<MilestoneScopeChangeEvent>(currentEvents, createMilestoneScopeChangeEvent({
+    milestone,
+    normalizedPlan: prepared.normalizedPlan,
+    actor: prepared.actor,
+    now,
+    previousEventHash: currentEvents.at(-1)?.eventHash ?? null,
+    candidatePlanHash: stagedPlan.hash,
+    candidateMembershipRevision: prepared.candidateMembershipRevision,
+    confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+    authorizationMode: prepared.authorizationMode,
+    autonomyContractEventHash: prepared.autonomyContractEventHash,
+    remediationEvidence: prepared.remediationEvidence,
+  }), { validateEvent: (candidate) => validateMilestoneScopeChangeEvent(candidate, milestone.id) });
+  if (preparedSidecar.event.actor !== prepared.actor) {
+    throw new WorkflowError('STATE_CORRUPT', 'Prepared Milestone scope-change actor drifted before journal apply.', {
+      expectedActor: prepared.actor,
+      actualActor: preparedSidecar.event.actor,
+    });
+  }
+  if (preparedSidecar.event.confirmationCodeBindingHash !== prepared.confirmationCodeBindingHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Prepared Milestone scope-change binding drifted before journal apply.', {
+      expectedBindingHash: prepared.confirmationCodeBindingHash,
+      actualBindingHash: preparedSidecar.event.confirmationCodeBindingHash,
+    });
+  }
+  const stagedSidecar = store.stageArtifact(milestoneRoot, SCOPE_CHANGE_SIDECAR, preparedSidecar.content);
+  const candidateState: MilestoneState = {
+    ...milestone,
+    revision: milestone.revision + 1,
+    updatedAt: now.toISOString(),
+    status: prepared.resultingStatus,
+    outcome: prepared.normalizedPlan.outcome,
+    successSignal: prepared.normalizedPlan.successSignal,
+    acceptance: prepared.normalizedPlan.acceptance,
+    taskIds: prepared.normalizedPlan.taskIds,
+    memberships: prepared.normalizedPlan.memberships,
+    checks: prepared.normalizedPlan.checks,
+    membershipRevision: prepared.candidateMembershipRevision,
+    authorizations: prepared.authorizations,
+    planHash: stagedPlan.hash,
+    resultHash: null,
+    evidenceHash: null,
+    acceptedHead: null,
+    cancellationReason: null,
+  };
+  assertMilestoneMembershipIntegrity(candidateState, readTask);
+  const stagedState = store.stageArtifact(
+    milestoneRoot,
+    'state.json',
+    `${JSON.stringify(candidateState, null, 2)}\n`,
+  );
+  const transactionId = `tx-${createEntityId('MS', now.getTime())}`;
+  const journal: MilestoneTransactionJournal = {
+    transactionId,
+    milestoneId: milestone.id,
+    expectedMilestoneRevision: milestone.revision,
+    actor: prepared.actor,
+    confirmationCodeBindingHash: prepared.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' }),
+      },
+      {
+        path: SCOPE_CHANGE_SIDECAR,
+        preimage: captureJournalTargetSnapshot(alpha6MilestoneRoot, SCOPE_CHANGE_SIDECAR),
+        staged: createJournalSnapshotFromContent(alpha6MilestoneRoot, readFileSync(stagedSidecar.stagedFile), { mode: 'inline' }),
+      },
+    ],
+    preparedAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  };
+  if (journal.actor !== preparedSidecar.event.actor) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal actor does not match latest staged scope-change event.', {
+      journalActor: journal.actor,
+      eventActor: preparedSidecar.event.actor,
+    });
+  }
+  if (journal.confirmationCodeBindingHash !== preparedSidecar.event.confirmationCodeBindingHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone transaction journal binding does not match latest staged scope-change event.', {
+      journalBindingHash: journal.confirmationCodeBindingHash,
+      eventBindingHash: preparedSidecar.event.confirmationCodeBindingHash,
+    });
+  }
+  writeMilestoneTransactionJournal(alpha6MilestoneRoot, journal);
+  try {
+    updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, transactionId, 'applying', now.toISOString(), {
+      expectedMilestoneId: milestone.id,
+    });
+    store.publishArtifact(stagedPlan);
+    store.publishArtifact({ ...stagedSidecar, hash: preparedSidecar.contentHash });
+    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,
+  });
+}
+
+export function applyInitialMilestonePlanTransaction(options: {
+  store: FileStateStore;
+  milestone: MilestoneState;
+  expectedRevision: number;
+  normalizedPlan: NormalizedMilestonePlan;
+  now: Date;
+  readTask: ReadTask;
+  listTasks?: ListTasks;
+}): MilestoneState {
+  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' as const }
+      : authorization,
+  );
+  const candidateState: MilestoneState = {
+    ...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: MilestoneTransactionJournal = {
+    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: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  readTask: ReadTask,
+): void {
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  const transactionDir = path.join(alpha6MilestoneRoot, '.transactions');
+  if (!existsSync(transactionDir)) return;
+  const journals = listMilestoneTransactionJournals(alpha6MilestoneRoot, { expectedMilestoneId: milestoneId });
+  for (const journal of journals) {
+    validateMilestoneTransactionTargets(journal);
+    try {
+      if (shouldCompleteMilestoneTransaction(store, projectId, milestoneId, journal, readTask)) {
+        completeMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+        continue;
+      }
+    } catch {
+      rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+      continue;
+    }
+    rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+  }
+}
+
+function assertMilestonePlanAgreement(store: FileStateStore, milestone: MilestoneState): void {
+  if (milestone.planHash === null) return;
+  const milestoneRoot = store.milestoneRoot(milestone.projectId, milestone.id);
+  let currentPlanHash: string;
+  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,
+      actualPlanHash: currentPlanHash,
+    });
+  }
+  const plan = parseMilestonePlanArtifact(readFileSync(path.join(milestoneRoot, 'plan.json'), 'utf8'), milestone.id);
+  const expectedScope = milestoneScopeSnapshotFromState(milestone);
+  const actualScope = milestoneScopeSnapshotFromPlan(plan);
+  if (canonicalJsonStringify(expectedScope) !== canonicalJsonStringify(actualScope)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} state.json and plan.json diverged.`, {
+      milestoneId: milestone.id,
+      stateScope: expectedScope,
+      planScope: actualScope,
+    });
+  }
+  const scopeEvents = readMilestoneScopeChangeEvents(store, milestone.projectId, milestone.id);
+  if (scopeEvents.length === 0) return;
+  const latest = scopeEvents.at(-1)!;
+  if (
+    latest.candidatePlanHash !== milestone.planHash
+    || latest.candidateMembershipRevision !== milestone.membershipRevision
+    || canonicalJsonStringify(latest.after) !== canonicalJsonStringify(expectedScope)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} scope-change sidecar diverged from current state.`, {
+      milestoneId: milestone.id,
+      latestEventId: latest.eventId,
+      latestCandidatePlanHash: latest.candidatePlanHash,
+      milestonePlanHash: milestone.planHash,
+      latestCandidateMembershipRevision: latest.candidateMembershipRevision,
+      milestoneMembershipRevision: milestone.membershipRevision,
+    });
+  }
+}
+
+export function readMilestoneScopeChangeEvents(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+): MilestoneScopeChangeEvent[] {
+  const sidecarPath = path.join(resolveAlpha6MilestoneRoot(store, projectId, milestoneId), SCOPE_CHANGE_SIDECAR);
+  assertNoSymlinkPathComponents(sidecarPath, { label: 'Milestone scope-change sidecar path', requireLeaf: true });
+  if (!existsSync(sidecarPath)) return [];
+  return parseMilestoneScopeChangeEvents(readFileSync(sidecarPath, 'utf8'), milestoneId);
+}
+
+function validateMilestoneScopeChangeEvent(event: MilestoneScopeChangeEvent, expectedMilestoneId: string): void {
+  if (event.milestoneId !== expectedMilestoneId) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change sidecar milestone mismatch.', {
+      expectedMilestoneId,
+      actualMilestoneId: event.milestoneId,
+      eventId: event.eventId,
+    });
+  }
+  if (!Number.isInteger(event.previousMilestoneRevision) || event.previousMilestoneRevision < 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change previousMilestoneRevision is invalid.', {
+      eventId: event.eventId,
+      previousMilestoneRevision: event.previousMilestoneRevision,
+    });
+  }
+  if (!Number.isInteger(event.previousMembershipRevision) || event.previousMembershipRevision < 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change previousMembershipRevision is invalid.', {
+      eventId: event.eventId,
+      previousMembershipRevision: event.previousMembershipRevision,
+    });
+  }
+  if (!Number.isInteger(event.candidateMembershipRevision) || event.candidateMembershipRevision < 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change candidateMembershipRevision is invalid.', {
+      eventId: event.eventId,
+      candidateMembershipRevision: event.candidateMembershipRevision,
+    });
+  }
+  if (event.candidateMembershipRevision !== event.previousMembershipRevision + 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change membershipRevision must advance by exactly one.', {
+      eventId: event.eventId,
+      previousMembershipRevision: event.previousMembershipRevision,
+      candidateMembershipRevision: event.candidateMembershipRevision,
+    });
+  }
+  if (!event.actor.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change actor is required.', { eventId: event.eventId });
+  }
+  if (
+    event.actor.startsWith('agent:')
+    && event.authorizationMode !== 'milestone-autonomy'
+    && event.authorizationMode !== 'audited-remediation'
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change actor must be human-only.', {
+      eventId: event.eventId,
+      actor: event.actor,
+    });
+  }
+  if (event.authorizationMode === 'milestone-autonomy') {
+    if (!event.actor.startsWith('agent:') || !event.autonomyContractEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', 'Autonomous Milestone scope change requires an agent actor and contract evidence.', {
+        eventId: event.eventId,
+      });
+    }
+    assertHash64(event.autonomyContractEventHash, 'Milestone scope-change autonomyContractEventHash');
+  } else if (event.autonomyContractEventHash !== undefined && event.autonomyContractEventHash !== null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Human Milestone scope change cannot carry autonomy contract evidence.');
+  }
+  if (event.authorizationMode === 'audited-remediation') {
+    if (event.actor !== `agent:milestone-remediation:${event.milestoneId}` || !event.remediationEvidence) {
+      throw new WorkflowError('STATE_CORRUPT', 'Audited remediation requires an agent actor and bound remediation evidence.', {
+        eventId: event.eventId,
+      });
+    }
+    validateAuditedRemediationEvidence(event.remediationEvidence, event.eventId);
+    validateAuditedRemediationTopologyEvent(event);
+  } else if (event.remediationEvidence !== undefined && event.remediationEvidence !== null) {
+    throw new WorkflowError('STATE_CORRUPT', 'Non-remediation scope change cannot carry remediation evidence.', {
+      eventId: event.eventId,
+    });
+  }
+  if (!event.confirmationCodeBindingHash.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change confirmationCodeBindingHash is required.', {
+      eventId: event.eventId,
+    });
+  }
+  assertHash64(event.confirmationCodeBindingHash, 'Milestone scope-change confirmationCodeBindingHash');
+  const expectedBindingHash = computeMilestoneScopeChangeBindingHash({
+    milestoneId: event.milestoneId,
+    expectedRevision: event.previousMilestoneRevision,
+    previousPlanHash: event.previousPlanHash,
+    previousMembershipRevision: event.previousMembershipRevision,
+    candidatePlanHash: event.candidatePlanHash,
+    candidateMembershipRevision: event.candidateMembershipRevision,
+    actor: event.actor,
+    after: event.after,
+    ...(event.authorizationMode === undefined ? {} : { authorizationMode: event.authorizationMode }),
+    ...(event.autonomyContractEventHash === undefined
+      ? {}
+      : { autonomyContractEventHash: event.autonomyContractEventHash }),
+    ...(event.remediationEvidence === undefined
+      ? {}
+      : { remediationEvidence: event.remediationEvidence }),
+  });
+  if (event.confirmationCodeBindingHash !== expectedBindingHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone scope-change confirmationCodeBindingHash is inconsistent.', {
+      eventId: event.eventId,
+      expectedBindingHash,
+      actualBindingHash: event.confirmationCodeBindingHash,
+    });
+  }
+}
+
+function validateMilestoneTransactionTargets(journal: MilestoneTransactionJournal): void {
+  const paths = journal.targetFiles.map((target) => target.path);
+  const unique = new Set(paths);
+  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 expectedTargets) {
+    if (!unique.has(target)) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing ${target}.`);
+    }
+  }
+}
+
+function shouldCompleteMilestoneTransaction(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  journal: MilestoneTransactionJournal,
+  readTask: ReadTask,
+): boolean {
+  const staged = readStagedMilestoneTransactionBundle(store, projectId, milestoneId, journal);
+  const currentStates = journal.targetFiles.map((target) => {
+    const current = captureJournalTargetSnapshot(resolveAlpha6MilestoneRoot(store, projectId, milestoneId), target.path);
+    const matchesPreimage = canonicalJsonStringify(current) === canonicalJsonStringify(target.preimage);
+    const matchesStaged = canonicalJsonStringify(current) === canonicalJsonStringify(target.staged);
+    return { target: target.path, matchesPreimage, matchesStaged };
+  });
+  if (currentStates.some((state) => !state.matchesPreimage && !state.matchesStaged)) return false;
+  if (staged.state.id !== journal.milestoneId || staged.state.revision !== journal.expectedMilestoneRevision + 1) {
+    return false;
+  }
+  assertMilestoneMembershipIntegrity(staged.state, readTask);
+  return true;
+}
+
+function completeMilestoneTransaction(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  journal: MilestoneTransactionJournal,
+  readTask: ReadTask,
+): void {
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  try {
+    updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'applying', new Date().toISOString(), {
+      expectedMilestoneId: milestoneId,
+    });
+    for (const target of journal.targetFiles) {
+      const content = readJournalSnapshotContent(alpha6MilestoneRoot, target.staged, {
+        expectedMilestoneId: milestoneId,
+        transactionId: journal.transactionId,
+      });
+      if (content === null) {
+        rmSync(resolveMilestoneTransactionTargetPath(alpha6MilestoneRoot, target.path), { force: true });
+        continue;
+      }
+      const staged = store.stageArtifact(
+        store.milestoneRoot(projectId, milestoneId),
+        target.path,
+        content.toString('utf8'),
+      );
+      store.publishArtifact(staged);
+    }
+  } catch (error) {
+    rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+    throw error;
+  }
+  finalizeCompletedMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+}
+
+function rollbackMilestoneTransaction(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  journal: MilestoneTransactionJournal,
+  readTask: ReadTask,
+): void {
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  for (const target of journal.targetFiles) {
+    const content = readJournalSnapshotContent(alpha6MilestoneRoot, target.preimage, {
+      expectedMilestoneId: milestoneId,
+      transactionId: journal.transactionId,
+    });
+    if (content === null) {
+      rmSync(resolveMilestoneTransactionTargetPath(alpha6MilestoneRoot, target.path), { force: true });
+      continue;
+    }
+    const staged = store.stageArtifact(
+      store.milestoneRoot(projectId, milestoneId),
+      target.path,
+      content.toString('utf8'),
+    );
+    store.publishArtifact(staged);
+  }
+  try {
+    const restored = store.readMilestone(projectId, milestoneId);
+    if (restored.revision !== journal.expectedMilestoneRevision) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} rollback restored an unexpected revision.`, {
+        expectedRevision: journal.expectedMilestoneRevision,
+        actualRevision: restored.revision,
+      });
+    }
+    assertMilestonePlanAgreement(store, restored);
+    assertMilestoneMembershipIntegrity(restored, readTask, { allowRepairableRequiredCancelled: true });
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} rollback validation failed.`, {
+      transactionId: journal.transactionId,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'rolled_back', new Date().toISOString(), {
+    expectedMilestoneId: milestoneId,
+  });
+  removeMilestoneTransactionJournal(alpha6MilestoneRoot, journal.transactionId);
+}
+
+function finalizeCompletedMilestoneTransaction(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  journal: MilestoneTransactionJournal,
+  readTask: ReadTask,
+  options: { expectedRevisionAfterApply?: number } = {},
+): MilestoneState {
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  let saved: MilestoneState;
+  try {
+    saved = store.readMilestone(projectId, milestoneId);
+    if (options.expectedRevisionAfterApply !== undefined && saved.revision !== options.expectedRevisionAfterApply) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope change wrote an unexpected revision.`, {
+        expectedRevision: options.expectedRevisionAfterApply,
+        actualRevision: saved.revision,
+      });
+    }
+    assertMilestonePlanAgreement(store, saved);
+    assertMilestoneMembershipIntegrity(saved, readTask);
+  } catch (error) {
+    rollbackMilestoneTransaction(store, projectId, milestoneId, journal, readTask);
+    throw error;
+  }
+  updateMilestoneTransactionJournalPhase(alpha6MilestoneRoot, journal.transactionId, 'applied', new Date().toISOString(), {
+    expectedMilestoneId: milestoneId,
+  });
+  removeMilestoneTransactionJournal(alpha6MilestoneRoot, journal.transactionId);
+  return saved;
+}
+
+function readStagedMilestoneTransactionBundle(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+  journal: MilestoneTransactionJournal,
+): {
+  state: MilestoneState;
+  plan: PersistedMilestonePlan;
+  events: MilestoneScopeChangeEvent[];
+} {
+  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) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} is missing a staged bundle.`);
+  }
+  const alpha6MilestoneRoot = resolveAlpha6MilestoneRoot(store, projectId, milestoneId);
+  const stateBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, stateSnapshot, {
+    expectedMilestoneId: milestoneId,
+    transactionId: journal.transactionId,
+  });
+  const planBuffer = readJournalSnapshotContent(alpha6MilestoneRoot, planSnapshot, {
+    expectedMilestoneId: milestoneId,
+    transactionId: journal.transactionId,
+  });
+  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 = 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) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${journal.transactionId} staged state revision is inconsistent.`, {
+      expectedRevision: journal.expectedMilestoneRevision + 1,
+      actualRevision: state.revision,
+    });
+  }
+  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,
+    });
+  }
+  return { state, plan, events };
+}
+
+function parseMilestonePlanArtifact(content: string, milestoneId: string): PersistedMilestonePlan {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json is not valid JSON.`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json must be an object.`);
+  }
+  const record = parsed as Record<string, unknown>;
+  const allowedKeys = new Set(['outcome', 'successSignal', 'acceptance', 'memberships', 'checks']);
+  const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json contains unexpected fields.`, {
+      extraKeys,
+    });
+  }
+  if (typeof record.outcome !== 'string' || !record.outcome.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json outcome must be a non-empty string.`);
+  }
+  if (typeof record.successSignal !== 'string' || !record.successSignal.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} plan.json successSignal must be a non-empty string.`);
+  }
+  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);
+  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 as MilestonePlanMembershipInput[],
+      '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: string, milestoneId: string): MilestoneScopeChangeEvent[] {
+  if (content.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar must not be empty.`);
+  }
+  const rawLines = content.split('\n');
+  if (rawLines.at(-1) === '') rawLines.pop();
+  if (rawLines.some((line) => line.length === 0)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar contains a blank line.`);
+  }
+  const events: MilestoneScopeChangeEvent[] = [];
+  const eventIds = new Set<string>();
+  let previousEventHash: string | null = null;
+  for (const [index, rawLine] of rawLines.entries()) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawLine);
+    } catch (error) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar has invalid JSONL.`, {
+        line: index + 1,
+        cause: error instanceof Error ? error.message : String(error),
+      });
+    }
+    const event = parseMilestoneScopeChangeEventRecord(parsed, milestoneId, index + 1);
+    validateMilestoneScopeChangeEvent(event, milestoneId);
+    if (eventIds.has(event.eventId)) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar contains duplicate event id.`, {
+        line: index + 1,
+        eventId: event.eventId,
+      });
+    }
+    eventIds.add(event.eventId);
+    if (event.previousEventHash !== previousEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change sidecar chain is broken.`, {
+        line: index + 1,
+        expectedPreviousEventHash: previousEventHash,
+        actualPreviousEventHash: event.previousEventHash,
+      });
+    }
+    const expectedEventHash = computeSidecarEventHash(event);
+    if (event.eventHash !== expectedEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change eventHash mismatch.`, {
+        line: index + 1,
+        expectedEventHash,
+        actualEventHash: event.eventHash,
+      });
+    }
+    previousEventHash = event.eventHash;
+    const previous = events.at(-1);
+    if (previous) {
+      if (
+        event.previousMilestoneRevision <= previous.previousMilestoneRevision
+        || event.previousPlanHash !== previous.candidatePlanHash
+        || event.previousMembershipRevision !== previous.candidateMembershipRevision
+        || canonicalJsonStringify(event.before) !== canonicalJsonStringify(previous.after)
+      ) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change semantic continuity is broken.`, {
+          line: index + 1,
+          previousEventId: previous.eventId,
+          eventId: event.eventId,
+        });
+      }
+    }
+    events.push(event);
+  }
+  return events;
+}
+
+function createMilestoneScopeChangeEvent(options: {
+  milestone: MilestoneState;
+  normalizedPlan: NormalizedMilestonePlan;
+  actor: string;
+  now: Date;
+  previousEventHash: string | null;
+  candidatePlanHash: string;
+  candidateMembershipRevision: number;
+  confirmationCodeBindingHash: string;
+  authorizationMode: 'human' | 'milestone-autonomy' | 'audited-remediation';
+  autonomyContractEventHash: string | null;
+  remediationEvidence: AuditedRemediationEvidence | null;
+}): Omit<MilestoneScopeChangeEvent, 'eventHash'> {
+  const {
+    milestone,
+    normalizedPlan,
+    actor,
+    now,
+    previousEventHash,
+    candidatePlanHash,
+    candidateMembershipRevision,
+    confirmationCodeBindingHash,
+    authorizationMode,
+    autonomyContractEventHash,
+    remediationEvidence,
+  } = options;
+  return {
+    eventId: createEntityId('MS', now.getTime()),
+    previousEventHash,
+    recordedAt: now.toISOString(),
+    milestoneId: milestone.id,
+    previousMilestoneRevision: milestone.revision,
+    previousPlanHash: milestone.planHash,
+    previousMembershipRevision: milestone.membershipRevision,
+    candidatePlanHash,
+    candidateMembershipRevision,
+    before: milestoneScopeSnapshotFromState(milestone),
+    after: milestoneScopeSnapshotFromPlan(normalizedPlan),
+    actor: actor.trim(),
+    confirmationCodeBindingHash,
+    ...(authorizationMode === 'milestone-autonomy'
+      ? { authorizationMode, autonomyContractEventHash }
+      : authorizationMode === 'audited-remediation'
+        ? { authorizationMode, remediationEvidence }
+        : {}),
+  };
+}
+
+function milestoneScopeSnapshotFromState(milestone: MilestoneState): MilestoneScopeSnapshot {
+  return {
+    outcome: milestone.outcome,
+    successSignal: milestone.successSignal,
+    acceptance: milestone.acceptance,
+    checks: milestone.checks,
+    taskIds: milestone.taskIds,
+    memberships: milestone.memberships,
+  };
+}
+
+function parseMilestoneScopeChangeEventRecord(
+  parsed: unknown,
+  milestoneId: string,
+  line: number,
+): MilestoneScopeChangeEvent {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change event must be an object.`, { line });
+  }
+  const record = parsed as Record<string, unknown>;
+  const allowedKeys = new Set([
+    'eventId',
+    'recordedAt',
+    'previousEventHash',
+    'milestoneId',
+    'previousMilestoneRevision',
+    'previousPlanHash',
+    'previousMembershipRevision',
+    'candidatePlanHash',
+    'candidateMembershipRevision',
+    'before',
+    'after',
+    'actor',
+    'confirmationCodeBindingHash',
+    'authorizationMode',
+    'autonomyContractEventHash',
+    'remediationEvidence',
+    'eventHash',
+  ]);
+  const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change event contains unexpected fields.`, {
+      line,
+      extraKeys,
+    });
+  }
+  const eventId = requireNonEmptyString(record.eventId, `Milestone ${milestoneId} scope-change eventId`, { line });
+  const recordedAt = requireIsoTimestamp(record.recordedAt, `Milestone ${milestoneId} scope-change recordedAt`, { line });
+  const previousEventHash = requireNullableHash64(record.previousEventHash, `Milestone ${milestoneId} scope-change previousEventHash`, { line });
+  const actualMilestoneId = requireNonEmptyString(record.milestoneId, `Milestone ${milestoneId} scope-change milestoneId`, { line });
+  const previousMilestoneRevision = requireInteger(record.previousMilestoneRevision, `Milestone ${milestoneId} scope-change previousMilestoneRevision`, { line });
+  const previousPlanHash = requireNullableHash64(record.previousPlanHash, `Milestone ${milestoneId} scope-change previousPlanHash`, { line });
+  const previousMembershipRevision = requireInteger(record.previousMembershipRevision, `Milestone ${milestoneId} scope-change previousMembershipRevision`, { line });
+  const candidatePlanHash = requireHash64(record.candidatePlanHash, `Milestone ${milestoneId} scope-change candidatePlanHash`, { line });
+  const candidateMembershipRevision = requireInteger(record.candidateMembershipRevision, `Milestone ${milestoneId} scope-change candidateMembershipRevision`, { line });
+  const before = parseMilestoneScopeSnapshot(record.before, milestoneId, line, 'before');
+  const after = parseMilestoneScopeSnapshot(record.after, milestoneId, line, 'after');
+  const actor = requireNonEmptyString(record.actor, `Milestone ${milestoneId} scope-change actor`, { line });
+  const confirmationCodeBindingHash = requireHash64(
+    record.confirmationCodeBindingHash,
+    `Milestone ${milestoneId} scope-change confirmationCodeBindingHash`,
+    { line },
+  );
+  const authorizationMode = record.authorizationMode === undefined
+    ? undefined
+    : requireMilestoneScopeChangeAuthorizationMode(record.authorizationMode, milestoneId, line);
+  const autonomyContractEventHash = record.autonomyContractEventHash === undefined
+    ? undefined
+    : requireNullableHash64(
+        record.autonomyContractEventHash,
+        `Milestone ${milestoneId} scope-change autonomyContractEventHash`,
+        { line },
+      );
+  const remediationEvidence = record.remediationEvidence === undefined
+    ? undefined
+    : parseAuditedRemediationEvidence(record.remediationEvidence, milestoneId, line);
+  const eventHash = requireHash64(record.eventHash, `Milestone ${milestoneId} scope-change eventHash`, { line });
+  return {
+    eventId,
+    recordedAt,
+    previousEventHash,
+    milestoneId: actualMilestoneId,
+    previousMilestoneRevision,
+    previousPlanHash,
+    previousMembershipRevision,
+    candidatePlanHash,
+    candidateMembershipRevision,
+    before,
+    after,
+    actor,
+    confirmationCodeBindingHash,
+    ...(authorizationMode === undefined ? {} : { authorizationMode }),
+    ...(autonomyContractEventHash === undefined ? {} : { autonomyContractEventHash }),
+    ...(remediationEvidence === undefined ? {} : { remediationEvidence }),
+    eventHash,
+  };
+}
+
+function requireMilestoneScopeChangeAuthorizationMode(
+  value: unknown,
+  milestoneId: string,
+  line: number,
+): 'human' | 'milestone-autonomy' | 'audited-remediation' {
+  if (value !== 'human' && value !== 'milestone-autonomy' && value !== 'audited-remediation') {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change authorizationMode is invalid.`, {
+      line,
+      value,
+    });
+  }
+  return value;
+}
+
+function parseAuditedRemediationEvidence(
+  value: unknown,
+  milestoneId: string,
+  line: number,
+): AuditedRemediationEvidence {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} remediation evidence must be an object.`, { line });
+  }
+  const record = value as Record<string, unknown>;
+  const allowedKeys = new Set([
+    'blockedTaskId',
+    'blockedTaskRevision',
+    'blockedBriefHash',
+    'blockedPlanHash',
+    'planRiskAuditEventId',
+    'planRiskAuditEventHash',
+    'remediationTaskId',
+    'predecessorTaskIds',
+  ]);
+  const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} remediation evidence contains unexpected fields.`, {
+      line,
+      extraKeys,
+    });
+  }
+  const evidence: AuditedRemediationEvidence = {
+    blockedTaskId: requireNonEmptyString(record.blockedTaskId, 'remediation blockedTaskId', { line }),
+    blockedTaskRevision: requireInteger(record.blockedTaskRevision, 'remediation blockedTaskRevision', { line }),
+    blockedBriefHash: requireHash64(record.blockedBriefHash, 'remediation blockedBriefHash', { line }),
+    blockedPlanHash: requireHash64(record.blockedPlanHash, 'remediation blockedPlanHash', { line }),
+    planRiskAuditEventId: requireNonEmptyString(record.planRiskAuditEventId, 'remediation planRiskAuditEventId', { line }),
+    planRiskAuditEventHash: requireHash64(record.planRiskAuditEventHash, 'remediation planRiskAuditEventHash', { line }),
+    remediationTaskId: requireNonEmptyString(record.remediationTaskId, 'remediation remediationTaskId', { line }),
+    predecessorTaskIds: parseTaskIdArray(record.predecessorTaskIds, 'remediation predecessorTaskIds', { line }),
+  };
+  validateAuditedRemediationEvidence(evidence, evidence.planRiskAuditEventId);
+  return evidence;
+}
+
+function validateAuditedRemediationEvidence(
+  evidence: AuditedRemediationEvidence,
+  eventId: string,
+): void {
+  if (!Number.isInteger(evidence.blockedTaskRevision) || evidence.blockedTaskRevision < 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Audited remediation blocked Task revision is invalid.', {
+      eventId,
+      blockedTaskRevision: evidence.blockedTaskRevision,
+    });
+  }
+  assertHash64(evidence.blockedBriefHash, 'Audited remediation blocked Brief hash');
+  assertHash64(evidence.blockedPlanHash, 'Audited remediation blocked Plan hash');
+  assertHash64(evidence.planRiskAuditEventHash, 'Audited remediation Plan Risk Audit event hash');
+  if (
+    !evidence.blockedTaskId.trim()
+    || !evidence.planRiskAuditEventId.trim()
+    || !evidence.remediationTaskId.trim()
+    || evidence.predecessorTaskIds.length === 0
+    || new Set(evidence.predecessorTaskIds).size !== evidence.predecessorTaskIds.length
+    || evidence.predecessorTaskIds.includes(evidence.blockedTaskId)
+    || evidence.predecessorTaskIds.includes(evidence.remediationTaskId)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Audited remediation evidence has invalid Task bindings.', {
+      eventId,
+      evidence,
+    });
+  }
+}
+
+function validateAuditedRemediationTopologyEvent(event: MilestoneScopeChangeEvent): void {
+  const evidence = event.remediationEvidence!;
+  const semanticsBefore = {
+    outcome: event.before.outcome,
+    successSignal: event.before.successSignal,
+    acceptance: event.before.acceptance,
+    checks: event.before.checks,
+  };
+  const semanticsAfter = {
+    outcome: event.after.outcome,
+    successSignal: event.after.successSignal,
+    acceptance: event.after.acceptance,
+    checks: event.after.checks,
+  };
+  const expectedTaskIds = [...event.before.taskIds, evidence.remediationTaskId];
+  const beforeBlocked = event.before.memberships.find((membership) => membership.taskId === evidence.blockedTaskId);
+  const afterBlocked = event.after.memberships.find((membership) => membership.taskId === evidence.blockedTaskId);
+  const remediation = event.after.memberships.find((membership) => membership.taskId === evidence.remediationTaskId);
+  const expectedBlockedDependencies = [...new Set([
+    ...(beforeBlocked?.dependsOnTaskIds ?? []),
+    evidence.remediationTaskId,
+  ])].sort();
+  const unchangedMemberships = event.before.memberships.every((beforeMembership) => {
+    if (beforeMembership.taskId === evidence.blockedTaskId) return true;
+    const afterMembership = event.after.memberships.find(
+      (candidate) => candidate.taskId === beforeMembership.taskId,
+    );
+    return canonicalJsonStringify(afterMembership) === canonicalJsonStringify(beforeMembership);
+  });
+  if (canonicalJsonStringify(semanticsBefore) !== canonicalJsonStringify(semanticsAfter)
+    || canonicalJsonStringify(event.after.taskIds) !== canonicalJsonStringify(expectedTaskIds)
+    || event.after.memberships.length !== event.before.memberships.length + 1
+    || beforeBlocked?.disposition !== 'required'
+    || afterBlocked?.disposition !== 'required'
+    || canonicalJsonStringify(afterBlocked?.dependsOnTaskIds ?? [])
+      !== canonicalJsonStringify(expectedBlockedDependencies)
+    || remediation?.disposition !== 'required'
+    || !remediation.reason.trim()
+    || canonicalJsonStringify(remediation.dependsOnTaskIds ?? [])
+      !== canonicalJsonStringify(evidence.predecessorTaskIds)
+    || canonicalJsonStringify(beforeBlocked?.dependsOnTaskIds ?? [])
+      !== canonicalJsonStringify(evidence.predecessorTaskIds)
+    || !unchangedMemberships) {
+    throw new WorkflowError(
+      'STATE_CORRUPT',
+      'Audited remediation scope-change event exceeds its additive topology authority.',
+      { eventId: event.eventId, remediationEvidence: evidence },
+    );
+  }
+}
+
+function parseMilestoneScopeSnapshot(
+  value: unknown,
+  milestoneId: string,
+  line: number,
+  label: 'before' | 'after',
+): MilestoneScopeSnapshot {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change ${label} snapshot must be an object.`, { line });
+  }
+  const record = value as Record<string, unknown>;
+  const allowedKeys = new Set(['outcome', 'successSignal', 'acceptance', 'checks', 'taskIds', 'memberships']);
+  const extraKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+  if (extraKeys.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope-change ${label} snapshot contains unexpected fields.`, {
+      line,
+      extraKeys,
+    });
+  }
+  const snapshot = {
+    outcome: requireNonEmptyString(record.outcome, `Milestone ${milestoneId} scope-change ${label}.outcome`, { line }),
+    successSignal: requireNonEmptyString(record.successSignal, `Milestone ${milestoneId} scope-change ${label}.successSignal`, { line }),
+    acceptance: parseStringArray(record.acceptance, `Milestone ${milestoneId} scope-change ${label}.acceptance`, { line }),
+    checks: parseStringArray(record.checks, `Milestone ${milestoneId} scope-change ${label}.checks`, { line }),
+    taskIds: parseTaskIdArray(record.taskIds, `Milestone ${milestoneId} scope-change ${label}.taskIds`, { line }),
+    memberships: parseMilestoneMembershipArray(record.memberships, milestoneId, { line, label }),
+  };
+  assertSnapshotTaskIdsMatchMemberships(snapshot, milestoneId, { line, label });
+  return snapshot;
+}
+
+function parseMilestoneMembershipArray(
+  value: unknown,
+  milestoneId: string,
+  options: { line?: number; label?: string } = {},
+): MilestoneMembership[] {
+  const label = options.label ? `${options.label}.memberships` : 'memberships';
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} ${label} must be a non-empty array.`, options.line !== undefined ? { line: options.line } : {});
+  }
+  const memberships = value.map((entry, index) => parseMilestoneMembership(entry, milestoneId, index, options.line));
+  const taskIds = memberships.map((membership) => membership.taskId);
+  if (new Set(taskIds).size !== taskIds.length) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} ${label} contains duplicate taskIds.`, options.line !== undefined ? { line: options.line, taskIds } : { taskIds });
+  }
+  return memberships;
+}
+
+function parseMilestoneMembership(
+  value: unknown,
+  milestoneId: string,
+  index: number,
+  line?: number,
+): MilestoneMembership {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership at index ${index} must be an object.`, line !== undefined ? { line, index } : { index });
+  }
+  const record = value as Record<string, unknown>;
+  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 });
+  }
+  const taskId = requireNonEmptyString(record.taskId, `Milestone ${milestoneId} membership.taskId`, line !== undefined ? { line, index } : { index });
+  const dispositionValue = requireNonEmptyString(record.disposition, `Milestone ${milestoneId} membership.disposition`, line !== undefined ? { line, index } : { index });
+  if (!['required', 'waived', 'cancelled'].includes(dispositionValue)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership disposition is invalid.`, line !== undefined ? { line, index, disposition: dispositionValue } : { index, disposition: dispositionValue });
+  }
+  const disposition = dispositionValue as MilestoneMembership['disposition'];
+  const reason = typeof record.reason === 'string' ? record.reason.trim() : '';
+  if (disposition !== 'required' && reason.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} membership ${disposition} requires a reason.`, line !== undefined ? { line, index } : { index });
+  }
+  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: unknown,
+  label: string,
+  details: Record<string, unknown> = {},
+): string[] {
+  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: unknown, label: string, details: Record<string, unknown> = {}): string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a non-empty array.`, details);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== 'string' || !entry.trim()) {
+      throw new WorkflowError('STATE_CORRUPT', `${label}[${index}] must be a non-empty string.`, { ...details, index });
+    }
+    return entry;
+  });
+}
+
+function parseTaskIdArray(value: unknown, label: string, details: Record<string, unknown> = {}): string[] {
+  const taskIds = parseStringArray(value, label, details);
+  if (new Set(taskIds).size !== taskIds.length) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} contains duplicate taskIds.`, { ...details, taskIds });
+  }
+  return taskIds;
+}
+
+function requireNonEmptyString(value: unknown, label: string, details: Record<string, unknown> = {}): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a non-empty string.`, details);
+  }
+  return value;
+}
+
+function requireInteger(value: unknown, label: string, details: Record<string, unknown> = {}): number {
+  if (!Number.isInteger(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be an integer.`, details);
+  }
+  return value as number;
+}
+
+function requireHash64(value: unknown, label: string, details: Record<string, unknown> = {}): string {
+  if (typeof value !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a sha256 hex digest.`, details);
+  }
+  assertHash64(value, label);
+  return value;
+}
+
+function requireNullableHash64(value: unknown, label: string, details: Record<string, unknown> = {}): string | null {
+  if (value === null) return null;
+  return requireHash64(value, label, details);
+}
+
+function requireIsoTimestamp(value: unknown, label: string, details: Record<string, unknown> = {}): string {
+  if (typeof value !== 'string' || !value.trim() || Number.isNaN(Date.parse(value))) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be an ISO timestamp string.`, details);
+  }
+  return value;
+}
+
+function milestoneScopeSnapshotFromPlan(
+  plan: NormalizedMilestonePlan | PersistedMilestonePlan,
+): MilestoneScopeSnapshot {
+  return {
+    outcome: plan.outcome,
+    successSignal: plan.successSignal,
+    acceptance: plan.acceptance,
+    checks: plan.checks,
+    taskIds: plan.taskIds,
+    memberships: plan.memberships,
+  };
+}
+
+function renderMilestonePlanArtifact(plan: NormalizedMilestonePlan): string {
+  return `${JSON.stringify({
+    outcome: plan.outcome,
+    successSignal: plan.successSignal,
+    acceptance: plan.acceptance,
+    memberships: plan.memberships,
+    checks: plan.checks,
+  }, null, 2)}\n`;
+}
+
+function milestoneScopeChangeConfirmationCode(bindingHash: string): string {
+  return `MSC-${bindingHash.slice(0, 24).toUpperCase()}`;
+}
+
+function computeMilestoneScopeChangeBindingHash(input: {
+  milestoneId: string;
+  expectedRevision: number;
+  previousPlanHash: string | null;
+  previousMembershipRevision: number;
+  candidatePlanHash: string;
+  candidateMembershipRevision: number;
+  actor: string;
+  after: MilestoneScopeSnapshot;
+  authorizationMode?: 'human' | 'milestone-autonomy' | 'audited-remediation';
+  autonomyContractEventHash?: string | null;
+  remediationEvidence?: AuditedRemediationEvidence | null;
+}): string {
+  return sha256Hex(canonicalJsonStringify({
+    kind: 'milestone-scope-change-v1',
+    milestoneId: input.milestoneId,
+    expectedRevision: input.expectedRevision,
+    previousPlanHash: input.previousPlanHash,
+    previousMembershipRevision: input.previousMembershipRevision,
+    candidatePlanHash: input.candidatePlanHash,
+    candidateMembershipRevision: input.candidateMembershipRevision,
+    actor: input.actor,
+    after: input.after,
+    ...(input.authorizationMode === 'milestone-autonomy'
+      ? {
+          authorizationMode: input.authorizationMode,
+          autonomyContractEventHash: input.autonomyContractEventHash,
+        }
+      : input.authorizationMode === 'audited-remediation'
+        ? {
+            authorizationMode: input.authorizationMode,
+            remediationEvidence: input.remediationEvidence,
+          }
+        : {}),
+  }));
+}
+
+function assertSnapshotTaskIdsMatchMemberships(
+  snapshot: MilestoneScopeSnapshot,
+  milestoneId: string,
+  details: Record<string, unknown> = {},
+): void {
+  const membershipTaskIds = snapshot.memberships.map((membership) => membership.taskId);
+  const taskIds = [...snapshot.taskIds];
+  if (
+    membershipTaskIds.length !== taskIds.length
+    || membershipTaskIds.some((taskId) => !taskIds.includes(taskId))
+    || taskIds.some((taskId) => !membershipTaskIds.includes(taskId))
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestoneId} scope snapshot taskIds and memberships diverged.`, {
+      ...details,
+      taskIds,
+      membershipTaskIds,
+    });
+  }
+}
+
+function parseStagedMilestoneStateArtifact(
+  content: string,
+  expectedProjectId: string,
+  milestoneId: string,
+  transactionId: string,
+): MilestoneState {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state.json is not valid JSON.`, {
+      milestoneId,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state.json must be an object.`, {
+      milestoneId,
+    });
+  }
+  const record = parsed as Record<string, unknown>;
+  if (record.kind !== 'milestone') {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state kind is invalid.`, {
+      milestoneId,
+      kind: record.kind,
+    });
+  }
+  if (record.id !== milestoneId || record.projectId !== expectedProjectId) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state identity is invalid.`, {
+      milestoneId,
+      expectedProjectId,
+      id: record.id,
+      projectId: record.projectId,
+    });
+  }
+  if (!Number.isInteger(record.revision)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state revision is invalid.`, {
+      milestoneId,
+      revision: record.revision,
+    });
+  }
+  if (
+    typeof record.status !== 'string'
+    || !['planning', 'awaiting_execution_authorization', 'active', 'validating', 'accepted', 'blocked', 'cancelled'].includes(record.status)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state status is invalid.`, {
+      milestoneId,
+      status: record.status,
+    });
+  }
+  if (!Array.isArray(record.taskIds) || !Array.isArray(record.memberships) || !Array.isArray(record.authorizations)) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone transaction ${transactionId} staged state arrays are invalid.`, {
+      milestoneId,
+    });
+  }
+  return parsed as MilestoneState;
+}
+
+function resolveAlpha6MilestoneRoot(store: FileStateStore, projectId: string, milestoneId: string): string {
+  const projectRootLogical = store.projectRoot(projectId);
+  const trustedProjectRoot = existsSync(projectRootLogical) ? realpathSync(projectRootLogical) : path.resolve(projectRootLogical);
+  const milestonesDirLogical = path.join(projectRootLogical, 'milestones');
+  const trustedMilestonesDir = existsSync(milestonesDirLogical)
+    ? realpathSync(milestonesDirLogical)
+    : path.join(trustedProjectRoot, 'milestones');
+  const milestoneRootLogical = store.milestoneRoot(projectId, milestoneId);
+  assertNoSymlinkPathComponents(trustedMilestonesDir, { label: 'Trusted milestones directory', requireLeaf: true });
+  if (existsSync(milestoneRootLogical) && lstatSync(milestoneRootLogical).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone root must not be a symlink: ${milestoneRootLogical}`);
+  }
+  const resolvedMilestoneRoot = existsSync(milestoneRootLogical)
+    ? realpathSync(milestoneRootLogical)
+    : path.resolve(trustedMilestonesDir, milestoneId);
+  if (
+    resolvedMilestoneRoot !== trustedMilestonesDir
+    && !resolvedMilestoneRoot.startsWith(`${trustedMilestonesDir}${path.sep}`)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', `Milestone root escaped the trusted milestones directory: ${milestoneRootLogical}`, {
+      trustedMilestonesDir,
+      resolvedMilestoneRoot,
+    });
+  }
+  return resolvedMilestoneRoot;
+}
+
+function taskHasStarted(task: TaskState): boolean {
+  return task.workspaceOwner !== null || [
+    'in_progress',
+    'validating',
+    'needs_fix',
+    'awaiting_final_acceptance',
+    'merging',
+    'ready_to_merge',
+    'merged',
+  ].includes(task.status);
+}