cc-devflow 4.5.9 → 4.5.10

package/.claude/skills/cc-do/scripts/build-task-context.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 # ------------------------------------------------------------
-# 组装当前任务的执行上下文，并记录 context_ready 事件
+# 组装当前任务的执行上下文，只输出到 stdout
 # ------------------------------------------------------------
 
 usage() {
@@ -51,12 +51,8 @@ if [[ -z "$task_json" ]]; then
 fi
 
 change_id="$(jq -r '.changeId // .requirementId // "REQ-UNKNOWN"' "$manifest")"
-runtime_task_dir="$(req_do_task_runtime_dir "$CHANGE_DIR" "$TASK_ID")"
-output_path="$runtime_task_dir/context.md"
 ready_json="$("$SCRIPT_DIR/select-ready-tasks.sh" --manifest "$manifest")"
 
-mkdir -p "$runtime_task_dir"
-
 list_or_none() {
   local value="$1"
   if [[ -z "${value//$'\n'/}" ]]; then
@@ -168,21 +164,12 @@ sync_status="$(jq -r '.spec.syncStatus // "unknown"' "$spec_source" 2>/dev/null
   echo
   echo "## Context Reset"
   echo
-  echo "- If chat context drifts, discard conversational memory and reload only the canonical files above plus the latest checkpoint."
-  echo "- Do not continue from memory if the current task, active phase, or latest checkpoint summary cannot be restated exactly."
+  echo "- If chat context drifts, discard conversational memory and reload only the canonical files above, current Git state, and CLI logs."
+  echo "- Do not continue from memory if the current task, active phase, or latest verification status cannot be restated exactly."
   echo
   if [[ -f "$resume_index" ]]; then
     echo "## Optional Resume Index"
     echo
     cat "$resume_index"
   fi
-} > "$output_path"
-
-"$SCRIPT_DIR/write-task-checkpoint.sh" \
-  --dir "$CHANGE_DIR" \
-  --task "$TASK_ID" \
-  --status pending \
-  --summary "Task context assembled" \
-  --next-action "Write the failing test for $TASK_ID" >/dev/null
-
-cat "$output_path"
+}

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,22 @@
 # 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

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,7 +16,7 @@
 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 问题必须先补边界探针、反向追踪或条件等待证据。
@@ -24,6 +24,7 @@
 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
 
@@ -48,7 +49,6 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 
 ## Required Outputs
 
-- `planning/analysis.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
 - `change-meta.json`
@@ -173,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.4.1
+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"
@@ -15,15 +15,11 @@ reads:
   - "CHANGELOG.md"
   - "references/investigation-contract.md"
   - "docs/guides/project-postmortem.md"
-  - "assets/ANALYSIS_TEMPLATE.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
@@ -38,6 +34,7 @@ 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."
@@ -45,16 +42,18 @@ entry_gate:
   - "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/analysis.md proves the first bad state and original trigger, not only the visible error site."
-  - "planning/analysis.md records the Project Postmortem Recall result, including matching incidents/principles or an explicit no-history verdict."
+  - "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."
@@ -69,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
@@ -100,19 +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`
-7. `docs/guides/project-postmortem.md`
+4. `assets/TASKS_TEMPLATE.md`
+5. `assets/TASK_MANIFEST_TEMPLATE.json`
+6. `docs/guides/project-postmortem.md`
 
 ## Use This Skill When
 
@@ -184,7 +199,7 @@ 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`.
@@ -199,44 +214,40 @@ rg -n "<symptom|module|boundary|failure-class|model-risk>" devflow/postmortems
 
 执行规则：
 
-1. `devflow/postmortems/` 不存在时，在 `planning/analysis.md` 记录 `no-project-postmortems-yet`。
+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
 
@@ -278,13 +289,13 @@ diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能
 7. **Freeze repair contract**
    - 先填写 `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/analysis.md`
+   - 根因确认后，写进 `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`
@@ -328,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
@@ -427,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
 
@@ -467,7 +478,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 
 ## Escalation Decision
 
-三次假设失败后，不准继续硬猜。`analysis.md` 必须写：
+三次假设失败后，不准继续硬猜。`planning/tasks.md#Root Cause Contract` 必须写：
 
 - failedHypothesisCount
 - what was attempted
@@ -493,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`
@@ -513,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`

package/.claude/skills/cc-investigate/assets/TASKS_TEMPLATE.md

@@ -5,6 +5,7 @@
 - Requirement version:
 - Analysis version:
 - Investigate skill version:
+- Work branch:
 - Output language:
 - Source bug / incident:
 - Roadmap sync status:
@@ -12,14 +13,56 @@
 
 ## Progressive Disclosure Index
 
-- Default read: Investigation Meta, Execution Handoff, current task block.
-- Open for root-cause doubt: `planning/analysis.md` Project Postmortem Recall, Feedback Loop, Evidence Chain, Boundary Probe Matrix.
+- Default read: Investigation Meta, Root Cause Contract, Execution Handoff, current task block.
+- Runtime reset: run `cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact` before `cc-do`, `cc-check`, or `cc-act`; use `packetOnly` plus `mustNotForget` first, verify `sourceHashes`, open `defaultOpen` refs only when needed, and reserve `deepOpen` for matching `openWhen.conditions`.
+- Open for root-cause doubt: `planning/tasks.md#Root Cause Contract` Project Postmortem Recall, Feedback Loop, Evidence Chain, Boundary Probe Matrix.
 - Open for scheduling: `planning/task-manifest.json`, dependencies, touched files.
-- Open for audit/recovery: checkpoint files, report-card findings, Workflow Forensics.
+- Open for audit/recovery: Git state, CLI logs, report-card findings, Workflow Forensics.
+
+## Root Cause Contract
+
+Change:
+Mode: investigation
+Approval:
+
+Symptom:
+-
+
+Reproduction:
+-
+
+Feedback Loop:
+-
+
+Root Cause Proof Ladder:
+- Symptom site:
+- First bad state:
+- Violated contract:
+- Original trigger:
+- Counterfactual proof:
+- Escape reason:
+
+Confirmed Root Cause:
+-
+
+Frozen Repair Boundary:
+- Allowed files:
+- Forbidden files:
+- Blast radius:
+
+Verification:
+-
+
+Risk / Escalate If:
+-
+
+> This is the default human-authored investigation contract. Do not create
+> `planning/analysis.md` for new investigations unless the user explicitly
+> requests a legacy artifact or a migration requires preserving one.
 
 ## Execution Handoff
 
-- Canonical analysis: `planning/analysis.md`
+- Canonical contract: `planning/tasks.md#Root Cause Contract`
 - Canonical change meta: `change-meta.json`
 - Execution mode: `single-path` | `parallel-ready`
 - Confirmed root cause:
@@ -68,7 +111,7 @@
   Read first: `analysis.md`, `path/to/test`
   Project postmortem search: `rg -n "<root cause|module|failure-class|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/test`
-  Evidence: passing output + checkpoint
+  Evidence: passing output + Git diff
   Do not re-decide: root cause, first bad state, original trigger, allowed files, forbidden files
   Ready when: T001 已证明同一个用户症状存在，analysis 已证明根因源头和 counterfactual proof