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

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

@@ -0,0 +1,403 @@
+/**
+ * Repository maintenance: the repository step of `adl reconcile`
+ * (`adl maintain --location DIR`). It replaces the retired git-maintain
+ * LaunchAgent (2026-09-30, Tarun: "one binary controlling everything").
+ *
+ * Scope is exactly ONE directory, the host's `repo_location` from the fleet
+ * manifest, and only its IMMEDIATE children that carry `adl-config.toml` and
+ * are git top-levels. Nothing else is ever touched or mentioned: every child
+ * is resolved (symlinks followed) and must still be a direct child of the
+ * location BEFORE any file inside it is stat'ed, so a symlink can never make
+ * this step read, fetch into or install into anything outside the location.
+ * A directory without the marker is not this step's business at all.
+ *
+ * Per repository, in order:
+ *   1. `git fetch origin --prune`;
+ *   2. fast-forward the local `integration` and `main` (whichever exist on
+ *      both sides) -- only ever a true fast-forward. A branch checked out in a
+ *      worktree (this one or another) is moved only when that worktree is
+ *      clean (`merge --ff-only`), else WARN and skip; a branch checked out
+ *      nowhere is moved with a compare-and-swap `update-ref`;
+ *   3. the safe-only local branch prune (ported from git-maintain): protected
+ *      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.
+ *
+ * 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.
+ *
+ * Reporting: plain progress lines go to `out`; every warning and failure goes
+ * to `err` as `WARN repo-maintain: ...` / `ERROR repo-maintain: ...` (the
+ * level word `adl logs` filters on). A failure never stops the other
+ * repositories; the run returns `ok: false` when any occurred.
+ */
+import { spawnSync } from 'node:child_process'
+import { readdirSync, realpathSync, statSync, type Dirent } from 'node:fs'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+import { NO_AGENT_IDENTITY_MESSAGE, resolveAgentIdentity } from '../../azdo/src/lib/agent-identity.ts'
+
+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'
+
+/** Branches fast-forwarded, in this order. */
+const SYNCED_BRANCHES = ['integration', 'main'] as const
+const PROTECTED = new Set(['integration', 'main', 'master', 'develop'])
+const DEFAULT_KEEP = 3
+
+/** Case-insensitive, by name and by realpath: never an Azure Pipelines agent install. */
+const FORBIDDEN_PATH_PATTERN = /azagent|vsts\.agent/i
+
+export interface MaintainOptions {
+  /** Absolute path of the host's `repo_location`. */
+  readonly location: string
+  /** The running adl binary, named in the Full Disk Access remedy. */
+  readonly executable: string
+  /** How to run `adl`: `<command> <...leadingArgs> install --repo <repo>`. */
+  readonly install: { readonly command: string; readonly leadingArgs: readonly string[] }
+  /** Most recent non-protected local branches kept by the prune. Default 3. */
+  readonly keep?: number
+  /** Report only: fetches, but never moves a ref, deletes a branch or runs install. */
+  readonly dryRun?: boolean
+  /** Environment for identity resolution and every child. Default process.env. */
+  readonly env?: NodeJS.ProcessEnv
+  readonly out?: (line: string) => void
+  readonly err?: (line: string) => void
+}
+
+export interface MaintainResult {
+  readonly ok: boolean
+  readonly repositories: number
+  readonly failures: readonly string[]
+}
+
+/**
+ * Lines explaining why `root` could not be listed. EPERM from readdir is what
+ * macOS privacy protection (TCC) returns -- plain permission bits give EACCES
+ * -- so it names the exact binary the owner must grant Full Disk Access.
+ */
+export function listFailureLines(root: string, error: unknown, executable: string): readonly string[] {
+  const message = error instanceof Error ? error.message : String(error)
+  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}`,
+    )
+  }
+  return lines
+}
+
+interface GitResult {
+  readonly ok: boolean
+  readonly stdout: string
+  readonly stderr: string
+}
+
+function errorCode(error: unknown): string | undefined {
+  const code = (error as { code?: unknown } | null)?.code
+  return typeof code === 'string' ? code : undefined
+}
+
+function lines(output: string): string[] {
+  return output.split('\n').filter((line) => line.length > 0)
+}
+
+function isForbiddenAzurePipelinesPath(path: string): boolean {
+  if (FORBIDDEN_PATH_PATTERN.test(path)) return true
+  try {
+    return FORBIDDEN_PATH_PATTERN.test(realpathSync(path))
+  } catch {
+    return false
+  }
+}
+
+/** `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
+  const dry = options.dryRun ?? false
+  const out = options.out ?? ((line: string) => void process.stdout.write(`${line}\n`))
+  const errOut = options.err ?? ((line: string) => void process.stderr.write(`${line}\n`))
+  const info = (message: string): void => out(`repo-maintain: ${message}`)
+  const warn = (message: string): void => errOut(`WARN repo-maintain: ${message}`)
+  const failures: string[] = []
+  const fail = (message: string, subject: string): void => {
+    errOut(`ERROR repo-maintain: ${message}`)
+    failures.push(subject)
+  }
+
+  let identityEnv: NodeJS.ProcessEnv = {}
+  const childEnv = (): NodeJS.ProcessEnv => ({ ...env, ...identityEnv })
+  const git = (repo: string, ...args: string[]): GitResult => {
+    const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', env: childEnv() })
+    if (result.error !== undefined) throw result.error
+    return { ok: result.status === 0, stdout: result.stdout, stderr: result.stderr ?? '' }
+  }
+
+  const { location } = options
+  if (!isAbsolute(location)) {
+    fail(`location must be an absolute path: ${location}`, location)
+    return { ok: false, repositories: 0, failures }
+  }
+  if (isForbiddenAzurePipelinesPath(location)) {
+    fail(`${location}: refusing an Azure Pipelines agent path`, location)
+    return { ok: false, repositories: 0, failures }
+  }
+
+  // Resolve the Azure DevOps agent identity ONCE, before touching any repo
+  // (F6): this job runs with no TTY and no ADL_AGENT_ID_AGENT, and bin/git-ado
+  // fails closed without one. A real resolution error is fatal; "nothing
+  // configured" is only fatal for Azure DevOps remotes, which are skipped
+  // loudly below rather than fetched with no identity.
+  let agent: string | undefined
+  try {
+    agent = resolveAgentIdentity(env).agent
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (message !== NO_AGENT_IDENTITY_MESSAGE) {
+      fail(`cannot resolve an Azure DevOps agent identity: ${message}`, 'identity')
+      return { ok: false, repositories: 0, failures }
+    }
+    warn(
+      'no Azure DevOps agent identity resolved (no ADL_AGENT_ID_AGENT, no default-agent file): ' +
+        'Azure DevOps repos will be skipped this run, not silently fetched with no identity',
+    )
+  }
+  if (agent !== undefined) identityEnv = { ADL_AGENT_ID_AGENT: agent }
+
+  info(`start location=${location} keep=${keep} dry=${dry ? 1 : 0}`)
+
+  let entries: Dirent[]
+  let locationReal: string
+  try {
+    locationReal = realpathSync(location)
+    entries = readdirSync(locationReal, { withFileTypes: true })
+  } catch (error) {
+    for (const line of listFailureLines(location, error, options.executable)) errOut(`ERROR repo-maintain: ${line}`)
+    failures.push(location)
+    return { ok: false, repositories: 0, failures }
+  }
+
+  const seen = new Set<string>()
+  let repositories = 0
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    // Files and other non-directories (a symlink is the one kind resolved below).
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    const candidate = join(locationReal, entry.name)
+
+    // 1. Resolve, then scope-check, BEFORE looking inside. A broken symlink
+    //    points nowhere and so carries no marker; any other failure to
+    //    resolve is reported, because it may hide an in-scope repository.
+    let real: string
+    try {
+      real = realpathSync(candidate)
+    } catch (error) {
+      if (errorCode(error) === 'ENOENT') continue
+      fail(`${candidate}: cannot resolve: ${error instanceof Error ? error.message : String(error)}`, candidate)
+      continue
+    }
+    if (dirname(real) !== locationReal) continue
+    if (seen.has(real)) continue
+
+    // 2. The marker decides scope. Not there: not this step's business, and
+    //    silent. Anything other than "not there" is a named failure.
+    try {
+      if (!statSync(join(real, MARKER)).isFile()) continue
+    } catch (error) {
+      const code = errorCode(error)
+      if (code === 'ENOENT' || code === 'ENOTDIR') continue
+      fail(`${real}: cannot read ${MARKER}: ${error instanceof Error ? error.message : String(error)}`, real)
+      continue
+    }
+    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)) {
+      warn(`${real}: ${MARKER} but not a git top-level; skipped`)
+      continue
+    }
+    repositories += 1
+    maintainRepo(real)
+  }
+
+  info(`done (${repositories} repositories, ${failures.length} failed)`)
+  return { ok: failures.length === 0, repositories, failures }
+
+  function isGitToplevel(directory: string): boolean {
+    const top = spawnSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: childEnv() })
+    if (top.error !== undefined || top.status !== 0) return false
+    try {
+      return realpathSync(top.stdout.trim()) === directory
+    } catch {
+      return false
+    }
+  }
+
+  function baselineFor(repo: string): string {
+    for (const branch of ['integration', 'main', 'master']) {
+      if (git(repo, 'show-ref', '--verify', '--quiet', `refs/remotes/origin/${branch}`).ok) return branch
+    }
+    return ''
+  }
+
+  function maintainRepo(repo: string): void {
+    const name = basename(repo)
+
+    // An Azure DevOps remote needs an agent identity; without one the fetch
+    // would only fail (or be refused) far from the cause.
+    if (agent === undefined) {
+      const url = git(repo, 'remote', 'get-url', 'origin')
+      if (url.ok && /^https:\/\/[^/]*dev\.azure\.com\//.test(url.stdout.trim())) {
+        fail(`${name}: skipping: Azure DevOps remote but no agent identity resolved (see the start-of-run warning)`, repo)
+        return
+      }
+    }
+
+    const head = git(repo, 'symbolic-ref', '--short', '-q', 'HEAD')
+    const current = head.ok ? head.stdout.trim() : '(detached)'
+
+    // 1. fetch + prune. Report what git SAID, never a guess at what it meant.
+    const fetched = git(repo, 'fetch', 'origin', '--prune', '--quiet')
+    if (!fetched.ok) {
+      const reason = fetched.stderr.trim().split('\n').pop() || 'no stderr from git'
+      fail(`${name}: fetch failed, skipping repo: ${reason}`, repo)
+      return
+    }
+
+    // 2. fast-forward integration and main.
+    for (const branch of SYNCED_BRANCHES) fastForward(repo, name, branch)
+
+    // 3. guarded prune.
+    prune(repo, name, current)
+
+    // 4. the per-repo enrolment.
+    const argv = [...options.install.leadingArgs, 'install', '--repo', repo]
+    const shown = `adl install --repo ${repo}`
+    if (dry) {
+      info(`${name}: [dry] would run ${shown}`)
+      return
+    }
+    const result = spawnSync(options.install.command, argv, { encoding: 'utf8', env: childEnv() })
+    if (result.error !== undefined) {
+      fail(`${name}: could not run ${options.install.command}: ${result.error.message}`, repo)
+    } else if (result.status !== 0) {
+      fail(`${name}: ${shown} exited ${result.status}: ${(result.stderr ?? '').trim()}`, repo)
+    } else {
+      info(`${name}: ${shown}: ok`)
+    }
+  }
+
+  function fastForward(repo: string, name: string, branch: string): void {
+    const local = `refs/heads/${branch}`
+    const remote = `refs/remotes/origin/${branch}`
+    if (!git(repo, 'show-ref', '--verify', '--quiet', local).ok) return
+    if (!git(repo, 'show-ref', '--verify', '--quiet', remote).ok) return
+    const localSha = git(repo, 'rev-parse', local).stdout.trim()
+    const remoteSha = git(repo, 'rev-parse', remote).stdout.trim()
+    if (localSha === remoteSha) return
+    if (!git(repo, 'merge-base', '--is-ancestor', local, remote).ok) {
+      // Not a fast-forward (local has commits origin lacks). Never moved.
+      if (!git(repo, 'merge-base', '--is-ancestor', remote, local).ok) {
+        warn(`${name}: ${branch} has diverged from origin/${branch}; not moved`)
+      }
+      return
+    }
+    // Where is it checked out, if anywhere? (`%(worktreepath)` covers this
+    // worktree and every linked one.)
+    const worktree = git(repo, 'for-each-ref', local, '--format=%(worktreepath)').stdout.trim()
+    if (worktree !== '') {
+      if (git(worktree, 'status', '--porcelain').stdout.trim() !== '') {
+        warn(`${name}: ${branch} checked out but dirty; skipped fast-forward`)
+      } else if (dry) {
+        info(`${name}: [dry] would fast-forward ${branch} (checked out)`)
+      } else if (git(worktree, 'merge', '--ff-only', `origin/${branch}`, '--quiet').ok) {
+        info(`${name}: ${branch} fast-forwarded (checked out)`)
+      } else {
+        fail(`${name}: ${branch} could not be fast-forwarded (checked out)`, repo)
+      }
+      return
+    }
+    if (dry) {
+      info(`${name}: [dry] would fast-forward ${branch} (background)`)
+    } else if (git(repo, 'update-ref', '-m', `adl maintain: fast-forward ${branch}`, local, remoteSha, localSha).ok) {
+      info(`${name}: ${branch} ref fast-forwarded (background)`)
+    } else {
+      fail(`${name}: ${branch} ref could not be fast-forwarded (background)`, repo)
+    }
+  }
+
+  function prune(repo: string, name: string, current: string): void {
+    const base = baselineFor(repo)
+    const keptRecent = new Set(
+      lines(git(repo, 'for-each-ref', '--sort=-committerdate', 'refs/heads/', '--format=%(refname:short)').stdout)
+        .filter((branch) => !PROTECTED.has(branch) && branch !== current)
+        .slice(0, keep),
+    )
+    const merged =
+      base === ''
+        ? new Set<string>()
+        : new Set(lines(git(repo, 'branch', '--merged', `origin/${base}`, '--format=%(refname:short)').stdout))
+
+    for (const line of lines(git(repo, 'for-each-ref', 'refs/heads/', '--format=%(refname:short)|%(upstream:track)').stdout)) {
+      const separator = line.indexOf('|')
+      const branch = line.slice(0, separator)
+      const track = line.slice(separator + 1)
+      if (PROTECTED.has(branch) || branch === current || keptRecent.has(branch)) continue
+
+      if (track.includes('[gone]')) {
+        // remote branch deleted after merge -> proven safe
+        if (dry) info(`${name}: [dry] would delete (upstream gone) ${branch}`)
+        else if (git(repo, 'branch', '-D', branch).ok) info(`${name}: deleted (upstream gone) ${branch}`)
+        else warn(`${name}: could not delete (upstream gone) ${branch}`)
+      } else if (base !== '' && merged.has(branch)) {
+        if (dry) info(`${name}: [dry] would delete (merged into ${base}) ${branch}`)
+        else if (git(repo, 'branch', '-d', branch).ok) info(`${name}: deleted (merged into ${base}) ${branch}`)
+        else info(`${name}: kept (${branch}: -d refused)`)
+      } else {
+        info(`${name}: kept (unconfirmed merged) ${branch}`)
+      }
+    }
+  }
+}

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

@@ -20,7 +20,7 @@
  * `git worktree prune` is not a substitute for any of this. It only clears
  * metadata for worktrees whose directory has ALREADY been deleted.
  *
- * Invoked by reconcile's six-hourly pass (bin/reconcile), gated on
+ * Invoked by reconcile's 12-hourly pass (bin/reconcile), gated on
  * config.scratch_reap.enabled and the per-device scratch_repos list. Devices
  * that declare no scratch_repos are never touched — a developer machine's
  * scratch worktrees are working state, not fleet state.

package/packages/repo-controls/README.md

@@ -59,6 +59,11 @@ have needed):
   evidence blocks the push, never a warning, never a silent pass. A push
   already requires network access to the remote, so a network + token
   requirement here is not a new cost the way it would be at commit time.
+  The only guard required on the target branch is the minimum-reviewer
+  policy (one approval, `resetOnSourcePush=true`). A build policy is NOT
+  required (Tarun, 2026-09-30, three-pipeline release flow): the promotion PR
+  runs no build and Tarun's approval is the only gate, so an absent build policy
+  is not a failure (a present one is recorded as `ok`, never flagged here).
 - **A bare `adl-repo-controls doctor` run** (not through either hook) keeps
   reporting everything, exactly as before — this split only changes which
   hook exercises which checks, never what `doctor` itself is capable of
@@ -214,6 +219,13 @@ deactivates its hook path. Canonical logs, their root ignore, quarantined log
 evidence, and runtime caches remain. `adl-config.toml` itself is never deleted — only the
 `[controls]` span this package appended is ever spliced back out.
 
+**promote** creates or reuses the active PR from `[controls.release].source`
+to `target` and arms auto-complete (the installed `.workflows/promote.ts`;
+see the assets list below). It requires the target's minimum-reviewer policy
+and does not require a build policy: the promotion PR runs no build (Tarun,
+2026-09-30). It is what the Promote pipeline (`promote.yml`, triggered by a
+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`
@@ -225,7 +237,7 @@ 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 build policy.
+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),
@@ -289,7 +301,25 @@ you own. Nothing is parsed and re-serialized; text is spliced into the table's s
 | `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 |
+| `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` — multi-language version bumps
 
@@ -365,12 +395,14 @@ sed -i.bak -E "s/^const Version = \".*\"/const Version = \"${ADL_NEXT_VERSION}\"
 rm -f "${file}.bak"
 ```
 
-`install` copies two package-owned standalone CI assets byte-for-byte:
+`install` copies four 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`
 
-Both installed assets are real executable files, never symlinks. Their SHA-256
+All installed assets are real executable files, never symlinks. Their SHA-256
 hashes live in `.workflows/repo-controls.lock.json`, and `doctor` fails if either
 file, mode, or lock entry drifts from the canonical source under `assets/`. A
 repository opts into promotion by declaring `[controls.release]` and wiring its
@@ -380,10 +412,11 @@ without deleting the source branch or transitioning work items — it never
 names a reviewer on the PR (Tarun, 2026-09-27: naming one, typically the
 person who pushed to `integration`, is a self-approval risk and contradicts
 "agent-reviewer is optional, never required"). Before it reads or mutates PRs,
-it proves the exact target branch has enabled blocking repository-wide
-policies for at least one approval with `resetOnSourcePush = true` (the
-author's own vote does not count towards it) and a build definition; a
-missing or weaker policy fails promotion. Pre-commit calls the same read-only
+it proves the exact target branch has an enabled blocking repository-wide
+policy for at least one approval with `resetOnSourcePush = true` (the
+author's own vote does not count towards it); a missing or weaker policy fails
+promotion. No build policy is required (Tarun, 2026-09-30: the promotion PR
+runs no build; the approval is the only gate). Pre-commit calls the same read-only
 doctor report and never repairs or stages the managed surface: run
 `adl repo controls install --repo .` explicitly to repair it.
 
@@ -399,6 +432,11 @@ and `X.Y.Z` subjects exempt; no staged `.scratchpad` paths or new references;
 
 ### Managed dot paths and protected controls
 
+`.workflows/` is the adl-owned managed root: every file `install` writes there,
+including the scripts `.workflows/promote.ts`, `.workflows/version-bump.sh` and
+`.workflows/reconcile-guard.sh`, is hashed in `.workflows/repo-controls.lock.json`
+and repaired by the next `install`; do not hand-edit it.
+
 The pre-commit gate has two deliberately different outcomes:
 
 - A changed or untracked **top-level** dot path is **commit-required**.

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

@@ -30,6 +30,11 @@
  * forget the other, and the derived form satisfies this package's own
  * commit-msg grammar for any pair.
  *
+ * The target branch's gate is Tarun's approval alone (Tarun, 2026-09-30): the
+ * promotion PR gets NO build validation and CD runs after the merge into the
+ * target. The pre-flight proves the minimum-reviewer policy (>=1 approver,
+ * resetOnSourcePush=true) and does not require a build policy.
+ *
  * There is no default pair. Defaulting to integration -> main would put one
  * repository's branch names back into the package by the back door.
  */
@@ -192,6 +197,12 @@ export interface PromotionPolicyReceipts {
  * only counts when it is enabled, blocking, and scoped exactly to the target
  * branch; a project-wide or path-filtered lookalike cannot guard a promotion.
  *
+ * The target's gate is the minimum-reviewer policy ONLY (Tarun, 2026-09-30):
+ * the integration -> main promotion PR gets no build validation, Tarun's
+ * approval is the only gate, and CD runs after the merge into main. Promotion
+ * therefore never requires a build policy. `build` is still reported so a
+ * caller can show one that happens to be present, but nothing here demands it.
+ *
  * No named-reviewer policy is checked here, deliberately (Tarun,
  * 2026-09-27): the two-branch standard's `main` gate is "exactly one human
  * reviewer, author's vote excluded" via the minimum-reviewer policy below —
@@ -245,17 +256,11 @@ async function verifyPolicyGate(
   )
   const policies = response.value ?? []
   const receipts = promotionPolicyReceipts(policies, { repositoryId, targetRef })
-  const { minimumReviewer, build } = receipts
-  if (!minimumReviewer) {
+  if (!receipts.minimumReviewer) {
     throw new Error(
       `promotion requires an enabled blocking minimum-reviewer policy for repository ${repositoryId} ${targetRef} with minimumApproverCount>=1 and resetOnSourcePush=true`,
     )
   }
-  if (!build) {
-    throw new Error(
-      `promotion requires an enabled blocking build policy for repository ${repositoryId} ${targetRef} with buildDefinitionId>0`,
-    )
-  }
 }
 
 export async function ensurePromotionPullRequest({

package/packages/repo-controls/assets/reconcile-guard.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Stage 2 of the CI pipeline for pull requests into `integration` (stage 1
+# bumps the PR branch, stage 3 runs the tests). It forces the PR author,
+# usually an agent, to reconcile with integration before anything merges:
+#
+#   Check A  the PR branch contains integration's tip
+#   Check B  the PR branch's manifest version is integration's + 1 patch
+#
+# Read-only: this script only fetches and reads. It never pushes, and the only
+# refs it writes are the two remote-tracking refs it fetches.
+#
+# Run from the package directory (like version-bump.sh); the manifest is
+# resolved repo-relative through `git rev-parse --show-prefix`.
+
+# CI never carries an agent identity. Never set one here, and never inherit
+# one from the caller.
+unset ADL_AGENT_ID_AGENT
+
+die() {
+  echo "reconcile-guard: $*" >&2
+  exit 1
+}
+
+version_file=''
+pr_source=''
+base=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --file)
+      [[ $# -ge 2 ]] || die '--file requires a path'
+      version_file="$2"
+      shift 2
+      ;;
+    --pr-source)
+      [[ $# -ge 2 ]] || die '--pr-source requires a branch'
+      pr_source="$2"
+      shift 2
+      ;;
+    --base)
+      [[ $# -ge 2 ]] || die '--base requires a branch'
+      base="$2"
+      shift 2
+      ;;
+    *)
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+[[ -n "$version_file" ]] || die '--file is required'
+[[ "$version_file" == 'package.json' ]] || die 'only --file package.json is supported'
+[[ -n "$pr_source" ]] || die '--pr-source is required'
+[[ -n "$base" ]] || die '--base is required'
+
+# Azure Pipelines hands over Build.SourceBranch-style refs (refs/heads/x).
+branch="${pr_source#refs/heads/}"
+base="${base#refs/heads/}"
+[[ -n "$branch" ]] || die "--pr-source '$pr_source' names no branch"
+
+case "$branch" in
+  main | integration | "$base")
+    die "refusing to guard '$branch': it is not a pull-request source branch"
+    ;;
+esac
+
+prefix="$(git rev-parse --show-prefix)" || die 'not inside a git work tree'
+manifest_path="${prefix}${version_file}"
+
+base_ref="refs/remotes/origin/$base"
+branch_ref="refs/remotes/origin/$branch"
+
+git fetch --quiet origin "+refs/heads/$base:$base_ref" || die "cannot fetch origin $base"
+git fetch --quiet origin "+refs/heads/$branch:$branch_ref" || die "cannot fetch origin $branch"
+
+base_short="$(git rev-parse --short "$base_ref")" || die "cannot resolve $base_ref"
+
+if ! git merge-base --is-ancestor "$base_ref" "$branch_ref"; then
+  missing="$(git rev-list --count "$branch_ref..$base_ref")"
+  echo "reconcile-guard: FAIL — $branch does not contain integration's tip ($base_short). Reconcile: git pull origin integration && git push" >&2
+  echo "reconcile-guard: $missing integration commit(s) missing from $branch" >&2
+  exit 1
+fi
+
+read_version() {
+  local ref="$1" text
+  text="$(git show "$ref:$manifest_path")" || die "cannot read $manifest_path at $ref"
+  printf '%s' "$text" | node -e '
+    const version = JSON.parse(require("node:fs").readFileSync(0, "utf8")).version
+    if (typeof version !== "string") process.exit(1)
+    process.stdout.write(version)
+  ' || die "cannot read a string version from $manifest_path at $ref"
+}
+
+parse_version() {
+  [[ "$1" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]] || die "cannot parse '$1' as a release version x.y.z"
+}
+
+base_version="$(read_version "$base_ref")"
+branch_version="$(read_version "$branch_ref")"
+
+parse_version "$base_version"
+target="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))"
+parse_version "$branch_version"
+
+if [[ "$branch_version" != "$target" ]]; then
+  echo "reconcile-guard: FAIL — $branch version $branch_version is not integration $base_version + 1 patch ($target). Stage 1 bumps it; re-run the PR build after reconciling." >&2
+  exit 1
+fi
+
+echo "reconcile-guard: PASS — $branch contains integration $base_short and is at $target"