cc-devflow 4.5.7 → 4.5.9

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

@@ -7,32 +7,35 @@
 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`，不能只留在聊天里。
+6. 所有 SKILL 输出必须遵守 `docs/guides/artifact-contract.md`：状态只能有一个 owner，其它文件只能引用、投影或派生。
+7. 计划里出现 placeholder 词，就说明还没想清楚。
+8. 一次只推进一个澄清问题，不允许问题轰炸。
+9. 推荐方案没获批前，不允许继续拆执行任务。
+10. `planning/design.md` 通过 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/design.md`，不能在任务里发明第二套语言。
+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/design.md`：用户视角问题、用户视角方案、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/design.md` 的 `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
@@ -73,11 +85,24 @@
 - 涉及文件
 - 验证方式
 - 完成证据
+- 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 可以例外，但必须写明原因、风险和替代验证。
 不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
 也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
 
+## Execution Protocol Fields
+
+`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 后重跑，禁止手工绕过
+- 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
 
 每个需要用户判断的 gate 至少记录：

package/.claude/skills/cc-pr-land/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Added review-first, rebase-first PR landing workflow with main parity proof.

package/.claude/skills/cc-pr-land/PLAYBOOK.md

@@ -0,0 +1,45 @@
+# CC-PR-Land Playbook
+
+## Visible State Machine
+
+`reviewed remote PRs -> cc-pr-land -> main parity | cc-pr-review | cc-dev | stop`
+
+- Enter from: `cc-pr-review` approval, PR URL, PR number, or user request to land reviewed PRs.
+- Stay in: `cc-pr-land` until each PR has review truth, rebase truth, conflict truth, validation truth, and parity truth.
+- Exit to: main parity, `cc-pr-review` for missing review, `cc-dev` for implementation gaps, or stop when GitHub truth is unavailable.
+
+## Core Rules
+
+1. GitHub live PR list is truth.
+2. 先 review，再 landing。
+3. rebase 到 evolving mainline，不 rebase 到过期 main。
+4. 冲突解决后必须 re-review。
+5. 不允许需求缩水。
+6. 不确定是不是需求缩水，就停下来问。
+7. 用 `--force-with-lease` 更新 PR head，不无脑 force。
+8. main 只允许 ff-only / inspected push，不覆盖未检查远端。
+9. landing 后必须证明 local main、remote main、active main worktree 一致。
+10. 临时 branch / worktree 要清理或报告。
+
+## Required Outputs
+
+- Live PR truth set
+- Landing order
+- Review evidence
+- Rebase/conflict notes
+- Post-conflict re-review verdict
+- Validation evidence
+- Main parity proof
+- Cleanup result
+
+## Stop Conditions
+
+Stop instead of guessing when:
+
+- GitHub truth unavailable
+- PR queue changed mid-run
+- review evidence is missing
+- conflict intent is unclear
+- resolved diff drops required behavior
+- validation fails only after integration
+- main parity cannot be proven

package/.claude/skills/cc-pr-land/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: cc-pr-land
+version: 1.0.0
+description: Use in a separate session to land one or more reviewed GitHub PRs into main with review-first, rebase-first discipline. It refreshes live PR truth, rebases each PR onto the evolving mainline, resolves conflicts without shrinking requirements, re-reviews after conflict resolution, pushes cleaned PR heads when needed, fast-forwards main, verifies local/remote parity, and cleans temporary branches. It must not implement new feature scope.
+triggers:
+  - 合并这个 PR
+  - 单独会话合并 PR
+  - land this PR
+  - merge reviewed PRs
+  - review and land open PRs
+  - rebase PRs onto main
+reads:
+  - ../cc-pr-review/SKILL.md
+  - ../cc-review/SKILL.md
+  - ../cc-check/SKILL.md
+  - GitHub pull requests
+  - devflow/changes/<change-key>/review/report-card.json
+writes:
+  - path: GitHub pull request head branch
+    durability: remote
+    required: false
+    when: the PR branch must be rebased or conflict fixes must be pushed back
+  - path: origin/main
+    durability: remote
+    required: true
+    when: landing succeeds
+effects:
+  - review-first PR landing
+  - rebase-first mainline integration
+  - local and remote main parity proof
+entry_gate:
+  - Fetch live GitHub PR truth; do not rely on stale local refs or cached queue state.
+  - Require prior review truth or perform a review pass before landing.
+  - Create only temporary integration/helper branches as needed; do not open new feature worktrees as product work.
+  - Rebase onto the evolving integration mainline, not stale origin/main.
+  - Stop when conflict resolution would require product intent guessing.
+exit_criteria:
+  - Each landed PR was reviewed before landing and re-reviewed after material rebase or conflict resolution.
+  - Requirement shrinkage after conflict resolution is explicitly rejected or ruled out.
+  - Remote main, local main, and the active main worktree parity are verified.
+  - Open PR queue state is refreshed after landing when the task was to clear the queue.
+  - Temporary branches or integration worktrees created by cc-pr-land are cleaned up or reported.
+reroutes:
+  - when: The PR has unreviewed implementation risk or stale review evidence.
+    target: cc-pr-review
+  - when: Conflict resolution reveals missing implementation or broken requirements.
+    target: cc-dev
+  - when: Mainline parity cannot be proven because GitHub, auth, or network truth is unavailable.
+    target: stop
+recovery_modes:
+  - name: queue-changed
+    when: The live open PR set changes during landing.
+    action: Stop, refresh the queue, and recalculate the landing order before continuing.
+  - name: requirement-shrinkage-risk
+    when: A conflict resolution makes the PR smaller or removes user-facing behavior, tests, or docs.
+    action: Re-review the resolved diff and stop for user decision if intent is unclear.
+  - name: parity-failure
+    when: local main, active main worktree, and origin/main do not match after landing.
+    action: Diagnose without force reset; preserve local work and repair through fetch/rebase/ff-only sync.
+tool_budget:
+  read_files: 12
+  search_steps: 8
+  shell_commands: 18
+---
+
+# CC-PR-Land
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、公开文档和分发配置，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-pr-land` 是远程 PR 的落主干入口。它回答：
+
+```text
+这些已经 review 的 PR 是否可以线性落到 main，并证明本地远程一致？
+```
+
+它不做新需求开发。发现需要新代码，回 `cc-dev`。
+
+## Read First
+
+1. Live GitHub PR truth
+2. `../cc-pr-review/SKILL.md`
+3. `../cc-review/SKILL.md`
+4. `../cc-check/SKILL.md`
+5. Linked change artifacts when available
+
+## Use This Skill When
+
+- 一个或多个 PR 已 review，准备合并。
+- 用户要求 review-first / rebase-first 落主干。
+- 用户要求清空 open PR 队列并证明 main parity。
+
+如果 PR 还没 review，先去 `cc-pr-review`。
+
+## Harness Contract
+
+- Allowed actions: refresh PR truth, verify prior review, rebase PR branches, resolve conflicts, re-review resolved diffs, push cleaned PR heads, fast-forward main, verify parity, and clean temporary integration state.
+- Forbidden actions: implement new feature scope, silently drop requirements, force-push main, rely on stale PR refs, or declare parity without remote proof.
+- Required evidence: PR list, review status, commit ranges, conflict resolutions, validation commands, remote main SHA, local main SHA, and active main worktree SHA when available.
+- Reroute rule: unreviewed PRs go to `cc-pr-review`; requirement or implementation gaps go to `cc-dev`; unavailable GitHub truth stops landing.
+
+## Landing Order
+
+1. Fetch live PR truth.
+2. Record PR number, title, head, base, review state, checks, and linked change.
+3. For each PR:
+   - confirm review exists or run/re-route to `cc-pr-review`
+   - separate true PR commits from base drift
+   - rebase onto the evolving integration mainline
+   - resolve conflicts without shrinking requirements
+   - re-review if the rebase or conflict resolution changed behavior
+   - push cleaned PR head with `--force-with-lease` when the PR branch changed
+   - fast-forward the integration branch
+4. Validate integrated result.
+5. Push or fast-forward main.
+6. Verify parity.
+7. Clean temporary state.
+
+## Conflict Rule
+
+Conflict resolution is not a place to redesign the product.
+
+After every conflict:
+
+- compare before vs after intent
+- check tests and docs were not silently dropped
+- rerun targeted verification
+- re-review resolved files
+
+If you cannot distinguish better upstream implementation from accidental requirement loss, stop and ask.
+
+## Parity Proof
+
+Do not declare done until these are true or explicitly blocked:
+
+```text
+origin/main SHA: <sha>
+local main SHA: <sha>
+active main worktree SHA: <sha or not-applicable>
+open PR queue: <empty or remaining list>
+```
+
+Use ff-only sync. Do not force reset user work.
+
+## Output
+
+Report:
+
+- PRs landed
+- PRs skipped and why
+- review evidence used
+- conflicts and requirement-shrinkage verdict
+- validation commands
+- final remote/local main SHA
+- open PR queue state
+- cleanup actions

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

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Added independent remote PR review workflow that separates review from landing.

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

@@ -0,0 +1,46 @@
+# CC-PR-Review Playbook
+
+## Visible State Machine
+
+`remote PR -> cc-pr-review -> cc-dev | cc-do | cc-pr-land | stop`
+
+- Enter from: a remote PR URL, PR number, or `cc-dev` terminal state.
+- Stay in: `cc-pr-review` until PR truth, diff intent, checks, artifacts, findings, and verdict are explicit.
+- Exit to: `cc-pr-land` when approved, `cc-dev` or `cc-do` when fixes are required, or stop when blocked or unclear.
+
+## Core Rules
+
+1. 只 review，不 merge。
+2. 先冻结 GitHub PR truth。
+3. 先区分 true PR commits 和 stale base drift。
+4. 先写 review packet，再写 findings。
+5. finding 必须有证据。
+6. 没有证据就写 unknown，不伪装成 bug。
+7. 宽 diff 使用四类风险 lane。
+8. subAgent reviewer 只读；主线程负责验证和去重。
+9. PR head 或 checks 改了，重新 refresh。
+10. 干净 PR 的下一步是 `cc-pr-land`，不是在本 skill 里顺手合并。
+
+## Required Outputs
+
+- PR review packet
+- Covered lanes
+- Findings triage
+- Checks status
+- Verdict
+- Next gate
+
+## Finding Shape
+
+Each accepted finding should include:
+
+```text
+- Path or PR surface:
+- Issue:
+- Why it matters:
+- Evidence:
+- Confidence:
+- Fix path:
+```
+
+Speculative or style-only comments do not block landing.

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

@@ -0,0 +1,142 @@
+---
+name: cc-pr-review
+version: 1.0.0
+description: Use in a separate session to review one remote GitHub PR before landing. It fetches PR truth, builds a review packet, runs cc-review-style plan or implementation review with optional read-only reviewers, records findings, and updates the PR or reroutes to cc-dev/cc-do for fixes. It must not merge the PR or push main.
+triggers:
+  - review 这个 PR
+  - 单独会话 review PR
+  - 审这个远程 PR
+  - review remote PR
+  - pre-landing PR review
+  - check this PR before merge
+reads:
+  - ../cc-review/SKILL.md
+  - ../cc-check/SKILL.md
+  - GitHub pull request
+  - devflow/changes/<change-key>/review/report-card.json
+writes:
+  - path: devflow/changes/<change-key>/review/cc-pr-review.md
+    durability: durable
+    required: false
+    when: the PR maps to a local cc-devflow change
+  - path: GitHub pull request comments or review
+    durability: remote
+    required: false
+    when: remote review feedback is posted
+effects:
+  - remote PR review packet
+  - finding triage
+  - fix or landing recommendation
+entry_gate:
+  - Freeze PR title, body, commits, head branch, base branch, checks, linked issues, and current diff from GitHub.
+  - Separate true PR commits from stale base drift before judging the diff.
+  - Read local cc-devflow artifacts when the PR links to a change key.
+  - Build a review packet before producing findings.
+  - Do not merge, push main, or mark the PR landed.
+exit_criteria:
+  - Review result is exactly one of approved-for-landing, changes-requested, needs-clarification, or blocked.
+  - Findings cite concrete PR diff, artifacts, command output, checks, or missing evidence.
+  - Any required fixes route back to cc-dev or cc-do; clean PRs route to cc-pr-land.
+  - No merge or mainline integration happened inside cc-pr-review.
+reroutes:
+  - when: Required fixes are inside the PR implementation scope.
+    target: cc-dev
+  - when: The PR is clean and ready to land.
+    target: cc-pr-land
+  - when: The review needs deeper local artifact or diff review.
+    target: cc-review
+recovery_modes:
+  - name: stale-pr-refresh
+    when: PR head, checks, comments, or base branch changed during review.
+    action: Refresh GitHub PR truth and rebuild the review packet before continuing.
+  - name: base-drift-confusion
+    when: The raw PR diff appears to delete or rewrite unrelated base work.
+    action: Use commit and cherry inspection to separate true PR changes from stale-base perspective.
+tool_budget:
+  read_files: 10
+  search_steps: 6
+  shell_commands: 12
+---
+
+# CC-PR-Review
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、公开文档和分发配置，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-pr-review` 是远程 PR 的独立审查入口。它回答：
+
+```text
+这个 PR 是否可以交给 cc-pr-land 合并？
+```
+
+它只 review，不合并。
+
+## Read First
+
+1. GitHub PR snapshot
+2. `../cc-review/SKILL.md`
+3. `../cc-check/SKILL.md`
+4. Linked `devflow/changes/<change-key>/` artifacts when available
+
+## Use This Skill When
+
+- PR 已经由 `cc-dev` 创建或更新。
+- 用户想在独立会话 review PR。
+- 合并前需要证明 diff、测试、门禁和需求没有漂移。
+
+如果用户要求合并，进入 `cc-pr-land`，不要把 review 和 landing 混成一个动作。
+
+## Harness Contract
+
+- Allowed actions: fetch PR truth, build review packet, inspect diffs/artifacts/checks, run safe verification, dispatch read-only reviewers when available, record review findings, and recommend fix or landing.
+- Forbidden actions: merge PRs, push main, rewrite unrelated PR scope, or accept findings without evidence.
+- Required evidence: every accepted finding must cite PR diff, local artifact, command output, check result, issue/PR text, or explicit missing evidence.
+- Reroute rule: required implementation fixes go back to `cc-dev` or `cc-do`; clean PRs go to `cc-pr-land`.
+
+## Review Packet
+
+Build this before findings:
+
+```text
+PR Review Packet
+- PR: #<number> <title>
+- Base/head: <base> <- <head>
+- Intended behavior: <from PR body, issue, commits, artifacts>
+- Must remain unchanged: <known invariants>
+- True PR commits: <commit range>
+- Drift ruled out: <yes/no and evidence>
+- Checks: <latest status>
+- Local artifacts: <change key and report-card if found>
+```
+
+## Review Lanes
+
+Use `cc-review` methods. For broad diffs, cover:
+
+- intent and regression
+- security and privacy
+- performance and reliability
+- contracts and coverage
+
+Small diffs may combine lanes, but the report must state what was covered or skipped.
+
+## Verdicts
+
+- `approved-for-landing`: no blocking findings; route to `cc-pr-land`.
+- `changes-requested`: PR needs fixes; route to `cc-dev` or `cc-do`.
+- `needs-clarification`: product intent or requirement shrinkage is unclear.
+- `blocked`: GitHub, auth, checks, dependencies, or local artifacts are unavailable.
+
+## Output
+
+Report:
+
+- PR number and URL
+- review packet summary
+- lanes covered or skipped
+- accepted findings
+- rejected or downgraded raw findings when reviewers were used
+- latest checks
+- verdict
+- next gate

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

@@ -1,5 +1,26 @@
 # CC-Review Changelog
 
+## 1.3.0
+
+- Added a risk-lane review swarm profile for broad implementation and PR-landing reviews.
+- Required `cc-review-plan.md` and `cc-review-report.md` to record intent/regression, security/privacy, performance/reliability, and contracts/coverage lane coverage when applicable.
+- Hardened main-thread aggregation so raw reviewer findings are accepted, merged, downgraded, or rejected before becoming final findings.
+
+## 1.2.0
+
+- Added automatic read-only reviewer subAgent dispatch for selected plan and implementation review nodes.
+- Required reviewer packets to be self-contained so each subAgent works from independent context instead of inherited chat assumptions.
+- Added `cc-review-agent-results.jsonl` for raw reviewer outputs and report-level accepted/merged/downgraded/rejected triage.
+- Required truthful main-thread fallback when the host does not expose subAgent tools.
+
+## 1.1.0
+
+- Added stateful review planning with `cc-review-plan.md` and per-node `cc-review-ledger.jsonl`.
+- Required prior review records and git/artifact deltas before re-reviewing the same plan or implementation.
+- Replaced short finding-list behavior with node-by-node review, per-node checks, and no artificial finding cap.
+- Added decision queues so user-judgment findings are collected after traversal and confirmed one by one before non-mechanical fixes.
+- Added `cc-simplify` selection guidance for code-smell and simplification review nodes.
+
 ## 1.0.0
 
 - Added `cc-review` as an optional deep review workflow that branches between plan-stage and implementation-stage review.

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

@@ -14,19 +14,30 @@
 ## Core Rules
 
 1. 先判断 review 对象是计划、实现，还是混合。
-2. 只读当前需求范围内的坏味道；历史债只在被本次变更放大时进入。
-3. `cc-check` 是证据验收，`cc-review` 是深度诊断，两者不要混成一个门。
-4. 计划分支按 strategy / design / engineering / DX 渐进加载，不把所有方法一次塞进上下文。
-5. 实现分支先读 diff 和意图，再读周边代码，最后才给 finding。
-6. UI 或运行时链路有风险时，必须用 Browser / Computer Use / CLI / logs 做端到端证明或写清阻塞原因。
-7. 每个坏味道必须有 evidence、scope、recommendation 和 route。
-8. 没有证据就写 unknown，不准把审美判断伪装成缺陷。
-9. 发现计划合同错误，回 `cc-plan`；发现代码错误，回 `cc-do`；只差验收，进 `cc-check`。
-10. 输出必须落到 `review/cc-review-report.md`，不能只留在聊天里。
+2. 先读上一次 `cc-review` 的 plan / report / ledger / findings，再看当前 git 或 artifact delta。
+3. 先写 `cc-review-plan.md`，列出要用哪些 Review 工具和哪些节点需要遍历。
+4. 对适合独立审查的节点，优先派发只读 reviewer subAgent；没有工具时如实降级。
+5. 复杂实现 diff 优先使用 intent/regression、security/privacy、performance/reliability、contracts/coverage 四类风险 lane；小 diff 可以合并但必须说明。
+6. 按节点逐个 Review：review 一个、check 一个、ledger 记录一个。
+7. 主线程必须验证 subAgent findings，不盲信 reviewer。
+8. 只读当前需求范围内的坏味道；历史债只在被本次变更放大时进入。
+9. `cc-check` 是证据验收，`cc-review` 是深度诊断，两者不要混成一个门。
+10. 计划分支按 strategy / design / engineering / DX 选择节点，不把所有方法一次塞进上下文，但不能因为渐进加载而跳过未审节点。
+11. 实现分支先读 diff 和意图，再读周边代码；每个 changed surface 都要 checked、skipped 或 blocked。
+12. UI 或运行时链路有风险时，必须用 Browser / Computer Use / CLI / logs 做端到端证明或写清阻塞原因。
+13. 每个坏味道必须有 evidence、scope、recommendation 和 route。
+14. 没有证据就写 unknown，不准把审美判断伪装成缺陷。
+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`，不能只留在聊天里。
 
 ## 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
 
 ## Local Kit
@@ -35,6 +46,45 @@
 - `references/plan-review-branch.md`: plan-stage deep review
 - `references/implementation-review-branch.md`: diff and code-stage deep review
 - `references/e2e-and-plugin-verification.md`: Browser / Computer Use / logs evidence
+- `scripts/collect-review-context.sh`: git delta and prior-review state helper
+
+## Stateful Review Plan
+
+`cc-review-plan.md` 必须至少包含：
+
+- review mode：plan / implementation / mixed
+- previous review state：上次 report、ledger、findings 是否存在
+- delta：本次相对哪个 SHA、哪些文件、哪些 artifacts 变了
+- selected tools：CEO/strategy、engineering、design、DX、TOC、code smell、cc-simplify、E2E/plugin/logs
+- skipped tools：为什么不需要
+- reviewer dispatch：哪些节点交给 subAgent、哪些主线程执行、为什么
+- 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；不要等最后一次性补记。
+
+## SubAgent Review
+
+触发 `cc-review` 本身就授权只读 reviewer subAgent。主线程不要为了“再确认是否能用 subAgent”打断用户。
+
+调度规则：
+
+- 大范围 / 多文件 / 多 facet review：至少尝试两个独立 reviewer。
+- 小范围 review：至少尝试一个 combined reviewer，除非 `cc-review-plan.md` 写明不需要。
+- Plan 节点可分配 strategy、engineering、design、DX、TOC reviewer。
+- Implementation 节点可分配 contract、smell、test、runtime reviewer。
+- 复杂 implementation 节点优先按四类风险 lane 派发 reviewer：intent/regression、security/privacy、performance/reliability、contracts/coverage。
+- Codex 环境优先用 `explorer`；ClaudeCode 环境用可用的 `Task` / subAgent。
+- reviewer 只读，不编辑文件，不改计划，不直接决定最终 route。
+- reviewer 的上下文应独立，只给 review packet，不给完整聊天历史。
+- 主线程负责合并、验证、去重和降级 false positive。
+
+如果没有 subAgent 工具，报告必须写：
+
+```text
+Agents used: no (subagent tool unavailable)
+Fallback: main-thread node-by-node review
+```
 
 ## Review Standard
 
@@ -47,8 +97,12 @@
 - 哪些代码坏味道在当前 blast radius 内？
 - 哪些测试、日志、UI 操作或端到端证据缺失？
 - 哪些 finding 必须修，哪些可以 defer，哪些只是 advisory？
+- 哪些节点已经被审过，哪些因为 delta 需要复审？
+- 哪些节点没有审，为什么 skip 或 blocked？
+- 哪些 reviewer 被派发，哪些 findings 被接受、合并、降级或拒绝？
+- 四类风险 lane 哪些覆盖了，哪些因为 scope 小或工具不可用而跳过？
 - 下一步为什么是 `cc-plan` / `cc-do` / `cc-check`？
 
 ## Decision Rule
 
-一个 finding 如果会改变范围、架构、用户可见行为、公共 API、测试策略或超过机械局部清理，必须交给用户决策或 reroute 到上游 skill。机械且低风险的问题可以作为 `cc-do` 的明确修复项，但 `cc-review` 自身不偷偷改代码。
+一个 finding 如果会改变范围、架构、用户可见行为、公共 API、测试策略或超过机械局部清理，必须进入用户决策队列或 reroute 到上游 skill。先列完整决策清单，再逐个问题向用户确认；确认前不做非机械修复。机械且低风险的问题可以作为 `cc-do` 的明确修复项，但 `cc-review` 自身不偷偷改代码。