cc-devflow 4.2.0 → 4.3.0

package/docs/v4.3.0-migration-guide.md

@@ -0,0 +1,276 @@
+# CC-DevFlow v4.3.0 Migration Guide
+
+## Overview
+
+CC-DevFlow v4.3.0 introduces automatic TDD order validation and OpenSpec interoperability to solve requirement drift problems. This guide helps you migrate from v4.2.x to v4.3.0.
+
+---
+
+## What's New in v4.3.0
+
+### 1. Automatic TDD Order Validation
+
+**Feature**: The harness planner now automatically validates TDD order when parsing TASKS.md.
+
+**Impact**:
+- [IMPL] tasks MUST depend on corresponding [TEST] tasks
+- [TEST] tasks CANNOT depend on [IMPL] tasks
+- Violations throw detailed error messages at `harness:plan` time
+
+**Example Error**:
+```
+TDD Order Validation Failed (Constitution Article VI):
+
+1. Task T002 (用户登录实现) missing corresponding TEST task.
+   Constitution Article VI requires: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+
+2. Task T004 (用户注册实现) must depend on T003 (用户注册测试).
+   TDD violation: Implementation must come AFTER test.
+```
+
+**Migration Steps**:
+1. Review your existing TASKS.md files
+2. Ensure all [IMPL] tasks have corresponding [TEST] tasks
+3. Add `dependsOn` to [IMPL] tasks pointing to [TEST] tasks
+4. Use `[P]` marker for parallel tasks that don't follow TEST→IMPL pattern
+
+**Example Fix**:
+```markdown
+<!-- Before (INVALID) -->
+- [ ] T001 [IMPL] 用户登录实现
+- [ ] T002 [TEST] 用户登录测试
+
+<!-- After (VALID) -->
+- [ ] T001 [TEST] 用户登录测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+```
+
+### 2. OpenSpec Interoperability
+
+**Feature**: Bidirectional conversion between OpenSpec and CC-DevFlow formats.
+
+**New Commands**:
+- `/flow:import-openspec` - Import OpenSpec spec.md to CC-DevFlow
+- `/flow:export-openspec` - Export CC-DevFlow spec.md to OpenSpec
+
+**Use Cases**:
+
+#### Import from OpenSpec
+```bash
+/flow:import-openspec "/path/to/openspec/specs/auth/spec.md" \
+  --req-id "REQ-123" \
+  --title "用户认证系统"
+```
+
+**What happens**:
+1. Parses OpenSpec format (Purpose + Requirements + BDD scenarios)
+2. Generates CC-DevFlow spec.md with YAML frontmatter
+3. Auto-generates TDD tasks (TEST + IMPL pairs with correct dependencies)
+4. Adds Design section with [NEEDS CLARIFICATION] markers
+5. Generates Verification checklist
+
+#### Export to OpenSpec
+```bash
+/flow:export-openspec "REQ-123" \
+  --output "/path/to/openspec/specs/auth/spec.md"
+```
+
+**What happens**:
+1. Parses CC-DevFlow spec.md
+2. Strips YAML frontmatter and metadata
+3. Removes Design, Tasks, Verification sections
+4. Removes [NEEDS CLARIFICATION] markers
+5. Outputs pure Requirements in OpenSpec format
+
+**Round-Trip Guarantee**: Requirements are preserved through import→export→import cycles.
+
+---
+
+## Breaking Changes
+
+### 1. TASKS.md Validation
+
+**Before v4.3.0**: TDD order was recommended but not enforced.
+
+**After v4.3.0**: TDD order is enforced at `harness:plan` time.
+
+**Migration**: Update existing TASKS.md files to follow TDD order.
+
+### 2. Task Type Detection
+
+**Before v4.3.0**: Task types were not tracked.
+
+**After v4.3.0**: Tasks are classified as TEST/IMPL/OTHER based on markers.
+
+**Migration**: Ensure your TASKS.md uses `[TEST]` and `[IMPL]` markers consistently.
+
+---
+
+## Feature Name Matching Algorithm
+
+The TDD validator uses intelligent fuzzy matching to pair TEST and IMPL tasks:
+
+**Normalization Rules**:
+- Removes suffixes: "测试", "实现", "功能", "开发", "编写"
+- Trims whitespace
+- Compares core feature names
+
+**Examples**:
+```
+"用户登录功能测试" ↔ "用户登录功能实现" ✅ Match
+"用户登录测试"     ↔ "用户登录实现"     ✅ Match
+"用户登录"         ↔ "用户登录功能"     ✅ Match
+"用户登录"         ↔ "用户注册"         ❌ No match
+```
+
+---
+
+## Parallel Tasks
+
+For tasks that don't follow TEST→IMPL pattern, use the `[P]` marker:
+
+```markdown
+- [ ] T001 [TEST] 用户登录测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+- [ ] T003 [OTHER] 数据库迁移 [P]
+- [ ] T004 [OTHER] 配置文件更新 [P]
+```
+
+The `[P]` marker tells the validator to skip dependency checks for that task.
+
+---
+
+## OpenSpec Format Reference
+
+### OpenSpec Format (Input)
+```markdown
+# Authentication Module
+
+## Purpose
+Provides secure authentication and session management.
+
+## 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
+```
+
+### CC-DevFlow Format (Output)
+```markdown
+---
+req_id: "REQ-123"
+title: "用户认证系统"
+created_at: "2026-03-13T10:00:00Z"
+version: "1.0.0"
+status: "draft"
+source: "openspec"
+---
+
+# Authentication Module
+
+## Purpose
+Provides secure authentication and session management.
+
+## 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
+
+## Design
+[NEEDS CLARIFICATION: 技术实现方案]
+
+## Tasks
+- [ ] T001 [TEST] User Login - 测试
+- [ ] T002 [IMPL] User Login - 实现 (dependsOn:T001)
+
+## Verification
+- [ ] User Login
+  - [ ] Valid credentials
+```
+
+---
+
+## Testing
+
+All v4.3.0 features are covered by automated tests:
+
+```bash
+# Run all tests
+npm test
+
+# Run TDD validation tests only
+npm test -- planner.tdd.test.js
+
+# Run OpenSpec interop tests only
+npm test -- openspec.test.js
+```
+
+**Test Coverage**:
+- TDD validation: 10 tests (all passing)
+- OpenSpec interop: 5 tests (all passing)
+- Total: 233 tests (all passing)
+
+---
+
+## Troubleshooting
+
+### Error: "Task T002 missing corresponding TEST task"
+
+**Cause**: An [IMPL] task has no matching [TEST] task.
+
+**Solution**: Add a [TEST] task with similar feature name before the [IMPL] task.
+
+### Error: "Task T002 must depend on T001"
+
+**Cause**: An [IMPL] task doesn't depend on its corresponding [TEST] task.
+
+**Solution**: Add `(dependsOn:T001)` to the [IMPL] task.
+
+### Error: "Task T001 depends on IMPL tasks"
+
+**Cause**: A [TEST] task depends on an [IMPL] task (reverse TDD order).
+
+**Solution**: Remove the dependency or reorder tasks.
+
+### Feature Name Mismatch
+
+**Cause**: TEST and IMPL tasks have very different feature names.
+
+**Solution**: Rename tasks to have similar core feature names, or use `[P]` marker if they're truly independent.
+
+---
+
+## Rollback
+
+If you need to rollback to v4.2.0:
+
+```bash
+npm install cc-devflow@4.2.0
+```
+
+Note: v4.2.0 does not have TDD validation or OpenSpec interop features.
+
+---
+
+## Support
+
+- GitHub Issues: https://github.com/anthropics/cc-devflow/issues
+- Documentation: https://github.com/anthropics/cc-devflow/tree/main/docs
+- Constitution: `.claude/rules/project-constitution.md`
+
+---
+
+**Last Updated**: 2026-03-13
+**Version**: 4.3.0

package/lib/harness/CLAUDE.md

@@ -3,16 +3,17 @@
 
 成员清单
 index.js: 聚合导出 harness 基础模块，供 CLI 与测试统一引用。
-schemas.js: 定义 manifest/report/checkpoint 的 Zod 契约，阻断脏数据进入执行层。
+schemas.js: 定义 manifest/report/checkpoint/harness-state 的 Zod 契约，阻断脏数据进入执行层。
 store.js: 提供路径规范、JSON/文本读写、JSONL 事件记录与 shell 命令执行。
 planner.js: 将 TASKS.md 解析为 dependency-aware 的 task-manifest.json。
+query.js: 聚合分散状态文件，提供 getProgress/getNextTask/getFullState 查询函数。
 cli.js: 解析命令参数并分发到 operations 子模块。
 operations/init.js: 初始化 requirement 与 runtime 目录并写入 harness-state。
 operations/pack.js: 采集 git 与脚本事实，生成 context-package.md。
-operations/plan.js: 调用 planner 生成 task-manifest.json。
-operations/dispatch.js: 依据依赖图与文件冲突并行执行任务，写 checkpoint 与 events。
+operations/plan.js: 调用 planner 生成 task-manifest.json，更新 harness-state 为 planned。
+operations/dispatch.js: 依据依赖图与文件冲突并行执行任务，写 checkpoint 与 events，更新 harness-state 为 in_progress。
 operations/resume.js: 恢复中断任务并复用 dispatch 继续执行。
-operations/verify.js: 执行 quick/strict 质量门禁并输出 report-card.json。
+operations/verify.js: 执行 quick/strict 质量门禁并输出 report-card.json，通过时更新 harness-state 为 verified。
 operations/release.js: 读取通过的 report-card，生成 RELEASE_NOTE 并标记 released。
 operations/janitor.js: 清理过期 runtime 工件，保留运行中任务状态。
 

package/lib/harness/__tests__/planner.tdd.test.js

@@ -0,0 +1,125 @@
+/**
+ * TDD Order Validation Tests
+ *
+ * Tests for Constitution Article VI enforcement in planner.js
+ */
+
+const { parseTasksMarkdown } = require('../planner');
+
+describe('TDD Order Validation', () => {
+  describe('Valid TDD sequences', () => {
+    test('should accept TEST before IMPL with correct dependency', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录功能测试
+- [ ] T002 [IMPL] 用户登录功能实现 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should accept multiple TEST-IMPL pairs', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+- [ ] T003 [TEST] 用户注册测试 [P]
+- [ ] T004 [IMPL] 用户注册实现 (dependsOn:T003)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should accept tasks without TEST/IMPL markers', () => {
+      const markdown = `
+- [ ] T001 初始化项目结构
+- [ ] T002 配置开发环境
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+  });
+
+  describe('TDD violations', () => {
+    test('should reject IMPL without corresponding TEST', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 用户登录功能实现
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /missing corresponding TEST task/
+      );
+    });
+
+    test('should reject IMPL not depending on TEST', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录功能测试
+- [ ] T002 [IMPL] 用户登录功能实现 [P]
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /must depend on T001/
+      );
+    });
+
+    test('should reject TEST depending on IMPL', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 用户登录功能实现
+- [ ] T002 [TEST] 用户登录功能测试 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /Tests must be written BEFORE implementation/
+      );
+    });
+
+    test('should reject IMPL depending on wrong TEST', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户注册测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /missing corresponding TEST task/
+      );
+    });
+  });
+
+  describe('Feature name extraction', () => {
+    test('should match TEST and IMPL with same feature name', () => {
+      const markdown = `
+- [ ] T001 [TEST] 实现用户认证功能
+- [ ] T002 [IMPL] 实现用户认证功能 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should handle case-insensitive markers', () => {
+      const markdown = `
+- [ ] T001 [test] 用户登录
+- [ ] T002 [impl] 用户登录 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+  });
+
+  describe('Error messages', () => {
+    test('should provide clear violation details', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 功能A
+- [ ] T002 [TEST] 功能B
+- [ ] T003 [IMPL] 功能B
+      `.trim();
+
+      try {
+        parseTasksMarkdown(markdown);
+        fail('Should have thrown TDD violation error');
+      } catch (error) {
+        expect(error.message).toContain('TDD Order Validation Failed');
+        expect(error.message).toContain('Constitution Article VI');
+        expect(error.message).toContain('T001');
+        expect(error.message).toContain('missing corresponding TEST task');
+      }
+    });
+  });
+});

package/lib/harness/index.js

@@ -1,6 +1,6 @@
 /**
  * [INPUT]: 依赖 harness 各模块。
- * [OUTPUT]: 统一导出 schema/store/planner 与 operations 入口。
+ * [OUTPUT]: 统一导出 schema/store/planner/query 与 operations 入口。
  * [POS]: harness 模块聚合出口，被 bin 与测试代码使用。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
  */
@@ -8,9 +8,11 @@
 const store = require('./store');
 const schemas = require('./schemas');
 const planner = require('./planner');
+const query = require('./query');
 
 module.exports = {
   ...store,
   ...schemas,
-  ...planner
+  ...planner,
+  ...query
 };

package/lib/harness/operations/dispatch.js

@@ -13,6 +13,7 @@ const {
   readJson,
   runCommand,
   getTaskManifestPath,
+  getHarnessStatePath,
   getRuntimeTaskDir,
   getEventsPath,
   getCheckpointPath
@@ -203,6 +204,18 @@ async function runDispatch({ repoRoot, changeId, parallel = 3, maxRetries, resum
   const manifestPath = getTaskManifestPath(repoRoot, changeId);
   const manifest = parseManifest(await readJson(manifestPath));
 
+  // Update harness-state.json to in_progress on first dispatch
+  const statePath = getHarnessStatePath(repoRoot, changeId);
+  const stateExists = require('fs').existsSync(statePath);
+  if (stateExists) {
+    const state = await readJson(statePath);
+    if (state.status === 'planned' || state.status === 'initialized') {
+      state.status = 'in_progress';
+      state.updatedAt = nowIso();
+      await writeJson(statePath, state);
+    }
+  }
+
   if (resume) {
     for (const task of manifest.tasks) {
       if (task.status === 'running') {

package/lib/harness/operations/plan.js

@@ -6,9 +6,53 @@
  */
 
 const { createTaskManifest } = require('../planner');
-const { getTaskManifestPath } = require('../store');
+const { getTaskManifestPath, getHarnessStatePath, exists, readText, readJson, writeJson } = require('../store');
+const path = require('path');
+const { execSync } = require('child_process');
 
 async function runPlan({ repoRoot, changeId, goal, overwrite }) {
+  // v4.3: 检查是否存在 proposal.md（新架构）
+  const reqDir = path.join(repoRoot, 'devflow', 'requirements', changeId);
+  const proposalPath = path.join(reqDir, 'proposal.md');
+  const hasProposal = await exists(proposalPath);
+
+  if (hasProposal) {
+    console.log(`[v4.3] Detected proposal.md, generating design.md and Delta specs...`);
+
+    // 注意：实际的 design.md 和 Delta specs 生成由 Claude Agent 在 /flow:spec 中完成
+    // 这里只是检测并提示，不执行生成逻辑
+    // 生成逻辑在 .claude/skills/flow-spec/SKILL.md 的 Execution Steps 中定义
+
+    const designPath = path.join(reqDir, 'design.md');
+    const specsDir = path.join(reqDir, 'specs');
+    const scopeReportPath = path.join(reqDir, 'scope-creep-report.md');
+
+    // 检查必需产物是否存在
+    const hasDesign = await exists(designPath);
+    const hasSpecs = await exists(specsDir);
+    const hasScopeReport = await exists(scopeReportPath);
+
+    if (!hasDesign) {
+      console.warn(`[v4.3] WARNING: design.md not found. Expected at ${designPath}`);
+    }
+
+    if (!hasSpecs) {
+      console.warn(`[v4.3] WARNING: specs/ directory not found. Expected at ${specsDir}`);
+    }
+
+    if (!hasScopeReport) {
+      console.warn(`[v4.3] WARNING: scope-creep-report.md not found. Run validate-scope.sh`);
+    }
+
+    // 如果存在 scope-creep-report.md，检查是否有阻塞性警告
+    if (hasScopeReport) {
+      const reportContent = await readText(scopeReportPath);
+      if (reportContent.includes('⚠️') && reportContent.includes('Potential scope creep')) {
+        console.warn(`[v4.3] WARNING: Scope creep detected. Review ${scopeReportPath}`);
+      }
+    }
+  }
+
   const manifest = await createTaskManifest({
     repoRoot,
     changeId,
@@ -16,6 +60,16 @@ async function runPlan({ repoRoot, changeId, goal, overwrite }) {
     overwrite
   });
 
+  // Update harness-state.json with plannedAt timestamp
+  const statePath = getHarnessStatePath(repoRoot, changeId);
+  if (await exists(statePath)) {
+    const state = await readJson(statePath);
+    state.status = 'planned';
+    state.plannedAt = new Date().toISOString();
+    state.updatedAt = new Date().toISOString();
+    await writeJson(statePath, state);
+  }
+
   return {
     changeId,
     manifestPath: getTaskManifestPath(repoRoot, changeId),

package/lib/harness/operations/release.js

@@ -10,12 +10,16 @@ const {
   readJson,
   writeText,
   writeJson,
+  exists,
   getReportCardPath,
   getTaskManifestPath,
   getReleaseNotePath,
   getHarnessStatePath
 } = require('../store');
 const { parseReportCard, parseManifest } = require('../schemas');
+const path = require('path');
+const { execSync } = require('child_process');
+const fs = require('fs').promises;
 
 function formatReleaseNote({ changeId, manifest, report }) {
   const passedTasks = manifest.tasks.filter((task) => task.status === 'passed');
@@ -59,6 +63,89 @@ async function runRelease({ repoRoot, changeId }) {
     throw new Error('Release blocked: report-card overall is not pass');
   }
 
+  // v4.3: 合并 Delta specs 到项目级 specs/
+  const reqDir = path.join(repoRoot, 'devflow', 'requirements', changeId);
+  const deltaSpecsDir = path.join(reqDir, 'specs');
+  const projectSpecsDir = path.join(repoRoot, 'devflow', 'specs');
+  const hasDeltaSpecs = await exists(deltaSpecsDir);
+
+  if (hasDeltaSpecs) {
+    console.log(`[v4.3] Merging Delta specs to project-level specs/...`);
+
+    try {
+      // 遍历所有 Delta spec.md 文件
+      const modules = await fs.readdir(deltaSpecsDir);
+      const mergeResults = [];
+
+      for (const module of modules) {
+        const deltaSpecPath = path.join(deltaSpecsDir, module, 'spec.md');
+        const projectSpecPath = path.join(projectSpecsDir, module, 'spec.md');
+
+        if (!(await exists(deltaSpecPath))) {
+          console.warn(`[v4.3] WARNING: Delta spec not found: ${deltaSpecPath}`);
+          continue;
+        }
+
+        if (!(await exists(projectSpecPath))) {
+          console.warn(`[v4.3] WARNING: Project spec not found: ${projectSpecPath}`);
+          console.log(`[v4.3] Creating new project spec for module: ${module}`);
+
+          // 如果项目级 spec 不存在，创建目录并复制 Delta 作为初始版本
+          await fs.mkdir(path.dirname(projectSpecPath), { recursive: true });
+          await fs.copyFile(deltaSpecPath, projectSpecPath);
+
+          mergeResults.push({ module, status: 'created', newVersion: '1.0.0' });
+          continue;
+        }
+
+        // 调用 delta-parser.ts merge 命令
+        const deltaParserPath = path.join(repoRoot, '.claude', 'scripts', 'delta-parser.ts');
+
+        try {
+          const output = execSync(
+            `npx ts-node "${deltaParserPath}" merge "${projectSpecPath}" "${deltaSpecPath}"`,
+            { cwd: repoRoot, encoding: 'utf-8' }
+          );
+
+          // 解析输出获取新版本号
+          const versionMatch = output.match(/New version: ([\d.]+)/);
+          const newVersion = versionMatch ? versionMatch[1] : 'unknown';
+
+          mergeResults.push({ module, status: 'merged', newVersion });
+          console.log(`[v4.3] ✅ Merged ${module}: ${newVersion}`);
+        } catch (mergeError) {
+          console.error(`[v4.3] ❌ Failed to merge ${module}:`, mergeError.message);
+          mergeResults.push({ module, status: 'failed', error: mergeError.message });
+        }
+      }
+
+      // 记录合并结果到 RELEASE_NOTE
+      const mergeReport = mergeResults
+        .map(r => {
+          if (r.status === 'merged') {
+            return `- ✅ ${r.module}: merged to v${r.newVersion}`;
+          } else if (r.status === 'created') {
+            return `- 🆕 ${r.module}: created v${r.newVersion}`;
+          } else {
+            return `- ❌ ${r.module}: ${r.error}`;
+          }
+        })
+        .join('\n');
+
+      console.log(`[v4.3] Delta merge summary:\n${mergeReport}`);
+
+      // 将合并结果添加到 release note
+      manifest.metadata = manifest.metadata || {};
+      manifest.metadata.deltaMergeResults = mergeResults;
+
+    } catch (error) {
+      console.error(`[v4.3] ERROR during Delta merge:`, error);
+      throw new Error(`Delta merge failed: ${error.message}`);
+    }
+  } else {
+    console.log(`[v4.3] No Delta specs found, skipping merge.`);
+  }
+
   const note = formatReleaseNote({ changeId, manifest, report });
   const releaseNotePath = getReleaseNotePath(repoRoot, changeId);
 

package/lib/harness/operations/verify.js

@@ -12,6 +12,7 @@ const {
   writeJson,
   runCommand,
   getTaskManifestPath,
+  getHarnessStatePath,
   getReportCardPath
 } = require('../store');
 const { parseManifest, parseReportCard } = require('../schemas');
@@ -150,6 +151,19 @@ async function runVerify({ repoRoot, changeId, strict = false, skipReview = fals
   const outputPath = getReportCardPath(repoRoot, changeId);
   await writeJson(outputPath, report);
 
+  // Update harness-state.json with verifiedAt timestamp if passed
+  if (!hasFailures) {
+    const statePath = getHarnessStatePath(repoRoot, changeId);
+    const stateExists = require('fs').existsSync(statePath);
+    if (stateExists) {
+      const state = await readJson(statePath);
+      state.status = 'verified';
+      state.verifiedAt = nowIso();
+      state.updatedAt = nowIso();
+      await writeJson(statePath, state);
+    }
+  }
+
   return {
     changeId,
     outputPath,