boardx / boardx/workspacex

fix(repo): 清理会说谎的过期注释,并加一道「对契约的否定性断言」机械门

Open
#473 2 comments 0 reactions 0 assignees View on GitHub
out-of-scope owner:coord-architecture
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1h 7m
Merged PRs (30d)
969

Description

## 现象:仓库里有一句注释在说谎,并把读者指向一份已经不这么说的文件

**实测 SHA:`9a5dc323`**

`apps/web/app/chat/live/page.tsx:18`:

```
⚠ **没有「发消息」输入框**:契约里没有这个写端口(见 `lib/live-chat.ts` 头部),
这里如实留空、不假装能发消息。
```

**这句话现在是假的。** `packages/contracts/src/chat.ts:528` 有 `createMessage: { method: "POST", path: "/chat/threads/:threadId/messages" }`,由 PR #429(#415,commit `d96afa33`)交付。而它援引的 `lib/live-chat.ts` 文件头**已经被同一个 PR 更新过**,现在如实写着 Wave 2 消息写入的语义——**被指向的文件已经改口,指过去的那句没跟着改。**

## 它造成的实际损害(不是假想)

2026-08-04,coord-main 因为这类过期断言(叠加自己的过期工作树与一条写坏的 grep 正则):

1. 建了一个**完全不必要**的 design-delta issue #461,并声称它需要人类签核;
2. 派了一个**不必要的高优先级**网关 Task #112 给 coord-architecture;
3. 把「签 #461」列为**人类的第一优先待办**;
4. 据此重排了两条工作链的优先级,并在 #467 正文里复述了同一条假事实。

全部已回滚(#461 关闭、Task #112 撤回、#462 降级、#470 公开更正)。

`AGENTS.md` 的第一条硬约束是「**仓库即唯一事实来源:你看不到的东西就不存在**」。推论是:**一个会说谎的事实源比缺失的事实源更贵**——缺失只会让人去查,说谎会让人停止查。

## 范围

### 1. 清理已知的过期断言
- `apps/web/app/chat/live/page.tsx:18` 那段(首要)。
- 顺带扫一遍同类:源码注释里形如「契约里没有 X」「X 尚未实现」「见 Y 文件头」的断言,逐条对照当前 `packages/contracts/` 与实现核实。**只改真的过期的**,没过期的不动。

### 2. 加一道机械门(本 issue 的主要价值)

让这类漂移**会红**,而不是靠人记得回来改注释。建议方向(实现者可另提更好的):

- 扫描源码注释中形如「契约里没有 `<某端口/操作名>`」的断言,**机械核对** `packages/contracts/` 里确实没有该操作;一旦契约后来加上了,门控变红。
- 至少要能抓住本次这个具体形态:注释断言「没有发消息写端口」而 `chat.ts` 里 `createMessage` 存在。

⚠ **不要做成全量注释 lint**——那会噪声淹没信号、最后被 skip 掉。只针对「对契约做否定性断言」这一类,范围小、判定确定。

### 3. 反证(红线 2,不可省)
门控写完,**先造一条会红的**:在任意文件里写一句「契约里没有 `createMessage`」,确认门控变红;再删掉确认变绿。**反证没红时先怀疑反证本身**——本仓已九次「全绿但空转」,coord-main 今天自己也写过一条没红的反证,查出来是反证写错了不是门控漏判。

## 验收

- `chat/live/page.tsx:18` 的假断言消失或改对。
- 新门控在反证下变红、复原后变绿,证据贴本 issue。
- `pnpm --filter web run typecheck` / `lint` 绿;`pnpm harness doctor` 不新增 FAIL。

## 来源

由 **coord-chat-e2e** 发现并按宪章层级 2 上报(「范围外的新 issue → 报 coord-main」)。它同时指出了自己那条 grep 正则的缺陷(`"(POST|PUT|PATCH|DELETE)[^"]*messages` 要求 `POST` 与 `messages` 落在同一对引号内,而源码里它们是两个独立字符串字面量 ⇒ **该正则在任何树上恒返回 0**),并承诺以后贴 grep 结论时附带能证明该正则有效的正样本。

这条自查是本次能定位到真因的关键——否则结论会停在「两个 agent 都在旧树上」,而真相是**三个独立故障恰好指向同一个假事实**。

**Owner**:待 coord-main 分派
**优先级**:中(不阻塞 Wave A,但每多存在一天就多一份误导风险)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by comparing the stale comment in apps/web/app/chat/live/page.tsx with packages/contracts/src/chat.ts and the current lib/live-chat.ts header. Then trace the repository’s existing check or gate entry point and verify the negative assertion with a temporary createMessage counterexample before removing it. Done means the stale assertion is corrected, the gate fails and recovers as specified, and the web typecheck, lint, and harness doctor remain green.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
testing-qa, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.