cc-devflow 4.5.8 → 4.5.10

package/.claude/skills/cc-plan/assets/{DESIGN_TEMPLATE.md → legacy/DESIGN_TEMPLATE.md}

@@ -5,6 +5,7 @@
 - Requirement version:
 - Design version:
 - CC-Plan skill version:
+- Work branch:
 - Output language:
 - Requirement ID:
 - Design mode: `full-design`
@@ -19,6 +20,13 @@
 - Date:
 - Owner:
 
+## Progressive Disclosure Index
+
+- Default read: Requirement Snapshot, Approved Direction, Validation Strategy, Roadmap Sync Gate.
+- Open for scope/design questions: Source Handoff, Options Considered, Design, Implementation Surface Map.
+- Open for trust/conflict questions: Source Trust Boundary, External Document Conflicts, Domain Language & Durable Decisions.
+- Open for audit/recovery: Project Postmortem Recall, Review Gate, Bounded Review Loop, Decision Questions, Risks.
+
 ## Source Handoff
 
 - Source stage:
@@ -55,6 +63,20 @@
 - Gate verdict: `pass` | `blocked`
 - Blocked question if any:
 
+## Deep Planning Funnel
+
+| Round | Decision focus | Confirmed answer | Evidence / user answer | Status | Artifact impact |
+|-------|----------------|------------------|------------------------|--------|-----------------|
+| Requirement Reality | user / operator, pain, status quo, success, non-goals |  |  | confirmed / auto-decided / blocked / not-applicable | Requirement Snapshot / PRD brief |
+| System Shape | current codepath, module ownership, state/data flow, invariants |  |  | confirmed / auto-decided / blocked / not-applicable | Design / File Plan |
+| Interface & Data Contract | callers, inputs, outputs, key fields, errors, permissions, categories |  |  | confirmed / auto-decided / blocked / not-applicable | Interface Contract / Validation Strategy |
+| Abstraction & Encapsulation | hidden complexity, rejected abstractions, public vs private methods, branch elimination |  |  | confirmed / auto-decided / blocked / not-applicable | Interface / Deep Module Check |
+| Execution Architecture | foundation/core/integration/polish decisions, failure recovery, distribution |  |  | confirmed / auto-decided / blocked / not-applicable | Implementation Decision Horizon |
+| Task Contract | tracer bullets, Red/Green/Refactor, AFK/HITL, 2-5 min grain, completion script |  |  | confirmed / auto-decided / blocked / not-applicable | planning/tasks.md / task-manifest.json |
+| Final Approval | approved direction and task contract summary |  |  | confirmed / blocked | Approval |
+
+> 如果某轮是 `blocked`，停止生成任务。先问一个 blocked question、拆分需求，或记录用户明确接受的 HITL 边界。
+
 ## External Document Conflicts
 
 | Source | Bucket | Conflict | Resolution / blocker |
@@ -101,6 +123,28 @@
 - Changes to options / tasks:
 - Skipped reason:
 
+## Project Postmortem Recall
+
+- Search status: `no-project-postmortems-yet` | `searched-no-match` | `matches-found`
+- Search command:
+- Search terms:
+- Sources opened:
+  - `devflow/postmortems/INDEX.md`
+  - `devflow/postmortems/principles.md`
+  - `devflow/postmortems/incidents/<date>-<change-key>.md`
+- Matching incidents:
+- Matching principles:
+- Relevant Git evidence:
+- Planning impact:
+  - Scope impact:
+  - Test seam impact:
+  - Verification impact:
+  - Files / surfaces to avoid:
+  - Review gate impact:
+- No-op reason:
+
+> 尸检报告先做检索提醒，再做深读。只有标签、模块、失败类或模型风险匹配时，才打开具体 incident。
+
 ## Capability Handoff
 
 - Canonical capability spec:
@@ -231,6 +275,22 @@
 
 > 新增或改动公共接口时，优先小接口深模块。若有两个合理形态，写清为什么没有选择另一个。
 
+## Interface & Data Contract
+
+| Surface | Caller / owner | Method or operation | Input fields | Output fields | Error shape | Category / type source | Compatibility / migration |
+|---------|----------------|---------------------|--------------|---------------|-------------|------------------------|---------------------------|
+|  |  |  |  |  |  | repo term / new term / user term |  |
+
+> 关键字段、方法、分类和错误形态必须在这里冻结。没有进入这张表的接口细节，不能在 `cc-do` 阶段临场发明。
+
+## Abstraction & Encapsulation Contract
+
+| Decision | Keep public | Keep private | Complexity hidden in | Rejected abstraction | Branches eliminated |
+|----------|-------------|--------------|----------------------|----------------------|---------------------|
+|  |  |  |  |  |  |
+
+> 好计划不是把 if/else 分发给执行者，而是提前决定哪些特殊情况应被设计消除。
+
 ## Interface Testability Check
 
 | Surface | Dependency shape | Result shape | Boundary adapter shape | Test setup complexity | Decision |
@@ -301,6 +361,14 @@
 - Manual:
 - Observability / evidence:
 
+## Task Contract Preview
+
+| Task | User / edge story | File responsibility | Method / interface | Key fields | Input / output | Failure path | Verification | AFK / HITL |
+|------|-------------------|---------------------|--------------------|------------|----------------|--------------|--------------|------------|
+| T001 |  |  |  |  |  |  |  | AFK / HITL |
+
+> 这里是 `planning/tasks.md` 和 `task-manifest.json.tasks[].contract` 的来源。前面问过但这里没落盘，就等于没问。
+
 ## Test Coverage Map
 
 | Code path / user flow | Public seam | Public verification path | Behavior asserted | One logical behavior? | Existing coverage | Quality | Required test | Level | Mock boundary | Implementation-detail risk | Regression? |

package/.claude/skills/cc-plan/assets/{TINY_DESIGN_TEMPLATE.md → legacy/TINY_DESIGN_TEMPLATE.md}

@@ -16,6 +16,13 @@
 - Primary capability:
 - Secondary capabilities:
 
+## Progressive Disclosure Index
+
+- Default read: Frozen Design Card, Validation, Main Risk, Approval.
+- Open for scope questions: Source Handoff, Capability Handoff, Implementation Surface Map.
+- Open for trust/conflict questions: Source Trust Boundary, External Document Conflicts, Domain Language & Decisions.
+- Open for audit/recovery: Project Postmortem Recall, Review Gate, Bounded Review Loop, Decision Questions.
+
 ## Source Handoff
 
 - Why now:
@@ -42,6 +49,20 @@
 - Gate verdict: `pass` | `blocked`
 - Blocked question if any:
 
+## Deep Planning Funnel
+
+| Round | Confirmed answer | Evidence / user answer | Status | Artifact impact |
+|-------|------------------|------------------------|--------|-----------------|
+| Requirement Reality |  |  | confirmed / auto-decided / blocked / not-applicable | Frozen Design Card |
+| System Shape |  |  | confirmed / auto-decided / blocked / not-applicable | Implementation Surface Map |
+| Interface & Data Contract |  |  | confirmed / auto-decided / blocked / not-applicable | Interface Shape / Validation |
+| Abstraction & Encapsulation |  |  | confirmed / auto-decided / blocked / not-applicable | Interface Shape |
+| Execution Architecture |  |  | confirmed / auto-decided / blocked / not-applicable | Validation / Roadmap Sync Gate |
+| Task Contract |  |  | confirmed / auto-decided / blocked / not-applicable | planning/tasks.md / task-manifest.json |
+| Final Approval |  |  | confirmed / blocked | Approval |
+
+> tiny-design 也必须把关键确认落盘。若出现新接口、字段、状态机或跨模块决策，优先升级 `full-design`。
+
 ## External Document Conflicts
 
 - Auto-resolved:
@@ -76,6 +97,19 @@
 - Changes to frozen design:
 - Skipped reason:
 
+## Project Postmortem Recall
+
+- Search status: `no-project-postmortems-yet` | `searched-no-match` | `matches-found`
+- Search command:
+- Search terms:
+- Sources opened:
+- Matching incidents:
+- Matching principles:
+- Planning impact:
+- No-op reason:
+
+> tiny-design 也必须查尸检报告。越小的改动越容易让模型凭直觉重复旧错误。
+
 ## Capability Handoff
 
 - Canonical capability spec:
@@ -121,9 +155,15 @@
 
 - Callers:
 - Public operations:
+- Methods / operations:
+- Key fields:
+- Input / output:
+- Error shape:
+- Category / type source:
 - Complexity hidden:
 - Misuse risk:
 - Why this stays simple:
+- Rejected abstraction:
 
 ## Interface Testability
 
@@ -154,13 +194,19 @@
 - Tracer bullet order:
 - Green implementation check:
 - Green minimality guard:
-- Refactor checkpoint:
+- Refactor gate:
 - Refactor candidates:
 - TDD exceptions:
 - Regression test required:
 - Primary check:
 - Secondary checks:
 
+## Task Contract Preview
+
+| Task | User / edge story | File responsibility | Method / interface | Key fields | Failure path | Verification | AFK / HITL |
+|------|-------------------|---------------------|--------------------|------------|--------------|--------------|------------|
+| T001 |  |  |  |  |  |  | AFK / HITL |
+
 ## Roadmap Sync Gate
 
 - Source RM:

package/.claude/skills/cc-plan/references/planning-contract.md

@@ -2,37 +2,40 @@
 
 ## Hard Rules
 
-1. `cc-plan` 默认只产出 4 个文件：`planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json`。
-2. clarification / brainstorm / review 结论必须并入 `planning/design.md`，不能再默认拆独立文档。
+1. `cc-plan` 默认只产出 3 个文件：`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json`。
+2. clarification / brainstorm / review 结论必须并入 `planning/tasks.md#Contract Summary`，不能再默认拆 `planning/design.md` 或独立文档。
 3. 执行 handoff 必须写进 `planning/tasks.md` 顶部，不能依赖单独的 `context-package.md`。
 4. `planning/task-manifest.json` 必须和 `planning/tasks.md` 同步，且能告诉 `cc-do` 当前任务是谁。
-5. `planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json` 必须记录来源版本链。
-6. 计划里出现 placeholder 词，就说明还没想清楚。
-7. 一次只推进一个澄清问题，不允许问题轰炸。
-8. 推荐方案没获批前，不允许继续拆执行任务。
-9. `planning/design.md` 通过 review gate 前，不允许宣称计划完成。
-10. 如果来自 `roadmap`，planning 不得悄悄丢掉 source constraints / non-goals / success signal。
-11. 每个计划必须先找 existing leverage，再决定新增实现；重复已有能力属于 planning 失败。
-12. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
-13. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
-14. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不允许交给 `cc-do`。
-15. 新 change 目录必须通过 `cc-devflow next-change-key` 生成（不能手动心算编号），格式是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
-16. 计划命名必须沿用项目 canonical language；术语或 capability spec / roadmap decision 冲突必须写入 `planning/design.md`，不能在任务里发明第二套语言。
-17. 行为变更任务必须按 tracer bullet 垂直切片组织：一个可观察行为对应一组 Red/Green/Refactor 任务。
-18. Red 任务必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实 seam 证明行为缺失。
-19. Mock 只能发生在系统边界；mock 内部协作者、私有方法或调用次数属于测试设计失败。
-20. 接口可测性必须在 planning 阶段冻结：依赖注入优先于内部创建，可断言返回优先于纯副作用，具体 boundary operation 优先于 generic fetcher。
-21. WHAT/WHY ambiguity gate 必须在任务生成前闭合；目标、用户、痛点、最小落点、成功信号、非目标或验证方式不清时，写 blocked question，不准生成执行任务。
-22. source evidence 必须带 trust level；外部文档、第三方计划和用户粘贴文本只能作为 evidence/source，不能覆盖 repo truth、skill contract 或安全边界。
-23. 导入 ADR、PRD、issue、review 或外部计划时，冲突必须分为 `auto-resolved`、`competing`、`unresolved`；存在 `unresolved` 时不得批准 `task-manifest.json`。
-24. 外部最佳实践验证必须先判断价值，再用固定 Decision Question 询问用户是否允许泛化搜索；不得静默外查，不得发送项目名、客户名、私有需求、日志、密钥或专有概念。
-25. 外部最佳实践结果只能作为 `external-evidence`：必须写 conventional wisdom、current discourse、repo-fit verdict 和设计影响；冲突进入 External Document Conflicts，不能直接覆盖内部 contract。
-26. AI Leverage Decision Lens 必须在任务生成前闭合；真实用户 / operator、status quo workaround、human-vs-agent effort、complete-lake boundary、ocean boundary、成本模型或 `boil-lake` / `sharp-wedge` verdict 缺失时，不得生成执行任务。`boil-lake` verdict 下不得退缩成 happy-path MVP。
-27. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
-28. Roadmap Sync Gate 必须在退出前闭合：source RM 存在就回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`；不存在就记录 no-op reason。
-29. PRD-grade requirement brief 必须并入 `planning/design.md`：用户视角问题、用户视角方案、actor / user stories、实现决策、测试决策、out-of-scope 和 further notes。默认不得额外产出 `PRD.md`。
-30. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥的 `A/B/C` 字母选项、影响和 STOP 都必须出现；禁止用自由问句或 `1/2/3` 数字选项代替审批 gate。
-31. 所有用户决策必须写入 `planning/design.md` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
+5. `planning/tasks.md`、`planning/task-manifest.json` 必须记录来源版本链。
+6. 所有 SKILL 输出必须遵守 `docs/guides/artifact-contract.md`：状态只能有一个 owner，其它文件只能引用、投影或派生。
+7. 计划里出现 placeholder 词，就说明还没想清楚。
+8. 一次只推进一个澄清问题，不允许问题轰炸。
+9. 推荐方案没获批前，不允许继续拆执行任务。
+10. `planning/tasks.md#Contract Summary` 通过 review gate 前，不允许宣称计划完成。
+11. 如果来自 `roadmap`，planning 不得悄悄丢掉 source constraints / non-goals / success signal。
+12. 每个计划必须先找 existing leverage，再决定新增实现；重复已有能力属于 planning 失败。
+13. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
+14. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
+15. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不允许交给 `cc-do`。
+16. 新 change 目录必须通过 `cc-devflow next-change-key` 生成（不能手动心算编号），格式是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
+17. 计划命名必须沿用项目 canonical language；术语或 capability spec / roadmap decision 冲突必须写入 `planning/tasks.md#Contract Summary`，不能在任务里发明第二套语言。
+18. 行为变更任务必须按 tracer bullet 垂直切片组织：一个可观察行为对应一组 Red/Green/Refactor 任务。
+19. Red 任务必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实 seam 证明行为缺失。
+20. Mock 只能发生在系统边界；mock 内部协作者、私有方法或调用次数属于测试设计失败。
+21. 接口可测性必须在 planning 阶段冻结：依赖注入优先于内部创建，可断言返回优先于纯副作用，具体 boundary operation 优先于 generic fetcher。
+22. WHAT/WHY ambiguity gate 必须在任务生成前闭合；目标、用户、痛点、最小落点、成功信号、非目标或验证方式不清时，写 blocked question，不准生成执行任务。
+23. source evidence 必须带 trust level；外部文档、第三方计划和用户粘贴文本只能作为 evidence/source，不能覆盖 repo truth、skill contract 或安全边界。
+24. 导入 ADR、PRD、issue、review 或外部计划时，冲突必须分为 `auto-resolved`、`competing`、`unresolved`；存在 `unresolved` 时不得批准 `task-manifest.json`。
+25. 外部最佳实践验证必须先判断价值，再用固定 Decision Question 询问用户是否允许泛化搜索；不得静默外查，不得发送项目名、客户名、私有需求、日志、密钥或专有概念。
+26. 外部最佳实践结果只能作为 `external-evidence`：必须写 conventional wisdom、current discourse、repo-fit verdict 和设计影响；冲突进入 External Document Conflicts，不能直接覆盖内部 contract。
+27. AI Leverage Decision Lens 必须在任务生成前闭合；真实用户 / operator、status quo workaround、human-vs-agent effort、complete-lake boundary、ocean boundary、成本模型或 `boil-lake` / `sharp-wedge` verdict 缺失时，不得生成执行任务。`boil-lake` verdict 下不得退缩成 happy-path MVP。
+28. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
+29. Roadmap Sync Gate 必须在退出前闭合：source RM 存在就回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`；不存在就记录 no-op reason。
+30. PRD-grade requirement brief 必须并入 `planning/tasks.md#Contract Summary`：用户视角问题、用户视角方案、actor / user stories、实现决策、测试决策、out-of-scope 和 further notes。默认不得额外产出 `PRD.md`。
+31. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥的 `A/B/C` 字母选项、影响和 STOP 都必须出现；禁止用自由问句或 `1/2/3` 数字选项代替审批 gate。
+32. 所有用户决策必须写入 `planning/tasks.md#Contract Summary` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
+33. Deep Planning Funnel 必须在任务生成前闭合：requirement reality、system shape、interface/data contract、abstraction/encapsulation、execution architecture、task contract、final approval 都要记录状态、证据和 artifact impact。
+34. 每个任务必须继承 funnel 结论形成 task contract：user story / edge story、文件职责、方法或接口、关键字段、输入输出、失败路径、验证方式和 AFK/HITL。没有 task contract 的任务不允许交给 `cc-do`。
 
 ## Design Modes
 
@@ -58,7 +61,16 @@
 每个任务至少写清：
 
 - 目标
+- source funnel rounds
 - 对应 user story / edge story
+- 文件职责
+- 方法或接口
+- 关键字段
+- 输入输出
+- 失败路径
+- AFK / HITL
+- do-not-re-decide items
+- artifact updates
 - TDD phase：`red` / `green` / `refactor` / `exception`
 - Vertical slice / tracer bullet
 - Spec-style test name
@@ -76,18 +88,21 @@
 - Completion command：调用 `mark-task-complete.sh`，同步 `planning/task-manifest.json` 与 `planning/tasks.md`
 - Forbidden shortcuts：禁止手工改 checkbox、manifest status 或 `currentTaskId`
 
-行为变更任务必须先有 `[TEST]` 红灯任务，再有 `[IMPL]` 绿灯任务，最后有 `[REFACTOR]` 或明确 refactor checkpoint。纯文档、纯配置、纯生成文件、throwaway prototype 可以例外，但必须写明原因、风险和替代验证。
+行为变更任务必须先有 `[TEST]` 红灯任务，再有 `[IMPL]` 绿灯任务，最后有 `[REFACTOR]` 或明确 refactor gate。纯文档、纯配置、纯生成文件、throwaway prototype 可以例外，但必须写明原因、风险和替代验证。
 不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
 也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
 
 ## Execution Protocol Fields
 
-`planning/tasks.md` 必须有 `Execution Protocol` 区块，`planning/task-manifest.json` 必须有 `executionProtocol` 对象。它们共同约束 ClaudeCode / Codex：
+`planning/tasks.md` 必须有 `Execution Protocol` 区块。`planning/task-manifest.json` 不再复制这段协议；它只保留执行图和调度状态，避免把同一条 shell 命令复制进全局 metadata 和每个 task。
 
 - task 选择来自 `currentTaskId` 或 `select-ready-tasks.sh`
 - 每个 task 必须按模板字段完整展开，不能退化成标题清单
 - 完成 task 必须调用 `mark-task-complete.sh`
-- 脚本失败时修 evidence / checkpoint / review gate 后重跑，禁止手工绕过
+- 脚本失败时修 evidence / review gate / dependency state 后重跑，禁止手工绕过
+- 禁止规划或要求生成执行过程文件：`execution/tasks/<task-id>/context.md`、`checkpoint.json`、review markdown 或其它 AI 手写过程文件都不是默认真相源；恢复只看代码、Git、`planning/tasks.md`、`task-manifest.json` 和 CLI 自动日志。
+- completion command、required-before-completion 和 forbidden-shortcuts 写在 `planning/tasks.md` 的 task block；不得再写入 `task-manifest.json.executionProtocol` 或 `tasks[].completion`
+- `task-manifest.json` 不写顶层 `status`、`activePhase`、`sourceRoadmap` 或 `spec`；整体完成度从 `tasks[].status` 派生，phase 从任务图派生，roadmap/spec 状态从 `change-meta.json` 和 `devflow/roadmap.json` 读取。
 
 ## Decision Question Fields
 
@@ -106,7 +121,7 @@
 
 ## Review Gate
 
-`planning/design.md` 至少完成：
+`planning/tasks.md#Contract Summary` 至少完成：
 
 1. Placeholder scan
 2. Consistency scan

package/.claude/skills/cc-review/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CC-Review Changelog
 
+## 2.0.0 - 2026-05-13
+
+- break default review output away from Markdown plan/report files and make `review-ledger.jsonl` the required durable record
+- add CLI-first lifecycle guidance for `review start`, `record-node`, `add-finding`, `close`, and on-demand `render`
+- rename optional machine outputs to `review-findings.json` and `review-agent-results.jsonl`, with legacy `cc-review-*` files retained only as fallback inputs
+
 ## 1.3.0
 
 - Added a risk-lane review swarm profile for broad implementation and PR-landing reviews.

package/.claude/skills/cc-review/PLAYBOOK.md

@@ -14,8 +14,8 @@
 ## Core Rules
 
 1. 先判断 review 对象是计划、实现，还是混合。
-2. 先读上一次 `cc-review` 的 plan / report / ledger / findings，再看当前 git 或 artifact delta。
-3. 先写 `cc-review-plan.md`，列出要用哪些 Review 工具和哪些节点需要遍历。
+2. 先读上一次 `cc-review` 的 `review-ledger.jsonl` / `review-findings.json` / `review-agent-results.jsonl`，再看当前 git 或 artifact delta；旧 `cc-review-*` 文件只作 fallback。
+3. 先用 `cc-devflow review start` 写入 `review-started` 事件，列出 Review 工具、节点、跳过理由和风险 lane。
 4. 对适合独立审查的节点，优先派发只读 reviewer subAgent；没有工具时如实降级。
 5. 复杂实现 diff 优先使用 intent/regression、security/privacy、performance/reliability、contracts/coverage 四类风险 lane；小 diff 可以合并但必须说明。
 6. 按节点逐个 Review：review 一个、check 一个、ledger 记录一个。
@@ -30,15 +30,13 @@
 15. 不允许固定只列 3 个问题；finding 数量由节点遍历和证据决定。
 16. 输出前必须聚合 raw findings：合并重复，降级弱证据，拒收 speculative / out-of-scope / stale findings。
 17. 发现计划合同错误，回 `cc-plan`；发现代码错误，回 `cc-do`；只差验收，进 `cc-check`。
-18. 输出必须落到 `review/cc-review-plan.md`、`review/cc-review-ledger.jsonl` 和 `review/cc-review-report.md`，不能只留在聊天里。
+18. 输出必须落到 `review/review-ledger.jsonl`，必要时补 `review/review-findings.json` / `review/review-agent-results.jsonl`；Markdown 报告只通过 `cc-devflow review render` 按需生成。
 
 ## Required Outputs
 
-- `review/cc-review-plan.md`
-- `review/cc-review-ledger.jsonl`
-- `review/cc-review-report.md`
-- `review/cc-review-agent-results.jsonl` when subagent reviewers are used
-- `review/cc-review-findings.json` when later agents need structured findings
+- `review/review-ledger.jsonl`
+- `review/review-agent-results.jsonl` when subagent reviewers are used
+- `review/review-findings.json` when later agents need structured findings
 
 ## Local Kit
 
@@ -50,7 +48,7 @@
 
 ## Stateful Review Plan
 
-`cc-review-plan.md` 必须至少包含：
+`review-started` ledger event 必须至少包含：
 
 - review mode：plan / implementation / mixed
 - previous review state：上次 report、ledger、findings 是否存在
@@ -61,7 +59,7 @@
 - risk lanes：implementation / mixed review 是否覆盖 intent-regression、security-privacy、performance-reliability、contracts-coverage
 - node list：`R001`、`R002` ...，每个节点有 target、method、owner、evidence source、status
 
-Review 过程中每完成一个节点，就追加一条 ledger；不要等最后一次性补记。
+Review 过程中每完成一个节点，就用 `cc-devflow review record-node` 追加一条 ledger；不要等最后一次性补记。
 
 ## SubAgent Review
 
@@ -70,7 +68,7 @@ Review 过程中每完成一个节点，就追加一条 ledger；不要等最后
 调度规则：
 
 - 大范围 / 多文件 / 多 facet review：至少尝试两个独立 reviewer。
-- 小范围 review：至少尝试一个 combined reviewer，除非 `cc-review-plan.md` 写明不需要。
+- 小范围 review：至少尝试一个 combined reviewer，除非 `review-ledger.jsonl` 写明不需要。
 - Plan 节点可分配 strategy、engineering、design、DX、TOC reviewer。
 - Implementation 节点可分配 contract、smell、test、runtime reviewer。
 - 复杂 implementation 节点优先按四类风险 lane 派发 reviewer：intent/regression、security/privacy、performance/reliability、contracts/coverage。

package/.claude/skills/cc-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-review
-version: 1.3.0
+version: 2.0.0
 description: Use when a complex requirement, bug fix, plan, or implementation diff needs optional deep multi-round review beyond cc-check. Builds a review plan from prior records and current git/artifact delta, dispatches independent read-only reviewer agents when available, applies a risk-lane review swarm profile for broad implementation diffs, records node results, identifies in-scope code smells, queues user decisions, and reroutes to cc-plan, cc-do, or cc-check.
 triggers:
   - 深度 review 这个方案
@@ -20,22 +20,17 @@ reads:
   - references/e2e-and-plugin-verification.md
   - scripts/collect-review-context.sh
 writes:
-  - path: devflow/changes/<change-key>/review/cc-review-plan.md
+  - path: devflow/changes/<change-key>/review/review-ledger.jsonl
     durability: durable
     required: true
-  - path: devflow/changes/<change-key>/review/cc-review-report.md
-    durability: durable
-    required: true
-  - path: devflow/changes/<change-key>/review/cc-review-ledger.jsonl
-    durability: durable
-    required: true
-  - path: devflow/changes/<change-key>/review/cc-review-agent-results.jsonl
+  - path: devflow/changes/<change-key>/review/review-findings.json
     durability: durable
     required: false
-    when: subagent reviewers are used
-  - path: devflow/changes/<change-key>/review/cc-review-findings.json
+    when: actionable findings need machine consumption
+  - path: devflow/changes/<change-key>/review/review-agent-results.jsonl
     durability: durable
     required: false
+    when: subagent reviewers are used
 effects:
   - optional deep review
   - read-only reviewer agent dispatch
@@ -45,18 +40,18 @@ effects:
 entry_gate:
   - Read planning/design.md or planning/analysis.md when the work is still plan-stage.
   - Read the current diff, task manifest, change metadata, and latest verification evidence when the work is execution-stage.
-  - Read prior cc-review-plan.md, cc-review-report.md, cc-review-ledger.jsonl, and cc-review-findings.json when present.
+  - Read prior `review-ledger.jsonl`, optional `review-findings.json`, optional `review-agent-results.jsonl`, and legacy `cc-review-*` files when present.
   - Use git diff or scripts/collect-review-context.sh to identify content changed since the last review before deciding what to re-review.
   - Classify the review branch as plan, implementation, or mixed before loading detailed references.
-  - Write or refresh cc-review-plan.md before producing findings.
-  - Decide whether nodes need independent reviewer agents before starting node execution; record the decision in cc-review-plan.md.
-  - For broad implementation or mixed reviews, decide whether the risk-lane review swarm profile is required; record used, skipped, or unavailable lanes in cc-review-plan.md.
+  - Start the durable review with `cc-devflow review start` before producing findings; encode selected nodes, skipped nodes, risk lanes, scope, base SHA, and head SHA in the first ledger event.
+  - Decide whether nodes need independent reviewer agents before starting node execution; record the decision in the `review-started` event and optional `review-agent-results.jsonl`.
+  - For broad implementation or mixed reviews, decide whether the risk-lane review swarm profile is required; record used, skipped, or unavailable lanes in `review-ledger.jsonl`.
   - Freeze the requested scope before finding smells; only report smells inside the requirement blast radius or clearly amplified by the current work.
 exit_criteria:
-  - cc-review-plan.md records selected tools, review nodes, skipped nodes with reasons, and checkpoint order.
-  - cc-review-ledger.jsonl appends one record per reviewed node with status, evidence, findings, and follow-up route.
-  - cc-review-agent-results.jsonl records read-only reviewer outputs when subagents are used, or cc-review-report.md records why agents were unavailable or unnecessary.
-  - cc-review-report.md records branch classification, scope, prior-review delta, methods used, node coverage, reviewer-lane coverage, findings triage, user decisions needed, quick fixes, and next route.
+  - review-ledger.jsonl records selected tools, review nodes, skipped nodes with reasons, review order, and final route through CLI events.
+  - review-ledger.jsonl appends one record per reviewed node with status, evidence refs, findings, and follow-up route.
+  - review-agent-results.jsonl records read-only reviewer outputs when subagents are used, or the review ledger records why agents were unavailable or unnecessary.
+  - review-findings.json exists only when later agents need structured findings; human Markdown is rendered on demand with `cc-devflow review render`.
   - Plan-stage reviews record every selected strategy/design/engineering/DX facet as checked, skipped, or blocked.
   - Implementation-stage reviews include diff evidence, code-smell evidence, test and E2E/plugin verification evidence for every selected changed surface.
   - Every in-scope code smell has a concrete recommendation or an explicit skip/defer rationale.
@@ -76,7 +71,7 @@ recovery_modes:
     action: Stop the current pass, restate the correct branch classification, load the matching reference, and restart from the scope freeze.
   - name: progressive-disclosure-reset
     when: The review is drowning in unrelated methods or external review templates.
-    action: Return to cc-review-plan.md, keep only review nodes that are in scope, and continue node-by-node instead of collapsing to a short finding list.
+    action: Return to the latest `review-started` event, keep only review nodes that are in scope, and continue node-by-node instead of collapsing to a short finding list.
 tool_budget:
   read_files: 24
   search_steps: 16
@@ -97,7 +92,7 @@ tool_budget:
 
 写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
 
-- `Output language` 是机器约束，`review/cc-review-report.md` 和 `review/cc-review-findings.json` 中新增的人类可读摘要必须记录并遵守它。
+- `Output language` 是机器约束，`review/review-ledger.jsonl`、`review/review-findings.json` 和 on-demand rendered Markdown 中新增的人类可读摘要必须记录并遵守它。
 - `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的 Review 边界。
 - 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
 
@@ -223,10 +218,10 @@ Low-confidence notes below `5` stay out of final findings unless they point to c
 Every run follows this loop:
 
 1. Collect prior review state:
-   - previous `cc-review-plan.md`
-   - previous `cc-review-report.md`
-   - previous `cc-review-ledger.jsonl`
-   - previous `cc-review-findings.json`
+   - previous `review-ledger.jsonl`
+   - previous `review-findings.json`
+   - previous `review-agent-results.jsonl`
+   - legacy `cc-review-plan.md` / `cc-review-report.md` / `cc-review-ledger.jsonl` / `cc-review-findings.json` only as fallback
 2. Collect current delta:
    - `git diff <last-reviewed-sha>...HEAD` when a reviewed SHA exists
    - otherwise `git diff <base>...HEAD`
@@ -243,14 +238,12 @@ Every run follows this loop:
    - which nodes need independent subagent review
    - which nodes stay in main thread
    - why any eligible reviewer was skipped
-5. Write `cc-review-plan.md` before findings:
-   - node id
-   - target artifact or code surface
-   - tool/reference to load
-   - reason selected
-   - owner: `main` or reviewer name
-   - check command or evidence source
-   - status: `pending`
+5. Run `cc-devflow review start` before findings:
+   - selected node ids
+   - skipped nodes and reasons
+   - review mode and scope
+   - risk lanes
+   - base/head SHA
 6. Traverse nodes one by one:
    - review the node
    - run the smallest useful check for that node
@@ -268,40 +261,23 @@ When re-reviewing the same file or plan, do not restart from zero. Compare curre
 
 ## Output Contract
 
-Write `review/cc-review-plan.md` before the review pass with:
-
-1. Branch classification and review scope.
-2. Prior review records found.
-3. Current git/artifact delta.
-4. Selected tools and skipped tools with reasons.
-5. Reviewer dispatch plan: agents used, unavailable, skipped, or unnecessary.
-6. Risk-lane coverage for implementation or mixed reviews.
-7. Ordered review nodes and per-node check plan.
-
-Write `review/cc-review-report.md` with:
-
-1. Review branch classification and scope.
-2. Source artifacts read and prior review records used.
-3. Current delta against previous review or base.
-4. Review methods used and methods intentionally skipped.
-5. Node coverage table.
-6. Reviewer dispatch summary, risk-lane coverage, and agent result paths.
-7. Raw finding triage: accepted, merged, downgraded, rejected.
-8. Findings by severity, each with evidence, smell category when relevant, recommendation, and route.
-9. Quick mechanical fixes that can be handled by `cc-do`.
-10. Decision questions still needing user input.
-11. E2E / Browser / Computer Use evidence when applicable.
-12. Final next action.
-
-Append one JSON line to `review/cc-review-ledger.jsonl` per reviewed node:
+Use CLI records as the default durable output:
+
+1. `cc-devflow review start --change <id> --change-key <key> --mode <plan|implementation|mixed> --scope <scope> --base-sha <sha> --head-sha <sha> --selected-node <node> --skipped-node <node:reason> --risk-lane <lane>`
+2. `cc-devflow review record-node --review-id <id> --node-id <node> --target <artifact> --status checked|skipped|blocked --evidence-ref <ref> --finding <id> --next <skill>`
+3. `cc-devflow review add-finding --review-id <id> --finding-id <id> --severity <level> --confidence <1-10> --display-tier <blocking|warning> --path <path> --evidence <evidence> --recommendation <text> --route <skill>`
+4. `cc-devflow review close --review-id <id> --status clean|findings|blocked --blocking-count <n> --warning-count <n> --next <skill>`
+5. `cc-devflow review render --review-id <id> --output <path>` only when a human Markdown report is explicitly needed.
+
+Append one JSON line to `review/review-ledger.jsonl` per review event. A reviewed node event looks like:
 
 ```json
 {"nodeId":"R001","status":"checked","target":"planning/design.md","tool":"engineering","headSha":"...","evidence":["..."],"findings":["F001"],"next":"cc-plan"}
 ```
 
-Write `review/cc-review-findings.json` when findings need machine consumption by later agents.
+Write `review/review-findings.json` only when findings need machine consumption by later agents.
 
-Write `review/cc-review-agent-results.jsonl` when subagents are used. It contains raw reviewer findings plus reviewer identity. The report must say which raw findings were accepted, merged, downgraded, or rejected.
+Write `review/review-agent-results.jsonl` when subagents are used. It contains raw reviewer findings plus reviewer identity. The ledger or rendered report must say which raw findings were accepted, merged, downgraded, or rejected.
 
 ## Finding Rules
 

package/.claude/skills/cc-review/references/e2e-and-plugin-verification.md

@@ -64,7 +64,7 @@ When Codex plugins are part of the expected path:
 
 ## Report Format
 
-Add an E2E section to `cc-review-report.md`:
+Record E2E evidence in `review-ledger.jsonl` and render it into Markdown on demand:
 
 ```markdown
 ## E2E / Plugin Evidence

package/.claude/skills/cc-review/references/implementation-review-branch.md

@@ -41,7 +41,7 @@ For broad or PR-landing diffs, prefer the risk-lane review swarm profile from `r
 3. Performance and reliability
 4. Contracts and coverage
 
-The lanes may map onto the passes below, but they should stay separate in `cc-review-plan.md` and raw reviewer output when separate reviewers are used.
+The lanes may map onto the passes below, but they should stay separate in `review-ledger.jsonl` and raw reviewer output when separate reviewers are used.
 
 ### 1. Contract Fidelity
 
@@ -57,7 +57,7 @@ Check whether implementation matches the frozen plan or investigation:
 
 Use `review-methods.md` smell taxonomy.
 
-If this pass finds duplication, over-complexity, awkward abstraction, branch forests, unclear ownership, or broad architecture cleanup risk, load `cc-simplify` and record it as a selected tool in `cc-review-plan.md`.
+If this pass finds duplication, over-complexity, awkward abstraction, branch forests, unclear ownership, or broad architecture cleanup risk, load `cc-simplify` and record it as a selected tool in `review-ledger.jsonl`.
 
 Look for:
 
@@ -110,7 +110,7 @@ If changed behavior affects README, guides, CLI help, package install, public AP
 Use git and prior review records:
 
 1. Find changed files with `git diff <base>...HEAD --name-only`.
-2. If prior `cc-review-ledger.jsonl` records a reviewed SHA, narrow to `git diff <reviewedSha>...HEAD`.
+2. If prior `review-ledger.jsonl` records a reviewed SHA, narrow to `git diff <reviewedSha>...HEAD`; fall back to legacy `cc-review-ledger.jsonl` only when needed.
 3. Group changed files by behavior surface, not just extension.
 4. Add dependent nodes for direct importers/callers when a shared helper, enum, state shape, API contract, or skill contract changes.
 5. Preserve prior clean nodes only when the target file and dependent contract did not change.
@@ -136,7 +136,7 @@ If the user explicitly asks to fix findings in the same turn, switch to `cc-do`
 
 ## Output Requirements
 
-Add to `cc-review-report.md`:
+Record in `review-ledger.jsonl` and render on-demand Markdown when a human report is needed:
 
 - base branch and diff summary
 - scope check
@@ -149,4 +149,4 @@ Add to `cc-review-report.md`:
 - docs/DX notes
 - final route
 
-Write `cc-review-findings.json` when there are actionable findings.
+Write `review-findings.json` when there are actionable findings that later agents need to consume.