cc-devflow 4.5.3 → 4.5.5

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

@@ -1,5 +1,17 @@
 # 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
+- require rollback guards before publish, merge, PR update, or release note handoff
+- add PR branch hygiene and learning extraction targets to delivery templates
+
 ## v1.8.0 - 2026-04-28
 
 - add remote state consistency rules for issue, PR, tracker, `needs-info`, and `ready-for-agent` closeout handoffs

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`，锁定这些事实：
@@ -84,6 +94,9 @@ Ship 必须属于这 4 种模式之一：
 4. 如果有 WIP commit，只能用非破坏性 rebase / fixup 处理，不允许盲目 soft reset。
 5. push 前比较 local / remote HEAD；PR 前检查是否已有打开 PR / MR。
 6. 生成 readiness dashboard：review freshness、review quality、QA coverage、browser QA、feedback loop、behavior evidence、failure ownership、documentation release、PR body accuracy。
+7. 生成 ship preflight：branch/base/remote/auth/clean tree/review freshness/ship mode。
+8. preflight 失败必须命名为 `ShipPreflightError`，并写明 rescue action 或切到 `local-handoff`。
+9. 发布、合并、PR 更新或 release note 前必须写 rollback guard。
 
 ## Phase 3: Build Delivery Pack
 
@@ -115,6 +128,8 @@ Ship 必须属于这 4 种模式之一：
 - review packet path / summary
 - finding triage summary
 - QA / claim evidence summary
+- ship preflight and `ShipPreflightError` rescue if any
+- rollback guard
 - QA behavior evidence and feedback-loop quality
 - readiness dashboard
 - PR body accuracy check
@@ -175,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
 
@@ -207,6 +225,9 @@ Ship 必须属于这 4 种模式之一：
 5. PR body / release note / handoff / changelog 说的是不是同一套现实？
 6. readiness dashboard 有没有 blocker 或 stale warning？
 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` 仍然太重或太糊。
 
@@ -216,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
 
@@ -228,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.0
+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, and ship-mode facts before writing delivery materials.
+  - 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 模式，而不是为了流程好看。
 
@@ -218,6 +223,29 @@ tool_budget:
 11. Remote state consistency：如果本次 closeout 触碰 GitHub issue / PR / tracker，必须记录当前 state、目标 state、允许转换、已保留事实和下一位 owner；`needs-info` 必须保留已确认事实和具体问题，`ready-for-agent` 必须有可执行 brief。
 12. Tooling smoke：如果本次改动影响 hook、pre-commit、lint、publish、adapt 或验证脚本，必须跑真实入口或最接近真实入口的 smoke；只读配置文件不等于工具链可用。
 
+## Ship Preflight And Rescue
+
+ship preflight 必须结构化记录：
+
+- `branch`: 当前分支、base、remote、local/remote HEAD 关系
+- `auth`: `gh` / registry / deploy / package publish 等权限是否可用
+- `workspace`: clean tree、staged files、未跟踪文件和相关 stash
+- `reviewFreshness`: `cc-check` 审查范围是否仍绑定当前 HEAD
+- `shipMode`: `create-pr` / `update-pr` / `local-handoff` / `post-merge-closeout`
+
+任何 preflight failure 都必须命名为 `ShipPreflightError`，并写清 rescue action。
+不能用“工具不可用”当作模糊失败；要明确切 `local-handoff`、补 auth、刷新 review，
+还是返回 `cc-check`。
+
+rollback guard 必须在 publish、merge、PR 更新或 release note 前写清：
+
+- safe state
+- rollback command 或人工回退步骤
+- data / migration / package / remote side effect
+- owner
+
+没有 rollback guard 的 release 只能停在 handoff，不准发布。
+
 ## Readiness Dashboard
 
 PR / handoff 之前必须把 readiness 压成一屏事实：
@@ -289,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
 
@@ -301,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
@@ -316,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
 
@@ -330,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
 
@@ -340,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
 
@@ -354,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

@@ -24,6 +24,27 @@
 - Base branch:
 - PR / MR:
 
+## Ship Preflight
+
+- Branch:
+- Base:
+- Remote:
+- Local / remote HEAD:
+- Auth:
+- Clean tree:
+- Review freshness:
+- Ship mode:
+- `ShipPreflightError`:
+- Rescue action:
+
+## PR Branch Hygiene
+
+- Existing PR / MR:
+- Duplicate PR risk:
+- Commit split:
+- Push idempotency:
+- Body source:
+
 ## Review Range
 
 - Reviewed base SHA:
@@ -59,6 +80,13 @@
 - Fresh evidence:
 - Merged-result verification:
 
+## Rollback Guard
+
+- Safe state:
+- Rollback command / manual steps:
+- Side effects:
+- Owner:
+
 ## QA Behavior Evidence
 
 - Feedback loop:
@@ -74,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`: 
@@ -96,6 +134,7 @@
 - Key interfaces:
 - Acceptance criteria:
 - Out of scope:
+- Learning extraction target:
 
 ## Risks
 

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

@@ -20,6 +20,13 @@
 
 - 
 
+## Rollback Guard
+
+- Safe state:
+- Rollback command / manual steps:
+- Side effects:
+- Owner:
+
 ## QA Behavior Evidence
 
 - Feedback loop:
@@ -30,9 +37,18 @@
 
 - 
 
+## Roadmap Progress
+
+- Source RM:
+- Status after sync:
+- Progress after sync:
+- Follow-up writeback:
+- No-op reason:
+
 ## Follow-Ups
 
 - Current behavior:
 - Desired behavior:
 - Acceptance criteria:
 - Out of scope:
+- Learning extraction target:

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-check/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CC-Check Skill Changelog
 
+## v1.10.1 - 2026-04-29
+
+- add named runtime failure fields with artifact references, owners, and rescue actions
+- add human UAT evidence to the report card so manual acceptance can block or reroute honestly
+- require review findings to carry explicit rescue actions instead of vague follow-up text
+
 ## v1.10.0 - 2026-04-28
 
 - add test fixture honesty review for partial fixtures, generated stubs, casts, and missing mock payload fields

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

@@ -63,6 +63,8 @@ NO PASS WITHOUT FRESH EVIDENCE
 6. 把每个成功声明映射到 `claimEvidence[]`
 7. 行为变更必须补 `qa` 证据或例外理由
 8. 失败输出必须写入 `runtime.failureOwnership[]`
+9. failure ownership 必须包含 named error、artifact refs 和 rescue action
+10. human UAT 必须 pass、fail、blocked 或带 skip reason；失败不能被测试绿灯覆盖
 
 ## Verification Layers
 
@@ -76,6 +78,8 @@ NO PASS WITHOUT FRESH EVIDENCE
 8. Review freshness and confidence calibration
 9. Failure ownership
 10. Spec alignment and sync readiness
+11. Human UAT
+12. Named runtime errors and rescue actions
 
 ## Claim Evidence Matrix
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-check
-version: 1.10.0
+version: 1.10.1
 description: Use when a planned or investigated change needs fresh verification evidence, layered gate proof, review truth, and an honest pass fail blocked verdict before entering cc-act.
 triggers:
   - 验收这个需求
@@ -25,7 +25,7 @@ entry_gate:
   - Re-run fresh commands instead of inheriting cc-do narration.
   - If evidence is stale or missing, reset context and rebuild the verdict from canonical artifacts.
 exit_criteria:
-  - review/report-card.json records pass, fail, or blocked using fresh evidence, review freshness, claim evidence, QA coverage and browser evidence, failure ownership, plus spec alignment and sync readiness.
+  - review/report-card.json records pass, fail, or blocked using fresh evidence, review freshness, claim evidence, QA coverage and browser evidence, human UAT when applicable, named failure ownership, plus spec alignment and sync readiness.
   - Task-level review and requirement-level diff review are separated clearly.
   - 'The next step is unambiguous: cc-act, cc-do, cc-investigate, or cc-plan.'
 reroutes:
@@ -169,6 +169,12 @@ NO PASS WITHOUT FRESH EVIDENCE
 10. **Behavior Contract Layer**
    - expected / actual / reproduction steps 是否用用户和领域语言写清
    - follow-up 是否是行为契约，而不是易腐烂的文件行号 TODO
+11. **Human UAT Layer**
+   - 人工验收是否 required、skipped with reason、pass、fail 或 blocked
+   - failed UAT 必须 reroute 到 `cc-do`、`cc-investigate` 或 `cc-plan`
+12. **Named Error Layer**
+   - runtime failure 必须有 `errorName`、artifact refs、failure owner 和 rescue action
+   - invalid JSON、stale artifact、missing report 不能变成静默 `blocked`
 
 任何一层失真，都不能写 `pass`。
 
@@ -284,6 +290,13 @@ NO PASS WITHOUT FRESH EVIDENCE
 4. `environment` 必须记录缺失依赖、权限、服务、密钥或平台约束。
 5. `pass` 不能带未解释的 `in-branch` 或 `ambiguous` 失败。
 
+每条 failure ownership 还必须命名：
+
+- `errorName`：可搜索的错误名，例如 `MissingSpecReviewProof`
+- `artifactRefs`：指向 report、manifest、checkpoint、日志或命令输出
+- `rescueAction`：下一步救援动作，不写空泛“检查一下”
+- `owner`：`branch` / `baseline` / `environment` / `external` / `unknown`
+
 ## Entry Gate
 
 1. 先读 `planning/design.md` 或 `planning/analysis.md`，再读 `planning/tasks.md`、`planning/task-manifest.json`。