cc-devflow 4.5.10 → 4.5.12

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

@@ -1,55 +1,19 @@
 # CC-Spec-Init Playbook
 
-## Core Rules
+## Role
 
-1. 先定 capability 边界，再写 spec 文本。
-2. `spec` 记录现状，`roadmap` 记录未来，`change-meta` 记录桥接。
-3. 同一个 change 可以多挂 capability，但只能有一个 primary capability。
-4. 正常演化优先 `deprecated` / `merged` / `split`，不要直接物理删除。
-5. 每次变更结束都跑链接校验，别把断链留到下轮执行。
+Specs record current capability truth. Roadmap records future work. Git records process history.
 
-## Standard Modes
+## Flow
 
-### Bootstrap
+1. Read existing `devflow/specs/INDEX.md`.
+2. Read related capability specs.
+3. Decide whether the work is bootstrap, create, split, merge, deprecate, or language cleanup.
+4. Update spec Markdown only.
+5. Commit the spec change.
 
-- 建 `devflow/specs/INDEX.md`
-- 建 `devflow/specs/capabilities/`
-- 为当前最重要的 capability 建最小 truth source
+## Do Not
 
-### Create
-
-- 新 capability spec
-- 回写 `INDEX.md`
-- 为当前 change 生成 `change-meta.json`
-
-### Update Links
-
-- 修 roadmap / backlog / change / spec 的 capability 引用
-- 重建 `INDEX.md`
-
-### Split / Merge / Deprecate
-
-- 在原 capability spec 标明状态变化
-- 补 `splitInto` / `mergedInto` / `supersededBy`
-- 确认历史 change 仍然可追踪
-
-## Command Kit
-
-```bash
-# 初始化 specs 目录
-bash .claude/skills/cc-spec-init/scripts/bootstrap-specs.sh
-
-# 校验 spec 链路
-bash .claude/skills/cc-spec-init/scripts/validate-spec-links.sh
-
-# 看哪些 change 已缺 change-meta
-find devflow/changes -maxdepth 2 -name change-meta.json | sort
-```
-
-## Review Questions
-
-1. capability 的边界是否清楚到 AI 不会把别的系统能力写进来？
-2. `Current Truth` 是否只写当前成立的承诺？
-3. `Missing` 和 `Intentional Gaps` 是否被保留下来？
-4. roadmap item 和 change 是否都能指向 capability？
-5. 这次是该 `update`，还是其实应该 `split` / `merge`？
+- Do not create change-scoped JSON.
+- 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

@@ -1,148 +1,45 @@
 ---
 name: cc-spec-init
-version: 1.1.0
-description: Use when you need to initialize capability specs under `devflow/specs/`, create or evolve capability truth sources, generate `change-meta.json`, or validate roadmap/change/spec links before roadmap, planning, or closeout work continues.
+version: 1.2.0
+description: Use when you need to initialize or evolve capability specs under `devflow/specs/`.
+reads:
+  - PLAYBOOK.md
+  - references/spec-contract.md
+  - assets/INDEX_TEMPLATE.md
+  - assets/CAPABILITY_TEMPLATE.md
+writes:
+  - path: devflow/specs/INDEX.md
+    durability: durable
+    required: false
+  - path: devflow/specs/capabilities/<capability>.md
+    durability: durable
+    required: false
+effects:
+  - capability truth source initialization or update
+  - Git commit after spec work completes
 ---
 
 # CC-Spec-Init
 
-> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
+`cc-spec-init` maintains long-lived capability specs. It is not a process-state generator.
 
-## Role
-
-`cc-spec-init` 是 capability-centered spec 的收口器。
-
-它只做一件事：把系统“当前承诺什么”收成稳定 truth source，并把 `roadmap -> change -> spec` 的链接补齐。
-
-它不是主 workflow 的一环。
-
-主 workflow 仍然是：
-
-- `cc-roadmap`
-- `cc-plan` 或 `cc-investigate`
-- `cc-do`
-- `cc-check`
-- `cc-act`
-
-`cc-spec-init` 负责这些动作：
-
-- 初始化 `devflow/specs/`
-- 新建 capability spec
-- 对 capability 做 `split` / `merge` / `deprecate`
-- 生成或修复 `devflow/changes/<change-key>/change-meta.json`
-- 重建 `devflow/specs/INDEX.md`
-- 校验 capability、roadmap item、change 之间的链接完整性
-
-## Runtime Output Policy
-
-写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
-
-- `Output language` 是机器约束，capability spec、`devflow/specs/INDEX.md` 和 `change-meta.json` 必须记录并遵守它。
-- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
-- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
-
-## Read First
-
-1. `PLAYBOOK.md`
-2. `CHANGELOG.md`
-3. `references/spec-contract.md`
-4. `assets/INDEX_TEMPLATE.md`
-5. `assets/CAPABILITY_TEMPLATE.md`
-6. `assets/CHANGE_META_TEMPLATE.json`
-
-## Use This Skill When
-
-- 你第一次把仓库升级到 capability-centered spec 模型
-- 需要创建新 capability spec
-- 需要把 change 绑定到 primary / secondary capability
-- 需要做 capability 的 `split` / `merge` / `deprecate`
-- `cc-roadmap`、`cc-plan`、`cc-act` 发现 spec 链路断了
-- 需要在 closeout 前确认 spec/roadmap/change 仍然同构
-
-如果当前工作只是执行一个已冻结任务，不要停在这里，回主 workflow。
-
-## Entry Gate
-
-1. 先读现有 `devflow/specs/INDEX.md`、相关 capability spec、相关 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`、相关 `change-meta.json`。
-2. 先判断你是在做 `bootstrap`、`create`、`update-links`、`split`、`merge` 还是 `deprecate`。
-3. 先锁定 capability 边界，再写模板；不要先写 prose 再猜结构。
-4. 先明确 primary capability，再允许 secondary capabilities 存在。
-5. 先检查命名是否已经有 canonical term；同义词、歧义词和关系约束没收口前，不要新建第二套 capability 名称。
-
-## Session Protocol
-
-1. 先判断现状：
-   - `devflow/specs/` 是否已存在
-   - capability 是否已存在
-   - 相关 change 是否已有 `change-meta.json`
-2. 如果是首次初始化：
-   - 创建 `devflow/specs/INDEX.md`
-   - 创建 `devflow/specs/capabilities/`
-   - 为当前已知 capability 写最小 spec
-3. 如果是新 capability：
-   - 先写 capability 边界、约束、当前 truth、gaps
-   - 再写最小 language block：canonical term、definition、aliases to avoid、relationships、flagged ambiguities
-   - 再登记到 `INDEX.md`
-4. 如果是 change 绑定：
-   - 生成或更新 `change-meta.json`
-   - 填入 `primaryCapability`、`secondaryCapabilities`、`expectedDelta`、`affectedInvariants`、`gapsClosed`、`newGaps`
-5. 如果是 capability 结构调整：
-   - 优先 `deprecated` / `mergedInto` / `splitInto`
-   - 不要直接物理删除，除非确认没有 roadmap/change 仍在引用
-6. 结束前运行链接校验，确认：
-   - `INDEX.md` 引到的 capability 文件都存在
-   - `change-meta.json` 里的 capability 都能落到 spec
-   - roadmap / backlog 里的 capability 引用仍可追踪
-   - 新 capability 的名称、aliases、relationships 没有和已有 spec 冲突
-
-## Language Boundary Gate
-
-capability spec 是长期 truth source，命名必须比一次需求更稳定：
-
-- canonical term：只选一个主名，优先沿用 roadmap、历史 design/analysis、代码公共接口和用户领域语言里已经稳定的词。
-- aliases to avoid：记录容易混用的别名，说明为什么不能继续用。
-- flagged ambiguity：同一个词指向两个概念时，必须写清拆分边界，必要时拆 capability。
-- relationships：用一句话写清 capability 之间的拥有、依赖、生命周期、输入输出或互斥关系。
-- implementation names：类名、文件名、函数名只有在它们已经是公共领域语言时才进入 spec；否则留在 change 设计里。
-
-## Output
+Allowed outputs:
 
 - `devflow/specs/INDEX.md`
 - `devflow/specs/capabilities/<capability>.md`
-- `devflow/changes/<change-key>/change-meta.json`
-- 链接校验结果
-
-## Working Rules
 
-1. `spec` 写现状，不写一次性推导过程。
-2. `roadmap` 写未来推进，不写当前 truth。
-3. `change-meta.json` 是机器真相源；capability markdown 是人机共读的长期约束源。
-4. 一个 change 可以挂多个 capability，但必须有一个 `primaryCapability`。
-5. capability 不直接硬删除；优先用状态表达历史连续性。
-6. `INDEX.md` 只做目录和状态总览，不复制各 spec 正文。
+Do not create change-scoped JSON. Changes link to specs through `task.md`, roadmap text, PR text, and Git commits.
 
-## Bundled Resources
+## Use This Skill When
 
-- 变更记录：`CHANGELOG.md`
-- 使用剧本：`PLAYBOOK.md`
-- 契约：`references/spec-contract.md`
-- 模板：`assets/INDEX_TEMPLATE.md`
-- 模板：`assets/CAPABILITY_TEMPLATE.md`
-- 模板：`assets/CHANGE_META_TEMPLATE.json`
-- 初始化：`scripts/bootstrap-specs.sh`
-- 校验：`scripts/validate-spec-links.sh`
+- initializing `devflow/specs/`
+- creating a capability spec
+- splitting, merging, or deprecating a capability
+- clarifying canonical project language
 
 ## Exit Criteria
 
-- `devflow/specs/` 已建立或已修复
-- 相关 capability spec 有明确边界、约束、truth、gaps
-- 相关 change 已有 `change-meta.json`
-- `INDEX.md`、roadmap、change、spec 之间的链接可追踪
-- 下一步可以安心回到 `cc-roadmap`、`cc-plan` 或 `cc-act`
-
-## Do Not
-
-- 不把 roadmap 写回 spec
-- 不把执行细节写成 capability truth
-- 不允许没有 primary capability 的多 capability change
-- 不直接删 capability 文件导致链路断裂
+- capability boundary is clear
+- current truth and gaps are written
+- `INDEX.md` links to existing capability files
+- spec changes are committed to Git

package/.claude/skills/cc-spec-init/references/spec-contract.md

@@ -1,22 +1,13 @@
 # Spec Contract
 
-## Truth Layers
+## Files
 
-- `devflow/ROADMAP.md` / `devflow/BACKLOG.md`: 未来推进什么 capability
-- `devflow/specs/INDEX.md`: capability 总目录与当前状态快照
-- `devflow/specs/capabilities/*.md`: 某个 capability 当前承诺什么
-- `devflow/changes/<change>/change-meta.json`: 某次 change 如何影响 capability
+- `devflow/specs/INDEX.md`
+- `devflow/specs/capabilities/<capability>.md`
 
-## Capability Rules
+## Rules
 
-1. 以用户可感知能力为主，内部系统能力为辅。
-2. `Boundary`、`Invariants`、`Current Truth` 是核心，不要被 narrative 淹没。
-3. `Missing` 与 `Intentional Gaps` 必须长期保留。
-4. capability 名称要稳定、可重用，不要按一次需求命名。
-
-## Change Meta Rules
-
-1. `primaryCapability` 必填。
-2. `secondaryCapabilities` 可空，但必须有明确原因。
-3. `changeType` 只使用：`create`、`update`、`split`、`merge`、`deprecate`。
-4. `syncStatus` 生命周期：`planned -> verified -> synced`。
+- Specs describe stable capability truth.
+- Specs do not track per-change state.
+- Per-change decisions live in `task.md`, PR text, commits, or postmortems.
+- Capability names must follow project language and avoid duplicate terms.

package/CHANGELOG.md

@@ -9,6 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.12] - 2026-05-13
+
+### Changed
+
+- Changed `cc-devflow task-contract` so task document budgets are advisory warnings instead of blocking validation failures.
+- Changed `npm run benchmark:skills` so skill entrypoint budgets report advisory failures without failing `npm run verify`.
+- Updated `cc-plan` and `cc-investigate` to preserve required task-template fields instead of trimming contract truth to fit token estimates.
+
+### Fixed
+
+- Fixed `task-contract compile` so shorthand task checklists fail before `task-manifest.json` or `change-meta.json` can be generated.
+- Added task-template validation to reject incomplete task blocks with `C11` instead of letting default manifest enrichment hide missing contract fields.
+
+## [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

package/README.md

@@ -118,7 +118,7 @@ Canonical language and durable decisions stay inside cc-devflow-native sources:
 
 `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.
+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`.
 
@@ -244,9 +244,10 @@ 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-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.
+- `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.
-- Use `cc-devflow task-contract validate`, `npm run verify:artifacts`, and `npm run benchmark:artifacts` to keep workflow artifacts small and measurable.
+- 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/`.
 
@@ -256,6 +257,7 @@ Artifact contract quick checks:
 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).

package/README.zh-CN.md

@@ -118,7 +118,7 @@ Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源
 
 `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 估算与路由正确性。
+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`。
 
@@ -244,9 +244,10 @@ 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-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。
+- `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 输入，不再是新默认写入。
-- 用 `cc-devflow task-contract validate`、`npm run verify:artifacts` 和 `npm run benchmark:artifacts` 保持 workflow artifact 小而可测。
+- 机器态 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/`。
 
@@ -256,6 +257,7 @@ Artifact contract 快速检查：
 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)。