Führen Sie ein lokales oder break-glass-Szenario außerhalb des Containers aus:```bash
export SUPERPOWERS_ROOT=/path/to/superpowers
export ANTHROPIC_API_KEY=...
bun run quorum run scenarios/triggering-writing-plans --coding-agent claude
bun run quorum show <run-dir>

The `claude` agent's default credential is `opus`.

## Shared Eval Appliance

Shared remote live evals are designed to run from a trusted appliance host with one blessed credential bundle, exact repo/ref provenance, host locks, and recoverable job records. Agents should use the appliance helper once it exists on the configured host:```bash
evals-appliance doctor --json
evals-appliance prepare --json --superpowers-ref <branch-tag-or-sha>
evals-appliance run-all --json --detach \
  --superpowers-ref <branch-tag-or-sha> \
  -- --tier sentinel \
     --coding-agents claude,codex,kimi \
     --jobs 4
evals-appliance status --json <job-id>
evals-appliance show --json <job-id>
evals-appliance costs --json <job-id>
evals-appliance cancel --json <job-id>

Dann baue, starte und validiere den Container:```bash
scripts/evals-container build
scripts/evals-container down || true
scripts/evals-container --env-file .env.container up
scripts/evals-container exec evals-tool-versions
scripts/evals-container exec quorum check

Führen Sie dieselben Befehle ohne `--tier sentinel` für die vollständige einsatzbereite Suite aus.
`run-all` schreibt jeden Batch unter `results/batches/<batch-id>/` und jeden Durchlauf
unter `results/<scenario>-<agent>-<os>-<timestamp>-<nonce>/`; rendern Sie einen Batch
mit:```bash
scripts/evals-container exec quorum show <batch-id>

For grouped all-agent host sweeps, per-agent credentials, auth mount details,
and troubleshooting, use [docs/coding-agent-care-and-feeding.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/coding-agent-care-and-feeding.md).

## Windows-Laufzeit

Für Evaluierungen unter Windows 11 verwenden Sie `--os windows` (nur Linux+KVM-Hosts):```bash
bun run quorum run scenarios/<name> --coding-agent claude --os windows

`quorum check` validiert `credentials.yaml` und die `default_credential` jedes Agents.

Der Scheduler richtet seinen Parallelitätsdeckel und seinen Ratenbegrenzungsriegel am **limiterKey** der Zugangsdaten aus — der `base_url` der Zugangsdaten, sofern gesetzt, andernfalls der Name der Zugangsdaten, verknüpft mit seiner `api` (z. B. `https://…/v1|openai-chat` oder `opus|anthropic` für eine native Zugangsdaten ohne `base_url`).

Zellen, die einen limiterKey gemeinsam nutzen, teilen sich einen Deckel und einen Ratenbegrenzungsriegel: Eine Ratenbegrenzungsantwort auf eine Zelle überspringt sofort alle verbleibenden in der Warteschlange befindlichen Zellen für diesen Endpunkt.

Standardmäßig benannte Zugangsdaten (siehe `credentials.yaml`): `opus`, `sonnet`, `haiku` (Claude-Harness), `codex_sub` (Codex-Abonnement), `kimi_default`, `openrouter_glm_5_2` (Pi-Standard), `pi_default` (nativer Pi-OAuth-Opt-In), `opencode_gpt5`, `gemini_default`, `serf_default`, `glm_5_2_chat`, `glm_5_2_responses`, `ollama_local`.

### Externe Serf-Kampagnen

Kurzlebige Serf-Modell-/Provider-Kampagnen verwenden eine externe Zugangsdatendatei, nicht das kanonische `credentials.yaml` des Repositorys. Übergeben Sie sie explizit mit `--credentials-file` an `quorum run`, `quorum run-all` oder `quorum check`. Bewahren Sie das eigentliche Kampagnen-YAML und alle Rohausführungsartefakte außerhalb von Git auf: Das YAML enthält Routing-Labels und den ausgewählten API-Schlüssel-Umgebungsvariablennamen, niemals einen Schlüsselwert.

Jeder Kampagnenvorlage muss genau ein Modell und einen Anbieter festlegen, Fallbacks deaktivieren und keine Überschreibungen für Prompt, Sampling, Reasoning, Tool oder Token-Limit enthalten. Stellen Sie ihren dedizierten Schlüssel über das vertrauenswürdige Laufzeit-Zugangsdatenpaket bereit. Der Schlüssel muss die beabsichtigte Datenrichtlinie der Kampagne durchsetzen, ein Kampagnenausgabenlimit haben und für eine gemeinsame Kapazitätskampagne keine BYOK-Bindung aufweisen. Ein BYOK-Vergleich ist eine separate Kampagne mit einem separaten Schlüssel und einer Kandidatendatei.

Vor dem Dispatch parst `run-all` die externe Datei einmal und schreibt deren kanonischen Snapshot nach `results/batches/<batch-id>/credentials.snapshot.yaml`; jedes Kind erhält diesen unveränderlichen Snapshot. Ein direkter `quorum run` schreibt denselben kanonischen Snapshot in sein Ausführungsverzeichnis. Das Bearbeiten des Quell-YAML nach Batchstart kann spätere Zellen nicht ändern. Snapshots enthalten schema-bekannte Routing-Metadaten und Umgebungsvariablennamen, keine Geheimniswerte, aber sie bleiben Teil der sensiblen Ausführungsartefakte.

Führen Sie zuerst den agentenneutralen Smoke-Test durch, dann führen Sie das teure Szenario nur für Zugangsdaten aus, deren endgültiges Smoke-Urteil `pass` lautet:```bash
quorum run-all \
  --scenarios 00-quorum-smoke-hello-world \
  --include-drafts \
  --coding-agents serf \
  --credentials-file /secure/campaign.yaml \
  --credentials serf_example_a \
  --jobs 1

quorum run-all \
  --scenarios serf-builder-fractals \
  --coding-agents serf \
  --credentials-file /secure/campaign.yaml \
  --credentials serf_example_a \
  --jobs 1

`quorum check` mit keinen Argumenten validiert jedes Szenario und die `credentials.yaml`.
`run-all` führt jedes enthaltene Szenario gegen jeden ausgewählten Coding-Agent aus,
gefiltert nach der `# coding-agents:`-Direktive jedes Szenarios.

## Urteile und Artefakte

quorum erzeugt ein dreiwertiges Urteil:

- `pass` - Gauntlet-Agent bestanden und jeder Post-Check bestanden.
- `fail` - Gauntlet-Agent nicht bestanden oder ein Post-Check nicht bestanden.
- `indeterminate` - Setup/Pre-Check/Capture/Quorum-Fehler, Gauntlet
  `investigate` oder leerer Trace, wenn Trace-Prüfungen vorhanden sind.

Exit-Codes sind 0 für `pass`, 1 für `fail` und 2 für `indeterminate`.

Jeder Lauf erzeugt ein Verzeichnis unter `results/`:```text
results/<scenario>-<coding-agent>-<os>-<timestamp>-<nonce>/
|-- verdict.json                     composed result; start here
|-- gauntlet-agent/                  Gauntlet-Agent evidence
|-- coding-agent-workdir/            files the Coding-Agent produced
|-- home/                            throwaway Coding-Agent HOME
|-- trajectory.json                  normalized ATIF trace
`-- coding-agent-token-usage.json    Coding-Agent token cost, when priced

`bun run check` ist das einzelne Tor (Biome lint/format + full-strict `tsc` +
`bun test`); die einzelnen Schritte sind `bun run lint`, `bun run typecheck`, und
`bun test`.

## Architecture

quorum ist **TypeScript auf Bun**. Die Konsole ist `bun run quorum <cmd>` (ein
[commander](https://github.com/tj/commander.js) CLI unter `src/cli/index.ts`, auch
als das `quorum`-Bin bereitgestellt); das Tor ist `bun run check`
(Biome + full-strict `tsc` + `bun test`).

Die Strukturen, die Prozess- und Dateigrenzen überschreiten — `verdict.json`, Batch-
Indizes, Ökonomie, das Gauntlet-Ergebnis, Agent-YAML — sind **zod-Schemata** in
`src/contracts/`, die an jeder Grenze validiert werden, sodass eine fehlerhafte externe Datei
laut scheitert, anstatt ein Urteil zu korrumpieren. Die `cli/`-Schicht parst Befehle
und leitet in die `runner/`-Pipeline (ein Szenario × ein Coding-Agent) oder
`run-all/` (die Matrix) weiter. Unterschiede pro Coding-Agent leben in zwei parallelen
Fan-Outs, die nach Agentenname indiziert sind: `agents/` befüllt die Konfiguration des
Agenten unter dem wegwerfbaren Pro-Lauf `$HOME` (`<run>/home`), und `normalize/` wandelt
das Sitzungsprotokoll dieses Agenten in eine einheitliche Tool-Call-Spur um. Live-Agent-CLI-
Aufrufe und andere nicht-hermetische Unterprozesse gehen durch die
`agents/command-runner.ts`-Nahtstelle, sodass die Unit-Testsuite Fakes einspritzt und niemals
eine echte CLI startet. `scheduler/` ist die gemeinsame Nebenläufigkeits-Engine unter
`run-all/`. Das Dashboard ist ein separates schreibgeschütztes Paket, das `results/`
und `grid-manifest.json` scannt. `env.ts` ist das einzige Modul, das `process.env` liest.```text
src/
  cli/                  commander CLI: run, list, new, check, show, costs, run-all, grid-manifest
    index.ts              command wiring + run / costs / run-all / grid-manifest actions
    render.ts             verdict renderer for triage (quorum show)
    render-batch.ts       batch-matrix renderer (quorum show <batch>)
    resolve-target.ts     run/batch target resolution; scenario.ts scenario loading
  runner/               per-run orchestration (one scenario × one Coding-Agent)
    index.ts              setup → pre-checks → gauntlet drive → capture → post-checks → compose
    context.ts            populate the Gauntlet-Agent context dir (HOWTO + launch-agent shim)
    phase.ts              phase.json (setup/agent/checks) for the dashboard
    stopped.ts            SIGINT → stopped (indeterminate) verdict; errors.ts staged run-error stages
  agents/               per-Coding-Agent provisioning (resolveAgent dispatch)
    index.ts              agent registry + dispatch (incl. the inline Claude/Default adapters)
    command-runner.ts     injectable subprocess seam (live CLIs faked in tests)
    <agent>.ts            codex/gemini/kimi/opencode/pi/copilot/antigravity adapters
  normalize/            session-log → normalized tool-call trace, one module per dialect
  capture/              session-log snapshot/diff + tool-call capture + token usage; cwd-filter
  obol/                 obol cost estimation (session-log + gauntlet sidecar)
  economics.ts          token-cost composition → coding-agent-token-usage.json
  composer.ts           three-valued verdict from the gauntlet + checks layers
  checks/               sources prelude.sh + checks.sh, runs pre()/post(), collects check records
    prelude.sh            bare-verb DSL: defines each check verb as a bash function that
                          delegates to the TS dispatchers (no bin/ shims, no PATH prepend)
  scheduler/            central concurrency dispatcher (one global slot pool, per-harness limits + spacing)
  run-all/              scenario × Coding-Agent matrix over the scheduler; batch index
  setup-helpers/        scenario fixture builders + the `setup-helpers` CLI (dispatch registry)
  contracts/            zod schemas at the JSON boundaries (verdict, batch, economics, gauntlet, agent-config)
  scaffold.ts           `quorum new` / `quorum check`
  setup-step.ts         runs scenario setup.sh (sources prelude.sh via BASH_ENV so bare verbs resolve)
  story-meta.ts         story.md frontmatter (quorum_max_time, quorum_tier, status)
  env.ts                the single process.env boundary
  paths.ts              repo root, UTC stamps, nonces
  invariant.ts          assertNever exhaustiveness guard for closed unions
  check/                typed check verbs: fs-verbs.ts (file/git/env + bootstrap),
                        dispatch.ts (table + `not`), transcript-dispatch.ts, record.ts (sole emitter)
  cli/check-tool.ts     the dispatcher behind every check verb function (file-exists,
                        file-contains, command-succeeds, git-*, assert-checkout-clean,
                        requires-tool, not, files-exist, the *-installed/hook/extension
                        checks); check-transcript.ts and setup-helpers/cli.ts are the
                        other two dispatchers the prelude delegates to
  cli/list-check-verbs.ts  prints the FS_VERBS verb set the prelude loops over (drift-proof)
coding-agents/          per-Coding-Agent material:
  <name>.yaml             CLI config
  <name>-context/         HOWTO prose and launchers for the Gauntlet-Agent
scenarios/              scenarios (one directory each)
fixtures/               shared static fixture repos (e.g. template-repo/, sdd-*/)
test/                   bun test suite
docs/                   design notes, specs, plans, testing protocols, baselines
packages/dashboard/     read-only web matrix UI: scan/view, typed HTML templates, SSE bus, Bun.serve

Dann verwenden Sie [docs/superpowers/skills/triaging-a-failing-eval.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/superpowers/skills/triaging-a-failing-eval.md)  
für den Attributionsatlas. Für agentspezifische Authentifizierungs-, Bereitstellungs- und Erfassungsprüfungen verwenden Sie [docs/coding-agent-care-and-feeding.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/coding-agent-care-and-feeding.md).

Für die aktuelle bekannte Basislinie siehe [docs/baselines/](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/baselines/).

## Beitragsregeln

Dieses Repository übernimmt die Qualitätsanforderungen von `superpowers`.

- Ein Problem pro PR.
- Keine generierten Artefakte oder Geheimnisse committen.
- Keine Live-Evals in öffentliche CI aufnehmen.
- Die PR-Vorlage verwenden und das Sicherheits-/Eval-Lab-Risiko für Änderungen erläutern, die Coding-Agent-Konfigurationen, Shell-Ausführung, Setup-Helfer, Prüfwerkzeuge oder Gauntlet-Agent-Eingaben betreffen.
- Änderungen an der verhaltensprägenden Eval-Methodik benötigen Belege, nicht nur Prosa.

## Übergeordneter Submodule-Bump

`superpowers-evals` wird von `superpowers` als das `evals`-Submodul verwendet.  
Öffnen Sie nach jedem Merge eines PR in `main` hier einen Folge-PR gegen das übergeordnete `superpowers`-Repository, das auf `dev` abzielt, der den `evals`-Submodul-Zeiger auf den gemergeten `superpowers-evals`-Commit setzt.

Behandeln Sie einen `superpowers-evals`-Merge erst dann als vollständig propagiert, wenn dieser übergeordnete Submodule-Bump-PR existiert.

---

Sicherheitsmeldungen → [SECURITY.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/SECURITY.md).