Запустите один локальный сценарий или сценарий экстренного доступа вне контейнера:```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`.

## Общее устройство для оценок

Общие удалённые интерактивные оценки предназначены для выполнения с доверенного хоста-устройства с одним одобренным набором учётных данных, точным указанием источника репозитория/ссылки, блокировками хоста и восстанавливаемыми записями заданий. Агенты должны использовать вспомогательное устройство (appliance helper) после его появления на настроенном хосте:```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

Для оценок на 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** учетных данных — это `base_url` учетных данных, если он задан, иначе имя учетных данных, объединенное с их `api` (например, `https://…/v1|openai-chat` или `opus|anthropic` для собственных учетных данных без `base_url`). Ячейки, имеющие общий limiterKey, разделяют один лимит и одну блокировку: ответ об ограничении скорости на любой ячейке немедленно пропускает все остальные ожидающие ячейки для этой конечной точки.

Стандартные именованные учетные данные (см. `credentials.yaml`): `opus`, `sonnet`, `haiku` (обвязка Claude), `codex_sub` (подписка Codex), `kimi_default`, `openrouter_glm_5_2` (Pi по умолчанию), `pi_default` (встроенный OAuth Pi по желанию), `opencode_gpt5`, `gemini_default`, `serf_default`, `glm_5_2_chat`, `glm_5_2_responses`, `ollama_local`.

### Внешние кампании Serf

Краткосрочные кампании модели/провайдера Serf используют внешний файл учетных данных, а не канонический `credentials.yaml` репозитория. Передавайте его явно с помощью `--credentials-file` командам `quorum run`, `quorum run-all` или `quorum check`. Храните реальный YAML кампании и все необработанные артефакты запуска вне Git: YAML содержит метки маршрутизации и имя переменной окружения выбранного API-ключа, но никогда — значение ключа.

Каждый предустановленный шаблон кампании должен привязываться ровно к одной модели и одному провайдеру, отключать резервные варианты и не содержать переопределений для промпта, сэмплирования, рассуждений, инструментов или лимита токенов. Предоставьте его выделенный ключ через доверенный пакет учетных данных времени выполнения. Ключ должен обеспечивать соблюдение заданной политики данных кампании, иметь лимит расходов на кампанию, а для кампании с общей емкостью — не иметь привязки 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-Agent, отфильтрованные по директиве `# coding-agents:` каждого сценария.

## Вердикты и артефакты

quorum выдает трехзначный вердикт:

- `pass` — Gauntlet-Agent прошел и все последующие проверки пройдены.
- `fail` — Gauntlet-Agent провалился, или последующая проверка провалена.
- `indeterminate` — сбой настройки/предварительной проверки/захвата/quorum, Gauntlet `investigate` или пустой трейс при наличии проверок трейс.

Коды выхода: 0 для `pass`, 1 для `fail` и 2 для `indeterminate`.

Каждый запуск создает одну директорию в `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 lint/format + full-strict `tsc` + `bun test`); отдельные шаги: `bun run lint`, `bun run typecheck` и `bun test`.

## Архитектура

quorum — это **TypeScript на Bun**. Консоль: `bun run quorum <cmd>` (CLI на [commander](https://github.com/tj/commander.js) в `src/cli/index.ts`, также предоставляется как бинарник `quorum`); шлюз — `bun run check` (Biome + full-strict `tsc` + `bun test`).

Формы данных, пересекающие границы процессов и файлов — `verdict.json`, индексы пакетов, экономика, результат Gauntlet, YAML агента — это **zod-схемы** в `src/contracts/`, проверяемые на каждой границе, поэтому некорректный внешний файл громко завершается ошибкой, а не повреждает вердикт. Слой `cli/` разбирает команды и направляет их в конвейер `runner/` (один сценарий × один Coding-Agent) или в `run-all/` (матрица). Различия между Coding-Agent реализованы в двух параллельных разветвлениях, ключом которых является имя агента: `agents/` заполняет конфигурацию агента во временном `$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

Затем используйте [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) для атласа атрибуции. Для проверок аутентификации, подготовки и захвата, специфичных для агента, используйте [docs/coding-agent-care-and-feeding.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/docs/coding-agent-care-and-feeding.md).

Для текущего известного хорошего базового уровня см. [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`.
После слияния любого PR в `main` здесь, откройте последующий PR в родительском репозитории `superpowers`, указывающий на `dev`, который обновит указатель подмодуля `evals` на объединённый коммит `superpowers-evals`.

Не считайте слияние `superpowers-evals` полностью распространённым до тех пор, пока не появится такой PR обновления родительского подмодуля.

---

Сообщение о безопасности → [SECURITY.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/SECURITY.md).