@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.29 → 0.1.32

package/packages/repo-controls/src/coverage-ratchet.ts

@@ -105,10 +105,9 @@ export function readSummary(read: () => string): CoverageSummary {
  *
  * Two asymmetries remain deliberate:
  *
- *   a file with NO baseline is not graded — new code cannot exceed a count it
- *   never had, so enrolling a file is never blocked by this gate.
+ *   a file with NO baseline is not graded, but `newlyBaselined` reports it so the enrolment is never silent.
  *
- *   a file that DISAPPEARS is not graded — there is nothing left to be untested.
+ *   a file that DISAPPEARS is not graded when it is gone from disk too; one still on disk fails.
  *
  * `srcTestRatio` is the exception: if the baseline reported one and the current
  * summary does not, that is a measurement that stopped happening, and silence
@@ -121,9 +120,18 @@ export function readSummary(read: () => string): CoverageSummary {
  * uncovered line and flags every time, where a percentage could absorb it in
  * rounding.
  */
-export function coverageRegressions(baseline: CoverageSummary, current: CoverageSummary): string[] {
+export function coverageRegressions(
+  baseline: CoverageSummary,
+  current: CoverageSummary,
+  existsOnDisk: (path: string) => boolean = () => false,
+): string[] {
   const errors: string[] = []
 
+  for (const [path, prior] of Object.entries(baseline)) {
+    if (RESERVED.has(path) || !isFileSummary(prior) || path in current) continue
+    if (existsOnDisk(path)) errors.push(`${path}: dropped from the coverage summary but still exists on disk`)
+  }
+
   for (const [path, entry] of Object.entries(current)) {
     if (RESERVED.has(path) || !isFileSummary(entry)) continue
     const prior = baseline[path]
@@ -151,3 +159,10 @@ export function coverageRegressions(baseline: CoverageSummary, current: Coverage
   }
   return errors
 }
+
+/** Files in `current` that have no baseline entry: they are baselined by this push, and said so. */
+export function newlyBaselined(baseline: CoverageSummary, current: CoverageSummary): string[] {
+  return Object.entries(current)
+    .filter(([path, entry]) => !RESERVED.has(path) && isFileSummary(entry) && !isFileSummary(baseline[path]))
+    .map(([path]) => path)
+}

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

@@ -59,8 +59,8 @@ const errorText = (error: unknown): string => (error as Error).message
 /**
  * The declared Azure DevOps promotion-governance checks alone: the
  * configured remote parsed, then the target branch's remote policies read
- * over the network with a minted token. Returns `[]` when the repository
- * declares no `[controls.release]` at all — there is nothing to prove.
+ * over the network with a minted token. Returns `[]` only for an explicit
+ * `release = false`; an absent `[controls.release]` is a failed check.
  *
  * Split out of `doctor()` (Tarun, 2026-09-28) so the pre-push gate can run
  * exactly these checks on their own, without re-running (or skipping) every
@@ -72,7 +72,16 @@ export function azureDevOpsPromotionGovernanceChecks(
   readAzureDevOpsPolicyEvidence?: AzureDevOpsPolicyReader,
 ): Check[] {
   const config = loadConfig(repo)
-  if (!config.release.source && !config.release.target) return []
+  if (config.release.optedOut) return []
+  if (!config.release.source && !config.release.target) {
+    return [
+      {
+        id: 'release-declaration',
+        status: 'fail',
+        message: '[controls.release] is not declared — declare [controls.release] source/target, or release = false to opt out',
+      },
+    ]
+  }
   const remote = capture(['git', 'remote', 'get-url', config.prePush.remote], repo, env)
   if (remote.code !== 0) {
     return [
@@ -150,51 +159,31 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
         ? '[controls.integrity].watched is empty — this repository\'s own gate-defining files (tsconfig, lint config, coverage baselines, CI pipeline) are not protected by the pre-commit integrity gate; declare them under [controls.integrity].watched'
         : null,
       `[controls.integrity].watched declares ${config.integrity.watched.length} pattern(s)`,
-      'warn',
     )
-    // The path the pre-push ratchet grades, not a default: a repository that
-    // declares `[controls.coverage].summary` elsewhere was probed at the wrong
-    // file and passed with its real summary missing. The gate has a safety
-    // gate: with no summary on either side of the index, the step is a no-op
-    // (see hook.ts), so this is informational rather than blocking.
+    // Armed gates fail when their input is missing; an explicit false in adl-config.toml switches a gate off.
     const coverageSummaryExists = existsSync(join(repo, config.coverage.summary))
     add(
       'coverage-summary',
       config.prePush.coverageRatchet && !coverageSummaryExists
-        ? `pre_push.coverage_ratchet is enabled but ${config.coverage.summary} does not exist — the gate is a no-op until a baseline lands; commit one or set pre_push.coverage_ratchet = false`
+        ? `pre_push.coverage_ratchet is enabled but ${config.coverage.summary} does not exist — every push fails until a baseline lands; commit one or set pre_push.coverage_ratchet = false`
         : null,
       `${config.coverage.summary} is present or the ratchet is disabled`,
-      'warn',
     )
-    // Same shape: `coverage_produce` defaults OFF, but armed with no declared
-    // `[controls.coverage].produce_push` it is NOT a no-op — the push gate
-    // fails loud (a step that measures nothing is not a pass), so doctor names
-    // the misconfiguration before the first push does.
     add(
       'coverage-produce',
       config.prePush.coverageProduce && config.coverage.producePush.trim() === ''
         ? 'pre_push.coverage_produce is enabled but [controls.coverage].produce_push declares no command — the push gate fails every push until one is declared; add produce_push or set pre_push.coverage_produce = false'
         : null,
       'pre_push.coverage_produce is disabled or [controls.coverage].produce_push is declared',
-      'warn',
     )
-    // Same shape: `findings_ratchet` defaults ON but is a no-op when the floor
-    // file is absent. A repo with no lint tooling at all is never asked for a
-    // floor it has no use for.
     const findingsFloorExists = existsSync(join(repo, config.findings.floor))
     add(
       'findings-floor',
       config.prePush.findingsRatchet && !findingsFloorExists
-        ? `pre_push.findings_ratchet is enabled but ${config.findings.floor} does not exist — the gate is a no-op until a floor lands; commit one or set pre_push.findings_ratchet = false`
+        ? `pre_push.findings_ratchet is enabled but ${config.findings.floor} does not exist — every push fails until a floor lands; commit one or set pre_push.findings_ratchet = false`
         : null,
       `${config.findings.floor} is present or the ratchet is disabled`,
-      'warn',
     )
-    // A floor on its own measures nothing. With the safety gate in hook.ts
-    // (counters empty + no floor → no-op), this is informational when the
-    // floor is missing; it stays a hard error only when a floor IS committed
-    // but no counter is declared to drive it (the runtime hard-fails too:
-    // `findingsRatchetReport` returns 1 when counters is empty).
     if (config.prePush.findingsRatchet && findingsFloorExists && Object.keys(config.findings.counters).length === 0) {
       add(
         'findings-counters',
@@ -205,9 +194,9 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
     } else if (config.prePush.findingsRatchet && Object.keys(config.findings.counters).length === 0) {
       add(
         'findings-counters',
-        'pre_push.findings_ratchet is enabled but [controls.findings.counters] declares none — the gate is a no-op until a counter is declared',
+        'pre_push.findings_ratchet is enabled but [controls.findings.counters] declares none — every push fails until a counter is declared',
         'at least one findings counter is declared, or the ratchet is disabled',
-        'warn',
+        'fail',
       )
     } else {
       add('findings-counters', null, 'at least one findings counter is declared, or the ratchet is disabled')
@@ -226,7 +215,9 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
   }
 
   let complianceEnabled = false
+  let complianceFlag = false
   try {
+    complianceFlag = loadConfig(repo).preCommit.compliance
     const complianceConfig = loadComplianceConfig(repo)
     add('compliance-config', null, 'adl-config.toml [compliance] is valid')
     complianceEnabled = complianceConfig.enabled.length > 0
@@ -244,7 +235,7 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
         ? 'this repository has a plans/ tree but docs.ledger is not in [controls.compliance].enabled — the knowledge-ledger contract (DOC-009) is unenforced'
         : null,
       hasPlans ? 'docs.ledger is armed for this plans/ tree' : 'no plans/ tree, so docs.ledger is not required',
-      'warn',
+      complianceFlag ? 'fail' : 'warn',
     )
   } catch (error) {
     add('compliance-config', errorText(error), '')
@@ -262,7 +253,6 @@ export function doctor(repoArg: string, env: Env, options: string | DoctorOption
       ? 'ast-grep not found on PATH — every compliance row that needs it reports could-not-run, never a pass; 26 rows are affected (see README)'
       : null,
     'ast-grep on PATH, or [compliance].enabled is empty so it is not required',
-    'warn',
   )
 
   let lock: Lock | null = null

package/packages/repo-controls/src/findings-ratchet.ts

@@ -161,3 +161,17 @@ export function findingsProblems(
   }
   return problems
 }
+
+/** A floor entry for a counter the repository does not declare grades nothing, so it fails. */
+export function undeclaredFloorProblems(floor: Floor, counters: Record<string, string>): FindingProblem[] {
+  const undeclared = Object.keys(floor).filter((counter) => !Object.hasOwn(counters, counter)).sort()
+  if (undeclared.length === 0) return []
+  return [
+    {
+      fails: true,
+      message:
+        `the floor lists counter(s) not declared in [controls.findings.counters]: ${undeclared.join(', ')} — ` +
+        'declare the counter or delete its floor entry',
+    },
+  ]
+}

package/packages/repo-controls/src/gitignore-block.ts

@@ -14,12 +14,7 @@
 //
 // Evidence for each entry, gathered 2026-09-27 by reading this monorepo's
 // own source (not guessed):
-//   - `/.enact/logs/`      — pre-hard-cut evidence only. Neither repo-controls' git
-//                            hooks (`src/hook-log.ts`, 2026-09-27) nor
-//                            agent-hooks' own hook log write here any more —
-//                            both moved to `.adl/logs/` JSON-Lines files
-//                            (docs/architecture/cli-design.md §5a). Existing rows are
-//                            quarantined in place, never migrated.
+//   - `/.enact/logs/`      — pre-hard-cut evidence only; nothing writes there (README, "Log folders").
 //   - `/.coverage-cache/`  — constants.ts `GITIGNORE_LINES` (retired) /
 //                            install.ts `installGitignore`'s coverage-cache
 //                            handling; populated by the coverage ratchet.
@@ -34,10 +29,7 @@
 //                            a static, always-present pattern that matches
 //                            nothing costs a consumer repo nothing, and one
 //                            static list is the whole point of this file.
-//   - `/.adl/`             — packages/cli/src/log.ts's `.adl/logs` (repo
-//                            root's session/tool-call log; docs/architecture/cli-design.md
-//                            §5a). Whole `.adl/` dir ignored, matching this
-//                            monorepo's own hand-authored line.
+//   - `/.adl/`             — the whole `.adl/` dir, including `.adl/logs/<owner>/` (README, "Log folders").
 //   - `/.scratchpad/`, `packages/*/.scratchpad/`
 //                          — not created by any single tool's code, but
 //                            mandated by the global agent convention (every
@@ -83,10 +75,8 @@ export const GITIGNORE_BLOCK_LINES: readonly string[] = [
   '# repo-controls: coverage ratchet cache',
   '/.coverage-cache/',
   '',
-  '# repo-controls / agent-hooks: canonical repository-local hook and session logs',
-  '/.enact/logs/',
-  '',
   '# repo-controls: pre-hardcut hook-log quarantine (evidence only, never read or written)',
+  '/.enact/logs/',
   '/.workflows/hooks/logs/',
   '/.enact-runtime/repo-controls/hooks/',
   '',

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

@@ -15,10 +15,7 @@
  *
  * BEHAVIOUR CHANGE (Tarun, 2026-09-27, §5a): this replaces two CSV files
  * under `.enact/logs/` (`adl-repo-controls-{activity,deny}.log`) with the
- * shared format's `.adl/logs/repo-controls.log` (every invocation) and
- * `.adl/logs/hooks-deny.log` (FAIL rows only — shared with agent-hooks' own
- * PreToolUse denies, so a human `git commit` denial and an agent's blocked
- * shell command land in one timeline). `.enact/logs/` is a hard cut: this
+ * shared format's `.adl/logs/git-hooks/{activity,deny}.log` (README, "Log folders"). `.enact/logs/` is a hard cut: this
  * module never reads or writes it; whatever evidence is already there is left exactly where it is.
  *
  * Field mapping onto `LogEntryInput` (`../../agent-hooks/src/log/writer.ts`)
@@ -26,7 +23,7 @@
  * fields (Tarun, 2026-09-28: host second with the host alone, tool_call
  * third with the hook kind):
  *   - `host` is the constant `'git'` — distinguishes a git-hook row from an
- *     agent-hook row sharing the same files.
+ *     row in agent-hooks' folder; the two owners no longer share a file.
  *   - `tool_call` is the hook name (`commit-msg`, `pre-commit`, ...),
  *     unchanged from `hook_log_init`'s first argument.
  *   - `event` is the hook name too, unchanged from `hook_log_init`'s first
@@ -45,7 +42,7 @@
  *     here — git hooks run outside an `adl run` child env.)
  *
  * Best-effort by construction, the same contract `hook-log.sh`'s CSV writer
- * always had: `writeLogEntry` throwing is swallowed here rather than
+ * always had: `writeLogEntry` throwing is reported on stderr (one line) rather than
  * propagated, so a genuinely unwritable `.adl/logs/` can never change a git
  * hook's exit code.
  */
@@ -63,9 +60,9 @@ export function logHookEvent(hook: HookName, reason: string, context: string, me
     ...(message !== '' ? { result: message } : {}),
   }
   try {
-    writeLogEntry('repo-controls', entry, { cwd })
-    if (reason.startsWith('FAIL')) writeLogEntry('hooks-deny', entry, { cwd })
-  } catch {
-    // Best-effort: a log write must never change a git hook's outcome.
+    writeLogEntry('git-hooks/activity', entry, { cwd })
+    if (reason.startsWith('FAIL')) writeLogEntry('git-hooks/deny', entry, { cwd })
+  } catch (error) {
+    process.stderr.write(`adl repo controls: could not write log row: ${error instanceof Error ? error.message : String(error)}\n`)
   }
 }

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

@@ -1,16 +1,16 @@
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { LOCKFILE_KEYS, loadComplianceConfig } from './compliance-config.ts'
+import { declaredComplianceTree, LOCKFILE_KEYS, loadComplianceConfig, parseComplianceConfig } 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 { BUNDLE_ROOT, COMPLIANCE_ROOT, CONFIG_REL, 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 { doctor, type DoctorReport } from './doctor.ts'
 import { commitRequiredProblems, integrityProblems } from './integrity.ts'
 import { lfsChain } from './lfs.ts'
 import { logHookEvent } from './hook-log.ts'
-import { type CoverageSummary, coverageRegressions, readSummary } from './coverage-ratchet.ts'
-import { type Floor, findingsProblems, parseCounterOutput, parseFloor } from './findings-ratchet.ts'
+import { type CoverageSummary, coverageRegressions, newlyBaselined, readSummary } from './coverage-ratchet.ts'
+import { type Floor, findingsProblems, parseCounterOutput, parseFloor, undeclaredFloorProblems } from './findings-ratchet.ts'
 import { bashProblem, capture, childEnv, type Env, resolveRepo, which } from './runtime.ts'
 import { postCheckoutWorktreeGuardStep } from './worktree-guard.ts'
 
@@ -30,6 +30,8 @@ export interface RunContext {
   err: (line: string) => void
   /** Progress the hook wants seen. Defaults to stderr's sink when not supplied. */
   out?: (line: string) => void
+  /** Discard the compliance engine's stdout rows; see README, "Compliance seeding". */
+  quietEngine?: boolean
   /**
    * 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
@@ -129,6 +131,8 @@ function runUv(args: string[], repo: string, context: RunContext): number {
     // (the engine rejects an empty `--declare` value); `parseMarkdown` already
     // guaranteed each root is comma-free, so the join is unambiguous.
     ...(config.markdown?.roots.length ? ['--declare', `markdown-roots=${config.markdown.roots.join(',')}`] : []),
+    // LAY-008's extra asset directories, one comma list. Empty is skipped, never sent; `parsePlacement` guaranteed each entry is comma-free.
+    ...(config.placement?.asset_dirs.length ? ['--declare', `asset-dirs=${config.placement.asset_dirs.join(',')}`] : []),
     // REP-002's declared manifest and lockfile paths, one comma list per key, in
     // `LOCKFILE_KEYS` order (`bun-manifests`, `bun-lockfiles`, `cargo-manifests`,
     // `cargo-lockfiles`). An empty list is skipped, never sent; `parseLockfiles` already
@@ -140,7 +144,7 @@ function runUv(args: string[], repo: string, context: RunContext): number {
   ]
   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' },
+    { cwd: repo, env: childEnv(context.env), stdin: 'inherit', stdout: context.quietEngine ? 'ignore' : 'inherit', stderr: 'inherit' },
   )
   return proc.exitCode ?? 1
 }
@@ -198,8 +202,13 @@ export function withStagedIndexSnapshot<T>(
   }
 }
 
-/** Whether the candidate commit itself arms compliance. */
-export function stagedComplianceEnabled(repo: string, env: Env): boolean {
+export interface StagedComplianceGate {
+  armed: boolean
+  enabled: string[]
+}
+
+/** The compliance flag and the enabled gate list, both read from the candidate commit's adl-config.toml. */
+export function stagedComplianceGate(repo: string, env: Env): StagedComplianceGate {
   const shown = capture(['git', 'show', ':adl-config.toml'], repo, env)
   if (shown.code !== 0) {
     if (loadConfig(repo).preCommit.compliance) {
@@ -207,9 +216,20 @@ export function stagedComplianceEnabled(repo: string, env: Env): boolean {
         'compliance is enabled in the working tree but adl-config.toml is absent from the staged index',
       )
     }
-    return false
+    return { armed: false, enabled: [] }
+  }
+  return { armed: parseConfig(shown.stdout).preCommit.compliance, enabled: parseComplianceConfig(shown.stdout).enabled }
+}
+
+/** Flag true with an empty gate list fails loud; only an explicit pre_commit.compliance = false skips. */
+export function stagedComplianceStep(gate: StagedComplianceGate, run: () => number, err: (line: string) => void): number {
+  if (!gate.armed) return 0
+  if (gate.enabled.length === 0) {
+    err('pre-commit: FAIL — pre_commit.compliance is on but [controls.compliance].enabled is empty.')
+    err('  enabled is empty; list gates or set pre_commit.compliance = false.')
+    return 1
   }
-  return parseConfig(shown.stdout).preCommit.compliance
+  return run()
 }
 
 /**
@@ -272,6 +292,10 @@ export function findingsRatchetReport(
   }
 
   let failed = false
+  for (const problem of undeclaredFloorProblems(floor, findings.counters)) {
+    failed = true
+    err(`pre-push: FAIL — ${problem.message}`)
+  }
   for (const [name, command] of counters) {
     const run = runCounter(command)
     if (run.code !== 0) {
@@ -398,9 +422,18 @@ export function coverageRatchetStep(
   readBaseline: () => string | null,
   readCurrent: () => string,
   err: (line: string) => void,
+  options: { firstBaseline?: boolean; existsOnDisk?: (path: string) => boolean } = {},
 ): number {
   const baselineText = readBaseline()
-  if (baselineText === null) return 0
+  if (baselineText === null) {
+    if (options.firstBaseline === true) {
+      err(`pre-push: note — ${summaryPath} is added in HEAD: first baseline, nothing to grade it against.`)
+      return 0
+    }
+    err(`pre-push: FAIL — no HEAD~1 baseline for ${summaryPath} and the summary is not added in HEAD.`)
+    err('  An armed ratchet with nothing to compare against grades nothing; commit the baseline first.')
+    return 1
+  }
 
   let baseline: CoverageSummary
   let current: CoverageSummary
@@ -418,13 +451,37 @@ export function coverageRatchetStep(
     return 1
   }
 
-  const regressions = coverageRegressions(baseline, current)
+  for (const path of newlyBaselined(baseline, current)) err(`pre-push: note — ${path} is new, now baselined.`)
+  const regressions = coverageRegressions(baseline, current, options.existsOnDisk)
   if (regressions.length === 0) return 0
   err(`pre-push: FAIL — coverage regressed in ${summaryPath}:`)
   for (const line of regressions) err(`    - ${line}`)
   return 1
 }
 
+export interface CoveragePushProbes {
+  rel: string
+  worktree: string | null
+  head: string | null
+  baseline: string | null
+  addedInHead: boolean
+  existsOnDisk: (path: string) => boolean
+}
+
+/** The armed coverage ratchet at push: every missing input fails, only a summary added in HEAD is a first baseline. */
+export function coverageRatchetPush(probes: CoveragePushProbes, err: (line: string) => void): number {
+  const current = probes.head ?? probes.worktree
+  if (current === null) {
+    err(`pre-push: FAIL — pre_push.coverage_ratchet is on but ${probes.rel} exists in neither HEAD nor the work tree.`)
+    err('  Commit a summary or set pre_push.coverage_ratchet = false.')
+    return 1
+  }
+  return coverageRatchetStep(probes.rel, () => probes.baseline, () => current, err, {
+    firstBaseline: probes.addedInHead,
+    existsOnDisk: probes.existsOnDisk,
+  })
+}
+
 /**
  * The repository's declared commands for one hook.
  *
@@ -544,6 +601,13 @@ function dirtyPaths(porcelain: string): string[] {
   return paths
 }
 
+/** The repository's `[controls.integrity] watched` plus the declared compliance register folder (see README, "Managed dot paths and protected controls"). */
+export function integrityWatched(repo: string): string[] {
+  const watched = loadConfig(repo).integrity.watched
+  const tree = declaredComplianceTree(readFileSync(join(repo, CONFIG_REL), 'utf8'))
+  return tree === null ? watched : [...watched, `${tree}/**`]
+}
+
 /** Refuses a commit while a protected worktree edit is excluded from its index. */
 export function integrityStep(
   porcelain: string,
@@ -600,10 +664,10 @@ export function integrityGate(
  * `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 {
+export function doctorGate(readDoctor: () => DoctorReport, err: (line: string) => void, hook = 'pre-commit'): number {
   const report = readDoctor()
   if (report.ok) return 0
-  err('pre-commit: FAIL — adl-repo-controls doctor found an unarmed control:')
+  err(`${hook}: FAIL — adl-repo-controls doctor found an unarmed control:`)
   for (const check of report.checks) {
     if (check.status === 'fail') err(`  ${check.id}  ${check.message}`)
   }
@@ -621,21 +685,16 @@ export function doctorGate(readDoctor: () => DoctorReport, err: (line: string) =
  * `loadConfig`) can throw on a malformed config; that is reported the same
  * way as an unarmed check rather than crashing the hook process.
  */
-function azureDevOpsPromotionGovernanceGate(readChecks: () => Check[], err: (line: string) => void): number {
-  let checks: Check[]
+function azureDevOpsPromotionGovernanceGate(readReport: () => DoctorReport, err: (line: string) => void): number {
+  let report: DoctorReport
   try {
-    checks = readChecks()
+    report = readReport()
   } catch (error) {
-    err('pre-push: FAIL — could not evaluate Azure DevOps promotion governance:')
+    err('pre-push: FAIL — could not evaluate adl-repo-controls doctor:')
     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
+  return doctorGate(() => report, err, 'pre-push')
 }
 
 /** Real I/O around `findingsRatchetReport`. */
@@ -643,7 +702,12 @@ function runFindingsRatchet(repo: string, context: RunContext): number {
   const config = loadConfig(repo)
   return findingsRatchetReport(
     config.findings,
-    () => readFileSync(join(repo, config.findings.floor), 'utf8'),
+    () => {
+      if (!existsSync(join(repo, config.findings.floor))) {
+        throw new Error(`${config.findings.floor} does not exist; commit a floor or set pre_push.findings_ratchet = false`)
+      }
+      return readFileSync(join(repo, config.findings.floor), 'utf8')
+    },
     (command) => capture(['bash', '-c', command], repo, context.env),
     context.err,
   )
@@ -673,7 +737,7 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
     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,
+      integrityWatched(repo),
       context.err,
     )
     if (code !== 0) return code
@@ -698,37 +762,28 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
   // when `[controls.compliance].enabled` is empty -- the same "wrapper on,
   // work gated by configured state" shape as stagedCoverage/coverageRatchet/
   // findingsRatchet above and the docFreshness floor's empty-files case.
-  if (name === 'pre-commit' && stagedComplianceEnabled(repo, context.env)) {
-    if (loadComplianceConfig(repo).enabled.length > 0) {
-      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
-    }
+  if (name === 'pre-commit') {
+    const code = stagedComplianceStep(
+      stagedComplianceGate(repo, context.env),
+      () =>
+        withStagedIndexSnapshot(repo, context.env, (snapshot) =>
+          complianceStep(() => runUv(['--files', snapshot.files, '--exhaustive'], snapshot.root, context)),
+        ),
+      context.err,
+    )
+    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`.
-  // Safety gate: `stagedCoverage` defaults ON; a repository that has not declared
-  // `[controls.coverage].produce` has nothing to run, so the step is a no-op.
-  // Same shape as `compliance` below: the wrapper is on, the work is gated by
-  // whether the repository opted into the configuration it needs.
   if (name === 'pre-commit' && loadConfig(repo).preCommit.stagedCoverage) {
-    const config = loadConfig(repo)
-    if (config.coverage.produce.trim() !== '') {
-      const code = stagedCoverageStep(
-        config.coverage,
-        (command) => capture(['bash', '-c', command], repo, context.env),
-        null,
-        context.err,
-      )
-      if (code !== 0) return code
-    }
+    const code = stagedCoverageStep(
+      loadConfig(repo).coverage,
+      (command) => capture(['bash', '-c', command], repo, context.env),
+      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
@@ -737,10 +792,7 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
   // 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,
-    )
+    const code = azureDevOpsPromotionGovernanceGate(() => doctor(repo, context.env), context.err)
     if (code !== 0) return code
   }
   // The coverage MEASUREMENT at push, before the ratchet below grades what it
@@ -757,37 +809,29 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
   }
   // 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.
-  // Safety gate: `coverageRatchet` defaults ON; the ratchet has no baseline
-  // unless the repository has staged a coverage summary file at the path
-  // `[controls.coverage].summary` declares. With no file on either side of the
-  // index, the step is a no-op — same shape as compliance below.
   if (name === 'pre-push' && loadConfig(repo).prePush.coverageRatchet) {
-    const config = loadConfig(repo)
-    const rel = config.coverage.summary
-    if (rel !== '' && (existsSync(join(repo, rel)) || capture(['git', 'cat-file', '-e', `HEAD:${rel}`], repo, context.env).code === 0)) {
-      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
+    const rel = loadConfig(repo).coverage.summary
+    const at = (ref: string): string | null => {
+      const shown = capture(['git', 'show', `${ref}:${rel}`], repo, context.env)
+      return shown.code === 0 ? shown.stdout : null
     }
+    const added = capture(['git', 'diff-tree', '--root', '--no-commit-id', '--name-status', '-r', 'HEAD', '--', rel], repo, context.env)
+    const code = coverageRatchetPush(
+      {
+        rel,
+        worktree: existsSync(join(repo, rel)) ? readFileSync(join(repo, rel), 'utf8') : null,
+        head: at('HEAD'),
+        baseline: at('HEAD~1'),
+        addedInHead: added.code === 0 && added.stdout.startsWith('A'),
+        existsOnDisk: (path) => existsSync(join(repo, path)),
+      },
+      context.err,
+    )
+    if (code !== 0) return code
   }
-  // The findings ratchet, before the bundled script, same shape as compliance
-  // above. Safety gate: `findingsRatchet` defaults ON; the gate has nothing
-  // to grade unless `[controls.findings].floor` exists. With no floor file,
-  // the step is a no-op — same shape as compliance and coverageRatchet.
   if (name === 'pre-push' && loadConfig(repo).prePush.findingsRatchet) {
-    const floorPath = loadConfig(repo).findings.floor
-    if (floorPath !== '' && existsSync(join(repo, floorPath))) {
-      const code = runFindingsRatchet(repo, context)
-      if (code !== 0) return code
-    }
+    const code = runFindingsRatchet(repo, context)
+    if (code !== 0) return code
   }
   // git writes pre-push's ref lines on stdin exactly once. The bundled script
   // reads them for the branch rules and `git lfs pre-push` needs them too, so