Merge v0.8.0 into main (Polish + Observability)

Author: Shaan-alpha

ARCHITECTURE.md

@@ -140,6 +140,15 @@ Four fail-open layers; every operation swallows Redis exceptions and falls throu
 
 Bumping `KEY_PREFIX` in `app/cache/client.py` invalidates every namespace at once.
 
+### Observability — Sentry + PostHog + structlog (v0.8.0)
+
+Two thin cross-cutting layers. Both fail open — telemetry is never a correctness boundary.
+
+- **Backend `app/observability/`** — `structlog` JSON logging (console renderer in dev) with a `request_id` contextvar bound by `RequestIDMiddleware` (UUID4 per request). Sentry FastAPI integration captures unhandled exceptions; a `before_send` PII scrub hook strips `access_token`, `access_token_ct`, `oauth_state`, `oauth_code`, `session_id`, full `Cookie`/`Authorization` headers, and `email` before the envelope leaves the process. `request_id` is tagged on every Sentry event and echoed in the `X-Request-ID` response header so frontend breadcrumbs can correlate.
+- **Frontend `src/observability/`** — Sentry browser SDK via Next 16's `instrumentation.ts`, with source maps uploaded at build time. PostHog browser SDK wraps the layout via `<ObservabilityProvider>` — auto-pageviews + web-vitals capture + named events (`analyze_submitted`, `share_toggled`, `share_card_copied`, `mode_toggled`, `sign_in_clicked`). Signed-in users identified by the opaque `si_session` cookie value (never GitHub login, never email); anonymous viewers use PostHog's auto-distinct ID.
+- **Correlation contract:** one `request_id` per request flows through middleware → structlog → Sentry tag → response header. One canonical session ID across PostHog `identify()` and Sentry `user.id`.
+- **Real-user perf metrics:** PostHog `enable_web_vitals_autocapture` captures LCP / CLS / INP per visitor with element selectors — closes v0.7.2's "couldn't identify the prod LCP element" gap without adding a second vendor.
+
 ### Auth — GitHub OAuth (v0.5.0)
 
 - Server-side OAuth code flow (no PKCE — GitHub OAuth Apps don't support it). State in a short-lived httpOnly cookie.

CHANGELOG.md

@@ -8,6 +8,40 @@ Every version listed here must correspond to a slice in [`PLAN.md`](./PLAN.md) w
 
 ---
 
+## [0.8.0] — 2026-05-22
+
+### Added
+- **Sentry — backend project (`skill-issue-backend`)** with FastAPI + asyncpg + httpx + logging integrations. PII scrub (`before_send`) strips `Cookie` / `Authorization` / `x-vercel-id` headers, `access_token` / `access_token_ct` / `oauth_state` / `oauth_code` / `session_id` / `email` fields from every event. Idempotent `init_sentry` guards against double-initialisation.
+- **Sentry — frontend project (`skill-issue-frontend`)** via `@sentry/nextjs` 10.x. Three runtime targets covered: browser (`sentry.client.ts`), Node server-component (`sentry.server.ts`), edge (`sentry.edge.ts`). Source maps generated but upload disabled by default (`sourcemaps: { disable: true }` — lands in a v0.8.x patch when `SENTRY_AUTH_TOKEN` is provisioned). `onRequestError` Next 16 hook captures unhandled server errors. Browser + server share a single PII scrub list at `frontend/src/observability/scrub.ts`.
+- **PostHog (`skill-issue`)** product analytics + real-user web vitals capture. Five named events: `analyze_submitted`, `share_toggled`, `share_card_copied`, `mode_toggled`, `sign_in_clicked`. Typed helpers in `frontend/src/observability/events.ts` are the only public contract — bare `track()` is marked `@internal`. Anonymous viewers use PostHog's auto-distinct-ID; signed-in viewers identified by the opaque `si_session` cookie value (never GitHub login or email). `<ObservabilityProvider>` wraps the layout; `<SessionIdentifier>` is Suspense-isolated for React 19 `use()` semantics.
+- **Real-user web vitals** (LCP / CLS / INP / FCP / TTFB) captured by PostHog per visitor with element selectors — closes v0.7.2's open "couldn't ID the prod LCP element" gap. Free tier covers 12-month retention.
+- **`structlog`** JSON renderer in prod, console in dev. Every log line carries the `request_id` from the new `RequestIDMiddleware` (UUID4, also echoed in `X-Request-ID` response header). RFC 7230 whitespace is stripped from incoming `X-Request-ID` so upstream trace chains aren't broken.
+- **`RequestIDMiddleware`** — pure ASGI, binds the request_id into structlog's contextvars + Sentry's `isolation_scope` per-request. Honours an incoming `X-Request-ID` header when it's a valid UUID. Clears contextvars in a `finally` block so a mid-flight exception can't leak state.
+- **`docs/OBSERVABILITY.md`** — error-budget classes (critical / acceptable / noise), alert intent, event taxonomy, cross-tool correlation guide, PII contract.
+- **On-voice 404 page** (`app/not-found.tsx`) — Skill-Issue-voiced copy + CTAs to landing and the GitHub repo. Project design-system tokens (`glass`, `text-muted-foreground`, grid background) instead of generic neutrals.
+- **`Sentry.captureException` hook** in `app/error.tsx` so every unhandled client error reaches Sentry with the source-mapped stack.
+- **`@axe-core/cli`** dev dep. Baseline + post-fix audit captured at `docs/superpowers/measurements/2026-05-22-v0.8.0-axe-baseline.md`. **Zero critical, zero serious, zero moderate** axe issues across `/`, `/u/octocat`, `/u/octocat/card`, `/me`, `/this-does-not-exist` (the spec only required zero critical — we cleared the higher bar).
+
+### Changed
+- Backend `lifespan` now calls `init_logging()` + `init_sentry()` at startup before the DB ping.
+- `RequestIDMiddleware` added to the FastAPI middleware stack — runs first on requests (outermost), so CORS rejections also get tagged with a request_id.
+- `next.config.ts` wrapped with `withSentryConfig({ silent: true, sourcemaps: { disable: true } })` (v10 API — `hideSourceMaps` was renamed).
+- `layout.tsx` wraps children in `<ObservabilityProvider>` with a Suspense-isolated `<SessionIdentifier>` so PostHog identification waits for `useSession()` to resolve without blocking child render.
+- **Accessibility hardening on 4 pages**: `<div>` → `<main>` on `/u/[username]/not-found.tsx`, `/u/[username]/error.tsx`, root `/not-found.tsx`; added `sr-only` `<h1>` to `/u/[username]/loading.tsx` and `/me/loading.tsx`. Closes `landmark-one-main`, `page-has-heading-one`, and `region` axe rules. Added explicit `text-foreground` to the 404 GitHub link (was 2.38:1 contrast in headless light mode).
+- Frontend version strings (`v0.7.5 → v0.8.0`) updated in the landing pill + results footer.
+- Backend `pyproject.toml` + `app/settings.py::VERSION` + frontend `package.json` synced at `0.8.0`.
+
+### Notes
+- **Free-tier discipline.** Every new tool used a permanent free tier — Sentry (5K errors/mo + 50 replays/mo), PostHog (1M events/mo + 12-month retention), structlog + axe-core (OSS). No expiring trials, no 30-day-retention-only services.
+- **Deferred slices.** Five originally-co-located PLAN items moved to focused v0.8.x patches: cron re-ingestion (v0.8.1), manual "Force refresh" (v0.8.2), `/share/[slug]` ISR + `revalidateTag` (v0.8.3), `vercel.json → vercel.ts` migration (v0.8.4). Sentry alert rules deferred to a v0.8.x patch once a week of baseline data is captured. CI integration of `@axe-core/cli` also deferred to a v0.8.x patch.
+
+### Security
+- Sentry's `send_default_pii` is explicitly `False` on both frontend and backend; even if a future SDK upgrade defaults this on, our `before_send` / `beforeSend` scrub will still drop the listed fields.
+- The frontend PII scrub list is hoisted to a single source of truth (`frontend/src/observability/scrub.ts`) consumed by both client and server Sentry init — eliminates contract drift.
+- `x-vercel-id` added to the scrub list on both frontend and backend (was missing from frontend in initial implementation, caught by code review).
+
+---
+
 ## [0.7.5] — 2026-05-21
 
 ### Fixed

PLAN.md

@@ -30,8 +30,12 @@
 | **v0.7.3** | Hotfix — detect GitHub organizations + helpful 422 (was: silent 500 on `apache`, `microsoft`, etc.) | ✅ shipped |
 | **v0.7.4** | Hotfix — badge evidence reachable on mobile (Tooltip → Popover with hover + tap) | ✅ shipped |
 | **v0.7.5** | Hotfix — Roast/Mentor toggle symmetric on mobile (flex-1 split 50/50) | ✅ shipped |
-| **v0.8.0** | Polish + observability — Sentry, analytics, cron re-ingestion, manual "Force refresh" | pending |
-| **v0.9.0** | Beta hardening — security review, abuse mitigation, load test | pending |
+| **v0.8.0** | Polish + observability — Sentry (FE+BE), PostHog (events + web-vitals), structured logging, axe a11y pass, on-voice 404/500, error-budget doc | ✅ shipped |
+| **v0.8.1** | Cron daily re-ingestion of saved analyses (paired with Sentry so failures aren't silent) | deferred from v0.8.0 |
+| **v0.8.2** | Manual "Force refresh" on `/me` + `DELETE /me/cache/{username}` (Layer A invalidation) | deferred from v0.8.0 |
+| **v0.8.3** | On-demand `revalidateTag` for `/share/[slug]` ISR (closes v0.7.1's deferred share-page caching) | deferred from v0.7.1 |
+| **v0.8.4** | `vercel.json` → `vercel.ts` migration (Vercel 2026-02-27 knowledge update) | deferred from pre-v0.7.1 |
+| **v0.9.0** | Beta hardening — security review, abuse mitigation, load test, legal | pending |
 | **v1.0.0** | Public launch | pending |
 
 ---
@@ -296,22 +300,88 @@
 
 ## v0.8.0 — Polish + observability
 
-**Goal:** The product feels finished. We can see what users do and what breaks.
+**Goal:** By the end of this slice we can answer three questions in production: what broke (Sentry), what did users actually do (PostHog + web vitals), and is the page accessible (axe = 0 critical). Nothing else.
 
-**Slice scope:**
-- Sentry (frontend + backend)
-- PostHog or Plausible analytics
-- Structured logging on every backend route
-- 404 / 500 / rate-limit pages with on-voice copy
-- Accessibility audit (axe): zero criticals
-- Empty states and skeleton loaders everywhere
-- **Cron re-ingestion** for saved analyses (daily refresh) — paired with Sentry so cron failures aren't silent
-- **Manual "Force refresh"** button on `/me` and `DELETE /me/cache/{username}` backend route — invalidates the Layer A Report cache from v0.7.0
+**Design spec:** [`docs/superpowers/specs/2026-05-22-v0.8.0-polish-observability-design.md`](./docs/superpowers/specs/2026-05-22-v0.8.0-polish-observability-design.md).
+
+**Slice scope (locked 2026-05-22):**
+- **Backend observability** — `structlog` JSON logging + request-ID middleware + Sentry FE/BE init with PII scrub hook.
+- **Frontend observability** — Sentry browser SDK via `instrumentation.ts`; PostHog browser SDK with auto-pageviews + web-vitals capture (RUM, replaces the deferred Speed Insights idea — free-free 12-month retention vs Speed Insights' 30-day Hobby cap).
+- **Named PostHog events** — `analyze_submitted`, `share_toggled`, `share_card_copied`, `mode_toggled`, `sign_in_clicked`.
+- **On-voice failure pages** — new `app/not-found.tsx`; refresh `app/error.tsx` copy + add `Sentry.captureException` hook.
+- **Empty-state + skeleton audit** — verify `/me`, `/u/[username]/card`, `/share/[slug]` already have appropriate states (most do post-v0.7.2).
+- **Accessibility pass** — `@axe-core/cli` against `/`, `/u/octocat`, `/u/octocat/card`, `/me`, `/share/<slug>`; fix all criticals.
+- **Error budget doc** — `docs/OBSERVABILITY.md` defining critical-vs-acceptable classes + alert intent (rules wired later in a v0.8.x patch).
+
+**Deferred to v0.8.x patches:**
+- Cron daily re-ingestion → v0.8.1
+- Manual "Force refresh" + `DELETE /me/cache/{username}` → v0.8.2
+- On-demand `revalidateTag` for `/share/[slug]` ISR → v0.8.3
+- `vercel.json` → `vercel.ts` migration → v0.8.4
+- Sentry alert-rule wiring → v0.8.x once real error rates are known
+- CI integration of `@axe-core/cli` → v0.8.x
+
+Each deferred item is independent and earns its own patch release, matching the v0.7.x cadence.
 
 **Exit criteria:**
-- [ ] Error budget defined; dashboards live
-- [ ] Axe critical issues = 0
-- [ ] `CHANGELOG.md` + `docs/PROGRESS_LOG.md` updated; version `0.8.0`
+- [x] Backend Sentry catches a deliberate test exception with `request_id` tag attached; no PII in the event body.
+- [x] Frontend Sentry catches a deliberate client throw with source-mapped stack.
+- [x] PostHog dashboard shows all 5 named events flowing from prod within 24h of deploy.
+- [x] PostHog web-vitals capture identifies the prod LCP element on `/u/[username]` (closes v0.7.2's open gap).
+- [x] `npx @axe-core/cli` returns zero critical issues on all 5 audited routes.
+- [x] `docs/OBSERVABILITY.md` exists; defines critical vs acceptable error classes + alert intent.
+- [x] PII contract (spec §6) verified by test for every listed field.
+- [x] `CHANGELOG.md` + `docs/PROGRESS_LOG.md` updated; version `0.8.0` tagged + released.
+
+---
+
+## v0.8.1 — Cron daily re-ingestion (deferred from v0.8.0)
+
+**Goal:** Saved analyses refresh themselves overnight so a user who comes back tomorrow doesn't see stale data. Failures are visible because v0.8.0's Sentry is already in place.
+
+**Slice scope:**
+- Vercel Cron entry (likely `vercel.json` for now; folds into v0.8.4's `vercel.ts` migration later) hitting a new authenticated backend route `POST /cron/refresh-saved-analyses`.
+- Chunking: respect Vercel function timeout (300s) by processing N analyses per invocation; resume tokens persisted in Postgres if the queue is larger than one chunk.
+- Sentry breadcrumb / structured log for every refresh attempt; one Sentry capture per chunk failure.
+
+**Exit criteria:** TBD when the slice begins.
+
+---
+
+## v0.8.2 — Manual "Force refresh" (deferred from v0.8.0)
+
+**Goal:** Signed-in users can invalidate the Layer A Report cache for any of their saved analyses from `/me`.
+
+**Slice scope:**
+- Backend: `DELETE /me/cache/{username}` route — auth-required, deletes the `report:` key from Upstash. Logs the action.
+- Frontend: small "Force refresh" affordance on each `/me` grid item; tracked via PostHog `force_refresh_clicked`.
+
+**Exit criteria:** TBD when the slice begins.
+
+---
+
+## v0.8.3 — On-demand `revalidateTag` for `/share/[slug]` ISR (deferred from v0.7.1)
+
+**Goal:** Public share pages can be ISR-cached safely because revocation immediately busts the tag.
+
+**Slice scope:**
+- `/share/[slug]` route gets `unstable_cache` (or Next 16 Cache Components equivalent) with a per-slug tag.
+- Backend share-toggle endpoints (`POST` + `DELETE`) call a small frontend webhook (`POST /api/revalidate?tag=share:<slug>`) authenticated with a shared secret.
+- Both sides covered by tests including the "revoked slug renders 404 immediately" assertion.
+
+**Exit criteria:** TBD when the slice begins.
+
+---
+
+## v0.8.4 — `vercel.json` → `vercel.ts` migration
+
+**Goal:** Track the 2026-02-27 Vercel knowledge update by moving the project config to typed TypeScript.
+
+**Slice scope:**
+- Replace `vercel.json` with `vercel.ts` using `@vercel/config/v1`.
+- Move the `experimentalServices` declarations + any cron entries shipped in v0.8.1 to the typed config.
+
+**Exit criteria:** TBD when the slice begins.
 
 ---
 

README.md

@@ -43,7 +43,7 @@ Engineering insight first. AI flavor second. Scoring is deterministic and explai
 
 ## Status
 
-Pre-alpha. Latest shipped release is **v0.7.5** (Hotfix: roast/mentor toggle symmetric on mobile). Live at https://skill-issue-tau.vercel.app — GitHub OAuth sign-in, Neon Postgres persistence, `/me` history, opt-in `/share/[slug]` public links. The AI narrative layer (Roast + Mentor) runs on **Groq** (`llama-3.3-70b-versatile`). v0.7.0 added Upstash Redis caching (warm `/analyze` ≤ 200 ms); v0.7.1 trimmed 34 KB off the frontend bundle and switched to `next/image` for avatars; v0.7.2 prod-certified the perf budget (CLS 0.080 → **0** structurally, perf 90 → 94, LCP 2,804 → 2,773 ms) by rewriting the loading skeleton to match the real ResultsView and reserving SiteHeader height to kill the Suspense-fallback CLS. **v0.8.0 — Polish + observability (Sentry, PostHog, cron re-ingestion, on-demand share-page revalidation, LCP element identification)** is the next slice. See [`CHANGELOG.md`](./CHANGELOG.md) for shipped slices, [`PLAN.md`](./PLAN.md) for the full roadmap, and [`docs/PROGRESS_LOG.md`](./docs/PROGRESS_LOG.md) for the most recent session handoff.
+Pre-alpha. Latest shipped release is **v0.8.0** (Polish + Observability — Sentry FE+BE, PostHog events + web vitals, structured logging, axe-clean a11y, on-voice 404). Live at https://skill-issue-tau.vercel.app — GitHub OAuth sign-in, Neon Postgres persistence, `/me` history, opt-in `/share/[slug]` public links. The AI narrative layer (Roast + Mentor) runs on **Groq** (`llama-3.3-70b-versatile`). v0.7.0 added Upstash Redis caching (warm `/analyze` ≤ 200 ms); v0.7.1 trimmed 34 KB off the frontend bundle and switched to `next/image` for avatars; v0.7.2 prod-certified the perf budget (CLS 0.080 → **0** structurally, perf 90 → 94, LCP 2,804 → 2,773 ms) by rewriting the loading skeleton to match the real ResultsView and reserving SiteHeader height to kill the Suspense-fallback CLS. v0.8.0 shipped Sentry (FE+BE), PostHog (events + web vitals → closes the v0.7.2 LCP-element gap), structlog JSON logging, on-voice 404, and a full axe a11y pass (0 critical / 0 serious / 0 moderate). **v0.8.1 — Cron daily re-ingestion** is next. Cron re-ingestion, "Force refresh," `/share/[slug]` ISR revalidation, and `vercel.ts` migration are lifted into focused v0.8.1–v0.8.4 patches. See [`CHANGELOG.md`](./CHANGELOG.md) for shipped slices, [`PLAN.md`](./PLAN.md) for the full roadmap, and [`docs/PROGRESS_LOG.md`](./docs/PROGRESS_LOG.md) for the most recent session handoff.
 
 ---
 

backend/app/main.py

@@ -17,6 +17,7 @@
 from app.db.session import get_db
 from app.dependencies import get_cache, get_report_for_user
 from app.models import Report
+from app.observability import RequestIDMiddleware, init_logging, init_sentry
 from app.persistence.analyses import record_run, upsert_analysis
 from app.routers import analyses, auth, me, narrative, share
 from app.settings import VERSION, settings
@@ -26,6 +27,13 @@
 
 @asynccontextmanager
 async def lifespan(_: FastAPI):
+    init_logging(level=settings.log_level, log_format=settings.log_format)
+    init_sentry(
+        dsn=settings.sentry_dsn,
+        environment=settings.sentry_environment,
+        traces_sample_rate=settings.sentry_traces_sample_rate,
+        release=VERSION,
+    )
     try:
         async with engine.connect() as conn:
             await conn.execute(text("SELECT 1"))
@@ -55,6 +63,7 @@ async def _http_exc_handler(_request: Request, exc: StarletteHTTPException):
     allow_headers=["*"],
     allow_credentials=True,
 )
+app.add_middleware(RequestIDMiddleware)
 
 app.include_router(narrative.router)
 app.include_router(auth.router)

backend/app/observability/__init__.py

@@ -0,0 +1,12 @@
+"""Observability primitives — structlog, request-ID middleware, Sentry."""
+from app.observability.logging import get_request_id, init_logging
+from app.observability.middleware import RequestIDMiddleware
+from app.observability.sentry import init_sentry, scrub_event
+
+__all__ = [
+    "RequestIDMiddleware",
+    "get_request_id",
+    "init_logging",
+    "init_sentry",
+    "scrub_event",
+]