Migration & Adoption Playbook

Schritt-für-Schritt-Leitfaden für die Einführung und laufende Pflege eines IIO-Nodes — von der ersten Platzierungsentscheidung über den No-AI-Ops-Betrieb bis zum Lernkreislauf zurück in den Seed.

Überblick: Drei Phasen

Jede IIO-Adoption durchläuft drei verbindliche Phasen. Keine Phase darf übersprungen werden.

Phase 1 — BEFORE: Placement & Struktur klären. Was gehört wohin? Welche Relations müssen entstehen? Neun Entscheidungsfragen bestimmen die Verortung jeden Artefakts.

Phase 2 — DURING: Adoption mit No-AI-Ops. Alle Kern-Operationen (init, adopt, discover …) laufen ohne LLM — deterministisch, scriptbar, lokal.

Phase 2 — AFTER: Learning Loop aktivieren. Beobachtungen am Node werden klassifiziert (local-only vs. seed-relevant) und nach definiertem Protokoll zurückgeführt oder lokal archiviert.

P-MIG-001 P-NOAI-001 P-LEARN-001 fail-closed Actor-agnostisch

PHASE 1 — BEFORE

Placement Rules

Bevor ein Node initialisiert wird, muss jedes Artefakt verortet werden. Die Hauptregel ist absolut:

Ein Node enthält ausschließlich das, was diesem Node gehört.

Neun Entscheidungsfragen bestimmen die Verortung:

Gehört das hier? (Ownership)

Wird das nur referenziert?

Wird das generiert?

Ist das importiert / Legacy?

Ist das ein Record / Archiv-Objekt?

Ist das sensitiv?

Gibt es einen Contract-, Lizenz-, Legal-, HR-, Finance- oder Tax-Impact?

Gehört das in ein Companion-Repo?

Welche Relations müssen entstehen?

Entscheidungsbaum

Antwort	Konsequenz
Q1 = Ja	Artefakt liegt im Node, volle Ownership-Dokumentation
Q2 = Ja	Nur Referenz-Link anlegen, kein Eigentumsanspruch
Q3 = Ja	Generiertes Artefakt in `generated/`-Verzeichnis, nicht versioniert
Q4 = Ja	Importiertes Artefakt in `imported/` oder `legacy/`, mit Quellvermerk
Q5 = Ja	In `archive/` ablegen, unveränderlich markieren
Q6 = Ja	Separate Ablage mit Zugriffsschutz, kein Plaintext in Repo
Q7 = Ja	Rechtsprüfung vor Verortung, Eskalation an Owner wenn unklar
Q8 = Ja	Companion-Repo anlegen, Cross-Referenz im Haupt-Node
Q9 = Ja	Relations in `relations.yaml` erfassen, bevor Node aktiviert wird

P-ROOT-001 P-ROOT-002 P-BOUND-001

PHASE 2 — DURING

No-AI Ops — Kernoperationen

IIO muss ohne LLMs laufen. LLMs beschleunigen Klassifikation, Planung und Coding, aber die Kern-OPS bleiben deterministisch, scriptbar und lokal. Kein Core-Command darf LLM-Verfügbarkeit voraussetzen.

LLM-optional deterministisch scriptbar lokal lauffähig

Unterstützte Core-Operationen (ohne LLM)

boot

Node starten, Services prüfen, Health-Check

init

Neue Node-Struktur aus Seed-Template anlegen

adopt

Bestehende Struktur in IIO-Governance überführen

discover

Registry-Einträge finden und validieren

inventory

Vollständiges Bestandsverzeichnis aller Artefakte

classify

Regelbasierte Klassifikation (ohne LLM)

suggest

Profil-Vorschläge aus Templates generieren

plan

Migrations-Skeleton aus Regeln ableiten

validate

Struktur- und Premises-Validierung

display

System-State und Relations anzeigen

check-relations

Relation-Integrität prüfen

Typischer Adoptions-Ablauf

1. boot — Systemvoraussetzungen prüfen, Dependencies validieren, Health-Check bestätigen

2. inventory — Vollständiger Ist-Zustand der zu adoptierenden Struktur erfassen

3. classify — Regelbasierte Klassifikation: Was ist owned / referenced / generated / imported?

4. plan — Migrations-Skeleton aus Placement Rules und Inventory ableiten (kein LLM nötig)

5. validate — Plan gegen Premises-Katalog prüfen, Placement-Fragen Q1–Q9 beantworten

6. init — Node-Struktur aus verifiziertem Plan aufbauen

7. adopt — Bestehende Artefakte in neue Struktur überführen, Relations anlegen

8. discover — Node in Registry eintragen, Sichtbarkeit für Federation prüfen

LLM-Einsatz während Adoption

Aktivität	LLM erlaubt?	Hinweis
Core-Command ausführen (`init`, `adopt` …)	Optional	Command selbst ist LLM-unabhängig
Klassifikation von Randfällen	Unterstützend	Ergebnis muss human-reviewt werden
Migrations-Plan-Text formulieren	Unterstützend	Struktur kommt aus Rules, nicht LLM
Go/Block-Entscheid treffen	Verboten	Muss deterministisch + human-approvedt sein
Premises ändern	Verboten	Immer strict-phase mit Human-Reviewer

P-NOAI-001 P-EXEC-001 P-EXEC-002 P-SAFE-002

PHASE 3 — AFTER

Learning Loop: Seed ↔ Node

IIO ist lernbegierig. Ein realer Node ist nicht nur Verbraucher des Seeds, sondern Quelle für Verbesserungen am Seed. Jede Erkenntnis aus dem Betrieb muss klassifiziert und nach Protokoll verarbeitet werden.

Klassifikation von Erkenntnissen

local-only

Erkenntnis gilt nur für diesen Node
Kein Seed-Impact
Wird lokal dokumentiert und archiviert
Kein Review-Gate nötig

seed-relevant

Verbessert universelle Regeln, Strukturen oder Guardrails
Wird in den Seed zurückgeführt
Review-Gate zwingend in kritischen Bereichen
Change-Hinweis für andere Nodes erforderlich

Pflichtablauf je Erkenntnis

1. Beobachtung erfassen — Kontext, Problem, Trigger, Auswirkungen dokumentieren

2. Evidenz sichern — Dateien, Entscheidungsgrund, Risiko und reproduzierbare Spuren erfassen

3. Klassifizieren — local-only oder seed-relevant?

4. Entscheidung dokumentieren — Warum bleibt es lokal oder warum muss es in den Seed?

5. Rückführung (nur seed-relevant) — Kleine, reviewbare Änderung am Seed erstellen; Auswirkungen auf bestehende Nodes markieren; Change-Hinweis anhängen

Minimales Protokollformat

id:       <uuid>
date:     <ISO-8601>
node:     <node-id>
category: local-only | seed-relevant
summary:  <ein Satz>
evidence: <Pfad oder Beschreibung>
risk:     <none | low | medium | high>
decision: <Begründung warum lokal oder zurückgeführt>
follow_up: <leer oder geplanter Change-ID>

Guardrails

Guardrail	Erklärung
Keine direkte Generalisierung ohne Evidenz	Einzelbeobachtung ≠ universelle Regel; Evidenzpflicht vor Seed-Änderung
Keine Seed-Änderung mit unklarem Impact	Impact auf bestehende Nodes muss vor Rückführung analysiert sein
Kein Review-Skip in kritischen Bereichen	Premises, Guardrails, Contract: immer Human-Reviewer erforderlich
Keine lokale Ausnahme als universelle Regel	Was lokal passt, muss nicht global passen — Klassifikation zuerst

Done-Definition einer Erkenntnis

✓ Klassifikation ist gesetzt (local-only oder seed-relevant)

✓ Evidenz ist dokumentiert

✓ Entscheidung ist begründet

✓ Bei seed-relevant: Rückführung umgesetzt oder als geplanter Change erfasst

P-LEARN-001 P-LEARN-002 P-TXN-001 P-EXEC-003

Vollständiger Lebenszyklus (Übersicht)

Phase	Ziel	Kernprinzip	Premises
BEFORE	Placement klären, Struktur und Relations definieren	Ein Node enthält nur, was ihm gehört	P-ROOT-001 P-BOUND-001
DURING	Resiliente Adoption: LLM-frei, deterministisch	Kern-OPS müssen ohne LLM funktionieren	P-NOAI-001 P-EXEC-001
AFTER	Erkenntnisse klassifizieren und Seed iterativ verbessern	Node ist Quelle, nicht nur Verbraucher	P-LEARN-001 P-TXN-001

Quellen

iio/base/agentic-organization/PLACEMENT-RULES.md — Placement-Entscheidungsfragen
iio/base/agentic-organization/NO-AI-OPS.md — No-AI-Ops Prinzip und Command-Liste
iio/base/agentic-organization/LEARNING-LOOP-SEED-NODE.md — Lernkreislauf-Protokoll