dsh-tower 2.0.4 → 2.1.0

package/docs/agents/domain.md

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+This repo is **single-context**: one `GLOSSARY.md` and one `docs/adr/` at the repo root.
+
+```
+/
+├── GLOSSARY.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+(If the repo ever grows per-package contexts, switch to the multi-context layout: a root `GLOSSARY-MAP.md` pointing at per-context `GLOSSARY.md` files, with system-wide decisions in `docs/adr/` and context decisions in `src/<context>/docs/adr/`.)
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

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/architecture/overview.md

@@ -2,24 +2,61 @@
 
 ## 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.
+
 ```
 Host plugin (index.js)
  ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
- ├─ lib/tools.js  -> 19 repository tools incl. tower_diff, tower_findings and tower_interrupt
- │                   (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
- └─ lib/tower.js  -> Tower domain: missions, gates, worktrees, roster, review, findings, merge
-       ├─ lib/git.js          minimal git port (execFile, bounded output, timeout classification)
-       ├─ lib/store.js        repo-scoped lock + atomic JSON + activity.jsonl
-       ├─ lib/config.js       Config schema + profile/repo layers + runtime snapshot
-       ├─ lib/errors.js       stable tool error codes and classification
-       ├─ 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
-Subagents
+ ├─ 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)
+ ├─ 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
+ pure domain modules (no fs/git):
+       domain/errors.js     stable, structural tool error catalog
+       domain/batch.js      batch admission create/close/summary validation
+       domain/config/schema.js  Schemastery config schema, defaults, validation
+       domain/contracts/outputs.js  tool output-schema catalog
+       domain/contracts/tool-inputs/  per-area TypeBox input schemas + ToolInputs map
+       domain/vocabulary.js  canonical status/type/action enums + predicates
+       domain/mission.js    statuses, transitions, pause causes
+       domain/gate.js       completion and merge-gate snapshot decisions
+       domain/scope.js      glob/scope validation and overlap
+       domain/summary.js    mission/finding summaries
+       domain/planning.js   mission numbering, dependency DAG, auto-deps
+       domain/state.js      load-time state validation
+       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
  ├─ tower-worker   (dsh-tower/worker)   read/write/edit/pwsh + mission tools + findings
  └─ tower-reviewer (dsh-tower/reviewer) read/glob/grep + tower_diff + review/finding (read-only)
 ```
 
+
 The main checkout is the control-tower repo; each mission has a branch `tower/<id>-<slug>` and a
 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.
@@ -64,8 +101,72 @@ 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 lock (stale locks are reported, never stolen) |
+| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (dead-PID reclaimed, live lock reported) |
+| `<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 |
 | `$DSH_HOME/tower-mode/modes.json` | Tower mode per agent/session |
+| `$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.
+
+## Layering rules
+
+`npm run architecture:check` (also in CI) enforces the rules as **errors**:
+
+- `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/`,
+  `adapters/`, `ports/` — and does not cover `scripts/**`, which holds maintenance
+  entry points (release check, mount smoke, docs generators) that may spawn git or npm.
+- `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.
+
+A fixture test seeds one violation per rule, so a rule that cannot fail is itself a test failure.
+
+## Mount smoke and host internals
+
+`npm run smoke:mount` (#95) boots a real profile through the pinned host instead of mocking the loader.
+`scripts/mount-smoke/probe.mjs` is the one file that imports the host's internals — `runProfile` from
+`dsh/lib/profile-boot.js` and the layered env from `dsh-app-boot` — because those are the entry points
+`dsh` itself calls to compose a profile; the probe uses them to boot without a model, browser, or
+session. `scripts/mount-smoke/host.json` is the single host/pnpm pin (a unit test keeps its `dsh` field
+equal to the newest `COMPATIBILITY.md` row), so a host bump can move those entry points and may require
+probe adjustments in the same change.
+
+## #56 definition of done
+
+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;
+  `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
+  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
+  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.
+
+
+

package/docs/board.md

@@ -0,0 +1,72 @@
+# Tracker board
+
+The three questions an owner asks weekly, as commands that actually work. Run them from the
+repository root (or add `--repo louifinn/dsh-tower`). Verified against the live tracker on
+2026-10-22; the counts below are evidence for the commands, not a promise they stay fixed.
+
+Priority lives in the `P0`–`P3` labels and area in `area/*`; issue titles carry no `[P*]`
+prefix any more. Every open issue has exactly one `P*` label and at least one `area/*` label.
+
+## Open P1
+
+```bash
+gh issue list --state open --label P1
+```
+
+Verified: **10** open on 2026-10-22 (#56, #69, #76, #77, #82, #94, #95, #96, #97, #98).
+
+`--label` uses REST filters, so it does not wait for the search index after an edit. Do **not**
+write `--label P0,P1`: `gh` treats that as one literal label name and returns nothing (verified).
+For "P0 or P1" use `--search 'label:P0,P1'` — inside `--search`, the comma means OR, while
+`label:P0 label:P1` (a space) means AND and returns only issues carrying both.
+
+## Unmilestoned P0/P1
+
+```bash
+gh issue list --state open --search 'no:milestone label:P0,P1'
+```
+
+Verified: **0** on 2026-10-22 — every open P0/P1 is in a milestone. A non-zero result means a
+release-scoped issue has no home; put it in the next release milestone or demote it to P2/P3.
+
+## Closed this week by area
+
+```bash
+# week starts Monday; compute it rather than pasting yesterday's date
+# GNU date (Linux/CI); on macOS use `gdate` or work the date out by hand
+MONDAY=$(date -d 'last monday' +%F)
+gh issue list --state closed --search "closed:>=$MONDAY label:area/ci"
+```
+
+```powershell
+$MONDAY = (Get-Date).Date.AddDays(-(([int](Get-Date).DayOfWeek+6)%7)).ToString('yyyy-MM-dd')
+gh issue list --state closed --search "closed:>=$MONDAY label:area/ci"
+```
+
+Swap `area/ci` for `area/state`, `area/tools`, `area/docs`, `area/release`, `area/process`,
+`area/architecture`, or `area/scope`. Verified for `area/ci` with `closed:>=2026-10-19`:
+**0**, because all **54** issues closed that week carry no `area/*` label at all. The query is
+right; the history is unlabelled. Label a closure before you close it (or backfill) and the
+by-area view starts working.
+
+## Release rule query
+
+A release may not be tagged while its milestone holds an open P0/P1 unless the release notes
+say why. Check the milestone that is about to ship (see the [release checklist](guide/release.md)):
+
+```bash
+gh issue list --state open --search 'milestone:2.1.0-beta.1 label:P0,P1' --json number,title
+```
+
+Verified: **8** on 2026-10-22 (#76, #77, #82, #94, #95, #96, #97, #98) — the delivery gate's own
+tickets block the release until they land. That is the rule doing its job, not a false positive.
+
+## Milestones
+
+```bash
+gh api 'repos/louifinn/dsh-tower/milestones?state=all&per_page=100' \
+  --jq '.[] | "\(.number)\t\(.title)\topen=\(.open_issues)\tclosed=\(.closed_issues)"'
+```
+
+Only issues that actually block a release belong in a milestone; everything else stays
+unmilestoned and is queried by priority.

package/docs/guide/hot-reload.md

@@ -101,7 +101,7 @@ The bridge behind the tool follows the `dev` config group:
 |---|---|
 | `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`. |
 | `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`, `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-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. |
 
 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

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-- DSH `0.2.1-rc.2` or newer
+- DSH `0.2.1-rc.2`; see [COMPATIBILITY.md](../../COMPATIBILITY.md) for the builds actually verified per release
 - Node.js 22+
 - Git (local worktrees; no network access is required)
 
@@ -29,6 +29,30 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
+- **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
+  evidence conventions and the tracker policy) rather than tool changes. These docs merge before the
+  human publish step: `next` only resolves to 2.1.0-beta.1 after the [release checklist](release.md)
+  runs `npm publish --tag next`, and `latest` stays on 2.0.4 until a stable release.
 - **2.0.3 → 2.0.4**: no state/config migration. This is a security-hardening and integrity release
   (authorization, merge SHA binding, dirty-worktree completion, stale-lock recovery, limited test/git
   process environment, `tower_recover`, UI 0.2.2). Review `review.requireReview`, `tests.admission` and

package/docs/guide/release.md

@@ -0,0 +1,125 @@
+# Release checklist
+
+One page, six steps, in order. The only **human-only** step is `npm publish` (npm
+credentials + 2FA); an agent can do everything else in this repository. A release is a claim —
+`npm run release:check` is the mechanical half of it.
+
+## Milestone rule (before step 1)
+
+A release may not be tagged while its milestone holds an open P0/P1, unless the release
+notes say why it was accepted:
+
+```bash
+gh issue list --state open --search 'milestone:2.1.0-beta.1 label:P0,P1' --json number,title
+```
+
+Empty output → proceed. Non-empty → close the issues (with the two-line closure contract in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#the-two-line-closure-contract)), or name each accepted
+issue and the reason in the release notes. The same query is saved in [the board](../board.md);
+comma means OR inside `--search`, while `--label P0,P1` matches one literal label name and
+returns nothing.
+
+`npm run release:check` prints `git describe`, the previous tag, the commit count since that
+tag and whether Unreleased is non-empty on every run. On a PR it warns; on a tag push it fails
+when `package.json` did not move past the last tag, when the tag is not `v<version>`, or when
+the CHANGELOG has no release content. CI runs it on every push and PR.
+
+## 1. Bump the version
+
+Edit `package.json` (`"version": "2.1.0-beta.1"`). The previous tag is found from the pushed
+tag's parent (`<tag>^`), so a tag push that repeats the old version fails.
+
+```bash
+npm run release:check -- --mode tag --tag v2.1.0-beta.1
+```
+
+## 2. Write the changelog
+
+Move the Unreleased entries under a version heading, so the GitHub Release body can be
+extracted mechanically. Keep the `## 未发布（Unreleased）` heading (it may be empty).
+
+```markdown
+## 未发布（Unreleased）
+
+## 2.1.0-beta.1（2026-10-22）
+
+- feat: ...
+```
+
+The gate accepts a non-empty Unreleased section (bump first, rename later) **or** a non-empty
+section whose heading names the version. Write the version section as user-facing notes.
+
+## 3. Add the COMPATIBILITY row
+
+`COMPATIBILITY.md` keeps the columns `| dsh version | tag / commit | verified on | what was run |`.
+Put the **host build in cell 0** and the **tag in cell 1**:
+
+```markdown
+| 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
+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).
+
+Commit steps 1–3 as the release PR against protected `main`, merge it, then continue from a
+**clean clone/worktree at the merge commit** — not the integration worktree.
+
+## 4. Publish — human-only (2FA)
+
+```bash
+git status --porcelain          # must be empty: files:["docs/"] packs untracked docs too
+npm ci
+npm test && npm run docs:check && npm run pack:check
+npm pack --dry-run              # inspect the published file list
+npm publish --tag next --otp <code>
+npm view dsh-tower dist-tags --json
+npm view dsh-tower@next version
+```
+
+- Publish pre-releases with `--tag next`, **never** `latest`; `latest` moves only for a stable minor.
+- Publish **before tagging**. If publishing fails, do not tag. If you already tagged, delete it
+  (`git tag -d <tag>` and `git push --delete origin <tag>`) instead of leaving a tag on an
+  unpublished commit.
+- Both checks must name the version just published, and `next` must differ from `latest`.
+
+## 5. Annotated tag on the published commit
+
+```bash
+npm run release:check -- --mode tag --tag v2.1.0-beta.1
+git tag -a "v2.1.0-beta.1" -m "dsh-tower 2.1.0-beta.1"
+git push origin "v2.1.0-beta.1"
+git for-each-ref refs/tags/v2.1.0-beta.1 --format='%(objecttype)|%(subject)'
+# tag|dsh-tower 2.1.0-beta.1      (a lightweight tag prints commit, and is not allowed)
+```
+
+The pushed tag must be exactly `v<version>`. The tag push re-runs `release:check` against
+`<tag>^`; this is why tagging a commit whose `package.json` did not move fails.
+
+## 6. GitHub Release from the CHANGELOG section
+
+```bash
+VERSION=2.1.0-beta.1
+awk -v v="$VERSION" '$0 ~ "^##[[:space:]]+.*" v {s=1; next} s && /^##[[:space:]]/ {exit} s {print}' \
+  CHANGELOG.md > release-notes.md
+test -s release-notes.md || { echo "empty section for $VERSION" >&2; exit 1; }
+gh release create "v$VERSION" --title "dsh-tower $VERSION" --notes-file release-notes.md \
+  --prerelease --verify-tag --latest=false
+gh release view "v$VERSION" --json tagName,isPrerelease,body
+```
+
+PowerShell extraction of the same section:
+
+```powershell
+$version = '2.1.0-beta.1'; $lines = Get-Content CHANGELOG.md
+$start = ($lines | Select-String -Pattern "^##\s+.*$([regex]::Escape($version))" | Select-Object -First 1).LineNumber
+if (-not $start) { throw "CHANGELOG has no section for $version" }
+$next = ($lines | Select-String -Pattern '^##\s+' | Where-Object LineNumber -gt $start | Select-Object -First 1).LineNumber
+$end = if ($next) { $next - 2 } else { $lines.Count - 1 }
+($lines[$start..$end] -join "`n").Trim() | Set-Content release-notes.md -Encoding utf8
+```
+
+`--verify-tag` refuses to create the tag at the default branch when the pushed tag is missing;
+`--prerelease --latest=false` keeps the GitHub "latest" marker on the stable release. Releases
+are what consumers and the plugin directory can see — a tag alone is not a release.

package/docs/operations/security.md

@@ -44,6 +44,49 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 - **Legacy import is read-only.** Imported snapshots live under the canonical state directory and are never
   activated, adopted, or resumed; an operator must explicitly re-plan/migrate work.
 
+## Repository protection
+
+This section is about **this repository**, not about a repository Tower runs on. Server-side branch
+protection is not a plugin feature — Tower writes to the local base branch and cannot configure a
+remote — but `dsh-tower` enables it for its own `main`, because the code that is the gate is also the
+code an attacker would most want to change:
+
+- `main` requires a pull request for every change, **enforced for admins**, so a direct push is
+  rejected even for the maintainer.
+- Required checks are `test (22)`, `test (24)` and `mount`. The mount job packs the tarball and boots
+  it in a throwaway profile, so "the tests pass" cannot land a bundle that fails to appear after
+  `dsh plugin add`.
+- Force-push and branch deletion are blocked, so history cannot be rewritten under a published tag.
+- There are no mandatory approvals: with one maintainer, a self-approval requirement would be a rubber
+  stamp. The evidence instead is the four-line PR body (failure mode, change, test, blast radius) for
+  the two-key paths, written in [CONTRIBUTING.md](../../CONTRIBUTING.md#landing-changes).
+
+What this buys: no untested change reaches `main`, a red or missing required check cannot be bypassed
+by the owner, and history is append-only. What it does **not** buy: a second reader, protection against
+a compromised maintainer token, or any protection for the repositories Tower itself operates on — those
+remain deployment concerns. The settings, their rationale and a verification command are recorded in
+[SECURITY.md](../../SECURITY.md#repository-protection-on-main).
+
+## Model-initiated mode entry (threat model)
+
+`mode.allowAgentControl:true` means a prompt injection in a repository file, issue text, or fetched
+page can ask the model to “enter tower mode and fix this”. Tower does **not** authenticate the human
+intent behind that entry. What it does provide:
+
+- the entry is recorded with actor, action, reason, and timestamp; `tower_status.mode.history`
+  surfaces the recent transitions without grepping the activity log;
+- the model cannot merge without the preflight gate, review policy, scope checks, tests, and
+  clean-base checks; writing the plan does not bypass them;
+- workers are tool-restricted and instructed to stay in their worktree, but the main-checkout
+  protection is enforced by scope/merge checks and the preset, **not** by an OS sandbox;
+- `mode.workspaceLock` prevents a second Tower session from driving the same repository.
+
+It does **not** defend against: a model that legitimately passes every gate while acting on malicious
+instructions; repository hooks or test commands the repository itself declares; or filesystem/shell
+access outside the worktree by a worker that ignores its instructions. For a higher-assurance team,
+set `mode.allowAgentControl:false`, keep `review.requireReview:true`, review the repository before
+Tower work, and run the host under OS-level isolation.
+
 ## Not enforced by the plugin (deployment concerns)
 
 - **Worktree isolation is a protocol convention, not an OS sandbox.** Workers are assigned a dedicated
@@ -65,8 +108,10 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   from disk. Only enable HMR watch roots for checkouts you trust; a reload executes the current files.
 - **Prompt injection.** The reviewer reads untrusted branch content (diff/comments). The read-only preset
   limits impact, but no model-side protection is absolute.
-- **Base branch protection.** Tower writes to the local base branch; server-side branch protection/push
-  rules are not part of the plugin.
+- **Base branch protection.** Tower writes to the local base branch; server-side branch protection and
+  push rules are not part of the plugin. This repository's own `main` protection is described in
+  [Repository protection](#repository-protection); enabling equivalent protection on the repository you
+  run Tower on remains a deployment concern.
 
 ## Reporting
 

package/docs/reference/blockers.md

@@ -16,7 +16,7 @@ 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. |
 | `no-review` | `review.requireReview:true` and no review exists on the branch: spawn a reviewer (or disable the review gate). |