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

package/packages/fleet/src/repo-maintain.ts

@@ -22,12 +22,20 @@
  *      integration/main/master/develop and HEAD are never deleted, the KEEP
  *      most recent branches are kept, and only "[gone]" upstreams (-D) or
  *      branches merged into the baseline (-d) are deleted;
- *   4. `adl install --repo <repo>` -- the existing per-repo enrolment.
+ *   4. the stale-branch prune (only when `branchMaxAgeDays` is configured, from
+ *      the manifest's `config.repo_maintain.branch_max_age_days`): every local
+ *      branch whose TIP commit is older than that many days is deleted with
+ *      `git branch -D` -- never integration/main/master/develop, the checked-out
+ *      HEAD, or a branch checked out in any worktree. Each deletion is a
+ *      `WARN repo-maintain: <repo>: deleted stale branch <name> at <sha> (last
+ *      commit <date>)` line, which is how a deleted branch is recovered from the
+ *      log (`git branch <name> <sha>`); a dry run lists them without deleting;
+ *   5. `adl install --repo <repo>` -- the existing per-repo enrolment.
  *
  * This runs as the device administrator, never root (the caller,
  * bin/reconcile-host, drops privileges and `adl maintain --expect-user`
- * refuses otherwise). It never migrates enact-config.toml: a repo that has
- * both markers is a named failure.
+ * refuses otherwise). It never reads, migrates or modifies enact-config.toml:
+ * a repo may carry both markers, and adl-config.toml alone decides scope.
  *
  * Reporting: plain progress lines go to `out`; every warning and failure goes
  * to `err` as `WARN repo-maintain: ...` / `ERROR repo-maintain: ...` (the
@@ -42,9 +50,7 @@ import { NO_AGENT_IDENTITY_MESSAGE, resolveAgentIdentity } from '../../azdo/src/
 export const TCC_DENIED_MARKER = 'TCC denied'
 
 /** The file whose presence puts a repository in this step's scope. */
-export const MARKER = 'adl-config.toml'
-/** The retired marker; a repo with both is ambiguous and fails loud. */
-const LEGACY_MARKER = 'enact-config.toml'
+const MARKER = 'adl-config.toml'
 
 /** Branches fast-forwarded, in this order. */
 const SYNCED_BRANCHES = ['integration', 'main'] as const
@@ -65,6 +71,14 @@ export interface MaintainOptions {
   readonly keep?: number
   /** Report only: fetches, but never moves a ref, deletes a branch or runs install. */
   readonly dryRun?: boolean
+  /**
+   * Delete local branches whose tip commit is older than this many days (a
+   * positive whole number). Unset: no age-based deletion. The manifest's
+   * `config.repo_maintain.branch_max_age_days`, never an environment variable.
+   */
+  readonly branchMaxAgeDays?: number
+  /** The clock, injectable for tests. Default: the current time. */
+  readonly now?: () => Date
   /** Environment for identity resolution and every child. Default process.env. */
   readonly env?: NodeJS.ProcessEnv
   readonly out?: (line: string) => void
@@ -87,15 +101,18 @@ export function listFailureLines(root: string, error: unknown, executable: strin
   const code = (error as { code?: unknown } | null)?.code
   if (code === 'ENOTDIR') return [`${root}: ${message}`]
   const lines = [`${root}: cannot list: ${message}`]
-  if (code === 'EPERM') {
-    lines.push(
-      `${root}: ${TCC_DENIED_MARKER}: macOS privacy protection blocked ${executable}; ` +
-        `one-time fix: System Settings › Privacy & Security › Full Disk Access › + › add ${executable}`,
-    )
-  }
+  if (code === 'EPERM') lines.push(tccDeniedLine(root, executable))
   return lines
 }
 
+/** The one Full Disk Access hint, for a refused readdir and for a git child refused the same way. */
+function tccDeniedLine(path: string, executable: string): string {
+  return (
+    `${path}: ${TCC_DENIED_MARKER}: macOS privacy protection blocked ${executable}; ` +
+    `one-time fix: System Settings › Privacy & Security › Full Disk Access › + › add ${executable}`
+  )
+}
+
 interface GitResult {
   readonly ok: boolean
   readonly stdout: string
@@ -120,29 +137,6 @@ function isForbiddenAzurePipelinesPath(path: string): boolean {
   }
 }
 
-/** `packages/<name>/enact-config.toml` -- the per-package copies of the retired marker. */
-function legacyMarkers(repo: string): string[] {
-  const found: string[] = []
-  const tryStat = (relative: string): void => {
-    try {
-      if (statSync(join(repo, relative)).isFile()) found.push(relative)
-    } catch (error) {
-      if (errorCode(error) !== 'ENOENT' && errorCode(error) !== 'ENOTDIR') throw error
-    }
-  }
-  tryStat(LEGACY_MARKER)
-  let packages: Dirent[] = []
-  try {
-    packages = readdirSync(join(repo, 'packages'), { withFileTypes: true })
-  } catch (error) {
-    if (errorCode(error) !== 'ENOENT' && errorCode(error) !== 'ENOTDIR') throw error
-  }
-  for (const entry of packages.sort((a, b) => a.name.localeCompare(b.name))) {
-    if (entry.isDirectory()) tryStat(join('packages', entry.name, LEGACY_MARKER))
-  }
-  return found
-}
-
 export function maintainRepositories(options: MaintainOptions): MaintainResult {
   const env = options.env ?? process.env
   const keep = options.keep ?? DEFAULT_KEEP
@@ -165,6 +159,13 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     return { ok: result.status === 0, stdout: result.stdout, stderr: result.stderr ?? '' }
   }
 
+  const maxAgeDays = options.branchMaxAgeDays
+  if (maxAgeDays !== undefined && (!Number.isInteger(maxAgeDays) || maxAgeDays < 1)) {
+    fail(`branch max age must be a positive whole number of days: ${maxAgeDays}`, 'branch-max-age-days')
+    return { ok: false, repositories: 0, failures }
+  }
+  const now = options.now ?? ((): Date => new Date())
+
   const { location } = options
   if (!isAbsolute(location)) {
     fail(`location must be an absolute path: ${location}`, location)
@@ -196,7 +197,7 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
   }
   if (agent !== undefined) identityEnv = { ADL_AGENT_ID_AGENT: agent }
 
-  info(`start location=${location} keep=${keep} dry=${dry ? 1 : 0}`)
+  info(`start location=${location} keep=${keep} dry=${dry ? 1 : 0}${maxAgeDays === undefined ? '' : ` branch_max_age_days=${maxAgeDays}`}`)
 
   let entries: Dirent[]
   let locationReal: string
@@ -242,19 +243,10 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     }
     seen.add(real)
 
-    // 3. In scope from here on.
-    let legacy: string[]
-    try {
-      legacy = legacyMarkers(real)
-    } catch (error) {
-      fail(`${real}: cannot read: ${error instanceof Error ? error.message : String(error)}`, real)
-      continue
-    }
-    if (legacy.length > 0) {
-      fail(`${real}: duplicate markers: ${MARKER} and ${LEGACY_MARKER} (${legacy.join(', ')}); migrate or remove one`, real)
-      continue
-    }
-    if (!isGitToplevel(real)) {
+    // 3. In scope from here on. enact-config.toml may sit beside the marker; it is never read.
+    const toplevel = gitToplevelState(real)
+    if (toplevel === 'failed') continue
+    if (toplevel === 'not-toplevel') {
       warn(`${real}: ${MARKER} but not a git top-level; skipped`)
       continue
     }
@@ -265,13 +257,33 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
   info(`done (${repositories} repositories, ${failures.length} failed)`)
   return { ok: failures.length === 0, repositories, failures }
 
-  function isGitToplevel(directory: string): boolean {
+  /**
+   * 'not-toplevel' only on git's own "not a git repository" answer (exit 128) or
+   * a toplevel that is a different directory. Anything else (spawn error, other
+   * exit status, unresolvable toplevel) is reported here as a failure naming the
+   * directory, and the repo is not maintained: it may hide an in-scope repository.
+   */
+  function gitToplevelState(directory: string): 'toplevel' | 'not-toplevel' | 'failed' {
+    const command = 'git rev-parse --show-toplevel'
     const top = spawnSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: childEnv() })
-    if (top.error !== undefined || top.status !== 0) return false
+    if (top.error !== undefined) {
+      fail(`${directory}: cannot run ${command}: ${top.error.message}`, directory)
+      return 'failed'
+    }
+    const stderr = (top.stderr ?? '').trim()
+    if (top.status === 128 && stderr.includes('not a git repository')) return 'not-toplevel'
+    if (top.status !== 0) {
+      const shown = stderr.split('\n').slice(0, 3).join(' | ')
+      fail(`${directory}: ${command} exited ${top.status ?? `by signal ${top.signal}`}: ${shown}`, directory)
+      // git's "Operation not permitted" is TCC refusing the files to this job's responsible process (adl).
+      if (stderr.includes('Operation not permitted')) errOut(`ERROR repo-maintain: ${tccDeniedLine(directory, options.executable)}`)
+      return 'failed'
+    }
     try {
-      return realpathSync(top.stdout.trim()) === directory
-    } catch {
-      return false
+      return realpathSync(top.stdout.trim()) === directory ? 'toplevel' : 'not-toplevel'
+    } catch (error) {
+      fail(`${directory}: cannot resolve git toplevel ${top.stdout.trim()}: ${error instanceof Error ? error.message : String(error)}`, directory)
+      return 'failed'
     }
   }
 
@@ -312,7 +324,10 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     // 3. guarded prune.
     prune(repo, name, current)
 
-    // 4. the per-repo enrolment.
+    // 4. stale-branch prune: by the tip commit's age.
+    if (maxAgeDays !== undefined) pruneStale(repo, name, current, maxAgeDays)
+
+    // 5. the per-repo enrolment.
     const argv = [...options.install.leadingArgs, 'install', '--repo', repo]
     const shown = `adl install --repo ${repo}`
     if (dry) {
@@ -368,6 +383,27 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     }
   }
 
+  function pruneStale(repo: string, name: string, current: string, days: number): void {
+    const cutoff = now().getTime() / 1000 - days * 86_400
+    // %1f (unit separator) cannot appear in a ref name, unlike `|`.
+    const format = '%(refname:short)%1f%(objectname)%1f%(committerdate:unix)%1f%(worktreepath)'
+    for (const line of lines(git(repo, 'for-each-ref', 'refs/heads/', `--format=${format}`).stdout)) {
+      const [branch = '', sha = '', committed = '', worktree = ''] = line.split('\x1f')
+      if (branch === '' || PROTECTED.has(branch) || branch === current) continue
+      const tip = Number(committed)
+      if (!Number.isFinite(tip) || tip >= cutoff) continue
+      // A branch checked out in any worktree (the main one included) is in use.
+      if (worktree !== '') {
+        info(`${name}: kept stale branch ${branch} (checked out in ${worktree})`)
+        continue
+      }
+      const described = `stale branch ${branch} at ${sha} (last commit ${new Date(tip * 1000).toISOString().slice(0, 10)})`
+      if (dry) info(`${name}: [dry] would delete ${described}`)
+      else if (git(repo, 'branch', '-D', branch).ok) warn(`${name}: deleted ${described}`)
+      else warn(`${name}: could not delete ${described}`)
+    }
+  }
+
   function prune(repo: string, name: string, current: string): void {
     const base = baselineFor(repo)
     const keptRecent = new Set(

package/packages/fleet/src/scratch-reap.ts

@@ -34,12 +34,12 @@ import { defaultAgentFilePath, type FleetPlatform } from './default-agent-file.t
 // apps/cli/src/commands/mcp.ts's own cross-package import of packages/azdo:
 // this workspace has no node_modules/@adl/* symlinks without `bun install`.
 // packages/azdo/src/lib/agent-identity.ts is now THE one place the
-// default-agent file is READ from (STATUS.md 12p,
-// W1); this package's own default-agent-file.ts keeps only the WRITE side
-// (`reconcileDefaultAgentFile`) plus the path computation both sides need.
+// default-agent file is READ from; this package's own default-agent-file.ts
+// keeps only the WRITE side (`reconcileDefaultAgentFile`) plus the path
+// computation both sides need.
 import { NO_AGENT_IDENTITY_MESSAGE, resolveAgentIdentity } from '../../azdo/src/lib/agent-identity.ts'
 
-export type Mode = 'plan' | 'apply'
+type Mode = 'plan' | 'apply'
 
 export type GitResult = { ok: boolean; stdout: string; stderr: string }
 export type Git = (args: string[], cwd: string) => GitResult
@@ -530,7 +530,7 @@ function usage(): never {
   process.exit(2)
 }
 
-export function main(argv: string[]): number {
+function main(argv: string[]): number {
   const repos: string[] = []
   let mode: Mode = 'plan'
   let idleDays = 1

package/packages/fleet/src/vscode-settings.ts

@@ -21,7 +21,7 @@
  * format and default/named-profile directory shape, under its own
  * `Application Support`/`.config` folder name (`Cursor` instead of `Code`) —
  * this is the standard, well-known Cursor Application Support location
- * (docs/operations/research-2026-09-27-worktree-controls-per-surface.md confirms
+ * (docs/research/research-2026-09-27-worktree-controls-per-surface.md confirms
  * `~/.cursor/worktrees/<repo>/` for worktree storage and that
  * `cursor.worktreeMaxCount` lives in "the regular Cursor settings.json (user
  * or workspace scope, VS Code-style)", but does not separately spell out the
@@ -51,14 +51,14 @@ import { basename, dirname, isAbsolute, join } from 'node:path'
 export type VscodePlatform = 'mac' | 'linux'
 
 /** A managed setting's value: VS Code's two owned keys are boolean; Cursor's `worktreeMaxCount` is numeric. */
-export type SettingValue = boolean | number
+type SettingValue = boolean | number
 
 export const REQUIRED_VSCODE_SETTINGS = {
   'git.detectWorktrees': true,
   'scm.alwaysShowRepositories': true,
 } as const
 
-export const APPLY_TO_ALL_PROFILES_SETTING = 'workbench.settings.applyToAllProfiles'
+const APPLY_TO_ALL_PROFILES_SETTING = 'workbench.settings.applyToAllProfiles'
 
 /**
  * `cursor.worktreeMaxCount` — docs/operations/worktree-guard.md L0. Deployed as a
@@ -75,7 +75,7 @@ export const REQUIRED_CURSOR_SETTINGS = {
   'cursor.worktreeMaxCount': 3,
 } as const
 
-export interface EditorSettingsSpec {
+interface EditorSettingsSpec {
   readonly requiredSettings: Readonly<Record<string, SettingValue>>
   /** VS Code only: the setting id that collects a profile-wide apply-to-all list. Omit for editors with no confirmed equivalent (Cursor). */
   readonly applyToAllProfilesSetting?: string
@@ -90,7 +90,7 @@ const CURSOR_SPEC: EditorSettingsSpec = {
   requiredSettings: REQUIRED_CURSOR_SETTINGS,
 }
 
-export interface VscodeSettingsFileResult {
+interface VscodeSettingsFileResult {
   readonly path: string
   readonly changed: boolean
   readonly missing: boolean

package/packages/repo-controls/README.md

@@ -16,7 +16,8 @@ target repo (committed)                      adl (fleet-installed; see below)
 .workflows/hooks/commit-msg     ├─ sh stub ──▶    ├─ validates adl-config.toml [controls]
 .workflows/hooks/pre-push       │  exec           ├─ checks bash >= 4
 .workflows/hooks/post-commit    │                 └─ runs scripts/hooks/<name>
-.workflows/hooks/post-checkout ─┘
+.workflows/hooks/post-checkout  │
+.workflows/hooks/post-merge    ─┘
 adl-config.toml [controls]   (config, shared file — see below)   (package-owned script, config via env)
 .workflows/repo-controls.lock.json (hashes)
 local .git/config: core.hooksPath = .workflows/hooks
@@ -25,9 +26,9 @@ local .git/config: core.hooksPath = .workflows/hooks
 - **Stubs** are POSIX `sh`, contain no paths, and fail loudly (with the install
   command) when `adl` is not on `PATH` — never a silent skip. This package is
   folded into the `adl` binary's `repo controls` namespace
-  (docs/architecture/cli-design.md §6, STATUS.md item 10); it is never itself a
+  (docs/architecture/cli-design.md §6); it is never itself a
   standalone global command — hard cut, no `adl-repo-controls` compat shim
-  (adl-m3-finish item 1, 2026-09-27).
+  (2026-09-27).
 - **Bundled scripts** in `scripts/hooks/` are package-owned implementations.
   They originated in enact-m5; commit `20ec790` removed the former byte-copy
   tree and manifest when mechanism moved into this package. Their current
@@ -77,6 +78,53 @@ a release-configured pre-commit commits successfully with no network-capable
 binary on `PATH` at all, and pre-push blocks by name when the token mint
 fails and permits the push once it succeeds.
 
+## Git LFS chaining (`pre-push`, `post-checkout`, `post-commit`, `post-merge`)
+
+Installed repositories set `core.hooksPath=.workflows/hooks`, so git never runs
+the `.git/hooks/{pre-push,post-checkout,post-commit,post-merge}` that
+`git lfs install` writes. Before 2026-10-01 nothing in adl called 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 (live, enact-combined: a
+broken WebM pointer had to be deleted by hand). `runHook` (`src/hook.ts`) now
+chains each of those four hooks to `git lfs <hook> "$@"` (`src/lfs.ts`):
+
+- **Only when the repository uses LFS:** a `filter=lfs` attribute in any
+  `.gitattributes` (tracked or untracked, nested included) or in
+  `.git/info/attributes`, a `.lfsconfig`, or `lfs.*` in the repository's own git
+  config. A repository without LFS never calls `git lfs`.
+- **Fail loud, never skip:** LFS in use and no `git-lfs` on `PATH` is a hard
+  failure with the install command in the message; a failing `git lfs <hook>`
+  fails the hook (for `pre-push`, the push). A FAIL row is also written to the
+  hook log, because the bundled script has already logged its PASS by then.
+- **`pre-push` order and stdin:** git writes the pushed ref lines once. `runHook`
+  reads them once and feeds the same bytes to the bundled script (branch rules)
+  and to `git lfs pre-push`. The LFS upload is the LAST step, after every adl
+  check passed, so a refused push uploads nothing. `post-merge` is a new hook
+  (`HOOK_NAMES`) whose only job is this chain; `doctor` therefore reports
+  `hook:post-merge`, and an already-installed repository needs `adl repo
+  controls install --repo .` once to project the stub.
+- **Credentials — one boundary, no second path.** `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 (`bin/git-ado`, the
+  two `exec env ... GIT_CONFIG_COUNT=` blocks); git passes its environment to
+  the hook. `runBundled` strips every `GIT_CONFIG_*` (`childEnv`) so adl's own
+  checks never hold the token, which is why the chain is TypeScript and not
+  bash: `runHook` still has the unstripped environment, and the one
+  `git lfs` spawn (`spawnGitLfs`) is the only child given it. git-lfs therefore
+  authenticates with exactly the pairs the parent `git push` had: same
+  mechanism, no second token mint, never the human's credential helper.
+  `tests/lfs-credential-boundary.test.ts` is the proof (real git-lfs, a local
+  LFS endpoint that requires the Bearer token and answers 401 otherwise, a
+  credential helper that records every call): every request carried the header,
+  the helper was never called, and with the header absent the helper IS called
+  (the control that makes the first claim falsifiable).
+- **Explicit `git lfs push|pull|fetch` for agents** was refused in `bin/git-ado`
+  until that proof existed; it now takes the ordinary agent path. The refusal
+  must come back if `lfs-credential-boundary.test.ts` ever goes red. No agent-hooks
+  rule mentions LFS, so `git push` -> hook -> `git lfs pre-push` is not a
+  command an agent types and is not intercepted by any rule.
+
 ## Worktree-count backstop (`post-checkout`)
 
 `MAX_WORKTREES` (`src/constants.ts`) is `3` — a repository may have at most 3
@@ -144,7 +192,7 @@ or a `Task`/`Agent` launch with `isolation: "worktree"`) — see
 
 ### Why bun (and not node)
 
-This package is never distributed standalone (adl-m3-finish item 1/2, 2026-09-27):
+This package is never distributed standalone (since 2026-09-27):
 `adl repo controls <command>` folds it into the one `adl` binary
 (docs/architecture/cli-design.md §6), which the fleet installs via `bin/reconcile`'s
 `bun-compile` manager; `apps/cli/src/commands/repo-controls.ts` resolves this
@@ -186,7 +234,7 @@ centralization are documented in
 adl-repo-controls install   --repo <path> [--dry-run]
 adl-repo-controls uninstall --repo <path> [--dry-run]
 adl-repo-controls doctor    --repo <path> [--json]
-adl-repo-controls hook <pre-commit|commit-msg|pre-push|post-commit> [git hook args]
+adl-repo-controls hook <pre-commit|commit-msg|pre-push|post-commit|post-checkout|post-merge> [git hook args]
 adl-repo-controls log <hook-name> <reason> [context] [message]   (internal — called by the bundled hooks)
 adl-repo-controls promote --repo <path>
 adl-repo-controls run <azdo-push|coverage|repo-hygiene|validate-pr-metadata> --repo <path> [-- args]
@@ -229,21 +277,56 @@ merge into `integration`) runs.
 **doctor** is read-only and exits 1 on any failure: bash >= 4, bun, binary on
 PATH, the bundled compliance package present at its packaged path, repository
 root, `[controls]` config validity, (warning) `coverage/coverage-summary.json`
-exists whenever `pre_push.coverage_ratchet` is enabled, `[controls.compliance]` config
-validity, `uv` on PATH (only checked once `[controls.compliance].enabled` is non-empty;
-otherwise reported ok unconditionally, same off-by-default posture as the
-coverage-summary check), (warning only, same conditioning) `ast-grep` on PATH,
-lock, each stub (present, unedited, executable), `core.hooksPath`, `.gitignore`
-lines, and (warning) lock version skew. When `[controls.release]` is declared,
-it also derives the configured `origin` remote, loads the validated canonical
-Agent Vault file before reading Azure DevOps, and records separate fail-closed receipts for the HTTPS handle,
-required owner reviewer, minimum-review reset, and (only when one is present) build policy.
+exists whenever `pre_push.coverage_ratchet` is enabled (`coverage_ratchet`
+defaults ON; the gate is a no-op until the file lands, so this is informational
+rather than blocking), (warning) `pre_push.coverage_produce` enabled with no
+`[controls.coverage].produce_push` declared (the push gate fails loud there, so
+doctor names it first), `[controls.compliance]` config validity, `uv` on PATH
+(only checked once `[controls.compliance].enabled` is non-empty; otherwise
+reported ok unconditionally, same on-by-default posture as the coverage-summary
+check), (warning only, same conditioning) `ast-grep` on PATH, lock, each stub
+(present, unedited, executable), `core.hooksPath`, `.gitignore` lines, and
+(warning) lock version skew. When `[controls.release]` is declared, it also
+derives the configured `origin` remote, loads the validated canonical Agent
+Vault file before reading Azure DevOps, and records separate fail-closed
+receipts for the HTTPS handle, required owner reviewer, minimum-review reset,
+and (only when one is present) build policy.
 
 **run** executes a bundled enact-m5 tool against the repository with the config
 exported: `azdo-push` (Azure DevOps push with push lock + behind-origin refusal),
 `coverage <check-push|prewarm-push|status|unlock|...>`, `repo-hygiene` (CI
 entrypoint), `validate-pr-metadata` (Azure PR title/description policy).
 
+#### azdo-push: one credential boundary
+
+`azdo-push` mints and injects **no credential** (Tarun, 2026-10-01). Its git
+children run through the managed front controller (`/usr/local/bin/git` ->
+`bin/git-ado`), the only place a token is minted and a header added. What
+`azdo-push` does contribute is `ADL_AGENT_ID_AGENT=<resolved agent>` on every
+git spawn (so the controller mints for the right agent) and the removal of any
+inherited `ADL_HUMAN_AZDO`. It refuses, before any network call, when no agent
+identity resolves, and when the `git` on `PATH` does not carry the
+`# Managed by adl global-tools.` marker (a plain git would fall to the human
+credential helper).
+
+**Verify on the wire** that a request carries exactly one `Authorization`
+header. Git redacts the value by default (`GIT_TRACE_REDACT`, on unless set to
+`0` -- never set it), so the trace is safe to read and to paste:
+
+```
+GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 git ls-remote origin HEAD 2>&1 \
+  | rg '=> Send header: (GET|POST|Authorization)'
+```
+
+Expect each `GET`/`POST` line to be followed by exactly one
+`=> Send header: Authorization: Bearer <redacted>` line. Count them with
+`... | rg -c '=> Send header: Authorization'` -- 1 for the single request of
+`ls-remote`. Two per request means a second credential path is back (the old
+behaviour was a global `http.extraheader` from `azdo-push` plus git-ado's own
+URL-scoped header). `ls-remote` is read-only; to trace the push path itself, run
+`GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 adl repo controls azdo-push` on a
+branch you mean to push.
+
 **run compliance** runs the bundled `adl-compliance` Python engine (via `uv`)
 against the repository. `--root <repo>` is always injected first from `--repo`;
 once `[controls.compliance].enabled` is non-empty, `--only <the enabled list, comma-joined>`
@@ -285,41 +368,47 @@ an inline table is one attribute, because editing inside one means rewriting byt
 you own. Nothing is parsed and re-serialized; text is spliced into the table's span.
 
 `[controls]` is strictly validated: unknown keys and wrong types are errors. An
-**absent** optional key is its documented default, never an error.
+**absent** key takes its documented default, never an error. Most gates default
+ON; the matching `[controls.<gate>]` keys are what configure them. A gate whose
+wrapper is ON but whose configuration is missing is a no-op at hook time and a
+*warning* at `doctor` time — informational, never blocking.
 
 | Key | Seeded by install | Default when absent | enact-m5 | Effect |
 |---|---|---|---|---|
 | `branches.protected` | yes | *required* | `["main", "integration"]` | pre-push refuses while on these branches |
 | `branches.prefixes` | yes | *required* | `["feat", "fix", "docs", "chore"]` | pre-push / azdo-push branch pattern `<prefix>/<kebab>` |
 | `pre_push.remote` | yes | *required* | `"origin"` | remote azdo-push pushes to and reads status from |
-| `pre_commit.biome` | no | `false` | `true` | Biome format+lint on the staged index snapshot |
-| `pre_commit.staged_coverage` | no | `false` | `true` | enact-m5-only staged coverage measurement |
-| `pre_commit.doc_freshness` | no | `false` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h |
-| `pre_push.coverage_ratchet` | no | `false` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress |
-| `pre_push.findings_ratchet` | no | `false` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor |
+| `pre_commit.staged_coverage` | no | `true` | `true` | enact-m5-only staged coverage measurement (no-op until `[controls.coverage].produce` is declared) |
+| `pre_commit.doc_freshness` | no | `true` | opt in | a staged `docs/` or `plans/` `.md` carries a `last_update` stamped within 5h (no-op when no docs are staged) |
+| `pre_commit.compliance` | no | `true` | `true` | staged adl-compliance gates (no-op until `[controls.compliance].enabled` is non-empty) |
+| `pre_push.coverage_ratchet` | no | `true` | `true` | per outgoing commit, `coverage/coverage-summary.json` must exist and not regress (no-op until the file lands) |
+| `pre_push.coverage_produce` | no | `false` | opt in | run the coverage MEASUREMENT at push via `[controls.coverage].produce_push` (fails the push when armed with no command declared) |
+| `pre_push.findings_ratchet` | no | `true` | opt in | per outgoing commit, every declared static-analysis counter's findings must not exceed the committed floor (no-op until `[controls.findings].counters` is declared and the floor file lands) |
 | `pre_push.static_checks` | no | `[]` | tsc, knip, svelte-check | `{ label, run }` commands run on an export of HEAD, pass cached per tree OID |
 | `release.source` | no | `""` | `"integration"` | source branch for the managed promotion PR; no branch pair is guessed |
 | `release.target` | no | `""` | `"main"` | target branch for the managed promotion PR |
 | `release.merge_strategy` | no | `"squash"` | `"no-fast-forward"` | one of `squash`, `rebase`, `rebase-merge`, or `no-fast-forward` — sent to Azure DevOps as the matching wire value (`squash`, `rebase`, `rebaseMerge`, `noFastForward`) |
-| `release.pre_bump` | no | `[]` | — | ordered, repository-relative script paths `version-bump.sh` runs from the repo root before the bump commit (the CI pipeline's Bump stage, on the PR's source branch) |
-
-### Release scripts — Bump and Guard (Tarun, 2026-09-30)
-
-One clean hard cutover to three pipelines (CI on PRs into `integration`,
-Promote on `integration`, CD on `main`; `docs/architecture/cli-design.md` §6a).
-Two managed scripts run in the CI pipeline, and neither ever pushes to
-`integration`:
-
-- **`.workflows/version-bump.sh --file package.json --pr-source <source> --base
-  integration --push`** (Bump stage) sets the PR's SOURCE branch to
-  `integration`'s version + 1 patch, running `release.pre_bump` scripts in the
-  same commit, and pushes it (a plain push as the build service, never an
-  agent identity, never force). It refuses a source that does not contain
-  `integration`'s tip. The old `--integration` mode is gone: it is an unknown
-  argument.
-- **`.workflows/reconcile-guard.sh`** (Guard stage) fails, printing the
-  reconcile command (`git pull origin integration && git push`), unless the
-  source contains `integration`'s tip and is at `integration` + 1.
+| `release.pre_bump` | no | `[]` | — | ordered, repository-relative script paths `version-bump.sh` runs from the repo root before the bump commit (the Promote pipeline's Bump stage, on the checkout of the `integration` commit that triggered it) |
+
+### Release scripts — Guard and Bump (Tarun, 2026-09-30; bump moved 2026-10-01)
+
+Three pipelines (CI on PRs into `integration`, Promote on `integration`, CD on
+`main`; `docs/architecture/cli-design.md` §6a). Two managed scripts:
+
+- **`.workflows/reconcile-guard.sh --pr-source <source> --base integration`**
+  (CI pipeline, Guard stage) is read-only and fails, printing the reconcile
+  command (`git pull origin integration, then push`), unless the source
+  contains `integration`'s tip. It checks no version: PR CI bumps nothing,
+  because a PR's build-validation policy ignores `[skip ci]`.
+- **`.workflows/version-bump.sh --file package.json --integration --push`**
+  (Promote pipeline, Bump stage) sets the manifest to the checked-out
+  `integration` commit's version + 1 patch, runs `release.pre_bump` scripts in
+  the same commit, commits `chore: bump version A to B [skip ci]` and pushes
+  `HEAD:refs/heads/integration` (a plain fast-forward as the build service,
+  which needs Contribute and "Bypass policies when pushing" there; never an
+  agent identity, never force). If `integration` moved since the checkout the
+  push is rejected and the script fails loud; the next merge's run bumps. The
+  old `--pr-source` mode is gone: it is an unknown argument.
 
 ### `release.pre_bump` — multi-language version bumps
 
@@ -395,10 +484,9 @@ sed -i.bak -E "s/^const Version = \".*\"/const Version = \"${ADL_NEXT_VERSION}\"
 rm -f "${file}.bak"
 ```
 
-`install` copies four package-owned standalone CI assets byte-for-byte:
+`install` copies three package-owned standalone CI assets byte-for-byte:
 
 - `.workflows/promote.ts`
-- `.workflows/scripts/enable-integration-auto-complete.mjs`
 - `.workflows/version-bump.sh`
 - `.workflows/reconcile-guard.sh`
 
@@ -469,6 +557,13 @@ Note: with `coverage_ratchet = true` every pushed commit and its parent must
 contain `coverage/coverage-summary.json` (Istanbul json-summary); commit a
 baseline first or set it to `false`.
 
+Note: with `coverage_produce = true` the coverage MEASUREMENT runs at push too,
+through `[controls.coverage].produce_push` — measurement at push, grading at
+push, so commits stay fast. `produce_push` is the push-appropriate command: it
+runs against immutable HEAD before the push, so a check-mode run that never
+mutates the index is the shape. Armed with no command declared, the gate fails
+the push by name — a step that measures nothing is not a pass.
+
 Note: with `findings_ratchet = true`, `[controls.findings]` says where the
 floor lives (`floor`, default `compliance/ratchets/static-analysis-findings.yaml`)
 and `[controls.findings.counters]` names the repository's own static-analysis
@@ -512,6 +607,9 @@ non-empty string.
 | `enabled` | `[]` | gate ids (`RST-001`) or `domain.name` addresses (`rust.acp-boundary`) to grade; empty = installed, nothing runs |
 | `registry` | `"default"` | forward-compatible; today both values point at the same packaged registry YAML |
 | `[controls.compliance.trees]` | `{}` (no entries) | per-key path overrides; a key absent here keeps the packaged (source-shaped) default for that key |
+| `[controls.compliance.limits]` | absent (engine defaults) | per-repository engine limits, strictly validated. `scripts_direct_files` (positive integer) replaces LAY-014's default of 15 direct files per scripts directory and reaches the engine as `--declare scripts-direct-files=N`; a value the engine cannot read as a positive integer is could-not-run, never a fall back to 15. The depth limit is not configurable. `open_gaps` and `open_plans` (each a positive integer) replace LAY-016's default cap of 10 open gaps and 10 open plans, independently, and reach the engine as `--declare open-gaps=N` / `--declare open-plans=N`; the same could-not-run rule applies to each, and a finding names the effective cap as `N open gaps, cap is M`. The engine default stays 10: a repository declares today's measured count and ratchets it down |
+| `[controls.compliance.markdown]` | absent (no extra Markdown roots) | extra Markdown roots for LAY-006 (`layout.markdown-trees`), strictly validated. `roots` is an array of repository-relative directories whose Markdown is site or application content rather than documentation (an Astro site's `src/content/**/*.md`); LAY-006 admits `.md` and `.mdx` beneath each, in addition to the docs trees, so a declared root only ever widens the allowlist and absent is the stricter grade. Reaches the engine as one `--declare markdown-roots=a,b`. An entry that is empty, absolute, contains `,` or `=`, or has a `.`, `..` or empty path segment is rejected when the config loads (a trailing `/` is dropped); the engine refuses the same values as could-not-run (exit 2) |
+| `[controls.compliance.lockfiles]` | absent (REP-002 keeps its tree-derived scope) | exactly which manifest and lockfile paths REP-002 (`repository.lockfile-integrity`) scans and grades, strictly validated. Four arrays: `bun_manifests` / `bun_lockfiles` and `cargo_manifests` / `cargo_lockfiles`. A manifest entry is a repository-relative path or glob ending in `package.json` (`Cargo.toml`), such as `package.json` or `apps/*/package.json`; a lockfile entry is a literal path (a missing one is reported by name). An ecosystem is declared as a pair, and a declared pair replaces that ecosystem's default (`<typescript>/package.json` + `<typescript>/bun.lock`, the `<rust>` pair) in both what selects the gate and what it grades; an undeclared ecosystem is unchanged. Reaches the engine as `--declare bun-manifests=a,b`, `bun-lockfiles=`, `cargo-manifests=`, `cargo-lockfiles=` (a list is omitted when empty); a declared manifest that matches no file is could-not-run naming it. An entry that is empty, absolute, duplicated, contains `,` `=` `\` `<` `>` `{` `}`, starts with `!`, has a `.`, `..` or empty path segment, ends in the wrong file name, or (for a lockfile) is a glob, an ecosystem with only one of its two lists, and a `REP-002:bun_lock` / `cargo_lock` / `cargo_manifest` / `workspace` input beside the pair it supersedes are all rejected when the config loads; the engine refuses the same values as could-not-run (exit 2) |
 
 ### Registry curation
 
@@ -534,5 +632,5 @@ bun test --coverage     # 100% lines + functions gate (bunfig.toml)
 ```
 
 Tests run real git in temporary repositories under `.scratchpad/test-tmp/`
-(gitignored), exercising the installed stubs end to end. CI:
-`azure-pipelines.yml` (publishing present but disabled).
+(gitignored), exercising the installed stubs end to end. CI runs them through
+the repository's root pipelines under `workflows/pipelines/`.

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

@@ -90,7 +90,7 @@ interface PullRequestList {
   value?: PullRequest[]
 }
 
-export interface PolicyScope {
+interface PolicyScope {
   repositoryId?: string
   refName?: string
   matchKind?: string
@@ -111,12 +111,12 @@ export interface PolicyConfiguration {
   }
 }
 
-export interface PolicyConfigurationList {
+interface PolicyConfigurationList {
   value?: PolicyConfiguration[]
 }
 
-export const MINIMUM_REVIEWER_POLICY_TYPE = 'fa4e907d-c16b-4a4c-9dfa-4906e5d171dd'
-export const BUILD_POLICY_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241'
+const MINIMUM_REVIEWER_POLICY_TYPE = 'fa4e907d-c16b-4a4c-9dfa-4906e5d171dd'
+const BUILD_POLICY_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241'
 
 /** `release: promote <source> to <target>` — derived, never declared. */
 export function promotionTitle(source: string, target: string): string {