@litmers/cursorflow-orchestrator 0.1.30 → 0.1.34

package/src/core/runner/prompt.ts

@@ -0,0 +1,174 @@
+import * as fs from 'fs';
+import * as logger from '../../utils/logger';
+import { safeJoin } from '../../utils/path';
+import { DependencyPolicy, RunnerConfig } from '../../types';
+import { DependencyResult } from './utils';
+
+/**
+ * Dependency request file name - agent writes here when dependency changes are needed
+ */
+export const DEPENDENCY_REQUEST_FILE = '_cursorflow/dependency-request.json';
+
+/**
+ * Wrap prompt with dependency policy instructions (legacy, used by tests)
+ */
+export function wrapPromptForDependencyPolicy(prompt: string, policy: DependencyPolicy): string {
+  if (policy.allowDependencyChange && !policy.lockfileReadOnly) {
+    return prompt;
+  }
+  
+  let wrapped = `### 📦 Dependency Policy\n`;
+  wrapped += `- allowDependencyChange: ${policy.allowDependencyChange}\n`;
+  wrapped += `- lockfileReadOnly: ${policy.lockfileReadOnly}\n\n`;
+  wrapped += prompt;
+  
+  return wrapped;
+}
+
+/**
+ * Wrap prompt with global context, dependency policy, and worktree instructions
+ */
+export function wrapPrompt(
+  prompt: string, 
+  config: RunnerConfig, 
+  options: { 
+    noGit?: boolean; 
+    isWorktree?: boolean;
+    dependencyResults?: DependencyResult[];
+    worktreePath?: string;
+    taskBranch?: string;
+    pipelineBranch?: string;
+  } = {}
+): string {
+  const { noGit = false, isWorktree = true, dependencyResults = [], worktreePath, taskBranch, pipelineBranch } = options;
+  
+  // 1. PREFIX: Environment & Worktree context
+  let wrapped = `### 🛠 Environment & Context\n`;
+  wrapped += `- **Workspace**: 당신은 독립된 **Git 워크트리** (프로젝트 루트)에서 작업 중입니다.\n`;
+  wrapped += `- **CWD**: 현재 터미널과 작업 경로는 이미 워크트리 루트(\`${worktreePath || 'current'}\`)로 설정되어 있습니다.\n`;
+  
+  if (taskBranch && !noGit) {
+    wrapped += `- **Current Branch**: \`${taskBranch}\` (현재 작업 중인 브랜치)\n`;
+    wrapped += `- **Branch Check**: 만약 브랜치가 다르다면 \`git checkout ${taskBranch}\`를 실행하세요.\n`;
+  }
+  if (pipelineBranch && !noGit) {
+    wrapped += `- **Base Branch**: \`${pipelineBranch}\` (이 작업의 기준이 되는 상위 브랜치)\n`;
+  }
+
+  if (worktreePath) {
+    wrapped += `- **Worktree Path**: \`${worktreePath}\`\n`;
+    wrapped += `- **CRITICAL**: 터미널 명령어 실행 시 반드시 워크트리 루트 내에서 실행되고 있는지 확인하세요.\n`;
+  }
+  
+  wrapped += `- **Path Rule**: 모든 파일 참조는 워크트리 루트 기준입니다.\n`;
+  
+  if (isWorktree) {
+    wrapped += `- **File Availability**: Git 추적 파일만 존재합니다. (node_modules, .env 등은 기본적으로 없음)\n`;
+    
+    // Add environment file copy instructions
+    if (worktreePath) {
+      // Extract main repo path from worktree path (remove _cursorflow/worktrees/xxx part)
+      const mainRepoPath = worktreePath.replace(/\/_cursorflow\/worktrees\/[^/]+$/, '');
+      wrapped += `\n### 🔐 Environment Files Setup\n`;
+      wrapped += `워크트리에 환경변수 파일이 없다면, 메인 레포에서 복사하세요:\n`;
+      wrapped += `\`\`\`bash\n`;
+      wrapped += `# 메인 레포 경로: ${mainRepoPath}\n`;
+      wrapped += `예시 커맨드: [ ! -f .env ] && [ -f "${mainRepoPath}/.env" ] && cp "${mainRepoPath}/.env" .env\n`;
+      wrapped += `예시 커맨드: [ ! -f .env.local ] && [ -f "${mainRepoPath}/.env.local" ] && cp "${mainRepoPath}/.env.local" .env.local\n`;
+      wrapped += `\`\`\`\n`;
+      wrapped += `⚠️ 이 작업은 **터미널 명령어 실행 전** 반드시 확인하세요!\n`;
+    }
+  }
+
+  // 2. Dependency Task Results (if available)
+  if (dependencyResults.length > 0) {
+    wrapped += `\n### 📋 의존 태스크 결과\n`;
+    wrapped += `이 태스크가 의존하는 이전 태스크들의 작업 결과입니다.\n\n`;
+    
+    for (const dep of dependencyResults) {
+      wrapped += `#### ${dep.taskId}\n`;
+      wrapped += `${dep.resultText}\n\n`;
+    }
+    wrapped += `---\n`;
+  }
+  
+  // 3. Dependency Policy (Integrated)
+  const policy = config.dependencyPolicy;
+  wrapped += `\n### 📦 Dependency Policy\n`;
+  wrapped += `- allowDependencyChange: ${policy.allowDependencyChange}\n`;
+  wrapped += `- lockfileReadOnly: ${policy.lockfileReadOnly}\n`;
+  
+  if (noGit) {
+    wrapped += `- NO_GIT_MODE: Git 명령어를 사용하지 마세요. 파일 수정만 가능합니다.\n`;
+  }
+
+  wrapped += `\n**📦 Dependency Change Rules:**\n`;
+  wrapped += `1. 코드를 수정하기 전, 의존성 변경이 필요한지 **먼저** 판단하세요.\n`;
+  wrapped += `2. 의존성 변경이 필요하다면:\n`;
+  wrapped += `   - **다른 파일을 절대 수정하지 마세요.**\n`;
+  wrapped += `   - 아래 JSON을 \`./${DEPENDENCY_REQUEST_FILE}\` 파일에 저장하세요:\n`;
+  wrapped += `     \`\`\`json\n`;
+  wrapped += `     {\n`;
+  wrapped += `       "reason": "왜 이 의존성이 필요한지 설명",\n`;
+  wrapped += `       "changes": ["add lodash@^4.17.21", "remove unused-pkg"],\n`;
+  wrapped += `       "commands": ["pnpm add lodash@^4.17.21", "pnpm remove unused-pkg"],\n`;
+  wrapped += `       "notes": "추가 참고사항 (선택)"  \n`;
+  wrapped += `     }\n`;
+  wrapped += `     \`\`\`\n`;
+  wrapped += `   - 파일 저장 후 **즉시 작업을 종료**하세요. 오케스트레이터가 처리합니다.\n`;
+  wrapped += `3. 의존성 변경이 불필요하면 바로 본 작업을 진행하세요.\n`;
+
+  wrapped += `\n---\n\n${prompt}\n\n---\n`;
+
+  // 4. SUFFIX: Task Completion & Git Requirements
+  wrapped += `\n### 📝 Task Completion Requirements\n`;
+  wrapped += `**반드시 다음 순서로 작업을 마무리하세요 (매우 중요):**\n\n`;
+  
+  if (!noGit) {
+    wrapped += `1. **변경 사항 확인**: \`git status\`와 \`git diff\`로 수정된 내용을 최종 확인하세요.\n`;
+    wrapped += `2. **Git Commit & Push** (필수!):\n`;
+    wrapped += `   \`\`\`bash\n`;
+    wrapped += `   git add -A\n`;
+    wrapped += `   git commit -m "feat: <작업 내용 요약>"\n`;
+    wrapped += `   git push origin HEAD\n`;
+    wrapped += `   \`\`\`\n`;
+    wrapped += `   ⚠️ **주의**: 커밋과 푸시를 생략하면 오케스트레이터가 변경 사항을 인식하지 못하며 작업이 손실됩니다.\n\n`;
+  }
+  
+  wrapped += `3. **최종 요약**: 작업 완료 후 아래 형식을 포함하여 요약해 주세요:\n`;
+  wrapped += `   - **수정된 파일**: [파일명1, 파일명2, ...]\n`;
+  wrapped += `   - **작업 결과**: [핵심 변경 사항 요약]\n`;
+  wrapped += `   - **커밋 정보**: [git log --oneline -1 결과]\n\n`;
+  wrapped += `4. 지시된 문서(docs/...)를 찾을 수 없거나 예기치 못한 오류가 발생하면 즉시 보고하세요.\n`;
+
+  return wrapped;
+}
+
+/**
+ * Apply file permissions based on dependency policy
+ */
+export function applyDependencyFilePermissions(worktreeDir: string, policy: DependencyPolicy): void {
+  const targets: string[] = [];
+  
+  if (!policy.allowDependencyChange) {
+    targets.push('package.json');
+  }
+  
+  if (policy.lockfileReadOnly) {
+    targets.push('pnpm-lock.yaml', 'package-lock.json', 'yarn.lock');
+  }
+  
+  for (const file of targets) {
+    const filePath = safeJoin(worktreeDir, file);
+    if (!fs.existsSync(filePath)) continue;
+    
+    try {
+      const stats = fs.statSync(filePath);
+      const mode = stats.mode & 0o777;
+      fs.chmodSync(filePath, mode & ~0o222); // Remove write bits
+    } catch {
+      // Best effort
+    }
+  }
+}
+

package/src/core/runner/task.ts

@@ -0,0 +1,320 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as git from '../../utils/git';
+import * as logger from '../../utils/logger';
+import { events } from '../../utils/events';
+import { safeJoin } from '../../utils/path';
+import { appendLog, createConversationEntry } from '../../utils/state';
+import { Task, RunnerConfig, TaskExecutionResult, LaneState } from '../../types';
+import { loadState } from '../../utils/state';
+import { waitForTaskDependencies as waitForDeps, DependencyWaitOptions } from '../../utils/dependency';
+import { 
+  cursorAgentSend, 
+  extractDependencyRequest 
+} from './agent';
+import { 
+  wrapPrompt, 
+  applyDependencyFilePermissions 
+} from './prompt';
+import { 
+  loadDependencyResults, 
+  saveTaskResult, 
+  readDependencyRequestFile, 
+  clearDependencyRequestFile,
+  DependencyResult
+} from './utils';
+
+/**
+ * Wait for task-level dependencies to be completed by other lanes
+ * Now uses the enhanced dependency module with timeout support
+ */
+export async function waitForTaskDependencies(
+  deps: string[], 
+  runDir: string,
+  options: DependencyWaitOptions = {}
+): Promise<void> {
+  if (!deps || deps.length === 0) return;
+
+  const lanesRoot = path.dirname(runDir);
+  
+  const result = await waitForDeps(deps, lanesRoot, {
+    timeoutMs: options.timeoutMs || 30 * 60 * 1000, // 30 minutes default
+    pollIntervalMs: options.pollIntervalMs || 5000,
+    onTimeout: options.onTimeout || 'fail',
+    onProgress: (pending, completed) => {
+      if (completed.length > 0) {
+        logger.info(`Dependencies progress: ${completed.length}/${deps.length} completed`);
+      }
+    },
+  });
+  
+  if (!result.success) {
+    if (result.timedOut) {
+      throw new Error(`Dependency wait timed out after ${Math.round(result.elapsedMs / 1000)}s. Pending: ${result.failedDependencies.join(', ')}`);
+    }
+    throw new Error(`Dependencies failed: ${result.failedDependencies.join(', ')}`);
+  }
+}
+
+/**
+ * Merge branches from dependency lanes with safe merge and conflict pre-check
+ */
+export async function mergeDependencyBranches(deps: string[], runDir: string, worktreeDir: string, pipelineBranch: string): Promise<void> {
+  if (!deps || deps.length === 0) return;
+
+  const lanesRoot = path.dirname(runDir);
+  const lanesToMerge = new Set(deps.map(d => d.split(':')[0]!));
+
+  // Ensure we are on the pipeline branch before merging dependencies
+  logger.info(`🔄 Syncing with ${pipelineBranch} before merging dependencies`);
+  git.runGit(['checkout', pipelineBranch], { cwd: worktreeDir });
+
+  for (const laneName of lanesToMerge) {
+    const depStatePath = safeJoin(lanesRoot, laneName, 'state.json');
+    if (!fs.existsSync(depStatePath)) continue;
+
+    try {
+      const state = loadState<LaneState>(depStatePath);
+      if (!state?.pipelineBranch) continue;
+      
+      logger.info(`Merging branch from ${laneName}: ${state.pipelineBranch}`);
+      
+      // Ensure we have the latest
+      git.runGit(['fetch', 'origin', state.pipelineBranch], { cwd: worktreeDir, silent: true });
+      
+      // Pre-check for conflicts before attempting merge
+      const conflictCheck = git.checkMergeConflict(state.pipelineBranch, { cwd: worktreeDir });
+      
+      if (conflictCheck.willConflict) {
+        logger.warn(`⚠️ Pre-check: Merge conflict detected with ${laneName}`);
+        logger.warn(`   Conflicting files: ${conflictCheck.conflictingFiles.join(', ')}`);
+        
+        // Emit event for potential auto-recovery or notification
+        events.emit('merge.conflict_detected', {
+          laneName,
+          targetBranch: state.pipelineBranch,
+          conflictingFiles: conflictCheck.conflictingFiles,
+          preCheck: true,
+        });
+        
+        throw new Error(`Pre-merge conflict check failed: ${conflictCheck.conflictingFiles.join(', ')}. Consider rebasing or resolving conflicts manually.`);
+      }
+      
+      // Use safe merge with conflict detection
+      const mergeResult = git.safeMerge(state.pipelineBranch, {
+        cwd: worktreeDir,
+        noFf: true,
+        message: `chore: merge task dependency from ${laneName}`,
+        abortOnConflict: true,
+      });
+      
+      if (!mergeResult.success) {
+        if (mergeResult.conflict) {
+          logger.error(`Merge conflict with ${laneName}: ${mergeResult.conflictingFiles.join(', ')}`);
+          throw new Error(`Merge conflict: ${mergeResult.conflictingFiles.join(', ')}`);
+        }
+        throw new Error(mergeResult.error || 'Merge failed');
+      }
+      
+      logger.success(`✓ Merged ${laneName}`);
+    } catch (e) {
+      logger.error(`Failed to merge branch from ${laneName}: ${e}`);
+      throw e;
+    }
+  }
+}
+
+/**
+ * Run a single task
+ */
+export async function runTask({
+  task,
+  config,
+  index,
+  worktreeDir,
+  pipelineBranch,
+  taskBranch,
+  chatId,
+  runDir,
+  runRoot,
+  noGit = false,
+}: {
+  task: Task;
+  config: RunnerConfig;
+  index: number;
+  worktreeDir: string;
+  pipelineBranch: string;
+  taskBranch: string;
+  chatId: string;
+  runDir: string;
+  runRoot?: string;
+  noGit?: boolean;
+}): Promise<TaskExecutionResult> {
+  // Calculate runRoot if not provided (runDir is lanes/{laneName}/, runRoot is parent of lanes/)
+  const calculatedRunRoot = runRoot || path.dirname(path.dirname(runDir));
+  const model = task.model || config.model || 'sonnet-4.5';
+  const timeout = task.timeout || config.timeout;
+  const convoPath = safeJoin(runDir, 'conversation.jsonl');
+  
+  logger.section(`[${index + 1}/${config.tasks.length}] ${task.name}`);
+  logger.info(`Model: ${model}`);
+  if (noGit) {
+    logger.info('🚫 noGit mode: skipping branch operations');
+  } else {
+    logger.info(`Branch: ${taskBranch}`);
+  }
+  
+  events.emit('task.started', {
+    taskName: task.name,
+    taskBranch,
+    index,
+  });
+
+  // Sync pipelineBranch with remote before starting (skip in noGit mode)
+  if (!noGit) {
+    logger.info(`🔄 Syncing ${pipelineBranch} with remote...`);
+    
+    // Fetch latest from remote
+    try {
+      git.runGit(['fetch', 'origin', pipelineBranch], { cwd: worktreeDir, silent: true });
+    } catch {
+      // Branch might not exist on remote yet - that's OK
+      logger.info(`  Branch ${pipelineBranch} not yet on remote, skipping sync`);
+    }
+    
+    // Try to fast-forward if behind
+    const syncResult = git.syncBranchWithRemote(pipelineBranch, { cwd: worktreeDir, createIfMissing: true });
+    if (syncResult.updated) {
+      logger.info(`  ✓ Updated ${pipelineBranch} with ${syncResult.behind || 0} new commits from remote`);
+    } else if (syncResult.error) {
+      logger.warn(`  ⚠️ Could not sync: ${syncResult.error}`);
+    }
+  }
+
+  // Checkout task branch from pipeline branch (skip in noGit mode)
+  if (!noGit) {
+    logger.info(`🌿 Forking task branch: ${taskBranch} from ${pipelineBranch}`);
+    git.runGit(['checkout', '-B', taskBranch, pipelineBranch], { cwd: worktreeDir });
+  }
+  
+  // Apply dependency permissions
+  applyDependencyFilePermissions(worktreeDir, config.dependencyPolicy);
+  
+  // Load dependency results if this task has dependsOn
+  let dependencyResults: DependencyResult[] = [];
+  if (task.dependsOn && task.dependsOn.length > 0) {
+    dependencyResults = loadDependencyResults(task.dependsOn, calculatedRunRoot);
+  }
+
+  // Wrap prompt with context, dependency results, and completion instructions
+  const wrappedPrompt = wrapPrompt(task.prompt, config, { 
+    noGit, 
+    isWorktree: !noGit,
+    dependencyResults,
+    worktreePath: worktreeDir,
+    taskBranch,
+    pipelineBranch,
+  });
+  
+  // Log ONLY the original prompt to keep logs clean
+  appendLog(convoPath, createConversationEntry('user', task.prompt, {
+    task: task.name,
+    model,
+  }));
+  
+  logger.info('Sending prompt to agent...');
+  const startTime = Date.now();
+  events.emit('agent.prompt_sent', {
+    taskName: task.name,
+    model,
+    promptLength: wrappedPrompt.length,
+  });
+
+  const r1 = await cursorAgentSend({
+    workspaceDir: worktreeDir,
+    chatId,
+    prompt: wrappedPrompt,
+    model,
+    signalDir: runDir,
+    timeout,
+    enableIntervention: config.enableIntervention,
+    outputFormat: config.agentOutputFormat,
+    taskName: task.name,
+  });
+  
+  const duration = Date.now() - startTime;
+  events.emit('agent.response_received', {
+    taskName: task.name,
+    ok: r1.ok,
+    duration,
+    responseLength: r1.resultText?.length || 0,
+    error: r1.error,
+  });
+
+  appendLog(convoPath, createConversationEntry('assistant', r1.resultText || r1.error || 'No response', {
+    task: task.name,
+    model,
+  }));
+  
+  if (!r1.ok) {
+    events.emit('task.failed', {
+      taskName: task.name,
+      taskBranch,
+      error: r1.error,
+    });
+    return {
+      taskName: task.name,
+      taskBranch,
+      status: 'ERROR',
+      error: r1.error,
+    };
+  }
+  
+  // Check for dependency request (file-based takes priority, then text-based)
+  const fileDepReq = readDependencyRequestFile(worktreeDir);
+  const textDepReq = extractDependencyRequest(r1.resultText || '');
+  
+  // Determine which request to use (file-based is preferred as it's more structured)
+  const depReq = fileDepReq.required ? fileDepReq : textDepReq;
+  
+  if (depReq.required) {
+    logger.info(`📦 Dependency change requested: ${depReq.plan?.reason || 'No reason provided'}`);
+    
+    if (depReq.plan) {
+      logger.info(`   Commands: ${depReq.plan.commands.join(', ')}`);
+    }
+    
+    if (!config.dependencyPolicy.allowDependencyChange) {
+      // Clear the file so it doesn't persist after resolution
+      clearDependencyRequestFile(worktreeDir);
+      
+      return {
+        taskName: task.name,
+        taskBranch,
+        status: 'BLOCKED_DEPENDENCY',
+        dependencyRequest: depReq.plan || null,
+      };
+    }
+  }
+  
+  // Push task branch (skip in noGit mode)
+  if (!noGit) {
+    git.push(taskBranch, { cwd: worktreeDir, setUpstream: true });
+  }
+  
+  // Save task result for dependency handoff
+  saveTaskResult(runDir, index, task.name, r1.resultText || '');
+  
+  events.emit('task.completed', {
+    taskName: task.name,
+    taskBranch,
+    status: 'FINISHED',
+  });
+
+  return {
+    taskName: task.name,
+    taskBranch,
+    status: 'FINISHED',
+  };
+}
+

package/src/core/runner/utils.ts

@@ -0,0 +1,142 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as logger from '../../utils/logger';
+import { safeJoin } from '../../utils/path';
+import { DependencyRequestPlan } from '../../types';
+import { DEPENDENCY_REQUEST_FILE } from './prompt';
+
+/**
+ * Task result directory name - stores task completion results
+ */
+export const TASK_RESULTS_DIR = 'task-results';
+
+/**
+ * Dependency result interface
+ */
+export interface DependencyResult {
+  taskId: string
+  resultText: string;  // Last response text
+}
+
+/**
+ * Save task result (last response text) to file
+ * Stored in runDir/task-results/{NN}-{taskName}.txt
+ */
+export function saveTaskResult(runDir: string, taskIndex: number, taskName: string, resultText: string): void {
+  const resultsDir = safeJoin(runDir, TASK_RESULTS_DIR);
+  try {
+    fs.mkdirSync(resultsDir, { recursive: true });
+    const paddedIndex = String(taskIndex + 1).padStart(2, '0');
+    const resultPath = safeJoin(resultsDir, `${paddedIndex}-${taskName}.txt`);
+    fs.writeFileSync(resultPath, resultText, 'utf8');
+    logger.info(`📝 Task result saved: ${resultPath}`);
+  } catch (e) {
+    logger.warn(`Failed to save task result: ${e}`);
+  }
+}
+
+/**
+ * Find task result file by task name (handles NN-taskName.txt format)
+ */
+export function findTaskResultFile(resultsDir: string, taskName: string): string | null {
+  if (!fs.existsSync(resultsDir)) {
+    return null;
+  }
+  
+  try {
+    const files = fs.readdirSync(resultsDir);
+    // Match pattern: NN-taskName.txt (e.g., 01-setup.txt, 02-implement.txt)
+    const pattern = new RegExp(`^\\d+-${taskName}\\.txt$`);
+    const matchedFile = files.find(f => pattern.test(f));
+    
+    if (matchedFile) {
+      return safeJoin(resultsDir, matchedFile);
+    }
+  } catch (e) {
+    logger.warn(`Failed to scan task results directory: ${e}`);
+  }
+  
+  return null;
+}
+
+/**
+ * Load dependency results based on dependsOn list
+ * Reads from runRoot/lanes/{laneName}/task-results/{NN}-{taskName}.txt
+ */
+export function loadDependencyResults(dependsOn: string[], runRoot: string): DependencyResult[] {
+  const results: DependencyResult[] = [];
+  
+  for (const dep of dependsOn) {
+    const parts = dep.split(':');
+    if (parts.length !== 2) {
+      logger.warn(`Invalid dependency format: ${dep} (expected "lane:task")`);
+      results.push({ taskId: dep, resultText: '(잘못된 의존성 형식)' });
+      continue;
+    }
+    
+    const [laneName, taskName] = parts;
+    const resultsDir = safeJoin(runRoot, 'lanes', laneName!, TASK_RESULTS_DIR);
+    const resultPath = findTaskResultFile(resultsDir, taskName!);
+    
+    if (resultPath && fs.existsSync(resultPath)) {
+      try {
+        const text = fs.readFileSync(resultPath, 'utf8');
+        results.push({ taskId: dep, resultText: text });
+        logger.info(`📖 Loaded dependency result: ${dep}`);
+      } catch (e) {
+        logger.warn(`Failed to read dependency result ${dep}: ${e}`);
+        results.push({ taskId: dep, resultText: '(읽기 실패)' });
+      }
+    } else {
+      logger.warn(`Dependency result not found for: ${dep}`);
+      results.push({ taskId: dep, resultText: '(결과 없음)' });
+    }
+  }
+  
+  return results;
+}
+
+/**
+ * Read dependency request from file if it exists
+ */
+export function readDependencyRequestFile(worktreeDir: string): { required: boolean; plan?: DependencyRequestPlan } {
+  const filePath = safeJoin(worktreeDir, DEPENDENCY_REQUEST_FILE);
+  
+  if (!fs.existsSync(filePath)) {
+    return { required: false };
+  }
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const plan = JSON.parse(content) as DependencyRequestPlan;
+    
+    // Validate required fields
+    if (plan.reason && Array.isArray(plan.commands) && plan.commands.length > 0) {
+      logger.info(`📦 Dependency request file detected: ${filePath}`);
+      return { required: true, plan };
+    }
+    
+    logger.warn(`Invalid dependency request file format: ${filePath}`);
+    return { required: false };
+  } catch (e) {
+    logger.warn(`Failed to parse dependency request file: ${e}`);
+    return { required: false };
+  }
+}
+
+/**
+ * Clear dependency request file after processing
+ */
+export function clearDependencyRequestFile(worktreeDir: string): void {
+  const filePath = safeJoin(worktreeDir, DEPENDENCY_REQUEST_FILE);
+  
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.unlinkSync(filePath);
+      logger.info(`🗑️ Cleared dependency request file: ${filePath}`);
+    } catch (e) {
+      logger.warn(`Failed to clear dependency request file: ${e}`);
+    }
+  }
+}
+