# Documentation

> **Conformance:** L1 / L2 / L3 (see `README.md`)
> **Audience:** Human engineers AND AI coding agents.
> **Propagation (DOC-18):** when a DOC-* rule changes, also update → README *Index of MUSTs* + `CHANGELOG.md` + `FEDERATION.md` (if the contract shifts) + the `mgf-fed standards` CLI + this doc's own §10.4 matrix. This is the home of the propagation rule itself (§10.4).

> **Scope.** Cross-project documentation standard. What docs every
> project ships, what each doc is FOR (and what it explicitly is
> not), the hierarchy that scales from a 200-line script to an
> 80-doc federation library, the formats that don't rot, and the
> drift mechanics that keep code and docs honest.
>
> Born from the realisation that **every consumer was reinventing
> the docs hierarchy from scratch** — every `CLAUDE.md`, every
> `CHANGELOG.md`, every priority tracker — and that AI agents
> entering a fresh project had to reverse-engineer the structure
> before they could contribute. Codifying the shape ends the
> reinvention.

---

## Rules box (read this first)

| ID | Rule |
|---|---|
| <a id="DOC-01"></a>**DOC-01** | **Every project MUST ship the root-level docs applicable to its shape** (see §2.0 for the cornerstone / sibling / application classification and the per-shape applicability matrix). The **uniform ten-doc baseline** — `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md` (per **SC-12**), `FEEDBACK.md` (per **DOC-13** / **FB-01..FB-04**), `AGENTS.md` (per **DOC-07**), `STARTHERE.md`, `DEPS.md` (per **DOC-16**), and `FEDERATION.md` (per **DOC-17**) — **plus a `docs/` directory** at the repo root, is MUST for **every project** (cornerstone, sibling, AND application). The canonical reference is the §2.0.1 applicability matrix (mirrored by [`FEDERATION.md`](../../FEDERATION.md) §3); only `PUBLIC_API.md`/`.json` stay library-only, and `FEDERATION.md` is canonical only in `mgf-standard` (a pointer stub everywhere else, per DOC-17). Missing any baseline doc, or shipping fewer because of project shape, is a defect. <br><br>The net rule above is current; the dated amendment history (FEEDBACK.md → universal-MUST; the misfile-into-cornerstone case study, mgf-common PAPER-36..42) lives in `CHANGELOG.md` (v2.8) + DOC-13 / FB-01..FB-04.<br><br>**v2.11 amendment** (2026-05-28 — maintainer directive): the universal-MUST root-doc set is expanded to a single uniform baseline for **every project** (cornerstone, sibling, AND application). Required at repo root: `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `FEEDBACK.md`, `SECURITY.md`, `AGENTS.md`, `FEDERATION.md`, `STARTHERE.md`, `DEPS.md` — **plus a `docs/` directory** at the repo root. These are no longer shape-dependent or inheritance-escapable. `PUBLIC_API.md`/`.json` remain library-only (applications have no public surface). Anti-duplication carve-outs preserve DOC-17 / DOC-02 / §2.0.4: every project except the standards owner (`mgf-standard`) ships `FEDERATION.md` as a **pointer stub** to `mgf-standard`'s canonical contract (NOT a copy) — including the `mgf-common` cornerstone.<br><br>**v2.12 amendment** (2026-05-28 — maintainer directive): `DEPS.md` replaces `USERS.md` in the required set. `DEPS.md` is the **bidirectional dependency manifest** — §1 what this project depends on (federation siblings + third-party), §2 who depends on this project (the former `USERS.md` "who depends on me" roster). It subsumes `USERS.md`; the old `USERS.md` is removed from the requirement and may be deleted. A leaf application fills §1 and leaves §2 empty; the file MUST still exist. |
| <a id="DOC-02"></a>**DOC-02** | **Every project MUST organise non-root docs into the six-bucket hierarchy applicable to its shape** (see §2.0). The buckets are: `docs/standards/` durable rules, `docs/reference/` component guides, `docs/inprogress/` living trackers, `docs/claude/` AI lookup, `docs/cutover/` per-release breaking-change guides, `docs/recipes/` task-shaped how-tos. A non-cornerstone project's `docs/standards/` MAY be a pointer-only README that links to the cornerstone (see §2.0.4); it MUST NOT duplicate cornerstone content. Additional buckets (`docs/audience/`, `docs/design/`, `docs/internal/`, `docs/ops/`, `docs/reference-consumers/`, application-specific buckets like `docs/runbooks/` or `docs/adrs/`) are allowed where genuinely needed; each carries a one-paragraph charter in its own `README.md`. |
| <a id="DOC-03"></a>**DOC-03** | **Every long-lived bucket MUST have its own `README.md`** stating the charter ("what goes here, what doesn't, when to add / remove an entry") and a one-line description of each file. The bucket README is the gate against creep. |
| <a id="DOC-04"></a>**DOC-04** | **Every public-API change MUST land with a `CHANGELOG.md` entry IN THE SAME COMMIT.** Format follows [Keep a Changelog](https://keepachangelog.com/). Every entry that breaks a documented surface MUST link a `docs/cutover/v<X.Y.Z>.md` migration guide and the corresponding `FEEDBACK.md` entry (where applicable). |
| <a id="DOC-05"></a>**DOC-05** | **Every breaking change (MAJOR, or MINOR within `0.x` per AP-03) MUST ship a `docs/cutover/v<X.Y.Z>.md`** guide. The guide MUST: (a) name every removed/renamed/reshaped name with its replacement, (b) state whether the codemod handles it (yes / no / partial — and which manual step is left), (c) provide a copy-pasteable migration block per shape, (d) name the corresponding FEEDBACK entry. |
| <a id="DOC-06"></a>**DOC-06** | **Living priority trackers MUST follow the standard shape** (priority table → first wave → §4 work units → §5 closed items). Every work unit MUST carry **verified `file:line` evidence** AND a **falsifiable "concrete output"** that can be checked off. Items that fail those gates ("we should look at X someday") go in `FEEDBACK.md` (consumer-facing) or `strategic_review.md` (long-horizon planning), not in a priority tracker. See §3. |
| <a id="DOC-07"></a>**DOC-07** | **Every project MUST ship a `docs/claude/CLAUDE.md`** in the dense-lookup format (§4). It is the AI-agent-specific entry point — facts, file:line citations, pre-approvals — NOT human prose. A project that wants AI agents to be productive MUST ship this. |
| <a id="DOC-08"></a>**DOC-08** | **`PUBLIC_API.md` MUST track `__all__`** (rule **AP-10**). The companion **`PUBLIC_API.json`** (machine-readable) MUST be generated from `__all__` at every release and pinned in CI against `PUBLIC_API.md`. Two pins — one for human-doc drift, one for machine-companion drift. |
| <a id="DOC-09"></a>**DOC-09** | **Docs that name code (file paths, line numbers, function names, env-var names) MUST be drift-detected.** Either (a) a CI lint that verifies the referenced name exists (the canonical shape for `PUBLIC_API.md`), or (b) a back-reference in the named code pointing at the docs path — either as a `See:` line inside the module/class docstring OR a `# See: docs/reference/XX.md` hash-comment. Both directions are stronger than either alone.<br><br>**Behavioral verification (v2.16, SHOULD).** Name-existence is the floor, not the ceiling: a doc may cite a symbol that *exists* and still describe behavior the code no longer has. So a **behavioral claim in a consumer-facing doc** (a `reference/` guide, a recipe, a `--help`/usage snippet, a stated default/return/raise) **SHOULD be verified against the code**, not just the name. The bound outcome is **the described behavior matches the code at a recorded version** — drift is catchable, not a maintainer's memory. The **canonical reference path** is an **executable example pinned in CI** at the strongest available form: a **doctest** in the cited module's docstring, or a **`smoke`-marked example test** (mgf-common's shape — the `smoke` tier-0 marker + the `tests/unit/test_examples.py` harness that drives examples as subprocesses). A claim that is **not auto-checkable** (a narrative invariant, an external-service behavior) is conformant with a recorded **`doc_claim:` / `code_truth:` + `verified-against: <tag-or-SHA>` note** at the claim — an equivalent that meets the outcome (recorded per [`non-adoption-is-valid`](./principles/non-adoption-is-valid.md), §14.1). **State which regime applies:** a doc that **tracks HEAD** (e.g. `PUBLIC_API.md`, per REL-03 — MAY be ahead of PyPI) verifies **same-commit against HEAD** at adopt-time; a doc **reviewed against a release** verifies **against a pinned tag/SHA** at review-time and records that tag in the note. Mind the REL-03 tension: HEAD-tracking docs MUST NOT pin a behavioral example to a *published* tag (it would lag the surface they mirror) — they verify against the commit they ship in. |
| <a id="DOC-10"></a>**DOC-10** | **`FEEDBACK.md` is the consumer-facing flow; `docs/inprogress/*.md` is internal posture.** A consumer's signal lands in FEEDBACK with one of four severities (🔴 / 🟡 / 🟢 / 💭) and progresses through the OPEN → ACCEPTED → SCHEDULED → SHIPPED lifecycle. The trackers in `docs/inprogress/` are the maintainer's internal hygiene queue, NOT the consumer's. Don't conflate. |
| <a id="DOC-11"></a>**DOC-11** | **`docs/inprogress/` is a workspace, not a graveyard.** A tracker SHOULD be moved to `docs/archive/<year>/` once its scope is complete (all items closed OR the rest formally deferred). A tracker that has sat fully-closed for one release cycle without movement is a maintenance signal — review and archive. |
| <a id="DOC-12"></a>**DOC-12** | **Docs MUST be navigable by AI agents.** Every cross-reference MUST be a relative link (`../reference/foo.md` not `https://...`). File paths in prose MUST use the form `src/<app>/path/to/file.py:LINE` so an agent can jump directly. Headings MUST be hierarchical (`## §N. Title`) so the agent's table-of-contents grep works. |
| <a id="DOC-13"></a>**DOC-13** (v2.8) | **`FEEDBACK.md` MUST be repo-scoped.** Sibling-specific issues (touching one library's public surface) live in the sibling's own `FEEDBACK.md`. Federation-wide issues (cross-sibling patterns, standards proposals) live in [`mgf-common/FEEDBACK.md`](../../FEEDBACK.md). A paper filed at the wrong target gets MOVED — the original location keeps a redirect stub with `Status: MOVED` and a link to the new home. Cross-references in either direction encouraged. See **FB-01..FB-04** for the discipline rules. |
| <a id="DOC-14"></a>**DOC-14** (v2.8) | **Every project that depends on mgf-common (or any federation sibling) MUST maintain an `MGF_ADOPTION.md` adoption tracker** at `docs/inprogress/MGF_ADOPTION.md` (recommended) or `docs/MGF_ADOPTION.md` (alternate). The README MUST link to it. The tracker is a living document — flips as pins bump, FEEDBACK papers close, phases progress. See **ADP-01..ADP-04** for the section + cadence rules. Template: [`docs/recipes/mgf-adoption-md-template.md`](../recipes/mgf-adoption-md-template.md). Reference shapes: [TelePlasma](https://codeberg.org/magogi-admin/TelePlasma/src/branch/main/docs/inprogress/MGF_ADOPTION.md) + [inthewords](https://codeberg.org/magogi-admin/inthewords/src/branch/main/docs/MGF_COMMON_ADOPTION.md). **ADP-04 carve-out:** federation siblings do NOT need this tracker — their adoption relationship to mgf-common is documented in [federation_roadmap.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/federation_roadmap.md) + each sibling's own CHANGELOG. |
| <a id="DOC-15"></a>**DOC-15** (v2.8) | **Every project that adopts mgf-common's standards MUST maintain an `MGF_STANDARDS_CONFORMANCE.md` conformance tracker** at `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`. This applies to BOTH consumer applications and federation siblings — both are held to the standards corpus. The tracker declares the project's **conformance level** (L1 / L2 / L3 — see [§CFM-02 below](#cfm-conformance-tracker-discipline-v28) for definitions) in the same place as the README. Per-rule status MUST use the markers ✅ / 🚫 / ⏳ / N/A. Decline-with-rationale (🚫) MUST carry a paragraph per [principles/non-adoption-is-valid.md](./principles/non-adoption-is-valid.md) (CFM-04). See **CFM-01..CFM-04** for the discipline rules. Template: [`docs/recipes/mgf-standards-conformance-md-template.md`](../recipes/mgf-standards-conformance-md-template.md). Reference shape: [TelePlasma](https://codeberg.org/magogi-admin/TelePlasma/src/branch/main/docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). |
| <a id="DOC-16"></a>**DOC-16** (v2.12) | **Every project MUST maintain a `DEPS.md` bidirectional dependency manifest at repo root.** It shows **both sides**: **§1 — what this project depends on** (federation siblings + third-party runtime deps), and **§2 — who depends on this project** (every consumer project + federation sibling that imports it, with location, import-site count as a coupling proxy, adoption status, and primary surfaces used). §2 is the inverse of DOC-14 (consumer-side `MGF_ADOPTION.md`): DOC-14 is "I depend on …"; `DEPS.md §2` is "… depends on me." Verified by `grep` import survey before every MINOR release. mgf-common owns the federation per the one-big-library mindset, so the mgf-common owner is the authority for sibling `DEPS.md` too. Reference shape: [mgf-common/DEPS.md](../../DEPS.md). **v2.12 (2026-05-28):** `DEPS.md` REPLACES the former `USERS.md` (whose "who depends on me" roll is now `DEPS.md §2`); `USERS.md` is removed from the requirement and may be deleted. Rationale: breaking-change blast-radius, deprecation planning, and "what do we even pull in?" audits all need both directions in one tractable place. |
| <a id="DOC-17"></a>**DOC-17** (v2.10) | **`FEDERATION.md` at mgf-standard root is the canonical contract.** Every project that depends on mgf-common (or any sibling) MUST treat [`FEDERATION.md`](../../FEDERATION.md) as the single source of truth for federation duties: required docs layout, standards-conformance levels (L1/L2/L3), federation-first principle, catch-up cadence, feedback discipline, and onboarding flows. Siblings and consumers MUST NOT maintain their own copy of the contract — they link here. `mgf-fed catch-up` enforces the contract: missing required artifacts (the DOC-01 v2.11 universal root-doc baseline + DOC-02 `docs/` dir + DOC-14 MGF_ADOPTION.md for consumers + DOC-15 MGF_STANDARDS_CONFORMANCE.md for everyone) cause a non-zero exit so the audit can gate CI. The mgf-standard maintainer updates FEDERATION.md in the same commit as any standards rule that changes the contract; drift between FEDERATION.md and the rule set is a defect. Rationale: without one canonical contract, every new consumer re-discovers expectations from scratch and the maintainer must remember to tell them; with it, the answer is `cat FEDERATION.md`. |
| <a id="DOC-18"></a>**DOC-18** (v2.13; cross-repo wave carve-out v2.26.1) | **Change propagation — a change to a coupled surface MUST update its dependents: in the same commit for same-repo dependents; for cross-repo dependents (e.g. the `mgf-fed` CLI surfaces in `mgf-common`), in the same change-wave — one commit per repo, cross-referenced in both commit messages, and the wave is not "done" until every repo's commit has landed (the ripple rule).** Surfaces are coupled: a public symbol ↔ `PUBLIC_API.{md,json}` + `CHANGELOG.md` + the rule that documents it; a **standards rule** ↔ the README *Index of MUSTs* + `CHANGELOG.md` + the `mgf-fed standards` / `agents` CLI surfaces + the AGENTS top-rules (if load-bearing) + the conformance-tracker template; a **CLI command/flag** ↔ its `--help` + the CLI reference/recipe + the standard that defines it + (if it changes the agent workflow) the `agents` briefing; a **wire schema** ↔ each parallel copy + `schema_version` + the two-sided alignment test + the release-coupling note; a **federation member** (add/rename) ↔ the registry generator (REL-13) + `DEPS.md` + `NAMING`. Before a change is "done" you MUST walk the **Change-Propagation Matrix (§10.4)** and update every dependent it lists — same commit in-repo, same change-wave cross-repo. Where a coupling is mechanizable it MUST be pinned (a test, or a `mgf-fed app-doctor --standards` check); every standards doc MUST carry a **Propagation header** (§10.4) naming its dependents so the ripple is visible at the point of edit. Leaving a dependent stale is a defect **even when nothing is "broken."** Generalises DOC-04 / DOC-08 / DOC-09 / DOC-17 into one discipline; the agent-facing form is **AG-14**. |
| <a id="DOC-19"></a>**DOC-19** (v2.20; **MUST since v2.21**) | **Every project MUST keep a root `LESSON_LEARNED.md`** — an append-only, dated log of the non-obvious things learned working *in this repo* (corrected assumptions, gotchas, reusable techniques, dead ends), so the federation stops re-learning the same thing. One entry = what / why / how-to-apply; supersede a wrong entry with a newer one, never rewrite history. A lesson that generalises **beyond** this repo MUST ALSO be routed as a `pending-feedback/<target>.md` paper (the FEEDBACK-OUT step of the [`federation-sync-prompt`](../recipes/federation-sync-prompt.md)) so the value crosses the repo boundary — `LESSON_LEARNED.md` is local memory, the outbox is how it reaches the federation. A seeded file with no real lessons yet is conformant (presence is the bar); the file MUST exist. Template + discipline: [`docs/recipes/lesson-learned-md-template.md`](../recipes/lesson-learned-md-template.md). <br><br>**Promotion history (v2.21, 2026-06-07):** shipped in v2.20 as a deliberately-staged **SHOULD**, kept out of the Index of MUSTs so it would not retro-fail every repo's ledger before the file existed. Promoted to **MUST** once the file was seeded federation-wide (the DOC-19 adoption wave, `docs/archive/2026/doc19-promotion-wave.md`): it now enters the [Index of MUSTs](README.md#index-of-musts) (so the **CFM-03** ledger-completeness gate requires a row) **and** the `mgf-fed app-doctor --standards` / `catch-up` **presence gate** (mgf-common FEEDBACK **PAPER-99**). <br><br>**Propagation (DOC-18):** README *Index of MUSTs* + `CHANGELOG.md` + §2.0.1 applicability matrix + `FEDERATION.md` + the `lesson-learned-md-template` recipe + the `mgf-fed app-doctor --standards` presence gate. |

---

## FB — FEEDBACK discipline (v2.8)

| ID | Rule |
|---|---|
| **FB-01** | **Paper numbering is local-per-repo.** Each `FEEDBACK.md` has its own `PAPER-NN` sequence starting at `PAPER-01`. Numbers NEVER renumber within a repo — papers keep their PAPER-NN forever for stable git-blame + cross-reference. When a paper is MOVED from one repo to another, it gets a new local number in the destination repo; the original-source federation number stays in a metadata-table row as a cross-reference (`Federation paper: PAPER-NN in mgf-common`). |
| **FB-02** | **Every paper MUST have a metadata table** carrying: `Status` (`OPEN` / `SHIPPED` / `DEFERRED` / `WONTFIX` / `MOVED`), `Submitter` (consumer name + commit URL to the friction site), `Submitted` (ISO-8601 date), and `Severity` (🟢 / 🟡 / 🔴 — recommended). |
| **FB-03** | **A `SHIPPED` paper MUST carry a `Shipped in` row** with the commit SHA + release-version reference. A consumer can `git blame` the close. |
| **FB-04** | **Consumer-side filing discipline.** When a consumer hits friction with mgf-common OR any federation sibling, file the PAPER-NN at the appropriate repo's `FEEDBACK.md` (per DOC-13). The misfile-into-cornerstone (mgf-common PAPER-36..42 case study, 2026-05-17) was the prompt for this rule. AI agents see the `feedback-discipline` auto-block in their `docs/CLAUDE.md` (managed by `mgf-fed catch-up`) reminding them where to file what. |
| <a id="FB-05"></a>**FB-05** (v2.23 — **MUST**, since `mgf-fed feedback` shipped in mgf-fed 0.3.0) | **Cross-repo feedback flows through a tracked OUTBOX and is RELAYED by the supervisor — never a direct edit.** A project is read-only on every other federation repo, so a finding destined elsewhere is drafted into an **outbox**: `pending-feedback/<target>.md` at the repo root, one file per target (`mgf-common`, a sibling slug, or `mgf-standard` for a standards challenge). Each outbox paper carries the [feedback-md-template](../recipes/feedback-md-template.md) fields **plus an `Origin:` line** (source repo + ISO date + friction-commit URL) so the relay can stamp the FB-01 cross-reference. **The supervisor** — the federation maintainer or a delegated relay agent, the *sole* sanctioned cross-repo writer — relays each paper into `<target>/FEEDBACK.md`: assign the target's next local `PAPER-NN` (FB-01), append in canonical format with a `Federation paper:` back-reference to the origin, then mark the source relayed (move to `pending-feedback/relayed/`). The relay lands via **PR** and is **idempotent** — a relayed paper is never re-relayed. Un-relayed outbox papers are visible federation debt: the tooling (`mgf-fed feedback --check` / `status`) MUST surface them so a finding can never rot silently. Procedure + tool: [`feedback-relay.md`](../recipes/feedback-relay.md). Enforced by `mgf-fed feedback --check` (the no-silent-rot gate; shipped in mgf-fed 0.3.0). |

---

## ADP — Adoption-tracker discipline (v2.8)

| ID | Rule |
|---|---|
| **ADP-01** | **Location:** `docs/inprogress/MGF_ADOPTION.md` (recommended — adoption is an active tracker, drift over time is the signal) OR `docs/MGF_ADOPTION.md` (alternate — for projects that don't use the `docs/inprogress/` bucket). The README MUST link to whichever path is chosen. |
| **ADP-02** | **Required sections:** §1 At-a-glance (pin / extras / status), §2 Strategic context, §3 Phase status, §4 Pin-bump history (one row per bump; append-only — drift over time is the signal), §5 FEEDBACK rounds (with cross-references to the project's own FEEDBACK.md + upstream FEEDBACK.md as applicable), §6 Cross-references. The template at [`docs/recipes/mgf-adoption-md-template.md`](../recipes/mgf-adoption-md-template.md) is the canonical shape. |
| **ADP-03** | **Update cadence.** The tracker MUST be updated on every pin bump (mgf-common OR any sibling) AND on every closed FEEDBACK paper that touches the project's adoption surface. The `adoption-discipline` auto-block in `docs/CLAUDE.md` (managed by `mgf-fed catch-up`) reminds AI agents of this cadence. |
| **ADP-04** | **Federation-sibling carve-out.** Federation siblings (mgf-fastapi, mgf-http, mgf-sqlalchemy, mgf-alembic, mgf-django, mgf-apiprobe, mgf-website-template) do NOT maintain their own `MGF_ADOPTION.md` — their adoption relationship to mgf-common is documented in [federation_roadmap.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/federation_roadmap.md) and each sibling's own CHANGELOG. The DOC-14 MUST-have applies to **consumer applications only** (vm-vmanager-app, TelePlasma, inthewords, iosRecovery, and any future adopter). Siblings DO still need `MGF_STANDARDS_CONFORMANCE.md` (CFM-01 applies to them). |

---

<a id="cfm-conformance-tracker-discipline-v28"></a>
## CFM — Conformance-tracker discipline (v2.8)

| ID | Rule |
|---|---|
| **CFM-01** | **Location:** `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`. The README MUST link to it AND declare the project's conformance level (L1 / L2 / L3 per CFM-02) in the same place. |
| **CFM-02** | **Conformance levels.** A project's level measures *how strictly* it follows the standards, not which features it wires. **L1 — Lite:** conform to the *spirit* of the standards on a best-effort basis. Suitable for greenfield experiments / scratch projects. **L2 — Standard:** conform to every **MUST** rule, evidenced by a per-rule audit. The expected default for production consumers + federation siblings. **L3 — Strict:** conform to every **MUST and SHOULD** rule, with run-time enforcement (audit-logs, redaction) wired up. Reserved for the cornerstone library (`mgf-common`) + flagship / high-stakes consumers. Canonical definition: [`FEDERATION.md` §4](../../FEDERATION.md). |
| **CFM-03** | **Per-rule audit shape.** For each standard's rules (DP-01..DP-N, LG-01..LG-N, etc.), the tracker assigns one status marker: **✅** conformant / **🚫** declined-with-rationale / **⏳** in-progress / **N/A** (rule doesn't apply to this project's shape). The audit MUST be re-run on every standards bump (v2.6 → v2.7 → v2.8 → ...) AND on every PR that changes code touching a conformance rule. Each pass appends an §4 Audit log row (drift over time is the signal — see also DOC-11 archival pattern). **Completeness (v2.19):** the ledger MUST account for **EVERY current MUST** in the [Index of MUSTs](README.md#index-of-musts) — each gets one ✅/🚫/⏳/N/A row (an out-of-shape MUST is *accounted for* as N/A, not omitted). A ledger missing any MUST is a **partial sync** that reads as conformant while it is not. **Mechanically enforced by `mgf-fed app-doctor --standards`** (the Index-of-MUSTs completeness gate — non-zero on any unaccounted MUST); wire it into CI for L2/L3. |
| **CFM-04** | **Decline-with-rationale.** A 🚫 status MUST carry a paragraph rationale in §3 of the tracker. Acceptable rationales follow [principles/non-adoption-is-valid.md](./principles/non-adoption-is-valid.md) (ASPIRE-04 precedent): the rule's underlying need is met by a different mechanism (with proof); the rule's premise doesn't hold for this project's shape (e.g., DEP-* for libraries); the rule is in tension with a framework constraint (e.g., CF-08 vs Django's `from django.conf import settings`). A "we just don't want to" rationale is NOT acceptable — cleanly file the friction as a paper in [mgf-common/FEEDBACK.md](../../FEEDBACK.md) instead. |

---

## 1. Mental model — docs as load-bearing infrastructure

Code without docs is **personal property**. Code with docs is
**infrastructure**.

The difference matters in practice: infrastructure has a
maintenance contract that personal property doesn't. A
consumer / contributor / AI agent shows up six months later and
expects to find:

- **What this project IS** (`README.md`).
- **How to start using it** (`STARTHERE.md`).
- **What changed in the version they're pinned to** (`CHANGELOG.md`).
- **What they're allowed to depend on** (`PUBLIC_API.md`).
- **How to file a problem / a feature request** (`FEEDBACK.md`).
- **How to contribute back** (`CONTRIBUTING.md`).
- **How to report a vulnerability privately** (`SECURITY.md`).

That's the minimum doc-shape for a cornerstone library. A
**federation sibling** scales down (FEEDBACK + CONTRIBUTING +
STARTHERE often inherited or N/A), and a **consumer
application** scales down further (no PUBLIC_API, no FEEDBACK
lifecycle). §2.0 carries the per-shape applicability matrix so
each project applies the right subset.

Anything less than the per-shape minimum and the
infrastructure-contract is broken for SOMEONE — and you don't get
to choose which someone.

Beyond the minimum, the hierarchy below scales linearly with
project complexity. A 200-line application still ships the
uniform ten-doc baseline (most files tiny — a one-line
STARTHERE, an empty-§2 DEPS) + one or two recipes. A cornerstone library serving multiple
consumers needs the full six-bucket hierarchy + audience-driven
entry points + living trackers. The structure is the same; the
depth grows.

**Documentation is not an afterthought, not a nice-to-have, not
"we'll do it after the release."** It is a deliverable equal to
the code, gated by the same CI, owned by the same author, and
shipped in the same commit. Treating it as anything less is how
projects become unmaintainable.

---

## 2. The hierarchy (rule DOC-02)

### 2.0 Project shapes — applicability matrix

Three project shapes exist in the MGF foundation. The doc
requirements differ per shape; the rules in this document apply
to each shape as documented in the tables below.

| Shape | Examples | Distinguishing feature |
|---|---|---|
| **Cornerstone library** | `mgf-common` | Sets the standards; ships the most rules. Has independent consumers across multiple projects. Owns the canonical `docs/standards/`. |
| **Federation sibling** | `mgf-django`, `mgf-fastapi`, `mgf-http`, `mgf-sqlalchemy`, `mgf-alembic`, `mgf-apiprobe`, `mgf-website-template` | Small focused library extracted from a cornerstone or peer to it. Has its own presence on the self-hosted devpi index (see [`PACKAGE_DISTRIBUTION.md`](PACKAGE_DISTRIBUTION.md), PKG-01/PKG-02) + version cadence. Inherits standards from the cornerstone. |
| **Consumer application** | desktop / GUI apps, web apps, scientific platforms, end-user tools | End-user application that *consumes* the libraries. Not published to the devpi index as a library (see [`PACKAGE_DISTRIBUTION.md`](PACKAGE_DISTRIBUTION.md), PKG-01). May not be open source. The owner of `docs/runbooks/`, `docs/adrs/`, `docs/personas/`, etc. |

**Where to declare the shape.** A project's `README.md` SHOULD
state its shape in the front-matter or first paragraph (e.g.,
"Federation sibling of `mgf-common`; depends on `mgf-common
>=0.33,<0.34`"). This single line tells a contributor or AI agent
which rules to apply.

#### 2.0.1 Per-shape root-doc applicability (DOC-01)

**v2.11 (2026-05-28):** the matrix below is now a uniform baseline —
the previously shape-dependent (⚠️) rows are universal-MUST (✅) for
every shape. Two carve-outs that keep the file *minimal* (never absent)
are noted in the table. Only `PUBLIC_API.md`/`.json` stays library-only.

| File | Cornerstone | Sibling | Application | Notes |
|---|---|---|---|---|
| `README.md` | ✅ | ✅ | ✅ | What is this project? Universal. |
| `LICENSE` | ✅ | ✅ | ✅ | License declaration. Required for every project. |
| `CHANGELOG.md` | ✅ | ✅ | ✅ | Per-release record per **DOC-04**. An app with no formal release cadence still keeps the file (per-tag notes are fine). |
| `SECURITY.md` | ✅ | ✅ | ✅ | Vuln-reporting policy per **SC-12**. |
| `FEEDBACK.md` | ✅ | ✅ | ✅ | Consumer-signal flow (DOC-13 / FB-01..04). An app whose feedback is exclusively upstream MAY redirect, but the file MUST exist with a pointer. |
| `AGENTS.md` | ✅ | ✅ | ✅ | Cross-tool agent-discovery pointer (managed by `mgf-fed catch-up`). |
| `CONTRIBUTING.md` | ✅ | ✅ | ✅ | Dev setup, gates, PR process. |
| `STARTHERE.md` | ✅ | ✅ | ✅ | "I just installed / cloned you — now what?" first-run flow. |
| `FEDERATION.md` | ✅ (pointer stub) | ✅ (canonical in `mgf-standard`; pointer stub elsewhere) | ✅ (pointer stub) | The federation contract. It is **canonical only in `mgf-standard`** (the standards/contract source of truth); every other project — including the `mgf-common` cornerstone — ships a **pointer stub**, NOT a copy (DOC-17). |
| `DEPS.md` | ✅ | ✅ | ✅ | Bidirectional dependency manifest (DOC-16): §1 what this project depends on + §2 who depends on it (the former `USERS.md` roster). A leaf app fills §1 and leaves §2 empty; the file MUST exist. |
| `PUBLIC_API.md` (+ `.json`) | ✅ | ✅ | ❌ | The contract surface for a library. Apps don't have one. Per **AP-10** + **DOC-08**. |
| `docs/` (directory) | ✅ | ✅ | ✅ | Every project MUST have a `docs/` directory at the repo root (bucket layout per **DOC-02**). |
| `LESSON_LEARNED.md` | ✅ | ✅ | ✅ | Append-only, dated lessons log (per **DOC-19** — **MUST since v2.21**; shipped v2.20 as a staged SHOULD, promoted once seeded federation-wide). A seeded file with no lessons yet is conformant; presence is the bar. |

Application-specific root docs (e.g., `USER_MANUAL.md`,
`ARCHITECTURE.md`, `ROADMAP.md`, `FEATURE_SPEC.md`) are
optional and project-shape-driven; if you ship them, follow
**DOC-12** (relative links, hierarchical headings, agent-
navigable). They do NOT belong in a library project — push
that content into `docs/reference/`, `docs/design/`, or the
cornerstone's `docs/inprogress/` strategic-review tracker.

#### 2.0.2 Per-shape `docs/` bucket applicability (DOC-02)

| Bucket | Cornerstone | Sibling | Application | Notes |
|---|---|---|---|---|
| `docs/standards/` | ✅ (defines them) | ⚠️ pointer-only README | ⚠️ pointer-only OR project-specific extensions | See §2.0.4 for the pointer-only pattern. |
| `docs/reference/` | ✅ | ⚠️ if API is wide enough to need per-component guides | ❌ | A sibling with one or two public modules usually doesn't need `docs/reference/` — the README's API section is enough. |
| `docs/inprogress/` | ✅ | ⚠️ if has parallel work streams | ✅ | Apps almost always have parallel work; siblings often don't. |
| `docs/claude/` | ✅ | ✅ | ✅ | Every project that wants AI agents to be productive ships this (per **DOC-07**). |
| `docs/cutover/` | ✅ | ✅ | ❌ | Cutover guides are a library-to-consumer contract. Apps have no downstream consumers. |
| `docs/recipes/` | ✅ | ✅ | ⚠️ as needed | A sibling ships recipes for its own surface. An app ships recipes only for its own operators / users. |
| `docs/design/` (additional) | ⚠️ as needed | ⚠️ as needed | ✅ | Architecture papers, ADRs. Apps tend to need these more than libraries. |
| `docs/runbooks/` (additional) | ❌ | ❌ | ✅ if production service | Service-shape apps; per **OP-11** runbook-per-alert. |
| `docs/adrs/` (additional) | ❌ | ❌ | ⚠️ as needed | Project-level architecture decision records. The `non-adoption-is-valid` principle invokes this for documenting declined upstream primitives. |
| `docs/reference-consumers/` (additional) | ✅ (when ≥2 consumers exist) | ❌ | ❌ | Cornerstone-only — evidence that the standards work in practice. |

#### 2.0.3 The minimum-set per shape

If you're standing up a new project, the minimum to start is:

**Federation sibling:**
```
README.md  LICENSE  CHANGELOG.md  SECURITY.md  PUBLIC_API.md  PUBLIC_API.json
docs/
├── claude/CLAUDE.md
├── cutover/      ← empty until first breaking change
├── recipes/      ← grows as the surface stabilises
└── standards/README.md   ← pointer-only; links to cornerstone (§2.0.4)
```

**Consumer application:**
```
README.md  LICENSE (if open-source)  CHANGELOG.md (if released)  SECURITY.md
docs/
├── claude/CLAUDE.md
├── inprogress/   ← living trackers (roadmap, in-flight work)
├── standards/README.md   ← pointer-only OR project-specific extensions (§2.0.4)
└── (additional as needed: design/, adrs/, runbooks/, personas/)
```

**Cornerstone library:** the full set (see §2.1 and §2.2).

#### 2.0.4 The pointer-only `docs/standards/README.md` pattern

A non-cornerstone project's `docs/standards/` MUST NOT duplicate
cornerstone content. Two valid shapes:

1. **Pointer-only.** The folder contains a single `README.md`
   that states "the cross-project standards live at
   `mgf-standard/docs/standards/`; this project inherits them"
   and lists which conformance level (L1 / L2 / L3) the project
   targets.

2. **Project-specific extensions.** The folder contains
   `README.md` (with the "NOT a duplicate" framing) + one or
   more project-specific standards files for concerns the
   cornerstone explicitly leaves out of scope (e.g., a
   multi-tenant web service's `MULTI_TENANCY.md`, a frontend
   app's `FRONTEND.md`, a probing service's project-specific
   `SCOPE.md`).

In both shapes, the `README.md`'s first paragraph MUST say:

> This folder is **NOT a duplicate** of `mgf-standard/docs/standards/`.
> The cross-project standards live at `mgf-standard`; this project
> depends on `mgf-common` (pinned via `mgf-common>=<X.Y>,<<X+1.0>`).

This prevents the rot pattern where a project copies the
cornerstone standards in a freeze-in-time snapshot and they
silently drift.

---

### 2.1 Root-level docs (rule DOC-01)

The uniform ten-doc baseline at the repository root, MUST for
every shape — cornerstone, sibling, AND application (the §2.0.1
matrix is the canonical applicability reference; only
`PUBLIC_API.md`/`.json` stays library-only):

| File | Purpose | Audience | Updated when |
|---|---|---|---|
| `README.md` | What this project IS + how to install + a 30-second "what does it do" demo + shape declaration | Everyone | Major shape changes only |
| `LICENSE` | The legal terms under which the project is distributed | Everyone (legal); auditors | Once at project birth; rare changes |
| `STARTHERE.md` | "I just `pip installed` you, now what?" — the one-command first-use flow | New users (human + AI) | When the entry-point UX changes |
| `CHANGELOG.md` | Per-release record (Keep a Changelog format); MUST be updated in the same commit as the change | Consumers pinning a version | Every release (per **DOC-04**) |
| `CONTRIBUTING.md` | Dev setup, four green gates, PR process, communication channels | Contributors | When the dev workflow changes |
| `FEEDBACK.md` | Consumer-facing flow for sharp edges, feature requests, design questions. Lifecycle OPEN → ACCEPTED → SCHEDULED → SHIPPED | Consumers + maintainers | Per consumer signal |
| `PUBLIC_API.md` | The contract surface — every public name with stability tier + since-version + one-line description (per **AP-10**) | Consumers | Every public-API change |
| `SECURITY.md` | Vulnerability-reporting policy (per **SC-12**) — supported versions, security contact, embargo expectations | Security researchers | Rare; per **SC-12** template |

Libraries additionally ship `PUBLIC_API.json` (the
machine-readable companion to `PUBLIC_API.md`, per **AP-10** +
**DOC-08**).

### 2.2 The six-bucket `docs/` hierarchy (rule DOC-02)

```
docs/
├── standards/          ← durable cross-project engineering rules
├── reference/          ← per-component user guides (one per public subpackage)
├── inprogress/         ← living priority trackers (this folder is a workspace)
├── claude/             ← AI-agent lookup (CLAUDE.md + claude_common.md)
├── cutover/            ← per-release breaking-change migration guides (v<X.Y.Z>.md)
└── recipes/            ← task-shaped how-tos ("I want to do X — here's the recipe")
```

**Charter table:**

| Bucket | Charter | Failure mode if missing | Failure mode if abused |
|---|---|---|---|
| `standards/` | "What good looks like" — durable, cross-project. The `MUST` / `SHOULD` rules + the patterns that implement them. Rate of change: low. | Every project reinvents the bar (or, worse, never sets one). | Becomes a kitchen-sink of opinions; rules drift from the code that ships. Pin every MUST to a mechanical check. |
| `reference/` | Per-component user guides. One doc per public subpackage. Reads top-to-bottom; consumer-facing. | Consumers reverse-engineer the API from `__all__`. | Drifts from `__all__` (catch via AP-10 + DOC-09). |
| `inprogress/` | Living priority trackers (RA / SH / PC / etc.). The maintainer's internal hygiene queue. | Internal posture rots invisibly until a release surfaces it. | Becomes a graveyard. Per **DOC-11**, move completed trackers to `docs/archive/<year>/`. |
| `claude/` | AI-agent dense-lookup. Facts, citations, pre-approvals. Format §4. | AI agents waste context reverse-engineering the structure. | Becomes human prose. Per **DOC-07**, keep it dense — no "Welcome to our project" paragraphs. |
| `cutover/` | One doc per breaking-change release. Migration recipes, codemod notes, manual-step instructions (per **DOC-05**). | Consumers stranded on an old version with no upgrade path. | Drifts from the actual breaking changes — every entry MUST be paired with the CHANGELOG row. |
| `recipes/` | Task-shaped how-tos ("set up logging for a CLI app", "compose Settings across a parent + plugin"). Consumer-facing. | Consumers do trial-and-error on the API. | Becomes a duplicate of `reference/` — keep recipes verb-shaped ("how to X"), keep reference noun-shaped ("the Y component"). |

### 2.3 Additional buckets (allowed where justified)

Use sparingly. Each additional bucket MUST have its own
`README.md` charter (per **DOC-03**) and a clear "why a new
bucket, not an existing one":

- **`docs/audience/`** — per-audience landing pages (developers /
  AI agents / security researchers / QA / users / release engineers).
  Each is a short pointer-doc routing the reader to the relevant
  reference / recipe / standards doc. Useful when the same content
  is needed from multiple entry points; harmful when it duplicates.
- **`docs/design/`** — architecture papers / ADRs / federation-shape
  documents that explain *why*, not *how*. Rate of change: very low.
- **`docs/internal/`** — maintainer-only recipes
  (`lift_checklist.md`, `TEST_COVERAGE.md`). Consumers don't read
  these; AI agents do.
- **`docs/ops/`** — operations recipes (`benchmarks.md`, runbook
  stubs). Cross-cuts reference + maintenance.
- **`docs/reference-consumers/`** — per-consumer shape profiles
  (one per known consumer). The evidence that the standards
  work in practice. The standards themselves stay
  consumer-neutral; the evidence lives next door (closes
  **PAPER-06** in the mgf-common FEEDBACK log).

The pattern: a new bucket is created only when the existing six
genuinely don't fit AND there are ≥3 docs that share the new
charter. Two docs sharing a theme go into the most-relevant
existing bucket.

### 2.4 The promotion / demotion cycle

Docs aren't immutable; they move buckets as a project matures.
The common transitions:

```
docs/inprogress/X.md            ──[scope complete]──▶  docs/archive/<year>/X.md
docs/design/proposal.md         ──[shipped]─────────▶  docs/reference/<component>.md
docs/recipes/X.md               ──[abstracted]─────▶  docs/standards/<topic>.md §N
FEEDBACK §X.Y                   ──[shipped]────────▶  docs/cutover/v<Z>.md "Closes X.Y"
                                                  +  CHANGELOG entry "Closes X.Y"
```

The discipline: when a doc has crossed a milestone (completed,
shipped, abstracted), MOVE it. Don't leave the old copy as
"historical reference" in the active bucket — that's how
buckets become graveyards.

---

## 3. The priority-tracker shape (rule DOC-06)

A *living priority tracker* is a workspace document — one item
per known concern, status flipped as work lands. The shape is
stolen from RELIABILITY_AND_ACCURACY.md and is the canonical
format for any "what's open?" document:

### 3.1 The six sections

```markdown
# <Tracker Name>

> **Status:** v0.1 — first pass. Last updated <YYYY-MM-DD>.
> <one-paragraph audit summary>
>
> **Scope:** <what's in / out>
> **Audience:** <Bassam-tomorrow, AI agents, future hires>
> **Cross-references:** <sibling trackers, standards>

## §1 You are here       ← framing + counts table + "do first" hint
## §2 Priority table     ← P0 / P1 / P2 with one-line per item + Effort + Status
## §3 Invariants we hold ← closed elsewhere; do not re-open
## §4 Work units         ← one section per row in §2 with file:line + concrete output
## §5 Closed items       ← one bullet per closure with commit SHA
## §6 Notes on methodology ← how the audit was run + what a v0.2 depth pass should do
```

### 3.2 The per-item shape (§4)

Each work unit has four sub-headings:

```markdown
### XX-NN <One-line title>

**Why:** [`src/path/to/file.py:LINE`](...) — the evidence.
Concrete observation, with a local measurement where applicable.
Why it matters in practice.

**Concrete output:**
- A bullet list of falsifiable outcomes. "X is now Y" not
  "we should think about Z".

**Dependencies:** <other item IDs, or "none">

**Status:** ⏳ open / 🟡 in progress / ✅ closed. Effort: S / M / L.
```

### 3.3 The discipline that makes it work

**Narrow.** Each item is a single concrete commit. If closing
it takes more than one sitting, the item is too wide — split it.

**Falsifiable.** "Concrete output" is checkable. A reader who
isn't the author can tell whether the item is closed or not.

**Verified evidence.** `file:line` references MUST resolve when
the tracker is read. A stale citation is a defect; refresh it
or rewrite the item.

**Generous budgets** (for perf trackers). "Current measurement
× 2-3" beats "current × 1.05". The point is order-of-magnitude
regression detection, not precise speedometering. See
`TESTING.md` §8.5.

**Honest scope.** A 10-item tracker is fine. A 40-item tracker
is fine. A 10-item tracker padded to 40 because "more items =
more thorough" is a defect. The
PERFORMANCE_AND_CAPACITY.md tracker's §1 explicitly states:
*"This is a thin tracker for a healthy library."* Adopt the
honesty.

**Status flipped at closure time, not later.** A closed item
moves to §5 in the SAME commit that lands the closure. No "I'll
update the tracker later" — later never comes.

### 3.4 What goes in a tracker vs. elsewhere

| Signal source | Goes in | Why |
|---|---|---|
| Internal audit ("we should fix X") | `docs/inprogress/<tracker>.md` | Maintainer-owned; needs verified evidence; falsifiable concrete output |
| Consumer report ("Y broke when I tried Z") | `FEEDBACK.md` | Consumer-owned lifecycle; OPEN → ACCEPTED → SCHEDULED → SHIPPED |
| Long-horizon "where should this go" | `docs/inprogress/strategic_review.md` (or equivalent) | Not falsifiable per-item; not actionable today |
| One-off "I noticed X" (no plan, no audit) | A GitHub/Codeberg issue | Doesn't deserve a doc commit |

Mixing these dilutes every category. A FEEDBACK entry with
no severity, no consumer, and no shape is half-a-tracker-item;
a tracker item with no file:line evidence is half-a-FEEDBACK.

---

## 4. The `CLAUDE.md` format (rule DOC-07)

`docs/claude/CLAUDE.md` is the AI-agent-specific entry point.
It is NOT a README for AI agents. It is a **dense lookup
document** — facts, file:line citations, pre-approvals — that
lets an agent answer common questions without re-reading the
codebase.

### 4.1 The mandatory shape

```markdown
# <project> — Claude Reference

Dense lookup document. No prose. Facts only.

> **See also: [`claude_common.md`](claude_common.md)** — cross-project
> rules that apply to every project on this machine.

---

## User pre-approvals — project addenda
<what the agent can do without asking>

## File map (where things live)
<table: docs/path/X.md ↔ "what this doc is for", one row per important doc>

## Cross-cutting patterns
<numbered list of patterns the agent is expected to know:
"never-raises" observer pattern, atomic-write helper, etc.>

## Build and release
<the canonical sequence: bump version → regen JSON → ...>

## Common pitfalls
<the things every agent gets wrong on first contact>

## Recently-touched areas
<rolling list, last N changes, so the agent has context on what's hot>
```

### 4.2 What doesn't belong in CLAUDE.md

- **Marketing.** "Our project is the best at X." Cut.
- **Tutorials.** Belongs in `docs/recipes/` or `STARTHERE.md`.
- **API reference.** Belongs in `docs/reference/<component>.md`.
- **Long prose explanations.** Reference, don't paraphrase. Link
  to the standards doc / reference doc / design doc that has
  the full story.
- **Stale items.** A CLAUDE.md that references removed code is
  worse than one that doesn't mention the code at all. RA-18
  was about this; it's a recurring failure mode at every
  deprecation removal.

### 4.3 The two-layer pattern

The MGF family splits CLAUDE-style content into two files:

- **`claude_common.md`** (cross-project, machine-level). Rules
  that apply to every project on the maintainer's machine —
  default branch, code-style preferences, communication style,
  global pre-approvals.
- **`CLAUDE.md`** (project-specific). Addenda for THIS project —
  the file map, the project-specific pre-approvals, the
  cross-cutting patterns unique to this codebase.

Both files live in `docs/claude/`. Consumers without the
cross-project layer collapse them into one `CLAUDE.md` —
nothing wrong with that until they have ≥3 projects.

---

## 5. The cutover-guide pattern (rule DOC-05)

Every breaking change ships a `docs/cutover/v<X.Y.Z>.md` guide.
The guide is the **consumer's runway** — when they pin to
`v<X.Y.Z>`, they read this and they know exactly what to do.

### 5.1 Mandatory sections

```markdown
# <project> v<X.Y.Z> — <one-line summary of the breakage>

> **Audience:** consumers pinning <project> who still depend on
> <the removed/changed surface>.

This is a **breaking minor** (or **breaking major**) — <one
sentence on the cycle that led here, e.g. "the AP-12 deprecation
cycle ran cleanly through v0.32.x; if your project ran clean
under `filterwarnings = error`, you have nothing to do">.

## What was removed / renamed / reshaped

| Symbol | Replacement | Codemod? |
|---|---|---|
| ... | ... | Yes / No / Partial |

## Quickest path — `<project> migrate`
<the codemod recipe, with --dry-run preview>

## Manual: <symbol> → <replacement>
<for each non-codemoddable change: before-code + after-code blocks>

## After the cutover
<verification steps: pip show, pytest, smoke check>

## Closes FEEDBACK <ID>
<one-line back-link>
```

### 5.2 What makes a cutover guide good

- **Identifier-anchored.** Every rename in the table is the
  literal old name and the literal new name. No paraphrasing.
- **Mechanical-first.** If a codemod handles it, the codemod
  recipe is FIRST. Manual paths are second.
- **Copy-pasteable.** Every "after" block is something the
  consumer can paste into their codebase without thinking.
- **Closing the loop.** Every cutover guide names the FEEDBACK
  entry it closes (if any) AND is named by the corresponding
  CHANGELOG entry. The three documents — FEEDBACK, CHANGELOG,
  cutover guide — are mutually-referential at the breaking-change
  boundary; checking the linkage is part of REL-07.

---

## 6. `PUBLIC_API.md` + `.json` (rule DOC-08)

The contract surface. Covered in depth in
[`API_DESIGN.md`](API_DESIGN.md) §2.4 + §2.5; the rule for THIS
doc is:

- `PUBLIC_API.md` is for humans (markdown, prose-friendly,
  consumer-facing).
- `PUBLIC_API.json` is for tooling (structured, machine-readable,
  versioned).
- **Both MUST be regenerated from `__all__` at every release.**
- **Two CI pins**, both required:
  - `PUBLIC_API.md` mentions every name in `__all__` (catches
    human-doc drift).
  - `PUBLIC_API.md` mentions every name in `PUBLIC_API.json`
    (catches machine-companion drift — RA-10).
- The `__version__` field in `PUBLIC_API.json` MUST match the
  package's `__version__` and `pyproject.toml::project.version`
  (per **AP-13**).

---

## 7. `FEEDBACK.md` lifecycle (rule DOC-10)

`FEEDBACK.md` is the **consumer-facing flow**. Every entry has
the same uniform shape (so it's grep-able and machine-actionable):

### 7.1 Severity tags

| Level | Meaning | SLA |
|---|---|---|
| 🔴 **Blocker** | Getting it wrong requires a breaking change to fix later. MUST be decided before locking the public surface. | Triaged within the release cycle it lands in; decision recorded inline. |
| 🟡 **High** | Significant quality-of-life issue. Painful, additive to fix later. | Addressed in a MINOR / patch; no release gate. |
| 🟢 **Nice-to-have** | Real value, not urgent. | Picked up when capacity or a second consumer arrives. |
| 💭 **Aspirational** | Long-term direction input. Not actionable today. | Kept for roadmap reviews; drives MAJOR-version planning. |

### 7.2 Status lifecycle

```
OPEN → ACCEPTED → SCHEDULED → SHIPPED
        ↓
     WONTFIX (with sharpened rationale)
        ↓
     DEFERRED (with explicit "what would change my mind" criterion)
```

Status MUST be **inline-grep-able** — a CI lint that greps for
`OPEN |` / `ACCEPTED |` / etc. and tallies them surfaces the
maintainer's queue at a glance.

### 7.3 The closing-the-loop rule (REL-09)

Every FEEDBACK entry flipped to `✅ SHIPPED` MUST produce a
consumer-facing **notification message** drafted at close-loop
time. The CHANGELOG migration section is the source content; the
notification is the *delivery mechanism* — without it, the
consumer who filed the entry never learns it was addressed.

See [`RELEASING.md`](RELEASING.md) §7 for the full template.

### 7.4 FEEDBACK vs. priority trackers

The boundary (per **DOC-10**):

- A **consumer-reported** problem (PAPER-NN, NICE-NN) lives in
  `FEEDBACK.md`. The consumer's experience is the source of
  truth; the maintainer responds.
- An **internally-audited** concern (RA-NN, SH-NN, PC-NN) lives
  in `docs/inprogress/<TRACKER>.md`. The maintainer's audit is
  the source of truth; the codebase is the evidence.

Both feeding into the same release notes is correct.
Cross-contaminating them is not — a tracker item with no file:line
is not a tracker item, and a FEEDBACK entry with no consumer
is not a FEEDBACK entry.

---

## 8. `CHANGELOG.md` discipline (rule DOC-04)

Format: [Keep a Changelog](https://keepachangelog.com/) v1.1.0,
SemVer (with the `0.x` window per **AP-03** — MINOR releases
MAY break).

### 8.1 The mandatory shape

```markdown
## [<X.Y.Z>] — <YYYY-MM-DD>

### Added
- <new public surface>. Closes FEEDBACK <ID>.

### Changed
- <behaviour shift>. Closes FEEDBACK <ID>.

### Deprecated
- <name>. Removal scheduled for <X.Y+N>. See `docs/cutover/<X.Y.Z>.md`.

### Removed
- <name> (deprecated in <X.Y-N>). See `docs/cutover/<X.Y.Z>.md`.

### Fixed
- <bug fix>. Closes RA-NN / SH-NN / PC-NN.

### Security
- <security fix>. Closes SH-NN.
```

### 8.2 The same-commit rule (DOC-04)

The CHANGELOG entry MUST land in the SAME commit as the change.
Not "we'll update the CHANGELOG before the release" — every
public-API-affecting commit updates the `[Unreleased]` section
at the top, and the release commit promotes `[Unreleased]` to
`[<X.Y.Z>] — <date>`.

Why: at release time, reconstructing "what changed since the
last release" from `git log` is brittle and lossy. The
CHANGELOG-in-commit discipline makes the answer trivially
findable.

### 8.3 What does NOT go in the CHANGELOG

- Internal refactors with no public-API impact (those are git
  log content).
- Test additions that don't change behaviour.
- Doc fixes that don't change the rule set.
- Pre-release tooling work.

The threshold: would a downstream consumer's behaviour or
debugging effort change because of this commit? If yes,
CHANGELOG. If no, skip.

---

## 9. Other named formats (lift checklist, benchmarks, etc.)

A few additional formats the MGF family uses recurrently. Each
has a canonical home; each follows a consistent shape so AI
agents and contributors don't have to relearn it.

### 9.1 The lift checklist

`docs/internal/lift_checklist.md` — the recipe for promoting a
component from a consumer codebase into the shared library (or
a sibling package). The shape:

```markdown
# Lifting a component — checklist

## When NOT to lift
<the "two consumers want the same thing" / "the standards demand
it" / "federation-wide policy" signal table>

## Pre-flight (before opening a PR)
- [ ] Confirm there's a second consumer.
- [ ] Read SCOPE.md §SP-04.
- [ ] ...

## The 8 steps
1. Sketch the API in `docs/design/<component>.md`.
2. Lift the source into `src/<library>/<component>/`.
3. ...
8. Open the consumer-side PR that removes the now-lifted local copy.

## After lift
<verification + bookkeeping>
```

The pattern: one canonical recipe, used every time. Every lift
goes through it; every lift produces a `docs/cutover/` entry +
a CHANGELOG row.

### 9.2 The benchmarks log

`docs/ops/benchmarks.md` — release-over-release microbench
numbers. The shape:

```markdown
# Benchmarks — `<project> bench`

## How to read this
<one paragraph: ns-per-call meaning, hardware variance, CI vs laptop>

## Reproducing
<the exact CLI invocation>

## Numbers (initial bench)

### <YYYY-MM-DD>

Hardware: <one-line spec>.

| Operation | ns/call | Iterations |
|---|---:|---:|
| ... | ... | ... |

**Headline numbers:** <one bullet per measurement explaining the meaning>

**Targets going forward:** <one bullet per row with the budget>
```

Append a new dated section per release. **Never edit historical
entries** — the historical record is the regression signal. CI
diffs the new numbers against a checked-in baseline JSON
(PC-06 codifies this for mgf-common's PERFORMANCE_AND_CAPACITY
tracker).

### 9.3 Per-bucket README

Every long-lived bucket (per **DOC-03**) ships its own README:

```markdown
# <Bucket> — <one-line charter>

## What goes here
<one paragraph: the bucket's scope>

## What does NOT go here
<one paragraph: the failure modes; cross-link to the correct bucket>

## Index

| File | One-line description |
|---|---|
| `X.md` | ... |
```

The "what does NOT go here" section is the gate. Without it,
new docs land in whichever bucket the author saw last.

---

## 10. Doc:code drift (rule DOC-09)

The single most common documentation failure is **drift** —
docs naming code that no longer exists, or code that exists but
isn't documented. The mechanical defenses:

### 10.1 Drift detectors (the canonical shapes)

| Drift surface | Detector | Lives at |
|---|---|---|
| `PUBLIC_API.md` ↔ `__all__` | Substring-based test; every name in `__all__` MUST appear in the doc | `tests/unit/test_public_api_doc.py` (per **AP-10**) |
| `PUBLIC_API.md` ↔ `PUBLIC_API.json` | Same shape (per **DOC-08**) | Same file |
| Reference docs ↔ source modules | `See: docs/reference/XX.md` line in the module/class docstring (mgf-common's shape) OR `# See: docs/reference/XX.md` hash comment; CI lint that resolves it | per-module |
| Code citations in standards | Manual review at the top of each tracker pass — a "v0.2 depth pass" refreshes citations | tracker §6 methodology |
| CHANGELOG.md ↔ git log | Same-commit rule (DOC-04) — no need for a detector, the rule prevents drift | n/a |
| Deprecation cycle in code ↔ cutover guide | Each `@deprecated` decoration cites the cutover doc path; CI lint matches | per-module |

### 10.2 The maintenance cadence

- **Per-release:** PUBLIC_API.json regenerated; CHANGELOG promoted; cutover guide drafted if breaking.
- **Per-tracker-closure:** §5 entry updated with commit SHA in the same commit.
- **Per-MAJOR:** scope policy revisited (SP-06); standards version bumped if MUSTs changed; bucket charters reviewed for creep.
- **Per-year:** completed trackers move to `docs/archive/<year>/` (DOC-11); deprecated docs deleted (not "kept for historical reference").

### 10.3 What about LLM-driven doc generation?

A doc generated from code (a Sphinx-style API reference, a JSON
schema from a Pydantic model, a `--help` output) is **derived
data**, not a doc. It belongs in the release artefacts, not in
the `docs/` tree. The `docs/` tree is for **decisions** —
what the API IS, why it is that way, how to use it. Generated
files commit-checked-in are a drift surface (the commit goes
stale the moment a code change lands without re-running the
generator).

If a project wants generated reference docs, generate them in
CI and publish to a separate location (`docs.<project>.org`,
GitHub Pages, the Woodpecker artifact UI) — don't commit them.

**Maintenance: patch the source, never the render (DOC-09, SHOULD).**
When a generated (or generated-and-hand-edited) doc is **wrong**, the
bound outcome is **the render becomes correct *and stays* correct on the
next regeneration** — which a hand-patch of the rendered output silently
breaks (the next `make docs` clobbers it, and the fix is now a phantom
drift). So you **fix the SOURCE the render is derived from** — the
docstring, the type/annotation, the Pydantic field, the JSON schema, the
`--help` string — **as a code change**, then regenerate; you do **not**
hand-edit the rendered artefact. To make the regime legible, a doc whose
content is even partly derived **SHOULD carry an origin tag** at its top:
`<!-- origin: HAND_AUTHORED -->` (decisions prose; edit freely),
`<!-- origin: GENERATED from <source> -->` (never hand-edit; fix the
source), or `<!-- origin: HYBRID — generated <section>; hand-authored
<section> -->` (edit only the hand-authored region). The tag tells the
next editor — human or agent — which surface is safe to touch.

**When the source is in another repo (defer to AG-13 / the FEEDBACK
seam).** If the wrong render derives from a *sibling* library's source,
you do **not** reach across and edit that library (AGENTS **AG-13**: only
the mgf-common supervisor changes a library). You file the source fix as
a PAPER in **that library's `FEEDBACK.md`** (the FEEDBACK seam) describing
the `doc_claim:` vs `code_truth:` gap; the supervisor patches the source
and the regeneration flows back. A local hand-patch of the cross-repo
render is the drift this rule exists to prevent.

### 10.4 The change-propagation matrix (rule DOC-18)

Drift (§10.1) is the *symptom*; **un-propagated change** is the
*cause*. A surface rarely lives alone — change it and a set of
dependents go stale unless you update them in the same breath.
This matrix is the federation's standing answer to "what else does
this touch?" **Walk the row for what you changed before you call it
done.** This is how we keep improving instead of accreting drift.

**Propagation crosses repo boundaries.** A coupling is not confined to
the repo you are editing: a standards rule in `mgf-standard` is
coupled to agent-facing surfaces that ship from `mgf-common` (the
`AGENTS_BRIEFING` constant + the `mgf-fed standards` / `agents` CLI),
and a wire schema is coupled to its parallel copy in
`mgf-test-supervisor`. The same change wave MUST update both sides — but
across a repo boundary the write-authority seam applies: per **AGENTS
AG-13** only the `mgf-common` supervisor edits the `mgf-common` (or any
sibling) side. The standards-repo edit and the supervisor-applied
mgf-common edit are the same logical propagation, landed by the
accountable owner of each repo; "the other repo's copy is stale" is the
exact defect DOC-18 forbids, repo boundary or not.

| When you change… | …you MUST also update (same commit; cross-repo dependents: same change-wave) | Mechanised by |
|---|---|---|
| A **public symbol** / `__all__` (add/remove/rename/retype) | `PUBLIC_API.md` + regenerate `PUBLIC_API.json` + `CHANGELOG.md` + the rule/recipe that documents it + its stability tier | `test_public_api_*` pins (DOC-08/AP-10) |
| A **standards rule** (new / revised / renumbered / removed) | the doc's Rules box + prose + cross-refs + README **Index of MUSTs** + the `mgf-fed standards` alias (if a new file) + AGENTS top-rules (if load-bearing) + the conformance-tracker template + `CHANGELOG.md` | `mgf-fed app-doctor --standards`; README same-commit note |
| A **CLI command or flag** (add/rename/remove) | its `--help` text + the CLI reference/recipe + the standard that defines the behaviour + (if it changes how an agent works) the `mgf-fed agents` briefing + OPERABILITY (if a `doctor`/`version`/`config` surface) | `--help` snapshot tests where present |
| A **wire schema** (`TestRecord`, `LogRecord`, perf artifact, JSONL) | bump `schema_version` + **every parallel copy** (e.g. mgf-common ↔ mgf-test-supervisor) + the **two-sided alignment test** + downstream consumers + the **release-coupling** note (the copies MUST publish together) | alignment contract tests (both sides) |
| A **federation member** (new sibling / rename / **version bump / release**) | regenerate `MGF_LIBRARIES.md` (`python scripts/gen_mgf_libraries.py`) + `DEPS.md` (both sides §1/§2) + each consumer's `MGF_ADOPTION.md` (§1 At-a-glance pin + §4 Pin-bump history, per ADP-03 — same dep/pin fact `DEPS.md §1` holds, kept in sync here so the two cadences don't drift) + `NAMING` mapping + the `/sync` onboarding if a new shape | `gen_mgf_libraries.py --check` — **consistency + currency** gate (REL-13): fails if a pin is inconsistent OR the committed registry is stale |
| **AGENTS briefing content** (AG-*) | the `AGENTS_BRIEFING` constant the `mgf-fed agents` CLI prints (AG-02) + the `STARTHERE.md` mirror | briefing renders rule-counts live from the docs |
| A **standards rule, across the repo boundary** (a rule edit in `mgf-standard` whose wording an agent-facing surface mirrors) | the **`mgf-common`** side, same change wave, **supervisor-applied per AG-13**: the `AGENTS_BRIEFING` constant + the `mgf-fed standards` / `agents` CLI output (the resolved-corpus / briefing the agent actually reads) | `mgf-fed app-doctor --standards` after the pin bump; the standards-repo edit names the coupled mgf-common surface so the supervisor applies it in the same wave |
| The **federation contract** (a contract-changing rule) | `FEDERATION.md` at mgf-standard root (DOC-17) | `mgf-fed catch-up` |
| A **breaking change** (MAJOR, or MINOR in 0.x per AP-03) | `CHANGELOG.md` + a `docs/cutover/v<X.Y.Z>.md` guide (DOC-04/DOC-05) | cutover-guide presence lint |

**Per-document Propagation header.** Every standards doc (and any
artifact with non-trivial dependents) carries, immediately under its
`> **Conformance:** …` block, a one-line pointer:

```markdown
> **Propagation (DOC-18):** when this changes, also update → <dependent>, <dependent>, … (see DOCUMENTATION.md §10.4).
```

It makes the ripple visible **at the point of edit** — the editor
sees the dependents without having to remember the matrix. The header
is the un-mechanisable backstop; prefer a real pin (a test, a
`doctor --standards` check) wherever the coupling can be checked.

**Adding a coupling.** When you introduce a new coupled pair, you
MUST do three things in the same change: (1) add a matrix row here,
(2) add the Propagation header to the upstream doc, and (3) add a
mechanical pin if the coupling is checkable. A coupling that lives
only in a maintainer's head is the next drift.

---

## 11. AI-agent considerations (rule DOC-12)

The MGF family's primary contributor pattern is **human +
AI agent**. The docs system MUST work for both readers.

### 11.1 Concrete rules

- **Relative links over absolute URLs.** `[X](../reference/foo.md)`
  works in a checkout; `https://codeberg.org/...` doesn't (or
  works, but eats context budget on a fetch). Use absolute URLs
  only for cross-repo references.
- **`file:line` citation format.** `src/mgf/common/_lifecycle.py:60`
  is grep-able + jumpable. `_lifecycle.py:60` is not (which file?).
  Always use the repo-rooted path.
- **Hierarchical headings.** `## §N. Title` lets an agent grep
  the top-level structure with one command. Don't skip levels
  (`#` → `###`).
- **Tables for enumerable content.** A list of three or more
  similar items goes in a table, not prose. Tables grep
  efficiently and render predictably in the agent's TOC pass.
- **No marketing language.** "Industry-leading" / "best-in-class"
  / "blazing-fast" — cut. The agent doesn't know what those mean
  and the human reader has already decided to use the library.
- **Date-stamp meaningful changes.** "Updated 2026-05-14"
  beats "Recently updated" — the agent can compute staleness
  from a date; not from prose.

### 11.2 The `CLAUDE.md` discipline (extended from §4)

The `CLAUDE.md` shape (§4) is mandatory; the contents are
project-specific. The two patterns that matter most for agent
productivity:

- **The file map.** A table mapping `path/to/doc.md` ↔ "what
  this is for" gives the agent the same orientation a human
  gets from a folder tour. Without it, agents waste context
  on directory listings.
- **The pre-approvals list.** Project-specific things the agent
  can do without asking ("pinned project root", "PyPI uploads
  follow procedure §X", "default branch is `master` not `main`").
  Without this, every agent run re-litigates the same
  decisions.

### 11.3 The auto-memory layer

Some agent runtimes (Claude Code's `auto memory`) maintain a
persistent file-based memory across conversations. This is
**adjacent to** `docs/claude/CLAUDE.md`, not a replacement:

- `CLAUDE.md` is project-state-stable, version-controlled, read
  by every agent run.
- Auto-memory is conversation-cumulative, agent-local, optional.

A project that wants AI-agent contributors SHOULD ship a clear
`CLAUDE.md` and let auto-memory be incremental. Memory is for
**user preferences and project context** an agent learns
session-by-session; the project's structural facts belong in
`CLAUDE.md` where every agent run reads them.

---

## 12. Anti-patterns (forbidden)

| Anti-pattern | What's wrong | Right shape |
|---|---|---|
| `docs/TODO.md` | Items rot; no owner; no scope | A priority tracker in `docs/inprogress/` OR an issue tracker |
| `docs/notes/` directory | Becomes a graveyard of half-thoughts | A specific bucket from §2.2 or §2.3 |
| `README.md` that includes the full API reference | Mixes project intro with reference; bloats; rots | Separate `PUBLIC_API.md` + per-component `docs/reference/<X>.md` |
| Two CHANGELOGs (root + docs/) | Inevitable drift | One canonical at the root (per DOC-04) |
| `LICENSE.md` | Tool ecosystem expects `LICENSE` (no extension) | Plain `LICENSE` at the root |
| Documentation in source-code comments only | Not discoverable by `pip install` consumers | Public docs in `docs/`; code comments only for non-obvious *why* |
| ASCII-art separators that aren't section breaks | Visual noise; brittle to wrap; useless to agents | Markdown `---` only at meaningful section boundaries |
| Marketing prose in `CLAUDE.md` | Wastes agent context; doesn't help productivity | Facts, citations, pre-approvals only (DOC-07) |
| `docs/cutover/v<X>.md` named after the FROM version, not TO | Hard to find when pinning to the TO version | Always name after the version that contains the breakage (DOC-05) |
| Generated reference docs committed to git | Drifts the moment a code change lands without re-running the generator | Generate in CI; publish separately |
| "TBD" / "Coming soon" in shipped docs | Promise without owner | Either ship the section or delete it; never ship a placeholder |
| Headings without numbers (`## Setup`, `## Configuration`) | Agents can't reliably grep the structure | `## §1. Setup`, `## §2. Configuration` (DOC-12) |

---

## 13. Self-review checklist (every PR that touches docs)

- [ ] **DOC-01** — root-level docs unchanged OR updated. No new root-level docs without a justification.
- [ ] **DOC-02** — new docs land in one of the six buckets (or a documented additional bucket).
- [ ] **DOC-03** — if a new bucket is being added, it ships with its own `README.md` charter.
- [ ] **DOC-04** — every public-API change has a CHANGELOG entry IN THIS COMMIT.
- [ ] **DOC-05** — if breaking, the `docs/cutover/v<X.Y.Z>.md` guide exists with all four mandatory sections.
- [ ] **DOC-06** — tracker work units carry verified `file:line` evidence + falsifiable concrete output.
- [ ] **DOC-07** — `CLAUDE.md` updates stay dense (no marketing, no prose explanations, no stale citations).
- [ ] **DOC-08** — `PUBLIC_API.md` + `.json` regenerated together; both CI pins green.
- [ ] **DOC-09** — every named file path / function / env var resolves at read time.
- [ ] **DOC-10** — consumer reports → FEEDBACK.md; internal audits → docs/inprogress/. No cross-contamination.
- [ ] **DOC-11** — closed trackers moved (or noted for archival) within one release cycle.
- [ ] **DOC-12** — relative links; `file:line` citations; hierarchical headings; no marketing prose.
- [ ] **DOC-18** — walked the **Change-Propagation Matrix (§10.4)** for every surface this change touched; updated each dependent **in this commit** (PUBLIC_API, Index of MUSTs, the `standards`/`agents` CLI, alignment copies, etc.); added a matrix row + Propagation header + pin for any *new* coupling introduced.

---

## 14. Mechanical enforcement matrix

| Rule | Mechanical check | Notes |
|---|---|---|
| DOC-01 root-level docs | repo lint: file existence for every doc in the §2.0.1 uniform baseline (the ten root docs + `docs/` dir; `PUBLIC_API.md`/`.json` for libraries) — equivalently `mgf-fed app-doctor --standards` / `catch-up` | One-shot per repo |
| DOC-02 bucket discipline | repo lint: `find docs -maxdepth 1 -type d` against the allowed set | Additional buckets need a §2.3 justification + README |
| DOC-03 per-bucket README | repo lint: every `docs/<bucket>/` has a `README.md` | Glob check |
| DOC-04 CHANGELOG same-commit | git pre-commit hook: if any `src/` changes touch `__all__` or a docstring of a public name, CHANGELOG must also be in the commit | Implementable as a `pre-commit` hook |
| DOC-05 cutover-guide existence | repo lint: every breaking-CHANGELOG entry references a `docs/cutover/v<X.Y.Z>.md` that exists | Greppable |
| DOC-06 tracker shape | tracker-self-test: a small script that walks `docs/inprogress/*.md` and checks for the six-section heading set | Per-tracker |
| DOC-07 CLAUDE.md exists | repo lint: `docs/claude/CLAUDE.md` exists; file is non-empty | One-shot |
| DOC-08 PUBLIC_API drift | `tests/unit/test_public_api_doc.py` (per **AP-10**) + a JSON-vs-MD lint | Pair of pins |
| DOC-09 doc:code drift | `See: docs/reference/XX.md` docstring lines (or `# See:` hash comments) + a CI grep that the referenced files exist | Per-module |
| DOC-10 FEEDBACK vs trackers | code review; format consistency makes mixing visible | Convention-enforced |
| DOC-11 archive cadence | manual: review at each release | No mechanical check (it's a maintenance signal, not a defect) |
| DOC-12 AI-navigability | code review; absolute-URL lint as a soft signal | Most can be checked with regex |
| DOC-18 change propagation | `mgf-fed app-doctor --standards` (Propagation-header presence check) + the per-coupling pins it names (PUBLIC_API tests, two-sided alignment tests, REL-13 consistency gate) | The matrix (§10.4) is the human checklist; the pins are the mechanical arm — each new coupling SHOULD add one |

---

## 15. AS-IS in `mgf-common`

Reference implementation — every rule above is exercised by
mgf-common's own docs system:

- **DOC-01** — shape: cornerstone library. The full v2.11/v2.12
  uniform root-doc baseline ships — `README.md`, `LICENSE`,
  `CHANGELOG.md`, `CONTRIBUTING.md`, `FEEDBACK.md`, `SECURITY.md`,
  `AGENTS.md`, `FEDERATION.md`, `STARTHERE.md`, `DEPS.md` — plus the
  library-only `PUBLIC_API.md` + `PUBLIC_API.json` (per **DOC-08**).
- **DOC-02** — all six canonical buckets exist
  (`docs/standards/`, `docs/reference/`, `docs/inprogress/`,
  `docs/claude/`, `docs/cutover/`, `docs/recipes/`) plus
  justified additional buckets (`docs/audience/`,
  `docs/design/`, `docs/internal/`, `docs/ops/`,
  `docs/reference-consumers/`).
- **DOC-04** — CHANGELOG.md is maintained per-commit; every
  release is a CHANGELOG promotion.
- **DOC-05** — every release in `0.22.0..0.33.0` ships its
  `docs/cutover/v<X.Y.Z>.md` (12 guides, one per release).
- **DOC-06** — three living trackers in `docs/inprogress/`
  follow the six-section shape:
  [`RELIABILITY_AND_ACCURACY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/RELIABILITY_AND_ACCURACY.md),
  [`SECURITY_HARDENING.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/SECURITY_HARDENING.md),
  [`PERFORMANCE_AND_CAPACITY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/PERFORMANCE_AND_CAPACITY.md).
- **DOC-07** — [`docs/claude/CLAUDE.md`](../claude/CLAUDE.md)
  ships in dense-lookup format.
- **DOC-08** — `tests/unit/test_public_api_doc.py` pins
  the MD ↔ `__all__` drift; `PUBLIC_API.json` ships next to
  `PUBLIC_API.md`.
- **DOC-09** — the reference-doc-bearing public modules carry a
  `See: docs/reference/XX.md` cross-reference line in their
  docstring (back-reference direction (b); the remaining modules
  rely on direction (a)). Direction (a) — CI lint — is supplied
  by `tests/unit/test_public_api_doc.py` for the
  `PUBLIC_API.md` ↔ `__all__` axis.
- **DOC-10** — `FEEDBACK.md` and `docs/inprogress/*.md` are
  distinct surfaces with non-overlapping content.
- **DOC-12** — the docs system was redesigned for AI-agent
  navigability in v0.18.x (the `docs/audience/` bucket adds
  the per-audience entry points; the `tools/docs_explorer/`
  web UI surfaces the cross-references).

The `tools/docs_explorer/serve.py` server (mentioned in
[`STARTHERE.md`](../../STARTHERE.md)) renders the docs as a
local web UI for human readers. AI agents read the markdown
directly.

---

## 16. Cross-references

- Public-API contract: [`API_DESIGN.md`](API_DESIGN.md) AP-10
  (PUBLIC_API.md), AP-13 (`__version__` ↔ pyproject sync).
- Release flow that produces the cutover guides + CHANGELOG
  promotion: [`RELEASING.md`](RELEASING.md).
- The MUST set this doc operationalises across the standards:
  AP-10, SC-12, REL-07, REL-09.
- The component catalogue: [`COMMON_COMPONENTS.md`](COMMON_COMPONENTS.md).
- The scope policy that gates new docs (a new doc is a new
  surface): [`SCOPE.md`](SCOPE.md) SP-03.
- The testing-standard's perf-marker discipline that benchmarks
  follow: [`TESTING.md`](TESTING.md) §8.4.

---

*End of `DOCUMENTATION.md`.*
