# CLAUDE.md — mgf-fed (dense-lookup agent notes)

Facts + `file:line`, not prose. Federation-wide briefing: `mgf-common agents`. Scope: [`../../SCOPE.md`](../../SCOPE.md).

## What it is
`mgf-fed` = federation orchestrator CLI (`mgf.fed`), **zero runtime deps**. Composes: `mgf-standard`
registry/waves · `mgf-test-supervisor` (`mtest`) · `woodpecker-cli exec` · `tea`/git · `uv` · `ruff`.

## Module map (`src/mgf/fed/`)
- `__main__.py` — argparse CLI; one handler per command.
- `_roster.py` — reads `<MGF_ROOT>/mgf-standard/MGF_LIBRARIES.json`; `Member`, `members()`, `federation_root()` (`$MGF_ROOT` → `~/PycharmProjects`).
- `_status.py` — `status` matrix → `~/.mgf/MGF_FED_STATUS.json`; parses each repo's §Z ledger for conf%.
- `_template.py` — reads `mgf-standard/templates/policy.toml` + canonical files.
- `_drift.py` — `drift-check` vs the policy (present/exact/ci-steps/pyproject); has `[exempt]` map.
- `_gates.py` — `gates` (ambient `ruff` lint+format; `_find_ruff()` = PATH or alongside interpreter).
- `_localci.py` — `local-ci` = `woodpecker-cli exec`.
- `_index.py` — local index `~/.mgf/local-index/`; `resolve_args(local, remote)` (remote=False → no Codeberg, local-first).
- `_release.py` — `release-local` (gate→build→validate→smoke→publish) + `release-remote` (pre-req→tag→`uv publish`→REST-verify); token `$MGF_CODEBERG_TOKEN`.
- `_scaffold.py` — `scaffold` applies byte-exact template files (inverse of drift-check).
- `_registry.py` — `registry [--check]` wraps `mgf-standard/scripts/gen_mgf_libraries.py` (REL-13).

## Invariants / pre-approvals
- **Build-once, promote** (REL-02): `release-remote` publishes the *same* wheel `release-local` built; never rebuild.
- **Local-first** smoke uses `resolve_args(remote=False)` → mgf-* deps must be locally released first (= wave order).
- All subprocess = argv lists, `shell=False` (SC-02). Token never printed (SC-11).
- Tests: monkeypatch the module-level `_run`/`shutil.which`/`_find_ruff`/`_codeberg_has`/`_local_wheel` (never hit the network).
- Gates: `ruff` (pinned `>=0.4,<0.16`) · `mypy --strict` · `pytest` (filterwarnings=error). mgf-fed must stay drift-check ✓.

## Release mgf-fed itself
`mgf-fed release-local mgf-fed && MGF_CODEBERG_TOKEN=… mgf-fed release-remote mgf-fed` (dogfood).
