cc-devflow 4.3.0 → 4.5.0

package/.claude/skills/cc-plan/assets/TASK_MANIFEST_TEMPLATE.json

@@ -0,0 +1,111 @@
+{
+  "changeId": "REQ-XXX",
+  "requirementId": "REQ-XXX",
+  "requirementVersion": "REQ-XXX.v1",
+  "outputPolicy": {
+    "documentLanguage": ""
+  },
+  "sourceRoadmap": {
+    "itemId": "RM-001",
+    "roadmapVersion": "1.0",
+    "roadmapSkillVersion": "2.1.0",
+    "sourceStage": "Stage 1",
+    "successSignal": "User can complete the new flow without manual workaround",
+    "killSignal": "Implementation requires reworking unrelated modules",
+    "dependencies": [
+      "Existing auth/session contract stays unchanged"
+    ],
+    "nonGoals": [
+      "No redesign of unrelated settings screens"
+    ]
+  },
+  "planningMeta": {
+    "reqPlanSkillVersion": "3.5.2",
+    "designVersion": "design.v1",
+    "approvedAt": "2026-04-15T12:00:00.000Z",
+    "approvedBy": "user",
+    "basedOnOption": "Option A"
+  },
+  "executionDiscipline": {
+    "default": "red-green-refactor",
+    "testFirstRequired": true,
+    "tddExceptions": []
+  },
+  "status": "planned",
+  "designMode": "tiny-design",
+  "approvedOption": "Option A",
+  "designStatus": "approved",
+  "reviewStatus": "approved",
+  "spec": {
+    "primaryCapability": "cap-example",
+    "secondaryCapabilities": [],
+    "expectedDelta": [
+      "Tighten current truth for the capability"
+    ],
+    "affectedInvariants": [],
+    "gapsClosed": [],
+    "newGaps": [],
+    "specFiles": [
+      "devflow/specs/capabilities/cap-example.md"
+    ],
+    "syncStatus": "planned"
+  },
+  "tasteDecisions": [],
+  "userChallenges": [],
+  "currentTaskId": "T001",
+  "activePhase": 1,
+  "frozenDecisions": [
+    "Keep the existing route and data contract",
+    "Prefer a minimal patch over a broader refactor"
+  ],
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "[TEST] Add a failing test for the missing behavior",
+      "phase": 1,
+      "status": "pending",
+      "tddPhase": "red",
+      "dependsOn": [],
+      "parallel": false,
+      "touches": [
+        "tests",
+        "requirement-behavior"
+      ],
+      "files": [
+        "src/feature/feature.test.ts"
+      ],
+      "acceptance": [
+        "The target behavior is reproduced as a failing test",
+        "The failure message points to the missing requirement behavior"
+      ],
+      "verification": [
+        "npm test -- src/feature/feature.test.ts"
+      ],
+      "evidence": [
+        "Failing test output"
+      ],
+      "context": {
+        "readFiles": [
+          "design.md",
+          "tasks.md",
+          "change-meta.json"
+        ],
+        "commands": [
+          "npm test -- src/feature/feature.test.ts"
+        ],
+        "notes": [
+          "Write the failing test first",
+          "Do not change unrelated contracts in this task"
+        ]
+      },
+      "reviews": {
+        "spec": "pending",
+        "code": "pending"
+      }
+    }
+  ],
+  "openQuestions": [],
+  "deferredQuestions": [
+    "If the patch touches shared contracts, upgrade the design to full-design"
+  ]
+}

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

@@ -0,0 +1,80 @@
+# DESIGN
+
+## Document Meta
+
+- Requirement version:
+- Design version:
+- CC-Plan skill version:
+- Output language:
+- 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,119 @@
+# Roadmap Skill Changelog
+
+## v4.3.2 - 2026-04-27
+
+- require roadmap outputs to resolve the runtime output policy before writing durable roadmap/backlog documents
+- record `Output language` as the machine-enforced language contract while treating `agent_preferences` as advisory style input
+
+## 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 产物。