# Template — `MGF_ADOPTION.md` for a consumer project

> **What this is.** Fork-and-fill template for the
> `MGF_ADOPTION.md` tracker every project depending on
> mgf-common ships per **DOC-14** + **ADP-01..04**.
> **Audience.** Maintainers of consumer applications adopting
> mgf-common (or any sibling). NOT for federation siblings
> themselves — they have the federation_roadmap, ADP-04
> carve-out.
> **Reference shapes.**
> [TelePlasma/docs/inprogress/MGF_ADOPTION.md](https://codeberg.org/magogi-admin/TelePlasma/src/branch/main/docs/inprogress/MGF_ADOPTION.md),
> [inthewords/docs/MGF_COMMON_ADOPTION.md](https://codeberg.org/magogi-admin/inthewords/src/branch/main/docs/MGF_COMMON_ADOPTION.md).

---

## How to use this template

1. **Copy** the block below into your repo as
   `docs/inprogress/MGF_ADOPTION.md` (recommended per ADP-01)
   or `docs/MGF_ADOPTION.md` (alternate).
2. **Link from your README** so consumers + AI agents can find
   it.
3. **Initial state:** populate the at-a-glance, pick a
   conformance level (L1 / L2 / L3 — see
   `MGF_STANDARDS_CONFORMANCE.md`), describe your strategic
   context.
4. **Update cadence** (ADP-03): on every pin bump AND every
   closed FEEDBACK paper that touches this project.

---

## Template — copy from below

```markdown
# mgf-common adoption tracker — <PROJECT-NAME>

> **Purpose.** Track <PROJECT-NAME>'s adoption of mgf-common
> from its current pin to full conformance with the current
> standards. **Living checklist** — flips as audits run, pins
> bump, FEEDBACK papers close.
>
> **Scope.** <PROJECT-NAME> is a <small/medium/large> consumer
> by mgf-common's framing. Adoption discipline is "adopt only
> what we actually call" — see strategic context below.
>
> **Conformance level.** L<1/2/3> — declared in
> [README.md](../../README.md) and (where applicable)
> ARCHITECTURE.md. See
> [`MGF_STANDARDS_CONFORMANCE.md`](MGF_STANDARDS_CONFORMANCE.md)
> for per-rule conformance status.
>
> **Sister consumers.** (links to other Magogi consumer projects'
> equivalent trackers — useful for cross-consumer grep)

---

## §1 At-a-glance

| Field | Value |
|---|---|
| Tracker opened | YYYY-MM-DD |
| Owner | <name> |
| mgf-common pin (current) | `>=0.X,<0.Y` |
| Extras declared | `[<extras-list>]` |
| Sibling pins (current) | `mgf-fastapi>=...`, `mgf-sqlalchemy>=...`, etc. |
| Sibling-source overrides | dev-only path overrides, if any |
| Catch-up status (latest run) | N ✅ · N 🔴 · N ⚠️ |
| Four-gates status | ruff · mypy --strict · pytest · lint-imports |
| FEEDBACK round | latest closure summary |
| Phase | A/B/C/D — see §3 |

Single command to re-audit at any time:

\`\`\`bash
mgf-fed catch-up                # read-only
mgf-fed catch-up --apply        # mechanical fixes only
mgf-fed app-doctor                  # install + wiring health
mgf-fed explain                 # active settings + sources
\`\`\`

---

## §2 Strategic context

(One paragraph: what shape is this project — desktop / web /
service / CLI? What's its trajectory? Why does the adoption
posture make sense for this shape? Reference any per-shape
carve-outs from mgf-common's standards that apply here.)

---

## §3 Phase status

| Phase | Status | Notes |
|---|---|---|
| Phase 0 — discovery | ⏳ / ✅ / 🚫 | initial catch-up + paper-filing |
| Phase 1 — scaffolding | ⏳ / ✅ / 🚫 | pyproject + four gates wired |
| Phase 2 — bootstrap + install | ⏳ / ✅ / 🚫 | `bootstrap()` integrated |
| Phase 3 — exception migration | ⏳ / ✅ / 🚫 | (if applicable) |
| Phase 4 — logging migration | ⏳ / ✅ / 🚫 | (if applicable) |
| Phase 5+ — feature uptake | rolling | per-feature adoption notes |

---

## §4 Pin-bump history

(One row per pin bump. Append; don't overwrite. Useful for
"when did we land mgf-common 0.X.0?" archaeology.)

| Date | From | To | Notes |
|---|---|---|---|
| YYYY-MM-DD | `>=0.X,<0.Y` | `>=0.Z,<0.W` | (what landed; what code changed; what paper closed) |

---

## §5 FEEDBACK rounds

(One subsection per round. Captures: papers filed, papers
closed, commit references for both sides.)

### Round 1 (YYYY-MM-DD)

- **Filed:** PAPER-NN (title) — [linkb](url).
- **Closed:** PAPER-NN — shipped in mgf-common commit `<sha>`,
  released as v0.X.0.

---

## §6 Cross-references

- [`<this-project>/FEEDBACK.md`](../../FEEDBACK.md) — papers
  filed BY this project (sibling/library-scoped per FB-04).
- [`MGF_STANDARDS_CONFORMANCE.md`](MGF_STANDARDS_CONFORMANCE.md)
  — per-rule conformance status (different concern from this
  tracker).
- [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
  — federation-wide PAPER pool.
- [mgf-standard/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md)
  — DOC-14 + ADP-01..04 (adoption-tracker rules).
```

---

## Update-cadence rules (ADP-03)

You MUST update this tracker on:

1. **Every pin bump** of `mgf-common` or any sibling — append a
   row to §4.
2. **Every closed FEEDBACK paper** that touches this project's
   adoption surface — append a bullet to the appropriate
   round in §5.
3. **Every conformance-level promotion / demotion** — update §1
   and `MGF_STANDARDS_CONFORMANCE.md` together.

The `mgf-fed catch-up` auto-block in your `docs/CLAUDE.md`
carries an `adoption-discipline` reminder for AI agents working
on this project.

---

## Federation-sibling carve-out (ADP-04)

Federation siblings (mgf-fastapi, mgf-http, etc.) do NOT
maintain `MGF_ADOPTION.md` — their adoption relationship to
mgf-common is documented in [federation_roadmap.md](../../docs/inprogress/federation_roadmap.md)
and their own CHANGELOG. But they DO maintain
`MGF_STANDARDS_CONFORMANCE.md` (CFM-01 applies to them too).
