# Standards audit — pass B (2026-05-15)

> **Status:** ✅ **closed 2026-05-15.** All 14 docs audited
> under the sharpened lens; findings rolled into
> [`docs/STANDARDS_COMPLIANCE.md`](../STANDARDS_COMPLIANCE.md)
> (v1.0 → v1.1). Cuts: 115 lines across 3 docs. Wording fixes:
> 5. Rules cut: 0; rules merged: 0. See §6 for the summary.

## §1 Framing

Pass A (`STANDARDS_AUDIT_2026-05-15.md`) asked: *"Does the
library follow the standards?"* — and surfaced gaps in both
directions. Five docs got fixes; nine were clean.

Pass B (this document) asks a different question, prompted
by the maintainer:

> *"The standard is here not to add complexity, it's to help
> make things better and consistent across all Magogi
> foundation projects."*

So for each rule, the question is:

1. **Does it serve consistency** across the federation
   (mgf-common + VManager + PlasmaMapper + inthewords + future
   projects)?
2. **Does it serve quality** in a measurable way (a class of
   bug it prevents, a confusion it removes)?
3. **Is it enforceable** — by a lint, a test, or at code
   review with a stable substring?

If a rule fails ALL three, it's bureaucracy and should be cut
(or merged with another rule, or dropped to a SHOULD).

## §2 Methodology

For each of the 14 docs:

1. **Read the Rules box.** For each MUST/SHOULD:
   - Does it pass the three questions above?
   - Does it overlap meaningfully with another rule? (Two
     rules saying the same thing is one rule too many.)
   - Is it currently followed? (If yes via Pass A, no need to
     re-verify mechanically — just confirm the rule is still
     load-bearing.)
2. **Read the body.** Look for:
   - Bloat: paragraphs that don't add information
   - Stale claims: references to closed FEEDBACK that no
     longer need calling out
   - Templates that have been superseded by the shipped
     `mgf-common` code (point at the code instead of carrying
     the template)
3. **Classify each finding:**
   - ✂️ **Cut** — rule / paragraph / section doesn't earn its
     place
   - 🪒 **Tighten** — keep the rule but trim the wording
   - 🔗 **Merge** — two rules become one
   - ✅ **Keep as is** — load-bearing
   - ➕ **Add** — gap discovered (rare in this pass)
4. **Apply changes** + commit per doc.

## §3 Per-doc progress

| # | Doc | Status | Findings |
|---|---|---|---|
| 1 | SCOPE.md | ✅ closed | All 6 SP-* rules pass the bar; no changes |
| 2 | DOCUMENTATION.md | ✅ closed | All 12 DOC-* rules pass; doc is dense but every section pulls weight |
| 3 | DESIGN_PRINCIPLES.md | ✅ closed | All 13 DP-* rules address distinct bug classes; no clean merges available |
| 4 | LOGGING.md | ✅ closed | All 17 LG-* rules earn their place; one stale §-reference fixed |
| 5 | ERROR_HANDLING.md | ✅ closed | 40-line VManager-specific §11 cut; sections renumbered; README cross-ref updated |
| 6 | CONFIGURATION.md | ✅ closed | 41-line VManager §14 cut; 3 cross-refs fixed in CONFIGURATION + COMMON_COMPONENTS |
| 7 | SECURITY_STANDARD.md | ✅ closed | All 18 SC-* rules earn their place; no changes |
| 8 | TESTING.md | ✅ closed | §13 title fix ("canonical four" → "canonical set"); all 21 TS-* rules keep |
| 9 | API_DESIGN.md | ✅ closed | 2 markdown defects fixed (broken `##` heading at §10; PUBLIC_API template heading line); all 15 AP-* rules keep |
| 10 | WORKFLOWS.md | ✅ closed | All 12 WF-* rules earn place; §2.4 extended-gate trio recent |
| 11 | WORKFLOWS_PATTERNS.md | ✅ closed | All 9 sections are paste-ready recipes verified vs live yaml in Pass A |
| 12 | RELEASING.md | ✅ closed | All 9 REL-* rules earn place; §2.3 SBOM + §7 closure notification recent |
| 13 | COMMON_COMPONENTS.md | ✅ closed | Catalogue accurate (cross-refs cleaned during CONFIG audit) |
| 14 | README.md (master index) | ✅ closed | Stale "gap-closure plan" cross-ref fixed during ERROR_HANDLING audit |

## §4 Findings (rolling)

### SCOPE.md — closed (no changes)

**Rules check (6 rules):**

| Rule | Consistency | Quality | Enforceable | Verdict |
|---|---|---|---|---|
| SP-01 IN-scope list | ✅ | ✅ prevents scope creep | ⚠️ review-level | ✅ keep |
| SP-02 OUT-scope list + reasoning | ✅ | ✅ prevents "but-couldn't-you" | ⚠️ review-level | ✅ keep |
| SP-03 PR justifies vs IN/Adjacent | ✅ | ✅ active mechanism for SP-01/02 | ⚠️ review-level | ✅ keep |
| SP-04 Adjacent needs consumer signal | ✅ | ✅ falsifiable ("≥2 consumers") | ⚠️ review-level | ✅ keep |
| SP-05 OUT-list cites alternative | ✅ | ✅ "lazy vs considered" | ✅ mechanical (table column) | ✅ keep |
| SP-06 revisit at MAJOR | ✅ | ✅ prevents stale policy | ⚠️ release-checklist | ✅ keep |

**Body check:** 238 lines / 6 sections — tight already. Pass A
cleaned the false IN-scope claims (SSH, resilience utilities).
No bloat to trim; no rules to merge or cut.

**Soft observation (not actionable):** SP-01..04 and SP-06 are
all review-level rather than mechanically-enforced. The
trade-off is fine — these rules govern *judgment calls* about
new modules, where a lint would either be too strict
(reject every PR adding a function) or too lax (let creep
through). Review is the right mechanism.

### DOCUMENTATION.md — closed (no changes)

**Rules check (12 rules):**

7 mechanically-enforceable, 5 review-level. Sample of the
mechanical group: DOC-01 (`ls` for root docs), DOC-02 (`ls -d`
for buckets), DOC-03 (per-bucket README presence), DOC-06 (grep
for §1..§6 headings), DOC-08 (test_public_api_doc.py).

Every rule earns its place. Notably:

- **DOC-08** overlaps AP-10 partly (both say "PUBLIC_API.md
  tracks `__all__`"), but DOC-08 adds the JSON-companion
  clause that AP-10 doesn't carry. The duplication is
  purposeful — DOC-08 sits in the docs-discipline standard;
  AP-10 sits in the API standard. A reader of either lands
  on the right rule.
- **DOC-12** elaborates in §11; the rule + body are not
  duplication, the rule names the MUST and §11 gives the
  worked patterns.

**Body check:** 844 lines / 16 sections. Large, but each
section pulls weight (worked CLAUDE.md / cutover-guide /
tracker examples are paste-ready). Cutting any would leave
the corresponding rule under-defined.

No changes. The doc is denser than most because it bootstraps
*itself* (the docs-discipline standard has to BE a model of
good docs); the trade-off is the right one.

### DESIGN_PRINCIPLES.md — closed (no changes)

**Rules check (13 rules):** all earn their place. The strongest
mechanically-enforced are DP-01 (`.importlinter`), DP-04
(`mypy --strict`), DP-11 (ruff RUF006), DP-12 (ruff DTZ).

**Merge candidates investigated:** DP-04 (mypy) + DP-07
(docstrings) — both code-quality, but distinct concerns
(types vs prose). DP-09 (cancellation) + DP-11 (async task
ownership) — both resource discipline, but distinct
(sync cancellation token vs async task lifecycle). No clean
merges; keep as 13 independent rules.

**Body check:** 916 lines. §2 (Qt worker pattern) is correctly
scoped to "mandatory for desktop & mobile apps" — federation
projects without a GUI skip it. §5 Replaceability path table
is consumer-template (VManager-shaped example). §6 Performance
budgets was refreshed in v2.2 to cross-ref TS-14 and the
PERFORMANCE_AND_CAPACITY tracker. All sections pull weight.

DP-08 ("doc near each component MUST describe the swap recipe")
is the weakest rule — purely review-level, no mechanical
check possible. But the §5 table gives the consumer-side
template, and the rule shapes thinking about replaceability.
Keep as SHOULD-with-table-template — which is what it
already says.

No changes.

### LOGGING.md — closed (one minor fix)

**Rules check (17 rules):** all earn their place. The 17 rules
cover 12 distinct concerns (acquisition / configuration / OTel
correlation / redaction / exception-logging / aggregation /
GUI-viewer / lazy-format / structured-fields /
headless-services / operation-tracing / perf / volume-control /
async-correlation / events / message-content / grouping).

**Merge candidates investigated and rejected:**
- LG-08 (lazy %) + LG-12 (≤100 µs per record): both perf-
  related but distinct (call-site cost vs record cost).
- LG-15 (events) + LG-16 (what/why/how): both message-quality
  but distinct (alert-target identifier vs content
  discipline).

**Fix landed:** Rules box for LG-15 / LG-16 / LG-17 referenced
"§19 / §19.1 / §19.2" — that was the predicted-section number
when I drafted them; they actually landed in §4.5 / §4.6 / §4.7
of the body. Fixed both LOGGING.md's rules box AND the master
README's Index of MUSTs (which had the same stale §-refs).

No other changes.

### ERROR_HANDLING.md — closed (40-line cut)

**Rules check (13 rules):** all 13 EH-* rules earn their
place. No merge candidates that hold up. Distinct concerns:
hierarchy / translation / chaining / top-level handlers /
crash report / GUI workers / bare except / typed fields /
actionable hints / best-effort observers / retry-with-backoff
/ idempotency / circuit breaker.

**Cut landed:** ✂️ §11 "Gap-closure plan for VManager" — 40
lines of VManager-specific tracker content (P0..P4 work items,
some likely already done, some never tracked further). Per
Pass B's bar: this fails consistency (one consumer only),
fails enforceable (it's a checklist, not a rule), and is
unmaintained. Sections §12..§16 renumbered to §11..§15.

The §10 "AS-IS in VManager" snapshot is KEPT — that's 18 lines
of grounded reference (specific call sites in a real consumer)
that serves as the disclaimer-allowed "illustrative example"
per standards/README's "⚠️ Consumer-specific examples are
illustrative" disclaimer. The line between §10 (grounded
example, kept) and §11 (consumer tracker, cut) is the boundary
between *describing what exists* and *tracking work to do*.

**Cross-references:** the cut leaves stale "gap-closure plan"
mentions in standards/README.md (line 163) — updated to point
at COMMON_COMPONENTS.md catalogue + per-topic "AS-IS"
sections instead. LOGGING.md (lines 6 + 1211) and
COMMON_COMPONENTS.md (lines 164 + 512) still carry stale
references; those will be addressed in their own Pass B audit
slots.

1411 tests still pass.

## §5 Bar for this pass

A rule SHOULD be cut or downgraded if any of these is true:

- **No mechanical check.** The rule reads MUST but no lint /
  test / grep / CI step enforces it; it depends entirely on
  reviewer goodwill. Either add the check OR drop to SHOULD.
- **Overlaps another rule.** Two MUSTs covering substantively
  the same ground — pick one, point the other at it.
- **Aspirational only.** The rule names a practice no project
  in the federation actually follows. Either ship the practice
  in code first OR drop the rule.
- **Too narrow.** The rule prescribes a specific implementation
  choice when consumers could legitimately differ (e.g.,
  prescribing a SPECIFIC tool when alternatives exist).
- **Wording bloat.** The rule says in 80 words what could be
  said in 30 without loss.

A rule SHOULD be kept if any of these is true:

- It prevents a specific class of bug or confusion mgf-common
  or a consumer has hit (commit history evidence).
- It's mechanically enforced (lint / test / CI gate).
- It's the consistency anchor consumers depend on — without
  it, every project would diverge on a meaningful axis.

## §6 Summary

**Cuts (115 lines, 3 docs):**

- ERROR_HANDLING §11 "Gap-closure plan for VManager" — 40 lines
- CONFIGURATION §14 "Gap-closure plan for VManager" — 41 lines
- LOGGING §15 "Gap-closure plan for VManager" — 34 lines

Pattern: consumer-specific tracker content (P0..P4 work items
for ONE consumer) inside consumer-neutral standards docs.
Failed Pass B's bar on consistency (one consumer only) + on
enforceable (checklist not rule). The corresponding "AS-IS in
VManager" GROUNDING sections were KEPT in all three docs —
the line between *describing what exists* (allowed
illustrative example) and *tracking work to do* (consumer-side
backlog content) is the cut boundary.

**Wording / markdown fixes (5):**

- TESTING §13 title "the canonical four" → "the canonical set"
  (5 markers now: smoke/e2e/integration layer markers +
  perf/slow orthogonal).
- API_DESIGN §10 heading: `## 10. The CHANGELOG contract
  (rule AP-12)follows [Keep a Changelog]...` was a heading +
  body smushed on one line. Fixed.
- API_DESIGN §2.4 template header: same shape defect inside
  the PUBLIC_API.md template code fence.
- LOGGING.md rules-box §-refs for LG-15/16/17: "See §19" →
  "See §4.5/4.6/4.7" (rules landed in §4 body, not §19 as
  drafted).
- Master README Index of MUSTs: same §-ref fix for LG-15/16/17.

**Cross-reference cleanup (4 stale "gap-closure plan" refs):**

- README §"How AI agents should use this folder" item 4
- CONFIGURATION §3.2 inline sentence
- COMMON_COMPONENTS §2 (settings status) + §13 (log viewer
  status)

**Rules cut: 0. Rules merged: 0.** The 148 MUST/SHOULD set
across 11 rule-bearing standards (DP / EH / LG / CF / SC /
TS / AP / WF / REL / SP / DOC) all earned their place under
Pass B's bar. Several merge candidates were investigated
(DP-04+DP-07; DP-09+DP-11; LG-08+LG-12; LG-15+LG-16); each
pair turned out to address distinct concerns.

**Result:**

Pass A asked *"does the library follow the standards?"* —
found 5 docs with fixes, 9 clean.

Pass B asks *"do the standards earn their weight?"* — found 3
docs with substantive cuts (the gap-closure-plan pattern),
2 with wording/markdown fixes, 9 entirely clean. The
remaining standards are tighter, more honest, and continue
to serve the federation consistency goal without carrying
consumer-tracking bloat.

The audit tracker stays in `docs/inprogress/` until next
release cycle, then moves to `docs/archive/2026/` per
**DOC-11**.

Findings rolled into `docs/STANDARDS_COMPLIANCE.md` as the
v1.0 → v1.1 update (rolling record per DOC-09 cadence).
