cc-devflow 4.5.2 → 4.5.3

package/.claude/skills/cc-check/scripts/render-report-card.js

@@ -80,6 +80,22 @@ function deriveVerdict(manifest, quickGates, strictGates, review) {
     return 'blocked';
   }
 
+  if (['fail'].includes(review.qa?.feedbackLoop?.status)) {
+    return 'fail';
+  }
+
+  if (['blocked', 'pending'].includes(review.qa?.feedbackLoop?.status)) {
+    return 'blocked';
+  }
+
+  if (['fail'].includes(review.qa?.behaviorEvidence?.status)) {
+    return 'fail';
+  }
+
+  if (['blocked', 'pending'].includes(review.qa?.behaviorEvidence?.status)) {
+    return 'blocked';
+  }
+
   if (review.status === 'blocked') {
     return 'blocked';
   }
@@ -185,6 +201,26 @@ function buildClaimEvidence({ manifest, quickGates, strictGates, review }) {
 function buildQa(review) {
   return {
     status: review.qa?.status || 'skipped',
+    feedbackLoop: review.qa?.feedbackLoop || {
+      status: 'skipped',
+      mode: 'not-applicable',
+      commandOrArtifact: '',
+      speed: '',
+      determinism: '',
+      signalSharpness: '',
+      reproductionRate: '',
+      attempts: [],
+      blockedReason: 'not recorded'
+    },
+    behaviorEvidence: review.qa?.behaviorEvidence || {
+      status: 'skipped',
+      userFacingBoundary: '',
+      expectedBehavior: '',
+      actualBehavior: '',
+      reproductionSteps: [],
+      consistency: '',
+      domainLanguage: []
+    },
     regressionProof: review.qa?.regressionProof || [],
     testQuality: review.qa?.testQuality || [],
     coverageAudit: review.qa?.coverageAudit || {
@@ -207,6 +243,7 @@ function buildQa(review) {
       issues: [],
       skipReason: 'not recorded'
     },
+    architectureFollowUps: review.qa?.architectureFollowUps || [],
     tddException: review.qa?.tddException || null
   };
 }

package/.claude/skills/cc-check/scripts/verify-gate.sh

@@ -63,8 +63,15 @@ jq -e '
   ((.qa.coverageAudit.status? // "skipped") | IN("pass", "fail", "blocked", "skipped", "pending")) and
   ((.qa.browserEvidence? // {"status":"skipped"}) | type == "object") and
   ((.qa.browserEvidence.status? // "skipped") | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.qa.feedbackLoop? // {"status":"skipped"}) | type == "object") and
+  ((.qa.feedbackLoop.status? // "skipped") | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.qa.behaviorEvidence? // {"status":"skipped"}) | type == "object") and
+  ((.qa.behaviorEvidence.status? // "skipped") | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.qa.architectureFollowUps? // []) | type == "array") and
   ((.review.findings? // []) | all(.[]; ((.confidenceScore? // 7) | type == "number") and ((.displayTier? // "info") | IN("blocking", "warning", "info", "suppressed")))) and
   ((.verdict != "pass") or ((.review.freshness.status? // "unknown") | IN("fresh", "not-applicable"))) and
+  ((.verdict != "pass") or ((.qa.feedbackLoop.status? // "skipped") | IN("pass", "skipped"))) and
+  ((.verdict != "pass") or ((.qa.behaviorEvidence.status? // "skipped") | IN("pass", "skipped"))) and
   ((.verdict != "pass") or (((.runtime.failureOwnership? // []) | map(select(((.classification? // "") | IN("in-branch", "ambiguous")) and ((.status? // "open") | IN("open", "pending")))) | length) == 0)) and
   ((.verdict == "pass" and .reroute == "none") or (.verdict != "pass" and .reroute != "none"))
 ' "$REPORT" >/dev/null

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

@@ -1,5 +1,17 @@
 # CC-Do Skill Changelog
 
+## v1.6.0 - 2026-04-28
+
+- prohibit horizontal TDD execution by requiring one tracer bullet Red/Green/Refactor cycle per observable behavior
+- add test fixture discipline so partial fixtures, type assertions, generated stubs, and mocks must preserve public seam behavior
+- require checkpoints to record fixture risk when test data shortcuts could hide a seam or contract problem
+
+## v1.5.3 - 2026-04-28
+
+- require Red evidence to prove behavior through a public seam instead of private methods, internal call counts, or implementation-shaped tests
+- add mock-boundary and test-quality gates to the TDD execution contract so internal collaborators are not mocked as fake proof
+- allow `write-task-checkpoint.sh --tdd-json` and runtime checkpoint schema to preserve structured TDD evidence for recovery and review
+
 ## v1.5.2 - 2026-04-27
 
 - require execution evidence that adds human-readable summaries to resolve the runtime output policy first

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

@@ -50,10 +50,12 @@
 
 1. 先写失败测试，再运行到红。
 2. 确认红灯是预期失败，不是测试写错、fixture 缺失或环境没接上。
-3. 只写让当前测试转绿的最小实现。
-4. 绿后才允许重构。
-5. 重构后必须保持绿。
-6. 测试没先红过，就不能宣称这次变更受 TDD 保护。
+3. 确认红灯通过公共 seam 证明行为缺失，而不是测私有函数、内部调用次数或临时结构。
+4. 确认 mock 只发生在系统边界；内部协作者不 mock。
+5. 只写让当前测试转绿的最小实现。
+6. 绿后才允许重构。
+7. 重构后必须保持绿。
+8. 测试没先红过，或红灯不是公共 seam 上的行为失败，就不能宣称这次变更受 TDD 保护。
 
 ## TDD Exception Rule
 
@@ -78,11 +80,14 @@
 
 1. `red_failed`: 已观察到预期失败
 2. `red_reason_verified`: 红灯原因与目标行为缺失一致
-3. `green_passed`: 当前任务实现转绿
-4. `refactor_done` 或 `refactor_not_needed`
-5. `refactor_green`: 重构后相关测试仍绿
-6. `spec_review_pass`
-7. `code_review_pass`
+3. `red_seam_verified`: 红灯通过公共接口、调用方流程、CLI/API/UI 或真实边界进入系统
+4. `red_behavior_verified`: 测试断言用户或调用方可观察行为，不断言内部实现细节
+5. `mock_boundary_verified`: mock 只在系统边界，内部协作者没有被 mock
+6. `green_passed`: 当前任务实现转绿
+7. `refactor_done` 或 `refactor_not_needed`
+8. `refactor_green`: 重构后相关测试仍绿
+9. `spec_review_pass`
+10. `code_review_pass`
 
 任何一门失败，都回到实现，不准直接跨过去。
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-do
-version: 1.5.2
+version: 1.6.0
 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
@@ -36,7 +36,7 @@ entry_gate:
   - Select only ready tasks whose dependencies and file ownership are clear.
   - If the current task cannot be restated from canonical artifacts, run a context reset before coding.
 exit_criteria:
-  - The current task has red/green evidence, review evidence, and a resumable checkpoint trail.
+  - The current task has red/green evidence, public-seam test quality evidence, review evidence, and a resumable checkpoint trail.
   - 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:
@@ -134,8 +134,14 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 3. Refactor：只有 Green 之后才能清理命名、重复、结构和坏味道。
 4. Record：每一站都写入 `checkpoint.json`，必要时写入 `events.jsonl`。
 
+Red 不是形式上的红，而是公共 seam 上的行为缺失证明。测试必须通过公共接口、调用方流程、CLI/API/UI 路径或其它真实边界进入系统；只验证私有函数、内部调用次数、临时数据结构或 mock 自己控制的内部协作者，不算 TDD 证据。
+
 例外只能用于 throwaway prototype、纯生成文件、纯配置改动；例外必须写进 checkpoint 的 `tddException`，包含原因、风险和替代验证命令。测试第一次就绿，说明测试没有证明新行为，必须修测试而不是继续写生产代码。
 
+禁止水平切片：不要先写一批测试，再写一批实现。每次只推进一个 tracer bullet：一个可观察行为的 Red -> 让它变绿的最小实现 -> 必要重构 -> 记录证据，然后再进入下一个行为。
+
+测试数据也必须诚实。fixture 只提供当前行为需要的最小输入；partial fixture、类型断言、mock payload 或 generated stub 必须写清哪些字段是真实 contract，哪些只是测试填充。不能用 `as`、`any`、双重 cast、缺字段 partial mock 或 test-only method 掩盖 seam 设计问题。
+
 ## Entry Gate
 
 1. 先读 `planning/design.md` 或 `planning/analysis.md`，再读 `planning/tasks.md`、`planning/task-manifest.json`；如果是恢复执行，再补读最近 checkpoint 或已有 `handoff/resume-index.md`。
@@ -151,11 +157,13 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 3. 没有明确并行资格，不准把多个实现任务同时推进。
 4. 先 `fail-first`：先写失败测试，先看见预期红，再写生产代码。
 5. 如果红灯不是预期失败（语法错、fixture 错、测试没连上），先修测试直到它正确失败。
-6. 按 `Red -> Green -> Refactor` 推进，Green 只允许最小实现。
-7. Refactor 后必须重跑相关测试，保持 Green。
-8. 每次推进都写 task runtime：`events.jsonl` + `checkpoint.json`。
-9. 任务实现后，先过 `spec review`，再过 `code review`，两道门都过才算任务收口；这里只验证 spec delta，不回写长期 spec。
-10. 当前任务完成后，把可验证证据留给 `cc-check`。
+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`。
 
 ## Output
 
@@ -168,7 +176,8 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 ## Good Output
 
 - 当前 task 一眼可见，执行者不用从聊天记录里猜目标
-- 至少留下一次明确的 Red/Green/Refactor 证据，且 Red 是预期失败
+- 至少留下一次明确的 tracer bullet Red/Green/Refactor 证据，且 Red 是公共 seam 上的预期行为失败
+- 测试 fixture 说明真实 contract 字段和测试填充字段，没有用类型欺骗或内部 mock 制造假绿
 - runtime / checkpoint 足够让下一位接手者无损恢复
 - reviewer 能顺着 review 记录和验证命令复盘这次实现
 
@@ -194,11 +203,13 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 3. 没有失败测试，不准写生产代码。
 4. 测试如果第一次就绿，说明你没证明任何东西，先修测试。
 5. 红灯原因必须和目标行为缺失一致；红灯如果只是测试写错，不算 TDD 证据。
-6. 先过 `spec review`，再过 `code review`，顺序不能反。
-7. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
-8. 失败和阻塞都要留下恢复证据。
-9. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
-10. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
+6. 红灯必须验证公共接口上的行为；实现细节测试、私有方法测试、内部调用次数断言都要先退回 Red 修正。
+7. Mock 只能放在系统边界；如果必须 mock 内部协作者才能测试，说明 seam 或设计合同有问题。
+8. 先过 `spec review`，再过 `code review`，顺序不能反。
+9. 不在 `cc-do` 里改 capability spec 正文；这里只产出实现证据和 spec 对齐证据。
+10. 失败和阻塞都要留下恢复证据。
+11. 给 subagent 的输入必须包含：当前进度、当前任务全文、依赖状态、必读文件、验收标准、可信命令。
+12. 三次失败修补后必须先质疑调查合同或设计合同，而不是继续堆补丁。
 
 ## Exit Criteria
 

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

@@ -37,11 +37,14 @@
 1. `context_ready`
 2. `red_failed`
 3. `red_reason_verified`
-4. `green_passed`
-5. `refactor_done` 或 `refactor_not_needed`
-6. `refactor_green`
-7. `spec_review_pass`
-8. `code_review_pass`
+4. `red_seam_verified`
+5. `red_behavior_verified`
+6. `mock_boundary_verified`
+7. `green_passed`
+8. `refactor_done` 或 `refactor_not_needed`
+9. `refactor_green`
+10. `spec_review_pass`
+11. `code_review_pass`
 
 如果 `events.jsonl` 没开启，至少仍要有最新 `checkpoint.json` 和 manifest review verdict。
 
@@ -52,9 +55,17 @@
 - `red.command`
 - `red.exitStatus`
 - `red.expectedFailure`
+- `red.testSeam`
+- `red.behaviorAsserted`
+- `red.allowedMocks`
+- `red.implementationDetailRisk`
 - `green.command`
 - `green.exitStatus`
 - `refactor.status`
+- `testQuality.usesPublicInterface`
+- `testQuality.describesBehavior`
+- `testQuality.survivesInternalRefactor`
+- `testQuality.mocksOnlySystemBoundaries`
 - `review.spec.status`
 - `review.code.status`
 

package/.claude/skills/cc-do/scripts/verify-task-gates.sh

@@ -82,12 +82,25 @@ if [[ -f "$events_file" ]]; then
       echo "-1"
     }
 
-    red_idx="$(first_index "red_failed")"
-    green_idx="$(first_index "green_passed")"
-    if [[ "$red_idx" != "-1" && "$green_idx" != "-1" && "$red_idx" -ge "$green_idx" ]]; then
-      echo "Task $TASK_ID gate order is invalid" >&2
-      exit 1
-    fi
+    assert_before() {
+      local before="$1"
+      local after="$2"
+      local before_idx after_idx
+      before_idx="$(first_index "$before")"
+      after_idx="$(first_index "$after")"
+      if [[ "$before_idx" != "-1" && "$after_idx" != "-1" && "$before_idx" -ge "$after_idx" ]]; then
+        echo "Task $TASK_ID gate order is invalid: $before must precede $after" >&2
+        exit 1
+      fi
+    }
+
+    assert_before "red_failed" "red_reason_verified"
+    assert_before "red_reason_verified" "red_seam_verified"
+    assert_before "red_seam_verified" "red_behavior_verified"
+    assert_before "red_behavior_verified" "mock_boundary_verified"
+    assert_before "mock_boundary_verified" "green_passed"
+    assert_before "red_failed" "green_passed"
+    assert_before "green_passed" "refactor_green"
   fi
 fi
 

package/.claude/skills/cc-do/scripts/write-task-checkpoint.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 Usage:
-  write-task-checkpoint.sh --dir path/to/change --task T001 --status pending|running|passed|failed|skipped --summary "..." [--event context_ready] [--attempt 0] [--session session-id] [--next-action "..."]
+  write-task-checkpoint.sh --dir path/to/change --task T001 --status pending|running|passed|failed|skipped --summary "..." [--event context_ready] [--attempt 0] [--session session-id] [--next-action "..."] [--tdd-json '{"red":...}']
 EOF
 }
 
@@ -23,6 +23,7 @@ EVENT_TYPE=""
 ATTEMPT="0"
 SESSION_ID=""
 NEXT_ACTION=""
+TDD_JSON=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -34,6 +35,7 @@ while [[ $# -gt 0 ]]; do
     --attempt) ATTEMPT="$2"; shift 2 ;;
     --session) SESSION_ID="$2"; shift 2 ;;
     --next-action) NEXT_ACTION="$2"; shift 2 ;;
+    --tdd-json) TDD_JSON="$2"; shift 2 ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
   esac
@@ -57,6 +59,15 @@ if [[ -z "$SESSION_ID" ]]; then
   SESSION_ID="${TASK_ID}-$(date -u +%s)"
 fi
 
+tdd_payload="null"
+if [[ -n "$TDD_JSON" ]]; then
+  if [[ -f "$TDD_JSON" ]]; then
+    tdd_payload="$(jq -c . "$TDD_JSON")"
+  else
+    tdd_payload="$(printf '%s' "$TDD_JSON" | jq -c .)"
+  fi
+fi
+
 jq -nc \
   --arg changeId "$change_id" \
   --arg taskId "$TASK_ID" \
@@ -66,6 +77,7 @@ jq -nc \
   --arg summary "$SUMMARY" \
   --arg timestamp "$timestamp" \
   --arg attempt "$ATTEMPT" \
+  --argjson tdd "$tdd_payload" \
   '{
     changeId: $changeId,
     taskId: $taskId,
@@ -75,7 +87,7 @@ jq -nc \
     summary: $summary,
     timestamp: $timestamp,
     attempt: ($attempt | tonumber)
-  }' > "$runtime_task_dir/checkpoint.json"
+  } + (if $tdd == null then {} else {tdd: $tdd} end)' > "$runtime_task_dir/checkpoint.json"
 
 if [[ -n "$EVENT_TYPE" || "$STATUS" == "failed" ]]; then
   jq -nc \

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

@@ -1,5 +1,23 @@
 # CC-Investigate Skill Changelog
 
+## 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
+- require flaky investigations to raise reproduction rate with stress, repetition, timing-window narrowing, or differential loops instead of guessing from weak signals
+- add prevention handoff so confirmed root causes produce either a regression task, architecture finding, or explicit non-recorded reason
+
+## v1.1.6 - 2026-04-28
+
+- clarify that investigation domain language and durable decisions come from cc-devflow native sources: `devflow/specs/`, roadmap/backlog handoff, historical design/analysis, and change metadata
+- remove external context/architecture-decision files from the standard investigation contract so they are not implied as generated artifacts
+- route conflicts through capability specs, roadmap decisions, or historical design decisions instead of external decision-document language
+
+## v1.1.5 - 2026-04-28
+
+- add a feedback-loop contract so investigations record loop type, command, symptom match, runtime, determinism, failure rate, signal specificity, and sharpening plan before freezing root cause
+- require ranked candidate hypotheses before narrowing to active falsification targets, plus probe tags for cleanup-safe diagnostic instrumentation
+- add performance-regression, native domain/decision context, correct-test-seam, and evidence-request fields across the analysis, task, manifest, playbook, and investigation contract templates
+
 ## v1.1.4 - 2026-04-28
 
 - add boundary-probe, backward-trace, reference-comparison, diagnostic-instrumentation, and condition-wait investigation modes for multi-component, deep-stack, similar-path, and flaky failures

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

@@ -12,12 +12,14 @@
 ## Core Rules
 
 1. 先复现，再猜原因。
-2. 先看最近变化，再决定是不是 regression。
-3. 先证伪假设，再冻结根因。
-4. `planning/analysis.md` 和 `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
-5. 调查失败三次后先重建入口，不准继续乱补。
-6. 没有 frozen root-cause contract，不准进入 repair task。
-7. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
+2. 先把复现做成快、准、可复跑的 feedback loop。
+3. 先确认 loop 复现的是用户报告的同一个失败。
+4. 先看最近变化，再决定是不是 regression。
+5. 先证伪假设，再冻结根因。
+6. `planning/analysis.md` 和 `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
+7. 调查失败三次后先重建入口，不准继续乱补。
+8. 没有 frozen root-cause contract，不准进入 repair task。
+9. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
 
 ## Iron Law
 
@@ -36,18 +38,21 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 ## Investigation Standard
 
 1. 先收集 symptom、expected、actual、repro。
-2. 先查 prior investigations、TODOS/backlog、report-card finding 和最近变更。
-3. 先沿代码路径定位触点和最近变更。
-4. 先做 pattern analysis，再形成 1-3 个可证伪假设。
-5. 每个假设都要写支持证据、反证、证伪方法、预期观察、实际观察。
-6. 只有被证据钉死的根因才能进入 repair contract。
-7. repair contract 只讲最小修复边界，不顺手发明新范围。
+2. 先构造 feedback loop：失败测试、HTTP 脚本、CLI fixture、浏览器脚本、trace replay、throwaway harness、fuzz、bisect、differential，最后才是 HITL。
+3. 记录 loop 的运行时间、确定性、失败率、症状匹配证据和 sharpen 计划。
+4. 先查 prior investigations、TODOS/backlog、report-card finding 和最近变更。
+5. 先沿代码路径定位触点和最近变更。
+6. 先做 pattern analysis，再列 3-5 个候选假设并收敛到 1-3 个 active hypotheses。
+7. 每个假设都要写支持证据、反证、证伪方法、预期观察、实际观察。
+8. 只有被证据钉死的根因才能进入 repair contract。
+9. repair contract 只讲最小修复边界，不顺手发明新范围。
 
 ## Investigation Modes
 
 | Mode | 什么时候用 | 第一动作 |
 | --- | --- | --- |
 | `reproduce-first` | 症状真实但不稳定 | 缩小复现命令 / 手动路径 |
+| `feedback-loop` | 已有复现但信号慢、松、偶然或不确定是否同一 bug | 记录 loop type、命令、runtime、determinism、failure rate 和 symptom match |
 | `diff-trace` | 昨天可用、今天坏了 | `git log --oneline -20 -- <affected-files>` |
 | `boundary-probe` | API -> service -> DB、CI -> build -> deploy 这类链路断裂 | 记录每层输入、输出、配置和状态 |
 | `backward-trace` | 错误出现在深层堆栈或坏值来源不明 | 从 immediate failure site 反追 original trigger |
@@ -68,9 +73,12 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - configuration drift：本地 / CI / 生产表现不同
 - stale cache：清缓存后恢复或旧状态复现
 - resource leak：OOM、句柄增长、生命周期未释放
+- performance regression：变慢、CPU / IO / 查询耗时升高、吞吐下降
 - trust boundary drift：外部输入、LLM 输出、用户输入被当成可信
 - timing guess / flaky wait：任意 sleep / timeout / setTimeout 掩盖真实条件
 
+性能回归先建 baseline、profiler、query plan 或 bisect，不把普通日志当性能证据。
+
 ## Boundary And Trace Evidence
 
 复杂链路必须在 `analysis.md` 写清：
@@ -78,7 +86,9 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - Boundary Probe Matrix：component boundary、input observed、output observed、config/env observed、state observed、verdict
 - Backward Trace Chain：immediate failure site、caller chain、bad value origin、original trigger、why symptom-site fix is rejected
 - Reference Comparison：similar working example、broken path、differences accepted / ruled out
-- Diagnostic Instrumentation Plan：probe location、question answered、command、expected signal、cleanup requirement
+- 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
 
 这些字段不是装饰。它们的作用是证明根因位于源头，而不是报错点。
 
@@ -93,6 +103,10 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 
 命中历史时，写入 `analysis.md` 的 `Prior Investigations`，说明这次是复发、同类结构味道，还是无关历史。
 
+## Domain And Decision Context
+
+优先读取 cc-devflow 原生上下文：`devflow/specs/INDEX.md`、相关 capability specs、roadmap/backlog handoff、历史 `planning/design.md` / `planning/analysis.md`、`change-meta.json`。调查输出里的领域名、假设名、测试名应沿用项目词汇；如果调查结论违反 capability spec、roadmap decision 或历史 design decision，要显式写入 evidence chain，而不是静默覆盖既有设计决策。
+
 ## External Research Hygiene
 
 只有在本地证据不足、错误类型陌生、或像依赖 / 框架 / 平台问题时才做外部调研。
@@ -130,6 +144,7 @@ root-cause contract 至少包含：稳定复现或缩小后的可验证症状、
 - attempted evidence
 - why current entry is suspect
 - next option：continue / instrument-and-wait / human-review / reroute-cc-plan
+- evidence request：需要可复现环境、HAR、日志 dump、core dump、带时间戳录屏或临时生产探针权限
 - recommendation
 
 ## Local Kit

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

@@ -1,6 +1,6 @@
 ---
 name: cc-investigate
-version: 1.1.4
+version: 1.2.0
 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"
@@ -33,9 +33,10 @@ writes:
 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."
-  - "Reproduce or narrow the symptom first, then freeze the evidence chain before proposing repair tasks."
+  - "Build a runnable feedback loop, confirm it matches the reported symptom, then freeze the evidence chain before proposing repair tasks."
   - "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."
 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."
@@ -130,6 +131,7 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 | 现实状态 | 先走什么路径 |
 | --- | --- |
 | 症状真实，但还没有稳定复现 | `reproduce-first`，先把现象钉死 |
+| 已有复现但信号慢 / 松 / 偶然 | `feedback-loop`，先把 pass/fail loop 做快、准、可复跑 |
 | 明显是 regression | `diff-trace`，先查最近变化 |
 | 多组件链路断裂 | `boundary-probe`，先记录每个边界的输入、输出、配置和状态 |
 | 报错点很深或坏值来源不明 | `backward-trace`，从 symptom site 一直追到 original trigger |
@@ -186,33 +188,44 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
    - 记录用户看见了什么
    - 记录预期与实际差异
    - 记录复现命令或手动路径
+   - 确认复现的是用户描述的同一个失败，而不是旁边的红灯
    - 如果上下文缺失，只问一个最关键问题，不一次性抛出问题清单
-2. **Trace reality**
+2. **Build feedback loop**
+   - 优先构造 agent 可运行的 pass/fail 信号：失败测试、curl / HTTP 脚本、CLI fixture、浏览器脚本、trace replay、throwaway harness、property / fuzz loop、bisect harness、differential loop，最后才是 HITL 脚本
+   - 记录 loop 类型、命令、运行时间、确定性、失败率、症状匹配证据和下一步 sharpen 计划
+   - loop 太慢、太宽、太 flaky 时，先优化 loop 本身；没有可信 loop，不进入 confirmed root cause
+   - 如果确实无法建 loop，写明尝试过什么，并请求 HAR、日志 dump、core dump、带时间戳录屏、可复现环境访问或临时生产探针权限
+3. **Trace reality**
    - 沿着代码路径找触点
    - 多组件系统先写 `Boundary Probe Matrix`：每个边界的输入、输出、配置 / 环境、状态和 pass/fail
    - 深层报错先写 `Backward Trace Chain`：immediate failure site、caller chain、bad value origin、original trigger
    - 查最近提交和同类改动
    - 查既有 `devflow/changes/*/planning/analysis.md`、`TODOS.md`、backlog、report-card finding
+   - 如果仓库有 `devflow/specs/`、roadmap/backlog handoff、历史 `planning/design.md` / `planning/analysis.md` 或 `change-meta.json`，把领域词汇和已冻结决策当成契约证据
    - 找现有测试和断点证据
    - 判定偏离的是 capability boundary、invariant，还是只是实现细节
-3. **Classify pattern**
-   - 判定是否属于 race condition、null propagation、state corruption、integration failure、configuration drift、stale cache、resource leak、trust boundary drift、timing guess / flaky wait
+4. **Classify pattern**
+   - 判定是否属于 race condition、null propagation、state corruption、integration failure、configuration drift、stale cache、resource leak、performance regression、trust boundary drift、timing guess / flaky wait
    - 如果有同仓库 working example，先写 `Reference Comparison`，列出 working path、broken path、差异和被接受 / 排除的假设
    - 如果错误类型陌生，先做脱敏外部调研；只搜索通用错误类型、框架 / 库名和版本，不搜索 raw secret / path / customer data
-4. **Form hypotheses**
-   - 只保留 1-3 个可被证伪的假设
-   - 每个假设都写支持证据和反证
+5. **Form hypotheses**
+   - 先列 3-5 个候选假设并排序，避免第一直觉锚定
+   - 再收敛到 1-3 个 active hypotheses 进入验证
+   - 每个假设都写支持证据、反证和优先级理由
    - 每个假设都写 `falsification method`、`expected observation`、`actual observation`
-5. **Test hypotheses**
+6. **Test hypotheses**
    - 用复现、日志、断言、最小探针验证
-   - 临时探针必须写 `Diagnostic Instrumentation Plan`：probe location、question answered、command、expected signal、cleanup requirement
+   - 临时探针必须写 `Diagnostic Instrumentation Plan`：probe tag、probe location、question answered、command、expected signal、cleanup requirement
+   - 每个 probe 只回答一个假设预测；一次只改一个变量
+   - debug 日志必须带唯一前缀，例如 `[DEBUG-FIX123-a4f2]`，进入 `cc-do` 前用前缀 grep 清理或转正
    - 三次假设都失败，就停下进入 escalation decision
-6. **Freeze repair contract**
+7. **Freeze repair contract**
    - 根因确认后，写进 `planning/analysis.md`
    - 只保留最小修复边界
+   - 写清正确测试缝隙：测试是否覆盖真实触发链；如果没有正确 seam，这本身就是需要记录的架构事实
    - 写明 affected module、allowed files、forbidden files、blast radius estimate；超过 5 个文件默认拆分或 reroute
    - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
-7. **Hand off**
+8. **Hand off**
    - 下一步明确写成 `cc-do`
    - 如果 repair contract 越过当前 requirement，就 reroute 到 `cc-plan`
 
@@ -229,6 +242,7 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 | configuration drift | 本地可用、CI/生产失败 | env、feature flag、版本、路径、权限 |
 | stale cache | 清缓存后恢复、旧状态复现 | browser / CDN / Redis / build cache |
 | resource leak | OOM、句柄增长、慢性崩溃 | lifecycle、subscription、retention、cleanup |
+| performance regression | 变慢、CPU / IO / 查询耗时升高、吞吐下降 | baseline、profiler、query plan、bisect |
 | trust boundary drift | LLM / 用户输入 / 外部响应被当成可信 | validation、escaping、policy gate |
 | timing guess / flaky wait | sleep / setTimeout / timeout 增大后偶尔通过 | 真实完成条件、事件、文件、状态或队列计数 |
 
@@ -285,6 +299,39 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 
 探针不能变成修复。进入 `cc-do` 前，要么删除，要么明确写入 repair task 的清理 / 转正方式。
 
+## Feedback Loop Contract
+
+根因调查首先依赖一个可信 loop：
+
+- loop type: failing test / HTTP script / CLI fixture / browser script / trace replay / throwaway harness / property-fuzz / bisect / differential / HITL
+- command or manual driver
+- expected failing signal
+- actual failing signal
+- symptom match: 为什么它复现的是用户报告的同一个问题
+- runtime and determinism
+- failure rate for flaky bugs
+- sharpening plan: 如何让它更快、更准、更稳定
+
+把 loop 当成调查产品来迭代。已有 loop 但信号差时，先优化它：
+
+1. faster：缓存 setup、缩小 test scope、跳过无关启动。
+2. sharper：断言用户看见的具体症状，不用“没有崩溃”冒充匹配。
+3. more deterministic：固定时间、随机种子、filesystem、network、locale、feature flag。
+
+flaky bug 的目标不是立刻 100% 复现，而是提高复现率直到可调试。可以循环 100 次、并行触发、加压力、缩小时序窗口或做 differential loop；如果失败率仍低到不可证伪，先写 Evidence Request，不要继续猜。
+
+没有 loop 时，不能把代码阅读当成根因。只能写 `Evidence Request`：需要可复现环境、HAR、日志 dump、core dump、带时间戳录屏，或临时生产探针权限。
+
+## Correct Test Seam
+
+进入 repair handoff 前，必须说明回归测试缝隙是否正确：
+
+- test seam
+- public interface exercised
+- why this seam reaches the real trigger chain
+- why a shallower test would be false confidence
+- if no correct seam exists, record it as an architecture finding and keep repair verification tied to the original feedback loop
+
 ## Timing And Flaky Bugs
 
 遇到 flaky、sleep、timeout、重试后消失：
@@ -345,6 +392,14 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 2. 不能拆但仍是根因跨度，写明为什么。
 3. 如果已经变成设计 / 架构范围，reroute 到 `cc-plan`。
 
+## Prevention Handoff
+
+根因冻结后必须写一句后验判断：什么结构、测试 seam、capability invariant、operator guard 或文档会让这个 bug 更早暴露或根本不出现。
+
+- 如果答案是小范围 regression test，把它写进当前 repair task。
+- 如果答案是 seam / module / capability 边界问题，把它写成 architecture finding，并明确交给 `cc-plan` 或后续 backlog。
+- 如果答案只是流程提醒或人工记忆，不算预防；要么转成可执行 guard，要么明确不记录。
+
 ## Escalation Decision
 
 三次假设失败后，不准继续硬猜。`analysis.md` 必须写：
@@ -353,6 +408,7 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 - what was attempted
 - why current entry is suspect
 - next option：`continue-with-new-hypothesis` / `instrument-and-wait` / `human-review` / `reroute-cc-plan`
+- evidence request if the loop cannot be built or the environment is missing
 - recommendation
 
 ## Good Output
@@ -362,6 +418,7 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 - 假设不是列表装饰，而是带证伪方法和实际观察
 - 历史调查、最近改动、模式分析没有被跳过
 - 修复边界清楚到 `cc-do` 不需要二次调查
+- 正确测试缝隙写清楚，不用浅层测试制造假安全
 - `planning/tasks.md` 只包含修复任务，不夹带新需求
 - 如果应该回 `cc-plan`，理由写清楚，不假装还能继续 patch
 
@@ -377,14 +434,15 @@ NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
 ## Working Rules
 
 1. 没有复现，不准声称找到了根因。
-2. 没有证据，不准把猜测写成结论。
-3. 先根因，再修复；先调查，再编码。
-4. `planning/tasks.md` 必须足够让 `cc-do` 在脱离当前对话后继续推进。
-5. 如果修复方案已经变成新 feature 设计，停止 debug，回 `cc-plan`。
-6. 三次假设失败后，默认说明你的调查入口错了，不准继续硬猜。
-7. 外部调研必须先脱敏，调研结论必须回到本仓库证据验证。
-8. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
-9. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
+2. 没有可信 feedback loop，不准把代码阅读包装成 confirmed root cause。
+3. 没有证据，不准把猜测写成结论。
+4. 先根因，再修复；先调查，再编码。
+5. `planning/tasks.md` 必须足够让 `cc-do` 在脱离当前对话后继续推进。
+6. 如果修复方案已经变成新 feature 设计，停止 debug，回 `cc-plan`。
+7. 三次假设失败后，默认说明你的调查入口错了，不准继续硬猜。
+8. 外部调研必须先脱敏，调研结论必须回到本仓库证据验证。
+9. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
+10. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
 
 ## Exit Criteria