feat(safe-outputs): per-repo create-pull-request target branches

A meta repo that checks out N repos can now open a PR into each repo's own
target branch, instead of a single target-branch applied to all. The base-ref
deepening (prepare-pr-base) uses the per-repo target so the diff base resolves
for each repo, and Stage 3 opens each PR into its resolved target.

New create-pull-request config (collision-free — target-branch stays a literal):
- target-branch: literal fallback (default main), unchanged.
- target-branches: per-alias literal overrides (highest precedence).
- infer-target-from-checkout-ref: opt-in bool; a checkout repo with no explicit
  override targets its own repos: ref. self never infers.

Resolution (shared by the compiler's deepening and Stage 3's PR creation, so the
deepened branch always matches the PR base): target-branches[R] > inferred ref >
target-branch > main.

- CreatePrConfig gains target_branches + infer_target_from_checkout_ref +
  resolve_target_branch(); ExecutionContext gains repo_refs (populated at Stage 3
  and used to resolve per-repo targets).
- prepare-pr-base emits/consumes repeated `--repo-dir <dir> --target-branch
  <branch>` pairs (per-dir target); double-quoted ADO-macro dir, single-quoted
  literal branch (shellcheck-clean).
- Resolver unit matrix + compile-integration (meta repo, diverse refs) + bundle
  multi-target tests; docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

docs/ado-script.md

@@ -71,17 +71,20 @@ pipeline** as runtime helpers. Today it produces thirteen bundles:
 - `prepare-pr-base.js` — create-pull-request base-ref preparer that runs in the
   **Agent job** before the Copilot invocation when `create-pull-request` is
   configured (issue #1413). For each allowed create-PR repo dir (`self` +
-  every `checkout:` alias, passed as repeated `--repo-dir` flags in the same form
-  `mcp.rs::resolve_git_dir_for_patch` resolves them), it fetches and progressively
-  deepens the configured `target-branch` into `refs/remotes/origin/<target>` and
-  points `refs/remotes/origin/HEAD` at it, so the host-side SafeOutputs MCP server
-  can compute a diff base on shallow-default agent pools without a full-history
-  `checkout: self`. Reuses `shared/merge-base.ts::ensureTargetRefFetched`
-  (the same fetch/deepen logic as the PR execution-context precompute). The
-  single `--target-branch` (the PR's destination/base) and each `--repo-dir` are
-  non-secret argv flags; the ADO bearer (`SYSTEM_ACCESSTOKEN`) rides in masked env
-  for the authenticated git fetch. Per-dir failures are isolated (logged +
-  skipped). Runs outside AWF. See
+  every `checkout:` alias, passed as repeated `--repo-dir <dir> --target-branch
+  <branch>` pairs in the same dir form `mcp.rs::resolve_git_dir_for_patch`
+  resolves), it fetches and progressively deepens THAT repo's resolved target
+  branch into `refs/remotes/origin/<target>` and points
+  `refs/remotes/origin/HEAD` at it, so the host-side SafeOutputs MCP server can
+  compute a diff base on shallow-default agent pools without a full-history
+  `checkout: self`. In a multi-checkout ("meta repo") setup each dir may carry a
+  different target (see `create-pull-request`'s `target-branches` /
+  `infer-target-from-checkout-ref`). Reuses
+  `shared/merge-base.ts::ensureTargetRefFetched` (the same fetch/deepen logic as
+  the PR execution-context precompute). Each `--repo-dir` is a double-quoted
+  ADO-macro path; each `--target-branch` is a single-quoted literal; the ADO
+  bearer (`SYSTEM_ACCESSTOKEN`) rides in masked env for the authenticated git
+  fetch. Per-dir failures are isolated (logged + skipped). Runs outside AWF. See
   [`safe-outputs.md`](safe-outputs.md#create-pull-request).
 
 > **Internal-only.** `ado-script` is not a user-facing front-matter

docs/safe-outputs.md

@@ -277,11 +277,12 @@ a full-history checkout and **without** hand-editing the compiled lock (so the
 runtime integrity check keeps passing). No configuration is required. See
 [`docs/ado-script.md`](ado-script.md) (`prepare-pr-base.js`).
 
-> **Branch semantics.** The step deepens the single `target-branch` (the PR's
-> **destination/base**, default `main`), applied uniformly to every repo dir — not
-> the per-repo `repos:` checkout `ref` (which is the source side). Multi-repo PRs
-> therefore all target the same branch name; per-repo target branches are not yet
-> expressible (tracked as a follow-up).
+> **Branch semantics.** The step deepens each repo's resolved `target-branch`
+> (the PR's **destination/base**) — not the per-repo `repos:` checkout `ref` (the
+> source side). By default every repo targets the single `target-branch`; enable
+> `infer-target-from-checkout-ref` (and/or `target-branches`) to give each repo
+> its own base branch in a multi-checkout setup. The deepened branch always
+> matches the branch the PR targets (shared resolution).
 
 **Stage 3 Execution Architecture (Hybrid Git + ADO API):**
 
@@ -326,7 +327,36 @@ This hybrid approach combines:
 Note: The source branch name is auto-generated from a sanitized version of the PR title plus a unique suffix (e.g., `agent/fix-bug-in-parser-a1b2c3`). This format is human-readable while preventing injection attacks.
 
 **Configuration options (front matter):**
-- `target-branch` - Target branch to merge into (default: "main")
+- `target-branch` - Target (base) branch the PR merges into (default: "main"). A
+  plain literal branch name, applied to every repo unless overridden below.
+- `target-branches` - Optional map of per-repository target-branch overrides,
+  keyed by the repository alias the agent passes to `create-pull-request` (`self`
+  or a `checkout:` alias). Highest precedence. Lets a multi-checkout ("meta repo")
+  agent open a PR into a different base branch per repo.
+- `infer-target-from-checkout-ref` - Optional bool (default: false). When `true`,
+  a checkout repo with no explicit `target-branches` entry targets its own
+  `repos: ref` (the branch it was checked out at). `self` and repos without a
+  known ref fall back to `target-branch`. It is a separate boolean (not a magic
+  `target-branch` value) so a real branch name can never be mistaken for a
+  directive.
+
+  **Per-repo target resolution precedence** (for a repo `R`): `target-branches[R]`
+  → (if `infer-target-from-checkout-ref`) `R`'s checkout ref → `target-branch` →
+  `main`. The same resolution drives both the credentialed base-ref deepening (so
+  the branch that is fetched/deepened matches the branch the PR targets) and the
+  Stage 3 PR creation. Example (meta repo):
+  ```yaml
+  repos:
+    - name: my-org/service   # checked out at refs/heads/main
+    - name: my-org/docs
+      ref: refs/heads/gh-pages
+  safe-outputs:
+    create-pull-request:
+      target-branch: main                  # self + fallback
+      infer-target-from-checkout-ref: true # service → main, docs → gh-pages (from their refs)
+      target-branches:
+        docs: gh-pages                      # (redundant here; shown as an explicit override)
+  ```
 - `draft` - Whether to create the PR as a draft (default: **true**). Set to `false` to publish the PR immediately. **Note:** `auto-complete` is silently skipped on draft PRs — set `draft: false` when using `auto-complete: true`.
 - `auto-complete` - Set auto-complete on the PR (default: false). Requires `draft: false` to take effect.
 - `delete-source-branch` - Delete source branch after merge (default: true)

scripts/ado-script/src/prepare-pr-base/__tests__/index.test.ts

@@ -42,100 +42,106 @@ function recordingChdir(): { chdir: (dir: string) => void; dirs: string[] } {
 }
 
 describe("parseArgs", () => {
-  it("defaults to main when --target-branch is absent", () => {
-    expect(parseArgs([]).targetBranch).toBe("main");
-  });
-
-  it("reads the --target-branch value", () => {
-    expect(parseArgs(["--target-branch", "develop"]).targetBranch).toBe("develop");
-  });
-
-  it("strips a leading refs/heads/ prefix", () => {
-    expect(parseArgs(["--target-branch", "refs/heads/release/2.x"]).targetBranch).toBe(
-      "release/2.x",
-    );
+  it("pairs each --repo-dir with the following --target-branch", () => {
+    const args = parseArgs([
+      "--repo-dir",
+      "/src",
+      "--target-branch",
+      "main",
+      "--repo-dir",
+      "/src/tools",
+      "--target-branch",
+      "release",
+    ]);
+    expect(args.repos).toEqual([
+      { dir: "/src", target: "main" },
+      { dir: "/src/tools", target: "release" },
+    ]);
   });
 
-  it("falls back to main for an empty value", () => {
-    expect(parseArgs(["--target-branch", ""]).targetBranch).toBe("main");
+  it("strips a leading refs/heads/ from targets", () => {
+    const args = parseArgs([
+      "--repo-dir",
+      "/src",
+      "--target-branch",
+      "refs/heads/release/2.x",
+    ]);
+    expect(args.repos).toEqual([{ dir: "/src", target: "release/2.x" }]);
   });
 
-  it("collects repeated --repo-dir flags in order, defaulting to empty", () => {
-    expect(parseArgs([]).repoDirs).toEqual([]);
-    expect(
-      parseArgs([
-        "--target-branch",
-        "main",
-        "--repo-dir",
-        "/src",
-        "--repo-dir",
-        "/src/tools",
-      ]).repoDirs,
-    ).toEqual(["/src", "/src/tools"]);
+  it("uses the fallback target for a --repo-dir with no following --target-branch", () => {
+    // A leading global --target-branch sets the fallback; a bare trailing
+    // --repo-dir inherits it.
+    const args = parseArgs(["--target-branch", "develop", "--repo-dir", "/src"]);
+    expect(args.fallbackTarget).toBe("develop");
+    expect(args.repos).toEqual([{ dir: "/src", target: "develop" }]);
   });
 
-  it("ignores empty --repo-dir values", () => {
-    expect(parseArgs(["--repo-dir", "", "--repo-dir", "/src"]).repoDirs).toEqual(["/src"]);
+  it("defaults the fallback target to main", () => {
+    expect(parseArgs([]).fallbackTarget).toBe("main");
+    expect(parseArgs([]).repos).toEqual([]);
   });
 });
 
 describe("prepare-pr-base main", () => {
   it("fetches origin/<target> and sets origin/HEAD on success", () => {
     const { runners, calls } = makeRunners({ fetchStatus: 0, mergeBase: SHA_M });
     const { chdir, dirs } = recordingChdir();
-    const rc = main({ targetBranch: "main", repoDirs: ["/src"] }, {}, runners, chdir);
-    expect(rc).toBe(0);
-    expect(dirs).toEqual(["/src"]);
-
-    const fetch = calls.find((c) => c[0] === "fetch");
-    expect(fetch).toBeDefined();
-    expect(fetch).toContain("+refs/heads/main:refs/remotes/origin/main");
-
-    const sym = calls.find((c) => c[0] === "symbolic-ref");
-    expect(sym).toEqual([
-      "symbolic-ref",
-      "refs/remotes/origin/HEAD",
-      "refs/remotes/origin/main",
-    ]);
-  });
-
-  it("threads a non-default target through the fetch refspec and origin/HEAD", () => {
-    const { runners, calls } = makeRunners({ fetchStatus: 0, mergeBase: SHA_M });
-    const { chdir } = recordingChdir();
     const rc = main(
-      { targetBranch: "release/2.x", repoDirs: ["/src"] },
+      { repos: [{ dir: "/src", target: "main" }], fallbackTarget: "main" },
       {},
       runners,
       chdir,
     );
     expect(rc).toBe(0);
+    expect(dirs).toEqual(["/src"]);
 
     const fetch = calls.find((c) => c[0] === "fetch");
-    expect(fetch).toContain("+refs/heads/release/2.x:refs/remotes/origin/release/2.x");
+    expect(fetch).toBeDefined();
+    expect(fetch).toContain("+refs/heads/main:refs/remotes/origin/main");
 
     const sym = calls.find((c) => c[0] === "symbolic-ref");
     expect(sym).toEqual([
       "symbolic-ref",
       "refs/remotes/origin/HEAD",
-      "refs/remotes/origin/release/2.x",
+      "refs/remotes/origin/main",
     ]);
   });
 
-  it("deepens every repo dir (self + aliases) and sets origin/HEAD in each", () => {
+  it("deepens each repo dir with its OWN target branch (meta-repo)", () => {
     const { runners, calls } = makeRunners({ fetchStatus: 0, mergeBase: SHA_M });
     const { chdir, dirs } = recordingChdir();
     const rc = main(
-      { targetBranch: "main", repoDirs: ["/src", "/src/tools", "/src/lib"] },
+      {
+        repos: [
+          { dir: "/src", target: "main" },
+          { dir: "/src/tools", target: "release" },
+          { dir: "/src/docs", target: "gh-pages" },
+        ],
+        fallbackTarget: "main",
+      },
       {},
       runners,
       chdir,
     );
     expect(rc).toBe(0);
-    // Entered each dir, in order.
-    expect(dirs).toEqual(["/src", "/src/tools", "/src/lib"]);
-    // One fetch + one origin/HEAD set per dir.
-    expect(calls.filter((c) => c[0] === "fetch").length).toBe(3);
-    expect(calls.filter((c) => c[0] === "symbolic-ref").length).toBe(3);
+    expect(dirs).toEqual(["/src", "/src/tools", "/src/docs"]);
+
+    // Each dir fetched + set origin/HEAD to ITS target ref.
+    const fetchRefspecs = calls
+      .filter((c) => c[0] === "fetch")
+      .map((c) => c.find((a) => a.startsWith("+refs/heads/")));
+    expect(fetchRefspecs).toEqual([
+      "+refs/heads/main:refs/remotes/origin/main",
+      "+refs/heads/release:refs/remotes/origin/release",
+      "+refs/heads/gh-pages:refs/remotes/origin/gh-pages",
+    ]);
+    const symTargets = calls.filter((c) => c[0] === "symbolic-ref").map((c) => c[2]);
+    expect(symTargets).toEqual([
+      "refs/remotes/origin/main",
+      "refs/remotes/origin/release",
+      "refs/remotes/origin/gh-pages",
+    ]);
   });
 
   it("isolates a per-dir chdir failure — other dirs still processed", () => {
@@ -148,38 +154,51 @@ describe("prepare-pr-base main", () => {
       }
     };
     const rc = main(
-      { targetBranch: "main", repoDirs: ["/src", "/src/broken", "/src/lib"] },
+      {
+        repos: [
+          { dir: "/src", target: "main" },
+          { dir: "/src/broken", target: "release" },
+          { dir: "/src/lib", target: "main" },
+        ],
+        fallbackTarget: "main",
+      },
       {},
       runners,
       chdir,
     );
     expect(rc).toBe(0);
-    // All dirs attempted...
     expect(dirs).toEqual(["/src", "/src/broken", "/src/lib"]);
-    // ...but only the two good dirs fetched + set origin/HEAD (broken skipped).
+    // Only the two good dirs fetched + set origin/HEAD (broken skipped).
     expect(calls.filter((c) => c[0] === "fetch").length).toBe(2);
     expect(calls.filter((c) => c[0] === "symbolic-ref").length).toBe(2);
   });
 
   it("exits 0 without setting origin/HEAD when every fetch fails (benign)", () => {
     const { runners, calls } = makeRunners({ fetchStatus: 1, mergeBase: null });
     const { chdir } = recordingChdir();
-    const rc = main({ targetBranch: "main", repoDirs: ["/src"] }, {}, runners, chdir);
+    const rc = main(
+      { repos: [{ dir: "/src", target: "main" }], fallbackTarget: "main" },
+      {},
+      runners,
+      chdir,
+    );
     // Non-fatal: the agent still runs; mcp.rs surfaces its own error if needed.
     expect(rc).toBe(0);
     expect(calls.some((c) => c[0] === "symbolic-ref")).toBe(false);
   });
 
-  it("falls back to BUILD_SOURCESDIRECTORY when no --repo-dir is given", () => {
-    const { runners } = makeRunners({ fetchStatus: 0, mergeBase: SHA_M });
+  it("falls back to BUILD_SOURCESDIRECTORY + fallback target when no repos given", () => {
+    const { runners, calls } = makeRunners({ fetchStatus: 0, mergeBase: SHA_M });
     const { chdir, dirs } = recordingChdir();
     main(
-      { targetBranch: "main", repoDirs: [] },
+      { repos: [], fallbackTarget: "develop" },
       { BUILD_SOURCESDIRECTORY: "/agent/src" },
       runners,
       chdir,
     );
     expect(dirs).toEqual(["/agent/src"]);
+    const fetch = calls.find((c) => c[0] === "fetch");
+    expect(fetch).toContain("+refs/heads/develop:refs/remotes/origin/develop");
   });
 
   it("passes the SYSTEM_ACCESSTOKEN bearer into the git fetch env", () => {
@@ -193,7 +212,7 @@ describe("prepare-pr-base main", () => {
     };
     const { chdir } = recordingChdir();
     main(
-      { targetBranch: "main", repoDirs: ["/src"] },
+      { repos: [{ dir: "/src", target: "main" }], fallbackTarget: "main" },
       { SYSTEM_ACCESSTOKEN: "tok" },
       runners,
       chdir,