dsh-tower 2.0.3 → 2.1.0-beta.1

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.
@@ -46,8 +83,9 @@ set by `tower_merge`/reconciliation.
 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.
-6. 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.
+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.
 
 ## Merge
 
@@ -65,6 +103,68 @@ After the command, regardless of exit status, it inspects `HEAD`:
 |---|---|
 | `<git-common-dir>/dsh-tower/state.json` | missions, roster, reviews, findings, messages, reviews sequence |
 | `<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/examples/first-mission.md

@@ -23,7 +23,8 @@ Wait for the worker's final report (delivered to this session) or check `tower_r
 creates `src/greet.txt`, commits on `tower/m1-add-greeting`, marks both tasks done, and calls
 `tower_complete`.
 
-Spawn the reviewer:
+This example follows the strict workflow: enable `review.requireReview:true` in the profile or
+repository config before the review step (default is optional review). Spawn the reviewer:
 
 ```json
 {"repoRoot":"D:\\work\\demo","missionId":"M1","role":"reviewer"}

package/docs/faq.md

@@ -1,7 +1,8 @@
 # FAQ
 
 **When should I use Tower instead of Agent Teams, Ralph, Workflow, or ordinary subagents?**
-Use Tower when the output is a reviewed, integrated change to one Git repository. Use ordinary
+Use Tower when the output is an integrated change to one Git repository (enable review when you also
+need an independent verdict). Use ordinary
 subagents for read-only exploration or quick independent subtasks, Agent Teams for cross-cutting human
 collaboration, Ralph for repeated fresh attempts at one objective, and Workflow for programmatic
 high-fan-out analysis. The full decision guide, scenarios, and comparison table are in
@@ -9,19 +10,21 @@ high-fan-out analysis. The full decision guide, scenarios, and comparison table
 
 **Can I combine Tower with Team/Workflow/Ralph?**
 Not concurrently in the same session: Tower mode refuses their tools and clears plan mode. Compose by
-phase instead—use Workflow/Team to analyze and decide, then start Tower to execute and review the
-repository change. See the [full guide](guide/scenarios-and-philosophy.md#4-how-tower-differs-from-other-dsh-workflow-patterns).
+phase instead—use Workflow/Team to analyze and decide, then start Tower to execute (and optionally
+review) the repository change. See the [full guide](guide/scenarios-and-philosophy.md#4-how-tower-differs-from-other-dsh-workflow-patterns).
 
 **Why did `tower_preflight` fail with `no-review` right after the worker finished?**
-That is expected: a completed mission awaits review. Spawn a reviewer; after a clean review the gate
-turns green.
+That happens only when `review.requireReview:true` is enabled: a completed mission awaits an
+independent review. Spawn a reviewer; after a clean review the gate turns green. With the default
+`review.requireReview:false`, review is optional and no `no-review` blocker is produced.
 
 **Do I need to poll the worker?**
 No. The worker's final report is delivered to this session; `tower_roster` shows live activity. Polling
 wastes turns.
 
 **`/tower` says the mode is on but `tower_control` is missing.**
-`mode.allowAgentControl` is off. Set it to `true` in the profile patch and restart DSH.
+`mode.allowAgentControl` is disabled. It defaults to `true`; if it was set to `false`, set it back to
+`true` in the profile patch and restart DSH.
 
 **The merge hook takes minutes and `tower_merge` failed.**
 Retry with a larger `timeoutMs`: `tower_merge({ missionId, timeoutMs: 1800000 })`. The default is 15
@@ -39,7 +42,8 @@ instead of rebasing.
 **Can I require independent review?**
 Yes. Set `review.requireReview:true` in the profile or repository config to enable the global review
 gate (default is `false`, review optional). When enabled, mission-level `reviewPolicy:"none"` + a
-reason is the narrower exemption. `tower_review` works and records verdicts either way.
+reason + `gates.allowReviewExemption:true` is the narrower exemption. `tower_review` works and records
+verdicts either way.
 
 **Can a reviewer edit files?**
 No. Reviewers use the read-only `tower-reviewer` preset (no write/edit/pwsh); a branch changed after the

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,13 +29,29 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
-- **1.x → 2.0 (unreleased)**: no state migration is needed (`schemaVersion` stays 1; new fields are
+- **2.0.4 → 2.1.0-beta.1**: no state/config migration. 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
+  worker tool permissions against your threat model after upgrading.
+- **2.0.1 → 2.0.3**: no state migration. Independent review became **optional by default** in 2.0.3
+  (`review.requireReview:false`); set it to `true` to keep the old review-gated merges. 2.0.1 added
+  `tower_batch` `abandon`, accepted merged members in batch close, made doctor skip torn-down worktrees,
+  and fixed terminal-mission spawn/preflight edge cases. The optional `ui-bundle` 0.2.1 adds the
+  persistent Tower-mode chip and mode-aware denied-tool rows.
+- **1.x → 2.0 (released)**: no state migration is needed (`schemaVersion` stays 1; new fields are
   optional). Behavior changes to review: `mode.denyTools` now also denies `workflow`, `ralph`, `subagent`,
   `subagent_fork`, `wait_agent` and `team_task_list` while Tower mode is active (override with an explicit
-  list); `spawn.maxLiveWorkers` defaults to 4; `mode.workspaceLock` is off by default. Workers can no
-  longer complete/abandon/scope a mission directly — use `tower_complete`. New tools: `tower_interrupt`,
-  and `tower_reload` when HMR is available. Restart DSH once after upgrading; see
-  [hot reload](hot-reload.md).
+  list); `spawn.maxLiveWorkers` defaults to 4; `mode.workspaceLock` is off in the code default and on in
+  the bundled patch. Workers can no longer complete/abandon/scope a mission directly — use
+  `tower_complete`. New tools: `tower_interrupt`, and `tower_reload` when HMR is available. Restart DSH
+  once after upgrading; see [hot reload](hot-reload.md).
 - **1.3 → 1.4**: no state migration is needed. New: repository-level config
   (`<git-common-dir>/dsh-tower/config.json`), stable `[tower:<code>]` tool errors, `tower_findings`,
   and `id`/`missionId` + snake/camel input aliases. Existing calls keep working; restart DSH to load

package/docs/guide/quickstart.md

@@ -31,14 +31,17 @@ The call returns immediately with the child agent id. The worker works inside th
 commits, marks tasks done, and calls `tower_complete`; its final report is delivered back to this
 session. Use `tower_roster` to observe activity; do not poll in a loop.
 
-## 4. Review
+## 4. Optional: review
+
+Independent review is optional by default. If you want the strict workflow, enable it in the profile
+or repository config first (`review.requireReview:true`), then:
 
 ```
 tower_spawn repoRoot=D:\work\repo missionId=M1 role=reviewer
 ```
 
 Reviewers use the read-only `tower-reviewer` preset. They inspect `tower_diff` and submit
-`tower_review`. A `clean` + `merge` verdict is required to merge.
+`tower_review`; with `review.requireReview:true`, a `clean` + `merge` verdict is required to merge.
 
 ## 5. Gate, merge, clean up
 
@@ -48,8 +51,9 @@ tower_merge     repoRoot=D:\work\repo missionId=M1
 tower_teardown  repoRoot=D:\work\repo
 ```
 
-`tower_preflight` before review is expected to report `no-review`; after a clean review it should be
-`ok:true`. `tower_merge` refuses while blockers remain. `tower_teardown` removes merged/abandoned
+With the review gate enabled, `tower_preflight` before review reports `no-review`, and after a clean
+review it should be `ok:true`. With the default (`review.requireReview:false`), no review blocker is
+required. `tower_merge` refuses while blockers remain. `tower_teardown` removes merged/abandoned
 worktrees and branches.
 
 ```
@@ -59,8 +63,9 @@ worktrees and branches.
 ## If something fails
 
 Read the blocker code and use [the blocker reference](../reference/blockers.md). The most common cases:
-`stale-base` (run `tower_rebase`), `no-review` (spawn a reviewer), `merge-hook-failed` (retry, or raise
-`timeoutMs`), `tip-moved` (the branch changed after review; review again).
+`stale-base` (run `tower_rebase`), `no-review` (only with `review.requireReview:true`; spawn a
+reviewer), `merge-hook-failed` (retry, or raise `timeoutMs`), `tip-moved` (only with the review gate;
+the branch changed after review, review again).
 
 Thrown tool failures carry a `[tower:<code>]` prefix; see [error codes](../reference/errors.md)
 (e.g. `preset-missing` means restart DSH after installing the bundle, `not-initialized` means run
@@ -73,7 +78,7 @@ JSON file at `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/c
 
 ```json
 {
-  "review": { "maxRoundsPerReviewer": 3 },
+  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" }
 }

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.