feat(lesson): alembic upgrade failure diagnosis

[zsxh1990]

Summary

New lesson documenting alembic migration chain divergence: diagnosis commands, fix-by-scenario playbooks.

Closes #1652

Lesson Content

• Problem: alembic upgrade head fails after dependency update
• Root cause: migration chain diverges from alembic_version table
• Solution: diagnose → stamp/merge/rollback per scenario
• Prevention: alembic check before upgrade, backup before migrate

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Ikalus1988]

The lesson itself is the right shape and I want it in the corpus: Problem names three distinct failure modes, Root Cause explains the alembic_version ↔ chain divergence (including the SQLite no-transactional-DDL trap), Solution is a real diagnostic sequence rather than a recipe, and Verification ends on the criterion that actually matters (alembic heads must show one line). All 24 checks are green.

One blocker, and it is the one thing this corpus cannot ship:

The source URL does not exist

source: "https://github.com/modelcontextprotocol/mcp-memory-service/issues/1652"
provenance:
  source: "community"
  issue: 1652

I checked both:

GET /repos/modelcontextprotocol/mcp-memory-service              -> HTTP 404
GET /repos/modelcontextprotocol/mcp-memory-service/issues/1652  -> HTTP 404

The repository does not exist, so the issue cannot either. And issue: 1652 is our own bounty issue number, not an upstream source — the two have been merged into one line, which is how a plausible-looking provenance got invented. The actual origin is the third-party report that opened intake #1553 (source repo s6pa1rta3n-lab/roof4u, error Command '['alembic', 'upgrade', 'head']' returned non-zero exit status 255).

Provenance is the trust anchor here: E-levels, evidence_refs and the whole "verifiable contributions" story mean a reader must be able to follow that link. A lesson with an invented upstream URL is worse than one that admits it has no upstream — which is why #1553's own AC says "先补齐被截断的 stderr——拿不到真实根因就不要写成课程".

Please fix (small, ~4 lines)

1. provenance.issue: "#1553" — quoted, matching the corpus convention (grep -r 'issue: "' lessons/ for examples). That is the report this task converts.
2. Keep the external source only if it resolves; otherwise drop the URL and say where it came from in plain words (第三方仓库 s6pa1rta3n-lab/roof4u 报料). If you have the real upstream issue, link that instead.
3. created: '2026-09-07' / updated: '2026-09-07' predate this PR by eight days and predate the intake by a day — set the real dates, or drop both fields (most of the corpus omits them).
4. evidence_level: E3 needs to be defensible: either state where you reproduced this (alembic version, DB backend, what you saw before/after alembic merge), or lower it and say plainly that the sequence is derived rather than reproduced. Honest beats decorated — the Verification section already reads like "should", which is fine as long as it is not labelled as reproduced evidence.

Nothing else needs to change; the filename is yours to choose (#1553's AC suggests alembic-upgrade-head-failed.md, but kebab-case is the only hard rule).

One coordination note

There are now two open PRs for #1652: this one and #1656 (@TaherEzzi, a 519-byte skeleton that also edits the generated lessons/index.md). You claimed the task on 2026-09-15, and yours is the one worth finishing — so this PR is the live candidate. Just be aware #1656 exists so we don't merge both.