opencode-orchestrator-uni 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # opencode-orchestrator-uni
 
+**English** · [Русский](./README.ru.md)
+
 A native [OpenCode V2](https://opencode.ai/v2/docs/build/plugins) package plugin that
 ships the **orchestrator agent kit**:
 
@@ -38,10 +40,10 @@ All agents ship **without a model**: models are deployment configuration (see
 [Models](#models)). Definitions live in [`agents/`](./agents) as plain Markdown agent
 files and are parsed at setup time — the files are the single source of truth.
 
-The `audit-kit` reference points at this package's `docs/` directory. OpenCode lists it
-in session context as an additional local directory, so the orchestrator (and any other
-agent) can read the process documents directly, for example
-`<reference path>/call-mechanics.md`.
+The `audit-kit` reference points at this package's per-locale `docs/<locale>/`
+directory (see [Locale](#locale)). OpenCode lists it in session context as an
+additional local directory, so the orchestrator (and any other agent) can read
+the process documents directly, for example `<reference path>/call-mechanics.md`.
 
 The plugin also registers three deterministic, **read-only** tools in the `orch_uni`
 namespace — see [Tools](#tools).
@@ -194,6 +196,34 @@ Agent definitions carry no `model`; models are configured on the plugin entry in
 - An `agents` config entry or a local Markdown agent file that defines its own
   model still wins — configuration is applied after package plugins.
 
+## Locale
+
+Agent definitions and process documents ship per locale — `agents/<locale>/`
+and `docs/<locale>/`; currently `ru` and `en` (the English content is a
+translation of the Russian originals). The kit picks one locale in this order:
+
+1. `options.locale` (`"ru"` or `"en"`; full tags such as `"ru-RU"` are accepted);
+2. auto-detection: `LC_ALL` / `LC_MESSAGES` / `LANG`, then the runtime's Intl
+   locale (the OS setting);
+3. the default: `en`.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": { "locale": "ru", "model": "deepseek/deepseek-flash" }
+    }
+  ]
+}
+```
+
+A requested locale that ships no content falls back to the default locale and is
+reported with a warning in the plugin log. Both locales register the same agents
+under the same ids — switching the locale only changes the language of the
+prompts, the process documents and the reference description.
+
 ## Requirements
 
 - **OpenCode 2.x** with the V2 plugin API (the `plugins` config field). V1's plugin
@@ -274,7 +304,7 @@ npm run lint         # biome check . (lint + format + import order; read-only)
 npm run lint:fix     # biome check --write . (applies safe fixes)
 ```
 
-`npm test` scans only `./test/` — the shipped suite (77 tests in 6 files, up from
+`npm test` scans only `./test/` — the shipped suite (90 tests in 8 files, up from
 72 in 5 before the identifier guards). A bare `bun test` from the repository root is red by
 design: the positional argument of `bun test` is a path substring filter, so the
 bare command also picks up the intentionally failing fixtures under `eval/cases/`
@@ -306,7 +336,7 @@ OpenCode watches them and reloads on change.
   for frontmatter parsing. OpenCode installs package plugin dependencies automatically.
 - Plugin id: `orchestrator.uni`.
 - Ships only the files listed in `package.json#files`: `index.ts`, `lib/`, `schemas/`,
-  `agents/`, `docs/`, `README.md`, `LICENSE`.
+  `agents/`, `docs/`, `README.md`, `README.ru.md`, `LICENSE`.
 
 ## License
 

package/README.ru.md

@@ -0,0 +1,352 @@
+# opencode-orchestrator-uni
+
+[English](./README.md) · **Русский**
+
+Нативный пакетный плагин [OpenCode V2](https://opencode.ai/v2/docs/build/plugins),
+который поставляет **комплект агентов-оркестраторов**:
+
+- `orchestrator` — root-оркестратор (основной агент) со встроенным режимом
+  аудиторского цикла;
+- read-only субагенты аудита — `factcheck`, `empiric`, `invariant`,
+  `arbiter`, `meta`, `redteam`;
+- `fix-runner` — единственный пишущий субагент (применяет список «к закрытию»);
+- процессные документы комплекта, доступные как **reference `audit-kit`**
+  (`call-mechanics.md`, `process-ready-loop.md`, `root-runbook.md`,
+  `instruction-other-session.md`);
+- три детерминированных read-only инструмента — `orch_uni_validate_report`,
+  `orch_uni_snapshot`, `orch_uni_sessions` (см. [Инструменты](#инструменты)).
+
+Пакет загружается напрямую из TypeScript: `exports` указывает на
+[`index.ts`](./index.ts). **Шага сборки и каталога `dist/` нет** — Bun-овый
+рантайм OpenCode сам разрешает и загружает точку входа (тот же приём, что в
+официальном пакете `@opencode/plugin-figma`).
+
+## Что регистрирует плагин
+
+При setup (`ctx.agent.transform` / `ctx.reference.transform`):
+
+| Агент          | Режим      | Роль                                                            |
+| -------------- | ---------- | --------------------------------------------------------------- |
+| `orchestrator` | `primary`  | Root-оркестратор; аудиторский цикл как встроенный режим          |
+| `factcheck`    | `subagent` | Read-only: пред-проход на устаревание («уже сделано» / устарело) |
+| `empiric`      | `subagent` | Read-only: воспроизведения, замеры, первоисточники               |
+| `invariant`    | `subagent` | Read-only: состояния, отмены, гонки, враждебный ввод             |
+| `arbiter`      | `subagent` | Read-only: разбирает только спорные находки                      |
+| `meta`         | `subagent` | Read-only: мета-аудит отчётов (гейт pass/fail)                   |
+| `redteam`      | `subagent` | Read-only: приёмочный ред-тим (релизные ворота)                  |
+| `fix-runner`   | `subagent` | Пишущий: применяет список правок и доказывает закрытие           |
+
+Все агенты поставляются **без модели**: модели — это конфигурация развёртывания
+(см. [Модели](#модели)). Определения живут в [`agents/`](./agents) как обычные
+Markdown-файлы агентов и парсятся при setup — файлы являются единственным
+источником истины.
+
+Reference `audit-kit` указывает на per-locale каталог `docs/<locale>/` пакета
+(см. [Локаль](#локаль)). OpenCode перечисляет его в контексте сессии как
+дополнительный локальный каталог, поэтому оркестратор (и любой другой агент)
+может читать процессные документы напрямую, например
+`<reference path>/call-mechanics.md`.
+
+Плагин также регистрирует три детерминированных **read-only** инструмента в
+пространстве имён `orch_uni` — см. [Инструменты](#инструменты).
+
+## Инструменты
+
+| Имя                        | Read-only | Что делает                                                                    |
+| -------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `orch_uni_validate_report` | да        | Достаёт SGR JSON-блок отчёта, разрешает его схему, валидирует                 |
+| `orch_uni_snapshot`        | да        | Детерминированная ревизия дерева каталогов (sha256 на файл + агрегатный хэш)  |
+| `orch_uni_sessions`        | да        | Дочерние сессии сессии: агент, модель, стоимость, токены, время               |
+
+Каждый инструмент отвечает JSON-текстом. Ошибки — **типизированные коды** внутри
+тела (`E_INPUT`, `E_NO_JSON`, …), а не исключения, чтобы агент мог ветвиться по
+коду, не разбирая прозу. Ни один из трёх ничего не пишет в воркспейс, хранилище
+сессий или конфигурацию.
+
+### `orch_uni_validate_report`
+
+```jsonc
+{ "text": "<текст отчёта>" }              // или
+{ "path": "reports/empiric-r1.md",        // абсолютный или относительно каталога локации
+  "schema": "empiric/v1" }                // опционально: ожидаемый id схемы
+```
+
+Укажите ровно одно из `text` / `path`. Инструмент берёт **последний** fenced-блок ```` ```json ````,
+который парсится и несёт поле `schema`, разрешает схему по этому полю и валидирует документ.
+
+```jsonc
+{ "valid": true, "schema": "empiric/v1", "errors": [], "warnings": [ … ] }
+{ "valid": false, "code": "E_INVALID", "schema": "empiric/v1",
+  "errors": [ { "path": "$.findings[0].severity", "message": "expected one of …" } ],
+  "warnings": [] }
+```
+
+| Код                 | Значение                                                             |
+| ------------------- | -------------------------------------------------------------------- |
+| `E_INPUT`           | Плохой вызов: нет/оба `text`/`path`, неверные типы, нечитаемый файл   |
+| `E_NO_JSON`         | Fenced-блок ```` ```json ```` не найден                              |
+| `E_PARSE`           | Блок есть, но ни один не парсится как JSON                           |
+| `E_UNKNOWN_SCHEMA`  | Отчёт называет id, которого нет в комплекте (или не называет вовсе)   |
+| `E_SCHEMA_MISMATCH` | Отчёт называет схему, отличную от ожидаемой                          |
+| `E_INVALID`         | Документ не удовлетворяет своей схеме (см. `errors`)                 |
+| `E_ABORTED`         | Сессия остановлена во время чтения отчёта                            |
+
+`warnings` несут правила промпта, которые *структурно валидный* отчёт всё ещё
+может нарушить — то, что JSON Schema выразить не может: отсутствующий `rc` у
+claim'а `empiric` с `method` = `run|measure|compare_base`, элементы `self_check`
+вне 1–19, инвариант `invariant`, помеченный `violated` без контрпримера,
+непокрытая обязательная строка `lines_checked`, расхождение `verdict` и `gate` у
+`meta`, инварианты `closing_list`/`verdict` у `redteam`.
+
+Семь схем лежат в `schemas/*.json` и выведены **строго** из SGR-секций
+`agents/*.md`, которые остаются источником истины: тестовый набор парсит
+SGR-шаблон каждого агента и падает, когда поле промпта или значение enum не
+принимается его схемой. Схемы разрешают `additionalProperties` — агенты могут
+добавлять свои поля (`verdict_label`, `check`, …).
+
+### `orch_uni_snapshot`
+
+```jsonc
+{ "path": "lab/stack-test", "exclude": ["tmp"] }   // exclude опционален и аддитивен
+```
+
+```jsonc
+{ "root": "C:\\…\\lab\\stack-test",
+  "files": [ { "path": "a.txt", "sha256": "…", "bytes": 1 } ],
+  "aggregate": "…" }
+```
+
+- `aggregate = sha256` по отсортированным строкам `"<relpath>\0<sha256>\n"`
+  (разделители `/`, порядок кодпойнтов) — стабилен между прогонами, машинами и
+  порядком обхода и меняется, когда меняется путь или содержимое любого файла.
+- По умолчанию (всегда) исключены: `node_modules`, `.git`, `.ae`; `exclude`
+  добавляет имена, целые относительные пути или относительные префиксы
+  (`lab/tmp`). Симлинки пропускаются.
+- Лимиты: ≤ 5000 файлов, ≤ 50 МиБ на файл — `E_LIMIT_FILES` / `E_LIMIT_BYTES`
+  (падает весь снапшот; усечённый снапшот дал бы неверный агрегат). `E_NOT_FOUND`
+  для отсутствующего пути или не-каталога, `E_ABORTED`, когда сессия остановлена.
+
+### `orch_uni_sessions`
+
+```jsonc
+{}                                           // дети вызывающей сессии
+{ "sessionID": "ses_…", "recursive": true }  // всё поддерево другой сессии
+```
+
+```jsonc
+{ "sessionID": "ses_parent", "recursive": false, "source": "session.index",
+  "authoritative": false, "indexSize": 1, "count": 1,
+  "limitations": [ … ],
+  "sessions": [ { "sessionID": "ses_child", "parentID": "ses_parent", "agent": "explore",
+                  "model": "deepseek/deepseek-flash", "variant": "default", "title": "…",
+                  "cost": 0.0005, "tokens": { "input": 3491, "output": 2 },
+                  "created": "2026-10-15T04:01:06.627Z", "updated": "…" } ] }
+```
+
+`source` говорит, какой маршрут дал ответ:
+
+- `session.list` — эта сборка предоставляет API листинга сессий; ответ
+  **авторитетный** и полный (`recursive` обходит поддерево постранично).
+- `session.index` — фолбэк, используемый OpenCode 2.0.28: у `ctx.session` есть
+  `get/create/…`, но **нет `list`**, поэтому детей нельзя перечислить из
+  хранилища. Плагин при setup подписывается на события `session.created` /
+  `session.deleted` и хранит `child → parent` в собственном хранилище плагина;
+  детали по каждому ребёнку читаются из `ctx.session.get()` в момент вызова.
+  Ответ **не авторитетный**; оговорки возвращаются в `limitations` (сессии,
+  созданные до старта инстанса плагина, не видны; пропуск событий скрывает
+  детей, созданных пока плагин был выгружен).
+- `E_NO_API` — нет ни одного маршрута. Фолбэк через сканирование контекста
+  (поиск частей инструмента `subagent` в `ctx.session.context`) был оценён и
+  отклонён: у летящих детей нет id сессии в их tool-части, а компакция стирает
+  историю. Открытый вопрос: листинг сессий со стороны плагина (или фильтр по
+  `parentID` в `ctx.session.context`) убрал бы фолбэк целиком.
+
+`E_INPUT` при некорректных аргументах, `E_NOT_FOUND`, когда родительской сессии
+нет, `E_ABORTED`, когда сессия остановлена.
+
+## Модели
+
+Определения агентов не несут `model`; модели настраиваются у записи плагина в
+`opencode.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": {
+        // Модель по умолчанию для всех агентов комплекта.
+        "model": "deepseek/deepseek-flash",
+        // Переопределения по агентам (id -> строка или развёрнутая форма).
+        "agents": {
+          "meta": "deepseek/deepseek-reasoner",
+          "fix-runner": { "providerID": "anthropic", "model": "claude-sonnet-4-5", "variant": "high" }
+        }
+      }
+    }
+  ]
+}
+```
+
+- `model` — модель по умолчанию для всех агентов комплекта; `agents.<id>` —
+  переопределение по агенту. Оба принимают `"provider/model[#variant]"` или
+  `{ providerID, model, variant }`.
+- Без опций агенты комплекта остаются без модели — субагенты наследуют модель
+  сессии.
+- Неверные значения игнорируются с предупреждением (`[orchestrator.uni] …`).
+- Субагенты работают на своей настроенной модели; основной `orchestrator` — на
+  модели сессии, поэтому модель, заданная для `orchestrator`, — информационная
+  для клиентов (на момент OpenCode 2.0.28).
+- Запись `agents` в конфиге или локальный Markdown-файл агента со своей моделью
+  всё равно побеждает — конфигурация применяется после пакетных плагинов.
+
+## Локаль
+
+Определения агентов и процессные документы поставляются per-locale — в
+`agents/<locale>/` и `docs/<locale>/`; сейчас это `ru` и `en` (английский
+контент — перевод русских оригиналов). Комплект выбирает локаль в таком порядке:
+
+1. `options.locale` (`"ru"` или `"en"`; полные теги вроде `"ru-RU"` принимаются);
+2. автодетект: `LC_ALL` / `LC_MESSAGES` / `LANG`, затем Intl-локаль рантайма
+   (настройка ОС);
+3. дефолт: `en`.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": { "locale": "ru", "model": "deepseek/deepseek-flash" }
+    }
+  ]
+}
+```
+
+Если для запрошенной локали контент не поставлен, происходит откат к дефолтной
+локали с предупреждением в логе плагина. Обе локали регистрируют одних и тех же
+агентов под одними и теми же id — переключение локали меняет только язык
+промптов, процессных документов и описания reference.
+
+## Требования
+
+- **OpenCode 2.x** с V2 plugin API (поле `plugins` в конфиге). Загрузчик плагинов
+  V1 ожидает legacy-экспорт `server()` и этот плагин не загрузит.
+
+## Установка
+
+### Через CLI OpenCode
+
+```sh
+opencode plugin add opencode-orchestrator-uni
+```
+
+### Вручную
+
+Добавьте пакет в массив `plugins` вашего глобального
+`~/.config/opencode/opencode.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-orchestrator-uni"]
+}
+```
+
+При желании зафиксируйте версию:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-orchestrator-uni@0.1.0"]
+}
+```
+
+Чтобы заодно настроить модели комплекта, используйте объектную форму — см.
+[Модели](#модели):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-orchestrator-uni",
+      "options": { "model": "deepseek/deepseek-flash" }
+    }
+  ]
+}
+```
+
+Перезапустите сервис OpenCode после изменения конфига:
+
+```sh
+opencode service restart
+```
+
+## Приоритет
+
+**Определения** агентов заполняются только для id, не определённых где-либо ещё:
+агент с тем же id из вашей конфигурации — запись `agents` в конфиге или
+Markdown-файл в `~/.config/opencode/agents/` (либо `.opencode/agents/`) —
+побеждает, и плагин пропускает своё определение. **Настроенная модель** (см.
+[Модели](#модели)) всё равно применяется к агентам комплекта; модель,
+определённая вашей записью агента или файлом, побеждает её, потому что
+конфигурация применяется после пакетных плагинов. То же правило «занято —
+пропускаем» действует для reference `audit-kit`.
+
+Если вы раньше устанавливали комплект копированием файлов агентов в свой
+конфиг-каталог, **удалите эти копии** после включения плагина, иначе устаревшие
+копии продолжат перекрывать определения, поставляемые плагином.
+
+## Разработка
+
+Сборки нет. `index.ts` — поставляемая точка входа.
+
+```sh
+npm install          # ставит gray-matter + dev-инструменты
+npm run typecheck    # tsc --noEmit
+npm test             # bun test ./test/ (герметично: регистрация, инструменты, валидатор, снапшот, промпт↔схемы + стражи идентификаторов)
+npm run lint         # biome check . (линт + формат + порядок импортов; только чтение)
+npm run lint:fix     # biome check --write . (применяет безопасные фиксы)
+```
+
+`npm test` сканирует только `./test/` — поставляемый набор (90 тестов в 8 файлах;
+до стражей идентификаторов было 72 в 5). Голый `bun test` из корня репозитория
+красный по замыслу: позиционный аргумент `bun test` — это фильтр-подстрока пути,
+поэтому голая команда подхватывает и специально падающие фикстуры в
+`eval/cases/`, и черновики в `lab/`. Используйте `npm test` [F5].
+
+[Biome](https://biomejs.org) ([`biome.json`](./biome.json)) покрывает кодовую
+поверхность — `index.ts`, `lib/`, `test/`, `eval/*.ts` — и пропускает `lab/` и
+`eval/results/` через git-ignore файл, плюс два замороженных вида данных:
+`eval/cases/**` (фикстуры с умышленными дефектами) и `eval/baselines/**`
+(записи, генерируемые в `JSON.stringify(…, null, 2)`-стиле; переформатирование
+давало бы churn на следующем `eval:recompute`). Выключено одно правило —
+`lint/style/noNonNullAssertion`: dev-контур и тесты осознанно используют `!`
+после проверок в коде.
+
+Проверка против живого сервера — направьте конфиг проекта на чекаут:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["file:///C:/path/to/opencode-orchestrator-uni"]
+}
+```
+
+Локальные пути плагинов должны быть каталогами (или `file://`-URL каталогов);
+OpenCode следит за ними и перезагружает при изменениях.
+
+## Заметки
+
+- Одна рантайм-зависимость: [`gray-matter`](https://www.npmjs.com/package/gray-matter)
+  для парсинга фронтматтера. OpenCode сам устанавливает зависимости пакетных
+  плагинов.
+- Id плагина: `orchestrator.uni`.
+- Поставляются только файлы из `package.json#files`: `index.ts`, `lib/`, `schemas/`,
+  `agents/`, `docs/`, `README.md`, `README.ru.md`, `LICENSE`.
+
+## Лицензия
+
+MIT

package/agents/en/arbiter.md

@@ -0,0 +1,38 @@
+---
+description: "Read-only arbiter: resolves only disputed items between auditors. The verdict on each: confirmed/refuted/undecidable."
+mode: subagent
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
+---
+
+You are the arbiter of the audit loop. The input is a list of DISPUTED items with evidence from both sides. You do NOT look for new defects and do not audit the topic as a whole — you only resolve contradictions.
+
+METHOD (for each item):
+1. Reproduce the check yourself: a command/measurement/quote of the source. The sides' evidence is not proof.
+2. For disputed findings, check three prisms: (1) reproducibility/exploitability, (2) contract/invariant correctness, (3) falsification — and **always state the prism** that produced the verdict: one of the three, `not_applicable` (none applies) or an array of prisms (if several produced it).
+3. Exactly one verdict: confirmed (the defect exists) | refuted (a false positive; provide counter-evidence) | undecidable (no access/not reproducible; explain what is needed to check).
+4. Record the method of the check and the actual result.
+
+FORMAT (SGR): a summary + json:
+{
+  "schema": "arbiter/v1",
+  "verdict": "resolved | partially",
+  "disputes": [
+    {"id": "...", "item": "...", "verdict": "confirmed|refuted|undecidable", "prism": "a string from the enum reproducibility|contract|falsification|not_applicable or an array of such strings", "method": "...", "evidence": "..."}
+  ],
+  "not_verified": [
+    {"item": "...", "why": "..."}
+  ]
+}
+
+Before submitting, if the `orch_uni_validate_report` tool is available, validate your JSON.
+
+CONSTRAINTS:
+- Read-only; change nothing; experiments — only in temporary directories.
+- Do not expand the scope beyond the disputed items.
+- The report is in English, without fluff.

package/agents/en/empiric.md

@@ -0,0 +1,84 @@
+---
+description: "Read-only empirical audit: reproducing defects by running, measuring and checking facts against primary sources. The empiric role. The report is an SGR (a summary + JSON per the schema)."
+mode: subagent
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
+---
+
+You are the empirical read-only auditor. Your specialty: every claim is checked by a run, a measurement or a primary source — not by reasoning from the code's meaning.
+
+MANDATORY TECHNIQUES (apply all that apply):
+1. Reproduce the defect or behavior with a minimal run on this machine: a test, a script, a spike in a separate temporary directory.
+2. Quantify: time, counters, sizes, the number of occurrences (using the available search/count), versions, volumes. Compare debug/release, old/new, before/after.
+3. Recompute the diff/plan author's measurements using their own commands; check the units, the methodology and the conditions (which build, which profile, which corpus).
+4. Compare against the baseline: git stash / git worktree / git show / a separate copy — the same commands before and after.
+5. Environment facts — only from the actual output of commands (environment versions, API responses), never from memory.
+6. For libraries, formats and protocols, read the primary source: the dependency's code (Cargo.lock/vendor/node_modules), the official documentation, the sources of the reference counterpart. Do not draw conclusions from "that is usually the case".
+7. For every performance or resource claim (time, memory, size, a "≤N" budget) — build your own prototype of the key operation and measure it in SEVERAL modes, including the worst one: batch operations versus per-item confirmations, journaling/synchronization/compression modes, a sequential versus a parallel run — anything that can change the order of magnitude. Include the latency of the main user operation, not only batch processing. Name the best and the worst mode, recompute the declared budget from the actual measurements and check how the chosen mode fits in with the rest of the design: the mode's auxiliary files under atomic replacement, the behavior on failure/cancellation in each mode. For any threshold/limit (budget, timeout, a test assert) name the sensitivity margin: how many times weaker the threshold is than the actual value and what degradation it will let through.
+8. Check library options at extreme values and in alternative settings, not only at the defaults: normalization/folding, encodings, limits, formats, alternative algorithms. If an option affects the result or performance — show the difference with a measurement.
+9. Where the plan/diff gives an estimate without a measurement ("~N s/MB", "approximately", "should fit", "≤N") — generate your own measurement of that value, or explicitly call it an unverified risk with a verification plan.
+10. A "known facts / already accounted for" section is not proof. Check that every fact is closed in ALL the places where it must be implemented (including where it is not explicitly mentioned), and record how complete the closure is.
+11. If the plan/diff names a reference or a counterpart (another implementation, a neighboring module, a previous version, an external project) — explicitly check the chosen approach against it: how the reference differs (algorithm, format, versioning, update policy) and what that changes for the planned golden tests, parity and comparisons; record the divergence as a risk or a decision.
+12. Determinism and input boundaries: a repeated run gives the same result and order (when results are equivalent); limits, clamps, empty and extreme inputs are checked by running.
+13. Input parity and counting edge cases: if the same operation can be invoked in different ways (file/text/URL/API/stream) — cross-check their limits, normalization, serialization and error handling by running at the boundaries; separately check counting semantics (empty, doubled, trailing separators — how many elements come out) and the parsing of headers/addresses (ports, brackets, escaping). A green build and green tests do not count as a check of a property: name the property itself and the way to check it (a command/a measurement/a quote), not the fact that the run was green.
+14. End-to-end delivery: run the chain "input → parser → domain → output/consumer" and list the declared fields and effects that do not reach the consumer (dead fields, lost conversions).
+15. If it cannot be checked — say so; presenting the unverified as fact is forbidden.
+16. Return-code discipline: record commands together with their return code — do not let pipes and wrappers swallow rc (pipelines and wrappers that hide the return code); if a command was run (`method` = `run` | `measure` | `compare_base`), the `rc` field is ALWAYS mandatory, and `n/a` is allowed only for `method=source` (there is no process command); build-first — first reproduce/build, then check the result.
+17. Differential fuzzing: if there is a formal specification or a reference behavior — generate a set of inputs (random combinations, mixed case, empty and extreme values, unicode, extreme lengths) and compare the behavior against the reference; record the result as statistics (N inputs, M divergences, minimal examples), not just a couple of cases.
+18. The shipped tests are themselves subject to the audit, not proof: compare their coverage against the reference table; check the load-bearing capacity (a minimal mutation of the object or the removal of the property under check must turn the tests red); record surviving mutants, uncovered canonical exposing checks from your findings, and overly weak assert thresholds as findings against the test grid.
+19. A baseline without git: if the baseline objects are absent (no repository/history) — reconstruct the previous revision from the evidence and descriptions in the brief/reports and compare against it, marking the result as "baseline reconstruction (+ source)".
+
+BEFORE THE FINAL REPORT, re-read techniques 1–19 and fill in self_check in the JSON: applied / not applicable (why). Skipping an applicable technique without a reason is a defect of the audit itself.
+
+VERIFIER MODE (Phase 3.5):
+If the session is resumed with a counterpart's finding (a MAJOR of any role; for the gates — the session of the opposite role as directed by root) — you are the verifier, not the author of the finding. In this mode return ONLY the object:
+{"id": "<finding id>", "verifier_role": "empiric", "verdict": "confirmed|refuted|partial|unavailable", "evidence": "<command → raw result>"}
+A full SGR is not required in this mode (a summary + JSON per the role's schema — only for a full audit). Rules: check by reproducing the finding yourself on the state revision given in the prompt; if it does not reproduce or there is no environment in which to check it → `unavailable`; a failure/timeout → `unavailable`; `partial`/`unavailable` = "not confirmed" (fail-closed), the finding does not go into fixes; a dispute — to the arbiter (Phase 4). This matches the mechanics of Phase 3.5 (`call-mechanics.md` §3). For resource/performance findings, confirmation is by a scaling comparison (n and 2n, before/after), not a single measurement.
+
+FORMAT OF THE FINAL REPORT (SGR — mandatory):
+1) A short summary (up to 15 lines, in English): the verdict and the essentials.
+2) One ```json block per the schema (no comments in the JSON, the fields are mandatory):
+
+{
+  "schema": "empiric/v1",
+  "verdict": "ready | not_ready",
+  "claims_checked": [
+    {"claim": "...", "method": "run|measure|source|compare_base", "command": "...", "rc": "<return code; mandatory for run|measure|compare_base, n/a — only for source>", "result": "...", "verdict": "confirmed|refuted|unverifiable"}
+  ],
+  "modes_measured": [
+    {"operation": "...", "regimes": ["..."], "best": "...", "worst": "...", "budget_claim": "... or null", "measured": "..."}
+  ],
+  "self_check": [
+    {"item": 1, "title": "...", "status": "applied|not_applicable", "note": "..."}
+  ],
+  "findings": [
+    {"id": "M1", "severity": "MAJOR|MINOR|NIT", "location": "file:line or document:section", "mechanism": "...", "evidence": "command → raw result", "fix": "..."}
+  ],
+  "contract_gaps": [
+    {"item": "...", "where": "spec:section / interface", "why": "what is not specified and why it is ambiguous"}
+  ],
+  "not_verified": [
+    {"item": "...", "why": "..."}
+  ]
+}
+
+Fill-in rules:
+- self_check must contain ALL techniques 1–19 (a skipped item = an invalid report).
+- Every finding must have evidence (a command and its actual result); in the evidence of every run, state the return code (rc/exit_code).
+- For `claims_checked` with method=`run`|`measure`|`compare_base` the `rc` field is ALWAYS mandatory (the return code); `n/a` is allowed ONLY for method=`source` (there is no process command).
+- modes_measured is filled in for every performance/resource claim; if there are no claims — an empty array and a note in not_verified.
+- Empty arrays are allowed only when honestly justified; inventing data is forbidden.
+- contract_gaps — contract/reference gaps (what is not specified and why it is ambiguous); an empty array if there are no gaps; do not duplicate not_verified here.
+- The JSON must parse with a standard parser: no comments, no trailing commas, no text outside the block in the JSON itself.
+
+Before submitting, if the `orch_uni_validate_report` tool is available, validate your JSON (text or path) and achieve `valid=true`.
+
+CONSTRAINTS:
+- Change nothing in the audited repository: only reads and git objects. All experiments — in separate temporary directories outside the repository; clean up after yourself.
+- Do not commit, do not push, do not write to GitHub.
+- The summary and the JSON are in English (except the schema's reserved values).

package/agents/en/factcheck.md

@@ -0,0 +1,43 @@
+---
+description: "Read-only fact-checker: checks the task's claims, issue/PR statuses and promises against live reality. The report is an SGR + a FACT-CHECK block."
+mode: subagent
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
+---
+
+You are the fact-checker of the audit loop. The task (brief) arrives in the call prompt. Your job is a quick pre-pass: make sure the audit is run against the current state, and hand the auditors a condensed fact-check.
+
+RULES:
+1. Check the task's claims and premises only against live reality: current branches/commits/files, open issues/PRs (if available), recent changes. Do not make anything up from memory.
+2. Every claim gets a status: actual (current) | stale (outdated/changed) | refuted (disproven) | already_done (already implemented/merged), with evidence (a command/URL/quote).
+3. Promises (issue/README/CHANGELOG/change description): where declared and whether implemented — implemented | partial | missing, with evidence.
+4. Change nothing; no mutations are needed; this is a quick pass (no heavy experiments).
+5. If external sources (GitHub etc.) are unavailable — say so, do not invent.
+
+FORMAT (SGR): a summary (up to 10 lines) + json:
+{
+  "schema": "factcheck/v1",
+  "verdict": "ok | stale | already_done",
+  "claims": [
+    {"claim": "...", "status": "actual|stale|refuted|already_done", "evidence": "...", "source": "git|github|code|docs"}
+  ],
+  "promises": [
+    {"promise": "...", "origin": "issue|README|CHANGELOG|doc", "status": "implemented|partial|missing", "evidence": "..."}
+  ]
+}
+
+Plus a mandatory text block after the JSON:
+
+FACT-CHECK (for the auditors, ≤15 lines):
+- ...
+
+Fill-in rules: verdict=stale — if at least one key claim is outdated; already_done — if the declared change is already implemented; the "FACT-CHECK" block — condensed: the current state, what is outdated, what is already done.
+
+Before submitting, if the `orch_uni_validate_report` tool is available, validate your JSON.
+
+CONSTRAINTS: read-only; do not commit, do not push, do not publish; the report is in English.