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

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

@@ -84,24 +84,26 @@
  * 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 the PR's source (feature) branch (GenericContribute), and create/update
- * the `integration -> main` PR and set auto-complete
+ * ACTUALLY RUNS THE PIPELINE (repo scope) push a `[skip ci]` bump commit
+ * to `integration` (GenericContribute), bypass `integration`'s own policies
+ * while doing so (PolicyExempt, read at the integration REF token), 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.
+ * Release flow (Tarun, 2026-09-30, amended 2026-10-01): the CI pipeline runs
+ * on PRs into `integration` and bumps nothing; the promote pipeline runs on
+ * every push to `integration`, bumps the version with a plain fast-forward
+ * push of a `[skip ci]` commit straight to `integration` as the build
+ * service, then opens the `integration -> main` PR; a CD pipeline runs on
+ * pushes to `main`. So (a) the build service REQUIRES PolicyExempt on
+ * `integration` (and Contribute on the repo) — never on `main`, never
+ * ForcePush; (b) the release-identity check requires PolicyExempt at the
+ * integration ref token; (c) the promotion PR gets NO build validation
+ * (Tarun's approval is the only gate; CD runs after the merge), so `main`
+ * does not require 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):
@@ -164,7 +166,7 @@ export const GIT_REPOSITORIES_NAMESPACE_ID = "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd
 
 type PermissionBitName = keyof typeof GIT_REPO_PERMISSION_BIT;
 
-export const REPO_STANDARD = {
+const REPO_STANDARD = {
   branches: {
     required: ["integration", "main"] as const,
     forbidden: ["develop"] as const,
@@ -231,13 +233,10 @@ export const REPO_STANDARD = {
      * — Tarun, 2026-09-27, cross-checked against
      * /Users/tarunrana/Documents/ADL-ISMS-Policies/.scratchpad/ci_build_service_grant.py,
      * which grants exactly these bits on adl-agent-control). CI needs to push
-     * and complete PRs on the repo (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).
+     * and complete PRs on the repo, and needs PolicyExempt only on
+     * `integration` (Tarun, 2026-10-01: the integration-merge pipeline pushes
+     * the `[skip ci]` version bump straight to `integration`, which its own
+     * policies would block) — 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
@@ -248,28 +247,37 @@ export const REPO_STANDARD = {
       repo: { allow: ["genericContribute", "pullRequestContribute"] } as {
         allow: readonly PermissionBitName[];
       },
-      integrationRef: { deny: ["policyExempt"] } as { deny: readonly PermissionBitName[] },
+      // Tarun, 2026-10-01: an explicit gate on the build service's EFFECTIVE permissions on
+      // refs/heads/integration -- Contribute and "Bypass policies when pushing" (the
+      // `[skip ci]` bump push) required, Force push forbidden. Live reference: effective
+      // allow 16550 = read + contribute + createTag + policyExempt + pullRequestContribute.
+      integrationRef: { allow: ["genericContribute", "policyExempt"], deny: ["forcePush"] } as {
+        allow: readonly PermissionBitName[];
+        deny: readonly PermissionBitName[];
+      },
       mainRef: { deny: ["policyExempt"] } as { deny: readonly PermissionBitName[] },
     },
     /**
      * checkBuildServiceCanRelease() (file header, "checkBuildServiceCanRelease()"):
-     * 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`.
+     * 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 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.
+     * `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
+     * its bump 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. `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: {
       repoScoped: ["genericContribute", "pullRequestContribute"] as const,
+      integrationRefScoped: ["genericContribute", "policyExempt"] as const,
+      integrationRefForbidden: ["forcePush"] as const,
     },
   },
 } as const;
@@ -280,7 +288,7 @@ export const REPO_STANDARD = {
  * 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> = {
+const GIT_REPO_PERMISSION_UI_LABEL: Record<PermissionBitName, string> = {
   genericRead: "Read",
   genericContribute: "Contribute",
   forcePush: "Force push (rewrite history, delete branches and tags)",
@@ -369,7 +377,7 @@ interface AccessControlListsResponse {
  * 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";
+const STRICT_MAIN_BRANCH_PROJECT = "Enact";
 
 function strictMainBranchRulesApply(project: string): boolean {
   return project.toLowerCase() === STRICT_MAIN_BRANCH_PROJECT.toLowerCase();
@@ -839,11 +847,11 @@ async function resolveBuildServiceDescriptor(namespaceId: string, projectId: str
 }
 
 /**
- * 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).
+ * CI needs to push and complete PRs on the repo itself, and needs to bypass
+ * policy only on `integration` (so the `[skip ci]` version-bump commit the
+ * integration-merge pipeline pushes there 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,
@@ -902,14 +910,19 @@ async function checkBuildServicePermissions(
     drifts,
   );
   if (integrationEffective) {
-    // 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.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`,
+        });
+      }
+    }
     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.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)`,
+          message: `the project build service effectively has ${bitName} (${GIT_REPO_PERMISSION_UI_LABEL[bitName]}) on refs/heads/integration, which the standard forbids: the bump is a plain fast-forward push and force push is required of no identity`,
         });
       }
     }
@@ -961,6 +974,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
@@ -983,10 +1006,12 @@ 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. 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
+ * `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.
@@ -994,6 +1019,7 @@ async function fetchEnforceJobAuthScope(c: AdoClient): Promise<boolean | undefin
 async function checkOneBuildServiceCanRelease(
   namespaceId: string,
   repoToken: string,
+  integrationRefToken: string,
   repository: string,
   displayName: string,
   drifts: RepoDoctorDrift[],
@@ -1020,7 +1046,8 @@ async function checkOneBuildServiceCanRelease(
   }
 
   // LOW, independent review 2026-09-30: name WHICH token failed — "the ACL"
-  // alone left a human unable to tell which token's read 403'd.
+  // 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 {
@@ -1045,6 +1072,23 @@ 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 push to integration would be refused. Fix: ${releaseFixPathForRef(repository, "integration", displayName, bitName)}`,
+    });
+  }
+  for (const bitName of REPO_STANDARD.permissions.buildServiceRelease.integrationRefForbidden) {
+    if ((effectiveAllowBits(integrationEffective) & GIT_REPO_PERMISSION_BIT[bitName]) === 0) continue;
+    drifts.push({
+      id: `permissions.release.${slug}.has-${bitName}`,
+      message: `'${displayName}' effectively has ${GIT_REPO_PERMISSION_UI_LABEL[bitName]} on 'refs/heads/integration' of '${repository}', which the standard forbids (the version bump is a plain fast-forward push; force push is required of no identity)`,
+    });
+  }
 }
 
 /**
@@ -1075,8 +1119,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);
   }
 }
 
@@ -1094,6 +1139,10 @@ export async function repoDoctorCheck(options: RepoDoctorOptions = {}): Promise<
 
   const repoInfo = await c.get<GitRepositoryResponse>(`/git/repositories/${repository}`, { "api-version": "7.1" });
   const repositoryId = repoInfo.id;
+  if (typeof repositoryId !== "string" || repositoryId === "") {
+    // `--repo .` (a path) reaches the list endpoint; never carry on with an `undefined` id.
+    throw new Error(`Azure DevOps returned no repository for '${repository}' — --repo takes a repository name, not a path`);
+  }
   const projectId = repoInfo.project?.id;
 
   const refs = await c.get<GitRefsResponse>(`/git/repositories/${repositoryId}/refs`, {

package/packages/azdo/src/azdo-wit.ts

@@ -2,6 +2,7 @@
 // mcp-server.ts — there is no CLI entry point here (nothing else in the
 // repo invoked this file as a CLI).
 import { AdoClient, adoProjectUrl, resolveProject } from './lib/client.ts'
+import { evaluateWorkflowState, formatWorkflowRefusal, pickWorkflowFlags, type WorkflowFlagRef } from './workflow-rules.ts'
 
 // Work-item calls use the SAME org/project resolution as every other tool in
 // this package (`lib/client.ts`). They used to carry their own `config` object
@@ -28,7 +29,7 @@ export function resetClientForTests(): void {
 }
 
 /** Canonical work-item contract: only these board levels are user-facing. */
-export const ALLOWED_TYPES = ['Feature', 'Product Backlog Item', 'Bug'] as const;
+const ALLOWED_TYPES = ['Feature', 'Product Backlog Item', 'Bug'] as const;
 type AllowedType = (typeof ALLOWED_TYPES)[number];
 export type WorkItemListOrGetArgs = { id?: number; ids?: number[]; type?: string; state?: string; assignedTo?: string; limit?: number; raw?: boolean };
 export type WorkItemWriteArgs = {
@@ -107,6 +108,21 @@ function buildWriteOps(args: WorkItemWriteArgs): any[] {
 export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<string> {
   if (args.id === undefined) {
     assertAllowedType(args.type); if (!args.title) throw new Error('title is required for create'); if (args.parentId === undefined) throw new Error(`${args.type} requires parentId`);
+    // FENCE 1 (create): System.State via the raw fields escape hatch is
+    // fenced for the gated types — the dedicated `state` argument exists so
+    // the workflow gate can evaluate the resulting state. Features carry no
+    // flags; for them the generic managed-field refusal in buildWriteOps
+    // still applies (unchanged behavior).
+    if (args.type !== 'Feature' && args.fields !== undefined && 'System.State' in args.fields) {
+      throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
+    }
+    // FENCE 2 (create): a new PBI/Bug starts in New with every flag false, so
+    // the gate on the resulting pair refuses any non-false flag or advanced
+    // state the same way an update would.
+    if (args.type !== 'Feature') {
+      const violations = evaluateWorkflowState(args.type, args.state ?? 'New', pickWorkflowFlags(args.fields));
+      if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+    }
     const ops = buildWriteOps(args);
     const c = await getClient();
     const parent = await c.get<any>(`/wit/workitems/${args.parentId}`, { 'api-version': '7.1' });
@@ -116,10 +132,33 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     return JSON.stringify(formatItem(created, false), null, 2);
   }
   if (args.type !== undefined) throw new Error('type cannot be changed on an existing work item');
-  let ops = buildWriteOps(args); if (!ops.length) throw new Error('nothing to write: no fields, state, comment, or relations were supplied');
+  // System.State arriving through the raw fields escape hatch is deferred:
+  // its refusal is type-dependent (FENCE 1 below) and the type is only known
+  // after the read. Every OTHER managed field is still refused inside
+  // buildWriteOps, before any network, exactly as before.
+  const fields = args.fields ?? {};
+  const stateViaRawFields = 'System.State' in fields;
+  const fieldsForOps = stateViaRawFields ? Object.fromEntries(Object.entries(fields).filter(([name]) => name !== 'System.State')) : fields;
+  let ops = buildWriteOps({ ...args, fields: fieldsForOps }); if (!ops.length && !stateViaRawFields) throw new Error('nothing to write: no fields, state, comment, or relations were supplied');
   const c = await getClient();
   const current = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' });
   assertTracked(current);
+  const currentType: AllowedType = current.fields?.['System.WorkItemType'];
+  // FENCE 1: System.State via raw fields on a gated type. Features carry no
+  // flags and keep the generic managed-field refusal instead.
+  if (stateViaRawFields) {
+    if (currentType === 'Feature') throw new Error(`fields may only set Custom.* fields; 'System.State' is managed by this tool`);
+    throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
+  }
+  // FENCE 2 (workflow matrix): evaluate the RESULTING (state, flags) pair on
+  // every write — a state move and a flag-only update are both writes, and a
+  // write that leaves the pair violating any yes/no row is refused.
+  if (currentType !== 'Feature') {
+    const postState = args.state ?? current.fields?.['System.State'];
+    const postFlags: Partial<Record<WorkflowFlagRef, boolean>> = { ...pickWorkflowFlags(current.fields), ...pickWorkflowFlags(args.fields) };
+    const violations = evaluateWorkflowState(currentType, postState, postFlags);
+    if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+  }
   if (args.parentId !== undefined) {
     // A parent is singular. Read the existing item so the write can remove all
     // old parent links before adding the one validated replacement.

package/packages/azdo/src/lib/agent-identity.ts

@@ -1,6 +1,5 @@
-// Azure DevOps identity RESOLUTION ONLY (P2, Tarun, 2026-09-27; standard
-// finalized 2026-09-28 in STATUS.md 12p "The
-// standard"; split from token minting 2026-09-28 -- see
+// Azure DevOps identity RESOLUTION ONLY (Tarun, 2026-09-27; one agent-identity
+// standard for every surface, 2026-09-28; split from token minting -- see
 // ./agent-token.ts's header for why).
 //
 // This module is THE one identity resolver -- every other Azure DevOps
@@ -35,7 +34,7 @@ export function isValidAgent(name: string): name is ValidAgent {
 
 /** The one message every surface shows when no agent identity can be resolved at all. */
 export const NO_AGENT_IDENTITY_MESSAGE =
-  'no agent identity: prefix the command with ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer>, or start the session with `adl run <surface> --as <agent>`';
+  'no agent identity: prefix the command with ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer>';
 
 /** Treat blank and whitespace-only values as unset. */
 function configured(value: string | undefined): string | undefined {
@@ -129,9 +128,8 @@ export interface AgentIdentityResolution {
 }
 
 /**
- * The human Azure DevOps pass-through check (STATUS.md 12p decision 1: fail
- * closed, the human opts in; 1b: TTY + env marker; 1c: the marker is
- * `ADL_HUMAN_AZDO=1`). This is the ONE place the rule is expressed in
+ * The human Azure DevOps pass-through check (fail closed, the human opts in:
+ * a real TTY plus the env marker `ADL_HUMAN_AZDO=1`; Tarun, 2026-09-29). This is the ONE place the rule is expressed in
  * TypeScript -- `adl id whoami` (apps/cli/src/commands/id.ts) calls this
  * rather than re-implementing it. `bin/git-ado`'s own human-pass-through
  * branch implements the IDENTICAL rule in bash (it cannot import this
@@ -142,9 +140,10 @@ export interface AgentIdentityResolution {
  *
  * Both halves are required:
  *  - `stdinIsTTY`: the caller's stdin is a real terminal, not a pipe, a
- *    closed fd, or a non-interactive automation shell (evidence 2026-09-29,
- *    STATUS.md 12p: the desktop agent shell has no TTY and does not inherit
- *    `.zshrc` exports either -- the TTY half alone already excludes it).
+ *    closed fd, or a non-interactive automation shell (observed 2026-09-29:
+ *    the desktop agent shell has no TTY and does not inherit `.zshrc`
+ *    exports either; agents started directly from a terminal DO inherit its
+ *    env, which is why the TTY half is required alongside the marker).
  *  - `env.ADL_HUMAN_AZDO === '1'`: the EXACT string `"1"`, not `"true"`,
  *    not `"yes"`, not trimmed whitespace -- Tarun exports it from his own
  *    `.zshrc`. An agent must never set it (packages/agent-settings'
@@ -160,12 +159,11 @@ export function isMarkedHumanAzdoCaller(env: NodeJS.ProcessEnv, stdinIsTTY: bool
 
 /**
  * The one agent-identity resolver every Azure DevOps surface in this repo
- * shares (STATUS.md 12p, "The standard"). One
- * function; first match wins; an invalid name is refused, never skipped:
+ * shares (Tarun, 2026-09-28). One function; first match wins; an invalid name is refused, never skipped:
  *
  *   1. `ADL_AGENT_ID_AGENT` from the environment (blank/whitespace-only
- *      counts as unset) -- set by an `adl run --as <agent>` session, or by
- *      a surface's managed default (e.g. Claude's managed-settings env).
+ *      counts as unset) -- set by a surface's managed default (e.g.
+ *      Claude's managed-settings env).
  *   2. Else the machine default-agent file, written by fleet reconcile.
  *   3. Else refuse with `NO_AGENT_IDENTITY_MESSAGE` -- there is never a
  *      human fallback for an agent.

package/packages/azdo/src/lib/agent-token.ts

@@ -136,8 +136,8 @@ export async function getAccessToken(agent: string): Promise<string> {
  * addresses and the same in-memory cache -- for callers whose call sites are
  * all sync (packages/repo-controls' doctor/hook checks), where importing the
  * async mint across the package boundary would mean threading `await`
- * through code that has none today. STATUS.md 12p finding M9: this is the
- * ONE mint every surface uses now; packages/repo-controls/src/azure-devops-governance.ts
+ * through code that has none today. This is the ONE mint every surface
+ * uses; packages/repo-controls/src/azure-devops-governance.ts
  * no longer keeps its own copy.
  *
  * `env` defaults to `process.env` (matching `getAccessToken`) but is

package/packages/azdo/src/lib/client.ts

@@ -110,11 +110,6 @@ export function currentRemote(cwd?: string): AzureRemote | null {
   return remoteCache;
 }
 
-/** Test seam: forget the cached remote. */
-export function resetRemoteCache(): void {
-  remoteCache = undefined;
-}
-
 export function resolveOrg(cwd?: string): string {
   return configured(process.env.AZURE_DEVOPS_ORG) ?? currentRemote(cwd)?.org ?? DEFAULT_ORG;
 }

package/packages/azdo/src/lib/graph-identity.ts

@@ -79,7 +79,7 @@ function configured(value: string | undefined): string | undefined {
 }
 
 /** The Graph service host — a different host from dev.azure.com entirely. */
-export function vsspsBaseUrl(): string {
+function vsspsBaseUrl(): string {
   return configured(process.env.AZURE_DEVOPS_VSSPS_BASE_URL) ?? `https://vssps.dev.azure.com/${resolveOrg()}`;
 }
 
@@ -92,7 +92,7 @@ export async function fetchJson<T>(url: string, label: string): Promise<T> {
   return resp.json() as Promise<T>;
 }
 
-export async function postJson<T>(url: string, body: unknown, label: string): Promise<T> {
+async function postJson<T>(url: string, body: unknown, label: string): Promise<T> {
   const token = await getAccessToken(resolveAgentIdentity().agent);
   const resp = await fetch(url, {
     method: 'POST',
@@ -106,7 +106,7 @@ export async function postJson<T>(url: string, body: unknown, label: string): Pr
   return resp.json() as Promise<T>;
 }
 
-export interface GraphSubjectQueryResponse {
+interface GraphSubjectQueryResponse {
   value?: Array<{ displayName?: string; descriptor?: string }>;
 }
 
@@ -142,7 +142,7 @@ interface GraphStorageKeyResponse {
 }
 
 /** Resolve a Graph `descriptor` to its legacy GUID storage key, or undefined when Graph has none on file. */
-export async function resolveIdentityStorageKey(descriptor: string): Promise<string | undefined> {
+async function resolveIdentityStorageKey(descriptor: string): Promise<string | undefined> {
   const result = await fetchJson<GraphStorageKeyResponse>(
     `${vsspsBaseUrl()}/_apis/graph/storagekeys/${encodeURIComponent(descriptor)}?api-version=7.1`,
     'Graph storage key',

package/packages/azdo/src/workflow-rules-matrix.csv

@@ -0,0 +1,85 @@
+work_item_type,state,state_category,flag_ref,flag_label,rule,meaning,failure_reason
+Product Backlog Item,New,Proposed,Custom.Planwritten,Plan written,no,must be false,Plan rejected
+Product Backlog Item,New,Proposed,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Product Backlog Item,New,Proposed,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Product Backlog Item,New,Proposed,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Product Backlog Item,New,Proposed,Custom.Docsupdated,Docs updated,no,must be false,
+Product Backlog Item,New,Proposed,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Product Backlog Item,Approved,Proposed,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Product Backlog Item,Approved,Proposed,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Product Backlog Item,Approved,Proposed,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Product Backlog Item,Approved,Proposed,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Product Backlog Item,Approved,Proposed,Custom.Docsupdated,Docs updated,no,must be false,
+Product Backlog Item,Approved,Proposed,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Product Backlog Item,Committed,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Product Backlog Item,Committed,InProgress,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Product Backlog Item,Committed,InProgress,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Product Backlog Item,Committed,InProgress,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Product Backlog Item,Committed,InProgress,Custom.Docsupdated,Docs updated,no,must be false,
+Product Backlog Item,Committed,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Product Backlog Item,In Progress,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Product Backlog Item,In Progress,InProgress,Custom.Implementationcomplete,Implementation complete,free,either — this is where the gate is worked,
+Product Backlog Item,In Progress,InProgress,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Product Backlog Item,In Progress,InProgress,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Product Backlog Item,In Progress,InProgress,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Product Backlog Item,In Progress,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Product Backlog Item,In Testing,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Product Backlog Item,In Testing,InProgress,Custom.Implementationcomplete,Implementation complete,yes,must be true,
+Product Backlog Item,In Testing,InProgress,Custom.Reviewpassed,Review passed,free,either — this is where the gate is worked,Reviewer rejected
+Product Backlog Item,In Testing,InProgress,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Product Backlog Item,In Testing,InProgress,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Product Backlog Item,In Testing,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Product Backlog Item,Done,Completed,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Product Backlog Item,Done,Completed,Custom.Implementationcomplete,Implementation complete,yes,must be true,
+Product Backlog Item,Done,Completed,Custom.Reviewpassed,Review passed,yes,must be true,Reviewer rejected
+Product Backlog Item,Done,Completed,Custom.Testspassing,Tests passing,yes,must be true,Tests failed
+Product Backlog Item,Done,Completed,Custom.Docsupdated,Docs updated,yes,must be true,
+Product Backlog Item,Done,Completed,Custom.Mergedtointegration,Merged to integration,yes,must be true,Build failed
+Product Backlog Item,Removed,Removed,Custom.Planwritten,Plan written,free,either — this is where the gate is worked,Plan rejected
+Product Backlog Item,Removed,Removed,Custom.Implementationcomplete,Implementation complete,free,either — this is where the gate is worked,
+Product Backlog Item,Removed,Removed,Custom.Reviewpassed,Review passed,free,either — this is where the gate is worked,Reviewer rejected
+Product Backlog Item,Removed,Removed,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Product Backlog Item,Removed,Removed,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Product Backlog Item,Removed,Removed,Custom.Mergedtointegration,Merged to integration,free,either — this is where the gate is worked,Build failed
+Bug,New,Proposed,Custom.Planwritten,Plan written,no,must be false,Plan rejected
+Bug,New,Proposed,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Bug,New,Proposed,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Bug,New,Proposed,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Bug,New,Proposed,Custom.Docsupdated,Docs updated,no,must be false,
+Bug,New,Proposed,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Bug,Approved,Proposed,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Bug,Approved,Proposed,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Bug,Approved,Proposed,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Bug,Approved,Proposed,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Bug,Approved,Proposed,Custom.Docsupdated,Docs updated,no,must be false,
+Bug,Approved,Proposed,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Bug,Committed,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Bug,Committed,InProgress,Custom.Implementationcomplete,Implementation complete,no,must be false,
+Bug,Committed,InProgress,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Bug,Committed,InProgress,Custom.Testspassing,Tests passing,no,must be false,Tests failed
+Bug,Committed,InProgress,Custom.Docsupdated,Docs updated,no,must be false,
+Bug,Committed,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Bug,In Progress,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Bug,In Progress,InProgress,Custom.Implementationcomplete,Implementation complete,free,either — this is where the gate is worked,
+Bug,In Progress,InProgress,Custom.Reviewpassed,Review passed,no,must be false,Reviewer rejected
+Bug,In Progress,InProgress,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Bug,In Progress,InProgress,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Bug,In Progress,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Bug,In Testing,InProgress,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Bug,In Testing,InProgress,Custom.Implementationcomplete,Implementation complete,yes,must be true,
+Bug,In Testing,InProgress,Custom.Reviewpassed,Review passed,free,either — this is where the gate is worked,Reviewer rejected
+Bug,In Testing,InProgress,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Bug,In Testing,InProgress,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Bug,In Testing,InProgress,Custom.Mergedtointegration,Merged to integration,no,must be false,Build failed
+Bug,Done,Completed,Custom.Planwritten,Plan written,yes,must be true,Plan rejected
+Bug,Done,Completed,Custom.Implementationcomplete,Implementation complete,yes,must be true,
+Bug,Done,Completed,Custom.Reviewpassed,Review passed,yes,must be true,Reviewer rejected
+Bug,Done,Completed,Custom.Testspassing,Tests passing,yes,must be true,Tests failed
+Bug,Done,Completed,Custom.Docsupdated,Docs updated,yes,must be true,
+Bug,Done,Completed,Custom.Mergedtointegration,Merged to integration,yes,must be true,Build failed
+Bug,Removed,Removed,Custom.Planwritten,Plan written,free,either — this is where the gate is worked,Plan rejected
+Bug,Removed,Removed,Custom.Implementationcomplete,Implementation complete,free,either — this is where the gate is worked,
+Bug,Removed,Removed,Custom.Reviewpassed,Review passed,free,either — this is where the gate is worked,Reviewer rejected
+Bug,Removed,Removed,Custom.Testspassing,Tests passing,free,either — this is where the gate is worked,Tests failed
+Bug,Removed,Removed,Custom.Docsupdated,Docs updated,free,either — this is where the gate is worked,
+Bug,Removed,Removed,Custom.Mergedtointegration,Merged to integration,free,either — this is where the gate is worked,Build failed