cc-devflow 4.5.4 → 4.5.6

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-020`
 - Source roadmap version: `roadmap.v3`
 
@@ -15,6 +15,13 @@
 - Frozen decisions:
   - export only the visible audit summary rows
   - CSV is the only format in this requirement
+- PRD brief:
+  - Problem statement: admins manually copy audit summaries into weekly reports
+  - Solution summary: CSV download action for currently visible audit summary rows
+  - User stories covered: `US-001`
+  - Implementation decisions: export visible rows only, CSV only
+  - Testing decisions: test through admin panel action and visible row data
+  - Out of scope: JSON export, scheduled reporting, shared reporting backend
 - Read first:
   - `design.md`
   - `src/admin/AuditSummaryPanel.tsx`

package/docs/examples/local-handoff/roadmap.json

@@ -0,0 +1,121 @@
+{
+  "version": 3,
+  "outputPolicy": {
+    "documentLanguage": "en"
+  },
+  "meta": {
+    "roadmapVersion": "roadmap.v2",
+    "skillVersion": "5.0.0",
+    "status": "active",
+    "lastUpdated": "2026-04-19",
+    "currentFocusStage": "Stage 2"
+  },
+  "context": {
+    "planningPosture": "",
+    "evidenceMaturity": "",
+    "canonicalTerms": [],
+    "durableDecisionSources": []
+  },
+  "evidence": [],
+  "route": {
+    "recommended": "",
+    "whyThisWinsNow": "",
+    "rejectedRoutes": [],
+    "firstSignal": "",
+    "killSignal": ""
+  },
+  "stages": [],
+  "items": [
+    {
+      "rmId": "RM-020",
+      "item": "Add an audit-log export summary download",
+      "stage": "Stage 2",
+      "priority": "P1",
+      "primaryCapability": "cap-audit-log-export",
+      "secondaryCapabilities": [],
+      "expectedSpecDelta": "codify local export summary truth",
+      "dependsOn": [],
+      "status": "Local handoff",
+      "req": "REQ-003",
+      "progress": "100%",
+      "backlog": {
+        "capabilityGap": "admins can export raw audit data but not a compact summary for review",
+        "evidence": "support escalations keep asking for a lightweight summary bundle",
+        "parallelWith": [],
+        "unknowns": "csv-only or csv-plus-markdown summary",
+        "nextDecision": "resume from local handoff once remote access returns",
+        "ready": true,
+        "whyNow": "the implementation and proof already exist, only the landing path is deferred",
+        "successSignal": "admins can download a concise audit summary without manual spreadsheet cleanup",
+        "entryConstraints": "stay local-only and avoid remote automation",
+        "openRisks": "handoff may age if schema changes before the next maintainer resumes",
+        "firstPlanningQuestion": "does the summary format need another review before remote landing?",
+        "requiredContextToLoad": "admin export screen, generated summary fixture, local handoff notes",
+        "whyReadyNow": "the requirement is already proven and only needs a clean resume point",
+        "parked": false,
+        "parkedReason": "",
+        "triggerToReopen": "",
+        "missingEvidence": ""
+      }
+    }
+  ],
+  "handoff": {
+    "readyForCcPlan": [
+      "RM-020"
+    ],
+    "parked": [],
+    "serialSpine": [
+      "RM-020"
+    ],
+    "parallelWaves": []
+  },
+  "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.v2",
+    "skillVersion": "4.4.1",
+    "currentFocusStage": "Stage 2"
+  },
+  "dependencyHandoff": {
+    "serialSpine": "RM-020",
+    "parallelReadyNextWave": "-",
+    "notesOnBlockers": "export work stays local-only until the next maintainer has remote access"
+  },
+  "lastSyncedAt": "2026-04-19"
+}

package/docs/examples/pdca-loop/BACKLOG.md

@@ -1,12 +1,14 @@
 # BACKLOG
 
+> Deprecated projection. Edit `roadmap.json` instead.
+
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v1`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 1`
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 ## Queue
 

package/docs/examples/pdca-loop/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`, `cc-act@1.8.1`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.7`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
 
 This folder shows one minimal but complete `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act` loop.
 
@@ -27,9 +27,9 @@ The sample requirement is:
 
 ## Artifact Map
 
-- `ROADMAP.md`: what `cc-roadmap` decided and why this item is first
-- `roadmap-tracking.json`: machine-readable roadmap/backlog truth that renders `ROADMAP.md` and `BACKLOG.md`
-- `BACKLOG.md`: capability-aware handoff that makes `RM-001` ready for `cc-plan`
+- `roadmap.json`: editable roadmap truth that renders the generated views
+- `ROADMAP.md`: generated view of what `cc-roadmap` decided and why this item is first
+- `BACKLOG.md`: deprecated capability-aware projection that makes `RM-001` ready for `cc-plan`
 - `changes/REQ-001-copy-invite-link/planning/design.md`: approved tiny design
 - `changes/REQ-001-copy-invite-link/planning/tasks.md`: executable task handoff
 - `changes/REQ-001-copy-invite-link/planning/task-manifest.json`: machine-readable execution truth

package/docs/examples/pdca-loop/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v1`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Status: `active`
 - Last updated: `2026-04-15`
 - Owner / decider: `product-owner`
@@ -122,7 +122,7 @@
 - What changed in this version: narrowed Stage 1 to the smallest visible sharing fix
 
 ## Implementation Tracking
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 <!-- roadmap-tracking:start -->
 | RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |
@@ -131,3 +131,17 @@
 | RM-002 | Add copied-state feedback to the share dialog | Stage 1 | P2 | cap-invite-links | - | extend invite-link feedback truth | RM-001 | Planned | - | 0% |
 | RM-004 | Collaboration analytics follow-up | - | - | - | - | - | - | - | - | - |
 <!-- roadmap-tracking:end -->
+
+
+## Technical Architecture
+
+```mermaid
+flowchart TD
+  roadmap_json["roadmap.json"]
+  roadmap_md["ROADMAP.md"]
+  backlog_md["BACKLOG.md (deprecated)"]
+  cc_plan["cc-plan"]
+  roadmap_json -->|renders| roadmap_md
+  roadmap_json -->|projects| backlog_md
+  roadmap_md -->|hands off| cc_plan
+```

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-001`
 - Design mode: `tiny-design`
 - Why this stays `tiny-design`: the patch is limited to an existing dialog and test file, with no API or data model changes
@@ -34,6 +34,23 @@
   - show a lightweight copied-state confirmation inside the current dialog
 - Upgrade trigger to `full-design`: if clipboard support requires new platform fallbacks, or if the patch spills into shared share-service contracts
 
+## PRD-Grade Brief
+
+- Problem statement: users can see the invite URL, but copying it still requires manual selection and creates avoidable share-flow friction.
+- Solution summary: users get a one-click copy action in the existing share dialog and see lightweight confirmation after the link is copied.
+- Actors / personas:
+  - workspace member sharing an invite
+- User stories:
+  - US-001: As a workspace member, I want to copy the invite link with one click, so that I can share it without manually selecting text.
+- Implementation decisions:
+  - Reuse the existing invite URL source and dialog props.
+  - Keep clipboard behavior inside the current share dialog surface.
+- Testing decisions:
+  - Test through the dialog behavior, not an internal helper.
+  - Existing share-dialog tests are the prior art.
+- Out of scope: new invite generation, role controls, analytics, or clipboard fallback redesign.
+- Further notes: if confirmation remains unclear, open a separate UX requirement.
+
 ## Validation
 
 - Primary check: targeted dialog test proves the button renders and copies the current invite URL
@@ -57,8 +74,16 @@
 - Scope scan: pass; no backend, no permission work
 - Ambiguity scan: pass; execution does not need to re-decide button placement or clipboard source
 - Feasibility scan: pass; existing dialog and tests already cover the target surface
+- PRD brief scan: pass; problem, story, implementation decision, testing decision, and out-of-scope are durable
+- Decision question scan: pass; `D1` approved the tiny-design copy-action boundary
 - Final recommendation: approved as `tiny-design`
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Existing dialog already renders the invite URL and the change stays inside one UI/test surface | Approve the tiny-design copy action | Tiny design copy action | Keep implementation inside the share dialog; do not add backend or permission work | answered |
+
 ## Approval
 
 - User approval status: approved

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json

@@ -9,7 +9,7 @@
   "sourceRoadmap": {
     "itemId": "RM-001",
     "roadmapVersion": "roadmap.v1",
-    "roadmapSkillVersion": "4.4.1",
+    "roadmapSkillVersion": "5.0.0",
     "sourceStage": "Stage 1",
     "successSignal": "Users can copy the invite link with one click",
     "killSignal": "The patch requires backend or permission changes",
@@ -22,11 +22,59 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.1",
+    "reqPlanSkillVersion": "3.7.7",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T10:05:00.000Z",
     "approvedBy": "user",
-    "basedOnOption": "Tiny design card"
+    "basedOnOption": "Tiny design card",
+    "requirementBrief": {
+      "problemStatement": "Users can see the invite URL, but copying it still requires manual selection.",
+      "solutionSummary": "Add a one-click copy action with lightweight confirmation inside the existing share dialog.",
+      "actors": ["workspace member sharing an invite"],
+      "userStories": [
+        {
+          "id": "US-001",
+          "actor": "workspace member",
+          "want": "copy the invite link with one click",
+          "benefit": "share it without manually selecting text",
+          "acceptance": ["Dialog behavior test proves the current invite URL is copied"]
+        }
+      ],
+      "edgeOrRecoveryStories": [],
+      "implementationDecisions": ["Reuse the existing invite URL source and dialog props"],
+      "testingDecisions": ["Test through the share dialog behavior, not an internal helper"],
+      "outOfScope": ["invite generation", "role controls", "analytics", "clipboard fallback redesign"],
+      "furtherNotes": ["Richer copied-state feedback is a separate UX requirement"]
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Existing dialog already renders the invite URL", "The patch stays inside one UI/test surface"],
+        "recommendation": "Approve the tiny-design copy action",
+        "options": [
+          {
+            "id": "A",
+            "label": "Tiny design copy action",
+            "recommended": true,
+            "completeness": "8/10",
+            "good": "Ships the visible user win with one dialog and one behavior test",
+            "costRisk": "Leaves richer feedback and clipboard fallback work for later"
+          },
+          {
+            "id": "B",
+            "label": "Full share-flow redesign",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "Could solve broader invite UX issues in one larger pass",
+            "costRisk": "Expands beyond the roadmap wedge and touches unrelated share contracts"
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do keeps implementation inside the share dialog and avoids backend or permission work",
+        "status": "answered"
+      }
+    ]
   },
   "currentTaskId": null,
   "activePhase": null,

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 
@@ -16,6 +16,13 @@
   - copy from the existing invite URL source
   - keep the patch inside the current dialog
   - leave richer feedback for a future requirement if needed
+- PRD brief:
+  - Problem statement: copying the visible invite URL still requires manual selection
+  - Solution summary: one-click copy action with lightweight confirmation
+  - User stories covered: `US-001`
+  - Implementation decisions: reuse existing invite URL source and dialog props
+  - Testing decisions: test through share dialog behavior
+  - Out of scope: invite generation, role controls, analytics, clipboard fallback redesign
 - Read first:
   - `design.md`
   - `src/features/share/ShareDialog.tsx`

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` advance as separate local sequences, so cross-prefix duplicates are valid. Parallel worktrees may still repeat numbers; the full change key, especially the description, distinguishes the work. 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` 分别维护自己的递增编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 的描述负责区分业务内容，旧小写目录只作为历史兼容读取。
 - `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。