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

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82920928 bytes
-sha256: 74d2d0af04a268afff30746e0d68d9d49d8e92c347e913330393c90362c99aff
+size: 82925024 bytes
+sha256: bf72c4f43099dc33afd161d5e8205d2fbfc5607e4b3aafac4ac0644224b75337

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

package/packages/agent-hooks/src/hooks/crg/background.ts

@@ -0,0 +1,179 @@
+/**
+ * Single-flight, detached `code-review-graph update --skip-flows`.
+ *
+ * Why this exists: on a large repo `update` takes ~13 s, but the
+ * `PostToolUse` hook that triggers it is killed by the host at 5 s
+ * (`assets/hooks.json`, `"timeout": 5`), so a synchronous run never
+ * finishes and the graph goes stale on every edit. The hook therefore only
+ * DECIDES here and returns at once; the work runs in a detached process
+ * group that outlives the hook.
+ *
+ * Protocol (all state under `<root>/.adl/`, already git-ignored):
+ *  - `crg-update.lock`   holds the pid of the process running the update.
+ *  - `crg-update.pending` marker: "an edit landed while an update ran".
+ *  - `logs/crg-update.log` the update's own stdout+stderr (append).
+ *
+ * `requestUpdate` (the hook side):
+ *  1. Acquire the lock atomically (`wx`), holding the hook's own pid as a
+ *     placeholder so a concurrent hook sees a live owner, then spawn the
+ *     runner and overwrite the lock with the runner's pid.
+ *  2. Lock already held by a live process (and younger than
+ *     `MAX_LOCK_AGE_MS`, a guard against pid reuse after a crash/reboot):
+ *     touch the pending marker and spawn nothing. A dead pid, or an
+ *     over-age lock, is stale: it is removed and step 1 retried once.
+ *  3. After touching the marker, re-check the owner: if it exited in the
+ *     window between the first check and the marker write, acquire and
+ *     spawn instead, so the queued edit is never stranded.
+ *
+ * `RUNNER_SCRIPT` (the detached side) runs the update, and while the
+ * pending marker exists clears it and runs once more. On its way out it
+ * releases the lock, then re-checks the marker once and re-acquires the
+ * lock (noclobber) if a hook queued in the meantime, closing the last gap.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const LOCK_REL = '.adl/crg-update.lock'
+export const PENDING_REL = '.adl/crg-update.pending'
+export const UPDATE_LOG_REL = '.adl/logs/crg-update.log'
+
+/** A lock older than this is presumed left by a crash, whatever its pid says. */
+export const MAX_LOCK_AGE_MS = 30 * 60 * 1000
+
+export const RUNNER_SCRIPT = [
+  'lock="$1"; pending="$2"; shift 2',
+  'while :; do',
+  '  rm -f "$pending"',
+  '  "$@"',
+  '  if [ -e "$pending" ]; then continue; fi',
+  '  rm -f "$lock"',
+  '  if [ -e "$pending" ] && (set -C; echo $$ > "$lock") 2>/dev/null; then continue; fi',
+  '  break',
+  'done',
+].join('\n')
+
+export interface SpawnSpec {
+  readonly cmd: string
+  readonly args: readonly string[]
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** Absolute path the child's stdout+stderr are appended to. */
+  readonly logFile: string
+}
+
+export interface BackgroundDeps {
+  /** Start a detached, unref'd child; return its pid. Must not wait for it. */
+  readonly spawn: (spec: SpawnSpec) => number
+  readonly isAlive: (pid: number) => boolean
+  readonly now: () => number
+  readonly selfPid: () => number
+  /** Resolve `bin` against `path` (the hook's own PATH); `null` when it is not there. */
+  readonly resolve: (bin: string, path: string | undefined) => string | null
+}
+
+export type UpdateRequest = 'spawned' | 'queued'
+
+const UPDATE_ARGS = ['update', '--skip-flows'] as const
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM: the process exists but belongs to someone else.
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+function spawnDetached(spec: SpawnSpec): number {
+  const fd = openSync(spec.logFile, 'a', 0o600)
+  try {
+    const proc = Bun.spawn([spec.cmd, ...spec.args], {
+      cwd: spec.cwd,
+      env: spec.env as Record<string, string>,
+      stdin: 'ignore',
+      stdout: fd,
+      stderr: fd,
+      // Own session/process group: survives the hook, unreachable by the host's timeout kill.
+      detached: true,
+    })
+    proc.unref()
+    return proc.pid
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export const defaultBackgroundDeps: BackgroundDeps = {
+  spawn: spawnDetached,
+  isAlive: isPidAlive,
+  now: () => Date.now(),
+  selfPid: () => process.pid,
+  resolve: (bin, path) => Bun.which(bin, { PATH: path ?? '' }),
+}
+
+function ownerIsLive(deps: BackgroundDeps, lockPath: string): boolean {
+  try {
+    const pid = Number.parseInt(readFileSync(lockPath, 'utf8').trim(), 10)
+    const ageMs = deps.now() - statSync(lockPath).mtimeMs
+    return Number.isInteger(pid) && pid > 0 && ageMs < MAX_LOCK_AGE_MS && deps.isAlive(pid)
+  } catch {
+    // Vanished between the caller's check and this read: nobody owns it.
+    return false
+  }
+}
+
+/** `wx` create: true if this call created the lock, false if it already exists. */
+function tryAcquire(lockPath: string, pid: number): boolean {
+  try {
+    writeFileSync(lockPath, `${pid}\n`, { flag: 'wx', mode: 0o600 })
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
+    throw error
+  }
+}
+
+function startRunner(deps: BackgroundDeps, root: string, env: SpawnSpec['env'], lockPath: string, pendingPath: string): void {
+  const pid = deps.spawn({
+    cmd: 'sh',
+    args: ['-c', RUNNER_SCRIPT, 'sh', lockPath, pendingPath, 'code-review-graph', ...UPDATE_ARGS],
+    cwd: root,
+    env,
+    logFile: join(root, UPDATE_LOG_REL),
+  })
+  writeFileSync(lockPath, `${pid}\n`, { mode: 0o600 })
+}
+
+/** Acquire + spawn. On a spawn failure the placeholder lock is released so the next edit can retry. */
+function acquireAndStart(deps: BackgroundDeps, root: string, env: SpawnSpec['env'], lockPath: string, pendingPath: string): boolean {
+  if (!tryAcquire(lockPath, deps.selfPid())) return false
+  try {
+    startRunner(deps, root, env, lockPath, pendingPath)
+  } catch (error) {
+    rmSync(lockPath, { force: true })
+    throw error
+  }
+  return true
+}
+
+export function requestUpdate(deps: BackgroundDeps, root: string, env: SpawnSpec['env']): UpdateRequest {
+  mkdirSync(join(root, '.adl', 'logs'), { recursive: true, mode: 0o700 })
+  const lockPath = join(root, LOCK_REL)
+  const pendingPath = join(root, PENDING_REL)
+
+  if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  if (!ownerIsLive(deps, lockPath)) {
+    rmSync(lockPath, { force: true })
+    if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  }
+  writeFileSync(pendingPath, '', { mode: 0o600 })
+  // The owner may have exited between the check and the marker write.
+  if (!ownerIsLive(deps, lockPath)) {
+    rmSync(lockPath, { force: true })
+    // The new runner clears the marker as its first step, so the queued edit is covered.
+    if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  }
+  return 'queued'
+}

package/packages/agent-hooks/src/hooks/crg/handler.ts

@@ -13,9 +13,10 @@
  */
 
 import type { HookInvocation, HookResult } from '../contract.ts'
+import { defaultBackgroundDeps } from './background.ts'
 import { bunRunner, createCrgHandler } from './index.ts'
 
-const crgHandler = createCrgHandler({ run: bunRunner })
+const crgHandler = createCrgHandler({ run: bunRunner, background: defaultBackgroundDeps })
 
 export async function handleCrg(inv: HookInvocation): Promise<HookResult> {
   return crgHandler(inv)

package/packages/agent-hooks/src/hooks/crg/index.ts

@@ -47,6 +47,7 @@
 
 import type { HookHandler, HookInvocation, HookResult } from '../contract.ts'
 import { spawnWithTimeout } from '../../lib/spawn-with-timeout.ts'
+import { defaultBackgroundDeps, requestUpdate, type BackgroundDeps } from './background.ts'
 import { toDecideInput } from '../../pre-tool-use/handler.ts'
 import { invocations } from '../../rules/shell/invocation.ts'
 
@@ -99,8 +100,38 @@ function missingBinaryNote(subcommand: string, result: RunResult): string {
   return `crg ${subcommand}: ${BIN} ${reason}\n`
 }
 
-/** `after-file-edit.sh`: silent `update --skip-flows`, stdout `{}`, always exit 0. */
-async function afterFileEdit(run: Runner, inv: HookInvocation): Promise<HookResult> {
+const UPDATE_LABEL = 'code-review-graph update --skip-flows'
+
+/**
+ * `after-file-edit.sh`: `update --skip-flows`, stdout `{}`, always exit 0.
+ *
+ * With `background` (production wiring) the update is spawned DETACHED and
+ * single-flight (see `./background.ts`) and the hook returns at once: the
+ * update takes longer than the host's 5 s hook timeout on a large repo, so a
+ * synchronous run was killed every time and the graph never refreshed.
+ * Without it (unit tests of the plain runner path) the update runs inline.
+ */
+async function afterFileEdit(run: Runner, inv: HookInvocation, background: BackgroundDeps | undefined): Promise<HookResult> {
+  if (background !== undefined) {
+    // Fail loud up front: the detached runner's own "command not found" would land only in crg-update.log.
+    if (background.resolve(BIN, inv.env.PATH) === null) {
+      const note = missingBinaryNote('after-file-edit', { status: null, stdout: '', stderr: '' })
+      inv.record?.({ reason: `ERROR ${BIN} not on PATH`, message: note.trim() })
+      return { stdout: '{}\n', stderr: note, exitCode: 0 }
+    }
+    try {
+      const outcome = requestUpdate(background, inv.root, inv.env)
+      inv.record?.({
+        reason: 'PASS',
+        downstream: outcome === 'spawned' ? `spawned ${UPDATE_LABEL} (background)` : 'update already running; queued',
+      })
+      return { stdout: '{}\n', stderr: '', exitCode: 0 }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      inv.record?.({ reason: `ERROR background ${UPDATE_LABEL}`, message })
+      return { stdout: '{}\n', stderr: `crg after-file-edit: could not start background update: ${message}\n`, exitCode: 0 }
+    }
+  }
   const result = await runCrg(run, inv, ['update', '--skip-flows'])
   return { stdout: '{}\n', stderr: missingBinaryNote('after-file-edit', result), exitCode: 0 }
 }
@@ -156,11 +187,11 @@ async function sessionStop(run: Runner, inv: HookInvocation): Promise<HookResult
   return { stdout: `${JSON.stringify({ message, passed: true })}\n`, stderr: note, exitCode: 0 }
 }
 
-export function createCrgHandler(deps: { run: Runner }): HookHandler {
+export function createCrgHandler(deps: { run: Runner; background?: BackgroundDeps }): HookHandler {
   return async (inv: HookInvocation): Promise<HookResult> => {
     switch (inv.subcommand) {
       case 'after-file-edit':
-        return afterFileEdit(deps.run, inv)
+        return afterFileEdit(deps.run, inv, deps.background)
       case 'pre-commit':
         return preCommit(deps.run, inv)
       case 'session-stop':
@@ -205,5 +236,5 @@ export const bunRunner: Runner = async (cmd, args, opts) => {
   }
 }
 
-export const handleCrg: HookHandler = createCrgHandler({ run: bunRunner })
+export const handleCrg: HookHandler = createCrgHandler({ run: bunRunner, background: defaultBackgroundDeps })
 export default handleCrg

package/packages/agent-hooks/src/rules/impl/git-paths.ts

@@ -31,15 +31,14 @@ export const gitRm: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked git rm. It deletes tracked content and stages the deletion in one step; agents leave the file in place and hand the removal to you.',
+      user: 'Blocked git rm. It deletes tracked content and stages the deletion in one step; agents remove a tracked file with trash instead.',
       agent:
         'DENIED git rm. Every form is refused - with flags or without, --cached included. `git rm` deletes ' +
         'tracked content AND stages the deletion in one step, so it is both the delete and the commit-prep ' +
-        'for it, and it was the last deletion verb this hook left open after rm and trash were closed. ' +
-        'There is no flag that makes it acceptable and no `git rm` that this hook allows. ' +
-        'If a tracked file genuinely has to go: leave it exactly where it is, finish the rest of the change, ' +
-        'and tell the user which paths should be removed and why - removal is theirs to run, the same rule ' +
-        `that already applies to committing a protected tree. ${gitAgentTail(ctx.snippet)}`,
+        'for it. There is no flag that makes it acceptable and no `git rm` that this hook allows. ' +
+        'If a tracked file genuinely has to go, run `trash <path>` (recoverable from ~/.Trash; fs.trash only ' +
+        'refuses the working directory, a system root, $HOME and .git), then `git add <path>` to stage the ' +
+        `deletion with the rest of the change. ${gitAgentTail(ctx.snippet)}`,
     }
   },
   corpus: {

package/packages/agent-hooks/src/rules/impl/tool-grep.ts

@@ -37,7 +37,7 @@ export const toolGrep: RuleSpec = {
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the grep family; steer at rg / ast-grep / search / ctx_search.',
+  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg / ctx_search.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'grep') return null
@@ -45,15 +45,15 @@ export const toolGrep: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked grep. Use `rg` (same job, faster, repo-aware), `ast-grep` for structural search, or `ctx_search` for the indexed search.',
+      user: 'Blocked grep. Pick the tool for the question: `ast-grep` for code shapes, `search` for docs by meaning, `crg` for callers and impact, `rg` for literal text, `ctx_search` for the indexed code search.',
       agent:
-        'DENIED grep. Use one of these instead - all are on PATH and already allowed:\n' +
-        '  rg          drop-in for grep, including stdin: `npm test 2>&1 | rg "pass|fail"`\n' +
-        '  ast-grep    structural/syntax search, for shapes rather than strings\n' +
-        '  search      hybrid semantic + keyword over indexed docs (`search query "<text>"`)\n' +
+        'DENIED grep. Match the tool to the question - in this order, all on PATH and already allowed:\n' +
+        '  ast-grep  code STRUCTURE: shapes rather than strings (`ast-grep -p "foo($A)" -l ts`)\n' +
+        '  search    docs and plans by MEANING: hybrid semantic + keyword (`search query "<text>"`)\n' +
+        '  crg       the code GRAPH: callers, callees, impact (`crg query callers_of <fn>`, `crg impact`)\n' +
+        '  rg        LITERAL text or regex, including stdin: `npm test 2>&1 | rg "pass|fail"`\n' +
         '  ctx_search  the indexed code search (action=symbol for an exact symbol)\n' +
-        'This applies to a pure output filter too: `rg` reads stdin exactly as grep does, ' +
-        'so there is no capability being removed here, only a slower tool. ' +
+        'A pure output filter is no exception: `rg` reads stdin exactly as grep does. ' +
         `Blocked command: ${ctx.snippet}`,
     }
   },

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

@@ -85,13 +85,24 @@
  * as its own finding. checkBuildServiceCanRelease() answers one narrow
  * question directly, per the real failure above: can the identity that
  * ACTUALLY RUNS THE PIPELINE (repo scope) push a `***NO_CI***` bump commit
- * to `integration` (GenericContribute), bypass `integration`'s own policies
- * while doing so (PolicyExempt), and create/update the `integration -> main`
- * PR and set auto-complete (PullRequestContribute) — and it FAILS loudly,
+ * to the PR's source (feature) branch (GenericContribute), and create/update
+ * the `integration -> main` PR and set auto-complete
+ * (PullRequestContribute) — and it FAILS loudly,
  * naming the permission, the identity's display name and the fix path, on
  * any of: the permission not effectively allowed, the identity not
  * resolvable, or the ACL itself not readable by the calling agent.
  *
+ * New release flow (Tarun, 2026-09-30): the CI pipeline runs on PRs into
+ * `integration` and its stage 1 pushes the version bump to the PR's SOURCE
+ * (feature) branch; a promote pipeline on `integration` pushes only opens the
+ * `integration -> main` PR; a CD pipeline runs on pushes to `main`. Nothing
+ * pushes directly to `integration` any more, so (a) the build service no
+ * longer needs PolicyExempt on `integration` — and, by least privilege,
+ * having it there is drift; (b) the release-identity check no longer needs
+ * PolicyExempt; (c) the promotion PR gets NO build validation (Tarun's
+ * approval is the only gate; CD runs after the merge), so `main` no longer
+ * requires a build-validation policy and an enabled one is drift.
+ *
  * Policy type GUIDs (verified against the azure-devops-cli-extension source,
  * packages/repo-controls already hardcodes the first three the same way):
  *   minimum reviewers   fa4e907d-c16b-4a4c-9dfa-4906e5d171dd
@@ -178,7 +189,11 @@ export const REPO_STANDARD = {
     forbiddenReviewerPolicies: [POLICY_TYPE.requiredReviewers] as const,
     mergeStrategy: { allowSquash: false, allowRebase: false, allowRebaseMerge: false, allowNoFastForward: true },
     commentRequirementsRequired: true,
-    buildValidationRequiredWhenPipelineExists: true,
+    // Tarun, 2026-09-30, new release flow: the integration -> main promotion
+    // PR must NOT run a build (Tarun's approval is the only gate; the CD
+    // pipeline runs after the merge, on pushes to main). An ENABLED build
+    // policy on main is drift (`main.build-validation-present`).
+    buildValidationForbidden: true,
   },
   // One table for every effective-permission expectation this checker reads
   // via the Git Repositories security namespace ACL, so the standard never
@@ -216,9 +231,13 @@ export const REPO_STANDARD = {
      * — Tarun, 2026-09-27, cross-checked against
      * /Users/tarunrana/Documents/ADL-ISMS-Policies/.scratchpad/ci_build_service_grant.py,
      * which grants exactly these bits on adl-agent-control). CI needs to push
-     * and complete PRs on the repo, and needs PolicyExempt only on
-     * `integration` (so a version-bump commit made by CI itself is not
-     * blocked by its own policies) — never on `main`.
+     * and complete PRs on the repo (Contribute is also what the version-bump
+     * push to the PR's SOURCE feature branch needs — Tarun, 2026-09-30, new
+     * release flow). It needs PolicyExempt NOWHERE: nothing pushes directly to
+     * `integration` any more (the bump lands on the feature branch), so
+     * PolicyExempt on `integration` is no longer required and, by least
+     * privilege, is drift (`permissions.build-service.has-policyExempt-integration`);
+     * never on `main` either (existing rule).
      *
      * NOT forcePush (Tarun, 2026-09-30): the bump is a plain fast-forward
      * `git push origin HEAD:integration`; agent-identities' build service has
@@ -229,33 +248,28 @@ export const REPO_STANDARD = {
       repo: { allow: ["genericContribute", "pullRequestContribute"] } as {
         allow: readonly PermissionBitName[];
       },
-      integrationRef: { allow: ["policyExempt"] } as { allow: readonly PermissionBitName[] },
+      integrationRef: { deny: ["policyExempt"] } as { deny: readonly PermissionBitName[] },
       mainRef: { deny: ["policyExempt"] } as { deny: readonly PermissionBitName[] },
     },
     /**
      * checkBuildServiceCanRelease() (file header, "checkBuildServiceCanRelease()"):
-     * the exact three permissions the release flow needs from whichever
-     * build service identity actually runs the pipeline — the real failure
-     * this check exists for was a 403 on `pullRequestContribute`.
+     * the permissions the release flow needs from whichever build service
+     * identity actually runs the pipeline — the real failure this check
+     * exists for was a 403 on `pullRequestContribute`.
      *
-     * `policyExempt` ("Bypass policies when pushing") is checked at the
-     * `integration` REF token, never the repo-scope token — verified live
-     * 2026-09-30 against adl-agent-control: the Infrastructure-AzDo Build
-     * Service demonstrably bypassed `integration`'s own policies to push
-     * `chore: bump version 0.1.6 to 0.1.7 ***NO_CI***` (c966e6a) straight to
-     * that protected branch, yet its repo-scope effective allow bitmask
-     * (16430) does not include PolicyExempt (128) at all — only its
-     * `refs/heads/integration`-scope effective allow (16558) does. Checking
-     * `policyExempt` at repo scope produced a false
-     * `permissions.release.<slug>.missing-policyExempt` finding that
-     * contradicted this observed reality. `genericContribute` and
-     * `pullRequestContribute` stay checked at repo scope — both bits ARE
-     * present there for real, and PR operations are a repo-level, not
-     * branch-level, permission.
+     * `policyExempt` ("Bypass policies when pushing") is NOT required any
+     * more (Tarun, 2026-09-30, new release flow): the version bump now lands
+     * on the PR's SOURCE (feature) branch, not on `integration`, so nothing
+     * needs to bypass `integration`'s policies. (History: it used to be
+     * checked at the `integration` REF token, never repo scope — verified
+     * live 2026-09-30 against adl-agent-control, where the build service
+     * pushed `chore: bump version 0.1.6 to 0.1.7 ***NO_CI***` (c966e6a)
+     * straight to `integration`.) `genericContribute` (the bump push to the
+     * feature branch) and `pullRequestContribute` stay checked at repo scope
+     * — PR operations are a repo-level, not branch-level, permission.
      */
     buildServiceRelease: {
       repoScoped: ["genericContribute", "pullRequestContribute"] as const,
-      integrationRefScoped: ["policyExempt"] as const,
     },
   },
 } as const;
@@ -518,11 +532,7 @@ function checkMainMergeStrategy(policies: readonly PolicyConfiguration[], drifts
   });
 }
 
-function checkMainCommentsAndBuild(
-  policies: readonly PolicyConfiguration[],
-  hasPipeline: boolean,
-  drifts: RepoDoctorDrift[],
-): void {
+function checkMainCommentsAndBuild(policies: readonly PolicyConfiguration[], drifts: RepoDoctorDrift[]): void {
   const comments = enabledPolicyOfType(policies, POLICY_TYPE.commentRequirements);
   if (!comments) {
     drifts.push({
@@ -531,21 +541,27 @@ function checkMainCommentsAndBuild(
     });
   }
 
-  if (!hasPipeline) return;
+  // Tarun, 2026-09-30, new release flow: the promotion PR must not run a
+  // build — main no longer requires build validation, and an enabled one is
+  // drift (regardless of whether a pipeline exists).
   const build = enabledPolicyOfType(policies, POLICY_TYPE.build);
-  if (!build) drifts.push({ id: "main.build-validation-missing", message: "missing build validation" });
+  if (build) {
+    drifts.push({
+      id: "main.build-validation-present",
+      message: `main has an enabled build-validation policy (#${build.id}); the promotion PR must not run a build (CD runs after merge) — Tarun's approval is the only gate`,
+    });
+  }
 }
 
 function checkMainPolicies(
   policies: readonly PolicyConfiguration[],
-  hasPipeline: boolean,
   strictMainBranchRules: boolean,
   drifts: RepoDoctorDrift[],
 ): void {
   checkMainRequiredReviewer(policies, drifts);
   checkMainMinimumReviewers(policies, strictMainBranchRules, drifts);
   checkMainMergeStrategy(policies, drifts);
-  checkMainCommentsAndBuild(policies, hasPipeline, drifts);
+  checkMainCommentsAndBuild(policies, drifts);
 }
 
 /**
@@ -823,10 +839,11 @@ async function resolveBuildServiceDescriptor(namespaceId: string, projectId: str
 }
 
 /**
- * CI needs to push and complete PRs on the repo itself, and needs to bypass
- * policy only on `integration` (so its own version-bump commit is not
- * blocked by the very policies it satisfies) — never on `main`, where a
- * bypass would defeat the human-reviewer gate entirely.
+ * CI needs to push (the version bump to the PR's source branch) and complete
+ * PRs on the repo itself. It needs to bypass policy NOWHERE (Tarun,
+ * 2026-09-30, new release flow: nothing pushes directly to `integration`
+ * any more, so PolicyExempt there is drift; on `main` a bypass would defeat
+ * the human-reviewer gate entirely).
  */
 async function checkBuildServicePermissions(
   namespaceId: string,
@@ -885,11 +902,14 @@ async function checkBuildServicePermissions(
     drifts,
   );
   if (integrationEffective) {
-    for (const bitName of REPO_STANDARD.permissions.buildService.integrationRef.allow) {
-      if ((effectiveAllowBits(integrationEffective) & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
+    // Tarun, 2026-09-30, new release flow: nothing pushes directly to
+    // integration any more, so PolicyExempt there is no longer required and
+    // is flagged when effectively allowed (least privilege).
+    for (const bitName of REPO_STANDARD.permissions.buildService.integrationRef.deny) {
+      if ((effectiveAllowBits(integrationEffective) & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) {
         drifts.push({
-          id: `permissions.build-service.missing-${bitName}-integration`,
-          message: `the project build service does not effectively have ${bitName} on refs/heads/integration`,
+          id: `permissions.build-service.has-${bitName}-integration`,
+          message: `the project build service effectively has ${bitName} on refs/heads/integration, which the standard forbids (nothing pushes directly to integration; the version bump lands on the PR's source branch)`,
         });
       }
     }
@@ -941,16 +961,6 @@ function releaseFixPath(repository: string, identityDisplayName: string, bitName
   return `Project settings → Repositories → \`${repository}\` → Security → \`${identityDisplayName}\` → \`${GIT_REPO_PERMISSION_UI_LABEL[bitName]}\` = Allow`;
 }
 
-/** Same as releaseFixPath() but for a bit that is granted per-BRANCH (verified live 2026-09-30: PolicyExempt on this org's build service lives on refs/heads/integration's own security page, never the repo-root one). */
-function releaseFixPathForRef(
-  repository: string,
-  ref: string,
-  identityDisplayName: string,
-  bitName: PermissionBitName,
-): string {
-  return `Repos → \`${repository}\` → Branches → \`${ref}\` → ⋯ → Branch security → \`${identityDisplayName}\` → \`${GIT_REPO_PERMISSION_UI_LABEL[bitName]}\` = Allow`;
-}
-
 /**
  * Which build service identity actually runs the pipeline, per Build —
  * General Settings — Get's `enforceJobAuthScope` (file header) — "Limit job
@@ -973,12 +983,10 @@ async function fetchEnforceJobAuthScope(c: AdoClient): Promise<boolean | undefin
 /**
  * One identity's answer to "can it release": resolve its descriptor by exact
  * display name (Identities — Read Identities, file header), then check
- * `buildServiceRelease.repoScoped` on the repository token AND
- * `buildServiceRelease.integrationRefScoped` on the `integration` ref token
- * — NOT the same token for all three (see REPO_STANDARD.permissions.
- * buildServiceRelease's own doc comment: PolicyExempt is a per-BRANCH grant
- * in this org, verified live against real bypass-on-push evidence, and
- * checking it at repo scope produced a false "missing" finding). Every
+ * `buildServiceRelease.repoScoped` on the repository token. PolicyExempt is
+ * no longer part of what a release needs (Tarun, 2026-09-30, new release
+ * flow: the bump lands on the PR's source branch, not on integration — see
+ * REPO_STANDARD.permissions.buildServiceRelease's own doc comment). Every
  * failure mode is its own loud, distinct drift — an unresolvable identity,
  * an ACL the calling agent cannot read, and each missing permission named
  * with its fix path — never a silent pass.
@@ -986,7 +994,6 @@ async function fetchEnforceJobAuthScope(c: AdoClient): Promise<boolean | undefin
 async function checkOneBuildServiceCanRelease(
   namespaceId: string,
   repoToken: string,
-  integrationRefToken: string,
   repository: string,
   displayName: string,
   drifts: RepoDoctorDrift[],
@@ -1013,8 +1020,7 @@ async function checkOneBuildServiceCanRelease(
   }
 
   // LOW, independent review 2026-09-30: name WHICH token failed — "the ACL"
-  // alone left a human unable to tell a repo-scope 403 from a
-  // refs/heads/integration-scope one without re-running this by hand.
+  // alone left a human unable to tell which token's read 403'd.
   async function effectiveAt(token: string, tokenLabel: string): Promise<{ allow: number; deny: number } | undefined> {
     let effective: EffectivePermissionsResult;
     try {
@@ -1039,16 +1045,6 @@ async function checkOneBuildServiceCanRelease(
       message: `'${displayName}' does not effectively have ${GIT_REPO_PERMISSION_UI_LABEL[bitName]} on '${repository}' — the release pipeline will 403 the way agent-identities build 4897 did. Fix: ${releaseFixPath(repository, displayName, bitName)}`,
     });
   }
-
-  const integrationEffective = await effectiveAt(integrationRefToken, "refs/heads/integration");
-  if (!integrationEffective) return;
-  for (const bitName of REPO_STANDARD.permissions.buildServiceRelease.integrationRefScoped) {
-    if ((effectiveAllowBits(integrationEffective) & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) continue;
-    drifts.push({
-      id: `permissions.release.${slug}.missing-${bitName}`,
-      message: `'${displayName}' does not effectively have ${GIT_REPO_PERMISSION_UI_LABEL[bitName]} on 'refs/heads/integration' of '${repository}' — its own version-bump commit would be blocked by integration's own policies. Fix: ${releaseFixPathForRef(repository, "integration", displayName, bitName)}`,
-    });
-  }
 }
 
 /**
@@ -1079,9 +1075,8 @@ async function checkBuildServiceCanRelease(
         : [projectScoped, collectionScoped];
 
   const repoToken = `repoV2/${projectId}/${repositoryId}`;
-  const integrationRefToken = `${repoToken}/refs/heads/${refNameHexUtf16Le("integration")}`;
   for (const displayName of displayNames) {
-    await checkOneBuildServiceCanRelease(namespaceId, repoToken, integrationRefToken, repository, displayName, drifts);
+    await checkOneBuildServiceCanRelease(namespaceId, repoToken, repository, displayName, drifts);
   }
 }
 
@@ -1140,7 +1135,7 @@ export async function repoDoctorCheck(options: RepoDoctorOptions = {}): Promise<
   const integrationPolicies = await fetchBranchPolicies(c, repositoryId, "integration");
   const mainPolicies = await fetchBranchPolicies(c, repositoryId, "main");
   checkIntegrationPolicies(integrationPolicies, hasPipeline, drifts);
-  checkMainPolicies(mainPolicies, hasPipeline, strictMainBranchRules, drifts);
+  checkMainPolicies(mainPolicies, strictMainBranchRules, drifts);
 
   await checkAgentPermissions(projectId, repositoryId, strictMainBranchRules, drifts);
   await checkBuildServicePermissions(

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"

package/packages/repo-controls/assets/version-bump.sh

@@ -1,13 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# The integration build owns package version allocation, exactly as every
-# other repo on this standard does it (enact-extensions, enact-combined):
-# after a PR merges, bump the patch version on `integration`, commit it with
-# ***NO_CI*** and push it straight back to `integration`. The build service
-# has "bypass policies when pushing"; ***NO_CI*** stops the push from
-# triggering another pipeline run. No npm query, no second PR, no second
-# test run (Tarun, 2026-09-29).
+# STAGE 1 of the PR pipeline (PR -> integration): the PR build owns package
+# version allocation. Every PR into `integration` must carry exactly
+# `<integration version> + patch 1`; this script makes it so, on the PR's
+# SOURCE branch, before anything else validates it:
+#
+#   version-bump.sh --file package.json --pr-source <feature branch> \
+#     --base integration --push
+#
+# The Azure Pipelines PR build checks out the detached refs/pull/N/merge
+# commit with persisted credentials, so `git push` authenticates as the
+# project build service. The bump commit is created on the source branch's own
+# tip (never on the merge commit), carries no ***NO_CI*** (feature branches
+# have no CI trigger, so the push re-queues the PR build, which then
+# validates the bumped commit), and is pushed with a plain push — never
+# forced. When the source is already at the target version nothing is
+# committed and the run continues. No npm query, no second PR.
 
 # CI never carries an agent identity: the push below authenticates as the
 # project build service through the checkout's persisted System.AccessToken.
@@ -20,8 +29,8 @@ die() {
 }
 
 version_file=''
-integration_branch=''
-integration_mode=false
+pr_source=''
+base_branch=''
 push_bump=false
 
 while [[ $# -gt 0 ]]; do
@@ -31,14 +40,15 @@ while [[ $# -gt 0 ]]; do
       version_file="$2"
       shift 2
       ;;
-    --branch)
-      [[ $# -ge 2 ]] || die '--branch requires a name'
-      integration_branch="$2"
+    --pr-source)
+      [[ $# -ge 2 ]] || die '--pr-source requires a branch ref'
+      pr_source="$2"
       shift 2
       ;;
-    --integration)
-      integration_mode=true
-      shift
+    --base)
+      [[ $# -ge 2 ]] || die '--base requires a branch name'
+      base_branch="$2"
+      shift 2
       ;;
     --push)
       push_bump=true
@@ -51,46 +61,73 @@ while [[ $# -gt 0 ]]; do
 done
 
 [[ "$version_file" == 'package.json' ]] || die 'only --file package.json is supported'
-[[ -f "$version_file" ]] || die "manifest not found: $version_file"
-[[ -n "$integration_branch" ]] || die '--branch is required'
-[[ "$integration_mode" == true ]] || die '--integration is required'
+[[ -n "$pr_source" ]] || die '--pr-source is required'
+[[ -n "$base_branch" ]] || die '--base is required'
 [[ "$push_bump" == true ]] || die '--push is required'
 
-current_branch="$(git branch --show-current)"
-if [[ -z "$current_branch" ]]; then
-  # Azure Pipelines' `checkout: self` leaves the working tree on a detached
-  # HEAD (build 4822, integration, 2026-09-27: `git branch --show-current`
-  # came back empty even though the checkout was the right commit on
-  # `integration`). Fall back to Build.SourceBranch (env BUILD_SOURCEBRANCH,
-  # e.g. `refs/heads/integration`) rather than requiring the pipeline to
-  # `git checkout -B` a real branch first.
-  case "${BUILD_SOURCEBRANCH:-}" in
-    refs/heads/*)
-      current_branch="${BUILD_SOURCEBRANCH#refs/heads/}"
-      ;;
-    '')
-      die 'cannot determine the current branch: HEAD is detached (git branch --show-current is empty) and BUILD_SOURCEBRANCH is not set'
-      ;;
-    *)
-      die "BUILD_SOURCEBRANCH '$BUILD_SOURCEBRANCH' is not a branch ref (expected 'refs/heads/<name>')"
-      ;;
-  esac
+# Accept `refs/heads/x` (Build.SourceBranch / System.PullRequest.SourceBranch)
+# or a bare `x`; anything else under refs/ is not a branch.
+source_branch="${pr_source#refs/heads/}"
+case "$source_branch" in
+  '') die '--pr-source names an empty branch' ;;
+  refs/*) die "--pr-source '$pr_source' is not a branch ref (expected 'refs/heads/<name>' or '<name>')" ;;
+esac
+base_branch="${base_branch#refs/heads/}"
+if [[ "$source_branch" == "$base_branch" || "$source_branch" == 'main' || "$source_branch" == 'integration' ]]; then
+  die "refusing to bump '$source_branch': the PR source must be a feature branch, not the base ('$base_branch'), main or integration"
 fi
-[[ "$current_branch" == "$integration_branch" ]] || \
-  die "integration mode expects branch '$integration_branch', currently on '$current_branch'"
-
-current_version="$(node -e 'const version = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).version; if (typeof version !== "string") process.exit(1); process.stdout.write(version)' "$version_file")" || \
-  die "cannot read a string version from $version_file"
 
-if [[ ! "$current_version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-  die "cannot parse '$current_version' as a release version x.y.z"
+git diff --quiet || die 'working tree is not clean before version bump'
+git diff --cached --quiet || die 'index is not clean before version bump'
+repo_root="$(git rev-parse --show-toplevel)" || die 'cannot resolve the repository root'
+# The script runs from the package directory (e.g. apps/cli); the manifest's
+# repository-relative path is how it is read from the base branch.
+repo_prefix="$(git rev-parse --show-prefix)" || die 'cannot resolve the working directory inside the repository'
+repo_relative_file="${repo_prefix}${version_file}"
+
+# Read both tips fresh from origin. The PR build's checkout is the detached
+# merge commit; bumping that would push a commit that is not the branch's own
+# history, so the working tree is moved onto a REAL branch at the source tip.
+git fetch origin \
+  "refs/heads/$base_branch:refs/remotes/origin/$base_branch" \
+  "refs/heads/$source_branch:refs/remotes/origin/$source_branch" || \
+  die "cannot fetch '$base_branch' and '$source_branch' from origin"
+
+# The source must already contain the base's tip: the version it is bumped to
+# is derived from that tip, so a source behind it would be validated against a
+# merge the bump never saw.
+if ! git merge-base --is-ancestor "refs/remotes/origin/$base_branch" "refs/remotes/origin/$source_branch"; then
+  missing_count="$(git rev-list --count "refs/remotes/origin/$source_branch..refs/remotes/origin/$base_branch")"
+  base_short="$(git rev-parse --short "refs/remotes/origin/$base_branch")"
+  echo "version-bump: FAIL — $source_branch does not contain $base_branch's tip ($base_short); reconcile first: git pull origin $base_branch && git push" >&2
+  echo "version-bump: $missing_count commit(s) on $base_branch are missing from $source_branch" >&2
+  exit 1
 fi
 
+git checkout -q -B "$source_branch" "refs/remotes/origin/$source_branch" || \
+  die "cannot check out '$source_branch' at its origin tip"
+
+[[ -f "$version_file" ]] || die "manifest not found: $version_file"
+
+read_version() {
+  node -e 'const version = JSON.parse(require("node:fs").readFileSync(0, "utf8")).version; if (typeof version !== "string") process.exit(1); process.stdout.write(version)'
+}
+
+base_version="$(git show "refs/remotes/origin/$base_branch:$repo_relative_file" | read_version)" || \
+  die "cannot read a string version from $repo_relative_file on origin/$base_branch"
+if [[ ! "$base_version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+  die "cannot parse '$base_version' (origin/$base_branch) as a release version x.y.z"
+fi
 next_version="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))"
 
-git diff --quiet || die 'working tree is not clean before version bump'
-git diff --cached --quiet || die 'index is not clean before version bump'
-repo_root="$(git rev-parse --show-toplevel)" || die 'cannot resolve the repository root'
+current_version="$(read_version < "$version_file")" || die "cannot read a string version from $version_file"
+
+if [[ "$current_version" == "$next_version" ]]; then
+  echo "version-bump: $source_branch already at $next_version (integration $base_version); nothing to bump"
+  echo '##vso[task.setvariable variable=bumped;isOutput=true]false'
+  exit 0
+fi
+
 node -e '
   const fs = require("node:fs")
   const [file, version] = process.argv.slice(1)
@@ -105,7 +142,7 @@ node -e '
 # package.json can reach. No file, or no `pre_bump` key: no scripts, and
 # everything below this comment is a no-op, so the resulting commit is
 # byte-identical to the behaviour before this feature existed (see
-# packages/repo-controls/tests/version-bump-pre-bump.test.ts).
+# packages/repo-controls/tests/version-bump-pr-source-pre-bump.test.ts).
 config_path="$repo_root/adl-config.toml"
 pre_bump_list=''
 if [[ -f "$config_path" ]]; then
@@ -189,6 +226,9 @@ fi
 
 git -C "$repo_root" add -A
 git diff --cached --quiet && die "version bump produced no staged change (expected at least $version_file)"
-git commit -m "chore: bump version $current_version to $next_version ***NO_CI***"
-git push origin "HEAD:$integration_branch"
-echo "Bumped $version_file from $current_version to $next_version on $integration_branch."
+# No ***NO_CI***: a feature branch has no CI trigger, so this push is what
+# re-queues the PR build against the bumped commit.
+git commit -m "chore: bump version $current_version to $next_version"
+git push origin "HEAD:refs/heads/$source_branch"
+echo "version-bump: bumped $source_branch from $current_version to $next_version (integration $base_version); pushed — this run ends, the re-queued PR build validates the bumped commit"
+echo '##vso[task.setvariable variable=bumped;isOutput=true]true'

package/packages/repo-controls/src/azure-devops-governance.ts

@@ -168,9 +168,12 @@ export interface AzureDevOpsGovernanceOptions {
 }
 
 /**
- * One read-only receipt per promotion guard. Unreadable evidence is a failure,
- * never a warning: a commit cannot claim the remote guard is armed when that
- * fact could not be established.
+ * One read-only receipt per promotion guard. The only required guard on the
+ * target branch is the minimum-reviewer policy (Tarun, 2026-09-30): a build
+ * policy is NOT required, because the integration -> main promotion PR gets no
+ * build validation and CD runs after the merge. Unreadable evidence is a
+ * failure, never a warning: a commit cannot claim the remote guard is armed
+ * when that fact could not be established.
  */
 export function azureDevOpsGovernanceChecks(options: AzureDevOpsGovernanceOptions): AzureDevOpsGovernanceCheck[] {
   const checks: AzureDevOpsGovernanceCheck[] = []
@@ -231,18 +234,16 @@ export function azureDevOpsGovernanceChecks(options: AzureDevOpsGovernanceOption
           message: `missing blocking minimum-reviewer policy requiring one approval and resetOnSourcePush=true for ${prefix}`,
         },
   )
-  checks.push(
-    receipts.build
-      ? {
-          id: 'azure-devops.build-policy',
-          status: 'ok',
-          message: `blocking build policy #${id(receipts.build)} uses definition ${receipts.build.settings?.buildDefinitionId} for ${prefix}`,
-        }
-      : {
-          id: 'azure-devops.build-policy',
-          status: 'fail',
-          message: `missing blocking build policy with a build definition for ${prefix}`,
-        },
-  )
+  // No build-policy requirement on `main` (Tarun, 2026-09-30): the promotion PR
+  // gets no build validation, so an absent build policy is not a failure. A
+  // present one is only recorded, never flagged here (the azdo repo doctor
+  // owns that).
+  if (receipts.build) {
+    checks.push({
+      id: 'azure-devops.build-policy',
+      status: 'ok',
+      message: `blocking build policy #${id(receipts.build)} uses definition ${receipts.build.settings?.buildDefinitionId} for ${prefix}`,
+    })
+  }
   return checks
 }

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

@@ -63,6 +63,8 @@ export const PROMOTE_REL = '.workflows/promote.ts'
 export const AUTO_COMPLETE_REL = '.workflows/scripts/enable-integration-auto-complete.mjs'
 /** The standalone immutable package-version allocator for integration CI. */
 export const VERSION_BUMP_REL = '.workflows/version-bump.sh'
+/** The standalone CI stage-2 guard: a PR branch must contain integration's tip and be at its version + 1 patch. */
+export const RECONCILE_GUARD_REL = '.workflows/reconcile-guard.sh'
 
 export const MANAGED_ASSETS = [
   { rel: PROMOTE_REL, source: join(PACKAGE_ROOT, 'assets', 'promote.ts'), mode: 0o755, doctorId: 'promote' },
@@ -78,6 +80,12 @@ export const MANAGED_ASSETS = [
     mode: 0o755,
     doctorId: 'version-bump',
   },
+  {
+    rel: RECONCILE_GUARD_REL,
+    source: join(PACKAGE_ROOT, 'assets', 'reconcile-guard.sh'),
+    mode: 0o755,
+    doctorId: 'reconcile-guard',
+  },
 ] as const
 /** Shared with adl hook ([hooks]/[rules]/[repo]) and adl-extensions ([skills]); this package owns only [controls]. */
 export const CONFIG_REL = 'adl-config.toml'

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

@@ -430,8 +430,9 @@ function dirtyPaths(porcelain: string): string[] {
     const hasOrigin = staged === 'R' || staged === 'C' || worktree === 'R' || worktree === 'C'
     const origin = hasOrigin ? records[++index] : undefined
     // An untracked path has no index entry, so it is necessarily omitted from
-    // this commit. Keep it: centrally managed dot paths must be staged rather
-    // than silently left behind.
+    // this commit. Keep it: other top-level dot paths must be staged rather than
+    // silently left behind, and a protected root (.workflows, .agents, .claude,
+    // .codex, .cursor, .kimi-code, .opencode) is refused outright (integrity.ts).
     if (staged === '?' && worktree === '?') {
       paths.push(record.slice(3))
       continue

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

@@ -9,7 +9,21 @@
 
 export const WIRING: readonly string[] = ['adl-config.toml']
 
-const FIXED_ROOTS: readonly string[] = ['compliance', 'workflows']
+// 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
+// only Tarun lands it. They were "centrally managed dotfiles" an agent could
+// commit alongside a related change; that let an agent land gate-defining files.
+const FIXED_ROOTS: readonly string[] = [
+  'compliance',
+  'workflows',
+  '.workflows',
+  '.agents',
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.kimi-code',
+  '.opencode',
+]
 
 /** A declared pattern, as a regex. `*` stays in one directory; `**` crosses them. */
 function patternToRegExp(pattern: string): RegExp {