dsh-tower 2.5.0 → 2.6.0

package/client.js

@@ -0,0 +1,321 @@
+// dsh-tower — core Web Client half.
+//
+// The Host half of the bundle declares the profile config schema; this module
+// adds the one editable control the Plugins page needs: a section in the
+// `plugins.bundle.config` keyed slot for the `dsh-tower` bundle. The section is
+// a single three-option radio group (off / optional / required) rendered from
+// the Host-owned settings form. There is deliberately no component row for the
+// review policy: rows are on/off capabilities, while the policy is one value
+// with three states.
+//
+// Saving goes through `ctx.configForms.get('tower-host')` (the Host entry id in
+// cordis.patch.yml). One `mutate([...])` call writes both review keys:
+// `review.mode` becomes the selected value and the deprecated scalar alias
+// `review.requireReview` is normalized to `false`, so the stored profile patch
+// can never contain a contradiction. The Host schema marks both keys volatile, so
+// the accepted values are reflected in place without reloading the plugin.
+//
+// The displayed selection is the *resolved* policy, not just `review.mode`: the
+// alias decides when `mode` is absent, exactly like `resolveReviewPolicy` in
+// domain/integration/review.js.
+//
+// No build step, no new dependency, no Host/Client package imports: React comes
+// from the browser module table and theme colors use `--dsw-alias-*` tokens.
+window.__ModuleLoader__.load({
+  id: 'dsh-tower',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const NS = 'dsh-tower'
+    const HOST_ENTRY = 'tower-host'
+    const MODES = ['off', 'optional', 'required']
+    const DEFAULT_MODE = 'optional'
+
+    const EN = {
+      'config.title': 'Review policy',
+      'config.intro': 'Choose how Tower treats review for this profile. This choice is saved immediately.',
+      'config.current': 'Current choice: {mode}',
+      'config.loading': 'Loading the saved review policy…',
+      'config.unavailable': 'The review policy cannot be changed here right now. Try again later, or open the Tower host settings.',
+      'config.readonly': 'This review policy is read-only in the current profile.',
+      'config.saving': 'Saving…',
+      'config.saved': 'Saved.',
+      'config.saveFailed': 'The new choice could not be saved; the previous policy is still in effect.',
+      'config.off.label': 'Off',
+      'config.off.description': 'Review is unavailable: no review can be recorded, and merges never wait for one.',
+      'config.optional.label': 'Optional',
+      'config.optional.description': 'Review is available, but it never blocks a merge.',
+      'config.required.label': 'Required',
+      'config.required.description': 'A clean review at the branch tip blocks merge; the reviewer preset is required.',
+      'config.restartHint':
+        'This profile started with review off, so the merge gate already uses the new choice but the review tool appears only after a restart (or a profile reload).',
+    }
+
+    const ZH = {
+      'config.title': '审查策略',
+      'config.intro': '选择 Tower 为此配置处理审查的方式，选择后会立即保存。',
+      'config.current': '当前选择：{mode}',
+      'config.loading': '正在加载已保存的审查策略…',
+      'config.unavailable': '暂时无法在此修改审查策略，请稍后再试，或打开 Tower 主机设置。',
+      'config.readonly': '当前配置下审查策略为只读。',
+      'config.saving': '正在保存…',
+      'config.saved': '已保存。',
+      'config.saveFailed': '新选择未能保存，仍使用之前的审查策略。',
+      'config.off.label': '关闭',
+      'config.off.description': '审查不可用：无法记录审查，合并也不会等待审查。',
+      'config.optional.label': '可选',
+      'config.optional.description': '审查可用，但不会阻止合并。',
+      'config.required.label': '必需',
+      'config.required.description': '分支末端的干净审查会阻止合并；需要审查代理预设。',
+      'config.restartHint':
+        '此配置启动时审查为关闭状态：合并门禁已使用新的选择，但审查工具需要重启（或重新加载配置）后才会出现。',
+    }
+
+    function fill(text, params) {
+      return String(text ?? '').replace(/\{([A-Za-z0-9_]+)\}/g, (match, key) =>
+        params && params[key] !== undefined ? String(params[key]) : match,
+      )
+    }
+
+    function makeT(props) {
+      const seat = props && typeof props.t === 'function' ? props.t : null
+      return function t(key, params) {
+        if (seat) {
+          try {
+            const value = seat(key, params)
+            if (typeof value === 'string') return value
+          } catch {
+            /* fall back to the bundled English dictionary */
+          }
+        }
+        return fill(EN[key] !== undefined ? EN[key] : key, params)
+      }
+    }
+
+    function readForm(props) {
+      return props && props.form && typeof props.form.getSnapshot === 'function' ? props.form : null
+    }
+
+    function safeSnapshot(form) {
+      if (!form) return null
+      try {
+        return form.getSnapshot() ?? null
+      } catch {
+        return null
+      }
+    }
+
+    // The resolved policy: an explicit `mode` wins; otherwise the deprecated
+    // boolean alias decides (true -> required, false -> optional), like
+    // `resolveReviewPolicy`. Only a literal `true` can raise the mode, which is
+    // also the only value the resolver accepts beside a non-required mode.
+    function currentMode(snapshot) {
+      const review = (snapshot && snapshot.value && snapshot.value.review) || {}
+      if (MODES.includes(review.mode)) return review.mode
+      return review.requireReview === true ? 'required' : DEFAULT_MODE
+    }
+
+    // Both review keys are written together: the selected mode, plus the alias
+    // normalized to `false`. An explicit `false` is required — leaving the key
+    // unset would restore the inherited default, and a stale `true` would
+    // contradict a non-required mode and make `resolveTowerConfig` throw.
+    function reviewOps(mode) {
+      return [
+        { op: 'set', path: ['review', 'mode'], value: mode },
+        { op: 'set', path: ['review', 'requireReview'], value: false },
+      ]
+    }
+
+    function ReviewPolicySection(props) {
+      const t = makeT(props)
+      const form = readForm(props)
+      const [snapshot, setSnapshot] = React.useState(function () {
+        return safeSnapshot(form)
+      })
+      const [pending, setPending] = React.useState(null)
+      const [notice, setNotice] = React.useState(null)
+      // The policy this page first saw. A session whose profile started with
+      // review off never registered the review tool, so switching to
+      // optional/required takes effect at the merge gate immediately but needs a
+      // restart (or profile reload) before the tool exists. The control states
+      // that limitation instead of pretending the tool appeared.
+      const startMode = React.useRef(null)
+
+      React.useEffect(
+        function () {
+          if (!form) return undefined
+          const update = function () {
+            const next = safeSnapshot(form)
+            if (startMode.current === null && next && next.status === 'ready') {
+              startMode.current = currentMode(next)
+            }
+            setSnapshot(next)
+          }
+          update()
+          let unsubscribe
+          try {
+            unsubscribe = form.subscribe(update)
+          } catch {
+            unsubscribe = undefined
+          }
+          return function () {
+            if (typeof unsubscribe === 'function') unsubscribe()
+          }
+        },
+        [form],
+      )
+
+      const status = snapshot && typeof snapshot.status === 'string' ? snapshot.status : 'unavailable'
+      const writable = status === 'ready' && snapshot.writable !== false
+      const selection = currentMode(snapshot)
+      const restartNeeded = notice === 'saved' && startMode.current === 'off' && selection !== 'off'
+
+      function choose(next) {
+        if (!form || !writable || pending || next === selection) return
+        setPending(next)
+        setNotice(null)
+        let result
+        try {
+          result = form.mutate(reviewOps(next), snapshot ? snapshot.revision : undefined)
+        } catch {
+          setPending(null)
+          setNotice('saveFailed')
+          return
+        }
+        Promise.resolve(result).then(
+          function (accepted) {
+            setPending(null)
+            setSnapshot(safeSnapshot(form))
+            setNotice(accepted === false ? 'saveFailed' : 'saved')
+          },
+          function () {
+            setPending(null)
+            setSnapshot(safeSnapshot(form))
+            setNotice('saveFailed')
+          },
+        )
+      }
+
+      const statusText =
+        status === 'loading'
+          ? t('config.loading')
+          : status !== 'ready'
+            ? t('config.unavailable')
+            : snapshot && snapshot.writable === false
+              ? t('config.readonly')
+              : ''
+
+      return h(
+        'section',
+        {
+          'data-dsh-tower-review-policy': '',
+          style: {
+            display: 'grid',
+            gap: '10px',
+            padding: '16px',
+            border: '1px solid var(--dsw-alias-border-l2)',
+            borderRadius: '8px',
+            background: 'var(--dsw-alias-bg-module-platform)',
+          },
+        },
+        h('div', { style: { color: 'var(--dsw-alias-label-primary)', fontWeight: 600 } }, t('config.title')),
+        h('p', { style: { margin: 0, color: 'var(--dsw-alias-label-secondary)', fontSize: '13px' } }, t('config.intro')),
+        h(
+          'div',
+          {
+            role: 'radiogroup',
+            'aria-label': t('config.title'),
+            style: { display: 'grid', gap: '8px' },
+          },
+          MODES.map(function (mode) {
+            const active = selection === mode
+            return h(
+              'label',
+              {
+                key: mode,
+                'data-mode': mode,
+                style: {
+                  display: 'grid',
+                  gridTemplateColumns: 'auto 1fr',
+                  gap: '8px',
+                  alignItems: 'start',
+                  padding: '8px',
+                  borderRadius: '6px',
+                  cursor: writable && !pending ? 'pointer' : 'default',
+                  border: active ? '1px solid var(--dsw-alias-label-primary)' : '1px solid var(--dsw-alias-border-l2)',
+                },
+              },
+              h('input', {
+                type: 'radio',
+                name: 'dsh-tower-review-policy',
+                value: mode,
+                checked: active,
+                disabled: !writable || Boolean(pending),
+                onChange: function () {
+                  choose(mode)
+                },
+              }),
+              h(
+                'span',
+                { style: { display: 'grid', gap: '2px' } },
+                h('span', { style: { color: 'var(--dsw-alias-label-primary)', fontWeight: 500 } }, t(`config.${mode}.label`)),
+                h('span', { style: { color: 'var(--dsw-alias-label-secondary)', fontSize: '13px' } }, t(`config.${mode}.description`)),
+              ),
+            )
+          }),
+        ),
+        statusText
+          ? h('p', { style: { margin: 0, color: 'var(--dsw-alias-label-secondary)', fontSize: '13px' } }, statusText)
+          : null,
+        h(
+          'p',
+          {
+            role: 'status',
+            'aria-live': 'polite',
+            style: { margin: 0, color: 'var(--dsw-alias-label-secondary)', fontSize: '13px', minHeight: '18px' },
+          },
+          pending ? t('config.saving') : notice ? t(`config.${notice}`) : t('config.current', { mode: t(`config.${selection}.label`) }),
+        ),
+        restartNeeded
+          ? h(
+              'p',
+              {
+                'data-dsh-tower-restart-hint': '',
+                style: { margin: 0, color: 'var(--dsw-alias-label-secondary)', fontSize: '13px' },
+              },
+              t('config.restartHint'),
+            )
+          : null,
+      )
+    }
+
+    return {
+      inject: ['slots', 'locale'],
+      async apply(ctx) {
+        ctx.effect(function () {
+          return ctx.locale.register(NS, { en: EN, zh: ZH })
+        }, 'dsh-tower: review policy settings')
+        ctx.slots.inject('plugins.bundle.config', function () {
+          return ctx.slots.register(
+            {
+              name: 'plugins.bundle.config',
+              key: 'dsh-tower',
+              locale: NS,
+              inject: function () {
+                let forms
+                try {
+                  forms = typeof ctx.get === 'function' ? ctx.get('configForms') : undefined
+                } catch {
+                  forms = undefined
+                }
+                const form = forms && typeof forms.get === 'function' ? forms.get(HOST_ENTRY) : undefined
+                return { form }
+              },
+            },
+            ReviewPolicySection,
+          )
+        })
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -85,9 +85,11 @@
     - id: tower-hmr
       name: 'dsh-tower/hmr'
       disabled: true
-    # Conditional optional component: off is supported only while
-    # review.requireReview is false; with the gate on planning/mode entry refuse
-    # the combination with an explanatory error.
+    # Optional capability row, usable while the review policy (`review.mode`) is
+    # off or optional. With `review.mode:required`, planning/mode entry refuse this
+    # row being off with an explanatory error. The row is not mutually exclusive
+    # with the policy: the policy is one tri-state control on the plugin page,
+    # not a component row.
     - id: preset-tower-reviewer
       name: 'dsh-tower/preset-reviewer'
       config:

package/docs/adr/0005-component-surface.md

@@ -42,14 +42,17 @@ Adopt this shape and record it as principle 11:
   a documented fallback stating what still works while it is off. A capability
   qualifies only when its off state leaves the rest of Tower intact and is not
   worse than uninstalling.
-- **The safety nets are never switches.** The health contract, the recovery
-  escape, the review contract and the merge gates are configuration or code; no
-  group, row or boolean key may gate them. Enforcement covers both routes: a
-  `cordis.patch.yml` row that defaults any key classified `forbidden-to-disable`
-  to `false` is refused, and every `tools.expose*` route in
-  `host/tool-registry.js` must match the `gateableTools` allowlist in the source
-  of truth, so a new route to a review, merge or host tool fails even when that
-  capability lists no tools of its own.
+- **The safety nets are never switches.** The health contract, the recovery escape
+  and the merge gates are configuration or code; no group, row or boolean key may
+  gate them. The review policy is configuration too — one tri-state control
+  (`off`/`optional`/`required`) on the plugin-page form, not a component row and
+  never one row per mode — while the review gate in required mode (clean,
+  tip-bound evidence and the exemption path) is contract and cannot be switched
+  off by a row. Enforcement covers both routes: a `cordis.patch.yml` row that
+  defaults any key classified `forbidden-to-disable` to `false` is refused, and
+  every `tools.expose*` route in `host/tool-registry.js` must match the
+  `gateableTools` allowlist in the source of truth, so a new route to a review,
+  merge or host tool fails even when that capability lists no tools of its own.
 - **Config keys stay on the component axis.** Every config key is classified
   `core`, `optional-component`, `optional-config` or `forbidden-to-disable` in
   `docs/reference/component-surface.md`, generated from the single source of
@@ -80,9 +83,10 @@ The one `tower-bundle` group is gone. `cordis.patch.yml` now ships the mandatory
 `tower` host anchor (the Host plugin and the worker preset are its internal
 sections) plus the 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 visible component count moved 1 → 8 and is recorded
-as a dated decision in `scripts/surface-baseline.json`.
+(shipped off) and `preset-tower-reviewer` (conditional on the review policy;
+today the reviewer row may be off unless `review.mode` is `required`). The
+visible component count moved 1 → 8 and is recorded as a dated decision in
+`scripts/surface-baseline.json`.
 
 The capability switches became rows: the seven `tools.expose*` keys and
 `dev.hotReload` were deleted from the schema and are now rejected as unknown
@@ -235,8 +239,9 @@ keys, 11 visible components.
 - Decisions: #137
 
 Wave 3 made the gate fail closed, but every label it admitted still passed. The
-plugin page leaked config keys (`gates.requireTests:true`, `review.requireReview`)
-and bare tool ids (`tower_batch`, `tower_resource`) into the off-state copy, the
+plugin page leaked config keys (`gates.requireTests:true`, the deprecated
+`review.requireReview` alias) and bare tool ids (`tower_batch`, `tower_resource`)
+into the off-state copy, the
 Chinese copy mixed 咨询式租约 / 重型工作 / untranslated `mission` and `preset`, and
 the Web UI used 任务线 while the plugin page left `mission` in English. The counts
 do not move: 53 config keys, 13 components, 11 visible.
@@ -294,3 +299,43 @@ do not move: 53 config keys, 13 components, 11 visible.
   `scripts/component-surface.json` and the generated
   `docs/reference/component-surface.md` is an operator reference for auditors, not
   a plugin-page label. It may name keys and tools; the locale fields may not.
+
+## Addendum (wave 5): the review policy is a tri-state control, not a component row
+
+- Date: 2026-11-01
+- Decisions: #M39, #M40, #M42
+
+Waves 1–4 listed "the review contract" among the things that are never switches.
+That wording was honest while review was a bare boolean, but it became wrong when
+#M39 made the policy a three-value mode and #M40 put one control for it on the
+plugin page. Wave 5 states the actual contract:
+
+- **`review.mode` is the policy, not a capability row.** It has exactly three
+  values — `off`, `optional` (the default) and `required` — and the plugin-pages
+  control is one tri-state radio group on the `dsh-tower` configuration form.
+  There is no review-policy component row, and there are no three mutually
+  exclusive rows. `off` is supported and documented: `tower_review` is not
+  registered, reviewer spawn is refused, and the merge gate ignores review.
+  `optional` keeps `tower_review` and never blocks a merge. `required` keeps the
+  merge gate: a completed mission needs a clean review bound to the branch tip,
+  with the existing exemption path.
+- **`review.requireReview` is a deprecated one-release alias.** It is classified
+  `core` (not `forbidden-to-disable`) because it is policy configuration and a
+  compatibility alias, not a switch a row may own. `true` resolves to `required`,
+  `false` to `optional`, and leaving it unset means `optional`. `true` next to an
+  explicit non-required mode is rejected; `false` never overrides an explicit
+  mode. The alias is removed after the 2.6 window.
+- **What stays non-disableable is the gate in `required` mode.** The merge gate's
+  review evidence and tip binding, and the exemption path, may not be removed by
+  any group, row or boolean. The reviewer preset row stays an optional
+  capability: it may be off while the policy is `off` or `optional`, and under
+  `required` planning and mode entry refuse that combination with an explanation.
+  It is not a mutually exclusive row — the policy is not a row at all.
+- **The gate enforces the shape.** A review-policy-shaped component row, a
+  component `allowedOverrides` or shipped row `config:` that names `review.mode`
+  (or the alias), a missing required-mode gate record, or a forbidden capability
+  that lists `preset-tower-reviewer` all fail
+  `npm run docs:check:components`.
+- **Counts do not move.** 54 config keys, 11 visible components; only the class of
+  one deprecated key changes. The source of truth carries the decision date
+  (`2026-11-01`) and this addendum is its written decision.

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,29 @@ 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
@@ -70,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
@@ -89,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" }
 }