# mgf-standard

> **The Magogi Foundation's engineering-standards corpus, federation
> contract, and library registry — the single source of truth for the
> `mgf-*` federation.**
>
> **Conformance:** L2 per its own [`docs/standards/`](docs/standards/)
> (one documented CFM-04 carve-out — see
> [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md)).
> **Audience:** every Magogi project (humans + AI agents). If you depend
> on `mgf-common` or any `mgf-*` sibling, the rules you follow live here.

---

## What this repo is

`mgf-standard` is the **standards leaf** of the Magogi Foundation. It
carries, as the canonical version-controlled source of truth:

- **The engineering-standards corpus** ([`docs/standards/`](docs/standards/))
  — the AP / CF / EH / LG / SC / TS / DP / DOC / … rule families every
  federation project conforms to, with a master index + per-topic Rules
  boxes.
- **The federation contract** ([`FEDERATION.md`](FEDERATION.md)) — what you
  owe by depending on the federation, and what it gives you. Every other
  repo (including the `mgf-common` cornerstone) ships a *pointer stub* to
  this copy (DOC-17).
- **The library registry** ([`MGF_LIBRARIES.md`](MGF_LIBRARIES.md)) — the
  always-current map of every federation library, kept honest by the
  REL-13 consistency gate ([`scripts/gen_mgf_libraries.py`](scripts/gen_mgf_libraries.py)).
- **Foundation-level design + process docs** — the federation-pattern
  architecture paper ([`docs/design/federation.md`](docs/design/federation.md))
  and the federation-operations recipes ([`docs/recipes/`](docs/recipes/):
  cohort releases, sibling renames, the sync prompt, and the pointer-stub /
  adoption / conformance templates).

## Why it's a separate repo (and a tiny package)

The standards used to live inside `mgf-common`. They were extracted so the
**rules version independently of the implementation**: `mgf-common` is the
reference *implementation* + the CLI front door; `mgf-standard` is the
*specification*. `mgf-common` now depends on `mgf-standard`.

The repo ships a **tiny, zero-dependency data package**, `mgf.standard`,
that carries the corpus as wheel data and exposes a typed resolver:

```python
import mgf.standard as std

std.standards_dir()           # Path to the corpus directory
std.list_standards()          # ['API_DESIGN', 'CONFIGURATION', 'LOGGING', ...]
std.read_standard("LOGGING")  # the full LOGGING.md text

std.recipes_dir()             # Path to the federation-operations recipes
std.list_recipes()            # ['cohort-release-wave', 'federation-sync-prompt', ...]
std.read_recipe("federation-sync-prompt")  # the /sync prompt text

std.libraries()               # the federation registry (roster + dep graph)
```

It depends on **nothing** in the `mgf.*` namespace — it is the federation
*leaf-of-leaves*, sitting below `mgf-common` in the dependency graph
(`mgf-standard` ← `mgf-common` ← every sibling ← every consumer), so
the runtime graph stays acyclic.

## How to read the standards

You almost never read this repo directly — you read it **through
`mgf-common`'s CLI**, which is installed in every federation project:

```sh
mgf-fed standards            # list all topics
mgf-fed standards LOGGING    # print one
mgf-fed agents               # the canonical AI-agent briefing
```

Those commands resolve this package's corpus via
`mgf.standard.standards_dir()`. Reading the rules never requires a
checkout of this repo.

## Repo layout

| Path | What |
|---|---|
| [`FEDERATION.md`](FEDERATION.md) | The federation contract (canonical; others link here) |
| [`MGF_LIBRARIES.md`](MGF_LIBRARIES.md) | The library registry (generated; REL-13 gate) |
| [`docs/standards/`](docs/standards/) | The engineering-standards corpus (the rules) |
| [`docs/design/federation.md`](docs/design/federation.md) | The federation-pattern architecture paper |
| [`docs/recipes/`](docs/recipes/) | Federation-operations recipes + templates |
| [`scripts/gen_mgf_libraries.py`](scripts/gen_mgf_libraries.py) | Registry generator + consistency gate |
| `src/mgf/standard/` | The tiny resolver package (corpus shipped as data) |

## Federation links

- **Cornerstone / CLI:** [`mgf-common`](https://codeberg.org/magogi-admin/mgf-common)
- **Contract:** [`FEDERATION.md`](FEDERATION.md) · **Registry:** [`MGF_LIBRARIES.md`](MGF_LIBRARIES.md)
- **Feedback** (standards proposals + cross-cutting rules): [`FEEDBACK.md`](FEEDBACK.md)
- **Onboarding:** [`STARTHERE.md`](STARTHERE.md) · **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)

## License

MIT — see [`LICENSE`](LICENSE).
