@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

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

@@ -0,0 +1,839 @@
+/**
+ * C9 (docs/specs/two-branch-standard-2026-09-27.md §3.3, §1a): read-only
+ * check of one repository against the two-branch standard. Same token path
+ * as every other tool in this package (the session's own agent identity via
+ * lib/agent-identity.ts) — no separate credential, no mutation.
+ *
+ * REPO_STANDARD below is the single place the standard's expected values
+ * live; every check reads from it rather than repeating a literal.
+ *
+ * REST APIs used (verified against Microsoft's docs 2026-09-27):
+ *   - Git Repositories — Get Repository
+ *     GET {org}/{project}/_apis/git/repositories/{repository}?api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/git/repositories/get-repository
+ *   - Git Refs — List (branches)
+ *     GET {org}/{project}/_apis/git/repositories/{repositoryId}/refs?filter=heads/&api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/git/refs/list
+ *   - Build Definitions — List (has-a-pipeline probe; already used by azdo-pl.ts)
+ *     GET {org}/{project}/_apis/build/definitions?repositoryId=..&repositoryType=TfsGit&api-version=7.1
+ *   - Git-scoped Policy Configurations (repository + branch scoped; the plain
+ *     /_apis/policy/configurations List doc itself names this as the one to
+ *     use for scope filtering: "Instead, use the /_apis/git/policy/configurations
+ *     API, which provides first class scope filtering support." Already used
+ *     the same way by packages/repo-controls/src/azure-devops-governance.ts.)
+ *     GET {org}/{project}/_apis/git/policy/configurations?repositoryId=..&refName=refs/heads/{branch}&api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/policy/configurations/list
+ *   - Security — Access Control Lists Query (Git Repositories namespace)
+ *     GET {org}/_apis/accesscontrollists/{namespaceId}?token=repoV2/{projectId}/{repositoryId}
+ *         &descriptors=<comma-separated>&includeExtendedInfo=true&api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/security/access-control-lists/query
+ *     (namespace id, token shape and the READ/CONTRIBUTE/PR_CONTRIBUTE bit
+ *     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)
+ *     POST https://vssps.dev.azure.com/{org}/_apis/graph/subjectquery?api-version=7.1-preview.1
+ *     body: { query: <displayName>, subjectKind: ['User'] }
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/graph/subject-query/query
+ *   - 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
+ *     checkBuildServiceCanRelease() below, lib/graph-identity.ts's
+ *     resolveIdentityByDisplayName())
+ *     GET https://vssps.dev.azure.com/{org}/_apis/identities?searchFilter=General&filterValue=<name>&queryMembership=None&api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/ims/identities/read-identities
+ *   - Build — General Settings — Get (which build service identity actually
+ *     runs the pipeline: `enforceJobAuthScope` is "Limit job authorization
+ *     scope to current project" in the UI — true means the PROJECT-scoped
+ *     build service runs the job, false means the ORG/COLLECTION-scoped one
+ *     does; used only by checkBuildServiceCanRelease() below)
+ *     GET {org}/{project}/_apis/build/generalsettings?api-version=7.1
+ *     https://learn.microsoft.com/en-us/rest/api/azure/devops/build/general-settings/get
+ *
+ * checkBuildServiceCanRelease() (C9 follow-up, Tarun 2026-09-29): a real
+ * pipeline failure — agent-identities build 4897, stage "Create integration
+ * to main PR" (packages/repo-controls/assets/promote.ts) — 403'd with
+ * `TF401027: You need the Git 'PullRequestContribute' permission ... identity
+ * 'Build\<projectId>', scope 'repository'`. checkBuildServicePermissions()
+ * above already checks a DIFFERENT, finer-grained set of per-branch bits for
+ * a different purpose (branch-scoped PolicyExempt allow/deny) and stops at
+ * "not found" for an unresolvable identity; it does not name the exact
+ * identity display name or the fix path, and a 403 reading the ACL itself
+ * propagates out of `repoDoctorCheck()` uncaught rather than being reported
+ * 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,
+ * 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.
+ *
+ * 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
+ *   required reviewers  fd2167ab-b0be-447a-8ec8-39368250530e
+ *   build validation    0609b952-1397-4640-95ec-e00a01b2c241
+ *   merge strategy      fa4e907d-c16b-4a4c-9dfa-4916e5d171ab
+ *   comment requirements c6a1889d-b943-4856-b76f-9e46bb6b0df2
+ */
+
+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";
+
+/** Treat blank and whitespace-only env overrides as unset, like lib/client.ts's own `configured()`. */
+function configured(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/** The org-root REST base (no project segment) — accesscontrollists lives here, not under a project. */
+function orgBaseUrl(): string {
+  return configured(process.env.AZURE_DEVOPS_ORG_BASE_URL) ?? `https://dev.azure.com/${resolveOrg()}`;
+}
+
+// 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.
+
+// -------------------------------------------------------------------------
+// The standard, in one place.
+// -------------------------------------------------------------------------
+
+export const POLICY_TYPE = {
+  minimumReviewers: "fa4e907d-c16b-4a4c-9dfa-4906e5d171dd",
+  requiredReviewers: "fd2167ab-b0be-447a-8ec8-39368250530e",
+  build: "0609b952-1397-4640-95ec-e00a01b2c241",
+  mergeStrategy: "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab",
+  commentRequirements: "c6a1889d-b943-4856-b76f-9e46bb6b0df2",
+} as const;
+
+/** Git Repositories security namespace (2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87) permission bits, read live 2026-09-26 — see the file header for the source. */
+export const GIT_REPO_PERMISSION_BIT = {
+  genericRead: 2,
+  genericContribute: 4,
+  forcePush: 8,
+  policyExempt: 128,
+  pullRequestContribute: 16384,
+  pullRequestBypassPolicy: 32768,
+} as const;
+
+export const GIT_REPOSITORIES_NAMESPACE_ID = "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87";
+
+type PermissionBitName = keyof typeof GIT_REPO_PERMISSION_BIT;
+
+export const REPO_STANDARD = {
+  branches: {
+    required: ["integration", "main"] as const,
+    forbidden: ["develop"] as const,
+    defaultBranch: "main",
+  },
+  integration: {
+    // No human gate: neither a minimum-reviewer nor a required-reviewer
+    // policy may be enabled here.
+    forbiddenReviewerPolicies: [POLICY_TYPE.minimumReviewers, POLICY_TYPE.requiredReviewers] as const,
+    mergeStrategy: { allowSquash: true, allowRebase: false, allowRebaseMerge: false, allowNoFastForward: false },
+    buildValidationRequiredWhenPipelineExists: true,
+  },
+  main: {
+    minimumReviewers: { minimumApproverCount: 1, creatorVoteCounts: false, resetOnSourcePush: true, isBlocking: true },
+    // A named required reviewer is forbidden, not merely optional: Tarun,
+    // 2026-09-27, "I should not be required for it" — the promotion PR
+    // (raised by the pipeline, not directed by a human) is approved by ANY
+    // one human via the minimum-reviewer policy above; naming one reviewer
+    // would make that person a standing approval bottleneck the standard
+    // never asked for. docs/specs/two-branch-standard-2026-09-27.md §1b.1,
+    // §1b.6; ADL-ISMS-Policies docs/questions.md A121.
+    forbiddenReviewerPolicies: [POLICY_TYPE.requiredReviewers] as const,
+    mergeStrategy: { allowSquash: false, allowRebase: false, allowRebaseMerge: false, allowNoFastForward: true },
+    commentRequirementsRequired: true,
+    buildValidationRequiredWhenPipelineExists: true,
+  },
+  // One table for every effective-permission expectation this checker reads
+  // via the Git Repositories security namespace ACL, so the standard never
+  // repeats a bit name or a token shape in two places.
+  permissions: {
+    namespaceId: GIT_REPOSITORIES_NAMESPACE_ID,
+    agents: {
+      "agent-tarun": {
+        allow: ["genericContribute", "pullRequestContribute"],
+        deny: ["forcePush", "policyExempt", "pullRequestBypassPolicy"],
+      },
+      "agent-vivek": {
+        allow: ["genericContribute", "pullRequestContribute"],
+        deny: ["forcePush", "policyExempt", "pullRequestBypassPolicy"],
+      },
+      "agent-reviewer": { allow: ["pullRequestContribute"], deny: ["genericContribute"] },
+    } as Record<string, { allow: readonly PermissionBitName[]; deny: readonly PermissionBitName[] }>,
+    /**
+     * The project's build service identity (display name `Build\<projectId>`,
+     * descriptor `Microsoft.TeamFoundation.ServiceIdentity;...<projectId>...`
+     * — 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`.
+     */
+    buildService: {
+      repo: { allow: ["genericContribute", "forcePush", "pullRequestContribute"] } as {
+        allow: readonly PermissionBitName[];
+      },
+      integrationRef: { allow: ["policyExempt"] } as { allow: readonly PermissionBitName[] },
+      mainRef: { deny: ["policyExempt"] } as { deny: readonly PermissionBitName[] },
+    },
+    /**
+     * 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.
+     */
+    buildServiceRelease: {
+      required: ["genericContribute", "policyExempt", "pullRequestContribute"] as const,
+    },
+  },
+} as const;
+
+/**
+ * The Azure DevOps Repos "Security" tab's own label for each permission bit
+ * (Set Git repository permissions —
+ * https://learn.microsoft.com/en-us/azure/devops/repos/git/set-git-repository-permissions),
+ * used only to build the fix-path message a human follows in that same UI.
+ */
+export const GIT_REPO_PERMISSION_UI_LABEL: Record<PermissionBitName, string> = {
+  genericRead: "Read",
+  genericContribute: "Contribute",
+  forcePush: "Force push (rewrite history, delete branches and tags)",
+  policyExempt: "Bypass policies when pushing",
+  pullRequestContribute: "Contribute to pull requests",
+  pullRequestBypassPolicy: "Bypass policies when completing pull requests",
+};
+
+// -------------------------------------------------------------------------
+// Azure DevOps response shapes (only the fields this checker reads).
+// -------------------------------------------------------------------------
+
+interface GitRepositoryResponse {
+  id: string;
+  defaultBranch?: string;
+  project?: { id?: string };
+}
+
+interface GitRefsResponse {
+  value?: Array<{ name: string }>;
+}
+
+interface BuildDefinitionsResponse {
+  value?: Array<{ id: number }>;
+}
+
+/** Build — General Settings — Get response (only the field this checker reads). */
+interface BuildGeneralSettingsResponse {
+  enforceJobAuthScope?: boolean;
+}
+
+interface PolicyConfiguration {
+  id?: number;
+  isEnabled?: boolean;
+  isBlocking?: boolean;
+  type?: { id?: string };
+  settings?: {
+    minimumApproverCount?: number;
+    creatorVoteCounts?: boolean;
+    resetOnSourcePush?: boolean;
+    buildDefinitionId?: number;
+    allowSquash?: boolean;
+    allowRebase?: boolean;
+    allowRebaseMerge?: boolean;
+    allowNoFastForward?: boolean;
+  };
+}
+
+interface PolicyConfigurationsResponse {
+  value?: PolicyConfiguration[];
+}
+
+interface AccessControlListsResponse {
+  value?: Array<{
+    acesDictionary?: Record<
+      string,
+      { allow?: number; deny?: number; extendedInfo?: { effectiveAllow?: number; effectiveDeny?: number } }
+    >;
+  }>;
+}
+
+export interface RepoDoctorDrift {
+  id: string;
+  message: string;
+}
+
+export interface RepoDoctorReport {
+  repository: string;
+  compliant: boolean;
+  drifts: RepoDoctorDrift[];
+}
+
+export interface RepoDoctorOptions {
+  /** Repository name; defaults to the current checkout's origin (via resolveRepository()). */
+  repository?: string;
+  /** Test seam: an AdoClient pointed at a stub, in place of the default singleton. */
+  client?: AdoClient;
+}
+
+function enabledPolicyOfType(
+  policies: readonly PolicyConfiguration[],
+  typeId: string,
+): PolicyConfiguration | undefined {
+  return policies.find((policy) => policy.type?.id === typeId && policy.isEnabled === true);
+}
+
+async function fetchBranchPolicies(c: AdoClient, repositoryId: string, branch: string): Promise<PolicyConfiguration[]> {
+  const result = await c.get<PolicyConfigurationsResponse>("/git/policy/configurations", {
+    repositoryId,
+    refName: `refs/heads/${branch}`,
+    "api-version": "7.1",
+  });
+  return result.value ?? [];
+}
+
+async function repositoryHasAPipeline(c: AdoClient, repositoryId: string): Promise<boolean> {
+  const result = await c.get<BuildDefinitionsResponse>("/build/definitions", {
+    repositoryId,
+    repositoryType: "TfsGit",
+    "api-version": "7.1",
+  });
+  return (result.value ?? []).length > 0;
+}
+
+function checkIntegrationPolicies(
+  policies: readonly PolicyConfiguration[],
+  hasPipeline: boolean,
+  drifts: RepoDoctorDrift[],
+): void {
+  const minReviewer = enabledPolicyOfType(policies, POLICY_TYPE.minimumReviewers);
+  if (minReviewer) {
+    drifts.push({
+      id: "integration.minimum-reviewers-enabled",
+      message: `integration has an enabled minimum-reviewer policy (#${minReviewer.id}); integration must have no human reviewer gate`,
+    });
+  }
+  const requiredReviewer = enabledPolicyOfType(policies, POLICY_TYPE.requiredReviewers);
+  if (requiredReviewer) {
+    drifts.push({
+      id: "integration.required-reviewer-enabled",
+      message: `integration has an enabled required-reviewer policy (#${requiredReviewer.id}); integration must have no human reviewer gate`,
+    });
+  }
+
+  const merge = enabledPolicyOfType(policies, POLICY_TYPE.mergeStrategy);
+  if (!merge) {
+    drifts.push({
+      id: "integration.merge-strategy-missing",
+      message: "integration is missing an enabled merge-strategy policy restricting merges to squash",
+    });
+  } else {
+    const settings = merge.settings ?? {};
+    const expected = REPO_STANDARD.integration.mergeStrategy;
+    const squashOnly =
+      Boolean(settings.allowSquash) === expected.allowSquash &&
+      Boolean(settings.allowRebase) === expected.allowRebase &&
+      Boolean(settings.allowRebaseMerge) === expected.allowRebaseMerge &&
+      Boolean(settings.allowNoFastForward) === expected.allowNoFastForward;
+    if (!squashOnly) {
+      drifts.push({
+        id: "integration.merge-strategy-not-squash-only",
+        message: `integration merge-strategy policy (#${merge.id}) does not restrict merges to squash only`,
+      });
+    }
+  }
+
+  if (hasPipeline) {
+    const build = enabledPolicyOfType(policies, POLICY_TYPE.build);
+    if (!build) drifts.push({ id: "integration.build-validation-missing", message: "missing build validation" });
+  }
+}
+
+// A named required reviewer on main is DRIFT (A121: "I should not be
+// required for it" — see REPO_STANDARD.main's comment above).
+function checkMainRequiredReviewer(policies: readonly PolicyConfiguration[], drifts: RepoDoctorDrift[]): void {
+  const requiredReviewer = enabledPolicyOfType(policies, POLICY_TYPE.requiredReviewers);
+  if (!requiredReviewer) return;
+  drifts.push({
+    id: "main.required-reviewer-enabled",
+    message: `main has an enabled required-reviewer policy (#${requiredReviewer.id}); no human may be named — any one approver satisfies the minimum-reviewer policy (A121)`,
+  });
+}
+
+function checkMainMinimumReviewers(policies: readonly PolicyConfiguration[], drifts: RepoDoctorDrift[]): void {
+  const minReviewer = enabledPolicyOfType(policies, POLICY_TYPE.minimumReviewers);
+  if (!minReviewer) {
+    drifts.push({
+      id: "main.minimum-reviewers-missing",
+      message: "main is missing an enabled minimum-reviewer policy",
+    });
+    return;
+  }
+  const settings = minReviewer.settings ?? {};
+  const expected = REPO_STANDARD.main.minimumReviewers;
+  const problems: string[] = [];
+  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)
+    problems.push(`creatorVoteCounts must be ${expected.creatorVoteCounts}`);
+  if (Boolean(settings.resetOnSourcePush) !== expected.resetOnSourcePush)
+    problems.push(`resetOnSourcePush must be ${expected.resetOnSourcePush}`);
+  if (problems.length === 0) return;
+  drifts.push({
+    id: "main.minimum-reviewers-misconfigured",
+    message: `main minimum-reviewer policy (#${minReviewer.id}) is misconfigured: ${problems.join("; ")}`,
+  });
+}
+
+function checkMainMergeStrategy(policies: readonly PolicyConfiguration[], drifts: RepoDoctorDrift[]): void {
+  const merge = enabledPolicyOfType(policies, POLICY_TYPE.mergeStrategy);
+  if (!merge) {
+    drifts.push({
+      id: "main.merge-strategy-missing",
+      message: "main is missing an enabled merge-strategy policy restricting merges to no-fast-forward",
+    });
+    return;
+  }
+  const settings = merge.settings ?? {};
+  const expected = REPO_STANDARD.main.mergeStrategy;
+  const noFastForwardOnly =
+    Boolean(settings.allowSquash) === expected.allowSquash &&
+    Boolean(settings.allowRebase) === expected.allowRebase &&
+    Boolean(settings.allowRebaseMerge) === expected.allowRebaseMerge &&
+    Boolean(settings.allowNoFastForward) === expected.allowNoFastForward;
+  if (noFastForwardOnly) return;
+  drifts.push({
+    id: "main.merge-strategy-not-no-ff-only",
+    message: `main merge-strategy policy (#${merge.id}) does not restrict merges to no-fast-forward only`,
+  });
+}
+
+function checkMainCommentsAndBuild(
+  policies: readonly PolicyConfiguration[],
+  hasPipeline: boolean,
+  drifts: RepoDoctorDrift[],
+): void {
+  const comments = enabledPolicyOfType(policies, POLICY_TYPE.commentRequirements);
+  if (!comments) {
+    drifts.push({
+      id: "main.comment-requirements-missing",
+      message: "main is missing an enabled comment-requirements policy",
+    });
+  }
+
+  if (!hasPipeline) return;
+  const build = enabledPolicyOfType(policies, POLICY_TYPE.build);
+  if (!build) drifts.push({ id: "main.build-validation-missing", message: "missing build validation" });
+}
+
+function checkMainPolicies(
+  policies: readonly PolicyConfiguration[],
+  hasPipeline: boolean,
+  drifts: RepoDoctorDrift[],
+): void {
+  checkMainRequiredReviewer(policies, drifts);
+  checkMainMinimumReviewers(policies, drifts);
+  checkMainMergeStrategy(policies, drifts);
+  checkMainCommentsAndBuild(policies, hasPipeline, drifts);
+}
+
+/**
+ * One Access Control Lists Query call for `token`. `descriptors` narrows the
+ * ACEs returned (comma-separated, per the REST docs); omitted or empty means
+ * "every ACE on this token", which is how `resolveBuildServiceDescriptor()`
+ * below finds a descriptor it does not know yet.
+ */
+async function fetchAccessControlLists(
+  namespaceId: string,
+  token: string,
+  descriptors?: readonly string[],
+): Promise<AccessControlListsResponse> {
+  const params = new URLSearchParams({ token, includeExtendedInfo: "true", "api-version": "7.1" });
+  if (descriptors && descriptors.length > 0) params.set("descriptors", descriptors.join(","));
+  const url = `${orgBaseUrl()}/_apis/accesscontrollists/${namespaceId}?${params.toString()}`;
+  return fetchJson<AccessControlListsResponse>(url, "Access control lists query");
+}
+
+async function fetchEffectivePermissions(
+  namespaceId: string,
+  token: string,
+  descriptors: readonly string[],
+): Promise<Map<string, { allow: number; deny: number }>> {
+  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,
+      });
+    }
+  }
+  return byDescriptor;
+}
+
+/** 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;
+}
+
+function checkAgentBits(
+  name: string,
+  ace: { allow: number; deny: number },
+  expected: { allow: readonly PermissionBitName[]; deny: readonly PermissionBitName[] },
+  drifts: RepoDoctorDrift[],
+): void {
+  for (const bitName of expected.allow) {
+    if ((ace.allow & GIT_REPO_PERMISSION_BIT[bitName]) === 0) {
+      drifts.push({
+        id: `permissions.${name}.missing-${bitName}`,
+        message: `${name} does not effectively have ${bitName} on this repository`,
+      });
+    }
+  }
+  for (const bitName of expected.deny) {
+    if ((ace.allow & 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`,
+      });
+    }
+  }
+}
+
+async function checkAgentPermissions(
+  projectId: string | undefined,
+  repositoryId: string,
+  drifts: RepoDoctorDrift[],
+): Promise<void> {
+  if (!projectId) {
+    drifts.push({
+      id: "permissions.no-project-id",
+      message: "could not determine the project id needed to build the permissions token",
+    });
+    return;
+  }
+  const descriptorByAgent = await resolveAgentDescriptors(drifts);
+
+  const token = `repoV2/${projectId}/${repositoryId}`;
+  const effective = await fetchEffectivePermissions(REPO_STANDARD.permissions.namespaceId, token, [
+    ...descriptorByAgent.values(),
+  ]);
+
+  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);
+  }
+}
+
+/**
+ * The Git Repositories token for a branch is `<repoToken>/refs/heads/<hex>`,
+ * where `<hex>` is the branch's ref name UTF-16LE-encoded and hex-dumped —
+ * https://devblogs.microsoft.com/devops/git-repo-tokens-for-the-security-service/,
+ * the same encoding
+ * ADL-ISMS-Policies/.scratchpad/ci_build_service_grant.py uses
+ * (`"integration".encode("utf-16-le")`). Branch names here are ASCII, so a
+ * plain per-character two-byte little-endian dump matches it exactly.
+ */
+export function refNameHexUtf16Le(name: string): string {
+  let hex = "";
+  for (let i = 0; i < name.length; i += 1) {
+    const code = name.charCodeAt(i);
+    hex += (code & 0xff).toString(16).padStart(2, "0");
+    hex += ((code >> 8) & 0xff).toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+/**
+ * The project's build service identity is not resolved through Graph (it is
+ * a `Microsoft.TeamFoundation.ServiceIdentity` descriptor, not a Graph
+ * subject) — it is found the same way
+ * ADL-ISMS-Policies/.scratchpad/ci_build_service_grant.py finds it: read the
+ * PROJECT-level ACL for this namespace (token `repoV2/<projectId>`, no
+ * descriptor filter — every ACE on that token comes back) and take the one
+ * service-identity descriptor that carries the project id.
+ */
+async function resolveBuildServiceDescriptor(namespaceId: string, projectId: string): Promise<string | undefined> {
+  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;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 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.
+ */
+async function checkBuildServicePermissions(
+  namespaceId: string,
+  projectId: string | undefined,
+  repositoryId: string,
+  drifts: RepoDoctorDrift[],
+): Promise<void> {
+  if (!projectId) return; // already reported by checkAgentPermissions()
+
+  const descriptor = await resolveBuildServiceDescriptor(namespaceId, projectId);
+  if (!descriptor) {
+    drifts.push({
+      id: "permissions.build-service.not-found",
+      message: `could not resolve the project's build service identity (Microsoft.TeamFoundation.ServiceIdentity;...${projectId}...) on the Git Repositories namespace`,
+    });
+    return;
+  }
+
+  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 integrationToken = `${repoToken}/refs/heads/${refNameHexUtf16Le("integration")}`;
+  const integrationEffective = (await fetchEffectivePermissions(namespaceId, integrationToken, [descriptor])).get(
+    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`,
+      });
+    }
+  }
+
+  const mainToken = `${repoToken}/refs/heads/${refNameHexUtf16Le("main")}`;
+  const mainEffective = (await fetchEffectivePermissions(namespaceId, mainToken, [descriptor])).get(descriptor) ?? {
+    allow: 0,
+    deny: 0,
+  };
+  for (const bitName of REPO_STANDARD.permissions.buildService.mainRef.deny) {
+    if ((mainEffective.allow & 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`,
+      });
+    }
+  }
+}
+
+/** "<project> Build Service (<org>)" / "Project Collection Build Service (<org>)" — the exact Security-tab display names of the two identities that could actually be running the pipeline. */
+function buildServiceDisplayNames(org: string, project: string): { projectScoped: string; collectionScoped: string } {
+  return {
+    projectScoped: `${project} Build Service (${org})`,
+    collectionScoped: `Project Collection Build Service (${org})`,
+  };
+}
+
+/** Stable, readable drift-id fragment from a display name, e.g. "Enact Build Service (amsterdamdatalabs)" -> "enact-build-service-amsterdamdatalabs". */
+function identitySlug(displayName: string): string {
+  return displayName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function releaseFixPath(repository: string, identityDisplayName: string, bitName: PermissionBitName): string {
+  return `Project settings → Repositories → \`${repository}\` → 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
+ * authorization scope to current project" in the UI: true means the
+ * PROJECT-scoped build service runs the job, false means the
+ * ORG/COLLECTION-scoped one does. `undefined` means the read itself failed
+ * (the calling agent may lack rights to read project settings) — "could not
+ * determine", not "assume project-scoped": the caller checks BOTH identities
+ * in that case rather than guessing one and staying silent about the other.
+ */
+async function fetchEnforceJobAuthScope(c: AdoClient): Promise<boolean | undefined> {
+  try {
+    const result = await c.get<BuildGeneralSettingsResponse>("/build/generalsettings", { "api-version": "7.1" });
+    return result.enforceJobAuthScope;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 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.
+ */
+async function checkOneBuildServiceCanRelease(
+  namespaceId: string,
+  repoToken: string,
+  repository: string,
+  displayName: string,
+  drifts: RepoDoctorDrift[],
+): Promise<void> {
+  const slug = identitySlug(displayName);
+
+  let descriptor: string | undefined;
+  try {
+    descriptor = await resolveIdentityByDisplayName(displayName);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    drifts.push({
+      id: `permissions.release.${slug}.identity-lookup-failed`,
+      message: `could not look up the Azure DevOps identity '${displayName}' (Identities - Read Identities call failed) — cannot confirm it can release: ${detail}`,
+    });
+    return;
+  }
+  if (!descriptor) {
+    drifts.push({
+      id: `permissions.release.${slug}.not-found`,
+      message: `could not resolve an Azure DevOps identity named '${displayName}' (Identities - Read Identities returned no exact display-name match) — cannot confirm it can release`,
+    });
+    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);
+    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}`,
+    });
+    return;
+  }
+
+  for (const bitName of REPO_STANDARD.permissions.buildServiceRelease.required) {
+    if ((effective.allow & 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)}`,
+    });
+  }
+}
+
+/**
+ * checkBuildServiceCanRelease() — see the file header for the real failure
+ * (agent-identities build 4897, TF401027 on PullRequestContribute) this
+ * exists to catch loudly instead of at pipeline-run time. Picks ONE identity
+ * to check when the project's own pipeline settings say which one runs the
+ * job; when that read itself fails, checks BOTH the project-scoped and the
+ * collection-scoped identity and reports each on its own.
+ */
+async function checkBuildServiceCanRelease(
+  c: AdoClient,
+  namespaceId: string,
+  projectId: string | undefined,
+  repositoryId: string,
+  repository: string,
+  drifts: RepoDoctorDrift[],
+): Promise<void> {
+  if (!projectId) return; // already reported by checkAgentPermissions()
+
+  const { projectScoped, collectionScoped } = buildServiceDisplayNames(resolveOrg(), resolveProject());
+  const enforceJobAuthScope = await fetchEnforceJobAuthScope(c);
+  const displayNames =
+    enforceJobAuthScope === true
+      ? [projectScoped]
+      : enforceJobAuthScope === false
+        ? [collectionScoped]
+        : [projectScoped, collectionScoped];
+
+  const repoToken = `repoV2/${projectId}/${repositoryId}`;
+  for (const displayName of displayNames) {
+    await checkOneBuildServiceCanRelease(namespaceId, repoToken, repository, displayName, drifts);
+  }
+}
+
+/**
+ * Read-only check of `repository` (default: the current checkout's origin)
+ * against the two-branch standard (REPO_STANDARD above). Never mutates
+ * anything in Azure DevOps. Throws only on identity/auth/transport failure —
+ * a compliance drift is reported in the returned list, not thrown.
+ */
+export async function repoDoctorCheck(options: RepoDoctorOptions = {}): Promise<RepoDoctorReport> {
+  resolveAgentIdentity();
+  const repository = resolveRepository(options.repository);
+  const c = options.client ?? new AdoClient();
+  const drifts: RepoDoctorDrift[] = [];
+
+  const repoInfo = await c.get<GitRepositoryResponse>(`/git/repositories/${repository}`, { "api-version": "7.1" });
+  const repositoryId = repoInfo.id;
+  const projectId = repoInfo.project?.id;
+
+  const refs = await c.get<GitRefsResponse>(`/git/repositories/${repositoryId}/refs`, {
+    filter: "heads/",
+    "api-version": "7.1",
+  });
+  const branchNames = new Set((refs.value ?? []).map((ref) => ref.name.replace(/^refs\/heads\//, "")));
+
+  for (const required of REPO_STANDARD.branches.required) {
+    if (!branchNames.has(required))
+      drifts.push({ id: `branches.missing-${required}`, message: `branch '${required}' does not exist` });
+  }
+  for (const forbidden of REPO_STANDARD.branches.forbidden) {
+    if (branchNames.has(forbidden))
+      drifts.push({
+        id: `branches.forbidden-${forbidden}`,
+        message: `branch '${forbidden}' exists and must be removed`,
+      });
+  }
+  const defaultBranch = (repoInfo.defaultBranch ?? "").replace(/^refs\/heads\//, "");
+  if (defaultBranch !== REPO_STANDARD.branches.defaultBranch) {
+    drifts.push({
+      id: "branches.default-branch",
+      message: `default branch is '${defaultBranch || "(unset)"}', expected '${REPO_STANDARD.branches.defaultBranch}'`,
+    });
+  }
+
+  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);
+
+  await checkAgentPermissions(projectId, repositoryId, drifts);
+  await checkBuildServicePermissions(REPO_STANDARD.permissions.namespaceId, projectId, repositoryId, drifts);
+  await checkBuildServiceCanRelease(c, REPO_STANDARD.permissions.namespaceId, projectId, repositoryId, repository, drifts);
+
+  return { repository, compliant: drifts.length === 0, drifts };
+}