@ronkovic/aad 0.3.0

package/src/modules/planning/file-conflict-validator.ts

@@ -0,0 +1,135 @@
+// File Conflict Validator - port from .aad/scripts/verify-file-conflicts.sh
+// Validates that tasks modifying the same file have proper dependency relationships
+
+import type { Task, TaskId } from "../../shared/types";
+
+export interface FileConflict {
+  filePath: string;
+  ownerTask: TaskId;
+  conflictingTask: TaskId;
+  hasDependency: boolean;
+}
+
+export interface FileConflictResult {
+  valid: boolean;
+  conflicts: FileConflict[];
+}
+
+/**
+ * Check if targetTask is a transitive dependency of taskId
+ * (i.e., taskId depends on targetTask directly or indirectly)
+ */
+function checkTransitiveDependency(
+  taskId: TaskId,
+  targetTask: TaskId,
+  tasks: Task[],
+  visited: Set<TaskId> = new Set()
+): boolean {
+  // Prevent circular reference
+  if (visited.has(taskId)) {
+    return false;
+  }
+
+  const task = tasks.find((t) => t.taskId === taskId);
+  if (!task) {
+    return false;
+  }
+
+  visited.add(taskId);
+
+  // Check direct dependencies
+  for (const dep of task.dependsOn) {
+    if (dep === targetTask) {
+      return true;
+    }
+
+    // Recursively check transitive dependencies
+    if (checkTransitiveDependency(dep, targetTask, tasks, visited)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validates file conflicts in task plan
+ * Port from .aad/scripts/verify-file-conflicts.sh
+ *
+ * Rules:
+ * - If multiple tasks modify the same file, the later task MUST depend on the earlier task
+ * - Dependencies can be direct or transitive
+ * - Tasks are processed in priority order (lower priority number = higher priority)
+ */
+export function validateFileConflicts(tasks: Task[]): FileConflictResult {
+  const conflicts: FileConflict[] = [];
+  const fileOwners = new Map<string, TaskId>();
+
+  // Sort by priority (ascending: lower number = higher priority)
+  const sortedTasks = [...tasks].sort((a, b) => a.priority - b.priority);
+
+  for (const task of sortedTasks) {
+    // Skip tasks with no files to modify
+    if (!task.filesToModify || task.filesToModify.length === 0) {
+      continue;
+    }
+
+    for (const filePath of task.filesToModify) {
+      // Skip empty file paths
+      if (!filePath || filePath.trim() === "") {
+        continue;
+      }
+
+      const ownerTask = fileOwners.get(filePath);
+
+      if (ownerTask) {
+        // File conflict detected
+        // Check if current task depends on the owner task (direct or transitive)
+        const hasDependency = checkTransitiveDependency(
+          task.taskId,
+          ownerTask,
+          tasks
+        );
+
+        if (!hasDependency) {
+          // Invalid: task modifies a file but doesn't depend on the owner
+          conflicts.push({
+            filePath,
+            ownerTask,
+            conflictingTask: task.taskId,
+            hasDependency: false,
+          });
+        }
+        // If hasDependency is true, the conflict is valid (tasks are properly ordered)
+      } else {
+        // This task is the first to claim this file
+        fileOwners.set(filePath, task.taskId);
+      }
+    }
+  }
+
+  return {
+    valid: conflicts.length === 0,
+    conflicts,
+  };
+}
+
+/**
+ * Format file conflict result as human-readable error messages
+ */
+export function formatConflictErrors(result: FileConflictResult): string[] {
+  if (result.valid) {
+    return [];
+  }
+
+  return result.conflicts.map((conflict) => {
+    return [
+      `⚠️  File conflict detected:`,
+      `    File: ${conflict.filePath}`,
+      `    Owner: ${conflict.ownerTask}`,
+      `    Conflicting task: ${conflict.conflictingTask}`,
+      `    ❌ ERROR: Task ${conflict.conflictingTask} should depend on ${conflict.ownerTask} but doesn't`,
+      `    Please update task_plan.json to add this dependency`,
+    ].join("\n");
+  });
+}

package/src/modules/planning/index.ts

@@ -0,0 +1,40 @@
+// Planning Module - Barrel Export
+// Provides task planning capabilities: project detection, file conflict validation, and task plan generation
+
+export {
+  detectProjectType,
+  detectPackageManager,
+  detectFramework,
+  detectTestFramework,
+  detectOrm,
+  detectArchitecturePattern,
+  isMonorepo,
+  detectWorkspaces,
+  analyzeProject,
+  createBunFileChecker,
+} from "./project-detection";
+
+export type {
+  ProjectType,
+  PackageManager,
+  TestFramework,
+  Framework,
+  OrmType,
+  ArchitecturePattern,
+  WorkspaceInfo,
+  ProjectAnalysis,
+  FileChecker,
+} from "./project-detection";
+
+export {
+  validateFileConflicts,
+  formatConflictErrors,
+} from "./file-conflict-validator";
+
+export type {
+  FileConflict,
+  FileConflictResult,
+} from "./file-conflict-validator";
+
+export { PlanningService } from "./planning.service";
+export type { PlanTasksParams } from "./planning.service";

package/src/modules/planning/planning.service.ts

@@ -0,0 +1,262 @@
+// Planning Service - orchestrates task planning workflow
+// Port from .aad/scripts/run-parallel.sh run_splitter()
+
+import type { ClaudeProvider, SubagentConfig } from "../claude-provider";
+import type { EventBus } from "../../shared/events";
+import type { Config } from "../../shared/config";
+import type { RunId, TaskPlan } from "../../shared/types";
+import type pino from "pino";
+import { PlanningError } from "../../shared/errors";
+import { parseTaskPlan, validateTaskPlan } from "../task-queue";
+import { validateFileConflicts, formatConflictErrors } from "./file-conflict-validator";
+import { analyzeProject, createBunFileChecker, type FileChecker } from "./project-detection";
+
+export interface PlanTasksParams {
+  runId: RunId;
+  parentBranch: string;
+  requirementsPath: string;
+  targetDocsDir: string;
+  projectRoot?: string;
+}
+
+export class PlanningService {
+  private fileChecker: FileChecker;
+
+  constructor(
+    private claudeProvider: ClaudeProvider,
+    private eventBus: EventBus,
+    private config: Config,
+    private logger: pino.Logger,
+    options?: { fileChecker?: FileChecker }
+  ) {
+    this.fileChecker = options?.fileChecker ?? createBunFileChecker();
+  }
+
+  /**
+   * Plan tasks from requirements
+   * Orchestrates: project analysis → Claude splitter → file conflict validation
+   */
+  async planTasks(params: PlanTasksParams): Promise<TaskPlan> {
+    const { runId, parentBranch, requirementsPath, targetDocsDir, projectRoot = process.cwd() } = params;
+
+    this.logger.info({ runId, requirementsPath }, "Planning tasks started");
+    this.eventBus.emit({
+      type: "planning:started",
+      requirementsPath,
+    });
+
+    try {
+      // 1. Project analysis (optional context for splitter)
+      const projectAnalysis = await analyzeProject(projectRoot, this.fileChecker);
+      this.logger.debug({ projectAnalysis }, "Project analysis completed");
+
+      // 2. Build splitter prompt
+      const prompt = this.buildSplitterPrompt({
+        runId,
+        parentBranch,
+        requirementsPath,
+        targetDocsDir,
+        projectAnalysis,
+      });
+
+      // 3. Call Claude splitter
+      this.logger.info("Calling Claude splitter agent");
+      const subagents = this.config.teams.splitter ? this.buildSplitterSubagents() : undefined;
+      const response = await this.claudeProvider.call({
+        prompt,
+        ...(subagents ? { subagents } : {}),
+      });
+
+      if (response.exitCode !== 0) {
+        throw new PlanningError(`Claude splitter failed with exit code ${response.exitCode}`, {
+          runId,
+          exitCode: response.exitCode,
+          output: response.result,
+        });
+      }
+
+      // 4. Parse task plan from Claude output
+      const taskPlanJsonStr = this.extractTaskPlanFromOutput(response.result);
+      const taskPlanJson = JSON.parse(taskPlanJsonStr);
+      const taskPlan = parseTaskPlan(taskPlanJson);
+
+      this.logger.debug({ taskCount: taskPlan.tasks.length }, "Task plan parsed");
+
+      // 5. Validate task plan structure (circular dependencies)
+      try {
+        validateTaskPlan(taskPlan.tasks);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new PlanningError(`Invalid task plan: ${errorMessage}`, {
+          runId,
+          error: errorMessage,
+        });
+      }
+
+      // 6. Validate file conflicts
+      const conflictResult = validateFileConflicts(taskPlan.tasks);
+      if (!conflictResult.valid) {
+        const errorMessages = formatConflictErrors(conflictResult);
+        throw new PlanningError(`File conflicts detected:\n${errorMessages.join("\n\n")}`, {
+          runId,
+          conflicts: conflictResult.conflicts,
+        });
+      }
+
+      this.logger.info({ taskCount: taskPlan.tasks.length }, "Planning completed successfully");
+      this.eventBus.emit({
+        type: "planning:completed",
+        taskCount: taskPlan.tasks.length,
+      });
+
+      return taskPlan;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error({ error, runId }, "Planning failed");
+      this.eventBus.emit({
+        type: "planning:failed",
+        error: errorMessage,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Build splitter prompt (teams mode or solo mode)
+   */
+  private buildSplitterPrompt(params: {
+    runId: RunId;
+    parentBranch: string;
+    requirementsPath: string;
+    targetDocsDir: string;
+    projectAnalysis: unknown;
+  }): string {
+    const { runId, parentBranch, requirementsPath } = params;
+
+    const taskPlanFormat = JSON.stringify(
+      {
+        run_id: runId,
+        parent_branch: parentBranch,
+        tasks: [
+          {
+            task_id: "task-001",
+            title: "タスクのタイトル",
+            description: "詳細な説明",
+            files_to_modify: ["file1.js", "file2.js"],
+            depends_on: ["task-000"],
+            priority: 1,
+          },
+        ],
+      },
+      null,
+      2
+    );
+
+    if (this.config.teams.splitter) {
+      // Teams mode: subagents handle analysis, main agent integrates
+      return `splitterエージェントとして、サブエージェントの分析結果を統合し、要件をタスクに分割してください。
+
+サブエージェント（codebase-analyzer, requirement-analyzer, dependency-mapper）が自動的に並列分析を行います。
+それぞれの結果を統合して、最終的なタスクプランを作成してください。
+
+要件: ${requirementsPath}
+Run ID: ${runId}
+親ブランチ: ${parentBranch}
+
+以下の手順を実行してください:
+1. サブエージェントの分析結果を統合する
+2. タスクに分割し、以下のJSON形式で標準出力に出力してください（ファイル生成ではなく、コンソールに直接出力）:
+   ${taskPlanFormat}
+3. 各タスクの files_to_modify を明確にする
+4. 依存関係 (depends_on) を設定する
+   ⚠️  重要: 同じファイルを変更する複数のタスクがある場合、必ず後のタスクを前のタスクに依存させてください
+   これにより、ファイル衝突を防ぎます
+5. priority を設定する
+
+⚠️  重要: 最終的な出力は、上記のJSON形式のみを標準出力に出力してください。説明文やコードブロック記法（\`\`\`）は不要です。`;
+    } else {
+      // Solo mode: traditional prompt
+      return `splitterエージェントとして、以下の要件を分割してください:
+
+要件: ${requirementsPath}
+Run ID: ${runId}
+親ブランチ: ${parentBranch}
+
+以下の手順を実行してください:
+1. 要件ファイル/ディレクトリを読み込む（ディレクトリの場合は配下のファイルを全て読む）
+2. タスクに分割し、以下のJSON形式で標準出力に出力してください（ファイル生成ではなく、コンソールに直接出力）:
+   ${taskPlanFormat}
+3. 各タスクの files_to_modify を明確にする
+4. 依存関係 (depends_on) を設定する
+   ⚠️  重要: 同じファイルを変更する複数のタスクがある場合、必ず後のタスクを前のタスクに依存させてください
+   これにより、ファイル衝突を防ぎます
+5. priority を設定する
+
+⚠️  重要: 最終的な出力は、上記のJSON形式のみを標準出力に出力してください。説明文やコードブロック記法（\`\`\`）は不要です。`;
+    }
+  }
+
+  /**
+   * Build subagent configs for splitter teams mode
+   */
+  private buildSplitterSubagents(): SubagentConfig[] {
+    return [
+      {
+        name: "codebase-analyzer",
+        prompt: `コードベース分析の専門家として、プロジェクトのディレクトリ構造、既存コード、技術スタックを分析してください。
+以下の観点で報告してください:
+- プロジェクト構造とモジュール構成
+- 使用されている技術スタック（言語、フレームワーク、ライブラリ）
+- コーディング規約やパターン
+- 既存のテスト構成`,
+      },
+      {
+        name: "requirement-analyzer",
+        prompt: `要件分析の専門家として、要件ドキュメントを分析してください。
+以下の観点で報告してください:
+- ユーザーストーリーの抽出
+- 受入基準の特定
+- 機能要件と非機能要件の分類
+- 実装の優先度提案`,
+      },
+      {
+        name: "dependency-mapper",
+        prompt: `依存関係分析の専門家として、モジュール間の依存関係を分析してください。
+以下の観点で報告してください:
+- モジュール間の依存グラフ
+- 並列実行可能なタスクの特定
+- ファイル変更の競合リスク
+- 推奨される実装順序`,
+      },
+    ];
+  }
+
+  /**
+   * Extract task_plan.json from Claude output
+   * Claude may return the JSON directly or wrapped in markdown code block
+   */
+  private extractTaskPlanFromOutput(output: string): string {
+    // Try to parse directly
+    try {
+      JSON.parse(output);
+      return output;
+    } catch {
+      // Not valid JSON, try to extract from markdown code block
+    }
+
+    // Try to extract from ```json ... ``` block
+    const jsonBlockMatch = output.match(/```json\s*([\s\S]*?)\s*```/);
+    if (jsonBlockMatch?.[1]) {
+      return jsonBlockMatch[1];
+    }
+
+    // Try to extract from ``` ... ``` block
+    const codeBlockMatch = output.match(/```\s*([\s\S]*?)\s*```/);
+    if (codeBlockMatch?.[1]) {
+      return codeBlockMatch[1];
+    }
+
+    // Return as-is and let parseTaskPlan handle validation
+    return output;
+  }
+}