cc-devflow 2.4.6 → 4.1.0

package/.claude/scripts/team-state-recovery.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Team State Recovery Script
+# =============================================================================
+# [INPUT]: 依赖 common.sh 的 Team 函数
+# [OUTPUT]: 恢复 Team 状态，支持断点续传
+# [POS]: flow-dev 的状态恢复器，被 /flow:dev --resume 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# =============================================================================
+# State Recovery Functions
+# =============================================================================
+
+# Check if Team state can be recovered
+# Args: $1 - repo root, $2 - requirement ID
+can_recover_state() {
+    local repo_root="$1"
+    local req_id="$2"
+    local status_file="$repo_root/devflow/requirements/$req_id/orchestration_status.json"
+
+    if [[ ! -f "$status_file" ]]; then
+        echo "false"
+        return 0
+    fi
+
+    local team_mode
+    team_mode=$(jq -r '.team.mode // "none"' "$status_file")
+
+    if [[ "$team_mode" == "none" || "$team_mode" == "null" ]]; then
+        echo "false"
+        return 0
+    fi
+
+    echo "true"
+}
+
+# Get recovery summary
+# Args: $1 - repo root, $2 - requirement ID
+get_recovery_summary() {
+    local repo_root="$1"
+    local req_id="$2"
+    local status_file="$repo_root/devflow/requirements/$req_id/orchestration_status.json"
+
+    if [[ ! -f "$status_file" ]]; then
+        echo '{"canRecover": false, "reason": "Status file not found"}'
+        return 0
+    fi
+
+    local team_data
+    team_data=$(jq '{
+        canRecover: (.team.mode != null and .team.mode != "none"),
+        mode: .team.mode,
+        lead: .team.lead,
+        teammateCount: (.team.teammates | length),
+        completedTasks: [.team.teammates[].completedTasks | length] | add,
+        pendingTasks: (.team.taskAssignments | keys | length),
+        lastActiveAt: ([.team.teammates[].lastActiveAt] | max),
+        ralphLoop: {
+            globalIteration: .ralphLoop.globalIteration,
+            maxIterations: .ralphLoop.maxIterations
+        }
+    }' "$status_file")
+
+    echo "$team_data"
+}
+
+# Recover Team state
+# Args: $1 - repo root, $2 - requirement ID
+recover_state() {
+    local repo_root="$1"
+    local req_id="$2"
+    local status_file="$repo_root/devflow/requirements/$req_id/orchestration_status.json"
+
+    echo "Recovering Team state for $req_id..."
+
+    # Reset teammate statuses to idle
+    local updated
+    updated=$(jq '
+        .team.teammates = [.team.teammates[] | .status = "idle" | .currentTask = null]
+    ' "$status_file")
+
+    echo "$updated" > "$status_file"
+
+    # Get pending tasks
+    local pending_tasks
+    pending_tasks=$(get_unassigned_tasks "$repo_root" "$req_id")
+
+    echo "Recovery complete."
+    echo "Pending tasks: $pending_tasks"
+}
+
+# Create state snapshot
+# Args: $1 - repo root, $2 - requirement ID
+create_snapshot() {
+    local repo_root="$1"
+    local req_id="$2"
+    local status_file="$repo_root/devflow/requirements/$req_id/orchestration_status.json"
+    local snapshot_dir="$repo_root/devflow/requirements/$req_id/.snapshots"
+    local timestamp
+    timestamp=$(date +%Y%m%d_%H%M%S)
+
+    mkdir -p "$snapshot_dir"
+
+    if [[ -f "$status_file" ]]; then
+        cp "$status_file" "$snapshot_dir/orchestration_status_$timestamp.json"
+        echo "Snapshot created: $snapshot_dir/orchestration_status_$timestamp.json"
+    else
+        echo "No status file to snapshot"
+    fi
+}
+
+# Restore from snapshot
+# Args: $1 - repo root, $2 - requirement ID, $3 - snapshot timestamp (optional)
+restore_snapshot() {
+    local repo_root="$1"
+    local req_id="$2"
+    local timestamp="${3:-}"
+    local status_file="$repo_root/devflow/requirements/$req_id/orchestration_status.json"
+    local snapshot_dir="$repo_root/devflow/requirements/$req_id/.snapshots"
+
+    if [[ -z "$timestamp" ]]; then
+        # Get latest snapshot
+        local latest
+        latest=$(ls -t "$snapshot_dir"/orchestration_status_*.json 2>/dev/null | head -1)
+        if [[ -z "$latest" ]]; then
+            echo "No snapshots found"
+            return 1
+        fi
+        cp "$latest" "$status_file"
+        echo "Restored from: $latest"
+    else
+        local snapshot_file="$snapshot_dir/orchestration_status_$timestamp.json"
+        if [[ -f "$snapshot_file" ]]; then
+            cp "$snapshot_file" "$status_file"
+            echo "Restored from: $snapshot_file"
+        else
+            echo "Snapshot not found: $snapshot_file"
+            return 1
+        fi
+    fi
+}
+
+# List available snapshots
+# Args: $1 - repo root, $2 - requirement ID
+list_snapshots() {
+    local repo_root="$1"
+    local req_id="$2"
+    local snapshot_dir="$repo_root/devflow/requirements/$req_id/.snapshots"
+
+    if [[ ! -d "$snapshot_dir" ]]; then
+        echo "[]"
+        return 0
+    fi
+
+    local snapshots='[]'
+    for file in "$snapshot_dir"/orchestration_status_*.json; do
+        if [[ -f "$file" ]]; then
+            local timestamp
+            timestamp=$(basename "$file" | sed 's/orchestration_status_//' | sed 's/.json//')
+            snapshots=$(echo "$snapshots" | jq --arg ts "$timestamp" '. + [$ts]')
+        fi
+    done
+
+    echo "$snapshots"
+}
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+    local action="${1:-help}"
+
+    case "$action" in
+        check)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            can_recover_state "$repo_root" "$req_id"
+            ;;
+        summary)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            get_recovery_summary "$repo_root" "$req_id"
+            ;;
+        recover)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            recover_state "$repo_root" "$req_id"
+            ;;
+        snapshot)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            create_snapshot "$repo_root" "$req_id"
+            ;;
+        restore)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            local timestamp="${4:-}"
+            restore_snapshot "$repo_root" "$req_id" "$timestamp"
+            ;;
+        list-snapshots)
+            local repo_root="${2:-$(get_repo_root)}"
+            local req_id="${3:-$(get_current_req_id)}"
+            list_snapshots "$repo_root" "$req_id"
+            ;;
+        help|*)
+            echo "Usage: $0 <action> [args...]"
+            echo ""
+            echo "Actions:"
+            echo "  check [repo_root] [req_id]              - Check if state can be recovered"
+            echo "  summary [repo_root] [req_id]            - Get recovery summary"
+            echo "  recover [repo_root] [req_id]            - Recover Team state"
+            echo "  snapshot [repo_root] [req_id]           - Create state snapshot"
+            echo "  restore [repo_root] [req_id] [timestamp] - Restore from snapshot"
+            echo "  list-snapshots [repo_root] [req_id]     - List available snapshots"
+            ;;
+    esac
+}
+
+# Run if executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

package/.claude/scripts/workflow-status.ts

@@ -0,0 +1,433 @@
+/**
+ * [INPUT]: 依赖 fs, path, yaml (js-yaml) 模块
+ * [OUTPUT]: 对外提供 WorkflowStatus 类型、isArtifactComplete, getNextActions, getWorkflowStatus 函数
+ * [POS]: .claude/scripts 的工作流状态检测工具，被 flow-* 命令和 hooks 消费
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { glob } from 'glob';
+
+// =============================================================================
+// 类型定义
+// =============================================================================
+
+/** 工件定义 */
+export interface Artifact {
+  id: string;
+  generates: string;
+  requires: string[];
+  skill: string;
+  optional?: boolean;
+  glob?: boolean;
+  instruction?: string;
+}
+
+/** 工件状态 */
+export type ArtifactStatus = 'complete' | 'ready' | 'blocked';
+
+/** 工件状态详情 */
+export interface ArtifactStatusDetail {
+  id: string;
+  status: ArtifactStatus;
+  generates: string;
+  resolvedPath: string;
+  skill: string;
+  optional: boolean;
+  blockedBy?: string[];
+}
+
+/** 工作流状态 */
+export interface WorkflowStatus {
+  reqId: string;
+  complete: ArtifactStatusDetail[];
+  ready: ArtifactStatusDetail[];
+  optionalPending: ArtifactStatusDetail[];
+  blocked: ArtifactStatusDetail[];
+  progress: {
+    completed: number;
+    total: number;
+    percent: number;
+  };
+  nextAction?: {
+    artifactId: string;
+    skill: string;
+    command: string;
+  };
+}
+
+/** workflow.yaml 结构 */
+interface WorkflowSchema {
+  name: string;
+  version: string;
+  description: string;
+  artifacts: Artifact[];
+  detection: {
+    method: string;
+    fallback: string;
+    glob_options?: {
+      ignore?: string[];
+    };
+  };
+  skills: Record<string, Array<{ id: string; path: string; description: string }>>;
+  context: {
+    global: Array<{ file: string; reason: string }>;
+    defaults: Record<string, Array<{ file: string; reason: string; optional?: boolean }>>;
+  };
+  deprecated: Array<{ id: string; replacement: string; message: string }>;
+}
+
+// =============================================================================
+// 配置
+// =============================================================================
+
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const WORKFLOW_YAML_PATH = path.join(PROJECT_ROOT, '.claude/skills/workflow.yaml');
+
+// =============================================================================
+// 核心函数
+// =============================================================================
+
+/** 加载 workflow.yaml */
+export function loadWorkflowSchema(): WorkflowSchema {
+  const content = fs.readFileSync(WORKFLOW_YAML_PATH, 'utf-8');
+  return yaml.load(content) as WorkflowSchema;
+}
+
+/** 替换路径中的占位符 */
+export function resolvePath(pattern: string, reqId: string, bugId?: string): string {
+  let resolved = pattern.replace(/\{REQ\}/g, reqId);
+  if (bugId) {
+    resolved = resolved.replace(/\{BUG\}/g, bugId);
+  }
+  return resolved;
+}
+
+/** 检查文件/目录是否存在（支持 glob） */
+export async function checkExists(pattern: string, isGlob: boolean): Promise<boolean> {
+  const fullPath = path.join(PROJECT_ROOT, pattern);
+
+  if (isGlob) {
+    // glob 模式：检查是否有匹配的文件
+    const matches = await glob(fullPath, { nodir: false });
+    return matches.length > 0;
+  } else {
+    // 精确路径：检查文件或目录存在
+    return fs.existsSync(fullPath);
+  }
+}
+
+/** 同步版本的检查存在性 */
+export function checkExistsSync(pattern: string, isGlob: boolean): boolean {
+  const fullPath = path.join(PROJECT_ROOT, pattern);
+
+  if (isGlob) {
+    // 简化的 glob 检查：使用 fs.readdirSync
+    const dir = path.dirname(fullPath);
+    const filePattern = path.basename(fullPath);
+
+    if (!fs.existsSync(dir)) return false;
+
+    try {
+      const files = fs.readdirSync(dir);
+      // 简单的通配符匹配
+      const regex = new RegExp('^' + filePattern.replace(/\*/g, '.*') + '$');
+      return files.some(f => regex.test(f));
+    } catch {
+      return false;
+    }
+  } else {
+    return fs.existsSync(fullPath);
+  }
+}
+
+/** 检查工件是否完成 */
+export function isArtifactComplete(artifact: Artifact, reqId: string): boolean {
+  const resolvedPath = resolvePath(artifact.generates, reqId);
+  return checkExistsSync(resolvedPath, artifact.glob ?? false);
+}
+
+/** 获取工件的依赖状态 */
+export function getBlockingDependencies(
+  artifact: Artifact,
+  reqId: string,
+  schema: WorkflowSchema
+): string[] {
+  const blocking: string[] = [];
+
+  for (const depId of artifact.requires) {
+    const depArtifact = schema.artifacts.find(a => a.id === depId);
+    if (!depArtifact) continue;
+
+    if (!isArtifactComplete(depArtifact, reqId)) {
+      blocking.push(depId);
+    }
+  }
+
+  return blocking;
+}
+
+/** 获取工件状态 */
+export function getArtifactStatus(
+  artifact: Artifact,
+  reqId: string,
+  schema: WorkflowSchema
+): ArtifactStatus {
+  if (isArtifactComplete(artifact, reqId)) {
+    return 'complete';
+  }
+
+  const blocking = getBlockingDependencies(artifact, reqId, schema);
+  if (blocking.length === 0) {
+    return 'ready';
+  }
+
+  return 'blocked';
+}
+
+/** 获取下一步可执行的工件 */
+export function getNextActions(reqId: string): Artifact[] {
+  const schema = loadWorkflowSchema();
+  const ready: Artifact[] = [];
+
+  // 筛选需求级工件
+  const reqArtifacts = schema.artifacts.filter(a => a.generates.includes('{REQ}'));
+
+  for (const artifact of reqArtifacts) {
+    const status = getArtifactStatus(artifact, reqId, schema);
+
+    // 只返回非可选的 ready 工件
+    if (status === 'ready' && !artifact.optional) {
+      ready.push(artifact);
+    }
+  }
+
+  return ready;
+}
+
+/** 获取完整的工作流状态 */
+export function getWorkflowStatus(reqId: string): WorkflowStatus {
+  const schema = loadWorkflowSchema();
+
+  const complete: ArtifactStatusDetail[] = [];
+  const ready: ArtifactStatusDetail[] = [];
+  const optionalPending: ArtifactStatusDetail[] = [];
+  const blocked: ArtifactStatusDetail[] = [];
+
+  // 筛选需求级工件
+  const reqArtifacts = schema.artifacts.filter(a => a.generates.includes('{REQ}'));
+
+  for (const artifact of reqArtifacts) {
+    const status = getArtifactStatus(artifact, reqId, schema);
+    const resolvedPath = resolvePath(artifact.generates, reqId);
+
+    const detail: ArtifactStatusDetail = {
+      id: artifact.id,
+      status,
+      generates: artifact.generates,
+      resolvedPath,
+      skill: artifact.skill,
+      optional: artifact.optional ?? false,
+    };
+
+    if (status === 'blocked') {
+      detail.blockedBy = getBlockingDependencies(artifact, reqId, schema);
+    }
+
+    switch (status) {
+      case 'complete':
+        complete.push(detail);
+        break;
+      case 'ready':
+        if (artifact.optional) {
+          optionalPending.push(detail);
+        } else {
+          ready.push(detail);
+        }
+        break;
+      case 'blocked':
+        blocked.push(detail);
+        break;
+    }
+  }
+
+  // 计算进度
+  const total = complete.length + ready.length + blocked.length;
+  const percent = total > 0 ? Math.round((complete.length / total) * 100) : 0;
+
+  // 确定下一步
+  let nextAction: WorkflowStatus['nextAction'];
+  if (ready.length > 0) {
+    const next = ready[0];
+    nextAction = {
+      artifactId: next.id,
+      skill: next.skill,
+      command: `/${next.skill} "${reqId}"`,
+    };
+  }
+
+  return {
+    reqId,
+    complete,
+    ready,
+    optionalPending,
+    blocked,
+    progress: {
+      completed: complete.length,
+      total,
+      percent,
+    },
+    nextAction,
+  };
+}
+
+/** 获取项目级工件状态 */
+export function getProjectStatus(): {
+  complete: ArtifactStatusDetail[];
+  missing: ArtifactStatusDetail[];
+} {
+  const schema = loadWorkflowSchema();
+
+  const complete: ArtifactStatusDetail[] = [];
+  const missing: ArtifactStatusDetail[] = [];
+
+  // 筛选项目级工件（不包含 {REQ} 或 {BUG}）
+  const projectArtifacts = schema.artifacts.filter(
+    a => !a.generates.includes('{REQ}') && !a.generates.includes('{BUG}')
+  );
+
+  for (const artifact of projectArtifacts) {
+    const exists = checkExistsSync(artifact.generates, artifact.glob ?? false);
+
+    const detail: ArtifactStatusDetail = {
+      id: artifact.id,
+      status: exists ? 'complete' : 'ready',
+      generates: artifact.generates,
+      resolvedPath: artifact.generates,
+      skill: artifact.skill,
+      optional: artifact.optional ?? false,
+    };
+
+    if (exists) {
+      complete.push(detail);
+    } else {
+      missing.push(detail);
+    }
+  }
+
+  return { complete, missing };
+}
+
+/** 格式化输出工作流状态 */
+export function formatWorkflowStatus(status: WorkflowStatus): string {
+  const lines: string[] = [];
+
+  lines.push(`\n=== 需求 ${status.reqId} 工作流状态 ===\n`);
+
+  if (status.complete.length > 0) {
+    lines.push(`已完成 (${status.complete.length}):`);
+    for (const a of status.complete) {
+      lines.push(`  ✓ ${a.id} → ${a.resolvedPath}`);
+    }
+    lines.push('');
+  }
+
+  if (status.ready.length > 0) {
+    lines.push(`可执行 (${status.ready.length}):`);
+    for (const a of status.ready) {
+      lines.push(`  → ${a.id} (skill: ${a.skill})`);
+    }
+    lines.push('');
+  }
+
+  if (status.optionalPending.length > 0) {
+    lines.push(`可选工件 (${status.optionalPending.length}):`);
+    for (const a of status.optionalPending) {
+      lines.push(`  ○ ${a.id} (skill: ${a.skill})`);
+    }
+    lines.push('');
+  }
+
+  if (status.blocked.length > 0) {
+    lines.push(`阻塞中 (${status.blocked.length}):`);
+    for (const a of status.blocked) {
+      lines.push(`  ✗ ${a.id} (等待: ${a.blockedBy?.join(', ')})`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`进度: ${status.progress.completed}/${status.progress.total} (${status.progress.percent}%)`);
+
+  if (status.nextAction) {
+    lines.push('');
+    lines.push(`建议下一步: ${status.nextAction.command}`);
+  }
+
+  return lines.join('\n');
+}
+
+// =============================================================================
+// CLI 入口
+// =============================================================================
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+用法: npx ts-node workflow-status.ts [REQ-ID] [选项]
+
+选项:
+  --json      JSON 格式输出
+  --next      仅输出下一步可执行的工件
+  --project   检查项目级工件状态
+  -h, --help  显示帮助
+`);
+    process.exit(0);
+  }
+
+  const isJson = args.includes('--json');
+  const isNext = args.includes('--next');
+  const isProject = args.includes('--project');
+  const reqId = args.find(a => a.startsWith('REQ-'));
+
+  if (isProject) {
+    const status = getProjectStatus();
+    if (isJson) {
+      console.log(JSON.stringify(status, null, 2));
+    } else {
+      console.log('\n=== 项目级工件状态 ===\n');
+      if (status.complete.length > 0) {
+        console.log(`已完成 (${status.complete.length}):`);
+        for (const a of status.complete) {
+          console.log(`  ✓ ${a.id} → ${a.generates}`);
+        }
+      }
+      if (status.missing.length > 0) {
+        console.log(`\n缺失 (${status.missing.length}):`);
+        for (const a of status.missing) {
+          console.log(`  ○ ${a.id} → ${a.generates} (skill: ${a.skill})`);
+        }
+      }
+    }
+  } else if (reqId) {
+    if (isNext) {
+      const actions = getNextActions(reqId);
+      for (const a of actions) {
+        console.log(`${a.id}:${a.skill}`);
+      }
+    } else {
+      const status = getWorkflowStatus(reqId);
+      if (isJson) {
+        console.log(JSON.stringify(status, null, 2));
+      } else {
+        console.log(formatWorkflowStatus(status));
+      }
+    }
+  } else {
+    console.error('错误: 需要指定 REQ-ID 或使用 --project');
+    process.exit(1);
+  }
+}

package/.claude/settings.json

@@ -60,6 +60,15 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use-guardrail.sh"
           }
         ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ts-node $CLAUDE_PROJECT_DIR/.claude/hooks/inject-agent-context.ts"
+          }
+        ]
       }
     ],
     "Stop": [
@@ -71,6 +80,16 @@
           }
         ]
       }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ts-node $CLAUDE_PROJECT_DIR/.claude/hooks/ralph-loop.ts"
+          }
+        ]
+      }
     ]
   }
 }