Overview

Solutions

Documented fixes for known issues encountered during development. Each entry carries a severity tag at the top so an emerging incident can be ranked at a glance against past fixes.

Severity legend

• P0 — security or data-loss class. Privilege escalation, secret leak, irreversible state.
• P1 — blocks development work broadly. Tests cannot run, builds cannot pass, deploys are blocked.
• P2 — blocks an individual workflow; a workaround exists but the workaround has cost.
• P3 — friction or ergonomics. The system works; the developer experience is degraded.

Build Errors

• passlib/bcrypt5 incompatibility — P2 · bcrypt 5.x broke passlib compatibility
• Ruff TC003 breaks Pydantic models with PEP 563 — P2 · unsafe-fix moves uuid behind TYPE_CHECKING, breaking Pydantic
• uv workspace Docker layer caching — P3 · Docker cache invalidation with uv workspaces

Integration Issues

• gh secret set —body - corrupts secrets — P1 · --body - sets every secret to the literal dash (gh reads stdin only when --body is omitted)

Logic Errors

• Legacy migration: dual-path antipattern — principle · why “if-legacy/else-new” is accretion, not migration
• Import-time env capture forces lazy-import hacks — principle · read env at call time so a plain import is order-independent

Security Issues

• OAuth default role escalation — P0 · OAuth auto-provisioning defaulted to admin role

Test Failures

• Module-level DB pool blocks tests — P1 · Connection pool initialized at import time blocked test isolation
• Pydantic Field validation changes HTTP 400 to 422 — P2 · Moving validation to Pydantic model changes status code
• TanStack Router Link render tests need router context or a focused mock — P2 · Render-only tests fail when Link is outside RouterProvider