dsh-tower 2.0.3 → 2.1.0-beta.1

package/lib/worktreeOwnership.js

@@ -6,12 +6,13 @@
 // and must still be the Git worktree of the recorded branch in the recorded
 // repository. Every mismatch is rejected with an actionable message; nothing
 // is repaired or recreated here.
-import fsp from 'node:fs/promises'
+import { fsp } from '../adapters/store-fs.js'
 import path from 'node:path'
 
 import { git } from './git.js'
 
 function fail(code, message) {
+  /** @type {Error & {code?: string}} */
   const error = new Error(message)
   error.code = code
   throw error
@@ -74,7 +75,7 @@ async function gitTop(resolved, label) {
  * @param {string} [input.missionId] mission id, used in error messages
  * @returns {Promise<{path:string, realPath:string}>}
  */
-export async function assertOwnership(input = {}) {
+export async function assertOwnership(input = /** @type {any} */ ({})) {
   const storedPath = input?.storedPath
   const storedRealPath = input?.storedRealPath
   const branch = input?.branch
@@ -138,7 +139,7 @@ export async function assertOwnership(input = {}) {
   } catch (error) {
     fail('invalid-transition', `${label} ${resolved} has no readable HEAD: ${error.message}`)
   }
-  const actualBranch = head === 'HEAD' ? null : head.trim()
+  const actualBranch = head === 'HEAD' ? null : String(head).trim()
   if (actualBranch !== branch) {
     fail(
       'invalid-transition',
@@ -146,7 +147,7 @@ export async function assertOwnership(input = {}) {
     )
   }
 
-  let commonRaw
+  let commonRaw = ''
   try {
     commonRaw = await git(resolved, ['rev-parse', '--git-common-dir'])
   } catch (error) {

package/locale/en.json

@@ -1,6 +1,28 @@
 {
   "meta": {
     "title": "Tower",
-    "description": "Mission planning, isolated worktrees, and review-gated merges for multi-agent work."
+    "description": "Mission planning, isolated worktrees, worker/reviewer agents, and review-gated merges."
+  },
+  "components": {
+    "tower-bundle": {
+      "title": "Tower",
+      "summary": "Mission planning, isolated worktrees, worker/reviewer agents, and merge gates.",
+      "disables": "Turns off the whole Tower bundle; no orphan preset or skill is left behind."
+    },
+    "tower-skills": {
+      "title": "Tower skills",
+      "summary": "Playbooks for worker/reviewer agents and recovery after a blocked merge.",
+      "disables": "Internal section; toggled with the Tower bundle."
+    },
+    "preset-tower-worker": {
+      "title": "Tower worker",
+      "summary": "Writes code, runs verification, and commits only the files assigned to its mission.",
+      "disables": "Internal section; a missing preset is rejected before planning/mode entry."
+    },
+    "preset-tower-reviewer": {
+      "title": "Tower reviewer",
+      "summary": "Read-only checks for scope and acceptance, returning a clean verdict or findings.",
+      "disables": "Internal section; a missing preset is rejected before planning/mode entry when review is required."
+    }
   }
 }

package/locale/zh.json

@@ -2,5 +2,27 @@
   "meta": {
     "title": "Tower",
     "description": "多代理任务规划、隔离工作树与审查门禁合并。"
+  },
+  "components": {
+    "tower-bundle": {
+      "title": "Tower 控制塔",
+      "summary": "任务规划、隔离工作树、执行/审查代理与合并门禁。",
+      "disables": "关闭后整个 Tower 一起停用；不会留下孤立的代理预设或技能。"
+    },
+    "tower-skills": {
+      "title": "Tower 技能包",
+      "summary": "执行与审查代理的操作手册，以及失败后的恢复指南。",
+      "disables": "内部 section；随 Tower 整体启停。"
+    },
+    "preset-tower-worker": {
+      "title": "Tower 执行代理",
+      "summary": "在独立分支里写代码、跑验证并提交，只改分给它的文件。",
+      "disables": "内部 section；缺失时会在规划/进入模式前被拒绝。"
+    },
+    "preset-tower-reviewer": {
+      "title": "Tower 审查代理",
+      "summary": "只读检查改动是否越界、是否达标，给出通过或问题清单。",
+      "disables": "内部 section；缺失且强制审查时会在规划/进入模式前被拒绝。"
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.0.3",
+  "version": "2.1.0-beta.1",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "url": "git+https://github.com/louifinn/dsh-tower.git"
   },
   "homepage": "https://github.com/louifinn/dsh-tower#readme",
+  "types": "types/index.d.ts",
   "bugs": {
     "url": "https://github.com/louifinn/dsh-tower/issues"
   },
@@ -41,17 +42,25 @@
     "skills.js",
     "skills/",
     "lib/*.js",
+    "domain/**/*.js",
+    "app/*.js",
+    "tools/*.js",
+    "adapters/*.js",
+    "types/",
     "cordis.patch.yml",
     "scripts/",
     "locale/*.json",
     "icon.svg",
     "README.md",
     "README.en.md",
+    "COMPATIBILITY.md",
     "CHANGELOG.md",
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
-    "docs/"
+    "docs/",
+    "ui-bundle/",
+    "ports/*.js"
   ],
   "dsh": {
     "bundle": {
@@ -62,11 +71,31 @@
     "test": "node --test tests/*.test.mjs",
     "test:watch": "node --test --watch tests/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "smoke:mount": "node scripts/mount-smoke.mjs",
+    "smoke:fixtures": "node scripts/mount-smoke/fixtures.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "audit:issues": "node scripts/issue-audit.mjs",
     "dev:hmr": "node scripts/enable-dev-hmr.mjs",
     "docs:check": "node scripts/check-docs.mjs",
-    "check": "npm test && npm run docs:check"
+    "docs:generate:errors": "node scripts/generate-error-reference.mjs",
+    "docs:check:generated": "node scripts/generate-error-reference.mjs --check",
+    "docs:generate:tools": "node scripts/generate-tools-reference.mjs",
+    "docs:check:generated:tools": "node scripts/generate-tools-reference.mjs --check",
+    "docs:generate:config": "node scripts/generate-config-reference.mjs",
+    "docs:check:generated:config": "node scripts/generate-config-reference.mjs --check",
+    "pack:check": "node scripts/check-pack.mjs",
+    "architecture:check": "node scripts/architecture.mjs",
+    "types:check": "tsc --noEmit",
+    "check": "npm test && npm run docs:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
+    "domain:metrics": "node scripts/domain-metrics.mjs",
+    "domain:check": "node scripts/domain-metrics.mjs --check"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "~3.18.5"
+    "@deepseek-ai/schemastery": "~3.18.5",
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "~5.9.3"
   }
 }

package/ports/clock.js

@@ -0,0 +1,6 @@
+// Clock port (#56).
+/**
+ * @typedef {object} ClockPort
+ * @property {() => number} now
+ */
+export {}

package/ports/ids.js

@@ -0,0 +1,7 @@
+// Ids port (#56).
+/**
+ * @typedef {object} IdsPort
+ * @property {() => string} uuid
+ * @property {(text: string) => string} shortHash
+ */
+export {}

package/ports/index.js

@@ -0,0 +1,2 @@
+// Explicit ports consumed by app use cases (#56).
+export {}

package/ports/store.js

@@ -0,0 +1,11 @@
+// Store port (#56). Implementation: adapters/store-fs.js.
+/**
+ * @typedef {object} StorePort
+ * @property {(file: string) => Promise<boolean>} exists
+ * @property {(dir: string) => Promise<void>} ensureDir
+ * @property {(file: string) => Promise<any>} readJson
+ * @property {(file: string, value: unknown) => Promise<void>} writeJsonAtomic
+ * @property {(file: string, value: unknown) => Promise<void>} appendJsonl
+ * @property {(paths: object, fn: () => Promise<any>, options?: object) => Promise<any>} withLock
+ */
+export {}

package/ports/vcs.js

@@ -0,0 +1,11 @@
+// Vcs port (#56). Implementation: adapters/vcs-git.js.
+/**
+ * @typedef {object} VcsPort
+ * @property {(cwd: string, args: string[], options?: object) => Promise<string>} git
+ * @property {(cwd: string, args: string[], options?: object) => Promise<string|null>} tryGit
+ * @property {(cwd: string, ref: string) => Promise<string>} revParse
+ * @property {(cwd: string) => Promise<boolean>} isClean
+ * @property {(cwd: string, a: string, b: string) => Promise<boolean>} isAncestor
+ * @property {(repoRoot: string) => Promise<{root:string, commonDir:string, branch:string|null}>} resolveRepo
+ */
+export {}

package/scripts/architecture.mjs

@@ -0,0 +1,94 @@
+// Architecture fitness functions (#55).
+//
+// Rules are intentionally staged: rules for not-yet-migrated areas are
+// warnings (printed, exit 0) and flip to errors in the PR that makes them true.
+// The evaluator is exported so tests can seed one fixture violation per rule.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const ROOTS = ['lib', 'app', 'domain', 'tools', 'adapters', 'ports']
+const CHILD_PROCESS_ALLOWED = new Set(['adapters/vcs-git.js'])
+const FS_ALLOWED = new Set(['adapters/store-fs.js'])
+// Composition roots own the only intentional process-wide mutable state.
+const AMBIENT_ALLOWED = new Set(['lib/config.js', 'lib/git.js'])
+// The registration aggregator wires tool modules together; the thinness rule
+// applies to the individual modules under tools/.
+const TOOLS_REGISTRATION = new Set(['tools/index.js'])
+// The registration aggregator is the only tools/ module above the 200-line
+// per-tool ceiling: it wires the individual modules together. P3c split
+// tower_spawn, so every tool module now enforces the ceiling.
+const TOOLS_SIZE_ALLOWED = new Set(['tools/index.js'])
+const LITERAL_PATTERN = /enum:\s*\[\s*'(?:planned|active|completed|blocked|paused|abandoned|worker|reviewer|bug|improve|vuln|idea|low|medium|high|critical|open|triaged|fixed|wontfix)'/
+const TOOL_LITERAL_PATTERN = /(?:===|!==|==|!=|\.includes\(|case\s+)'?(?:planned|active|completed|blocked|paused|abandoned|worker|reviewer|bug|improve|vuln|idea|low|medium|high|critical|open|triaged|fixed|wontfix|create|abandon|close|status|merge|fix-then-merge|hold|acquire|release|map|user|failure|resource|dependency|json|markdown)'/
+
+function walk(root, relative = '') {
+  const dir = path.join(root, relative)
+  if (!fs.existsSync(dir)) return []
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const next = path.join(relative, entry.name)
+    if (entry.isDirectory()) out.push(...walk(root, next))
+    else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) out.push(next.split(path.sep).join('/'))
+  }
+  return out
+}
+
+function evaluator(root) {
+  const files = ROOTS.flatMap((dir) => walk(root, dir)).filter((file) => !file.includes('/node_modules/'))
+  const violations = []
+  const record = (rule, file, detail, level) => violations.push({ rule, file, detail, level })
+
+  for (const file of files) {
+    const text = fs.readFileSync(path.join(root, file), 'utf8')
+    const lines = text.split('\n')
+    const imports = [...text.matchAll(/from\s+'([^']+)'|require\('([^']+)'\)/g)].map((match) => match[1] ?? match[2])
+    if (file.startsWith('domain/') && imports.some((spec) => /^(node:fs|node:fs\/promises|node:child_process|\.\.\/adapters|adapters\/)/.test(spec))) {
+      record('domain-pure', file, 'domain imports I/O or adapters', 'error')
+    }
+    if (imports.includes('node:child_process') && !CHILD_PROCESS_ALLOWED.has(file)) {
+      record('child-process-surface', file, 'only adapters/** may spawn processes', 'error')
+    }
+    if (imports.some((spec) => spec === 'node:fs' || spec === 'node:fs/promises') && !FS_ALLOWED.has(file)) {
+      record('fs-surface', file, 'only adapters/** may use fs', 'error')
+    }
+    if (file.startsWith('tools/')) {
+      if (imports.some((spec) => spec.startsWith('node:') && spec !== 'node:path')) {
+        record('tools-thin', file, 'tools/** may import only node:path', 'error')
+      }
+      if (LITERAL_PATTERN.test(text) || TOOL_LITERAL_PATTERN.test(text)) {
+        record('tools-vocabulary', file, 'status/type/role literal in tools/**', 'error')
+      }
+      if (lines.length < 40 || lines.length > 200) {
+        record('aggregate-size', file, `${lines.length} lines outside 40-200`, 'error')
+      }
+    } else if (lines.length > 800) {
+      record('aggregate-size', file, `${lines.length} lines exceeds 800`, 'error')
+    }
+    if (/^(?:export\s+)?let\s+/m.test(text) && !AMBIENT_ALLOWED.has(file) && (file.startsWith('lib/') || file.startsWith('app/') || file.startsWith('domain/'))) {
+      record('ambient-state', file, 'top-level let outside an allow-list', 'error')
+    }
+  }
+  return { ok: violations.every((violation) => violation.level !== 'error'), violations }
+}
+
+const rootArg = process.argv.indexOf('--root')
+const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : PACKAGE_ROOT
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+  const result = evaluator(root)
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    for (const violation of result.violations) {
+      const line = `architecture ${violation.level}: [${violation.rule}] ${violation.file}: ${violation.detail}`
+      if (violation.level === 'error') console.error(line)
+      else console.warn(line)
+    }
+    if (result.violations.length === 0) console.log('architecture: ok')
+  }
+  process.exit(result.ok ? 0 : 1)
+}
+
+export { evaluator }

package/scripts/check-docs.mjs

@@ -9,14 +9,20 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const read = (file) => fs.readFileSync(path.join(root, file), 'utf8')
 const exists = (file) => fs.existsSync(path.join(root, file))
 
-const toolsSource = read('lib/tools.js') + read('index.js')
+const toolModuleSources = fs.existsSync(path.join(root, 'tools'))
+  ? fs.readdirSync(path.join(root, 'tools'))
+      .filter((name) => name.endsWith('.js'))
+      .map((name) => read(`tools/${name}`))
+      .join('\n')
+  : ''
+const toolsSource = read('tools/index.js') + toolModuleSources + read('lib/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')
   .sort()
 const missingTools = toolNames.filter((name) => !documentedTools.includes(`\`${name}\``))
 
-const towerSource = read('lib/tower.js')
+const towerSource = read('app/tower.js')
 const blockersSource = read('docs/reference/blockers.md')
 const blockerCodes = new Set()
 for (const match of towerSource.matchAll(/push\(\s*'([a-z][a-z-]+)'/g)) blockerCodes.add(match[1])
@@ -77,16 +83,20 @@ const eventNames = [
   'status',
   'preflight',
   'doctor',
+  'recover',
   'test',
   'batch',
   'resource',
   'import_legacy',
   'legacy_map',
+  'mode',
+  'control',
+  'reload',
 ]
 const documentedEvents = read('docs/reference/events.md')
 const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
 
-const errorsSource = read('lib/errors.js')
+const errorsSource = read('domain/errors.js')
 const documentedErrors = read('docs/reference/errors.md')
 const errorCodes = [...new Set([...errorsSource.matchAll(/^ {2}'([a-z][a-z-]+)':/gm)].map((match) => match[1]))].sort()
 const missingErrors = errorCodes.filter((code) => !documentedErrors.includes(`\`${code}\``))
@@ -102,6 +112,37 @@ if (missingErrors.length > 0) problems.push(`docs/reference/errors.md misses cod
 if (missingEvents.length > 0) problems.push(`docs/reference/events.md misses events: ${missingEvents.join(', ')}`)
 if (missingChangelog) problems.push(`CHANGELOG.md misses version ${packageJson.version}`)
 
+// Counts and high-risk defaults are part of the contract, not just names.
+const toolsDoc = read('docs/reference/tools.md')
+const blockersDoc = read('docs/reference/blockers.md')
+const errorsDoc = read('docs/reference/errors.md')
+const eventsDoc = read('docs/reference/events.md')
+const configDoc = read('docs/reference/config.md')
+const zhConfigDoc = read('docs/zh/reference/config.md')
+if (!toolsDoc.includes(`up to ${toolNames.length} tools`)) {
+  problems.push(`docs/reference/tools.md must state "up to ${toolNames.length} tools"`)
+}
+if (!blockersDoc.includes(`${blockerCodes.size} stable blocker/failure codes`)) {
+  problems.push(`docs/reference/blockers.md must state ${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`)
+}
+for (const required of [
+  '| `tests.admission` | `off` |',
+  '| `review.requireReview` | `false` |',
+  '| `mode.allowAgentControl` | `true` |',
+  '| `git.timeoutMs` | `15000` |',
+]) {
+  if (!configDoc.includes(required)) problems.push(`docs/reference/config.md misses required default: ${required}`)
+}
+if (!zhConfigDoc.includes('| `tests.admission` | `off` |')) {
+  problems.push('docs/zh/reference/config.md misses the tests.admission default')
+}
+
 // Chinese parity: when the translation tree exists it must cover the same
 // reference names, so a tool or code cannot be added only in English.
 if (exists('docs/zh')) {

package/scripts/check-pack.mjs

@@ -0,0 +1,49 @@
+// Fail when the published file list drifts from the reviewed snapshot.
+// Run: node scripts/check-pack.mjs [--write]
+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 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 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)
+}
+console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)

package/scripts/domain-metrics.mjs

@@ -0,0 +1,48 @@
+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 SOURCE_ROOTS = ['domain', 'app', 'tools', 'adapters', 'lib']
+const ENTRY_FILES = ['index.js', 'worker.js', 'reviewer.js', 'skills.js']
+const PURE_ROOTS = ['domain']
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) walk(full, out)
+    else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) out.push(full)
+  }
+  return out
+}
+
+function loc(file) {
+  return fs.readFileSync(file, 'utf8').split('\n').length
+}
+
+const files = SOURCE_ROOTS.flatMap((dir) => walk(path.join(root, dir)))
+for (const file of ENTRY_FILES) {
+  const full = path.join(root, file)
+  if (fs.existsSync(full)) files.push(full)
+}
+let pure = 0
+let total = 0
+for (const file of files) {
+  const lines = loc(file)
+  total += lines
+  const relative = path.relative(root, file).split(path.sep).join('/')
+  if (PURE_ROOTS.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) pure += lines
+}
+const share = total === 0 ? 0 : pure / total
+const result = { pure, total, share: Number(share.toFixed(4)) }
+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})`)
+} else {
+  console.log(`domain-metrics: pure domain share ${(share * 100).toFixed(1)}% (${pure}/${total})`)
+}

package/scripts/generate-config-reference.mjs

@@ -0,0 +1,46 @@
+// Generate the config reference from the schemastery schema (#46).
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Config, resolveTowerConfig } from '../domain/config/schema.js'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const target = path.join(root, 'docs', 'reference', 'config.generated.md')
+const defaults = resolveTowerConfig({})
+const rows = []
+for (const [key, schema] of Object.entries(Config.dict ?? {})) {
+  const dict = schema?.dict
+  if (dict && typeof dict === 'object') {
+    for (const [child, childSchema] of Object.entries(dict)) {
+      rows.push(format(`${key}.${child}`, childSchema, schema))
+    }
+  } else {
+    rows.push(format(key, schema, Config))
+  }
+}
+function format(key, schema, parent) {
+  const value = key.split('.').reduce((current, part) => (current == null ? undefined : current[part]), defaults)
+  const fallback = value === undefined ? '' : JSON.stringify(value)
+  const description = String(schema?.meta?.description ?? parent?.meta?.description ?? '').replace(/\s+/g, ' ').trim()
+  return `| \`${key}\` | \`${fallback}\` | ${description} |`
+}
+const expected = `# Config reference (generated)
+
+> Generated by \`npm run docs:generate:config\` from \`domain/config/schema.js\`. Values are defaults before repo config.
+
+| Key | Default | Description |
+|---|---|---|
+${rows.join('\n')}
+`
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('config reference is stale; run npm run docs:generate:config')
+    process.exit(1)
+  }
+  console.log(`config reference: ${rows.length} keys in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${rows.length} keys)`)
+}

package/scripts/generate-error-reference.mjs

@@ -0,0 +1,29 @@
+// 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]
+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)
+
+> 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')}
+`
+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`)
+    process.exit(1)
+  }
+  console.log(`error reference: ${Object.keys(ERROR_CODES).length} codes in sync`)
+} 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)`)
+}

package/scripts/generate-tools-reference.mjs

@@ -0,0 +1,56 @@
+// Generate the tools overview from the registered tool definitions (#46).
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerTowerTools } from '../tools/index.js'
+
+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 rows = [...tools.values()]
+  .sort((a, b) => a.name.localeCompare(b.name))
+  .map((tool) => `| \`${tool.name}\` | ${String(tool.description ?? '').replace(/\s+/g, ' ').trim()} |`)
+const expected = `# Tools overview (generated)
+
+> Generated by \`npm run docs:generate:tools\` from the registered tool definitions. Do not edit by hand.
+
+| Tool | Description |
+|---|---|
+${rows.join('\n')}
+`
+if (process.argv.includes('--check')) {
+  const actual = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  if (actual !== expected) {
+    console.error('tools reference is stale; run npm run docs:generate:tools')
+    process.exit(1)
+  }
+  console.log(`tools reference: ${tools.size} tools in sync`)
+} else {
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, expected)
+  console.log(`wrote ${path.relative(root, target)} (${tools.size} tools)`)
+}
+process.exit(0)