# Fleet libraries review — program tracker

> **Durable, git-tracked source of truth** for the three-item libraries review.
> Designed to survive across sessions **and containers** — anyone (human or
> agent) picks up here. The machine-readable state lives next to this file
> (`item1-conformance.json`); regenerate it any time with the audit harness.

**Scope:** all on-disk `mgf-*` repos (currently **34**), not just the 31-library
registry — includes apps/infra (`mgf-brand`, `mgf-cost-watch`, `mgf-website`)
and the 6 zig libs.

## Recent completions (2026-06-27)

- **mgf-common 0.49 cornerstone ripple** — webhooks HMAC primitive + 3 AP-14 public seams; fleet pin-walked `<0.50`; cohort (cloud/logship/sqlalchemy/livepush) + adopters (auth/fastapi/fed) republished. REL-13 **GREEN + CURRENT** (31 libs).
- **Full-fleet uv parity** — 13 lagging leaves + mgf-cloud-provision backfilled to devpi; `uv pip install <all mgf-*>` now resolves **mgf-common 0.49.1** (verified `--refresh`). Closed the devpi-backfill gap.
- **Fleet co-install CI gate** — `mgf-fed/tests/fleet` asserts the whole fleet resolves at the cornerstone (catches future leaf-lag REL-13 can't see).
- **Audit re-run + harness fix** — `mgf-fed` self-scan FPs (its own detector pattern table) now N/A; trustworthy count is **10 real gaps / 5 repos**.
- **Item 1a CLOSED + Item 2 boundary fan-out (2026-06-28)** — mechanical catch-up (brand/cloud-provision), H1 pin-prose fix (django/fastapi/http), brand WF-13 carve-out + harness N/A; verified ownership boundary injected into all **24** python `SCOPE.md` + **10 new** non-python `SCOPE.md`. **34/34 clean · 0 real gaps**; ownership gate GREEN. (Survived a multi-hour codeberg outage mid-run — branches stayed committed, auto-recovered.)

## The three items

| # | Item | State |
|---|---|---|
| **1** | Sync to standard + best practices; **consumer version catch-up**; conformance level. | **1a CLOSED (2026-06-28)** — **0 real gaps · 34/34 clean**. The tail (brand mechanical + WF-13 carve-out, cloud-provision mechanical, django/fastapi/http H1 pin-prose) is all fixed. **mgf-fed clean** (0.49 retired its `_DEFERRED` reaches; its 2 ex-flags were catch-up *self-scan* FPs — the detector's own pattern table lives in `_catch_up.py` — now N/A). **Catch-up (version) DONE**: mgf-common **0.49.1** cornerstone adopted fleet-wide, REL-13 GREEN+CURRENT, full fleet co-installs at 0.49.1 (uv). **1b (L3 uplift): in progress** — **mgf-common + mgf-cloud are L3**; 1b-0 (reference) + 1b-1 (high-stakes) + Wave 1 done; Waves 2–4 remain. See [`item1b-l3-uplift.md`](item1b-l3-uplift.md). |
| **2** | Make every library's **ownership boundary explicit and verified** (grep-proven, not implied). | **DONE (2026-06-28)** — `fleet_ownership_audit.py` `--inject`s a verified boundary block + a `--check` drift gate (Item 3 seed). Boundary **fan-out COMPLETE**: all **24** python `SCOPE.md` carry an in-sync block + **10** non-python repos have a `SCOPE.md`; `--check` GREEN. **F-B resolved** (mgf-cloud #33); **F-SVIX SHIPPED** in mgf-common 0.49 (`verify_svix_hmac`; auth + fastapi adopted, dup'd crypto deleted). See [`item2-execution.md`](item2-execution.md). |
| **3** | Docs fully updated + a **drift-sync mechanism** between docs and code. | Seeded, not complete — drift-sync instances exist: Item 2's `--check` gate, and the **mgf-fed `tests/fleet` co-install gate** (uv parity, 2026-06-27). Full docs sweep + a general drift-sync mechanism remain. |

### The L3 question (decided)
`FEDERATION.md` §4 defines L1 (Lite) / L2 (Standard, all MUST) / L3 (Strict,
MUST+SHOULD+runtime). **`mgf-common` + `mgf-cloud` are L3** (as of 2026-06-27);
L2 is the documented default for the remaining siblings. Item 1 originally said
"all at L3" → that is the 1b uplift (Waves 2–4 remain).

**User decision (2026-06-25):** *do the audit-against-declared-target first and
complete it; then* start a fleet-wide **uplift to L3** as a separate, large,
multi-session effort tracked here. So Item 1 has two phases:

- **1a — Audit + mechanical catch-up to declared target** (this baseline). ← current
- **1b — Uplift every repo to L3** (MUST+SHOULD+runtime). ← after 1a, own tracker.

## How to reproduce the audit (any container)

```sh
# from mgf-standard repo root; mgf-fed is auto-discovered (PATH or
# <siblings>/mgf-fed/.venv/bin/mgf-fed). Override roots with --root.
python3 scripts/fleet_conformance_audit.py --generated "$(date -u +'%Y-%m-%d %H:%MZ')"
```

Writes `item1-conformance.{md,json}` here. The engine is `mgf-fed catch-up`
(read-only) per repo — ~15 checks, each ✅ clean / ⚠️ gap.

## Item 1a — gap taxonomy + how each class is resolved

Baseline 2026-06-25: **34 repos, 141 raw gaps, 0 fully clean.** Gap classes:

| Class | What it is | Resolution | Auto? |
|---|---|---|---|
| **M1 — stale CLI pointer** | `AGENTS.md` + `docs/claude/CLAUDE.md` auto-block still say `mgf-common <verb>` (pre-rename). | `mgf-fed catch-up --apply` rewrites to `mgf-fed`. Doc-only, no code/test impact. | ✅ mechanical |
| **M2 — missing `.claude/settings.json`** | Repo never got the per-kind settings. | `--apply` creates it. | ✅ mechanical |
| **M3 — test-supervisor TS-22..27 not wired** | Missing dev deps / pytest timeout config (Python repos only). | `--apply` inserts the 3 PAPER-73 sub-fixes. | ✅ mechanical (Python) |
| **M4 — marker taxonomy TS-25** | Missing federation pytest markers. | `--apply` / register markers. Verify per repo. | ⚠️ confirm |
| **H1 — pin-literal drift (PAPER-72)** | `CLAUDE.md` prose quotes a stale `mgf-common >=x` pin vs pyproject. | **Hand-fix** prose (replace literal with cross-ref). | ✋ manual |
| **C1 — closed-box leaks** | `mgf.common._*` private imports across boundaries (`mgf-common`, `mgf-fed`). | **Investigate code.** | ✋ manual |
| **C2 — v0.1-pattern usage** | Legacy `configure()/setup_logging()/install_excepthook()` (`mgf-fed`). | **Investigate code.** | ✋ manual |
| **N/A — shape false-positives** | catch-up isn't shape-aware: flags zig/docs repos for "missing mgf-common pin" + "Python four-gates"; flags `mgf-standard` for "no mgf-common dep" (correct by design — it's the root). | **Mark N/A**, don't "fix". | — |

### Proven mechanical recipe (per repo)
```sh
cd <repo>
/path/to/mgf-fed catch-up --apply      # applies M1/M2/M3; auto-removes its own .bak if clean
git diff                               # confirm doc-only (AGENTS.md, CLAUDE.md) + settings.json
# land per Codeberg PR workflow: branch -> push -> PR -> CI -> self-merge -> delete
```
Doc-only changes don't meaningfully exercise the four-gate test run; CI still
runs on the PR. Branch protection is ON for the 24 CI-enabled Python libs, so
those MUST go through a PR (no direct main push).

## Per-repo status (Item 1a)

Legend: ⬜ todo · 🟩 fixed+landed · ⬛ N/A (shape) · 🟨 needs manual

_Update this as repos are landed. Counts are the baseline gap totals._

| Repo | Lang | Decl | Gaps | Classes | Status |
|---|---|---|---|---|---|
| mgf-alembic | python | L2 | 3 | M1,H1 | ⬜ |
| mgf-apiprobe | python | L2 | 2 | M1 | ⬜ (recipe validated here) |
| mgf-auth | python | L2 | 2 | M1 | ⬜ |
| mgf-brand | other | — | 8 | M1,M2,N/A | ⬜ |
| mgf-cloud | python | L1 | 3 | M1,H1 | ⬜ |
| mgf-cloud-provision | python | L2 | 3 | M2,M1,memory | ⬜ |
| mgf-common | python | L3 | 3 | M1,M2,C1 | ⬜ |
| mgf-common-identity | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-common-zig | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-cost-watch | other | — | 4 | M2,memory,gitignore | ⬜ |
| mgf-django | python | L2 | 3 | M1,H1 | ⬜ |
| mgf-fastapi | python | L2 | 3 | M1,H1 | ⬜ |
| mgf-fed | python | L2 | 6 | M1,M2,M3,C1,C2 | ⬜ |
| mgf-hrb | python | L2 | 2 | M1 | ⬜ |
| mgf-hrb-cap | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-hrb-kabi | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-hrb-model | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-hrb-rt | zig | L2 | 7 | M1,M2,N/A | ⬜ |
| mgf-http | python | L2 | 3 | M1,H1 | ⬜ |
| mgf-livepush | python | L2 | 2 | M1 | ⬜ |
| mgf-logship | python | L2 | 4 | M1,M2,M4 | ⬜ |
| mgf-sqlalchemy | python | L2 | 3 | M1,H1 | ⬜ |
| mgf-standard | python | L2 | 6 | M1,M2,M3,M4,N/A | ⬜ |
| mgf-tele-core | python | L2 | 2 | M1 | ⬜ |
| mgf-tele-teltonika | python | L2 | 2 | M1 | ⬜ |
| mgf-test-supervisor | python | L2 | 3 | M1,M2 | ⬜ |
| mgf-vm-core | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-vm-firecracker | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-vm-forensics | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-vm-interchange | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-vm-libvirt | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-vm-sdk | python | L2 | 4 | M1,M3,M4 | ⬜ |
| mgf-website | node | L1 | 2 | M1 | ⬜ |
| mgf-website-template | other | L1 | 6 | M1,M2,N/A | ⬜ |

## Item 1a — CLOSE-OUT (verified 2026-06-25)

The per-repo table above is the **baseline**; the regenerated `item1-conformance.json`
is current truth. Outcome of the mechanical sweep (`mgf-fed catch-up --apply` per
repo, landed via the Codeberg PR workflow):

**Landed: 30 PRs** — 22 Python libraries + `mgf-standard`'s own catch-up + 6 H1
pin-cross-ref fixes + 5 (of 9) oddballs, via three self-paced engines
(`~/scratch/fleet_{sweep,h1,oddball}_engine.py`). **17 Python repos now fully
clean (0 gaps).** Every M-class (M1 pointer / M2 settings / M3 supervisor /
M4 markers) gap is closed across the Python fleet.

### Residual gaps — what's left and why
| Repo(s) | Residual | Class | Plan |
|---|---|---|---|
| `mgf-django`, `mgf-fastapi`, `mgf-http` | PAPER-72 pin-literal (a **second**, *space-form* literal `mgf-common >=0.33,<0.34.` ~L193 the H1 regex missed) | H1 | trivial: extend the cross-ref edit to the spaced form; 3 PRs (deferred — rate-limit) |
| `mgf-common` | "closed-box leaks" (94) | **N/A** | FALSE POSITIVE — it's mgf-common importing its *own* internals. Not a leak. |
| `mgf-fed` | closed-box leaks (43) + v0.1-pattern | C1 + C2 | **real.** C1 tiered: ~9 trivial public-swaps (`_identity`/`_lifecycle`) + ~25 needing a mgf-common FEEDBACK paper (`atomic_write`, `cli._exit_codes`/`_subcommand_registry` → public). C2: v0.1→`bootstrap()` migration (non-mechanical). Fit into 1b. |
| `mgf-standard` | supervisor + markers + "no mgf-common pin" | **N/A / declined** | CFM-04 pure-leaf decline (adding test-supervisor closes a mgf-common cycle); "no pin" is correct (it's the root). |
| 6 zig libs | mgf-common pin / four-gates / supervisor / markers | **N/A** | shape false-positives (no pyproject). M1/M2 doc fixes landed (7→4 gaps). |
| `mgf-cloud-provision` | M2 + memory + `.gates/` untracked | M2 + hygiene | small manual: add `.gates/` to `.gitignore` (test-supervisor runtime output) + careful catch-up. |
| `mgf-brand`, `mgf-website` | no `.woodpecker.yml` (+ no SCOPE/conformance) | deeper | need CI enabled (`mgf-fed scaffold`) before they can conform — separate effort. |
| `mgf-cost-watch`, `mgf-website-template`, `mgf-common-zig` | oddball M1/M2 | M-class | **landing now** (oddball engine, throttled by the PR-title rate-limit; auto-backoff). |

### Remaining roadmap (durable next steps)
1. **Item 1a tail:** the 3 spaced-literal H1 fixes; the 4 trickling oddballs; cloud-provision `.gates/`.
2. **mgf-fed C1/C2** (real L2 MUST): the tiered closed-box fix + bootstrap() migration — best folded into **1b**.
3. **Item 1b — L3 uplift:** every repo L2→L3 (MUST+SHOULD+runtime). The big phase; own sub-tracker.
4. **Item 2 execution:** machine-readable `owns:` blocks + Boundary stanzas in each SCOPE.md; fix F-B (mgf-cloud web→mgf-fastapi) + resolve F-SVIX (auth/fastapi); SCOPE.md for the 10 missing; wire `fleet_ownership_audit.py --check`.
5. **Item 3:** the doc↔code drift-sync mechanism (the `--check` gate is its seed).

**Engine learnings:** serial processing keeps the 3-workflow Woodpecker runner
uncongested (the real fix for transient clone-auth races); auto-restart clears
the rest; the Gitea **PR-title similarity rate-limit** (~2/cluster/hr) is the
binding throughput constraint — distinct titles + backoff. mgf-standard's M3 was
correctly **held out** (would have added a circular dep).

## Resume protocol (new session / container)
1. `python3 scripts/fleet_conformance_audit.py --generated "$(date ...)"` → fresh `item1-conformance.md`.
2. Diff fresh gaps vs the close-out table above; the residuals there are the live work-list.
3. Work remaining by class (M-classes via `--apply`; H1/C1/C2 + Item-2 fixes manual).
4. Keep the JSON + this close-out the authority; commit after each batch.

## Item 2 — ownership boundary (scoped)
See [`item2-ownership.md`](item2-ownership.md) + `item2-ownership.json` (machine
data, regen via `scripts/fleet_ownership_audit.py`). Methodology validated on the
mgf-cloud/mgf-fed reference case (import = rigorous, string-grep = triage).
Verified sole-owners confirmed; findings: **F-B** (mgf-cloud web imports fastapi
raw vs its "via mgf-fastapi" claim — drift), **F-SVIX** (Svix verification dup'd
in mgf-auth + mgf-fastapi), + legit optional-extra patterns to document, + 10
repos missing SCOPE.md. Next: declare machine-readable `owns:` blocks + wire the
`--check` gate.

## Item 3 — doc↔code drift sync (placeholder)
Inventory existing mechanisms (`mgf-fed catch-up`, `mgf-fed drift-check`,
`docs/recipes/doc-review.md`) and close gaps. Item 2's `fleet_ownership_audit.py
--check` is the first concrete instance of the boundary-drift gate. Tracker:
`item3-doc-drift.md` (TBD).
