dsh-tower 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,109 @@
 
 ## 未发布（Unreleased）
 
+## 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,10 @@ 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.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 +29,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,25 @@
 
 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).
+
+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`.
+
 ## Landing changes
 
 `main` is protected. Every change lands through a pull request; direct pushes to `main` are rejected,
@@ -18,7 +37,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 +60,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 +93,37 @@ 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.
 
 ## 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 (573 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.
 
 ## Mount smoke
 
@@ -182,6 +218,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,145 @@
+# 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`.
+
+## 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.
@@ -202,7 +202,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) |
-| `index.js`, `lib/`, `worker.js`, `reviewer.js` | Host entry, protocol/config implementation, worker and reviewer preset policies |
+| `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 +217,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,15 +228,18 @@ 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 four `docs:check:generated*` checks, `pack:check`, `architecture: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.

package/README.md

@@ -175,7 +175,7 @@ review/merge 阶段死锁。
 ## 安全与约束
 
 - **门禁不全绿不合并。** `tower_preflight` 是只读检查，返回稳定的 blocker code；存在 blocker 时 `tower_merge` 拒绝合并。
-- **审查绑定提交。** 开启 `review.requireReview` 时，审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。
+- **审查绑定提交。** 开启 `review.requireReview` 时，审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。非 clean 的一轮审查会让 mission 回到 active，此后其他 route 仍可为同一 reviewed tip 提交结论并追加到同一轮；依赖为 `completed` 的 survey 视为已满足（build 依赖仍需 merged）。
 - **scope 强制。** mission 只能修改其 scope glob 匹配的文件，越界会以 `out-of-scope` 阻止合并。
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
@@ -200,7 +200,7 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 | 路径 | 内容 |
 |---|---|
 | `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（单个 `tower-bundle` group，内含 Host、skills 与两个 preset） |
-| `index.js`、`lib/`、`worker.js` | Host 入口、协议实现、worker preset 策略 |
+| `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 运行时脚本 |
 | `ui-bundle/` | 可选 Client 小挂件（Tower 工具卡片、Tower·on 状态 chip、模式感知的 disabled 行、dock 摘要、临时 overlay 状态条），默认不安装 |
@@ -212,7 +212,7 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 npm test        # node --test tests/*.test.mjs
 ```
 
-热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `lib/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
+热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `host/`、`adapters/`、`app/`、`domain/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
 
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
@@ -222,15 +222,18 @@ 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: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` |
 | `mount`（Node 22） | 打出的 tarball 经 plugin CLI 装进一次性 profile 后，真实 loader 挂载并注册了 bundle 声称的表面 | `npm run smoke:mount` |
 | `mount-fixtures`（Node 22，非必需检查） | mount smoke 仍会因正确的种子失败而变红（改名一个工具 id、删除 skills 段），三次运行共用一次缓存的 host 安装 | `npm run smoke:fixtures -- --host-dir <缓存的 host>` |
+| `live (<固定 host 版本>)`（nightly/手动，非必需检查） | 浏览器 live suite 在固定 host 版本矩阵上仍能驱动真实 Web 运行时；push/PR 只做无浏览器的环境与解析检查 | nightly 跑 `npm run test:live -- --script nightly`；push 跑 `npm run test:live -- --check` |
 
 `test` 的三条 leg 在 job 内用 `matrix.name` 固定各自的 context 字符串：`test (22)`、`test (24)` 与新增的 `test (22, windows)`。前两条是 `main` 的必需检查，名字逐字节不变；把 `os` 直接塞进 matrix 会把它们改名成 `test (22, ubuntu-latest)`，保护规则将永远等不到该 context，所以矩阵用显式 `include` + `name`。Windows leg 只跑 Node 22 和离线套件/离线 gates（无浏览器、无 live suite、无 release/coverage），与现有 job 并行，不延长关键路径。它目前不是必需 context：让它变绿是本 issue 的验收，把它加入保护设置是 #94 的人工步骤。
 
+live suite 需要下载浏览器并真实启动 host，因此移出 push/PR，改为 nightly `schedule`（另支持 `workflow_dispatch`），在固定 host 版本矩阵上运行；它的输出第一行打印解析后的 `DSH_HOME` 与 host 版本。push 上只保留 `--check`（环境 + Playwright 解析，无浏览器）。Playwright 由 `tests/live/package-lock.json` 固定，root 的 `npm ci` 不下载浏览器。
+
 `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、已加载计数与每一条未满足的声明。

package/SECURITY.md

@@ -42,6 +42,12 @@ gh api repos/louifinn/dsh-tower/branches/main/protection \
 
 Please do **not** publish exploit details in a public issue. Open a minimal issue titled `security: request private contact` describing only the impact category (for example “merge gate bypass”), and a maintainer will arrange a private channel. Include the affected version and, if possible, a minimal reproduction in the private follow-up.
 
+A security fix that shipped and then stopped working is a regression, not an
+ordinary bug. Use the six-field record in
+[docs/operations/incident.md](docs/operations/incident.md) (including the
+`Regression test:` path) once the private report is resolved; the public closure
+still carries no exploit detail.
+
 ## Supported versions
 
 Security fixes target the latest released `2.x` line (currently `2.0.4`). Older pre-release snapshots

package/{lib → adapters}/archive.js

@@ -12,7 +12,7 @@
 // mission id, so a crash between the two files is recoverable on the next
 // mutation instead of losing a mission.
 import path from 'node:path'
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import {
   ARCHIVE_VERSION,
   archiveDocumentError,

package/{lib → adapters}/caseSensitivity.js

@@ -13,7 +13,7 @@
 //          stat failure). "Unknown" is deliberately not "case-sensitive": init
 //          keeps working and `tower_doctor` reports the safe default.
 import path from 'node:path'
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 
 /** Prefix is public so tests and support code can recognise a leaked probe. */
 export const CASE_PROBE_PREFIX = '.tower-case-probe-'

package/adapters/default.js

@@ -1,12 +1,53 @@
-// Default composition root for Tower dependencies (#50).
-import * as store from '../lib/store.js'
-import * as vcs from '../lib/git.js'
-import * as caseSensitivity from '../lib/caseSensitivity.js'
+// Default composition root for the Tower ports (#50, #69).
+//
+// This module is the one place where the concrete adapters (node:fs,
+// node:child_process) are turned into the plain deps object the app layer
+// takes. `createDefaultDeps()` is called once by the host entry (index.js); the
+// app never imports an adapter. Tests and embedders use the memoised
+// `defaultDeps` (or host/tower.js) so the process has exactly one adapter set.
+import crypto from 'node:crypto'
+import * as archive from './archive.js'
+import * as caseSensitivity from './caseSensitivity.js'
+import * as config from '../host/config.js'
+import { loadStateFile } from './stateFile.js'
+import * as ownership from './worktreeOwnership.js'
+import { createStorePort } from './store-fs.js'
+import { createVcsPort } from './vcs-git.js'
+import { NOOP_EVENT_PORT } from '../ports/events.js'
 
-export const defaultDeps = {
-  store,
-  vcs,
-  caseSensitivity,
-  clock: { now: () => Date.now() },
-  ids: { uuid: () => crypto.randomUUID() },
+/**
+ * Assemble a dependency object implementing every port in ports/.
+ * @param {Partial<Record<'store'|'vcs'|'config'|'state'|'archive'|'ownership'|'caseSensitivity'|'clock'|'ids'|'events', any>>} [overrides]
+ * @returns {Record<string, any>}
+ */
+export function createDefaultDeps(overrides = {}) {
+  const store = createStorePort()
+  return {
+    store,
+    vcs: createVcsPort(),
+    config: {
+      runtimeConfig: config.runtimeConfig,
+      resolveRepoConfig: config.resolveRepoConfig,
+    },
+    state: { loadStateFile },
+    archive: {
+      readIndex: archive.readArchiveIndex,
+      readEntry: archive.readArchivedEntry,
+      writeEntries: archive.writeArchiveEntries,
+    },
+    ownership: {
+      assertOwnership: ownership.assertOwnership,
+      canonicalPath: ownership.canonicalPath,
+    },
+    caseSensitivity: { detect: caseSensitivity.detectCaseSensitivity },
+    clock: { now: () => Date.now() },
+    ids: { uuid: () => crypto.randomUUID(), shortHash: store.shortHash },
+    // The host entry replaces this with the Cordis emitter; default deps (and
+    // tests/embedders) keep the no-op channel so events never fail a tool.
+    events: NOOP_EVENT_PORT,
+    ...overrides,
+  }
 }
+
+/** The single process-wide default adapter set. */
+export const defaultDeps = createDefaultDeps()

package/{lib → adapters}/git.js

@@ -1,6 +1,6 @@
 import { TowerToolError } from '../domain/errors.js'
 // Minimal git port: array arguments only, bounded output, no shell.
-import { execFile } from '../adapters/vcs-git.js'
+import { execFile } from './vcs-git.js'
 import path from 'node:path'
 
 const GIT_TIMEOUT_MS = 15000

package/{lib → adapters}/leases.js

@@ -11,7 +11,7 @@
 // Fail-closed protocol: a held, expired, or token-mismatched lease is reported,
 // never silently taken over. Only the token holder may release a lease, and
 // releasing an expired lease requires an explicit `force: true`.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 

package/{lib → adapters}/legacy.js

@@ -9,7 +9,7 @@
 //
 // `validateLegacyMap` is the audit-only mapping check: a map is a record that
 // legacy id X corresponds to DSH mission Y. It never adopts or restores work.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'