# v1.0 maintainer HAND-OFF (Wave 4 / E4)

**Status:** STOP point. Wave 4 is complete. Wave 5 = the v1.0 cut itself, which
is **the maintainer's call**, not Claude's.

**Generated:** 2026-05-18.
**Owner of next action:** maintainer (Bassam).

---

## §1 What's done

Five waves of federation work were planned. Four have shipped:

| Wave | Scope                                                          | Outcome                                                                 |
|------|----------------------------------------------------------------|-------------------------------------------------------------------------|
| Phase A | Standards v2.8 — FEEDBACK / MGF_ADOPTION / MGF_STANDARDS_CONFORMANCE | DOC-13/14/15 + FB-01..04 + ADP-01..04 + CFM-01..04 added.              |
| Wave 1  | mgf-common 0.35.0 + 0.36.0 — flags, schedule, plugins, doctor       | 22 new public names. 4 federation primitives.                          |
| Wave 2  | Six sibling minors — bundle PAPER closures + new features           | 26 new public names across the 6 siblings.                             |
| Wave 3  | mgf-common 0.37.0 — rate_limit / idempotency / health / cache       | 17 new public names. 4 cross-cutting protocols.                        |
| Wave 4  | Stability audit + quality-gate sweep + this hand-off                | 2 audit docs + 2 retrospective updates. **NO version bumps**.          |

**Federation surface delta this cycle:** +65 public names (50 features + 15
audit-doc names not counted in §3). Net experimental count: 248 federation-wide.
Net stable count: 114.

**Federation test sweep (2026-05-18):** 2885 passed, 0 failed.

---

## §2 What to read, in order

1. **[`v1_0_stability_audit.md`](v1_0_stability_audit.md)** —
   experimental→stable promotion proposal per module. The §3 table is the
   sign-off worksheet.

2. **[`v1_0_quality_gates.md`](v1_0_quality_gates.md)** —
   the QG-1..QG-12 gate matrix. Q-2 and Q-4 are the two real v1.0 blockers.

3. **[`pre_release_additions.md`](pre_release_additions.md) §12** —
   confirms 15/15 roadmap candidates shipped (no carry-over from earlier waves).

4. **[`pre_release_check.md`](pre_release_check.md) §9 (2026-05-18 rows)** —
   re-keys the original B-/I-/N- blockers to the new Q-* blockers from
   Wave 4.

---

## §3 Three decisions you (the maintainer) need to make

These cannot be made by Claude — they are policy calls.

### Q-2: N818 exception-name suffix

Twelve public exception classes (8 in `mgf-http`, 3 in `mgf.common.process`,
1 in `mgf-fastapi`) do not have an `Error` suffix. PEP-8 convention says
they should. They've been in `PUBLIC_API.md` as stable for multiple cycles.

- **(a)** Rename at v1.0 (e.g., `HttpBadRequest` → `HttpBadRequestError`).
  Ship aliases for one major; mark aliases deprecated on the v1.0 tag.
  Rip-the-bandaid; convention is correct from v1.x forward.

- **(b)** Lock the names; add `noqa: N818` per class with a comment.
  v1.0 ships with these names *forever*. Less churn for consumers today;
  one less Pythonic surface forever.

  **Default recommendation: (a).** It costs one cycle of alias work and a
  single CHANGELOG entry; the alternative bakes a style miss into v1.x+.

### Q-4: PyPI publication

Today, **every** federation package is behind PyPI:

  - mgf-common at 0.34 vs local 0.37 (3 behind)
  - mgf-alembic / mgf-fastapi / mgf-sqlalchemy each 3 behind
  - mgf-apiprobe / mgf-http each 1 behind
  - mgf-django **never published**
  - mgf-website-template intentionally template-only

v1.0 cannot ship from a federation that hasn't shipped 0.x to PyPI first.

- **(a)** Wait for the private PyPI server (your stated path). Cut v1.0
  from that index. Consumers configure their `pip install --index-url`
  to it.

- **(b)** Drain the public PyPI backlog now (one queue cycle past the
  new-project rate-limit), then cut v1.0 to public PyPI.

  No default recommendation — this is your strategy call, not a technical one.

### Q-11: Stability promotion sign-off

`v1_0_stability_audit.md` §3 proposes **~38 names move experimental→stable
in mgf-common** and **~94 names hold one more MINOR**. The siblings hold all
experimental (0 promotions there).

Before v1.0, you should walk that §3 table row-by-row and either:

  - sign off ("yes promote") — Claude will then edit `PUBLIC_API.md` to flip
    `experimental` → `stable (v1.0.0)` and run the pinned test.
  - reject ("no, hold") — Claude leaves it experimental for v1.0.

You can also propose **additional** promotions Claude didn't pick (or
**fewer**). The proposal is a starting point, not a vote.

---

## §4 What WILL happen when you give the word

The moment you say "go cut v1.0":

1. Resolve Q-2 (rename or noqa).
2. Resolve Q-4 (publish path).
3. Resolve Q-11 (promotion list).
4. Apply promotions to `PUBLIC_API.md` + regenerate `PUBLIC_API.json`.
5. Bump mgf-common to 1.0.0.
6. Update CHANGELOG with "v1.0.0 — first stable release" section.
7. Run federation test sweep one more time. Must be 2885+ green.
8. Build + twine check + commit + tag `v1.0.0` + push to Codeberg.
9. Upload to PyPI (your private index or public).
10. Refresh sibling pyproject pins: `mgf-common>=1.0,<2`.

**The siblings do NOT cut v1.0 in this same cycle.** Each gets its own
audit + v1.0 when its maintainer (you, today) is satisfied with its
consumer mileage. The audit pattern in `v1_0_stability_audit.md` is
reusable per-sibling.

---

## §5 What WILL NOT happen until you say go

- No version bumps from any Wave 4 work.
- No edits to `PUBLIC_API.md` (Wave 4 was *recommendation only*).
- No tag pushes.
- No PyPI uploads.
- No promotion of any experimental → stable.

Wave 4 was deliberately read-only on the public surface. The doc set
exists; the proposal is ready. The maintainer holds the trigger.

---

## §6 Outstanding non-v1.0 work tracked elsewhere

These are deferred to v1.x — *not* blockers:

- Q-1: Port `PUBLIC_API.json` generation to each sibling (sibling-v1.0
  blockers, not mgf-common-v1.0).
- Q-3: Sweep mgf-common ruff backlog (31 auto-fixable findings).
- Q-5: `tools/verify_standards_sync.py` for cross-repo standards drift.
- `extraction_watch_list` memory: webhook-audit, health-probes,
  cursor-pagination — all parked until 2nd-consumer evidence.

Tracker: `pre_release_additions.md` §10 (parked candidates).

---

## §7 STOP

Wave 4 ends here. The maintainer's review starts here.

Claude will not:

- propose v1.0 again until asked.
- modify any source file in this session.
- push any commit or tag.
- bump any version.

When you're ready, say what you decided on Q-2 / Q-4 / Q-11 (or all three)
and a new wave will start.
