@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,694 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadComplianceConfig } from './compliance-config.ts'
+import { configEnv, type FindingsConfig, loadConfig, parseConfig, type StaticCheck } from './config.ts'
+import { BUNDLE_ROOT, COMPLIANCE_ROOT, HOOK_NAMES, type HookName } from './constants.ts'
+import { docFreshnessProblems, inScope } from './doc-freshness.ts'
+import { azureDevOpsPromotionGovernanceChecks, type Check, doctor, type DoctorReport } from './doctor.ts'
+import { commitRequiredProblems, integrityProblems } from './integrity.ts'
+import { type CoverageSummary, coverageRegressions, readSummary } from './coverage-ratchet.ts'
+import { type Floor, findingsProblems, parseCounterOutput, parseFloor } from './findings-ratchet.ts'
+import { bashProblem, capture, childEnv, type Env, resolveRepo, which } from './runtime.ts'
+import { postCheckoutWorktreeGuardStep } from './worktree-guard.ts'
+
+export const isHookName = (name: string): name is HookName => (HOOK_NAMES as readonly string[]).includes(name)
+
+/** Bundled enact-m5 tools runnable against a repository via `adl-repo-controls run`. */
+export const TOOLS = {
+  /** The bundled Python compliance engine — a separate runtime (`uv`), no bundled script of ours. */
+  compliance: { runtime: 'uv' },
+} as const
+export type ToolName = keyof typeof TOOLS
+export const isToolName = (name: string): name is ToolName => Object.hasOwn(TOOLS, name)
+
+export interface RunContext {
+  env: Env
+  cwd: string
+  err: (line: string) => void
+  /** Progress the hook wants seen. Defaults to stderr's sink when not supplied. */
+  out?: (line: string) => void
+  /**
+   * What the bundled script's stdin is wired to. `inherit` is the default and
+   * the production answer: git pipes the pushed refs into the hook process, and
+   * `hooks/pre-push` consumes them with `push_updates="$(cat)"`.
+   *
+   * That `cat` is why this is configurable at all. A caller that invokes the
+   * hook IN PROCESS -- the test suite -- hands the child whatever stdin it
+   * happens to own. On a developer machine that stream is already at EOF, so
+   * `cat` returns instantly and the hook looks fine. On the pipeline agent it
+   * stays open, `cat` blocks forever, and the test dies on its timeout with
+   * nothing to show for it. Raising the timeout only changes how long it takes
+   * to fail; the fix is to stop relying on ambient stdin.
+   */
+  stdin?: 'inherit' | 'ignore'
+}
+
+/** Runs one bundled script with the repository's config exported; returns its exit status. */
+function runBundled(runtime: 'bash' | 'bun', script: string, args: string[], repo: string, workdir: string, context: RunContext): number {
+  const problem = bashProblem(context.env)
+  if (problem) throw new Error(problem)
+  const env = { ...context.env, ...configEnv(repo, loadConfig(repo)) }
+  const executable = which(runtime, context.env)
+  if (!executable) throw new Error(`${runtime} not found on PATH`)
+  const proc = Bun.spawnSync([executable, join(BUNDLE_ROOT, script), ...args], {
+    cwd: workdir,
+    env: childEnv(env),
+    stdin: context.stdin ?? 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  })
+  return proc.exitCode ?? 1
+}
+
+/**
+ * Runs `adl-compliance` (a `uv`-managed Python project bundled at `COMPLIANCE_ROOT`)
+ * against the repository. `--root` is always injected first so a user-supplied `--root`
+ * after `--` overrides it (argparse's last-flag-wins); `--only` is injected from
+ * `[compliance].enabled` whenever it is non-empty, same override rule applies. Unlike
+ * `runBundled`, this never reads `[controls]`/`configEnv()` — that env means nothing to
+ * the Python side.
+ */
+function runUv(args: string[], repo: string, context: RunContext): number {
+  const executable = which('uv', context.env)
+  if (!executable) throw new Error('uv not found on PATH — required by `run compliance` (see README)')
+  const config = loadComplianceConfig(repo)
+  // Everything the repository declares about its own shape, passed through. Before
+  // this, `[controls.compliance].trees` was parsed, validated and 100%-covered by
+  // tests — and reached nothing, so 29 of 100 rows errored against this repo alone
+  // because `<compliance>` still resolved to the packaged default. `inputs` is the
+  // same shape for a check's named files, which had no override at all.
+  const injected = [
+    ...(config.enabled.length > 0 ? ['--only', config.enabled.join(',')] : []),
+    ...Object.entries(config.trees).flatMap(([name, path]) => ['--tree', `${name}=${path}`]),
+    ...Object.entries(config.inputs).flatMap(([name, path]) => ['--input', `${name}=${path}`]),
+    ...Object.entries(config.declarations).flatMap(([name, value]) => ['--declare', `${name}=${value}`]),
+  ]
+  const proc = Bun.spawnSync(
+    [executable, 'run', '--project', COMPLIANCE_ROOT, 'adl-compliance', '--root', repo, ...injected, ...args],
+    { cwd: repo, env: childEnv(context.env), stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' },
+  )
+  return proc.exitCode ?? 1
+}
+
+export interface StagedIndexSnapshot {
+  /** Root containing exactly the files and bytes currently stored in Git's index. */
+  root: string
+  /** Newline-delimited repository-relative paths in the complete staged snapshot. */
+  files: string
+}
+
+/**
+ * Materialize the complete candidate commit and remove it after `use` returns.
+ *
+ * Compliance at pre-commit must grade the index, not the working tree. A changed-
+ * files list is insufficient because exact-zero gates have repository-wide
+ * invariants, while pointing the engine at the live checkout lets unstaged bytes
+ * change the verdict. `git checkout-index` is the one operation that gives both
+ * the staged bytes and staged path topology, including additions, deletions and
+ * renames. The file list comes from the same index and is declared exhaustive to
+ * the engine, so the snapshot never needs its own `.git` directory.
+ */
+export function withStagedIndexSnapshot<T>(
+  repo: string,
+  env: Env,
+  use: (snapshot: StagedIndexSnapshot) => T,
+): T {
+  const container = mkdtempSync(join(tmpdir(), 'adl-compliance-index-'))
+  const root = join(container, 'tree')
+  const files = join(container, 'files.list')
+  mkdirSync(root)
+
+  try {
+    const listed = capture(['git', 'ls-files', '--cached', '-z'], repo, env)
+    if (listed.code !== 0) {
+      throw new Error(`git ls-files --cached failed: ${listed.stderr.trim()}`)
+    }
+    const paths = listed.stdout.split('\0').filter(Boolean)
+    if (paths.length === 0) {
+      throw new Error('the staged index contains no files; an empty snapshot cannot pass compliance')
+    }
+    writeFileSync(files, `${paths.join('\n')}\n`)
+
+    const exported = capture(
+      ['git', 'checkout-index', '--all', '--force', `--prefix=${root}/`],
+      repo,
+      { ...env, GIT_LFS_SKIP_SMUDGE: '1' },
+    )
+    if (exported.code !== 0) {
+      throw new Error(`git checkout-index failed: ${exported.stderr.trim()}`)
+    }
+    return use({ root, files })
+  } finally {
+    rmSync(container, { recursive: true, force: true })
+  }
+}
+
+/** Whether the candidate commit itself arms compliance. */
+export function stagedComplianceEnabled(repo: string, env: Env): boolean {
+  const shown = capture(['git', 'show', ':adl-config.toml'], repo, env)
+  if (shown.code !== 0) {
+    if (loadConfig(repo).preCommit.compliance) {
+      throw new Error(
+        'compliance is enabled in the working tree but adl-config.toml is absent from the staged index',
+      )
+    }
+    return false
+  }
+  return parseConfig(shown.stdout).preCommit.compliance
+}
+
+/**
+ * `last_update` freshness over the STAGED INDEX, in this package rather than in the
+ * bundled script: this is the package's own code, not a copy of a consumer's.
+ *
+ * Blobs are read with `git show :<path>`, the index version, for the same reason the
+ * bundled biome step snapshots the index with `git checkout-index`: the rule grades
+ * what is being committed, not what happens to be in the work tree.
+ */
+function stagedDocFreshness(repo: string, now: Date, context: RunContext): number {
+  const listed = capture(['git', 'diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z'], repo, context.env)
+  if (listed.code !== 0) throw new Error(`git diff --cached failed: ${listed.stderr.trim()}`)
+
+  const docs = listed.stdout
+    .split('\0')
+    .filter((path) => path !== '' && inScope(path))
+    .map((path) => ({ path, text: capture(['git', 'show', `:${path}`], repo, context.env).stdout }))
+
+  const problems = docFreshnessProblems(docs, now)
+  if (problems.length === 0) return 0
+
+  context.err('pre-commit: FAIL — staged documentation is not stamped with a current last_update.')
+  for (const problem of problems) context.err(`    - ${problem.path}: ${problem.message}`)
+  context.err(`  ${problems[0]?.hint}`)
+  return 1
+}
+
+/**
+ * Runs each declared counter and grades its paths against the floor.
+ *
+ * Lives in `src/` because it is mechanism: this package decides WHEN a gate
+ * runs and grades the result. `scripts/` holds only what a hook execs.
+ *
+ * A counter that exits non-zero has not run. That is could-not-run and it
+ * blocks, because the alternative -- treating a broken counter as "no findings"
+ * -- is the empty-scope false pass this estate keeps paying for.
+ */
+export function findingsRatchetReport(
+  findings: FindingsConfig,
+  readFloor: () => string,
+  runCounter: (command: string) => { code: number; stdout: string; stderr: string },
+  err: (line: string) => void,
+): number {
+  const counters = Object.entries(findings.counters)
+
+  if (counters.length === 0) {
+    err('pre-push: FAIL — pre_push.findings_ratchet is on but [controls.findings.counters] is empty.')
+    err('  A ratchet with nothing to measure grades nothing and would pass every push.')
+    return 1
+  }
+
+  let floor: Floor
+  try {
+    floor = parseFloor(readFloor())
+  } catch (error) {
+    err(`pre-push: FAIL — cannot read the findings floor ${findings.floor}:`)
+    err(`    ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+
+  let failed = false
+  for (const [name, command] of counters) {
+    const run = runCounter(command)
+    if (run.code !== 0) {
+      err(`pre-push: FAIL — findings counter '${name}' did not run (exit ${run.code}).`)
+      err(`    ${command}`)
+      if (run.stderr.trim() !== '') err(`    ${run.stderr.trim().split('\n').slice(-3).join('\n    ')}`)
+      err('  A counter that cannot run is could-not-run, never zero findings.')
+      failed = true
+      continue
+    }
+    for (const problem of findingsProblems(name, parseCounterOutput(name, run.stdout), floor)) {
+      if (problem.fails) {
+        failed = true
+        err(`pre-push: FAIL — ${problem.message}`)
+      } else {
+        err(`pre-push: note — ${problem.message}`)
+      }
+    }
+  }
+  if (failed) {
+    err(`  The floor is ${findings.floor}. A listed file is amnestied entirely;`)
+    err('  a file not listed must be clean. Adding a line declares new debt.')
+    return 1
+  }
+  return 0
+}
+
+/**
+ * Staged-coverage at commit: the repository's declared command, not ours.
+ *
+ * The bundled `pre-commit` used to shell into
+ * `$HOOK_REPO_ROOT/workflows/scripts/coverage/command.ts`, which is a path INTO
+ * this package running this package's copy of the consumer's code. `workflows/`
+ * is the tree the repository declares and owns; `.workflows/` is what this
+ * package deploys as owner of the git hooks. The package reaching into the
+ * former is the coupling being removed, and this is the seam that removes it.
+ *
+ * `[controls.coverage].produce` has been parsed, typed and documented since
+ * before this function existed, and read by nothing. The division is the same
+ * one `pre_push.static_checks` and `findings.counters` already draw: the repo
+ * says HOW to measure, the package decides WHEN and grades the exit status. No
+ * tool name appears here.
+ *
+ * Absence is deliberately NOT a skip. A step that measures nothing and reports
+ * success is the empty-scope false pass this estate keeps paying for, so with
+ * neither a declaration nor a fallback this is could-not-run.
+ */
+export function stagedCoverageStep(
+  coverage: { produce: string },
+  runCommand: (command: string) => { code: number; stdout: string; stderr: string },
+  fallback: (() => number) | null,
+  err: (line: string) => void,
+): number {
+  const declared = coverage.produce.trim()
+  if (declared === '') {
+    if (fallback !== null) return fallback()
+    err('pre-commit: FAIL — staged coverage is on but [controls.coverage].produce declares no command,')
+    err('  and no bundled fallback is available. A step that measures nothing is not a pass.')
+    return 1
+  }
+  const run = runCommand(declared)
+  if (run.code !== 0) {
+    err(`pre-commit: FAIL — coverage.produce exited ${run.code}: ${declared}`)
+    if (run.stderr.trim() !== '') err(`    ${run.stderr.trim().split('\n').slice(-3).join('\n    ')}`)
+  }
+  return run.code
+}
+
+/**
+ * The coverage ratchet at push: did anything get worse between the baseline and
+ * what is being pushed.
+ *
+ * This is the whole of what the package does about coverage. Producing the
+ * summary is the repository's (`[controls.coverage].produce`); this reads the
+ * file the repository declared (`[controls.coverage].summary`) and grades it.
+ *
+ * `readBaseline` returning `null` means there is no baseline — a new branch, or
+ * the file is new — and that passes: nothing can have regressed against a floor
+ * that does not exist. But once a baseline EXISTS, a current summary that
+ * cannot be read blocks. "I could not measure" must never resolve to "nothing
+ * got worse"; that is the empty-baseline false pass in the other direction.
+ */
+export function coverageRatchetStep(
+  summaryPath: string,
+  readBaseline: () => string | null,
+  readCurrent: () => string,
+  err: (line: string) => void,
+): number {
+  const baselineText = readBaseline()
+  if (baselineText === null) return 0
+
+  let baseline: CoverageSummary
+  let current: CoverageSummary
+  try {
+    baseline = readSummary(() => baselineText)
+  } catch (error) {
+    err(`pre-push: FAIL — the BASELINE ${summaryPath} is unreadable: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+  try {
+    current = readSummary(readCurrent)
+  } catch (error) {
+    err(`pre-push: FAIL — ${summaryPath} is unreadable, and a baseline exists: ${error instanceof Error ? error.message : String(error)}`)
+    err('  A summary that cannot be read is not a summary with no regressions.')
+    return 1
+  }
+
+  const regressions = coverageRegressions(baseline, current)
+  if (regressions.length === 0) return 0
+  err(`pre-push: FAIL — coverage regressed in ${summaryPath}:`)
+  for (const line of regressions) err(`    - ${line}`)
+  return 1
+}
+
+/**
+ * The repository's declared commands for one hook.
+ *
+ * Every hook name has a seam, `post-commit` included. That one looks decorative
+ * and is not: a producer that DEFERS work from pre-commit -- enact-m5's coverage
+ * summary publish lock marks itself `awaiting-commit` and releases after the
+ * commit lands -- has nowhere to land it otherwise. A lock that is never
+ * released does not fail loudly; it fails on somebody's next commit.
+ */
+export function declaredChecksFor(
+  name: HookName,
+  config: {
+    preCommit: { staticChecks: StaticCheck[] }
+    prePush: { staticChecks: StaticCheck[] }
+    commitMsg: { staticChecks: StaticCheck[] }
+    postCommit: { staticChecks: StaticCheck[] }
+  },
+): StaticCheck[] {
+  switch (name) {
+    case 'pre-commit':
+      return config.preCommit.staticChecks
+    case 'pre-push':
+      return config.prePush.staticChecks
+    case 'commit-msg':
+      return config.commitMsg.staticChecks
+    case 'post-commit':
+      return config.postCommit.staticChecks
+    // `post-checkout` is a fixed safety gate (the worktree-count backstop —
+    // see ./worktree-guard.ts), never a repository-customizable pipeline
+    // step: it has no `[controls.post_checkout]` config table and no seam
+    // here, on purpose — see tests/declared-hook-scripts.test.ts.
+    case 'post-checkout':
+      return []
+  }
+}
+
+/**
+ * The repository's declared pre-commit checks.
+ *
+ * This package decides WHEN a check runs and grades its exit status; the
+ * repository decides WHAT runs and which hook it runs in. Identical division to
+ * `pre_push.static_checks` and `findings.counters`, and no tool is named here --
+ * the package is language agnostic, so a Rust repository declaring `cargo
+ * clippy` and a TypeScript one declaring a linter are the same case to it.
+ *
+ * Every check runs even after one fails. One report per commit beats one
+ * failure per commit: a developer who must re-run to discover the next problem
+ * re-runs once per problem.
+ */
+export function preCommitChecks(
+  checks: readonly { label: string; run: string }[],
+  runCommand: (command: string) => { code: number; stdout: string; stderr: string },
+  err: (line: string) => void,
+): number {
+  let failed = 0
+  for (const { label, run } of checks) {
+    const result = runCommand(run)
+    if (result.code === 0) continue
+    failed = 1
+    err(`pre-commit: FAIL — ${label} exited ${result.code}: ${run}`)
+    const detail = result.stderr.trim() || result.stdout.trim()
+    if (detail !== '') err(`    ${detail.split('\n').slice(-5).join('\n    ')}`)
+  }
+  return failed
+}
+
+/**
+ * The armed compliance rows, through an injected runner.
+ *
+ * Injectable for the same reason the other three steps are: the alternative is
+ * spawning `uv` and grading the real engine inside a unit test, which takes
+ * minutes. A gate that can only be tested by running everything it gates is a
+ * gate nobody tests.
+ */
+export function complianceStep(run: () => number): number {
+  return run()
+}
+
+/**
+ * Read paths excluded from this commit, including untracked paths that have no
+ * index entry yet.
+ *
+ * `git status --porcelain=v1 -z` emits literal paths separated by NUL, so a
+ * filename's newline or non-ASCII bytes never become C-quoted syntax. Rename
+ * and copy records carry a second, origin path; consume it before reading the
+ * next status record.
+ */
+function dirtyPaths(porcelain: string): string[] {
+  const paths: string[] = []
+  const records = porcelain.split('\0')
+  for (let index = 0; index < records.length; index++) {
+    const record = records[index] as string
+    if (record.length < 4 || record[2] !== ' ') continue
+    const staged = record[0] as string
+    const worktree = record[1] as string
+    const hasOrigin = staged === 'R' || staged === 'C' || worktree === 'R' || worktree === 'C'
+    const origin = hasOrigin ? records[++index] : undefined
+    // An untracked path has no index entry, so it is necessarily omitted from
+    // this commit. Keep it: centrally managed dot paths must be staged rather
+    // than silently left behind.
+    if (staged === '?' && worktree === '?') {
+      paths.push(record.slice(3))
+      continue
+    }
+    if (worktree === ' ') continue
+    paths.push(record.slice(3))
+    // A worktree rename changes both paths. Keep the origin too, otherwise
+    // moving a protected path to an ordinary name would evade this half of the
+    // integrity check.
+    if (origin !== undefined && origin !== '') paths.push(origin)
+  }
+  return paths
+}
+
+/** Refuses a commit while a protected worktree edit is excluded from its index. */
+export function integrityStep(
+  porcelain: string,
+  watched: readonly string[],
+  err: (line: string) => void,
+): number {
+  const paths = dirtyPaths(porcelain)
+  const problems = [...integrityProblems(paths, watched), ...commitRequiredProblems(paths, watched)]
+  if (problems.length === 0) return 0
+  for (const line of problems) err(line)
+  return 1
+}
+
+/**
+ * The final-index gate plus the dirty-but-excluded check. The index reader is
+ * separate from status because `git diff --cached --no-renames -z` is the
+ * authoritative final path set: crossing-boundary renames report both sides.
+ */
+export function integrityGate(
+  readStatus: () => { code: number; stdout: string },
+  readFinalStaged: () => { code: number; stdout: string },
+  watched: readonly string[],
+  err: (line: string) => void,
+): number {
+  const status = readStatus()
+  if (status.code !== 0) {
+    err('pre-commit: FAIL — `git status` could not be read, so gate-file integrity is unknown.')
+    return 1
+  }
+  const staged = readFinalStaged()
+  if (staged.code !== 0) {
+    err('pre-commit: FAIL — `git diff --cached` could not be read, so final-index control integrity is unknown.')
+    return 1
+  }
+  const finalPaths = staged.stdout.split('\0').filter((path) => path !== '')
+  const dirty = dirtyPaths(status.stdout)
+  const problems = [
+    ...integrityProblems([...finalPaths, ...dirty], watched),
+    ...commitRequiredProblems(dirty, watched),
+  ]
+  if (problems.length === 0) return 0
+  for (const line of problems) err(line)
+  return 1
+}
+
+/**
+ * Read-only pre-commit gate. `doctor` proves the local hook surface is armed;
+ * repair is an explicit `install` operation, never an implicit commit side
+ * effect. As of 2026-09-28 (Tarun) this runs `doctor` with the Azure DevOps
+ * promotion-governance checks EXCLUDED (`includeAzureDevOpsGovernance: false`
+ * — see `runHook`'s `pre-commit` wiring below): those checks need network
+ * access and a minted Azure DevOps token, which a `git commit` must never
+ * require. They still run — fail-closed, by name — in the `pre-push` gate via
+ * `azureDevOpsPromotionGovernanceGate` below. A bare `adl-repo-controls
+ * doctor` run (not through a hook) keeps reporting everything.
+ */
+export function doctorGate(readDoctor: () => DoctorReport, err: (line: string) => void): number {
+  const report = readDoctor()
+  if (report.ok) return 0
+  err('pre-commit: FAIL — adl-repo-controls doctor found an unarmed control:')
+  for (const check of report.checks) {
+    if (check.status === 'fail') err(`  ${check.id}  ${check.message}`)
+  }
+  err('  Fix the named control, then rerun: adl-repo-controls doctor --repo . --json')
+  return 1
+}
+
+/**
+ * pre-push gate for the Azure DevOps promotion-governance checks alone
+ * (Tarun, 2026-09-28): these need network access and a minted Azure DevOps
+ * token, so they moved out of pre-commit and into pre-push, where a network
+ * requirement is already expected. Same fail-closed contract as `doctorGate`:
+ * unreadable evidence blocks the push, by name — never a warning, never a
+ * silent pass. `readChecks` reading `[controls.release]` itself (via
+ * `loadConfig`) can throw on a malformed config; that is reported the same
+ * way as an unarmed check rather than crashing the hook process.
+ */
+export function azureDevOpsPromotionGovernanceGate(readChecks: () => Check[], err: (line: string) => void): number {
+  let checks: Check[]
+  try {
+    checks = readChecks()
+  } catch (error) {
+    err('pre-push: FAIL — could not evaluate Azure DevOps promotion governance:')
+    err(`  ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+  const failed = checks.filter((check) => check.status === 'fail')
+  if (failed.length === 0) return 0
+  err('pre-push: FAIL — adl-repo-controls doctor found an unarmed Azure DevOps promotion control:')
+  for (const check of failed) err(`  ${check.id}  ${check.message}`)
+  err('  Fix the named control, then rerun: adl-repo-controls doctor --repo . --json')
+  return 1
+}
+
+/** Real I/O around `findingsRatchetReport`. */
+function runFindingsRatchet(repo: string, context: RunContext): number {
+  const config = loadConfig(repo)
+  return findingsRatchetReport(
+    config.findings,
+    () => readFileSync(join(repo, config.findings.floor), 'utf8'),
+    (command) => capture(['bash', '-c', command], repo, context.env),
+    context.err,
+  )
+}
+
+/** `adl-repo-controls hook <name>` — invoked by the committed stubs, from the work tree root. */
+export function runHook(name: HookName, args: string[], context: RunContext): number {
+  const top = capture(['git', 'rev-parse', '--show-toplevel'], context.cwd, context.env)
+  if (top.code !== 0) throw new Error(`not inside a git work tree: ${context.cwd}`)
+  const repo = top.stdout.trim()
+  // The worktree-count backstop (STATUS.md item 2, adl-m3-items). Git has no
+  // pre-worktree hook, so this cannot stop `git worktree add` from creating
+  // the checkout — it runs after, in the NEW worktree, and actively removes it
+  // when the repository is over the limit. See ./worktree-guard.ts for why
+  // this fires here and not just on the shell/agent-tool side
+  // (packages/agent-hooks's `git.worktree` denies agent-driven worktree
+  // creation outright; this is the backstop for a human, or any agent path
+  // that hook engine cannot see).
+  if (name === 'post-checkout') {
+    const code = postCheckoutWorktreeGuardStep(repo, args, context)
+    if (code !== 0) return code
+  }
+  // The atomic index gate comes first. A modified managed hook can make doctor
+  // fail too, but integrity must name every protected path rather than masking
+  // it behind that secondary symptom.
+  if (name === 'pre-commit') {
+    const code = integrityGate(
+      () => capture(['git', 'status', '--porcelain=v1', '-z', '--untracked-files=all'], repo, context.env),
+      () => capture(['git', 'diff', '--cached', '--name-only', '--no-renames', '-z'], repo, context.env),
+      loadConfig(repo).integrity.watched,
+      context.err,
+    )
+    if (code !== 0) return code
+  }
+  // After path integrity is clean, prove the local hook surface is armed.
+  // This path never writes or stages files. The Azure DevOps promotion-
+  // governance checks are deliberately excluded here (2026-09-28, Tarun):
+  // they need network access and a minted token, which a commit must never
+  // require — see azureDevOpsPromotionGovernanceGate below, run at pre-push.
+  if (name === 'pre-commit') {
+    const code = doctorGate(() => doctor(repo, context.env, { includeAzureDevOpsGovernance: false }), context.err)
+    if (code !== 0) return code
+  }
+  if (name === 'pre-commit' && loadConfig(repo).preCommit.docFreshness) {
+    const code = stagedDocFreshness(repo, new Date(), context)
+    if (code !== 0) return code
+  }
+  // The armed compliance gates, before the bundled script. Until this existed
+  // `[controls.compliance].enabled` armed nothing that ever ran: no bundled hook
+  // mentions compliance and `runHook` never reached `runUv`, so a gate was
+  // "enabled" and dormant. Off by default -- a repository opts in with
+  // `pre_commit.compliance = true`, the same way it opts into every other step.
+  if (name === 'pre-commit' && stagedComplianceEnabled(repo, context.env)) {
+    const code = withStagedIndexSnapshot(repo, context.env, (snapshot) => {
+      // Activation is itself read from the candidate commit. An unstaged config
+      // edit cannot turn a staged gate off (or on), and a commit introducing the
+      // gate proves it is armed before it lands.
+      return complianceStep(() =>
+        runUv(['--files', snapshot.files, '--exhaustive'], snapshot.root, context),
+      )
+    })
+    if (code !== 0) return code
+  }
+  // Staged coverage, through the repository's declared command. Was a hardcoded
+  // shell-out inside the bundled pre-commit into this package's copy of the
+  // consumer's coverage code; see `stagedCoverageStep`.
+  if (name === 'pre-commit' && loadConfig(repo).preCommit.stagedCoverage) {
+    const config = loadConfig(repo)
+    const code = stagedCoverageStep(
+      config.coverage,
+      (command) => capture(['bash', '-c', command], repo, context.env),
+      // No fallback. The bundled coverage mechanism is gone, so a repository
+      // that arms staged coverage without declaring `produce` is could-not-run,
+      // which is the honest answer rather than a step that measures nothing.
+      null,
+      context.err,
+    )
+    if (code !== 0) return code
+  }
+  // The Azure DevOps promotion-governance checks, moved here from pre-commit
+  // (2026-09-28, Tarun): network access and a minted token are already
+  // expected at push time, unlike at commit time. `azureDevOpsPromotionGovernanceChecks`
+  // itself returns `[]` (an unconditional pass) when the repository declares
+  // no `[controls.release]` at all, so this runs on every pre-push rather than
+  // behind its own config flag.
+  if (name === 'pre-push') {
+    const code = azureDevOpsPromotionGovernanceGate(
+      () => azureDevOpsPromotionGovernanceChecks(repo, context.env),
+      context.err,
+    )
+    if (code !== 0) return code
+  }
+  // The coverage ratchet at push. Was `command.ts check-push` inside the bundled
+  // pre-push, running the package's copy of the consumer's coverage code.
+  if (name === 'pre-push' && loadConfig(repo).prePush.coverageRatchet) {
+    const config = loadConfig(repo)
+    const rel = config.coverage.summary
+    const at = (ref: string) => {
+      const shown = capture(['git', 'show', `${ref}:${rel}`], repo, context.env)
+      return shown.code === 0 ? shown.stdout : null
+    }
+    const code = coverageRatchetStep(
+      rel,
+      () => at('HEAD~1'),
+      () => at('HEAD') ?? readFileSync(join(repo, rel), 'utf8'),
+      context.err,
+    )
+    if (code !== 0) return code
+  }
+  // The findings ratchet, before the bundled script, same shape as compliance
+  // above. `[controls.findings]` was parsed, defaulted, exported into every
+  // child process, documented and doctored -- and read by nothing. Opt-in via
+  // `pre_push.findings_ratchet`, off by default.
+  if (name === 'pre-push' && loadConfig(repo).prePush.findingsRatchet) {
+    const code = runFindingsRatchet(repo, context)
+    if (code !== 0) return code
+  }
+  // The package's standard bash: the shared policy every repository gets.
+  const standard = runBundled('bash', `hooks/${name}`, args, repo, context.cwd, context)
+  if (standard !== 0) return standard
+
+  // pre-push owns its declared static checks inside the bundled script: it
+  // exports immutable HEAD, runs them there, and caches the pass by tree OID.
+  // Running them again here would grade the dirty checkout a second time.
+  if (name === 'pre-push') return 0
+
+  // Then the repository's own script, on top (owner: "standard bash + script
+  // calling on top"). Declared per hook, run from the repo root, never named by
+  // this package. Absent means nothing runs -- there is no bundled default for
+  // a repository's own policy.
+  return preCommitChecks(
+    declaredChecksFor(name, loadConfig(repo)),
+    (command) => capture(['bash', '-c', command], repo, context.env),
+    context.err,
+  )
+}
+
+// `_tool` is unread on purpose. `compliance` is the only tool left, and it is a
+// separate runtime (`uv`) rather than a bundled script of ours -- everything else
+// became a CLI command or a repository-declared check. Dispatching on the name
+// would be a branch no test could reach, but the parameter stays because it is
+// what the CLI parsed and what a second runtime would key off.
+export function runTool(_tool: ToolName, repoArg: string, args: string[], context: RunContext): number {
+  const repo = resolveRepo(repoArg)
+  return runUv(args, repo, context)
+}