@spec-box/sdd 0.10.0 → 0.12.0

package/README.md

@@ -24,11 +24,12 @@ cd <репозиторий продукта>     # spec-box (.tms.json) или O
 sbox init --host claude       # .sbox/config.yaml, шаблоны .sbox/project/*.md, .gitignore, скиллы и агенты Claude Code
 # заполнить .sbox/project/*.md
 sbox doctor                   # структурная проверка документации, спецификаций и сред запуска
+sbox help                     # справка для агентов и людей: указатель тем и руководства инструментов (sbox-contract help, sbox-wiki help, sbox-browser help)
 sbox change new add-search --title "Поиск по каталогу" --request "Добавить поле поиска на главную"
 sbox next --change add-search # пакет для первой роли (researcher)
 ```
 
-Дальше цикл ведёт скилл `/sbox-run` в Claude Code: он вызывает `sbox next`, запускает субагента нужной роли, сдаёт его ответ через `sbox report` и останавливается на гейтах. Гейты решает человек: `sbox approve <gate>` или `sbox reject <gate> --comment "..."`.
+Дальше цикл ведёт скилл `/sbox-run` в Claude Code или `$sbox-run` в Codex: он вызывает `sbox next`, запускает субагента нужной роли, сдаёт его ответ через `sbox report` и останавливается на гейтах. Гейты решает человек: `sbox approve <gate>` или `sbox reject <gate> --comment "..."`.
 
 ## Что где лежит
 
@@ -39,14 +40,15 @@ src/core/        доменная модель, конфиг, состояние
 src/adapters/    spec/spec-box, spec/openspec — истина и дельты в двух форматах; runner/claude, runner/codex — среды агентов;
                  repo/github, repo/local — хостинг репозитория; host/skills — раскладки скиллов по хостам, host/claude — агенты Claude Code
 src/cli/         команды commander: init, doctor, host, change, next, report, approve, reject,
-                 status, instructions, validate, archive, log
+                 status, instructions, validate, archive, log, help
 src/contract/    sbox-contract: модель поведения, конфигурация, поиск, дельты и применение
 src/wiki/        sbox-wiki: индекс и кеш Markdown, поиск, страницы, ссылки и валидация
 src/browser/     sbox-browser: демон с Chrome на сессию, клиент через локальный сокет, команды страницы,
                  снимок дерева доступности со ссылками, поиск и установка браузера, вход человеком, перенос состояния
 assets/roles/    определения ролей (Markdown): researcher, planner, tester, implementer, reviewer, verifier…
 assets/schema/   граф артефактов по умолчанию и инструкции к ним
-assets/skills/   скиллы хостов (единый источник): sbox-run, sbox-approve, sbox-browser; копируются в папку хоста при init и host install
+assets/skills/   скиллы хостов (единый источник): sbox-run, sbox-approve, sbox-browser, sbox-contract, sbox-wiki; копируются в папку хоста
+                 при init и host install, роли видят их в указателе tools пакета и читают через help
 assets/templates/ шаблоны артефактов изменения
 assets/project/  шаблоны категорий проектной документации
 assets/ci/       шаблоны GitHub Actions и Dockerfile
@@ -73,7 +75,45 @@ sbox change rate <id> --score 4               # оценка результат
 sbox prompt show project-docs                 # промпт для заполнения .sbox/project/*.md под адаптер проекта
 ```
 
-Модели и усилие по ролям задаются в `runner.models` и `runner.efforts` (по умолчанию opus только для planner и challenger, effort medium); после правки выполните `sbox host install --target claude`. Среды: `claude` через Claude Agent SDK (нужен `ANTHROPIC_API_KEY` для CI; локально годится вход Claude Code), `codex` через `codex exec` (в конфиге `runner.codex.executable`, например бинарник из ChatGPT.app). Репозиторий: `repo.adapter: github` с токеном в `GITHUB_TOKEN`; `local` только коммитит.
+Модель и effort задаются по профилям отдельно в `runner.claude.profiles` и `runner.codex.profiles`; после правки выполните `sbox host install --target claude`. Среды: `claude` через Claude Agent SDK (нужен `ANTHROPIC_API_KEY` для CI; локально годится вход Claude Code), `codex` через `codex exec` (в конфиге `runner.codex.executable`, например бинарник из ChatGPT.app). Репозиторий: `repo.adapter: github` с токеном в `GITHUB_TOKEN`; `local` только коммитит.
+
+## Профили моделей
+
+Одна политика выбора для headless и материалов Claude Code: роль и оценка сложности определяют профиль `simple`, `medium` или `complex`, затем выбранный раннер подставляет пару `model` + `effort`.
+
+```yaml
+runner:
+  default: codex
+  roleProfiles:             # необязательная фиксация профиля роли
+    planner: complex
+    challenger: complex
+    reviewer: complex
+  claude:
+    profiles:
+      simple:  { model: claude-sonnet-5, effort: low }
+      medium:  { model: claude-sonnet-5, effort: medium }
+      complex: { model: claude-opus-5, effort: high }
+  codex:
+    profiles:
+      simple:  { model: gpt-5.6-terra, effort: low }
+      medium:  { model: gpt-5.6-terra, effort: medium }
+      complex: { model: gpt-5.6-sol, effort: high }
+```
+
+Пример показывает встроенные значения. Профили можно задавать частично: остальные поля получают дефолты. Доступность конкретной модели и поддержка effort зависят от установленного раннера и учётной записи.
+
+По умолчанию planner/challenger/reviewer используют complex, distiller — simple, остальные — medium. Оценка планировщика `complexity.implementation` переключает tester/implementer: простая → simple, обычная → medium, высокая → complex. Оценка complexity.review сохраняется для аудита, но не ослабляет независимое ревью: reviewer остаётся complex. При возвратах оценка может повышаться. Явный `roleProfiles.<роль>` фиксирует профиль и имеет приоритет над автоматическим выбором. Размер small/normal/large определяет артефакты и не меняет профиль сам по себе.
+
+```bash
+sbox models --json                           # обе среды, профили по ролям
+sbox models --change add-search --json       # с учётом сложности изменения
+sbox next --change add-search --runner claude --brief --json
+sbox host install --target claude            # обновить определения агентов
+```
+
+`next` возвращает `execution` с раннером, профилем, моделью, effort и именем агента выбранного хоста. `/sbox-run` использует это имя; устанавливаются варианты `sbox-<роль>-simple|medium|complex` и базовый `sbox-<роль>`. При изменении профиля/модели/effort предыдущая сессия не продолжается. Для Codex генерируются `.codex/agents/*.toml`, устанавливается общий скилл в `.agents/skills/sbox-run` и добавляется управляемый раздел `AGENTS.md`. Пользовательский `.codex/config.toml` не меняется. После установки откройте новую сессию Codex в доверенном проекте. Если клиент не поддерживает выбор пользовательских агентов, скилл использует `sbox run --runner codex --max-runs 1` с теми же настройками.
+
+**Миграция:** общие `runner.models`, `runner.efforts`, `runner.defaultEffort` удалены и вызывают понятную ошибку конфигурации. Перенесите настройки в профили нужного раннера, при необходимости задайте roleProfiles, удалите старые поля и переустановите материалы хоста. Автоматический перенос не выполняется: старая таблица не указывает, какому раннеру принадлежит модель.
 
 ## Браузер для проверки интерфейса
 
@@ -95,7 +135,7 @@ sbox-browser state save auth.json                     # перенести вх
 sbox-browser stop
 ```
 
-Существующий браузер вместо установки: флаг `--executable`, переменная `SBOX_BROWSER_EXECUTABLE` или `browser.executable` в `.sbox/config.yaml`; без них по порядку проверяются кэш инструмента, кэш puppeteer, системный Chrome, Chromium, Edge и Brave. Сессия это фоновый процесс с браузером: команды идут к нему через локальный сокет, поэтому страница, куки, консоль и сетевые ошибки сохраняются между вызовами; `--session <имя>` даёт несколько независимых браузеров, простой 30 минут завершает сессию. Настройки в секции `browser` конфига: `executable`, `headless`, `profile`, `baseUrl`, `cacheDir`, `viewport`, `timeoutMs`, `idleMinutes`; те же значения задаются переменными `SBOX_BROWSER_EXECUTABLE`, `SBOX_BROWSER_HEADLESS`, `SBOX_BROWSER_PROFILE`, `SBOX_BROWSER_BASE_URL`, `SBOX_BROWSER_CACHE_DIR` (каталог инструмента: `SBOX_BROWSER_HOME`) и глобальными флагами `--profile`, `--session`, `--timeout`, `--cwd`. Все команды поддерживают `--json`, ошибки разбора аргументов тоже приходят в JSON-конверте. Профили и файлы состояния содержат секреты входа и живут в `~/.sbox/browser`, вне репозитория. Скилл `sbox-browser` лежит в `assets/skills` и копируется в папку хоста командой `sbox host install --target claude | codex`; агентам researcher, tester и verifier он подключается по `metadata.roles` (в Claude Code полем `skills`).
+Существующий браузер вместо установки: флаг `--executable`, переменная `SBOX_BROWSER_EXECUTABLE` или `browser.executable` в `.sbox/config.yaml`; без них по порядку проверяются кэш инструмента, кэш puppeteer, системный Chrome, Chromium, Edge и Brave. Сессия это фоновый процесс с браузером: команды идут к нему через локальный сокет, поэтому страница, куки, консоль и сетевые ошибки сохраняются между вызовами; `--session <имя>` даёт несколько независимых браузеров, простой 30 минут завершает сессию. Настройки в секции `browser` конфига: `executable`, `headless`, `profile`, `baseUrl`, `cacheDir`, `viewport`, `timeoutMs`, `idleMinutes`; те же значения задаются переменными `SBOX_BROWSER_EXECUTABLE`, `SBOX_BROWSER_HEADLESS`, `SBOX_BROWSER_PROFILE`, `SBOX_BROWSER_BASE_URL`, `SBOX_BROWSER_CACHE_DIR` (каталог инструмента: `SBOX_BROWSER_HOME`) и глобальными флагами `--profile`, `--session`, `--timeout`, `--cwd`. Все команды поддерживают `--json`, ошибки разбора аргументов тоже приходят в JSON-конверте. Профили и файлы состояния содержат секреты входа и живут в `~/.sbox/browser`, вне репозитория. Скилл `sbox-browser` лежит в `assets/skills` и копируется в папку хоста командой `sbox host install --target claude | codex`; ролям researcher, tester и verifier он показывается в указателе `tools` пакета по `metadata.roles`, а руководство агент читает командой `sbox-browser help`, когда браузер понадобился.
 
 ## Контракт поведения продукта
 
@@ -139,6 +179,8 @@ sbox-wiki validate --json
 
 Валидация проверяет типы метаданных, уникальность id, локальные ссылки и якоря заголовков; ссылки из блоков кода не учитываются. Внешние URL не проверяются, ссылки за пределы wiki запрещены; HTML-ссылки и пользовательские HTML-якоря не поддерживаются. Код выхода 1 означает ошибку; отсутствие summary/read_when — предупреждение. Скилл `sbox-wiki` устанавливается для Claude и Codex через `sbox host install`; `sbox doctor` использует ту же проверку wiki.
 
+Аудит плана обязателен: `plan → [гейт plan] → challenge → cover`. Challenger проверяет артефакты против запроса и кода, ищет пропущенные сценарии и возвращает блокирующие замечания планировщику. После исправления повторяются гейт и аудит; отчёты сохраняются в `evidence/challenge-N.md`. Человеческие гейты зависят от автономности, аудит — нет. Изменения, уже прошедшие планирование до обновления, продолжаются с текущей фазы; при возврате в plan проходят новый аудит.
+
 ## Состояние
 
 Готово (этапы 1 и 2): конфиг и раскладка `.sbox/`, жизненный цикл изменения с гейтами, возвратами и бюджетом (`parked`), ревизия и lock `change.yaml`, пакеты и receipt запусков, приём отчётов с проверками (артефакты, дельты, задачи, защищённые тесты, дрейф change-set, disposition и `delivery_narrative` ревьюера), запечатывание change-set после реализации, адаптер spec-box, категории документации и структурный `doctor`, материалы для Claude Code, адаптеры сред Claude и Codex с надзором и одним транспортным повтором, `run`/`stop`/`watch`, адаптер GitHub с идемпотентной доставкой и каналом гейтов через комментарии, отчёты тестов jest/vitest/playwright и покрытие, шаблоны CI и Dockerfile.
@@ -149,4 +191,13 @@ sbox-wiki validate --json
 
 Готово также: папка `runs/` не переносится в архив (ответы ролей и квитанции остаются в истории ветки, `delivery_narrative` и запуски в `change.yaml`; `archive.runs: true` сохраняет её), `sbox-browser` для проверки интерфейса (сессии с Chrome через `puppeteer-core`, необязательная установка браузера, вход человеком с постоянным профилем, снимок дерева доступности для агентов, перенос состояния входа), проверка браузера в `sbox doctor`.
 
-Не готово: дискавери и правила (этап 3), Arcadia и Codex-материалы для хоста (этап 4), межрепозиторный протокол (этап 5), роутер и дистилляция wiki (этап 6), продолжение сессий Codex, семантический `doctor --deep`.
+Не готово: дискавери и правила (этап 3), Arcadia (этап 4), межрепозиторный протокол (этап 5), роутер и дистилляция wiki (этап 6), семантический `doctor --deep`.
+
+Для Codex в существующем проекте:
+
+```bash
+sbox host install --target codex
+sbox models --runner codex
+```
+
+В новой сессии вызовите `$sbox-run`. Headless-раннер сохраняет ID сессии и продолжает её при возврате к той же роли с теми же настройками; старые клиенты без нужных возможностей resume запускают новую сессию. При первоначальной настройке доступен `sbox init --host codex`. Агент возвращает полный отчёт оркестратору; тот сохраняет его и передаёт CLI. Headless-вариант без интерактивного клиента: `sbox run --runner codex --change <id>`.

package/assets/help/log.md

@@ -0,0 +1,12 @@
+---
+description: Журнал изменения log.md — теги, приоритет записей и команда sbox log add
+---
+
+# Журнал изменения
+
+Файл `log.md` в папке изменения хранит однострочные записи `- [TAG] дата автор: текст`. Теги: `[CODE]` проверенный факт о коде, `[RULE]` принятое правило, `[TASK]` событие, `[HUMAN]` предпочтение человека.
+
+- Добавить: `sbox log add --change <id> --tag CODE "<факт с путём>"`. Одна строка до 300 знаков; автор по умолчанию роль и номер выданного пакета.
+- Прочитать: файл из `files.log` пакета или `sbox log show --change <id> [--tag CODE] --json`.
+
+Приоритет: запись `[CODE]` сильнее факта из evidence или раннего артефакта, если она появилась позже. Опровергнутый факт фиксируй записью, evidence не правь. Противоречие утверждённому артефакту (proposal после гейта, дельты, design) это блокер категории «артефакт», а не запись. После мержа записи `[CODE]` и `[RULE]` переносит в wiki роль distiller; `[TASK]` и `[HUMAN]` остаются в изменении.

package/assets/help/packet.md

@@ -0,0 +1,19 @@
+---
+description: Пакет роли packet.json — что означают его поля и в каком порядке их читать
+---
+
+# Пакет роли
+
+Пакет это данные для одного запуска роли; путь к нему приходит в сообщении `packet: <путь>`. Пути внутри относительно корня репозитория. Текста роли в файле нет: он уже в системном промпте агента.
+
+Читай в таком порядке:
+
+1. `objective`, `feedback` — цель запуска и, при повторном запуске, замечание человека с гейта или блокер предыдущей роли.
+2. `ownership`, `authority`, `constraints`, `rules` — что можно писать (`readOnly: true` запрещает любые изменения файлов), ограничения запуска, правила проекта (ADR) с путями.
+3. `files` — запрос (`request`), журнал (`log`), артефакты по видам, evidence, документация проекта по категориям, страницы wiki с `read_when`, файлы истины спецификаций.
+4. `instructions` — инструкции к артефактам этой фазы: шаблон, требования, путь записи `resolvedOutputPath`; `specAdapterInstructions` — формат дельт спецификаций.
+5. `changeset`, `verificationReport`, `wiring` — запечатанный диф, отчёт верификатора и кандидаты подключения нового модуля (фазы verify и review).
+6. `resultFile`, `resultFormat`, `stop` — куда писать ответ, как его завершать (`sbox help result`), когда остановиться.
+7. `tools` — инструменты, доступные роли: `when` говорит, когда инструмент нужен, `help` даёт команду руководства (`sbox help <тема>`, `sbox-contract help`, `sbox-wiki help`, `sbox-browser help`), `commands` перечисляет самые частые вызовы дословно; остальные команды читай в руководстве, когда инструмент понадобился.
+
+`change`, `role`, `phase`, `runId`, `execution` описывают сам запуск; `execution` это запрошенные модель и усилие, а не доказательство фактического запуска.

package/assets/help/result.md

@@ -0,0 +1,28 @@
+---
+description: Блок sbox-result в ответе роли — статусы, блокеры и поля по ролям
+---
+
+# Блок sbox-result
+
+Ответ роли заканчивается YAML-блоком с первой строкой `# sbox-result`. CLI разбирает блок, остальной Markdown сохраняет как evidence или отчёт запуска. Ответ без блока считается неуспешным запуском.
+
+```yaml
+# sbox-result
+status: готово | утверждение | заблокировано
+blocker: { category: артефакт | тесты | реализация | внешний | пользователь | нет, artifact: <id артефакта>, message: "" }
+```
+
+- `status: заблокировано` требует категорию блокера, отличную от «нет», и точное сообщение; категория «артефакт» требует `artifact` (specs, design, tasks…).
+- `status: утверждение` возвращает только planner на фазе propose: изменение уходит на гейт proposal.
+
+## Поля по ролям
+
+- **researcher**: `request` — разбор запроса, по строке на явное утверждение: `{ quote: "дословная цитата", status: подтверждено | противоречит | не проверено, evidence: "путь и факт" }`. CLI сверяет цитаты с текстом запроса; без поля отчёт не принимается.
+- **planner, фаза propose**: `size: small | normal | large`; `complexity: { implementation, review }` со значениями простая | обычная | высокая; `skip_specs: true`, если поведение не меняется; `deviations: [{ subject: запрос | evidence, text, decision, reason }]` — отступления proposal от запроса или evidence, обязательны при противоречиях исследователя.
+- **planner, фаза plan**: `questions: [{ id: Q1, priority: P0 | P1 | P2, text }]`; вопрос P0 останавливает изменение до ответа человека.
+- **tester**: `protected` — глобы созданных и изменённых тестовых файлов, они становятся защищёнными от реализатора; `verified` — выполненные проверки одной строкой каждая.
+- **implementer**: `verified`.
+- **verifier**: `checks: [{ id: V1, purpose, result: PASS | FAIL | PARTIAL | NOT_RUN, evidence }]`, `gaps: [{ id: G1, environment, oracle, risk }]`, `verified`. Хотя бы один FAIL означает статус «заблокировано».
+- **reviewer**: `findings: [{ level: blocking | non-blocking, file, text }]`; в фазе review `dispositions: [{ item, disposition: satisfied | manual_gap_accepted | change_required | blocked, reason }]` по каждому не-PASS пункту и пробелу верификатора, а при статусе «готово» `delivery_narrative: { title, delta, why, preserved, rollout, rollback }` — единственный источник текста пул-реквеста.
+
+Полный контракт и машина состояний: docs/design.md, раздел 5.

package/assets/hosts/claude/agent.md

@@ -1,10 +1,10 @@
 ---
-name: sbox-{{role}}
+name: {{name}}
 description: {{description}}
 tools: {{tools}}
 model: {{model}}
 effort: {{effort}}
-{{skills}}---
+---
 
 Ты выполняешь роль {{role}} инструмента @spec-box/sdd. Во входном сообщении путь к JSON-пакету (`packet`). Прочитай пакет целиком: там цель, допущенные файлы, ограничения, правила проекта, инструкции к артефактам и путь `resultFile`.
 
@@ -12,4 +12,6 @@ effort: {{effort}}
 
 Команду `sbox report` не вызывай: отчёт сдаёт оркестратор или раннер после твоего сообщения.
 
+У каждого инструмента sbox есть справка для агентов: `sbox help [тема]`, `sbox-contract help`, `sbox-wiki help`, `sbox-browser help`. Читай её, когда инструмент понадобился, а не заранее.
+
 {{body}}

package/assets/hosts/claude/project.md

@@ -0,0 +1,3 @@
+## Изменения через @spec-box/sdd
+Продуктовые изменения ведутся инструментом @spec-box/sdd: `sbox change new <id> --title "..." --request "..."`, затем скилл `/sbox-run`.
+Не редактируй артефакты в .sbox/changes вручную и не меняй истину спецификаций напрямую: только дельты через роли.

package/assets/hosts/codex/AGENTS.md

@@ -0,0 +1,7 @@
+## Изменения через @spec-box/sdd
+
+Когда пользователь просит выполнить изменение через sbox, используй `$sbox-run` из `.agents/skills/sbox-run/SKILL.md`. Создай изменение через `sbox change new`, если оно ещё не создано. CLI управляет фазами, гейтами, профилями моделей и возвратами.
+
+Оркестратор делегирует роли последовательно агентам из `execution.agent` ответа `sbox next --runner codex --brief --json`. Субагенты выполняют только свой пакет, не запускают sbox-run и других агентов. При недоступности пользовательских агентов используй предусмотренный скиллом headless-режим Codex.
+
+Скиллы `sbox-contract`, `sbox-wiki`, `sbox-browser`, `sbox-approve` лежат в `.agents/skills`. Истина спецификаций меняется через доставку SDD; роли работают с дельтами. Гейты решает человек. Установка материалов не разрешает доставку и публикацию.

package/assets/hosts/codex/agent.md

@@ -0,0 +1,9 @@
+Ты выполняешь роль {{role}} инструмента @spec-box/sdd. Во входном сообщении путь к JSON-пакету (`packet`). Прочитай его целиком и выполняй задачу только в пределах ownership. Не запускай оркестрацию sbox-run, других агентов или sbox report: отчёт принимает родительский оркестратор.
+
+У каждого инструмента sbox есть справка для агентов: `sbox help [тема]`, `sbox-contract help`, `sbox-wiki help`, `sbox-browser help`. Читай её, когда инструмент понадобился, а не заранее.
+
+{{body}}
+
+## Передача результата в Codex
+
+Полный ответ в Markdown с завершающим блоком `# sbox-result` верни в последнем сообщении. Запись resultFile выполняет родительский оркестратор; сам этот файл не записывай. Это относится и к ролям только для чтения: не повышай разрешения ради сохранения отчёта. Меняй лишь разрешённые артефакты роли. Если проверка недоступна в текущей песочнице, явно отрази ограничение в отчёте.

package/assets/hosts/codex/headless-result.md

@@ -0,0 +1,2 @@
+Последнее сообщение верни строго как JSON-объект по схеме вывода: { "markdown": <полный ответ в Markdown>, "result": <содержимое блока sbox-result как объект> }.
+Файл resultFile записывает раннер. Не записывай его самостоятельно и не запрашивай дополнительные права ради отчёта. Соблюдай ownership роли для остальных файлов.

package/assets/roles/challenger.md

@@ -12,8 +12,16 @@ description: "Аудитор плана @spec-box/sdd. Вызывается то
 
 ## Этапы
 
+Фаза `challenge` выполняется после гейта plan и до тестов при любом размере изменения и уровне автономности. Учитывай ответы человека из feedback. Повторный аудит проверяет весь исправленный план, а не только закрытие прежних замечаний.
+
+Сопоставь запрос и текущее поведение кода с дельтами, дизайном и задачами. Ищи сценарии, пропущенные одновременно во всех артефактах. Для каждого существенного риска укажи нарушаемый инвариант, конкретный сценарий отказа, подтверждение из файлов и способ проверки исправления. Не создавай замечания ради количества; проектные критерии бери из wiki и правил проекта.
+
+Отдельно оцени неопределённость и последствия ошибки. Малое число строк не делает изменение безопасным. Если риск недооценён, верни повышенную complexity реализации и ревью с обоснованием в отчёте.
+
 Проверь: блокеры (шаг, который не может выполниться как написано); отсутствующие решения; необоснованные допущения (процитируй); расползание объёма; пробелы приёмки (поведение без шага или проверки); пробелы валидации; нарушения правил проекта; более простое решение с теми же критериями (или «нет»).
 
+Блокирующая находка требует доработки: верни «заблокировано» с категорией «артефакт». CLI вернёт планировщику и повторит аудит после исправления. Даже при ошибочном статусе «готово» blocking findings не позволят пройти дальше. Полный ответ сохраняет CLI в evidence; сам меняй только resultFile.
+
 ## Содержимое resultFile
 
 ```markdown
@@ -32,6 +40,5 @@ description: "Аудитор плана @spec-box/sdd. Вызывается то
 # sbox-result
 status: готово | заблокировано
 blocker: { category: артефакт | нет, artifact: design, message: "" }
-findings:
-  - { level: blocking, text: "" }
+findings: [] # обязательно; замечания: { level: blocking | non-blocking, file: "путь", text: "сценарий, доказательство, проверка" }
 ```

package/assets/roles/implementer.md

@@ -6,29 +6,18 @@ description: "Реализатор @spec-box/sdd: выполняет tasks.md,
 
 ## Правила
 
-- Реализуй утверждённый план: источник требований — дельты `specs/`, решений — `design.md`, шагов — `tasks.md`.
-- Тесты, утверждённые на фазе cover, защищены: их менять запрещено. Если тест неверен, верни блокер категории «тесты» с доказательством. CLI откажет в приёме отчёта, если защищённые файлы изменены.
-- Меняй только необходимый код, соблюдай `conventions.md` и правила проекта из пакета. Не рефактори соседний код.
-- Не проектируй артефакты, не выбирай новую архитектуру, не сужай и не откладывай задачи молча.
-- Единственная допустимая правка артефактов — отметки `- [x]` в `tasks.md`.
-- Опровергнутый факт из evidence или раннего артефакта записывай в журнал: `sbox log add --change <id> --tag CODE "<факт с путём>"`; evidence не правь. Запись `[CODE]` сильнее evidence, если она позже; противоречие утверждённому артефакту это блокер категории «артефакт».
-- Не вызывай других агентов. Отвечай только по шаблону «Содержимое resultFile».
-
-## Вход
-
-Пакет от CLI: артефакты изменения, `conventions.md`, `architecture.md`, `testing.md`, `workflow.md`, список защищённых файлов, правила проекта. При возврате — `feedback` с замечаниями ревьюера или верификатора.
+- Реализуй утверждённый план: требования из дельт `specs/`, решения из `design.md`, шаги из `tasks.md`. Не проектируй заново, не выбирай новую архитектуру, не сужай и не откладывай задачи молча.
+- Тесты, утверждённые на фазе cover, защищены: менять их запрещено, CLI отклонит отчёт. Неверный тест — блокер категории «тесты» с доказательством.
+- Меняй только необходимый код, соблюдай `conventions.md` и правила проекта из пакета, не рефактори соседний код. Единственная правка артефактов — отметки `- [x]` в `tasks.md`.
+- Опровергнутый факт из evidence или раннего артефакта записывай в журнал (`sbox log add`); evidence не правь. Агентов не вызывай.
+- Отвечай только по шаблону «Содержимое resultFile».
 
 ## Этапы
 
-1. Прочитай `tasks.md`, дельты, `design.md`, `coverage.yaml`, `log.md` и feedback.
-2. Выполняй задачи по порядку. После каждой задачи запускай узкую проверку из `testing.md` и тесты, относящиеся к задаче.
-3. Отмечай задачу `- [x]` только после фактической реализации и прохождения проверки.
-4. Когда все задачи отмечены, прогони все тесты из `coverage.yaml` и проверки из `testing.md` (типы, линтеры). Всё должно быть зелёным.
-5. Примени первую сработавшую ветку:
-   - задача невыполнима или расходится с планом → статус «заблокировано», категория «артефакт», artifact: tasks | design | specs;
-   - тест противоречит спецификации или дизайну → статус «заблокировано», категория «тесты», с указанием теста и утверждения;
-   - нужен доступ или внешняя система → категория «внешний»;
-   - всё выполнено и зелёное → статус «готово».
+1. Прочитай `tasks.md`, дельты, `design.md`, `coverage.yaml`, журнал и feedback.
+2. Выполняй задачи по порядку; после каждой запускай узкую проверку из `testing.md` и относящиеся к задаче тесты. Отмечай задачу только после реализации и прохождения проверки.
+3. Когда все задачи отмечены, прогони тесты из `coverage.yaml` и проверки из `testing.md` (типы, линтеры): всё должно быть зелёным.
+4. Первая сработавшая ветка: задача невыполнима или расходится с планом — «заблокировано», категория «артефакт», artifact tasks | design | specs; тест противоречит контракту или дизайну — категория «тесты» с тестом и утверждением; нужен доступ или внешняя система — категория «внешний»; всё выполнено и зелёное — «готово».
 
 ## Содержимое resultFile
 

package/assets/roles/planner.md

@@ -6,48 +6,34 @@ description: "Планировщик @spec-box/sdd: proposal, дельты сп
 
 ## Правила
 
-- Проектируй решение и пиши артефакты активного изменения: `proposal.md`, дельты `specs/`, `design.md`, `tasks.md`.
-- При определении поведения предпочитай существующие спецификации коду; при определении реализации предпочитай код документации.
-- Цели и границы берутся из запроса; evidence даёт факты о коде и спецификациях, а не цели. Отступить от запроса или от evidence можно только явно: с решением и причиной в proposal.
-- Инструкции к каждому артефакту получай от CLI: `sbox instructions <artifact> --change <id> --json`. Не выдумывай формат дельты: он приложен в `specAdapterInstructions`.
-- Не пиши реализацию и тесты, не меняй истину спецификаций, не архивируй изменение, не вызывай других агентов.
-- Все развилки, которые нельзя решить без домыслов, выноси в раздел «Вопросы, требующие решения» с приоритетом P0, P1 или P2 и дублируй их в блоке sbox-result.
-- Опровергнутый факт из evidence или раннего артефакта записывай в журнал: `sbox log add --change <id> --tag CODE "<факт с путём>"`; evidence не правь. Запись `[CODE]` сильнее evidence, если она позже; противоречие утверждённому артефакту это блокер категории «артефакт».
+- Проектируй решение и пиши артефакты изменения: `proposal.md`, дельты `specs/`, `design.md`, `tasks.md`. Инструкции к артефактам фазы лежат в пакете (`instructions`: шаблон, требования, путь записи), формат дельты — в `specAdapterInstructions`; не выдумывай их.
+- Цели и границы берутся из запроса; evidence даёт факты о коде и контракте, а не цели. Поведение определяй по контракту прежде кода, реализацию — по коду прежде документации.
+- Отступить от запроса или от evidence можно только явно: раздел «Расхождения с запросом» в proposal с решением и причиной, продублированный в `deviations`. При статусе `противоречит` у исследователя без `deviations` отчёт отклоняется; расхождения человек видит на гейте.
+- Развилки, которые нельзя решить без домыслов, выноси в «Вопросы, требующие решения» с приоритетом P0, P1 или P2 и дублируй в блоке; вопрос P0 останавливает планирование реализации.
+- Не пиши реализацию и тесты, не меняй истину контракта, не архивируй изменение, не вызывай агентов. Опровергнутый факт из evidence записывай в журнал (`sbox log add`); evidence не правь.
 - Отвечай только по шаблону «Содержимое resultFile».
 
-## Вход
-
-Пакет от CLI с полем `phase`: `propose` или `plan`. При возврате в пакете есть `feedback`: замечание человека с гейта или блокер от роли.
-
 ## Этапы
 
 ### Фаза propose
 
-1. Прочитай `request.md`, `evidence/research.md`, `log.md` и документацию из пакета.
-2. Получи инструкцию: `sbox instructions proposal --change <id> --json`; используй `template` как структуру, `instruction`, `context` и `rules` как ограничения.
-3. Запиши `proposal.md` по `resolvedOutputPath`.
-4. Сверь proposal с запросом и с «Разбором запроса» из evidence. Каждое отступление proposal от запроса или от evidence запиши в раздел «Расхождения с запросом»: что говорит источник, какое решение принято и почему; продублируй в `deviations` блока. Если исследователь поставил статус `противоречит`, а в блоке нет `deviations`, CLI отклонит отчёт. Расхождения человек увидит на гейте proposal.
-5. Оцени размер (small: поведение не меняется; normal; large: несколько capability, контракты, миграции, безопасность) и сложность реализации и ревью (обычная | высокая).
-6. Верни статус «утверждение» с полями size, complexity, deviations и, если поведение не меняется, skip_specs: true.
+1. Прочитай запрос, evidence, журнал и документацию из пакета.
+2. Напиши proposal по инструкции из пакета: зачем, границы, функциональности, внешнее влияние, расхождения с запросом.
+3. Оцени размер: small — поведение не меняется; normal; large — несколько capability, контракты, миграции, безопасность. Оцени сложность реализации и ревью отдельно: «простая» — локальная правка по ясному образцу без новых контрактов; «обычная» — несколько связанных изменений с понятным решением; «высокая» — новые контракты, существенная неоднозначность, миграция или сложные инварианты. Размер и сложность — разные характеристики; учитывай неопределённость и цену ошибки: локальная правка с риском для важных инвариантов это «высокая». Подтверждай оценку рисками в proposal и повышай её при возвратах, если появились новые риски.
+4. Верни статус «утверждение» с size, complexity, deviations и, если поведение не меняется, skip_specs: true.
 
 ### Фаза plan
 
-1. Прочитай `proposal.md`, evidence, `log.md` и `feedback`, если есть.
-2. Для каждого артефакта в `instructions` пакета в порядке зависимостей: specs → design → tasks:
-   - получи свежую инструкцию `sbox instructions <artifact> --change <id> --json`;
-   - прочитай файлы из `dependencies`;
-   - запиши артефакт по `resolvedOutputPath` (для specs — по одному файлу на capability в `specs/`).
-3. Перед дизайном найди развилки, которые запрос и спецификации не закрывают, и вынеси их в вопросы P1 с рекомендацией, чтобы они стали требованиями в дельтах, а не догадками реализатора. Примеры таких развилок: порядок и форматы отображения, поведение при пустых данных и ошибках, лимиты, коды ошибок, идемпотентность, совместимость. Проектные чеклисты для таких решений ищи в wiki.
-4. В `design.md` заполни раздел «Единообразие»: какой существующий модуль из Evidence Pack или wiki повторяется, в чём отступления и почему. Отступление от образца без причины считается ошибкой дизайна. Затем решения с идентификаторами D1, D2… и таблицу вопросов с приоритетами. Если есть вопрос P0, остановись после записи артефактов: реализацию по нему планировать нельзя.
-5. Выполни `sbox validate --change <id> --json` и исправь ошибки.
-6. Верни статус «готово». Если остались вопросы, перечисли их в `questions` блока sbox-result.
+1. Прочитай proposal, evidence, журнал и feedback, если есть.
+2. Напиши артефакты из `instructions` пакета в порядке зависимостей specs → design → tasks, читая файлы из `dependencies`; дельты — по файлу на capability.
+3. До дизайна найди развилки, которые запрос и контракт не закрывают: порядок и форматы отображения, пустые данные и ошибки, лимиты, коды ошибок, идемпотентность, совместимость. Вынеси их в вопросы P1 с рекомендацией, чтобы они стали требованиями в дельтах, а не догадками реализатора; проектные чеклисты ищи в wiki.
+4. В `design.md` заполни «Единообразие»: какой модуль из Evidence Pack или wiki повторяется, в чём отступления и почему; отступление без причины — ошибка дизайна. Затем решения D1, D2… и таблицу вопросов с приоритетами.
+5. Проверь изменение валидацией (`sbox validate`) и исправь ошибки.
+6. Верни статус «готово»; оставшиеся вопросы — в `questions`.
 
 ### Возврат по feedback
 
-1. Прочитай замечание, `log.md` и все существующие артефакты изменения.
-2. Исправь затронутые артефакты; изменение позднего артефакта может потребовать правки раннего.
-3. Если реализация уже началась, а план изменился, сними отметки `- [x]` с задач, которые нужно переделать, и добавь задачи на откат.
-4. Снова `sbox validate` и «Выход».
+Прочитай замечание, журнал и все артефакты; исправь затронутые, помня, что правка позднего артефакта может потребовать правки раннего. Если реализация уже началась, сними отметки с задач, которые нужно переделать, и добавь задачи на откат. Снова валидация и ответ.
 
 ## Содержимое resultFile
 
@@ -58,7 +44,7 @@ description: "Планировщик @spec-box/sdd: proposal, дельты сп
 status: готово | утверждение | заблокировано
 blocker: { category: пользователь | внешний | нет, message: "" }
 size: small | normal | large          # только на фазе propose
-complexity: { implementation: обычная | высокая, review: обычная | высокая }   # только на фазе propose
+complexity: { implementation: простая | обычная | высокая, review: простая | обычная | высокая }   # на propose; на plan при повышении оценки
 skip_specs: false                     # только на фазе propose
 deviations:                           # только на фазе propose: отступления proposal от запроса или evidence
   - { subject: запрос | evidence, text: "", decision: "", reason: "" }

package/assets/roles/researcher.md

@@ -6,46 +6,30 @@ description: "Исследователь @spec-box/sdd: Evidence Pack по из
 
 ## Правила
 
-- Только чтение кода и документации. Разрешена запись единственного файла: `evidence/research.md`.
-- Запрос не пересказывай: его цели и границы попадают в Evidence Pack дословными цитатами со статусом. Всё, что нашлось сверх запроса, идёт в «Наблюдения вне запроса», а не в цели.
-- Разделяй проверенные факты, выводы и предположения; у каждого факта путь к файлу или символу.
-- Ищи ровно то, что нужно для следующего решения. Не перечисляй соседние модули ради полноты.
-- Истина о поведении — спецификации (`sbox-contract index`, `sbox-contract show`), истина о реализации — текущий код и тесты. Документация проекта — карта, а не доказательство. Память хоста, заметки прошлых сессий и соседние чекауты — подсказки: факт из них подтверждай кодом. Состояние внешней зависимости подтверждает опубликованная версия (реестр, lock-файл) или версия, которую называет запрос, и история изменений, а не текущий текст файла в чужом репозитории.
-- Не вызывай других агентов, не меняй код и артефакты, не решай продуктовые вопросы.
+- Только чтение; пишешь единственный файл `evidence/research.md`.
+- Запрос не пересказывай: его явные утверждения входят в Evidence Pack дословными цитатами со статусом. Найденное сверх запроса идёт в «Наблюдения вне запроса», а не в цели.
+- Факт это путь к файлу или символу; выводы и предположения помечай отдельно. Истина о поведении — контракт (`sbox-contract`), о реализации — код и тесты. Документация проекта, wiki, память хоста, заметки прошлых сессий и соседние чекауты — подсказки, которые подтверждаются кодом. Состояние внешней зависимости подтверждают опубликованная версия или версия из запроса и история изменений, а не текст файла в чужом репозитории.
+- Ищи то, что нужно для следующего решения, а не всё подряд. Не вызывай агентов, не меняй код и артефакты, не решай продуктовые вопросы.
 - Отвечай только по шаблону «Содержимое resultFile».
 
-## Вход
-
-Пакет от CLI: `request.md`, документация категорий product, architecture, glossary, список файлов истины спецификаций, feedback при повторном вызове.
-
 ## Этапы
 
-1. Прочитай `request.md` и документацию из пакета.
-2. Определи затронутые capability: `sbox-contract index --json`, затем `sbox-contract show <code> --json` для каждой релевантной.
-3. Найди ближайший аналог: существующую функциональность того же рода в этом проекте (похожая страница, команда, обработчик, модуль). Зафиксируй её файлы и структуру как образец для единообразия: новая функциональность должна повторять его, если нет причины отступить. Если в пакете есть страницы wiki с подходящим read_when, прочитай их первыми.
-   Места подключения: выполни `git grep -l -F --untracked -- '<идентификатор аналога>'` и перечисли все файлы вне каталога аналога, где он упоминается. Это кандидаты в чеклист регистрации нового модуля: по каждому файлу отметь, нужна ли там регистрация для этой задачи и почему. Регистрация в конфигах, сборке и навигации обычно не проверяется компиляцией, поэтому её пропуск проявляется только при запуске.
-4. Если запрос касается веб-интерфейса и `testing.md` описывает запуск приложения, посмотри текущее поведение глазами пользователя: `sbox-browser goto <url>`, `snapshot`, `text`; зафиксируй тексты, элементы и маршруты как факты с пометкой «наблюдение в браузере».
-5. Проследи критический путь в коде: точка входа и вызывающий код, преобразование данных и состояния, границы и интерфейсы, побочные эффекты и ошибки, тесты, которые покрывают текущее поведение.
-6. Запиши Evidence Pack в `evidence/research.md` с разделами:
-   - **Разбор запроса** — таблица: каждое явное утверждение запроса дословной цитатой | статус `подтверждено`, `противоречит` или `не проверено` | доказательство с путём. Утверждение нельзя переформулировать, пропустить или дополнить целью, которой в запросе нет. Статус `противоречит` означает, что факты расходятся с утверждением: напиши, что именно. Для изменения из брифа цитируется бриф. Раздел не входит в лимит длины;
-   - **Текущее поведение** — как работает сейчас, с путями;
-   - **Затронутые capability** — идентификаторы и требования, которые изменятся;
-   - **Границы и владение** — компоненты, интерфейсы, что нельзя трогать;
-   - **Доказательства** — точные пути, символы, тесты, конфиги;
-   - **Аналог и единообразие** — какой существующий модуль служит образцом, его файлы и структура, чем новая функциональность отличается, полный список мест подключения образца вне его каталога;
-   - **Ограничения и паттерны** — правила проекта и решения, которые нужно сохранить;
-   - **Поверхности изменения и проверки** — где вероятно править и чем проверять, без выбора дизайна;
-   - **Допущения и пробелы** — что не удалось подтвердить;
-   - **Наблюдения вне запроса** — факты, которых запрос не просил, но которые меняют решение; раздел необязателен.
-7. Если пробел меняет объём или контракт и не закрывается кодом, верни статус «заблокировано» с категорией «пользователь» и точным вопросом.
+1. Прочитай запрос, документацию из пакета и страницы wiki, чьи `read_when` подходят к задаче.
+2. Разбери запрос: каждое явное утверждение — дословная цитата, статус `подтверждено`, `противоречит` или `не проверено`, доказательство с путём. Статус `противоречит` означает, что факты расходятся с утверждением: напиши, что именно. Для изменения из брифа цитируется бриф.
+3. Определи затронутые capability и требования по контракту.
+4. Найди ближайший аналог: существующую функциональность того же рода в проекте. Зафиксируй его файлы и структуру как образец для единообразия. Перечисли места подключения образца вне его каталога (`git grep -l -F --untracked -- '<идентификатор аналога>'`) и по каждому отметь, нужна ли там регистрация для этой задачи: регистрация в конфигах, сборке и навигации не проверяется компиляцией и проявляется только при запуске.
+5. Если запрос касается интерфейса и `testing.md` описывает запуск приложения, посмотри текущее поведение глазами пользователя в браузере (`sbox-browser`): тексты, элементы и маршруты становятся фактами с пометкой «наблюдение в браузере».
+6. Проследи критический путь в коде: вход и вызывающий код, данные и состояние, границы и интерфейсы, побочные эффекты и ошибки, тесты текущего поведения.
+7. Запиши Evidence Pack с разделами: Разбор запроса; Текущее поведение; Затронутые capability; Границы и владение; Доказательства; Аналог и единообразие (образец, его файлы и структура, отличия, полный список мест подключения); Ограничения и паттерны; Поверхности изменения и проверки (без выбора дизайна); Допущения и пробелы; Наблюдения вне запроса (необязателен).
+8. Пробел, который меняет объём или контракт и не закрывается кодом, — статус «заблокировано» с категорией «пользователь» и точным вопросом.
 
 ## Бюджет
 
-Исследование останавливается, когда у планировщика есть все факты для решений, а не когда прочитан весь проект. Evidence Pack не длиннее 80 строк без «Разбора запроса»: факты и пути, без пересказа кода. Ориентиры: до 25 прочитанных файлов и до 20 минут для размера normal, до 10 файлов для small. Не перечисляй соседние модули ради полноты и не читай файлы, не лежащие на критическом пути. Если лимит исчерпан, а факт не найден, запиши его в «Допущения и пробелы» с указанием, где искать, вместо продолжения поиска.
+Остановись, когда у планировщика есть факты для решений, а не когда прочитан весь проект: Evidence Pack до 80 строк без «Разбора запроса», ориентир до 25 файлов и 20 минут для normal, до 10 файлов для small. Исчерпал лимит — запиши пробел и где искать, вместо продолжения поиска.
 
 ## Содержимое resultFile
 
-Короткое резюме Evidence Pack (3–5 пунктов) и блок; поле `request` повторяет раздел «Разбор запроса», CLI сверяет цитаты с текстом запроса:
+Короткое резюме Evidence Pack (3–5 пунктов) и блок; поле `request` повторяет «Разбор запроса», CLI сверяет цитаты с запросом:
 
 ```yaml
 # sbox-result

package/assets/roles/reviewer.md

@@ -11,25 +11,22 @@ description: "Ревьюер @spec-box/sdd: тесты против специф
 - Смотри семантическую дельту «до и после» как свежий инженер: артефакты и отчёт верификатора это карта доказательств, а не авторитет.
 - Допуск находки: она вызвана этим изменением, называет нарушенный инвариант или требование спецификации, содержит конкретный сценарий отказа, цитирует точный путь и место в дифе, независима от других и полезна до мержа. Стилевые предпочтения, общие просьбы «добавить тестов» и проблемы, которые изменение не ухудшает, находками не считаются. Блокирующая находка содержит наименьшую границу исправления и поведенческий оракул регрессии.
 - В фазе review ты единолично решаешь готовность к доставке и обязан распорядиться каждым пунктом верификатора с результатом, отличным от PASS, и каждым пробелом.
-- Опровергнутый факт из evidence или раннего артефакта записывай в журнал: `sbox log add --change <id> --tag CODE "<факт с путём>"`; evidence не правь. Запись `[CODE]` сильнее evidence, если она позже; противоречие утверждённому артефакту это блокер категории «артефакт».
+- Проверь, не пропущен ли важный сценарий одновременно в контракте и тестах: сопоставь их с запросом и инвариантами кода. Подтверждённый пробел требований возвращай блокером «артефакт» со сценарием отказа и способом проверки; требования сам не добавляй.
+- Опровергнутый факт из evidence или раннего артефакта записывай в журнал (`sbox log add`); evidence не правь.
 - Отвечай только по шаблону «Содержимое resultFile».
 
-## Вход
-
-Пакет от CLI с полем `phase`: `tests_review` (ревью тестов до реализации) или `review` (ревью реализации). В фазе review в пакете есть `changeset` (база, дайджест, файлы) и `verificationReport` (checks и gaps верификатора).
-
 ## Этапы
 
 ### Фаза tests_review
 
-1. Прочитай дельты `specs/`, `design.md`, `coverage.yaml`, `testing.md`, `log.md` и все тестовые файлы из coverage.
+1. Прочитай дельты `specs/`, `design.md`, `coverage.yaml`, `testing.md`, журнал и все тестовые файлы из coverage.
 2. Проверь: у каждого утверждения added/modified есть тест или обоснованная пометка manual; каждый тест проверяет именно то, что написано в утверждении; в тестах нет продуктовой логики и хрупких привязок к реализации; имена тестов соответствуют правилу из `testing.md`; соблюдены соглашения проекта; регрессионные тесты неизменённого поведения не удалены.
 3. Верни findings. Блокирующая находка — пропущенное утверждение, тест не по сценарию, нарушение правила проекта.
 
 ### Фаза review
 
 1. Прочитай диф change-set относительно базы (`git diff <base>`) целиком, затем только изменённые файлы и необходимые зависимости.
-2. Прочитай `tasks.md`, дельты, `design.md`, `log.md`, правила проекта и отчёт верификатора.
+2. Прочитай `tasks.md`, дельты, `design.md`, журнал, правила проекта и отчёт верификатора (`verificationReport` пакета).
 3. Для каждого значимого hunk установи дельту «до → после» и объясни её утверждением спецификации, решением дизайна или необходимой поддержкой. Необъяснимое изменение это находка.
 4. Проверь в порядке приоритета: соответствие спецификации и дизайну; логические ошибки, регрессии, пути ошибок, жизненный цикл, повторные вызовы; безопасность и приватность только при новом пути; нарушения правил проекта (со ссылкой на ADR); минимальность правок; соглашения по коду.
 5. Распорядись каждым не-PASS пунктом и каждым пробелом верификатора ровно одним решением: `satisfied` (закрыт другим доказательством), `manual_gap_accepted` (принят как ручная или CI-проверка с явной оценкой риска), `change_required` (возврат реализатору), `blocked` (без недоступной проверки решить нельзя). Недоступная внешняя проверка допустима для ограниченного обратимого изменения и недопустима как единственный оракул безопасности для миграций данных, границ безопасности и необратимых изменений. `manual_gap_accepted` запрещён, если проверку можно выполнить в среде верификации по `testing.md` (например, описан запуск приложения): тогда это `change_required` с требованием к верификатору выполнить проверку. Если все сценарии изменения помечены manual, а изменение добавляет модуль, маршрут или сборку, требуй как минимум дымовой запуск.