@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/repo-controls/src/config.ts

@@ -0,0 +1,690 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CONFIG_REL, INSTALL_HINT } from './constants.ts'
+import { MERGE_STRATEGIES, type MergeStrategy } from './promote.ts'
+
+export interface StaticCheck {
+  label: string
+  run: string
+}
+
+/**
+ * There is NO schema version in the config file, deliberately.
+ *
+ * A `version = N` line in every repository is a second copy of a fact the installed
+ * package already owns, free to disagree with it — and it did: a file written in the
+ * new shape kept declaring the old one, so readers graded it against the wrong rules
+ * and reported five type errors about keys that had been deliberately removed. A
+ * per-repo copy is also editable, which makes a schema claim a user preference.
+ *
+ * The schema is whatever the installed binary writes. The single central record of
+ * which one that is lives in `.workflows/repo-controls.lock.json` as the package
+ * version, and `doctor` compares it against the running binary.
+ */
+
+/**
+ * What a repository's coverage summary IS, and how that repository makes one.
+ *
+ * The gate validates the artifact; it never produces it. `produce` is recorded
+ * so the repository states its own command in one place rather than in a
+ * justfile, a package.json script and a pipeline step that can disagree — the
+ * gate reads it to tell a human what to run, not to run it.
+ *
+ * Everything here was a hardcoded literal in the bundled coverage scripts,
+ * where `sourceRoots` alone appeared in nine places across five files. A
+ * repository whose trees are named anything else was graded against
+ * enact-m5's, which is why this moved into config.
+ */
+export interface CoverageConfig {
+  summary: string
+  produce: string
+  sourceRoots: string[]
+  srcTestRatioGlobs: string[]
+}
+
+/**
+ * A findings ratchet's floor, and the repo-owned commands that measure it.
+ *
+ * NO TOOL NAME IS EVER WRITTEN HERE, deliberately (owner correction,
+ * 2026-09-15: "the REPO declares what they will use for linting and dead
+ * code"). `counters` is a name -> command map the repository authors itself
+ * — `lint = "just check-biome-lint"` in enact-m5, `lint = "cargo clippy
+ * --message-format=json | ..."` in a Rust repo, `dead-code = "ruff check
+ * --output-format=json | ..."` in a Python one. The package knows only the
+ * name and the command, the same division `pre_push.static_checks` already
+ * draws for a repo-authored shell command it never interprets.
+ *
+ * The command's OUTPUT is the one place a contract exists, and it names no
+ * tool either: one repository-relative path per line on stdout, one line
+ * per finding location, for a counter that ran to completion. Exit 0 means
+ * "ran; stdout is a valid (possibly empty) path list"; any other exit is
+ * the counter failing to run at all, never zero findings and never a pass
+ * (`findings-ratchet.ts`'s own header states this in
+ * full). `floor` is a repository-relative path, not resolved through the
+ * Python compliance package's `<compliance>` tree placeholder — this gate
+ * is TypeScript, outside that package, and reads the path directly.
+ */
+export interface FindingsConfig {
+  floor: string
+  counters: Record<string, string>
+}
+
+export interface RepoControlsConfig {
+  branches: { protected: string[]; prefixes: string[] }
+  preCommit: { staticChecks: StaticCheck[]; stagedCoverage: boolean; docFreshness: boolean; compliance: boolean }
+  commitMsg: { staticChecks: StaticCheck[] }
+  release: { source: string; target: string; mergeStrategy: MergeStrategy; preBump: string[] }
+  postCommit: { staticChecks: StaticCheck[] }
+  prePush: {
+    coverageRatchet: boolean
+    findingsRatchet: boolean
+    staticChecks: StaticCheck[]
+    exportLinks: string[]
+    remote: string
+  }
+  coverage: CoverageConfig
+  findings: FindingsConfig
+  integrity: { watched: string[] }
+}
+
+/**
+ * Seeded by `install` as the `[controls]` table of the shared `adl-config.toml`
+ * (repo root) when that table is missing; user-owned afterwards. This text is
+ * also the exact byte span `install`/`uninstall` append/splice — see
+ * `extractTableSpan`/`removeTableSpan` — so it must start with the
+ * `[controls]` header line and never contain another line starting with `[`.
+ */
+/**
+ * The `[controls]` attributes `install` SCAFFOLDS, each independently.
+ *
+ * Install wires the hooks; it does not arm a gate. Only the three attributes below
+ * are written, and only when absent — an attribute already in the file is never
+ * rewritten, reordered or reformatted, whatever its value. Everything else
+ * (`pre_commit.*`, `pre_push.coverage_ratchet`, `pre_push.findings_ratchet`,
+ * `pre_push.static_checks`) is omitted and defaults to off, so a first install
+ * changes what no `git push` or `git commit` does until somebody opts in.
+ *
+ * `branches` and `pre_push.remote` are seeded rather than omitted because they are
+ * not gates — they are the vocabulary the gates are phrased in — and because
+ * `pre-push` reads their env vars with `${VAR:?}`, which aborts on an empty value.
+ * "No branch policy" therefore cannot be spelled as an empty list.
+ *
+ * Granularity is the top-level key inside `[controls]`: an inline table is one
+ * attribute, because editing inside one means rewriting bytes the user owns.
+ */
+export interface SeededAttribute {
+  key: string
+  text: string
+}
+
+export const SEEDED_ATTRIBUTES: SeededAttribute[] = [
+  {
+    key: 'branches',
+    text: `
+# pre-push refuses to push while one of these branches is checked out; prefixes: <prefix>/<kebab>.
+branches = { protected = ["main", "integration"], prefixes = ["feat", "fix", "docs", "chore"] }
+`,
+  },
+  {
+    key: 'pre_push',
+    text: `
+# Remote that pre-push and azdo-push push to and read status from.
+#
+# Every gate is OFF until its key is added here: installing wires the hooks and arms
+# nothing. Opt in by adding pre_commit (static_checks, staged_coverage, doc_freshness) or the
+# remaining pre_push keys (coverage_ratchet, findings_ratchet, static_checks). README,
+# "Configuration", lists each one. Deliberately no example assignments in this comment — commented TOML
+# is indistinguishable from a real setting to find-and-replace, in an editor or a script.
+pre_push = { remote = "origin" }
+`,
+  },
+]
+
+/**
+ * Seeded by `install` as the `[controls]` table of the shared `adl-config.toml`
+ * when that table is missing; user-owned afterwards. When the table already exists,
+ * install scaffolds only the individual `SEEDED_ATTRIBUTES` it lacks. This text is
+ * also the exact byte span `install`/`uninstall` append/splice — see
+ * `extractTableSpan`/`removeTableSpan` — so it must start with the `[controls]`
+ * header line and never contain another line starting with `[`.
+ */
+export const DEFAULT_CONFIG_TEXT = `[controls]${SEEDED_ATTRIBUTES.map((a) => a.text).join('')}`
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * Every table this package writes and splices as its own independent unit.
+ *
+ * `controls.compliance` is deliberately nested under `controls` rather than being a
+ * root-level `[compliance]`: `adl hook` rejects the whole shared document on an
+ * unrecognized ROOT key, so a root `[compliance]` turned every one of its runs into
+ * a decode error in any repo carrying it. Nesting keeps this package's config inside
+ * the one root key it already owns, which needs no coordination with the other two
+ * tools — the same "no tool parses another tool's table" rule the file is built on.
+ */
+export const OWNED_TABLES = ['controls', 'controls.compliance'] as const
+
+/**
+ * Locates a table's exact byte span in a shared `adl-config.toml`: from the line
+ * matching `^\[<tableName>\]\s*$` to the next line starting with `[` at column 0
+ * that is neither `[<tableName>]` nor a dotted sub-table `[<tableName>.*]` of it
+ * (so `[controls.compliance]` through `[controls.compliance.trees]` splice as one
+ * span) — except that a sub-table listed in `OWNED_TABLES` terminates the span
+ * instead, so parent and child stay independently spliceable. Known limitation: a
+ * hand-edited block containing a multi-line string whose content starts a line with
+ * `[` would confuse this — this tool never writes such content itself.
+ */
+function findTableSpan(text: string, tableName: string): { start: number; end: number } | null {
+  const starts: number[] = [0]
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') starts.push(i + 1)
+  const lines = text.split('\n').slice(0, starts.length)
+  const lineStart = (index: number): number => starts[index] ?? text.length
+
+  const escaped = escapeRegExp(tableName)
+  const headerRe = new RegExp(`^\\[${escaped}\\]\\s*$`)
+  const subTableRe = new RegExp(`^\\[${escaped}\\.`)
+  // A dotted sub-table that this package manages as its own independent span
+  // (`[controls.compliance]` living inside `[controls]`) must TERMINATE the parent's
+  // span rather than be swallowed by it. Without this, appending compliance to a repo
+  // that already has `[controls]` would change `[controls]`'s own recorded bytes, and
+  // the next install would read that as drift and refuse — an upgrade path that fails
+  // on every already-installed repo.
+  const nestedRes = OWNED_TABLES.filter((name) => name !== tableName && name.startsWith(`${tableName}.`)).map(
+    (name) => new RegExp(`^\\[${escapeRegExp(name)}\\]\\s*$|^\\[${escapeRegExp(name)}\\.`),
+  )
+  const isSeparatelyOwned = (line: string): boolean => nestedRes.some((re) => re.test(line))
+  const isSameTableLine = (line: string): boolean => (headerRe.test(line) || subTableRe.test(line)) && !isSeparatelyOwned(line)
+
+  const startLine = lines.findIndex((line) => headerRe.test(line))
+  if (startLine === -1) return null
+
+  let endLine = starts.length
+  for (let index = startLine + 1; index < starts.length; index++) {
+    const line = lines[index] ?? ''
+    if (/^\[/.test(line) && !isSameTableLine(line)) {
+      endLine = index
+      break
+    }
+  }
+  // Trim blank lines immediately before the boundary: they separate this table from
+  // whatever follows (or end-of-file), not content the table itself owns — so appending
+  // another table afterwards never retroactively changes this table's own byte span.
+  let contentEnd = endLine
+  while (contentEnd > startLine + 1 && (lines[contentEnd - 1] ?? '').trim() === '') contentEnd--
+  return { start: lineStart(startLine), end: contentEnd < starts.length ? lineStart(contentEnd) : text.length }
+}
+
+/** The exact bytes of a table's span (header through its last line, including dotted sub-tables), or `null` if absent. */
+export function extractTableSpan(text: string, tableName: string): string | null {
+  const span = findTableSpan(text, tableName)
+  return span === null ? null : text.slice(span.start, span.end)
+}
+
+/**
+ * `text` with `addition` inserted at the END of a table's span — after its last line,
+ * before whatever follows. Used to scaffold a single missing attribute into a table
+ * this package did not create: every existing byte, including comments, ordering and
+ * formatting, is preserved exactly, because nothing is parsed and re-serialized.
+ * Returns `text` unchanged when the table is absent.
+ */
+export function appendToTableSpan(text: string, tableName: string, addition: string): string {
+  const span = findTableSpan(text, tableName)
+  if (span === null) return text
+  const before = text.slice(0, span.end)
+  const separator = before.endsWith('\n') ? '' : '\n'
+  return `${before}${separator}${addition}${text.slice(span.end)}`
+}
+
+/**
+ * Keys this package once wrote and now owns the removal of. `version` was a per-repo
+ * copy of a fact the installed package already owns; it drifted, and a stale copy made
+ * every reader grade the file against the wrong rules. Install strips it, because it
+ * was never a user setting to preserve.
+ */
+export const RETIRED_ATTRIBUTES = ['version'] as const
+
+/**
+ * `text` with `key`'s assignment line removed from inside a table's span, along with a
+ * blank line left immediately after it. Every other byte is untouched — nothing is
+ * parsed and re-serialized. Returns `text` unchanged when the table or key is absent.
+ */
+export function removeFromTableSpan(text: string, tableName: string, key: string): string {
+  const span = findTableSpan(text, tableName)
+  if (span === null) return text
+  const body = text.slice(span.start, span.end)
+  const assignment = new RegExp(`^${escapeRegExp(key)}\\s*=.*\\n(\\n)?`, 'm')
+  if (!assignment.test(body)) return text
+  return text.slice(0, span.start) + body.replace(assignment, '') + text.slice(span.end)
+}
+
+/** `text` with a table's span removed (a no-op if there is none); other tables are untouched. */
+export function removeTableSpan(text: string, tableName: string): string {
+  const span = findTableSpan(text, tableName)
+  if (span === null) return text
+  let before = text.slice(0, span.start)
+  const after = text.slice(span.end)
+  if (before.endsWith('\n\n')) before = before.slice(0, -1)
+  return before + after
+}
+
+/** The exact bytes of the `[controls]` table, or `null` if absent. */
+export function extractControlsSpan(text: string): string | null {
+  return extractTableSpan(text, 'controls')
+}
+
+const BRANCH_RE = /^[a-z0-9][a-z0-9/-]*$/
+const PREFIX_RE = /^[a-z0-9][a-z0-9-]*$/
+const LABEL_RE = /^[a-z0-9][a-z0-9-]*$/
+const REMOTE_RE = /^\S+$/
+
+/**
+ * Where the ratchet looks when a repository does not say otherwise.
+ *
+ * This was a literal in five places (`coverage/paths.ts`, `command.ts`,
+ * `full.ts`, `check-floors.ts`, `doctor.ts`), which is why enact-extensions —
+ * tracking `.coverage/summary.json` and gitignoring `coverage/` — could not
+ * push at all. The non-JavaScript override is retained as an executable case
+ * in `tests/config.test.ts`.
+ */
+const DEFAULT_COVERAGE_SUMMARY = 'coverage/coverage-summary.json'
+
+/**
+ * Where a findings ratchet's floor lives when a repository does not say
+ * otherwise: `compliance/ratchets/`, the estate's settled location for a
+ * consumer-owned number that may fall (owner ruling 2026-09-15, "grants are
+ * basically ratchets" — `LAY-004`'s `compliance/ratchets/
+ * LAY-004-over-limit-directory.yaml` is the same convention for a Python
+ * compliance-package row). This gate is not a registry row, so the file is
+ * named by SUBJECT rather than a `<GATE-ID>-<name>` this package has no id
+ * for — see `findings-ratchet.ts`'s own header.
+ */
+const DEFAULT_FINDINGS_FLOOR = 'compliance/ratchets/static-analysis-findings.yaml'
+
+export type Table = Record<string, unknown>
+export const isTable = (value: unknown): value is Table => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+export class Problems {
+  readonly list: string[]
+  constructor() {
+    this.list = []
+  }
+  add(message: string): void {
+    this.list.push(message)
+  }
+  unknownKeys(table: Table, known: string[], prefix: string): void {
+    for (const key of Object.keys(table)) if (!known.includes(key)) this.add(`unknown key: ${prefix}${key}`)
+  }
+  table(parent: Table, key: string, known: string[]): Table {
+    const value = parent[key]
+    if (!isTable(value)) {
+      this.add(`${key} must be a table`)
+      return {}
+    }
+    this.unknownKeys(value, known, `${key}.`)
+    return value
+  }
+  /**
+   * A table this package SEEDS but does not require. Absent means "every control in
+   * it is off", never an error — installing wires the hooks and arms nothing, so a
+   * repository that never opted into a control simply has no key for it. Present but
+   * the wrong type is still a hard error, and unknown keys inside it still are too.
+   */
+  optionalTable(parent: Table, key: string, known: string[]): Table {
+    if (parent[key] === undefined) return {}
+    return this.table(parent, key, known)
+  }
+  /** Absent is the documented default; present-but-not-a-boolean is still an error. */
+  optionalBool(table: Table, key: string, name: string, fallback: boolean): boolean {
+    if (table[key] === undefined) return fallback
+    return this.bool(table, key, name)
+  }
+  bool(table: Table, key: string, name: string): boolean {
+    const value = table[key]
+    if (typeof value !== 'boolean') this.add(`${name} must be a boolean`)
+    return value === true
+  }
+  string(table: Table, key: string, name: string, pattern: RegExp): string {
+    const value = table[key]
+    if (typeof value !== 'string') {
+      this.add(`${name} must be a string`)
+      return ''
+    }
+    if (!pattern.test(value)) this.add(`${name} must match ${pattern.source}`)
+    return value
+  }
+  names(table: Table, key: string, name: string, pattern: RegExp): string[] {
+    const value = table[key]
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+      this.add(`${name} must be an array of strings`)
+      return []
+    }
+    if (value.length === 0) this.add(`${name} must not be empty`)
+    value.forEach((item: string, index) => {
+      if (!pattern.test(item)) this.add(`${name}[${index}] must match ${pattern.source}`)
+    })
+    return value as string[]
+  }
+  /** Absent means "take the default"; present but wrong-typed is still a problem. */
+  optionalString(table: Table, key: string, name: string, fallback: string): string {
+    const value = table[key]
+    if (value === undefined) return fallback
+    if (typeof value !== 'string' || value.trim() === '') {
+      this.add(`${name} must be a non-empty string`)
+      return fallback
+    }
+    return value
+  }
+  /** As above, for a list. An explicitly empty list is a problem, not a default:
+   *  writing `[]` reads as "grade nothing", which is never what anyone means. */
+  optionalNames(table: Table, key: string, name: string, fallback: string[]): string[] {
+    const value = table[key]
+    if (value === undefined) return fallback
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+      this.add(`${name} must be an array of strings`)
+      return fallback
+    }
+    if (value.length === 0) {
+      this.add(`${name} must not be empty`)
+      return fallback
+    }
+    return value as string[]
+  }
+}
+
+export function parseConfig(text: string): RepoControlsConfig {
+  let raw: unknown
+  try {
+    raw = Bun.TOML.parse(text)
+  } catch (error) {
+    throw new Error(`${CONFIG_REL} is not valid TOML: ${(error as Error).message}`)
+  }
+  const root = raw as Table
+  // Root carries other tools' tables ([hooks]/[rules]/[repo] from adl hook, [skills] from
+  // adl-extensions, a bare tool-agnostic `version`) — opaque bytes this package never inspects.
+  if (!isTable(root.controls)) throw new Error(`${CONFIG_REL} has no [controls] table — ${INSTALL_HINT}`)
+  const controls = root.controls
+
+  const problems = new Problems()
+  // `compliance` is accepted and ignored here: it is this package's config too, but it
+  // has its own schema and its own strict decoder in `compliance-config.ts`. Listing it
+  // keeps a typo elsewhere in `[controls]` failing loud without this decoder having to
+  // know anything about the compliance schema.
+  problems.unknownKeys(controls, ['branches', 'pre_commit', 'pre_push', 'commit_msg', 'post_commit', 'compliance', 'coverage', 'findings', 'integrity', 'release'], '')
+
+  const branches = problems.table(controls, 'branches', ['protected', 'prefixes'])
+  // `branches` and `pre_push.remote` are REQUIRED: install always seeds them, and
+  // `pre-push` reads their env vars with `${VAR:?}`, which aborts on an empty value —
+  // so "no branch policy" cannot be spelled as an empty list. Everything else is
+  // optional and defaults to off.
+  const preCommit = problems.optionalTable(controls, 'pre_commit', ['static_checks', 'staged_coverage', 'doc_freshness', 'compliance'])
+  const prePush = problems.table(controls, 'pre_push', ['coverage_ratchet', 'findings_ratchet', 'static_checks', 'export_links', 'remote'])
+  // Optional, and every field defaults, so a repository that never writes this
+  // table behaves exactly as before. `pre_push.coverage_ratchet` stays where it
+  // is: that key says WHETHER the gate is armed, this table says WHAT it grades.
+  // WHAT the commit gate protects, on top of the wiring files the package names
+  // itself. Declared rather than packaged because `knip.json` and `biome.json`
+  // are one ecosystem's vocabulary: a package naming them would standardise that
+  // ecosystem, which is the coupling removed from this package on 2026-09-16.
+  //
+  // Absent means only the wiring files are protected. That is deliberately NOT
+  // could-not-run, unlike a tree: the wiring set is always meaningful and always
+  // enforced, so absence shrinks the protected set visibly rather than turning a
+  // gate into a silent pass.
+  const integrity = problems.optionalTable(controls, 'integrity', ['watched'])
+
+  const coverage = problems.optionalTable(controls, 'coverage', [
+    'summary',
+    'produce',
+    'source_roots',
+    'src_test_ratio_globs',
+  ])
+  // Same split as `coverage` above: `pre_push.findings_ratchet` says WHETHER,
+  // this table says WHAT and WHERE. `counters` names no tool: each key is a
+  // repository-chosen counter name, each value the repository's own command
+  // for it — the same shape `pre_push.static_checks` already uses for an
+  // opaque, repo-authored shell command this package never interprets.
+  const findings = problems.optionalTable(controls, 'findings', ['floor', 'counters'])
+  // Every hook gets the same seam. `post_commit` in particular is not
+  // decoration: a producer that defers work from pre-commit has nowhere to
+  // land it without one.
+  const commitMsg = problems.optionalTable(controls, 'commit_msg', ['static_checks'])
+  const postCommit = problems.optionalTable(controls, 'post_commit', ['static_checks'])
+  // Which branch is promoted to which. No default pair: defaulting to
+  // integration -> main would put one repository's branch names back into
+  // this package by the back door.
+  const release = problems.optionalTable(controls, 'release', ['source', 'target', 'merge_strategy', 'pre_bump'])
+  const releaseMergeStrategy = problems.optionalString(release, 'merge_strategy', 'release.merge_strategy', 'squash')
+  if (!Object.hasOwn(MERGE_STRATEGIES, releaseMergeStrategy)) {
+    problems.add(`release.merge_strategy must be one of ${Object.keys(MERGE_STRATEGIES).join(', ')}`)
+  }
+
+  const config: RepoControlsConfig = {
+    branches: {
+      protected: problems.names(branches, 'protected', 'branches.protected', BRANCH_RE),
+      prefixes: problems.names(branches, 'prefixes', 'branches.prefixes', PREFIX_RE),
+    },
+    preCommit: {
+      // The repository declares WHAT runs at commit and WHICH hook it runs in.
+      // Same shape as `pre_push.static_checks`; this package never interprets
+      // the command and names no tool.
+      staticChecks: preCommit.static_checks === undefined ? [] : parseStaticChecks(preCommit.static_checks, problems, 'pre_commit.static_checks'),
+      stagedCoverage: problems.optionalBool(preCommit, 'staged_coverage', 'pre_commit.staged_coverage', false),
+      docFreshness: problems.optionalBool(preCommit, 'doc_freshness', 'pre_commit.doc_freshness', false),
+      compliance: problems.optionalBool(preCommit, 'compliance', 'pre_commit.compliance', false),
+    },
+    prePush: {
+      coverageRatchet: problems.optionalBool(prePush, 'coverage_ratchet', 'pre_push.coverage_ratchet', false),
+      findingsRatchet: problems.optionalBool(prePush, 'findings_ratchet', 'pre_push.findings_ratchet', false),
+      staticChecks: prePush.static_checks === undefined ? [] : parseStaticChecks(prePush.static_checks, problems, 'pre_push.static_checks'),
+      // Untracked paths the HEAD export needs, e.g. a dependency directory.
+      // The hook used to hardcode `node_modules`, which assumed JavaScript in a
+      // package that is language agnostic.
+      exportLinks: parseExportLinks(prePush.export_links, problems),
+      remote: problems.string(prePush, 'remote', 'pre_push.remote', REMOTE_RE),
+    },
+    integrity: { watched: parseWatched(integrity.watched, problems) },
+    coverage: {
+      summary: problems.optionalString(coverage, 'summary', 'coverage.summary', DEFAULT_COVERAGE_SUMMARY),
+      produce: problems.optionalString(coverage, 'produce', 'coverage.produce', ''),
+      sourceRoots: problems.optionalNames(coverage, 'source_roots', 'coverage.source_roots', []),
+      srcTestRatioGlobs: problems.optionalNames(
+        coverage,
+        'src_test_ratio_globs',
+        'coverage.src_test_ratio_globs',
+        [],
+      ),
+    },
+    commitMsg: {
+      staticChecks: commitMsg.static_checks === undefined ? [] : parseStaticChecks(commitMsg.static_checks, problems, 'commit_msg.static_checks'),
+    },
+    release: {
+      source: problems.optionalString(release, 'source', 'release.source', ''),
+      target: problems.optionalString(release, 'target', 'release.target', ''),
+      // The MCP server's PR tool admits only Squash, and that enum is the
+      // standard. A repository deviating declares it here.
+      mergeStrategy: releaseMergeStrategy as MergeStrategy,
+      // Ordered, repo-relative scripts `version-bump.sh` runs from the repo
+      // root before the bump commit — see `parsePreBump`'s own docstring for
+      // what "repository-relative" is checked to mean here; existence on
+      // disk is checked by `version-bump.sh` itself, which is the only place
+      // that knows the repo root at run time.
+      preBump: parsePreBump(release.pre_bump, problems),
+    },
+    postCommit: {
+      staticChecks: postCommit.static_checks === undefined ? [] : parseStaticChecks(postCommit.static_checks, problems, 'post_commit.static_checks'),
+    },
+    findings: {
+      floor: problems.optionalString(findings, 'floor', 'findings.floor', DEFAULT_FINDINGS_FLOOR),
+      counters: findings.counters === undefined ? {} : parseCounters(findings.counters, problems),
+    },
+  }
+  if (problems.list.length > 0) {
+    throw new Error(`${CONFIG_REL} is invalid:\n  - ${problems.list.join('\n  - ')}`)
+  }
+  return config
+}
+
+/**
+ * Repository-relative paths to link into the HEAD export.
+ *
+ * Refuses absolute paths and `..` segments: the target is resolved against the
+ * repository root and the link is created inside a temp directory, so either
+ * would reach outside both.
+ */
+/**
+ * `[controls.integrity].watched` — repository-relative patterns, `*` and `**`.
+ *
+ * Rejected with a named reason rather than dropped: a pattern nobody can match
+ * protects nothing, and a protected-file list that silently shrinks is worse
+ * than one that refuses to load.
+ */
+function parseWatched(value: unknown, problems: Problems): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    problems.add('integrity.watched must be an array of strings')
+    return []
+  }
+  const watched: string[] = []
+  for (const entry of value as string[]) {
+    if (entry === '' || entry.startsWith('/') || entry.split('/').includes('..')) {
+      problems.add(`integrity.watched entry must be a repository-relative path: ${entry}`)
+      continue
+    }
+    watched.push(entry)
+  }
+  return watched
+}
+
+function parseExportLinks(value: unknown, problems: Problems): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    problems.add('pre_push.export_links must be an array of strings')
+    return []
+  }
+  const links: string[] = []
+  for (const entry of value as string[]) {
+    if (entry === '' || entry.startsWith('/') || entry.split('/').includes('..')) {
+      problems.add(`pre_push.export_links entry must be a repository-relative path: ${entry}`)
+      continue
+    }
+    links.push(entry)
+  }
+  return links
+}
+
+/**
+ * `[controls.release].pre_bump` — ordered, repository-relative script paths
+ * `version-bump.sh` runs from the repo root before the bump commit, one
+ * multi-language repo's escape hatch out of the single npm-`package.json`
+ * assumption baked into the rest of `[controls.release]` (e.g.
+ * agent-identities' Go version constant). Absent means no scripts and the
+ * bump commit stays byte-identical to the behaviour before this key existed.
+ *
+ * Only SHAPE is checked here (array of strings, repository-relative, no `..`
+ * escape) — the same two checks `parseWatched`/`parseExportLinks` already
+ * apply to every other repo-relative list this package parses. Whether each
+ * path actually exists on disk is NOT checked here: `parseConfig` takes raw
+ * text with no repository to check against (`monorepo-config-parses.test.ts`
+ * parses arbitrary siblings' text this way) — existence is `version-bump.sh`'s
+ * own job, the one place that both reads this list and knows the repo root.
+ */
+function parsePreBump(value: unknown, problems: Problems): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    problems.add('release.pre_bump must be an array of strings')
+    return []
+  }
+  const scripts: string[] = []
+  for (const entry of value as string[]) {
+    if (entry === '' || entry.startsWith('/') || entry.split('/').includes('..')) {
+      problems.add(`release.pre_bump entry must be a repository-relative path: ${entry}`)
+      continue
+    }
+    scripts.push(entry)
+  }
+  return scripts
+}
+
+function parseStaticChecks(value: unknown, problems: Problems, table: string): StaticCheck[] {
+  if (!Array.isArray(value)) {
+    problems.add(`${table} must be an array`)
+    return []
+  }
+  return value.map((entry: unknown, index) => {
+    const name = `${table}[${index}]`
+    if (!isTable(entry)) {
+      problems.add(`${name} must be a table`)
+      return { label: '', run: '' }
+    }
+    problems.unknownKeys(entry, ['label', 'run'], `${name}.`)
+    const label = typeof entry.label === 'string' ? entry.label : ''
+    const run = typeof entry.run === 'string' ? entry.run : ''
+    if (!LABEL_RE.test(label)) problems.add(`${name}.label must match ${LABEL_RE.source}`)
+    if (run.trim() === '' || /[\t\r\n]/.test(run)) problems.add(`${name}.run must be a non-empty single-line command`)
+    return { label, run }
+  })
+}
+
+/**
+ * `[controls.findings.counters]`: a repository-chosen name -> repository-owned
+ * command map, an inline table rather than `static_checks`' array of tables
+ * because each name must be unique (a TOML table enforces that for free) and
+ * is also the floor file's own key — see `FindingsConfig`'s docstring.
+ */
+function parseCounters(value: unknown, problems: Problems): Record<string, string> {
+  if (!isTable(value)) {
+    problems.add('findings.counters must be a table')
+    return {}
+  }
+  const counters: Record<string, string> = {}
+  for (const [name, raw] of Object.entries(value)) {
+    if (!LABEL_RE.test(name)) {
+      problems.add(`findings.counters key must match ${LABEL_RE.source}: ${name}`)
+      continue
+    }
+    const command = typeof raw === 'string' ? raw : ''
+    if (command.trim() === '' || /[\t\r\n]/.test(command)) {
+      problems.add(`findings.counters.${name} must be a non-empty single-line command`)
+      continue
+    }
+    counters[name] = command
+  }
+  return counters
+}
+
+export function loadConfig(repo: string): RepoControlsConfig {
+  const path = join(repo, CONFIG_REL)
+  if (!existsSync(path)) throw new Error(`${CONFIG_REL} is missing — ${INSTALL_HINT}`)
+  return parseConfig(readFileSync(path, 'utf8'))
+}
+
+/** The environment contract between this CLI and the package-owned hook scripts. */
+export function configEnv(repo: string, config: RepoControlsConfig): Record<string, string> {
+  const env: Record<string, string> = {
+    ADL_REPO_CONTROLS_ROOT: repo,
+    ADL_REPO_CONTROLS_PROTECTED_BRANCHES: config.branches.protected.join('|'),
+    ADL_REPO_CONTROLS_BRANCH_PREFIXES: config.branches.prefixes.join('|'),
+    ADL_REPO_CONTROLS_COVERAGE_RATCHET: config.prePush.coverageRatchet ? '1' : '0',
+    ADL_REPO_CONTROLS_FINDINGS_RATCHET: config.prePush.findingsRatchet ? '1' : '0',
+    ADL_REPO_CONTROLS_EXPORT_LINKS: config.prePush.exportLinks.join('\n'),
+    ADL_REPO_CONTROLS_STATIC_CHECKS: config.prePush.staticChecks.map((check) => `${check.label}\t${check.run}`).join('\n'),
+    ADL_REPO_CONTROLS_REMOTE: config.prePush.remote,
+    // The coverage artifact and the repository's own shape. Empty means "the
+    // bundled script's own default" — a repo that declares nothing keeps the
+    // behaviour it had before this table existed.
+    ADL_REPO_CONTROLS_COVERAGE_SUMMARY: config.coverage.summary,
+    ADL_REPO_CONTROLS_COVERAGE_PRODUCE: config.coverage.produce,
+    ADL_REPO_CONTROLS_COVERAGE_SOURCE_ROOTS: config.coverage.sourceRoots.join('|'),
+    ADL_REPO_CONTROLS_COVERAGE_SRC_TEST_GLOBS: config.coverage.srcTestRatioGlobs.join('|'),
+    // Where the findings ratchet's floor is, and the repo's own named
+    // counter commands — same `name\tcommand` shape as `_STATIC_CHECKS`,
+    // and empty when the repo declared none, so this gate runs nothing.
+    ADL_REPO_CONTROLS_FINDINGS_FLOOR: config.findings.floor,
+    ADL_REPO_CONTROLS_FINDINGS_COUNTERS: Object.entries(config.findings.counters)
+      .map(([name, command]) => `${name}\t${command}`)
+      .join('\n'),
+  }
+  // enact-m5's pre-commit honours ADL_SKIP_STAGED_COVERAGE=1; disabled config sets it.
+  if (!config.preCommit.stagedCoverage) env.ADL_SKIP_STAGED_COVERAGE = '1'
+  return env
+}