dsh-tower 2.5.0 → 2.6.0

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)

package/docs/reference/component-surface.md

@@ -3,7 +3,7 @@
 > Generated by `npm run docs:generate:components` from `scripts/component-surface.json` and
 > `scripts/surface-baseline.json`. Do not edit by hand.
 
-Decision: [ADR 0005](../adr/0005-component-surface.md) · decision date: 2026-10-23 · baseline 2026-10-23 · visible components: 11 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-board`, `tower-archive`, `tower-hmr`, `preset-tower-reviewer`, `tower-ui`)
+Decision: [ADR 0005](../adr/0005-component-surface.md) · decision date: 2026-11-01 · baseline 2026-10-23 · visible components: 11 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-board`, `tower-archive`, `tower-hmr`, `preset-tower-reviewer`, `tower-ui`)
 
 The component axis answers one question for every config key: may a user turn it
 off, and if so, must that switch be a component? Four classes cover every key, so
@@ -14,7 +14,7 @@ off, and if so, must that switch be a component? Four classes cover every key, s
 | `core` | Removing it breaks the Tower contract. It is never a switch. |
 | `optional-component` | A capability whose off state leaves the rest of Tower intact. It must be a user-visible switch with a documented fallback. |
 | `optional-config` | A tuning knob, not a capability. It stays in the config form and never hides a component. |
-| `forbidden-to-disable` | The host, the health contract, the recovery escape, the review contract and the merge gates. No group, row or boolean key may turn it off. |
+| `forbidden-to-disable` | The host, the health contract, the recovery escape and the merge gates. No group, row or boolean key may turn it off. |
 
 ## Components
 
@@ -35,13 +35,18 @@ row is a section of its parent and is not independently switchable.
 | `tower-archive` | visible | row | Terminal missions are not moved out of state.json, so the hot state keeps growing and status/doctor keep loading their full history. Merges, gates and every other capability keep working; nothing is deleted. afterDays/maxMissions keep their tuning meaning. |
 | `tower-hmr` | visible | row | Development-only tooling: tower_reload and /tower reload are unavailable, so a linked-profile reload has to be triggered outside Tower. A normal profile behaves exactly as before; the row ships disabled on purpose. |
 | `preset-tower-worker` | internal | row | Declared by dsh-tower/preset-worker: tower_spawn fails without the worker preset. A mandatory dependency, never a switch. |
-| `preset-tower-reviewer` | visible | row | Declared by dsh-tower/preset-reviewer: the reviewer cannot be dispatched. Supported while review.requireReview is false (merge is unaffected); with the gate on planning/mode entry is locked with an explanatory error. |
+| `preset-tower-reviewer` | visible | row | Declared by dsh-tower/preset-reviewer: the reviewer cannot be dispatched. Supported while review.mode is off or optional (merge is unaffected; off does not use the preset at all); with review.mode required, planning/mode entry is locked with an explanatory error. |
 | `tower-ui` | visible | row | The Tower web UI plugin does not load in this profile: no Tower tool cards, composer-dock summary or status strip. Host tools, missions, state and the MISSIONS.md board are unaffected. |
 
 ## Forbidden to disable
 
-The host, the health contract, the recovery escape, the review contract and the
-merge gates are configuration or code, never switches. `npm run
+The host, the health contract, the recovery escape and the merge gates are
+configuration or code, never switches. The review gate in `required` mode is
+also non-disableable: a completed mission still needs the review evidence bound
+to the branch tip, and the exemption path stays explicit. The policy itself is
+not a never-switch — `review.mode` is the one tri-state control on the
+plugin-page config form (`off`, `optional` or `required`) — and only the gate it
+turns on in `required` mode is non-disableable. `npm run
 docs:check:components` derives the live disablers from `host/tool-registry.js`
 and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
 
@@ -50,7 +55,7 @@ and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
 | the Tower host | Without the host the plugin registers nothing; there is no off state that leaves the rest working, and no config boolean may remove it. The visible `tower` anchor is the all-off boundary, and the host section nested under it may never become its own switch. | none | none may exist |
 | tower_doctor (read-only health contract) | Diagnosis must always exist so a failure message can point at it. #122 removed exposeDoctor and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
 | tower_recover (stale state-lock escape) | The escape hatch must exist whenever the lock it repairs can be left behind. #122 removed exposeRecovery and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
-| the review contract | review.requireReview is a merge blocker, not a component; a row may not switch it off. The reviewer row is conditional, not a way to weaken the gate. | none | none may exist |
+| the review gate in required mode | The policy is one tri-state configuration control on the plugin-page form, not a component row: review.mode is off, optional (default) or required, and off is a documented mode that removes tower_review and makes the merge gate ignore review. What no group, row or boolean key may switch off is the gate once the mode is required: a completed mission still needs a clean review bound to the branch tip, and the exemption path stays explicit. review.requireReview is a deprecated one-release alias, not a switch. The reviewer preset row remains a capability the policy may leave unused, never a way to weaken required mode. | none | none may exist |
 | the merge gates | gates.* decides delivery; a component may not bypass it. | none | none may exist |
 
 ## Gateable tools
@@ -92,7 +97,8 @@ All keys from `domain/config/schema.js`, classified on the component axis.
 | `mode.storePath` | `optional-config` | Custom mode-store location; no capability is removed. |
 | `mode.maxEntries` | `optional-config` | Bounds the persisted mode store. |
 | `mode.lockTimeoutMs` | `optional-config` | Bounded wait for the cross-process mode lock. |
-| `review.requireReview` | `forbidden-to-disable` | Turns independent review into a merge blocker; no component may switch it off. With it on, the preset-tower-reviewer row may not be off (planning/mode entry refuse the combination). |
+| `review.mode` | `core` | The review policy: off, optional (default) or required, selected by one tri-state control on the plugin-page configuration form. It is configuration, not a component row and not three mutually exclusive rows. off intentionally removes tower_review, refuses reviewer spawn and makes the merge gate ignore review; optional never blocks a merge; required makes a clean tip-bound review a merge blocker. The reviewer preset row stays a capability the mode may leave unused. |
+| `review.requireReview` | `core` | Deprecated one-release boolean alias for review.mode (true -> required, false -> optional; default optional). It is policy configuration and a deprecated alias, not a switch a row may own; false never overrides an explicit mode. Kept so 2.5 configurations keep working; remove after the 2.6 alias window. |
 | `review.maxRoundsPerReviewer` | `forbidden-to-disable` | Caps review rounds; part of the review contract. |
 | `merge.timeoutMs` | `optional-config` | Default merge timeout; a per-call value wins. |
 | `merge.maxBufferBytes` | `optional-config` | Captured merge output buffer. |
@@ -135,6 +141,7 @@ hides a capability cannot use the tuning class without that record.
 
 | Key |
 |---|
+| `review.mode` |
 | `spawn.requireLease` |
 | `tests.admission` |
 

package/docs/reference/config.generated.md

@@ -1,7 +1,7 @@
 # Config reference (generated)
 
 > Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
-> Surface: config keys: 53 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
+> Surface: config keys: 54 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|
@@ -25,7 +25,8 @@
 | `mode.storePath` | `` | Directory for modes.json; defaults to $DSH_HOME/tower-mode. |
 | `mode.maxEntries` | `200` | Maximum persisted mode entries. |
 | `mode.lockTimeoutMs` | `5000` | How long saveModes waits for the cross-process modes.lock before giving up. |
-| `review.requireReview` | `false` | Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally. |
+| `review.mode` | `"optional"` | Review policy. off = review is intentionally unavailable (recording a review is refused, reviewer spawn is refused, and the merge gate ignores review; a profile-level off also does not register tower_review); optional = review is available but never blocks a merge (default); required = a clean review bound to the branch tip is a merge blocker. |
+| `review.requireReview` | `false` | Deprecated alias for review.mode (true -> required, false -> optional); prefer review.mode. true next to a non-required mode is rejected; false never overrides an explicit mode (off, optional or required). The Plugins-page control shows the alias when it is the only key and always writes review.mode with review.requireReview:false. |
 | `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per mission branch. |
 | `merge.timeoutMs` | `900000` | Default tower_merge timeout, including pre-merge hooks. |
 | `merge.maxBufferBytes` | `67108864` | Captured merge output buffer. |

package/docs/reference/config.md

@@ -27,13 +27,38 @@ win, profile keys survive when the repo does not set them. `tower_status` report
 
 ```json
 {
-  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
+  "review": { "mode": "required", "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
 }
 ```
 
+`review.mode` is the review policy: `off`, `optional` or `required`. `review.requireReview` is a
+deprecated alias kept for one release (`true` → `required`, `false` → `optional`); prefer
+`review.mode`. When both are set in the same layer, `requireReview:true` next to any mode other than
+`required` is a contradiction and is rejected with `config-invalid` naming both keys.
+`requireReview:false` never contradicts an explicit mode: `off`, `optional` and `required` all stay
+accepted and the mode wins (`required` still enforces the gate; the resolved alias is mirrored back as
+`true` only for that mode). A repository layer is resolved on its own: it may relax review, but a
+profile with `review.mode:off` never registered `tower_review`, so a repository cannot raise its own
+mode.
+
+The Plugins-page control shows the policy exactly as the runtime resolves it: `review.mode` decides
+when present, and a profile that still sets only `review.requireReview` displays Required (`true`) or
+Optional (`false`). Saving a choice always writes `review.mode` and sets `review.requireReview` to
+`false` in the same profile patch, so the alias can never contradict the selected mode.
+
+The same three choices are available on the Plugins page, in the `dsh-tower` configuration
+section: **Off**, **Optional** (the default) and **Required**, each with a one-line description of
+its effect. That control writes the profile config through the Host settings form, so the accepted
+value is reflected on the page without a manual file edit.
+
+One live change cannot rebuild the mounted tool surface: a profile that started with review off did
+not register `tower_review`. Switching to Optional or Required through the page immediately changes
+the merge gate, but the review tool itself appears only after a restart (or a profile reload); the
+control states that after such a save.
+
 The `mode.*` group is session-scoped, not repository-scoped: it is accepted in the repository file
 for schema compatibility but only the profile config controls the Tower-mode prompt and the
 model-controlled toggle. A malformed file, a non-object value, unknown top-level keys, or a value that
@@ -61,7 +86,8 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `mode.denyTools` | goal/todo/team/workflow/subagent tools | Tools refused while the mode is active (12 defaults). |
 | `mode.storePath` | `$DSH_HOME/tower-mode` | Directory for `modes.json`. |
 | `mode.maxEntries` | `200` | Maximum persisted mode entries (1–2000). |
-| `review.requireReview` | `false` | Enforce an independent clean review before merge. Default `false` (review optional); set `true` to require `no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch` checks. `tower_review` remains available either way. |
+| `review.mode` | `optional` | Review policy. `off` = review is intentionally unavailable: recording a review is refused, `tower_spawn` refuses the reviewer role, the merge gate ignores review, and a profile-level `off` does not register `tower_review` (a repository-level `off` refuses the submission instead); `optional` = review is available but never blocks a merge (default); `required` = a clean review bound to the branch tip is a merge blocker (`no-review`/`not-clean`/`review-hold`/`review-not-approved`/`tip-moved`/`review-mission-mismatch`). |
+| `review.requireReview` | `false` | Deprecated alias for `review.mode`: `true` → `required`, `false` → `optional`. Prefer `review.mode`. `true` next to a non-`required` `review.mode` is rejected with `config-invalid` naming both keys; `false` is accepted next to any explicit `review.mode` (`off`/`optional`/`required`) and never overrides it. The Plugins-page control shows the alias when it is the only key and always writes `review.mode` with `review.requireReview:false`. |
 | `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per branch. |
 | `merge.timeoutMs` | `900000` (15 min) | Default `tower_merge` timeout, including hooks. A per-call `timeoutMs` wins. |
 | `merge.maxBufferBytes` | `67108864` (64 MB) | Merge output buffer. |
@@ -86,7 +112,7 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `tests.allowPackageDiscovery` | `true` | Allow repo-controlled `tower.testDiscovery` commands (executes worktree code; see security). |
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
 | `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. With the `tower-tests` component row off, planning/mode entry refuse this combination with an explanation. |
-| `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
+| `gates.allowReviewExemption` | `false` | With `review.mode:required`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant when `review.mode` is `off` or `optional` (no review blocker is produced). |
 | `gates.maxReportBytes` | `32768` (32 KiB) | Hard cap in UTF-8 bytes for `tower_complete.report`. A larger report is rejected with `invalid-argument` and an actionable `nextAction` (file the full text in the mission worktree and reference its path); it is never truncated. Existing larger reports still load. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. Whether the board is written at all is the `tower-board` component row (#133); `docs.board` was removed and is rejected as an unknown key. |
 | `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). Archival itself is the `tower-archive` component row (#135); `archive.enabled` was removed and is rejected as an unknown key. |

package/docs/reference/errors.generated.md

@@ -29,6 +29,7 @@ single recovery step appended to the message as ` — next: …` (with ` (retrya
 | `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. | yes | wait for the cooldown to expire, then retry |
 | `preset-missing` | The configured agent preset is not registered. | no | install the tower-worker and tower-reviewer agent presets and restart DSH |
 | `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | no | complete the mission first, then spawn the reviewer |
+| `review-disabled` | Review is disabled by `review.mode:off`; no reviewer, verdict, or review blocker exists in this configuration. | no | set review.mode to optional or required in the Tower config, then retry |
 | `not-authorized` | The calling agent role may not perform this action. | no | call the tool as the tower, or as the worker/reviewer it is assigned to |
 | `workspace-busy` | Another Tower session owns this repository workspace lock. | yes | run /tower off in the other session or wait for its lock to become stale |
 | `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. | no | wait for a live worker to finish or raise spawn.maxLiveWorkers |

package/docs/reference/errors.md

@@ -2,7 +2,7 @@
 
 Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
 [blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
-release defines 35 tool error codes.
+release defines 36 tool error codes.
 
 Every `TowerToolError` carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
 (structured context or `null`) for programmatic callers. The model-visible surface is the message:
@@ -43,6 +43,7 @@ plain `Error` without a structured code is reported as `tool-internal`.
 | `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. | yes | wait for the cooldown to expire, then retry | repeated retryable provider failures; wait for `blockedUntil` |
 | `preset-missing` | The configured agent preset is not registered. | no | install the tower-worker and tower-reviewer agent presets and restart DSH | missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted |
 | `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | no | complete the mission first, then spawn the reviewer | reviewer spawned before the mission is `completed`, or before a worktree exists |
+| `review-disabled` | Review is disabled by `review.mode:off`; no reviewer, verdict, or review blocker exists in this configuration. | no | set review.mode to optional or required in the Tower config, then retry | `tower_spawn` with `role:"reviewer"`, or a review submission, while `review.mode` is `off` |
 | `not-authorized` | The calling agent role may not perform this action. | no | call the tool as the tower, or as the worker/reviewer it is assigned to | a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings |
 | `workspace-busy` | Another Tower session owns this repository workspace lock. | yes | run /tower off in the other session or wait for its lock to become stale | `mode.workspaceLock:true` and a second session calls a repo-scoped tool |
 | `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. | no | wait for a live worker to finish or raise spawn.maxLiveWorkers | spawning a fifth worker with the default limit |

package/docs/reference/surface-budget.md

@@ -65,8 +65,24 @@ config-key count is two-way: a later increase **or** decrease needs its own
 decision naming an ADR, unlike sections and tools. The same wave makes the gate
 import `OPERATIONAL_TOOLS` instead of scraping it, discover every shipped
 `cordis.patch.yml` in both directions, review the non-boolean behaviour knobs
-(`spawn.requireLease`, `tests.admission`), and refuse a row config outside its
-component's `allowedOverrides`.
+(`spawn.requireLease`, `tests.admission`, and now `review.mode`), and refuse a row
+config outside its component's `allowedOverrides`.
+
+#M39 grew the config surface by exactly one, 53 → 54: `review.mode`
+(`off`/`optional`/`required`) is the review policy, and the deprecated
+`review.requireReview` boolean stays accepted for one release as a normalized
+alias. It is not a fifth component row: `preset-tower-reviewer` remains a
+capability row and `review.mode:off` simply leaves it unused (no `tower_review`,
+no reviewer spawn, no review blockers). The dated decision records both the new
+key and why the old boolean was not removed in the same release.
+
+#M42 reclassifies the deprecated alias from `forbidden-to-disable` to `core` in
+the component surface: it is policy configuration and a compatibility alias, not
+a capability a row may switch. The policy is one tri-state control on the
+plugin-page form, not a row and not one row per mode; the review gate in
+`required` mode, its tip-bound evidence and the exemption path remain
+non-disableable. The component and config-key counts do not move (11 visible
+components, 54 keys).
 
 ## Config keys
 
@@ -92,7 +108,8 @@ component's `allowedOverrides`.
 | `mode.storePath` | niche | Custom mode-store location added for one deployment workflow. Removal note: derive the path from `$DSH_HOME` in the next minor; no in-tree caller sets this key. |
 | `mode.maxEntries` | tuning | Bounds the persisted mode store. |
 | `mode.lockTimeoutMs` | tuning | Bounded wait for the cross-process mode lock. |
-| `review.requireReview` | core | Turns the review gate into a merge blocker. |
+| `review.mode` | core | The review policy itself (`off`/`optional`/`required`); it replaces the deprecated boolean as the single gate switch. |
+| `review.requireReview` | core | Deprecated alias for `review.mode` (`true` → `required`, `false` → `optional`); retained for one release. |
 | `review.maxRoundsPerReviewer` | core | Caps review rounds; changes the review lifecycle. |
 | `merge.timeoutMs` | tuning | Default merge timeout; a per-call value wins. |
 | `merge.maxBufferBytes` | tuning | Captured merge output buffer. |

package/docs/reference/testing.md

@@ -51,7 +51,7 @@ discovery fails.
 - `tower_complete` adds a `tests` check when `tests.autoChecks` is on.
 - `gates.requireChecks` requires any completion check; `gates.requireTests` requires a passing receipt
   for the current mission branch tip (`tests-missing`). Review is independent of this gate: with
-  `review.requireReview:false` the tests gate still checks the branch tip.
+  `review.mode:optional` (the default) or `off`, the tests gate still checks the branch tip.
 
 ## Trust boundary
 

package/docs/reference/tools.generated.md

@@ -1,7 +1,7 @@
 # Tools overview (generated)
 
 > Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
-> Surface: config keys: 53 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
+> Surface: config keys: 54 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Tool | Description |
 |---|---|
@@ -22,15 +22,15 @@
 | `tower_mission` | Update one mission: lifecycle status, decision note, blocker, clear blockers, mark a task done, drop a task with a reason, or widen the scope (tower only). "merged" is never set here; only a future tower_merge records it. Merged and abandoned are terminal. |
 | `tower_mode` | Report whether Tower mode is active for the calling agent, who changed it last, whether the model may toggle it, any goal paused on entry, the workspace lock, HMR availability and the plugin version. |
 | `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. |
-| `tower_preflight` | Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything. |
+| `tower_preflight` | Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.mode is required; review.mode off and optional skip them. Never changes anything. |
 | `tower_rebase` | Rebase a mission branch onto the current base tip inside its own worktree. Refuses while its worker is running or the worktree is dirty. A clean conflict-free rebase waives re-review for the old review; a conflict is aborted and the mission is marked blocked. If the branch is already contained in the base, it returns alreadyMerged and leaves the branch untouched so tower_merge can record the landed merge. |
 | `tower_recover` | Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner with its age, heartbeat age and staleness; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. force:true additionally clears a live-but-silent PID (a recycled PID) and still renames the record to a .recovered-<ts> backup. It never resets Tower state or worktrees. |
 | `tower_reload` | Dev-only: ask DSH HMR to reconcile this profile and reload the Tower Host plugin from disk. Registered only while the tower-hmr component is on (the row is shipped off). The reload is scheduled a few milliseconds after this call returns (so the result reaches the model first). Use after editing the plugin source in a linked profile; plugin_manager install/update already triggers reconciliation by itself. Fails with reload-unavailable when the HMR service is absent. |
 | `tower_resource` | Advisory resource leases per repository (coordination only; no OS CPU/memory hard cap). acquire/release require a token and are tower-only; status is read-only. Expired leases are never taken over silently. |
-| `tower_review` | Submit an independent review verdict bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason. |
+| `tower_review` | Submit an independent review verdict bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason. The tool is not registered when review.mode is off. |
 | `tower_roster` | List tower roster agents with authoritative live activity from the subagent catalog (running/inactive/missing/unknown). Read-only; never resumes children. Use before completion or merge decisions. |
 | `tower_send` | Send a durable inbox message to a tower participant: a roster agent name, "tower", or "all" (broadcast). The message is persisted first; when the recipient is a currently running roster agent the tower also steers it into that child's current turn. Returns delivery results. |
-| `tower_spawn` | Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true. |
-| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, archive count, config path and the activity tail. Also reports the repo-scoped git lock holder (`gitLock: {held,pid,phase,heldMs}`) so a merge holding the mutex is visible. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only. |
+| `tower_spawn` | Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset, and the reviewer role is refused when review.mode is off. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true. |
+| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, archive count, config path and the activity tail. Also reports the repo-scoped git lock holder (`gitLock: {held,pid,phase,heldMs}`) so a merge holding the mutex is visible, and the resolved review policy (`review: {mode, available, required, detail}`; mode off means review is intentionally unavailable). Pass missionId for one full mission (tasks, notes, reviews, findings, completion report; archived missions are loaded from their year file); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; includeArchived appends compact archived summaries after the active page; format:"markdown" returns the human-readable mission board (active missions plus an archived count). Read-only. |
 | `tower_teardown` | Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything. Terminal missions whose worktree is gone and whose configured archive policy is due (archive.afterDays / archive.maxMissions) are moved to <git-common-dir>/dsh-tower/archive/ so state.json stops rewriting them; nothing is deleted. |
 | `tower_test` | Run the mission worktree's declared tower.testDiscovery (package.json) and record the receipt. Returns ok:false with diagnostics when discovery fails; does not change mission status. Use tower_complete for automatic admission checks. |

package/docs/reference/tools.md

@@ -38,7 +38,7 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `tower_plan` | `missions[]` (`title` — printable Unicode, NFC-normalized, ≤120 characters, `scope[]`, `tasks[]?`, `deps[]?`, `kind?`, `context?`, `references[]?` ≤20, `reviewPolicy?`, `reviewExemptionReason?`) | Create missions `M1..`; overlapping build scopes auto-add a dependency; rejects unknown deps and cycles. Mission ids stay ASCII (`M1`, `M2`); invisible characters and over-long titles are rejected with `invalid-argument`. `reviewPolicy:"none"` requires a non-empty reason; when the review gate is on, preflight also requires `gates.allowReviewExemption`. |
 | `tower_mission` | `id` (alias `missionId`), `status?`, `task_done?`, `task_drop?`+`task_drop_reason?`, `blocker?`, `clear_blockers?`, `note?`, `scope?`, `pause_cause?`, `authorization?` | Update one mission. Worker-safe fields are task/blocker/note; `merged` cannot be set here. Paused missions record `pause_cause` (user/failure/resource/dependency); resuming a user-paused mission honors `mode.requireResumeAuthorization`. |
 \|\ `tower_status`\ \|\ `missionId\?`,\ `offset\?`,\ `limit\?`,\ `includeGate\?`,\ `includeArchived\?`,\ `format\?`\ \|\ Dashboard\ by\ default\.\ Paged\ missions\ carry\ `reportBytes`\ only;\ `missionId`\ returns\ full\ detail\ \(tasks/notes/reviews/findings/completionReport\ body\),\ and\ an\ archived\ mission\ is\ loaded\ from\ its\ year\ file\.\ `offset`/`limit`\ page\ active\ missions\ \(default\ 20,\ max\ 100\),\ `includeGate`\ adds\ gate\ digests,\ `includeArchived`\ appends\ compact\ archived\ summaries\ \(flagged\ `archived:true`,\ no\ report\ body\)\ after\ the\ active\ page,\ and\ `format:"markdown"`\ returns\ the\ board\ \(active\ rows\ plus\ an\ archived\ count\)\.\ Includes\ `mode`\ with\ `lastChange`\ and\ recent\ `history`\ when\ the\ host\ mode\ hook\ is\ available\.\ `archive`\ reports\ `\{count,\ years,\ unreadable,\ message}`;\ a\ corrupt\ archive\ degrades\ to\ `unreadable:true`\ instead\ of\ failing\ the\ dashboard\.\ Also\ returns\ `gitLock`\ \(`\{held,\ pid,\ phase,\ heldMs}`\)\ for\ the\ repo-scoped\ git\ mutex,\ and\ `\{held:\ false}`\ when\ it\ is\ free\.\ \|
-| `tower_spawn` | `missionId` (alias `id`), `role` (`worker`/`reviewer`), `name?`, `instructions?`, `worktreeRoot?`, `wait?`, `waitMs?`, `takeover?`, `includeDirtyBase?` | Provision/reuse the worktree and start a subagent. Worker uses `tower-worker`; reviewer requires a `completed` mission and uses the read-only `tower-reviewer`. `takeover:true` replaces a live worker entry that is no longer running (increments ownerGeneration). Only one live worker per mission; `spawn.maxLiveWorkers` caps the repository. |
+| `tower_spawn` | `missionId` (alias `id`), `role` (`worker`/`reviewer`), `name?`, `instructions?`, `worktreeRoot?`, `wait?`, `waitMs?`, `takeover?`, `includeDirtyBase?` | Provision/reuse the worktree and start a subagent. Worker uses `tower-worker`; reviewer requires a `completed` mission and uses the read-only `tower-reviewer`; with `review.mode:off` the reviewer role is refused with `[tower:review-disabled]`. `takeover:true` replaces a live worker entry that is no longer running (increments ownerGeneration). Only one live worker per mission; `spawn.maxLiveWorkers` caps the repository. |
 | `tower_roster` | — | Roster with live activity (`running`/`inactive`/`missing`/`unknown`) and `stale` flags from the subagent catalog. Read-only. |
 | `tower_adopt` | `retireMissing?` | Reconcile roster entries with the durable subagent catalog. Provably gone agents are retired (default) or marked `missing` (`retireMissing:false`) so they can be inspected/taken over. |
 | `tower_diff` | `missionId` (alias `id`), `maxBytes?` | Read-only merge-base diff: files, commits, capped patch. Safe for reviewers. |
@@ -48,8 +48,8 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `tower_interrupt` | `to?` (roster name), `agentId?`, `reason?` | Interrupt one running roster agent via `subagents.interrupt`, record `state:"interrupted"`. Idempotent (not running → `interrupted:false`). |
 | `tower_finding` | `type`, `title`, `summary`, `details`, `suggested_fix`, `severity?`, `missionId?`, `location?` | Record an out-of-scope issue; reviewers use this instead of editing. Finds start as `open`. |
 | `tower_findings` | `id?`, `status?`, `note?`, filters (`type?`, `severity?`, `missionId?`, `open?`, `limit?`) | Lifecycle tool: list/read/transition. Statuses `open → triaged → fixed`/`wontfix`, reopen allowed. Only the tower or a worker may mutate; a reviewer can list/read. |
-| `tower_review` | `missionId` (alias `id`), `status` (`clean`/`p1-Nitems`/`p2-Nitems`), `merge` (`merge`/`fix-then-merge`/`hold`), `findings`, `decision`, `checks?`, `breakGlassReason?` | Reviewer verdict bound to the current tip. Reviewer must be the assigned reviewer (or tower break-glass). A later route may record a verdict for the same reviewed tip while the mission is active: it appends to that round (`appended:true`) without changing the status; a verdict for a moved tip is rejected with an explanation. |
-| `tower_preflight` | `missionId` (alias `id`) | Read-only gate: returns `{ok, blockers[], branchTip, baseTip, changedFiles, review}`. |
+| `tower_review` | `missionId` (alias `id`), `status` (`clean`/`p1-Nitems`/`p2-Nitems`), `merge` (`merge`/`fix-then-merge`/`hold`), `findings`, `decision`, `checks?`, `breakGlassReason?` | Reviewer verdict bound to the current tip. Reviewer must be the assigned reviewer (or tower break-glass). Not registered when `review.mode:off`; a repository-level `off` refuses the submission with `[tower:review-disabled]`. A later route may record a verdict for the same reviewed tip while the mission is active: it appends to that round (`appended:true`) without changing the status; a verdict for a moved tip is rejected with an explanation. |
+| `tower_preflight` | `missionId` (alias `id`) | Read-only gate: returns `{ok, blockers[], branchTip, baseTip, changedFiles, review}`. Review blockers appear only with `review.mode:required`; `off`/`optional` skip them. |
 | `tower_merge` | `missionId` (alias `id`), `timeoutMs?` (alias `timeout_ms`) | Merge after a green gate. Records already-landed merges (`reconciled`), recovers a failed call whose commit exists (`recoveredFromFailure`), and separates `merge-hook-failed` from `merge-conflict`. |
 | `tower_rebase` | `missionId` (alias `id`) | Rebase the branch onto the base in its worktree. Refuses while the worker runs or the worktree is dirty. Already-contained branches return `alreadyMerged` untouched. |
 | `tower_teardown` | `force?`, `exclude?`, `dry_run?` (alias `dryRun`) | Remove eligible merged/abandoned worktrees and branches; running agents are always kept. The final pass applies the `archive` policy while the `tower-archive` component row is mounted: terminal missions whose worktree is gone are moved to `<git-common-dir>/dsh-tower/archive/` once `archive.afterDays`/`archive.maxMissions` says so, and `archived` lists their ids. Nothing is deleted; `archive.afterDays:0` archives a just-torn-down mission immediately. |

package/docs/zh/faq.md

@@ -12,8 +12,8 @@
 分析与决策，再启动 Tower 执行（可选审查）仓库变更。详见[完整指南](guide/scenarios-and-philosophy.md#4-tower-与其他-dsh-工作流模式的区别)。
 
 **为什么 worker 刚完成，`tower_preflight` 就因 `no-review` 失败？**
-只有在 `review.requireReview:true` 开启时才会如此：已完成的 mission 在等待独立审查。spawn 一个
-reviewer；干净审查后门禁就会变绿。默认 `review.requireReview:false` 时审查可选，不会产生
+只有在审查策略为 `required`（`review.mode:required`）时才会如此：已完成的 mission 在等待独立审查。
+spawn 一个 reviewer；干净审查后门禁就会变绿。默认 `review.mode:optional` 时审查可选，不会产生
 `no-review` blocker。
 
 **需要轮询 worker 吗？**
@@ -35,9 +35,11 @@ reviewer；干净审查后门禁就会变绿。默认 `review.requireReview:fals
 正确：分支已经包含在基线中。此时调用 `tower_merge` 记录已落地的合并，而不是 rebase。
 
 **可以要求强制独立审查吗？**
-可以。在 profile 或仓库配置中设 `review.requireReview:true` 可开启全局审查门禁（默认 `false`，
-即审查可选）。开启后可用 mission 级 `reviewPolicy:"none"` + 理由 + `gates.allowReviewExemption:true`
-做更窄的豁免。`tower_review` 始终可用并记录结论。
+可以。把审查策略设为 `required` —— 插件页上的一个三态控件，或在 profile/仓库配置中写
+`review.mode:required`（默认 `optional`）。策略为 `required` 时，可用 mission 级
+`reviewPolicy:"none"` + 理由 + `gates.allowReviewExemption:true` 做更窄的豁免。`optional` 模式下
+`tower_review` 同样可用并记录结论。旧布尔开关是已弃用、保留一个版本的别名；映射关系见
+[安装、升级与迁移](guide/install-upgrade-migration.md)。
 
 **reviewer 能修改文件吗？**
 不能。reviewer 使用只读的 `tower-reviewer` preset（没有 write/edit/pwsh）；reviewer spawn 之后分支