cc-devflow 4.5.4 → 4.5.6

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

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,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.6] - 2026-05-08
+
+### Changed
+
+- Updated `cc-plan` with a fixed Decision Question Protocol so approval gates use numbered questions, recommendations, option tradeoffs, impact, and STOP instead of ad hoc prose.
+- Updated `cc-plan` to treat the full `REQ/FIX-<number>-<description>` change key as identity, so repeated numbers from parallel worktrees stay distinct.
+
+### Fixed
+
+- Fixed typed runtime queries and `cc-devflow query` so duplicate local change numbers can be resolved with an explicit `--change-key`.
+- Fixed ambiguous query path resolution so duplicate change ids return a structured JSON failure instead of escaping the query registry.
+
+## [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. Parallel worktrees may also create repeated numbers; the full change key must use a specific description to distinguish the work.
 - `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` 各自递增自己的编号，跨前缀同号允许共存。并行工作树也可能产生重复编号，必须用完整 change key 的描述区分业务内容。
 - `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/bin/cc-devflow-cli.js

@@ -89,6 +89,7 @@ Query options:
   --cwd <path>         Project path used for devflow artifact lookup
   --change <id>        Change id, for example REQ-123
   --change-id <id>     Alias for --change
+  --change-key <key>   Full change key, for example REQ-123-my-feature
 
 Examples:
   cc-devflow init
@@ -101,6 +102,7 @@ Examples:
   cc-devflow config resolve --cwd /path/to/project --format policy
   cc-devflow query list
   cc-devflow query ship-readiness --cwd /path/to/project --change REQ-123
+  cc-devflow query progress --change REQ-123 --change-key REQ-123-my-feature
 `);
 }
 
@@ -449,6 +451,7 @@ function parseQueryArgs(args) {
   const parsed = {
     cwd: null,
     changeId: null,
+    changeKey: null,
     rest: []
   };
 
@@ -480,6 +483,16 @@ function parseQueryArgs(args) {
       continue;
     }
 
+    if (arg === '--change-key') {
+      parsed.changeKey = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--change-key=')) {
+      parsed.changeKey = arg.slice('--change-key='.length);
+      continue;
+    }
+
     parsed.rest.push(arg);
   }
 
@@ -490,7 +503,7 @@ async function runQueryCommand(args) {
   const [subcommand, ...rest] = args;
 
   if (!subcommand || subcommand === '--help' || subcommand === '-h') {
-    console.error('Use: cc-devflow query list OR cc-devflow query <id> --change <changeId> [--cwd <path>]');
+    console.error('Use: cc-devflow query list OR cc-devflow query <id> --change <changeId> [--change-key <key>] [--cwd <path>]');
     return 3;
   }
 
@@ -507,7 +520,8 @@ async function runQueryCommand(args) {
 
   const result = await runQuery(subcommand, {
     repoRoot: path.resolve(options.cwd || process.cwd()),
-    changeId: options.changeId
+    changeId: options.changeId,
+    changeKey: options.changeKey
   });
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

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` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 依靠描述区分业务内容；描述部分使用 kebab-case。