Revamp the quiz system: flow is bare-bones and half-wired, UI needs a redesign

[AndresL230]

Why

The quiz experience is one of the core loops (quiz → mastery → graph → XP) but today it's the plainest surface in the app: a single MCQ flow with three dropdowns, unstyled beyond inline styles, no history, no final breakdown, and several selector options that are outright broken. This epic covers a functional + visual revamp.

Current state (surveyed 2026-08-12)

Backend (backend/routes/quiz.py): two endpoints — POST /api/quiz/generate and POST /api/quiz/submit. Generation runs through the Pydantic AI quiz_agent (#145) with weak-area/misconception/recent-attempt tools and RAG course-material grounding; submit does an atomic completed_at claim, mastery via apply_graph_update, XP + achievements, and regenerates adaptive quiz_context in a background task. Questions are MCQ-only, single-correct, A–F labels. questions_json/answers_json are encrypted at rest (#521/#527).

Frontend: components/QuizPanel.tsx (398 lines, all inline styles) drives four phases: select (course → concept → count → difficulty) → active (one question at a time) → per-question review → results. Selection logic lives in lib/quizSelection.ts (unit-tested). Mounted at (shell)/quiz via components/screens/Quiz.tsx; deep-linkable via ?concept=.

Broken or half-wired today

These were found while surveying; each is independently fixable ahead of the redesign:

1. "Adaptive" difficulty is dead. QuizPanel.tsx:64-69 offers adaptive, but routes/quiz.py:39 (VALID_DIFFICULTIES = {easy, medium, hard}) 400s it — the request never reaches the agent. The dropdown option has been shipping a guaranteed error.
2. "15 questions" is dead. QuizPanel.tsx:58-62 offers 5/10/15, but models/__init__.py:49 caps num_questions at le=10 → Pydantic 422.
3. The results screen ignores the server's per-question results. submitQuiz returns a results[] array (per-question correctness, correct answer, explanation) that the results phase never renders — students get a bare % + mastery line with no breakdown and no way to review what they missed.
4. The full answer key ships to the client at generate time. Every option carries correct: true/false in the /generate response (the review phase grades client-side from it). Server re-scores at submit, but the key is one devtools tab away — grading should be server-side end to end.
5. Adaptive quiz context has silently not persisted since migration 0025 — tracked as quiz_context lost UNIQUE (user_id, concept_node_id) in 0025 — save_quiz_context's upsert 42P10s and the failure is swallowed #529 (quiz_context lost its UNIQUE, the upsert 42P10s and is swallowed). The agent's adaptive inputs are running on stale/absent context; any "truly adaptive" work depends on that fix.

Proposed scope (to be shaped before implementation)

Functionality

• Question variety beyond single-correct MCQ: e.g. multi-select, true/false, cloze/short-answer (short-answer implies LLM grading — new agent task, needs a function-mode handler).
• A real adaptive mode: difficulty adjusts within the quiz from answers so far, backed by the (fixed) quiz_context — replacing the broken dropdown option.
• Quiz history: quiz_attempts already stores plaintext score/total/difficulty/completed_at scalars precisely so analytics stay possible (Quiz performance data stored in plaintext (questions_json, answers_json, quiz_context) #521) — there is currently no route or UI reading them. Attempt list per concept/course, score trend, "retake the ones I missed".
• Resume/abandon handling: unanswered attempt rows currently just orphan.
• Post-quiz review surface built from the server results[] (fixes 3): missed-question review with explanations and per-concept breakdown, linking into the tutor (Explain this already deep-links to /learn).
• Server-side grading of the in-quiz review verdict (fixes 4).

UI/UX

• Rebuild QuizPanel on the components/ui primitives + design tokens (Canopy: the component-system refactor retired inline-style surfaces; QuizPanel predates it).
• Real visual identity for the quiz surface: progress indicator, question transitions, a results screen worth reaching (per-question breakdown, per-concept mastery deltas, XP earned — gamification feat(gamification): XP, levels, achievements catalog, and leaderboards #505 already awards it, the UI never shows it).
• Keyboard support (A–D / 1–4 to select, Enter to submit), reduced-motion compliance, focus management between phases.

Constraints

• LLM changes go through agents/ + agents/_providers.py slots only (ADR 0024); any new request-path agent task needs a handler in agents/function_handlers_e2e.py or the E2E lanes break with UnregisteredHandlerError.
• questions_json/answers_json/context_json encryption boundaries (Quiz performance data stored in plaintext (questions_json, answers_json, quiz_context) #521) must survive any schema/shape changes; new sensitive columns need ciphertext-oracle manifest entries.
• The test(e2e): journey — quiz answer → mastery update (UI + DB) #393 quiz→mastery Playwright journey pins the current quiz-* testids (docs/frontend-testids.md) — the revamp must update the journey in the same PR, and per CLAUDE.md the E2E gate (hermetic + Chapter 1 + oracles) applies pre-merge.
• quiz_attempts.difficulty is CHECK-constrained (0025): a real adaptive mode either fits the enum or ships a migration.

Related

• quiz_context lost UNIQUE (user_id, concept_node_id) in 0025 — save_quiz_context's upsert 42P10s and the failure is swallowed #529 — quiz_context UNIQUE regression (blocker for any adaptive work)
• [P2] Agent migration: quiz generation + course-context regen → agent #145 — quiz LLM seams → Pydantic AI agents (done, the seam to build on)
• Quiz performance data stored in plaintext (questions_json, answers_json, quiz_context) #521/feat(quiz): encrypt quiz performance JSON at rest (#521) #527 — quiz data encryption at rest
• feat(gamification): XP, levels, achievements catalog, and leaderboards #505 — XP/achievements already hook quiz submit
• fix(quiz): UI submit sends selected, backend requires selected_label — every quiz submission 422s #438 — the last shell revamp broke quiz submits (422) and only the E2E journey caught it; same risk class applies here

Items 1–4 under "Broken or half-wired" are small and independently shippable; they can be split into standalone bug issues if we want fixes ahead of the epic.

[AndresL230]

Pre-revamp backend repair batch filed from the 2026-08-12 audit verification (all Rule-0 claims confirmed against code; forensics on #529):

• quiz A (P0): accept 'adaptive' difficulty, single-source /api/quiz/config, stable error envelope #540 — A (P0, ships alone): adaptive difficulty, GET /api/quiz/config, stable error envelope
• quiz_context lost UNIQUE (user_id, concept_node_id) in 0025 — save_quiz_context's upsert 42P10s and the failure is swallowed #529 — B: repair the adaptive context loop (UNIQUE lost in 0025; staging has 0 rows, write dead since 2026-06-23)
• quiz C: server-authoritative grading — per-question answer endpoint, quiz_responses table, answer-key deprecation #541 — C: server-authoritative grading (/attempts/{id}/answer, quiz_responses, answer-key deprecation → quiz: flip include_answer_key default to false, then delete it once the #537 client ships #546)
• quiz D: attempt lifecycle — persist mastery snapshot, status + abandonment sweep, resume + paginated history, completed-only achievements #542 — D: attempt lifecycle (mastery snapshot, status/abandonment, resume, history, completed-only achievements)
• quiz E: scoring/generation correctness — mastery-delta config seam, honest delivered_count, wire validation, concurrency tests #543 — E: mastery-delta config seam + generation honesty/validation
• quiz F: cost, abuse, observability — rate limit + spend guard, timeout/502 taxonomy, failure events, scope tests #544 — F: rate limit, spend guard, timeout taxonomy, failure events
• quiz G: test gate for the pre-revamp batch — real-DB round-trips, subcutaneous coverage, #393 journey, #529 regression guard #545 — G: cross-cutting test gate (real-DB assertions, test(e2e): journey — quiz answer → mastery update (UI + DB) #393 journey, quiz_context lost UNIQUE (user_id, concept_node_id) in 0025 — save_quiz_context's upsert 42P10s and the failure is swallowed #529 regression guard)

Order: A → B → C → D → E → F, one PR each, each green before the next. The new-flow API lands behind explicit compat flags; nothing builds to the current QuizPanel.tsx contract.