cc-devflow 4.5.9 → 4.5.11

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

@@ -15,10 +15,12 @@ if [[ -z "$change_dir" ]]; then
 fi
 
 review_dir="$change_dir/review"
-ledger="$review_dir/cc-review-ledger.jsonl"
+ledger="$review_dir/review-ledger.jsonl"
+legacy_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"
+findings="$review_dir/review-findings.json"
+legacy_findings="$review_dir/cc-review-findings.json"
 
 head_sha="$(git rev-parse HEAD)"
 base_sha=""
@@ -27,9 +29,14 @@ if git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
 fi
 
 reviewed_sha=""
-if [[ -f "$ledger" ]]; then
+ledger_for_read="$ledger"
+if [[ ! -f "$ledger_for_read" && -f "$legacy_ledger" ]]; then
+  ledger_for_read="$legacy_ledger"
+fi
+
+if [[ -f "$ledger_for_read" ]]; then
   reviewed_sha="$(
-    sed -n 's/.*"headSha"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ledger" |
+    sed -n 's/.*"headSha"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ledger_for_read" |
       tail -n 1
   )"
 fi
@@ -57,7 +64,7 @@ echo "diff_base=${diff_base:-unknown}"
 
 echo
 echo "PRIOR_REVIEW_FILES"
-for file in "$plan" "$report" "$ledger" "$findings"; do
+for file in "$ledger" "$findings" "$plan" "$report" "$legacy_ledger" "$legacy_findings"; do
   if [[ -f "$file" ]]; then
     printf 'present %s\n' "$file"
   else
@@ -73,8 +80,8 @@ else
   git diff --name-status HEAD
 fi
 
-if [[ -f "$ledger" ]]; then
+if [[ -f "$ledger_for_read" ]]; then
   echo
   echo "RECENT_LEDGER"
-  tail -n 20 "$ledger"
+  tail -n 20 "$ledger_for_read"
 fi

package/CHANGELOG.md

@@ -9,6 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.11] - 2026-05-13
+
+### Added
+
+- Added `npm run benchmark:skills` to keep public skill entrypoints under explicit context budgets.
+
+### Changed
+
+- Slimmed the `cc-plan` public entrypoint into a thin harness contract and moved low-frequency planning/review rules behind conditional references.
+- Slimmed the `cc-investigate` public entrypoint into a thin root-cause contract and moved low-frequency debug rules behind conditional references.
+- Updated `cc-plan` and `cc-investigate` to require CLI-owned machine artifacts: agents write `planning/tasks.md`, then run `cc-devflow task-contract compile` / `validate` for `task-manifest.json` and `change-meta.json`.
+- Internalized the new PDCA/IDCA operating principles into the stage skills themselves: assumptions and simplicity in plan/investigate, surgical read-before-write execution in do, fresh intent-focused proof in check, and explicit checkpoint/ship blockers in dev/act.
+- Updated `npm run verify` to include `benchmark:skills` after tests, example binding checks, and artifact verification.
+
+## [4.5.10] - 2026-05-13
+
+### Added
+
+- Added the `workflow-context` typed runtime query as a context index that reports the next PDCA/IDCA skill, current task, source hashes, `mustNotForget` guardrails, default section/JSON refs, trusted commands, fail-closed rules, and machine-readable deep-open triggers.
+- Added `cc-devflow query --data-only --no-trace --compact` output controls and `npm run benchmark:workflow-context` for checked-in token estimates plus synthetic routing-correctness cases.
+- Added the minimized workflow artifact contract guide, `cc-devflow task-contract validate`, `npm run verify:artifacts`, and `npm run benchmark:artifacts` so change artifacts stay small and measurable.
+
+### Changed
+
+- Updated `cc-plan`, `cc-investigate`, `cc-do`, `cc-check`, `cc-act`, and `cc-dev` so stage transitions start from `cc-devflow query workflow-context --data-only --no-trace --compact` instead of reloading the full loop history by default.
+- Updated `cc-plan` and `cc-investigate` so new changes default to `planning/tasks.md` as the only human-authored Markdown handoff: feature plans use `## Contract Summary`, bug investigations use `## Root Cause Contract`, and legacy `planning/design.md` / `planning/analysis.md` remain fallback inputs only.
+- Updated `cc-review` so `review/review-ledger.jsonl` is the default durable review record, with `review-findings.json` and rendered Markdown reports created only when needed.
+- Updated `cc-check` review truth loading to prefer structured findings and review ledger records before legacy `cc-review-*.md` reports.
+- Updated `npm run verify` to include `verify:artifacts` after tests and example binding checks.
+
 ## [4.5.9] - 2026-05-11
 
 ### Added

package/CONTRIBUTING.md

@@ -13,17 +13,25 @@ cc-devflow is now a skills-first repository with a restored distributable CLI.
 Public surface:
 
 - `cc-roadmap`
+- `cc-next`
+- `cc-dev`
 - `cc-plan`
 - `cc-investigate`
 - `cc-do`
+- `cc-review`
+- `cc-pr-review`
+- `cc-pr-land`
 - `cc-check`
 - `cc-act`
 - `cc-devflow init`
 - `cc-devflow adapt`
+- `cc-devflow query`
+- `cc-devflow task-contract`
+- `cc-devflow review`
 
 Shared runtime helpers may still live under `lib/skill-runtime/`, but they are not the user-facing workflow anymore.
 
-Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`, but they do not change the public `cc-roadmap + PDCA/IDCA` workflow story.
+Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`. `cc-spec-init` and `cc-simplify` ship with the pack as maintenance skills; `docs-sync` stays internal.
 
 ---
 
@@ -125,7 +133,34 @@ If you touch a shipped skill, treat these files as one contract:
 
 Do not change one part of the contract and leave the others stale.
 
-### 3. Keep Distribution Clean
+Codex output under `.codex/skills/` is generated by `cc-devflow adapt`. Do not hand-edit it. Change `.claude/skills/<skill>/` first, then regenerate the mirror with:
+
+```bash
+npm run adapt
+npm run adapt -- --check
+```
+
+### 3. Keep Skill Contract Changes Complete
+
+When a shipped skill contract changes, update the source and public surfaces in one pass:
+
+- `.claude/skills/<skill>/SKILL.md`
+- `.claude/skills/<skill>/CHANGELOG.md`
+- affected `PLAYBOOK.md`, `assets/`, `references/`, and `scripts/`
+- root `README.md` / `README.zh-CN.md`
+- affected docs under `docs/`
+- `docs/examples/example-bindings.json` and example metadata
+
+Then run the relevant gates:
+
+```bash
+npm run verify:examples
+npm run verify:publish
+npm run verify:artifacts
+npm run verify
+```
+
+### 4. Keep Distribution Clean
 
 Do not ship transient files in templates or tarballs.
 
@@ -135,7 +170,7 @@ Examples of junk we should exclude:
 - `.DS_Store`
 - local editor or OS artifacts
 
-### 4. Keep Runtime Helpers Secondary
+### 5. Keep Runtime Helpers Secondary
 
 If you touch `lib/skill-runtime/`, keep the behavior testable, but do not document it as the primary user entry. The public workflow still belongs to the shipped skills.
 
@@ -178,7 +213,8 @@ This should confirm:
 - do not describe `.claude/commands/` as required structure
 - do not describe internal runtime helpers as the supported public workflow
 - if a shipped skill changes, update that skill's `version`, local `CHANGELOG.md`, and affected public docs in the same PR
-- keep the workflow story as `cc-roadmap + PDCA/IDCA` visible skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+- keep the workflow story as `cc-roadmap`, `cc-next`, `cc-dev`, manual PDCA/IDCA skills, optional `cc-review`, and PR review/landing skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+- do not hand-edit `.codex/skills`; regenerate it from `.claude/skills` with `npm run adapt`
 
 ---
 

package/CONTRIBUTING.zh-CN.md

@@ -13,17 +13,25 @@ cc-devflow 现在是一个 skills-first 仓库，并且重新带回了可分发
 对外可见面只有这些：
 
 - `cc-roadmap`
+- `cc-next`
+- `cc-dev`
 - `cc-plan`
 - `cc-investigate`
 - `cc-do`
+- `cc-review`
+- `cc-pr-review`
+- `cc-pr-land`
 - `cc-check`
 - `cc-act`
 - `cc-devflow init`
 - `cc-devflow adapt`
+- `cc-devflow query`
+- `cc-devflow task-contract`
+- `cc-devflow review`
 
 `lib/skill-runtime/` 可以保留共享运行时支撑，但它已经不是用户要直接理解或运行的工作流入口。
 
-仓库里也可以存在维护类 Skill，例如 `cc-spec-init`、`cc-simplify`、`docs-sync`，但它们不改变公开的 `cc-roadmap + PDCA/IDCA` 叙事。
+仓库里也可以存在维护类 Skill，例如 `cc-spec-init`、`cc-simplify`、`docs-sync`。其中 `cc-spec-init` 和 `cc-simplify` 随整包分发为维护类 Skill；`docs-sync` 仍是内部维护 Skill。
 
 ---
 
@@ -125,7 +133,34 @@ cc-devflow/
 
 不要只改其中一部分，让其余说明继续过期。
 
-### 3. 保持分发包干净
+Codex 输出目录 `.codex/skills/` 由 `cc-devflow adapt` 生成。不要手改它。先改 `.claude/skills/<skill>/`，再重新生成镜像：
+
+```bash
+npm run adapt
+npm run adapt -- --check
+```
+
+### 3. 保持 Skill 契约变更完整
+
+如果一个已发布 Skill 的契约变化，请一次性同步这些面：
+
+- `.claude/skills/<skill>/SKILL.md`
+- `.claude/skills/<skill>/CHANGELOG.md`
+- 受影响的 `PLAYBOOK.md`、`assets/`、`references/` 和 `scripts/`
+- 根 `README.md` / `README.zh-CN.md`
+- `docs/` 下受影响的公开文档
+- `docs/examples/example-bindings.json` 和样例 metadata
+
+然后运行相关门禁：
+
+```bash
+npm run verify:examples
+npm run verify:publish
+npm run verify:artifacts
+npm run verify
+```
+
+### 4. 保持分发包干净
 
 不要把瞬态文件放进模板或 tarball。
 
@@ -135,7 +170,7 @@ cc-devflow/
 - `.DS_Store`
 - 本地编辑器和操作系统产生的垃圾文件
 
-### 4. 让运行时辅助层保持次要
+### 5. 让运行时辅助层保持次要
 
 如果你改了 `lib/skill-runtime/`，请保持可测试，但不要再把它写成用户主入口。真正的公开 workflow 仍然属于已发布 Skill。
 
@@ -178,7 +213,8 @@ node scripts/validate-publish.js
 - 不要把 `.claude/commands/` 写成必需结构
 - 不要把内部运行时辅助层写成受支持的公开工作流
 - 如果改了已发布 Skill，在同一个 PR 里同步该 Skill 的 `version`、本地 `CHANGELOG.md` 和受影响的公开文档
-- 主 workflow 仍然只讲 `cc-roadmap + PDCA/IDCA`；`cc-spec-init` / `cc-simplify` 等维护类 Skill 单独说明
+- 主 workflow 仍然围绕 `cc-roadmap`、`cc-next`、`cc-dev`、手动 PDCA/IDCA Skill、可选 `cc-review` 和 PR review/landing Skill；`cc-spec-init` / `cc-simplify` 等维护类 Skill 单独说明
+- 不要手改 `.codex/skills`；从 `.claude/skills` 通过 `npm run adapt` 重新生成
 
 ---
 

package/README.md

@@ -96,10 +96,10 @@ 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/design.md`, `planning/tasks.md`, `task-manifest.json` |
-| `cc-investigate` | A bug needs symptom, reproduction, root cause, and repair boundary | `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json` |
-| `cc-do` | Planned or investigated work needs implementation | code, tests, checkpoints, scratch runtime |
-| `cc-review` | Complex plans, investigations, or diffs need optional deep multi-round review before implementation or verification | `cc-review-report.md`, optional `cc-review-findings.json` |
+| `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-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` |
@@ -114,11 +114,13 @@ 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/design.md`, `planning/analysis.md`, and `change-meta.json`.
+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.
 
 `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.
 
-`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 first reads prior review records and current git/artifact delta, writes a review plan, then checks review nodes one by one with ledger entries. 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`.
+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.
+
+`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`.
 
 ## Verification And Ship Gates
 
@@ -242,11 +244,23 @@ 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: `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file.
+- `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/workspaces/<change>/` stores ephemeral runtime scratch such as worker assignment, journals, prompts, and session logs.
 - Regenerable files should not be persisted under `devflow/changes/`.
 
-For complete artifact examples, start with [`docs/examples/START-HERE.md`](./docs/examples/START-HERE.md). Example version bindings live in [`docs/examples/example-bindings.json`](./docs/examples/example-bindings.json).
+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
+npm run benchmark:skills
+```
+
+For complete artifact examples, start with [`docs/examples/START-HERE.md`](./docs/examples/START-HERE.md). Example version bindings live in [`docs/examples/example-bindings.json`](./docs/examples/example-bindings.json). Migration and authoring guidance for the minimized artifact contract lives in [`docs/guides/minimize-artifacts.md`](./docs/guides/minimize-artifacts.md).
 
 ## Development
 

package/README.zh-CN.md

@@ -96,10 +96,10 @@ 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/design.md`、`planning/tasks.md`、`task-manifest.json` |
-| `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` |
-| `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、checkpoint、scratch runtime |
-| `cc-review` | 复杂方案、调查根因或 diff 需要在实现前或验证前做可选深度多轮 Review | `cc-review-report.md`，可选 `cc-review-findings.json` |
+| `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-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` |
@@ -114,11 +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/design.md`、`planning/analysis.md` 和 `change-meta.json`。
+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。
 
 `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 不再漂移。
 
-`cc-review` 是可选的深度 Review，不替代 `cc-check`。它可以接在 `cc-plan` / `cc-investigate` 后审冻结的计划或根因合同，也可以接在 `cc-do` 后审实现。它先读取上次 Review 记录和当前 git/artifact delta，写出 Review 计划，再逐节点检查并写 ledger。宿主支持 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`。
+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 后面，而不是默认上下文里。
+
+`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`。
 
 ## 验证与交付门禁
 
@@ -242,11 +244,23 @@ 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：`change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、`team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一最终 handoff 文件。
+- `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/workspaces/<change>/` 保存 ephemeral runtime scratch，例如 worker assignment、journal、prompt 和 session log。
 - 能从 durable truth 再生成的文件，不应该持久化到 `devflow/changes/`。
 
-想先看完整产物链，可以从 [`docs/examples/START-HERE.md`](./docs/examples/START-HERE.md) 开始。样例和 Skill 的版本绑定真相源在 [`docs/examples/example-bindings.json`](./docs/examples/example-bindings.json)。
+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
+npm run benchmark:skills
+```
+
+想先看完整产物链，可以从 [`docs/examples/START-HERE.md`](./docs/examples/START-HERE.md) 开始。样例和 Skill 的版本绑定真相源在 [`docs/examples/example-bindings.json`](./docs/examples/example-bindings.json)。最小 artifact 合同的迁移与编写指南在 [`docs/guides/minimize-artifacts.md`](./docs/guides/minimize-artifacts.md)。
 
 ## 开发