dsh-tower 2.4.2 → 2.5.0

package/domain/component-rules.js

@@ -0,0 +1,216 @@
+// Component-surface rules split out of `domain/components.js` (#138) so the
+// policy module stays under the architecture aggregate-size brake (800 lines).
+// These are pure checks over the parsed source of truth: a key's class must
+// match its value shape, and a row may only override config its component owns.
+// `domain/components.js` re-exports them for the gate and the tests.
+
+// A row's `config:` mapping mixes Tower's config with the row package's own
+// metadata (`id`, `name`, `description`, `order`) and its nested `plugins:` list.
+// Only the Tower config leaves are overrides of the component surface.
+const ROW_CONFIG_METADATA = new Set(['id', 'name', 'description', 'order'])
+
+function scalarText(value) {
+  const trimmed = String(value ?? '').trim()
+  const quoted = /^(['"])(.*)\1$/.exec(trimmed)
+  return quoted ? quoted[2] : trimmed
+}
+
+/**
+ * Read the scalar overrides under a row's own top-level `config:` mapping.
+ *
+ * The group rows are skipped by the parser: their `config:` is the list of
+ * nested component rows, so the overrides belong to the child row, not the group.
+ * A `plugins:` list is skipped for the same reason. This is what keeps a
+ * legitimate plugin config (`write: false`, `sampleOverCapGlobResults: false`)
+ * from being mistaken for a Tower config key, while a removed switch
+ * (`docs.board: false`) is captured as `docs.board` and refused.
+ *
+ * @param {string[]} lines
+ * @param {{ indent: number, line: number }} row
+ * @returns {Array<{ key: string, value: string }>}
+ */
+export function collectConfigOverrides(lines, row) {
+  let configIndent = null
+  let start = null
+  for (let index = row.line + 1; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = /^(\s*)/.exec(line)?.[1].length ?? 0
+    const nextId = /^\s*-\s+id:/.exec(line)
+    if (nextId && indent <= row.indent) break
+    if (indent <= row.indent && !/^\s*-\s+/.test(line)) break
+    if (/^\s*config:\s*$/.test(line)) {
+      configIndent = indent
+      start = index + 1
+      break
+    }
+  }
+  if (start === null || configIndent === null) return []
+  /** @type {Array<{ indent: number, key: string }>} */
+  const stack = []
+  const overrides = []
+  let skipIndent = null
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = /^(\s*)/.exec(line)?.[1].length ?? 0
+    if (indent <= configIndent) break
+    if (skipIndent !== null) {
+      if (indent > skipIndent) continue
+      skipIndent = null
+    }
+    if (/^\s*-\s+/.test(line)) {
+      // A list item: the group config list or a `plugins:` entry. Skip its whole
+      // subtree; it does not belong to this row's config.
+      skipIndent = indent
+      continue
+    }
+    const match = /^\s*([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line)
+    if (!match) continue
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
+    const key = match[1]
+    const value = match[2].trim()
+    if (value === '') {
+      if (key === 'plugins') {
+        skipIndent = indent
+        continue
+      }
+      stack.push({ indent, key })
+      continue
+    }
+    const parts = [...stack.map((entry) => entry.key), key]
+    if (ROW_CONFIG_METADATA.has(parts[0]) || parts[0] === 'plugins') continue
+    overrides.push({ key: parts.join('.'), value: scalarText(value) })
+  }
+  return overrides
+}
+
+/**
+ * #138.1: the class is not free text. A boolean key that removes a capability
+ * cannot file as `optional-config`; it must be `core`, `optional-component` or
+ * `forbidden-to-disable`, or carry a dated tuning-only exemption. The same rule
+ * covers the non-boolean behaviour knobs recorded in `behaviorKnobs`, so a
+ * string/union switch cannot hide on the tuning axis.
+ *
+ * @param {{ keys: Array<{ name: string, class: string, exemption?: any }>, behaviorKnobs?: string[] }} surface
+ * @param {{ keyTypes?: Record<string, string> }} live live schema key -> type
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function checkKeyClassifications(surface, live = {}) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  const declared = new Map(surface.keys.map((key) => [key.name, key]))
+  const types = live.keyTypes ?? {}
+  const behavior = new Set(surface.behaviorKnobs ?? [])
+  const reviewedClasses = ['core', 'optional-component', 'forbidden-to-disable']
+  for (const name of behavior) {
+    if (!declared.has(name)) {
+      record('behavior-knob-unknown', `behaviorKnobs records ${name}, which has no component-axis class`)
+    }
+    if (types[name] === undefined) {
+      record('behavior-knob-unknown', `behaviorKnobs records ${name}, which is not a live config key`)
+    }
+  }
+  for (const key of surface.keys) {
+    const type = types[key.name]
+    const isBoolean = type === 'boolean'
+    const isBehavior = behavior.has(key.name)
+    if (isBoolean || isBehavior) {
+      if (key.class === 'optional-config') {
+        if (!key.exemption) {
+          record(
+            'boolean-class',
+            `${key.name} is a ${isBoolean ? 'boolean' : 'recorded behaviour knob'} classified optional-config; it needs core/optional-component/forbidden-to-disable or a dated tuning-only exemption`,
+          )
+        } else if (!/tuning|tune/i.test(key.exemption.reason)) {
+          record(
+            'boolean-exemption',
+            `${key.name} keeps optional-config but its exemption reason does not name a tuning-only nature: ${key.exemption.reason}`,
+          )
+        }
+      } else if (!reviewedClasses.includes(key.class)) {
+        record('boolean-class', `${key.name} is a ${isBoolean ? 'boolean' : 'behaviour knob'} with unknown class "${key.class}"`)
+      }
+    }
+    if (key.exemption) {
+      if (!isBoolean && !isBehavior) {
+        record('exemption-invalid', `${key.name} carries a tuning exemption but is neither a boolean nor a recorded behaviour knob`)
+      }
+      if (key.class !== 'optional-config') {
+        record('exemption-invalid', `${key.name} carries a tuning exemption but is classified "${key.class}", not optional-config`)
+      }
+      if (!/tuning|tune/i.test(key.exemption.reason)) {
+        record('exemption-invalid', `${key.name} exemption reason must name its tuning-only nature: ${key.exemption.reason}`)
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * #138.4: a row may only override config it owns. The parser captures the scalar
+ * leaves under the row's own `config:` mapping; each one must be a live config
+ * key (so a removed switch such as `docs.board:false` fails) and must be listed
+ * in that component's `allowedOverrides` (so a row cannot enable or disable a
+ * capability it does not own). `allowedOverrides` itself is checked in the other
+ * direction: every listed key must be live and must not be forbidden-to-disable.
+ *
+ * @param {{ keys: Array<{ name: string, class: string }>, components: Array<{ id: string, allowedOverrides?: string[] }> }} surface
+ * @param {{ configKeys?: string[], patch?: { rows?: Array<{ id: string, configOverrides?: Array<{ key: string, value: string }> }> } }} live
+ * @returns {Array<{ code: string, level: string, message: string }>}
+ */
+export function checkRowOverrides(surface, live = {}) {
+  const findings = []
+  const record = (code, message) => findings.push({ code, level: 'error', message })
+  const rows = live.patch?.rows ?? []
+  const liveKeys = new Set(live.configKeys ?? [])
+  const keyClass = new Map(surface.keys.map((key) => [key.name, key.class]))
+  const classified = new Map(surface.components.map((component) => [component.id, component]))
+  for (const component of surface.components) {
+    const allowed = component.allowedOverrides ?? []
+    const seen = new Set()
+    for (const key of allowed) {
+      if (seen.has(key)) record('row-override-duplicate', `component "${component.id}" lists ${key} twice in allowedOverrides`)
+      seen.add(key)
+      if (!liveKeys.has(key)) {
+        record('component-override-unknown', `component "${component.id}" allows ${key}, which is not a live config key`)
+      }
+      if (keyClass.get(key) === 'forbidden-to-disable') {
+        record('row-override-forbidden', `component "${component.id}" allows ${key}, which is classified forbidden-to-disable`)
+      }
+    }
+  }
+  for (const row of rows) {
+    const component = classified.get(row.id)
+    if (!component) continue
+    const allowed = new Set(component.allowedOverrides ?? [])
+    for (const entry of row.configOverrides ?? []) {
+      const key = entry?.key
+      if (typeof key !== 'string' || !key) {
+        record('row-override-invalid', `row "${row.id}" has an override without a config key`)
+        continue
+      }
+      if (!liveKeys.has(key)) {
+        record(
+          'row-override-unknown',
+          `row "${row.id}" sets ${key}:${entry.value}; it is not a live config key (a switch removed in favour of a component must not keep working from a row config)`,
+        )
+        continue
+      }
+      if (keyClass.get(key) === 'forbidden-to-disable') {
+        record(
+          'row-override-forbidden',
+          `row "${row.id}" sets ${key}:${entry.value}; a component may not switch off a forbidden-to-disable key`,
+        )
+        continue
+      }
+      if (!allowed.has(key)) {
+        record(
+          'row-override-foreign',
+          `row "${row.id}" sets ${key}:${entry.value}; that key is outside the overrides allowed for component "${component.id}"`,
+        )
+      }
+    }
+  }
+  return findings
+}

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