sdd-agent-platform 0.3.0 → 0.4.1

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

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

@@ -0,0 +1,160 @@
+import { WAVE_PLANNER_CONTRACT_VERSION } from '../contracts.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { inspectTaskGraph } from './task-graph.js';
+import type { TaskGraphDiagnostic, TaskGraphNode, TaskGraphPlan } from './task-graph.js';
+import { inspectWorktreeIsolation } from '../worktree/isolation.js';
+import type { WorktreeIsolationDecision, WorktreeIsolationMode } from '../worktree/isolation.js';
+
+export interface WavePlanTask {
+  taskId: string;
+  isolationMode: WorktreeIsolationMode;
+  reasons: string[];
+}
+
+export interface WavePlanWave {
+  index: number;
+  tasks: WavePlanTask[];
+}
+
+export interface WavePlanGate {
+  taskId: string;
+  gate: 'manual' | 'blocked';
+  reasons: string[];
+}
+
+export interface WavePlan {
+  version: typeof WAVE_PLANNER_CONTRACT_VERSION;
+  branch: string;
+  valid: boolean;
+  waves: WavePlanWave[];
+  manualGates: WavePlanGate[];
+  blockedTasks: WavePlanGate[];
+  diagnostics: TaskGraphDiagnostic[];
+  summary: {
+    tasks: number;
+    waves: number;
+    plannedTasks: number;
+    manualTasks: number;
+    blockedTasks: number;
+  };
+}
+
+export async function inspectWavePlan(projectRoot: string, options: { branch?: string; capabilityId?: string } = {}): Promise<WavePlan> {
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const capabilityId = options.capabilityId ?? 'native-file-edit';
+  const graph = await inspectTaskGraph(projectRoot, { branch });
+  const taskIds = new Set(graph.nodes.map((node) => node.taskId));
+  const blockingDiagnostics = graph.diagnostics.filter((diagnostic) => diagnostic.severity === 'blocking');
+  const globalBlocking = blockingDiagnostics.filter((diagnostic) => diagnostic.taskId === null);
+  const blockingByTask = new Map<string, string[]>();
+  for (const diagnostic of blockingDiagnostics.filter((candidate) => candidate.taskId !== null)) {
+    const reasons = blockingByTask.get(diagnostic.taskId ?? '') ?? [];
+    reasons.push(diagnostic.message);
+    blockingByTask.set(diagnostic.taskId ?? '', reasons);
+  }
+
+  const decisions = new Map<string, WorktreeIsolationDecision>();
+  await Promise.all(graph.nodes.map(async (node) => {
+    decisions.set(node.taskId, await inspectWorktreeIsolation(projectRoot, { branch, taskId: node.taskId, capabilityId }));
+  }));
+
+  const manualGates: WavePlanGate[] = [];
+  const blockedTasks: WavePlanGate[] = [];
+  const blockedTaskIds = new Set<string>();
+  const manualTaskIds = new Set<string>();
+  const candidates = new Map<string, TaskGraphNode>();
+
+  for (const node of graph.nodes) {
+    const decision = decisions.get(node.taskId);
+    const diagnosticReasons = blockingByTask.get(node.taskId) ?? [];
+    if (globalBlocking.length > 0) {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: globalBlocking.map((diagnostic) => diagnostic.message) });
+      blockedTaskIds.add(node.taskId);
+    } else if (diagnosticReasons.length > 0) {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: diagnosticReasons });
+      blockedTaskIds.add(node.taskId);
+    } else if (!decision || decision.mode === 'blocked') {
+      blockedTasks.push({ taskId: node.taskId, gate: 'blocked', reasons: decision?.reasons ?? [`Task ${node.taskId} cannot be inspected for isolation.`] });
+      blockedTaskIds.add(node.taskId);
+    } else if (decision.mode === 'manual') {
+      manualGates.push({ taskId: node.taskId, gate: 'manual', reasons: decision.reasons });
+      manualTaskIds.add(node.taskId);
+    } else {
+      candidates.set(node.taskId, node);
+    }
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [taskId, node] of [...candidates]) {
+      const blockedDependencies = node.dependsOn.filter((dependency) => !taskIds.has(dependency) || blockedTaskIds.has(dependency) || manualTaskIds.has(dependency));
+      if (blockedDependencies.length > 0) {
+        blockedTasks.push({
+          taskId,
+          gate: 'blocked',
+          reasons: [`Task ${taskId} depends on non-plannable task(s): ${blockedDependencies.join(', ')}.`]
+        });
+        blockedTaskIds.add(taskId);
+        candidates.delete(taskId);
+        changed = true;
+      }
+    }
+  }
+
+  const waves: WavePlanWave[] = [];
+  const completed = new Set<string>();
+  const remaining = new Map(candidates);
+  while (remaining.size > 0) {
+    const ready = [...remaining.values()]
+      .filter((node) => node.dependsOn.every((dependency) => completed.has(dependency)))
+      .sort((left, right) => left.taskId.localeCompare(right.taskId));
+    if (ready.length === 0) {
+      for (const taskId of remaining.keys()) {
+        blockedTasks.push({ taskId, gate: 'blocked', reasons: [`Task ${taskId} cannot be placed in a dependency wave.`] });
+        blockedTaskIds.add(taskId);
+      }
+      break;
+    }
+    const waveNodes: TaskGraphNode[] = [];
+    for (const node of ready) {
+      if (!waveNodes.some((candidate) => graphTasksOverlap(graph, candidate.taskId, node.taskId))) {
+        waveNodes.push(node);
+      }
+    }
+    const tasks = waveNodes.map((node): WavePlanTask => ({
+      taskId: node.taskId,
+      isolationMode: decisions.get(node.taskId)?.mode ?? 'blocked',
+      reasons: decisions.get(node.taskId)?.reasons ?? []
+    }));
+    waves.push({ index: waves.length + 1, tasks });
+    for (const node of waveNodes) {
+      remaining.delete(node.taskId);
+      completed.add(node.taskId);
+    }
+  }
+
+  const plannedTasks = waves.reduce((count, wave) => count + wave.tasks.length, 0);
+  return {
+    version: WAVE_PLANNER_CONTRACT_VERSION,
+    branch,
+    valid: graph.valid && blockedTasks.length === 0,
+    waves,
+    manualGates,
+    blockedTasks,
+    diagnostics: graph.diagnostics,
+    summary: {
+      tasks: graph.nodes.length,
+      waves: waves.length,
+      plannedTasks,
+      manualTasks: manualGates.length,
+      blockedTasks: blockedTasks.length
+    }
+  };
+}
+
+function graphTasksOverlap(graph: TaskGraphPlan, leftTaskId: string, rightTaskId: string): boolean {
+  return graph.fileOverlapEdges.some((edge) =>
+    (edge.from === leftTaskId && edge.to === rightTaskId) || (edge.from === rightTaskId && edge.to === leftTaskId)
+  );
+}

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

@@ -0,0 +1,2 @@
+export * from './planning/task-graph.js';
+export * from './planning/wave-plan.js';