dsh-tower 2.4.1 → 2.5.0

package/domain/components.js

@@ -12,6 +12,12 @@
 //
 // This module is pure: no fs, no git. `scripts/check-components.mjs` supplies the
 // live schema, `cordis.patch.yml`, the locale files and the baseline.
+//
+// #138: the class/row-override rules live in `component-rules.js` so this module
+// stays under the architecture aggregate-size brake; they are re-exported here.
+import { collectConfigOverrides } from './component-rules.js'
+export { checkKeyClassifications, checkRowOverrides } from './component-rules.js'
+
 export const COMPONENT_SURFACE_FILE = 'scripts/component-surface.json'
 export const COMPONENT_REFERENCE_FILE = 'docs/reference/component-surface.md'
 export const COMPONENT_SCHEMA_VERSION = 1
@@ -20,6 +26,13 @@ export const COMPONENT_SCOPES = ['visible', 'internal']
 export const COMPONENT_KINDS = ['group', 'row']
 export const LOCALE_FILES = ['locale/en.json', 'locale/zh.json']
 export const LOCALE_FIELDS = ['title', 'summary', 'disables']
+// #134: every shipped Cordis patch has component rows, not only the root one.
+// `ui-bundle/cordis.patch.yml` ships the `tower-ui` row. Labels for its rows live
+// in that package's own locale files (a DSH row renders `meta.title` /
+// `meta.description`, not the root `components` block).
+export const COMPONENT_PATCH_FILES = ['cordis.patch.yml', 'ui-bundle/cordis.patch.yml']
+export const META_LABEL_PATCHES = ['ui-bundle/cordis.patch.yml']
+export const META_LOCALE_FILES = ['ui-bundle/locale/en.json', 'ui-bundle/locale/zh.json']
 
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
 
@@ -58,6 +71,7 @@ function normalizeComponent(entry, index) {
     scope,
     kind,
     fallback: text(entry.fallback, `components[${index}].fallback`),
+    allowedOverrides: stringList(entry.allowedOverrides, `components[${index}].allowedOverrides`),
   }
 }
 
@@ -71,6 +85,10 @@ function normalizeKey(entry, index) {
     name: text(entry.name, `keys[${index}].name`),
     class: className,
     note: text(entry.note, `keys[${index}].note`),
+    // #138: an `optional-config` boolean (or a recorded behaviour knob) needs a
+    // dated reason for staying a tuning key; the gate refuses the classification
+    // without it.
+    exemption: entry.exemption === undefined ? null : normalizeDecision(entry.exemption, `keys[${index}].exemption`),
   }
 }
 
@@ -134,35 +152,6 @@ function normalizeGateableTools(value) {
   })
 }
 
-/**
- * Parse the static `host/tool-registry.js` route table that lets a boolean
- * remove a tool. This is the denylist's live input, so it is deliberately
- * tolerant about formatting (F11): it accepts a tuple with a trailing comma and
- * a `Map.set(...)` route, so a reformatted or rewritten table cannot fall out of
- * the allowlist and silently legalise a forbidden switch.
- *
- * @param {string} source the registry module text
- * @returns {Record<string, string>} tool name -> expose flag (without `tools.`)
- */
-export function parseOperationalRegistry(source) {
-  const text = String(source ?? '')
-  /** @type {Record<string, string>} */
-  const registry = {}
-  // Tuple form: ['tower_batch', 'exposeBatch'] with an optional trailing comma.
-  for (const match of text.matchAll(
-    /\[\s*['"](tower_[a-z0-9_]+)['"]\s*,\s*['"](expose[A-Za-z0-9]+)['"]\s*,?\s*\]/g,
-  )) {
-    registry[match[1]] = match[2]
-  }
-  // Map form: OPERATIONAL_TOOLS.set('tower_batch', 'exposeBatch').
-  for (const match of text.matchAll(
-    /OPERATIONAL_TOOLS\s*\.\s*set\(\s*['"](tower_[a-z0-9_]+)['"]\s*,\s*['"](expose[A-Za-z0-9]+)['"]\s*\)/g,
-  )) {
-    registry[match[1]] = match[2]
-  }
-  return registry
-}
-
 /**
  * Parse and validate the single source of truth. Structural problems throw with
  * an actionable message; semantic problems are findings from the validators
@@ -203,6 +192,9 @@ export function parseComponentSurface(source) {
   const keys = value.keys.map(normalizeKey)
   const forbidden = Array.isArray(value.forbidden) ? value.forbidden.map(normalizeForbidden) : []
   const gateableTools = normalizeGateableTools(value.gateableTools)
+  // #138: non-boolean keys that gate behaviour cannot hide behind
+  // `optional-config`; they are reviewed on the same axis as booleans.
+  const behaviorKnobs = stringList(value.behaviorKnobs, 'component surface behaviorKnobs')
   const seen = (list, label) => {
     const names = new Set()
     for (const entry of list) {
@@ -220,7 +212,17 @@ export function parseComponentSurface(source) {
   if (!components.some((component) => component.scope === 'visible')) {
     throw componentError('component surface needs at least one visible component')
   }
-  return { schema: COMPONENT_SCHEMA_VERSION, date, adr, classes, components, keys, gateableTools, forbidden }
+  return {
+    schema: COMPONENT_SCHEMA_VERSION,
+    date,
+    adr,
+    classes,
+    components,
+    keys,
+    behaviorKnobs,
+    gateableTools,
+    forbidden,
+  }
 }
 
 /**
@@ -232,13 +234,13 @@ export function parseComponentSurface(source) {
  * sections rather than a single plugin.
  *
  * @param {string} text
- * @returns {{ rows: Array<{ id: string, scope: string, kind: string, group: boolean, overrides: string[] }>, visible: string[] }}
+ * @returns {{ rows: Array<{ id: string, scope: string, kind: string, group: boolean, overrides: string[], configOverrides: Array<{ key: string, value: string }>, patch?: string }>, visible: string[] }}
  */
 export function parseCordisPatch(text) {
   const lines = String(text ?? '').split(/\r?\n/)
   const insertIndex = lines.findIndex((line) => /^\s*-\s+insert:\s*$/.test(line))
   if (insertIndex < 0) return { rows: [], visible: [] }
-  /** @type {Array<{ id: string, scope: string, kind: string, group: boolean, overrides: string[], indent: number, line: number }>} */
+  /** @type {Array<{ id: string, scope: string, kind: string, group: boolean, overrides: string[], configOverrides: Array<{ key: string, value: string }>, indent: number, line: number }>} */
   const rows = []
   const stack = []
   let rowIndent = null
@@ -263,6 +265,7 @@ export function parseCordisPatch(text) {
         kind: 'row',
         group: false,
         overrides: [],
+        configOverrides: [],
         indent,
         line: index,
       })
@@ -287,11 +290,10 @@ export function parseCordisPatch(text) {
     }
     row.group = block.some((line) => /^\s*group:\s*true\s*$/.test(line))
     row.kind = row.group ? 'group' : 'row'
-    const overrides = new Set()
-    for (const line of block) {
-      for (const match of line.matchAll(/([A-Za-z0-9_-]+)\s*:\s*false\b/g)) overrides.add(match[1])
-    }
-    row.overrides = [...overrides]
+    row.configOverrides = row.group ? [] : collectConfigOverrides(lines, row)
+    // #138: keep the false-valued paths for the forbidden denylist, and the full
+    // override set for the "row matches the capability it owns" check.
+    row.overrides = row.configOverrides.filter((entry) => entry.value === 'false').map((entry) => entry.key)
   }
   return {
     rows: rows.map(({ line, indent, ...row }) => row),
@@ -299,13 +301,32 @@ export function parseCordisPatch(text) {
   }
 }
 
+/**
+ * Merge every shipped patch into the one live shape the policy checks compare
+ * against. Rows keep the file they came from, so a finding can name it.
+ *
+ * @param {Record<string, ReturnType<typeof parseCordisPatch>>} patches file -> parsed patch
+ * @returns {{ rows: Array<{ id: string, scope: string, kind: string, group: boolean, overrides: string[], patch: string }>, visible: string[] }}
+ */
+export function mergeCordisPatches(patches = {}) {
+  const files = Object.keys(patches)
+  const rows = []
+  for (const file of files) {
+    for (const row of patches[file]?.rows ?? []) rows.push({ ...row, patch: file })
+  }
+  return {
+    rows,
+    visible: rows.filter((row) => row.scope === 'visible').map((row) => row.id),
+  }
+}
+
 /**
  * The shipped shape and the classification must describe the same components and
  * config keys. This is the parity half of the gate: a row without a class, or a
  * class without a row, is an unowned decision.
  *
  * @param {ReturnType<typeof parseComponentSurface>} surface
- * @param {{ configKeys: string[], patch: ReturnType<typeof parseCordisPatch> }} live
+ * @param {{ configKeys: string[], patch: ReturnType<typeof mergeCordisPatches> }} live
  */
 export function validateComponentSurface(surface, live) {
   const findings = []
@@ -315,25 +336,25 @@ export function validateComponentSurface(surface, live) {
   for (const component of surface.components) {
     const row = shipped.get(component.id)
     if (!row) {
-      record('component-missing', `component surface lists "${component.id}" but cordis.patch.yml does not ship it`)
+      record('component-missing', `component surface lists "${component.id}" but no shipped cordis.patch.yml defines it`)
       continue
     }
     if (row.scope !== component.scope) {
       record(
         'component-scope',
-        `component "${component.id}" is ${component.scope} in the source of truth but ${row.scope} in cordis.patch.yml`,
+        `component "${component.id}" is ${component.scope} in the source of truth but ${row.scope} in ${row.patch ?? 'cordis.patch.yml'}`,
       )
     }
     if (row.kind !== component.kind) {
       record(
         'component-kind',
-        `component "${component.id}" is a ${component.kind} in the source of truth but a ${row.kind} in cordis.patch.yml`,
+        `component "${component.id}" is a ${component.kind} in the source of truth but a ${row.kind} in ${row.patch ?? 'cordis.patch.yml'}`,
       )
     }
   }
   for (const row of live.patch.rows) {
     if (!classified.has(row.id)) {
-      record('component-unclassified', `cordis.patch.yml ships component "${row.id}" but the source of truth does not classify it`)
+      record('component-unclassified', `${row.patch ?? 'cordis.patch.yml'} ships component "${row.id}" but the source of truth does not classify it`)
     }
   }
   const declared = new Set(surface.keys.map((key) => key.name))
@@ -364,15 +385,22 @@ export function validateComponentSurface(surface, live) {
  * shipped locale. The locale set itself must only name known components, so a
  * typo cannot pass as coverage.
  *
+ * `options.ids` restricts the required set to the components whose labels live in
+ * these locale files. #134: the `tower-ui` row ships in `ui-bundle/` and is
+ * labelled by that package's own `meta` block, not by the root `components` block.
+ *
  * @param {ReturnType<typeof parseComponentSurface>} surface
  * @param {Record<string, any>} locales file path -> parsed locale JSON
+ * @param {{ ids?: string[] }} [options]
  */
-export function checkLocaleCoverage(surface, locales) {
+export function checkLocaleCoverage(surface, locales, options = {}) {
   const findings = []
   const record = (code, message) => findings.push({ code, level: 'error', message })
   const known = new Set(surface.components.map((component) => component.id))
+  const required = options.ids === undefined ? null : new Set(options.ids)
   for (const component of surface.components) {
     if (component.scope !== 'visible') continue
+    if (required && !required.has(component.id)) continue
     for (const file of LOCALE_FILES) {
       const entry = locales?.[file]?.components?.[component.id]
       if (!entry || typeof entry !== 'object') {
@@ -393,6 +421,75 @@ export function checkLocaleCoverage(surface, locales) {
   return findings
 }
 
+/**
+ * #132: the plugin page renders a group row from the root locale `meta.title` /
+ * `meta.description`. The off consequence of the `tower` group (off equals
+ * uninstalling Tower) must therefore appear in `meta.description`, in every
+ * shipped language — otherwise the most important consequence is dead copy.
+ *
+ * @param {ReturnType<typeof parseComponentSurface>} surface
+ * @param {Record<string, any>} locales file path -> parsed locale JSON
+ */
+export function checkGroupLabelCoverage(surface, locales) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  for (const component of surface.components) {
+    if (component.scope !== 'visible' || component.kind !== 'group') continue
+    for (const file of LOCALE_FILES) {
+      const meta = locales?.[file]?.meta
+      const title = typeof meta?.title === 'string' ? meta.title.trim() : ''
+      const description = typeof meta?.description === 'string' ? meta.description.trim() : ''
+      if (!title) record('group-locale', `${file} misses meta.title for group component "${component.id}"`)
+      if (!description) {
+        record('group-locale', `${file} misses meta.description for group component "${component.id}"`)
+        continue
+      }
+      const disables = locales?.[file]?.components?.[component.id]?.disables
+      const consequence = typeof disables === 'string' ? disables.trim() : ''
+      if (!consequence) continue
+      if (!description.includes(consequence)) {
+        record(
+          'group-locale',
+          `${file} meta.description does not state the off consequence of group component "${component.id}"`,
+        )
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * #134: a row that ships in its own package is labelled by that package's
+ * `meta.title` / `meta.description`, and DSH shows the "when off" consequence in
+ * the description. Require both meta strings and the off marker for every
+ * visible row of a meta-labelled patch, in every language file it ships.
+ *
+ * @param {string[]} ids row ids whose labels live in `locales`
+ * @param {Record<string, any>} locales file path -> parsed locale JSON
+ * @param {Record<string, string>} markers language -> off-effect marker
+ */
+export function checkMetaLabelCoverage(ids, locales, markers) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  for (const id of ids) {
+    for (const [file, payload] of Object.entries(locales ?? {})) {
+      const lang = /([a-z]{2})\.json$/.exec(file)?.[1] ?? ''
+      const marker = markers?.[lang] ?? ''
+      const title = typeof payload?.meta?.title === 'string' ? payload.meta.title.trim() : ''
+      const description = typeof payload?.meta?.description === 'string' ? payload.meta.description.trim() : ''
+      if (!title) record('meta-locale', `row "${id}" misses meta.title in ${file}`)
+      if (!description) {
+        record('meta-locale', `row "${id}" misses meta.description in ${file}`)
+        continue
+      }
+      if (marker && !description.includes(marker)) {
+        record('meta-locale', `row "${id}" meta.description does not state the off consequence in ${file}`)
+      }
+    }
+  }
+  return findings
+}
+
 /**
  * The denylist. The host, the health contract, the recovery escape, the review
  * contract and the merge gates may not be turned off by any group, row or
@@ -427,15 +524,17 @@ export function checkForbidden(surface, live) {
   // row, whatever capability owns it. `gatedBy` is folded in so a contract key
   // recorded only on the capability still resolves to its full name.
   const forbiddenLeaves = new Map()
+  const remember = (name) => {
+    const leaf = name.split('.').pop()
+    if (!forbiddenLeaves.has(name)) forbiddenLeaves.set(name, name)
+    if (!forbiddenLeaves.has(leaf)) forbiddenLeaves.set(leaf, name)
+  }
   for (const key of surface.keys) {
     if (key.class !== 'forbidden-to-disable') continue
-    forbiddenLeaves.set(key.name.split('.').pop(), key.name)
+    remember(key.name)
   }
   for (const capability of surface.forbidden) {
-    for (const key of capability.gatedBy ?? []) {
-      const leaf = key.split('.').pop()
-      if (!forbiddenLeaves.has(leaf)) forbiddenLeaves.set(leaf, key)
-    }
+    for (const key of capability.gatedBy ?? []) remember(key)
   }
   for (const row of rows) {
     if (row.scope === 'visible' && forbiddenRowIds.has(row.id)) {
@@ -547,7 +646,17 @@ export function renderComponentSurface(surface, options = {}) {
         `| \`${component.id}\` | ${component.scope} | ${component.kind} | ${component.fallback} |`,
     )
     .join('\n')
-  const keyRows = surface.keys.map((key) => `| \`${key.name}\` | \`${key.class}\` | ${key.note} |`).join('\n')
+  const keyRows = surface.keys
+    .map((key) => {
+      const exemption = key.exemption
+        ? ` Tuning exemption: ${key.exemption.reason} (${key.exemption.date}${key.exemption.issue ? ` · ${key.exemption.issue}` : ''} · [${decidedIn(key.exemption.ref)}](${relativeAdr(key.exemption.ref)}))`
+        : ''
+      return `| \`${key.name}\` | \`${key.class}\` | ${key.note}${exemption} |`
+    })
+    .join('\n')
+  const behaviorRows = (surface.behaviorKnobs ?? [])
+    .map((name) => `| \`${name}\` |`)
+    .join('\n') || '| _(none)_ |'
   const forbiddenRows = surface.forbidden
     .map((capability) => {
       const decision = capability.acceptedSwitches?.decision
@@ -621,6 +730,17 @@ All keys from \`domain/config/schema.js\`, classified on the component axis.
 |---|---|---|
 ${keyRows}
 
+## Behaviour knobs
+
+Non-boolean keys that gate behaviour are reviewed on the same axis as booleans
+(#138): each must be \`core\`, \`optional-component\`, \`forbidden-to-disable\`, or an
+\`optional-config\` key with a dated tuning-only exemption. A string or union that
+hides a capability cannot use the tuning class without that record.
+
+| Key |
+|---|
+${behaviorRows}
+
 ## Non-goals
 
 This page does not decide whether a key is useful, and it is not an approval

package/domain/config/schema.js

@@ -74,14 +74,36 @@ const SECTION_KEYS = {
     'requireLease',
   ],
   send: ['maxPerMinute', 'interruptDefault'],
-  tests: ['enabled', 'admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
+  tests: ['admission', 'timeoutMs', 'maxBytes', 'autoChecks', 'allowPackageDiscovery'],
   gates: ['requireChecks', 'requireTests', 'allowReviewExemption', 'maxReportBytes'],
-  docs: ['board', 'boardLocation'],
-  archive: ['enabled', 'afterDays', 'maxMissions'],
+  docs: ['boardLocation'],
+  archive: ['afterDays', 'maxMissions'],
   leases: ['ttlMs'],
   dev: ['reloadDelayMs', 'reloadRequiredIds'],
 }
 
+// #133/#135: `docs.board` and `archive.enabled` were component-shaped switches
+// hiding in the config form. They are component rows now, so a legacy config
+// keeps failing as an unknown key — with an upgrade note naming the row that
+// replaced it.
+/** @type {Record<string, string>} */
+const REMOVED_KEYS = {
+  'docs.board': 'tower-board',
+  'archive.enabled': 'tower-archive',
+}
+
+/**
+ * Upgrade note for a removed component switch, appended to the unknown-key error.
+ * @param {string} group
+ * @param {string} key
+ * @returns {string}
+ */
+function removedKeyNote(group, key) {
+  const component = REMOVED_KEYS[`${group}.${key}`]
+  if (!component) return ''
+  return ` — ${group}.${key} was removed: the ${component} component row in cordis.patch.yml is the switch (see docs/adr/0005-component-surface.md)`
+}
+
 const MODEL_KEYS = ['provider', 'model', 'reasoningEffort', 'maxTokens']
 
 const ModelSchema = () =>
@@ -207,7 +229,9 @@ export const Config = Schema.object({
     .default({})
     .description('Message delivery policy.'),
   tests: Schema.object({
-    enabled: Schema.boolean().default(true).description('Run declared test discovery when a mission configures it.'),
+    // #136: no `enabled` switch. The `tower-tests` component row *is* the
+    // switch; a second boolean could only disagree with it, and a row-off
+    // profile has no tower_test tool and no receipt to gate on.
     admission: Schema.union(['spawn', 'complete', 'off'])
       .default('off')
       .description('Run discovery before spawning a worker, when completing, or only on explicit tower_test (default off: repository code runs only on an explicit tower_test).'),
@@ -239,30 +263,24 @@ export const Config = Schema.object({
     .default({})
     .description('Merge-gate strictness.'),
   docs: Schema.object({
-    board: Schema.boolean()
-      .default(true)
-      .description('Write a human-readable MISSIONS.md after mission changes.'),
     boardLocation: Schema.union(['common', 'repo'])
       .default('common')
-      .description('common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md.'),
+      .description('common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. Whether the board is written at all is the tower-board component row (#133).'),
   })
     .default({})
-    .description('Human-readable artifacts.'),
+    .description('Human-readable artifact location. Turning the board off is a component row, not a tuning key.'),
   archive: Schema.object({
-    enabled: Schema.boolean()
-      .default(true)
-      .description('Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history.'),
     afterDays: Schema.natural()
       .min(0)
       .default(30)
-      .description('Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately).'),
+      .description('Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). Archival itself is the tower-archive component row (#135).'),
     maxMissions: Schema.natural()
       .min(0)
       .default(100)
       .description('Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission).'),
   })
     .default({})
-    .description('Terminal-mission archival policy. Archived missions are moved, never deleted.'),
+    .description('Terminal-mission archival tuning. Whether archival runs at all is the tower-archive component row; archived missions are moved, never deleted.'),
   leases: Schema.object({
     ttlMs: Schema.natural().min(1000).max(86400000).default(900000).description('Default advisory lease lifetime; expiry never auto-releases.'),
   })
@@ -376,9 +394,10 @@ export function assertKnownKeys(raw, label) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) continue
     const bad = Object.keys(value).filter((key) => !allowed.includes(key))
     if (bad.length > 0) {
+      const notes = bad.map((key) => removedKeyNote(group, key)).join('')
       throw new TowerToolError(
         'config-unknown-key',
-        `${label} has unknown key(s) ${bad.map((key) => `${group}.${key}`).join(', ')}`,
+        `${label} has unknown key(s) ${bad.map((key) => `${group}.${key}`).join(', ')}${notes}`,
       )
     }
     if ((group === 'spawn') && value.workerModel && typeof value.workerModel === 'object') {
@@ -423,13 +442,10 @@ export function resolveTowerConfig(rawConfig) {
     throw new TowerToolError('config-invalid', `Tower config is invalid: ${String(error?.message ?? error)}`)
   }
   const mode = clone(parsed.mode ?? {})
-  if (parsed.gates?.requireTests === true && parsed.tests?.enabled === false) {
-    // #121: the tower-tests *component row* is the capability switch now; a
-    // repository that turns the row off cannot satisfy gates.requireTests. The
-    // component-level half of this invariant is enforced at plan/mode entry,
-    // where the mounted rows are known (host/presets.js).
-    throw new TowerToolError('config-invalid', 'Tower config is invalid: gates.requireTests is true but test discovery is disabled (tests.enabled:false)')
-  }
+  // #136: `tests.enabled` is gone, so this resolver can no longer disagree with
+  // the mounted rows. The component-level invariant (`gates.requireTests:true`
+  // with the `tower-tests` row off) is enforced where the rows are known:
+  // host/presets.js at plan/mode entry, and the merge gate reports its cause.
   // Canonical keys win; the legacy top-level aliases only fill gaps.
   const rawMode = raw.mode ?? {}
   if (rawMode.promptSection === undefined && raw.section !== undefined) mode.promptSection = raw.section
@@ -440,9 +456,16 @@ export function resolveTowerConfig(rawConfig) {
   // Cordis config may omit this key, and an explicit legacy top-level
   // `allowAgentControl:true` must not be shadowed by a schema default.
   if (mode.allowAgentControl === undefined) mode.allowAgentControl = true
+  // F17/#130: materialize the resolved prompt section as well. `section` always
+  // mirrors `mode.promptSection`, so leaving the canonical field absent for a
+  // config with neither key would make a *second* pass copy the just-added
+  // `section:''` back into `mode` (`promptSection:''`): one pass would not be a
+  // fixed point. Filling it here makes `resolve(resolve(raw))` equal
+  // `resolve(raw)` for every valid config without changing any resolved value.
+  if (mode.promptSection === undefined) mode.promptSection = ''
   if (!Array.isArray(mode.denyTools) || mode.denyTools.length === 0) mode.denyTools = [...DEFAULT_DENY_TOOLS]
   return {
-    section: mode.promptSection ?? '',
+    section: mode.promptSection,
     init: clone(parsed.init ?? {}),
     mode,
     review: clone(parsed.review ?? {}),

package/domain/gate.js

@@ -47,7 +47,11 @@ export function completionBlockers(mission, config = {}) {
 
 /**
  * Review, roster, and test-evidence blockers; all inputs are snapshots.
- * @param {MergeGateOptions} options
+ * `testsComponent` is the optional `tower-tests` row state (#140). It is passed
+ * through the options bag rather than declared on `MergeGateOptions` because the
+ * domain may not read the component registry itself: the composition root
+ * publishes the probe on the port bag and `app/gate.js` forwards the snapshot.
+ * @param {MergeGateOptions & { testsComponent?: ({ enabled?: boolean, reason?: string } | null) }} options
  * @returns {Blocker[]}
  */
 export function mergeGateBlockers({
@@ -61,6 +65,7 @@ export function mergeGateBlockers({
   parentStatus = null,
   inactiveStates = [],
   rebaseWaived = false,
+  testsComponent = null,
 }) {
   /** @type {Blocker[]} */
   const blockers = []
@@ -106,7 +111,17 @@ export function mergeGateBlockers({
   if (config.gates?.requireTests === true) {
     const runs = (mission.testRuns ?? []).filter((run) => run.ok === true && run.treeTip && branchTip && run.treeTip === branchTip)
     if (runs.length === 0) {
-      push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${branchTip ? branchTip.slice(0, 7) : '(none)'}`)
+      // #140: name the component cause when the row is off. Without this the
+      // blocker reads as a repository mistake ("no passing discovery") when the
+      // real cause is a disabled row and no tower_test tool exists to produce a
+      // receipt. The component state is a snapshot on the options bag.
+      const tip = branchTip ? branchTip.slice(0, 7) : '(none)'
+      const cause =
+        testsComponent && testsComponent.enabled !== true
+          ? `; ${testsComponent.reason ?? 'disabled by component tower-tests'} so no receipt can exist: ` +
+            're-enable the tower-tests component (or set gates.requireTests:false) and re-record discovery'
+          : ''
+      push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${tip}${cause}`)
     }
   }
   return blockers