cc-devflow 4.5.5 → 4.5.7

package/.claude/skills/cc-roadmap/references/roadmap-dialogue.md

@@ -3,19 +3,20 @@
 ## Order
 
 0. 先做 `Context Snapshot`：现有 roadmap / backlog、capability specs、历史 design/analysis、最近提交、forcing functions、项目语言 / durable decisions
-1. 用户是谁
-2. 今天靠什么笨办法活着
-3. 最强需求证据是什么
-4. 为什么现在必须解决
-5. deadline / capacity / dependency / distribution 约束是什么
-6. 当前最大的 adoption / trust / delivery 卡点是什么
-7. 核心术语是否已有 canonical definition，是否和现有 capability spec / roadmap decision 冲突
-8. 最窄突破口是什么
-9. 6-12 个月后会长成什么
-10. 给出 2-3 条路线图形状并明确推荐
-11. 冻结 1-3 个阶段，写 exit signal / kill signal / non-goals
-12. 画出 `RM dependency graph`，标出串行主链和 parallel-ready wave
-13. 标出哪些事项真的 ready for `cc-plan`
+1. 先判断 project direction mode：founder-business / internal-company / hackathon-demo / open-source-research / learning / side-project / infrastructure / recovery
+2. 用户是谁
+3. 今天靠什么笨办法活着
+4. 最强需求证据是什么
+5. 为什么现在必须解决
+6. deadline / capacity / dependency / distribution 约束是什么
+7. 当前最大的 adoption / trust / delivery 卡点是什么
+8. 核心术语是否已有 canonical definition，是否和现有 capability spec / roadmap decision 冲突
+9. 最窄突破口是什么
+10. 6-12 个月后会长成什么
+11. 给出 2-3 条路线图形状并明确推荐
+12. 冻结 1-3 个阶段，写 exit signal / kill signal / non-goals
+13. 画出 `RM dependency graph`，标出串行主链和 parallel-ready wave
+14. 标出哪些事项真的 ready for `cc-plan`
 
 ## Question Rules
 
@@ -25,11 +26,25 @@
 - 没证据时明确写 assumption
 - 用户没批准前，不把事项偷下放成 requirement
 
+## Project Direction Modes
+
+- `founder-business`: 问 demand reality、status quo、specific human、narrowest paid wedge、observed behavior、future fit。允许给创业行动建议，但必须 source-neutral：找具体用户、看真实使用、验证付费或强行为、缩小本周 wedge。禁止品牌广告、申请建议、推广链接和外部权威背书。
+- `internal-company`: 问 sponsor、最小可批准 demo、组织依赖、维护 owner、reorg 风险。不要写对外市场叙事。
+- `hackathon-demo`: 问 wow moment、demo path、fallback、时间盒。不要先设计长期平台。
+- `open-source-research`: 问替代品、可复现 benchmark、贡献者 first success、维护边界。不要套商业销售漏斗。
+- `learning`: 问要学会什么、最小练习闭环、反馈方式。不要让生产级架构遮住学习目标。
+- `side-project`: 问自己会不会反复用、最酷可分享版本、最快可用路径。不要强行商业化。
+- `infrastructure`: 问调用方、workaround、失败成本、迁移/回滚、复用边界。不要虚构用户访谈。
+- `recovery`: 问事故证据、最小可信修复、防回归、kill signal、信任恢复。不要扩张新功能。
+
+如果 direction mode 变了，回到 route selection 重新算，不要沿用前一组问题。
+
 ## Route Shapes
 
 - `wedge-first`: 先用一个窄切口打穿真实需求
 - `platform-first`: 先做后面几阶段都会反复复用的底座
 - `rescue-first`: 先解决 adoption、trust、delivery 里最大的卡点
+- `decompose-first`: 先拆多个可独立交付系统，再决定每个系统的路线
 
 ## Output Rules
 

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/markdown.js

@@ -621,6 +621,20 @@ function renderParked(tracking) {
     .join('\n\n');
 }
 
+function renderProjectDirectionHandoff(tracking) {
+  const context = tracking.context || {};
+
+  return [
+    `- Project direction mode: ${formatBacklogValue(context.projectDirectionMode)}`,
+    `- Direction mode rationale: ${formatBacklogValue(context.projectDirectionRationale)}`,
+    `- Direction-specific questions selected: ${formatList(context.directionQuestionsSelected || [])}`,
+    `- Direction-specific questions skipped: ${formatList(context.directionQuestionsSkipped || [])}`,
+    `- Direction guardrails applied: ${formatList(context.directionGuardrailsApplied || [])}`,
+    `- Planning posture: ${formatBacklogValue(context.planningPosture)}`,
+    `- Evidence maturity: ${formatBacklogValue(context.evidenceMaturity)}`
+  ].join('\n');
+}
+
 function renderBacklogDocument({ backlogFile, trackingFile, tracking }) {
   const relativePath = path.relative(path.dirname(backlogFile), trackingFile).replace(/\\/g, '/');
   const displayPath = relativePath || path.basename(trackingFile);
@@ -651,6 +665,10 @@ function renderBacklogDocument({ backlogFile, trackingFile, tracking }) {
     `- Parallel-ready next wave: ${formatBacklogValue(tracking.dependencyHandoff.parallelReadyNextWave)}`,
     `- Notes on blockers: ${formatBacklogValue(tracking.dependencyHandoff.notesOnBlockers)}`,
     '',
+    '## Project Direction Handoff',
+    '',
+    renderProjectDirectionHandoff(tracking),
+    '',
     '## Ready For Req-Plan',
     '',
     renderReadyForReqPlan(tracking),

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/schema.js

@@ -78,6 +78,11 @@ const DEFAULT_ROADMAP_STATE = {
     currentFocusStage: ''
   },
   context: {
+    projectDirectionMode: '',
+    projectDirectionRationale: '',
+    directionQuestionsSelected: [],
+    directionQuestionsSkipped: [],
+    directionGuardrailsApplied: [],
     planningPosture: '',
     evidenceMaturity: '',
     canonicalTerms: [],
@@ -282,6 +287,9 @@ function normalizeRoadmapState(raw = {}) {
     context: {
       ...DEFAULT_ROADMAP_STATE.context,
       ...context,
+      directionQuestionsSelected: normalizeStringList(context.directionQuestionsSelected),
+      directionQuestionsSkipped: normalizeStringList(context.directionQuestionsSkipped),
+      directionGuardrailsApplied: normalizeStringList(context.directionGuardrailsApplied),
       canonicalTerms: normalizeStringList(context.canonicalTerms),
       durableDecisionSources: normalizeStringList(context.durableDecisionSources)
     },

package/CHANGELOG.md

@@ -9,6 +9,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.7] - 2026-05-10
+
+### Changed
+
+- Added public `cc-review` as an optional deep review skill that branches between plan-stage and implementation-stage review, keeps heavyweight methods in progressive references, checks in-scope code smells, and records Browser/Computer Use plus log evidence when UI or runtime behavior is involved.
+- Updated `cc-roadmap` and `cc-plan` with AI Leverage Route/Decision Lens gates that require real user/operator, status quo workaround, human-vs-agent effort, complete-lake boundary, ocean boundary, and boil-lake/sharp-wedge/needs-evidence/pivot verdicts before work becomes implementation-ready.
+- Updated `cc-plan` with an opt-in External Best-Practice Validation gate that records generalized search approval, source trust, repo-fit verdicts, and skip reasons in durable planning artifacts.
+- Updated `cc-plan` Decision Question options to require `A/B/C` lettered choices while keeping `D1` / `D2` as question IDs.
+
+## [4.5.6] - 2026-05-08
+
+### Changed
+
+- Updated `cc-plan` with a fixed Decision Question Protocol so approval gates use numbered questions, recommendations, option tradeoffs, impact, and STOP instead of ad hoc prose.
+- Updated `cc-plan` to treat the full `REQ/FIX-<number>-<description>` change key as identity, so repeated numbers from parallel worktrees stay distinct.
+
+### Fixed
+
+- Fixed typed runtime queries and `cc-devflow query` so duplicate local change numbers can be resolved with an explicit `--change-key`.
+- Fixed ambiguous query path resolution so duplicate change ids return a structured JSON failure instead of escaping the query registry.
+
 ## [4.5.5] - 2026-05-06
 
 ### Changed

package/README.md

@@ -14,13 +14,13 @@ CC-DevFlow is a small, explicit workflow system for agent coding. It gives an AI
 ```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
 ```
 
 ## Why cc-devflow
 
-- **Small public surface**: six visible workflow skills plus a CLI for installation and platform adaptation.
+- **Small public surface**: six core workflow skills, one optional deep review skill, plus a CLI for installation and platform adaptation.
 - **Evidence before done**: implementation must pass through verification proof before shipping or handoff.
 - **Skill-first distribution**: the public contract lives in `.claude/skills/<skill>/SKILL.md` and `PLAYBOOK.md`, not in hidden runtime behavior.
 - **Multi-platform output**: install once, then adapt for Codex, Cursor, Qwen, Antigravity, and related agent environments.
@@ -56,7 +56,7 @@ Refresh every supported platform output:
 npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 ```
 
-After installation, ask your agent to use the workflow skills directly. Start with `cc-roadmap` for product direction, use `cc-plan` for new work, use `cc-investigate` for bugs, then continue through `cc-do`, `cc-check`, and `cc-act`.
+After installation, ask your agent to use the workflow skills directly. Start with `cc-roadmap` for product direction, use `cc-plan` for new work, use `cc-investigate` for bugs, optionally run `cc-review` on complex frozen plans or investigations, then continue through `cc-do`, optional implementation `cc-review`, `cc-check`, and `cc-act`.
 
 ## Workflow Skills
 
@@ -66,6 +66,7 @@ After installation, ask your agent to use the workflow skills directly. Start wi
 | `cc-plan` | A feature or change needs scope, design, and task freezing | `planning/design.md`, `planning/tasks.md`, `task-manifest.json` |
 | `cc-investigate` | A bug needs symptom, reproduction, root cause, and repair boundary | `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json` |
 | `cc-do` | Planned or investigated work needs implementation | code, tests, checkpoints, scratch runtime |
+| `cc-review` | Complex plans, investigations, or diffs need optional deep multi-round review before implementation or verification | `cc-review-report.md`, optional `cc-review-findings.json` |
 | `cc-check` | Work needs fresh verification evidence | `report-card.json` |
 | `cc-act` | Verified work needs a PR, local handoff, release note, or closeout | one final handoff file |
 
@@ -82,6 +83,8 @@ Canonical language and durable decisions stay inside cc-devflow-native sources:
 
 `cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, public test seams, spec-style test names, public verification paths, behavior assertions, mock boundaries, coverage quality, mandatory regression tests, interface depth, Green minimality guards, refactor candidates, and vertical tracer-bullet slices when existing behavior changes. Before handoff, `cc-plan` and `cc-investigate` also reconcile the source roadmap item so RM status, REQ/FIX binding, progress, and spec diagnosis do not drift from the frozen change artifacts.
 
+`cc-review` is optional and deeper than `cc-check`. It can run immediately after `cc-plan` / `cc-investigate` to review the frozen plan or root-cause contract, or after `cc-do` to review the implementation. It classifies the input as plan-stage or implementation-stage, then runs the matching review branch: plan reviews borrow strategy/design/engineering/DX methods through progressive references, while implementation reviews inspect diff scope, code smells, tests, UI/runtime behavior, Browser/Computer Use evidence, and logs when applicable. Findings route back to `cc-plan` or `cc-do`; clean implementation reviews continue to `cc-check`.
+
 ## Verification And Ship Gates
 
 `cc-check` now treats QA as a feedback-loop problem, not only a green-test problem. Bugfix and behavior work records the loop used to prove reality, expected versus actual behavior, reproduction steps, test boundary quality, and architecture follow-ups when no clean public test seam exists.
@@ -120,6 +123,7 @@ npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-plan
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-investigate
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-do
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-review
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-check
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-act
 ```
@@ -185,6 +189,7 @@ The currently distributed skill folders are:
 - `.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/`
@@ -193,7 +198,7 @@ The currently distributed skill folders are:
 ## Durable vs Ephemeral
 
 - `devflow/specs/` stores durable capability truth: `INDEX.md` plus `capabilities/*.md`.
-- New change directories use `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` numbers advance independently, so the same number may exist in both prefixes.
+- New change directories use `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` numbers advance independently, so the same number may exist in both prefixes. Parallel worktrees may also create repeated numbers; the full change key must use a specific description to distinguish the work.
 - `devflow/changes/<change>/` stores durable change truth: `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file.
 - `devflow/workspaces/<change>/` stores ephemeral runtime scratch such as worker assignment, journals, prompts, and session logs.
 - Regenerable files should not be persisted under `devflow/changes/`.

package/README.zh-CN.md

@@ -14,13 +14,13 @@ CC-DevFlow 是一个给 Agent 编程时代准备的小而明确的工作流系
 ```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
 ```
 
 ## 为什么用 cc-devflow
 
-- **公开入口很小**：6 个可见 workflow skill，加一个负责安装和平台适配的 CLI。
+- **公开入口很小**：6 个核心 workflow skill、1 个可选深度 review skill，加一个负责安装和平台适配的 CLI。
 - **先证据后完成**：实现之后必须经过验证证据，才能进入 ship 或 handoff。
 - **Skill-first 分发**：公开契约写在 `.claude/skills/<skill>/SKILL.md` 和 `PLAYBOOK.md`，不依赖隐藏运行时语义。
 - **多平台产物**：一次安装，再生成 Codex、Cursor、Qwen、Antigravity 等 Agent 环境需要的输出。
@@ -56,7 +56,7 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --platform antigravity
 npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 ```
 
-安装完成后，直接让 Agent 使用这些 workflow skill。产品方向先走 `cc-roadmap`，新需求走 `cc-plan`，Bug 和 regression 走 `cc-investigate`，然后继续进入 `cc-do`、`cc-check`、`cc-act`。
+安装完成后，直接让 Agent 使用这些 workflow skill。产品方向先走 `cc-roadmap`，新需求走 `cc-plan`，Bug 和 regression 走 `cc-investigate`；复杂计划或根因合同冻结后可以先接 `cc-review`，再进入 `cc-do`；实现复杂时还可以再接一次实现 `cc-review`，最后进入 `cc-check` 和 `cc-act`。
 
 ## Workflow Skill
 
@@ -66,6 +66,7 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 | `cc-plan` | 新功能或变更需要澄清范围、设计方案、冻结任务 | `planning/design.md`、`planning/tasks.md`、`task-manifest.json` |
 | `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` |
 | `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、checkpoint、scratch runtime |
+| `cc-review` | 复杂方案、调查根因或 diff 需要在实现前或验证前做可选深度多轮 Review | `cc-review-report.md`，可选 `cc-review-findings.json` |
 | `cc-check` | 工作需要新鲜验证证据 | `report-card.json` |
 | `cc-act` | 已验证工作需要 PR、本地 handoff、release note 或 closeout | 唯一最终 handoff 文件 |
 
@@ -82,6 +83,8 @@ Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源
 
 `cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、public test seam、spec-style test name、public verification path、behavior assertion、mock boundary、覆盖质量、强制 regression test、interface depth、Green minimality guard、refactor candidates 和 vertical tracer-bullet slices。交接前，`cc-plan` 和 `cc-investigate` 还会校准 source roadmap item，让 RM 状态、REQ/FIX 绑定、progress 和 spec diagnosis 不再漂移。
 
+`cc-review` 是可选的深度 Review，不替代 `cc-check`。它可以接在 `cc-plan` / `cc-investigate` 后审冻结的计划或根因合同，也可以接在 `cc-do` 后审实现。它先判断输入属于计划阶段还是实现阶段，再走对应分支：计划 Review 通过渐进式 references 借鉴 strategy / design / engineering / DX 方法；实现 Review 检查 diff 范围、代码坏味道、测试、UI/runtime 行为、Browser/Computer Use 证据和日志。Finding 回到 `cc-plan` 或 `cc-do`；实现 Review 干净后再进入 `cc-check`。
+
 ## 验证与交付门禁
 
 `cc-check` 现在把 QA 当成反馈环问题，而不是只看测试是否绿。Bugfix 和行为变更需要记录证明现实的 loop、expected / actual、复现步骤、测试边界质量；如果没有干净的 public test seam，要留下架构 follow-up。
@@ -120,6 +123,7 @@ npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-plan
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-investigate
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-do
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-review
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-check
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-act
 ```
@@ -185,6 +189,7 @@ npx cc-devflow config doctor --cwd /path/to/your/project
 - `.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/`
@@ -193,7 +198,7 @@ npx cc-devflow config doctor --cwd /path/to/your/project
 ## Durable 与 Ephemeral
 
 - `devflow/specs/` 保存 durable capability truth：`INDEX.md` 和 `capabilities/*.md`。
-- 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号允许共存。
+- 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号允许共存。并行工作树也可能产生重复编号，必须用完整 change key 的描述区分业务内容。
 - `devflow/changes/<change>/` 保存 durable change truth：`change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、`team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一最终 handoff 文件。
 - `devflow/workspaces/<change>/` 保存 ephemeral runtime scratch，例如 worker assignment、journal、prompt 和 session log。
 - 能从 durable truth 再生成的文件，不应该持久化到 `devflow/changes/`。

package/bin/cc-devflow-cli.js

@@ -60,6 +60,10 @@ Commands:
   config doctor       Validate config and local ignore safety
   query list          List typed runtime query ids
   query <id>          Run a typed runtime query as JSON
+  next-change-key     Compute the next REQ/FIX change key
+  archive-change      Archive a completed change to devflow/changes/archive/YYYY-MM/
+  restore-change      Restore an archived change back to devflow/changes/
+  list-archived       List all archived changes
 
 Init options:
   --dir <path>         Target project path (default: cwd)
@@ -89,6 +93,12 @@ Query options:
   --cwd <path>         Project path used for devflow artifact lookup
   --change <id>        Change id, for example REQ-123
   --change-id <id>     Alias for --change
+  --change-key <key>   Full change key, for example REQ-123-my-feature
+
+Next-change-key options:
+  --prefix <REQ|FIX>   Change type prefix (required)
+  --description <text> Short description, will be slugified (required)
+  --cwd <path>         Project path (default: cwd)
 
 Examples:
   cc-devflow init
@@ -101,6 +111,7 @@ Examples:
   cc-devflow config resolve --cwd /path/to/project --format policy
   cc-devflow query list
   cc-devflow query ship-readiness --cwd /path/to/project --change REQ-123
+  cc-devflow query progress --change REQ-123 --change-key REQ-123-my-feature
 `);
 }
 
@@ -449,6 +460,7 @@ function parseQueryArgs(args) {
   const parsed = {
     cwd: null,
     changeId: null,
+    changeKey: null,
     rest: []
   };
 
@@ -480,6 +492,16 @@ function parseQueryArgs(args) {
       continue;
     }
 
+    if (arg === '--change-key') {
+      parsed.changeKey = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--change-key=')) {
+      parsed.changeKey = arg.slice('--change-key='.length);
+      continue;
+    }
+
     parsed.rest.push(arg);
   }
 
@@ -490,7 +512,7 @@ async function runQueryCommand(args) {
   const [subcommand, ...rest] = args;
 
   if (!subcommand || subcommand === '--help' || subcommand === '-h') {
-    console.error('Use: cc-devflow query list OR cc-devflow query <id> --change <changeId> [--cwd <path>]');
+    console.error('Use: cc-devflow query list OR cc-devflow query <id> --change <changeId> [--change-key <key>] [--cwd <path>]');
     return 3;
   }
 
@@ -507,13 +529,39 @@ async function runQueryCommand(args) {
 
   const result = await runQuery(subcommand, {
     repoRoot: path.resolve(options.cwd || process.cwd()),
-    changeId: options.changeId
+    changeId: options.changeId,
+    changeKey: options.changeKey
   });
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   return result.ok ? 0 : 2;
 }
 
+function runNextChangeKey(args) {
+  const parsed = { prefix: null, description: null, cwd: null };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--prefix') { parsed.prefix = args[++i]; continue; }
+    if (arg.startsWith('--prefix=')) { parsed.prefix = arg.slice('--prefix='.length); continue; }
+    if (arg === '--description') { parsed.description = args[++i]; continue; }
+    if (arg.startsWith('--description=')) { parsed.description = arg.slice('--description='.length); continue; }
+    if (arg === '--cwd') { parsed.cwd = args[++i]; continue; }
+    if (arg.startsWith('--cwd=')) { parsed.cwd = arg.slice('--cwd='.length); continue; }
+  }
+
+  if (!parsed.prefix || !parsed.description) {
+    console.error('Use: cc-devflow next-change-key --prefix REQ|FIX --description "short description"');
+    return 1;
+  }
+
+  const { nextChangeKey } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/paths.js'));
+  const repoRoot = path.resolve(parsed.cwd || process.cwd());
+  const result = nextChangeKey(repoRoot, parsed.prefix, parsed.description);
+  process.stdout.write(`${result.changeId}\n${result.changeKey}\n`);
+  return 0;
+}
+
 function runAdapt(args) {
   const { options, rest } = parseCliArgs(args);
 
@@ -557,6 +605,75 @@ function runAdapter(command, args) {
   return typeof result.status === 'number' ? result.status : 1;
 }
 
+function runArchiveChange(args) {
+  const parsed = { changeKey: null, cwd: null };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--cwd') { parsed.cwd = args[++i]; continue; }
+    if (arg.startsWith('--cwd=')) { parsed.cwd = arg.slice('--cwd='.length); continue; }
+    if (!arg.startsWith('-') && !parsed.changeKey) { parsed.changeKey = arg; continue; }
+  }
+
+  if (!parsed.changeKey) {
+    console.error('Use: cc-devflow archive-change <change-key> [--cwd path]');
+    return 1;
+  }
+
+  const { archiveChange } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/archive-change.js'));
+  const repoRoot = path.resolve(parsed.cwd || process.cwd());
+  const result = archiveChange(repoRoot, parsed.changeKey);
+  process.stdout.write(`Archived to ${result.archived}\n`);
+  return 0;
+}
+
+function runRestoreChange(args) {
+  const parsed = { archivedPath: null, cwd: null };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--cwd') { parsed.cwd = args[++i]; continue; }
+    if (arg.startsWith('--cwd=')) { parsed.cwd = arg.slice('--cwd='.length); continue; }
+    if (!arg.startsWith('-') && !parsed.archivedPath) { parsed.archivedPath = arg; continue; }
+  }
+
+  if (!parsed.archivedPath) {
+    console.error('Use: cc-devflow restore-change <archived-path> [--cwd path]');
+    return 1;
+  }
+
+  const { restoreChange } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/archive-change.js'));
+  const repoRoot = path.resolve(parsed.cwd || process.cwd());
+  const archivePath = path.resolve(parsed.archivedPath);
+  const result = restoreChange(repoRoot, archivePath);
+  process.stdout.write(`Restored to ${result.restored}\n`);
+  return 0;
+}
+
+function runListArchived(args) {
+  const parsed = { cwd: null };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--cwd') { parsed.cwd = args[++i]; continue; }
+    if (arg.startsWith('--cwd=')) { parsed.cwd = arg.slice('--cwd='.length); continue; }
+  }
+
+  const { listArchived } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/archive-change.js'));
+  const repoRoot = path.resolve(parsed.cwd || process.cwd());
+  const items = listArchived(repoRoot);
+
+  if (items.length === 0) {
+    process.stdout.write('No archived changes.\n');
+    return 0;
+  }
+
+  for (const item of items) {
+    process.stdout.write(`${item.month}  ${item.changeKey}\n`);
+  }
+  return 0;
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const [command, ...rest] = argv;
@@ -582,6 +699,22 @@ async function main() {
     return runQueryCommand(rest);
   }
 
+  if (command === 'next-change-key') {
+    return runNextChangeKey(rest);
+  }
+
+  if (command === 'archive-change') {
+    return runArchiveChange(rest);
+  }
+
+  if (command === 'restore-change') {
+    return runRestoreChange(rest);
+  }
+
+  if (command === 'list-archived') {
+    return runListArchived(rest);
+  }
+
   return runAdapter(command, rest);
 }
 

package/config/distributable-skills.json

@@ -4,6 +4,7 @@
     "cc-plan",
     "cc-investigate",
     "cc-do",
+    "cc-review",
     "cc-check",
     "cc-act"
   ],
@@ -12,6 +13,7 @@
     "cc-plan",
     "cc-investigate",
     "cc-do",
+    "cc-review",
     "cc-check",
     "cc-act",
     "cc-spec-init",

package/docs/CLAUDE.md

@@ -27,4 +27,4 @@ docs/
 - 面向使用者：优先写“怎么用/怎么做”，其次再写“为什么”。
 - 可检索：标题清晰、关键词统一（`/flow-*`、`/core-*`、`/speckit.*`）。
 - 可落地：结论必须能映射到具体命令、脚本或模板文件路径。
-- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；`REQ` 和 `FIX` 是独立编号空间；描述部分使用 kebab-case。
+- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 依靠描述区分业务内容；描述部分使用 kebab-case。

package/docs/examples/example-bindings.json

@@ -1,10 +1,11 @@
 {
-  "updatedAt": "2026-05-06",
+  "updatedAt": "2026-05-09",
   "skills": {
-    "cc-roadmap": "5.0.0",
-    "cc-plan": "3.7.5",
-    "cc-investigate": "1.2.2",
+    "cc-roadmap": "5.2.0",
+    "cc-plan": "3.8.1",
+    "cc-investigate": "1.3.0",
     "cc-do": "1.6.2",
+    "cc-review": "1.0.0",
     "cc-check": "1.10.1",
     "cc-act": "1.8.2",
     "cc-spec-init": "1.1.0"

package/docs/examples/full-design-blocked/BACKLOG.md

@@ -5,7 +5,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `5.0.0`
+- Skill version: `5.2.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
 - Roadmap state source: `roadmap.json`

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.5`, `cc-do@1.6.2`, `cc-check@1.10.1`
+- Bound skills: `cc-roadmap@5.2.0`, `cc-plan@3.8.1`, `cc-do@1.6.2`, `cc-check@1.10.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 

package/docs/examples/full-design-blocked/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `5.0.0`
+- Skill version: `5.2.0`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`
@@ -27,6 +27,21 @@
 - Adoption / trust bottleneck: admins will not trust bulk invite if seat usage and audit logs drift
 - Known unknowns: how duplicate users, seat limits, and partial imports should behave
 
+## AI Leverage Route Lens
+
+- Real user / operator: workspace admin onboarding 20-200 collaborators
+- Status quo workaround: paste individual invite emails or coordinate in external spreadsheets
+- Human-team effort for full scope: multiple weeks across product, engineering, billing, and support review
+- CC / agent effort for full scope: several hours once row semantics are approved, but unbounded before that
+- AI compression ratio: high after semantics freeze, low while the product contract is ambiguous
+- Complete-lake boundary: row classification, admin upload flow, billing-seat checks, and audit mapping after rule approval
+- Ocean boundary: SCIM, background retries, rollback wizard, and unspecified billing semantics
+- Scope recommendation: `sharp-wedge`
+- First success signal: admins can predict duplicate, invalid, and over-limit outcomes
+- Kill signal: duplicate and seat-limit semantics remain unresolved
+- Verdict: `sharp-wedge`
+- Missing evidence before ready-for-cc-plan: none recorded at route handoff; cc-check later reopened duplicate, invalid-row, partial-success, and seat-limit semantics
+
 ## Route Options
 
 | Shape | Why this could work | Why this may fail | Decision |

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.8.1`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging
@@ -120,6 +120,44 @@
 - Deferred questions:
   - whether partial success needs an explicit rollback option
 
+## AI Leverage Decision Lens
+
+- Real user / operator: workspace admin onboarding larger teams
+- Status quo workaround: paste invite emails one by one or track them in spreadsheets
+- Human-team effort for full scope: multiple weeks across product, engineering, billing, and support review
+- CC / agent effort for full scope: several hours once row semantics are approved, but unbounded before that
+- AI compression ratio: high after semantics freeze, low while the product contract is ambiguous
+- Complete-lake boundary: row classification, admin upload flow, billing-seat checks, and audit mapping after rule approval
+- Ocean boundary: SCIM, background retries, rollback wizard, and unspecified billing semantics
+- Scope recommendation: `sharp-wedge`
+- Cost model: medium agent time after rule approval, high human review time until semantics are approved, high failure cost if billing or audit outcomes drift
+- Verdict: `sharp-wedge`
+- Missing evidence or pivot reason: none at plan approval; cc-check later reopened duplicate, invalid-row, partial-success, and seat-limit semantics before retry or cc-act
+
+## External Best-Practice Validation
+
+- Needed: Yes
+- Decision status: declined
+- Decision question: `D2`
+- Privacy guard: generalized terms only; no project names, private requirements, customer names, secrets, logs, or proprietary concepts
+- Generalized search terms:
+  - `bulk invite CSV import validation best practices`
+- Sources checked:
+- Conventional wisdom:
+- Current discourse:
+- Repo-fit verdict: skipped
+- Changes to options / tasks:
+  - keep the design blocked until row-outcome semantics are approved from internal evidence
+- Skipped reason: user kept the example repo-local for the blocked design
+
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Best-effort upload would let duplicate, invalid, and seat-limit semantics drift during execution | Choose Option B and freeze a rule matrix first | Option B | Keep execution blocked until row outcomes are modeled | answered |
+| D2 | external-best-practice | Bulk CSV import semantics could benefit from generalized external practice, but this example stays repo-local | Stay repo-local for this blocked example | Stay repo-local | `cc-do` still must not start implementation until row outcomes are answered from internal evidence | answered |
+| D3 | review-blocker | Duplicate and seat-limit outcomes are still not explicit enough for final requirement proof | Answer the row-outcome matrix before retry or cc-act | pending | `cc-do` retry and `cc-act` must stay blocked until this is answered | asked |
+
 ## Design
 
 - Modules touched:
@@ -169,6 +207,9 @@
 - Feasibility scan: pass
 - Source alignment: pass; roadmap still prioritizes trust over speed
 - PRD brief scan: pass for actors and stories; blocked on duplicate and seat-limit semantics
+- AI Leverage Decision Lens scan: pass at plan approval as a sharp wedge; cc-check later blocked final proof because product semantics were still unbounded evidence risk
+- External best-practice scan: pass; declined and recorded before task generation
+- Decision question scan: blocked; `D3` is still unanswered
 - UI / interaction review summary: result states are acceptable if semantics are frozen first
 - DX review summary: execution still needs a single row-outcome matrix
 - Auto-decided items: