From 4601199587e22f6000a411b266bcde3b2f39e689 Mon Sep 17 00:00:00 2001 From: Marc Froehlich Date: Tue, 25 Aug 2026 01:00:26 +0200 Subject: [PATCH] chore: add Codex project context and agent guidance --- .agents/skills/kst4contest-change/SKILL.md | 90 +++++++++ .../kst4contest-change/agents/openai.yaml | 7 + .../references/architecture.md | 102 ++++++++++ .../references/automation-and-messaging.md | 42 ++++ .../references/domain-and-callsigns.md | 87 +++++++++ .../references/known-edge-cases.md | 115 +++++++++++ .../references/project-behavior-catalog.md | 183 ++++++++++++++++++ .../references/protocols-and-integrations.md | 101 ++++++++++ .../kst4contest-change/references/roadmap.md | 22 +++ .../references/settings-and-data.md | 80 ++++++++ .../references/testing-build-release.md | 100 ++++++++++ .../references/threading-and-state.md | 73 +++++++ .../references/ui-behavior.md | 65 +++++++ .../skills/kst4contest-documentation/SKILL.md | 74 +++++++ .../agents/openai.yaml | 7 + .../references/current-feature-context.md | 26 +++ .../references/manual-and-website.md | 47 +++++ .../references/release-communications.md | 35 ++++ .agents/skills/kst4contest-review/SKILL.md | 52 +++++ .../kst4contest-review/agents/openai.yaml | 7 + .../references/review-checklist.md | 61 ++++++ .codex/config.toml | 4 + AGENTS.md | 180 +++++++++++++++++ docs/PROJECT_CONTEXT.md | 159 +++++++++++++++ 24 files changed, 1719 insertions(+) create mode 100644 .agents/skills/kst4contest-change/SKILL.md create mode 100644 .agents/skills/kst4contest-change/agents/openai.yaml create mode 100644 .agents/skills/kst4contest-change/references/architecture.md create mode 100644 .agents/skills/kst4contest-change/references/automation-and-messaging.md create mode 100644 .agents/skills/kst4contest-change/references/domain-and-callsigns.md create mode 100644 .agents/skills/kst4contest-change/references/known-edge-cases.md create mode 100644 .agents/skills/kst4contest-change/references/project-behavior-catalog.md create mode 100644 .agents/skills/kst4contest-change/references/protocols-and-integrations.md create mode 100644 .agents/skills/kst4contest-change/references/roadmap.md create mode 100644 .agents/skills/kst4contest-change/references/settings-and-data.md create mode 100644 .agents/skills/kst4contest-change/references/testing-build-release.md create mode 100644 .agents/skills/kst4contest-change/references/threading-and-state.md create mode 100644 .agents/skills/kst4contest-change/references/ui-behavior.md create mode 100644 .agents/skills/kst4contest-documentation/SKILL.md create mode 100644 .agents/skills/kst4contest-documentation/agents/openai.yaml create mode 100644 .agents/skills/kst4contest-documentation/references/current-feature-context.md create mode 100644 .agents/skills/kst4contest-documentation/references/manual-and-website.md create mode 100644 .agents/skills/kst4contest-documentation/references/release-communications.md create mode 100644 .agents/skills/kst4contest-review/SKILL.md create mode 100644 .agents/skills/kst4contest-review/agents/openai.yaml create mode 100644 .agents/skills/kst4contest-review/references/review-checklist.md create mode 100644 .codex/config.toml create mode 100644 AGENTS.md create mode 100644 docs/PROJECT_CONTEXT.md diff --git a/.agents/skills/kst4contest-change/SKILL.md b/.agents/skills/kst4contest-change/SKILL.md new file mode 100644 index 0000000..581a61e --- /dev/null +++ b/.agents/skills/kst4contest-change/SKILL.md @@ -0,0 +1,90 @@ +--- +name: kst4contest-change +description: Analyze or implement KST4Contest Java/JavaFX changes, bug fixes, refactorings, protocol handling, contest workflow behaviour, callsign/band logic, AirScout/logging/rotor/DXCluster integrations, threading and state management. Use current code as source of truth and follow the mandatory concept-and-question gate before edits. +--- + +# KST4Contest change workflow + +Read the relevant reference files before proposing a concept. + +## Phase 1: read-only analysis + +- Inspect the current code and tests. +- Identify the current data flow and thread ownership. +- Identify user-visible and protocol-visible behaviour. +- Check relevant `docs/PROJECT_CONTEXT.md` sections when they exist. +- Check whether the task overlaps a known invariant in the references. +- Do not modify files. + +## Phase 2: report understanding in German + +Explain: + +- what Marc wants changed; +- what must remain unchanged; +- which components appear affected; +- what evidence in the current code supports that understanding; +- any conflict between current code and historical project context. + +Never resolve a conflict by guessing. + +## Phase 3: questions and final concept in German + +Before finalizing the concept: + +- identify all material implementation choices; +- ask Marc questions that are not already answered by code, project instructions or prior confirmed decisions; +- wait for answers when needed. + +Then present: + +- intended data/control flow; +- exact behavioural changes; +- compatibility impact; +- thread/UI impact; +- persistence impact; +- test strategy; +- likely documentation impact; +- likely durable project-context impact; +- related-project impact when relevant. + +Ask for explicit concept approval and wait before editing. + +## Phase 4: implementation + +After approval: + +- implement the smallest coherent change; +- preserve unrelated behaviour; +- keep comments/Javadoc in English; +- add/update focused tests; +- keep external protocol parsing defensive; +- avoid hidden defaulting for unknown values. + +## Phase 5: verification and documentation impact + +Run focused checks, then appropriate broader checks. + +Because KST4Contest build configuration may ignore failures/findings, inspect summaries and reports rather than only command exit status. + +Then use `$software-project-context`: + +- do a low-cost documentation-impact classification; +- inspect only likely affected manual/README/website sections; +- update targeted documentation when clearly required by the approved implementation; +- update `docs/PROJECT_CONTEXT.md` for significant durable technical decisions/state changes; +- do not perform a full manual audit unless there is a specific trigger. + +## Phase 6: report + +Report in German: + +- files changed; +- implementation summary; +- tests/checks; +- warnings/findings; +- documentation-impact result; +- documentation/context updates or why none were required; +- related-project impact when relevant; +- unresolved issues; +- no Git publication action unless explicitly requested. diff --git a/.agents/skills/kst4contest-change/agents/openai.yaml b/.agents/skills/kst4contest-change/agents/openai.yaml new file mode 100644 index 0000000..bd1661f --- /dev/null +++ b/.agents/skills/kst4contest-change/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "KST4Contest Change" + short_description: "Plan and implement KST4Contest changes safely" + default_prompt: "Analyze the requested KST4Contest change, explain your understanding and concept in German, ask implementation questions, and wait for approval before editing." + +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/kst4contest-change/references/architecture.md b/.agents/skills/kst4contest-change/references/architecture.md new file mode 100644 index 0000000..1b7d61b --- /dev/null +++ b/.agents/skills/kst4contest-change/references/architecture.md @@ -0,0 +1,102 @@ +# Architecture context + +## Current package shape + +The repository currently contains major packages under `src/main/java/kst4contest/` including: + +- `controller` +- `locatorUtils` +- `logic` +- `model` +- `service` +- `test` +- `utils` +- `view` + +Do not treat package names alone as proof of clean MVC boundaries. Inspect actual dependencies. + +## Preferred message/member data flow + +The established target architecture for active chat members is: + +```text +ON4KST / network + | + v +MessageBusManagementThread + | + v +ChatController + | + v +thread-safe active-member domain state +(ConcurrentMap; identity includes callsign + category) + | + v +JavaFX ObservableList UI mirror + | + v +FilteredList / SortedList / TableView / selection +``` + +Key rule: + +`ObservableList` is a JavaFX UI projection, not the canonical store for worker-thread logic. + +`MessageBusManagementThread` must not directly read or modify the UI list. + +## JavaFX boundary + +UI-visible mutations belong on the JavaFX Application Thread. + +Prefer controller-owned helpers such as an existing `runOnFxThread` abstraction when available; otherwise use `Platform.runLater` consistently. + +Do not move business/data access into the FX thread merely to silence a threading problem. + +## Parser/service separation + +For protocol receivers, the preferred direction is: + +```text +Receiver (I/O only) + -> Parser (wire data -> DTO) + -> Service (domain/persistence logic) + -> Controller (UI coordination) + -> Observable UI model + -> View +``` + +A previous concrete example for UCXLog was: + +```text +UcxUdpReceiver + -> UcxPacketParser + -> DTO + -> UcxLogService + -> ChatController + -> UI projection +``` + +This is architectural guidance, not permission for a broad refactor. Apply only when it is in scope and approved. + +## DTO preference + +Prefer explicit DTO classes over records when introducing protocol/transport data structures in this project, unless the approved concept intentionally changes that convention. + +## Null safety + +Chat members can be incomplete, especially: + +- fallback members; +- historic message senders; +- server-derived partial members. + +Values such as QRB and QTF can be absent. + +Rules: + +- absence stays absence; +- do not map `null` to numeric zero; +- UI must render unavailable state safely; +- sorting/filtering/calculation code must tolerate missing values; +- unexpected missing values must not terminate worker or UI threads. diff --git a/.agents/skills/kst4contest-change/references/automation-and-messaging.md b/.agents/skills/kst4contest-change/references/automation-and-messaging.md new file mode 100644 index 0000000..f85174c --- /dev/null +++ b/.agents/skills/kst4contest-change/references/automation-and-messaging.md @@ -0,0 +1,42 @@ +# Automated messaging, beacons and skeds + +## General + +Automated replies/beacons must be conservative because they interact with the live ON4KST service. + +## Established safety behaviour + +Historical confirmed rules include: + +- beacon/autoanswer scheduling shares controlled timing rather than spawning uncontrolled independent timers; +- minimum interval has been tightened to avoid spam; +- automated text length is bounded; +- invalid or incomplete replies are rejected before transmission; +- a cooldown is not consumed unless a complete valid reply enters the TX queue; +- QRG/frequency requests take precedence where the current implementation defines that; +- automated-message markers are ignored to prevent response loops. + +Recent logic used a two-minute cooldown keyed by complete callsign plus chat category and ignored the project's own automated-message marker. + +Treat exact marker strings and timing constants as current-code facts to verify, not values to recreate from memory. + +## Monitoring + +Station monitoring is intentionally base-call-wide: + +Entering a variant such as: + +```text +DN9APW-2 +DN9APW-70 +``` + +monitors: + +```text +DN9APW +``` + +This reduces manual configuration for sked monitoring. + +Keep this separate from chat-member identity, which may require full suffix + category. diff --git a/.agents/skills/kst4contest-change/references/domain-and-callsigns.md b/.agents/skills/kst4contest-change/references/domain-and-callsigns.md new file mode 100644 index 0000000..cf1216f --- /dev/null +++ b/.agents/skills/kst4contest-change/references/domain-and-callsigns.md @@ -0,0 +1,87 @@ +# Domain, callsigns and bands + +## Chat-member identity + +Full callsign variants can be distinct chat identities. + +Examples: + +```text +DN9APW +DN9APW-2 +DN9APW-70 +``` + +Do not globally strip suffixes when identifying chat members. + +Category is also part of identity. A practical key is conceptually equivalent to: + +```text +FULL_CALLSIGN|CATEGORY +``` + +Do not allow messages from one category to attach to a same-looking member in another category. + +## Base-call operations + +Some features intentionally operate on the base callsign. + +Confirmed examples: + +### Worked state + +Worked status is shared across suffix variants of the same base call. + +If the base station has been worked on the relevant basis, variants such as `CALL-2`, `CALL-70`, `CALL-144`, `CALL-432` should not become independent worked identities merely because of the suffix. + +### Monitoring + +Monitoring a station entered as `DN9APW-2` or `DN9APW-70` should monitor the base call `DN9APW`. + +This is intentional: a user monitoring another station's skeds should not have to create one monitor entry per SSID. + +Do not extend base-call matching to unrelated features without approval. + +## Suffix semantics + +Do not assume a suffix always means a band or category. + +Historical examples have shown the same base calls with different suffix conventions in different chat categories. + +Therefore: + +- preserve exact full-call identity where needed; +- normalize only for explicitly approved base-call features; +- never infer missing band/category semantics from the suffix alone. + +## Categories + +KST4Contest's central VHF/UHF usage focuses on ON4KST categories 2 and 3. + +However, other categories can occur. + +Rules: + +- unsupported/uninteresting categories must be ignored or handled safely; +- they must not produce index, switch or null errors; +- do not let their values contaminate category-2/category-3 band logic. + +## Band availability + +Band activity can be derived from several signals including name/text parsing and explicit/manual information. + +Confirmed invariant: + +`NOT-QRV` overrides positive availability indications. + +Known-active-band and `B+` handling should use one consistent interpretation across the program. + +Do not implement separate slightly different parsers in multiple UI/features if a shared existing mechanism is available. + +## Current QRG + +Features that depend on propagation/band/frequency should use the current relevant QRG or the approved band calculation. + +Never silently reintroduce a universal hardcoded 144 MHz fallback. + +When a frequency is ambiguous and no approved fallback exists, ask rather than guessing. diff --git a/.agents/skills/kst4contest-change/references/known-edge-cases.md b/.agents/skills/kst4contest-change/references/known-edge-cases.md new file mode 100644 index 0000000..6f155be --- /dev/null +++ b/.agents/skills/kst4contest-change/references/known-edge-cases.md @@ -0,0 +1,115 @@ +# Known edge cases and regression patterns + +This file is a regression-awareness list. Reproduce/inspect current code before deciding a historical bug still exists. + +## Incomplete ChatMember + +Known failure pattern: + +```text +Cannot invoke "java.lang.Double.intValue()" because +ChatMember.getQrb() is null +``` + +Lesson: + +- QRB can be absent; +- UI/calculation code must not blindly unbox/convert; +- unavailable is not zero. + +Apply the same reasoning to QTF and other server/fallback-derived fields. + +## Callsign suffix collisions + +A historical issue caused messages/identity problems between: + +```text +DN9APW +DN9APW-2 +``` + +The corrective model is not "strip all suffixes". + +Instead: + +- keep full-call chat identities distinct; +- include category; +- use base call only for explicitly base-call-wide features such as worked state/monitoring. + +## Unsupported chat categories + +The ON4KST ecosystem can expose categories outside the two central ones. + +A parser/switch/filter must not throw because the category is irrelevant to KST4Contest. + +Safe ignore/fallback beats fake band assignment. + +## AirScout higher-band queries + +A historical observation showed aircraft visible in AirScout while API results for a 432 MHz case were empty. + +Potential causes included frequency-string formatting. + +Lesson: + +- verify the exact upstream contract; +- compare request produced by KST4Contest with a known-working request; +- do not "fix" by guessing a string format or falling back to an unrelated band. + +## Second airplane-scatter result / missing aircraft + +A known UI failure involved missing/partial airplane-scatter data and a `TextInputControl` range error (`start must be <= end`). + +Lesson: + +- empty/partial AP results must be validated before text-range highlighting/selection; +- second-result paths need the same null/range checks as primary results. + +## Historic/unknown user message + +A user/message record can refer to a callsign not present in the current member list. + +Do not require current login membership to render or classify historic messages. + +## UM3-style handling + +Historical message handling included cases that should be ignored safely if the user is not in the chat/member state. + +Lesson: + +- external message types must tolerate missing member references. + +## CR/LF and disconnect suspicion + +Do not treat line endings as harmless text formatting in socket code. + +When diagnosing a disconnect: + +- inspect transmitted bytes; +- inspect server response/EOF; +- compare Windows versions only after proving the application sends different bytes; +- avoid duplicated LF/CRLF terminators. + +## Filter reset + +A reset button that clears control values but leaves predicates active is not a valid reset. + +Verify final predicate composition, not only UI state. + +## Map render flicker + +Leaflet/WebView render fragmentation under Java 21 was mitigated by: + +```text +window.L_DISABLE_3D = true +``` + +before Leaflet load. + +Do not remove as "obsolete CSS cleanup" without a visual regression check. + +## Network start/reconnect loop + +Initial connection failure must not spin indefinitely or block controlled recovery. + +Connection state must be based on actual I/O lifecycle rather than only `Socket.isConnected()`-style historical state. diff --git a/.agents/skills/kst4contest-change/references/project-behavior-catalog.md b/.agents/skills/kst4contest-change/references/project-behavior-catalog.md new file mode 100644 index 0000000..2e28605 --- /dev/null +++ b/.agents/skills/kst4contest-change/references/project-behavior-catalog.md @@ -0,0 +1,183 @@ +# Project behaviour catalog + +This catalog summarizes behaviour established during prior KST4Contest work. It is context for analysis, not permission to overwrite newer code. Always inspect the current implementation before modifying a listed area. + +## Core purpose + +KST4Contest is an ON4KST-oriented desktop client optimized for VHF/UHF/microwave contest workflows. + +Core areas developed over time include: + +- simultaneous ON4KST chat handling; +- priority candidates; +- sked workflow and timeline; +- worked-state synchronization; +- logging integrations; +- DXCluster; +- AirScout / airplane-scatter assistance; +- rotor/control integrations; +- map/path visualization; +- automated replies/beacons; +- user filtering and reachability; +- documentation and website/update-feed integration. + +## Two chat categories + +The application is designed around two simultaneous relevant chat categories in normal operation. + +Important consequences: + +- same-looking calls in different categories are not automatically the same chat identity; +- category is part of message/member identity; +- category-specific QRG/band settings must not leak into the other category; +- unsupported categories must not crash shared logic. + +## Priority candidates + +Priority scoring has included factors such as: + +- QTF match; +- recent activity; +- message count; +- positive signal indications; +- sked rate. + +Do not change weighting/meaning as collateral work. Treat it as user-facing contest logic. + +## Timeline / skeds + +The sked timeline has used 30-minute lanes and visualized airplane-scatter probability windows. + +Known historical AP strength levels: + +- 100%; +- 75%; +- 50%. + +Sked reminder presets have covered short contest-relevant lead times. + +Do not hardcode historical display constants into new code without verifying the current view/model. + +## Worked state + +Worked state is loaded from persistence and updated live from supported logging inputs. + +The simplified UI meaning has been "worked any" where the locator/worked indicator is concerned. + +Worked state is base-call-wide across suffix variants where established. + +When changing persistence or logging synchronization, verify: + +- startup DB load; +- live update; +- suffix/base-call mapping; +- band mapping; +- 50/70 MHz support where applicable; +- UI projection. + +## Known active bands / B+ + +Known-active-band information is derived consistently across the application from available hints. + +Historical work unified: + +- band mentions in user names; +- band mentions in text; +- manual/global band information; +- `B+`-style availability. + +Explicit `NOT-QRV` overrides positive hints. + +Avoid introducing a second parser with different semantics. + +## Selection and send workflow + +Established fast-workflow behaviour includes: + +- selecting a new station prefills `/cq callsign`; +- send text is geared toward minimal contest interaction; +- if no target chat category is selected, Main is the established fallback. + +These are intentional workflow decisions, not incidental UI details. + +## DXCluster + +DXCluster support has included: + +- integrated display; +- copyable lines; +- `/cq` workflow support; +- beacon monitoring; +- QTF/bearing-related presentation. + +Preserve locator semantics and avoid sender/receiver field confusion. + +## Map / path view + +Map work has included: + +- Leaflet 1.9.4 in JavaFX WebView; +- terrain/path information; +- airplane-scatter integration; +- target-station selection; +- path-analysis visibility; +- station-count/status information; +- target reset that does not reset zoom. + +A persistent right-side station-information panel has been reduced/removed in favour of more compact presentation in later UI work. + +Before changing layout, inspect the current version because this area has been actively iterated. + +## Reachability and filters + +Filter work has separated reachability concerns from generic filters. + +A Reset Filter control must reset the actual filter predicates, not just visual controls. + +UI sorting/filtering must remain stable when backing data changes. + +## Autoanswer and beacons + +Automated messaging exists to reduce repetitive contest chat work without creating spam or feedback loops. + +Important principles: + +- conservative timing; +- bounded text; +- no loop on own automated markers; +- only consume cooldown after a valid queued reply; +- category/callsign-safe identity; +- QRG requests handled with the intended precedence. + +## Connection handling + +Network reliability is contest-critical. + +Work has explicitly targeted: + +- accurate connected/disconnected state; +- server disconnect detection; +- reconnect behaviour on unstable links; +- no infinite loop on initial connection failure; +- visible connection-state indication in the UI. + +Do not regress connection state into "socket object exists therefore connected". + +## Historic messages + +Historic/non-current chat senders may not have a complete live `ChatMember`. + +Highlighting, display and parsing must tolerate users not currently logged in. + +## Website and documentation + +The application repository also contains: + +- bilingual manual content; +- documentation images; +- automated documentation PDF build; +- Eleventy website; +- download/update metadata generation; +- release-oriented website automation. + +A user-visible feature change may therefore affect more than Java source. diff --git a/.agents/skills/kst4contest-change/references/protocols-and-integrations.md b/.agents/skills/kst4contest-change/references/protocols-and-integrations.md new file mode 100644 index 0000000..62d7d14 --- /dev/null +++ b/.agents/skills/kst4contest-change/references/protocols-and-integrations.md @@ -0,0 +1,101 @@ +# Protocols and external integrations + +This file records stable rules plus historical context. For exact current wire formats, ports and frequency strings, inspect the current code and authoritative upstream documentation. + +## ON4KST + +KST4Contest depends on long-lived server communication where malformed commands or framing can lead to disconnects. + +Rules: + +- preserve exact protocol framing; +- treat CR/LF changes as protocol changes, not formatting cleanup; +- do not append extra line terminators without verification; +- detect actual socket/server disconnects reliably; +- initial connection failure must not create an uncontrolled infinite loop; +- reconnect logic must tolerate unstable Internet access; +- the UI should make disconnected state clearly visible where implemented. + +If Windows-specific behaviour is suspected, do not assume Win10/Win11 line-ending semantics explain it without reproducing or tracing the bytes. + +## UCXLog / DXLog UDP XML + +`contactreplace` must be handled equivalently to `contactinfo` for whole-log broadcasts where applicable. + +Historical raw-packet XML start detection included: + +```text + parser -> DTO -> service/domain/DB -> controller -> UI +``` + +## Win-Test + +Historical integration uses UDP port 8721 for Win-Test information. + +Do not hardcode this fact into unrelated logic. Verify current configuration before changing listener setup or band mapping. + +Changes involving 50/70 MHz, worked state or frequency mapping must be consistent with other logging inputs. + +## AirScout + +KST4Contest integrates with AirScout path/airplane-scatter information. + +Stable principles: + +- propagation/path queries must reflect the current relevant frequency/band; +- do not fall back to 144 MHz merely because older code did; +- unsupported chat categories must fail safely; +- frequency-string formatting is an external API contract and must be checked, not guessed. + +Historical work included a temporary 430 MHz approximation for ambiguous higher-band handling. Treat that as historical context, not a permanent invariant. Inspect the current implementation before using or changing it. + +## PSTRotator + +The integration has evolved. + +Historical project notes mention more than one control approach, and recent work included UDP control/feedback behaviour around a configurable control port and feedback on the next port, including SPID movement retry logic. + +Therefore: + +- inspect the current implementation before assuming TCP vs UDP; +- inspect current settings/defaults; +- do not copy an old port/transport assumption into new code; +- preserve asynchronous JavaFX-safe handling; +- preserve any verified retry sequence only if it still exists in current code/tests. + +If current code and historical notes conflict, ask Marc after showing the conflict. + +## DXCluster + +DXCluster is integrated into the contest workflow. + +Preserve: +- copyable/usable cluster lines; +- correct sender/receiver locator semantics; +- safe handling of missing locator data. + +A historical bug copied sender and receiver locators as equal; do not reintroduce that behaviour. + +## Protocol-wide error handling + +External data is not trusted to be complete. + +Rules: + +- validate before dereferencing; +- unknown categories/bands/tags should degrade safely; +- malformed packets must not kill long-running receiver/management threads; +- logging should make the rejected input diagnosable without flooding normal operation. diff --git a/.agents/skills/kst4contest-change/references/roadmap.md b/.agents/skills/kst4contest-change/references/roadmap.md new file mode 100644 index 0000000..3d40214 --- /dev/null +++ b/.agents/skills/kst4contest-change/references/roadmap.md @@ -0,0 +1,22 @@ +# Deferred and roadmap context + +This file is background only. Do not implement these items merely because they are mentioned here. + +## Propagation model + +After the manual audit, Marc intends to revisit and improve KST4Contest propagation modelling. + +Exploration areas include: + +- higher-density Copernicus GLO-30 terrain sampling; +- Fresnel-zone analysis; +- diffraction modelling; +- simplified ray tracing / multi-segment paths; +- VHF/UHF/microwave contest applicability, including around 1296 MHz and above; +- practical contest-oriented prediction rather than academic complexity for its own sake. + +This requires a fresh concept before implementation. + +## Rule + +Roadmap context must never silently enlarge the scope of a current task. diff --git a/.agents/skills/kst4contest-change/references/settings-and-data.md b/.agents/skills/kst4contest-change/references/settings-and-data.md new file mode 100644 index 0000000..abf639b --- /dev/null +++ b/.agents/skills/kst4contest-change/references/settings-and-data.md @@ -0,0 +1,80 @@ +# Settings and data context + +Inspect `Config`/settings classes and current UI before using these names; this list records important settings/concepts encountered during prior work. + +## Band / station settings + +Important concepts have included: + +- `MYQRGFirstCat`; +- `MYQRGSecondCat`; +- manual station band information; +- current/actual QTF; +- known-active bands; +- selected/current QRG. + +Band-dependent features must use the correct category/station context. + +## Antenna / path settings + +Important concepts have included: + +- `actualQTF`; +- `antennaBeamWidthDeg`; +- maximum QRB; +- AirScout/path-analysis settings. + +Missing QRB/QTF must remain unknown, not numeric zero. + +## UI settings + +Persisted UI behaviour has included: + +- dark mode; +- map/path-analysis visibility; +- filters/reachability controls; +- column visibility; +- divider/layout state where implemented. + +Do not reset persisted user choices as an incidental effect of a feature change. + +## Logging / worked persistence + +Worked information is persisted and updated through multiple input paths. + +Before changing one path, compare semantics across: + +- DB load on startup; +- simple/manual log integration where present; +- UCXLog/DXLog; +- Win-Test; +- other current logging inputs. + +The goal is one worked-state interpretation regardless of source. + +## Chat/message automation + +Configuration has included: + +- beacon/autoanswer enablement; +- beacon defaults; +- message limits/timers; +- category-specific communication. + +Do not duplicate timers or create per-feature scheduling that bypasses the shared safety model. + +## Connection state + +Connection-state UI must reflect actual ON4KST connection lifecycle. + +Any new state enum/property should have a clear owner and thread boundary. + +## Persistence rule + +Do not change persisted keys/schema/semantics simply to make new code easier. + +If a schema/key migration is required: + +1. explain current and new format; +2. describe backward compatibility; +3. ask for approval before implementing. diff --git a/.agents/skills/kst4contest-change/references/testing-build-release.md b/.agents/skills/kst4contest-change/references/testing-build-release.md new file mode 100644 index 0000000..267a2d1 --- /dev/null +++ b/.agents/skills/kst4contest-change/references/testing-build-release.md @@ -0,0 +1,100 @@ +# Build, tests, static analysis and release safety + +## Maven + +Use the repository Maven wrapper. + +Windows: + +```text +.\mvnw.cmd test +.\mvnw.cmd package +``` + +Run narrower tests first when possible. + +## Important Surefire behaviour + +The project has used: + +```xml +true +``` + +Therefore an exit code of zero is not sufficient evidence that all tests passed. + +Always inspect: + +- test counts; +- failures; +- errors; +- skipped tests; +- Surefire report output when necessary. + +State exact results in the completion report. + +## PMD and SpotBugs + +PMD and SpotBugs are integrated, but their findings have historically not always failed the build. + +Do not say "static analysis clean" unless the relevant reports/output were actually checked. + +## Packaging + +The build contains packaging/module-list consistency logic. + +Changes involving modules, JavaFX modules, jpackage or `module-info.java` must check: + +- `pom.xml`; +- `packaging/` helpers; +- module requirements; +- packaging verification output. + +Do not manually update only one copy of a generated/synchronized module list. + +## Website + +The website is Eleventy-based and has Node tests. + +Inspect `website/package.json`, `website/test/` and current scripts before choosing exact commands. + +Historical website validation included Node tests for generated version/update information. + +## Documentation build + +GitHub Actions generates documentation/PDF and site artefacts. + +A local code build does not prove documentation/site CI will pass. + +## Versioning + +Do not change project version, semantic version, update feed, tag or release metadata unless explicitly requested. + +## Git + +Each of these needs separate authorization: + +- stage; +- commit; +- push; +- PR; +- merge; +- tag; +- release. + +When asked to commit, use a concise English commit message. + +Do not stage unrelated files. + +## Release communication + +When a release is explicitly in scope, check: + +- current changelog; +- GitHub release/tag; +- website download/update feed; +- documentation; +- HamRadioOnline download/manual destinations; +- any SourceForge publication workflow currently used. + +Do not assume an older deployment pipeline is still active. diff --git a/.agents/skills/kst4contest-change/references/threading-and-state.md b/.agents/skills/kst4contest-change/references/threading-and-state.md new file mode 100644 index 0000000..91c58e1 --- /dev/null +++ b/.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 activeMembers + | + | FX-thread projection/update + v +ObservableList 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. diff --git a/.agents/skills/kst4contest-change/references/ui-behavior.md b/.agents/skills/kst4contest-change/references/ui-behavior.md new file mode 100644 index 0000000..6190426 --- /dev/null +++ b/.agents/skills/kst4contest-change/references/ui-behavior.md @@ -0,0 +1,65 @@ +# UI behaviour and workflow invariants + +These are known user-experience decisions. Verify the current implementation before changing them. + +## Selection and send text + +A new station selection should prefill the established command form: + +```text +/cq callsign +``` + +This behaviour is deliberate even when prior input text existed, according to the established workflow. + +If no category is selected for sending, the established fallback is the Main category. + +Do not change either behaviour as a side effect of unrelated refactoring. + +## Map view + +Known decisions: + +- reset clears the target/station selection; +- reset does not change the current zoom level; +- selected-station information was moved toward the compact status line rather than requiring a persistent right-side detail panel; +- path-analysis visibility is user-controllable and should not become undiscoverable; +- map controls must remain usable in dark/light modes. + +## Leaflet / JavaFX WebView + +With Leaflet 1.9.4 under Java 21, fragmented rendering/flicker was fixed by disabling Leaflet CSS 3D transforms before Leaflet loads: + +```text +window.L_DISABLE_3D = true +``` + +Do not remove/reorder this workaround without reproducing the rendering problem and proving the replacement. + +## Filters + +Known UI direction: + +- Reset Filter must actually clear relevant filter predicates; +- reachability controls are conceptually separate from generic filter controls; +- reset control should remain visually discoverable; +- truncated text should remain accessible through tooltips where implemented; +- clickable links should remain functional in both themes. + +## Priority / timeline + +The contest workflow includes: +- priority candidate presentation; +- sked timeline; +- activity/AP windows; +- sked reminders. + +Avoid UI changes that damage quick contest operation merely to make layout code simpler. + +## Null display + +Missing data is not `0`. + +For QRB/QTF/locator/derived values, follow the current UI convention for unavailable/empty state. + +Do not show a plausible-looking number when the model value is actually unknown. diff --git a/.agents/skills/kst4contest-documentation/SKILL.md b/.agents/skills/kst4contest-documentation/SKILL.md new file mode 100644 index 0000000..7fca611 --- /dev/null +++ b/.agents/skills/kst4contest-documentation/SKILL.md @@ -0,0 +1,74 @@ +--- +name: kst4contest-documentation +description: Perform targeted KST4Contest documentation-impact checks and update affected German/English manuals, README, website feature text, changelog, release notes and durable project context. Avoid full audits by default; keep documentation aligned with implemented behaviour and use the praktimarc-writing-style skill. +--- + +# KST4Contest documentation workflow + +Use `$software-project-context` and `$praktimarc-writing-style`. + +## Default behaviour + +Do not read the complete manual or website after every code change. + +Start with a documentation-impact classification and search for the affected feature, setting, UI label, protocol/integration or operational concept. + +Escalate to a broader audit only when: + +- Marc explicitly requests it; +- a major release is being prepared; +- the change is broad across UI/workflows; +- multiple targeted checks reveal wider drift. + +## Before editing documentation + +1. Inspect the actual implementation or approved specification. +2. Explain in German what documentation is probably affected. +3. Ask only unresolved behaviour/scope questions. +4. If documentation updates are already part of an approved implementation concept, no second approval is required for obvious synchronisation. +5. If documentation reveals a new material product decision, stop and ask Marc. + +## Manuals + +When user-facing behaviour is affected: + +- search English and German manual content under `github_docs/` for the relevant feature/labels first; +- inspect surrounding sections only; +- keep both language versions semantically equivalent; +- do not translate mechanically; English must be idiomatic; +- preserve exact UI labels, values, callsigns, ports and protocol terminology; +- document current behaviour only; +- if code and manual disagree and it is unclear which behaviour is intended, report the conflict; +- identify outdated/missing screenshots explicitly. + +## README / website + +Check only when the changed feature, installation, configuration, capability or compatibility is represented there or should reasonably be represented there. + +- Keep feature descriptions concise. +- Explain real contest/operating benefit, not marketing slogans. +- Avoid duplicating large manual sections on the website. +- Keep the main manual/download destinations consistent with the current site strategy. + +## Durable project context + +Update `docs/PROJECT_CONTEXT.md` for significant: + +- architectural decisions; +- threading/state ownership; +- callsign/category semantics; +- protocol/integration contracts; +- persistence/configuration changes; +- durable workarounds; +- deployment/website relationships; +- cross-project dependencies; +- planned propagation/API architecture when it becomes concrete. + +Keep current-state sections current rather than using the file as a raw changelog. + +## Changelog / release notes + +- Compact factual bullets. +- Include user-visible changes and important reliability/compatibility fixes. +- Do not invent version scope; derive it from actual commits/changelog/release context. +- Keep release posts short and operationally relevant. diff --git a/.agents/skills/kst4contest-documentation/agents/openai.yaml b/.agents/skills/kst4contest-documentation/agents/openai.yaml new file mode 100644 index 0000000..0c0ff35 --- /dev/null +++ b/.agents/skills/kst4contest-documentation/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "KST4Contest Documentation" + short_description: "Keep KST4Contest manuals, website and release text aligned" + default_prompt: "Review the implemented KST4Contest behaviour, explain the documentation impact in German, propose a concept, ask questions, and wait for approval before editing." + +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/kst4contest-documentation/references/current-feature-context.md b/.agents/skills/kst4contest-documentation/references/current-feature-context.md new file mode 100644 index 0000000..faccee8 --- /dev/null +++ b/.agents/skills/kst4contest-documentation/references/current-feature-context.md @@ -0,0 +1,26 @@ +# User-facing feature context + +This is a documentation coverage reminder, not a canonical feature list. Verify each item in current code before documenting it. + +Areas repeatedly documented or changed include: + +- simultaneous ON4KST chat categories; +- priority candidates; +- sked timeline/reminders; +- known active bands / B+ / NOT-QRV; +- worked indicators; +- DXCluster; +- AirScout integration; +- map/path analysis; +- filtering and reachability; +- PSTRotator/rotor integration; +- UCXLog/DXLog and Win-Test log synchronization; +- beacon/autoanswer behaviour; +- connection status/reconnect behaviour; +- dark/light UI behaviour; +- QTF/bearing workflow; +- download/update behaviour. + +When one of these changes, search both language manuals and website copy for affected references. + +Do not specialize documentation beyond actual behaviour. A useful example from prior work is callsign monitoring: entering an SSID-style variant can intentionally monitor the base call rather than requiring every suffix to be configured individually. diff --git a/.agents/skills/kst4contest-documentation/references/manual-and-website.md b/.agents/skills/kst4contest-documentation/references/manual-and-website.md new file mode 100644 index 0000000..d841393 --- /dev/null +++ b/.agents/skills/kst4contest-documentation/references/manual-and-website.md @@ -0,0 +1,47 @@ +# Manual and website context + +## Manual location + +KST4Contest documentation is maintained in `github_docs/` with English and German Markdown pages plus screenshots. + +The documentation build is automated through repository workflows. + +## Audit workflow established with Marc + +The normal review method is: + +1. compare documentation with actual code/behaviour; +2. propose exact changes; +3. note missing/outdated screenshots and their intended repo location; +4. if code must change to match the manual, stop and confirm that code change first; +5. keep German and English content aligned; +6. prefer one thorough update over many cosmetic iterations. + +With Codex editing locally, the old copy/paste insertion-guide step is replaced by direct edits, but the approval logic remains. + +## Examples and easter eggs + +Deliberate examples/test strings must not be "cleaned up" merely because they are informal. + +A known example uses: + +```text +DO5AMF +Testing DXC-Spot: Congrats, you donated $100! +``` + +Preserve such deliberate easter eggs unless Marc explicitly asks to remove or replace them. + +## Website + +The website under `website/` uses Eleventy/Nunjucks. + +Style direction: + +- modern and concise; +- technically focused; +- no promotional tone; +- English primary where appropriate; +- documentation remains the detailed source; website text should not duplicate entire manual sections. + +Current website architecture/scripts must be inspected before changes. diff --git a/.agents/skills/kst4contest-documentation/references/release-communications.md b/.agents/skills/kst4contest-documentation/references/release-communications.md new file mode 100644 index 0000000..2a2c7c1 --- /dev/null +++ b/.agents/skills/kst4contest-documentation/references/release-communications.md @@ -0,0 +1,35 @@ +# Release communications + +## Changelog + +Write concise English change descriptions. + +Prioritize: + +- behaviour users notice; +- contest workflow impact; +- protocol/integration compatibility; +- bug/reliability fixes; +- documentation improvements. + +Avoid internal refactor trivia unless it materially changes reliability or maintainability relevant to the release. + +## Social release post + +Use `$praktimarc-writing-style`. + +Typical structure: + +- version; +- short statement of what the release contains; +- compact highlights; +- operational context where relevant, e.g. preparation for a VUSHF contest or planned use at DM5M; +- one clear download/manual destination. + +Do not oversell. + +## Download/manual direction + +Marc has preferred routing users to the HamRadioOnline/KST4Contest download/manual pages rather than scattering multiple download links. + +Before publishing new text, inspect the current website URLs and release setup instead of copying an old link. diff --git a/.agents/skills/kst4contest-review/SKILL.md b/.agents/skills/kst4contest-review/SKILL.md new file mode 100644 index 0000000..e5484d8 --- /dev/null +++ b/.agents/skills/kst4contest-review/SKILL.md @@ -0,0 +1,52 @@ +--- +name: kst4contest-review +description: Review current KST4Contest local changes or a proposed diff before commit. Check regressions, null safety, JavaFX threading, callsign/category semantics, band handling, protocol compatibility, tests, targeted documentation impact, durable project context and unintended scope. Report findings in German and do not modify files unless explicitly asked after the review. +--- + +# KST4Contest review + +Review first; do not edit during the review. + +Read the relevant KST4Contest change references. + +## Review priorities + +1. Behaviour matches the approved concept. +2. No unrelated changes. +3. Full callsign/category identity remains correct. +4. Base-call normalization is used only where intended. +5. Null/unknown values are not converted to fake defaults. +6. Worker threads do not manipulate JavaFX UI collections. +7. FX-thread boundaries are correct. +8. Protocol framing, CR/LF, XML and frequency formatting are unchanged unless explicitly intended. +9. External malformed input cannot kill long-running threads. +10. Tests cover the changed behaviour. +11. Maven test output was interpreted correctly despite ignored-failure settings. +12. A documentation-impact assessment was performed. +13. Any likely affected manual/README/website sections match the implementation. +14. `docs/PROJECT_CONTEXT.md` is updated when the change introduces a durable architectural/protocol/state/operational/integration decision. +15. Comments/Javadoc are English. +16. No unintended dependency/version/release changes. + +Do not demand a full manual audit for an internal-only change when the impact assessment reasonably concludes there is no documentation effect. + +## Report format + +Report in German, ordered by severity. + +For each finding include: + +- affected file/location; +- concrete problem; +- consequence; +- recommended correction. + +Then include: + +- verification gaps; +- documentation-impact result; +- durable-context gaps; +- related-project gaps when relevant; +- overall assessment. + +Do not fix findings until Marc explicitly asks for implementation and the normal concept gate has been satisfied for the fixes. diff --git a/.agents/skills/kst4contest-review/agents/openai.yaml b/.agents/skills/kst4contest-review/agents/openai.yaml new file mode 100644 index 0000000..f1969b4 --- /dev/null +++ b/.agents/skills/kst4contest-review/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "KST4Contest Review" + short_description: "Review KST4Contest diffs before commit" + default_prompt: "Review the current KST4Contest changes only. Report findings in German and do not edit files." + +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/kst4contest-review/references/review-checklist.md b/.agents/skills/kst4contest-review/references/review-checklist.md new file mode 100644 index 0000000..d395c89 --- /dev/null +++ b/.agents/skills/kst4contest-review/references/review-checklist.md @@ -0,0 +1,61 @@ +# Review checklist + +## Scope + +- Is every changed file necessary? +- Did unrelated formatting or refactoring slip in? +- Were user-authored local changes preserved? + +## Architecture/threading + +- Is canonical state owned outside JavaFX controls/lists? +- Does worker code avoid `ObservableList` access? +- Are UI mutations routed to the FX thread? +- Are parser/I/O/domain/UI responsibilities clearer or at least not more coupled? + +## Domain + +- Full callsign + category identity preserved? +- Base-call matching restricted to worked/monitoring or another explicitly approved feature? +- Unknown category/band values safe? +- NOT-QRV precedence preserved? +- Missing QRB/QTF remains unavailable rather than zero? + +## Protocols + +- ON4KST framing unchanged unless approved? +- CR/LF exact? +- UCX `contactreplace` compatibility preserved? +- Frequency strings verified rather than guessed? +- PSTRotator/AirScout transport/API assumptions checked against current code? +- Malformed input contained? + +## UI + +- Selection/focus/zoom/sorting preserved? +- `/cq callsign` prefill behaviour preserved where relevant? +- Main send-category fallback preserved where relevant? +- map WebView workaround preserved? +- null values displayed safely? + +## Tests/build + +- Focused regression test added or updated? +- Test summary checked? +- Ignored failures explicitly reported? +- PMD/SpotBugs output considered? +- packaging/module-list checks considered if modules changed? + +## Documentation + +- DE and EN manual both checked? +- website/README/changelog checked if user-visible? +- screenshot impact reported? +- writing style applied? +- no undocumented implementation or documented-but-unimplemented behaviour? + +## Git/release + +- No version bump unless requested? +- No generated release/update-feed changes by accident? +- No staging/commit/push without explicit authorization? diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..9788c08 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,4 @@ +model_reasoning_effort = "high" +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "cached" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..54da608 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,180 @@ +# KST4Contest agent instructions + +These project instructions extend Marc's global Codex working agreements. + +## Project identity + +KST4Contest is a Java/JavaFX desktop client for ON4KST chat with contest-oriented workflows and integrations including logging software, AirScout, rotor control, DXCluster and local persistence. + +Primary repository areas: + +- `src/main/java/kst4contest/` +- `src/test/` where present; +- `github_docs/` +- `website/` +- `docs/` +- `packaging/` +- `.github/` +- `pom.xml` + +Inspect the current tree before assuming an exact class/path still exists. + +## Mandatory interaction rule + +For every planned code or documentation implementation: + +1. inspect first; +2. explain the task understanding in German; +3. identify and ask all relevant implementation questions; +4. wait for answers when needed; +5. present the final concept in German; +6. state what must remain unchanged; +7. request explicit concept approval; +8. wait; +9. implement only after approval. + +If an answer is uncertain, do not interpolate it. Check current code/tests/docs/project context first and ask Marc when the uncertainty can affect behaviour. + +## Language + +- Communicate with Marc in German. +- Write source-code comments and Javadoc exclusively in English. +- Keep log/protocol/API literals in their canonical form. +- Commit messages are concise English when a commit is explicitly requested. +- User-facing DE/EN documentation follows `$praktimarc-writing-style`. + +## Java and JavaFX architecture + +- Preserve or improve separation between network/parsing/service/controller/UI responsibilities. +- Do not solve architecture problems by letting worker/model code directly manipulate JavaFX UI collections. +- Active chat-member domain state is conceptually thread-safe state; JavaFX `ObservableList` data is a UI projection, not the canonical worker-thread store. +- `MessageBusManagementThread` must not directly read or mutate the JavaFX `ObservableList` used by the UI. +- Route UI-visible mutations through the controller and the JavaFX Application Thread (`Platform.runLater` or the project's equivalent helper). +- Prefer explicit DTOs over records when introducing transport/parser DTOs in this codebase unless the approved concept says otherwise. +- Handle incomplete external/historical data defensively. +- `qrb`, QTF and related external values can be absent. `null` means unavailable, not zero. +- Unexpected input must not terminate message-processing or UI threads. + +## Callsign and category identity + +- Preserve full callsign variants as distinct chat-member identities where the server exposes them separately. +- Category is part of chat identity. Do not merge messages across categories. +- Base-call normalization may be used only for explicitly base-call-wide features such as worked status or monitoring rules. +- Worked status is shared across suffix variants of the same base call. +- Monitoring a callsign variant such as `DN9APW-2` or `DN9APW-70` is intended to monitor the base call `DN9APW`, so users do not need to enter every SSID. +- Do not generalize suffix semantics beyond behaviour explicitly established by the current code/specification. + +## Bands and availability + +- ON4KST categories 2 and 3 are central to the normal VHF/UHF workflow, but other category values can occur and must fail safely. +- Do not let unsupported categories produce exceptions. +- Known-active-band logic and `B+` interpretation must remain consistent across the application. +- Band information parsed from names/text must respect explicit `NOT-QRV` information; NOT-QRV overrides positive availability hints. +- Do not silently fall back to a fixed band/frequency when a required decision is ambiguous unless an approved fallback exists. +- Manual band settings and actual current QRG must remain consistent with features that depend on frequency. + +## External protocols and integrations + +Before changing ON4KST, AirScout, UCXLog/DXLog, Win-Test, PSTRotator or DXCluster handling: + +- inspect the current implementation; +- preserve exact framing and compatibility; +- inspect current tests; +- check authoritative upstream documentation when the protocol detail is uncertain; +- ask Marc if more than one behaviour is plausible. + +Specific invariants and historical context are in `$kst4contest-change` references. + +Never change CR/LF, XML framing, callsign normalization, frequency formatting or port/transport assumptions casually. + +## UI behaviour + +- Preserve contest workflow speed and discoverability. +- Do not change zoom, selection, focus, sorting, tab choice or prefilled text as an incidental side effect. +- Map reset behaviour should clear the selected target without changing the zoom unless a new task explicitly changes this. +- New station selection should preserve the established `/cq callsign` prefill behaviour. +- If no send category is selected, preserve the established Main-category fallback unless explicitly changed. +- Null/unknown data must render as unavailable/empty according to current UI conventions, not as fake zero values. + +## WebView / map compatibility + +- The Leaflet WebView workaround that disables problematic CSS 3D transforms before Leaflet loads is a known Java 21 stability measure. Do not remove or reorder it without reproducing and understanding the original rendering/flicker problem. + +## Autoanswer / beacon safety + +- Prevent automated-message loops. +- Respect the established minimum interval/cooldown logic. +- Do not consume a cooldown for a reply that is rejected before a complete valid TX item is queued. +- Preserve priority of frequency/QRG requests where established. +- Cooldown identity must not accidentally collapse unrelated callsign/category identities. +- Treat the current implementation/tests as the source of truth for exact message markers and timer details. + +## Build and verification + +Use the Maven wrapper. + +Windows: + +```text +.\mvnw.cmd ... +``` + +Read the current `pom.xml` before relying on version numbers. + +At the package creation snapshot the project uses Java 21 / JavaFX 21.x and JUnit 5/Mockito, with PMD and SpotBugs integrated. + +Important: Maven/Surefire configuration has historically allowed test failures to be ignored, and static-analysis findings may not fail the build. Therefore: + +- inspect the Maven test summary; +- inspect Surefire results when needed; +- do not infer "all tests passed" from exit code 0; +- report PMD/SpotBugs findings that are visible in the relevant build. + +Run focused tests first, then normally the relevant broader test/build command for the scope. + +## Documentation and durable project context + +Use `$software-project-context`, `$kst4contest-documentation`, and `$praktimarc-writing-style` as relevant. + +Do not perform a full manual or website audit after every implementation. + +After a completed change: + +1. perform a short documentation-impact classification; +2. if user-visible behaviour is plausibly affected, search only the relevant German and English manual sections under `github_docs/`; +3. keep both language versions semantically aligned when an update is required; +4. check README and website feature text only when the changed feature/configuration is represented there or is likely to need representation; +5. identify screenshots that are likely stale instead of fabricating replacements; +6. update `docs/PROJECT_CONTEXT.md` for significant architectural, protocol, state/persistence, operational, integration, deployment, workaround, or long-lived behavioural decisions; +7. keep `Related Projects / Integration Points` current when KST4Contest, its website, hamradioonline infrastructure or planned propagation services affect one another. + +A full documentation audit is reserved for explicit audit requests, major release preparation, broad UI/workflow changes, or evidence that documentation is broadly stale. + +## Website + +The repository contains an Eleventy-based website under `website/` with its own tests/build logic. + +Do not assume website deployment/update-feed details; inspect current scripts/workflows before changing them. + +## Change scope and Git + +- No unrelated refactoring. +- No production dependency without prior approval. +- No automatic version bump. +- No commit/push/merge/tag/release/deploy without separate explicit authorization. +- Preserve deliberate test data and easter eggs unless explicitly changed. +- Never overwrite unrelated working-tree changes. + +## Completion + +After implementation, report in German: + +- understanding fulfilled; +- changed files; +- important design decisions; +- tests/builds and exact results; +- documentation-impact classification; +- manual/website/README/context updates made or why none were necessary; +- related-project impact when relevant; +- remaining uncertainty; +- suggested next action, without performing it automatically. diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md new file mode 100644 index 0000000..f867d83 --- /dev/null +++ b/docs/PROJECT_CONTEXT.md @@ -0,0 +1,159 @@ +# KST4Contest Project Context + +Last reviewed: 2026-08-25 + +This file is the durable technical project context for KST4Contest. It is not a user manual and not a replacement for the changelog. Current code, tests and authoritative external specifications remain the source of truth when this document is stale or ambiguous. + +## Purpose + +KST4Contest is a Java/JavaFX desktop client for ON4KST chat focused on VHF/UHF/microwave contest workflows. It combines chat handling with contest-oriented station prioritisation, sked/timeline workflows and integrations with logging, aircraft-scatter, rotor and DX-cluster tooling. + +## Current Architecture + +- Java 21 / JavaFX desktop application built with Maven. +- Main code is under `src/main/java/kst4contest/`. +- Responsibilities are separated across controller, service, logic, model, utility and view areas. +- Network/parser/service/controller/UI boundaries should remain explicit. +- Long-running network/message processing must tolerate malformed or incomplete external input without terminating processing threads. +- JavaFX `ObservableList` state is a UI projection, not the canonical worker-thread domain store. + +## Important Invariants + +### Chat identity + +- Full callsign variants can be distinct chat-member identities. +- Category is part of chat identity. +- Base-call normalization is permitted only for explicitly base-call-wide functions. +- Worked status is shared across suffix variants of the same base call. +- Monitoring a variant such as `DN9APW-2` or `DN9APW-70` intentionally monitors the base call `DN9APW`. +- Suffixes must not be globally interpreted as a band/category/frequency. + +### Band and availability semantics + +- ON4KST categories 2 and 3 are the main operational categories, but unexpected category values must fail safely. +- `NOT-QRV` overrides positive inferred band-availability hints. +- Unknown/missing frequency, QRB, QTF or similar external data must remain unavailable rather than becoming a fabricated zero/default. +- Features that depend on frequency should use the current/actual QRG according to current implemented rules; do not silently revert to a fixed 144 MHz default. + +### JavaFX/threading + +Conceptually: + +```text +thread-safe canonical domain state + | + | projection on JavaFX Application Thread + v +JavaFX ObservableList / UI state +``` + +`MessageBusManagementThread` must not directly iterate or mutate UI-bound JavaFX collections. UI-visible changes should cross the controller/UI boundary and run on the JavaFX Application Thread. + +## External Interfaces + +Treat current implementation/tests and authoritative upstream documentation as source of truth before modifying any interface. + +Known integration areas include: + +- ON4KST chat; +- AirScout; +- UCXLog / DXLog UDP XML (`contactinfo`, `contactreplace`); +- Win-Test UDP; +- PSTRotator TCP; +- DXCluster; +- local SQLite persistence. + +CR/LF framing, XML framing, ports/transports, callsign normalization and frequency formatting are protocol behaviour and must not be changed as incidental cleanup. + +## User Workflow / UI Invariants + +- Contest operating speed and low-friction interaction are primary goals. +- Incidental code changes must not unexpectedly change selection, focus, sorting, tab state, map zoom or prefilled text. +- Map reset clears the selected target without changing zoom unless explicitly redesigned. +- Station selection preserves the established `/cq callsign` prefill behaviour. +- Sending without an explicitly selected send category preserves the established Main-category fallback unless explicitly changed. + +## Autoanswer / Beacon + +- Automated-message loops must be prevented. +- Cooldown/minimum-interval rules must be preserved. +- A reply rejected before a complete valid TX item is queued must not consume cooldown. +- Current implementation/tests define the exact message markers and timer details. + +## Build / Verification + +- Use the repository Maven wrapper (`.\mvnw.cmd` on Windows). +- The project uses Java 21 / JavaFX 21.x at this context snapshot. +- JUnit 5/Mockito, PMD and SpotBugs are part of the verification environment. +- Build/test configuration has historically allowed some test/static-analysis failures not to fail the process exit code. Always read actual summaries/reports. + +## Documentation Surfaces + +- German and English manuals under `github_docs/`. +- Repository README. +- Eleventy-based project website under `website/`. +- Changelog/release communication. +- This technical project context under `docs/PROJECT_CONTEXT.md`. + +After implementation use targeted documentation-impact checks. Do not run a complete manual audit unless explicitly requested, release preparation is broad, or targeted checks indicate systematic drift. + +## Website / Deployment Relationship + +The repository contains the KST4Contest website under `website/`, published separately from the desktop application build. + +Current website/deployment scripts and update-feed behaviour must be inspected before changes; do not rely on historical assumptions. + +## Important Decisions and Workarounds + +- Preserve full callsign/category identity while applying base-call normalisation only to specifically defined features. +- Keep canonical worker-thread domain state separate from JavaFX UI projections. +- Preserve the established JavaFX WebView/Leaflet workaround that avoids problematic CSS 3D transforms unless the original rendering/flicker issue has been reproduced and the replacement is validated. +- Deliberate test data, comments and Easter eggs are preserved unless explicitly changed. + +## Planned Technical Direction + +These are planned directions, not necessarily implemented behaviour: + +- improve propagation/path modelling using higher-resolution terrain data, including Copernicus GLO-30; +- increase terrain/path sampling through a dedicated service/API; +- support high-precision station locations (e.g. extended Maidenhead locators or direct GPS coordinates) while preserving compatible standard display; +- improve terrain/Fresnel/diffraction/refraction modelling for VHF/UHF/microwave use; +- evaluate/implement richer tropospheric/scatter models; +- continue integration of aircraft-scatter and propagation data into reachability/contest workflows. + +Before implementing planned items, re-check current decisions and obtain a fresh concept approval. + +## Known Limitations / Maintenance Notes + +- Historical project context is useful but may be stale; current code/tests win. +- External service/API behaviour must be verified against current upstream documentation when uncertain. +- Screenshots in manuals/website may need targeted replacement after visible UI changes; never fabricate them. + +## Recent Significant Changes + +### 2026-08-25 – Durable project context introduced + +- Added a persistent technical context layer so future agents/developers can understand architecture, invariants and cross-project dependencies without replaying chat history. +- Documentation maintenance uses targeted impact assessment rather than a full audit after every implementation. + +## Related Projects / Integration Points + +### KST4Contest website + +- Source is maintained inside this repository under `website/`. +- User-facing feature/configuration changes may require a targeted website check. + +### hamradioonline.de + +- Serves as the broader amateur-radio umbrella site/infrastructure context. +- KST4Contest content/download/manual links and related knowledge content may intersect with the broader site strategy. + +### Webserver / hosting infrastructure + +- KST4Contest website and other hamradioonline services depend on the hosting environment. +- Operational details should be maintained in a private infrastructure context rather than duplicated into this public project context when sensitive. + +### Planned propagation / terrain service + +- Intended to provide richer terrain/propagation data (including higher-resolution Copernicus GLO-30-based processing) to KST4Contest and potentially related hamradioonline tooling. +- Interface contracts must be documented on both provider and consumer sides when they become concrete.