dsh-tower 2.3.0 → 2.4.1

package/index.js

@@ -12,7 +12,7 @@
 // plugin from disk when the HMR service is present (dev/linked installs).
 import fs from 'node:fs'
 import { randomUUID } from 'node:crypto'
-import { registerTowerTools } from './host/tool-registry.js'
+import { registerCoreTowerTools, recordToolRegistration } from './host/tool-registry.js'
 import { createDefaultDeps } from './adapters/default.js'
 import { loadModes, saveModes, storePath } from './host/modeStore.js'
 import { ModeState } from './host/modeState.js'
@@ -26,8 +26,8 @@ import {
   touchWorkspaceLock,
   workspaceLockToken,
 } from './adapters/workspaceLock.js'
-import { createHmrBridge } from './host/hmr.js'
-import { assertPresetsAvailable } from './host/presets.js'
+import { assertRuntimePreconditions } from './host/presets.js'
+import { currentHmrBridge } from './host/capability-registry.js'
 
 export const name = 'dsh-tower'
 export const inject = ['tools', 'systemPrompt']
@@ -256,14 +256,6 @@ export function apply(ctx, rawConfig) {
   modeState.replace(loadModes(config.mode.storePath || undefined))
   if (typeof ctx.provide === 'function') ctx.provide('tower', modeState)
   denyTools = new Set(config.mode.denyTools)
-  const hotReloadEnabled = config.dev?.hotReload !== false
-  const hmrBridge = hotReloadEnabled
-    ? createHmrBridge(ctx, {
-        requiredIds: config.dev?.reloadRequiredIds,
-        delayMs: config.dev?.reloadDelayMs,
-        logger: ctx.logger ?? console,
-      })
-    : null
 
   const workspace = {
     /** Lazily acquire the advisory workspace lock on the first repo-scoped tool. */
@@ -346,12 +338,24 @@ export function apply(ctx, rawConfig) {
 
   // #69: the host entry is the composition root — the adapters are constructed
   // once here and injected into the tool layer and every Tower instance.
-  registerTowerTools(ctx, { workspace, hmrBridge, deps: createDefaultDeps() })
+  // #121: only the mandatory host surface is registered here. The optional
+  // capability rows (batch/import/leases/tests/hmr) are separate loader entries
+  // and register their own tools, so a disabled row removes exactly one
+  // capability.
+  registerCoreTowerTools(ctx, { workspace, deps: createDefaultDeps() })
+
+  // #118/#121: tower_mode/tower_control are registered directly here instead of
+  // through define(), so record them through the same recorder the registry
+  // uses. tower_control is recorded before the allowAgentControl gate: the
+  // concept budget measures the surface this build can register, not only the
+  // tools one profile exposes (#84). Together with the capability-tool names the
+  // registry records before row gating, these are the shipped 29.
+  recordToolRegistration('tower_mode')
+  recordToolRegistration('tower_control')
 
   // On dispose (including an HMR reload) release advisory workspace locks this
   // process still owns; a reloaded plugin restores the entries from modes.json.
   ctx.effect(() => () => {
-    if (hmrBridge) hmrBridge.dispose?.()
     for (const entry of modeState.values()) {
       if (entry?.lock) {
         releaseWorkspaceLock(entry.lock.commonDir, { token: entry.lock.token }).catch(() => {})
@@ -451,7 +455,12 @@ export function apply(ctx, rawConfig) {
           deniedWhileActive: [...denyTools],
           persistedAt: storePath(config.mode.storePath || undefined),
           pluginVersion: readPluginVersion(),
-          hotReload: hmrBridge ? hmrBridge.status() : { available: false, disabled: true },
+          hotReload: (() => {
+            // #121/#122: the tower-hmr component row owns the bridge. When the
+            // row is off the capability is reported, never silently absent.
+            const bridge = currentHmrBridge()
+            return bridge ? bridge.status() : { available: false, disabled: true, component: 'tower-hmr' }
+          })(),
           planMode: (() => {
             const state = planModeState(ctx, exec.agent)
             return { available: state.available, active: state.active, pending: state.pending }
@@ -507,7 +516,7 @@ export function apply(ctx, rawConfig) {
           }
           const reason = args.reason.trim()
           if (args.action === 'enter' && !modeOn(key)) {
-            await assertPresetsAvailable(ctx, config)
+            await assertRuntimePreconditions(ctx, config)
           }
           const outcome =
             args.action === 'enter'
@@ -558,20 +567,23 @@ export function apply(ctx, rawConfig) {
         }
         const parsed = parseTowerInput(rawInput)
         if (parsed.action === 'reload') {
-          if (!hotReloadEnabled) {
-            return { kind: 'error', text: 'Tower reload is disabled by dev.hotReload:false; restart DSH instead.' }
+          // #121: /tower reload is the tower-hmr component. The row is shipped
+          // off, so the error names the component instead of an invisible key.
+          const bridge = currentHmrBridge()
+          if (!bridge) {
+            return { kind: 'error', text: 'Tower reload is disabled by component tower-hmr; enable the tower-hmr row in the plugin page and restart DSH.' }
           }
-          if (!hmrBridge || !hmrBridge.available) {
+          if (!bridge.available) {
             return { kind: 'error', text: 'Tower reload is unavailable: this DSH profile has no HMR service. Restart DSH instead.' }
           }
-          const outcome = hmrBridge.schedule()
+          const outcome = bridge.schedule()
           return {
             kind: 'success',
             text: `Tower reload scheduled in ${outcome.delayMs}ms (required entries: ${outcome.requiredIds.join(', ')}). If the new code does not appear, restart DSH.`,
           }
         }
         const { active, message } = parsed
-        if (active) await assertPresetsAvailable(ctx, config)
+        if (active) await assertRuntimePreconditions(ctx, config)
         const outcome = active
           ? enterMode(ctx, key, agent, 'user', message || null)
           : await exitMode(key, 'user', message || null)

package/locale/batch/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Evidence batches",
+    "description": "Group missions into finite evidence batches and close them against required checks and receipts. When off: tower_batch is not registered; missions, gates and merges are unaffected."
+  }
+}

package/locale/batch/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "证据批次",
+    "description": "把 mission 归入有限证据批次，并按必需检查与回执关闭批次。关闭后：不再注册 tower_batch；mission、门禁与合并不受影响。"
+  }
+}

package/locale/en.json

@@ -4,25 +4,45 @@
     "description": "Mission planning, isolated worktrees, worker/reviewer agents, and review-gated merges."
   },
   "components": {
-    "tower-bundle": {
-      "title": "Tower",
-      "summary": "Mission planning, isolated worktrees, worker/reviewer agents, and merge gates.",
-      "disables": "Turns off the whole Tower bundle; no orphan preset or skill is left behind."
+    "tower": {
+      "title": "Tower host",
+      "summary": "Mission planning, worktree isolation, the mode guard, the health contract and the recovery escape.",
+      "disables": "Turns off the mandatory host; this equals uninstalling Tower: no tools, presets or skills remain."
     },
     "tower-skills": {
       "title": "Tower skills",
       "summary": "Playbooks for worker/reviewer agents and recovery after a blocked merge.",
-      "disables": "Internal section; toggled with the Tower bundle."
+      "disables": "The three Tower skills leave the catalog; the worker/reviewer protocol sections and every mission tool keep working."
     },
-    "preset-tower-worker": {
-      "title": "Tower worker",
-      "summary": "Writes code, runs verification, and commits only the files assigned to its mission.",
-      "disables": "Internal section; a missing preset is rejected before planning/mode entry."
+    "tower-batch": {
+      "title": "Evidence batches",
+      "summary": "Group missions into finite evidence batches and close them against required checks and receipts.",
+      "disables": "tower_batch is not registered; missions, gates and merges are unaffected."
+    },
+    "tower-import": {
+      "title": "Legacy import",
+      "summary": "Import a Tower Codex legacy state file and audit its snapshot-to-mission mapping.",
+      "disables": "tower_import_legacy and tower_legacy_map are not registered; new state is unaffected."
+    },
+    "tower-leases": {
+      "title": "Advisory leases",
+      "summary": "Coordinate heavy per-repository work with advisory resource leases.",
+      "disables": "tower_resource is not registered; nothing else depends on a lease."
+    },
+    "tower-tests": {
+      "title": "Test discovery",
+      "summary": "Run the worktree's declared test discovery and record a receipt for the mission tip.",
+      "disables": "tower_test is not registered and no receipt can be recorded; with gates.requireTests:true planning/mode entry is rejected with an explanation."
+    },
+    "tower-hmr": {
+      "title": "Dev hot reload",
+      "summary": "Register tower_reload and /tower reload for linked-profile development.",
+      "disables": "tower_reload and /tower reload are unavailable; a non-HMR profile behaves exactly as before. Shipped off."
     },
     "preset-tower-reviewer": {
       "title": "Tower reviewer",
-      "summary": "Read-only checks for scope and acceptance, returning a clean verdict or findings.",
-      "disables": "Internal section; a missing preset is rejected before planning/mode entry when review is required."
+      "summary": "Read-only independent review: inspect the mission diff, verify scope and acceptance, return a verdict.",
+      "disables": "The reviewer cannot be dispatched. Supported while review.requireReview is false; with the gate on planning/mode entry is locked with an explanatory error."
     }
   }
 }

package/locale/hmr/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Dev hot reload",
+    "description": "Register tower_reload and /tower reload for linked-profile development. When off: tower_reload and /tower reload are unavailable; a non-HMR profile behaves exactly as before. Shipped off."
+  }
+}

package/locale/hmr/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "开发热重载",
+    "description": "为联动开发 profile 注册 tower_reload 与 /tower reload。关闭后：tower_reload 与 /tower reload 不可用；非 HMR profile 的行为与之前完全相同。随包默认关闭。"
+  }
+}

package/locale/import/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Legacy import",
+    "description": "Import a Tower Codex legacy state file and audit its snapshot-to-mission mapping. When off: tower_import_legacy and tower_legacy_map are not registered; new state is unaffected."
+  }
+}

package/locale/import/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "旧版导入",
+    "description": "导入 Tower Codex 旧状态文件，并审计快照到 mission 的映射。关闭后：不再注册 tower_import_legacy 与 tower_legacy_map；新状态不受影响。"
+  }
+}

package/locale/leases/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Advisory leases",
+    "description": "Coordinate heavy per-repository work with advisory resource leases. When off: tower_resource is not registered; nothing else depends on a lease."
+  }
+}

package/locale/leases/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "咨询式租约",
+    "description": "用咨询式资源租约协调每个仓库中的重型工作。关闭后：不再注册 tower_resource；其他能力不依赖租约。"
+  }
+}

package/locale/skills/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tower skills",
+    "description": "Playbooks for worker/reviewer agents and recovery after a blocked merge. When off: The three Tower skills leave the catalog; the worker/reviewer protocol sections and every mission tool keep working."
+  }
+}

package/locale/skills/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tower 技能包",
+    "description": "执行与审查代理的操作手册，以及失败后的恢复指南。关闭后：三个 Tower 技能从目录中移除；执行/审查协议段落与所有 mission 工具继续工作。"
+  }
+}

package/locale/tests/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Test discovery",
+    "description": "Run the worktree's declared test discovery and record a receipt for the mission tip. When off: tower_test is not registered and no receipt can be recorded; with gates.requireTests:true planning/mode entry is rejected with an explanation."
+  }
+}

package/locale/tests/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "测试发现",
+    "description": "运行 worktree 声明的测试发现，并为 mission tip 记录回执。关闭后：不再注册 tower_test，也无法记录回执；若 gates.requireTests:true，规划/进入模式会以解释性错误拒绝。"
+  }
+}

package/locale/zh.json

@@ -4,25 +4,45 @@
     "description": "多代理任务规划、隔离工作树与审查门禁合并。"
   },
   "components": {
-    "tower-bundle": {
+    "tower": {
       "title": "Tower 控制塔",
-      "summary": "任务规划、隔离工作树、执行/审查代理与合并门禁。",
-      "disables": "关闭后整个 Tower 一起停用；不会留下孤立的代理预设或技能。"
+      "summary": "任务规划、隔离工作树、模式守卫、健康契约与恢复逃生口。",
+      "disables": "关闭强制主组件等同于卸载 Tower：不再保留任何工具、preset 或技能。"
     },
     "tower-skills": {
       "title": "Tower 技能包",
       "summary": "执行与审查代理的操作手册，以及失败后的恢复指南。",
-      "disables": "内部 section；随 Tower 整体启停。"
+      "disables": "三个 Tower 技能从目录中移除；执行/审查协议段落与所有 mission 工具继续工作。"
     },
-    "preset-tower-worker": {
-      "title": "Tower 执行代理",
-      "summary": "在独立分支里写代码、跑验证并提交，只改分给它的文件。",
-      "disables": "内部 section；缺失时会在规划/进入模式前被拒绝。"
+    "tower-batch": {
+      "title": "证据批次",
+      "summary": "把 mission 归入有限证据批次，并按必需检查与回执关闭批次。",
+      "disables": "不再注册 tower_batch；mission、门禁与合并不受影响。"
+    },
+    "tower-import": {
+      "title": "旧版导入",
+      "summary": "导入 Tower Codex 旧状态文件，并审计快照到 mission 的映射。",
+      "disables": "不再注册 tower_import_legacy 与 tower_legacy_map；新状态不受影响。"
+    },
+    "tower-leases": {
+      "title": "咨询式租约",
+      "summary": "用咨询式资源租约协调每个仓库中的重型工作。",
+      "disables": "不再注册 tower_resource；其他能力不依赖租约。"
+    },
+    "tower-tests": {
+      "title": "测试发现",
+      "summary": "运行 worktree 声明的测试发现，并为 mission tip 记录回执。",
+      "disables": "不再注册 tower_test，也无法记录回执；若 gates.requireTests:true，规划/进入模式会以解释性错误拒绝。"
+    },
+    "tower-hmr": {
+      "title": "开发热重载",
+      "summary": "为联动开发 profile 注册 tower_reload 与 /tower reload。",
+      "disables": "tower_reload 与 /tower reload 不可用；非 HMR profile 的行为与之前完全相同。随包默认关闭。"
     },
     "preset-tower-reviewer": {
       "title": "Tower 审查代理",
-      "summary": "只读检查改动是否越界、是否达标，给出通过或问题清单。",
-      "disables": "内部 section；缺失且强制审查时会在规划/进入模式前被拒绝。"
+      "summary": "只读独立审查：检查 mission diff、核对范围与验收，给出结论。",
+      "disables": "无法派发审查代理。review.requireReview 为 false 时允许关闭；强制审查开启时规划/进入模式会被锁定并给出解释。"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -31,6 +31,17 @@
     "./worker": "./worker.js",
     "./reviewer": "./reviewer.js",
     "./skills": "./skills.js",
+    "./batch": "./host/capability-batch.js",
+    "./import": "./host/capability-import.js",
+    "./leases": "./host/capability-leases.js",
+    "./tests": "./host/capability-tests.js",
+    "./hmr": "./host/capability-hmr.js",
+    "./skills/locale/*.json": "./locale/skills/*.json",
+    "./batch/locale/*.json": "./locale/batch/*.json",
+    "./import/locale/*.json": "./locale/import/*.json",
+    "./leases/locale/*.json": "./locale/leases/*.json",
+    "./tests/locale/*.json": "./locale/tests/*.json",
+    "./hmr/locale/*.json": "./locale/hmr/*.json",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
     "./package.json": "./package.json"
@@ -49,7 +60,7 @@
     "types/",
     "cordis.patch.yml",
     "scripts/",
-    "locale/*.json",
+    "locale/",
     "icon.svg",
     "README.md",
     "README.en.md",
@@ -90,10 +101,20 @@
     "docs:check:generated:config": "node scripts/generate-config-reference.mjs --check",
     "docs:generate:events": "node scripts/generate-events-reference.mjs",
     "docs:check:generated:events": "node scripts/generate-events-reference.mjs --check",
+    "types:generate": "node scripts/generate-types.mjs",
+    "docs:check:generated:types": "node scripts/generate-types.mjs --check",
+    "docs:generate:components": "node scripts/generate-component-surface.mjs",
+    "docs:check:generated:components": "node scripts/generate-component-surface.mjs --check",
+    "docs:generate:locale": "node scripts/generate-capability-locale.mjs",
+    "docs:check:generated:locale": "node scripts/generate-capability-locale.mjs --check",
+    "docs:check:components": "node scripts/check-components.mjs",
     "pack:check": "node scripts/check-pack.mjs",
     "architecture:check": "node scripts/architecture.mjs",
-    "types:check": "tsc --noEmit",
-    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
+    "types:check": "tsc --noEmit && tsc -p tsconfig.strict.json",
+    "types:coverage": "node scripts/types-coverage.mjs",
+    "types:strict:check": "node scripts/types-strict.mjs",
+    "types:strict:write": "node scripts/types-strict.mjs --write",
+    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run docs:check:generated:types && npm run docs:check:generated:components && npm run docs:check:generated:locale && npm run docs:check:components && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:coverage && npm run types:strict:check && npm run types:check && npm run domain:check",
     "domain:metrics": "node scripts/domain-metrics.mjs",
     "domain:check": "node scripts/domain-metrics.mjs --check"
   },

package/scripts/check-components.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Component-surface policy gate (#120).
+//
+// Principle 11 says optional capabilities are switches and the core is not. This
+// gate is what makes that a rule instead of a slogan. It fails on:
+//
+//   1. a visible component without `title`, `summary` and `disables` in both
+//      locale/en.json and locale/zh.json;
+//   2. a forbidden-to-disable capability (host, health, recovery, review
+//      contract, 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).
+//
+// 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
+// component-axis class, and a generated reference that is out of date.
+//
+// The single source of truth is `scripts/component-surface.json`; the generated
+// table is `docs/reference/component-surface.md`; the policy is recorded in
+// `docs/adr/0005-component-surface.md`.
+//
+// Usage:
+//   node scripts/check-components.mjs [--root <dir>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Config, configSurface } from '../domain/config/schema.js'
+import {
+  COMPONENT_REFERENCE_FILE,
+  COMPONENT_SURFACE_FILE,
+  LOCALE_FILES,
+  checkForbidden,
+  checkLocaleCoverage,
+  parseComponentSurface,
+  parseCordisPatch,
+  parseOperationalRegistry,
+  renderComponentSurface,
+  validateComponentSurface,
+} from '../domain/components.js'
+import { validateSurfaceBaselineKey } from '../domain/surface.js'
+import { readBaseline } from './lib/surface.mjs'
+import { parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const REGISTRY_FILE = 'host/tool-registry.js'
+const PATCH_FILE = 'cordis.patch.yml'
+const USAGE = `usage: node scripts/check-components.mjs [--root <dir>] [--json]
+
+  --root   repository root to check (default: this package)
+  --json   print the report as JSON
+  --help   print this text
+
+Fails on a visible component without title/summary/disables in both locale files,
+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, and a stale generated reference.
+Regenerate the table with \`npm run docs:generate:components\`.`
+
+function finding(code, level, message) {
+  return { code, level, message }
+}
+
+/** The live boolean config keys, derived from the schemastery schema. */
+function liveBooleanKeys() {
+  const keys = []
+  for (const [key, schema] of Object.entries(Config.dict ?? {})) {
+    const dict = schema?.dict
+    if (dict && typeof dict === 'object') {
+      for (const [child, childSchema] of Object.entries(dict)) {
+        if (childSchema?.type === 'boolean') keys.push(`${key}.${child}`)
+      }
+    } else if (schema?.type === 'boolean') {
+      keys.push(key)
+    }
+  }
+  return keys
+}
+
+/**
+ * The static wiring that lets a boolean key remove a tool: the OPERATIONAL_TOOLS
+ * table in host/tool-registry.js. Parsing it (rather than importing the runtime)
+ * keeps the denylist check offline and free of a booted Host. The parser accepts
+ * both the tuple and the `Map.set(...)` forms, and a trailing comma (F11), so a
+ * reformatted table cannot fall out of the allowlist.
+ */
+function operationalRegistry(root) {
+  const file = path.join(root, REGISTRY_FILE)
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+  return parseOperationalRegistry(text)
+}
+
+/** Read the live inputs the pure checks need: schema, patch, locales, registry. */
+export function componentCheckData(root) {
+  const config = configSurface()
+  const patchFile = path.join(root, PATCH_FILE)
+  const patch = fs.existsSync(patchFile)
+    ? parseCordisPatch(fs.readFileSync(patchFile, 'utf8'))
+    : { rows: [], visible: [] }
+  const locales = {}
+  for (const file of LOCALE_FILES) {
+    const localeFile = path.join(root, file)
+    locales[file] = fs.existsSync(localeFile) ? JSON.parse(fs.readFileSync(localeFile, 'utf8')) : null
+  }
+  return {
+    configKeys: config.keys,
+    sections: config.sections,
+    booleans: liveBooleanKeys(),
+    registry: operationalRegistry(root),
+    patch,
+    locales,
+  }
+}
+
+/**
+ * Run every component-surface rule against one repository root.
+ * @param {string} root
+ * @returns {{ ok: boolean, surface: any, live: any, findings: Array<{ code: string, level: string, message: string }> }}
+ */
+export function checkComponents(root) {
+  const findings = []
+  const live = componentCheckData(root)
+  const surfaceFile = path.join(root, COMPONENT_SURFACE_FILE)
+  if (!fs.existsSync(surfaceFile)) {
+    return {
+      ok: false,
+      surface: null,
+      live,
+      findings: [finding('surface-missing', 'error', `${COMPONENT_SURFACE_FILE} is missing`)],
+    }
+  }
+  let surface
+  try {
+    surface = parseComponentSurface(fs.readFileSync(surfaceFile, 'utf8'))
+  } catch (error) {
+    return {
+      ok: false,
+      surface: null,
+      live,
+      findings: [finding('surface-invalid', 'error', `${COMPONENT_SURFACE_FILE}: ${String(error?.message ?? error)}`)],
+    }
+  }
+  findings.push(...validateComponentSurface(surface, { configKeys: live.configKeys, patch: live.patch }))
+  findings.push(...checkLocaleCoverage(surface, live.locales))
+  findings.push(...checkForbidden(surface, { booleans: live.booleans, registry: live.registry, patch: live.patch }))
+
+  // #122: an empty OPERATIONAL_TOOLS table is the expected state. Every route
+  // that does exist must still match the `gateableTools` allowlist, which
+  // checkForbidden enforces above; there is no "unreadable registry" failure to
+  // raise when the correct count is zero.
+
+  // The decision record must exist: the ADR is where the policy is argued.
+  if (!fs.existsSync(path.join(root, surface.adr))) {
+    findings.push(finding('adr-missing', 'error', `component surface names ${surface.adr}, which does not exist`))
+  }
+  for (const capability of surface.forbidden) {
+    const decision = capability.acceptedSwitches?.decision
+    if (!decision) continue
+    if (!fs.existsSync(path.join(root, decision.ref))) {
+      findings.push(
+        finding(
+          'forbidden-decision',
+          'error',
+          `forbidden capability ${capability.id} records a decision in ${decision.ref}, which does not exist`,
+        ),
+      )
+    }
+  }
+
+  // Check 3: the component count is a baselined surface. `surface:check` runs
+  // the full baseline; this narrow call keeps the component brake available in
+  // this gate too, so a moved count fails here without re-measuring the rest.
+  const visible = live.patch.visible
+  let baseline = null
+  try {
+    baseline = readBaseline(root)
+    findings.push(
+      ...validateSurfaceBaselineKey(
+        baseline,
+        'components',
+        { components: visible.length, liveNames: { components: visible } },
+        { exists: (relative) => fs.existsSync(path.join(root, relative)) },
+      ),
+    )
+  } catch (error) {
+    findings.push(finding('baseline-unreadable', 'error', `scripts/surface-baseline.json is unreadable: ${String(error?.message ?? error)}`))
+  }
+
+  // The reference is a rendering, not prose. There is exactly one way to update
+  // it: edit the source of truth and run the generator.
+  try {
+    const expected = renderComponentSurface(surface, { baselineDate: baseline?.date })
+    const referenceFile = path.join(root, COMPONENT_REFERENCE_FILE)
+    const actual = fs.existsSync(referenceFile) ? fs.readFileSync(referenceFile, 'utf8') : ''
+    if (actual !== expected) {
+      findings.push(
+        finding('reference-stale', 'error', `${COMPONENT_REFERENCE_FILE} is stale; run npm run docs:generate:components`),
+      )
+    }
+  } catch (error) {
+    findings.push(finding('reference-unreadable', 'error', `${COMPONENT_REFERENCE_FILE} cannot be rendered: ${String(error?.message ?? error)}`))
+  }
+
+  return { ok: findings.every((entry) => entry.level !== 'error'), surface, live, findings }
+}
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { root: PACKAGE_ROOT, json: false, help: false },
+    values: { '--root': { key: 'root', parse: path.resolve } },
+    flags: { '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const root = path.resolve(options.root)
+  const report = checkComponents(root)
+  if (options.json) {
+    console.log(JSON.stringify({ root, ...report }, null, 2))
+    return report.ok ? 0 : 1
+  }
+  if (report.surface) {
+    const visible = report.surface.components.filter((component) => component.scope === 'visible').length
+    const internal = report.surface.components.length - visible
+    console.log(
+      `components: ${visible} visible, ${internal} internal, ${report.surface.keys.length} config keys classified (${COMPONENT_SURFACE_FILE})`,
+    )
+  }
+  for (const item of report.findings) console.log(`components: ${item.level} [${item.code}] ${item.message}`)
+  if (report.ok) console.log('components: ok — locale coverage, the forbidden denylist and the component baseline hold')
+  else console.log(`components: ${report.findings.length} problem(s); see docs/adr/0005-component-surface.md`)
+  return report.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'components', usage: USAGE })

package/scripts/check-pack.mjs

@@ -10,6 +10,7 @@ import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { capabilityLocalePaths } from './generate-capability-locale.mjs'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const REQUIRED_FILES = [
@@ -17,6 +18,9 @@ const REQUIRED_FILES = [
   'index.js',
   'locale/en.json',
   'locale/zh.json',
+  // #121: every optional capability row explains itself on the Plugins page
+  // through a subpath locale resource, so those generated files are required.
+  ...capabilityLocalePaths(),
   'ui-bundle/index.js',
   'ui-bundle/package.json',
   'ui-bundle/cordis.patch.yml',