cc-devflow 4.5.5 → 4.5.6

package/.claude/skills/cc-plan/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CC-Plan Skill Changelog
 
+## v3.7.7 - 2026-05-08
+
+- treat the full `REQ/FIX-<number>-<description>` change key as identity so duplicate numbers from parallel worktrees are valid
+- stop requiring local planning to resequence or rename changes solely because another worktree used the same numeric suffix
+- make runtime path resolution fail clearly when a bare `REQ/FIX-<number>` is ambiguous and no explicit `changeKey` was supplied
+
+## v3.7.6 - 2026-05-06
+
+- add a fixed Decision Question Protocol so user-facing planning gates use numbered questions, recommendations, options, impact, and STOP instead of free-form prose
+- record required user decisions in `planning/design.md` and `task-manifest.json.planningMeta.decisionQuestions`
+- update design, tiny-design, manifest, and example bindings for the new decision-question contract
+
 ## v3.7.5 - 2026-05-06
 
 - absorb the external TDD skill's interface-testability details into native planning: injected dependencies, returned results, concrete boundary operations, and small-interface/deep-implementation checks

package/.claude/skills/cc-plan/PLAYBOOK.md

@@ -19,7 +19,7 @@
 6. 机械决策自动落盘；taste decision 和 user challenge 必须显式交给用户拍板。
 7. 同 blast radius 内的完整边界优先做完，跨系统或无证据扩张才 defer。
 8. 具体执行计划默认测试先行；没有 Red/Green/Refactor 链、spec-style test name、公共测试 seam、行为断言、mock 边界或 TDD exception，不准交给 `cc-do`。
-9. 新 change 目录必须使用 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；旧小写目录只读兼容，不再作为新输出。
+9. 新 change 目录必须使用 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分；旧小写目录只读兼容，不再作为新输出。
 10. 原始需求跨多个独立子系统时，先拆回 roadmap / 多个 REQ/FIX；不要把一个大杂烩压成单个计划。
 11. `tiny-design` 仍然必须被批准，它只是短设计，不是跳过设计。
 12. 非 trivial 方案必须至少比较 `minimal viable` 和 `ideal architecture` 两种角色，小方案没有天然优先权。
@@ -32,6 +32,7 @@
 19. 退出前必须跑 Roadmap Sync Gate：`devflow/roadmap.json` 是真相源，`devflow/ROADMAP.md` 和 `devflow/BACKLOG.md` 只是投影；source RM 存在就回写，找不到才记录 no-op。
 20. PRD 的结构要吸收进 `planning/design.md`：用户视角的问题和方案、完整 user stories、实现决策、测试决策、out-of-scope 和 further notes；不要默认创建独立 `PRD.md`。
 21. 接口可测性必须在计划阶段解决：依赖尽量注入，结果尽量可返回和断言，系统边界 adapter 拆成具体操作，避免让测试用条件分支 mock 一个万能 fetcher。
+22. 需要用户判断时必须走固定 `D<N>` Decision Question：证据、推荐、2-3 个互斥选项、影响和 STOP 都要出现，答案写回 design / manifest。
 
 ## Required Outputs
 
@@ -53,7 +54,7 @@
 1. 一份 `planning/design.md` 讲清 clarification、方案、review 和 final gate。
 2. 一份 `planning/tasks.md` 讲清执行任务和 handoff。
 3. `planning/task-manifest.json` 只做机器真相源，不再重复人类叙事。
-4. 先固定 canonical change key：需求用 `REQ-*`，修复用 `FIX-*`，编号只在同前缀内取最大值后递增。
+4. 先固定 canonical change key：需求用 `REQ-*`，修复用 `FIX-*`，编号只在同前缀内取最大值后递增；并行 PR 已经产生同号时不强制重排，完整 key 的描述承担身份区分。
 5. 推荐方案获批前，不得生成 `planning/tasks.md`。
 6. `planning/tasks.md` 之前，`planning/design.md` 内的 review gate 必须闭合。
 7. 每个任务都要写清：
@@ -72,25 +73,26 @@
 13. `full-design` 必须包含 implementation decision horizon 和 error/rescue map；不适用时写清 N/A 理由。
 14. `planning/design.md` 必须包含 assumptions preview、ambiguity gate、source trust boundary、external conflict buckets 和 bounded review loop。
 15. `planning/design.md` 必须包含 PRD-grade brief：Problem Statement、Solution、actors / user stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。
-16. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
-17. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
-18. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
-19. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
-20. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
-21. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
-22. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
-23. Red 任务必须说明 public verification path：从同一公共接口或用户可见路径读回结果。直接查 DB / 内部状态只在该边界本身就是被测对象时允许。
-24. Green 任务必须写 minimality guard：只做当前红灯要求的最少实现，不预铺未来测试尚未要求的分支、状态或 API。
-25. Refactor 任务必须列候选坏味道：重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支，以及新代码暴露出的旧代码问题。
-26. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
-27. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
-28. Review gate 只拦会导致实现错误、执行卡住、范围越界、验证缺失的问题；文字偏好和 nice-to-have 只能作为 advisory。
+16. `planning/design.md` 必须包含 Decision Questions：哪些问题问过、推荐项、用户选择、影响、是否已写入任务。
+17. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
+18. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
+19. 行为变更任务必须按一个 observable behavior 一条 tracer bullet 链组织，不能先批量写红灯再批量实现。
+20. 回归测试不能 defer。修改既有行为且缺少覆盖时，必须先计划 regression test。
+21. Red 任务必须验证公共接口上的行为，不验证私有函数、内部调用次数或临时数据结构。
+22. Mock 只能放在系统边界；如果测试必须 mock 自己控制的模块，说明 seam 或接口设计还没压平。
+23. 找不到正确 seam 时，先计划 exploratory spike 或设计修正，不能用假红灯冒充 TDD。
+24. Red 任务必须说明 public verification path：从同一公共接口或用户可见路径读回结果。直接查 DB / 内部状态只在该边界本身就是被测对象时允许。
+25. Green 任务必须写 minimality guard：只做当前红灯要求的最少实现，不预铺未来测试尚未要求的分支、状态或 API。
+26. Refactor 任务必须列候选坏味道：重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支，以及新代码暴露出的旧代码问题。
+27. UI scope 要写 design completeness score 和 loading / empty / error / success / partial 状态。
+28. developer/operator-facing scope 要写 target persona、time to first value、magic moment 和 install / run / debug / upgrade 风险。
+29. Review gate 只拦会导致实现错误、执行卡住、范围越界、验证缺失的问题；文字偏好和 nice-to-have 只能作为 advisory。
 
 ## Approval Flow
 
 1. 先写 `Source Handoff` 和 requirement framing。
 2. 在 `planning/design.md` 里记录备选方案和推荐。
-3. 用户批准推荐方案后，再冻结正式设计。
+3. 用户批准推荐方案后，再冻结正式设计；批准必须来自固定 Decision Question 或明确用户指令。
 4. 在 `planning/design.md` 里完成 review loop 与 final gate。
 5. gate 通过后，再拆 `planning/tasks.md` 与 `planning/task-manifest.json`。
 

package/.claude/skills/cc-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-plan
-version: 3.7.5
+version: 3.7.7
 description: Use when a requirement, roadmap item, or bug needs scope clarification, design decisions, and executable task breakdown before coding starts.
 triggers:
   - 帮我规划这个需求
@@ -44,7 +44,8 @@ entry_gate:
   - "For non-trivial designs, compare named option roles: minimal viable, ideal architecture, and optional hybrid. Do not default to smallest unless it best serves the goal."
   - Plan executable work as Red/Green/Refactor by default; identify the first failing test before any production implementation task, or write an explicit TDD exception with replacement evidence.
   - For behavior changes, freeze the spec-style test name, one logical behavior, public verification path, and interface-testability decision before task split.
-  - Assign a canonical change key before writing artifacts; feature work must use `REQ-<number>-<description>`, and bug-fix work must use `FIX-<number>-<description>`. REQ and FIX use independent number sequences.
+  - When user judgment is required, ask with the fixed `cc-plan` Decision Question Protocol (`D<N>`, evidence, recommendation, 2-3 options, impact, STOP) instead of free-form prose.
+  - Assign a canonical change key before writing artifacts; feature work must use `REQ-<number>-<description>`, and bug-fix work must use `FIX-<number>-<description>`. REQ and FIX use independent local number sequences, and the full change key, including description, is the identity when parallel worktrees produce repeated numbers.
   - Do not generate planning/tasks.md, planning/task-manifest.json, or change-meta.json until the recommended design is approved.
   - Before exit, locate the source RM in `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`, or legacy `devflow/roadmap-tracking.json`; plan the progress sync instead of relying on chat memory.
 exit_criteria:
@@ -52,6 +53,7 @@ exit_criteria:
   - planning/tasks.md, planning/task-manifest.json, and change-meta.json are explicit enough that cc-do can continue without chat memory.
   - The task breakdown preserves test-first execution; failing-test tasks precede implementation tasks, refactor checkpoints are visible, and any TDD exception is justified.
   - "Testability decisions make the public seam natural: small interface, deep implementation, injected boundary dependencies, returned results where practical, and boundary mocks only where the system genuinely leaves the repo."
+  - Required user decisions were asked through numbered decision questions and recorded in `planning/design.md` / `task-manifest.json` instead of left in chat.
   - The source roadmap item has been synchronized to the frozen planning state, or `planning/design.md` and `change-meta.json` record why no roadmap update is valid.
   - 'Only one next step remains: enter cc-do.'
 reroutes:
@@ -138,6 +140,8 @@ PRD 的好处要进入 `planning/design.md`，不要变成第 5 个文件。`cc-
 
 `REQ` 和 `FIX` 是两个独立编号空间。选择下一个编号时，只扫描同前缀的现有目录：新 `REQ` 只看 `devflow/changes/REQ-*` 的最大编号，新 `FIX` 只看 `devflow/changes/FIX-*` 的最大编号。`REQ-038-*` 与 `FIX-038-*` 可以同时存在，不因为另一个前缀用了相同数字就跳号、改名或合并编号。编号位宽沿用项目现状。
 
+编号不是合并后的全局身份。工作树开 PR 的并行模式下，多个 `REQ-038-*` 或多个 `FIX-038-*` 也可能同时存在；合并后不因为同号而强制改名、跳号或重排历史。完整 `<prefix>-<number>-<description>` 才是 canonical change key，描述必须具体到能区分业务内容。只有用户明确要求统一编号时，才做批量重编号。
+
 描述部分使用 kebab-case，可以保留中文词组，但不允许丢掉大写 `REQ` / `FIX` 前缀。不要再创建 `req-123-...`、`bug-123-...`、纯描述目录或没有编号的目录。旧的小写目录只能作为历史兼容读取目标，不作为新 planning 输出。
 
 ## Autoplan Principles
@@ -240,6 +244,52 @@ PRD 的好处要进入 `planning/design.md`，不要变成第 5 个文件。`cc-
 5. 具体场景优先于抽象概念。每个关键边界至少用一个真实 codepath、user flow、operator flow 或 failure path 压测。
 6. 只有满足 hard to reverse、surprising without context、real trade-off 三个条件的决策，才建议沉淀为 capability spec delta 或 roadmap/backlog decision note；否则留在本次 design decision log。
 
+## Decision Question Protocol
+
+`cc-plan` 不是自由聊天。只在用户答案会改变设计、任务或交付边界时提问；能从 repo evidence、roadmap handoff、spec、测试或 git history 确认的，不问用户。
+
+必须使用固定 `D<N>` 决策问题，而不是临场自由发挥。第一个问题是 `D1`，之后递增。每次只问一个决策点，并在问题后 STOP，等待用户回答；没有回答前不得继续写 `planning/tasks.md`、`task-manifest.json` 或 `change-meta.json`。
+
+触发点只允许这些 gate：
+
+1. `planning-mode`：`clarify-first` / `tiny-design` / `full-design` 无法由证据直接决定。
+2. `ambiguity-blocker`：WHAT / WHY ambiguity gate 阻塞，且缺口不能从代码或文档补齐。
+3. `approach-approval`：需要用户批准 `minimal viable` / `ideal architecture` / `hybrid` 中的推荐方案。
+4. `taste-or-user-challenge`：推荐方案挑战用户原始方向，或属于品味 / 取舍判断。
+5. `final-design-approval`：`planning/design.md` 已闭合 review gate，准备生成执行任务。
+
+固定格式：
+
+```text
+D<N> - <decision title>
+Planning object: <REQ/FIX/RM id, branch, or change key>
+Known evidence: <repo / roadmap / code / test facts that constrain the choice>
+Decision needed: <the downstream design or task split this answer changes>
+Recommendation: <A/B/C> because <one concrete reason>
+Completeness: A=<score>/10, B=<score>/10, C=<score>/10
+Options:
+A) <label> (recommended)
+  Good: <concrete upside tied to this requirement>
+  Cost/Risk: <honest cost, risk, or what it leaves out>
+B) <label>
+  Good: <concrete upside tied to this requirement>
+  Cost/Risk: <honest cost, risk, or what it leaves out>
+C) <label, optional>
+  Good: <concrete upside tied to this requirement>
+  Cost/Risk: <honest cost, risk, or what it leaves out>
+Impact: <what cc-do will do differently after this answer>
+STOP: wait for the user answer before continuing.
+```
+
+规则：
+
+1. 选项必须是 2-3 个互斥选择；不要输出开放式“大段想法”让用户自己整理。
+2. 必须有推荐项，且推荐项标注 `(recommended)`；机械选择可以 auto-decide，但必须写进 decision log。
+3. 如果选项不是覆盖度差异，而是方向差异，`Completeness` 写 `different-kind` 并说明为什么不能打分。
+4. 每个选项都要说清 `Good` 与 `Cost/Risk`。没有代价的确认不是选择，应改为执行说明或 final approval。
+5. 用户回答后，把结果写入 `planning/design.md` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`。聊天不是真相源。
+6. 如果连续两个问题都被用户纠正为“你应该能自己判断”，停止追问，回到 evidence sweep，修正问题选择标准。
+
 ## Session Protocol
 
 1. 先探索上下文，再写结论。
@@ -249,6 +299,7 @@ PRD 的好处要进入 `planning/design.md`，不要变成第 5 个文件。`cc-
    - `full-design` 的方案必须至少包含 `minimal viable` 和 `ideal architecture` 两个角色。
    - 两个角色权重相等；小方案不是默认答案，理想架构也不是默认过度设计。
    - 只有一个方案成立时，必须写清其它方案为何被排除。
+   - 用户批准必须走 `Decision Question Protocol`，不能用自由问句代替。
 5. 推荐方案没有得到用户明确批准前，不允许生成 `planning/tasks.md`。
 6. 批准后先判断这次用 `tiny-design` 还是 `full-design`。
 7. 把批准后的唯一方案冻结进 `planning/design.md`。

package/.claude/skills/cc-plan/assets/DESIGN_TEMPLATE.md

@@ -167,6 +167,14 @@
 - Frozen decisions:
 - Deferred questions:
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | planning-mode / ambiguity-blocker / approach-approval / taste-or-user-challenge / final-design-approval |  |  |  |  | asked / answered / auto-decided |
+
+> 只记录真正改变设计或任务的用户判断。机械选择可以 auto-decide，但必须说明证据和影响。
+
 ## Design
 
 - Modules touched:
@@ -318,6 +326,7 @@
 - External conflict scan:
 - Ambiguity gate:
 - Review loop status:
+- Decision question scan:
 - UI / interaction review summary:
 - DX / operator review summary:
 - Test-first readiness:

package/.claude/skills/cc-plan/assets/TASK_MANIFEST_TEMPLATE.json

@@ -28,7 +28,7 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.5",
+    "reqPlanSkillVersion": "3.7.6",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T12:00:00.000Z",
     "approvedBy": "user",
@@ -66,7 +66,36 @@
       "repeatedConcernFingerprints": [],
       "stallReason": "",
       "rerouteIfStalled": "ask-user"
-    }
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": [],
+        "recommendation": "Option A",
+        "options": [
+          {
+            "id": "A",
+            "label": "Minimal viable",
+            "recommended": true,
+            "completeness": "7/10",
+            "good": "",
+            "costRisk": ""
+          },
+          {
+            "id": "B",
+            "label": "Ideal architecture",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "",
+            "costRisk": ""
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do follows the approved implementation surface and task split",
+        "status": "answered"
+      }
+    ]
   },
   "sourceEvidence": [
     {

package/.claude/skills/cc-plan/assets/TINY_DESIGN_TEMPLATE.md

@@ -180,6 +180,7 @@
 - External conflict scan:
 - Ambiguity gate:
 - Review loop status:
+- Decision question scan:
 - Test-first readiness:
 - Review calibration:
 - Final recommendation:
@@ -192,6 +193,12 @@
 - Stall reason:
 - Reroute if stalled:
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | planning-mode / ambiguity-blocker / approach-approval / taste-or-user-challenge / final-design-approval |  |  |  |  | asked / answered / auto-decided |
+
 ## Approval
 
 - User approval status:

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

@@ -16,7 +16,7 @@
 12. 同 blast radius 内的完整边界默认纳入，defer 必须写入 `NOT in scope` 和原因。
 13. 如果推荐方案挑战用户原始方向，必须标成 `user challenge`，不能自动改写用户意图。
 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` 是独立编号空间，只在同前缀内递增，跨前缀同号允许共存。
+15. 新 change 目录必须是 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`，不能用小写 `req-*` / `bug-*` 或纯描述目录；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成同前缀同号时，完整 change key 靠描述区分业务内容。
 16. 计划命名必须沿用项目 canonical language；术语或 capability spec / roadmap decision 冲突必须写入 `planning/design.md`，不能在任务里发明第二套语言。
 17. 行为变更任务必须按 tracer bullet 垂直切片组织：一个可观察行为对应一组 Red/Green/Refactor 任务。
 18. Red 任务必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实 seam 证明行为缺失。
@@ -28,6 +28,8 @@
 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`。
+27. 需要用户判断时必须使用固定 Decision Question：`D<N>`、证据、推荐、2-3 个互斥选项、影响和 STOP 都必须出现；禁止用自由问句代替审批 gate。
+28. 所有用户决策必须写入 `planning/design.md` 的 `Decision Questions`，并同步到 `task-manifest.json.planningMeta.decisionQuestions`，不能只留在聊天里。
 
 ## Design Modes
 
@@ -73,6 +75,21 @@
 不要把计划拆成水平层：一批测试、一批服务、一批 UI。每个切片完成后都应该能证明一个真实行为。
 也不要把一批 Red 一次性写完再批量实现。每条 tracer bullet 只证明一个可观察行为，Green 只做当前红灯要求的最小实现；下一条 Red 可以吸收上一轮学到的事实，但不能越过冻结边界。
 
+## Decision Question Fields
+
+每个需要用户判断的 gate 至少记录：
+
+- questionId：`D1` / `D2` / ...
+- gate：`planning-mode` / `ambiguity-blocker` / `approach-approval` / `taste-or-user-challenge` / `final-design-approval`
+- knownEvidence
+- recommendation
+- options
+- userChoice
+- impact
+- status：`asked` / `answered` / `auto-decided`
+
+如果选项不是覆盖度差异，completeness 使用 `different-kind`，并写清不能打分的原因。
+
 ## Review Gate
 
 `planning/design.md` 至少完成：
@@ -100,7 +117,8 @@
 21. Bounded review loop
 22. NOT in scope
 23. Test-first readiness
-24. Final recommendation
+24. Decision questions recorded
+25. Final recommendation
 
 如有 UI scope，再补 design review 结论。
 如有 developer-facing scope，再补 DX review 结论。

package/CHANGELOG.md

@@ -9,6 +9,18 @@ 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

package/README.md

@@ -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. `REQ` and `FIX` numbers advance independently, so the same number may exist in both prefixes.
+- 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

@@ -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 修复。`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号允许共存。
+- 新 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-...` 表示缺陷修复；`REQ` 和 `FIX` 是独立编号空间；描述部分使用 kebab-case。
+- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；`REQ` 和 `FIX` 各自递增自己的编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 依靠描述区分业务内容；描述部分使用 kebab-case。

package/docs/examples/example-bindings.json

@@ -2,7 +2,7 @@
   "updatedAt": "2026-05-06",
   "skills": {
     "cc-roadmap": "5.0.0",
-    "cc-plan": "3.7.5",
+    "cc-plan": "3.7.7",
     "cc-investigate": "1.2.2",
     "cc-do": "1.6.2",
     "cc-check": "1.10.1",

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.5`, `cc-do@1.6.2`, `cc-check@1.10.1`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.7`, `cc-do@1.6.2`, `cc-check@1.10.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging
@@ -120,6 +120,13 @@
 - Deferred questions:
   - whether partial success needs an explicit rollback option
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Best-effort upload would let duplicate, invalid, and seat-limit semantics drift during execution | Choose Option B and freeze a rule matrix first | Option B | Keep execution blocked until row outcomes are modeled | answered |
+| D2 | ambiguity-blocker | Duplicate and seat-limit outcomes are still not explicit enough for tests or audit mapping | Answer the row-outcome matrix before task generation | pending | `cc-do` must not start implementation until this is answered | asked |
+
 ## Design
 
 - Modules touched:
@@ -169,6 +176,7 @@
 - Feasibility scan: pass
 - Source alignment: pass; roadmap still prioritizes trust over speed
 - PRD brief scan: pass for actors and stories; blocked on duplicate and seat-limit semantics
+- Decision question scan: blocked; `D2` is still unanswered
 - UI / interaction review summary: result states are acceptable if semantics are frozen first
 - DX review summary: execution still needs a single row-outcome matrix
 - Auto-decided items:

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/task-manifest.json

@@ -6,7 +6,7 @@
   "requirementId": "REQ-002",
   "requirementVersion": "REQ-002.v2",
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.5",
+    "reqPlanSkillVersion": "3.7.7",
     "designVersion": "design.v2",
     "approvedAt": null,
     "approvedBy": null,
@@ -44,7 +44,63 @@
       "testingDecisions": ["Test row semantics through bulk-import rules and the admin upload flow"],
       "outOfScope": ["enterprise SCIM provisioning", "background job redesign", "rollback wizard for partial success"],
       "furtherNotes": ["Design remains blocked until duplicate and seat-limit semantics are approved"]
-    }
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Best-effort upload would hide duplicate, invalid, and seat-limit semantics", "Audit mapping depends on deterministic row outcomes"],
+        "recommendation": "Choose Option B and freeze a rule matrix first",
+        "options": [
+          {
+            "id": "A",
+            "label": "Front-end-only CSV upload",
+            "recommended": false,
+            "completeness": "5/10",
+            "good": "Fastest prototype and reuses the existing single-invite API",
+            "costRisk": "Lets hidden backend edge cases define user-visible semantics"
+          },
+          {
+            "id": "B",
+            "label": "Rule matrix first",
+            "recommended": true,
+            "completeness": "9/10",
+            "good": "Makes billing, duplicate, invalid, and audit behavior reviewable",
+            "costRisk": "Requires one more planning pass before execution can start"
+          }
+        ],
+        "userChoice": "B",
+        "impact": "cc-do stays blocked until row outcomes are modeled",
+        "status": "answered"
+      },
+      {
+        "questionId": "D2",
+        "gate": "ambiguity-blocker",
+        "knownEvidence": ["Duplicate and seat-limit outcomes are still not explicit enough for tests", "Audit entries must match visible row outcomes"],
+        "recommendation": "Answer the row-outcome matrix before task generation",
+        "options": [
+          {
+            "id": "A",
+            "label": "Block execution until matrix is explicit",
+            "recommended": true,
+            "completeness": "10/10",
+            "good": "Prevents cc-do from inventing semantics during implementation",
+            "costRisk": "Requires user/product input before coding can continue"
+          },
+          {
+            "id": "B",
+            "label": "Let implementation choose defaults",
+            "recommended": false,
+            "completeness": "4/10",
+            "good": "Starts coding sooner with fewer planning minutes",
+            "costRisk": "Creates invisible product decisions inside implementation tasks"
+          }
+        ],
+        "userChoice": null,
+        "impact": "No executable task manifest should be approved until this is answered",
+        "status": "asked"
+      }
+    ]
   },
   "currentTaskId": null,
   "activePhase": null,

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-010`
 - Source roadmap version: `roadmap.v2`
 

package/docs/examples/local-handoff/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.5`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
+- 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 example shows verified work that is **ready to move forward**, but `cc-act` still chooses `local-handoff`.
 

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

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-003`
 - Design mode: `tiny-design`
 - Why this stays `tiny-design`: the patch adds one export action inside the existing admin audit UI without changing data contracts
@@ -74,8 +74,15 @@
 - Ambiguity scan: pass
 - Feasibility scan: pass
 - PRD brief scan: pass; the export story and scope boundaries are explicit
+- Decision question scan: pass; `D1` approved the tiny-design CSV-export 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 admin panel already owns visible summary rows and the change does not need a reporting backend | Approve the tiny-design CSV export | Tiny design CSV export | Export only visible rows from the current panel; do not create reporting contracts | answered |
+
 ## Approval
 
 - User approval status: approved