cc-devflow 4.1.6 → 4.3.0

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,

package/lib/harness/planner.js

@@ -72,9 +72,13 @@ function parseTasksMarkdown(content) {
     const dependsOn = parseDependsOn(tail, previousTaskId, isParallel);
     const title = normalizeTitle(tail).replace(TRAILING_PATHS, '').trim() || `Task ${taskId}`;
 
+    // 提取任务类型 [TEST] 或 [IMPL]
+    const taskType = extractTaskType(title);
+
     tasks.push({
       id: taskId,
       title,
+      type: taskType,
       dependsOn,
       touches,
       run: [`echo "[TASK ${taskId}] ${title}"`],
@@ -87,9 +91,136 @@ function parseTasksMarkdown(content) {
     previousTaskId = taskId;
   }
 
+  // TDD 顺序验证 (Constitution Article VI)
+  validateTDDOrder(tasks);
+
   return tasks;
 }
 
+function extractTaskType(title) {
+  if (/\[TEST\]/i.test(title)) {
+    return 'TEST';
+  }
+  if (/\[IMPL\]/i.test(title)) {
+    return 'IMPL';
+  }
+  return 'OTHER';
+}
+
+/**
+ * TDD 顺序验证 (Constitution Article VI)
+ *
+ * 规则:
+ * 1. 每个 [IMPL] 任务必须有对应的 [TEST] 任务
+ * 2. [IMPL] 任务必须依赖对应的 [TEST] 任务 (通过 dependsOn)
+ * 3. [TEST] 任务不能依赖 [IMPL] 任务
+ *
+ * @param {Array} tasks - 任务列表
+ * @throws {Error} - TDD 顺序违规时抛出错误
+ */
+function validateTDDOrder(tasks) {
+  const violations = [];
+  const testTasks = tasks.filter(t => t.type === 'TEST');
+  const implTasks = tasks.filter(t => t.type === 'IMPL');
+
+  // 为每个 IMPL 任务查找对应的 TEST 任务
+  for (const implTask of implTasks) {
+    // 提取功能名称 (去除 [IMPL] 标记后的主要描述)
+    const implFeature = extractFeatureName(implTask.title);
+
+    // 查找匹配的 TEST 任务 (使用模糊匹配)
+    const matchingTest = testTasks.find(testTask => {
+      const testFeature = extractFeatureName(testTask.title);
+      // 模糊匹配：检查是否包含相同的核心关键词
+      return isSimilarFeature(testFeature, implFeature);
+    });
+
+    if (!matchingTest) {
+      violations.push(
+        `Task ${implTask.id} (${implTask.title}) missing corresponding TEST task. ` +
+        `Constitution Article VI requires: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.`
+      );
+      continue;
+    }
+
+    // 检查依赖关系
+    if (!implTask.dependsOn.includes(matchingTest.id)) {
+      violations.push(
+        `Task ${implTask.id} (${implTask.title}) must depend on ${matchingTest.id} (${matchingTest.title}). ` +
+        `TDD violation: Implementation must come AFTER test.`
+      );
+    }
+  }
+
+  // 检查 TEST 任务不能依赖 IMPL 任务
+  for (const testTask of testTasks) {
+    const implDeps = testTask.dependsOn.filter(depId => {
+      const depTask = tasks.find(t => t.id === depId);
+      return depTask && depTask.type === 'IMPL';
+    });
+
+    if (implDeps.length > 0) {
+      violations.push(
+        `Task ${testTask.id} (${testTask.title}) depends on IMPL tasks: ${implDeps.join(', ')}. ` +
+        `TDD violation: Tests must be written BEFORE implementation.`
+      );
+    }
+  }
+
+  if (violations.length > 0) {
+    throw new Error(
+      `TDD Order Validation Failed (Constitution Article VI):\n\n` +
+      violations.map((v, i) => `${i + 1}. ${v}`).join('\n\n') +
+      `\n\nFix TASKS.md to follow TDD sequence: [TEST] tasks BEFORE [IMPL] tasks.`
+    );
+  }
+}
+
+/**
+ * 从任务标题中提取功能名称
+ * 例如: "[TEST] 用户登录功能" -> "用户登录功能"
+ *       "[IMPL] 用户登录功能" -> "用户登录功能"
+ */
+function extractFeatureName(title) {
+  return title
+    .replace(/\[TEST\]/gi, '')
+    .replace(/\[IMPL\]/gi, '')
+    .replace(/\[P\]/gi, '')
+    .replace(/\(dependsOn:[^)]*\)/gi, '')
+    .replace(/\([^)]*\)/g, '')
+    .trim();
+}
+
+/**
+ * 判断两个功能名称是否相似
+ * 使用核心关键词匹配策略
+ */
+function isSimilarFeature(feature1, feature2) {
+  // 提取核心关键词 (去除常见后缀如"测试"、"实现"、"功能"等)
+  const normalize = (str) => str
+    .replace(/测试$/g, '')
+    .replace(/实现$/g, '')
+    .replace(/功能$/g, '')
+    .replace(/开发$/g, '')
+    .replace(/编写$/g, '')
+    .trim();
+
+  const core1 = normalize(feature1);
+  const core2 = normalize(feature2);
+
+  // 精确匹配
+  if (core1 === core2) {
+    return true;
+  }
+
+  // 包含匹配 (较长的包含较短的)
+  if (core1.length > core2.length) {
+    return core1.includes(core2);
+  } else {
+    return core2.includes(core1);
+  }
+}
+
 function buildDefaultTasks(changeId) {
   return [
     {

package/lib/harness/query.js

@@ -0,0 +1,126 @@
+/**
+ * [INPUT]: 依赖 store 读取 harness-state/task-manifest/report-card，接收 repoRoot 和 changeId。
+ * [OUTPUT]: 对外提供 getProgress/getNextTask/getFullState 查询函数，聚合分散的状态信息。
+ * [POS]: harness 查询工具层，被 CLI 与 skills 调用以获取聚合状态视图。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  getHarnessStatePath,
+  getTaskManifestPath,
+  getReportCardPath,
+  readJson
+} = require('./store');
+
+/**
+ * 获取任务进度统计
+ * @param {string} repoRoot - 仓库根目录
+ * @param {string} changeId - 需求 ID
+ * @returns {Promise<Object>} 进度统计对象
+ */
+async function getProgress(repoRoot, changeId) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+
+  try {
+    const manifest = await readJson(manifestPath);
+
+    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,
+      runningTasks: manifest.tasks.filter(t => t.status === 'running').length,
+      skippedTasks: manifest.tasks.filter(t => t.status === 'skipped').length
+    };
+  } catch (error) {
+    return {
+      totalTasks: 0,
+      completedTasks: 0,
+      failedTasks: 0,
+      pendingTasks: 0,
+      runningTasks: 0,
+      skippedTasks: 0,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * 获取下一个待执行的任务
+ * @param {string} repoRoot - 仓库根目录
+ * @param {string} changeId - 需求 ID
+ * @returns {Promise<Object|null>} 下一个任务对象或 null
+ */
+async function getNextTask(repoRoot, changeId) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+
+  try {
+    const manifest = await readJson(manifestPath);
+
+    // 找到第一个 pending 状态的任务
+    const nextTask = manifest.tasks.find(t => t.status === 'pending');
+
+    return nextTask || null;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * 获取完整的聚合状态视图
+ * @param {string} repoRoot - 仓库根目录
+ * @param {string} changeId - 需求 ID
+ * @returns {Promise<Object>} 完整状态对象
+ */
+async function getFullState(repoRoot, changeId) {
+  const statePath = getHarnessStatePath(repoRoot, changeId);
+  const reportPath = getReportCardPath(repoRoot, changeId);
+
+  try {
+    const state = await readJson(statePath);
+    const progress = await getProgress(repoRoot, changeId);
+    const nextTask = await getNextTask(repoRoot, changeId);
+
+    let report = null;
+    try {
+      report = await readJson(reportPath);
+    } catch {
+      // report-card.json 可能不存在（未执行 verify）
+      report = null;
+    }
+
+    return {
+      lifecycle: {
+        changeId: state.changeId,
+        goal: state.goal,
+        status: state.status,
+        initializedAt: state.initializedAt,
+        plannedAt: state.plannedAt,
+        verifiedAt: state.verifiedAt,
+        releasedAt: state.releasedAt,
+        updatedAt: state.updatedAt
+      },
+      progress,
+      nextTask,
+      quality: report ? {
+        overall: report.overall,
+        blockingFindings: report.blockingFindings,
+        timestamp: report.timestamp
+      } : null
+    };
+  } catch (error) {
+    return {
+      error: error.message,
+      lifecycle: null,
+      progress: null,
+      nextTask: null,
+      quality: null
+    };
+  }
+}
+
+module.exports = {
+  getProgress,
+  getNextTask,
+  getFullState
+};