cc-devflow 4.5.8 → 4.5.10

package/.claude/skills/cc-review/references/plan-review-branch.md

@@ -137,7 +137,7 @@ Each planning smell must become a plan finding and route to `cc-plan`.
 
 ## Output Requirements
 
-Add to `cc-review-report.md`:
+Record in `review-ledger.jsonl` and render on-demand Markdown when a human report is needed:
 
 - plan review nodes checked, skipped, or blocked
 - plan reviewer agents used or fallback reason

package/.claude/skills/cc-review/references/review-methods.md

@@ -4,7 +4,7 @@ Use this reference for every `cc-review` run. It defines the shared method libra
 
 ## Method Selection
 
-Select every method needed by the current risk and write the selected methods into `cc-review-plan.md`. This table is a routing map, not a cap.
+Select every method needed by the current risk and write the selected methods into the `review-started` event in `review-ledger.jsonl`. This table is a routing map, not a cap.
 
 | Risk | Method |
 | --- | --- |
@@ -53,7 +53,7 @@ Assignment rules:
 
 - Assign independent reviewers by facet, not by random file chunks.
 - Keep each reviewer packet self-contained: scope, delta, node ids, required artifacts, reference to use, and output schema.
-- Do not ask one reviewer to wait for another reviewer result unless the dependency is explicit in `cc-review-plan.md`.
+- Do not ask one reviewer to wait for another reviewer result unless the dependency is explicit in `review-ledger.jsonl`.
 - Do not assign two reviewers to the same node unless a critical finding needs a second opinion.
 - Main thread validates reviewer evidence before final findings.
 
@@ -66,7 +66,7 @@ downgraded -> real note but not blocking or confidence too low
 rejected   -> out-of-scope, stale, speculative, or contradicted by evidence
 ```
 
-Record these states in `cc-review-report.md` and preserve raw reviewer output in `cc-review-agent-results.jsonl`.
+Record these states in `review-ledger.jsonl` or on-demand rendered Markdown and preserve raw reviewer output in `review-agent-results.jsonl`.
 
 ## Risk-Lane Review Swarm Profile
 
@@ -93,7 +93,7 @@ The main thread owns aggregation:
 
 Use git and prior records to avoid repeating stale work:
 
-1. Find the previous reviewed SHA from `cc-review-ledger.jsonl` or `cc-review-report.md`.
+1. Find the previous reviewed SHA from `review-ledger.jsonl`, falling back to legacy `cc-review-ledger.jsonl` or `cc-review-report.md`.
 2. Compare `git diff <previous-sha>...HEAD` when possible.
 3. If no previous SHA exists, compare against the base branch or reviewed artifact timestamps.
 4. Re-review changed nodes and dependent nodes.

package/.claude/skills/cc-review/scripts/collect-review-context.sh

@@ -15,10 +15,12 @@ if [[ -z "$change_dir" ]]; then
 fi
 
 review_dir="$change_dir/review"
-ledger="$review_dir/cc-review-ledger.jsonl"
+ledger="$review_dir/review-ledger.jsonl"
+legacy_ledger="$review_dir/cc-review-ledger.jsonl"
 report="$review_dir/cc-review-report.md"
 plan="$review_dir/cc-review-plan.md"
-findings="$review_dir/cc-review-findings.json"
+findings="$review_dir/review-findings.json"
+legacy_findings="$review_dir/cc-review-findings.json"
 
 head_sha="$(git rev-parse HEAD)"
 base_sha=""
@@ -27,9 +29,14 @@ if git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
 fi
 
 reviewed_sha=""
-if [[ -f "$ledger" ]]; then
+ledger_for_read="$ledger"
+if [[ ! -f "$ledger_for_read" && -f "$legacy_ledger" ]]; then
+  ledger_for_read="$legacy_ledger"
+fi
+
+if [[ -f "$ledger_for_read" ]]; then
   reviewed_sha="$(
-    sed -n 's/.*"headSha"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ledger" |
+    sed -n 's/.*"headSha"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ledger_for_read" |
       tail -n 1
   )"
 fi
@@ -57,7 +64,7 @@ echo "diff_base=${diff_base:-unknown}"
 
 echo
 echo "PRIOR_REVIEW_FILES"
-for file in "$plan" "$report" "$ledger" "$findings"; do
+for file in "$ledger" "$findings" "$plan" "$report" "$legacy_ledger" "$legacy_findings"; do
   if [[ -f "$file" ]]; then
     printf 'present %s\n' "$file"
   else
@@ -73,8 +80,8 @@ else
   git diff --name-status HEAD
 fi
 
-if [[ -f "$ledger" ]]; then
+if [[ -f "$ledger_for_read" ]]; then
   echo
   echo "RECENT_LEDGER"
-  tail -n 20 "$ledger"
+  tail -n 20 "$ledger_for_read"
 fi

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

@@ -1,5 +1,11 @@
 # Roadmap Skill Changelog
 
+## v5.3.0 - 2026-05-11
+
+- add the Roadmap Funnel Protocol with fixed F0-F9 rounds for direction mode, demand reality, status quo, specific human/sponsor, wedge/lake boundary, observation signal, future fit, premise challenge, alternatives, and route approval
+- persist the funnel transcript in `devflow/roadmap.json` and render it into `devflow/ROADMAP.md` so route decisions survive beyond chat
+- upgrade backlog handoff fields so ready RM items carry source funnel rounds, frozen decisions, do-not-re-decide constraints, and remaining blocking questions for downstream `cc-plan`
+
 ## v5.2.0 - 2026-05-09
 
 - add project-direction routing and brand-neutral founder guardrails

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

@@ -20,6 +20,8 @@
 8. 先判断 planning posture 和 evidence maturity，再决定追问哪些问题；不要用同一套问题硬套 idea、已有用户、付费客户、infra 和 recovery 场景。
 9. developer-facing / operator-facing 路线必须写清 target user、time to first value、magic moment 和 adoption bottleneck。
 10. 先对齐 `devflow/specs/`、roadmap/backlog 和历史 design decision，再命名 stage、capability、RM 和 backlog；术语或决策冲突必须成为显式路线风险。
+11. Roadmap Funnel Protocol 必须固定推进：方向、真实需求、现状、具体人、wedge/lake、观察信号、future fit、premise challenge、alternatives、route approval。
+12. 每轮要么由证据回答，要么问用户一个 `D<N>` 决策题，要么写明 skipped reason；不能让关键轮次停在聊天记忆里。
 
 ## Local Kit
 
@@ -48,6 +50,31 @@
 
 先把这些材料压成 `Context Snapshot`，再追问用户。
 
+## Roadmap Funnel Protocol
+
+固定轮次：
+
+1. `F0 Direction Mode`
+2. `F1 Demand / Operator Reality`
+3. `F2 Status Quo`
+4. `F3 Specific Human / Sponsor`
+5. `F4 Narrowest Wedge / Lake Boundary`
+6. `F5 Observation / Feedback Signal`
+7. `F6 Future Fit`
+8. `F7 Premise Challenge`
+9. `F8 Alternatives`
+10. `F9 Route Approval`
+
+执行规则：
+
+1. 一次只推进一轮；需要用户时只问一个 `D<N> - <decision title>`。
+2. 每个问题必须有推荐答案、证据来源、选项影响和 STOP。
+3. 用户回答后先更新 `roadmapFunnel.rounds[]`，再继续下一轮。
+4. 用户要求跳过时，最多再问 2 个最关键剩余问题，然后必须仍然跑 `F7` 和 `F8`。
+5. `F7` 把隐含前提写成可同意 / 反对的句子；反对时回到受影响轮次重算。
+6. `F8` 至少给最小路径和理想架构路径；非平凡项目给第三条 lateral / decomposition 路径。
+7. `F9` 才能冻结 route、stage、ready RM 和 `cc-plan` handoff。
+
 ## Force Reality First
 
 至少逼清这 5 件事：
@@ -119,10 +146,12 @@
 `devflow/roadmap.json`
 - single editable roadmap state
 - output policy, meta, context, evidence, route, stages, items, handoff, and architecture
+- `context.roadmapFunnel.rounds[]` stores every fixed round, answer source, evidence, skipped reason, and decision impact
 - flat `architecture.nodes` / `architecture.edges` used to generate Mermaid
 
 `devflow/ROADMAP.md`
 - version / skill version / context snapshot / evidence ledger
+- Roadmap Funnel Transcript with F0-F9 answers and skipped reasons
 - 1-3 个阶段
 - 独立子系统拆分判断
 - 每阶段目标
@@ -139,6 +168,7 @@
 - deprecated compatibility projection; edit `devflow/roadmap.json` instead
 - 只保留会真的进入下一轮 `cc-plan` 的事项
 - 每项注明来源阶段、优先级、证据、`Depends On`、`Parallel With`、当前未知点、下一决策、是否 ready
+- ready 项必须带 `Source funnel rounds`、`Frozen decisions`、`Do not re-decide` 和 `Remaining blocking question`
 - developer-facing / operator-facing 条目要带 target user、time to first value、magic moment 和 adoption bottleneck，方便 `cc-plan` 继续做 DX 设计
 - `Backlog Meta`、`Queue`、`Dependency Handoff`、`Ready For Req-Plan`、`Parked` 由 `devflow/roadmap.json` 回渲染，避免 roadmap truth 和 backlog handoff 分叉
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-roadmap
-version: 5.2.0
+version: 5.3.0
 description: "Use when defining, resetting, or narrowing project direction, stage order, or backlog priority before a concrete requirement enters the PDCA loop."
 triggers:
   - "帮我定路线图"
@@ -42,6 +42,7 @@ entry_gate:
   - "If the ask contains multiple independent subsystems, decompose them into stages and RM candidates before refining any implementation detail."
   - "Do not decompose implementation tasks while the roadmap is still being decided."
   - "Apply the AI Leverage Route Lens before route approval: name the reachable user/operator, current workaround, human-vs-agent effort, complete-lake boundary, ocean boundary, first success signal, and kill signal."
+  - "Run the Roadmap Funnel Protocol as fixed one-question rounds; every round must either be answered from repo evidence, asked to the user, or explicitly skipped with reason."
   - "If AI makes a complete same-blast-radius route cheap and verifiable, prefer boil-lake over a timid MVP slice."
   - "If the route cannot name a real user/operator and current workaround, mark it as needs-evidence instead of producing implementation-ready RM handoff."
 exit_criteria:
@@ -50,6 +51,7 @@ exit_criteria:
   - "The roadmap shows an explicit RM dependency graph so serial blockers and parallel-ready work are obvious."
   - "The user-approved recommendation is explicit and grounded in current evidence."
   - "Each Stage 1 or ready-for-cc-plan item records an AI Leverage Route Lens verdict: boil-lake, sharp-wedge, needs-evidence, or pivot."
+  - "The Roadmap Funnel Transcript is persisted in `devflow/roadmap.json`, rendered into `devflow/ROADMAP.md`, and each ready RM carries the source funnel rounds, frozen decisions, and remaining blocking question."
 reroutes:
   - when: "The user is already discussing one concrete requirement, bug, or execution task."
     target: "cc-plan"
@@ -240,6 +242,39 @@ Verdict 只允许四种：
 5. 每条路线都要用一个具体 scenario 压测：谁在什么约束下，今天如何绕路，Stage 1 完成后哪一步不再发生。
 6. 硬决策才沉淀：只有 hard to reverse、surprising without context、real trade-off 三者同时成立，才进入 capability spec delta、roadmap decision note 或本次 design decision log。
 
+## Roadmap Funnel Protocol
+
+路线图必须像 office-hours 一样固定推进多轮，但输出必须是 source-neutral 的 `cc-roadmap` 产物，不暴露外部来源。
+
+每轮只允许处理一个 route-changing unknown。能从仓库证据回答就写 `answered-by-evidence`；不能回答才问用户；用户催促跳过时最多保留 2 个最关键问题，然后进入 premise challenge 和 alternatives。每个问题都必须给推荐答案、证据、反对时会改变的路线，并在回答后更新 `Roadmap Funnel Transcript`。
+
+固定轮次：
+
+1. `F0 Direction Mode`：确认项目目标模式，说明为什么不是其它模式。
+2. `F1 Demand / Operator Reality`：确认真实用户或操作者，以及他们今天是否真的痛。
+3. `F2 Status Quo`：确认现状 workaround、成本、失败方式；没有 workaround 默认 `needs-evidence`。
+4. `F3 Specific Human / Sponsor`：把类别词压成可命名角色、具体约束、职业/组织后果。
+5. `F4 Narrowest Wedge / Lake Boundary`：比较最窄 wedge、完整 same-blast-radius lake、ocean boundary。
+6. `F5 Observation / Feedback Signal`：确认看过真实使用、失败日志、运营证据或可复现实验；没有观察就写 Stage 1 observation task。
+7. `F6 Future Fit`：确认 6-12 个月后为什么更需要这条路，而不是只靠今天的热词。
+8. `F7 Premise Challenge`：把本轮隐含前提写成 2-4 条，逐条确认或修正。
+9. `F8 Alternatives`：至少给 2 条路线，非平凡项目给 3 条；必须包含最小路径与理想架构路径。
+10. `F9 Route Approval`：冻结推荐路线、拒绝路线、第一成功信号、kill signal、下一批 ready RM。
+
+STOP 规则：
+
+- 每次需要用户判断时只问一个 `D<N> - <decision title>`。
+- 选项只用 `A` / `B` / `C`，推荐项必须标 `(recommended)`。
+- 问完必须停止等待，不能同一轮继续生成最终 roadmap。
+- 用户回答后，先更新 transcript，再决定是否进入下一轮。
+
+产物规则：
+
+- `devflow/roadmap.json.context.roadmapFunnel.rounds[]` 记录每轮 `id`、`question`、`answerSource`、`answer`、`evidence`、`decisionImpact`、`status`。
+- `devflow/ROADMAP.md` 必须渲染 `## Roadmap Funnel Transcript`，让后续读者知道路线不是拍脑袋。
+- `devflow/BACKLOG.md` 的 ready RM 必须记录 `Source funnel rounds`、`Frozen decisions`、`Do not re-decide`、`Remaining blocking question`。
+- 没有闭合 `F7` 和 `F8` 时，不允许把任何 RM 标成 ready for `cc-plan`，除非用户给出已成形且有证据的计划；即便如此也要把跳过理由写入 transcript。
+
 ## Founder Advice Guardrail
 
 创业建议只能服务于 roadmap 质量，不是推广内容。遇到 `founder-business` 或 `internal-company`：
@@ -319,13 +354,15 @@ Verdict 只允许四种：
 1. 没有 `Context Snapshot`，不准给路线推荐。
 2. 没有 project direction mode、planning posture、evidence maturity 和 framing check，不准给路线推荐。
 3. 没有 native language / durable decision scan，不准给路线推荐；如果缺少 `devflow/specs/` 或历史决策材料，写成 `not present`，不要假装已对齐。
-4. 没有 2-3 条路线对比，不准直接拍脑袋定主线。
-5. 没有 exit signal / kill signal / non-goals，不算阶段冻结。
-6. 没有明确成功信号和下一决策，不准把事项放进 `Ready For Req-Plan`。
-7. developer-facing / operator-facing item 没有 target user、time to first value 或 adoption bottleneck，不准标成 ready。
-8. 没有 `RM dependency graph` 或 parallel-ready wave，不准宣称事项可以并发推进。
-9. 没有独立子系统拆分判断，不准把大而混杂的方向伪装成单一主线。
-10. 没有用户批准，不准把 roadmap item 下放到 `cc-plan`。
+4. 没有 `Roadmap Funnel Transcript`，不准给路线推荐。
+5. 没有 `F7 Premise Challenge` 和 `F8 Alternatives`，不准把事项标成 ready。
+6. 没有 2-3 条路线对比，不准直接拍脑袋定主线。
+7. 没有 exit signal / kill signal / non-goals，不算阶段冻结。
+8. 没有明确成功信号和下一决策，不准把事项放进 `Ready For Req-Plan`。
+9. developer-facing / operator-facing item 没有 target user、time to first value 或 adoption bottleneck，不准标成 ready。
+10. 没有 `RM dependency graph` 或 parallel-ready wave，不准宣称事项可以并发推进。
+11. 没有独立子系统拆分判断，不准把大而混杂的方向伪装成单一主线。
+12. 没有用户批准，不准把 roadmap item 下放到 `cc-plan`。
 
 ## Review Loop
 

package/.claude/skills/cc-roadmap/assets/BACKLOG_TEMPLATE.md

@@ -27,6 +27,10 @@
 ## Adoption Handoff
 
 - Project direction mode:
+- Source funnel rounds:
+- Frozen decisions:
+- Do not re-decide:
+- Remaining blocking question:
 - Direction-specific first question:
 - Founder / builder / infra guardrail:
 - Planning posture:
@@ -56,6 +60,10 @@
   - Expected spec delta:
   - Open risks:
   - First planning question:
+  - Source funnel rounds:
+  - Frozen decisions:
+  - Do not re-decide:
+  - Remaining blocking question:
   - Evidence maturity:
   - Target developer / operator:
   - Time to first value:

package/.claude/skills/cc-roadmap/assets/ROADMAP_TEMPLATE.md

@@ -53,6 +53,28 @@
 | Feasibility |  | High / Med / Low |  |  |
 | Distribution |  | High / Med / Low |  |  |
 
+## Roadmap Funnel Transcript
+
+| Round | Question | Answer source | Answer / decision | Evidence | Decision impact | Status |
+|-------|----------|---------------|-------------------|----------|-----------------|--------|
+| F0 Direction Mode |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F1 Demand / Operator Reality |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F2 Status Quo |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F3 Specific Human / Sponsor |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F4 Narrowest Wedge / Lake Boundary |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F5 Observation / Feedback Signal |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F6 Future Fit |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F7 Premise Challenge |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F8 Alternatives |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+| F9 Route Approval |  | repo-evidence / user-answer / skipped |  |  |  | pending |
+
+- Premises confirmed:
+- Premises rejected / revised:
+- Alternatives reviewed:
+- Approved route:
+- Open concerns:
+- Skipped rounds and reasons:
+
 ## AI Leverage Route Lens
 
 - Real user / operator:

package/.claude/skills/cc-roadmap/assets/TRACKING_TEMPLATE.json

@@ -5,7 +5,7 @@
   },
   "meta": {
     "roadmapVersion": "roadmap.v1",
-    "skillVersion": "5.2.0",
+    "skillVersion": "5.3.0",
     "status": "active",
     "lastUpdated": "2026-05-01",
     "currentFocusStage": "Stage 1"
@@ -32,6 +32,33 @@
       "verdict": "needs-evidence",
       "missingEvidence": []
     },
+    "roadmapFunnel": {
+      "status": "in-progress",
+      "currentRound": "F0",
+      "approvedRouteRound": "",
+      "rounds": [
+        {
+          "id": "F0",
+          "title": "Direction Mode",
+          "question": "What project-direction mode are we in, and why not the other modes?",
+          "answerSource": "repo-evidence | user-answer | skipped",
+          "answer": "",
+          "evidence": [],
+          "decisionImpact": "Selects the question set and default route shape",
+          "status": "pending",
+          "skippedReason": ""
+        }
+      ],
+      "premiseChallenge": [],
+      "alternativesReviewed": [],
+      "routeApproval": {
+        "approved": false,
+        "approvedRoute": "",
+        "approvedBy": "",
+        "approvedAt": "",
+        "openConcerns": []
+      }
+    },
     "canonicalTerms": [],
     "durableDecisionSources": []
   },
@@ -69,6 +96,10 @@
         "entryConstraints": "",
         "openRisks": "",
         "firstPlanningQuestion": "",
+        "sourceFunnelRounds": [],
+        "frozenDecisions": [],
+        "doNotRedecide": [],
+        "remainingBlockingQuestion": "",
         "requiredContextToLoad": "",
         "whyReadyNow": "",
         "parked": false,

package/.claude/skills/cc-roadmap/references/roadmap-dialogue.md

@@ -3,28 +3,27 @@
 ## Order
 
 0. 先做 `Context Snapshot`：现有 roadmap / backlog、capability specs、历史 design/analysis、最近提交、forcing functions、项目语言 / durable decisions
-1. 先判断 project direction mode：founder-business / internal-company / hackathon-demo / open-source-research / learning / side-project / infrastructure / recovery
-2. 用户是谁
-3. 今天靠什么笨办法活着
-4. 最强需求证据是什么
-5. 为什么现在必须解决
-6. deadline / capacity / dependency / distribution 约束是什么
-7. 当前最大的 adoption / trust / delivery 卡点是什么
-8. 核心术语是否已有 canonical definition，是否和现有 capability spec / roadmap decision 冲突
-9. 最窄突破口是什么
-10. 6-12 个月后会长成什么
-11. 给出 2-3 条路线图形状并明确推荐
-12. 冻结 1-3 个阶段，写 exit signal / kill signal / non-goals
-13. 画出 `RM dependency graph`，标出串行主链和 parallel-ready wave
-14. 标出哪些事项真的 ready for `cc-plan`
+1. `F0 Direction Mode`：project direction mode，为什么不是其它模式
+2. `F1 Demand / Operator Reality`：用户是谁，最强需求或运营证据是什么
+3. `F2 Status Quo`：今天靠什么笨办法活着，成本和失败方式是什么
+4. `F3 Specific Human / Sponsor`：具体人、具体角色、具体组织后果
+5. `F4 Narrowest Wedge / Lake Boundary`：最窄突破口、完整 lake、ocean boundary
+6. `F5 Observation / Feedback Signal`：真实观察、运行证据、demo 使用或待补证据任务
+7. `F6 Future Fit`：6-12 个月后为什么更需要它
+8. `F7 Premise Challenge`：核心前提、canonical language、capability/spec 冲突
+9. `F8 Alternatives`：给出 2-3 条路线图形状并明确推荐
+10. `F9 Route Approval`：冻结 1-3 个阶段、dependency graph、parallel wave、ready RM
 
 ## Question Rules
 
 - 一次只推进一个关键未知点
 - 每个问题附带推荐答案、证据来源，以及用户反对时会改变哪条路线
+- 问题编号使用 `D<N> - <decision title>`；选项只用 `A` / `B` / `C`，推荐项标 `(recommended)`
+- 每轮回答必须落入 `Roadmap Funnel Transcript`
 - 能从 repo / capability spec / roadmap / design / git history 得到答案时先查证，不问用户
 - 没证据时明确写 assumption
 - 用户没批准前，不把事项偷下放成 requirement
+- 用户催促跳过时，最多补问 2 个关键问题，但不能跳过 `F7 Premise Challenge` 和 `F8 Alternatives`
 
 ## Project Direction Modes
 
@@ -54,3 +53,4 @@
 - backlog 只收下一轮真会进入 `cc-plan` 的事项
 - ready 项必须带成功信号、下一决策、`Depends On`、`Parallel With`
 - ready 项必须带 canonical terms、capability spec context 或明确的 language / decision conflict
+- ready 项必须带 Source funnel rounds、Frozen decisions、Do not re-decide、Remaining blocking question

package/CHANGELOG.md

@@ -9,6 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.10] - 2026-05-13
+
+### Added
+
+- Added the `workflow-context` typed runtime query as a context index that reports the next PDCA/IDCA skill, current task, source hashes, `mustNotForget` guardrails, default section/JSON refs, trusted commands, fail-closed rules, and machine-readable deep-open triggers.
+- Added `cc-devflow query --data-only --no-trace --compact` output controls and `npm run benchmark:workflow-context` for checked-in token estimates plus synthetic routing-correctness cases.
+- Added the minimized workflow artifact contract guide, `cc-devflow task-contract validate`, `npm run verify:artifacts`, and `npm run benchmark:artifacts` so change artifacts stay small and measurable.
+
+### Changed
+
+- Updated `cc-plan`, `cc-investigate`, `cc-do`, `cc-check`, `cc-act`, and `cc-dev` so stage transitions start from `cc-devflow query workflow-context --data-only --no-trace --compact` instead of reloading the full loop history by default.
+- Updated `cc-plan` and `cc-investigate` so new changes default to `planning/tasks.md` as the only human-authored Markdown handoff: feature plans use `## Contract Summary`, bug investigations use `## Root Cause Contract`, and legacy `planning/design.md` / `planning/analysis.md` remain fallback inputs only.
+- Updated `cc-review` so `review/review-ledger.jsonl` is the default durable review record, with `review-findings.json` and rendered Markdown reports created only when needed.
+- Updated `cc-check` review truth loading to prefer structured findings and review ledger records before legacy `cc-review-*.md` reports.
+- Updated `npm run verify` to include `verify:artifacts` after tests and example binding checks.
+
+## [4.5.9] - 2026-05-11
+
+### Added
+
+- Added project-level AI postmortem contracts under `devflow/postmortems/`, with `cc-act` writing progressive incident, index, and principle records that include Git evidence and verification facts.
+
+### Changed
+
+- Updated `cc-plan`, `cc-investigate`, and `cc-do` to search project postmortems before freezing plans, finalizing root-cause hypotheses, or executing individual tasks.
+- Updated `cc-act` so `post-merge-closeout` must run `cc-devflow archive-change <change-key>` and prove the archive path, instead of leaving archive as an optional next action.
+- Updated `cc-next` so unarchived `devflow/changes/<REQ|FIX>-*` directories are next-work candidates, including done-but-unarchived closeout work.
+
 ## [4.5.8] - 2026-05-11
 
 ### Changed

package/CONTRIBUTING.md

@@ -13,17 +13,25 @@ cc-devflow is now a skills-first repository with a restored distributable CLI.
 Public surface:
 
 - `cc-roadmap`
+- `cc-next`
+- `cc-dev`
 - `cc-plan`
 - `cc-investigate`
 - `cc-do`
+- `cc-review`
+- `cc-pr-review`
+- `cc-pr-land`
 - `cc-check`
 - `cc-act`
 - `cc-devflow init`
 - `cc-devflow adapt`
+- `cc-devflow query`
+- `cc-devflow task-contract`
+- `cc-devflow review`
 
 Shared runtime helpers may still live under `lib/skill-runtime/`, but they are not the user-facing workflow anymore.
 
-Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`, but they do not change the public `cc-roadmap + PDCA/IDCA` workflow story.
+Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`. `cc-spec-init` and `cc-simplify` ship with the pack as maintenance skills; `docs-sync` stays internal.
 
 ---
 
@@ -125,7 +133,34 @@ If you touch a shipped skill, treat these files as one contract:
 
 Do not change one part of the contract and leave the others stale.
 
-### 3. Keep Distribution Clean
+Codex output under `.codex/skills/` is generated by `cc-devflow adapt`. Do not hand-edit it. Change `.claude/skills/<skill>/` first, then regenerate the mirror with:
+
+```bash
+npm run adapt
+npm run adapt -- --check
+```
+
+### 3. Keep Skill Contract Changes Complete
+
+When a shipped skill contract changes, update the source and public surfaces in one pass:
+
+- `.claude/skills/<skill>/SKILL.md`
+- `.claude/skills/<skill>/CHANGELOG.md`
+- affected `PLAYBOOK.md`, `assets/`, `references/`, and `scripts/`
+- root `README.md` / `README.zh-CN.md`
+- affected docs under `docs/`
+- `docs/examples/example-bindings.json` and example metadata
+
+Then run the relevant gates:
+
+```bash
+npm run verify:examples
+npm run verify:publish
+npm run verify:artifacts
+npm run verify
+```
+
+### 4. Keep Distribution Clean
 
 Do not ship transient files in templates or tarballs.
 
@@ -135,7 +170,7 @@ Examples of junk we should exclude:
 - `.DS_Store`
 - local editor or OS artifacts
 
-### 4. Keep Runtime Helpers Secondary
+### 5. Keep Runtime Helpers Secondary
 
 If you touch `lib/skill-runtime/`, keep the behavior testable, but do not document it as the primary user entry. The public workflow still belongs to the shipped skills.
 
@@ -178,7 +213,8 @@ This should confirm:
 - do not describe `.claude/commands/` as required structure
 - do not describe internal runtime helpers as the supported public workflow
 - if a shipped skill changes, update that skill's `version`, local `CHANGELOG.md`, and affected public docs in the same PR
-- keep the workflow story as `cc-roadmap + PDCA/IDCA` visible skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+- keep the workflow story as `cc-roadmap`, `cc-next`, `cc-dev`, manual PDCA/IDCA skills, optional `cc-review`, and PR review/landing skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+- do not hand-edit `.codex/skills`; regenerate it from `.claude/skills` with `npm run adapt`
 
 ---
 

package/CONTRIBUTING.zh-CN.md

@@ -13,17 +13,25 @@ cc-devflow 现在是一个 skills-first 仓库，并且重新带回了可分发
 对外可见面只有这些：
 
 - `cc-roadmap`
+- `cc-next`
+- `cc-dev`
 - `cc-plan`
 - `cc-investigate`
 - `cc-do`
+- `cc-review`
+- `cc-pr-review`
+- `cc-pr-land`
 - `cc-check`
 - `cc-act`
 - `cc-devflow init`
 - `cc-devflow adapt`
+- `cc-devflow query`
+- `cc-devflow task-contract`
+- `cc-devflow review`
 
 `lib/skill-runtime/` 可以保留共享运行时支撑，但它已经不是用户要直接理解或运行的工作流入口。
 
-仓库里也可以存在维护类 Skill，例如 `cc-spec-init`、`cc-simplify`、`docs-sync`，但它们不改变公开的 `cc-roadmap + PDCA/IDCA` 叙事。
+仓库里也可以存在维护类 Skill，例如 `cc-spec-init`、`cc-simplify`、`docs-sync`。其中 `cc-spec-init` 和 `cc-simplify` 随整包分发为维护类 Skill；`docs-sync` 仍是内部维护 Skill。
 
 ---
 
@@ -125,7 +133,34 @@ cc-devflow/
 
 不要只改其中一部分，让其余说明继续过期。
 
-### 3. 保持分发包干净
+Codex 输出目录 `.codex/skills/` 由 `cc-devflow adapt` 生成。不要手改它。先改 `.claude/skills/<skill>/`，再重新生成镜像：
+
+```bash
+npm run adapt
+npm run adapt -- --check
+```
+
+### 3. 保持 Skill 契约变更完整
+
+如果一个已发布 Skill 的契约变化，请一次性同步这些面：
+
+- `.claude/skills/<skill>/SKILL.md`
+- `.claude/skills/<skill>/CHANGELOG.md`
+- 受影响的 `PLAYBOOK.md`、`assets/`、`references/` 和 `scripts/`
+- 根 `README.md` / `README.zh-CN.md`
+- `docs/` 下受影响的公开文档
+- `docs/examples/example-bindings.json` 和样例 metadata
+
+然后运行相关门禁：
+
+```bash
+npm run verify:examples
+npm run verify:publish
+npm run verify:artifacts
+npm run verify
+```
+
+### 4. 保持分发包干净
 
 不要把瞬态文件放进模板或 tarball。
 
@@ -135,7 +170,7 @@ cc-devflow/
 - `.DS_Store`
 - 本地编辑器和操作系统产生的垃圾文件
 
-### 4. 让运行时辅助层保持次要
+### 5. 让运行时辅助层保持次要
 
 如果你改了 `lib/skill-runtime/`，请保持可测试，但不要再把它写成用户主入口。真正的公开 workflow 仍然属于已发布 Skill。
 
@@ -178,7 +213,8 @@ node scripts/validate-publish.js
 - 不要把 `.claude/commands/` 写成必需结构
 - 不要把内部运行时辅助层写成受支持的公开工作流
 - 如果改了已发布 Skill，在同一个 PR 里同步该 Skill 的 `version`、本地 `CHANGELOG.md` 和受影响的公开文档
-- 主 workflow 仍然只讲 `cc-roadmap + PDCA/IDCA`；`cc-spec-init` / `cc-simplify` 等维护类 Skill 单独说明
+- 主 workflow 仍然围绕 `cc-roadmap`、`cc-next`、`cc-dev`、手动 PDCA/IDCA Skill、可选 `cc-review` 和 PR review/landing Skill；`cc-spec-init` / `cc-simplify` 等维护类 Skill 单独说明
+- 不要手改 `.codex/skills`；从 `.claude/skills` 通过 `npm run adapt` 重新生成
 
 ---