dsh-tower 2.1.0 → 2.4.0

package/scripts/regression-audit.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Regression closure audit (#85): a closed `regression` issue must name a
+// `Regression test:` path that exists.
+//
+// A regression is "worked in a released version, then stopped". The project's
+// own closure standard is a pointer, not prose: the incident template
+// (docs/operations/incident.md) carries six fields and the regression test path
+// is the one that can be checked. This script reads a local tracker export, the
+// same format as `npm run audit:issues`, so it never touches the network:
+//
+//   { "issues": [ { number, title, state, labels, closedAt, body, comments } ] }
+//
+// Usage:
+//   node scripts/regression-audit.mjs [--tracker <file>] [--root <dir>] [--json]
+//
+// Exit codes: 0 all checked regressions point at an existing test; 1 at least
+// one is missing or points at a nonexistent/non-test path; 2 the export is
+// missing or malformed.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { inspectPointer, isClosed, labelsOf, parseTracker } from './issue-audit.mjs'
+import { findingRecorder, parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const DEFAULT_TRACKER = path.join('tracker', 'issues.json')
+const USAGE = `usage: node scripts/regression-audit.mjs [--tracker <file>] [--root <dir>] [--json]
+
+  --tracker  local tracker export (default: tracker/issues.json)
+  --root     repository the Regression test paths resolve against (default: this package)
+  --json     print the report as JSON
+  --help     print this text
+
+A regression issue is closed when state is closed (or closedAt is set) and its
+labels include "regression". Its body or newest comment must carry:
+
+  Regression test: tests/<file>.test.mjs
+
+The path must exist under --root and must be a test file. Produce the export once
+with gh (see CONTRIBUTING.md, "Regressions and incidents"); the audit itself is
+offline.`
+
+function cleanValue(value) {
+  return String(value)
+    .trim()
+    .replace(/^`+|`+$/g, '')
+    .trim()
+    .replace(/^["']+|["']+$/g, '')
+    .trim()
+}
+
+/**
+ * The newest text (body first, then comments oldest to newest) that carries a
+ * `Regression test:` line is the closure evidence. Returns `{ pointer }` or
+ * `{ error: 'missing' }`.
+ * @param {any} issue
+ */
+export function selectRegressionField(issue) {
+  const sources = []
+  if (typeof issue.body === 'string' && issue.body.trim()) sources.push(issue.body)
+  const comments = Array.isArray(issue.comments) ? issue.comments : []
+  for (const comment of comments) {
+    const body = typeof comment === 'string' ? comment : comment?.body
+    if (typeof body === 'string' && body.trim()) sources.push(body)
+  }
+  for (let index = sources.length - 1; index >= 0; index -= 1) {
+    for (const rawLine of sources[index].split(/\r?\n/)) {
+      const line = rawLine.replace(/^\s*(?:[-*+]\s+|>\s*)+/, '')
+      const match = /^Regression test\s*:\s*(.+)$/i.exec(line)
+      if (!match) continue
+      const pointer = cleanValue(match[1])
+      if (pointer) return { pointer }
+    }
+  }
+  return { error: 'missing' }
+}
+
+/**
+ * Audit closed regression issues against the repository test tree.
+ * @param {any[]} issues parsed tracker issues
+ * @param {{ root?: string }} [options]
+ */
+export function auditRegressions(issues, options = {}) {
+  const root = path.resolve(options.root ?? PACKAGE_ROOT)
+  const findings = []
+  let checked = 0
+  for (const issue of issues) {
+    if (!isClosed(issue)) continue
+    const labels = labelsOf(issue).map((label) => label.toLowerCase())
+    if (!labels.includes('regression')) continue
+    checked += 1
+    const label = `#${issue.number} ${String(issue.title ?? '').trim()}`
+    const record = findingRecorder(findings, { number: issue.number, title: issue.title })
+    const field = selectRegressionField(issue)
+    if (field.error) {
+      record(
+        'missing-regression-test',
+        'error',
+        `${label}: closed regression has no "Regression test:" field (see docs/operations/incident.md)`,
+      )
+      continue
+    }
+    const problem = inspectPointer(field.pointer, root)
+    if (!problem) continue
+    if (problem.code === 'missing-test') {
+      record('missing-regression-test', 'error', `${label}: Regression test names a missing file: ${field.pointer}`)
+    } else if (problem.code === 'not-a-test') {
+      record('not-a-test', 'error', `${label}: Regression test is not a test file: ${field.pointer} (${problem.detail})`)
+    } else {
+      record(
+        'invalid-regression-test',
+        'error',
+        `${label}: Regression test must be a repository-relative path: ${field.pointer} (${problem.detail})`,
+      )
+    }
+  }
+  const errors = findings.filter((item) => item.level === 'error')
+  return { ok: errors.length === 0, checked, findings, errors: errors.length }
+}
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { tracker: null, root: PACKAGE_ROOT, json: false, help: false },
+    values: {
+      '--tracker': 'tracker',
+      '--root': { key: 'root', parse: path.resolve },
+    },
+    flags: { '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const tracker = options.tracker ? path.resolve(process.cwd(), options.tracker) : path.join(PACKAGE_ROOT, DEFAULT_TRACKER)
+  let text
+  try {
+    text = fs.readFileSync(tracker, 'utf8')
+  } catch (error) {
+    console.error(`regression-audit: cannot read tracker export ${tracker}: ${error?.message ?? error}`)
+    console.error('regression-audit: produce one with the gh command in CONTRIBUTING.md ("Regressions and incidents")')
+    return 2
+  }
+  let issues
+  let result
+  try {
+    issues = parseTracker(text)
+    result = auditRegressions(issues, { root: options.root })
+  } catch (error) {
+    console.error(`regression-audit: ${error.message}`)
+    return 2
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ tracker, root: path.resolve(options.root), ...result }, null, 2))
+    return result.ok ? 0 : 1
+  }
+  console.log(`regression-audit: ${tracker}`)
+  console.log(`regression-audit: ${result.checked} closed regression(s) checked, ${result.errors} error(s)`)
+  for (const item of result.findings) console.log(`${item.level} [${item.code}] ${item.message}`)
+  if (result.ok) console.log('regression-audit: every closed regression names an existing test file')
+  else console.log('regression-audit: a closed regression has no verifiable test pointer; see docs/operations/incident.md')
+  return result.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'regression-audit', usage: USAGE })

package/scripts/release-check.mjs

@@ -27,7 +27,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { compareVersions } from '../lib/compatibility.js'
+import { compareVersions } from '../host/compatibility.js'
 import { findingRecorder, parseArgs, runMain, UsageError } from './lib/cli.mjs'
 
 const USAGE = `usage: node scripts/release-check.mjs [--mode pr|tag] [--tag <name>] [--json] [--help]

package/scripts/surface-baseline.json

@@ -0,0 +1,52 @@
+{
+  "schema": 1,
+  "date": "2026-10-23",
+  "surfaces": {
+    "configKeys": {
+      "seed": 64,
+      "value": 56,
+      "decisions": []
+    },
+    "sections": {
+      "seed": 15,
+      "value": 14,
+      "decisions": []
+    },
+    "tools": {
+      "seed": 27,
+      "value": 29,
+      "decisions": [
+        {
+          "from": 27,
+          "to": 29,
+          "date": "2026-10-23",
+          "correction": {
+            "reason": "Measurement correction, not surface growth: the 2.3.0 baseline recorded only define()-registered tools. tower_mode and tower_control are registered directly by index.js, so the shipped surface was always 29 (#118). The recorder in host/tool-registry.js now covers both paths.",
+            "date": "2026-10-23",
+            "ref": "docs/adr/0004-surface-budget.md"
+          }
+        }
+      ]
+    },
+    "components": {
+      "seed": 4,
+      "value": 8,
+      "decisions": [
+        {
+          "from": 4,
+          "to": 1,
+          "date": "2026-10-23",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "The component surface joins the budget with its history. 2.0.4 shipped four top-level rows (tower, tower-skills, preset-tower-worker, preset-tower-reviewer); 2.3.0 replaced them with one tower-bundle group row that still mounts the same four sections. This is a recorded contraction, not a free ratchet: the seed stays at 4 so any further move -- including the #121 growth back to individually toggleable optional rows -- must extend this chain with a dated decision."
+        },
+        {
+          "from": 1,
+          "to": 8,
+          "date": "2026-10-23",
+          "adr": "docs/adr/0005-component-surface.md",
+          "note": "#121 restores the #65 policy from ADR 0005: the one tower-bundle group becomes a mandatory tower host anchor plus seven individually switchable optional rows (tower-skills, tower-batch, tower-import, tower-leases, tower-tests, tower-hmr shipped off, preset-tower-reviewer conditional). The host anchor and preset-tower-worker stay mandatory; tower_doctor and tower_recover stay mandatory with the host (#122), so they are not rows. configKeys and sections shrank in the same wave because the seven tools.expose* keys and dev.hotReload became rows."
+        }
+      ]
+    }
+  }
+}

package/scripts/surface-baseline.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Concept-budget gate (#84): compare the live surface with the committed
+// baseline and require evidence for growth.
+//
+// The surface is four counts the user has to hold at once:
+//   config keys   leaf keys in domain/config/schema.js (one level deep)
+//   sections      object groups in that schema
+//   tools         every tool the Host entry registers, including the
+//                 tower_mode/tower_control pair that index.js registers
+//                 directly rather than through define() (#118)
+//   components    user-visible rows in cordis.patch.yml (#120), so the 2.3.0
+//                 4 -> 1 contraction and any future move need a written decision
+//
+// `scripts/surface-baseline.json` freezes those counts. A PR that grows a count
+// fails here until the baseline carries a decision with either an ADR under
+// docs/adr/, deletions that no longer exist in the live surface, or an explicit
+// measurement-correction record (reason + date). The same file supplies the date
+// and counts printed in the generated config/tools reference headers, so growth
+// is visible in a diff.
+//
+// Usage:
+//   node scripts/surface-baseline.mjs [--root <dir>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { configSurface } from '../domain/config/schema.js'
+import { parseCordisPatch } from '../domain/components.js'
+import { SURFACE_CLASSIFICATION_FILE, SURFACE_BASELINE_FILE, surfaceLine } from '../domain/surface.js'
+import { loadShippedToolSurface } from './lib/tool-surface.mjs'
+import { checkSurfaceBudget } 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/surface-baseline.mjs [--root <dir>] [--json]
+
+  --root   repository root to check (default: this package)
+  --json   print the report as JSON
+  --help   print this text
+
+Growth is refused by default. To grow a count, update ${SURFACE_BASELINE_FILE}
+with a decision that names an existing docs/adr/ ADR, deletions that are no
+longer in the live surface, or a measurement-correction record with a reason and
+date. The classification table in
+${SURFACE_CLASSIFICATION_FILE} must cover every key and tool exactly once, and
+the component count comes from the visible rows in cordis.patch.yml.`
+
+/**
+ * The live tool names: apply the shipped Host entry so every registration path
+ * is included, then release the mock context's timers.
+ */
+function liveToolNames() {
+  const surface = loadShippedToolSurface()
+  try {
+    return surface.names
+  } finally {
+    surface.dispose()
+  }
+}
+
+/**
+ * The live surface used by the gate. Exported so tests can compare the counts
+ * with the generated references without spawning the CLI.
+ * @param {string} [root] repository root (defaults to this package)
+ */
+export function liveSurface(root = PACKAGE_ROOT) {
+  const config = configSurface()
+  const tools = liveToolNames()
+  const patch = parseCordisPatch(fs.readFileSync(path.join(root, 'cordis.patch.yml'), 'utf8'))
+  return {
+    configKeys: config.count,
+    sections: config.sections.length,
+    tools: tools.length,
+    components: patch.visible.length,
+    liveNames: {
+      configKeys: config.keys,
+      sections: config.sections,
+      tools,
+      components: patch.visible,
+    },
+  }
+}
+
+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 root = path.resolve(options.root)
+  if (!fs.existsSync(path.join(root, SURFACE_BASELINE_FILE))) {
+    console.error(`surface: ${SURFACE_BASELINE_FILE} is missing under ${root}`)
+    return 2
+  }
+  const current = liveSurface()
+  const result = checkSurfaceBudget({ root, current })
+  if (options.json) {
+    console.log(JSON.stringify({ root, current, ...result }, null, 2))
+    return result.ok ? 0 : 1
+  }
+  console.log(`surface: ${surfaceLine(current)}`)
+  console.log(`surface: components: ${current.components} visible (${current.liveNames.components.join(', ')})`)
+  if (result.baseline) console.log(`surface: baseline ${result.baseline.date} (${SURFACE_BASELINE_FILE})`)
+  if (result.classification) {
+    const configRows = result.classification.entries.filter((entry) => entry.kind === 'config').length
+    const toolRows = result.classification.entries.filter((entry) => entry.kind === 'tools').length
+    console.log(`surface: classified ${configRows} config keys and ${toolRows} tools (${SURFACE_CLASSIFICATION_FILE})`)
+  }
+  for (const finding of result.findings) console.log(`surface: ${finding.level} [${finding.code}] ${finding.message}`)
+  if (result.ok) console.log('surface: ok — counts match the committed baseline and every entry is classified')
+  else console.log(`surface: ${result.findings.length} problem(s); growth needs an ADR or a matching deletion`)
+  return result.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'surface', usage: USAGE })

package/scripts/types-coverage.mjs

@@ -0,0 +1,184 @@
+// Type-coverage fitness rule (#115, step 1).
+//
+// The checked program must be derived from the shipped program: every runtime
+// `.js` file that `package.json` publishes has to appear in the `tsc` program,
+// otherwise "this file is unchecked" cannot even be reported. Today the
+// tsconfig `include` list is hand-written, so a new module outside it is
+// invisible by construction; this gate makes that gap a red check.
+//
+// Run: node scripts/types-coverage.mjs [--root <dir>] [--json]
+//
+// The shipped set comes from `package.json` `files` (the same list `npm pack`
+// uses; scripts/pack-manifest.txt pins the reviewed snapshot). The checked set
+// comes from `tsc --noEmit --listFiles`, so no second enumeration is involved:
+// changing the tsconfig is enough and this gate follows.
+//
+// Excluded tiers are data with a reason, not silent gaps:
+//   - `ui-bundle/**` is the optional Web client: a browser artifact with DOM
+//     types and no Node runtime, checked by tests/ui-bundle.test.mjs and the
+//     architecture client rules instead of the Node tsc program;
+//   - `scripts/**` is build/dev tooling (ESM `.mjs`, not plugin runtime).
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = path.resolve(MODULE_DIR, '..')
+const TSC_BIN = path.join(SELF_ROOT, 'node_modules', 'typescript', 'bin', 'tsc')
+const WALK_SKIP = new Set(['node_modules', '.git', '.dsh-tower-worktrees', 'coverage', '.nyc_output'])
+
+/** Shipped `.js` tiers that are deliberately outside the Node tsc program. */
+export const NOT_CHECKED_TIERS = [
+  {
+    pattern: 'ui-bundle/**',
+    reason: 'optional Web client: browser artifact, checked by tests/ui-bundle.test.mjs and the client architecture rules',
+  },
+  {
+    pattern: 'scripts/**',
+    reason: 'build/dev tooling, not plugin runtime',
+  },
+]
+
+/** Expand one package.json `files` pattern into repo-relative paths. */
+export function globToRegExp(pattern) {
+  const source = String(pattern)
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]')
+    .replace(/\u0000\//g, '(?:[^/]+/)*')
+    .replace(/\u0000/g, '.*')
+  return new RegExp(`^${source}$`)
+}
+
+function walkFiles(root, relative = '') {
+  const dir = path.join(root, relative)
+  if (!fs.existsSync(dir)) return []
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (WALK_SKIP.has(entry.name)) continue
+    const next = relative ? `${relative}/${entry.name}` : entry.name
+    if (entry.isDirectory()) out.push(...walkFiles(root, next))
+    else out.push(next)
+  }
+  return out
+}
+
+/**
+ * Resolve `package.json` `files` into the repo-relative file list.
+ * A trailing slash (or a bare directory name) means the whole directory, the
+ * same reading `npm pack` gives it.
+ * @param {string[]} patterns
+ * @param {string[]} files every repo-relative file
+ * @returns {string[]}
+ */
+export function expandShipped(patterns, files) {
+  const out = new Set()
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string' || pattern.length === 0) continue
+    const normalized = pattern.endsWith('/') ? `${pattern}**` : pattern
+    const matcher = globToRegExp(normalized)
+    const directory = !/\*|\?/.test(normalized) && files.some((file) => file.startsWith(`${normalized}/`))
+    const hit = (file) => (directory ? file === normalized || file.startsWith(`${normalized}/`) : matcher.test(file))
+    for (const file of files) if (hit(file)) out.add(file)
+  }
+  return [...out].sort()
+}
+
+/**
+ * The Node-runtime slice of the shipped set: `.js` files minus the documented
+ * non-Node tiers.
+ * @param {string[]} shipped
+ * @returns {{ runtime: string[], excluded: Array<{ file: string, reason: string }> }}
+ */
+export function runtimeJavaScript(shipped) {
+  const excluded = []
+  const runtime = []
+  for (const file of shipped) {
+    if (!file.endsWith('.js')) continue
+    const tier = NOT_CHECKED_TIERS.find((entry) => globToRegExp(entry.pattern).test(file))
+    if (tier) excluded.push({ file, reason: tier.reason })
+    else runtime.push(file)
+  }
+  return { runtime: runtime.sort(), excluded }
+}
+
+/**
+ * Compare the shipped runtime set with the checked program. One direction only:
+ * a shipped file outside the program fails. Extra program files (tests/*.ts,
+ * the declaration files, fixture helpers) are expected and allowed.
+ * @param {{ runtime: string[], program: string[] }} input
+ * @returns {{ ok: boolean, missing: string[], checked: number, total: number }}
+ */
+export function evaluateCoverage({ runtime, program }) {
+  const checked = new Set(program)
+  const missing = runtime.filter((file) => !checked.has(file))
+  return { ok: missing.length === 0, missing, checked: runtime.length - missing.length, total: runtime.length }
+}
+
+/** List the project files (never node_modules) in the `tsc` program. */
+function programFiles(root) {
+  const config = path.join(root, 'tsconfig.json')
+  if (!fs.existsSync(config)) throw new Error(`no tsconfig.json under ${root}`)
+  if (!fs.existsSync(TSC_BIN)) throw new Error('typescript is not installed; run npm ci first')
+  let output
+  try {
+    output = execFileSync(process.execPath, [TSC_BIN, '--noEmit', '--listFiles', '-p', config], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch (error) {
+    // A program with type errors still lists its files; only a config failure
+    // (no input at all) is fatal for this gate. Keep diagnostics out of the
+    // parse by only accepting existing absolute paths.
+    output = String(error?.stdout ?? '')
+    if (!output.trim()) throw new Error(`tsc --listFiles failed: ${String(error?.stderr ?? error?.message ?? error)}`)
+  }
+  const files = new Set()
+  for (const raw of output.split('\n')) {
+    const line = raw.trim()
+    if (!line || !path.isAbsolute(line)) continue
+    if (!fs.existsSync(line)) continue
+    const relative = path.relative(root, line).split(path.sep).join('/')
+    if (!relative || relative.startsWith('..') || relative.startsWith('node_modules/')) continue
+    if (relative.includes('/node_modules/')) continue
+    files.add(relative)
+  }
+  return [...files].sort()
+}
+
+function main() {
+  const rootArg = process.argv.indexOf('--root')
+  const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : SELF_ROOT
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+  const shipped = expandShipped(Array.isArray(pkg.files) ? pkg.files : [], walkFiles(root))
+  const { runtime, excluded } = runtimeJavaScript(shipped)
+  let program
+  try {
+    program = programFiles(root)
+  } catch (error) {
+    console.error(`types coverage: ${String(error?.message ?? error)}`)
+    process.exit(1)
+  }
+  const result = evaluateCoverage({ runtime, program })
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ ...result, program: program.length, excluded }, null, 2))
+  } else if (result.ok) {
+    console.log(
+      `types coverage: ${result.checked}/${result.total} shipped runtime .js files are in the tsc program` +
+        ` (${program.length} program files, ${excluded.length} excluded: ${[...new Set(excluded.map((entry) => entry.file.split('/')[0]))].join(', ') || 'none'})`,
+    )
+  } else {
+    console.error(
+      `types coverage: ${result.missing.length} shipped runtime .js file(s) are outside the tsc program:`,
+    )
+    for (const file of result.missing) console.error(`  - ${file}`)
+    console.error('add the file (or its directory glob) to tsconfig.json `include`')
+  }
+  process.exit(result.ok ? 0 : 1)
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) main()

package/scripts/types-strict-manifest.txt

@@ -0,0 +1,10 @@
+domain/contracts/outputs.js
+domain/contracts/tool-inputs/collaboration.js
+domain/contracts/tool-inputs/findings.js
+domain/contracts/tool-inputs/index.js
+domain/contracts/tool-inputs/integration.js
+domain/contracts/tool-inputs/missions.js
+domain/contracts/tool-inputs/ops.js
+domain/contracts/tool-inputs/shared.js
+types/cordis.d.ts
+types/index.d.ts

package/scripts/types-strict.mjs

@@ -0,0 +1,141 @@
+// Strict type ratchet (#115, step 4).
+//
+// `tsconfig.strict.json` turns `noImplicitAny: true` on for an explicit,
+// growing file list. The list is the ratchet: CI runs the strict config, and
+// this gate makes the list a reviewed artifact instead of a file that can
+// silently shrink.
+//
+// Run: node scripts/types-strict.mjs [--write] [--allow-shrink] [--root <dir>]
+//
+//   * no flag          — check: every listed file exists, every file in the
+//                        seed tier (`domain/contracts/**`) is listed, and the
+//                        reviewed snapshot (scripts/types-strict-manifest.txt)
+//                        matches the list exactly.
+//   * --write          — record the current list in the snapshot. Removing an
+//                        entry additionally needs `--allow-shrink`, so shrinking
+//                        the ratchet is a deliberate, visible decision.
+//
+// The list must stay explicit files: a glob would let a new file enter the
+// strict program without a reviewed one-line diff, which is the opposite of a
+// ratchet. `domain/contracts/**` is the seed tier: adding a file there fails
+// the check until the list and the snapshot name it.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SELF_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+export const MANIFEST = 'scripts/types-strict-manifest.txt'
+const SEED_DIRECTORIES = ['domain/contracts']
+
+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 = `${relative}/${entry.name}`
+    if (entry.isDirectory()) out.push(...walk(root, next))
+    else out.push(next)
+  }
+  return out
+}
+
+/** Entries that are not repo-relative explicit files. @param {unknown} include */
+export function invalidEntries(include) {
+  if (!Array.isArray(include) || include.length === 0) return ['include must be a non-empty array of files']
+  const problems = []
+  for (const entry of include) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      problems.push(`${JSON.stringify(entry)} is not a non-empty path`)
+      continue
+    }
+    if (path.isAbsolute(entry) || entry.includes('\\') || entry.split('/').includes('..')) {
+      problems.push(`${entry}: use a repo-relative path with forward slashes`)
+    } else if (/[*?]/.test(entry)) {
+      problems.push(`${entry}: the strict list must name explicit files, not a glob`)
+    }
+  }
+  return problems
+}
+
+/** @param {{ include: string[], manifest: string[] }} input */
+export function compareLists({ include, manifest }) {
+  const listed = new Set(include)
+  const pinned = new Set(manifest)
+  return {
+    lost: manifest.filter((file) => !listed.has(file)).sort(),
+    grew: include.filter((file) => !pinned.has(file)).sort(),
+  }
+}
+
+/** Every seed-tier file the strict list must name. */
+function seedFiles(root) {
+  return SEED_DIRECTORIES.flatMap((directory) => walk(root, directory)).filter((file) => file.endsWith('.js')).sort()
+}
+
+function readManifest(root) {
+  const file = path.join(root, MANIFEST)
+  if (!fs.existsSync(file)) return []
+  return fs.readFileSync(file, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean)
+}
+
+function fail(lines) {
+  console.error('types strict: the ratchet would shrink or drift:')
+  for (const line of lines) console.error(`  - ${line}`)
+  process.exit(1)
+}
+
+function main() {
+  const rootArg = process.argv.indexOf('--root')
+  const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : SELF_ROOT
+  const write = process.argv.includes('--write')
+  const allowShrink = process.argv.includes('--allow-shrink')
+  const configFile = path.join(root, 'tsconfig.strict.json')
+
+  if (!fs.existsSync(configFile)) {
+    console.error(`types strict: ${path.relative(process.cwd(), configFile)} is missing`)
+    process.exit(1)
+  }
+  const config = JSON.parse(fs.readFileSync(configFile, 'utf8'))
+  if (config?.compilerOptions?.noImplicitAny !== true) {
+    console.error('types strict: tsconfig.strict.json must set compilerOptions.noImplicitAny: true explicitly')
+    process.exit(1)
+  }
+  const include = Array.isArray(config.include) ? config.include : []
+  const invalid = invalidEntries(include)
+  if (invalid.length > 0) fail(invalid)
+
+  const missingFiles = include.filter((file) => !fs.existsSync(path.join(root, file)))
+  if (missingFiles.length > 0) fail(missingFiles.map((file) => `${file}: listed in tsconfig.strict.json but does not exist`))
+
+  const seeds = seedFiles(root)
+  const unlistedSeeds = seeds.filter((file) => !include.includes(file))
+  if (unlistedSeeds.length > 0) {
+    fail(unlistedSeeds.map((file) => `${file}: in the seed tier but not in tsconfig.strict.json include`))
+  }
+
+  const manifest = readManifest(root)
+  const { lost, grew } = compareLists({ include, manifest })
+  if (write) {
+    if (lost.length > 0 && !allowShrink) {
+      fail([
+        ...lost.map((file) => `${file}: pinned in ${MANIFEST} but missing from tsconfig.strict.json include`),
+        'pass --allow-shrink to record a deliberate removal',
+      ])
+    }
+    fs.mkdirSync(path.join(root, 'scripts'), { recursive: true })
+    fs.writeFileSync(path.join(root, MANIFEST), `${[...include].sort().join('\n')}\n`)
+    console.log(`types strict: wrote ${include.length} files to ${MANIFEST} (${lost.length} removed, ${grew.length} added)`)
+    return
+  }
+
+  if (lost.length > 0 || grew.length > 0) {
+    fail([
+      ...lost.map((file) => `${file}: pinned in ${MANIFEST} but no longer checked (the ratchet must not shrink)`),
+      ...grew.map((file) => `${file}: newly checked but not pinned; run npm run types:strict:write to record it`),
+    ])
+  }
+  console.log(`types strict: ${include.length} files pinned, noImplicitAny over ${SEED_DIRECTORIES.join(', ')}/**`)
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) main()