dsh-tower 2.4.2 → 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

@@ -8,11 +8,13 @@
 #
 # Policy: principle 11 in PRINCIPLES.md + docs/adr/0005-component-surface.md.
 # The per-key answer is docs/reference/component-surface.md, generated from
-# scripts/component-surface.json. `npm run docs:check:components` refuses a new
-# switch, a missing locale label, or a moved component count without a written
-# decision. `tower_doctor` and `tower_recover` are part of the host and are never
-# switches (#122); a capability row owns exactly one optional capability, and
-# `tower_status` / `tower_doctor` name any row that is off.
+# scripts/component-surface.json. `npm run docs:check:components` reads every
+# shipped patch (this file and ui-bundle/cordis.patch.yml, which ships the
+# tower-ui row) and refuses a row with no classification, a missing locale label,
+# or a moved component count without a written decision. `tower_doctor` and
+# `tower_recover` are part of the host and are never switches (#122); a capability
+# row owns exactly one optional capability, and `tower_status` / `tower_doctor`
+# name any row that is off.
 - insert:
     # Mandatory host anchor. Not an optional capability: off == uninstall.
     - id: tower
@@ -66,13 +68,28 @@
       name: 'dsh-tower/leases'
     - id: tower-tests
       name: 'dsh-tower/tests'
-    # dev hot reload: shipped off. Enable the row for a linked dev profile.
+    # #133: the MISSIONS.md board is a capability, not the old `docs.board` key.
+    # Off writes no board and leaves an existing one to go stale; every tool and
+    # gate keeps working. `docs.boardLocation` stays genuine tuning.
+    - id: tower-board
+      name: 'dsh-tower/board'
+    # #135: archival is a capability, not the old `archive.enabled` key. Off keeps
+    # terminal missions hot in state.json, so the hot state keeps growing; merges,
+    # gates and every other capability keep working and nothing is deleted.
+    # `archive.afterDays` / `archive.maxMissions` stay genuine tuning.
+    - id: tower-archive
+      name: 'dsh-tower/archive'
+    # #141: developer tooling, not an end-user capability switch. It stays shipped
+    # off; the locale copy states that this row exists for linked-profile
+    # development only, so the plugin page does not read as a missing feature.
     - 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/0004-surface-budget.md

@@ -30,7 +30,9 @@ note for each niche key.
 
 - Growth is visible in a diff instead of arriving one reasonable-looking key at a
   time.
-- A reduction is cheap: the baseline can be ratcheted down with no ADR.
+- A reduction is cheap for `sections` and `tools`: the baseline can be ratcheted
+  down with no ADR. Since #138 the config-key count is two-way like the component
+  count (see [ADR 0005](0005-component-surface.md)).
 - The classification table is auditable, not decorative: the check fails when a
   live key or tool is missing from it.
 - The numbers are three lines in `tower_doctor` output, not a new dashboard.
@@ -53,8 +55,10 @@ extends the budget with a fourth — the number of user-visible component rows i
 `cordis.patch.yml` — and records it as its own `components` baseline entry with a
 two-way decision rule (a contraction needs a decision just like growth). The
 three original counts are still measured by `npm run surface:check`; the
-component count is validated by `npm run docs:check:components`. The historical
-decision above is unchanged: "three surfaces" describes the 2.3.0 rule.
+component count is validated by `npm run docs:check:components`. ADR 0005's wave
+3 (#138) also makes `configKeys` two-way, so the cheap-shrink consequence above
+now applies only to `sections` and `tools`. The historical decision above is
+unchanged: "three surfaces" describes the 2.3.0 rule.
 
 ## Rejected alternatives
 
@@ -65,6 +69,8 @@ decision above is unchanged: "three surfaces" describes the 2.3.0 rule.
 - **A per-key count in each generated reference** — two references can disagree;
   one shared baseline plus one check keeps the counts equal.
 - **Only an ADR requirement** — a pure deletion would need paperwork even though it
-  shrinks the surface; the matching-deletion path keeps reductions cheap.
+  shrinks the surface; the matching-deletion path keeps `sections`/`tools`
+  reductions cheap. The config-key surface is the exception since #138: a removed
+  switch is itself a capability decision, so it needs a dated record (ADR 0005).
 - **A GitHub issue label instead of a repo file** — the brake must run offline in
   `npm test` and in CI without a token.

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
@@ -128,3 +132,210 @@ this wave makes the shipped surface obey it instead of carrying debt.
 - **A GitHub issue label or a docs-only policy.** The brake must run offline in
   `npm test` and in CI without a token, and the policy must survive the closure
   of the issue that introduced it.
+
+## Addendum (wave 2): board, archive, UI and explicit development tooling
+
+- Date: 2026-11-02
+- Decisions: #132, #133, #134, #135, #141
+
+Four components were component-shaped but sat outside the policy: `docs.board` and
+`archive.enabled` were booleans in the config form, `tower-ui` shipped as a real
+plugin-page row that no source-of-truth entry described, and the group rows never
+stated their off consequence where a reader sees it. Wave 2 closes those gaps
+without widening the mechanism.
+
+- **`tower-board` (#133).** `docs.board` is deleted; the board is the optional
+  `tower-board` row with its own capability module. Its fallback: no `MISSIONS.md`
+  is written or refreshed, an existing board goes stale, and every state tool and
+  gate keeps working. `docs.boardLocation` stays a tuning key because it only
+  chooses a path. With the row off, the composition behaves like an all-Tower-off
+  profile for the board (nothing is written) while the rest of Tower keeps working.
+- **`tower-archive` (#135).** `archive.enabled` is deleted; archival is the
+  optional `tower-archive` row. Its fallback is deliberately honest: terminal
+  missions stay hot in `state.json`, the hot state keeps growing, and `status` /
+  `doctor` keep loading their full history; merges and gates are unaffected and
+  nothing is deleted. `archive.afterDays` / `archive.maxMissions` stay tuning.
+- **Removed keys fail loudly.** A config that still sets `docs.board` or
+  `archive.enabled` is rejected with `config-unknown-key` and an upgrade note that
+  names the replacing row and points here. There is no silent alias: a switch that
+  moved to the plugin page must not keep working from a config file.
+- **`tower-ui` is classified (#134).** The UI plugin row is now a visible
+  component with a documented fallback (the web UI plugin does not load: no tool
+  cards, composer-dock summary or status strip; host tools, missions and the board
+  are unaffected). Because it ships in `ui-bundle/`, the gate reads **every**
+  shipped `cordis.patch.yml` (root and `ui-bundle/`), classifies every visible row
+  and enforces a label source for each: either a generated `<specifier>/locale`
+  row, or the row package's own `meta` label when the labels live there. A row
+  added to any shipped patch without a source-of-truth entry fails
+  `npm run docs:check:components`.
+- **A group row states its consequence where it is read (#132).** The plugin page
+  renders the group row from the package `meta` block, so the off-equals-uninstall
+  consequence lives in the root `meta.description` in both languages, and the gate
+  pins it there instead of trusting only the `components` block. This is a label
+  fix, not a new mechanism.
+- **`tower-hmr` stays shipped off (#141).** Moving it to a separate install path
+  would hide the switch and re-open the orphan-mount hazard; the row is kept as
+  explicit development tooling instead: its locale copy and its source-of-truth
+  fallback say that it exists for a linked dev profile, that a normal profile
+  behaves exactly as before, and that it is off on purpose.
+- **Count decision.** The visible component count moved 8 → 9 → 10 → 11 across
+  #133, #135 and #134; the three dated steps are recorded in
+  `scripts/surface-baseline.json`. The config surface contracted 55 → 53, which the
+  other surfaces allow without a decision record.
+
+## Addendum (wave 3): close the gate's blind spots
+
+- Date: 2026-11-03
+- Decisions: #138
+
+Wave 2 made the gate read every shipped row, but four ways to evade it remained:
+a class was free text, the operational route table was scraped with a regex, only
+the patches named in `COMPONENT_PATCH_FILES` were read, and only booleans were
+reviewed. Wave 3 closes them without changing the shipped decisions: 53 config
+keys, 11 visible components.
+
+- **The class is checked against the key's shape (#138.1).** A boolean that
+  removes a capability cannot file as `optional-config` by assertion. Every live
+  boolean must be `core`, `optional-component` or `forbidden-to-disable`, or an
+  `optional-config` key carrying a dated `exemption` whose reason names its
+  tuning-only nature. The same rule covers the non-boolean behaviour knobs below.
+  An exemption is only legal on a reviewed boolean/knob, and its `ref` must exist.
+- **The config-key count is two-way (#138.1).** Wave 2's closing note ("the config
+  surface contracted 55 → 53, which the other surfaces allow without a decision
+  record") is retracted. Removing a switch is a capability decision, so
+  `configKeys` now joins `components` in `SURFACE_TWO_WAY_KEYS`: any later increase
+  or decrease needs a dated decision in `scripts/surface-baseline.json`. The gate
+  requires the `date` field itself (`YYYY-MM-DD`) on every decision of a two-way
+  surface, so a bare from/to record fails even when its chain reaches the value
+  (review of #138). The 64 → 53 history is recorded as one dated decision there;
+  sections and tools keep the ADR 0004 cheap-shrink rule.
+- **The route table is imported, not scraped (#138.2).** `host/tool-registry.js`
+  exports `OPERATIONAL_TOOLS`, and the gate imports that module instead of
+  regex-matching its source. A missing file, a failed import, or a missing/non-Map
+  export is `registry-unreadable` and fails the gate. An empty Map is still the
+  correct determined state (#122): "nothing is gated" is distinct from "could not
+  read".
+- **Every shipped patch is discovered (#138.3).** The gate walks the package for
+  `cordis.patch.yml` and compares the result with `COMPONENT_PATCH_FILES` in both
+  directions. An unlisted patch fails `patch-unclassified`; a listed patch that is
+  missing fails `patch-missing`. The row checks stay bidirectional: every shipped
+  row needs a source-of-truth entry, and every source-of-truth row needs a shipped
+  row.
+- **Behaviour knobs and row overrides are reviewed (#138.4).** `spawn.requireLease`
+  and `tests.admission` are recorded in `behaviorKnobs` and carry tuning-only
+  exemptions: the optional `tower-leases` / `tower-tests` row owns the capability,
+  while these keys choose the safety level or timing inside it. A row's scalar
+  `config:` overrides are now parsed and must name a live config key and be listed
+  in that component's `allowedOverrides`. A row that sets `docs.board`,
+  `archive.enabled` or `tests.enabled` therefore fails as `row-override-unknown`
+  (those capabilities are rows), a row that enables or disables a key it does not
+  own fails as `row-override-foreign`, and `allowedOverrides` may never name a
+  forbidden-to-disable key. Fixtures reproduce the #133/#135/#136 shapes and a
+  foreign override, proving they fail before the fix passes.
+
+## Addendum (wave 4): broad-audience labels and a copy gate
+
+- Date: 2026-11-04
+- 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`, 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.
+
+- **The labels are rewritten for a reader, not for an operator (#137.1).** Every
+  visible row, the group row and the UI row now say what the capability is for
+  and what stops when it is off, in plain language. Config keys, tool ids, slash
+  commands and module specifiers are gone from `title`, `summary`, `disables` and
+  the two `meta` descriptions. The off copy says "refused with an explanation",
+  not "locked", and names Tower mode. The `tower-leases` fix also removes the F19
+  claim that "nothing else depends on a lease": a lease is coordination only, but
+  a worker configured to require one cannot start while the row is off; planning
+  and Tower-mode entry are refused with an explanation until the setting is
+  cleared or the row is re-enabled, and everything else keeps working.
+- **One bilingual vocabulary, recorded (#137.2).** `GLOSSARY.md` is the single
+  table for mission/任务线, batch/批次, doctor/体检, board/看板, archive/归档,
+  preset/预设, worktree/工作树, review/审查, lease/租约, worker/执行代理 and
+  reviewer/审查代理. It also records the copy rules (two sentences, no
+  identifiers, truthful off effect, natural Chinese) and is a gate input: a label
+  that uses a term the table does not pair with its other-language field fails.
+  The Web client's own string catalogue shares this table but is migrated
+  separately; the runtime error copy in `host/presets.js` is likewise a follow-up.
+- **The copy is checked mechanically (#137.3).** `checkLocaleCopy` runs over the
+  root locale pair, the ui-bundle meta pair and every generated row-locale pair.
+  It fails on config-key syntax, `tower_*` ids, `/tower` commands, `dsh-tower/*`
+  specifiers, empty fields, zh/en path drift and glossary mismatches in both
+  directions; the Chinese side may not leave glossary words untranslated.
+  `checkMetaRowCopy` pins the hand-written ui-bundle `meta.title` / `description`
+  to the root `components['tower-ui']` entry and the same composition the
+  generator renders, so the one row that ships its own label cannot drift.
+  `checkGlossaryFile` keeps `GLOSSARY.md` present and complete. Negative
+  fixtures in `tests/locale-copy.test.mjs` prove a raw key, a bare tool id and a
+  term mismatch fail in both languages before the fixed copy passes.
+- **Review of #137 corrected three claims and hardened the guard.** The
+  `tower-tests` off copy promised that "merges … keep working", but
+  `domain/gate.js` emits the `tests-missing` merge blocker while the test
+  requirement is on and `host/presets.js` refuses planning and Tower-mode entry,
+  so the copy now says planning and entry are refused and merges stay blocked
+  until the requirement is cleared. The reviewer preset summary said "only used
+  when review before merging is required"; the row is usable while review is
+  optional and becomes a precondition for merging only when the requirement is
+  on, so the summary says that instead. The Chinese calques 锁状态的恢复出口,
+  收口, 一项命名工作, 在线状态文件 and 关闭该行 were replaced with 卡住的锁如何
+  恢复, 关闭该批次, 某一具体工作, 当前状态文件 and 关闭这一项. The guard now
+  normalizes full-width punctuation and matches case-insensitively, so
+  `Gates.requireTests`, `Tower_batch` and `gates。requireTests` fail; the worker
+  and reviewer role nouns accept an initial capital but exclude the product names
+  "Tower Worker" and "Tower Reviewer", in both the en→zh and zh→en directions.
+  `GLOSSARY.md` ships in the package (`package.json` `files`, pinned by
+  `scripts/pack-manifest.txt`) because it is a gate input, not repository-only
+  prose.
+- **Rejected: a prose style guide with no gate.** It is what let wave 1–3 pass;
+  a reviewer's attention does not survive the next rename.
+- **Rejected: translating the developer reference table.** The fallback text in
+  `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.