IIO Operative Praxis

0 · Neu: Tagesadministration fuer Objekte, Kunden und Projekte

Auf deine Praxisfrage gibt es jetzt ein eigenes Grosskapitel mit SOPs und aufgesplittetem Objektbaum: Taegliche Administration: Objekte, Kunden, Projekte.

Objekt anlegen

→

Kunde public/private trennen

→

Projekt starten

→

TX + Audit sauber

1 · Neue Story erstellen – der vollständige Ablauf

Eine Story ist die operative Einheit: ein abgrenzbares, commit-fähiges Vorhaben mit Premise-Coverage, Skill-Assignment und HITL-Gate.

Intake

→

Premise-Mapping

→

Gate-Bewertung

→

HITL-Gate

→

GO / Commit

→

Revision

Intake klassifizieren: Typ (new_feature | premises_change | contract_change | drift_fix | audit), Scope (Dateipfade), Actor-ID, Phase (report | adaptive | strict).
Canonical Sources prüfen: Alle 7 Quellen lesbar? (→ Priority Registry in Gate-Matrix unten). Wenn eine Quelle fehlt: sofort BLOCK.
Premise-IDs mappen: Welche Prefixe betrifft die Änderung? (→ Prefix-Tabelle Abschnitt 2). Mindestens einen P-Präfix identifizieren.
8-Gate-Assessment: Jeden der 8 Gates evaluieren. Ergebnis: pass | pass-inferred | block | escalate. Bei strict: kein pass-inferred zulässig.
HITL-Gate entscheiden: Handoff-Signal setzen wenn nötig. Checkliste: Änderung sichtbar für User? Daten betroffen? Architektur-Impact? → ESCALATE.
GO-Entscheidung aufzeichnen: Alle Gates passed → Story-Revision erstellen unter iio/public/revisions/ mit Decision-Metadata.
Commit + Publish: Story läuft durch den Trace-Pfad (→ Abschnitt 5): Skill → Base → Public.

2 · Premise-Prefix-Referenz (18 Layer)

Jede Änderung im System muss auf mindestens einen Premise-Präfix gemappt werden. Prefix bestimmt den Gate-Einstiegspunkt.

P-CORE

Ontologie → actor-Gate

P-STORY

Story-Layer → story-Gate

P-ROLE

Rollen → role-Gate

P-ARCH

Architektur → role + boundary

P-COMP

Komposition → composition-Gate

P-TXN

Transaction → txn + audit

P-BOUND

Boundary → boundary-Gate

P-SKILL

Skills → skill-Gate

P-DIAG

Diagramme → audit-Gate

P-EXEC

Runtime / Determinism → alle

P-SAFE

Safety / Guardrails → alle

P-PROJ

Seed-Node → actor + story

P-LEARN

Learning Loop → story + audit

P-LANG

Sprache / Publishing → boundary

P-MIG

Migration → txn + audit

P-ROOT

Root Placement → boundary

P-NOAI

No-AI Fallback → skill + txn

P-OPS

Operator Governance → txn + audit

Regel: Wenn eine Änderung iio/specs/, iio/base/ oder ein AGENTS.md berührt, sind immer P-EXEC und P-SAFE co-aktiv (alle Gates).

3 · 8-Gate-Assessment Matrix

Gates werden in dieser Reihenfolge evaluiert. Jedes Gate kann pass, pass-inferred, block oder escalate ausgeben. Ein einziges BLOCK stoppt den flow.

#	Gate	Was wird geprüft	BLOCK-Trigger	Quelle
1	actor	Gültiger Actor-ID; keine anonyme Transaktion	Kein Actor-ID im Intake	`contract.yaml`
2	story	Story-Scope klar definiert; Premise-Coverage nachgewiesen	Scope leer; keine P-IDs identifiziert	`layer-premises-catalog.yaml`
3	role	Actor hat die Rolle(n) für diese Änderung	Rolle nicht in `team-workflow.yaml` eingetragen	`team-workflow.yaml`
4	boundary	Änderung überschreitet keine Scope-Grenzen; Root Placement korrekt	Datei außerhalb erlaubtem Placement; Cross-Scope ohne Delegation	`root-placement-policy.yaml`
5	composition	Layer-Abhängigkeiten korrekt; keine zirkulären Referenzen	Upstream-Layer nicht stabil; Zirkularität erkannt	`LAYER-INTEGRATION.md`
6	skill	Verwendete Skills mit passender Evidenzklasse zugewiesen	Skill ohne Evidence-Klasse; proficiency_level zu niedrig	`SKILL-REGISTRY-LAYER.md`
7	transaction	Transaktion vollständig: TX-ID, Timestamp, Actor, Payload-Hash	Fehlende Pflichtfelder im TX-Schema	`TRANSACTION-LAYER.md`
8	audit	Audit-Trail vollständig; kein Evidence-Gap; Reviewer bestimmt	Evidence fehlt oder nicht reproduzierbar; kein Reviewer	`contract.yaml` + `team-workflow.yaml`

8/8 pass → GO

|

≥1 block → BLOCK

|

HITL-Signal → ESCALATE

4 · Tägliche Abläufe — Quick Reference

Die häufigsten Operator-Aktionen und welche Gate-Subset sie auslösen.

Story committen (Routine)

Intake: new_feature, Actor gesetzt
Premise-IDs: ≥1 identifiziert
Gates 1–8 evaluiert, alles pass
Kein HITL-Signal → direkt GO
Revision-Eintrag in public/revisions/
Git commit mit TX-ID im Message

Premise ändern (P-Change)

Intake: premises_change
Evidence vorhanden? Wenn nein → BLOCK
Alle betroffenen P-IDs auflisten
P-EXEC + P-SAFE immer co-aktiv
Phase auf strict setzen
HITL-Gate: immer ESCALATE
Reviewer in team-workflow.yaml bestätigt

Drift beheben (Fix)

Intake: drift_fix
Quell-Datei identifizieren (wo ist canonical?)
Fix NUR an Quelle — nie am Downstream-Artefakt
Gates 4 (boundary) + 7 (txn) + 8 (audit)
Drift-Eintrag in governance-depth-map schließen

Periodischer Audit

Intake: audit, Phase strict
Alle 7 Canonical Sources durchlaufen
Alle aktiven OPs: noch gate-compliant?
Drift-Heatmap aktualisieren
Offene HITL-Gates schließen oder eskalieren
Audit-Revision erstellen

Manual / Public aktualisieren

Intake: new_feature oder drift_fix
P-LANG + P-OPS prüfen (boundary-Gate)
Quelle zuerst: spec/base → dann manual/public
CSS/Nav: nur in _shell.js / _public-shell.js
Kein per-Seite-Workaround

Neue Node registrieren

Intake: new_feature
P-PROJ (actor + story-Gate)
Root-Placement: root-placement-policy.yaml
AGENTS.md für neue Unterordner setzen
Gateway-Check: Überschneidung mit anderen Nodes?
HITL: Sichtbarkeit für andere Nodes? → ESCALATE

5 · Worked Example: Premise-Assessment in der Praxis

Konkretes Beispiel: Ein Operator fügt eine neue Manual-Seite hinzu, die Governance-Informationen zeigt. Wie läuft das Assessment ab?

Szenario Neue Manual-Seite "Operative Praxis" hinzufügen

Intake:
request_type : new_feature scope : iio/manual/operative-praxis.html, iio/theme/_shell.js, iio/manual/index.html actor_id : operator/main phase : report priority : normal blocking_gate : boundary evidence_present: yes

Premise-Mapping Welche P-Prefixe sind betroffen?

Prefix	Warum betroffen	Gate-Impact
`P-LANG`	Neue Seite publiziert Inhalte im Manual	boundary-Gate
`P-OPS`	Operator-Governance-Doku geändert	txn + audit
`P-STORY`	Story-Konzept beschrieben → Story-Gate	story-Gate

Gate Trace Alle 8 Gates evaluiert

Gate	Ergebnis	Evidenz
actor	pass	operator/main bekannt in team-workflow.yaml
story	pass	P-LANG, P-OPS, P-STORY identifiziert; scope klar
role	pass	operator/main hat new_feature-Berechtigung
boundary	pass	iio/manual/ liegt in erlaubtem Placement
composition	pass	Kein Upstream-Layer verändert
skill	pass-inferred	Keine neue Skill-Datei; vorhandene Manual-Skills gelten
transaction	pass	TX-ID wird im Git-Commit-Message gesetzt
audit	pass	File-Änderungen sind reproduzierbar; keine Evidence-Gaps

Ergebnis: 8/8 pass → GO. Kein HITL-Signal nötig. Direkt commit möglich.

6 · Fail-Closed: Wann der Operator stopp macht

Fail-Closed ist kein Notfallmodus — es ist der Default. Diese Situationen erzwingen immer einen STOP, auch wenn kein expliziter BLOCK ausgegeben wurde.

Situation	Default	Warum
Scope nicht bestimmbar	BLOCK	Kein Premise-Mapping ohne Scope möglich
Canonical Source nicht lesbar	BLOCK	Gate-Bewertung ohne Quelle ist ungültig
Actor-ID fehlt	BLOCK	Kein gültiger Transaktionsanker
Evidence nicht vorhanden (bei premises_change)	BLOCK	Premise-Änderung ohne Evidence ist strukturell ungültig
Gate-Ergebnis unklar / widersprüchlich	ESCALATE	Unsicherheit → HITL-Entscheid nötig; AI entscheidet hier nicht selbst
Reviewer nicht bestimmt (bei audit)	BLOCK	Audit ohne Reviewer ist nicht abgeschlossen
Downstream-Seite ohne Upstream-Quelle	BLOCK	Keine "Quick Fix" an Artefakten erlaubt; immer Quelle zuerst
Architektur-Impact unbekannt	ESCALATE	Ko-Evolutionsgrenze: Mensch muss impact einschätzen

Merksatz: Das System bevorzugt eine klare Ablehnung mit Ursache gegenüber einer unvollständigen Genehmigung. Jeder BLOCK hat eine Reparatur-Anleitung — kein BLOCK ist terminal.

7 · Ko-Evolution: Human ↔ Agent Rollenverteilung

IIO ist kein Automatisierungs-System im klassischen Sinne. Es ist ein Ko-Evolutions-Framework: Mensch und Agent tragen komplementäre Verantwortlichkeiten.

Human (HITL-Operator)

Premises definieren und legitimieren
Gate-Entscheidung bei ESCALATE
Architektur-Impact beurteilen
Team-Workflow und Reviewer bestimmen
Sichtbarkeit für andere Nodes prüfen
Roadmap und Story-Priorität setzen
System-Design verantworten (OBEN in der Klettermetapher)

Agent (AI Operator)

Gate-1–8 deterministisch evaluieren
Premise-Mapping aus Scope ableiten
BLOCK- und ESCALATE-Signale korrekt senden
Evidence-Ketten zusammenstellen
Revisionen und Audit-Trails erstellen
Downstream-Artefakte nach Freigabe erzeugen
Never infer intent beyond evidenced scope

Ko-Evolutions-Grenze: Alles, was Premises definiert oder Architektur-Impact hat, liegt auf der menschlichen Seite. Alles, was deterministisch aus bestehenden Premises folgt, liegt auf der Agent-Seite. Die Grenze ist die ESCALATE-Entscheidung.