cc-devflow 4.5.8 → 4.5.10

package/README.md

@@ -11,40 +11,6 @@
 
 CC-DevFlow is a small, explicit workflow system for agent coding. It gives an AI agent one roadmap entry point, then routes every change through either a feature loop or a bug-investigation loop before work can be called done.
 
-```text
-cc-roadmap
-
-PR Harness: cc-next -> cc-dev -> cc-pr-review -> cc-pr-land
-
-PDCA: cc-plan        -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
-IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
-```
-
-```mermaid
-flowchart TD
-  Roadmap["cc-roadmap\nProduct direction and staged truth"] --> Next["cc-next\nPick next ready Goal Packet"]
-  Next --> Dev["cc-dev\nDrive current worktree to PR"]
-
-  Dev --> Route{"Route"}
-  Route -->|Feature or change| Plan["cc-plan\nFreeze scope and tasks"]
-  Route -->|Bug or regression| Investigate["cc-investigate\nFreeze root cause and repair boundary"]
-
-  Plan --> PlanReview["cc-review\nOptional plan review"]
-  Investigate --> PlanReview
-  PlanReview --> Do["cc-do\nImplement with evidence"]
-  Plan --> Do
-  Investigate --> Do
-
-  Do --> ImplReview["cc-review\nOptional implementation review"]
-  ImplReview --> Check["cc-check\nFresh verification verdict"]
-  Do --> Check
-  Check --> Act["cc-act\nCreate or update remote PR"]
-  Act --> PRReview["cc-pr-review\nSeparate PR review session"]
-  PRReview --> PRLand["cc-pr-land\nRebase, land, prove main parity"]
-  PRReview -->|Fixes required| Dev
-  PRLand --> Main["main\nLocal and remote parity"]
-```
-
 ![CC-DevFlow PR Harness visual workflow](./docs/assets/cc-devflow-pr-harness-en.svg)
 
 ## Why cc-devflow
@@ -87,17 +53,53 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 After installation, ask your agent to use the workflow skills directly. Start with `cc-roadmap` for product direction. Use `cc-next` to select the next roadmap-aware target, `cc-dev` to drive the current worktree through PDCA or IDCA until a remote PR is opened, `cc-pr-review` to review that PR in a separate session, and `cc-pr-land` to land reviewed PRs into main. For manual core workflow work, use `cc-plan` for new work, use `cc-investigate` for bugs, optionally run `cc-review` on complex frozen plans or investigations, then continue through `cc-do`, optional implementation `cc-review`, `cc-check`, and `cc-act`.
 
+## Workflow Map
+
+```text
+cc-roadmap
+
+PR Harness: cc-next -> cc-dev -> cc-pr-review -> cc-pr-land
+
+PDCA: cc-plan        -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+```
+
+```mermaid
+flowchart TD
+  Roadmap["cc-roadmap\nProduct direction and staged truth"] --> Next["cc-next\nPick next ready Goal Packet"]
+  Next --> Dev["cc-dev\nDrive current worktree to PR"]
+
+  Dev --> Route{"Route"}
+  Route -->|Feature or change| Plan["cc-plan\nFreeze scope and tasks"]
+  Route -->|Bug or regression| Investigate["cc-investigate\nFreeze root cause and repair boundary"]
+
+  Plan --> PlanReview["cc-review\nOptional plan review"]
+  Investigate --> PlanReview
+  PlanReview --> Do["cc-do\nImplement with evidence"]
+  Plan --> Do
+  Investigate --> Do
+
+  Do --> ImplReview["cc-review\nOptional implementation review"]
+  ImplReview --> Check["cc-check\nFresh verification verdict"]
+  Do --> Check
+  Check --> Act["cc-act\nCreate or update remote PR"]
+  Act --> PRReview["cc-pr-review\nSeparate PR review session"]
+  PRReview --> PRLand["cc-pr-land\nRebase, land, prove main parity"]
+  PRReview -->|Fixes required| Dev
+  PRLand --> Main["main\nLocal and remote parity"]
+```
+
 ## Workflow Skills
 
 | Skill | Use it when | Main output |
 | --- | --- | --- |
 | `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 and issue truth | one Goal Packet for `cc-dev` |
+| `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` |
@@ -112,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.
+
+`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
 
@@ -240,11 +244,21 @@ 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: `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.
+- Use `cc-devflow task-contract validate`, `npm run verify:artifacts`, and `npm run benchmark:artifacts` to keep workflow artifacts 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
+```
+
+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

@@ -11,40 +11,6 @@
 
 CC-DevFlow 是一个给 Agent 编程时代准备的小而明确的工作流系统。它先用一个 roadmap 入口确定方向，再让每个变更进入「新需求闭环」或「Bug 调查闭环」，最后必须经过验证和交付收口。
 
-```text
-cc-roadmap
-
-PR Harness: cc-next -> cc-dev -> cc-pr-review -> cc-pr-land
-
-PDCA: cc-plan        -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
-IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
-```
-
-```mermaid
-flowchart TD
-  Roadmap["cc-roadmap\n产品方向和阶段真相"] --> Next["cc-next\n选择下一个 Goal Packet"]
-  Next --> Dev["cc-dev\n当前 worktree 自动推进到 PR"]
-
-  Dev --> Route{"路线"}
-  Route -->|新需求或变更| Plan["cc-plan\n冻结范围和任务"]
-  Route -->|Bug 或回归| Investigate["cc-investigate\n冻结根因和修复边界"]
-
-  Plan --> PlanReview["cc-review\n可选方案 Review"]
-  Investigate --> PlanReview
-  PlanReview --> Do["cc-do\n实现并留下证据"]
-  Plan --> Do
-  Investigate --> Do
-
-  Do --> ImplReview["cc-review\n可选实现 Review"]
-  ImplReview --> Check["cc-check\n新鲜验证裁决"]
-  Do --> Check
-  Check --> Act["cc-act\n创建或更新远程 PR"]
-  Act --> PRReview["cc-pr-review\n单独会话 Review PR"]
-  PRReview --> PRLand["cc-pr-land\nRebase 合并并证明 main parity"]
-  PRReview -->|需要修复| Dev
-  PRLand --> Main["main\n本地和远程一致"]
-```
-
 ![CC-DevFlow PR Harness 中文可视化流程](./docs/assets/cc-devflow-pr-harness-zh.svg)
 
 ## 为什么用 cc-devflow
@@ -87,17 +53,53 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 安装完成后，直接让 Agent 使用这些 workflow skill。产品方向先走 `cc-roadmap`。需要自动选择下一步时走 `cc-next`；选中目标后用 `cc-dev` 在当前 worktree 内自动跑 PDCA 或 IDCA，直到远程 PR 打开；PR 用单独会话跑 `cc-pr-review`；review 后用单独会话跑 `cc-pr-land` 合并并证明 main parity。手动核心链路仍然是：新需求走 `cc-plan`，Bug 和 regression 走 `cc-investigate`；复杂计划或根因合同冻结后可以先接 `cc-review`，再进入 `cc-do`；实现复杂时还可以再接一次实现 `cc-review`，最后进入 `cc-check` 和 `cc-act`。
 
+## 流程图
+
+```text
+cc-roadmap
+
+PR Harness: cc-next -> cc-dev -> cc-pr-review -> cc-pr-land
+
+PDCA: cc-plan        -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
+```
+
+```mermaid
+flowchart TD
+  Roadmap["cc-roadmap\n产品方向和阶段真相"] --> Next["cc-next\n选择下一个 Goal Packet"]
+  Next --> Dev["cc-dev\n当前 worktree 自动推进到 PR"]
+
+  Dev --> Route{"路线"}
+  Route -->|新需求或变更| Plan["cc-plan\n冻结范围和任务"]
+  Route -->|Bug 或回归| Investigate["cc-investigate\n冻结根因和修复边界"]
+
+  Plan --> PlanReview["cc-review\n可选方案 Review"]
+  Investigate --> PlanReview
+  PlanReview --> Do["cc-do\n实现并留下证据"]
+  Plan --> Do
+  Investigate --> Do
+
+  Do --> ImplReview["cc-review\n可选实现 Review"]
+  ImplReview --> Check["cc-check\n新鲜验证裁决"]
+  Do --> Check
+  Check --> Act["cc-act\n创建或更新远程 PR"]
+  Act --> PRReview["cc-pr-review\n单独会话 Review PR"]
+  PRReview --> PRLand["cc-pr-land\nRebase 合并并证明 main parity"]
+  PRReview -->|需要修复| Dev
+  PRLand --> Main["main\n本地和远程一致"]
+```
+
 ## Workflow Skill
 
 | Skill | 什么时候用 | 主要产物 |
 | --- | --- | --- |
 | `cc-roadmap` | 需要产品方向、阶段范围或 backlog 顺序 | `devflow/roadmap.json`、`devflow/ROADMAP.md`、deprecated `devflow/BACKLOG.md` |
-| `cc-next` | 需要从 roadmap 和 issue truth 里选下一个 ready 目标 | 交给 `cc-dev` 的 Goal Packet |
+| `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` |
@@ -112,11 +114,13 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 `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 估算与路由正确性。
+
+`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`。
 
 ## 验证与交付门禁
 
@@ -240,11 +244,21 @@ 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：`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 输入，不再是新默认写入。
+- 用 `cc-devflow task-contract validate`、`npm run verify:artifacts` 和 `npm run benchmark:artifacts` 保持 workflow artifact 小而可测。
 - `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
+```
+
+想先看完整产物链，可以从 [`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)。
 
 ## 开发