dsh-tower 2.1.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,143 @@
 
 ## 未发布（Unreleased）
 
+## 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）
+
+### 新增
+
+- **#87 live harness 可复现**：`tests/live/package.json` 固定 `playwright`（含独立 lockfile），
+  根脚本 `npm run test:live` 解析本地/`NODE_PATH` 并在缺失时打印两条确切安装命令后退出 2（无堆栈）；
+  七个 live 脚本统一走该解析器；`--check` 模式无需浏览器即可在 clean clone 上通过；
+  `tests/README.md` 以可复现路径为默认、全局安装作为 fallback。
+- **#47 live 套件安全门禁 + nightly**：live 入口强制 `DSH_LIVE=1` 且 `DSH_HOME` 必须是 `os.tmpdir()` 的严格子目录，
+  拒绝真实 home 及其 `profiles/*`（错误信息指向 `npm run test:live`）；CI 的浏览器 live job 移出 push/PR，
+  改为 nightly `schedule`/`workflow_dispatch` 且主机版本固定在 `0.2.1-rc.2`；输出首行打印解析后的
+  `DSH_HOME` 与 host 版本。
+- **#83 工程哲学**：根目录 `PRINCIPLES.md`（10 条原则，每条带明确的 refusal 与可解析的 enforcement pointer）、
+  `docs/adr/` 四份带日期的 ADR（ports-as-data、单一 state.json、allowAgentControl 默认、surface budget，
+  均含 rejected alternatives）、`docs/` 非目标审计、PR 模板的 principle 问题；
+  `scripts/check-philosophy.mjs` + `npm run docs:check:philosophy` 在 pointer 失效时失败。
+- **#84 概念预算**：`tower_doctor` 打印 `config keys: 64 · sections: 15 · tools: 27 (baseline 2026-10-23)`；
+  生成的 config/tools 参考头部携带同一计数与日期；`scripts/surface-baseline.json` + `npm run surface:check`
+  在 surface 增长而无 ADR/等量删除时失败（fixture 覆盖）；64 个 config key 的 core/tuning/niche 分类
+  （含 3 条 niche removal note）与 27 个工具的 core/optional 分类。
+- **#85 事故实践**：`docs/operations/incident.md` 六字段模板（Symptom/Introduced in/Blast radius/Root cause/
+  Regression test/Released in），从 CONTRIBUTING 与 SECURITY 链接；`regression` label 语义固定为
+  “worked in a released version, then stopped”；`scripts/regression-audit.mjs` 离线审计已关闭 regression issue
+  的 `Regression test:` 路径；#68 已按模板回填并通过审计。
+
+### 修复
+
+- 发布前 CI flake：lock 心跳测试改为轮询等待一次 tick，避免高负载 Node 24 下固定 60ms 窗口偶发失败。
+## 2.2.0（2026-10-23）
+
+### 新增
+
+- **#74 恢复动作到达模型**：`ERROR_CODES` 统一为 35 条目录（description/trigger/retryable/nextAction）；
+  `renderErrorMessage()` 在消息尾部追加恰好一个 `— next: …` 片段，retryable 条目附加 `(retryable)`；
+  无 nextAction 的条目保持字节不变；`TowerToolError`/`classifyError()` 均从目录解析字段；
+  `errors.generated.md` 与 errors.md 的 Code/Retryable/Next action 表由同一目录生成。
+- **#75 领域事件**：域转换返回 `{ state, events }`；app 持久化后发出稳定事件
+  `tower.mission.planned|completed|reviewed|merged|abandoned`（携带 missionId/revision/at，merged 另有 commit），
+  `tower/<tool>` 作为弃用别名保留一个 minor；`ports/events.js` 新增 `EventPort`（no-op 默认，Cordis `ctx.emit` 绑定）；
+  `docs/reference/events.md` 由事件表生成并纳入 `--check`。
+- **#71 ui-bundle 纳入 fitness gate**：`client-no-node`/`client-size`/`client-ambient` 三条阻塞规则；
+  `client.js` 从 1,980 行拆为 entry + 9 个按渲染面切分的 chunk（每个 ≤400 行，总行数 +9.95%）；
+  `domain:metrics` 打印 ui-bundle 行；`pack:check` 额外要求 ui-bundle/package.json 与 cordis.patch.yml。
+
+### 变更
+
+- **#69 app 依赖 ports 而非 adapters**：9 个运行时 Port 契约 + `assertPorts`；组合根一次性构造 adapter 并注入；
+  `app-ports-only`/`composition-root`/`port-shape` 三条 fitness 规则；内存 adapter 全生命周期测试。
+- **#70 退役 lib/**：23 个文件 `git mv` 到 adapters/host/app；新增 `no-lib-from-core`、`host-scope` 阻塞规则；
+  ambient 豁免降为 2 条 I/O 边界；`lib/` 不再存在。
+- **#80 fitness 豁免有据**：硬编码 allow-list 改为 `scripts/architecture-waivers.json` 中带 reason/owner/ref 的豁免；
+  新增阻塞 `waiver-contract`，无理由豁免/未知规则/ambient 无 match/domain 豁免一律失败；statement-aware ambient 扫描。
+
+### 修复
+
+- **发布前 hygiene（F2–F5）**：根级 `*.log` 忽略规则；控制流 `)` 后正则的 scanner 加固；
+  `tsconfig` 移除已删除 lib 路径；COMPATIBILITY/ui-bundle 文档中的旧 lib 路径更新。
+## 2.1.2（2026-10-23）
+
+### 修复
+
+- **#107 survey 依赖满足门禁**：`dependencySatisfied()` 让 `merged`/`abandoned` 继续满足任意类型依赖，
+  并额外接受 `kind === 'survey' && status === 'completed'`（survey 的终态成功，没有可合并分支）；
+  `dependencyBlockers()` 对活跃 state 与归档索引一视同仁，因此归档的已完成 survey 也满足依赖。
+  build→build 仍要求 `merged`，不为 survey 发明新状态。
+- **#108 多路 review 同 tip 记录**：`reviewAdmission()` 允许 `active` mission 的后续 route 在同一
+  reviewed tip 上追加 verdict，并入同一 round（`appended:true`），不再次翻转状态；tip 已移动时以
+  明确说明拒绝。`app/review.js` 与输出 schema 同步。
+
+### 变更
+
+- **Tower 交付流程**：2.1.2 的 #107/#108 由 Tower mission M2 实施（worker → reviewer clean R2 →
+  preflight → merge）；review 后按文档化路径扩了 mission scope 以覆盖根文档，`tower_review` 契约
+  描述更新为「completed 起新 round / active 可追加同 tip route」。
+## 2.1.1（2026-10-23）
+
+### 修复
+
+- **#92 PID 复用导致 state 锁永久不可恢复**：持有 state/git 锁期间，记录中的 `at` 现在按固定间隔
+  心跳重写（默认 1000 ms，`unref` 定时器，释放时清除且任何写失败都不会抛给调用方）。回收条件
+  从"PID 已死"改为"`ESRCH` 立即回收，或心跳静默超过 3 × 间隔（默认 3 s）且改名后字节校验通过"，
+  因此即使 PID 被无关进程复用也能安全回收，且仍在默认 5 s 的 state 锁等待预算内。修复前
+  `tower_recover clear-stale-lock` 会拒绝 PID 仍存活的锁；新增 `force: true`（仍需
+  `confirm:"CLEAR_STALE_LOCK"`）可清理"PID 存活但心跳静默"的锁，输出
+  `{pid, startedAt, ageMs, heartbeatAgeMs}` 并始终改名为 `.recovered-<ts>` 备份、绝不 unlink。
+  自动回收一个"PID 存活但心跳过期"的记录时保留 `state.lock.reclaimed-<ts>-<id>` 审计备份；
+  `ESRCH` 快速路径行为不变。`tower_doctor` 新增 `stateLock` 报告（`ageMs`、`heartbeatAgeMs`、
+  `staleAfterMs`、`stale`），锁记录新增 `since`（记录写入时间；旧记录回退到 `at`）。
+  改名 → 校验字节 → 再处置的顺序保持不变，回收中途被替换的记录会被还原而不会丢失。
+
+- **#93 git mutex 等待按合并超时预算**：持有 git 锁的一方记录 `{kind:'git', phase}`，并让
+  `tower_init`/`tower_teardown`/`tower_rebase`/`tower_spawn` 按 `merge.timeoutMs`
+  （默认 900000）+ 60 s 边距等待，慢 pre-merge hook 不再让并发操作在 60 s 失败。超时错误携带
+  `{holderPid, holderPhase, heldMs, waitedMs}`（消息形如 `held by pid 1234 (merge) for 92 s;
+  waited 60 s`），`tower_status`/`tower_doctor` 新增 `gitLock {held,pid,phase,heldMs}` 与
+  `git-lock` 检查；state 锁的 5 s 预算与 merge 超时默认值保持不变。
+
+### 变更
+
+- **#106 执行规范**：新增 `docs/agents/workflow.md`，把 Matt Pocock 技能流程（triage → spec →
+  tickets → TDD → 两轴 code-review → retro）与 Tower 交付协议（worktree mission、scope 围栏、
+  review/merge 门禁）合并为仓库唯一执行规范，`AGENTS.md` 指向它；明确 tag-only 与 published
+  两种发布模式以及人工门禁（npm publish/2FA、保护分支变更）。
 ## 2.1.0（2026-10-23）
 
 ### 新增

package/COMPATIBILITY.md

@@ -5,6 +5,11 @@ 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.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 |
+| 0.2.1-rc.2 | v2.1.1 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (490), `npm run docs:check`, generated docs checks |
 | 0.2.1-rc.2 | v2.1.0 | 2026-10-23 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (479), `npm run docs:check`, generated docs checks |
 | 0.2.1-rc.2 | v2.1.0-beta.1 | 2026-10-22 | mount smoke (29 tower tools, `/tower`, 3 skills, 2 presets, single bundle row), `npm test` (413), `npm run docs:check`, generated docs checks |
 | 0.2.1-rc.2 | 6ee19de | 2026-10-21 | `npm test` (229), `npm run docs:check`, offline `ui-bundle` tests |
@@ -25,7 +30,7 @@ Tower work. This is provenance, not a feature-detection mechanism.
 
 Add a row in the release PR, before tagging, after running the offline suite and docs check on the
 host build being shipped. Name the release tag in cell 1 and the host build in cell 0; the other
-columns are read positionally by `lib/compatibility.js`, so do not insert or reorder them. Do not
+columns are read positionally by `host/compatibility.js`, so do not insert or reorder them. Do not
 claim a live run that was not performed. The 2.1.0-beta.1 row is a pre-release: it becomes
 installable on the `next` dist-tag only after the checklist's publish step, and `latest` stays on
 2.0.4 until a stable release. The full six-step procedure is the

package/CONTRIBUTING.md

@@ -2,6 +2,35 @@
 
 Thanks for your interest in `dsh-tower`. This is a DeepSeek Harness plugin; the repository root is the bundle itself (`package.json` + `cordis.patch.yml`).
 
+## Engineering philosophy and decisions
+
+Two short documents say what this project refuses to do:
+
+- [PRINCIPLES.md](PRINCIPLES.md) — the numbered refusals. Each one names what it
+  refuses and the file plus test or gate that enforces it. A principle whose
+  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, 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
+existing refusal covers the change, say why a new principle is needed. The
+concept budget and its classification table are in
+[docs/reference/surface-budget.md](docs/reference/surface-budget.md): a config key
+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,
@@ -18,7 +47,9 @@ The context names come from the workflow job id and matrix values. Renaming a jo
 changes the required context; update the protection setting in the same PR, or the check never reports
 and every PR stays unmergeable. The setting and its verification command are in
 [SECURITY.md](SECURITY.md#repository-protection-on-main). The `mount-fixtures` job runs the seeded
-smoke failures for evidence but is deliberately **not** a required context.
+smoke failures for evidence but is deliberately **not** a required context. The `live` job is nightly
+(and manual-dispatch) only, runs on a pinned host matrix, and is evidence as well: it is never part of
+a push or a PR gate.
 
 The offline `test` matrix also has a `test (22, windows)` leg on `windows-latest` (Node 22). It runs the
 offline suite and the offline gates, not the release/coverage steps, so the platform branches are
@@ -39,8 +70,8 @@ four-line body, in this order:
 
 - `domain/**`
 - `app/**`
-- `lib/store.js`, `lib/persistence.js`, `lib/*lock*.js`
-- `scripts/architecture.mjs`
+- `adapters/store.js`, `adapters/persistence.js`, `adapters/*lock*.js`
+- `scripts/architecture.mjs`, `scripts/architecture-waivers.json`
 - `cordis.patch.yml`
 
 ```markdown
@@ -72,22 +103,41 @@ npm test        # no dependencies to install; Node's built-in test runner only
 
 Requirements: Node.js 22+, Git. No package installation is needed for the offline suite.
 
+The opt-in live suite is the exception: install it once with
+`npm ci --prefix tests/live && npx --prefix tests/live playwright install chromium`, then run it with `npm run test:live`
+against a disposable `DSH_HOME` under the OS temp directory and a booted isolated profile. The guard
+refuses the operator's real `DSH_HOME` and any profile under `DSH_HOME/profiles`. `npm run test:live --
+--check` validates the environment and Playwright resolution without a browser. See
+[tests/README.md](tests/README.md#2-real-web-runtime-isolated-profile). The live suite is not part of
+the push gates; CI schedules it nightly.
+
 ## What to change
 
 - `index.js` — Host entry: `/tower` command, mode guard, dynamic prompt section, `tower_control`.
-- `lib/` — the Tower domain (`tower.js`), tool definitions (`tools.js`), persistence (`store.js`, `modeStore.js`), Git helpers (`git.js`).
+- `host/` — the composition root and session/process glue (`tool-registry.js`, `config.js`, `hmr.js`, `modeStore.js`, `doctor.js`); `adapters/` — the only I/O implementations (store, git, archive, leases, locks); `app/` — use cases; `domain/` — the pure core.
 - `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 (479 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 (612 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.
 5. Update `README.md` / `README.en.md` when the user-visible behavior changes.
 6. If you touched `cordis.patch.yml`, `index.js`, `skills.js`, or `tools/`, run `npm run smoke:mount` (see below).
 7. A commit carries `Refs #n` or `Fixes #n`; a P0/P1 closure carries `verified-by:` and `commit:`, and `npm run audit:issues` reports no new failures.
+8. A regression closure carries the six-field record from
+   [docs/operations/incident.md](docs/operations/incident.md) and `npm run audit:regressions`
+   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. 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`.
 
 ## Mount smoke
 
@@ -182,6 +232,29 @@ Exit codes: `0` — every checked closure names an existing test file (a missing
 export is missing or malformed. `--strict` promotes the missing-`commit:` warning to an error.
 `tracker/` is a local snapshot and is gitignored; regenerate it instead of committing it.
 
+## Regressions and incidents
+
+The `regression` label means **"worked in a released version, then stopped"**. It is
+narrower than `bug` and mutually exclusive with it for a shipped break: a user
+could rely on the old behavior, so the record must say which release broke it and
+which test prevents it from happening again.
+
+A closed `regression` issue carries the six-field record from
+[docs/operations/incident.md](docs/operations/incident.md) (symptom, introduced in,
+blast radius, root cause and fix, regression test, released in). The one checkable
+line is `Regression test:`, which must name a test file that exists. The same
+`tracker/issues.json` export from above is audited offline:
+
+```powershell
+npm run audit:regressions
+npm run audit:regressions -- --tracker path/to/export.json --json
+```
+
+Exit codes: `0` — every closed regression names an existing test; `1` — a line is
+missing or the path is nonexistent/non-test; `2` — the export is missing or
+malformed. The fixture in `tests/regression-audit.test.mjs` seeds a missing path
+and a valid one, so the rule cannot quietly become prose.
+
 ## Commit style
 
 Conventional-commit prefixes are preferred: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`. Keep the subject line in the imperative mood. Add the issue trailer (`Refs #n` / `Fixes #n`) described above.

package/PRINCIPLES.md

@@ -0,0 +1,163 @@
+# Engineering principles
+
+These are the refusals this project makes. A principle with no refusal and no
+enforcement pointer is a slogan, so every entry below names what it refuses and
+the file plus test or gate that makes the refusal real. `npm run
+docs:check:philosophy` fails when a pointer no longer resolves.
+
+The product philosophy — when to use Tower, and when not to — is a separate
+document: [docs/guide/scenarios-and-philosophy.md](docs/guide/scenarios-and-philosophy.md).
+Decisions already made are recorded in [docs/adr/README.md](docs/adr/README.md).
+
+## 1. Evidence before done
+
+We do not accept "done" as an assertion. A change is done when a named test,
+command, or receipt can be re-run by someone else, and the closure names that
+pointer instead of describing the work.
+
+Refused because of this: one-line closures, "implemented on main, trust me",
+and completion reports that list prose without an exit code.
+
+Enforced by: `scripts/issue-audit.mjs` and `scripts/regression-audit.mjs`, with
+the fixtures in `tests/issue-audit.test.mjs` and `tests/regression-audit.test.mjs`;
+gate: `npm run audit:issues`.
+
+## 2. Gates before prose
+
+We do not add a rule to a document that a machine could enforce. If a sentence
+says "always" or "never", the same change must either point at an existing check
+or admit that the sentence is `unowned`.
+
+Refused because of this: warnings-only lint rules, "please remember to bump the
+version", and instructions that only a careful reader can follow.
+
+Enforced by: `scripts/architecture.mjs` and `scripts/check-docs.mjs`; tests in
+`tests/architecture.test.mjs`; gate: `npm run architecture:check`.
+
+## 3. Ports are data, not a DI container
+
+We do not add a service locator, decorators, or a reflection-driven container.
+The adapter seam is a table of frozen runtime contracts that a test asserts, so a
+reader can see every effectful call without booting the app.
+
+Refused because of this: `reflect-metadata`, string-keyed service lookup, and
+"the container will wire it" as an explanation for a dependency.
+
+Enforced by: `ports/index.js` and `scripts/architecture.mjs`; contract tests in
+`tests/memory-adapters.contract.test.mjs`; ADR:
+`docs/adr/0001-ports-adapters-as-data.md`.
+
+## 4. One state file, one writer
+
+We do not split mission state across per-mission files for diffability. One
+`state.json` with one lock and one atomic write is the persistence contract;
+archived missions move to year files only after they are terminal.
+
+Refused because of this: per-mission JSON files, append-only forks of the state
+tree, and any write that does not go through the lock.
+
+Enforced by: `adapters/store.js` and `adapters/persistence.js`; tests in
+`tests/persistence-contract.test.mjs`; ADR: `docs/adr/0002-single-state-json.md`.
+
+## 5. The human owns the mode
+
+The model may toggle Tower mode, but it may not acquire ownership of it, resume a
+user-paused goal, or merge without the gate. The default that lets the model
+enter is paired with lock, ack, and resume-authorization checks rather than with
+trust.
+
+Refused because of this: an autonomous "always on" mode, auto-resuming a paused
+goal, and a model-initiated merge that skips preflight.
+
+Enforced by: `index.js` and `host/modeState.js`; tests in `tests/plugin.test.mjs`;
+ADR: `docs/adr/0003-allow-agent-control-default-true.md`.
+
+## 6. The surface is a budget
+
+We do not treat "highly configurable" as a feature. Every config key and tool is
+a promise, so the counts are committed in `scripts/surface-baseline.json` and a
+count may grow only with an ADR or a provably matching deletion.
+
+Refused because of this: a new config key added because it was easy, and a tool
+added without deciding which tool it replaces.
+
+Enforced by: `scripts/surface-baseline.mjs` and
+`docs/reference/surface-budget.md`; tests in `tests/surface.test.mjs`; gate:
+`npm run surface:check`.
+
+## 7. Read-only means no writes
+
+A tool that says read-only may not create a temp file, migrate state, or probe the
+filesystem. Diagnostics either report the absence or return a warning; they never
+make the repository healthier as a side effect.
+
+Refused because of this: doctor probes, lazy migrations during inspection, and
+"read-only" tools that repair things on first call.
+
+Enforced by: `host/doctor.js` and `adapters/store.js`; tests in
+`tests/lock-heartbeat.test.mjs` and `tests/state-migration.test.mjs`; gate:
+`npm test`.
+
+## 8. Offline tests are the contract
+
+`npm test` does not need a network, a browser, credentials, or a live host. A
+proof that can only run on one machine is evidence for that machine, not a gate.
+
+Refused because of this: a test that calls GitHub, a required model run in the
+offline suite, and a live-only check that blocks a merge.
+
+Enforced by: `tests/live-harness.test.mjs` and `scripts/mount-smoke/fixtures.mjs`;
+gate: `npm run smoke:fixtures`.
+
+## 9. Generated references are generated
+
+We do not hand-maintain a list that the source already knows. Docs under
+`docs/reference/*.generated.md` are written by a generator, their count line
+comes from `scripts/surface-baseline.json`, and a mismatch is a failed check
+rather than a review comment.
+
+Refused because of this: hand-editing a generated table, and two references that
+disagree about the same count.
+
+Enforced by: `scripts/generate-config-reference.mjs` and
+`scripts/generate-tools-reference.mjs`; tests in `tests/surface.test.mjs`; gate:
+`npm run docs:check:generated:config`.
+
+## 10. A regression keeps its test
+
+We do not close a shipped regression with a sentence. A `regression` is anything
+that worked in a released version and then stopped, and its closure carries the
+six-field incident record plus a test path that exists.
+
+Refused because of this: "fixed in the next release", a regression closed
+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
+review board, and no required approval. The list stays useful only while its
+pointers resolve, which is exactly what `scripts/check-philosophy.mjs` checks.
+
+Enforced by: `scripts/check-philosophy.mjs`; tests in
+`tests/philosophy.test.mjs`; gate: `npm run docs:check:philosophy`.

package/README.en.md

@@ -16,7 +16,7 @@ The repository root **is** the DSH bundle: `package.json` declares `dsh.bundle.p
 
 - **Configurable Tower mode.** `/tower` toggles a session-level stance that narrows the tool surface and injects the Tower protocol. `/tower on|off <instruction>` also forwards your instruction to the model in the same step. By default the model may also enter/leave with `tower_control` and a concrete reason; set `mode.allowAgentControl:false` for human-only control.
 - **Missions with real isolation.** Every mission gets its own branch and Git worktree; workers never touch your checkout.
-- **Review-gated merges.** When `review.requireReview:true`, a reviewer bound to the current branch tip must submit a `clean` / `merge` verdict before merge; the merge gate re-checks scope, staleness, task completion, review history, and worktree ownership before a `--no-ff` merge. Independent review is optional by default (the gate is off); use `reviewPolicy:"none"` + reason plus `gates.allowReviewExemption:true` for a single mission when the global gate is on.
+- **Review-gated merges.** When `review.requireReview:true`, a reviewer bound to the current branch tip must submit a `clean` / `merge` verdict before merge; the merge gate re-checks scope, staleness, task completion, review history, and worktree ownership before a `--no-ff` merge. Independent review is optional by default (the gate is off); use `reviewPolicy:"none"` + reason plus `gates.allowReviewExemption:true` for a single mission when the global gate is on. Multi-route review is recorded per round: while a non-clean round keeps the mission `active`, a later reviewer may still submit its verdict for the same reviewed tip and it appends to that round. A completed `survey` dependency satisfies the dependency gate (a build dependency still must be merged).
 - **Durable coordination.** Roster, inbox, findings, reviews, and mission state are persisted under `.git/dsh-tower/`, so a restart does not lose the plan.
 - **Bounded state growth.** Terminal missions whose worktree is gone move to `.git/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, keeping their tasks, reviews, findings and completion report; mutations then rewrite only active work. `tower_status includeArchived` lists compact archived summaries, and `tower_doctor` reports archive size, count and policy.
 - **Safe by default.** While Tower mode is active, `create_goal`, `update_goal(resume)`, `todo_write`, the Team task board, and `spawn_teammate` are refused; a paused goal is never resumed automatically.
@@ -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,8 +214,8 @@ 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) |
-| `index.js`, `lib/`, `worker.js`, `reviewer.js` | Host entry, protocol/config implementation, worker and reviewer preset policies |
+| `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 |
 | `locale/`, `icon.svg` | localization and icon |
@@ -217,7 +230,7 @@ npm test        # node --test tests/*.test.mjs
 ```
 
 Hot-reload development: `npm run dev:hmr` adds this checkout to the current profile's HMR watch roots
-(one DSH restart); afterwards `/tower reload` or the automatic watcher applies `lib/` edits. See
+(one DSH restart); afterwards `/tower reload` or the automatic watcher applies `host/`, `adapters/`, `app/` and `domain/` edits. See
 [docs/guide/hot-reload.md](docs/guide/hot-reload.md).
 
 The offline suite needs no DSH process and creates throwaway Git repositories in the OS temp directory. `tests/README.md` documents the isolated Web-runtime checks, model-driven acceptance, and the session-diagnostic scripts used while hardening the plugin.
@@ -228,18 +241,21 @@ 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 three `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` |
 | `mount` (Node 22) | the packed tarball, added through the plugin CLI to a throwaway profile, mounts in the real loader and registers the surface the bundle claims | `npm run smoke:mount` |
 | `mount-fixtures` (Node 22, not required) | the mount smoke still goes red for the right seeded reasons (a renamed tool id, a removed skills section), with one cached host install shared by all runs | `npm run smoke:fixtures -- --host-dir <cached host>` |
+| `live (<pinned host build>)` (nightly/manual, not required) | the browser live suite still drives a real Web runtime on the pinned host-version matrix; push/PR runs only the browserless environment and resolution check | nightly runs `npm run test:live -- --script nightly`; push runs `npm run test:live -- --check` |
 
 The `test` matrix pins each leg's context string through `matrix.name`: `test (22)`, `test (24)` and the new `test (22, windows)`. The first two are `main`'s required checks and keep their exact names; adding an `os` matrix key without an explicit name would rename them to `test (22, ubuntu-latest)`, and protected `main` would wait for a context that never reports. The Windows leg is Node 22 only and runs the offline suite and offline gates (no browser, no live suite, no release/coverage), in parallel with the existing jobs, so it does not extend the critical path. It is not a required context yet: making it green is the acceptance for #86, while adding it to the protection setting is a human step in #94.
 
+The live suite downloads a browser and boots a real host, so it is out of push/PR: it runs on a nightly `schedule` (also `workflow_dispatch`) on a pinned host-version matrix, and its first output line prints the resolved `DSH_HOME` and host version. Push keeps only `--check` (environment + Playwright resolution, no browser). Playwright is pinned by `tests/live/package-lock.json`; the root `npm ci` downloads no browsers.
+
 `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).