mission-control-v2/docs/AUFTRAGSBUCH.md

# Auftragsbuch — die Vorschlags-Inbox der Box

Das Auftragsbuch ist das Mensch-Gate des propose-only-Kreislaufs als Klick statt
Git-Handarbeit: alles, was die Box von allein baut oder sich ausdenkt, landet hier
als Karte — du entscheidest mit **Annehmen** oder **Ablehnen**.

## Die Ideen-Queue davor (natives Hermes-Kanban, seit 10.07.2026)

Vor dem Auftragsbuch liegt DIE eine Ideen-Queue: das native Hermes-Kanban
(`hermes kanban`, SQLite-Board, Dispatcher läuft im Gateway). Der Weg einer Idee:

1. **Idee rein — Tür egal:** Eingabefeld im Auftragsbuch-Tab (`POST /api/ideen`),
   Telegram/Desktop (natives Tool `kanban_create`, Regel in SOUL.md) oder Lucys
   Sprech-Leitung (`idee_notieren` in `mcp/mcp_voice.py`). Alles landet als
   `triage`-Aufgabe auf demselben Board.
2. **Die Box arbeitet sie aus:** der Kanban-Specifier macht aus der rohen Idee
   einen sauberen Auftrag und wählt das Worker-Profil (Routing über die
   Profil-Beschreibungen: Code → `werkstatt` [Qwen3-Coder-Next, Leitplanken in
   `deploy/werkstatt-SOUL.md`], Doku/Analyse → `default`).
3. **Der Worker baut** im isolierten Workspace; Code-Ergebnisse pusht er als
   Vorschlags-Branch auf Gitea — der hier als Karte erscheint. **Das Gate bleibt
   dein Klick.**

**Die Queue füttert sich auch selbst — Idle-Radar (S4 „Zündung", 12.07.2026):** ein
nächtlicher Hermes-Cron (03:45, `deploy/idle-radar-feed.sh`) destilliert aus den
Journal-Fehlermustern der letzten 24 h und der jüngsten Traum-Notiz bis zu **2 belegte**
Wartungs-Kandidaten und legt sie als rohe Ideen (`triage`, `created_by=idle-radar`) auf
dasselbe Board. Leitplanken: jedes Beleg-Zitat wird **mechanisch** gegen das Material
geprüft (erfundene Belege fliegen raus — reproduziert-oder-abgelehnt), **Stau-Bremse**
(ab 4 offenen Queue-Aufgaben oder 3 offenen Karten legt er nichts nach), dreifacher
Dedup (State-Datei `~/.hermes/state/idle-radar-gemeldet.txt`, Board-Abgleich inklusive
archivierter = verworfener Ideen, `--idempotency-key`), Security/Config/Updates tabu.
Der Radar legt nur Ideen an — gebaut wird über denselben Kreislauf, dein Klick bleibt
das Gate.

Die Queue-Sicht im Tab (Status, offene Ideen) kommt aus `hermes kanban list --json`
(`backend/services/ideen.py`); die Morgenlage bekommt `kanban stats` als
Beweismaterial. Entscheid nativ-vs-Eigenbau (Hermes-first): Probe 10.07.2026 —
Dispatcher, Specifier, Profil-Modellwahl und Artefakt-Tracking sind nativ E2E
bewiesen; ein Eigenbau hätte all das nur nachgebaut.

## Woher die Karten kommen

- **Fertige Patches** — Branches auf Gitea (`wartung/*`, `orchestrator/*`, `doku/*`,
  `feature/*`), wie die Werkstatt und der Orchestrator sie hinterlassen. Die Karte
  zeigt Commit-Botschaft, geänderte Dateien und den vollen Diff. Seit S3
  (lucy-pipeline) aus **zwei Repos**: `mission-control-v2` (Box-Stack) und `lucy`
  (Desktop-App, rosa „Lucy"-Badge auf der Karte).
- **Skill-Kandidaten** — Ideen des nächtlichen Traum-Crons aus dem Wissens-Vault
  (`~/wissens-vault/skill-kandidaten/`). „Beauftragen" schickt sie als Auftrag an
  die Werkstatt (Orchestrator-Skill); das Ergebnis kommt als neuer Patch zurück.

## Was „Annehmen" bei einem Patch macht (deploy/auftrag-annehmen.sh)

1. Merge des Branches in einem **isolierten Worktree** (Live-Checkout bleibt unberührt).
   Kollidiert der Merge, weil main weitergelaufen ist, versucht der Runner **automatisch
   einen Rebase** des Branches auf main (Selbstheilung für veraltete Vorschläge) — erst
   wenn auch der kollidiert, fällt die Karte mit ehrlicher Meldung durch.
2. `py_compile`-Gate über die geänderten Python-Dateien.
3. Push nach `main` auf Gitea (mit Retry).
4. Deploy (als /tmp-Kopie von deploy.sh — Selbst-Reset-Falle) — die Zentrale
   startet dabei kurz neu.
5. Health-Check mit Geduld. **Rot ⇒ automatischer Revert des Merges + Redeploy +
   Alarm.** Grün ⇒ Branch wird aufgeräumt, Meldung an Telegram + Chronik.

Der Lauf ist eine eigene systemd-Unit (detached) — er überlebt den Neustart des
Backends, das ihn gestartet hat. Fortschritt steht live auf der Karte
(`/srv/models/mc2-auftragsbuch.json`).

**Kaputt aufgesetzte Branches** (Worker machte `git init`/Shallow statt zu klonen → kein
gemeinsamer Ursprung mit main, „refusing to merge unrelated histories") erkennt das
Auftragsbuch an der Quelle: rote Markierung „kein gemeinsamer Ursprung", der
Annehmen-Knopf fehlt (Annehmen wäre ein garantierter Fehllauf), API und Runner halten
zusätzlich dicht. Ebenso markiert: „Diff leer — bringt nichts" (Branch würde gegenüber
main nichts ändern). In beiden Fällen: **ablehnen mit Grund** und die Idee frisch in die
Queue geben; die Prävention (voll klonen, merge-base-Selbstcheck, fetch+rebase vor dem
Push) steht in der werkstatt-SOUL.

## Was „Annehmen" bei einer LUCY-Karte macht (deploy/lucy-annahme.sh)

Lucy (Electron) lebt auf dem Windows-PC; ihr `dist` liegt nicht im Repo — die Box
kann sie nicht bauen. Der Lucy-Runner spannt darum den PC ein (PC-Executor :7777,
Token aus `~/.hermes/config.yaml`):

1. **Vorprüfung am PC, VOR dem Merge:** Executor erreichbar? Arbeitskopie
   `F:\Coding Stuff\lucy` auf `main` und sauber? Läuft Lucy gerade? Scheitert etwas,
   bricht der Lauf ab, ohne irgendetwas zu verändern — der PC muss an sein.
2. Merge des Branches im isolierten Worktree von `~/lucy` → Push nach `main`.
3. Der PC zieht `main` (ff-only) und startet **detached**
   `deploy/lucy-annahme.ps1` (liegt im Lucy-Repo): ggf. `npm ci` (nur wenn sich
   das Lockfile geändert hat) → `tsc --noEmit`-Gate → dist-Backup → `npm run dist`
   → Lucy-Neustart **nur, wenn sie vorher lief** (User-Entscheid: Lucy startet
   nur, wenn der Commander sie will) → Stimme-Health (`:8130`).
4. Die Box pollt die PC-Status-Datei (`.lucy-annahme.json`) und spiegelt den
   Fortschritt live auf die Karte. **Rot ⇒ Merge wird automatisch revertiert**,
   der PC stellt dist aus dem Backup wieder her — die laufende Lucy bleibt die
   alte. Grün ⇒ Branch aufgeräumt, Meldung an Telegram + Chronik.

## Bagatellen ohne Klick (mc2-bagatell.timer, 04:10)

Einzige Ausnahme vom Klick-Gate (User-Entscheid 10.07.2026, bewusst eng geschnitten):
`deploy/bagatell-annahme.sh` spielt nachts Vorschlags-Branches ein, deren Diff
**ausschließlich `.md`-Dateien anlegt oder ändert** — keine Code-Zeile, keine
Löschungen, keine Renames, keine Skripte. Der Weg ist derselbe Annahme-Runner wie
beim Klick (Merge → Gate → Deploy → Health → Auto-Revert), maximal 2 pro Nacht und
nur Branches ohne vorherige Fehl-Läufe. Fangnetz: Nacht-Sicherung 03:30 liegt davor,
jede Annahme steht in Chronik + Telegram, die Morgenlage 04:30 berichtet. Die Klasse
erweitert nur der Commander, nie das Skript.

## „Lucy kennt sich" (12.07.2026): Selbstbild, Empfehlungs-Stempel, Lern-Gedächtnis

- **Selbst-Inventur (Cron 03:35, `deploy/selbst-inventur.sh`):** erhebt den
  **Selbst-Steckbrief** der Box live aus der Realität (Versionen, Dienste, Modelle,
  Crons, Queue, Karten → `~/.hermes/state/selbst-steckbrief.md`) und **bemerkt selbst,
  wenn sich etwas ändert** (Diff gegen gestern → stille Chronik-Karte + kurze
  Telegram-Zeile; keine Änderung = still). Der Steckbrief ist das „was es schon
  gibt"-Gedächtnis: Idle-Radar-Analyst und Werkstatt (Realitäts-Check-Regel) lesen ihn,
  bevor sie vorschlagen oder bauen.
- **Karten-Gutachter (Cron 04:00, `deploy/karten-gutachter.sh`):** stempelt jede neue
  Karte mit **„Empfehlung: Annehmen/Ablehnen/Unklar" + einem ehrlichen Satz** —
  geprüft werden Redundanz (existiert das laut Steckbrief schon?), Risiko und Nutzen.
  Der Stempel ist eine Meinung, kein Gate; ein nachgeschobener Commit macht ihn
  ungültig (wird neu gestempelt). Ablage `/srv/models/mc2-karten-gutachten.json`.
- **Ablehnen mit Grund:** Beim Ablehnen einer Karte kannst du der Box in einem Satz
  sagen, *warum* („gibt es schon", „will ich nicht"). Der Grund landet in
  `/srv/models/mc2-ablehnungen.jsonl` und wird Radar/Analysten als „NIE wieder
  vorschlagen"-Material vorgelegt — dein Klick wird damit zum Lehrer, nicht nur zum Tor.
- **Radar-Treffer → Queue:** Meldet der wöchentliche Release-Radar einen echten Treffer,
  legt er zusätzlich EINE rohe Idee in die Ideen-Queue („Probe bauen?", idempotent je
  Release-Tag) — der Blick nach draußen füttert damit denselben Kreislauf.

## Curator Auto-Archivierung (Cron `0 3 * * *` — täglich um 03:00)

**Zweck:** Automatische Archivierung inaktiver Skills nach 14 Tagen ohne Nutzung.

**Skripte:**
- `~/.hermes/scripts/curator-archive-watchdog.sh` — Cron-Einstieg, ruft das Python-Skript auf.
- `~/.hermes/scripts/curator_archive_logic.py` — Hauptlogik. Liest `.curator_state` und `.usage.json` aus `~/.hermes/skills/`, prüft auf Inaktivität (>14 Tage seit letztem Gebrauch), überspringt gepinnte und exkludierte Skills, verschiebt Skills nach `.archive/<Kategorie>/`.
- `~/.hermes/scripts/curator-idle-watchdog.sh` — Zusätzlicher Watchdog (Sonntag 00:00, Cron `0 0 * * 0`): prüft, ob der Curator selbst ≥14 Tage idle ist und triggert ggf. eine Reaktivierung.

**Konfiguration** (`~/.hermes/skills/.curator_state`):
- `archivierung.enabled: false` — Archivierung muss explizit aktiviert werden.
- `archivierung.threshold_days: 14` — Tage ohne Nutzung bis zur Archivierung.
- `archivierung.excluded_skills: [...]` — Liste der nie zu archivierenden Skills.
- `archivierung.last_archive_run_at` — Zeitstempel des letzten Durchlaufs.

**Ablauf im Durchlauf:**
1. Prüft, ob Archivierung aktiviert ist.
2. Läuft alle Skills durch `.usage.json`.
3. Überspringt: gepinnte Skills, exkludierte Skills, aktive Skills (<14 Tage).
4. Archiviert: State auf "archived" setzen, Verzeichnis nach `.archive/<Kategorie>/` verschieben, Usage-Datei aktualisieren.
5. Protokolliert in `~/.hermes/logs/curator/archive-<Datum>.log`.

**Sicherheit:**
- Archivierung standardmäßig deaktiviert — passiert nie ohne explizite Freigabe.
- Gepinnte und exkludierte Skills werden nie berührt.
- Archivierung ist reversibel: Skills können manuell aus `.archive/` zurückverschoben werden.

## Leitplanken

- Propose-only bleibt: **keine Code-Zeile geht ohne Klick live.** Das Gate ist dieses
  Buch; einzige Ausnahme sind die eng geschnittenen Doku-Bagatellen (oben).
- „Frontend ohne Build"-Warnung (nur mc2): enthält ein Branch `frontend/src` ohne
  frisches `frontend/dist`, bleibt die Oberfläche nach dem Annehmen alt, bis am PC
  gebaut wird. Lucy-Karten brauchen die Warnung nicht — dort baut IMMER der PC.
- Ablehnen löscht nur den Remote-Branch; die Historie auf Gitea bleibt.

Diese Datei kam übrigens selbst über das Auftragsbuch ins Repo — als erste echte
End-to-End-Annahme (Probe-Branch `wartung/annahme-probe`, 08.07.2026).