dsh-tower 2.1.0-beta.1 → 2.3.0

package/docs/agents/issue-tracker.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. For this repo the remote is `louifinn/dsh-tower`.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use. The right column currently equals the role name, so these are the defaults — `wontfix` already exists on the GitHub repo, while `needs-triage`, `needs-info`, `ready-for-agent`, and `ready-for-human` will be created by `/triage` on first use (or add them upfront with `gh label create`).

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 four `docs:check:generated*`, `npm run pack:check`, `npm run architecture:check`, `npm run types:check`, `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

@@ -10,7 +10,7 @@ or skill can remain mounted while the `tower_*` tools are gone.
 ```
 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
+ ├─ host/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)
  ├─ tools/index.js  -> thin public wiring (re-exports the registry + briefings)
@@ -18,20 +18,37 @@ Host plugin (index.js)
        ├─ 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/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 +65,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 +77,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 +146,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.
@@ -101,9 +165,11 @@ After the command, regardless of exit status, it inspects `HEAD`:
 
 | Path | Contents |
 |---|---|
-| `<git-common-dir>/dsh-tower/state.json` | missions, roster, reviews, findings, messages, reviews sequence |
+| `<git-common-dir>/dsh-tower/state.json` | active missions, roster, reviews, findings, messages, reviews sequence |
+| `<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 |
@@ -111,8 +177,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
 
@@ -121,17 +189,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.
 
-A fixture test seeds one violation per rule, so a rule that cannot fail is itself a test failure.
+### 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.
+
+`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
 
@@ -147,24 +264,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

@@ -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.

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

@@ -29,7 +29,24 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
-- **2.0.4 → 2.1.0-beta.1**: no state/config migration. This is a **pre-release** published on the
+- **state schema v1 → v2 (unreleased)**: `state.json` migrates automatically. The first **write** after
+  upgrading keeps a `state.json.v1.bak` backup, advances `revision` once, and appends
+  `state.migrated {from,to}` to `activity.jsonl`; read-only tools keep reading a v1 file without
+  rewriting it. `tower_doctor` reports the on-disk version and the pending migration. A file written by
+  a newer plugin is refused with `[tower:state-version-unsupported]` and is never rewritten or
+  downgraded; a migration that throws reports `[tower:state-migration-failed]` and leaves the original
+  file byte-identical.
+
+- **state schema v2 → v3 (unreleased, #90)**: scope matching follows the checkout's filesystem. The
+  migration backfills `caseInsensitive: null` ("not detected"); a migration never reads the filesystem,
+  so the first `tower_init` after upgrading probes the checkout once and records `true`/`false`. Until
+  then the safe `case-sensitive` comparison applies, and `tower_doctor` reports the unknown mode as a
+  `warn` (`case-mode`). On a case-insensitive checkout, `src/Api/**` and `src/api/**` then count as
+  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.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
   `dsh plugin --profile web add dsh-tower@next` (or the exact version). The runtime behavior is
   unchanged; the release carries the delivery gate (mount smoke in CI, `npm run release:check`, the

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).

package/docs/operations/incident.md

@@ -0,0 +1,82 @@
+# Incidents and regressions
+
+A **regression** is something that *worked in a released version, then stopped*.
+It is not a feature request and not an ordinary bug: a user could rely on the old
+behavior, so the record must say which release broke it, who was affected, and
+which test now prevents it from happening again.
+
+Only shipped regressions get this record. Ordinary bugs, missing features and
+questions use the normal issue flow.
+
+## The six-field record
+
+Copy this into the issue body (or the closing comment) when a regression is
+confirmed. All six lines are part of the closure; the `Regression test:` line is
+the one a machine can check.
+
+```text
+Symptom:            what the user sees, with the exact error text
+Introduced in:      version / commit range
+Blast radius:       who is affected (all sessions? restored ones? one platform?)
+Root cause:         one paragraph, mechanism not blame; include the fix
+Regression test:    path to the test that fails without the fix
+Released in:        version that carries the fix, and how it was verified
+```
+
+The fields answer, in order: what broke, which release introduced it, the user
+impact, the cause and the fix, the proof, and the release that carries the fix.
+`Introduced in` and `Released in` are different answers; do not fill both with the
+current version.
+
+## Label
+
+The `regression` label means exactly **"worked in a released version, then
+stopped"**. It is mutually exclusive with `bug` for a shipped break: the regression
+label is the narrower claim. The issue title still describes the symptom.
+
+## Closing rule
+
+A `regression` issue may not be closed while any of these is true:
+
+- no `Regression test:` line names a path;
+- the path does not exist in the repository;
+- the path is not a test file (a script or a doc is not evidence).
+
+The offline audit reads a local tracker export, so it needs no network and no
+token:
+
+```powershell
+# 1) Export (network, once) — same export as the P0/P1 audit
+New-Item -ItemType Directory -Force tracker | Out-Null
+$all = foreach ($n in (gh issue list --repo louifinn/dsh-tower --state all --limit 500 --json number --jq '.[].number')) {
+  gh issue view $n --repo louifinn/dsh-tower --json number,title,state,labels,closedAt,body,comments | ConvertFrom-Json
+}
+@{ issues = @($all) } | ConvertTo-Json -Depth 8 | Set-Content tracker/issues.json -Encoding utf8
+
+# 2) Audit (offline)
+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` — at least
+one is missing or points at a nonexistent/non-test path; `2` — the export is
+missing or malformed.
+
+The audit is a script because a checklist is only as reliable as the reader.
+`tests/regression-audit.test.mjs` proves the check fails for a seeded missing path
+and passes for a real one, so the rule cannot silently become prose.
+
+## Where the practice starts
+
+The first real entry is #68 (all tower write tools failed with `unknown` after a
+session restore). The tower retro-fills that issue with these six fields; this
+document is the template it used.
+
+## Non-goals
+
+No blameless-postmortem ceremony for ordinary bugs, no SLA commitments, no
+five-whys, and no incident commander. Only shipped regressions get the six fields.
+
+Unowned. This is a writing habit and a closing convention; no runtime code
+enforces it. The one checkable part — the `Regression test:` path — is enforced by
+`scripts/regression-audit.mjs`.

package/docs/operations/runbook.md

@@ -48,9 +48,18 @@ fails, the previous plugin code no longer runs: restart DSH and check the HMR lo
 
 ## State lock
 
-`tower state is locked by another writer` means an operation holds `state.lock`. Wait and retry. Only if
-the owning process is gone, remove `<git-common-dir>/dsh-tower/state.lock` deliberately; never delete it
-while an agent may still be running.
+`tower state is locked by another writer` means an operation holds `state.lock`. Wait and retry: a
+live holder rewrites the record's `at` heartbeat every second, so it is never stolen while it runs.
+A crashed holder stops heartbeating; once its last heartbeat is older than three intervals (3 s), the
+next mutation reclaims the record after byte verification. A reclaimed live-PID record is kept as
+`state.lock.reclaimed-<ts>-<id>` for audit; a provably dead PID (ESRCH) is reclaimed immediately.
+
+If a lock never clears, `tower_recover({action:"status"})` reports the owner's `pid`, `startedAt`,
+`ageMs` and `heartbeatAgeMs`, and `tower_doctor` reports the same. `tower_recover
+clear-stale-lock` with `confirm:"CLEAR_STALE_LOCK"` moves a provably dead lock to
+`state.lock.recovered-<ts>`; add `force: true` to clear a live-but-silent PID (the recycled-PID case)
+after confirming no writer is active. The repair always renames, never deletes, so the bytes stay
+auditable. Never delete `state.lock` by hand while an agent may still be running.
 
 ## Worktrees and teardown
 

package/docs/reference/blockers.md

@@ -16,12 +16,12 @@ tables below define 32 stable blocker/failure codes.
 | `branch-missing` | No worktree/branch yet: spawn a worker first. |
 | `stale-base` | The branch does not contain the base tip: run `tower_rebase`. |
 | `read-only-survey` | Survey mission changed files; survey missions must be read-only. |
-| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. |
+| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. On a case-sensitive checkout a case-only mismatch is still rejected and the detail names the scope entry it would match if case were folded. |
 | `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
-| `deps-unmerged` | A dependency mission is not merged/abandoned. |
+| `deps-unmerged` | A dependency mission is not satisfied: a build dependency must be `merged`/`abandoned`, while a survey dependency is satisfied at `completed` (archived entries included). |
 | `no-review` | `review.requireReview:true` and no review exists on the branch: spawn a reviewer (or disable the review gate). |
 | `review-mission-mismatch` | `review.requireReview:true` and the latest review belongs to another mission. |
-| `not-clean` | `review.requireReview:true` and latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
+| `not-clean` | `review.requireReview:true` and latest review is `p1-Nitems`/`p2-Nitems`; another round is required. Verdicts from later routes of the same round are appended to it instead of flipping the mission again. |
 | `review-hold` | `review.requireReview:true` and latest review recommends hold; a later clean review must supersede it. |
 | `review-not-approved` | `review.requireReview:true` and latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
 | `tip-moved` | `review.requireReview:true` and the branch changed after review; review again (or use a clean rebase waiver). |

package/docs/reference/config.generated.md

@@ -1,6 +1,7 @@
 # Config reference (generated)
 
 > Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
+> Surface: config keys: 64 · sections: 15 · tools: 27 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|
@@ -51,8 +52,12 @@
 | `gates.requireChecks` | `false` | Require at least one completion check (tower_complete.checks) before a mission can merge. |
 | `gates.requireTests` | `false` | Require a passing test-discovery receipt for the reviewed worktree tip before merge. |
 | `gates.allowReviewExemption` | `false` | Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers. |
+| `gates.maxReportBytes` | `32768` | Hard cap, in UTF-8 bytes, for tower_complete.report; a larger report is rejected with an actionable nextAction, never truncated. |
 | `docs.board` | `true` | Write a human-readable MISSIONS.md after mission changes. |
 | `docs.boardLocation` | `"common"` | common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. |
+| `archive.enabled` | `true` | Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history. |
+| `archive.afterDays` | `30` | Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). |
+| `archive.maxMissions` | `100` | Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission). |
 | `tools.exposeOperational` | `true` | Master switch for batch/resource/import/legacy/recover/test/doctor tools. |
 | `tools.exposeBatch` | `true` | Register tower_batch. |
 | `tools.exposeImport` | `true` | Register tower_import_legacy/tower_legacy_map. |

package/docs/reference/config.md

@@ -83,8 +83,12 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
 | `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
 | `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
+| `gates.maxReportBytes` | `32768` (32 KiB) | Hard cap in UTF-8 bytes for `tower_complete.report`. A larger report is rejected with `invalid-argument` and an actionable `nextAction` (file the full text in the mission worktree and reference its path); it is never truncated. Existing larger reports still load. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
+| `archive.enabled` | `true` | Move terminal (`merged`/`abandoned`) missions whose worktree is gone into `<git-common-dir>/dsh-tower/archive/` at a mutation boundary. Archived missions keep tasks, reviews, findings and the completion report; they are moved, never deleted. |
+| `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). |
+| `archive.maxMissions` | `100` | Cap trigger: once more than this many terminal missions are hot, the oldest eligible ones are archived until the cap holds (`0` archives every eligible terminal mission). A mission with a live worktree is never archived. |
 | `tools.exposeOperational` | `true` | Register batch/resource/import/legacy/recover/test/doctor tools; `false` shrinks the fixed tool-schema context. |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
 | `dev.hotReload` | `true` | Register `tower_reload`; `/tower reload` is disabled when off. It returns `reload-unavailable` when the profile has no HMR service. |