초능력(superpowers)을 위한 행동 평가(Behavioral eval) 실험실입니다.
Quorum은 Gauntlet QA 에이전트를 통해 실제 코딩 에이전트 CLI(Claude, Codex, Antigravity, Gemini, Kimi, OpenCode, Pi, Copilot)를 구동하며, 시나리오 수락 기준 및 결정론적 사후 점검(deterministic post-checks)을 바탕으로 이들을 평가합니다.

코드, CLI, 경로 및 인라인 산문(inline prose)에서는 모두 소문자 quorum을 사용하며, 대문자 형태인 Quorum은 헤딩(headings)과 액터 테이블(actor table)에 등장합니다.

이것은 일반적인 벤치마크 제품군이 아닙니다. 이는 워크플로 준수(workflow compliance)를 위한 평가 실험실입니다: 기술 트리거링(skill triggering), 워크트리 동작(worktree behavior), 하위 에이전트 조정(subagent coordination), 검증 반사(verification reflexes), 리뷰 품질(review quality), 그리고 비용 형성 패턴(cost-shaping patterns)을 다룹니다.

quorum에는 매우 다른 두 가지 실행 모드가 있습니다:

**정적/단위 점검 (Static/unit checks)**은 공개 CI(Continuous Integration)에 안전합니다. 이 모드는 biome, tsc, bun test를 실행합니다. 모델 API를 호출하지 않으며 에이전트 CLI를 실행하지도 않습니다. **라이브 평가 (Live evals)**는 신뢰할 수 있는 유지 관리자(trusted-maintainer) 작업입니다. 이 모드는 Claude Code, Codex CLI, Antigravity CLI, Gemini CLI, Kimi Code, OpenCode CLI, Pi CLI 또는 Copilot CLI를 허용 모드(permissive modes)로 실행하고 원본 트랜스크립트(raw transcripts), 도구 호출(tool calls), 파일 시스템 상태(filesystem state) 및 세션 로그(session logs)를 수집합니다.

공개 CI는 반드시 해당 경계의 정적/단위 점검 측에 머물러야 합니다. 공개 CI에 API 키, 라이브 quorum run … 호출 또는 위험 모드(dangerous-mode) 에이전트 실행을 절대 추가하지 마십시오.

라이브 평가는 테스트 대상인 코딩 에이전트(Coding-Agent)를 광범위한 실행 권한과 함께 실행합니다:

• Claude는 --dangerously-skip-permissions를 사용합니다.
• Codex는 --dangerously-bypass-approvals-and-sandbox를 사용합니다.
• Antigravity는 --dangerously-skip-permissions를 사용하며 agy를 위해 로컬 브라우저/키링(keyring) 인증에 의존합니다.
• Gemini는 --skip-trust --approval-mode=yolo를 사용합니다; API 키 인증이 기본이며, 신뢰할 수 있는 로컬 실행을 위해 선택적 OAuth 인증을 제공합니다.
• Kimi는 --yolo를 사용합니다.
• OpenCode는 --dangerously-skip-permissions를 사용합니다.
• Pi는 실행 로컬 설정 디렉토리(run-local config dir)에서 명시적인 도구 허용 목록(tool allowlists)과 API 키 인증을 사용합니다.
• Copilot은 --allow-all을 사용합니다.

quorum은 각 코딩 에이전트의 HOME(및 XDG base dirs와 TMPDIR)을 <run>/home에 있는 일회용 실행별 홈(throwaway per-run home)으로 고정합니다.

— 런처는 src/agents/home-env.ts에 의해 구축된 $QUORUM_HOME_ENV 토큰(xdgHomeEnv, 단일 진실 공급원 (single source of truth))을 삽입합니다. 각 에이전트의 설정 디렉터리는 해당 홈 디렉터리 하위로 통합됩니다 (Claude .claude, Codex .codex, Gemini ., OpenCode ., Antigravity ., Copilot .copilot, Kimi .kimi-code, Pi .pi/agent). 따라서 코딩 에이전트 (Coding-Agent)는 자신의 $HOME 기본값을 통해 설정을 찾으며, 호스트의 실제 ~/.claude, ~/.codex, ~/.gemini, ~/.kimi-code, ~/.pi, ~/.copilot, ~/.config 또는 기타 홈 상대적 상태, 설치된 플러그인, 또는 이전 세션을 절대 볼 수 없습니다. 프로비저닝 (Provisioning) 단계에서 실행 전 해당 일회용 홈 디렉터리에 설정값과 각 에이전트에 필요한 호스트 OAuth 자격 증명을 심어두므로, 런타임 (run-time) 로그인이 필요하지 않습니다. Copilot 또한 로컬 Superpowers 플러그인을 격리된 홈 디렉터리 아래에 배치하고, 허용 목록에 있는 외부 환경을 사용하며, 실행 디렉터리 내부에 비밀 정보를 포함하는 chmod-0600 권한의 .copilot-env 파일을 작성합니다. 이는 피해 범위 (blast radius)를 좁혀주지만 샌드박스 (sandbox)는 아닙니다. OpenCode 및 Copilot 런처는 추가적으로 허용 목록에 있는 환경을 사용하지만, 실제 실행되는 코딩 에이전트 (Coding-Agents)는 여전히 광범위한 파일 시스템 및 명령 실행 권한을 가지고 실행됩니다.

실제 평가 (evals)는 반드시 신뢰할 수 있는 로컬 환경에서만 실행하십시오:

• 선택된 코딩 에이전트 (Coding-Agent)에 필요한 API 키만 내보내기 (Export) 하십시오.
• 환경 변수에 광범위한 운영(production) 또는 개인 비밀 정보를 포함하여 실행하는 것을 피하십시오.
• results/, 가공되지 않은 세션 로그, 세션 상태/도구 호출 아티팩트 (session-state/tool-call artifacts), 그리고 Gauntlet-Agent 입력값은 민감한 정보로 취급하십시오. - 실행 아티팩트를 먼저 확인하지 않고 커밋하거나 붙여넣지 마십시오.

정적 게이트 (static gates)를 설치하고 실행하십시오:

bun install
bun run check
bun run quorum check

컨테이너 외부에서 로컬 또는 비상 상황 (break-glass) 시나리오를 실행하십시오:

export SUPERPOWERS_ROOT=/path/to/superpowers
export ANTHROPIC_API_KEY=...
bun run quorum run scenarios/triggering-writing-plans --coding-agent claude
...

Gauntlet-Agent (QA 드라이버)는 ANTHROPIC_API_KEY를 사용하여 Anthropic에 인증합니다.

기본적으로는 그렇습니다. 대신 로그인된 Claude 구독을 통해 실행하려면 환경 변수(예: .env)에 CLAUDE_CODE_OAUTH_TOKEN ( claude setup-token 에서 가져온 값)을 설정하세요. 하네스 (harness)가 이를 전달하며, Gauntlet은 API 키보다 이 토큰을 선호합니다. 주의: 구독 서비스는 대화형 사용에 맞춰진 사용량 제한 (usage caps)이 있습니다. 고동시성 (high-concurrency) run-all 배치 작업 시 제한에 걸릴 수 있으므로, 과도한 부하에는 API 키가 더 적합합니다.

에이전트 (Agent) 이름은 claude, codex, antigravity, gemini, kimi, opencode, pi, 그리고 copilot입니다. 모든 에이전트가 모든 시나리오에서 유효한 것은 아닙니다.

중요 변경 사항 (자격 증명 축): claude-haiku와 claude-sonnet은 더 이상 별도의 에이전트 이름이 아닙니다. Sonnet 또는 Haiku를 대상으로 Claude 하네스를 실행하려면 다음과 같이 입력하세요:

bun run quorum run scenarios/<name> --coding-agent claude --credential sonnet
bun run quorum run scenarios/<name> --coding-agent claude --credential haiku

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

공유 원격 라이브 평가 (Shared remote live evals)는 신뢰할 수 있는 어플라이언스 호스트 (appliance host)에서 실행되도록 설계되었습니다. 여기에는 승인된 하나의 자격 증명 번들, 정확한 리포지토리/참조 출처 (repo/ref provenance), 호스트 잠금 (host locks), 그리고 복구 가능한 작업 기록이 포함됩니다. 에이전트는 구성된 호스트에 어플라이언스 헬퍼 (appliance helper)가 준비되면 이를 사용해야 합니다:

evals-appliance doctor --json
evals-appliance prepare --json --superpowers-ref <branch-tag-or-sha>
evals-appliance run-all --json --detach \
...

대상 인터페이스와 운영 규칙은 docs/appliance-runbook.md에 있으며, docs/superpowers/specs/2026-06-18-shared-eval-appliance-design.md를 기반으로 합니다. doctor는 읽기 전용입니다. prepare는 라이브 작업이 활성화되어 있는 동안 참조를 변경하는 대신 lock_busy를 반환합니다. 호스트 액세스 및 제공업체별 비상 절차 (break-glass procedures)는 의도적으로 이 공개 리포지토리에서 제외되었습니다. 해당 세부 사항은 비공개 운영 런북 (private ops runbook)을 사용하세요. 가공되지 않은 bun run quorum ... 및 scripts/evals-container exec quorum ...은 공유 라이브 평가를 위한 로컬 또는 신뢰할 수 있는 비상 (break-glass) 워크플로우로 유지됩니다.

Docker 런타임 (runtime)은 실제 스위트 (suite) 실행을 위한 주요 레시피 (recipe)입니다. 이는 quorum이 풍부한 Ubuntu 워크스페이스 컨테이너 (workspace container) 내부에서 실행되는 동안, evals 체크아웃 (checkout), 테스트 대상인 Superpowers 체크아웃, 자격 증명 (credentials), 인증 소스 (auth sources), 그리고 모든 실행 아티팩트 (artifacts)를 호스트 (host)에 유지합니다.

.env.container를 생성하거나

up 명령에 명시적인 환경 파일 (env file)을 전달하세요:

ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
OPENROUTER_API_KEY=... # Pi 기본값: OpenRouter GLM 5.2
...

그런 다음 컨테이너를 빌드 (build), 시작 (start), 검증 (validate) 하세요:

scripts/evals-container build
scripts/evals-container down || true
scripts/evals-container --env-file .env.container up
...

래퍼 (wrapper)는 이 evals 체크아웃을 /workspace/evals에, 상위 Superpowers 체크아웃을 /workspace/superpowers에, 그리고 호스트의 results/를 /workspace/evals/results에 마운트 (mount) 합니다. 기본 상위 경로가 테스트 대상 시스템이 아닌 경우 --superpowers-root <dir>를 사용하여 Superpowers 체크아웃을 재정의 (override) 하세요.

이미지 빌드에는 로컬 Gauntlet 체크아웃이 필요합니다. 래퍼는 GAUNTLET_ROOT 또는 Bun 글로벌 bun link 설치를 통해 이를 찾아냅니다. 명시적으로 선택하려면 build 시 --gauntlet-root <dir>를 사용하세요.

자격 증명 (credentials)은 읽기 전용 마운트 (read-only mounts)입니다. 기본적으로 up은 .env.container를 먼저 사용한 다음 .env를 사용하며, 가장 먼저 발견된 파일을 /run/evals/credentials.env에 마운트합니다. 명시적으로 선택하려면 up 이전에 --env-file <file>을 전달하세요. 래퍼는 호스트 환경을 통째로 전달하지 않습니다. 컨테이너 내부의 quorum 심 (shim) 만 dotenv 파일을 소싱 (sources) 하므로, scripts/evals-container exec bash ...는 실시간 평가 자격 증명을 자동으로 받지 못합니다. 기존 컨테이너의 env-file 마운트를 변경하기 전에는 down을 사용하세요.

OAuth/파일 인증 소스 (auth sources) 또한 읽기 전용입니다. 기존의 ~/.codex, ~/.gemini, ~/.kimi-code, ~/.pi 디렉토리는 각각 /auth/codex, /auth/gemini, /auth/kimi-code, /auth/pi로 마운트됩니다. 소스를 재정의하려면 --auth codex=<dir>, --auth gemini=<dir>, --auth kimi=<dir>, 또는 --auth pi=<dir>를 사용하세요.

Sentinel 스위트 (suite)로 시작하세요:

scripts/evals-container exec quorum run-all \
--tier sentinel \
--coding-agents claude,codex,kimi \
...

전체 준비된 스위트 (suite)를 실행하려면 --tier sentinel 없이 동일한 명령어를 실행하세요.

run-all은 각 배치 (batch)를 results/batches/<batch-id>/ 아래에 기록하며,
각 실행 (run)은 results/<scenario>-<agent>-<os>-<timestamp>-<nonce>/ 아래에 기록합니다.

배치를 렌더링하려면 다음을 사용하세요:

scripts/evals-container exec quorum show <batch-id>

run-all은 주기적인 라이브니스 하트비트 (liveness heartbeat)를 출력합니다
(⋯ … · running N/jobs · done D · queued Q · [agent:scenario, …])

--heartbeat-seconds <n>으로 이를 조정할 수 있습니다
(0은 비활성화).

배치를 중단하는 경우 — Ctrl-C를 누르거나 exec 세션이 종료되는 경우 — 프로세스가 우아하게(gracefully) 중단됩니다. 즉, 큐 (queue)가 취소되고, 진행 중인 실행 (runs)은 SIGINT 신호를 받으며 (중단된 것으로 기록됨), 배치 푸터 (footer)가 여전히 작성되므로 finished_at이 null 상태로 남지 않습니다.

컨테이너 런타임 (container runtime)은 Docker 소켓을 마운트하거나, 대시보드 포트를 게시하거나, 데스크톱 IDE를 포함하지 않습니다. 이 이미지는 Antigravity의 데스크톱 agy 설치 프로그램을 제외합니다. 헤드리스 (headless) 설치 경로가 생길 때까지는 호스트 측에서 Antigravity를 실행하세요:

bun run quorum run-all --coding-agents antigravity --jobs 1

그룹화된 모든 에이전트 (all-agent) 호스트 스윕 (sweeps), 에이전트별 자격 증명 (credentials), 인증 마운트 (auth mount) 상세 정보 및 문제 해결에 대해서는 docs/coding-agent-care-and-feeding.md를 참조하세요.

Windows 11에서의 평가 (evals)를 위해서는 --os windows를 사용하세요 (Linux+KVM 호스트만 가능):

bun run quorum run scenarios/<name> --coding-agent claude --os windows

설정 및 배포에 대해서는 docs/windows/eval-runtime.md를 참조하세요.

액터 (actors)를 명확히 구분하세요. 이들을 혼동하는 것이 가장 흔한 분류 (triage) 오류입니다. 이 이름들은 문서, CLI 출력, 코드, 파일 이름, 커밋 메시지 등 모든 곳에서 사용됩니다.

행위자 (Actor)	정의	위치 / 관련 파일
Gauntlet	범용 QA 프레임워크 (framework); gauntlet CLI. 블랙박스 테스터 (black-box tester).	리포지토리 (repo) github.com/prime-radiant-inc/gauntlet ; bun link 또는 GAUNTLET_ROOT를 통해 PATH 상의 gauntlet으로 존재
Gauntlet-Agent	Gauntlet 내부에서 Coding-Agent를 구동하고 시나리오의 수락 기준 (ACs, Acceptance Criteria)에 따라 스스로 채점하는 LLM.	모델 예: claude-sonnet-4-6 ; 이벤트 스트림(event stream) → <run>/gauntlet-agent/results/<runId>/run.jsonl ; 판정(verdict) → result.{json,md}
Coding-Agent	테스트 대상인 에이전트 — 즉, SUT (System Under Test). 인스턴스: Claude, Codex, Antigravity, Gemini, Kimi, OpenCode, Pi, Copilot.	임시 $HOME 디렉토리 하위의 설정(config) + 세션 로그: <run>/home/… ; 에이전트가 작성하는 파일 → <run>/coding-agent-workdir/
Quorum	TypeScript/Bun 래퍼 (wrapper). 설정 (setup), Coding-Agent 적응 (adaptation), 결정론적 검사 (deterministic checks), 그리고 최종 판정 (final verdict)을 담당.	리포지토리 (repo) superpowers-evals/src/ ; <run>/verdict.json

하나의 실행 (run)에는 두 개의 LLM이 포함됩니다 — Gauntlet-Agent (QA 테스터)와 Coding-Agent (대상). 모델이 서로 다르고, 로그가 분리되며, 토큰 비용도 별도로 발생합니다.

• docs/scenario-authoring.md - 시나리오 구조 (anatomy), 스토리/AC 작성법, 설정 도우미 (setup helpers), 검사 동사 (check verbs), 그리고 작성 시 주의사항 (authoring traps).

• docs/appliance-runbook.md - 에이전트를 위한 공유 원격 어플라이언스 (remote appliance) 운영 규칙.

• docs/coding-agent-care-and-feeding.md - 자격 증명 (credentials), 스윕 (sweeps), 에이전트별 런타임 노트, 그리고 문제 해결 (troubleshooting).

• docs/adding-a-coding-agent.md - 새로운 에이전트 타겟, 런처 (launcher), 프로비저너 (provisioner), 정규화 도구 (normalizer), 그리고 스모크 테스트 (smoke)를 추가하기 위한 체크리스트.

• docs/superpowers/skills/triaging-a-failing-eval.md - 실패한 평가 (eval)에 대한 분류 (triage).

• 통과하지 못한 실행 (runs)에 대한 귀속 아틀라스 (attribution atlas).

• docs/baselines/ - 백엔드별 현재 알려진 양호한 베이스라인 (baselines).

평가 차원 (eval dimension)은 **(scenario, coding-agent, credential, os)**입니다. 리포지토리 루트의 credentials.yaml은 명명된 자격 증명 (named credentials)을 정의합니다. 각 항목은 모델, 와이어 프로토콜 (wire protocol) (api: openai-chat, openai-responses, anthropic, 또는 gemini), 기본값이 아닌 엔드포인트를 위한 선택적 base_url, 인증 유형 (api-key

, subscription)
, 선택적 api_key_env
, 해당 런타임 패밀리 (harnesses)
, 선택적 스케줄러 오버라이드 (max_concurrency, launch_spacing_seconds)
및 compat 블록 (thinking_format, max_tokens_field).

각 에이전트 YAML은 default_credential을 선언합니다. 런타임에 오버라이드하려면:

# 지정된 자격 증명(credential)으로 실행
bun run quorum run scenarios/<name> --coding-agent claude --credential sonnet
# 여러 자격 증명에 대해 run-all 실행 (호환되지 않는 셀은 건너뜀)
...

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

스케줄러는 자격 증명의 limiterKey를 기준으로 동시성 제한(concurrency cap)과 속도 제한 래치(rate-limit latch)를 설정합니다. limiterKey는 base_url이 설정되어 있으면 해당 base_url을 사용하고, 그렇지 않으면 자격 증명 이름에 api를 결합하여 생성합니다 (예: base_url이 있는 경우 https://…/v1|openai-chat, base_url이 없는 네이티브 자격 증명의 경우 opus|anthropic). 동일한 limiterKey를 공유하는 셀들은 하나의 제한(cap)과 하나의 속도 제한 래치를 공유합니다. 즉, 특정 셀에서 속도 제한(rate-limit) 응답이 발생하면 해당 엔드포인트에 대해 대기 중인 나머지 모든 셀은 즉시 건너뛰게 됩니다.