cc-devflow 4.5.4 → 4.5.5

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/schema.js

@@ -65,6 +65,47 @@ const DEFAULT_TRACKING = {
   items: []
 };
 
+const DEFAULT_ROADMAP_STATE = {
+  version: 3,
+  outputPolicy: {
+    documentLanguage: 'en'
+  },
+  meta: {
+    roadmapVersion: '',
+    skillVersion: '',
+    status: 'active',
+    lastUpdated: '',
+    currentFocusStage: ''
+  },
+  context: {
+    planningPosture: '',
+    evidenceMaturity: '',
+    canonicalTerms: [],
+    durableDecisionSources: []
+  },
+  evidence: [],
+  route: {
+    recommended: '',
+    whyThisWinsNow: '',
+    rejectedRoutes: [],
+    firstSignal: '',
+    killSignal: ''
+  },
+  stages: [],
+  items: [],
+  handoff: {
+    readyForCcPlan: [],
+    parked: [],
+    serialSpine: [],
+    parallelWaves: []
+  },
+  architecture: {
+    diagramType: 'flowchart',
+    nodes: [],
+    edges: []
+  }
+};
+
 function normalizeHeader(value) {
   return String(value || '')
     .trim()
@@ -188,6 +229,83 @@ function normalizeTracking(raw) {
   };
 }
 
+function normalizeStringList(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
+  }
+
+  return parseList(value);
+}
+
+function buildRoadmapHandoff(tracking, handoff = {}) {
+  const items = Array.isArray(tracking.items) ? tracking.items : [];
+  const dependencyHandoff = tracking.dependencyHandoff || {};
+  const readyForCcPlan = normalizeStringList(handoff.readyForCcPlan);
+  const parked = normalizeStringList(handoff.parked);
+
+  return {
+    readyForCcPlan: readyForCcPlan.length
+      ? readyForCcPlan
+      : items.filter((item) => item.backlog.ready && !item.backlog.parked).map((item) => item.rmId),
+    parked: parked.length
+      ? parked
+      : items.filter((item) => item.backlog.parked).map((item) => item.rmId),
+    serialSpine: normalizeStringList(handoff.serialSpine || dependencyHandoff.serialSpine),
+    parallelWaves: normalizeStringList(
+      handoff.parallelWaves || dependencyHandoff.parallelReadyNextWave
+    )
+  };
+}
+
+function normalizeRoadmapState(raw = {}) {
+  const tracking = normalizeTracking(raw);
+  const meta = raw.meta || {};
+  const context = raw.context || {};
+  const route = raw.route || {};
+  const architecture = raw.architecture || {};
+
+  return {
+    ...DEFAULT_ROADMAP_STATE,
+    version: 3,
+    outputPolicy: {
+      ...DEFAULT_ROADMAP_STATE.outputPolicy,
+      ...(raw.outputPolicy || {})
+    },
+    meta: {
+      ...DEFAULT_ROADMAP_STATE.meta,
+      roadmapVersion: String(meta.roadmapVersion || tracking.backlogMeta.roadmapVersion).trim(),
+      skillVersion: String(meta.skillVersion || tracking.backlogMeta.skillVersion).trim(),
+      status: String(meta.status || DEFAULT_ROADMAP_STATE.meta.status).trim(),
+      lastUpdated: String(meta.lastUpdated || tracking.lastSyncedAt).trim(),
+      currentFocusStage: String(meta.currentFocusStage || tracking.backlogMeta.currentFocusStage).trim()
+    },
+    context: {
+      ...DEFAULT_ROADMAP_STATE.context,
+      ...context,
+      canonicalTerms: normalizeStringList(context.canonicalTerms),
+      durableDecisionSources: normalizeStringList(context.durableDecisionSources)
+    },
+    evidence: Array.isArray(raw.evidence) ? raw.evidence : [],
+    route: {
+      ...DEFAULT_ROADMAP_STATE.route,
+      ...route,
+      rejectedRoutes: Array.isArray(route.rejectedRoutes) ? route.rejectedRoutes : []
+    },
+    stages: Array.isArray(raw.stages) ? raw.stages : [],
+    items: tracking.items,
+    backlogMeta: tracking.backlogMeta,
+    dependencyHandoff: tracking.dependencyHandoff,
+    lastSyncedAt: tracking.lastSyncedAt,
+    handoff: buildRoadmapHandoff(tracking, raw.handoff || {}),
+    architecture: {
+      ...DEFAULT_ROADMAP_STATE.architecture,
+      ...architecture,
+      nodes: Array.isArray(architecture.nodes) ? architecture.nodes : [],
+      edges: Array.isArray(architecture.edges) ? architecture.edges : []
+    }
+  };
+}
+
 const ROADMAP_HEADER_TO_KEY = new Map(
   ROADMAP_COLUMNS.map(([header, key]) => [normalizeHeader(header), key])
 );
@@ -225,6 +343,7 @@ const PARKED_FIELD_MAP = new Map(
 module.exports = {
   BACKLOG_QUEUE_COLUMNS,
   BACKLOG_QUEUE_HEADER_TO_KEY,
+  DEFAULT_ROADMAP_STATE,
   DEFAULT_TRACKING,
   PARKED_FIELD_MAP,
   READY_FIELD_MAP,
@@ -240,6 +359,7 @@ module.exports = {
   normalizeCell,
   normalizeHeader,
   normalizeItem,
+  normalizeRoadmapState,
   normalizeTracking,
   parseList
 };

package/.claude/skills/cc-roadmap/scripts/lib/roadmap-tracking/store.js

@@ -1,8 +1,10 @@
 const fs = require('fs');
+const path = require('path');
 
 const {
   emptyBacklog,
   normalizeItem,
+  normalizeRoadmapState,
   normalizeTracking,
   parseList
 } = require('./schema');
@@ -63,7 +65,26 @@ function upgradeLegacyTracking(parsed) {
   });
 }
 
+function isRoadmapStateFile(filePath) {
+  return path.basename(filePath || '') === 'roadmap.json';
+}
+
+function legacyTrackingFileFor(filePath) {
+  return path.join(path.dirname(filePath), 'roadmap-tracking.json');
+}
+
 function loadTracking({ trackingFile, roadmapFile = '', backlogFile = '' }) {
+  if (isRoadmapStateFile(trackingFile)) {
+    if (fs.existsSync(trackingFile)) {
+      return normalizeRoadmapState(readJson(trackingFile));
+    }
+
+    const legacyTrackingFile = legacyTrackingFileFor(trackingFile);
+    if (fs.existsSync(legacyTrackingFile)) {
+      return normalizeRoadmapState(readJson(legacyTrackingFile));
+    }
+  }
+
   if (trackingFile && fs.existsSync(trackingFile)) {
     return upgradeLegacyTracking(readJson(trackingFile));
   }
@@ -112,7 +133,10 @@ function applySyncArgs(tracking, args) {
 }
 
 function persistTrackingFiles({ trackingFile, roadmapFile, backlogFile, tracking }) {
-  writeJson(trackingFile, tracking);
+  writeJson(
+    trackingFile,
+    isRoadmapStateFile(trackingFile) ? normalizeRoadmapState(tracking) : tracking
+  );
 
   const roadmapOutput = renderRoadmapDocument({
     original: readFileIfExists(roadmapFile) || '# ROADMAP\n',

package/.claude/skills/cc-roadmap/scripts/locate-roadmap-item.sh

@@ -8,7 +8,7 @@ set -euo pipefail
 
 usage() {
   cat <<'EOF'
-Usage: locate-roadmap-item.sh <ID> [--roadmap devflow/ROADMAP.md] [--backlog devflow/BACKLOG.md] [--tracking-file devflow/roadmap-tracking.json]
+Usage: locate-roadmap-item.sh <ID> [--roadmap devflow/ROADMAP.md] [--backlog devflow/BACKLOG.md] [--tracking-file devflow/roadmap.json]
 
 ID can be RM-xxx or REQ-xxx.
 EOF
@@ -22,8 +22,10 @@ LEGACY_ROADMAP_FILE="$REPO_ROOT/devflow/roadmap/roadmap.md"
 DEFAULT_BACKLOG_FILE="$REPO_ROOT/devflow/BACKLOG.md"
 ROOT_BACKLOG_FILE="$REPO_ROOT/BACKLOG.md"
 LEGACY_BACKLOG_FILE="$REPO_ROOT/devflow/roadmap/backlog.md"
-DEFAULT_TRACKING_FILE="$REPO_ROOT/devflow/roadmap-tracking.json"
-ROOT_TRACKING_FILE="$REPO_ROOT/roadmap-tracking.json"
+DEFAULT_TRACKING_FILE="$REPO_ROOT/devflow/roadmap.json"
+ROOT_TRACKING_FILE="$REPO_ROOT/roadmap.json"
+LEGACY_DEFAULT_TRACKING_FILE="$REPO_ROOT/devflow/roadmap-tracking.json"
+LEGACY_ROOT_TRACKING_FILE="$REPO_ROOT/roadmap-tracking.json"
 LEGACY_TRACKING_FILE="$REPO_ROOT/devflow/roadmap/roadmap-tracking.json"
 ROADMAP_FILE="$DEFAULT_ROADMAP_FILE"
 BACKLOG_FILE="$DEFAULT_BACKLOG_FILE"
@@ -40,7 +42,7 @@ while [[ $# -gt 0 ]]; do
   case "$1" in
     --roadmap) ROADMAP_FILE="$2"; shift 2 ;;
     --backlog) BACKLOG_FILE="$2"; shift 2 ;;
-    --tracking-file) TRACKING_FILE="$2"; shift 2 ;;
+    --tracking|--tracking-file) TRACKING_FILE="$2"; shift 2 ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
   esac
@@ -64,10 +66,16 @@ fi
 
 if [[ "$TRACKING_FILE" == "$DEFAULT_TRACKING_FILE" && ! -f "$TRACKING_FILE" ]]; then
   roadmap_dir="$(cd "$(dirname "$ROADMAP_FILE")" 2>/dev/null && pwd || true)"
-  if [[ -n "$roadmap_dir" && -f "$roadmap_dir/roadmap-tracking.json" ]]; then
+  if [[ -n "$roadmap_dir" && -f "$roadmap_dir/roadmap.json" ]]; then
+    TRACKING_FILE="$roadmap_dir/roadmap.json"
+  elif [[ -n "$roadmap_dir" && -f "$roadmap_dir/roadmap-tracking.json" ]]; then
     TRACKING_FILE="$roadmap_dir/roadmap-tracking.json"
   elif [[ -f "$ROOT_TRACKING_FILE" ]]; then
     TRACKING_FILE="$ROOT_TRACKING_FILE"
+  elif [[ -f "$LEGACY_DEFAULT_TRACKING_FILE" ]]; then
+    TRACKING_FILE="$LEGACY_DEFAULT_TRACKING_FILE"
+  elif [[ -f "$LEGACY_ROOT_TRACKING_FILE" ]]; then
+    TRACKING_FILE="$LEGACY_ROOT_TRACKING_FILE"
   elif [[ -f "$LEGACY_TRACKING_FILE" ]]; then
     TRACKING_FILE="$LEGACY_TRACKING_FILE"
   fi

package/.claude/skills/cc-roadmap/scripts/roadmap-tracking.js

@@ -9,9 +9,9 @@ function usage() {
   process.stderr.write(
     [
       'Usage:',
-      '  roadmap-tracking.js sync --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap-tracking.json> --rm <RM-ID> [field updates]',
-      '  roadmap-tracking.js render --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap-tracking.json>',
-      '  roadmap-tracking.js find --tracking <roadmap-tracking.json> --id <RM-ID|REQ-ID>',
+      '  roadmap-tracking.js sync --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap.json> --rm <RM-ID> [field updates]',
+      '  roadmap-tracking.js render --roadmap <ROADMAP.md> --backlog <BACKLOG.md> --tracking <roadmap.json>',
+      '  roadmap-tracking.js find --tracking <roadmap.json> --id <RM-ID|REQ-ID>',
       '',
       'Fields:',
       '  --item <title>',

package/.claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh

@@ -11,7 +11,7 @@ usage() {
 Usage: sync-roadmap-progress.sh --rm RM-001 [--status Planned] [--req REQ-001] [--progress 50%] [--file devflow/ROADMAP.md]
        [--item "Add copy action"] [--stage "Stage 1"] [--priority P1] [--depends-on "RM-000"]
        [--primary-capability cap-example] [--secondary-capabilities "cap-a,cap-b"] [--spec-delta "tighten truth"]
-       [--tracking-file devflow/roadmap-tracking.json] [--backlog-file devflow/BACKLOG.md]
+       [--tracking-file devflow/roadmap.json] [--backlog-file devflow/BACKLOG.md]
 EOF
 }
 
@@ -49,7 +49,7 @@ while [[ $# -gt 0 ]]; do
     --secondary-capabilities) SECONDARY_CAPABILITIES="$2"; shift 2 ;;
     --spec-delta) SPEC_DELTA="$2"; shift 2 ;;
     --file) FILE="$2"; shift 2 ;;
-    --tracking-file) TRACKING_FILE="$2"; shift 2 ;;
+    --tracking|--tracking-file) TRACKING_FILE="$2"; shift 2 ;;
     --backlog-file) BACKLOG_FILE="$2"; shift 2 ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
@@ -70,7 +70,7 @@ if [[ -z "$RM_ID" || ! -f "$FILE" ]]; then
 fi
 
 if [[ -z "$TRACKING_FILE" ]]; then
-  TRACKING_FILE="$(cd "$(dirname "$FILE")" && pwd)/roadmap-tracking.json"
+  TRACKING_FILE="$(cd "$(dirname "$FILE")" && pwd)/roadmap.json"
 fi
 
 if [[ -z "$BACKLOG_FILE" ]]; then

package/CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.5] - 2026-05-06
+
+### Changed
+
+- Updated `cc-plan` and `cc-investigate` with Roadmap Sync Gates so frozen planning and root-cause handoffs reconcile source RM progress before moving to `cc-do`.
+- Updated `cc-act` to check roadmap progress during closeout and to write source RM status through `devflow/roadmap.json` with regenerated `ROADMAP.md` / `BACKLOG.md` projections.
+
 ## [4.5.4] - 2026-04-29
 
 ### Fixed

package/README.md

@@ -62,7 +62,7 @@ After installation, ask your agent to use the workflow skills directly. Start wi
 
 | Skill | Use it when | Main output |
 | --- | --- | --- |
-| `cc-roadmap` | You need product direction, staged scope, or backlog order | `devflow/ROADMAP.md`, `devflow/BACKLOG.md` |
+| `cc-roadmap` | You need product direction, staged scope, or backlog order | `devflow/roadmap.json`, `devflow/ROADMAP.md`, deprecated `devflow/BACKLOG.md` |
 | `cc-plan` | A feature or change needs scope, design, and task freezing | `planning/design.md`, `planning/tasks.md`, `task-manifest.json` |
 | `cc-investigate` | A bug needs symptom, reproduction, root cause, and repair boundary | `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json` |
 | `cc-do` | Planned or investigated work needs implementation | code, tests, checkpoints, scratch runtime |
@@ -78,15 +78,15 @@ Maintenance skills are shipped with the pack:
 
 `cc-roadmap` now records planning posture, evidence maturity, canonical project language, and durable decision context before recommending a route. That keeps idea-stage, active-user, paying-customer, infrastructure, and recovery work from being forced through the same questions, and prevents roadmap items from inventing a second vocabulary. Developer-facing or operator-facing roadmap items also carry target user, time to first value, magic moment, adoption bottleneck, and domain handoff into `cc-plan`.
 
-Canonical language and durable decisions stay inside cc-devflow-native sources: `devflow/specs/`, `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, `planning/design.md`, `planning/analysis.md`, and `change-meta.json`.
+Canonical language and durable decisions stay inside cc-devflow-native sources: `devflow/specs/`, `devflow/roadmap.json`, `devflow/ROADMAP.md`, `planning/design.md`, `planning/analysis.md`, and `change-meta.json`.
 
-`cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, public test seams, behavior assertions, mock boundaries, coverage quality, mandatory regression tests, interface depth, and vertical tracer-bullet slices when existing behavior changes.
+`cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, public test seams, spec-style test names, public verification paths, behavior assertions, mock boundaries, coverage quality, mandatory regression tests, interface depth, Green minimality guards, refactor candidates, and vertical tracer-bullet slices when existing behavior changes. Before handoff, `cc-plan` and `cc-investigate` also reconcile the source roadmap item so RM status, REQ/FIX binding, progress, and spec diagnosis do not drift from the frozen change artifacts.
 
 ## Verification And Ship Gates
 
 `cc-check` now treats QA as a feedback-loop problem, not only a green-test problem. Bugfix and behavior work records the loop used to prove reality, expected versus actual behavior, reproduction steps, test boundary quality, and architecture follow-ups when no clean public test seam exists.
 
-`cc-act` carries that evidence into PR briefs, handoffs, and release notes. Follow-ups must be durable behavior briefs with current behavior, desired behavior, key interfaces, acceptance criteria, and explicit out-of-scope notes before they are written back to roadmap or backlog.
+`cc-act` carries that evidence into PR briefs, handoffs, and release notes. It checks source roadmap progress during closeout, updates `devflow/roadmap.json`, and regenerates `devflow/ROADMAP.md` / `devflow/BACKLOG.md` when verified reality changes. Follow-ups must be durable behavior briefs with current behavior, desired behavior, key interfaces, acceptance criteria, and explicit out-of-scope notes before they are written back to roadmap or backlog.
 
 ## Installation Modes
 
@@ -193,7 +193,7 @@ The currently distributed skill folders are:
 ## Durable vs Ephemeral
 
 - `devflow/specs/` stores durable capability truth: `INDEX.md` plus `capabilities/*.md`.
-- New change directories use `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes.
+- New change directories use `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` numbers advance independently, so the same number may exist in both prefixes.
 - `devflow/changes/<change>/` stores durable change truth: `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file.
 - `devflow/workspaces/<change>/` stores ephemeral runtime scratch such as worker assignment, journals, prompts, and session logs.
 - Regenerable files should not be persisted under `devflow/changes/`.

package/README.zh-CN.md

@@ -62,7 +62,7 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 | Skill | 什么时候用 | 主要产物 |
 | --- | --- | --- |
-| `cc-roadmap` | 需要产品方向、阶段范围或 backlog 顺序 | `devflow/ROADMAP.md`、`devflow/BACKLOG.md` |
+| `cc-roadmap` | 需要产品方向、阶段范围或 backlog 顺序 | `devflow/roadmap.json`、`devflow/ROADMAP.md`、deprecated `devflow/BACKLOG.md` |
 | `cc-plan` | 新功能或变更需要澄清范围、设计方案、冻结任务 | `planning/design.md`、`planning/tasks.md`、`task-manifest.json` |
 | `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` |
 | `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、checkpoint、scratch runtime |
@@ -78,15 +78,15 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 `cc-roadmap` 现在会先记录 planning posture、evidence maturity、项目 canonical language 和持久决策上下文，再推荐路线。idea、已有用户、付费客户、infra、recovery 场景不会被套进同一组问题，也不会让 roadmap item 发明第二套词汇。面向开发者或操作者的 roadmap item 还会把目标用户、time to first value、magic moment、adoption bottleneck 和 domain handoff 交给 `cc-plan`。
 
-Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源：`devflow/specs/`、`devflow/ROADMAP.md`、`devflow/BACKLOG.md`、`planning/design.md`、`planning/analysis.md` 和 `change-meta.json`。
+Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源：`devflow/specs/`、`devflow/roadmap.json`、`devflow/ROADMAP.md`、`planning/design.md`、`planning/analysis.md` 和 `change-meta.json`。
 
-`cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、public test seam、behavior assertion、mock boundary、覆盖质量、强制 regression test、interface depth 和 vertical tracer-bullet slices。
+`cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、public test seam、spec-style test name、public verification path、behavior assertion、mock boundary、覆盖质量、强制 regression test、interface depth、Green minimality guard、refactor candidates 和 vertical tracer-bullet slices。交接前，`cc-plan` 和 `cc-investigate` 还会校准 source roadmap item，让 RM 状态、REQ/FIX 绑定、progress 和 spec diagnosis 不再漂移。
 
 ## 验证与交付门禁
 
 `cc-check` 现在把 QA 当成反馈环问题，而不是只看测试是否绿。Bugfix 和行为变更需要记录证明现实的 loop、expected / actual、复现步骤、测试边界质量；如果没有干净的 public test seam，要留下架构 follow-up。
 
-`cc-act` 会把这些证据带进 PR brief、handoff 和 release note。Follow-up 必须写成 durable behavior brief，包含 current behavior、desired behavior、key interfaces、acceptance criteria 和 out-of-scope，再回写 roadmap 或 backlog。
+`cc-act` 会把这些证据带进 PR brief、handoff 和 release note。它会在 closeout 检查 source roadmap progress，必要时更新 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`。Follow-up 必须写成 durable behavior brief，包含 current behavior、desired behavior、key interfaces、acceptance criteria 和 out-of-scope，再回写 roadmap 或 backlog。
 
 ## 安装方式
 
@@ -193,7 +193,7 @@ npx cc-devflow config doctor --cwd /path/to/your/project
 ## Durable 与 Ephemeral
 
 - `devflow/specs/` 保存 durable capability truth：`INDEX.md` 和 `capabilities/*.md`。
-- 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。
+- 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号允许共存。
 - `devflow/changes/<change>/` 保存 durable change truth：`change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、`team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一最终 handoff 文件。
 - `devflow/workspaces/<change>/` 保存 ephemeral runtime scratch，例如 worker assignment、journal、prompt 和 session log。
 - 能从 durable truth 再生成的文件，不应该持久化到 `devflow/changes/`。

package/docs/CLAUDE.md

@@ -27,4 +27,4 @@ docs/
 - 面向使用者：优先写“怎么用/怎么做”，其次再写“为什么”。
 - 可检索：标题清晰、关键词统一（`/flow-*`、`/core-*`、`/speckit.*`）。
 - 可落地：结论必须能映射到具体命令、脚本或模板文件路径。
-- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；描述部分使用 kebab-case。
+- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；`REQ` 和 `FIX` 是独立编号空间；描述部分使用 kebab-case。

package/docs/examples/START-HERE.md

@@ -64,9 +64,9 @@ Use this when the only thing you know is the file in front of you.
 
 | If the main file you have is... | You are probably here | Read this first |
 | --- | --- | --- |
-| `ROADMAP.md` | `cc-roadmap` | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
-| `roadmap-tracking.json` | `cc-roadmap` machine truth source for roadmap + backlog | [pdca-loop/roadmap-tracking.json](./pdca-loop/roadmap-tracking.json) |
-| `BACKLOG.md` | `cc-roadmap` -> `cc-plan` handoff | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
+| `roadmap.json` | `cc-roadmap` editable machine truth source | [pdca-loop/roadmap.json](./pdca-loop/roadmap.json) |
+| `ROADMAP.md` | `cc-roadmap` generated human view | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
+| `BACKLOG.md` | deprecated `cc-roadmap` -> `cc-plan` projection | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
 | `design.md` | `cc-plan` | [pdca-loop/design.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md) or [full-design-blocked/design.md](./full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md) |
 | `tasks.md` | `cc-plan` or `cc-do` | [pdca-loop/tasks.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md) |
 | `task-manifest.json` | `cc-do` | [pdca-loop/task-manifest.json](./pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json) |

package/docs/examples/example-bindings.json

@@ -1,12 +1,12 @@
 {
-  "updatedAt": "2026-04-28",
+  "updatedAt": "2026-05-06",
   "skills": {
-    "cc-roadmap": "4.4.1",
-    "cc-plan": "3.7.1",
-    "cc-investigate": "1.2.1",
-    "cc-do": "1.6.1",
+    "cc-roadmap": "5.0.0",
+    "cc-plan": "3.7.5",
+    "cc-investigate": "1.2.2",
+    "cc-do": "1.6.2",
     "cc-check": "1.10.1",
-    "cc-act": "1.8.1",
+    "cc-act": "1.8.2",
     "cc-spec-init": "1.1.0"
   },
   "examples": [
@@ -15,7 +15,13 @@
       "readme": "docs/examples/pdca-loop/README.md",
       "root": "docs/examples/pdca-loop",
       "changeDir": "docs/examples/pdca-loop/changes/REQ-001-copy-invite-link",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check",
+        "cc-act"
+      ],
       "expectedShipMode": "create-pr"
     },
     {
@@ -23,7 +29,12 @@
       "readme": "docs/examples/full-design-blocked/README.md",
       "root": "docs/examples/full-design-blocked",
       "changeDir": "docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check"
+      ],
       "expectedShipMode": "none"
     },
     {
@@ -31,7 +42,13 @@
       "readme": "docs/examples/local-handoff/README.md",
       "root": "docs/examples/local-handoff",
       "changeDir": "docs/examples/local-handoff/changes/REQ-003-audit-log-export",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check",
+        "cc-act"
+      ],
       "expectedShipMode": "local-handoff"
     }
   ]

package/docs/examples/full-design-blocked/BACKLOG.md

@@ -1,12 +1,14 @@
 # BACKLOG
 
+> Deprecated projection. Edit `roadmap.json` instead.
+
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 ## Queue
 

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.5`, `cc-do@1.6.2`, `cc-check@1.10.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 
@@ -40,9 +40,9 @@ The sample shows what happens when implementation moved before the integration d
 
 ## Artifact Map
 
-- `ROADMAP.md`
-- `roadmap-tracking.json` (shared roadmap/backlog truth)
-- `BACKLOG.md`
+- `roadmap.json` (editable roadmap truth)
+- `ROADMAP.md` (generated view)
+- `BACKLOG.md` (deprecated projection)
 - `changes/REQ-002-bulk-invite-import/planning/design.md`
 - `changes/REQ-002-bulk-invite-import/planning/tasks.md`
 - `changes/REQ-002-bulk-invite-import/planning/task-manifest.json`

package/docs/examples/full-design-blocked/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`
@@ -44,10 +44,24 @@
 - Kill signal / stop condition: if the team cannot specify bulk invite semantics before implementation starts
 
 ## Implementation Tracking
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 <!-- roadmap-tracking:start -->
 | RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |
 |------|------|------|------|------|------|------|------|------|------|------|
 | RM-010 | Add CSV bulk invite import for admins | Stage 2 | P1 | cap-bulk-invite-import | cap-workspace-membership | define import semantics before widening current truth | - | Verification blocked | REQ-002 | 80% |
 <!-- roadmap-tracking:end -->
+
+
+## Technical Architecture
+
+```mermaid
+flowchart TD
+  roadmap_json["roadmap.json"]
+  roadmap_md["ROADMAP.md"]
+  backlog_md["BACKLOG.md (deprecated)"]
+  cc_plan["cc-plan"]
+  roadmap_json -->|renders| roadmap_md
+  roadmap_json -->|projects| backlog_md
+  roadmap_md -->|hands off| cc_plan
+```

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.5`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging
@@ -42,6 +42,43 @@
   - enterprise SCIM provisioning
   - background retry orchestration
 
+## PRD-Grade Requirement Brief
+
+- Problem statement: admins onboarding larger teams spend too much time sending individual invites, and they cannot predict how duplicates, invalid rows, and seat limits will resolve in bulk.
+- Solution summary: admins upload a CSV and receive deterministic row outcomes before the invite flow can be trusted for execution.
+- Actors / personas:
+  - workspace admin onboarding 20-200 collaborators
+  - support operator explaining invite outcomes
+- Primary user stories:
+
+| ID | Actor | Wants | Benefit | Acceptance / evidence |
+|----|-------|-------|---------|-----------------------|
+| US-001 | Workspace admin | upload a CSV of invite emails | invite many collaborators without one-by-one entry | mixed valid rows produce visible accepted outcomes |
+| US-002 | Workspace admin | see duplicate, invalid, and over-limit row states | understand what happened without support help | every skipped or rejected row has a reason |
+| US-003 | Support operator | trust the audit trail for each row outcome | explain invite history consistently | audit entries match visible row outcomes |
+
+- Edge / recovery stories:
+
+| ID | Actor | Failure / boundary | Desired outcome | Acceptance / evidence |
+|----|-------|--------------------|-----------------|-----------------------|
+| US-EDGE-001 | Workspace admin | CSV contains duplicates and invalid emails | safe rows can proceed while bad rows are explained | rule matrix covers duplicate and invalid cases |
+| US-EDGE-002 | Workspace admin | upload exceeds seat limits | over-limit rows are rejected consistently | billing-seat tests match UI summary |
+
+- Implementation decisions:
+  - Freeze one row-outcome matrix before execution resumes.
+  - Reuse the existing invite engine, billing seat checks, and audit log contract.
+  - Keep enterprise provisioning and background retry orchestration outside this requirement.
+- Testing decisions:
+  - Test row semantics through bulk-import rules and the admin upload flow.
+  - Verify audit mapping against visible row outcomes.
+  - Use existing invite and admin panel tests as prior art.
+- Out of scope:
+  - enterprise SCIM provisioning
+  - background job redesign
+  - rollback wizard for partial success
+- Further notes:
+  - This design remains blocked until duplicate and seat-limit semantics are approved.
+
 ## Success Criteria
 
 - Observable success signals:
@@ -131,6 +168,7 @@
 - Ambiguity scan: blocked; duplicate + seat-limit semantics still need sharper wording
 - Feasibility scan: pass
 - Source alignment: pass; roadmap still prioritizes trust over speed
+- PRD brief scan: pass for actors and stories; blocked on duplicate and seat-limit semantics
 - UI / interaction review summary: result states are acceptable if semantics are frozen first
 - DX review summary: execution still needs a single row-outcome matrix
 - Auto-decided items:

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/task-manifest.json

@@ -5,6 +5,47 @@
   "updatedAt": "2026-04-16T12:00:00.000Z",
   "requirementId": "REQ-002",
   "requirementVersion": "REQ-002.v2",
+  "planningMeta": {
+    "reqPlanSkillVersion": "3.7.5",
+    "designVersion": "design.v2",
+    "approvedAt": null,
+    "approvedBy": null,
+    "basedOnOption": "Option B",
+    "requirementBrief": {
+      "problemStatement": "Admins onboarding larger teams need predictable bulk invite behavior for duplicates, invalid rows, and seat limits.",
+      "solutionSummary": "Freeze deterministic CSV row outcomes before executing the bulk invite flow.",
+      "actors": ["workspace admin", "support operator"],
+      "userStories": [
+        {
+          "id": "US-001",
+          "actor": "workspace admin",
+          "want": "upload a CSV of invite emails",
+          "benefit": "invite many collaborators without one-by-one entry",
+          "acceptance": ["Mixed valid rows produce visible accepted outcomes"]
+        },
+        {
+          "id": "US-002",
+          "actor": "workspace admin",
+          "want": "see duplicate, invalid, and over-limit row states",
+          "benefit": "understand what happened without support help",
+          "acceptance": ["Every skipped or rejected row has a reason"]
+        }
+      ],
+      "edgeOrRecoveryStories": [
+        {
+          "id": "US-EDGE-001",
+          "actor": "workspace admin",
+          "boundary": "CSV contains duplicates, invalid emails, or over-limit rows",
+          "desiredOutcome": "safe rows can proceed while bad rows are explained",
+          "acceptance": ["Rule matrix covers duplicate, invalid, and seat-limit cases"]
+        }
+      ],
+      "implementationDecisions": ["Freeze one row-outcome matrix before execution resumes"],
+      "testingDecisions": ["Test row semantics through bulk-import rules and the admin upload flow"],
+      "outOfScope": ["enterprise SCIM provisioning", "background job redesign", "rollback wizard for partial success"],
+      "furtherNotes": ["Design remains blocked until duplicate and seat-limit semantics are approved"]
+    }
+  },
   "currentTaskId": null,
   "activePhase": null,
   "tasks": [