Esegui uno scenario locale o di break-glass all'esterno del contenitore:```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>

La credenziale predefinita dell'agente `claude` è `opus`.

## Shared Eval Appliance

Gli eval live remoti condivisi sono progettati per essere eseguiti da un host appliance affidabile con un bundle di credenziali approvato, provenienza esatta repo/ref, blocchi host e record di job recuperabili. Gli agenti dovrebbero utilizzare l'helper dell'appliance una volta che esiste sull'host configurato:```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>

Quindi costruisci, avvia e convalida il 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

Esegui gli stessi comandi senza `--tier sentinel` per la suite completa pronta. `run-all` scrive ogni batch in `results/batches/<batch-id>/` e ogni esecuzione in `results/<scenario>-<agent>-<os>-<timestamp>-<nonce>/`; renderizza un batch con:```bash
scripts/evals-container exec quorum show <batch-id>

Per sweep di host con tutti gli agenti raggruppati, credenziali per agente, dettagli di montaggio auth e risoluzione dei problemi, utilizzare [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 Runtime

Per valutazioni su Windows 11, usa `--os windows` (solo host Linux+KVM):```bash
bun run quorum run scenarios/<name> --coding-agent claude --os windows

`quorum check` convalida `credentials.yaml` e `default_credential` di ogni agente.

Lo scheduler basa il proprio limite di concorrenza e il latch di rate-limit sulla **limiterKey** della credenziale — il `base_url` della credenziale se impostato, altrimenti il nome della credenziale, unito alla sua `api` (ad es. `https://…/v1|openai-chat`, o `opus|anthropic` per una credenziale nativa senza `base_url`). Le celle che condividono una limiterKey condividono un limite e un latch di rate-limit: una risposta di rate-limit su qualsiasi cella salta immediatamente tutte le celle rimanenti in coda per quell'endpoint.

Credenziali standard con nome (vedi `credentials.yaml`): `opus`, `sonnet`, `haiku` (Claude harness), `codex_sub` (abbonamento Codex), `kimi_default`, `openrouter_glm_5_2` (Pi predefinito), `pi_default` (opt-in Pi OAuth nativo), `opencode_gpt5`, `gemini_default`, `serf_default`, `glm_5_2_chat`, `glm_5_2_responses`, `ollama_local`.

### Campagne Serf esterne

Le campagne Serf di breve durata per modello/provider utilizzano un file di credenziali esterno, non il `credentials.yaml` canonico del repository. Passalo esplicitamente con `--credentials-file` a `quorum run`, `quorum run-all` o `quorum check`. Tieni il vero YAML della campagna e tutti gli artefatti grezzi delle esecuzioni fuori da Git: lo YAML contiene etichette di instradamento e il nome della variabile d'ambiente della chiave API selezionata, mai un valore di chiave.

Ogni preset di campagna deve fissare esattamente un modello e un provider, disabilitare i fallback, e non contenere override di prompt, sampling, reasoning, tool o limiti di token. Fornisci la sua chiave dedicata tramite il bundle di credenziali runtime affidabile. La chiave deve applicare la policy dei dati prevista dalla campagna, avere un limite di spesa per la campagna e, per una campagna a capacità condivisa, non avere binding BYOK. Un confronto BYOK è una campagna separata con una chiave separata e un file candidato separato.

Prima dell'invio, `run-all` analizza il file esterno una volta e scrive il suo snapshot canonico in `results/batches/<batch-id>/credentials.snapshot.yaml`; ogni figlio riceve quello snapshot immutabile. Un `quorum run` diretto scrive lo stesso snapshot canonico nella propria directory di esecuzione. Modificare lo YAML di origine dopo l'avvio di un batch non può cambiare le celle successive. Gli snapshot contengono metadati di instradamento conosciuti dallo schema e nomi di variabili d'ambiente, non valori segreti, ma rimangono parte degli artefatti di esecuzione sensibili.

Esegui prima lo smoke test neutrale rispetto all'agente, poi esegui lo scenario costoso solo per le credenziali il cui verdetto finale dello smoke test è `pass`:```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` senza argomenti convalida ogni scenario e `credentials.yaml`.
`run-all` esegue ogni scenario incluso contro ogni Coding-Agent selezionato, filtrato dalla direttiva `# coding-agents:` di ogni scenario.

## Verdetto e Artefatti

quorum produce un verdetto a tre valori:

- `pass` - Gauntlet-Agent superato e ogni post-check superato.
- `fail` - Gauntlet-Agent fallito, o un post-check fallito.
- `indeterminate` - fallimento setup/pre-check/capture/quorum, Gauntlet `investigate`, o trace vuoto quando i trace checks sono presenti.

I codici di uscita sono 0 per `pass`, 1 per `fail` e 2 per `indeterminate`.

Ogni esecuzione produce una directory sotto `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` è il singolo gate (Biome lint/format + full-strict `tsc` + `bun test`); i singoli passi sono `bun run lint`, `bun run typecheck` e `bun test`.

## Architettura

quorum è **TypeScript su Bun**. La console è `bun run quorum <cmd>` (una CLI [commander](https://github.com/tj/commander.js) in `src/cli/index.ts`, esposta anche come bin `quorum`); il gate è `bun run check` (Biome + full-strict `tsc` + `bun test`).

Le strutture che attraversano i confini di processo e file — `verdict.json`, indici batch, economics, il risultato Gauntlet, YAML degli agent — sono **schemi zod** in `src/contracts/`, validati a ogni confine, in modo che un file esterno malformato fallisca rumorosamente invece di corrompere un verdetto. Il livello `cli/` analizza i comandi e li smista nella pipeline `runner/` (uno scenario × un Coding-Agent) o in `run-all/` (la matrice). Le differenze per Coding-Agent risiedono in due fan-out paralleli chiave per nome agente: `agents/` semina la configurazione dell'agente sotto il `$HOME` temporaneo per esecuzione (`<run>/home`), e `normalize/` trasforma il log di sessione di quell'agente in una traccia uniforme di chiamate a strumenti. Le chiamate live agente-CLI e altri sottoprocessi non ermetici passano attraverso il punto di giunzione `agents/command-runner.ts`, in modo che la suite unità inietti finti e non lanci mai una CLI reale. `scheduler/` è il motore di concorrenza condiviso sotto `run-all/`. Il dashboard è un pacchetto separato in sola lettura che scansiona `results/` e `grid-manifest.json`. `env.ts` è l'unico modulo che legge `process.env`.```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

Quindi utilizzare [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)
per l'atlante di attribuzione. Per i controlli di autenticazione, provisioning e acquisizione specifici dell'agente,
utilizzare [docs/coding-agent-care-and-feeding.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/coding-agent-care-and-feeding.md).

Per la baseline attuale conosciuta come buona, vedere [docs/baselines/](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/baselines/).

## Regole di Contribuzione

Questo repository eredita il livello di qualità di `superpowers`.

- Un problema per PR.
- Non fare commit di artefatti di esecuzione generati o segreti.
- Non aggiungere valutazioni live alla CI pubblica.
- Utilizzare il template PR e spiegare il rischio di sicurezza/lab di valutazione per le modifiche che riguardano configurazioni Coding-Agent, esecuzione shell, helper di setup, strumenti di controllo o input di Gauntlet-Agent.
- Le modifiche alla metodologia di valutazione che modella il comportamento necessitano di prove, non solo testo.

## Aggiornamento Submodulo Padre

`superpowers-evals` è consumato da `superpowers` come submodulo `evals`.
Dopo che qualsiasi PR viene unito a `main` qui, aprire un PR successivo contro il repository padre `superpowers` con destinazione `dev` che aggiorni il puntatore del submodulo `evals` al commit unito di `superpowers-evals`.

Non considerare un'unione di `superpowers-evals` come completamente propagata finché quel PR di aggiornamento del submodulo padre non esiste.

---

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