refactor: code quality sweep — circular deps, deduplication, agent config consistency

Architecture:
- Break circular deps: new output.py (console + energy_to_label), new services/backlog.py
- Shared DB connection factory: new db.py connect_db(), deduplicated 3 callers
- escape_fts_query: semantic_search.py now imports from query_utils

Agent config contradictions (5 fixes):
- Break thresholds: energy-adaptive references replace hardcoded High-only
- Session state init: removed dual-init race in Claude agent
- Voice toggle: added to Claude, Gemini, OpenCode agents
- AuDHD support: Gemini/OpenCode reference shared doc instead of stale inline copy
- Spaced repetition: max 3 per session standardised across all agents + shared protocol

Test infrastructure:
- addopts: -m 'not integration' (matches CI, integration tests opt-in)
- mcp[cli] in root dev deps (14 MCP tests now run)
- test_history.py: importorskip for cross-package import

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: NetDevAutomate

agents/claude/socratic-mentor.md

@@ -49,15 +49,9 @@ Exceptions: explicit "just show me", 4+ rounds stuck, pure syntax lookup, boiler
 
 ## Session State Management
 
-At the start of each session, create the session state file:
-```bash
-mkdir -p ~/.config/studyctl
-cat > ~/.config/studyctl/session-state.json << 'EOF'
-{"energy": "medium", "topic": "", "pomodoro": null}
-EOF
-```
+Session state is created by `studyctl session start`. Do NOT manually create the file.
 
-When the user specifies their energy level, update the state file:
+When the user specifies their energy level mid-session, update the state file:
 ```bash
 python3 -c "import json; from pathlib import Path; p=Path.home()/'.config/studyctl/session-state.json'; d=json.loads(p.read_text()); d['energy']='LEVEL'; p.write_text(json.dumps(d))"
 ```
@@ -71,8 +65,7 @@ This state is read by the Claude Code status line to show persistent session inf
 
 Follow `agents/shared/session-protocol.md`. Summary:
 
-1. Initialise the session state file (see above)
-2. Run system checks:
+1. Run system checks:
    ```bash
    studyctl resume          # Where you left off
    studyctl status          # Check sync state
@@ -89,7 +82,7 @@ Follow `agents/shared/session-protocol.md`. Summary:
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (interleave if 2+ due) → record scores
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record scores
 - **Body doubling (active):** agree goal + time → start/mid/end check-ins
 - **Body doubling (async):** periodic low-demand check-ins, no teaching
 - **Ad-hoc question:** identify topic → respond Socratically
@@ -170,6 +163,13 @@ Requires: pandoc, @mermaid-js/mermaid-cli for markdown→PDF with diagram suppor
 
 ---
 
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `/speak-start` and `/speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
+
+---
+
 ## Anti-Patterns to Avoid
 
 - **The Encyclopedia Response**: Too much information at once

agents/gemini/study-mentor.md

@@ -69,19 +69,13 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (max 3, interleave if 2+ due) → record
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 - **Body doubling:** agree goal + time → start/mid/end check-ins
 - **Ad-hoc question:** identify topic → respond Socratically
 
 ## AuDHD Support (Always Active)
 
-- **Bottom-up processing**: Concrete example first, then pattern, then principle
-- **Executive function**: Explicit starting points, time-boxes, numbered steps, summaries every 3-5 exchanges
-- **RSD/Imposter syndrome**: Reframe mistakes as exploration, bridge to infrastructure experience
-- **Overload prevention**: Max 3-4 concepts, tables over prose, TL;DR at top, mermaid diagrams
-- **Hyperfocus**: Time warnings, exit points, hydration/food reminders
-- **Emotional regulation**: Micro-celebrations for genuine progress, sensory checks at 45+ min
-- **Transition support**: Summarise when switching, parking lot for tangents
+See `agents/shared/audhd-framework.md` for the complete methodology. Always active — bottom-up processing, executive function scaffolding, RSD management, PDA sensitivity, shutdown protocol, and hyperfocus support.
 
 ## End-of-Session Protocol
 
@@ -90,14 +84,20 @@ Follow `wind-down-protocol.md`:
 2. End session: `studyctl session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
 3. Suggest next review based on spaced repetition intervals
 4. Offer calendar blocks: `studyctl schedule-blocks`
-5. If session was 25+ min, remind to take a break
+5. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
 6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 
-- 25 min: "Good time for a 5-minute break."
-- 50 min: "Take a proper break before continuing."
-- 90 min: "You should stop here and come back fresh."
+Follow the energy-adaptive schedule in `agents/shared/break-science.md`:
+- High energy: 25/50/90 min
+- Medium energy: 20/40/75 min
+- Low energy: 15/30/60 min
+
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `@speak-start` and `@speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
 
 ## Anti-Patterns to Avoid
 

agents/kiro/study-mentor/persona.md

@@ -38,7 +38,7 @@ Run `studyctl config show` to see your configured notebook IDs.
 ## Session Types
 
 **Study session:** arrival → state check → system check → topic → Socratic session → record
-**Spaced review:** arrival → state check → `studyctl review` → quiz overdue topics (interleave if 2+ due) → record
+**Spaced review:** arrival → state check → `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 **Body doubling (active):** agree goal + time → start/mid/end check-ins
 **Body doubling (async):** "I'm working, not studying. Check in on me." → periodic low-demand check-ins
 **Ad-hoc question:** identify topic → query NotebookLM → respond Socratically

agents/opencode/study-mentor.md

@@ -73,19 +73,13 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (max 3, interleave if 2+ due) → record
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 - **Body doubling:** agree goal + time → start/mid/end check-ins
 - **Ad-hoc question:** identify topic → respond Socratically
 
 ## AuDHD Support (Always Active)
 
-- **Bottom-up processing**: Concrete example first, then pattern, then principle
-- **Executive function**: Explicit starting points, time-boxes, numbered steps, summaries every 3-5 exchanges
-- **RSD/Imposter syndrome**: Reframe mistakes as exploration, bridge to infrastructure experience
-- **Overload prevention**: Max 3-4 concepts, tables over prose, TL;DR at top, mermaid diagrams
-- **Hyperfocus**: Time warnings, exit points, hydration/food reminders
-- **Emotional regulation**: Micro-celebrations for genuine progress, sensory checks at 45+ min
-- **Transition support**: Summarise when switching, parking lot for tangents
+See `agents/shared/audhd-framework.md` for the complete methodology. Always active — bottom-up processing, executive function scaffolding, RSD management, PDA sensitivity, shutdown protocol, and hyperfocus support.
 
 ## End-of-Session Protocol
 
@@ -94,14 +88,20 @@ Follow `wind-down-protocol.md`:
 2. End session: `studyctl session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
 3. Suggest next review based on spaced repetition intervals
 4. Offer calendar blocks: `studyctl schedule-blocks`
-5. If session was 25+ min, remind to take a break
+5. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
 6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 
-- 25 min: "Good time for a 5-minute break."
-- 50 min: "Take a proper break before continuing."
-- 90 min: "You should stop here and come back fresh."
+Follow the energy-adaptive schedule in `agents/shared/break-science.md`:
+- High energy: 25/50/90 min
+- Medium energy: 20/40/75 min
+- Low energy: 15/30/60 min
+
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `@speak-start` and `@speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
 
 ## Anti-Patterns to Avoid
 

agents/shared/session-protocol.md

@@ -78,7 +78,7 @@ If `studyctl streaks` shows a current streak, mention it: "Day [N] of your study
 
 Based on state check + what's due, propose a session plan:
 
-- If spaced repetition items are due → review session (interleave related topics)
+- If spaced repetition items are due → review session (max 3 topics per session, interleave related topics; if more due, prioritise longest-overdue)
 - If struggle topics detected → targeted practice with extra scaffolding
 - If nothing due + high energy → new material
 - If low energy or flat → body doubling or light review

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

@@ -70,26 +70,7 @@ class SearchContext:
     exclude_session_ids: list[str] = field(default_factory=list)
 
 
-def escape_fts_query(query: str) -> str:
-    """Escape a query string for FTS5 MATCH.
-
-    With porter stemming enabled, we can use simpler queries that match variants.
-    For example: "create" will match "created", "creating", "creates".
-    """
-    query = query.strip().strip('"').strip("'")
-
-    # If query contains FTS operators (AND, OR, NOT), use as-is
-    if any(op in query.upper() for op in [" AND ", " OR ", " NOT "]):
-        return query
-
-    # Escape quotes
-    escaped = query.replace('"', '""')
-
-    # Multi-word queries become phrases
-    if " " in escaped:
-        return f'"{escaped}"'
-
-    return escaped
+from agent_session_tools.query_utils import escape_fts_query  # noqa: E402, F401
 
 
 def hybrid_search(

packages/studyctl/pyproject.toml

@@ -49,7 +49,7 @@ packages = ["src/studyctl"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--tb=short"
+addopts = "--tb=short -m 'not integration'"
 markers = [
     "integration: requires external infrastructure (tmux, real DB, network)",
 ]

packages/studyctl/src/studyctl/cli/_session.py

@@ -34,13 +34,9 @@ def session_start(topic: str, energy: int) -> None:
 
     _ensure_session_dir()
 
-    # Map integer energy to label for history.py
-    if energy <= 3:
-        energy_label = "low"
-    elif energy <= 7:
-        energy_label = "medium"
-    else:
-        energy_label = "high"
+    from studyctl.output import energy_to_label
+
+    energy_label = energy_to_label(energy)
 
     study_id = start_study_session(topic, energy_label)
     if not study_id:

packages/studyctl/src/studyctl/cli/_shared.py

@@ -5,12 +5,9 @@
 import subprocess
 from pathlib import Path
 
-from rich.console import Console
-
+from studyctl.output import console
 from studyctl.topics import Topic, get_topics
 
-console = Console()
-
 # Topic keywords for session DB queries
 TOPIC_KEYWORDS = {
     "python": [

packages/studyctl/src/studyctl/cli/_study.py

@@ -7,12 +7,15 @@
 
 from __future__ import annotations
 
+import logging
 from datetime import UTC, datetime
 
 import click
 
 from studyctl.cli._shared import console
 
+logger = logging.getLogger(__name__)
+
 
 def _agent_names() -> list[str]:
     """Registered agent names for CLI --agent choices."""
@@ -202,40 +205,20 @@ def _auto_persist_struggled(
 ) -> None:
     """Persist struggled topics from session-topics.md to the backlog.
 
-    Uses FCIS pattern -- plan_auto_persist decides what to persist,
-    then we execute by calling park_topic for each action.
+    Thin CLI wrapper over services.backlog.auto_persist_struggled —
+    adds console output.
     """
-    import contextlib
-
-    with contextlib.suppress(Exception):
-        from studyctl.logic.backlog_logic import plan_auto_persist
-        from studyctl.parking import get_parked_topics, park_topic
-
-        # Gather existing questions for this session to deduplicate
-        existing = get_parked_topics(study_session_id=study_session_id)
-        existing_questions = {t["question"] for t in existing}
-
-        # Decide
-        actions = plan_auto_persist(topic_entries, existing_questions, study_session_id)
-
-        # Execute
-        persisted = 0
-        for action in actions:
-            result = park_topic(
-                question=action.question,
-                topic_tag=action.topic_tag,
-                context=action.context,
-                study_session_id=action.study_session_id,
-                source=action.source,
-            )
-            if result:
-                persisted += 1
+    try:
+        from studyctl.services.backlog import auto_persist_struggled
 
+        persisted = auto_persist_struggled(study_session_id, topic_entries)
         if persisted:
             console.print(
                 f"[dim]Saved {persisted} struggled "
                 f"topic{'s' if persisted != 1 else ''} to backlog[/dim]"
             )
+    except Exception:
+        logger.exception("Failed to auto-persist struggled topics to backlog")
 
 
 def _handle_start(
@@ -313,12 +296,9 @@ def _handle_start(
 
     # --- Create DB session ---
 
-    if energy <= 3:
-        energy_label = "low"
-    elif energy <= 7:
-        energy_label = "medium"
-    else:
-        energy_label = "high"
+    from studyctl.output import energy_to_label
+
+    energy_label = energy_to_label(energy)
 
     study_id = start_study_session(topic, energy_label)
     if not study_id: