@tea-agent/loop-agent 0.7.4 → 0.8.0

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（见 `docs/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（见 `docs/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% 的"无根因"案例是不完整调查。

package/docs/harness-methodology-tdd.md

@@ -1,130 +1,130 @@
-# Harness Methodology: Test-Driven Development
-
-从 Superpowers `test-driven-development` skill 中提取的 TDD 纪律，适配本仓库 harness 工作流。
-
-## Iron Law
-
-```
-NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
-```
-
-在测试之前写的任何实现代码，必须在写测试前删除。不是"留作参考"、不是"边写测试边改"——删除就是删除，从零开始实现。
-
-## RED-GREEN-REFACTOR 循环
-
-### RED：写一个失败测试
-
-写一个最小的测试，展示代码应该做什么。
-
-**要求：**
-- 一个行为
-- 清晰的命名
-- 真实代码（除非不可避免才 mock）
-
-```
-✅ test('rejects empty email', async () => {
-     const result = await submitForm({ email: '' });
-     expect(result.error).toBe('Email required');
-   })
-
-❌ test('retry works', ...)  // 名字模糊
-❌ test('validates email and domain and whitespace')  // 一次测太多
-```
-
-### Verify RED：看着它失败
-
-**不可跳过。**
-
-```bash
-npm test path/to/test.test.ts
-```
-
-确认：
-- 测试**失败**（不是报错）
-- 失败原因是你预期的（因为功能还没实现，而不是拼写错误）
-- 测试通过？→ 你在测已有行为，修正测试。测试报错？→ 修复错误，重新跑到真的失败为止。
-
-### GREEN：最小实现
-
-写刚好能让测试通过的最简单代码。不要加功能、不要重构其他代码、不要"顺手优化"。
-
-### Verify GREEN：看着它通过
-
-**不可跳过。**
-
-```bash
-npm test path/to/test.test.ts
-```
-
-确认：
-- 测试通过
-- 其他测试依然通过
-- 输出干净（无 error、warning）
-
-### REFACTOR：清理
-
-只在 GREEN 之后：
-- 消除重复
-- 改善命名
-- 提取辅助函数
-
-保持测试绿色。不添加行为。
-
-## 为什么顺序重要
-
-**"我先写实现再补测试"** → 实现后写的测试立即通过，这什么都证明不了。你可能测了错误的东西、漏了边界情况、从未见过它抓到 bug。测试先行迫使你看到测试失败，证明它确实在测有意义的东西。
-
-**"我已经手工测过了"** → 手工测试是临时的。没有记录、不能重跑、压力下容易忘。"刚刚试了能用" ≠ 全面覆盖。自动化测试是系统性的，每次跑得一样。
-
-**"删掉已写代码太浪费"** → 沉没成本谬误。时间已经花了。现在的选择是：(a) 删掉重写 TDD（X 小时，高信心）vs (b) 保留它然后补测试（30 分钟，低信心，大概率有 bug）。保留不可信的代码才是真正的浪费。
-
-## TDD 与 Harness 工作流的对齐
-
-| TDD 阶段 | Harness 步骤 |
-|----------|-------------|
-| RED | Contract → 写验收标准（含测试预期） |
-| GREEN | Implement → 最小实现 |
-| REFACTOR | Verify 通过后可做受控清理 |
-| 循环 | 下一个工作块 |
-
-## 验证清单
-
-在标记工作完成前：
-
-- [ ] 每个新函数/方法有对应测试
-- [ ] 看过每个测试在实现前失败
-- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
-- [ ] 为每个测试写了最小实现
-- [ ] 所有测试通过
-- [ ] 输出干净（无 error、warning）
-- [ ] 测试使用真实代码（仅在不可避免时 mock）
-- [ ] 边界情况和错误路径已覆盖
-
-无法勾完所有框 → 跳过了 TDD → 从 RED 重新开始。
-
-## 反模式
-
-- **测试 mock 行为而非真实行为**：mock 只在调用外部 API/DB 等不可避免时使用
-- **给生产类加仅测试用的方法**：设计接口应同时对生产者和消费者友好
-- **不理解依赖就 mock**：先理解数据流，再 mock
-
-## Bug 修复的 TDD
-
-发现 bug → 先写复现它的失败测试 → RED-GREEN-REFACTOR → 测试即证明修复有效且防止回归。
-
-永远不要在没有测试的情况下修 bug。
-
-## 当卡住时
-
-| 问题 | 解法 |
-|------|------|
-| 不知道怎么写测试 | 先写期望的 API 调用方式；先写断言 |
-| 测试太复杂 | 设计太复杂，简化接口 |
-| 必须 mock 一切 | 代码耦合太重，用依赖注入 |
-| 测试 setup 巨大 | 提取辅助函数；还是复杂？简化设计 |
-
-## 参考
-
-- Harness 工作流：`docs/feature-workflow.md`
-- 验证矩阵：`docs/verification-matrix.md`
-- Sprint Contract 模板：`docs/templates/sprint-contract.md`
+# Harness Methodology: Test-Driven Development
+
+从 Superpowers `test-driven-development` skill 中提取的 TDD 纪律，适配本仓库 harness 工作流。
+
+## Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+在测试之前写的任何实现代码，必须在写测试前删除。不是"留作参考"、不是"边写测试边改"——删除就是删除，从零开始实现。
+
+## RED-GREEN-REFACTOR 循环
+
+### RED：写一个失败测试
+
+写一个最小的测试，展示代码应该做什么。
+
+**要求：**
+- 一个行为
+- 清晰的命名
+- 真实代码（除非不可避免才 mock）
+
+```
+✅ test('rejects empty email', async () => {
+     const result = await submitForm({ email: '' });
+     expect(result.error).toBe('Email required');
+   })
+
+❌ test('retry works', ...)  // 名字模糊
+❌ test('validates email and domain and whitespace')  // 一次测太多
+```
+
+### Verify RED：看着它失败
+
+**不可跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试**失败**（不是报错）
+- 失败原因是你预期的（因为功能还没实现，而不是拼写错误）
+- 测试通过？→ 你在测已有行为，修正测试。测试报错？→ 修复错误，重新跑到真的失败为止。
+
+### GREEN：最小实现
+
+写刚好能让测试通过的最简单代码。不要加功能、不要重构其他代码、不要"顺手优化"。
+
+### Verify GREEN：看着它通过
+
+**不可跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试依然通过
+- 输出干净（无 error、warning）
+
+### REFACTOR：清理
+
+只在 GREEN 之后：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+
+保持测试绿色。不添加行为。
+
+## 为什么顺序重要
+
+**"我先写实现再补测试"** → 实现后写的测试立即通过，这什么都证明不了。你可能测了错误的东西、漏了边界情况、从未见过它抓到 bug。测试先行迫使你看到测试失败，证明它确实在测有意义的东西。
+
+**"我已经手工测过了"** → 手工测试是临时的。没有记录、不能重跑、压力下容易忘。"刚刚试了能用" ≠ 全面覆盖。自动化测试是系统性的，每次跑得一样。
+
+**"删掉已写代码太浪费"** → 沉没成本谬误。时间已经花了。现在的选择是：(a) 删掉重写 TDD（X 小时，高信心）vs (b) 保留它然后补测试（30 分钟，低信心，大概率有 bug）。保留不可信的代码才是真正的浪费。
+
+## TDD 与 Harness 工作流的对齐
+
+| TDD 阶段 | Harness 步骤 |
+|----------|-------------|
+| RED | Contract → 写验收标准（含测试预期） |
+| GREEN | Implement → 最小实现 |
+| REFACTOR | Verify 通过后可做受控清理 |
+| 循环 | 下一个工作块 |
+
+## 验证清单
+
+在标记工作完成前：
+
+- [ ] 每个新函数/方法有对应测试
+- [ ] 看过每个测试在实现前失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 为每个测试写了最小实现
+- [ ] 所有测试通过
+- [ ] 输出干净（无 error、warning）
+- [ ] 测试使用真实代码（仅在不可避免时 mock）
+- [ ] 边界情况和错误路径已覆盖
+
+无法勾完所有框 → 跳过了 TDD → 从 RED 重新开始。
+
+## 反模式
+
+- **测试 mock 行为而非真实行为**：mock 只在调用外部 API/DB 等不可避免时使用
+- **给生产类加仅测试用的方法**：设计接口应同时对生产者和消费者友好
+- **不理解依赖就 mock**：先理解数据流，再 mock
+
+## Bug 修复的 TDD
+
+发现 bug → 先写复现它的失败测试 → RED-GREEN-REFACTOR → 测试即证明修复有效且防止回归。
+
+永远不要在没有测试的情况下修 bug。
+
+## 当卡住时
+
+| 问题 | 解法 |
+|------|------|
+| 不知道怎么写测试 | 先写期望的 API 调用方式；先写断言 |
+| 测试太复杂 | 设计太复杂，简化接口 |
+| 必须 mock 一切 | 代码耦合太重，用依赖注入 |
+| 测试 setup 巨大 | 提取辅助函数；还是复杂？简化设计 |
+
+## 参考
+
+- Harness 工作流：`docs/feature-workflow.md`
+- 验证矩阵：`docs/verification-matrix.md`
+- Sprint Contract 模板：`docs/templates/sprint-contract.md`

package/docs/harness-methodology-verification.md

@@ -1,27 +1,27 @@
-# 验证方法论
-
-完成声明需要当前证据。
-
-## 门禁函数
-
-1. 确定能证明声明的命令
-2. 完整运行该命令
-3. 读输出与 exit code
-4. 修失败或报告确切失败状态
-5. 然后再声明结果
-
-## 常见门禁
-
-| 声明 | 命令 |
-|---|---|
-| 治理有效 | `bash scripts/check-repo.sh` |
-| TypeScript 编译通过 | `npm run typecheck` |
-| 行为有覆盖 | `npm test` |
-| 完整本地交付有效 | `bash scripts/ci.sh` |
-
-## Red Flags
-
-- 凭意图声明完成
-- 依赖陈旧命令输出
-- 用窄检查支撑宽声明
-- 跳过失败命令的细节
+# 验证方法论
+
+完成声明需要当前证据。
+
+## 门禁函数
+
+1. 确定能证明声明的命令
+2. 完整运行该命令
+3. 读输出与 exit code
+4. 修失败或报告确切失败状态
+5. 然后再声明结果
+
+## 常见门禁
+
+| 声明 | 命令 |
+|---|---|
+| 治理有效 | `bash scripts/check-repo.sh` |
+| TypeScript 编译通过 | `npm run typecheck` |
+| 行为有覆盖 | `npm test` |
+| 完整本地交付有效 | `bash scripts/ci.sh` |
+
+## Red Flags
+
+- 凭意图声明完成
+- 依赖陈旧命令输出
+- 用窄检查支撑宽声明
+- 跳过失败命令的细节