# Standards compliance — rolling audit record

> **Status:** v1.1 (2026-05-15, second pass). Pass B added a
> sharpened "do the standards earn their weight?" lens:
> 115 lines of consumer-tracker bloat cut from 3 docs
> (ERROR_HANDLING §11, CONFIGURATION §14, LOGGING §15);
> 5 wording/markdown fixes; 4 stale cross-refs cleaned.
> No rules cut or merged — all 148 MUST/SHOULD earned their
> place. Full Pass B record in
> `docs/inprogress/STANDARDS_AUDIT_2026-05-15B.md`.
>
> **Status:** v1.0 (2026-05-15). First full pass on all 14
> standards docs. Updated when the maintainer (or AI agent
> acting as maintainer) re-audits a standard against the code
> base. Format: one section per standard, rolling findings +
> "as of <date>" status.
>
> **Audience:** Maintainer, AI agents, downstream consumers
> verifying mgf-common's own compliance against the standards
> it publishes.
>
> **Origin:** Created at the closeout of the 2026-05-15
> 14-doc standards audit (full record in
> `docs/inprogress/STANDARDS_AUDIT_2026-05-15.md`, scheduled
> for archive per **DOC-11**).

---

## §1 Headline

**Every standards doc has been verified against the live code
base as of 2026-05-15.** **Five** docs surfaced fixes; **nine**
were clean. Two of the five fixes were substantive code
changes (perf-deselect bug in `pyproject.toml`, LG-15/16
retrofit in `crash_reporter.py`); the rest were doc-only
corrections (missing index entries, stale wording, missing
bucket READMEs, false IN-scope claims).

| Doc | Pass | Fixes shipped during audit |
|---|---|---|
| README.md (master index) | ✅ | Index of MUSTs +39 missing rules added; LG-06 / LG-11 / AP-12 wording fixed |
| SCOPE.md | ✅ | 2 false IN-scope claims (SSH wrapper, resilience utilities) → moved to §3 Adjacent |
| DOCUMENTATION.md | ✅ | 6 missing bucket READMEs shipped; DOC-09 format clarified to accept docstring-line + hash-comment shapes |
| DESIGN_PRINCIPLES.md | ✅ | No fixes — all DP-* mechanical checks pass |
| LOGGING.md | ✅ | 8 crash_reporter WARN sites retrofitted to LG-15/16 (event= + structured extras); 6 new events catalogued in EVENTS.md; RA-30 created for ~9 remaining sites |
| ERROR_HANDLING.md | ✅ | No fixes — all EH-* checks pass |
| CONFIGURATION.md | ✅ | No fixes — all CF-* checks pass |
| SECURITY_STANDARD.md | ✅ | No fixes — all SC-* checks pass (everything already retrofitted in the v2.2 review arc) |
| TESTING.md | ✅ | **Substantive:** perf-deselect bug fixed (perf tests were running on every PR despite the design); TS-19 wording corrected (layer markers vs orthogonal markers); `slow` marker registered defensively |
| API_DESIGN.md | ✅ | No fixes — all AP-* checks pass |
| WORKFLOWS.md | ✅ | No fixes — all WF-* visible in `.woodpecker.yml` |
| WORKFLOWS_PATTERNS.md | ✅ | No fixes — recipes match the live yaml line-for-line |
| RELEASING.md | ✅ | No fixes — all REL-* checks pass |
| COMMON_COMPONENTS.md | ✅ | No fixes — every catalogued component verified shipping |

**Aggregate:** 14/14 docs verified. The standards faithfully
describe the library's actual posture as of v0.33.0.

---

## §2 Per-doc compliance

### §2.1 README.md (master index)

- ✅ File-map covers all 14 docs.
- ✅ Reading-order table covers every common scenario.
- ✅ Conformance keywords + levels defined.
- ✅ Index of MUSTs now complete (148 entries — covers DP / EH / LG / CF / SC / TS / AP / WF / REL / SP / DOC) after audit-time refresh.
- ✅ Per-version release notes (v2.0 → v2.4) accurate.
- **Maintenance discipline added:** when a Rules box in any topic doc changes, the index MUST be updated in the same commit (same shape as DOC-04 for CHANGELOG).

### §2.2 SCOPE.md

- ✅ SP-01 IN list — verified after fix (SSH + resilience moved to Adjacent).
- ✅ SP-02 OUT list — every entry carries an ecosystem alternative citation.
- ✅ SP-03 PR-review question codified.
- ✅ SP-04 Adjacent items carry promotion criteria.
- ✅ SP-06 revisit cadence pinned to MAJOR boundaries.
- **Code findings parked for separate cleanup:** `src/mgf/common/db/`, `/django/`, `/alembic/` are empty namespace dirs from the federation extractions (RA-31 created during the LOGGING audit).

### §2.3 DOCUMENTATION.md

- ✅ DOC-01 7 root-level docs + PUBLIC_API.json all present.
- ✅ DOC-02 6 canonical buckets all present.
- ✅ DOC-03 every long-lived bucket now has a README charter (6 shipped during audit: inprogress / cutover / design / internal / ops / release).
- ✅ DOC-05 12 cutover guides v0.22 → v0.33.
- ✅ DOC-06 3 trackers all in §1..§6 canonical shape.
- ✅ DOC-07 `docs/claude/CLAUDE.md` in dense-lookup format.
- ✅ DOC-08 PUBLIC_API.md + .json + drift test.
- ✅ DOC-09 every public module's docstring carries a `See:` line (the library's preferred form; the hash-comment form is also valid per the audit's wording fix).

### §2.4 DESIGN_PRINCIPLES.md

| Rule | Check | Status |
|---|---|---|
| DP-01 layering | `.importlinter` contract | ✅ |
| DP-03 frozen domains | `frozen=True` at 5+ sites | ✅ |
| DP-04 mypy --strict | 69 source files clean | ✅ |
| DP-09 cancellation token | `CancellationToken` + asyncio variant | ✅ |
| DP-11 task lifecycle | no bare `asyncio.create_task` in core | ✅ |
| DP-12 UTC time | no `datetime.now()` in real code | ✅ |
| DP-13 deterministic release | zero `__del__` — context managers throughout | ✅ |

### §2.5 LOGGING.md

| Rule | Check | Status |
|---|---|---|
| LG-01 logger acquisition | no bare `logging.info` | ✅ |
| LG-04 redaction depth cap | `_MAX_REDACT_DEPTH = 64` (SH-03) | ✅ |
| LG-08 lazy %-formatting | no f-strings in LOG calls | ✅ |
| LG-12 perf gate | `tests/perf/test_perf_pins.py::TestFileSinkLoggingPerf` — baseline-relative (PF-01), `@pytest.mark.perf` | ✅ |
| LG-15 typed events | 15 stable event names emitted (9 pre-audit + 6 new `crash.*` from this audit); all catalogued in `docs/reference/EVENTS.md` | ✅ |
| LG-16 message content | crash_reporter retrofitted (8 sites); RA-30 for ~9 remaining | ✅ |

### §2.6 ERROR_HANDLING.md

All EH-01 / EH-04 / EH-05 / EH-07 / EH-08 mechanically verified. EH-09 (user-facing actionable hints) is correctly scoped — applies to consumers, not to mgf-common's library-level typed exceptions. Resilience-pattern utilities (EH-11..13 implementations) are §3 Adjacent per SCOPE.md.

### §2.7 CONFIGURATION.md

All CF-01..CF-12 mechanically verified:
- BaseAppSettings + MgfSettings shape ✅
- Schema versioning with CURRENT_VERSION ✅
- Atomic write via `mgf.common._io.atomic_write` (RA-01) ✅
- Vault three-backend pattern ✅
- `extra="forbid"` everywhere ✅
- Discriminated union for vault config ✅

### §2.8 SECURITY_STANDARD.md

All SC-01..SC-18 mechanically verified:
- No `shell=True`, no `yaml.load`, no `pickle`, no `verify=False` in real code
- pip-audit + gitleaks + cyclonedx-py SBOM all wired in CI
- root SECURITY.md present
- SH-01 / SH-03 / SH-06 / SH-08 hardening surfaced in §9 (v2.2 arc)

### §2.9 TESTING.md

**Substantive audit findings + fixes:**

1. **Perf-deselect bug fixed.** pyproject's `perf` marker description claimed nightly-sweep exclusion but the `addopts` didn't actually deselect. Default `pytest tests/` was running all 4 perf tests on every PR. Fixed: added `-m "not perf and not slow"` to `addopts`. Verified: 1411 in default, 4 selectable via `-m perf`.
2. **TS-19 wording corrected.** The canonical-marker list now distinguishes (a) layer markers (`smoke`/`e2e`/`integration`, `unit/` unmarked default) from (b) orthogonal markers (`perf` for RA-11, `slow` for TS-18 — registered defensively).

All other TS-* mechanical checks pass.

**Open follow-up (NOT a violation, just missing infrastructure):** no nightly CI cron running `pytest -m perf`. The perf-pin budgets exist but don't gate anything until a nightly job runs them. Surface as a follow-up RA-* or PC-* item if the maintainer wants it tracked.

### §2.10 API_DESIGN.md

All AP-01 / AP-08 / AP-09 / AP-10 / AP-13 / AP-14 mechanically verified. `__all__` declared at every public-module boundary; `py.typed` ships; `__version__` synced with pyproject.

### §2.11 WORKFLOWS.md

All WF-* visible in `.woodpecker.yml`. Extended-gate trio (vuln-scan / secret-scan / sbom) live as designed by §2.4 (v2.2 arc).

### §2.12 WORKFLOWS_PATTERNS.md

All paste-ready recipes match the live `.woodpecker.yml` line-for-line. Image pins match (`zricethezav/gitleaks:v8.30.1`, `python:3.12-slim`).

### §2.13 RELEASING.md

All REL-* mechanically verified. Tags exist for v0.22.0 → v0.33.0; PUBLIC_API.md banner present; SBOM emission (§2.3) live in CI; pre-release smoke step in CI matches REL-08.

### §2.14 COMMON_COMPONENTS.md

Every catalogued component verified shipping:

| § | Component | Shipping at |
|---|---|---|
| §10 | Vault (env/keyring/file backends) | `vault/_env_vault.py`, `_keyring_vault.py`, `_file_vault.py` |
| §11 | Crash reporter | `observability/crash_reporter.py` |
| §12 | OTel setup | `observability/otel_setup.py` |
| §14 | Redactor (SH-03 depth cap + cycle guard) | `observability/redaction.py:133` + `:310` |
| §17 | atomic_write helper | `_io.py:35` |

---

## §3 Open follow-ups (surfaced by this audit)

These are not violations of any current standard — they're
infrastructure additions or code-cleanup tasks the audit
identified. Each is tracked in the relevant living tracker:

| # | Item | Tracker | Effort |
|---|---|---|---|
| 1 | LG-15/16 retrofit for the ~9 remaining WARN/ERROR sites outside crash_reporter (otel_setup / logging_setup / versioned / process / cli) | RA-30 in `RELIABILITY_AND_ACCURACY.md` | S |
| 2 | Empty federation-extraction namespace dirs (`db/`, `django/`, `alembic/`) — stale `__pycache__/` from v0.30/v0.31 extractions | RA-31 in `RELIABILITY_AND_ACCURACY.md` | S |
| 3 | ~~Nightly CI cron running `pytest -m perf`~~ | ✅ closed 2026-05-15: `.woodpecker.yml` `perf-nightly` step + `event: cron` accepted at top-level. Schedule configured platform-side (Codeberg → Settings → Crons). TESTING.md §8.4 now carries the reference shape. | S |

---

## §4 Cadence

This file is updated:

- **After every full audit pass** (next one: at MAJOR-version boundary per SP-06, or when a substantive rule revision lands).
- **When a finding lands a code fix** that resolves a previously-recorded gap (mark closed; cross-reference the commit).
- **When a new standard is added** (next row in §1 + new §2.X section).

The discipline mirrors the FEEDBACK lifecycle (`OPEN` → closed by code+commit). Without this cadence, the "AS-IS in mgf-common" claims in topic docs drift silently.

---

## §5 Cross-references

- [`docs/inprogress/STANDARDS_AUDIT_2026-05-15.md`](inprogress/STANDARDS_AUDIT_2026-05-15.md) — the full audit record + per-doc finding details. Scheduled for archive per **DOC-11** after this compliance doc lands.
- `mgf-fed standards README` — the master index + Index of MUSTs (148 rules across 11 source docs).
- `mgf-fed standards DOCUMENTATION` — the docs-discipline standard this compliance doc was created to satisfy (DOC-09 drift-detection cadence).
