---
name: rollout-phase-a
description: Phase A of a qvac-fabric rollout — set up overlay port and validate all 7 consumers against the fabric branch before publishing to the registry. Pass --on-top-of-pr to apply the overlay onto an open PR's head branch instead of a dedicated validation branch.
argument-hint: "<fabric-version> <fabric-branch-or-commit> [--on-top-of-pr <pr-url>]"
---

# Rollout Phase A — Overlay Validation

**Prerequisites:** Fabric PR open in `tetherto/qvac-fabric-llm.cpp`. Tag does NOT exist yet.

**The 7 consumers:** `embed-llamacpp`, `fabric`, `llm-llamacpp`, `model-fit`, `ocr-ggml`,
`translation-nmtcpp`, `vla-ggml`.

`classification-ggml` is **not** a fabric consumer — it dropped the `qvac-fabric` vcpkg dependency
and now consumes the published npm package `@qvac/fabric`. It needs neither overlay validation nor
a `version>=` bump during a rollout. Do not re-add it.

Re-derive the roster if in doubt — it is one command, and it changes:
```bash
git -C <repo> grep -l "qvac-fabric" origin/main -- "packages/*/vcpkg.json"
```

## THE GOLDEN RULE
Never bump `default-registry.baseline` in `vcpkg-configuration.json`. Not now, not ever during a rollout.

Why nothing breaks without it: vcpkg resolves `version>=` against the registry's **published versions
(HEAD)**, not the baseline commit — the baseline is only a *floor* for ports with no explicit
constraint. Baselines are advanced only by separate, unrelated infra "Sync with fabric" maintenance
PRs; bumping the baseline in a rollout PR is the #1 review rejection.

## Two modes

| Invocation | Where the overlay lands |
|---|---|
| no `--on-top-of-pr` | **Default.** A dedicated validation branch, as below. |
| `--on-top-of-pr <pr-url>` | On top of that open PR's head branch, as one revertable commit. |

The default exists to validate fabric in isolation. `--on-top-of-pr` exists for the common case where
the fabric change was made *because of* an open feature PR: that PR already carries the consumer code
needing the new fabric, so validating on a separate branch leaves the PR's own CI building against
the published (old) fabric, and the two only meet after the whole rollout lands.

Every difference the mode makes is called out inline below under **`--on-top-of-pr`**; everything
else is shared. The overlay is scaffolding either way — `/rollout-phase-b` removes it, and in this
mode it does so by reverting the single commit Step 5 creates.

## Steps

### Step 0 — Preflight, then ask

**Do this before anything else.** Nothing below runs until the user approves.

| Case | Behaviour |
|---|---|
| `<fabric-version>` / `<fabric-branch-or-commit>` given on the invocation | Use them **verbatim**. |
| Not given | **Derive from context** (ladder below), recording the source of each value. |
| Neither | Name what is missing and stop. |

**What was supplied is what gets used.** Never substitute the registry's latest published version or
the newest fabric tag for a value the user gave you, and never "correct" a supplied value to one of
them. The version is passed **bare** — `10297.0.0`, not `v10297.0.0`; the `v` is added at tag time in
Phase B. A `v`-prefixed value is malformed: report the expected form and ask.

**Derivation ladder** — first hit wins, and remember which one it was:

1. **This session**, or the open fabric PR under validation — whose head ref is also
   `<fabric-branch-or-commit>`.
2. **The newest `temp-<N>` release branch with no corresponding `v<N>.*` tag.** Fabric releases are
   cut from branches named `temp-<upstream-llama.cpp-build>`, and the version is
   `<build>.<major>.<minor>` — `temp-10069` carries `v10069.0.0`, `temp-9341` carries `v9341.1.6`. An
   untagged `temp-<N>` is therefore the next rollout, and `<N>` gives the version's leading component.
   The trailing `.<major>.<minor>` is still a human decision — propose `<N>.0.0` and ask.

**Never derive the version from the registry's latest entry, the newest `v*` tag, or the consumers'
current `version>=` floors.** All three hold the *previous* version.

**Resolve against the remote** — read-only; the fabric repo is public, so no token:

| Fact | Command |
|---|---|
| ref → commit sha | `git ls-remote https://github.com/tetherto/qvac-fabric-llm.cpp <ref>` |
| `v<VERSION>` must NOT exist yet | `git ls-remote --tags https://github.com/tetherto/qvac-fabric-llm.cpp "v<VERSION>"` |
| commit subject + date | `gh api repos/tetherto/qvac-fabric-llm.cpp/commits/<sha> --jq '{sha:.sha,msg:.commit.message,date:.commit.committer.date}'` |

Do **not** compare the ref against `master` — it tracks upstream, not the release line, and reports
`diverged` for every legitimate rollout.

#### `--on-top-of-pr` — resolve and vet the target PR

Only in this mode, and before anything else in Step 0 is presented:

```bash
gh pr view <n> --repo tetherto/qvac \
  --json number,title,state,isDraft,headRefName,headRefOid,headRepositoryOwner,baseRefName,labels,files
```

**Hard stops.** Report the reason, not a bare failure — each of these means the run cannot do what it
claims to:

| Condition | Why it stops the run |
|---|---|
| the URL is not a `tetherto/qvac` PR | a **fabric-repo** PR URL is the likely slip — that is the change being validated, not the target |
| PR is not `OPEN` | nothing to validate |
| head repo ≠ `tetherto/qvac` (a fork) | the overlay commit cannot be pushed to a fork's head branch |
| `baseRefName` ∉ `main` / `release-*` / `feature-*` / `tmp-*` | every `on-pr-<consumer>.yml` carries that `branches:` filter, so **no** consumer workflow fires at all |
| PR already carries `overlay-ports` or `vcpkg-overlays/ports/qvac-fabric/` | already overlaid — re-applying doubles it |
| local worktree dirty, or local branch ≠ `headRefOid` | the commit would sweep in unrelated work |

**Then the stage-eligibility report — this is the check that makes the mode honest.** CI stages are
routed by event, and `pull_request_target` is *not* a trusted event:
`.github/actions/ci-router/action.yml` enables every stage for `workflow_dispatch` / `workflow_call` /
`push` / `schedule`, but for a PR event it enables only `run_verified_checks` plus whatever the
granular labels select — and a **draft PR routes nothing at all**.

That matters because `run_verified_checks` gates only `sanity-checks` and `cpp-lint`. The `prebuild`
job — the one that actually compiles the addon against fabric — is gated on `run_prebuilds`.

Compute the report from the PR's own labels and draft state; never assume it:

```
  target PR       #3352  "QVAC-21981 feat[api]: ABot-World …"
                  head QVAC-21981/abot-world @ a2d3265d  ->  base main
                  labels: (none)   draft: no

  sanity-checks   eligible
  cpp-lint        eligible
  prebuild        NOT eligible   <- needs `prebuilds`
  cpp tests       NOT eligible   <- needs `run-cpp-addon-tests`
  desktop tests   NOT eligible   <- needs `run-desktop-addon-tests`
  mobile tests    NOT eligible   <- needs `run-mobile-addon-tests`

  ⚠ Without at least `prebuilds`, the overlay is never compiled — the PR
    goes green having built nothing against the new fabric.
```

A draft PR is its own `⚠`: it routes nothing, so the overlay sits inert until the PR is marked ready.
This is the same failure the misplaced-overlay warning in Step 3 describes — a green result that
validated the old version — reached by a different route, so treat it with the same seriousness.

**Present, then ask.** Label every value `(as given)` or `(derived: <source>)` — that label is what
lets the user catch a bad derivation, so never omit it. Render an anomaly (unknown ref, `v<VERSION>`
already present) as a `⚠` row naming its consequence:

```
Phase A — confirm before proceeding:

  fabric version   10297.0.0    (derived: temp-10297 is untagged)
  validating ref   temp-10297   (derived: newest untagged release branch)
  resolves to      6a32c29a7    "<subject>"   <date>
  tag v10297.0.0   does not exist yet ✓  (Phase B creates it)
  target          validation branch  (default mode)
```

In `--on-top-of-pr` mode the last row names the PR instead, and the stage-eligibility report above is
printed immediately below the block:

```
  target          PR #3352 on tetherto/qvac   (as given)
                  head QVAC-21981/abot-world @ a2d3265d  ->  base main
```

Then `AskUserQuestion` with exactly:

**Proceed** · **Correct a value** (say which) · **Abort**

The run does not start until Proceed is chosen — silence is not consent, and approval is required
even when every value resolves cleanly. When a `⚠` is present, Proceed's description must name what
is being accepted — an unlabelled PR means accepting that nothing will be compiled. If nothing yields
a version, say which value is missing and stop; never guess one.

**`--on-top-of-pr`:** the working branch for Steps 1–4 is the PR's head branch — `gh pr checkout <n>
--repo tetherto/qvac`. **Do not rebase it.** Rewriting a contributor's history is not this skill's
business, and the overlay works from wherever the PR's head happens to sit. Everything in Steps 1–3
is otherwise identical, all 7 consumers included.

### Step 1: Compute SHA512 of the fabric tarball
The fabric repo is public — no token needed. Use the `/archive/` URL (what vcpkg fetches). Do NOT use
`gh api …/tarball/` — its differently-named top-level directory yields a different hash.
```bash
curl -fsSL https://github.com/tetherto/qvac-fabric-llm.cpp/archive/<fabric-branch-or-commit>.tar.gz -o /tmp/fabric.tgz
vcpkg hash /tmp/fabric.tgz
```
Or let vcpkg print the expected hash on first failed fetch (intentionally wrong hash triggers it).

### Step 2: Add shared overlay port
Copy ALL files from the registry port (`tetherto/qvac-registry-vcpkg/ports/qvac-fabric/`) into `vcpkg-overlays/ports/qvac-fabric/` (repo root — `vcpkg-overlays/` already exists, holding `triplets/` and `toolchains/`). Then update `portfile.cmake` to point at the fabric branch/commit (NOT a tag — it doesn't exist yet):
```cmake
vcpkg_from_github(
  OUT_SOURCE_PATH SOURCE_PATH
  REPO tetherto/qvac-fabric-llm.cpp
  REF <fabric-branch-or-commit>
  SHA512 <sha512>
)
```
Keep the call to those four arguments. The registry port carries **no `HEAD_REF`**, and fabric's
default branch is `master` — so a copied-in `HEAD_REF main` is both an addition to the port you were
told to copy verbatim and a wrong value.

The registry port's `REF` is parameterized as `REF v${VERSION}`; the overlay replaces it with the
literal branch/commit precisely because no tag exists yet. Phase B restores the parameterized form
by leaving the registry portfile's `REF` untouched.

Update `vcpkg-overlays/ports/qvac-fabric/vcpkg.json` with `"version": "<VERSION>"`. (Overlays bypass
version resolution entirely, so this version only needs to satisfy the consumers' existing
`version>=` pin — the new `<VERSION>` is fine.)
Copy any other files from the registry port too (e.g. `android-vulkan-version.cmake` if present).

### Step 3: Add overlay-ports to all 7 consumers
In each `packages/<consumer>/vcpkg-configuration.json`, add:
```json
"overlay-ports": ["../../vcpkg-overlays/ports"]
```
The path is relative to the `vcpkg-configuration.json` that declares it — hence two levels up out
of `packages/<consumer>/` and back down into `vcpkg-overlays/ports`. Same string for all 7.

If this path is wrong, **nothing errors**: vcpkg finds no overlay, silently resolves `qvac-fabric`
from the registry, and you validate the OLD version while believing you tested the new one. Confirm
the overlay is live by checking the install log for the overlay's `<VERSION>`.

Do NOT change `default-registry.baseline`.

**Do NOT bump consumer `vcpkg.json` `"version>="` in Phase A** — that happens in Phase B. The overlay bypasses version resolution entirely; only the overlay port's own `vcpkg.json` version needs to match.

### Step 4: Confirm changes with user before committing

`git diff --stat` must show **exactly 9 files** — the 7 `packages/<consumer>/vcpkg-configuration.json`
plus `vcpkg-overlays/ports/qvac-fabric/{portfile.cmake,vcpkg.json}`. Anything else means something
got swept in; in `--on-top-of-pr` mode that something is the PR author's own work.

### Step 5: Commit and push to upstream branch (NOT fork)
```bash
git push origin <branch>
```
`origin` = `tetherto/qvac` (cloned directly, not a fork). Push straight to origin.

#### `--on-top-of-pr` — one commit, and only the overlay in it

Phase B removes the overlay by **reverting this commit**, so its contents decide whether that revert
is safe. Two halves, both required:

- **The commit holds those 9 files and nothing else.** Consumer C++ fixes from Step 7 are real work
  that stays on the PR after the rollout — they go in *separate* commits. Fold a fix into the overlay
  commit and Phase B's revert silently removes the fix along with the overlay.
- **The message has to be findable and self-explanatory**, because the next person to read it is
  whoever is triaging the PR:

  ```
  <TICKET> chore[notask]: overlay-validate the 7 fabric consumers against <fabric-ref>

  Rollout Phase A for the <feature> fabric change. Adds the shared qvac-fabric overlay
  port and points all 7 consumers at it, so they build against the fabric branch head
  before the tag exists and before anything is published to the registry.

  Consumer version>= pins are untouched — the overlay bypasses version resolution, so
  only the overlay port's own version matters here; bumping the pins is Phase B.
  default-registry.baseline is untouched in all 7.

  TEMPORARY. This commit is reverted by /rollout-phase-b --on-top-of-pr before the
  fabric dependency bump. The PR itself is meant to merge; this commit is not.

  Rollout-Overlay: qvac-fabric <VERSION> ref=<fabric-branch-or-commit> sha=<fabric-sha>
  ```

  The trailing `Rollout-Overlay:` line is functional metadata — it is what Phase B greps for. Keep it
  last and keep the prefix exact.

**Do not copy `DO NOT MERGE` from a validation-branch commit.** On a dedicated branch that marked the
whole branch as throwaway. Here the PR *is* meant to merge; it is the overlay **commit** that must go
first, and the wording above says so precisely.

Push to the PR's head branch, then **print the resulting commit SHA** — it is Phase B's input.

### Step 6: Trigger validation CI per consumer (`workflow_dispatch`)
```bash
for w in embed-llamacpp fabric llm-llamacpp model-fit ocr-ggml translation-nmtcpp vla; do
  gh workflow run on-pr-$w.yml --repo tetherto/qvac --ref <validation-branch>
done
```
- The workflow file for the `vla-ggml` consumer is `on-pr-vla.yml` (NOT `on-pr-vla-ggml.yml`).
  `on-pr-fabric.yml` and `on-pr-model-fit.yml` follow the standard naming — `vla` is the only
  exception.
- **Triage `fabric` first.** It is the shared runtime addon the other consumers link against, so a
  break there usually explains failures in the rest; fixing it first avoids chasing the same root
  cause across six other runs.
- Do NOT add stage labels to a validation PR — with `prebuilds` or any `run-*` label on it, every
  push re-runs ALL consumers (`pull_request_target` fires on each synchronize). `workflow_dispatch`
  is a trusted event in `ci-router` (no label needed, every stage enabled) and lets you re-run only
  the consumer(s) you actually changed. `verified` is **not** one of the labels to avoid adding or
  to add — `ci-router` reads only `prebuilds`, `run-cpp-addon-tests`, `run-desktop-addon-tests`
  and `run-mobile-addon-tests`; `verified` selects nothing.
- **A draft validation PR routes nothing at all.** `ci-router` sets `IS_AUTHORIZED=false` when
  `draft` is true, so *zero* stages run however many labels are on it — labels on a draft buy no
  coverage. Mark it ready, or drive it by dispatch.
- First pass: all seven. Later iterations: re-dispatch just the one(s) you touched.
- **A re-pin counts as touching all seven.** Moving the overlay's `REF`/`SHA512` changes the fabric
  every consumer builds against, so re-dispatching only `fabric` after one leaves the other six
  showing a **stale green from the previous fabric ref**, with nothing to say so. Nothing re-runs on
  this branch unless you dispatch it — there is no PR here, so no path filter is doing it for you.

**Expected failures / flakes while monitoring:**
- `merge-guard` / `validate-pr` always fail on a no-PR dispatch branch — expected, ignore. (Not so in
  `--on-top-of-pr` mode: a real PR has a real title, so these pass and a failure is genuine.)
- Known-flaky macOS and mobile device-farm jobs are typically non-blocking and orthogonal to a fabric
  change — confirm they're pre-existing / baseline-reproducible, retry the failed job (not the whole
  run), and don't chase them as rollout blockers.

#### `--on-top-of-pr` — do NOT dispatch; the push already triggered CI

The Step 5 push auto-triggers all 7 consumer workflows: the overlay commit edits every
`packages/<consumer>/vcpkg-configuration.json`, which each `on-pr-<consumer>.yml` path-matches via
`packages/<consumer>/**`. Monitor those runs. Dispatching as well would duplicate every run on the
same ref.

**Ask before adding labels.** Step 0's eligibility report says which stages the PR is actually
eligible for, and without `prebuilds` none of them compile anything. Adding labels changes the CI
cost of someone else's PR, so present the report, ask, and add only what was approved. `prebuilds`
alone gets the addon built against fabric; `run-cpp-addon-tests` / `run-desktop-addon-tests` /
`run-mobile-addon-tests` add the test tiers (each of the latter two implies `prebuilds`).

**Re-pinning the overlay re-triggers all 7 — `paths:` matches the whole PR, not the push.** When you
iterate by moving the overlay's `REF`/`SHA512`, a commit touching only
`vcpkg-overlays/ports/qvac-fabric/portfile.cmake` still fires every consumer workflow. On a
`pull_request_target` event GitHub evaluates `paths:` against the PR's **cumulative** changed-file set
(`base...head`), not the delta of the push that triggered it — and Step 5's overlay commit already put
all 7 `packages/<consumer>/vcpkg-configuration.json` into that set, so each `on-pr-<consumer>.yml`
keeps matching on `packages/<consumer>/**` for the rest of the PR's life. Do **not** touch the 7
configs to force a rebuild, and do not dispatch the six: both add noise to someone else's PR for an
effect you already have.

The same rule is why adding a label re-runs all 7 — a `labeled` event carries no file delta at all,
yet the cumulative path match still holds. Verified on qvac#3725: commit `40a157675` changed two lines
of the portfile and fired Fabric, Embed, LLM, Model Fit, NMTCPP, OCR-GGML and VLA.

This is the one place where the two modes genuinely diverge, so do not carry the default flow's
instinct across: on a dispatch-driven validation branch there is no PR and no cumulative diff, so
nothing re-runs unless you dispatch it — see the re-pin warning in Step 6 above.

### Step 7: Fix consumer breaks
Apply C++ fixes (API drift, new failure modes) using the Edit tool — specific lines only. Never `git checkout <branch> -- file.cpp` (takes the whole file, causes regressions).

Watch for:
- **API drift** — a fabric bump pulls a newer upstream llama.cpp/ggml whose API may have moved
  (renamed/relocated struct fields, changed signatures). Fix in the consumer addon.
- **Runtime behaviour shifts** (perf, threading, init paths) — if an integration test now hits a
  timeout, calibrate the timeout with a comment explaining why; NEVER skip/disable the test. Guard
  new failure modes (e.g. an init call returning null) with a catchable error, not a segfault.

**`--on-top-of-pr`:** these fixes are real work that stays on the PR — commit them **separately** from
the Step 5 overlay commit, never as an amend to it. That commit has to stay a pure overlay so Phase B
can revert it without taking a fix with it.

### Step 8: Update the fabric PR description with the validation runs
Once all consumers are green, add the validation CI runs to the fabric PR description — one bullet
per consumer, all 7 listed, noting the head commit they validated:
```
- <consumer name>: <CI run link>
```
In `--on-top-of-pr` mode these are the target PR's own runs; name the PR and the head commit they
validated, so a later reader can tell which fabric ref the green belongs to.

### Step 9: Post Slack message when all consumers green
```
Hi Team, Please review the PR for <feature name>
Fabric PR: https://github.com/tetherto/qvac-fabric-llm.cpp/pull/<N>
Validation branch: <validation-branch> (consumer CI runs listed in the fabric PR description)
```
If a qvac validation PR was opened, add its link (`Add on PR: https://github.com/tetherto/qvac/pull/<N>`).

In `--on-top-of-pr` mode, replace the validation-branch line with the target PR and say the overlay is
temporary, so nobody merges it by mistake:
```
Validated on: https://github.com/tetherto/qvac/pull/<N> (carries a TEMPORARY qvac-fabric
overlay commit — /rollout-phase-b reverts it before the dependency bump)
```

If you have no Slack access, print the message (with the links) to the console so the user can post it.
Wait for lead to merge fabric PR before proceeding to `/rollout-phase-b`.