cc-devflow 4.5.8 → 4.5.10

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

@@ -1,5 +1,38 @@
 # CC-Act Skill Changelog
 
+## v1.8.8 - 2026-05-12
+
+- require `cc-devflow query workflow-context` before ship work so `cc-act` confirms the context-index next action before opening delivery artifacts
+- make deep closeout reads conditional on ship-mode, rollback, roadmap-sync, or postmortem triggers
+- keep `ship-readiness` as the hard readiness query while using workflow context for the end-to-end PDCA/IDCA handoff
+
+## v1.8.7 - 2026-05-11
+
+- add project-level AI postmortem writeback under `devflow/postmortems/` for FIX closeout and recurring AI/process/engineering failures
+- add index, principle, and incident templates with progressive disclosure, Git evidence, verification evidence, and prevention summaries
+- make `cc-act` the default postmortem writer because ship closeout has the verified review range, branch state, commits, PR/handoff, and follow-up truth
+- add a Redaction Guard so project postmortems preserve evidence without copying secrets, customer data, private logs, or personal machine paths
+- make post-merge archive a hard closeout gate instead of a soft next-action suggestion
+- require `cc-devflow archive-change <change-key>` plus archive-path proof for `post-merge-closeout`
+- allow skipping archive only with an explicit `ArchiveSkip` blocker and retry command in handoff material
+
+## v1.8.6 - 2026-05-11
+
+- add a language-aware Pull Request Body Contract so `create-pr` and `update-pr` derive PR title/body language from runtime `Output language`
+- render a detailed PR body draft in `pr-brief.md` with summary, problem, changes, validation, review/gate evidence, risk/rollback, docs/writeback, and follow-ups
+- block shallow PR descriptions by requiring current diff/report-card/doc-sync/roadmap facts, real validation evidence, and no leftover placeholders before `gh pr create` or `gh pr edit`
+
+## v1.8.5 - 2026-05-11
+
+- expand `references/git-commit-guidelines.md` from title-only guidance into a structured commit-record contract with problem, change, rationale, validation, risk, and refs sections
+- require Chinese commit subjects and body text for Chinese output contexts while keeping the Conventional Commits `type(scope)` prefix machine-readable
+- add type-specific commit body templates so fixes carry root cause, tests carry real seam evidence, and docs/tooling commits explain validation and risk instead of shipping one-line summaries
+
+## v1.8.4 - 2026-05-11
+
+- prefer `change-meta.json` for roadmap sync and spec file summaries so `task-manifest.json` stays focused on execution state
+- keep backward-compatible manifest fallback for older change folders while preserving one owner for roadmap/spec status
+
 ## v1.8.3 - 2026-05-11
 
 - add `ensure-ship-branch.sh` so detached HEAD closeouts can create a named branch and continue toward `create-pr`

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

@@ -140,6 +140,7 @@ Ship 必须属于这 4 种模式之一：
 - QA behavior evidence and feedback-loop quality
 - readiness dashboard
 - PR body accuracy check
+- Pull Request Body Draft: 按 `Output language` 生成中文或英文 PR 正文草稿，包含 summary/problem/changes/validation/review-gate/risk-rollback/docs-writeback/follow-ups
 - Durable follow-up briefs: current behavior、desired behavior、key interfaces、acceptance criteria、out of scope
 
 缺这些字段时，可以生成 local handoff，但不能声称 PR body 已经可 review。
@@ -166,15 +167,16 @@ Ship 必须属于这 4 种模式之一：
 - 如果当前是 detached HEAD，先运行 `scripts/ensure-ship-branch.sh --dir <requirement-dir>`
 - 推送当前分支
 - 用 `gh pr create` 创建 PR / MR
-- PR body 以 `pr-brief.md` 为真相源，并包含 Summary、Test Coverage、Pre-Landing Review、Readiness Dashboard、Scope Drift、Plan Completion、Verification Results、Documentation、Test plan
-- 创建前检查 PR body 是否来自当前 report-card 和当前 diff，不继承旧 body
+- PR body 以 `pr-brief.md` 的 `Pull Request Body Draft` 为真相源，并按 `Output language` 输出中文或英文
+- PR body 必须包含 Summary/摘要、Problem/问题、Changes/变更、Validation/验证、Review/Gate Evidence、Risk/Rollback、Docs/Writeback、Follow-ups
+- 创建前检查 PR body 是否来自当前 report-card、当前 diff、doc sync 和 roadmap writeback，不继承旧 body、不保留 `<placeholder>`、不只写一句泛化摘要
 
 ### `update-pr`
 
 - 如果有新增提交，先按 `references/git-commit-guidelines.md` 完成 commit / push
 - 不重新造一个 PR
 - 刷新已有 PR / MR body
-- 确保 body 由本次最新 `cc-check` 结果与 doc sync 状态重建，不沿用旧 body
+- 确保 body 由本次最新 `cc-check` 结果、doc sync 状态和 `Pull Request Body Draft` 重建，不沿用旧 body
 - PR body 与当前 commits / diff 不一致时，必须先更新 body，再继续交付判断
 
 ### `local-handoff`
@@ -187,6 +189,7 @@ Ship 必须属于这 4 种模式之一：
 - 不做 feature branch PR 动作
 - 在 merged result 上重跑必要 gate，并记录命令、exit status、关键观察
 - 完成 release note、文档同步、backlog/roadmap 回写、归档
+- 归档是 exit gate：运行 `cc-devflow archive-change <change-key>`，再用 archive path 或 `cc-devflow list-archived` 证明 active change 已离开 `devflow/changes/<change-key>`
 
 ### destructive cleanup
 
@@ -219,7 +222,7 @@ Ship 必须属于这 4 种模式之一：
 
 `cc-act` 结束时必须留下一个明确入口：
 
-- requirement 真闭环：可归档，下一轮入口在 backlog / roadmap
+- requirement 真闭环：已经归档，下一轮入口在 backlog / roadmap
 - requirement 未完全闭环：`handoff/resume-index.md` 必须告诉下一位从哪里接、怎么验、当前卡点是什么
 
 ## Recommendation Test
@@ -236,6 +239,7 @@ Ship 必须属于这 4 种模式之一：
 8. ship preflight failure 是否有 `ShipPreflightError`、artifact ref 和 rescue action？
 9. rollback guard 是否足够让下一位维护者不靠聊天记录回退？
 10. source RM 的 status、REQ/FIX、progress 是否已经和 ship 现实一致？
+11. `post-merge-closeout` 是否已经跑过 `cc-devflow archive-change <change-key>`，并留下 archive path？如果没有，是否有明确 `ArchiveSkip` blocker 和 retry command？
 
 如果第 1 或第 3 题答案不是“能”，说明 `cc-act` 仍然太重或太糊。
 
@@ -246,6 +250,7 @@ Ship 必须属于这 4 种模式之一：
 - 更新后的 `handoff/resume-index.md`
 - 更新后的 `CLAUDE.md` / README / 架构文档（如果结构或行为变了）
 - 必要时更新后的 `devflow/roadmap.json` / `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+- `post-merge-closeout` 必须留下 archive path；未归档只能留下 `ArchiveSkip` blocker，不能宣称闭环完成
 
 ## Local Kit
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-act
-version: 1.8.3
+version: 1.8.8
 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,10 @@ reads:
   - references/git-commit-guidelines.md
   - assets/PR_BRIEF_TEMPLATE.md
   - assets/RELEASE_NOTE_TEMPLATE.md
+  - assets/PROJECT_POSTMORTEM_TEMPLATE.md
+  - assets/PROJECT_POSTMORTEM_INDEX_TEMPLATE.md
+  - assets/PROJECT_POSTMORTEM_PRINCIPLES_TEMPLATE.md
+  - docs/guides/project-postmortem.md
   - ../cc-roadmap/scripts/locate-roadmap-item.sh
   - ../cc-roadmap/scripts/sync-roadmap-progress.sh
   - scripts/ensure-ship-branch.sh
@@ -36,17 +40,34 @@ writes:
     required: false
     when: handoff mode is release
     exclusive_group: handoff
+  - path: devflow/postmortems/INDEX.md
+    durability: durable
+    required: false
+    when: closing a FIX or recurring AI/process/engineering failure
+  - path: devflow/postmortems/principles.md
+    durability: durable
+    required: false
+    when: an incident yields a generalized model or engineering lesson
+  - path: devflow/postmortems/incidents/<date>-<change-key>.md
+    durability: durable
+    required: false
+    when: closing a FIX or recurring AI/process/engineering failure
 effects:
   - roadmap progress and backlog follow-up updates when needed
 entry_gate:
+  - Run `cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --data-only --no-trace --compact` first; continue only when it reports `nextAction.skill == "cc-act"`.
   - 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.
+  - For FIX closeout or recurring AI/process/engineering failures, update the project postmortem under `devflow/postmortems/` before final ship/handoff material is declared complete.
+  - 'For `post-merge-closeout`, freeze the archive target and run `cc-devflow archive-change <change-key>` after release note and roadmap writeback; only skip with an explicit `ArchiveSkip` blocker in the handoff.'
 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.
+  - FIX closeout and recurring failures have a progressive project postmortem entry with factual Git evidence, prevention summary, and principle extraction decision.
+  - '`post-merge-closeout` has archived the closed change under `devflow/changes/archive/YYYY-MM/`, or the handoff records an explicit `ArchiveSkip` blocker with the exact retry command.'
   - 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.
@@ -55,7 +76,7 @@ reroutes:
     target: cc-do
 recovery_modes:
   - name: memory-consolidation
-    when: Delivery evidence is scattered across checkpoints, reviews, and prior handoff notes.
+    when: Delivery evidence is scattered across task state, reviews, CLI logs, 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.
@@ -92,6 +113,7 @@ tool_budget:
 2. `CHANGELOG.md`
 3. `references/closure-contract.md`
 4. `references/git-commit-guidelines.md`
+5. `docs/guides/project-postmortem.md`
 
 ## Use This Skill When
 
@@ -126,18 +148,44 @@ tool_budget:
 - 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`.
 
+## Project Postmortem Writeback
+
+`cc-act` 是项目级 AI 尸检报告的唯一默认写入者，因为它能看到 verified reality、Git 状态、review range、ship mode 和 follow-up。
+
+固定位置：
+
+- `devflow/postmortems/INDEX.md`
+- `devflow/postmortems/principles.md`
+- `devflow/postmortems/incidents/<date>-<change-key>.md`
+
+触发条件：
+
+1. 当前 change key 是 `FIX-*`。
+2. `cc-check` / `cc-act` 暴露重复的 AI、流程、测试、release、Git 或架构错误。
+3. 用户明确要求记录一次教训。
+
+写入规则：
+
+1. 先用 `assets/PROJECT_POSTMORTEM_TEMPLATE.md` 写具体 incident；事实必须包含 branch、base/head SHA、review range、相关 commits、PR/handoff、验证命令和关键输出。
+2. 再更新 `INDEX.md` 的短入口：日期、change、severity、tags、one-line lesson、incident 链接。
+3. 只有能从 incident 和 Git 证据提炼出可迁移规则时，才更新 `principles.md`；原则必须引用 incident 和 Git 证据。
+4. 报告使用渐进式披露：默认层只给检索和提醒，深层 incident 才放完整时间线、根因、逃逸原因和验证记录。
+5. 写入前执行 Redaction Guard：不要复制 secret、token、客户数据、个人机器路径或私密原始日志；必要证据用 `<redacted>` 和 redaction summary 表达。
+6. 尸检报告不拥有 roadmap、task、review 或 spec 状态；只能引用对应 owner artifact 和 Git 证据。
+
 ## 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 路径。
+1. 先运行 `cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --data-only --no-trace --compact`，确认 context index 的 `nextAction.skill == "cc-act"`。
+2. 再读 `review/report-card.json`，只接受已通过且有证据的现实。
+3. 默认只使用 workflow context 的 `packetOnly`、`mustNotForget` 和 `sourceHashes`；必要时打开 `progressiveDisclosure.defaultOpen` 的 section / JSON refs；只有 ship mode、roadmap sync、rollback、hash mismatch 或 postmortem 触发时，再读 `deepOpen` 里的完整 `planning/design.md` / `planning/analysis.md`、`planning/tasks.md`、完整 manifest、change-meta、相关 capability spec 或 `handoff/resume-index.md`。
+4. 运行 `scripts/verify-act-gate.sh --dir <requirement-dir>`，确认 gate 真的闭合。
+5. 运行 `scripts/detect-ship-target.sh`，识别当前分支、base branch、PR 状态与推荐 ship 路径。
    - 如果输出 `BRANCH_STATE=detached` 且 `BRANCH_RESCUE=create-branch-before-pr`，这不是阻塞；立即运行 `scripts/ensure-ship-branch.sh --dir <requirement-dir>`，然后重跑最终验证与 `detect-ship-target.sh`。
    - 用户已经表达“继续 / 提交远程 PR / 推进”的场景下，detached HEAD 只能触发分支锚定，不能把 `create-pr` 降级成 `local-handoff`。
-5. 检查 `review.freshness`、`runtime.failureOwnership`、`qa.coverageAudit`、`qa.browserEvidence`，确认 readiness dashboard 没有 blocker。
-6. 检查 `qa.feedbackLoop`、`qa.behaviorEvidence`、`qa.architectureFollowUps` 和 follow-up brief，确认交付材料继承的是行为证据，不是聊天记忆或易腐烂 TODO。
-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。
+6. 检查 `review.freshness`、`runtime.failureOwnership`、`qa.coverageAudit`、`qa.browserEvidence`，确认 readiness dashboard 没有 blocker。
+7. 检查 `qa.feedbackLoop`、`qa.behaviorEvidence`、`qa.architectureFollowUps` 和 follow-up brief，确认交付材料继承的是行为证据，不是聊天记忆或易腐烂 TODO。
+8. 定位 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。
+9. 如果在 `cc-act` 期间因为 `cc-simplify`、单测、e2e、review 修复而改了代码，必须回 `cc-check`，不能带着旧证明继续 ship。
 
 ## Ship Modes
 
@@ -185,6 +233,7 @@ tool_budget:
    - 必须完成 doc sync
    - 需要对外说明时生成 `handoff/release-note.md`
    - 必须把 follow-up 回写到 `devflow/roadmap.json`，并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+   - 必须运行 `cc-devflow archive-change <change-key>` 归档已闭环 change；除非存在明确安全阻塞并写入 `ArchiveSkip`
 
 不是每次都要把所有文件生成一遍。材料必须服务于当前 ship 模式，而不是为了流程好看。
 
@@ -269,6 +318,16 @@ PR / handoff 之前必须把 readiness 压成一屏事实：
 
 readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute 到 `cc-check` / `cc-do` 或生成 local handoff。
 
+## Pull Request Body Template Contract
+
+PR body 不是聊天摘要，而是 reviewer 的第一份执行材料。`create-pr` / `update-pr` 必须从当前事实生成一版可直接提交的 PR body draft：
+
+1. Language decision：读取 `Output language`。中文项目输出中文 PR 标题和正文；英文项目输出英文 PR 标题和正文；`type(scope)`、路径、命令、issue key、REQ/FIX/RM ID 保持机器可读。
+2. Required shape：必须包含 summary、problem、changes、validation、review/gate evidence、risk/rollback、docs/writeback、follow-ups。
+3. Evidence density：validation 不能只有“tests passed”，必须列命令、退出结果或关键观察；review/gate evidence 必须带 reviewed base/head SHA、finding triage、QA/claim evidence 和 readiness 摘要。
+4. Freshness：已有 PR body 只能作为远端旧状态参考，不能继承；每次 `gh pr create` / `gh pr edit` 前都用当前 `handoff/pr-brief.md`、当前 diff、当前 report-card、doc sync 和 roadmap writeback 重建。
+5. Completeness gate：空标题、`<placeholder>`、泛化句子、缺少风险/回滚边界、缺少文档/回写状态时，不准创建或更新 PR。
+
 ## Integration Safety
 
 `cc-act` 可以清理交付路径，但不能悄悄做破坏性动作：
@@ -330,7 +389,8 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
    - 被推迟但必须保留的事项
    - 因本次结果而改变优先级的事项
 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 真正闭环，更新状态摘要并归档：运行 `cc-devflow archive-change <change-key>` 将已完成变更移入 `devflow/changes/archive/YYYY-MM/`；否则把下一位接手者的入口写清楚。
+15. 如果 ship mode 是 `post-merge-closeout`，归档不是建议而是 exit gate：运行 `cc-devflow archive-change <change-key>` 将已完成变更移入 `devflow/changes/archive/YYYY-MM/`，然后用 `cc-devflow list-archived` 或文件路径确认归档成功。
+16. 只有在归档会丢失未合并证据、用户明确要求保留 active change、或 archive target 已冲突时，才允许跳过；跳过必须在 handoff 写 `ArchiveSkip`、原因、受影响路径、以及精确 retry command。
 
 ## Output
 
@@ -341,8 +401,9 @@ readiness dashboard 有 blocker 时，不能创建或更新 PR，只能 reroute
 - 必要时更新后的 `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
+- PR / MR body 中按 `Output language` 生成的 Summary/摘要、Problem/问题、Changes/变更、Validation/验证、Review/Gate Evidence、Risk/Rollback、Docs/Writeback、Follow-ups
 - readiness dashboard 和 PR body accuracy check
+- `post-merge-closeout` 的 archive path，或显式 `ArchiveSkip` blocker
 
 ## Good Output
 

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

@@ -0,0 +1,30 @@
+# Project Postmortem Index
+
+## How To Search
+
+Start here, then open only the incident files whose tags or failure class match
+the current work.
+
+```bash
+rg -n "<capability|module|error|failure-class|model-risk>" devflow/postmortems
+```
+
+## Latest Entries
+
+| Date | Change | Severity | Tags | One-line lesson | Incident |
+| --- | --- | --- | --- | --- | --- |
+|  |  | low / medium / high |  |  | `incidents/<date>-<change-key>.md` |
+
+## Recurring Patterns
+
+| Pattern | Count | Last seen | Principle |
+| --- | ---: | --- | --- |
+|  | 0 |  | `principles.md#` |
+
+## Deep-Dive Rules
+
+- Open `principles.md` when the current work involves architecture choices,
+  test-seam design, model judgment, reliability, release hygiene, or recurring
+  review findings.
+- Open a specific incident file when the current task touches the same module,
+  failure class, or Git/release workflow.

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

@@ -0,0 +1,29 @@
+# Project Postmortem Principles
+
+This file stores generalized lessons extracted from concrete incidents. Keep each
+principle short enough to scan, but cite the incident file and Git evidence that
+made it real.
+
+## Principles
+
+### PM-P001 <principle title>
+
+- Failure class:
+- Model limitation or professional judgment trap:
+- Rule:
+- Countermeasure before planning:
+- Countermeasure before coding:
+- Countermeasure before shipping:
+- Evidence:
+  - Incident: `devflow/postmortems/incidents/<date>-<change-key>.md`
+  - Git: `<commit-or-range>`
+- Search terms:
+
+## Candidate Principles
+
+Use this section for patterns that appeared once but are not yet strong enough to
+be promoted.
+
+| Candidate | Evidence | Promotion trigger |
+| --- | --- | --- |
+|  |  | repeats, high severity, or architecture-wide impact |

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

@@ -0,0 +1,103 @@
+# <date> <change-key> Postmortem
+
+## Progressive Disclosure Index
+
+- Default read: Summary, Search Tags, Prevention Summary, Git Evidence.
+- Open for recurrence: Root Cause, AI Failure Mode, Why It Escaped.
+- Open for audit: Timeline, Verification Evidence, Follow-up Actions.
+
+## Summary
+
+- Change:
+- Incident / failure:
+- Severity: low / medium / high
+- Impact:
+- Current status: repaired / mitigated / deferred / monitoring
+- Owner:
+
+## Search Tags
+
+- Capabilities:
+- Modules:
+- Failure class:
+- Model-risk tags:
+- Related principles:
+
+## Prevention Summary
+
+- Do this next time:
+- Do not do this next time:
+- Planning reminder:
+- Investigation reminder:
+- Execution reminder:
+- Ship reminder:
+
+## Git Evidence
+
+- Base branch:
+- Working branch:
+- Base SHA:
+- Head SHA:
+- Review range:
+- Relevant commits:
+- PR / handoff:
+- Dirty-tree notes:
+- Commands used:
+  - `git status -sb`
+  - `git log --oneline --decorate -n 12`
+  - `git diff --stat <base>...HEAD`
+
+## Redaction Guard
+
+- Sensitive values copied: yes / no
+- Redacted values:
+  - `<redacted>`:
+- Private logs or customer data omitted:
+- Evidence shape preserved without raw sensitive value:
+
+## Timeline
+
+| Time | Event | Evidence |
+| --- | --- | --- |
+|  |  |  |
+
+## Root Cause
+
+- Confirmed root cause:
+- Broken contract:
+- Rejected near-causes:
+- Why symptom-site fix was insufficient:
+
+## AI Failure Mode
+
+- Model limitation:
+- Bad default behavior observed:
+- Missing evidence or professional rule:
+- Countermeasure:
+
+## Why It Escaped
+
+- Planning gap:
+- Investigation gap:
+- Execution gap:
+- Review / verification gap:
+- Ship / handoff gap:
+
+## Verification Evidence
+
+| Command / artifact | Result | Key observation |
+| --- | --- | --- |
+|  |  |  |
+
+## Follow-up Actions
+
+| Type | Action | Owner | Target |
+| --- | --- | --- | --- |
+| root-cause-fix / detection / docs / backlog / principle |  |  |  |
+
+## Principle Extraction
+
+- Promote to `principles.md`: yes / no
+- Principle title:
+- Search terms:
+- Incident file linked from `INDEX.md`: yes / no

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

@@ -66,13 +66,69 @@
 - Documentation release:
 - PR body accuracy:
 
+## Pull Request Body Contract
+
+- Language source: `Output language: <value from report-card>`
+- PR body language: `中文` / `English`
+- Title rule: same language as the PR body after the Conventional Commits `type(scope)` prefix; keep identifiers, paths, commands, and issue keys unchanged.
+- Body source: current `pr-brief.md`, current diff, current `review/report-card.json`, doc sync output, and roadmap/backlog writeback.
+- Required sections: summary, problem, changes, validation, review/gate evidence, risk/rollback, docs/writeback, follow-ups.
+- Completeness gate: no empty headings, no stale inherited PR body, no generic "tests passed" without command or evidence, and no `<placeholder>` text before `gh pr create` or `gh pr edit`.
+
+## Pull Request Body Draft
+
+```markdown
+## Summary / 摘要
+
+- TBD
+
+## Problem / 问题
+
+- Requirement / 需求:
+- User-visible gap / 用户可见缺口:
+
+## Changes / 变更
+
+- TBD
+
+## Validation / 验证
+
+- `report-card.json` verdict / 结论:
+- Commands / 命令:
+- Key observations / 关键观察:
+
+## Review / Gate Evidence
+
+- Reviewed base SHA:
+- Reviewed head SHA:
+- Review packet:
+- Finding triage:
+- QA / claim evidence:
+- Readiness:
+
+## Risk And Rollback / 风险与回滚
+
+- Main risk / 主要风险:
+- Rollback boundary / 回滚边界:
+
+## Docs And Writeback / 文档与回写
+
+- `CLAUDE.md`:
+- `README.md`:
+- Roadmap progress:
+
+## Follow-ups / 后续事项
+
+- TBD
+```
+
 ## Summary
 
-- 
+- TBD
 
 ## What Changed
 
-- 
+- TBD
 
 ## Verification Evidence
 
@@ -115,7 +171,7 @@
 ## Consolidated Memory
 
 - `handoff path`: 
-- latest checkpoint / review summary:
+- latest task-state / review summary:
 - handoff entry for the next maintainer:
 
 ## Minimum Landing Pack
@@ -125,7 +181,7 @@
 
 ## How To Verify
 
-- 
+- TBD
 
 ## Follow-Ups
 
@@ -138,4 +194,4 @@
 
 ## Risks
 
-- 
+- TBD

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

@@ -12,6 +12,7 @@
 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
+11. `post-merge-closeout` 必须预先冻结 archive target；最终只能是已归档，或带 `ArchiveSkip` blocker 的未完成 closeout
 
 ## Ship Decision Contract
 
@@ -43,6 +44,7 @@ detached HEAD 是分支事实，不是第 5 种 ship 模式。若远端可用且
 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`
+14. `post-merge-closeout` 的归档必须真实执行：`cc-devflow archive-change <change-key>`，不能只把“可归档”写进 next action
 
 ## Memory Consolidation
 
@@ -52,7 +54,7 @@ detached HEAD 是分支事实，不是第 5 种 ship 模式。若远端可用且
 - `handoff/resume-index.md`（需要 handoff 时）
 - `handoff/release-note.md`（需要发布时）
 
-如果下一位接手者还得去翻零散 checkpoint 才知道从哪接，说明 act 还没收口。
+如果下一位接手者还得去翻零散过程笔记才知道从哪接，说明 act 还没收口。
 
 ## After Closing
 
@@ -63,5 +65,6 @@ detached HEAD 是分支事实，不是第 5 种 ship 模式。若远端可用且
 - QA behavior evidence 和 feedback loop 已进入 PR / handoff / release 材料
 - post-merge closeout 反映 merged result 的验证事实，而不是只反映合并前事实
 - source RM 的 status、REQ/FIX 绑定、progress 和 follow-up 已经落入 roadmap truth
+- closed change 已经移动到 `devflow/changes/archive/YYYY-MM/<change-key>`；如果没有，必须有 `ArchiveSkip` blocker、原因、受影响路径和 retry command
 - 下一轮计划入口更清楚
 - 文档入口可发现，changelog 不丢历史，TODO / backlog 只记录有证据的事项