cc-devflow 4.5.8 → 4.5.10

package/.claude/skills/cc-do/scripts/record-review-decision.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 # ------------------------------------------------------------
-# 记录 spec / code review 结论，并同步 runtime / manifest
+# 记录 spec / code review 结论，并同步 manifest；失败时保留 CLI 事件
 # ------------------------------------------------------------
 
 usage() {
@@ -46,12 +46,9 @@ fi
 CHANGE_DIR="$(req_do_resolve_change_dir "$REQ_DIR")"
 manifest="$(req_do_manifest_path "$CHANGE_DIR")"
 change_id="$(jq -r '.changeId // .requirementId // "REQ-UNKNOWN"' "$manifest" 2>/dev/null || basename "$CHANGE_DIR")"
-runtime_task_dir="$(req_do_task_runtime_dir "$CHANGE_DIR" "$TASK_ID")"
 timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 event_name="${GATE}_review_${VERDICT}"
 
-mkdir -p "$runtime_task_dir"
-
 if [[ -f "$manifest" ]]; then
   tmp_manifest="$(mktemp)"
   jq --arg task "$TASK_ID" --arg gate "$GATE" --arg verdict "$VERDICT" '
@@ -66,7 +63,9 @@ if [[ -f "$manifest" ]]; then
   mv "$tmp_manifest" "$manifest"
 fi
 
-if [[ -f "$runtime_task_dir/events.jsonl" || "$VERDICT" != "pass" ]]; then
+if [[ "$VERDICT" != "pass" ]]; then
+  runtime_task_dir="$(req_do_task_runtime_dir "$CHANGE_DIR" "$TASK_ID")"
+  mkdir -p "$runtime_task_dir"
   jq -nc \
     --arg type "$event_name" \
     --arg changeId "$change_id" \

package/.claude/skills/cc-do/scripts/recover-workflow.sh

@@ -68,17 +68,15 @@ if [[ -f "$report" ]]; then
   echo "- Latest check verdict: $verdict"
 fi
 
-if [[ -n "$change_id" ]]; then
-  runtime_dir="$(req_do_execution_dir "$CHANGE_DIR")/tasks"
+if [[ -f "$manifest" ]]; then
+  echo
+  echo "## Task Status"
+  jq -r '.tasks[]? | "- " + .id + ": " + (.status // "pending") + (if .lastError then " - " + .lastError else "" end)' "$manifest" 2>/dev/null || true
 fi
 
-if [[ -n "${runtime_dir:-}" && -d "$runtime_dir" ]]; then
-  echo "- Runtime dir: $runtime_dir"
-
-  while IFS= read -r checkpoint_path; do
-    task_id="$(jq -r '.taskId // "unknown"' "$checkpoint_path" 2>/dev/null || echo unknown)"
-    checkpoint_status="$(jq -r '.status // "unknown"' "$checkpoint_path" 2>/dev/null || echo unknown)"
-    checkpoint_summary="$(jq -r '.summary // ""' "$checkpoint_path" 2>/dev/null || echo "")"
-    echo "- Checkpoint $task_id: $checkpoint_status ${checkpoint_summary:+- $checkpoint_summary}"
-  done < <(find "$runtime_dir" -name checkpoint.json | sort)
+if git -C "$CHANGE_DIR" rev-parse --show-toplevel >/dev/null 2>&1; then
+  repo_root="$(git -C "$CHANGE_DIR" rev-parse --show-toplevel)"
+  echo
+  echo "## Git State"
+  git -C "$repo_root" status --short
 fi

package/.claude/skills/cc-do/scripts/verify-task-gates.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 # ------------------------------------------------------------
-# 校验任务是否完成 Red / Green / Refactor / Review 闭环
+# 校验任务状态、依赖和可选 CLI 事件顺序
 # ------------------------------------------------------------
 
 usage() {
@@ -36,19 +36,21 @@ CHANGE_DIR="$(req_do_resolve_change_dir "$REQ_DIR")"
 manifest="$(req_do_manifest_path "$CHANGE_DIR")"
 runtime_task_dir="$(req_do_task_runtime_dir "$CHANGE_DIR" "$TASK_ID")"
 events_file="$runtime_task_dir/events.jsonl"
-checkpoint_file="$runtime_task_dir/checkpoint.json"
 
-if [[ ! -f "$checkpoint_file" ]]; then
-  echo "Missing $checkpoint_file" >&2
-  exit 1
-fi
-
-checkpoint_status="$(jq -r '.status // "unknown"' "$checkpoint_file" 2>/dev/null || echo unknown)"
-[[ "$checkpoint_status" == "passed" ]] || {
-  echo "Task $TASK_ID checkpoint status is not passed" >&2
+task_json="$(jq -c --arg task "$TASK_ID" '.tasks[] | select(.id == $task)' "$manifest" 2>/dev/null || true)"
+[[ -n "$task_json" ]] || {
+  echo "Task $TASK_ID not found in manifest" >&2
   exit 1
 }
 
+while IFS= read -r dependency; do
+  dep_status="$(jq -r --arg dep "$dependency" '.tasks[] | select(.id == $dep) | .status // "pending"' "$manifest" 2>/dev/null || echo pending)"
+  [[ "$dep_status" == "passed" || "$dep_status" == "completed" || "$dep_status" == "done" || "$dep_status" == "verified" ]] || {
+    echo "Task $TASK_ID dependency $dependency is not complete" >&2
+    exit 1
+  }
+done < <(jq -r '(.dependsOn // [])[]?' <<<"$task_json")
+
 spec_verdict="$(jq -r --arg task "$TASK_ID" '.tasks[] | select(.id == $task) | .reviews.spec // "pending"' "$manifest" 2>/dev/null || echo pending)"
 code_verdict="$(jq -r --arg task "$TASK_ID" '.tasks[] | select(.id == $task) | .reviews.code // "pending"' "$manifest" 2>/dev/null || echo pending)"
 

package/.claude/skills/cc-do/scripts/write-task-checkpoint.sh

@@ -3,13 +3,13 @@
 set -euo pipefail
 
 # ------------------------------------------------------------
-# 写入 task checkpoint.json / events.jsonl
+# 兼容旧入口：只写必要的 CLI 事件，不再生成 checkpoint.json
 # ------------------------------------------------------------
 
 usage() {
   cat <<'EOF'
 Usage:
-  write-task-checkpoint.sh --dir path/to/change --task T001 --status pending|running|passed|failed|skipped --summary "..." [--event context_ready] [--attempt 0] [--session session-id] [--next-action "..."] [--tdd-json '{"red":...}']
+  write-task-checkpoint.sh --dir path/to/change --task T001 --status pending|running|passed|failed|skipped [--summary "..."] [--event context_ready] [--attempt 0] [--session session-id] [--next-action "..."] [--tdd-json '{"red":...}']
 EOF
 }
 
@@ -41,7 +41,7 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-if [[ -z "$REQ_DIR" || -z "$TASK_ID" || -z "$STATUS" || -z "$SUMMARY" ]]; then
+if [[ -z "$REQ_DIR" || -z "$TASK_ID" || -z "$STATUS" ]]; then
   usage
   exit 1
 fi
@@ -49,12 +49,9 @@ fi
 CHANGE_DIR="$(req_do_resolve_change_dir "$REQ_DIR")"
 manifest="$(req_do_manifest_path "$CHANGE_DIR")"
 change_id="$(jq -r '.changeId // .requirementId // "REQ-UNKNOWN"' "$manifest" 2>/dev/null || basename "$REQ_DIR")"
-plan_version="$(jq -r '.metadata.planVersion // 1' "$manifest" 2>/dev/null || echo 1)"
 timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 runtime_task_dir="$(req_do_task_runtime_dir "$CHANGE_DIR" "$TASK_ID")"
 
-mkdir -p "$runtime_task_dir"
-
 if [[ -z "$SESSION_ID" ]]; then
   SESSION_ID="${TASK_ID}-$(date -u +%s)"
 fi
@@ -68,28 +65,8 @@ if [[ -n "$TDD_JSON" ]]; then
   fi
 fi
 
-jq -nc \
-  --arg changeId "$change_id" \
-  --arg taskId "$TASK_ID" \
-  --arg sessionId "$SESSION_ID" \
-  --arg planVersion "$plan_version" \
-  --arg status "$STATUS" \
-  --arg summary "$SUMMARY" \
-  --arg timestamp "$timestamp" \
-  --arg attempt "$ATTEMPT" \
-  --argjson tdd "$tdd_payload" \
-  '{
-    changeId: $changeId,
-    taskId: $taskId,
-    sessionId: $sessionId,
-    planVersion: ($planVersion | tonumber),
-    status: $status,
-    summary: $summary,
-    timestamp: $timestamp,
-    attempt: ($attempt | tonumber)
-  } + (if $tdd == null then {} else {tdd: $tdd} end)' > "$runtime_task_dir/checkpoint.json"
-
 if [[ -n "$EVENT_TYPE" || "$STATUS" == "failed" ]]; then
+  mkdir -p "$runtime_task_dir"
   jq -nc \
     --arg type "${EVENT_TYPE:-status_$STATUS}" \
     --arg changeId "$change_id" \
@@ -99,6 +76,7 @@ if [[ -n "$EVENT_TYPE" || "$STATUS" == "failed" ]]; then
     --arg summary "$SUMMARY" \
     --arg nextAction "$NEXT_ACTION" \
     --arg timestamp "$timestamp" \
+    --argjson tdd "$tdd_payload" \
     '{
       type: $type,
       changeId: $changeId,
@@ -108,7 +86,7 @@ if [[ -n "$EVENT_TYPE" || "$STATUS" == "failed" ]]; then
       summary: $summary,
       nextAction: $nextAction,
       timestamp: $timestamp
-    }' >> "$runtime_task_dir/events.jsonl"
+    } + (if $tdd == null then {} else {tdd: $tdd} end)' >> "$runtime_task_dir/events.jsonl"
 fi
 
-echo "Wrote $runtime_task_dir/checkpoint.json"
+echo "No checkpoint written; task truth lives in planning/tasks.md and planning/task-manifest.json"

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

@@ -1,5 +1,39 @@
 # CC-Investigate Skill Changelog
 
+## v1.5.0 - 2026-05-13
+
+- collapse default investigation output to `planning/tasks.md` plus CLI-generated `task-manifest.json` and `change-meta.json`
+- move root-cause truth into `planning/tasks.md#Root Cause Contract` so `planning/analysis.md` is legacy fallback only
+- archive the legacy analysis template under `assets/legacy/` and keep repair handoffs rooted in `assets/TASKS_TEMPLATE.md`
+
+## v1.4.3 - 2026-05-13
+
+- add the Worktree Branch Contract so new `FIX` investigations anchor detached worktrees to `FIX/<task>` before artifacts are written
+- treat investigations on `main` / the default branch as a setup blocker instead of allowing the main checkout to accumulate repair state
+- require analysis, tasks, and change metadata to record the canonical work branch for downstream `cc-do`
+
+## v1.4.2 - 2026-05-12
+
+- require IDCA repair handoffs to be consumable by `cc-devflow query workflow-context`
+- add the compact runtime reset to investigation task templates so `cc-do`, `cc-check`, and `cc-act` continue from the frozen root-cause packet instead of chat history
+
+## v1.4.1 - 2026-05-11
+
+- add the Project Postmortem Recall Gate so investigations search `devflow/postmortems` before final hypotheses are frozen
+- update analysis and repair-task templates to connect similar incidents, principles, Git evidence, and model-risk lessons to the current root-cause table
+- require recurring or same-root-cause findings to be classified explicitly instead of treated as novel bugs
+
+## v1.4.0 - 2026-05-11
+
+- add the Root Cause Proof Ladder so investigations must prove symptom site, first bad state, violated contract, original trigger, counterfactual proof, and escape reason before repair tasks are generated
+- upgrade `planning/analysis.md`, `planning/tasks.md`, and `task-manifest.json` templates so downstream `cc-do` inherits the root-cause proof instead of re-deciding from chat
+- require investigations that cannot prove first bad state, original trigger, or counterfactual proof to stop at evidence request or reroute instead of producing symptom patches
+
+## v1.3.1 - 2026-05-11
+
+- slim investigation task manifests so roadmap/spec status stays owned by `change-meta.json` and `devflow/roadmap.json`
+- remove duplicate design/review/status mirrors from the investigation manifest template while keeping root-cause evidence in `planning/analysis.md`
+
 ## v1.3.0 - 2026-05-09
 
 - FIX change key assignment now uses `cc-devflow next-change-key` instead of prose instructions

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

@@ -5,7 +5,7 @@
 `cc-investigate -> cc-do -> cc-check`
 
 - Enter from: a bug, regression, or broken requirement whose root cause is still unclear.
-- Stay in: `cc-investigate` until `planning/analysis.md` and the repair handoff are both frozen.
+- Stay in: `cc-investigate` until `planning/tasks.md#Root Cause Contract` and the repair handoff are both frozen.
 - Exit to: `cc-do` only after root cause, repair boundary, and source roadmap progress are explicit in canonical artifacts.
 - Reroute to: `cc-plan` for scope/design truth changes, or `roadmap` for project-level priority decisions.
 
@@ -16,13 +16,15 @@
 3. 先确认 loop 复现的是用户报告的同一个失败。
 4. 先看最近变化，再决定是不是 regression。
 5. 先证伪假设，再冻结根因。
-6. `planning/analysis.md` 和 `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
+6. `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
 7. 调查失败三次后先重建入口，不准继续乱补。
 8. 没有 frozen root-cause contract，不准进入 repair task。
 9. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
 10. diagnose-only 只能输出根因、owner、风险和 next action，不能把未修复状态标成完成。
 11. workflow forensics 先分类 artifact / git / state / tool / permission / process failure，再决定是否进入修复。
 12. 退出前必须跑 Roadmap Sync Gate：`implementation drift`、`missing spec truth`、`roadmap mismatch` 三种结论都要让 source RM 的状态和 next action 跟上。
+13. Root Cause Proof Ladder 必须证明 symptom site、first bad state、violated contract、original trigger、counterfactual proof 和 escape reason。
+14. 分配 `FIX-*` change key 后立刻执行 Worktree Branch Contract：detached worktree 先挂到 `FIX/<task>`；当前在 `main` / default branch 时停止，不写 investigation artifacts。
 
 ## Iron Law
 
@@ -32,9 +34,21 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 
 root-cause contract 至少包含：稳定复现或缩小后的可验证症状、被破坏的代码 / 配置 / 数据 / 依赖契约、已证伪假设、最小修复边界。
 
+## Root Cause Proof Ladder
+
+根因要从“看到错误的地方”追到“错误第一次被制造的地方”：
+
+1. `L1 Symptom Site`：用户看到的失败。
+2. `L2 First Bad State`：第一个坏字段、坏 artifact、坏队列消息、坏配置或坏状态。
+3. `L3 Violated Contract`：被破坏的 schema、invariant、state transition、权限边界或协议。
+4. `L4 Original Trigger`：制造坏状态的用户动作、命令、事件、recent diff、配置或外部响应。
+5. `L5 Counterfactual Proof`：恢复 contract 或替换输入后，症状变化的实际观察。
+6. `L6 Escape Reason`：为什么测试、类型、review、监控或 artifact gate 没挡住。
+
+缺 `L2`、`L4` 或 `L5` 时，`analysis.md` 只能写 `needs-more-evidence`、`Evidence Request` 或 reroute，不能生成 `cc-do` repair task。
+
 ## Required Outputs
 
-- `planning/analysis.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
 - `change-meta.json`
@@ -91,6 +105,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 
 - Boundary Probe Matrix：component boundary、input observed、output observed、config/env observed、state observed、verdict
 - Backward Trace Chain：immediate failure site、caller chain、bad value origin、original trigger、why symptom-site fix is rejected
+- Root Cause Proof Ladder：symptom site、first bad state、violated contract、original trigger、counterfactual proof、escape reason
 - Reference Comparison：similar working example、broken path、differences accepted / ruled out
 - Diagnostic Instrumentation Plan：probe tag、probe location、question answered、command、expected signal、cleanup requirement
 - Feedback Loop Contract：loop type、command、expected / actual signal、symptom match、runtime、determinism、failure rate、sharpening plan
@@ -158,14 +173,15 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 
 ## Local Kit
 
-- 模板在 `assets/`
+- 默认模板在 `assets/TASKS_TEMPLATE.md` 和 `assets/TASK_MANIFEST_TEMPLATE.json`
+- 旧分析模板在 `assets/legacy/`，只用于 legacy fallback / migration
 - 调查契约在 `references/investigation-contract.md`
 - 需要分析骨架时用 `scripts/bootstrap-analysis.sh`
 - Roadmap 回写使用 `../cc-roadmap/scripts/locate-roadmap-item.sh` 和 `../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Exit Rule
 
-只有当下一位执行者读完 `planning/analysis.md`、`planning/tasks.md`、`planning/task-manifest.json` 就知道：
+只有当下一位执行者读完 `planning/tasks.md`、`planning/task-manifest.json` 就知道：
 
 - 为什么坏
 - 该修什么

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

@@ -1,6 +1,6 @@
 ---
 name: cc-investigate
-version: 1.3.0
+version: 1.5.0
 description: "Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation, reproducible evidence, and a frozen repair handoff before cc-do resumes coding."
 triggers:
   - "帮我查这个 bug"
@@ -14,15 +14,12 @@ reads:
   - "PLAYBOOK.md"
   - "CHANGELOG.md"
   - "references/investigation-contract.md"
-  - "assets/ANALYSIS_TEMPLATE.md"
+  - "docs/guides/project-postmortem.md"
   - "assets/TASKS_TEMPLATE.md"
   - "assets/TASK_MANIFEST_TEMPLATE.json"
   - "../cc-roadmap/scripts/locate-roadmap-item.sh"
   - "../cc-roadmap/scripts/sync-roadmap-progress.sh"
 writes:
-  - path: "devflow/changes/<change-key>/planning/analysis.md"
-    durability: "durable"
-    required: true
   - path: "devflow/changes/<change-key>/planning/tasks.md"
     durability: "durable"
     required: true
@@ -37,19 +34,26 @@ effects:
 entry_gate:
   - "Read the current bug report, existing requirement artifacts, relevant code, tests, and recent history before forming any hypothesis."
   - "Assign the change key by running `cc-devflow next-change-key --prefix FIX --description \"<short bug name>\"`. Use both output lines: first is changeId for task-manifest, second is the full changeKey for the directory."
+  - "Immediately after assigning the change key and before writing durable artifacts, enforce the Worktree Branch Contract: if the current worktree is detached, create or switch to the canonical `FIX/<task>` branch derived from the change key; if the current branch is the default branch (`main` / `master` / origin HEAD), stop with a setup blocker instead of investigating on main."
   - "Build a runnable feedback loop, confirm it matches the reported symptom, then freeze the evidence chain before proposing repair tasks."
   - "Record persistent debug session state: active hypothesis, probes, cleanup status, and next evidence action."
   - "Search prior investigations, TODO/backlog signals, and recent fixes in the affected area before declaring the bug novel."
+  - "Search project postmortems before forming final hypotheses: check `devflow/postmortems/INDEX.md`, `principles.md`, and matching `incidents/*.md` for similar symptoms, modules, failure classes, Git patterns, and model-risk lessons."
   - "For multi-component, deep-stack, or flaky symptoms, record boundary probes, backward trace, or condition-wait evidence before declaring the root cause."
+  - "Run the Root Cause Proof Ladder before generating repair tasks: symptom site, first bad state, violated contract, original trigger, counterfactual proof, and escape reason must all be explicit."
   - "For performance regressions, collect a baseline or profile signal before treating logs as evidence."
-  - "Do not write production code here; this stage ends with planning/analysis.md plus executable repair tasks for cc-do."
+  - "Do not write production code here; this stage ends with planning/tasks.md#Root Cause Contract plus executable repair tasks for cc-do."
   - "Before exit, locate the source RM in `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`, or legacy `devflow/roadmap-tracking.json`; the repair handoff must not leave roadmap progress stale."
 exit_criteria:
-  - "planning/analysis.md records symptom, reproduction, evidence chain, boundary probes or backward trace when applicable, pattern analysis, tested hypotheses, confirmed root cause, and repair boundary."
+  - "planning/tasks.md contains `## Root Cause Contract` with symptom, reproduction, evidence chain, boundary probes or backward trace when applicable, pattern analysis, tested hypotheses, confirmed root cause, and repair boundary."
+  - "planning/tasks.md#Root Cause Contract proves the first bad state and original trigger, not only the visible error site."
+  - "planning/tasks.md#Root Cause Contract records the Project Postmortem Recall result, including matching incidents/principles or an explicit no-history verdict."
   - "diagnose-only outcomes clearly stop before implementation while preserving root cause, owner, and next action."
   - "workflow forensics classify artifact, git, state, or tool failures before repair tasks are generated."
   - "planning/tasks.md and planning/task-manifest.json are explicit enough that cc-do can repair the bug without chat memory."
-  - "The source roadmap item has been synchronized with the investigation outcome, or `planning/analysis.md` and `change-meta.json` record why no roadmap update is valid."
+  - "planning/tasks.md and change-meta.json record the canonical work branch or the explicit reason no branch mutation was valid."
+  - "`cc-devflow query workflow-context` can derive the IDCA next action, packet digests, default section refs, repair task, trusted commands, and deep-open triggers from the frozen investigation artifacts."
+  - "The source roadmap item has been synchronized with the investigation outcome, or `planning/tasks.md` and `change-meta.json` record why no roadmap update is valid."
   - "The honest next step is cc-do, cc-plan, or roadmap."
 reroutes:
   - when: "The issue is actually a new feature, a scope redesign, or a product decision instead of a bug investigation."
@@ -64,7 +68,7 @@ recovery_modes:
     action: "Drop the narrative, rebuild the reproduction from canonical artifacts and fresh output, then restate the symptom before testing hypotheses."
   - name: "re-open-investigation"
     when: "New execution evidence disproves the current root-cause contract or widens the suspected blast radius."
-    action: "Reopen planning/analysis.md, update the evidence chain, and regenerate repair tasks only after the new root cause is frozen."
+    action: "Reopen planning/tasks.md#Root Cause Contract, update the evidence chain, and regenerate machine records only after the new root cause is frozen."
 tool_budget:
   read_files: 11
   search_steps: 6
@@ -95,18 +99,35 @@ tool_budget:
 
 写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
 
-- `Output language` 是机器约束，`planning/analysis.md`、`planning/tasks.md` 和 `change-meta.json` 必须记录并遵守它。
+- `Output language` 是机器约束，`planning/tasks.md` 和 `change-meta.json` 必须记录并遵守它。
 - `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
 - 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
 
+## Worktree Branch Contract
+
+每个新的 `FIX` 默认拥有一个同名工作分支。主项目 checkout 的 `main` 只服务同步、审查和 parity proof，不承载调查产物或修复实现。
+
+分支锚定顺序固定：
+
+1. 先运行 `cc-devflow next-change-key --prefix FIX --description "<short bug name>"`，得到 `changeId` 和完整 `changeKey`。
+2. 计算 canonical work branch：`FIX/<task>`，其中 `<task>` 是去掉 `FIX-` 前缀后的 change key 尾部。例如 `FIX-014-auth-race` -> `FIX/014-auth-race`。
+3. 立即检查 `git branch --show-current`：
+   - 为空：当前是 detached worktree，立刻 `git switch -c <canonical-work-branch>`；如果分支已存在且指向当前 HEAD，可以 `git switch <canonical-work-branch>`。
+   - 等于 default branch（`main` / `master` / `origin/HEAD` 指向的分支）：停止并报告 setup blocker；不要在主分支写 investigation artifacts。
+   - 等于 canonical work branch：继续。
+   - 其它分支：只有它已经明确绑定同一个 `changeKey` 时才继续；否则停止并让用户确认是否切换或新开 worktree。
+4. 在 `planning/tasks.md` 和 `change-meta.json` 记录 work branch。没有记录 work branch 的 repair handoff 不能进入 `cc-do`。
+
+这不是发布前补救动作。`cc-act` 的 detached HEAD rescue 只处理历史遗留；新的 `cc-investigate` 必须在入口阶段就把 worktree 绑定到 `FIX/<task>`。
+
 ## Read First
 
 1. `PLAYBOOK.md`
 2. `CHANGELOG.md`
 3. `references/investigation-contract.md`
-4. `assets/ANALYSIS_TEMPLATE.md`
-5. `assets/TASKS_TEMPLATE.md`
-6. `assets/TASK_MANIFEST_TEMPLATE.json`
+4. `assets/TASKS_TEMPLATE.md`
+5. `assets/TASK_MANIFEST_TEMPLATE.json`
+6. `docs/guides/project-postmortem.md`
 
 ## Use This Skill When
 
@@ -133,6 +154,27 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 3. 哪些假设被证伪，为什么不是它们。
 4. 最小修复边界在哪里，哪些文件明确不该动。
 
+## Root Cause Proof Ladder
+
+`cc-investigate` 的根因不是“报错点在哪里”，而是“坏状态第一次被制造在哪里”。任何只修 symptom site 的结论默认不合格，除非已经证明 symptom site 就是 original trigger。
+
+每次调查必须爬完这 6 层，无法爬完就不能生成 repair task：
+
+1. `L1 Symptom Site`：用户看见的错误、失败命令、UI 状态、日志或坏 artifact。
+2. `L2 First Bad State`：第一个可观察到状态从正确变成错误的位置；可以是文件、字段、缓存、队列消息、API 响应、配置或内存对象。
+3. `L3 Violated Contract`：被破坏的 schema、capability invariant、API contract、state transition、权限边界或时序条件。
+4. `L4 Original Trigger`：哪个用户动作、命令、事件、recent diff、配置变化或外部响应制造了 first bad state。
+5. `L5 Counterfactual Proof`：如果恢复该 contract、替换输入、回滚 diff、固定配置或断言边界，症状应如何变化；必须记录实际观察。
+6. `L6 Escape Reason`：为什么现有测试、类型、验证、监控、review 或 artifact gate 没提前挡住它。
+
+硬规则：
+
+- `First bad state` 为空时，root cause 只能是 `needs-more-evidence`。
+- `Original trigger` 为空时，不能把下游 guard 写成根因修复。
+- `Counterfactual proof` 为空时，假设只能停在 candidate，不准进入 confirmed root cause。
+- `Escape reason` 不能写成人工提醒；必须变成 regression test、artifact guard、capability invariant、operator check 或明确的 follow-up。
+- 如果 ladder 指向 spec 缺失或路线假设错误，停止生成修复任务，reroute 到 `cc-plan` 或 `roadmap`。
+
 ## Quick Start
 
 先判断你面对的是哪一类调查现实：
@@ -157,44 +199,55 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 
 ## Harness Contract
 
-- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, write `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`, then run the final roadmap progress sync for the source RM.
+- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, write `planning/tasks.md`, generate `planning/task-manifest.json` / `change-meta.json`, then run the final roadmap progress sync for the source RM.
 - Forbidden actions: writing production code, disguising guesses as root cause, or skipping directly from symptoms to repair.
 - Required evidence: every root-cause claim must point to reproduction evidence, code facts, recent history, or explicit user confirmation.
 - Reroute rule: product/scope changes go to `cc-plan`; strategy questions go to `roadmap`; only confirmed repair handoff goes to `cc-do`.
 
+## Project Postmortem Recall Gate
+
+`cc-investigate` 必须先查项目级 AI 尸检报告，再宣称 bug 是新问题。历史不是权威结论，但它能暴露模型容易重复的错判。
+
+```bash
+rg -n "<symptom|module|boundary|failure-class|model-risk>" devflow/postmortems
+```
+
+执行规则：
+
+1. `devflow/postmortems/` 不存在时，在 `planning/tasks.md#Root Cause Contract` 记录 `no-project-postmortems-yet`。
+2. 有命中时，先读 `INDEX.md` / `principles.md`，再打开最相关的 1-2 个 incident。
+3. 相关 incident 必须进入假设表或反证表：同根因、相似症状不同根因、已知模型陷阱、或明确不相关。
+4. 如果本次确认是重复根因，`Root Cause` 的 `Prior history relationship` 必须标成 `recurring` 或 `same-root-cause`。
+
 ## Output Model
 
-`cc-investigate` 只允许产出 4 个主文件：
-
-1. `planning/analysis.md`
-   - 现象
-   - 复现
-   - 证据链
-   - 假设表
-   - 已确认根因
-   - 修复边界
-2. `planning/tasks.md`
-   - 只保留真正要执行的修复任务
-   - 顶部明确 canonical contract 是 `planning/analysis.md`
-3. `planning/task-manifest.json`
+`cc-investigate` 默认只允许产出 3 个主文件：
+
+1. `planning/tasks.md`
+   - 唯一默认 human-authored Markdown
+   - `## Root Cause Contract` 记录现象、复现、证据链、假设表、已确认根因和修复边界
+   - 后续区块只保留真正要执行的修复任务
+   - 顶部明确 canonical contract 是 `planning/tasks.md#Root Cause Contract`
+2. `planning/task-manifest.json`
    - 机器真相源
    - 标记当前任务、依赖、验证命令、调查版本链
-4. `change-meta.json`
+3. `change-meta.json`
    - 标记当前 bug 是实现偏离 spec、spec 本身缺失，还是 roadmap 假设错误
    - 记录这次修复会如何影响 capability truth
 
 `cc-investigate` 不写生产代码，不在这里偷跑 `cc-do`。
 
-diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能包含证据交接、
+diagnose-only 仍然写 `planning/tasks.md#Root Cause Contract`，但 task blocks 只能包含证据交接、
 监控、人工动作或明确的 `reroute`；不能把“已经诊断”伪装成“已经修复”。
 
 ## Entry Gate
 
 1. 先确认当前对象仍然属于一个 requirement，而不是整个项目级故障。
-2. 先收症状事实：错误、触发条件、影响面、复现路径。
-3. 先读现有 change 目录里的 `planning/design.md` / `planning/analysis.md` / `planning/tasks.md` / `planning/task-manifest.json`，不要假设自己是第一位调查者。
-4. 先读代码、测试、日志、相关 capability spec 和最近提交，再下任何假设。
-5. 如果复现都不稳定，先不要写根因。
+2. 先分配 canonical `FIX-*` change key，并执行 Worktree Branch Contract；detached worktree 必须先挂到 `FIX/<task>`，主分支必须停止。
+3. 先收症状事实：错误、触发条件、影响面、复现路径。
+4. 先读现有 change 目录里的 `planning/design.md` / `planning/analysis.md` / `planning/tasks.md` / `planning/task-manifest.json`，不要假设自己是第一位调查者。
+5. 先读代码、测试、日志、相关 capability spec 和最近提交，再下任何假设。
+6. 如果复现都不稳定，先不要写根因。
 
 ## Investigation Loop
 
@@ -234,13 +287,15 @@ diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能
    - debug 日志必须带唯一前缀，例如 `[DEBUG-FIX123-a4f2]`，进入 `cc-do` 前用前缀 grep 清理或转正
    - 三次假设都失败，就停下进入 escalation decision
 7. **Freeze repair contract**
-   - 根因确认后，写进 `planning/analysis.md`
+   - 先填写 `Root Cause Proof Ladder`：symptom site、first bad state、violated contract、original trigger、counterfactual proof、escape reason
+   - 如果 first bad state、original trigger 或 counterfactual proof 缺失，只能写 `Evidence Request` 或 reroute，不能生成 repair task
+   - 根因确认后，写进 `planning/tasks.md#Root Cause Contract`
    - 只保留最小修复边界
    - 写清正确测试缝隙：测试是否覆盖真实触发链；如果没有正确 seam，这本身就是需要记录的架构事实
    - 写明 affected module、allowed files、forbidden files、blast radius estimate；超过 5 个文件默认拆分或 reroute
    - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
 8. **Roadmap sync**
-   - 用 `locate-roadmap-item.sh` 定位 source RM；找不到时在 `analysis.md` 和 `change-meta.json.roadmapSync` 写 `no-source-rm`
+   - 用 `locate-roadmap-item.sh` 定位 source RM；找不到时在 `planning/tasks.md#Root Cause Contract` 和 `change-meta.json.roadmapSync` 写 `no-source-rm`
    - `implementation drift`：回写 source RM 为 `Repair planned` 或等价调查完成状态，绑定 `FIX-*`，进度保持在可执行修复前的真实百分比
    - `missing spec truth`：回写 source RM 的 expected spec delta 或 follow-up，必要时 reroute 到 `cc-plan`
    - `roadmap mismatch`：不要直接进入修复；先把 mismatch 写回 roadmap / backlog，下一步写 `roadmap` 或 `cc-plan`
@@ -284,7 +339,7 @@ diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能
 
 ## Backward Trace Chain
 
-报错点很深时，不准只在 symptom site 加 guard。`analysis.md` 必须追到：
+报错点很深时，不准只在 symptom site 加 guard。`planning/tasks.md#Root Cause Contract` 必须追到：
 
 - immediate failure site
 - direct caller
@@ -383,7 +438,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 4. 既有 `report-card.json` finding 和 `planning/analysis.md`
 5. 可用时，查询项目记忆或历史调查摘要
 
-如果命中过往调查，写入 `analysis.md` 的 `Prior Investigations`，包括是否复发、根因是否同类、这次是否说明结构问题。
+如果命中过往调查，写入 `planning/tasks.md#Root Cause Contract` 的 `Prior Investigations`，包括是否复发、根因是否同类、这次是否说明结构问题。
 
 ## External Research Hygiene
 
@@ -423,7 +478,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 
 ## Escalation Decision
 
-三次假设失败后，不准继续硬猜。`analysis.md` 必须写：
+三次假设失败后，不准继续硬猜。`planning/tasks.md#Root Cause Contract` 必须写：
 
 - failedHypothesisCount
 - what was attempted
@@ -436,6 +491,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 
 - 看完第一屏就知道 bug 是什么、怎么复现、为什么会坏
 - 根因不是感觉，而是被证据钉死的具体断点
+- 根因证明追到 first bad state 和 original trigger，而不是停在 symptom site
 - 假设不是列表装饰，而是带证伪方法和实际观察
 - 历史调查、最近改动、模式分析没有被跳过
 - 修复边界清楚到 `cc-do` 不需要二次调查
@@ -448,7 +504,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 
 - 变更记录：`CHANGELOG.md`
 - 调查契约：`references/investigation-contract.md`
-- 分析模板：`assets/ANALYSIS_TEMPLATE.md`
+- legacy 分析模板：`assets/legacy/ANALYSIS_TEMPLATE.md`
 - 修复任务模板：`assets/TASKS_TEMPLATE.md`
 - manifest 模板：`assets/TASK_MANIFEST_TEMPLATE.json`
 - 分析骨架：`scripts/bootstrap-analysis.sh`
@@ -468,10 +524,11 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 9. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
 10. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
 11. Roadmap 相关文件以 `devflow/roadmap.json` 为真相源，`devflow/ROADMAP.md` / `devflow/BACKLOG.md` 只是投影；不要再写旧式 `devflow/roadmap/*` 路径。
+12. 一个 `FIX` 对应一个 canonical work branch；新调查不在 `main` 上落盘，不把 detached worktree 留到 `cc-act` 才补救。
 
 ## Exit Criteria
 
-- `planning/analysis.md` 已冻结症状、复现、证据链、根因和修复边界
+- `planning/tasks.md#Root Cause Contract` 已冻结症状、复现、证据链、根因和修复边界
 - `planning/tasks.md` / `planning/task-manifest.json` 可直接交给 `cc-do`
 - Roadmap Sync Gate 已闭合：source RM 已回写调查结果 / reroute，或 no-op reason 已落盘
 - 下一步唯一答案是 `cc-do`、`cc-plan` 或 `roadmap`