feat: add bridge CLI command + 4 E2E experience verification tests

Re-register bridge add/list commands that were dropped during the
compact-to-core CLI pass. Add 4 new E2E tests that verify user
experience not just plumbing: sidebar pane renders topics, cleanup
notes flow into resume persona, strict directory reuse on resume,
and sidebar shows elapsed time. 31 integration tests now pass.

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

Author: NetDevAutomate

packages/studyctl/src/studyctl/cli/__init__.py

@@ -24,13 +24,14 @@
         "setup": "studyctl.cli._setup:setup",
         # _config.py — configuration
         "config": "studyctl.cli._config:config_group",
-        # _review.py — spaced repetition, progress, wins, streaks
+        # _review.py — spaced repetition, progress, wins, streaks, bridges
         "review": "studyctl.cli._review:review",
         "struggles": "studyctl.cli._review:struggles",
         "wins": "studyctl.cli._review:wins",
         "progress": "studyctl.cli._review:progress",
         "resume": "studyctl.cli._review:resume",
         "streaks": "studyctl.cli._review:streaks",
+        "bridge": "studyctl.cli._review:bridge_group",
         # _content.py — content pipeline (pdf splitting, NotebookLM, syllabus)
         "content": "studyctl.cli._content:content_group",
         # _web.py — web UI

packages/studyctl/src/studyctl/cli/_review.py

@@ -1,4 +1,4 @@
-"""Review commands — spaced repetition, progress, and struggle detection."""
+"""Review commands — spaced repetition, progress, struggle detection, and knowledge bridges."""
 
 from __future__ import annotations
 
@@ -9,6 +9,8 @@
 
 from studyctl.cli._shared import TOPIC_KEYWORDS, console
 from studyctl.history import (
+    get_bridges,
+    record_bridge,
     spaced_repetition_due,
     struggle_topics,
 )
@@ -219,3 +221,82 @@ def streaks() -> None:
         console.print(
             "\n  [dim]No session today or yesterday. Start one to keep your streak going![/dim]"
         )
+
+
+# --- Knowledge bridges ---
+
+
+@click.group(name="bridge")
+def bridge_group() -> None:
+    """Manage knowledge bridges between domains."""
+
+
+@bridge_group.command(name="add")
+@click.argument("source")
+@click.option("--source-domain", "-s", required=True, help="Source domain (e.g. networking).")
+@click.argument("target")
+@click.option("--target-domain", "-t", required=True, help="Target domain (e.g. python).")
+@click.option("--mapping", "-m", required=True, help="How concepts relate.")
+@click.option(
+    "--quality",
+    "-q",
+    type=click.Choice(["strong", "moderate", "weak"]),
+    default="moderate",
+    help="Bridge quality.",
+)
+def bridge_add(
+    source: str,
+    source_domain: str,
+    target: str,
+    target_domain: str,
+    mapping: str,
+    quality: str,
+) -> None:
+    """Add a knowledge bridge between two concepts.
+
+    Example::
+
+        studyctl bridge add "ECMP" -s networking \\
+            "Spark partitions" -t python -m "Both distribute"
+    """
+    if record_bridge(source, source_domain, target, target_domain, mapping, quality, "student"):
+        console.print(
+            f"[green]Bridge added:[/green] "
+            f"{source} ({source_domain}) \u2192 {target} ({target_domain})"
+        )
+    else:
+        console.print("[red]Failed to add bridge. Check your session database.[/red]")
+
+
+@bridge_group.command(name="list")
+@click.option("--source-domain", "-s", default=None, help="Filter by source domain.")
+@click.option("--target-domain", "-t", default=None, help="Filter by target domain.")
+@click.option("--quality", "-q", default=None, help="Filter by quality.")
+def bridge_list(source_domain: str | None, target_domain: str | None, quality: str | None) -> None:
+    """List knowledge bridges."""
+    bridges = get_bridges(target_domain=target_domain, source_domain=source_domain, quality=quality)
+    if not bridges:
+        console.print("[dim]No bridges found. Use 'studyctl bridge add' to create some.[/dim]")
+        return
+
+    table = Table(title="Knowledge Bridges")
+    table.add_column("Source", style="cyan")
+    table.add_column("Domain")
+    table.add_column("\u2192")
+    table.add_column("Target", style="green")
+    table.add_column("Domain")
+    table.add_column("Mapping")
+    table.add_column("Quality")
+
+    for b in bridges:
+        table.add_row(
+            b["source_concept"],
+            b["source_domain"],
+            "\u2192",
+            b["target_concept"],
+            b["target_domain"],
+            b["mapping"],
+            b["quality"],
+        )
+
+    console.print(table)

packages/studyctl/tests/test_study_integration.py

@@ -678,3 +678,116 @@ def test_wrapper_script_exists_and_executable(self, tmp_path):
         content = wrapper.read_text()
         assert "python" in content.lower()
         assert "-m studyctl.cli" in content
+
+
+# ---------------------------------------------------------------------------
+# Test: E2E Experience Verification
+# ---------------------------------------------------------------------------
+
+
+class TestExperienceVerification:
+    """Verify user-facing experience, not just plumbing.
+
+    These tests go beyond checking IPC files to verify what the user
+    actually sees in the terminal and what data flows across sessions.
+    """
+
+    def test_sidebar_pane_renders_topics(self, tmp_path):
+        """Topics logged by the agent appear in the sidebar PANE, not just IPC files."""
+        agent = _make_mock_agent(tmp_path)
+        info = _start_session(agent)
+
+        _wait_for(
+            lambda: TOPICS_FILE.exists() and "First-class" in TOPICS_FILE.read_text(),
+            desc="topics logged to IPC",
+        )
+        time.sleep(7)
+
+        content = _capture_pane(info["sidebar_pane"])
+        assert any(marker in content for marker in ["Closures", "First-class", "W:", "L:"]), (
+            f"Sidebar pane should render topic data but got:\n{content}"
+        )
+
+    def test_cleanup_notes_flow_into_resume_persona(self, tmp_path):
+        """Full chain: topics -> cleanup -> DB notes -> resume persona."""
+        agent = _make_mock_agent(tmp_path)
+        info = _start_session(agent)
+        original_name = info["session_name"]
+
+        _wait_for(
+            lambda: TOPICS_FILE.exists() and "First-class" in TOPICS_FILE.read_text(),
+            desc="topics logged before end",
+        )
+        _studyctl("study", "--end")
+        _wait_for(
+            lambda: not _session_exists(original_name),
+            timeout=10,
+            desc="original session killed",
+        )
+
+        agent2 = _make_mock_agent(tmp_path, name="mock-agent-chain.sh")
+        _studyctl(
+            "study",
+            "--resume",
+            env_overrides={"STUDYCTL_TEST_AGENT_CMD": f"bash {agent2} {{persona_file}}"},
+        )
+        _wait_for(STATE_FILE.exists, desc="resumed state file")
+        state = _read_state()
+
+        persona_path = state.get("persona_file")
+        assert persona_path, "Resumed session should have a persona file"
+        persona = Path(persona_path)
+        assert persona.exists(), f"Persona file not found at {persona_path}"
+
+        persona_content = persona.read_text()
+        has_topic_ref = "Closures" in persona_content or "First-class" in persona_content
+        has_resume_section = "Resuming" in persona_content or "Previous" in persona_content
+        assert has_topic_ref or has_resume_section, (
+            f"Resume persona should reference session 1 topics.\n"
+            f"Persona content (first 800 chars):\n{persona_content[:800]}"
+        )
+
+    def test_resume_flag_strictly_present(self, tmp_path):
+        """Resume must reuse session directory -- no OR fallback allowed."""
+        agent = _make_fast_agent(tmp_path)
+        info = _start_session(agent)
+        original_dir = info["session_dir"]
+        original_name = info["session_name"]
+
+        _wait_for(
+            lambda: not _session_exists(original_name) or _read_state().get("mode") == "ended",
+            timeout=20,
+            desc="session ended",
+        )
+
+        agent2 = _make_mock_agent(tmp_path, name="mock-resume-strict.sh")
+        _studyctl(
+            "study",
+            "--resume",
+            env_overrides={"STUDYCTL_TEST_AGENT_CMD": f"bash {agent2} {{persona_file}}"},
+        )
+        _wait_for(STATE_FILE.exists, desc="resumed state file")
+        state = _read_state()
+
+        assert state.get("session_dir") == original_dir, (
+            f"Resume should reuse {original_dir}, got {state.get('session_dir')}"
+        )
+
+    def test_sidebar_shows_elapsed_time(self, tmp_path):
+        """Sidebar should display a non-zero elapsed time after a few seconds."""
+        import re
+
+        agent = _make_mock_agent(tmp_path)
+        info = _start_session(agent)
+
+        _wait_for(
+            lambda: len(_capture_pane(info["sidebar_pane"]).strip()) > 0,
+            timeout=10,
+            desc="sidebar to render",
+        )
+        time.sleep(5)
+
+        content = _capture_pane(info["sidebar_pane"])
+        has_time = bool(re.search(r"\d+:\d{2}", content))
+        has_elapsed = "elapsed" in content.lower() or "timer" in content.lower()
+        assert has_time or has_elapsed, f"Sidebar should show elapsed time but got:\n{content}"