opencode-orchestrator-uni 0.3.0 → 0.4.0

package/agents/ru/context-lint.md

@@ -0,0 +1,90 @@
+---
+description: "Read-only аудитор AGENTS.md/SPEC.md/CLAUDE.md: бюджет токенов, проверяемость, дубли, ссылки, полнота SPEC. Отчёт — SGR + closing_list."
+mode: subagent
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
+---
+
+Ты — read-only аудитор файлов инструкций для AI-агентов: `AGENTS.md`, `SPEC.md`, `CLAUDE.md`. Проверяешь token-эффективность и качество; ничего не меняешь.
+
+ВХОД: путь к репозиторию или файлам — в промпте вызова; если не задан — текущий каталог. Найди целевые файлы в корне и на 3 уровня каталогов ниже, исключая `node_modules`, `.git`, `.ae`, `dist`, `build`, `target`, `vendor`. Скан от корня подхватывает и фикстуры вроде `eval/`; передай явный путь, если нужны только канонические файлы.
+
+ЗАМЕР: для каждого файла посчитай строки, слова, символы, оценку токенов (`кириллица/3 + прочее/4`), число заголовков, таблиц и списков. Используй только чтение (`find`, `wc`, `grep`, `test -e`); сборку, тесты, миграции и деплой не запускай.
+
+Если доступен инструмент `orch_uni_context_lint`, сначала вызови его по целевому пути; используй его findings как детерминированную базу, затем добавь семантические проверки (конфликты, тестируемость, intent SPEC).
+
+Коды инструмента: `E_NO_FILES` → verdict=fail, один элемент `files` с `path: "-"`, `kind: "other"` и finding `CTX-000`; `E_LIMIT_FILE` / `E_LIMIT_FILES` / `E_OUT_OF_ROOT` → verdict=fail с `CTX-000` (kind=unverified_command или other), в evidence — код и путь из ошибки. Ошибка — не отчёт: она объявляет `schema: "context-lint-failure/v1"` и валидируется только по этой схеме (`{ok: false, code, message, path?, bytes?, files?, max?}`). `truncated: true` означает, что список находок усечён: MINOR/INFO могут отсутствовать, а при переполнении MAJOR остаётся MAJOR-маркер `truncated` в `closing_list` — отметь это в `summary`.
+
+Ничего не пропускается молча: цель ссылки вне корня workspace, каталог глубже лимита 3, пропущенный обходом junction и незакрытые fence, `<pre>` или HTML-комментарий отдаются INFO-находками (`was not checked`, `was skipped`, `depth limit 3`, `the rest of the file is masked`), поэтому pass не скрывает непроверенную область. Исключение — незакрытый `<code>`: он маскирует только остаток своей строки и не репортится; отмена наблюдается между файлами, каждые 2048 строк построчной проверки и в каждом гейте.
+
+Потолки → `truncated`: кандидаты-ссылки → MAJOR-маркер; находки на файл/глобально → один маркер (MAJOR, если выпал MAJOR, иначе INFO); у дублей внутреннего потолка нет. Все строки сканируются целиком: потолка и маркера длинной строки нет. `max_files` отказывает рано — обход останавливается на первом файле выше лимита, а не разворачивает всё дерево. Любой потолок ставит `truncated: true` и называется в `summary`.
+
+AGENTS.md — проверь:
+1. Бюджет: >200 строк или >2500 токенов — MAJOR; 150–200 строк — MINOR.
+2. Команды: есть install/build/test/one test/lint/run, с флагами и рабочей директорией; команда считается только в коде, таблице задач или секции Commands, HTML-комментарий командой не является (`<!-- npm install -->` не в счёт), а `make` требует цели (`make build`), поэтому проза «Make sure …» — не команда; пересказ очевидного (`npm test`) — MINOR.
+3. Границы: generated/vendor/prod/secrets/migrations — иначе MINOR.
+4. Приоритеты и область действия — иначе MINOR.
+5. Vague-фразы: clean, best practices, robust, «аккуратно», «правильно», «оптимально» — MINOR; три и более различных термина — MAJOR (инструмент считает различные термины).
+6. Дубли строк длиной ≥40 символов; пересказ README/линтера — MINOR.
+7. Относительные ссылки и пути существуют — иначе MAJOR.
+8. Плейсхолдеры `<...>`, `TODO`, `TBD`, `FIXME` — MAJOR.
+9. Дата/версия в первых трёх строках (ломает prefix cache) — MINOR.
+10. Каждая строка проверяема: команда, запрет с границей, инвариант или ссылка — иначе MINOR.
+
+SPEC.md — проверь:
+1. Non-goals: 3–7 пунктов — иначе MAJOR.
+2. Требования R1..Rn: одно наблюдаемое поведение на требование; «and»-цепочки — MINOR.
+3. У каждого R есть AC, у каждого AC есть Test — иначе MAJOR.
+4. AC измеримы (число или наблюдаемый результат); «быстро/удобно/надёжно» без метрики — MAJOR.
+5. Инварианты и краевые случаи — иначе MINOR.
+6. Трассировка R→AC→task→test — иначе MINOR.
+7. Не более трёх открытых вопросов, у каждого owner и дата; `TODO`/`TBD` вне блока — MAJOR.
+8. Frontmatter: status/owner/version — иначе MINOR.
+9. Нет HOW (стек, файлы, классы) в требованиях — иначе MINOR.
+10. Контракты — ссылками, не копиями — иначе MINOR.
+
+ОБЩИЕ ПРОВЕРКИ:
+- Конфликт «always/never» или приоритетов между файлами — MAJOR.
+- Дубли между AGENTS.md и SPEC.md — MINOR.
+- Целевых файлов нет — verdict=fail, один элемент `files` с `path: "-"`, `kind: "other"` и finding `CTX-000`, kind=missing_section.
+- Каждое finding: id `CTX-NNN`, severity, kind, evidence `file:line`, detail, fix.
+- verdict=fail при любом MAJOR; `closing_list` = id всех MAJOR. verdict=pass только если MAJOR нет.
+
+ФОРМАТ (SGR): резюме (до 10 строк) + json:
+{
+  "schema": "context-lint/v1",
+  "ok": true,
+  "verdict": "pass | fail",
+  "closing_list": [],
+  "truncated": false,
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "kind": "agents | spec | claude | other",
+      "lines": 0,
+      "words": 0,
+      "chars": 0,
+      "tokens_est": 0,
+      "findings": [
+        {
+          "id": "CTX-001",
+          "severity": "MAJOR | MINOR | INFO",
+          "kind": "budget | vague | duplicate | broken_link | missing_section | conflict | unverified_command | other",
+          "evidence": "AGENTS.md:42",
+          "detail": "...",
+          "fix": "..."
+        }
+      ]
+    }
+  ],
+  "summary": "..."
+}
+
+Перед сдачей проверь JSON текстом через `orch_uni_validate_report` и добейся `valid=true`; отчёт возвращай текстом в ответе — файлы не создавай.
+
+ОГРАНИЧЕНИЯ: read-only (edit deny + запрет в промпте); shell разрешён только для проверок; не запускать сборку/тесты/миграции/деплой; отчёт по-русски, без воды. Плейсхолдеры — только `<...>` (три и более точки) и `TODO`/`TBD`/`FIXME`; `<DoD>`, `<название>` — не плейсхолдеры.

package/agents/ru/empiric.md

@@ -76,7 +76,7 @@ permissions:
 - contract_gaps — пробелы контракта/эталона (что не задано и почему неоднозначно); пустой массив, если пробелов нет; не дублировать сюда not_verified.
 - JSON должен парситься стандартным парсером: без комментариев, без висячих запятых, без текста вне блока в самом JSON.
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON (текст или путь) и добейся `valid=true`.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ:
 - Ничего не менять в аудируемом репозитории: только чтение и git-объекты. Все эксперименты — в отдельных временных каталогах вне репозитория; после себя убирать.

package/agents/ru/factcheck.md

@@ -38,6 +38,6 @@ permissions:
 
 Правила заполнения: verdict=stale — если хотя бы один ключевой тезис устарел; already_done — если заявленное изменение уже реализовано; блок «ФАКТ-ЧЕК» — сжато: актуальное состояние, что устарело, что уже сделано.
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ: read-only; не коммитить, не пушить, не публиковать; отчёт — по-русски.

package/agents/ru/fix-runner.md

@@ -53,7 +53,7 @@ permissions:
   ]
 }
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ:
 - Никаких рефакторингов и «улучшений» вне списка.

package/agents/ru/invariant.md

@@ -71,7 +71,7 @@ permissions:
 - Пустые массивы допустимы только когда это честно обосновано; выдумывать данные запрещено.
 - JSON должен парситься стандартным парсером: без комментариев, без висячих запятых, без текста вне блока в самом JSON.
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON (текст или путь) и добейся `valid=true`.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ:
 - Ничего не менять в аудируемом репозитории; только чтение и git-объекты. Эксперименты — в отдельных временных каталогах, если нужны.

package/agents/ru/meta.md

@@ -41,7 +41,7 @@ permissions:
 
 `gate` — **единственный блокирующий агрегат** (pass только когда все отчёты pass, MAJOR-находки верифицированы и `closing_list` пуст/закрыт); `verdict` — синоним `gate` (оставлен для совместимости, отдельного смысла не несёт). Происхождение `closing_list`: это **копия** `closing_list` отчёта ред-тима (id находок, обязательных к закрытию; на воротах ред-тим обязателен) — при расхождении состава с отчётом ред-тима мета выносит **fail**. `coverage_gaps` — что не удалось проверить; ship допускается только при `gate`=pass и явном принятии `coverage_gaps` владельцем (запись в `risks-<id>.md`).
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ:
 - Read-only; не искать новые дефекты кода (только отчёты); отчёты не править.

package/agents/ru/orchestrator.md

@@ -19,6 +19,7 @@ permissions:
 4. Делегируй субагентам:
    - исследование по коду — `explore`; по темам и данным — `general`;
    - проверка изменения/плана/релиза — аудиторский контур (см. режим ниже);
+   - аудит инструкций (AGENTS.md, SPEC.md, CLAUDE.md) — `context-lint` (read-only, SGR + closing_list);
    - реализация — сам (мелкое) или `fix-runner` (правки по списку «к закрытию»), крупные задачи — `general`;
    - параллельные задачи запускай в одном блоке (background) и не опрашивай — уведомления придут сами.
 5. Проверяй результат: критерий приёмки должен быть подтверждён доказательством (команда и фактический вывод), а не «зелёными тестами» самими по себе. Спорное решай явно (кроме аудиторского режима — там спорное идёт только арбитру); недоказуемое → решение владельца: root оформляет вопрос, фиксирует риск и эскалирует.
@@ -31,7 +32,7 @@ permissions:
 - Факт-чек вернул `stale`/`already_done` → СТОП, пересмотр задачи (пару не запускать).
 - re-audit = resume тех же сессий с дельтой: правки (диапазон), список закрытого; аудитор проверяет свои находки и регрессии на новом состоянии; переголосование по старому снапшоту запрещено.
 - Невалидный отчёт: пустой/битый/неразбираемый отчёт или вердикт вне enum → дефект шага: resume той же сессии с требованием перевыпустить SGR; повторный сбой → эскалация владельцу.
-- Если доступны инструменты `orch_uni_*`: ревизия состояния → `orch_uni_snapshot` (aggregate — хэш каталога для вердикта/верификации); проверка отчёта роли → `orch_uni_validate_report` (путь или текст; `valid=false` → resume той же сессии с требованием перевыпустить SGR); sessionID/роль/модель/стоимость запущенных субагентов → `orch_uni_sessions`; иначе — вручную, как прежде.
+- Если доступны инструменты `orch_uni_*`: ревизия состояния → `orch_uni_snapshot` (aggregate — хэш каталога для вердикта/верификации); проверка отчёта роли → `orch_uni_validate_report` (предпочтительно `text`; файлы — `write`, не shell-heredoc: Windows-лимит 32 767; `valid=false` → resume той же сессии с требованием перевыпустить SGR); sessionID/роль/модель/стоимость запущенных субагентов → `orch_uni_sessions`; иначе — вручную, как прежде.
 - Верификация MAJOR (Фаза 3.5): каждая MAJOR-находка проходит независимую проверку ролью, отличной от автора (resume сессии противоположной роли; `verifier_role` ≠ роль автора); в промпт верификации включай ревизию состояния (хэш каталога/коммит). Вердикт верификатора: `{id, verifier_role, verdict: confirmed|refuted|partial|unavailable, evidence}`; `partial`/`unavailable` = «не подтверждена» (fail-closed) — в правки не идёт (спор → арбитр); сбой/таймаут верификатора → `unavailable` + шум аудита; `refuted` — в refuted-список сводки; статусы верификации дописываются в свод `reports/summary-<id>.md`.
 - Вызовы верификатора (Фаза 3.5) и re-audit — только resume сессий соответствующих ролей: перед вызовом сверь, что передан сохранённый sessionID (из ответа запуска пары/роли); вызов без sessionID = дефект шага (это новая сессия, а не продолжение): перезапусти с sessionID и отметь в сводке.
 - Если MAJOR-находка независимо воспроизведена обеими ролями в их собственных прогонах — это засчитывается как перекрёстная верификация: зафиксируй в своде обе стороны (`verifier_role` каждой роли + evidence), отдельный прогон верификатора не требуется.

package/agents/ru/redteam.md

@@ -49,7 +49,7 @@ permissions:
 
 `claim_partial` — заявление верно частично либо вместо него найден другой дефект. `claim_partial` с обнаруженным дефектом обязан породить запись в `findings` (и в `closing_list`, если дефект блокирующий).
 
-Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON.
+Перед сдачей, если доступен инструмент `orch_uni_validate_report`, проверь свой JSON **текстом** (`text`) и добейся `valid=true`; файлы создавай инструментом `write`, не shell-heredoc: на Windows команда длиннее 32 767 символов обрезается, и heredoc зависает.
 
 ОГРАНИЧЕНИЯ:
 - Read-only; мутации — только во временных каталогах; песочницу/проект не менять.

package/docs/en/call-mechanics.md

@@ -192,7 +192,7 @@ Persistence (all kit documents): the SGR reports of all roles, including **the S
 ### The `orch_uni_*` tools (if registered by the plugin)
 
 - the state revision → `orch_uni_snapshot` (aggregate = the directory hash): recorded together with the verdict and the verification;
-- a role's report → `orch_uni_validate_report` (path or text): `valid=false` → a step defect, resume the same session and demand that the SGR be reissued; do not ignore `warnings`;
+- a role's report → `orch_uni_validate_report` (prefer `text`; files — `write`, not a shell heredoc: the Windows limit is 32,767): `valid=false` → a step defect, resume the same session and demand that the SGR be reissued; do not ignore `warnings`;
 - the roles' sessionIDs, their model and cost → `orch_uni_sessions`;
 - if the tools are unavailable, work manually, as before.
 
@@ -238,5 +238,5 @@ The session's environment can change in the course of work: direct tools are rep
 - Preflight: before the audit phase, check that `subagent` is available; if not — do not start the loop.
 - The outcome status: "done; the regular audit is deferred". The outcome includes the state revision (commit/directory hash), compensating checks as a list (explicitly as checks), and the run plan in a normal session.
 - Forbidden: passing a self-check/`ai` review off as an independent audit; marking the task as audited; writing "ready".
-- Handoff: the audit is run on the recorded revision in a normal session; or the roles are launched as separate processes `opencode run --agent <role> "<brief>"` in the project directory (if the environment provides a shell — for example, AetherShell); keep the roles' sessionIDs (Phase 3.5/re-audit).
+- Handoff: the audit is run on the recorded revision in a normal session; or the roles are launched as separate processes `opencode run --agent <role> "<brief>"` in the project directory (if the environment provides a shell); keep the roles' sessionIDs (Phase 3.5/re-audit).
 - If the environment is restored before completion — run the deferred audit and update the verdict.

package/docs/en/context-efficiency.md

@@ -0,0 +1,196 @@
+# Token-efficient AGENTS.md and SPEC.md
+
+An instruction file is a budget of attention, not documentation. Every line is paid for: it participates in every session's context and competes with the task. The goal is the minimum set of testable rules that cannot be inferred from the code and are needed in most sessions.
+
+## Budget
+
+| File | Target | Ceiling |
+|---|---:|---:|
+| Global `AGENTS.md` | 25–40 lines / <500 tokens | 60 lines |
+| Root `AGENTS.md` | 100–200 lines / 1–2k tokens | 200 lines |
+| Nested `AGENTS.md` | 20–60 lines / <700 tokens | 100 lines |
+| `SPEC.md` | 80–150 lines / ≤1.5k words | 2k words |
+| `ADR` | 30–60 lines / <700 tokens | 100 lines |
+
+`orch_uni_context_lint` applies one root budget (`max_lines`, 200 lines by default) and one SPEC word budget (`max_words`, 1500 by default — the target from the table; pass `max_words: 2000` for the ceiling). The per-level figures above are authoring guidance, not separate tool limits. The tool reports what it did not check (links outside the root, directories below depth 3, an unclosed fence) as INFO findings; a `pass` therefore never means "unverified".
+
+Selection rule: if a line is not testable, is inferable from code/linters, or is needed in fewer than half of sessions — delete it or move it to a link.
+
+## AGENTS.md: 12 rules
+
+1. Commands first: install, build, test, one test, lint, run; with flags and a working directory.
+2. Only the non-inferable: flags, traps, layer order, prohibitions, versions.
+3. One instruction per line, imperative, testable.
+4. Style belongs to the linter; do not restate the README or the language standard.
+5. Explicit "Never" and "Ask first": secrets, `dist/`, prod, migrations, dependencies.
+6. Precedence in the text: what overrides what; on a conflict, stop and ask.
+7. One source of truth: `AGENTS.md` plus a symlink/import for `CLAUDE.md`.
+8. Links instead of inline copies; inline only what is needed every time.
+9. Add a rule after a repeated agent mistake, not "for the future".
+10. Delete dead rules: they tax every request.
+11. Stable content on top, dates/branches/tasks at the bottom (prefix cache).
+12. Review the file as code; update it when tooling/CI changes.
+
+## AGENTS.md template
+
+```md
+# AGENTS.md
+
+## Precedence
+1. The user's explicit instruction in the task.
+2. `SPEC.md` of the active feature.
+3. The nearest `AGENTS.md`.
+4. This file.
+5. The global `AGENTS.md`.
+On a conflict, stop and ask.
+
+## Commands
+| Task | Command | Note |
+|---|---|---|
+| Install | `<...>` | `<version>` |
+| Build | `<...>` | `<flag>` |
+| Tests | `<...>` | `<limit>` |
+| One test | `<...>` | `<name>` |
+| Lint/types | `<...>` | |
+| Run | `<...>` | `<port>` |
+
+## Boundaries
+- `<path>/` is generated; do not edit.
+- `<path>/` is vendored; do not edit.
+- New files go to `<path>`.
+
+## Conventions
+- <One testable rule per line.>
+
+## Verification
+`<analyze>` → `<lint>` → `<test>`.
+Done = all commands green + `<DoD>`.
+
+## Never / ask first
+- Never: secrets, `dist/`, prod, applied migrations.
+- Ask first: DB schema, public API, new dependencies, CI.
+
+## Pointers
+- `SPEC.md` — the feature contract.
+- `docs/adr/` — decisions.
+- `docs/pitfalls.md` — traps.
+```
+
+## SPEC.md: 12 rules
+
+1. One feature per file, 1–3 pages; larger — split via a roadmap.
+2. Stable IDs (`R1`, `AC1.1`); never renumber.
+3. One requirement — one observable behavior.
+4. EARS or Given/When/Then — consistently; MUST/SHOULD/MAY — sparingly.
+5. No HOW: stack, files, classes belong in plan/design/ADR.
+6. Contracts as links, not copies.
+7. Non-goals: 3–7 items.
+8. Invariants separate from acceptance criteria.
+9. Tables for AC and traceability; prose for context only.
+10. Frontmatter: `status`, `owner`, `version`, `supersedes`; no changelog in the body.
+11. At most three open questions, each with an owner and a date; `TBD` elsewhere is forbidden.
+12. DoD and metrics are measurable; "faster" without a number does not count.
+
+## SPEC.md template
+
+```md
+---
+id: SPEC-000
+title: <name>
+status: draft
+owner: "@team"
+version: 1.0.0
+supersedes: —
+---
+
+# SPEC-000: <name>
+
+## 1. Context and problem
+<3–5 lines: who suffers, what hurts, why now.>
+
+## 2. Goal and non-goals
+**Goal:** <one sentence>.
+**Non-goals:** <3–7 items we deliberately do not do>.
+<!-- one item per line with `-` at 0–4 spaces; a wrapped paragraph is one item;
+     fenced, `<pre>` and bullets indented 5+ are code, not items. -->
+
+## 3. Scenarios
+| ID | Role | Goal | Value | Independent test |
+|---|---|---|---|---|
+| S1 | <...> | <...> | <...> | <...> |
+
+## 4. Requirements (EARS)
+- **R1** — WHEN <trigger>, THE SYSTEM SHALL <result>.
+- **R2** — IF <condition>, THEN THE SYSTEM SHALL <...>.
+
+## 5. Acceptance criteria
+| AC | R | Given | When | Then | Test |
+|---|---|---|---|---|---|
+| AC1.1 | R1 | <...> | <...> | <...> | `test_...` |
+
+## 6. Invariants and edge cases
+- Invariant: <always true>.
+- Empty/limit/concurrency/error: <...>.
+
+## 7. Contracts
+Links: `<openapi.yaml>`, `<schema.sql>`, `<types.ts>`.
+
+## 8. Non-functional requirements
+| Metric | Target | How we check |
+|---|---|---|
+| Latency p95 | <...> | <...> |
+
+## 9. Success metrics
+- **SC-1** — <number and how to check>.
+
+## 10. Open questions
+- **Q1** — <...>; owner: <...>; due <date>.
+
+## 11. Traceability
+| R | AC | Task | Test |
+|---|---|---|---|
+| R1 | AC1.1 | T1 | `test_...` |
+
+## 12. Definition of Done
+- [ ] AC closed.
+- [ ] Tests green.
+- [ ] Contracts and docs/ADR updated.
+```
+
+## Command /agents-md
+
+1. Decide the mode: audit an existing file or draft from scratch.
+2. For an audit: `orch_uni_context_lint` → `context-lint`; show the SGR and `closing_list`.
+3. For a draft: collect facts and ask at most 8 questions; do not invent commands or paths.
+4. Fill the template; stay within 150–200 lines.
+5. Run the linter; show the diff and open questions.
+6. Change the canonical file only after approval; apply fixes through `fix-runner`.
+
+## Command /spec
+
+1. Capture the brief and ask at most 5 clarifying questions.
+2. Non-goals, priorities and metrics are owned by the owner; do not invent them.
+3. Fill the template: EARS, AC with tests, invariants, traceability, DoD.
+4. Run `orch_uni_context_lint` and `context-lint`; show the diff and questions.
+5. Change the canonical file only after approval.
+
+## Review
+
+- [ ] `AGENTS.md` ≤200 lines, `SPEC.md` ≤1.5k words.
+- [ ] Every line is testable.
+- [ ] No duplicates with README/linter/CI.
+- [ ] Precedence and boundaries are explicit.
+- [ ] Every relative link exists.
+- [ ] Every R has an AC, every AC has a test.
+- [ ] Non-goals and DoD are present.
+- [ ] A baseline on 10–20 tasks exists.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is bad | What to do |
+|---|---|---|
+| Auto-generation "just in case" | −0.5…−2% success, +20–23% cost | Write manually, high-signal only |
+| Restating README/architecture | Duplication, zero effect | Link to docs |
+| Duplicating the linter | Tokens on what is already checked | Linter/CI |
+| Generic phrases ("write clean code") | Not testable | Imperative + example |
+| Conflicts between layers | The model chooses arbitrarily | Explicit precedence |

package/docs/en/root-runbook.md

@@ -45,7 +45,7 @@ A "Fact-check (pre-pass): …" block is added to the pair's prompts — 5–15 l
 
 ## 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 the session and demand that the SGR be reissued), the roles' sessionID/model/cost — `orch_uni_sessions`; otherwise — manually, as before.
+- The `orch_uni_*` tools (if registered by the plugin): the state revision — `orch_uni_snapshot` (aggregate), an SGR report check — `orch_uni_validate_report` (text; files — `write`, not a heredoc; invalid → resume the session and demand 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 to the chat (the `edit deny` rule in `permissions`; `shell` is allowed), the root itself saves what is needed.
 - "Blind" runs — a sandbox without git history (without fix commits); re-audit — by contrast, the fixes delta is shown.
 - The root's verdict does not substitute for the auditors' verdicts: until both roles are ready, the loop lives (plus the escalation rules from `process-ready-loop.md`).

package/docs/ru/call-mechanics.md

@@ -192,7 +192,7 @@ subagent({agent:"redteam", background:true,
 ### Инструменты `orch_uni_*` (если зарегистрированы плагином)
 
 - ревизия состояния → `orch_uni_snapshot` (aggregate = хэш каталога): фиксируется вместе с вердиктом и верификацией;
-- отчёт роли → `orch_uni_validate_report` (путь или текст): `valid=false` → дефект шага, resume той же сессии с требованием перевыпустить SGR; не пропускать `warnings`;
+- отчёт роли → `orch_uni_validate_report` (предпочтительно `text`; файлы — `write`, не shell-heredoc: Windows-лимит 32 767): `valid=false` → дефект шага, resume той же сессии с требованием перевыпустить SGR; не пропускать `warnings`;
 - sessionID ролей, их модель и стоимость → `orch_uni_sessions`;
 - инструменты недоступны — работаем вручную, как прежде.
 
@@ -238,5 +238,5 @@ subagent({agent:"redteam", background:true,
 - Preflight: перед аудиторской фазой проверь наличие `subagent`; нет — цикл не запускай.
 - Статус итога: «готово; штатный аудит отложен». В итог: ревизия состояния (коммит/хэш каталога), компенсирующие проверки списком (явно как проверки), план прогона в обычной сессии.
 - Запрещено: выдавать самопроверку/`ai`-ревью за независимый аудит; помечать задачу прошедшей аудит; писать «ready».
-- Хендофф: аудит на зафиксированной ревизии в обычной сессии; либо роли запускаются отдельными процессами `opencode run --agent <роль> "<бриф>"` в каталоге проекта (если среда даёт shell — например, AetherShell); sessionID ролей сохранить (Фаза 3.5/re-audit).
+- Хендофф: аудит на зафиксированной ревизии в обычной сессии; либо роли запускаются отдельными процессами `opencode run --agent <роль> "<бриф>"` в каталоге проекта (если среда даёт shell); sessionID ролей сохранить (Фаза 3.5/re-audit).
 - Если среда восстановилась до завершения — проведи отложенный аудит и обнови вердикт.

package/docs/ru/context-efficiency.md

@@ -0,0 +1,196 @@
+# Token-efficient AGENTS.md и SPEC.md
+
+Файл инструкций — это бюджет внимания, а не документация. Оплачивается каждая строка: она участвует в контексте каждой сессии и конкурирует с задачей. Цель — минимум проверяемых правил, которые нельзя вывести из кода и которые нужны в большинстве сессий.
+
+## Бюджет
+
+| Файл | Цель | Потолок |
+|---|---:|---:|
+| Глобальный `AGENTS.md` | 25–40 строк / <500 токенов | 60 строк |
+| Корневой `AGENTS.md` | 100–200 строк / 1–2k токенов | 200 строк |
+| Вложенный `AGENTS.md` | 20–60 строк / <700 токенов | 100 строк |
+| `SPEC.md` | 80–150 строк / ≤1,5k слов | 2k слов |
+| `ADR` | 30–60 строк / <700 токенов | 100 строк |
+
+`orch_uni_context_lint` применяет один бюджет корня (`max_lines`, по умолчанию 200 строк) и бюджет слов SPEC (`max_words`, по умолчанию 1500 — цель из таблицы; потолок 2k включается через `max_words: 2000`). Цифры по уровням выше — ориентир для автора, а не отдельные лимиты инструмента. Инструмент сообщает о том, что не проверял (ссылки вне корня, каталоги глубже глубины 3, незакрытый фенс), INFO-находками, поэтому `pass` никогда не означает «непроверено».
+
+Правило отбора: если строка не проверяема, выводима из кода/линтера или нужна реже половины сессий — удалить либо вынести в ссылку.
+
+## AGENTS.md: 12 правил
+
+1. Команды — в начало: install, build, test, one test, lint, run; с флагами и рабочей директорией.
+2. Только невыводимое: флаги, ловушки, порядок слоёв, запреты, версии.
+3. Одна инструкция — одна строка, императив, проверяемо.
+4. Стиль — линтеру; не пересказывать README и стандарт языка.
+5. Явные «Never» и «Ask first»: секреты, `dist/`, prod, миграции, зависимости.
+6. Приоритеты — в тексте: что переопределяет что; при конфликте — остановись и спроси.
+7. Один источник правды: `AGENTS.md` + симлинк/импорт для `CLAUDE.md`.
+8. Ссылки вместо инлайна; инлайнить только то, что нужно всегда.
+9. Правило добавлять после повторной ошибки агента, а не «на будущее».
+10. Мёртвое правило удалять: это налог на каждый запрос.
+11. Стабильное — вверх, даты/ветки/задачи — вниз (prefix cache).
+12. Ревьюить файл как код; менять при смене тулинга/CI.
+
+## Шаблон AGENTS.md
+
+```md
+# AGENTS.md
+
+## Приоритеты
+1. Явное указание пользователя в задаче.
+2. SPEC.md активной фичи.
+3. Ближайший AGENTS.md.
+4. Этот файл.
+5. Глобальный AGENTS.md.
+При конфликте — остановись и спроси.
+
+## Команды
+| Задача | Команда | Примечание |
+|---|---|---|
+| Установка | `<...>` | `<версия>` |
+| Сборка | `<...>` | `<флаг>` |
+| Тесты | `<...>` | `<лимит>` |
+| Один тест | `<...>` | `<имя>` |
+| Линт/типы | `<...>` | |
+| Запуск | `<...>` | `<порт>` |
+
+## Границы
+- `<path>/` — сгенерировано, не редактировать.
+- `<path>/` — вендорное, не редактировать.
+- Новые файлы — в `<path>`.
+
+## Конвенции
+- <Одно проверяемое правило на строку.>
+
+## Проверка
+`<analyze>` → `<lint>` → `<test>`.
+Готово = все команды зелёные + `<DoD>`.
+
+## Никогда / сначала спроси
+- Никогда: секреты, `dist/`, prod, применённые миграции.
+- Сначала спроси: схема БД, публичный API, новые зависимости, CI.
+
+## Указатели
+- `SPEC.md` — контракт фичи.
+- `docs/adr/` — решения.
+- `docs/pitfalls.md` — ловушки.
+```
+
+## SPEC.md: 12 правил
+
+1. Одна фича — один файл, 1–3 страницы; больше — split через roadmap.
+2. Стабильные ID (`R1`, `AC1.1`), не перенумеровывать.
+3. Одно требование — одно наблюдаемое поведение.
+4. EARS или Given/When/Then — единообразно; MUST/SHOULD/MAY — редко.
+5. Никакого HOW: стек, файлы, классы — в plan/design/ADR.
+6. Контракты — ссылками, не копиями.
+7. Non-goals — 3–7 пунктов.
+8. Инварианты — отдельно от acceptance criteria.
+9. Таблицы — для AC и трассировки; проза — для контекста.
+10. Frontmatter: `status`, `owner`, `version`, `supersedes`; без changelog в теле.
+11. Не более трёх открытых вопросов, у каждого owner и дата; `TBD` в других местах запрещён.
+12. DoD и метрики — измеримые; «быстрее» без числа не считается.
+
+## Шаблон SPEC.md
+
+```md
+---
+id: SPEC-000
+title: <название>
+status: draft
+owner: "@team"
+version: 1.0.0
+supersedes: —
+---
+
+# SPEC-000: <название>
+
+## 1. Контекст и проблема
+<3–5 строк: кто страдает, в чём боль, почему сейчас.>
+
+## 2. Цель и non-goals
+**Цель:** <одно предложение>.
+**Non-goals:** <3–7 пунктов «сознательно не делаем»>.
+<!-- один пункт на строку с `-` и отступом 0–4; перенесённый абзац — один пункт;
+     фенс, `<pre>` и bullet с отступом 5+ — код, не пункт. -->
+
+## 3. Сценарии
+| ID | Роль | Цель | Ценность | Независимый тест |
+|---|---|---|---|---|
+| S1 | <...> | <...> | <...> | <...> |
+
+## 4. Требования (EARS)
+- **R1** — WHEN <триггер>, THE SYSTEM SHALL <результат>.
+- **R2** — IF <условие>, THEN THE SYSTEM SHALL <...>.
+
+## 5. Acceptance criteria
+| AC | R | Given | When | Then | Test |
+|---|---|---|---|---|---|
+| AC1.1 | R1 | <...> | <...> | <...> | `test_...` |
+
+## 6. Инварианты и краевые случаи
+- Инвариант: <всегда истинно>.
+- Пусто/лимит/конкурентность/ошибка: <...>.
+
+## 7. Контракты
+Ссылки: `<openapi.yaml>`, `<schema.sql>`, `<types.ts>`.
+
+## 8. Нефункциональные требования
+| Метрика | Цель | Как проверяем |
+|---|---|---|
+| Latency p95 | <...> | <...> |
+
+## 9. Метрики успеха
+- **SC-1** — <число и способ проверки>.
+
+## 10. Открытые вопросы
+- **Q1** — <...>; owner: <...>; до <дата>.
+
+## 11. Трассировка
+| R | AC | Task | Test |
+|---|---|---|---|
+| R1 | AC1.1 | T1 | `test_...` |
+
+## 12. Definition of Done
+- [ ] AC закрыты.
+- [ ] Тесты зелёные.
+- [ ] Контракты и docs/ADR обновлены.
+```
+
+## Команда /agents-md
+
+1. Определи режим: аудит существующего файла или черновик с нуля.
+2. Для аудита: `orch_uni_context_lint` → `context-lint`; покажи SGR и `closing_list`.
+3. Для черновика: собери факты и задай не более 8 вопросов; не выдумывай команды и пути.
+4. Заполни шаблон; уложись в 150–200 строк.
+5. Прогони линтер, покажи diff и открытые вопросы.
+6. Канонический файл меняй только после подтверждения; правки — через `fix-runner`.
+
+## Команда /spec
+
+1. Зафиксируй бриф и задай не более 5 уточняющих вопросов.
+2. Non-goals, приоритеты и метрики утверждает владелец; не придумывай их.
+3. Заполни шаблон: EARS, AC с тестами, инварианты, трассировка, DoD.
+4. Прогони `orch_uni_context_lint` и `context-lint`; покажи diff и вопросы.
+5. Канонический файл меняй только после подтверждения.
+
+## Ревью
+
+- [ ] `AGENTS.md` ≤200 строк, `SPEC.md` ≤1,5k слов.
+- [ ] Каждая строка проверяема.
+- [ ] Нет дублей с README/линтером/CI.
+- [ ] Приоритеты и границы прописаны.
+- [ ] Все относительные ссылки существуют.
+- [ ] У каждого R есть AC, у каждого AC есть тест.
+- [ ] Non-goals и DoD на месте.
+- [ ] Есть baseline на 10–20 задачах.
+
+## Анти-паттерны
+
+| Анти-паттерн | Почему плохо | Что делать |
+|---|---|---|
+| Автогенерация «на всякий случай» | −0,5…−2% успеха, +20–23% косты | Писать вручную, только высокосигнальное |
+| Пересказ README/архитектуры | Дублирование, нулевой эффект | Ссылка на docs |
+| Дублирование линтера | Токены на то, что и так проверяется | Линтер/CI |
+| Общие фразы («пиши чисто») | Непроверяемо | Императив + пример |
+| Противоречия между уровнями | Модель выбирает произвольно | Явные приоритеты |

package/docs/ru/root-runbook.md

@@ -45,7 +45,7 @@
 
 ## Тонкости
 
-- Инструменты `orch_uni_*` (если зарегистрированы плагином): ревизия состояния — `orch_uni_snapshot` (aggregate), проверка SGR-отчёта — `orch_uni_validate_report` (невалиден → resume сессии с перевыпуском SGR), sessionID/модель/стоимость ролей — `orch_uni_sessions`; иначе — вручную, как прежде.
+- Инструменты `orch_uni_*` (если зарегистрированы плагином): ревизия состояния — `orch_uni_snapshot` (aggregate), проверка SGR-отчёта — `orch_uni_validate_report` (text; файлы — `write`, не heredoc; невалиден → resume сессии с перевыпуском SGR), sessionID/модель/стоимость ролей — `orch_uni_sessions`; иначе — вручную, как прежде.
 - Бриф и реестр рисков — файлами; отчёты субагенты возвращают в чат (правило `edit deny` в `permissions`; `shell` разрешён), root сохраняет нужное сам.
 - «Слепые» прогоны — песочница без git-истории (без фикс-коммитов); re-audit — наоборот, дельта правок показывается.
 - Вердикт root'а не подменяет вердикты аудиторов: пока обе роли не ready — цикл живёт (плюс правила эскалации из `process-ready-loop.md`).