cc-devflow 4.1.6 → 4.3.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.3.0] - 2026-03-13
+
+### ✨ TDD Enforcement + OpenSpec Interop
+
+v4.3.0 adds automatic TDD order validation and bidirectional OpenSpec conversion to solve requirement drift problems.
+
+#### Added
+
+- **TDD Order Validation**
+  - Added `validateTDDOrder()` in `lib/harness/planner.js` to enforce Constitution Article VI
+  - Validates that [IMPL] tasks depend on corresponding [TEST] tasks
+  - Validates that [TEST] tasks don't depend on [IMPL] tasks
+  - Intelligent feature name matching with fuzzy algorithm (removes suffixes like "测试", "实现", "功能")
+  - Extended `TaskSchema` in `lib/harness/schemas.js` with `type` field (TEST/IMPL/OTHER)
+  - Comprehensive test coverage in `lib/harness/__tests__/planner.tdd.test.js` (10 tests, all passing)
+
+- **OpenSpec Interoperability**
+  - Added `.claude/scripts/import-openspec.js` for OpenSpec → CC-DevFlow conversion
+    - Parses OpenSpec format (Purpose + Requirements + BDD scenarios)
+    - Auto-generates TDD tasks (TEST + IMPL pairs with correct dependencies)
+    - Adds Design section with [NEEDS CLARIFICATION] markers
+    - Generates Verification checklist
+  - Added `.claude/scripts/export-openspec.js` for CC-DevFlow → OpenSpec conversion
+    - Strips YAML frontmatter and metadata
+    - Removes Design, Tasks, Verification sections
+    - Removes [NEEDS CLARIFICATION] markers
+    - Outputs pure Requirements in OpenSpec format
+  - Added `.claude/commands/flow/import-openspec.md` command documentation
+  - Added `.claude/commands/flow/export-openspec.md` command documentation
+  - Comprehensive test coverage in `.claude/scripts/__tests__/openspec.test.js` (5 tests, all passing)
+  - Round-trip conversion preserves requirements integrity
+
+#### Benefits
+
+- ✅ Automatic enforcement of TDD order (Constitution Article VI)
+- ✅ Prevents implementation before tests at parse time
+- ✅ Bidirectional OpenSpec compatibility
+- ✅ Automatic TDD task generation during import
+- ✅ Clean requirement export without implementation details
+
+## [4.2.0] - 2026-02-19
+
+### 🧠 Long-Running Harness Protocol Alignment
+
+v4.2.0 unifies long-running execution protocol across project-level `/core:*` commands and requirement-level `/flow:*` skills, reducing context-loss regressions and premature completion.
+
+#### Added
+
+- **Project-level harness protocol**
+  - Added `Initializer / Worker / Done Gate` guidance to:
+    - `.claude/commands/core/roadmap.md`
+    - `.claude/commands/core/architecture.md`
+    - `.claude/commands/core/guidelines.md`
+    - `.claude/commands/core/style.md`
+  - Standardized resumable artifacts under `devflow/.core-harness/*` (`checklist`, `progress`, `handoff`)
+
+- **Requirement-level protocol parity**
+  - Added the same long-running protocol to:
+    - `.claude/skills/workflow/flow-init/SKILL.md`
+    - `.claude/skills/workflow/flow-spec/SKILL.md`
+    - `.claude/skills/workflow/flow-dev/SKILL.md`
+  - Standardized requirement session artifacts:
+    - `session-checklist.json`
+    - `session-progress.md`
+    - `session-handoff.md`
+
+- **Routing-level enforcement**
+  - Extended `.claude/skills/cc-devflow-orchestrator/SKILL.md` with project-level harness routing defaults and artifact-backed completion rules
+
+#### Benefits
+
+- ✅ Consistent long-running behavior between `/core:*` and `/flow:*`
+- ✅ Clear resumability across context windows
+- ✅ Stronger done criteria via artifact-backed gates (instead of subjective completion)
+
 ## [4.1.6] - 2026-02-18
 
 ### 🔧 Multi-Platform Adapt Pipeline Stabilization
@@ -19,6 +94,12 @@ v4.1.6 fixes multi-platform `adapt` compilation drift and parsing failures, with
   - `.claude/commands/**/CLAUDE.md` is now excluded from command parsing
   - Prevents false `Missing YAML frontmatter` failures during `npm run adapt`
 
+- **Harness runtime chain bootstrap**
+  - `cc-devflow init` and `cc-devflow adapt` now auto-add missing `harness:*` npm scripts into target `package.json`
+  - Added `cc-devflow harness <subcommand>` passthrough so injected scripts have a stable runtime entry
+  - Injected scripts are now machine-portable (`cc-devflow harness ...`) with no absolute-path coupling
+  - Auto-repairs legacy `node bin/harness.js <cmd>`, old `npx` wrappers, and prior absolute-path script values
+
 - **Manifest consistency across platforms**
   - Separated source hash (`sourceHash`) and emitted target hash (`hash`)
   - Drift detection now compares emitted artifact hashes correctly

package/README.md

@@ -27,8 +27,9 @@ Harness-first five-stage workflow from requirement setup to release: `/flow:init
 - 🔗 **GitHub Integration** - Automated PR creation, branch management, and conventional commits
 - 📊 **Progress Tracking** - Real-time status monitoring and intelligent restart points
 - 🔍 **Consistency Verification** - Enterprise-grade consistency checking with intelligent conflict detection
-- 🧪 **TDD Enforced** - Strict Test-Driven Development with TEST VERIFICATION CHECKPOINT
+- 🧪 **TDD Enforced** - Strict Test-Driven Development with automatic TDD order validation in harness planner
 - 📜 **Constitution** - 10 Articles governing quality, security, and architecture
+- 🔄 **OpenSpec Interop** - Bidirectional conversion between OpenSpec and CC-DevFlow formats with automatic TDD task generation
 - 🔄 **Autonomous Development** - Ralph × Manus Integration for memory-enhanced continuous iteration
 - 🔌 **Multi-Platform Support** - Compile workflows for Codex, Cursor, Qwen, Antigravity via `npm run adapt`
 - 🔄 **Multi-Module Compiler** - Full module compilation: skills, commands, agents, rules, hooks
@@ -184,8 +185,13 @@ cc-devflow init --dir /path/to/project
 # Compile for specific platform
 cc-devflow adapt --platform codex
 cc-devflow adapt --cwd /path/to/project --platform cursor
+
+# Run harness runtime directly (for npm script delegation)
+cc-devflow harness release --change-id REQ-123
 ```
 
+`cc-devflow init` and `cc-devflow adapt` now auto-bootstrap missing `harness:*` npm scripts in `package.json` using portable `cc-devflow harness <subcommand>` entries (no machine-specific absolute paths), so `/flow:*` can execute the runtime chain without manual script patching.
+
 ### Optional Dependencies
 
 ```bash

package/README.zh-CN.md

@@ -27,8 +27,9 @@
 - 🔗 **GitHub 集成** - 自动化 PR 创建、分支管理和规范化提交
 - 📊 **进度跟踪** - 实时状态监控和智能重启点
 - 🔍 **一致性验证** - 企业级一致性检查，智能冲突检测
-- 🧪 **TDD 强制执行** - 严格的测试驱动开发，TEST VERIFICATION CHECKPOINT
+- 🧪 **TDD 强制执行** - 严格的测试驱动开发，harness planner 自动 TDD 顺序验证
 - 📜 **Constitution** - 10条宪法条款管控质量、安全和架构
+- 🔄 **OpenSpec 互操作** - OpenSpec 与 CC-DevFlow 格式双向转换，自动生成 TDD 任务
 - 🔄 **自主开发** - Ralph × Manus 集成实现有记忆的持续迭代
 - 🔌 **多平台支持** - 通过 `npm run adapt` 编译工作流到 Codex、Cursor、Qwen、Antigravity
 - 🔄 **多模块编译器** - 完整模块编译：skills、commands、agents、rules、hooks
@@ -184,8 +185,13 @@ cc-devflow init --dir /path/to/project
 # 编译到特定平台
 cc-devflow adapt --platform codex
 cc-devflow adapt --cwd /path/to/project --platform cursor
+
+# 直接运行 harness runtime（供 npm scripts 委派）
+cc-devflow harness release --change-id REQ-123
 ```
 
+`cc-devflow init` 与 `cc-devflow adapt` 现在会自动补齐 `package.json` 中缺失的 `harness:*` scripts，且统一写入可移植的 `cc-devflow harness <subcommand>`（不使用机器绝对路径），避免 `/flow:*` 因脚本缺失退化到手工 fallback。
+
 ### 验证安装
 
 ```bash

package/bin/cc-devflow-cli.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+/**
+ * [INPUT]: 依赖 .claude 模板、adapt 编译入口与 harness 运行时入口。
+ * [OUTPUT]: 提供 init/adapt/harness 命令，并在目标仓库自动补齐 harness npm scripts。
+ * [POS]: cc-devflow 的统一 CLI 门面，串联安装、编译与运行时发布链路。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
@@ -7,6 +13,17 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, '.claude');
 const ADAPT_BIN = path.join(PACKAGE_ROOT, 'bin', 'adapt.js');
 const ADAPTER_BIN = path.join(PACKAGE_ROOT, 'bin', 'cc-devflow.js');
+const HARNESS_BIN = path.join(PACKAGE_ROOT, 'bin', 'harness.js');
+const HARNESS_SCRIPT_COMMANDS = {
+  'harness:init': 'init',
+  'harness:pack': 'pack',
+  'harness:plan': 'plan',
+  'harness:dispatch': 'dispatch',
+  'harness:verify': 'verify',
+  'harness:release': 'release',
+  'harness:resume': 'resume',
+  'harness:janitor': 'janitor'
+};
 
 function showHelp() {
   console.log(`
@@ -15,6 +32,7 @@ Usage: cc-devflow <command> [options]
 Commands:
   init                Install .claude template into a project
   adapt               Compile .claude into multi-platform outputs
+  harness             Run harness runtime commands (init/verify/release/janitor...)
 
 Init options:
   --dir <path>         Target project path (default: cwd)
@@ -34,6 +52,7 @@ Examples:
   cc-devflow init --dir /path/to/project
   cc-devflow adapt --platform cursor
   cc-devflow adapt --cwd /path/to/project --platform codex
+  cc-devflow harness release --change-id REQ-123
 `);
 }
 
@@ -122,6 +141,114 @@ function copyIncremental(src, dest) {
   }
 }
 
+function detectJsonIndent(content) {
+  const match = content.match(/\n([ \t]+)"[^"\n]+":/);
+  if (!match) {
+    return 2;
+  }
+
+  const indent = match[1];
+  return indent.includes('\t') ? '\t' : indent.length;
+}
+
+function hasLocalHarnessBinary(targetRoot) {
+  return fs.existsSync(path.join(targetRoot, 'bin', 'harness.js'));
+}
+
+function getHarnessScriptCommand(targetRoot, subcommand) {
+  if (hasLocalHarnessBinary(targetRoot)) {
+    return `node bin/harness.js ${subcommand}`;
+  }
+  return `cc-devflow harness ${subcommand}`;
+}
+
+function ensureHarnessScripts(targetRoot) {
+  const pkgPath = path.join(targetRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.warn(`[WARN] Missing package.json in ${targetRoot}; skipping harness script bootstrap.`);
+    return;
+  }
+
+  let raw;
+  let packageJson;
+  try {
+    raw = fs.readFileSync(pkgPath, 'utf8');
+    packageJson = JSON.parse(raw);
+  } catch (error) {
+    console.warn(`[WARN] Skipping harness script bootstrap: cannot parse package.json (${error.message})`);
+    return;
+  }
+
+  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    console.warn('[WARN] Skipping harness script bootstrap: package.json root must be an object.');
+    return;
+  }
+
+  if (!packageJson.scripts || typeof packageJson.scripts !== 'object' || Array.isArray(packageJson.scripts)) {
+    packageJson.scripts = {};
+  }
+
+  const hasLocalBinary = hasLocalHarnessBinary(targetRoot);
+  const added = [];
+  const repaired = [];
+  let changed = false;
+
+  for (const [scriptName, subcommand] of Object.entries(HARNESS_SCRIPT_COMMANDS)) {
+    const desired = getHarnessScriptCommand(targetRoot, subcommand);
+    const existing = packageJson.scripts[scriptName];
+
+    if (typeof existing === 'undefined') {
+      packageJson.scripts[scriptName] = desired;
+      added.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    if (typeof existing !== 'string') {
+      continue;
+    }
+
+    // Auto-repair legacy value when local harness binary does not exist.
+    if (!hasLocalBinary && existing.trim() === `node bin/harness.js ${subcommand}`) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    // Auto-repair previous injected npx-based value to deterministic runtime path.
+    if (!hasLocalBinary && existing.trim() === `npx --yes cc-devflow harness ${subcommand}`) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    // Auto-repair previous absolute-path fallback value (not portable across machines).
+    const escapedHarnessBin = HARNESS_BIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const absoluteLegacy = new RegExp(`^node\\s+["']?${escapedHarnessBin}["']?\\s+${subcommand}(\\s*\\|\\|\\s*cc-devflow\\s+harness\\s+${subcommand})?$`);
+    if (!hasLocalBinary && absoluteLegacy.test(existing.trim())) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return;
+  }
+
+  const indent = detectJsonIndent(raw);
+  fs.writeFileSync(pkgPath, `${JSON.stringify(packageJson, null, indent)}\n`);
+
+  if (added.length > 0) {
+    console.log(`[UPDATE] package.json (added ${added.join(', ')})`);
+  }
+  if (repaired.length > 0) {
+    console.log(`[UPDATE] package.json (repaired ${repaired.join(', ')})`);
+  }
+}
+
 function runInit(args) {
   const { options } = parseCliArgs(args);
 
@@ -141,6 +268,7 @@ function runInit(args) {
   // Case 1: Directory does not exist - Clean Install
   if (!fs.existsSync(targetDir)) {
     fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+    ensureHarnessScripts(targetRoot);
     console.log(`Initialized .claude in ${targetRoot}`);
     return 0;
   }
@@ -150,6 +278,7 @@ function runInit(args) {
     console.log('Force flag detected. Resetting .claude directory...');
     fs.rmSync(targetDir, { recursive: true, force: true });
     fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+    ensureHarnessScripts(targetRoot);
     console.log(`Re-initialized .claude in ${targetRoot}`);
     return 0;
   }
@@ -157,6 +286,7 @@ function runInit(args) {
   // Case 3: Directory exists - Incremental Update
   console.log(`Target ${targetDir} already exists. Performing incremental update...`);
   copyIncremental(TEMPLATE_DIR, targetDir);
+  ensureHarnessScripts(targetRoot);
   console.log('Incremental update complete. Existing files were preserved.');
   return 0;
 }
@@ -178,6 +308,8 @@ function runAdapt(args) {
     return 1;
   }
 
+  ensureHarnessScripts(targetRoot);
+
   const result = spawnSync(process.execPath, [ADAPT_BIN, ...rest], {
     stdio: 'inherit',
     cwd: targetRoot
@@ -191,6 +323,24 @@ function runAdapt(args) {
   return typeof result.status === 'number' ? result.status : 1;
 }
 
+function runHarness(args) {
+  const { options, rest } = parseCliArgs(args);
+
+  const targetRoot = path.resolve(options.cwd || process.cwd());
+  const cliArgs = options.help || rest.length === 0 ? ['--help'] : rest;
+  const result = spawnSync(process.execPath, [HARNESS_BIN, ...cliArgs], {
+    stdio: 'inherit',
+    cwd: targetRoot
+  });
+
+  if (result.error) {
+    console.error(`Failed to run harness: ${result.error.message}`);
+    return 1;
+  }
+
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
 function runAdapter(command, args) {
   const result = spawnSync(process.execPath, [ADAPTER_BIN, command, ...args], {
     stdio: 'inherit'
@@ -221,6 +371,10 @@ function main() {
     return runAdapt(rest);
   }
 
+  if (command === 'harness') {
+    return runHarness(rest);
+  }
+
   return runAdapter(command, rest);
 }
 

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 工件，保留运行中任务状态。