cc-devflow 4.5.9 → 4.5.10

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

@@ -6,8 +6,9 @@
     "documentLanguage": ""
   },
   "planningMeta": {
-    "ccInvestigateSkillVersion": "1.4.1",
+    "ccInvestigateSkillVersion": "1.5.0",
     "analysisVersion": "analysis.v1",
+    "workBranch": "FIX/XXX-short-bug-name",
     "approvedAt": "2026-04-17T12:00:00.000Z",
     "basedOnRootCause": "Root cause sentence"
   },
@@ -35,7 +36,7 @@
         "configuration drift",
         "timing guess / flaky wait"
       ],
-      "notes": "Pattern evidence belongs in planning/analysis.md"
+      "notes": "Pattern evidence belongs in planning/tasks.md#Root Cause Contract"
     },
     "boundaryProbes": [
       {
@@ -63,7 +64,7 @@
       "symptomSite": "User-visible failure, command, UI state, log, or bad artifact",
       "firstBadState": "First field, artifact, cache entry, queue message, config, response, or memory object that becomes invalid",
       "firstBadStateEvidence": [
-        "Boundary probe or trace evidence from planning/analysis.md"
+        "Boundary probe or trace evidence from planning/tasks.md#Root Cause Contract"
       ],
       "violatedContract": "Schema, invariant, API contract, state transition, trust boundary, or timing condition violated",
       "originalTrigger": "User action, command, event, recent diff, config change, or external response that created the first bad state",

package/.claude/skills/cc-investigate/assets/{ANALYSIS_TEMPLATE.md → legacy/ANALYSIS_TEMPLATE.md}

@@ -5,6 +5,7 @@
 - Requirement version:
 - Analysis version:
 - Investigate skill version:
+- Work branch:
 - Output language:
 - Source roadmap item:
 - Source roadmap version:

package/.claude/skills/cc-investigate/references/investigation-contract.md

@@ -35,8 +35,8 @@
 
 ## Output Shape
 
-- `planning/analysis.md` 是人类真相源
-- `planning/tasks.md` 是修复 handoff
+- `planning/tasks.md#Root Cause Contract` 是人类真相源
+- `planning/tasks.md` 的 task blocks 是修复 handoff
 - `planning/task-manifest.json` 是执行真相源
 - `change-meta.json` 必须记录 roadmap sync status、spec diagnosis 和 no-op reason / updated files
 

package/.claude/skills/cc-investigate/scripts/bootstrap-analysis.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-TEMPLATE="$ROOT_DIR/assets/ANALYSIS_TEMPLATE.md"
+TEMPLATE="$ROOT_DIR/assets/legacy/ANALYSIS_TEMPLATE.md"
 REQ_DIR=""
 
 usage() {

package/.claude/skills/cc-plan/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CC-Plan Skill Changelog
 
+## v3.9.0 - 2026-05-13
+
+- collapse the default planning artifact surface to `planning/tasks.md` plus CLI-generated `task-manifest.json` and `change-meta.json`
+- move the human-authored design contract into `planning/tasks.md#Contract Summary` so `planning/design.md` is legacy fallback only
+- archive legacy design templates under `assets/legacy/` and keep new task handoffs rooted in `assets/TASKS_TEMPLATE.md`
+- ban generated execution process files from new task plans: no `context.md`, `checkpoint.json`, review markdown, or AI-written process notes under `execution/tasks`
+
+## v3.8.7 - 2026-05-13
+
+- add the Worktree Branch Contract so new `REQ` / `FIX` planning anchors detached worktrees to `REQ/<task>` or `FIX/<task>` before artifacts are written
+- treat planning on `main` / the default branch as a setup blocker instead of allowing the main checkout to accumulate feature state
+- require design, tasks, and change metadata to record the canonical work branch for downstream `cc-do`
+
+## v3.8.6 - 2026-05-12
+
+- require generated execution handoffs to start from `cc-devflow query workflow-context` so progressive disclosure is runtime-derived, not chat memory
+- make the compact context packet the default bridge from planning into `cc-do`, `cc-check`, and `cc-act`
+- keep deep planning sections available only behind explicit open conditions such as scope drift, scheduling conflict, recovery, or delivery
+
 ## v3.8.5 - 2026-05-11
 
 - add the Project Postmortem Recall Gate so plans search `devflow/postmortems` before freezing direction

package/.claude/skills/cc-plan/PLAYBOOK.md

@@ -5,8 +5,8 @@
 `roadmap -> cc-plan -> cc-do`
 
 - Enter from: an approved roadmap item, requirement, or bug that still needs design.
-- Stay in: `cc-plan` until the approved design and executable task breakdown are both frozen.
-- Exit to: `cc-do` only after `planning/design.md` is approved, `planning/tasks.md` plus `planning/task-manifest.json` are generated, and the source roadmap progress is synchronized or explicitly marked no-op.
+- Stay in: `cc-plan` until `planning/tasks.md#Contract Summary` and executable task blocks are both frozen.
+- Exit to: `cc-do` only after `planning/tasks.md` plus CLI-generated `planning/task-manifest.json` are ready, and the source roadmap progress is synchronized or explicitly marked no-op.
 - Reroute to: `roadmap` if the conversation expands back into project strategy.
 
 ## Core Rules
@@ -14,38 +14,39 @@
 1. 先读上游 handoff，再写 planning 结论。
 2. 没有证据时写 assumption，不准冒充事实。
 3. 一次只推进一个关键未知点。
-4. `planning/design.md` 和 `planning/tasks.md` 必须足够让执行者脱离当前会话继续工作。
+4. `planning/tasks.md` 必须足够让执行者脱离当前会话继续工作。
 5. 版本、来源、冻结决策必须可追踪。
 6. 机械决策自动落盘；taste decision 和 user challenge 必须显式交给用户拍板。
 7. 同 blast radius 内的完整边界优先做完，跨系统或无证据扩张才 defer。
 8. 具体执行计划默认测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不准交给 `cc-do`。
 9. 新 change 目录必须通过 `cc-devflow next-change-key --prefix REQ|FIX --description "..."` 生成，不要手动扫描或心算编号；`REQ` 和 `FIX` 各自递增；并行工作树造成同前缀同号时，完整 change key 靠描述区分；旧小写目录只读兼容，不再作为新输出。
-10. 原始需求跨多个独立子系统时，先拆回 roadmap / 多个 REQ/FIX；不要把一个大杂烩压成单个计划。
-11. `tiny-design` 仍然必须被批准，它只是短设计，不是跳过设计。
-12. 非 trivial 方案必须至少比较 `minimal viable` 和 `ideal architecture` 两种角色，小方案没有天然优先权。
-13. `full-design` 必须冻结 implementation decision horizon 和 error/rescue map，避免 `cc-do` 临场补设计。
-14. 测试框架来源、覆盖质量、测试 seam、mock 边界和回归测试必须在计划阶段写清，不准靠执行阶段猜。
-15. UI 和 developer/operator-facing 范围只在适用时触发对应 gate，不把每个计划都塞成大审查清单。
-16. 先对齐项目语言和持久决策，再命名 capability、模块、接口、测试和任务；术语冲突必须显式暴露。
-17. 行为变更按 tracer bullet 垂直切片推进，不能把任务水平切成“先测试层、再服务层、最后 UI 层”。
-18. WHAT/WHY ambiguity、外部文档冲突、source trust boundary 和 review loop 上限必须在设计 gate 内闭合；模糊需求不能靠 `cc-do` 临场解释。
-19. 退出前必须跑 Roadmap Sync Gate：`devflow/roadmap.json` 是真相源，`devflow/ROADMAP.md` 和 `devflow/BACKLOG.md` 只是投影；source RM 存在就回写，找不到才记录 no-op。
-20. PRD 的结构要吸收进 `planning/design.md`：用户视角的问题和方案、完整 user stories、实现决策、测试决策、out-of-scope 和 further notes；不要默认创建独立 `PRD.md`。
-21. 接口可测性必须在计划阶段解决：依赖尽量注入，结果尽量可返回和断言，系统边界 adapter 拆成具体操作，避免让测试用条件分支 mock 一个万能 fetcher。
-22. 需要用户判断时必须走固定 `D<N>` Decision Question：证据、推荐、2-3 个互斥的 `A/B/C` 字母选项、影响和 STOP 都要出现，答案写回 design / manifest；选项禁止用 `1/2/3`。
-23. 内部证据扫完后，判断是否需要外部最佳实践验证；需要时先问用户是否允许用泛化关键词搜索，结果只作为 `external-evidence`，不能覆盖 repo truth。
-24. 第一版设计推荐前必须跑 Deep Planning Funnel 的前四轮；任务生成前必须跑完前六轮。对话里确认过的架构、接口、字段、方法、分类和任务粒度必须进入模板产物。
+10. 分配 change key 后立刻执行 Worktree Branch Contract：detached worktree 先挂到 `REQ/<task>` 或 `FIX/<task>`；当前在 `main` / default branch 时停止，不写 planning artifacts。
+11. 原始需求跨多个独立子系统时，先拆回 roadmap / 多个 REQ/FIX；不要把一个大杂烩压成单个计划。
+12. `tiny-design` 仍然必须被批准，它只是短设计，不是跳过设计。
+13. 非 trivial 方案必须至少比较 `minimal viable` 和 `ideal architecture` 两种角色，小方案没有天然优先权。
+14. `full-design` 必须冻结 implementation decision horizon 和 error/rescue map，避免 `cc-do` 临场补设计。
+15. 测试框架来源、覆盖质量、测试 seam、mock 边界和回归测试必须在计划阶段写清，不准靠执行阶段猜。
+16. UI 和 developer/operator-facing 范围只在适用时触发对应 gate，不把每个计划都塞成大审查清单。
+17. 先对齐项目语言和持久决策，再命名 capability、模块、接口、测试和任务；术语冲突必须显式暴露。
+18. 行为变更按 tracer bullet 垂直切片推进，不能把任务水平切成“先测试层、再服务层、最后 UI 层”。
+19. WHAT/WHY ambiguity、外部文档冲突、source trust boundary 和 review loop 上限必须在设计 gate 内闭合；模糊需求不能靠 `cc-do` 临场解释。
+20. 退出前必须跑 Roadmap Sync Gate：`devflow/roadmap.json` 是真相源，`devflow/ROADMAP.md` 和 `devflow/BACKLOG.md` 只是投影；source RM 存在就回写，找不到才记录 no-op。
+21. PRD 的结构要吸收进 `planning/tasks.md#Contract Summary`：用户视角的问题和方案、完整 user stories、实现决策、测试决策、out-of-scope 和 further notes；不要默认创建独立 `PRD.md`。
+22. 接口可测性必须在计划阶段解决：依赖尽量注入，结果尽量可返回和断言，系统边界 adapter 拆成具体操作，避免让测试用条件分支 mock 一个万能 fetcher。
+23. 需要用户判断时必须走固定 `D<N>` Decision Question：证据、推荐、2-3 个互斥的 `A/B/C` 字母选项、影响和 STOP 都要出现，答案写回 design / manifest；选项禁止用 `1/2/3`。
+24. 内部证据扫完后，判断是否需要外部最佳实践验证；需要时先问用户是否允许用泛化关键词搜索，结果只作为 `external-evidence`，不能覆盖 repo truth。
+25. 第一版设计推荐前必须跑 Deep Planning Funnel 的前四轮；任务生成前必须跑完前六轮。对话里确认过的架构、接口、字段、方法、分类和任务粒度必须进入模板产物。
 
 ## Required Outputs
 
-- `planning/design.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
 - `change-meta.json`
 
 ## Local Kit
 
-- 模板全部在 `assets/`
+- 默认模板在 `assets/TASKS_TEMPLATE.md` 和 `assets/TASK_MANIFEST_TEMPLATE.json`
+- 旧设计模板在 `assets/legacy/`，只用于 legacy fallback / migration
 - 任务结构解析在 `scripts/parse-task-dependencies.js`
 - 计划边界和 placeholder 红线见 `references/planning-contract.md`
 - 变更版本时同步 `CHANGELOG.md`，必要时用 `scripts/bump-skill-version.sh`
@@ -53,13 +54,14 @@
 
 ## Planning Standard
 
-1. 一份 `planning/design.md` 讲清 clarification、方案、review 和 final gate。
-2. 一份 `planning/tasks.md` 讲清执行任务和 handoff。
+1. 一份 `planning/tasks.md#Contract Summary` 讲清 clarification、方案、review 和 final gate。
+2. 同一份 `planning/tasks.md` 讲清执行任务和 handoff。
 3. `planning/task-manifest.json` 只做机器真相源，不再重复人类叙事。
 4. 先运行 `cc-devflow next-change-key --prefix REQ|FIX --description "..."` 获取 canonical change key；不要手动扫描目录或心算编号。并行 PR 产生同号时不强制重排，完整 key 的描述承担身份区分。
-5. 推荐方案获批前，不得生成 `planning/tasks.md`。
-6. `planning/tasks.md` 之前，`planning/design.md` 内的 review gate 必须闭合。
-7. 每个任务都要写清：
+5. 立刻检查并锚定 work branch：detached worktree 创建 / 切换到 `REQ/<task>` 或 `FIX/<task>`；`main` / default branch 是 setup blocker。
+6. 推荐方案获批前，不得生成执行 task blocks。
+7. 进入任务拆分前，`planning/tasks.md#Contract Summary` 内的 review gate 必须闭合。
+8. 每个任务都要写清：
    - 目标
    - TDD phase：`red` / `green` / `refactor` / `exception`
    - dependsOn / 是否允许并行
@@ -67,40 +69,40 @@
    - 必读上下文
    - 验证方式
    - 完成证据
-8. `planning/tasks.md` 顶部必须写清 frozen decisions、commands to trust、do-not-re-decide。
-9. `planning/task-manifest.json` 必须是 `cc-do` 的真相源，而不是装饰文件。
-10. `change-meta.json` 必须记录 `roadmapSync`：status、updatedFiles、command、no-op reason 或阻塞原因。
-11. `planning/design.md` 必须包含 `Existing Leverage`、`NOT in scope`、`Failure Modes`、`Test Diagram`，除非明确说明为什么不适用。
-12. `planning/design.md` 或 `planning/tasks.md` 必须包含 implementation surface map：文件、职责、归属理由、耦合风险。
-13. `full-design` 必须包含 implementation decision horizon 和 error/rescue map；不适用时写清 N/A 理由。
-14. `planning/design.md` 必须包含 assumptions preview、ambiguity gate、source trust boundary、external best-practice validation、external conflict buckets 和 bounded review loop。
-15. `planning/design.md` 必须包含 Deep Planning Funnel：requirement reality、system shape、interface/data contract、abstraction/encapsulation、execution architecture、task contract、final approval。
-16. `planning/design.md` 必须包含 PRD-grade brief：Problem Statement、Solution、actors / user stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。
-17. `planning/design.md` 必须包含 Decision Questions：哪些问题问过、推荐项、用户选择、影响、是否已写入任务。
-18. `planning/design.md` 必须包含 External Best-Practice Validation：是否需要、是否获用户允许、泛化搜索词、来源、conventional wisdom、repo-fit verdict、设计影响和跳过原因。
-19. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
-20. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
-21. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
-22. 每个任务必须有 task contract：对应 user story / edge story、文件职责、方法或接口、关键字段、输入输出、失败路径、验证和完成脚本。
-23. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
-24. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
-25. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
-26. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
-27. Red 任务必须说明 public verification path：从同一公共接口或用户可见路径读回结果。直接查 DB / 内部状态只在该边界本身就是被测对象时允许。
-28. Green 任务必须写 minimality guard：只做当前红灯要求的最少实现，不预铺未来测试尚未要求的分支、状态或 API。
-29. Refactor 任务必须列候选坏味道：重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支，以及新代码暴露出的旧代码问题。
-30. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
-31. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
+9. `planning/tasks.md` 顶部必须写清 frozen decisions、commands to trust、do-not-re-decide。
+10. `planning/task-manifest.json` 必须是 `cc-do` 的真相源，而不是装饰文件。
+11. `change-meta.json` 必须记录 `roadmapSync`：status、updatedFiles、command、no-op reason 或阻塞原因。
+12. `planning/tasks.md#Contract Summary` 必须包含 `Existing Leverage`、`NOT in scope`、`Failure Modes`、`Test Diagram`，除非明确说明为什么不适用。
+13. `planning/tasks.md` 必须包含 implementation surface map：文件、职责、归属理由、耦合风险。
+14. `full-design` 必须包含 implementation decision horizon 和 error/rescue map；不适用时写清 N/A 理由。
+15. `planning/tasks.md#Contract Summary` 必须包含 assumptions preview、ambiguity gate、source trust boundary、external best-practice validation、external conflict buckets 和 bounded review loop。
+16. `planning/tasks.md#Contract Summary` 必须包含 Deep Planning Funnel：requirement reality、system shape、interface/data contract、abstraction/encapsulation、execution architecture、task contract、final approval。
+17. `planning/tasks.md#Contract Summary` 必须包含 PRD-grade brief：Problem Statement、Solution、actors / user stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。
+18. `planning/tasks.md#Contract Summary` 必须包含 Decision Questions：哪些问题问过、推荐项、用户选择、影响、是否已写入任务。
+19. `planning/tasks.md#Contract Summary` 必须包含 External Best-Practice Validation：是否需要、是否获用户允许、泛化搜索词、来源、conventional wisdom、repo-fit verdict、设计影响和跳过原因。
+20. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
+21. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
+22. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
+23. 每个任务必须有 task contract：对应 user story / edge story、文件职责、方法或接口、关键字段、输入输出、失败路径、验证和完成脚本。
+24. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
+25. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
+26. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
+27. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
+28. Red 任务必须说明 public verification path：从同一公共接口或用户可见路径读回结果。直接查 DB / 内部状态只在该边界本身就是被测对象时允许。
+29. Green 任务必须写 minimality guard：只做当前红灯要求的最少实现，不预铺未来测试尚未要求的分支、状态或 API。
+30. Refactor 任务必须列候选坏味道：重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支，以及新代码暴露出的旧代码问题。
+31. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
+32. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
 32. Review gate 只拦会导致实现错误、执行卡住、范围越界、验证缺失的问题；文字偏好和 nice-to-have 只能作为 advisory。
 
 ## Approval Flow
 
 1. 先写 `Source Handoff` 和 requirement framing。
 2. 跑 Deep Planning Funnel 前四轮，缺口以 blocked question 或 auto-decided evidence 处理。
-3. 在 `planning/design.md` 里记录备选方案和推荐。
+3. 在 `planning/tasks.md#Contract Summary` 里记录备选方案和推荐。
 4. 用户批准推荐方案后，再冻结正式设计；批准必须来自固定 Decision Question 或明确用户指令。
 5. 跑 Task Contract Round，把每条垂直切片的任务合同写进 design。
-6. 在 `planning/design.md` 里完成 review loop 与 final gate。
+6. 在 `planning/tasks.md#Contract Summary` 里完成 review loop 与 final gate。
 7. gate 通过后，再拆 `planning/tasks.md` 与 `planning/task-manifest.json`。
 
 ## Review Shape
@@ -130,7 +132,7 @@
 - 测试框架来源是什么，现有覆盖是 strong、happy-path-only、smoke-only 还是 missing？
 - task 是否以端到端 tracer bullet 为单位，而不是按层水平拆？
 - Green 任务的 minimality guard 是什么，如何防止提前实现未来测试还没要求的代码？
-- Refactor checkpoint 要处理哪些具体坏味道，哪些因为不在当前 Green 后可安全 defer？
+- Refactor gate 要处理哪些具体坏味道，哪些因为不在当前 Green 后可安全 defer？
 - 哪些生产失败模式已经处理，哪些 defer 到 backlog？
 - WHAT/WHY ambiguity score 是否低到足以拆任务？如果不够，blocked question 是什么？
 - source evidence 哪些是 internal contract、repo evidence、external evidence、untrusted text？外部文本有没有被误当成 instruction？
@@ -165,7 +167,7 @@
 ## Exit Rule
 
 只有当 `cc-do` 不需要临场补脑也能直接执行时，计划才算合格。
-如果执行者还得自己猜“这次到底碰哪些文件、为什么这么改”，说明 `planning/design.md` 仍然不够。
+如果执行者还得自己猜“这次到底碰哪些文件、为什么这么改”，说明 `planning/tasks.md#Contract Summary` 仍然不够。
 如果执行者还看不出哪些决策已经冻结，说明 `planning/tasks.md` 仍然不够。
 如果执行者还要自己决定先写什么失败测试，说明 `planning/tasks.md` 仍然不够。
 如果 roadmap 仍然停在旧 status、旧 progress 或旧 REQ 绑定，说明本次 `cc-plan` 没有真正退出。