dsh-tower 2.5.0 → 2.7.0

package/docs/zh/operations/security.md

@@ -6,12 +6,13 @@ Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些
 
 ## 由插件强制执行的约束
 
-- **审查绑定（开启审查时）。** `tower_review` 会记录它检查的分支 tip；开启 `review.requireReview` 后
-  tip 变化会被门禁拒绝（`tip-moved`），除非一次干净且无冲突的 rebase 给予了豁免。reviewer 在 spawn
-  之后修改分支会被拒绝（`reviewer must not modify the mission branch`）。
-- **审查默认可选，可配置强制。** `review.requireReview:false` 是默认值；设为 `true` 才启用独立审查
-  门禁。全局开启时，mission 级 `reviewPolicy:"none"` + 理由是更窄的豁免。关闭门禁时插件不强制职责
-  分离；只应用于可信仓库或有人类监督的会话。
+- **审查绑定（策略为 required 时）。** `tower_review` 会记录它检查的分支 tip；策略为
+  `review.mode:required` 时，tip 变化会被门禁拒绝（`tip-moved`），除非一次干净且无冲突的 rebase
+  给予了豁免。reviewer 在 spawn 之后修改分支会被拒绝（`reviewer must not modify the mission branch`）。
+- **审查默认可选，可由三态策略强制。** `review.mode` 取 `off`、`optional`（默认）或 `required`。
+  设为 `required` 才启用独立审查门禁。策略为 required 时，mission 级 `reviewPolicy:"none"` + 理由是
+  更窄的豁免。策略为 `off` 时审查被有意关闭；为 `optional` 时插件不强制职责分离，只应用于可信仓库或
+  有人类监督的会话。该策略是插件页上的一个控件，不是组件行。
 - **角色强制。** 调用方会根据 roster 解析。worker 的 mission 更新仅限于 task/blocker/note；
   `completed`、`abandoned`、扩大 scope 与清除 blocker 仅限控制塔，完成（连同未读消息/提交门禁）必须
   走 `tower_complete`。仅限控制塔的工具会以 `[tower:not-authorized]` 拒绝 roster 中的 worker。
@@ -52,8 +53,8 @@ Tower 模式并修复它”。Tower **不认证**这句话背后的人类意图
 
 它**不**防御：完全通过所有门禁但被恶意指令操纵的模型；仓库自己声明的 hooks/测试命令；或无视
 指令、通过 shell 访问 worktree 之外文件的 worker。更高保证的团队应设
-`mode.allowAgentControl:false`、保持 `review.requireReview:true`、在运行 Tower 前审查仓库，并用
-OS 级隔离运行 host。
+`mode.allowAgentControl:false`、保持审查策略为 `review.mode:required`、在运行 Tower 前审查仓库，
+并用 OS 级隔离运行 host。
 
 ## 不由插件强制执行的约束（部署关注点）
 

package/docs/zh/reference/blockers.md

@@ -5,6 +5,10 @@
 `tower_preflight` 返回 `{ok:false, blockers:[{code, detail}]}`。`tower_merge` 与 `tower_rebase`
 在操作失败时返回相同结构。code 稳定；detail 面向人。下表共定义 32 个稳定 blocker/failure code。
 
+下列审查 blocker（`no-review`、`review-mission-mismatch`、`not-clean`、`review-hold`、
+`review-not-approved`、`tip-moved`、`review-exemption-invalid`）只在 `review.mode` 为 `required`
+时产生。`off` 或 `optional` 不会产生审查 blocker；`off` 还会移除 `tower_review` 并拒绝 reviewer spawn。
+
 ## 门禁 blocker（26 个）
 
 | Code | 含义 / 下一步 |
@@ -16,16 +20,16 @@
 | `no-check-evidence` | 启用了 `gates.requireChecks` 且完成报告没有 `checks`。把 completed mission 退回 `active`，带 checks 重新调用 `tower_complete`，然后重新审查。 |
 | `branch-missing` | 还没有 worktree/分支：先 spawn worker。 |
 | `stale-base` | 分支不包含基线 tip：执行 `tower_rebase`。 |
-| `read-only-survey` | survey mission 修改了文件；survey mission 必须只读。 |
 | `out-of-scope` | 改动文件超出 mission scope；有意为之就扩大 scope，否则回退。在大小写敏感的检出上，仅大小写不同的路径仍会被拒绝，detail 会指出折叠大小写后本可匹配的 scope 条目。 |
 | `base-dirty` | 主检出存在未提交改动，合并会覆盖它们。 |
 | `deps-unmerged` | 依赖 mission 尚未满足：build 依赖须 `merged`/`abandoned`；survey 依赖在 `completed` 即视为满足（含归档记录）。 |
-| `no-review` | `review.requireReview:true` 且分支上没有审查：spawn reviewer（或关闭审查门禁）。 |
-| `review-mission-mismatch` | `review.requireReview:true` 且最新审查属于另一个 mission。 |
-| `not-clean` | `review.requireReview:true` 且最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮（同一轮的各 route 结论会追加记录，不会让状态反复翻转）。 |
-| `review-hold` | `review.requireReview:true` 且最新审查建议 hold；必须由后续的干净审查取代。 |
-| `review-not-approved` | `review.requireReview:true` 且最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
-| `tip-moved` | `review.requireReview:true` 且审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |
+| `survey-stale` | build 依赖的 survey 的 `readCommit` 不是 build base 的祖先或同一提交。默认只是 `plan`/`preflight` 的 `warnings[]` 条目；`gates.requireFreshSurvey:true` 时同一 code 阻止合并。针对当前 base 重新规划 survey，或记录为何该读取仍然有效。 |
+| `no-review` | `review.mode:required` 且分支上没有审查：spawn reviewer（或关闭审查门禁）。 |
+| `review-mission-mismatch` | `review.mode:required` 且最新审查属于另一个 mission。 |
+| `not-clean` | `review.mode:required` 且最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮（同一轮的各 route 结论会追加记录，不会让状态反复翻转）。 |
+| `review-hold` | `review.mode:required` 且最新审查建议 hold；必须由后续的干净审查取代。 |
+| `review-not-approved` | `review.mode:required` 且最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
+| `tip-moved` | `review.mode:required` 且审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |
 | `worker-busy` | 该 mission 的 roster agent 正在运行；等待或让其退役。 |
 | `worker-status-unknown` | 父目录不可用，无法证明 live roster agent 已停止；等目录恢复后重试，或先 adopt。 |
 | `base-wrong-branch` | 主检出不在记录的基线分支上。 |
@@ -33,7 +37,7 @@
 | `worker-stale` | 该 mission 的 roster worker 超过 `spawn.staleMs` 没有目录活动；合并前 adopt（只有确实还在运行时才 interrupt）。 |
 | `tests-missing` | 启用了 `gates.requireTests` 且没有针对当前分支 tip 的通过测试回执；运行 `tower_test` 或 `tower_complete`。 |
 | `tests-failed` | 最新测试发现回执失败，或不满足 minCount/required 检查。修复测试并重跑。 |
-| `review-exemption-invalid` | `review.requireReview:true` 且 mission 请求 `reviewPolicy:"none"`，但 `gates.allowReviewExemption` 关闭（或缺少理由）。 |
+| `review-exemption-invalid` | `review.mode:required` 且 mission 请求 `reviewPolicy:"none"`，但 `gates.allowReviewExemption` 关闭（或缺少理由）。 |
 | `merge-intent-pending` | 崩溃/失败前记录了合并意图；先运行 `tower_merge` 对账，再进行其他门禁。 |
 
 ## 合并失败（4 个）
@@ -59,4 +63,4 @@
 分支已包含在基线中时，`tower_rebase` 返回 `alreadyMerged: true`；此时调用 `tower_merge` 记录这次
 已落地的合并。
 
-稳定的 blocker code 共 32 个（26 个门禁 + 4 个合并失败 + 2 个 rebase 专属；`worker-busy` 与门禁共用）。
+稳定的 blocker code 共 31 个（25 个门禁 + 4 个合并失败 + 2 个 rebase 专属；`worker-busy` 与门禁共用）。

package/docs/zh/reference/config.md

@@ -27,13 +27,30 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 
 ```json
 {
-  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
+  "review": { "mode": "required", "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
 }
 ```
 
+`review.mode` 就是审查策略：`off`、`optional` 或 `required`。`review.requireReview` 是保留一个版本的
+兼容别名（`true` → `required`，`false` → `optional`），请优先使用 `review.mode`。同一层同时设置两者时，
+`requireReview:true` 与任何非 `required` 的 mode 冲突，会以 `config-invalid` 拒绝并同时点名两个键。
+`requireReview:false` 与任何显式 mode 都不冲突：`off`、`optional`、`required` 都接受，且以 mode 为准
+（`required` 仍然强制门禁；只有该 mode 才会把解析后的别名镜像回 `true`）。仓库层会独立解析：它可以放宽
+审查，但若 profile 已是 `review.mode:off`，`tower_review` 根本没有注册，仓库层不能自行提高 mode。
+
+插件页控件显示的正是运行时解析出的策略：`review.mode` 存在时以它为准；只设置了 `review.requireReview`
+的配置会显示为「必需」（`true`）或「可选」（`false`）。保存任何选择都会在同一份 profile patch 中写入
+`review.mode`，并把 `review.requireReview` 置为 `false`，因此该别名不可能与所选 mode 矛盾。
+
+同样的三个选项也出现在插件页的 `dsh-tower` 配置区：**关闭**、**可选**（默认）和 **必需**，每个选项都有一行效果说明。
+该控件通过宿主设置表单写入 profile 配置，因此无需手动编辑文件，页面就会接受并显示所选值。
+
+但已挂载的工具面无法实时重建：启动时审查为关闭的 profile 没有注册 `tower_review`。通过页面切换到「可选」
+或「必需」会立即改变合并门禁，但审查工具本身需要重启（或重新加载配置）后才会出现；出现这种情况后控件会给出提示。
+
 `mode.*` 分组是会话级的，不是仓库级的：为兼容 schema，它可以在仓库文件中出现，但只有 profile
 配置能控制 Tower 模式提示与模型切换开关。文件格式错误、值不是对象、未知顶层键，或违反声明 schema
 的值（例如 `merge.timeoutMs` 小于 1000）会以稳定的 `config-invalid` / `config-unknown-key`
@@ -60,7 +77,8 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `mode.denyTools` | goal/todo/team/workflow/subagent 工具（默认 12 个） | 模式激活期间被拒绝的工具。 |
 | `mode.storePath` | `$DSH_HOME/tower-mode` | `modes.json` 所在目录。 |
 | `mode.maxEntries` | `200` | 最多持久化的模式条目数（1–2000）。 |
-| `review.requireReview` | `false` | 合并前是否强制独立 clean 审查。默认 `false`（审查可选）；设为 `true` 则要求 `no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch` 全部通过。`tower_review` 始终可用。 |
+| `review.mode` | `optional` | 审查策略。`off` = 审查被有意关闭（记录审查会被拒绝、`tower_spawn` 拒绝 reviewer 角色、合并门禁忽略审查；profile 级的 `off` 也不会注册 `tower_review`，仓库级的 `off` 则拒绝提交）；`optional` = 审查可用但从不阻塞合并（默认）；`required` = 绑定分支 tip 的 clean 审查是合并门禁（`no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch`）。 |
+| `review.requireReview` | `false` | `review.mode` 的兼容别名（已弃用）：`true` → `required`，`false` → `optional`。请优先使用 `review.mode`。`true` 与非 `required` 的 `review.mode` 同时设置会以 `config-invalid` 拒绝并点名两个键；`false` 可与任何显式 `review.mode`（`off`/`optional`/`required`）共存，且不会覆盖它。插件页控件在该别名是唯一键时按它显示，并在保存时写入 `review.mode` 且把 `review.requireReview` 归一化为 `false`。 |
 | `review.maxRoundsPerReviewer` | `5` | 每个 reviewer 对每条分支的审查轮数上限。 |
 | `merge.timeoutMs` | `900000`（15 分钟） | `tower_merge` 默认超时，包含钩子；单次调用的 `timeoutMs` 优先。 |
 | `merge.maxBufferBytes` | `67108864`（64 MB） | 合并输出缓冲区。 |
@@ -81,11 +99,10 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `tests.admission` | `off` | `spawn` 在启动 worker 前运行发现（fail-closed，不启动子代理）；`complete` 在 `tower_complete` 时运行；`off` 只在显式 `tower_test` 时运行（默认；不会自动执行仓库代码）。 |
 | `tests.timeoutMs` | `60000` | 每条发现命令的超时。 |
 | `tests.maxBytes` | `16777216`（16 MiB） | 每条命令捕获的 stdout 上限。 |
-| `tests.autoChecks` | `true` | 向完成报告附加自动 `tests` 检查。 |
 | `tests.allowPackageDiscovery` | `true` | 允许仓库控制的 `tower.testDiscovery` 命令（会执行 worktree 代码；见安全页）。 |
-| `gates.requireChecks` | `false` | 合并前要求至少一条 `tower_complete.checks` 证据（`no-check-evidence`）。 |
+| `gates.requireChecks` | `false` | 合并前要求至少一条已记录检查（`tower_complete.checks`）或测试回执（`no-check-evidence`）。 |
 | `gates.requireTests` | `false` | 要求针对当前 mission 分支 tip 的通过测试回执（`tests-missing`）；与审查门禁独立。`tower-tests` 组件行关闭时，规划/进入模式会带解释拒绝该组合。 |
-| `gates.allowReviewExemption` | `false` | 在 `review.requireReview:true` 时，允许用 `reviewPolicy:"none"` + 非空理由跳过审查 blocker；默认故意关闭；全局审查关闭时无影响。 |
+| `gates.allowReviewExemption` | `false` | 在 `review.mode:required` 时，允许用 `reviewPolicy:"none"` + 非空理由跳过审查 blocker；默认故意关闭；`review.mode` 为 `off` 或 `optional` 时无影响（不会产生审查 blocker）。 |
 | `gates.maxReportBytes` | `32768`（32 KiB） | `tower_complete.report` 的 UTF-8 字节硬上限。超出时以 `invalid-argument` 拒绝并给出可执行的 `nextAction`（把全文写进 mission worktree 的文件并引用路径），绝不截断。已存在的超限报告仍可读取。 |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。是否写出看板由 `tower-board` 组件行决定（#133）；`docs.board` 已移除，会作为未知键被拒绝。 |
 | `archive.afterDays` | `30` | 年龄触发：终态任务超过这么多天未更新，会在下次变更时归档（`0` 表示立即归档）。归档本身由 `tower-archive` 组件行决定（#135）；`archive.enabled` 已移除，会作为未知键被拒绝。 |

package/docs/zh/reference/errors.md

@@ -3,7 +3,7 @@
 [English](../../reference/errors.md) | **简体中文**
 
 工具失败是抛出的错误，不是 `{ok:false}` 结果（门禁结果是例外：见 [blockers.md](blockers.md)）。
-每个抛出的错误都以稳定 code 作为消息前缀。本版本定义 35 个工具错误码。
+每个抛出的错误都以稳定 code 作为消息前缀。本版本定义 36 个工具错误码。
 
 ```
 [tower:mission-not-found] unknown mission "M9"
@@ -35,6 +35,7 @@
 | `provider-cooldown` | 连续可重试的 provider 失败后，spawn 进入短暂冷却。 | 等待 `blockedUntil` 后重试 |
 | `preset-missing` | 配置的 agent preset 未注册。 | 缺少 `tower-worker`/`tower-reviewer` preset 行、DSH 未重启 |
 | `reviewer-prerequisite` | reviewer spawn 的前置条件未满足。 | mission 尚未 `completed` 或还没有 worktree 就 spawn reviewer |
+| `review-disabled` | 审查被 `review.mode:off` 关闭；该配置下没有 reviewer、审查结论或审查 blocker。 | `review.mode` 为 `off` 时以 `role:"reviewer"` 调用 `tower_spawn`，或提交审查 |
 | `not-authorized` | 调用方 agent 角色无权执行该操作。 | worker 调用仅限控制塔的工具，或修改 mission 状态/scope；reviewer 修改 finding |
 | `workspace-busy` | 另一个 Tower 会话持有该仓库的 workspace 锁。 | `mode.workspaceLock:true` 时第二个会话调用仓库级工具 |
 | `worker-limit` | 仓库达到 `spawn.maxLiveWorkers` 个活跃 worker。 | 默认上限下 spawn 第五个 worker |

package/docs/zh/reference/testing.md

@@ -48,10 +48,11 @@ stdout/stderr 文件、SHA-256 哈希、退出码、计数、required 名称、w
 `tower_complete` 会抛出 `[tower:tests-failed]`。
 
 - `tower_test({repoRoot,missionId})` 按需运行发现并记录回执。
-- `tests.autoChecks` 开启时，`tower_complete` 会添加一条 `tests` 检查。
-- `gates.requireChecks` 要求任意完成检查；`gates.requireTests` 要求针对当前 mission 分支 tip 的
-  通过回执（`tests-missing`）。测试门禁与审查独立：即使 `review.requireReview:false`，测试门禁仍
-  检查分支 tip。
+- `testRuns` 中的回执是唯一的证据形态；`tower_complete` 不再向完成报告复制 `tests` 检查，完成检查、批次关闭
+  与 `gates.requireChecks` 读取同一份回执。
+- `gates.requireChecks` 要求任意已记录检查或回执；`gates.requireTests` 要求针对当前 mission 分支 tip 的
+  通过回执（`tests-missing`）。测试门禁与审查独立：即使策略为 `review.mode:optional`（默认）或
+  `off`，测试门禁仍检查分支 tip。
 
 ## 信任边界
 

package/docs/zh/reference/tools.md

@@ -37,7 +37,7 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_plan` | `missions[]`（`title`——可打印 Unicode，NFC 规范化，≤120 字符、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。mission id 保持 ASCII（`M1`、`M2`）；不可见字符与超长标题会以 `invalid-argument` 拒绝。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
 | `tower_mission` | `id`（别名 `missionId`）、`status?`、`task_done?`、`task_drop?`+`task_drop_reason?`、`blocker?`、`clear_blockers?`、`note?`、`scope?`、`pause_cause?`、`authorization?` | 更新单个 mission。worker 可安全使用的字段是 task/blocker/note；不能在这里设置 `merged`。暂停的 mission 记录 `pause_cause`（user/failure/resource/dependency）；恢复用户暂停的 mission 会遵循 `mode.requireResumeAuthorization`。 |
 | `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。分页 mission 只带 `reportBytes`；`missionId` 返回完整详情（任务/备注/审查/finding/完成报告正文）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。还返回仓库级 git 互斥锁 `gitLock`（`{held, pid, phase, heldMs}`，空闲时 `{held:false}`）。 |
-| `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
+| `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`；`review.mode:off` 时 reviewer 角色会以 `[tower:review-disabled]` 被拒绝。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
 | `tower_roster` | — | roster 及来自子代理目录的实时活动（`running`/`inactive`/`missing`/`unknown`）与 `stale` 标记。只读。 |
 | `tower_adopt` | `retireMissing?` | 把 roster 条目与持久子代理目录对账。可证明已消失的 agent 会被标记为 retired（默认），或标记为 `missing`（`retireMissing:false`）以便检查/接管。 |
 | `tower_diff` | `missionId`（别名 `id`）、`maxBytes?` | 只读 merge-base diff：文件、提交、有上限的 patch。供 reviewer 安全使用。 |
@@ -47,8 +47,8 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_interrupt` | `to?`（roster 名称）、`agentId?`、`reason?` | 通过 `subagents.interrupt` 中断一个运行中的 roster agent，并记录 `state:"interrupted"`。幂等（未运行 → `interrupted:false`）。 |
 | `tower_finding` | `type`、`title`、`summary`、`details`、`suggested_fix`、`severity?`、`missionId?`、`location?` | 记录 scope 之外的问题；reviewer 用它代替直接改文件。新 finding 初始为 `open`。 |
 | `tower_findings` | `id?`、`status?`、`note?`、过滤（`type?`、`severity?`、`missionId?`、`open?`、`limit?`） | 生命周期工具：列出/读取/流转。状态为 `open → triaged → fixed`/`wontfix`，允许重新打开。只有控制塔或 worker 能修改；reviewer 只能列出/读取。 |
-| `tower_review` | `missionId`（别名 `id`）、`status`（`clean`/`p1-Nitems`/`p2-Nitems`）、`merge`（`merge`/`fix-then-merge`/`hold`）、`findings`、`decision`、`checks?`、`breakGlassReason?` | 绑定当前 tip 的 reviewer 结论。reviewer 必须是获派的 reviewer（或由控制塔使用 break-glass）。非 clean 结论使 mission 回到 active 后，其他 route 仍可为同一 reviewed tip 提交结论：追加到同一轮（`appended:true`），不再改变状态；tip 已移动时会被明确拒绝。 |
-| `tower_preflight` | `missionId`（别名 `id`） | 只读门禁：返回 `{ok, blockers[], branchTip, baseTip, changedFiles, review}`。 |
+| `tower_review` | `missionId`（别名 `id`）、`status`（`clean`/`p1-Nitems`/`p2-Nitems`）、`merge`（`merge`/`fix-then-merge`/`hold`）、`findings`、`decision`、`checks?`、`breakGlassReason?` | 绑定当前 tip 的 reviewer 结论。reviewer 必须是获派的 reviewer（或由控制塔使用 break-glass）。`review.mode:off` 时不注册；仓库层为 `off` 时提交会以 `[tower:review-disabled]` 被拒绝。非 clean 结论使 mission 回到 active 后，其他 route 仍可为同一 reviewed tip 提交结论：追加到同一轮（`appended:true`），不再改变状态；tip 已移动时会被明确拒绝。 |
+| `tower_preflight` | `missionId`（别名 `id`） | 只读门禁：返回 `{ok, blockers[], branchTip, baseTip, changedFiles, review}`。审查 blocker 只在 `review.mode:required` 时出现；`off`/`optional` 会跳过。 |
 | `tower_merge` | `missionId`（别名 `id`）、`timeoutMs?`（别名 `timeout_ms`） | 门禁全绿后合并。若合并提交已落地则记录（`reconciled`）；若命令失败但提交已存在则恢复（`recoveredFromFailure`）；区分 `merge-hook-failed` 与 `merge-conflict`。 |
 | `tower_rebase` | `missionId`（别名 `id`） | 在 worktree 内把分支 rebase 到基线。worker 运行中或 worktree 脏时拒绝。分支已包含在基线中时返回 `alreadyMerged` 且保持分支不动。 |
 | `tower_teardown` | `force?`、`exclude?`、`dry_run?`（别名 `dryRun`） | 移除符合条件的 merged/abandoned worktree 与分支；运行中的 agent 始终保留。 |

package/domain/batch.js

@@ -1,5 +1,11 @@
 // Batch admission packets (2.1): pure create/close/summarize validation.
 //
+// A batch is a second, generic lifecycle layered over missions (#149 W3): it is
+// not a mission shape and never gets a kind. Its whole lifecycle — statuses,
+// transition edges, terminality, legacy-status normalization and the status
+// vocabulary — lives in this module (see `BATCH_STATUS*`), so no other module
+// compares or writes `batch.status` to a string literal.
+//
 // This module performs no filesystem, git, or subprocess I/O. The tower tool
 // layer reads the worktree, receipt files, and test results, then passes what
 // it observed into `validateClose`. Receipt hashes may be supplied by the
@@ -11,7 +17,7 @@
 //   state.missions[]        -> { id, status, mergedCommit?, completionReport?, testRuns? }
 //   state.batches[]         -> { id, status: 'open'|'closed'|'abandoned', missionIds,
 //                                exclusions, requiredChecks, receiptPaths, receiptHashes? }
-//   state.legacySnapshots[] -> { hash, missions: [{ id, status }], pausedIds? }
+//   state.legacySnapshots[] -> { sourceHash, pausedMissionIds: string[] }
 // A batch record is the normalized validateCreate result plus `id`, `status`,
 // `createdAt`, and the optional `receiptHashes` expected-hash map.
 //
@@ -23,16 +29,64 @@
 // `input.treeTip` to bind recorded check `treeCommit` values to the current
 // HEAD.
 import path from 'node:path'
+import { findEvidence } from './evidence.js'
+import { shapeFor } from './shapes/index.js'
 
 const SHA256_PATTERN = /^[a-f0-9]{64}$/i
 const MAX_MISSIONS = 50
 const MAX_CHECKS = 50
 const MAX_RECEIPTS = 200
 const MAX_EXCLUSIONS = 50
-const PASS_STATUSES = new Set(['passed', 'pass', 'ok', 'success', 'succeeded', 'done', 'green'])
-const FAIL_STATUSES = new Set(['failed', 'fail', 'error', 'errored', 'timeout', 'timed-out', 'blocked'])
-const OPEN_BATCH_STATUSES = new Set(['open', 'created', 'active', 'pending'])
-const CLOSED_BATCH_STATUSES = new Set(['closed', 'abandoned'])
+
+// The batch lifecycle contract (#149 W3). A batch is opened by tower_batch
+// create and leaves `open` exactly once, to `closed` (every member verified) or
+// `abandoned` (retired without verification). There is no third stop state and
+// no per-shape variant.
+export const BATCH_STATUS = Object.freeze({ OPEN: 'open', CLOSED: 'closed', ABANDONED: 'abandoned' })
+/** @type {readonly string[]} */
+export const BATCH_STATUSES = Object.freeze([BATCH_STATUS.OPEN, BATCH_STATUS.CLOSED, BATCH_STATUS.ABANDONED])
+export const BATCH_TRANSITIONS = Object.freeze({
+  [BATCH_STATUS.OPEN]: Object.freeze([BATCH_STATUS.CLOSED, BATCH_STATUS.ABANDONED]),
+  [BATCH_STATUS.CLOSED]: Object.freeze([]),
+  [BATCH_STATUS.ABANDONED]: Object.freeze([]),
+})
+// Pre-v5 documents (and hand-written fixtures) used synonyms for `open`; v5
+// normalizes them once in the state migration and nothing else accepts them.
+/** @type {readonly string[]} */
+const LEGACY_OPEN_BATCH_STATUSES = Object.freeze(['created', 'active', 'pending'])
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isBatchTerminal(value) {
+  return value === BATCH_STATUS.CLOSED || value === BATCH_STATUS.ABANDONED
+}
+
+/**
+ * @param {unknown} from
+ * @param {unknown} to
+ * @returns {boolean}
+ */
+export function canTransitionBatch(from, to) {
+  return (BATCH_TRANSITIONS[/** @type {string} */ (from)] ?? []).includes(/** @type {string} */ (to))
+}
+
+/**
+ * Normalize a recorded batch status to the canonical vocabulary. An absent
+ * status means `open`; a legacy synonym means `open`; an unknown value is left
+ * as-is so validation can report it instead of silently rewriting it.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeBatchStatus(value) {
+  if (value === undefined || value === null || value === '') return BATCH_STATUS.OPEN
+  const status = String(value)
+  if (BATCH_STATUSES.includes(status)) return status
+  if (LEGACY_OPEN_BATCH_STATUSES.includes(status)) return BATCH_STATUS.OPEN
+  return status
+}
+
 
 /** Stable batch error; add `batch-invalid` to ERROR_CODES to map it directly. */
 export class BatchError extends Error {
@@ -123,28 +177,13 @@ function normalizeReceiptPathOrNull(value, where) {
 /** Legacy snapshots imported by adapters/legacy.js; only paused missions may be excluded. */
 function pausedLegacyIds(state) {
   const ids = new Set()
-  const collectMission = (mission) => {
-    if (isPlainObject(mission) && nonEmptyString(mission.id) && mission.status === 'paused') {
-      ids.add(mission.id.trim())
-    }
-  }
-  const collectList = (value) => {
-    if (Array.isArray(value)) value.forEach(collectMission)
-    else if (isPlainObject(value)) Object.values(value).forEach(collectMission)
-  }
   const snapshots = Array.isArray(state.legacySnapshots) ? state.legacySnapshots : []
   for (const snapshot of snapshots) {
     if (!isPlainObject(snapshot)) continue
-    collectList(snapshot.missions)
-    if (isPlainObject(snapshot.snapshot)) collectList(snapshot.snapshot.missions)
-    if (isPlainObject(snapshot.payload)) collectList(snapshot.payload.missions)
-    // adapters/legacy.js stores imported snapshots with `pausedMissionIds`; older,
-    // hand-written fixtures may use `pausedIds`.
-    for (const key of ['pausedIds', 'pausedMissionIds']) {
-      if (Array.isArray(snapshot[key])) {
-        for (const id of snapshot[key]) if (nonEmptyString(id)) ids.add(id.trim())
-      }
-    }
+    // #149 W4: `pausedMissionIds` is the one canonical field the legacy adapter
+    // writes. Reading any other shape here would be a second live vocabulary.
+    if (!Array.isArray(snapshot.pausedMissionIds)) continue
+    for (const id of snapshot.pausedMissionIds) if (nonEmptyString(id)) ids.add(id.trim())
   }
   return ids
 }
@@ -153,82 +192,13 @@ function missionInOpenBatch(state, missionId) {
   const batches = Array.isArray(state.batches) ? state.batches : []
   for (const batch of batches) {
     if (!isPlainObject(batch)) continue
-    const status = batch.status ?? 'open'
-    if (!OPEN_BATCH_STATUSES.has(status)) continue
+    const status = normalizeBatchStatus(batch.status ?? BATCH_STATUS.OPEN)
+    if (isBatchTerminal(status)) continue
     if (Array.isArray(batch.missionIds) && batch.missionIds.includes(missionId)) return batch
   }
   return null
 }
 
-function checkNames(entry) {
-  if (!isPlainObject(entry)) return []
-  for (const candidate of [entry.name, entry.id, entry.check]) {
-    if (nonEmptyString(candidate)) return [candidate.trim()]
-  }
-  // A nameless runDiscovery receipt stored in mission.testRuns is the built-in
-  // test tool evidence. It answers to `tests` (the tool-layer auto check name)
-  // and to `tower_test` (the synthetic name used by earlier integrations).
-  if (Array.isArray(entry.commands) && Array.isArray(entry.tests)) return ['tests', 'tower_test']
-  return []
-}
-
-function checkOutcome(entry) {
-  if (!isPlainObject(entry)) return null
-  if (typeof entry.status === 'string') {
-    const status = entry.status.trim().toLowerCase()
-    if (PASS_STATUSES.has(status)) return true
-    if (FAIL_STATUSES.has(status)) return false
-  }
-  if (typeof entry.ok === 'boolean') return entry.ok
-  if (typeof entry.pass === 'boolean') return entry.pass
-  if (typeof entry.success === 'boolean') return entry.success
-  if (entry.exitCode !== undefined && entry.exitCode !== null) {
-    const exitCode = typeof entry.exitCode === 'number' ? entry.exitCode : Number(entry.exitCode)
-    if (Number.isFinite(exitCode)) return exitCode === 0
-  }
-  if (entry.error !== undefined && entry.error !== null && entry.error !== '') return false
-  return null
-}
-
-/**
- * Find the most authoritative recorded outcome for `name` on one mission:
- * completion report first, then testRuns newest-first, then caller-supplied
- * `extraChecks` (optionally scoped by `missionId`).
- */
-function findCheck(mission, name, extraChecks, missionId) {
-  const sources = []
-  const reportChecks = Array.isArray(mission?.completionReport?.checks) ? mission.completionReport.checks : []
-  for (let index = reportChecks.length - 1; index >= 0; index -= 1) {
-    sources.push({ source: 'completionReport', entry: reportChecks[index] })
-  }
-  const testRuns = Array.isArray(mission?.testRuns) ? mission.testRuns : []
-  for (let index = testRuns.length - 1; index >= 0; index -= 1) {
-    const run = testRuns[index]
-    if (!isPlainObject(run)) continue
-    if (Array.isArray(run.checks) && run.checks.length > 0) {
-      for (let inner = run.checks.length - 1; inner >= 0; inner -= 1) {
-        sources.push({ source: 'testRuns', entry: run.checks[inner] })
-      }
-    } else {
-      sources.push({ source: 'testRuns', entry: run })
-    }
-  }
-  for (let index = extraChecks.length - 1; index >= 0; index -= 1) {
-    const entry = extraChecks[index]
-    if (!isPlainObject(entry)) continue
-    const scope = entry.missionId ?? entry.mission_id
-    if (scope !== undefined && scope !== null && String(scope) !== missionId) continue
-    sources.push({ source: 'input', entry })
-  }
-  for (const source of sources) {
-    if (!checkNames(source.entry).includes(name)) continue
-    const outcome = checkOutcome(source.entry)
-    if (outcome === null) continue
-    return { outcome, source: source.source, entry: source.entry }
-  }
-  return null
-}
-
 function blocker(message, code = 'batch-invalid') {
   return { code, message }
 }
@@ -414,9 +384,9 @@ export function validateClose(state, batch, input = {}) {
   const receiptPaths = receiptPathsRaw.map((value, index) => normalizeReceiptPath(value, `batch.receiptPaths[${index}]`))
 
   const blockers = []
-  const status = batch.status ?? 'open'
-  if (status === 'closed') blockers.push(blocker(`batch ${batch.id ?? ''} is already closed`.trim()))
-  else if (status === 'abandoned') blockers.push(blocker(`batch ${batch.id ?? ''} is abandoned`.trim()))
+  const status = normalizeBatchStatus(batch.status ?? BATCH_STATUS.OPEN)
+  if (status === BATCH_STATUS.CLOSED) blockers.push(blocker(`batch ${batch.id ?? ''} is already closed`.trim()))
+  else if (status === BATCH_STATUS.ABANDONED) blockers.push(blocker(`batch ${batch.id ?? ''} is abandoned`.trim()))
 
   const missions = Array.isArray(state.missions) ? state.missions : fail('state.missions must be an array')
   const byId = new Map()
@@ -447,13 +417,13 @@ export function validateClose(state, batch, input = {}) {
         results.push({ missionId, name, ok: true, outcome: 'skipped', source: 'abandoned' })
         continue
       }
-      const found = findCheck(mission, name, extraChecks, missionId)
+      const found = findEvidence(shapeFor(mission.kind).evidence, mission, name, { extraChecks, missionId })
       if (!found) {
         results.push({ missionId, name, ok: false, outcome: 'missing', source: null })
         blockers.push(blocker(`mission ${missionId} has no recorded check "${name}"`, 'tests-missing'))
         continue
       }
-      if (found.outcome !== true) {
+      if (found.ok !== true) {
         results.push({ missionId, name, ok: false, outcome: 'failed', source: found.source })
         blockers.push(blocker(`mission ${missionId} check "${name}" did not pass`, 'tests-failed'))
         continue
@@ -507,14 +477,14 @@ export function summarize(state, batch) {
   if (!Array.isArray(receiptPathsRaw)) fail('batch.receiptPaths must be an array')
   const receiptPaths = receiptPathsRaw.map((value, index) => normalizeReceiptPath(value, `batch.receiptPaths[${index}]`))
   const exclusions = Array.isArray(batch.exclusions) ? batch.exclusions : []
-  const status = batch.status ?? 'open'
+  const status = normalizeBatchStatus(batch.status ?? BATCH_STATUS.OPEN)
 
   const missions = Array.isArray(state.missions) ? state.missions : fail('state.missions must be an array')
   const byId = new Map()
   for (const mission of missions) if (isPlainObject(mission) && nonEmptyString(mission.id)) byId.set(mission.id, mission)
 
   const blockers = []
-  if (CLOSED_BATCH_STATUSES.has(status)) blockers.push(blocker(`batch ${batch.id ?? ''} is already ${status}`.trim()))
+  if (isBatchTerminal(status)) blockers.push(blocker(`batch ${batch.id ?? ''} is already ${status}`.trim()))
   const members = []
   const checks = []
   for (const missionId of missionIds) {
@@ -539,7 +509,7 @@ export function summarize(state, batch) {
         checks.push({ missionId, name, ok: true, outcome: 'skipped', source: 'abandoned' })
         continue
       }
-      const found = findCheck(mission, name, [], missionId)
+      const found = findEvidence(shapeFor(mission.kind).evidence, mission, name, { missionId })
       if (!found) {
         checks.push({ missionId, name, ok: false, outcome: 'missing', source: null })
         continue
@@ -547,8 +517,8 @@ export function summarize(state, batch) {
       checks.push({
         missionId,
         name,
-        ok: found.outcome === true,
-        outcome: found.outcome === true ? 'passed' : 'failed',
+        ok: found.ok === true,
+        outcome: found.ok === true ? 'passed' : 'failed',
         source: found.source,
       })
     }

package/domain/collab/batch.js

@@ -1,12 +1,14 @@
 // Pure batch lifecycle decisions and status projection.
 //
-// `domain/batch.js` owns the admission/close evidence validation; this module
-// owns the id assignment, close/abandon record transitions, and status payload
-// that app/batch.js used to keep inline. Receipt file reads stay in the tool
-// layer.
+// `domain/batch.js` owns the lifecycle vocabulary, admission/close evidence
+// validation and normalization; this module owns the id assignment, close/abandon
+// record transitions, and status payload that app/batch.js used to keep inline.
+// Receipt file reads stay in the tool layer. Every status move goes through the
+// lifecycle module's `canTransitionBatch`, so this file never names a status
+// literal of its own (#149 W3).
 // @ts-check
 import { TowerToolError } from '../errors.js'
-import { summarize } from '../batch.js'
+import { BATCH_STATUS, canTransitionBatch, isBatchTerminal, normalizeBatchStatus, summarize } from '../batch.js'
 
 /** @typedef {import('../../types/index.js').TowerState} TowerState */
 
@@ -19,6 +21,21 @@ function fail(message, code = 'batch-invalid') {
   throw new TowerToolError(code, message)
 }
 
+/**
+ * Move a draft batch to `to`, refusing a transition the lifecycle does not
+ * allow. A no-op (already at the target) is handled by the callers, not here.
+ * @param {any} batch
+ * @param {string} to
+ * @param {string} batchId
+ * @returns {void}
+ */
+function assertBatchMove(batch, to, batchId) {
+  const from = normalizeBatchStatus(batch.status)
+  if (!canTransitionBatch(from, to)) {
+    fail(`batch ${batchId} is ${from}; it cannot move to ${to}${isBatchTerminal(from) ? ' (a batch is closed or abandoned exactly once)' : ''}`)
+  }
+}
+
 /**
  * Next free `B<n>` id.
  * @param {any[]} batches
@@ -43,7 +60,7 @@ export function nextBatchId(batches) {
 export function createBatchRecord(id, normalized, actor, now) {
   return {
     id,
-    status: 'open',
+    status: BATCH_STATUS.OPEN,
     ...normalized,
     createdBy: actor,
     createdAt: now,
@@ -59,7 +76,8 @@ export function createBatchRecord(id, normalized, actor, now) {
  * @returns {any}
  */
 export function closeBatchRecord(batch, options, actor, now) {
-  batch.status = 'closed'
+  assertBatchMove(batch, BATCH_STATUS.CLOSED, String(batch.id ?? ''))
+  batch.status = BATCH_STATUS.CLOSED
   batch.closedAt = now
   batch.closedBy = actor
   batch.close = {
@@ -78,8 +96,9 @@ export function closeBatchRecord(batch, options, actor, now) {
  * @returns {{ alreadyAbandoned: boolean }}
  */
 export function abandonBatchCheck(batch, batchId) {
-  if (batch.status === 'closed') fail(`batch ${batchId} is already closed`)
-  return { alreadyAbandoned: batch.status === 'abandoned' }
+  const status = normalizeBatchStatus(batch.status)
+  if (status === BATCH_STATUS.CLOSED) fail(`batch ${batchId} is already closed`)
+  return { alreadyAbandoned: status === BATCH_STATUS.ABANDONED }
 }
 
 /**
@@ -88,7 +107,8 @@ export function abandonBatchCheck(batch, batchId) {
  * @returns {any}
  */
 export function applyBatchAbandon({ batch, actor, reason, now }) {
-  batch.status = 'abandoned'
+  assertBatchMove(batch, BATCH_STATUS.ABANDONED, String(batch.id ?? ''))
+  batch.status = BATCH_STATUS.ABANDONED
   batch.abandonedAt = now
   batch.abandonedBy = actor
   batch.abandonReason = typeof reason === 'string' && reason.trim() ? reason.trim() : null