# Federation-docs extraction — operation tracker

> **Status:** ✅ COMPLETE — 2026-06-01. `mgf-standard 0.1.1` + `mgf-common 0.44.1` shipped to PyPI + merged to main; registry regenerated (REL-13). Remaining federation work (behind consumers, hands-off `mgf-vm*`, `mgf-hrb` first-publish) is out of this operation's scope.
> **Audience:** the mgf-common/mgf-standard supervisor (+ AI agents
> continuing this work).
> **What this is:** the single living record of the operation that extracted
> the Magogi Foundation's standards + federation-level artifacts out of
> `mgf-common` into this repo (`mgf-standard`). It captures the **charter**
> (what belongs here), a **classification matrix** of every candidate
> artifact, the **work units** with status, what's **done**, and what's
> **deferred / out of scope**. Follows **DOC-06** (living priority tracker).

---

## §0 Charter — what `mgf-standard` is for

`mgf-standard` is the federation's **source of truth for everything
federation-level** — NOT only the standards prose. It is the home for any
artifact whose audience is *the whole federation* rather than one library:

| Kind | Examples |
|---|---|
| **Standards** | the `docs/standards/` corpus (the AP/CF/EH/LG/SC/TS/DP/DOC/… rules) |
| **Contract** | `FEDERATION.md` (the federation contract) |
| **Registry** | `MGF_LIBRARIES.md` + `scripts/gen_mgf_libraries.py` (REL-13) |
| **Foundation design** | `docs/design/federation.md` (the federation-pattern paper) |
| **Templates** | the per-repo doc templates (DEPS/FEEDBACK/adoption/conformance/pointer-stub/PR-test-plan) **and** the new-project **cookiecutter** scaffold |
| **Process recipes** | cohort-release, sibling-rename, the `/sync` prompt, library↔app split, test-supervisor adoption |
| **Reference evidence** | `docs/reference-consumers/` (how real consumers exercise the standards) |
| **Federation tooling** | the registry generator (here); candidate: PR-conformance + consumer-adoption audits |
| **Federation examples** | *(none yet)* — reference examples demonstrating the federation **patterns** (vs `mgf-common`'s API usage) would live here |

**The test for "does it belong here?"** — *would a second project ever need
it as-is, independent of `mgf-common`'s implementation?* If yes → here. If it
documents/uses `mgf.common.*` specifically (API how-tos, the `mgf-common` CLI,
its own internals/history/changelog) → it stays in `mgf-common`.

`mgf-common` keeps: its public-API docs (`docs/reference/`), its API-usage
recipes + `examples/`, its own design papers (`architecture`, `multi_tenancy`,
`extraction_history`), its trackers/cutover/audience pages, its self-audit
(`STANDARDS_COMPLIANCE.md`), and the **agent-briefing constant** (a `mgf-common`
CLI string, pinned to its `STARTHERE.md`).

---

## §1 Work units (priority order)

| ID | Unit | Priority | Status |
|---|---|---|---|
| F2 | Move remaining **foundation docs** (reference-consumers + 3 doc templates + 2 process recipes) | 🔴 high | ✅ moved (9 files) |
| F3 | Move the **cookiecutter scaffold**; decide the 2 audit scripts | 🟡 med | ✅ done — cookiecutter + `audit_pr_conformance.py` moved; `audit_consumers.py` stays (mgf-common API-usage audit) |
| F4 | Repair **cross-repo links** inside the moved corpus (DOC-09) | 🔴 high | ✅ done — 37 links repaired by agent + 6 it missed (TESTING.md ×5 → mgf-common Codeberg URLs, GUI_CONSUMERS bare `FEEDBACK.md` → `../../`); independent check clean. 3 flags intentionally left: DOC-12 syntax examples (`...`, `../reference/foo.md`) + machine-level `claude_common.md` (`~/.claude/`) — all pre-existing, none extraction-caused |
| F5 | Flip **agent-briefing §7** routing (lockstep) + mop residual `docs/standards/` mentions | 🟡 med | ✅ done — briefing lockstep flip (`_agents.py` ↔ `STARTHERE.md`, 14/14 test_agents) + 22-file mgf-common reference sweep |
| F6 | Finish `mgf-standard` **conformance audit** + validate CI + verify gates + ship `0.1.1` | 🟡 med | ✅ done — shipped `mgf-standard 0.1.1` + `mgf-common 0.44.1` to PyPI (both merged to main ff-only, tagged, smoke-verified: 0.44.1 transitively resolves 0.1.1, 23 standards reachable); registry regenerated (REL-13, `6573f9b`). Per-rule conformance flesh-out **deferred** (non-gating; family-summary + TS-23 CFM-04 carve-out documented) |
| — | Deferred (historical links, cosmetic comments) — see §4 | ⚪ low | ⏸ deferred |

---

## §2 Classification matrix

✅ already in `mgf-standard` · ➡️ to move (this pass) · 🏠 stays in `mgf-common` · ❓ decide

| Artifact (in `mgf-common` unless noted) | Federation-level? | Verdict |
|---|---|---|
| `docs/standards/` corpus (26 files) | yes | ✅ moved |
| `FEDERATION.md` | yes | ✅ moved (canonical here) |
| `MGF_LIBRARIES.md` + `scripts/gen_mgf_libraries.py` (+ test) | yes | ✅ moved |
| `docs/design/federation.md` | yes | ✅ moved |
| recipes: `sibling_rename`, `cohort-release-wave`, `federation-sync-prompt` | yes | ✅ moved |
| templates: `federation-pointer-stub`, `mgf-adoption-md`, `mgf-standards-conformance-md` | yes | ✅ moved |
| **`docs/reference-consumers/`** (inthewords, PlasmaMapper, VManager, README) | yes — standards' consumer evidence | ➡️ **F2** |
| **`docs/recipes/deps-md-template.md`** | yes — every repo ships `DEPS.md` | ➡️ **F2** |
| **`docs/recipes/feedback-md-template.md`** | yes — every repo ships `FEEDBACK.md` | ➡️ **F2** |
| **`docs/recipes/pr-standard-test-plan-template.md`** | yes — federation PR process | ➡️ **F2** |
| **`docs/recipes/library-app-separation.md`** | yes — federation library↔app pattern (PRESENTATION_LAYER) | ➡️ **F2** |
| **`docs/recipes/test-supervisor-adoption.md`** | yes — adopt the federation test runner | ➡️ **F2** |
| **`templates/cookiecutter-mgf-project/`** | yes — new-mgf-project scaffold (CLI does NOT reference it) | ➡️ **F3** |
| `scripts/audit_pr_conformance.py` | ❓ audits a PR vs the standards | ❓ **F3** (assess: federation vs mgf-common-only) |
| `tools/audit_consumers.py` | ❓ scans consumers for adoption | ❓ **F3** (assess) |
| recipes: `cli`, `testing`, `new_project`, `providers`, `observability_shim`, `process-management`, `versioned`, `web-sse`, `scan-deps`, `script`, `notebook`, `multi_tenant_settings`, `framework-owned-logging`, `cloud-native-logging`, `local-ci-pipeline` | no — `mgf.common.*` how-tos | 🏠 stays |
| `docs/reference/`, `docs/audience/`, `docs/cutover/`, `docs/release/`, `docs/ops/`, `docs/internal/`, `docs/testing/`, `docs/inprogress/` | no — mgf-common docs/trackers | 🏠 stays |
| `docs/design/architecture.md`, `multi_tenancy.md`, `extraction_history.md` | no — mgf-common internals/history | 🏠 stays |
| `docs/STANDARDS_COMPLIANCE.md` | no — mgf-common's OWN self-audit | 🏠 stays |
| `examples/` (01..06) | no — `mgf.common.*` API demos | 🏠 stays |
| `scripts/ci-local.sh`, `check_sbom.py`; `tools/generate_public_api_json.py`, `gen_log_record_schema.py`, `docs_explorer/` | no — mgf-common dev/CI tooling | 🏠 stays |
| the **agent briefing** (`_agents.py::AGENTS_BRIEFING` ↔ `STARTHERE.md`) | content is federation-wide, but it's a **CLI constant** | 🏠 stays (delivery seam); routing fixed in **F5** |

---

## §3 Work units (detail)

### F2 — Move remaining foundation docs
- **First**: check CLI coupling — `src/mgf/common/cli/_test.py` + `_doctor.py`
  reference some of these (verify none is *read at runtime*; printed-URL refs
  just need updating, like `_init_project.py` did at extraction).
- Move (copy → `git rm`): `docs/reference-consumers/` → `mgf-standard/docs/reference-consumers/`;
  recipes `deps-md-template.md`, `feedback-md-template.md`,
  `pr-standard-test-plan-template.md`, `library-app-separation.md`,
  `test-supervisor-adoption.md` → `mgf-standard/docs/recipes/`.
- Update `mgf-common`: `docs/recipes/README.md` index + any CLI printed URLs +
  `docs/reference-consumers/README.md` consumers (leave a one-line pointer
  where a reader would expect them).
- Update `mgf-standard/docs/recipes/README.md` to list the newly-arrived
  templates/recipes.

### F3 — cookiecutter scaffold + audit tooling
- Move `templates/cookiecutter-mgf-project/` → `mgf-standard/templates/`
  (the CLI does not reference it; manual `cookiecutter` usage). Update any
  doc that points at `mgf-common/templates/`.
- **Decide** `scripts/audit_pr_conformance.py` + `tools/audit_consumers.py`:
  read each; if it audits the *federation* against the standards → move
  (sits with `gen_mgf_libraries.py`); if it's mgf-common-PR/mgf-common-consumer
  specific → keep + note here.

### F4 — Repair cross-repo links in the moved corpus (DOC-09)
The moved `docs/standards/*` link to ~25 docs via `../` that don't all live
here now. Rule:
- target **moved here** (e.g. `../reference-consumers/`, the moved templates) →
  link stays local (resolves after F2).
- target **stays in mgf-common** (`../reference/EVENTS.md`, `../release/ci.md`,
  `../inprogress/*` trackers, `../cutover/archive/*`, `../design/extraction_history.md`,
  non-moved recipes like `../recipes/cloud-native-logging.md`) → rewrite to the
  `mgf-common` Codeberg URL (the standards legitimately *cite* the reference
  implementation's docs cross-repo).
- placeholders (`../reference/foo.md` in DOCUMENTATION.md examples) → leave (illustrative).
- Pin: after F4, `grep -rE '\]\(\.\./' docs/standards` should resolve to a
  local file or a full URL — no dangling relative paths.

### F5 — Briefing routing + residual mentions
- `mgf-common`: edit `_agents.py::AGENTS_BRIEFING` §7 so **standards / contract /
  registry** feedback routes to `mgf-standard/FEEDBACK.md` (matching
  `FEDERATION.md §7`), with cross-cutting/library issues → `mgf-common`. **Edit
  `STARTHERE.md` identically** (the `test_agents.py` pin requires verbatim match).
- Mop residual `docs/standards/` references the focused sweep missed:
  `docs/README.md` (same-dir `](standards/)`), `audience/ai-agents.md`,
  `release/README.md`, a few `reference/*` + `inprogress/*` (prose + links).

### F6 — Conformance + verify + ship
- Flesh out `mgf-standard/docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`
  per-rule (currently summary + the TS-23 carve-out).
- Verify gates green: `mgf-standard` (ruff/format/mypy/lint-imports/pytest);
  `mgf-common` (ruff/mypy/lint-imports/2021 pytest + the `test_agents` lockstep).
- Confirm `.woodpecker.yml` validity (it has never run on Codeberg yet).
- If the corrected corpus should be on PyPI, cut **`mgf-standard 0.1.1`**
  (the wheel ships `docs/standards/` as data, so corpus edits change the wheel).
- Show diffs; push the `finish-extraction` branches; PR/merge per review.

---

## §4 Done (prior phases — for context)

- **Extraction + rewire** (2026-06-01): corpus + contract + registry + design
  paper + 6 process recipes moved here; `mgf-common` depends on
  `mgf-standard` and surfaces the corpus via `mgf-common standards`/`agents`.
- **Published**: `mgf-standard 0.1.0`, `mgf-common 0.44.0`, and 12 active
  non-vm siblings adopting 0.44 (tele-core/teltonika 0.1.3, apiprobe 0.5.4,
  fastapi 0.6.5, http 0.4.5, sqlalchemy 0.5.3, auth 0.1.3, alembic 0.4.5,
  django 0.4.4, livepush 0.1.3, logship 0.1.1, test-supervisor 0.1.9).
- **Registry regenerated** (`d51e858`); REL-13 gate RED only on the hands-off
  `mgf-vm*` family.

## §5 Deferred / out of scope

- **Deferred (historical/cosmetic):** old `../standards/` links in
  `docs/cutover/` + `docs/archive/` (21 files); rule-citation comments in
  `.gitleaks.toml`/`.importlinter`/`.woodpecker.yml`/perf-test docstrings.
- **NOT this operation (federation propagation):** consumer **version**
  catch-up (hrb-app, inthewords, iosRecovery, PlasmaMapper are behind several
  minors — a separate per-repo upgrade); the **`mgf-vm*` family** (HANDS-OFF —
  retirement); **`mgf-hrb`** first-publish (never on PyPI + stale Zig broker
  binary). NOTE: the review pass (§6) DID repoint dead standards *links* in the
  reachable consumers (inthewords, hrb-app); version catch-up is what remains.
- **`mgf-common` first-publish / agent-briefing ownership:** the briefing stays
  a `mgf-common` CLI constant by design (F5 fixes only its *routing* content).

---

## §6 Review pass — close-out (2026-06-01)

Adversarial review after the two waves; fixed the real gaps they left:
- **Core repos:** the corpus link-repair had skipped the *non-corpus* moved docs
  (reference-consumers / recipes / `design/federation.md`) — ~16 broken `../`
  links repaired + `VManager.md` → `vm-vmanager-app.md` (`e8d27dd`). `mgf-common`
  `docs/tutorial.md` cookiecutter pointer + `.woodpecker.yml` header comment +
  a **stale `uv.lock`** (bumped pyproject to 0.44.1 but lock still said 0.44.0 —
  a `--locked` CI step would fail) fixed (`1f8b851`; lock now 0.44.1 / 0.1.1).
- **Federation-wide standards-link rot:** every sibling/consumer doc citing a
  rule linked the now-dead `mgf-common/docs/standards/` URL. Repointed →
  `mgf-standard` across **all 13 non-vm siblings + inthewords + hrb-app**
  (docs-only, committed + pushed, residual = 0 verified).
- **PlasmaMapper** (22 files, `magogi-products` org) — SWEPT on follow-up
  (`2790e58`; cross-org push works; its pending `uv.lock` commit pushed too).
- **Residual (NOT swept):** iosRecovery (9 files — local-only, no git remote,
  nothing to push to); `vm-vmanager-app` + `mgf-vm*` (hands-off). Standards-link
  rot is now fixed across the entire reachable federation (2 core + 13 siblings
  + 3 consumers).
- **Verified clean:** both core repos gate-green (mgf-common 2021 pytest);
  mgf-common wheel ships only resolver code (`_standards.py`), no corpus leak;
  `.woodpecker` `docs/standards` mentions were comments, not broken CI steps.

---

## §7 Federation state at session handoff (2026-06-01)

Extraction closed; this records the **post-extraction state** so a session
continuing from `mgf-standard` has the full picture (memory is per-project —
this in-repo note is the cross-project handoff).

**Federation-awareness mechanism — SHIPPED (the principle: *resolve, don't copy*):**
- `mgf-standard 0.1.2` — registry shipped as wheel data (`MGF_LIBRARIES.json`
  force-included) + public seam **`mgf.standard.libraries()`** (roster +
  dependency graph). `gen_mgf_libraries.py` emits the JSON; REL-13 `--check` guards it.
- `mgf-common 0.44.2` — `mgf-common agents` appends a live "Federation map / you
  are here" block from `libraries()`.
- `mgf-common 0.44.3` — `mgf-common catch-up` adds a "Federation position" check
  (pin-currency vs the roster). Dep floor raised to `mgf-standard>=0.1.2`.
- Chain: **AGENTS.md pointer → `mgf-common agents` → resolve** (briefing +
  standards + map). AGENTS.md synced to the canonical pointer federation-wide
  (16 repos + the cookiecutter scaffold); `mgf-standard` keeps its
  leaf-variant (mgf-common isn't a dependency here).

**Live on PyPI:** mgf-standard **0.1.2**, mgf-common **0.44.3**.

**vm-* pin-walk — DONE (verified):** the 6 active `mgf-vm-*` walked their
`mgf-common` caps to `<0.45` on main (verified ZERO test-delta on 0.44.3).
**REL-13 is RED on `mgf-vm` ALONE** — being DELETED; it drops from the registry
when removed → REL-13 then fully GREEN. (forensics/interchange feature branches
still carry the old pin; their main is walked — they rebase onto it.)

**Open / next:**
1. ~~**`mgf-vm` deletion** (user's action) → regen registry → REL-13 fully GREEN.~~
   **DONE (2026-06):** the vm-vmanager-app team retired + deleted `mgf-vm`; the
   umbrella drain is complete (forensics 0.1.4 / interchange 0.2.0 /
   vm-vmanager-app 0.3.0 / vm-vmanager-agent now depend on `mgf-vm-core>=0.1.9`,
   not the umbrella). Registry is GREEN/CURRENT at cornerstone **mgf-common
   0.45.2**; no bare `mgf-vm` in the roster. The generator keeps a defensive
   `_EXCLUDED_REPOS` guard. See [[codeberg-package-registry]].
2. **Freshness live-check** (optional): wire `catch-up` to also check the latest
   registry on PyPI / `mgf-standard@main` beyond the installed snapshot
   (the snapshot-vs-freshness split). `libraries()` is ready for it.
3. **Consumer version catch-up** — inthewords / PlasmaMapper / iosRecovery /
   hrb-app are behind several `mgf-common` minors (separate per-repo upgrade).
4. **Still hands-off** (vm-team territory): vm-* CI greening + any vm-* publish.

**Sharing the standards with an external agent:** regenerable bundle =
`FEDERATION.md` + `docs/design/federation.md` + `MGF_LIBRARIES.md` +
`docs/standards/*` (29 files). External agents can't run `mgf-common agents`
(no install) → hand them the docs, not the pointer.
