cc-devflow 4.5.4 → 4.5.5

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

@@ -1,5 +1,11 @@
 # CC-Act Skill Changelog
 
+## v1.8.2 - 2026-05-06
+
+- add an execution-time Roadmap Progress Check so act verifies source RM state before ship work continues
+- align all roadmap writeback guidance on `devflow/roadmap.json` with generated `ROADMAP.md` / `BACKLOG.md` projections
+- update delivery templates and act render scripts to surface roadmap sync state in PR briefs, release notes, resume indexes, and doc sync reports
+
 ## v1.8.1 - 2026-04-29
 
 - add structured ship preflight fields with `ShipPreflightError` rescue actions

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

@@ -6,7 +6,7 @@
 
 - Enter from: `cc-check` with a passing report card.
 - Stay in: `cc-act` while ship mode, simplify/test evidence, docs, and handoff are being aligned to proven facts.
-- Exit to: the next roadmap/backlog loop once delivery artifacts and follow-up writeback are complete.
+- Exit to: the next roadmap/backlog loop once delivery artifacts, source RM progress, and follow-up writeback are complete.
 - Reroute to: `cc-check` if verification changes, or `cc-do` if act uncovers unfinished implementation.
 
 ## Core Thesis
@@ -27,9 +27,19 @@
 3. 确认 `planning/tasks.md` 不再有未完成项
 4. 确认 `review.freshness` 新鲜、`runtime.failureOwnership` 无未解释失败、`qa.coverageAudit` / `qa.browserEvidence` 有证据或明确 skip
 5. 确认 `qa.feedbackLoop` / `qa.behaviorEvidence` 能支撑行为结论；不可复现时必须写清缺什么 artifact / 权限 / 输入
+6. 定位 source RM，并确认 `devflow/roadmap.json`、`devflow/ROADMAP.md`、optional `devflow/BACKLOG.md` 没有和 verified reality 冲突
 
 如果 gate 没闭合，直接回 `cc-check` 或 `cc-do`，不要在 `cc-act` 自我安慰。
 
+## Phase 0.5: Check Roadmap Progress
+
+Roadmap 是执行链路的长期记忆，不是收尾时才想起的备忘录。
+
+1. 从 `change-meta.json` / `planning/task-manifest.json` 读取 `sourceRoadmap.itemId`、REQ/FIX、primary capability、expected spec delta。
+2. 用 `../cc-roadmap/scripts/locate-roadmap-item.sh <RM-ID>` 对照 `devflow/roadmap.json`、`devflow/ROADMAP.md`、optional `devflow/BACKLOG.md`。
+3. 如果 RM 已经指向另一个 change、被标成 blocked/deferred/done，或 progress 与 `review/report-card.json` 现实冲突，先同步或 reroute，不继续 ship。
+4. 如果没有 source RM，不编造；在 handoff 写 `roadmapSync.noOpReason: no-source-rm`。
+
 ## Phase 1: Freeze Ship Facts
 
 运行 `scripts/detect-ship-target.sh`，锁定这些事实：
@@ -180,19 +190,22 @@ Ship 必须属于这 4 种模式之一：
 
 ## Phase 6: Write Back The Learning
 
-以下情况必须回写 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`：
+以下情况必须回写 `devflow/roadmap.json`，再重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`：
 
 1. 本次工作暴露了新的 follow-up
 2. 原有优先级被改变
 3. 有明确 deferred item 不能靠口头记忆保存
+4. source RM 的 ship 现实从 planned / repair planned 推进到了 in review / ready for handoff / done
 
 原则：
 
-- 长期方向写 `devflow/roadmap/roadmap.md`
-- 下一轮待排队动作写 `devflow/roadmap/backlog.md`
+- 长期方向写进 `devflow/roadmap.json` 的 stage / item / backlog 字段
+- 下一轮待排队动作写进对应 RM 的 backlog 字段，或交给 `cc-roadmap` 新增 RM
 - 不要把噪音和碎念回写成系统真相
 - follow-up 必须是 durable brief：用领域语言写 current behavior、desired behavior、key interfaces、acceptance criteria、out of scope
 - 独立行为拆独立条目；有依赖关系时写明顺序，方便下一轮并行或排队
+- 常规进度用 `../cc-roadmap/scripts/sync-roadmap-progress.sh --rm <RM-ID> --status <state> --req <REQ/FIX> --progress <percent>`
+- follow-up 改变阶段顺序或项目优先级时，不在 `cc-act` 临场重排，reroute 到 `cc-roadmap`
 
 ## Phase 7: Declare The Next Entry
 
@@ -214,6 +227,7 @@ Ship 必须属于这 4 种模式之一：
 7. follow-up 是不是行为契约，而不是“改某文件某行”的易腐烂 TODO？
 8. ship preflight failure 是否有 `ShipPreflightError`、artifact ref 和 rescue action？
 9. rollback guard 是否足够让下一位维护者不靠聊天记录回退？
+10. source RM 的 status、REQ/FIX、progress 是否已经和 ship 现实一致？
 
 如果第 1 或第 3 题答案不是“能”，说明 `cc-act` 仍然太重或太糊。
 
@@ -223,7 +237,7 @@ Ship 必须属于这 4 种模式之一：
 - `handoff/release-note.md`（需要发布时）
 - 更新后的 `handoff/resume-index.md`
 - 更新后的 `CLAUDE.md` / README / 架构文档（如果结构或行为变了）
-- 必要时更新后的 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+- 必要时更新后的 `devflow/roadmap.json` / `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 
 ## Local Kit
 
@@ -235,6 +249,8 @@ Ship 必须属于这 4 种模式之一：
 - `scripts/render-pr-brief.sh` 负责从 requirement 真相源渲染 `pr-brief.md`
 - `scripts/generate-status-report.sh` 负责汇总 requirement 与 ship 现状
 - `scripts/archive-requirement.sh` 负责 requirement 生命周期收尾
+- `../cc-roadmap/scripts/locate-roadmap-item.sh` 负责定位 source RM
+- `../cc-roadmap/scripts/sync-roadmap-progress.sh` 负责回写 roadmap progress 并渲染投影
 - `cc-simplify` 负责在 ship 前压掉重复、坏味道、低效实现
 - `references/git-commit-guidelines.md` 负责提交规范真相源
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-act
-version: 1.8.1
+version: 1.8.2
 description: 'Use when verified work must be shipped or handed off with a clear landing path: run simplify and required tests, create or update a PR, prepare a local handoff, close out merged work, sync docs, write release notes, and fold follow-ups back into backlog or roadmap.'
 triggers:
   - 准备提 PR
@@ -17,6 +17,8 @@ reads:
   - references/git-commit-guidelines.md
   - assets/PR_BRIEF_TEMPLATE.md
   - assets/RELEASE_NOTE_TEMPLATE.md
+  - ../cc-roadmap/scripts/locate-roadmap-item.sh
+  - ../cc-roadmap/scripts/sync-roadmap-progress.sh
 writes:
   - path: devflow/changes/<change-key>/handoff/pr-brief.md
     durability: durable
@@ -34,15 +36,17 @@ writes:
     when: handoff mode is release
     exclusive_group: handoff
 effects:
-  - roadmap or backlog follow-up updates when needed
+  - roadmap progress and backlog follow-up updates when needed
 entry_gate:
   - Accept only a passing review/report-card.json with reroute=none and specSyncReady=true.
   - Freeze current branch, PR, ship-mode, auth, clean-tree, and rollback facts before writing delivery materials.
   - If simplify, tests, or act changes code or verification scope, return to cc-check immediately.
+  - Read source roadmap progress from `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`, or legacy `devflow/roadmap-tracking.json`; act must not ship against stale RM state.
 exit_criteria:
   - The ship mode is explicit, delivery materials match that mode, and the next maintainer has one clear entry point.
   - Docs, PR text, release notes, handoff artifacts, review range, readiness dashboard, PR body accuracy check, and test evidence reflect the same proven facts.
   - Follow-up items are written back to roadmap/backlog instead of lingering in chat memory.
+  - The source roadmap item reflects the latest verified state, ship mode, and follow-up decision, or the handoff records a no-op reason.
 reroutes:
   - when: Verification is stale, incomplete, or changed during act.
     target: cc-check
@@ -58,7 +62,7 @@ recovery_modes:
 tool_budget:
   read_files: 8
   search_steps: 5
-  shell_commands: 10
+  shell_commands: 11
 ---
 
 # CC-Act
@@ -94,7 +98,7 @@ tool_budget:
 - 需要决定这次是 `create-pr`、`update-pr`、`local-handoff`，还是 `post-merge-closeout`
 - 需要在 ship 前再做一次 `cc-simplify`、单测、以及按协调器要求执行的 e2e
 - 需要同步最终文档、handoff、release note
-- 需要把遗留 follow-up / 优先级变化回写 `devflow/roadmap/backlog.md` 或 `devflow/roadmap/roadmap.md`
+- 需要把遗留 follow-up / 优先级变化回写 `devflow/roadmap.json`，并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 - 需要把已验证的 spec delta 正式回写 capability spec 与 `devflow/specs/INDEX.md`
 - 需要让下一轮入口比现在更清楚
 
@@ -128,7 +132,8 @@ tool_budget:
 4. 运行 `scripts/detect-ship-target.sh`，识别当前分支、base branch、PR 状态与推荐 ship 路径。
 5. 检查 `review.freshness`、`runtime.failureOwnership`、`qa.coverageAudit`、`qa.browserEvidence`，确认 readiness dashboard 没有 blocker。
 6. 检查 `qa.feedbackLoop`、`qa.behaviorEvidence`、`qa.architectureFollowUps` 和 follow-up brief，确认交付材料继承的是行为证据，不是聊天记忆或易腐烂 TODO。
-7. 如果在 `cc-act` 期间因为 `cc-simplify`、单测、e2e、review 修复而改了代码，必须回 `cc-check`，不能带着旧证明继续 ship。
+7. 定位 source RM：优先读 `change-meta.json` / `task-manifest.json` 的 `sourceRoadmap.itemId`，再用 `locate-roadmap-item.sh` 对照 `devflow/roadmap.json`、`devflow/ROADMAP.md` 和 optional `devflow/BACKLOG.md`；如果 roadmap 状态和 verified reality 冲突，先同步或 reroute，不能继续 ship。
+8. 如果在 `cc-act` 期间因为 `cc-simplify`、单测、e2e、review 修复而改了代码，必须回 `cc-check`，不能带着旧证明继续 ship。
 
 ## Ship Modes
 
@@ -173,7 +178,7 @@ tool_budget:
 4. `post-merge-closeout`
    - 必须完成 doc sync
    - 需要对外说明时生成 `handoff/release-note.md`
-   - 必须把 follow-up 回写到 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+   - 必须把 follow-up 回写到 `devflow/roadmap.json`，并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 
 不是每次都要把所有文件生成一遍。材料必须服务于当前 ship 模式，而不是为了流程好看。
 
@@ -312,11 +317,12 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
    - `post-merge-closeout`：跳过 PR，完成发布与闭环回写
 11. 处理 PR / MR body：从当前 `pr-brief.md`、最新验证、review、doc sync、TODO/backlog 结果重新渲染，不复用旧 body。
 12. 在 `handoff/pr-brief.md` 写入 readiness dashboard 与 PR body accuracy check；已有 PR body 与当前事实不一致时先刷新再继续。
-13. 回写 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`：
+13. 回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`：
    - 新发现的 follow-up
    - 被推迟但必须保留的事项
    - 因本次结果而改变优先级的事项
-14. 如果 requirement 真正闭环，更新状态摘要并归档；否则把下一位接手者的入口写清楚。
+14. 用 `sync-roadmap-progress.sh` 更新 source RM 的 status、REQ/FIX 绑定和 progress：`create-pr` / `update-pr` 通常写 `In review` + `100%`，`local-handoff` 写 `Ready for handoff`，`post-merge-closeout` 写 `Done`；如果无 source RM，必须在 handoff 写 no-op reason。
+15. 如果 requirement 真正闭环，更新状态摘要并归档；否则把下一位接手者的入口写清楚。
 
 ## Output
 
@@ -324,7 +330,7 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 - `handoff/release-note.md`（需要对外发布时）
 - 更新后的 `handoff/resume-index.md`
 - 同步后的 `CLAUDE.md` / README / 架构文档
-- 必要时更新后的 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+- 必要时更新后的 `devflow/roadmap.json` / `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 - 单测 / e2e 的通过证据，或明确记录的 skip / blocker
 - 必要时创建或更新的 PR / MR
 - PR / MR body 中的 Summary、Test Coverage、Pre-Landing Review、Scope Drift、Plan Completion、Verification Results、Documentation、Test plan
@@ -339,6 +345,7 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 - 现在谁都可以顺着 `handoff/pr-brief.md` 或 `handoff/resume-index.md` 继续往前走
 - 文档、PR 描述、release note 说的是同一套现实
 - `cc-simplify`、单测、e2e、commit/push 的结果都能被接手者追溯
+- source RM 的 status、REQ/FIX 绑定、progress 和 follow-up 已经和 ship 现实一致
 
 ## Bundled Resources
 
@@ -353,6 +360,8 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 - 文档同步：`scripts/sync-act-docs.sh`
 - PR 简报生成：`scripts/render-pr-brief.sh`
 - requirement 归档：`scripts/archive-requirement.sh`
+- Roadmap 定位：`../cc-roadmap/scripts/locate-roadmap-item.sh`
+- Roadmap 回写：`../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Working Rules
 
@@ -363,12 +372,13 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 5. 分支决策必须明确属于 4 种模式之一，不要含糊。
 6. 已存在 PR / MR 时，优先更新，不重复创建。
 7. `cc-simplify`、单测、e2e 任何一步只要导致代码变化或验证口径变化，必须回 `cc-check`。
-8. `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md` 只回写真正改变优先级或产生 follow-up 的事项，不写噪音。
+8. `devflow/roadmap.json` 只回写真正改变优先级或产生 follow-up 的事项，并用 `sync-roadmap-progress.sh` 重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`，不写噪音。
 9. `local-handoff` 不是偷懒模式，它仍然必须让下一位接手者知道做什么、怎么验证、卡在哪。
 10. `create-pr` / `update-pr` 模式默认要求提交历史符合 `references/git-commit-guidelines.md`，并完成正确的 push、PR 创建或更新动作。
 11. CHANGELOG 只能基于当前 diff / commit history / release truth 更新，不允许覆盖既有历史条目。
 12. PR / MR body 每次都从当前事实重建，不沿用旧 body 或旧测试输出。
 13. Verification 每次执行 `cc-act` 都必须重新运行；只有已完成且可证明幂等的动作可以跳过。
+14. source RM 找不到时不能编造新 RM；写 no-op reason。如果 follow-up 改变阶段顺序或优先级，reroute 到 `cc-roadmap`。
 
 ## Exit Criteria
 
@@ -377,7 +387,7 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 - reviewer / maintainer 能直接接手
 - 需要同步的文档已经同步
 - `cc-simplify`、单测、e2e 已执行完毕，或 skip / blocker 已被明确记录
-- follow-up 已回写到正确的 backlog / roadmap 位置
+- source RM 已回写最新进度，follow-up 已回写到正确的 backlog / roadmap 位置
 - 下一轮该怎么继续已经写清楚
 - requirement 不是“看起来结束”，而是真正闭环
 

package/.claude/skills/cc-act/assets/PR_BRIEF_TEMPLATE.md

@@ -102,6 +102,16 @@
 - `release-note.md`:
 - `resume-index.md`:
 
+## Roadmap Progress Sync
+
+- Source RM:
+- Roadmap files: `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`
+- Sync command:
+- Status after sync:
+- Progress after sync:
+- Follow-up writeback:
+- No-op reason:
+
 ## Consolidated Memory
 
 - `handoff path`: 

package/.claude/skills/cc-act/assets/RELEASE_NOTE_TEMPLATE.md

@@ -37,6 +37,14 @@
 
 - 
 
+## Roadmap Progress
+
+- Source RM:
+- Status after sync:
+- Progress after sync:
+- Follow-up writeback:
+- No-op reason:
+
 ## Follow-Ups
 
 - Current behavior:

package/.claude/skills/cc-act/references/closure-contract.md

@@ -11,6 +11,7 @@
 7. PR / handoff 必须记录 `cc-check` 审过的 base/head SHA、review packet、finding triage 摘要
 8. readiness dashboard 必须说明 review freshness、QA coverage、browser evidence、failure ownership、documentation release、PR body accuracy
 9. behavior handoff 必须带上 QA feedback loop、expected / actual / reproduction steps，以及 durable follow-up brief
+10. source RM 必须已从 `devflow/roadmap.json` 定位，且 roadmap progress 与 verified reality 一致；没有 source RM 时记录 no-op reason
 
 ## Ship Decision Contract
 
@@ -37,6 +38,7 @@
 10. verification 每次进入 `cc-act` 都必须重新跑；只有 push、PR 更新、文档生成等动作可以因为幂等状态跳过
 11. PR body accuracy 必须对照当前 report-card、当前 diff、当前 commits；旧 body 不能作为证据源
 12. follow-up 回写必须用行为契约表达，包含 current behavior、desired behavior、key interfaces、acceptance criteria、out of scope；不能只写文件路径或聊天 TODO
+13. roadmap 回写只更新 `devflow/roadmap.json`，并通过 `sync-roadmap-progress.sh` 重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 
 ## Memory Consolidation
 
@@ -56,5 +58,6 @@
 - readiness dashboard 没有 blocker，PR body accuracy 已检查或明确阻塞
 - QA behavior evidence 和 feedback loop 已进入 PR / handoff / release 材料
 - post-merge closeout 反映 merged result 的验证事实，而不是只反映合并前事实
+- source RM 的 status、REQ/FIX 绑定、progress 和 follow-up 已经落入 roadmap truth
 - 下一轮计划入口更清楚
 - 文档入口可发现，changelog 不丢历史，TODO / backlog 只记录有证据的事项

package/.claude/skills/cc-act/scripts/cc-act-common.sh

@@ -253,6 +253,54 @@ req_act_collect_spec_files() {
   req_act_dedup_file "$out_file"
 }
 
+req_act_roadmap_sync_summary() {
+  local manifest="$1"
+  local repo_root="${2:-$(req_act_repo_root)}"
+  local item_id=""
+  local sync_status=""
+  local sync_command=""
+  local no_op_reason=""
+  local updated_files=""
+  local existing_files=""
+
+  if [[ -f "$manifest" ]]; then
+    item_id="$(jq -r '.sourceRoadmap.itemId // empty' "$manifest" 2>/dev/null || true)"
+    sync_status="$(jq -r '.sourceRoadmap.syncStatus // .roadmapSync.status // "not recorded"' "$manifest" 2>/dev/null || true)"
+    sync_command="$(jq -r '.sourceRoadmap.syncCommand // .roadmapSync.command // empty' "$manifest" 2>/dev/null || true)"
+    no_op_reason="$(jq -r '.sourceRoadmap.noOpReason // .roadmapSync.noOpReason // empty' "$manifest" 2>/dev/null || true)"
+    updated_files="$(jq -r '(.sourceRoadmap.updatedFiles // .roadmapSync.updatedFiles // []) | join(", ")' "$manifest" 2>/dev/null || true)"
+  fi
+
+  for candidate in devflow/roadmap.json devflow/ROADMAP.md devflow/BACKLOG.md devflow/roadmap-tracking.json; do
+    if [[ -f "$repo_root/$candidate" ]]; then
+      if [[ -n "$existing_files" ]]; then
+        existing_files+=", "
+      fi
+      existing_files+="$candidate"
+    fi
+  done
+
+  [[ -n "$existing_files" ]] || existing_files="no roadmap files found"
+  [[ -n "$updated_files" ]] || updated_files="not recorded"
+  [[ -n "$sync_command" ]] || sync_command="not recorded"
+  [[ -n "$sync_status" ]] || sync_status="not recorded"
+
+  if [[ -z "$item_id" ]]; then
+    [[ -n "$no_op_reason" ]] || no_op_reason="no-source-rm"
+    printf 'source=none; status=no-op; files=%s; no-op=%s\n' "$existing_files" "$no_op_reason"
+    return 0
+  fi
+
+  printf 'source=%s; status=%s; files=%s; updated=%s; command=%s' \
+    "$item_id" "$sync_status" "$existing_files" "$updated_files" "$sync_command"
+
+  if [[ -n "$no_op_reason" ]]; then
+    printf '; no-op=%s' "$no_op_reason"
+  fi
+
+  printf '\n'
+}
+
 req_act_collect_evidence() {
   local report_card="$1"
   local out_file="$2"

package/.claude/skills/cc-act/scripts/generate-status-report.sh

@@ -31,6 +31,7 @@ source "$script_dir/cc-act-common.sh"
 CHANGE_DIR="$(req_act_change_dir "$REQ_DIR")"
 report_card="$(req_act_report_path "$CHANGE_DIR")"
 tasks_file="$(req_act_tasks_path "$CHANGE_DIR")"
+manifest="$(req_act_manifest_path "$CHANGE_DIR")"
 handoff_dir="$(req_act_handoff_dir "$CHANGE_DIR")"
 
 verdict="unknown"
@@ -59,6 +60,7 @@ platform="$(printf '%s\n' "$ship_context" | awk -F= '/^PLATFORM=/{print $2}')"
 decision_hint="$(printf '%s\n' "$ship_context" | awk -F= '/^DECISION_HINT=/{print $2}')"
 pr_status="$(printf '%s\n' "$ship_context" | awk -F= '/^PR_STATUS=/{print $2}')"
 pr_url="$(printf '%s\n' "$ship_context" | awk -F= '/^PR_URL=/{print $2}')"
+roadmap_sync_summary="$(req_act_roadmap_sync_summary "$manifest")"
 
 {
   echo "# Status Report"
@@ -76,6 +78,7 @@ pr_url="$(printf '%s\n' "$ship_context" | awk -F= '/^PR_URL=/{print $2}')"
   [[ -n "$decision_hint" ]] && echo "- Ship mode hint: $decision_hint"
   [[ -n "$pr_status" ]] && echo "- PR status: $pr_status"
   [[ -n "$pr_url" ]] && echo "- PR url: $pr_url"
+  echo "- Roadmap progress: $roadmap_sync_summary"
   [[ -f "$handoff_dir/pr-brief.md" ]] && echo "- PR brief: ready"
   [[ -f "$handoff_dir/release-note.md" ]] && echo "- Release note: ready"
   [[ -f "$handoff_dir/resume-index.md" ]] && echo "- Resume index: ready"

package/.claude/skills/cc-act/scripts/render-pr-brief.sh

@@ -186,6 +186,7 @@ failure_ownership_summary="$(jq -r '
 ' "$report_card")"
 documentation_release_summary="CLAUDE=${claude_status}; README=${readme_status}"
 pr_body_accuracy_summary="body must be regenerated from this pr-brief, current report-card, and current diff before PR create/update"
+roadmap_sync_summary="$(req_act_roadmap_sync_summary "$manifest" "$REPO_ROOT")"
 
 {
   echo "# PR Brief"
@@ -231,6 +232,7 @@ pr_body_accuracy_summary="body must be regenerated from this pr-brief, current r
   echo "- Behavior evidence: $behavior_evidence_summary"
   echo "- Failure ownership: $failure_ownership_summary"
   echo "- Documentation release: $documentation_release_summary"
+  echo "- Roadmap progress: $roadmap_sync_summary"
   echo "- PR body accuracy: $pr_body_accuracy_summary"
   echo
   echo "## Summary"
@@ -298,6 +300,10 @@ pr_body_accuracy_summary="body must be regenerated from this pr-brief, current r
     echo "- \`resume-index.md\`: missing"
   fi
   echo
+  echo "## Roadmap Progress Sync"
+  echo
+  echo "- $roadmap_sync_summary"
+  echo
   echo "## How To Verify"
   echo
   if [[ -s "$tmp_verify" ]]; then

package/.claude/skills/cc-act/scripts/sync-act-docs.sh

@@ -62,6 +62,7 @@ spec_sync_ready="$(req_act_spec_sync_ready "$report_card")"
 output_language="$(req_act_output_language "$report_card")"
 design_goal="$(req_act_design_goal "$design_file")"
 main_risk="$(req_act_main_risk "$design_file")"
+roadmap_sync_summary="$(req_act_roadmap_sync_summary "$manifest" "$REPO_ROOT")"
 
 tmp_changed="$(mktemp)"
 tmp_verify="$(mktemp)"
@@ -176,6 +177,11 @@ find "$REPO_ROOT" -maxdepth 2 -type f \( -iname 'README.md' -o -iname 'README*.m
   echo "- Base branch: ${base_branch:-unknown}"
   [[ -n "$pr_status" ]] && echo "- PR status: $pr_status"
   [[ -n "$pr_url" ]] && echo "- PR url: $pr_url"
+  echo "- Roadmap progress: $roadmap_sync_summary"
+  echo
+  echo "## Roadmap Progress"
+  echo
+  echo "- $roadmap_sync_summary"
   echo
   echo "## Follow-Ups"
   if [[ -s "$tmp_followups" ]]; then
@@ -225,6 +231,7 @@ esac
     echo "- Req-Check passed; see review/report-card.json for evidence."
   fi
   echo "- Ship mode decided as \`$ship_mode\`."
+  echo "- Roadmap progress: $roadmap_sync_summary"
   [[ -n "$pr_url" ]] && echo "- Active PR / MR: $pr_url"
   echo
   echo "## Follow-Ups"
@@ -241,6 +248,7 @@ esac
   echo
   echo "- $next_action"
   echo "- Formal spec sync belongs in cc-act before final ship closeout."
+  echo "- Roadmap progress must be synced through cc-roadmap before final closeout when a source RM exists."
   echo
   echo "## Parallel Notes"
   echo
@@ -289,6 +297,10 @@ esac
     echo "- No capability spec files recorded in task-manifest.json."
   fi
   echo
+  echo "## Roadmap Targets"
+  echo
+  echo "- $roadmap_sync_summary"
+  echo
   echo "## Project Doc Targets"
   echo
   echo "### CLAUDE Targets"
@@ -317,6 +329,7 @@ esac
   echo
   echo "- Update the listed \`CLAUDE.md\` files if structure, workflow, or operational truth changed."
   echo "- Update README candidates if user-visible behavior or setup flow changed."
+  echo "- Update \`devflow/roadmap.json\` via \`sync-roadmap-progress.sh\` when source RM status, progress, or follow-up truth changed."
   echo "- Re-render \`pr-brief.md\` after any manual doc edits so the PR body stays in sync."
   if [[ -n "$main_risk" ]]; then
     echo "- Main risk to reflect in docs: $main_risk"

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

@@ -1,5 +1,11 @@
 # CC-Do Skill Changelog
 
+## v1.6.2 - 2026-05-06
+
+- absorb the external TDD skill's execution details into native `cc-do`: spec-style test names, one logical behavior per Red, and public verification paths
+- strengthen Green evidence with minimality guards so implementation does not pre-build future unproven behavior
+- expand checkpoint recovery fields with interface-testability proof and concrete refactor candidates such as duplication, long methods, shallow modules, feature envy, primitive obsession, naming, and nested branches
+
 ## v1.6.1 - 2026-04-29
 
 - reject parent/child touched-path overlaps when selecting parallel execution surfaces

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

@@ -53,10 +53,11 @@
 2. 确认红灯是预期失败，不是测试写错、fixture 缺失或环境没接上。
 3. 确认红灯通过公共 seam 证明行为缺失，而不是测私有函数、内部调用次数或临时结构。
 4. 确认 mock 只发生在系统边界；内部协作者不 mock。
-5. 只写让当前测试转绿的最小实现。
-6. 绿后才允许重构。
-7. 重构后必须保持绿。
-8. 测试没先红过，或红灯不是公共 seam 上的行为失败，就不能宣称这次变更受 TDD 保护。
+5. 确认测试名像规格说明，一个 Red 只证明一个逻辑行为，结果从公共验证路径读回。
+6. 只写让当前测试转绿的最小实现，不提前实现未来测试尚未要求的分支、状态或 API。
+7. 绿后才允许重构。
+8. 重构后必须保持绿，并说明处理了重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支或其它具体坏味道。
+9. 测试没先红过，或红灯不是公共 seam 上的行为失败，就不能宣称这次变更受 TDD 保护。
 
 ## TDD Exception Rule
 
@@ -84,9 +85,9 @@
 3. `red_seam_verified`: 红灯通过公共接口、调用方流程、CLI/API/UI 或真实边界进入系统
 4. `red_behavior_verified`: 测试断言用户或调用方可观察行为，不断言内部实现细节
 5. `mock_boundary_verified`: mock 只在系统边界，内部协作者没有被 mock
-6. `green_passed`: 当前任务实现转绿
+6. `green_passed`: 当前任务实现转绿，且实现只覆盖当前红灯要求的最小行为
 7. `refactor_done` 或 `refactor_not_needed`
-8. `refactor_green`: 重构后相关测试仍绿
+8. `refactor_green`: 重构后相关测试仍绿，且没有在 Red 状态做结构清理
 9. `spec_review_pass`
 10. `code_review_pass`
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-do
-version: 1.6.1
+version: 1.6.2
 description: Use when implementing planned tasks, resuming interrupted work, applying a frozen investigation handoff, or landing review feedback after cc-plan or cc-investigate.
 triggers:
   - 开始做 T003
@@ -40,8 +40,10 @@ entry_gate:
   - Select only ready tasks whose dependencies, wave, touched paths, and file ownership are clear.
   - Reject parallel execution when touched paths overlap by exact path or parent/child path; submodule touches must be isolated unless the task explicitly owns that submodule.
   - If the current task cannot be restated from canonical artifacts, run a context reset before coding.
+  - "Validate the current task's TDD shape before coding: spec-style test name, one logical behavior, public verification path, allowed boundary mocks, Green minimality guard, and refactor candidates."
 exit_criteria:
   - The current task has red/green evidence, public-seam test quality evidence, review evidence, and a resumable checkpoint trail.
+  - Red evidence proves one observable behavior through a public verification path; Green evidence shows only the minimal production change; Refactor evidence names the concrete smell removed or says why none was needed.
   - Execution leaves the next verifier enough runtime truth to judge the task without chat memory.
   - The honest next step is cc-check or an explicit reroute.
 reroutes:
@@ -141,12 +143,18 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实边界进入系统；只验证私有函数、内部调用次数、临时数据结构或 mock 自己控制的内部协作者，不算 TDD 证据。
 
+一个 Red 只证明一个逻辑行为。测试名要像规格说明，而不是实现步骤；结果要从同一类公共入口读回。直接查数据库、读内部状态、扫描临时文件或绕过 API 来证明行为，只在那个边界本身就是被测对象时成立。
+
 例外只能用于 throwaway prototype、纯生成文件、纯配置改动；例外必须写进 checkpoint 的 `tddException`，包含原因、风险和替代验证命令。测试第一次就绿，说明测试没有证明新行为，必须修测试而不是继续写生产代码。
 
 禁止水平切片：不要先写一批测试，再写一批实现。每次只推进一个 tracer bullet：一个可观察行为的 Red -> 让它变绿的最小实现 -> 必要重构 -> 记录证据，然后再进入下一个行为。
 
 测试数据也必须诚实。fixture 只提供当前行为需要的最小输入；partial fixture、类型断言、mock payload 或 generated stub 必须写清哪些字段是真实 contract，哪些只是测试填充。不能用 `as`、`any`、双重 cast、缺字段 partial mock 或 test-only method 掩盖 seam 设计问题。
 
+Green 不是顺手把未来行为都做掉。只写当前红灯要求的最小生产代码；如果需要新接口，优先保持小接口深模块，依赖从调用方传入，外部 boundary adapter 拆成具体操作，而不是用一个 generic fetcher 把复杂条件推给 mock。
+
+Refactor 只能发生在 Green 之后。优先处理当前 slice 暴露出的重复、长方法、浅模块、feature envy、primitive obsession、命名混乱、三层以上分支和新代码揭开的旧代码坏味道；没被当前绿色测试保护的扩张性整理，回到 `cc-plan` 或后续任务。
+
 ## Entry Gate
 
 1. 先读 `planning/design.md` 或 `planning/analysis.md`，再读 `planning/tasks.md`、`planning/task-manifest.json`；如果是恢复执行，再补读最近 checkpoint 或已有 `handoff/resume-index.md`。
@@ -165,12 +173,13 @@ Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试
 4. 先 `fail-first`：先写失败测试，先看见预期红，再写生产代码。
 5. 如果红灯不是预期失败（语法错、fixture 错、测试没连上），先修测试直到它正确失败。
 6. 如果红灯通过错误 seam 得到，比如私有方法、内部调用次数、mock 内部协作者，先修测试 seam，不准进入 Green。
-7. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现。
-8. 如果当前 Red 需要新的 fixture 或 mock，先证明它仍从公共 seam 触发真实行为；fixture 缺字段、类型强转或内部 mock 都要写入 `tdd.testQuality.fixtureRisk` 或先修 seam。
-9. Refactor 后必须重跑相关测试，保持 Green。
-10. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`，并记录 `tdd.testQuality` 或 `tddException`。
-11. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
-12. 当前任务完成后，把可验证证据留给 `cc-check`。
+7. 如果红灯只断言实现形状、直接查内部状态或一次证明多个逻辑行为，先改测试，不准进入 Green。
+8. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现，不预铺未来测试尚未要求的分支、状态或 API。
+9. 如果当前 Red 需要新的 fixture 或 mock，先证明它仍从公共 seam 触发真实行为；fixture 缺字段、类型强转或内部 mock 都要写入 `tdd.testQuality.fixtureRisk` 或先修 seam。
+10. Refactor 后必须重跑相关测试，保持 Green；Red 状态下不重构。
+11. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`，并记录 `tdd.testQuality`、`tdd.greenMinimality`、`tdd.refactorCandidates` 或 `tddException`。
+12. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
+13. 当前任务完成后，把可验证证据留给 `cc-check`。
 
 ## Output
 
@@ -185,6 +194,9 @@ Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试
 - 当前 task 一眼可见，执行者不用从聊天记录里猜目标
 - 当前 wave、ready tasks、parallel candidates、touch conflict verdict 和 submoduleTouches 一眼可见
 - 至少留下一次明确的 tracer bullet Red/Green/Refactor 证据，且 Red 是公共 seam 上的预期行为失败
+- Red 证据说明测试名、单一行为、公共验证路径和为何不是实现细节测试
+- Green 证据说明 minimality guard：本轮只满足当前红灯，没有提前实现未来分支
+- Refactor 证据说明清掉了哪个具体坏味道，或者为什么当前 slice 不需要 refactor
 - 测试 fixture 说明真实 contract 字段和测试填充字段，没有用类型欺骗或内部 mock 制造假绿
 - runtime / checkpoint 足够让下一位接手者无损恢复
 - quick lane 也有 mini manifest、checkpoint、verification 和唯一 next action，不靠聊天记录继续
@@ -214,11 +226,14 @@ Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试
 5. 红灯原因必须和目标行为缺失一致；红灯如果只是测试写错，不算 TDD 证据。
 6. 红灯必须验证公共接口上的行为；实现细节测试、私有方法测试、内部调用次数断言都要先退回 Red 修正。
 7. Mock 只能放在系统边界；如果必须 mock 内部协作者才能测试，说明 seam 或设计合同有问题。
-8. 先过 `spec review`，再过 `code review`，顺序不能反。
-9. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
-10. 失败和阻塞都要留下恢复证据。
-11. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
-12. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
+8. 一个 Red 只证明一个逻辑行为；bulk Red 或测试名描述实现步骤，都先退回测试设计。
+9. Green 只写当前红灯需要的最小实现；预铺未来功能、兼容分支或宽接口都算越界。
+10. Red 时不重构；Refactor 只在相关测试已绿后处理当前 slice 暴露的坏味道。
+11. 先过 `spec review`，再过 `code review`，顺序不能反。
+12. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
+13. 失败和阻塞都要留下恢复证据。
+14. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
+15. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
 
 ## Exit Criteria
 

package/.claude/skills/cc-do/references/execution-recovery.md

@@ -59,13 +59,22 @@
 - `red.expectedFailure`
 - `red.testSeam`
 - `red.behaviorAsserted`
+- `red.specStyleTestName`
+- `red.oneLogicalBehavior`
+- `red.publicVerificationPath`
 - `red.allowedMocks`
 - `red.implementationDetailRisk`
 - `green.command`
 - `green.exitStatus`
+- `green.minimalityGuard`
 - `refactor.status`
+- `refactor.candidates`
+- `refactor.greenCommand`
 - `testQuality.usesPublicInterface`
 - `testQuality.describesBehavior`
+- `testQuality.specStyleName`
+- `testQuality.verifiesThroughPublicPath`
+- `testQuality.noBulkRed`
 - `testQuality.survivesInternalRefactor`
 - `testQuality.mocksOnlySystemBoundaries`
 - `review.spec.status`

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

@@ -1,5 +1,11 @@
 # CC-Investigate Skill Changelog
 
+## v1.2.2 - 2026-05-06
+
+- add a Roadmap Sync Gate so frozen investigations must reconcile the source RM before handing off repair work
+- classify roadmap updates by `implementation drift`, `missing spec truth`, and `roadmap mismatch` outcomes
+- update analysis, tasks, and manifest templates with roadmap sync status fields
+
 ## v1.2.1 - 2026-04-29
 
 - add persistent debug session fields for active hypothesis, probes, cleanup state, and next evidence action