cc-devflow 4.1.4 → 4.1.6

package/docs/guides/getting-started.zh-CN.md

@@ -42,37 +42,35 @@ python3 .claude/scripts/demo.py
 ### 1. 启动需求开发
 
 ```bash
-/flow-new "REQ-001|用户认证功能|https://docs.example.com/auth"
+/flow:init "REQ-001|用户认证功能|https://docs.example.com/auth"
+/flow:spec "REQ-001"
+/flow:dev "REQ-001"
+/flow:verify "REQ-001" --strict
+/flow:release "REQ-001"
 ```
 
 ### 2. 查看进度
 
 ```bash
-/flow-status REQ-001
+/flow:status REQ-001
 ```
 
 ### 3. 如果中断，恢复开发
 
 ```bash
-/flow-restart "REQ-001"
+/flow:dev "REQ-001" --resume
 ```
 
 ### 4. 验证一致性
 
 ```bash
-/flow-verify "REQ-001"
+/flow:verify "REQ-001" --strict
 ```
 
-### 5. 执行 QA
+### 5. 创建发布
 
 ```bash
-/flow-qa "REQ-001"
-```
-
-### 6. 创建发布
-
-```bash
-/flow-release "REQ-001"
+/flow:release "REQ-001"
 ```
 
 ## 📋 核心脚本

package/lib/compiler/__tests__/manifest.test.js

@@ -13,9 +13,13 @@
 const {
   MANIFEST_VERSION,
   createManifest,
+  createEntry,
   migrateToV2,
+  needsRecompile,
+  addEntry,
   addSkillEntry,
   addRulesEntry,
+  pruneCommandEntries,
   needsSkillRecompile,
   needsRulesRecompile,
   hashContent
@@ -87,6 +91,158 @@ describe('Manifest v2.0', () => {
     });
   });
 
+  describe('createEntry()', () => {
+    test('should persist sourceHash for incremental compile and target hash for drift check', () => {
+      const sourceHash = 'a'.repeat(64);
+      const targetHash = 'b'.repeat(64);
+      const entry = createEntry({
+        source: '.claude/commands/flow/init.md',
+        target: '.codex/prompts/flow/init.md',
+        sourceHash,
+        targetHash,
+        platform: 'codex'
+      });
+
+      expect(entry.sourceHash).toBe(sourceHash);
+      expect(entry.hash).toBe(targetHash);
+    });
+  });
+
+  describe('needsRecompile()', () => {
+    test('should return false when sourceHash is unchanged', () => {
+      const sourcePath = '.claude/commands/flow/init.md';
+      const sourceHash = hashContent('source content');
+      const manifest = createManifest();
+
+      manifest.entries.push({
+        source: sourcePath,
+        target: '.codex/prompts/flow/init.md',
+        hash: hashContent('target content'),
+        sourceHash,
+        platform: 'codex'
+      });
+
+      expect(needsRecompile(sourcePath, sourceHash, manifest, 'codex')).toBe(false);
+    });
+
+    test('should return true for legacy entries without sourceHash', () => {
+      const sourcePath = '.claude/commands/flow/init.md';
+      const sourceHash = hashContent('source content');
+      const manifest = createManifest();
+
+      manifest.entries.push({
+        source: sourcePath,
+        target: '.codex/prompts/flow/init.md',
+        hash: sourceHash,
+        platform: 'codex'
+      });
+
+      expect(needsRecompile(sourcePath, sourceHash, manifest, 'codex')).toBe(true);
+    });
+
+    test('should return false when all split outputs share same sourceHash', () => {
+      const sourcePath = '.claude/commands/flow/init.md';
+      const sourceHash = hashContent('source content');
+      const manifest = createManifest();
+
+      manifest.entries.push({
+        source: sourcePath,
+        target: '.agent/workflows/flow/init.md',
+        hash: hashContent('output a'),
+        sourceHash,
+        platform: 'antigravity'
+      });
+      manifest.entries.push({
+        source: sourcePath,
+        target: '.agent/workflows/flow/init.toml',
+        hash: hashContent('output b'),
+        sourceHash,
+        platform: 'antigravity'
+      });
+
+      expect(needsRecompile(sourcePath, sourceHash, manifest, 'antigravity')).toBe(false);
+    });
+  });
+
+  describe('addEntry()', () => {
+    test('should keep multiple outputs for same source and platform', () => {
+      const manifest = createManifest();
+      addEntry(manifest, {
+        source: '.claude/commands/flow/init.md',
+        target: '.agent/workflows/flow/init.md',
+        hash: 'a',
+        sourceHash: 'sa',
+        platform: 'antigravity'
+      });
+      addEntry(manifest, {
+        source: '.claude/commands/flow/init.md',
+        target: '.agent/workflows/flow/init.toml',
+        hash: 'b',
+        sourceHash: 'sa',
+        platform: 'antigravity'
+      });
+
+      expect(manifest.entries).toHaveLength(2);
+    });
+
+    test('should update only the matching output target', () => {
+      const manifest = createManifest();
+      addEntry(manifest, {
+        source: '.claude/commands/flow/init.md',
+        target: '.agent/workflows/flow/init.md',
+        hash: 'a',
+        sourceHash: 'sa',
+        platform: 'antigravity'
+      });
+      addEntry(manifest, {
+        source: '.claude/commands/flow/init.md',
+        target: '.agent/workflows/flow/init.toml',
+        hash: 'b',
+        sourceHash: 'sa',
+        platform: 'antigravity'
+      });
+      addEntry(manifest, {
+        source: '.claude/commands/flow/init.md',
+        target: '.agent/workflows/flow/init.md',
+        hash: 'c',
+        sourceHash: 'sb',
+        platform: 'antigravity'
+      });
+
+      expect(manifest.entries).toHaveLength(2);
+      expect(
+        manifest.entries.find(entry => entry.target === '.agent/workflows/flow/init.md')
+      ).toMatchObject({ hash: 'c', sourceHash: 'sb' });
+      expect(
+        manifest.entries.find(entry => entry.target === '.agent/workflows/flow/init.toml')
+      ).toMatchObject({ hash: 'b', sourceHash: 'sa' });
+    });
+  });
+
+  describe('pruneCommandEntries()', () => {
+    test('should remove stale command entries for selected platforms only', () => {
+      const manifest = createManifest();
+      manifest.entries = [
+        { source: '.claude/commands/flow/init.md', target: '.codex/prompts/flow/init.md', hash: '1', platform: 'codex' },
+        { source: '.claude/commands/flow/old.md', target: '.codex/prompts/flow/old.md', hash: '2', platform: 'codex' },
+        { source: '.claude/commands/flow/old.md', target: '.qwen/commands/flow/old.toml', hash: '3', platform: 'qwen' },
+        { source: '.claude/rules/base.md', target: '.cursor/rules/base.mdc', hash: '4', platform: 'cursor' }
+      ];
+
+      const removed = pruneCommandEntries(manifest, {
+        sourcePrefix: '.claude/commands',
+        activeSources: new Set(['.claude/commands/flow/init.md']),
+        platforms: ['codex', 'cursor']
+      });
+
+      expect(removed).toBe(1);
+      expect(manifest.entries).toHaveLength(3);
+      expect(manifest.entries.find(e => e.target === '.codex/prompts/flow/old.md')).toBeUndefined();
+      expect(manifest.entries.find(e => e.target === '.qwen/commands/flow/old.toml')).toBeDefined();
+      expect(manifest.entries.find(e => e.target === '.cursor/rules/base.mdc')).toBeDefined();
+    });
+  });
+
   describe('addSkillEntry()', () => {
     test('should add new skill entry', () => {
       const manifest = createManifest();

package/lib/compiler/__tests__/parser.test.js

@@ -479,6 +479,27 @@ Body`);
       }
     });
 
+    it('should ignore CLAUDE.md documentation files', async () => {
+      const tmpDir = path.join(os.tmpdir(), `test-claude-doc-${Date.now()}`);
+      const flowDir = path.join(tmpDir, 'flow');
+      fs.mkdirSync(flowDir, { recursive: true });
+
+      fs.writeFileSync(path.join(flowDir, 'CLAUDE.md'), '# flow docs only');
+      fs.writeFileSync(path.join(flowDir, 'init.md'), `---
+name: flow-init
+description: Flow init command
+---
+Body`);
+
+      try {
+        const result = await parser.parseAllCommands(tmpDir);
+        expect(result).toHaveLength(1);
+        expect(result[0].source.filename).toBe('flow/init');
+      } finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      }
+    });
+
     it('should preserve relative subpath in source filename', async () => {
       const tmpDir = path.join(os.tmpdir(), `test-relpath-${Date.now()}`);
       const flowDir = path.join(tmpDir, 'flow');

package/lib/compiler/index.js

@@ -33,6 +33,7 @@ const {
   migrateToV2,
   addSkillEntry,
   addRulesEntry,
+  pruneCommandEntries,
   needsSkillRecompile,
   needsRulesRecompile,
   MANIFEST_PATH
@@ -371,6 +372,8 @@ async function compile(options = {}) {
     skillsRegistered: 0,
     errors: []
   };
+  const absoluteOutputBaseDir = path.resolve(outputBaseDir);
+  const toManifestPath = (absolutePath) => path.relative(absoluteOutputBaseDir, absolutePath).replace(/\\/g, '/');
 
   // 加载 manifest 并迁移到 v2.0
   const manifestPath = path.join(outputBaseDir, MANIFEST_PATH);
@@ -445,6 +448,19 @@ async function compile(options = {}) {
     console.log(`Found ${irs.length} command files`);
   }
 
+  // 清理已删除命令文件的旧 manifest 条目，避免多平台漂移噪音
+  const sourcePrefix = toManifestPath(absoluteSourceDir).replace(/\/+$/, '');
+  const activeSources = new Set(irs.map(ir => toManifestPath(ir.source.path)));
+  const prunedEntries = pruneCommandEntries(manifest, {
+    sourcePrefix,
+    activeSources,
+    platforms
+  });
+
+  if (verbose && prunedEntries > 0) {
+    console.log(`Pruned ${prunedEntries} stale command entries from manifest`);
+  }
+
   // 生成规则入口文件
   if (rules && registry) {
     try {
@@ -494,7 +510,7 @@ async function compile(options = {}) {
   for (const ir of irs) {
     for (const platform of platforms) {
       // 检查是否需要重新编译
-      const sourceRelative = path.relative(outputBaseDir, ir.source.path);
+      const sourceRelative = toManifestPath(ir.source.path);
       if (!needsRecompile(sourceRelative, ir.source.hash, manifest, platform)) {
         result.filesSkipped++;
         if (verbose) {

package/lib/compiler/manifest.js

@@ -31,13 +31,19 @@ function hashContent(content) {
 // createEntry - 创建 manifest 条目
 // ============================================================
 function createEntry({ source, target, sourceHash, targetHash, platform }) {
-  return {
+  const entry = {
     source,
     target,
-    hash: sourceHash,
+    hash: targetHash || sourceHash,
     timestamp: new Date().toISOString(),
     platform
   };
+
+  if (sourceHash) {
+    entry.sourceHash = sourceHash;
+  }
+
+  return entry;
 }
 
 // ============================================================
@@ -72,19 +78,29 @@ function needsRecompile(sourcePath, sourceHash, manifest, platform) {
     return true;
   }
 
-  const entry = manifest.entries.find(e => e.source === sourcePath && e.platform === platform);
-  if (!entry) {
+  const scopedEntries = manifest.entries.filter(
+    entry => entry.source === sourcePath && entry.platform === platform
+  );
+  if (scopedEntries.length === 0) {
+    return true;
+  }
+
+  // Legacy entries (v1/v2 early) stored source hash in `hash`.
+  // Force one-time recompile to migrate to explicit `sourceHash`.
+  if (scopedEntries.some(entry => !entry.sourceHash)) {
     return true;
   }
 
-  return entry.hash !== sourceHash;
+  return scopedEntries.some(entry => entry.sourceHash !== sourceHash);
 }
 
 // ============================================================
 // addEntry - 添加或更新条目
 // ============================================================
 function addEntry(manifest, entry) {
-  const existingIndex = manifest.entries.findIndex(e => e.source === entry.source && e.platform === entry.platform);
+  const existingIndex = manifest.entries.findIndex(
+    e => e.source === entry.source && e.platform === entry.platform && e.target === entry.target
+  );
 
   if (existingIndex >= 0) {
     manifest.entries[existingIndex] = entry;
@@ -93,6 +109,51 @@ function addEntry(manifest, entry) {
   }
 }
 
+// ============================================================
+// pruneCommandEntries - 清理已删除命令文件对应的旧条目
+// ============================================================
+function pruneCommandEntries(manifest, options = {}) {
+  if (!manifest || !Array.isArray(manifest.entries) || manifest.entries.length === 0) {
+    return 0;
+  }
+
+  const {
+    sourcePrefix = '.claude/commands',
+    activeSources = new Set(),
+    platforms = null
+  } = options;
+
+  const normalizePath = (value) => String(value || '').replace(/\\/g, '/');
+  const normalizedPrefix = normalizePath(sourcePrefix).replace(/\/+$/, '');
+  const normalizedActiveSources = new Set(
+    Array.from(activeSources).map(source => normalizePath(source))
+  );
+  const platformSet = Array.isArray(platforms) ? new Set(platforms) : null;
+
+  let removed = 0;
+  manifest.entries = manifest.entries.filter(entry => {
+    if (platformSet && !platformSet.has(entry.platform)) {
+      return true;
+    }
+
+    const source = normalizePath(entry.source);
+    const inScope = source === normalizedPrefix || source.startsWith(`${normalizedPrefix}/`);
+
+    if (!inScope) {
+      return true;
+    }
+
+    if (normalizedActiveSources.has(source)) {
+      return true;
+    }
+
+    removed += 1;
+    return false;
+  });
+
+  return removed;
+}
+
 // ============================================================
 // checkDrift - 检查漂移（目标文件被手动修改）
 // ============================================================
@@ -237,6 +298,7 @@ module.exports = {
   migrateToV2,
   addSkillEntry,
   addRulesEntry,
+  pruneCommandEntries,
   needsSkillRecompile,
   needsRulesRecompile
 };

package/lib/compiler/parser.js

@@ -35,6 +35,7 @@ const TEMPLATE_PATTERN = /\{TEMPLATE:([^}]+)\}/g;
 const GUIDE_PATTERN = /\{GUIDE:([^}]+)\}/g;
 const AGENT_SCRIPT_PATTERN = /\{AGENT_SCRIPT\}/g;
 const ARGUMENTS_PATTERN = /\$ARGUMENTS/g;
+const IGNORED_MARKDOWN_FILES = new Set(['CLAUDE.MD']);
 
 // ============================================================
 // hashContent - 计算 SHA-256 哈希
@@ -270,6 +271,10 @@ function collectMarkdownFiles(rootDir, currentDir) {
       continue;
     }
 
+    if (IGNORED_MARKDOWN_FILES.has(entry.name.toUpperCase())) {
+      continue;
+    }
+
     results.push(path.join(currentDir, entry.name));
   }
 

package/lib/harness/CLAUDE.md

@@ -0,0 +1,21 @@
+# harness/
+> L2 | 父级: /Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/CLAUDE.md
+
+成员清单
+index.js: 聚合导出 harness 基础模块，供 CLI 与测试统一引用。
+schemas.js: 定义 manifest/report/checkpoint 的 Zod 契约，阻断脏数据进入执行层。
+store.js: 提供路径规范、JSON/文本读写、JSONL 事件记录与 shell 命令执行。
+planner.js: 将 TASKS.md 解析为 dependency-aware 的 task-manifest.json。
+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/resume.js: 恢复中断任务并复用 dispatch 继续执行。
+operations/verify.js: 执行 quick/strict 质量门禁并输出 report-card.json。
+operations/release.js: 读取通过的 report-card，生成 RELEASE_NOTE 并标记 released。
+operations/janitor.js: 清理过期 runtime 工件，保留运行中任务状态。
+
+法则: 成员完整·一行一文件·父级链接·技术词前置
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/lib/harness/cli.js

@@ -0,0 +1,208 @@
+/**
+ * [INPUT]: 依赖 operations 子模块与命令行参数。
+ * [OUTPUT]: 对外提供 runCli(argv) 统一命令分发入口。
+ * [POS]: harness 命令编排层，被 bin/harness.js 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  resolveRepoRoot,
+  ChangeIdSchema
+} = require('./index');
+const { runInit } = require('./operations/init');
+const { runPack } = require('./operations/pack');
+const { runPlan } = require('./operations/plan');
+const { runDispatch } = require('./operations/dispatch');
+const { runResume } = require('./operations/resume');
+const { runVerify } = require('./operations/verify');
+const { runRelease } = require('./operations/release');
+const { runJanitor } = require('./operations/janitor');
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const args = {
+    command,
+    changeId: null,
+    goal: null,
+    parallel: 3,
+    maxRetries: undefined,
+    strict: false,
+    skipReview: false,
+    overwrite: false,
+    hours: 72
+  };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const token = rest[i];
+
+    if (token === '--change-id') {
+      args.changeId = rest[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (token === '--goal') {
+      args.goal = rest[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (token === '--parallel') {
+      args.parallel = Number.parseInt(rest[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (token === '--max-retries') {
+      args.maxRetries = Number.parseInt(rest[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (token === '--hours') {
+      args.hours = Number.parseInt(rest[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (token === '--strict') {
+      args.strict = true;
+      continue;
+    }
+
+    if (token === '--skip-review') {
+      args.skipReview = true;
+      continue;
+    }
+
+    if (token === '--overwrite') {
+      args.overwrite = true;
+      continue;
+    }
+  }
+
+  return args;
+}
+
+function showHelp() {
+  console.log(`
+Usage: node bin/harness.js <command> [options]
+
+Commands:
+  init      --change-id <REQ-ID> [--goal "..."]
+  pack      --change-id <REQ-ID> [--goal "..."]
+  plan      --change-id <REQ-ID> [--goal "..."] [--overwrite]
+  dispatch  --change-id <REQ-ID> [--parallel 3] [--max-retries 2]
+  resume    --change-id <REQ-ID> [--parallel 3] [--max-retries 2]
+  verify    --change-id <REQ-ID> [--strict] [--skip-review]
+  release   --change-id <REQ-ID>
+  janitor   [--hours 72]
+`);
+}
+
+function requireChangeId(changeId) {
+  const parsed = ChangeIdSchema.safeParse(changeId);
+  if (!parsed.success) {
+    throw new Error('Missing or invalid --change-id (expected REQ-123 or BUG-123)');
+  }
+  return parsed.data;
+}
+
+function printResult(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function runCli(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.command || args.command === 'help' || args.command === '--help' || args.command === '-h') {
+    showHelp();
+    return 0;
+  }
+
+  const repoRoot = resolveRepoRoot(process.cwd());
+
+  switch (args.command) {
+    case 'init': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runInit({ repoRoot, changeId, goal: args.goal });
+      printResult(result);
+      return 0;
+    }
+
+    case 'pack': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runPack({ repoRoot, changeId, goal: args.goal });
+      printResult(result);
+      return 0;
+    }
+
+    case 'plan': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runPlan({
+        repoRoot,
+        changeId,
+        goal: args.goal,
+        overwrite: args.overwrite
+      });
+      printResult(result);
+      return 0;
+    }
+
+    case 'dispatch': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runDispatch({
+        repoRoot,
+        changeId,
+        parallel: args.parallel,
+        maxRetries: Number.isInteger(args.maxRetries) ? args.maxRetries : undefined
+      });
+      printResult(result);
+      return result.success ? 0 : 1;
+    }
+
+    case 'resume': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runResume({
+        repoRoot,
+        changeId,
+        parallel: args.parallel,
+        maxRetries: Number.isInteger(args.maxRetries) ? args.maxRetries : undefined
+      });
+      printResult(result);
+      return result.success ? 0 : 1;
+    }
+
+    case 'verify': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runVerify({
+        repoRoot,
+        changeId,
+        strict: args.strict,
+        skipReview: args.skipReview
+      });
+      printResult(result);
+      return result.overall === 'pass' ? 0 : 1;
+    }
+
+    case 'release': {
+      const changeId = requireChangeId(args.changeId);
+      const result = await runRelease({ repoRoot, changeId });
+      printResult(result);
+      return 0;
+    }
+
+    case 'janitor': {
+      const result = await runJanitor({ repoRoot, hours: args.hours });
+      printResult(result);
+      return 0;
+    }
+
+    default:
+      throw new Error(`Unknown harness command: ${args.command}`);
+  }
+}
+
+module.exports = {
+  runCli
+};

package/lib/harness/index.js

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