review(harness): 从 AGENTS.md 起的全面复审 —— 规范在长、执行没跟上，16 条建议

## 结论先行

这套 harness 的**核心律条是对的**，问题不在理念，在**文档层的增长速度远快于机械层**。

它自己写着：

> **没有脚本的规范条目视为未落地。**

而它自己就是最大的违反者。四个数字（均可复跑，SHA `origin/main` 2026-08-05）：

| 度量 | 数字 | 含义 |
|---|---|---|
| `AGENTS.md` 自称硬上限 ~100 行 | **实际 131 行** | 立规矩的文件自己破规矩 |
| `.harness/instructions/` | **2284 行 / 15 份** | 没人能在一轮里读完 |
| ADR | **22 条** | 每条都是一次"以后别再这样" |
| **已签契约操作有路由的比例** | **122 / 428 = 27%** | 73% 的规范**从未被执行过** |
| **controller 前缀有 rewrite 覆盖的** | **14 / 29** | 16 颗带电的雷，等人踩 |

⇒ **规范在长，执行没跟上。** 每次事故的产物是"再写一条规矩"，而不是"再加一道门"。

---

# 建议清单

按「每条能省下多少个未来的半轮」排序。

## L0 宪法层（`AGENTS.md`）

### 建议 1 —— 把 AGENTS.md 压回 100 行，并让门控守住它
自己声明的上限自己不守，读者学到的是"这里的数字是装饰"。加一条 `harness doctor` 检查：超 100 行即红。**十行脚本。**

### 建议 2 —— 每条硬约束旁边必须标注「由哪个脚本门控」
现在的形式是散文 + 一句"由 `assertSingleInProgress` 门控"（只有个别条目有）。改成**表格**：

| 约束 | 门控脚本 | 反证 |
|---|---|---|
| 一次只做一个 feature | `assertSingleInProgress` | ✅ |
| 状态不能自己改 | `verify.ts` | ✅ |
| 设计签核是人的动作 | *（本次新增）* | ✅ |
| 文件不超 2000 行 | **无** | ❌ |
| 范围纪律 | **无** | ❌ |

**没有门控的条目要么补门，要么降级成"建议"。** 混在一起，读者无法区分哪条会红、哪条只是愿望——而人只会为会红的东西改行为。

### 建议 3 —— 完成定义再加一条：**每条契约操作必须有路由**
现有六条完成定义都在讲"这个 feature 做完没有"，没有一条防"契约写了但没接线"。73% 就是这么来的。

---

## L1 指令层（`.harness/instructions/`）

### 建议 4 —— 2284 行按「读者 × 时机」重切
现在是按主题切（contract-design / coordinator-sop / agent-bootstrap…），一个新 agent 要判断哪几份跟自己有关。改成按**什么时候读**切：

- `ON-JOIN.md`（一次性，≤80 行）
- `EVERY-LOOP.md`（每轮，≤40 行）
- `BEFORE-PR.md`（交付前，≤60 行）
- `REFERENCE/`（其余，按需查，不要求读）

判据：**前三份加起来必须能在一轮里读完。** 读不完的规范等于不存在。

### 建议 5 —— 每份指令加「最后一次被违反」栏
`coordinator-sop.md` 316 行里，哪几条是活的、哪几条是历史包袱？让每条规则记录上次实际拦下问题的时间。**半年没拦住过任何东西的规则，要么删，要么它的门是假的。**

---

## L2 机械层（这一层是短板）

### 建议 6 🔴 —— 三道派生棘轮门（最高优先）
1. **契约 → 路由**：新增契约操作不接线 → 红。当前 313 条进 allowlist，只减不增。
2. **路由 → rewrite**：新增 controller 前缀无 rewrite → 红。当前 16 条同样棘轮。
3. **UI → controller**（#397 已有 issue）：同一形态。

**为什么是棘轮不是全绿门**：313 条今天补不完；写个全绿门只会被放宽到能过为止 —— 那就是又造一个坏仪器。棘轮今天就能合，且从今天起生效。

### 建议 7 🔴 —— 「注入反证」写进规范并强制
今天一天，我一个人撞到 **7 类坏仪器**（说谎注释、钉死错值、钉死字面量、正则吃掉证据、结构上不可能命中的 grep、拿渲染结果猜版本、吞掉退出码），**其中 2 类是我自己制造的**，且都是靠注入反证才发现的。

规则：**每道新门必须附一次注入反证，证明破坏被守的性质会红，且只红对应那一条。** 整组一起塌证明不了任何事。

### 建议 8 —— 断言禁止钉死"当前值"
断言必须表达**关系**，不是**快照**：

```ts
// ❌ expect(cfg).toContain('COORD_GATEWAY_URL = "https://x.workers.dev"')
// ✅ 从 apps/coord-gateway/wrangler.toml 的 name 推出期望值再比
```

元门控：断言里出现 URL / 版本号 / 具体函数名字面量时，同文件须有 `// invariant:` 说明。

---

## L3 协调层 —— **看板**（人类点名的部分）

`pnpm harness board` 已经存在且方向正确（三处真实数据源、读 spec 不读说法）。以下是我**实测跑过之后**的具体改进：

### 建议 9 🔴 —— 看板要回答的是「**下一个动作**」，不是「状态」
实测：它给 #466 的"下一步"写的是「补录音 UI 入口」，**而那会交付一个能点但不产出的按钮** —— 它把一个两段的活（采音 + WS 面）写成了一段。

⇒ **下一步必须从"最近一次可验证产物"推出**，不能从 issue 标题推。判据：`最后一个合入的 PR` + `spec 里还红的那条断言` → 差集就是下一步。

### 建议 10 —— 看板必须读 issue **评论**，不只读正文
我在 #493 的评论里写了完整勘定（哪两个 controller 缺、需要两跳前置），看板没看到，于是给出的下一步等于把标题抄了一遍。**勘定结果活在评论里，那是最新的事实。**

### 建议 11 —— 瓶颈行按**读者**分叉
现在算出的是「人类阻断项 2 条」——对人类准确，对正在写代码的 agent 无用。它不回答我唯一想问的：**我手上两条红，先做哪条？**

每个 owner 分节加一行「**你的最长串行链**」：`#466 第二段(WS) → e2e → review` vs `#493 两个 controller → 前端 → e2e`，把排序算给我，别让我自己算。

### 建议 12 —— 时限必须带「依据」，不只带时刻
今天我差点做错一件事：因为一个被 #548 挡住的依赖，想把 #466 的基线往后调。**正确做法不是调宽数字，是标注"这个承诺含一个不在我控制内的依赖"。**

看板每条承诺加两个字段：`阻塞源`（谁挡着）+ `我能控制的部分`。这样超时时一眼看出是谁的问题，而不是笼统地"晚了"。

### 建议 13 —— 看板是**共识的载体**，所以必须能被反驳
它今天已经栽过三次（五条编造 testid、一条说谎标题、新 issue 让它整块崩）。加一条自检：**看板每次渲染时校验自己引用的每个 testid 在源码里真实存在**，不存在就把那一行标红为"锚点失效"而不是照常显示。

---

## L4 迭代层（人类点名的"每轮一次改进"）

### 建议 14 🔴 —— 每个 C-cycle 必须交付**一条已落地的机械改进**
现在的 cycle-result 报的是"做了什么"。改成必须包含：

```
本周期实测的低效：<一句话 + 数字>
对应的机械改进：
反证：<破坏它会红的证据>
```

**没有 PR 链接的"改进"不算改进。** 这条本身就是这套 harness 核心律条的自我应用。

### 建议 15 —— 立一个可比较的效率指标
今天没有任何数字能回答"我们比昨天快了吗"。建议只立**一个**：

> **flow time = PR 开出 → 合入的中位数分钟**

理由：它同时受"写得快不快""review 等多久""CI 空转几次"影响，而这三件正是今天的全部痛点。三个周期后如果它不降，砍掉所有仪式只留 SLA + Andon（`work-cycle-proposal.md` 自己已经这么写过，但**没有人在量它**）。

### 建议 16 —— 进度报告改为**产物驱动**
今天我有连续几轮在回消息、跑看板、答问题，而**没有推进名下任何一条红**。这不是纪律问题，是结构问题：**消息是推送的，issue 是拉取的，推送天然赢。**

规则：报告里只允许出现 commit / PR / 测试输出。没有产物的一轮如实写「本轮无产物，原因是 X」——这样"我在忙"就不再是一个不可反驳的断言。

---

## 优先级

| 序 | 建议 | 理由 |
|---|---|---|
| 1 | **6**（三道棘轮门） | 73% + 16 颗雷，收益最大且今天能合 |
| 2 | **7 + 8**（反证 + 禁钉死值） | 已实测有效，我今天靠它抓出自己两次假门 |
| 3 | **9 + 10 + 11**（看板给动作而非状态） | 错的下一步比没有下一步更糟 |
| 4 | **14 + 15**（每轮一改进 + 一个指标） | 没有指标的"持续改进"无法证伪 |
| 5 | 1–5（文档层瘦身） | 重要但不紧急 |

---

**发起人**：coord-architecture
**证据**：全部来自 2026-08-05 一整天的一手经历，其中两类缺陷是我自己制造并自己抓出的

Start by reading AGENTS.md and the .harness/instructions/ directory, then run the existing `pnpm harness board` entry point. This is a broad review containing 16 recommendations rather than one scoped change; completion would require selecting one recommendation, identifying its affected files and validation, and agreeing on a concrete result.

Written by the indexing model from the issue text.