Orkestrering: AI kun ved oppretting, eventually-modus for Claude Code

Fundamentalt restrukturert:
- AI genererer script ved oppretting, ikke ved kjøring
- Vaktmesteren validerer script før lagring (verktøy finnes? variabler ok?)
- Systemprompt bygges automatisk fra cli_tool-noder i PG
- Kjøring er alltid deterministisk script, ingen AI
- Feil → work_item, ikke AI-eskalering
- "Eventually"-modus: forespørsel lagres, Claude Code (betalt)
  genererer script i neste sesjon med Opus — ingen API-kostnad,
  bedre kvalitet, ingen hastverk

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/concepts/orkestrering.md

@@ -79,57 +79,124 @@ Enkelt nok til å parse med en liten Rust-parser i vaktmesteren.
 Deterministisk, gratis, raskt. **De fleste produksjons-
 orkestreringer vil være på dette nivået.**
 
-### Nivå 2: Fritekst med AI-tolkning
+### Nivå 2: AI-assistert oppretting
 
-Naturlig språk som boten tolker og utfører steg for steg
+Brukeren beskriver hva de vil i naturlig språk. AI genererer
-med function calling. For orkestreringer der stegene ikke
+et deklarativt script (nivå 1) som vaktmesteren validerer.
-er helt forutsigbare.
+**AI brukes ved oppretting, ikke ved kjøring.**
 
 ```
-Når en innspilling i en samling med podcast-trait avsluttes:
+Bruker: "Gjør episoden klar for publisering"
 
-1. Transkriber lydfilen med stor modell
+  → synops-ai genererer script-forslag:
-2. Generer oppsummering
-3. Foreslå kapitler basert på transkripsjonen
-4. Generer show notes
-5. Oppdater RSS-feed
 
-Hvis transkribering feiler, prøv igjen med medium modell.
+    NÅR innspilling.avsluttet
-Hvis RSS feiler, opprett en oppgave.
+    HVIS samling.har_trait("podcast")
+    1. synops-transcribe --cas-hash {event.cas_hash} --model large
+       VED_FEIL: synops-transcribe --cas-hash {event.cas_hash} --model medium
+    2. synops-summarize --communication-id {event.communication_id}
+    3. synops-rss --collection-id {event.collection_id}
+    VED_FEIL: work_item "Pipeline feilet" --tag bug
+
+  → Vaktmesteren validerer:
+    ✓ Alle verktøy finnes
+    ✓ Alle variabler er gyldige
+    ✓ Syntaks er korrekt
+
+  → Bruker godkjenner eller justerer
+  → Lagres som orchestration-node (nivå 1)
 ```
 
-Boten mapper "transkriber lydfilen" → `synops-transcribe`,
+Etter oppretting kjører scriptet uten AI — deterministisk,
-"oppsummer" → `synops-summarize`, osv. Krever LLM-kall
+gratis, raskt. AI-kostnaden er én gang, ved oppretting.
-per kjøring (Haiku er nok for de fleste).
 
 ### Nivå 3: Drømmemodus
 
 Brukeren skriver hva de *ønsker*, uten å vite hvilke verktøy
-som finnes. Boten prøver, og mangler som oppdages blir
+som finnes. AI prøver å generere et script, og mangler
-feature requests.
+som oppdages blir feature requests.
 
 ```
-Gjør episoden klar for publisering. Lag en lydfil med
+Bruker: "Lag en lydfil med sammendrag og send til deltakerne"
-sammendrag og send den til alle deltakere.
+
+  → synops-ai genererer:
+    1. synops-summarize --communication-id {event.communication_id}
+    2. synops-tts ???  ← finnes ikke
+
+  → Vaktmesteren validerer:
+    ✗ synops-tts finnes ikke
+
+  → Tilbake til bruker:
+    "Scriptet refererer til synops-tts som ikke finnes.
+     Jeg oppretter en forespørsel om TTS-verktøy."
+    → work_item "TTS for møteoppsummeringer" --tag feature
+    → Delvis script lagres med synops-tts markert som manglende
 ```
 
-Boten sjekker tilgjengelige verktøy, gjør det den kan,
+### Systemprompt for script-generering
-og oppretter work_items for det som mangler.
+
+AI-modellen trenger kontekst for å generere gode scripts.
+`synops-orchestrate --generate-system-prompt` bygger dette
+automatisk fra PG:
+
+```
+Du er en orkestreringsplanlegger for Synops.
+
+TILGJENGELIGE VERKTØY:
+- synops-transcribe: Whisper-transkribering
+  Bruk: --cas-hash <hash> --model <model>
+- synops-summarize: AI-oppsummering
+  Bruk: --communication-id <uuid>
+- synops-rss: RSS-generering
+  Bruk: --collection-id <uuid>
+[... hentet fra cli_tool-noder i PG]
+
+SCRIPT-GRAMMATIKK:
+  NÅR <event> [HVIS <betingelse>]
+  <N>. <tool> <args...>
+  VED_FEIL: <tool> <args...> | work_item <title> [--tag <tag>]
+  Variabler: {event.<felt>}, {input.<felt>}
+
+EKSEMPLER:
+[... hentet fra eksisterende orchestration-noder]
+
+Svar KUN med et gyldig orkestreringscript.
+```
+
+Systemprompt oppdateres automatisk når nye verktøy legges til.
+Fungerer med alle modeller — Claude, Llama, Mixtral, Grok.
+
+### Tre-stegs flyten
+
+```
+1. OPPRETTING (AI, én gang)
+   Bruker beskriver → synops-ai genererer script
+   → vaktmester validerer → bruker godkjenner → lagres
+
+2. KJØRING (ingen AI, hver gang)
+   Trigger → vaktmester parser script → utfører CLI-kall
+   → logger resultat
+
+3. FEILHÅNDTERING (AI, sjelden)
+   VED_FEIL feiler → eskalér til synops-ai
+   → foreslå fix eller opprett work_item
+```
+
+AI-kostnad er nesten null i drift.
 
 ### Naturlig progresjon
 
 ```
 Drømmemodus  → Bruker beskriver ønsket resultat
-  ↓ AI foreslår
+  ↓ AI genererer script-forslag
-Fritekst     → Bruker justerer steg i naturlig språk
+Script       → Vaktmester validerer, bruker godkjenner
-  ↓ AI foreslår kompilering etter N kjøringer
+  ↓ Kjører uten AI
-Script       → Deklarative CLI-kall, ingen AI
+Produksjon   → Deterministisk, gratis, raskt
-  ↓ manuelt
+  ↓ Hvis mønster gjentas
 Kode         → Eget CLI-verktøy (synops-<verb>)
 ```
 
-Hvert nivå kan fryses til nivået under. AI foreslår
+AI ved oppretting. Ingen AI ved kjøring. Script kan alltid
-kompilering, bruker godkjenner. Scriptet kan alltid
 redigeres manuelt.
 
 ## 5. Strukturert trigger
@@ -185,38 +252,50 @@ Trigger aktiveres
 
 Ingen LLM. Deterministisk. Raskt.
 
-### Bot-modus (nivå 2)
+### Feilhåndtering ved kjøring
 
-```
+Alle orkestreringer kjører som script (nivå 1). Ved feil:
-Trigger aktiveres
-  → Vaktmesteren finner matchende orchestration-node
-  → Sender til bot med function calling:
-    - Trigger-kontekst (hvilken node, hvilken event)
-    - Instruksjonene fra orchestration.content
-    - Tilgjengelige verktøy (cli_tool-noder)
-  → Boten utfører steg for steg
-  → Logger hvert steg i orchestration_log
-  → Ved feil: resonnerer og prøver alternativ
-```
-
-### Drømmemodus (nivå 3)
-
-Som bot-modus, men med høyere intelligens (Sonnet+) og
-instruks om å opprette work_items for manglende verktøy.
-
-### Auto-eskalering
-
-Script-modus faller tilbake til bot-modus ved uventet feil:
 
 ```
 Script kjører steg 2
   → synops-summarize returnerer exit 1
-  → VED_FEIL er definert → prøv alternativ
+  → VED_FEIL definert? → kjør alternativ
-  → Alternativ feiler også
+  → Alternativ feiler også?
-  → Eskalér til bot-modus for dette steget
+    → Opprett work_item med feilbeskrivelse
-  → Boten resonnerer om feilen og prøver å løse det
+    → Logger i orchestration_log
+    → Stopp orkestreringen
 ```
 
+Ingen AI-eskalering ved kjøring. Feil håndteres av scriptet
+(VED_FEIL) eller blir work_items for manuell/AI-assistert
+oppfølging.
+
+### Asynkron modus: "eventually"
+
+Brukeren kan godta at et svar eller script-generering kommer
+*etterhvert* i stedet for umiddelbart:
+
+```
+Bruker: "Lag en orkestrering for podcast-pipeline"
+  → [Nå] [Eventually]
+
+"Eventually":
+  → Forespørselen lagres som work_item med tag "script_request"
+  → Neste Claude Code-sesjon (task runner) plukker den opp
+  → Genererer script med Opus (full verktøy-tilgang, fillesing)
+  → Scriptet valideres og lagres
+  → Bruker varsles: "Orkestreringen din er klar"
+```
+
+Fordeler:
+- **Ingen API-kostnad** — Claude Code (betalt) gjør jobben
+- **Bedre kvalitet** — Opus med full kontekst, ikke en lettvekts API-modell
+- **Ingen hastverk** — script-generering trenger ikke skje i sanntid
+
+Dette gjelder også feilhåndtering: et feilet VED_FEIL-steg
+blir en work_item som Claude Code løser i neste sesjon —
+reparerer scriptet, legger til manglende verktøy, osv.
+
 ## 7. Koblinger mellom orkestreringer
 
 Orkestreringer er noder med edges: