sdd-agent-platform 0.4.2 → 0.5.1

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

@@ -1,88 +1,88 @@
-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 { writeVerifyContract } from '../verification/verify-contract.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'])}`);
-    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
-
-    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 });
-  }
-});
+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 { writeVerifyContract } from '../verification/verify-contract.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'])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    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

@@ -1,222 +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;
-}
+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;
+}