codex-workflow-v2 2.0.0-beta.13.14 → 2.0.0-beta.13.16

package/src/dependency-provenance.ts

@@ -0,0 +1,538 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import type {
+  DependencyProvenanceRecoveryPreflight,
+  DownstreamProofReplanCompatibility,
+  HistoricalStepDependencyCompatibility,
+  PlanIntegrityUpdateCompatibility,
+  ProjectKnowledgeMap,
+  RootCauseReplanDirtyCarryoverCompatibility,
+  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';
+import { pathAllowed } from './domain/validation.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,
+  downstreamProofReplan: DownstreamProofReplanCompatibility | null = null,
+  historicalStepProvenance: HistoricalStepDependencyCompatibility | null = null,
+  planIntegrity: PlanIntegrityUpdateCompatibility | null = null,
+  rootCauseReplan: RootCauseReplanDirtyCarryoverCompatibility | 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, downstreamProofReplan, historicalStepProvenance,
+    planIntegrity, rootCauseReplan].filter(Boolean).length;
+  if (compatibilityCount > 1) blockers.push('Dependency recovery accepts exactly one dirty compatibility binding.');
+
+  const dirtyCompatibility = activeDownstreamProof ?? downstreamProofReplan ?? historicalStepProvenance
+    ?? planIntegrity ?? rootCauseReplan;
+  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 (downstreamProofReplan) {
+      if (task.status !== 'awaiting_execution_authorization'
+        || task.planHash !== downstreamProofReplan.reboundPlanHash
+        || task.steps.some((step) => step.status === 'in_progress')) {
+        blockers.push('The Task must retain the exact stranded post-rebind/no-running-Step posture.');
+      }
+    } 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 (planIntegrity) {
+      const failedStep = task.steps.find((step) => step.id === planIntegrity.stepId) ?? null;
+      if (planIntegrity.mode === 'post-rebind-scope-adoption') {
+        if (task.status !== 'awaiting_execution_authorization'
+          || task.planHash !== planIntegrity.planHash
+          || failedStep?.status !== 'planned'
+          || task.steps.some((step) => step.status === 'in_progress')
+          || !planIntegrity.scopeExtensions?.length
+          || planIntegrity.scopeExtensions.some((scopePath) =>
+            !failedStep.allowedWrites.some((allowedPath) => allowedPath === scopePath))) {
+          blockers.push('The Task must retain the exact post-rebind/no-running-Step check-support adoption posture.');
+        }
+      } else if (planIntegrity.mode === 'post-rebind-dirty-carryover') {
+        if (!['ready', 'in_progress'].includes(task.status)
+          || task.planHash !== planIntegrity.planHash
+          || failedStep?.status !== 'planned'
+          || task.steps.some((step) => step.status === 'in_progress')
+          || !planIntegrity.scopeExtensions?.length
+          || planIntegrity.scopeExtensions.some((scopePath) =>
+            !failedStep.allowedWrites.some((allowedPath) => allowedPath === scopePath)
+            || !failedStep.expectedOutputs.some((declared) =>
+              (declared.startsWith('path:') ? declared.slice(5) : declared) === scopePath))) {
+          blockers.push('The Task must retain the exact authorized/no-running-Step check-support dirty-carryover posture.');
+        }
+      } else if (planIntegrity.mode === 'navigation-fix-dirty-carryover') {
+        if (task.status !== 'ready'
+          || task.planHash !== planIntegrity.planHash
+          || failedStep?.status !== 'planned'
+          || failedStep.evidence !== null
+          || task.steps.some((step) => step.status === 'in_progress')
+          || planIntegrity.dirtyFiles.some((file) => !pathAllowed(file, failedStep.allowedWrites))) {
+          blockers.push('The Task must retain the exact ready/planned navigation-fix dirty-carryover posture.');
+        }
+      } else if (task.status !== 'needs_fix'
+          || task.planHash !== planIntegrity.planHash
+          || failedStep?.status !== 'failed'
+          || task.steps.some((step) => step.status === 'in_progress')) {
+          blockers.push('The Task must retain the exact failed/no-running-Step Plan-integrity posture.');
+      }
+    } else if (rootCauseReplan) {
+      const correctiveStep = task.steps.find((step) => step.id === rootCauseReplan.stepId) ?? null;
+      if (task.status !== 'ready'
+        || correctiveStep?.status !== 'planned'
+        || correctiveStep.evidence !== null
+        || task.steps.some((step) => step.status === 'in_progress')
+        || task.id !== rootCauseReplan.taskId
+        || task.revision !== rootCauseReplan.sourceTaskRevision
+        || !task.planHash) {
+        blockers.push('The Task must retain the exact authorized corrective-replan/no-running-Step posture.');
+      }
+      if (rootCauseReplan.dirtyFiles.some((file) => !correctiveStep
+        || !pathAllowed(file, correctiveStep.allowedWrites))) {
+        blockers.push('Corrective carryover cannot expand the replacement Step allowedWrites.');
+      }
+    }
+  } 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.');
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    action: blockers.length === 0
+      ? activeDownstreamProof
+        ? 'update downstream-proof-dependency-recover'
+        : downstreamProofReplan
+          ? 'update downstream-proof-replan-dependency-recover'
+          : historicalStepProvenance
+            ? 'update historical-step-dependency-recover'
+            : planIntegrity
+              ? 'update plan-integrity-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,
+    downstreamProofReplan,
+    historicalStepProvenance,
+    planIntegrity,
+    rootCauseReplan,
+    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;
+  }
+}