feat(personal-tutor): add desirable-difficulty hooks

[minsoo-web]

Summary

Cross-session retrieval is now the only path to understood. Previously the personal-tutor skill let a learner pass a quiz with the answer still echoing in working memory ("fluency illusion") and mark a concept understood in the same session it was first taught — not really retention. This PR introduces Bjork's "desirable difficulty" hooks: same-session warm quizzes cap at partial, a Cold quiz pending: yes flag schedules retrieval verification for the next session, and a Phase 5 self-audit drift guard mechanically enforces the rule.

What changed

Mechanism	Effect
Phase 2.0 Cold Quiz Sweep	New session phase that fires when any node has Cold quiz pending: yes. Runs before any new teaching, with no re-explanation of the concept
Iron Rule #6	"Never advance to understood within the same session a node was first taught." Phase 5 self-audit reverts violations back to partial
R5 sole scheduler	Every new-concept warm pass (hint or no hint) sets Cold quiz pending: yes. Cold quiz is the only path to understood for first-taught nodes
Generation Effect	Phase 3 now starts with a Predict step — learner guesses before Explain, and Explain anchors on the guess
Deterministic format rotation	feynman → apply → analyze → apply (no return to feynman). Last quiz format unchanged on fail, so failure never escalates the learner into a higher Bloom level
3-strike downgrade	3 consecutive failed or passed (hint used) entries with no passed (no hint) between → partial → gap, breaks indefinite hint-pass loops
Path B escape valve	Review-slot warm pass without hints + prior cold attempt → partial → understood. Rescues nodes whose cold quiz was attempted-but-not-cleanly-passed

Schema additions: Cold quiz pending and Last quiz format lines per node. Read-time defaults + write-time touched-node-only migration — no batch rewrite of existing graphs.

Session flow

flowchart TB
    A[Session Start] --> B{Cold quiz<br/>pending?}
    B -->|yes| C[Phase 2.0<br/>Cold Quiz Sweep]
    B -->|no| D[Phase 2 Agenda]
    C --> D
    D --> E[Phase 3<br/>Predict → Explain → Q&A → Check]
    E --> F[Phase 4 Warm Quiz<br/>caps at gap→partial]
    F --> G[Phase 5 Archive<br/>+ self-audit]
    G --> H{Path A: cold<br/>no-hint pass?}
    G --> I{Path B: review-slot pass<br/>+ prior cold attempt?}
    H -->|yes| J[partial → understood]
    I -->|yes| J
    G --> K{3-strike or<br/>2-fail streak?}
    K -->|yes| L[partial → gap]

Loading

Validation

Post-implementation eval against the pre-improvement skill across 4 protocol-compliance scenarios (cold-pending routing, Iron Rule #6 enforcement, path B escape valve, 3-strike streak detection):

Metric	Pre-improvement	This PR	Delta
Pass rate	25.0% (7/30)	100.0% (30/30)	+75pp
Avg time / scenario	105.9s ± 18.7s	92.2s ± 14.6s	−13.7s
Avg tokens / scenario	34,966	38,119	+3,152

The new version is faster despite carrying more rules — deterministic format rotation and explicit cap rules eliminate the reasoning ambiguity the old skill burned cycles on.

The eval set (plugins/personal-tutor/evals/evals.json) lands in a follow-up commit so reviewers can verify methodology against future regressions; per-run outputs and the benchmark viewer are local-only.

Why these ship together

The three feature commits (brainstorm, plan, impl) describe one cognitive intervention. Separating impl from its requirements-and-plan would force a reviewer to reconstruct the desirable-difficulty rationale from code alone — which is exactly the failure mode the rule changes are trying to fix in the learner. Keeping the why and the how in one PR means future edits to the skill can re-read the reason a rule exists before changing it.

---