@tea-agent/loop-agent 0.1.0-fe-test.0

package/docs/architecture/system-overview.md

@@ -0,0 +1,100 @@
+# 系统全景
+
+本页用一张全景图说明 loop-agent、agent-worker、治理层与外部系统的关系。依赖方向、import 边界与 governance hook 是契约级事实，权威源是 `runtime-boundaries.md`（本页只交叉引用，不复制）。
+
+## 两个 CLI 二进制
+
+发布包 `@tea-agent/loop-agent` 提供两个入口（见 `package.json` `bin`）：
+
+| 二进制 | 入口 | 角色 |
+| --- | --- | --- |
+| `loop-agent` | `bin/loop-agent.js` → `src/cli.ts` | 仓库级 AI coding 任务运行时与治理控制器 |
+| `agent-worker` | `bin/agent-worker.js` → `src/worker/cli.ts` | 产品线 TaskSpec / Feature / Task Pool / Observe 外层适配 |
+
+两个二进制是独立进程，不共享 in-process runtime。`agent-worker` 真正执行 DAG 时通过已发布的 `loop-agent` 子进程调用（详见 `worker-and-feature.md`）。
+
+## 分层概览（交叉引用）
+
+完整分层图、各层职责、允许/禁止的 import 方向见 `runtime-boundaries.md` §分层概览 与 §各层职责。一句话摘要：
+
+```text
+Skill layer      .agents/skills/loop-agent、.agents/skills/agent-worker（Markdown，非 TS import）
+CLI layer        src/cli/ — argv 解析、调用 application/handler、格式化输出
+Application      src/application/ — typed use-case（validate/run/generate DAG 等）
+Workflow runtime src/workflows/ — DAG / Dynamic / Loop 核心执行规则
+Executors        src/executors/ — Pi / shell / static 受治理外部工具适配
+Sidecars         src/sidecars/cursor-prompt — 显式手工 one-shot；不得被 workflow 自动依赖
+Worker adapter   src/worker/ — 产品线适配 + Observe；子进程调用已发布 loop-agent
+Infrastructure   src/infrastructure/ — .harness 副作用、run lifecycle、原子写入
+Governance       scripts/check-*.sh、src/governance/ — 防漂移机器校验
+```
+
+## 两条入口路径
+
+### 直接任务路径
+
+```text
+人类 / 主 agent
+  │  写任务源与执行约束（.harness/tasks/<taskId>/source）
+  ▼
+loop-agent（runtime + 治理控制器）
+  │  dag run-task / validate / run-dag / report / doctor / reconcile-run
+  ▼
+workflow runtime（调度 Pi / shell / static 节点）
+  │  证据落入 .harness/dag-runs/{active,paused,completed}/<runId>/
+  └─ report / doctor / promote / closeout 读取并投影证据
+```
+
+### 产品线 Feature 路径
+
+```text
+人类 / 外部调度器
+  → agent-worker（TaskSpec / Feature / Task Pool）
+  → 冻结 controller identity
+  → spawn 已发布 loop-agent 子进程
+  → 同一 DAG runtime 与 executor registry
+  → DAG facts + Task Pool records
+  → Feature review / morning report / Observe（派生只读视图）
+```
+
+`agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
+
+### 本地 Operator Console（Official，0.17.x MVP，与 Observe 协作）
+
+- `agent-worker console|doctor` 提供 loopback Operator Console（默认 `127.0.0.1:8790`；本地图形环境 listen 后默认打开浏览器，`--no-open` 禁止）；Happy Path / Interview 策略面、Task Contract 落地与 recovery CTA 已随 **0.17.0–0.17.2** 发布。
+- canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
+- Observe 保持**独立**只读进程（默认 `8787`）；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/archive/2026-07-21-local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
+
+## 外部边界
+
+- npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。
+- 目标仓库：`loop-agent init` 投影语言无关治理资料；源码仓库专用架构文档只随包可读，不默认投影。
+- 本地文件系统：`.harness/` 保存运行态事实；Git 工作树保存代码、治理文档与长期交接资料。
+- 远程 Git/PR/CI、云 Worker 与云 Task Pool 当前不是核心 runtime 的已实现内置边界，见 `evolution.md`。
+
+## 治理层入口
+
+治理检查是机器校验，不是文档约定。主入口：
+
+- `scripts/check-repo.sh` — 聚合入口，CI / in-flight DAG 均调它。
+- 子脚本：`scripts/check-architecture-boundaries.sh`（import 边界）、`scripts/check-command-registry-drift.sh`（command registry）、`scripts/check-skill-entry.sh`（公共 skill entry）、`scripts/check-doc-index.sh` / `scripts/check-doc-links.sh`（文档链接）、`scripts/check-init-surface.sh`（package/init surface 契约）、`scripts/check-init-evolution-needed.sh`（高影响变更需报告）。
+- `src/governance/**` — 治理逻辑与相关 Vitest。
+- `scripts/self-host-canary.mjs` — 源码仓库的 deterministic candidate takeover 证据入口；**不**属于发布 package surface。
+
+完整的 governance hook 表（哪个脚本检查什么、失败条件）见 `runtime-boundaries.md` §Governance 钩子。
+
+## 受治理 Agent runtime = Pi-only
+
+自 0.10.0 起受治理 Agent runtime 硬切为 Pi-only（ADR 0001）。DAG 中 `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；`executor: "cursor"` 会抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`。`cursor-prompt` 仅保留为显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。详见 `dag-execution.md` 与 `runtime-boundaries.md` §Executors / §Sidecars。
+
+## 运行态 vs 治理资料 vs 用法文档
+
+| 位置 | 内容 | 权威性质 |
+| --- | --- | --- |
+| `.harness/` | 任务、DAG run、one-shot run、Task Pool、live state | 运行态事实（canonical + derived） |
+| 源仓 `docs/`（目标项目常为 `ai_workspace/loop-agent/`） | 原则、边界、计划、报告、模板 | 治理权威 |
+| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
+| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
+
+`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。

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

@@ -0,0 +1,122 @@
+# Worker 与 Feature 架构
+
+本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与统一 Operator Console（Operate + Inspect）。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
+
+**维护校准：2026-07-27 / `@tea-agent/loop-agent@0.24.0`** — 统一 Operator Console（Operate + Inspect）、恢复操作面与自适应 liveness 已落地；细节以 `CHANGELOG.md` 与对应 active/completed plan 为准。
+
+## 核心事实：子进程，非 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 实现。
+
+### `run-dag` kernel-owned supervision vs explicit hard timeout
+
+`run-task` 启动 `run-dag` 时默认把外层 `timeoutMs` 设为 `0`，由 DAG kernel 负责节点 liveness，**不再**无条件把 30 分钟当作 hard kill：
+
+- 省略 `worker.timeout_ms` → Worker 不设置 wall-clock deadline，并等待 `run-dag` 产生可确认终态。
+- 显式 `worker.timeout_ms` → hard kill（可 capped），观察到 exit 后可报 `timedOut`。
+- 客户端 `onHeartbeat` 仍是监管心跳，不等于 Pi meaningful progress。
+
+设计真源：`docs/design/active/dag-adaptive-liveness-and-supervision.md`。
+
+## 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`、`console` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
+
+## 产品线 read model
+
+### TaskSpec 与 workflow 路由
+
+- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
+- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
+- **0.16.0+**：可选 `execution.workflow` 映射到 loop-agent `taskKind`（如 agent-dag / frontend-implementation / backend-test / frontend-test）；typed Task Outcome 与 artifact-aware Ready 门禁见 completed `2026-07-19-taskspec-workflow-routing.md`。
+- 文档映射镜像：`docs/architecture/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
+
+### 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 等都基于此根。
+- **Ready Planner**：`batch plan-ready` 零写入预览 selected/deferred/blocked；`run-ready` 冻结 `ready-plan.json`（priority + 产物门禁）。
+
+### 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]`、`docs/reports/feature/2026-07-12-m2-completion-audit.md`。
+
+### Final Verification 权威（ADR 0007）
+
+| 入口 | 职责 |
+| --- | --- |
+| `agent-worker feature verify-final` | **唯一** canonical writer：Feature Verification Bundle、`qa-pass.json`、`final-verification.json` |
+| `agent-worker feature advance` | 编排 verify-final → delivery → closeout preview[/apply]（ADR 0007 运维入口） |
+| `agent-worker feature doctor` | 只读诊断证据/Pool/dirty worktree；建议下一步命令 |
+| Feature Packet `FINAL-VERIFY-*`（若保留） | 可选 **local smoke recipe**（样本 `verify:final` / reports）；Task Done ≠ Final Verification Record |
+| `feature delivery` | 重验 verify-final 证据；省略路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json` |
+| `feature closeout` | 只认 Delivery manifest + Final Verification Record 链 |
+
+禁止把 packet Task 的 smoke 报告或 agent-dag `verify-pi` 结论当作 Delivery 放行条件。
+
+### Inspect（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 read model 是本地只读 Inspect 能力；snapshot 投影失败返回安全错误摘要而非全零健康状态。
+- `agent-worker console` 在同一进程挂载 `/inspect/` 与现有 GET `/api/**`；`/api/health` 返回 `OperatorSurfaceHealthV1`。`observe serve` 已硬下线（REMOVED / exit 2）。
+
+### Local Operator Console（Official，0.18.0）
+
+- 模块：`src/worker/console/`（loopback `serve|doctor`、operator API、Vite SPA）。
+- **已发布能力**：Happy Path / Interview、Task Contract、SSE、同站 Inspect、Run/Recovery 紧凑检视与 recovery CTA 矩阵（无 Cancel / 无主 CTA「直接改代码」）。
+- Inspect 仍复用唯一 Observe read model，GET-only；不复制 snapshot projector。
+- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`（含 `task contract *` / DAG confirm-run）。
+- 证据：completed Console Phase 0.5 / 1–3；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`；ADR 0005。
+
+## 版本化自举的 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/governance/README.md

@@ -0,0 +1,18 @@
+# 工程治理
+
+这里放的是“怎么推进一次工作”的长期规则。开始实现前先读工作流，需要选择验证命令时再看验证矩阵；三份方法论文档用于测试、完成声明和故障排查。
+
+## 入口
+
+- [`development-principles.md`](development-principles.md)：工程原则与完成纪律。
+- [`feature-workflow.md`](feature-workflow.md)：会话治理、taskKind、profile、Agent DAG 路径，以及 managed contract 的边界更新与恢复语法。
+- [`verification-matrix.md`](verification-matrix.md)：按变更类型选择验证命令。
+- [`harness-methodology-tdd.md`](harness-methodology-tdd.md)：测试先行的方法与边界。
+- [`harness-methodology-verification.md`](harness-methodology-verification.md)：如何用新鲜命令结果支持完成声明。
+- [`harness-methodology-debugging.md`](harness-methodology-debugging.md)：系统化定位故障，不用猜测代替证据。
+- [`document-review-policy.md`](document-review-policy.md)：文档 freshness、`reviewTier` 与 `lastReviewed` 更新边界。
+- [`lightweight-github-collaboration.md`](lightweight-github-collaboration.md)：短分支、简短 PR、CI 与 Squash Merge 的轻量协作规则。
+- [`研发模式.md`](研发模式.md)：Feature 团队推进、交付和知识回写方法论。
+- [`腾讯实践对当前项目的指引.md`](腾讯实践对当前项目的指引.md)：外部工程实践与本仓库治理/能力边界的映射。
+
+架构事实见 [`../architecture/README.md`](../architecture/README.md)，运行手册见 [`../runtime/README.md`](../runtime/README.md)，日常维护操作见 [`../operations/README.md`](../operations/README.md)。

package/docs/governance/harness-methodology-debugging.md

@@ -0,0 +1,177 @@
+# Harness Methodology: Systematic Debugging
+
+从 Superpowers `systematic-debugging` skill 中提取的调试方法，适配本仓库 harness 工作流。
+
+## Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
+
+## 前置：构建反馈回路（Phase 1 的地基）
+
+在读代码猜原因、列假设或动手修复之前，先建立一条**快速、确定性、Agent 可运行**的 pass/fail 信号。后续复现、假设、插桩和修复都消费这条回路，而不是依赖聊天里的印象。
+
+按优先级选用（能用更靠前的就不要降级）：
+
+1. 失败测试（已有或最小新增）
+2. HTTP / API 脚本（固定输入 → 断言状态码或响应）
+3. CLI fixture / snapshot
+4. 浏览器脚本（确定性交互 + 断言）
+5. Trace / log replay
+6. 一次性本地 harness（最小复现命令）
+7. Property / fuzz（非确定性边界）
+8. `git bisect run`（回归定位）
+9. 新旧版本 differential
+10. 结构化 HITL 脚本（仅当自动化回路不可得，且人工步骤可重复）
+
+把回路本身当作产品优化：更快、更锋利、更确定性。间歇性问题先提高复现率，再进入根因调查。
+
+**不能建立回路时：停下。** 请求缺失的环境、artifact、凭据或临时插桩许可；不要在没有 pass/fail 信号时继续猜。
+
+## 何时使用
+
+适用于任何技术问题：
+- 测试失败
+- 生产 bug
+- 意外行为
+- 性能问题
+- 构建/集成失败
+
+**尤其要在以下情况使用：**
+- 时间压力下（紧急情况最容易让人猜）
+- "一个快速修复"看起来很明显
+- 已经试过多次修复
+- 上一个修复没奏效
+- 不完全理解问题
+
+## 四阶段流程
+
+每个阶段必须完成才能进入下一个。反馈回路是 Phase 1 的地基，不是第五阶段。
+
+### 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
+
+如果你发现自己这样想：
+- "没有 pass/fail 回路，先读代码猜原因"
+- "先快速修一下，后面再调查"
+- "试试改 X 看看行不行"
+- "一次改多个东西然后跑测试"
+- "跳过测试，手工验证就行"
+- "大概就是 X 的问题，直接修吧"
+- "不太确定但可能有用"
+- "再试一个修复"（已经试了 2+ 次）
+
+**以上任何一种 → 停止。回到反馈回路 / Phase 1。**
+
+## 和 Harness 工作流的对齐
+
+| 调试阶段 | Harness 步骤 |
+|---------|-------------|
+| 反馈回路 | Baseline / Reproduction evidence：先有可重复的 pass/fail 信号 |
+| Phase 1：根因调查 | Baseline：确认 bug 可复现，并收集证据 |
+| Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
+| Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
+| Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
+| Phase 4.5：质疑架构 | 可能需要新的 exec plan |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|------|---------|---------|
+| 0. 反馈回路 | 建立快速确定性 pass/fail 信号 | 有可重复命令与退出码 |
+| 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
+| 2. 模式 | 找工作中的例子、对比 | 识别差异 |
+| 3. 假设 | 形成理论、最小测试 | 确认或新假设 |
+| 4. 实现 | 创建测试、修复、验证 | Bug 解决、测试通过 |
+
+## 当流程揭示"无根因"时
+
+如果系统性调查揭示问题确实属于环境性、时序性或外部依赖：
+1. 已完成流程（不是跳过）
+2. 记录调查了什么
+3. 实现适当处理（重试、超时、错误提示）
+4. 添加监控/日志供将来调查
+
+**但是：** 95% 的"无根因"案例是不完整调查。

package/docs/governance/harness-methodology-tdd.md

@@ -0,0 +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 工作流：`feature-workflow.md`
+- 验证矩阵：`verification-matrix.md`
+- Sprint Contract 模板：`templates/sprint-contract.md`

package/docs/governance/harness-methodology-verification.md

@@ -0,0 +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
+
+- 凭意图声明完成
+- 依赖陈旧命令输出
+- 用窄检查支撑宽声明
+- 跳过失败命令的细节