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

package/src/alpha6/navigation-dirty-carryover.ts

@@ -0,0 +1,154 @@
+import type { PlanIntegrityUpdateCompatibility, TaskState } from '../contracts.js';
+import { inspectBoundedWorkflowDependencyCommit } from '../dependency-provenance.js';
+import { assertKnowledgeBindingOnlyPlanChange, readVerifiedPlanArtifact } from '../domain/plan-semantics.js';
+import { pathAllowed } from '../domain/validation.js';
+import { validateTaskHistory } from '../git.js';
+import { changedFiles, currentBranch, gitIsAncestor, headCommit, runGit } from '../repository.js';
+import type { FileStateStore } from '../state/store.js';
+import { hashDirtyWorktree } from './downstream-proof.js';
+import { readTaskC1Posture, readTaskHandoffEvents } from './handoff.js';
+import { assertMechanicalFeasibilityFresh, hashMechanicalFeasibilityEvidence } from './mechanical-feasibility.js';
+import { readCurrentPlanRiskAudit, readPlanRiskAuditEvents } from './plan-risk.js';
+import { verifiedHistoricalStepReviewBindings } from './review.js';
+import { readRemediationEvents } from './remediation.js';
+
+export interface NavigationDirtyCarryoverAssessment {
+  applicable: boolean;
+  eligible: boolean;
+  compatibility: PlanIntegrityUpdateCompatibility | null;
+  blockers: string[];
+  requiredActor?: string;
+}
+
+/** Validate an existing native checkpoint; this never grants writes or execution authority. */
+export function assessNavigationDirtyCarryover(
+  store: FileStateStore,
+  repositoryRoot: string,
+  task: TaskState,
+  stepId?: string,
+  historyBoundary = headCommit(repositoryRoot),
+  authorizationBoundary = headCommit(repositoryRoot),
+): NavigationDirtyCarryoverAssessment {
+  const records = (task.dependencyProvenanceRecoveries ?? []).filter(record =>
+    record.planIntegrity?.mode === 'navigation-fix-dirty-carryover'
+    && (!stepId || record.planIntegrity.stepId === stepId));
+  const record = records.at(-1);
+  if (!record) return { applicable: false, eligible: false, compatibility: null, blockers: [] };
+  const binding = record.planIntegrity!;
+  const blockers: string[] = [];
+  const require = (condition: unknown, message: string) => { if (!condition) blockers.push(message); };
+  let requiredActor: string | undefined;
+  try {
+    const step = task.steps.find(candidate => candidate.id === binding.stepId);
+    require(task.status === 'ready' && task.workspaceOwner === 'local', 'Navigation checkpoint requires a ready local Task.');
+    require(task.taskBranch && currentBranch(repositoryRoot) === task.taskBranch, 'Navigation checkpoint requires the owned Task branch.');
+    require(step?.status === 'planned' && step.evidence === null, 'The checkpoint Step must remain planned without evidence.');
+    require(!task.steps.some(candidate => candidate.status === 'in_progress'), 'No Step may be in progress.');
+    require(task.systemCommits.includes(record.commitSha)
+      && (task.dependencyProvenanceRecoveries ?? []).filter(item => item.commitSha === record.commitSha).length === 1
+      && record.packageName === 'codex-workflow-v2'
+      && JSON.stringify(record.files) === JSON.stringify(['package-lock.json', 'package.json']),
+      'The checkpoint must have one exact registered Workflow dependency record.');
+    const inspected = inspectBoundedWorkflowDependencyCommit(repositoryRoot, record.commitSha);
+    require(inspected?.parentCommitSha === record.parentCommitSha && inspected?.packageVersion === record.packageVersion,
+      'The checkpoint is not the exact recorded dependency-only commit.');
+    require(gitIsAncestor(repositoryRoot, record.commitSha, historyBoundary), 'The checkpoint must precede the assessed history boundary.');
+    validateTaskHistory(repositoryRoot, task, historyBoundary);
+    const suffix = runGit(repositoryRoot, ['rev-list', '--reverse', `${record.commitSha}..${historyBoundary}`]).split('\n').filter(Boolean);
+    let parent = record.commitSha;
+    for (const commit of suffix) {
+      const inspectedCommit = inspectBoundedWorkflowDependencyCommit(repositoryRoot, commit);
+      const matches = (task.dependencyProvenanceRecoveries ?? []).filter(item => item.commitSha === commit);
+      require(inspectedCommit?.parentCommitSha === parent && matches.length === 1
+        && matches[0]!.parentCommitSha === parent && matches[0]!.packageVersion === inspectedCommit?.packageVersion
+        && task.systemCommits.includes(commit), 'Checkpoint continuation requires exact registered dependency-only continuity.');
+      parent = commit;
+    }
+    const dirty = changedFiles(repositoryRoot).sort();
+    require(dirty.length > 0 && JSON.stringify(dirty) === JSON.stringify([...binding.dirtyFiles].sort())
+      && hashDirtyWorktree(repositoryRoot, dirty) === binding.dirtyWorktreeHash, 'Navigation checkpoint dirty paths or bytes changed.');
+    if (step) {
+      require(dirty.every(file => pathAllowed(file, step.allowedWrites) && !pathAllowed(file, step.forbiddenScope)),
+        'Checkpoint dirty files must remain inside allowedWrites and outside forbiddenScope.');
+      require(step.dependencies.every(id => task.steps.find(item => item.id === id)?.status === 'completed'),
+        'Checkpoint Step dependencies must be complete.');
+    }
+    const events = readRemediationEvents(store, task).filter(event => event.stepId === binding.stepId && event.failureKind === 'checks-failed');
+    require(events.length > 0 && JSON.stringify(events.map(event => event.eventId)) === JSON.stringify(binding.remediationEventIds),
+      'Checkpoint remediation IDs must equal the complete ordered native Step check-failure history.');
+    const terminal = events.at(-1);
+    require(terminal?.failureEvidence.dirtyWorktreeHash === binding.dirtyWorktreeHash
+      && terminal?.failureEvidence.completionCommit === record.parentCommitSha,
+    'The terminal native failure must bind the checkpoint parent and exact dirty bytes.');
+    require(terminal && Number.isFinite(Date.parse(record.recordedAt)) && Date.parse(record.recordedAt) >= Date.parse(terminal.recordedAt),
+      'The checkpoint timestamp must follow its native failure.');
+    const root = store.taskRoot(task.projectId, task.id);
+    require(task.planHash && task.briefHash && store.hashArtifact(root, 'brief.md') === task.briefHash,
+      'Current Brief authority does not match its artifact.');
+    if (!task.planHash) throw new Error('Current Plan is missing.');
+    let expected = binding.planHash;
+    readVerifiedPlanArtifact(root, expected, task.planHash);
+    const planHashes = [expected];
+    if (expected !== task.planHash) {
+      const start = task.knowledgeRebinds.findIndex(item => item.previousPlanHash === expected);
+      require(start >= 0, 'Checkpoint Plan requires an exact Knowledge-rebind chain.');
+      let previousTime = Number.NEGATIVE_INFINITY;
+      for (const item of start < 0 ? [] : task.knowledgeRebinds.slice(start)) {
+        require(item.previousPlanHash === expected && !planHashes.includes(item.reboundPlanHash)
+          && Number.isFinite(Date.parse(item.recordedAt)) && Date.parse(item.recordedAt) > previousTime,
+        'Checkpoint Knowledge-rebind chain forks, cycles, or has invalid timestamps.');
+        assertKnowledgeBindingOnlyPlanChange(readVerifiedPlanArtifact(root, item.previousPlanHash, task.planHash),
+          readVerifiedPlanArtifact(root, item.reboundPlanHash, task.planHash));
+        expected = item.reboundPlanHash;
+        previousTime = Date.parse(item.recordedAt);
+        planHashes.push(expected);
+      }
+    }
+    require(expected === task.planHash, 'Checkpoint Plan chain does not terminate at the current Plan.');
+    const audit = readCurrentPlanRiskAudit(store, task);
+    require(audit && ['approved', 'approved-with-rationale'].includes(audit.audit.decision), 'Current approved Plan Risk Audit is required.');
+    const audits = readPlanRiskAuditEvents(store, task);
+    const reviews = verifiedHistoricalStepReviewBindings(store, task);
+    for (const completed of task.steps.filter(item => item.status === 'completed')) {
+      require(completed.evidence, 'Every completed Step must retain execution evidence.');
+      const guarded = audits.some(item => item.stepClassifications.some(classification => classification.stepId === completed.id && classification.reviewRequired));
+      if (guarded) require(completed.evidence && reviews.some(review => review.stepId === completed.id && review.commitSha === completed.evidence!.commitSha),
+        'Completed guarded Step must retain verified strict-review evidence.');
+    }
+    const selected = planHashes.map(hash => audits.filter(item => item.planHash === hash));
+    require(selected.every(matches => matches.length === 1), 'Checkpoint Plan audit chain is missing or ambiguous.');
+    if (selected.every(matches => matches.length === 1)) {
+      const chain = selected.map(matches => matches[0]!);
+      require(chain.at(-1)?.eventHash === audit?.audit.eventHash, 'Checkpoint audit chain must reach the current audit.');
+      chain.forEach((item, index) => {
+        require(item.briefHash === task.briefHash, 'Checkpoint audit Brief authority changed.');
+        if (index) {
+          const before = chain[index - 1]!;
+          require(item.previousEventHash === before.eventHash && item.planner === before.planner
+            && item.auditor !== item.planner && item.decision === before.decision
+            && item.splitRationale === before.splitRationale
+            && JSON.stringify(item.stepClassifications) === JSON.stringify(before.stepClassifications),
+          'Checkpoint Plan Risk Audit changed beyond its Knowledge binding.');
+        }
+      });
+    }
+    const authorization = [...task.authorizations].reverse().find(item => item.kind === 'execution' && item.decision === 'approved');
+    require(authorization && authorization.planHash === task.planHash && authorization.briefHash === task.briefHash
+      && authorization.headCommit === authorizationBoundary
+      && gitIsAncestor(repositoryRoot, authorizationBoundary, headCommit(repositoryRoot)), 'Current execution authorization must bind the exact Brief, Plan and HEAD.');
+    if (!authorization?.mechanicalFeasibility) throw new Error('Checkpoint requires current mechanical-feasibility evidence.');
+    require(authorization.evidenceHash === hashMechanicalFeasibilityEvidence(authorization.mechanicalFeasibility)
+      && authorization.headCommit === authorization.mechanicalFeasibility.evaluatedHead,
+      'Mechanical-feasibility evidence hash or HEAD does not match authorization.');
+    assertMechanicalFeasibilityFresh(repositoryRoot, task, authorization.mechanicalFeasibility, task.briefHash!, task.planHash);
+    const posture = readTaskC1Posture(store, task);
+    const claim = readTaskHandoffEvents(store, task).filter(event => event.eventType === 'claim').at(-1);
+    requiredActor = claim?.actor;
+    require(posture.state === 'claimed' && claim && posture.claimant === claim.actor
+      && planHashes.includes(claim.planHash ?? '') && claim.briefHash === task.briefHash,
+      'Checkpoint requires its original actor with a current immutable claimed C1 boundary.');
+  } catch (error) { blockers.push(error instanceof Error ? error.message : String(error)); }
+  return { applicable: true, eligible: blockers.length === 0,
+    compatibility: blockers.length ? null : { ...structuredClone(binding), planHash: task.planHash! },
+    blockers: [...new Set(blockers)], ...(requiredActor ? { requiredActor } : {}) };
+}

package/src/alpha6/npm-check-contract.ts

@@ -0,0 +1,47 @@
+import path from 'node:path';
+
+const NPM_RUN_CHECK = /^npm\s+run(?:-script)?\s+([A-Za-z0-9._:-]+)(?:\s+--\s+(.+))?$/;
+const SAFE_FORWARD_ARG = /^--[A-Za-z0-9._:-]+=[^\s]+$/;
+const NODE_AFFECTED_SCRIPT = /^node\s+([A-Za-z0-9._/-]+\.(?:cjs|js|mjs))\s+affected$/;
+const SELECTOR = /^(?:--base|--head|--files)=.+$/;
+
+export interface ParsedNpmRunCheck {
+  script: string;
+  forwardedArguments: string[];
+}
+
+export interface RequiredSelectorContract {
+  runnerPath: string;
+  selectors: readonly ['--base', '--head', '--files'];
+}
+
+export function parseNpmRunCheck(command: string): ParsedNpmRunCheck | null {
+  const match = NPM_RUN_CHECK.exec(command.trim());
+  if (!match) return null;
+  const forwardedArguments = match[2]?.trim().split(/\s+/).filter(Boolean) ?? [];
+  if (forwardedArguments.some((argument) => !SAFE_FORWARD_ARG.test(argument))) return null;
+  return { script: match[1]!, forwardedArguments };
+}
+
+export function inspectRequiredSelectorContract(
+  scriptCommand: string,
+  readRunner: (runnerPath: string) => string | null,
+): RequiredSelectorContract | null {
+  const match = NODE_AFFECTED_SCRIPT.exec(scriptCommand.trim());
+  if (!match) return null;
+  const runnerPath = match[1]!;
+  if (path.posix.isAbsolute(runnerPath)
+    || runnerPath.split('/').some((segment) => segment === '.' || segment === '..')) return null;
+  const source = readRunner(runnerPath);
+  if (!source
+    || !source.includes('process.argv.slice(3)')
+    || !source.includes('--base')
+    || !source.includes('--head')
+    || !source.includes('--files')
+    || !source.includes('Affected mode requires')) return null;
+  return { runnerPath, selectors: ['--base', '--head', '--files'] };
+}
+
+export function hasRequiredSelector(arguments_: readonly string[]): boolean {
+  return arguments_.some((argument) => SELECTOR.test(argument));
+}

package/src/alpha6/plan-integrity.ts

@@ -0,0 +1,298 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import type {
+  PlanIntegrityConflictEvidence,
+  PlanIntegrityConflictEvidenceV2,
+  PlanIntegrityConflictEvidenceV3,
+  PlanIntegrityConflictEvidenceV4,
+  TaskState,
+} from '../contracts.js';
+import { pathAllowed } from '../domain/validation.js';
+import { WorkflowError } from '../errors.js';
+import { hashCanonical } from '../lifecycle/fingerprint.js';
+import { changedFiles, headCommit } from '../repository.js';
+import type { FileStateStore } from '../state/store.js';
+import {
+  hasRequiredSelector,
+  inspectRequiredSelectorContract,
+  parseNpmRunCheck,
+} from './npm-check-contract.js';
+import { inspectCheckSupportAnchors } from './check-support-anchor.js';
+import { inspectFailedCheckComponentOwners, semanticBoundaryHash } from './component-owner.js';
+import {
+  readCorrectiveDecisionEvents,
+  readRemediationEvents,
+  selectPlanIntegrityRemediations,
+} from './remediation.js';
+
+const ROOT_MANIFEST = 'package.json' as const;
+const TASK_ID = /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/;
+
+export interface PlanIntegrityRecoveryAssessment {
+  readonly applicable: boolean;
+  readonly eligible: boolean;
+  readonly taskId: string;
+  readonly taskRevision: number;
+  readonly stepId: string;
+  readonly planHash: string | null;
+  readonly blockers: readonly string[];
+  readonly evidence: PlanIntegrityConflictEvidence | null;
+}
+
+export function defaultPlanIntegrityRecoveryActor(taskId: string): string {
+  if (!TASK_ID.test(taskId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Cannot derive a Plan-integrity recovery actor from invalid Task ID ${taskId}.`);
+  }
+  return `agent:plan-integrity-recovery:${taskId.toLowerCase()}`;
+}
+
+export function assessPlanIntegrityRecovery(
+  store: FileStateStore,
+  repositoryRoot: string,
+  task: TaskState,
+  stepId: string,
+): PlanIntegrityRecoveryAssessment {
+  const base = {
+    taskId: task.id,
+    taskRevision: task.revision,
+    stepId,
+    planHash: task.planHash,
+  };
+  const step = task.steps.find((candidate) => candidate.id === stepId) ?? null;
+  if (!step || task.status !== 'needs_fix' || step.status !== 'failed' || !task.planHash) {
+    return { ...base, applicable: false, eligible: false, blockers: [], evidence: null };
+  }
+
+  const allRemediations = readRemediationEvents(store, task).filter((event) => event.stepId === stepId);
+  const decisions = readCorrectiveDecisionEvents(store, task).filter((event) => event.stepId === stepId);
+  const remediations = selectPlanIntegrityRemediations(store, task, allRemediations, decisions);
+  if (!remediations || remediations.some(event => event.failureKind !== 'checks-failed')) {
+    return { ...base, applicable: false, eligible: false, blockers: [], evidence: null };
+  }
+
+  const manifest = inspectRootManifest(repositoryRoot);
+  const runnerBlockers: string[] = [];
+  const conflicts: PlanIntegrityConflictEvidenceV2['conflicts'] = [];
+  for (const command of step.checks) {
+    const invocation = parseNpmRunCheck(command);
+    if (!invocation) continue;
+    const scriptCommand = manifest.scripts.get(invocation.script) ?? null;
+    if (scriptCommand === null) {
+      if (pathAllowed(ROOT_MANIFEST, step.allowedWrites)) continue;
+      conflicts.push({
+        reasonCode: 'MISSING_NPM_SCRIPT' as const,
+        script: invocation.script,
+        command: command.trim(),
+        scriptCommand: null,
+        runnerPath: null,
+        runnerHash: null,
+      });
+      continue;
+    }
+    const runnerInspections = new Map<string, ReturnType<typeof inspectRepositoryFile>>();
+    const selectorContract = inspectRequiredSelectorContract(scriptCommand, (runnerPath) => {
+      const inspection = inspectRepositoryFile(repositoryRoot, runnerPath);
+      runnerInspections.set(runnerPath, inspection);
+      return inspection.content;
+    });
+    if (!selectorContract || hasRequiredSelector(invocation.forwardedArguments)) continue;
+    const runnerInspection = runnerInspections.get(selectorContract.runnerPath) ?? null;
+    if (runnerInspection?.blocker) runnerBlockers.push(runnerInspection.blocker);
+    if (pathAllowed(ROOT_MANIFEST, step.allowedWrites)
+      || pathAllowed(selectorContract.runnerPath, step.allowedWrites)) continue;
+    conflicts.push({
+      reasonCode: 'REQUIRED_SELECTOR_MISSING' as const,
+      script: invocation.script,
+      command: command.trim(),
+      scriptCommand,
+      runnerPath: selectorContract.runnerPath,
+      runnerHash: runnerInspection?.hash ?? null,
+    });
+  }
+  conflicts.sort((left, right) => left.command.localeCompare(right.command) || left.reasonCode.localeCompare(right.reasonCode));
+  const supportConflicts: PlanIntegrityConflictEvidenceV3['conflicts'] = conflicts.length === 0
+    ? inspectCheckSupportAnchors({
+        step,
+        scripts: manifest.scripts,
+        readFile: (relativePath) => {
+          const inspected = inspectRepositoryFile(repositoryRoot, relativePath);
+          return { content: inspected.content, hash: inspected.hash };
+        },
+        pathExists: (relativePath) => gitPathExists(repositoryRoot, headCommit(repositoryRoot), relativePath),
+      }).map((conflict) => ({
+        ...conflict,
+        expectedOutputPaths: [...conflict.expectedOutputPaths],
+        anchoredMigrationNames: [...conflict.anchoredMigrationNames],
+      }))
+    : [];
+  const componentOwnerConflicts: PlanIntegrityConflictEvidenceV4['conflicts'] =
+    conflicts.length === 0 && supportConflicts.length === 0
+      ? inspectFailedCheckComponentOwners({
+          step,
+          scripts: manifest.scripts,
+          isTracked: (relativePath) => gitPathExists(repositoryRoot, headCommit(repositoryRoot), relativePath),
+          readFile: (relativePath) => {
+            const inspected = inspectRepositoryFile(repositoryRoot, relativePath);
+            return { content: inspected.content, hash: inspected.hash };
+          },
+        }).map(({ causeFingerprint: _causeFingerprint, ...conflict }) => conflict)
+      : [];
+  if (conflicts.length === 0 && supportConflicts.length === 0 && componentOwnerConflicts.length === 0) {
+    return { ...base, applicable: false, eligible: false, blockers: [], evidence: null };
+  }
+
+  if (remediations.length !== allRemediations.length && conflicts.length > 0)
+    return { ...base, applicable: false, eligible: false, blockers: [], evidence: null };
+
+  const files = [...changedFiles(repositoryRoot)].sort();
+  const outsideAllowedWrites = files.filter((file) => !pathAllowed(file, step.allowedWrites));
+  const forbiddenChanges = files.filter((file) => pathAllowed(file, step.forbiddenScope));
+  const blockers = [
+    ...(manifest.blocker ? [manifest.blocker] : []),
+    ...runnerBlockers,
+    ...(outsideAllowedWrites.length > 0
+      ? [`Changed files outside ${stepId} allowedWrites: ${outsideAllowedWrites.join(', ')}`]
+      : []),
+    ...(forbiddenChanges.length > 0
+      ? [`Changed files intersect ${stepId} forbiddenScope: ${forbiddenChanges.join(', ')}`]
+      : []),
+    ...supportConflicts.flatMap((conflict) => pathAllowed(conflict.supportPath, step.forbiddenScope)
+      ? [`Check-support authority ${conflict.supportPath} intersects ${stepId} forbiddenScope.`]
+      : []),
+    ...componentOwnerConflicts.flatMap((conflict) => pathAllowed(conflict.ownerPath, step.forbiddenScope)
+      ? [`Component owner ${conflict.ownerPath} intersects ${stepId} forbiddenScope.`]
+      : []),
+  ];
+  const stepDefinitionHash = hashCanonical({
+    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,
+  });
+  const remediationBindings = remediations.map((event) => ({
+    eventId: event.eventId,
+    eventHash: event.eventHash,
+    attemptOrdinal: event.attemptOrdinal,
+  }));
+  const evidenceBase = supportConflicts.length > 0 ? {
+    kind: 'check-support-anchor-outside-allowed-writes' as const,
+    taskRevision: task.revision,
+    remediationEvents: remediationBindings,
+    manifestPath: ROOT_MANIFEST,
+    manifestHash: manifest.hash,
+    gitHead: headCommit(repositoryRoot),
+    stepDefinitionHash,
+    conflicts: supportConflicts,
+    scopeExtensions: [...new Set(supportConflicts.map((conflict) => conflict.supportPath))].sort(),
+    changedFiles: files,
+  } : componentOwnerConflicts.length > 0 ? {
+    kind: 'failed-check-component-owner-outside-allowed-writes' as const,
+    taskRevision: task.revision,
+    remediationEvents: remediationBindings,
+    gitHead: headCommit(repositoryRoot),
+    stepDefinitionHash,
+    semanticBoundaryHash: semanticBoundaryHash(task),
+    failedCheckCauseFingerprint: step.failurePause!.failedChecks!.find((failure) =>
+      componentOwnerConflicts.some((conflict) => conflict.command === failure.command))!.causeFingerprint,
+    conflicts: componentOwnerConflicts,
+    scopeExtensions: [...new Set(componentOwnerConflicts.map((conflict) => conflict.ownerPath))].sort(),
+    changedFiles: files,
+  } : {
+    kind: 'non-executable-npm-check-outside-allowed-writes' as const,
+    taskRevision: task.revision,
+    remediationEvents: remediationBindings,
+    manifestPath: ROOT_MANIFEST,
+    manifestHash: manifest.hash,
+    gitHead: headCommit(repositoryRoot),
+    stepDefinitionHash,
+    conflicts,
+    changedFiles: files,
+  };
+  const evidence: PlanIntegrityConflictEvidence = {
+    ...evidenceBase,
+    conflictHash: hashCanonical({
+      domain: supportConflicts.length > 0
+        ? 'codex-workflow/plan-integrity-conflict/v3'
+        : componentOwnerConflicts.length > 0
+          ? 'codex-workflow/plan-integrity-conflict/v4'
+          : 'codex-workflow/plan-integrity-conflict/v2',
+      taskId: task.id,
+      planHash: task.planHash,
+      stepId,
+      evidence: evidenceBase,
+    }),
+  };
+  return {
+    ...base,
+    applicable: true,
+    eligible: blockers.length === 0,
+    blockers,
+    evidence,
+  };
+}
+
+function gitPathExists(repositoryRoot: string, commit: string, relativePath: string): boolean {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'cat-file', '-e', `${commit}:${relativePath}`], {
+    encoding: 'utf8',
+  });
+  if (result.status === 0) return true;
+  if (result.status === 128) return false;
+  throw new WorkflowError('COMMAND_FAILED', `Unable to inspect ${relativePath} at ${commit}.`, {
+    stderr: result.stderr.trim(),
+    exitCode: result.status,
+  });
+}
+
+function inspectRootManifest(repositoryRoot: string): {
+  readonly scripts: ReadonlyMap<string, string>;
+  readonly hash: string | null;
+  readonly blocker: string | null;
+} {
+  const file = path.join(repositoryRoot, ROOT_MANIFEST);
+  if (!existsSync(file)) return { scripts: new Map(), hash: null, blocker: null };
+  const stat = lstatSync(file);
+  if (!stat.isFile()) {
+    return { scripts: new Map(), hash: null, blocker: 'Root package.json is not a regular file.' };
+  }
+  const bytes = readFileSync(file);
+  const hash = createHash('sha256').update(bytes).digest('hex');
+  try {
+    const parsed = JSON.parse(bytes.toString('utf8')) as { scripts?: unknown };
+    if (parsed.scripts === undefined) return { scripts: new Map(), hash, blocker: null };
+    if (!parsed.scripts || typeof parsed.scripts !== 'object' || Array.isArray(parsed.scripts)) {
+      return { scripts: new Map(), hash, blocker: 'Root package.json scripts field is malformed.' };
+    }
+    return {
+      scripts: new Map(Object.entries(parsed.scripts)
+        .filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
+      hash,
+      blocker: null,
+    };
+  } catch {
+    return { scripts: new Map(), hash, blocker: 'Root package.json is not valid JSON.' };
+  }
+}
+
+function inspectRepositoryFile(repositoryRoot: string, relativePath: string): {
+  content: string | null;
+  hash: string | null;
+  blocker: string | null;
+} {
+  const file = path.join(repositoryRoot, relativePath);
+  if (!existsSync(file)) return { content: null, hash: null, blocker: `${relativePath} is missing.` };
+  const stat = lstatSync(file);
+  if (!stat.isFile()) return { content: null, hash: null, blocker: `${relativePath} is not a regular file.` };
+  const bytes = readFileSync(file);
+  return {
+    content: bytes.toString('utf8'),
+    hash: createHash('sha256').update(bytes).digest('hex'),
+    blocker: null,
+  };
+}