cc-devflow 4.5.3 → 4.5.5

package/.claude/skills/cc-check/assets/REPORT_CARD_TEMPLATE.json

@@ -13,10 +13,17 @@
     "status": "blocked",
     "failureOwnership": [
       {
+        "errorName": "MissingSpecReviewProof",
         "failure": "missing spec review proof",
         "classification": "in-branch",
+        "owner": "branch",
         "touchedByDiff": true,
+        "artifactRefs": [
+          "planning/task-manifest.json",
+          "review/report-card.json"
+        ],
         "evidence": "planning/task-manifest.json tasks[T002].reviews.spec is empty",
+        "rescueAction": "record spec review proof for T002 or reroute to cc-do",
         "action": "reroute-cc-do",
         "status": "open"
       }
@@ -107,6 +114,16 @@
       "issues": [],
       "skipReason": "template example is not a UI browser QA scenario"
     },
+    "humanUat": {
+      "status": "skipped",
+      "required": false,
+      "scenario": "",
+      "tester": "",
+      "evidence": [],
+      "failure": "",
+      "reroute": "none",
+      "skipReason": "not required for this template scenario"
+    },
     "architectureFollowUps": [
       {
         "summary": "Add the missing public test seam before widening coverage",
@@ -183,6 +200,7 @@
           "summary": "T002 spec review proof is missing",
           "evidence": "planning/task-manifest.json tasks[T002].reviews.spec is empty",
           "action": "reroute-cc-do",
+          "rescueAction": "record spec review proof for T002 or return to cc-do",
           "triageStatus": "clarification-needed",
           "confidenceScore": 9,
           "fingerprint": "task-review:T002:missing-spec-review",

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

@@ -1,5 +1,17 @@
 # CC-Do Skill Changelog
 
+## v1.6.2 - 2026-05-06
+
+- absorb the external TDD skill's execution details into native `cc-do`: spec-style test names, one logical behavior per Red, and public verification paths
+- strengthen Green evidence with minimality guards so implementation does not pre-build future unproven behavior
+- expand checkpoint recovery fields with interface-testability proof and concrete refactor candidates such as duplication, long methods, shallow modules, feature envy, primitive obsession, naming, and nested branches
+
+## v1.6.1 - 2026-04-29
+
+- reject parent/child touched-path overlaps when selecting parallel execution surfaces
+- report submodule touches separately so unrelated tasks are not serialized by mere `.gitmodules` presence
+- document quick-lane and wave scheduling gates so small tasks still leave checkpoint, verification, and handoff truth
+
 ## v1.6.0 - 2026-04-28
 
 - prohibit horizontal TDD execution by requiring one tracer bullet Red/Green/Refactor cycle per observable behavior

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

@@ -23,14 +23,15 @@
 
 ## Execution Loop
 
-1. 读取 `task-manifest.json`，先用 `scripts/select-ready-tasks.sh` 找出当前 ready tasks。
-2. 如果有多于一个 ready task，要先跑 `scripts/detect-file-conflicts.sh`；有共享触点或依赖关系就退回串行。
+1. 读取 `task-manifest.json`，先用 `scripts/select-ready-tasks.sh` 找出当前 ready tasks 和当前 wave。
+2. 如果有多于一个 ready task，要先跑 `scripts/detect-file-conflicts.sh`；有共享触点、父子路径触点或依赖关系就退回串行。
 3. 对每个要执行的 task，先用 `scripts/build-task-context.sh` 从 `planning/design.md`、`planning/tasks.md`、`planning/task-manifest.json` 组装上下文，再开始编码。
 4. 如果当前任务来自 `cc-investigate`，把 `planning/analysis.md` 当成上游合同，不准一边做一边重开调查。
 5. 进入 TDD 闭环：先红，再绿，再重构。
 6. 每个关键节点都写 runtime：失败测试、Green 通过、Refactor、Review 结论、阻塞原因。
 7. 任务实现后，先过 `spec review`，再过 `code review`，review 不通过就回到实现。
 8. 两道 review 门都通过后，才能把任务标成完成，并把结果留给 `cc-check`。
+9. quick lane 只允许减少叙事，不允许减少 current task、checkpoint、verification、handoff 和 review gates。
 
 ## Local Kit
 
@@ -52,10 +53,11 @@
 2. 确认红灯是预期失败，不是测试写错、fixture 缺失或环境没接上。
 3. 确认红灯通过公共 seam 证明行为缺失，而不是测私有函数、内部调用次数或临时结构。
 4. 确认 mock 只发生在系统边界；内部协作者不 mock。
-5. 只写让当前测试转绿的最小实现。
-6. 绿后才允许重构。
-7. 重构后必须保持绿。
-8. 测试没先红过，或红灯不是公共 seam 上的行为失败，就不能宣称这次变更受 TDD 保护。
+5. 确认测试名像规格说明，一个 Red 只证明一个逻辑行为，结果从公共验证路径读回。
+6. 只写让当前测试转绿的最小实现，不提前实现未来测试尚未要求的分支、状态或 API。
+7. 绿后才允许重构。
+8. 重构后必须保持绿，并说明处理了重复、长方法、浅模块、feature envy、primitive obsession、命名、三层以上分支或其它具体坏味道。
+9. 测试没先红过，或红灯不是公共 seam 上的行为失败，就不能宣称这次变更受 TDD 保护。
 
 ## TDD Exception Rule
 
@@ -83,9 +85,9 @@
 3. `red_seam_verified`: 红灯通过公共接口、调用方流程、CLI/API/UI 或真实边界进入系统
 4. `red_behavior_verified`: 测试断言用户或调用方可观察行为，不断言内部实现细节
 5. `mock_boundary_verified`: mock 只在系统边界，内部协作者没有被 mock
-6. `green_passed`: 当前任务实现转绿
+6. `green_passed`: 当前任务实现转绿，且实现只覆盖当前红灯要求的最小行为
 7. `refactor_done` 或 `refactor_not_needed`
-8. `refactor_green`: 重构后相关测试仍绿
+8. `refactor_green`: 重构后相关测试仍绿，且没有在 Red 状态做结构清理
 9. `spec_review_pass`
 10. `code_review_pass`
 
@@ -98,8 +100,9 @@
 1. 任务处于当前 active phase
 2. `dependsOn` 已全部满足
 3. 任务显式允许并行，例如 `[P]`
-4. `touches` / `files` 不冲突
-5. 每个 subagent 都拿到了自己的 task context
+4. `touches` / `files` 不冲突，且父路径 / 子路径也不重叠
+5. submodule touches 已被标出；触达 submodule 的任务不能默认拿普通 worktree 隔离
+6. 每个 subagent 都拿到了自己的 task context
 
 少一条，都按顺序执行。
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-do
-version: 1.6.0
+version: 1.6.2
 description: Use when implementing planned tasks, resuming interrupted work, applying a frozen investigation handoff, or landing review feedback after cc-plan or cc-investigate.
 triggers:
   - 开始做 T003
@@ -27,16 +27,23 @@ writes:
     durability: durable
     required: false
     when: execution mode uses delegated or team workers
+  - path: devflow/changes/<change-key>/meta/change-state.json
+    durability: durable
+    required: false
+    when: pause, resume, dispatch, or quick-lane state changes
 effects:
   - code changes
   - test changes
   - workspace scratch runtime updates
 entry_gate:
   - Read planning/design.md or planning/analysis.md, then planning/tasks.md, planning/task-manifest.json, change-meta.json, related capability specs, and the latest checkpoint before changing code.
-  - Select only ready tasks whose dependencies and file ownership are clear.
+  - Select only ready tasks whose dependencies, wave, touched paths, and file ownership are clear.
+  - Reject parallel execution when touched paths overlap by exact path or parent/child path; submodule touches must be isolated unless the task explicitly owns that submodule.
   - If the current task cannot be restated from canonical artifacts, run a context reset before coding.
+  - "Validate the current task's TDD shape before coding: spec-style test name, one logical behavior, public verification path, allowed boundary mocks, Green minimality guard, and refactor candidates."
 exit_criteria:
   - The current task has red/green evidence, public-seam test quality evidence, review evidence, and a resumable checkpoint trail.
+  - Red evidence proves one observable behavior through a public verification path; Green evidence shows only the minimal production change; Refactor evidence names the concrete smell removed or says why none was needed.
   - Execution leaves the next verifier enough runtime truth to judge the task without chat memory.
   - The honest next step is cc-check or an explicit reroute.
 reroutes:
@@ -136,34 +143,43 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实边界进入系统；只验证私有函数、内部调用次数、临时数据结构或 mock 自己控制的内部协作者，不算 TDD 证据。
 
+一个 Red 只证明一个逻辑行为。测试名要像规格说明，而不是实现步骤；结果要从同一类公共入口读回。直接查数据库、读内部状态、扫描临时文件或绕过 API 来证明行为，只在那个边界本身就是被测对象时成立。
+
 例外只能用于 throwaway prototype、纯生成文件、纯配置改动；例外必须写进 checkpoint 的 `tddException`，包含原因、风险和替代验证命令。测试第一次就绿，说明测试没有证明新行为，必须修测试而不是继续写生产代码。
 
 禁止水平切片：不要先写一批测试，再写一批实现。每次只推进一个 tracer bullet：一个可观察行为的 Red -> 让它变绿的最小实现 -> 必要重构 -> 记录证据，然后再进入下一个行为。
 
 测试数据也必须诚实。fixture 只提供当前行为需要的最小输入；partial fixture、类型断言、mock payload 或 generated stub 必须写清哪些字段是真实 contract，哪些只是测试填充。不能用 `as`、`any`、双重 cast、缺字段 partial mock 或 test-only method 掩盖 seam 设计问题。
 
+Green 不是顺手把未来行为都做掉。只写当前红灯要求的最小生产代码；如果需要新接口，优先保持小接口深模块，依赖从调用方传入，外部 boundary adapter 拆成具体操作，而不是用一个 generic fetcher 把复杂条件推给 mock。
+
+Refactor 只能发生在 Green 之后。优先处理当前 slice 暴露出的重复、长方法、浅模块、feature envy、primitive obsession、命名混乱、三层以上分支和新代码揭开的旧代码坏味道；没被当前绿色测试保护的扩张性整理，回到 `cc-plan` 或后续任务。
+
 ## Entry Gate
 
 1. 先读 `planning/design.md` 或 `planning/analysis.md`，再读 `planning/tasks.md`、`planning/task-manifest.json`；如果是恢复执行，再补读最近 checkpoint 或已有 `handoff/resume-index.md`。
 2. 先用 `scripts/select-ready-tasks.sh` 判断现在到底哪几个任务真的 ready。
-3. 只锁定当前 ready task，或一组经依赖与触点校验后可并行的 ready tasks。
+3. 只锁定当前 ready task，或一组经依赖、wave、精确触点与父子路径触点校验后可并行的 ready tasks。
 4. 如果这次来自 `cc-investigate`，必须把 `planning/analysis.md` 当成 canonical contract，而不是一边实现一边重新调查。
 5. 没有任务上下文，不准把任务扔给 subagent；先用 `scripts/build-task-context.sh` 从 `planning/design.md` 或 `planning/analysis.md`、`planning/tasks.md`、`planning/task-manifest.json`、`change-meta.json` 与相关 capability spec 组装上下文。
+6. 如果 `task-manifest.json.metadata.lane == "quick"`，仍然必须有 current task、verification、checkpoint 和 handoff；quick 只缩短文档密度，不跳过证据。
+7. 如果仓库含 `.gitmodules` 或 manifest 提供 `submodulePaths`，先用 `scripts/detect-file-conflicts.sh` 标出 `submoduleTouches`；只有触达该 submodule 的任务失去默认 worktree 隔离资格，未触达任务不能被无辜串行化。
 
 ## Loop
 
 1. 读取当前任务，而不是重新发明任务。
-2. 依赖没满足前，不准提前做下游任务。
-3. 没有明确并行资格，不准把多个实现任务同时推进。
+2. 依赖没满足前，不准提前做下游任务；不同 wave 之间不允许抢跑。
+3. 没有明确并行资格，不准把多个实现任务同时推进；`touches` 父子路径重叠也算同一执行表面。
 4. 先 `fail-first`：先写失败测试，先看见预期红，再写生产代码。
 5. 如果红灯不是预期失败（语法错、fixture 错、测试没连上），先修测试直到它正确失败。
 6. 如果红灯通过错误 seam 得到，比如私有方法、内部调用次数、mock 内部协作者，先修测试 seam，不准进入 Green。
-7. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现。
-8. 如果当前 Red 需要新的 fixture 或 mock，先证明它仍从公共 seam 触发真实行为；fixture 缺字段、类型强转或内部 mock 都要写入 `tdd.testQuality.fixtureRisk` 或先修 seam。
-9. Refactor 后必须重跑相关测试，保持 Green。
-10. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`，并记录 `tdd.testQuality` 或 `tddException`。
-11. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
-12. 当前任务完成后，把可验证证据留给 `cc-check`。
+7. 如果红灯只断言实现形状、直接查内部状态或一次证明多个逻辑行为，先改测试，不准进入 Green。
+8. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现，不预铺未来测试尚未要求的分支、状态或 API。
+9. 如果当前 Red 需要新的 fixture 或 mock，先证明它仍从公共 seam 触发真实行为；fixture 缺字段、类型强转或内部 mock 都要写入 `tdd.testQuality.fixtureRisk` 或先修 seam。
+10. Refactor 后必须重跑相关测试，保持 Green；Red 状态下不重构。
+11. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`，并记录 `tdd.testQuality`、`tdd.greenMinimality`、`tdd.refactorCandidates` 或 `tddException`。
+12. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
+13. 当前任务完成后，把可验证证据留给 `cc-check`。
 
 ## Output
 
@@ -176,9 +192,14 @@ Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试
 ## Good Output
 
 - 当前 task 一眼可见，执行者不用从聊天记录里猜目标
+- 当前 wave、ready tasks、parallel candidates、touch conflict verdict 和 submoduleTouches 一眼可见
 - 至少留下一次明确的 tracer bullet Red/Green/Refactor 证据，且 Red 是公共 seam 上的预期行为失败
+- Red 证据说明测试名、单一行为、公共验证路径和为何不是实现细节测试
+- Green 证据说明 minimality guard：本轮只满足当前红灯，没有提前实现未来分支
+- Refactor 证据说明清掉了哪个具体坏味道，或者为什么当前 slice 不需要 refactor
 - 测试 fixture 说明真实 contract 字段和测试填充字段，没有用类型欺骗或内部 mock 制造假绿
 - runtime / checkpoint 足够让下一位接手者无损恢复
+- quick lane 也有 mini manifest、checkpoint、verification 和唯一 next action，不靠聊天记录继续
 - reviewer 能顺着 review 记录和验证命令复盘这次实现
 
 ## Bundled Resources
@@ -205,11 +226,14 @@ Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试
 5. 红灯原因必须和目标行为缺失一致；红灯如果只是测试写错，不算 TDD 证据。
 6. 红灯必须验证公共接口上的行为；实现细节测试、私有方法测试、内部调用次数断言都要先退回 Red 修正。
 7. Mock 只能放在系统边界；如果必须 mock 内部协作者才能测试，说明 seam 或设计合同有问题。
-8. 先过 `spec review`，再过 `code review`，顺序不能反。
-9. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
-10. 失败和阻塞都要留下恢复证据。
-11. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
-12. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
+8. 一个 Red 只证明一个逻辑行为；bulk Red 或测试名描述实现步骤，都先退回测试设计。
+9. Green 只写当前红灯需要的最小实现；预铺未来功能、兼容分支或宽接口都算越界。
+10. Red 时不重构；Refactor 只在相关测试已绿后处理当前 slice 暴露的坏味道。
+11. 先过 `spec review`，再过 `code review`，顺序不能反。
+12. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
+13. 失败和阻塞都要留下恢复证据。
+14. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
+15. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
 
 ## Exit Criteria
 

package/.claude/skills/cc-do/references/execution-recovery.md

@@ -7,6 +7,8 @@
 - 当前 task status
 - 当前 active phase
 - 当前 ready tasks
+- 当前 wave / parallel candidates / touch conflict verdict
+- submoduleTouches（如适用）
 - 当前 review gates（spec / code）
 - 已完成证据
 - 阻塞点
@@ -57,13 +59,22 @@
 - `red.expectedFailure`
 - `red.testSeam`
 - `red.behaviorAsserted`
+- `red.specStyleTestName`
+- `red.oneLogicalBehavior`
+- `red.publicVerificationPath`
 - `red.allowedMocks`
 - `red.implementationDetailRisk`
 - `green.command`
 - `green.exitStatus`
+- `green.minimalityGuard`
 - `refactor.status`
+- `refactor.candidates`
+- `refactor.greenCommand`
 - `testQuality.usesPublicInterface`
 - `testQuality.describesBehavior`
+- `testQuality.specStyleName`
+- `testQuality.verifiesThroughPublicPath`
+- `testQuality.noBulkRed`
 - `testQuality.survivesInternalRefactor`
 - `testQuality.mocksOnlySystemBoundaries`
 - `review.spec.status`
@@ -95,3 +106,4 @@
 - 验收标准
 - 验证命令
 - 不做项 / 边界
+- quick lane 是否仍有 mini manifest、checkpoint、verification 和唯一 next action

package/.claude/skills/cc-do/references/parallel-dispatch.md

@@ -12,17 +12,18 @@
 
 1. 两个任务都在当前 active phase
 2. `dependsOn` 已满足，且互不依赖
-3. `touches` / `files` 没有交集
+3. `touches` / `files` 没有交集，且没有父路径 / 子路径重叠
 4. 不共享同一个可变资源，例如同一 schema、同一公共接口、同一全局状态
 5. 验证命令可以各自独立运行
 6. 每个任务都有完整上下文包，不需要靠别人的临场解释补脑
+7. submodule touches 已经被识别；只有实际触达 submodule 的任务失去普通 worktree 隔离资格
 
 ## Must Run Sequentially
 
 命中任一条，就必须串行：
 
 1. 一个任务依赖另一个任务的输出
-2. 两个任务会改同一个文件或同一抽象边界
+2. 两个任务会改同一个文件、父子路径或同一抽象边界
 3. 上游任务在定义契约，下游任务在消费契约
 4. 一个任务先改 schema / API，另一个任务基于它写实现
 5. 你还不能清楚说出每个任务各自的验收标准
@@ -50,8 +51,9 @@
 
 1. 先选当前 active phase 的 ready tasks
 2. 在 ready tasks 里优先选 `touches` 不重叠的任务
-3. 在不重叠任务里优先选验证面最小的任务
-4. 如果仍然不确定，退回串行
+3. 在不重叠任务里排除 submodule-touch 隔离风险
+4. 在剩余任务里优先选验证面最小的任务
+5. 如果仍然不确定，退回串行
 
 ## Good Example
 

package/.claude/skills/cc-do/scripts/detect-file-conflicts.sh

@@ -30,18 +30,41 @@ const sourceTasks = Array.isArray(parsed)
 const tasks = sourceTasks.filter((task) => task && task.parallel !== false);
 const fileConflicts = [];
 const dependencyConflicts = [];
+const submoduleTouches = [];
 const conflictedTaskIds = new Set();
 
 function touchesOf(task) {
-  return [...new Set([...(task.touches || []), ...(task.files || [])].filter(Boolean))];
+  return [...new Set([...(task.touches || []), ...(task.files || [])].filter(Boolean).map(normalizePath))];
+}
+
+function normalizePath(value) {
+  return String(value)
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/$/, '');
+}
+
+function overlaps(left, right) {
+  if (left === right) return left;
+  if (left && right.startsWith(`${left}/`)) return left;
+  if (right && left.startsWith(`${right}/`)) return right;
+  return '';
 }
 
 for (let index = 0; index < tasks.length; index += 1) {
   for (let offset = index + 1; offset < tasks.length; offset += 1) {
     const left = tasks[index];
     const right = tasks[offset];
-    const leftTouches = new Set(touchesOf(left));
-    const sharedTouches = touchesOf(right).filter((touch) => leftTouches.has(touch));
+    const leftTouches = touchesOf(left);
+    const rightTouches = touchesOf(right);
+    const sharedTouches = [
+      ...new Set(
+        leftTouches.flatMap((leftTouch) =>
+          rightTouches.map((rightTouch) => overlaps(leftTouch, rightTouch)).filter(Boolean)
+        )
+      )
+    ];
 
     if (sharedTouches.length > 0) {
       conflictedTaskIds.add(left.id);
@@ -68,6 +91,28 @@ for (let index = 0; index < tasks.length; index += 1) {
   }
 }
 
+const submodulePaths = (parsed.submodulePaths || [])
+  .map(normalizePath)
+  .filter(Boolean);
+
+if (submodulePaths.length > 0) {
+  for (const task of tasks) {
+    const taskTouches = touchesOf(task);
+
+    for (const submodulePath of submodulePaths) {
+      const matchedTouches = taskTouches.filter((touch) => overlaps(submodulePath, touch));
+
+      if (matchedTouches.length > 0) {
+        submoduleTouches.push({
+          task: task.id,
+          submodulePath,
+          touches: matchedTouches
+        });
+      }
+    }
+  }
+}
+
 const safeTaskIds = tasks
   .map((task) => task.id)
   .filter((taskId) => !conflictedTaskIds.has(taskId));
@@ -78,6 +123,7 @@ process.stdout.write(
       hasConflicts: fileConflicts.length > 0 || dependencyConflicts.length > 0,
       fileConflicts,
       dependencyConflicts,
+      submoduleTouches,
       safeTaskIds
     },
     null,

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

@@ -1,5 +1,17 @@
 # CC-Investigate Skill Changelog
 
+## v1.2.2 - 2026-05-06
+
+- add a Roadmap Sync Gate so frozen investigations must reconcile the source RM before handing off repair work
+- classify roadmap updates by `implementation drift`, `missing spec truth`, and `roadmap mismatch` outcomes
+- update analysis, tasks, and manifest templates with roadmap sync status fields
+
+## v1.2.1 - 2026-04-29
+
+- add persistent debug session fields for active hypothesis, probes, cleanup state, and next evidence action
+- add diagnose-only and workflow-forensics modes so root-cause reports do not masquerade as completed repairs
+- update the analysis template with debug session, workflow forensics, and diagnose-only outcome sections
+
 ## v1.2.0 - 2026-04-28
 
 - treat feedback loops as investigation products that must be made faster, sharper, and more deterministic before root cause freeze

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

@@ -6,7 +6,7 @@
 
 - Enter from: a bug, regression, or broken requirement whose root cause is still unclear.
 - Stay in: `cc-investigate` until `planning/analysis.md` and the repair handoff are both frozen.
-- Exit to: `cc-do` only after root cause and repair boundary are explicit in canonical artifacts.
+- Exit to: `cc-do` only after root cause, repair boundary, and source roadmap progress are explicit in canonical artifacts.
 - Reroute to: `cc-plan` for scope/design truth changes, or `roadmap` for project-level priority decisions.
 
 ## Core Rules
@@ -20,6 +20,9 @@
 7. 调查失败三次后先重建入口，不准继续乱补。
 8. 没有 frozen root-cause contract，不准进入 repair task。
 9. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
+10. diagnose-only 只能输出根因、owner、风险和 next action，不能把未修复状态标成完成。
+11. workflow forensics 先分类 artifact / git / state / tool / permission / process failure，再决定是否进入修复。
+12. 退出前必须跑 Roadmap Sync Gate：`implementation drift`、`missing spec truth`、`roadmap mismatch` 三种结论都要让 source RM 的状态和 next action 跟上。
 
 ## Iron Law
 
@@ -34,6 +37,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - `planning/analysis.md`
 - `planning/tasks.md`
 - `planning/task-manifest.json`
+- `change-meta.json`
 
 ## Investigation Standard
 
@@ -61,6 +65,8 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 | `history-trace` | 同一区域反复坏 | 查历史 `analysis.md`、TODO、report-card finding |
 | `pattern-research` | 陌生框架 / 依赖 / 平台错误 | 脱敏后查通用错误类型 |
 | `contract-check` | 修复边界可能扩大 | 判定 implementation drift / missing spec truth / roadmap mismatch |
+| `diagnose-only` | 用户只要问题解释或现在不能修 | 冻结 root cause、owner、risk、next action，不生成实现完成态 |
+| `workflow-forensics` | devflow artifact、git、状态、权限或工具链断裂 | 分类 failure owner 和 rescue action，再决定 reroute |
 
 ## Pattern Analysis
 
@@ -89,6 +95,9 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - Diagnostic Instrumentation Plan：probe tag、probe location、question answered、command、expected signal、cleanup requirement
 - Feedback Loop Contract：loop type、command、expected / actual signal、symptom match、runtime、determinism、failure rate、sharpening plan
 - Correct Test Seam：test seam、public interface exercised、why it reaches the real trigger chain、why shallow tests are rejected
+- Persistent Debug Session：session id、active hypothesis、completed probes、cleanup state、next evidence action
+- Workflow Forensics：artifact state、git state、runtime state、tool/permission/process failure owner、rescue action
+- Diagnose-Only Outcome：root cause, owner, risk, next action, and explicit no-repair verdict
 
 这些字段不是装饰。它们的作用是证明根因位于源头，而不是报错点。
 
@@ -152,6 +161,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - 模板在 `assets/`
 - 调查契约在 `references/investigation-contract.md`
 - 需要分析骨架时用 `scripts/bootstrap-analysis.sh`
+- Roadmap 回写使用 `../cc-roadmap/scripts/locate-roadmap-item.sh` 和 `../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Exit Rule
 
@@ -163,3 +173,4 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - 用什么命令证明修好了
 
 这次调查才算合格。
+如果 source RM 仍然停在旧 status、旧 progress 或旧 REQ/FIX 绑定，说明本次 `cc-investigate` 没有真正退出。

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

@@ -1,6 +1,6 @@
 ---
 name: cc-investigate
-version: 1.2.0
+version: 1.2.2
 description: "Use when a bug, regression, broken task, or unexpected behavior needs root-cause investigation, reproducible evidence, and a frozen repair handoff before cc-do resumes coding."
 triggers:
   - "帮我查这个 bug"
@@ -17,6 +17,8 @@ reads:
   - "assets/ANALYSIS_TEMPLATE.md"
   - "assets/TASKS_TEMPLATE.md"
   - "assets/TASK_MANIFEST_TEMPLATE.json"
+  - "../cc-roadmap/scripts/locate-roadmap-item.sh"
+  - "../cc-roadmap/scripts/sync-roadmap-progress.sh"
 writes:
   - path: "devflow/changes/<change-key>/planning/analysis.md"
     durability: "durable"
@@ -30,17 +32,24 @@ writes:
   - path: "devflow/changes/<change-key>/change-meta.json"
     durability: "durable"
     required: true
+effects:
+  - source roadmap progress sync when investigation freezes, reroutes, or diagnoses a roadmap mismatch
 entry_gate:
   - "Read the current bug report, existing requirement artifacts, relevant code, tests, and recent history before forming any hypothesis."
   - "Use a FIX-<number>-<description> change key for new bug-fix investigations."
   - "Build a runnable feedback loop, confirm it matches the reported symptom, then freeze the evidence chain before proposing repair tasks."
+  - "Record persistent debug session state: active hypothesis, probes, cleanup status, and next evidence action."
   - "Search prior investigations, TODO/backlog signals, and recent fixes in the affected area before declaring the bug novel."
   - "For multi-component, deep-stack, or flaky symptoms, record boundary probes, backward trace, or condition-wait evidence before declaring the root cause."
   - "For performance regressions, collect a baseline or profile signal before treating logs as evidence."
   - "Do not write production code here; this stage ends with planning/analysis.md plus executable repair tasks for cc-do."
+  - "Before exit, locate the source RM in `devflow/roadmap.json`, `devflow/ROADMAP.md`, optional `devflow/BACKLOG.md`, or legacy `devflow/roadmap-tracking.json`; the repair handoff must not leave roadmap progress stale."
 exit_criteria:
   - "planning/analysis.md records symptom, reproduction, evidence chain, boundary probes or backward trace when applicable, pattern analysis, tested hypotheses, confirmed root cause, and repair boundary."
+  - "diagnose-only outcomes clearly stop before implementation while preserving root cause, owner, and next action."
+  - "workflow forensics classify artifact, git, state, or tool failures before repair tasks are generated."
   - "planning/tasks.md and planning/task-manifest.json are explicit enough that cc-do can repair the bug without chat memory."
+  - "The source roadmap item has been synchronized with the investigation outcome, or `planning/analysis.md` and `change-meta.json` record why no roadmap update is valid."
   - "The honest next step is cc-do, cc-plan, or roadmap."
 reroutes:
   - when: "The issue is actually a new feature, a scope redesign, or a product decision instead of a bug investigation."
@@ -57,9 +66,9 @@ recovery_modes:
     when: "New execution evidence disproves the current root-cause contract or widens the suspected blast radius."
     action: "Reopen planning/analysis.md, update the evidence chain, and regenerate repair tasks only after the new root cause is frozen."
 tool_budget:
-  read_files: 10
+  read_files: 11
   search_steps: 6
-  shell_commands: 6
+  shell_commands: 7
 ---
 
 # CC-Investigate
@@ -141,12 +150,14 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 | 错误类型陌生，像框架 / 依赖 / 平台问题 | `pattern-research`，先做脱敏外部调研 |
 | 同一区域反复坏 | `history-trace`，先查 prior investigations 和最近修复 |
 | 看起来像 bug，实则是未定义行为或新需求 | 直接 reroute 到 `cc-plan` |
+| 用户只要根因报告、不要求修复 | `diagnose-only`，停止在报告与 next action，不生成完成态实现任务 |
+| 失败来自 workflow / artifact / git / state 断裂 | `workflow-forensics`，先分类坏在文件、状态、工具、权限还是流程 |
 
 先说“这是什么类问题”，再说“我要怎么修”。没有分类的 debug，最后都会变成乱打补丁。
 
 ## Harness Contract
 
-- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, and write only `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`.
+- Allowed actions: reproduce, collect evidence, trace code paths, test hypotheses, freeze root cause, write `planning/analysis.md`, `planning/tasks.md`, `planning/task-manifest.json`, and `change-meta.json`, then run the final roadmap progress sync for the source RM.
 - Forbidden actions: writing production code, disguising guesses as root cause, or skipping directly from symptoms to repair.
 - Required evidence: every root-cause claim must point to reproduction evidence, code facts, recent history, or explicit user confirmation.
 - Reroute rule: product/scope changes go to `cc-plan`; strategy questions go to `roadmap`; only confirmed repair handoff goes to `cc-do`.
@@ -174,6 +185,9 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 
 `cc-investigate` 不写生产代码，不在这里偷跑 `cc-do`。
 
+diagnose-only 仍然写 `planning/analysis.md`，但 `planning/tasks.md` 只能包含证据交接、
+监控、人工动作或明确的 `reroute`；不能把“已经诊断”伪装成“已经修复”。
+
 ## Entry Gate
 
 1. 先确认当前对象仍然属于一个 requirement，而不是整个项目级故障。
@@ -225,9 +239,16 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
    - 写清正确测试缝隙：测试是否覆盖真实触发链；如果没有正确 seam，这本身就是需要记录的架构事实
    - 写明 affected module、allowed files、forbidden files、blast radius estimate；超过 5 个文件默认拆分或 reroute
    - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
-8. **Hand off**
+8. **Roadmap sync**
+   - 用 `locate-roadmap-item.sh` 定位 source RM；找不到时在 `analysis.md` 和 `change-meta.json.roadmapSync` 写 `no-source-rm`
+   - `implementation drift`：回写 source RM 为 `Repair planned` 或等价调查完成状态，绑定 `FIX-*`，进度保持在可执行修复前的真实百分比
+   - `missing spec truth`：回写 source RM 的 expected spec delta 或 follow-up，必要时 reroute 到 `cc-plan`
+   - `roadmap mismatch`：不要直接进入修复；先把 mismatch 写回 roadmap / backlog，下一步写 `roadmap` 或 `cc-plan`
+   - 使用 `sync-roadmap-progress.sh` 更新 `devflow/roadmap.json`，并重新生成 `devflow/ROADMAP.md` / `devflow/BACKLOG.md`
+9. **Hand off**
    - 下一步明确写成 `cc-do`
    - 如果 repair contract 越过当前 requirement，就 reroute 到 `cc-plan`
+   - 如果是 diagnose-only，下一步写成 human action、monitoring、backlog、`cc-plan` 或 `cc-do`，但不得标记实现完成
 
 ## Pattern Analysis
 
@@ -421,6 +442,7 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 - 正确测试缝隙写清楚，不用浅层测试制造假安全
 - `planning/tasks.md` 只包含修复任务，不夹带新需求
 - 如果应该回 `cc-plan`，理由写清楚，不假装还能继续 patch
+- Roadmap Sync Gate 必须在 handoff 前闭合：source RM 绑定的 `FIX-*`、调查状态、spec diagnosis 和 next action 不能停留在聊天里。
 
 ## Bundled Resources
 
@@ -430,6 +452,8 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 - 修复任务模板：`assets/TASKS_TEMPLATE.md`
 - manifest 模板：`assets/TASK_MANIFEST_TEMPLATE.json`
 - 分析骨架：`scripts/bootstrap-analysis.sh`
+- Roadmap 定位：`../cc-roadmap/scripts/locate-roadmap-item.sh`
+- Roadmap 回写：`../cc-roadmap/scripts/sync-roadmap-progress.sh`
 
 ## Working Rules
 
@@ -443,11 +467,13 @@ flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调
 8. 外部调研必须先脱敏，调研结论必须回到本仓库证据验证。
 9. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
 10. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
+11. Roadmap 相关文件以 `devflow/roadmap.json` 为真相源，`devflow/ROADMAP.md` / `devflow/BACKLOG.md` 只是投影；不要再写旧式 `devflow/roadmap/*` 路径。
 
 ## Exit Criteria
 
 - `planning/analysis.md` 已冻结症状、复现、证据链、根因和修复边界
 - `planning/tasks.md` / `planning/task-manifest.json` 可直接交给 `cc-do`
+- Roadmap Sync Gate 已闭合：source RM 已回写调查结果 / reroute，或 no-op reason 已落盘
 - 下一步唯一答案是 `cc-do`、`cc-plan` 或 `roadmap`
 
 ## Do Not