cc-devflow 4.3.0 → 4.5.0

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

@@ -1,349 +0,0 @@
-# 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

@@ -1,323 +0,0 @@
-# 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