cc-devflow 4.5.4 → 4.5.5

package/docs/examples/pdca-loop/roadmap.json

@@ -0,0 +1,191 @@
+{
+  "version": 3,
+  "outputPolicy": {
+    "documentLanguage": "en"
+  },
+  "meta": {
+    "roadmapVersion": "roadmap.v1",
+    "skillVersion": "5.0.0",
+    "status": "active",
+    "lastUpdated": "2026-04-19",
+    "currentFocusStage": "Stage 1"
+  },
+  "context": {
+    "planningPosture": "",
+    "evidenceMaturity": "",
+    "canonicalTerms": [],
+    "durableDecisionSources": []
+  },
+  "evidence": [],
+  "route": {
+    "recommended": "",
+    "whyThisWinsNow": "",
+    "rejectedRoutes": [],
+    "firstSignal": "",
+    "killSignal": ""
+  },
+  "stages": [],
+  "items": [
+    {
+      "rmId": "RM-001",
+      "item": "Add one-click copy action to the share dialog",
+      "stage": "Stage 1",
+      "priority": "P1",
+      "primaryCapability": "cap-invite-links",
+      "secondaryCapabilities": [],
+      "expectedSpecDelta": "tighten invite-link copy truth",
+      "dependsOn": [],
+      "status": "In review",
+      "req": "REQ-001",
+      "progress": "100%",
+      "backlog": {
+        "capabilityGap": "share dialog exposes invite URL but not direct copy action",
+        "evidence": "repeated support friction",
+        "parallelWith": [],
+        "unknowns": "copied-state feedback shape",
+        "nextDecision": "freeze tiny design and execute",
+        "ready": true,
+        "whyNow": "it removes the first visible collaboration friction in the beta flow",
+        "successSignal": "users can copy the invite link with one click",
+        "entryConstraints": "no backend changes, no share dialog redesign",
+        "openRisks": "clipboard failure copy may still need follow-up UX",
+        "firstPlanningQuestion": "can this stay a tiny-design patch without changing contracts?",
+        "requiredContextToLoad": "current share dialog, current invite URL source, existing tests",
+        "whyReadyNow": "the ask is narrow, the evidence is real, and the dependency surface is already known",
+        "parked": false,
+        "parkedReason": "",
+        "triggerToReopen": "",
+        "missingEvidence": ""
+      }
+    },
+    {
+      "rmId": "RM-002",
+      "item": "Add copied-state feedback to the share dialog",
+      "stage": "Stage 1",
+      "priority": "P2",
+      "primaryCapability": "cap-invite-links",
+      "secondaryCapabilities": [],
+      "expectedSpecDelta": "extend invite-link feedback truth",
+      "dependsOn": [
+        "RM-001"
+      ],
+      "status": "Planned",
+      "req": "",
+      "progress": "0%",
+      "backlog": {
+        "capabilityGap": "invite links lack durable copied-state feedback after action completion",
+        "evidence": "likely useful after RM-001",
+        "parallelWith": [],
+        "unknowns": "toast vs inline state",
+        "nextDecision": "decide after first patch ships",
+        "ready": false,
+        "whyNow": "",
+        "successSignal": "",
+        "entryConstraints": "",
+        "openRisks": "",
+        "firstPlanningQuestion": "",
+        "requiredContextToLoad": "",
+        "whyReadyNow": "",
+        "parked": false,
+        "parkedReason": "",
+        "triggerToReopen": "",
+        "missingEvidence": ""
+      }
+    },
+    {
+      "rmId": "RM-004",
+      "item": "Collaboration analytics follow-up",
+      "stage": "",
+      "priority": "",
+      "primaryCapability": "",
+      "secondaryCapabilities": [],
+      "expectedSpecDelta": "",
+      "dependsOn": [],
+      "status": "",
+      "req": "",
+      "progress": "",
+      "backlog": {
+        "capabilityGap": "",
+        "evidence": "",
+        "parallelWith": [],
+        "unknowns": "",
+        "nextDecision": "",
+        "ready": false,
+        "whyNow": "",
+        "successSignal": "",
+        "entryConstraints": "",
+        "openRisks": "",
+        "firstPlanningQuestion": "",
+        "requiredContextToLoad": "",
+        "whyReadyNow": "",
+        "parked": true,
+        "parkedReason": "collaboration analytics is premature before Stage 1 and 2 prove usage",
+        "triggerToReopen": "repeated invite usage after beta activation",
+        "missingEvidence": "stable collaboration volume"
+      }
+    }
+  ],
+  "handoff": {
+    "readyForCcPlan": [
+      "RM-001"
+    ],
+    "parked": [
+      "RM-004"
+    ],
+    "serialSpine": [
+      "RM-001 -> RM-002"
+    ],
+    "parallelWaves": [
+      "none until RM-001 proves the copy action shape"
+    ]
+  },
+  "architecture": {
+    "diagramType": "flowchart",
+    "nodes": [
+      {
+        "id": "roadmap_json",
+        "label": "roadmap.json"
+      },
+      {
+        "id": "roadmap_md",
+        "label": "ROADMAP.md"
+      },
+      {
+        "id": "backlog_md",
+        "label": "BACKLOG.md (deprecated)"
+      },
+      {
+        "id": "cc_plan",
+        "label": "cc-plan"
+      }
+    ],
+    "edges": [
+      {
+        "from": "roadmap_json",
+        "to": "roadmap_md",
+        "label": "renders"
+      },
+      {
+        "from": "roadmap_json",
+        "to": "backlog_md",
+        "label": "projects"
+      },
+      {
+        "from": "roadmap_md",
+        "to": "cc_plan",
+        "label": "hands off"
+      }
+    ]
+  },
+  "backlogMeta": {
+    "roadmapVersion": "roadmap.v1",
+    "skillVersion": "4.4.1",
+    "currentFocusStage": "Stage 1"
+  },
+  "dependencyHandoff": {
+    "serialSpine": "RM-001 -> RM-002",
+    "parallelReadyNextWave": "none until RM-001 proves the copy action shape",
+    "notesOnBlockers": "RM-002 should reuse the final interaction contract from RM-001, not race it"
+  },
+  "lastSyncedAt": "2026-04-19"
+}

package/docs/examples/scripts/check-example-bindings.sh

@@ -67,7 +67,7 @@ while IFS= read -r encoded; do
   review_dir="$change_dir/review"
   handoff_dir="$change_dir/handoff"
 
-  for file in "$readme" "$root/ROADMAP.md" "$root/BACKLOG.md" "$root/roadmap-tracking.json" "$planning_dir/design.md" "$planning_dir/tasks.md" "$planning_dir/task-manifest.json"; do
+  for file in "$readme" "$root/ROADMAP.md" "$root/BACKLOG.md" "$root/roadmap.json" "$planning_dir/design.md" "$planning_dir/tasks.md" "$planning_dir/task-manifest.json"; do
     if [[ ! -f "$file" ]]; then
       echo "Example $example_id is missing required file: $file" >&2
       exit 1
@@ -75,14 +75,17 @@ while IFS= read -r encoded; do
   done
 
   assert_contains "$root/ROADMAP.md" "- Skill version: \`$ROADMAP_VERSION\`"
-  assert_contains "$root/ROADMAP.md" "- Tracking source: \`roadmap-tracking.json\`"
+  assert_contains "$root/ROADMAP.md" "- Roadmap state source: \`roadmap.json\`"
+  assert_contains "$root/ROADMAP.md" "## Technical Architecture"
+  assert_contains "$root/ROADMAP.md" "\`\`\`mermaid"
   assert_contains "$root/BACKLOG.md" "- Skill version: \`$ROADMAP_VERSION\`"
-  assert_contains "$root/BACKLOG.md" "- Tracking source: \`roadmap-tracking.json\`"
+  assert_contains "$root/BACKLOG.md" "> Deprecated projection. Edit \`roadmap.json\` instead."
+  assert_contains "$root/BACKLOG.md" "- Roadmap state source: \`roadmap.json\`"
   assert_contains "$root/BACKLOG.md" "| RM-ID | Title | Source Stage | Priority | Primary Capability | Secondary Capabilities | Capability Gap | Expected Spec Delta | Evidence | Depends On | Parallel With | Unknowns | Next Decision | Ready |"
   assert_contains "$root/BACKLOG.md" "## Ready For Req-Plan"
   assert_contains "$root/BACKLOG.md" "  - Primary Capability:"
   assert_contains "$root/BACKLOG.md" "  - Expected spec delta:"
-  jq -er '.version == 2 and (.items | length) > 0 and (.backlogMeta | type == "object") and (.dependencyHandoff | type == "object") and any(.items[]; .backlog != null)' "$root/roadmap-tracking.json" >/dev/null
+  jq -er '.version == 3 and (.items | length) > 0 and (.meta | type == "object") and (.handoff | type == "object") and (.architecture.nodes | length) > 0 and any(.items[]; .backlog != null)' "$root/roadmap.json" >/dev/null
   assert_contains "$planning_dir/design.md" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
   assert_contains "$planning_dir/tasks.md" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
 

package/docs/guides/getting-started.md

@@ -83,7 +83,7 @@ Use the skills in this order:
 
 Typical outputs:
 
-- `cc-roadmap` writes `devflow/ROADMAP.md` and `devflow/BACKLOG.md`; helper sync can also maintain `devflow/roadmap-tracking.json` as the shared roadmap/backlog truth source
+- `cc-roadmap` writes `devflow/roadmap.json` as the editable roadmap truth, then generates `devflow/ROADMAP.md` and deprecated `devflow/BACKLOG.md`
 - `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
 - `cc-plan` writes `planning/design.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
 - `cc-investigate` writes `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
@@ -94,7 +94,7 @@ Capability truth lives in `devflow/specs/`.
 Change truth lives in `devflow/changes/<change>/`.
 
 - Keep `INDEX.md` plus capability markdown under `devflow/specs/`.
-- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes; old lowercase directories are compatibility reads only.
+- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` are separate number sequences; old lowercase directories are compatibility reads only.
 - Keep `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`.
 - Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 

package/docs/guides/getting-started.zh-CN.md

@@ -83,7 +83,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 
 常见产物：
 
-- `cc-roadmap` 产出 `devflow/ROADMAP.md` 和 `devflow/BACKLOG.md`；如果使用内置同步脚本，还会维护 `devflow/roadmap-tracking.json` 作为 roadmap/backlog 的共享真相源
+- `cc-roadmap` 产出可编辑真相 `devflow/roadmap.json`，再生成 `devflow/ROADMAP.md` 和 deprecated `devflow/BACKLOG.md`
 - `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
 - `cc-plan` 产出 `planning/design.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
 - `cc-investigate` 产出 `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
@@ -93,7 +93,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 durable truth 分两层：
 
 - `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
-- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；旧小写目录只作为历史兼容读取。
+- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，旧小写目录只作为历史兼容读取。
 - `devflow/changes/<change>/`：变更真相，保留 `change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、可选 `team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一的最终 handoff 文件。
 - worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 

package/lib/compiler/__tests__/skills-registry.test.js

@@ -195,7 +195,7 @@ describe('Skills Registry Generator', () => {
       );
     });
 
-    test('should publish roadmap outputs under devflow', async () => {
+    test('should publish unified roadmap state outputs under devflow', async () => {
       const { generateSkillsRegistryV2 } = require('../skills-registry');
 
       const result = await generateSkillsRegistryV2('.claude/skills');
@@ -204,14 +204,28 @@ describe('Skills Registry Generator', () => {
       expect(roadmap).toBeDefined();
       expect(roadmap.writes).toEqual(
         expect.arrayContaining([
-          expect.objectContaining({ path: 'devflow/ROADMAP.md' }),
-          expect.objectContaining({ path: 'devflow/BACKLOG.md' })
+          expect.objectContaining({
+            path: 'devflow/roadmap.json',
+            durability: 'durable',
+            required: true
+          }),
+          expect.objectContaining({
+            path: 'devflow/ROADMAP.md',
+            durability: 'durable',
+            required: true
+          }),
+          expect.objectContaining({
+            path: 'devflow/BACKLOG.md',
+            durability: 'durable',
+            required: false
+          })
         ])
       );
       expect(roadmap.writes).not.toEqual(
         expect.arrayContaining([
           expect.objectContaining({ path: 'ROADMAP.md' }),
           expect.objectContaining({ path: 'BACKLOG.md' }),
+          expect.objectContaining({ path: 'devflow/roadmap-tracking.json', required: true }),
           expect.objectContaining({ path: 'devflow/roadmap/roadmap.md' }),
           expect.objectContaining({ path: 'devflow/roadmap/backlog.md' })
         ])

package/lib/skill-runtime/__tests__/cli-bootstrap.integration.test.js

@@ -229,6 +229,11 @@ describe('cc-devflow cli distribution bootstrap', () => {
     );
     expect(codexRoadmapSkill.data.writes).toEqual(
       expect.arrayContaining([
+        expect.objectContaining({
+          path: 'devflow/roadmap.json',
+          durability: 'durable',
+          required: true
+        }),
         expect.objectContaining({
           path: 'devflow/ROADMAP.md',
           durability: 'durable',
@@ -237,10 +242,13 @@ describe('cc-devflow cli distribution bootstrap', () => {
         expect.objectContaining({
           path: 'devflow/BACKLOG.md',
           durability: 'durable',
-          required: true
+          required: false
         })
       ])
     );
+    expect(codexRoadmapSkill.data.writes).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ path: 'devflow/roadmap-tracking.json', required: true })])
+    );
   });
 
   test('adapt mirrors Codex skills without baking project YAML output policy', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.5.4",
+    "version": "4.5.5",
     "description": "Multi-platform CLI and skill pack for agent coding",
     "main": "bin/cc-devflow.js",
     "bin": {