cc-devflow 4.5.5 → 4.5.7

package/.claude/skills/cc-plan/assets/TASK_MANIFEST_TEMPLATE.json

@@ -8,7 +8,7 @@
   "sourceRoadmap": {
     "itemId": "RM-001",
     "roadmapVersion": "1.0",
-    "roadmapSkillVersion": "2.1.0",
+    "roadmapSkillVersion": "5.2.0",
     "syncStatus": "pending",
     "syncCommand": ".claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh --rm RM-001 --status Planned --req REQ-XXX --progress 0%",
     "updatedFiles": [
@@ -28,7 +28,7 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.5",
+    "reqPlanSkillVersion": "3.8.1",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T12:00:00.000Z",
     "approvedBy": "user",
@@ -52,6 +52,27 @@
       "outOfScope": [],
       "furtherNotes": []
     },
+    "aiLeverageDecisionLens": {
+      "realUserOrOperator": "",
+      "statusQuoWorkaround": "",
+      "humanTeamEffortForFullScope": "",
+      "ccAgentEffortForFullScope": "",
+      "aiCompressionRatio": "",
+      "completeLakeBoundary": "",
+      "oceanBoundary": "",
+      "scopeRecommendation": "sharp-wedge",
+      "costModel": {
+        "agentTime": "",
+        "humanReviewTime": "",
+        "verificationCost": "",
+        "maintenanceCost": "",
+        "failureCost": "",
+        "reversibility": ""
+      },
+      "verdict": "sharp-wedge",
+      "missingEvidenceOrPivotReason": "",
+      "impactOnApprovedDirection": ""
+    },
     "ambiguityGate": {
       "whatScore": 0,
       "whyScore": 0,
@@ -66,7 +87,49 @@
       "repeatedConcernFingerprints": [],
       "stallReason": "",
       "rerouteIfStalled": "ask-user"
-    }
+    },
+    "externalBestPractice": {
+      "needed": false,
+      "decisionStatus": "not-needed",
+      "decisionQuestionId": "",
+      "privacyGuard": "generalized terms only; no project names, private requirements, customer names, secrets, logs, or proprietary concepts",
+      "generalizedSearchTerms": [],
+      "sourcesChecked": [],
+      "conventionalWisdom": "",
+      "currentDiscourse": "",
+      "repoFitVerdict": "skipped",
+      "designImpacts": [],
+      "skippedReason": "repo evidence is sufficient for this plan"
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": [],
+        "recommendation": "Option A",
+        "options": [
+          {
+            "id": "A",
+            "label": "Minimal viable",
+            "recommended": true,
+            "completeness": "7/10",
+            "good": "",
+            "costRisk": ""
+          },
+          {
+            "id": "B",
+            "label": "Ideal architecture",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "",
+            "costRisk": ""
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do follows the approved implementation surface and task split",
+        "status": "answered"
+      }
+    ]
   },
   "sourceEvidence": [
     {

package/.claude/skills/cc-plan/assets/TINY_DESIGN_TEMPLATE.md

@@ -48,6 +48,34 @@
 - Competing:
 - Unresolved blockers:
 
+## AI Leverage Decision Lens
+
+- Real user / operator:
+- Status quo workaround:
+- Human-team effort for full scope:
+- CC / agent effort for full scope:
+- AI compression ratio:
+- Complete-lake boundary:
+- Ocean boundary:
+- Scope recommendation: `boil-lake` | `sharp-wedge`
+- Cost model:
+- Verdict: `boil-lake` | `sharp-wedge` | `needs-evidence` | `pivot`
+- Missing evidence or pivot reason:
+
+## External Best-Practice Validation
+
+- Needed: Yes / No
+- Decision status: not-needed / ask-user / approved / declined / search-unavailable
+- Decision question:
+- Privacy guard: generalized terms only; no project names, private requirements, customer names, secrets, logs, or proprietary concepts
+- Generalized search terms:
+- Sources checked:
+- Conventional wisdom:
+- Current discourse:
+- Repo-fit verdict: confirmed / adjusted / contradicted / skipped
+- Changes to frozen design:
+- Skipped reason:
+
 ## Capability Handoff
 
 - Canonical capability spec:
@@ -177,9 +205,12 @@
 - Green minimality / refactor candidate scan:
 - PRD brief scan:
 - Source trust boundary scan:
+- AI Leverage Decision Lens scan:
+- External best-practice scan:
 - External conflict scan:
 - Ambiguity gate:
 - Review loop status:
+- Decision question scan:
 - Test-first readiness:
 - Review calibration:
 - Final recommendation:
@@ -192,6 +223,12 @@
 - Stall reason:
 - Reroute if stalled:
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | planning-mode / ambiguity-blocker / approach-approval / taste-or-user-challenge / final-design-approval |  |  |  |  | asked / answered / auto-decided |
+
 ## Approval
 
 - User approval status:

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` 是独立编号空间，只在同前缀内递增，跨前缀同号允许共存。
+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,9 +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`。
+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
 
@@ -73,6 +78,21 @@
 不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
 也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
 
+## Decision Question Fields
+
+每个需要用户判断的 gate 至少记录：
+
+- questionId：`D1` / `D2` / ...
+- gate：`planning-mode` / `ambiguity-blocker` / `external-best-practice` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
+- knownEvidence
+- recommendation
+- options：只能使用 `A` / `B` / `C` 作为 option id
+- userChoice
+- impact
+- status：`asked` / `answered` / `auto-decided`
+
+如果选项不是覆盖度差异，completeness 使用 `different-kind`，并写清不能打分的原因。
+
 ## Review Gate
 
 `planning/design.md` 至少完成：
@@ -95,12 +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. 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`