# Standards audit pass — 2026-05-15

> **Status:** ✅ **closed 2026-05-15.** All 14 docs audited;
> findings rolled up into [`docs/STANDARDS_COMPLIANCE.md`](../STANDARDS_COMPLIANCE.md).
> This tracker stays in `docs/inprogress/` until next release
> cycle (per **DOC-11**), then moves to `docs/archive/2026/`.
>
> One-time deep audit covering all 14 docs in
> `docs/standards/`. Each doc was verified against the
> library's actual code; standards updated where wrong /
> excessive / missing context; code updated where the standard
> was right and code had drifted.
>
> **Author's framing** (from the maintainer): *"This library
> owns the Magogi foundation standard and can modify it for
> the best."* The audit treats every standard as **mutable** —
> a rule that doesn't earn its place in code is a rule that
> should be relaxed or cut.
>
> **Audience:** session-continuation context for AI agents +
> human reviewers. After closeout, the rolling findings move
> to `docs/STANDARDS_COMPLIANCE.md`.

---

## §1 Methodology

For each of the 14 docs:

1. **Read** the doc end-to-end (Rules box + body + AS-IS).
2. **Verify** each MUST against the codebase. The check is
   one of:
   - **Mechanical** — a grep / lint / test pin that proves
     the rule holds. Pass = ✅.
   - **Code-walk** — read the named modules; confirm the rule
     is followed in practice. Pass = ✅.
   - **Sampling** — for rules with many sites, sample 3–5
     representative call sites. Pass = ✅ with a noted sample.
3. **Classify** each finding into one of:
   - **Standard is right, code follows it.** → No action; mark
     ✅ in this tracker.
   - **Standard is right, code drifted.** → Fix code. Commit
     with the rule ID in the message.
   - **Standard is wrong / excessive / missing context.** →
     Update the standard. Commit with rationale.
   - **Standard names a non-existent component.** → Either ship
     the component OR remove the claim from the standard. Pick
     whichever serves the library better.
4. **Record** in §3 below (one row per doc).
5. **Commit + push** at the end of each doc's audit.

The discipline: **a rule the code doesn't follow is either a
defect in the code OR a defect in the rule**. The audit
forces the choice. No "we should follow this someday."

## §2 Scope

In scope (this audit):

- All 14 docs in `docs/standards/`:
  - `README.md` (master index)
  - `DESIGN_PRINCIPLES.md`
  - `ERROR_HANDLING.md`
  - `LOGGING.md`
  - `CONFIGURATION.md`
  - `SECURITY_STANDARD.md`
  - `TESTING.md`
  - `API_DESIGN.md`
  - `WORKFLOWS.md`
  - `WORKFLOWS_PATTERNS.md`
  - `RELEASING.md`
  - `SCOPE.md`
  - `COMMON_COMPONENTS.md`
  - `DOCUMENTATION.md`

Out of scope:

- Tracker docs in `docs/inprogress/` (those are workspaces,
  not standards).
- Reference docs in `docs/reference/` (those describe surface,
  not rules).
- Recipes in `docs/recipes/` (those describe HOW, not WHAT
  good looks like).
- Code-only changes unrelated to a standard rule (those go
  through their own RA/SH/PC trackers).

## §3 Per-doc progress

| # | Doc | Status | Commit(s) | Findings |
|---|---|---|---|---|
| 1 | README.md | ✅ closed | (this commit) | Index of MUSTs ~40 rules stale; 3 wording fixes |
| 2 | SCOPE.md | ✅ closed | (this commit) | 2 false IN claims (SSH, resilience utilities); moved to Adjacent |
| 3 | DOCUMENTATION.md | ✅ closed | (this commit) | 6 missing bucket READMEs shipped; DOC-09 format clarified |
| 4 | DESIGN_PRINCIPLES.md | ✅ closed | (this commit) | All DP-* mechanical checks pass; no findings |
| 5 | LOGGING.md | ✅ closed | (this commit) | crash_reporter LG-15/16 retrofit (8 sites); RA-30 created for remaining ~9 |
| 6 | ERROR_HANDLING.md | ✅ closed | (this commit) | All EH-* mechanical checks pass; no findings |
| 7 | CONFIGURATION.md | ✅ closed | (this commit) | All CF-* mechanical checks pass; no findings |
| 8 | SECURITY_STANDARD.md | ✅ closed | (this commit) | All SC-* mechanical checks pass; no findings |
| 9 | TESTING.md | ✅ closed | (this commit) | TS-19 wording fix; perf-deselect bug fix; slow marker registered |
| 10 | API_DESIGN.md | ✅ closed | (this commit) | All AP-* mechanical checks pass; no findings |
| 11 | WORKFLOWS.md | ✅ closed | (this commit) | All WF-* mechanical checks pass; no findings |
| 12 | WORKFLOWS_PATTERNS.md | ✅ closed | (this commit) | All paste-ready recipes match the live .woodpecker.yml |
| 13 | RELEASING.md | ✅ closed | (this commit) | All REL-* mechanical checks pass; no findings |
| 14 | COMMON_COMPONENTS.md | ✅ closed | (this commit) | All components in §10..§17 verified shipping; no findings |

## §4 Findings (rolling)

> Each per-doc entry appended here as the audit progresses.
> When closed out, the entries are summarised into
> `docs/STANDARDS_COMPLIANCE.md` (which becomes the rolling
> compliance record). This file then moves to
> `docs/archive/2026/` per **DOC-11**.

### README.md (master index) — closed

**Verdict:** structurally sound; index-of-MUSTs section was the
drift surface predicted by RA-18 (doc:code drift after additions
to topic docs). Fixed in this commit.

**Fixes landed:**

1. **Index of MUSTs — appended 39 missing rules.** The index had
   not been refreshed since the v2.0 introduction of three new
   doc topics. Added: LG-15 / LG-16 / LG-17 (v2.4); TS-19 /
   TS-20 / TS-21 (v2.0 layer markers); WF-01..WF-12 (12 rules,
   never indexed); REL-01..REL-09 (9 rules, never indexed);
   DOC-01..DOC-12 (12 rules, v2.3). Total index entries went
   from ~108 to ~148 — now matches the actual cross-doc count.
2. **LG-11 text fix.** Index said "SHOULD be logged"; actual
   rule is now MUST (promoted in v2.4 with the ≥100 ms /
   boundary-crossing threshold). Updated to match the source.
3. **LG-06 text fix.** Index said "A rotating file sink MUST be
   configured by default"; the actual rule was revised in
   v0.18.0 (closing FEEDBACK LOG-01) to allow cloud-native
   shapes (stdout capture / remote sink) as alternatives. Index
   now reflects the revised text.
4. **AP-12 typo fix.** "documented inwith" → "documented with".
5. **New maintenance note above the Index** pointing at the
   DOC-04 same-commit shape — when a topic doc's Rules box
   changes, the master index updates in the same commit. The
   drift surface is real (RA-18 closure already named this for
   per-module docstrings); the note generalises the discipline
   to the master index.

**Open items (deferred to audit closeout):**

- The README files (this one + `docs/claude/CLAUDE.md`)
  reference `docs/STANDARDS_COMPLIANCE.md` as if it exists; it
  doesn't yet. That file is the natural output of THIS audit
  — it lands at closeout (task #73). No fix here.

**Findings about the standards themselves (not just drift):**

- None. The README is a meta-doc; the rules it indexes live in
  the topic docs. Substantive rule revisions (if any) will
  surface in the per-doc audits below.

### SCOPE.md (SP-01..SP-06) — closed

**Verdict:** the SP-* rules themselves are sound (every PR
clears them; the IN/OUT/Adjacent discipline is followed in
practice). The **IN-scope list itself** carried two false
claims — items listed as shipped but never landed in core.

**Fixes landed:**

1. **"Subprocess + SSH + service-management"** wording was
   ambiguous and partially false. Split into two honest
   bullets: (a) `mgf.common.process.run` (subprocess wrapper —
   ships, verified) + `mgf.common.process.Service` (service
   lifecycle orchestration — ships, verified); (b) the
   explicit non-claim that `Service` is NOT a systemd-style
   supervisor. SSH wrapper does NOT ship in mgf-common core
   (verified by `grep -r paramiko/SSHClient src/` → zero hits)
   — moved to §3 Adjacent with the promotion criterion ("≥2
   consumers need it"; VManager's
   `src/vmanager/common/ssh.py` is the reference shape).
2. **"Resilience patterns — retry with jitter, circuit breaker,
   bulkhead"** falsely implied utility implementations ship in
   `mgf.common`. Verified — no `mgf.common.resilience`,
   `retry_with_backoff`, `CircuitBreaker`, or `Bulkhead`
   exists. The STANDARDS exist (EH-11 / EH-12 / EH-13 in
   ERROR_HANDLING.md); consumers implement them in their own
   code today. Updated IN-scope wording to distinguish
   "standards shipped" from "utilities shipped"; added a
   §3 Adjacent entry for the utility implementations with the
   "≥2 consumers ship near-identical copies" promotion
   criterion.

**Code findings (incidental, surfaced by the audit, parked
for a separate cleanup):**

- `src/mgf/common/db/`, `src/mgf/common/django/`,
  `src/mgf/common/alembic/` directories exist but contain
  ZERO `.py` files — only stale `__pycache__/` from the
  federation extractions (v0.30 mgf-sqlalchemy / mgf-alembic,
  v0.31 mgf-django). They're not import-targets; they're
  artefacts. **Action:** add to a future RA-* item (cleanup
  cadence at MAJOR boundaries per SP-06); not in scope for the
  SCOPE audit itself.

### DOCUMENTATION.md (DOC-01..DOC-12) — closed

**Verdict:** mostly compliant. Mechanical audit:

- ✅ **DOC-01** — all 8 root docs present (`README.md`,
  `STARTHERE.md`, `CHANGELOG.md`, `CONTRIBUTING.md`,
  `FEEDBACK.md`, `PUBLIC_API.md`, `PUBLIC_API.json`,
  `SECURITY.md`).
- ✅ **DOC-02** — six canonical buckets all present.
- ❌ **DOC-03** — 6 buckets missing READMEs (inprogress /
  cutover / design / internal / ops / release). **Fixed in
  commit `771d335`** (all 6 charter READMEs shipped).
- ✅ **DOC-05** — 12 cutover guides exist (`v0.22.0` → `v0.33.0`).
- ✅ **DOC-06** — all 3 trackers follow the canonical §1..§6
  shape (verified via `grep -E "^## §[1-6]"`).
- ✅ **DOC-07** — `docs/claude/CLAUDE.md` dense-lookup ships.
- ✅ **DOC-08** — `PUBLIC_API.md` + `.json` both ship;
  `tests/unit/test_public_api_doc.py` pins the drift.
- ⚠️ **DOC-09 format mismatch** — standard's wording said the
  back-reference shape was `# See: docs/reference/XX.md` (hash
  comment); library actually uses `See: docs/reference/XX.md`
  *inside the module docstring*. Both forms satisfy the
  rule's intent. **Fixed** — DOC-09 + §10 drift-table + §14
  enforcement matrix + §15 AS-IS claim all now name BOTH
  forms as valid.

### DESIGN_PRINCIPLES.md (DP-01..DP-13) — closed

**Verdict:** clean. All mechanically-checkable DP-* rules
pass. No findings; no fixes needed.

**Checks run:**

| Rule | Check | Result |
|---|---|---|
| DP-01 layering | `.importlinter` contract present | ✅ |
| DP-03 frozen domain types | `grep -rln frozen=True` finds 5+ sites incl. `versioned/_store.py`, `process/_run.py`, `observability/redaction.py` | ✅ |
| DP-04 mypy --strict | `python -m mypy --strict src/mgf` | ✅ "no issues found in 69 source files" |
| DP-08 layering enforcement | `.importlinter` ships + CI runs `lint-imports` | ✅ |
| DP-09 explicit cancellation | `CancellationToken` in `mgf.common.progress` + asyncio variant | ✅ |
| DP-11 task lifecycle ownership | `grep -rln "asyncio.create_task" src/mgf/` → only `cli/_init_project.py` (project template; not core code) | ✅ |
| DP-12 UTC time | `grep -rn "datetime\\.now()" src/mgf/` → hits only in `_init_project.py` (quoted rule text) + `_doctor_standards.py` (the linter that enforces the rule) — true code uses `datetime.now(UTC)` | ✅ |
| DP-13 deterministic release | `grep -rn "__del__" src/mgf/common/` → zero — context-manager / try/finally throughout | ✅ |

The §1.5 first-class-concerns section was updated to current
shape in the v2.2 review arc (added perf-pin discipline +
RA-22 best-effort-in-committed-region pattern); the §6
performance-budgets section gained TS-14 cross-ref and the
PERFORMANCE_AND_CAPACITY tracker recommendation. No further
changes warranted.

### LOGGING.md (LG-01..LG-17) — closed

**Verdict:** the standards themselves are correct (just
codified in v2.4); the code has measurable LG-15/16 drift
because those rules postdate most of the WARN/ERROR sites.

**Checks run:**

| Rule | Check | Result |
|---|---|---|
| LG-01 logger acquisition | `grep -rn "^logging\\.(info\|warning\|error)"` in src/mgf/ | ✅ zero bare-`logging` calls |
| LG-08 lazy %-formatting | `grep -rEn 'LOG\\.(...) \\(\\s*f"'` | ✅ zero f-strings in LOG calls |
| LG-12 perf gate | `tests/unit/test_logging_perf.py` exists with `@pytest.mark.perf` | ✅ test registered + nightly-sweep-eligible |
| LG-04 redaction depth cap | `_MAX_REDACT_DEPTH = 64` at `redaction.py:133` (SH-03) | ✅ |
| LG-15 typed events | 8 distinct event names already emitted: `vault.{read,write,delete}` + `bootstrap.replace` + `bootstrap.runtime_snapshot_failed` + `reload.unrecoverable` + `crash.redaction_failed` + `process.{reap_timeout,streamer_read_failure}` | ✅ existing emitters compliant |
| LG-15/16 drift in crash_reporter | 8 `_LOG.warning(...)` sites without `event=` | **Fixed in this commit** |
| LG-15/16 drift elsewhere | ~9 sites in `otel_setup`, `logging_setup`, `versioned/_store`, `process/_run`, `cli/_handler` | **RA-30 created** to track the retrofit |

**Fixes landed (crash_reporter.py):**

8 WARN sites upgraded to LG-15 + LG-16 compliance:

| Line | New event name | Required fields |
|---|---|---|
| `:83` | `crash.build_failed` | `error_type`, `error_message` |
| `:95` | `crash.write_failed` | `error_type`, `error_message` |
| `:415` | `crash.sink_unknown` (settings path) | `sink_name`, `hint` |
| `:427` | `crash.sink_failed` | `sink_name`, `error_type`, `error_message` |
| `:440` | `crash.ship_failed` (HTTP-URL path) | `sink_kind="http"`, `error_type`, `error_message` |
| `:444` | `crash.sink_unknown` (env-var path) | `sink_name`, `env_var`, `hint` |
| `:449` | `crash.ship_failed` (named-sink path) | `sink_name`, `error_type`, `error_message` |
| `:479` | `crash.sink_unavailable` (sentry) | `sink_name="sentry"`, `missing_dependency`, `hint` |
| `:502` | `crash.sink_unavailable` (otlp) | `sink_name="otlp"`, `missing_dependency`, `hint` |

6 new events registered in `docs/reference/EVENTS.md` with the
canonical row shape (Level / Audit / Required fields /
Optional fields / Emitted-by-file:line / What it means / What
to do). The "what to do" column carries actionable
remediation per LG-16 HOW discipline.

All 1415 tests pass; mypy --strict clean on the modified file.

**Open items deferred:**

- **RA-30** — LG-15/16 retrofit for the remaining ~9 sites
  outside crash_reporter (otel_setup / logging_setup /
  versioned-store / process-run / cli-handler). Effort: S.
- The standards themselves required no edits — LG-* rules are
  correct as-shipped in v2.4.

### ERROR_HANDLING.md (EH-01..EH-13) — closed

**Verdict:** clean. All mechanically-checkable EH-* rules
pass. The just-updated §6.3 hardening + §7 best-effort-in-
committed-region (v2.2 arc) stand.

**Checks run:**

| Rule | Check | Result |
|---|---|---|
| EH-01 subclass base | `grep "class .*Error(Exception)"` in src/mgf/ excluding the AppError definition itself | ✅ zero direct-Exception subclasses in core |
| EH-04 top-level handlers | `excepthook.py` + `threading_excepthook.py` both ship under `observability/` | ✅ |
| EH-05 never-raises | `test_crash_reporter.py` has `never_raises` + `fail_safe` tests; all pass | ✅ |
| EH-08 typed fields | `SchemaValidationError.errors`, `CommandError.argv/returncode/stderr`, `ResourceNotFoundError.name` — all visible in `exceptions/_well_known.py` | ✅ |
| EH-07 narrow `except Exception` | 26 sites total; sampled — all in legitimate carve-out positions (best-effort observers per EH-10, translation seams per EH-02, cleanup paths, EH-05 never-raises) | ✅ |
| EH-11..13 resilience utilities | Standards exist; utility implementations are §3 Adjacent per SCOPE.md (and the SCOPE audit just clarified this) | ✅ alignment |

**Soft finding (not a violation, recorded for clarity):**

- **EH-09** (user-facing actionable hints + substring pin
  test) does NOT apply to mgf-common's OWN typed exceptions —
  they're library-level types that get translated at the
  consumer's CLI / UI boundary, NOT shown to end-users
  directly. Verified: `grep "rerun\|set \\w+="` in
  `exceptions/_well_known.py` → zero hits. No actionable hints
  embedded; therefore no pin test needed. EH-09 still applies
  to *consumers* (VManager-style applications) — the rule's
  scope is correct as-written.

**Standards themselves required no edits.** §6 (crash reporter
template) was substantially expanded in the v2.2 review arc to
surface SH-01 / SH-03 / SH-06 hardening; §7 gained the
committed-state-region best-effort pattern (RA-22). Both
sections reflect current code.

### CONFIGURATION.md (CF-01..CF-12) — closed

**Verdict:** clean. All mechanically-checkable CF-* rules
pass. §9 + §10 were updated in the v2.2 review arc to surface
`mgf.common._io.atomic_write` (RA-01) + `platform_dir` (RA-29);
both reflect current code.

**Checks run:**

| Rule | Check | Result |
|---|---|---|
| CF-01 typed Settings | `BaseAppSettings(BaseSettings)` at `config/_settings.py:120` + `MgfSettings(BaseAppSettings)` at `settings.py:465` | ✅ |
| CF-03 schema versioning | `CURRENT_VERSION: ClassVar[int]` + `version: int` + version-check validator that rejects `v > CURRENT_VERSION` | ✅ |
| CF-04 atomic write | `config/_loader.py:221` delegates to `mgf.common._io.atomic_write(target, text, mode=0o600, fsync_dir=True)` per RA-01 | ✅ |
| CF-05 secrets via Vault | `vault/__init__.py` ships `EnvVault` + `KeyringVault` + `EncryptedFileVault` | ✅ |
| CF-06 unknown-key reject | `extra="forbid"` on every Settings subclass | ✅ |
| CF-08 Settings injection | `_GLOBAL_CONTEXT` set by `bootstrap()` once; reads via `current_context()` | ✅ |
| CF-11 field aliases | `AliasChoices` re-exported via `config/_reexports.py` | ✅ |
| CF-12 discriminated unions | `vault/_configs.py` has `backend_type` literal discriminator on EnvVault/KeyringVault/EncryptedFileVault variants | ✅ |

No code drift; no standard edits warranted.

### WORKFLOWS_PATTERNS.md — closed

**Verdict:** clean. Paste-ready recipes match the live
`.woodpecker.yml` line-for-line on the critical commands.

| Recipe | Live yaml | Match |
|---|---|---|
| §5 `pip-audit --strict --desc \|\| (sleep 30 && pip-audit --strict --desc)` | identical | ✅ |
| §5.1 `gitleaks detect --source . --config .gitleaks.toml --no-banner --redact --verbose` | identical | ✅ |
| §5.1 image `zricethezav/gitleaks:v8.30.1` | identical | ✅ |
| §5.2 `cyclonedx-py environment --pyproject pyproject.toml --mc-type library --of JSON --output-reproducible` | identical | ✅ |
| §6 compat-matrix shape | mgf-common uses the literal pattern (`compat-matrix-example-app`) | ✅ |

§5.1 + §5.2 added in v2.2; §8 canonical recipe still
present + comprehensive. No drift.

### RELEASING.md (REL-01..REL-09) — closed

**Verdict:** clean. All REL-* mechanical checks pass. §2.3
(SBOM emission) added in v2.2 + §8 self-review checklist
includes the extended-gate CI items. All reflect current
practice.

| Rule | Check | Result |
|---|---|---|
| REL-01 annotated tags | `git tag -l "v*"` shows v0.22.0 → v0.33.0 (every release tagged) | ✅ |
| REL-02 dist immutability | dist/ holds the v0.33.0 wheel; never re-built from a later commit | ✅ |
| REL-03 PUBLIC_API.md banner | ⚠️ "This file documents `master` HEAD" banner at top of PUBLIC_API.md (PAPER-12) | ✅ |
| REL-06 release-flow order | CHANGELOG has `[Unreleased]` + Keep-a-Changelog format; per-commit promotion discipline | ✅ |
| REL-08 pre-release smoke | `.woodpecker.yml` `smoke` step (also implements WF-07) | ✅ |
| §2.3 SBOM emission | `.woodpecker.yml` `sbom` step (SC-18 + SH-07) | ✅ |

No code drift; no standard edits warranted.

### WORKFLOWS.md (WF-01..WF-12) — closed

**Verdict:** clean. All WF-* requirements visible in
`.woodpecker.yml`. §2.4 extended-gate trio
(vuln-scan / secret-scan / sbom) added in v2.2 — all live.

| Rule | Check | Result |
|---|---|---|
| WF-02 four-gate baseline | lint + typecheck + test + import-linter steps exist | ✅ |
| WF-04 secret-store token | `TWINE_PASSWORD: from_secret: pypi_token` | ✅ |
| WF-05 tag-coherence | dedicated step verifies CI_COMMIT_TAG ↔ pyproject ↔ __version__ | ✅ |
| WF-07 pre-publish smoke | `smoke` step installs + imports the freshly-built wheel | ✅ |
| WF-08 post-publish verify | `verify-pypi` step polls PyPI for the artifact + SHA | ✅ |
| WF-09 pinned images | `python:3.12-slim`, `zricethezav/gitleaks:v8.30.1` — exact tags | ✅ |
| §2.4 extended gates | `vuln-scan` (pip-audit) + `secret-scan` (gitleaks) + `sbom` (cyclonedx-py) all run; `publish` step's `depends_on:` includes all three | ✅ |

No code drift; no standard edits warranted.

### API_DESIGN.md (AP-01..AP-15) — closed

**Verdict:** clean. All mechanically-checkable AP-* rules
pass. §2.4 (RA-10 substring-lint shape) + §2.5 (PUBLIC_API.json
companion) added in v2.2 — both reflect current code.

| Rule | Check | Result |
|---|---|---|
| AP-01 `__all__` | every public module (common / exceptions / observability / config / vault) declares `__all__` | ✅ |
| AP-08 `from __future__ import annotations` | every `src/mgf/common/*.py` top-level | ✅ |
| AP-09 `py.typed` | `src/mgf/common/py.typed` present | ✅ |
| AP-10 PUBLIC_API.md ↔ `__all__` | `tests/unit/test_public_api_doc.py` substring-pin | ✅ |
| AP-13 `__version__` ↔ pyproject | both at `0.33.0` | ✅ |
| AP-14 internal privacy | 9 `_*-prefixed` modules (`_env_source`, `_errors`, `_identity`, `_io`, `_lifecycle`, `_request_id`, `_test_helpers`, `_warnings`) | ✅ |

No code drift; no standard edits warranted.

### TESTING.md (TS-01..TS-21) — closed

**Verdict:** TS-19 had outdated wording; the perf-deselect
was aspirational, not actual. Both fixed in this commit.

**Checks run + findings:**

| Rule | Check | Result |
|---|---|---|
| TS-01 mirror | 58 src files vs 64 unit tests | ✅ |
| TS-04 filterwarnings=error | set in `pyproject.toml` | ✅ |
| TS-05 strict-markers + strict-config | both in `addopts` | ✅ |
| TS-06 coverage ≥80% | CI runs `--fail-under=85` (stricter than required) | ✅ |
| TS-13 Hypothesis | 2 property test files (redaction property + value patterns) | ✅ |
| TS-18 slow marker | `slow` was NOT registered in `[tool.pytest.ini_options].markers` — would trip `--strict-markers` if anyone added a slow test | **Fixed** — added defensive `slow` marker registration |
| TS-19 marker registration | wording said canonical four were `smoke / e2e / integration / slow`; mgf-common ships `smoke / e2e / integration / perf` (no `slow` used yet). Standard text was outdated. | **Fixed** — TS-19 now distinguishes layer markers (`smoke`/`e2e`/`integration`, with `unit/` unmarked default) from orthogonal markers (`perf` for RA-11, `slow` for TS-18); spelled out that defensive registration of `slow` is recommended |
| TS-20 four-layer dirs | `tests/{unit,integration,e2e,smoke}/` all exist | ✅ |
| TS-21 smoke layer | `tests/smoke/test_process_smoke.py` exists | ✅ |
| **Perf-deselect bug** | pyproject's `perf` marker description claimed "excluded from the default suite via the `not perf` deselect at the top of testpaths" but **the deselect wasn't actually wired** — running `pytest tests/` was running all 4 perf tests on every PR. | **Fixed** — added `-m "not perf and not slow"` to `addopts`. Default suite now 1411 tests (was 1415; 4 perf tests deselected). `pytest -m perf` still runs the 4 perf tests explicitly. |

**Standards themselves required one wording fix (TS-19).**
The marker-set framing now correctly distinguishes
test-layer markers from cross-cutting orthogonal markers,
and explicitly recommends defensive `slow` registration.

**Code fix landed:** `pyproject.toml` addopts now actually
implements the perf-nightly-sweep design (was aspirational
in the marker description; now real). `slow` marker
registered defensively.

**Open follow-up (not in scope for this audit):** there's no
nightly CI job that runs `pytest -m perf` against `main`.
The perf-pin RA-11 budgets exist; they don't gate anything
today (the CI per-PR test step deselects them, and there's
no nightly counterpart). Add a Woodpecker cron / nightly
step running `pytest -m perf` so regressions actually fire
an alert. This is a CI feature addition, not a bug fix —
surface as a future RA-* or PC-* item if the maintainer wants
it tracked.

### COMMON_COMPONENTS.md — closed

**Verdict:** clean. Every catalogued component verified
shipping at the claimed path. §14 (Redactor SH-03 invariants)
+ §17 (atomic_write helper) added in v2.2 — both reflect
current code.

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

No code drift; no standard edits warranted.

### SECURITY_STANDARD.md (SC-01..SC-18) — closed

**Verdict:** clean. All mechanically-checkable SC-* rules
pass. §9 (redactor + crash-reporter defense-in-depth chain) +
§8.5 (env-var trust) + §16 (AS-IS) were refreshed in the v2.2
arc with the SH-01 / SH-03 / SH-06 / SH-08 closures; all
reflect current code.

**Checks run:**

| Rule | Check | Result |
|---|---|---|
| SC-02 argv-only | `grep -rn "shell=True" src/mgf/` excluding template + standards quotes | ✅ zero hits in real code |
| SC-03 safe deserialization | `grep "yaml\\.load(\|import pickle"` in src/mgf/ | ✅ zero hits |
| SC-04 atomic + 0o600 | delegated to `mgf.common._io.atomic_write` (RA-01); 5 call sites all pass `mode=0o600` | ✅ |
| SC-06 TLS verify | `grep "verify=False\|CERT_NONE\|AutoAddPolicy"` in src/mgf/ | ✅ zero hits |
| SC-09 redaction | `Redactor` + JsonFormatter wired by default in `setup_logging`; SH-03 depth cap | ✅ |
| SC-10 dep scan | `.woodpecker.yml` runs `pip-audit --strict --desc` (line ~208) | ✅ |
| SC-12 root SECURITY.md | file exists at repo root | ✅ |
| SC-17 audit log | `audit=true` records emitted for vault read/write/delete + bootstrap.replace + reload.unrecoverable + crash sink events (after the LOGGING audit retrofit) | ✅ |
| SC-18 SBOM | `.woodpecker.yml` runs `cyclonedx-py environment` (line ~255) | ✅ |
| SC-01 secret scan | `.woodpecker.yml` runs `gitleaks` with `.gitleaks.toml` allowlist (SH-05) | ✅ |

No code drift; no standard edits warranted.

## §5 Standing principles for this audit

- **The library owns the standard.** A rule that doesn't earn
  its place can be cut.
- **No aspirational MUSTs.** Every MUST MUST hold today, or it
  becomes a SHOULD (or gets cut).
- **No untested claims.** Every "AS-IS in mgf-common" bullet
  resolves to code that ships.
- **Honest scope.** If the library is in fact a leaf-with-
  siblings rather than a monolith, the standards reflect that.
- **Bias toward fewer rules.** Fewer load-bearing rules beat
  more aspirational ones. Cut what isn't pulling weight.
