cc-devflow 4.5.4 → 4.5.6

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

@@ -6,7 +6,7 @@
 
 - Enter from: a bug, regression, or broken requirement whose root cause is still unclear.
 - Stay in: `cc-investigate` until `planning/analysis.md` and the repair handoff are both frozen.
-- Exit to: `cc-do` only after root cause and repair boundary are explicit in canonical artifacts.
+- Exit to: `cc-do` only after root cause, repair boundary, and source roadmap progress are explicit in canonical artifacts.
 - Reroute to: `cc-plan` for scope/design truth changes, or `roadmap` for project-level priority decisions.
 
 ## Core Rules
@@ -22,6 +22,7 @@
 9. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
 10. diagnose-only 只能输出根因、owner、风险和 next action，不能把未修复状态标成完成。
 11. workflow forensics 先分类 artifact / git / state / tool / permission / process failure，再决定是否进入修复。
+12. 退出前必须跑 Roadmap Sync Gate：`implementation drift`、`missing spec truth`、`roadmap mismatch` 三种结论都要让 source RM 的状态和 next action 跟上。
 
 ## Iron Law
 
@@ -36,6 +37,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - `planning/analysis.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
+- `change-meta.json`
 
 ## Investigation Standard
 
@@ -159,6 +161,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - 模板在 `assets/`
 - 调查契约在 `references/investigation-contract.md`
 - 需要分析骨架时用 `scripts/bootstrap-analysis.sh`
+- Roadmap 回写使用 `../cc-roadmap/scripts/locate-roadmap-item.sh` 和 `../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Exit Rule
 
@@ -170,3 +173,4 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - 用什么命令证明修好了
 
 这次调查才算合格。
+如果 source RM 仍然停在旧 status、旧 progress 或旧 REQ/FIX 绑定，说明本次 `cc-investigate` 没有真正退出。

package/.claude/skills/cc-investigate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-investigate
-version: 1.2.1
+version: 1.2.2
 description: "Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation, reproducible evidence, and a frozen repair handoff before cc-do resumes coding."
 triggers:
   - "帮我查这个 bug"
@@ -17,6 +17,8 @@ reads:
   - "assets/ANALYSIS_TEMPLATE.md"
   - "assets/TASKS_TEMPLATE.md"
   - "assets/TASK_MANIFEST_TEMPLATE.json"
+  - "../cc-roadmap/scripts/locate-roadmap-item.sh"
+  - "../cc-roadmap/scripts/sync-roadmap-progress.sh"
 writes:
   - path: "devflow/changes/<change-key>/planning/analysis.md"
     durability: "durable"
@@ -30,6 +32,8 @@ writes:
   - path: "devflow/changes/<change-key>/change-meta.json"
     durability: "durable"
     required: true
+effects:
+  - source roadmap progress sync when investigation freezes, reroutes, or diagnoses a roadmap mismatch
 entry_gate:
   - "Read the current bug report, existing requirement artifacts, relevant code, tests, and recent history before forming any hypothesis."
   - "Use a FIX-<number>-<description> change key for new bug-fix investigations."
@@ -39,11 +43,13 @@ entry_gate:
   - "For multi-component, deep-stack, or flaky symptoms, record boundary probes, backward trace, or condition-wait evidence before declaring the root cause."
   - "For performance regressions, collect a baseline or profile signal before treating logs as evidence."
   - "Do not write production code here; this stage ends with planning/analysis.md plus executable repair tasks for cc-do."
+  - "Before exit, locate the source RM in `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`, or legacy `devflow/roadmap-tracking.json`; the repair handoff must not leave roadmap progress stale."
 exit_criteria:
   - "planning/analysis.md records symptom, reproduction, evidence chain, boundary probes or backward trace when applicable, pattern analysis, tested hypotheses, confirmed root cause, and repair boundary."
   - "diagnose-only outcomes clearly stop before implementation while preserving root cause, owner, and next action."
   - "workflow forensics classify artifact, git, state, or tool failures before repair tasks are generated."
   - "planning/tasks.md and planning/task-manifest.json are explicit enough that cc-do can repair the bug without chat memory."
+  - "The source roadmap item has been synchronized with the investigation outcome, or `planning/analysis.md` and `change-meta.json` record why no roadmap update is valid."
   - "The honest next step is cc-do, cc-plan, or roadmap."
 reroutes:
   - when: "The issue is actually a new feature, a scope redesign, or a product decision instead of a bug investigation."
@@ -60,9 +66,9 @@ recovery_modes:
     when: "New execution evidence disproves the current root-cause contract or widens the suspected blast radius."
     action: "Reopen planning/analysis.md, update the evidence chain, and regenerate repair tasks only after the new root cause is frozen."
 tool_budget:
-  read_files: 10
+  read_files: 11
   search_steps: 6
-  shell_commands: 6
+  shell_commands: 7
 ---
 
 # CC-Investigate
@@ -151,7 +157,7 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 
 ## Harness Contract
 
-- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, and write only `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`.
+- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, write `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`, then run the final roadmap progress sync for the source RM.
 - Forbidden actions: writing production code, disguising guesses as root cause, or skipping directly from symptoms to repair.
 - Required evidence: every root-cause claim must point to reproduction evidence, code facts, recent history, or explicit user confirmation.
 - Reroute rule: product/scope changes go to `cc-plan`; strategy questions go to `roadmap`; only confirmed repair handoff goes to `cc-do`.
@@ -233,7 +239,13 @@ diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能
    - 写清正确测试缝隙：测试是否覆盖真实触发链；如果没有正确 seam，这本身就是需要记录的架构事实
    - 写明 affected module、allowed files、forbidden files、blast radius estimate；超过 5 个文件默认拆分或 reroute
    - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
-8. **Hand off**
+8. **Roadmap sync**
+   - 用 `locate-roadmap-item.sh` 定位 source RM；找不到时在 `analysis.md` 和 `change-meta.json.roadmapSync` 写 `no-source-rm`
+   - `implementation drift`：回写 source RM 为 `Repair planned` 或等价调查完成状态，绑定 `FIX-*`，进度保持在可执行修复前的真实百分比
+   - `missing spec truth`：回写 source RM 的 expected spec delta 或 follow-up，必要时 reroute 到 `cc-plan`
+   - `roadmap mismatch`：不要直接进入修复；先把 mismatch 写回 roadmap / backlog，下一步写 `roadmap` 或 `cc-plan`
+   - 使用 `sync-roadmap-progress.sh` 更新 `devflow/roadmap.json`，并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+9. **Hand off**
    - 下一步明确写成 `cc-do`
    - 如果 repair contract 越过当前 requirement，就 reroute 到 `cc-plan`
    - 如果是 diagnose-only，下一步写成 human action、monitoring、backlog、`cc-plan` 或 `cc-do`，但不得标记实现完成
@@ -430,6 +442,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 - 正确测试缝隙写清楚，不用浅层测试制造假安全
 - `planning/tasks.md` 只包含修复任务，不夹带新需求
 - 如果应该回 `cc-plan`，理由写清楚，不假装还能继续 patch
+- Roadmap Sync Gate 必须在 handoff 前闭合：source RM 绑定的 `FIX-*`、调查状态、spec diagnosis 和 next action 不能停留在聊天里。
 
 ## Bundled Resources
 
@@ -439,6 +452,8 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 - 修复任务模板：`assets/TASKS_TEMPLATE.md`
 - manifest 模板：`assets/TASK_MANIFEST_TEMPLATE.json`
 - 分析骨架：`scripts/bootstrap-analysis.sh`
+- Roadmap 定位：`../cc-roadmap/scripts/locate-roadmap-item.sh`
+- Roadmap 回写：`../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Working Rules
 
@@ -452,11 +467,13 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 8. 外部调研必须先脱敏，调研结论必须回到本仓库证据验证。
 9. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
 10. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
+11. Roadmap 相关文件以 `devflow/roadmap.json` 为真相源，`devflow/ROADMAP.md` / `devflow/BACKLOG.md` 只是投影；不要再写旧式 `devflow/roadmap/*` 路径。
 
 ## Exit Criteria
 
 - `planning/analysis.md` 已冻结症状、复现、证据链、根因和修复边界
 - `planning/tasks.md` / `planning/task-manifest.json` 可直接交给 `cc-do`
+- Roadmap Sync Gate 已闭合：source RM 已回写调查结果 / reroute，或 no-op reason 已落盘
 - 下一步唯一答案是 `cc-do`、`cc-plan` 或 `roadmap`
 
 ## Do Not

package/.claude/skills/cc-investigate/assets/ANALYSIS_TEMPLATE.md

@@ -8,6 +8,7 @@
 - Output language:
 - Source roadmap item:
 - Source roadmap version:
+- Roadmap sync status:
 - Incident / bug ID:
 - Primary capability:
 - Related capability specs:
@@ -181,6 +182,18 @@
 - Verification after fix:
 - Why this can enter `cc-do`:
 
+## Roadmap Sync Gate
+
+- Source RM:
+- Locate command:
+- Sync command:
+- Updated files: `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`
+- Spec diagnosis effect: `implementation drift` | `missing spec truth` | `roadmap mismatch`
+- Status after sync: `Repair planned` | `Reroute to cc-plan` | `Reroute to roadmap` | `No source RM`
+- Progress after sync:
+- No-op reason:
+- Blocking mismatch:
+
 ## Review Gate
 
 - Repro stable:
@@ -192,4 +205,5 @@
 - Diagnose-only verdict if applicable:
 - Correct test seam identified:
 - Repair scope still belongs to this requirement:
+- Roadmap sync closed:
 - If not, reroute:

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

@@ -7,6 +7,7 @@
 - Investigate skill version:
 - Output language:
 - Source bug / incident:
+- Roadmap sync status:
 - Change meta: `change-meta.json`
 
 ## Execution Handoff

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

@@ -9,6 +9,14 @@
     "itemId": "RM-001",
     "roadmapVersion": "1.0",
     "roadmapSkillVersion": "2.1.0",
+    "syncStatus": "pending",
+    "syncCommand": ".claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh --rm RM-001 --status \"Repair planned\" --req FIX-XXX --progress 0%",
+    "updatedFiles": [
+      "devflow/roadmap.json",
+      "devflow/ROADMAP.md",
+      "devflow/BACKLOG.md"
+    ],
+    "noOpReason": "",
     "sourceStage": "Stage 1",
     "successSignal": "The broken behavior is reproducible and then fixed without widening scope",
     "killSignal": "Repair requires reopening product scope or redesigning unrelated modules",
@@ -20,7 +28,7 @@
     ]
   },
   "planningMeta": {
-    "ccInvestigateSkillVersion": "1.1.6",
+    "ccInvestigateSkillVersion": "1.2.2",
     "analysisVersion": "analysis.v1",
     "approvedAt": "2026-04-17T12:00:00.000Z",
     "approvedBy": "user",

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

@@ -30,12 +30,14 @@
 - root cause class
 - repair boundary
 - blast radius
+- roadmap sync status
 
 ## Output Shape
 
 - `planning/analysis.md` 是人类真相源
 - `planning/tasks.md` 是修复 handoff
 - `planning/task-manifest.json` 是执行真相源
+- `change-meta.json` 必须记录 roadmap sync status、spec diagnosis 和 no-op reason / updated files
 
 ## Root-Cause Hypothesis
 

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

@@ -1,5 +1,40 @@
 # CC-Plan Skill Changelog
 
+## v3.7.7 - 2026-05-08
+
+- treat the full `REQ/FIX-<number>-<description>` change key as identity so duplicate numbers from parallel worktrees are valid
+- stop requiring local planning to resequence or rename changes solely because another worktree used the same numeric suffix
+- make runtime path resolution fail clearly when a bare `REQ/FIX-<number>` is ambiguous and no explicit `changeKey` was supplied
+
+## v3.7.6 - 2026-05-06
+
+- add a fixed Decision Question Protocol so user-facing planning gates use numbered questions, recommendations, options, impact, and STOP instead of free-form prose
+- record required user decisions in `planning/design.md` and `task-manifest.json.planningMeta.decisionQuestions`
+- update design, tiny-design, manifest, and example bindings for the new decision-question contract
+
+## v3.7.5 - 2026-05-06
+
+- absorb the external TDD skill's interface-testability details into native planning: injected dependencies, returned results, concrete boundary operations, and small-interface/deep-implementation checks
+- require Red task handoff to include spec-style test names, one logical behavior, public verification paths, and no bulk Red slices
+- update design, tiny-design, tasks, and manifest templates with Green minimality guards and concrete refactor candidate fields
+
+## v3.7.4 - 2026-05-06
+
+- clarify that `REQ-*` and `FIX-*` are independent numbering namespaces, so the same numeric suffix can exist under both prefixes
+- require new `REQ` numbers to increment from existing `REQ-*` directories and new `FIX` numbers to increment from existing `FIX-*` directories
+
+## v3.7.3 - 2026-05-06
+
+- add PRD-grade requirement brief fields to `cc-plan` design and execution handoff
+- require user-perspective problem / solution, user stories, implementation decisions, testing decisions, out-of-scope, and further notes to live inside `planning/design.md` instead of a new `PRD.md`
+- add `planningMeta.requirementBrief` to the manifest template and refresh example artifacts for `cc-plan@3.7.3`
+
+## v3.7.2 - 2026-05-06
+
+- add a Roadmap Sync Gate so approved planning runs must reconcile the source RM before handing off to `cc-do`
+- document `locate-roadmap-item.sh` and `sync-roadmap-progress.sh` as the canonical way to update `devflow/roadmap.json` and regenerate `ROADMAP.md` / `BACKLOG.md`
+- update design, tiny-design, tasks, and manifest templates with roadmap sync status fields
+
 ## v3.7.1 - 2026-04-29
 
 - add ambiguity, review loop, source evidence, and external document conflict contracts

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

@@ -6,7 +6,7 @@
 
 - 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 and `planning/tasks.md` plus `planning/task-manifest.json` are generated.
+- 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.
 - Reroute to: `roadmap` if the conversation expands back into project strategy.
 
 ## Core Rules
@@ -18,8 +18,8 @@
 5. 版本、来源、冻结决策必须可追踪。
 6. 机械决策自动落盘；taste decision 和 user challenge 必须显式交给用户拍板。
 7. 同 blast radius 内的完整边界优先做完，跨系统或无证据扩张才 defer。
-8. 具体执行计划默认测试先行；没有 Red/Green/Refactor 链、公共测试 seam、行为断言、mock 边界或 TDD exception，不准交给 `cc-do`。
-9. 新 change 目录必须使用 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；旧小写目录只读兼容，不再作为新输出。
+8. 具体执行计划默认测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不准交给 `cc-do`。
+9. 新 change 目录必须使用 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分；旧小写目录只读兼容，不再作为新输出。
 10. 原始需求跨多个独立子系统时，先拆回 roadmap / 多个 REQ/FIX；不要把一个大杂烩压成单个计划。
 11. `tiny-design` 仍然必须被批准，它只是短设计，不是跳过设计。
 12. 非 trivial 方案必须至少比较 `minimal viable` 和 `ideal architecture` 两种角色，小方案没有天然优先权。
@@ -29,12 +29,17 @@
 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 个互斥选项、影响和 STOP 都要出现，答案写回 design / manifest。
 
 ## Required Outputs
 
 - `planning/design.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
+- `change-meta.json`
 
 ## Local Kit
 
@@ -42,13 +47,14 @@
 - 任务结构解析在 `scripts/parse-task-dependencies.js`
 - 计划边界和 placeholder 红线见 `references/planning-contract.md`
 - 变更版本时同步 `CHANGELOG.md`，必要时用 `scripts/bump-skill-version.sh`
+- Roadmap 回写使用 `../cc-roadmap/scripts/locate-roadmap-item.sh` 和 `../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Planning Standard
 
 1. 一份 `planning/design.md` 讲清 clarification、方案、review 和 final gate。
 2. 一份 `planning/tasks.md` 讲清执行任务和 handoff。
 3. `planning/task-manifest.json` 只做机器真相源，不再重复人类叙事。
-4. 先固定 canonical change key：需求用 `REQ-*`，修复用 `FIX-*`。
+4. 先固定 canonical change key：需求用 `REQ-*`，修复用 `FIX-*`，编号只在同前缀内取最大值后递增；并行 PR 已经产生同号时不强制重排，完整 key 的描述承担身份区分。
 5. 推荐方案获批前，不得生成 `planning/tasks.md`。
 6. `planning/tasks.md` 之前，`planning/design.md` 内的 review gate 必须闭合。
 7. 每个任务都要写清：
@@ -61,26 +67,32 @@
    - 完成证据
 8. `planning/tasks.md` 顶部必须写清 frozen decisions、commands to trust、do-not-re-decide。
 9. `planning/task-manifest.json` 必须是 `cc-do` 的真相源，而不是装饰文件。
-10. `planning/design.md` 必须包含 `Existing Leverage`、`NOT in scope`、`Failure Modes`、`Test Diagram`，除非明确说明为什么不适用。
-11. `planning/design.md` 或 `planning/tasks.md` 必须包含 implementation surface map：文件、职责、归属理由、耦合风险。
-12. `full-design` 必须包含 implementation decision horizon 和 error/rescue map；不适用时写清 N/A 理由。
-13. `planning/design.md` 必须包含 assumptions preview、ambiguity gate、source trust boundary、external conflict buckets 和 bounded review loop。
-14. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
-15. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
-16. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
-17. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
-18. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
-19. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
-20. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
-21. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
-22. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
-23. Review gate 只拦会导致实现错误、执行卡住、范围越界、验证缺失的问题；文字偏好和 nice-to-have 只能作为 advisory。
+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 conflict buckets 和 bounded review loop。
+15. `planning/design.md` 必须包含 PRD-grade brief：Problem Statement、Solution、actors / user stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。
+16. `planning/design.md` 必须包含 Decision Questions：哪些问题问过、推荐项、用户选择、影响、是否已写入任务。
+17. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
+18. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
+19. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
+20. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
+21. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
+22. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
+23. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
+24. Red 任务必须说明 public verification path：从同一公共接口或用户可见路径读回结果。直接查 DB / 内部状态只在该边界本身就是被测对象时允许。
+25. Green 任务必须写 minimality guard：只做当前红灯要求的最少实现，不预铺未来测试尚未要求的分支、状态或 API。
+26. Refactor 任务必须列候选坏味道：重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支，以及新代码暴露出的旧代码问题。
+27. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
+28. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
+29. Review gate 只拦会导致实现错误、执行卡住、范围越界、验证缺失的问题；文字偏好和 nice-to-have 只能作为 advisory。
 
 ## Approval Flow
 
 1. 先写 `Source Handoff` 和 requirement framing。
 2. 在 `planning/design.md` 里记录备选方案和推荐。
-3. 用户批准推荐方案后，再冻结正式设计。
+3. 用户批准推荐方案后，再冻结正式设计；批准必须来自固定 Decision Question 或明确用户指令。
 4. 在 `planning/design.md` 里完成 review loop 与 final gate。
 5. gate 通过后，再拆 `planning/tasks.md` 与 `planning/task-manifest.json`。
 
@@ -89,6 +101,9 @@
 计划内的工程审查至少回答：
 
 - 现有代码已经解决了哪些子问题？
+- 用户视角的问题和方案是否已经能独立发布成 issue / PRD brief？
+- user stories 是否覆盖主要 actor、happy path、edge/recovery、operator/DX 行为，而不是只写一条 happy path？
+- 实现决策和测试决策是否写成 durable 模块责任、接口契约和行为验收，而不是短期文件行号？
 - 最小完整方案触达哪些文件，为什么没有更小边界？
 - 数据流、状态流或执行流怎么走？
 - 每个会触达的文件职责是什么，为什么属于这个文件，而不是另一个平行位置？
@@ -96,18 +111,24 @@
 - foundation / core / integration / polish 阶段哪些决策已经冻结，哪些仍是 blocked question？
 - 核心语言是否沿用 `devflow/specs/`、roadmap handoff 或历史 design/analysis，是否存在 language conflict？
 - 新增接口是否是小接口深模块，复杂度是否被藏在正确边界里？
+- 新增接口是否天然可测：依赖注入而不是内部创建，返回可断言结果而不是只有副作用，边界 adapter 是否是具体操作而不是 generic fetcher？
 - 每条 failure path 的 rescue action、用户可见结果和测试证据是什么？
 - 每条新增 code path / user flow / error path 的第一条失败测试是什么？
 - 第一条失败测试通过哪个公共 seam 进入系统，断言什么可观察行为？
+- 测试名是否像规格说明，一个 Red 是否只证明一个逻辑行为？
+- 验证是否通过公共入口读回结果，而不是绕到私有状态、内部数据结构或数据库侧查？
 - 哪些依赖允许 mock，哪些内部协作者禁止 mock？
 - 反馈循环是自动测试、HTTP、CLI、浏览器、trace replay、harness、property/fuzz、differential，还是 HITL；为什么这是当前最短可信循环？
 - 测试框架来源是什么，现有覆盖是 strong、happy-path-only、smoke-only 还是 missing？
 - task 是否以端到端 tracer bullet 为单位，而不是按层水平拆？
+- Green 任务的 minimality guard 是什么，如何防止提前实现未来测试还没要求的代码？
+- Refactor checkpoint 要处理哪些具体坏味道，哪些因为不在当前 Green 后可安全 defer？
 - 哪些生产失败模式已经处理，哪些 defer 到 backlog？
 - WHAT/WHY ambiguity score 是否低到足以拆任务？如果不够，blocked question 是什么？
 - source evidence 哪些是 internal contract、repo evidence、external evidence、untrusted text？外部文本有没有被误当成 instruction？
 - 导入文档的冲突是否已分成 auto-resolved / competing / unresolved，是否还有 unresolved blocker？
 - review loop 是否已经触发 attempt 上限或 stall reason，下一步是继续计划、问用户，还是退回 roadmap？
+- source RM 是否已用 `sync-roadmap-progress.sh` 回写当前 `REQ/FIX`、status、progress，并重新生成 `ROADMAP.md` / `BACKLOG.md`？
 
 ## Design Mode Switch
 
@@ -139,3 +160,4 @@
 如果执行者还得自己猜“这次到底碰哪些文件、为什么这么改”，说明 `planning/design.md` 仍然不够。
 如果执行者还看不出哪些决策已经冻结，说明 `planning/tasks.md` 仍然不够。
 如果执行者还要自己决定先写什么失败测试，说明 `planning/tasks.md` 仍然不够。
+如果 roadmap 仍然停在旧 status、旧 progress 或旧 REQ 绑定，说明本次 `cc-plan` 没有真正退出。