sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,92 @@
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+type TaskDependencyModel = Pick<SddTaskModel, 'tasks'>;
+
+export interface TaskDependencyReadinessEntry {
+  taskId: string;
+  status: SddTask['status'] | 'missing';
+  ready: boolean;
+  reason: string | null;
+}
+
+export interface TaskDependencyReadiness {
+  taskId: string;
+  ready: boolean;
+  dependencies: TaskDependencyReadinessEntry[];
+  blockingReasons: string[];
+}
+
+export interface WorkflowDependencyBlocker {
+  taskId: string;
+  dependencyId: string;
+  dependencyStatus: SddTask['status'] | 'missing';
+  reason: string;
+}
+
+export function resolveTaskDependencyReadiness(model: TaskDependencyModel, taskId: string): TaskDependencyReadiness {
+  const task = model.tasks.find((candidate) => candidate.id === taskId) ?? null;
+  if (!task) {
+    return { taskId, ready: false, dependencies: [], blockingReasons: [`Task ${taskId} was not found.`] };
+  }
+
+  const dependencies = task.dependsOn.map((dependencyId) => dependencyReadinessEntry(task.id, dependencyId, model.tasks.find((candidate) => candidate.id === dependencyId) ?? null));
+  const blockingReasons = dependencies.map((dependency) => dependency.reason).filter((reason): reason is string => Boolean(reason));
+  return {
+    taskId: task.id,
+    ready: blockingReasons.length === 0,
+    dependencies,
+    blockingReasons
+  };
+}
+
+export function dependencyBlockingReasonsForTask(model: TaskDependencyModel, taskId: string): string[] {
+  return resolveTaskDependencyReadiness(model, taskId).blockingReasons;
+}
+
+export function workflowDependencyBlockers(model: TaskDependencyModel): WorkflowDependencyBlocker[] {
+  const blockers: WorkflowDependencyBlocker[] = [];
+  for (const task of model.tasks) {
+    if (task.status === 'completed' || task.status === 'deferred') {
+      continue;
+    }
+    for (const dependency of resolveTaskDependencyReadiness(model, task.id).dependencies) {
+      if (!dependency.ready && dependency.reason) {
+        blockers.push({
+          taskId: task.id,
+          dependencyId: dependency.taskId,
+          dependencyStatus: dependency.status,
+          reason: dependency.reason
+        });
+      }
+    }
+  }
+  return blockers;
+}
+
+export function nextDependencyTaskId(model: TaskDependencyModel, taskId: string): string | null {
+  return resolveTaskDependencyReadiness(model, taskId).dependencies.find((dependency) => !dependency.ready)?.taskId ?? null;
+}
+
+function dependencyReadinessEntry(taskId: string, dependencyId: string, dependency: SddTask | null): TaskDependencyReadinessEntry {
+  if (!dependency) {
+    return {
+      taskId: dependencyId,
+      status: 'missing',
+      ready: false,
+      reason: `Task ${taskId} depends on ${dependencyId}, but ${dependencyId} was not found; restore or remove the dependency before continuing ${taskId}.`
+    };
+  }
+  if (dependency.status === 'completed') {
+    return {
+      taskId: dependency.id,
+      status: dependency.status,
+      ready: true,
+      reason: null
+    };
+  }
+  return {
+    taskId: dependency.id,
+    status: dependency.status,
+    ready: false,
+    reason: `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} status is ${dependency.status}; complete and sync-back ${dependency.id} before continuing ${taskId}.`
+  };
+}

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

@@ -0,0 +1,115 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
+import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { bindTestRunState, markTestRunReadyForSyncBack } from '../test-support/run-state.js';
+import { createDelegationRecord } from '../delegation/validation.js';
+import { resolveWorkflowState } from './resolve.js';
+
+test('workflow state resolver projects branch docs latest run and next action', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const run = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, run.runId, 'feature', 'T1');
+    await markTestRunReadyForSyncBack(root, run.runId, 'T1');
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.contract, 'phase-7.3-workflow-state-resolver-v1');
+    assert.equal(workflow.workflowStatus, 'active');
+    assert.equal(workflow.latestRun?.runId, 'run-1');
+    assert.deepEqual(workflow.latestRunsByTask.map((entry) => `${entry.partition}:${entry.taskId}:${entry.runId}`), ['feature:T1:run-1']);
+    assert.equal(workflow.taskCounts.total, 1);
+    assert.equal(workflow.recommendedNextCommand, 'sdd sync-back inspect --branch feature --task T1');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state resolver reports affected-file conflicts without run-index rebuild', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-conflict-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `${validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'src/shared.ts')}\n${validTaskMarkdown('T2', []).replace('T1', 'T2').replace('packages/core/src/index.ts', 'src/shared.ts')}`);
+    const runA = await createRun(root, { runId: 'run-a' });
+    await bindTestRunState(root, runA.runId, 'feature', 'T1');
+    await markTestRunReadyForSyncBack(root, runA.runId, 'T1');
+    const runB = await createRun(root, { runId: 'run-b' });
+    await bindTestRunState(root, runB.runId, 'feature', 'T2');
+    const archived = await createRun(root, { runId: 'run-c' });
+    await writeRunState(root, { ...archived, status: 'archived' });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.deepEqual(workflow.affectedFileConflicts.map((entry) => entry.runId), ['run-b']);
+    assert.equal(workflow.blockingReasons.some((reason) => reason.includes('src/shared.ts')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state ignores superseded failed and foreground observer conflict candidates', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-filtered-conflicts-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'docs/t1.md'));
+    const failed = await createRun(root, { runId: 'run-failed' });
+    await bindTestRunState(root, failed.runId, 'feature', 'T1');
+    await writeRunState(root, {
+      ...await readRunState(root, failed.runId),
+      status: 'failed',
+      validation: { status: 'fail', commands: ['npm test'], evidence: [] }
+    });
+    const observer = await createRun(root, { runId: 'run-observer' });
+    await bindTestRunState(root, observer.runId, 'feature', 'T1');
+    const delegation = createDelegationRecord({
+      delegationId: 'F-T1-observer-001',
+      task: 'T1',
+      agent: 'observer',
+      runMode: 'foreground',
+      blocking: false,
+      requiredForPhaseExit: false,
+      expectedArtifact: 'artifacts/observer-T1.md'
+    });
+    await writeRunState(root, {
+      ...await readRunState(root, observer.runId),
+      status: 'completed',
+      phase: 'foreground-subagents',
+      delegations: { [delegation.delegationId]: { ...delegation, status: 'COMPLETED', terminalEventAt: new Date().toISOString() } }
+    });
+    const retry = await createRun(root, { runId: 'run-retry' });
+    await bindTestRunState(root, retry.runId, 'feature', 'T1');
+    await markTestRunReadyForSyncBack(root, retry.runId, 'T1');
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.latestRun?.runId, 'run-retry');
+    assert.deepEqual(workflow.affectedFileConflicts, []);
+    assert.equal(workflow.blockingReasons.some((reason) => reason.includes('Affected file')), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state resolver surfaces dependency blockers and points next action upstream', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-dependencies-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks\n\n${validTaskMarkdown('DEP1', [])}\n${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'DEP2' });
+
+    assert.deepEqual(workflow.dependencyBlockers.map((blocker) => `${blocker.taskId}->${blocker.dependencyId}`), ['DEP2->DEP1']);
+    assert.equal(workflow.blockingReasons.some((reason) => reason.includes('DEP2 depends on DEP1')), true);
+    assert.equal(workflow.recommendedNextCommand, 'sdd tasks inspect DEP1 --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,175 @@
+import { WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
+import { recordRuntimeProjection } from '../storage/runtime-store.js';
+import type { RunState, 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 SddTaskGap, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { workflowDependencyBlockers, type WorkflowDependencyBlocker } from './dependencies.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;
+}
+
+
+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[];
+  affectedFileConflicts: WorkflowAffectedFileConflict[];
+  blockingReasons: string[];
+  dependencyBlockers: WorkflowDependencyBlocker[];
+  recommendedNextCommand: string;
+}
+
+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 latestRunsByTask = latestTaskRuns(states, branch);
+  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 dependencyBlockers = workflowDependencyBlockers(model);
+  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,
+    affectedFileConflicts,
+    dependencyBlockers,
+    blockingReasons,
+    recommendedNextCommand: recommendedNextCommand(context, model, latestRunState, visibleGaps, dependencyBlockers)
+  };
+  await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(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 latestTaskRuns(states: RunState[], partition: string): WorkflowLatestTaskRun[] {
+  const latest = new Map<string, WorkflowLatestTaskRun>();
+  for (const state of states) {
+    if (state.status === 'archived' || state.partition !== partition || !state.taskId) {
+      continue;
+    }
+    const entry: WorkflowLatestTaskRun = {
+      partition,
+      gitBranch: state.gitBranch,
+      taskId: state.taskId,
+      runId: state.runId,
+      runStatus: state.status,
+      validationStatus: state.validation.status,
+      syncBackStatus: state.syncBack.status,
+      affectedFiles: state.affectedFiles,
+      updatedAt: state.updatedAt
+    };
+    const existing = latest.get(entry.taskId);
+    if (!existing || Date.parse(entry.updatedAt) > Date.parse(existing.updatedAt) || (entry.updatedAt === existing.updatedAt && entry.runId.localeCompare(existing.runId) > 0)) {
+      latest.set(entry.taskId, entry);
+    }
+  }
+  return Array.from(latest.values()).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 recommendedNextCommand(context: ContextResolverContract, model: SddTaskModel, latestRun: RunState | null, gaps: SddTaskGap[], dependencyBlockers: WorkflowDependencyBlocker[]): string {
+  if (!workflowIsActive(model)) {
+    return context.branchSource === 'git_branch' ? '/sdd:spec' : `/sdd:spec --branch ${context.rawBranch}`;
+  }
+  if (gaps.some((gap) => gap.severity === 'blocking')) {
+    return `sdd tasks gaps --branch ${context.partition}`;
+  }
+  const dependencyBlocker = dependencyBlockers[0];
+  if (dependencyBlocker) {
+    return `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`;
+  }
+  if (latestRun?.syncBack.status === 'proposed' && latestRun.currentTask) {
+    return `sdd sync-back inspect --branch ${context.partition} --task ${latestRun.currentTask}`;
+  }
+  const pendingTask = model.tasks.find((task) => task.status === 'pending');
+  return pendingTask ? `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}` : `sdd tasks list --branch ${context.partition}`;
+}
+
+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,
+    affectedFileConflicts: resolution.affectedFileConflicts,
+    dependencyBlockers: resolution.dependencyBlockers,
+    blockingReasons: resolution.blockingReasons,
+    recommendedNextCommand: resolution.recommendedNextCommand
+  };
+}

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

@@ -0,0 +1 @@
+export * from './workflow-state/resolve.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(/^\.\//, '');
+}