cc-devflow 4.5.6 → 4.5.7

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

@@ -16,7 +16,7 @@
 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 目录必须是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`，不能用小写 `req-*` / `bug-*` 或纯描述目录；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
+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 证明行为缺失。
@@ -25,11 +25,14 @@
 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. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
-25. Roadmap Sync Gate 必须在退出前闭合：source RM 存在就回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`；不存在就记录 no-op reason。
-26. PRD-grade requirement brief 必须并入 `planning/design.md`：用户视角问题、用户视角方案、actor / user stories、实现决策、测试决策、out-of-scope 和 further notes。默认不得额外产出 `PRD.md`。
-27. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥选项、影响和 STOP 都必须出现；禁止用自由问句代替审批 gate。
-28. 所有用户决策必须写入 `planning/design.md` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
+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`，不能只留在聊天里。
 
 ## Design Modes
 
@@ -80,10 +83,10 @@
 每个需要用户判断的 gate 至少记录：
 
 - questionId：`D1` / `D2` / ...
-- gate：`planning-mode` / `ambiguity-blocker` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
+- gate：`planning-mode` / `ambiguity-blocker` / `external-best-practice` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
 - knownEvidence
 - recommendation
-- options
+- options：只能使用 `A` / `B` / `C` 作为 option id
 - userChoice
 - impact
 - status：`asked` / `answered` / `auto-decided`
@@ -112,13 +115,15 @@
 16. Green minimality / refactor candidate scan
 17. PRD brief scan
 18. Source trust boundary scan
-19. External conflict scan
-20. Ambiguity gate
-21. Bounded review loop
-22. NOT in scope
-23. Test-first readiness
-24. Decision questions recorded
-25. Final recommendation
+19. External best-practice validation scan
+20. AI Leverage Decision Lens scan
+21. External conflict scan
+22. Ambiguity gate
+23. Bounded review loop
+23. NOT in scope
+24. Test-first readiness
+25. Decision questions recorded
+26. Final recommendation
 
 如有 UI scope，再补 design review 结论。
 如有 developer-facing scope，再补 DX review 结论。

package/.claude/skills/cc-plan/scripts/next-change-key.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 计算下一个 REQ/FIX change key，输出两行：changeId 和 changeKey
+
+usage() {
+  echo 'Usage: next-change-key.sh --prefix REQ|FIX --description "short description" [--cwd path]'
+}
+
+PREFIX=""
+DESCRIPTION=""
+CWD=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --prefix) PREFIX="$2"; shift 2 ;;
+    --description) DESCRIPTION="$2"; shift 2 ;;
+    --cwd) CWD="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$PREFIX" || -z "$DESCRIPTION" ]]; then
+  usage
+  exit 1
+fi
+
+REPO_ROOT="${CWD:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# 优先用本仓库 node CLI（最可靠），再用全局 cc-devflow，最后纯 bash 兜底
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI_JS="$SCRIPT_DIR/../../../../bin/cc-devflow-cli.js"
+
+if [[ -f "$CLI_JS" ]] && command -v node >/dev/null 2>&1; then
+  node "$CLI_JS" next-change-key --prefix "$PREFIX" --description "$DESCRIPTION" --cwd "$REPO_ROOT"
+  exit $?
+fi
+
+if command -v cc-devflow >/dev/null 2>&1; then
+  cc-devflow next-change-key --prefix "$PREFIX" --description "$DESCRIPTION" --cwd "$REPO_ROOT"
+  exit $?
+fi
+
+# 纯 bash 兜底：扫描 devflow/changes/ 取 max+1
+CHANGES_DIR="$REPO_ROOT/devflow/changes"
+PREFIX_UPPER="$(echo "$PREFIX" | tr '[:lower:]' '[:upper:]')"
+
+MAX_NUM=0
+PAD_WIDTH=3
+
+if [[ -d "$CHANGES_DIR" ]]; then
+  for dir in "$CHANGES_DIR/${PREFIX_UPPER}-"*; do
+    [[ -d "$dir" ]] || continue
+    basename="$(basename "$dir")"
+    num_part="$(echo "$basename" | sed -E "s/^${PREFIX_UPPER}-([0-9]+).*/\1/")"
+    if [[ "$num_part" =~ ^[0-9]+$ ]]; then
+      num=$((10#$num_part))
+      if (( num > MAX_NUM )); then
+        MAX_NUM=$num
+      fi
+      if (( ${#num_part} > PAD_WIDTH )); then
+        PAD_WIDTH=${#num_part}
+      fi
+    fi
+  done
+fi
+
+NEXT_NUM=$((MAX_NUM + 1))
+PADDED_NUM="$(printf "%0${PAD_WIDTH}d" "$NEXT_NUM")"
+CHANGE_ID="${PREFIX_UPPER}-${PADDED_NUM}"
+
+SLUG="$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed -E 's/[[:space:]_]+/-/g; s/^-+|-+$//g')"
+[[ -z "$SLUG" ]] && SLUG="change"
+
+CHANGE_KEY="${CHANGE_ID}-${SLUG}"
+echo "$CHANGE_ID"
+echo "$CHANGE_KEY"

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

@@ -0,0 +1,7 @@
+# CC-Review Changelog
+
+## 1.0.0
+
+- Added `cc-review` as an optional deep review workflow that branches between plan-stage and implementation-stage review.
+- Added progressive references for TOC/root-cause methods, plan review, implementation review, and Codex plugin E2E verification.
+- Added durable review report and structured findings output contracts.

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

@@ -0,0 +1,54 @@
+# CC-Review Playbook
+
+## Visible State Machine
+
+`cc-plan / cc-investigate -> cc-review -> cc-plan | cc-do`
+
+`cc-do -> cc-review -> cc-do | cc-check`
+
+- Enter from: a complex plan, investigated bug, implementation diff, review comment, or user request for deep review.
+- Stay in: `cc-review` until the branch type, scope, findings, plugin/E2E evidence needs, and next route are explicit.
+- Exit to: `cc-plan` for broken plan contracts, `cc-do` for implementation fixes, or `cc-check` for fresh verification.
+- Reroute to: `cc-act` only if `cc-check` is already fresh and clean.
+
+## 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`，不能只留在聊天里。
+
+## Required Outputs
+
+- `review/cc-review-report.md`
+- `review/cc-review-findings.json` when later agents need structured findings
+
+## Local Kit
+
+- `references/review-methods.md`: TOC / logic tree / smells / severity rules
+- `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
+
+## Review Standard
+
+`cc-review` 至少回答：
+
+- 这次 Review 的对象是什么？
+- 当前 scope 的真实意图是什么？
+- 现有代码或计划已经解决了哪些子问题？
+- 哪些设计约束会让实现变脆？
+- 哪些代码坏味道在当前 blast radius 内？
+- 哪些测试、日志、UI 操作或端到端证据缺失？
+- 哪些 finding 必须修，哪些可以 defer，哪些只是 advisory？
+- 下一步为什么是 `cc-plan` / `cc-do` / `cc-check`？
+
+## Decision Rule
+
+一个 finding 如果会改变范围、架构、用户可见行为、公共 API、测试策略或超过机械局部清理，必须交给用户决策或 reroute 到上游 skill。机械且低风险的问题可以作为 `cc-do` 的明确修复项，但 `cc-review` 自身不偷偷改代码。

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

@@ -0,0 +1,173 @@
+---
+name: cc-review
+version: 1.0.0
+description: Use when a complex requirement, bug fix, plan, or implementation diff needs an optional deep multi-round review beyond cc-check. Routes plan-stage material through strategy/design/engineering/DX review methods, routes execution-stage code through diff/code-quality/E2E review, identifies in-scope code smells, and writes durable cc-review findings before rerouting to cc-plan, cc-do, or cc-check.
+triggers:
+  - 深度 review 这个方案
+  - review 这个复杂需求
+  - review 这个 bug 修复
+  - 做一次 cc-review
+  - deep review this plan
+  - review this implementation deeply
+  - check code smells
+  - run cc-review
+reads:
+  - PLAYBOOK.md
+  - CHANGELOG.md
+  - references/review-methods.md
+  - references/plan-review-branch.md
+  - references/implementation-review-branch.md
+  - references/e2e-and-plugin-verification.md
+writes:
+  - path: devflow/changes/<change-key>/review/cc-review-report.md
+    durability: durable
+    required: true
+  - path: devflow/changes/<change-key>/review/cc-review-findings.json
+    durability: durable
+    required: false
+effects:
+  - optional deep review
+  - durable findings
+  - reroute recommendation
+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.
+  - Classify the review branch as plan, implementation, or mixed before loading detailed references.
+  - 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-report.md records branch classification, scope, methods used, findings, user decisions needed, and next route.
+  - Plan-stage reviews record strategy/design/engineering/DX facets only when applicable.
+  - Implementation-stage reviews include diff evidence, code-smell evidence, test and E2E/plugin verification evidence when applicable.
+  - Every in-scope code smell has a concrete recommendation or an explicit skip/defer rationale.
+  - The next action is exactly one of cc-plan, cc-do, cc-check, cc-act, or no-op.
+reroutes:
+  - when: Plan assumptions, scope, architecture, design, or DX contracts are wrong or incomplete.
+    target: cc-plan
+  - when: Implementation findings require code, test, docs, or UI behavior changes.
+    target: cc-do
+  - when: Deep review is clean and only fresh evidence verification remains.
+    target: cc-check
+recovery_modes:
+  - name: branch-reclassification
+    when: The review started on the wrong branch type or new evidence shows both plan and implementation need review.
+    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 SKILL.md, reload only the branch-specific reference and review-methods.md, then continue with the smallest applicable checklist.
+tool_budget:
+  read_files: 12
+  search_steps: 8
+  shell_commands: 10
+---
+
+# CC-Review
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、公开分发配置和相关文档，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-review` 是可选的深度 Review 节点。
+
+它不替代 `cc-check`。`cc-check` 负责流程式证据验收和 pass/fail/blocked 裁决；`cc-review` 负责在复杂需求、复杂 bug、架构风险、UI/DX 风险、代码坏味道出现时做更深的多轮审查。
+
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，`review/cc-review-report.md` 和 `review/cc-review-findings.json` 中新增的人类可读摘要必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的 Review 边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
+## Iron Law
+
+```text
+REVIEW THE RIGHT THING AT THE RIGHT STAGE.
+```
+
+计划还没进入实现时，Review 计划。代码已经改了时，Review diff 和运行效果。两者都有时，先 Review 计划合同，再 Review 实现是否兑现合同。
+
+## Read First
+
+1. `PLAYBOOK.md`
+2. `CHANGELOG.md`
+3. `references/review-methods.md`
+4. Branch-specific reference:
+   - plan-stage: `references/plan-review-branch.md`
+   - implementation-stage: `references/implementation-review-branch.md`
+   - UI/runtime/plugin evidence: `references/e2e-and-plugin-verification.md`
+
+## Use This Skill When
+
+- 复杂需求或复杂 bug 需要比 `cc-check` 更深的 Review。
+- `cc-plan` 已有方案，但你怀疑范围、根因、架构、测试或 DX 没压实。
+- `cc-do` 已经实现，但你要在进入 `cc-check` 前找设计坏味道、代码坏味道和端到端落地风险。
+- 需要检查僵化、冗余、循环依赖、脆弱性、晦涩性、数据泥团、不必要复杂。
+- UI 或 Codex 插件链路需要用浏览器、电脑操作、日志和点击验证证明实际效果。
+
+不要把每个小改动都送进 `cc-review`。简单、低风险、证据充分的变更直接走 `cc-check`。
+
+## Branch Classifier
+
+先分类，再加载详细方法：
+
+| Branch | Signal | Load |
+| --- | --- | --- |
+| `plan` | 用户说“先别写代码”、只有 `planning/design.md` / `planning/analysis.md`，或没有实现 diff | `plan-review-branch.md` |
+| `implementation` | 当前分支已有代码 diff、review comment、UI 改动、测试改动或用户说“Review 代码” | `implementation-review-branch.md` |
+| `mixed` | 计划和实现都存在，且实现可能偏离计划 | 先 plan，再 implementation |
+
+如果分类不清，先读 change artifacts 和 diff。仍然不清时，用一个 Decision Question 问用户，不要猜。
+
+## Harness Contract
+
+- Allowed actions: read artifacts, inspect code and diff, run safe read-only or verification commands, use Browser/Computer Use for behavior proof, write review reports.
+- Forbidden actions: silently rewriting the plan, silently editing production code, turning optional review into mandatory ship gate, or reviewing unrelated historical debt.
+- Required evidence: every finding must cite plan text, code path, diff line, command output, browser action, UI state, log line, or explicit missing evidence.
+- Reroute rule: plan contract defects return to `cc-plan`; implementation defects return to `cc-do`; clean deep review proceeds to `cc-check`.
+
+## Output Contract
+
+Write `review/cc-review-report.md` with:
+
+1. Review branch classification and scope.
+2. Source artifacts read.
+3. Review methods used and methods intentionally skipped.
+4. Findings by severity, each with evidence, smell category when relevant, recommendation, and route.
+5. E2E / Browser / Computer Use evidence when applicable.
+6. Decision questions still needing user input.
+7. Final next action.
+
+Write `review/cc-review-findings.json` when findings need machine consumption by later agents.
+
+## Finding Rules
+
+Each finding must include:
+
+- severity: `critical` / `important` / `advisory`
+- confidence: 1-10
+- scope: why this is inside the current requirement blast radius
+- evidence: concrete path, line, artifact, command, browser action, or log
+- smell: one of `rigidity`, `duplication`, `cycle`, `fragility`, `obscurity`, `data-clump`, `unnecessary-complexity`, or `none`
+- recommendation: exact next move
+- route: `cc-plan`, `cc-do`, `cc-check`, `cc-act`, or `no-op`
+
+Bad smells inside the requested scope are never hidden. Every in-scope smell must produce either a decision question, a routed fix recommendation, or an explicit defer/skip rationale. Ask whether to optimize when the smell is real and the fix is not a purely mechanical local cleanup.
+
+## Progressive Disclosure
+
+Do not load every reference by default.
+
+1. Always read `review-methods.md`.
+2. Read `plan-review-branch.md` only for plan or mixed reviews.
+3. Read `implementation-review-branch.md` only for implementation or mixed reviews.
+4. Read `e2e-and-plugin-verification.md` only when UI, browser behavior, desktop app behavior, CLI runtime, or Codex plugin chain evidence is relevant.
+
+## Exit Rule
+
+`cc-review` is complete only when the next route is unambiguous:
+
+- `cc-plan`: revise design, scope, root cause, UI/DX contract, or task split.
+- `cc-do`: fix implementation, tests, docs, UI behavior, logs, or review findings.
+- `cc-check`: deep review is clean enough for evidence verification.
+- `cc-act`: only when a fresh `cc-check` pass already exists.
+- `no-op`: review found no relevant issue and no downstream action is needed.

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

@@ -0,0 +1,81 @@
+# E2E and Plugin Verification
+
+Use this reference when implementation review touches UI, browser behavior, desktop app behavior, local app flows, CLI runtime, logs, or Codex plugin interactions.
+
+## Applicability
+
+Run this pass when any of these are true:
+
+- frontend/UI files changed
+- user-visible interaction changed
+- route, API, or CLI output changed
+- background job or log-based progress changed
+- user asked to use Browser, Computer Use, or Codex plugins
+- plan claims UI and implementation are consistent
+
+Skip with reason for backend-only, docs-only, or pure planning reviews.
+
+## Evidence Chain
+
+1. Identify the user path:
+   - page, route, command, app screen, or plugin operation
+   - expected visible result
+   - logs or artifacts that prove backend behavior
+2. Start the smallest safe runtime:
+   - use repo scripts when available
+   - avoid production spend unless explicitly required
+   - record blocked env vars or missing services
+3. Use the right tool:
+   - Browser plugin for local web targets and screenshots
+   - Computer Use plugin for native desktop apps or real app UI
+   - shell/CLI for commands and logs
+4. Click or run every affected primary action.
+5. Check:
+   - visible result
+   - console/errors/logs
+   - persisted artifact or backend state
+   - empty/error/loading states when applicable
+
+## UI Verification Checklist
+
+For each changed flow:
+
+```text
+FLOW
+├── page opened
+├── primary action clicked
+├── expected UI state observed
+├── error/empty/loading state checked or explicitly skipped
+├── console/log checked
+└── backend artifact/log checked when relevant
+```
+
+## Plugin Verification Checklist
+
+When Codex plugins are part of the expected path:
+
+- confirm the plugin exists in the current environment
+- use Browser for localhost/file targets instead of shell-only inspection
+- use Computer Use for desktop app interactions
+- record if plugin access is unavailable and what verification replaced it
+- never claim end-to-end UI proof from code inspection alone
+
+## Report Format
+
+Add an E2E section to `cc-review-report.md`:
+
+```markdown
+## E2E / Plugin Evidence
+
+| Flow | Tool | Evidence | Result |
+| --- | --- | --- | --- |
+| ... | Browser / Computer Use / CLI | screenshot, log, command, artifact | pass / fail / blocked |
+```
+
+If blocked, include:
+
+- missing dependency
+- command attempted
+- exact error or missing tool
+- fallback evidence
+- whether this blocks `cc-check`

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

@@ -0,0 +1,115 @@
+# Implementation Review Branch
+
+Use this reference when the review target is code, tests, docs, UI behavior, or a current branch diff.
+
+## Intake
+
+Read, in order:
+
+1. current branch and base branch
+2. `git diff <base>...HEAD --stat`
+3. full diff for changed files
+4. `planning/design.md` or `planning/analysis.md`
+5. `planning/tasks.md` and `planning/task-manifest.json`
+6. changed code plus direct importers/callers for enum, state, API, and behavior changes
+
+If no plan exists, infer intent from user request, commits, TODOs, and PR body if present. Mark intent confidence.
+
+## Scope Check
+
+Produce:
+
+```text
+Scope Check: CLEAN | DRIFT DETECTED | REQUIREMENTS MISSING
+Intent: ...
+Delivered: ...
+Diff surface: ...
+```
+
+Out-of-scope files are findings only when they change behavior or expand blast radius.
+
+## Diff Review Passes
+
+### 1. Contract Fidelity
+
+Check whether implementation matches the frozen plan or investigation:
+
+- required tasks done
+- rejected scope not implemented
+- root cause still true
+- expected spec delta honored
+- behavior visible at public seam
+
+### 2. Code Smell Scan
+
+Use `review-methods.md` smell taxonomy.
+
+Look for:
+
+- copy-paste helper logic
+- broad catch-all errors
+- parameter clumps
+- shallow pass-through modules
+- internal mocks driving production design
+- new branch forests where a data shape would collapse cases
+- hidden state or multiple truth sources
+- cycles between modules
+
+### 3. Structural Risk
+
+Check:
+
+- security and trust boundaries
+- enum/value completeness outside the diff
+- migrations and rollback
+- concurrency and double-submit
+- external service failures
+- logs/metrics for new paths
+
+### 4. Test Quality
+
+Build a coverage map:
+
+```text
+CODE PATHS                         USER/RUNTIME FLOWS
+file.ts                            feature flow
+├── [tested] happy                 ├── [tested] main path
+├── [gap] empty                    ├── [gap] double action
+└── [gap] upstream error           └── [gap] navigate away / timeout
+```
+
+Flag:
+
+- no regression test for changed behavior
+- tests only assert implementation shape
+- tests mock internal modules instead of public seam
+- fixture lies with missing fields or type casts
+- no UI/E2E proof for user-visible change
+
+### 5. Documentation and DX
+
+If changed behavior affects README, guides, CLI help, package install, public API, agent skill usage, or examples, check whether docs changed too.
+
+## Fix Policy
+
+`cc-review` does not silently edit code. It writes findings and routes:
+
+- mechanical local issue -> `cc-do` with direct fix recommendation
+- architecture/contract issue -> `cc-plan`
+- clean implementation -> `cc-check`
+
+If the user explicitly asks to fix findings in the same turn, switch to `cc-do` behavior after writing the review report.
+
+## Output Requirements
+
+Add to `cc-review-report.md`:
+
+- base branch and diff summary
+- scope check
+- code smell findings
+- structural findings
+- test and E2E coverage map
+- docs/DX notes
+- final route
+
+Write `cc-review-findings.json` when there are actionable findings.