dsh-tower 2.1.0 → 2.4.0

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

@@ -0,0 +1,52 @@
+# Architecture decision records
+
+An ADR is a dated record of a decision that is already load-bearing. It is not a
+proposal: the status says whether the decision is accepted, and the rejected
+alternatives exist so a future reader can see what was actually weighed.
+
+The engineering principles that these records serve are in
+[../PRINCIPLES.md](../PRINCIPLES.md). `npm run docs:check:philosophy` requires at
+least three numbered ADRs, each with Context, Decision, Consequences, Rejected
+alternatives, Date and Status.
+
+| ADR | Decision | Date |
+|---|---|---|
+| [0001](0001-ports-adapters-as-data.md) | Ports and adapters are data, not a dependency-injection container | 2026-10-23 |
+| [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
+
+```markdown
+# NNNN — Decision title
+
+- Date: YYYY-MM-DD
+- Status: Proposed | Accepted | Superseded by NNNN
+- Deciders: <who>
+
+## Context
+
+What forced the decision.
+
+## Decision
+
+What was decided, in one paragraph.
+
+## Consequences
+
+What becomes easier, what becomes harder, and what is now refused.
+
+## Rejected alternatives
+
+- **Alternative** — why it was not chosen.
+```
+
+## Non-goals
+
+These records do not form an RFC queue, an architecture review board, or a
+process for approving ordinary changes.
+
+Unowned. This is a documentation convention, not a gate; nothing in CI blocks a
+new ADR or rewards one.

package/docs/agents/workflow.md

@@ -0,0 +1,51 @@
+# Execution workflow: Matt Pocock skills × Tower
+
+This repository uses two workflows together. They are not alternatives: the **Matt Pocock skills** own thinking, planning, review discipline and retros; **Tower** owns delivery — isolated worktrees, scope fences, review gates, merges and durable mission state. **GitHub Issues** is the single source of truth for what is planned, in progress, blocked and shipped.
+
+## Who owns what
+
+| Stage | Owner | Artifact |
+|---|---|---|
+| Intake | Matt Pocock `/triage` for raw external reports; milestones + `P*`/`area/*` labels for self-authored findings | issue with owner-facing state |
+| Plan | `/to-spec` → `/to-tickets` (or an existing issue whose acceptance criteria are already ticket-shaped) | spec issue, tickets with native `blocked_by` edges |
+| Execute | `/implement-spec` subagents for one-session waves; **Tower missions** for parallel or long-lived work | integration branch + PRs, or mission worktrees + merge gate |
+| Build each unit | `/tdd` inside the ticket/mission | failing test first, then green |
+| Verify | gates + required CI checks + `/code-review` (Standards + Spec) | green PR with two-axis review |
+| Land | protected `main`, four-line PR body, `verified-by:`/`commit:` closure | merged PR, closed issues |
+| Release | `release:check`, CHANGELOG, COMPATIBILITY, tag; publish only when planned | tag-only or published release |
+| Learn | `/retro`; mechanical findings become checks, judgement becomes standards | CONTRIBUTING/AGENTS/scanner updates |
+
+## The flow
+
+1. **Intake.** Raw external bug reports and feature requests go through `/triage` (they are not ours). Findings we file ourselves (audits, retros) skip triage and get a priority, an area and a milestone; they are already acceptance-criteria-shaped.
+2. **Plan.** Multi-session work goes `/to-spec` → `/to-tickets`. Tickets are tracer bullets with native blocking edges; the frontier is whatever has no open blockers. Small work may skip the spec when the issue already states acceptance criteria (e.g. a patch ticket).
+3. **Choose the orchestrator.**
+   - **One-session wave (≤3 tickets, mostly independent):** `/implement-spec`-style: an integration branch, one implementer subagent per ticket in its own worktree, merger merges to the integration branch, one PR to `main`.
+   - **Parallel or long-lived wave (architecture epics, >3 tickets, review needed):** **Tower**. `tower_init` → `tower_plan` with one mission per ticket, `scope` = the ticket's write fence, `deps` = the ticket's blocking edges → `tower_spawn` a worker per mission → optional reviewer (`tower-reviewer`) → `tower_merge` (gate checks scope, branch freshness, review, tasks) → `tower_teardown`. Tower's persistent state makes the wave resumable after a restart.
+   - Never run both orchestrators over the same files at once.
+4. **Build.** Each unit starts with `/tdd`: one failing test, then the implementation, then the next slice. Commit messages carry `Refs #n`; the completing commit uses `Fixes #n`. Workers do not merge; they hand off a branch.
+5. **Verify before landing.** Run `npm test`, `npm run docs:check`, all five `docs:check:generated*` (including the generated type vocabulary), `npm run pack:check`, `npm run architecture:check`, `npm run types:coverage`, `npm run types:strict:check`, `npm run types:check` (both tsconfigs), `npm run domain:check`. Bundle changes also run `npm run smoke:mount`. CI must be green on the required checks (`test (22)`, `test (24)`, `test (22, windows)`, `mount`). Then `/code-review` runs both axes on the diff (Standards against CONTRIBUTING/architecture docs, Spec against the ticket); every finding is fixed in the same PR or explicitly deferred with a reason.
+6. **Land.** PR body follows the four-line contract (failure mode → change → test that fails without it → blast radius). `main` is protected: PR + required checks, admins included, no force-push. A closure comment carries `verified-by: <test file>` and `commit: <sha>`; `npm run audit:issues` flags closures whose evidence is missing.
+7. **Release.** `release:check` compares the version, the previous tag and the CHANGELOG; a tag push fails when the version did not move or the tag does not match. Releases are either **tag-only** (version + changelog + compatibility row + annotated tag; no npm publish, no GitHub Release) or **published** (adds the human `npm publish --tag latest` with 2FA, `dist-tags` verification, then the GitHub Release). The mode is recorded in the milestone/plan.
+8. **Learn.** After a release (or a wave that went sideways) run `/retro`: mechanical mistakes become deterministic checks (scripts, CI jobs, preflight), judgement calls become written standards. Periodically run `/improve-codebase-architecture` for deepening opportunities and `/domain-modeling` to keep the vocabulary and ADRs (2.3.0) honest.
+
+## Decision table
+
+| Situation | Flow |
+|---|---|
+| Raw external issue | `/triage` → then plan |
+| Design question you cannot settle on paper | `/grill-with-docs`, detour through `/prototype` if it needs a runnable answer |
+| Multi-session feature | `/to-spec` → `/to-tickets` → `/implement-spec` |
+| Small fix with acceptance criteria | ticket → `/implement` (+ `/tdd`) |
+| Architecture epic / parallel missions | Tower plan → missions → review gate → merge |
+| Something broken, cause unknown | `/diagnosing-bugs` (tight red loop first) |
+| Repeated mistakes | `/retro` → checks/standards |
+| Release | release plan: tag-only or publish |
+
+## Invariants
+
+- One ticket per PR series; a branch never touches two tickets.
+- Tracked blocking edges, not prose: work only the frontier.
+- Tower missions: `scope` is the write fence, a mission that outgrows it is re-scoped, not silently widened; the workspace lock keeps one Tower session per repository.
+- Human-only gates: npm publish/2FA, branch-protection changes, anything behind a third-party credential. Stop and hand over rather than inventing a credential path.
+- Context hygiene: keep planning in one window until tickets exist; start each implementation unit from the ticket, not from the previous unit's context.

package/docs/architecture/overview.md

@@ -2,36 +2,71 @@
 
 ## Components
 
-The bundle is all-or-nothing: `cordis.patch.yml` inserts one `tower-bundle` `cordis:group` row whose
-internal sections are the Host plugin, the skills provider, and the worker/reviewer presets. The
-group is the only user-facing component; disabling it disables every section together, so no preset
-or skill can remain mounted while the `tower_*` tools are gone.
+Since #121 the bundle ships a mandatory host anchor plus individually switchable
+optional rows: `cordis.patch.yml` declares top-level `tower` (a `cordis:group`
+that mounts the Host plugin and the mandatory worker preset), then
+`tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`,
+`tower-hmr` (shipped off) and `preset-tower-reviewer`. Turning one optional row
+off removes exactly that capability; the host, the diagnostics and the recovery
+escape keep working.
+
+[Principle 11](../../PRINCIPLES.md) and
+[ADR 0005](../adr/0005-component-surface.md) say a component may exist only for
+a capability whose off state leaves the rest intact, and that the host, health,
+recovery, review and merge-gate capabilities are never switches. Which keys are
+allowed to be switches is a table lookup in
+[component-surface.md](../reference/component-surface.md), generated from
+`scripts/component-surface.json`; the component count is baselined and checked by
+`npm run docs:check:components`. That gate also refuses a `tools.expose*` route
+to a tool that is not on the recorded allowlist (empty since #122) and any
+`cordis.patch.yml` row that defaults a forbidden key off.
 
 ```
 Host plugin (index.js)
- ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
- ├─ lib/tool-registry.js -> registration aggregator, actor guards, shared helpers
- │                    (+ 27 registered repository tools)
- │                    (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
+ ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control)
+ ├─ host/tool-registry.js -> registration aggregator, actor guards, shared helpers
+ │                    (+ 21 define()-registered host tools)
+ │                    (+ tower_mode/tower_control registered by the Host entry, 29 total
+ │                       once every optional capability row is on)
+ │                    (tower_doctor/tower_recover are host tools, never switches)
+ ├─ host/capability-*.js -> optional capability entry points (batch/import/leases/tests/hmr)
  ├─ tools/index.js  -> thin public wiring (re-exports the registry + briefings)
  └─ app/tower.js   -> orchestration surface; delegates to use-case modules
        ├─ app/init.js, provision.js, merge.js, rebase.js, teardown.js
        ├─ app/review.js, findings.js, batch.js, messages.js, roster.js
        ├─ app/plan.js, mission.js, checkCompletion.js, spawn.js, recording.js
-       └─ app/gate.js, read.js, board.js, missionContext.js, enrichedMissions.js
- ports (explicit contracts):
-       ports/store.js vcs.js clock.js ids.js
- adapters (the only I/O):
-       adapters/store-fs.js   the only module importing node:fs
-       adapters/vcs-git.js    the only module importing node:child_process
-       adapters/default.js    composition root: store, vcs, clock, ids
- infrastructure (lib/):
-       lib/store.js           repo-scoped lock + atomic JSON + activity.jsonl
-       lib/git.js             bounded git commands + timeout classification
-       lib/config.js          profile/repo config layers over the pure schema
-       lib/workspaceLock.js   optional one-Tower-session-per-repository advisory lock
-       lib/hmr.js             optional DSH HMR bridge (tower_reload / /tower reload)
-       lib/modeStore.js       per-agent Tower mode persistence
+       ├─ app/spawn-prechecks.js, spawn-support.js, briefing.js
+       └─ app/archive.js, gate.js, read.js, board.js, missionContext.js, enrichedMissions.js
+ host (composition root + process/session glue; the only layer that may hold ambient state):
+       host/tool-registry.js   registration aggregator + shared guards/helpers
+       host/config.js          profile/repo config layers over the pure schema
+       host/doctor.js          read-only environment contract and health checks
+       host/capability-registry.js  mounted-component report for status/doctor
+       host/hmr.js             optional DSH HMR bridge (tower_reload / /tower reload)
+       host/modeStore.js       per-agent Tower mode persistence
+       host/modeState.js       owned in-memory mode state
+       host/presets.js         cross-field preset validation before work starts
+       host/compatibility.js   COMPATIBILITY.md provenance
+       host/tower.js           default-deps Tower binding for tests/embedders
+ ports (explicit runtime contracts, no implementation):
+       ports/contract.js      definePort/assertPort runtime contract primitives
+       ports/{store,vcs,clock,ids,config,state,ownership,caseSensitivity,archive}.js
+       ports/index.js         PORTS table + assertPorts(deps) injection check
+ adapters (the only I/O; they implement the ports):
+       adapters/store-fs.js   the only module importing node:fs; createStorePort()
+       adapters/vcs-git.js    the only module importing node:child_process; createVcsPort()
+       adapters/git.js        bounded git commands + timeout classification
+       adapters/store.js      repo-scoped lock + atomic JSON + activity.jsonl
+       adapters/persistence.js  shared atomic write / lock / heartbeat primitives
+       adapters/archive.js    terminal-mission archive files
+       adapters/leases.js     repo-scoped advisory lease ledger
+       adapters/workspaceLock.js  optional one-Tower-session-per-repository lock
+       adapters/worktreeOwnership.js  worktree identity verification
+       adapters/stateFile.js  state-file load/migrate/persist
+       adapters/caseSensitivity.js  filesystem case-folding probe
+       adapters/legacy.js     read-only legacy snapshot validation + storage
+       adapters/tests.js      test discovery execution + TAP/JSON parsing
+       adapters/default.js    createDefaultDeps(): the one default port implementation set
  pure domain modules (no fs/git):
        domain/errors.js     stable, structural tool error catalog
        domain/batch.js      batch admission create/close/summary validation
@@ -48,7 +83,6 @@ Host plugin (index.js)
        domain/report.js     board rendering
        domain/roster.js     roster predicates
  tools layer:
-       lib/tool-registry.js     registration aggregator + shared guards/helpers
        tools/index.js           thin public wiring (re-exports only)
        tools/*.js               one module per tool, handler + imported input schema
  Subagents
@@ -61,6 +95,54 @@ The main checkout is the control-tower repo; each mission has a branch `tower/<i
 worktree in `.dsh-tower-worktrees/<hash>/<missionId>`. The plugin never operates on the main checkout's
 working tree except merge and the read-only diff.
 
+## Ports and the composition root (#69)
+
+The seam is real, not documented-only. `ports/` exports **runtime contracts**: each module defines a
+frozen `{ name, methods }` descriptor plus an `assert*Port` helper, and `ports/index.js` exposes the
+`PORTS` table and `assertPorts(deps)`.
+
+`app/**` imports only app siblings, `domain/**`, `ports/**` and `node:path`. Every effectful call goes
+through the `deps` object:
+
+| deps member | contract | default implementation |
+|---|---|---|
+| `store` | StorePort: `pathsFor/exists/ensureDir/readJson/writeJsonAtomic/appendJsonl/withLock/withGitLock/readActivityTail` plus the raw-file and lock primitives `readText/writeText/appendText/rename/renameWithRetry/stat/unlink/readGitLock/gitLockView` | `adapters/store-fs.js` `createStorePort()` |
+| `vcs` | VcsPort: `git/tryGit/revParse/isClean/isAncestor/resolveRepo/currentBranch/countCommits/listWorktrees` | `adapters/vcs-git.js` `createVcsPort()` |
+| `clock`, `ids` | ClockPort / IdsPort | `adapters/default.js` |
+| `config` | ConfigPort: `runtimeConfig/resolveRepoConfig` | `host/config.js` |
+| `state` | StatePort: `loadStateFile` | `adapters/stateFile.js` |
+| `archive` | ArchivePort: `readIndex/readEntry/writeEntries` | `adapters/archive.js` |
+| `ownership` | OwnershipPort: `assertOwnership/canonicalPath` | `adapters/worktreeOwnership.js` |
+| `caseSensitivity` | CaseSensitivityPort: `detect` | `adapters/caseSensitivity.js` |
+
+`index.js` is the composition root: it calls `createDefaultDeps()` once and passes the object to
+`registerTowerTools`. The registry adopts and validates that object (`assertPorts`) instead of building
+its own adapter set, hands every tool an `openTower(repoRoot)` factory bound to those ports, and
+`Tower.open(repoRoot, deps)` / `new Tower(repo, config, deps)` validates the object again before use.
+`app/tower.js` itself imports no adapter and no `host/` module. The one piece of lock policy the app and
+the store share (the git-mutex budget, #93) is pure and lives in `domain/lockBudget.js`;
+`adapters/store.js` re-exports it for the infrastructure callers.
+
+`store.rename` and `store.renameWithRetry` are both declared because they are not interchangeable: the
+retrying helper has temp-file semantics and removes its source when the rename finally fails, which is
+right for a disposable temp file but would destroy the lock bytes `tower_recover` must keep auditable.
+The audit rename therefore uses the plain `rename`. The contract test scans `app/**` **and** `tools/**`
+for every `deps.<port>.<method>` call and fails if the named port does not declare it, so a tool that
+reaches a new port method cannot slip past `assertPorts`.
+
+`lib/` no longer exists (#70): every module was `git mv`-ed into the layer that owns it. The I/O
+implementations now sit in `adapters/` (`store`, `persistence`, `git`, `archive`, `stateFile`,
+`leases`, `workspaceLock`, `worktreeOwnership`, `caseSensitivity`, `legacy`, `tests`), the
+composition root and process/session glue in `host/`, and spawn policy in `app/`. `host/**` is the
+only source root, besides `adapters/**` itself, allowed to import an adapter; `app/**` and `domain/**`
+may not import `lib/**` (rule `no-lib-from-core`) and may not hold ambient module state
+(`host-scope`). Tools receive effectful helpers from the registry instead of importing an adapter.
+
+A full mission lifecycle (init → plan → provision → spawn → complete → review → gate → merge →
+teardown) runs through the real app use cases on an in-memory store and a scripted vcs:
+`tests/ports-lifecycle.test.mjs`. The default adapter set and the in-memory doubles are both asserted
+against the same port contracts in `tests/memory-adapters.contract.test.mjs`.
+
 ## Mission state machine
 
 ```
@@ -82,7 +164,7 @@ set by `tower_merge`/reconciliation.
    against the merge base.
 3. Survey missions must not change files; build missions must stay inside `scope`.
 4. The main checkout must be clean for the files this merge would overwrite and on the base branch.
-5. Dependency missions must be merged/abandoned.
+5. Dependency missions must be merged/abandoned, except a completed survey dependency which is its terminal success state (#107).
 6. If `review.requireReview:true` (default false), a review must exist, belong to this mission, be
    clean, approve merge, and be bound to the tip (unless a clean rebase waived it). No worker may be
    running.
@@ -105,7 +187,7 @@ After the command, regardless of exit status, it inspects `HEAD`:
 | `<git-common-dir>/dsh-tower/archive/index.json` | compact terminal-mission index (ids, status, branch, timestamps) |
 | `<git-common-dir>/dsh-tower/archive/<year>.json` | full archived missions plus their linked reviews/findings |
 | `<git-common-dir>/dsh-tower/activity.jsonl` | append-only activity |
-| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (dead-PID reclaimed, live lock reported) |
+| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (heartbeat reclaim; a recycled PID cannot pin it) |
 | `<git-common-dir>/dsh-tower/git.lock` | repo-scoped serialization for git mutations outside the state lock |
 | `<git-common-dir>/dsh-tower/lock-holds.jsonl` | state/git lock-hold telemetry |
 | `<checkout parent>/.dsh-tower-worktrees/<hash>/<missionId>` | mission worktree |
@@ -113,8 +195,10 @@ After the command, regardless of exit status, it inspects `HEAD`:
 | `$DSH_HOME/tower-mode/modes.lock` | mode-store single-writer lock |
 
 `state.json` and `modes.json` both use an atomic write (temp + rename), token-checked lock release,
-dead-PID reclamation, and bounded lock waits. `state.json` is the mission persistence contract;
-`modes.json` is the per-agent mode contract; neither is written without its own lock.
+heartbeat-based reclamation (a live PID with a silent heartbeat is reclaimed after byte verification;
+a live holder that keeps heartbeating is never stolen), and bounded lock waits. `state.json` is the
+mission persistence contract; `modes.json` is the per-agent mode contract; neither is written without
+its own lock.
 
 ## Layering rules
 
@@ -123,17 +207,66 @@ dead-PID reclamation, and bounded lock waits. `state.json` is the mission persis
 - `domain/**` must not import I/O or adapters (`domain-pure`).
 - Only `adapters/vcs-git.js` may import `node:child_process`, and only
   `adapters/store-fs.js` may import `node:fs` (`child-process-surface`, `fs-surface`).
-  The rule is enforced over the source roots — `lib/`, `app/`, `domain/`, `tools/`,
+  The rule is enforced over the source roots — `host/`, `app/`, `domain/`, `tools/`,
   `adapters/`, `ports/` — and does not cover `scripts/**`, which holds maintenance
   entry points (release check, mount smoke, docs generators) that may spawn git or npm.
+  The optional Web client (`ui-bundle/`) is its own tier with its own rules.
 - `tools/**` must stay thin and free of status/type literals (`tools-thin`, `tools-vocabulary`);
-  `tools/index.js` is the thin public wiring module and stays exempt from the thinness rule,
-  while registration/shared machinery lives in `lib/tool-registry.js`.
-- Aggregate files have size ceilings; top-level mutable state is limited to explicit composition
-  roots (`aggregate-size`, `ambient-state`). The per-tool ceiling is 200 lines; only the
-  `tools/index.js` wiring module is exempt, and it is now far below the ceiling.
+  `tools/index.js` is the thin public wiring module (it imports `host/tool-registry.js`, not a
+  `node:` module), while registration/shared machinery lives in `host/tool-registry.js`.
+  Tools receive effectful helpers (repository resolution, leases, recovery, legacy import) from
+  the registry instead of importing an adapter.
+- Aggregate files have size ceilings; top-level mutable state is limited to `host/**`
+  (`aggregate-size`, `host-scope`). The per-tool ceiling is 200 lines; `tools/index.js`
+  currently sits inside the 40-200 range, so the tools allow-list is empty rather than silently
+  exempting the wiring module.
+- `app/**` may import only app siblings, `domain/**`, `ports/**` and `node:path` (`app-ports-only`);
+  an app module that reaches an adapter, a `host/` module or `lib/` fails the gate.
+- `app/**` and `domain/**` may not import the retired `lib/` layer (`no-lib-from-core`); with the
+  layer gone this keeps it from creeping back.
+- `host/**` is the only source root that may hold ambient module state (`host-scope`);
+  `app/**` and `domain/**` must stay stateless at module scope. Only `host/**` and `adapters/**`
+  may import an adapter (`composition-root`); `app/`, `tools/`, `domain/` and `ports/` never may.
+- Every `ports/**` module must export a runtime contract (`const`/`function`/`class`) and must not
+  import an implementation (`port-shape`); a typedef plus `export {}` is no longer accepted.
+- `ui-bundle/**` is a browser tier, not host code (#71): no `node:*` import
+  (`client-no-node` — DOM globals are fine; host capabilities must come through the
+  plugin's registration surface), every client file stays at or below 800 lines
+  (`client-size`), and module-level mutable state is banned exactly as it is for
+  `app/**` (`client-ambient`); the split surfaces keep their state inside the
+  `create*` closure the entry composes. `ui-bundle/` is also excluded from
+  `aggregate-size`, which it would otherwise duplicate.
+
+### Exemptions are justified data
+
+The gate's only exemptions live in `scripts/architecture-waivers.json`; `scripts/architecture.mjs`
+keeps no allow-lists of its own. Since #70 the file has exactly two entries, both I/O adapter
+boundaries (`adapters/vcs-git.js` for `node:child_process` and `adapters/store-fs.js` for
+`node:fs`). Each entry names the `rule` and `path` and must carry a non-empty `reason` plus an
+`owner` or `ref`. An entry missing any of those is itself a blocking `waiver-contract` violation
+that names the rule and the path, so a bare path cannot turn the gate green. The waiver file is a
+two-key path in `CONTRIBUTING.md`; there is no `reviewBy`/expiry field in this release, so the
+reason and the owner are the reviewed decision.
+
+`host-scope` replaces the old `ambient-state` waivers (#70). It scans `app/**` and `domain/**` and
+records every module-level `let`; `host/**` owns the process/session state and needs no waiver. The
+scan is statement-aware rather than line-based: it walks the module's token stream and records every
+binding of every top-level `let` declaration. A second declarator (`let a = 1, b = 2`), a second
+statement on one line (`let a = 1; let b = 2`), and any new top-level `let` in `app/` or `domain/`
+are each their own violation. Strings, comments, template literals and regex literals are skipped,
+and `let` inside a function, block, class or `for (…)` header is not module-level state.
 
-A fixture test seeds one violation per rule, so a rule that cannot fail is itself a test failure.
+`domain-pure`, `host-scope`, `no-lib-from-core`, and anything under `domain/**` are load-bearing: no
+waiver may target them, even a justified one. A `waiver-contract` violation rejects that entry and
+the underlying rule still fails.
+
+A green run prints `architecture: ok (waivers: N)`; N is the number of entries that actually
+suppressed a violation, so a stale waiver is visible in the output and in the tests. The fixture
+suite seeds an unjustified waiver (it fails), a justified one (it passes), a `host-scope` fixture
+that puts ambient state in `host/` (allowed) and in `app/`/`domain/` (rejected), a `no-lib-from-core`
+import from `app/` (rejected), a same-line second binding (rejected), and a new violation inside
+each rule. A separate fixture seeds one violation per rule, so a rule that cannot fail is itself a
+test failure.
 
 ## Mount smoke and host internals
 
@@ -149,24 +282,40 @@ probe adjustments in the same change.
 
 All epic DoD items now have an executable gate:
 
-- Pure domain share: **37.9%** (5,993 / 15,820 source lines), enforced by
-  `npm run domain:check` (threshold 35%).
-- `domain/**` imports no fs, child_process, adapters, app, tools, or lib infrastructure;
+- Pure domain share: **39.5%** (7,475 / 18,936 host source lines), enforced by
+  `npm run domain:check` (threshold 35%). `npm run domain:metrics` also prints a
+  separate `ui-bundle` line, so Web-client growth is visible in CI output while the
+  share itself still measures the Host architecture.
+- `domain/**` imports no fs, child_process, adapters, app, tools, or host infrastructure;
   `domain-pure` is a blocking architecture rule.
 - Inside the source roots, only `adapters/vcs-git.js` imports `node:child_process`; only
-  `adapters/store-fs.js` imports `node:fs`; both are blocking rules with fixtures.
-- `lib`, `app`, and `domain` files stay <= 800 lines; every `tools/**` file stays
+  `adapters/store-fs.js` imports `node:fs`; both are blocking rules whose files are the only
+  `child-process-surface`/`fs-surface` entries in `scripts/architecture-waivers.json`.
+- `host`, `app`, and `domain` files stay <= 800 lines; the same ceiling applies to
+  `ui-bundle/**` (`client-size`); every `tools/**` file stays
   40-200 lines (one handler module per tool; `tools/index.js` is 40-line wiring).
 - No `withLock` scope starts a process; the two-phase tests instrument every git call.
 - `tools/**` has no status/type/enum literal; vocabulary is owned by
   `domain/vocabulary.js`; the `tools-vocabulary` rule is blocking.
 - `validateState` has a four-line body over `domain/state/schema.js` and
   `domain/state/semantics.js`.
-- `state.json` and `modes.json` share `lib/persistence.js` atomic write, token-owned
+- `state.json` and `modes.json` share `adapters/persistence.js` atomic write, token-owned
   lock, dead-PID quarantine, and bounded-wait primitives.
-- The in-memory lifecycle and adapter contracts run a full mission lifecycle with no
-  disk and no git.
-- The seven fitness rules are errors, each with a seeded failing fixture.
+- The in-memory lifecycle runs the real app use cases (init → plan → provision → spawn → complete →
+  review → gate → merge → teardown) on an in-memory store and scripted vcs supplied through the
+  composition root, with no disk, no git and no `defaultDeps` (#69).
+- The eleven host fitness rules are errors, each with a seeded failing fixture; the
+  three `client-*` rules form the Web-client tier with one fixture each, and the
+  `waiver-contract` rule makes an unjustified exemption blocking as well.
+
+## Non-goals
+
+This layer map is not a dependency-injection container, a service locator, or a
+place to register classes by reflection. Ports stay runtime contracts and the
+composition root stays the only place that assembles implementations.
+
+Enforced by: `scripts/architecture.mjs` and `ports/index.js`; tests in
+`tests/architecture.test.mjs`; gate: `npm run architecture:check`.
 
 
 

package/docs/guide/hot-reload.md

@@ -26,8 +26,8 @@ This page covers the development loop. It is not required to use Tower.
   `plugin_manager`); it compares already-loaded modules with disk and replaces the changed ones even
   with `root: []`. Watching only makes that happen automatically after a save.
 - HMR is only mounted for profile boots (`disabled` when there is no `profileContext`). A process
-  booted without a profile reports reload as unavailable (`tower_reload` stays registered while
-  `dev.hotReload` is on, so the tool returns `reload-unavailable` instead of disappearing).
+  booted without a profile reports reload as unavailable (`tower_reload` stays registered while the
+  `tower-hmr` component row is on, so the tool returns `reload-unavailable` instead of disappearing).
 - The profile patch layer is loaded when DSH boots. Editing it — in practice the hmr `root` list —
   takes effect after **one DSH restart**. Nothing in the running process re-reads the HMR row's own
   configuration.
@@ -86,7 +86,7 @@ To stop watching, run `npm run dev:hmr -- --remove` and restart DSH once.
 
 ## The edit loop
 
-1. Edit `lib/*.js`, `index.js`, `worker.js`, `reviewer.js` or `skills.js`.
+1. Edit `host/*.js`, `adapters/*.js`, `app/*.js`, `domain/**/*.js`, `index.js`, `worker.js`, `reviewer.js` or `skills.js`.
 2. Save the file. The watcher debounces (DSH default 100 ms) and reconciles the profile; changed
    modules are replaced and the affected Loader entries restart.
 3. Watch the DSH log for `reload plugin at <path>` / `restart required: …` messages.
@@ -99,9 +99,9 @@ The bridge behind the tool follows the `dev` config group:
 
 | Config key | Meaning |
 |---|---|
-| `dev.hotReload` | Register `tower_reload`; `/tower reload` is disabled when off (default `true`). Without the HMR service the tool is still registered so it can return `reload-unavailable`. |
+| `tower-hmr` (component row) | The switch: on registers `tower_reload` and `/tower reload`, off reports "disabled by component tower-hmr". The row ships off; enable it from the plugin page for a linked dev profile. `dev.hotReload` was removed in 2.4.0 and is now an unknown key. |
 | `dev.reloadDelayMs` | Delay before the scheduled reconciliation runs, in milliseconds (default `50`), so the tool/command result reaches the model before the plugin is replaced. |
-| `dev.reloadRequiredIds` | Loader entry ids the profile must keep active (default `tower-bundle`, `tower`, `tower-skills`, `preset-tower-worker`, `preset-tower-reviewer`). An inactive required entry is reported as a reload failure even if it was already inactive. |
+| `dev.reloadRequiredIds` | Loader entry ids the profile must keep active (default `tower`, `tower-host`, `preset-tower-worker`). An inactive required entry is reported as a reload failure even if it was already inactive. Optional capability rows are deliberately not required, so a row switched off is not a reload failure. |
 
 A reload is **scheduled, not awaited**: `/tower reload` and `tower_reload` return immediately with
 `scheduled`, `delayMs`, `requiredIds` (and the current `lastError` when one is pending), then HMR

package/docs/guide/install-upgrade-migration.md

@@ -45,6 +45,19 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
   overlapping and case-only mismatches are no longer refused by the out-of-scope gate. Stored scope
   strings are never rewritten: the board keeps showing what the operator typed.
 
+- **2.3.0 → 2.4.0 (unreleased)**: the single `tower-bundle` group row is gone. `cordis.patch.yml`
+  now ships the mandatory `tower` host anchor (the Host plugin and the worker preset are its internal
+  sections) plus 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 `tools` config group and `dev.hotReload` were removed: a profile that
+  still carries them is now rejected as an unknown key (`config-unknown-key`) and the host stops
+  mounting until they are deleted, so no silent no-op switch remains. Move each capability to its row
+  in the plugin page instead; `tower-hmr` ships off, so `tower_reload` and `/tower reload` are reported
+  as "disabled by component tower-hmr" until you enable it for a linked dev profile. `tower_doctor` and
+  `tower_recover` are registered for every configuration and need no key. The reviewer row may be off
+  only while `review.requireReview` is false; with the gate on, planning and mode entry refuse the
+  combination with an explanatory error. No state migration is needed.
+
 - **2.0.4 → 2.1.0-beta.1**: no config migration; the state file migrates automatically (v1/v2 → v3) as
   described above. This is a **pre-release** published on the
   `next` dist-tag, so `latest` still resolves to 2.0.4 — install it with

package/docs/guide/release.md

@@ -58,7 +58,7 @@ Put the **host build in cell 0** and the **tag in cell 1**:
 | 0.2.1-rc.2 | v2.1.0-beta.1 | 2026-10-22 | `npm test`, `npm run docs:check`, mount smoke |
 ```
 
-`lib/compatibility.js#parseCompatibility` reads cells 0–3 only: never insert a column before
+`host/compatibility.js#parseCompatibility` reads cells 0–3 only: never insert a column before
 the tag and never add one before "what was run", or `tower_doctor` stops seeing the row. The
 host pin in `scripts/mount-smoke/host.json` must equal cell 0 of the newest row (a unit test
 enforces it).