# DOC-19 SHOULD→MUST promotion wave — tracker

> **Goal:** promote **DOC-19** (`LESSON_LEARNED.md`) from SHOULD to MUST —
> into the README *Index of MUSTs* + a `doctor --standards` presence gate
> (mgf-common **PAPER-99**) — with **zero red-CI window** anywhere.
> **Status:** ✅ **COMPLETE (2026-06-07).** All four phases shipped + verified
> end-to-end. DOC-19 (`LESSON_LEARNED.md`) is a MUST (standards v2.21), seeded
> on all 34 repos, ledger-row-complete on the 12 per-id ledgers, and
> presence-gated by `mgf-common doctor --standards` 0.46.5 (PAPER-99).
> **End-to-end proof:** `doctor --standards` on mgf-common = `✓ DOC-15 (218/218
> MUSTs) · ✓ DOC-19 (present)`, 7 pass · 0 fail; a no-file control correctly
> fails DOC-19. Move this tracker to `docs/archive/` next cycle (DOC-11).
> **Origin:** mgf-standard FEEDBACK PAPER-03; planned in the same session.

## The safety mechanic (why this can't break the federation)

Conformance resolves from the **pinned** `mgf-standard`, not "latest." A repo
only *sees* DOC-19 as a MUST once it resolves the promotion corpus (0.1.20). The
flip is therefore **inert until each repo bumps its pin** — the retro-fail is
per-repo and self-triggered, never instantaneous. We exploit this: **seed every
repo's `LESSON_LEARNED.md` BEFORE 0.1.20 is published**, so no repo can resolve
the new MUST without already satisfying it.

## Verified facts (2026-06-07, checked — not from memory)

- **Scope: 34 repos**, all checked out locally (reachable): 28 `mgf-*` libraries
  (the roster — which already includes `mgf-standard`) + 6 consumer apps
  (`hrb-app`, `inthewords`, `iosRecovery`, `TelePlasma`, `vm-vmanager-agent`,
  `vm-vmanager-app`). *(Corrected from an earlier "35" — `mgf-standard` is
  one of the 28, not a 35th.)*
- **Adoption: was 1/34; now 34/34** after the Phase-A seed sweep (2026-06-07).
- **DOC-19 confirmed ABSENT from the Index of MUSTs** (gate-safe today).
- **Ledger formats are heterogeneous and mostly NOT CFM-03-complete.** Spot-check:
  `mgf-http`'s `MGF_STANDARDS_CONFORMANCE.md` is the *family-aggregated* shape
  (§2.x per-standard prose, no per-MUST-id table) — so it does not enumerate all
  MUSTs and is already CFM-03-incomplete, **independent of DOC-19**. Memory's
  claim that the consumer-deps rollout enumerated all 217 MUSTs into mgf-http
  does **not** match its `main`. ⇒ verify each repo's ledger format; do not trust
  the prior rollout notes.

## Consequence: the wave decouples into two independent things

1. **File presence (this wave's job):** create `LESSON_LEARNED.md` everywhere →
   the thing PAPER-99 gates. Uniform, mechanical, low-risk.
2. **Per-id ledger completeness (NOT this wave):** the CFM-03 gate wants a row
   for *every* MUST. Most ledgers already miss most MUSTs — a large, pre-existing
   backlog (the "deferred per-repo conformance audit" open item). DOC-19's row is
   one of many; it rides along with that effort. **The only ledgers that need a
   DOC-19 row added *for this wave* are the ones that are CURRENTLY per-id
   complete** (so the flip doesn't newly break them) — verify per repo.

## Phases

| Phase | What | Gate | Status |
|---|---|---|---|
| **A** | Seed `LESSON_LEARNED.md` in all repos (roots→leaves); append DOC-19 row only to ledgers that are *currently* per-id complete | repo gates green; doctor still green (DOC-19 still SHOULD) | ✅ **file-seed done 34/34** (worktree+push, default branches incl. iosRecovery=master, verified). A2 ledger-rows: see note below — folded into the Phase-B pre-check |
| **B** | Flip the standard → `mgf-standard` 0.1.20: DOC-19 SHOULD→MUST + Index of MUSTs + §2.0.1 ✅ + FEDERATION baseline + What's-new v2.21 + recipe; regen registry; release | gates + REST 200 | ✅ **DONE** — pre-check added `DOC-19 ✅` to the **12 currently-complete ledgers** (vm-vmanager-app/-agent, TelePlasma, mgf-vm-{sdk,libvirt,interchange,forensics,core}, mgf-hrb, mgf-common, inthewords, hrb-app); flipped + released 0.1.20. The other 21 are already CFM-03-incomplete (unaffected); **mgf-logship has NO ledger** (pre-existing DOC-15 gap → backlog) |
| **C** | mgf-common PAPER-99: `doctor --standards` `LESSON_LEARNED.md` presence gate (`_check_lesson_learned_present`, corpus-aware/inert <0.1.20) + 4 tests; release 0.46.5 | full suite 2061 + REST 200 | ✅ **DONE** (PR #11, mgf-common 0.46.5, fresh-install verified; FEEDBACK PAPER-99 → SHIPPED) |
| **D** | REL-13 regen → mgf-standard 0.1.21 (cornerstone 0.46.5); end-to-end doctor proof; flip PAPER-03/PAPER-99 → SHIPPED | doctor green on a complete-ledger repo; REL-13 CURRENT | ✅ **DONE** — end-to-end: mgf-common `doctor --standards` = ✓ DOC-15 (218/218) · ✓ DOC-19; no-file control ✗ fails. **Note:** "doctor GREEN *federation-wide*" is NOT claimed — 21 repos have family-aggregated/incomplete ledgers (pre-existing CFM-03 backlog, unaffected by DOC-19); mgf-logship has no ledger. DOC-19 broke **no one new** (presence on all 34; row on all 12 complete ledgers). |

**Ordering law:** Phase A must be 100% done before B is *published*. C may land
after B. Seeding-first guarantees no red doctor even on an eager pin bump.

## Per-repo unit of work (Phase A)

For each repo, via git-worktree off `origin/<default>` (WIP-safe), docs-only,
direct push to default branch (the established federation-sweep pattern; no
per-repo release — the file + ledger are not wheel data):

1. Create root `LESSON_LEARNED.md` from `lesson-learned-md-template` (seeded
   header + a dated meta-entry noting it was created by this wave).
2. **Check the ledger format.** If `MGF_STANDARDS_CONFORMANCE.md` has a per-MUST
   table → append a `DOC-19 | ✅` row. If family-aggregated → no DOC-19-specific
   edit (its CFM-03 completeness is the separate backlog); note it here.
3. Repo gates as applicable; commit `docs(lessons): seed LESSON_LEARNED.md
   (DOC-19 adoption wave)` with AG-03 trailers.

## §4 — Work units / progress (Phase A, dependency-ordered)

Wave 0 (roots): mgf-common · mgf-common-zig · mgf-hrb-model · mgf-website-template · ~~mgf-standard (done)~~
Wave 1: mgf-apiprobe · mgf-auth · mgf-django · mgf-hrb · mgf-hrb-kabi · mgf-hrb-rt · mgf-http · mgf-livepush · mgf-logship · mgf-sqlalchemy · mgf-tele-core · mgf-test-supervisor · mgf-vm-core
Wave 2: mgf-alembic · mgf-common-identity · mgf-fastapi · mgf-hrb-cap · mgf-tele-teltonika · mgf-vm-firecracker · mgf-vm-forensics · mgf-vm-interchange · mgf-vm-libvirt
Wave 3: mgf-vm-sdk
Wave 4 (consumer apps): hrb-app · inthewords · vm-vmanager-app · vm-vmanager-agent · iosRecovery · TelePlasma

| Repo group | LESSON_LEARNED.md | Pushed | Ledger DOC-19 row |
|---|---|---|---|
| mgf-standard | ✅ (5 entries) | ✅ pre-wave | n/a (standards owner) |
| Wave 0 roots (mgf-common, mgf-common-zig, mgf-hrb-model, mgf-website-template) | ✅ | ✅ main | ⬜ (Phase-B pre-check) |
| Wave 1 (13) + Wave 2 (9) + Wave 3 (mgf-vm-sdk) | ✅ | ✅ main | ⬜ (Phase-B pre-check) |
| Wave 4 apps (hrb-app, inthewords, vm-vmanager-app, vm-vmanager-agent, TelePlasma) | ✅ | ✅ main | ⬜ (Phase-B pre-check) |
| iosRecovery | ✅ | ✅ **master** | ⬜ (Phase-B pre-check) |

**All 34 verified present on their default branch (`Missing: NONE`).** Seed
content = the template header + one dated meta-entry noting the wave created it.

**A2 (ledger DOC-19 rows) — finding + decision.** Spot-checks show sibling
ledgers are mostly the *family-aggregated* shape (no per-MUST-id table) →
already CFM-03-incomplete, so DOC-19 changes none of their pass/fail status. The
only ledgers needing a DOC-19 row *for this wave* are any that are CURRENTLY
per-id complete (so the flip doesn't newly break them). **Phase-B pre-check:**
before publishing 0.1.20, run `mgf-common doctor --standards` (or scan ledgers)
across the 34; add a `DOC-19 ✅` row only where the ledger is already complete.
Per-id completion of the rest is the separate, pre-existing conformance backlog,
NOT a blocker for the file-presence promotion.

## §5 — Decisions

- **R1 (mgf-common's incomplete ledger):** OUT OF SCOPE for this wave — mgf-common
  gets a `LESSON_LEARNED.md` like every repo; completing its full per-MUST ledger
  is the separate conformance backlog.
- **Execution:** sequential git-worktree sweep (no multi-agent workflow opted in).
- **N/A policy:** `LESSON_LEARNED.md` is effectively never N/A (every repo accrues
  lessons) → default ✅ present. No declines expected.

## Risks

- **Eager pin-bump mid-Phase-A** → transient red. Mitigation: do not publish
  0.1.20 until the §4 table is 35/35.
- **Heterogeneous ledgers** → the per-id DOC-19 row is only meaningful for
  currently-complete ledgers; do not fabricate per-id tables here (that's the
  separate audit).
