- commit
- d349be1
- parent
- eacbc47
- author
- im_wower
- date
- 2026-03-25 23:15:49 +0800 CST
chore: add next-wave task docs
4 files changed,
+262,
-9
+9,
-2
1@@ -6,10 +6,10 @@
2
3 ## 当前代码基线
4
5-- 主线基线：`main@7c9f009`
6+- 主线基线：`main@1078d2b`
7 - 任务文档已统一收口到 `tasks/`
8 - 当前活动任务见 `tasks/TASK_OVERVIEW.md`
9-- 当前工作区已落地 `T-S001` 到 `T-S004` 的改动，但还没提交回主线
10+- `T-S001` 到 `T-S004` 已经合入主线
11
12 ## 当前状态
13
14@@ -48,6 +48,13 @@
15 - `T-S002`：legacy Worker / D1 入口已从当前工作区收口；`tests/control-api/**` 改为 absence smoke，`ops/cloudflare/**` 收敛到 legacy 说明
16 - `T-S003`：`status-api`、launchd 模板和 runtime 文档已切到当前 `conductor` 主接口，`BAA_CONTROL_API_BASE` 只保留为兼容覆盖
17 - `T-S004`：`conductor-daemon` 测试已统一通过 `withRuntimeFixture(...)` 收口 cleanup，`BUG-009` 已修复
18+- `T-S005`：默认 launchd 现在只把 `BAA_CONTROL_API_BASE` 写给 `conductor`；`status-api` 和 `worker-runner` 不再携带这个变量
19+- `T-S007`：`ConductorRuntime.stop()` 已补专项测试，覆盖 listener 释放、Firefox bridge client 关闭和重复 stop 的幂等行为
20+
21+## 下一步任务
22+
23+- `T-S006`：清理历史任务 / 缺陷 / 文档里的 `control-api` 命名残留
24+- `T-S008`：给 codexd child / transport 提前断流补诊断与 reopen 规则
25
26 ## 当前仍需关注
27
+119,
-0
1@@ -0,0 +1,119 @@
2+# Task T-S006：清理历史 `control-api` 命名残留
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S006.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/tasks/TASK_OVERVIEW.md`
11+- `/Users/george/code/baa-conductor/plans/STATUS_SUMMARY.md`
12+- `/Users/george/code/baa-conductor/bugs/README.md`
13+- `/Users/george/code/baa-conductor/docs/api/README.md`
14+- `/Users/george/code/baa-conductor/docs/runtime/README.md`
15+- `/Users/george/code/baa-conductor/docs/api/hand-shell-migration.md`
16+
17+## 当前基线
18+
19+- 仓库：`/Users/george/code/baa-conductor`
20+- 分支：`main`
21+- 提交：`1078d2b`
22+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
23+
24+## 建议分支名
25+
26+- `chore/clean-legacy-control-api-names`
27+
28+## 目标
29+
30+把仓库里仍然误导当前主线的 `control-api` / `control-api.makefile.so` 命名清掉，只保留必要的历史背景描述。
31+
32+## 背景
33+
34+- 当前功能与运行时已经切到 `4317` 和 `conductor.makefile.so`。
35+- 剩余风险之一是历史任务文档、缺陷文档、迁移说明和部分兼容说明里还保留 `control-api` 命名。
36+- 这些命名如果不清，会继续误导后续协作和任务拆分。
37+
38+## 涉及仓库
39+
40+- `/Users/george/code/baa-conductor`
41+
42+## 范围
43+
44+- 清理历史文档里的 misleading current-tense `control-api` 命名
45+- 保留必要的历史背景，但要明确“legacy / 兼容 / 已移除”
46+- 统一当前任务与状态文档的口径
47+
48+## 路径约束
49+
50+- 只做文档和任务/缺陷记录清理，不改运行时代码。
51+- 如果某处是“历史事实”，可以保留，但必须明确是历史背景。
52+
53+## 推荐实现边界
54+
55+建议优先做：
56+
57+- `tasks/**`、`plans/**`、`bugs/**` 的当前口径清理
58+- `docs/api/**`、`docs/runtime/**` 里仍像当前配置说明的 legacy 命名收口
59+- 避免把历史 bug / 任务的复现描述洗掉
60+
61+## 允许修改的目录
62+
63+- `/Users/george/code/baa-conductor/tasks/`
64+- `/Users/george/code/baa-conductor/plans/`
65+- `/Users/george/code/baa-conductor/bugs/`
66+- `/Users/george/code/baa-conductor/docs/api/`
67+- `/Users/george/code/baa-conductor/docs/runtime/`
68+- `/Users/george/code/baa-conductor/README.md`
69+
70+## 尽量不要修改
71+
72+- `/Users/george/code/baa-conductor/apps/`
73+- `/Users/george/code/baa-conductor/scripts/runtime/`
74+- `/Users/george/code/baa-conductor/ops/launchd/`
75+- `/Users/george/code/baa-conductor/tests/`
76+
77+## 必须完成
78+
79+### 1. 清理误导性的当前时态表述
80+
81+- 把仍像“当前主线配置”的 `control-api` 描述改成 legacy 背景说明
82+- 当前 canonical 接口必须始终指向 `4317` / `conductor.makefile.so`
83+
84+### 2. 保留必要的历史信息
85+
86+- 不要删除仍有排障价值的历史背景
87+- 历史事实必须明确标成 “legacy / 迁移前 / 已移除”
88+
89+### 3. 统一状态文档口径
90+
91+- `tasks/`、`plans/`、`bugs/` 的现状描述要彼此一致
92+- 不再出现一份文档说“已修复”，另一份还写“未解决”
93+
94+## 需要特别注意
95+
96+- 不要改代码逻辑
97+- 不要为了追求“全删干净”而损失历史排障信息
98+- 与 `T-S005` 同时改 `docs/runtime/**` 会冲突，避免并行落地
99+
100+## 验收标准
101+
102+- 当前主线相关文档不再把 `control-api` 写成现行默认入口
103+- 历史背景仍可追溯，但不会误导当前维护
104+- `tasks/`、`plans/`、`bugs/` 三处状态口径一致
105+- `git diff --check` 通过
106+
107+## 推荐验证命令
108+
109+- `rg -n "control-api\\.makefile\\.so|control-api" /Users/george/code/baa-conductor/tasks /Users/george/code/baa-conductor/plans /Users/george/code/baa-conductor/bugs /Users/george/code/baa-conductor/docs`
110+- `git -C /Users/george/code/baa-conductor diff --check`
111+
112+## 交付要求
113+
114+完成后请说明：
115+
116+- 修改了哪些文件
117+- 哪些 `control-api` 命名被改掉了
118+- 哪些历史描述被保留了
119+- 你如何区分“历史事实”和“误导性当前口径”
120+- 还有哪些遗留命名决定暂时不动
+119,
-0
1@@ -0,0 +1,119 @@
2+# Task T-S008：补 codexd child / transport 断流诊断与 reopen 规则
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S008.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/apps/codexd/src/daemon.ts`
11+- `/Users/george/code/baa-conductor/apps/codexd/src/app-server-transport.ts`
12+- `/Users/george/code/baa-conductor/apps/codexd/src/index.test.js`
13+- `/Users/george/code/baa-conductor/bugs/BUG-008-codexd-second-thread-turn-timeout.md`
14+- `/Users/george/code/baa-conductor/bugs/BUG-010-codexd-turn-status-stuck-inprogress.md`
15+- `/Users/george/code/baa-conductor/docs/runtime/codexd.md`
16+
17+## 当前基线
18+
19+- 仓库：`/Users/george/code/baa-conductor`
20+- 分支：`main`
21+- 提交：`1078d2b`
22+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
23+
24+## 建议分支名
25+
26+- `feat/codexd-transport-failure-diagnostics`
27+
28+## 目标
29+
30+给 codexd 增加“app-server 提前断流但没有合法 `turn/completed`”场景的明确诊断与 reopen 规则，避免以后再把新故障混进已修复的 BUG-008 / BUG-010。
31+
32+## 背景
33+
34+- `BUG-008` 和 `BUG-010` 已经按当前证据修复。
35+- 当前剩余风险是另一类故障：如果 child / transport 在合法完成事件发出前就断流，这将是新的独立问题。
36+- 现在需要把这种场景的诊断和 reopen 规则写清楚，最好让代码和测试也能给出更明确的失败信号。
37+
38+## 涉及仓库
39+
40+- `/Users/george/code/baa-conductor`
41+
42+## 范围
43+
44+- 增强 codexd 在“未收到合法 completed 就断流”场景下的可诊断性
45+- 增加对应测试
46+- 回写 BUG-008 / BUG-010 和 runtime 文档里的 reopen 规则
47+
48+## 路径约束
49+
50+- 不要重做已完成的尾包冲刷修复
51+- 优先补 failure classification / diagnostics，不做大范围架构重构
52+
53+## 推荐实现边界
54+
55+建议优先做：
56+
57+- 明确 transport close 时当前 turn 处于什么状态
58+- 把“合法完成缺失”与“尾包被截断”区分开
59+- 给测试和文档一个可复用的 reopen 判断口径
60+
61+## 允许修改的目录
62+
63+- `/Users/george/code/baa-conductor/apps/codexd/`
64+- `/Users/george/code/baa-conductor/docs/runtime/codexd.md`
65+- `/Users/george/code/baa-conductor/bugs/BUG-008-codexd-second-thread-turn-timeout.md`
66+- `/Users/george/code/baa-conductor/bugs/BUG-010-codexd-turn-status-stuck-inprogress.md`
67+- `/Users/george/code/baa-conductor/bugs/README.md`
68+
69+## 尽量不要修改
70+
71+- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
72+- `/Users/george/code/baa-conductor/apps/status-api/`
73+- `/Users/george/code/baa-conductor/scripts/runtime/`
74+
75+## 必须完成
76+
77+### 1. 明确 child / transport 断流诊断
78+
79+- 在未收到合法完成事件就断流时，给出明确可区分的失败信息
80+- 不要让调用方只能看到模糊的 reconnect / failed
81+
82+### 2. 补回归测试
83+
84+- 至少增加一条“没有合法 completed 就断流”的测试
85+- 测试要能证明这类场景和已修复的尾包冲刷缺陷是不同问题
86+
87+### 3. 写清 reopen 规则
88+
89+- 在 bug 文档和 runtime 文档里明确：
90+ - 什么情况算旧问题已修复范围内
91+ - 什么情况应该 reopen 为新 bug
92+
93+## 需要特别注意
94+
95+- 不要把任务扩展成 codexd 新协议设计
96+- 不要引入额外的 completion 轮询兜底
97+- 与 `T-S007` 并行时写范围完全不重叠，可同时推进
98+
99+## 验收标准
100+
101+- child / transport 提前断流场景有明确诊断
102+- 有回归测试覆盖“没有合法 completed 就断流”
103+- BUG / runtime 文档的 reopen 规则清楚一致
104+- `git diff --check` 通过
105+
106+## 推荐验证命令
107+
108+- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/codexd test`
109+- `node --test /Users/george/code/baa-conductor/apps/codexd/src/index.test.js`
110+- `git -C /Users/george/code/baa-conductor diff --check`
111+
112+## 交付要求
113+
114+完成后请说明：
115+
116+- 修改了哪些文件
117+- 新增了什么 failure classification / diagnostics
118+- 如何区分“旧尾包问题”和“新的 child / transport 故障”
119+- 跑了哪些测试
120+- 还有哪些场景仍未覆盖
+15,
-7
1@@ -9,23 +9,31 @@
2 - `control-api.makefile.so`、Cloudflare Worker、D1 只剩迁移期兼容残留
3 - `baa-hand` / `baa-shell` 只保留为接口语义参考，不再作为主系统维护
4 - 当前任务卡都放在本目录
5-- 当前任务基线：`main@7c9f009`
6+- 当前任务基线：`main@1078d2b`
7
8 ## 最近完成任务
9
10-当前 4 张主线收口任务已经在工作区完成实现：
11+当前已完成的主线任务：
12
13 1. [`T-S001.md`](./T-S001.md)：修复 codexd turn 完成状态
14 2. [`T-S002.md`](./T-S002.md)：清理 `control-api-worker` 残留与坏测试
15 3. [`T-S003.md`](./T-S003.md)：切换 `status-api` 到 `conductor` 主接口
16 4. [`T-S004.md`](./T-S004.md)：修复 `conductor-daemon` 测试 listener 泄漏
17+5. [`T-S005.md`](./T-S005.md)：收口 `BAA_CONTROL_API_BASE` 兼容入口
18+6. [`T-S007.md`](./T-S007.md)：补 `ConductorRuntime.stop()` 关闭路径专项测试
19
20-当前没有新的活动任务卡；如果要继续往下拆，建议围绕这些剩余风险开新任务：
21+## 当前活动任务
22
23-- `BAA_CONTROL_API_BASE` 兼容入口是否继续保留，还是继续收口
24-- 历史任务 / 缺陷文档里残余的 `control-api` 命名清理
25-- `ConductorRuntime.stop()` 关闭路径的专项运行时测试
26-- 新的 child / transport 故障兜底与 reopen 规则
27+围绕剩余风险，当前建议继续推进这 2 张任务卡：
28+
29+1. [`T-S006.md`](./T-S006.md)：清理历史 `control-api` 命名残留
30+2. [`T-S008.md`](./T-S008.md)：补 codexd child / transport 断流诊断与 reopen 规则
31+
32+并行建议：
33+
34+- `T-S006` 主要改文档和状态口径
35+- `T-S008` 主要改 codexd 与 bug/runtime 文档
36+- 这两张卡写范围基本不重叠，可以并行
37
38 ## 任务文档约定
39