cc-devflow 4.2.0 → 4.4.1

package/.claude/skills/cc-plan/assets/TINY_DESIGN_TEMPLATE.md

@@ -0,0 +1,79 @@
+# DESIGN
+
+## Document Meta
+
+- Requirement version:
+- Design version:
+- CC-Plan skill version:
+- Requirement ID:
+- Design mode: `tiny-design`
+- Why this stays `tiny-design`:
+- Approval status: `draft` | `in-review` | `approved`
+- Source roadmap item:
+- Source roadmap version:
+- Primary capability:
+- Secondary capabilities:
+
+## Source Handoff
+
+- Why now:
+- Capability gap:
+- Expected spec delta:
+- Inherited success signal:
+- Inherited kill signal:
+- Inherited non-goals:
+- Upstream evidence:
+
+## Capability Handoff
+
+- Canonical capability spec:
+- Current truth to preserve:
+- Current gaps:
+- Spec sync target:
+
+## Frozen Design Card
+
+- Change:
+- Keep out:
+- Touched files:
+- Contract changes:
+- Invariant impact:
+- Gap changes:
+- Key decisions that `cc-do` must not re-decide:
+- Upgrade trigger to `full-design`:
+
+## Validation
+
+- First failing test:
+- Green implementation check:
+- Refactor checkpoint:
+- TDD exceptions:
+- Primary check:
+- Secondary checks:
+- Evidence to collect:
+
+## Main Risk
+
+- Risk:
+- Mitigation:
+
+## Review Gate
+
+- Placeholder scan:
+- Consistency scan:
+- Scope scan:
+- Ambiguity scan:
+- Feasibility scan:
+- Test-first readiness:
+- Final recommendation:
+
+## Approval
+
+- User approval status:
+- Deferred questions:
+
+## First-Read Test
+
+- 一眼能看出这次为什么够小
+- 一眼能看出什么情况会逼它升级成 `full-design`
+- `cc-do` 看完不会继续追问“那接口 / 边界到底怎么算”

package/.claude/skills/cc-plan/references/planning-contract.md

@@ -0,0 +1,82 @@
+# Planning Contract
+
+## Hard Rules
+
+1. `cc-plan` 默认只产出 4 个文件：`planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json`。
+2. clarification / brainstorm / review 结论必须并入 `planning/design.md`，不能再默认拆独立文档。
+3. 执行 handoff 必须写进 `planning/tasks.md` 顶部，不能依赖单独的 `context-package.md`。
+4. `planning/task-manifest.json` 必须和 `planning/tasks.md` 同步，且能告诉 `cc-do` 当前任务是谁。
+5. `planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json` 必须记录来源版本链。
+6. 计划里出现 placeholder 词，就说明还没想清楚。
+7. 一次只推进一个澄清问题，不允许问题轰炸。
+8. 推荐方案没获批前，不允许继续拆执行任务。
+9. `planning/design.md` 通过 review gate 前，不允许宣称计划完成。
+10. 如果来自 `roadmap`，planning 不得悄悄丢掉 source constraints / non-goals / success signal。
+11. 每个计划必须先找 existing leverage，再决定新增实现；重复已有能力属于 planning 失败。
+12. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
+13. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
+14. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链或 TDD exception，不允许交给 `cc-do`。
+15. 新 change 目录必须是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`，不能用小写 `req-*` / `bug-*` 或纯描述目录。
+
+## Design Modes
+
+- `tiny-design`：超小需求的冻结设计卡片，不是跳过设计。
+- `full-design`：涉及跨模块、复杂数据流、迁移或高风险约束的完整设计。
+
+默认优先 `tiny-design`，但一旦需要解释复杂边界，就升级到 `full-design`。
+
+## Placeholder Ban
+
+- TODO later
+- implement later
+- handle edge cases
+- write tests later
+- similar to task N
+- TBD
+- 待定
+- 之后再补
+- 后面再想
+
+## Task Fields
+
+每个任务至少写清：
+
+- 目标
+- TDD phase：`red` / `green` / `refactor` / `exception`
+- 涉及文件
+- 验证方式
+- 完成证据
+
+行为变更任务必须先有 `[TEST]` 红灯任务，再有 `[IMPL]` 绿灯任务，最后有 `[REFACTOR]` 或明确 refactor checkpoint。纯文档、纯配置、纯生成文件、throwaway prototype 可以例外，但必须写明原因、风险和替代验证。
+
+## Review Gate
+
+`planning/design.md` 至少完成：
+
+1. Placeholder scan
+2. Consistency scan
+3. Scope scan
+4. Ambiguity scan
+5. Feasibility scan
+6. Source alignment
+7. Existing leverage map
+8. Scope / complexity challenge
+9. Test diagram and failure modes
+10. NOT in scope
+11. Test-first readiness
+12. Final recommendation
+
+如有 UI scope，再补 design review 结论。
+如有 developer-facing scope，再补 DX review 结论。
+
+## Decision Log
+
+每个非平凡决策至少记录：
+
+- decision
+- classification：`mechanical` / `taste` / `user challenge`
+- principle：completeness / pragmatic / DRY / explicit / action
+- rationale
+- rejected alternative
+
+机械选择可以自动落盘。taste decision 和 user challenge 必须在最终 gate 里显式出现。

package/.claude/skills/cc-plan/scripts/bump-skill-version.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# cc-plan skill semver helper
+# - bump SKILL.md frontmatter version
+# - prepend CHANGELOG.md entry
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage:
+  bump-skill-version.sh --type patch|minor|major --message "change summary" \
+    [--skill-file SKILL.md] [--changelog CHANGELOG.md] [--date YYYY-MM-DD]
+EOF
+}
+
+TYPE=""
+MESSAGE=""
+SKILL_FILE="SKILL.md"
+CHANGELOG_FILE="CHANGELOG.md"
+DATE="$(date +%Y-%m-%d)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --type) TYPE="$2"; shift 2 ;;
+    --message) MESSAGE="$2"; shift 2 ;;
+    --skill-file) SKILL_FILE="$2"; shift 2 ;;
+    --changelog) CHANGELOG_FILE="$2"; shift 2 ;;
+    --date) DATE="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$TYPE" || -z "$MESSAGE" ]]; then
+  usage
+  exit 1
+fi
+
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "Skill file not found: $SKILL_FILE" >&2
+  exit 1
+fi
+
+CURRENT_VERSION="$(awk '/^version: / { print $2; exit }' "$SKILL_FILE")"
+
+if [[ -z "$CURRENT_VERSION" ]]; then
+  echo "No version field found in $SKILL_FILE" >&2
+  exit 1
+fi
+
+IFS='.' read -r MAJOR MINOR PATCH <<<"$CURRENT_VERSION"
+
+case "$TYPE" in
+  patch)
+    PATCH=$((PATCH + 1))
+    ;;
+  minor)
+    MINOR=$((MINOR + 1))
+    PATCH=0
+    ;;
+  major)
+    MAJOR=$((MAJOR + 1))
+    MINOR=0
+    PATCH=0
+    ;;
+  *)
+    echo "Unsupported bump type: $TYPE" >&2
+    exit 1
+    ;;
+esac
+
+NEXT_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+
+TMP_SKILL="$(mktemp)"
+awk -v next_version="$NEXT_VERSION" '
+  BEGIN { done = 0 }
+  {
+    if (!done && $0 ~ /^version: /) {
+      print "version: " next_version
+      done = 1
+      next
+    }
+    print
+  }
+' "$SKILL_FILE" > "$TMP_SKILL"
+mv "$TMP_SKILL" "$SKILL_FILE"
+
+if [[ ! -f "$CHANGELOG_FILE" ]]; then
+  printf '# CC-Plan Skill Changelog\n\n' > "$CHANGELOG_FILE"
+fi
+
+TMP_CHANGELOG="$(mktemp)"
+{
+  sed -n '1p' "$CHANGELOG_FILE"
+  printf '\n## v%s - %s\n\n- %s\n' "$NEXT_VERSION" "$DATE" "$MESSAGE"
+  sed -n '2,$p' "$CHANGELOG_FILE"
+} > "$TMP_CHANGELOG"
+mv "$TMP_CHANGELOG" "$CHANGELOG_FILE"
+
+echo "Bumped cc-plan skill: ${CURRENT_VERSION} -> ${NEXT_VERSION}"

package/.claude/skills/cc-plan/scripts/parse-task-dependencies.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+'use strict';
+
+// ------------------------------------------------------------
+// 解析 tasks.md 里的 phase / [P] / 文件触点
+// ------------------------------------------------------------
+
+const fs = require('fs');
+
+const phaseRegex = /^##\s+Phase\s+(\d+):\s*(.+)$/;
+const taskRegex = /^-\s+\[([ xX])\]\s+(?:\*\*)?(T\d+)(?:\*\*)?\s+(.*)$/;
+const fileRegex = /`([^`]+)`/g;
+const dependsOnRegex = /\(dependsOn:([^)]+)\)/;
+
+function parse(content) {
+  const lines = content.replace(/\r\n?/g, '\n').split('\n');
+  const tasks = [];
+  let phase = 0;
+
+  for (const line of lines) {
+    const phaseMatch = line.match(phaseRegex);
+    if (phaseMatch) {
+      phase = Number(phaseMatch[1]);
+      continue;
+    }
+
+    const taskMatch = line.match(taskRegex);
+    if (!taskMatch) continue;
+
+    const [, box, id, rest] = taskMatch;
+    const files = [...rest.matchAll(fileRegex)].map((m) => m[1]);
+    const dependsOnMatch = rest.match(dependsOnRegex);
+    const dependsOnValue = dependsOnMatch ? dependsOnMatch[1].trim() : '';
+    const dependsOn = !dependsOnValue || dependsOnValue === 'none'
+      ? []
+      : dependsOnValue.split(',').map((item) => item.trim()).filter(Boolean);
+    tasks.push({
+      id,
+      phase,
+      completed: box.toLowerCase() === 'x',
+      parallel: rest.includes('[P]'),
+      dependsOn,
+      files,
+      title: rest
+        .replace(/\[P\]/g, '')
+        .replace(dependsOnRegex, '')
+        .replace(fileRegex, '')
+        .replace(/\*\*/g, '')
+        .trim()
+    });
+  }
+
+  return tasks;
+}
+
+function main() {
+  const file = process.argv[2];
+  if (!file) {
+    console.error('Usage: parse-task-dependencies.js tasks.md');
+    process.exit(1);
+  }
+
+  const tasks = parse(fs.readFileSync(file, 'utf8'));
+  const completedIds = new Set(tasks.filter((t) => t.completed).map((t) => t.id));
+  const runnableTasks = tasks.filter((t) => !t.completed && t.dependsOn.every((dep) => completedIds.has(dep)));
+  const nextPhase = runnableTasks.reduce((min, t) => Math.min(min, t.phase), Infinity);
+  const nextTasks = Number.isFinite(nextPhase) ? runnableTasks.filter((t) => t.phase === nextPhase) : [];
+
+  process.stdout.write(JSON.stringify({ tasks, nextTasks }, null, 2));
+}
+
+if (require.main === module) {
+  main();
+}

package/.claude/skills/cc-plan/scripts/validate-scope.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# 检查计划文档是否越界或仍有 placeholder
+# ------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Usage: validate-scope.sh --source FILE [--source FILE...]
+EOF
+}
+
+sources=()
+bad_terms=(
+  "TODO later"
+  "implement later"
+  "handle edge cases"
+  "write tests later"
+  "{{"
+  "[NEEDS CLARIFICATION"
+  "TBD"
+  "待定"
+  "之后再补"
+  "后面再想"
+)
+
+required_markers=(
+  "Requirement version:"
+  "CC-Plan skill version:"
+)
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --source) sources+=("$2"); shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ ${#sources[@]} -eq 0 ]]; then
+  usage
+  exit 1
+fi
+
+fail=0
+for file in "${sources[@]}"; do
+  [[ -f "$file" ]] || continue
+  for term in "${bad_terms[@]}"; do
+    if rg -n --fixed-strings "$term" "$file" >/dev/null 2>&1; then
+      echo "[FAIL] $file contains: $term"
+      fail=1
+    fi
+  done
+  if rg -n '^\|  \|  \|  \|$' "$file" >/dev/null 2>&1; then
+    echo "[FAIL] $file contains an empty markdown table row"
+    fail=1
+  fi
+  if rg -n '^[[:space:]]*(- )?[A-Za-z][A-Za-z /_-]*:\s*$' "$file" >/dev/null 2>&1; then
+    echo "[FAIL] $file contains an empty field bullet"
+    fail=1
+  fi
+  if [[ "$file" != *"TASK_MANIFEST_TEMPLATE.json" ]]; then
+    for marker in "${required_markers[@]}"; do
+      if ! rg -n --fixed-strings "$marker" "$file" >/dev/null 2>&1; then
+        echo "[FAIL] $file is missing marker: $marker"
+        fail=1
+      fi
+    done
+  fi
+done
+
+if [[ "$fail" -eq 1 ]]; then
+  exit 1
+fi
+
+echo "Scope validation passed"

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

@@ -0,0 +1,114 @@
+# Roadmap Skill Changelog
+
+## v4.3.1 - 2026-04-19
+
+- refactor `scripts/roadmap-tracking.js` into focused schema / markdown / store helpers so the CLI stops carrying parsing, rendering, upgrade, and persistence in one 1000-line file
+- route `locate-roadmap-item.sh` through the shared tracking query path instead of maintaining a second inline Node formatter
+- preserve existing `backlog` fields when auto-upgrading legacy v1 tracking JSON so shared lookup and render paths stay behaviorally correct
+
+## v4.3.0 - 2026-04-19
+
+- expand `devflow/roadmap-tracking.json` from implementation-only tracking into the shared truth source for `ROADMAP.md` and `BACKLOG.md`
+- teach `roadmap-tracking.js render` and `sync-roadmap-progress.sh` to regenerate both files from the same sidecar so roadmap status and backlog handoff can no longer drift apart
+- upgrade locator, templates, docs, examples, and tests so backlog queue / ready / parked data are read from the sidecar before falling back to markdown text
+
+Migration note:
+
+- existing v4.2.x `roadmap-tracking.json` files are auto-upgraded on first render or sync run
+- if you maintain backlog handoff by hand, move the durable fields into `roadmap-tracking.json` and rerender instead of treating `BACKLOG.md` as the writable source
+- `scripts/roadmap-tracking.js render` now requires both `--roadmap` and `--backlog`
+
+## v4.2.1 - 2026-04-19
+
+- teach `locate-roadmap-item.sh` to resolve `RM-*` and `REQ-*` through `devflow/roadmap-tracking.json` before falling back to markdown grep
+- realign bundled examples with the capability-aware backlog contract so templates, examples, and helper checks no longer drift apart
+- tighten example validation to require the new backlog queue columns and `Ready For Req-Plan` handoff fields
+
+## v4.2.0 - 2026-04-19
+
+- add `devflow/roadmap-tracking.json` as the structured truth source for `Implementation Tracking`
+- replace fragile column-position markdown rewrites with JSON-first sync plus markdown re-rendering
+- ship a reusable `render` path so manual edits to the tracking sidecar can be pushed back into `ROADMAP.md`
+
+Migration note:
+
+- keep `devflow/ROADMAP.md` as the human-facing roadmap, but let helper automation update `devflow/roadmap-tracking.json`
+- the first sync run bootstraps `roadmap-tracking.json` from an existing `Implementation Tracking` table, then rewrites the section in the new generated shape
+- if you were scripting direct table edits, switch to `scripts/sync-roadmap-progress.sh` or edit `roadmap-tracking.json` and rerender
+
+## v4.1.0 - 2026-04-19
+
+- teach `cc-roadmap` to anchor roadmap items to capability specs instead of leaving future work as requirement-shaped fragments
+- upgrade roadmap and backlog templates with `Primary Capability`, `Secondary Capabilities`, `Capability Gap`, and `Expected Spec Delta`
+- extend `sync-roadmap-progress.sh` so roadmap tracking can update capability/spec columns together with status progress
+
+Migration note:
+
+- roadmap items should now point to at least one capability, with one explicit primary capability
+- backlog handoffs should carry expected spec delta into `cc-plan`
+
+## v4.0.0 - 2026-04-18
+
+- restore `cc-roadmap` durable outputs to `devflow/ROADMAP.md` and `devflow/BACKLOG.md`, matching the repository contract and keeping roadmap artifacts under `devflow/`
+- update bundled helper scripts to prefer `devflow/ROADMAP.md` and `devflow/BACKLOG.md`, while still falling back to the recent repo-root paths and the older `devflow/roadmap/*` paths
+- realign skill docs, public guides, and registry/bootstrap tests with the restored canonical paths
+
+Migration note:
+
+- new roadmap runs should write `devflow/ROADMAP.md` and `devflow/BACKLOG.md`
+- if you temporarily have repo-root `ROADMAP.md` / `BACKLOG.md` from v3.0.0, move them back under `devflow/`
+- helper scripts now resolve files in this order: `devflow/*.md` -> repo-root `*.md` -> legacy `devflow/roadmap/*.md`
+
+## v3.0.0 - 2026-04-17
+
+- change `cc-roadmap` durable outputs to repo-root `ROADMAP.md` and `BACKLOG.md`, aligning the skill contract with README, examples, and live usage
+- require roadmap output to include an explicit `RM Dependency Graph` plus `Parallel Waves`, so serial blockers and concurrent work are visible
+- upgrade backlog handoff fields to record `Depends On` and `Parallel With`
+- update bundled helper scripts to prefer repo-root files and fall back to legacy `devflow/roadmap/*` files when present
+
+Migration note:
+
+- new roadmap runs should write repo-root `ROADMAP.md` and `BACKLOG.md`
+- helper scripts still read legacy `devflow/roadmap/*` files as fallback, but the canonical path is now the repo root
+- if you maintain automation that parses the `Implementation Tracking` table, account for the new `Depends On` column before `Status`
+
+## v2.2.0 - 2026-04-17
+
+- convert public frontmatter from loose prose into structured harness contract fields: `triggers`, `reads`, `writes`, `entry_gate`, `exit_criteria`, `reroutes`, `recovery_modes`, `tool_budget`
+- add `Harness Contract` to `SKILL.md` and `Visible State Machine` to `PLAYBOOK.md`
+- make roadmap explicitly skill-first: strategy stays in skill text and artifacts instead of hidden harness behavior
+
+Migration note:
+
+- any downstream tooling that only read `name` and `description` can keep working, but new registry consumers should prefer the structured contract fields
+- roadmap users do not need to change existing `ROADMAP.md` / `BACKLOG.md` files; the new contract only makes the operating rules explicit
+
+## v2.1.0 - 2026-04-15
+
+- 增强 frontmatter `description`，补充中英文触发词，提升命中率。
+- 新增 `Quick Start` 和 `Route Selection Rule`，把首次路线判断前置成更易执行的入口。
+- 新增 `Recommendation Test`，要求推荐必须同时说明“为什么选它”和“为什么不先做另外两条”。
+- 升级 `ROADMAP_TEMPLATE.md`，增加 `Recommended Route` 区块。
+- 升级 `BACKLOG_TEMPLATE.md`，让 ready 项显式写清“为什么现在 ready”。
+
+Migration note:
+
+- 旧版 `ROADMAP.md` / `BACKLOG.md` 可以继续使用；建议在下次重跑 roadmap 时补齐 `Recommended Route` 和 ready rationale，以减少后续 `cc-plan` 阶段的解释成本。
+
+## v2.0.0 - 2026-04-10
+
+- 增加 `version` frontmatter，并定义 roadmap skill 的 semver 规则。
+- 强化 `Context Sweep`，要求先读取现有 roadmap、文档、最近提交、forcing functions，再开始追问。
+- 增加 `Approval Gates` 与 `Review Loop`，避免没有证据、没有退出信号的伪路线图。
+- 升级 `ROADMAP_TEMPLATE.md`，加入 metadata、context snapshot、evidence ledger、route options、dependencies、kill signal、版本差异记录。
+- 升级 `BACKLOG_TEMPLATE.md`，让事项带上 evidence、dependency、next decision、ready 状态。
+- 新增 `scripts/bump-skill-version.sh`，用于递增 skill 版本并同步 changelog。
+
+Migration note:
+
+- 旧版 `ROADMAP.md` / `BACKLOG.md` 仍可继续使用，但建议补齐新模板里的 metadata、evidence、dependencies、kill signal、ready 字段。
+- `Implementation Tracking` 表保持兼容，`scripts/sync-roadmap-progress.sh` 无需修改。
+
+## v1.0.0 - 2026-04-10
+
+- 初始版 roadmap skill，提供基础路线图和 backlog 产物。

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

@@ -0,0 +1,136 @@
+# Roadmap Playbook
+
+## Visible State Machine
+
+`roadmap` is the only strategy stage.
+
+- Enter from: project kickoff, backlog drift, or strategy reset.
+- Stay in: `roadmap` while direction is still being argued or evidence is incomplete.
+- Exit to: `cc-plan` once one approved roadmap item becomes the next concrete requirement.
+
+## Core Rules
+
+1. 先读上下文，再问现实，不先写愿景。
+2. 一次只推进一个关键未知点。
+3. 只定 1-3 个阶段，不写愿望清单。
+4. 通过 `roadmap` 只能产出方向，不能偷拆实现任务。
+5. 没有证据时写 assumption，不准冒充事实。
+6. 每次都必须明确推荐一条路线，不准只列选项不下判断。
+
+## Local Kit
+
+- 生成骨架时用 `assets/ROADMAP_TEMPLATE.md` 和 `assets/BACKLOG_TEMPLATE.md`
+- 需要结构化 tracking 时用 `assets/TRACKING_TEMPLATE.json`
+- 需要追问脚本时看 `references/roadmap-dialogue.md`
+- 需要定位 / 回写条目时用 `scripts/locate-roadmap-item.sh` 和 `scripts/sync-roadmap-progress.sh`
+- `scripts/locate-roadmap-item.sh` 先读 `roadmap-tracking.json`，再回落到 `ROADMAP.md` / `BACKLOG.md`，避免定位依赖 markdown 列位或文案漂移
+- 只想把 sidecar 重渲染回 `ROADMAP.md` / `BACKLOG.md` 时，直接调用 `scripts/roadmap-tracking.js render`
+- `scripts/sync-roadmap-progress.sh` 会把 `roadmap-tracking.json` 当真相源，再回渲染 `ROADMAP.md` 和 `BACKLOG.md`
+- 变更版本时同步 `CHANGELOG.md`，必要时用 `scripts/bump-skill-version.sh`
+
+## Context Sweep
+
+进入 roadmap 对话前，至少摸清：
+
+1. 现有 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+2. `CLAUDE.md`、`README*`、`TODOS.md`
+3. 最近相关 docs / specs / plans
+4. 最近相关提交、当前工作树状态、正在推进的 requirement
+5. 现实 forcing functions：deadline、distribution、资源、依赖、当前卡点
+
+先把这些材料压成 `Context Snapshot`，再追问用户。
+
+## Force Reality First
+
+至少逼清这 5 件事：
+
+1. 这个项目真正服务谁
+2. 用户今天用什么笨办法解决
+3. 为什么他们现在就会想要这个东西
+4. 最窄但最有穿透力的第一阶段是什么
+5. 未来 6-12 个月产品会自然长成什么样
+
+同时补齐这 4 件落地信息：
+
+6. 当前最强证据是什么
+7. deadline / capacity / dependency / distribution 约束是什么
+8. 当前最大的 adoption / trust / delivery 卡点是什么
+9. 成功与失败的判断信号是什么
+
+## Route Shapes
+
+- `wedge-first`: 用一个极窄切口先打穿真实需求
+- `platform-first`: 先搭通后续阶段复用的关键底座
+- `rescue-first`: 先解决当前最大的 adoption / trust / delivery 卡点
+
+推荐时必须回答：为什么这条主线比其他两条更值得先打。
+
+## Recommendation Test
+
+写完推荐后，快速自检：
+
+1. 如果删掉路线名，别人还能从理由里猜出为什么是这条吗？
+2. 有没有明确说“不先做另外两条”的原因？
+3. Stage 1 的 win signal 能不能在 1-2 个周期内看到？
+4. 如果 Stage 1 输了，kill signal 是不是具体到可以止损？
+
+## Stage Contract
+
+每个阶段至少要有：
+
+1. `Goal`
+2. `Why now`
+3. `Dependencies`
+4. `Exit signal`
+5. `Kill signal`
+6. `Non-goals`
+7. 可以自然长成下一轮 `cc-plan` 的候选事项
+
+## Dependency Contract
+
+1. `Depends On` 只写硬阻塞，不写“最好先做”的软顺序。
+2. 至少画出一份 `RM Dependency Graph`，让串行主链和并行分支一眼可见。
+3. 至少列出一组 `Parallel waves`，说明哪些事项可共享同一前置后并发推进。
+4. 如果图里出现环，说明阶段切分错了，先重切，不要硬解释。
+
+## Output Contract
+
+`devflow/ROADMAP.md`
+- version / skill version / context snapshot / evidence ledger
+- 1-3 个阶段
+- 每阶段目标
+- 每阶段存在原因
+- 每阶段 dependencies
+- 每阶段 exit signal
+- 每阶段 kill signal
+- 非目标
+- `RM Dependency Graph`
+- `Parallel waves`
+- `Implementation Tracking` 由 `devflow/roadmap-tracking.json` 渲染，避免手改 markdown 表格列位
+
+`devflow/BACKLOG.md`
+- 只保留会真的进入下一轮 `cc-plan` 的事项
+- 每项注明来源阶段、优先级、证据、`Depends On`、`Parallel With`、当前未知点、下一决策、是否 ready
+- `Backlog Meta`、`Queue`、`Dependency Handoff`、`Ready For Req-Plan`、`Parked` 可由 `devflow/roadmap-tracking.json` 回渲染，避免 roadmap truth 和 backlog handoff 分叉
+
+## Review Loop
+
+交付前至少扫一遍：
+
+1. 有没有 placeholder
+2. 阶段之间是否有因果链
+3. 阶段目标是否真能被当前资源支撑
+4. `RM Dependency Graph` 是否只有硬依赖、没有环
+5. ready 项是否真能进入 `cc-plan`
+6. 本次版本相比上一版到底改了什么
+
+## Versioning
+
+- `patch`: 文案澄清、模板说明、小修补
+- `minor`: 上下文收集、评审、字段增强，且不破坏既有 tracking 习惯
+- `major`: 核心输出契约变化，需要 migration note
+
+## Exit Rule
+
+只有当第一批 requirement 能从阶段主线自然长出来时，`roadmap` 才算完成。
+如果用户看完还会问“所以现在到底先做什么”，说明 roadmap 还没写好。