cc-devflow 4.5.12 → 4.5.14

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

@@ -1,13 +1,166 @@
 # Review Methods
 
-Pick only the methods that match the current risk:
+Use this reference for every `cc-review` run. It defines the method library. Load branch-specific references for concrete workflow steps.
 
-- diff review
-- test-quality review
-- security review
-- performance review
-- API contract review
-- UI/browser review
-- documentation/PR body review
+## Method Selection
 
-Each finding needs evidence, impact, recommendation, and route. Do not write process files.
+Pick every method needed by the current risk. This is a routing map, not a finding 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 |
+
+Selected methods stay in scratch reasoning and final response/task updates. Do not write process files.
+
+## Review Nodes
+
+Before findings, mentally create ordered review nodes:
+
+```text
+R001 plan.strategy.outcome
+  target: task.md
+  method: goal tree
+  check: outcome and scope consistency
+
+R101 implementation.contract.public-seam
+  target: changed code + tests
+  method: contract fidelity
+  check: public behavior matches task.md
+```
+
+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 ends as `checked`, `skipped`, or `blocked`
+- no finding limit exists while nodes remain unchecked
+- prior clean conclusions can be reused only when Git proves the target and dependencies did not change
+
+## Risk-Lane Review Swarm Profile
+
+Use this profile when a broad implementation diff, PR landing review, or mixed review benefits from independent 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.
+
+## Aggregation
+
+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
+
+Subagent output is evidence input, not verdict.
+
+## 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.
+
+Plan decisions are written to `task.md`. Implementation repair choices stay in the response.

package/.claude/skills/cc-spec-init/PLAYBOOK.md

@@ -14,6 +14,6 @@ Specs record current capability truth. Roadmap records future work. Git records
 
 ## Do Not
 
-- Do not create change-scoped JSON.
+- Do not create extra change-scoped files.
 - Do not store workflow state in specs.
 - Do not turn one requirement's implementation detail into capability truth.

package/.claude/skills/cc-spec-init/SKILL.md

@@ -28,7 +28,7 @@ Allowed outputs:
 - `devflow/specs/INDEX.md`
 - `devflow/specs/capabilities/<capability>.md`
 
-Do not create change-scoped JSON. Changes link to specs through `task.md`, roadmap text, PR text, and Git commits.
+Changes link to specs through `task.md`, roadmap text, PR text, and Git commits.
 
 ## Use This Skill When
 

package/CHANGELOG.md

@@ -9,6 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.14] - 2026-05-14
+
+### Changed
+
+- Removed legacy process JSON and report-card assumptions from the public workflow contracts.
+- Restored the artifact-light `cc-plan` planning dialogue flow inside `task.md` contracts.
+- Restored `cc-investigate` root-cause proof, hypothesis, reroute, and feedback-loop guidance without bringing back separate analysis artifacts.
+- Restored `cc-do` TDD execution discipline and `cc-check` fresh-evidence verification flow while keeping durable truth limited to `task.md`, Git, PR briefs, and postmortems.
+- Restored `cc-review` node-by-node review, risk lanes, finding aggregation, and decision-question flow while routing plan findings into `task.md` and implementation findings through user-selected repair options.
+
+## [4.5.13] - 2026-05-13
+
+### Changed
+
+- Updated `cc-review` so plan and investigation reviews write findings directly into `task.md`.
+- Updated implementation reviews to return repair options and wait for the user's selected fix before editing code.
+- Removed all other local `cc-review` output surfaces.
+
 ## [4.5.12] - 2026-05-13
 
 ### Changed

package/README.md

@@ -95,15 +95,15 @@ flowchart TD
 | --- | --- | --- |
 | `cc-roadmap` | You need product direction, staged scope, or backlog order | `devflow/roadmap.json`, `devflow/ROADMAP.md`, deprecated `devflow/BACKLOG.md` |
 | `cc-next` | You need to pick the next roadmap-aware ready target from roadmap, unarchived local changes, and issue truth | one Goal Packet for `cc-dev` |
-| `cc-dev` | A selected objective should be driven in the current worktree to a remote PR | PDCA/IDCA artifacts plus a PR or handoff |
-| `cc-plan` | A feature or change needs scope, design, and task freezing | `planning/tasks.md#Contract Summary`, `task-manifest.json`, `change-meta.json` |
-| `cc-investigate` | A bug needs symptom, reproduction, root cause, and repair boundary | `planning/tasks.md#Root Cause Contract`, `task-manifest.json`, `change-meta.json` |
-| `cc-do` | Planned or investigated work needs implementation | code, tests, task state, scratch runtime |
-| `cc-review` | Complex plans, investigations, or diffs need optional deep multi-round review before implementation or verification | `review-ledger.jsonl`, optional `review-findings.json`, optional rendered Markdown |
+| `cc-dev` | A selected objective should be driven in the current worktree to a remote PR | `task.md`, Git commits, and a PR or handoff |
+| `cc-plan` | A feature or change needs scope, design, and task freezing | `task.md#Contract Summary` |
+| `cc-investigate` | A bug needs symptom, reproduction, root cause, and repair boundary | `task.md#Root Cause Contract` |
+| `cc-do` | Planned or investigated work needs implementation | code, tests, `task.md` status, Git commit |
+| `cc-review` | Complex plans, investigations, or diffs need optional deep review before implementation or verification | plan findings in `task.md`; implementation findings and repair options in the response |
 | `cc-pr-review` | A remote PR needs an independent review session before landing | PR review packet, findings, and landing verdict |
 | `cc-pr-land` | Reviewed PRs need rebase-first landing into main with parity proof | integrated main plus local/remote parity evidence |
-| `cc-check` | Work needs fresh verification evidence | `report-card.json` |
-| `cc-act` | Verified work needs a PR, local handoff, release note, or closeout | one final handoff file |
+| `cc-check` | Work needs fresh verification evidence | pass/fail/blocked response and Git commit |
+| `cc-act` | Verified work needs a PR, local handoff, or closeout | optional `handoff/pr-brief.md`, Git/PR truth, or incident postmortem |
 
 Maintenance skills are shipped with the pack:
 
@@ -114,19 +114,19 @@ Maintenance skills are shipped with the pack:
 
 `cc-roadmap` now records planning posture, evidence maturity, canonical project language, and durable decision context before recommending a route. That keeps idea-stage, active-user, paying-customer, infrastructure, and recovery work from being forced through the same questions, and prevents roadmap items from inventing a second vocabulary. Developer-facing or operator-facing roadmap items also carry target user, time to first value, magic moment, adoption bottleneck, and domain handoff into `cc-plan`.
 
-Canonical language and durable decisions stay inside cc-devflow-native sources: `devflow/specs/`, `devflow/roadmap.json`, `devflow/ROADMAP.md`, `planning/tasks.md`, and `change-meta.json`. Legacy `planning/design.md` and `planning/analysis.md` remain readable fallback inputs for older changes.
+Canonical language and durable decisions stay inside cc-devflow-native sources: `devflow/specs/`, `devflow/roadmap.json`, `devflow/ROADMAP.md`, `task.md`, Git history, and PR truth. Legacy planning artifacts are readable fallback inputs only.
 
 `cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, public test seams, spec-style test names, public verification paths, behavior assertions, mock boundaries, coverage quality, mandatory regression tests, interface depth, Green minimality guards, refactor candidates, and vertical tracer-bullet slices when existing behavior changes. Before handoff, `cc-plan` and `cc-investigate` also reconcile the source roadmap item so RM status, REQ/FIX binding, progress, and spec diagnosis do not drift from the frozen change artifacts.
 
-Every post-planning stage can start from `cc-devflow query workflow-context --change <id> --change-key <key> --data-only --no-trace --compact`. Treat the result as a context index, not semantic compression: it routes the next stage, names the current task, carries source hashes, `mustNotForget` constraints, default section/JSON refs, trusted commands, fail-closed rules, and machine-readable deep-open conditions. Source artifacts still decide disputed facts. This primarily reduces stage-routing and context-reset reads; end-to-end PDCA/IDCA savings depend on how often agents open `defaultOpen` and `deepOpen` refs. Use `npm run benchmark:workflow-context` to inspect token estimates plus routing correctness over the checked-in and synthetic examples. Use `npm run benchmark:skills` to keep public skill entrypoints thin; deeper planning rules should live behind conditional references instead of default context.
+Every post-planning stage can start from `cc-devflow query workflow-context --change <id> --change-key <key> --data-only --no-trace --compact`. Treat the result as a context index, not semantic compression: it routes the next stage from `task.md`, Git history, and PR/handoff truth. Source artifacts still decide disputed facts. Use `npm run benchmark:skills` to keep public skill entrypoints thin; deeper planning rules should live behind conditional references instead of default context.
 
-`cc-review` is optional and deeper than `cc-check`. It can run immediately after `cc-plan` / `cc-investigate` to review the frozen plan or root-cause contract, or after `cc-do` to review the implementation. It reads prior review records and current git/artifact delta, then records review lifecycle events through `cc-devflow review start`, `record-node`, `add-finding`, and `close` into `review-ledger.jsonl`. Human Markdown reports are rendered on demand with `cc-devflow review render`. When the host supports subagents, selected nodes can be dispatched to independent read-only reviewers so strategy, engineering, design, DX, smell, test, and runtime checks do not share one contaminated context. Broad implementation reviews can use separate risk lanes for intent/regression, security/privacy, performance/reliability, and contracts/coverage before the main thread triages raw findings. Plan reviews borrow strategy/design/engineering/DX methods through progressive references, while implementation reviews inspect diff scope, code smells, tests, UI/runtime behavior, Browser/Computer Use evidence, and logs when applicable. Findings route back to `cc-plan` or `cc-do`; clean implementation reviews continue to `cc-check`.
+`cc-review` is optional and deeper than `cc-check`. It can run immediately after `cc-plan` / `cc-investigate` to review the frozen plan or root-cause contract, or after `cc-do` to review the implementation. Plan and investigation review findings are written directly into `task.md`. Implementation review findings are returned in the response with repair options; the user chooses the repair path before code is edited. PR reviews stay in the response or GitHub review. No local review report, ledger, findings JSON, or other review output file is written.
 
 ## Verification And Ship Gates
 
 `cc-check` now treats QA as a feedback-loop problem, not only a green-test problem. Bugfix and behavior work records the loop used to prove reality, expected versus actual behavior, reproduction steps, test boundary quality, and architecture follow-ups when no clean public test seam exists.
 
-`cc-act` carries that evidence into PR briefs, handoffs, and release notes. It checks source roadmap progress during closeout, updates `devflow/roadmap.json`, and regenerates `devflow/ROADMAP.md` / `devflow/BACKLOG.md` when verified reality changes. Follow-ups must be durable behavior briefs with current behavior, desired behavior, key interfaces, acceptance criteria, and explicit out-of-scope notes before they are written back to roadmap or backlog.
+`cc-act` carries that evidence into PR briefs, handoffs, or incident postmortems when needed. It checks source roadmap progress during closeout, updates `devflow/roadmap.json`, and regenerates `devflow/ROADMAP.md` / `devflow/BACKLOG.md` when verified reality changes. Follow-ups must be durable behavior briefs with current behavior, desired behavior, key interfaces, acceptance criteria, and explicit out-of-scope notes before they are written back to roadmap or backlog.
 
 ## Installation Modes
 
@@ -244,19 +244,18 @@ The currently distributed skill folders are:
 
 - `devflow/specs/` stores durable capability truth: `INDEX.md` plus `capabilities/*.md`.
 - New change directories use `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` numbers advance independently, so the same number may exist in both prefixes. Parallel worktrees may also create repeated numbers; the full change key must use a specific description to distinguish the work.
-- `devflow/changes/<change>/` stores durable change truth: CLI-generated `change-meta.json`, `planning/tasks.md`, CLI-generated `task-manifest.json`, review ledger/findings records, optional CLI logs for debug/failure, `report-card.json`, and one final handoff file. Task `context.md`, `checkpoint.json`, review markdown, and AI-written process files are not default durable truth.
-- New changes default to one human-authored Markdown artifact: `planning/tasks.md`. Feature plans put the frozen design in `## Contract Summary`; bug investigations put root-cause truth in `## Root Cause Contract`. Legacy `planning/design.md`, `planning/analysis.md`, and `cc-review-*.md` remain fallback inputs, not new default writes.
-- Machine JSON is CLI-owned: write the human contract in `planning/tasks.md`, then run `cc-devflow task-contract compile` / `validate`; do not handwrite `task-manifest.json` or `change-meta.json`.
-- Use `cc-devflow task-contract validate`, `npm run verify:artifacts`, `npm run benchmark:artifacts`, and `npm run benchmark:skills` to keep workflow artifacts and skill entrypoints small and measurable.
+- `devflow/changes/<change>/` stores durable change truth in `task.md`, optional `handoff/pr-brief.md`, and Git commits. Real recurring failures may also write incident postmortems under `devflow/postmortems/`.
+- New changes default to one human-authored Markdown artifact: `task.md`. Feature plans put the frozen design in `## Contract Summary`; bug investigations put root-cause truth in `## Root Cause Contract`. Legacy planning and review artifacts are readable fallback inputs only.
+- Workflow state is Git-owned: keep `task.md` current, commit each completed stage/environment, and do not create extra process files.
+- Use `cc-devflow query workflow-context`, `npm run verify:examples`, and `npm run benchmark:skills` to keep workflow truth and skill entrypoints small and measurable.
 - `devflow/workspaces/<change>/` stores ephemeral runtime scratch such as worker assignment, journals, prompts, and session logs.
 - Regenerable files should not be persisted under `devflow/changes/`.
 
 Artifact contract quick checks:
 
 ```bash
-npx cc-devflow task-contract validate --change REQ-001 --change-key REQ-001-copy-invite-link
-npm run verify:artifacts
-npm run benchmark:artifacts
+npx cc-devflow query workflow-context --change REQ-001 --change-key REQ-001-copy-invite-link --data-only --no-trace --compact
+npm run verify:examples
 npm run benchmark:skills
 ```
 

package/README.zh-CN.md

@@ -95,15 +95,15 @@ flowchart TD
 | --- | --- | --- |
 | `cc-roadmap` | 需要产品方向、阶段范围或 backlog 顺序 | `devflow/roadmap.json`、`devflow/ROADMAP.md`、deprecated `devflow/BACKLOG.md` |
 | `cc-next` | 需要从 roadmap、未归档本地 change 和 issue truth 里选下一个 ready 目标 | 交给 `cc-dev` 的 Goal Packet |
-| `cc-dev` | 已选目标要在当前 worktree 内自动推进到远程 PR | PDCA/IDCA 产物加 PR 或 handoff |
-| `cc-plan` | 新功能或变更需要澄清范围、设计方案、冻结任务 | `planning/tasks.md#Contract Summary`、`task-manifest.json`、`change-meta.json` |
-| `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `planning/tasks.md#Root Cause Contract`、`task-manifest.json`、`change-meta.json` |
-| `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、任务状态、scratch runtime |
-| `cc-review` | 复杂方案、调查根因或 diff 需要在实现前或验证前做可选深度多轮 Review | `review-ledger.jsonl`，可选 `review-findings.json`，可按需渲染 Markdown |
+| `cc-dev` | 已选目标要在当前 worktree 内自动推进到远程 PR | `task.md`、Git commit、PR 或 handoff |
+| `cc-plan` | 新功能或变更需要澄清范围、设计方案、冻结任务 | `task.md#Contract Summary` |
+| `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `task.md#Root Cause Contract` |
+| `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、`task.md` 状态、Git commit |
+| `cc-review` | 复杂方案、调查根因或 diff 需要在实现前或验证前做可选深度 Review | 计划 finding 写入 `task.md`；执行 finding 和修复选项回到对话 |
 | `cc-pr-review` | 远程 PR 需要单独会话做合并前 Review | PR review packet、findings 和 landing verdict |
 | `cc-pr-land` | 已 Review PR 需要 rebase-first 合并到 main 并证明 parity | 已集成 main 和本地 / 远程一致性证据 |
-| `cc-check` | 工作需要新鲜验证证据 | `report-card.json` |
-| `cc-act` | 已验证工作需要 PR、本地 handoff、release note 或 closeout | 唯一最终 handoff 文件 |
+| `cc-check` | 工作需要新鲜验证证据 | pass/fail/blocked 回复和 Git commit |
+| `cc-act` | 已验证工作需要 PR、本地 handoff 或 closeout | 可选 `handoff/pr-brief.md`、Git/PR 真相或 incident postmortem |
 
 整包还包含两个维护类 Skill：
 
@@ -114,13 +114,13 @@ flowchart TD
 
 `cc-roadmap` 现在会先记录 planning posture、evidence maturity、项目 canonical language 和持久决策上下文，再推荐路线。idea、已有用户、付费客户、infra、recovery 场景不会被套进同一组问题，也不会让 roadmap item 发明第二套词汇。面向开发者或操作者的 roadmap item 还会把目标用户、time to first value、magic moment、adoption bottleneck 和 domain handoff 交给 `cc-plan`。
 
-Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源：`devflow/specs/`、`devflow/roadmap.json`、`devflow/ROADMAP.md`、`planning/tasks.md` 和 `change-meta.json`。历史 `planning/design.md` / `planning/analysis.md` 只作为旧 change 的可读 fallback。
+Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源：`devflow/specs/`、`devflow/roadmap.json`、`devflow/ROADMAP.md`、`task.md`、Git history 和 PR truth。历史 planning artifacts 只作为可读 fallback 输入。
 
 `cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、public test seam、spec-style test name、public verification path、behavior assertion、mock boundary、覆盖质量、强制 regression test、interface depth、Green minimality guard、refactor candidates 和 vertical tracer-bullet slices。交接前，`cc-plan` 和 `cc-investigate` 还会校准 source roadmap item，让 RM 状态、REQ/FIX 绑定、progress 和 spec diagnosis 不再漂移。
 
-planning 之后的每个阶段都可以先运行 `cc-devflow query workflow-context --change <id> --change-key <key> --data-only --no-trace --compact`。把结果当成 context index，而不是语义压缩：它负责路由下一阶段、标记当前 task、携带 source hash、`mustNotForget` 约束、默认 section/JSON refs、可信命令、fail-closed 规则和机器可读 deep-open 条件；有争议的事实仍由源 artifact 裁决。它主要降低 stage-routing 和 context-reset 的读取成本；端到端 PDCA/IDCA 节省取决于 agent 实际打开多少 `defaultOpen` 和 `deepOpen` refs。可用 `npm run benchmark:workflow-context` 查看仓库示例和合成用例上的 token 估算与路由正确性。用 `npm run benchmark:skills` 保持 public skill 入口足够薄；深层规划规则应该放在条件 reference 后面，而不是默认上下文里。
+planning 之后的每个阶段都可以先运行 `cc-devflow query workflow-context --change <id> --change-key <key> --data-only --no-trace --compact`。把结果当成 context index，而不是语义压缩：它从 `task.md`、Git history 和 PR/handoff truth 路由下一阶段；有争议的事实仍由源 artifact 裁决。用 `npm run benchmark:skills` 保持 public skill 入口足够薄；深层规划规则应该放在条件 reference 后面，而不是默认上下文里。
 
-`cc-review` 是可选的深度 Review，不替代 `cc-check`。它可以接在 `cc-plan` / `cc-investigate` 后审冻结的计划或根因合同，也可以接在 `cc-do` 后审实现。它先读取上次 Review 记录和当前 git/artifact delta，再通过 `cc-devflow review start`、`record-node`、`add-finding`、`close` 把生命周期事件写进 `review-ledger.jsonl`。需要人类 Markdown 报告时，再用 `cc-devflow review render` 按需渲染。宿主支持 subAgent 时，选中的节点可以派给独立只读 reviewer，让 strategy、engineering、design、DX、坏味道、测试和运行时审查不共享同一个被污染的上下文。复杂实现 Review 可以把 intent/regression、security/privacy、performance/reliability、contracts/coverage 拆成独立风险 lane，再由主线程聚合和筛掉弱 findings。计划 Review 通过渐进式 references 借鉴 strategy / design / engineering / DX 方法；实现 Review 检查 diff 范围、代码坏味道、测试、UI/runtime 行为、Browser/Computer Use 证据和日志。Finding 回到 `cc-plan` 或 `cc-do`；实现 Review 干净后再进入 `cc-check`。
+`cc-review` 是可选的深度 Review，不替代 `cc-check`。它可以接在 `cc-plan` / `cc-investigate` 后审冻结的计划或根因合同，也可以接在 `cc-do` 后审实现。计划 / 调查 Review 的 finding 直接写进 `task.md`。执行 Review 的 finding 在当前回复里组织成修复选项，用户选择后才改代码。PR Review 只留在对话或 GitHub review 中。不写本地 review report、ledger、findings JSON 或其它 Review 产物文件。
 
 ## 验证与交付门禁
 
@@ -244,19 +244,18 @@ npx cc-devflow config doctor --cwd /path/to/your/project
 
 - `devflow/specs/` 保存 durable capability truth：`INDEX.md` 和 `capabilities/*.md`。
 - 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号允许共存。并行工作树也可能产生重复编号，必须用完整 change key 的描述区分业务内容。
-- `devflow/changes/<change>/` 保存 durable change truth：CLI 生成的 `change-meta.json`、`planning/tasks.md`、CLI 生成的 `task-manifest.json`、review ledger / findings 记录、debug / failed 的可选 CLI 日志、`report-card.json` 和唯一最终 handoff 文件。任务级 `context.md`、`checkpoint.json`、review markdown 和 AI 手写过程文件不是默认 durable truth。
-- 新 change 默认只有一个人工编写的 Markdown artifact：`planning/tasks.md`。功能计划把冻结设计写进 `## Contract Summary`；Bug 调查把根因真相写进 `## Root Cause Contract`。历史 `planning/design.md`、`planning/analysis.md` 和 `cc-review-*.md` 只作为旧 change 的 fallback 输入，不再是新默认写入。
-- 机器态 JSON 归 CLI 所有：先把人类合同写进 `planning/tasks.md`，再运行 `cc-devflow task-contract compile` / `validate`；不要手写 `task-manifest.json` 或 `change-meta.json`。
-- 用 `cc-devflow task-contract validate`、`npm run verify:artifacts`、`npm run benchmark:artifacts` 和 `npm run benchmark:skills` 保持 workflow artifact 与 skill 入口小而可测。
+- `devflow/changes/<change>/` 的 durable change truth 只保留 `task.md`、可选 `handoff/pr-brief.md` 和 Git commits。真实复发故障可以在 `devflow/postmortems/` 写 incident postmortem。
+- 新 change 默认只有一个人工编写的 Markdown artifact：`task.md`。功能计划把冻结设计写进 `## Contract Summary`；Bug 调查把根因真相写进 `## Root Cause Contract`。历史 planning / review artifacts 只作为可读 fallback 输入。
+- 流程状态归 Git：保持 `task.md` 当前，每个完成阶段 / 执行环境提交 commit，不创建额外过程文件。
+- 用 `cc-devflow query workflow-context`、`npm run verify:examples` 和 `npm run benchmark:skills` 保持 workflow truth 与 skill 入口小而可测。
 - `devflow/workspaces/<change>/` 保存 ephemeral runtime scratch，例如 worker assignment、journal、prompt 和 session log。
 - 能从 durable truth 再生成的文件，不应该持久化到 `devflow/changes/`。
 
 Artifact contract 快速检查：
 
 ```bash
-npx cc-devflow task-contract validate --change REQ-001 --change-key REQ-001-copy-invite-link
-npm run verify:artifacts
-npm run benchmark:artifacts
+npx cc-devflow query workflow-context --change REQ-001 --change-key REQ-001-copy-invite-link --data-only --no-trace --compact
+npm run verify:examples
 npm run benchmark:skills
 ```
 

package/docs/examples/example-bindings.json

@@ -4,13 +4,13 @@
     "cc-roadmap": "5.3.0",
     "cc-next": "1.1.1",
     "cc-dev": "1.1.2",
-    "cc-plan": "3.10.1",
-    "cc-investigate": "1.6.1",
-    "cc-do": "1.7.1",
-    "cc-review": "2.1.2",
+    "cc-plan": "3.10.2",
+    "cc-investigate": "1.6.2",
+    "cc-do": "1.7.2",
+    "cc-review": "2.2.1",
     "cc-pr-review": "1.1.1",
     "cc-pr-land": "1.1.0",
-    "cc-check": "1.12.1",
+    "cc-check": "1.12.2",
     "cc-act": "1.9.1",
     "cc-spec-init": "1.2.0"
   },

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.1`, `cc-do@1.7.1`, `cc-check@1.12.1`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.2`, `cc-do@1.7.2`, `cc-check@1.12.2`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/task.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.10.1`
+- CC-Plan skill version: `3.10.2`
 - Work branch: `REQ/002-bulk-invite-import`
 - Source roadmap item: `RM-010`
 - Source roadmap version: `roadmap.v2`

package/docs/examples/local-handoff/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.1`, `cc-do@1.7.1`, `cc-check@1.12.1`, `cc-act@1.9.1`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.2`, `cc-do@1.7.2`, `cc-check@1.12.2`, `cc-act@1.9.1`
 
 This example shows verified work that is **ready to move forward**, but `cc-act` still chooses `local-handoff`.
 

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/task.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.10.1`
+- CC-Plan skill version: `3.10.2`
 - Work branch: `REQ/003-audit-log-export`
 - Source roadmap item: `RM-020`
 - Source roadmap version: `roadmap.v3`

package/docs/examples/pdca-loop/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.1`, `cc-do@1.7.1`, `cc-check@1.12.1`, `cc-act@1.9.1`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.10.2`, `cc-do@1.7.2`, `cc-check@1.12.2`, `cc-act@1.9.1`
 
 This folder shows one minimal but complete `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act` loop.
 

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/task.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.10.1`
+- CC-Plan skill version: `3.10.2`
 - Work branch: `REQ/001-copy-invite-link`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`

package/docs/guides/artifact-contract.md

@@ -15,4 +15,4 @@ Git records process history. Commit after each completed PDCA or IDCA environmen
 
 ## Retired Surface
 
-Do not create process JSON, review ledgers, report cards, status files, resume files, release notes, or principle files.
+Do not create process files beyond the durable files above.

package/docs/guides/getting-started.md

@@ -89,7 +89,7 @@ Typical outputs:
 - `cc-spec-init` writes `devflow/specs/INDEX.md` and capability specs
 - `cc-plan` writes `task.md#Contract Summary`
 - `cc-investigate` writes `task.md#Root Cause Contract`
-- `cc-review` reports concrete findings in the response; it does not write review process files
+- `cc-review` writes plan/investigation findings into `task.md`; implementation findings stay in the response until the user chooses a repair option
 - `cc-check` reports verification facts in the response, PR brief, or Git commit
 - `cc-act` writes exactly one final PR file, `handoff/pr-brief.md`, or incident postmortem files when a real incident needs a corpse report
 
@@ -98,8 +98,8 @@ Change truth lives in `devflow/changes/<change>/`.
 
 - Keep `INDEX.md` plus capability markdown under `devflow/specs/`.
 - Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` advance as separate local sequences, so cross-prefix duplicates are valid. Parallel worktrees may still repeat numbers; the full change key, especially the description, distinguishes the work. Old lowercase directories are compatibility reads only.
-- Keep `task.md`, optional `handoff/pr-brief.md`, and incident postmortem files under each `devflow/changes/<change>/`. Do not generate task `context.md`, `checkpoint.json`, review ledgers, status/resume files, release notes, principle files, or AI-written process files.
-- Workflow state is Git-owned: keep `task.md`, commit each completed stage, and do not create process JSON.
+- Keep `task.md`, optional `handoff/pr-brief.md`, and Git commits as change truth. Real recurring failures may also write incident postmortems under `devflow/postmortems/`. Do not generate extra process files.
+- Workflow state is Git-owned: keep `task.md`, commit each completed stage, and do not create extra process files.
 - Legacy `planning/design.md`, `planning/analysis.md`, and `cc-review-*.md` are readable fallback inputs for older changes, not new default writes.
 - Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 

package/docs/guides/getting-started.zh-CN.md

@@ -89,7 +89,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 - `cc-spec-init` 产出 `devflow/specs/INDEX.md` 和 capability spec
 - `cc-plan` 产出 `task.md#Contract Summary`
 - `cc-investigate` 产出 `task.md#Root Cause Contract`
-- `cc-review` 在当前回复里报告具体问题，不写 review 过程文件
+- `cc-review` 把计划 / 调查 finding 写入 `task.md`；执行 finding 留在回复里，等用户选择修复方案后再改代码
 - `cc-check` 在当前回复、PR 文件或 Git commit 里记录验证事实
 - `cc-act` 只产出最终 PR 文件 `handoff/pr-brief.md`；真实事故需要尸检时才产出 incident postmortem 文件
 
@@ -97,8 +97,8 @@ durable truth 分两层：
 
 - `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
 - 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 的描述负责区分业务内容，旧小写目录只作为历史兼容读取。
-- `devflow/changes/<change>/`：变更真相，只保留 `task.md`、可选 `handoff/pr-brief.md`，以及真实事故需要的尸检文件。不要生成任务级 `context.md`、`checkpoint.json`、review ledger、status/resume 文件、release note、principles 或 AI 手写过程文件。
-- 流程状态归 Git：保留 `task.md`，每个完成阶段提交 commit，不创建过程 JSON。
+- `devflow/changes/<change>/`：变更真相，只保留 `task.md`、可选 `handoff/pr-brief.md` 和 Git commit；真实复发事故可在 `devflow/postmortems/` 写尸检文件。不要生成额外过程文件。
+- 流程状态归 Git：保留 `task.md`，每个完成阶段提交 commit，不创建额外过程文件。
 - 历史 `planning/design.md`、`planning/analysis.md` 和 `cc-review-*.md` 是旧 change 的可读 fallback，不再是新默认写入。
 - worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 

package/docs/guides/minimize-artifacts.md

@@ -10,13 +10,7 @@ The workflow is intentionally Git-first.
 
 ## Do Not Keep
 
-- process JSON
-- review ledgers or finding files
-- report cards
-- status or resume files
-- release notes
-- principles files
-- task context or checkpoint files
+Do not generate process files beyond the durable files above.
 
 ## Commit Rule
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.5.12",
+    "version": "4.5.14",
     "description": "Multi-platform CLI and skill pack for agent coding",
     "main": "bin/cc-devflow.js",
     "bin": {