---
name: Aria Corrections & Learnings
description: Aktive Korrekturen und Regeln — jeder Eintrag verhindert denselben Fehler.
type: learnings
date: 2026-05-11
title: CORRECTIONS
tags: [root]
status: aktiv
---

# ARIA — Corrections (Aktive Regeln)

**Verwandte Notizen:** [[SOUL]] · [[SELF-IMPROVEMENT]] · [[HEARTBEAT]] · [[HOOKS]] · [[HANDOFF]]

## Promotion-Regel

3× Recurrence → in SOUL.md promoten. 5× → in SELF-IMPROVEMENT als Behavioral Rule.

## Refactor-Note (V5 Sprint 1)

Telegraph-Style. Pattern + 1-Satz-Rule + Quelle. Lange Spec-Records (multi-step Fixes) bleiben ausführlich, kurze Behavioral-Rules sind kompakt.

## Split-Note (KAR-68, 11.05.2026)

Historische Infra-LRNs (≥1 Monat alt, Fix in Tools gebacken oder als Behavioral Rule promoted) in `CORRECTIONS.archive/2026-Q2-historical-infra.md` ausgelagert. Aktive Regeln hier bleiben unter 12 KB Bootstrap-Cap.

---

## Aktive Regeln

### LRN-20260402-007 — Umlaute in Website-Texten
`comm.umlaute_in_website_texten` · Recurrence: 2 · TSX/HTML immer echte Umlaute. Nach dem Schreiben: `grep -E "ue|ae|oe"` in geänderten Dateien.

### LRN-20260406-008 — Eat your own dogfood
`arch.eat_own_dogfood` · Was wir an User ausliefern, selbst nutzen. Konsistenz für Bug-Reproduktion.

### LRN-20260416-001 — Telegram-Sprachnachrichten transkribieren
`telegram.voice_message_handling` · `attachment_file_id` ohne `image_path` → `download_attachment` → `python3 /root/scripts/groq-whisper.py <path>` → als Text behandeln.

### LRN-20260506-001 — Telegram Inbound-Logging via Plugin-Patch
`infra.telegram_inbound_via_plugin_patch` · Telegram-Channel-Messages kommen als MCP `notifications/claude/channel`, NICHT als UserPromptSubmit-Event. Hook und tmux-Scraping sehen sie nicht.

Fix 06.05.2026: Direct-Patch in `/root/.claude/plugins/cache/claude-plugins-official/telegram/0.0.6/server.ts` nach `mcp.notification({...})` in `handleInbound()` — fire-and-forget `fetch` zu `${ARIA_SUPABASE_URL}/rest/v1/aria_chat_log`. Env-Vars via `aria-wrapper.sh` (`set -a; source .env.aria; set +a`) ans Plugin vererbt.

Backup: `server.ts.bak.20260506`. **Bei Plugin-Update Patch verloren** — analog zum archivierten LRN-20260402-001. Nach Update prüfen ob `aria-patch: supabase log inbound` Block noch da ist.

### LRN-20260506-002 — Telegram-Token zwei Quellen
`infra.telegram_token_two_sources` · Frische Installs: Token nur in `/root/.claude/channels/telegram/.env` (MCP-Konvention), nicht in `/root/aria/.env` (Hook-Konvention). Fix: `session-start.sh` liest `TG_TOKEN` mit Fallback — erst aria/.env, dann channels/.env. **Single Source of Truth: `/root/.claude/channels/telegram/.env`**, NICHT in beide duplizieren.

### LRN-20260506-003 — Kais pastet Secrets über Telegram
`comm.kais_secrets_via_telegram` · Kais hat 06.05.2026 GitHub PAT + Linear API Key über Telegram trotz Warnung gepasted. Sein Workflow: Bequemlichkeit > Token-Hygiene.

Wie ich künftig handle:
1. Bei Setup-Tasks die Token brauchen: alternativen Setup-Weg (Web-Form, SSH-direkt, Onboarding-Skill) parat haben — sonst ist Warnung leer.
2. Wenn er trotzdem in Telegram pastet: einmal warnen, dann pragmatisch in `/root/aria/.env` (chmod 600), API-Test laufen lassen. Nicht 5× wiederholen.
3. Rotation/Revoke nur auf explizites OK (SOUL Punkt 4 „explizite Anweisung" steht über Sicherheits-Reflex, sofern nicht akut katastrophal).
4. Lokale Spuren (SQLite, Supabase, JSONL-Transcript) prüfen + transparent berichten — er entscheidet über Scrub.

Aufgabe nächstes Onboarding: Sicherer Token-Eingabe-Weg (Aria-Dashboard `/setup`-Form ohne Telegram-Spur). Solange das fehlt: Telegram bleibt Default.

### LRN-20260506-005 — Vercel verlangt valide Author-Email
`infra.vercel_requires_real_author_email` · Erster Push auf KADi-backend `main` (06.05.2026) blockiert mit `ERROR` 0s, leere Logs. Grund: Author `Aria <aria@kadicon.local>` — `.local` ist keine resolvable Domain.

**Regel:** Bei JEDEM Commit auf Vercel-deployten Repos: echte Email als Author. `git -c user.email=aseckzai@gmail.com -c user.name="Kais Aseckzai" commit ...`. Niemals `*.local`-Pseudo-Domains.

Recovery: `git commit --amend --reset-author --no-edit` mit korrektem `-c user.email=` plus `git push --force-with-lease` (nur nach explizitem OK).

### LRN-20260506-006 — SessionStart-Hook lud Supabase nicht
`infra.session_start_hook_supabase_lookup` · Hook sourced kein `.env`, Subprocess hatte keine `ARIA_SUPABASE_URL`. Plus falscher Skript-Name (`aria-context-restore-supabase.py` statt `aria-context-restore.py`) versteckt durch `2>/dev/null`.

**Regel:** Hook-Skripte die ENV brauchen → Hook sourced selbst ODER Helper parsed `.env`. Default-Endpoints NICHT als Fallback in Helper-Code — hart fehlschlagen statt falsche DB. `2>/dev/null` versteckt FileNotFound — bei Hook-Skript-Calls einmal ohne Stderr-Suppression testen.

Fix 06.05.2026 in `session-start.sh` Subshell mit `set -a; source .env.aria; source .env; set +a` + Fallback `ARIA_SUPABASE_URL=$SUPABASE_URL`. Backup `session-start.sh.bak.20260506-supabase`.

### LRN-20260508-001 — Telegram-Format MarkdownV2
`comm.telegram_markdownv2_default` · Standard ab 08.05.2026. Kais hat nach Plain-Text-Bericht-Screenshot Bold/Code/Pre angefordert.

**Tool-Aufruf:** `mcp__plugin_telegram_telegram__reply` mit `format: "markdownv2"`. Plain-Text nur in Notfällen.

**Layout:**
- Section-Header: `*Header*` (Bold)
- Bullets: `•` (U+2022). Kein Escape. `-` und `—` müssten escaped werden, deshalb meiden.
- Code/Pfade/IDs/Commits inline: `` `text` ``
- Mehrzeiliger Code: ``` ```pre``` ``` (Tap-to-Copy)
- Leerzeile zwischen Sections
- Wichtigstes zuerst, max 5 Bullets/Section

**Escape-Pflicht außerhalb Code:** `_ * [ ] ( ) ~ \` > # + - = | { } . !` mit `\` escapen. Innerhalb `` ` `` und ``` ``` ``` nur `\` und `` ` ``.

**Beispiele:** Punkt am Satzende → `\.` · „Kadi-v2" → `Kadi\-v2` ODER `` `Kadi-v2` `` · Version „1.5.2" → `1\.5\.2` ODER `` `1.5.2` `` · Klammern → `\(text\)`

**Emojis bleiben** — kein Escape: ✓ ⚠️ ❌ 🔴 🟢 🟠 🟡

**Test bei Unsicherheit:** Erst kleine Test-Nachricht mit problematischen Zeichen. Telegram lehnt MarkdownV2 mit Escape-Fehler komplett ab — sichtbar am `reply`-Tool-Fehler oder literal `\`.

**Warum:** Kais liest auf 5"-Display, Bold/Code/Pre sind die einzigen Anker die er zuverlässig erkennt.

**Verwandt:** `feedback_telegram_format.md` (Memory mit Detail-Spec), archivierte LRN-20260506-004 (superseded).

### LRN-20260508-002 — Active Memory bei Telegram-Inbound
`comm.active_memory_pre_reply` · V5 Sprint 2 · Bei jedem signifikanten Telegram-Inbound (Frage, Auftrag, neue Information) **vor** der Reply: `bash /root/aria/scripts/aria-active-memory.sh "<inbound text>"` aufrufen. Output liefert top-3 Memory-Hits + Brain-Hits, max 6 KB, 2 s Timeout.

**Nicht aufrufen** für: Reaktions-Trigger („A", „1", „ok", reine Bestätigungen), Voice-Memo-Re-Transkription, Skill-Skript-Outputs.

**Warum**: Memory-Recall war reaktiv. Active Memory injiziert vor der Antwort die richtigen Pattern. Trefferquote im Test ≥66%.

### LRN-20260508-003 — Sandbox-Pattern für riskante Bash-Calls
`infra.sandbox_for_risky_bash` · V5 Sprint 5 · Bei riskanten Bash-Operationen (`curl|bash`-Installer, fremde npm packages, ungetestete Skripte): vor Host-Execution `aria-sandbox-run.sh "<cmd>"` aufrufen.

**Default**: alpine:latest, network=none, readonly fs, tmpfs /tmp + /home/sandbox, user 1000, 60 s timeout, --rm.

**Sandbox-Use für:** `npm install <unbekannt>`, `curl -fsSL https://... | bash`, Test-Run von fremden Tools (ruflo/openclaw/hermes), probably-safe Tools die noch nicht bekannt sind.

**NICHT sandboxed** für: bekannte system tools (`git`, `apt`, `vim`, `python3`-Skripte aus dem eigenen Repo, `bash` mit committeten Skripten).

**Limitation**: Default no-net heißt npm install/curl funktioniert nicht. Mit `--net` flag aktivieren wenn nötig.

Quelle: ruflo-Episode (08.05.2026 21:22) hätte in Container weniger Schaden auf Host gemacht. OpenClaw-Pattern.

### LRN-20260510-001 — BIG vs SMALL Eingangs-Gate für nicht-triviale Tasks
`work.big_small_classifier` · Adaptiert aus Garry-Tan-Senior-Engineer-Prompt (10.05.2026).

Bei jedem neuen nicht-trivialen Task **als erstes** klassifizieren:

- **BIG change** (System-weite Implikation, mehrere Files, neue Architektur, Schema-Bruch, Distributions-Patch): 4-Section-Sweep nutzen (Architecture → Code → Tests → Performance) mit For-Each-Issue-Template (Problem · Why · 2-3 Options · Effort/Risk/Impact/Maintenance · Recommendation). Top 3-4 Issues pro Section. Pause-Approval nach jeder Section *außer* Kais sagt „Go alle Phasen".
- **SMALL change** (lokal, eindeutig, eine Komponente, reversibel): 1 fokussierte Frage pro Section, knapp halten, schnell durch.
- Falls unklar: BIG annehmen (defensiv).

**Triviale Tasks** (Typo-Fix, Daily-Log, Memory-Update, einzelner Read) sind weder BIG noch SMALL — durchziehen ohne Klassifikation.

**Tooling**: `senior-review` Skill in `/root/.claude/skills/senior-review/` codiert das Framework. Triggert via `/senior-review` oder „Architecture-Review", „Senior-Engineer-Review".

**Engineering-Principles** (jeder Code-Task, in `ENGINEERING.md`):
1. DRY · 2. Well-tested · 3. Engineered enough (nicht fragile, nicht over-engineered) · 4. Correctness und Edge Cases > Tempo · 5. Explicit > clever

**Limitation**: Kais hat „Go alle Phasen" gesagt um Approval-Gates zu skippen (USER.md Widerspruch). Section-Pause ist *opt-in* — Default ist BIG-Sweep mit Pausen, Kais kann ausschalten.

Verwandt: `senior-review` Skill, `ENGINEERING.md`, SELF-IMPROVEMENT "Sparring vor Implementation".

### LRN-20260512-001 — .env-Änderungen brauchen Service-Restart
`infra.systemd_env_requires_restart` · 12.05.2026 · Aria zeigte 401 „Please run /login" obwohl `/root/aria/.env` einen validen `ANTHROPIC_API_KEY` enthielt. Ursache: systemd sourced `.env` nur beim Service-Start, der laufende Aria-Prozess hatte noch den alten (revoked) Key im RAM. Edit war 41 Min nach Service-Start.

**Regel:** Nach JEDER Änderung an `/root/aria/.env`, `/root/aria/scripts/.env.aria` oder `/root/.env` → `systemctl restart aria.service`. Sonst wirkt der Edit nicht.

**Diagnose:** `diff <(tr '\0' '\n' < /proc/$(pgrep -f '^claude --channels' | head -1)/environ | grep ^KEY=) <(grep ^KEY= /root/aria/.env)` — wenn unterschiedlich → Restart nötig.

**Verwandt:** Wenn `ANTHROPIC_API_KEY` in env steht, ignoriert Claude Code den OAuth-Max-Plan-Login. Default sollte sein: kein API-Key in `.env` → OAuth nutzen (gratis, SOUL „Max Plan bevorzugen").

---

## Allgemeine Regeln (kein LRN-Bezug)

### Zeitschätzungen
Immer zwei Horizonte: Grundfunktion (X Min) vs. Production-Ready (X Wochen). Nie „2–4 Wochen" für etwas das in Minuten steht.

### Öffentlicher Bot-Link
Nie Features mit Kosten/Sicherheitsrisiken ohne explizite Freigabe live stellen. Auch mit `allowedUsers`: erst fragen, dann bauen.

### V5-Anpassung 2026-05-08
- `aria-heartbeat.service` deaktiviert (Skript fehlte) · `mcp.json` 3 broken Pfade entfernt · Brain-Schema gekürzt auf 7 reale Folders · `MEMORIES.md` zu Pointer-File · HOOKS.md angelegt · Bootstrap-Limits 12k/80k im Hook · `aria-memory-curator.sh` neu (weekly Sonntag 03:30) · `aria-user-update.sh` neu (weekly Sonntag 04:00) · `aria-active-memory.sh` neu (Pre-Reply Helper)

## Archive

Historische Infra-LRNs (Fix gebacken oder als Behavioral Rule promoted): siehe `CORRECTIONS.archive/2026-Q2-historical-infra.md`.

Konkret ausgelagert (Stand 11.05.2026): LRN-20260331-004, 20260401-001/002/003, 20260402-001/002/003/004/005/006, 20260403-001/002/003/004, 20260406-002/003, 20260413-001, 20260420-001, 20260506-004 (SUPERSEDED).