cc-devflow 4.2.0 → 4.4.1

package/.claude/docs/guides/ROADMAP_TROUBLESHOOTING.md

@@ -1,188 +0,0 @@
-# Core-Roadmap Troubleshooting Guide
-
-> Quick reference for `/core-roadmap` dialogue errors and recovery
-
----
-
-## Core Errors
-
-### E1: User Cancel During Dialogue
-```bash
-用户输入: cancel
-→ 对话取消
-```
-**Fix**: `/core-roadmap --resume` → 从草稿恢复，选择继续的 Stage
-
----
-
-### E2: Circular Dependency Detected
-```bash
-❌ ERROR: 检测到循环依赖: RM-001 → RM-003 → RM-005 → RM-001
-```
-**Fix**: 用户输入 `modify` → 移除循环中的一条依赖边（如 `remove RM-005 → RM-001`）
-
----
-
-### E3: Over-Capacity Warning
-```bash
-⚠️ WARNING: 总工作量 150% (计划 18 项 vs 容量 12 项)
-```
-**Fix**:
-- 降低优先级: 将部分 P2 改为 P3
-- 缩减工作量: 重新评估项目估算
-- 延长规划周期: 从 3 个月延长到 6 个月
-
----
-
-### E4: Roadmap Not Found (Update Mode)
-```bash
-❌ ERROR: devflow/ROADMAP.md 不存在
-```
-**Fix**: `find . -name "ROADMAP.md"` → 检查路径 → 移动到正确位置或重新创建
-
----
-
-### E5: Hanging Dependency (未完成的依赖)
-```bash
-⚠️ WARNING: RM-005 依赖 REQ-008 但该需求未完成
-```
-**Fix**: `/flow:status REQ-008` → 确认状态 → 继续但标记风险 或 移除该依赖
-
----
-
-### E6: Quarter Assignment Conflict
-```bash
-❌ ERROR: RM-005 分配到 Q1 但其依赖 RM-001 分配到 Q2
-```
-**Fix**: 调整 RM-005 到 Q2 或提前 RM-001 到 Q1
-
----
-
-### E7: Agent Invocation Failed
-```bash
-❌ ERROR: roadmap-planner execution failed (Cannot read property 'candidates')
-```
-**Diagnose**: `cat .roadmap-context.json | jq .` → 检查 context 完整性
-**Fix**: `cp .roadmap-draft.json .roadmap-context.json` → `/core-roadmap --regenerate`
-
----
-
-### E8: Mermaid Syntax Error
-```bash
-⚠️ WARNING: Mermaid syntax error (Node ID: REQ-001 包含非法字符)
-```
-**Fix**: 编辑 ROADMAP.md → 将 `REQ-001[...]` 改为 `REQ001[REQ-001: ...]` (移除 Node ID 中的 hyphen)
-
----
-
-### E9: Architecture Generation Failed
-```bash
-❌ ERROR: Cannot generate ARCHITECTURE.md (No requirements found)
-```
-**Fix**: 跳过 ARCHITECTURE.md 生成，完成第一个需求后运行 `/core-architecture`
-
----
-
-## Recovery Scenarios
-
-### 对话中断恢复
-```bash
-# 检查草稿文件
-cat .roadmap-draft.json | jq '.candidates | length'
-
-# 恢复对话
-/core-roadmap --resume
-
-# 选择从哪个阶段继续 (2: 头脑风暴, 3: 依赖分析, ...)
-```
-
-### 生成文档损坏
-```bash
-# 备份损坏文件
-cp devflow/ROADMAP.md devflow/ROADMAP.md.bak
-
-# 重新生成 (使用保存的 context)
-/core-roadmap --regenerate
-
-# 对比新旧文件
-diff devflow/ROADMAP.md.bak devflow/ROADMAP.md
-```
-
-### Velocity 数据错误
-```bash
-# 验证完成需求数量
-ls devflow/requirements/REQ-*/orchestration_status.json | \
-  xargs -I {} jq -r 'select(.status=="merged") | .reqId' {} | \
-  wc -l
-
-# 在对话中手动修正容量估算
-```
-
----
-
-## Advanced Features
-
-### --regenerate 模式
-```bash
-/core-roadmap --regenerate
-
-# 执行步骤:
-# 1. 读取现有 ROADMAP.md
-# 2. 运行 sync-roadmap-progress.sh
-# 3. 更新 Velocity 指标
-# 4. 重新生成文档
-
-# 适用场景:
-# - 定期更新路线图进度 (每周)
-# - 需求完成后同步状态
-```
-
-### --resume 模式
-```bash
-/core-roadmap --resume
-
-# 执行步骤:
-# 1. 读取 .roadmap-draft.json
-# 2. 恢复 context 状态
-# 3. 询问从哪个 Stage 继续
-# 4. 跳转到对应 Stage
-
-# 适用场景:
-# - 对话被意外中断
-# - 需要暂停并稍后继续
-# - 需要修改之前阶段的输入
-```
-
----
-
-## Configuration
-
-### Environment Variables
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ROADMAP_DRAFT_FILE` | `.roadmap-draft.json` | 草稿文件路径 |
-| `DEFAULT_PLANNING_HORIZON` | `3 months` | 默认规划周期 |
-| `FLOW_DEBUG` | `false` | 启用调试日志 |
-
-### Scripts
-| Script | Purpose |
-|--------|---------|
-| `calculate-quarter.sh` | 计算当前季度信息 |
-| `sync-roadmap-progress.sh` | 同步路线图进度 |
-
----
-
-## FAQ
-
-**Q: 如何修改已生成的路线图？**
-A: 手动编辑 `vim devflow/ROADMAP.md` 或重新运行 `/core-roadmap`
-
-**Q: 如何添加新的 RM 项目？**
-A: 编辑 ROADMAP.md 或重新运行对话并在 Stage 3 添加
-
-**Q: Velocity 计算不准确怎么办？**
-A: 在对话 Stage 0 中会显示预估容量，如不准确可在后续阶段调整工作量和时间线
-
----
-
-**Last Updated**: 2025-12-19

package/.claude/docs/guides/TASK_COMPLETION_MARKING.md

@@ -1,338 +0,0 @@
-# 任务完成标记指南
-
-## 问题描述
-
-在执行 `/flow:dev` 时，主代理完成了代码实现，但没有同步更新 TASKS.md 中的待办事项复选框。这导致：
-
-- ❌ TASKS.md 显示任务未完成 `[ ]`，但代码已经实现
-- ❌ 进度追踪不准确，无法知道真实进度
-- ❌ 可能重复执行已完成的任务
-- ❌ 无法正确生成状态报告
-
-## 解决方案
-
-### 1. 强制执行标记流程
-
-在 `/flow:dev` 命令文档中，已经强化了任务完成标记的要求：
-
-```bash
-# 每完成一个任务后，必须立即执行
-bash .claude/scripts/mark-task-complete.sh T001
-```
-
-**关键点**：
-- ⚠️ **MANDATORY** - 不是可选的
-- 每个任务完成后立即执行
-- 不要手动编辑 TASKS.md
-- 验证输出显示 "✅ Task T001 marked as complete"
-
-### 2. 使用诊断工具
-
-新增的 `sync-task-marks.sh` 脚本可以帮助检测和修复未标记的任务：
-
-```bash
-# 检查哪些任务已执行但未标记
-bash .claude/scripts/sync-task-marks.sh --dry-run
-
-# 交互式修复（推荐）
-bash .claude/scripts/sync-task-marks.sh
-
-# 批量自动标记（谨慎使用）
-bash .claude/scripts/sync-task-marks.sh --auto-mark
-```
-
-### 3. 工作流集成
-
-#### 阶段 1: 任务执行循环
-
-```text
-For each task in TASKS.md:
-  1. Load task details
-  2. Display task information
-  3. Execute task implementation (写代码)
-  4. Verify task completion (DoD check)
-  5. ⚠️ MANDATORY: Mark task as complete
-     → bash .claude/scripts/mark-task-complete.sh ${task_id}
-  6. Continue to next task
-```
-
-#### 阶段 2: Exit Gate 验证
-
-```bash
-# 验证所有任务都已标记完成
-bash .claude/scripts/check-task-status.sh --json
-
-# 如果发现任务未标记
-bash .claude/scripts/sync-task-marks.sh --dry-run
-# 手动执行每个任务的标记命令
-```
-
-## 完整示例
-
-### 场景 1: 正常工作流
-
-```bash
-# 1. 开始开发
-/flow:dev "REQ-123"
-
-# 2. Claude 完成任务 T001
-#    (写代码、运行测试等)
-
-# 3. ⚠️ 立即标记任务完成
-bash .claude/scripts/mark-task-complete.sh T001
-# 输出: ✅ Task T001 marked as complete
-#       Progress: 1 completed, 9 remaining
-#       Overall: 10% complete
-
-# 4. 继续下一个任务 T002
-# ...重复步骤 2-3
-```
-
-### 场景 2: 发现任务未标记
-
-```bash
-# 1. 发现问题：代码已实现，但 TASKS.md 显示 [ ]
-$ cat devflow/requirements/REQ-123/TASKS.md
-## Phase 2: Tests First
-- [ ] **T003** Write user creation test  # ← 代码已经写了，但未标记
-
-# 2. 运行诊断脚本
-$ bash .claude/scripts/sync-task-marks.sh --dry-run
-
-🔍 Checking task completion status for REQ-123...
-
-Task Summary:
-  Total tasks:     10
-  Completed:       2
-  Remaining:       8
-
-⚠️  Uncompleted tasks (still marked as [ ]):
-  [ ] T003: - [ ] **T003** Write user creation test
-  [ ] T004: - [ ] **T004** Write login test
-  ...
-
-🔍 DRY RUN - No changes will be made
-
-To mark these tasks as complete, run:
-  bash .claude/scripts/mark-task-complete.sh T003
-  bash .claude/scripts/mark-task-complete.sh T004
-  ...
-
-# 3. 手动执行标记命令
-bash .claude/scripts/mark-task-complete.sh T003
-bash .claude/scripts/mark-task-complete.sh T004
-
-# 或使用交互式模式
-$ bash .claude/scripts/sync-task-marks.sh
-What would you like to do?
-
-1. Show commands to manually mark each task
-2. Mark all tasks as complete now (auto-mark)
-3. Exit without changes
-
-Choose [1-3]: 1
-```
-
-### 场景 3: 批量修复（谨慎使用）
-
-```bash
-# 仅在确定所有任务都已完成时使用
-bash .claude/scripts/sync-task-marks.sh --auto-mark
-
-⚠️  AUTO-MARK mode enabled - marking all tasks as complete...
-
-Marking T003...
-✅ Task T003 marked as complete
-Marking T004...
-✅ Task T004 marked as complete
-...
-
-✅ All tasks marked as complete
-```
-
-## 脚本 API
-
-### mark-task-complete.sh
-
-标记单个任务为完成状态。
-
-**用法**:
-```bash
-bash .claude/scripts/mark-task-complete.sh TASK_ID [OPTIONS]
-```
-
-**参数**:
-- `TASK_ID`: 任务ID (如 T001, T002)
-
-**选项**:
-- `--json`: JSON 格式输出
-- `--no-log`: 不记录到 EXECUTION_LOG.md
-- `--help`: 显示帮助
-
-**返回值**:
-- `0`: 成功标记
-- `1`: 错误（任务不存在、已完成等）
-
-**示例**:
-```bash
-# 标记 T001 为完成
-bash .claude/scripts/mark-task-complete.sh T001
-
-# JSON 输出
-bash .claude/scripts/mark-task-complete.sh T005 --json
-
-# 不记录日志
-bash .claude/scripts/mark-task-complete.sh T010 --no-log
-```
-
-### sync-task-marks.sh
-
-诊断和修复未标记的任务。
-
-**用法**:
-```bash
-bash .claude/scripts/sync-task-marks.sh [OPTIONS]
-```
-
-**选项**:
-- `--dry-run`: 只显示要做什么，不实际修改
-- `--auto-mark`: 自动标记所有任务（危险）
-- `--help`: 显示帮助
-
-**返回值**:
-- `0`: 成功或所有任务已完成
-- `1`: 错误（无需求ID、目录不存在等）
-
-**示例**:
-```bash
-# 检查状态（推荐先运行）
-bash .claude/scripts/sync-task-marks.sh --dry-run
-
-# 交互式修复
-bash .claude/scripts/sync-task-marks.sh
-
-# 批量自动标记
-bash .claude/scripts/sync-task-marks.sh --auto-mark
-```
-
-## 最佳实践
-
-### DO ✅
-
-1. **立即标记**: 完成任务后立即执行 `mark-task-complete.sh`
-2. **使用脚本**: 始终用脚本，不要手动编辑 TASKS.md
-3. **验证输出**: 检查脚本输出确认标记成功
-4. **定期检查**: 在开发过程中定期运行 `sync-task-marks.sh --dry-run`
-5. **Exit Gate**: 在 `/flow:dev` 结束前验证所有任务已标记
-
-### DON'T ❌
-
-1. **手动编辑**: 不要直接修改 TASKS.md 的复选框
-2. **批量操作**: 不要等到所有任务完成后再批量标记
-3. **跳过验证**: 不要忽略脚本输出或进度信息
-4. **盲目 auto-mark**: 不要在未确认任务完成时使用 `--auto-mark`
-5. **忽略错误**: 如果标记失败，必须立即调查原因
-
-## 常见问题
-
-### Q: 为什么要使用脚本而不是手动编辑？
-
-**A**: 脚本提供：
-- ✅ 标准化的格式（避免手动编辑错误）
-- ✅ 自动记录到 EXECUTION_LOG.md
-- ✅ 更新 orchestration_status.json
-- ✅ 实时进度反馈
-- ✅ 错误检查和验证
-
-### Q: 如果任务已经标记为完成，再次运行会怎样？
-
-**A**: 脚本会检测到并提示：
-```bash
-$ bash .claude/scripts/mark-task-complete.sh T001
-Task T001 is already marked as complete
-```
-
-### Q: sync-task-marks.sh 如何知道任务是否真的完成了？
-
-**A**: 它只检查 TASKS.md 中的复选框状态。实际验证任务是否完成需要：
-- 检查代码文件是否存在
-- 运行测试验证功能
-- 人工 review
-
-使用 `--dry-run` 先检查，然后手动确认每个任务再标记。
-
-### Q: 什么时候使用 --auto-mark？
-
-**A**: 只在以下情况：
-- 100% 确定所有显示为 `[ ]` 的任务都已完成
-- 需要快速修复遗留的标记问题
-- 有完整的 Git 历史可以回滚
-
-**推荐**: 使用交互式模式，逐个确认每个任务。
-
-## 技术实现
-
-### mark-task-complete.sh 工作原理
-
-```bash
-# 1. 解析任务ID (T001 → T001)
-TASK_ID=$(echo "$TASK_ID" | tr '[:lower:]' '[:upper:]')
-
-# 2. 验证格式 (T\d+)
-[[ "$TASK_ID" =~ ^T[0-9]+$ ]]
-
-# 3. 查找任务行
-grep -q "\\[ \\] .*$TASK_ID" "$TASKS_FILE"
-
-# 4. 替换复选框 ([ ] → [x])
-sed "s/- \[ \] \(\*\*\)\{0,1\}$TASK_ID\(\*\*\)\{0,1\}/- [x] \1$TASK_ID\2/" "$TASKS_FILE"
-
-# 5. 记录事件
-log_event "$REQ_ID" "✅ Task $TASK_ID marked as complete"
-```
-
-### sync-task-marks.sh 工作原理
-
-```bash
-# 1. 统计任务
-TOTAL_TASKS=$(grep -c "^- \[ \]" "$TASKS_FILE")
-COMPLETED_TASKS=$(grep -c "^- \[x\]" "$TASKS_FILE")
-
-# 2. 提取未完成任务ID
-while IFS= read -r line; do
-    if [[ "$line" =~ \*\*T([0-9]+)\*\* ]]; then
-        task_id="T${BASH_REMATCH[1]}"
-        UNCOMPLETED+=("$task_id")
-    fi
-done < <(grep "^- \[ \]" "$TASKS_FILE")
-
-# 3. 显示或执行标记
-for task_id in "${UNCOMPLETED[@]}"; do
-    bash mark-task-complete.sh "$task_id"
-done
-```
-
-## 集成测试
-
-新增的测试套件 `test_sync_task_marks.sh` 验证：
-
-- ✅ Help 消息显示
-- ✅ 无需求ID时的错误处理
-- ✅ 需求目录不存在的错误处理
-- ✅ TASKS.md 不存在的错误处理
-- ✅ 所有任务已完成的场景
-- ✅ 列出未完成任务
-- ✅ Dry-run 模式显示命令
-
-运行测试：
-```bash
-bash .claude/tests/scripts/test_sync_task_marks.sh
-```
-
-## 相关文档
-
-- [mark-task-complete.sh 源码](.claude/scripts/mark-task-complete.sh)
-- [sync-task-marks.sh 源码](.claude/scripts/sync-task-marks.sh)
-- [/flow:dev 命令文档](.claude/commands/flow/dev.md)
-- [TASKS_TEMPLATE.md 模板](.claude/docs/templates/TASKS_TEMPLATE.md)
-- [测试框架](.claude/tests/test-framework.sh)