# `docs/recipes/` — federation-operations recipes

> **Audience:** federation maintainers and AI agents performing governance
> operations across the `mgf-*` family.
> **What this is NOT:** library-usage how-tos (those live in
> `mgf-common/docs/recipes/`).

These recipes cover **how to operate and govern the federation** — cohort
releases, sibling lifecycle events, compliance templates, and the reusable
sync prompt. They are not about how to build with `mgf-common`; they are about
how to keep the federation itself healthy.

For engineering rules (MUST/SHOULD/MAY), see [`../standards/`](../standards/).

## Onboarding — start with `mgf-fed start`

The four onboarding prompts below (`sync` / `new-project` / `adopt` / `onboard`)
each cover one case. You rarely need to pick by hand: **`mgf-fed start`** is the
single front-door. It is print-only — it auto-detects when the repo is already a
federation member (prints the **sync** prompt) and otherwise prints a scenario
menu. Force a case with `mgf-fed start --mode {new|onboard|sync|adopt}`; list the
menu with `mgf-fed start --list`. The four `*-prompt` verbs remain the direct
entry points it dispatches to.

| Intent | `--mode` | Prompt it prints |
|---|---|---|
| already an `mgf-*` member, get current | `sync` | `federation-sync-prompt` |
| empty repo → new member | `new` | `federation-new-project-prompt` |
| existing external code → join as member | `onboard` | `federation-onboard-prompt` |
| adopt the standards, stay independent | `adopt` | `federation-adopt-prompt` |

---

## Index

| Recipe / Template | What it covers |
|---|---|
| [`sibling_rename.md`](sibling_rename.md) | Rename a federation sibling (separator drift or whole-name change). Eight-surface checklist: sibling code, PyPI, Codeberg, mgf-common refs, each consumer's pyproject + uv.sources + venv `.pth` + on-disk husks. Closes PAPER-79 Approach A. |
| [`federation-update-strategy.md`](federation-update-strategy.md) | **Umbrella procedure** for updating more than one `mgf-*` project at once. Picks the scope (R1 one-lib / R2 all-libraries / R3 +consumer-apps), fixes the dependency-ordered **walk order** (the generated `fed_waves.py` waves, roots→leaves), sequences the two engines (cohort-release-wave + federation-sync-prompt), and defines the close-out proof (per-repo gate + REST-200 barrier + REL-13 GREEN / app tracker). The "when, in what order, how to know you're done" layer above the two recipes below. |
| [`cohort-release-wave.md`](cohort-release-wave.md) | Federation cohort-release procedure (REL-10/11/12). Phase A parallel mechanical edits + Phase B sequential ship. Required when a `mgf-common` MINOR breaks any sibling's pin upper-bound. |
| [`local-release.md`](local-release.md) | The **local-release** mode (`mgf-fed release-local`): build-once → validate against the local index → publish there, wave-ordered + local-first. The QA / pre-promotion gate run before any remote release. Reaffirms REL-02 / REL-08. |
| [`remote-release.md`](remote-release.md) | The **remote-release** mode (`mgf-fed release-remote`): promote the locally-validated wheel to the devpi index — annotated tag (REL-01) → publish (PKG-04) → verify-devpi (PKG-05) → consistency gate (REL-13). Build-once / promote (REL-02). |
| [`run-ci.md`](run-ci.md) | **Run CI locally + remotely (WF-13 + activation).** The single "how do I run the pipeline" recipe: locally with `mgf-fed local-ci <repo>` (`woodpecker-cli exec`, full gate set; note the shared-workspace caveat for parallel supervisor steps); the pipeline is a **generated** artifact (`mgf-fed scaffold` from the canonical template — don't hand-edit, **WF-13**); remotely by push/PR once remote Woodpecker is **activated** (see `activate-ci.md`; present-but-dormant until then); release via `release-local` → `release-remote`. |
| [`activate-ci.md`](activate-ci.md) | **Turn remote CI on — the operational step that makes WF-01/WF-02 real.** Connect a repo to Woodpecker (`ci.codeberg.org`) so its generated pipeline actually RUNS + gates: the one-time Woodpecker API token, enable the repo (WP API), gate-only event config (no publish secrets — `mgf-fed` publishes), Codeberg branch-protection (require the CI status check), trigger + verify, and the per-repo coverage-floor reds the first real run surfaces. **WF-13 = pipeline present + current; this = pipeline actually runs.** |
| [`federation-sync-prompt.md`](federation-sync-prompt.md) | The reusable prompt to drop into any sibling `mgf-*` repo so an agent syncs it with `mgf-common` + the federation, catches every update (pins, extractions, standards), and brings it into conformance — read-only on the federation, no unsolicited releases. |
| [`federation-new-project-prompt.md`](federation-new-project-prompt.md) | **Case B — bootstrap an EMPTY repo into a federation member.** install `[standards]` → understand (`agents`/`standards`) → `mgf-fed init-project --kind …` (scaffold) → `sync-prompt` to conform → declare level + DEPS + inherit `/sync`. Printed by `mgf-fed new-project-prompt` (or `mgf-fed start --mode new`; self-updating). |
| [`federation-adopt-prompt.md`](federation-adopt-prompt.md) | **Case C — a NON-member understands / adopts the standards.** install `[standards]` → understand → CONSUMER (MGF_ADOPTION.md + pins) or LEARNER (port selectively; non-adoption first-class) → feedback welcomed. NOT a member: no `init-project`, no §Z ledger. Printed by `mgf-fed adopt-prompt` (or `mgf-fed start --mode adopt`). |
| [`federation-onboard-prompt.md`](federation-onboard-prompt.md) | **Onboard — bring an EXISTING external project INTO the federation as a member.** install `[standards]` → understand → decide join shape (sibling `mgf-<name>` or consumer app) + add `mgf-common` → conform existing code via the sync engine (many ⏳ at first is fine) → declare + ask to be registered. Printed by `mgf-fed onboard-prompt` (or `mgf-fed start --mode onboard`). |
| [`feedback-relay.md`](feedback-relay.md) | **The other half of the feedback loop (FB-05).** Drains a sibling's `pending-feedback/<target>.md` outbox into the target's `FEEDBACK.md` — the deterministic, idempotent, gated relay run by the *supervisor* (the sole sanctioned cross-repo writer). Defines the outbox schema + the relay procedure + the `mgf-fed feedback` tool spec, closing the one manual seam the sync-prompt's FEEDBACK-OUT step writes into. |
| [`codeberg-pr.md`](codeberg-pr.md) | The canonical CLI for federation PR operations: install `tea` (Forgejo CLI; `gh` is GitHub-only), add a repository-scoped Codeberg login, and `tea pr create` / `merge` / `list`. Removes the manual "hand back the compare URL" step at the end of the land-the-slice loop. Closes PAPER-01. |
| [`umbrella-drain.md`](umbrella-drain.md) | Draining a consumer off a retiring umbrella `mgf-*` package onto the granular siblings/contracts that replace it. Centers on the **slice classification gate** — per removed call, verify (Q-A) the neutral value type carries every field the consumer *reads* and (Q-B) the legacy actually populated it in production; cross-repo-blocked only when a real field is genuinely missing. Closes PAPER-02. |
| [`commit-signing.md`](commit-signing.md) | The one-time git setup (identity + per-repo `.gitmessage` template) and per-commit discipline for the two **AG-03** signing trailers — canonical `Signed-off-by: Bassam Alsanie <bassam@magogi.org>` + the drafting agent's `Co-Authored-By:`. Applies to **every** `mgf-*` repo. |
| [`standardized-git-config.md`](standardized-git-config.md) | **The full AG-18 git wiring** — the canonical `.gitignore` (build / IDE / Claude-local artifacts + the never-committed `my_stuff/` secrets dir, PKG-03), the `.gitmessage` commit template wired via `commit.template`, and the canonical identity. `catch-up --apply` appends missing ignore lines; `doctor` checks `my_stuff/` is ignored. The companion to `commit-signing.md`. |
| [`in-repo-memory.md`](in-repo-memory.md) | **The AG-17 committed-memory convention** — `docs/memory/` (a `MEMORY.md` index + one-fact-per-file topic notes) so durable, federation-scoped agent context travels with the repo instead of living only in a machine-local `~/.claude/` store. The committed tier alongside `docs/claude/CLAUDE.md` (DOC-07) + `LESSON_LEARNED.md` (DOC-19). |
| [`shared-code.md`](shared-code.md) | The **shared-code / duplication discipline**: "one behavior, one home" with the counterweight "duplication is cheaper than the wrong abstraction." The design-time DUP check, the rule-of-three extraction trigger, duplication-as-defect + waivers, the junk-drawer-name ban (NM-05), blast-radius tiers on shared code, and blame-free eviction. Folded back from the Plasma project's (since renamed **soothfast**) Commons standard (PAPER-107). |
| [`federation-pointer-stub-template.md`](federation-pointer-stub-template.md) | The DOC-17 pointer-stub template every `mgf-*` sibling copies into its own `FEDERATION.md` to point at the canonical contract here. |
| [`mgf-adoption-md-template.md`](mgf-adoption-md-template.md) | Template for a sibling's `MGF_ADOPTION.md` — the per-repo declaration of which federation rules it adopts and at what conformance level. |
| [`mgf-standards-conformance-md-template.md`](mgf-standards-conformance-md-template.md) | Template for a sibling's `MGF_STANDARDS_CONFORMANCE.md` — the rolling per-MUST compliance table (✅ / 🟠 / ❌ / ➖) with evidence and CFM-04 carve-out records. |
| [`deps-md-template.md`](deps-md-template.md) | Fork-and-fill template for a project's `DEPS.md` bidirectional dependency manifest (DOC-16) — §1 what this project depends on, §2 who depends on it. |
| [`feedback-md-template.md`](feedback-md-template.md) | Fork-and-fill template for a project's `FEEDBACK.md` consumer-feedback queue — paper structure, severity markers, and the FB-01..FB-04 lifecycle fields. |
| [`lesson-learned-md-template.md`](lesson-learned-md-template.md) | Fork-and-fill template for a project's root `LESSON_LEARNED.md` — the append-only, dated log of non-obvious lessons learned *in this repo* (corrected assumptions, gotchas, reusable techniques, dead ends) so the federation stops re-learning them. The federation-sync prompt's LESSON-OUT step appends here; generalizing lessons ALSO route to a `pending-feedback/` paper. Binding-rule proposal in FEEDBACK PAPER-03. |
| [`pr-standard-test-plan-template.md`](pr-standard-test-plan-template.md) | Copy-paste test-plan template for PRs adopting a new standards rule — the second-adopter checklist shortcut (PRESENTATION_LAYER.md §8.1). |
| [`library-app-separation.md`](library-app-separation.md) | Process recipe for cleanly separating library code from application code when a consumer or sibling extracts a reusable primitive — when to extract, where to put it, and how to migrate consumers. |
| [`test-supervisor-adoption.md`](test-supervisor-adoption.md) | Step-by-step guide for adopting `mgf-test-supervisor` in a new project — install, configure markers and timeout, register the plugin, and run the self-check (TS-22..TS-27). |
| [`architecture-review.md`](architecture-review.md) | **Review methodology (review-time).** The principal-engineer AUDIT / REDESIGN / RESTRUCTURE review for a critical codebase — mode handshake, persistent git-tracked review folder, native testing lens, evidence/confidence + concrete-cost discipline. The foundation's golden design+test review prompt, federation-integrated. |
| [`ui-review.md`](ui-review.md) | **Review methodology (review-time).** The principal-UI-engineer BUILD / REVIEW pass across CLI / Qt / web / mobile — design tokens, component library, accessibility / i18n / sensitive-data / lifecycle, functional + visual testing. The foundation's golden UI prompt, federation-integrated. |
| [`doc-review.md`](doc-review.md) | **Review methodology (review-time).** The principal-tech-writer AUDIT / REORGANIZE / REWRITE / MAINTAIN pass — code-is-truth verification at a pinned version, Diátaxis, generated-docs-at-source, the persistent review folder. The foundation's golden documentation prompt, federation-integrated. |

---

## Review methodologies vs binding rules (read before using the review recipes)

The three **review-methodology** recipes above (`architecture-review` /
`ui-review` / `doc-review`) are a **different kind** of artifact from
everything else here, and from `docs/standards/`. Keep the distinction:

- **They are REVIEW-TIME, not adopt-time.** They tell an agent how to
  *assess* a codebase and produce findings + proposals in a **separate,
  transient, git-tracked review folder** (default `../<project>-review/`)
  — they explicitly **never edit the project under review**. That is the
  opposite of the federation's normal **adopt-and-ship** model, where docs
  ship in the *same commit* as code (DOC-04 / DOC-18 / AG-14). Do **not**
  compile a review recipe's "never edit the target" stance, its per-finding
  multi-letter ID grammar (F-/R-/S-/T-…), or its rich per-finding schema
  into a binding `docs/standards/` rule — those live **only inside the
  recipe**, as review work-products.
- **The FEEDBACK seam is the federation's, not a parallel one.** Where a
  golden prompt stages cross-cutting feedback in an `MGF_COMMON_FEEDBACK`
  file, the federation equivalent is the **`FEEDBACK.md` PAPER lifecycle**
  (AG-04 / AG-11 / AG-13, FB-01..FB-04): file the paper in the target
  project's `FEEDBACK.md`; only the supervisor changes a library. A review
  surfaces and proposes; adoption is a separate, supervised step.
- **One canonical conformance ledger.** A review's findings about standards
  conformance reconcile into the project's existing
  `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` (DOC-15 / the six-flag
  [`audit-outcomes`](../standards/principles/audit-outcomes.md) vocabulary)
  — the review folder is the working surface, the ledger is the durable home.
- **They embody the empowerment posture.** These prompts are the exemplar
  behind the [Agent Empowerment Charter](../standards/principles/agent-empowerment-charter.md):
  mode handshake, "no change needed is a first-class answer,"
  concrete-cost-is-the-test, evidence + confidence independent of severity,
  self-correction, never-block. Read them as the worked form of that charter.

---

## Governance context

These recipes are the operational layer of the federation contract
([`../../FEDERATION.md`](../../FEDERATION.md)). When a recipe and a rule in
`docs/standards/` disagree, the rule wins — file the discrepancy via
[`../../FEEDBACK.md`](../../FEEDBACK.md) so the recipe can be brought into line.
