opencode-orchestrator-uni 0.1.0 → 0.2.0

package/docs/en/instruction-other-session.md

@@ -0,0 +1,81 @@
+# Instruction: a test run of the audit loop in another session (on another project)
+
+The loop: read-only subagents `factcheck`, `empiric`, `invariant`, `arbiter`, `meta`, `redteam` + the writing `fix-runner` (fixes per the "to close" list).
+The agents are universal (without project specifics). Definitions: your harness's global agents directory (the path depends on the OS) and the harness's project agents directory. A backup copy — in the kit directory (`agents/`).
+
+## How to use
+
+1. Open a session in the target project's directory — or choose the primary agent `orchestrator` (its audit loop is a built-in mode; it is enough to specify the project/change/data/budget).
+2. Copy the prompt below into it and fill in the placeholders:
+   - `<PROJECT_PATH>` — the path to the project;
+   - `<CHANGE>` — a branch / a commit range / an uncommitted diff;
+   - `<BASE>` — the comparison base;
+   - `<DATA>` — the available corpora/test stands/reference materials (paths) and what is allowed to run;
+   - `<BUDGET>` — the time/build limits and prohibitions;
+   - `<MODE>` — `commit` (the light loop) or `release` (the gates with the red team).
+
+## The prompt for the root agent (copy in full)
+
+---
+You are the root orchestrator of the audit. Drive the audit loop to full ready.
+
+Project: <PROJECT_PATH>
+Change: <CHANGE>
+Comparison base: <BASE>
+Available data and test stands: <DATA>
+Budget: <BUDGET>
+Mode: <MODE>
+
+The loop's rules:
+- The auditors are read-only subagents; you make the fixes (micro-fixes) or delegate them to `fix-runner` (medium/large ones). You are the orchestrator: the brief, the launch, the consolidation of the reports, decisions, fixes. You do not audit yourself.
+- Communication — via the brief file and SGR reports. Do NOT poll background subagents: the notifications arrive on their own.
+- The loop lives until FULL ready: all roles ready, no open MAJORs, MINOR/NIT closed or explicitly accepted.
+- Disputed matters are resolved by `arbiter` (disputed items only); the unprovable → the owner's decision: the root frames the question, records the risk and escalates.
+- "Owner" = the user. Publication (push/PR/release) — only after ship and with the owner's confirmation; `fix-runner` does not push anything.
+
+Steps:
+0) Prepare the working directory `audit-<id>` in your environment's temporary area: the brief `case.md` (the template below), the registry `risks.md`.
+   For the initial audit — a "blind" copy of the state (without the history of fixes); for a repeat one — with the fixes delta.
+1) Fact-check (foreground):
+   subagent(agent="factcheck", prompt="Read the brief <path>. Check the theses and premises against live reality (git, upstream issues/PRs, the current code): what is stale, what is already done, which promises have diverged. Return the SGR + the "FACT-CHECK" block.")
+   If verdict=stale/already_done — stop the loop and revise the task.
+2) The pair in parallel (background, one block):
+   subagent(agent="empiric",   background=true, prompt="Brief <path>. FACT-CHECK:\n<block>. Do your role; return the SGR.")
+   subagent(agent="invariant", background=true, prompt="Brief <path>. FACT-CHECK:\n<block>. Do your role; return the SGR.")
+   Save both sessionIDs from the responses.
+3) Summary: parse the SGRs (verdicts, open MAJORs, conflicts by places/classes); materialize the summary reports/summary-<id>.md (for every MAJOR — id, verifier_role, verdict, evidence; the refuted list; accepted risks; the state revision).
+4) Verification of MAJORs (cross-verification, fail-closed): every MAJOR finding is confirmed by the session of the opposite role (not by the author of the finding) —
+   subagent(agent="<sibling>", sessionID="<session of the opposite role>", prompt="A counterpart's finding <id>: <text>. The author's evidence: <command→output>. State revision: <directory hash/commit>. Confirm or refute it by your own reproduction; the default is not confirmed. Return: {id, verifier_role, verdict: confirmed|refuted|partial|unavailable, evidence}.")
+   partial/unavailable = "not confirmed"; a verifier failure/timeout — the same + noise. The refuted ones — into the refuted list; write the statuses into the summary reports/summary-<id>.md; an unconfirmed MAJOR does not go into fixes.
+   Conflicts → subagent(agent="arbiter", prompt="Disputed items: <item → evidence A → evidence B>. For each: confirmed/refuted/undecidable + the prism (reproducibility|contract|falsification|not_applicable; for several — an array) + the way of checking. Only these items.")
+   The summary's verdict (and the verification/arbitration) is recorded BEFORE the fixes and together with the state revision (hash/commit); a fix after the verdict is recorded → a repeat run (re-audit) or an explicit downgrade of the verdict: do not fix before the verdict.
+5) Fixes by threshold: micro-fixes — yourself; medium/large ones — subagent(agent="fix-runner", prompt="To close: <id | location | mechanism | class/area (paths + a search rule for similar places) | repro (before) | acceptance criterion (after)>. Boundaries: <…>; budget/limit: <time, number of fixes>; commit fix-<round>. Return fix-runner/v1."). Before the re-audit check the delta (git show --stat + a key run); update risks.md (closed / accepted-risk with a reason).
+6) Re-audit — resume of the SAME sessions (background, one block):
+   subagent(agent="empiric",   sessionID="<emp>", background=true, prompt="Fixes: <range + the actual list of changed files>; closed: <…>. Check the closure of your findings and the absence of regressions on the new state; return the updated SGR.")
+   subagent(agent="invariant", sessionID="<inv>", background=true, prompt="… same …")
+7) Repeat steps 3–6 until full ready is reached (the number of rounds is unlimited). From round 3 on, unresolved items — the arbiter one by one; recurring false ones — dismiss and record as the audit noise.
+8) Release mode (the gates; order: red team → meta): freeze the candidate →
+   subagent(agent="redteam", background=true, prompt="Brief <path>. The author's submission: <…>. The summary of previous rounds: <…>. Falsification mandate: reproduce every claim with your own instruments; available data: <…>; generate crafted inputs. Return the SGR.")
+   → the same loop (fixes; the red team's MAJOR findings — with verification by the session of the opposite role as directed by the root; a dispute → `arbiter`) with the red team's resume until its ready → subagent(agent="meta", prompt="Reports: <paths>; summary: <path to summary-<id>.md>. Check the MAJOR verification statuses in the summary (verdict + verifier_role); the evidence of every finding; the completeness of the self-checks, the absence of "green tests = checked". Return pass/fail.") → a check of the SHIP condition (below); ship only when it holds.
+   SHIP ⟺ meta.gate=pass ∧ closing_list is empty/closed ∧ coverage_gaps accepted by the owner (a record in risks.md). In all other cases ship is forbidden.
+9) Final: a summary by rounds (the verdicts, what was closed, the accepted risks); save the reports in `reports/` of the audit's working directory.
+
+Brief template `case.md`:
+# Audit <id>: <name>
+State: <path, commit/range; the base>
+Context: <the goal of the change, what the author declares>
+Materials: <diff/paths; what is ABSENT: e.g., git history unavailable>
+Available data and budget: <corpora/reference materials/test stands (paths); whether a build is allowed (an isolated target in a temporary directory); the time limit; what is forbidden>
+Constraints: read-only; experiments in a temporary directory; do not publish
+Report contract: SGR (a summary + ```json per the role's schema)
+
+If a subagent is unavailable ("Agent not found"): check the agent files in your harness's global agents directory (the path depends on the OS) and in the harness's project agents directory; restore from the backup copy in the kit directory (`agents/`).
+---
+
+## What counts as the test's success
+
+- The fact-check ran and either dismissed the stale task or gave a block for the pair.
+- The pair produced SGR reports; the conflicts (if any) were resolved by the arbiter.
+- The loop reached full ready (all verdicts ready; no open MAJORs).
+- `reports\` holds all the reports and the summary `summary-<id>.md`, in `risks.md` — the accepted risks.
+- No agent changed the project (check the target project's `git status`).

package/docs/en/process-ready-loop.md

@@ -0,0 +1,66 @@
+# Process: the run loop to full ready
+
+Rule: the audit is considered complete only when **all roles** have issued `verdict=ready` and all findings are processed. No "stops after N rounds": the loop runs to full ready; when it does not converge — escalation, not endless repeats on the same state.
+
+Numbering: "[N]" — the steps of this document (`process-ready-loop.md`); "Phase N" — the phases of `call-mechanics.md`. Cross-document references state their namespace explicitly.
+
+## Tree
+
+```
+[0] FACT-CHECKER (the actuality of premises/issues/PRs)
+     │
+     ├─ the task is stale/done → STOP (revise the task)
+     ▼
+[1] EMPIRIC ∥ INVARIANT (on state X0)
+     │        └─ conflicts? → ARBITER (disputed items only); MAJOR → independent verification (cross-verification, fail-closed)
+     ▼
+   VERDICT: all ready and no open MAJORs?
+     ├─ YES ──► for the release gates: [4] RED TEAM → [5] META
+     │           (input of [5]: the pair's reports + the red team's report + the summary reports/summary-<id>.md)
+     │           ├─ SHIP ⟺ `meta.gate`=pass ∧ closing_list is empty/closed ∧ coverage_gaps accepted by the owner (a record in risks-<id>.md)
+     │           ├─ otherwise ship is forbidden; a targeted list of non-conformities → fixes/rebuild of the reports → another meta pass; a repeated fail → escalation to the owner
+     │         for a commit/PR: SHIP if there were no fixes after the verdict (the red team and meta are not mandatory)
+     └─ NO ─► [2] FIXES (close the MAJORs; MINOR/NIT — close or explicitly accept with a rationale, a record in risks-<id>.md)
+                ▼
+           [3] NEW STATE X1 (the fixes are committed/recorded)
+                ▼
+           repeat [1] on X1 (both auditors, the same brief)
+                ▼
+           … repeat [1] on Xn until all roles issue ready …
+
+   [A VERDICT EXISTS, THE STATE CHANGED] → repeat [1] (re-audit on the new state) or an explicit downgrade of the verdict
+   [COMMIT/PR] → the line "no fixes after the verdict"
+```
+
+At the release gates the loop is the same, plus after the first full ready — the red team; its findings (including MAJORs — with independent verification by the session of the opposite role) go through the same loop of fixes/re-checks until it, too, issues ready.
+
+## The "full ready" criterion
+
+1. All roles (the empiric, the invariant; at the gates — the red team as well) — `verdict=ready`.
+2. No open MAJORs. MINOR/NIT: closed or **explicitly accepted** with a reason (a record in `risks-<id>.md`; in the summary/PR: "accepted as debt: …").
+3. All discrepancies are resolved by the arbiter; the unprovable → the owner's decision: the root frames the question, records the risk and escalates.
+4. The repeat run goes **by the state after the fixes**, not by the old diff. No "re-votings" on the same snapshot.
+5. At the release gates — `meta` = pass (`gate`=pass), `closing_list` is empty/closed, `coverage_gaps` accepted by the owner (a record in `risks-<id>.md`). **SHIP ⟺ `meta.gate`=pass ∧ `closing_list` is empty/closed ∧ `coverage_gaps` accepted by the owner (a record in `risks-<id>.md`); otherwise ship is forbidden.**
+6. MAJOR findings go into fixes only after independent verification; the verifier's default is "not confirmed" (fail-closed).
+7. The verdict and the verification are recorded together with the state revision (directory hash/commit); any fix after the verdict is recorded → a repeat run (re-audit) or an explicit downgrade of the verdict.
+
+## When the loop "does not converge" — escalation (instead of a stop)
+
+- Round 3+ and still not_ready → the arbiter examines **the remaining items one by one**: confirmed / refuted (a false positive) / undecidable.
+  - "refuted" — the finding is dismissed, recorded as a false positive of the auditor (noise data for calibration);
+  - "undecidable" — the owner's decision: the root frames the question, records the risk and escalates;
+  - "confirmed" — a mandatory fix, the loop continues.
+- A sign of a meaningless continuation: the same false/undecidable findings repeat without new facts. This is not "not ready", this is an audit defect — record it and close it.
+
+## Loop data (per round)
+
+- Input: the diff/state Xn + the fact-checker's report + the list of accepted risks.
+- Output: two SGR reports (the empiric, the invariant) + the arbiter's resolution (if any).
+- The orchestrator's summary: `ready` / `not_ready(the list of open ones)`, what was closed, what was accepted.
+- At the gates, additionally: the summary `reports/summary-<id>.md` — the input of meta `[5]` (Phase 6); the gates' verdicts — the red team (`closing_list`/`coverage_gaps`) and meta (`meta.gate`/`closing_list`/`coverage_gaps`).
+
+## Notes
+
+- "Ready" is not "zero findings" but "all findings are processed": closed or consciously accepted.
+- The variance of single runs is accounted for by the loop itself: the next round gives a new sample; hence the loop to convergence, not "one run in a cage".
+- History confirms the model: PR #37 (bsl-context) — the pair said ready with caveats, acceptance found 8 defects, after the fixes and a repeat acceptance — v0.22.0 and full ready.

package/docs/en/root-runbook.md

@@ -0,0 +1,57 @@
+# Root-runbook: initiating an audit from the primary agent
+
+## Roles
+
+- **Root (the primary agent)** — does not audit: forms the brief, launches subagents, consolidates the reports; for the "unprovable" — the owner's decision: the root frames the question, records the risk and escalates. Maintains the registry of accepted risks, makes fixes as separate commits, decides on "ship".
+- **Subagents** (read-only): `factcheck`, `empiric`, `invariant`, `arbiter`, (at the gates) `redteam`, `meta`.
+
+## Brief template `case-<id>.md` (common to all steps)
+
+```
+# Audit: <task/PR/release>
+State: <path to the sandbox/repo, commit or range; the diff base>
+Context: <what the change is, its goal, what the author declares>
+Materials: <the diff file, base/head paths; what is unavailable (e.g., git history)>
+Constraints: read-only; experiments in a temporary directory; a targeted build; do not publish
+Report format: SGR (a summary + ```json per its own schema)
+```
+
+A "Fact-check (pre-pass): …" block is added to the pair's prompts — 5–15 lines from the fact-checker's report.
+
+## Call checklist (order)
+
+1. **Fact-check**: `subagent(agent="factcheck", prompt="<brief> + check the theses against live reality: git/upstream issues/PRs/code; what is stale, what is already done, which promises have diverged")`.
+   - If "stale/already done" → **STOP** and revise the task (the cheapest saving).
+2. **The pair in parallel**: `subagent(agent="empiric", background=true, prompt="<brief> + the fact-check block")` and the same for `invariant`. Do not poll — wait for notifications.
+3. **Summary by the root**: parse the JSON blocks; compute the verdicts (ready/not_ready), open MAJORs, intersections and discrepancies (by location+mechanism). Materialize the summary artifact `reports/summary-<id>.md` (definition — `call-mechanics.md` §4): for every MAJOR — {id, verifier_role, verdict, evidence}; the refuted list (explicit, even if empty); accepted risks; the state revision (directory hash/commit).
+4. **Verification of MAJORs (cross-verification, fail-closed)**: every MAJOR finding is confirmed independently by **the session of the opposite role** (not by the author of the finding) — `subagent(agent="<sibling>", sessionID=<session of the opposite role>, prompt="A counterpart's finding <id>: <text>. The author's evidence: <command→output>. State revision: <directory hash/commit>. Confirm or refute it by your own reproduction; the default is not confirmed. Return: {id, verifier_role, verdict: confirmed|refuted|partial|unavailable, evidence}.")`. `verifier_role` ≠ the author's role; `partial`/`unavailable` = "not confirmed"; `refuted` — into the refuted list for the summary; a verifier failure/timeout — "not confirmed" + noise. Not confirmed → it does not go into fixes (a dispute → step 5, the arbiter); the verification statuses are written to the summary `reports/summary-<id>.md` (step 3). If a MAJOR finding is independently reproduced by both roles in their own runs — the mutual confirmation counts as verification (both sides in the summary), a separate run is not required. The sessionID in the call is mandatory: without it this is a new session, not a continuation — a step defect.
+5. **The arbiter — only on discrepancies**: `subagent(agent="arbiter", prompt="Disputed items: <item → evidence A → evidence B>. For each: confirmed/refuted/undecidable + a command/quote.")`. The summary's verdict (and the verification/arbitration) is recorded BEFORE the fixes and **together with the state revision** (directory hash/commit); any fix after the verdict is recorded → a repeat run (re-audit) or an explicit downgrade of the verdict: do not fix before the verdict.
+6. **Fixes** by threshold: micro — the root itself; medium/large ones — `fix-runner` (input: the "to close" list — id, location, mechanism, **class/area** (paths + a search rule for similar places), repro (before), acceptance criterion (after), severity — plus the boundaries and the **budget/limit (time, number of fixes)**; output: fix-runner/v1 with before/after/`proof`/tests). Separate commits `fix-<round>`; update the registry: `closed` / `accepted-risk` (with a reason). The root checks the delta before the re-audit. The round's test stand (if the kit ships a verification stand — the tools `tools/kit-verify` and `tools/kit-sync` of the kit directory; in rounds on other projects — only if the stand is explicitly included in the call boundaries): the stand's baseline into the fixer's prompt (if the output is passed — the fixer does not duplicate the run); closure — sync of the copies and a repeat run of the stand; both outputs — in the report's `stand` field. `fix-runner` statuses: `needs_decision` → the root's decision (for a dispute — the arbiter; if the decision is the owner's — escalation) with a record in the risk registry; `not_closed` → another iteration with the same id; the `out_of_scope` field (noticed outside the list) → include in the next "to close" list or escalate.
+7. **Re-audit = resume of the same sessions** (the sessionID from step 2): "Fixes: <range + the actual list of changed files>. Check the closure of your findings and the absence of regressions; return the updated SGR." — historically, that is how it was done (a continuation of the GLM/DS sessions). The sessionID is mandatory: a call without it (a new session instead of a continuation) — a step defect.
+8. **Repeat steps 3–7 until full ready is reached** (the number of rounds is unlimited; all roles ready, MAJOR=0). From round 3 on, unresolved items — the arbiter one by one; recurring false ones — dismiss and record as the audit noise.
+9. **Gates (release; order: red team → meta)**: a frozen commit → `redteam` (the falsification mandate + corpora/test stands) → a loop over its findings (MAJORs — with verification by the session of the opposite role) → `meta` (input: the reports + the summary `reports/summary-<id>.md`; evidence, completeness, the absence of "green tests = checked").
+   - **SHIP ⟺ `meta.gate`=pass ∧ `closing_list` is empty/closed ∧ `coverage_gaps` accepted by the owner (a record in `risks-<id>.md`); otherwise ship is forbidden.**
+   - `meta` → fail: ship is forbidden; a targeted list of non-conformities → fixes/rebuild of the reports → another meta pass; a repeated fail → escalation to the owner. Ship — only after the meta's pass and the fulfillment of the ship condition above.
+
+## Data transfer between nodes
+
+- fact-check → both auditors: a short block in the prompt (5–15 lines);
+- the pair → the root: SGR JSON (machine-readable; keep in `reports/`);
+- the root → the arbiter: **only disputed items** + evidence from both sides;
+- the root → re-audit: the fixes range + a brief "what was closed";
+- the root → the red team: the author's submission + the summary of all previous rounds (the object of falsification);
+- the root → meta: the reports (paths) + the summary `reports/summary-<id>.md`;
+- the root → fix-runner: the "to close" list (with the class/area) + boundaries + budget/limit (time, number of fixes).
+
+## Subtleties
+
+- The `orch_uni_*` tools (if registered by the plugin): the state revision — `orch_uni_snapshot` (aggregate), an SGR report check — `orch_uni_validate_report` (invalid → resume of the session demanding that the SGR be reissued), the roles' sessionID/model/cost — `orch_uni_sessions`; otherwise — manually, as before.
+- The brief and the risk registry — as files; the subagents return the reports into the chat (the `edit deny` rule in `permissions`; `shell` is allowed), the root saves what is needed itself.
+- "Blind" runs — a sandbox without git history (without fix commits); re-audit — on the contrary, the fixes delta is shown.
+- The root's verdict does not substitute for the auditors' verdicts: while both roles are not ready — the loop lives (plus the escalation rules from `process-ready-loop.md`).
+- Timings are approximate: fact-check ~1–2 min, the pair ~5–10 min, the arbiter ~1–3 min per item, the red team — hours (the gates only).
+- Universality: both auditors and the types being added carry no project specifics; all project specifics — in the briefs and reference materials.
+- **Environment preflight (Code Mode)**: if `subagent` is unavailable — the loop does not start; the outcome is "done; the regular audit is deferred" (the revision + compensating checks + the run plan), details — `call-mechanics.md` §8.
+- **A mandatory configuration snapshot after installing/updating the agents**: the configuration snapshot — `tools/config-guard` (if shipped), otherwise save a copy of the configuration manually (otherwise there will be nothing to restore from). Do not mix the sources: agent definitions — the kit directory (`agents/`), configuration — `tools/config-guard` (if shipped).
+- **Snapshot coverage**: the configuration snapshot covers the **configuration** (your harness's global configuration directory: agent definitions, the main config, general instructions, etc.); the kit's docs (`docs/`, `agents/`, `README.md`) are NOT covered by the snapshot — the kit remains the source, and the run reports are kept in `reports/`. The snapshot check returns 0 when there are no divergences and 2 when problems are found.
+- The configuration guard (if shipped): the default restore only adds the missing elements and does NOT overwrite existing ones; a full overwrite from the snapshot — only with explicit confirmation (`-Force` or an equivalent).

package/docs/{call-mechanics.md → ru/call-mechanics.md}

@@ -228,7 +228,7 @@ subagent({agent:"redteam", background:true,
 
 Среда сессии может смениться в ходе работы: прямые инструменты заменяются вызовом через `execute`+каталог, инструмент `subagent` пропадает — аудиторский цикл в такой сессии невозможен.
 
-- Преflight: перед аудиторской фазой проверь наличие `subagent`; нет — цикл не запускай.
+- Preflight: перед аудиторской фазой проверь наличие `subagent`; нет — цикл не запускай.
 - Статус итога: «готово; штатный аудит отложен». В итог: ревизия состояния (коммит/хэш каталога), компенсирующие проверки списком (явно как проверки), план прогона в обычной сессии.
 - Запрещено: выдавать самопроверку/`ai`-ревью за независимый аудит; помечать задачу прошедшей аудит; писать «ready».
 - Хендофф: аудит на зафиксированной ревизии в обычной сессии; либо роли запускаются отдельными процессами `opencode run --agent <роль> "<бриф>"` в каталоге проекта (если среда даёт shell — например, AetherShell); sessionID ролей сохранить (Фаза 3.5/re-audit).

package/docs/{root-runbook.md → ru/root-runbook.md}

@@ -51,7 +51,7 @@
 - Вердикт root'а не подменяет вердикты аудиторов: пока обе роли не ready — цикл живёт (плюс правила эскалации из `process-ready-loop.md`).
 - Тайминги ориентировочно: факт-чек ~1–2 мин, пара ~5–10 мин, арбитр ~1–3 мин на пункт, ред-тим — часы (только ворота).
 - Универсальность: оба аудитора и добавляемые типы не содержат проектной конкретики; вся проектная специфика — в брифах и эталонах.
-- **Преflight среды (Code Mode)**: если `subagent` недоступен — цикл не запускается; итог — «готово; штатный аудит отложен» (ревизия + компенсирующие проверки + план прогона), детали — `call-mechanics.md` §8.
+- **Preflight среды (Code Mode)**: если `subagent` недоступен — цикл не запускается; итог — «готово; штатный аудит отложен» (ревизия + компенсирующие проверки + план прогона), детали — `call-mechanics.md` §8.
 - **Обязательный снимок конфигурации после установки/обновления агентов**: снимок конфигурации — `tools/config-guard` (если поставляется), иначе вручную сохранить копию конфигурации (иначе восстанавливать будет нечего). Источники не смешивать: определения агентов — каталог комплекта (`agents/`), конфигурация — `tools/config-guard` (если поставляется).
 - **Покрытие снимка**: снимок конфигурации покрывает **конфигурацию** (глобальный каталог конфигурации вашего харнесса: определения агентов, основной конфиг, общие инструкции и пр.); доки комплекта (`docs/`, `agents/`, `README.md`) снимком НЕ покрыты — комплект остаётся источником, а отчёты прогонов сохраняются в `reports/`. Проверка снимка возвращает 0 при отсутствии расхождений и 2 при найденных проблемах.
 - Хранитель конфигурации (если поставляется): восстановление по умолчанию докопирует только отсутствующие элементы и НЕ перезаписывает существующие; полная перезапись из снимка — только с явным подтверждением (`-Force` или аналог).

package/index.ts

@@ -34,6 +34,13 @@
  * a Markdown agent file that sets its own model still wins, because config is
  * applied after package plugins.
  *
+ * Localization: agent definitions and process documents ship per locale
+ * (`agents/<locale>/`, `docs/<locale>/` — currently `ru` and `en`).
+ * `options.locale` selects one; otherwise the locale is auto-detected from
+ * `LC_ALL`/`LC_MESSAGES`/`LANG` and the runtime's Intl locale, falling back to
+ * `DEFAULT_LOCALE` (`en`). A locale that ships no content falls back with a
+ * warning — first to `DEFAULT_LOCALE`, then to the flat pre-locale layout.
+ *
  * The only runtime dependency is `gray-matter` (frontmatter parsing). OpenCode
  * installs package plugin dependencies automatically.
  */
@@ -50,16 +57,68 @@ export const PLUGIN_ID = "orchestrator.uni"
 /** Name of the reference that exposes the kit's process documents. */
 export const REFERENCE_NAME = "audit-kit"
 
-/** Absolute path to the shipped agent definitions (`agents/*.md`). */
+/** Absolute path to the shipped agent definitions (`agents/<locale>/*.md`). */
 export const AGENTS_DIRECTORY = fileURLToPath(new URL("./agents/", import.meta.url))
 
-/** Absolute path to the shipped process documents (`docs/*.md`). */
+/** Absolute path to the shipped process documents (`docs/<locale>/*.md`). */
 export const DOCS_DIRECTORY = fileURLToPath(new URL("./docs/", import.meta.url))
 
+/** Locales the kit ships; `DEFAULT_LOCALE` content is the fallback for others. */
+export const SUPPORTED_LOCALES = ["ru", "en"] as const
+
+export type Locale = (typeof SUPPORTED_LOCALES)[number]
+
+/** Fallback when no locale is configured or detected. */
+export const DEFAULT_LOCALE: Locale = "en"
+
+/** `<root>/<locale>/` — where one locale's content lives. */
+export function localeDirectory(root: string, locale: Locale): string {
+  return path.join(root, locale)
+}
+
+/** Language subtag of a locale-ish tag: `ru-RU`, `en_US.UTF-8` → `ru`, `en`. */
+export function parseLocaleTag(value: unknown): Locale | undefined {
+  if (typeof value !== "string") return undefined
+  const language = value
+    .trim()
+    .toLowerCase()
+    .split(/[-_.@]/, 1)[0]
+  return (SUPPORTED_LOCALES as readonly string[]).includes(language) ? (language as Locale) : undefined
+}
+
+/** First supported candidate wins; `DEFAULT_LOCALE` when none is. */
+export function pickLocale(candidates: readonly string[]): Locale {
+  for (const candidate of candidates) {
+    const locale = parseLocaleTag(candidate)
+    if (locale) return locale
+  }
+  return DEFAULT_LOCALE
+}
+
+/** Detection candidates: deliberate env overrides first, then the OS locale. */
+function localeCandidates(): string[] {
+  const candidates: string[] = []
+  for (const key of ["LC_ALL", "LC_MESSAGES", "LANG"] as const) {
+    const value = process.env[key]
+    if (value) candidates.push(value)
+  }
+  try {
+    candidates.push(Intl.DateTimeFormat().resolvedOptions().locale)
+  } catch {
+    // No Intl data in this runtime — the env values or the default decide.
+  }
+  return candidates
+}
+
 /** Description shown next to the `audit-kit` reference in session context. */
-const REFERENCE_DESCRIPTION =
-  "Process documents of the orchestrator agent kit (audit loop): call-mechanics.md, " +
-  "process-ready-loop.md, root-runbook.md, instruction-other-session.md."
+const REFERENCE_DESCRIPTIONS: Record<Locale, string> = {
+  ru:
+    "Процессные документы комплекта оркестратора (аудиторский цикл): call-mechanics.md, " +
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md.",
+  en:
+    "Process documents of the orchestrator agent kit (audit loop): call-mechanics.md, " +
+    "process-ready-loop.md, root-runbook.md, instruction-other-session.md.",
+}
 
 /** Frontmatter keys this loader understands; anything else is reported and ignored. */
 const SUPPORTED_KEYS: ReadonlySet<string> = new Set(["description", "mode", "model", "permissions"])
@@ -231,32 +290,81 @@ function parseAgentFile(id: string, source: string): KitAgent | undefined {
   }
 }
 
-/** Read and parse every shipped `agents/*.md` definition (stable file order). */
-async function loadKitAgents(): Promise<KitAgent[]> {
-  const entries = await readdir(AGENTS_DIRECTORY, { withFileTypes: true })
-  const files = entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
-    .map((entry) => entry.name)
-    .sort()
+/** Markdown file names in a directory, sorted; `[]` when the directory is absent. */
+async function listMarkdown(directory: string): Promise<string[]> {
+  try {
+    const entries = await readdir(directory, { withFileTypes: true })
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+      .map((entry) => entry.name)
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Resolve one content root for a locale: `<root>/<locale>/` first, then
+ * `<root>/<DEFAULT_LOCALE>/`, then the flat pre-locale layout. Every fallback
+ * is reported — a silently wrong language would be worse than a warning.
+ */
+async function resolveLocalized(
+  root: string,
+  what: string,
+  locale: Locale,
+): Promise<{ directory: string; files: string[] }> {
+  const steps: readonly { readonly directory: string; readonly label: string }[] = [
+    { directory: localeDirectory(root, locale), label: `"${locale}/"` },
+    { directory: localeDirectory(root, DEFAULT_LOCALE), label: `"${DEFAULT_LOCALE}/"` },
+    { directory: root, label: "the flat pre-locale layout" },
+  ]
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index]!
+    const files = await listMarkdown(step.directory)
+    if (files.length === 0) continue
+    if (index > 0) {
+      warn(`${what}: no content shipped for locale "${locale}" — falling back to ${step.label}`)
+    }
+    return { directory: step.directory, files }
+  }
+  return { directory: localeDirectory(root, locale), files: [] }
+}
+
+/** Read and parse every shipped `agents/<locale>/*.md` definition (stable file order). */
+async function loadKitAgents(locale: Locale): Promise<KitAgent[]> {
+  const { directory, files } = await resolveLocalized(AGENTS_DIRECTORY, "agents", locale)
   const agents: KitAgent[] = []
   for (const file of files) {
-    const source = await readFile(path.join(AGENTS_DIRECTORY, file), "utf8")
+    const source = await readFile(path.join(directory, file), "utf8")
     const agent = parseAgentFile(file.replace(/\.md$/, ""), source)
     if (agent) agents.push(agent)
   }
   return agents
 }
 
+/** `options.locale`, when present and supported; invalid values fall through to detection. */
+function readLocaleOptions(options: unknown): Locale | undefined {
+  if (typeof options !== "object" || options === null) return undefined
+  const raw = (options as Record<string, unknown>).locale
+  if (raw === undefined) return undefined
+  const locale = parseLocaleTag(raw)
+  if (!locale) {
+    warn(`options.locale: expected one of ${SUPPORTED_LOCALES.join("|")}, got ${JSON.stringify(raw)}, ignored`)
+  }
+  return locale
+}
+
 async function setup(ctx: Plugin.Context): Promise<Plugin.Cleanup | undefined> {
   const models = readModelOptions(ctx.options)
-  const agents = await loadKitAgents()
+  const locale = readLocaleOptions(ctx.options) ?? pickLocale(localeCandidates())
+  const agents = await loadKitAgents(locale)
   const defined = new Set(agents.map((agent) => agent.id))
   for (const id of models.perAgent.keys()) {
     if (!defined.has(id)) warn(`options.agents["${id}"]: unknown kit agent, override ignored`)
   }
   const overrides = new Map([...models.perAgent].filter(([id]) => defined.has(id)))
   if (agents.length === 0) {
-    warn(`no agent definitions found in ${AGENTS_DIRECTORY}`)
+    warn(`no agent definitions found for locale "${locale}" under ${AGENTS_DIRECTORY}`)
   } else {
     await ctx.agent.transform((editor) => {
       for (const agent of agents) {
@@ -283,11 +391,12 @@ async function setup(ctx: Plugin.Context): Promise<Plugin.Cleanup | undefined> {
   // rendered for models in session context. The promise editor's parameter type uses
   // the public client shape, which does not declare it, so the source is built as a
   // variable to keep the excess-property check out of the way.
+  const docs = await resolveLocalized(DOCS_DIRECTORY, "docs", locale)
   const docsReference = {
     type: "local" as const,
     // AbsolutePath is a branded schema type; the runtime value is a plain path.
-    path: DOCS_DIRECTORY as Reference.LocalSource["path"],
-    description: REFERENCE_DESCRIPTION,
+    path: docs.directory as Reference.LocalSource["path"],
+    description: REFERENCE_DESCRIPTIONS[locale],
   }
   await ctx.reference.transform((editor) => {
     if (editor.get(REFERENCE_NAME)) return

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-orchestrator-uni",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native OpenCode V2 plugin that registers the orchestrator agent kit (root orchestrator, audit subagents, fix-runner) and exposes the kit's process documents as the audit-kit reference.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "agents",
     "docs",
     "README.md",
+    "README.ru.md",
     "LICENSE"
   ],
   "scripts": {
@@ -43,6 +44,7 @@
     "test": "bun test ./test/",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "check:locales": "bun tools/locale-check.ts",
     "eval": "bun eval/run.ts",
     "eval:selfcheck": "bun eval/selfcheck.ts",
     "eval:recompute": "bun eval/recompute.ts"