dsh-tower 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -4,6 +4,50 @@
 
 ## 未发布（Unreleased）
 
+## 2.4.1（2026-10-24）
+
+### 修复
+
+- **可选组件行在 Plugins 页面只显示模块名**：每个可选能力导出现在提供
+  `<specifier>/locale/{en,zh}.json`（`meta.title` / `meta.description`），由
+  `locale/<lang>.json` 的 `components` 块经 `npm run docs:generate:locale` 生成，并由
+  `docs:check:generated:locale` + CI 步骤防漂移；描述同时说明能力用途与关闭后移除的内容，
+  开关无需离开页面即可判断。
+
+## 2.4.0（2026-10-24）
+
+### 新增
+
+- **#121 可选能力回到组件**：一个 `tower-bundle` 组拆成强制 `tower` 宿主 + 可独立开关的顶层行
+  （`tower-skills`/`tower-batch`/`tower-import`/`tower-leases`/`tower-tests`/`tower-hmr` 默认关/
+  `preset-tower-reviewer` 依 `review.requireReview` 条件存在）；新增 `./batch`/`./import`/`./leases`/
+  `./tests`/`./hmr` 导出，每个入口只注册自己的能力；8 个可见组件的 title/summary/disables 双语覆盖；
+  任一可选行关闭后 Tower 仍可用（模式、规划、状态、其余工具），缺失能力在 status/doctor 中以
+  “disabled by component <id>” 呈现。
+- **#120 组件面政策载体**：`PRINCIPLES.md` 第 11 条（“optional capabilities are switches; the core is not”）、
+  ADR 0005、64 键的组件轴分类（core / optional-component / optional-config / forbidden-to-disable，由
+  `scripts/component-surface.json` 单一来源生成）、`check-components`（locale 覆盖、forbidden-to-disable
+  denylist、组件计数 baseline）与 `components` 基线；组件面 4→1→8 的变化以带日期的 decision 记录。
+- **#115 类型面完整性**：`types:coverage` 从 `package.json files` 与 `tsc --listFiles` 派生检查程序
+  （146/146 运行时 .js 全覆盖，旧配置下可复现 19 个漏检）；tsconfig 改为 glob；`types:generate` 从运行时常量
+  生成发布词汇（ErrorCode/状态/角色等）并纳入 `--check`，修掉 8 个幽灵码与 4 个缺失码；
+  `tsconfig.strict.json`（noImplicitAny）以显式文件清单起步，manifest 禁止清单收缩。
+- **#118 surface 计数覆盖完整工具面**：`tower_doctor`/生成参考/`docs:check`/`surface:check` 统一为
+  29 个工具面（默认装配 28，tower-hmr 关闭时少 `tower_reload`），直接注册的 `tower_mode`/`tower_control`
+  也进入刹车；baseline 以 correction 记录 27→29。
+
+### 变更
+
+- **#122 安全网永不可关**：`tower_doctor`/`tower_recover` 在任何配置下都注册；删除
+  `tools.exposeDoctor`/`exposeRecovery`/`exposeOperational` 与整个 `tools` 组、`dev.hotReload`；
+  旧配置作为未知键被拒绝并停止挂载（升级指南 en/zh 已记录迁移）。
+- 配置面从 64 键/15 节收缩为 56 键/14 节；生成的 config/tools/component-surface 参考同步更新。
+
+### 修复
+
+- **F11/F9**：`operationalRegistry` 解析容忍 trailing comma 与 `OPERATIONAL_TOOLS.set` 路由；
+  根 README 的工具计数标题修正为 29（20 core + 9 optional）并注明默认装配 28。
+- 真实 `smoke:mount` 在 pinned host `0.2.1-rc.2` 上通过（默认 28/28），required `mount` CI 上下文保持绿。
 ## 2.3.0（2026-10-23）
 
 ### 新增

package/COMPATIBILITY.md

@@ -5,6 +5,8 @@ is shipped in the npm package; doctor reads it locally and never contacts a regi
 
 | dsh version | tag / commit | verified on | what was run |
 |---|---|---|---|
+| 0.2.1-rc.2 | v2.4.1 | 2026-10-24 | mount smoke (28/28 default tools, 3 skills, 2 presets, 1 bundle row), `npm test` (620), `types:coverage` 146/146, docs + seven generated checks incl capability-row locales, components + philosophy + surface gates |
+| 0.2.1-rc.2 | v2.4.0 | 2026-10-24 | mount smoke (28/28 default tools, 3 skills, 2 presets, 1 bundle row), `npm test` (612), `types:coverage` 146/146, strict ratchet 10, docs + six generated checks, components + philosophy + surface gates |
 | 0.2.1-rc.2 | v2.3.0 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (573), `npm run docs:check`, four generated docs checks, philosophy + surface gates, live `--check` |
 | 0.2.1-rc.2 | v2.2.0 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (536), `npm run docs:check`, four generated docs checks |
 | 0.2.1-rc.2 | v2.1.2 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (495), `npm run docs:check`, generated docs checks |

package/CONTRIBUTING.md

@@ -11,7 +11,7 @@ Two short documents say what this project refuses to do:
   pointer does not resolve fails `npm run docs:check:philosophy`.
 - [docs/adr/](docs/adr/README.md) — dated decision records for choices already
   made (ports as data, one `state.json`, `allowAgentControl`, the surface
-  budget).
+  budget, the component surface).
 
 Every pull request answers **"which principle does this change touch, or which new
 one does it require?"** in the PR template. "None" is not an answer: if no
@@ -21,6 +21,16 @@ concept budget and its classification table are in
 or tool may grow only with an ADR or a provably matching deletion, checked by
 `npm run surface:check`.
 
+The component axis — who may be switched off — is principle 11 and
+[ADR 0005](docs/adr/0005-component-surface.md). It is generated from
+[scripts/component-surface.json](scripts/component-surface.json) into
+[docs/reference/component-surface.md](docs/reference/component-surface.md) and
+enforced by `npm run docs:check:components`: every visible component needs
+`title`/`summary`/`disables` in both locales, the host/health/recovery/review/
+merge-gate capabilities may not be gated by any row or boolean key (the
+`gateableTools` allowlist is empty since #122), and the component count — 8
+visible rows in 2.4.0 — is the fourth baselined surface.
+
 ## Landing changes
 
 `main` is protected. Every change lands through a pull request; direct pushes to `main` are rejected,
@@ -108,10 +118,11 @@ the push gates; CI schedules it nightly.
 - `worker.js` — the `tower-worker` preset policy (tool surface + protocol text).
 - `tests/` — add a regression test for every behavior change. The offline suite is `tests/*.test.mjs`; live-runtime scripts are documented in `tests/README.md`.
 - `scripts/architecture.mjs` — the fitness rules; `scripts/architecture-waivers.json` — the only exemptions, each with a `reason` and an `owner`/`ref`. An entry without a reason fails the blocking `waiver-contract` rule, The three layering rules that keep the core pure — `domain-pure`, `host-scope`, and `no-lib-from-core` — cannot be waived at all. The `let` scan behind `host-scope` is statement-aware: every binding of every top-level declaration is recorded, and only `host/**` may hold ambient state.
+- `types/` — the published declaration surface (`package.json` `types` is `types/index.d.ts`). The vocabulary block in that file is generated from the runtime constants by `npm run types:generate` and gated by `npm run docs:check:generated:types`; never edit it by hand. `tsconfig.strict.json` turns `noImplicitAny` on for an explicit file list that may grow but never silently shrink: add a file, then record it with `npm run types:strict:write` (a removal also needs `--allow-shrink`). `npm run types:coverage` fails when a shipped runtime `.js` file is outside the `tsc` program.
 
 ## Pull request checklist
 
-1. `npm test` passes locally (573 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) and `npm run docs:check` passes.
+1. `npm test` passes locally (620 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) and `npm run docs:check` passes.
 2. New behavior has a test. Bug fixes should add a test that fails before the fix.
 3. No secrets, tokens, personal paths, session logs, or generated artifacts are added. `.gitignore` covers local acceptance output; do not force-add it.
 4. Keep the public API and state-file formats compatible; if a change is breaking, call it out in `CHANGELOG.md` and bump the version.
@@ -123,7 +134,13 @@ the push gates; CI schedules it nightly.
    reports no failure; a `Regression test:` path must exist.
 9. If you added a config key or tool, `scripts/surface-baseline.json` and
    [docs/reference/surface-budget.md](docs/reference/surface-budget.md) are updated in the
-   same PR, and `npm run surface:check` passes.
+   same PR, and `npm run surface:check` passes. A visible component change also updates
+   `scripts/surface-baseline.json` (`components`), `scripts/component-surface.json` and
+   `docs/reference/component-surface.md` (`npm run docs:generate:components`), and must pass
+   `npm run docs:check:components`. A new visible capability row also ships its own
+   `<specifier>/locale/*.json` row label via `npm run docs:generate:locale` and passes
+   `npm run docs:check:generated:locale` (see
+   [architecture/overview.md](docs/architecture/overview.md#row-display-metadata-121)).
 
 ## Mount smoke
 

package/PRINCIPLES.md

@@ -135,6 +135,24 @@ without a test path, and a postmortem that names the cause but not the proof.
 Enforced by: `docs/operations/incident.md`, `scripts/regression-audit.mjs`, and
 `tests/regression-audit.test.mjs`; gate: `npm run audit:regressions`.
 
+## 11. Optional capabilities are switches; the core is not
+
+A component may exist only for a capability whose off state leaves the rest of the
+product intact. Every capability that qualifies gets a component, so the user can
+control it. Every capability that does not — the host, the health contract, the
+recovery escape, the review contract, the merge gates — is configuration or code,
+never a switch: not as a row, and not as a boolean that removes it.
+
+Refused because of this: a single all-or-nothing switch offered as "simpler"; a
+disableable `tower_doctor`/`tower_recover`; a core feature exposed as a toggle; a
+component whose off state is worse than uninstalling the plugin.
+
+Enforced by: `scripts/check-components.mjs` (locale coverage, the
+forbidden-to-disable denylist and the generated component reference),
+`scripts/surface-baseline.mjs` (the component count is a baselined surface),
+`docs/adr/0005-component-surface.md`, and `tests/components.test.mjs`; gate:
+`npm run docs:check:components`.
+
 ## Non-goals
 
 This file is not a governance process: there is no RFC queue, no architecture

package/README.en.md

@@ -128,20 +128,33 @@ Image and file attachments are forwarded together with the instruction as one co
 
 ## Component model
 
-This bundle is **all-or-nothing**: `cordis.patch.yml` inserts one `tower-bundle`
-`cordis:group` row, and the Host plugin, skills, and worker/reviewer presets are internal sections
-of it. The plugin page should treat that group as one component; disabling it disables all sections
-together, so no orphan preset or skill points at missing `tower_*` tools. Do not enable/disable the
-child rows independently.
-
-Mode entry and `tower_plan` validate both presets before work starts. A missing preset is refused
-with `preset-missing` and names `preset-tower-worker` / `preset-tower-reviewer`, instead of planning
-or spawning first and dead-ending at review/merge.
+The bundle ships a **mandatory host anchor plus individually switchable optional
+rows** (#121): `cordis.patch.yml` inserts a top-level `tower` group that mounts
+the Host plugin and the mandatory `preset-tower-worker`, then the optional
+components `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`,
+`tower-tests`, `tower-hmr` (shipped off) and `preset-tower-reviewer`. Turn a row
+off from the Plugins page and exactly that capability goes away; the mode, the
+planning tools, `tower_status`, and the remaining tools keep working.
+
+Mode entry and `tower_plan` validate the required presets before work starts. The
+worker preset is mandatory; the reviewer preset is required only when
+`review.requireReview` is true, so the reviewer row may be off while review is
+optional and is locked with an explanatory `preset-missing` error when the gate
+is on. `tower-tests` off with `gates.requireTests:true` is refused the same way.
+`tower_doctor` and `tower_recover` are not components and have no config key: they
+are registered for every configuration (#122).
+
+[Principle 11](PRINCIPLES.md) and
+[ADR 0005](docs/adr/0005-component-surface.md) say a component may exist only for
+a capability whose off state leaves the rest intact; the host, health, recovery,
+review and merge-gate capabilities are never switches. The per-key answer is the
+generated [component surface](docs/reference/component-surface.md), enforced by
+`npm run docs:check:components`.
 
 ## Configuration
 
 ```yaml
-- id: tower
+- id: tower-host
   name: 'dsh-tower'
   config:
     section: 'Optional legacy alias replacing the Tower-mode prompt text'
@@ -166,13 +179,13 @@ or spawning first and dead-ending at review/merge.
 - `mode.allowAgentControl` defaults to `true` in code; the bundled `cordis.patch.yml` also sets it explicitly to `true` so the model may enter/leave when the user intent or task state warrants it, always stating a reason. Set it to `false` for human-only control. The bundled patch also enables `mode.workspaceLock` (single-active tower), `send.interruptDefault`, `init.autoGitInit`, and sets `spawn.staleMs` to 15s.
 - `/tower base <branch>` records a session-level init base preference; `/tower on` clears an active plan mode (`mode.planModePolicy:"refuse"` instead refuses entry), keeping plan and Tower mutually exclusive.
 - Repository-level config: put the same JSON shape in `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`) to override `review`/`merge`/`worktrees`/`spawn`. Precedence is code defaults < profile config < repository config < tool arguments. `mode.*` is session-scoped and only the profile layer controls it.
-- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown top-level keys are rejected so typos cannot silently disable security-relevant settings, while unknown keys inside a group are ignored. Tool error codes are in [docs/reference/errors.md](docs/reference/errors.md).
+- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown keys are rejected (top-level and inside a group) so typos cannot silently disable security-relevant settings. Tool error codes are in [docs/reference/errors.md](docs/reference/errors.md).
 
-## Tools (27 core)
+## Tools (29: 22 core + 7 optional)
 
 `tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_recover` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` is registered by default (`allowAgentControl:true`); set it to `false` to disable it. `tower_reload` is registered while `dev.hotReload` is on (default true) and returns `reload-unavailable` without an HMR service (so up to 29 tools). Mission-scoped tools also accept `id` as an alias for `missionId`; snake/camel spellings such as `task_done`/`taskDone` are both accepted.
+The list above is the 22 core tools plus 5 of the component-owned optional tools. `tower_control` is the sixth optional tool, registered by default (`allowAgentControl:true`); set it to `false` to disable it. `tower_reload` is the seventh, registered only while the `tower-hmr` component row is on (shipped off) and returning `reload-unavailable` without an HMR service (so up to 29 tools: 22 core + 7 optional). `tower_doctor` and `tower_recover` are core: they are registered for every configuration (#122). Mission-scoped tools also accept `id` as an alias for `missionId`; snake/camel spellings such as `task_done`/`taskDone` are both accepted.
 
 ## Safety and guardrails
 
@@ -201,7 +214,7 @@ Workers use the bundled `tower-worker` preset (writable worktree surface); revie
 
 | Path | Contents |
 |---|---|
-| `package.json`, `cordis.patch.yml` | bundle manifest and loader patch (one `tower-bundle` group containing the Host, skills, and both presets) |
+| `package.json`, `cordis.patch.yml` | bundle manifest and loader patch (a mandatory `tower` host group plus the optional capability rows) |
 | `index.js`, `host/`, `adapters/`, `app/`, `domain/`, `ports/`, `tools/`, `worker.js`, `reviewer.js` | Host entry; `domain/` pure core; `ports/` contracts; `adapters/` the only I/O; `app/` use cases; `host/` composition root and session glue; `tools/` one handler per tool; worker and reviewer preset policies |
 | `skills.js`, `skills/` | bundled agent skills (worker protocol, review checklist, recovery playbook) |
 | `docs/` | guides, reference, architecture, operations, FAQ and examples |
@@ -228,7 +241,7 @@ Every push and PR runs the same set of jobs; each job backs one checkable claim
 
 | Job | Claim | Evidence |
 |---|---|---|
-| `test (22)`, `test (24)` (Ubuntu) | the offline suite, documentation consistency, generated references, the published file list, architecture, types, and domain purity all hold | `npm test`, `npm run docs:check`, the four `docs:check:generated*` checks, `pack:check`, `architecture:check`, `types:check`, `domain:check` |
+| `test (22)`, `test (24)` (Ubuntu) | the offline suite, documentation consistency, generated references, the published file list, architecture, types, and domain purity all hold | `npm test`, `npm run docs:check`, the five `docs:check:generated*` checks (including the generated type vocabulary), `pack:check`, `architecture:check`, `types:coverage`, `types:strict:check`, `types:check`, `domain:check` |
 | `test (22, windows)` (`windows-latest`, not required) | the same offline suite and offline gates hold on a real Windows filesystem, so path casing, the `pwsh` shell, and the rename/unlink retries are measured instead of assumed | `npm test` plus the same offline gates as Ubuntu (no release/coverage) |
 | `test`'s `Coverage (Node 22)` step | coverage is actually measured in CI (reported only: no threshold, no badge) | `npm run test:coverage` |
 | `test`'s `Release check` step (Node 22) | a tag is a claim: the version moved past the previous version tag, a pushed tag is `v<version>`, and the changelog carries release content | `npm run release:check` |
@@ -242,7 +255,7 @@ The live suite downloads a browser and boots a real host, so it is out of push/P
 
 `tests/platform.test.mjs` injects `platform`/`rename`/`unlink` so both the win32 and POSIX branches are asserted on any OS; the only case that needs a real Windows filesystem (renaming over an open destination) is counted as `# SKIP` on Linux (`tests 11`, `skipped 1`), never silently absent. There is no macOS runner: macOS follows the same POSIX branch as Linux, which is a #86 non-goal.
 
-`mount` asserts the throwaway profile's **loaded surface**, never the text of `cordis.patch.yml`: 29 `tower_*` tools (27 `tools/*.js` modules plus `tower_mode` / `tower_control`), the 3 bundled skills, both the `tower-worker` and `tower-reviewer` presets, the `/tower` command, and exactly one top-level `tower-bundle` group row (the #66 invariant). It calls no model and opens no browser. Measured on the maintainer's Windows machine: about 100 seconds on a cold host (install included) and about 85 seconds with a cached host; the CI step allows 3 minutes (`timeout-minutes: 3`) inside the 5-minute `mount` job. A red run prints the resolved profile path, the host build, the loaded counts, and every unmet claim.
+`mount` asserts the throwaway profile's **loaded surface**, never the text of `cordis.patch.yml`: 28 `tower_*` tools in the shipped profile (27 `tools/*.js` modules plus `tower_mode` / `tower_control`, minus `tower_reload` because `tower-hmr` ships off; 29 with every optional capability row on), the 3 bundled skills, both the `tower-worker` and `tower-reviewer` presets, the `/tower` command, one top-level `tower` host group, and the optional top-level rows (`tower-hmr` is shipped off). It calls no model and opens no browser. Measured on the maintainer's Windows machine: about 100 seconds on a cold host (install included) and about 85 seconds with a cached host; the CI step allows 3 minutes (`timeout-minutes: 3`) inside the 5-minute `mount` job. A red run prints the resolved profile path, the host build, the loaded counts, and every unmet claim.
 
 The host build is pinned in exactly one place, `scripts/mount-smoke/host.json`; a unit test keeps the newest `COMPATIBILITY.md` row equal to it, so a release never retypes it. `npm run smoke:fixtures` proves the smoke still fails for the right seeded reasons (a renamed tool id, a removed skills section). CI runs it as the non-required `mount-fixtures` job, where the control and both seeds share one cached host install through `--host-dir` (about 2 minutes warm here).
 

package/README.md

@@ -127,19 +127,26 @@ tower_teardown  repoRoot=D:\work\repo
 
 ## 组件模型
 
-本 bundle 采用 **all-or-nothing**：`cordis.patch.yml` 只插入一个 `tower-bundle`
-`cordis:group` 行，Host 插件、skills、worker/reviewer preset 都是它的内部 section。插件页只应把
-这个 group 当作一个组件；关闭它时四个 section 一起关闭，不会留下指向已消失 `tower_*` 工具的
-orphan preset/skill。不要再把子行单独启停。
-
-进入 Tower 模式与 `tower_plan` 前会校验两个 preset 是否已注册；缺失时直接以 `preset-missing`
-拒绝（并在消息中点名 `preset-tower-worker` / `preset-tower-reviewer`），不会先完成规划/派发再在
-review/merge 阶段死锁。
+本 bundle 采用 **强制 host 锚点 + 可单独启停的可选行**（#121）：`cordis.patch.yml` 插入顶层
+`tower` group（挂载 Host 插件与强制的 `preset-tower-worker`），随后是可选组件 `tower-skills`、
+`tower-batch`、`tower-import`、`tower-leases`、`tower-tests`、`tower-hmr`（随包关闭）与
+`preset-tower-reviewer`。在插件页关闭某一行，只会移除该能力；模式、规划工具、`tower_status`
+与其余工具继续工作。
+
+进入 Tower 模式与 `tower_plan` 前会校验必需的 preset。worker preset 是强制依赖；reviewer
+preset 只在 `review.requireReview` 为 true 时必需，因此审查可选时允许关闭 reviewer 行，强制审查
+开启时会以带解释的 `preset-missing` 锁定。`tower-tests` 关闭且 `gates.requireTests:true` 时同样
+拒绝。`tower_doctor` 与 `tower_recover` 不是组件、也没有配置键：任何配置都会注册它们（#122）。
+
+原则 11（[PRINCIPLES.md](PRINCIPLES.md)）与
+[ADR 0005](docs/adr/0005-component-surface.md) 要求：只有关闭后仍不破坏其余能力的 capability
+才能成为组件；host、健康检查、恢复通道、审查契约与合并门禁永远不是开关。逐键答案见生成的
+[组件表面](docs/reference/component-surface.md)，由 `npm run docs:check:components` 强制。
 
 ## 配置
 
 ```yaml
-- id: tower
+- id: tower-host
   name: 'dsh-tower'
   config:
     section: '（可选，兼容别名）覆盖 Tower 模式系统提示文案'
@@ -164,13 +171,13 @@ review/merge 阶段死锁。
 - 代码中 `mode.allowAgentControl` 默认 `true`；随包 `cordis.patch.yml` 也显式设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。随包 patch 还默认开启 `mode.workspaceLock`（单活塔）、`send.interruptDefault`、`init.autoGitInit`，并把 `spawn.staleMs` 设为 15s。
 - `/tower base <branch>` 可设置会话级 init base 偏好；`/tower on` 会清除活跃 plan mode（`mode.planModePolicy:"refuse"` 则拒绝进入），保证 plan/tower 互斥。
 - 仓库级配置：在 `<git-common-dir>/dsh-tower/config.json`（通常是 `.git/dsh-tower/config.json`）放入同样的 JSON 结构，可覆盖 `review`/`merge`/`worktrees`/`spawn`；优先级为代码默认 < profile < 仓库配置 < 工具参数。`mode.*` 属于会话级，只在 profile 生效。
-- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知顶层键会被拒绝（防止拼写错误静默失效），嵌套分组内的未知键会被忽略。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
+- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知键（顶层与分组内）都会被拒绝，防止拼写错误静默失效。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
 
-## 工具（27 个核心）
+## 工具（29 个：22 个核心 + 7 个可选）
 
 `tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_recover` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` 默认注册（`allowAgentControl:true`）；设为 `false` 可禁用；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 29 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
+上面列出的是 22 个核心工具加 5 个由组件行拥有的可选工具。`tower_control` 是第 6 个可选工具，默认注册（`allowAgentControl:true`）；设为 `false` 可禁用。`tower_reload` 是第 7 个，仅在 `tower-hmr` 组件行开启时注册（随包关闭），无 HMR 服务调用会返回 `reload-unavailable`（因此最多 29 个工具：22 个核心 + 7 个可选）。`tower_doctor` 与 `tower_recover` 属于核心：任何配置都会注册它们（#122）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
 
 ## 安全与约束
 
@@ -199,7 +206,7 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 
 | 路径 | 内容 |
 |---|---|
-| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（单个 `tower-bundle` group，内含 Host、skills 与两个 preset） |
+| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（强制 `tower` host group + 可选能力行） |
 | `index.js`、`host/`、`adapters/`、`app/`、`domain/`、`ports/`、`tools/`、`worker.js` | Host 入口；`domain/` 纯核心；`ports/` 契约；`adapters/` 唯一 I/O；`app/` 用例；`host/` 组合根与会话胶水；`tools/` 每工具一个 handler；worker preset 策略 |
 | `locale/`、`icon.svg` | 本地化与图标 |
 | `tests/` | 纯函数、协议 e2e、插件级测试；可选的真实 Web 运行时脚本 |
@@ -222,7 +229,7 @@ npm test        # node --test tests/*.test.mjs
 
 | Job | 声明 | 证据 |
 |---|---|---|
-| `test (22)`、`test (24)`（Ubuntu） | 离线套件、文档一致性、生成文档、发布文件清单、架构、类型与 domain 纯度全部成立 | `npm test`、`npm run docs:check`、四个 `docs:check:generated*`、`pack:check`、`architecture:check`、`types:check`、`domain:check` |
+| `test (22)`、`test (24)`（Ubuntu） | 离线套件、文档一致性、生成文档、发布文件清单、架构、类型与 domain 纯度全部成立 | `npm test`、`npm run docs:check`、五个 `docs:check:generated*`（含生成的类型词汇表）、`pack:check`、`architecture:check`、`types:coverage`、`types:strict:check`、`types:check`、`domain:check` |
 | `test (22, windows)`（`windows-latest`，非必需检查） | 同一套离线套件与离线 gates 在真实 Windows 文件系统上成立；路径大小写、`pwsh` shell、rename/unlink 重试都不是只在 Linux 上被假设 | `npm test` + 与 Ubuntu 相同的离线 gates（不跑 release/coverage） |
 | `test` 的 `Coverage (Node 22)` 步骤 | 覆盖率在 CI 中真实测量（只报告，不设阈值、不加徽章） | `npm run test:coverage` |
 | `test` 的 `Release check`（Node 22）步骤 | tag 是一种声明：版本已越过上一个版本 tag、推送的 tag 是 `v<version>`、CHANGELOG 带有发布内容 | `npm run release:check` |
@@ -236,7 +243,7 @@ live suite 需要下载浏览器并真实启动 host，因此移出 push/PR，
 
 `tests/platform.test.mjs` 用注入的 `platform`/`rename`/`unlink` 在任意 OS 上同时断言 win32 与 POSIX 两条分支；唯一需要真实 Windows 的“rename 覆盖被打开的目标文件”用例在 Linux 上以 `# SKIP` 计入 TAP（`tests 11`、`skipped 1`），而不是静默消失。macOS 不单设 runner：它与 Linux 走同一条 POSIX 分支，这是 #86 的非目标。
 
-`mount` 断言一次性 profile 的**已加载表面**，而不是 `cordis.patch.yml` 的文本：29 个 `tower_*` 工具（27 个 `tools/*.js` 模块 + `tower_mode` / `tower_control`）、3 个内置 skill、`tower-worker` / `tower-reviewer` 两个 preset、`/tower` 命令，以及唯一一个顶层 `tower-bundle` group 行（#66）。它不调用模型、不打开浏览器。在维护者的 Windows 机器上实测：host 冷装（含安装）约 100 秒，host 已缓存约 85 秒；CI 中该步骤上限为 3 分钟（`timeout-minutes: 3`），`mount` job 上限 5 分钟。红叉会打印解析后的 profile 路径、host build、已加载计数与每一条未满足的声明。
+`mount` 断言一次性 profile 的**已加载表面**，而不是 `cordis.patch.yml` 的文本：随包 profile 加载 28 个 `tower_*` 工具（27 个 `tools/*.js` 模块 + `tower_mode` / `tower_control`，减去因 `tower-hmr` 随包关闭而不注册的 `tower_reload`；所有可选能力行全开时为 29 个）、3 个内置 skill、`tower-worker` / `tower-reviewer` 两个 preset、`/tower` 命令、一个顶层 `tower` host group 以及可选的顶层能力行（`tower-hmr` 随包关闭）。它不调用模型、不打开浏览器。在维护者的 Windows 机器上实测：host 冷装（含安装）约 100 秒，host 已缓存约 85 秒；CI 中该步骤上限为 3 分钟（`timeout-minutes: 3`），`mount` job 上限 5 分钟。红叉会打印解析后的 profile 路径、host build、已加载计数与每一条未满足的声明。
 
 host build 只固定在一个地方：`scripts/mount-smoke/host.json`，`COMPATIBILITY.md` 最新一行由单元测试强制与它一致，发布时不再各写一遍。`npm run smoke:fixtures` 用两种种子失败（改名一个工具 id、删除 skills 段）证明 smoke 会以正确原因变红；CI 中它作为非必需的 `mount-fixtures` job 运行，control 与两个种子通过 `--host-dir` 共用一次缓存的 host 安装（本机热跑约 2 分钟）。
 

package/cordis.patch.yml

@@ -1,13 +1,25 @@
-# dsh-tower is an all-or-nothing bundle. The single group row is the only
-# user-visible component: disabling it disables every internal section (host,
-# skills, worker/reviewer presets) together, so no orphan preset or skill can
-# point at missing tower_* tools. See docs/architecture/overview.md.
+# dsh-tower component rows (#121).
+#
+# The first top-level row is the mandatory host group: the Host plugin and its
+# worker-preset dependency. Turning it off equals uninstalling Tower (no tools,
+# no presets, no skills), which is the accepted all-off boundary; every other
+# top-level row is an individually switchable optional capability whose off
+# state leaves the rest of Tower working.
+#
+# Policy: principle 11 in PRINCIPLES.md + docs/adr/0005-component-surface.md.
+# The per-key answer is docs/reference/component-surface.md, generated from
+# scripts/component-surface.json. `npm run docs:check:components` refuses a new
+# switch, a missing locale label, or a moved component count without a written
+# decision. `tower_doctor` and `tower_recover` are part of the host and are never
+# switches (#122); a capability row owns exactly one optional capability, and
+# `tower_status` / `tower_doctor` name any row that is off.
 - insert:
-    - id: tower-bundle
+    # Mandatory host anchor. Not an optional capability: off == uninstall.
+    - id: tower
       name: cordis:group
       group: true
       config:
-        - id: tower
+        - id: tower-host
           name: 'dsh-tower'
           config:
             mode:
@@ -21,8 +33,6 @@
               interruptDefault: true
             spawn:
               staleMs: 15000
-        - id: tower-skills
-          name: 'dsh-tower/skills'
         - id: preset-tower-worker
           name: '@deepseek-ai/dsh-agent-preset'
           config:
@@ -41,23 +51,41 @@
                   sampleOverCapGlobResults: false
               - id: tower-worker-pwsh
                 name: '@deepseek-ai/dsh-tool-pwsh'
-        - id: preset-tower-reviewer
-          name: '@deepseek-ai/dsh-agent-preset'
-          config:
-            id: tower-reviewer
-            name: Tower Reviewer
-            description: Read-only independent reviewer for a completed Tower mission.
-            order: 61
-            plugins:
-              - id: tower-reviewer-policy
-                name: 'dsh-tower/reviewer'
-              - id: tower-reviewer-fs
-                name: '@deepseek-ai/dsh-tool-fs'
-                config:
-                  write: false
-                  edit: false
-                  readImage: false
-              - id: tower-reviewer-fs-search
-                name: '@deepseek-ai/dsh-tool-fs-search'
-                config:
-                  sampleOverCapGlobResults: false
+    # Optional capabilities: each row is the switch for exactly one capability.
+    - id: tower-skills
+      name: 'dsh-tower/skills'
+    - id: tower-batch
+      name: 'dsh-tower/batch'
+    - id: tower-import
+      name: 'dsh-tower/import'
+    - id: tower-leases
+      name: 'dsh-tower/leases'
+    - id: tower-tests
+      name: 'dsh-tower/tests'
+    # dev hot reload: shipped off. Enable the row for a linked dev profile.
+    - id: tower-hmr
+      name: 'dsh-tower/hmr'
+      disabled: true
+    # Conditional optional component: off is supported only while
+    # review.requireReview is false; with the gate on planning/mode entry refuse
+    # the combination with an explanatory error.
+    - id: preset-tower-reviewer
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: tower-reviewer
+        name: Tower Reviewer
+        description: Read-only independent reviewer for a completed Tower mission.
+        order: 61
+        plugins:
+          - id: tower-reviewer-policy
+            name: 'dsh-tower/reviewer'
+          - id: tower-reviewer-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              write: false
+              edit: false
+              readImage: false
+          - id: tower-reviewer-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false

package/docs/README.md

@@ -9,7 +9,7 @@ Choose a path:
 | New user | [When to use Tower](guide/scenarios-and-philosophy.md) → [Quick start](guide/quickstart.md) → [Tools](reference/tools.md) → [Example](examples/first-mission.md) |
 | Choosing a workflow | [When to use Tower, and how it differs from Agent Teams, Ralph, Workflow and parallel subagents](guide/scenarios-and-philosophy.md) |
 | Operator | [Runbook](operations/runbook.md) → [Blockers](reference/blockers.md) → [Error codes](reference/errors.md) → [Events](reference/events.md) → [Doctor](reference/doctor.md) → [Testing](reference/testing.md) → [Batches/leases/legacy](reference/operations.md) → [Security](operations/security.md) → [Incidents and regressions](operations/incident.md) |
-| Maintainer | [Engineering principles](../PRINCIPLES.md) → [ADRs](adr/README.md) → [Architecture](architecture/overview.md) → [Surface budget](reference/surface-budget.md) → [Config](reference/config.md) → [Hot reload](guide/hot-reload.md) → [Release checklist](guide/release.md) → [Tracker board](board.md) → [Contributing](../CONTRIBUTING.md) |
+| Maintainer | [Engineering principles](../PRINCIPLES.md) → [ADRs](adr/README.md) → [Architecture](architecture/overview.md) → [Surface budget](reference/surface-budget.md) → [Component surface](reference/component-surface.md) → [Config](reference/config.md) → [Hot reload](guide/hot-reload.md) → [Release checklist](guide/release.md) → [Tracker board](board.md) → [Contributing](../CONTRIBUTING.md) |
 
 Reference pages are the source of truth for the current release; the [tools reference](reference/tools.md),
 [blocker list](reference/blockers.md) and [error codes](reference/errors.md) are checked against the
@@ -37,6 +37,7 @@ Other useful pages: [When to use Tower](guide/scenarios-and-philosophy.md), [Ins
 - [Batches, leases and legacy import](reference/operations.md)
 - [Doctor](reference/doctor.md)
 - [Surface budget and classification](reference/surface-budget.md)
+- [Component surface: who may be switched off](reference/component-surface.md)
 
 **Operations and background**
 

package/docs/adr/0004-surface-budget.md

@@ -36,6 +36,26 @@ note for each niche key.
 - The numbers are three lines in `tower_doctor` output, not a new dashboard.
 - This does not remove any key in this release; it is a brake, not a clean-up.
 
+## Measurement correction (2026-10-23)
+
+The first baseline counted 27 tools because it recorded only the `define()`
+registration path. `tower_mode` and `tower_control` are registered directly by
+`index.js`, so the shipped surface was always 29 (#118). The baseline now carries
+an explicit correction decision (27 → 29) with a reason, a date and a reference
+to this ADR, and the recorder in `host/tool-registry.js` covers both registration
+paths. This is a measurement correction, not surface growth: a later count change
+still needs its own ADR or a provably matching deletion.
+
+## Amended by ADR 0005 (2026-10-23)
+
+The decision above counts three surfaces. [ADR 0005](0005-component-surface.md)
+extends the budget with a fourth — the number of user-visible component rows in
+`cordis.patch.yml` — and records it as its own `components` baseline entry with a
+two-way decision rule (a contraction needs a decision just like growth). The
+three original counts are still measured by `npm run surface:check`; the
+component count is validated by `npm run docs:check:components`. The historical
+decision above is unchanged: "three surfaces" describes the 2.3.0 rule.
+
 ## Rejected alternatives
 
 - **A line-count or file-size rule** — the project already has those and the

package/docs/adr/0005-component-surface.md

@@ -0,0 +1,130 @@
+# 0005 — The component surface: mandatory host, switchable optional rows
+
+- Date: 2026-10-23
+- Status: Accepted
+- Deciders: maintainer
+- Supersedes: none
+
+## Context
+
+The plugin had no durable statement of what may and may not be a switch. The
+policy that #65 was resolved against lived only in the issue body, so when the
+issue closed the policy evaporated: the 2.0.4 surface (four top-level rows:
+`tower`, `tower-skills`, `preset-tower-worker`, `preset-tower-reviewer`) became
+one all-or-nothing `tower-bundle` group row plus seven `tools.expose*` config
+keys. The user-controllable component count went 4 → 1 while nothing recorded
+that decision or refused the next one.
+
+Two failure modes are already visible in the 2.3.0 tree:
+
+1. Optional capabilities have no component. Skills, the reviewer preset, the
+   batch/import/leases/test tools and hot reload can only be changed by editing
+   YAML under `tools:`, which is the discoverability problem components exist to
+   solve. A config key is still a switch, just a worse-labelled one.
+2. The safety nets are switchable. `tools.exposeOperational:false` removes all
+   seven operational tools including `tower_recover` and `tower_doctor`, so the
+   equipment that diagnoses and repairs a stale `state.lock` can itself be
+   turned off, while the plugin stays mounted. That off state is worse than
+   uninstalling the plugin, because uninstalling would remove the lock problem
+   too.
+
+`PRINCIPLES.md` already says an enforcement pointer that does not resolve is a
+slogan; by that standard the component policy was a slogan.
+
+## Decision
+
+Adopt this shape and record it as principle 11:
+
+- **The host is mandatory.** `tower` (and its worker preset dependency) is never
+  a switch, not as a row and not as a boolean that removes it.
+- **Each optional capability is its own component row**, individually toggleable
+  from the plugin page, with `title`, `summary` and `disables` in both locales and
+  a documented fallback stating what still works while it is off. A capability
+  qualifies only when its off state leaves the rest of Tower intact and is not
+  worse than uninstalling.
+- **The safety nets are never switches.** The health contract, the recovery
+  escape, the review contract and the merge gates are configuration or code; no
+  group, row or boolean key may gate them. Enforcement covers both routes: a
+  `cordis.patch.yml` row that defaults any key classified `forbidden-to-disable`
+  to `false` is refused, and every `tools.expose*` route in
+  `host/tool-registry.js` must match the `gateableTools` allowlist in the source
+  of truth, so a new route to a review, merge or host tool fails even when that
+  capability lists no tools of its own.
+- **Config keys stay on the component axis.** Every config key is classified
+  `core`, `optional-component`, `optional-config` or `forbidden-to-disable` in
+  `docs/reference/component-surface.md`, generated from the single source of
+  truth `scripts/component-surface.json`, so "should this be a component?" is a
+  table lookup rather than a judgement call.
+- **The component count is a baselined surface.** `scripts/surface-baseline.json`
+  gains `components` (seed 4, the 2.0.4 row count; value 1, today's group row) and
+  the 4 → 1 contraction is itself a dated decision. Unlike the other surfaces, the
+  component count is two-way: a contraction needs a decision record just like
+  growth does. `npm run surface:check` and `npm run docs:check:components` refuse a
+  count that moved without one. That is what makes the next contraction — or the
+  coming growth — visible in a diff.
+
+This ADR records the policy. The individual instance fixes follow it: #121 turns
+the qualifying capabilities into optional rows, and #122 deletes
+`tools.exposeDoctor` / `tools.exposeRecovery`, removes the `exposeOperational`
+master switch and the whole `tools` config group. While that migration was in
+flight the two `tools.expose*` keys that gated the health and recovery contracts
+were recorded as dated debt in `scripts/component-surface.json`, so a *new*
+switch failed the gate immediately even before #122 landed.
+
+## Migration (2.4.0): the #65 policy is restored from the carrier
+
+- Date: 2026-10-23
+- Status: implemented by #121 and #122
+
+The one `tower-bundle` group is gone. `cordis.patch.yml` now ships the mandatory
+`tower` host anchor (the Host plugin and the worker preset are its internal
+sections) plus the individually switchable top-level rows `tower-skills`,
+`tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-hmr`
+(shipped off) and `preset-tower-reviewer` (conditional on
+`review.requireReview`). The visible component count moved 1 → 8 and is recorded
+as a dated decision in `scripts/surface-baseline.json`.
+
+The capability switches became rows: the seven `tools.expose*` keys and
+`dev.hotReload` were deleted from the schema and are now rejected as unknown
+keys. `tower_doctor` and `tower_recover` are registered for every configuration
+and have no switch; the `gateableTools` allowlist is empty. This is the
+carrier's promised instance fix, not a new policy: #120 wrote the rule down, and
+this wave makes the shipped surface obey it instead of carrying debt.
+
+## Consequences
+
+- The user can control every capability that legitimately has an off state, from
+  the place components are controlled, instead of editing YAML.
+- The host, the diagnostics and the lock escape are always registered; a failure
+  message may safely point at `tower_recover`.
+- A component count change now needs a written decision, so the 2.3.0 4 → 1
+  contraction can never recur silently; the 1 → 8 restoration is recorded the
+  same way.
+- The 2.3.0 debt is paid: `tools.exposeDoctor`, `tools.exposeRecovery` and the
+  `exposeOperational` master switch are gone, so no configuration can remove the
+  health contract or the lock escape. The `gateableTools` allowlist stays in the
+  source of truth, empty, so the next `tools.expose*` route is refused rather
+  than legalised by default.
+- Adding a component costs a locale row in two languages and a fallback sentence
+  in the source of truth; that is the intended marginal cost.
+
+## Rejected alternatives
+
+- **One all-or-nothing group row (the shipped 2.3.0 shape).** Simple, and it
+  removes the orphan-mount hazard, but it removes every user control as well:
+  the qualifying capabilities become unreachable from the plugin page. It also
+  makes the "off state" question vacuous, because the only off state is
+  "uninstalled".
+- **Config-key switches instead of components.** `tools.expose*` and
+  `dev.hotReload` carry the same capabilities with none of the discoverability,
+  and they make safety nets disableable in a place where no label warns about it.
+  A config key is a switch with worse labelling, not an absence of a switch.
+- **Per-tool components.** 29 rows is a worse surface than 29 tools, and it turns
+  every implementation detail of the tool registry into a user decision.
+- **A denylist-only rule with no component count.** It would catch a forbidden
+  switch but not the 4 → 1 contraction, which is the failure that actually
+  happened; the count baseline is the part that keeps the policy alive across the
+  next refactor.
+- **A GitHub issue label or a docs-only policy.** The brake must run offline in
+  `npm test` and in CI without a token, and the policy must survive the closure
+  of the issue that introduced it.

package/docs/adr/README.md

@@ -15,6 +15,7 @@ alternatives, Date and Status.
 | [0002](0002-single-state-json.md) | One `state.json` is the mission persistence contract | 2026-10-23 |
 | [0003](0003-allow-agent-control-default-true.md) | `allowAgentControl` defaults to `true` | 2026-10-23 |
 | [0004](0004-surface-budget.md) | The concept surface is frozen by a committed baseline | 2026-10-23 |
+| [0005](0005-component-surface.md) | Mandatory host plus individually toggleable optional component rows | 2026-10-23 |
 
 ## Template