@tea-agent/loop-agent 0.13.0 → 0.15.0

package/docs/architecture/worker-and-feature.md

@@ -1,85 +1,85 @@
-# Worker 与 Feature 架构
-
-本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与 Observe。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
-
-## 核心事实：子进程，非 in-process
-
-`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
-
-| 事实 | 源码入口 |
-| --- | --- |
-| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
-| 执行入口 | `LoopAgentClient.run(args, options)` |
-| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
-| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
-
-`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
-
-## controller identity（冻结的已发布 controller）
-
-每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
-
-| 字段 | 含义 |
-| --- | --- |
-| `schemaVersion` | 固定 `1` |
-| `packageName` | 必须为 `@tea-agent/loop-agent` |
-| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
-| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
-| `binarySha256` | `actualEntry` 二进制 hash |
-| `packageVersion` | `package.json` version |
-| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
-
-关键方法：
-
-- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
-- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
-- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
-
-CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
-
-controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
-
-## 独立 CLI
-
-`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
-
-## 产品线 read model
-
-### TaskSpec
-
-- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
-- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
-
-### Task Pool
-
-- 唯一 runtime root：`src/worker/pool/run-store.ts`
-  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
-- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
-- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
-- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
-- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
-- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
-- batch / retry / morning report 等都基于此根。
-
-### Feature（M2 交付闭环）
-
-- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
-- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
-- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
-- 权威证据：`CHANGELOG.md [0.10.0]`、`ai_workspace/loop-agent/reports/2026-07-12-m2-completion-audit.md`。
-
-### Observe（只读 read model）
-
-- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
-- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
-- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
-
-## 版本化自举的 deterministic canary
-
-源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
-
-## 不变式
-
-- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
-- Worker 不实现 executor、scheduler、prompt 或 write guard。
-- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。
+# Worker 与 Feature 架构
+
+本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与 Observe。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
+
+## 核心事实：子进程，非 in-process
+
+`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
+
+| 事实 | 源码入口 |
+| --- | --- |
+| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
+| 执行入口 | `LoopAgentClient.run(args, options)` |
+| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
+| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
+
+`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
+
+## controller identity（冻结的已发布 controller）
+
+每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `schemaVersion` | 固定 `1` |
+| `packageName` | 必须为 `@tea-agent/loop-agent` |
+| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
+| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
+| `binarySha256` | `actualEntry` 二进制 hash |
+| `packageVersion` | `package.json` version |
+| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
+
+关键方法：
+
+- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
+- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
+- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
+
+CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
+
+controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
+
+## 独立 CLI
+
+`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
+
+## 产品线 read model
+
+### TaskSpec
+
+- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
+- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
+
+### Task Pool
+
+- 唯一 runtime root：`src/worker/pool/run-store.ts`
+  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
+- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
+- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
+- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
+- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
+- batch / retry / morning report 等都基于此根。
+
+### Feature（M2 交付闭环）
+
+- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
+- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
+- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
+- 权威证据：`CHANGELOG.md [0.10.0]`、`ai_workspace/loop-agent/reports/2026-07-12-m2-completion-audit.md`。
+
+### Observe（只读 read model）
+
+- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
+- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
+- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
+
+## 版本化自举的 deterministic canary
+
+源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
+
+## 不变式
+
+- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
+- Worker 不实现 executor、scheduler、prompt 或 write guard。
+- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。

package/docs/harness-methodology-debugging.md

@@ -1,153 +1,153 @@
-# Harness Methodology: Systematic Debugging
-
-从 Superpowers `systematic-debugging` skill 中提取的调试方法，适配本仓库 harness 工作流。
-
-## Iron Law
-
-```
-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-```
-
-没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
-
-## 何时使用
-
-适用于任何技术问题：
-- 测试失败
-- 生产 bug
-- 意外行为
-- 性能问题
-- 构建/集成失败
-
-**尤其要在以下情况使用：**
-- 时间压力下（紧急情况最容易让人猜）
-- "一个快速修复"看起来很明显
-- 已经试过多次修复
-- 上一个修复没奏效
-- 不完全理解问题
-
-## 四阶段流程
-
-每个阶段必须完成才能进入下一个。
-
-### Phase 1：根因调查
-
-**在尝试任何修复之前：**
-
-1. **仔细读错误信息**
-   - 不要跳过 error 和 warning
-   - 错误信息常常包含精确的解决方案
-   - 完整读 stack trace
-   - 记下文件名、行号、错误码
-
-2. **稳定复现**
-   - 能可靠触发吗？
-   - 精确步骤是什么？
-   - 每次都发生？
-   - 如果不能复现 → 收集更多数据，不要猜
-
-3. **检查最近变更**
-   - 什么改动可能导致这个问题？
-   - `git diff`、最近提交
-   - 新依赖、配置变更
-   - 环境差异
-
-4. **多组件系统：收集跨层证据**
-
-   当系统涉及多个组件（CI → build → sign, API → service → DB）：
-   ```
-   对每个组件边界：
-     - 记录进入组件的数据
-     - 记录离开组件的数据
-     - 验证环境/配置传播
-     - 检查每层状态
-
-   跑一次收集证据 → 分析证据确定失败组件 → 针对该组件调查
-   ```
-
-5. **追踪数据流**
-
-   当错误在深层调用栈中：
-   - 坏值从哪里来？
-   - 谁用坏值调用了这里？
-   - 持续向上追踪直到源头
-   - 在源头修复，不在症状处修复
-
-### Phase 2：模式分析
-
-1. **找工作中的例子** — 在同一个代码库里定位相似的工作代码
-2. **对照参考实现** — 完整阅读参考实现，不要跳读
-3. **识别差异** — 列出工作和失败之间的每一项差异，再小也不假设"这不重要"
-4. **理解依赖** — 需要哪些其他组件、设置、配置、假设？
-
-### Phase 3：假设与测试
-
-1. **形成单一假设** — "我认为 X 是根因，因为 Y"
-2. **最小测试** — 做最小的改动来测试假设，一次只变一个变量
-3. **验证后再继续** — 成功了？→ Phase 4。没成功？→ 形成新假设。不要在原假设上叠加更多修复
-
-### Phase 4：实现
-
-1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `harness-methodology-tdd.md`）
-2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
-3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
-4. **如果修复无效**：
-   - 尝试了几个修复？
-   - < 3 个 → 回到 Phase 1 重新分析
-   - **≥ 3 个 → 停止，质疑架构（Phase 4.5）**
-
-### Phase 4.5：质疑架构
-
-**以下模式表明架构问题：**
-- 每次修复暴露新的共享状态/耦合/不同位置的问题
-- 修复需要"大规模重构"才能实现
-- 每次修复在其他地方产生新症状
-
-**停止并质疑基础：**
-- 这个模式从根本上正确吗？
-- 我们是否在"靠惯性坚持它"？
-- 是否应该重构架构，而不是继续修症状？
-
-在尝试更多修复之前讨论。
-
-## Red Flags：停止并回到 Phase 1
-
-如果你发现自己这样想：
-- "先快速修一下，后面再调查"
-- "试试改 X 看看行不行"
-- "一次改多个东西然后跑测试"
-- "跳过测试，手工验证就行"
-- "大概就是 X 的问题，直接修吧"
-- "不太确定但可能有用"
-- "再试一个修复"（已经试了 2+ 次）
-
-**以上任何一种 → 停止。回到 Phase 1。**
-
-## 和 Harness 工作流的对齐
-
-| 调试阶段 | Harness 步骤 |
-|---------|-------------|
-| Phase 1：根因调查 | Baseline：先验证当前基线，确认 bug 是可复现的 |
-| Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
-| Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
-| Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
-| Phase 4.5：质疑架构 | 可能需要新的 exec plan |
-
-## 快速参考
-
-| 阶段 | 关键活动 | 成功标准 |
-|------|---------|---------|
-| 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
-| 2. 模式 | 找工作中的例子、对比 | 识别差异 |
-| 3. 假设 | 形成理论、最小测试 | 确认或新假设 |
-| 4. 实现 | 创建测试、修复、验证 | Bug 解决、测试通过 |
-
-## 当流程揭示"无根因"时
-
-如果系统性调查揭示问题确实属于环境性、时序性或外部依赖：
-1. 已完成流程（不是跳过）
-2. 记录调查了什么
-3. 实现适当处理（重试、超时、错误提示）
-4. 添加监控/日志供将来调查
-
-**但是：** 95% 的"无根因"案例是不完整调查。
+# Harness Methodology: Systematic Debugging
+
+从 Superpowers `systematic-debugging` skill 中提取的调试方法，适配本仓库 harness 工作流。
+
+## Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
+
+## 何时使用
+
+适用于任何技术问题：
+- 测试失败
+- 生产 bug
+- 意外行为
+- 性能问题
+- 构建/集成失败
+
+**尤其要在以下情况使用：**
+- 时间压力下（紧急情况最容易让人猜）
+- "一个快速修复"看起来很明显
+- 已经试过多次修复
+- 上一个修复没奏效
+- 不完全理解问题
+
+## 四阶段流程
+
+每个阶段必须完成才能进入下一个。
+
+### Phase 1：根因调查
+
+**在尝试任何修复之前：**
+
+1. **仔细读错误信息**
+   - 不要跳过 error 和 warning
+   - 错误信息常常包含精确的解决方案
+   - 完整读 stack trace
+   - 记下文件名、行号、错误码
+
+2. **稳定复现**
+   - 能可靠触发吗？
+   - 精确步骤是什么？
+   - 每次都发生？
+   - 如果不能复现 → 收集更多数据，不要猜
+
+3. **检查最近变更**
+   - 什么改动可能导致这个问题？
+   - `git diff`、最近提交
+   - 新依赖、配置变更
+   - 环境差异
+
+4. **多组件系统：收集跨层证据**
+
+   当系统涉及多个组件（CI → build → sign, API → service → DB）：
+   ```
+   对每个组件边界：
+     - 记录进入组件的数据
+     - 记录离开组件的数据
+     - 验证环境/配置传播
+     - 检查每层状态
+
+   跑一次收集证据 → 分析证据确定失败组件 → 针对该组件调查
+   ```
+
+5. **追踪数据流**
+
+   当错误在深层调用栈中：
+   - 坏值从哪里来？
+   - 谁用坏值调用了这里？
+   - 持续向上追踪直到源头
+   - 在源头修复，不在症状处修复
+
+### Phase 2：模式分析
+
+1. **找工作中的例子** — 在同一个代码库里定位相似的工作代码
+2. **对照参考实现** — 完整阅读参考实现，不要跳读
+3. **识别差异** — 列出工作和失败之间的每一项差异，再小也不假设"这不重要"
+4. **理解依赖** — 需要哪些其他组件、设置、配置、假设？
+
+### Phase 3：假设与测试
+
+1. **形成单一假设** — "我认为 X 是根因，因为 Y"
+2. **最小测试** — 做最小的改动来测试假设，一次只变一个变量
+3. **验证后再继续** — 成功了？→ Phase 4。没成功？→ 形成新假设。不要在原假设上叠加更多修复
+
+### Phase 4：实现
+
+1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `harness-methodology-tdd.md`）
+2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
+3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
+4. **如果修复无效**：
+   - 尝试了几个修复？
+   - < 3 个 → 回到 Phase 1 重新分析
+   - **≥ 3 个 → 停止，质疑架构（Phase 4.5）**
+
+### Phase 4.5：质疑架构
+
+**以下模式表明架构问题：**
+- 每次修复暴露新的共享状态/耦合/不同位置的问题
+- 修复需要"大规模重构"才能实现
+- 每次修复在其他地方产生新症状
+
+**停止并质疑基础：**
+- 这个模式从根本上正确吗？
+- 我们是否在"靠惯性坚持它"？
+- 是否应该重构架构，而不是继续修症状？
+
+在尝试更多修复之前讨论。
+
+## Red Flags：停止并回到 Phase 1
+
+如果你发现自己这样想：
+- "先快速修一下，后面再调查"
+- "试试改 X 看看行不行"
+- "一次改多个东西然后跑测试"
+- "跳过测试，手工验证就行"
+- "大概就是 X 的问题，直接修吧"
+- "不太确定但可能有用"
+- "再试一个修复"（已经试了 2+ 次）
+
+**以上任何一种 → 停止。回到 Phase 1。**
+
+## 和 Harness 工作流的对齐
+
+| 调试阶段 | Harness 步骤 |
+|---------|-------------|
+| Phase 1：根因调查 | Baseline：先验证当前基线，确认 bug 是可复现的 |
+| Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
+| Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
+| Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
+| Phase 4.5：质疑架构 | 可能需要新的 exec plan |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|------|---------|---------|
+| 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
+| 2. 模式 | 找工作中的例子、对比 | 识别差异 |
+| 3. 假设 | 形成理论、最小测试 | 确认或新假设 |
+| 4. 实现 | 创建测试、修复、验证 | Bug 解决、测试通过 |
+
+## 当流程揭示"无根因"时
+
+如果系统性调查揭示问题确实属于环境性、时序性或外部依赖：
+1. 已完成流程（不是跳过）
+2. 记录调查了什么
+3. 实现适当处理（重试、超时、错误提示）
+4. 添加监控/日志供将来调查
+
+**但是：** 95% 的"无根因"案例是不完整调查。