cc-devflow 4.5.4 → 4.5.5

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,9 +169,13 @@
 - 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:

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

@@ -15,16 +15,19 @@
 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` 是独立编号空间，只在同前缀内递增，跨前缀同号允许共存。
 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`。
 
 ## Design Modes
 
@@ -50,18 +53,25 @@
 每个任务至少写清：
 
 - 目标
+- 对应 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 可以吸收上一轮学到的事实，但不能越过冻结边界。
 
 ## Review Gate
 
@@ -78,15 +88,19 @@
 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. 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 |

package/.claude/skills/cc-roadmap/assets/TRACKING_TEMPLATE.json

@@ -1,20 +1,30 @@
 {
-  "version": 2,
+  "version": 3,
   "outputPolicy": {
     "documentLanguage": ""
   },
-  "lastSyncedAt": "2026-04-19",
-  "backlogMeta": {
+  "meta": {
     "roadmapVersion": "roadmap.v1",
-    "skillVersion": "4.4.1",
+    "skillVersion": "5.0.0",
+    "status": "active",
+    "lastUpdated": "2026-05-01",
     "currentFocusStage": "Stage 1"
   },
-  "dependencyHandoff": {
-    "serialSpine": "RM-001",
-    "parallelReadyNextWave": "-",
-    "decompositionNotes": "-",
-    "notesOnBlockers": "-"
+  "context": {
+    "planningPosture": "",
+    "evidenceMaturity": "",
+    "canonicalTerms": [],
+    "durableDecisionSources": []
   },
+  "evidence": [],
+  "route": {
+    "recommended": "",
+    "whyThisWinsNow": "",
+    "rejectedRoutes": [],
+    "firstSignal": "",
+    "killSignal": ""
+  },
+  "stages": [],
   "items": [
     {
       "rmId": "RM-001",
@@ -48,5 +58,42 @@
         "missingEvidence": ""
       }
     }
-  ]
+  ],
+  "handoff": {
+    "readyForCcPlan": [],
+    "parked": [],
+    "serialSpine": [
+      "RM-001"
+    ],
+    "parallelWaves": []
+  },
+  "architecture": {
+    "diagramType": "flowchart",
+    "nodes": [
+      {
+        "id": "roadmap_json",
+        "label": "roadmap.json"
+      },
+      {
+        "id": "roadmap_md",
+        "label": "ROADMAP.md"
+      },
+      {
+        "id": "cc_plan",
+        "label": "cc-plan"
+      }
+    ],
+    "edges": [
+      {
+        "from": "roadmap_json",
+        "to": "roadmap_md",
+        "label": "renders"
+      },
+      {
+        "from": "roadmap_md",
+        "to": "cc_plan",
+        "label": "hands off"
+      }
+    ]
+  }
 }

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

@@ -445,13 +445,18 @@ function renderRoadmapTable(tracking) {
   return [header, separator, ...rows.map((row) => `| ${row} |`)].join('\n');
 }
 
+function isRoadmapState(tracking) {
+  return Number(tracking.version) === 3;
+}
+
 function buildTrackingBody(roadmapFile, trackingFile, tracking) {
   const relativePath = path.relative(path.dirname(roadmapFile), trackingFile).replace(/\\/g, '/');
   const displayPath = relativePath || path.basename(trackingFile);
+  const sourceLabel = isRoadmapState(tracking) ? 'Roadmap state source' : 'Tracking source';
 
   return [
     '',
-    `- Tracking source: \`${displayPath}\``,
+    `- ${sourceLabel}: \`${displayPath}\``,
     '',
     '<!-- roadmap-tracking:start -->',
     renderRoadmapTable(tracking),
@@ -460,14 +465,69 @@ function buildTrackingBody(roadmapFile, trackingFile, tracking) {
   ].join('\n');
 }
 
+function formatMermaidId(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+function formatMermaidLabel(value) {
+  return String(value || '').replace(/"/g, '\\"');
+}
+
+function renderArchitectureDiagram(tracking) {
+  const architecture = tracking.architecture || {};
+  const nodes = Array.isArray(architecture.nodes) ? architecture.nodes : [];
+  const edges = Array.isArray(architecture.edges) ? architecture.edges : [];
+
+  if (!nodes.length && !edges.length) {
+    return '';
+  }
+
+  const lines = ['## Technical Architecture', '', '```mermaid', 'flowchart TD'];
+
+  nodes.forEach((node) => {
+    const id = formatMermaidId(node.id);
+    if (id) {
+      lines.push(`  ${id}["${formatMermaidLabel(node.label || node.id)}"]`);
+    }
+  });
+
+  edges.forEach((edge) => {
+    const from = formatMermaidId(edge.from);
+    const to = formatMermaidId(edge.to);
+    if (!from || !to) {
+      return;
+    }
+
+    const label = String(edge.label || '').trim();
+    lines.push(label ? `  ${from} -->|${formatMermaidLabel(label)}| ${to}` : `  ${from} --> ${to}`);
+  });
+
+  lines.push('```', '');
+  return lines.join('\n');
+}
+
 function renderRoadmapDocument({ original = '# ROADMAP\n', roadmapFile, trackingFile, tracking }) {
   const section = extractSection(original, 'Implementation Tracking');
   const body = buildTrackingBody(roadmapFile, trackingFile, tracking);
   const nextSection = `## Implementation Tracking${body}`;
+  const architectureSection = isRoadmapState(tracking) ? `\n${renderArchitectureDiagram(tracking)}` : '';
 
-  return section
+  const rendered = section
     ? `${original.slice(0, section.start)}${nextSection}${original.slice(section.end)}`
     : `${original.replace(/\s*$/, '')}\n\n${nextSection}\n`;
+
+  if (!architectureSection.trim()) {
+    return rendered;
+  }
+
+  const existingArchitecture = extractSection(rendered, 'Technical Architecture');
+  if (existingArchitecture) {
+    return `${rendered.slice(0, existingArchitecture.start)}${architectureSection.trimEnd()}\n${rendered.slice(existingArchitecture.end)}`;
+  }
+
+  return `${rendered.replace(/\s*$/, '')}\n\n${architectureSection}`;
 }
 
 function renderBacklogQueue(tracking) {
@@ -564,17 +624,22 @@ function renderParked(tracking) {
 function renderBacklogDocument({ backlogFile, trackingFile, tracking }) {
   const relativePath = path.relative(path.dirname(backlogFile), trackingFile).replace(/\\/g, '/');
   const displayPath = relativePath || path.basename(trackingFile);
+  const sourceLabel = isRoadmapState(tracking) ? 'Roadmap state source' : 'Tracking source';
+  const deprecationNotice = isRoadmapState(tracking)
+    ? ['> Deprecated projection. Edit `roadmap.json` instead.', '']
+    : [];
 
   return [
     '# BACKLOG',
     '',
+    ...deprecationNotice,
     '## Backlog Meta',
     '',
     `- Roadmap version: ${formatInlineCode(tracking.backlogMeta.roadmapVersion)}`,
     `- Skill version: ${formatInlineCode(tracking.backlogMeta.skillVersion)}`,
     `- Last synced: ${formatInlineCode(tracking.lastSyncedAt)}`,
     `- Current focus stage: ${formatInlineCode(tracking.backlogMeta.currentFocusStage)}`,
-    `- Tracking source: \`${displayPath}\``,
+    `- ${sourceLabel}: \`${displayPath}\``,
     '',
     '## Queue',
     '',