cc-devflow 4.3.0 → 4.5.0

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

@@ -0,0 +1,70 @@
+# CC-Act Skill Changelog
+
+## v1.6.2 - 2026-04-27
+
+- require closeout handoff documents to resolve the runtime output policy before writing PR briefs, release notes, resume indexes, or status handoffs
+- record `Output language` as the machine-enforced language contract while treating `agent_preferences` as advisory style input
+- render `Output language` metadata in generated PR briefs, release notes, resume indexes, and doc sync reports
+
+## v1.6.1 - 2026-04-25
+
+- remove external tool provenance from the public skill contract so ship and documentation release rules read as native `cc-act` behavior
+- keep idempotent ship, documentation audit, changelog protection, and PR regeneration requirements unchanged
+
+## v1.6.0 - 2026-04-24
+
+- add the native `cc-act` ship and documentation closeout contract
+- add ship hygiene rules for base detection, version/package/changelog drift, bisectable commits, final verification, push idempotency, and PR idempotency
+- strengthen documentation release rules so README/CLAUDE/architecture/handoff/changelog/TODO updates are audited from the final diff before PR or handoff
+- require PR bodies to be regenerated from current `cc-check`, scope drift, plan completion, verification, documentation, and test-plan facts
+
+Migration note:
+
+- new `create-pr` and `update-pr` closeouts should treat documentation sync and PR-body regeneration as first-class ship steps rather than optional post-processing
+
+## v1.5.0 - 2026-04-19
+
+- require `cc-act` to finish formal spec synchronization before ship closeout when `cc-check` marks `specSyncReady=true`
+- surface spec sync state and target capability files in `sync-act-docs.sh` outputs so closeout materials stay aligned with capability truth
+- tighten act entry rules so a passing report without spec readiness can no longer masquerade as a complete closeout
+
+Migration note:
+
+- change closeout now expects `change-meta.json`, related capability specs, and `report-card.json.specSyncReady`
+
+## v1.4.1 - 2026-04-18
+
+- compress duplicated commit-rule summaries in `SKILL.md` and `PLAYBOOK.md` so `references/git-commit-guidelines.md` stays the single truth source
+- keep only stage-level enforcement language in the main docs and move commit-detail semantics fully behind the reference
+- reduce drift risk between skill overview text and playbook execution text
+
+## v1.4.0 - 2026-04-18
+
+- add `references/git-commit-guidelines.md` as the canonical commit-history reference for `cc-act`
+- require `create-pr` and `update-pr` flows to generate commit messages and commit boundaries by that guideline instead of relying on vague "clear message" wording
+- surface the commit guideline in `Read First`, bundled resources, playbook integration steps, and working rules so commit generation has one explicit truth source
+
+## v1.3.0 - 2026-04-18
+
+- add an explicit pre-ship validation stage for `cc-simplify`, unit tests, and coordinator-directed e2e runs
+- require `create-pr` and `update-pr` flows to commit verified changes, push the branch, and use `gh pr create` or refresh the existing PR instead of duplicating it
+- tighten reroute rules so any simplify or test-driven code change sends the requirement back through `cc-check` before act can continue
+
+## v1.2.0 - 2026-04-17
+
+- add structured frontmatter contract fields so cc-act exposes ship-mode rules, reroutes, recovery, and tool budget directly in the skill
+- add `Harness Contract` and `Visible State Machine` to make closeout behavior readable without internal harness code
+- add memory-consolidation guidance so delivery truth is compressed into status, brief, and resume artifacts before handoff
+
+Migration note:
+
+- existing `pr-brief.md`, `status-report.md`, and `resume-index.md` files remain valid
+- registry and publish tooling now expect the new public frontmatter keys on this skill
+
+## v1.1.0 - 2026-04-15
+
+- add stronger trigger phrases in frontmatter
+- add `Quick Start` mode selector for first-use clarity
+- add `Minimum Output By Mode` to reduce overproduction
+- add `Good Output` criteria so ship materials stay concise and mode-aware
+- align protocol and read-first sections with versioned changelog workflow

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

@@ -0,0 +1,212 @@
+# CC-Act Playbook
+
+## Visible State Machine
+
+`cc-check -> cc-act -> roadmap/cc-plan next loop`
+
+- 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.
+- Reroute to: `cc-check` if verification changes, or `cc-do` if act uncovers unfinished implementation.
+
+## Core Thesis
+
+`cc-act` 的任务不是“再解释一遍”，而是把已经通过验证的事实推进成真正的交付状态。
+
+它接收 `cc-check` 的结果，但不复用 `cc-check` 的职责。
+
+- `cc-check` 解决：这次变更到底有没有被证明
+- `cc-act` 解决：这次被证明的变更到底怎么落地
+
+## Phase 0: Close The Gate
+
+开始前先做 3 件事：
+
+1. 运行 `scripts/verify-act-gate.sh --dir <requirement-dir>`
+2. 确认 `review/report-card.json` 是 `pass`，且没有未解释的 gaps / reroute
+3. 确认 `planning/tasks.md` 不再有未完成项
+
+如果 gate 没闭合，直接回 `cc-check` 或 `cc-do`，不要在 `cc-act` 自我安慰。
+
+## Phase 1: Freeze Ship Facts
+
+运行 `scripts/detect-ship-target.sh`，锁定这些事实：
+
+- current branch
+- base branch
+- platform / remote 能力
+- 是否已有 PR / MR
+- 推荐 ship 模式
+
+Ship 必须属于这 4 种模式之一：
+
+- `create-pr`
+- `update-pr`
+- `local-handoff`
+- `post-merge-closeout`
+
+这里不要只报事实，必须给出一句明确结论：
+
+- `Recommended mode: <mode>`
+- `Why now: <一句话理由>`
+- `Why not others: <一句话排除>`
+
+## Phase 2: Simplify And Refresh Proof
+
+在真正准备交付材料前，先做这 4 件事：
+
+1. 调用 `cc-simplify`
+   - 通过当前运行时可用的 skill 调用器执行
+   - 如果桥接环境暴露为 `${JM}`，使用 `${JM}` with `skill: "cc-simplify"`
+2. 跑项目单测
+   - 先检查 `package.json` scripts、`Makefile`、或项目常见测试入口
+   - 选择项目实际存在的命令执行
+3. 跑 e2e
+   - 严格遵守协调器 prompt 给出的 e2e recipe
+   - recipe 明确要求跳过时，只记录 skip 理由
+4. 一旦这三步里有任何修复改了代码，立即回 `cc-check`
+
+原则很简单：
+
+- `cc-act` 可以做清理和收尾修复
+- 但只要现实被改写，就必须重新证明
+
+## Phase 2.5: Ship Hygiene
+
+真正提交或推送前，先锁住 ship 卫生：
+
+1. 比较 `VERSION` / `package.json` / base branch，识别 `fresh`、`already bumped`、`stale package`、`unexpected drift`。
+2. 读取 changelog，不覆盖已有条目；新增或润色只能基于当前 diff 和 commit history。
+3. 检查提交边界，按逻辑单元拆分，保证提交顺序不引用未来代码。
+4. 如果有 WIP commit，只能用非破坏性 rebase / fixup 处理，不允许盲目 soft reset。
+5. push 前比较 local / remote HEAD；PR 前检查是否已有打开 PR / MR。
+
+## Phase 3: Build Delivery Pack
+
+先按模式整理最小材料：
+
+- `create-pr`: `handoff/pr-brief.md`
+- `update-pr`: 更新后的 `handoff/pr-brief.md`
+- `local-handoff`: `handoff/resume-index.md`
+- `post-merge-closeout`: doc sync 结果 + `handoff/release-note.md`（需要发布时）
+
+然后再补下面这些扩展材料：
+
+- `handoff/pr-brief.md`
+- `handoff/release-note.md`（需要发布时）
+- 更新后的 `handoff/resume-index.md`
+- `doc-sync-report.md`
+
+这些文件只允许写已经被证明过的事实，不准补编故事。
+
+建议顺序：
+
+1. `scripts/sync-act-docs.sh --dir <requirement-dir>`
+2. `scripts/render-pr-brief.sh --dir <requirement-dir>`
+
+## Phase 4: Sync Docs
+
+文档同步不是装饰动作，而是 ship 的一部分。
+
+同步规则：
+
+1. 代码结构变了，就同步对应目录的 `CLAUDE.md`
+2. 用户可感知行为变了，就同步 `README.md` / `handoff/release-note.md`
+3. handoff 路径变了，就同步 `handoff/resume-index.md`
+4. reviewer 如果看文档还得猜，就说明 sync 失败
+5. 新文档必须从 README、CLAUDE 或 handoff 入口可发现
+6. CHANGELOG 只允许保护性更新，不能重写历史
+7. doc sync 结果要进入 PR body 或 handoff，而不是只留在聊天里
+
+## Phase 5: Execute Integration
+
+### `create-pr`
+
+- 按 `references/git-commit-guidelines.md` 完成提交
+- 推送当前分支
+- 用 `gh pr create` 创建 PR / MR
+- PR body 以 `pr-brief.md` 为真相源，并包含 Summary、Test Coverage、Pre-Landing Review、Scope Drift、Plan Completion、Verification Results、Documentation、Test plan
+
+### `update-pr`
+
+- 如果有新增提交，先按 `references/git-commit-guidelines.md` 完成 commit / push
+- 不重新造一个 PR
+- 刷新已有 PR / MR body
+- 确保 body 由本次最新 `cc-check` 结果与 doc sync 状态重建，不沿用旧 body
+
+### `local-handoff`
+
+- 不假装已经 ship
+- 明确写出下一位接手者的入口、验证方式、阻塞点
+
+### `post-merge-closeout`
+
+- 不做 feature branch PR 动作
+- 完成 release note、文档同步、backlog/roadmap 回写、归档
+
+如果 `gh` 不可用、push 失败、远端不可达，就不要硬凹 `create-pr` / `update-pr`。切到 `local-handoff`，把阻塞和下一步写清楚。
+
+## Phase 6: Write Back The Learning
+
+以下情况必须回写 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`：
+
+1. 本次工作暴露了新的 follow-up
+2. 原有优先级被改变
+3. 有明确 deferred item 不能靠口头记忆保存
+
+原则：
+
+- 长期方向写 `devflow/roadmap/roadmap.md`
+- 下一轮待排队动作写 `devflow/roadmap/backlog.md`
+- 不要把噪音和碎念回写成系统真相
+
+## Phase 7: Declare The Next Entry
+
+`cc-act` 结束时必须留下一个明确入口：
+
+- requirement 真闭环：可归档，下一轮入口在 backlog / roadmap
+- requirement 未完全闭环：`handoff/resume-index.md` 必须告诉下一位从哪里接、怎么验、当前卡点是什么
+
+## Recommendation Test
+
+交付前过一遍这 4 个问题：
+
+1. 看完第一屏，别人能不能立刻知道 ship 模式？
+2. 材料是不是只覆盖当前模式真正需要的内容？
+3. reviewer / 接手者 还需不需要追问“所以我现在该看哪个文件”？
+4. `cc-simplify`、单测、e2e、commit/push 的结果是不是都能追溯？
+5. PR body / release note / handoff / changelog 说的是不是同一套现实？
+
+如果第 1 或第 3 题答案不是“能”，说明 `cc-act` 仍然太重或太糊。
+
+## Required Outputs
+
+- `handoff/pr-brief.md`
+- `handoff/release-note.md`（需要发布时）
+- 更新后的 `handoff/resume-index.md`
+- 更新后的 `CLAUDE.md` / README / 架构文档（如果结构或行为变了）
+- 必要时更新后的 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+
+## Local Kit
+
+- `assets/PR_BRIEF_TEMPLATE.md` 负责 reviewer / PR 交付骨架
+- `assets/RELEASE_NOTE_TEMPLATE.md` 负责对外发布骨架
+- `scripts/verify-act-gate.sh` 负责 gate 闭合校验
+- `scripts/detect-ship-target.sh` 负责分支与 PR 决策
+- `scripts/sync-act-docs.sh` 负责同步 requirement 级文档与 doc target 报告
+- `scripts/render-pr-brief.sh` 负责从 requirement 真相源渲染 `pr-brief.md`
+- `scripts/generate-status-report.sh` 负责汇总 requirement 与 ship 现状
+- `scripts/archive-requirement.sh` 负责 requirement 生命周期收尾
+- `cc-simplify` 负责在 ship 前压掉重复、坏味道、低效实现
+- `references/git-commit-guidelines.md` 负责提交规范真相源
+
+## Exit Smell
+
+如果用户看完结果还会问：
+
+- “所以现在是提 PR 还是先 handoff？”
+- “你真的跑过 simplify、单测、e2e 吗？”
+- “为什么要写 release note？”
+- “下一位到底从哪里开始接？”
+
+那这次 `cc-act` 还没有把复杂度压平。

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

@@ -0,0 +1,330 @@
+---
+name: cc-act
+version: 1.6.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
+  - 帮我发版
+  - 收尾
+  - ship this
+  - handoff
+  - close this requirement
+  - merge 之后怎么收口
+reads:
+  - PLAYBOOK.md
+  - CHANGELOG.md
+  - references/closure-contract.md
+  - references/git-commit-guidelines.md
+  - assets/PR_BRIEF_TEMPLATE.md
+  - assets/RELEASE_NOTE_TEMPLATE.md
+writes:
+  - path: devflow/changes/<change-key>/handoff/pr-brief.md
+    durability: durable
+    required: false
+    when: handoff mode is create-pr or update-pr
+    exclusive_group: handoff
+  - path: devflow/changes/<change-key>/handoff/resume-index.md
+    durability: durable
+    required: false
+    when: handoff mode is local resume
+    exclusive_group: handoff
+  - path: devflow/changes/<change-key>/handoff/release-note.md
+    durability: durable
+    required: false
+    when: handoff mode is release
+    exclusive_group: handoff
+effects:
+  - roadmap or 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.
+  - If simplify, tests, or act changes code or verification scope, return to cc-check immediately.
+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, and test evidence reflect the same proven facts.
+  - Follow-up items are written back to roadmap/backlog instead of lingering in chat memory.
+reroutes:
+  - when: Verification is stale, incomplete, or changed during act.
+    target: cc-check
+  - when: Act reveals unfinished implementation or unresolved review findings.
+    target: cc-do
+recovery_modes:
+  - name: memory-consolidation
+    when: Delivery evidence is scattered across checkpoints, reviews, and prior handoff notes.
+    action: Compress the current truth into handoff/pr-brief.md, handoff/resume-index.md, and handoff/release-note.md before any ship action continues.
+  - name: local-handoff-refresh
+    when: Remote push or PR tooling is unavailable but the requirement is otherwise ready to land.
+    action: Switch to local-handoff mode, refresh handoff/resume-index.md, and leave a verified next entry for the maintainer.
+tool_budget:
+  read_files: 8
+  search_steps: 5
+  shell_commands: 10
+---
+
+# CC-Act
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-act` 是 PDCA 里的 `Act + Ship`。
+
+它不再只是“写收尾文档”，而是负责把已经通过验证的现实推进到真正可接手、可 review、可发布、可回写的状态。
+
+一句话：`cc-check` 证明“东西已经好”，`cc-act` 负责把“已经好”变成“已经落地”。
+
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，PR brief、resume index、release note 和 status handoff 必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
+## Read First
+
+1. `PLAYBOOK.md`
+2. `CHANGELOG.md`
+3. `references/closure-contract.md`
+4. `references/git-commit-guidelines.md`
+
+## Use This Skill When
+
+- `cc-check` 已通过
+- 需要决定这次是 `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`
+- 需要把已验证的 spec delta 正式回写 capability spec 与 `devflow/specs/INDEX.md`
+- 需要让下一轮入口比现在更清楚
+
+如果 `review/report-card.json` 不是 `pass`，或 `specSyncReady` 不是 `true`，或者仍指向 `cc-do` / `cc-plan`，停止在这里，不准 ship。
+
+## Quick Start
+
+先回答一句话：**这次 verified work 应该以什么方式落地？**
+
+| 现实状态 | 直接选用模式 |
+| --- | --- |
+| 在 feature branch，远端可用，还没有 PR / MR | `create-pr` |
+| 在 feature branch，已经有打开的 PR / MR | `update-pr` |
+| 在 feature branch，但现在不推远端或工具不可用 | `local-handoff` |
+| 已在 base branch，或 requirement 已合并完成 | `post-merge-closeout` |
+
+如果 10 秒内还说不清属于哪一类，先停下，重新跑 `scripts/detect-ship-target.sh`。`cc-act` 不是猜模式的地方。
+
+## Harness Contract
+
+- Allowed actions: freeze ship facts, run simplify and required tests, sync docs, prepare landing materials, and execute the matching ship mode.
+- Forbidden actions: shipping with a stale report card, claiming readiness without simplify/test evidence or explicit skip evidence, inventing a fifth ambiguous mode, or continuing feature development inside act.
+- Required evidence: PR briefs, status reports, release notes, resume indexes, and test evidence must summarize already-proven facts only.
+- Reroute rule: changed verification goes back to `cc-check`; unfinished implementation or new fixes go back to `cc-do`.
+
+## Entry Gate
+
+1. 先读 `review/report-card.json`，只接受已通过且有证据的现实。
+2. 再读 `planning/design.md` 或 `planning/analysis.md`、`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json`、相关 capability spec；如果已有 `handoff/resume-index.md`，一并读取，确认这次到底完成了什么。
+3. 运行 `scripts/verify-act-gate.sh --dir <requirement-dir>`，确认 gate 真的闭合。
+4. 运行 `scripts/detect-ship-target.sh`，识别当前分支、base branch、PR 状态与推荐 ship 路径。
+5. 如果在 `cc-act` 期间因为 `cc-simplify`、单测、e2e、review 修复而改了代码，必须回 `cc-check`，不能带着旧证明继续 ship。
+
+## Ship Modes
+
+`cc-act` 只允许 4 种模式，避免“收尾”变成模糊动作：
+
+1. `create-pr`
+   - 当前在 feature branch
+   - 远端存在
+   - 当前没有 PR / MR
+2. `update-pr`
+   - 当前在 feature branch
+   - 已存在打开的 PR / MR
+   - 需要刷新 body、补文档、同步最新状态
+3. `local-handoff`
+   - 当前在 feature branch
+   - 暂不推远端，或远端工具不可用
+   - 但要把 handoff 与下一步写清楚
+4. `post-merge-closeout`
+   - 当前已在 base branch，或 requirement 已完成合并
+   - 重点是 release note、doc sync、backlog writeback、归档
+
+不要发明第五种模糊模式。
+
+## Minimum Output By Mode
+
+先做最小必要交付，再补充可选材料：
+
+1. `create-pr`
+   - 必须有 `handoff/pr-brief.md`
+   - 必须完成需要同步的 doc updates
+   - 新增提交必须遵守 `references/git-commit-guidelines.md`
+   - 远端可用时必须完成 commit、push、`gh pr create`
+2. `update-pr`
+   - 必须有更新后的 `handoff/pr-brief.md`
+   - 必须说明这次新增了什么验证或文档同步
+   - 必须避免重复创建 PR / MR
+   - 新增提交必须遵守 `references/git-commit-guidelines.md`
+   - 如果有新增提交，必须 push 并刷新 PR / MR 内容
+3. `local-handoff`
+   - 必须有更新后的 `handoff/resume-index.md`
+   - 必须写清接手入口、验证方式、当前阻塞
+4. `post-merge-closeout`
+   - 必须完成 doc sync
+   - 需要对外说明时生成 `handoff/release-note.md`
+   - 必须把 follow-up 回写到 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+
+不是每次都要把所有文件生成一遍。材料必须服务于当前 ship 模式，而不是为了流程好看。
+
+## Pre-Ship Validation
+
+在真正写交付材料或推远端之前，先把这 4 件事做完：
+
+1. `Simplify`
+   - 通过当前运行时可用的 skill 调用器调用 `cc-simplify`
+   - 如果桥接环境暴露为 `${JM}`，就按 `${JM}` + `skill: "cc-simplify"` 执行
+   - 目标不是再开发新范围，而是清理重复、坏味道、低效实现
+2. `Run unit tests`
+   - 先检查项目的标准测试入口，例如 `package.json` scripts、`Makefile`、`bun test`、`pytest`、`go test`
+   - 选择该项目实际存在的单测入口执行
+   - 失败就修，但修完必须回 `cc-check` 刷新证明
+3. `Test end-to-end`
+   - 严格按协调器 prompt 里的 e2e recipe 执行
+   - 如果 recipe 明确要求跳过，记录 skip 原因，不要伪造执行
+   - e2e 失败并导致代码修改时，同样回 `cc-check`
+4. `Commit and push`
+   - 只对 `create-pr` / `update-pr` 模式生效
+   - 所有验证通过后再 commit，并遵守 `references/git-commit-guidelines.md`
+   - push 当前分支，并用 `gh pr create` 创建 PR；已有 PR 时只更新，不重复创建
+   - `gh` 不可用、push 失败、远端不可达时，切到 `local-handoff` 并把阻塞写清楚
+
+这 4 步只接受两种结果：`全部完成` 或 `明确 reroute / handoff`。不要停在“差不多已经好了”。
+
+## Ship Discipline
+
+`cc-act` 的 ship 动作必须是幂等、可审计、可复跑的：
+
+1. Base and branch：识别 base branch、当前 branch、远端状态、已有 PR / MR，所有 diff/log/push 都基于同一个 base。
+2. Scope completion：PR 简报必须包含 `cc-check` 的 plan completion、scope drift、review finding、验证结果摘要。
+3. Version and changelog：如果项目有 `VERSION`、`package.json`、`CHANGELOG.md`，先判断是否已 bump / 是否漂移；不要重复 bump，也不要覆盖 changelog。
+4. Bisectable commits：提交按逻辑单元拆分，顺序保证每个 commit 独立可理解、尽量可验证；小于 50 行且少于 4 文件可单 commit。
+5. Fresh final verification：如果 `cc-act` 中的 review fix、doc sync、version sync 改了代码或运行时输入，重新回 `cc-check`；纯文档/PR body 变化记录即可。
+6. Push idempotency：push 前比较 local/remote HEAD；已同步就不重复 push，不可用就切 `local-handoff`。
+7. PR idempotency：已有打开的 PR / MR 只更新 body，不重复创建。
+
+## Documentation Release
+
+文档同步要作为发布链路的一部分，而不是 PR 后的人工补丁：
+
+1. Diff audit：按最终 diff/log 识别新增能力、行为变化、删除项、基础设施变化。
+2. Per-file audit：检查 README、CLAUDE、ARCHITECTURE、CONTRIBUTING、docs、handoff 是否与 diff 矛盾。
+3. Auto-update facts：路径、命令、计数、skill 列表、入口链接、明显过期事实可以直接更新。
+4. Risky narrative gate：产品定位、安全模型、架构哲学、大段删除、含义改变的 changelog 改写必须停下说明。
+5. Changelog protection：只允许润色既有条目或新增由当前 diff 支撑的条目，不能重写历史、删除已有发布说明。
+6. Discoverability：新增文档必须能从 README、CLAUDE 或 handoff 入口找到。
+7. TODO/backlog cleanup：只把有 diff 证据完成的事项移到 completed；新 follow-up 写回 backlog/roadmap。
+
+## Loop
+
+1. 先锁定 ship 事实：当前分支、base branch、PR 状态、requirement 状态。
+2. 调用 `cc-simplify`，清理重复、坏味道、低效实现；如果因此改了代码，回 `cc-check`。
+3. 运行项目单测；失败就修，修完回 `cc-check`。
+4. 按协调器 recipe 执行 e2e；如果 recipe 允许 skip，记录 skip 理由；如果失败并修复，回 `cc-check`。
+5. 先把 `change-meta.json.spec.syncStatus` 从 `planned/verified` 推进到 `synced`，并正式回写 capability spec 与 `devflow/specs/INDEX.md`；只在 spec truth 更新后继续交付材料。
+6. 只使用 `cc-check` 已经证明过的事实写交付材料，不编故事，不补脑。
+7. 同步文档：
+   - 结构变了，更新对应目录的 `CLAUDE.md`
+   - 用户可感知行为变了，更新 `README.md` / `handoff/release-note.md`
+   - handoff 变了，更新 `handoff/resume-index.md`
+8. 执行 documentation release audit：保护 changelog，检查 discoverability，记录 doc sync 结果。
+9. 生成 `handoff/pr-brief.md`，把需求、变更、验证证据、风险、文档同步状态一次写清。
+   - 优先运行 `scripts/sync-act-docs.sh --dir <requirement-dir>`
+   - 再运行 `scripts/render-pr-brief.sh --dir <requirement-dir>`
+10. 执行分支集成动作：
+   - `create-pr`：按 `references/git-commit-guidelines.md` 完成提交并推分支，再优先使用 `gh pr create` 创建 PR / MR
+   - `update-pr`：如果有新提交，先按 `references/git-commit-guidelines.md` 完成 commit / push，再刷新 PR / MR body，不沿用陈旧内容
+   - `local-handoff`：不假装已经发出，只生成可接手材料
+   - `post-merge-closeout`：跳过 PR，完成发布与闭环回写
+11. 处理 PR / MR body：从当前 `pr-brief.md`、最新验证、review、doc sync、TODO/backlog 结果重新渲染，不复用旧 body。
+12. 回写 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`：
+   - 新发现的 follow-up
+   - 被推迟但必须保留的事项
+   - 因本次结果而改变优先级的事项
+13. 如果 requirement 真正闭环，更新状态摘要并归档；否则把下一位接手者的入口写清楚。
+
+## Output
+
+- `handoff/pr-brief.md`
+- `handoff/release-note.md`（需要对外发布时）
+- 更新后的 `handoff/resume-index.md`
+- 同步后的 `CLAUDE.md` / README / 架构文档
+- 必要时更新后的 `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md`
+- 单测 / e2e 的通过证据，或明确记录的 skip / blocker
+- 必要时创建或更新的 PR / MR
+- PR / MR body 中的 Summary、Test Coverage、Pre-Landing Review、Scope Drift、Plan Completion、Verification Results、Documentation、Test plan
+
+## Good Output
+
+一个好的 `cc-act` 结果应该让 reviewer 或下一位接手者不用追问：
+
+- 这次到底选了哪种 ship 模式，为什么不是另外三种
+- 哪些材料已经准备好，哪些刻意不需要
+- 现在谁都可以顺着 `handoff/pr-brief.md` 或 `handoff/resume-index.md` 继续往前走
+- 文档、PR 描述、release note 说的是同一套现实
+- `cc-simplify`、单测、e2e、commit/push 的结果都能被接手者追溯
+
+## Bundled Resources
+
+- 变更记录：`CHANGELOG.md`
+- 契约：`references/closure-contract.md`
+- 模板：`assets/PR_BRIEF_TEMPLATE.md`
+- 模板：`assets/RELEASE_NOTE_TEMPLATE.md`
+- 提交规范：`references/git-commit-guidelines.md`
+- 状态摘要：`scripts/generate-status-report.sh`
+- Gate 校验：`scripts/verify-act-gate.sh`
+- Ship 目标识别：`scripts/detect-ship-target.sh`
+- 文档同步：`scripts/sync-act-docs.sh`
+- PR 简报生成：`scripts/render-pr-brief.sh`
+- requirement 归档：`scripts/archive-requirement.sh`
+
+## Working Rules
+
+1. `cc-check` 没过，不准 ship。
+2. 没有新鲜证据的完成结论，不准进入交付材料。
+3. 交付材料只总结现实，不重写历史。
+4. 文档必须与最终代码和 ship 状态同构。
+5. 分支决策必须明确属于 4 种模式之一，不要含糊。
+6. 已存在 PR / MR 时，优先更新，不重复创建。
+7. `cc-simplify`、单测、e2e 任何一步只要导致代码变化或验证口径变化，必须回 `cc-check`。
+8. `devflow/roadmap/backlog.md` / `devflow/roadmap/roadmap.md` 只回写真正改变优先级或产生 follow-up 的事项，不写噪音。
+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 或旧测试输出。
+
+## Exit Criteria
+
+- gate 闭合且现实一致
+- ship 模式已明确并执行到位
+- reviewer / maintainer 能直接接手
+- 需要同步的文档已经同步
+- `cc-simplify`、单测、e2e 已执行完毕，或 skip / blocker 已被明确记录
+- follow-up 已回写到正确的 backlog / roadmap 位置
+- 下一轮该怎么继续已经写清楚
+- requirement 不是“看起来结束”，而是真正闭环
+
+## Do Not
+
+- 不把发布动作偷偷塞回 `cc-check`
+- 不拿旧测试输出冒充当前事实
+- 不跳过 `cc-simplify`、单测、e2e 却声称 ready
+- 不重复创建 PR / MR
+- 不让 handoff 只停留在口头描述
+- 不留“下次再说”的关键空洞
+- 不在 `cc-act` 阶段继续偷偷开发新范围
+
+## Companion Files
+
+- 深入剧本：`PLAYBOOK.md`
+- 变更记录：`CHANGELOG.md`
+- 收尾契约：`references/closure-contract.md`
+- 提交规范：`references/git-commit-guidelines.md`

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

@@ -0,0 +1,68 @@
+# PR Brief
+
+## Document Meta
+
+- Output language:
+
+## Decision
+
+- Recommended mode:
+- Why now:
+- Why not others:
+
+## Requirement
+
+- 
+
+## Ship Mode
+
+- `create-pr` / `update-pr` / `local-handoff` / `post-merge-closeout`
+
+## Branch Context
+
+- Current branch:
+- Base branch:
+- PR / MR:
+
+## Summary
+
+- 
+
+## What Changed
+
+- 
+
+## Verification Evidence
+
+- `review/report-card.json` verdict:
+- Fresh evidence:
+
+## Documentation Sync
+
+- `CLAUDE.md`:
+- `README.md`:
+- `release-note.md`:
+- `resume-index.md`:
+
+## Consolidated Memory
+
+- `handoff path`: 
+- latest checkpoint / review summary:
+- handoff entry for the next maintainer:
+
+## Minimum Landing Pack
+
+- Required for this mode:
+- Intentionally omitted:
+
+## How To Verify
+
+- 
+
+## Follow-Ups
+
+- 
+
+## Risks
+
+-