컨테이너 외부에서 로컬 또는 break-glass 시나리오를 하나 실행하십시오:```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>

`claude` 에이전트의 기본 자격 증명은 `opus`입니다.

## 공유 평가 어플라이언스

공유 원격 라이브 평가는 신뢰할 수 있는 어플라이언스 호스트에서 실행되도록 설계되었으며, 승인된 자격 증명 번들, 정확한 저장소/참조 출처, 호스트 잠금, 복구 가능한 작업 기록을 갖추고 있습니다. 에이전트는 구성된 호스트에 어플라이언스 헬퍼가 존재하면 이를 사용해야 합니다:```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>

그런 다음, 컨테이너를 빌드하고, 시작하고, 검증하십시오:```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

전체 준비된 제품군을 위해 `--tier sentinel` 없이 동일한 명령을 실행하세요. `run-all`은 각 배치를 `results/batches/<batch-id>/` 아래에 기록하고 각 실행을 `results/<scenario>-<agent>-<os>-<timestamp>-<nonce>/` 아래에 기록합니다; 다음으로 배치를 렌더링하세요:```bash
scripts/evals-container exec quorum show <batch-id>

그룹화된 전체 에이전트 호스트 스위핑, 에이전트별 자격 증명, 인증 마운트 세부 정보 및 문제 해결에 대해서는 [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

Windows 11에서 평가를 수행하려면 `--os windows`를 사용하세요(Linux+KVM 호스트만 해당):```bash
bun run quorum run scenarios/<name> --coding-agent claude --os windows

`quorum check`는 `credentials.yaml`과 각 에이전트의 `default_credential`을 검증합니다.

스케줄러는 동시성 상한과 속도 제한 래치를 자격 증명의 **limiterKey**에 키잉합니다. **limiterKey**는 자격 증명의 `base_url`이 설정된 경우 그 값이고, 그렇지 않으면 자격 증명 이름과 `api`를 결합한 것입니다(예: `https://…/v1|openai-chat`, 또는 `base_url`이 없는 네이티브 자격 증명의 경우 `opus|anthropic`). 동일한 limiterKey를 공유하는 셀은 하나의 상한과 하나의 속도 제한 래치를 공유합니다. 즉, 어떤 셀에서 속도 제한 응답이 발생하면 해당 엔드포인트에 대해 대기 중인 나머지 모든 셀이 즉시 건너뛰어집니다.

표준 명명된 자격 증명 (`credentials.yaml` 참조): `opus`, `sonnet`, `haiku` (Claude harness), `codex_sub` (Codex 구독), `kimi_default`, `openrouter_glm_5_2` (Pi 기본값), `pi_default` (네이티브 Pi OAuth 옵트인), `opencode_gpt5`, `gemini_default`, `serf_default`, `glm_5_2_chat`, `glm_5_2_responses`, `ollama_local`.

### 외부 Serf 캠페인

단기 Serf 모델/공급자 캠페인은 저장소의 표준 `credentials.yaml`이 아닌 외부 자격 증명 파일을 사용합니다. `quorum run`, `quorum run-all` 또는 `quorum check`에 `--credentials-file`을 사용하여 명시적으로 전달하세요. 실제 캠페인 YAML과 모든 원시 실행 아티팩트는 Git 외부에 보관하세요. YAML에는 라우팅 레이블과 선택된 API 키 환경 변수 이름이 포함되며, 키 값은 절대 포함되지 않습니다.

각 캠페인 사전 설정은 정확히 하나의 모델과 하나의 공급자를 고정하고, fallback을 비활성화해야 하며, 프롬프트, 샘플링, 추론, 도구 또는 토큰 제한 재정의를 포함하지 않아야 합니다. 신뢰할 수 있는 런타임 자격 증명 번들을 통해 전용 키를 제공하세요. 키는 캠페인의 의도된 데이터 정책을 적용하고, 캠페인 지출 상한을 가져야 하며, 공유 용량 캠페인의 경우 BYOK 바인딩이 없어야 합니다. BYOK 비교는 별도의 키와 후보 파일을 사용하는 별도의 캠페인입니다.

디스패치 전에 `run-all`은 외부 파일을 한 번 구문 분석하고 표준 스냅샷을 `results/batches/<batch-id>/credentials.snapshot.yaml`에 기록합니다. 모든 하위 프로세스는 해당 불변 스냅샷을 받습니다. 직접 `quorum run`은 동일한 표준 스냅샷을 실행 디렉터리 아래에 기록합니다. 배치 시작 후 소스 YAML을 편집해도 이후 셀을 변경할 수 없습니다. 스냅샷에는 스키마에서 알 수 있는 라우팅 메타데이터와 환경 변수 이름이 포함되며, 비밀 값은 포함되지 않지만 민감한 실행 아티팩트의 일부로 남아 있습니다.

먼저 에이전트 중립적인 스모크 테스트를 실행한 다음, 최종 스모크 판정이 `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`은 인수 없이 모든 시나리오와 `credentials.yaml`의 유효성을 검사합니다.
`run-all`은 각 시나리오의 `# coding-agents:` 지시문에 따라 필터링된 모든 선택된 코딩 에이전트에 대해 포함된 모든 시나리오를 실행합니다.

## 평결 및 결과물

quorum은 세 가지 값의 평결을 생성합니다:

- `pass` - Gauntlet-Agent가 통과했으며 모든 사후 검사가 통과되었습니다.
- `fail` - Gauntlet-Agent가 실패했거나 사후 검사 중 하나가 실패했습니다.
- `indeterminate` - 설정/사전 검사/캡처/쿼럼 실패, Gauntlet `investigate`, 또는 추적 검사가 있을 때 빈 추적.

종료 코드는 `pass`의 경우 0, `fail`의 경우 1, `indeterminate`의 경우 2입니다.

각 실행은 `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`는 단일 게이트입니다 (Biome 린트/포맷 + 완전 엄격 `tsc` + `bun test`); 개별 단계는 `bun run lint`, `bun run typecheck`, `bun test`입니다.

## Architecture

quorum은 **Bun 위의 TypeScript**입니다. 콘솔은 `bun run quorum <cmd>`입니다 ( `src/cli/index.ts`에 있는 [commander](https://github.com/tj/commander.js) CLI이며, `quorum` bin으로도 노출됩니다); 게이트는 `bun run check`입니다 (Biome + 완전 엄격 `tsc` + `bun test`).

프로세스 및 파일 경계를 넘는 형태들 — `verdict.json`, 배치 인덱스, 이코노믹스, Gauntlet 결과, 에이전트 YAML — 은 `src/contracts/`에 있는 **zod 스키마**로, 모든 경계에서 검증되므로 잘못된 외부 파일은 판결을 손상시키는 대신 큰 소리로 실패합니다. `cli/` 레이어는 명령을 파싱하고 `runner/` 파이프라인 (하나의 시나리오 × 하나의 Coding-Agent) 또는 `run-all/` (매트릭스)로 디스패치합니다. Coding-Agent별 차이는 에이전트 이름으로 키가 지정된 두 개의 병렬 팬-아웃에 있습니다: `agents/`는 일회용 per-run `$HOME` (`<run>/home`) 아래에 에이전트의 구성을 시드하고, `normalize/`는 해당 에이전트의 세션 로그를 균일한 도구 호출 추적으로 변환합니다. 실제 에이전트-CLI 호출 및 기타 비-허메틱 서브프로세스는 `agents/command-runner.ts` 심을 통해 진행되므로, 단위 스위트는 가짜를 주입하고 실제 CLI를 실행하지 않습니다. `scheduler/`는 `run-all/` 아래의 공유 동시성 엔진입니다. 대시보드는 `results/` 및 `grid-manifest.json`을 스캔하는 별도의 읽기 전용 패키지입니다. `env.ts`는 `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

Then use [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)
for the attribution atlas. For agent-specific auth, provisioning, and capture
checks, 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).

For the current known-good baseline, see [docs/baselines/](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/baselines/).

## 기여 규칙

이 저장소는 `superpowers`의 품질 기준을 따릅니다.

- PR당 하나의 문제.
- 생성된 실행 아티팩트나 비밀을 커밋하지 마세요.
- 공개 CI에 라이브 평가를 추가하지 마세요.
- PR 템플릿을 사용하고 변경 사항에 대한 보안/평가-실험실 위험을 설명하세요. 다음을 변경하는 경우:
  Coding-Agent 설정, 셸 실행, 설정 도우미, 체크 도구 또는
  Gauntlet-Agent 입력을 건드리는 경우.
- 행동 형성 평가 방법론의 변경은 단순한 설명이 아닌 증거가 필요합니다.

## 상위 서브모듈 범프

`superpowers-evals`는 `superpowers`에서 `evals` 서브모듈로 사용됩니다.
여기서 `main`에 PR이 병합된 후, 상위 `superpowers` 저장소에서 `dev`를 대상으로 하는 후속 PR을 열어 `evals` 서브모듈 포인터를 병합된 `superpowers-evals` 커밋으로 범프하세요.
해당 상위 서브모듈 범프 PR이 존재할 때까지 `superpowers-evals` 병합이 완전히 전파된 것으로 간주하지 마세요.

---

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