cc-devflow 4.5.6 → 4.5.7

package/docs/guides/getting-started.md

@@ -11,13 +11,13 @@ CC-DevFlow has two entry paths:
 - `cc-devflow init`: install the whole `.claude` pack into your project
 - `cc-devflow adapt`: generate platform outputs such as Codex rules
 
-The workflow itself is driven by six visible skills:
+The core workflow is driven by six visible skills, with `cc-review` available as an optional deep review pass:
 
 ```text
 cc-roadmap
 
-PDCA: cc-plan -> cc-do -> cc-check -> cc-act
-IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+PDCA: cc-plan -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
 ```
 
 The public skills are the visible harness. Each distributed `SKILL.md` now carries structured frontmatter plus a `Harness Contract`, and each `PLAYBOOK.md` carries the stage transition rules in a `Visible State Machine` section.
@@ -36,7 +36,7 @@ The public skills are the visible harness. Each distributed `SKILL.md` now carri
 npx cc-devflow init --dir /path/to/your/project
 ```
 
-The whole-pack install includes the six visible workflow skills plus `cc-spec-init` and `cc-simplify` as maintenance helpers.
+The whole-pack install includes the six core workflow skills, optional `cc-review`, plus `cc-spec-init` and `cc-simplify` as maintenance helpers.
 
 ### Single Skill Install
 
@@ -75,10 +75,12 @@ Use the skills in this order:
 ```text
 1. cc-roadmap
 2. choose cc-plan or cc-investigate
-3. cc-do
-4. cc-check
-5. cc-act
-6. repeat
+3. optional cc-review for complex frozen plans or investigations
+4. cc-do
+5. optional cc-review for complex implementations
+6. cc-check
+7. cc-act
+8. repeat
 ```
 
 Typical outputs:
@@ -87,6 +89,7 @@ Typical outputs:
 - `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
 - `cc-plan` writes `planning/design.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
 - `cc-investigate` writes `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
+- `cc-review` writes `cc-review-report.md` and optional structured findings for deep plan or implementation review
 - `cc-check` writes `report-card.json`
 - `cc-act` writes exactly one final handoff file: `handoff/pr-brief.md`, `handoff/resume-index.md`, or `handoff/release-note.md`
 
@@ -151,7 +154,7 @@ npx cc-devflow adapt --cwd /path/to/your/project --platform codex
 
 If your project has no optional `.claude/commands/` input, this is expected: the compiler will still generate the skills registry and mirror the distributed skill set for Codex.
 
-Codex mirrors the distributed skills from `.claude/skills/<skill>/` into `.codex/skills/<skill>/`. That set includes the six public workflow skills plus `cc-spec-init` and `cc-simplify`, and the mirror is additive-only: existing project-owned Codex skills are preserved instead of being deleted.
+Codex mirrors the distributed skills from `.claude/skills/<skill>/` into `.codex/skills/<skill>/`. That set includes the six core workflow skills, optional `cc-review`, `cc-spec-init`, and `cc-simplify`, and the mirror is additive-only: existing project-owned Codex skills are preserved instead of being deleted.
 
 ### Keep skills and examples in sync
 

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

@@ -11,13 +11,13 @@ CC-DevFlow 现在有两条入口：
 - `cc-devflow init`：把整包 `.claude` 安装到你的项目里
 - `cc-devflow adapt`：生成 Codex、Cursor、Qwen、Antigravity 等平台产物
 
-真正的工作流由 6 个可见 Skill 组成：
+核心工作流由 6 个可见 Skill 组成，复杂工作可选 `cc-review` 做深度 Review：
 
 ```text
 cc-roadmap
 
-PDCA: cc-plan -> cc-do -> cc-check -> cc-act
-IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+PDCA: cc-plan -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
 ```
 
 公开 Skill 本身就是可见 harness。现在每个分发 `SKILL.md` 都带结构化 frontmatter 和 `Harness Contract`，每个 `PLAYBOOK.md` 都带 `Visible State Machine`，不再依赖隐藏运行时语义来理解阶段流转。
@@ -36,7 +36,7 @@ IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 npx cc-devflow init --dir /path/to/your/project
 ```
 
-整包安装会带上 6 个可见 workflow skill，以及维护用的 `cc-spec-init` 和 `cc-simplify`。
+整包安装会带上 6 个核心 workflow skill、可选 `cc-review`，以及维护用的 `cc-spec-init` 和 `cc-simplify`。
 
 ### 单个 Skill 安装
 
@@ -75,10 +75,12 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 ```text
 1. cc-roadmap
 2. 在 cc-plan 和 cc-investigate 里二选一
-3. cc-do
-4. cc-check
-5. cc-act
-6. repeat
+3. 复杂计划或调查根因冻结后可选 cc-review
+4. cc-do
+5. 复杂实现可选 cc-review
+6. cc-check
+7. cc-act
+8. repeat
 ```
 
 常见产物：
@@ -87,6 +89,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 - `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
 - `cc-plan` 产出 `planning/design.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
 - `cc-investigate` 产出 `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
+- `cc-review` 产出 `cc-review-report.md`，以及可选的结构化深度 Review findings
 - `cc-check` 产出 `report-card.json`
 - `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
 
@@ -150,7 +153,7 @@ npx cc-devflow adapt --cwd /path/to/your/project --platform codex
 
 如果你的项目没有可选的 `.claude/commands/` 输入目录，这也是正常的；编译器仍然会生成 skills registry，并为 Codex 镜像正式分发 skill 集合。
 
-Codex 现在会把正式分发的 skill 从 `.claude/skills/<skill>/` 镜像到 `.codex/skills/<skill>/`。这套集合包含 6 个公开 workflow skill 和维护类 skill `cc-spec-init`、`cc-simplify`，并且镜像是纯增量的：项目里已有的自定义 Codex skill 不会被删除。
+Codex 现在会把正式分发的 skill 从 `.claude/skills/<skill>/` 镜像到 `.codex/skills/<skill>/`。这套集合包含 6 个核心 workflow skill、可选 `cc-review` 和维护类 skill `cc-spec-init`、`cc-simplify`，并且镜像是纯增量的：项目里已有的自定义 Codex skill 不会被删除。
 
 ### 保持 skill 和样例同步
 

package/lib/skill-runtime/__tests__/archive-change.test.js

@@ -0,0 +1,124 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { archiveChange, restoreChange, listArchived, getArchiveRoot } = require('../archive-change');
+
+function makeTempRepo() {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-archive-'));
+  const changesDir = path.join(repoRoot, 'devflow', 'changes');
+  fs.mkdirSync(changesDir, { recursive: true });
+  return repoRoot;
+}
+
+afterEach(() => {});
+
+describe('archiveChange', () => {
+  test('moves change directory to archive/YYYY-MM/', () => {
+    const repoRoot = makeTempRepo();
+    const changeDir = path.join(repoRoot, 'devflow', 'changes', 'REQ-001-feature');
+    fs.mkdirSync(changeDir, { recursive: true });
+    fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# test');
+
+    const result = archiveChange(repoRoot, 'REQ-001-feature');
+    const month = new Date().toISOString().slice(0, 7);
+
+    expect(result.month).toBe(month);
+    expect(fs.existsSync(result.archived)).toBe(true);
+    expect(fs.existsSync(path.join(result.archived, 'proposal.md'))).toBe(true);
+    expect(fs.existsSync(changeDir)).toBe(false);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('throws when change directory does not exist', () => {
+    const repoRoot = makeTempRepo();
+
+    expect(() => archiveChange(repoRoot, 'REQ-999-nonexistent'))
+      .toThrow(/not found/);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('throws when archive target already exists', () => {
+    const repoRoot = makeTempRepo();
+    const changeDir = path.join(repoRoot, 'devflow', 'changes', 'REQ-001-dup');
+    fs.mkdirSync(changeDir, { recursive: true });
+
+    const month = new Date().toISOString().slice(0, 7);
+    const existingArchive = path.join(getArchiveRoot(repoRoot), month, 'REQ-001-dup');
+    fs.mkdirSync(existingArchive, { recursive: true });
+
+    expect(() => archiveChange(repoRoot, 'REQ-001-dup'))
+      .toThrow(/already exists/);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+});
+
+describe('restoreChange', () => {
+  test('moves archived directory back to changes/', () => {
+    const repoRoot = makeTempRepo();
+    const archivedDir = path.join(repoRoot, 'devflow', 'changes', 'archive', '2026-04', 'REQ-002-restored');
+    fs.mkdirSync(archivedDir, { recursive: true });
+    fs.writeFileSync(path.join(archivedDir, 'tasks.md'), '- [ ] task');
+
+    const result = restoreChange(repoRoot, archivedDir);
+
+    expect(result.changeKey).toBe('REQ-002-restored');
+    expect(fs.existsSync(result.restored)).toBe(true);
+    expect(fs.existsSync(path.join(result.restored, 'tasks.md'))).toBe(true);
+    expect(fs.existsSync(archivedDir)).toBe(false);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('throws when archived directory does not exist', () => {
+    const repoRoot = makeTempRepo();
+
+    expect(() => restoreChange(repoRoot, '/tmp/nonexistent-archive-path'))
+      .toThrow(/not found/);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('throws when change already exists in active directory', () => {
+    const repoRoot = makeTempRepo();
+    const activeDir = path.join(repoRoot, 'devflow', 'changes', 'REQ-003-conflict');
+    fs.mkdirSync(activeDir, { recursive: true });
+
+    const archivedDir = path.join(repoRoot, 'devflow', 'changes', 'archive', '2026-03', 'REQ-003-conflict');
+    fs.mkdirSync(archivedDir, { recursive: true });
+
+    expect(() => restoreChange(repoRoot, archivedDir))
+      .toThrow(/already exists/);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+});
+
+describe('listArchived', () => {
+  test('returns empty array when no archive exists', () => {
+    const repoRoot = makeTempRepo();
+    expect(listArchived(repoRoot)).toEqual([]);
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('lists archived changes across months', () => {
+    const repoRoot = makeTempRepo();
+    const archiveRoot = getArchiveRoot(repoRoot);
+
+    fs.mkdirSync(path.join(archiveRoot, '2026-03', 'REQ-001-old'), { recursive: true });
+    fs.mkdirSync(path.join(archiveRoot, '2026-04', 'FIX-002-bugfix'), { recursive: true });
+    fs.mkdirSync(path.join(archiveRoot, '2026-04', 'REQ-003-another'), { recursive: true });
+
+    const items = listArchived(repoRoot);
+
+    expect(items).toHaveLength(3);
+    expect(items[0]).toEqual(expect.objectContaining({ month: '2026-03', changeKey: 'REQ-001-old' }));
+    expect(items[1]).toEqual(expect.objectContaining({ month: '2026-04', changeKey: 'FIX-002-bugfix' }));
+    expect(items[2]).toEqual(expect.objectContaining({ month: '2026-04', changeKey: 'REQ-003-another' }));
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+});

package/lib/skill-runtime/__tests__/cli-bootstrap.integration.test.js

@@ -199,6 +199,7 @@ describe('cc-devflow cli distribution bootstrap', () => {
     expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-plan', 'SKILL.md'))).toBe(true);
     expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-investigate', 'SKILL.md'))).toBe(true);
     expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-do', 'SKILL.md'))).toBe(true);
+    expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-review', 'SKILL.md'))).toBe(true);
     expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-check', 'SKILL.md'))).toBe(true);
     expect(fs.existsSync(path.join(repoRoot, '.codex', 'skills', 'cc-act', 'SKILL.md'))).toBe(true);
 

package/lib/skill-runtime/__tests__/paths.test.js

@@ -5,7 +5,8 @@ const path = require('path');
 const {
   buildChangeKey,
   getChangePaths,
-  getChangeSlug
+  getChangeSlug,
+  nextChangeKey
 } = require('../paths');
 
 describe('change directory naming', () => {
@@ -65,3 +66,82 @@ describe('change directory naming', () => {
     fs.rmSync(repoRoot, { recursive: true, force: true });
   });
 });
+
+describe('nextChangeKey', () => {
+  test('starts at 001 when no existing directories', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes'), { recursive: true });
+
+    const result = nextChangeKey(repoRoot, 'REQ', 'my feature');
+    expect(result.changeId).toBe('REQ-001');
+    expect(result.changeKey).toBe('REQ-001-my-feature');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('increments from existing max', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-001-first'), { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-002-second'), { recursive: true });
+
+    const result = nextChangeKey(repoRoot, 'REQ', 'third feature');
+    expect(result.changeId).toBe('REQ-003');
+    expect(result.changeKey).toBe('REQ-003-third-feature');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('REQ and FIX have independent numbering', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-005-feature'), { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'FIX-002-bugfix'), { recursive: true });
+
+    const reqResult = nextChangeKey(repoRoot, 'REQ', 'next req');
+    expect(reqResult.changeId).toBe('REQ-006');
+
+    const fixResult = nextChangeKey(repoRoot, 'FIX', 'next fix');
+    expect(fixResult.changeId).toBe('FIX-003');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('preserves existing padding width', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-0001-wide'), { recursive: true });
+
+    const result = nextChangeKey(repoRoot, 'REQ', 'narrow');
+    expect(result.changeId).toBe('REQ-0002');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('rejects invalid prefix', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes'), { recursive: true });
+
+    expect(() => nextChangeKey(repoRoot, 'BUG', 'test')).toThrow(/Invalid prefix/);
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('handles missing changes directory', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+
+    const result = nextChangeKey(repoRoot, 'FIX', 'first ever');
+    expect(result.changeId).toBe('FIX-001');
+    expect(result.changeKey).toBe('FIX-001-first-ever');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('slugifies Chinese descriptions', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-next-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes'), { recursive: true });
+
+    const result = nextChangeKey(repoRoot, 'REQ', '统一配置');
+    expect(result.changeId).toBe('REQ-001');
+    expect(result.changeKey).toBe('REQ-001-统一配置');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+});

package/lib/skill-runtime/archive-change.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+const path = require('path');
+const { getChangesRoot } = require('./paths.js');
+
+function getArchiveRoot(repoRoot) {
+  return path.join(getChangesRoot(repoRoot), 'archive');
+}
+
+function archiveChange(repoRoot, changeKey) {
+  const changesRoot = getChangesRoot(repoRoot);
+  const changeDir = path.join(changesRoot, changeKey);
+
+  if (!fs.existsSync(changeDir) || !fs.statSync(changeDir).isDirectory()) {
+    throw new Error(`Change directory not found: ${changeDir}`);
+  }
+
+  const month = new Date().toISOString().slice(0, 7);
+  const archiveDir = path.join(getArchiveRoot(repoRoot), month);
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  const dest = path.join(archiveDir, changeKey);
+  if (fs.existsSync(dest)) {
+    throw new Error(`Archive target already exists: ${dest}`);
+  }
+
+  fs.renameSync(changeDir, dest);
+  return { archived: dest, month };
+}
+
+function restoreChange(repoRoot, archivedPath) {
+  if (!fs.existsSync(archivedPath) || !fs.statSync(archivedPath).isDirectory()) {
+    throw new Error(`Archived directory not found: ${archivedPath}`);
+  }
+
+  const changeKey = path.basename(archivedPath);
+  const changesRoot = getChangesRoot(repoRoot);
+  const dest = path.join(changesRoot, changeKey);
+
+  if (fs.existsSync(dest)) {
+    throw new Error(`Change already exists in active directory: ${dest}`);
+  }
+
+  fs.mkdirSync(changesRoot, { recursive: true });
+  fs.renameSync(archivedPath, dest);
+  return { restored: dest, changeKey };
+}
+
+function listArchived(repoRoot) {
+  const archiveRoot = getArchiveRoot(repoRoot);
+  if (!fs.existsSync(archiveRoot)) return [];
+
+  const results = [];
+  for (const month of fs.readdirSync(archiveRoot, { withFileTypes: true })) {
+    if (!month.isDirectory()) continue;
+    const monthDir = path.join(archiveRoot, month.name);
+    for (const entry of fs.readdirSync(monthDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      results.push({ month: month.name, changeKey: entry.name, path: path.join(monthDir, entry.name) });
+    }
+  }
+  return results;
+}
+
+module.exports = { archiveChange, restoreChange, listArchived, getArchiveRoot };

package/lib/skill-runtime/paths.js

@@ -161,6 +161,37 @@ function resolveChangeKey(repoRoot, changeId, options = {}) {
   return buildChangeKey(changeId, options);
 }
 
+function nextChangeKey(repoRoot, prefix, description) {
+  const upper = String(prefix || '').toUpperCase();
+  if (upper !== 'REQ' && upper !== 'FIX') {
+    throw new Error(`Invalid prefix "${prefix}". Use REQ or FIX.`);
+  }
+
+  const numberPattern = new RegExp(`^${upper}-(\\d+)`);
+  let maxNum = 0;
+  let padWidth = 3;
+
+  for (const name of listChangeKeys(repoRoot)) {
+    const match = name.match(numberPattern);
+    if (match) {
+      const numStr = match[1];
+      const num = parseInt(numStr, 10);
+      if (num > maxNum) maxNum = num;
+      if (numStr.length > padWidth) padWidth = numStr.length;
+    }
+  }
+
+  const paddedNum = String(maxNum + 1).padStart(padWidth, '0');
+  const changeId = `${upper}-${paddedNum}`;
+  const slug = slugifySegment(
+    stripChangeIdPrefix(changeId, description) || description,
+    'change'
+  );
+  const changeKey = `${changeId}-${slug}`;
+
+  return { changeId, changeKey };
+}
+
 function getChangePaths(repoRoot, changeId, options = {}) {
   const changeKey = resolveChangeKey(repoRoot, changeId, options);
   const changeDir = path.join(getChangesRoot(repoRoot), changeKey);
@@ -226,6 +257,7 @@ module.exports = {
   getDevflowRoot,
   getChangesRoot,
   getWorkspacesRoot,
+  nextChangeKey,
   resolveChangeKey,
   buildChangeKey,
   getChangePaths,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.5.6",
+    "version": "4.5.7",
     "description": "Multi-platform CLI and skill pack for agent coding",
     "main": "bin/cc-devflow.js",
     "bin": {
@@ -14,6 +14,7 @@
         ".claude/skills/cc-plan/",
         ".claude/skills/cc-investigate/",
         ".claude/skills/cc-do/",
+        ".claude/skills/cc-review/",
         ".claude/skills/cc-check/",
         ".claude/skills/cc-act/",
         ".claude/skills/cc-spec-init/",