@tea-agent/loop-agent 0.5.0 → 0.7.0

package/docs/exec-plans/README.md

@@ -1,6 +1,6 @@
-# 执行计划
-
-- `active/README.md` — 当前进行中的计划
-- `completed/README.md` — 已完成的计划
-
-影响多文件、公开命令行为或仓库治理的变更应使用 execution plan。
+# 执行计划
+
+- `active/README.md` — 当前进行中的计划
+- `completed/README.md` — 已完成的计划
+
+影响多文件、公开命令行为或仓库治理的变更应使用 execution plan。

package/docs/exec-plans/active/README.md

@@ -1,7 +1,12 @@
-# 进行中的执行计划
-
-本目录存放当前进行中的 execution plan。
-
-源码仓库可在本 README 旁保留具体 active plan 文件。npm 包只携带本 README 作为目录契约，不复制 loop-agent 源码历史的 active plan；目标仓库自行生成 active plan。
-
-当前没有 active plan。`2026-07-08-taskspec-worker-master.md` 的 7 个 step 已全部完成并归档到 `../completed/`。
+# 进行中的执行计划
+
+本目录存放当前进行中的 execution plan。
+
+源码仓库可在本 README 旁保留具体 active plan 文件。npm 包只携带本 README 作为目录契约，不复制 loop-agent 源码历史的 active plan；目标仓库自行生成 active plan。
+
+当前 active execution plan：
+
+- `2026-07-10-release-0.6.0-nightly-drill.md` — 技术演练已完成；等待 0.6.0 发布 owner 对 Day-1 provisional remediation 作明确 ratify / revise / reject。
+- `2026-07-11-round-2-interactive-ui-productization.md` — 补齐 Round-1 owner gate，发布 interactive-ui controller，完成 React A/B/C、Round 2/3 扩量、CI/cron 和产品线模板/docs CI。
+
+- 已归档：`../completed/2026-07-11-interactive-ui-writer-routing.md`、`../completed/2026-07-10-next-stage-worker-evidence.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -1,19 +1,32 @@
-# 已完成的执行计划
-
-实现与验证结束后，已完成计划移入此目录。
-
-npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
-
-- [`2026-07-02-loop-agent-subject-restructure.md`](2026-07-02-loop-agent-subject-restructure.md) — 将原 `tools/code-agent` runtime 提升到仓库根、重命名为 `loop-agent`，移除旧 memory plugin 产品线
-- [`2026-07-04-remove-level1-fallback.md`](2026-07-04-remove-level1-fallback.md) — 移除历史顺序 Level 1 fallback，runtime、文档与 command surface 收敛到 DAG 执行
-- [`2026-07-04-runtime-boundary-remediation.md`](2026-07-04-runtime-boundary-remediation.md) — 整合 CLI/skill/runtime 边界，抽出 DAG/Loop runtime seam，集中 harness store/guard 策略
-- [`2026-07-04-dag-role-skill-alignment.md`](2026-07-04-dag-role-skill-alignment.md) — 对齐 DAG/Dynamic Workflow role 与 repo-local vetted skills，新增 strict skill audit
-- [`2026-07-06-production-readiness-hardening.md`](2026-07-06-production-readiness-hardening.md) — 冻结 Production Readiness v0.1，打磨 DAG 主路径 next steps、failure routing、doctor/report/failure handoff 与 dogfood 验证
-- [`2026-07-08-taskspec-schema-validate.md`](2026-07-08-taskspec-schema-validate.md) — 新增 TaskSpec v0.1 schema、三层校验器、risk→complexity 映射和 5 个 dogfood TaskSpec 样例
-- [`2026-07-08-acceptance-taskgraph-ready.md`](2026-07-08-acceptance-taskgraph-ready.md) — 新增 AcceptanceSpec / TaskGraphSpec schema、Feature graph 校验、环检测和 Ready 队列计算
-- [`2026-07-08-profile-mapping-agent-worker-cli.md`](2026-07-08-profile-mapping-agent-worker-cli.md) — 新增 business profile 到 loop-agent profile 映射、独立 `agent-worker` CLI 和 package bin surface
-- [`2026-07-08-loop-agent-client-contract-smoke.md`](2026-07-08-loop-agent-client-contract-smoke.md) — 新增 LoopAgentClient、command artifact、JSON parse failure、repo resolver/preflight 与 Ring 0 CLI contract smoke
-- [`2026-07-08-materializer-ring1-dag.md`](2026-07-08-materializer-ring1-dag.md) — 新增 TaskSpec materializer、materialize manifest、coverage-safe source 输出与 Ring 1 DAG generate/validate/dry-run smoke
-- [`2026-07-08-run-task-pipeline-ring2.md`](2026-07-08-run-task-pipeline-ring2.md) — 新增 Worker run-task pipeline、task-local run record、成功/失败分流与 Ring 2 shell-only DAG success/failure smoke
-- [`2026-07-08-task-pool-morning-report.md`](2026-07-08-task-pool-morning-report.md) — 新增 Worker Task Pool JSONL/state store、failure routing、串行 batch run-ready 和 morning report
-- [`2026-07-08-taskspec-worker-master.md`](2026-07-08-taskspec-worker-master.md) — 完成 TaskSpec + Worker 7 步 master 编排，覆盖 schema、graph、profile、client、materialize、run-task、Task Pool 和 morning report
+# 已完成的执行计划
+
+实现与验证结束后，已完成计划移入此目录。
+
+npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
+
+- [`2026-07-02-loop-agent-subject-restructure.md`](2026-07-02-loop-agent-subject-restructure.md) — 将原 `tools/code-agent` runtime 提升到仓库根、重命名为 `loop-agent`，移除旧 memory plugin 产品线
+- [`2026-07-04-remove-level1-fallback.md`](2026-07-04-remove-level1-fallback.md) — 移除历史顺序 Level 1 fallback，runtime、文档与 command surface 收敛到 DAG 执行
+- [`2026-07-04-runtime-boundary-remediation.md`](2026-07-04-runtime-boundary-remediation.md) — 整合 CLI/skill/runtime 边界，抽出 DAG/Loop runtime seam，集中 harness store/guard 策略
+- [`2026-07-10-next-stage-worker-evidence.md`](2026-07-10-next-stage-worker-evidence.md) — Worker retry、EnvFailure、边界治理、初始化投影与真实 BE/FE/QA dogfood evidence 闭环
+- [`2026-07-11-interactive-ui-writer-routing.md`](2026-07-11-interactive-ui-writer-routing.md) — 新增 interactive-ui writer-only HIGH 路由、UI 交付契约、真实 React dogfood fixture 与 Round-2 A/B/C 实验入口
+- [`2026-07-04-dag-role-skill-alignment.md`](2026-07-04-dag-role-skill-alignment.md) — 对齐 DAG/Dynamic Workflow role 与 repo-local vetted skills，新增 strict skill audit
+- [`2026-07-06-production-readiness-hardening.md`](2026-07-06-production-readiness-hardening.md) — 冻结 Production Readiness v0.1，打磨 DAG 主路径 next steps、failure routing、doctor/report/failure handoff 与 dogfood 验证
+- [`2026-07-08-taskspec-schema-validate.md`](2026-07-08-taskspec-schema-validate.md) — 新增 TaskSpec v0.1 schema、三层校验器、risk→complexity 映射和 5 个 dogfood TaskSpec 样例
+- [`2026-07-08-acceptance-taskgraph-ready.md`](2026-07-08-acceptance-taskgraph-ready.md) — 新增 AcceptanceSpec / TaskGraphSpec schema、Feature graph 校验、环检测和 Ready 队列计算
+- [`2026-07-08-profile-mapping-agent-worker-cli.md`](2026-07-08-profile-mapping-agent-worker-cli.md) — 新增 business profile 到 loop-agent profile 映射、独立 `agent-worker` CLI 和 package bin surface
+- [`2026-07-08-loop-agent-client-contract-smoke.md`](2026-07-08-loop-agent-client-contract-smoke.md) — 新增 LoopAgentClient、command artifact、JSON parse failure、repo resolver/preflight 与 Ring 0 CLI contract smoke
+- [`2026-07-08-materializer-ring1-dag.md`](2026-07-08-materializer-ring1-dag.md) — 新增 TaskSpec materializer、materialize manifest、coverage-safe source 输出与 Ring 1 DAG generate/validate/dry-run smoke
+- [`2026-07-08-run-task-pipeline-ring2.md`](2026-07-08-run-task-pipeline-ring2.md) — 新增 Worker run-task pipeline、task-local run record、成功/失败分流与 Ring 2 shell-only DAG success/failure smoke
+- [`2026-07-08-task-pool-morning-report.md`](2026-07-08-task-pool-morning-report.md) — 新增 Worker Task Pool JSONL/state store、failure routing、串行 batch run-ready 和 morning report
+- [`2026-07-08-taskspec-worker-master.md`](2026-07-08-taskspec-worker-master.md) — 完成 TaskSpec + Worker 7 步 master 编排，覆盖 schema、graph、profile、client、materialize、run-task、Task Pool 和 morning report
+- [`2026-07-10-obs-001.md`](2026-07-10-obs-001.md) — WorkerEvent schema 与 append-only event/snapshot store
+- [`2026-07-10-obs-002.md`](2026-07-10-obs-002.md) — LoopAgentClient 流式输出、heartbeat 与实时 artifact
+- [`2026-07-10-obs-003.md`](2026-07-10-obs-003.md) — composite progress 与 Worker pipeline 事件打点
+- [`2026-07-10-obs-004.md`](2026-07-10-obs-004.md) — observability snapshot read model
+- [`2026-07-10-obs-005.md`](2026-07-10-obs-005.md) — 本地只读 observe HTTP/SSE server
+- [`2026-07-10-obs-006.md`](2026-07-10-obs-006.md) — Dashboard、Batch Detail 与 Run Detail UI
+- [`2026-07-10-obs-007.md`](2026-07-10-obs-007.md) — run-dag JSONL events 与 composite observer
+- [`2026-07-10-obs-008.md`](2026-07-10-obs-008.md) — Worker DAG events 接线与 DAG Detail UI
+- [`2026-07-10-obs-009.md`](2026-07-10-obs-009.md) — stale、quiet 与 timeout-risk 诊断
+- [`2026-07-10-obs-010.md`](2026-07-10-obs-010.md) — Failure Inbox、文档、package surface 与 smoke 验证
+- [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示

package/docs/feature-workflow.md

@@ -1,186 +1,186 @@
-# 功能工作流
-
-本文档区分两层：
-
-- **Session governance**：监督方（人/agent）如何组织一次工作会话
-- **Runtime workflows**：`src/workflows/` 下代码实际执行的内容
-
-## 默认会话协议
-
-1. **Orient**：读 `README.md`、`harness.json` 与本 docs 索引
-2. **Select**：选一个有限边界的工作块
-3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
-4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
-5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
-6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
-
-## Orient
-
-先理解当前系统，不要默认「没有」：
-
-- 读 `harness.json` 列出的仓库入口
-- 查 `git status --short --branch` 与最近提交
-- 新增结构前搜索现有源码、测试、脚本、文档与模板
-- 任务依赖健康基线时跑最小基线检查
-- 涉及 TDD、完成声明或调试时读方法论文档
-
-基线已坏时，记录失败命令，并决定当前块是修基线还是在明确范围内接受已知失败。
-
-## Select
-
-工作块要窄到可验证。避免无关重构、功能与文档迁移混在一起。
-
-选中的块应有：
-
-- 单一用户可见或维护者可见结果
-- 委托写工作时显式 allowed paths
-- 已知非目标
-- 能证明结果的验证命令
-
-## Contract
-
-非平凡工作应在实现前写或更新 execution plan、sprint contract、progress log 或 issue 级笔记。Contract 应包含：
-
-- 交付物
-- 非目标
-- 验收标准
-- 验证命令
-- 失败条件
-- 预期更新的 artifacts
-
-Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或 smoke check。
-
-## Implement
-
-做满足 contract 的最小连贯变更。
-
-- 优先现有 helper 与目录边界
-- 行为变更更新测试
-- 工作流或命令变更更新文档与示例
-- 治理变更更新 `harness.json`、检查脚本或模板
-- 不把占位实现当作已完成
-- 重复约束出现时固化为持久产物
-
-## Verify
-
-验证是完成权威。
-
-- 用 `docs/verification-matrix.md` 选最窄的证明命令
-- 完整重跑命令
-- 读 exit code 与输出
-- 修失败或报告确切失败状态
-- 不用陈旧输出或部分检查声明完成
-
-## Agent DAG First
-
-复杂实现优先 DAG 工作流：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。macOS/Windows 上实际文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-这不是线性 OS-CIVH runtime 状态机。代码里 DAG 有三个命令阶段：
-
-1. `dag run-task` 加载 `.harness/tasks/<task-id>/source/需求.md`、可选 `执行约束.md`、`task.json` 与 adapter 验证命令，写出 DAG spec
-2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
-3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
-
-标准生成的 hybrid DAG 默认无 Cursor：
-
-```text
-contract-pi
-  -> scout-src + scout-tests
-  -> plan-pi
-  -> implement-pi
-  -> verify-pi
-  -> closeout-pi
-```
-
-`implement-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。当 `harness.json` 显式禁用 Pi 并启用 Cursor 时，实现与修复 writer 节点改用 `implement-cursor` / `repair-cursor`。
-
-review-gated 模板插入：
-
-```text
-verify-pi -> review-pi -> review-gate-shell -> closeout-pi
-```
-
-supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
-
-源码参考：
-
-- `src/commands/dag-run-task.ts`
-- `src/commands/dag-validate.ts`
-- `src/commands/run-dag.ts`
-- `src/workflows/dag/init-hybrid.ts`
-- `src/workflows/dag/runner.ts`
-
-监督 agent 仍负责：
-
-- 写 contract
-- 限定 allowed/forbidden paths
-- 审查 DAG/writeSet 范围
-- 选择验证命令
-- 记录 handoff 证据
-
-声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
-
-## 已移除的顺序工作流
-
-历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。
-
-改用 DAG 路径：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-遗留 `.harness/tasks/<task-id>/.workflow_state.json` 在 task status 完全迁移到 DAG 导向读模型前仍可读，但不是新任务完成的权威。
-
-## Outer Loop Runtime
-
-`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review、Cursor 修复或 DAG action，并选择下一自动 action。
-
-支持的 loop actions：
-
-- `shell-verify`
-- `pi-review`
-- `cursor-fix`
-- `dag`
-- `record-round`
-- `add-signal`
-- `closeout`
-
-源码参考：
-
-- `src/commands/loop.ts`
-- `src/workflows/loop/actions.ts`
-- `src/workflows/loop/state.ts`
-- `src/workflows/loop/rounds.ts`
-
-## 调试与 TDD
-
-任务需要时使用方法论文档：
-
-- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
-- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
-- 失败与意外行为：`docs/harness-methodology-debugging.md`
-
-## Handoff
-
-Handoff 应说明：
-
-- 改了什么
-- 有意未做什么
-- 跑了哪些验证命令
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续工作
-
-较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。
+# 功能工作流
+
+本文档区分两层：
+
+- **Session governance**：监督方（人/agent）如何组织一次工作会话
+- **Runtime workflows**：`src/workflows/` 下代码实际执行的内容
+
+## 默认会话协议
+
+1. **Orient**：读 `README.md`、`harness.json` 与本 docs 索引
+2. **Select**：选一个有限边界的工作块
+3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
+4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
+5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
+6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
+
+## Orient
+
+先理解当前系统，不要默认「没有」：
+
+- 读 `harness.json` 列出的仓库入口
+- 查 `git status --short --branch` 与最近提交
+- 新增结构前搜索现有源码、测试、脚本、文档与模板
+- 任务依赖健康基线时跑最小基线检查
+- 涉及 TDD、完成声明或调试时读方法论文档
+
+基线已坏时，记录失败命令，并决定当前块是修基线还是在明确范围内接受已知失败。
+
+## Select
+
+工作块要窄到可验证。避免无关重构、功能与文档迁移混在一起。
+
+选中的块应有：
+
+- 单一用户可见或维护者可见结果
+- 委托写工作时显式 allowed paths
+- 已知非目标
+- 能证明结果的验证命令
+
+## Contract
+
+非平凡工作应在实现前写或更新 execution plan、sprint contract、progress log 或 issue 级笔记。Contract 应包含：
+
+- 交付物
+- 非目标
+- 验收标准
+- 验证命令
+- 失败条件
+- 预期更新的 artifacts
+
+Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或 smoke check。
+
+## Implement
+
+做满足 contract 的最小连贯变更。
+
+- 优先现有 helper 与目录边界
+- 行为变更更新测试
+- 工作流或命令变更更新文档与示例
+- 治理变更更新 `harness.json`、检查脚本或模板
+- 不把占位实现当作已完成
+- 重复约束出现时固化为持久产物
+
+## Verify
+
+验证是完成权威。
+
+- 用 `docs/verification-matrix.md` 选最窄的证明命令
+- 完整重跑命令
+- 读 exit code 与输出
+- 修失败或报告确切失败状态
+- 不用陈旧输出或部分检查声明完成
+
+## Agent DAG First
+
+复杂实现优先 DAG 工作流：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` 为平台原生临时目录。macOS/Windows 上实际文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+这不是线性 OS-CIVH runtime 状态机。代码里 DAG 有三个命令阶段：
+
+1. `dag run-task` 加载 `.harness/tasks/<task-id>/source/需求.md`、可选 `执行约束.md`、`task.json` 与 adapter 验证命令，写出 DAG spec
+2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
+3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
+
+标准生成的 hybrid DAG 默认无 Cursor：
+
+```text
+contract-pi
+  -> scout-src + scout-tests
+  -> plan-pi
+  -> implement-pi
+  -> verify-pi
+  -> closeout-pi
+```
+
+`implement-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。当 `harness.json` 显式禁用 Pi 并启用 Cursor 时，实现与修复 writer 节点改用 `implement-cursor` / `repair-cursor`。
+
+review-gated 模板插入：
+
+```text
+verify-pi -> review-pi -> review-gate-shell -> closeout-pi
+```
+
+supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
+
+源码参考：
+
+- `src/commands/dag-run-task.ts`
+- `src/commands/dag-validate.ts`
+- `src/commands/run-dag.ts`
+- `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/dag/runner.ts`
+
+监督 agent 仍负责：
+
+- 写 contract
+- 限定 allowed/forbidden paths
+- 审查 DAG/writeSet 范围
+- 选择验证命令
+- 记录 handoff 证据
+
+声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
+
+## 已移除的顺序工作流
+
+历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。
+
+改用 DAG 路径：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+遗留 `.harness/tasks/<task-id>/.workflow_state.json` 在 task status 完全迁移到 DAG 导向读模型前仍可读，但不是新任务完成的权威。
+
+## Outer Loop Runtime
+
+`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review、Cursor 修复或 DAG action，并选择下一自动 action。
+
+支持的 loop actions：
+
+- `shell-verify`
+- `pi-review`
+- `cursor-fix`
+- `dag`
+- `record-round`
+- `add-signal`
+- `closeout`
+
+源码参考：
+
+- `src/commands/loop.ts`
+- `src/workflows/loop/actions.ts`
+- `src/workflows/loop/state.ts`
+- `src/workflows/loop/rounds.ts`
+
+## 调试与 TDD
+
+任务需要时使用方法论文档：
+
+- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
+- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
+- 失败与意外行为：`docs/harness-methodology-debugging.md`
+
+## Handoff
+
+Handoff 应说明：
+
+- 改了什么
+- 有意未做什么
+- 跑了哪些验证命令
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续工作
+
+较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。