feat: enhance CLAUDE.md with detailed plugin routing instructions and update MainWindow tests for better resource management

Author: chrisdpurcell

CLAUDE.md

@@ -2,6 +2,21 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Plugin Routing — Qt Plugins (MANDATORY)
+
+This is a PySide6/Qt project. Always invoke the appropriate plugin skill before writing code:
+
+| Task | Invoke |
+|------|--------|
+| Write or add tests (pytest-qt, QTest) | `qt:qtest-patterns` skill |
+| Run the test suite or check pass/fail | `qt:run` skill |
+| Measure test coverage, find gaps | `qt:coverage` skill → `qt:qt-coverage-workflow` skill |
+| Generate tests for uncovered lines | `qt:generate` skill (delegates to `qt:test-generator` agent) |
+| Visual/GUI interaction testing | `qt:visual` skill (delegates to `qt:gui-tester` agent) |
+| Any new feature or UI work | `qt:qtest-patterns` after implementation, `qt:visual` to verify |
+
+**Rule**: Never write Qt/PySide6 tests without first consulting `qt:qtest-patterns`. Never run tests manually via raw `pytest` when `qt:run` is available — use the skill so the agent can capture results and act on failures.
+
 ## Project Overview
 
 TextTools is a PySide6 desktop application for text processing on Linux. Its planned features are encoding conversion (to UTF-8), text formatting/cleaning, find/replace, and file management. **The MVVM framework and UI shell are in place, but all TextTools feature logic is unimplemented — the current source files are scaffolding/template code.** `DESIGN.md` is the authoritative spec for what needs to be built (UI mockups, widget objectNames, feature acceptance criteria, data flow diagrams).

src/views/main_window.py

@@ -20,6 +20,7 @@
 from PySide6.QtGui import QAction, QColor, QFont, QKeySequence, QPalette, QShortcut
 from PySide6.QtUiTools import QUiLoader
 from PySide6.QtWidgets import (
+    QAbstractItemView,
     QApplication,
     QCheckBox,
     QFileDialog,
@@ -247,8 +248,6 @@ def _setup_file_tree(self) -> None:
 
     def _setup_merge_tab(self) -> None:
         """Configure the merge list widget (drag-drop mode set programmatically)."""
-        from PySide6.QtWidgets import QAbstractItemView
-
         self._merge_file_list.setDragDropMode(
             QAbstractItemView.DragDropMode.InternalMove
         )
@@ -264,9 +263,12 @@ def _connect_signals(self) -> None:
 
         # Cleaning: each checkbox triggers a fresh apply when a doc is loaded.
         # The checkboxes act as "apply now" toggles, not deferred configuration.
-        self._trim_cb.stateChanged.connect(self._on_clean_requested)
-        self._clean_cb.stateChanged.connect(self._on_clean_requested)
-        self._remove_tabs_cb.stateChanged.connect(self._on_clean_requested)
+        # checkStateChanged replaces the deprecated stateChanged (Qt 6.7+); both
+        # work but stateChanged passes int while checkStateChanged passes Qt.CheckState.
+        # _on_clean_requested ignores the argument so either signature is compatible.
+        self._trim_cb.checkStateChanged.connect(self._on_clean_requested)
+        self._clean_cb.checkStateChanged.connect(self._on_clean_requested)
+        self._remove_tabs_cb.checkStateChanged.connect(self._on_clean_requested)
 
         # Find / Replace
         self._find_button.clicked.connect(self._on_find_clicked)

tests/integration/test_main_window.py

@@ -30,8 +30,20 @@ def mock_text_svc():
 
 @pytest.fixture
 def window(mock_file_svc, mock_text_svc, qapp):
+    """Construct a MainWindow and clean up the aboutToQuit connection on teardown.
+
+    MainWindow.__init__ connects app.aboutToQuit → window._save_settings. Without
+    teardown, every test that uses this fixture adds another live connection to the
+    session-scoped QApplication, preventing GC of the window objects for the whole
+    test session and triggering save_settings for every window at program exit.
+    """
     vm = MainViewModel(mock_file_svc, mock_text_svc)
-    return MainWindow(vm)
+    win = MainWindow(vm)
+    yield win
+    try:
+        qapp.aboutToQuit.disconnect(win._save_settings)
+    except RuntimeError:
+        pass  # already disconnected or never connected
 
 
 class TestWindowTitle:
@@ -607,8 +619,18 @@ def test_merge_tab_list_refreshes_on_add(self, window, mock_file_svc, tmp_path,
         assert list_widget.count() == 1
         assert list_widget.item(0).text() == "hello.txt"
 
-    def test_merge_empty_list_shows_error(self, window, qtbot):
-        """Clicking Merge with no files emits error_occurred."""
+    def test_merge_empty_list_shows_error(self, window, monkeypatch, qtbot):
+        """Clicking Merge with no files emits error_occurred and shows an error dialog.
+
+        Must monkeypatch QMessageBox.critical: the signal is connected to _on_error
+        which calls QMessageBox.critical() (a blocking modal). The modal creates a
+        nested event loop that blocks waitSignal's slot from ever firing in offscreen
+        mode — the dialog is never dismissed so the test hangs without this patch.
+        """
+        monkeypatch.setattr(
+            "src.views.main_window.QMessageBox.critical",
+            lambda *a, **kw: None,
+        )
         with qtbot.waitSignal(window._viewmodel.error_occurred, timeout=1000) as blocker:
             window._viewmodel.execute_merge()
         assert "No files in merge list" in blocker.args[0]