Harden beacon sessions and mark automatic messages

docs/superpowers/plans/2026-11-13-automatic-chat-suffix.md

@@ -0,0 +1,96 @@
+# Automatic Chat Suffix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Append the fixed suffix ` *a*` to every active KST4Contest autoanswer and beacon while leaving manual and protocol traffic unchanged.
+
+**Architecture:** A package-private `AutomaticChatMessageFormatter` owns the suffix and performs unconditional appending. The active autoanswer and beacon producers call it explicitly; beacon validation keeps a 120-character payload allowance and validates the resulting 124-character maximum.
+
+**Tech Stack:** Java 21, Kotlin 2.2, Gradle wrapper, JUnit 5, Mockito
+
+**Spec:** `docs/superpowers/specs/2026-11-13-automatic-chat-suffix-design.md`
+
+## Global Constraints
+
+- The exact suffix is ` *a*`, including its leading space.
+- `[KST4C Automsg]` remains on autoanswers and remains the loop-prevention marker.
+- Suffix insertion is unconditional; duplicate `*a*` markers are allowed.
+- Beacon payloads remain limited to 120 characters; complete suffixed beacons are limited to 124 characters.
+- Manual messages and internal ON4KST frames must remain byte-for-byte unaffected by this feature.
+- No new dependency, setting, persistence field, version bump, staging, commit or publication action.
+
+## Review Focus
+
+- A 120-character beacon payload must be sent as exactly 124 characters after suffix insertion.
+- A 121-character beacon payload must still be rejected rather than producing a 125-character frame.
+- Text already ending in `*a*` must receive a second suffix without deduplication.
+- Autoanswer validation and cooldown accounting must still reject invalid text before consuming cooldown.
+- The existing prefix-based ping-pong guard and all manual send paths must remain unchanged.
+
+---
+
+### Task 1: Shared automatic-message formatter and autoanswers
+
+**Files:**
+- Create: `core/src/main/java/kst4contest/controller/AutomaticChatMessageFormatter.java`
+- Create: `core/src/test/java/kst4contest/controller/AutomaticChatMessageFormatterTest.java`
+- Modify: `core/src/main/java/kst4contest/controller/MessageBusManagementThread.java`
+- Modify: `core/src/test/java/kst4contest/controller/MessageBusManagementThreadAutoAnswerDecisionTest.java`
+- Modify: `core/src/test/java/kst4contest/controller/MessageBusManagementThreadAutoAnswerTest.java`
+- Modify: `core/src/test/java/kst4contest/controller/MessageBusManagementThreadChatFrameTest.java`
+
+**Interfaces:**
+- Produces: `AutomaticChatMessageFormatter.appendSuffix(String messageText): String`
+- Consumes: existing `ApplicationConstants.AUTOANSWER_PREFIX` and `On4KstProtocol.messageText(String)`
+
+- [x] Add failing formatter tests for exact suffix insertion and intentional duplicate suffixes.
+- [x] Run `\.\gradlew.bat :core:test --tests "kst4contest.controller.AutomaticChatMessageFormatterTest"` and confirm the tests fail because the formatter is absent.
+- [x] Implement the package-private formatter with `SUFFIX = " *a*"` and unconditional appending.
+- [x] Update failing autoanswer and version-reply expectations so generic, QRG and `//VER` replies end in ` *a*` while retaining `[KST4C Automsg]`.
+- [x] Append before final autoanswer protocol validation and in the `//VER` construction path.
+- [x] Run the formatter and three focused autoanswer test classes and confirm zero failures.
+
+### Task 2: Beacon suffix and length boundaries
+
+**Files:**
+- Modify: `core/src/main/java/kst4contest/controller/ChatController.java`
+- Modify: `core/src/main/java/kst4contest/controller/BeaconTask.java`
+- Modify: `core/src/test/java/kst4contest/controller/On4KstProtocolTest.java`
+- Modify: `core/src/test/java/kst4contest/controller/BeaconTaskTest.java`
+
+**Interfaces:**
+- Consumes: `AutomaticChatMessageFormatter.appendSuffix(String)` from Task 1
+- Produces: beacon payload validation at 120 characters and final-message validation at 124 characters
+
+- [x] Add failing tests asserting that each queued beacon ends in ` *a*`, a 120-character payload produces a 124-character message, and a 121-character payload is rejected.
+- [x] Run `\.\gradlew.bat :core:test --tests "kst4contest.controller.On4KstProtocolTest" --tests "kst4contest.controller.BeaconTaskTest"` and confirm the new assertions fail.
+- [x] Separate the 120-character payload limit from the 124-character final beacon limit in `ChatController`.
+- [x] Append the suffix only after macro resolution and payload validation, then validate the final message before queueing.
+- [x] Run the focused beacon tests and confirm zero failures.
+
+### Task 3: Targeted documentation and verification
+
+**Files:**
+- Modify: `github_docs/de-Konfiguration.md`
+- Modify: `github_docs/en-Configuration.md`
+- Modify: `github_docs/de-Makros-und-Variablen.md`
+- Modify: `github_docs/en-Macros-and-Variables.md`
+- Modify: `github_docs/de-Funktionen.md`
+- Modify: `github_docs/en-Features.md`
+- Modify: `github_docs/de-Changelog.md`
+- Modify: `github_docs/en-Changelog.md`
+- Modify: `website/src/features/automatic-replies.md`
+- Modify: `website/src/features/macros.md`
+- Modify: `docs/PROJECT_CONTEXT.md`
+
+**Interfaces:**
+- Consumes: implemented suffix and length behaviour from Tasks 1 and 2
+- Produces: aligned German/English user documentation and durable current-state context
+
+- [x] Update examples and behavioural text so autoanswers retain `[KST4C Automsg]` and all automated chat messages end in ` *a*`.
+- [x] Document the 120-character beacon payload and 124-character transmitted-message limits in German and English.
+- [x] Record the fixed suffix rule in the changelogs and `docs/PROJECT_CONTEXT.md` without changing unrelated documentation.
+- [x] Run the focused core tests from Tasks 1 and 2, then `\.\gradlew.bat build`.
+- [x] Read every Gradle test-result XML summary and report failures, errors and skipped tests; inspect PMD and SpotBugs XML counts produced by the build.
+- [x] Run the website test/build commands defined by the current `website/package.json` if the changed website pages participate in that build.
+- [x] Run `git diff --check` and review the complete scoped diff for accidental changes; perform no Git publication action.