cc-devflow 4.3.0 → 4.5.0

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

@@ -0,0 +1,224 @@
+---
+name: cc-do
+version: 1.5.2
+description: Use when implementing planned tasks, resuming interrupted work, applying a frozen investigation handoff, or landing review feedback after cc-plan or cc-investigate.
+triggers:
+  - 开始做 T003
+  - 继续上次做到一半的任务
+  - 按 planning/tasks.md 开始实现
+  - 修这个 review comment
+  - implement this task
+  - resume this requirement
+  - repair this investigated bug
+reads:
+  - PLAYBOOK.md
+  - CHANGELOG.md
+  - references/execution-recovery.md
+  - references/parallel-dispatch.md
+writes:
+  - path: devflow/changes/<change-key>/execution/tasks/<task-id>/checkpoint.json
+    durability: durable
+    required: true
+  - path: devflow/changes/<change-key>/execution/tasks/<task-id>/events.jsonl
+    durability: durable
+    required: false
+    when: debug mode is enabled or the task execution fails
+  - path: devflow/changes/<change-key>/execution/team-state.json
+    durability: durable
+    required: false
+    when: execution mode uses delegated or team workers
+effects:
+  - code changes
+  - test changes
+  - workspace scratch runtime updates
+entry_gate:
+  - Read planning/design.md or planning/analysis.md, then planning/tasks.md, planning/task-manifest.json, change-meta.json, related capability specs, and the latest checkpoint before changing code.
+  - Select only ready tasks whose dependencies and file ownership are clear.
+  - If the current task cannot be restated from canonical artifacts, run a context reset before coding.
+exit_criteria:
+  - The current task has red/green evidence, review evidence, and a resumable checkpoint trail.
+  - Execution leaves the next verifier enough runtime truth to judge the task without chat memory.
+  - The honest next step is cc-check or an explicit reroute.
+reroutes:
+  - when: Three failed repair attempts or new evidence show the investigation contract is wrong.
+    target: cc-investigate
+  - when: New evidence shows the requirement design or scope contract is wrong.
+    target: cc-plan
+  - when: Implementation and reviews are complete for the current task set.
+    target: cc-check
+recovery_modes:
+  - name: resume-from-checkpoint
+    when: Work was interrupted but the current design contract is still valid.
+    action: Reload the latest checkpoint, rebuild task context, and continue from the last confirmed red/green/review milestone.
+  - name: context-reset
+    when: The conversation history is noisy, stale, or cannot reproduce the exact task state.
+    action: Discard chat memory, reread planning/design.md or planning/analysis.md plus planning/tasks.md/planning/task-manifest.json and the latest checkpoint, then restate the next action before coding.
+tool_budget:
+  read_files: 9
+  search_steps: 6
+  shell_commands: 8
+---
+
+# CC-Do
+
+> [PROTOCOL]: 变更时同步更新 `version`、`CHANGELOG.md`、相关模板/脚本引用，然后检查 `CLAUDE.md`
+
+## Role
+
+`cc-do` 是 PDCA 里的 `Do`。
+
+同时它也是 IDCA / DDCA 里的 `Do`。
+
+它只做一件事：沿着已经冻结的任务，把代码真正做出来，并把执行证据留到足够让别人接手、复盘、复验。
+
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，checkpoint、events、team-state 中新增的人类可读摘要必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
+上游冻结合同可以来自两条路：
+
+- `cc-plan` 产出的 `planning/design.md`
+- `cc-investigate` 产出的 `planning/analysis.md`
+
+## Read First
+
+1. `PLAYBOOK.md`
+2. `CHANGELOG.md`
+3. `references/execution-recovery.md`
+4. `references/parallel-dispatch.md`
+
+## Use This Skill When
+
+- 要实现 `planning/tasks.md` / `planning/task-manifest.json`
+- 执行被中断，需要恢复
+- bug 根因已经在 `cc-investigate` 里冻结，准备开始修
+- review feedback 要落成代码
+
+如果方案还没冻结、任务边界还没定，停下并回 `cc-plan` 或 `cc-investigate`。
+
+## Quick Start
+
+先判断现在是哪一种执行局面，再开始编码：
+
+| 现实状态 | 先走什么路径 |
+| --- | --- |
+| 已有 ready task，直接实现 | `implement` |
+| 上次做到一半，需要继续 | `resume` |
+| bug 根因已冻结 | `repair-from-investigation` |
+| bug 还没搞清根因 | reroute 到 `cc-investigate` |
+| 收到 review comment，要在既定范围内修正 | `review-fix` |
+
+如果连“当前 task 是什么”都说不清，先别写代码，先跑 `scripts/select-ready-tasks.sh` 和 `scripts/build-task-context.sh`。
+
+## Harness Contract
+
+- Allowed actions: implement ready tasks, debug inside frozen scope, write runtime evidence, and apply review feedback that does not reopen design.
+- Forbidden actions: re-planning the requirement in place, blindly rerunning the whole requirement, or delegating tasks without full task context.
+- Required evidence: every task must leave red/green/review checkpoints plus objective failure notes when blocked.
+- Reroute rule: after repeated failed repairs or root-cause drift, stop patching and go back to `cc-investigate`; if scope or design truth breaks, go back to `cc-plan`; after task closure, hand off to `cc-check`.
+
+## TDD Iron Law
+
+```text
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+`cc-do` 默认采用测试先行的执行纪律：
+
+1. Red：先写一个最小失败测试，运行并确认它因为目标行为缺失而失败。
+2. Green：只写让当前失败测试通过的最小生产代码。
+3. Refactor：只有 Green 之后才能清理命名、重复、结构和坏味道。
+4. Record：每一站都写入 `checkpoint.json`，必要时写入 `events.jsonl`。
+
+例外只能用于 throwaway prototype、纯生成文件、纯配置改动；例外必须写进 checkpoint 的 `tddException`，包含原因、风险和替代验证命令。测试第一次就绿，说明测试没有证明新行为，必须修测试而不是继续写生产代码。
+
+## Entry Gate
+
+1. 先读 `planning/design.md` 或 `planning/analysis.md`，再读 `planning/tasks.md`、`planning/task-manifest.json`；如果是恢复执行，再补读最近 checkpoint 或已有 `handoff/resume-index.md`。
+2. 先用 `scripts/select-ready-tasks.sh` 判断现在到底哪几个任务真的 ready。
+3. 只锁定当前 ready task，或一组经依赖与触点校验后可并行的 ready tasks。
+4. 如果这次来自 `cc-investigate`，必须把 `planning/analysis.md` 当成 canonical contract，而不是一边实现一边重新调查。
+5. 没有任务上下文，不准把任务扔给 subagent；先用 `scripts/build-task-context.sh` 从 `planning/design.md` 或 `planning/analysis.md`、`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json` 与相关 capability spec 组装上下文。
+
+## Loop
+
+1. 读取当前任务，而不是重新发明任务。
+2. 依赖没满足前，不准提前做下游任务。
+3. 没有明确并行资格，不准把多个实现任务同时推进。
+4. 先 `fail-first`：先写失败测试，先看见预期红，再写生产代码。
+5. 如果红灯不是预期失败（语法错、fixture 错、测试没连上），先修测试直到它正确失败。
+6. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现。
+7. Refactor 后必须重跑相关测试，保持 Green。
+8. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`。
+9. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
+10. 当前任务完成后，把可验证证据留给 `cc-check`。
+
+## Output
+
+- 代码变更
+- 测试变更
+- `devflow/changes/<change-key>/execution/tasks/<task-id>/checkpoint.json`
+- `devflow/changes/<change-key>/execution/tasks/<task-id>/events.jsonl`（仅 debug / failed 默认保留）
+- `planning/task-manifest.json` 里的 task review verdict
+
+## Good Output
+
+- 当前 task 一眼可见，执行者不用从聊天记录里猜目标
+- 至少留下一次明确的 Red/Green/Refactor 证据，且 Red 是预期失败
+- runtime / checkpoint 足够让下一位接手者无损恢复
+- reviewer 能顺着 review 记录和验证命令复盘这次实现
+
+## Bundled Resources
+
+- 变更记录：`CHANGELOG.md`
+- 执行 / 恢复规则：`references/execution-recovery.md`
+- 并行分配准则：`references/parallel-dispatch.md`
+- 恢复分析：`scripts/recover-workflow.sh`
+- 任务状态：`scripts/check-task-status.sh`
+- ready 任务选择：`scripts/select-ready-tasks.sh`
+- 任务上下文组装：`scripts/build-task-context.sh`
+- checkpoint 记录：`scripts/write-task-checkpoint.sh`
+- review 记录：`scripts/record-review-decision.sh`
+- 任务闭环校验：`scripts/verify-task-gates.sh`
+- 任务勾选：`scripts/mark-task-complete.sh`
+- 文件冲突：`scripts/detect-file-conflicts.sh`
+
+## Working Rules
+
+1. 没有根因，不准修 bug。
+2. 没有任务边界，不准无界发散。
+3. 没有失败测试，不准写生产代码。
+4. 测试如果第一次就绿，说明你没证明任何东西，先修测试。
+5. 红灯原因必须和目标行为缺失一致；红灯如果只是测试写错，不算 TDD 证据。
+6. 先过 `spec review`，再过 `code review`，顺序不能反。
+7. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
+8. 失败和阻塞都要留下恢复证据。
+9. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
+10. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
+
+## Exit Criteria
+
+- 当前任务有 Red/Green 证据
+- 当前任务有 `spec review` / `code review` 两道门证据
+- 恢复点已更新到 `devflow/changes/<change-key>/execution/tasks/<task-id>/`
+- 阻塞原因已写清楚
+- 下一步应进入 `cc-check`，或明确退回 `cc-investigate` / `cc-plan`
+
+## Do Not
+
+- 不在这里重开方案讨论
+- 不把一次修复膨胀成重写整个模块
+- 不把依赖任务和被依赖任务同时并行
+- 不把没有当前进度的任务直接丢给 subagent
+- 三层以上判断说明上游合同该回炉
+
+## Companion Files
+
+- 深入剧本：`PLAYBOOK.md`
+- 变更记录：`CHANGELOG.md`
+- 执行规则：`references/execution-recovery.md`
+- 并行规则：`references/parallel-dispatch.md`

package/.claude/skills/cc-do/references/execution-recovery.md

@@ -0,0 +1,86 @@
+# Execution And Recovery
+
+## Minimum Runtime Truth
+
+- 当前 requirement / change ID
+- 当前 task ID
+- 当前 task status
+- 当前 active phase
+- 当前 ready tasks
+- 当前 review gates（spec / code）
+- 已完成证据
+- 阻塞点
+- 下一步唯一动作
+
+## Recovery Rule
+
+恢复时只回答 3 件事：
+
+1. 现在停在哪
+2. 为什么停在这
+3. 下一步必须先做什么
+
+如果这三件事不能只靠规范产物和最新 checkpoint 回答，就先做 context reset，不准继续依赖聊天记忆。
+
+## Runtime Layout
+
+运行态证据按任务落在：
+
+- `devflow/changes/<change-key>/execution/tasks/<task-id>/checkpoint.json`
+- `devflow/changes/<change-key>/execution/tasks/<task-id>/events.jsonl`（仅 debug / failed 默认保留）
+- `planning/task-manifest.json` 里的 `tasks[*].reviews`
+
+## Required Event Spine
+
+一个健康任务最少要看见这些事件：
+
+1. `context_ready`
+2. `red_failed`
+3. `red_reason_verified`
+4. `green_passed`
+5. `refactor_done` 或 `refactor_not_needed`
+6. `refactor_green`
+7. `spec_review_pass`
+8. `code_review_pass`
+
+如果 `events.jsonl` 没开启，至少仍要有最新 `checkpoint.json` 和 manifest review verdict。
+
+## Checkpoint TDD Fields
+
+最新 checkpoint 至少能回答：
+
+- `red.command`
+- `red.exitStatus`
+- `red.expectedFailure`
+- `green.command`
+- `green.exitStatus`
+- `refactor.status`
+- `review.spec.status`
+- `review.code.status`
+
+如果跳过 TDD，必须有 `tddException`，并写清替代验证。没有这些字段时，恢复执行先补证据，不准直接继续实现。
+
+## Bug Rule
+
+- 先复现
+- 再收证据
+- 再下根因判断
+- 最后改代码
+
+## Local Recovery Ladder
+
+1. 先重试当前命令或当前 task，而不是重跑整条 requirement
+2. 两次失败后回看证据链和 task context
+3. 三次失败后默认怀疑上游合同：根因漂移回 `cc-investigate`，范围 / 设计漂移回 `cc-plan`
+
+## Subagent Rule
+
+给 subagent 的上下文至少包含：
+
+- 当前任务全文
+- 当前进度与最近 checkpoint
+- 已满足 / 未满足的依赖
+- 必读文件
+- 验收标准
+- 验证命令
+- 不做项 / 边界

package/.claude/skills/cc-do/references/parallel-dispatch.md

@@ -0,0 +1,80 @@
+# Parallel Dispatch Guide
+
+## Golden Law
+
+并行的是独立事实，不是因果链。
+
+如果一个任务的输出会改变另一个任务的实现选择，那它们就不是并行任务，而是顺序任务。
+
+## Can Run In Parallel
+
+只有全部满足，才算可并行：
+
+1. 两个任务都在当前 active phase
+2. `dependsOn` 已满足，且互不依赖
+3. `touches` / `files` 没有交集
+4. 不共享同一个可变资源，例如同一 schema、同一公共接口、同一全局状态
+5. 验证命令可以各自独立运行
+6. 每个任务都有完整上下文包，不需要靠别人的临场解释补脑
+
+## Must Run Sequentially
+
+命中任一条，就必须串行：
+
+1. 一个任务依赖另一个任务的输出
+2. 两个任务会改同一个文件或同一抽象边界
+3. 上游任务在定义契约，下游任务在消费契约
+4. 一个任务先改 schema / API，另一个任务基于它写实现
+5. 你还不能清楚说出每个任务各自的验收标准
+6. 你打算让第二个 subagent 先看第一个 subagent 的结果再决定怎么写
+
+## Dispatch Packet
+
+每个 subagent 在开工前必须拿到：
+
+- 当前任务全文
+- 当前 requirement 摘要
+- 当前进度摘要
+- 当前任务依赖状态
+- 必读文件列表
+- 允许修改的触点
+- 验收标准
+- 可信命令
+- 非目标
+
+少任何一项，都不是“已准备好的并行任务”。
+
+## Scheduling Heuristics
+
+优先级从高到低：
+
+1. 先选当前 active phase 的 ready tasks
+2. 在 ready tasks 里优先选 `touches` 不重叠的任务
+3. 在不重叠任务里优先选验证面最小的任务
+4. 如果仍然不确定，退回串行
+
+## Good Example
+
+- `T010 [TEST]` 为支付折扣补失败测试，触点只在 `tests/payment-discount.test.ts`
+- `T011 [TEST]` 为通知重试补失败测试，触点只在 `tests/notify-retry.test.ts`
+- `T012 [IMPL]` 修支付折扣实现，`dependsOn:T010`
+- `T013 [IMPL]` 修通知重试实现，`dependsOn:T011`
+
+可以并行的是 `T010` 和 `T011`，也可以在它们各自通过后并行 `T012` 和 `T013`。
+
+## Bad Example
+
+- `T020` 重命名鉴权中间件导出
+- `T021` 基于新导出接入路由
+
+这不是并行，它们是显式因果链。
+
+## Taste Check
+
+并行调度前问自己三件事：
+
+1. 如果 A 任务晚 30 分钟完成，B 还能独立写完吗？
+2. 如果两个任务同时改完，我能不用人工大合并就直接集成吗？
+3. 如果把两个任务交给两个完全不共享记忆的 subagent，他们还能各自成功吗？
+
+有一个答案是否，就别并行。

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

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 组装当前任务的执行上下文，并记录 context_ready 事件
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage:
+  build-task-context.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" || ! -d "$REQ_DIR" ]]; then
+  usage
+  exit 1
+fi
+
+CHANGE_DIR="$(req_do_resolve_change_dir "$REQ_DIR")"
+manifest="$(req_do_manifest_path "$CHANGE_DIR")"
+design_file="$(req_do_contract_path "$CHANGE_DIR")"
+tasks_file="$(req_do_tasks_path "$CHANGE_DIR")"
+change_meta="$(req_do_change_meta_path "$CHANGE_DIR")"
+resume_index="$(req_do_resume_index_path "$CHANGE_DIR")"
+
+if [[ ! -f "$manifest" ]]; then
+  echo "Missing $manifest" >&2
+  exit 1
+fi
+
+task_json="$(jq -c --arg task "$TASK_ID" '.tasks[] | select(.id == $task)' "$manifest")"
+if [[ -z "$task_json" ]]; then
+  echo "$TASK_ID not found in manifest" >&2
+  exit 1
+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
+    echo "- None"
+  else
+    printf '%s\n' "$value" | sed '/^$/d' | awk '!seen[$0]++' | sed 's/^/- /'
+  fi
+}
+
+task_title="$(jq -r '.title // ""' <<<"$task_json")"
+task_phase="$(jq -r '.phase // 0' <<<"$task_json")"
+task_status="$(jq -r '.status // "pending"' <<<"$task_json")"
+task_parallel="$(jq -r '.parallel // false' <<<"$task_json")"
+task_depends="$(jq -r '(.dependsOn // [])[]?' <<<"$task_json")"
+task_touches="$(jq -r '((.touches // .files // [])[]?)' <<<"$task_json")"
+task_acceptance="$(jq -r '(.acceptance // [])[]?' <<<"$task_json")"
+task_verification="$(jq -r '(.verification // [])[]?' <<<"$task_json")"
+task_read_files="$(jq -r '(.context.readFiles // [])[]?' <<<"$task_json")"
+task_commands="$(jq -r '(.context.commands // [])[]?' <<<"$task_json")"
+task_notes="$(jq -r '(.context.notes // [])[]?' <<<"$task_json")"
+completed_tasks="$(jq -r '
+  .tasks[]
+  | select((.status // "pending") == "passed" or (.status // "pending") == "completed" or (.status // "pending") == "done" or (.status // "pending") == "verified")
+  | .id
+' "$manifest")"
+ready_tasks="$(echo "$ready_json" | jq -r '.readyTasks[]?.id')"
+running_tasks="$(echo "$ready_json" | jq -r '.runningTasks[]?.id')"
+active_phase="$(echo "$ready_json" | jq -r '.activePhase // "unknown"')"
+primary_capability="$(jq -r '.spec.primaryCapability // empty' "$manifest" 2>/dev/null || true)"
+secondary_capabilities="$(jq -r '(.spec.secondaryCapabilities // [])[]?' "$manifest" 2>/dev/null || true)"
+spec_files="$(jq -r '(.spec.specFiles // [])[]?' "$manifest" 2>/dev/null || true)"
+expected_delta="$(jq -r '(.spec.expectedDelta // [])[]?' "$manifest" 2>/dev/null || true)"
+sync_status="$(jq -r '.spec.syncStatus // "unknown"' "$manifest" 2>/dev/null || true)"
+
+{
+  echo "# Task Context"
+  echo
+  echo "- Change: $change_id"
+  echo "- Task: $TASK_ID"
+  echo "- Title: $task_title"
+  echo "- Phase: $task_phase"
+  echo "- Status: $task_status"
+  echo "- Parallel eligible: $task_parallel"
+  echo "- Active phase: $active_phase"
+  echo
+  echo "## Current Progress"
+  echo
+  echo "### Completed Tasks"
+  list_or_none "$completed_tasks"
+  echo
+  echo "### Running Tasks"
+  list_or_none "$running_tasks"
+  echo
+  echo "### Ready Tasks"
+  list_or_none "$ready_tasks"
+  echo
+  echo "## Dependencies"
+  echo
+  list_or_none "$task_depends"
+  echo
+  echo "## Touches"
+  echo
+  list_or_none "$task_touches"
+  echo
+  echo "## Acceptance"
+  echo
+  list_or_none "$task_acceptance"
+  echo
+  echo "## Verification"
+  echo
+  list_or_none "$task_verification"
+  echo
+  echo "## Read First"
+  echo
+  list_or_none "$task_read_files"
+  echo
+  echo "## Commands To Trust"
+  echo
+  list_or_none "$task_commands"
+  echo
+  echo "## Spec Contract"
+  echo
+  echo "- Primary capability: ${primary_capability:-none}"
+  echo "- Spec sync status: ${sync_status:-unknown}"
+  echo
+  echo "### Secondary Capabilities"
+  list_or_none "$secondary_capabilities"
+  echo
+  echo "### Capability Specs"
+  list_or_none "$spec_files"
+  echo
+  echo "### Expected Spec Delta"
+  list_or_none "$expected_delta"
+  echo
+  echo "## Task Notes"
+  echo
+  list_or_none "$task_notes"
+  echo
+  echo "## Canonical Planning Files"
+  echo
+  [[ -f "$design_file" ]] && echo "- ${design_file#$CHANGE_DIR/}"
+  [[ -f "$tasks_file" ]] && echo "- ${tasks_file#$CHANGE_DIR/}"
+  [[ -f "$change_meta" ]] && echo "- ${change_meta#$CHANGE_DIR/}"
+  echo "- planning/task-manifest.json"
+  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 [[ -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/cc-do-common.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+
+# ------------------------------------------------------------
+# cc-do: canonical devflow layout 解析
+# ------------------------------------------------------------
+
+req_do_resolve_change_dir() {
+  local input="$1"
+  local normalized
+
+  normalized="${input%/}"
+  case "$(basename "$normalized")" in
+    planning|execution|review|handoff|meta)
+      dirname "$normalized"
+      ;;
+    *)
+      printf '%s\n' "$normalized"
+      ;;
+  esac
+}
+
+req_do_planning_dir() {
+  printf '%s/planning\n' "$(req_do_resolve_change_dir "$1")"
+}
+
+req_do_execution_dir() {
+  printf '%s/execution\n' "$(req_do_resolve_change_dir "$1")"
+}
+
+req_do_review_dir() {
+  printf '%s/review\n' "$(req_do_resolve_change_dir "$1")"
+}
+
+req_do_handoff_dir() {
+  printf '%s/handoff\n' "$(req_do_resolve_change_dir "$1")"
+}
+
+req_do_manifest_path() {
+  printf '%s/task-manifest.json\n' "$(req_do_planning_dir "$1")"
+}
+
+req_do_tasks_path() {
+  printf '%s/tasks.md\n' "$(req_do_planning_dir "$1")"
+}
+
+req_do_change_meta_path() {
+  printf '%s/change-meta.json\n' "$(req_do_resolve_change_dir "$1")"
+}
+
+req_do_contract_path() {
+  local planning_dir
+  local design_file
+  local analysis_file
+
+  planning_dir="$(req_do_planning_dir "$1")"
+  design_file="$planning_dir/design.md"
+  analysis_file="$planning_dir/analysis.md"
+
+  if [[ -f "$analysis_file" && ! -f "$design_file" ]]; then
+    printf '%s\n' "$analysis_file"
+    return 0
+  fi
+
+  printf '%s\n' "$design_file"
+}
+
+req_do_report_card_path() {
+  printf '%s/report-card.json\n' "$(req_do_review_dir "$1")"
+}
+
+req_do_resume_index_path() {
+  printf '%s/resume-index.md\n' "$(req_do_handoff_dir "$1")"
+}
+
+req_do_task_runtime_dir() {
+  local change_dir="$1"
+  local task_id="$2"
+  printf '%s/tasks/%s\n' "$(req_do_execution_dir "$change_dir")" "$task_id"
+}