Add codex implementation brief

CODEX_PROMPT.md

@@ -0,0 +1,55 @@
+# Codex implementation brief — Live In-Lecture Quiz Portal
+
+You are implementing a complete, production-quality web application from a detailed specification. The user (Prof. Ameer H. Khan) wants to use this for an in-lecture engagement quiz with his students next week.
+
+## Required reading
+**Read `SPEC.md` in full before writing any code.** It is the authoritative specification. Sections 1-18 cover everything: routes, data model, state machine, WebSocket protocol, frontend pages, security, project layout, and acceptance criteria. Implement exactly what the spec says.
+
+## Working directory
+You are at `/home/ameer/RD/Projects/Apps/quiz/`. This is your workspace root. The spec, a baseline git commit, and `.git/` are already in place.
+
+## Your responsibilities, end-to-end
+
+1. **Implement** the full application per `SPEC.md` — backend (FastAPI + websockets + aiosqlite), frontend (vanilla HTML/CSS/JS), data model, scoring, state machine, all routes.
+2. **Set up** the project structure exactly as specified in §12 (`pyproject.toml`, `.env.example`, `.gitignore`, `app/`, `static/`, `tests/`, `examples/`).
+3. **Author** an example question pool at `examples/week9_pool.json` with 10 plausible MCQs about Computer Organization Week 9 recap topics (CPU structure, multi-cycle datapath, hardwired control unit, FSM, microprogrammed control, hardwired vs microprogrammed tradeoffs). It is fine to generate plausible technical content; the user will replace with his real questions later.
+4. **Write tests** as listed in §14 — unit, API, WebSocket, edge-case, and the load-simulation test.
+5. **Run tests iteratively** until all pass: `pytest -q` green, `pytest --cov=app` at least 80% line coverage on `app/`. Fix bugs as they surface. Iterate until clean.
+6. **Smoke test** by starting `uvicorn app.main:app` with a test `.env`, verify it boots without errors and `GET /healthz` responds.
+7. **Document** in `README.md` (install + run + test + manual smoke test) and `NOTES.md` (any non-obvious choices or deviations from the spec, per §17).
+8. **Commit incrementally** to git as you go — separate commits for "scaffold project", "data model + db", "scoring + pool validation", "auth + cookies", "student API + WS", "admin API + WS", "frontend student", "frontend admin", "tests", "fixes from test runs". This makes the human review tractable.
+
+## Operational rules
+
+- **Use `python3.11` or newer** (system has `python3` available; check version; if <3.11, document fallback in NOTES).
+- **Create a `.venv`** inside the project dir, install deps via `pip install -e '.[dev]'`. Do NOT use conda or shared envs.
+- **Pin dependencies** with compatible-release operators (e.g. `fastapi~=0.115`).
+- **Do not** invent new features beyond the spec. Where the spec is silent, pick the simplest reasonable option and document in `NOTES.md`.
+- **Do not** add Docker, systemd, Caddy, DNS, or any deployment config. §15 explicitly defers these to the human.
+- **Do not** commit `.env`, `quiz.db`, `__pycache__`, or `.venv` (`.gitignore` handles this).
+- **Do not** add em-dashes (`—` or `---`) in user-visible text (frontend strings, README, error messages). Use commas, semicolons, periods, parens, or colons. (User preference; internal scratch is unconstrained.)
+
+## When you are done
+
+Write a final summary to `IMPLEMENTATION_REPORT.md` in the project root covering:
+- What was built (file inventory + LoC counts).
+- Test results: full `pytest -q` output, coverage percentage.
+- Any deviations from the spec (with rationale).
+- How to run locally (3-5 lines of shell).
+- Any open issues, known bugs, or things you noticed but couldn't fix.
+- Anything you'd recommend the human review carefully.
+
+Then stop. Do not deploy, do not push to remote, do not modify anything outside `/home/ameer/RD/Projects/Apps/quiz/`.
+
+## Acceptance bar
+
+The implementation is acceptable when:
+- All test categories from SPEC §14 are present.
+- `pytest -q` is fully green.
+- Line coverage on `app/` is ≥ 80%.
+- The load simulation test passes with 50 simulated students.
+- `uvicorn app.main:app` boots without errors.
+- `README.md` and `NOTES.md` are present and informative.
+- Git history shows incremental commits.
+
+If you hit a blocker you genuinely cannot resolve, document it clearly in `IMPLEMENTATION_REPORT.md` under "Open issues" and continue with the rest of the work; do not halt the whole job for a single recoverable issue.