Merge branch 'feat/study-backlog-phase2'

Author: taylaand

docs/architecture/study-backlog-phase2.md

@@ -0,0 +1,63 @@
+# Brainstorm: Study Backlog Phase 2 — AI Prioritization + MCP Integration — 2026-04-03
+
+## What We're Building
+
+Three interconnected pieces:
+
+1. **`studyctl topics suggest`** — CLI command that ranks pending backlog topics using frequency + agent-assessed importance
+2. **4 new MCP tools** — `get_study_backlog`, `get_topic_suggestions`, `get_study_history`, `record_topic_progress` — giving the agent direct session-db access
+3. **Session-db integration tests** — comprehensive tests for all session types, ensuring the full data pipeline works
+4. **Architecture documentation** — updated diagrams showing session-db as a first-class component
+
+## Scoring Model
+
+Two signals, combined:
+
+| Signal | Source | Weight | Rationale |
+|--------|--------|--------|-----------|
+| **Frequency** | COUNT of parked_topics entries per question | Data-driven | Topics that keep coming up are clearly important |
+| **Importance** | Agent-assessed priority (1-5) on parked_topics | LLM-driven | Fundamental topics (OOP basics, closures) rank higher than niche ones |
+
+**Importance scoring**: The agent sets a `priority` (1-5) when parking or struggling on a topic. The MCP `record_topic_progress` tool can also update priority. Topics without a priority score default to 3 (neutral).
+
+**Combined score**: `score = frequency_weight * normalized_frequency + importance_weight * (priority / 5.0)`
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Scoring model | Frequency + agent importance | Fundamentality matters more than recency for learning paths |
+| MCP tools | All 4 (read + write) | Full agent integration, extensibility investment |
+| Priority storage | `priority` INTEGER column on parked_topics | Migration v17, agent sets via MCP |
+| Suggest output | Ranked list with scores + reasoning hints | Agent can re-rank with its own context |
+| Session-db tests | Integration tests with real DB for all session types | Validates full data pipeline end-to-end |
+| Architecture docs | Updated PlantUML with session-db as central component | Source of truth for the whole system |
+
+## MCP Tools Spec
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `get_study_backlog` | Read | Query pending backlog items with filters (tech, source, status) |
+| `get_topic_suggestions` | Read | Return algorithmically ranked topic suggestions |
+| `get_study_history` | Read | Query study_sessions + study_progress for a topic |
+| `record_topic_progress` | Write | Update study_progress confidence, record teach-back, set topic priority |
+
+## Migration v17
+
+```sql
+ALTER TABLE parked_topics ADD COLUMN priority INTEGER;
+-- NULL = not yet assessed, 1 = low, 5 = critical/foundational
+```
+
+## Scope
+
+### In scope
+- `studyctl topics suggest` CLI command (FCIS: scoring logic in backlog_logic.py)
+- 4 MCP tools registered in studyctl-mcp server
+- Migration v17 (priority column)
+- Updated architecture doc with session-db integration diagrams
+- Integration tests: migration, MCP tools, scoring, all session types
+
+### Out of scope
+- Auto-categorization of tech_area by LLM (manual or agent-set for now)
+- Spaced repetition integration with suggestions (future)

docs/brainstorms/2026-04-03-study-backlog-phase2-brainstorm.md

@@ -13,7 +13,7 @@
 logger = logging.getLogger(__name__)
 
 # Current schema version - increment when adding new migrations
-CURRENT_VERSION = 16
+CURRENT_VERSION = 17
 
 # Migration functions: version -> (description, migration_func)
 MIGRATIONS: dict[int, tuple[str, Callable[[sqlite3.Connection], None]]] = {}
@@ -614,6 +614,21 @@ def migrate_v16(conn: sqlite3.Connection) -> None:
     """)
 
 
+@migration(17, "Add priority column to parked_topics for agent-assessed importance")
+def migrate_v17(conn: sqlite3.Connection) -> None:
+    """Add agent-assessed importance score to backlog items.
+
+    Priority is set by the AI agent during study sessions to indicate
+    how foundational a topic is in the learning path:
+    - NULL = not yet assessed (defaults to 3 in scoring)
+    - 1 = low importance (niche/optional)
+    - 5 = critical/foundational (e.g. OOP basics, closures)
+    """
+    conn.execute("""
+        ALTER TABLE parked_topics ADD COLUMN priority INTEGER
+    """)
+
+
 def check_migration_status(db_path: Path) -> dict:
     """Check migration status without modifying database.
 

packages/agent-session-tools/src/agent_session_tools/migrations.py

@@ -52,6 +52,89 @@ class PersistAction:
     source: str = "struggled"
 
 
+@dataclass
+class ScoringInput:
+    """Pre-gathered data for a single backlog item."""
+
+    item: BacklogItem
+    frequency: int  # count of times this topic appears in parked_topics
+    priority: int | None  # agent-assessed importance (1-5), None = unassessed
+
+
+@dataclass
+class TopicSuggestion:
+    """A scored and ranked topic suggestion."""
+
+    item: BacklogItem
+    score: float  # 0.0 - 1.0, higher = study this next
+    frequency: int
+    priority: int  # effective priority (default 3 if unassessed)
+    reasoning: str  # human-readable explanation
+
+
+# Scoring weights: importance matters more than frequency
+_FREQUENCY_WEIGHT = 0.4
+_IMPORTANCE_WEIGHT = 0.6
+_DEFAULT_PRIORITY = 3
+
+
+def score_backlog_items(inputs: list[ScoringInput]) -> list[TopicSuggestion]:
+    """Score and rank backlog items by frequency + agent-assessed importance.
+
+    Pure logic — no I/O. Takes pre-gathered scoring inputs, returns
+    sorted suggestions (highest score first).
+
+    Score formula:
+        effective_priority = priority or 3
+        score = 0.4 * normalized_frequency + 0.6 * normalized_priority
+    """
+    if not inputs:
+        return []
+
+    max_frequency = max(inp.frequency for inp in inputs)
+    if max_frequency == 0:
+        max_frequency = 1  # avoid division by zero
+
+    suggestions: list[TopicSuggestion] = []
+    for inp in inputs:
+        effective_priority = inp.priority if inp.priority is not None else _DEFAULT_PRIORITY
+        norm_freq = inp.frequency / max_frequency
+        norm_priority = effective_priority / 5.0
+
+        score = (_FREQUENCY_WEIGHT * norm_freq) + (_IMPORTANCE_WEIGHT * norm_priority)
+
+        # Build reasoning
+        parts: list[str] = []
+        if effective_priority >= 4:
+            parts.append(f"high importance ({effective_priority}/5)")
+        elif effective_priority <= 2:
+            parts.append(f"low importance ({effective_priority}/5)")
+        else:
+            parts.append(f"moderate importance ({effective_priority}/5)")
+
+        if inp.frequency >= 3:
+            parts.append(f"frequently appears ({inp.frequency}x)")
+        elif inp.frequency == 1:
+            parts.append("appeared once")
+        else:
+            parts.append(f"appeared {inp.frequency}x")
+
+        reasoning = ", ".join(parts)
+
+        suggestions.append(
+            TopicSuggestion(
+                item=inp.item,
+                score=round(score, 3),
+                frequency=inp.frequency,
+                priority=effective_priority,
+                reasoning=reasoning,
+            )
+        )
+
+    suggestions.sort(key=lambda s: s.score, reverse=True)
+    return suggestions
+
+
 def format_backlog_list(
     items: list[BacklogItem],
     *,

packages/studyctl/src/studyctl/backlog_logic.py

@@ -141,6 +141,84 @@ def topics_resolve(topic_id: int) -> None:
         console.print(f"[yellow]Topic #{topic_id} not found or already resolved.[/yellow]")
 
 
+@topics_group.command("suggest")
+@click.option("--limit", "-l", default=10, show_default=True, help="Max suggestions to show.")
+@click.option("--topic", "-t", default=None, help="Current study topic for relevance sorting.")
+def topics_suggest(limit: int, topic: str | None) -> None:
+    """Suggest what to study next, ranked by importance and frequency.
+
+    Uses algorithmic scoring: agent-assessed importance (60%) combined
+    with how frequently a topic has been parked/struggled (40%).
+
+    Examples:
+
+        studyctl backlog suggest
+
+        studyctl backlog suggest --limit 5
+
+        studyctl backlog suggest --topic "Python Patterns"
+    """
+    from rich.table import Table
+
+    from studyctl.backlog_logic import BacklogItem, ScoringInput, score_backlog_items
+    from studyctl.cli._shared import console
+    from studyctl.parking import get_parked_topics, get_topic_frequencies
+
+    # GATHER
+    raw_topics = get_parked_topics(status="pending")
+    if not raw_topics:
+        console.print("[dim]No pending topics to suggest.[/dim]")
+        return
+
+    frequencies = get_topic_frequencies(status="pending")
+
+    scoring_inputs = [
+        ScoringInput(
+            item=BacklogItem(
+                id=t["id"],
+                question=t["question"],
+                topic_tag=t.get("topic_tag"),
+                tech_area=t.get("tech_area"),
+                source=t.get("source", "parked"),
+                context=t.get("context"),
+                parked_at=t["parked_at"],
+                session_topic=None,
+            ),
+            frequency=frequencies.get(t["question"], 1),
+            priority=t.get("priority"),
+        )
+        for t in raw_topics
+    ]
+
+    # DECIDE
+    suggestions = score_backlog_items(scoring_inputs)[:limit]
+
+    # PRESENT
+    table = Table(title=f"Study Suggestions — Top {len(suggestions)}")
+    table.add_column("#", justify="right", style="dim", width=3)
+    table.add_column("Topic", style="cyan")
+    table.add_column("Tech", style="green")
+    table.add_column("Score", justify="right", style="bold yellow")
+    table.add_column("Why", style="dim")
+
+    for rank, s in enumerate(suggestions, 1):
+        tech_col = s.item.tech_area or ""
+        score_col = f"{s.score:.2f}"
+        table.add_row(str(rank), s.item.question, tech_col, score_col, s.reasoning)
+
+    console.print(table)
+
+    if topic:
+        # Highlight items relevant to the current topic
+        relevant = [
+            s for s in suggestions if s.item.tech_area and s.item.tech_area.lower() in topic.lower()
+        ]
+        if relevant:
+            console.print(
+                f"\n[dim]{len(relevant)} of these relate to your current topic ({topic})[/dim]"
+            )
+
+
 def _relative_time(iso_datetime: str) -> str:
     """Convert ISO datetime string to a relative time like '2d', '5h'."""
     from datetime import UTC, datetime