grahama1970/agentic-evals

Was macht agentic-evals?

Verwenden Sie dieses Skill, wenn ein einfacher einmaliger Smoke-Test zu schwach ist und die Aufgabe eine wiederholbare, evidenzbasierte Bewertung eines Skills oder eines Agent-Workflows erfordert.

Aktueller Umfang

Dieses anfängliche Paket bietet einen deterministischen Testläufer (Fixture Runner) für befehlsbasierte Fälle. Es führt jeden Fall mehrfach aus, zeichnet stdout/stderr/Exit-Status und Dauer auf, überprüft explizite Erwartungen und gibt eine maschinenlesbare Bereitschaftszusammenfassung aus.

Dies beweist nur das deklarierte Verhalten des Testlaufs. Es beweist keine semantische Korrektheit, keine reale Service-Integration, keine LLM-Judge-Qualität und keine Release-Bereitschaft, es sei denn, die Testbefehle selbst durchlaufen diese Live-Pfade.

Verwendung

./run.sh run fixtures/agentic_eval.json
./run.sh run fixtures/agentic_eval.json --output /tmp/agentic-evals-report.json
./run.sh audit-skills ../ --output /tmp/agentic-evals-baseline-gap-report.json
./run.sh scaffold-fixture ../some-skill --output ../some-skill/fixtures/agentic_eval.json
./run.sh apply-scaffolds ../ --write --output /tmp/agentic-evals-apply-scaffolds.json
# Planung requirements-to-journey mittels Live-Erkundung (Issue #1629)
./run.sh plan-journeys --fixture fixtures/agentic_eval.json \
  --requirements requirements.json \
  --interaction-inventory discovery/discovery-inventory.json \
  --state-graph discovery/state-graph.json \
  --output journey-plan.json [--scaffold-output fragment.json] [--report-only]
# Anspruch / Evidenz / Regression / Abdeckung (Issues #1445-#1448)
./run.sh regressions audit ../ --output /tmp/agentic-evals-regressions.json
./run.sh regressions show . && ./run.sh regressions verify .
./run.sh coverage audit ../ --output /tmp/agentic-evals-coverage.json
./run.sh coverage show .

Anspruchsbasierte Bereitschaft (#1445)

Deterministische Tests beweisen Mechanismen; echte E2Es beweisen Fähigkeiten. Ein Stapel von grünen deterministischen Fällen darf niemals wie Bereitschaft für eine Live-Fähigkeit aussehen, die nie ausgeübt wurde. Die Bereitschaft wird daher pro deklariertem Fähigkeitsanspruch (capability claim) berechnet und dann aggregiert – nicht aus einer Fallanzahl.

Deklarieren Sie capability_claims (getrennt von der claims Beweisumfangs-Prosa gehalten, damit v2-Fixtures gültig bleiben). Jeder Fall, der einen Anspruch unterstützt, kennzeichnet sich selbst:

{
  "capability_claims": [
    {"id": "ask.roundtable.mixed_provider", "description": "...",
     "criticality": "critical",
     "evidence_required": {"deterministic": true, "live_e2e": true}}
  ],
  "cases": [
    {"name": "roundtable-live", "type": "positive", "evidence_class": "live_e2e",
     "supports_claims": ["ask.roundtable.mixed_provider"],
     "command": ["bash", "run.sh", "..."],
     "expected": {"exit_code": 0, "artifacts": [{"path": "out/join.json", "json_pointer": "/settled", "equals": true}]}}
  ]
}

Evidenzklassen: deterministic, property_or_fuzz, fault_injected_deterministic, live_e2e, adversarial_live_e2e, human_evaluation. Pro-Anspruchs-Urteile: PROVEN, PARTIALLY_PROVEN, BLOCKED_EXTERNAL, FAILED, NOT_ESTABLISHED. Ein Skill ist nur dann READY, wenn jeder erforderliche kritische Anspruch gemäß seiner eigenen Evidenzanforderungen PROVEN ist. Wenn Ansprüche deklariert sind, ist das Tor von run das schlechtere aus der fallbasierten und der anspruchsbasierten Bereitschaft, sodass zwanzig grüne deterministische Fälle mit einem unerfüllten erforderlichen live_e2e-Slot nicht READY erreichen können. Ein Live-Fall, der mehr als einen Anspruch unterstützt, muss unabhängige, pro-claim spezifische Artefakte mitführen, sonst zählt er für keinen von ihnen. report["capability_readiness"] enthält die Aufschlüsselung pro Anspruch.

Aus Invarianten abgeleitete Ansprüche (niemals eine Antwort stuben) – Operator 2026-09-11

Der oai-Test wurde durch eine Auslassung verloren: Die Anforderung "keine PII gelangt in die Ausgabe" wurde stillschweigend auf "keine PII-Zeichenketten gelangen in die Ausgabe" verengt. Jede Bewertung, jeder Prüfer und jeder Qualifikationslauf bewies die verengte Behauptung als grün, während ganzzahlige Telefonnummern unberührt durchkamen. Der Kunde las die Invariante im Domänenkontext; wir bewiesen sie im Mechanismuskontext. REGELN:

1. Ansprüche werden aus der Domäneninvariante abgeleitet, nicht daraus, was der Code bereits tut. Bevor Sie capability_claims deklarieren, schreiben Sie die Invariante in den Worten des Kunden ("kein X gelangt in IRGENDEINER Darstellung in die Ausgabe") und deklarieren Sie diese – wörtlich – als den kritischen Anspruch. Ein Anspruch, der das aktuelle Verhalten beschreibt, ist eine Stube.
2. Eine Darstellungsmatrix ist für werttragende Ansprüche obligatorisch. Jeder Anspruch über Datenwerte (PII, Geld, Identifikatoren, Geheimnisse) muss die Darstellungen auflisten, die das Eingabeformat zulässt – JSON string/int/float/wissenschaftliche Notation, CSV-Zitierung, SQL-Typen – und mindestens einen adversarischen Fall pro Darstellung enthalten, der jeweils fehlschlagen kann. Ein Wertanspruch ohne Darstellungsmatrix kann nicht PROVEN sein.
3. Eine Abdeckungsnaht namens value-representation (Kritikalität: critical) ist für jede Pipeline erforderlich, die Datenwerte transformiert, filtert oder schwärzt. Das Audit muss eine fähige Wache an dieser Naht zeigen.
4. Unabhängige Prüfer dürfen nicht den Datengenerator des Erzeugers teilen. Die Fixtures des Prüfers müssen Darstellungen enthalten, die die eigenen Fixtures der Transformation nicht enthalten, sonst ist die Unabhängigkeit nominell.
5. Wenn eine Darstellungslücke ausgeliefert wird, erfassen Sie sie in fixtures/regressions.json (Vorfall → beibehaltene Wache) und in der Naht value-representation – die gleiche Art von Fehler muss für immer danach erkennbar sein.

Der Anti-Slop-Vertrag lehnt selbstgefällige Klempnerarbeit ab; diese Regeln lehnen selbstgefällige Annahmen ab – die Testsuite, die ehrlich, adversarisch, mehrfach durchgeführt und dennoch blind ist, weil jedes Fixture eine unsichtbare Vorbedingung über die Form der Daten teilt.

Vertrag für echte End-to-End-Evidenz (#1446)

evidence_class wird nicht aus einem Befehl gefolgert, der run.sh oder curl enthält. Ein Fall, der eine Live-Klasse deklariert (live_e2e/adversarial_live_e2e), wird strukturell qualifiziert und herabgestuft (niemals stillschweigend akzeptiert), wenn er:

• sich selbst mit fixtures//Stub/mocked-Eingaben als Grenzautorität versorgt;
• keinen substantiellen Produktionseinstiegspunkt erreicht;
• kein unabhängiges Readback-Orakel hat (expected.artifacts, readback: true oder stdout_excludes) – ein Exit-Code plus die eigene Erfolgsprosa des Befehls ist kein Beweis; oder
• Live-Evidenz für $ask-Browser-tau-dag/compete-Handler beansprucht ohne --execute und Readback aus Browser-/Provider-Lauf-Artefakten wie node-receipt.json, response.md, response.meta.json, browser-tab-lifecycle.json, execution-status.json, roundtable-summary.md oder compete-scorecard.json. Compile-/Preflight-only-$ask-Fälle sind deterministische Mechanismusevidenz, niemals live_e2e.

Ein herabgestufter Fall wird zu fault_injected_deterministic (Fehler auf einem realen Pfad) oder deterministic, und der Bericht zeichnet evidence_disqualifiers auf. Ein erforderlicher Live-Slot, der nur durch einen BLOCKED_EXTERNAL-Fall erfüllt wird, hinterlässt den Anspruch als nicht-PROVEN.

Ausnahmen sind explizit und befristet. Ein Anspruch kann exemptions mit evidence_class, reason_code, justification, owner und expires enthalten. Eine gültige Ausnahme wird im Bericht aufgeführt (exempt_evidence), macht einen Anspruch aber nie PROVEN; eine abgelaufene oder unvollständige Ausnahme wird ignoriert. Keine pauschale eval_not_required erfüllt eine ausführbare operationelle Fähigkeit.

Vorfall → beibehaltene Regression (#1447)

Ein Live-Fehler wird zu einem dauerhaften Beweis in fixtures/regressions.json (agentic_evals.regressions.v1). Jeder Datensatz verknüpft den Vorfall mit den Ansprüchen und Nähten, die er bedrohte, benennt den beibehaltenen Wache-Fall (retained_case / retained_fixture) und führt einen fail_before_fix.proof_command mit.

• regressions show <skill> / regressions audit <root> berichtet: ungeschützte Regressionen (beibehaltener Fall fehlt/umbenannt), niemals bewiesene (möglicherweise leere) Regressionen, veraltete Live-Beweise, zurückgezogene Regressionen und offene Vorfälle ohne Regression-Mapping.
• regressions verify <skill> führt jeden Beweisbefehl erneut aus und bestätigt, dass die Wache tatsächlich gegen das fehlerhafte Verhalten fehlschlägt (mit Exit-Code ungleich Null) – ein Nicht-Leerheitsbeweis, kein selbstberichtetes Flag. Es beendet sich mit Exit-Code ungleich Null, wenn die Wache einer aktiven Regression nicht das Fehlschlagen-vor-der-Korrektur demonstrieren kann.

Einen Fehler durch Bearbeiten der Evaluierungserwartung an die fehlerhafte Ausgabe zu beheben, ist genau das, was der Nicht-Leerheitsbeweis abfängt. Die Zurückziehung einer Regression erfordert einen retirement-Grund.

Risikobasierte Abdeckungsangemessenheit (#1448)

Das Zählen von Fällen ist manipulierbar. coverage audit/coverage show fragen pro deklarierter seam: Gibt es mindestens einen Fall, der in der Lage ist, eine Regression an dieser Naht zu erkennen, in jeder Evidenzklasse, die das Risiko der Naht erfordert? Deklarieren Sie seams mit seam_id, seam_type, criticality und required_evidence; kennzeichnen Sie Fälle mit seams. Ein Fall deckt eine Naht nur ab, wenn er diese Naht auflistet und ein Orakel mitführt, das fehlschlagen kann – ein bloßer exit 0-Positivtest ist weak_only und zählt nicht. Das Audit berichtet abgedeckte/unabgedeckte Nähte, Weak-Only-Abdeckung, Live- vs. deterministische Abdeckung, kartierte Vorfallsregressionen und priorisierte nächste Evaluierungen. Abdeckung (eine leistungsfähige Wache ist deklariert) und Aktualität (ein Live-Beweis ist aktuell) sind getrennte Dimensionen; der Läufer führt die Nahtfälle hier nicht aus.

Fixture-Vertrag

{
  "version": 2,
  "skill": "example-skill",
  "trials": 3,
  "proof_scope": "fixture wiring smoke",
  "claims": {
    "proves": "the declared command exits with the expected status",
    "does_not_prove": "semantic correctness, live service behavior, or full skill readiness"
  },
  "cases": [
    {
      "name": "happy-path",
      "type": "positive",
      "command": ["echo", "success"],
      "expected": {
        "exit_code": 0,
        "stdout_contains": ["success"]
      }
    }
  ]
}

Jeder Fall muss deklarieren:

• name
• type: positive, negative oder adversarial
• command: eine nicht-leere Argumentliste
• expected.exit_code

Optionale Erwartungen:

• expected.stdout_contains
• expected.stderr_contains
• must_exercise: Liste von Teilzeichenfolgen stromabwärtiger Vertragsbefehle, die im Top-Level-Befehl des Falls vorkommen müssen. Verwenden Sie dies, wenn ein Wrapper sonst Erfolg vortäuschen könnte; beispielsweise muss eine Evaluierung, die $ticket/$project-watchdog-Routingfähigkeit beansprucht, "skills/ticket/run.sh feature" enthalten, nicht nur ein Hilfsskript, das OK ausgibt.

Anti-Slop-Vertrag (fail-closed)

Ein Skill-Evaluierungs-Fixture wird zur Ladezeit ZURÜCKGEWIESEN (Exit-Code ungleich Null, kein Durchlauf), wenn es sich um selbstgefällige deterministische Klempnerarbeit und nicht um einen realen Beweis handelt. Um zu bestehen, MUSS ein Skill-Fixture:

• trials >= 2 setzen (ein einzelner Durchlauf ist keine Evidenz);
• mindestens einen negative- oder adversarial-Fall enthalten (ein reines Positiv-Fixture ist selbstgefällig);
• mindestens einen realen Fall enthalten: "real_world": true, dessen Befehl einen Live-Pfad ausübt (das run.sh des Skills / ein Skript / Live-HTTP / ein Testläufer) und sich NICHT selbst mit fixtures/-Stub-Eingaben versorgt;
• keine trivialen echo/Konstanten-Fälle enthalten, die nichts beweisen.

Die Zurückweisungsmeldung nennt jeden Verstoß. Dies verhindert eine Evaluierung, die trivial besteht, während sie nichts darüber beweist, ob der Skill tatsächlich funktioniert.

Compliance-Stufe ("eval_tier": "compliance")

Ein Fixture, das eine Compliance-Pipeline-Stufe bewacht, deklariert "eval_tier": "compliance" und der Läufer verlangt dann den STRENGEN Vertrag zusätzlich zur Grundlinie (Operatorenanweisung 2026-08-12, "dies ist eine Compliance-Pipeline und muss robust gehärtet sein"). Ein solches Fixture wird ZURÜCKGEWIESEN, es sei denn:

• eine strenge Mehrheit der Fälle ist adversarial/negative (mehr als die Hälfte, nicht genau die Hälfte – positive Kontrollen sind die Minderheit);
• mindestens ein Fall ist nicht-deterministisch: sein Befehl sampelt jedes Mal frische Eingaben über --samples, --seed oder eine Shell $RANDOM (ein Prüf-Skript-Name mit einem festen Schlüssel zählt nicht);
• jeder nicht-deterministische Fall benennt --samples >= 50, sodass die Abdeckung jeder Stufe hunderte bis tausende Behauptungen pro Lauf beträgt, mit dem Ziel von ~1000 pro Stufe über ihre Modi hinweg.

Die Deklaration kann nicht stillschweigend gelockert werden: Die eigenen Fixtures der Compliance-Pipeline setzen die Stufe, sodass das Entfernen zur Umgehung des Tores selbst eine Regression ist. tests/test_compliance_tier_gate.py fixiert jede Regel gegen ihre Abschwächung.

Zwei ehrlich deklarierte Ausnahmen umgehen das Tor – niemals gültig für eine echte Skill-Evaluierung:

• "eval_kind": "runner_selftest" – ein Fixture, das diesen Läufer selbst testet oder ein Dokumentationsbeispiel ist.
• "eval_kind": "scaffold" – das mechanische Ersteinsatz-Fixture, das von scaffold-fixture / apply-scaffolds ausgegeben wird, das das Audit immer noch als benötigend echter Fälle kennzeichnet.

Bereitschaftszuordnung

Die Bereitschaft wird nur über erforderliche Fälle bewertet ("required": false optiert einen Fall aus). Ein erforderlicher BLOCKED-Fall kann READY nicht erreichen: Eine unerfüllte Vorbedingung ist Abwesenheit von Evidenz, nicht Evidenz von Erfolg.

• READY: Jeder erforderliche Fall hat jeden Durchlauf bestanden.
• USABLE_WITH_GAPS: Mindestens ein Durchlauf bestanden und mindestens einer nicht.
• NOT_READY: Durchläufe ausgeführt, aber kein erforderlicher Fall vollständig bestanden.
• NOT_ESTABLISHED: Keine Fälle ausgeführt.

Fail-closed-Exit

run beendet sich mit Exit-Code ungleich Null, es sei denn, die Bereitschaft ist READY. Ein Läufer, der mit USABLE_WITH_GAPS mit Exit-Code 0 endet, lässt einen äußeren CI-Job über fehlgeschlagene Fälle grün werden, was genau das Versagen ist, das dieses Tor verhindern soll. Verwenden Sie --report-only, wenn Sie den Bericht ohne das Tor wünschen.

Fallergebnisse

Jeder Fall meldet ein outcome, da diese für ein Tor unterschiedliche Bedeutungen haben:

Ergebnis	Bedeutung
PASS	jeder Durchlauf hat jede Erwartung erfüllt
FAIL	ein Fehler, oder ein Timeout, oder ein Durchlauf, der einen Kindprozess hinterlassen hat
BLOCKED	eine Vorbedingung war unerfüllt; deklarieren Sie Markierungen via blocked_when_stdout_contains
NOT_TESTED	keine Durchläufe ausgeführt

Artefakt-Behauptungen

Die Substring-Übereinstimmung von stdout kann nicht ausdrücken "diese beiden Quittungen nennen dieselbe Sitzung" oder "der Lauf hat nichts hinterlassen". Deklarieren Sie expected.artifacts:

"expected": {
  "exit_code": 0,
  "artifacts": [
    {"path": "out/session.json", "json_pointer": "/sessionId",
     "equals_artifact": {"path": "out/detach.json", "json_pointer": "/sessionId"}},
    {"path": "out/attach.json", "json_pointer": "/sessionId",
     "is_artifact": true},
    {"path": "out/cleanup.log", "exists": false}
  ]
}

Unterstützte Prüfungen:

• json_pointer + equals (literaler Wert / true / false / Zahl / null)
• json_pointer + equals_artifact (ein anderer JSON-Pfad im selben Lauf)
• json_pointer + is_artifact (einfach prüfen, ob das Feld existiert)
• exists (true/false) – Datei existiert oder nicht
• content_regex – regulärer Ausdruck gegen den Dateiinhalt
• content_excludes – Zeichenfolge darf nicht im Inhalt vorkommen

Qualifikationsverfolgung (#1629)

Das Markieren von Fällen mit einer Qualifikationsstufe:

{
  "qualification": {
    "required_up_to": "simulated",
    "required_for": ["integration-test-suite-v2"]
  }
}

Werte: system_test (echte Live-Ausführung mit allen realen Abhängigkeiten), full_integration (echte Systeme, aber mit simulierten Grenzen), simulated (vollständig simuliert), unit (isolierter Logiktest), not_required. Der Bericht gruppiert Fälle nach ihrer höchsten bestandenen Stufe, sodass ein system_test-Lauf die integration-Stufe nicht aufgrün macht, wenn er nicht ausgeführt wurde.

Erzwungene Anforderungspfade (#1629, Forts.)

Wenn Ihr Lauf --require-system-test angibt, wird jeder erforderliche Fall, dessen qualification.required_up_to auf system_test gesetzt, aber nicht erreicht ist, als BLOCKED mit dem Grund "MISSING_SYSTEM_TEST" gemeldet – selbst wenn er in einem niedrigeren Modus bestanden wird. Dies verhindert, dass eine Pipeline einen „systemgetesteten“ Auslieferungsblock auf der Grundlage von simulierten Läufen grün macht.

Pfadverfolgung (#1444)

Jeder Fall kann deklarieren, dass bestimmte Befehle oder Dateien während des Laufs berührt werden müssen. Wenn ein Fall expected.must_exercise setzt, prüft der Läufer (über ptrace/DTrace, sofern verfügbar, oder über Shell-Protokollierung), dass die Unterprozesse die angegebenen Zeichenfolgen tatsächlich ausgeführt haben.

{
  "name": "routing-exercise",
  "must_exercise": ["skills/ticket/run.sh", "skills/project-watchdog/run.sh"],
  "command": ["bash", "run.sh", "feature"],
  "expected": {"exit_code": 0}
}

Dies verhindert, dass ein Eval-Wrapper einfach echo "OK" ausgibt, anstatt die echten Skills aufzurufen, die er zu testen vorgibt.

Verhaltensgesteuerte Bedrohungsannahmen (#1630)

Ein Fall kann eine threat_assumption deklarieren:

{
  "name": "pii-redaction-adversarial",
  "type": "adversarial",
  "threat_assumption": {
    "model": "A user provides PII in a context where redaction is expected",
    "subverted_by": ["integer phone number", "obfuscated email"],
    "adversarial_goal": "PII passes through unredacted due to representation mismatch"
  },
  "command": ["bash", "run.sh", "--input", "fixtures/adversarial/pii_representations.json"],
  "expected": {
    "exit_code": 0,
    "stdout_contains": ["REDACTED"],
    "artifacts": [{"path": "output.json", "json_pointer": "/pii_matches", "equals": 0}]
  }
}

Dies macht das Bedrohungsmodell explizit und überprüfbar und verhindert, dass ein Prüfer „PII-Redaktion bestanden“ meldet, während er nur eine einzelne Darstellung getestet hat.

Automatisierte Befehlszeilendokumentation

Führen Sie ./run.sh --help für die vollständige Befehlszeilendokumentation aus.