release: v0.5.0 — load smoothing, progression gate, and rebalance

## What's New

### sensei mark — Load Smoothing
- Automatically spreads reviews across nearby days to prevent spikes
- Spread windows: s=fixed, h=2-4d, g=5-14d, e=15-45d, t=45-90d
- Low-review-count problems prefer earliest slot; high-count prefer latest
- --no-spread flag for exact base intervals

### sensei mark — Progression Gate
- New problems gated through 1→3→7→30→full SRS ladder
- Prevents first-solve from jumping to 30 days
- Capping note shown in output when gate fires

### times_reviewed Field
- All problem files now track times_reviewed (incremented on each mark)
- Legacy files default to 0 — no migration required
- New sensei new scaffolds revisit_in_days=1, times_reviewed=0

### sensei rebalance (new command)
- Dry-run and --apply modes for reactive cluster busting
- Displaces most-reviewed problems first within ±50% interval window
- --cap N sets the overloaded-day threshold (default: 3)

### Docs
- README: new sections for progression gate, load smoothing, rebalance
- AGENTS.md: CLI reference updated with all new commands and flags;
  rating integrity rule and socratic-question hint distinction added

Author: ashmanda-cs

README.md

@@ -39,9 +39,10 @@ Sensei tracks **when** you solved a problem and **how well** you understood it.
 | `sensei status` | JSON snapshot for you or your AI agent |
 | `sensei hint <problem>` | Get the problem URL + deets **without the answer** (for quizzing) |
 | `sensei show <problem>` | Full problem + your saved solution (for review) |
-| `sensei mark <problem> --rating g` | "Good" → next review in 7 days |
+| `sensei mark <problem> --rating g` | "Good" → next review in 7 days (with load smoothing) |
 | `sensei new <num> <slug> <cat>` | Scaffold a fresh problem in 0.3 seconds |
 | `sensei open <problem>` | Jump into the code + LeetCode page |
+| `sensei rebalance` | Spread review clusters across empty days |
 | `sensei revisit --export` | Dump everything to CSV or Markdown |
 
 ---
@@ -80,6 +81,36 @@ Rate yourself after each solve. Intervals are hardcoded — no adaptive math, no
 
 **The schedule is the curriculum.** Every rating directly sets the next review — no surprises.
 
+### 📈 New-Problem Progression Gate
+
+New problems are gated through a 1 → 3 → 7 → 30 day ladder before entering full SRS. No matter how well you solve a brand-new problem, it can't skip ahead:
+
+| Review # | Max interval |
+|----------|-------------|
+| 1st solve | 1 day |
+| 2nd solve | 3 days |
+| 3rd solve | 7 days |
+| 4th solve | 30 days |
+| 5th+ | Full SRS (no cap) |
+
+Rating `e` on your first solve → capped at 1 day. Rating `s` on your 4th solve → 1 day (under cap). The gate only fires when the rating would exceed the cap.
+
+### ⚖️ Load Smoothing
+
+`sensei mark` automatically spreads reviews across nearby days to avoid spikes. Instead of 6 problems all landing on the same day, the scheduler finds the least-loaded day within a window:
+
+| Rating | Base | Spread range |
+|--------|------|-------------|
+| `s` | 1d | fixed |
+| `h` | 3d | 2–4 days |
+| `g` | 7d | 5–14 days |
+| `e` | 30d | 15–45 days |
+| `t` | 90d | 45–90 days |
+
+Problems reviewed 5+ times are biased toward the **later** end of their window (stable memory, safe to defer). Newer problems stay at the **earlier** end (fragile memory, keep close).
+
+Disable with `--no-spread` to get exact base intervals.
+
 ---
 
 ## 🤖 AI-Agent Native
@@ -159,10 +190,23 @@ Same as `show` but **no `solution` field**. Perfect for agents that want to quiz
 ### `sensei mark <problem>` — rate your session
 
 ```bash
-sensei mark 217                    # Interactive prompt
-sensei mark 217 --rating e         # Non-interactive (agent-friendly)
+sensei mark 217                         # Interactive prompt
+sensei mark 217 --rating e              # Non-interactive (agent-friendly)
+sensei mark 217 --rating g --no-spread  # Exact base interval, no smoothing
+```
+
+Automatically increments `times_reviewed` and applies the progression gate and load smoothing.
+
+### `sensei rebalance` — flatten review spikes
+
+```bash
+sensei rebalance              # Dry run — preview moves, no writes
+sensei rebalance --apply      # Write changes to disk
+sensei rebalance --cap 2      # Flag days with more than 2 reviews
 ```
 
+Finds days exceeding the review cap and displaces the most-reviewed problems (most stable memory) to nearby low-load dates within ±50% of their current interval. Always preview before applying.
+
 ### `sensei new <num> <slug> <cat>` — scaffold
 
 ```bash
@@ -213,4 +257,4 @@ autoload -Uz compinit && compinit
 
 PolyForm Noncommercial License 1.0.0 — free for personal and non-commercial use.
 
-Full license in [`LICENSE`](LICENSE).
+Full license in [`LICENSE`](LICENSE).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jobbernaut-sensei"
-version = "0.4.10"
+version = "0.5.0"
 description = "A spaced-repetition CLI for LeetCode practice problems"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -78,3 +78,4 @@ exclude_lines = [
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
 ]
+