sdd-agent-platform 0.3.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/phase8-risk-kernel.test.ts

@@ -0,0 +1,272 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { initProject } from './config/init-project.js';
+import type { CodingRiskSignal } from './risk.js';
+import { evaluateLifecycleRiskDecision, evaluateLifecycleRiskDecisionForModel, evaluateLifecycleRiskDecisionFromProfile, inspectLifecycleRiskDecisionForModel, LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, LIFECYCLE_RISK_POLICY_VERSION, lifecycleRiskDecisionScopeKey, recordLifecycleRiskDecisionProjection, readLifecycleRiskDecisionProjection, taskRiskProfileToCodingRiskProfile } from './risk.js';
+import { buildTaskRiskProfile } from './task-risk-profile.js';
+import type { SddTask, SddTaskModel } from './sdd-docs/task-parser.js';
+import { recordRuntimeProjectionEnvelope } from './storage/runtime-store.js';
+
+const scope = { branch: 'master', taskId: 'PHASE8-3' };
+
+test('lifecycle risk kernel allows direct for low-risk known work', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('workflow', 'low', 'high')],
+    factSet: knownFacts(),
+    generatedAt: '2026-05-01T00:00:00.000Z'
+  });
+
+  assert.equal(decision.profile, 'direct');
+  assert.deepEqual(decision.requiredStages, ['do', 'test']);
+  assert.equal(decision.approvalPolicy, 'auto-allow');
+  assert.equal(decision.humanCheckpointRequired, false);
+  assert.equal(decision.requiredEvidence.length, 1);
+  assert.equal(Object.hasOwn(decision, 'agent'), false);
+  assert.equal(Object.hasOwn(decision, 'subagent'), false);
+});
+
+test('lifecycle risk kernel selects compact for bounded context and evidence signals', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('context', 'medium', 'medium'), signal('evidence', 'low', 'high')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(decision.profile, 'compact');
+  assert.deepEqual(decision.requiredStages, ['tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back']);
+  assert.equal(decision.approvalPolicy, 'review-required');
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'evidence'), true);
+});
+
+test('lifecycle risk kernel selects full for source runtime and security risks', () => {
+  const profile = taskRiskProfileToCodingRiskProfile(buildTaskRiskProfile({
+    id: 'PHASE8-3',
+    risk: ['security'],
+    affectedFiles: ['packages/core/src/risk/kernel.ts', '.sdd/runtime.sqlite']
+  }), scope, '2026-05-01T00:00:00.000Z');
+  const decision = evaluateLifecycleRiskDecisionFromProfile(profile, knownFacts(), '2026-05-01T00:00:00.000Z');
+
+  assert.equal(decision.profile, 'full');
+  assert.deepEqual(decision.requiredStages, ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back']);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'source-boundary'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'runtime-state'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'security'), true);
+  assert.equal(decision.approvalPolicy, 'human-required');
+});
+
+test('lifecycle risk kernel selects research for low-confidence external impact', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('external', 'high', 'low')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(decision.profile, 'research');
+  assert.deepEqual(decision.requiredStages, ['spec', 'plan', 'verifies']);
+  assert.equal(decision.requiredEvidence.length, 0);
+  assert.equal(decision.humanCheckpointRequired, true);
+  assert.equal(decision.approvalPolicy, 'human-required');
+});
+
+test('lifecycle risk kernel blocks unknown intent or blocked signals first', () => {
+  const unknownIntent = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('workflow', 'low', 'high')],
+    factSet: {
+      request: { intentKnown: false, acceptanceKnown: true, validationKnown: true },
+      documents: { specExists: false, planExists: false, tasksExists: false, verifiesExists: false }
+    }
+  });
+  const blockedSignal = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('security', 'blocked', 'high'), signal('source', 'high', 'high')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(unknownIntent.profile, 'blocked');
+  assert.deepEqual(unknownIntent.requiredStages, []);
+  assert.deepEqual(unknownIntent.blockedStages, ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back', 'ship']);
+  assert.equal(unknownIntent.approvalPolicy, 'blocked');
+  assert.equal(blockedSignal.profile, 'blocked');
+  assert.equal(blockedSignal.approvalPolicy, 'blocked');
+});
+
+test('lifecycle risk decision projection can be written and read', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-kernel-'));
+  try {
+    await initProject(root);
+    const decision = evaluateLifecycleRiskDecision({
+      scope,
+      signals: [signal('source', 'high', 'high')],
+      factSet: knownFacts(),
+      inputHash: 'risk-input-a',
+      generatedAt: '2026-05-01T00:00:00.000Z'
+    });
+    const write = await recordLifecycleRiskDecisionProjection(root, decision);
+    const restored = await readLifecycleRiskDecisionProjection(root, scope);
+
+    assert.equal(write.status, 'created');
+    assert.equal(restored?.projectionType, 'phase8_lifecycle_risk_decision');
+    assert.equal(restored?.payload.profile, 'full');
+    assert.equal(restored?.payload.inputHash, 'risk-input-a');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports missing projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-missing-'));
+  try {
+    await initProject(root);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', taskModel());
+
+    assert.equal(diagnostic.status, 'missing');
+    assert.equal(diagnostic.profile, null);
+    assert.equal(diagnostic.producerVersion, null);
+    assert.equal(diagnostic.expectedProducerVersion, LIFECYCLE_RISK_POLICY_VERSION);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports stale projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-stale-'));
+  try {
+    await initProject(root);
+    const model = taskModel();
+    const decision = {
+      ...evaluateLifecycleRiskDecisionForModel('master', model),
+      inputHash: 'old-risk-input'
+    };
+    await recordLifecycleRiskDecisionProjection(root, decision);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'stale');
+    assert.equal(diagnostic.inputHash, 'old-risk-input');
+    assert.notEqual(diagnostic.inputHash, diagnostic.expectedInputHash);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports blocked fresh projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-blocked-'));
+  try {
+    await initProject(root);
+    const model = taskModel({ specExists: false, tasks: [] });
+    const decision = evaluateLifecycleRiskDecisionForModel('master', model);
+    await recordLifecycleRiskDecisionProjection(root, decision);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'blocked');
+    assert.equal(diagnostic.profile, 'blocked');
+    assert.equal(diagnostic.approvalPolicy, 'blocked');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports incompatible producer versions', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-incompatible-'));
+  try {
+    await initProject(root);
+    const model = taskModel();
+    const decision = evaluateLifecycleRiskDecisionForModel('master', model);
+    await recordRuntimeProjectionEnvelope(root, {
+      projectionType: LIFECYCLE_RISK_DECISION_PROJECTION_TYPE,
+      scopeKey: lifecycleRiskDecisionScopeKey(decision.scope),
+      inputHash: decision.inputHash,
+      producer: 'phase8-risk-kernel',
+      producerVersion: 'phase8-risk-kernel-v0',
+      payload: {
+        ...decision,
+        policyVersion: 'phase8-risk-kernel-v0'
+      },
+      generatedAt: '2026-05-01T00:00:00.000Z'
+    });
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'incompatible');
+    assert.equal(diagnostic.producerVersion, 'phase8-risk-kernel-v0');
+    assert.equal(diagnostic.expectedProducerVersion, LIFECYCLE_RISK_POLICY_VERSION);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+function signal(dimension: CodingRiskSignal['dimension'], level: CodingRiskSignal['level'], confidence: CodingRiskSignal['confidence']): CodingRiskSignal {
+  return {
+    id: `test:${dimension}:${level}:${confidence}`,
+    dimension,
+    level,
+    scope,
+    confidence,
+    inputRefs: [{ kind: 'task', ref: 'PHASE8-3' }],
+    reasons: [`${dimension} ${level} test signal`]
+  };
+}
+
+function knownFacts() {
+  return {
+    request: { intentKnown: true, acceptanceKnown: true, validationKnown: true },
+    documents: { specExists: true, planExists: true, tasksExists: true, verifiesExists: false }
+  };
+}
+
+function taskModel(options: { specExists?: boolean; tasks?: SddTask[] } = {}): SddTaskModel {
+  const tasks = options.tasks ?? [task()];
+  const specExists = options.specExists ?? true;
+  return {
+    branch: 'master',
+    specPath: 'specs/master/spec.md',
+    planPath: 'specs/master/plan.md',
+    tasksPath: 'specs/master/tasks.md',
+    verifyPath: 'specs/master/verify.md',
+    documents: {
+      specExists,
+      planExists: true,
+      tasksExists: tasks.length > 0,
+      verifyExists: true
+    },
+    tasks,
+    gaps: []
+  };
+}
+
+function task(): SddTask {
+  return {
+    id: 'PHASE8-4',
+    title: 'Integrate lifecycle risk diagnostics',
+    status: 'pending',
+    wave: null,
+    dependsOn: [],
+    affectedFiles: ['packages/core/src/status/project-status.ts'],
+    validation: ['npm test'],
+    validationCommands: [],
+    risk: [],
+    acceptanceRefs: [],
+    planRefs: [],
+    fileOwnership: [],
+    agentFit: [],
+    verificationAvailability: [],
+    autonomy: null,
+    allowedAgents: [],
+    requiredArtifacts: [],
+    gapState: null,
+    boundary: null,
+    acceptance: [],
+    implementationNotes: null,
+    rawMetadata: {},
+    source: {
+      filePath: 'specs/master/tasks.md',
+      heading: null,
+      lineStart: 1,
+      lineEnd: 1
+    }
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/planning/task-graph.test.ts

@@ -0,0 +1,86 @@
+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 { doctor } from '../doctor/doctor.js';
+import { graphTaskMarkdown, harnessTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { inspectTaskGraph } from './task-graph.js';
+
+test('task graph planner builds dependency and file overlap graph', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-valid-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('G1', [], ['src/a.ts'], [])}\n${graphTaskMarkdown('G2', ['G1'], ['./src/a.ts', 'src/b.ts'], ['security'])}`);
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+
+    assert.equal(graph.version, 'phase-3.9-task-graph-planner-v1');
+    assert.equal(graph.valid, true);
+    assert.equal(graph.nodes.length, 2);
+    assert.deepEqual(graph.dependencyEdges, [{ from: 'G1', to: 'G2', type: 'depends_on', files: [] }]);
+    assert.deepEqual(graph.fileOverlapEdges, [{ from: 'G1', to: 'G2', type: 'file_overlap', files: ['src/a.ts'] }]);
+    assert.deepEqual(graph.summary.highRiskTasks, ['G2']);
+    assert.deepEqual(graph.summary.validationCommands, ['npm test']);
+    assert.deepEqual(graph.summary.riskNotes, ['G2:high:security']);
+    assert.equal(graph.contract, 'phase-5.3-task-graph-v1');
+    assert.deepEqual(graph.nodes[1].agentFit, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('task graph parses Phase 5.3 harness metadata fields', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase53-task-graph-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${harnessTaskMarkdown('H1')}`);
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+    const node = graph.nodes[0];
+
+    assert.equal(graph.contract, 'phase-5.3-task-graph-v1');
+    assert.deepEqual(node.fileOwnership, ['packages/core/src/index.ts']);
+    assert.deepEqual(node.agentFit, ['implementer', 'validator']);
+    assert.deepEqual(node.verificationAvailability, ['unit-test', 'cli-smoke']);
+    assert.equal(node.autonomy, 'foreground_write');
+    assert.deepEqual(node.allowedAgents, ['implementer', 'validator']);
+    assert.deepEqual(node.requiredArtifacts, ['artifacts/implementer-H1.md', 'artifacts/validation-H1.md']);
+    assert.equal(node.gapState, 'none');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('task graph planner blocks missing dependency and cycle diagnostics', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-blocked-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('C1', ['C2'], ['src/c1.ts'], [])}\n${graphTaskMarkdown('C2', ['C1'], ['src/c2.ts'], [])}\n${graphTaskMarkdown('M1', ['M404'], ['src/m1.ts'], [])}`);
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+
+    assert.equal(graph.valid, false);
+    assert.equal(graph.diagnostics.some((diagnostic) => /unknown task M404/.test(diagnostic.message)), true);
+    assert.equal(graph.diagnostics.some((diagnostic) => /Task dependency cycle detected: C1 -> C2 -> C1|Task dependency cycle detected: C2 -> C1 -> C2/.test(diagnostic.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports task graph planner contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'task_graph_planner_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.9-task-graph-planner-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/planning/task-graph.ts

@@ -0,0 +1,222 @@
+import { TASK_GRAPH_CONTRACT_VERSION, TASK_GRAPH_PLANNER_CONTRACT_VERSION } from '../contracts.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import type { SddGapSeverity, SddTask, SddTaskSourceLocation, SddTaskStatus } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile, type TaskRiskProfile } from '../task-risk-profile.js';
+
+export type TaskGraphEdgeType = 'depends_on' | 'file_overlap';
+
+export interface TaskGraphNode {
+  taskId: string;
+  title: string | null;
+  status: SddTaskStatus;
+  wave: number | null;
+  dependsOn: string[];
+  affectedFiles: string[];
+  risk: string[];
+  validation: string[];
+  acceptanceRefs: string[];
+  planRefs: string[];
+  fileOwnership: string[];
+  agentFit: string[];
+  verificationAvailability: string[];
+  autonomy: string | null;
+  allowedAgents: string[];
+  requiredArtifacts: string[];
+  gapState: string | null;
+  source: SddTaskSourceLocation;
+}
+
+export interface TaskGraphEdge {
+  from: string;
+  to: string;
+  type: TaskGraphEdgeType;
+  files: string[];
+}
+
+export interface TaskGraphDiagnostic {
+  severity: SddGapSeverity;
+  taskId: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface TaskGraphPlan {
+  contract: typeof TASK_GRAPH_CONTRACT_VERSION;
+  version: typeof TASK_GRAPH_PLANNER_CONTRACT_VERSION;
+  branch: string;
+  valid: boolean;
+  nodes: TaskGraphNode[];
+  dependencyEdges: TaskGraphEdge[];
+  fileOverlapEdges: TaskGraphEdge[];
+  diagnostics: TaskGraphDiagnostic[];
+  summary: {
+    tasks: number;
+    dependencies: number;
+    fileOverlaps: number;
+    highRiskTasks: string[];
+    validationCommands: string[];
+    riskNotes: string[];
+  };
+}
+
+export async function inspectTaskGraph(projectRoot: string, options: { branch?: string } = {}): Promise<TaskGraphPlan> {
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const model = await parseSddBranch(projectRoot, branch);
+  const nodes = model.tasks.map((task): TaskGraphNode => ({
+    taskId: task.id,
+    title: task.title,
+    status: task.status,
+    wave: task.wave,
+    dependsOn: task.dependsOn,
+    affectedFiles: task.affectedFiles,
+    risk: task.risk,
+    validation: task.validation,
+    acceptanceRefs: task.acceptanceRefs,
+    planRefs: task.planRefs,
+    fileOwnership: task.fileOwnership,
+    agentFit: task.agentFit,
+    verificationAvailability: task.verificationAvailability,
+    autonomy: task.autonomy,
+    allowedAgents: task.allowedAgents,
+    requiredArtifacts: task.requiredArtifacts,
+    gapState: task.gapState,
+    source: task.source
+  }));
+  const diagnostics: TaskGraphDiagnostic[] = model.gaps.map((gap) => ({
+    severity: gap.severity,
+    taskId: gap.taskId,
+    field: gap.field,
+    message: gap.message,
+    recommendation: gap.recommendation
+  }));
+  diagnostics.push(...detectTaskGraphCycles(model.tasks));
+  const taskCounts = new Map<string, number>();
+  for (const task of model.tasks) {
+    taskCounts.set(task.id, (taskCounts.get(task.id) ?? 0) + 1);
+  }
+  const dependencyEdges = model.tasks.flatMap((task): TaskGraphEdge[] => task.dependsOn
+    .filter((dependency) => taskCounts.get(dependency) === 1)
+    .map((dependency) => ({ from: dependency, to: task.id, type: 'depends_on', files: [] })));
+  const fileOverlapEdges: TaskGraphEdge[] = [];
+  for (let leftIndex = 0; leftIndex < model.tasks.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < model.tasks.length; rightIndex += 1) {
+      const left = model.tasks[leftIndex];
+      const right = model.tasks[rightIndex];
+      const files = overlappingFiles(left.affectedFiles, right.affectedFiles);
+      if (files.length > 0) {
+        fileOverlapEdges.push({ from: left.id, to: right.id, type: 'file_overlap', files });
+      }
+    }
+  }
+  const validationCommands = [...new Set(model.tasks.flatMap((task) => task.validation))].sort();
+  const taskRiskProfiles = model.tasks.map((task) => ({ task, profile: buildTaskRiskProfile(task) }));
+  const highRiskTasks = taskRiskProfiles
+    .filter(({ profile }) => profile.riskLevel === 'high')
+    .map(({ task }) => task.id)
+    .sort();
+  const riskNotes = taskRiskProfiles
+    .map(({ task, profile }) => buildTaskRiskNote(task, profile))
+    .filter((note): note is string => Boolean(note))
+    .sort();
+
+  return {
+    contract: TASK_GRAPH_CONTRACT_VERSION,
+    version: TASK_GRAPH_PLANNER_CONTRACT_VERSION,
+    branch,
+    valid: diagnostics.every((diagnostic) => diagnostic.severity !== 'blocking'),
+    nodes,
+    dependencyEdges,
+    fileOverlapEdges,
+    diagnostics,
+    summary: {
+      tasks: nodes.length,
+      dependencies: dependencyEdges.length,
+      fileOverlaps: fileOverlapEdges.length,
+      highRiskTasks,
+      validationCommands,
+      riskNotes,
+    }
+  };
+}
+
+function buildTaskRiskNote(task: SddTask, profile: TaskRiskProfile): string | null {
+  const signals = [
+    profile.sourceBoundary ? 'source-boundary' : null,
+    profile.runtimeStateBoundary ? 'runtime-state' : null,
+    profile.contextRisk ? 'context' : null,
+    profile.tokenRisk ? 'token' : null,
+    profile.performanceRisk ? 'performance' : null,
+    profile.externalUnknown ? 'external-unknown' : null,
+    profile.securitySensitive ? 'security' : null
+  ].filter((signal): signal is string => Boolean(signal));
+  if (profile.riskLevel === 'low' && signals.length === 0) {
+    return null;
+  }
+  return `${task.id}:${profile.riskLevel}:${signals.length > 0 ? signals.join(',') : profile.normalizedTags.join(',') || 'risk-profile'}`;
+}
+
+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(/^\.\//, '');
+}
+
+function detectTaskGraphCycles(tasks: SddTask[]): TaskGraphDiagnostic[] {
+  const uniqueTaskIds = new Set<string>();
+  const duplicateTaskIds = new Set<string>();
+  for (const task of tasks) {
+    if (uniqueTaskIds.has(task.id)) {
+      duplicateTaskIds.add(task.id);
+    }
+    uniqueTaskIds.add(task.id);
+  }
+  const graph = new Map<string, string[]>();
+  for (const task of tasks.filter((candidate) => !duplicateTaskIds.has(candidate.id))) {
+    graph.set(task.id, task.dependsOn.filter((dependency) => uniqueTaskIds.has(dependency) && !duplicateTaskIds.has(dependency)));
+  }
+  const diagnostics: TaskGraphDiagnostic[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const stack: string[] = [];
+  const reportedCycles = new Set<string>();
+
+  const visit = (taskId: string): void => {
+    if (visiting.has(taskId)) {
+      const cycleStart = stack.indexOf(taskId);
+      const cycle = [...stack.slice(cycleStart), taskId];
+      const key = cycle.join('->');
+      if (!reportedCycles.has(key)) {
+        reportedCycles.add(key);
+        diagnostics.push({
+          severity: 'blocking',
+          taskId,
+          field: 'depends_on',
+          message: `Task dependency cycle detected: ${cycle.join(' -> ')}.`,
+          recommendation: 'Break the cycle before graph planning or wave planning.'
+        });
+      }
+      return;
+    }
+    if (visited.has(taskId)) {
+      return;
+    }
+    visiting.add(taskId);
+    stack.push(taskId);
+    for (const dependency of graph.get(taskId) ?? []) {
+      visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(taskId);
+    visited.add(taskId);
+  };
+
+  for (const taskId of graph.keys()) {
+    visit(taskId);
+  }
+  return diagnostics;
+}

package/node_modules/@sdd-agent-platform/core/src/planning/wave-plan.test.ts

@@ -0,0 +1,76 @@
+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 { doctor } from '../doctor/doctor.js';
+import { graphTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { inspectWavePlan } from './wave-plan.js';
+
+test('wave planner builds dependency waves and separates file overlaps', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-valid-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('W1', [], ['src/a.ts'], [])}\n${graphTaskMarkdown('W2', [], ['./src/a.ts'], [])}\n${graphTaskMarkdown('W3', ['W1'], ['src/c.ts'], [])}`);
+
+    const plan = await inspectWavePlan(root, { branch: 'master', capabilityId: 'native-file-edit' });
+
+    assert.equal(plan.version, 'phase-3.10-wave-planner-v1');
+    assert.equal(plan.valid, true);
+    assert.deepEqual(plan.waves.map((wave) => wave.tasks.map((task) => task.taskId)), [['W1'], ['W2', 'W3']]);
+    assert.equal(plan.manualGates.length, 0);
+    assert.equal(plan.blockedTasks.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('wave planner routes manual gates and downstream blocked tasks', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-manual-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('DB1', [], ['db/schema.sql'], ['database'])}\n${graphTaskMarkdown('APP1', ['DB1'], ['src/app.ts'], [])}`);
+
+    const plan = await inspectWavePlan(root, { branch: 'master', capabilityId: 'native-file-edit' });
+
+    assert.equal(plan.valid, false);
+    assert.deepEqual(plan.manualGates.map((gate) => gate.taskId), ['DB1']);
+    assert.deepEqual(plan.blockedTasks.map((gate) => gate.taskId), ['APP1']);
+    assert.match(plan.blockedTasks[0]?.reasons.join(' ') ?? '', /depends on non-plannable task\(s\): DB1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('wave planner blocks graph diagnostics', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-blocked-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('M1', ['M404'], ['src/m1.ts'], [])}`);
+
+    const plan = await inspectWavePlan(root, { branch: 'master', capabilityId: 'native-file-edit' });
+
+    assert.equal(plan.valid, false);
+    assert.deepEqual(plan.blockedTasks.map((gate) => gate.taskId), ['M1']);
+    assert.equal(plan.diagnostics.some((diagnostic) => /unknown task M404/.test(diagnostic.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports wave planner contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'wave_planner_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.10-wave-planner-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});