cc-devflow 4.5.6 → 4.5.8

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

@@ -0,0 +1,152 @@
+# 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
+
+Turn these passes into review nodes before reporting findings. Every changed file, public behavior, test surface, documentation surface, and UI/runtime flow must belong to a node or have a skip reason.
+
+For complex diffs, assign independent read-only reviewers by facet: contract, smell, test, docs/DX, and runtime. Keep reviewer outputs separate until the main thread validates evidence and merges duplicates.
+
+For broad or PR-landing diffs, prefer the risk-lane review swarm profile from `review-methods.md` before reporting findings:
+
+1. Intent and regression
+2. Security and privacy
+3. Performance and reliability
+4. Contracts and coverage
+
+The lanes may map onto the passes below, but they should stay separate in `cc-review-plan.md` and raw reviewer output when separate reviewers are used.
+
+### 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.
+
+If this pass finds duplication, over-complexity, awkward abstraction, branch forests, unclear ownership, or broad architecture cleanup risk, load `cc-simplify` and record it as a selected tool in `cc-review-plan.md`.
+
+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.
+
+## Delta Node Selection
+
+Use git and prior review records:
+
+1. Find changed files with `git diff <base>...HEAD --name-only`.
+2. If prior `cc-review-ledger.jsonl` records a reviewed SHA, narrow to `git diff <reviewedSha>...HEAD`.
+3. Group changed files by behavior surface, not just extension.
+4. Add dependent nodes for direct importers/callers when a shared helper, enum, state shape, API contract, or skill contract changes.
+5. Preserve prior clean nodes only when the target file and dependent contract did not change.
+
+Example:
+
+```text
+R101 implementation.contract.skill-frontmatter
+R102 implementation.smell.review-state
+R103 implementation.tests.distribution
+R104 implementation.docs.workflow-map
+```
+
+## 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
+- implementation review nodes checked, skipped, or blocked
+- implementation reviewer agents used or fallback reason
+- risk-lane coverage and raw finding triage
+- 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.

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

@@ -0,0 +1,151 @@
+# Plan Review Branch
+
+Use this reference when the review target is a plan, investigation handoff, or mixed branch whose plan contract may be wrong.
+
+## Intake
+
+Read, in order:
+
+1. `planning/design.md` or `planning/analysis.md`
+2. `planning/tasks.md`
+3. `planning/task-manifest.json`
+4. `change-meta.json`
+5. related roadmap/spec/docs/code referenced by the plan
+
+If no change directory exists, review the user-provided plan text and clearly mark missing durable artifacts.
+
+## Review Shape
+
+First select applicable facets, then create one or more review nodes for each selected facet. Do not load every facet when the plan is small, but do not skip a selected facet merely to keep the answer short.
+
+For complex plans, assign selected facets to independent read-only reviewers when subagent support is available. Strategy, engineering, design, DX, and TOC reviewers should not share intermediate conclusions; the main thread merges their findings after each reviewer returns.
+
+### 1. Strategy Facet
+
+Use a native strategy review question set:
+
+- Is this the right problem?
+- Is the stated user/business outcome direct or a proxy?
+- What happens if we do nothing?
+- What does the 12-month ideal look like?
+- What existing code or workflow already solves part of this?
+
+Output:
+
+```text
+CURRENT -> THIS PLAN -> 12-MONTH IDEAL
+```
+
+Node examples:
+
+- `plan.strategy.problem-fit`
+- `plan.strategy.outcome-signal`
+- `plan.strategy.do-nothing-risk`
+
+### 2. Engineering Facet
+
+Review:
+
+- component boundaries
+- data flow and shadow paths
+- state transitions
+- security boundaries
+- rollback shape
+- testability seam
+- parallelization risk
+
+Required diagram for non-trivial plans:
+
+```text
+Entry -> validate -> transform -> persist -> output
+  |        |            |            |          |
+ nil     invalid      exception    conflict   stale
+ empty   wrong type   timeout      duplicate  partial
+```
+
+Node examples:
+
+- `plan.engineering.boundaries`
+- `plan.engineering.data-flow`
+- `plan.engineering.state-transitions`
+- `plan.engineering.testability`
+
+### 3. Design Facet
+
+Run only for user-facing UI or interaction flows.
+
+Check:
+
+- first, second, third thing the user sees
+- loading / empty / error / success / partial states
+- responsive and accessibility intent
+- generic UI or AI slop risk
+- whether live design review will be needed after implementation
+
+Node examples:
+
+- `plan.design.primary-flow`
+- `plan.design.states`
+- `plan.design.responsive-accessibility`
+
+### 4. DX Facet
+
+Run only for API, CLI, SDK, package, docs, agent skill, MCP, or developer/operator surfaces.
+
+Check:
+
+- target developer/operator persona
+- time to first value
+- install/run/debug/upgrade path
+- actionable errors: problem + cause + fix
+- copy-paste examples and escape hatches
+
+Node examples:
+
+- `plan.dx.first-value`
+- `plan.dx.errors`
+- `plan.dx.examples`
+
+## TOC Root-Cause Pass
+
+For complex bugs, use:
+
+1. Current reality tree: symptoms, causes, enabling conditions.
+2. Conflict diagram: why the obvious fix conflicts with a real need.
+3. Future reality tree: what the proposed fix changes and what it may break.
+
+If the root cause is not proven, reroute to `cc-investigate`, not `cc-do`.
+
+Record each TOC pass as a separate node so the review can resume:
+
+- current reality tree
+- conflict diagram
+- future reality tree
+
+## Code Smell Pass In Planning
+
+Plans can contain smells before code exists:
+
+- repeated implementation steps with slight variations
+- parallel data sources
+- task split by technical layer instead of behavior
+- fake abstraction or one-adapter seam
+- missing owner for shared state
+- hand-wavy "handle edge cases" or "add validation"
+
+Each planning smell must become a plan finding and route to `cc-plan`.
+
+## Output Requirements
+
+Add to `cc-review-report.md`:
+
+- plan review nodes checked, skipped, or blocked
+- plan reviewer agents used or fallback reason
+- plan artifacts read
+- strategy/engineering/design/DX facets used
+- diagrams produced
+- in-scope bad smells
+- decisions needed
+- reroute recommendation
+
+If any plan facet changes the task list or implementation contract, route to `cc-plan`.

package/.claude/skills/cc-review/references/review-methods.md

@@ -0,0 +1,221 @@
+# CC-Review Methods
+
+Use this reference for every `cc-review` run. It defines the shared method library. Load branch-specific references for concrete workflow steps.
+
+## Method Selection
+
+Select every method needed by the current risk and write the selected methods into `cc-review-plan.md`. This table is a routing map, not a cap.
+
+| Risk | Method |
+| --- | --- |
+| unclear goal | goal tree |
+| repeated symptom | current reality tree |
+| hidden tradeoff | conflict diagram |
+| uncertain fix impact | future reality tree |
+| implementation complexity | logic tree and smell scan |
+| UI/runtime mismatch | E2E/plugin verification |
+| code quality or simplification risk | cc-simplify reference plus smell scan |
+| broad implementation diff | risk-lane review swarm profile |
+
+## Review Plan Nodes
+
+Before findings, create ordered nodes:
+
+```text
+R001 plan.strategy.outcome
+  target: planning/design.md
+  method: goal tree
+  check: outcome and scope consistency
+  status: pending
+
+R002 plan.engineering.data-flow
+  target: planning/design.md + referenced code
+  method: engineering facet
+  check: single truth source and state transitions
+  status: pending
+```
+
+Node rules:
+
+- one node reviews one coherent question, artifact, or changed surface
+- every selected method creates at least one node
+- every changed file or user-facing surface is assigned to a node or explicitly skipped
+- every node has an owner: `main` or a named read-only reviewer
+- every node ends as `checked`, `skipped`, or `blocked`
+- no finding limit exists while nodes remain pending
+- when a prior ledger exists, reuse checked nodes only if their target and dependencies did not change
+
+## Independent Reviewer Assignment
+
+Use subagents to preserve independent context when the host supports them.
+
+Assignment rules:
+
+- Assign independent reviewers by facet, not by random file chunks.
+- Keep each reviewer packet self-contained: scope, delta, node ids, required artifacts, reference to use, and output schema.
+- Do not ask one reviewer to wait for another reviewer result unless the dependency is explicit in `cc-review-plan.md`.
+- Do not assign two reviewers to the same node unless a critical finding needs a second opinion.
+- Main thread validates reviewer evidence before final findings.
+
+Reviewer result states:
+
+```text
+accepted   -> finding has concrete in-scope evidence
+merged     -> duplicate finding folded into stronger finding
+downgraded -> real note but not blocking or confidence too low
+rejected   -> out-of-scope, stale, speculative, or contradicted by evidence
+```
+
+Record these states in `cc-review-report.md` and preserve raw reviewer output in `cc-review-agent-results.jsonl`.
+
+## Risk-Lane Review Swarm Profile
+
+Use this profile when a broad implementation diff, PR landing review, or mixed review benefits from independent read-only context. The profile is a default decomposition, not a requirement to manufacture findings.
+
+| Lane | Reviewer question |
+| --- | --- |
+| intent-regression | Does the diff match the intended behavior without extra behavior drift, broken edge cases, fallback loss, or caller/callee contract drift? |
+| security-privacy | Did the diff weaken auth, validation, secret handling, sensitive data boundaries, defaults, or trust of external input? |
+| performance-reliability | Did the diff add duplicate work, hot-path cost, missing cleanup, retry storms, ordering races, or brittle failure handling? |
+| contracts-coverage | Did the diff miss API/schema/type/config/flag alignment, migration fallout, regression tests, logs, metrics, assertions, or error paths? |
+
+Small diffs may use one combined reviewer that covers all lanes. Large or multi-surface diffs should assign separate reviewers for the highest-risk lanes when the host supports subagents.
+
+The main thread owns aggregation:
+
+- Merge duplicate findings under the clearest evidence.
+- Reject style preferences, nits, and speculative concerns with no concrete impact.
+- Downgrade low-confidence notes unless they point to critical impact.
+- Convert intent-unclear claims into decision questions instead of findings.
+- Order final findings by severity, confidence, and current-scope impact.
+
+## Stateful Delta Review
+
+Use git and prior records to avoid repeating stale work:
+
+1. Find the previous reviewed SHA from `cc-review-ledger.jsonl` or `cc-review-report.md`.
+2. Compare `git diff <previous-sha>...HEAD` when possible.
+3. If no previous SHA exists, compare against the base branch or reviewed artifact timestamps.
+4. Re-review changed nodes and dependent nodes.
+5. Preserve previous clean nodes only when their target content and assumptions are unchanged.
+
+If git cannot identify the delta, mark the delta source as `unknown` and review the full in-scope surface.
+
+## Thinking Tools
+
+### Goal Tree
+
+Use when the plan has too many proposed actions and not enough outcome clarity.
+
+```text
+GOAL
+├── necessary condition A
+│   ├── measurable signal
+│   └── blocked by
+├── necessary condition B
+└── NOT IN SCOPE
+```
+
+### Current Reality Tree
+
+Use for bugs and recurring failures.
+
+```text
+SYMPTOM
+├── direct cause
+│   └── deeper cause
+├── enabling condition
+└── missing control
+```
+
+### Conflict Diagram
+
+Use when two requirements appear incompatible.
+
+```text
+Objective
+├── Need A -> Want X
+└── Need B -> Want not-X
+Assumption to break: ...
+```
+
+### Future Reality Tree
+
+Use before recommending a non-trivial redesign.
+
+```text
+CHANGE
+├── desired effect
+├── possible negative branch
+│   └── prevention
+└── verification signal
+```
+
+### Logic Tree
+
+Use for implementation reviews.
+
+```text
+Entry point
+├── path A
+│   ├── happy
+│   ├── empty
+│   └── error
+└── path B
+```
+
+## Code Smell Taxonomy
+
+Only report smells inside the current requirement blast radius or smells made worse by the current work.
+
+| Smell | Review question | Preferred fix shape |
+| --- | --- | --- |
+| rigidity | Does a small change force unrelated edits? | move decision to one owner |
+| duplication | Is the same logic repeated with small variations? | reuse existing helper or make one narrow helper |
+| cycle | Do modules know each other's internals? | invert dependency or extract boundary |
+| fragility | Can one change break unrelated behavior? | isolate side effects and add focused tests |
+| obscurity | Is intent hidden behind clever names or control flow? | rename, split, or make data shape explicit |
+| data-clump | Do fields always travel together? | group them into one object/value |
+| unnecessary-complexity | Is abstraction solving a hypothetical future? | delete seam or collapse to direct code |
+
+## Severity
+
+- `critical`: ships wrong behavior, data/security risk, silent failure, broken root cause, or impossible verification.
+- `important`: likely maintenance, test, UX, DX, performance, or operability problem in current scope.
+- `advisory`: good improvement but not required for this change.
+
+## Confidence
+
+- `9-10`: directly verified in code, artifact, command output, UI run, or log.
+- `7-8`: strong evidence from nearby patterns and diff.
+- `5-6`: plausible but needs confirmation; mark as verify-first.
+- `<5`: do not put in main findings unless critical impact.
+
+## Decision Questions
+
+Ask only when a finding requires user judgment. Do not stop the whole review at the first decision unless that answer blocks the next review node.
+
+Use:
+
+```text
+D<N> - <decision title>
+Evidence: <concrete artifact/path/line/log/UI action>
+Risk: <what breaks if ignored>
+Recommendation: A because <principle>
+Options:
+A) <fix now> (recommended) - impact
+B) <defer> - impact
+C) <skip> - impact
+STOP: wait for the user answer before continuing.
+```
+
+After the node pass, present a decision queue:
+
+```text
+Decision Queue
+├── D1 scope or architecture decision
+├── D2 user-visible behavior decision
+└── D3 test strategy decision
+```
+
+Then ask decisions one by one. Do not batch unrelated issues inside one decision.

package/.claude/skills/cc-review/scripts/collect-review-context.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 收集 cc-review 的增量上下文
+# ------------------------------------------------------------
+
+change_dir="${1:-}"
+base_ref="${2:-origin/main}"
+
+if [[ -z "$change_dir" ]]; then
+  echo "Usage: collect-review-context.sh <change-dir> [base-ref]" >&2
+  exit 2
+fi
+
+review_dir="$change_dir/review"
+ledger="$review_dir/cc-review-ledger.jsonl"
+report="$review_dir/cc-review-report.md"
+plan="$review_dir/cc-review-plan.md"
+findings="$review_dir/cc-review-findings.json"
+
+head_sha="$(git rev-parse HEAD)"
+base_sha=""
+if git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
+  base_sha="$(git merge-base "$base_ref" HEAD)"
+fi
+
+reviewed_sha=""
+if [[ -f "$ledger" ]]; then
+  reviewed_sha="$(
+    sed -n 's/.*"headSha"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ledger" |
+      tail -n 1
+  )"
+fi
+
+if [[ -z "$reviewed_sha" && -f "$report" ]]; then
+  reviewed_sha="$(
+    sed -n 's/.*Reviewed head SHA:[[:space:]]*`\?\([0-9a-f]\{7,40\}\)`\?.*/\1/p' "$report" |
+      tail -n 1
+  )"
+fi
+
+diff_base="$base_sha"
+if [[ -n "$reviewed_sha" ]] && git rev-parse --verify "$reviewed_sha^{commit}" >/dev/null 2>&1; then
+  diff_base="$reviewed_sha"
+fi
+
+echo "CC_REVIEW_CONTEXT"
+echo "change_dir=$change_dir"
+echo "review_dir=$review_dir"
+echo "base_ref=$base_ref"
+echo "base_sha=${base_sha:-unknown}"
+echo "reviewed_sha=${reviewed_sha:-none}"
+echo "head_sha=$head_sha"
+echo "diff_base=${diff_base:-unknown}"
+
+echo
+echo "PRIOR_REVIEW_FILES"
+for file in "$plan" "$report" "$ledger" "$findings"; do
+  if [[ -f "$file" ]]; then
+    printf 'present %s\n' "$file"
+  else
+    printf 'missing %s\n' "$file"
+  fi
+done
+
+echo
+echo "CHANGED_FILES"
+if [[ -n "$diff_base" ]]; then
+  git diff --name-status "$diff_base...HEAD"
+else
+  git diff --name-status HEAD
+fi
+
+if [[ -f "$ledger" ]]; then
+  echo
+  echo "RECENT_LEDGER"
+  tail -n 20 "$ledger"
+fi

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

@@ -1,5 +1,11 @@
 # Roadmap Skill Changelog
 
+## v5.2.0 - 2026-05-09
+
+- add project-direction routing and brand-neutral founder guardrails
+- add the AI Leverage Route Lens so roadmap recommendations must name the real user/operator, current workaround, human-vs-agent effort, complete-lake boundary, ocean boundary, first success signal, kill signal, and boil-lake/sharp-wedge/needs-evidence/pivot verdict
+- update roadmap and tracking templates so AI-era scope choices can choose complete same-blast-radius lakes instead of timid MVP slices
+
 ## v5.0.0 - 2026-05-01
 
 - replace the roadmap/backlog/tracking split with `devflow/roadmap.json` as the single editable roadmap state