# Magogi Foundation Standards — Conformance Tracker (mgf-cloud)

> **Status (2026-06-25).** Re-baselined + re-audited at **0.1.1** after the
> Item 1b-1 L3 depth-audit uplift. This REPLACES the 2026-06-14 "Pass-1 scaffold"
> tracker, which was frozen at v0.1.0 with a deferred-to-Pass-7 audit and several
> false N/As — the surface it deferred against has since fully shipped (core +
> Infomaniak adapter + CLI + cost + remote/bootstrap + web GUI), so the audit is
> now real.
> **Scope.** mgf-cloud's conformance to the standards at
> [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/)
> (corpus index: **263 MUSTs across 22 families + 8 indexed SHOULDs**).
> **Audience.** Maintainer-tomorrow, AI coding agents, future contributors.
> **Cross-references.** [README.md](../../README.md) (declared level),
> [CHANGELOG.md](../../CHANGELOG.md), [PUBLIC_API.md](../../PUBLIC_API.md),
> [docs/design/DESIGN.md](../design/DESIGN.md).

---

## §1 You are here

**Project shape:** a provider-agnostic cloud-resource interface — a pure-Python
**library** (`mgf.cloud`) that ships a **CLI** (`mgf-cloud`) and an optional local
single-user **web GUI** (`mgf-cloud web`). Infomaniak Public Cloud (OpenStack)
first, AWS-ready. It is credential-holding (OpenStack application credentials +
SSH keys) but is **not** a deployed, page-able service — it is operator-run
tooling. That shape decides which rules apply and which are N/A.

**Current version:** **0.1.1** (single-sourced — `mgf.cloud.__version__` reads
`importlib.metadata.version("mgf-cloud")`; `tests/unit/test_version_in_sync.py`
pins it to `pyproject.toml::project.version` on every push, not just at tag time).

**Declared TARGET conformance level: L3 — Strict.** **Current verified standing:
L2 — every applicable MUST that mgf-cloud owns is met**, with **two tracked
fleet-infra deferrals it does not own** (PKG-01, WF-11 — §4). Runtime enforcement
is wired (federation logging + audit records at the credential seams, the gate
stack). The **distance from L2 to a declared L3** is (a) a full per-MUST
`file:line` depth audit of all 263 rules — this re-audit verifies the families
that had gaps + the load-bearing ones, not yet every rule with citations — and
(b) the PERFORMANCE baseline family (PF-01/03/05/07), which is N/A-leaning for a
network-bound CLI but not yet evidenced either way.

**Honest level note (CFM-02).** L2 = *every MUST met*; L3 = *every MUST **and**
SHOULD + runtime enforcement*. The 2026-06-25 depth audit (the 113-agent
`l3-audit-1b1` workflow, adversarial-refute-filtered) found **24 MUST + 7
lower-severity gaps** in mgf-cloud. The Item 1b-1 uplift (stages 1 + 2) **closed
22 of the 24 MUSTs in code** and the lower-severity batch; the **2 remaining MUSTs
(PKG-01, WF-11) are fleet-infra items** — the publish channel and the CI install
method are governed by the `mgf-standard` woodpecker template + the devpi backfill
gap, which mgf-cloud cannot change unilaterally without breaking template-parity.
Per [non-adoption-is-valid](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/principles/non-adoption-is-valid.md),
these are deferred-with-rationale, not declined. **mgf-cloud is therefore at the
L2 bar on every surface it controls.**

| Marker | Meaning here |
|---|---|
| ✅ | conformant against the live 0.1.1 code (evidence in §Z where audited) |
| ⏳ | applicable MUST not met — open gap with a plan (§4) |
| N/A | rule's premise is service/GUI-server/deploy-shaped; mgf-cloud is operator tooling |
| 🚫 | declined-with-rationale (CFM-04 — §3) |

---

## §2 Per-standard audit (2026-06-25, re-baselined to corpus 263 MUSTs / 22 families)

| Family | MUSTs | Verdict | Notes (evidence: §Z where audited) |
|---|---|---|---|
| **AG** AGENTS | 19 | ✅ / N/A | AGENTS.md + docs/memory present, `my_stuff/` gitignored (AG-17/18/19); AG-14 propagation followed in this uplift (PUBLIC_API + CHANGELOG + this ledger walked together). |
| **AP** API_DESIGN | 15 | ✅ | `__all__` on every public module; AP-13 version single-sourced; **AP-10/AP-11** PUBLIC_API.md now enumerates all 24 names with Tier+Since (was "added in Passes 2-3"); **DOC-08** md↔`__all__`↔json drift pins. AP-01: `cost.py` now carries `__all__`. |
| **CF** CONFIGURATION | 12 | ✅ | `config.py` — typed pydantic models, layered resolution (explicit → `$MGF_CLOUD_CLOUDS_YAML` → `OS_*` → search paths), `SecretStr` secrets; rates via TOML + env. CF-09 `--clouds-yaml` flag present. |
| **DEP** DEPLOYMENT | 11 | N/A | mgf-cloud is operator-run tooling, not a deployed service (no systemd unit / container image / deploy pipeline of its own). |
| **DOC** DOCUMENTATION | 19 | ✅ | DOC-01 root set + `docs/` tree; **DOC-08** PUBLIC_API regen + pins; **DOC-09** `mgf-common <verb>` → `mgf-fed <verb>` swept (STARTHERE/FEEDBACK); **DOC-15/CFM-03** this re-baseline. |
| **DP** DESIGN_PRINCIPLES | 13 | ✅ | Closed-box import-linter (3 contracts, all KEPT), mypy --strict, frozen pydantic models, lazy provider loading; DP-13 SSH client closed in `finally`. |
| **EH** ERROR_HANDLING | 13 | ✅ | Typed vocabulary onto `mgf.common.exceptions` (+ `CredentialsError`/`ProviderNotFoundError`, EH-08 attrs-before-super); **EH-01** `rates_from_config` raises `ConfigError`; **EH-04** CLI top-level routes untyped bugs to `report_now`; **EH-12** idempotent `create_volume`. |
| **FB** FEEDBACK | 1 | ✅ | FEEDBACK.md present + referenced. |
| **GUI** GUI_CONSUMERS | 10 | N/A | The PySide/Qt desktop-GUI rules; mgf-cloud's GUI is a server-rendered local web page, not a Qt app. |
| **LG** LOGGING | 17 | ✅ | **OB-01/LG-02/LG-06** `mgf.common.bootstrap` wired at both entry points (CLI `main`, web `serve`); per-module `get_logger`; **LG-11** INFO operation start/end with a stable `operation` field + `duration_ms` at the Infomaniak `_boundary` + `remote.run_commands`. |
| **NM** NAMING | 3 | ✅ | Hyphen slug + dotted namespace + PEP-420 (no `src/mgf/__init__.py`); NM-05: no `utils/misc/helpers` junk modules (every module domain-named). |
| **OB** OBSERVABILITY | 10 | ✅ / N/A | OB-01 logs pillar wired (above). Metrics/traces/SLO (OB-02..08) legitimately N/A — operator tooling, no page-able service surface. |
| **OP** OPERABILITY | 12 | ✅ | **OP-01** rich `version` (+`--json`: pkg + git SHA + python + platform + dep versions); **OP-02** `doctor` (offline install+config health, exit = failed-check count); **OP-05** `explain` (resolved CloudConfig + winning source, secrets redacted); **OP-07** `bundle` (redacted diagnostic tarball). OP-09..12 N/A (no service). |
| **PF** PERFORMANCE | 7 | N/A (leaning) | mgf-cloud's latency is dominated by remote OpenStack/SSH calls, not local CPU; no in-process hot path warrants a perf-baseline harness. PF-02 `perf` marker available via mgf-common. Not yet formally evidenced — the honest L3 gap. |
| **PKG** PACKAGE_DISTRIBUTION | 12 | ⏳ PKG-01 (§4) | Hatchling, `py.typed`, extras-gated SDKs; **PKG-06** pyproject index comment corrected to the actual devpi single-index. **PKG-01** = the devpi-vs-Codeberg channel reconciliation (fleet-infra, §4). |
| **PR** PRESENTATION_LAYER | 5 | ✅ / 🚫 | **PR-01** closed-box forbidden floor raised (typer/fire/rich/prompt_toolkit/qasync); **PR-04** new `independence` contract between `cli` and `web` (only the lazy launcher edge whitelisted); **PR-02** (dedicated `-app` repo) declined-with-rationale (§3); PR-06 N/A. |
| **REL** RELEASING | 13 | ✅ | **REL-03/REL-06** version coherence: `__version__`/wheel/PUBLIC_API.json all single-sourced from metadata, pinned push-time. Annotated tags; CI publish + post-publish verify (channel = PKG-01). |
| **SC** SECURITY_STANDARD | 18 | ✅ | `SecretStr` everywhere (never logged/repr'd); gitleaks; **SC-07** finite configurable `api_timeout` on the OpenStack Connection; **SC-17** `audit=true` structured records at the clean seams (`ssh.connect`/`disconnect`, `auth.ok`/`auth.fail`) carrying host/user/auth_url, never the secret; **SC-10** in-tree CVE triage. |
| **SP** SCOPE | 6 | ✅ | SCOPE.md (SP-01..06) authored; tight 3-dep core, SDKs/web split behind extras. |
| **TM** TIME | 6 | ✅ | UTC at boundaries (`datetime.now(UTC)` in cost/audit), ISO serialisation; resource ages computed from UTC creation times. |
| **TS** TESTING | 28 | ✅ | pytest matrix (3.11–3.13), markers, timeout, coverage floor; **TS-01** `tests/test_mirror.py` allow-list (now incl. the four new ops-verb modules); 137 tests green incl. the new ops-verb + version-sync pins. |
| **WF** WORKFLOWS | 13 | ⏳ WF-11 (§4) | Generated `.woodpecker.yml`; four-gate CI (ruff/mypy/lint-imports/pytest) + full-clone fix; WF-02 `ruff format --check` present. **WF-11** = CI install via frozen lock (fleet-infra, §4). |

**Tally:** of the 263 MUSTs, the applicable set for this shape is met **except
PKG-01 + WF-11** (both fleet-infra deferrals, §4). The DEP / GUI / most OB / PF
families are N/A-by-shape (operator tooling, not a deployed service or a Qt
desktop app).

---

## §3 Decline-with-rationale ledger (CFM-04)

| Rule | Decision | Rationale |
|---|---|---|
| **PR-02** | 🚫 declined | "2+ UI consumers → a dedicated `-app` repo." mgf-cloud bundles its CLI and its single local web GUI in one repo deliberately: they share the exact same provider-agnostic core, there is one maintainer + one release cadence, and the web GUI is an optional `[web]` extra (not a separate distributable product). PR-04's `independence` import-linter contract enforces that the two surfaces stay decoupled, so the spirit of PR-02 (no UI/UI coupling) is mechanically met without the repo split. Revisit if a third UI consumer appears. |

---

## §4 Open gaps — tracked with a plan (⏳)

Both remaining items are **fleet-infra, not mgf-cloud-owned defects** — they are
governed by the `mgf-standard` woodpecker template and the federation devpi
rollout, which a single sibling cannot change without breaking template-parity
(`mgf-fed drift-check`). Per non-adoption-is-valid, deferred-with-rationale.

| Rule | Standard | Status |
|---|---|---|
| **PKG-01** | PACKAGE_DISTRIBUTION | ⏳ **Fleet-governance.** The L1-binding PACKAGE_DISTRIBUTION.md still names Codeberg, while the woodpecker publish/verify (a generated, drift-checked artifact) was retargeted to the self-hosted devpi index during the federation B2 migration. Reconciling the channel — either bless devpi in the L1 doc or revert the template to Codeberg + regen the fleet — is a federation-wide decision tracked at mgf-standard. PKG-06 (the stale pyproject index comment) was the part mgf-cloud *does* own and is fixed. |
| **WF-11** | WORKFLOWS | ⏳ **Fleet-infra.** Wants CI to install from a hash-pinned `uv.lock` (`uv sync --frozen`) instead of range-resolving `pip install -e .[...]`. `.woodpecker.yml` is a generated, drift-checked template artifact; fleet-wide adoption is blocked by the devpi backfill gap (the full-graph fleet lock doesn't resolve). Tracked at mgf-standard as the WF-13 template uv-migration. |

---

## §SHOULD — the 8 indexed SHOULD rules

L3 requires every SHOULD met or justified. The corpus indexes **8** SHOULDs:

| Rule | Verdict | Evidence |
|---|---|---|
| **NM-04** | N/A | Operator-chosen local clone layout; never appears in an artifact. (mgf-cloud is in fact cloned to its slug.) |
| **NM-05** | ✅ | No junk-drawer modules: `find src/mgf/cloud -name '*.py'` yields zero `utils/misc/helpers/util.py`; every module is domain-named (`config`, `cost`, `models`, `remote`, `providers/*`, `cli/*`, `web/*`). |
| **OB-06** | N/A | SLI→SLO targets are for a deployed, page-able service. mgf-cloud is operator-run tooling with no SLO surface. |
| **PF-06** | N/A | "Document non-obvious public-API perf" — mgf-cloud's public surface is data models + thin provider methods whose cost is the remote API call, not local complexity worth annotating. |
| **PR-02** | 🚫 | Declined-with-rationale (§3) — single-repo CLI+web is deliberate; PR-04 enforces the decoupling. |
| **PR-06** | N/A | The optional "medium-agnostic `fmt` helpers" path is not exercised; output goes through the CLI `emit` helper + the web templates. |
| **TM-05** | ✅ | User-facing datetime display happens at presentation (the `cost` command renders `%Y-%m-%d %H:%M UTC`); core carries UTC-aware datetimes. |
| **TM-06** | N/A / justified | No OTel span emission of its own; audit/log timestamps follow the federation ISO-8601 log contract (logship → OpenObserve), deliberately not ns-epoch. |

**Result: 8/8 met / N-A / justified-or-declined.** The remaining L3 distance is the
full per-MUST `file:line` evidence audit + a verdict on the PF baseline family,
not an open SHOULD.

---

## §5 Audit log

| Date | Auditor | Trigger | Findings |
|---|---|---|---|
| 2026-06-25 | Item 1b-1 L3 depth-audit uplift (stages 1 + 2) | maintainer directive — uplift the high-stakes repos toward L3 against the mgf-common reference | **24 MUST + 7 lower-severity gaps found** (113-agent adversarial-refute workflow). **Closed 22/24 MUSTs in code** + the lower-severity batch: observability wiring (OB-01/LG-02/LG-06/LG-11/SC-17), version coherence (AP-13/REL-03/REL-06/OP-04), typed errors + guards (EH-01/EH-04/EH-12), SC-07 api_timeout, AP-10/AP-11/DOC-08 PUBLIC_API enumeration, PR-01/PR-04 import-linter, AP-01, TS-01, DOC-09, SC-10, PKG-06; **stage 2** shipped the **OP-01/OP-02/OP-05/OP-07** operability verbs (version/doctor/explain/bundle) + this ledger re-baseline (CFM-03/DOC-15). Gates green: ruff + mypy --strict + lint-imports + 137 tests. **Deferred: PKG-01 + WF-11** (fleet-infra, §4). Declared **L2 on every owned surface** (target L3). |
| 2026-06-14 | Pass-1 scaffold | new sibling bootstrap | Structural baseline met; per-MUST audit deferred to "Pass 7". Declared L1. (Superseded — the deferred surface has since shipped; this 2026-06-25 re-audit replaces the v0.1.0-frozen scaffold and its false N/As.) |

---

## §6 Cross-references

- [`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) — the corpus this audits against (263 MUSTs / 8 SHOULDs).
- [`PUBLIC_API.md`](../../PUBLIC_API.md) / [`PUBLIC_API.json`](../../PUBLIC_API.json) — the audited public surface (AP-10/DOC-08).
- [`.importlinter`](../../.importlinter) — the DP-01 / PR-01 / PR-04 closed-box + independence contracts.
- [`../../FEEDBACK.md`](../../FEEDBACK.md) — feedback filed against this sibling.
- The mgf-common reference ledger: [`mgf-common/docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).

---

## §Z Per-MUST evidenced audit (the gap-closing rules — `file:line`)

> This re-audit evidences the rules the 1b-1 workflow flagged + the load-bearing
> ones it touched (the families above are family-level verdicts). A full
> 263-row `file:line` audit is the remaining L3 step (§1).

### ERROR_HANDLING

| Rule | Status | Evidence | Notes |
|---|---|---|---|
| EH-01 | ✅ | `src/mgf/cloud/cost.py` `rates_from_config` raises `ConfigError` (not bare `FileNotFoundError`) on a missing explicit path | Typed; `tests/unit/test_cost.py` asserts the typed error. |
| EH-04 | ✅ | `src/mgf/cloud/cli/_app.py:main` final `except Exception` → `report_now(exc, source="mgf.cloud.cli")` + actionable message | Untyped bugs route to a crash report, not a raw traceback. |
| EH-12 | ✅ | `infomaniak.py create_volume` find-volume guard → `ResourceAlreadyExistsError`; mirrored in `FakeProvider.create_volume` | Idempotent — a retry can't leak a duplicate billable volume. |

### LOGGING / OBSERVABILITY / SECURITY (the credential-seam wiring)

| Rule | Status | Evidence | Notes |
|---|---|---|---|
| OB-01 / LG-02 / LG-06 | ✅ | `cli/_app.py:main` + `web/_app.py:serve` wrap dispatch in `mgf.common.bootstrap(app_name="mgf-cloud", ...)`; per-module `get_logger(__name__)` | Single wiring point per entry; rotating JSON file sink + console (text on TTY / JSON off). |
| LG-11 | ✅ | INFO operation start/end with a stable `operation` field + `duration_ms` at the Infomaniak `_boundary` and `remote.run_commands` (verb split from the id-bearing detail) | The `operation` value is the stable verb, not the raw f-string. |
| SC-07 | ✅ | `infomaniak._build_connection` passes a finite, configurable `api_timeout` (default 30s) to `openstack.connect(...)` | Per-call REST reads can't block forever; `RequestTimeout` maps via `_boundary`. |
| SC-17 | ✅ | `audit=true` INFO records at `ssh.connect`/`ssh.disconnect` (`remote.py`) and `auth.ok`/`auth.fail` (`infomaniak`) carrying host/user/auth_url — never the `SecretStr` | One unit test per event. |

### API / RELEASING (version coherence)

| Rule | Status | Evidence | Notes |
|---|---|---|---|
| AP-13 / REL-03 / REL-06 | ✅ | `src/mgf/cloud/__init__.py` `__version__ = importlib.metadata.version("mgf-cloud")`; `tests/unit/test_version_in_sync.py` pins it to pyproject on every push | No frozen literal; wheel/tag/`__version__`/PUBLIC_API.json can't drift. |
| AP-10 / AP-11 / DOC-08 | ✅ | `PUBLIC_API.md` enumerates all 24 `__all__` names (Tier + Since); `tests/unit/test_public_api_pin.py` pins md↔`__all__`↔json | RA-10 second pin closed. |
| AP-01 | ✅ | `cost.py` declares `__all__` | Every non-underscore module now declares one. |

### OPERABILITY (the stage-2 verbs)

| Rule | Status | Evidence | Notes |
|---|---|---|---|
| OP-01 | ✅ | `cli/_version.py` `version_facts()`/`render_version()` — version (single-sourced) + git SHA + python + platform + dep versions; `--json` shape | `tests/unit/test_ops_verbs.py::test_version_*`. |
| OP-02 | ✅ | `cli/_doctor.py` `run_doctor` — offline checks (providers, provider-SDK extra, credentials resolve+parse, rates parse) via `mgf.common.doctor.DoctorBundle`; exit = failed-check count | Distinct from the live `provider check`. `test_doctor_*`. |
| OP-05 | ✅ | `cli/_explain.py` `run_explain` — resolved CloudConfig + which source won; secrets stay `SecretStr` (`**********`), never `get_secret_value()` | `test_explain_reports_source_and_redacts` asserts the secret never leaks. |
| OP-07 | ✅ | `cli/_bundle.py` `run_bundle` — one redacted `.tar.gz` (version + explain + doctor + log tail + crash reports), every text section through `Redactor`, per-section fail-open | `test_bundle_writes_redacted_tarball`. |

### PRESENTATION_LAYER (import contracts)

| Rule | Status | Evidence | Notes |
|---|---|---|---|
| PR-01 | ✅ | `.importlinter` closed-box `forbidden_modules` raised to include typer/fire/rich/prompt_toolkit/qasync; core-light surface extended (cost/defaults/providers.fake) | `lint-imports`: 3 contracts KEPT. |
| PR-04 | ✅ | `.importlinter` `independence` contract between `mgf.cloud.cli` and `mgf.cloud.web`, whitelisting only `cli._app -> web` (the lazy launcher) | Mechanically enforced in CI. |
