cc-devflow 2.4.6 → 4.1.0

package/.claude/hooks/teammate-idle-hook.ts

@@ -0,0 +1,690 @@
+#!/usr/bin/env npx ts-node
+/**
+ * [INPUT]: 依赖 quality-gates.yml 的 teammate_idle 配置，依赖 orchestration_status.json 的 Team 状态
+ * [OUTPUT]: 对外提供 TeammateIdle Hook，在 Teammate 空闲时验证任务并分配下一个任务
+ * [POS]: hooks/ 的 Team 任务调度器，被 Claude Team 的 TeammateIdle 事件触发
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ *
+ * =============================================================================
+ * CC-DevFlow TeammateIdle Hook (v4.7)
+ * =============================================================================
+ *
+ * 核心设计哲学：
+ * - Teammate 空闲时执行任务验证
+ * - 验证通过后分配下一个任务
+ * - 所有任务完成且所有 Teammate 空闲时触发 shutdown
+ * - 状态持久化到 orchestration_status.json
+ *
+ * 触发条件：TeammateIdle 事件
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+// =============================================================================
+// 类型定义
+// =============================================================================
+
+interface TeammateIdleInput {
+  hook_event_name: 'TeammateIdle';
+  teammate_id: string;
+  teammate_role: string;
+  last_task_id?: string;
+  idle_reason: 'task_complete' | 'waiting_dependency' | 'no_tasks' | 'error';
+  cwd: string;
+  session_id: string;
+}
+
+interface TeammateIdleOutput {
+  action: 'assign_task' | 'wait' | 'shutdown';
+  task_id?: string;
+  message?: string;
+}
+
+interface VerifyCommand {
+  name?: string;
+  command: string;
+  required?: boolean;
+}
+
+interface TeammateIdleConfig {
+  idle_checks?: (string | VerifyCommand)[];
+  assignment_strategy?: 'priority_first' | 'round_robin' | 'skill_match';
+  idle_timeout?: number;
+}
+
+interface QualityGatesConfig {
+  teammate_idle?: TeammateIdleConfig;
+  verify?: (string | VerifyCommand)[];
+  global?: {
+    max_iterations?: number;
+    timeout_minutes?: number;
+  };
+}
+
+interface TeammateState {
+  id: string;
+  role: string;
+  status: 'idle' | 'working' | 'blocked' | 'completed' | 'error';
+  currentTask: string | null;
+  completedTasks: string[];
+  lastActiveAt: string;
+  errorMessage?: string;
+}
+
+interface TeamState {
+  mode: 'sequential' | 'parallel';
+  lead: string;
+  teammates: TeammateState[];
+  taskAssignments: Record<string, string>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface OrchestrationStatus {
+  reqId: string;
+  title?: string;
+  status: string;
+  phase: string;
+  team?: TeamState;
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// 配置常量
+// =============================================================================
+
+const CONFIG_FILE = '.claude/config/quality-gates.yml';
+const COMMAND_TIMEOUT_MS = 60000; // 1 minute per command
+
+// =============================================================================
+// 工具函数
+// =============================================================================
+
+/**
+ * 查找 Git 仓库根目录
+ */
+function findRepoRoot(startPath: string): string | null {
+  let current = path.resolve(startPath);
+  while (current !== path.dirname(current)) {
+    if (fs.existsSync(path.join(current, '.git'))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 从 worktree 目录名或分支名提取 REQ-ID
+ */
+function extractReqId(repoRoot: string): string | null {
+  // 尝试从目录名提取 (e.g., cc-devflow-REQ-123)
+  const dirName = path.basename(repoRoot);
+  const dirMatch = dirName.match(/-([A-Z]+-\d+(?:-\d+)?)$/);
+  if (dirMatch) {
+    return dirMatch[1];
+  }
+
+  // 尝试从 git 分支提取
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      timeout: 5000
+    }).trim();
+    const branchMatch = branch.match(/(REQ-\d+(?:-\d+)?|BUG-\d+(?:-\d+)?)/);
+    if (branchMatch) {
+      return branchMatch[1];
+    }
+  } catch {
+    // 忽略 git 错误
+  }
+
+  return null;
+}
+
+/**
+ * 简单 YAML 解析器 (无外部依赖)
+ * 只解析 teammate_idle 和 verify 配置
+ */
+function parseSimpleYaml(content: string): QualityGatesConfig {
+  const config: QualityGatesConfig = {};
+  const lines = content.split('\n');
+
+  let inTeammateIdleSection = false;
+  let inIdleChecksSection = false;
+  let inVerifySection = false;
+  const idleChecks: (string | VerifyCommand)[] = [];
+  const verifyCommands: (string | VerifyCommand)[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // 跳过注释和空行
+    if (trimmed.startsWith('#') || trimmed === '') continue;
+
+    // 检测顶级 section
+    if (!line.startsWith(' ') && !line.startsWith('\t') && trimmed.endsWith(':')) {
+      const section = trimmed.slice(0, -1);
+      inTeammateIdleSection = section === 'teammate_idle';
+      inIdleChecksSection = false;
+      inVerifySection = section === 'verify';
+      continue;
+    }
+
+    // 检测 teammate_idle 子 section
+    if (inTeammateIdleSection && trimmed === 'idle_checks:') {
+      inIdleChecksSection = true;
+      continue;
+    }
+
+    // 解析 idle_checks 列表项
+    if (inIdleChecksSection && trimmed.startsWith('- ')) {
+      const value = trimmed.slice(2).trim();
+      if (!value.startsWith('name:') && !value.includes(':')) {
+        idleChecks.push(value);
+      }
+      continue;
+    }
+
+    // 解析顶级 verify 列表项
+    if (inVerifySection && trimmed.startsWith('- ')) {
+      const value = trimmed.slice(2).trim();
+      if (!value.startsWith('name:') && !value.includes(':')) {
+        verifyCommands.push(value);
+      }
+      continue;
+    }
+  }
+
+  if (idleChecks.length > 0) {
+    config.teammate_idle = { idle_checks: idleChecks };
+  }
+
+  if (verifyCommands.length > 0) {
+    config.verify = verifyCommands;
+  }
+
+  return config;
+}
+
+/**
+ * 读取 quality-gates.yml 配置
+ */
+function loadConfig(repoRoot: string): QualityGatesConfig {
+  const configPath = path.join(repoRoot, CONFIG_FILE);
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return parseSimpleYaml(content);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 获取 idle_checks 命令列表
+ */
+function getIdleChecks(config: QualityGatesConfig): string[] {
+  // 优先使用 teammate_idle.idle_checks
+  if (config.teammate_idle?.idle_checks) {
+    return config.teammate_idle.idle_checks.map(cmd => {
+      if (typeof cmd === 'string') return cmd;
+      return cmd.command;
+    });
+  }
+
+  // 回退到顶级 verify 命令
+  if (config.verify) {
+    return config.verify.map(cmd => {
+      if (typeof cmd === 'string') return cmd;
+      return cmd.command;
+    });
+  }
+
+  // 默认验证命令
+  return [
+    'npm run lint --if-present',
+    'npm run typecheck --if-present',
+    'npm test -- --passWithNoTests'
+  ];
+}
+
+/**
+ * 读取 orchestration_status.json
+ */
+function loadOrchestrationStatus(repoRoot: string, reqId: string): OrchestrationStatus | null {
+  const statusPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'orchestration_status.json');
+  if (!fs.existsSync(statusPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(statusPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 更新 orchestration_status.json 中的 Teammate 状态
+ */
+function updateTeammateStatus(
+  repoRoot: string,
+  reqId: string,
+  teammateId: string,
+  status: string,
+  currentTask: string | null
+): void {
+  const statusPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'orchestration_status.json');
+  if (!fs.existsSync(statusPath)) {
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(statusPath, 'utf-8');
+    const statusObj: OrchestrationStatus = JSON.parse(content);
+
+    if (!statusObj.team) {
+      return;
+    }
+
+    const now = new Date().toISOString();
+    const teammate = statusObj.team.teammates.find(t => t.id === teammateId);
+    if (teammate) {
+      teammate.status = status as TeammateState['status'];
+      teammate.currentTask = currentTask;
+      teammate.lastActiveAt = now;
+    }
+    statusObj.team.updatedAt = now;
+
+    fs.writeFileSync(statusPath, JSON.stringify(statusObj, null, 2), 'utf-8');
+  } catch {
+    // 忽略更新错误
+  }
+}
+
+/**
+ * 标记任务完成
+ */
+function markTaskComplete(
+  repoRoot: string,
+  reqId: string,
+  teammateId: string,
+  taskId: string
+): void {
+  const statusPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'orchestration_status.json');
+  if (!fs.existsSync(statusPath)) {
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(statusPath, 'utf-8');
+    const statusObj: OrchestrationStatus = JSON.parse(content);
+
+    if (!statusObj.team) {
+      return;
+    }
+
+    const now = new Date().toISOString();
+    const teammate = statusObj.team.teammates.find(t => t.id === teammateId);
+    if (teammate) {
+      if (!teammate.completedTasks.includes(taskId)) {
+        teammate.completedTasks.push(taskId);
+      }
+      teammate.currentTask = null;
+      teammate.status = 'idle';
+      teammate.lastActiveAt = now;
+    }
+    statusObj.team.updatedAt = now;
+
+    fs.writeFileSync(statusPath, JSON.stringify(statusObj, null, 2), 'utf-8');
+  } catch {
+    // 忽略更新错误
+  }
+}
+
+/**
+ * 执行验证命令
+ */
+function runIdleChecks(
+  repoRoot: string,
+  commands: string[]
+): { passed: boolean; failures: string[] } {
+  const failures: string[] = [];
+
+  for (const cmd of commands) {
+    try {
+      execSync(cmd, {
+        cwd: repoRoot,
+        timeout: COMMAND_TIMEOUT_MS,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8'
+      });
+    } catch (error: unknown) {
+      let output = '';
+      if (error && typeof error === 'object') {
+        const execError = error as { stderr?: string; stdout?: string; message?: string };
+        output = execError.stderr || execError.stdout || execError.message || 'Unknown error';
+      }
+
+      // 截断过长输出
+      if (output.length > 300) {
+        output = output.slice(0, 300) + '...';
+      }
+
+      failures.push(`Command: ${cmd}\nError: ${output}`);
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures
+  };
+}
+
+/**
+ * 从 TASKS.md 提取所有任务 ID
+ */
+function extractTaskIds(repoRoot: string, reqId: string): string[] {
+  const tasksPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'TASKS.md');
+  if (!fs.existsSync(tasksPath)) {
+    return [];
+  }
+
+  try {
+    const content = fs.readFileSync(tasksPath, 'utf-8');
+    // 匹配 **T001** 格式的任务 ID
+    const matches = content.match(/\*\*T\d+\*\*/g) || [];
+    return [...new Set(matches.map((m: string) => m.replace(/\*\*/g, '')))];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 获取未分配的任务
+ */
+function getUnassignedTasks(
+  allTasks: string[],
+  teamState: TeamState | undefined
+): string[] {
+  if (!teamState) {
+    return allTasks;
+  }
+
+  const assignedTasks = Object.keys(teamState.taskAssignments);
+  const completedTasks = teamState.teammates.flatMap(t => t.completedTasks);
+
+  return allTasks.filter(task =>
+    !assignedTasks.includes(task) && !completedTasks.includes(task)
+  );
+}
+
+/**
+ * 检查是否所有 Teammate 都空闲
+ */
+function allTeammatesIdle(teamState: TeamState | undefined): boolean {
+  if (!teamState || teamState.teammates.length === 0) {
+    return true;
+  }
+
+  return teamState.teammates.every(t =>
+    t.status === 'idle' || t.status === 'completed'
+  );
+}
+
+/**
+ * 检查 Teammate 是否超时
+ * @param teammate Teammate 状态
+ * @param timeoutSeconds 超时秒数
+ * @returns 是否超时
+ */
+function isTeammateTimedOut(teammate: TeammateState, timeoutSeconds: number): boolean {
+  if (!teammate.lastActiveAt) {
+    return false;
+  }
+
+  const lastActive = new Date(teammate.lastActiveAt).getTime();
+  const now = Date.now();
+  const elapsedSeconds = (now - lastActive) / 1000;
+
+  return elapsedSeconds > timeoutSeconds;
+}
+
+/**
+ * 获取超时的 Teammate 列表
+ */
+function getTimedOutTeammates(
+  teamState: TeamState | undefined,
+  timeoutSeconds: number
+): TeammateState[] {
+  if (!teamState || teamState.teammates.length === 0) {
+    return [];
+  }
+
+  return teamState.teammates.filter(t =>
+    t.status === 'working' && isTeammateTimedOut(t, timeoutSeconds)
+  );
+}
+
+/**
+ * 记录超时告警到 EXECUTION_LOG.md
+ */
+function logTimeoutAlert(
+  repoRoot: string,
+  reqId: string,
+  timedOutTeammates: TeammateState[]
+): void {
+  const logPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'EXECUTION_LOG.md');
+
+  const timestamp = new Date().toISOString();
+  const alertContent = timedOutTeammates.map(t =>
+    `- **${t.id}** (task: ${t.currentTask || 'none'}, last active: ${t.lastActiveAt})`
+  ).join('\n');
+
+  const logEntry = `
+## [${timestamp}] ⚠️ Teammate Timeout Alert
+
+The following teammates have exceeded the idle timeout:
+
+${alertContent}
+
+**Action**: Consider checking their status or reassigning tasks.
+
+---
+`;
+
+  try {
+    if (fs.existsSync(logPath)) {
+      fs.appendFileSync(logPath, logEntry, 'utf-8');
+    } else {
+      fs.writeFileSync(logPath, `# Execution Log\n${logEntry}`, 'utf-8');
+    }
+  } catch {
+    // 忽略日志写入错误
+  }
+}
+
+/**
+ * 分配任务给 Teammate
+ */
+function assignTask(
+  repoRoot: string,
+  reqId: string,
+  taskId: string,
+  teammateId: string
+): void {
+  const statusPath = path.join(repoRoot, 'devflow', 'requirements', reqId, 'orchestration_status.json');
+  if (!fs.existsSync(statusPath)) {
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(statusPath, 'utf-8');
+    const statusObj: OrchestrationStatus = JSON.parse(content);
+
+    if (!statusObj.team) {
+      return;
+    }
+
+    const now = new Date().toISOString();
+    statusObj.team.taskAssignments[taskId] = teammateId;
+
+    const teammate = statusObj.team.teammates.find(t => t.id === teammateId);
+    if (teammate) {
+      teammate.currentTask = taskId;
+      teammate.status = 'working';
+      teammate.lastActiveAt = now;
+    }
+    statusObj.team.updatedAt = now;
+
+    fs.writeFileSync(statusPath, JSON.stringify(statusObj, null, 2), 'utf-8');
+  } catch {
+    // 忽略更新错误
+  }
+}
+
+// =============================================================================
+// 主函数
+// =============================================================================
+
+function main(): void {
+  let inputData: TeammateIdleInput;
+
+  // 读取 stdin 输入
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8');
+    inputData = JSON.parse(stdin);
+  } catch {
+    // 无法解析输入，返回 wait
+    const output: TeammateIdleOutput = {
+      action: 'wait',
+      message: 'Failed to parse input'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 验证 hook 事件类型
+  if (inputData.hook_event_name !== 'TeammateIdle') {
+    const output: TeammateIdleOutput = {
+      action: 'wait',
+      message: 'Not a TeammateIdle event'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  const { teammate_id, last_task_id, idle_reason, cwd } = inputData;
+
+  // 查找仓库根目录
+  const repoRoot = findRepoRoot(cwd);
+  if (!repoRoot) {
+    const output: TeammateIdleOutput = {
+      action: 'wait',
+      message: 'Not in a git repository'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 提取 REQ-ID
+  const reqId = extractReqId(repoRoot);
+  if (!reqId) {
+    const output: TeammateIdleOutput = {
+      action: 'wait',
+      message: 'Could not determine REQ-ID'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 加载配置
+  const config = loadConfig(repoRoot);
+  const idleChecks = getIdleChecks(config);
+  const idleTimeout = config.teammate_idle?.idle_timeout || 300; // 默认 5 分钟
+
+  // 加载 orchestration_status.json
+  const status = loadOrchestrationStatus(repoRoot, reqId);
+  if (!status) {
+    const output: TeammateIdleOutput = {
+      action: 'wait',
+      message: 'orchestration_status.json not found'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 检查超时的 Teammate 并记录告警
+  const timedOutTeammates = getTimedOutTeammates(status.team, idleTimeout);
+  if (timedOutTeammates.length > 0) {
+    logTimeoutAlert(repoRoot, reqId, timedOutTeammates);
+  }
+
+  // 如果有上一个任务，执行验证
+  if (last_task_id && idle_reason === 'task_complete') {
+    const { passed, failures } = runIdleChecks(repoRoot, idleChecks);
+
+    if (!passed) {
+      // 验证失败，让 Teammate 继续修复
+      updateTeammateStatus(repoRoot, reqId, teammate_id, 'working', last_task_id);
+
+      const output: TeammateIdleOutput = {
+        action: 'assign_task',
+        task_id: last_task_id,
+        message: `Verification failed. Please fix the issues:\n\n${failures.join('\n\n')}`
+      };
+      console.log(JSON.stringify(output, null, 0));
+      process.exit(0);
+    }
+
+    // 验证通过，标记任务完成
+    markTaskComplete(repoRoot, reqId, teammate_id, last_task_id);
+  }
+
+  // 获取所有任务和未分配任务
+  const allTasks = extractTaskIds(repoRoot, reqId);
+  const unassignedTasks = getUnassignedTasks(allTasks, status.team);
+
+  // 如果有未分配任务，分配下一个
+  if (unassignedTasks.length > 0) {
+    const nextTask = unassignedTasks[0]; // priority_first 策略
+    assignTask(repoRoot, reqId, nextTask, teammate_id);
+
+    const output: TeammateIdleOutput = {
+      action: 'assign_task',
+      task_id: nextTask,
+      message: `Assigned task ${nextTask}`
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 没有未分配任务，检查是否所有 Teammate 都空闲
+  if (allTeammatesIdle(status.team)) {
+    // 所有任务完成，所有 Teammate 空闲，触发 shutdown
+    const output: TeammateIdleOutput = {
+      action: 'shutdown',
+      message: 'All tasks completed. Shutting down.'
+    };
+    console.log(JSON.stringify(output, null, 0));
+    process.exit(0);
+  }
+
+  // 还有其他 Teammate 在工作，等待
+  const output: TeammateIdleOutput = {
+    action: 'wait',
+    message: 'Waiting for other teammates to complete their tasks'
+  };
+  console.log(JSON.stringify(output, null, 0));
+  process.exit(0);
+}
+
+main();