sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/workflow-state/resolve.ts

@@ -0,0 +1,363 @@
+import { WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
+import { recordRuntimeProjection } from '../storage/runtime-store.js';
+import type { RunState, RunStateTaskRuntime, RunSummary } from '../run-state/model.js';
+import { affectedFileConflictsForSelectedRun, type WorkflowAffectedFileConflict } from './affected-file-conflicts.js';
+import { readAllRunStates, summarizeRunState } from '../run-state/run-state.js';
+import { resolveSddContext, type ContextBranchSource, type ContextResolverContract } from '../sdd-docs/context.js';
+import { parseSddBranch, type SddTask, type SddTaskGap, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { dependencyBlockingReasonsForTask, workflowDependencyBlockers, type WorkflowDependencyBlocker } from './dependencies.js';
+import { selectLatestEligibleRunsByTask, type DocumentCompatibilityClass, type LatestEligibleRunSelection } from './latest-eligible-run.js';
+
+export interface WorkflowTaskCounts {
+  total: number;
+  pending: number;
+  inProgress: number;
+  completed: number;
+  blocked: number;
+  deferred: number;
+  unknown: number;
+  gaps: number;
+}
+
+export interface WorkflowLatestTaskRun {
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunState['status'];
+  validationStatus: RunState['validation']['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  affectedFiles: string[];
+  updatedAt: string;
+  compatibility: DocumentCompatibilityClass;
+  eligibleForDefaultApply: boolean;
+  reasons: string[];
+}
+
+export type WorkflowCommandSemantics = 'inspection_navigation' | 'gate_execution';
+export type WorkflowHostProjectionStatus = 'active' | 'future' | 'unsupported';
+export type WorkflowNextStage = 'spec' | 'tasks' | 'do' | 'test' | 'ship';
+export type WorkflowNextIntentKind = 'start_spec' | 'resolve_task_gaps' | 'inspect_dependency' | 'ship_readiness' | 'inspect_task' | 'list_tasks' | 'continue_do' | 'run_task_validation' | 'run_batch_validation' | 'run_wave_validation';
+
+export interface WorkflowHostCommandProjection {
+  host: 'claude_code' | 'codex' | 'opencode';
+  status: WorkflowHostProjectionStatus;
+  entry: string | null;
+  projectionSurfaces: string[];
+  permissionProjection: string;
+  reason: string;
+}
+
+export interface WorkflowNextIntent {
+  stage: WorkflowNextStage;
+  intent: WorkflowNextIntentKind;
+  canonicalCommand: string;
+  commandSemantics: WorkflowCommandSemantics;
+  evidenceRequirement: string;
+  blockingReason: string | null;
+  hostProjections: WorkflowHostCommandProjection[];
+}
+
+
+export interface WorkflowStateResolution {
+  contract: typeof WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION;
+  generatedAt: string;
+  branch: string;
+  workflowStatus: 'active' | 'not_started';
+  context: ContextResolverContract;
+  documents: SddTaskModel['documents'];
+  model: SddTaskModel;
+  taskCounts: WorkflowTaskCounts;
+  visibleGaps: SddTaskGap[];
+  latestRun: RunSummary | null;
+  latestRunState: RunState | null;
+  latestRunsByTask: WorkflowLatestTaskRun[];
+  latestEligibleRunsByTask: LatestEligibleRunSelection[];
+  affectedFileConflicts: WorkflowAffectedFileConflict[];
+  blockingReasons: string[];
+  dependencyBlockers: WorkflowDependencyBlocker[];
+  recommendedNextCommand: string;
+  nextIntent: WorkflowNextIntent;
+}
+
+export async function resolveWorkflowState(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; taskId?: string | null } = {}): Promise<WorkflowStateResolution> {
+  const context = await resolveSddContext(projectRoot, options);
+  const branch = context.partition;
+  const [model, states] = await Promise.all([parseSddBranch(projectRoot, branch), readAllRunStates(projectRoot)]);
+  const visibleGaps = workflowIsActive(model) ? model.gaps : [];
+  const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch });
+  const latestRunsByTask = selectedLatestTaskRuns(latestEligibleRunsByTask);
+  const selectedTaskRun = options.taskId
+    ? latestRunsByTask.find((entry) => entry.taskId === options.taskId) ?? null
+    : latestRunsByTask.slice().sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0] ?? null;
+  const latestRunState = selectedTaskRun ? states.find((state) => state.runId === selectedTaskRun.runId) ?? null : null;
+  const affectedFileConflicts = latestRunState ? affectedFileConflictsForSelectedRun(states, latestRunState) : [];
+  const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
+  const dependencyBlockers = workflowDependencyBlockers(model, { runtimeByTask });
+  const blockingReasons = blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers);
+  const resolution: WorkflowStateResolution = {
+    contract: WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    branch,
+    workflowStatus: workflowIsActive(model) ? 'active' : 'not_started',
+    context,
+    documents: model.documents,
+    model,
+    taskCounts: taskCounts(model, visibleGaps),
+    visibleGaps,
+    latestRun: latestRunState ? summarizeRunState(latestRunState) : null,
+    latestRunState,
+    latestRunsByTask,
+    latestEligibleRunsByTask,
+    affectedFileConflicts,
+    dependencyBlockers,
+    blockingReasons,
+    nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask),
+    recommendedNextCommand: ''
+  };
+  resolution.recommendedNextCommand = resolution.nextIntent.canonicalCommand;
+  try {
+    await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(resolution));
+  } catch {
+    // Projection writes are rebuildable and must not block workflow resolution.
+  }
+  return resolution;
+}
+
+function workflowIsActive(model: SddTaskModel): boolean {
+  return model.documents.specExists || model.documents.planExists || model.documents.tasksExists;
+}
+
+function taskCounts(model: SddTaskModel, gaps: SddTaskGap[]): WorkflowTaskCounts {
+  return {
+    total: model.tasks.length,
+    pending: model.tasks.filter((task) => task.status === 'pending').length,
+    inProgress: model.tasks.filter((task) => task.status === 'in_progress').length,
+    completed: model.tasks.filter((task) => task.status === 'completed').length,
+    blocked: model.tasks.filter((task) => task.status === 'blocked').length,
+    deferred: model.tasks.filter((task) => task.status === 'deferred').length,
+    unknown: model.tasks.filter((task) => task.status === 'unknown').length,
+    gaps: gaps.length
+  };
+}
+
+function selectedLatestTaskRuns(selections: LatestEligibleRunSelection[]): WorkflowLatestTaskRun[] {
+  return selections
+    .flatMap((selection) => selection.selected ? [selection.selected] : [])
+    .map((candidate) => ({
+      partition: candidate.partition,
+      gitBranch: candidate.gitBranch,
+      taskId: candidate.taskId,
+      runId: candidate.runId,
+      runStatus: candidate.runStatus,
+      validationStatus: candidate.validationStatus,
+      syncBackStatus: candidate.syncBackStatus,
+      affectedFiles: candidate.affectedFiles,
+      updatedAt: candidate.updatedAt,
+      compatibility: candidate.compatibility,
+      eligibleForDefaultApply: candidate.eligibleForDefaultApply,
+      reasons: candidate.reasons
+    }))
+    .sort((left, right) => left.taskId.localeCompare(right.taskId));
+}
+
+
+function blockingWorkflowReasons(gaps: SddTaskGap[], conflicts: WorkflowAffectedFileConflict[], dependencyBlockers: WorkflowDependencyBlocker[]): string[] {
+  const reasons = gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`);
+  for (const conflict of conflicts) {
+    reasons.push(`Affected file ${conflict.file} is active in run ${conflict.runId} for ${conflict.partition}/${conflict.taskId}.`);
+  }
+  for (const blocker of dependencyBlockers) {
+    reasons.push(blocker.reason);
+  }
+  return reasons;
+}
+
+function recommendedWorkflowNextIntent(
+  context: ContextResolverContract,
+  model: SddTaskModel,
+  latestRunsByTask: WorkflowLatestTaskRun[],
+  gaps: SddTaskGap[],
+  dependencyBlockers: WorkflowDependencyBlocker[],
+  runtimeByTask: Map<string, RunStateTaskRuntime>
+): WorkflowNextIntent {
+  if (!workflowIsActive(model)) {
+    return workflowNextIntent('spec', 'start_spec', `sdd spec --branch ${context.partition}`, 'Start the spec stage before planning or task execution.', null);
+  }
+  const blockingGap = gaps.find((gap) => gap.severity === 'blocking');
+  if (blockingGap) {
+    return workflowNextIntent('tasks', 'resolve_task_gaps', `sdd tasks gaps --branch ${context.partition}`, 'Resolve blocking task document gaps before execution evidence can be trusted.', `${blockingGap.field}: ${blockingGap.message}`);
+  }
+
+  const strictTask = model.tasks.find((task) => needsTaskValidation(task, runtimeByTask.get(task.id)));
+  if (strictTask) {
+    return workflowNextIntent('test', 'run_task_validation', `sdd test task ${strictTask.id} --branch ${context.partition}`, 'Validate this strict or task_end task before more implementation proceeds.', null);
+  }
+
+  const readyBoundary = readyValidationBoundary(model, runtimeByTask);
+  if (readyBoundary?.kind === 'batch') {
+    return workflowNextIntent('test', 'run_batch_validation', `sdd test batch ${readyBoundary.id} --branch ${context.partition}`, `Validate accumulated implementation evidence for batch ${readyBoundary.id}.`, null);
+  }
+  if (readyBoundary?.kind === 'wave') {
+    return workflowNextIntent('test', 'run_wave_validation', waveValidationCommand(context.partition, readyBoundary.wave), `Validate accumulated implementation evidence for wave ${readyBoundary.wave ?? 'all'}.`, null);
+  }
+
+  if (latestRunsByTask.some(latestEligibleRunReadyForShip)) {
+    return workflowNextIntent('ship', 'ship_readiness', `sdd ship --branch ${context.partition} --dry-run`, 'Run release readiness after validation PASS; create a decision card only if the gate requires human review.', null);
+  }
+
+  const nextTask = model.tasks.find((task) => task.status === 'pending' && !runtimeTaskImplemented(runtimeByTask.get(task.id)) && dependencyBlockingReasonsForTask(model, task.id, { runtimeByTask }).length === 0);
+  if (nextTask) {
+    return workflowNextIntent('do', 'continue_do', `sdd do task ${nextTask.id} --branch ${context.partition}`, 'Continue sequential implementation; validation can wait until the declared task or batch boundary.', null);
+  }
+
+  const dependencyBlocker = dependencyBlockers[0];
+  if (dependencyBlocker) {
+    return workflowNextIntent('tasks', 'inspect_dependency', `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`, 'Inspect the dependency task before continuing this workflow.', dependencyBlocker.reason);
+  }
+
+  const pendingTask = model.tasks.find((task) => task.status === 'pending');
+  return pendingTask
+    ? workflowNextIntent('tasks', 'inspect_task', `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}`, 'Inspect task boundary, acceptance, validation, and capability needs before do/test.', null)
+    : workflowNextIntent('tasks', 'list_tasks', `sdd tasks list --branch ${context.partition}`, 'Inspect task state and decide whether to continue or ship.', null);
+}
+
+function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], states: RunState[]): Map<string, RunStateTaskRuntime> {
+  const stateByRunId = new Map(states.map((state) => [state.runId, state]));
+  const result = new Map<string, RunStateTaskRuntime>();
+  for (const selection of selections) {
+    const selected = selection.selected;
+    if (!selected) {
+      continue;
+    }
+    const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
+    if (taskState) {
+      result.set(selected.taskId, taskState);
+    }
+  }
+  return result;
+}
+
+function needsTaskValidation(task: SddTask, runtime: RunStateTaskRuntime | undefined): boolean {
+  return Boolean(runtimeTaskImplemented(runtime) && runtime?.verificationStatus !== 'pass' && (task.requiresVerifyBeforeNext || task.validationTiming === 'task_end'));
+}
+
+function readyValidationBoundary(model: SddTaskModel, runtimeByTask: Map<string, RunStateTaskRuntime>): { kind: 'batch'; id: string } | { kind: 'wave'; wave: number | null } | null {
+  const batchGroups = new Map<string, SddTask[]>();
+  const waveGroups = new Map<string, { wave: number | null; tasks: SddTask[] }>();
+  for (const task of model.tasks) {
+    if (task.validationTiming === 'batch_end' && task.validationBatch) {
+      batchGroups.set(task.validationBatch, [...(batchGroups.get(task.validationBatch) ?? []), task]);
+    }
+    if (task.validationTiming === 'wave_end') {
+      const key = String(task.wave ?? 'all');
+      const group = waveGroups.get(key) ?? { wave: task.wave, tasks: [] };
+      group.tasks.push(task);
+      waveGroups.set(key, group);
+    }
+  }
+  for (const [id, tasks] of batchGroups) {
+    if (validationBoundaryReady(tasks, runtimeByTask)) {
+      return { kind: 'batch', id };
+    }
+  }
+  for (const group of waveGroups.values()) {
+    if (validationBoundaryReady(group.tasks, runtimeByTask)) {
+      return { kind: 'wave', wave: group.wave };
+    }
+  }
+  return null;
+}
+
+function validationBoundaryReady(tasks: SddTask[], runtimeByTask: Map<string, RunStateTaskRuntime>): boolean {
+  return tasks.every((task) => runtimeTaskImplemented(runtimeByTask.get(task.id)))
+    && tasks.some((task) => runtimeByTask.get(task.id)?.verificationStatus !== 'pass');
+}
+
+function runtimeTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
+  return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
+}
+
+function latestEligibleRunReadyForShip(run: WorkflowLatestTaskRun): boolean {
+  return run.runStatus === 'completed' && run.validationStatus === 'pass';
+}
+
+function waveValidationCommand(branch: string, wave: number | null): string {
+  return wave === null ? `sdd test wave --branch ${branch}` : `sdd test wave --branch ${branch} --wave ${wave}`;
+}
+
+
+function workflowNextIntent(
+  stage: WorkflowNextStage,
+  intent: WorkflowNextIntentKind,
+  canonicalCommand: string,
+  evidenceRequirement: string,
+  blockingReason: string | null
+): WorkflowNextIntent {
+  return {
+    stage,
+    intent,
+    canonicalCommand,
+    commandSemantics: stage === 'do' || stage === 'test' || stage === 'ship' ? 'gate_execution' : 'inspection_navigation',
+    evidenceRequirement,
+    blockingReason,
+    hostProjections: hostCommandProjections(canonicalCommand)
+  };
+}
+
+function hostCommandProjections(canonicalCommand: string): WorkflowHostCommandProjection[] {
+  return [
+    {
+      host: 'claude_code',
+      status: 'active',
+      entry: claudeCodeSlashEntry(canonicalCommand),
+      projectionSurfaces: ['slash command', 'skill', 'settings/hooks/statusline metadata'],
+      permissionProjection: 'Claude Code permission mode/tool prompts remain host enforcement, not SDD lifecycle truth.',
+      reason: 'Claude Code supports slash/skill/statusline projections; the canonical CLI command remains the portable source of workflow intent.'
+    },
+    {
+      host: 'codex',
+      status: 'future',
+      entry: null,
+      projectionSurfaces: ['config.toml profile', 'AGENTS.md instruction surface', 'approval_policy', 'sandbox_mode'],
+      permissionProjection: 'Codex approval and sandbox controls can project execution policy; custom command/skill projection is not marked active without stronger evidence.',
+      reason: 'Codex exposes approval, sandbox, AGENTS.md, and built-in slash surfaces, but project custom workflow command semantics stay future until validated.'
+    },
+    {
+      host: 'opencode',
+      status: 'active',
+      entry: opencodeCommandEntry(canonicalCommand),
+      projectionSurfaces: ['opencode.json/jsonc', '.opencode/commands', '.opencode/agents', '.opencode/skills', 'permissions'],
+      permissionProjection: 'OpenCode allow/ask/deny permissions can project SDD tool policy; SDD artifacts remain authoritative evidence.',
+      reason: 'OpenCode documents project commands, agents, skills, and permissions suitable for host-specific projection.'
+    }
+  ];
+}
+
+function claudeCodeSlashEntry(canonicalCommand: string): string {
+  const [command, ...rest] = canonicalCommand.replace(/^sdd\s+/, '').split(' ');
+  return `/sdd:${command}${rest.length > 0 ? ` ${rest.join(' ')}` : ''}`;
+}
+
+function opencodeCommandEntry(canonicalCommand: string): string {
+  return `/sdd ${canonicalCommand.replace(/^sdd\s+/, '')}`;
+}
+
+function projectWorkflowStateProjection(resolution: WorkflowStateResolution): unknown {
+  return {
+    contract: resolution.contract,
+    generatedAt: resolution.generatedAt,
+    branch: resolution.branch,
+    workflowStatus: resolution.workflowStatus,
+    documents: resolution.documents,
+    taskCounts: resolution.taskCounts,
+    latestRun: resolution.latestRun,
+    latestRunsByTask: resolution.latestRunsByTask,
+    latestEligibleRunsByTask: resolution.latestEligibleRunsByTask,
+    affectedFileConflicts: resolution.affectedFileConflicts,
+    dependencyBlockers: resolution.dependencyBlockers,
+    blockingReasons: resolution.blockingReasons,
+    nextIntent: resolution.nextIntent,
+    recommendedNextCommand: resolution.recommendedNextCommand
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-state.ts

@@ -0,0 +1,2 @@
+export * from './workflow-state/resolve.js';
+export * from './workflow-state/dependencies.js';

package/node_modules/@sdd-agent-platform/core/src/worktree/isolation.ts

@@ -0,0 +1,130 @@
+import { inspectToolCapability, listToolCapabilities } from '../registries/tool-capabilities.js';
+import type { ToolCapabilitySideEffect } from '../registries/tool-capabilities.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+
+export const WORKTREE_ISOLATION_CONTRACT_VERSION = 'phase-3.7-worktree-isolation-contract-v1';
+
+export type WorktreeIsolationMode = 'none' | 'required' | 'blocked' | 'manual';
+
+export interface WorktreeIsolationPeer {
+  taskId: string;
+  affectedFiles: string[];
+  risk: string[];
+}
+
+export interface WorktreeIsolationGate {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+export interface WorktreeIsolationDecision {
+  version: string;
+  taskId: string;
+  mode: WorktreeIsolationMode;
+  safeConcurrency: boolean;
+  capabilityId: string;
+  capabilitySideEffect: ToolCapabilitySideEffect;
+  affectedFiles: string[];
+  risk: string[];
+  peers: WorktreeIsolationPeer[];
+  overlaps: Array<{ peerTaskId: string; files: string[] }>;
+  gates: WorktreeIsolationGate[];
+  reasons: string[];
+}
+
+export async function inspectWorktreeIsolation(projectRoot: string, options: { branch?: string; taskId: string; capabilityId?: string; peerTaskIds?: string[] }): Promise<WorktreeIsolationDecision> {
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const [model, capabilityRegistry] = await Promise.all([parseSddBranch(projectRoot, branch), listToolCapabilities(projectRoot)]);
+  const inspected = inspectSddTask(model, options.taskId);
+  const capabilityId = options.capabilityId ?? 'native-file-edit';
+  const capability = capabilityRegistry.capabilities.find((candidate) => candidate.id === capabilityId);
+  const task = inspected.task;
+  const affectedFiles = task?.affectedFiles ?? [];
+  const risk = task?.risk ?? [];
+  const peers = (options.peerTaskIds ?? []).map((peerTaskId): WorktreeIsolationPeer => {
+    const peer = inspectSddTask(model, peerTaskId).task;
+    return { taskId: peerTaskId, affectedFiles: peer?.affectedFiles ?? [], risk: peer?.risk ?? [] };
+  });
+  const sideEffect = capability?.sideEffect ?? 'local_write';
+  const overlaps = peers
+    .map((peer) => ({ peerTaskId: peer.taskId, files: overlappingFiles(affectedFiles, peer.affectedFiles) }))
+    .filter((overlap) => overlap.files.length > 0);
+  const riskProfile = buildTaskRiskProfile(task);
+  const highRisk = riskProfile.riskLevel === 'high';
+  const manualRisk = riskProfile.securitySensitive || riskProfile.normalizedTags.includes('database');
+  const unsafeOverlap = overlaps.length > 0 && sideEffect !== 'read_only';
+  const reasons: string[] = [];
+  const gates: WorktreeIsolationGate[] = [];
+
+  if (!task) {
+    reasons.push(`Task ${options.taskId} is missing or ambiguous in specs/${branch}/tasks.md.`);
+  }
+  if (!capability) {
+    reasons.push(`Capability ${capabilityId} is not declared in the Phase 3.1 capability registry.`);
+  }
+  if (unsafeOverlap) {
+    reasons.push(`Writable task overlaps peer affected file(s): ${overlaps.map((overlap) => `${overlap.peerTaskId}:${overlap.files.join(',')}`).join('; ')}.`);
+  }
+  if (manualRisk) {
+    reasons.push('Database/security risk profile requires manual isolation gate before worktree lifecycle automation.');
+  } else if (highRisk && sideEffect !== 'read_only') {
+    reasons.push('High-risk writable task risk profile requires worktree isolation.');
+  } else if (sideEffect === 'read_only') {
+    reasons.push('Read-only capability does not require worktree isolation.');
+  } else if (sideEffect === 'local_write' || sideEffect === 'command_execution') {
+    reasons.push('Writable or command-executing capability requires worktree isolation unless blocked by overlap.');
+  }
+
+  gates.push(
+    { name: 'task_found', passed: task !== null, message: task ? `Task ${options.taskId} found.` : `Task ${options.taskId} missing or ambiguous.` },
+    { name: 'capability_declared', passed: capability !== undefined, message: capability ? `Capability ${capabilityId} side_effect=${sideEffect}.` : `Capability ${capabilityId} missing.` },
+    { name: 'files_overlap', passed: overlaps.length === 0, message: overlaps.length === 0 ? 'No peer affected_files overlap.' : `Overlaps: ${overlaps.map((overlap) => `${overlap.peerTaskId}:${overlap.files.join(',')}`).join('; ')}` },
+    { name: 'unsafe_concurrency', passed: !unsafeOverlap, message: unsafeOverlap ? 'Writable overlapping tasks are not safe to run concurrently.' : 'No unsafe writable overlap detected.' },
+    { name: 'read_only', passed: sideEffect === 'read_only', message: sideEffect === 'read_only' ? 'Read-only task can run without worktree.' : 'Task may mutate local state or execute commands.' }
+  );
+
+  const mode: WorktreeIsolationMode = !task || !capability || unsafeOverlap
+    ? 'blocked'
+    : manualRisk || sideEffect === 'external_interaction'
+      ? 'manual'
+      : sideEffect === 'read_only'
+        ? 'none'
+        : 'required';
+
+  return {
+    version: WORKTREE_ISOLATION_CONTRACT_VERSION,
+    taskId: options.taskId,
+    mode,
+    safeConcurrency: mode !== 'blocked',
+    capabilityId,
+    capabilitySideEffect: sideEffect,
+    affectedFiles,
+    risk,
+    peers,
+    overlaps,
+    gates,
+    reasons
+  };
+}
+
+export async function inspectWorktreeIsolationContract(projectRoot: string): Promise<{ valid: boolean; issues: string[] }> {
+  const capability = await inspectToolCapability(projectRoot, 'native-file-edit');
+  const issues: string[] = [];
+  if (!capability) {
+    issues.push('native-file-edit capability is missing.');
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+function overlappingFiles(left: string[], right: string[]): string[] {
+  const rightSet = new Set(right.map(normalizeComparablePath));
+  return left.filter((file) => rightSet.has(normalizeComparablePath(file)));
+}
+
+function normalizeComparablePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}