grahama1970/agent-ecosystem

Agent Ecosystem

Eine geschichtete Governance-Schleife. Jede Komponente besitzt genau eine Aufgabe; sie koppeln nur durch typisierte JSON-Verträge, niemals durch Import der Zustandsmaschinen der jeweils anderen.

Das unveränderliche $shame-Ziel ist shame-deterministic-instruction-obedience-v1 (skills/shame/immutable_goal.json): Es soll Projekt-Agenten unmöglich gemacht werden, explizite Anweisungen zu ignorieren, indem Instruktionsgehorsam und Abschlussberichte in typisierte pydantic-validierte Verträge, deterministische Erweiterungsgates und beibehaltene agentische Evaluierungen umgewandelt werden. Prosa ist nur zur Anzeige und kann nicht über Erfolg entscheiden. Jedes unten genannte Ökosystem-Mitglied MUSS dieses Ziel an seiner Grenze bewahren.

Der Graph

Gerendert mit $create-svg (scene.yml ist die Quelle; neu generieren mit skills/create-svg/run.sh render skills/agent-ecosystem/scene.yml skills/agent-ecosystem/ecosystem.svg). Das maschinenlesbare Mitgliederverzeichnis ist members.json (validiert von scripts/membership.py validate; beibehaltene Evaluierung hält es aktuell). erzeugt sie, das obige SVG und der folgende Mermaid-Block sind NICHT-NORMATIVE Illustrationen; die Besitztabelle und die ## Ecosystem-Abschnitte der Mitglieder sind die normative Topologie.

flowchart TB
    subgraph SHAPE[Erzeugungsformung]
        PONY[ponytail\nYAGNI-Leiter, keine Receipts]
    end
    subgraph TURN[Zug-Ebene - Pi-Sitzung]
        SHAME[shame extension\npi.agent_status.v1\nvalidieren, kompilieren, schlucken]
        TRIAGE[triage-error\nFehlervokabular\ncode, cause, next_command]
    end
    subgraph WORK[Workflow-Ebene]
        ASK[ask\nkompiliert Absicht zu DAG-Verträgen]
        TAU[tau\nführt DAGs aus, besitzt Akzeptanz\ntypisierte Knoten-Receipts, goal_hash]
    end
    subgraph OPS[Betriebsebene]
        WD[project-watchdog\nCron-Dispatch, Leases,\nProof-Gates, Tick-Receipts]
        HERDR[ops-herdr bridge\nInbox, Quieszenz,\nTTL-Totbriefe]
    end
    MEM[(Memory\nTrainingsbeispiele,\nTriage-Auflösungen,\nProjektwissen)]

    PONY -.-> SHAME
    SHAME -->|failed.triage.code| TRIAGE
    SHAME -->|needs_* kompilierte Befehle| ASK
    ASK -->|tau.dag_contract.v1| TAU
    TAU -->|Knoten-Receipts / handoff v2 trägt Status| SHAME
    WD -->|ticket_repair via ask| ASK
    WD -->|liest Urteile| TAU
    HERDR -->|Totbrief-Triage-Codes| TRIAGE
    SHAME -->|beschriftete Beispiele| MEM
    TRIAGE -->|geprägte Codes| MEM
    TAU -->|Export fehlerhafter Knoten-Receipts nach Ausführung| MEM

Besitztabelle

Komponente	Besitzt	Gibt aus	Konsumiert	MUSS für das unveränderliche $shame-Ziel
Projekt-Agenten	Instruktionsgehorsam an der Zug-Grenze	pi.agent_status.v1-Berichte	Operatoranweisungen, Tool-Ergebnisse, Receipts	MUSS bewachte Arbeit als typisierte Statusdaten melden, continuing.not_done[].next_command für agentenausführbare unerledigte Arbeit verwenden und niemals Prosa/Commits/Reviewer-Meinung als Abschlussnachweis behandeln.
triage-error	Fehlervokabular (failure_codes.json)	{code, cause, next_command}	roher Fehlertext aus jeder Ebene	MUSS ein rohes Signal auf einen Katalog- oder geprägten Code abbilden; vage terminale Bezeichnungen können keine gültigen Entscheidungen werden.
shame	Zug-Status (pi.agent_status.v1) und shame.immutable_goal.v1	Statusobjekte, unveränderliches Ziel, Trainingsbeispiele	Triage-Codes, menschliche Beschriftungen	MUSS Statuswahrheit pydantic-validiert, nur zur Prosa-Anzeige und evaluierungsbewertet halten.
lazy-report-shame-shame-shame extension	Pi message_end-Durchsetzung	Ablehnungspakete, gerenderter Status, Folgekommandos	endgültiger Status JSON, Fortsetzungsjournale	MUSS fehlenden/ungültigen Status JSON ablehnen, vom Modell verfassten Status-Prosa entfernen, aus validierten Daten rendern und kompilierte Fortsetzungs-/Eskalationsbefehle in die Warteschlange stellen.
status-json-check.mjs	Endstatus-Extraktion und Validator-Aufruf	Prüfergebnis mit validiertem Statusobjekt	Assistententext	DARF Statusgültigkeit nicht mit Regex, Prosa-Überschriften, Markdown, HTML oder LLM-Urteil entscheiden.
agent_status_schema.py	pydantic-Status-Legalität	Parse bestanden/nicht bestanden	endgültiger Status JSON	MUSS ungültige Statuszustände mit extra=forbid, typisierten Zustands-Payloads, kanonischen Triage-Codes und not_done nur bei continuing undarstellbar machen.
compile-status-command.mjs	Typisierte Status-zu-Befehl-Kompilierung	genauer Folgekommando oder kein Befehl	pydantic-valides Statusobjekt	MUSS continuing/needs_*-Payloads mechanisch kompilieren und terminale/menschliche Zustände zu keinem Autobefehl kompilieren.
agentic-evals	beibehaltene Regressionsnachweise	Bereitschaftsberichte	Fixtures und Befehle	MUSS fehlschlagen, wenn Regex/Prosa-Statusrichtlinie zurückkehrt oder pydantic-Statusinvarianten geschwächt werden.
ask	Absichts-zu-DAG-Kompilierung	tau.dag_contract.v1, Wiederherstellungspakete	Status-Eskalations-Payloads	MUSS typisierte needs_*-Payloads anstelle von informeller Eskalationsprosa konsumieren.
tau	DAG-Ausführung und Akzeptanz	Knoten-Receipts, tau.agent_handoff.v1/v2, Ziel-Hashes	DAG-Verträge, eingebettete Statusobjekte	MUSS unveränderliche Ziel-Hashes und typisierte Akzeptanz-Receipts besitzen; Reviewer-Prosa kann Akzeptanz nicht ersetzen.
project-watchdog	geplanter Dispatch	Tick-Receipts, Proof-Gates, Sperren, Fortsetzungsjournale	GitHub-Tickets, tau-Urteile	MUSS maschinenlesbare offene Arbeit bereitstellen, sodass done fehlschlagen kann, während Tickets/Gates/nächste Schritte ungelöst bleiben.
ops-herdr	sitzungsübergreifender Transport	Inbox-Datensätze, Totbriefe	Triage-Codes	MUSS sitzungsübergreifende Fehler/Zustände als typisierte Inbox- oder Totbriefdatensätze mit Triage-Codes transportieren.
ponytail	Erzeugungsminimalismus	ponytail:-Schuldenkommentare (keine Receipts)	nichts aus der Receipt-Welt	DARF Status-, Receipt-, Proof- oder Evaluierungsanforderungen nicht überschreiben.
Memory	Abruf	Speichern/Abrufen Rückleseantworten (keine Envelope-Receipts; Abrufe sind Beobachtungen, niemals verpackt)	alles dauerhafte	MUSS shame-Beispiele, Triage-Auflösungen und Projektwissen mit Rücklese speichern; Abrufe sind Beobachtungen, keine Abschluss-Receipts.
agent-ecosystem	Komponentenbesitz und Receipt-Grenzen	pi.receipt_envelope.v1-Validierung	Grenz-Payloads	MUSS die Besitzkarte veröffentlichen und Envelope-Verpackung an autoritätswechselnden Grenzen verlangen.
goal-helper	nachweiszentrierte Zielform	unveränderliches Ziel-Prompt/Checkliste	menschlicher Zieltext	MUSS Erfolg an primären Nachweis, Abschlusskriterien, erlaubten Umfang, verbotene Abweichung, Wiederholungsbudget und Stoppbedingung binden.

pi.receipt_envelope.v1 - der Grenzenvelope

Verpacken Sie eine Payload NUR an autoritätswechselnden Grenzen in den Envelope: Dispatch, Übergabe, Akzeptanz, Eskalation, Abschluss, dauerhafter Fehler. Interne Objekte bleiben unverpackt (geprüftes YAGNI-Urteil: kein universeller Ereignisbus, kein Envelope auf jedem Artefakt).

{
  "schema": "pi.receipt_envelope.v1",
  "receipt_id": "stabile-id",
  "payload_schema": "pi.agent_status.v1",
  "producer": "shame",
  "emitted_at": "RFC3339",
  "goal_hash": "sha256:<64hex> (optional)",
  "parent_refs": [
    {"receipt_id": "id", "expected_schema": "s", "expected_producer": "p", "digest": "sha256:<64hex> (optional)"}
  ],
  "triage_code": "Katalog- oder geprägter Code (optional)",
  "payload": {}
}

Validieren mit:

skills/agent-ecosystem/run.sh validate <envelope.json>
echo '{...}' | skills/agent-ecosystem/run.sh validate -

Regeln, durchgesetzt von scripts/receipt_envelope.py (pydantic, extra=forbid):

• triage_code, falls vorhanden, muss ein Katalogcode von triage-error oder ein geprägter *_unclassified_<8hex>-Code sein - dieselbe Regel wie pi.agent_status.v1.failure.
• goal_hash und parent_refs[].digest müssen sha256: + 64 hexadezimale Kleinbuchstaben sein.
• parent_refs erfordern goal_hash: Eine Beweiskante ohne gemeinsames Ziel ist nicht vertrauenswürdig und schlägt bei der Validierung fehl.
• Pydantic bewegt nur die STRUKTUR. Die Referenzauflösung (REFERENCE RESOLUTION) ist ein separater Schritt auf der Konsumentenseite mit vier obligatorischen Prüfungen: Die referenzierte Receipt existiert; ihr Schema ist gleich expected_schema; ihr Produzent ist gleich expected_producer; und resolved_parent.goal_hash == envelope.goal_hash (ein vorhandener Hash ist erst dann ein gemeinsames Ziel, wenn er verglichen wird). Die Digestprüfung wird angewendet, wenn digest gesetzt ist. Ein strukturell gültiger Envelope ist noch kein vertrauenswürdiger.
• payload.schema ist in jeder verpackten Payload ERFORDERLICH und muss dem Envelope payload_schema entsprechen; eine anonyme Payload schlägt bei der Validierung fehl.
• Feldmengenänderungen an jedem extra=forbid-Schema sind konstruktionsbedingt brechend; sie erfordern eine neue Schemaversion, niemals eine direkte Änderung.

Gemeinsame JSON-Feldkonventionen

Die folgenden Felder sind die tatsächliche gemeinsame Oberfläche. Eine Komponente "teilt" ein Feld, wenn sie denselben Namen, dieselbe Form und dieselbe Semantik wie der Besitzer ausgibt oder validiert.

Feld	Form	Besitzer	Geteilt von
schema	versionierte ID, z.B. pi.agent_status.v1	jeder Schema-Besitzer	jedes Vertragsobjekt; Versionssprünge sind additiv-oder-neuer-Name
code (Triage)	Katalogeintrag oder <präfix>_unclassified_<8hex>	triage-error	shame failure.triage.code, Envelope triage_code, herdr-Totbriefe, ask-Wiederherstellungspakete
cause / next_command	einfacher String / genauer ausführbarer Befehl	triage-error	jeder Konsument einer Triage-Klassifikation; next_command ist auch das shame continuing-Weitermach-Feld
goal_hash	sha256: + 64 hexadezimale Kleinbuchstaben	tau (unveränderliches Zielpaket)	shame-Status (optional), Envelope (optional), jeder tau-Knoten-Receipt
verified[]	{command, result}-Paare	shame	Nachweis im done-Zustand überall, wo ein Statusobjekt eingebettet ist
proof[]	konkrete Pfade/URLs/IDs; lokale Pfade in pi.agent_status.v1 müssen existieren, bevor done durchgeht	shame	Statusobjekte; watchdog-Proof-Gates benennen dieselben Artefakte
parent_refs[]	{receipt_id, expected_schema, expected_producer, digest?}	agent-ecosystem Envelope	Eskalationsnachweise (ersetzt Ad-hoc-Pfade in needs_webgpt)
producer / receipt_id / emitted_at	String / stabile ID / RFC3339	agent-ecosystem Envelope	jeder an der Grenze verpackte Receipt
payload_schema	versionierte ID; muss gleich payload.schema sein, wenn die Payload eine deklariert	agent-ecosystem Envelope	jeder an der Grenze verpackte Receipt
terminale Urteile	PASS FAIL BLOCKED NEEDS_ATTENTION	tau	ask verbindet, watchdog-Proof-Gates, Stream-Monitore
recoverable / not_this	bool / Ausschlussliste	triage-error Katalog	Konsumenten, die über Wiederholung vs. Eskalation entscheiden

triage-error-Konventionen (normativ hier, implementiert dort)

1. Ein rohes Signal wird auf EINEN {code, cause, next_command} abgebildet; ein generischer Code an einer Ebenengrenze ist ein Fehler, keine Klassifikation.
2. Katalogeinträge leben in skills/triage-error/failure_codes.json mit {code, layer, match[], cause, next_command, recoverable, not_this[]}. Das Matching ist deterministisch: Normalisierung ist genau " ".join(text.lower().split()) (Kleinbuchstaben, alle Leerzeichenläufe auf einzelne Leerzeichen reduziert, Enden getrimmt); ein Eintrag matcht, wenn IRGENDEINER seiner match[]-Tokens (ebenfalls kleingeschrieben) ein Teilstring des normalisierten Signals ist; wenn --layer angegeben ist, werden Einträge mit einem anderen layer übersprungen; der ERSTE passende Eintrag in Dateireihenfolge gewinnt. Niemals Regex, niemals LLM-Urteil. Als terminale Klassifikationen verboten (sie sind Symptome, keine Ursachen, und müssen aus dem zugrunde liegenden Signal erneut triagiert werden): NEEDS_ATTENTION, BLOCKED, browser_handler_timeout, unknown_error, generic_failure, und jedes bloße terminale Urteilswort.
3. Ungepaarte Signale prägen <layer-or-unknown>_unclassified_<8hex>, wobei die 8 Hex-Zeichen die ersten 8 von sha256 über den normalisierten Signaltext sind, sodass dasselbe Signal immer denselben Code prägt. Prägen öffnet den Ticket- + agentic-eval- + Memory-Loop. Wiederholungsschwelle: Die ZWEITE Beobachtung desselben geprägten Codes löst Promotion oder Aliasing aus. Alias-Darstellung: Eine aliases-Map auf oberster Ebene in der Katalogdatei bildet geprägten Code -> kanonischen Code; da das Prägen über dem normalisierten Signal deterministisch ist, prägt ein wiederkehrendes Signal denselben Code neu und der Klassifikator löst ihn über die Map zum kanonischen Eintrag auf (aufgezeichnet als aliased_from); der geprägte Code ist niemals eine zweite kanonische Identität. Die Ticket-/Eval-/Memory- Seiteneffekte sind idempotent pro geprägtem Code (schlüsselgebunden an die Code-Zeichenfolge).
4. Jede Ökosystem-Komponente, die einen Fehler benennt, verwendet einen Katalog- oder geprägten Code. Sowohl pydantic-Validatoren (Statusschema, Envelope) setzen dies zur Parse-Zeit durch, sodass eine mehrdeutige Bezeichnung in einem gültigen Objekt nicht existieren kann.

Design-Entscheidungen (aus dem externen Review)

1. Strenge gilt für ENTSCHEIDUNGEN, nicht für Beobachtungen. Behalten Sie rohe Beweise permissiv; halten Sie akzeptierte Ergebnisse streng. Eine typisierte unknown-Beobachtung ist legal; eine mehrdeutige Entscheidung nicht.
2. Geprägte *_unclassified_*-Codes erhalten einen vorläufigen Lebenszyklus: Promoten Sie sie zum Katalog oder aliassen Sie zu einem vorhandenen Code, wenn sie wiederkehren; lassen Sie sie niemals ausufern.
3. Schemaänderungen sind additiv; brechende Formänderungen erhalten eine neue Version (tau.agent_handoff.v2-Muster), niemals direkte Änderungen.
4. Bauen Sie nicht: einen universellen Governance-Ereignisbus; Receipts für ponytail-Kommentare, Memory-Abrufe oder interne Wiederholungen.

Mitgliedschaft

Eine Fähigkeit oder Erweiterung tritt dem Ökosystem bei, indem sie einen ## Ecosystem-Abschnitt zu ihrer SKILL.md hinzufügt, der benennt: welche Schemas sie produziert, welche sie konsumiert und welche Grenzereignisse sie in den Envelope verpackt. Aktuelle Mitglieder: shame, triage-error, tau, ask, project-watchdog, ops-herdr. Ponytail ist konstruktionsbedingt benachbart.