dsh-tower 2.4.2 → 2.6.0

package/docs/architecture/overview.md

@@ -12,9 +12,14 @@ escape keep working.
 
 [Principle 11](../../PRINCIPLES.md) and
 [ADR 0005](../adr/0005-component-surface.md) say a component may exist only for
-a capability whose off state leaves the rest intact, and that the host, health,
-recovery, review and merge-gate capabilities are never switches. Which keys are
-allowed to be switches is a table lookup in
+a capability whose off state leaves the rest intact, and that the host, the
+health contract, the recovery escape and the merge gates are never switches.
+The review policy is not one of them: `review.mode` is a single tri-state
+control (`off`, `optional` or `required`) on the plugin-page configuration
+form, not a component row and never one row per mode, and only the review gate
+it turns on in `required` mode — the clean, tip-bound evidence and the
+exemption path — is non-disableable. Which keys are allowed to be switches is a
+table lookup in
 [component-surface.md](../reference/component-surface.md), generated from
 `scripts/component-surface.json`; the component count is baselined and checked by
 `npm run docs:check:components`. That gate also refuses a `tools.expose*` route
@@ -236,9 +241,10 @@ 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, 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.
+6. If the review policy is `required` (`review.mode:required`; the default is `optional`), a review
+   must exist, belong to this mission, be clean, approve merge, and be bound to the tip (unless a clean
+   rebase waived it). With `off`, review is intentionally unavailable and the gate ignores it. No
+   worker may be running.
 
 ## Merge
 

package/docs/examples/first-mission.md

@@ -23,8 +23,9 @@ 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`.
 
-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:
+This example follows the strict workflow: set the review policy to `required` (`review.mode:required`
+in the profile or repository config, or the one tri-state control on the Plugins page) before the
+review step; the default is `optional`. Spawn the reviewer:
 
 ```json
 {"repoRoot":"D:\\work\\demo","missionId":"M1","role":"reviewer"}

package/docs/faq.md

@@ -14,9 +14,9 @@ phase instead—use Workflow/Team to analyze and decide, then start Tower to exe
 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 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.
+That happens only when the review policy is `required` (`review.mode:required`): a completed mission
+awaits an independent review. Spawn a reviewer; after a clean review the gate turns green. With the
+default `review.mode:optional`, 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
@@ -40,10 +40,12 @@ Correct: the branch is already contained in the base. Call `tower_merge` to reco
 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 + `gates.allowReviewExemption:true` is the narrower exemption. `tower_review` works and records
-verdicts either way.
+Yes. Set the review policy to `required` — the one tri-state control on the Plugins page, or
+`review.mode:required` in the profile or repository config (the default is `optional`). When required,
+mission-level `reviewPolicy:"none"` + a reason + `gates.allowReviewExemption:true` is the narrower
+exemption. `tower_review` works and records verdicts in `optional` mode too. The old boolean toggle is
+a deprecated one-release alias; the mapping is in
+[install, upgrade and migration](guide/install-upgrade-migration.md).
 
 **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/install-upgrade-migration.md

@@ -29,6 +29,50 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
+- **2.5.0 → 2.6.0 (#M39/#M40) — review modes replace the boolean**: the review policy is one
+  tri-state control on the Plugins page in the `dsh-tower` configuration section, and the config key
+  is `review.mode`: `off`, `optional` (the default) or `required`.
+  - `off` is supported and documented: `tower_review` is not registered, reviewer spawn is refused,
+    and the merge gate ignores review.
+  - `optional` keeps `tower_review` but never blocks a merge.
+  - `required` keeps the merge gate: a completed mission needs a clean review bound to the branch tip
+    (the existing per-mission exemption still applies).
+  `review.requireReview` is a deprecated one-release alias: `true` resolves to `required`, `false`
+  to `optional`, and leaving it unset means `optional`. A `true` next to an explicit non-`required`
+  mode is rejected with `config-invalid`; `false` never overrides an explicit mode. Saving from the
+  plugin page always writes `review.mode` and normalizes the alias to `false`. The policy is not a
+  component row and there are no mutually exclusive review rows: `preset-tower-reviewer` remains an
+  optional capability the policy may leave unused. The row may be off while `review.mode` is `off`
+  or `optional`; when `review.mode` is `required` and the reviewer row is off, planning and mode
+  entry refuse the combination with an explanatory `preset-missing` error.
+  A profile that starts with the policy `off` never registered `tower_review`; switching to
+  `optional` or `required` changes the merge gate immediately, but the tool appears only after a DSH
+  restart (or a profile reload), and the plugin page states that after such a save.
+  Upgrade: replace `review.requireReview: true|false` with `review.mode: required|optional`; keep the
+  alias only if the same config is shared with older 2.5 installations, and remove it after this
+  release. No state migration.
+
+- **2.4.2 → 2.5.0 (#131/#133/#135/#136/#142)**: three component-shaped config
+  keys are gone — `tests.enabled`, `docs.board`, and `archive.enabled`. The
+  `tower-tests`, `tower-board`, and `tower-archive` component rows are the only
+  switches. A profile or repository config that still writes any of these keys is
+  rejected as `config-unknown-key` with an upgrade note and the host stops
+  mounting, so delete the key and enable or disable the row in the plugin page
+  instead. `docs.boardLocation` and `archive.afterDays`/`archive.maxMissions`
+  remain tuning keys. With `tower-tests` off there is no `tower_test` tool and no
+  receipt, which also means `gates.requireTests` cannot be satisfied: planning and
+  mode entry refuse that combination, and the merge gate's `tests-missing` blocker
+  names the disabled row and the fix. `tower_test` no longer reports "not
+  configured" for a component cause; it reports `disabled by component
+  tower-tests` with the remedy.
+  Two more runtime rules became explicit: a config that sets `spawn.requireLease`
+  while the `tower-leases` row is off is refused up front with `config-invalid`
+  naming the row and both remedies (previously every spawn failed at `lease-busy`
+  advising an unregistered `tower_resource`), and `/tower` re-validates the runtime
+  preconditions only when it enters the mode, so `/tower off` and a forwarded
+  `/tower <text>` keep working while an unrelated row is disabled. No state
+  migration; see [component rows and messages](quickstart.md#component-rows-runtime-preconditions-and-message-language).
+
 - **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
@@ -49,14 +93,14 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
   now ships the mandatory `tower` host anchor (the Host plugin and the worker preset are its internal
   sections) plus individually switchable top-level rows: `tower-skills`, `tower-batch`, `tower-import`,
   `tower-leases`, `tower-tests`, `tower-hmr` (shipped off) and `preset-tower-reviewer` (conditional on
-  `review.requireReview`). The `tools` config group and `dev.hotReload` were removed: a profile that
-  still carries them is now rejected as an unknown key (`config-unknown-key`) and the host stops
+  the review policy, today `review.mode`). The `tools` config group and `dev.hotReload` were removed: a
+  profile that still carries them is now rejected as an unknown key (`config-unknown-key`) and the host stops
   mounting until they are deleted, so no silent no-op switch remains. Move each capability to its row
   in the plugin page instead; `tower-hmr` ships off, so `tower_reload` and `/tower reload` are reported
   as "disabled by component tower-hmr" until you enable it for a linked dev profile. `tower_doctor` and
   `tower_recover` are registered for every configuration and need no key. The reviewer row may be off
-  only while `review.requireReview` is false; with the gate on, planning and mode entry refuse the
-  combination with an explanatory error. No state migration is needed.
+  while the policy is `off` or `optional`; with `review.mode:required`, planning and mode entry refuse
+  the combination with an explanatory error. No state migration is needed.
 
 - **2.0.4 → 2.1.0-beta.1**: no config migration; the state file migrates automatically (v1/v2 → v3) as
   described above. This is a **pre-release** published on the
@@ -68,10 +112,12 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
   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.
+  process environment, `tower_recover`, UI 0.2.2). Review the review policy (`review.mode`, or the
+  deprecated `review.requireReview` alias), `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
+  (today's `review.mode:optional`); set `review.mode:required` 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.

package/docs/guide/quickstart.md

@@ -33,15 +33,25 @@ session. Use `tower_roster` to observe activity; do not poll in a loop.
 
 ## 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:
+The review policy is one tri-state control — `off`, `optional` (the default) or `required` — on the
+Plugins page in the `dsh-tower` configuration section, or `review.mode` in the profile/repository
+config. It is one control, not a component row and not three rows. Set it to `required` for the strict
+workflow, 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`; with `review.requireReview:true`, a `clean` + `merge` verdict is required to merge.
+`tower_review`; with `review.mode:required`, a `clean` + `merge` verdict is required to merge.
+`optional` records reviews but never blocks a merge, and `off` is a supported mode that does not
+register `tower_review`.
+
+The old boolean review toggle is a one-release alias (`true` → `required`, `false` → `optional`;
+unset → `optional`). Prefer `review.mode`. A profile that started with
+`off` only registers `tower_review` after a restart/reload, although the merge gate changes
+immediately. See [install, upgrade and migration](install-upgrade-migration.md) for the full
+migration.
 
 ## 5. Gate, merge, clean up
 
@@ -51,10 +61,10 @@ tower_merge     repoRoot=D:\work\repo missionId=M1
 tower_teardown  repoRoot=D:\work\repo
 ```
 
-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.
+With `review.mode:required`, `tower_preflight` before review reports `no-review`, and after a clean
+review it should be `ok:true`. With the default (`optional`), no review blocker is required.
+`tower_merge` refuses while blockers remain. `tower_teardown` removes merged/abandoned worktrees and
+branches.
 
 ```
 /tower off
@@ -63,8 +73,8 @@ 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` (only with `review.requireReview:true`; spawn a
-reviewer), `merge-hook-failed` (retry, or raise `timeoutMs`), `tip-moved` (only with the review gate;
+`stale-base` (run `tower_rebase`), `no-review` (only with `review.mode:required`; spawn a reviewer),
+`merge-hook-failed` (retry, or raise `timeoutMs`), `tip-moved` (only when the policy is `required`;
 the branch changed after review, review again).
 
 Thrown tool failures carry a `[tower:<code>]` prefix; see [error codes](../reference/errors.md)
@@ -78,7 +88,7 @@ JSON file at `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/c
 
 ```json
 {
-  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
+  "review": { "mode": "required", "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" }
 }
@@ -100,3 +110,74 @@ Statuses are `open → triaged → fixed` / `wontfix`, and `fixed`/`wontfix` can
 tower or a worker may change a finding; reviewers can list and read.
 
 A complete copy-paste example: [examples/first-mission.md](../examples/first-mission.md).
+
+## Component rows, runtime preconditions and message language
+
+The optional component rows are the only switches in this bundle (#121, #136). Three runtime rules
+follow from that, plus the language policy for everything a tool prints.
+
+### A row is the only switch
+
+`tests.enabled` was removed (#136). Discovery is on exactly while the `tower-tests` row is mounted:
+with the row off there is no `tower_test` tool and no test receipt to gate on, so a second boolean
+could only disagree with the mounted profile. A repository config that still writes
+`tests.enabled` is rejected as `config-unknown-key`; delete the key and enable or disable the row
+instead.
+
+The same reasoning covers the other rows:
+
+- `tower-leases` owns `tower_resource`. `spawn.requireLease` is satisfied through that tool, so a
+  config that requires a lease while the row is off is refused by the runtime preconditions with
+  `config-invalid`, naming the row and both remedies ("re-enable the tower-leases component or clear
+  spawn.requireLease") instead of failing every spawn at `lease-busy` with advice to use a tool that
+  is not registered (#131).
+- `tower-tests` must stay mounted while `gates.requireTests` is true. Planning and mode entry refuse
+  the combination; the merge gate's `tests-missing` blocker also names the disabled row as the cause
+  (#140).
+- `tower-hmr` ships off; `/tower reload` reports it by row name.
+
+No runtime path may claim a repository is "not configured" when a component row is the reason.
+Runtime refusals report the cause as `disabled by component <id>` and come with the fix (`enable the
+<id> row in the plugin page and restart DSH`).
+
+### Preconditions run on mode entry, not on every `/tower` input (#142)
+
+`/tower` re-validates the runtime preconditions (presets, component/config contradictions) only when
+it **enters** Tower mode:
+
+| Input | Preconditions |
+|---|---|
+| `/tower`, `/tower on`, `/tower <text>` while the mode is off | validated |
+| `/tower off`, `/tower off <text>` | not validated |
+| `/tower <text>` while the mode is already on | not validated |
+| `/tower ack`, `/tower base <branch>`, `/tower reload` | not validated |
+
+The reason: a row disabled after the session started (or a profile reloaded with a stricter config)
+must not make `/tower off` — the command a human needs to leave the mode — or an ordinary forwarded
+instruction fail. Capability guards still run where the work happens: `tower_spawn`, planning and
+merge/preflight evaluate their own preconditions, so the checks cannot be bypassed by entering the
+mode first.
+
+### Language of tool output
+
+Machine-facing output is **English only**, regardless of the request locale:
+
+- tool errors (`[tower:<code>] ...`), `nextAction`, blocker `detail` strings, `tower_status` /
+  `tower_doctor` detail lines, and completion reports;
+- anything that a script, a log search or another agent is expected to pattern-match.
+
+Localized, human-facing copy lives in `locale/*.json` (component descriptions, UI labels) and is the
+only translated surface. Two rules keep the split honest:
+
+1. New detail/error strings are written in English even when the surrounding UI is Chinese; they are
+   not added to `locale/*.json`.
+2. A localized label never shadows a machine-readable cause. The row id, the error code and the
+   English remedy phrase stay verbatim inside the message, so a grep for
+   `disabled by component tower-tests` works in every locale.
+
+`tower_status` and `tower_doctor` follow this policy but are not textually identical: `tower_status`
+returns the cause only — `components.disabled` is `[{id, reason}]` with `reason` set to
+`disabled by component <id>` — while `tower_doctor` repeats that reason and adds the English remedy
+(`enable the reported row in the plugin page and restart DSH` for the `components` check; a
+capability-specific check names the row directly, e.g. `enable the tower-tests row and restart DSH`).
+Neither interpolates a translated label.

package/docs/guide/release.md

@@ -97,29 +97,70 @@ git for-each-ref refs/tags/v2.1.0-beta.1 --format='%(objecttype)|%(subject)'
 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
+## 6. GitHub Release with cumulative notes
+
+A Release body is not just its own CHANGELOG section: it carries **every** section after the
+previous GitHub Release (see [Cumulative Release notes](#cumulative-release-notes--累积发布说明)
+below). `scripts/release-notes.mjs` is the authority for that body — do not hand-extract a single
+section. The checklist step is `npm run release:notes -- --version <v> --since <prev-release> --output notes.md`, then pass that file to `gh release create`/`gh release edit` with `--notes-file notes.md`.
 
 ```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
+# Stable release (the common case): no pre-release flags.
+VERSION=2.3.0
+SINCE=2.1.0                 # the previous GitHub Release, not the previous tag
+npm run release:notes -- --version "$VERSION" --since "$SINCE" --output notes.md
+npm run release:notes -- --version "$VERSION" --since "$SINCE" --check notes.md
+gh release create "v$VERSION" --title "dsh-tower $VERSION" --notes-file notes.md --verify-tag
+# editing a Release that already exists (for example, to correct its window):
+gh release edit "v$VERSION" --notes-file notes.md
 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
+```bash
+# Pre-release variant (a beta, for example 2.5.0-beta.1): mark the Release and keep "latest"
+# on the previous stable Release.
+VERSION=2.5.0-beta.1
+SINCE=2.4.2                 # the previous GitHub Release; a pre-release counts as one too
+npm run release:notes -- --version "$VERSION" --since "$SINCE" --output notes.md
+gh release create "v$VERSION" --title "dsh-tower $VERSION" --notes-file notes.md \
+  --prerelease --verify-tag --latest=false
 ```
 
-`--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.
+`--check notes.md` exits 1 when the file differs from the generated text (it prints the first
+differing line and both byte counts), so a correction is verifiable. The script exits 2 on a
+missing/unknown flag, an invalid version, `since >= version`, or an empty window; it never emits
+a Release body it cannot justify.
+
+`--verify-tag` refuses to create the tag at the default branch when the pushed tag is missing.
+A beta Release adds `--prerelease --latest=false`: GitHub marks it as a pre-release and keeps
+the "latest" marker on the stable Release. Releases are what consumers and the plugin directory
+can see — a tag alone is not a release.
+
+## Cumulative Release notes / 累积发布说明
+
+A GitHub Release is cumulative: it aggregates every CHANGELOG section **after the previous
+Release**, up to and including the version being released.
+
+- The **previous Release** is the latest published GitHub Release by version. Pre-releases
+  created with `--prerelease` count as Releases, so a `2.1.0-beta.1` Release is a boundary too.
+- **Tag-only versions have no Release.** A version that was tagged or published to npm without
+  creating a GitHub Release — 2.1.1 and 2.1.2 were tag-only, and 2.2.0 too — would otherwise
+  lose its notes; its CHANGELOG section rolls into the next Release.
+- Example: once 2.1.0 is the previous Release, the 2.3.0 Release includes 2.1.1, 2.1.2, 2.2.0
+  and 2.3.0:
+
+  ```bash
+  npm run release:notes -- --version 2.3.0 --since 2.1.0 --output notes.md
+  ```
+
+  The window is `(2.1.0, 2.3.0]`; `2.1.0-beta.1` sorts before 2.1.0 and therefore stays out.
+- `npm run release:notes` (`scripts/release-notes.mjs`) is the authoritative generator: it reads
+  `CHANGELOG.md`, filters the window, orders sections by SemVer (pre-release identifiers
+  included), and emits the `# dsh-tower <v>` title, a provenance quote naming the previous
+  Release and the included versions, then the sections separated by `---`.
+- `--check <file>` re-verifies an existing notes file byte-for-byte (exit 1 on a mismatch), so
+  the body of a published Release can be audited without editing it. Use `--root <dir>` to check
+  another checkout.
+
+Never hand-extract only the current version's section: that is what produced single-section
+Releases whose tag-only predecessors were invisible.

package/docs/guide/scenarios-and-philosophy.md

@@ -10,8 +10,8 @@ a better fit.
 
 If you only remember one sentence: **use Tower when the output is an integrated repository change that
 must land through a controlled merge; use the other patterns when the output is exploration, repeated
-attempts, or programmatic fan-out.** Enable `review.requireReview` when the change also needs an
-independent reviewer.
+attempts, or programmatic fan-out.** Set the review policy to `required` when the change also needs
+an independent reviewer; the default policy is `optional`.
 
 ## 1. The design philosophy
 
@@ -45,11 +45,13 @@ When review is enabled, a reviewer also inspects a specific branch tip and the g
 binding. Separation of duties is the point when review is on: the agent that wrote the code is not the
 agent that approves it, and neither is the agent that merges.
 
-Independent review is optional by default: `review.requireReview:true` enforces it (and then a complete
-mission must carry a clean, merge-approved review from a reviewer bound to the branch tip). Set the flag
-to `true` for sensitive repositories; `reviewPolicy:"none"` + a reason + `gates.allowReviewExemption:true`
-remains available as a per-mission exemption when the global gate is on. Reviews can be submitted and
-recorded either way.
+The review policy is one tri-state control: `off`, `optional` (the default) or `required`. `required`
+enforces independent review (a complete mission must carry a clean, merge-approved review from a
+reviewer bound to the branch tip). Choose it for sensitive repositories; `reviewPolicy:"none"` + a
+reason + `gates.allowReviewExemption:true` remains available as a per-mission exemption when the
+policy is required. `optional` records reviews but never blocks a merge, and `off` is a supported
+mode that removes the review tool. The policy is configuration, not a component row: there is one
+control on the plugin page, not three mutually exclusive rows.
 
 ### 1.5 Evidence over assertion
 
@@ -184,7 +186,7 @@ integration, and what "done" means.**
 | Isolation | Git worktree + branch per mission; one writer per mission | Shared workspace; coordination by task ownership | Fresh child per round; no built-in branch/merge contract | Per-step child; no Git isolation | Child sessions; may share workspace |
 | Durable state | Git metadata + JSON state + activity + board | Team task board + sessions | Minimal; each round starts fresh | Run record/results; not a merge ledger | Session/subagent records |
 | Integration authority | Tower only, after preflight/gate (plus review when enabled) | Humans/teammates merge or edit manually | Usually the parent/worker applies results | Script applies results | Parent applies results |
-| Review / gate | Optional independent review (enable `review.requireReview`) + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
+| Review / gate | Optional independent review (one `review.mode` control: off/optional/required) + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
 | Parallelism | Multiple missions, disjoint scopes, serialized merges | Many teammates, shared board | Sequential rounds (or external fan-out) | High fan-out, script-controlled | High fan-out |
 | Human role | Owns the mode; can inspect evidence and release | Collaborator/coordinator | Author of the repeated objective | Author of the orchestration script | Delegator |
 | Best for | Feature delivery, migrations, release-bound changes | Design, research, cross-cutting collaboration | Iterative search/repair with fresh context | Large audits, batch analysis, deterministic pipelines | Quick exploration or independent subtasks |
@@ -195,8 +197,8 @@ integration, and what "done" means.**
 Ordinary `subagent`/`subagent_fork` calls are cheap and flexible. They are the right tool for "read
 these five files in parallel" or "try three approaches". They do not provide a write scope, a
 dedicated worktree, a durable mission, independent review, or a merge gate. Tower wraps the same
-subagent primitive in those contracts; it also costs more per child. (Review is optional: enable
-`review.requireReview` when you need the reviewer role.)
+subagent primitive in those contracts; it also costs more per child. (Review is optional: set the
+policy to `required` when you need the reviewer role to gate a merge.)
 
 Choose subagents when the work is read-mostly, short-lived, or you will integrate the result
 yourself. Choose Tower when the result must land on a branch under a controlled merge; enable review
@@ -245,14 +247,19 @@ Tower entry clears an active plan (or refuses entry under `mode.planModePolicy:"
 Tower session cannot use the goal/todo/team/workflow tools. Plan first, then execute; do not expect
 Tower to discover the plan for you.
 
-### 4.6 Review is optional by default
+### 4.6 The review policy is one tri-state control
 
-`review.requireReview:false` is the default, so a completed mission can merge without a reviewer for
-low-risk repositories, scratch work, or human-supervised sessions. Set it to `true` to enforce the
+The review policy is one control — `off`, `optional` (the default) or `required` — in the plugin-page
+`dsh-tower` configuration section, mirrored by `review.mode` in config. It is not a component row and
+not three mutually exclusive rows. `optional` means a completed mission can merge without a reviewer
+for low-risk repositories, scratch work, or human-supervised sessions. `required` enforces the
 independent review gate; the gate then re-checks `no-review`, `not-clean`, `review-hold`,
-`review-not-approved`, `tip-moved`, and `review-mission-mismatch`. `tower_review` is always available
-and records verdicts even when the gate is off. For one mission only, with the global gate on, set
-`reviewPolicy:"none"` + a reason and `gates.allowReviewExemption:true`.
+`review-not-approved`, `tip-moved`, and `review-mission-mismatch`. `off` is a supported mode that
+does not register `tower_review`; `optional` records verdicts but never blocks a merge. For one
+mission only, with the policy `required`, set `reviewPolicy:"none"` + a reason and
+`gates.allowReviewExemption:true`. The deprecated one-release boolean alias maps `true` → `required`
+and `false` → `optional`; see
+[install, upgrade and migration](install-upgrade-migration.md).
 
 ### 4.7 Concrete examples by workflow
 
@@ -309,8 +316,8 @@ A team wants "organization invitations": token model, email delivery, accept/dec
    `src/ui/invites/**`; make the API depend on tokens and email.
 2. Spawn workers for the independent missions; the API waits for its deps.
 3. Each worker commits on its branch, completes with checks.
-4. With `review.requireReview:true`, spawn reviewers and require a clean+merge verdict; otherwise
-   review is optional.
+4. With `review.mode:required`, spawn reviewers and require a clean+merge verdict; otherwise review
+   is optional or off.
 5. `tower_preflight` and `tower_merge` each mission; resolve scope/base/review blockers.
 6. `tower_teardown`; `MISSIONS.md` is the human-readable record.
 
@@ -344,9 +351,9 @@ Tower missions from those findings.
 ### Scenario E: sensitive release
 
 A library release with external consumers. Plan missions for the change, migration guide, and
-release notes; enable `review.requireReview:true` if the release requires independent review, require
-tests, and use `tower_batch` to close the release evidence only when all required checks are present;
-merge and tag outside Tower as your release process requires.
+release notes; set `review.mode:required` if the release requires independent review, require tests,
+and use `tower_batch` to close the release evidence only when all required checks are present; merge
+and tag outside Tower as your release process requires.
 
 ## 6. Choosing in practice: a short decision path
 
@@ -354,9 +361,9 @@ merge and tag outside Tower as your release process requires.
 2. **Would you open a PR for it?** No → Tower is too heavy; use a normal agent.
 3. **Do the slices have stable scopes and a known definition of done?** No → plan/explore first; then
    return to Tower.
-4. **Do you need a merge gate?** Repository changes with integration risk → Tower. Enable
-   `review.requireReview:true` if you also need independent review. If neither isolation nor evidence
-   is needed, plain subagents may be enough.
+4. **Do you need a merge gate?** Repository changes with integration risk → Tower. Set the review
+   policy to `required` if you also need independent review. If neither isolation nor evidence is
+   needed, plain subagents may be enough.
 5. **Do you need many parallel analyses or repeated fresh attempts?** Use Workflow/Ralph for that
    phase; encode the resulting changes as Tower missions.
 6. **Do you need cross-cutting human collaboration?** Use Agent Teams to decide; execute the decided
@@ -368,9 +375,9 @@ merge and tag outside Tower as your release process requires.
   round, gate, merge. Keep missions meaningful (roughly a PR-sized slice), not one task per function.
 - **Merges serialize**: overlapping scopes auto-add dependencies; independent missions still merge
   one at a time onto the base. Do not expect linear speedup for merge-heavy work.
-- **Review is not free when enabled**: each mission then needs a reviewer and a clean verdict.
-  `review.requireReview:false` (the default) makes review optional; when the gate is on, exemptions
-  are opt-in and require a reason.
+- **Review is not free when required**: each mission then needs a reviewer and a clean verdict.
+  `review.mode:optional` (the default) makes review non-blocking, and `off` removes the review tool;
+  when the policy is `required`, exemptions are opt-in and require a reason.
 - **Too-fine missions** increase coordination and merge cost. **Too-coarse missions** lose the benefit
   of parallel review and make scope conflicts likely.
 - **Tower is not a sandbox**: it is a coordination protocol. Host permissions, repository hooks, and
@@ -385,7 +392,7 @@ merge and tag outside Tower as your release process requires.
 - [ ] The work produces a repository change that deserves a PR-style review.
 - [ ] I can name 2–8 missions with non-overlapping scopes and a rough dependency order.
 - [ ] Each mission has a testable definition of done (tasks, checks/tests, optional review).
-- [ ] If this change needs independent review, `review.requireReview` is on (default is off).
+- [ ] If this change needs independent review, the review policy is `required` (default is `optional`).
 - [ ] I know which missions can run in parallel and which must wait.
 - [ ] I accept the merge-gate overhead (and review overhead if enabled) and will inspect
       `MISSIONS.md`/the branch.

package/docs/operations/security.md

@@ -4,15 +4,16 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 
 ## Enforced by the plugin
 
-- **Review binding (when review is enabled).** `tower_review` records the branch tip it inspected;
-  with `review.requireReview:true`, the gate rejects a moved tip (`tip-moved`) unless a clean
-  conflict-free rebase waived it. A reviewer that modifies the branch after spawning is rejected
+- **Review binding (when required).** `tower_review` records the branch tip it inspected; with
+  `review.mode:required`, the gate rejects a moved tip (`tip-moved`) unless a clean conflict-free
+  rebase waived it. A reviewer that modifies the branch after spawning is rejected
   (`reviewer must not modify the mission branch`).
-- **Review is optional by default, enforceable by config.** `review.requireReview:false` is the
-  default; set it to `true` to enforce the independent-review gate. Mission-level
-  `reviewPolicy:"none"` + reason is the narrower exemption when the global gate is on. With the gate
-  off, separation of duties is not enforced by the plugin; use it only for trusted or human-supervised
-  repositories.
+- **Review is optional by default, enforceable by the tri-state policy.** `review.mode` is `off`,
+  `optional` (the default) or `required`. Set it to `required` to enforce the independent-review gate.
+  Mission-level `reviewPolicy:"none"` + reason is the narrower exemption when the policy is required.
+  With `off`, review is intentionally unavailable; with `optional`, separation of duties is not
+  enforced by the plugin, so use it only for trusted or human-supervised repositories. The policy is
+  one control on the plugin page, not a component row.
 - **Role enforcement.** The caller is resolved against the roster. Worker mission updates are limited to
   task/blocker/note; `completed`, `abandoned`, scope widening and blocker clearing are tower-only, and
   completion (with its unread-inbox/commit gates) must go through `tower_complete`. Tower-only tools reject
@@ -84,8 +85,8 @@ intent behind that entry. What it does provide:
 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.
+set `mode.allowAgentControl:false`, keep the review policy at `review.mode:required`, review the
+repository before Tower work, and run the host under OS-level isolation.
 
 ## Not enforced by the plugin (deployment concerns)
 

package/docs/reference/blockers.md

@@ -4,6 +4,11 @@
 return the same shape for operation failures. Codes are stable; the detail is human-facing. The
 tables below define 32 stable blocker/failure codes.
 
+The review blockers below (`no-review`, `review-mission-mismatch`, `not-clean`, `review-hold`,
+`review-not-approved`, `tip-moved`, `review-exemption-invalid`) exist only when `review.mode` is
+`required`. With `off` or `optional` no review blocker is produced; `off` additionally removes
+`tower_review` and refuses reviewer spawn.
+
 ## Gate blockers (26)
 
 | Code | Meaning / next action |
@@ -19,12 +24,12 @@ tables below define 32 stable blocker/failure codes.
 | `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 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. 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). |
+| `no-review` | `review.mode:required` and no review exists on the branch: spawn a reviewer (or disable the review gate). |
+| `review-mission-mismatch` | `review.mode:required` and the latest review belongs to another mission. |
+| `not-clean` | `review.mode:required` 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.mode:required` and latest review recommends hold; a later clean review must supersede it. |
+| `review-not-approved` | `review.mode:required` and latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
+| `tip-moved` | `review.mode:required` and the branch changed after review; review again (or use a clean rebase waiver). |
 | `worker-busy` | A roster agent for this mission is running; wait or retire it. |
 | `worker-status-unknown` | The parent catalog is unavailable, so a live roster agent cannot be proven stopped; retry after the catalog recovers or adopt it. |
 | `base-wrong-branch` | The main checkout is not on the recorded base branch. |
@@ -32,7 +37,7 @@ tables below define 32 stable blocker/failure codes.
 | `worker-stale` | A roster worker for this mission has no catalog activity beyond `spawn.staleMs`; adopt it (or interrupt it only if it is actually running) before merge. |
 | `tests-missing` | `gates.requireTests` is enabled and there is no passing discovery receipt for the current branch tip; run `tower_test` or `tower_complete`. |
 | `tests-failed` | The latest discovery receipt failed or did not meet minCount/required checks. Fix the tests and re-run. |
-| `review-exemption-invalid` | `review.requireReview:true` and the mission requests `reviewPolicy:"none"` while `gates.allowReviewExemption` is off (or the reason is missing). |
+| `review-exemption-invalid` | `review.mode:required` and the mission requests `reviewPolicy:"none"` while `gates.allowReviewExemption` is off (or the reason is missing). |
 | `merge-intent-pending` | A merge intent was recorded before a crash/failure; run `tower_merge` to reconcile before another gate. |
 
 ## Merge failures (4)