cc-devflow 4.3.0 → 4.5.0

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 校验任务是否完成 Red / Green / Refactor / Review 闭环
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage:
+  verify-task-gates.sh --dir path/to/change --task T001
+EOF
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/cc-do-common.sh"
+REQ_DIR=""
+TASK_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) REQ_DIR="$2"; shift 2 ;;
+    --task) TASK_ID="$(echo "$2" | tr '[:lower:]' '[:upper:]')"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$REQ_DIR" || -z "$TASK_ID" ]]; then
+  usage
+  exit 1
+fi
+
+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
+  exit 1
+}
+
+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)"
+
+[[ "$spec_verdict" == "pass" ]] || {
+  echo "Task $TASK_ID spec review verdict is not pass" >&2
+  exit 1
+}
+
+[[ "$code_verdict" == "pass" ]] || {
+  echo "Task $TASK_ID code review verdict is not pass" >&2
+  exit 1
+}
+
+if [[ -f "$events_file" ]]; then
+  events=()
+  while IFS= read -r event; do
+    events+=("$event")
+  done < <(jq -r --arg task "$TASK_ID" 'select(.taskId == $task) | .type' "$events_file")
+
+  if [[ ${#events[@]} -gt 0 ]]; then
+    first_index() {
+      local target="$1"
+      local index=0
+      for event in "${events[@]}"; do
+        if [[ "$event" == "$target" ]]; then
+          echo "$index"
+          return
+        fi
+        index=$((index + 1))
+      done
+      echo "-1"
+    }
+
+    red_idx="$(first_index "red_failed")"
+    green_idx="$(first_index "green_passed")"
+    if [[ "$red_idx" != "-1" && "$green_idx" != "-1" && "$red_idx" -ge "$green_idx" ]]; then
+      echo "Task $TASK_ID gate order is invalid" >&2
+      exit 1
+    fi
+  fi
+fi
+
+echo "Task $TASK_ID gates verified"

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 写入 task checkpoint.json / events.jsonl
+# ------------------------------------------------------------
+
+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 "..."]
+EOF
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/cc-do-common.sh"
+REQ_DIR=""
+TASK_ID=""
+STATUS=""
+SUMMARY=""
+EVENT_TYPE=""
+ATTEMPT="0"
+SESSION_ID=""
+NEXT_ACTION=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) REQ_DIR="$2"; shift 2 ;;
+    --task) TASK_ID="$(echo "$2" | tr '[:lower:]' '[:upper:]')"; shift 2 ;;
+    --status) STATUS="$2"; shift 2 ;;
+    --summary) SUMMARY="$2"; shift 2 ;;
+    --event) EVENT_TYPE="$2"; shift 2 ;;
+    --attempt) ATTEMPT="$2"; shift 2 ;;
+    --session) SESSION_ID="$2"; shift 2 ;;
+    --next-action) NEXT_ACTION="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$REQ_DIR" || -z "$TASK_ID" || -z "$STATUS" || -z "$SUMMARY" ]]; then
+  usage
+  exit 1
+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
+
+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" \
+  '{
+    changeId: $changeId,
+    taskId: $taskId,
+    sessionId: $sessionId,
+    planVersion: ($planVersion | tonumber),
+    status: $status,
+    summary: $summary,
+    timestamp: $timestamp,
+    attempt: ($attempt | tonumber)
+  }' > "$runtime_task_dir/checkpoint.json"
+
+if [[ -n "$EVENT_TYPE" || "$STATUS" == "failed" ]]; then
+  jq -nc \
+    --arg type "${EVENT_TYPE:-status_$STATUS}" \
+    --arg changeId "$change_id" \
+    --arg taskId "$TASK_ID" \
+    --arg sessionId "$SESSION_ID" \
+    --arg status "$STATUS" \
+    --arg summary "$SUMMARY" \
+    --arg nextAction "$NEXT_ACTION" \
+    --arg timestamp "$timestamp" \
+    '{
+      type: $type,
+      changeId: $changeId,
+      taskId: $taskId,
+      sessionId: $sessionId,
+      status: $status,
+      summary: $summary,
+      nextAction: $nextAction,
+      timestamp: $timestamp
+    }' >> "$runtime_task_dir/events.jsonl"
+fi
+
+echo "Wrote $runtime_task_dir/checkpoint.json"

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

@@ -0,0 +1,31 @@
+# CC-Investigate Skill Changelog
+
+## v1.1.2 - 2026-04-27
+
+- require investigation outputs to resolve the runtime output policy before writing analysis, task, or change metadata artifacts
+- record `Output language` as the machine-enforced language contract while treating `agent_preferences` as advisory style input
+
+## v1.1.1 - 2026-04-25
+
+- require new bug-fix investigations to use `FIX-<number>-<description>` change keys
+- update manifest examples so repair handoffs no longer advertise `REQ-*` for fresh fix work
+
+Migration note:
+
+- existing `REQ-*` investigation directories can still be read as historical requirement-linked work; new bug-fix work should start with `FIX-*`
+
+## v1.1.0 - 2026-04-19
+
+- add `change-meta.json` to the investigation output so bug work also preserves capability/spec linkage
+- upgrade `ANALYSIS.md`, debug task handoff, and manifest templates with spec diagnosis and expected spec delta fields
+- teach investigation to classify whether the problem is implementation drift, missing spec truth, or roadmap mismatch
+
+Migration note:
+
+- investigated bug changes should now refresh or create `devflow/changes/<change-key>/change-meta.json`
+
+## v1.0.0 - 2026-04-17
+
+- 初始版 `cc-investigate` skill，作为 bug 路径里的专用调查入口。
+- 把根因调查从 `cc-do` 中拆出，形成 `cc-investigate -> cc-do -> cc-check -> cc-act` 的独立闭环。
+- 新增 `ANALYSIS.md`、debug `TASKS.md`、`task-manifest.json` 的调查输出模型，让 bug 修复也能留下可执行 handoff。

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

@@ -0,0 +1,49 @@
+# CC-Investigate Playbook
+
+## Visible State Machine
+
+`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.
+- Exit to: `cc-do` only after root cause and repair boundary are explicit in canonical artifacts.
+- Reroute to: `cc-plan` for scope/design truth changes, or `roadmap` for project-level priority decisions.
+
+## Core Rules
+
+1. 先复现，再猜原因。
+2. 先看最近变化，再决定是不是 regression。
+3. 先证伪假设，再冻结根因。
+4. `planning/analysis.md` 和 `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
+5. 调查失败三次后先重建入口，不准继续乱补。
+
+## Required Outputs
+
+- `planning/analysis.md`
+- `planning/tasks.md`
+- `planning/task-manifest.json`
+
+## Investigation Standard
+
+1. 先收集 symptom、expected、actual、repro。
+2. 先沿代码路径定位触点和最近变更。
+3. 每个假设都要写支持证据和反证。
+4. 只有被证据钉死的根因才能进入 repair contract。
+5. repair contract 只讲最小修复边界，不顺手发明新范围。
+
+## Local Kit
+
+- 模板在 `assets/`
+- 调查契约在 `references/investigation-contract.md`
+- 需要分析骨架时用 `scripts/bootstrap-analysis.sh`
+
+## Exit Rule
+
+只有当下一位执行者读完 `planning/analysis.md`、`planning/tasks.md`、`planning/task-manifest.json` 就知道：
+
+- 为什么坏
+- 该修什么
+- 不该扩到哪里
+- 用什么命令证明修好了
+
+这次调查才算合格。

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

@@ -0,0 +1,229 @@
+---
+name: cc-investigate
+version: 1.1.2
+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"
+  - "先别修先找根因"
+  - "debug this bug"
+  - "investigate this regression"
+  - "why is this broken"
+  - "root cause this"
+  - "先调查再修"
+reads:
+  - "PLAYBOOK.md"
+  - "CHANGELOG.md"
+  - "references/investigation-contract.md"
+  - "assets/ANALYSIS_TEMPLATE.md"
+  - "assets/TASKS_TEMPLATE.md"
+  - "assets/TASK_MANIFEST_TEMPLATE.json"
+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
+  - path: "devflow/changes/<change-key>/planning/task-manifest.json"
+    durability: "durable"
+    required: true
+  - path: "devflow/changes/<change-key>/change-meta.json"
+    durability: "durable"
+    required: true
+entry_gate:
+  - "Read the current bug report, existing requirement artifacts, relevant code, tests, and recent history before forming any hypothesis."
+  - "Use a FIX-<number>-<description> change key for new bug-fix investigations."
+  - "Reproduce or narrow the symptom first, then freeze the evidence chain before proposing repair tasks."
+  - "Do not write production code here; this stage ends with planning/analysis.md plus executable repair tasks for cc-do."
+exit_criteria:
+  - "planning/analysis.md records symptom, reproduction, evidence chain, confirmed root cause, and repair boundary."
+  - "planning/tasks.md and planning/task-manifest.json are explicit enough that cc-do can repair the bug without chat memory."
+  - "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."
+    target: "cc-plan"
+  - when: "The discussion expands into project sequencing or roadmap priority instead of one broken requirement."
+    target: "roadmap"
+  - when: "Root cause and repair boundary are already frozen."
+    target: "cc-do"
+recovery_modes:
+  - name: "repro-reset"
+    when: "The current conversation cannot state a stable reproduction path or the symptom evidence is stale."
+    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."
+tool_budget:
+  read_files: 10
+  search_steps: 6
+  shell_commands: 6
+---
+
+# CC-Investigate
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-investigate` 是 bug 路径里的 `Investigate`，也可以理解成 `Debug Plan`。
+
+它不是直接修 bug 的地方，而是替代原来 bug 场景下那种混在 `cc-do` 里的临场 planning。它先把症状压成证据，再把证据压成根因，再把根因压成一个可执行的修复 handoff。
+
+一句话：
+
+- 新需求走 `cc-plan -> cc-do -> cc-check -> cc-act`
+- 已知需求里的 bug 走 `cc-investigate -> cc-do -> cc-check -> cc-act`
+
+所以现在仓库里有两条闭环：
+
+- `PDCA`
+- `IDCA`，如果你更喜欢口语，也可以把它理解成 `DDCA`
+
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，`planning/analysis.md`、`planning/tasks.md` 和 `change-meta.json` 必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
+## 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`
+
+## Use This Skill When
+
+- bug 现象很多，但根因还没冻结
+- regression 已出现，不能接受“先补一个试试”
+- `cc-do` 连续修补失败，怀疑上游根因判断错了
+- review / verification 指出当前修法只是症状补丁
+- 你需要一个专门面向 debug 的可执行 handoff，而不是重开 feature planning
+
+如果问题其实是在问“应该做什么功能”或“范围是否要变”，别硬调试，回 `cc-plan`。
+
+## Quick Start
+
+先判断你面对的是哪一类调查现实：
+
+| 现实状态 | 先走什么路径 |
+| --- | --- |
+| 症状真实，但还没有稳定复现 | `reproduce-first`，先把现象钉死 |
+| 明显是 regression | `diff-trace`，先查最近变化 |
+| 症状已知，但修复边界可能扩大范围 | `contract-check`，先判是否还属于当前 requirement |
+| 看起来像 bug，实则是未定义行为或新需求 | 直接 reroute 到 `cc-plan` |
+
+先说“这是什么类问题”，再说“我要怎么修”。没有分类的 debug，最后都会变成乱打补丁。
+
+## Harness Contract
+
+- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, and write only `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`.
+- 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`.
+
+## Output Model
+
+`cc-investigate` 只允许产出 4 个主文件：
+
+1. `planning/analysis.md`
+   - 现象
+   - 复现
+   - 证据链
+   - 假设表
+   - 已确认根因
+   - 修复边界
+2. `planning/tasks.md`
+   - 只保留真正要执行的修复任务
+   - 顶部明确 canonical contract 是 `planning/analysis.md`
+3. `planning/task-manifest.json`
+   - 机器真相源
+   - 标记当前任务、依赖、验证命令、调查版本链
+4. `change-meta.json`
+   - 标记当前 bug 是实现偏离 spec、spec 本身缺失，还是 roadmap 假设错误
+   - 记录这次修复会如何影响 capability truth
+
+`cc-investigate` 不写生产代码，不在这里偷跑 `cc-do`。
+
+## Entry Gate
+
+1. 先确认当前对象仍然属于一个 requirement，而不是整个项目级故障。
+2. 先收症状事实：错误、触发条件、影响面、复现路径。
+3. 先读现有 change 目录里的 `planning/design.md` / `planning/analysis.md` / `planning/tasks.md` / `planning/task-manifest.json`，不要假设自己是第一位调查者。
+4. 先读代码、测试、日志、相关 capability spec 和最近提交，再下任何假设。
+5. 如果复现都不稳定，先不要写根因。
+
+## Investigation Loop
+
+1. **Collect symptom**
+   - 记录用户看见了什么
+   - 记录预期与实际差异
+   - 记录复现命令或手动路径
+2. **Trace reality**
+   - 沿着代码路径找触点
+   - 查最近提交和同类改动
+   - 找现有测试和断点证据
+   - 判定偏离的是 capability boundary、invariant，还是只是实现细节
+3. **Form hypotheses**
+   - 只保留 1-3 个可被证伪的假设
+   - 每个假设都写支持证据和反证
+4. **Test hypotheses**
+   - 用复现、日志、断言、最小探针验证
+   - 三次假设都失败，就停下重建上下文
+5. **Freeze repair contract**
+   - 根因确认后，写进 `planning/analysis.md`
+   - 只保留最小修复边界
+   - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
+6. **Hand off**
+   - 下一步明确写成 `cc-do`
+   - 如果 repair contract 越过当前 requirement，就 reroute 到 `cc-plan`
+
+## Good Output
+
+- 看完第一屏就知道 bug 是什么、怎么复现、为什么会坏
+- 根因不是感觉，而是被证据钉死的具体断点
+- 修复边界清楚到 `cc-do` 不需要二次调查
+- `planning/tasks.md` 只包含修复任务，不夹带新需求
+- 如果应该回 `cc-plan`，理由写清楚，不假装还能继续 patch
+
+## Bundled Resources
+
+- 变更记录：`CHANGELOG.md`
+- 调查契约：`references/investigation-contract.md`
+- 分析模板：`assets/ANALYSIS_TEMPLATE.md`
+- 修复任务模板：`assets/TASKS_TEMPLATE.md`
+- manifest 模板：`assets/TASK_MANIFEST_TEMPLATE.json`
+- 分析骨架：`scripts/bootstrap-analysis.sh`
+
+## Working Rules
+
+1. 没有复现，不准声称找到了根因。
+2. 没有证据，不准把猜测写成结论。
+3. 先根因，再修复；先调查，再编码。
+4. `planning/tasks.md` 必须足够让 `cc-do` 在脱离当前对话后继续推进。
+5. 如果修复方案已经变成新 feature 设计，停止 debug，回 `cc-plan`。
+6. 三次假设失败后，默认说明你的调查入口错了，不准继续硬猜。
+7. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
+
+## Exit Criteria
+
+- `planning/analysis.md` 已冻结症状、复现、证据链、根因和修复边界
+- `planning/tasks.md` / `planning/task-manifest.json` 可直接交给 `cc-do`
+- 下一步唯一答案是 `cc-do`、`cc-plan` 或 `roadmap`
+
+## Do Not
+
+- 不在这里写生产代码
+- 不拿“可能是”冒充“已经证实”
+- 不把新需求伪装成 bug 修复
+- 不在根因未明时开始堆 patch
+
+## Companion Files
+
+- 深入剧本：`PLAYBOOK.md`
+- 变更记录：`CHANGELOG.md`
+- 调查契约：`references/investigation-contract.md`

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

@@ -0,0 +1,56 @@
+# ANALYSIS
+
+## Investigation Meta
+
+- Requirement version:
+- Analysis version:
+- Investigate skill version:
+- Output language:
+- Source roadmap item:
+- Source roadmap version:
+- Incident / bug ID:
+- Primary capability:
+- Related capability specs:
+
+## Symptom
+
+- What the user saw:
+- Reproduction command / path:
+- Expected:
+- Actual:
+
+## Evidence Chain
+
+- Logs / stack traces:
+- Code path:
+- Recent changes:
+- Existing tests:
+
+## Hypothesis Table
+
+| Hypothesis | Evidence for | Evidence against | Status |
+| --- | --- | --- | --- |
+| | | | pending |
+
+## Root Cause
+
+- Confirmed root cause:
+- Broken contract:
+- Spec diagnosis: `implementation drift` | `missing spec truth` | `roadmap mismatch`
+- Why it escaped:
+
+## Repair Boundary
+
+- Fix strategy:
+- Files likely touched:
+- Do not change:
+- Expected spec delta:
+- Verification after fix:
+- Why this can enter `cc-do`:
+
+## Review Gate
+
+- Repro stable:
+- Root cause confirmed:
+- Repair scope still belongs to this requirement:
+- If not, reroute:

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

@@ -0,0 +1,53 @@
+# TASKS
+
+## Investigation Meta
+
+- Requirement version:
+- Analysis version:
+- Investigate skill version:
+- Output language:
+- Source bug / incident:
+- Change meta: `change-meta.json`
+
+## Execution Handoff
+
+- Canonical analysis: `planning/analysis.md`
+- Canonical change meta: `change-meta.json`
+- Execution mode: `single-path` | `parallel-ready`
+- Confirmed root cause:
+- Frozen repair boundary:
+- Capability specs:
+- Read first:
+- Commands to trust:
+- Do not re-decide:
+- Parallel boundaries:
+
+## Phase 1: Reproduce Guard
+
+- [ ] T001 [TEST] Capture the failing behavior as a stable reproduction (dependsOn:none) `path/to/test`
+  Goal: 让 bug 先变成一个可复跑的失败事实。
+  Files: `path/to/test`
+  Read first: `analysis.md`, `tasks.md`
+  Verification: `npm test -- path/to/test`
+  Evidence: failing output or reproducible log
+  Ready when: reproduction path 已稳定
+
+## Phase 2: Repair
+
+- [ ] T002 [IMPL] Apply the minimal root-cause fix (dependsOn:T001) `path/to/file`
+  Goal: 只修已确认根因，不扩成重写。
+  Files: `path/to/file`
+  Read first: `analysis.md`, `path/to/test`
+  Verification: `npm test -- path/to/test`
+  Evidence: passing output + checkpoint
+  Ready when: T001 已证明问题存在
+
+## Phase 3: Verify
+
+- [ ] T003 Run checks and collect fresh evidence (dependsOn:T002) `command or file`
+  Goal: 为 `cc-check` 准备新鲜证据。
+  Files: `command or file`
+  Read first: `tasks.md`, `task-manifest.json`
+  Verification: `npm test && npm run lint`
+  Evidence: gate output
+  Ready when: repair task 已收口