cc-devflow 4.5.3 → 4.5.5

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',
     '',

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',