# LESSON_LEARNED — mgf-standard

> 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. See docs/recipes/lesson-learned-md-template.md.

---

## 2026-06-07 — A doc describing ANOTHER repo's file silently drifted from reality

- **Context:** Relaying `pending-feedback/mgf-common.md` — one paper asked to
  re-sync `mgf-common/.claude/commands/sync.md` to the rewritten prompt, on the
  strength of THIS recipe's Note claiming it held an "inline copy" of the prompt.
- **What I learned:** I checked the actual file: it is a thin *delegator*
  (`Run mgf-common sync-prompt …`), not an inline copy — so it can't drift, and
  the paper was a false alarm. The bug was in THIS repo's
  `federation-sync-prompt.md` Note, which described an inline-copy model that
  hadn't been true for some time. A doc that narrates a *different* repo's file
  is drift waiting to happen — nothing tests it.
- **Why it matters:** I almost filed (and acted on) cross-repo work based on a
  stale self-authored Note. Cross-repo descriptions are the highest-drift,
  lowest-verification kind of doc.
- **How to apply:** Before acting on any claim about another repo's file, OPEN
  that file. Treat docs-about-other-repos as hypotheses to verify, never facts —
  especially when they drive cross-repo action.
- **Generalizes?:** partly — the stale Note is fixed here; the habit "verify the
  artifact, not the doc about it" pairs with the earlier "audit the entry point"
  lesson.

## 2026-06-06 — On a PRIVATE registry, an unauth'd 404/401 reads as "absent" — a guesswork trap

- **Context:** Review pass on the sync-prompt hardening — I had written STEP-0
  instructions telling agents to `curl` Codeberg raw-file + package-index URLs
  with NO auth header.
- **What I learned:** magogi-admin is a private account: the unauthenticated
  raw-file URL returns **404** and the package simple-index returns **401** — and
  an agent naturally misreads those as "this file/version doesn't exist" and
  proceeds on a false negative (e.g. "already on latest"). With the PKG-03 token
  header both return **200**. The danger isn't just the missing auth — it's that
  the failure code actively lies in the direction of "nothing to do."
- **Why it matters:** A misleading-but-plausible error is worse than a loud one;
  it produces a confident wrong conclusion, exactly the guesswork the prompt
  exists to remove.
- **How to apply:** Every Codeberg remote-read instruction must (1) carry
  `Authorization: token $CB` (PKG-03) or reuse the already-configured index
  creds, and (2) explicitly state that a 401/404 means AUTHENTICATE, never
  "absent." Test the literal command unauthenticated before shipping it as
  guidance — assume nothing is public.
- **Generalizes?:** yes → the fix is in the sync prompt (STEP-0 ASSERT-LATEST +
  sibling-read blocks); the broader rule "verify the failure code can't be
  misread as success" is a review habit worth keeping.

## 2026-06-06 — Red-team the bootstrap prompt, not just the recipe it loads

- **Context:** Hardening the federation-sync mechanism by simulating a
  sibling-repo agent handed only "run `mgf-common sync-prompt` and follow it"
  (after `pip install -U mgf-common`).
- **What I learned:** The recipe (`federation-sync-prompt.md`) was already
  correct (it installs `'mgf-common[standards]'`), but the *bootstrap one-liner
  humans hand to agents* still said bare `mgf-common` — which loud-degrades
  before the agent ever sees the prompt. The gap was in the handoff message, a
  layer above the artifact we kept reviewing. Reviewing only the recipe would
  have missed it.
- **Why it matters:** The entry-point instruction is part of the mechanism. A
  perfect prompt is useless if the sentence that launches it is wrong.
- **How to apply:** When auditing any "do X then follow Y" flow, test the
  literal first instruction a fresh agent receives — not just Y. Trace from the
  human's exact words inward.
- **Generalizes?:** yes → the canonical bootstrap string fix is folded into the
  sync prompt's GUARD; broader "audit the entry point" is a review habit.

## 2026-06-06 — "Synced" must mean "to the latest released," not "to my pin"

- **Context:** Same red-team — checking whether an agent following the prompt
  actually lands on current standards.
- **What I learned:** The resolve-don't-copy seams read the corpus from the
  version THIS project's pin RESOLVES TO. If the pin ceiling lags the latest
  release, the agent syncs to OLD standards and still reports success — a
  green, confident, WRONG sync. "Resolve from the pinned version" (a deliberate,
  good design for reproducibility) quietly became "stale is fine" without an
  explicit latest-check.
- **Why it matters:** It silently breaks the core "always get the latest"
  guarantee — the worst kind of bug, because every signal says pass.
- **How to apply:** Any "read config/contract from a dependency" design needs an
  explicit installed-vs-latest assertion at the boundary (here: STEP-0
  ASSERT-LATEST against the Codeberg registry), or it will eventually bind to
  stale-as-current. Don't conflate "deterministic" with "current."
- **Generalizes?:** yes → filed to pending-feedback/mgf-common.md (wire a live
  latest-check into `catch-up`) and FEEDBACK PAPER-05.

## 2026-06-06 — Read-only-on-the-federation needs a writable outbox, or value leaks

- **Context:** Same red-team — tracing what happens when the agent finds a bug
  in a dependency or wants to challenge a standard.
- **What I learned:** "Route it to the target's FEEDBACK.md" + "never reach into
  another repo" with no writable destination = the finding dies in the chat
  transcript. Two reasonable rules combined into a dead end. The fix was a
  `pending-feedback/<target>.md` outbox in the agent's OWN repo (the one place
  it may write), which the supervisor relays — reconciling read-only with
  never-lose-value.
- **Why it matters:** The whole "never waste or duplicate effort, everything is
  up for evolution" value depends on findings surviving the session.
- **How to apply:** Whenever a rule forbids writing where the value belongs,
  give it a writable staging area + a relay step — don't leave "surface it
  somehow" as the instruction.
- **Generalizes?:** yes → the outbox mechanism is now in the sync prompt; a
  supervisor-side relay recipe is the open follow-up (FEEDBACK PAPER-04).
