Qv Merge Guard Wire

Merge Guard Wire — hook a new job into the required status check

qvac-merge-guard / validate-pr is the single required status check on main. Adding a new CI job without wiring it into this aggregate creates a second, disconnected check the branch ruleset never requires — its failures become invisible. This skill is the checklist for wiring a job into the existing aggregate correctly.

Full reference with diagrams and worked examples: docs/ci/MERGE-GUARD.md.

When to use

• Adding any new job/workflow that should block merges — regardless of domain (addon package check, SDK check, docs validation, security scan, licensing gate, anything).
• A PR review flags a new job that isn't reflected in qvac-merge-guard's pass/fail.

Hard rule: nothing but pr-gate-merge.yml may produce the qvac-merge-guard / validate-pr check name

grep -rl "^  qvac-merge-guard:$" .github/workflows/*.yml

Must return only pr-gate-merge.yml. If any other file has a job id qvac-merge-guard (or a job calling a reusable workflow whose job id is validate-pr), that's a collision — it would silently satisfy the required check without going through the real gate. Fix before doing anything else in this skill.

Step 1 — Read the current job graph

Read .github/workflows/pr-gate-merge.yml, specifically the final qvac-merge-guard job's needs: list and the three with: booleans it passes to public-pr.yml. Read docs/ci/MERGE-GUARD.md for the diagram and worked examples.

Note: sdk-pod-checks reports under two check-context strings (SDK Pod Checks and sdk-pod-checks / SDK Pod Checks) — branch-coverage artifact, not a ruleset requirement. See the doc's "Gotcha" section.

Step 2 — Ask the user which of the three patterns fits — do not silently infer it

Present these three options as an explicit question and let the human pick. Even if the repo state (an existing half-built caller workflow, an existing similar job, etc.) suggests one pattern, don't silently commit to it — surface the choice and its tradeoffs, then proceed with whichever the human confirms:

1. Folds into an existing category (another instance of a check already gated on, whatever its domain) — if matrix/filter-driven, add it to the changes job's dorny/paths-filter map; no other wiring needed. Otherwise add the job to an existing category's needs: and AND its result into that category's boolean expression.

2. A repeated, growing family of similarly-shaped jobs — more than one or two near-identical jobs differing only by target (one per package, one per platform, one per service, whatever naming pattern). Only one target today? This is not your pattern — use 1 or 3 instead and wire the single job directly. A caller workflow's value is dispatching to multiple targets from one place; building one for a single target is pure indirection. Refactor into a caller once a second target genuinely shows up.

   When there truly are multiple targets, check matrix vs. caller before building anything — this repo has both shapes for the same problem:

   • Uniform job body across targets (same composite action/steps, only e.g. workdir differs) → use a matrix like sanity-checks (strategy.matrix.include: ...). No caller workflow at all; the matrix job itself is what qvac-merge-guard depends on.
   • Heterogeneous per-target jobs (different uses:/inputs/secrets per target, or steps that genuinely diverge) → use a caller workflow with one named job per target, like prebuilds-caller.yml. This shape exists mainly for readability/separation, not because a matrix is technically impossible.

   Do not add each family member individually to qvac-merge-guard's needs:. Whichever shape you land on (matrix or caller), wire only that one job/caller into pr-gate-merge.yml, and feed its result into public-pr.yml's existing spare integration-tests-status input if unclaimed (don't invent a new one if a spare already fits).

3. Genuinely new category — a one-off job that isn't a repeated family and doesn't fit any existing boolean. Add the job, add it to qvac-merge-guard's needs:, and either reuse public-pr.yml's other spare input (build-with-model-status) or add a brand new boolean to both the with: block and public-pr.yml's workflow_call.inputs + shell check block.