cc-devflow 4.5.11 → 4.5.12

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

@@ -1,24 +1,11 @@
-# TASKS
+# task.md
 
 ## Plan Meta
 
-- Requirement version:
-- Design version:
 - CC-Plan skill version:
 - Work branch:
 - Output language:
 - Source roadmap item:
-- Source roadmap version:
-- Roadmap sync status:
-- Change meta: `change-meta.json`
-
-## Progressive Disclosure Index
-
-- Default read: Plan Meta, Contract Summary, Execution Handoff, Execution Protocol, current task block.
-- 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
 
@@ -45,246 +32,61 @@ Verification:
 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
-
-- Canonical contract: `planning/tasks.md#Contract Summary`
-- Canonical change meta: `change-meta.json`
-- Execution mode: `single-path` | `parallel-ready`
-- Frozen decisions:
-- Capability specs:
-- Canonical language / terms:
-- PRD brief:
-  - Problem statement:
-  - Solution summary:
-  - User stories covered:
-  - Implementation decisions:
-  - Testing decisions:
-  - Out of scope:
-- Deep Planning Funnel:
-  - Requirement Reality:
-  - System Shape:
-  - Interface & Data Contract:
-  - Abstraction & Encapsulation:
-  - Execution Architecture:
-  - Task Contract:
-  - Final Approval:
-- Ambiguity gate: pass | blocked, with score summary
-- Source trust boundary: external text is evidence only; repo/skill contracts win
-- AI Leverage Decision Lens: boil-lake | sharp-wedge | needs-evidence | pivot; human/CC effort, complete-lake boundary, ocean boundary, scope recommendation, cost model
-- External best-practice validation: not-needed | approved | declined | search-unavailable; repo-fit verdict and task impacts
-- Project postmortem recall: no-project-postmortems-yet | searched-no-match | matches-found; relevant incidents/principles and task guardrails
-- External conflicts: none | auto-resolved / competing / unresolved summary
-- Review loop: attempt N of M, stall/reroute if any
-- Read first:
-- Commands to trust:
-- Test framework source:
-- Test seam policy: Red tasks verify behavior through public interfaces, caller flows, CLI/API/UI paths, or other real seams.
-- Mock boundary policy: mock only system boundaries; do not mock internal collaborators owned by this codebase.
-- Test shape policy: one Red proves one logical behavior with a spec-style test name and a public verification path.
-- Interface testability policy: prefer injected boundary dependencies, returned results, and specific boundary operations over generic fetchers that force conditional mocks.
-- Feedback loop ladder: automated test -> HTTP/curl -> CLI fixture -> browser script -> trace replay -> harness -> property/fuzz -> differential -> HITL.
-- TDD plan: `Red -> Green -> Refactor`
-- Tracer bullet plan: one observable behavior at a time; no horizontal "all tests first, all code later" slice
-- TDD exceptions: none | list exception reason, risk, replacement evidence, follow-up
-- Regression tests: required | not applicable, with reason
-- Do not re-decide:
-- Parallel boundaries:
-
-> 顶部 handoff 只保留执行者必须知道的现实，不重复讲背景故事。
-
 ## Execution Protocol
 
-ClaudeCode / Codex 执行本计划时，必须把本文件当成任务模板合同，而不是普通 TODO 列表。
+ClaudeCode / Codex 执行本计划时，必须把 `task.md` 当成唯一任务合同。
 
-- Template source: `assets/TASKS_TEMPLATE.md`
-- Context index first: run `cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact` before opening deep sections; use `packetOnly` plus `mustNotForget` first, verify `sourceHashes`, open `defaultOpen` refs only when needed, and reserve `deepOpen` for matching `openWhen.conditions`.
-- Task selection: read `planning/task-manifest.json.currentTaskId`; if empty, run the ready-task selector before choosing work.
-- Task block rule: read the full task block before coding; title-only execution is invalid.
-- Contract sync rule: every task must inherit one row from Task Contract Matrix; if the matrix lacks source funnel rounds, interface/data contract, do-not-re-decide items, or artifact updates, return to `planning/tasks.md#Contract Summary` before coding.
-- Completion rule: after verification and review gates pass, run the completion script; do not manually edit checkbox, status, or `currentTaskId`.
-- Completion failure: if the script fails, fix the missing review / dependency evidence and rerun it. Do not bypass it by editing JSON or Markdown.
-- Postmortem recall rule: before each task, search `devflow/postmortems` with the task's touched files, capability, failure class, and model-risk terms; apply relevant reminders to the work. Do not generate no-match process files.
-- Runtime file ban: do not generate `execution/tasks/<task-id>/context.md`, `checkpoint.json`, review markdown, or any AI-written process file. Recovery reads code, Git, `planning/tasks.md`, `planning/task-manifest.json`, and CLI logs only.
+- CLI resolver: all workflow commands must run through `.claude/skills/cc-dev/scripts/resolve-cc-devflow.sh` or `.codex/skills/cc-dev/scripts/resolve-cc-devflow.sh`; if it cannot prove `query workflow-context` and `next-change-key`, stop blocked.
+- Task selection: use `scripts/select-ready-tasks.sh --tasks devflow/changes/<change-key>/task.md`.
+- Completion: after Red/Green/Refactor evidence and review pass, run `scripts/mark-task-complete.sh --tasks devflow/changes/<change-key>/task.md --task <task-id>`.
+- Stage commit rule: when PDCA or IDCA finishes in the current environment, commit the completed stage to Git.
+- Runtime file ban: do not generate process files beyond this `task.md`.
 
 ```bash
-cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact
+DEVFLOW=".claude/skills/cc-dev/scripts/resolve-cc-devflow.sh"
+if [[ ! -f "$DEVFLOW" && -f ".codex/skills/cc-dev/scripts/resolve-cc-devflow.sh" ]]; then
+  DEVFLOW=".codex/skills/cc-dev/scripts/resolve-cc-devflow.sh"
+fi
+bash "$DEVFLOW" require query workflow-context next-change-key
+bash "$DEVFLOW" query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact
 SCRIPT_ROOT=".claude/skills/cc-do/scripts"
 if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then
   SCRIPT_ROOT=".codex/skills/cc-do/scripts"
 fi
-bash "$SCRIPT_ROOT/select-ready-tasks.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json
-bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task <task-id>
+bash "$SCRIPT_ROOT/select-ready-tasks.sh" --tasks devflow/changes/<change-key>/task.md
+bash "$SCRIPT_ROOT/mark-task-complete.sh" --tasks devflow/changes/<change-key>/task.md --task <task-id>
 ```
 
-## Implementation Surface Map
-
-| Surface | Responsibility | Tasks | Coupling risk |
-|---------|----------------|-------|---------------|
-|  |  |  |  |
-
-> 这张表是执行边界，不是装饰。任务拆分必须沿着这些职责走，不能让 `cc-do` 临场重切文件归属。
-
-## Tracer Bullet Map
-
-| Slice | Observable behavior | Spec-style test name | Public test seam | Public verification path | Feedback loop | Red task | Green task | Refactor / evidence | Why vertical |
-|-------|---------------------|----------------------|------------------|--------------------------|---------------|----------|------------|---------------------|--------------|
-| Slice 1 |  |  |  |  | automated test | T001 | T002 | T005 |  |
-
-> 每个 slice 必须能独立证明一个端到端行为，不要按“只改数据层 / 只改 UI 层”横切。
-
 ## Task Contract Matrix
 
-| Task | Source funnel rounds | User / edge story | Interface / method | Key fields | File owner / responsibility | Do not re-decide | Artifact updates | Verification evidence |
-|------|----------------------|-------------------|--------------------|------------|-----------------------------|------------------|------------------|-----------------------|
-| T001 | Requirement Reality; Interface & Data Contract; Task Contract | US-001 / US-EDGE-001 |  |  |  |  | test file only | failing output |
-
-> 这张表是 task block 的来源映射。每个 task 必须能追溯到已经确认的 funnel round，且明确哪些设计点不允许 `cc-do` 重新发明。
+| Task | User / edge story | Interface / method | File owner / responsibility | Do not re-decide | Verification evidence |
+|------|-------------------|--------------------|-----------------------------|------------------|-----------------------|
+| T001 | US-001 / US-EDGE-001 |  | tests own behavior proof | public seam | failing output |
 
 ## Phase 1: Foundation
 
 - [ ] T001 [TEST] Write the first failing test (dependsOn:none) `path/to/test`
   Goal: 证明当前行为还没实现，必须先看到失败。
-  Source funnel rounds: Requirement Reality; Interface & Data Contract; Task Contract.
-  Contract: user story `US-001`; edge story `US-EDGE-001`; file responsibility `tests own behavior proof`; method/interface `<public seam>`; key fields `<field list>`; input/output `<contract>`; failure path `<expected missing behavior>`; AFK/HITL `AFK`.
-  Do not re-decide: target behavior, public seam, key fields, allowed mock boundary.
-  Artifact updates: `path/to/test`; no production files in Red.
+  Contract: user story `US-001`; method/interface `<public seam>`; input/output `<contract>`.
+  Do not re-decide: target behavior, public seam, allowed mock boundary.
   TDD phase: red
   Files: `path/to/test`
-  Read first: `design.md`, `tasks.md`
-  Project postmortem search: `rg -n "<test seam|capability|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
+  Read first: `task.md`
   Verification: `npm test -- path/to/test`
   Evidence: failing output
-  Completion: after failing evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T001`; do not hand-edit status.
-  Coverage: unit / integration / e2e / eval; regression: yes / no
-  Spec-style test name: 测试名像规格说明，描述可观察行为
-  One logical behavior: yes / no
-  Test seam: public interface / caller flow / CLI / API / UI / trace replay / harness
-  Public verification path: 从同一公共入口或用户可见路径读回结果；除非 DB / filesystem 本身是被测边界，不绕过接口侧查
-  Behavior asserted: 描述用户或调用方可观察行为，不描述内部实现步骤
-  Allowed mocks: none / external API / time / randomness / filesystem / database boundary
-  Test quality guard: no private methods, no internal call-count assertions, no internal collaborator mocks, no broad bulk Red
-  Vertical slice: Slice 1
-  Ready when: 没有上游依赖，且测试路径已经确定
+  Completion: after failing evidence exists, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --tasks devflow/changes/<change-key>/task.md --task T001`.
+  Public verification path: 从公共入口或用户可见路径读回结果。
+  Ready when: 没有上游依赖，且测试路径已经确定。
 
 - [ ] T002 [IMPL] Make the first test pass (dependsOn:T001) `path/to/file`
   Goal: 用最小实现让 T001 转绿。
-  Source funnel rounds: System Shape; Abstraction & Encapsulation; Execution Architecture; Task Contract.
-  Contract: user story `US-001`; file responsibility `<module responsibility>`; method/interface `<method or operation>`; key fields `<field list>`; input/output `<contract>`; failure path `<rescue or error behavior>`; AFK/HITL `AFK`.
-  Do not re-decide: file ownership, method shape, key fields, error shape, Green minimality boundary.
-  Artifact updates: `path/to/file`; update tests only if the approved public seam changes.
+  Contract: user story `US-001`; method/interface `<method or operation>`; input/output `<contract>`.
+  Do not re-decide: file ownership, method shape, error shape, Green minimality boundary.
   TDD phase: green
   Files: `path/to/file`
-  Read first: `design.md`, `path/to/test`
-  Project postmortem search: `rg -n "<implementation surface|module|failure-class|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
+  Read first: `task.md`, `path/to/test`
   Verification: `npm test -- path/to/test`
   Evidence: passing output + Git diff
-  Completion: after green evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T002`; do not hand-edit status.
-  Green minimality guard: 只写当前红灯要求的最小实现，不预铺未来行为、分支或 API
-  Vertical slice: Slice 1
-  Ready when: T001 已经见红，且当前 touched files 不和其他并行任务冲突
-
-## Phase 2: Build
-
-- [ ] T003 [P] [TEST] Add another independent failing test (dependsOn:T002) `path/to/other.test`
-  Goal: 为独立行为补红灯。
-  Source funnel rounds: Requirement Reality; Interface & Data Contract; Task Contract.
-  Contract: user story `US-002`; edge story `US-EDGE-002`; file responsibility `tests own behavior proof`; method/interface `<public seam>`; key fields `<field list>`; input/output `<contract>`; failure path `<expected missing behavior>`; AFK/HITL `AFK`.
-  Do not re-decide: behavior boundary, public seam, key fields, allowed mock boundary.
-  Artifact updates: `path/to/other.test`; no production files in Red.
-  TDD phase: red
-  Files: `path/to/other.test`
-  Read first: `design.md`, `tasks.md`
-  Project postmortem search: `rg -n "<test seam|capability|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
-  Verification: `npm test -- path/to/other.test`
-  Evidence: failing output
-  Completion: after failing evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T003`; do not hand-edit status.
-  Coverage: unit / integration / e2e / eval; regression: yes / no
-  Spec-style test name: 测试名像规格说明，描述可观察行为
-  One logical behavior: yes / no
-  Test seam: public interface / caller flow / CLI / API / UI / trace replay / harness
-  Public verification path: 从同一公共入口或用户可见路径读回结果；除非 DB / filesystem 本身是被测边界，不绕过接口侧查
-  Behavior asserted: 描述用户或调用方可观察行为，不描述内部实现步骤
-  Allowed mocks: none / external API / time / randomness / filesystem / database boundary
-  Test quality guard: no private methods, no internal call-count assertions, no internal collaborator mocks, no broad bulk Red
-  Vertical slice: Slice 2
-  Ready when: T002 完成，且该测试覆盖的是独立行为
-
-- [ ] T004 [P] [IMPL] Make the independent test pass (dependsOn:T003) `path/to/other-file`
-  Goal: 用最小实现让 T003 转绿，并保留重构空间。
-  Source funnel rounds: System Shape; Abstraction & Encapsulation; Execution Architecture; Task Contract.
-  Contract: user story `US-002`; file responsibility `<module responsibility>`; method/interface `<method or operation>`; key fields `<field list>`; input/output `<contract>`; failure path `<rescue or error behavior>`; AFK/HITL `AFK`.
-  Do not re-decide: module ownership, method shape, key fields, Green minimality boundary.
-  Artifact updates: `path/to/other-file`; preserve public seam from T003.
-  TDD phase: green
-  Files: `path/to/other-file`
-  Read first: `design.md`, `path/to/other.test`
-  Project postmortem search: `rg -n "<implementation surface|module|failure-class|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
-  Verification: `npm test -- path/to/other.test`
-  Evidence: passing output + review notes
-  Completion: after green evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T004`; do not hand-edit status.
-  Green minimality guard: 只写当前红灯要求的最小实现，不预铺未来行为、分支或 API
-  Vertical slice: Slice 2
-  Ready when: T003 已经见红，且文件触点与其他 `[P]` 任务不冲突
-
-## Phase 3: Verify
-
-- [ ] T005 [REFACTOR] Simplify after green evidence (dependsOn:T002,T004) `path/to/file`
-  Goal: 在所有相关测试已绿后清理重复、命名、结构和坏味道。
-  Source funnel rounds: Abstraction & Encapsulation; Execution Architecture; Task Contract.
-  Contract: user story `US-001/US-002`; file responsibility `<module responsibility>`; method/interface `<public surface stays unchanged>`; key fields `<no contract drift>`; input/output `<unchanged>`; failure path `<green tests must still cover>`; AFK/HITL `AFK`.
-  Do not re-decide: public interface, key fields, user-visible behavior, scope boundary.
-  Artifact updates: implementation files only; update tests only to remove implementation coupling.
-  TDD phase: refactor
-  Files: `path/to/file`
-  Read first: `design.md`, green test outputs
-  Project postmortem search: `rg -n "<refactor candidate|code smell|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
-  Verification: `npm test -- path/to/test path/to/other.test`
-  Evidence: refactor diff + repeated green output
-  Completion: after refactor evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T005`; do not hand-edit status.
-  Refactor candidates: duplication / long method / shallow module / feature envy / primitive obsession / naming / >3 nesting / newly exposed old code smell
-  Ready when: 对应 Red/Green 任务都已完成，且清理不会扩大 scope
-
-- [ ] T006 Run checks and collect evidence (dependsOn:T005) `command or file`
-  Goal: 为 `cc-check` 准备新鲜证据。
-  Source funnel rounds: Execution Architecture; Task Contract; Final Approval.
-  Contract: user story `all planned stories`; file responsibility `verification evidence`; method/interface `all changed public seams`; key fields `all contract fields`; input/output `not applicable`; failure path `gate failure blocks completion`; AFK/HITL `AFK`.
-  Do not re-decide: scope, test framework, gate set, completion protocol.
-  Artifact updates: review evidence only; no behavior changes and no execution process files.
-  TDD phase: evidence
-  Files: `command or file`
-  Read first: `tasks.md`, `task-manifest.json`
-  Project postmortem search: `rg -n "<verification|release|tooling|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
-  Verification: `npm test && npm run lint`
-  Evidence: gate output
-  Completion: after gate evidence and required review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T006`; do not hand-edit status.
-  Ready when: 当前 requirement 的实现任务都已收口
-
-> `[P]` 只表示“依赖满足后有资格并行”，不表示可以无脑同时开发。
-
-## Task Quality Bar
-
-一个好的 task block 至少让执行者立刻知道：
-
-- 现在为什么轮到它做
-- 做完后现实会发生什么变化
-- 用哪条命令证明它完成
-- 要留下什么证据给 `cc-check`
-- 它处于 Red、Green、Refactor，还是明确的 TDD exception
-- 它覆盖哪条 user story 或 edge / recovery story
-- 它继承了 Deep Planning Funnel 里确认的哪个接口、方法、字段、分类、输入输出和失败路径
-- 它来自哪几轮 funnel，哪些设计点不允许重决策，哪些 artifact 可以改、哪些不能改
-- 测试框架依据来自哪里，回归测试是否被明确处理
-- Red task 通过哪个公共 seam 证明行为缺失，允许 mock 的边界是什么
-- Red task 的测试名是否像规格，一个测试是否只证明一个逻辑行为，结果是否从公共入口读回
-- Green task 如何保证只写当前红灯要求的最小代码
-- Refactor task 要清理哪些具体坏味道，且只在相关测试已绿后执行
-- 测试是否会在内部重构后继续成立，而不是绑定私有函数、调用次数或临时结构
-- 它属于哪个 tracer bullet 垂直切片，完成后哪个可观察行为被证明
-- 它完成后要运行哪条 `mark-task-complete.sh` 命令，以及为什么不能手工改状态
-- 开工前查过哪些项目尸检报告，相关原则如何转成当前 task guardrail
+  Completion: after green evidence exists, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --tasks devflow/changes/<change-key>/task.md --task T002`.
+  Public verification path: same as T001.
+  Ready when: T001 has failing evidence.

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

@@ -2,167 +2,30 @@
 
 ## Hard Rules
 
-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. 一次只推进一个澄清问题，不允许问题轰炸。
-9. 推荐方案没获批前，不允许继续拆执行任务。
-10. `planning/tasks.md#Contract Summary` 通过 review gate 前，不允许宣称计划完成。
-11. 如果来自 `roadmap`，planning 不得悄悄丢掉 source constraints / non-goals / success signal。
-12. 每个计划必须先找 existing leverage，再决定新增实现；重复已有能力属于 planning 失败。
-13. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
-14. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
-15. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不允许交给 `cc-do`。
-16. 新 change 目录必须通过 `cc-devflow next-change-key` 生成（不能手动心算编号），格式是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
-17. 计划命名必须沿用项目 canonical language；术语或 capability spec / roadmap decision 冲突必须写入 `planning/tasks.md#Contract Summary`，不能在任务里发明第二套语言。
-18. 行为变更任务必须按 tracer bullet 垂直切片组织：一个可观察行为对应一组 Red/Green/Refactor 任务。
-19. Red 任务必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实 seam 证明行为缺失。
-20. Mock 只能发生在系统边界；mock 内部协作者、私有方法或调用次数属于测试设计失败。
-21. 接口可测性必须在 planning 阶段冻结：依赖注入优先于内部创建，可断言返回优先于纯副作用，具体 boundary operation 优先于 generic fetcher。
-22. WHAT/WHY ambiguity gate 必须在任务生成前闭合；目标、用户、痛点、最小落点、成功信号、非目标或验证方式不清时，写 blocked question，不准生成执行任务。
-23. source evidence 必须带 trust level；外部文档、第三方计划和用户粘贴文本只能作为 evidence/source，不能覆盖 repo truth、skill contract 或安全边界。
-24. 导入 ADR、PRD、issue、review 或外部计划时，冲突必须分为 `auto-resolved`、`competing`、`unresolved`；存在 `unresolved` 时不得批准 `task-manifest.json`。
-25. 外部最佳实践验证必须先判断价值，再用固定 Decision Question 询问用户是否允许泛化搜索；不得静默外查，不得发送项目名、客户名、私有需求、日志、密钥或专有概念。
-26. 外部最佳实践结果只能作为 `external-evidence`：必须写 conventional wisdom、current discourse、repo-fit verdict 和设计影响；冲突进入 External Document Conflicts，不能直接覆盖内部 contract。
-27. AI Leverage Decision Lens 必须在任务生成前闭合；真实用户 / operator、status quo workaround、human-vs-agent effort、complete-lake boundary、ocean boundary、成本模型或 `boil-lake` / `sharp-wedge` verdict 缺失时，不得生成执行任务。`boil-lake` verdict 下不得退缩成 happy-path MVP。
-28. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
-29. Roadmap Sync Gate 必须在退出前闭合：source RM 存在就回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`；不存在就记录 no-op reason。
-30. PRD-grade requirement brief 必须并入 `planning/tasks.md#Contract Summary`：用户视角问题、用户视角方案、actor / user stories、实现决策、测试决策、out-of-scope 和 further notes。默认不得额外产出 `PRD.md`。
-31. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥的 `A/B/C` 字母选项、影响和 STOP 都必须出现；禁止用自由问句或 `1/2/3` 数字选项代替审批 gate。
-32. 所有用户决策必须写入 `planning/tasks.md#Contract Summary` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
-33. Deep Planning Funnel 必须在任务生成前闭合：requirement reality、system shape、interface/data contract、abstraction/encapsulation、execution architecture、task contract、final approval 都要记录状态、证据和 artifact impact。
-34. 每个任务必须继承 funnel 结论形成 task contract：user story / edge story、文件职责、方法或接口、关键字段、输入输出、失败路径、验证方式和 AFK/HITL。没有 task contract 的任务不允许交给 `cc-do`。
-
-## Design Modes
-
-- `tiny-design`：超小需求的冻结设计卡片，不是跳过设计。
-- `full-design`：涉及跨模块、复杂数据流、迁移或高风险约束的完整设计。
-
-默认优先 `tiny-design`，但一旦需要解释复杂边界，就升级到 `full-design`。
-
-## Placeholder Ban
-
-- TODO later
-- implement later
-- handle edge cases
-- write tests later
-- similar to task N
-- TBD
-- 待定
-- 之后再补
-- 后面再想
-
-## Task Fields
-
-每个任务至少写清：
-
-- 目标
-- source funnel rounds
-- 对应 user story / edge story
-- 文件职责
-- 方法或接口
-- 关键字段
-- 输入输出
-- 失败路径
-- AFK / HITL
-- do-not-re-decide items
-- artifact updates
-- TDD phase：`red` / `green` / `refactor` / `exception`
-- Vertical slice / tracer bullet
-- Spec-style test name
-- One logical behavior
-- Test seam / public interface
-- Public verification path
-- Behavior asserted
-- Mock boundary
-- Feedback loop type
-- Green minimality guard
-- Refactor candidates
-- 涉及文件
-- 验证方式
-- 完成证据
-- Completion command：调用 `mark-task-complete.sh`，同步 `planning/task-manifest.json` 与 `planning/tasks.md`
-- Forbidden shortcuts：禁止手工改 checkbox、manifest status 或 `currentTaskId`
-
-行为变更任务必须先有 `[TEST]` 红灯任务，再有 `[IMPL]` 绿灯任务，最后有 `[REFACTOR]` 或明确 refactor gate。纯文档、纯配置、纯生成文件、throwaway prototype 可以例外，但必须写明原因、风险和替代验证。
-不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
-也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
-
-## Execution Protocol Fields
-
-`planning/tasks.md` 必须有 `Execution Protocol` 区块。`planning/task-manifest.json` 不再复制这段协议；它只保留执行图和调度状态，避免把同一条 shell 命令复制进全局 metadata 和每个 task。
-
-- task 选择来自 `currentTaskId` 或 `select-ready-tasks.sh`
-- 每个 task 必须按模板字段完整展开，不能退化成标题清单
-- 完成 task 必须调用 `mark-task-complete.sh`
-- 脚本失败时修 evidence / review gate / dependency state 后重跑，禁止手工绕过
-- 禁止规划或要求生成执行过程文件：`execution/tasks/<task-id>/context.md`、`checkpoint.json`、review markdown 或其它 AI 手写过程文件都不是默认真相源；恢复只看代码、Git、`planning/tasks.md`、`task-manifest.json` 和 CLI 自动日志。
-- completion command、required-before-completion 和 forbidden-shortcuts 写在 `planning/tasks.md` 的 task block；不得再写入 `task-manifest.json.executionProtocol` 或 `tasks[].completion`
-- `task-manifest.json` 不写顶层 `status`、`activePhase`、`sourceRoadmap` 或 `spec`；整体完成度从 `tasks[].status` 派生，phase 从任务图派生，roadmap/spec 状态从 `change-meta.json` 和 `devflow/roadmap.json` 读取。
-
-## Decision Question Fields
-
-每个需要用户判断的 gate 至少记录：
-
-- questionId：`D1` / `D2` / ...
-- gate：`planning-mode` / `ambiguity-blocker` / `external-best-practice` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
-- knownEvidence
-- recommendation
-- options：只能使用 `A` / `B` / `C` 作为 option id
-- userChoice
-- impact
-- status：`asked` / `answered` / `auto-decided`
-
-如果选项不是覆盖度差异，completeness 使用 `different-kind`，并写清不能打分的原因。
+1. `cc-plan` writes only `task.md`.
+2. Git commit records Plan completion.
+3. Clarification, approval, review notes, and execution protocol live inside `task.md`.
+4. No process file beyond `task.md`.
+5. New change keys come from `cc-devflow next-change-key`.
+6. Branch binds to the full change key before durable output.
+7. User decisions that affect scope, design, or verification are written into `task.md#Contract Summary`.
+8. Placeholder tasks are invalid.
+9. Behavior work uses tracer bullets and TDD unless an exception is recorded.
+10. Roadmap sync, when needed, happens through roadmap files and Git commit, not change metadata.
+
+## Required Task Fields
+
+- goal
+- user or edge story
+- files
+- dependencies
+- TDD phase
+- public verification path
+- verification command
+- completion evidence
+- completion command
+- commit point
 
 ## Review Gate
 
-`planning/tasks.md#Contract Summary` 至少完成：
-
-1. Placeholder scan
-2. Consistency scan
-3. Scope scan
-4. Ambiguity scan
-5. Feasibility scan
-6. Source alignment
-7. Existing leverage map
-8. Scope / complexity challenge
-9. Test diagram and failure modes
-10. Domain language / spec decision conflict scan
-11. Interface depth scan
-12. Interface testability scan
-13. Test seam / mock boundary scan
-14. Public verification path scan
-15. Tracer bullet scan
-16. Green minimality / refactor candidate scan
-17. PRD brief scan
-18. Source trust boundary scan
-19. External best-practice validation scan
-20. AI Leverage Decision Lens scan
-21. External conflict scan
-22. Ambiguity gate
-23. Bounded review loop
-23. NOT in scope
-24. Test-first readiness
-25. Decision questions recorded
-26. Final recommendation
-
-如有 UI scope，再补 design review 结论。
-如有 developer-facing scope，再补 DX review 结论。
-
-## Decision Log
-
-每个非平凡决策至少记录：
-
-- decision
-- classification：`mechanical` / `taste` / `user challenge`
-- principle：completeness / pragmatic / DRY / explicit / action
-- rationale
-- rejected alternative
-
-机械选择可以自动落盘。taste decision 和 user challenge 必须在最终 gate 里显式出现。
+Before exit, check scope, existing leverage, non-goals, ambiguity, test seam, mock boundary, and failure modes. If the plan is not executable from `task.md`, it is not done.

package/.claude/skills/cc-plan/scripts/next-change-key.sh

@@ -28,51 +28,15 @@ fi
 
 REPO_ROOT="${CWD:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 
-# 优先用本仓库 node CLI（最可靠），再用全局 cc-devflow，最后纯 bash 兜底
+# 通过共享 resolver 找到可证明支持 next-change-key 的真实 CLI。
+# 不再用 PATH 裸命令或 bash 扫目录兜底；缺 CLI 时必须 fail closed。
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CLI_JS="$SCRIPT_DIR/../../../../bin/cc-devflow-cli.js"
+RESOLVER="$SCRIPT_DIR/../../cc-dev/scripts/resolve-cc-devflow.sh"
 
-if [[ -f "$CLI_JS" ]] && command -v node >/dev/null 2>&1; then
-  node "$CLI_JS" next-change-key --prefix "$PREFIX" --description "$DESCRIPTION" --cwd "$REPO_ROOT"
-  exit $?
-fi
-
-if command -v cc-devflow >/dev/null 2>&1; then
-  cc-devflow next-change-key --prefix "$PREFIX" --description "$DESCRIPTION" --cwd "$REPO_ROOT"
-  exit $?
-fi
-
-# 纯 bash 兜底：扫描 devflow/changes/ 取 max+1
-CHANGES_DIR="$REPO_ROOT/devflow/changes"
-PREFIX_UPPER="$(echo "$PREFIX" | tr '[:lower:]' '[:upper:]')"
-
-MAX_NUM=0
-PAD_WIDTH=3
-
-if [[ -d "$CHANGES_DIR" ]]; then
-  for dir in "$CHANGES_DIR/${PREFIX_UPPER}-"*; do
-    [[ -d "$dir" ]] || continue
-    basename="$(basename "$dir")"
-    num_part="$(echo "$basename" | sed -E "s/^${PREFIX_UPPER}-([0-9]+).*/\1/")"
-    if [[ "$num_part" =~ ^[0-9]+$ ]]; then
-      num=$((10#$num_part))
-      if (( num > MAX_NUM )); then
-        MAX_NUM=$num
-      fi
-      if (( ${#num_part} > PAD_WIDTH )); then
-        PAD_WIDTH=${#num_part}
-      fi
-    fi
-  done
+if [[ ! -f "$RESOLVER" ]]; then
+  echo "Missing cc-devflow CLI resolver: $RESOLVER" >&2
+  echo "Do not compute change keys manually; install/update cc-devflow skills." >&2
+  exit 1
 fi
 
-NEXT_NUM=$((MAX_NUM + 1))
-PADDED_NUM="$(printf "%0${PAD_WIDTH}d" "$NEXT_NUM")"
-CHANGE_ID="${PREFIX_UPPER}-${PADDED_NUM}"
-
-SLUG="$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed -E 's/[[:space:]_]+/-/g; s/^-+|-+$//g')"
-[[ -z "$SLUG" ]] && SLUG="change"
-
-CHANGE_KEY="${CHANGE_ID}-${SLUG}"
-echo "$CHANGE_ID"
-echo "$CHANGE_KEY"
+bash "$RESOLVER" next-change-key --prefix "$PREFIX" --description "$DESCRIPTION" --cwd "$REPO_ROOT"

package/.claude/skills/cc-plan/scripts/parse-task-dependencies.js

@@ -3,7 +3,7 @@
 'use strict';
 
 // ------------------------------------------------------------
-// 解析 tasks.md 里的 phase / [P] / 文件触点
+// 解析 task.md 里的 phase / [P] / 文件触点
 // ------------------------------------------------------------
 
 const fs = require('fs');
@@ -57,7 +57,7 @@ function parse(content) {
 function main() {
   const file = process.argv[2];
   if (!file) {
-    console.error('Usage: parse-task-dependencies.js tasks.md');
+    console.error('Usage: parse-task-dependencies.js task.md');
     process.exit(1);
   }
 

package/.claude/skills/cc-plan/scripts/validate-scope.sh

@@ -61,7 +61,7 @@ for file in "${sources[@]}"; do
     echo "[FAIL] $file contains an empty field bullet"
     fail=1
   fi
-  if [[ "$file" != *"TASK_MANIFEST_TEMPLATE.json" ]]; then
+  if [[ "$file" != *"task template" ]]; then
     for marker in "${required_markers[@]}"; do
       if ! rg -n --fixed-strings "$marker" "$file" >/dev/null 2>&1; then
         echo "[FAIL] $file is missing marker: $marker"