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

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

@@ -31,10 +31,32 @@
  *     values below are the same ones already read live and recorded in
  *     ADL-ISMS-Policies/docs/scripts/enact-agent-git-permissions.py and
  *     .../docs/evidence/vanta-documents/100-.../azure-devops-git-security-namespace.json)
- *   - Graph — Subject Query (resolve a service principal's descriptor by display name)
+ *   - Graph — Subject Query (resolve agent-tarun/agent-vivek/agent-reviewer's
+ *     descriptor by display name — each is an Azure AD SERVICE PRINCIPAL
+ *     ("aadsp") subject, verified live 2026-09-30; subjectKind must include
+ *     'ServicePrincipal' or the query returns no match at all, which is
+ *     exactly what the permissions.<agent>.not-found drift below reported
+ *     before this fix)
  *     POST https://vssps.dev.azure.com/{org}/_apis/graph/subjectquery?api-version=7.1-preview.1
- *     body: { query: <displayName>, subjectKind: ['User'] }
+ *     body: { query: <displayName>, subjectKind: ['User', 'ServicePrincipal'] }
  *     https://learn.microsoft.com/en-us/rest/api/azure/devops/graph/subject-query/query
+ *   - Identities — Read Identities, `subjectDescriptors` + `queryMembership=ExpandedUp`
+ *     (an agent's own LEGACY descriptor — verified live 2026-09-30:
+ *     agent-tarun/agent-vivek/agent-reviewer hold NO direct ACE anywhere on
+ *     adl-agent-control or agent-identities; their real Contribute /
+ *     Contribute-to-pull-requests bits come entirely from group membership,
+ *     which Access Control Lists Query below can only expand server-side
+ *     when given a LEGACY descriptor, never a raw Graph one — and that
+ *     server-side expansion already correctly combines group membership
+ *     WITH token-level inheritance, which is why this checker queries the
+ *     ACL with ONLY the agent's own legacy descriptor and trusts its
+ *     `effectiveAllow`/`effectiveDeny` directly, never a client-side union
+ *     across separately-queried group descriptors — see
+ *     lib/graph-identity.ts's `resolveLegacyDescriptor()` doc comment,
+ *     "SECOND REVIEW", for the full live evidence and why an earlier
+ *     per-group-union attempt was wrong.)
+ *     GET https://vssps.dev.azure.com/{org}/_apis/identities?subjectDescriptors=<descriptor>&queryMembership=ExpandedUp&api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/ims/identities/read-identities
  *   - Identities — Read Identities (resolve a BUILD SERVICE's descriptor by
  *     exact display name — a build service is not a Graph 'User'/'Group'
  *     subject, so Subject Query above cannot find it; used only by
@@ -81,7 +103,12 @@
 
 import { resolveAgentIdentity } from "./lib/agent-identity.ts";
 import { AdoClient, resolveOrg, resolveProject, resolveRepository } from "./lib/client.ts";
-import { fetchJson, resolveAgentDescriptor, resolveIdentityByDisplayName } from "./lib/graph-identity.ts";
+import {
+  fetchJson,
+  isProjectBuildServiceDescriptor,
+  resolveAgentLegacyDescriptor,
+  resolveIdentityByDisplayName,
+} from "./lib/graph-identity.ts";
 
 /** Treat blank and whitespace-only env overrides as unset, like lib/client.ts's own `configured()`. */
 function configured(value: string | undefined): string | undefined {
@@ -95,9 +122,10 @@ function orgBaseUrl(): string {
 }
 
 // fetchJson/postJson (bearer-token GET/POST against an arbitrary Azure DevOps
-// host) and resolveAgentDescriptor (Graph Subject Query) live in
-// ./lib/graph-identity.ts — this file only adds its own orgBaseUrl() (the
-// accesscontrollists host); vsspsBaseUrl() moved with the Graph helpers.
+// host) and resolveAgentLegacyDescriptor (Graph Subject Query + Identities —
+// ExpandedUp) live in ./lib/graph-identity.ts — this file only adds its own
+// orgBaseUrl() (the accesscontrollists host); vsspsBaseUrl() moved with the
+// Graph helpers.
 
 // -------------------------------------------------------------------------
 // The standard, in one place.
@@ -157,6 +185,18 @@ export const REPO_STANDARD = {
   // repeats a bit name or a token shape in two places.
   permissions: {
     namespaceId: GIT_REPOSITORIES_NAMESPACE_ID,
+    /**
+     * Tarun, 2026-09-30: "leave [agent-reviewer's] permissions as they are
+     * and stop flagging it outside Enact." agent-reviewer's own
+     * `genericContribute` DENY check below (the Reader-only / no-Contribute
+     * rule) is scoped to the Enact project only — the SAME
+     * `STRICT_MAIN_BRANCH_PROJECT` mechanism (`repoInfo.project.name`,
+     * case-insensitive) the main-branch rules already use, enforced in
+     * `checkAgentBits()`'s own `ENACT_ONLY_AGENT_DENY` check just below.
+     * Every OTHER agent-permission check here — agent-tarun's and
+     * agent-vivek's full allow/deny sets, and agent-reviewer's own required
+     * `pullRequestContribute` — stays unconditional, for every project.
+     */
     agents: {
       "agent-tarun": {
         allow: ["genericContribute", "pullRequestContribute"],
@@ -166,7 +206,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>`,
@@ -174,12 +216,17 @@ 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
+     * 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`.
+     *
+     * 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[] },
@@ -187,12 +234,28 @@ export const REPO_STANDARD = {
     },
     /**
      * checkBuildServiceCanRelease() (file header, "checkBuildServiceCanRelease()"):
-     * the exact three repo-scope 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 the third one.
+     * 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`.
+     *
+     * `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.
      */
     buildServiceRelease: {
-      required: ["genericContribute", "policyExempt", "pullRequestContribute"] as const,
+      repoScoped: ["genericContribute", "pullRequestContribute"] as const,
+      integrationRefScoped: ["policyExempt"] as const,
     },
   },
 } as const;
@@ -219,7 +282,7 @@ export const GIT_REPO_PERMISSION_UI_LABEL: Record<PermissionBitName, string> = {
 interface GitRepositoryResponse {
   id: string;
   defaultBranch?: string;
-  project?: { id?: string };
+  project?: { id?: string; name?: string };
 }
 
 interface GitRefsResponse {
@@ -265,6 +328,39 @@ interface AccessControlListsResponse {
   }>;
 }
 
+/**
+ * Tarun, 2026-09-30: the strict main-branch rules below — the build service
+ * must not have PolicyExempt (bypass) on refs/heads/main
+ * (`permissions.build-service.has-policyExempt-main`) and main's
+ * minimum-reviewer policy must have creatorVoteCounts=false
+ * (`main.minimum-reviewers-misconfigured: creatorVoteCounts must be false`)
+ * — apply ONLY to repositories in the Azure DevOps project "Enact".
+ * Repositories in "Infrastructure-AzDo" (the small internal tool repos:
+ * adl-agent-control, agent-identities, …) keep their existing settings and
+ * must not be flagged for these two; every other check in this file stays
+ * exactly as is, for every project. Real evidence this fix responds to:
+ * `adl repo doctor --repo agent-identities` (Infrastructure-AzDo) reported
+ * both findings before this change.
+ *
+ * Scoped from the REPOSITORY'S OWN project, as Git Repositories — Get
+ * Repository's response names it (`repoInfo.project.name`) — NEVER
+ * `resolveProject()`/cwd/env (independent review, 2026-09-30: cwd/env name
+ * the project the CALLING checkout happens to sit in, which can differ from
+ * the project the repository being CHECKED actually lives in; the doctor
+ * already resolves the repository by name against whichever project cwd/env
+ * picked, but the compliance decision must follow the checked repository,
+ * not the caller's own working directory). Compared case-insensitively,
+ * since Azure DevOps project names are case-preserving but not
+ * case-sensitive for identity purposes. No environment variable controls
+ * this; a per-repository override, if one is ever genuinely needed, belongs
+ * in that repository's own adl-config.toml / manifest, never an env var.
+ */
+export const STRICT_MAIN_BRANCH_PROJECT = "Enact";
+
+function strictMainBranchRulesApply(project: string): boolean {
+  return project.toLowerCase() === STRICT_MAIN_BRANCH_PROJECT.toLowerCase();
+}
+
 export interface RepoDoctorDrift {
   id: string;
   message: string;
@@ -367,7 +463,11 @@ function checkMainRequiredReviewer(policies: readonly PolicyConfiguration[], dri
   });
 }
 
-function checkMainMinimumReviewers(policies: readonly PolicyConfiguration[], drifts: RepoDoctorDrift[]): void {
+function checkMainMinimumReviewers(
+  policies: readonly PolicyConfiguration[],
+  strictMainBranchRules: boolean,
+  drifts: RepoDoctorDrift[],
+): void {
   const minReviewer = enabledPolicyOfType(policies, POLICY_TYPE.minimumReviewers);
   if (!minReviewer) {
     drifts.push({
@@ -382,7 +482,9 @@ function checkMainMinimumReviewers(policies: readonly PolicyConfiguration[], dri
   if (minReviewer.isBlocking !== expected.isBlocking) problems.push(`isBlocking must be ${expected.isBlocking}`);
   if ((settings.minimumApproverCount ?? 0) < expected.minimumApproverCount)
     problems.push(`minimumApproverCount must be at least ${expected.minimumApproverCount}`);
-  if (Boolean(settings.creatorVoteCounts) !== expected.creatorVoteCounts)
+  // Enact-only (STRICT_MAIN_BRANCH_PROJECT above): a repo outside Enact keeps
+  // its own creatorVoteCounts setting, flagged neither way.
+  if (strictMainBranchRules && Boolean(settings.creatorVoteCounts) !== expected.creatorVoteCounts)
     problems.push(`creatorVoteCounts must be ${expected.creatorVoteCounts}`);
   if (Boolean(settings.resetOnSourcePush) !== expected.resetOnSourcePush)
     problems.push(`resetOnSourcePush must be ${expected.resetOnSourcePush}`);
@@ -437,10 +539,11 @@ function checkMainCommentsAndBuild(
 function checkMainPolicies(
   policies: readonly PolicyConfiguration[],
   hasPipeline: boolean,
+  strictMainBranchRules: boolean,
   drifts: RepoDoctorDrift[],
 ): void {
   checkMainRequiredReviewer(policies, drifts);
-  checkMainMinimumReviewers(policies, drifts);
+  checkMainMinimumReviewers(policies, strictMainBranchRules, drifts);
   checkMainMergeStrategy(policies, drifts);
   checkMainCommentsAndBuild(policies, hasPipeline, drifts);
 }
@@ -462,50 +565,128 @@ async function fetchAccessControlLists(
   return fetchJson<AccessControlListsResponse>(url, "Access control lists query");
 }
 
-async function fetchEffectivePermissions(
+/**
+ * Comfortably under every documented and empirically observed URL-length
+ * limit for this API (independent review, 2026-09-30: "keep the
+ * query-string size bounded" — an identity's transitive group-membership
+ * count is unbounded in principle, and three agents' descriptor sets get
+ * combined into one call). `fetchEffectivePermissions()` below chunks
+ * automatically rather than ever sending one unbounded `descriptors` list —
+ * never a silent truncation: a failed chunk's fetch throws, same as a
+ * failed single-descriptor call always did.
+ */
+export const MAX_DESCRIPTORS_PER_ACL_QUERY = 50;
+
+function chunk<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
+  return chunks;
+}
+
+export interface EffectivePermissionsResult {
+  byDescriptor: Map<string, { allow: number; deny: number }>;
+  /**
+   * Requested descriptors that never ended up in `byDescriptor` — either
+   * ABSENT from every chunk's `acesDictionary` entirely, or present but with
+   * NO `extendedInfo` key at all (checked via `'extendedInfo' in ace`, which
+   * distinguishes "the key is not there" from "the key is `{}`"). Both mean
+   * the effective bits could not actually be confirmed for that descriptor
+   * at this token. An entry that HAS `extendedInfo`, even `extendedInfo: {}`
+   * (a real, normal shape: the server computed it and every field happened
+   * to be zero/omitted), is NOT unresolved — it lands in `byDescriptor` with
+   * allow/deny defaulted to 0 exactly as before (independent review,
+   * 2026-09-30, LOW: "an entry that HAS extendedInfo with zero-valued
+   * fields omitted is normal and stays as today"). The caller MUST check
+   * this list and raise its own loud, distinct finding naming the identity
+   * and the token — never silently default an unresolved descriptor to
+   * `{allow: 0, deny: 0}`, which previously made a real "cannot confirm"
+   * look identical to "confirmed: nothing granted" (e.g. the Enact
+   * build-service refs/heads/main PolicyExempt DENY check silently PASSED
+   * when its own ACL entry was missing, instead of failing loudly).
+   */
+  unresolved: string[];
+}
+
+/** Exported for testing: proves the chunking guard above merges every chunk's result, including the last one, rather than sending — or silently dropping — one unbounded query. */
+export async function fetchEffectivePermissions(
   namespaceId: string,
   token: string,
   descriptors: readonly string[],
-): Promise<Map<string, { allow: number; deny: number }>> {
+): Promise<EffectivePermissionsResult> {
   const byDescriptor = new Map<string, { allow: number; deny: number }>();
-  if (descriptors.length === 0) return byDescriptor;
-  const result = await fetchAccessControlLists(namespaceId, token, descriptors);
-  for (const acl of result.value ?? []) {
-    for (const [descriptor, ace] of Object.entries(acl.acesDictionary ?? {})) {
-      byDescriptor.set(descriptor, {
-        allow: ace.extendedInfo?.effectiveAllow ?? ace.allow ?? 0,
-        deny: ace.extendedInfo?.effectiveDeny ?? ace.deny ?? 0,
-      });
+  if (descriptors.length === 0) return { byDescriptor, unresolved: [] };
+  for (const batch of chunk(descriptors, MAX_DESCRIPTORS_PER_ACL_QUERY)) {
+    const result = await fetchAccessControlLists(namespaceId, token, batch);
+    for (const acl of result.value ?? []) {
+      for (const [descriptor, ace] of Object.entries(acl.acesDictionary ?? {})) {
+        if (!("extendedInfo" in ace)) continue; // see EffectivePermissionsResult.unresolved's doc comment
+        byDescriptor.set(descriptor, {
+          allow: ace.extendedInfo?.effectiveAllow ?? ace.allow ?? 0,
+          deny: ace.extendedInfo?.effectiveDeny ?? ace.deny ?? 0,
+        });
+      }
     }
   }
-  return byDescriptor;
+  const unresolved = descriptors.filter((descriptor) => !byDescriptor.has(descriptor));
+  return { byDescriptor, unresolved };
 }
 
-/** Resolves every agent's Graph descriptor, reporting an unresolved name as its own drift rather than throwing. */
-async function resolveAgentDescriptors(drifts: RepoDoctorDrift[]): Promise<Map<string, string>> {
-  const descriptorByAgent = new Map<string, string>();
-  for (const name of Object.keys(REPO_STANDARD.permissions.agents)) {
-    const descriptor = await resolveAgentDescriptor(name);
-    if (!descriptor) {
-      drifts.push({
-        id: `permissions.${name}.not-found`,
-        message: `could not resolve a Graph descriptor for '${name}' (Graph subject query returned no exact display-name match)`,
-      });
-      continue;
-    }
-    descriptorByAgent.set(name, descriptor);
-  }
-  return descriptorByAgent;
+/**
+ * Look up `descriptor`'s effective ACE in `effective`, or push a loud,
+ * distinct `permissions.<idFragment>.acl-entry-missing<idSuffix>` finding
+ * naming `description` and `token` and return undefined — the caller must
+ * then skip whatever bit checks it was about to run for this identity/token
+ * pair, never fall back to `{allow: 0, deny: 0}` (see
+ * `EffectivePermissionsResult.unresolved`'s doc comment for why that
+ * silently hid real forbidden-bit findings).
+ */
+function resolveEffectiveAce(
+  effective: EffectivePermissionsResult,
+  descriptor: string,
+  idFragment: string,
+  idSuffix: string,
+  description: string,
+  tokenLabel: string,
+  drifts: RepoDoctorDrift[],
+): { allow: number; deny: number } | undefined {
+  const ace = effective.byDescriptor.get(descriptor);
+  if (ace) return ace;
+  drifts.push({
+    id: `permissions.${idFragment}.acl-entry-missing${idSuffix}`,
+    message: `could not confirm ${description}'s effective permissions on ${tokenLabel} — its Access Control Lists Query entry was missing from the response (or had no extendedInfo at all), never treated as "no permission"`,
+  });
+  return undefined;
+}
+
+/**
+ * `ace.allow` bits with `ace.deny` bits removed — Azure DevOps: an explicit
+ * Deny always beats an Allow FOR THE SAME EFFECTIVE RESULT. `ace` here is
+ * always the SERVER's own already-combined `effectiveAllow`/`effectiveDeny`
+ * for ONE descriptor at ONE token (see `checkAgentPermissions()`'s doc
+ * comment for why this file never reconstructs that combination itself from
+ * several descriptors — the server already does it correctly, including
+ * token-level precedence a client-side union cannot see).
+ */
+function effectiveAllowBits(ace: { allow: number; deny: number }): number {
+  return ace.allow & ~ace.deny;
 }
 
+/** The ONE agent-permission check scoped to Enact (Tarun, 2026-09-30) — see `REPO_STANDARD.permissions.agents`'s own doc comment above for why. */
+const ENACT_ONLY_AGENT_DENY: { readonly name: string; readonly bit: PermissionBitName } = {
+  name: "agent-reviewer",
+  bit: "genericContribute",
+};
+
 function checkAgentBits(
   name: string,
   ace: { allow: number; deny: number },
   expected: { allow: readonly PermissionBitName[]; deny: readonly PermissionBitName[] },
+  strictMainBranchRules: boolean,
   drifts: RepoDoctorDrift[],
 ): void {
+  const effective = effectiveAllowBits(ace);
   for (const bitName of expected.allow) {
-    if ((ace.allow & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
+    if ((effective & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
       drifts.push({
         id: `permissions.${name}.missing-${bitName}`,
         message: `${name} does not effectively have ${bitName} on this repository`,
@@ -513,7 +694,10 @@ function checkAgentBits(
     }
   }
   for (const bitName of expected.deny) {
-    if ((ace.allow & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) {
+    if (!strictMainBranchRules && name === ENACT_ONLY_AGENT_DENY.name && bitName === ENACT_ONLY_AGENT_DENY.bit) {
+      continue; // Tarun, 2026-09-30: leave agent-reviewer's permissions as they are outside Enact
+    }
+    if ((effective & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) {
       drifts.push({
         id: `permissions.${name}.has-${bitName}`,
         message: `${name} effectively has ${bitName} on this repository, which the standard forbids`,
@@ -522,9 +706,59 @@ function checkAgentBits(
   }
 }
 
+/**
+ * Resolves every agent's own LEGACY descriptor — see
+ * `resolveAgentLegacyDescriptor()`'s doc comment in lib/graph-identity.ts
+ * for the full live evidence this is built on (agent-tarun/agent-vivek/
+ * agent-reviewer hold no direct ACE at all in this org; their real
+ * Contribute/Contribute-to-pull-requests bits come entirely from group
+ * membership, and the Access Control Lists Query API cannot evaluate a raw
+ * Graph descriptor at all). `not-found` (Graph could not resolve the
+ * display name) and `expansion-failed` (Graph resolved it, but Identities —
+ * ExpandedUp could not) are reported as DISTINCT drifts rather than one
+ * generic failure — each names a different hop and a different fix.
+ * Identity lookups are cached across all three agents inside
+ * lib/graph-identity.ts (resetLegacyDescriptorCacheForTests()).
+ */
+async function resolveAgentDescriptors(drifts: RepoDoctorDrift[]): Promise<Map<string, string>> {
+  const descriptorByAgent = new Map<string, string>();
+  for (const name of Object.keys(REPO_STANDARD.permissions.agents)) {
+    const resolved = await resolveAgentLegacyDescriptor(name);
+    if ("error" in resolved) {
+      const message =
+        resolved.error === "not-found"
+          ? `could not resolve a Graph descriptor for '${name}' (Graph subject query returned no exact display-name match)`
+          : `resolved a Graph descriptor for '${name}' but could not expand it to a legacy identity (Identities — Read Identities with queryMembership=ExpandedUp returned no match)`;
+      drifts.push({ id: `permissions.${name}.${resolved.error}`, message });
+      continue;
+    }
+    descriptorByAgent.set(name, resolved.descriptor);
+  }
+  return descriptorByAgent;
+}
+
+/**
+ * Independent review, 2026-09-30 (second pass — design correction): an
+ * earlier version of this check queried EACH agent's own descriptor AND
+ * every group it transitively belongs to, then unioned their allow/deny
+ * bits client-side. That is wrong in general: the security service's own
+ * per-descriptor evaluation already combines group membership WITH
+ * token-level inheritance using real precedence (an explicit Allow at the
+ * repo-scope token can override an inherited Deny that came down from the
+ * project-scope token) — live-verified on agent-tarun's real legacy
+ * descriptor (`effectiveAllow: 82038` with no direct ACE anywhere, i.e.
+ * fully server-computed from its group). A client-side union of
+ * separately-queried group ACEs cannot see WHICH token level a bit came
+ * from and can therefore disagree with the server: a false `missing-*`,
+ * or worse, silently hiding a real forbidden bit the server would report.
+ * The fix is to query the ACL with ONLY each agent's own legacy descriptor
+ * and trust ITS `effectiveAllow`/`effectiveDeny` directly — never to
+ * reconstruct that answer from parts.
+ */
 async function checkAgentPermissions(
   projectId: string | undefined,
   repositoryId: string,
+  strictMainBranchRules: boolean,
   drifts: RepoDoctorDrift[],
 ): Promise<void> {
   if (!projectId) {
@@ -544,7 +778,9 @@ async function checkAgentPermissions(
   for (const [name, expected] of Object.entries(REPO_STANDARD.permissions.agents)) {
     const descriptor = descriptorByAgent.get(name);
     if (!descriptor) continue; // already reported above
-    checkAgentBits(name, effective.get(descriptor) ?? { allow: 0, deny: 0 }, expected, drifts);
+    const ace = resolveEffectiveAce(effective, descriptor, name, "", name, "this repository", drifts);
+    if (!ace) continue; // already reported by resolveEffectiveAce()
+    checkAgentBits(name, ace, expected, strictMainBranchRules, drifts);
   }
 }
 
@@ -580,8 +816,7 @@ async function resolveBuildServiceDescriptor(namespaceId: string, projectId: str
   const result = await fetchAccessControlLists(namespaceId, `repoV2/${projectId}`);
   for (const acl of result.value ?? []) {
     for (const descriptor of Object.keys(acl.acesDictionary ?? {})) {
-      if (descriptor.startsWith("Microsoft.TeamFoundation.ServiceIdentity") && descriptor.includes(projectId))
-        return descriptor;
+      if (isProjectBuildServiceDescriptor(descriptor, projectId)) return descriptor;
     }
   }
   return undefined;
@@ -597,6 +832,7 @@ async function checkBuildServicePermissions(
   namespaceId: string,
   projectId: string | undefined,
   repositoryId: string,
+  strictMainBranchRules: boolean,
   drifts: RepoDoctorDrift[],
 ): Promise<void> {
   if (!projectId) return; // already reported by checkAgentPermissions()
@@ -610,40 +846,73 @@ async function checkBuildServicePermissions(
     return;
   }
 
+  // Deny-aware throughout (effectiveAllowBits()'s own doc comment): a
+  // single descriptor can itself carry both an allow and a deny
+  // bit (effectiveAllow/effectiveDeny are independent fields on the same
+  // ACE) — the build service's own group-membership situation is different
+  // from the agents' (live evidence: it holds direct ACEs everywhere this
+  // function checks, no group expansion needed), but the SAME deny-wins
+  // arithmetic applies regardless of where the bits came from.
   const repoToken = `repoV2/${projectId}/${repositoryId}`;
-  const repoEffective = (await fetchEffectivePermissions(namespaceId, repoToken, [descriptor])).get(descriptor) ?? {
-    allow: 0,
-    deny: 0,
-  };
-  for (const bitName of REPO_STANDARD.permissions.buildService.repo.allow) {
-    if ((repoEffective.allow & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
-      drifts.push({
-        id: `permissions.build-service.missing-${bitName}`,
-        message: `the project build service does not effectively have ${bitName} on this repository`,
-      });
+  const repoEffective = resolveEffectiveAce(
+    await fetchEffectivePermissions(namespaceId, repoToken, [descriptor]),
+    descriptor,
+    "build-service",
+    "",
+    "the project build service",
+    "this repository",
+    drifts,
+  );
+  if (repoEffective) {
+    for (const bitName of REPO_STANDARD.permissions.buildService.repo.allow) {
+      if ((effectiveAllowBits(repoEffective) & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
+        drifts.push({
+          id: `permissions.build-service.missing-${bitName}`,
+          message: `the project build service does not effectively have ${bitName} on this repository`,
+        });
+      }
     }
   }
 
   const integrationToken = `${repoToken}/refs/heads/${refNameHexUtf16Le("integration")}`;
-  const integrationEffective = (await fetchEffectivePermissions(namespaceId, integrationToken, [descriptor])).get(
+  const integrationEffective = resolveEffectiveAce(
+    await fetchEffectivePermissions(namespaceId, integrationToken, [descriptor]),
     descriptor,
-  ) ?? { allow: 0, deny: 0 };
-  for (const bitName of REPO_STANDARD.permissions.buildService.integrationRef.allow) {
-    if ((integrationEffective.allow & 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`,
-      });
+    "build-service",
+    "-integration",
+    "the project build service",
+    "refs/heads/integration",
+    drifts,
+  );
+  if (integrationEffective) {
+    for (const bitName of REPO_STANDARD.permissions.buildService.integrationRef.allow) {
+      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`,
+        });
+      }
     }
   }
 
+  // Enact-only (STRICT_MAIN_BRANCH_PROJECT above): a repo outside Enact keeps
+  // whatever PolicyExempt the build service already has on main, flagged
+  // neither way — skip the ACL read entirely rather than fetch-and-ignore.
+  if (!strictMainBranchRules) return;
+
   const mainToken = `${repoToken}/refs/heads/${refNameHexUtf16Le("main")}`;
-  const mainEffective = (await fetchEffectivePermissions(namespaceId, mainToken, [descriptor])).get(descriptor) ?? {
-    allow: 0,
-    deny: 0,
-  };
+  const mainEffective = resolveEffectiveAce(
+    await fetchEffectivePermissions(namespaceId, mainToken, [descriptor]),
+    descriptor,
+    "build-service",
+    "-main",
+    "the project build service",
+    "refs/heads/main",
+    drifts,
+  );
+  if (!mainEffective) return;
   for (const bitName of REPO_STANDARD.permissions.buildService.mainRef.deny) {
-    if ((mainEffective.allow & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) {
+    if ((effectiveAllowBits(mainEffective) & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) {
       drifts.push({
         id: `permissions.build-service.has-${bitName}-main`,
         message: `the project build service effectively has ${bitName} on refs/heads/main, which the standard forbids`,
@@ -672,6 +941,16 @@ 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
@@ -693,15 +972,21 @@ 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 the
- * three REPO_STANDARD.permissions.buildServiceRelease.required bits on the
- * repository token. 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.
+ * 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
+ * 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.
  */
 async function checkOneBuildServiceCanRelease(
   namespaceId: string,
   repoToken: string,
+  integrationRefToken: string,
   repository: string,
   displayName: string,
   drifts: RepoDoctorDrift[],
@@ -727,26 +1012,41 @@ async function checkOneBuildServiceCanRelease(
     return;
   }
 
-  let effective: { allow: number; deny: number };
-  try {
-    effective = (await fetchEffectivePermissions(namespaceId, repoToken, [descriptor])).get(descriptor) ?? {
-      allow: 0,
-      deny: 0,
-    };
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+  // 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.
+  async function effectiveAt(token: string, tokenLabel: string): Promise<{ allow: number; deny: number } | undefined> {
+    let effective: EffectivePermissionsResult;
+    try {
+      effective = await fetchEffectivePermissions(namespaceId, token, [descriptor!]);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      drifts.push({
+        id: `permissions.release.${slug}.acl-read-forbidden`,
+        message: `could not read the Git Repositories security ACL for '${displayName}' on '${repository}' (${tokenLabel} token) — the calling agent identity may lack rights to read repository security, so this cannot be confirmed either way: ${detail}`,
+      });
+      return undefined;
+    }
+    return resolveEffectiveAce(effective, descriptor!, `release.${slug}`, "", `'${displayName}'`, tokenLabel, drifts);
+  }
+
+  const repoEffective = await effectiveAt(repoToken, "repo-scope");
+  if (!repoEffective) return;
+  for (const bitName of REPO_STANDARD.permissions.buildServiceRelease.repoScoped) {
+    if ((effectiveAllowBits(repoEffective) & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) continue;
     drifts.push({
-      id: `permissions.release.${slug}.acl-read-forbidden`,
-      message: `could not read the Git Repositories security ACL for '${displayName}' on '${repository}' — the calling agent identity may lack rights to read repository security, so this cannot be confirmed either way: ${detail}`,
+      id: `permissions.release.${slug}.missing-${bitName}`,
+      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)}`,
     });
-    return;
   }
 
-  for (const bitName of REPO_STANDARD.permissions.buildServiceRelease.required) {
-    if ((effective.allow & GIT_REPO_PERMISSION_BIT[bitName]) !== 0) continue;
+  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 '${repository}' — the release pipeline will 403 the way agent-identities build 4897 did. Fix: ${releaseFixPath(repository, displayName, 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)}`,
     });
   }
 }
@@ -779,8 +1079,9 @@ 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, repository, displayName, drifts);
+    await checkOneBuildServiceCanRelease(namespaceId, repoToken, integrationRefToken, repository, displayName, drifts);
   }
 }
 
@@ -825,14 +1126,30 @@ export async function repoDoctorCheck(options: RepoDoctorOptions = {}): Promise<
     });
   }
 
+  const repositoryProjectName = repoInfo.project?.name;
+  if (!repositoryProjectName) {
+    drifts.push({
+      id: "branches.no-project-name",
+      message:
+        "Git Repositories — Get Repository response did not include a project name; cannot determine whether the Enact-only main-branch rules (STRICT_MAIN_BRANCH_PROJECT) apply to this repository",
+    });
+  }
+  const strictMainBranchRules = repositoryProjectName ? strictMainBranchRulesApply(repositoryProjectName) : false;
+
   const hasPipeline = await repositoryHasAPipeline(c, repositoryId);
   const integrationPolicies = await fetchBranchPolicies(c, repositoryId, "integration");
   const mainPolicies = await fetchBranchPolicies(c, repositoryId, "main");
   checkIntegrationPolicies(integrationPolicies, hasPipeline, drifts);
-  checkMainPolicies(mainPolicies, hasPipeline, drifts);
+  checkMainPolicies(mainPolicies, hasPipeline, strictMainBranchRules, drifts);
 
-  await checkAgentPermissions(projectId, repositoryId, drifts);
-  await checkBuildServicePermissions(REPO_STANDARD.permissions.namespaceId, projectId, repositoryId, drifts);
+  await checkAgentPermissions(projectId, repositoryId, strictMainBranchRules, drifts);
+  await checkBuildServicePermissions(
+    REPO_STANDARD.permissions.namespaceId,
+    projectId,
+    repositoryId,
+    strictMainBranchRules,
+    drifts,
+  );
   await checkBuildServiceCanRelease(c, REPO_STANDARD.permissions.namespaceId, projectId, repositoryId, repository, drifts);
 
   return { repository, compliant: drifts.length === 0, drifts };