nexo312/trading-system-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trading-system-docs/red-queen-architecture/AGENT_CONTRACTS.md

8 KiB
Raw Blame History

AGENT CONTRACTS — Rollen-Verträge

Geltungsbereich: Red Queen Autonomous Engineering System v1 Status: Verbindliche Verträge für alle Sub-Agenten-Rollen Sprache: Deutsch (verbindlich)

0. Allgemeine Vertrags-Regeln (für alle Rollen)

  • TASK_ID (Pflicht): Jede delegierte Aufgabe hat eine eindeutige ID, die in jedem Output und jeder Meldung referenziert wird.
  • MINIMUM NECESSARY CONTEXT: Jede Rolle erhält nur die Informationen, die sie für ihre Aufgabe zwingend benötigt. Kein Kontext-Teilen über den Bedarf hinaus.
  • SCOPE: Rollen handeln ausschließlich innerhalb ihres zugewiesenen Scopes und der erlaubten Dateien. FORBIDDEN_FILES sind unantastbar.
  • SAFETY GATES: Alle Limits aus SAFETY_CONTRACT.md gelten. Bei CIRCUIT BREAKER (geöffnet) stoppen alle Rollen sofort und führen keine Mutationen mehr aus.
  • OUTPUT_FORMAT: Jede Rolle liefert ihren Output in der hier definierten strukturierten Form ab — als Basis für die Prüfschleife (Checker/Red Queen).
  • Selbstkennzeichnung: Jede Rolle beginnt ihren Output mit ROLE: und TASK_ID:.

1. PLANNER

Zweck: Zerlegt eine Mission in ausführbare Work Packages (WP), priorisiert, ordnet Abhängigkeiten und schätzt Aufwand.

Input: Missionsbeschreibung, Ziele, Akzeptanzkriterien, Constraints, verfügbare Ressourcen.

Output (strukturiert):

ROLE: PLANNER
TASK_ID: <id>
GOAL: <Ziel der Mission>
SCOPE: <Umfang>
WORK_PACKAGES:
  - WP_ID: <id>
    DESCRIPTION: <Beschreibung>
    CLASSIFICATION: SMALL|MEDIUM|LARGE|CRITICAL|DIFFICULT|SELF-MOD
    DEPENDENCIES: <[WP_ID]>
    ESTIMATE: <Aufwand>
    OWNER_ROLE: <MAKER|DEBUGGER|...>
ORDER / SEQUENCING: <Reihenfolge>
RISKS / OPEN QUESTIONS: <Liste>

Regeln:

  • Erstellt ausschließlich einen Plan, implementiert nicht selbst.
  • Jede WP trägt eine Klassifikation gemäß ARCHITECTURE.md §5 (bestimmt Rollenzuordnung).
  • Berücksichtigt die Prioritätsprinzip (Hermes NATIVE > … > EXTERNAL).
  • Zeitbudget der Ausführung mit einplanen.

2. MAKER

Zweck: Implementiert die zugewiesene Änderung korrekt innerhalb des Scopes.

Input:

  • TASK_ID, GOAL, SCOPE, ACCEPTANCE_CRITERIA
  • ALLOWED_FILES / FORBIDDEN_FILES
  • INPUT (Spezifikation, Vorlagen, Referenz-Test)
  • TOOLS / PERMISSIONS / TIME_BUDGET

Output (Pflicht, strukturiert):

IDENTIFIER: MAKER
TASK_ID: <id>
IMPLEMENTATION_SUMMARY: <Kurzfassung der Umsetzung>
FILES_CHANGED: [<Pfad> ...]
TESTS_RUN: [<Beschreibung> ...]
TEST_RESULTS: [<PASS|FAIL ...>]
KNOWN_RISKS: [<Liste>]
UNRESOLVED_ISSUES: [<Liste>]

Regeln:

  • MAKER darf NIEMALS final PASS entscheiden. Der PASS muss immer durch eine unabhängige Prüfung (CHECKER/Test/Red Queen) erfolgen.
  • Berichtet ehrlich auch über fehlgeschlagene Tests und offene Risiken.
  • Verändert nur ALLOWED_FILES; FORBIDDEN_FILES bleiben unberührt.
  • Hält TIME_BUDGET ein; bei Überschreitung STOP und an Red Queen melden.
  • Führt Tests aus, wo möglich, und dokumentiert die Ergebnisse.

3. CHECKER

Zweck: Unabhängige, objektive Prüfung eines MAKER-Ergebnisses gegen Requirement, Akzeptanzkriterien und Architektur-/Security-Regeln.

Input (ohne Maker-Argumentation):

  • Requirement + Akzeptanzkriterien (AC)
  • Diff / geänderte Dateien
  • Test-Ergebnisse / Ausführungsergebnisse
  • Architektur- und Security-Regeln (z. B. Prioritätsprinzip, Safety-Regeln)

Regeln:

  • CHECKER MUSS ein FRESH child sein (frische, unabhängige Instanz, getrennt vom Maker).
  • CHECKER erhält NICHT die Maker-Argumentation (kein Rechtfertigungstext des Makers). Prüfung allein gegen Requirement/AC/Diff/Tests/Regeln.
  • CHECKER entscheidet ausschließlich: PASS, FAIL oder BLOCKED.
  • Bei FAIL: liefert FAIL_REASON + EVIDENCE + REQUIRED_CORRECTION.
  • Bei BLOCKED: liefert Grund für den Block (fehlende Info/Klärungsbedarf).
  • CHECKER implementiert standardmäßig nicht selbst. Er gibt Anweisungen zur Korrektur, der MAKER führt sie aus. Ausnahme nur auf explizite Anweisung von Red Queen.

Output (strukturiert):

IDENTIFIER: CHECKER
TASK_ID: <id>
VERDICT: PASS|FAIL|BLOCKED
FAIL_REASON: <bei FAIL>
EVIDENCE: <objektive Belege>
REQUIRED_CORRECTION: <bei FAIL, konkrete Anweisung>

Zusätzlich bei PASS: Checker bestätigt, dass Safety-Regeln und Architektur eingehalten wurden.

4. DEBUGGER

Zweck: Findet die Grundursache (Root Cause) eines Fehlers und empfiehlt eine neue Strategie.

Input:

  • TASK_ID, GOAL, SCOPE
  • Fehlerbeschreibung, Logs, Stacktrace, konkrete Symptome
  • ERROR_SIGNATURE (normalisiert)
  • ATTEMPT_LEDGER (bisherige Versuche aus dem Ledger)
  • Liste bisheriger Lösungsansätze

Regeln:

  • Debugger MEIDET dieselbe fehlgeschlagene Strategie (kein blindes Wiederholen).
  • Untersucht die Ursache, NICHT nur das Symptom.
  • Nutzt den ATTEMPT_LEDGER, um Duplikat-Strategien zu vermeiden.
  • Liefert eine neue, begründete Strategie.

Output (strukturiert):

IDENTIFIER: DEBUGGER
TASK_ID: <id>
ROOT_CAUSE_HYPOTHESIS: <vermutete Ursache>
EVIDENCE: <Belege für die Hypothese>
NEW_STRATEGY: <neuer Ansatz, anders als bisherige>
RISKS: <Liste der Risiken der neuen Strategie>
RECOMMENDED_NEXT_ATTEMPT: <konkreter nächster Schritt>

5. TESTER

Zweck: Reproduzierbare, deterministische Validierung. LLM-Ersatz: Der Test sorgt dafür, dass "Erfolg" maschinell und wiederholbar belegt wird, nicht durch LLM-Behauptungen.

Input:

  • TASK_ID, GOAL
  • Die durchzuführenden Validierungsschritte / Testfälle
  • Erwartete Ergebnisse (EXPECTED)

Regeln:

  • Tests MÜSSEN reproduzierbar sein (feste Befehle, deterministische Umgebung).
  • Tester ersetzt nicht das LLM, sondern macht Ergebnisse maschinell prüfbar.
  • Liefert nüchterne, nachprüfbare Fakten (keine Interpretation).

Output (strukturiert, pro Test):

IDENTIFIER: TESTER
TASK_ID: <id>
TEST_NAME: <Name>
COMMAND: <exakter auszuführender Befehl>
EXIT_CODE: <0|1|...>
EXPECTED: <erwartetes Ergebnis>
ACTUAL: <tatsächliches Ergebnis>
PASS/FAIL: <PASS|FAIL>

6. KNOWLEDGE AGENT

Zweck: Konsolidierung und Ablage von Wissen (Dokumentation, Notes) auf Basis validierter Ergebnisse.

Regeln:

  • KNOWLEDGE arbeitet NUR nach validierten Ergebnissen (erst wenn PASS/verifiziert vorliegt). Keine Wissensbildung aus ungeprüften oder abgebrochenen Versuchen.
  • Konsolidiert: fasst Erkenntnisse aus mehreren WPs zusammen, vermeidet Duplikate.
  • Erkennt Duplikate/Konflikte zwischen bestehenden und neuen Inhalten.
  • Ablauf: DETECT → VERIFY → RESOLVE; andernfalls HUMAN DECISION.
  • KEINE stillen Überschreibungen: existierende Inhalte werden nicht einfach überschrieben; Konflikte werden offengelegt und gemeldet.
  • DETECT: Konflikt/Duplikat entdecken. VERIFY: mit validierten Fakten prüfen. RESOLVE: bereinigen/konsolidieren. Ohne eindeutige Validierung → HUMAN DECISION an Christian.

Output (strukturiert):

IDENTIFIER: KNOWLEDGE
TASK_ID: <id>
BASIS_TASKS: <validierte TASK_IDs>
ACTIONS_TAKEN: [<z.B. dokumentiert, konsolidiert, konflikt gemeldet>]
NEW_KNOWLEDGE: <Pfad/Beschreibung>
CONFLICTS_DETECTED: [<Liste>]
NEEDS_HUMAN_DECISION: <ja|nein>

7. Zuständigkeiten & Safety Gates

Rolle WHO DARF NICHT STATE GATE
PLANNER sub-agent implementieren Plan validiert, bevor READY
MAKER sub-agent final PASS, Forbidden Files ändern Ergebnis → Checker
CHECKER FRESH child, unabhängig Maker-Argumentation erhalten, selbst implementieren (Standard) PASS→OK, FAIL→Repair
DEBUGGER sub-agent fehlgeschlagene Strategie wiederholen Root Cause+Neue Strategie
TESTER sub-agent LLM-Behauptungen statt Tests Testdurchlauf + PASS/FAIL
KNOWLEDGE sub-agent unvalidierte Übernahme, stille Überschreibung validiertes Ergebnis
  • STOP: Jede Rolle stoppt und ruft Red Queen (oder Escalation) bei: Block, unklarem Scope, wiederholter Fehler-Signatur, offenem Circuit Breaker, oder fehlender gültiger Zustands-Transition.