dsh-tower 2.1.0-beta.1 → 2.3.0

package/scripts/check-docs.mjs

@@ -4,6 +4,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { EVENT_COUNT, LEGACY_TOOL_EVENT_NAMES } from '../domain/events.js'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const read = (file) => fs.readFileSync(path.join(root, file), 'utf8')
@@ -15,7 +16,7 @@ const toolModuleSources = fs.existsSync(path.join(root, 'tools'))
       .map((name) => read(`tools/${name}`))
       .join('\n')
   : ''
-const toolsSource = read('tools/index.js') + toolModuleSources + read('lib/tool-registry.js') + read('index.js')
+const toolsSource = read('tools/index.js') + toolModuleSources + read('host/tool-registry.js') + read('index.js')
 const documentedTools = read('docs/reference/tools.md')
 const toolNames = [...new Set([...toolsSource.matchAll(/name: '(tower_[a-z_]+)'/g)].map((match) => match[1]))]
   .filter((name) => name !== 'tower-control')
@@ -62,37 +63,9 @@ for (const code of [
 ]) blockerCodes.add(code)
 const missingBlockers = [...blockerCodes].filter((code) => !blockersSource.includes(`\`${code}\``)).sort()
 
-const eventNames = [
-  'init',
-  'plan',
-  'mission',
-  'spawn',
-  'complete',
-  'review',
-  'merge',
-  'rebase',
-  'teardown',
-  'finding',
-  'findings',
-  'send',
-  'inbox',
-  'interrupt',
-  'diff',
-  'adopt',
-  'roster',
-  'status',
-  'preflight',
-  'doctor',
-  'recover',
-  'test',
-  'batch',
-  'resource',
-  'import_legacy',
-  'legacy_map',
-  'mode',
-  'control',
-  'reload',
-]
+// #75: the legacy alias list comes from the same event table the generated
+// reference and the runtime use, so a renamed alias fails here first.
+const eventNames = LEGACY_TOOL_EVENT_NAMES.map((name) => name.replace(/^tower\//, ''))
 const documentedEvents = read('docs/reference/events.md')
 const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
 
@@ -128,8 +101,8 @@ if (!blockersDoc.includes(`${blockerCodes.size} stable blocker/failure codes`))
 if (!errorsDoc.includes(`${errorCodes.length} tool error codes`)) {
   problems.push(`docs/reference/errors.md must state ${errorCodes.length} tool error codes`)
 }
-if (!eventsDoc.includes(`${eventNames.length} process-local events`)) {
-  problems.push(`docs/reference/events.md must state ${eventNames.length} process-local events`)
+if (!eventsDoc.includes(`${EVENT_COUNT} process-local events`)) {
+  problems.push(`docs/reference/events.md must state ${EVENT_COUNT} process-local events`)
 }
 for (const required of [
   '| `tests.admission` | `off` |',
@@ -172,5 +145,5 @@ if (problems.length > 0) {
   process.exit(1)
 }
 console.log(
-  `docs ok: ${toolNames.length} tools, ${blockerCodes.size} blocker codes, ${errorCodes.length} error codes, ${eventNames.length} events, version ${packageJson.version}`,
+  `docs ok: ${toolNames.length} tools, ${blockerCodes.size} blocker codes, ${errorCodes.length} error codes, ${EVENT_COUNT} events, version ${packageJson.version}`,
 )

package/scripts/check-pack.mjs

@@ -1,49 +1,78 @@
 // Fail when the published file list drifts from the reviewed snapshot.
-// Run: node scripts/check-pack.mjs [--write]
+// Run: node scripts/check-pack.mjs [--write] [--root <dir>]
+//
+// #71: the optional Web client ships inside the main package, so the required
+// list asserts the client package manifest and its bundle patch — not just the
+// directory's index.js. `requiredMissing` is exported so a fixture can prove
+// that removing one of them fails the check; `--root` lets that fixture run the
+// real gate against a temporary package.
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const manifestFile = path.join(root, 'scripts', 'pack-manifest.txt')
-const write = process.argv.includes('--write')
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const REQUIRED_FILES = [
+  'cordis.patch.yml',
+  'index.js',
+  'locale/en.json',
+  'locale/zh.json',
+  'ui-bundle/index.js',
+  'ui-bundle/package.json',
+  'ui-bundle/cordis.patch.yml',
+  'COMPATIBILITY.md',
+]
 
-const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
-let parsed
-try {
-  const output = execFileSync(npm, ['pack', '--dry-run', '--json'], {
-    cwd: root,
-    encoding: 'utf8',
-    shell: process.platform === 'win32',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-  parsed = JSON.parse(output)
-} catch (error) {
-  console.error(`pack check: npm pack failed: ${String(error?.message ?? error)}`)
-  process.exit(1)
+function requiredMissing(paths, required = REQUIRED_FILES) {
+  return required.filter((file) => !paths.includes(file))
 }
 
-const entry = Array.isArray(parsed) ? parsed[0] : parsed
-const paths = (entry?.files ?? []).map((file) => file.path).filter(Boolean).sort()
-if (write) {
-  fs.writeFileSync(manifestFile, `${paths.join('\n')}\n`)
-  console.log(`pack check: wrote ${paths.length} paths to ${path.relative(root, manifestFile)}`)
-  process.exit(0)
-}
-const expected = fs.readFileSync(manifestFile, 'utf8').split('\n').filter(Boolean).sort()
-const added = paths.filter((file) => !expected.includes(file))
-const removed = expected.filter((file) => !paths.includes(file))
-if (added.length > 0 || removed.length > 0) {
-  console.error('pack check: published file list changed; review and update scripts/pack-manifest.txt')
-  if (added.length > 0) console.error(`  added: ${added.join(', ')}`)
-  if (removed.length > 0) console.error(`  removed: ${removed.join(', ')}`)
-  process.exit(1)
-}
-const required = ['cordis.patch.yml', 'index.js', 'locale/en.json', 'locale/zh.json', 'ui-bundle/index.js', 'COMPATIBILITY.md']
-const missing = required.filter((file) => !paths.includes(file))
-if (missing.length > 0) {
-  console.error(`pack check: required runtime files missing: ${missing.join(', ')}`)
-  process.exit(1)
+function main() {
+  const rootArg = process.argv.indexOf('--root')
+  const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : ROOT
+  const manifestFile = path.join(root, 'scripts', 'pack-manifest.txt')
+  const write = process.argv.includes('--write')
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  let parsed
+  try {
+    const output = execFileSync(npm, ['pack', '--dry-run', '--json'], {
+      cwd: root,
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    parsed = JSON.parse(output)
+  } catch (error) {
+    console.error(`pack check: npm pack failed: ${String(error?.message ?? error)}`)
+    process.exit(1)
+  }
+
+  const entry = Array.isArray(parsed) ? parsed[0] : parsed
+  const paths = (entry?.files ?? []).map((file) => file.path).filter(Boolean).sort()
+  if (write) {
+    fs.writeFileSync(manifestFile, `${paths.join('\n')}\n`)
+    console.log(`pack check: wrote ${paths.length} paths to ${path.relative(root, manifestFile)}`)
+    process.exit(0)
+  }
+  const expected = fs.readFileSync(manifestFile, 'utf8').split('\n').filter(Boolean).sort()
+  const added = paths.filter((file) => !expected.includes(file))
+  const removed = expected.filter((file) => !paths.includes(file))
+  if (added.length > 0 || removed.length > 0) {
+    console.error('pack check: published file list changed; review and update scripts/pack-manifest.txt')
+    if (added.length > 0) console.error(`  added: ${added.join(', ')}`)
+    if (removed.length > 0) console.error(`  removed: ${removed.join(', ')}`)
+    process.exit(1)
+  }
+  const missing = requiredMissing(paths)
+  if (missing.length > 0) {
+    console.error(`pack check: required runtime files missing: ${missing.join(', ')}`)
+    process.exit(1)
+  }
+  console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)
 }
-console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) main()
+
+export { REQUIRED_FILES, requiredMissing }

package/scripts/check-philosophy.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// Engineering-philosophy gate (#83).
+//
+// The repository writes down what it refuses to do and points every principle at
+// the thing that enforces it. A pointer that does not resolve is a slogan, so
+// this check fails on it. It also keeps the ADR set dated/structure-complete and
+// makes every "Non-goals" heading in docs/ auditable: it must either name an
+// existing enforcement file or be explicitly labelled `unowned`.
+//
+// Usage:
+//   node scripts/check-philosophy.mjs [--root <dir>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PRINCIPLES_FILE = 'PRINCIPLES.md'
+const ADR_DIR = 'docs/adr'
+const MIN_PRINCIPLES = 8
+const MIN_ADRS = 3
+const ADR_REQUIRED_SECTIONS = ['Context', 'Decision', 'Consequences', 'Rejected alternatives']
+const ADR_REQUIRED_TOPICS = ['ports', 'state.json', 'allowAgentControl']
+const USAGE = `usage: node scripts/check-philosophy.mjs [--root <dir>] [--json]
+
+  --root   repository root to check (default: this package)
+  --json   print the report as JSON
+  --help   print this text
+
+Every principle needs "Refused because of this:" and "Enforced by:" where the
+enforcement names an existing file and a test or gate. Every docs/ "Non-goals"
+heading needs an existing enforcement pointer or the word "unowned". At least
+${MIN_ADRS} dated ADRs need Context, Decision, Consequences and Rejected alternatives.`
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+function finding(code, message) {
+  return { code, level: 'error', message }
+}
+
+function listMarkdown(dir) {
+  const files = []
+  if (!fs.existsSync(dir)) return files
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...listMarkdown(full))
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(full)
+  }
+  return files
+}
+
+/** Candidate repository paths: backticked tokens with a slash or a file suffix. */
+function backtickedPaths(text) {
+  const paths = []
+  for (const match of String(text ?? '').matchAll(/`([^`]+)`/g)) {
+    const token = match[1].trim().replace(/\\/g, '/')
+    if (!token || token.startsWith('npm ') || token.startsWith('gh ') || token.includes(' ')) continue
+    if (!token.includes('/') && !/\.(?:mjs|js|cjs|ts|md|json|ya?ml)$/.test(token)) continue
+    paths.push(token)
+  }
+  return paths
+}
+
+function fieldText(body, label) {
+  const lines = String(body ?? '').split(/\r?\n/)
+  const start = lines.findIndex((line) => new RegExp(`^\\s*(?:[-*]\\s*)?\\**${label}:?\\**\\s*(.*)$`, 'i').test(line))
+  if (start < 0) return null
+  const match = new RegExp(`^\\s*(?:[-*]\\s*)?\\**${label}:?\\**\\s*(.*)$`, 'i').exec(lines[start])
+  const parts = [match?.[1] ?? '']
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim()) break
+    if (/^\s*(?:[-*]\s*)?\**Refused because of this:?/i.test(line)) break
+    if (/^\s*(?:[-*]\s*)?\**Enforced by:?/i.test(line)) break
+    if (/^#{1,6}\s+/.test(line)) break
+    parts.push(line.trim())
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim() || null
+}
+
+/**
+ * Read PRINCIPLES.md into sections, then check each section's refusal and
+ * enforcement pointer. A section without both is not a principle.
+ * @param {string} text
+ * @param {(relative: string) => boolean} exists
+ */
+export function checkPrinciplesText(text, exists) {
+  const findings = []
+  const headings = [...String(text ?? '').matchAll(/^##\s+(\d+)\.\s+(.+?)\s*$/gm)]
+  if (headings.length < MIN_PRINCIPLES) {
+    findings.push(finding('principles-count', `${PRINCIPLES_FILE} has ${headings.length} numbered principles; at least ${MIN_PRINCIPLES} are required`))
+  }
+  const principles = []
+  headings.forEach((heading, index) => {
+    const start = heading.index + heading[0].length
+    const end = index + 1 < headings.length ? headings[index + 1].index : text.length
+    const body = text.slice(start, end)
+    const number = Number(heading[1])
+    const title = heading[2].trim()
+    const refusal = fieldText(body, 'Refused because of this')
+    const enforcement = fieldText(body, 'Enforced by')
+    const record = { number, title, refusal, enforcement }
+    principles.push(record)
+    if (!record.refusal) {
+      findings.push(finding('principle-refusal', `principle ${number} (${title}) has no "Refused because of this:" line`))
+    }
+    if (!record.enforcement) {
+      findings.push(finding('principle-enforcement', `principle ${number} (${title}) has no "Enforced by:" line`))
+      return
+    }
+    const candidates = backtickedPaths(record.enforcement)
+    const missing = candidates.filter((candidate) => !exists(candidate))
+    if (candidates.length === 0) {
+      findings.push(finding('principle-pointer-missing', `principle ${number} (${title}) names no backticked file in "Enforced by:"`))
+    } else {
+      for (const candidate of missing) {
+        findings.push(
+          finding('principle-pointer-missing', `principle ${number} (${title}) points at a missing file: ${candidate}`),
+        )
+      }
+    }
+    if (!/(?:tests\/|\.test\.|npm run [a-z0-9:_-]+)/i.test(record.enforcement)) {
+      findings.push(
+        finding('principle-enforcement-weak', `principle ${number} (${title}) names no test or gate in "Enforced by:"`),
+      )
+    }
+  })
+  return { principles, findings }
+}
+
+/**
+ * Check that the ADR set is dated, structured and covers the three load-bearing
+ * decisions the issue asked to backfill.
+ * @param {string} root
+ */
+export function checkAdrs(root) {
+  const findings = []
+  const dir = path.join(root, ADR_DIR)
+  const files = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((name) => /^\d{4}-.+\.md$/.test(name))
+        .sort()
+    : []
+  if (files.length < MIN_ADRS) {
+    findings.push(finding('adr-count', `${ADR_DIR} has ${files.length} numbered ADRs; at least ${MIN_ADRS} are required`))
+  }
+  const combined = []
+  for (const name of files) {
+    const relative = `${ADR_DIR}/${name}`
+    const text = fs.readFileSync(path.join(dir, name), 'utf8')
+    combined.push(text)
+    for (const section of ADR_REQUIRED_SECTIONS) {
+      const heading = new RegExp(`^#{1,6}\\s+${section}\\b`, 'im')
+      if (!heading.test(text)) findings.push(finding('adr-section', `${relative} misses the "${section}" section`))
+    }
+    if (!/^\s*(?:[-*]\s*)?Date:\s*(\d{4}-\d{2}-\d{2})\s*$/im.test(text)) {
+      findings.push(finding('adr-date', `${relative} needs a "Date: YYYY-MM-DD" line`))
+    }
+    if (!/^\s*(?:[-*]\s*)?Status:\s*\S+/im.test(text)) {
+      findings.push(finding('adr-status', `${relative} needs a "Status:" line`))
+    }
+  }
+  const all = combined.join('\n')
+  for (const topic of ADR_REQUIRED_TOPICS) {
+    if (!new RegExp(topic.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i').test(all)) {
+      findings.push(finding('adr-topic', `no ADR explains the "${topic}" decision`))
+    }
+  }
+  return { adrDir: ADR_DIR, adrs: files, findings }
+}
+
+/**
+ * Every "Non-goals" heading in docs/ must carry an enforcement pointer that
+ * resolves or the explicit word `unowned`. No heading may be an orphan refusal.
+ * @param {string} root
+ */
+export function checkNonGoals(root) {
+  const findings = []
+  const files = listMarkdown(path.join(root, 'docs'))
+  let headings = 0
+  for (const file of files) {
+    const relative = path.relative(root, file).replace(/\\/g, '/')
+    const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/)
+    lines.forEach((line, index) => {
+      const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line)
+      if (!heading || !/\bnon[-\s]?goals?\b/i.test(heading[2])) return
+      headings += 1
+      const level = heading[1].length
+      const body = []
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        const next = /^(#{1,6})\s+/.exec(lines[cursor])
+        if (next && next[1].length <= level) break
+        body.push(lines[cursor])
+      }
+      const text = body.join('\n')
+      const enforcement = /^\s*(?:[-*]\s*)?\**Enforced by:?\**\s*(.+)$/im.exec(text)
+      const unowned = /\bunowned\b/i.test(text)
+      const enforced =
+        Boolean(unowned) ||
+        Boolean(enforcement && backtickedPaths(enforcement[1]).some((candidate) => fs.existsSync(path.join(root, candidate))))
+      if (!enforced) {
+        findings.push(
+          finding(
+            'non-goal-unowned',
+            `${relative}:${index + 1} has a "Non-goals" heading with no existing enforcement pointer and no "unowned" label`,
+          ),
+        )
+      }
+    })
+  }
+  return { headings, findings }
+}
+
+/** Run all three checks against one repository root. */
+export function checkPhilosophy(root) {
+  const findings = []
+  const principlesFile = path.join(root, PRINCIPLES_FILE)
+  let principles = []
+  if (!fs.existsSync(principlesFile)) {
+    findings.push(finding('principles-missing', `${PRINCIPLES_FILE} is missing`))
+  } else {
+    const result = checkPrinciplesText(fs.readFileSync(principlesFile, 'utf8'), (relative) =>
+      fs.existsSync(path.join(root, relative)),
+    )
+    principles = result.principles
+    findings.push(...result.findings)
+  }
+  const adr = checkAdrs(root)
+  findings.push(...adr.findings)
+  const nonGoals = checkNonGoals(root)
+  findings.push(...nonGoals.findings)
+  return {
+    ok: findings.length === 0,
+    principles,
+    adrs: adr.adrs,
+    nonGoals,
+    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 report = checkPhilosophy(path.resolve(options.root))
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2))
+    return report.ok ? 0 : 1
+  }
+  console.log(
+    `philosophy: ${report.principles.length} principles, ${report.adrs.length} ADRs, ${report.nonGoals.headings} non-goal heading(s)`,
+  )
+  for (const item of report.findings) console.log(`philosophy: ${item.level} [${item.code}] ${item.message}`)
+  if (report.ok) console.log('philosophy: ok — every refusal points at an existing test or gate')
+  else console.log(`philosophy: ${report.findings.length} unenforced statement(s)`)
+  return report.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'philosophy', usage: USAGE })

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-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)`,
+  )
 }