cc-devflow 4.5.7 → 4.5.8

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` 自身不偷偷改代码。