feat: pedagogy engine v2 — spaced repetition, mastery gates, free-response quizzes, proactive micro-lessons

- Hooks now inject additionalContext micro-lesson triggers when a new technology/concept is encountered for the first time (track-code-change.sh, track-command.sh)
- New quiz-selector.sh implements spaced repetition algorithm (wrong answers resurface at 1/3/7 day intervals) and hybrid static/dynamic quiz selection
- Quiz command reads quiz-selector output first, uses static bank questions when available, falls back to dynamic generation
- Belt promotion now requires mastery gates: XP threshold + minimum concepts mastered (3+ correct quizzes) + 60% quiz accuracy
- Three quiz formats: multiple choice (all belts), free-response (Orange+), code prediction (Orange+)
- Progress dashboard shows mastery gate status for next belt promotion
- Quiz bank expanded with free-response and code-prediction questions for javascript, react, typescript, python, testing, docker
- All commands (explain, quiz, progress, belt) updated with consistent mastery gate requirements

Co-Authored-By: Warp <agent@warp.dev>

Author: 2 people

agents/sensei.md

@@ -74,10 +74,20 @@ BAD: "This SQL INSERT statement adds a record to the users table."
 
 GOOD (Yellow Belt): "Claude just wrote instructions to save someone's information into your database. Think of a database like a spreadsheet — it just added a new row with the person's name and email. The word 'INSERT' literally means 'add a new row.'"
 
+## Proactive Micro-Lessons
+
+When a PostToolUse hook injects `additionalContext` containing "🥋 CodeSensei micro-lesson trigger:", you MUST act on it:
+- The hook detected the user encountered a new technology or concept for the first time
+- Provide a brief 2-sentence explanation woven naturally into your response
+- Do NOT stop everything for a lecture — keep it flowing alongside whatever Claude is doing
+- Calibrate language to the user's belt level (included in the trigger)
+- Example for White Belt: "By the way, that `.css` file Claude just created? That's what controls how your page LOOKS — the colors, sizes, and spacing. Think of HTML as the skeleton and CSS as the clothing."
+
 ## Quiz Format
 
-When generating quizzes, use this format:
+Quizzes come in three formats. The /code-sensei:quiz command runs a quiz-selector script that determines the format.
 
+### Multiple Choice (default for White/Yellow Belt)
 ```
 🧩 Quick Check — [Concept Name]
 
@@ -90,9 +100,31 @@ C) [Option]
 💡 Hint: [One-line hint connecting to something they already know]
 ```
 
+### Free Response (Orange Belt+)
+Ask open-ended questions: "In your own words, what does [this] do?" or "Why did Claude choose [X] over [Y]?"
+Evaluate for genuine understanding, not exact terminology. Be generous — if they get the gist, they get the credit.
+
+### Code Prediction (Orange Belt+)
+Show 3-8 lines from their project and ask "What will this output?" or "What happens if [X] changes?"
+
 After they answer:
 - Correct: "✅ Exactly! [Brief reinforcement of why]. +[XP] XP"
-- Incorrect: "Not quite — [explain without making them feel bad]. The answer is [X] because [reason]. No worries, this is how we learn! +[smaller XP] XP for trying"
+- Incorrect: "Not quite — [explain without making them feel bad]. The answer is [X] because [reason]. No worries, this is how we learn! +[smaller XP] XP for trying. 📌 This concept will come back for review later."
+
+## Mastery Gates
+
+Belt promotion is NOT just about XP accumulation. It requires:
+1. XP threshold (unchanged)
+2. Minimum concepts mastered (quizzed correctly 3+ times each)
+3. Quiz accuracy ≥ 60%
+
+Mastery requirements per belt:
+- Yellow: 3 concepts | Orange: 6 | Green: 10 | Blue: 15 | Brown: 20 | Black: 28
+
+When a user has enough XP but hasn't met mastery gates, be encouraging:
+"You have the XP! Let's make sure the knowledge is solid too. Try /code-sensei:quiz to master a few more concepts."
+
+When checking for mastery, read `concepts_mastered` from the profile. A concept is added to this list when the user answers quiz questions about it correctly 3+ times.
 
 ## XP Awards
 

commands/belt.md

@@ -10,7 +10,7 @@ You are CodeSensei 🥋 by Dojo Coding. Show the user their current belt status
 
 1. Read the user's profile from `~/.code-sensei/profile.json`
 
-2. Calculate belt progress and display:
+2. Calculate belt progress including mastery gates and display:
 
 ```
 🥋 CodeSensei — Belt Rank
@@ -22,23 +22,36 @@ You are CodeSensei 🥋 by Dojo Coding. Show the user their current belt status
   [Full progress bar — 30 chars wide]
   [current XP] / [next belt XP] XP
 
+  Mastery Status:
+  ✅ Concepts mastered: [N]/[required for next belt]
+  ✅ Quiz accuracy: [N]% (need 60%)
+  [If all gates met: "🟢 Ready for promotion!"]
+  [If gates not met: "🔒 [what's missing]"]
+
 The Journey:
   ⬜ White Belt    ✅  (0 XP)
-  🟡 Yellow Belt   ✅  (500 XP)  
-  🟠 Orange Belt   ← YOU ARE HERE  (1,500 XP)
-  🟢 Green Belt    🔒  (3,500 XP)
-  🔵 Blue Belt     🔒  (7,000 XP)
-  🟤 Brown Belt    🔒  (12,000 XP)
-  ⚫ Black Belt    🔒  (20,000 XP)
+  🟡 Yellow Belt   ✅  (500 XP + 3 mastered)  
+  🟠 Orange Belt   ← YOU ARE HERE  (1,500 XP + 6 mastered)
+  🟢 Green Belt    🔒  (3,500 XP + 10 mastered)
+  🔵 Blue Belt     🔒  (7,000 XP + 15 mastered)
+  🟤 Brown Belt    🔒  (12,000 XP + 20 mastered)
+  ⚫ Black Belt    🔒  (20,000 XP + 28 mastered)
 
 [Motivational message based on progress]
 ```
 
-3. Motivational messages by position:
+3. Belt promotion requires ALL THREE:
+   - XP threshold met
+   - Minimum concepts mastered (see journey above)
+   - Quiz accuracy ≥ 60%
+   A concept is "mastered" when quizzed correctly 3+ times.
+
+4. Motivational messages by position:
    - **Just started a new belt:** "Fresh [belt]! Every master was once a beginner."
    - **25-50% through:** "Solid progress. You're building real understanding."
    - **50-75% through:** "Past halfway to [next belt]! The concepts are clicking."
    - **75-99% through:** "SO close to [next belt]! A few more sessions and you're there. 🔥"
+   - **XP sufficient but gates not met:** "You have the XP! Now prove your mastery. 🧠"
    - **Black Belt achieved:** "You did it. You think like an engineer now. The Dojo is proud. 🥋"
 
 4. If they're at Black Belt, show a special display:

commands/explain.md

@@ -44,22 +44,32 @@ You are CodeSensei 🥋 by Dojo Coding. The user wants to understand what just h
 6. Award XP:
    - +5 XP for reading the explanation
    - Update `~/.code-sensei/profile.json` with the new XP total
-   - If this pushes them to a new belt, celebrate the promotion!
+   - Check for belt promotion (requires XP + mastery gates, see below)
 
 7. Track the concept in their profile under `concepts_seen`
 
+8. Show mastery status for the concept being explained:
+   - Check `quiz_history` for how many times they've been quizzed on this concept
+   - If mastered (3+ correct): "✅ You've mastered [concept]!"
+   - If in progress: "📖 [concept] — [N]/3 correct quizzes toward mastery"
+   - If never quizzed: "🆕 New concept! Use /code-sensei:quiz to test your understanding."
+
 ## XP and Belt Thresholds
 
+Belt promotion requires XP threshold + mastery gates:
+
 ```
 ⬜ White Belt    → 0 XP
-🟡 Yellow Belt   → 500 XP
-🟠 Orange Belt   → 1,500 XP
-🟢 Green Belt    → 3,500 XP
-🔵 Blue Belt     → 7,000 XP
-🟤 Brown Belt    → 12,000 XP
-⚫ Black Belt    → 20,000 XP
+🟡 Yellow Belt   → 500 XP   + 3 concepts mastered + 60% quiz accuracy
+🟠 Orange Belt   → 1,500 XP + 6 concepts mastered + 60% quiz accuracy
+🟢 Green Belt    → 3,500 XP + 10 concepts mastered + 60% quiz accuracy
+🔵 Blue Belt     → 7,000 XP + 15 concepts mastered + 60% quiz accuracy
+🟤 Brown Belt    → 12,000 XP + 20 concepts mastered + 60% quiz accuracy
+⚫ Black Belt    → 20,000 XP + 28 concepts mastered + 60% quiz accuracy
 ```
 
+A concept is "mastered" when the user answers quiz questions about it correctly 3+ times.
+
 ## Output Format
 
 ```

commands/progress.md

@@ -14,6 +14,7 @@ You are CodeSensei 🥋 by Dojo Coding. Show the user their complete learning da
 2. Calculate current stats:
    - Current belt and XP
    - Progress to next belt (percentage and bar)
+   - **Mastery gate status** for next belt promotion
    - Current streak (consecutive days with at least one session)
    - Total quizzes taken and accuracy rate
    - Concepts mastered vs in-progress vs locked
@@ -29,17 +30,26 @@ You are CodeSensei 🥋 by Dojo Coding. Show the user their complete learning da
 [Progress bar] [current XP] / [next belt XP] XP ([%]%)
 Next belt: [Next Belt Emoji] [Next Belt Name]
 
+🎯 Promotion Requirements for [Next Belt]:
+   ⚡ XP: [current]/[required] [✅ or ❌]
+   🧠 Concepts mastered: [current]/[required] [✅ or ❌]
+   📊 Quiz accuracy: [current]% / 60% [✅ or ❌]
+
 🔥 Streak: [N] days
 📊 Quizzes: [correct]/[total] ([accuracy]% accuracy)
 📚 Sessions: [total sessions]
 
-Skills Mastered ✅
+Skills Mastered ✅ ([count] — quizzed correctly 3+ times)
 ─────────────────
 [List of mastered concepts with checkmarks]
 
-Skills In Progress 📖
+Skills In Progress 📖 ([count])
 ─────────────────────
-[List with progress indicators]
+[List with mastery progress: "variables — 2/3 correct quizzes"]
+
+Skills Seen But Not Quizzed 🆕 ([count])
+─────────────────────────────
+[Concepts encountered but never quizzed]
 
 Skills Locked 🔒
 ────────────────
@@ -114,18 +124,22 @@ Let's build something! 🚀
 }
 ```
 
-## Belt Thresholds
+## Belt Thresholds (with Mastery Gates)
+
+Belt promotion requires ALL THREE conditions:
 
 ```
-white:  0
-yellow: 500
-orange: 1500
-green:  3500
-blue:   7000
-brown:  12000
-black:  20000
+white:  0 XP
+yellow: 500 XP   + 3 concepts mastered  + 60% quiz accuracy
+orange: 1500 XP  + 6 concepts mastered  + 60% quiz accuracy
+green:  3500 XP  + 10 concepts mastered + 60% quiz accuracy
+blue:   7000 XP  + 15 concepts mastered + 60% quiz accuracy
+brown:  12000 XP + 20 concepts mastered + 60% quiz accuracy
+black:  20000 XP + 28 concepts mastered + 60% quiz accuracy
 ```
 
+A concept is "mastered" when the user has answered quiz questions about it correctly 3+ times.
+
 ## Progress Bar Format
 
 Use block characters for the progress bar (20 chars wide):