dsh-tower 2.1.0 → 2.4.0

package/scripts/domain-metrics.mjs

@@ -3,9 +3,13 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const SOURCE_ROOTS = ['domain', 'app', 'tools', 'adapters', 'lib']
+const SOURCE_ROOTS = ['domain', 'app', 'tools', 'adapters', 'host']
 const ENTRY_FILES = ['index.js', 'worker.js', 'reviewer.js', 'skills.js']
 const PURE_ROOTS = ['domain']
+// #71: the optional Web client is its own tier. It is printed on every run so
+// its growth is visible in CI, but it stays out of the pure-domain denominator:
+// the share measures the Host architecture, not the browser widget.
+const CLIENT_ROOT = 'ui-bundle'
 
 function walk(dir, out = []) {
   if (!fs.existsSync(dir)) return out
@@ -34,15 +38,20 @@ for (const file of files) {
   const relative = path.relative(root, file).split(path.sep).join('/')
   if (PURE_ROOTS.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) pure += lines
 }
+const clientLines = walk(path.join(root, CLIENT_ROOT)).reduce((sum, file) => sum + loc(file), 0)
 const share = total === 0 ? 0 : pure / total
-const result = { pure, total, share: Number(share.toFixed(4)) }
+const result = { pure, total, share: Number(share.toFixed(4)), uiBundle: clientLines }
+function printMetrics() {
+  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+  console.log(`domain-metrics: ui-bundle ${clientLines} lines (client tier; excluded from the pure-domain share)`)
+}
 if (process.argv.includes('--json')) console.log(JSON.stringify(result))
 else if (process.argv.includes('--check')) {
   if (share < 0.35) {
     console.error(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% < 35% (${pure}/${total})`)
     process.exit(1)
   }
-  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+  printMetrics()
 } else {
-  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+  printMetrics()
 }

package/scripts/generate-component-surface.mjs

@@ -0,0 +1,59 @@
+// Generate the component-surface reference from the single source of truth
+// (#120). The table is a rendering of `scripts/component-surface.json`; editing
+// the markdown by hand fails `npm run docs:check:generated:components`.
+//
+// Usage:
+//   node scripts/generate-component-surface.mjs [--root <dir>] [--check]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  COMPONENT_REFERENCE_FILE,
+  COMPONENT_SURFACE_FILE,
+  parseComponentSurface,
+  renderComponentSurface,
+} from '../domain/components.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 USAGE = `usage: node scripts/generate-component-surface.mjs [--root <dir>] [--check]
+
+  --root   repository root to read and write (default: this package)
+  --check  fail when the committed reference differs instead of writing it
+  --help   print this text
+
+The table is generated from ${COMPONENT_SURFACE_FILE}; do not edit
+${COMPONENT_REFERENCE_FILE} by hand.`
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { root: PACKAGE_ROOT, check: false, help: false },
+    values: { '--root': { key: 'root', parse: path.resolve } },
+    flags: { '--check': 'check', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const root = path.resolve(options.root)
+  const surface = parseComponentSurface(fs.readFileSync(path.join(root, COMPONENT_SURFACE_FILE), 'utf8'))
+  const baseline = readBaseline(root)
+  const expected = renderComponentSurface(surface, { baselineDate: baseline.date })
+  const target = path.join(root, COMPONENT_REFERENCE_FILE)
+  if (options.check) {
+    const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+    if (actual !== expected) {
+      console.error(`component reference is stale; run npm run docs:generate:components (${COMPONENT_REFERENCE_FILE})`)
+      return 1
+    }
+    console.log(`component reference: ${surface.keys.length} keys in sync (${COMPONENT_REFERENCE_FILE})`)
+    return 0
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${COMPONENT_REFERENCE_FILE} (${surface.keys.length} keys, ${surface.components.length} components)`)
+  return 0
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'components', usage: USAGE })

package/scripts/generate-config-reference.mjs

@@ -2,11 +2,15 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { Config, resolveTowerConfig } from '../domain/config/schema.js'
+import { Config, configSurface, resolveTowerConfig } from '../domain/config/schema.js'
+import { SURFACE_BASELINE_FILE, surfaceLine } from '../domain/surface.js'
+import { readBaseline } from './lib/surface.mjs'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const target = path.join(root, 'docs', 'reference', 'config.generated.md')
 const defaults = resolveTowerConfig({})
+const baseline = readBaseline(root)
+const surface = configSurface()
 const rows = []
 for (const [key, schema] of Object.entries(Config.dict ?? {})) {
   const dict = schema?.dict
@@ -24,9 +28,18 @@ function format(key, schema, parent) {
   const description = String(schema?.meta?.description ?? parent?.meta?.description ?? '').replace(/\s+/g, ' ').trim()
   return `| \`${key}\` | \`${fallback}\` | ${description} |`
 }
+// The counts are live for the config half and come from the committed baseline
+// for the tools half; `npm run surface:check` makes the two agree, so the header
+// is a generated decision record rather than hand-maintained prose.
+const counts = {
+  configKeys: rows.length,
+  sections: surface.sections.length,
+  tools: baseline.surfaces.tools.value,
+}
 const expected = `# Config reference (generated)
 
 > Generated by \`npm run docs:generate:config\` from \`domain/config/schema.js\`. Values are defaults before repo config.
+> Surface: ${surfaceLine(counts)} · baseline ${baseline.date}. Generated from \`${SURFACE_BASELINE_FILE}\`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|

package/scripts/generate-error-reference.mjs

@@ -1,29 +1,83 @@
-// Generate the error-code reference from domain/errors.js so the catalog and docs
-// cannot disagree (#46). Usage: node scripts/generate-error-reference.mjs [--check]
+// Generate the error-code reference from domain/errors.js so the catalog, the
+// recovery metadata (`retryable` / `nextAction`) and the docs cannot disagree
+// (#46, #74). Usage: node scripts/generate-error-reference.mjs [--check]
+//
+// Two artifacts come from the same catalog:
+//   - docs/reference/errors.generated.md — the compact generated catalog;
+//   - the table block inside docs/reference/errors.md, delimited by
+//     `generated:error-table:start/end` markers. The surrounding prose is
+//     hand-written; only the table is generated.
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { ERROR_CODES } from '../domain/errors.js'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const target = path.join(root, 'docs', 'reference', 'errors.generated.md')
-const expected = `# Error code catalog (generated)
+const generatedTarget = path.join(root, 'docs', 'reference', 'errors.generated.md')
+const referenceTarget = path.join(root, 'docs', 'reference', 'errors.md')
+const START = '<!-- generated:error-table:start -->'
+const END = '<!-- generated:error-table:end -->'
+
+const cell = (value) => String(value ?? '').replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim()
+const retryableCell = (entry) => (entry.retryable === true ? 'yes' : 'no')
+const nextActionCell = (entry) => (entry.nextAction === null || entry.nextAction === undefined ? '—' : cell(entry.nextAction))
+
+/** @param {{ withTrigger?: boolean }} options */
+function table(options = {}) {
+  const withTrigger = options.withTrigger === true
+  const header = withTrigger
+    ? '| Code | Meaning | Retryable | Next action | Typical trigger |'
+    : '| Code | Meaning | Retryable | Next action |'
+  const divider = withTrigger ? '|---|---|---|---|---|' : '|---|---|---|---|'
+  const rows = Object.entries(ERROR_CODES).map(([code, entry]) => {
+    const base = `| \`${code}\` | ${cell(entry.description)} | ${retryableCell(entry)} | ${nextActionCell(entry)} |`
+    return withTrigger ? `${base} ${cell(entry.trigger)} |` : base
+  })
+  return [header, divider, ...rows].join('\n')
+}
+
+const expectedGenerated = `# Error code catalog (generated)
 
 > Generated by \`npm run docs:generate:errors\` from \`domain/errors.js\`. Do not edit by hand.
 
-| Code | Description |
-|---|---|
-${Object.entries(ERROR_CODES).map(([code, description]) => `| \`${code}\` | ${description} |`).join('\n')}
+The catalog is the source of truth for the stable codes and the recovery metadata the tool boundary
+renders: \`retryable\` marks a failure that can succeed later unchanged, and \`nextAction\` is the
+single recovery step appended to the message as \` — next: …\` (with \` (retryable)\` when retryable).
+
+${table()}
 `
+
+/** Replace the marked block in the hand-written reference. @param {string} text */
+function expectedReference(text) {
+  const start = text.indexOf(START)
+  const end = text.indexOf(END)
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`docs/reference/errors.md is missing the ${START} / ${END} markers`)
+  }
+  return `${text.slice(0, start + START.length)}\n${table({ withTrigger: true })}\n${text.slice(end)}`
+}
+
+const referenceSource = fs.readFileSync(referenceTarget, 'utf8')
+const expectedReferenceText = expectedReference(referenceSource)
+
 if (process.argv.includes('--check')) {
-  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
-  if (actual !== expected) {
-    console.error(`error reference is stale; run npm run docs:generate:errors`)
+  const actualGenerated = fs.existsSync(generatedTarget) ? fs.readFileSync(generatedTarget, 'utf8') : ''
+  if (actualGenerated !== expectedGenerated) {
+    console.error('error reference is stale; run npm run docs:generate:errors')
+    process.exit(1)
+  }
+  if (referenceSource !== expectedReferenceText) {
+    console.error('docs/reference/errors.md generated table is stale; run npm run docs:generate:errors')
     process.exit(1)
   }
-  console.log(`error reference: ${Object.keys(ERROR_CODES).length} codes in sync`)
+  const withRecovery = Object.values(ERROR_CODES).filter((entry) => entry.nextAction !== null).length
+  console.log(`error reference: ${Object.keys(ERROR_CODES).length} codes in sync (${withRecovery} with a next action)`)
 } else {
-  fs.mkdirSync(path.dirname(target), { recursive: true })
-  fs.writeFileSync(target, expected)
-  console.log(`wrote ${path.relative(root, target)} (${Object.keys(ERROR_CODES).length} codes)`)
+  fs.mkdirSync(path.dirname(generatedTarget), { recursive: true })
+  fs.writeFileSync(generatedTarget, expectedGenerated)
+  fs.writeFileSync(referenceTarget, expectedReferenceText)
+  const withRecovery = Object.values(ERROR_CODES).filter((entry) => entry.nextAction !== null).length
+  console.log(
+    `wrote ${path.relative(root, generatedTarget)} and the generated table in ${path.relative(root, referenceTarget)} (${Object.keys(ERROR_CODES).length} codes, ${withRecovery} with a next action)`,
+  )
 }

package/scripts/generate-events-reference.mjs

@@ -0,0 +1,83 @@
+// Generate docs/reference/events.md from the event table (#75) so event names
+// and payloads cannot drift from the runtime. Usage:
+//   node scripts/generate-events-reference.mjs [--check]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  EVENT_COUNT,
+  LEGACY_TOOL_EVENT_TABLE,
+  MISSION_EVENT_TABLE,
+} from '../domain/events.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'events.md')
+
+const payloadCell = (entry) => `\`{ ${entry.payload.join(', ')} }\``
+const missionRows = MISSION_EVENT_TABLE.map(
+  (entry) => `| \`${entry.name}\` | ${payloadCell(entry)} | ${entry.description} |`,
+).join('\n')
+const legacyRows = LEGACY_TOOL_EVENT_TABLE.map((entry) => `| \`${entry.name}\` | ${entry.description} |`).join('\n')
+
+const expected = `# Tower events
+
+> Generated by \`npm run docs:generate:events\` from \`domain/events.js\`. Do not edit by hand.
+
+Tower emits process-local Cordis events after successful tool calls (mutations and read-only tools), so
+other plugins can observe a repository without polling. This release defines ${EVENT_COUNT} process-local events:
+${MISSION_EVENT_TABLE.length} stable domain events and ${LEGACY_TOOL_EVENT_TABLE.length} deprecated tool-shaped
+aliases. Events are **not** sent over the network and carry no telemetry.
+
+## Domain events (stable)
+
+Domain events describe what changed, not which tool ran. They are emitted only after the state write
+succeeds, so \`revision\` is the revision a reader can load back from \`state.json\`; a failed tool emits
+no domain event. \`at\` is the transition timestamp in epoch milliseconds. \`state.json\` stays
+authoritative: these events are an observation channel, not an event-sourced log, and are never
+replayed.
+
+| Event | Payload | Emitted after |
+|---|---|---|
+${missionRows}
+
+\`\`\`js
+ctx.on('tower.mission.merged', ({ missionId, revision, at, commit }) => {
+  // the merge is already durable; commit is the merge commit that landed
+})
+\`\`\`
+
+## Tool-shaped aliases (deprecated)
+
+The older \`tower/<tool>\` events are kept for one minor release as a **deprecated** alias for the
+tool-shaped observation channel; prefer the domain events above and expect the alias to be removed in
+the next minor. They carry \`{ tool, repoRoot, value }\`, fire after a successful tool call, and never
+fail a tool when a listener throws. For \`tower_merge\` the alias also fires for a gate failure whose
+\`value.ok\` is false.
+
+| Event | Emitted after |
+|---|---|
+${legacyRows}
+
+\`\`\`js
+ctx.on('tower/merge', (payload) => {
+  // deprecated: prefer tower.mission.merged
+  // payload.tool, payload.repoRoot, payload.value (the tool's JSON result)
+})
+\`\`\`
+
+For a durable audit trail use \`<git-common-dir>/dsh-tower/activity.jsonl\` and \`MISSIONS.md\` instead;
+events are process-local and are not replayed.
+`
+
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('events reference is stale; run npm run docs:generate:events')
+    process.exit(1)
+  }
+  console.log(`events reference: ${EVENT_COUNT} events in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${EVENT_COUNT} events)`)
+}

package/scripts/generate-tools-reference.mjs

@@ -1,46 +1,39 @@
 // Generate the tools overview from the registered tool definitions (#46).
+//
+// #118: use the shipped Host entry, not only the define() path, so the table and
+// its header count include tower_mode/tower_control as well.
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { registerTowerTools } from '../tools/index.js'
+import { SURFACE_BASELINE_FILE, surfaceLine } from '../domain/surface.js'
+import { loadShippedToolSurface } from './lib/tool-surface.mjs'
+import { readBaseline } from './lib/surface.mjs'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const target = path.join(root, 'docs', 'reference', 'tools.generated.md')
-const tools = new Map()
-const ctx = {
-  get() {
-    return undefined
-  },
-  effect(fn) {
-    const dispose = fn()
-    return typeof dispose === 'function' ? dispose : () => {}
-  },
-  systemPrompt: { section() {} },
-  tools: {
-    register(definition) {
-      tools.set(definition.name, definition)
-      return () => {}
-    },
-    guard() {
-      return () => {}
-    },
-    restrict() {
-      return () => {}
-    },
-  },
-}
-registerTowerTools(ctx)
+const baseline = readBaseline(root)
+const surface = loadShippedToolSurface()
+const tools = surface.definitions
 const rows = [...tools.values()]
   .sort((a, b) => a.name.localeCompare(b.name))
   .map((tool) => `| \`${tool.name}\` | ${String(tool.description ?? '').replace(/\s+/g, ' ').trim()} |`)
+// Live tools count, baseline config counts: `npm run surface:check` keeps the
+// two halves equal, so the generated header carries one decision record.
+const counts = {
+  configKeys: baseline.surfaces.configKeys.value,
+  sections: baseline.surfaces.sections.value,
+  tools: tools.size,
+}
 const expected = `# Tools overview (generated)
 
 > Generated by \`npm run docs:generate:tools\` from the registered tool definitions. Do not edit by hand.
+> Surface: ${surfaceLine(counts)} · baseline ${baseline.date}. Generated from \`${SURFACE_BASELINE_FILE}\`; do not edit by hand.
 
 | Tool | Description |
 |---|---|
 ${rows.join('\n')}
 `
+surface.dispose()
 if (process.argv.includes('--check')) {
   const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
   if (actual !== expected) {

package/scripts/generate-types.mjs

@@ -0,0 +1,127 @@
+// Generate the published type vocabulary from the runtime constants (#115).
+//
+// `types/index.d.ts` is the shipped type surface (`package.json` `types`). Its
+// status/type/role/error unions used to be a hand-copied second declaration of
+// constants that live in domain/; this generator makes the runtime the single
+// source: the marked block is rewritten from ERROR_CODES, MISSION_STATUSES,
+// REVIEW_STATUSES, MERGE_VERDICTS, MISSION_KINDS, REVIEW_POLICIES, FINDING_*,
+// ROLES and PAUSE_CAUSES. It is the type-surface sibling of the four
+// `docs:generate:*` generators and shares their `--check` contract.
+//
+// Usage: node scripts/generate-types.mjs [--check]
+//
+// The block is delimited by `// generated:vocabulary:start` / `:end` in
+// types/index.d.ts; the prose around it is hand-written. A missing marker is a
+// configuration error, not a silent no-op.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { ERROR_CODES } from '../domain/errors.js'
+import {
+  FINDING_SEVERITIES,
+  FINDING_STATUSES,
+  FINDING_TYPES,
+  MERGE_VERDICTS,
+  MISSION_STATUSES,
+  PAUSE_CAUSES,
+  REVIEW_STATUSES,
+} from '../domain/mission.js'
+import { MISSION_KINDS, REVIEW_POLICIES, ROLES } from '../domain/vocabulary.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const TARGET = path.join(root, 'types', 'index.d.ts')
+export const START = '// generated:vocabulary:start'
+export const END = '// generated:vocabulary:end'
+
+/** One published alias per runtime constant family, in declaration order. */
+const DECLARATIONS = [
+  { key: 'missionStatuses', name: 'MissionStatus' },
+  { key: 'missionKinds', name: 'MissionKind' },
+  { key: 'reviewStatuses', name: 'ReviewStatus', multiline: true },
+  { key: 'mergeVerdicts', name: 'MergeVerdict' },
+  { key: 'reviewPolicies', name: 'ReviewPolicy' },
+  { key: 'findingTypes', name: 'FindingType' },
+  { key: 'findingSeverities', name: 'FindingSeverity' },
+  { key: 'findingStatuses', name: 'FindingStatus' },
+  { key: 'roles', name: 'Role' },
+  { key: 'pauseCauses', name: 'PauseCause' },
+  { key: 'errorCodes', name: 'ErrorCode', multiline: true },
+]
+
+/** The runtime data the block is generated from. `--check` compares this exact input. */
+export function vocabularyData() {
+  return {
+    missionStatuses: [...MISSION_STATUSES],
+    missionKinds: [...MISSION_KINDS],
+    reviewStatuses: [...REVIEW_STATUSES],
+    mergeVerdicts: [...MERGE_VERDICTS],
+    reviewPolicies: [...REVIEW_POLICIES],
+    findingTypes: [...FINDING_TYPES],
+    findingSeverities: [...FINDING_SEVERITIES],
+    findingStatuses: [...FINDING_STATUSES],
+    roles: [...ROLES],
+    pauseCauses: [...PAUSE_CAUSES],
+    errorCodes: Object.keys(ERROR_CODES),
+  }
+}
+
+function renderDeclaration({ name, values, multiline = false }) {
+  const quoted = values.map((value) => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`)
+  const inline = `export type ${name} = ${quoted.join(' | ')}`
+  if (!multiline && inline.length <= 120) return inline
+  return [`export type ${name} =`, ...quoted.map((value) => `  | ${value}`)].join('\n')
+}
+
+/**
+ * Render the marked block (markers excluded) for one vocabulary input.
+ * @param {Record<string, string[]>} data
+ * @returns {string}
+ */
+export function vocabularyBlock(data) {
+  return DECLARATIONS.map((declaration) =>
+    renderDeclaration({ ...declaration, values: data[declaration.key] }),
+  ).join('\n')
+}
+
+/**
+ * Replace the marked block in a declaration file. Removing or reordering the
+ * markers is a hard error: a generated block that cannot be found would
+ * otherwise pass every check while drifting.
+ * @param {string} source
+ * @param {string} block
+ * @returns {string}
+ */
+export function injectVocabulary(source, block) {
+  const start = source.indexOf(START)
+  const end = source.indexOf(END)
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`types/index.d.ts is missing the ${START} / ${END} markers`)
+  }
+  return `${source.slice(0, start + START.length)}\n${block}\n${source.slice(end)}`
+}
+
+function main() {
+  const source = fs.readFileSync(TARGET, 'utf8')
+  const expected = injectVocabulary(source, vocabularyBlock(vocabularyData()))
+  const codes = Object.keys(ERROR_CODES).length
+  if (process.argv.includes('--check')) {
+    if (source !== expected) {
+      console.error('published type vocabulary is stale; run npm run types:generate')
+      process.exit(1)
+    }
+    console.log(`type vocabulary: ${DECLARATIONS.length} aliases (${codes} error codes) in sync`)
+  } else {
+    fs.writeFileSync(TARGET, expected)
+    console.log(`wrote ${path.relative(root, TARGET)} (${DECLARATIONS.length} aliases, ${codes} error codes)`)
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+  try {
+    main()
+  } catch (error) {
+    console.error(`type vocabulary: ${String(error?.message ?? error)}`)
+    process.exit(1)
+  }
+}

package/scripts/issue-audit.mjs

@@ -87,7 +87,7 @@ export function selectEvidence(issue) {
   return null
 }
 
-function labelsOf(issue) {
+export function labelsOf(issue) {
   const labels = Array.isArray(issue.labels) ? issue.labels : []
   return labels.map((label) => (typeof label === 'string' ? label : label?.name ?? '')).filter(Boolean)
 }
@@ -116,7 +116,7 @@ function closedAtOf(issue) {
 
 // A pointer must stay inside the repository and name a real test file: an
 // existing script or doc is not evidence of a regression test.
-function inspectPointer(pointer, root) {
+export function inspectPointer(pointer, root) {
   const normalized = String(pointer).replace(/\\/g, '/').trim()
   if (!normalized) return { code: 'invalid-pointer', detail: 'empty' }
   if (path.isAbsolute(normalized) || /^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')) {

package/scripts/lib/surface.mjs

@@ -0,0 +1,87 @@
+// File-reading wrapper around the pure concept-budget surface (#84).
+//
+// `domain/surface.js` owns the rules; this module owns the two files they read
+// (`scripts/surface-baseline.json` and `docs/reference/surface-budget.md`) and
+// the combined check used by the CLI gate and the tests.
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  SURFACE_BASELINE_FILE,
+  SURFACE_CLASSIFICATION_FILE,
+  parseBaseline,
+  validateBaseline,
+  validateClassification,
+} from '../../domain/surface.js'
+
+/**
+ * @param {string} root repository root
+ * @returns {ReturnType<typeof parseBaseline>}
+ */
+export function readBaseline(root) {
+  const file = path.join(root, SURFACE_BASELINE_FILE)
+  return parseBaseline(fs.readFileSync(file, 'utf8'))
+}
+
+/**
+ * @param {string} root repository root
+ */
+export function readClassification(root) {
+  return fs.readFileSync(path.join(root, SURFACE_CLASSIFICATION_FILE), 'utf8')
+}
+
+/**
+ * Run both halves of the concept-budget gate against one repository root.
+ * `current` carries the live counts and the live key/tool names.
+ *
+ * @param {{ root: string, current: { configKeys: number, sections: number, tools: number, liveNames: { configKeys: string[], sections: string[], tools: string[] } } }} options
+ */
+export function checkSurfaceBudget({ root, current }) {
+  let baseline
+  try {
+    baseline = readBaseline(root)
+  } catch (error) {
+    return {
+      ok: false,
+      baseline: null,
+      classification: null,
+      findings: [
+        {
+          code: 'baseline-unreadable',
+          level: 'error',
+          message: `${SURFACE_BASELINE_FILE} is unreadable: ${String(error?.message ?? error)}`,
+        },
+      ],
+    }
+  }
+  const findings = validateBaseline(baseline, current, {
+    exists: (relative) => fs.existsSync(path.join(root, relative)),
+  })
+  let classificationText
+  try {
+    classificationText = readClassification(root)
+  } catch (error) {
+    return {
+      ok: false,
+      baseline,
+      classification: null,
+      findings: [
+        ...findings,
+        {
+          code: 'classification-unreadable',
+          level: 'error',
+          message: `${SURFACE_CLASSIFICATION_FILE} is unreadable: ${String(error?.message ?? error)}`,
+        },
+      ],
+    }
+  }
+  const classification = validateClassification(classificationText, current.liveNames, {
+    baselineDate: baseline.date,
+  })
+  const all = [...findings, ...classification.findings]
+  return {
+    ok: all.length === 0,
+    baseline,
+    classification,
+    findings: all,
+  }
+}