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

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
@@ -206,7 +221,9 @@ export const REPO_STANDARD = {
         allow: ["genericContribute", "pullRequestContribute"],
         deny: ["forcePush", "policyExempt", "pullRequestBypassPolicy"],
       },
-      "agent-reviewer": { allow: ["pullRequestContribute"], deny: ["genericContribute"] },
+      // Tarun, 2026-09-30: no agent gets force push — agent-reviewer included,
+      // in every project (only its genericContribute deny is Enact-only).
+      "agent-reviewer": { allow: ["pullRequestContribute"], deny: ["genericContribute", "forcePush"] },
     } as Record<string, { allow: readonly PermissionBitName[]; deny: readonly PermissionBitName[] }>,
     /**
      * The project's build service identity (display name `Build\<projectId>`,
@@ -214,41 +231,45 @@ 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
-     * tags/branches 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
+     * no ForcePush and bumped 0.4.2 → 0.4.3 fine. The grant script's
+     * ForcePush has no consumer, so force push is required of no identity.
      */
     buildService: {
-      repo: { allow: ["genericContribute", "forcePush", "pullRequestContribute"] } as {
+      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;
@@ -511,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({
@@ -524,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);
 }
 
 /**
@@ -816,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,
@@ -878,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)`,
         });
       }
     }
@@ -934,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
@@ -966,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.
@@ -979,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[],
@@ -1006,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 {
@@ -1032,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)}`,
-    });
-  }
 }
 
 /**
@@ -1072,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);
   }
 }
 
@@ -1133,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"