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

package/src/dependency-provenance.ts

@@ -0,0 +1,472 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import type {
+  DependencyProvenanceRecoveryPreflight,
+  HistoricalStepDependencyCompatibility,
+  ProjectKnowledgeMap,
+  PlanIntegrityUpdateCompatibility,
+  TaskState,
+} from './contracts.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+import { changedFiles, currentBranch, headCommit, runGit } from './repository.js';
+import { hashDirtyWorktree } from './alpha6/downstream-proof.js';
+import { inspectWorkflowVersions } from './diagnostics.js';
+
+interface RecoveryEnvironment {
+  activeLeaseCount: number;
+  staleLeaseCount: number;
+  pendingTransactionCount: number;
+  corruptTransactionCount: number;
+  coreOperationCount: number;
+  verifiedHistoricalStepCommits: string[];
+  versions: {
+    runtime: string;
+    declared: string | null;
+    locked: string | null;
+    installed: string | null;
+    currentBranch: string | null;
+    baseBranch: string | null;
+  };
+}
+
+export interface ActiveDownstreamProofCompatibility {
+  activeStepId: string;
+  planHash: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  invalidatedStepIds: string[];
+}
+
+const RECOVERY_FILES = ['package-lock.json', 'package.json'] as const;
+const TERMINAL_TASK_STATUSES = new Set<TaskState['status']>(['merged', 'cancelled']);
+
+export interface DependencyKnowledgeRefreshAssessment {
+  eligible: boolean;
+  changedKnowledgePaths: string[];
+  dependencyCommits: string[];
+  sourcePackageVersion: string | null;
+  targetPackageVersion: string;
+  blockers: string[];
+}
+
+/**
+ * Proves that a stale approved Knowledge Map differs only because one or more
+ * consecutive package.json edits changed the exact codex-workflow-v2 pin. The
+ * intervening repository history may contain ordinary product commits, but
+ * every commit that touched package.json after the approved content must be a
+ * package.json/package-lock.json-only dependency update.
+ */
+export function inspectDependencyKnowledgeRefresh(
+  repositoryRoot: string,
+  milestoneBaseBranch: string,
+  approved: ProjectKnowledgeMap,
+  inspected: ProjectKnowledgeMap,
+  allowedDirtyFiles: readonly string[] = [],
+): DependencyKnowledgeRefreshAssessment {
+  const blockers: string[] = [];
+  const approvedByPath = new Map(approved.entries.map((entry) => [entry.path, entry]));
+  const inspectedByPath = new Map(inspected.entries.map((entry) => [entry.path, entry]));
+  const changedKnowledgePaths = [...new Set([
+    ...approved.entries.map((entry) => entry.path),
+    ...inspected.entries.map((entry) => entry.path),
+  ])].filter((candidatePath) => {
+    const before = approvedByPath.get(candidatePath);
+    const after = inspectedByPath.get(candidatePath);
+    return !before || !after
+      || before.id !== after.id
+      || before.category !== after.category
+      || before.scope !== after.scope
+      || before.authority !== after.authority
+      || before.discoveredBy !== after.discoveredBy
+      || before.contentHash !== after.contentHash;
+  }).sort();
+  if (approved.status !== 'active' || !approved.approval) {
+    blockers.push('Dependency Knowledge refresh requires a previously approved active map.');
+  }
+  if (inspected.status !== 'stale') {
+    blockers.push('Dependency Knowledge refresh requires an inspected stale map.');
+  }
+  if (JSON.stringify(changedKnowledgePaths) !== JSON.stringify(['package.json'])) {
+    blockers.push('Only package.json may differ in Project Knowledge.');
+  }
+
+  const versions = inspectWorkflowVersions(repositoryRoot, [milestoneBaseBranch]);
+  const versionSurfaces = [
+    versions.runtime,
+    versions.declared,
+    versions.locked,
+    versions.installed,
+    versions.currentBranch,
+    ...versions.milestoneBases.map((entry) => entry.version),
+  ];
+  if (versionSurfaces.some((version) => version !== PACKAGE_VERSION)) {
+    blockers.push(`Every Workflow version surface must equal ${PACKAGE_VERSION}.`);
+  }
+  const dirtyFiles = changedFiles(repositoryRoot).sort();
+  if (JSON.stringify(dirtyFiles) !== JSON.stringify([...allowedDirtyFiles].sort())) {
+    blockers.push(allowedDirtyFiles.length === 0
+      ? 'Dependency Knowledge refresh requires a clean checkout.'
+      : 'Dependency Knowledge refresh dirty files changed outside the bound compatibility allowlist.');
+  }
+
+  const approvedPackage = approvedByPath.get('package.json') ?? null;
+  const dependencyCommits: string[] = [];
+  let sourcePackageVersion: string | null = null;
+  if (!approvedPackage) {
+    blockers.push('The approved Knowledge Map does not contain package.json.');
+  } else {
+    try {
+      const historyOutput = runGit(repositoryRoot, ['rev-list', 'HEAD', '--', 'package.json']);
+      const packageHistory = historyOutput ? historyOutput.split('\n') : [];
+      const sourceIndex = packageHistory.findIndex((commit) =>
+        sha256(readGitFile(repositoryRoot, commit, 'package.json')) === approvedPackage.contentHash);
+      if (sourceIndex < 0) {
+        blockers.push('Approved package.json content is not present in current Git ancestry.');
+      } else {
+        sourcePackageVersion = manifestDependencyVersion(
+          parseJson(readGitFile(repositoryRoot, packageHistory[sourceIndex]!, 'package.json')),
+        );
+        for (const commit of packageHistory.slice(0, sourceIndex).reverse()) {
+          const parent = runGit(repositoryRoot, ['rev-parse', `${commit}^`]);
+          const filesOutput = runGit(repositoryRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', commit]);
+          const files = filesOutput ? filesOutput.split('\n').sort() : [];
+          if (JSON.stringify(files) !== JSON.stringify(RECOVERY_FILES)) {
+            blockers.push(`Knowledge-changing commit ${commit} is not dependency-only.`);
+            continue;
+          }
+          if (!workflowDependencyJsonDiffIsBounded(repositoryRoot, parent, commit, null)) {
+            blockers.push(`Knowledge-changing commit ${commit} changes fields beyond the Workflow dependency.`);
+            continue;
+          }
+          dependencyCommits.push(commit);
+        }
+        if (dependencyCommits.length === 0) {
+          blockers.push('No bounded Workflow dependency commit explains the Knowledge drift.');
+        }
+      }
+    } catch {
+      blockers.push('Dependency Knowledge refresh Git ancestry could not be verified.');
+    }
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    changedKnowledgePaths,
+    dependencyCommits,
+    sourcePackageVersion,
+    targetPackageVersion: PACKAGE_VERSION,
+    blockers,
+  };
+}
+
+export function inspectDependencyProvenanceRecovery(
+  repositoryRoot: string,
+  task: TaskState,
+  environment: RecoveryEnvironment,
+  activeDownstreamProof: ActiveDownstreamProofCompatibility | null = null,
+  historicalStepProvenance: HistoricalStepDependencyCompatibility | null = null,
+  retainedNavigationCarryover: PlanIntegrityUpdateCompatibility | null = null,
+): DependencyProvenanceRecoveryPreflight {
+  const blockers: string[] = [];
+  const dirty = changedFiles(repositoryRoot);
+  const head = headCommit(repositoryRoot);
+  let parent: string | null = null;
+  let commitFiles: string[] = [];
+  let dependencyCommits: Array<{
+    commitSha: string;
+    parentCommitSha: string;
+    packageVersion: string;
+  }> = [];
+  let retainedHistoricalCommits: string[] = [];
+
+  const compatibilityCount = [activeDownstreamProof, historicalStepProvenance, retainedNavigationCarryover].filter(Boolean).length;
+  if (compatibilityCount > 1) blockers.push('Dependency recovery accepts exactly one dirty compatibility binding.');
+
+  const dirtyCompatibility = activeDownstreamProof ?? historicalStepProvenance ?? retainedNavigationCarryover;
+  if (dirtyCompatibility) {
+    if (JSON.stringify(dirty.sort()) !== JSON.stringify([...dirtyCompatibility.dirtyFiles].sort())) {
+      blockers.push('Dirty files changed after the compatibility assessment.');
+    }
+    try {
+      if (hashDirtyWorktree(repositoryRoot, dirty) !== dirtyCompatibility.dirtyWorktreeHash) {
+        blockers.push('Dirty file content changed after the compatibility assessment.');
+      }
+    } catch (error) {
+      blockers.push(error instanceof Error ? error.message : String(error));
+    }
+    if (activeDownstreamProof) {
+      if (!task.planHash || task.planHash !== activeDownstreamProof.planHash) {
+        blockers.push('The current Task Plan must match the active downstream-proof compatibility binding.');
+      }
+      const inProgressSteps = task.steps.filter((step) => step.status === 'in_progress');
+      if (inProgressSteps.length !== 1 || inProgressSteps[0]?.id !== activeDownstreamProof.activeStepId) {
+        blockers.push('Exactly the bound downstream-proof Step must remain in progress.');
+      }
+    } else if (historicalStepProvenance) {
+      if (task.status !== 'in_progress' || task.planHash !== historicalStepProvenance.planHash) {
+        blockers.push('The current in-progress Task Plan must match the historical Step compatibility binding.');
+      }
+      const inProgressSteps = task.steps.filter((step) => step.status === 'in_progress');
+      if (inProgressSteps.length !== 1 || inProgressSteps[0]?.id !== historicalStepProvenance.activeStepId) {
+        blockers.push('Exactly the bound corrective Step must remain in progress.');
+      }
+
+    }
+  } else {
+    if (dirty.length > 0) blockers.push('Repository checkout must be clean.');
+  }
+  if (task.workspaceOwner !== 'local') blockers.push('Recovery is limited to a local Task workspace.');
+  if (!task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+    blockers.push('The current branch must be the recorded Task branch.');
+  }
+  if (!task.baseCommit) blockers.push('The Task must have a recorded base commit.');
+  if (TERMINAL_TASK_STATUSES.has(task.status)) blockers.push('Terminal Tasks cannot recover dependency provenance.');
+  if (!dirtyCompatibility && task.steps.some((step) => step.status === 'in_progress')) {
+    blockers.push('No Step may be in progress.');
+  }
+  if (environment.activeLeaseCount > 0) blockers.push('No active writer lease may exist.');
+  if (environment.staleLeaseCount > 0) blockers.push('No stale writer lease may exist.');
+  if (environment.pendingTransactionCount > 0) blockers.push('No pending Workflow transaction may exist.');
+  if (environment.corruptTransactionCount > 0) blockers.push('No corrupt Workflow transaction may exist.');
+  if (environment.coreOperationCount > 0) blockers.push('No Core Task operation may exist.');
+
+  for (const [surface, version] of Object.entries(environment.versions)) {
+    if (version !== PACKAGE_VERSION) blockers.push(`${surface} Workflow version must equal ${PACKAGE_VERSION}.`);
+  }
+
+  try {
+    if (task.systemCommits.includes(head)) blockers.push('The candidate commit is already registered.');
+    if (task.baseCommit) {
+      const outputHistory = runGit(repositoryRoot, ['rev-list', '--reverse', `${task.baseCommit}..HEAD`]);
+      const history = outputHistory ? outputHistory.split('\n') : [];
+      const expectedRegistered = [
+        ...task.steps.flatMap((step) => (step.evidence ? [step.evidence.commitSha] : [])),
+        ...task.systemCommits,
+        ...(task.invalidatedStepCommits ?? []),
+        ...(task.dependencyProvenanceRecoveries ?? []).flatMap((recovery) => recovery.retainedHistoricalCommits ?? []),
+        ...environment.verifiedHistoricalStepCommits.filter((commit) => history.includes(commit)),
+      ];
+      const expectedSet = new Set(expectedRegistered);
+      const candidateStart = history.findIndex((commit) => !expectedSet.has(commit));
+      const registeredPrefix = candidateStart < 0 ? history : history.slice(0, candidateStart);
+      const candidateChain = candidateStart < 0 ? [] : history.slice(candidateStart);
+      retainedHistoricalCommits = environment.verifiedHistoricalStepCommits.filter((commit) =>
+        registeredPrefix.includes(commit)
+        && !task.systemCommits.includes(commit)
+        && !task.steps.some((step) => step.evidence?.commitSha === commit)
+      );
+      if (historicalStepProvenance
+        && !retainedHistoricalCommits.includes(historicalStepProvenance.retainedCommitSha)) {
+        blockers.push('The dependency candidate no longer retains the bound reviewed historical Step commit.');
+      }
+      if (history.at(-1) !== head || !sameCommitSet(registeredPrefix, [...new Set(expectedRegistered)])) {
+        blockers.push('Only a trailing dependency-only commit chain may follow the exact recorded Task history.');
+      }
+      parent = registeredPrefix.at(-1) ?? task.baseCommit;
+      let expectedParent = parent;
+      for (const commit of candidateChain) {
+        const inspected = inspectBoundedWorkflowDependencyCommit(repositoryRoot, commit);
+        if (!inspected) {
+          blockers.push(`Unregistered commit ${commit} is not a consecutive bounded Workflow dependency update.`);
+          blockers.push('The candidate commit must change exactly package.json and package-lock.json and only the Workflow dependency pin.');
+          blockers.push(`The candidate commit contains changes beyond the exact ${PACKAGE_NAME}@${PACKAGE_VERSION} dependency update.`);
+          blockers.push('Only a trailing dependency-only commit chain may follow the exact recorded Task history.');
+          continue;
+        }
+        if (inspected.parentCommitSha !== expectedParent) {
+          blockers.push(`Unregistered commit ${commit} does not continue the bounded Workflow dependency parent chain.`);
+          blockers.push('Only a trailing dependency-only commit chain may follow the exact recorded Task history.');
+          continue;
+        }
+        dependencyCommits.push(inspected);
+        expectedParent = commit;
+      }
+      if (dependencyCommits.length !== candidateChain.length || dependencyCommits.at(-1)?.commitSha !== head) {
+        blockers.push('The complete unregistered suffix must be a bounded Workflow dependency-only chain ending at HEAD.');
+      }
+      if (dependencyCommits.at(-1)?.packageVersion !== PACKAGE_VERSION) {
+        blockers.push(`The dependency-only chain must end at ${PACKAGE_NAME}@${PACKAGE_VERSION}.`);
+      }
+    }
+    commitFiles = dependencyCommits.length > 0 ? [...RECOVERY_FILES] : [];
+  } catch {
+    blockers.push('The candidate dependency commit could not be inspected.');
+  }
+
+  if (retainedNavigationCarryover && (dependencyCommits.length !== 1 || task.status !== 'ready'
+    || task.steps.some(step => step.status === 'in_progress')
+    || !task.steps.some(step => step.id === retainedNavigationCarryover.stepId && step.status === 'planned' && step.evidence === null))) {
+    blockers.push('Retained navigation carryover requires one dependency commit and the unchanged ready/planned Step.');
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    action: blockers.length === 0
+      ? activeDownstreamProof
+        ? 'update downstream-proof-dependency-recover'
+        : historicalStepProvenance
+          ? 'update historical-step-dependency-recover'
+          : 'update dependency-provenance-recover'
+      : null,
+    projectId: task.projectId,
+    taskId: task.id,
+    taskRevision: task.revision,
+    commitSha: blockers.length === 0 ? head : null,
+    parentCommitSha: blockers.length === 0 ? parent : null,
+    packageVersion: PACKAGE_VERSION,
+    changedFiles: commitFiles,
+    dependencyCommits,
+    retainedHistoricalCommits,
+    activeDownstreamProof,
+    historicalStepProvenance,
+    ...(retainedNavigationCarryover ? { retainedNavigationCarryover } : {}),
+    blockers,
+  };
+}
+
+function sameCommitSet(actual: string[], expected: string[]): boolean {
+  return actual.length === expected.length
+    && actual.every((commit) => expected.includes(commit))
+    && expected.every((commit) => actual.includes(commit));
+}
+
+export function inspectBoundedWorkflowDependencyCommit(
+  repositoryRoot: string,
+  commitSha: string,
+): { commitSha: string; parentCommitSha: string; packageVersion: string } | null {
+  try {
+    const parentCommitSha = runGit(repositoryRoot, ['rev-parse', `${commitSha}^`]);
+    const output = runGit(repositoryRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', commitSha]);
+    const files = output ? output.split('\n').sort() : [];
+    if (JSON.stringify(files) !== JSON.stringify(RECOVERY_FILES)) return null;
+    const packageVersion = manifestDependencyVersion(parseJson(runGit(repositoryRoot, ['show', `${commitSha}:package.json`])));
+    if (!packageVersion || !workflowDependencyJsonDiffIsBounded(
+      repositoryRoot,
+      parentCommitSha,
+      commitSha,
+      packageVersion,
+    )) return null;
+    return { commitSha, parentCommitSha, packageVersion };
+  } catch {
+    return null;
+  }
+}
+
+export function workflowDependencyVersionAt(repositoryRoot: string, commitSha: string): string | null {
+  try {
+    return manifestDependencyVersion(parseJson(runGit(repositoryRoot, ['show', `${commitSha}:package.json`])));
+  } catch {
+    return null;
+  }
+}
+
+function workflowDependencyJsonDiffIsBounded(
+  repositoryRoot: string,
+  parent: string,
+  revision: string,
+  expectedAfterVersion: string | null,
+): boolean {
+  const beforeManifestContent = runGit(repositoryRoot, ['show', `${parent}:package.json`]);
+  const afterManifestContent = runGit(repositoryRoot, ['show', `${revision}:package.json`]);
+  const beforeLockContent = runGit(repositoryRoot, ['show', `${parent}:package-lock.json`]);
+  const afterLockContent = runGit(repositoryRoot, ['show', `${revision}:package-lock.json`]);
+  const beforeManifest = parseJson(beforeManifestContent);
+  const afterManifest = parseJson(afterManifestContent);
+  const beforeLock = parseJson(beforeLockContent);
+  const afterLock = parseJson(afterLockContent);
+  if (!beforeManifest || !afterManifest || !beforeLock || !afterLock) return false;
+  const beforeManifestDependencies = manifestDependencyValues(beforeManifest);
+  const beforeVersion = beforeManifestDependencies.length === 1 ? beforeManifestDependencies[0] : null;
+  const afterVersion = manifestDependencyVersion(afterManifest);
+  if (!beforeVersion || !afterVersion || beforeVersion === afterVersion) return false;
+  if (!targetsExactDevDependency(beforeManifest, beforeVersion)) return false;
+  if (!targetsExactDevDependency(afterManifest, afterVersion)) return false;
+  if (expectedAfterVersion !== null && afterVersion !== expectedAfterVersion) return false;
+  if (!lockTargetsExactVersion(beforeLock, beforeVersion)) return false;
+  if (!lockTargetsExactVersion(afterLock, afterVersion)) return false;
+  return JSON.stringify(stripManifestDependency(beforeManifest)) === JSON.stringify(stripManifestDependency(afterManifest))
+    && JSON.stringify(stripLockDependency(beforeLock)) === JSON.stringify(stripLockDependency(afterLock));
+}
+
+function parseJson(content: string): Record<string, unknown> | null {
+  try {
+    const value = JSON.parse(content) as unknown;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestDependencyValues(manifest: Record<string, unknown>): string[] {
+  const values: string[] = [];
+  for (const key of ['devDependencies', 'dependencies']) {
+    const group = record(manifest[key]);
+    if (typeof group?.[PACKAGE_NAME] === 'string') values.push(group[PACKAGE_NAME] as string);
+  }
+  return values;
+}
+
+function manifestDependencyVersion(manifest: Record<string, unknown> | null): string | null {
+  if (!manifest) return null;
+  const values = manifestDependencyValues(manifest);
+  return values.length === 1 ? values[0]! : null;
+}
+
+function lockTargetsExactVersion(lock: Record<string, unknown>, version: string): boolean {
+  const packages = record(lock.packages);
+  const entry = record(packages?.[`node_modules/${PACKAGE_NAME}`]);
+  const root = record(packages?.['']);
+  if (entry?.version !== version || !targetsExactDevDependency(root ?? {}, version)) return false;
+  const dependencies = record(lock.dependencies);
+  const legacyEntry = record(dependencies?.[PACKAGE_NAME]);
+  return !legacyEntry || legacyEntry.version === version;
+}
+
+function targetsExactDevDependency(manifest: Record<string, unknown>, version: string): boolean {
+  const devDependencies = record(manifest.devDependencies);
+  const dependencies = record(manifest.dependencies);
+  return devDependencies?.[PACKAGE_NAME] === version && dependencies?.[PACKAGE_NAME] === undefined;
+}
+
+function stripManifestDependency(source: Record<string, unknown>): Record<string, unknown> {
+  const clone = structuredClone(source);
+  for (const key of ['devDependencies', 'dependencies']) {
+    const group = record(clone[key]);
+    if (group) delete group[PACKAGE_NAME];
+  }
+  return clone;
+}
+
+function stripLockDependency(source: Record<string, unknown>): Record<string, unknown> {
+  const clone = structuredClone(source);
+  const packages = record(clone.packages);
+  if (packages) {
+    delete packages[`node_modules/${PACKAGE_NAME}`];
+    const root = record(packages['']);
+    if (root) {
+      for (const key of ['devDependencies', 'dependencies']) {
+        const group = record(root[key]);
+        if (group) delete group[PACKAGE_NAME];
+      }
+    }
+  }
+  const dependencies = record(clone.dependencies);
+  if (dependencies) delete dependencies[PACKAGE_NAME];
+  return clone;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function readGitFile(repositoryRoot: string, revision: string, filePath: string): string {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'show', `${revision}:${filePath}`], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) throw new Error(result.stderr.trim() || `Cannot read ${revision}:${filePath}.`);
+  return result.stdout;
+}

package/src/diagnostics.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { inspectGraphView } from './graph.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+import { runGit } from './repository.js';
+
+export interface DependencyDiagnostic {
+  packageFile: string;
+  declared: string | null;
+  exact: boolean;
+  current: boolean;
+}
+
+export function inspectLocalDependency(repositoryRoot: string): DependencyDiagnostic {
+  const packageFile = path.join(repositoryRoot, 'package.json');
+  if (!existsSync(packageFile)) return { packageFile, declared: null, exact: false, current: false };
+  const manifest = JSON.parse(readFileSync(packageFile, 'utf8')) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+  const declared = manifest.devDependencies?.[PACKAGE_NAME] ?? manifest.dependencies?.[PACKAGE_NAME] ?? null;
+  return {
+    packageFile,
+    declared,
+    exact: declared === PACKAGE_VERSION,
+    current: declared === PACKAGE_VERSION,
+  };
+}
+
+export function integrationDiagnostics(repositoryRoot: string) {
+  return {
+    package: { name: PACKAGE_NAME, version: PACKAGE_VERSION },
+    localDependency: inspectLocalDependency(repositoryRoot),
+    graphView: inspectGraphView(),
+  };
+}
+
+export function inspectWorkflowVersions(repositoryRoot: string, baseBranches: string[]) {
+  const packageFile = path.join(repositoryRoot, 'package.json');
+  const lockFile = path.join(repositoryRoot, 'package-lock.json');
+  const declared = existsSync(packageFile) ? dependencyFromManifest(readFileSync(packageFile, 'utf8')) : null;
+  const locked = existsSync(lockFile) ? dependencyFromLock(readFileSync(lockFile, 'utf8')) : null;
+  const installedFile = path.join(repositoryRoot, 'node_modules', PACKAGE_NAME, 'package.json');
+  const installed = existsSync(installedFile) ? manifestVersion(readFileSync(installedFile, 'utf8')) : null;
+  const currentBranch = gitManifestDependency(repositoryRoot, 'HEAD');
+  const milestoneBases = [...new Set(baseBranches)].map((branch) => ({
+    branch,
+    version: gitManifestDependency(repositoryRoot, branch),
+  }));
+  return { runtime: PACKAGE_VERSION, declared, locked, installed, currentBranch, milestoneBases };
+}
+
+function dependencyFromManifest(content: string): string | null {
+  try {
+    const manifest = JSON.parse(content) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    return manifest.devDependencies?.[PACKAGE_NAME] ?? manifest.dependencies?.[PACKAGE_NAME] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function dependencyFromLock(content: string): string | null {
+  try {
+    const lock = JSON.parse(content) as {
+      packages?: Record<string, { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }>;
+      dependencies?: Record<string, { version?: string }>;
+    };
+    return lock.packages?.[`node_modules/${PACKAGE_NAME}`]?.version
+      ?? lock.packages?.['']?.devDependencies?.[PACKAGE_NAME]
+      ?? lock.packages?.['']?.dependencies?.[PACKAGE_NAME]
+      ?? lock.dependencies?.[PACKAGE_NAME]?.version
+      ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestVersion(content: string): string | null {
+  try {
+    const value = (JSON.parse(content) as { version?: unknown }).version;
+    return typeof value === 'string' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function gitManifestDependency(repositoryRoot: string, revision: string): string | null {
+  try {
+    return dependencyFromManifest(runGit(repositoryRoot, ['show', `${revision}:package.json`]));
+  } catch {
+    return null;
+  }
+}

package/src/domain/base-sync-conflict.ts

@@ -0,0 +1,35 @@
+import { existsSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import type { TaskState } from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { readJson, writeJsonAtomic } from '../fs-utils.js';
+import type { FileStateStore } from '../state/store.js';
+
+type Conflict = { protocol: 'base-sync-conflict-v1'; taskId: string; taskRevision: number; taskHead: string; baseHead: string };
+const fileFor = (store: FileStateStore, task: TaskState) => path.join(store.taskRoot(task.projectId, task.id), 'base-sync-conflict.json');
+
+/** A negative receipt can suppress a repeated attempt, never authorize Git work. */
+export function currentBaseSyncConflict(store: FileStateStore, task: TaskState, taskHead: string, baseHead: string): Conflict | null {
+  const file = fileFor(store, task);
+  if (!existsSync(file)) return null;
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2048) throw new WorkflowError('STATE_CORRUPT', 'Invalid base-sync conflict receipt.');
+  const value = readJson<Conflict>(file);
+  if (!value || Object.keys(value).sort().join(',') !== 'baseHead,protocol,taskHead,taskId,taskRevision'
+    || value.protocol !== 'base-sync-conflict-v1' || value.taskId !== task.id
+    || !Number.isSafeInteger(value.taskRevision) || value.taskRevision < 1
+    || typeof value.taskHead !== 'string' || typeof value.baseHead !== 'string'
+    || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value.taskHead) || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value.baseHead)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Invalid base-sync conflict receipt.');
+  }
+  if (value.taskRevision === task.revision && value.taskHead !== taskHead) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Reviewed Task HEAD changed after a base-sync conflict; retained review authority cannot be reused.');
+  }
+  return value.taskRevision === task.revision && value.taskHead === taskHead && value.baseHead === baseHead ? value : null;
+}
+
+export function recordBaseSyncConflict(store: FileStateStore, task: TaskState, taskHead: string, baseHead: string): void {
+  // Validate existing evidence before replacing a stale negative receipt.
+  currentBaseSyncConflict(store, task, taskHead, baseHead);
+  writeJsonAtomic(fileFor(store, task), { protocol: 'base-sync-conflict-v1', taskId: task.id, taskRevision: task.revision, taskHead, baseHead } satisfies Conflict);
+}

package/src/domain/completed-step-carryover.ts

@@ -0,0 +1,76 @@
+import type { PlanStepInput, TaskPlanInput, TaskState } from '../contracts.js';
+
+type TaskStep = TaskState['steps'][number];
+
+/**
+ * Derive the completed Steps whose authority remains valid under a replacement Plan.
+ *
+ * A completed Step is retained only when its executable definition is unchanged and
+ * every dependency is itself retained. The recursive dependency check makes the
+ * result independent from candidate Plan ordering and fails closed on malformed
+ * dependency cycles even though ordinary Plan validation rejects cycles earlier.
+ */
+export function deriveCompletedStepCarryover(
+  task: TaskState,
+  candidateSteps: readonly TaskPlanInput['steps'][number][],
+): ReadonlyMap<string, TaskStep> {
+  const duplicateCandidateIds = new Set<string>();
+  const candidateById = new Map<string, PlanStepInput>();
+  for (const candidate of candidateSteps) {
+    if (candidateById.has(candidate.id)) duplicateCandidateIds.add(candidate.id);
+    else candidateById.set(candidate.id, normalizePlanStepDefinition(candidate));
+  }
+
+  const exactCompletedById = new Map<string, TaskStep>();
+  for (const previous of task.steps) {
+    if (previous.status !== 'completed' || duplicateCandidateIds.has(previous.id)) continue;
+    const candidate = candidateById.get(previous.id);
+    if (!candidate) continue;
+    if (samePlanStepDefinition(previous, candidate)) exactCompletedById.set(previous.id, previous);
+  }
+
+  const retained = new Map<string, TaskStep>();
+  const rejected = new Set<string>();
+  const visiting = new Set<string>();
+  const retain = (stepId: string): boolean => {
+    if (retained.has(stepId)) return true;
+    if (rejected.has(stepId) || visiting.has(stepId)) return false;
+    const previous = exactCompletedById.get(stepId);
+    if (!previous) {
+      rejected.add(stepId);
+      return false;
+    }
+    visiting.add(stepId);
+    const dependenciesRetained = previous.dependencies.every((dependencyId) => retain(dependencyId));
+    visiting.delete(stepId);
+    if (!dependenciesRetained) {
+      rejected.add(stepId);
+      return false;
+    }
+    retained.set(stepId, previous);
+    return true;
+  };
+
+  for (const stepId of exactCompletedById.keys()) retain(stepId);
+  return retained;
+}
+
+export function normalizePlanStepDefinition(
+  step: PlanStepInput | TaskStep,
+): PlanStepInput {
+  return {
+    id: step.id,
+    title: step.title,
+    objective: step.objective,
+    requirements: [...step.requirements],
+    dependencies: [...step.dependencies],
+    expectedOutputs: [...step.expectedOutputs],
+    allowedWrites: [...step.allowedWrites],
+    forbiddenScope: [...step.forbiddenScope],
+    checks: [...step.checks],
+  };
+}
+
+function samePlanStepDefinition(previous: TaskStep, candidate: PlanStepInput): boolean {
+  return JSON.stringify(normalizePlanStepDefinition(previous)) === JSON.stringify(candidate);
+}