# AP-16 cohort-wave runbook — adopt the federation pin-window fleet-wide

**Scope:** Item 1b / rule **AP-16** (`API_DESIGN.md` §4.4). One-time rollout.
**Owner:** the maintainer driving the wave — the mechanical per-repo steps are
agent-drivable; the merges and the one host secret are human/host-gated.

## What this does

Turns AP-16 **ON** for the 27 `mgf-common`-consuming siblings: widen each
`mgf-common` pin to the AP-16 window `>=<floor>,<1.0` and regenerate its
`.woodpecker.yml` so the `mgf-common-matrix` compat step ships. After this, a
`mgf-common` MINOR bump no longer forces a fleet-wide pin-walk — the wide window
absorbs it, and the per-repo compat-matrix + the cornerstone `ping-siblings`
fan-out keep it honest.

## Preconditions (ALL must hold before starting)

1. **PRs merged** ✅ (2026-07-01): #181 (rule), #182 (templates + ping script), #59 (generator + verb).
2. **mgf-fed released ≥ 0.10.0** to devpi (PR #60 → tag `v0.10.0`). The compat-matrix
   only renders with the new generator. Verify:
   `pip install "mgf-fed[cli]" --index-url https://195.15.203.250.sslip.io/magogi/prod/+simple/`
   then `mgf-fed scaffold --dry-run mgf-http` shows a `mgf-common-matrix` step.
3. **Local:** the new mgf-fed installed in the working venv (so `mgf-fed scaffold`
   renders the matrix locally during the wave).
4. *(Ping only — NOT a cohort blocker):* the `woodpecker_token` secret provisioned.
   Needed for the cornerstone `ping-siblings` step to **fire**, not for the cohort
   regen. Can lag the wave.

## Targets — 27 consumers (floor = the current `>=` bound; ceiling is uniformly `<0.50`)

| repo | floor | repo | floor | repo | floor |
|---|---|---|---|---|---|
| mgf-alembic | 0.41 | mgf-fedres | 0.47 | mgf-tele-teltonika | 0.41 |
| mgf-apiprobe | 0.41 | mgf-hrb | 0.41 | mgf-test-supervisor | 0.41 |
| mgf-auth | 0.49 | mgf-http | 0.41 | mgf-test-web | 0.47 |
| mgf-brand-web | 0.47 | mgf-livepush | 0.41 | mgf-vm-core | 0.41 |
| mgf-cloud | 0.47 | mgf-logship | 0.42 | mgf-vm-firecracker | 0.41 |
| mgf-cloud-provision | 0.47 | mgf-sqlalchemy | 0.41 | mgf-vm-forensics | 0.41 |
| mgf-cloud-web | 0.47 | mgf-tele-core | 0.41 | mgf-vm-interchange | 0.41 |
| mgf-django | 0.41 | mgf-fed | 0.49 | mgf-vm-libvirt | 0.41 |
| mgf-fastapi | 0.49 | mgf-fed-web | 0.47 | mgf-vm-sdk | 0.41 |

Source of truth: `mgf-fed ping-siblings --dry-run` → 27 targets, 9 skipped
(cornerstone `mgf-common`, 6 Zig repos, `mgf-website-template`, `mgf-standard`).

## The change, per repo

1. **Widen the pin** in `pyproject.toml`: `mgf-common[...]>=<floor>,<0.50` →
   `mgf-common[...]>=<floor>,<1.0`. Keep the floor + extras; only the ceiling moves.
2. **Regenerate CI:** `mgf-fed scaffold <repo>` → rewrites `.woodpecker.yml` with the
   `mgf-common-matrix` step (floor auto-derived from the pin by the generator).
3. **Sanity:** `grep -A1 'name: mgf-common-matrix' <repo>/.woodpecker.yml` shows
   `mgf-common==<floor>.*`.
4. **PR-route** (every consumer is branch-protected): branch → commit (pin +
   woodpecker, AG-03 trailers) → push → PR → CI green → merge.

## The floor test may legitimately RED — that's AP-16 working

The matrix runs the suite against `mgf-common==<floor>.*`. If a repo's code actually
needs a newer `mgf-common` than its declared floor, this **REDS**. Fix: **raise the
floor** to the lowest MINOR the suite passes on (bisect floor → cornerstone), commit
the raised floor, re-run. Do NOT silence the matrix — a red floor means the pin was
lying about its lower bound.

## Wave order (repos are independent; pilot-first de-risks)

- **Pilot (1):** `mgf-http` (floor 0.41) — land it, confirm the matrix runs and is
  green, before fanning out.
- **Then:** the remaining 26, in any order / batches. `mgf-fed` regenerates like any
  consumer (its own CI then carries the matrix too).

## After the cohort

1. **REL-13 regen:** `python scripts/gen_mgf_libraries.py` (mgf-standard) → the
   registry's deps now show `<1.0`. Commit → PR. Confirm the REL-13
   consistency/currency gate GREEN.
2. **Verify the ping** (Item #6): on the next `mgf-common` release, confirm
   `ping-siblings` fires (post-`verify-devpi`) and each consumer's matrix runs green
   against the new cornerstone.

## Rollback

Per repo: revert the pin + woodpecker commit — the matrix step vanishes on the next
`mgf-fed scaffold` with the narrower pin. No fleet coordination; each repo is
independent.

## Automation sketch (one repo, PR-route)

```bash
R=mgf-http                                   # the repo
cd ~/PycharmProjects/$R
git checkout -b chore/ap16-pin-window origin/main
# widen ceiling to <1.0, keep the floor:
sed -i -E 's/(mgf-common(\[[a-z,]*\])?>=[0-9.]+),<0\.50/\1,<1.0/' pyproject.toml
mgf-fed scaffold $R                          # regenerate .woodpecker.yml (adds the matrix)
grep -A1 'name: mgf-common-matrix' .woodpecker.yml   # sanity: mgf-common==<floor>.*
git add pyproject.toml .woodpecker.yml
git commit -m "chore(ap16): widen mgf-common pin to <1.0 + compat-matrix"   # + AG-03 trailers
git push -u origin chore/ap16-pin-window
# → open PR (tea), wait CI green (raise floor if the matrix reds), merge
```
