cc-devflow 4.5.4 → 4.5.6

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

@@ -9,6 +9,14 @@
     "itemId": "RM-001",
     "roadmapVersion": "1.0",
     "roadmapSkillVersion": "2.1.0",
+    "syncStatus": "pending",
+    "syncCommand": ".claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh --rm RM-001 --status Planned --req REQ-XXX --progress 0%",
+    "updatedFiles": [
+      "devflow/roadmap.json",
+      "devflow/ROADMAP.md",
+      "devflow/BACKLOG.md"
+    ],
+    "noOpReason": "",
     "sourceStage": "Stage 1",
     "successSignal": "User can complete the new flow without manual workaround",
     "killSignal": "Implementation requires reworking unrelated modules",
@@ -20,11 +28,30 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.1",
+    "reqPlanSkillVersion": "3.7.6",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T12:00:00.000Z",
     "approvedBy": "user",
     "basedOnOption": "Option A",
+    "requirementBrief": {
+      "problemStatement": "The user-perspective problem this requirement solves.",
+      "solutionSummary": "The user-perspective solution after the requirement lands.",
+      "actors": [],
+      "userStories": [
+        {
+          "id": "US-001",
+          "actor": "",
+          "want": "",
+          "benefit": "",
+          "acceptance": []
+        }
+      ],
+      "edgeOrRecoveryStories": [],
+      "implementationDecisions": [],
+      "testingDecisions": [],
+      "outOfScope": [],
+      "furtherNotes": []
+    },
     "ambiguityGate": {
       "whatScore": 0,
       "whyScore": 0,
@@ -39,7 +66,36 @@
       "repeatedConcernFingerprints": [],
       "stallReason": "",
       "rerouteIfStalled": "ask-user"
-    }
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": [],
+        "recommendation": "Option A",
+        "options": [
+          {
+            "id": "A",
+            "label": "Minimal viable",
+            "recommended": true,
+            "completeness": "7/10",
+            "good": "",
+            "costRisk": ""
+          },
+          {
+            "id": "B",
+            "label": "Ideal architecture",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "",
+            "costRisk": ""
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do follows the approved implementation surface and task split",
+        "status": "answered"
+      }
+    ]
   },
   "sourceEvidence": [
     {
@@ -70,8 +126,13 @@
     "testQualityPolicy": {
       "publicInterfaceRequired": true,
       "behaviorAssertionRequired": true,
+      "specStyleTestNameRequired": true,
+      "oneLogicalBehaviorPerRed": true,
+      "publicVerificationPathRequired": true,
       "mockBoundary": "system-boundaries-only",
       "implementationDetailTests": "blocked",
+      "bulkRedTests": "blocked",
+      "boundaryAdapterShape": "specific-operations-preferred",
       "feedbackLoopPreference": [
         "automated-test",
         "http-curl",
@@ -125,6 +186,9 @@
       "testSeam": {
         "entry": "public interface / caller flow / CLI / API / UI / trace replay / harness",
         "behaviorAsserted": "The user or caller observable behavior that should exist",
+        "specStyleTestName": "caller can observe the required behavior",
+        "oneLogicalBehavior": true,
+        "publicVerificationPath": "Read back through the same public interface or user-visible path",
         "implementationDetailRisk": "low"
       },
       "feedbackLoop": {
@@ -138,9 +202,26 @@
       "testQuality": {
         "usesPublicInterface": true,
         "describesBehavior": true,
+        "specStyleName": true,
+        "oneLogicalBehavior": true,
+        "verifiesThroughPublicPath": true,
         "survivesInternalRefactor": true,
-        "mocksOnlySystemBoundaries": true
+        "mocksOnlySystemBoundaries": true,
+        "noBulkRed": true
       },
+      "greenMinimality": {
+        "guard": "Implement only the code needed to pass this Red behavior",
+        "noSpeculativeBranches": true
+      },
+      "refactorCandidates": [
+        "duplication",
+        "long method",
+        "shallow module",
+        "feature envy",
+        "primitive obsession",
+        "naming",
+        "more than three nested branches"
+      ],
       "dependsOn": [],
       "parallel": false,
       "touches": [

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

@@ -12,6 +12,7 @@
 - Approval status: `draft` | `in-review` | `approved`
 - Source roadmap item:
 - Source roadmap version:
+- Roadmap sync status:
 - Primary capability:
 - Secondary capabilities:
 
@@ -74,6 +75,20 @@
 
 > `tiny-design` 是短设计，不是免设计。没有明确批准状态、验证证据和升级触发条件，就不能继续拆任务。
 
+## PRD-Grade Brief
+
+- Problem statement:
+- Solution summary:
+- Actors / personas:
+- User stories:
+  - US-001: As a `<actor>`, I want `<feature>`, so that `<benefit>`.
+- Implementation decisions:
+- Testing decisions:
+- Out of scope:
+- Further notes:
+
+> 即使是 tiny-design，也要保留用户视角和验收口径。这里只写 durable 行为、契约和模块责任，不写易过期的行号或代码片段。
+
 ## Interface Shape
 
 - Callers:
@@ -82,6 +97,14 @@
 - Misuse risk:
 - Why this stays simple:
 
+## Interface Testability
+
+- Dependency shape: injected / created internally
+- Result shape: returned result / side effect
+- Boundary adapter shape: specific operation / generic fetcher / N/A
+- Test setup complexity: simple / conditional / brittle
+- Decision:
+
 ## Implementation Surface Map
 
 | Surface | Responsibility | Why here | Coupling risk |
@@ -93,16 +116,33 @@
 - Test framework source:
 - First failing test:
 - Test seam / public interface:
+- Spec-style test name:
+- One logical behavior:
+- Public verification path:
 - Behavior asserted:
 - Mock boundary:
+- Boundary adapter shape:
 - Feedback loop type:
 - Tracer bullet order:
 - Green implementation check:
+- Green minimality guard:
 - Refactor checkpoint:
+- Refactor candidates:
 - TDD exceptions:
 - Regression test required:
 - Primary check:
 - Secondary checks:
+
+## Roadmap Sync Gate
+
+- Source RM:
+- Locate command:
+- Sync command:
+- Updated files: `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`
+- Status after sync: `Planned` | `Split` | `Rerouted` | `No source RM`
+- Progress after sync:
+- No-op reason:
+- Blocking mismatch:
 - Evidence to collect:
 
 ## Conditional Design Checks
@@ -129,13 +169,18 @@
 - Domain language scan:
 - Implementation surface scan:
 - Interface depth scan:
+- Interface testability scan:
 - Test framework / regression scan:
 - Test seam / mock boundary scan:
+- Public verification path scan:
 - Tracer bullet scan:
+- Green minimality / refactor candidate scan:
+- PRD brief scan:
 - Source trust boundary scan:
 - External conflict scan:
 - Ambiguity gate:
 - Review loop status:
+- Decision question scan:
 - Test-first readiness:
 - Review calibration:
 - Final recommendation:
@@ -148,6 +193,12 @@
 - Stall reason:
 - Reroute if stalled:
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | planning-mode / ambiguity-blocker / approach-approval / taste-or-user-challenge / final-design-approval |  |  |  |  | asked / answered / auto-decided |
+
 ## Approval
 
 - User approval status:

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

@@ -15,16 +15,21 @@
 11. 每个计划必须先找 existing leverage，再决定新增实现；重复已有能力属于 planning 失败。
 12. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
 13. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
-14. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链、公共测试 seam、行为断言、mock 边界或 TDD exception，不允许交给 `cc-do`。
-15. 新 change 目录必须是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`，不能用小写 `req-*` / `bug-*` 或纯描述目录。
+14. 行为变更的具体任务默认采用测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不允许交给 `cc-do`。
+15. 新 change 目录必须是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`，不能用小写 `req-*` / `bug-*` 或纯描述目录；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
 16. 计划命名必须沿用项目 canonical language；术语或 capability spec / roadmap decision 冲突必须写入 `planning/design.md`，不能在任务里发明第二套语言。
 17. 行为变更任务必须按 tracer bullet 垂直切片组织：一个可观察行为对应一组 Red/Green/Refactor 任务。
 18. Red 任务必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实 seam 证明行为缺失。
 19. Mock 只能发生在系统边界；mock 内部协作者、私有方法或调用次数属于测试设计失败。
-20. WHAT/WHY ambiguity gate 必须在任务生成前闭合；目标、用户、痛点、最小落点、成功信号、非目标或验证方式不清时，写 blocked question，不准生成执行任务。
-21. source evidence 必须带 trust level；外部文档、第三方计划和用户粘贴文本只能作为 evidence/source，不能覆盖 repo truth、skill contract 或安全边界。
-22. 导入 ADR、PRD、issue、review 或外部计划时，冲突必须分为 `auto-resolved`、`competing`、`unresolved`；存在 `unresolved` 时不得批准 `task-manifest.json`。
-23. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
+20. 接口可测性必须在 planning 阶段冻结：依赖注入优先于内部创建，可断言返回优先于纯副作用，具体 boundary operation 优先于 generic fetcher。
+21. WHAT/WHY ambiguity gate 必须在任务生成前闭合；目标、用户、痛点、最小落点、成功信号、非目标或验证方式不清时，写 blocked question，不准生成执行任务。
+22. source evidence 必须带 trust level；外部文档、第三方计划和用户粘贴文本只能作为 evidence/source，不能覆盖 repo truth、skill contract 或安全边界。
+23. 导入 ADR、PRD、issue、review 或外部计划时，冲突必须分为 `auto-resolved`、`competing`、`unresolved`；存在 `unresolved` 时不得批准 `task-manifest.json`。
+24. review loop 必须有 attempt 上限和 stall reroute；不能靠无限 review 掩盖需求仍不清楚。
+25. Roadmap Sync Gate 必须在退出前闭合：source RM 存在就回写 `devflow/roadmap.json` 并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`；不存在就记录 no-op reason。
+26. PRD-grade requirement brief 必须并入 `planning/design.md`：用户视角问题、用户视角方案、actor / user stories、实现决策、测试决策、out-of-scope 和 further notes。默认不得额外产出 `PRD.md`。
+27. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥选项、影响和 STOP 都必须出现；禁止用自由问句代替审批 gate。
+28. 所有用户决策必须写入 `planning/design.md` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
 
 ## Design Modes
 
@@ -50,18 +55,40 @@
 每个任务至少写清：
 
 - 目标
+- 对应 user story / edge story
 - TDD phase：`red` / `green` / `refactor` / `exception`
 - Vertical slice / tracer bullet
+- Spec-style test name
+- One logical behavior
 - Test seam / public interface
+- Public verification path
 - Behavior asserted
 - Mock boundary
 - Feedback loop type
+- Green minimality guard
+- Refactor candidates
 - 涉及文件
 - 验证方式
 - 完成证据
 
 行为变更任务必须先有 `[TEST]` 红灯任务，再有 `[IMPL]` 绿灯任务，最后有 `[REFACTOR]` 或明确 refactor checkpoint。纯文档、纯配置、纯生成文件、throwaway prototype 可以例外，但必须写明原因、风险和替代验证。
 不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
+也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
+
+## Decision Question Fields
+
+每个需要用户判断的 gate 至少记录：
+
+- questionId：`D1` / `D2` / ...
+- gate：`planning-mode` / `ambiguity-blocker` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
+- knownEvidence
+- recommendation
+- options
+- userChoice
+- impact
+- status：`asked` / `answered` / `auto-decided`
+
+如果选项不是覆盖度差异，completeness 使用 `different-kind`，并写清不能打分的原因。
 
 ## Review Gate
 
@@ -78,15 +105,20 @@
 9. Test diagram and failure modes
 10. Domain language / spec decision conflict scan
 11. Interface depth scan
-12. Test seam / mock boundary scan
-13. Tracer bullet scan
-14. Source trust boundary scan
-15. External conflict scan
-16. Ambiguity gate
-17. Bounded review loop
-18. NOT in scope
-19. Test-first readiness
-20. Final recommendation
+12. Interface testability scan
+13. Test seam / mock boundary scan
+14. Public verification path scan
+15. Tracer bullet scan
+16. Green minimality / refactor candidate scan
+17. PRD brief scan
+18. Source trust boundary scan
+19. External conflict scan
+20. Ambiguity gate
+21. Bounded review loop
+22. NOT in scope
+23. Test-first readiness
+24. Decision questions recorded
+25. Final recommendation
 
 如有 UI scope，再补 design review 结论。
 如有 developer-facing scope，再补 DX review 结论。

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

@@ -1,5 +1,17 @@
 # Roadmap Skill Changelog
 
+## v5.0.0 - 2026-05-01
+
+- replace the roadmap/backlog/tracking split with `devflow/roadmap.json` as the single editable roadmap state
+- render `devflow/ROADMAP.md` and deprecated `devflow/BACKLOG.md` projections from the same state, including data-driven Mermaid architecture
+- make helper commands prefer `roadmap.json` while preserving legacy `roadmap-tracking.json` migration fallback
+
+Migration note:
+
+- edit `devflow/roadmap.json` for new roadmap work; treat `devflow/ROADMAP.md` and `devflow/BACKLOG.md` as generated views
+- existing `devflow/roadmap-tracking.json` files are read as legacy input and upgraded into `roadmap.json` on render or sync
+- `BACKLOG.md` remains generated for one compatibility release only and should not be used as durable truth
+
 ## v4.4.1 - 2026-04-28
 
 - clarify that roadmap language and durable decisions come from cc-devflow native sources: `devflow/specs/`, roadmap/backlog, historical design/analysis, and change metadata

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

@@ -23,20 +23,20 @@
 
 ## Local Kit
 
-- 生成骨架时用 `assets/ROADMAP_TEMPLATE.md` 和 `assets/BACKLOG_TEMPLATE.md`
-- 需要结构化 tracking 时用 `assets/TRACKING_TEMPLATE.json`
+- 生成骨架时先用 `assets/TRACKING_TEMPLATE.json` 写 `devflow/roadmap.json`，再渲染 `assets/ROADMAP_TEMPLATE.md` / `assets/BACKLOG_TEMPLATE.md` 形状
+- 需要结构化 roadmap state 时用 `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`
+- `scripts/locate-roadmap-item.sh` 先读 `roadmap.json`，再回落到旧 `roadmap-tracking.json` 和 Markdown，避免定位依赖 markdown 列位或文案漂移
+- 只想把 state 重渲染回 `ROADMAP.md` / `BACKLOG.md` 时，直接调用 `scripts/roadmap-tracking.js render`
+- `scripts/sync-roadmap-progress.sh` 会把 `roadmap.json` 当真相源，再回渲染 `ROADMAP.md` 和 deprecated `BACKLOG.md`
 - 变更版本时同步 `CHANGELOG.md`，必要时用 `scripts/bump-skill-version.sh`
 
 ## Context Sweep
 
 进入 roadmap 对话前，至少摸清：
 
-1. 现有 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+1. 现有 `devflow/roadmap.json` / `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
 2. `CLAUDE.md`、`README*`、`TODOS.md`
 3. 项目语言和持久决策：`devflow/specs/INDEX.md`、相关 capability specs、当前 roadmap/backlog、历史 `planning/design.md` / `planning/analysis.md`、`change-meta.json`、长期 design decision
 4. 最近相关 docs / specs / plans
@@ -116,6 +116,11 @@
 
 ## Output Contract
 
+`devflow/roadmap.json`
+- single editable roadmap state
+- output policy, meta, context, evidence, route, stages, items, handoff, and architecture
+- flat `architecture.nodes` / `architecture.edges` used to generate Mermaid
+
 `devflow/ROADMAP.md`
 - version / skill version / context snapshot / evidence ledger
 - 1-3 个阶段
@@ -128,13 +133,14 @@
 - 非目标
 - `RM Dependency Graph`
 - `Parallel waves`
-- `Implementation Tracking` 由 `devflow/roadmap-tracking.json` 渲染，避免手改 markdown 表格列位
+- `Implementation Tracking` 和 `Technical Architecture` 由 `devflow/roadmap.json` 渲染，避免手改 markdown 表格或 Mermaid
 
 `devflow/BACKLOG.md`
+- deprecated compatibility projection; edit `devflow/roadmap.json` instead
 - 只保留会真的进入下一轮 `cc-plan` 的事项
 - 每项注明来源阶段、优先级、证据、`Depends On`、`Parallel With`、当前未知点、下一决策、是否 ready
 - developer-facing / operator-facing 条目要带 target user、time to first value、magic moment 和 adoption bottleneck，方便 `cc-plan` 继续做 DX 设计
-- `Backlog Meta`、`Queue`、`Dependency Handoff`、`Ready For Req-Plan`、`Parked` 可由 `devflow/roadmap-tracking.json` 回渲染，避免 roadmap truth 和 backlog handoff 分叉
+- `Backlog Meta`、`Queue`、`Dependency Handoff`、`Ready For Req-Plan`、`Parked` 由 `devflow/roadmap.json` 回渲染，避免 roadmap truth 和 backlog handoff 分叉
 
 ## Review Loop
 
@@ -153,7 +159,7 @@
 ## Versioning
 
 - `patch`: 文案澄清、模板说明、小修补
-- `minor`: 上下文收集、评审、字段增强，且不破坏既有 tracking 习惯
+- `minor`: 上下文收集、评审、字段增强，且不破坏既有 roadmap state 习惯
 - `major`: 核心输出契约变化，需要 migration note
 
 ## Exit Rule

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

@@ -1,6 +1,6 @@
 ---
 name: cc-roadmap
-version: 4.4.1
+version: 5.0.0
 description: "Use when defining, resetting, or narrowing project direction, stage order, or backlog priority before a concrete requirement enters the PDCA loop."
 triggers:
   - "帮我定路线图"
@@ -19,16 +19,20 @@ reads:
   - "assets/TRACKING_TEMPLATE.json"
   - "references/roadmap-dialogue.md"
 writes:
+  - path: "devflow/roadmap.json"
+    durability: "durable"
+    required: true
   - path: "devflow/ROADMAP.md"
     durability: "durable"
     required: true
   - path: "devflow/BACKLOG.md"
     durability: "durable"
-    required: true
+    required: false
+    when: "deprecated compatibility projection is generated for downstream readers"
   - path: "devflow/roadmap-tracking.json"
     durability: "durable"
     required: false
-    when: "roadmap/backlog tracking is maintained through bundled helper scripts"
+    when: "legacy projects are being migrated into devflow/roadmap.json"
 entry_gate:
   - "Read current roadmap, backlog, related capability specs, and surrounding repo context before proposing direction."
   - "Load cc-devflow native language and durable-decision sources (`devflow/specs/`, current roadmap/backlog, prior `planning/design.md` or `planning/analysis.md`, and `change-meta.json`) before naming stages, capabilities, users, or backlog items."
@@ -68,7 +72,7 @@ tool_budget:
 
 写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
 
-- `Output language` 是机器约束，`devflow/ROADMAP.md`、`devflow/BACKLOG.md` 和 tracking metadata 必须记录并遵守它。
+- `Output language` 是机器约束，`devflow/roadmap.json`、`devflow/ROADMAP.md` 和兼容投影必须记录并遵守它。
 - `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
 - 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
 
@@ -76,9 +80,10 @@ tool_budget:
 
 1. `PLAYBOOK.md`
 2. `CHANGELOG.md`
-3. `assets/ROADMAP_TEMPLATE.md`
-4. `assets/BACKLOG_TEMPLATE.md`
-5. `references/roadmap-dialogue.md`
+3. `assets/TRACKING_TEMPLATE.json`
+4. `assets/ROADMAP_TEMPLATE.md`
+5. `assets/BACKLOG_TEMPLATE.md`
+6. `references/roadmap-dialogue.md`
 
 ## Use This Skill When
 
@@ -104,14 +109,14 @@ tool_budget:
 
 ## Harness Contract
 
-- Allowed actions: read current strategy files, repo context, and recent reality; compare route shapes; decompose independent subsystems into stages and RM candidates; write `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, and the optional `devflow/roadmap-tracking.json` sidecar used by bundled helpers as the shared roadmap/backlog truth source.
+- Allowed actions: read current strategy files, repo context, and recent reality; compare route shapes; decompose independent subsystems into stages and RM candidates; write `devflow/roadmap.json` as the editable roadmap state, then generate `devflow/ROADMAP.md` and the deprecated `devflow/BACKLOG.md` compatibility projection from that state.
 - Forbidden actions: decompose implementation tasks, invent hidden context, or jump into `cc-plan` before the roadmap is approved.
 - Required evidence: every stage and backlog item must point back to explicit repo facts, user constraints, or observed market signals.
 - Reroute rule: once the conversation collapses to one concrete requirement, stop strategic expansion and hand off to `cc-plan`.
 
 ## Entry Gate
 
-1. 如果 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 已存在，先读现状再重写。
+1. 如果 `devflow/roadmap.json`、`devflow/ROADMAP.md`、`devflow/BACKLOG.md` 或旧 `devflow/roadmap-tracking.json` 已存在，先读现状再重写。
 2. 先判断这是“项目方向问题”还是“单 requirement 执行问题”。
 3. 如果输入是多个独立子系统的混合目标，先拆成阶段和 `RM` 候选；不要继续追问某个子系统的实现细节。
 4. 先做一次上下文扫描，不能跳过现有事实直接写愿景。
@@ -232,7 +237,7 @@ tool_budget:
 
 ## Review Loop
 
-写完 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 后，至少完成这 6 个检查：
+写完 `devflow/roadmap.json` 并生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 后，至少完成这些检查：
 
 1. Placeholder scan：不能有 TBD、TODO、`[NEEDS CONTEXT]` 之类的逃避词。
 2. Evidence scan：每个阶段是否都能指回某个现实证据，而不是空洞愿景。
@@ -250,8 +255,9 @@ tool_budget:
 ## Output
 
 - `devflow/ROADMAP.md`
-- `devflow/BACKLOG.md`
-- `devflow/roadmap-tracking.json` when helper automation needs a shared roadmap/backlog truth source
+- `devflow/roadmap.json`
+- `devflow/BACKLOG.md` as a deprecated compatibility projection
+- `devflow/roadmap-tracking.json` only when migrating legacy projects
 
 ## Good Output
 
@@ -270,13 +276,13 @@ tool_budget:
 
 - `patch`：措辞、模板字段说明、非契约性澄清
 - `minor`：新增兼容字段、上下文收集规则、评审规则、输出结构增强
-- `major`：改变 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 的核心契约、阶段模型或 handoff 预期
+- `major`：改变 `devflow/roadmap.json`、生成投影、阶段模型或 handoff 预期
 
 每次修改都必须：
 
 1. 更新本文件 frontmatter 的 `version`
 2. 更新 `CHANGELOG.md`
-3. 如果会影响已有 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 使用方式，在 `CHANGELOG.md` 写清 migration note
+3. 如果会影响已有 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` / `devflow/roadmap-tracking.json` 使用方式，在 `CHANGELOG.md` 写清 migration note
 
 ## Bundled Resources
 
@@ -286,7 +292,7 @@ tool_budget:
 - 结构化 tracking 模板：`assets/TRACKING_TEMPLATE.json`
 - 对话骨架：`references/roadmap-dialogue.md`
 - 条目定位：`scripts/locate-roadmap-item.sh`
-- tracking 渲染器：`scripts/roadmap-tracking.js`
+- roadmap state 渲染器：`scripts/roadmap-tracking.js`
 - 进度回写：`scripts/sync-roadmap-progress.sh`
 - 版本递增：`scripts/bump-skill-version.sh`
 
@@ -302,7 +308,7 @@ tool_budget:
 
 1. 先收上下文，再收意见。
 2. 没有现实证据时必须明确写成 assumption，而不是偷偷当事实。
-3. `devflow/ROADMAP.md` 是方向真相源，`devflow/BACKLOG.md` 是进入下一轮规划的缓冲区。
+3. `devflow/roadmap.json` 是唯一可编辑方向真相源，`devflow/ROADMAP.md` 和 `devflow/BACKLOG.md` 是生成投影。
 4. 决策理由必须保留下来，方便以后重跑时比较版本差异。
 5. 路线图里的术语必须沿用项目语言；没有 canonical term 时写 assumption，不要创造第二套概念系统。
 6. 不要为了显得完整而写 6 个阶段，能打赢下一仗比画完整战争图更重要。

package/.claude/skills/cc-roadmap/assets/BACKLOG_TEMPLATE.md

@@ -1,5 +1,7 @@
 # BACKLOG
 
+> Deprecated projection. Edit `roadmap.json` instead.
+
 ## Backlog Meta
 
 - Roadmap version:
@@ -7,7 +9,7 @@
 - Output language:
 - Last synced:
 - Current focus stage:
-- Tracking source: `devflow/roadmap-tracking.json`
+- Roadmap state source: `devflow/roadmap.json`
 
 ## Queue
 

package/.claude/skills/cc-roadmap/assets/ROADMAP_TEMPLATE.md

@@ -2,6 +2,7 @@
 
 ## Roadmap Meta
 
+- Roadmap state source: `devflow/roadmap.json`
 - Roadmap version:
 - Skill version:
 - Output language:
@@ -178,6 +179,15 @@ flowchart LR
 - Serial spine:
 - Parallel-ready branches:
 
+## Technical Architecture
+
+```mermaid
+flowchart TD
+  roadmap_json["roadmap.json"] --> roadmap_md["ROADMAP.md"]
+  roadmap_json --> backlog_md["BACKLOG.md (deprecated)"]
+  roadmap_md --> cc_plan["cc-plan"]
+```
+
 ## Parallel Waves
 
 | Wave | Ready when | Items | Why parallel |
@@ -197,7 +207,7 @@ flowchart LR
 
 ## Implementation Tracking
 
-- Tracking source: `devflow/roadmap-tracking.json`
+- Roadmap state source: `devflow/roadmap.json`
 
 <!-- roadmap-tracking:start -->
 | RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |