cc-devflow 4.5.10 → 4.5.11

package/.claude/skills/cc-plan/assets/TASKS_TEMPLATE.md

@@ -18,6 +18,7 @@
 - Open for scheduling: `planning/task-manifest.json`, ready-task selector output, dependencies, touched files.
 - Open for parallel or ownership questions: Implementation Surface Map, Tracer Bullet Map.
 - Open for audit/recovery: Task Quality Bar, Git state, CLI logs, review/report-card.json.
+- Machine JSON rule: after editing this file, run `cc-devflow task-contract compile --change <changeId> --change-key <changeKey>` and `cc-devflow task-contract validate --change <changeId> --change-key <changeKey>`; do not handwrite `task-manifest.json` or `change-meta.json`.
 
 ## Contract Summary
 
@@ -47,6 +48,8 @@ Risk / Escalate If:
 > This is the default human-authored planning contract. Do not create
 > `planning/design.md` for new changes unless the user explicitly requests a
 > legacy artifact or a migration requires preserving one.
+> `task-manifest.json` and `change-meta.json` are generated by
+> `cc-devflow task-contract compile`, not by manual AI JSON authoring.
 
 ## Execution Handoff
 

package/.claude/skills/cc-plan/assets/TASK_MANIFEST_TEMPLATE.json

@@ -9,7 +9,7 @@
     "documentLanguage": ""
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.9.0",
+    "reqPlanSkillVersion": "3.9.2",
     "designVersion": "design.v1",
     "workBranch": "REQ/XXX-short-feature-name",
     "approvedAt": "2026-04-15T12:00:00.000Z",
@@ -133,7 +133,6 @@
       ],
       "context": {
         "readFiles": [
-          "design.md",
           "tasks.md",
           "change-meta.json"
         ],
@@ -173,7 +172,7 @@
   ],
   "metadata": {
     "source": "tasks.md",
-    "generatedBy": "skill:cc-plan",
+    "generatedBy": "cc-devflow task-contract",
     "planVersion": 1
   }
 }

package/.claude/skills/cc-plan/references/planning-contract.md

@@ -2,11 +2,12 @@
 
 ## Hard Rules
 
-1. `cc-plan` 默认只产出 3 个文件：`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json`。
+1. `cc-plan` 默认只产出 3 个文件：`planning/tasks.md`、CLI 生成的 `planning/task-manifest.json`、CLI 生成的 `change-meta.json`。
 2. clarification / brainstorm / review 结论必须并入 `planning/tasks.md#Contract Summary`，不能再默认拆 `planning/design.md` 或独立文档。
 3. 执行 handoff 必须写进 `planning/tasks.md` 顶部，不能依赖单独的 `context-package.md`。
 4. `planning/task-manifest.json` 必须和 `planning/tasks.md` 同步，且能告诉 `cc-do` 当前任务是谁。
 5. `planning/tasks.md`、`planning/task-manifest.json` 必须记录来源版本链。
+6. 机器态 JSON 必须由 `cc-devflow task-contract compile` / 模板 / validator 生成或更新；AI 不手写 `task-manifest.json` 或 `change-meta.json`。
 6. 所有 SKILL 输出必须遵守 `docs/guides/artifact-contract.md`：状态只能有一个 owner，其它文件只能引用、投影或派生。
 7. 计划里出现 placeholder 词，就说明还没想清楚。
 8. 一次只推进一个澄清问题，不允许问题轰炸。

package/CHANGELOG.md

@@ -9,6 +9,20 @@ 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

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)。

package/docs/examples/START-HERE.md

@@ -140,7 +140,8 @@ That should already tell you:
 
 `devflow/changes/<change>/` should stay lean.
 
-- Durable truth only: `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. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
+- Durable truth only: 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. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
+- Machine JSON is CLI-owned: run `cc-devflow task-contract compile` / `validate`; do not handwrite `task-manifest.json` or `change-meta.json`.
 - Legacy `planning/design.md`, `planning/analysis.md`, and `cc-review-*.md` are readable fallback inputs for older examples, not new default writes.
 - Runtime scratch belongs in `devflow/workspaces/<change>/`, not beside the durable record.
 

package/docs/examples/example-bindings.json

@@ -3,15 +3,15 @@
   "skills": {
     "cc-roadmap": "5.3.0",
     "cc-next": "1.0.1",
-    "cc-dev": "1.0.1",
-    "cc-plan": "3.9.0",
-    "cc-investigate": "1.5.0",
-    "cc-do": "1.6.7",
+    "cc-dev": "1.0.2",
+    "cc-plan": "3.9.2",
+    "cc-investigate": "1.5.1",
+    "cc-do": "1.6.8",
     "cc-review": "2.0.0",
     "cc-pr-review": "1.0.0",
     "cc-pr-land": "1.0.0",
-    "cc-check": "1.11.1",
-    "cc-act": "1.8.8",
+    "cc-check": "1.11.2",
+    "cc-act": "1.8.9",
     "cc-spec-init": "1.1.0"
   },
   "examples": [

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.9.0`, `cc-do@1.6.7`, `cc-check@1.11.1`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.9.2`, `cc-do@1.6.8`, `cc-check@1.11.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/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.9.0`
+- CC-Plan skill version: `3.9.2`
 - Work branch: `REQ/002-bulk-invite-import`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`

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

@@ -6,7 +6,7 @@
   "requirementId": "REQ-002",
   "requirementVersion": "REQ-002.v2",
   "planningMeta": {
-    "reqPlanSkillVersion": "3.9.0",
+    "reqPlanSkillVersion": "3.9.2",
     "designVersion": "design.v2",
     "workBranch": "REQ/002-bulk-invite-import",
     "approvedAt": null,

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

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.9.0`
+- CC-Plan skill version: `3.9.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.9.0`, `cc-do@1.6.7`, `cc-check@1.11.1`, `cc-act@1.8.8`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.9.2`, `cc-do@1.6.8`, `cc-check@1.11.2`, `cc-act@1.8.9`
 
 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/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.9.0`
+- CC-Plan skill version: `3.9.2`
 - Work branch: `REQ/003-audit-log-export`
 - Requirement ID: `REQ-003`
 - Design mode: `tiny-design`

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/task-manifest.json

@@ -6,7 +6,7 @@
   "requirementId": "REQ-003",
   "requirementVersion": "REQ-003.v1",
   "planningMeta": {
-    "reqPlanSkillVersion": "3.9.0",
+    "reqPlanSkillVersion": "3.9.2",
     "designVersion": "design.v1",
     "workBranch": "REQ/003-audit-log-export",
     "approvedAt": "2026-04-16T13:10:00.000Z",

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

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.9.0`
+- CC-Plan skill version: `3.9.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.9.0`, `cc-do@1.6.7`, `cc-check@1.11.1`, `cc-act@1.8.8`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.9.2`, `cc-do@1.6.8`, `cc-check@1.11.2`, `cc-act@1.8.9`
 
 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/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.9.0`
+- CC-Plan skill version: `3.9.2`
 - Work branch: `REQ/001-copy-invite-link`
 - Requirement ID: `REQ-001`
 - Design mode: `tiny-design`

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json

@@ -6,7 +6,7 @@
   "requirementId": "REQ-001",
   "requirementVersion": "REQ-001.v1",
   "planningMeta": {
-    "reqPlanSkillVersion": "3.9.0",
+    "reqPlanSkillVersion": "3.9.2",
     "designVersion": "design.v1",
     "workBranch": "REQ/001-copy-invite-link",
     "approvedAt": "2026-04-15T10:05:00.000Z",

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

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

package/docs/guides/artifact-contract.md

@@ -1,6 +1,9 @@
 # Artifact Contract
 
 cc-devflow artifacts follow two rules: progressive disclosure and one state owner.
+Machine JSON has a third rule: it is CLI-owned. Agents write the human contract
+in `planning/tasks.md`, then run `cc-devflow task-contract compile` / `validate`;
+they must not handwrite `task-manifest.json` or `change-meta.json`.
 
 ## Progressive Disclosure
 
@@ -32,6 +35,7 @@ If a field has no clear opener and no downstream consumer, remove it.
 - Derived fields must be described as derived/cache and must be recomputable.
 - A skill must not create a new status field unless it also names the owner, lifecycle, projection readers, and validation gate.
 - Task manifests must not duplicate PRD narrative, review-loop prose, source-trust details, completion shell commands, roadmap progress, or spec sync status.
+- Task manifests and change metadata must be generated or refreshed by CLI/template tooling, not manually edited as process notes.
 - Project postmortems must cite stronger owner artifacts and Git evidence; they do not own roadmap progress, task status, review verdicts, or spec sync state.
 
 ## Required Check

package/docs/guides/getting-started.md

@@ -87,8 +87,8 @@ Typical outputs:
 
 - `cc-roadmap` writes `devflow/roadmap.json` as the editable roadmap truth, then generates `devflow/ROADMAP.md` and deprecated `devflow/BACKLOG.md`
 - `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
-- `cc-plan` writes `planning/tasks.md#Contract Summary`, CLI-generated `task-manifest.json`, and `change-meta.json`
-- `cc-investigate` writes `planning/tasks.md#Root Cause Contract`, CLI-generated `task-manifest.json`, and `change-meta.json`
+- `cc-plan` writes `planning/tasks.md#Contract Summary`, then CLI-generates `task-manifest.json` and `change-meta.json`
+- `cc-investigate` writes `planning/tasks.md#Root Cause Contract`, then CLI-generates `task-manifest.json` and `change-meta.json`
 - `cc-review` writes `review-ledger.jsonl`, optional `review-findings.json`, and Markdown reports only when rendered on demand
 - `cc-check` writes `report-card.json`
 - `cc-act` writes exactly one final handoff file: `handoff/pr-brief.md`, `handoff/resume-index.md`, or `handoff/release-note.md`
@@ -98,7 +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 `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 under each `devflow/changes/<change>/`. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
+- Keep 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 under each `devflow/changes/<change>/`. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
+- Machine JSON is CLI-owned: run `cc-devflow task-contract compile` / `validate`; do not handwrite `task-manifest.json` or `change-meta.json`.
 - 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

@@ -87,8 +87,8 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 
 - `cc-roadmap` 产出可编辑真相 `devflow/roadmap.json`，再生成 `devflow/ROADMAP.md` 和 deprecated `devflow/BACKLOG.md`
 - `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
-- `cc-plan` 产出 `planning/tasks.md#Contract Summary`、CLI 生成的 `task-manifest.json` 和 `change-meta.json`
-- `cc-investigate` 产出 `planning/tasks.md#Root Cause Contract`、CLI 生成的 `task-manifest.json` 和 `change-meta.json`
+- `cc-plan` 产出 `planning/tasks.md#Contract Summary`，再由 CLI 生成 `task-manifest.json` 和 `change-meta.json`
+- `cc-investigate` 产出 `planning/tasks.md#Root Cause Contract`，再由 CLI 生成 `task-manifest.json` 和 `change-meta.json`
 - `cc-review` 产出 `review-ledger.jsonl`、可选 `review-findings.json`，Markdown 报告只在需要时按需渲染
 - `cc-check` 产出 `report-card.json`
 - `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
@@ -97,7 +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>/`：变更真相，保留 `change-meta.json`、`planning/tasks.md`、CLI 生成的 `task-manifest.json`、review ledger / findings 记录、debug / failed 的可选 CLI 日志、`report-card.json` 和唯一的最终 handoff 文件。不要生成任务级 `context.md`、`checkpoint.json` 或 AI 手写过程文件。
+- `devflow/changes/<change>/`：变更真相，保留 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` 或 AI 手写过程文件。
+- 机器态 JSON 归 CLI 所有：运行 `cc-devflow task-contract compile` / `validate`；不要手写 `task-manifest.json` 或 `change-meta.json`。
 - 历史 `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

@@ -11,7 +11,7 @@ Default human-authored Markdown:
 
 - `planning/tasks.md`
 
-Default machine-owned records:
+Default CLI-owned machine records:
 
 - `change-meta.json`
 - `planning/task-manifest.json`
@@ -34,8 +34,8 @@ Feature and scope changes use:
 
 `Contract Summary` owns the frozen human-readable plan: user story, non-negotiable
 constraints, decisions that must not be reopened, task slices, and verification
-expectations. The task manifest is generated or validated by CLI tooling and owns
-machine-readable task status.
+expectations. `task-manifest.json` and `change-meta.json` must be generated or
+updated by `cc-devflow task-contract compile`; agents must not handwrite them.
 
 ## Bug Investigations
 
@@ -48,6 +48,8 @@ Bug, regression, and unexpected-behavior work uses:
 `Root Cause Contract` owns the symptom, reproduction evidence, confirmed cause,
 rejected near-causes, repair boundary, and task handoff. `cc-do` should implement
 from that frozen contract instead of reopening investigation during execution.
+`task-manifest.json` and `change-meta.json` must be generated or updated by
+`cc-devflow task-contract compile`; agents must not handwrite them.
 
 ## Review Records
 
@@ -90,6 +92,7 @@ them by default. When migrating old work, fold feature-plan truth into
 Validate one change:
 
 ```bash
+npx cc-devflow task-contract compile --change REQ-001 --change-key REQ-001-copy-invite-link
 npx cc-devflow task-contract validate --change REQ-001 --change-key REQ-001-copy-invite-link
 ```
 
@@ -111,6 +114,16 @@ The package-level verification command also includes artifact validation:
 npm run verify
 ```
 
+Skill entrypoints have a separate context budget:
+
+```bash
+npm run benchmark:skills
+```
+
+Keep `SKILL.md` files as thin entry contracts. Move low-frequency planning,
+review, and recovery details behind `PLAYBOOK.md` or `references/*` so agents
+open them only when the matching escalation condition appears.
+
 ## Authoring Rule
 
 Before adding a durable file under `devflow/changes/<change-key>/`, answer:
@@ -119,5 +132,6 @@ Before adding a durable file under `devflow/changes/<change-key>/`, answer:
 2. Which state does it own that no existing artifact owns?
 3. Which command fails if it drifts?
 
-If those answers are unclear, keep the information in `planning/tasks.md`, a
-machine record, or ephemeral workspace scratch instead.
+If those answers are unclear, keep the information in `planning/tasks.md` or
+ephemeral workspace scratch. Machine JSON belongs to the CLI/compiler path, not
+manual agent authoring.

package/lib/skill-runtime/__tests__/benchmark-skills.test.js

@@ -0,0 +1,109 @@
+/**
+ * [INPUT]: 依赖 scripts/benchmark-skills.js 导出的 runBenchmarkSkills 和临时 skill fixture。
+ * [OUTPUT]: 验证 benchmark:skills 对 SKILL.md 入口体积执行 byte/line 预算。
+ * [POS]: skill 入口瘦身基准的 Red/Green 证据。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { runBenchmarkSkills } = require('../../../scripts/benchmark-skills');
+
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const BENCHMARK_SCRIPT = path.join(REPO_ROOT, 'scripts', 'benchmark-skills.js');
+
+function writeSkill(repoRoot, skillName, body) {
+  const filePath = path.join(repoRoot, '.claude', 'skills', skillName, 'SKILL.md');
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, body);
+}
+
+function skillBody({ version = '1.0.0', filler = '' } = {}) {
+  return [
+    '---',
+    'name: cc-plan',
+    `version: ${version}`,
+    'description: fixture',
+    '---',
+    '',
+    '# Fixture',
+    '',
+    'Thin entrypoint.',
+    filler
+  ].join('\n');
+}
+
+function investigateSkillBody({ filler = '' } = {}) {
+  return skillBody().replace('name: cc-plan', 'name: cc-investigate') + filler;
+}
+
+describe('benchmark:skills', () => {
+  let repoRoot;
+
+  beforeEach(() => {
+    repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-benchmark-skills-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('passes when cc-plan stays under the thin entrypoint budget', () => {
+    writeSkill(repoRoot, 'cc-plan', skillBody());
+
+    const result = runBenchmarkSkills(repoRoot);
+
+    expect(result.code).toBe(0);
+    expect(result.rows[0]).toMatchObject({
+      skill: 'cc-plan',
+      max_bytes: 16000,
+      max_lines: 360,
+      correctness_pass: true
+    });
+  });
+
+  test('passes when cc-investigate stays under the thin entrypoint budget', () => {
+    writeSkill(repoRoot, 'cc-investigate', investigateSkillBody());
+
+    const result = runBenchmarkSkills(repoRoot);
+
+    expect(result.rows[0]).toMatchObject({
+      skill: 'cc-investigate',
+      max_bytes: 16000,
+      max_lines: 360,
+      correctness_pass: true
+    });
+  });
+
+  test('exits 1 when cc-plan grows past the byte budget', () => {
+    writeSkill(repoRoot, 'cc-plan', skillBody({ filler: 'x'.repeat(17000) }));
+
+    const result = runBenchmarkSkills(repoRoot);
+
+    expect(result.code).toBe(1);
+    expect(result.rows[0]).toMatchObject({
+      skill: 'cc-plan',
+      correctness_pass: false,
+      note: 'skill entrypoint exceeds context budget'
+    });
+  });
+
+  test('CLI prints stdout JSON array', () => {
+    writeSkill(repoRoot, 'cc-plan', skillBody());
+
+    const result = spawnSync(process.execPath, [BENCHMARK_SCRIPT, repoRoot], { encoding: 'utf8' });
+    const rows = JSON.parse(result.stdout);
+
+    expect(result.status).toBe(0);
+    expect(Array.isArray(rows)).toBe(true);
+    expect(rows[0]).toHaveProperty('estimated_tokens');
+  });
+
+  test('package.json exposes npm run benchmark:skills', () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    expect(pkg.scripts['benchmark:skills']).toBe('node scripts/benchmark-skills.js');
+  });
+});