quantum-bridge-mcp/docs/superpowers/plans/2026-04-29-quantum-tutor/README.md

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.

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