cc-devflow 4.2.0 → 4.4.1

package/.claude/docs/design/prd-version-management-design.md

@@ -1,437 +0,0 @@
-# PRD 版本管理系统设计
-
-> **设计目标**: 建立追踪 PRD 变更历史和影响分析的完整系统
-> **创建时间**: 2025-01-20
-> **版本**: v1.0
-
-## 📋 概述
-
-基于 spec-kit 的规格驱动理念，为 cc-devflow 建立完整的 PRD 版本管理体系，支持：
-- PRD 文档版本化 (v1.0, v1.1, v2.0...)
-- 变更影响分析报告
-- 规格变更触发的重新评估机制
-- 向后兼容性检查
-
-## 🎯 核心目标
-
-### 主要功能
-1. **自动版本化**: PRD 变更时自动创建新版本
-2. **变更追踪**: 详细记录每次变更的内容和原因
-3. **影响分析**: 分析变更对现有实现的影响
-4. **回滚支持**: 支持回滚到历史版本
-5. **兼容性检查**: 检查新版本与现有实现的兼容性
-
-### 设计原则
-- **增量式管理**: 支持语义化版本控制 (SemVer)
-- **变更透明**: 每次变更都有清晰的记录和说明
-- **影响预测**: 在变更前预测可能的影响范围
-- **自动化优先**: 减少手动维护工作
-
-## 🏗 架构设计
-
-### 文件结构
-```text
-devflow/requirements/${reqId}/
-├── PRD.md                           # 当前版本 PRD
-├── versions/                        # 版本历史
-│   ├── v1.0/
-│   │   ├── PRD.md                  # v1.0 版本快照
-│   │   ├── CHANGELOG.md            # v1.0 变更日志
-│   │   └── IMPACT_ANALYSIS.md      # 影响分析报告
-│   ├── v1.1/
-│   │   ├── PRD.md
-│   │   ├── CHANGELOG.md
-│   │   └── IMPACT_ANALYSIS.md
-│   └── v2.0/
-│       ├── PRD.md
-│       ├── CHANGELOG.md
-│       └── IMPACT_ANALYSIS.md
-├── VERSION_HISTORY.md               # 完整版本历史
-├── COMPATIBILITY_MATRIX.md          # 兼容性矩阵
-└── upgrade/                         # 升级工具和脚本
-    ├── migration_guide.md           # 迁移指南
-    └── compatibility_check.json     # 兼容性检查结果
-```
-
-### 版本控制策略
-
-#### 语义化版本控制
-```yaml
-版本格式: MAJOR.MINOR.PATCH
-
-MAJOR (主版本):
-  - 破坏性变更
-  - 核心用户故事删除或重大修改
-  - API 接口不兼容变更
-
-MINOR (次版本):
-  - 新增功能
-  - 新增用户故事
-  - 向后兼容的功能增强
-
-PATCH (修订版):
-  - Bug 修复
-  - 文档更新
-  - 澄清性修改
-```
-
-#### 自动版本检测算法
-```yaml
-变更分析:
-  user_story_changes:
-    - added_stories: count
-    - removed_stories: count
-    - modified_stories: count
-
-  acceptance_criteria_changes:
-    - breaking_changes: count
-    - new_requirements: count
-    - clarifications: count
-
-  non_functional_changes:
-    - performance_requirements: modified
-    - security_requirements: modified
-    - integration_requirements: modified
-
-版本判定:
-  if removed_stories > 0 OR breaking_changes > 0:
-    version_type: MAJOR
-  elif added_stories > 0 OR new_requirements > 0:
-    version_type: MINOR
-  else:
-    version_type: PATCH
-```
-
-## 🔧 实现方案
-
-### 1. 版本管理核心组件
-
-#### 版本检测器 (Version Detector)
-```yaml
-职责:
-  - 比较新旧 PRD 内容
-  - 识别变更类型和级别
-  - 自动确定版本号
-
-输入:
-  - 当前 PRD 内容
-  - 新的 PRD 内容
-  - 历史版本信息
-
-输出:
-  - 建议版本号
-  - 变更摘要
-  - 影响评估
-```
-
-#### 影响分析器 (Impact Analyzer)
-```yaml
-职责:
-  - 分析变更对现有实现的影响
-  - 识别需要更新的代码模块
-  - 评估测试覆盖影响
-
-分析维度:
-  - API 接口变更
-  - 数据模型变更
-  - 业务流程变更
-  - 非功能需求变更
-  - 依赖关系变更
-```
-
-#### 兼容性检查器 (Compatibility Checker)
-```yaml
-职责:
-  - 检查新版本与现有实现的兼容性
-  - 生成兼容性报告
-  - 提供迁移建议
-
-检查类型:
-  - 向后兼容性
-  - 向前兼容性
-  - 数据兼容性
-  - API 兼容性
-```
-
-### 2. 升级工作流
-
-#### /flow-upgrade 命令
-```bash
-# 分析当前 PRD 并建议版本升级
-/flow-upgrade "REQ-123" --analyze
-
-# 执行版本升级
-/flow-upgrade "REQ-123" --version="2.0" --reason="添加移动端支持"
-
-# 回滚到指定版本
-/flow-upgrade "REQ-123" --rollback="v1.2"
-```
-
-#### 升级流程
-```yaml
-Phase 1 - 变更分析:
-  1. 读取当前 PRD 和历史版本
-  2. 执行差异分析
-  3. 生成变更摘要
-  4. 建议版本号
-
-Phase 2 - 影响评估:
-  1. 分析代码库中相关实现
-  2. 识别需要更新的文件
-  3. 评估测试影响
-  4. 生成影响分析报告
-
-Phase 3 - 版本创建:
-  1. 创建新版本目录
-  2. 保存 PRD 快照
-  3. 生成变更日志
-  4. 更新版本历史
-
-Phase 4 - 后续处理:
-  1. 触发相关代码更新流程
-  2. 更新测试用例
-  3. 生成迁移指南
-  4. 通知相关团队
-```
-
-### 3. 变更追踪机制
-
-#### 变更日志格式
-```markdown
-# PRD 变更日志 - v2.1
-
-> **版本**: v2.1.0
-> **发布日期**: 2025-01-20T14:30:00Z
-> **变更类型**: MINOR
-
-## 🆕 新增功能
-- **US-007**: 移动端用户登录支持
-  - 添加触摸 ID 认证选项
-  - 支持设备记住登录状态
-
-## 🔄 功能变更
-- **US-003**: 用户注册流程优化
-  - 简化注册步骤从 5 步减至 3 步
-  - 移除中间确认页面
-
-## 🔧 技术需求变更
-- **性能要求**: 登录响应时间从 <2s 调整为 <1s
-- **安全要求**: 新增设备指纹验证
-
-## 📊 影响分析
-- **前端代码**: 需要更新登录组件 (3 个文件)
-- **后端 API**: 需要新增移动端认证接口
-- **测试用例**: 需要增加 12 个新测试用例
-- **预估工作量**: 8-12 工作小时
-
-## 🔗 相关链接
-- [完整影响分析报告](./IMPACT_ANALYSIS.md)
-- [兼容性检查结果](../upgrade/compatibility_check.json)
-- [迁移指南](../upgrade/migration_guide.md)
-```
-
-#### 自动变更检测
-```yaml
-监控机制:
-  - PRD 文件修改检测
-  - Git commit 钩子集成
-  - 定期一致性检查
-
-触发条件:
-  - PRD.md 文件内容变更
-  - 用户手动触发升级
-  - 依赖需求变更
-
-处理策略:
-  - 自动创建变更提案
-  - 等待用户确认
-  - 执行版本升级流程
-```
-
-## 🔍 影响分析框架
-
-### 分析维度
-
-#### 1. 功能影响分析
-```yaml
-用户故事变更:
-  - 新增: 需要新的代码实现
-  - 修改: 需要更新现有代码
-  - 删除: 需要清理相关代码
-
-验收标准变更:
-  - 性能指标变化
-  - 安全要求调整
-  - 集成接口修改
-```
-
-#### 2. 技术影响分析
-```yaml
-代码影响:
-  - 前端组件 (React/Vue 组件)
-  - 后端服务 (API 接口)
-  - 数据库模式 (表结构/索引)
-  - 配置文件 (环境配置)
-
-测试影响:
-  - 单元测试更新
-  - 集成测试调整
-  - E2E 测试修改
-  - 性能测试更新
-```
-
-#### 3. 运维影响分析
-```yaml
-部署影响:
-  - 数据库迁移脚本
-  - 配置更新需求
-  - 服务重启要求
-  - 监控指标调整
-
-运行时影响:
-  - 性能指标变化
-  - 资源使用调整
-  - 监控告警更新
-  - 备份策略修改
-```
-
-### 影响评估算法
-```yaml
-影响权重计算:
-  breaking_changes_weight: 0.4
-  new_features_weight: 0.3
-  performance_changes_weight: 0.2
-  documentation_changes_weight: 0.1
-
-影响级别:
-  HIGH (>0.7): 需要项目经理审批
-  MEDIUM (0.3-0.7): 需要技术负责人审批
-  LOW (<0.3): 可以直接执行
-
-工作量估算:
-  基于历史数据和变更复杂度
-  考虑团队技能和项目熟悉度
-  包含测试和文档更新时间
-```
-
-## 📊 兼容性检查
-
-### 检查类型
-
-#### 1. API 兼容性
-```yaml
-向后兼容性:
-  - 接口签名未变更
-  - 响应格式保持一致
-  - 错误码保持稳定
-
-数据兼容性:
-  - 数据库模式兼容
-  - 数据迁移路径清晰
-  - 历史数据可访问
-```
-
-#### 2. 功能兼容性
-```yaml
-用户体验:
-  - 核心用户流程保持
-  - 界面交互一致性
-  - 性能不显著下降
-
-集成兼容性:
-  - 第三方集成稳定
-  - 内部服务接口兼容
-  - 消息格式保持
-```
-
-### 兼容性矩阵
-```yaml
-兼容性级别:
-  FULLY_COMPATIBLE: 完全兼容，无需任何变更
-  BACKWARD_COMPATIBLE: 向后兼容，旧版本客户端可正常工作
-  MIGRATION_REQUIRED: 需要迁移，提供自动迁移工具
-  BREAKING_CHANGE: 破坏性变更，需要手动处理
-
-检查结果格式:
-  version_from: v1.2
-  version_to: v2.0
-  compatibility_level: MIGRATION_REQUIRED
-  affected_components: [frontend, api, database]
-  migration_tools: [schema_migration, api_adapter]
-  estimated_effort: 16_hours
-```
-
-## 🔄 自动化集成
-
-### Git 钩子集成
-```bash
-# .git/hooks/pre-commit
-#!/bin/bash
-# 检查 PRD 变更并自动创建版本
-
-if [[ $(git diff --cached --name-only) == *"PRD.md"* ]]; then
-    echo "检测到 PRD 变更，执行版本分析..."
-    /flow-upgrade $(extract_req_id) --analyze --auto
-fi
-```
-
-### CI/CD 集成
-```yaml
-# .github/workflows/prd-version-check.yml
-name: PRD Version Management
-on:
-  pull_request:
-    paths: ['devflow/requirements/**/PRD.md']
-
-jobs:
-  version-check:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Analyze PRD Changes
-        run: |
-          /flow-upgrade ${{ env.REQ_ID }} --analyze --format=json > impact.json
-
-      - name: Comment PR with Impact Analysis
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const impact = require('./impact.json');
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: generateImpactComment(impact)
-            });
-```
-
-## 🎯 验收标准
-
-### 功能验收
-- [x] PRD 变更能够自动版本化
-- [x] 变更影响分析准确度 > 85%
-- [x] 支持回滚到历史版本
-- [x] 兼容性检查覆盖主要风险点
-- [x] 版本升级流程文档完整
-
-### 技术验收
-- [x] 版本管理不影响现有工作流性能
-- [x] 支持并发安全的版本操作
-- [x] 历史版本存储优化，避免空间浪费
-- [x] 与现有 git 工作流良好集成
-
-### 用户体验验收
-- [x] 版本升级过程对用户透明
-- [x] 提供清晰的变更摘要和影响说明
-- [x] 支持一键回滚操作
-- [x] 错误提示信息清晰易懂
-
-## 📚 相关文档
-
-- [/flow-upgrade 命令文档](./../commands/flow-upgrade.md)
-- [版本管理最佳实践](./../docs/best-practices/version-management.md)
-- [影响分析算法详解](./../docs/algorithms/impact-analysis.md)
-- [兼容性检查指南](./../docs/guides/compatibility-checking.md)
-
----
-
-**核心价值**: PRD 版本管理系统为 cc-devflow 提供了规格演进的完整支持，确保需求变更的可追踪性和影响可控性，这是实现真正的 Specification-Driven Development 的关键基础设施。

package/.claude/docs/guides/INIT_TROUBLESHOOTING.md

@@ -1,117 +0,0 @@
-# Flow-Init Troubleshooting Guide
-
-> Quick reference for `/flow:init` errors and recovery
-
----
-
-## Core Errors
-
-### E1: Invalid REQ_ID Format
-```bash
-❌ ERROR: REQ_ID format invalid
-```
-**Fix**: 使用格式 `REQ-123` 或 `BUG-456`（`^(REQ|BUG)-[0-9]+$`）
-
----
-
-### E2: REQ_ID Already Exists
-```bash
-❌ ERROR: devflow/requirements/REQ-123/ already exists
-```
-**Fix**: 使用不同 ID 或 `/flow:init "REQ-123|..." --force` 强制覆盖
-
----
-
-### E3: Git Status Not Clean
-```bash
-❌ ERROR: Git working directory has uncommitted changes
-```
-**Fix**: `git status` → `git commit` 或 `git stash`
-
----
-
-### E4: Research Validation Failed
-```bash
-❌ ERROR: research.md validation failed (incomplete)
-```
-**Diagnose**: `grep -c "Decision:" devflow/requirements/REQ-123/research/research.md`
-**Fix**: 手动补充 research.md Decision blocks 或重新运行 research 步骤
-
----
-
-### E5: MCP Fetch Failed
-```bash
-⚠️ WARNING: MCP fetch timed out (Context7)
-```
-**Fix**: 继续执行但标记 `research/mcp/` 下的待补项，稍后手动补充
-
----
-
-## Recovery Procedures
-
-### Complete Restart
-```bash
-rm -rf devflow/requirements/REQ-123/
-git branch -D feature/REQ-123-*
-/flow:init "REQ-123|Title|URLs"
-```
-
-### Recover from Interruption
-```bash
-# 检查当前状态
-cat devflow/requirements/REQ-123/orchestration_status.json | jq '.phase0_complete'
-
-# 如果 false，补充研究材料
-# 手动编辑 research/research.md → 添加 Decision blocks
-
-# 更新状态
-jq '.phase0_complete = true' devflow/requirements/REQ-123/orchestration_status.json > tmp.json
-mv tmp.json devflow/requirements/REQ-123/orchestration_status.json
-
-# 继续下一阶段
-/flow:spec "REQ-123"
-```
-
-### Rebuild Research.md from Tasks.json
-```bash
-REQ_DIR="devflow/requirements/REQ-123"
-
-# 从 tasks.json 生成 research.md
-bash .claude/scripts/consolidate-research.sh "$REQ_DIR"
-
-# 验证
-bash .claude/scripts/validate-research.sh "$REQ_DIR"
-```
-
----
-
-## Configuration
-
-### Environment Variables
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `SKIP_MCP_RESEARCH` | `false` | 跳过外部 MCP 材料抓取 |
-| `REQUIRE_CLEAN_GIT` | `true` | 要求 Git 状态干净 |
-
-### Command-Line Flags
-```bash
-/flow:init "REQ-123|..." --force        # 强制覆盖现有需求
-/flow:init --interactive                # 交互式输入模式
-```
-
----
-
-## FAQ
-
-**Q: 如何跳过 MCP 研究阶段？**
-A: `SKIP_MCP_RESEARCH=1 /flow:init "REQ-123|..."`
-
-**Q: Context Loading 阶段找不到 ROADMAP.md 怎么办？**
-A: 可选步骤，不影响执行。如需路线图，先运行 `/core-roadmap`
-
-**Q: Research.md 格式要求？**
-A: 至少包含 1 个 `### Decision:` block，每个 block 有 Rationale/Alternatives/Source
-
----
-
-**Last Updated**: 2025-12-19

package/.claude/docs/guides/NEW_TROUBLESHOOTING.md

@@ -1,99 +0,0 @@
-# Mainline Troubleshooting Guide
-
-> Quick reference for canonical `/flow:*` delivery errors and recovery.
-
----
-
-## Core Errors
-
-### E1: Stage Command Not Found
-```bash
-❌ ERROR: Command /flow:init not found
-```
-**Fix**: 检查 `.claude/commands/flow/` 是否完整；确认当前分支已同步最新命令目录。
-
-### E2: Status File Corrupted
-```bash
-❌ ERROR: Invalid orchestration_status.json
-```
-**Diagnose**: `jq . devflow/requirements/REQ-123/orchestration_status.json`
-**Fix**: 重建状态文件后执行 `/flow:status "REQ-123"` 并从建议阶段恢复。
-
-### E3: Interrupted, Cannot Resume
-```bash
-❌ ERROR: development_in_progress but checkpoint missing
-```
-**Diagnose**: `/flow:status "REQ-123"`
-**Fix**: `/flow:dev "REQ-123" --resume`
-
-### E4: Task Manifest Missing
-```bash
-❌ ERROR: TASKS.md not found
-```
-**Fix**: 重新执行 `/flow:spec "REQ-123"` 生成规划产物。
-
-### E5: Verify Gate Failure
-```bash
-❌ Coverage below threshold
-❌ High severity security issue
-```
-**Fix**:
-- 修复代码与测试后重跑 `/flow:verify "REQ-123" --strict`
-- 通过后再执行 `/flow:release "REQ-123"`
-
-### E6: Release Blocked
-```bash
-❌ Missing strict verify report-card
-```
-**Fix**: 先执行 `/flow:verify "REQ-123" --strict`，再执行 `/flow:release "REQ-123"`。
-
----
-
-## Recovery Procedures
-
-### Full Rebuild
-```bash
-rm -rf devflow/requirements/REQ-123/
-/flow:init "REQ-123|Title|URLs"
-/flow:spec "REQ-123"
-/flow:dev "REQ-123"
-/flow:verify "REQ-123" --strict
-```
-
-### Resume From Current Stage
-```bash
-/flow:status "REQ-123"
-/flow:dev "REQ-123" --resume
-```
-
-### State File Rebuild (Minimal)
-```bash
-REQ_DIR="devflow/requirements/REQ-123"
-cat > "$REQ_DIR/orchestration_status.json" <<EOF_JSON
-{
-  "reqId": "REQ-123",
-  "status": "spec_complete",
-  "phase": "planning",
-  "spec_complete": true,
-  "development_complete": false,
-  "quality_complete": false,
-  "release_complete": false
-}
-EOF_JSON
-
-jq . "$REQ_DIR/orchestration_status.json"
-/flow:status "REQ-123"
-```
-
----
-
-## FAQ
-
-**Q: 如何从特定阶段重启？**  
-A: 用 `/flow:status` 先确认状态，然后执行对应阶段命令（通常是 `/flow:dev --resume` 或 `/flow:verify --strict`）。
-
-**Q: 什么时候需要重跑 `/flow:spec`？**  
-A: `TASKS.md` 缺失、规格有重大变更、或 manifest 与实现明显漂移时。
-
-**Q: 可以继续使用 `/flow-new` 吗？**  
-A: 不建议。`/flow-new` 仅兼容保留，主链是 `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release`。