cc-devflow 4.5.1 → 4.5.2

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

@@ -68,6 +68,18 @@ function deriveVerdict(manifest, quickGates, strictGates, review) {
     return 'fail';
   }
 
+  if ([...quickGates, ...strictGates].some((gate) => ['blocked', 'pending'].includes(gate.status))) {
+    return 'blocked';
+  }
+
+  if (review.qa?.status === 'fail') {
+    return 'fail';
+  }
+
+  if (['blocked', 'pending'].includes(review.qa?.status)) {
+    return 'blocked';
+  }
+
   if (review.status === 'blocked') {
     return 'blocked';
   }
@@ -76,6 +88,20 @@ function deriveVerdict(manifest, quickGates, strictGates, review) {
     return 'fail';
   }
 
+  const freshness = buildReviewFreshness(review).status;
+  if (review.status === 'pass' && !['fresh', 'not-applicable'].includes(freshness)) {
+    return 'blocked';
+  }
+
+  const openOwnedFailures = (review.runtime?.failureOwnership || []).some((item) => {
+    const classification = item.classification || '';
+    const status = item.status || 'open';
+    return ['in-branch', 'ambiguous'].includes(classification) && !['resolved', 'closed'].includes(status);
+  });
+  if (openOwnedFailures) {
+    return 'blocked';
+  }
+
   return 'pass';
 }
 
@@ -116,10 +142,139 @@ function buildSummary({ quickGates, strictGates, review, verdict }) {
   ].join(' ');
 }
 
+function claimFromGate(gate) {
+  const name = String(gate.name || '').toLowerCase();
+  if (/test|spec/.test(name)) {
+    return 'tests-pass';
+  }
+  if (/lint/.test(name)) {
+    return 'lint-clean';
+  }
+  if (/type/.test(name)) {
+    return 'typecheck-clean';
+  }
+  if (/build|compile/.test(name)) {
+    return 'build-succeeds';
+  }
+  return `gate-${gate.name || 'unknown'}`;
+}
+
+function buildClaimEvidence({ manifest, quickGates, strictGates, review }) {
+  const gateClaims = [...quickGates, ...strictGates].map((gate) => ({
+    claim: claimFromGate(gate),
+    requiredProof: 'fresh command output with exit status and key observation',
+    commandOrArtifact: gate.command || gate.name || '',
+    exitStatus: gate.exitStatus ?? null,
+    keyObservation: gate.summary || gate.details || '',
+    status: gate.status || 'blocked'
+  }));
+
+  const openTasks = (manifest.tasks || []).filter((task) => task.status !== 'done' && task.status !== 'completed');
+  gateClaims.push({
+    claim: 'requirements-met',
+    requiredProof: 'line-by-line planning/tasks.md and task-manifest.json checklist',
+    commandOrArtifact: 'planning/tasks.md + planning/task-manifest.json',
+    exitStatus: null,
+    keyObservation: openTasks.length === 0 ? 'no open task gaps recorded' : `${openTasks.length} open task gaps recorded`,
+    status: openTasks.length === 0 && review.status === 'pass' ? 'pass' : 'blocked'
+  });
+
+  return [...(review.claimEvidence || []), ...gateClaims];
+}
+
+function buildQa(review) {
+  return {
+    status: review.qa?.status || 'skipped',
+    regressionProof: review.qa?.regressionProof || [],
+    testQuality: review.qa?.testQuality || [],
+    coverageAudit: review.qa?.coverageAudit || {
+      status: 'skipped',
+      coveragePct: null,
+      pathMap: [],
+      gaps: [],
+      testsAdded: [],
+      e2eRequired: false,
+      evalRequired: false,
+      qualityStars: ''
+    },
+    browserEvidence: review.qa?.browserEvidence || {
+      status: 'skipped',
+      mode: 'not-applicable',
+      affectedRoutes: [],
+      screenshots: [],
+      consoleErrors: [],
+      healthScore: null,
+      issues: [],
+      skipReason: 'not recorded'
+    },
+    tddException: review.qa?.tddException || null
+  };
+}
+
+function buildRuntime(review) {
+  const failureOwnership = review.runtime?.failureOwnership || [];
+  const hasOpenOwnedFailure = failureOwnership.some((item) => {
+    const classification = item.classification || '';
+    const status = item.status || 'open';
+    return ['in-branch', 'ambiguous'].includes(classification) && !['resolved', 'closed'].includes(status);
+  });
+
+  return {
+    status: review.runtime?.status || (hasOpenOwnedFailure ? 'blocked' : 'pass'),
+    failureOwnership
+  };
+}
+
+function firstReviewHead(review) {
+  return [
+    review.taskReviews?.reviewPacket?.headSha,
+    review.diffReview?.reviewPacket?.headSha
+  ].find((value) => typeof value === 'string' && value.length > 0) || '';
+}
+
+function buildReviewFreshness(review) {
+  if (review.freshness) {
+    return review.freshness;
+  }
+
+  const headSha = firstReviewHead(review);
+  if (!headSha) {
+    return {
+      status: 'unknown',
+      reviewedCommit: '',
+      currentCommit: '',
+      commitsSinceReview: null,
+      staleReason: 'review headSha is not recorded'
+    };
+  }
+
+  return {
+    status: 'fresh',
+    reviewedCommit: headSha,
+    currentCommit: headSha,
+    commitsSinceReview: 0,
+    staleReason: ''
+  };
+}
+
+function buildReview(review) {
+  return {
+    ...review,
+    freshness: buildReviewFreshness(review),
+    qualityScore: review.qualityScore ?? null,
+    specialistReviews: review.specialistReviews || []
+  };
+}
+
+function isFindingOpen(item) {
+  const status = item.status || item.triageStatus || '';
+  return !['resolved', 'accepted', 'informational', 'accepted-fixed', 'rejected-with-evidence', 'deferred-minor'].includes(status);
+}
+
 function summarizeOpenReviewFindings(findings = []) {
   return findings
-    .filter((item) => item.status !== 'resolved' && item.status !== 'accepted' && item.status !== 'informational')
-    .map((item) => `${item.source}: ${item.summary}`);
+    .filter(isFindingOpen)
+    .map((item) => `${item.source || 'review'}: ${item.summary || item.evidence || 'open finding'}`);
 }
 
 function collectBlockingFindings({ manifest, quickGates, strictGates, review }) {
@@ -132,8 +287,8 @@ function collectBlockingFindings({ manifest, quickGates, strictGates, review })
   }
 
   for (const gate of [...quickGates, ...strictGates]) {
-    if (gate.status === 'fail') {
-      findings.push(`${gate.name}: ${gate.details}`);
+    if (['fail', 'blocked', 'pending'].includes(gate.status)) {
+      findings.push(`${gate.name}: ${gate.details || gate.summary || gate.status}`);
     }
   }
 
@@ -200,6 +355,15 @@ function main() {
     blockingFindings
   });
   const specSignals = deriveSpecSignals(manifest, verdict, review);
+  const claimEvidence = buildClaimEvidence({
+    manifest,
+    quickGates,
+    strictGates,
+    review
+  });
+  const runtime = buildRuntime(review);
+  const qa = buildQa(review);
+  const reviewReport = buildReview(review);
 
   const report = {
     changeId: args.changeId,
@@ -214,9 +378,12 @@ function main() {
     specAlignment: specSignals.specAlignment,
     specDeltaVerified: specSignals.specDeltaVerified,
     specSyncReady: specSignals.specSyncReady,
+    runtime,
+    claimEvidence,
+    qa,
     quickGates,
     strictGates,
-    review,
+    review: reviewReport,
     blockingFindings,
     gaps: manifest.spec?.newGaps || [],
     reroute,

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

@@ -36,6 +36,10 @@ jq -e '
   .summary and
   .review and
   .blockingFindings and
+  (.runtime and (.runtime | type == "object")) and
+  (.runtime.status | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.runtime.failureOwnership? // []) | type == "array") and
+  ((.runtime.failureOwnership? // []) | all(.[]; (.classification? // "environment") | IN("in-branch", "pre-existing", "environment", "ambiguous"))) and
   (.specAlignment? // "blocked") and
   ((.specDeltaVerified? // false) | type == "boolean") and
   ((.specSyncReady? // false) | type == "boolean") and
@@ -45,6 +49,23 @@ jq -e '
   (.overall | IN("pass", "fail")) and
   (.reroute | IN("none", "cc-do", "cc-investigate", "cc-plan")) and
   (.review.status | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.review.freshness? // {"status":"unknown"}) | type == "object") and
+  ((.review.freshness.status? // "unknown") | IN("fresh", "stale", "unknown", "not-applicable")) and
+  ((.review.specialistReviews? // []) | type == "array") and
+  ((.claimEvidence? // []) | type == "array") and
+  ((.claimEvidence? // []) | all(.[];
+    (.claim and .requiredProof and .commandOrArtifact and .keyObservation and .status) and
+    (.status | IN("pass", "fail", "blocked", "skipped", "pending"))
+  )) and
+  ((.qa? // {"status":"skipped"}) | type == "object") and
+  ((.qa.status? // "skipped") | IN("pass", "fail", "blocked", "skipped", "pending")) and
+  ((.qa.coverageAudit? // {"status":"skipped"}) | type == "object") and
+  ((.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
+  ((.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 (((.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-investigate/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CC-Investigate Skill Changelog
 
+## 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
+- require analysis templates to record boundary matrices, caller chains, working-vs-broken comparisons, probe cleanup, root-cause class, and no-code-root-cause evidence
+- update tasks and manifest templates so repair handoffs preserve the probe/trace facts that prove the confirmed root cause
+
+## v1.1.3 - 2026-04-28
+
+- add the explicit `NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT` iron law to keep investigation separate from implementation
+- require prior investigation history, pattern analysis, falsification methods, sanitized external research, and escalation decisions before freezing a root cause
+- add repair-boundary scope lock fields for affected module, allowed files, forbidden files, blast radius, and split-or-reroute decisions
+- update analysis, tasks, and task-manifest templates with root-cause hypothesis and investigation metadata
+
 ## v1.1.2 - 2026-04-27
 
 - require investigation outputs to resolve the runtime output policy before writing analysis, task, or change metadata artifacts

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

@@ -16,6 +16,16 @@
 3. 先证伪假设，再冻结根因。
 4. `planning/analysis.md` 和 `planning/tasks.md` 必须足够让 `cc-do` 脱离当前会话继续工作。
 5. 调查失败三次后先重建入口，不准继续乱补。
+6. 没有 frozen root-cause contract，不准进入 repair task。
+7. 多组件、深层调用、flaky 问题必须先补边界探针、反向追踪或条件等待证据。
+
+## Iron Law
+
+```text
+NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
+```
+
+root-cause contract 至少包含：稳定复现或缩小后的可验证症状、被破坏的代码 / 配置 / 数据 / 依赖契约、已证伪假设、最小修复边界。
 
 ## Required Outputs
 
@@ -26,10 +36,101 @@
 ## Investigation Standard
 
 1. 先收集 symptom、expected、actual、repro。
-2. 先沿代码路径定位触点和最近变更。
-3. 每个假设都要写支持证据和反证。
-4. 只有被证据钉死的根因才能进入 repair contract。
-5. repair contract 只讲最小修复边界，不顺手发明新范围。
+2. 先查 prior investigations、TODOS/backlog、report-card finding 和最近变更。
+3. 先沿代码路径定位触点和最近变更。
+4. 先做 pattern analysis，再形成 1-3 个可证伪假设。
+5. 每个假设都要写支持证据、反证、证伪方法、预期观察、实际观察。
+6. 只有被证据钉死的根因才能进入 repair contract。
+7. repair contract 只讲最小修复边界，不顺手发明新范围。
+
+## Investigation Modes
+
+| Mode | 什么时候用 | 第一动作 |
+| --- | --- | --- |
+| `reproduce-first` | 症状真实但不稳定 | 缩小复现命令 / 手动路径 |
+| `diff-trace` | 昨天可用、今天坏了 | `git log --oneline -20 -- <affected-files>` |
+| `boundary-probe` | API -> service -> DB、CI -> build -> deploy 这类链路断裂 | 记录每层输入、输出、配置和状态 |
+| `backward-trace` | 错误出现在深层堆栈或坏值来源不明 | 从 immediate failure site 反追 original trigger |
+| `reference-compare` | 同仓库有相似可用路径 | 列出 working / broken 差异并逐项接受或排除 |
+| `condition-wait` | flaky、sleep、timeout、重试后消失 | 找真实等待条件，不先加大延时 |
+| `history-trace` | 同一区域反复坏 | 查历史 `analysis.md`、TODO、report-card finding |
+| `pattern-research` | 陌生框架 / 依赖 / 平台错误 | 脱敏后查通用错误类型 |
+| `contract-check` | 修复边界可能扩大 | 判定 implementation drift / missing spec truth / roadmap mismatch |
+
+## Pattern Analysis
+
+至少对照这些模式，不要直接猜：
+
+- race condition：间歇性、时序相关、共享状态
+- null propagation：TypeError / undefined / missing guard
+- state corruption：数据不一致、部分更新、hook / transaction 顺序
+- integration failure：timeout、协议不匹配、外部服务边界
+- configuration drift：本地 / CI / 生产表现不同
+- stale cache：清缓存后恢复或旧状态复现
+- resource leak：OOM、句柄增长、生命周期未释放
+- trust boundary drift：外部输入、LLM 输出、用户输入被当成可信
+- timing guess / flaky wait：任意 sleep / timeout / setTimeout 掩盖真实条件
+
+## Boundary And Trace Evidence
+
+复杂链路必须在 `analysis.md` 写清：
+
+- 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
+
+这些字段不是装饰。它们的作用是证明根因位于源头，而不是报错点。
+
+## Prior Investigation History
+
+形成根因前至少查：
+
+1. `git log --oneline -20 -- <affected-files>`
+2. `rg -n "<error-keyword>|<module>|<capability>" devflow/changes`
+3. `TODOS.md`、backlog、roadmap 中的相关项
+4. 既有 `planning/analysis.md` 和 `review/report-card.json`
+
+命中历史时，写入 `analysis.md` 的 `Prior Investigations`，说明这次是复发、同类结构味道，还是无关历史。
+
+## External Research Hygiene
+
+只有在本地证据不足、错误类型陌生、或像依赖 / 框架 / 平台问题时才做外部调研。
+
+- 先删除 host、IP、token、customer id、内部路径、SQL、私有 repo 名。
+- 只搜错误类别、框架 / 库名、版本、通用组件名。
+- 调研结果只能进入候选假设，必须回到本仓库复现或代码证据验证。
+
+## No Code Root Cause
+
+如果结论是环境、外部服务或时序窗口：
+
+- 写 `rootCauseClass`: `code` / `config` / `environment` / `external` / `timing`
+- 写明为什么不是 code root cause
+- 写明需要什么 monitoring / future evidence
+- 写明 operator handling，不要把未知外因包装成代码修复
+
+## Scope Lock
+
+根因假设形成后，写清：
+
+- affected module
+- allowed files
+- forbidden files
+- blast radius estimate
+- if touches >5 files: split / justify / reroute
+
+超过 5 个文件默认是调查信号，不是正常 bug-fix 规模。
+
+## Escalation
+
+三次假设失败后写 `Escalation Decision`：
+
+- failed hypothesis count
+- attempted evidence
+- why current entry is suspect
+- next option：continue / instrument-and-wait / human-review / reroute-cc-plan
+- recommendation
 
 ## Local Kit
 

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

@@ -1,6 +1,6 @@
 ---
 name: cc-investigate
-version: 1.1.2
+version: 1.1.4
 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"
@@ -34,9 +34,11 @@ 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."
+  - "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."
   - "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, confirmed root cause, and repair boundary."
+  - "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."
   - "planning/tasks.md and planning/task-manifest.json are explicit enough that cc-do can repair the bug without chat memory."
   - "The honest next step is cc-do, cc-plan, or roadmap."
 reroutes:
@@ -106,6 +108,21 @@ tool_budget:
 
 如果问题其实是在问“应该做什么功能”或“范围是否要变”，别硬调试，回 `cc-plan`。
 
+## Iron Law
+
+```text
+NO REPAIR WITHOUT A FROZEN ROOT-CAUSE CONTRACT
+```
+
+`cc-investigate` 可以跑复现、读代码、查日志、加临时探针、证伪假设，但不能把“可能是”写成 repair task。
+
+根因合同必须同时回答：
+
+1. 症状如何稳定复现或被缩小到可验证范围。
+2. 哪条代码 / 配置 / 数据 / 依赖路径违反了什么契约。
+3. 哪些假设被证伪，为什么不是它们。
+4. 最小修复边界在哪里，哪些文件明确不该动。
+
 ## Quick Start
 
 先判断你面对的是哪一类调查现实：
@@ -114,7 +131,13 @@ tool_budget:
 | --- | --- |
 | 症状真实，但还没有稳定复现 | `reproduce-first`，先把现象钉死 |
 | 明显是 regression | `diff-trace`，先查最近变化 |
+| 多组件链路断裂 | `boundary-probe`，先记录每个边界的输入、输出、配置和状态 |
+| 报错点很深或坏值来源不明 | `backward-trace`，从 symptom site 一直追到 original trigger |
+| 同仓库有相似可用路径 | `reference-compare`，先列出 working vs broken differences |
+| flaky / sleep / timeout 类问题 | `condition-wait`，先找真实等待条件，不先加大延时 |
 | 症状已知，但修复边界可能扩大范围 | `contract-check`，先判是否还属于当前 requirement |
+| 错误类型陌生，像框架 / 依赖 / 平台问题 | `pattern-research`，先做脱敏外部调研 |
+| 同一区域反复坏 | `history-trace`，先查 prior investigations 和最近修复 |
 | 看起来像 bug，实则是未定义行为或新需求 | 直接 reroute 到 `cc-plan` |
 
 先说“这是什么类问题”，再说“我要怎么修”。没有分类的 debug，最后都会变成乱打补丁。
@@ -163,29 +186,181 @@ tool_budget:
    - 记录用户看见了什么
    - 记录预期与实际差异
    - 记录复现命令或手动路径
+   - 如果上下文缺失，只问一个最关键问题，不一次性抛出问题清单
 2. **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
    - 找现有测试和断点证据
    - 判定偏离的是 capability boundary、invariant，还是只是实现细节
-3. **Form hypotheses**
+3. **Classify pattern**
+   - 判定是否属于 race condition、null propagation、state corruption、integration failure、configuration drift、stale cache、resource leak、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 个可被证伪的假设
    - 每个假设都写支持证据和反证
-4. **Test hypotheses**
+   - 每个假设都写 `falsification method`、`expected observation`、`actual observation`
+5. **Test hypotheses**
    - 用复现、日志、断言、最小探针验证
-   - 三次假设都失败，就停下重建上下文
-5. **Freeze repair contract**
+   - 临时探针必须写 `Diagnostic Instrumentation Plan`：probe location、question answered、command、expected signal、cleanup requirement
+   - 三次假设都失败，就停下进入 escalation decision
+6. **Freeze repair contract**
    - 根因确认后，写进 `planning/analysis.md`
    - 只保留最小修复边界
+   - 写明 affected module、allowed files、forbidden files、blast radius estimate；超过 5 个文件默认拆分或 reroute
    - 输出 `planning/tasks.md` + `planning/task-manifest.json` + `change-meta.json`
-6. **Hand off**
+7. **Hand off**
    - 下一步明确写成 `cc-do`
    - 如果 repair contract 越过当前 requirement，就 reroute 到 `cc-plan`
 
+## Pattern Analysis
+
+不要从空白猜测开始。先把 bug 放进一个可检查的模式：
+
+| Pattern | Signature | First place to inspect |
+| --- | --- | --- |
+| race condition | 间歇性、时序相关、重试后消失 | 并发写、锁、队列、共享状态 |
+| null propagation | TypeError / NoMethod / undefined access | nullable 输入、默认值、边界 guard |
+| state corruption | 数据不一致、部分更新、顺序错乱 | transaction、callback、hook、副作用 |
+| integration failure | timeout、unexpected response、协议不匹配 | API boundary、service config、schema |
+| configuration drift | 本地可用、CI/生产失败 | env、feature flag、版本、路径、权限 |
+| stale cache | 清缓存后恢复、旧状态复现 | browser / CDN / Redis / build cache |
+| resource leak | OOM、句柄增长、慢性崩溃 | lifecycle、subscription、retention、cleanup |
+| trust boundary drift | LLM / 用户输入 / 外部响应被当成可信 | validation、escaping、policy gate |
+| timing guess / flaky wait | sleep / setTimeout / timeout 增大后偶尔通过 | 真实完成条件、事件、文件、状态或队列计数 |
+
+模式分析不是结论，只是定位第一批证据的索引。
+
+## Boundary Probe Matrix
+
+多组件链路不要先猜。先记录每个边界的事实：
+
+- component boundary
+- input observed
+- output observed
+- config / env observed
+- state observed
+- verdict: `pass` / `fail` / `unknown`
+
+只有一个边界先失败时，后续调查才收缩到那个组件。多个边界都异常时，优先找共同上游，不在下游堆补丁。
+
+## Backward Trace Chain
+
+报错点很深时，不准只在 symptom site 加 guard。`analysis.md` 必须追到：
+
+- immediate failure site
+- direct caller
+- caller chain
+- bad value origin
+- original trigger
+- why symptom-site fix is rejected
+
+找不到 original trigger 时，根因还没有冻结，只能继续调查或进入 escalation。
+
+## Reference Comparison
+
+同仓库或参考实现有相似可用路径时，先对照再假设：
+
+- similar working example
+- broken path
+- differences found
+- differences accepted as hypothesis
+- differences ruled out
+
+不要用“看起来差不多”跳过差异。小差异也可能是根因。
+
+## Diagnostic Instrumentation
+
+临时日志、断言、探针只能用于回答一个明确问题：
+
+- probe location
+- question answered
+- command to run
+- expected signal
+- actual signal
+- cleanup requirement
+
+探针不能变成修复。进入 `cc-do` 前，要么删除，要么明确写入 repair task 的清理 / 转正方式。
+
+## Timing And Flaky Bugs
+
+遇到 flaky、sleep、timeout、重试后消失：
+
+- 先找真实等待条件：event、state、file、count、queue empty、network response
+- 任意 timeout 必须说明为什么这个时间是业务 / 协议事实，不是猜测
+- 如果只能在并发或负载下复现，记录对应命令和环境
+- 不把“加大 sleep”写成 repair contract，除非它本身就是被证实的协议等待窗口
+
+## No Code Root Cause
+
+如果调查证明是环境、外部服务或时序窗口，不要假装代码根因：
+
+- `rootCauseClass`: `code` / `config` / `environment` / `external` / `timing`
+- `why not code root cause`
+- `monitoring or future evidence needed`
+- `operator handling after fix`
+
+这类结论仍然需要本地证据支撑；“没有根因”通常只是调查不完整。
+
+## Prior Investigation History
+
+同一区域反复坏是架构味道，不是巧合。形成根因前至少查：
+
+1. `git log --oneline -20 -- <affected-files>`
+2. `rg -n "<error-keyword>|<module>|<capability>" devflow/changes`
+3. `TODOS.md`、backlog、roadmap 中的相关未解决项
+4. 既有 `report-card.json` finding 和 `planning/analysis.md`
+5. 可用时，查询项目记忆或历史调查摘要
+
+如果命中过往调查，写入 `analysis.md` 的 `Prior Investigations`，包括是否复发、根因是否同类、这次是否说明结构问题。
+
+## External Research Hygiene
+
+外部调研只在本地证据不足、错误类型陌生、或像依赖 / 框架 / 平台 bug 时使用。
+
+调研前必须脱敏：
+
+- 删除 host、IP、token、customer id、内部路径、SQL 片段、私有 repo 名
+- 搜索错误类别、框架 / 库名、版本和通用组件名
+- 如果无法安全脱敏，就跳过外部搜索，并在 `researchEvidence` 写明原因
+
+调研结论只能作为候选假设，不能直接变成 confirmed root cause。必须回到本仓库复现或代码证据验证。
+
+## Scope Lock And Blast Radius
+
+形成根因假设后，先锁定最小调查 / 修复边界：
+
+- `affectedModule`
+- `allowedFiles`
+- `forbiddenFiles`
+- `blastRadiusFiles`
+- `blastRadiusRisk`: `low` / `medium` / `high`
+
+如果修复预计触碰超过 5 个文件，默认说明这可能不是单点 bug：
+
+1. 能拆成 critical path + follow-up，就拆。
+2. 不能拆但仍是根因跨度，写明为什么。
+3. 如果已经变成设计 / 架构范围，reroute 到 `cc-plan`。
+
+## Escalation Decision
+
+三次假设失败后，不准继续硬猜。`analysis.md` 必须写：
+
+- failedHypothesisCount
+- what was attempted
+- why current entry is suspect
+- next option：`continue-with-new-hypothesis` / `instrument-and-wait` / `human-review` / `reroute-cc-plan`
+- recommendation
+
 ## Good Output
 
 - 看完第一屏就知道 bug 是什么、怎么复现、为什么会坏
 - 根因不是感觉，而是被证据钉死的具体断点
+- 假设不是列表装饰，而是带证伪方法和实际观察
+- 历史调查、最近改动、模式分析没有被跳过
 - 修复边界清楚到 `cc-do` 不需要二次调查
 - `planning/tasks.md` 只包含修复任务，不夹带新需求
 - 如果应该回 `cc-plan`，理由写清楚，不假装还能继续 patch
@@ -207,7 +382,9 @@ tool_budget:
 4. `planning/tasks.md` 必须足够让 `cc-do` 在脱离当前对话后继续推进。
 5. 如果修复方案已经变成新 feature 设计，停止 debug，回 `cc-plan`。
 6. 三次假设失败后，默认说明你的调查入口错了，不准继续硬猜。
-7. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
+7. 外部调研必须先脱敏，调研结论必须回到本仓库证据验证。
+8. 修复触点超过 5 个文件时，默认先拆分或 reroute，不把大重构伪装成 bug fix。
+9. 好的调查不是“找了很多可能性”，而是把错误世界缩成一个可信的 repair contract。
 
 ## Exit Criteria