Standard für Evidence-basierte Qualitätssicherung und Agent-exekutierbare Verifikation

Gültigkeitsbereich: Alle Governance-Arbeiten, die - sofern im Repository genutzt - über .sisyphus/plans/*.md oder eine projektspezifisch definierte Plan-Ablage strukturiert sind
Version: 1.0
Letzte Aktualisierung: 2026-02-19

Dieses Protokoll definiert den verbindlichen Standard für Evidence-Dateien in Governance-Projekten. Es stellt sicher, dass Aufgaben nachweisbar abgeschlossen, reproduzierbar verifiziert und langfristig auditierbar sind.

Kernprinzip: Keine Aufgabe ist ohne Evidence-Dateien abgeschlossen.

Pattern:

task-{N}-{scenario-slug}.{ext}

Komponenten:

Regex (für Validierung):

^task-\d{1,3}-[a-z0-9]+(-[a-z0-9]+)*\.(txt|json|log|md)$

Valide Beispiele:

.sisyphus/evidence/task-4-gate-matrix.txt
.sisyphus/evidence/task-10-branch-protection.json
.sisyphus/evidence/task-15-preview-cleanup-error.txt

Invalide Beispiele:

.sisyphus/evidence/task4_check.txt          (Unterstrich statt Bindestrich)
.sisyphus/evidence/branch-protection.txt    (Aufgabennummer fehlt)
.sisyphus/evidence/task-4-check              (Dateierweiterung fehlt)
.sisyphus/evidence/TASK-4-gate-matrix.txt   (Großbuchstaben in Task)

Datei: task-8-concurrency-cap.txt

max_active_previews: 10
priority_queue_max: 5
idle_ttl_days: 7
destroy_ttl_days: 14

// Datei: task-10-branch-protection.json
{
  "required_status_checks": {
    "strict": true,
    "contexts": [
      "Lint / lint",
      "Unit / unit",
      "Types / types",
      "Coverage and Quality Gates / Coverage Gate",
      "Coverage and Quality Gates / Complexity Gate",
      "Coverage and Quality Gates / PR Integration Gate",
      "App E2E Smoke / App E2E Smoke"
    ]
  }
}

Datei: task-12-migration-coverage.log

[2026-02-19T18:00:00Z] Starting validation...
[2026-02-19T18:00:01Z] Checking dual-handling section...
[2026-02-19T18:00:02Z] PASS: Dual-handling documented
[2026-02-19T18:00:03Z] Checking cutover-deadline...
[2026-02-19T18:00:04Z] PASS: Cutover deadline = 30 days

<!-- Datei: task-6-comparison-matrix.md -->

| Kriterium | Vercel | Self-Hosted |
|-----------|--------|-------------|
| Setup     | 5      | 3           |
| Security  | 4      | 5           |
| Isolation | 4      | 5           |

No Evidence → No Done

Eine Aufgabe gilt als NICHT ABGESCHLOSSEN, wenn nicht für jedes QA-Szenario eine entsprechende Evidence-Datei existiert.

1. Erstellung: Jedes QA-Szenario in der Aufgabendefinition MUSS eine Evidence-Datei produzieren.
2. Staging: Evidence-Dateien MÜSSEN zusammen mit den Deliverables gestaged und committed werden.
3. Verifikation: Der Orchestrator MUSS vor dem Markieren der Checkbox die Existenz aller Evidence-Dateien prüfen.

• Vermeidung von "Done, but broken": Claims ohne Nachweis führen zu Folgefehlern.
• Audit-Trail: Evidence-Dateien schaffen eine nachprüfbare Historie für Compliance.
• Reproduzierbarkeit: Andere Agenten oder zukünftige Reviews können Ergebnisse eigenständig validieren.

QA-Szenarien:

1. Gate-Matrix vollständig → .sisyphus/evidence/task-4-gate-matrix.txt (ERFORDERLICH)
2. Broken-Main-Error-Handling dokumentiert → .sisyphus/evidence/task-4-broken-main-error.txt (ERFORDERLICH)

Status ohne beide Dateien: Task 4 = INCOMPLETE, auch wenn docs/governance/merge-review-gates.md existiert.

Keine Ausnahmen. Wenn ein Szenario keine Evidence produzieren kann, ist das Szenario fehlerhaft und muss überarbeitet werden.

Verantwortlich: Subagent (z. B. Sisyphus-Junior)

1. Szenario ausführen: Kommando oder Check gemäß QA-Szenario-Definition durchführen.
2. Output erfassen: Ergebnis in Evidence-Datei mit korrektem Naming speichern.
3. Stagen: Evidence-Datei mit git add zu Deliverables hinzufügen.

Beispiel:

# Szenario: Concurrency Cap validieren
grep -E "max_active_previews|priority_queue_max" docs/governance/preview-cost-capacity-guardrails.md \
  > .sisyphus/evidence/task-8-concurrency-cap.txt

git add .sisyphus/evidence/task-8-concurrency-cap.txt

Verantwortlich: Orchestrator (z. B. Atlas)

1. Existenzprüfung: Prüfen, ob Evidence-Datei unter .sisyphus/evidence/task-{N}-{slug}.{ext} existiert.
2. Inhaltsvalidierung: Evidence-Inhalt gegen erwartete Kriterien prüfen (z. B. Regex-Match, JSON-Schema, Mindest-Zeilenanzahl).
3. Entscheidung:
   • PASS: Task als abgeschlossen markieren (Checkbox setzen).
   • FAIL: Subagent-Session wiederaufnehmen, Nachbesserung verlangen.

Beispiel:

# Prüfen, ob task-8-concurrency-cap.txt existiert und relevante Werte enthält
test -f .sisyphus/evidence/task-8-concurrency-cap.txt && \
  grep -qE "max_active_previews: [0-9]+" .sisyphus/evidence/task-8-concurrency-cap.txt

Verantwortlich: Orchestrator oder Subagent (je nach Workflow)

1. Commit: Evidence-Dateien zusammen mit Governance-Dokumenten committen.
2. Referenz: In Final Verification (F1-F4) auf Evidence-Dateien verweisen.
3. Retention: Evidence-Dateien niemals löschen nach Commit (permanente Aufbewahrung für Audits).

Git-Historie: Evidence-Dateien bleiben dauerhaft in Git-History für Compliance-Nachweise verfügbar.

Pfad: .sisyphus/evidence/ (flat structure), sofern dieses Evidence-Schema im Projekt initialisiert wurde; andernfalls ist die im Projekt definierte gleichwertige Ablage zu verwenden.

Rationale:

• Einfache Glob-Patterns (task-*.txt)
• Keine verschachtelten Ordner pro Task (verhindert Fragmentierung)
• Alle Evidence-Dateien eines Plans an einem Ort

Regel: Evidence-Dateien werden niemals gelöscht nach Commit.

Begründung:

• Audit-Trail für Governance-Compliance
• Reproduzierbarkeit für zukünftige Reviews
• Git-Historie als Single Source of Truth

Gesamt: 28 Evidence-Dateien (14 Tasks × 2 Szenarien durchschnittlich)
Format-Verteilung: 27× .txt, 1× .json

Beobachtungen:

• Alle Dateinamen folgen task-{N}-{slug}.{ext} (100% Konformität)
• Extensions: Überwiegend .txt (einfache Validierungen), .json für GitHub API Response (T10)
• Szenarien pro Task: Mindestens 2 (1× positive Validierung, 1× Error/Edge-Case)

Regex-basierte Prüfung:

# Alle Evidence-Dateien prüfen
for file in .sisyphus/evidence/task-*.*; do
  if ! echo "$file" | grep -qE "^\.sisyphus/evidence/task-[0-9]{1,3}-[a-z0-9]+(-[a-z0-9]+)*\.(txt|json|log|md)$"; then
    echo "INVALID: $file"
  fi
done

Beispiel (für Plan mit 2 Szenarien pro Task):

# Erwartete Evidence-Dateien für Task 4
expected_files=(
  ".sisyphus/evidence/task-4-gate-matrix.txt"
  ".sisyphus/evidence/task-4-broken-main-error.txt"
)

for file in "${expected_files[@]}"; do
  if [[ ! -f "$file" ]]; then
    echo "MISSING: $file"
    exit 1
  fi
done

Optional: Hook, der vor Commit prüft, ob alle Evidence-Dateien für gestaged Governance-Dokumente vorhanden sind.

Format:

## QA-Szenarien

1. **[Positive Validation Scenario]**
   - Evidence: `.sisyphus/evidence/task-{N}-{slug}.{ext}`
   - Muss: [Erwartetes Ergebnis mit messbarem Kriterium]

2. **[Error/Edge-Case Scenario]**
   - Evidence: `.sisyphus/evidence/task-{N}-{slug}-error.{ext}`
   - Muss: [Erwartetes Fehlerverhalten oder Edge-Case-Handling]

Beispiel (Task 10):

## QA-Szenarien

1. **Branch-Protection Required Checks vollständig**
   - Evidence: `.sisyphus/evidence/task-10-branch-protection.json`
   - Muss: JSON enthält die konfigurierten Required Checks inkl. `Coverage and Quality Gates / Coverage Gate`

2. **Merge-Queue Bypass-Regel dokumentiert**
   - Evidence: `.sisyphus/evidence/task-10-merge-queue-error.txt`
   - Muss: Bypass nur für P0/P1 mit Incident-Referenz-Pflicht

Problem: "Branch Protection Required Checks" → required-checks oder branch-protection?

Lösung: Slug sollte aus den relevanten Keywords des Szenarios abgeleitet werden, die das spezifische Artefakt beschreiben:

• "Branch Protection Required Checks" → branch-protection (da JSON = Branch-Protection-Snapshot)
• "Merge-Queue Bypass-Regel" → merge-queue-error (da Fehlerfall = Bypass-Regel)

Problem: Datei ohne Extension (task-4-check)

Lösung: Extension ist verpflichtend. Immer mindestens .txt verwenden.

Problem: Orchestrator markiert Task als done, obwohl Evidence-Dateien fehlen.

Lösung: Orchestrator-Verifikation muss zuerst Evidence-Existenz prüfen, bevor Checkbox gesetzt wird.

Für .json-Evidence-Dateien kann ein JSON-Schema definiert werden, um strukturierte Validierung zu ermöglichen.

Beispiel:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["required_status_checks"],
  "properties": {
    "required_status_checks": {
      "type": "object",
      "required": ["contexts"],
      "properties": {
        "contexts": {
          "type": "array",
          "minItems": 5,
          "items": { "type": "string" }
        }
      }
    }
  }
}

Optionale Header in Evidence-Dateien für bessere Nachvollziehbarkeit:

# Evidence Metadata
# Task: T10
# Scenario: Branch-Protection Required Checks vollständig
# Generated: 2026-02-19T18:30:00Z
# Command: gh api repos/owner/repo/branches/main/protection

{...}

Kernanforderungen:

1. Naming: task-{N}-{scenario-slug}.{ext} (deterministisch, Regex-validierbar)
2. Extensions: .txt, .json, .log, .md (nach Artefakttyp)
3. Completion Rule: Keine Evidence → Keine Aufgabe als abgeschlossen markierbar
4. Lifecycle: Erstellung → Validierung → Archivierung (permanent)

Erfolgsmetriken:

• 100% Evidence-Coverage für alle QA-Szenarien
• 0% Tasks mit fehlenden Evidence-Dateien nach Completion
• 0% Evidence-Dateien mit ungültigem Naming

Nächste Schritte:

• Orchestrator-Integration: Automatisierte Existenzprüfung vor Checkbox-Markierung
• Git-Hooks: Optional Pre-Commit-Hook für Evidence-Vollständigkeit