cc-devflow 4.5.5 → 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`
 
@@ -94,7 +97,7 @@ Capability truth lives in `devflow/specs/`.
 Change truth lives in `devflow/changes/<change>/`.
 
 - Keep `INDEX.md` plus capability markdown under `devflow/specs/`.
-- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` are separate number sequences; old lowercase directories are compatibility reads only.
+- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` advance as separate local sequences, so cross-prefix duplicates are valid. Parallel worktrees may still repeat numbers; the full change key, especially the description, distinguishes the work. Old lowercase directories are compatibility reads only.
 - Keep `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`.
 - Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 
@@ -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,13 +89,14 @@ 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`
 
 durable truth 分两层：
 
 - `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
-- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，旧小写目录只作为历史兼容读取。
+- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 的描述负责区分业务内容，旧小写目录只作为历史兼容读取。
 - `devflow/changes/<change>/`：变更真相，保留 `change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、可选 `team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一的最终 handoff 文件。
 - worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 
@@ -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__/autopilot.test.js

@@ -55,9 +55,10 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       [
         '- [ ] T001 启动 autopilot 闭环 (src/a.ts)',
         '- [ ] T002 多文件委派任务 [P] (src/a.ts,src/b.ts)'
@@ -67,14 +68,14 @@ describe('runAutopilot', () => {
     const result = await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop'
+      goal
     });
 
     const runtimeState = JSON.parse(fs.readFileSync(getRuntimeStatePath(repoRoot, 'REQ-123'), 'utf8'));
 
     expect(result.executed).toEqual(['init', 'snapshot', 'plan']);
     expect(result.currentStage).toBe('approve');
-    expect(runtimeState.changeKey).toBe('REQ-123-change');
+    expect(runtimeState.changeKey).toBe('REQ-123-ship-thin-autopilot-loop');
     expect(fs.existsSync(getReportCardPath(repoRoot, 'REQ-123'))).toBe(false);
     expect(fs.existsSync(getIntentPrBriefPath(repoRoot, 'REQ-123'))).toBe(false);
     expect(fs.existsSync(getIntentResumeIndexPath(repoRoot, 'REQ-123'))).toBe(false);
@@ -93,9 +94,10 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop with delegated workers';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       [
         '- [ ] T001 直接执行任务 (src/a.ts)',
         '- [ ] T002 委派实现任务 [P] (src/a.ts,src/b.ts)'
@@ -105,7 +107,7 @@ describe('runAutopilot', () => {
     await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop with delegated workers'
+      goal
     });
 
     await runApprove({
@@ -160,16 +162,17 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop and release';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       '- [ ] T001 发布前收尾 (src/a.ts)'
     );
 
     await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop and release'
+      goal
     });
 
     await runApprove({

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', () => {
@@ -39,4 +40,108 @@ describe('change directory naming', () => {
 
     fs.rmSync(repoRoot, { recursive: true, force: true });
   });
+
+  test('allows duplicate numbers when descriptions differ', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-paths-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-existing-plan'), { recursive: true });
+
+    const paths = getChangePaths(repoRoot, 'REQ-123', { goal: 'Another plan' });
+
+    expect(paths.changeKey).toBe('REQ-123-another-plan');
+    expect(paths.changeDir).toBe(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-another-plan'));
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('requires explicit change keys when duplicate numbers already exist', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-paths-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-first-plan'), { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-second-plan'), { recursive: true });
+
+    expect(() => getChangePaths(repoRoot, 'REQ-123'))
+      .toThrow(/Ambiguous changeId "REQ-123"/);
+    expect(getChangePaths(repoRoot, 'REQ-123', { changeKey: 'REQ-123-second-plan' }).changeKey)
+      .toBe('REQ-123-second-plan');
+
+    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/__tests__/query.test.js

@@ -324,6 +324,55 @@ describe('query helpers', () => {
     expect(listQueryIds()).toEqual(expect.arrayContaining(['full-state', 'next-task', 'progress']));
   });
 
+  test('requires a full change key when duplicate local numbers exist', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-duplicate-key-'));
+    const firstKey = 'REQ-132-first-plan';
+    const secondKey = 'REQ-132-second-plan';
+
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', firstKey), { recursive: true });
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-132', { changeKey: secondKey }), {
+      changeId: 'REQ-132',
+      goal: 'Resolve duplicate local numbers',
+      createdAt: '2026-05-08T01:00:00.000Z',
+      updatedAt: '2026-05-08T01:05:00.000Z',
+      tasks: [
+        { id: 'T001', status: 'passed' },
+        { id: 'T002', status: 'pending' }
+      ],
+      metadata: {
+        source: 'test',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    await expect(runQuery('progress', { repoRoot, changeId: 'REQ-132' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'progress',
+      error: {
+        message: expect.stringContaining('Ambiguous changeId "REQ-132"')
+      },
+      trace: {
+        event: 'query.progress.failed',
+        nextAction: 'inspect-runtime-artifacts'
+      }
+    });
+
+    await expect(runQuery('progress', {
+      repoRoot,
+      changeId: 'REQ-132',
+      changeKey: secondKey
+    })).resolves.toMatchObject({
+      ok: true,
+      queryId: 'progress',
+      data: {
+        totalTasks: 2,
+        completedTasks: 1,
+        pendingTasks: 1
+      }
+    });
+  });
+
   test('returns a named error for unknown query ids', async () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-unknown-'));
 

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/artifacts.js

@@ -68,8 +68,8 @@ function getLegacyIntentProjectionPaths(repoRoot, goalId, taskIds = [], options
   ];
 }
 
-async function ensureIntentScaffold(repoRoot, goalId) {
-  const change = getChangePaths(repoRoot, goalId);
+async function ensureIntentScaffold(repoRoot, goalId, options = {}) {
+  const change = getChangePaths(repoRoot, goalId, options);
 
   await ensureDir(change.changeDir);
   await ensureDir(change.metaDir);