cc-devflow 4.2.0 → 4.3.0

package/.claude/docs/spec-format-guide.md

@@ -0,0 +1,349 @@
+# CC-DevFlow spec.md Format Guide
+
+> **Version**: v4.3.0
+> **Purpose**: 定义项目级和需求级 spec.md 的格式规范
+
+---
+
+## 核心设计原则
+
+**OpenSpec 复刻**：
+- 项目级 `devflow/specs/` = 不可变源代码真相（描述当前系统状态）
+- 需求级 `requirements/{REQ}/specs/` = Delta（ADDED/MODIFIED/REMOVED/RENAMED）
+- 归档时自动合并 Delta 到项目级
+
+**关键区别**：
+- ❌ 错误理解：每个需求有自己的 spec.md
+- ✅ 正确理解：项目有统一的 specs/，需求通过 Delta 修改它
+
+---
+
+## 项目级 spec.md 格式
+
+### YAML Frontmatter
+
+```yaml
+---
+module: "auth"                      # 模块名称
+created_at: "2026-01-01T10:00:00Z"  # 创建时间
+updated_at: "2026-03-12T15:30:00Z"  # 最后更新时间
+version: "2.1.0"                    # 语义化版本号
+---
+```
+
+### 文档结构
+
+```markdown
+# {Module Name}
+
+## Purpose
+{高层描述：这个模块是干什么的}
+
+## Requirements
+
+### Requirement: {Requirement Name}
+The system {SHALL|MUST|SHOULD|MAY} {behavior description}.
+
+#### Scenario: {Scenario Name}
+- GIVEN {precondition}
+- WHEN {action}
+- THEN {expected result}
+- AND {additional assertion}
+
+### Requirement: {Another Requirement}
+...
+
+## Implementation
+
+### API Endpoints
+- POST /api/auth/login
+- GET /api/auth/verify
+
+### Data Model
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY,
+  email VARCHAR(255) UNIQUE NOT NULL
+);
+```
+
+### Files
+- `src/api/auth/login.ts`
+- `src/middleware/jwt.ts`
+```
+
+### RFC 2119 关键字
+
+| 关键字 | 含义 | 用法 |
+|--------|------|------|
+| SHALL | 必须实现 | 核心功能 |
+| MUST | 强制要求 | 安全/合规 |
+| SHOULD | 推荐实现 | 最佳实践 |
+| MAY | 可选实现 | 增强功能 |
+
+### BDD Scenario 格式
+
+```markdown
+#### Scenario: {场景名称}
+- GIVEN {前置条件}
+- WHEN {触发动作}
+- THEN {预期结果}
+- AND {额外断言}
+```
+
+**示例**：
+```markdown
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits valid email and password
+- THEN a JWT token is issued
+- AND the user is redirected to dashboard
+```
+
+---
+
+## 需求级 Delta spec.md 格式
+
+### YAML Frontmatter
+
+```yaml
+---
+delta_id: "REQ-123"                 # 需求 ID
+module: "auth"                      # 目标模块
+title: "添加 2FA 支持"               # 变更标题
+created_at: "2026-03-12T10:00:00Z"  # 创建时间
+status: "draft"                     # draft | approved | applied
+---
+```
+
+### 文档结构
+
+```markdown
+# Delta: {变更标题}
+
+## Summary
+{为什么需要这个变更？简短说明}
+
+## ADDED Requirements
+
+### Requirement: {New Requirement Name}
+The system SHALL {new behavior}.
+
+#### Scenario: {New Scenario}
+- GIVEN ...
+- WHEN ...
+- THEN ...
+
+## MODIFIED Requirements
+
+### Requirement: {Existing Requirement Name}
+The system SHALL {modified behavior}.
+(Previously: {old behavior})
+
+## REMOVED Requirements
+
+### Requirement: {Removed Requirement Name}
+{说明为什么移除}
+
+## RENAMED Requirements
+
+### Requirement: {Old Name} → {New Name}
+{说明为什么重命名}
+```
+
+### Delta 操作类型
+
+| 操作 | 含义 | 示例 |
+|------|------|------|
+| ADDED | 新增需求 | 添加 2FA 功能 |
+| MODIFIED | 修改现有需求 | 会话超时从 60 分钟改为 30 分钟 |
+| REMOVED | 删除需求 | 移除已废弃的 OAuth 1.0 支持 |
+| RENAMED | 重命名需求 | "User Authentication" → "Multi-Factor Authentication" |
+
+---
+
+## 完整示例
+
+### 项目级 spec.md
+
+```markdown
+---
+module: "auth"
+created_at: "2026-01-01T10:00:00Z"
+updated_at: "2026-03-12T15:30:00Z"
+version: "2.1.0"
+---
+
+# Authentication Module
+
+## Purpose
+Provides secure authentication and session management for the application.
+
+## Requirements
+
+### Requirement: User Login
+The system SHALL allow users to log in with email and password.
+
+#### Scenario: Valid credentials
+- GIVEN a registered user
+- WHEN the user submits valid email and password
+- THEN a JWT token is issued
+- AND the user is redirected to dashboard
+
+#### Scenario: Invalid credentials
+- GIVEN a registered user
+- WHEN the user submits invalid password
+- THEN an error message is displayed
+- AND no token is issued
+
+### Requirement: Session Management
+The system MUST expire sessions after 30 minutes of inactivity.
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass without activity
+- THEN the session is invalidated
+- AND the user must re-authenticate
+
+## Implementation
+
+### API Endpoints
+- POST /api/auth/login
+- POST /api/auth/logout
+- GET /api/auth/verify
+
+### Data Model
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### Files
+- `src/api/auth/login.ts`
+- `src/api/auth/logout.ts`
+- `src/middleware/jwt.ts`
+```
+
+### 需求级 Delta spec.md
+
+```markdown
+---
+delta_id: "REQ-123"
+module: "auth"
+title: "添加 2FA 支持"
+created_at: "2026-03-12T10:00:00Z"
+status: "draft"
+---
+
+# Delta: 添加 2FA 支持
+
+## Summary
+为提高安全性，添加两因素认证支持。用户可选择启用 2FA，登录时需要输入 OTP 验证码。
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login for users with 2FA enabled.
+
+#### Scenario: OTP required
+- GIVEN a user with 2FA enabled
+- WHEN the user submits valid credentials
+- THEN an OTP challenge is presented
+- AND the user must enter a valid OTP code
+
+#### Scenario: OTP validation
+- GIVEN a user has entered valid credentials
+- WHEN the user submits a valid OTP code
+- THEN a JWT token is issued
+- AND the user is redirected to dashboard
+
+#### Scenario: Invalid OTP
+- GIVEN a user has entered valid credentials
+- WHEN the user submits an invalid OTP code
+- THEN an error message is displayed
+- AND the user remains on the OTP challenge page
+
+## MODIFIED Requirements
+
+### Requirement: Session Management
+The system SHALL expire sessions after 30 minutes of inactivity.
+(Previously: 60 minutes)
+
+**Rationale**: 缩短超时时间以提高安全性，配合 2FA 使用。
+
+## REMOVED Requirements
+
+None
+
+## RENAMED Requirements
+
+None
+```
+
+---
+
+## 合并逻辑
+
+归档时，`delta-parser.ts` 自动执行以下操作：
+
+1. **ADDED**: 追加到项目级 spec.md 的 Requirements 章节
+2. **MODIFIED**: 替换项目级 spec.md 中对应的 Requirement
+3. **REMOVED**: 从项目级 spec.md 中删除对应的 Requirement
+4. **RENAMED**: 重命名项目级 spec.md 中的 Requirement 标题
+5. **Version Bump**: 更新项目级 spec.md 的 version 字段
+
+---
+
+## 最佳实践
+
+### 1. 保持 Delta 最小化
+- 只包含本次需求的变更
+- 不要在 Delta 中重复现有内容
+
+### 2. 使用清晰的 Scenario
+- 每个 Scenario 测试一个具体行为
+- 使用 Given-When-Then 格式
+- 避免模糊的描述
+
+### 3. 记录变更原因
+- MODIFIED 时说明为什么修改
+- REMOVED 时说明为什么移除
+- RENAMED 时说明为什么重命名
+
+### 4. 版本号规范
+- ADDED 新功能 → MINOR 版本号 +1
+- MODIFIED 现有功能 → PATCH 版本号 +1
+- REMOVED 功能 → MAJOR 版本号 +1（破坏性变更）
+
+---
+
+## 工具支持
+
+### 生成 Delta
+```bash
+/flow:spec "REQ-123"
+→ 生成 devflow/requirements/REQ-123/specs/{module}/spec.md
+```
+
+### 验证 Delta
+```bash
+/flow:validate-scope "REQ-123"
+→ 检测需求偏移，生成 scope-creep-report.md
+```
+
+### 合并 Delta
+```bash
+/flow:release "REQ-123"
+→ 自动合并 Delta 到 devflow/specs/{module}/spec.md
+→ 更新版本号
+→ 归档需求
+```
+
+---
+
+**Last Updated**: 2026-03-12
+**Version**: v4.3.0

package/.claude/docs/state-consolidation-design.md

@@ -0,0 +1,323 @@
+# State Consolidation Design (Task #10 重新设计)
+
+> **Version**: 1.0.0
+> **Date**: 2026-03-12
+> **Status**: Design Proposal
+
+---
+
+## 问题诊断
+
+### 现象层
+Task #10 原始设计要求创建统一的 `.harness/state.json`，合并：
+- `orchestration_status.json`
+- `session-checklist.json`
+- `session-progress.md`
+- `session-handoff.md`
+
+### 本质层
+这个设计与 v6.0 Harness-First 架构冲突：
+- v6.0 已经实现了**关注点分离**
+- 将所有状态塞入一个文件违反了单一职责原则
+- 真正的问题是**旧文件未被废弃**，而非需要新的统一文件
+
+### 哲学层
+**单一真相源 ≠ 单一文件**
+
+正确的架构：
+```
+harness-state.json     → 生命周期状态 (initialized/released)
+task-manifest.json     → 任务定义与进度 (tasks[].status)
+checkpoint.json        → 会话恢复点 (per task)
+report-card.json       → 质量验证结果
+```
+
+---
+
+## v6.0 当前架构分析
+
+### 1. harness-state.json (核心生命周期)
+```json
+{
+  "changeId": "REQ-123",
+  "goal": "Deliver REQ-123 safely",
+  "status": "initialized|released",
+  "initializedAt": "2026-03-12T10:00:00Z",
+  "releasedAt": "2026-03-12T15:00:00Z",
+  "updatedAt": "2026-03-12T15:00:00Z"
+}
+```
+
+**职责**：
+- 需求的生命周期状态
+- 初始化和发布时间戳
+- 不包含任务细节
+
+### 2. task-manifest.json (任务定义与进度)
+```json
+{
+  "changeId": "REQ-123",
+  "goal": "...",
+  "createdAt": "...",
+  "updatedAt": "...",
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "...",
+      "status": "pending|running|passed|failed",
+      "attempts": 0,
+      "maxRetries": 1,
+      "dependsOn": [],
+      "touches": [],
+      "run": [],
+      "checks": []
+    }
+  ],
+  "metadata": {
+    "source": "TASKS.md",
+    "generatedBy": "harness:plan"
+  }
+}
+```
+
+**职责**：
+- 任务定义（依赖、文件、命令）
+- 任务执行状态（pending/running/passed/failed）
+- 重试次数和错误信息
+- **已经包含了 progress 信息**（completedTasks = tasks.filter(t => t.status === 'passed').length）
+
+### 3. checkpoint.json (会话恢复)
+```json
+{
+  "changeId": "REQ-123",
+  "taskId": "T001",
+  "sessionId": "session-abc123",
+  "status": "passed",
+  "summary": "Task completed successfully",
+  "timestamp": "2026-03-12T10:30:00Z",
+  "attempt": 0
+}
+```
+
+**职责**：
+- 每个任务的检查点
+- 会话恢复信息
+- 任务执行摘要
+
+### 4. report-card.json (质量验证)
+```json
+{
+  "changeId": "REQ-123",
+  "overall": "pass|fail",
+  "quickGates": [...],
+  "strictGates": [...],
+  "review": {...},
+  "blockingFindings": [],
+  "timestamp": "..."
+}
+```
+
+**职责**：
+- 质量门禁结果
+- 阻塞性问题列表
+
+---
+
+## 旧文件映射分析
+
+### orchestration_status.json → 已被替代
+```json
+{
+  "reqId": "REQ-006",
+  "status": "release_complete",        // → harness-state.json: status
+  "phase": "release",                  // → harness-state.json: status
+  "completedSteps": [...],             // → task-manifest.json: tasks[].status
+  "documents": {...},                  // → 文件系统本身就是真相源
+  "research": {...},                   // → 文件系统
+  "createdAt": "...",                  // → harness-state.json: initializedAt
+  "updatedAt": "...",                  // → harness-state.json: updatedAt
+  "prUrl": "..."                       // → 不属于 harness 职责
+}
+```
+
+**结论**：orchestration_status.json 是冗余的，所有信息已在新架构中表达。
+
+### session-checklist.json → 已被替代
+```json
+{
+  "flow:init": { "passes": true },
+  "flow:spec": { "passes": false }
+}
+```
+
+**映射**：
+- `flow:init.passes` → harness-state.json: status === 'initialized'
+- `flow:spec.passes` → task-manifest.json 存在且有效
+
+**结论**：session-checklist.json 是冗余的。
+
+### session-progress.md → 可生成
+```markdown
+## Progress
+- Total Tasks: 6
+- Completed: 2
+- Failed: 0
+```
+
+**映射**：
+```javascript
+const manifest = readJson('task-manifest.json');
+const totalTasks = manifest.tasks.length;
+const completedTasks = manifest.tasks.filter(t => t.status === 'passed').length;
+const failedTasks = manifest.tasks.filter(t => t.status === 'failed').length;
+```
+
+**结论**：session-progress.md 可从 task-manifest.json 实时生成，无需存储。
+
+### session-handoff.md → 可生成
+```markdown
+## Next Steps
+- Continue from Task T003
+- Review checkpoint at ...
+```
+
+**映射**：
+```javascript
+const manifest = readJson('task-manifest.json');
+const nextTask = manifest.tasks.find(t => t.status === 'pending');
+const lastCheckpoint = readJson(`checkpoint-${lastTaskId}.json`);
+```
+
+**结论**：session-handoff.md 可从 task-manifest.json + checkpoint.json 生成。
+
+---
+
+## 正确的实现策略
+
+### Phase 1: 废弃旧文件（不破坏兼容性）
+
+1. **标记为 deprecated**：
+   - 在 flow-init/flow-spec skills 中移除对 session-* 文件的引用
+   - 添加迁移警告：检测到旧文件时输出 deprecation warning
+
+2. **迁移脚本**（可选）：
+   ```bash
+   # .claude/scripts/migrate-legacy-state.sh
+   # 将 orchestration_status.json 转换为 harness-state.json
+   ```
+
+### Phase 2: 增强 harness-state.json（最小化扩展）
+
+当前 harness-state.json 已经足够简洁，只需添加一个可选字段：
+
+```json
+{
+  "changeId": "REQ-123",
+  "goal": "...",
+  "status": "initialized|planned|in_progress|verified|released",
+  "initializedAt": "...",
+  "plannedAt": "...",      // 新增：plan 完成时间
+  "verifiedAt": "...",     // 新增：verify 完成时间
+  "releasedAt": "...",
+  "updatedAt": "..."
+}
+```
+
+**新增状态**：
+- `planned` - harness:plan 完成后
+- `in_progress` - harness:dispatch 开始后
+- `verified` - harness:verify 通过后
+
+### Phase 3: 提供查询工具
+
+创建辅助函数从分散的文件中聚合信息：
+
+```javascript
+// lib/harness/query.js
+
+async function getProgress(repoRoot, changeId) {
+  const manifest = await readJson(getTaskManifestPath(repoRoot, changeId));
+  return {
+    totalTasks: manifest.tasks.length,
+    completedTasks: manifest.tasks.filter(t => t.status === 'passed').length,
+    failedTasks: manifest.tasks.filter(t => t.status === 'failed').length,
+    pendingTasks: manifest.tasks.filter(t => t.status === 'pending').length
+  };
+}
+
+async function getNextTask(repoRoot, changeId) {
+  const manifest = await readJson(getTaskManifestPath(repoRoot, changeId));
+  return manifest.tasks.find(t => t.status === 'pending');
+}
+
+async function getFullState(repoRoot, changeId) {
+  const state = await readJson(getHarnessStatePath(repoRoot, changeId));
+  const manifest = await readJson(getTaskManifestPath(repoRoot, changeId));
+  const report = await readJson(getReportCardPath(repoRoot, changeId), null);
+
+  return {
+    lifecycle: state,
+    progress: await getProgress(repoRoot, changeId),
+    nextTask: await getNextTask(repoRoot, changeId),
+    quality: report
+  };
+}
+```
+
+---
+
+## 实施计划
+
+### Task #10 重新定义
+
+**目标**：废弃旧状态文件，增强 harness-state.json，提供查询工具
+
+**步骤**：
+
+1. **更新 harness-state.json schema**：
+   - 添加 `plannedAt`, `verifiedAt` 字段
+   - 扩展 status 枚举：`initialized|planned|in_progress|verified|released`
+
+2. **更新 operations**：
+   - `plan.js`: 写入 `plannedAt`
+   - `dispatch.js`: 写入 `status: 'in_progress'`
+   - `verify.js`: 写入 `verifiedAt`
+
+3. **创建查询工具**：
+   - `lib/harness/query.js`: getProgress, getNextTask, getFullState
+
+4. **废弃旧文件引用**：
+   - 更新 flow-init/flow-spec skills
+   - 移除 session-* 文件的生成逻辑
+   - 添加 deprecation warnings
+
+5. **文档更新**：
+   - 更新 CLAUDE.md 说明新架构
+   - 添加迁移指南
+
+---
+
+## 验证标准
+
+- [ ] harness-state.json 包含完整生命周期状态
+- [ ] task-manifest.json 包含任务进度
+- [ ] query.js 可以聚合所有状态信息
+- [ ] flow-init/flow-spec 不再引用 session-* 文件
+- [ ] 旧需求（REQ-004/005/006）可以继续工作（向后兼容）
+
+---
+
+## 总结
+
+**核心原则**：
+1. 不创建新的臃肿文件
+2. 保持 v6.0 的关注点分离
+3. 通过查询工具聚合信息
+4. 优雅地废弃旧文件
+
+**哲学**：
+> 单一真相源通过**职责分离 + 查询聚合**实现，而非将所有数据塞入一个文件。
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md