Goal
Fix conflicts between static assets and API routes, add health check endpoint, and improve error handling for 500 errors on page routes.
Acceptance Criteria
☑ /health endpoint returns 200 with DB reachability check
☑ Global 500 exception handler logs tracebacks and returns styled error page
☑ /style.css includes proper Cache-Control headers
☑ Root cause of /agora, /debates, /analyses/ 500 errors identified and documented
☑ /api/coverage and /api/events 422 behavior confirmed as expected (auth required)
Root Cause Analysis
| Route | Status | Root Cause |
|---|
| /style.css | 200 | Working — file served or inline fallback |
| / | 302 | Working — redirect to dashboard |
| /agora | 500 | breadcrumb_html NameError (html vs _html) — fixed in 3a46ff11f |
| /debates | 500 | Same breadcrumb_html bug — fixed in 3a46ff11f |
| /analyses/ | 500 | Same breadcrumb_html bug — fixed in 3a46ff11f |
| /api/quality-gates | 200 | Working |
| /api/growth | 200 | Working |
| /api/coverage | 422 | Expected — requires x-api-key header |
| /api/visual-report | 200 | Working |
| /api/events | 422 | Expected — requires x-api-key header |
The 500 errors on /agora, /debates, and /analyses/ were caused by a NameError in
api_shared/nav.py's
breadcrumb_html function. After the api.py modularization
(commit 10b333a2d), the html module was imported as
_html but the function
referenced
html.escape() instead of
_html.escape(). Fixed in commit 3a46ff11f.
The API needs a restart after merging to pick up the breadcrumb fix.
Changes Made (commit 6c2915459)
Added /health and /api/health endpoints — lightweight DB reachability check
Added global Exception handler — logs full traceback, returns styled 500 page
Added Cache-Control: public, max-age=300 header to /style.css responseWork Log
2026-04-16 14:45 PT — Reopened task investigation
- Checked prior commit 4cb0526ee (spec-only, never merged to main)
- Tested all 10 affected routes against live API on port 8000
- Found /agora, /debates, /analyses/ return 500; /api/coverage and /api/events return 422
- Investigated route handlers, DB queries, helper functions — all correct
- Discovered root cause: breadcrumb_html NameError in api_shared/nav.py (html vs _html)
- Found fix already on main in commit 3a46ff11f, but API not restarted
- Rebased worktree onto latest main to pick up fix
- Added /health endpoint, global 500 handler, CSS caching headers
- Committed and pushed