@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

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

@@ -1,12 +1,14 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { loadComplianceConfig } from './compliance-config.ts'
+import { LOCKFILE_KEYS, 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 { 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 { bashProblem, capture, childEnv, type Env, resolveRepo, which } from './runtime.ts'
@@ -45,7 +47,16 @@ export interface RunContext {
 }
 
 /** 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 {
+function runBundled(
+  runtime: 'bash' | 'bun',
+  script: string,
+  args: string[],
+  repo: string,
+  workdir: string,
+  context: RunContext,
+  /** What to write to the script's stdin instead of {@link RunContext.stdin}: pre-push's already-captured ref lines. */
+  input?: string,
+): number {
   const problem = bashProblem(context.env)
   if (problem) throw new Error(problem)
   const env = { ...context.env, ...configEnv(repo, loadConfig(repo)) }
@@ -54,7 +65,7 @@ function runBundled(runtime: 'bash' | 'bun', script: string, args: string[], rep
   const proc = Bun.spawnSync([executable, join(BUNDLE_ROOT, script), ...args], {
     cwd: workdir,
     env: childEnv(env),
-    stdin: context.stdin ?? 'inherit',
+    stdin: input === undefined ? (context.stdin ?? 'inherit') : Buffer.from(input),
     stdout: 'inherit',
     stderr: 'inherit',
   })
@@ -83,6 +94,49 @@ function runUv(args: string[], repo: string, context: RunContext): number {
     ...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}`]),
+    // Extra root names this repository allows, as comma lists. An empty list is
+    // skipped, never sent: the engine rejects an empty `--declare` value. Names are
+    // validated comma-free in `parseRoot`, so the join is unambiguous.
+    ...(config.root?.files.length ? ['--declare', `root-files=${config.root.files.join(',')}`] : []),
+    ...(config.root?.dirs.length ? ['--declare', `root-dirs=${config.root.dirs.join(',')}`] : []),
+    // Engine limits this repository overrides. An unset key sends nothing, so the
+    // engine's own default stays in force; `parseLimits` already guaranteed a
+    // positive integer, which is what the engine will accept.
+    ...(config.limits?.scripts_direct_files !== undefined
+      ? ['--declare', `scripts-direct-files=${config.limits.scripts_direct_files}`]
+      : []),
+    ...(config.limits?.open_gaps !== undefined ? ['--declare', `open-gaps=${config.limits.open_gaps}`] : []),
+    ...(config.limits?.open_plans !== undefined ? ['--declare', `open-plans=${config.limits.open_plans}`] : []),
+    ...(config.limits?.docs_pages_per_directory !== undefined
+      ? ['--declare', `docs-pages-per-directory=${config.limits.docs_pages_per_directory}`]
+      : []),
+    // LAY-004's per-tree ceilings, as ONE comma list of `<path>:<n>` entries —
+    // the engine splits the list and refuses anything but a repo-relative
+    // path and a base-10 positive integer. Entries are sorted so the argv is
+    // deterministic whatever the TOML table's order. An empty or undeclared
+    // table sends nothing: no configuration, nothing to enforce.
+    ...(() => {
+      const ceilings = config.directory_ratchet?.max_children ?? {}
+      const entries = Object.entries(ceilings)
+      if (entries.length === 0) return []
+      const joined = entries
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([path, n]) => `${path}:${n}`)
+        .join(',')
+      return ['--declare', `directory-ceilings=${joined}`]
+    })(),
+    // Extra Markdown roots, as one comma list. An empty list is skipped, never sent
+    // (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(',')}`] : []),
+    // 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
+    // guaranteed each entry is comma-free and that a half is set as a pair.
+    ...LOCKFILE_KEYS.flatMap((key) => {
+      const entries = config.lockfiles?.[key] ?? []
+      return entries.length > 0 ? ['--declare', `${key.replace('_', '-')}=${entries.join(',')}`] : []
+    }),
   ]
   const proc = Bun.spawnSync(
     [executable, 'run', '--project', COMPLIANCE_ROOT, 'adl-compliance', '--root', repo, ...injected, ...args],
@@ -286,6 +340,45 @@ export function stagedCoverageStep(
   return run.code
 }
 
+/**
+ * The coverage MEASUREMENT at push: the repository's declared push-phase
+ * command, not ours.
+ *
+ * The same division as `stagedCoverageStep`, one phase later: the repository
+ * says HOW to measure (`[controls.coverage].produce_push`), this package
+ * decides WHEN (pre-push, before the ratchet grades what the measurement
+ * wrote) and grades the exit status. The estate moved the measurement here
+ * because it serialises minutes of work; commits stay fast, and the push
+ * measures then grades in one gate.
+ *
+ * `produce_push` is a separate declaration from `produce` rather than a reuse:
+ * a commit-phase producer may stage a refreshed summary, while a push-phase
+ * command runs against an immutable HEAD — a check-mode run that never mutates
+ * the index is the shape.
+ *
+ * Absence is deliberately NOT a skip, same rule as at commit: with the gate
+ * armed and no command declared, this is could-not-run — a step that measures
+ * nothing is not a pass.
+ */
+export function coverageProduceStep(
+  producePush: string,
+  runCommand: (command: string) => { code: number; stdout: string; stderr: string },
+  err: (line: string) => void,
+): number {
+  const declared = producePush.trim()
+  if (declared === '') {
+    err('pre-push: FAIL — pre_push.coverage_produce is on but [controls.coverage].produce_push declares no command.')
+    err('  A step that measures nothing is not a pass.')
+    return 1
+  }
+  const run = runCommand(declared)
+  if (run.code !== 0) {
+    err(`pre-push: FAIL — coverage.produce_push 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.
@@ -365,6 +458,10 @@ export function declaredChecksFor(
     // here, on purpose — see tests/declared-hook-scripts.test.ts.
     case 'post-checkout':
       return []
+    // `post-merge` exists only to chain Git LFS (scripts/hooks/lib/lfs.sh); like
+    // post-checkout it has no repository-declared seam.
+    case 'post-merge':
+      return []
   }
 }
 
@@ -524,7 +621,7 @@ 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.
  */
-export function azureDevOpsPromotionGovernanceGate(readChecks: () => Check[], err: (line: string) => void): number {
+function azureDevOpsPromotionGovernanceGate(readChecks: () => Check[], err: (line: string) => void): number {
   let checks: Check[]
   try {
     checks = readChecks()
@@ -557,7 +654,7 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
   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
+  // The worktree-count backstop (docs/operations/worktree-guard.md). 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
@@ -597,34 +694,41 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
   // 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.
+  // "enabled" and dormant. `compliance` defaults ON, but the step is a no-op
+  // 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)) {
-    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 (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
+    }
   }
   // 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)
-    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
+    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
+    }
   }
   // The Azure DevOps promotion-governance checks, moved here from pre-commit
   // (2026-09-28, Tarun): network access and a minted token are already
@@ -639,49 +743,101 @@ export function runHook(name: HookName, args: string[], context: RunContext): nu
     )
     if (code !== 0) return code
   }
+  // The coverage MEASUREMENT at push, before the ratchet below grades what it
+  // wrote. Opt-in: `coverageProduce` defaults OFF (new gates opt in), unlike
+  // the ratchet's ON. Armed with no declared command, the step itself fails
+  // loud — a step that measures nothing is not a pass; off is a no-op.
+  if (name === 'pre-push' && loadConfig(repo).prePush.coverageProduce) {
+    const code = coverageProduceStep(
+      loadConfig(repo).coverage.producePush,
+      (command) => capture(['bash', '-c', command], 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.
+  // 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
-    const at = (ref: string) => {
-      const shown = capture(['git', 'show', `${ref}:${rel}`], repo, context.env)
-      return shown.code === 0 ? shown.stdout : null
+    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 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.
+  // 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 code = runFindingsRatchet(repo, context)
-    if (code !== 0) return code
+    const floorPath = loadConfig(repo).findings.floor
+    if (floorPath !== '' && existsSync(join(repo, floorPath))) {
+      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
+  // they are read here, once, and fed to both. Every other hook has no stdin
+  // contract and passes none.
+  const pushUpdates = name === 'pre-push' && (context.stdin ?? 'inherit') === 'inherit' ? readFileSync(0, 'utf8') : ''
   // The package's standard bash: the shared policy every repository gets.
-  const standard = runBundled('bash', `hooks/${name}`, args, repo, context.cwd, context)
+  const standard = runBundled(
+    'bash',
+    `hooks/${name}`,
+    args,
+    repo,
+    context.cwd,
+    context,
+    name === 'pre-push' ? pushUpdates : undefined,
+  )
   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
+  // Git LFS comes last, after every adl check passed: a refused push uploads
+  // nothing. See ./lfs.ts for why this is here and not in the bash.
+  if (name === 'pre-push') return lfsStep(name, args, pushUpdates, repo, context)
 
   // 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(
+  const declared = preCommitChecks(
     declaredChecksFor(name, loadConfig(repo)),
     (command) => capture(['bash', '-c', command], repo, context.env),
     context.err,
   )
+  const lfs = lfsStep(name, args, '', repo, context)
+  return declared !== 0 ? declared : lfs
+}
+
+/** `lfsChain` plus the log row the bundled script cannot write: it has already logged PASS by the time git-lfs runs. */
+function lfsStep(name: HookName, args: string[], input: string, repo: string, context: RunContext): number {
+  const failures: string[] = []
+  const code = lfsChain(name, args, input, repo, {
+    env: context.env,
+    err: (line) => {
+      failures.push(line)
+      context.err(line)
+    },
+  })
+  if (code !== 0) logHookEvent(name, `FAIL exit=${code}`, '', failures[0] ?? `git lfs ${name} failed`, repo)
+  return code
 }
 
 // `_tool` is unread on purpose. `compliance` is the only tool left, and it is a

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

@@ -48,7 +48,7 @@ interface GitignoreRecord {
   created: boolean
 }
 
-export type TableConfigRecord = { created: boolean; sha256: string } | null
+type TableConfigRecord = { created: boolean; sha256: string } | null
 
 export interface Lock {
   lockVersion: 1
@@ -79,9 +79,9 @@ export function vendoredPromotePath(): string {
 
 /**
  * The stub execs `adl repo controls hook <name>`, not a standalone
- * `adl-repo-controls` binary (adl-m3-finish item 1, 2026-09-27): this
+ * `adl-repo-controls` binary (2026-09-27): this
  * package is folded into the `adl` binary's `repo controls` namespace
- * (docs/architecture/cli-design.md §6, STATUS.md item 10) — hard cut, no compat shim, the
+ * (docs/architecture/cli-design.md §6) — hard cut, no compat shim, the
  * same decision `adl hook` already made for agent-hooks. `adl` is what a
  * repository's hooks now require on PATH, and `adl` is what the fleet
  * actually installs (bin/reconcile's `bun-compile` manager); see
@@ -335,15 +335,21 @@ function ownedTable(text: string, tableName: string): Table | null {
   }
 }
 
-/** Reject malformed text that declares itself to be this package's table. */
+/**
+ * Reject malformed text that declares itself to be this package's table, and the two
+ * array tables install owns outright: `[[controls]]` and `[[controls.compliance]]`.
+ * Array tables NESTED under an owned table (`[[controls.pre_push.static_checks]]`,
+ * what `adl migrate` writes) are ordinary user data: the same value as the inline
+ * form, kept byte-for-byte.
+ */
 function assertNoMalformedOwnedHeader(text: string): void {
   for (const raw of text.split('\n')) {
     const line = raw.trim()
-    const ownedArrayTable = /^\[\[\s*(controls(?:\.[A-Za-z0-9_-]+)*)\s*\]\]\s*(?:#.*)?$/.exec(line)
-    if (ownedArrayTable !== null) {
-      throw new Error(`${CONFIG_REL} declares unsupported owned array table: [[${ownedArrayTable[1]}]]`)
+    const arrayTable = /^\[\[\s*(controls(?:\.[A-Za-z0-9_-]+)*)\s*\]\]\s*(?:#.*)?$/.exec(line)
+    if (arrayTable !== null && (arrayTable[1] === 'controls' || arrayTable[1] === 'controls.compliance')) {
+      throw new Error(`${CONFIG_REL} declares unsupported owned array table: [[${arrayTable[1]}]]`)
     }
-    if (/^\[\[\s*controls(?:\.|\]|\s)/.test(line)) {
+    if (arrayTable === null && /^\[\[\s*controls(?:\.|\]|\s)/.test(line)) {
       throw new Error(`${CONFIG_REL} [controls] is invalid TOML: malformed table header`)
     }
     if (line === '[controls' || /^\[controls(?=\.|\])/.test(line) && !/^\[controls(?:\.[A-Za-z0-9_-]+)*\]$/.test(line)) {

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

@@ -7,7 +7,7 @@
  * adl hook is responsible for refusing that escape hatch to agents.
  */
 
-export const WIRING: readonly string[] = ['adl-config.toml']
+const WIRING: readonly string[] = ['adl-config.toml']
 
 // Tarun, 2026-09-30: `.workflows/` and every agent surface root are protected
 // like `workflows/` — a dirty path under any of them blocks a normal commit and
@@ -50,7 +50,7 @@ function patternToRegExp(pattern: string): RegExp {
 }
 
 /** Match the repository-declared portion of the protected set. */
-export function protectedMatchers(watched: readonly string[]): ((path: string) => boolean)[] {
+function protectedMatchers(watched: readonly string[]): ((path: string) => boolean)[] {
   const wiring = WIRING.map((name) => (path: string) => path === name)
   const declared = watched.map((pattern) => {
     const re = patternToRegExp(pattern)
@@ -62,7 +62,7 @@ export function protectedMatchers(watched: readonly string[]): ((path: string) =
 const isUnderFixedRoot = (path: string): boolean => FIXED_ROOTS.some((root) => path === root || path.startsWith(`${root}/`))
 
 /** Centrally managed repository files that must travel with the next commit. */
-export const isTopLevelDotPath = (path: string): boolean => path.startsWith('.')
+const isTopLevelDotPath = (path: string): boolean => path.startsWith('.')
 
 /**
  * The single source of truth used for final-index and dirty-worktree checks.

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

@@ -0,0 +1,111 @@
+/**
+ * Git LFS chaining for the projected hooks.
+ *
+ * WHY THIS EXISTS (live, 2026-10-01, enact-combined). `adl repo controls install`
+ * sets `core.hooksPath=.workflows/hooks`, so git never runs the
+ * `.git/hooks/{pre-push,post-checkout,post-commit,post-merge}` that
+ * `git lfs install` writes. adl's own hooks did not call git-lfs, so a push of a
+ * commit carrying an LFS pointer succeeded WITHOUT uploading the object and left
+ * a broken pointer on the remote. Each of those four hooks now chains to
+ * `git lfs <hook> "$@"` from `runHook`.
+ *
+ * Rules, in order:
+ *   1. A repository that does not use LFS never calls git lfs.
+ *   2. A repository that uses LFS with no `git-lfs` on PATH FAILS LOUD. There is
+ *      no silent skip: a skipped pre-push is exactly the broken-pointer bug.
+ *   3. A failing `git lfs <hook>` is the hook's failure (for pre-push: the push
+ *      fails).
+ *
+ * WHY THIS IS TYPESCRIPT, NOT THE BUNDLED BASH. bin/git-ado authenticates an
+ * agent's `git push` by exporting `GIT_CONFIG_COUNT` and a
+ * `GIT_CONFIG_KEY_n=http.https://<host>/.extraHeader` /
+ * `GIT_CONFIG_VALUE_n=Authorization: Bearer <token>` pair to the real git; git
+ * passes its environment to the hook. `runBundled` hands the bash scripts a
+ * `childEnv` with every `GIT_CONFIG_*` removed, on purpose, so adl's own checks
+ * never hold the token. git-lfs is the one child that must, and it must hold
+ * exactly the pairs the parent `git push` had -- the same mechanism, never a
+ * second mint, never the human's credential helper (tests/lfs-credential-
+ * boundary.test.ts proves git-lfs reads that header and does not fall back).
+ * `runHook` is the only place that still has the unstripped `context.env`, so
+ * the chaining lives here and only this one spawn is given it.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { HookName } from './constants.ts'
+import { capture, type Env, which } from './runtime.ts'
+
+/** The hooks `git lfs install` writes -- and so the ones a controlled repository must chain. */
+export const LFS_HOOKS: readonly HookName[] = ['pre-push', 'post-checkout', 'post-commit', 'post-merge']
+
+const FILTER_LFS = /filter=lfs(\s|$)/m
+
+/**
+ * Whether the repository uses Git LFS: a `filter=lfs` attribute in any
+ * `.gitattributes` (tracked, or untracked and not ignored) or in
+ * `.git/info/attributes`, a `.lfsconfig`, or `lfs.*` in the repository's own git
+ * config. The git calls run through `capture`, whose env carries no
+ * `GIT_CONFIG_*`.
+ */
+export function repoUsesLfs(repo: string, env: Env): boolean {
+  if (existsSync(join(repo, '.lfsconfig'))) return true
+  const grep = capture(['git', 'grep', '-q', '--untracked', '-E', 'filter=lfs([[:space:]]|$)', '--', ':(glob)**/.gitattributes'], repo, env)
+  if (grep.code === 0) return true
+  const info = capture(['git', 'rev-parse', '--git-path', 'info/attributes'], repo, env)
+  if (info.code === 0) {
+    const path = join(repo, info.stdout.trim())
+    if (existsSync(path) && FILTER_LFS.test(readFileSync(path, 'utf8'))) return true
+  }
+  return capture(['git', 'config', '--local', '--name-only', '--get-regexp', '^lfs\\.'], repo, env).code === 0
+}
+
+export interface LfsChainContext {
+  /** The environment git handed the hook, UNSTRIPPED: it is what authenticates git-lfs. */
+  env: Env
+  err: (line: string) => void
+}
+
+/**
+ * Chains one hook to `git lfs <hook> <args...>`, feeding `input` on stdin
+ * (pre-push's ref lines; `''` for the others). Returns the hook's exit status.
+ *
+ * `run` is injected so the decision (skip / fail loud / propagate the status) is
+ * unit-testable without spawning git-lfs; production passes {@link spawnGitLfs}.
+ */
+export function lfsChain(
+  hook: HookName,
+  args: string[],
+  input: string,
+  repo: string,
+  context: LfsChainContext,
+  run: (hook: HookName, args: string[], input: string, repo: string, env: Env) => number = spawnGitLfs,
+): number {
+  if (!LFS_HOOKS.includes(hook)) return 0
+  if (!repoUsesLfs(repo, context.env)) return 0
+  if (!which('git-lfs', context.env)) {
+    context.err(`${hook}: FAIL — this repository uses Git LFS but 'git-lfs' is not on PATH.`)
+    context.err('  Skipping it would leave LFS pointers without their objects; refusing instead.')
+    context.err('  Install git-lfs (macOS: brew install git-lfs; Debian/Ubuntu: apt install git-lfs), then retry.')
+    context.err('  If this repository no longer uses LFS, remove the filter=lfs lines from .gitattributes (and any .lfsconfig).')
+    return 1
+  }
+  const code = run(hook, args, input, repo, context.env)
+  if (code !== 0) context.err(`${hook}: FAIL — git lfs ${hook} exited ${code}.`)
+  return code
+}
+
+/**
+ * `git lfs <hook> <args...>` with the caller's whole environment, GIT_CONFIG_*
+ * included. This is deliberately NOT `childEnv`: see the header.
+ */
+function spawnGitLfs(hook: HookName, args: string[], input: string, repo: string, env: Env): number {
+  const git = which('git', env)
+  if (!git) throw new Error('git not found on PATH')
+  const proc = Bun.spawnSync([git, 'lfs', hook, ...args], {
+    cwd: repo,
+    env: { ...process.env, ...env },
+    stdin: Buffer.from(input),
+    stdout: 'inherit',
+    stderr: 'inherit',
+  })
+  return proc.exitCode ?? 1
+}

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

@@ -6,9 +6,9 @@
  * repositories. Do not add a second implementation here.
  */
 export {
-  BUILD_POLICY_TYPE,
+  
   MERGE_STRATEGIES,
-  MINIMUM_REVIEWER_POLICY_TYPE,
+  
   ensurePromotionPullRequest,
   main,
   promotionPolicyReceipts,
@@ -16,10 +16,10 @@ export {
   type FetchImpl,
   type MergeStrategy,
   type PolicyConfiguration,
-  type PolicyConfigurationList,
-  type PolicyScope,
-  type PromotionPolicyReceipts,
-  type PromotionPolicyRequirement,
-  type PromotionRequest,
-  type PromotionResult,
+  
+  
+  
+  
+  
+  
 } from '../assets/promote.ts'

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

@@ -76,9 +76,17 @@ export function gitOrThrow(repo: string, args: string[]): string {
   return result.stdout
 }
 
-/** The work tree root for `path`; `path` must be that root. */
+/** The work tree root for `path`; `path` must be that root, or empty to default to cwd's git root. */
 export function resolveRepo(path: string): string {
   const absolute = resolve(path)
+  // An empty `path` defaults to cwd's git work tree root — `--repo` is no
+  // longer a typing tax when the caller is already inside the repository.
+  // All `--repo`-taking commands inherit this; the explicit flag still wins.
+  if (absolute === '' || (path === '' && !existsSync(absolute))) {
+    const cwdTop = capture(['git', 'rev-parse', '--show-toplevel'], process.cwd())
+    if (cwdTop.code !== 0) throw new Error(`not a git repository: ${process.cwd()} (cwd)`)
+    return cwdTop.stdout.trim()
+  }
   if (!existsSync(absolute)) throw new Error(`repository path does not exist: ${absolute}`)
   const result = capture(['git', 'rev-parse', '--show-toplevel'], absolute)
   if (result.code !== 0) throw new Error(`not a git repository: ${absolute}`)

package/packages/repo-controls/src/workflows-drift.ts

@@ -5,7 +5,7 @@ import { HOOK_NAMES, HOOKS_PATH, INSTALL_HINT, LOCK_REL, MANAGED_ASSETS, VERSION
 import { checkGitignoreBlock } from './gitignore-block.ts'
 import { readLock, stubText, type Lock } from './install.ts'
 
-export interface WorkflowsDriftFinding {
+interface WorkflowsDriftFinding {
   /** Same ids `doctor()` uses for the same surface (`promote`, `hook:pre-commit`, `version`, ...). */
   id: string
   message: string
@@ -36,13 +36,12 @@ export interface WorkflowsDriftReport {
  * Written for exactly the drift this package's own dogfood install had on
  * 2026-09-27: adl-agent-control's root `.workflows/repo-controls.lock.json`
  * claimed version 0.3.2 with only `promote.ts` and the four hook stubs
- * recorded, while `version-bump.sh` and
+ * recorded, while `version-bump.sh` and the since-retired
  * `scripts/enable-integration-auto-complete.mjs` existed on disk with no
  * lock entry at all, and the `adl-config.toml` the lock's own `config`
  * record claimed to have created did not exist. `checkWorkflowsDrift` would
- * report `version-bump` and `integration-auto-complete` findings for the
- * missing lock entries and a `version` finding for the lock/package
- * mismatch — `doctor()` already does, but nothing outside a full `doctor`
+ * report a finding for each missing lock entry and a `version` finding for
+ * the lock/package mismatch — `doctor()` already does, but nothing outside a full `doctor`
  * run could ask for just this until now.
  */
 export function checkWorkflowsDrift(repoRoot: string): WorkflowsDriftReport {

package/packages/repo-controls/src/worktree-guard.ts

@@ -1,7 +1,7 @@
 /**
- * The `post-checkout` worktree-count backstop (STATUS.md item 2, adl-m3-items,
- * 2026-09-27 — "add a hook to detect existing worktrees and deny worktree
- * creation — maximum worktrees allowed is 3 including the main folder").
+ * The `post-checkout` worktree-count backstop (Tarun, 2026-09-27: "add a hook
+ * to detect existing worktrees and deny worktree creation — maximum worktrees
+ * allowed is 3 including the main folder"; see docs/operations/worktree-guard.md).
  *
  * Git has no pre-worktree hook: nothing runs BEFORE `git worktree add` creates
  * the new checkout. What git DOES run is `post-checkout`, and — per git's own