Vincent Bourdon
66 lines
5.0 KiB
Markdown
66 lines
5.0 KiB
Markdown
# 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/`](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`](../specs/2026-04-29-quantum-tutor-design.md).
|
||
|
||
---
|
||
|
||
## Sub-tasks (in order)
|
||
|
||
| # | File | Goal | Depends on |
|
||
|---|------|------|------------|
|
||
| 0 | [`00-prerequisites.md`](2026-04-29-quantum-tutor/00-prerequisites.md) | `QuantumBridgeServer` holds `Arc<dyn Backend>` + `tempfile` dev-dep | — |
|
||
| 1 | [`01-curriculum-types.md`](2026-04-29-quantum-tutor/01-curriculum-types.md) | Curriculum types + module 1 JSON | 0 |
|
||
| 2 | [`02-curriculum-loader.md`](2026-04-29-quantum-tutor/02-curriculum-loader.md) | `OnceLock`-cached `CurriculumLoader`, no `expect()` | 1 |
|
||
| 3 | [`03-progress-store.md`](2026-04-29-quantum-tutor/03-progress-store.md) | Sandboxable `ProgressStore` (`QB_PROGRESS_PATH`) | 0 |
|
||
| 4 | [`04-circuit-analyzer.md`](2026-04-29-quantum-tutor/04-circuit-analyzer.md) | AST-based gate listing | 0 |
|
||
| 5 | [`05-exercise-checker.md`](2026-04-29-quantum-tutor/05-exercise-checker.md) | `ExerciseChecker` with `&dyn Backend`, 2σ, statevector | 2, 4 |
|
||
| 6 | [`06-get-lesson.md`](2026-04-29-quantum-tutor/06-get-lesson.md) | `get_lesson` response (first uncompleted lesson) | 2, 3 |
|
||
| 7 | [`07-check-exercise.md`](2026-04-29-quantum-tutor/07-check-exercise.md) | `check_exercise` response (structured diagnostics) | 5, 6 |
|
||
| 8 | [`08-explain-result.md`](2026-04-29-quantum-tutor/08-explain-result.md) | `explain_result` response (AST-based) | 4, 7 |
|
||
| 9 | [`09-get-progress.md`](2026-04-29-quantum-tutor/09-get-progress.md) | `get_progress` response (current_lesson + unlock) | 8 |
|
||
| 10 | [`10-wire-tools.md`](2026-04-29-quantum-tutor/10-wire-tools.md) | Register the 4 MCP tools on the server | 9 |
|
||
| 11 | [`11-curriculum-module-2.md`](2026-04-29-quantum-tutor/11-curriculum-module-2.md) | Module 2 — Superposition | 10 |
|
||
| 12 | [`12-curriculum-module-3.md`](2026-04-29-quantum-tutor/12-curriculum-module-3.md) | Module 3 — Interférence | 11 |
|
||
| 13 | [`13-curriculum-module-4.md`](2026-04-29-quantum-tutor/13-curriculum-module-4.md) | Module 4 — Intrication | 12 |
|
||
| 14 | [`14-curriculum-module-5.md`](2026-04-29-quantum-tutor/14-curriculum-module-5.md) | Module 5 — Multi-qubits | 13 |
|
||
| 15 | [`15-curriculum-module-6.md`](2026-04-29-quantum-tutor/15-curriculum-module-6.md) | Module 6 — Premiers algorithmes (phase kickback) | 14 |
|
||
| 16 | [`16-curriculum-module-7.md`](2026-04-29-quantum-tutor/16-curriculum-module-7.md) | Module 7 — Grover + 18-exercise assertion | 15 |
|
||
| 17 | [`17-integration-tests.md`](2026-04-29-quantum-tutor/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.
|