# Federation sync/conformance hardening — locked spec & tracker

> **Status:** ✅ COMPLETE (2026-06-06) — WU1–WU8 all shipped + verified. mgf-standard 0.1.14, mgf-common 0.46.1; the mgf-common 0.46.0 MINOR's cohort pin-walk (all 19 siblings → `<0.47`) done; REL-13 GREEN + CURRENT (28 libraries); vm-vmanager-app `doctor --standards` GREEN (first real run of the enforced flow).
> **Audience:** the mgf-standard + mgf-common supervisor (and agents
> continuing this). Follows **DOC-06** (living priority tracker).
> **Why:** make "every mgf project's agent fully understands the federation
> end-to-end, then syncs *completely* (never partially)" a guarantee with
> ZERO assumptions — discoverable, communicable, and *verifiable*. This layer
> underpins every later item, so it is built first.

---

## §0 The problem (verified against code/packaging, not assumed)

1. **Gap A — contract + design not resolvable.** The `mgf-standard` wheel
   `force-include`s `docs/standards/`, `docs/recipes/`, and
   `MGF_LIBRARIES.json` only. **`FEDERATION.md` (the DOC-17 contract) and
   `docs/design/federation.md` are NOT shipped and have no seam** → an agent
   with only the package installed cannot read the contract/design via the CLI.
2. **Gap B (critical) — the corpus is behind an optional extra.** Since
   mgf-common 0.45.1, `mgf-standard` is the **`[standards]` extra**, not a
   runtime dep (a real fix: uv won't index-pin a *transitive* Codeberg dep).
   So plain `pip install mgf-common` resolves **nothing** of the corpus, and
   `mgf-common standards`/`sync-prompt` print an install error while `agents`
   **silently** omits the federation map. The orientation line said
   `pip install -U mgf-common` (no extra) → the resolve-don't-copy chain is
   broken by default.
3. **Soft prompt.** `federation-sync-prompt.md` *intends* full-read-before-act
   but has no mechanical coverage receipt and depends on the (degradable) CLI;
   nothing forces the agent to account for every MUST → partial sync is
   invisible. (Evidence: `vm-vmanager-app`'s `MGF_ADOPTION.md` /
   `MGF_STANDARDS_CONFORMANCE.md` are stale — cite mgf-common 0.38/0.42,
   standards v2.13, and the deleted `mgf-vm`.)

## §1 Locked decisions (2026-06-06)

| # | Decision |
|---|---|
| **D1** | **Standardize on `mgf-common[standards]` + loud degrade.** The extra is the canonical install everywhere (orientation line, AGENTS.md pointer, `new_project`, cookiecutter). Every project declares `mgf-common[standards]` (direct extra → `[tool.uv.sources]` index-pin applies). The four federation CLI cmds degrade **LOUDLY** (non-zero + `pip install 'mgf-common[standards]'`), never silently. |
| **D2** | **Ship the contract + design + add CLI seams.** `force-include` `FEDERATION.md` and `docs/design/` as wheel data; add `federation()` / `design_dir()` (+ list/read) seams; surface via the CLI so the *whole picture* is resolvable offline. |
| **D3** | **Enforced two-phase sync prompt.** Rewrite `federation-sync-prompt.md` to **Comprehend (no edits, emit a coverage map + read-receipt) → Conform (per-rule, recorded in the ledger) → Verify**. Keep mgf-common's `/sync` command body in lockstep. |
| **D4** | **Partial-sync gate.** Extend `mgf-common catch-up`/`doctor` to fail when `MGF_STANDARDS_CONFORMANCE.md` does not account for **every current MUST** in the corpus (rule-set ↔ ledger drift = defect). Turns partial sync into red CI. |

## §2 Confirmed mandatory documents (DOC-01/07/08/14/15/16/17)

- **Every project** (cornerstone / sibling / app): `README.md`, `LICENSE`,
  `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `FEEDBACK.md`, `AGENTS.md`,
  `STARTHERE.md`, `DEPS.md`, `FEDERATION.md` (pointer-stub except here) — **plus**
  a `docs/` dir, `docs/claude/CLAUDE.md`, and `MGF_STANDARDS_CONFORMANCE.md`.
- **Libraries also:** `PUBLIC_API.md` + `PUBLIC_API.json`.
- **Consumer apps also:** `MGF_ADOPTION.md`.

**Adoption vs conformance (why both):** `MGF_ADOPTION.md` (DOC-14, *apps only* —
ADP-04 carves out siblings) tracks **which libs you consume + version
currency**. `MGF_STANDARDS_CONFORMANCE.md` (DOC-15, *everyone*) is the **per-rule
ledger + L1/L2/L3 level**. Different questions: "am I current on my deps?" vs
"do I follow the rules, at what level?"

## §3 Work units (sequenced — later units depend on earlier)

| WU | Repo | Unit | Gate | Status |
|---|---|---|---|---|
| **WU1** | mgf-standard | D2 packaging: `force-include` `FEDERATION.md` + `docs/design/`; add `federation()` / `design_dir()` / `list_design` / `read_design` seams + tests; bump 0.1.10→0.1.11; publish to Codeberg | pytest + lint-imports + the 5 gates; wheel-ships-data smoke | ✅ **DONE** (PR #16, v0.1.11 published + REST 200 + consumer-resolved) |
| **WU2** | mgf-standard | D3 rewrite `federation-sync-prompt.md` → STEP 0 install `[standards]`+resolve / PHASE A Comprehend (read-receipt, no edits) / PHASE B Conform (per-rule ledger) / PHASE C Verify; route through the new contract/design seams; `/sync` lockstep note | recipe renders via seam; phase markers present | ✅ **DONE** (v0.1.12) |
| **WU3** | mgf-common | D1 loud degrade: `standards`/`sync-prompt` → non-zero + actionable `pip install 'mgf-common[standards]'`; `agents` loud stderr warning (no silent map omission) | CLI tests | ✅ **DONE** (mgf-common PR #5, v0.46.0) |
| **WU4** | mgf-common | D1 install posture: `agents` briefing + `STARTHERE` (lockstep) + `new_project` → `mgf-common[standards]`; new `.claude/commands/sync.md` thin `/sync`→`sync-prompt` delegator | test_agents lockstep | ✅ **DONE** (v0.46.0) — cookiecutter part folded into WU7 (it lives here) |
| **WU5** | mgf-common | D2 surface: `mgf-common federation` (contract) + `design` (papers) over the new seams | CLI tests | ✅ **DONE** (v0.46.0) |
| **WU6** | mgf-common | D4 partial-sync gate in `doctor --standards`: `_check_conformance_ledger_complete` parses the README Index-of-MUSTs (216→217); fails non-zero on any unaccounted MUST | gate test on a partial-ledger fixture | ✅ **DONE** (v0.46.0; verified end-to-end from the published artifacts) |
| **WU7** | mgf-standard | Encode as **binding rules**: **AG-16** (corpus-resolvable / `[standards]` install) + **CFM-03** completeness amendment (every MUST, doctor-enforced) + `FEDERATION.md` §2/§4/header + DOC-18 ripple (Index of MUSTs, What's new v2.19, AGENTS Propagation) | DOC-18 ripple; gates | ✅ **DONE** (v0.1.13) |
| **WU8** | consumers | First real run of the new flow on `vm-vmanager-app`: complete `MGF_STANDARDS_CONFORMANCE.md` to all 217 MUSTs, refresh `MGF_ADOPTION.md`, walk its mgf-common pin `<0.47`. Surfaced + fixed a real gap: `doctor --standards` couldn't detect shape when dist-name≠package (`vm-vmanager-cli`→`vmanager`) → mgf-common **0.46.1** `_find_package_root` fallback | `doctor --standards` GREEN (6/6) | ✅ **DONE** (vm-vmanager-app 0.3.1; mgf-common 0.46.1; registry refresh 0.1.14) |

**Ordering:** WU1 → (WU2 ∥ WU3 ∥ WU4) → WU5 → WU6 → WU7 → WU8. WU1 ships the
seams/data the mgf-common units consume; WU7 makes the whole thing binding;
WU8 proves it end-to-end.

## §4 The end-state guarantee

After this layer: a fresh agent in any mgf repo runs **one** command
(`pip install -U 'mgf-common[standards]'` then `mgf-common sync-prompt`),
gets a prompt that **forces** it to resolve and read the *entire* picture
(standards + recipes + contract + design + registry, all offline-resolvable),
**comprehend before editing**, conform **per-rule**, and **verify** — with
`catch-up` failing the build on any partial sync. No silent degrade, no
unreadable contract, no unaccounted rule.
