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

Quantum Tutor Implementation Plan (rev 2 — split index)

For agentic workers: this plan is split into 18 atomic sub-tasks. Each task has its own file under 2026-04-29-quantum-tutor/. When executing, load only the matching sub-task file plus the design spec — never load this index nor sibling tasks. Use superpowers:executing-plans or superpowers:subagent-driven-development.

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.

---

Sub-tasks (in order)

#	File	Goal	Depends on
0	00-prerequisites.md	QuantumBridgeServer holds Arc<dyn Backend> + tempfile dev-dep	—
1	01-curriculum-types.md	Curriculum types + module 1 JSON	0
2	02-curriculum-loader.md	OnceLock-cached CurriculumLoader, no expect()	1
3	03-progress-store.md	Sandboxable ProgressStore (QB_PROGRESS_PATH)	0
4	04-circuit-analyzer.md	AST-based gate listing	0
5	05-exercise-checker.md	ExerciseChecker with &dyn Backend, 2σ, statevector	2, 4
6	06-get-lesson.md	get_lesson response (first uncompleted lesson)	2, 3
7	07-check-exercise.md	check_exercise response (structured diagnostics)	5, 6
8	08-explain-result.md	explain_result response (AST-based)	4, 7
9	09-get-progress.md	get_progress response (current_lesson + unlock)	8
10	10-wire-tools.md	Register the 4 MCP tools on the server	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 (phase kickback)	14
16	16-curriculum-module-7.md	Module 7 — Grover + 18-exercise assertion	15
17	17-integration-tests.md	MCP integration tests + golden files	16

---

Architecture invariants enforced by this plan

(These are the only invariants you need to remember when walking sub-tasks; each task file repeats the relevant ones.)

• QuantumBridgeServer owns Arc<dyn Backend>; tutor tools route through self.backend.
• ExerciseChecker::check_circuit(backend: &dyn Backend, …) — never instantiates LocalSimulator directly (CLAUDE.md §3 / spec §3).
• CurriculumLoader lazily parses an embedded JSON via OnceLock; returns Result, no expect() (CLAUDE.md §10).
• ProgressStore is sandboxed via QB_PROGRESS_PATH; missing HOME returns Err, never falls back to ..
• CircuitAnalyzer exposes AST-based gate listing — explain_result does not string-match the QASM source (spec §2.3).
• 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, spec §2.2).
• Module 6 uses phase kickback rather than teleportation (the v1 executor walks past Stmt::If).

---

Changelog vs. rev 1 (legacy single-file plan)

The previous monolithic plan was 1767 lines and contained:

1. DIP violations (LocalSimulator::new() inside ExerciseChecker).
2. String-matching in explain_result.
3. expect() in production (CurriculumLoader::load).
4. get_lesson always returning lesson 1.
5. 3σ tolerance instead of spec's 2σ.
6. statevector_check defined but unused.
7. Validation errors collapsed to McpError.
8. Test bugs (process-id collision in ProgressStore tests; integration tests writing to real ~/.config/).
9. Module 6 teleportation that the v1 executor cannot run.
10. Task 5 (4 tools) and Task 7 (6 modules) bundled into single commits.

Rev 2 fixes all of the above and splits the work into 18 atomic, single-responsibility tasks.