# LESSON_LEARNED — mgf-common

> Append-only, dated log of non-obvious lessons learned working in this repo.
> Newest first. One entry per lesson. Supersede a wrong past entry with a new
> one — never rewrite history. Federation rule: **DOC-19**; template:
> `mgf-common sync-prompt` / docs/recipes/lesson-learned-md-template.md.

---

## 2026-06-16 — Activating CI surfaced a regression my own AG-18 ship caused

- **Context:** The self-hosted Woodpecker CI went live (WF-11) and ran mgf-common's
  pipeline for the **first time ever** (Codeberg shared CI was never available). It
  immediately red-flagged 5 things — and one was a regression I had just introduced.
- **What I learned:** Tightening a standard that flips a `mgf-common doctor` check
  from **inert → enforcing** (here: AG-18 v2.24 / PAPER-102 making the
  `prepare-commit-msg` hook MUST-present, shipped in mgf-standard 0.1.58 +
  mgf-common 0.46.12) **breaks any test fixture that runs that check** if the
  fixture isn't updated in the same change. `test_clean_project_exits_zero` built a
  "clean" project via `_write_project` that didn't seed `.githooks/prepare-commit-msg`
  → doctor exited 2. It went unnoticed because **no CI was running to catch it.**
- **Why it matters:** A standard tightening has a *test-fixture blast radius* that's
  invisible without CI. "Lands GREEN, not retro-failing" reasoning must include the
  doctor-fixture tests, not just the generated CI gate steps.
- **How to apply:** When a standard tightening flips a doctor/`catch-up` check to
  enforcing, **update the clean-project fixtures in the SAME change** (seed whatever
  the new rule requires) and run the doctor tests against the *target* corpus
  version. Fix here: `_write_project(prepare_commit_hook=True)` by default; the
  absent-hook unit test opts out. Also: the first CI run after a long absence is a
  *backlog audit* — expect several real findings (a transitive-CVE in CI tooling,
  gitleaks on placeholder tokens in committed `.claude/` configs, a timing/bench test
  needing `@pytest.mark.perf` on a small runner, public-API pin drift). Triage each;
  don't suppress.
- **Generalizes?:** YES — the standard-tightening-vs-fixtures coupling is a
  federation-wide DOC-18/DOC-19 concern.

## 2026-06-07 — File seeded (DOC-19 adoption wave)

- **Context:** The federation adopted **DOC-19** — every project keeps an
  append-only `LESSON_LEARNED.md` so the federation stops re-learning the same
  thing.
- **What I learned:** (none yet — seeded by the adoption wave).
- **Why it matters:** Lessons left only in chat transcripts evaporate.
- **How to apply:** When you hit a gotcha / corrected assumption / reusable
  technique in this repo, add a dated entry here. If it generalises beyond this
  repo, ALSO file a `pending-feedback/<target>.md` paper.
- **Generalizes?:** n/a (seed entry).

---
