From 6773c6363465a9ba5a352596878299d821ac7db3 Mon Sep 17 00:00:00 2001 From: Marius Ciepluch <11855163+norandom@users.noreply.github.com> Date: Fri, 9 Oct 2026 11:58:10 +0200 Subject: [PATCH] steering: operator Discord notifications for OpenUltraSAST process status Record the policy: OpenUltraSAST notifies the system/AI operator on Discord about its own processes and results, and especially when a process is stuck or impaired (stall, insufficient result, abort, instrument_failure, timeout, budget/resource limit). Operator-facing, not developer debugging, and explicitly not k3s/ax infrastructure. Credentials by name in gitignored .env (DISCORD_WEBHOOK_URL, DISCORD_OPERATOR_ID), listed blank in .env.example; off when unset. Messages carry status/counts/digests only, under the hardening and measurement-record redaction (no payloads, secrets, or repo content). Notifier implementation to be wired/specced; this states the behavior. Co-Authored-By: Claude Opus 4.8 --- .env.example | 7 +++ .kiro/steering/operator-notifications.md | 60 ++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 .kiro/steering/operator-notifications.md diff --git a/.env.example b/.env.example index 6274c0e..7c4b710 100644 --- a/.env.example +++ b/.env.example @@ -21,3 +21,10 @@ OPENROUTER_API_KEY= # AWS_SESSION_TOKEN= # The bucket must have versioning enabled, a lifecycle rule expiring runs/, S3 Select and readable object tags # (see docs/rustfs.md); the store verifies them at startup and refuses to run otherwise. + +# Operator notifications (Discord). Status of OpenUltraSAST processes and their results for the +# system/AI operator -- not developer debugging, and not k3s/ax infra health. See +# .kiro/steering/operator-notifications.md. Webhook posts to the operator channel; the operator id +# is the account to @mention on a stuck/impaired alert. Leave blank to disable notifications. +DISCORD_WEBHOOK_URL= +DISCORD_OPERATOR_ID= diff --git a/.kiro/steering/operator-notifications.md b/.kiro/steering/operator-notifications.md new file mode 100644 index 0000000..3a01932 --- /dev/null +++ b/.kiro/steering/operator-notifications.md @@ -0,0 +1,60 @@ +# Operator notifications (Discord) + +Recorded 2026-10-09 from the maintainer's direction. OpenUltraSAST notifies the operator on +Discord about the status and results of its own processes, and especially when a process is +**stuck or otherwise impaired**. This is an operator channel, not a developer or infrastructure +one. + +## Audience + +The **system operator** and the **AI operator** who run and oversee the tool. Not developers +debugging the code, and not an infrastructure on-call. The messages answer "is the work moving, +did it finish, what did it produce, is it stuck" for someone supervising a run, not "why does this +function throw". + +## Scope: OpenUltraSAST processes and their results + +Notify on the actual OpenUltraSAST workloads and what they produce: + +- scans and pre-push checks (a completed check and its verdict/degradations), +- unseen-repo sourcing / draft, freeze, and replay / baseline runs, +- learning and evaluation runs (compile, evaluate, experiments) and their recorded results, +- fusion / adjudication and any long-running job. + +**Not** k3s or ax cluster infrastructure. Cluster, node, and ax-task health is a separate +infrastructure concern monitored elsewhere; this channel does not carry it. The line is: a message +here is about an OpenUltraSAST process or result, never about the plane's plumbing. + +## When to notify + +- **Completion:** a process finished, with a one-line result summary (counts, status, digest). +- **Stuck or impaired (the important case):** a stall, a clean-but-short result + (`insufficient_*`), an abort or `instrument_failure`, a timeout or deadline hit, budget + exhaustion, or a resource limit (disk, memory). These @mention the operator so a supervised run + does not sit silently broken. + +Advisory and low-volume by design: a start/finish and the impaired cases, not per-step chatter. + +## Transport and secrets + +A Discord webhook, with credentials referenced by name only and stored in gitignored `.env`, like +every other credential (`.env.example` lists the names, blank): + +- `DISCORD_WEBHOOK_URL` — the operator channel webhook. +- `DISCORD_OPERATOR_ID` — the account to @mention on a stuck/impaired alert. + +The webhook URL is a secret (anyone holding it can post to the channel): it never enters a tracked +file, a prompt, a log, or a commit, and it is rotated if exposed. Notifications are **off** when the +webhook is unset, so the tool runs the same with or without it. + +## Content discipline + +Messages carry status, counts, and digests only, under the same redaction as the hardening and +measurement-record conventions: no exploit payloads or request strings, no secrets, no customer +content, no repository contents. A notification is safe to read in a shared channel. + +## Status + +Policy recorded; the notifier (reading the env-named webhook, quiet when unset, honoring the +redaction above) is to be wired into the process entry points and may be specced separately. Until +then this steering states the intended behavior for any process that adds notifications.