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-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).
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`).

## 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.

## 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).