Metadata-Version: 2.4
Name: mgf-doc-standard
Version: 0.1.2
Summary: The Magogi Foundation engineering-standards corpus, federation contract, and library registry — the source of truth for the mgf-* federation
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-doc-standard
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-doc-standard/issues
Author: Bassam Alsanie, mgf-doc-standard contributors
License: MIT
License-File: LICENSE
Keywords: documentation,engineering-standards,federation,governance,standards
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5.0; extra == 'dev'
Requires-Dist: pytest<10,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# mgf-doc-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-doc-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-doc-standard` is the
*specification*. `mgf-common` now depends on `mgf-doc-standard`.

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

```python
import mgf.doc_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
```

It depends on **nothing** in the `mgf.*` namespace — it is the federation
*leaf-of-leaves*, sitting below `mgf-common` in the dependency graph
(`mgf-doc-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-common standards            # list all topics
mgf-common standards LOGGING    # print one
mgf-common agents               # the canonical AI-agent briefing
```

Those commands resolve this package's corpus via
`mgf.doc_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/doc_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).
