نفِّذ سيناريو محلي أو سيناريو الطوارئ خارج الحاوية:```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).

## وقت تشغيل ويندوز

للتقييمات على ويندوز 11، استخدم `--os windows` (مضيفو Linux+KVM فقط):```bash
bun run quorum run scenarios/<name> --coding-agent claude --os windows

`quorum check` يتحقق من صحة `credentials.yaml` والـ `default_credential` الخاص بكل وكيل.

يقوم المجدول (scheduler) بربط حد التزامن (concurrency cap) ومزلاج تحديد المعدل (rate-limit latch) بـ **limiterKey** الخاص بالاعتماد — وهو `base_url` للاعتماد إذا تم تعيينه، وإلا اسم الاعتماد، مدمجًا مع `api` الخاص به (على سبيل المثال `https://…/v1|openai-chat`، أو `opus|anthropic` لاعتماد أصلي بدون `base_url`). المشاركات (Cells) التي تشارك نفس 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` الأساسي للمستودع. قم بتمريره صراحة باستخدام
`--credentials-file` إلى `quorum run` أو `quorum run-all` أو `quorum check`.
احتفظ بملف YAML الحقيقي للحملة وجميع نتائج التشغيل الخام خارج Git: يحتوي YAML
على تسميات التوجيه واسم متغير البيئة لمفتاح API المحدد، وليس قيمة مفتاح.

يجب أن يحدد كل إعداد مسبق للحملة نموذجًا واحدًا وموفرًا واحدًا بالضبط، وتعطيل
البدائل، وألا يحتوي على أي تجاوزات للموجه (prompt) أو أخذ العينات (sampling) أو الاستدلال (reasoning) أو الأداة (tool) أو حد الرمز (token-limit). قم بتوفير مفتاحه المخصص من خلال حزمة الاعتماديات في وقت التشغيل الموثوقة. يجب أن يفرض المفتاح سياسة البيانات المقصودة للحملة، وأن يكون له حد إنفاق للحملة، وبالنسبة لحملة ذات سعة مشتركة، ألا يكون له ربط BYOK. مقارنة BYOK هي حملة منفصلة بمفتاح منفصل وملف مرشح منفصل.

قبل الإرسال، يقوم `run-all` بتحليل الملف الخارجي مرة واحدة ويكتب لقطة سريعة قانونية له في
`results/batches/<batch-id>/credentials.snapshot.yaml`؛ يتلقى كل تابع (child) تلك اللقطة الثابتة. يقوم `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، أو `investigate` من Gauntlet، أو تتبع فارغ عند وجود فحوصات التتبع.

رموز الخروج هي 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 + `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 + `tsc` الكامل الصارم + `bun test`).

الأشكال التي تعبر حدود العمليات والملفات — `verdict.json`، فهارس الدفعات، الاقتصاديات، نتيجة Gauntlet، YAML الوكيل — هي **مخططات zod** في `src/contracts/`، ويتم التحقق من صحتها عند كل حد، لذا فإن ملفًا خارجيًا غير صحيح يفشل بصوت عالٍ بدلاً من إفساد الحكم.

طبقة `cli/` تحلل الأوامر وترسلها إلى خط أنابيب `runner/` (سيناريو واحد × وكيل ترميز واحد) أو `run-all/` (المصفوفة).

الاختلافات لكل وكيل ترميز موجودة في مخرجين متوازيين يتم مفتاحهما باسم الوكيل: `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).
- لا تقم بارتكاب (commit) القطع الأثرية الناتجة عن التشغيل أو الأسرار.
- لا تضف تقييمات حية إلى CI العام.
- استخدم قالب طلب السحب واشرح مخاطر الأمان/مختبر التقييم للتغييرات التي تمس تكوينات Coding-Agent، أو تنفيذ الصدفة، أو مساعدي الإعداد، أو أدوات الفحص، أو إدخال Gauntlet-Agent.
- التغييرات في منهجية التقييم التي تشكل السلوك تحتاج إلى أدلة، وليس مجرد نثر.

## تحديث الوحدة الفرعية الأصلية

يتم استهلاك `superpowers-evals` بواسطة `superpowers` كوحدة فرعية `evals`. بعد أي دمج لطلب سحب إلى `main` هنا، افتح طلب سحب متابعة ضد المستودع الأصلي `superpowers` موجه إلى `dev` يقوم بتحديث مؤشر الوحدة الفرعية `evals` إلى الالتزام المدمج `superpowers-evals`.

لا تعامل دمج `superpowers-evals` على أنه قد تم نشره بالكامل حتى وجود طلب سحب تحديث الوحدة الفرعية الأصلية.

---

الإبلاغ عن الأمان → [SECURITY.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/HEAD/SECURITY.md).