Modul 1: Premises & Layer
Kurs: iio-operator-basics | Modul: 1 von 4 | Dauer: ~45 minWas ist IIO?
IIO steht für Immutable Infrastructure Organization — ein Framework für deterministische, nachvollziehbare und fail-closed Governance von Organisationen und AI-Agenten. Einfach erklärt: IIO ist ein System, das sicherstellt, dass jede Änderung — egal ob von einem Menschen oder einem AI-Agenten — kontrolliert, dokumentiert und rückgängig machbar ist.Die drei Kernkonzepte
1. Seed → Node → Tenant
Wichtig:CODEIIO Seed (iio/) └── Universelle Vorlage — immutabel, Referenz für alles │ └── projiziert auf → Node (z.B. intelego/) └── Konkrete Organisation mit eigenem Kontext │ └── projiziert auf → Tenants (bilz/, pm24/, ...) └── Mandanten/Kunden
- Der Seed wird nicht direkt verändert — er ist die stabile Referenz
- Nodes und Tenants projizieren vom Seed — sie erben Governance-Regeln
- Änderungen fließen: Seed → Node → Tenant (nie umgekehrt ohne Review)
2. Premises (Prämissen)
Premises sind verbindliche Aussagen darüber, wie IIO funktioniert. Sie sind der "Bauplan" des Systems — 102 Prämissen in 8 Schichten.
Beispiele:
P-CORE-001— Jede Aktion hinterlässt ein Evidence-FileP-SAFE-001— Fail-closed: bei Unsicherheit blockieren, nicht stillschweigend weitermachenP-PROJ-001— Keine Projektion ohne Manifest, Profil und lokalen Kontext
Die Prämissen liegen in: iio/specs/governance/layer-premises-catalog.yaml
3. Die 8 Layer
IIO organisiert alles in 8 Schichten:
| Layer | Name | Was | Beispiel |
|---|---|---|---|
| 1 | Ontology Core | Grundbegriffe, Invarianten | Was ist ein "Actor"? |
| 2 | Architecture | Schichtentrennung | Warum darf Layer 3 nicht Layer 5 kennen? |
| 3 | Projection | Seed→Node-Regeln | Wie projiziert man korrekt? |
| 4 | Safety & Review | Fail-closed, HITL | Wann braucht es einen Menschen? |
| 5 | Determinism | Gleicher Input → gleicher Output | Warum keine Zufälligkeit? |
| 6 | Transaction & State | Kontrollierter Zustandswechsel | Evidence vor jeder Änderung |
| 7 | Learning & Feedback | Was geht in den Seed zurück? | Nur mit explizitem Review |
| 8 | Language & Publishing | Sprachtrennung | AGT/DE/EN strikt getrennt |
Warum Premises statt Regeln?
Regeln sagen: "Du darfst X nicht." Premises sagen: "Das System funktioniert so, weil Y."Der Unterschied: Premises erklären das Warum. Wer das Warum versteht, macht keine Ausnahmen — weil er sieht, warum Ausnahmen das System beschädigen.
Fail-Closed — das wichtigste Prinzip
Wenn IIO unsicher ist, blockiert es. Es macht nicht stillschweigend weiter.
Deine Rolle als Operator: Du bist der Mensch, der den Stopp überprüft und entscheidet, ob weitergemacht werden kann.CODEBeispiel: Validator findet einen Fehler → Normales System: gibt Warnung, macht weiter → IIO: stoppt, schreibt Evidence, wartet auf menschliche Entscheidung Warum? Stille Fehler akkumulieren sich. Ein bekannter, dokumentierter Stopp ist besser als unbekannte Konsequenzen eines Weitermachens.
Evidence-Culture
Jede Aktion in IIO hinterlässt ein Evidence-File — eine maschinenlesbare und menschenlesbare Aufzeichnung was getan wurde, von wem, wann, mit welchem Ergebnis.
Warum?CODEiio/specs/transformation/evidence/ full-stack-audit-20260503T120000Z.md ← Audit-Ergebnis training-evidence-workspace-owner-zolo-20260503.md ← Schulungsnachweis
- Jede Entscheidung ist nachvollziehbar
- Kein "ich glaube, das haben wir so gemacht"
- ISO 42001 und EU AI Act verlangen diese Nachvollziehbarkeit
Wissenscheck — Modul 1
Bevor du weitergehst, beantworte diese Fragen für dich selbst:
- Was ist der Unterschied zwischen Seed, Node und Tenant?
- Warum ist der Seed immutabel?
- Was bedeutet "fail-closed" in der Praxis?
- Warum hinterlässt jede Aktion ein Evidence-File?
- Was ist der Unterschied zwischen einer Prämisse und einer Regel?
3 schnelle Fragen — kein Druck, nur zum Festigen.
- Ein Deployment das lief obwohl Tests noch liefen
- Eine Entscheidung die ohne vollständige Information getroffen wurde
- Eine Änderung die rückgängig gemacht werden musste
Modul 2: Session-Workflow
Kurs: iio-operator-basics | Modul: 2 von 4 | Dauer: ~45 minDer verbindliche Session-Ablauf
Jede Arbeit in IIO — ob Mensch oder AI-Agent — folgt demselben Ablauf:
Absolutes Verbot: Arbeit ohneCODESESSION START ↓ bash iio/specs/scripts/session-start.sh ↓ [Prüft: git-Status, Drifts, Queue, Processing-State, Wiring, Parity] ↓ Ergebnis: GO oder NO-GO ↓ Bei GO: Arbeit beginnen ↓ [... Arbeit erledigen ...] ↓ SESSION CLOSEOUT ↓ bash iio/specs/scripts/session-closeout.sh ↓ [Prüft: uncommitted, unpushed, full-stack-audit, Timestamps, Parity] ↓ Evidence-File erstellt
session-start.sh. Immer. Kein Kontext-Wissen
aus vorherigen Sessions annehmen — immer frisch lesen.
session-start.sh — Was wird geprüft?
BASHbash iio/specs/scripts/session-start.sh
Das Script prüft automatisch:
| Prüfung | Was | Warum |
|---|---|---|
| Git-Status | Uncommitted changes? | Kein ungesicherter Stand |
| Drift-Report | Bekannte Drifts offen? | Keine blinden Flecken |
| Queue | Offene Work Items? | Prioritäten kennen |
| Processing-State | In welcher Phase? | Kontext herstellen |
| Wiring-Check | Alle Skills verdrahtet? | Keine Broken-Links |
| Parity | YAML ↔ JS Konsistenz | Kein Zustandskonflikt |
Was tun bei NO-GO?
- Fehlermeldung lesen — was genau ist das Problem?
- Häufige Ursachen:
git add . && git commit -m "..."
- Offener Drift → drift-report.yaml prüfen, Drift dokumentieren oder beheben
- Blocker-Gate offen → Gate-Owner informieren, Approval einholen
- Parity-Konflikt → sync-public-state.sh ausführen
- session-start.sh erneut ausführen
- Erst bei GO weiterarbeiten
Während der Arbeit — die drei absoluten Verbote
Verbot 1: Kein Direktfix
Warum: Direktänderungen auf dem Server sind nicht im Git, nicht nachvollziehbar, kein Evidence, kein Review möglich.CODEFALSCH: ssh server "sed -i 's/alt/neu/' /etc/config" RICHTIG: Lokal ändern → commit → push → IIO-Prozess
Verbot 2: Kein Scheinfix
Warum: Validator-Anpassungen um Fehler zu verstecken untergraben die gesamte Governance-Kette.CODEFALSCH: Validator schlägt an → Validator anpassen, damit er nicht mehr schlägt RICHTIG: Ursache finden → Ursache reparieren → Validator läuft sauber durch
Verbot 3: Kein Kontext-Wissen
Warum: Der System-Zustand ändert sich zwischen Sessions. Entscheidungen auf veralteten Annahmen können Schaden anrichten.CODEFALSCH: "Ich weiß noch aus letzter Session, dass..." RICHTIG: session-start.sh ausführen, System-Zustand lesen, dann entscheiden
session-closeout.sh — Was wird geprüft?
BASHbash iio/specs/scripts/session-closeout.sh
| Prüfung | Was |
|---|---|
| Uncommitted | Gibt es ungespeicherte Änderungen? |
| Unpushed | Wurde alles gepushed? |
| Full-Stack-Audit | Läuft die vollständige Validierungskette durch? |
| Timestamps | Sind alle Evidence-Files aktuell? |
| Parity | Stimmt YAML mit JS überein? |
Erst wenn session-closeout.sh durchläuft, ist eine Session offiziell beendet.
Der IIO-Prozess-Lookup — vor jeder Aktion
Bevor du etwas tust, frage:
Warum? Prozesse sind deterministische, nachvollziehbare Pfade. Ad-hoc-Aktionen hinterlassen kein Evidence und können nicht wiederholt werden.CODEGibt es einen IIO-Prozess für diese Aufgabe? JA → Prozess ausführen. Nicht abkürzen. NEIN → Erst Prozess in iio/base/ oder iio/specs/scripts/ ergänzen, dann ausführen.
Praktische Beispiele
Beispiel: Normaler Arbeitstag
BASH# Morgens bash iio/specs/scripts/session-start.sh # → GO # Arbeit erledigen # (Dateien bearbeiten, Scripts ausführen, etc.) # Änderungen committen git add . git commit -m "feat: ..." # Abends bash iio/specs/scripts/session-closeout.sh # → Session abgeschlossen, Evidence erstellt
Beispiel: Gate muss approved werden
BASHbash iio/specs/scripts/session-start.sh # → NO-GO: gate.platform-security-posture OPEN (blocker: true) # Gate prüfen cat intelego/specs/gate-status.yaml | grep -A5 "platform-security-posture" # Gate-Kriterien erfüllen (was fehlt?) bash iio/specs/scripts/check-gate-readiness.sh # Gate approven (wenn bereit) bash iio/specs/scripts/approve-hitl-gate.sh gate.platform-security-posture "[Workspace-Owner]" "Alle Kriterien erfüllt" # Erneut starten bash iio/specs/scripts/session-start.sh # → GO
Wissenscheck — Modul 2
- Was passiert, wenn
session-start.shNO-GO zurückgibt? - Warum darf man nicht direkt auf dem Server editieren?
- Was prüft
session-closeout.sh? - Was bedeutet "Prozess-Lookup-Pflicht"?
- Welches der drei Verbote verletzt folgende Aktion: "Letztes Mal hatte ich auch dieses Problem — ich mache einfach dasselbe wie damals."?
Kurz prüfen ob der Ablauf sitzt.
Es ist 18 Uhr. Ein Tippfehler in einer Konfigurationsdatei auf dem Server verursacht Probleme. Dein Kollege sagt: "Schnell per SSH drauf und ändern — dauert 30 Sekunden."
Modul 3: HITL-Gates
Kurs: iio-operator-basics | Modul: 3 von 4 | Dauer: ~45 minWas ist ein HITL-Gate?
HITL = Human-In-The-Loop.Ein HITL-Gate ist ein kontrollierter Haltepunkt im IIO-System. Automatisierung stoppt. Ein benannter Mensch prüft und entscheidet: GO oder NO-GO.
CODEAutomatisierter Prozess ↓ ┌─────────────────┐ │ HITL-GATE │ ← Hier stoppt alles │ Prüfe: ... │ │ Approver: [Owner] │ └─────────────────┘ ↓ (nur wenn GO) Nächster Schritt
Warum Gates? — Das Prinzip
Manche Entscheidungen sind zu kritisch für reine Automatisierung:
- Produktiv-Deployments
- Security-Änderungen
- Migrationsschritte
- Schulungsabschlüsse
Gates stellen sicher, dass immer ein Mensch die Verantwortung übernimmt bevor etwas Irreversibles passiert.
Gate-Status-Werte
| Status | Bedeutung |
|---|---|
OPEN | Noch nicht approved — blockiert (wenn blocker: true) |
APPROVED | Mensch hat explizit GO gegeben |
REJECTED | Mensch hat NO-GO gegeben (mit Begründung) |
DEFERRED | Bewusst verschoben (mit neuem Review-Datum) |
Wo leben die Gates?
Regeln:CODEiio/specs/governance/hitl-gate-definitions.yaml ← Alle Gate-Definitionen <node>/specs/gate-status.yaml ← Aktueller Gate-Status
- Kein Gate darf ohne Eintrag in
hitl-gate-definitions.yamlexistieren - Jedes APPROVED benötigt: Named Approver + Timestamp
- Blocker-Gates mit Status OPEN blockieren alle Automatisierung in ihrem Scope
Gate prüfen — Schritt für Schritt
1. Gate-Status anzeigen
BASH# Alle Gates auf einen Blick bash iio/specs/scripts/check-gate-readiness.sh # Spezifisches Gate grep -A10 "gate.manual-portal-deploy" intelego/specs/gate-status.yaml
2. Release-Kriterien prüfen
Jedes Gate hat Kriterien in hitl-gate-release-criteria.yaml. Prüfe, ob alle erfüllt sind:
BASHbash iio/specs/scripts/check-gate-readiness.sh [gate-id]
3. Entscheidung treffen
Als Approver:
- GO: Alle Kriterien erfüllt, Risiko akzeptiert → approve
- NO-GO: Kriterien nicht erfüllt, Risiko zu hoch → reject mit Begründung
- DEFER: Kriterien noch nicht prüfbar → defer mit Datum
4. Gate approven
BASHbash iio/specs/scripts/approve-hitl-gate.sh \ "gate.manual-portal-deploy-go-no-go" \ "[Workspace-Owner]" \ "Alle Validierungen PASS, Security-Check clean"
Das Script:
- Aktualisiert
gate-status.yaml(Status, Approver, Timestamp) - Schreibt Evidence-File
- Gibt Bestätigung aus
Gate-Rollen
Jedes Gate hat einen required_approver_role:
| Rolle | Welche Gates |
|---|---|
workspace-owner | Seed-Änderungen, Security, kritische Deployments, Schulungsabschlüsse |
risk-owner | Compliance-Gates, GDPR, AI-Governance |
node-operator | Node-spezifische Deployments, Tenant-Onboarding |
named-gate-owner | Spezifisch delegierte Gates |
Häufige Fehler bei Gates
Fehler 1: Gate approven ohne Kriterien zu prüfen
CODEFALSCH: Gate ist OPEN → einfach approve → fertig RICHTIG: Kriterien lesen → prüfen → evidenzbasiert entscheiden
Fehler 2: Blocker-Gate ignorieren
CODEFALSCH: "Das Gate ist offen aber ich mach trotzdem weiter" RICHTIG: Blocker-Gates stoppen alles in ihrem Scope — kein Umgehen
Fehler 3: Approve ohne Begründung
CODEFALSCH: approve-hitl-gate.sh "gate.xyz" "[Workspace-Owner]" "" RICHTIG: approve-hitl-gate.sh "gate.xyz" "[Workspace-Owner]" "Warum ist GO gerechtfertigt?"
Schulungs-Gates — dein erstes Gate
Nachdem du diesen Kurs abgeschlossen hast, wird das Gate training.iio-operator-basics-complete geöffnet.
Das ist dein erstes eigenes Gate-Approval — direkt angewendetes Wissen.
YAML# In hitl-gate-definitions.yaml: - id: "training.iio-operator-basics-complete" scope: "Operator training certification" description: | Controls certification for iio-operator-basics course completion. Requires assessment score ≥ 80% and workspace owner review. required_approver_role: "workspace-owner" blocker_by_phase: build: false integrate: true release: true
Eskalation bei Gate-Konflikten
Wenn du dir bei einem Gate unsicher bist:
- Nicht approven — lieber warten als falsch entscheiden
- Gate-Owner kontaktieren (aus
gate-ownership_ref) - In
drift-report.yamlals offenes Issue dokumentieren - Workspace Owner informieren
BASHbash iio/specs/scripts/escalate-gate-blocker.sh \ "gate.xyz" \ "Unsicher ob Kriterien erfüllt — brauche Review"
Wissenscheck — Modul 3
- Was ist der Unterschied zwischen einem OPEN und einem DEFERRED Gate?
- Darf man ein Gate approven, für das man nicht die erforderliche Rolle hat?
- Was passiert, wenn ein Blocker-Gate OPEN ist?
- Welche Pflichten hast du als Approver vor dem Approve?
- Was ist das korrekte Vorgehen wenn du dir bei einem Gate unsicher bist?
Kurzer Check — kein Druck, nur zum Festigen.
Du sollst gate.platform-security-posture approven. Die Release-Kriterien sagen: 'Security-Check clean, keine offenen Findings.' Du hast keine Zeit den Check selbst durchzuführen. Dein Kollege sagt: 'Letztes Mal war es auch clean — approve einfach.'
Modul 4: Drift & Eskalation
Kurs: iio-operator-basics | Modul: 4 von 4 | Dauer: ~45 minWas ist Drift?
Drift ist der Zustand, wenn die Realität vom erwarteten Zustand abweicht.Drifts sind keine Fehler. Sie entstehen natürlich im Betrieb. Das Problem ist stiller Drift — Drift, der nicht erkannt und dokumentiert wird.CODEBeispiele: Strukturdrift — Datei liegt am falschen Ort Zustandsdrift — YAML und JS beschreiben unterschiedliche Zustände Governance-Drift — Prozess wurde abgekürzt, kein Evidence vorhanden Inhaltsdrift — Dokumentation beschreibt nicht mehr was tatsächlich läuft
IIO-Prinzip: Kein stiller Drift
CODEFALSCH: Drift bemerkt → ignoriert → weitergemacht RICHTIG: Drift bemerkt → dokumentiert → eskaliert oder behoben
Jeder Drift — egal wie klein — wird dokumentiert. Erst dann kann entschieden werden: beheben, akzeptieren oder eskalieren.
Drift erkennen
Automatisch (via Scripts)
BASH# Drift-Check ausführen bash iio/specs/scripts/detect-state-drift.sh # Full-Stack-Audit (umfassend) bash iio/specs/scripts/run-full-stack-audit.sh # Session-Start (prüft automatisch) bash iio/specs/scripts/session-start.sh
Manuell (Indikatoren)
| Signal | Möglicher Drift |
|---|---|
| Validator schlägt plötzlich an | Strukturdrift |
| YAML- und JS-Dateien widersprechen sich | Zustandsdrift |
| Evidence-Files fehlen | Governance-Drift |
| Script läuft nicht durch | Wiring-Drift |
| Gate offen aber Arbeit abgeschlossen | Gate-Status-Drift |
Drift dokumentieren
Jeder erkannte Drift kommt in drift-report.yaml:
YAML# In iio/specs/agents/drift-report.yaml drifts: - id: DRIFT-2026-001 detected_at: "2026-05-03T10:00:00Z" detected_by: "[Operator] (session-start.sh)" type: structural description: "training-status.yaml fehlt in intelego/specs/" impact: medium status: open remediation_plan: "project-seed-to-node.sh ausführen" assigned_to: node-operator resolved_at: null
Drift-Schweregrade
| Grad | Beschreibung | Beispiel | Vorgehen |
|---|---|---|---|
| Critical | Blocker — System kann nicht weiterlaufen | Parity-Konflikt YAML/JS | Sofort beheben, kein Weiterarbeiten |
| High | Governance-Verletzung | Gate approved ohne Evidence | Sofort dokumentieren + eskalieren |
| Medium | Strukturproblem | Datei am falschen Ort | In Queue — nächste Session |
| Low | Inhaltliche Abweichung | Veralteter Kommentar in Doku | In Backlog |
Eskalation — wann und wie
Wann eskalieren?
- Drift-Schweregrad Critical oder High
- Du kannst den Drift nicht selbst beheben
- Drift betrifft Critical Area (Security, Legal, Finance, HR)
- Unsicherheit über Auswirkungen
Eskalationspfad
CODE1. Dokument in drift-report.yaml ↓ 2. Gate öffnen (falls Critical/High) bash iio/specs/scripts/escalate-gate-blocker.sh ↓ 3. Workspace Owner / Risk Owner informieren bash iio/base/iio-agent-bot/scripts/send-operator-notification.sh \ zolo gate_hitl '{"artifact":"DRIFT-ID","details":"Beschreibung"}' neutral ↓ 4. Warten auf menschliche Entscheidung → Beheben → Akzeptieren → Eskalieren weiters
Was NICHT zu tun ist
CODENICHT: Drift ignorieren und hoffen dass er sich auflöst NICHT: Validator anpassen um Drift zu verstecken (= Scheinfix) NICHT: Selbständig in Critical Areas beheben ohne Review NICHT: Drift "zwischen den Stühlen lassen" — immer Verantwortlichen zuweisen
Drift beheben — korrekte Sequenz
CODE1. Drift verstehen — was ist die Ursache? (Nicht das Symptom beheben) 2. Lösungsweg dokumentieren drift-report.yaml: remediation_plan setzen 3. Lösung implementieren Via IIO-Prozess (nie Direktfix) → lokal ändern → commit → push 4. Lösung verifizieren → Validator/Script erneut ausführen → Ergebnis: PASS 5. Drift als resolved markieren drift-report.yaml: status → resolved, resolved_at setzen 6. Evidence erstellen → session-closeout.sh erstellt automatisch
Typische Drifts und ihre Behebung
Parity-Drift: YAML ↔ JS
BASH# Symptom: session-start gibt NO-GO wegen Parity-Conflict # Ursache: node-state.yaml und node-state.js beschreiben verschiedene Zustände # Lösung: bash iio/specs/scripts/sync-public-state.sh # → regeneriert JS aus YAML, Parity wiederhergestellt
Klassifikations-Drift: Unklassifiziertes Artefakt
BASH# Symptom: validate-classification-completeness.sh findet unclassified Dateien # Lösung: Datei öffnen, classification hinzufügen: # classification: own | reference | generated | imported | archive
Wiring-Drift: Script referenziert fehlendes Modul
BASH# Symptom: validate-seed-operational-wiring.sh FAIL # Lösung: Fehlendes SKILL.md oder Eintrag in orchestration/workspace.yaml ergänzen
Anti-Kontamination — Sonderfall Drift aus migrate/
Der migrate/-Ordner enthält UNTRUSTED Legacy-Inhalte. Drift aus diesem Bereich hat besondere Regeln:
CODENIEMALS: Legacy-Strukturen aus migrate/ direkt in iio/base/ übernehmen IMMER: Semantik extrahieren → HITL-Review → dann selektiv übernehmen Grund: Legacy-Rails aus Altprojekten können falsch, veraltet oder kontraproduktiv sein. Kein blindes Kopieren.
Relevant: iio/specs/governance/ANTI-CONTAMINATION-POLICY.md
Wissenscheck — Modul 4
- Was ist der Unterschied zwischen einem erkannten und einem stillen Drift?
- Welche Aktion ist immer falsch beim Umgang mit Drift?
- Was sind die Schritte um einen Drift korrekt zu beheben?
- Wann muss eskaliert werden?
- Warum dürfen Inhalte aus
migrate/nicht direkt in den Seed übernommen werden?
Kurs abgeschlossen — nächste Schritte
Du hast alle 4 Module abgeschlossen. Jetzt:
- Workspace Owner informieren — Gate
training.iio-operator-basics-completeöffnen - Gate-Approval — Workspace Owner prüft und approvet
- Zertifikat — wird automatisch ausgestellt + in
training-status.yamleingetragen
Kurzer Check — kein Druck, nur zum Festigen.
validate-classification-completeness.sh meldet: 5 unclassified Dateien. Du hast gerade wichtigere Arbeit. Dein erster Gedanke: 'Das sind nur 5 Dateien — ich schaue das später an.'
- Zeitdruck macht Direktfixes verlockend
- Validator-Anpassungen fühlen sich wie 'Lösung' an, sind aber Symptombehandlung
- Kontext-Wissen ist bequem — neu lesen kostet Zeit