.kanman/acceptance.json

Das Akzeptanz-Manifest sagt kanman, wie eine Story in Ihrem Repository belegt wird. Es liegt unter .kanman/acceptance.json im Wurzelverzeichnis des Repositorys. Damit kann kanman das Outcome-Gate ausführen: Es schreibt für jede Story eine ausführbare Akzeptanz-Spec, prüft, dass die Spec fehlschlägt, bevor es Code gibt, und prüft, dass sie nach der Änderung auf einem frischen Checkout besteht.

kanman bleibt unabhängig vom Repository. Das Manifest legt die Befehle fest, kanman führt sie in einer frischen Umgebung aus. Secrets bleiben in Ihren CI-Einstellungen und gehören nie ins Manifest.

Eine Schritt-für-Schritt-Einführung finden Sie unter Akzeptanz-Manifest anlegen. Den lokalen Prüfbefehl beschreibt .kanman/verify.json.

Beispiel

Das ist das Manifest des öffentlichen Demo-Repositorys kanman-ai/pilot-sandbox, eines kleinen TypeScript-Dienstes mit Playwright-Specs:

{
  "version": 1,
  "provision": {
    "type": "docker_compose",
    "file": "docker-compose.acceptance.yml",
    "up": "docker compose -f docker-compose.acceptance.yml up -d --build --wait",
    "down": "docker compose -f docker-compose.acceptance.yml down -v"
  },
  "ready_url": "http://localhost:3000/api/invoices",
  "ready_timeout_seconds": 120,
  "setup": "npm ci && npx playwright install --with-deps chromium",
  "run": {
    "command": "npx playwright test",
    "spec_arg": ".kanman/acceptance/{KEY}/",
    "env": {
      "BASE_URL": "http://localhost:3000"
    }
  },
  "spec_dir": ".kanman/acceptance/{KEY}",
  "artifacts": [
    "test-results/**/trace.zip",
    "test-results/**/*.png",
    "test-results/**/*.webm",
    "test-results/results.json",
    "playwright-report/**"
  ]
}

Für die Story SBX-12 führt kanman npx playwright test .kanman/acceptance/SBX-12/ gegen die mit Docker Compose gestartete App aus und speichert Trace, Screenshots, Video und JSON-Bericht als Nachweis.

Schlüssel auf oberster Ebene

Unbekannte Schlüssel werden ignoriert. Ein Manifest für eine neuere Version funktioniert also auch mit einem älteren Runner.

provision

provision.type wählt eine von zwei Formen.

Docker Compose

Für Anwendungen, die als ein oder mehrere Container starten.

Apply

Für Repositorys, die keine laufende App sind, zum Beispiel Infrastruktur oder Konfiguration. Der Nachweis ist das Apply-Log plus das, was Ihre Spec prüft.

Beispiel für ein Infrastruktur-Repository, das seine Module gegen einen lokalen Test-Stack prüft:

{
  "version": 1,
  "provision": {
    "type": "apply",
    "command": "make test-env-up > apply.log 2>&1",
    "down": "make test-env-down"
  },
  "ready_timeout_seconds": 600,
  "setup": "make tools",
  "run": {
    "command": "pytest",
    "spec_arg": ".kanman/acceptance/{KEY}/",
    "env": {
      "TEST_ENV": "acceptance"
    }
  },
  "spec_dir": ".kanman/acceptance/{KEY}",
  "framework": "pytest",
  "artifacts": ["apply.log", "reports/**/*.xml"]
}

run

Der vollständige Befehl für eine Story ist command, ein Leerzeichen und spec_arg mit eingesetztem {KEY}.

kanman setzt für den Durchlauf immer CI=true und KANMAN_STORY_KEY (den Story-Schlüssel). Werte aus run.env haben Vorrang.

Der Platzhalter {KEY}

{KEY} ist der Story-Schlüssel, den kanman auf der Story-Seite zeigt: das Schlüsselpräfix des Teams und eine Nummer, zum Beispiel SBX-12. Er wird in spec_dir und run.spec_arg ersetzt.

Der geschützte Spec-Ordner

Alles unter .kanman/acceptance/ gehört dem Spec-Autor von kanman:

• kanman schreibt die Spec aus dem Demonstrate-Block der Story, bevor die Story nach Ready wandert. Die Dateien müssen im eigenen Ordner der Story liegen (.kanman/acceptance/<KEY>/).
• Sobald die Spec wie erwartet fehlschlägt, committet kanman sie auf den Branch kanman/spec/<KEY>. Der Umsetzungs-Branch startet von dort, die Spec kommt also mit dem Pull Request.
• Die Implementierung ändert diese Dateien nie. Jedes Preset sperrt .kanman/acceptance/** für den Executor, und der Diff-Wächter stoppt den Run, falls ein Commit den Ordner trotzdem berührt oder der Ordner von der bei Ready freigegebenen Fassung abweicht.
• Eine Spec darf ihr eigenes Ziel nicht mocken. Netzwerk-Interception, MSW, nock und Modul-Mocks des geprüften Verhaltens machen die Spec ungültig.

Wie kanman das Manifest nutzt

Jeder Durchlauf bekommt einen frischen Checkout in einem eigenen Verzeichnis. down läuft nach jedem dieser Schritte, auch wenn die Spec fehlschlägt. Ein Durchlauf (Bereitstellung, Setup und Spec zusammen) darf höchstens 30 Minuten dauern.

Eine Spec, die nicht kompiliert, keine Tests findet oder den Test-Runner abstürzen lässt, zählt als Fehler, nicht als rot. Probleme, bevor die Spec startet (Klonen, Bereitstellung, Bereitschaftsprüfung, Setup), zählen als Umgebungsfehler; kanman wiederholt sie still, bevor es Sie fragt.

Validierungsfehler

kanman liest das Manifest von Ihrem Standard-Branch, wenn eine Story Richtung Ready wandert. Fehlt es oder ist es ungültig, bleibt die Story in der Verfeinerung, und die Story-Seite zeigt Das Repository hat keine .kanman/acceptance.json, daher kann keine Akzeptanzspezifikation laufen oder Das Akzeptanz-Manifest ist ungültig: mit dem Grund. Häufige Ursachen:

Repositorys ohne Manifest laufen nur mit dem Preset Testphase; mit jedem anderen Preset bleibt die Story in der Verfeinerung. kanman nutzt dann CI, den Testplan und den Reviewer-Run, und das Nachweispaket sagt deutlich, dass kein Ergebnisnachweis vorliegt.

Verwandte Seiten

• Das Outcome-Gate und Nachweise
• Akzeptanz-Manifest anlegen
• .kanman/verify.json
• Richtlinien-Einstellungen (require_acceptance_spec)