dsh-tower 2.5.0 → 2.6.0

package/domain/integration/review.js

@@ -1,11 +1,197 @@
-// Pure review-selection and exemption decisions shared by the merge/gate/read
-// projections. No repository I/O.
+// Pure review-selection, review-policy resolution and exemption decisions
+// shared by the merge/gate/read projections and the config layer. No repository
+// I/O and no process state.
+//
+// REVIEW POLICY (#M39)
+// --------------------
+// `review.mode` is the single policy with exactly three independent values:
+//
+//   off       review is intentionally unavailable: recording a review is
+//             refused, `tower_spawn` refuses the reviewer role, and the merge
+//             gate ignores review blockers. Registration is profile-time: a
+//             profile-level off does not mount `tower_review`, while a
+//             repository-level off over a profile that mounted it refuses the
+//             submission with `review-disabled`;
+//   optional  review is available but never blocks a merge (the default, and the
+//             2.0.3+ behavior of `review.requireReview:false`);
+//   required  a clean review bound to the branch tip is a merge blocker (the
+//             old `review.requireReview:true` behavior).
+//
+// `review.requireReview` stays accepted for one release as a normalized alias:
+// true -> required, false -> optional. Precedence for one raw config object is
+// deterministic:
+//
+//   * only the alias set: the alias decides;
+//   * only the mode set: the mode decides;
+//   * both set: an alias of `true` next to any mode other than `required` is a
+//     contradiction and is rejected naming both keys. An alias of `false` stays
+//     compatible with `off` because both mean "not required by merge" and the
+//     mode is the more specific policy. That asymmetry is also what keeps the
+//     resolver idempotent: it materializes the alias from the mode it resolved,
+//     and `required` is the only mode that mirrors back to `true`.
 // @ts-check
+import { TowerToolError } from '../errors.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').Review} Review */
 /** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
 
+export const REVIEW_MODES = Object.freeze(['off', 'optional', 'required'])
+export const DEFAULT_REVIEW_MODE = 'optional'
+
+// Cordis materializes a `.volatile()` schema field as a live reference object
+// (`{ get() }` plus a non-enumerable `Symbol.for('cosmokit.volatile.write')`).
+// Settings forms hand the runtime these references, not plain values, so every
+// consumer below unwraps them before validating or comparing. Keeping the
+// helpers here (instead of a new config module) lets the schema import them
+// without a cycle: review.js has no dependency on schema.js.
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/**
+ * True for the live reference Cordis/Schemastery creates for a volatile field.
+ * @param {unknown} value
+ * @returns {value is { get: () => unknown }}
+ */
+export function isVolatileRef(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof /** @type {{ get?: unknown }} */ (value).get === 'function' &&
+    Object.getOwnPropertySymbols(value).includes(VOLATILE_WRITE)
+  )
+}
+
+/**
+ * Read a volatile reference once; other values pass through unchanged.
+ * @template T
+ * @param {T | { get: () => T }} value
+ * @returns {T}
+ */
+export function unwrapVolatile(value) {
+  return /** @type {any} */ (isVolatileRef(value) ? value.get() : value)
+}
+
+/**
+ * Deep-copy a raw config object, replacing every volatile reference with its
+ * current value. Non-plain objects (for example a class instance) are returned
+ * as-is; Tower config is JSON-shaped plain data.
+ * @param {unknown} value
+ * @returns {any}
+ */
+export function materializeVolatile(value) {
+  const plain = unwrapVolatile(value)
+  if (Array.isArray(plain)) return plain.map((entry) => materializeVolatile(entry))
+  if (plain === null || typeof plain !== 'object') return plain
+  const proto = Object.getPrototypeOf(plain)
+  if (proto !== Object.prototype && proto !== null) return plain
+  /** @type {Record<string, unknown>} */
+  const copy = {}
+  for (const [key, entry] of Object.entries(plain)) copy[key] = materializeVolatile(entry)
+  return copy
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is 'off' | 'optional' | 'required'}
+ */
+export function isReviewMode(value) {
+  return typeof value === 'string' && REVIEW_MODES.includes(value)
+}
+
+/**
+ * The mode the deprecated boolean alias means.
+ * @param {boolean} requireReview
+ */
+export function legacyReviewMode(requireReview) {
+  return requireReview === true ? 'required' : DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The resolved mode for any config object the runtime may hold: a resolved
+ * config, a raw profile/repo layer, or a hand-built test fixture. An explicit
+ * `mode` always wins; otherwise the deprecated alias decides; otherwise the
+ * documented default applies.
+ * @param {{ review?: any } | null | undefined} [config]
+ * @returns {'off' | 'optional' | 'required'}
+ */
+export function reviewModeOf(config) {
+  const review = config?.review ?? {}
+  const mode = unwrapVolatile(review.mode)
+  if (isReviewMode(mode)) return mode
+  const alias = unwrapVolatile(review.requireReview)
+  if (typeof alias === 'boolean') return legacyReviewMode(alias)
+  return DEFAULT_REVIEW_MODE
+}
+
+/**
+ * The review gate is enforced only in `required`. `off` and `optional` both
+ * ignore review at the merge gate; they differ in availability, not strictness.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewRequired(config) {
+  return reviewModeOf(config) === 'required'
+}
+
+/**
+ * True when review is intentionally switched off (`tower_review` absent,
+ * reviewer spawn refused, merge gate ignores review).
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewUnavailable(config) {
+  return reviewModeOf(config) === 'off'
+}
+
+/**
+ * Resolve one raw `review` object (a profile, a repository layer, or a single
+ * written config) into its mode. Rejects contradictory explicit values and an
+ * unknown mode with an actionable `config-invalid` error.
+ *
+ * @param {any} rawReview
+ * @returns {{ mode: 'off' | 'optional' | 'required', explicit: boolean, legacy: boolean }}
+ */
+export function resolveReviewPolicy(rawReview) {
+  const review = rawReview && typeof rawReview === 'object' && !Array.isArray(rawReview) ? rawReview : {}
+  const mode = unwrapVolatile(review.mode)
+  const alias = unwrapVolatile(review.requireReview)
+  if (mode !== undefined && !isReviewMode(mode)) {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode must be one of ${REVIEW_MODES.join('|')}, got ${JSON.stringify(mode)}`,
+    )
+  }
+  if (alias !== undefined && typeof alias !== 'boolean') {
+    throw new TowerToolError(
+      'config-invalid',
+      'review.requireReview must be a boolean (deprecated alias: true -> required, false -> optional)',
+    )
+  }
+  if (mode !== undefined && alias === true && mode !== 'required') {
+    throw new TowerToolError(
+      'config-invalid',
+      `review.mode is ${JSON.stringify(mode)} but review.requireReview is true; set only review.mode (off|optional|required) — review.requireReview is a deprecated alias (true -> required, false -> optional) and may not contradict it`,
+    )
+  }
+  if (mode !== undefined) return { mode, explicit: true, legacy: alias !== undefined }
+  if (alias !== undefined) return { mode: legacyReviewMode(alias), explicit: true, legacy: true }
+  return { mode: DEFAULT_REVIEW_MODE, explicit: false, legacy: false }
+}
+
+/**
+ * The small read-only projection reported by `tower_status` and the doctor's
+ * `review` check. `detail` is the one sentence both surfaces share.
+ * @param {{ review?: any } | null | undefined} [config]
+ */
+export function reviewPolicyView(config) {
+  const mode = reviewModeOf(config)
+  const detail =
+    mode === 'off'
+      ? 'review.mode:off — review is intentionally unavailable: recording a review is refused, reviewer spawn is refused, and the merge gate ignores review; a profile-level off does not register tower_review'
+      : mode === 'required'
+        ? 'review.mode:required — a clean review bound to the branch tip is a merge blocker'
+        : 'review.mode:optional — review is available but never blocks a merge'
+  return { mode, available: mode !== 'off', required: mode === 'required', detail }
+}
+
 /**
  * Reviews are branch-scoped; a missing branch has no reviews.
  * @param {Review[] | null | undefined} reviews
@@ -26,27 +212,35 @@ export function latestReview(reviews) {
 }
 
 /**
- * A mission may skip review only with both the exemption gate and a reason.
+ * A mission skips the review gate unless `review.mode` is `required`. In
+ * `required`, it may still skip with both the exemption gate and a reason.
+ * `off` and `optional` both bypass the gate; they differ only in whether the
+ * review tools/spawn role exist.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function isReviewExempt(mission, config = {}) {
+  if (!reviewRequired(config)) return true
   return (
-    config.review?.requireReview === false ||
-    (mission.reviewPolicy === 'none' &&
-      config.gates?.allowReviewExemption === true &&
-      String(mission.reviewExemptionReason ?? '').trim().length > 0)
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption === true &&
+    String(mission.reviewExemptionReason ?? '').trim().length > 0
   )
 }
 
 /**
  * `reviewPolicy: none` is invalid when the reviewer gate does not allow it.
+ * Only `review.mode:required` can make the request invalid; with review off or
+ * optional no review blocker is produced at all.
  * @param {Mission} mission
  * @param {TowerConfig} [config]
  * @returns {boolean}
  */
 export function reviewExemptionInvalid(mission, config = {}) {
-  const requireReview = config.review?.requireReview !== false
-  return requireReview && mission.reviewPolicy === 'none' && config.gates?.allowReviewExemption !== true
+  return (
+    reviewRequired(config) &&
+    mission.reviewPolicy === 'none' &&
+    config.gates?.allowReviewExemption !== true
+  )
 }

package/host/config.js

@@ -24,6 +24,7 @@ import {
   resolveTowerConfig,
 } from '../domain/config/schema.js'
 import { TowerToolError } from '../domain/errors.js'
+import { materializeVolatile, resolveReviewPolicy, reviewUnavailable } from '../domain/integration/review.js'
 
 export { Config, DEFAULT_DENY_TOOLS, resolveTowerConfig }
 
@@ -31,11 +32,16 @@ const REPO_CONFIG_MAX_BYTES = 1024 * 1024
 
 // The last raw profile config `apply()` received; repository config is merged
 // over it so a repo can tune spawn/merge/review without editing the profile.
+//
+// #M40: this must stay the *raw* object. A `.volatile()` field arrives as a
+// live reference that Cordis updates in place on a settings write, and cloning
+// (JSON) would freeze a copy and hide the new value from runtimeConfig(). Only
+// readers that need plain data (profileConfig) materialize it.
 let profileRaw = {}
 
 export function configureRuntime(config) {
-  profileRaw = clone(config ?? {}) ?? {}
-  return resolveTowerConfig(config)
+  profileRaw = config ?? {}
+  return resolveTowerConfig(profileRaw)
 }
 
 export function runtimeConfig() {
@@ -44,7 +50,7 @@ export function runtimeConfig() {
 
 /** Raw profile config before defaults are materialized (for doctor warnings). */
 export function profileConfig() {
-  return clone(profileRaw) ?? {}
+  return clone(materializeVolatile(profileRaw)) ?? {}
 }
 
 export function repoConfigPath(commonDir) {
@@ -92,6 +98,10 @@ export async function readRepoConfig(commonDir) {
     // Validate value types without letting the schema's defaults win over the
     // profile layer: merge into an empty raw object and discard the result.
     Config(parsed)
+    // #M39: the schema accepts both review keys; only the resolver knows that an
+    // explicit `requireReview:true` next to a conflicting `review.mode` is a
+    // contradiction. Reject it here, before the layer can be merged.
+    resolveReviewPolicy(parsed.review)
   } catch (error) {
     throw new TowerToolError('config-invalid', `repo config at ${file} is invalid: ${String(error?.message ?? error)}`)
   }
@@ -130,6 +140,33 @@ export async function resolveRepoConfig(repo) {
   if (!Array.isArray(merged.mode?.denyTools) || merged.mode.denyTools.length === 0) {
     merged.mode = { ...(merged.mode ?? {}), denyTools: [...DEFAULT_DENY_TOOLS] }
   }
+  // #M39: the review policy is resolved per layer instead of deep-merging two
+  // resolved shapes. A resolved base always carries both `review.mode` and its
+  // mirrored alias, so a repository layer that sets only one of the two would
+  // otherwise pair a stale inherited `mode` with the new alias. The repository
+  // layer wins as a whole when it names either key; a layer that names neither
+  // inherits the profile policy untouched.
+  const repoReview = repoLayer.review
+  if (repoReview && typeof repoReview === 'object' && !Array.isArray(repoReview)) {
+    const explicit = repoReview.mode !== undefined || repoReview.requireReview !== undefined
+    if (explicit) {
+      const repoPolicy = resolveReviewPolicy(repoReview)
+      if (reviewUnavailable(base) && repoPolicy.mode !== 'off') {
+        // The tool surface is fixed when the plugin applies: a profile with
+        // review off never registered tower_review, so a repository may relax
+        // review further but cannot re-enable a tool that does not exist.
+        throw new TowerToolError(
+          'config-invalid',
+          `review.mode is off in the profile, so tower_review is not registered; repository config cannot set review.mode:${repoPolicy.mode}. Set review.mode in the profile instead.`,
+        )
+      }
+      merged.review = {
+        ...(merged.review ?? {}),
+        mode: repoPolicy.mode,
+        requireReview: repoPolicy.mode === 'required',
+      }
+    }
+  }
   merged.section = merged.mode?.promptSection ?? merged.section ?? ''
   return {
     ...merged,

package/host/doctor.js

@@ -13,6 +13,7 @@ import { SCHEMA_VERSION } from '../domain/mission.js'
 import { DEFAULT_MAX_REPORT_BYTES, completionReportBytes } from '../domain/missions/completion.js'
 import { comparisonMode } from '../domain/scope.js'
 import { configSurface } from '../domain/config/schema.js'
+import { reviewPolicyView, reviewRequired } from '../domain/integration/review.js'
 import { parseBaseline, surfaceLine, SURFACE_BASELINE_FILE } from '../domain/surface.js'
 import { assessHostVersion, detectHostVersion, readCompatibility } from './compatibility.js'
 import { profileConfig } from './config.js'
@@ -242,8 +243,11 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
   const config = tower.config ?? {}
   const profile = profileConfig()
   const staleDefaults = []
-  if (profile.review && profile.review.requireReview === undefined) {
-    staleDefaults.push('review.requireReview now defaults to false (2.0.3)')
+  // #M39: `review.mode` replaces the deprecated boolean. A profile that names
+  // neither key relies on the default (optional), so say so rather than letting
+  // a reader assume review is enforced.
+  if (profile.review && profile.review.mode === undefined && profile.review.requireReview === undefined) {
+    staleDefaults.push('review.mode defaults to optional; review.requireReview is a deprecated alias')
   }
   if (profile.mode && profile.mode.allowAgentControl === undefined) {
     staleDefaults.push('mode.allowAgentControl now defaults to true (2.0.4)')
@@ -261,6 +265,11 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
       'optional: add <git-common-dir>/dsh-tower/config.json',
     ),
   )
+  // #M39: the resolved review mode is its own diagnostic fact. `off` is a
+  // supported, intentional posture (not a degradation), so it is a pass whose
+  // detail says exactly what is unavailable.
+  const reviewPolicy = reviewPolicyView(config)
+  checks.push(check('review', 'pass', reviewPolicy.detail))
   // #84: report the concept-budget surface instead of implying it. The counts
   // are the live schema/tool surface; the date is the committed baseline, so a
   // reader sees both the number and the decision it was frozen at.
@@ -288,7 +297,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
         ),
   )
   const presets = ctx.get?.('agentPresets')
-  const reviewerRequired = config.review?.requireReview === true
+  const reviewerRequired = reviewRequired(config)
   if (presets && typeof presets.list === 'function') {
     try {
       const available = (await presets.list()).map((entry) => String(entry.id))
@@ -296,9 +305,10 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
       const reviewer = config.spawn?.reviewerPreset ?? 'tower-reviewer'
       const required = reviewerRequired ? [worker, reviewer] : [worker]
       const missing = required.filter((id) => !available.includes(id))
-      // #121: `preset-tower-reviewer` is a conditional component. Its off state
-      // is supported while review.requireReview is false; with the gate on it is
-      // a fail, because no independent review can be dispatched.
+      // #121/#M39: `preset-tower-reviewer` is a conditional component. Its off
+      // state is supported while review is off or optional; with
+      // `review.mode:required` it is a fail, because no independent review can
+      // be dispatched.
       if (missing.length === 0) {
         const reviewerNote = available.includes(reviewer)
           ? `reviewer=${reviewer}`
@@ -309,7 +319,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
           check(
             'presets',
             'fail',
-            `missing preset(s): ${missing.join(', ')}${reviewerRequired && missing.includes(reviewer) ? ' (review.requireReview is true, so preset-tower-reviewer may not be off)' : ''}`,
+            `missing preset(s): ${missing.join(', ')}${reviewerRequired && missing.includes(reviewer) ? ' (review.mode is required, so preset-tower-reviewer may not be off)' : ''}`,
             'enable the Tower preset component and retry',
           ),
         )
@@ -596,6 +606,7 @@ export async function runDoctor({ tower, ctx, agent, hostVersion, compatibilityF
 // reports (from #89) and archive (from #73) are both kept
     reports: reportsReport,
     surface: surfaceReport,
+    review: reviewPolicy,
     components,
     archive: {
       missions: state ? state.missions.length : null,

package/host/presets.js

@@ -6,9 +6,9 @@
 //   1. `preset-tower-worker` is a mandatory dependency: planning, mode entry and
 //      spawn must refuse when the worker preset is absent.
 //   2. `preset-tower-reviewer` is a *conditional* component. It may be off while
-//      `review.requireReview` is false (merge is unaffected); with the review
-//      gate on it must be locked with an explanatory error, never silently
-//      allowed.
+//      `review.mode` is `off` or `optional` (merge is unaffected; `off` does not
+//      use the preset at all); with `review.mode:required` it must be locked with
+//      an explanatory error, never silently allowed.
 //
 // `tower-tests` adds a third: with the component row off there is no
 // `tower_test` tool and no receipt, so `gates.requireTests: true` is refused
@@ -19,6 +19,7 @@
 // spawn would fail at `lease-busy` advising a tool that is not registered, so the
 // contradiction is refused up front instead.
 import { TowerToolError } from '../domain/errors.js'
+import { reviewRequired } from '../domain/integration/review.js'
 import { componentEnabled, disabledReason } from './capability-registry.js'
 
 export function presetIds(config = {}) {
@@ -38,22 +39,22 @@ function rowId(preset) {
  * registered. If the service is unavailable, doctor reports that separately and
  * this check cannot make a claim either way.
  *
- * The reviewer preset is required only when `review.requireReview` is true; the
- * off state is otherwise supported by the component contract.
+ * The reviewer preset is required only when `review.mode` is `required`; with
+ * `off`/`optional` the off state is supported by the component contract.
  */
 export async function assertPresetsAvailable(ctx, config = {}) {
   const service = ctx?.get?.('agentPresets')
   if (!service || typeof service.list !== 'function') return { checked: false, missing: [] }
   const presets = presetIds(config)
   const required = [presets.worker]
-  if (config.review?.requireReview === true) required.push(presets.reviewer)
+  if (reviewRequired(config)) required.push(presets.reviewer)
   const available = new Set((await service.list()).map((entry) => String(entry.id)))
   const missing = required.filter((id) => !available.has(id))
   if (missing.length === 0) return { checked: true, missing: [] }
   const rows = [...new Set(missing.map(rowId))]
   const reviewLock =
-    config.review?.requireReview === true && missing.includes(presets.reviewer)
-      ? ` review.requireReview is true, so the reviewer row may not be off; ${disabledReason(rowId(presets.reviewer))} is rejected`
+    reviewRequired(config) && missing.includes(presets.reviewer)
+      ? ` review.mode is required, so the reviewer row may not be off; ${disabledReason(rowId(presets.reviewer))} is rejected`
       : ''
   throw new TowerToolError(
     'preset-missing',

package/host/tool-registry.js

@@ -16,6 +16,7 @@ import {
 } from '../domain/vocabulary.js'
 import { git, resolveRepo, hasAnyCommit } from '../adapters/git.js'
 import { runtimeConfig } from './config.js'
+import { reviewUnavailable } from '../domain/integration/review.js'
 import { runDoctor } from './doctor.js'
 import { createHmrBridge } from './hmr.js'
 import { assertRuntimePreconditions } from './presets.js'
@@ -652,7 +653,14 @@ export function registerCoreTowerTools(ctx, options = {}) {
 
   registerFindingsTool(ctx, { openTower, define, actorFor, requireKnownActor })
 
-  registerReviewTool(ctx, { openTower, define, actorFor })
+  // #M39: `review.mode:off` is the one configuration that removes tower_review
+  // from the mounted surface. The name is still recorded before the decision so
+  // the concept budget keeps measuring the build surface (the same rule the
+  // shipped-off component rows follow), and status/doctor report the mode as
+  // intentionally unavailable. A repository layer cannot re-enable the tool
+  // (host/config.js refuses that); the profile owns the mounted surface.
+  recordToolRegistration('tower_review')
+  if (!reviewUnavailable(runtimeConfig())) registerReviewTool(ctx, { openTower, define, actorFor })
 
   registerPreflightTool(ctx, { openTower, define, observeActivity })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -28,6 +28,7 @@
   },
   "exports": {
     ".": "./index.js",
+    "./client": "./client.js",
     "./worker": "./worker.js",
     "./reviewer": "./reviewer.js",
     "./skills": "./skills.js",
@@ -55,6 +56,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "client.js",
     "index.js",
     "worker.js",
     "reviewer.js",
@@ -86,6 +88,10 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
     }
   },
   "scripts": {

package/scripts/check-components.mjs

@@ -8,14 +8,19 @@
 //      locale/en.json and locale/zh.json — and the same three strings for every
 //      component that ships a generated row label, including the internal
 //      worker preset (#121);
-//   2. a forbidden-to-disable capability (host, health, recovery, review
-//      contract, merge gates) that any group, row or boolean key can disable;
+//   2. a forbidden-to-disable capability (host, health, recovery, merge gates)
+//      that any group, row or boolean key can disable;
 //   3. a component count that moved without a decision in
 //      scripts/surface-baseline.json (the same brake `surface:check` applies);
 //   4. #137: user-facing label copy that leaks a config key, an internal tool id,
 //      a slash command or a module specifier, leaves a term untranslated in
 //      Chinese, drifts from the recorded glossary, or diverges between zh and en
-//      in the root locale, the generated row locales and the ui-bundle locale.
+//      in the root locale, the generated row locales and the ui-bundle locale;
+//   5. #M42: the review policy presented as a row. `review.mode` is one
+//      tri-state configuration control (off/optional/required) on the plugin
+//      page, not a component row and not three mutually exclusive rows; no row
+//      may own the policy, and the reviewer preset row may not be made
+//      incompatible with the off/optional modes.
 //
 // It also refuses the quiet forms of the same drift: a shipped component row
 // missing from the single source of truth, a live config key without a
@@ -72,9 +77,10 @@ a visible row with no label source at all, a group row whose plugin-page
 description omits its off consequence, a forbidden-to-disable capability disabled
 by a group, row or boolean key, a component count that moved without a
 scripts/surface-baseline.json decision, an unclassified config key or component
-row, a stale generated reference, and (#137) any label copy that names a config
-key or internal tool id, leaves a glossary term untranslated, or diverges between
-zh and en.
+row, a stale generated reference, (#137) any label copy that names a config key or
+internal tool id, leaves a glossary term untranslated, or diverges between zh and
+en, and (#M42) the review policy exposed as a row instead of one tri-state
+configuration control.
 Regenerate the table with \`npm run docs:generate:components\` and the row labels
 with \`npm run docs:generate:locale\`.`
 
@@ -650,6 +656,112 @@ export function checkRowLabelSources(patch, rowLocales) {
   return findings
 }
 
+// #M42: the review policy is one tri-state configuration control on the plugin
+// page. These names are the policy-shaped rows the gate refuses to see: a row
+// per mode (or one "review policy" row) is the shape the product replaced.
+export const REVIEW_POLICY_KEY = 'review.mode'
+export const REVIEW_ALIAS_KEY = 'review.requireReview'
+export const REVIEW_REVIEWER_ROW = 'preset-tower-reviewer'
+const REVIEW_POLICY_ROW_IDS = Object.freeze([
+  'review',
+  'review-policy',
+  'review-mode',
+  'review-modes',
+  'tower-review',
+  'tower-review-policy',
+])
+
+/**
+ * #M42: hold the review control to its declared shape. The policy is one
+ * tri-state control (`off`/`optional`/`required`) on the plugin-page
+ * configuration form, not a component row and not three mutually exclusive rows.
+ *
+ * The gate fails when a review-policy-shaped row exists, when a component
+ * `allowedOverrides` or a shipped row's `config:` block owns `review.mode` (or
+ * the deprecated alias), when the non-disableable required-mode gate is not
+ * recorded on the forbidden list, and when a forbidden capability claims the
+ * reviewer preset row as a disabler. The reviewer row is an optional capability:
+ * it may be off while the policy is off or optional, and is only a precondition
+ * (with an explanatory refusal) under required.
+ *
+ * @param {ReturnType<typeof parseComponentSurface>} surface
+ * @param {{ patch?: ReturnType<typeof parseCordisPatch> }} live
+ */
+export function checkReviewPolicySurface(surface, live) {
+  const findings = []
+  const record = (code, message) => findings.push(finding(code, 'error', message))
+  const components = surface?.components ?? []
+  const byName = new Map((surface?.keys ?? []).map((key) => [key.name, key]))
+
+  for (const name of [REVIEW_POLICY_KEY, REVIEW_ALIAS_KEY]) {
+    const key = byName.get(name)
+    if (!key) {
+      record('review-policy-key', `${name} is missing from the component surface; the review policy needs an explicit class`)
+      continue
+    }
+    if (key.class !== 'core') {
+      record(
+        'review-policy-class',
+        `${name} is classified "${key.class}"; the review policy is one tri-state configuration control and its keys must be core, never a switch a row can turn off`,
+      )
+    }
+  }
+
+  const policyRow = components.find((component) => REVIEW_POLICY_ROW_IDS.includes(component.id))
+  if (policyRow) {
+    record(
+      'review-policy-row',
+      `component "${policyRow.id}" is a review-policy row; the review policy is one tri-state control on the plugin-page configuration form, not a component row and never one row per mode`,
+    )
+  }
+
+  const reviewerRow = components.find((component) => component.id === REVIEW_REVIEWER_ROW)
+  if (!reviewerRow) {
+    record(
+      'review-policy-reviewer-row',
+      `${REVIEW_REVIEWER_ROW} is missing from the component surface; the reviewer preset must stay an optional capability the review policy may leave unused`,
+    )
+  }
+
+  for (const component of components) {
+    for (const override of component.allowedOverrides ?? []) {
+      if (override !== REVIEW_POLICY_KEY && override !== REVIEW_ALIAS_KEY) continue
+      record(
+        'review-policy-switch',
+        `component "${component.id}" lists ${override} in allowedOverrides; the review policy is one tri-state configuration control and no component row may own it`,
+      )
+    }
+  }
+
+  for (const row of live?.patch?.rows ?? []) {
+    for (const override of row.configOverrides ?? []) {
+      if (override.key !== REVIEW_POLICY_KEY && override.key !== REVIEW_ALIAS_KEY) continue
+      record(
+        'review-policy-switch',
+        `row "${row.id}" sets ${override.key} in cordis.patch.yml; the review policy is one tri-state configuration control, not a per-row switch`,
+      )
+    }
+  }
+
+  const gate = (surface?.forbidden ?? []).find((capability) => (capability.gatedBy ?? []).includes(REVIEW_POLICY_KEY))
+  if (!gate) {
+    record(
+      'review-policy-gate',
+      `no forbidden capability records the required-mode review gate via gatedBy ${REVIEW_POLICY_KEY}; required mode must keep its review evidence and exemption path non-disableable`,
+    )
+  }
+
+  for (const capability of surface?.forbidden ?? []) {
+    if (!(capability.rowIds ?? []).includes(REVIEW_REVIEWER_ROW)) continue
+    record(
+      'review-policy-exclusive',
+      `forbidden capability "${capability.id}" lists ${REVIEW_REVIEWER_ROW} as a row it may disable; a component may not be mutually exclusive with the review policy, which is one control, not a row`,
+    )
+  }
+
+  return findings
+}
+
 /**
  * Run every component-surface rule against one repository root.
  * @param {string} root
@@ -735,6 +847,8 @@ export async function checkComponents(root) {
     findings.push(finding('registry-unreadable', 'error', live.registryError))
   }
   findings.push(...checkForbidden(surface, { booleans: live.booleans, registry: live.registry, patch: live.patch }))
+  // #M42: the review policy is one tri-state configuration control, not a row.
+  findings.push(...checkReviewPolicySurface(surface, live))
 
   // The decision record must exist: the ADR is where the policy is argued.
   if (!fs.existsSync(path.join(root, surface.adr))) {