# pending-feedback → mgf-common

Outbound papers (FB-05 / DOC-19): findings from `mgf-uitest-web` that **generalise
beyond this repo**, so they must cross the repo boundary rather than sit in local
memory. Each was found during the 2026-07-16 pre-publication conformance audit
(see [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](../docs/inprogress/MGF_STANDARDS_CONFORMANCE.md)).

Per **AG-13**, only the mgf-common supervisor edits mgf-common — these are filed,
not fixed locally. Per **DOC-09 §10.3**, a generated render is never hand-patched;
the source generator is the fix site. That is precisely why they are here.

---

## PAPER-01 — the generated `docs/claude/CLAUDE.md` asserts an mgf-common runtime dependency that need not exist

**Status:** OPEN · **Severity:** 🟡 (misleads every agent that reads it) · **Filed:** 2026-07-16

**What.** The `mgf-fed init-project` / `catch-up` render of `docs/claude/CLAUDE.md`
states, as fact: *"This project depends on mgf-common… call `mgf.common.bootstrap()`"*
and shows `from mgf.common import bootstrap_for_test, AppContext` under the path
`src/mgf-uitest-web/__init__.py`.

**Why it's wrong here.** `mgf-uitest-web` does **not** depend on mgf-common at
runtime — mgf-common is a `[standards]` extra only (for the conformance tooling).
Its runtime is `playwright` + `axe-playwright-python` + `pytest`, and an
import-linter contract now *forbids* it from importing a web framework. The shown
path is also wrong twice: the package is PEP-420 `src/mgf/uitest_web/`, never
`src/mgf-uitest-web/`.

**Why it generalises.** The template hard-codes the *consumer* shape. Any sibling
that is a pure tool/library (rather than an mgf-common consumer) gets the same
false briefing — and CLAUDE.md is the first thing an agent reads, so a wrong claim
here propagates into every subsequent decision. This is the "instrument lies" class
the 2026-07-14 fleet review named.

**Suggested fix.** Make the Quick-start block conditional on the repo actually
declaring an mgf-common **runtime** dep (the renderer already reads the manifest —
`mgf-fed`'s woodpecker renderer gates `lint-imports` on `[tool.importlinter]`
exactly this way), and derive the import path from the real package rather than the
repo slug.

---

## PAPER-02 — DOC-12's `## §N.` heading mandate and fleet practice disagree

**Status:** OPEN · **Severity:** 🟢 (consistency) · **Filed:** 2026-07-16

**What.** DOC-12 mandates numbered headings: *"Headings MUST be hierarchical
(`## §N. Title`) so the agent's table-of-contents grep works"*, and §12's
anti-pattern table is explicit (`## Setup` → `## §1. Setup`). But the fleet's root
docs are uniformly **unnumbered** — `mgf-fed-web` (the clean sibling used as the
reference shape) uses plain headings in README/SECURITY/STARTHERE/CONTRIBUTING,
reserving `## §N` for trackers and standards.

**Why it generalises.** Following the rule made `mgf-uitest-web` the *only* numbered
README in the fleet; following the fleet would have knowingly broken a MUST. A rule
that no repo obeys is either a rule to relax or a wave to schedule — but the
divergence should be decided once, federation-wide, not re-litigated per repo.

**Suggested fix.** Either (a) relax DOC-12's numbering to trackers/standards docs
(codifying actual practice), or (b) schedule a numbering wave and let
`app-doctor` check it. We followed the letter (option b's end-state) and will
happily revert to match the fleet if (a) is chosen.

---

## PAPER-03 — `scripts/check_commit_trailers.py` fails **open**: the AG-03 gate can go green without checking

**Status:** OPEN · **Severity:** 🟠 (a gate that lies) · **Filed:** 2026-07-16

**What.** The template-distributed trailer checker returns `0` when it cannot
compute `base..HEAD`, and the generated `.woodpecker.yml` step fetches the base with
`git fetch … || true`. So a fetch failure yields *"no commits to check"* → **exit 0
→ green**, with the AG-03 trailer gate having verified nothing.

**Why it generalises.** It is distributed by `mgf-fed catch-up --apply` to every
repo, so every repo's AG-03 server-side gate carries the same silent-pass path. This
is the same failure mode as the reconciler fail-open and the `mgf-fed status` emoji
`conf %` — a gate whose green means "didn't run", not "passed". AG-18 leans on this
step as *"the authoritative server-side gate… independent of a contributor's local
config"*, which is exactly the promise a fail-open breaks.

**Suggested fix.** Fail **closed**: if the base ref cannot be resolved, exit
non-zero with "could not determine the base commit — refusing to pass vacuously",
and drop the `|| true` on the fetch (or make the fetch failure itself fatal).

---

## PAPER-04 — REL-13's federation consistency gate is RED, and the registry is stale

**Status:** OPEN · **Severity:** 🔴 (the release-consistency gate is failing now) · **Filed:** 2026-07-16

**What.** `python scripts/gen_mgf_libraries.py --check` in mgf-standard currently
reports:

- `REGISTRY CURRENCY: STALE` — `MGF_LIBRARIES.md` was not regenerated after recent
  releases (e.g. `mgf-brand-web 0.5.2`, `mgf-fed-web 0.2.1`, both shipped 2026-07-16).
- `FEDERATION CONSISTENCY GATE: RED` — **`mgf-fed-web` and `mgf-test-web` both pin
  `mgf-fedres >=0.1,<0.2` while `mgf-fedres` is at `0.2.0`**: the pins *exclude the
  current version*, which REL-13 defines as a hard failure.

**Why it generalises.** This is the cornerstone supervisor's release-consistency
duty, and it is red independently of any one repo. It also blocks registry changes:
any PR that regenerates `MGF_LIBRARIES.json` (e.g. registering a new sibling) runs
into the same red gate.

**Suggested fix.** Walk the two `mgf-fedres` pins forward to accept `0.2.0`, verify
both consoles' suites against it, then regenerate the registry and commit it (the
registry is *generated* — note that `ENSHRINE-RUNBOOK.md` incorrectly instructs a
hand-insert, which would fight the generator and fail the currency check).
