chore: add Codex project context and agent guidance

.agents/skills/kst4contest-change/references/threading-and-state.md

@@ -0,0 +1,73 @@
+# Threading and state management
+
+## Canonical state vs UI state
+
+Use a thread-safe canonical state for data consumed by worker/network threads.
+
+The active-member UI list is only a projection.
+
+Preferred conceptual model:
+
+```text
+ConcurrentMap<MemberKey, ChatMember> activeMembers
+        |
+        | FX-thread projection/update
+        v
+ObservableList<ChatMember> activeMembersUi
+```
+
+`MemberKey` semantics must preserve full callsign plus category unless the specific operation is intentionally base-call-wide.
+
+## MessageBusManagementThread
+
+Do not:
+
+- iterate JavaFX `ObservableList` from the worker thread;
+- add/remove JavaFX-list entries directly from the worker thread;
+- use the FX thread as a substitute for proper domain state ownership.
+
+Do:
+
+- pass domain events/data to the controller/service boundary;
+- modify canonical thread-safe state outside UI code as appropriate;
+- project changes to JavaFX state on the FX thread.
+
+## Controller boundary
+
+`ChatController` is the preferred coordination boundary for UI-visible state.
+
+Keep view-specific operations out of protocol receiver code.
+
+## External receiver design
+
+For receiver refactors, separate:
+
+- socket/UDP/TCP I/O;
+- parsing;
+- DTO;
+- domain/persistence;
+- UI coordination.
+
+## Error containment
+
+Long-running threads must survive:
+
+- malformed server records;
+- incomplete members;
+- unknown bands/categories;
+- missing locators;
+- null QRB/QTF;
+- temporary socket failure.
+
+Catch errors at meaningful boundaries and include enough context in English diagnostic logs/comments to trace the input and stage of failure.
+
+Do not swallow errors silently.
+
+## JavaFX selection/sorting
+
+When updating backing data:
+
+- preserve current selection where the feature expects it;
+- avoid invalidating `FilteredList`/`SortedList` assumptions;
+- do not create recursive UI updates;
+- avoid accessing control state from worker threads.