dsh-tower 2.4.2 → 2.6.0

package/scripts/check-pack.mjs

@@ -16,6 +16,9 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const REQUIRED_FILES = [
   'cordis.patch.yml',
   'index.js',
+  // #M40: the core Web Client half carries the Plugins-page review policy
+  // control; it is part of the published bundle like ui-bundle/.
+  'client.js',
   'locale/en.json',
   'locale/zh.json',
   // #121: every optional capability row and both preset-declaring rows explain

package/scripts/component-surface.json

@@ -1,12 +1,12 @@
 {
   "schema": 1,
-  "date": "2026-10-23",
+  "date": "2026-11-01",
   "adr": "docs/adr/0005-component-surface.md",
   "classes": {
     "core": "Removing it breaks the Tower contract. It is never a switch.",
     "optional-component": "A capability whose off state leaves the rest of Tower intact. It must be a user-visible switch with a documented fallback.",
     "optional-config": "A tuning knob, not a capability. It stays in the config form and never hides a component.",
-    "forbidden-to-disable": "The host, the health contract, the recovery escape, the review contract and the merge gates. No group, row or boolean key may turn it off."
+    "forbidden-to-disable": "The host, the health contract, the recovery escape and the merge gates. No group, row or boolean key may turn it off."
   },
   "components": [
     {
@@ -19,7 +19,16 @@
       "id": "tower-host",
       "scope": "internal",
       "kind": "row",
-      "fallback": "The Host plugin itself, nested under the mandatory tower anchor. A mandatory dependency, never its own switch."
+      "fallback": "The Host plugin itself, nested under the mandatory tower anchor. A mandatory dependency, never its own switch.",
+      "allowedOverrides": [
+        "mode.allowAgentControl",
+        "mode.workspaceLock",
+        "mode.workspaceLockScope",
+        "mode.planModePolicy",
+        "init.autoGitInit",
+        "send.interruptDefault",
+        "spawn.staleMs"
+      ]
     },
     {
       "id": "tower-skills",
@@ -43,7 +52,7 @@
       "id": "tower-leases",
       "scope": "visible",
       "kind": "row",
-      "fallback": "tower_resource is not registered; advisory leases are coordination only, so nothing else depends on them."
+      "fallback": "tower_resource is not registered; advisory leases are coordination only, but spawn.requireLease still needs the tool to acquire one, so a config that sets spawn.requireLease is rejected at runtime preconditions instead of failing every spawn at lease-busy."
     },
     {
       "id": "tower-tests",
@@ -51,11 +60,23 @@
       "kind": "row",
       "fallback": "tower_test is not registered and no test receipt can be recorded. With gates.requireTests:true planning/mode entry is rejected with an explanation, and the merge gate still reports tests-missing."
     },
+    {
+      "id": "tower-board",
+      "scope": "visible",
+      "kind": "row",
+      "fallback": "MISSIONS.md is not written or refreshed, so an existing board goes stale. Mission state tools, gates and every other capability keep working; docs.boardLocation still chooses where a board would be written."
+    },
+    {
+      "id": "tower-archive",
+      "scope": "visible",
+      "kind": "row",
+      "fallback": "Terminal missions are not moved out of state.json, so the hot state keeps growing and status/doctor keep loading their full history. Merges, gates and every other capability keep working; nothing is deleted. afterDays/maxMissions keep their tuning meaning."
+    },
     {
       "id": "tower-hmr",
       "scope": "visible",
       "kind": "row",
-      "fallback": "tower_reload and /tower reload are unavailable; a profile without HMR behaves exactly as before. Shipped disabled: enable the row for a linked dev profile."
+      "fallback": "Development-only tooling: tower_reload and /tower reload are unavailable, so a linked-profile reload has to be triggered outside Tower. A normal profile behaves exactly as before; the row ships disabled on purpose."
     },
     {
       "id": "preset-tower-worker",
@@ -67,10 +88,21 @@
       "id": "preset-tower-reviewer",
       "scope": "visible",
       "kind": "row",
-      "fallback": "Declared by dsh-tower/preset-reviewer: the reviewer cannot be dispatched. Supported while review.requireReview is false (merge is unaffected); with the gate on planning/mode entry is locked with an explanatory error."
+      "fallback": "Declared by dsh-tower/preset-reviewer: the reviewer cannot be dispatched. Supported while review.mode is off or optional (merge is unaffected; off does not use the preset at all); with review.mode required, planning/mode entry is locked with an explanatory error."
+    },
+    {
+      "id": "tower-ui",
+      "scope": "visible",
+      "kind": "row",
+      "fallback": "The Tower web UI plugin does not load in this profile: no Tower tool cards, composer-dock summary or status strip. Host tools, missions, state and the MISSIONS.md board are unaffected."
     }
   ],
   "gateableTools": {},
+  "behaviorKnobs": [
+    "review.mode",
+    "spawn.requireLease",
+    "tests.admission"
+  ],
   "keys": [
     {
       "name": "section",
@@ -85,17 +117,35 @@
     {
       "name": "init.autoGitInit",
       "class": "optional-config",
-      "note": "Bootstrap convenience; off only means tower_init will not run git init."
+      "note": "Bootstrap convenience; off only means tower_init will not run git init.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning, not capability: tower_init stays the component and the switch only decides whether it runs git init."
+      }
     },
     {
       "name": "init.snapshotDirty",
       "class": "optional-config",
-      "note": "Dirty-work baseline convenience; no capability is removed."
+      "note": "Dirty-work baseline convenience; no capability is removed.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning, not capability: the init component remains available with or without a dirty-work snapshot baseline."
+      }
     },
     {
       "name": "init.autoExclude",
       "class": "optional-config",
-      "note": "Keeps Tower artifacts out of .git/info/exclude; safe either way."
+      "note": "Keeps Tower artifacts out of .git/info/exclude; safe either way.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning, not capability: both values keep the init component and only change which artifacts the exclude file names."
+      }
     },
     {
       "name": "mode.promptSection",
@@ -172,10 +222,15 @@
       "class": "optional-config",
       "note": "Bounded wait for the cross-process mode lock."
     },
+    {
+      "name": "review.mode",
+      "class": "core",
+      "note": "The review policy: off, optional (default) or required, selected by one tri-state control on the plugin-page configuration form. It is configuration, not a component row and not three mutually exclusive rows. off intentionally removes tower_review, refuses reviewer spawn and makes the merge gate ignore review; optional never blocks a merge; required makes a clean tip-bound review a merge blocker. The reviewer preset row stays a capability the mode may leave unused."
+    },
     {
       "name": "review.requireReview",
-      "class": "forbidden-to-disable",
-      "note": "Turns independent review into a merge blocker; no component may switch it off. With it on, the preset-tower-reviewer row may not be off (planning/mode entry refuse the combination)."
+      "class": "core",
+      "note": "Deprecated one-release boolean alias for review.mode (true -> required, false -> optional; default optional). It is policy configuration and a deprecated alias, not a switch a row may own; false never overrides an explicit mode. Kept so 2.5 configurations keep working; remove after the 2.6 alias window."
     },
     {
       "name": "review.maxRoundsPerReviewer",
@@ -250,7 +305,13 @@
     {
       "name": "spawn.requireLease",
       "class": "optional-config",
-      "note": "Advisory-lease gate before a worker starts."
+      "note": "Advisory-lease gate before a worker starts.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning the safety level inside the optional tower-leases row; with leases off the Host refuses requireLease instead of removing the spawn capability."
+      }
     },
     {
       "name": "send.maxPerMinute",
@@ -260,17 +321,24 @@
     {
       "name": "send.interruptDefault",
       "class": "optional-config",
-      "note": "Default for the interrupt-before-deliver flag."
-    },
-    {
-      "name": "tests.enabled",
-      "class": "optional-component",
-      "note": "Tuning inside the optional tower-tests component: it decides whether discovery runs when the row is on. Off with gates.requireTests:true is rejected at config resolution."
+      "note": "Default for the interrupt-before-deliver flag.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning, not capability: the send component always exists and the switch only picks a delivery default."
+      }
     },
     {
       "name": "tests.admission",
       "class": "optional-config",
-      "note": "Chooses when discovery runs inside the optional tests capability."
+      "note": "Chooses when discovery runs inside the optional tests capability.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning when the admission check runs inside the optional tower-tests row, which still owns whether test tooling exists."
+      }
     },
     {
       "name": "tests.timeoutMs",
@@ -285,7 +353,13 @@
     {
       "name": "tests.autoChecks",
       "class": "optional-config",
-      "note": "Attaches a tests check to completion when discovery runs."
+      "note": "Attaches a tests check to completion when discovery runs.",
+      "exemption": {
+        "date": "2026-11-03",
+        "ref": "docs/adr/0005-component-surface.md",
+        "issue": "#138",
+        "reason": "Tuning the default receipt policy inside the optional tower-tests row, which still owns whether any test tooling exists."
+      }
     },
     {
       "name": "tests.allowPackageDiscovery",
@@ -312,25 +386,15 @@
       "class": "forbidden-to-disable",
       "note": "The report cap is part of the completion contract; the refusal itself is never configurable away."
     },
-    {
-      "name": "docs.board",
-      "class": "optional-config",
-      "note": "Writes the human-readable board; no capability is removed."
-    },
     {
       "name": "docs.boardLocation",
       "class": "optional-config",
-      "note": "Chooses the board location."
-    },
-    {
-      "name": "archive.enabled",
-      "class": "optional-config",
-      "note": "Archival is maintenance, not a tool capability; off only leaves terminal missions hot."
+      "note": "Chooses where the board is written; whether it is written is the tower-board component row (#133)."
     },
     {
       "name": "archive.afterDays",
       "class": "optional-config",
-      "note": "Archive age threshold."
+      "note": "Archive age threshold inside the optional tower-archive component (#135)."
     },
     {
       "name": "archive.maxMissions",
@@ -377,11 +441,11 @@
     },
     {
       "id": "review",
-      "capability": "the review contract",
-      "reason": "review.requireReview is a merge blocker, not a component; a row may not switch it off. The reviewer row is conditional, not a way to weaken the gate.",
-      "tools": ["tower_diff", "tower_preflight", "tower_review"],
-      "rowIds": ["tower-review"],
-      "gatedBy": ["review.requireReview", "review.maxRoundsPerReviewer"]
+      "capability": "the review gate in required mode",
+      "reason": "The policy is one tri-state configuration control on the plugin-page form, not a component row: review.mode is off, optional (default) or required, and off is a documented mode that removes tower_review and makes the merge gate ignore review. What no group, row or boolean key may switch off is the gate once the mode is required: a completed mission still needs a clean review bound to the branch tip, and the exemption path stays explicit. review.requireReview is a deprecated one-release alias, not a switch. The reviewer preset row remains a capability the policy may leave unused, never a way to weaken required mode.",
+      "tools": [],
+      "rowIds": [],
+      "gatedBy": ["review.mode", "review.maxRoundsPerReviewer", "gates.allowReviewExemption"]
     },
     {
       "id": "merge-gates",

package/scripts/generate-capability-locale.mjs

@@ -30,6 +30,7 @@ const LANGUAGES = Object.keys(LANGUAGE_FILES)
 // `disables` prose, so the check can prove every description names what the
 // switch removes without depending on one English or Chinese phrasing.
 const OFF_EFFECT_LABEL = { en: 'When off:', zh: '关闭后：' }
+export { OFF_EFFECT_LABEL }
 // The worker preset has no off state; it is a mandatory dependency of the Tower
 // host. Its description says so with an explicit marker instead of a "When off"
 // label that would make the row read like a switch.
@@ -46,6 +47,8 @@ export const CAPABILITY_LOCALES = [
   { specifier: 'import', component: 'tower-import' },
   { specifier: 'leases', component: 'tower-leases' },
   { specifier: 'tests', component: 'tower-tests' },
+  { specifier: 'board', component: 'tower-board' },
+  { specifier: 'archive', component: 'tower-archive' },
   { specifier: 'hmr', component: 'tower-hmr' },
 ]
 

package/scripts/mount-smoke/surface.mjs

@@ -29,7 +29,9 @@ export const BUNDLE_CHILD_IDS = ['preset-tower-worker', 'tower-host']
 /** The optional capability rows that sit at the top level beside the host. */
 export const OPTIONAL_ROW_IDS = [
   'preset-tower-reviewer',
+  'tower-archive',
   'tower-batch',
+  'tower-board',
   'tower-hmr',
   'tower-import',
   'tower-leases',

package/scripts/pack-manifest.txt

@@ -1,6 +1,7 @@
 CHANGELOG.md
 COMPATIBILITY.md
 CONTRIBUTING.md
+GLOSSARY.md
 LICENSE
 PRINCIPLES.md
 README.en.md
@@ -45,6 +46,7 @@ app/spawn-support.js
 app/spawn.js
 app/teardown.js
 app/tower.js
+client.js
 cordis.patch.yml
 docs/README.md
 docs/adr/0001-ports-adapters-as-data.md
@@ -102,6 +104,7 @@ domain/collab/batch.js
 domain/collab/messages.js
 domain/collab/roster.js
 domain/collab/spawn.js
+domain/component-rules.js
 domain/components.js
 domain/config/schema.js
 domain/contracts/outputs.js
@@ -145,7 +148,9 @@ domain/state/semantics.js
 domain/summary.js
 domain/surface.js
 domain/vocabulary.js
+host/capability-archive.js
 host/capability-batch.js
+host/capability-board.js
 host/capability-hmr.js
 host/capability-import.js
 host/capability-leases.js
@@ -164,8 +169,12 @@ host/tool-registry.js
 host/tower.js
 icon.svg
 index.js
+locale/archive/en.json
+locale/archive/zh.json
 locale/batch/en.json
 locale/batch/zh.json
+locale/board/en.json
+locale/board/zh.json
 locale/en.json
 locale/hmr/en.json
 locale/hmr/zh.json
@@ -225,6 +234,7 @@ scripts/mount-smoke/surface.mjs
 scripts/pack-manifest.txt
 scripts/regression-audit.mjs
 scripts/release-check.mjs
+scripts/release-notes.mjs
 scripts/surface-baseline.json
 scripts/surface-baseline.mjs
 scripts/types-coverage.mjs

package/scripts/release-notes.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Cumulative Release notes.
+//
+// Policy: every GitHub Release aggregates every CHANGELOG section since the
+// previous GitHub Release, not just the section that names its own version.
+// Tag-only versions have no Release, so their sections roll into the next
+// Release. Example: when 2.1.0 was the previous Release, the 2.3.0 Release
+// includes 2.1.1, 2.1.2, 2.2.0 and 2.3.0; 2.1.0-beta.1 is older than 2.1.0 and
+// stays out of the window.
+//
+// The script is the authority for a Release body: it reads `<root>/CHANGELOG.md`
+// and emits
+//
+//   # dsh-tower <version>
+//
+//   > <provenance line naming the previous Release>
+//
+//   ---
+//
+//   <CHANGELOG section> --- <CHANGELOG section> ...
+//
+// in ascending SemVer order (`1.0.0-beta.2 < 1.0.0-beta.10 < 1.0.0`). The
+// window is `since < v <= version`. `--check <file>` compares an existing notes
+// file byte-for-byte with the generated text so a published Release body can be
+// re-verified.
+//
+// Usage:
+//   node scripts/release-notes.mjs --version <semver> --since <semver> \
+//     [--output <file>] [--check <file>] [--root <dir>]
+//
+// Exit codes: 0 success or matching --check; 1 --check mismatch; 2 bad
+// arguments, an unreadable CHANGELOG, `since >= version`, or an empty window.
+import fs from 'node:fs'
+import path from 'node:path'
+import { compareVersions } from '../host/compatibility.js'
+import { parseArgs, runMain, UsageError } from './lib/cli.mjs'
+
+const USAGE = `usage: node scripts/release-notes.mjs --version <semver> --since <semver>
+                                     [--output <file>] [--check <file>] [--root <dir>] [--help]
+
+  --version  release version to generate notes for (required, e.g. 2.3.0)
+  --since    previous GitHub Release version, exclusive (required, e.g. 2.1.0)
+  --output   write the notes to this file instead of stdout
+  --check    compare the generated notes with this file byte-for-byte
+  --root     repository root that holds CHANGELOG.md (default: current directory)
+  --help     print this text
+
+A version may be written with or without its "v" tag prefix. The window
+(since, version] is emitted in ascending SemVer order, so tag-only versions
+between the two Releases are included.`
+
+// SemVer 2.0.0 without build metadata: X.Y.Z with an optional pre-release.
+// Numeric core and numeric pre-release identifiers have no leading zeros, so
+// "2.3.0" is a version and "2.3" or "2.3.0-01" are not.
+const SEMVER =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?$/
+
+// A level-2 heading whose first token is a version. The loose token keeps the
+// pre-release suffix intact (`2.1.0-beta.1`, not `2.1.0`); SEMVER then rejects
+// a heading such as `## Unreleased`. `### Added` never matches: the third `#`
+// is not whitespace.
+const HEADING = /^##[ \t]+(?:\[[ \t]*)?v?([0-9A-Za-z.-]+)/
+
+function usageError(message) {
+  const error = new UsageError(message)
+  error.showUsage = true
+  return error
+}
+
+function normalizeVersion(value, flag) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw usageError(`${flag} <semver> is required`)
+  }
+  const text = value.trim().replace(/^v/, '')
+  if (!SEMVER.test(text)) {
+    throw usageError(`${flag} ${JSON.stringify(value)} is not a SemVer version (expected X.Y.Z or X.Y.Z-pre)`)
+  }
+  return text
+}
+
+/**
+ * Read every `## <version>` section from CHANGELOG text, in file order.
+ *
+ * The body ends at the next level-2 heading. Leading and trailing blank lines
+ * are dropped, so a section touched by the next heading without an intervening
+ * blank line (the real CHANGELOG has a few) still produces stable output.
+ * Duplicate version headings are a malformed changelog, not a choice.
+ */
+export function extractSections(changelog) {
+  const lines = String(changelog ?? '').split(/\r?\n/)
+  const sections = []
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = HEADING.exec(lines[index])
+    if (!match || !SEMVER.test(match[1])) continue
+    const body = []
+    let cursor = index + 1
+    while (cursor < lines.length && !/^##[ \t]/.test(lines[cursor])) {
+      body.push(lines[cursor])
+      cursor += 1
+    }
+    while (body.length > 0 && body[0].trim() === '') body.shift()
+    while (body.length > 0 && body[body.length - 1].trim() === '') body.pop()
+    const heading = lines[index].trimEnd()
+    sections.push({
+      version: match[1],
+      heading,
+      body: body.join('\n'),
+      text: body.length > 0 ? `${heading}\n\n${body.join('\n')}` : heading,
+    })
+    index = cursor - 1
+  }
+  const seen = new Set()
+  for (const section of sections) {
+    if (seen.has(section.version)) {
+      throw new Error(`CHANGELOG.md has more than one section for version ${section.version}`)
+    }
+    seen.add(section.version)
+  }
+  return sections
+}
+
+/**
+ * Build the cumulative Release body for `version`, containing every CHANGELOG
+ * section with `since < v <= version` in ascending SemVer order.
+ */
+export function generateReleaseNotes({ changelog, version, since }) {
+  const target = normalizeVersion(version, '--version')
+  const previous = normalizeVersion(since, '--since')
+  const relation = compareVersions(target, previous)
+  if (relation !== null && relation <= 0) {
+    throw usageError(`--since ${previous} must be older than --version ${target}`)
+  }
+  const sections = extractSections(changelog)
+    .filter((section) => {
+      const afterSince = compareVersions(section.version, previous)
+      const atOrBeforeTarget = compareVersions(section.version, target)
+      return afterSince > 0 && atOrBeforeTarget <= 0
+    })
+    .sort((left, right) => compareVersions(left.version, right.version))
+
+  if (sections.length === 0) {
+    throw usageError(
+      `no CHANGELOG section falls in the window (${previous}, ${target}]; ` +
+        'bump the changelog or check --since (it is the previous GitHub Release, not the previous tag)',
+    )
+  }
+
+  const versions = sections.map((section) => section.version)
+  const quote =
+    versions.length === 1
+      ? `> 自上一个 Release \`v${previous}\` 起的变更。`
+      : `> 本 Release 包含自上一个 Release \`v${previous}\` 以来的全部变更：${versions.join('、')}。`
+  const text = `# dsh-tower ${target}\n\n${quote}\n\n---\n\n${sections
+    .map((section) => section.text)
+    .join('\n\n---\n\n')}\n`
+  return { version: target, since: previous, versions, sections, text }
+}
+
+function firstDifference(expected, actual) {
+  const expectedLines = expected.split('\n')
+  const actualLines = actual.split('\n')
+  const limit = Math.max(expectedLines.length, actualLines.length)
+  for (let index = 0; index < limit; index += 1) {
+    if (expectedLines[index] !== actualLines[index]) {
+      return {
+        line: index + 1,
+        expected: expectedLines[index] ?? '<end of file>',
+        actual: actualLines[index] ?? '<end of file>',
+      }
+    }
+  }
+  return null
+}
+
+function compareWithFile(file, result) {
+  const expected = Buffer.from(result.text, 'utf8')
+  let existing
+  try {
+    existing = fs.readFileSync(file)
+  } catch (error) {
+    console.error(`release-notes: cannot read ${file}: ${error?.message ?? error}`)
+    return 2
+  }
+  if (existing.equals(expected)) {
+    console.log(
+      `release-notes: ${file} matches the generated notes for ${result.version} ` +
+        `(${result.versions.length} section(s): ${result.versions.join(', ')})`,
+    )
+    return 0
+  }
+  const found = existing.toString('utf8')
+  const difference = firstDifference(result.text, found)
+  console.error(`release-notes: ${file} does not match the generated notes for ${result.version}`)
+  if (difference) {
+    console.error(`  first difference at line ${difference.line}: expected ${JSON.stringify(difference.expected)}`)
+    console.error(`  found ${JSON.stringify(difference.actual)}`)
+  }
+  console.error(`  expected ${expected.length} bytes, found ${existing.length} bytes`)
+  return 1
+}
+
+function cli(argv) {
+  const options = parseArgs(argv, {
+    initial: { version: null, since: null, output: null, check: null, root: null, help: false },
+    values: {
+      '--version': 'version',
+      '--since': 'since',
+      '--output': 'output',
+      '--check': 'check',
+      '--root': 'root',
+    },
+    flags: { '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  if (options.output && options.check) {
+    throw usageError('--output and --check are mutually exclusive')
+  }
+
+  const root = path.resolve(options.root ?? process.cwd())
+  const changelogPath = path.join(root, 'CHANGELOG.md')
+  let changelog
+  try {
+    changelog = fs.readFileSync(changelogPath, 'utf8')
+  } catch (error) {
+    console.error(`release-notes: cannot read ${changelogPath}: ${error?.message ?? error}`)
+    return 2
+  }
+
+  let result
+  try {
+    result = generateReleaseNotes({ changelog, version: options.version, since: options.since })
+  } catch (error) {
+    // UsageError messages already name the offending flag; file/data errors are
+    // reported with the same prefix and exit 2 (never a partial Release).
+    console.error(`release-notes: ${error?.message ?? error}`)
+    if (error?.showUsage) console.error(USAGE)
+    return 2
+  }
+
+  if (options.check) return compareWithFile(path.resolve(options.check), result)
+  if (options.output) {
+    const outputPath = path.resolve(options.output)
+    fs.writeFileSync(outputPath, result.text, 'utf8')
+    console.log(
+      `release-notes: wrote ${outputPath} (${result.versions.length} section(s): ${result.versions.join(', ')})`,
+    )
+    return 0
+  }
+  process.stdout.write(result.text)
+  return 0
+}
+
+await runMain(import.meta.url, () => cli(process.argv.slice(2)), { errorPrefix: 'release-notes', usage: USAGE })

package/scripts/surface-baseline.json

@@ -4,8 +4,23 @@
   "surfaces": {
     "configKeys": {
       "seed": 64,
-      "value": 56,
-      "decisions": []
+      "value": 54,
+      "decisions": [
+        {
+          "from": 64,
+          "to": 53,
+          "date": "2026-11-03",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "Recorded contraction, not a free ratchet (#138). #121 removed the seven tools.expose* keys plus dev.hotReload, #136 replaced tests.enabled with the tower-tests row, and #133/#135 replaced docs.board/archive.enabled with the tower-board/tower-archive rows. The chain now continues here: the config-key surface is two-way like components, so any later increase or decrease needs its own dated decision."
+        },
+        {
+          "from": 53,
+          "to": 54,
+          "date": "2026-11-03",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#M39: one new key, review.mode (off/optional/required), replaces the deprecated review.requireReview boolean as the review policy. It is not a fifth component row: the reviewer preset row stays a capability, and the mode decides whether it is required (required) or unused (off). review.requireReview remains accepted for one release as a normalized alias, so it is a deprecated key rather than a removed one and the surface grows by exactly one."
+        }
+      ]
     },
     "sections": {
       "seed": 15,
@@ -30,7 +45,7 @@
     },
     "components": {
       "seed": 4,
-      "value": 8,
+      "value": 11,
       "decisions": [
         {
           "from": 4,
@@ -45,6 +60,27 @@
           "date": "2026-10-23",
           "adr": "docs/adr/0005-component-surface.md",
           "note": "#121 restores the #65 policy from ADR 0005: the one tower-bundle group becomes a mandatory tower host anchor plus seven individually switchable optional rows (tower-skills, tower-batch, tower-import, tower-leases, tower-tests, tower-hmr shipped off, preset-tower-reviewer conditional). The host anchor and preset-tower-worker stay mandatory; tower_doctor and tower_recover stay mandatory with the host (#122), so they are not rows. configKeys and sections shrank in the same wave because the seven tools.expose* keys and dev.hotReload became rows."
+        },
+        {
+          "from": 8,
+          "to": 9,
+          "date": "2026-11-02",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#133: `docs.board` was a capability wearing a tuning-key costume. The visible tower-board row owns the MISSIONS.md board now; `docs.boardLocation` stays tuning. Off writes no board."
+        },
+        {
+          "from": 9,
+          "to": 10,
+          "date": "2026-11-02",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#135: `archive.enabled` was the same costume. The visible tower-archive row owns archival now; `afterDays`/`maxMissions` stay tuning. Off keeps terminal missions hot, so state keeps growing."
+        },
+        {
+          "from": 10,
+          "to": 11,
+          "date": "2026-11-02",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#134: the gate reads every shipped cordis.patch.yml, so the tower-ui row in ui-bundle/cordis.patch.yml joins the counted surface. The row was always shipped and unclassified; counting it is not new surface, it is the existing surface becoming visible to the policy."
         }
       ]
     }