SDK Pod Backmerge PR Creation

Create the backmerge PR that keeps main aligned with what shipped on a release-<pkg>-<x.y.z> branch, per docs/gitflow.md "Keep main aligned" sections.

When to use this skill

Applies to SDK pod packages whose paths are owned by .github/teams/sdk.json.

Use when:

• A release PR has been (or is being) created for release-<pkg>-<x.y.z>
• User invokes /qv-sdk-backmerge
• sdk-pr-create chains into this flow automatically when the target is a release branch (see that skill's "Release Target Dual-PR Flow")

The backmerge PR carries the version bump + changelog metadata from the release branch onto main so future development sees it. It is tagged [skiplog] to keep it out of subsequent changelogs.

@qvac/inference and @qvac/sdk release separately, so a new major.minor produces two release branches and two backmerges: release-inference-<x.y.z> (engine version + changelog) and then release-sdk-<x.y.z> (SDK version + its @qvac/inference range + changelog + docs). Run this skill once per release branch.

On a release train (qv-release-train), run it once for the whole train: read release-train-<train>-<x.y.z> wherever this skill says release-<pkg>-<x.y.z>. The source carries several manifests, changelogs and pnpm-lock.yaml; that is release metadata for Step 2's sanity check. Never carry a .nx/version-plans/ file to main: if the cherry-pick brings one, git rm it before committing, or the next train applies it again.

Inputs (resolve in priority order)

1. Active release-PR context (when chained from sdk-pr-create): release PR number/URL, release branch, source head branch, ticket
2. Explicit args when invoked standalone:
   • Release PR URL/number, OR
   • --package=<pkg> --version=<x.y.z> and one of --source=<head-branch> or --commit=<sha>
3. Inferred from current branch when no args given: if currently on a head branch that targets release-<pkg>-<x.y.z>, derive package, version, and source from it
4. ASK only if still ambiguous after the steps above

Branch / remote preference

Same policy as qv-sdk-pr-create: prefer pushing the backmerge head to the org remote (tetherto/qvac) and opening a same-repo PR. Personal-fork heads are a fallback and count as external for CI (fork-ci environment approval required per run on the current head SHA).

In command examples below, ORG_REMOTE / FORK_REMOTE are placeholders — substitute the resolved remote names from Step 1. Do not run those tokens literally.

Workflow

Step 1: Pre-flight

• gh is installed and authenticated (gh auth status)
• Working tree is clean (git status empty); if not, ASK whether to stash
• Identify org remote: scan git remote -v for the canonical org repo (tetherto/qvac.git); fall back to a remote literally named upstream. ASK if neither found.
• Identify fork remote if present (often origin when org is upstream) — used only when org push is unavailable or the user explicitly chooses the fork path
• Prefer org-branch push for the backmerge head

Step 2: Resolve the cherry-pick source

Sanity check: the source range must reflect release metadata only (version bump, changelog files, NOTICE, optional model registry/history, and for --package=sdk the two generated reference pages under docs/website/content/docs/sdk/). If git diff <range> --stat shows broad unrelated changes (suggesting the branch was based off main, not the release branch), STOP and ASK how to proceed — do not silently cherry-pick unrelated work onto main.

Step 3: Detect no-op (main already aligned)

Before creating the backmerge branch, check whether main already contains the release content.

git fetch ORG_REMOTE main
git fetch ORG_REMOTE release-<pkg>-<x.y.z>
git merge-tree --write-tree --merge-base=<src>^ ORG_REMOTE/main <src>
git rev-parse ORG_REMOTE/main^{tree}

The first command prints the tree SHA produced by simulating the cherry-pick. The second prints main's current tree SHA. If they are identical, every change in the source range is already on main:

1. STOP. Do not create a branch, do not push, do not open a PR.
2. Find the commit that landed the release content directly on main so you can cite it:

   git log ORG_REMOTE/main --oneline -1 -- <pkg-dir>/changelog/<x.y.z>/

   Resolve <pkg-dir> via node -p "require('./scripts/sdk/package-paths.cjs').getPackageDir('<pkg>')" (plugins use plugins/…, not packages/…).
3. Report to the user, e.g.:

   No backmerge PR needed — main is already aligned with release-<pkg>-<x.y.z>.
   The release content landed on main via <commit-sha> (<commit-subject>).

This avoids pushing an empty branch and a gh pr create failure.

Step 4: Sync and create the backmerge branch

git fetch ORG_REMOTE main
git fetch ORG_REMOTE release-<pkg>-<x.y.z>
git checkout -b backmerge/release-<pkg>-<x.y.z> ORG_REMOTE/main

If a local branch with that name already exists, ASK before overwriting.

Step 5: Cherry-pick

git cherry-pick -x <commit_or_range>

For a true merge commit (not squashed), add -m 1.

Step 6: Conflict triage

Resolve <pkg-dir> with scripts/sdk/package-paths.cjs (getPackageDir('<pkg>')).

On a release train, apply the rules to every package directory the release touched.

Auto-resolvable (resolve, git add, then git cherry-pick --continue):

• <pkg-dir>/package.json — version and dependency-range conflicts: take release-side.

  git checkout --theirs <pkg-dir>/package.json
  git add <pkg-dir>/package.json

• <pkg-dir>/CHANGELOG.md (top-level aggregated): regenerate from the version folders just cherry-picked in.

  node scripts/sdk/generate-changelog-sdk-pod.cjs --package=<pkg>
  git add <pkg-dir>/CHANGELOG.md

• pnpm-lock.yaml: take main's and regenerate, never a text merge.

  git checkout --ours pnpm-lock.yaml
  pnpm install --lockfile-only --ignore-scripts
  git add pnpm-lock.yaml

  A text merge leaves duplicate keys (ERR_PNPM_BROKEN_LOCKFILE), or a lockfile that installs but resolves different versions.

Anything else → STOP. Hand control back to the user. Do not force-resolve, skip, or abort the cherry-pick on the user's behalf.

Never drop pnpm-lock.yaml from the cherry-pick: CI's pnpm install --frozen-lockfile fails on main when a manifest's range and the lockfile disagree.

Docs-website conflicts are never auto-resolvable. An --package=sdk release commit also carries the two generated pages of the SDK's current documentation line (docs/website/content/docs/sdk/(v<X.Y>)/reference/{api,release-notes}.mdx, see qv-sdk-changelog Step 8). A conflict there — or a cherry-pick that cannot find the path at all — usually means main has since been cut to a newer line, so the folder the release wrote into is now the plain v<X.Y> one. STOP and hand it to the documentation engineer: choosing which line the content belongs in is their call, not a merge resolution.

When stopping, print:

• git status -sb
• The list of unresolved files
• Resume instructions:

  # After resolving manually:
  git add <files>
  git cherry-pick --continue
  # Then re-run: /qv-sdk-backmerge --resume

Step 7: Push the backmerge head

Re-verify that the cherry-pick produced commits that actually change ORG_REMOTE/main. Defensive only — Step 3 catches the common no-op case; this guards against rarer paths (e.g. a --commit=<sha> arg that turned out to already be on main, or a -m 1 cherry-pick of a merge commit that resolved to nothing):

git diff --stat ORG_REMOTE/main..HEAD

If the output is empty, treat it as a late no-op and STOP (same handling as Step 3 — report and exit).

Then check the branch installs; do not push until it does:

pnpm install --frozen-lockfile --ignore-scripts

On specifiers in the lockfile don't match, regenerate (pnpm install --lockfile-only --ignore-scripts) and amend.

Otherwise push to the org remote when write access allows:

# Preferred — org-branch head (substitute real remote name for ORG_REMOTE):
git push -u ORG_REMOTE backmerge/release-<pkg>-<x.y.z>

# Fallback — personal fork (external CI path):
git push -u FORK_REMOTE backmerge/release-<pkg>-<x.y.z>

Step 8: Build PR title and body

Title (default — release PRs typically have a QVAC-#### ticket):

TICKET chore[skiplog]: backmerge release-<pkg>-<x.y.z> — <summary>

Title (tickless fallback) — only when there is genuinely no ticket; combine the two tags inside a single bracket pair separated by | per the format defined in this skill:

chore[skiplog|notask]: backmerge release-<pkg>-<x.y.z> — <summary>

• Reuse the ticket from the companion release PR whenever possible.
• <summary> lists what is being landed (e.g. version bump, changelog, NOTICE).

Body (concise, copy-ready):

## What this PR does

Lands the release metadata for `<pkg>@<x.y.z>` on `main`, per [gitflow.md](../../../docs/gitflow.md) "Keep main aligned". No functional changes — tagged `[skiplog]` so it does not appear in future changelogs.

## Companion release PR

- <release PR URL>

## Files

- `<pkg-dir>/package.json` — version `<prev>` → `<x.y.z>`
- `<pkg-dir>/changelog/<x.y.z>/` — generated changelog files
- `<pkg-dir>/CHANGELOG.md` — aggregated changelog
- `<pkg-dir>/NOTICE` — updated dependency attributions (if present)
- `docs/website/content/docs/sdk/(v<X.Y>)/reference/` — API summary (minor only) and release notes of the SDK's current documentation line (`--package=sdk` only)
- (any other release-metadata files included in the cherry-pick)

Step 9: Open the PR

# Preferred — org-branch (same-repo) PR:
gh pr create \
  --repo tetherto/qvac \
  --base main \
  --head backmerge/release-<pkg>-<x.y.z> \
  --title "<title>" \
  --body "<body>"

# Fallback — personal fork -> org PR:
gh pr create \
  --repo tetherto/qvac \
  --base main \
  --head <FORK_OWNER>:backmerge/release-<pkg>-<x.y.z> \
  --title "<title>" \
  --body "<body>"

Print the new PR URL as a clickable hyperlink. When chained from sdk-pr-create, the parent prints both URLs side by side. If the fork fallback was used, note that merge/release must approve the fork-ci environment for privileged CI on that head.

Quality Checklist

Before completing:

• Branch name is exactly backmerge/release-<pkg>-<x.y.z>
• Title contains [skiplog] tag (combined as [skiplog|notask] if tickless)
• Body links the companion release PR
• Cherry-pick used -x (so the original SHA is recorded in commit messages)
• No conflicts remain; any non-trivial conflicts were resolved by the user, not the skill
• pnpm install --frozen-lockfile passes on the branch
• Head was pushed to the org remote when write access allows; fork path only as fallback
• gh pr view confirms target is tetherto/qvac:main and head is the expected org branch (or <fork>:backmerge/... if fallback)

References

• .agents/skills/qv-sdk-pr-create/SKILL.md — companion skill, auto-chains into this one for release targets
• .agents/skills/qv-sdk-changelog/SKILL.md — changelog regeneration used during conflict resolution
• docs/gitflow.md — title format and [skiplog] semantics
• .github/teams/sdk.json — packages this skill applies to
• docs/gitflow.md — release flow and "Keep main aligned" rules (still documents fork-first contribution; prefer org-branch heads per this skill until DevOps updates gitflow)
• Fork CI trust model: docs/ci/LABELS.md (fork-ci environment + fork-approval)