# Quantum Tutor — sub-task index

**Goal:** Add 4 MCP tools (`get_lesson`, `check_exercise`, `explain_result`, `get_progress`) to quantum-bridge-mcp, backed by a JSON curriculum (7 modules / 18 exercises) and a persistent progress file.

**Spec:** [`docs/superpowers/specs/2026-04-29-quantum-tutor-design.md`](../../specs/2026-04-29-quantum-tutor-design.md).

This plan is split into 18 atomic sub-tasks. Each file is self-contained — when executing a task, load only the matching file plus the spec. Do not load the master plan or sibling tasks.

## Execution order

| # | File | Goal | Depends on |
|---|------|------|------------|
| 0 | [`00-prerequisites.md`](00-prerequisites.md) | Backend injection seam + tempfile dev-dep | — |
| 1 | [`01-curriculum-types.md`](01-curriculum-types.md) | Curriculum types + module 1 JSON | 0 |
| 2 | [`02-curriculum-loader.md`](02-curriculum-loader.md) | `OnceLock`-cached `CurriculumLoader` | 1 |
| 3 | [`03-progress-store.md`](03-progress-store.md) | Sandboxable `ProgressStore` | 0 |
| 4 | [`04-circuit-analyzer.md`](04-circuit-analyzer.md) | AST-based gate listing | 0 |
| 5 | [`05-exercise-checker.md`](05-exercise-checker.md) | `ExerciseChecker` with `&dyn Backend` | 2, 4 |
| 6 | [`06-get-lesson.md`](06-get-lesson.md) | `get_lesson` response | 2, 3 |
| 7 | [`07-check-exercise.md`](07-check-exercise.md) | `check_exercise` response | 5, 6 |
| 8 | [`08-explain-result.md`](08-explain-result.md) | `explain_result` response | 4, 7 |
| 9 | [`09-get-progress.md`](09-get-progress.md) | `get_progress` response | 8 |
| 10 | [`10-wire-tools.md`](10-wire-tools.md) | Register the 4 tools on `QuantumBridgeServer` | 9 |
| 11 | [`11-curriculum-module-2.md`](11-curriculum-module-2.md) | Module 2 — Superposition | 10 |
| 12 | [`12-curriculum-module-3.md`](12-curriculum-module-3.md) | Module 3 — Interférence | 11 |
| 13 | [`13-curriculum-module-4.md`](13-curriculum-module-4.md) | Module 4 — Intrication | 12 |
| 14 | [`14-curriculum-module-5.md`](14-curriculum-module-5.md) | Module 5 — Multi-qubits | 13 |
| 15 | [`15-curriculum-module-6.md`](15-curriculum-module-6.md) | Module 6 — Premiers algorithmes | 14 |
| 16 | [`16-curriculum-module-7.md`](16-curriculum-module-7.md) | Module 7 — Grover | 15 |
| 17 | [`17-integration-tests.md`](17-integration-tests.md) | Integration tests + golden files | 16 |

## Architecture summary (the only context you need from the master plan)

- `QuantumBridgeServer` owns `Arc<dyn Backend>`; tutor tools route through `self.backend`.
- `ExerciseChecker::check_circuit(backend: &dyn Backend, ...)` — never instantiates `LocalSimulator` directly.
- `CurriculumLoader` lazily parses an embedded JSON via `OnceLock`; returns `Result`, no `expect()`.
- `ProgressStore` is sandboxed via `QB_PROGRESS_PATH`; missing `HOME` returns `Err`.
- `CircuitAnalyzer` (new module) exposes AST-based gate listing — `explain_result` does not string-match the QASM source.
- Statistical tolerance for exercise checks is **2σ** below `min_ratio` (spec §3).
- `check_exercise` distinguishes protocol errors (unknown exercise → `McpError`) from validation errors (circuit invalid → structured `diagnostics` payload).
- Module 6 teleportation exercise was replaced by phase kickback (the v1 executor ignores classical-controlled gates).

## Convention per task file

Each task file contains:
1. **Goal** — single paragraph.
2. **Prerequisites** — which tasks must already be merged.
3. **Files** — what is created or modified.
4. **Steps** — `- [ ]` checkboxes with code blocks and verification commands.
5. **Commit** — exact `git commit` message.

Use `superpowers:executing-plans` or `superpowers:subagent-driven-development` to walk one task at a time.