@spec-box/sdd 0.6.4

package/README.md

@@ -0,0 +1,81 @@
+# @spec-box/sdd
+
+Инструмент автономной реализации продуктовых фич ИИ-агентами: вы даёте описание фичи, агенты-роли проводят её через исследование, предложение, спецификации, дизайн, тесты, реализацию, верификацию и ревью до пул-реквеста, готового к влитию. Состояние процесса хранится в файлах репозитория продукта.
+
+Проект входит в группу [spec-box](https://github.com/spec-box): инструменты для работы со спецификациями и автотестами. Репозиторий: [github.com/spec-box/sdd](https://github.com/spec-box/sdd).
+
+Замысел и устройство описаны в [docs/design.md](docs/design.md). Ниже то, что уже реализовано (этапы 1 и 2 плана).
+
+## Установка
+
+Требуется Node.js 22. Инструмент ставится глобально из npm и обновляется той же командой:
+
+```bash
+npm install -g @spec-box/sdd
+sbox --version
+```
+
+Для разработки самого @spec-box/sdd: `pnpm install`, `pnpm build` (tsc → dist/), `pnpm test` (vitest), `pnpm dev -- <команда>` запускает CLI через tsx без сборки. Публикация: `npm publish` из корня репозитория, `prepublishOnly` собирает и прогоняет тесты.
+
+## Быстрый старт в проекте продукта
+
+```bash
+cd <репозиторий продукта>     # spec-box (.tms.json) или OpenSpec (openspec/specs); адаптер определяется автоматически
+sbox init --host claude       # .sbox/config.yaml, шаблоны .sbox/project/*.md, .gitignore, скиллы и агенты Claude Code
+# заполнить .sbox/project/*.md
+sbox doctor                   # структурная проверка документации, спецификаций и сред запуска
+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 "..."`.
+
+## Что где лежит
+
+```text
+src/core/        доменная модель, конфиг, состояние изменения (ревизия, lock), машина состояний, схема артефактов,
+                 пакет для роли, приём отчёта, change-set, headless-цикл run, доставка и текст PR, гейты через PR,
+                 отчёты тестов и покрытие, категории документации и doctor, архивация
+src/adapters/    spec/spec-box, spec/openspec — истина и дельты в двух форматах; runner/claude, runner/codex — среды агентов;
+                 repo/github, repo/local — хостинг репозитория; host/claude — материалы для Claude Code
+src/cli/         команды commander: init, doctor, host, change, next, report, approve, reject,
+                 status, instructions, validate, spec, archive
+assets/roles/    определения ролей (Markdown): researcher, planner, tester, implementer, reviewer, verifier…
+assets/schema/   граф артефактов по умолчанию и инструкции к ним
+assets/templates/ шаблоны артефактов изменения
+assets/project/  шаблоны категорий проектной документации
+assets/ci/       шаблоны GitHub Actions и Dockerfile
+test/            vitest: парсеры, адаптер spec-box, doctor, полный цикл изменения на фикстуре
+docs/design.md   проектный документ
+```
+
+## Headless-режим
+
+```bash
+sbox run --change add-search --runner claude  # роли выполняет адаптер среды до гейта, блокера или конца
+sbox run --change add-search --detach         # в фоне; журнал в .sbox/changes/<id>/runs/run.log
+sbox watch --change add-search                # ждать терминального статуса, выход 1 при parked/blocked/stopped
+sbox stop --change add-search                 # остановить процесс роли, доставка после этого запрещена
+sbox change resume add-search --returns 6     # продолжить после parked с большим бюджетом возвратов
+sbox changeset show                           # запечатанный change-set и дрейф рабочей копии
+sbox coverage --report jest=reports/jest.json # покрытие утверждений дельт тестами
+sbox deliver --check && sbox deliver          # чеклист готовности, архив, коммит, push, пул-реквест
+sbox gates poll                               # гейты через комментарии /sbox approve|reject в пул-реквесте
+sbox ci install --target github               # workflows для GitHub Actions; --target docker для Dockerfile.sbox
+sbox wiring --analog X --new Y                # новый модуль подключён везде, где подключён образец
+sbox metrics                                  # время агентов, ожидание человека, запуски, стоимость, вмешательства, оценки
+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` только коммитит.
+
+## Состояние
+
+Готово (этапы 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.
+
+Готово также: адаптер OpenSpec (истина в `openspec/specs`, дельты в родном синтаксисе ADDED/MODIFIED/REMOVED/RENAMED, текстовое применение с сохранением остальных разделов, `.openspec.yaml` в папке изменения для совместимости с CLI OpenSpec).
+
+Готово также: wiki проекта в `.sbox/wiki/` (индекс страниц с `read_when` попадает в пакет каждой роли), метрики `sbox metrics` и оценка `sbox change rate`.
+
+Не готово: дискавери и правила (этап 3), Arcadia и Codex-материалы для хоста (этап 4), межрепозиторный протокол (этап 5), роутер и дистилляция wiki (этап 6), продолжение сессий Codex, семантический `doctor --deep`.

package/assets/adapters/openspec/instructions.md

@@ -0,0 +1,47 @@
+## Формат дельты спецификаций (адаптер OpenSpec)
+
+Истина хранится в `openspec/specs/<capability-path>/spec.md`: заголовок `# <Название> Specification`, раздел `## Purpose`, раздел `## Requirements` с блоками `### Requirement: <название>` (нормативный текст с SHALL или MUST) и сценариями `#### Scenario: <название>` в форме GIVEN / WHEN / THEN. Идентификатор capability это путь относительно `openspec/specs/`, например `auth` или `identity/user-auth` (`sbox spec list --json`).
+
+Дельта лежит в `specs/<capability-path>/spec.md` папки изменения, по одному файлу на capability. Она описывает только изменения:
+
+```markdown
+## Purpose
+<!-- только для новой capability: 1–2 предложения, не короче 50 символов -->
+
+## ADDED Requirements
+
+### Requirement: Экспорт данных в CSV
+Система SHALL позволять пользователю экспортировать свои данные в формате CSV.
+
+#### Scenario: Успешный экспорт
+- **GIVEN** пользователь авторизован
+- **WHEN** пользователь нажимает «Экспорт»
+- **THEN** система отдаёт CSV-файл со всеми данными пользователя
+
+## MODIFIED Requirements
+
+### Requirement: Истечение сессии
+Система SHALL завершать сессию после 15 минут бездействия.
+
+#### Scenario: Таймаут при бездействии
+- **WHEN** проходит 15 минут без активности
+- **THEN** сессия завершается
+
+## REMOVED Requirements
+
+### Requirement: Запомнить меня
+**Reason**: Заменено двухфакторной аутентификацией
+**Migration**: Пользователи входят заново в каждой сессии
+
+## RENAMED Requirements
+- FROM: `### Requirement: Старое название`
+- TO: `### Requirement: Новое название`
+```
+
+Правила:
+- `MODIFIED`, `REMOVED`, `RENAMED` применимы только к требованиям, которые есть в истине (`sbox spec show <capability-path> --json`); заголовок должен совпадать буква в букву.
+- `MODIFIED` заменяет блок требования целиком: скопируйте существующий блок с всеми сценариями и измените нужное. Потерянные сценарии валидатор пометит предупреждением.
+- Если меняется и название, и поведение: пара FROM/TO в `RENAMED` и полный блок в `MODIFIED` под новым названием.
+- Для новой capability допустим только `ADDED` и обязателен `## Purpose`.
+- Каждое требование содержит нормативный текст с SHALL или MUST и хотя бы один сценарий. Сценарии оформляются ровно четырьмя `#`: три `#` не распознаются.
+- Названия сценариев попадают в имена тестов: пишите их коротко и без переносов строк.

package/assets/adapters/spec-box/instructions.md

@@ -0,0 +1,44 @@
+## Формат дельты спецификаций (адаптер spec-box)
+
+Истина хранится в YAML-файлах spec-box: `feature`, `code`, `specs-unit` (группы утверждений `assert`). Одна группа соответствует требованию, одно утверждение соответствует сценарию, и на каждое утверждение приходится один автотест. Нормативный текст требования пишите полным предложением в названии группы (например, «Сессия завершается после 30 минут бездействия»), шаги GIVEN/WHEN/THEN пишите в `description` утверждения.
+
+Дельта лежит в `specs/<code>.yml` папки изменения, по одному файлу на capability:
+
+```yaml
+code: checkout-page                 # обязательно; совпадает с code существующей фичи или задаёт новую
+feature: Страница оформления заказа # обязательно только для новой фичи
+description: Назначение фичи        # для новой фичи: 1–2 предложения
+type: Functional                    # опционально
+definitions:                        # опционально, атрибуты из .spec-box-meta.yml
+  page: [checkout]
+
+added:                              # новые группы или новые утверждения в существующей группе
+  Пользователь может выбрать адрес доставки:
+    - assert: При нажатии «Выбрать адрес» открывается диалог выбора адреса на карте
+      description: |
+        GIVEN пользователь на странице оформления
+        WHEN нажимает «Выбрать адрес»
+        THEN открывается диалог с картой и полем поиска
+
+modified:                           # полная замена утверждений существующей группы
+  Отображается сводка заказа:
+    - assert: Отображается количество и общая стоимость товаров с учётом скидки
+
+removed:                            # удаление группы целиком или отдельных утверждений
+  Промокод применяется на странице корзины:
+    reason: Промокод переносится на страницу оформления
+    migration: Сценарии покрыты группой «Промокод применяется при оформлении»
+  Блок рекомендаций:
+    asserts: ["Отображается блок «С этим покупают»"]
+
+renamed:
+  - from: Старое название группы
+    to: Новое название группы
+```
+
+Правила:
+- `modified`, `removed`, `renamed` применимы только к группам, которые есть в истине (`sbox spec show <code> --json`).
+- Для новой фичи допустима только секция `added`.
+- В `modified` перечисляйте все утверждения группы целиком, а не только изменённые. Если группа одновременно переименована в `renamed`, в `modified` пишите её под новым названием.
+- Утверждение формулируйте наблюдаемым поведением с точки зрения пользователя или внешнего контракта; одно утверждение проверяет одно поведение.
+- Названия групп и утверждений попадают в имена тестов (`describe` и `it`), поэтому не используйте в них кавычки-ёлочки внутри кавычек и переносы строк.

package/assets/ci/Dockerfile

@@ -0,0 +1,9 @@
+# Образ для headless-запуска @spec-box/sdd в нейтральной среде (docs/design.md, раздел 13).
+FROM node:22-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN npm install -g pnpm @spec-box/sdd
+# Codex CLI ставится отдельно, если нужен адаптер codex: npm install -g @openai/codex
+WORKDIR /work
+ENV SBOX_HOME=/work/.sbox-runs
+ENTRYPOINT ["sbox"]
+CMD ["--help"]

package/assets/ci/github-sbox-run.yml

@@ -0,0 +1,85 @@
+# @spec-box/sdd: headless-запуск изменения в GitHub Actions (docs/design.md, раздел 13).
+# Триггеры: ручной запуск, расписание и команды в комментариях пул-реквеста (/sbox approve|reject).
+name: sbox run
+
+on:
+  workflow_dispatch:
+    inputs:
+      change:
+        description: Идентификатор изменения
+        required: true
+      runner:
+        description: claude | codex
+        default: claude
+  schedule:
+    - cron: '*/30 * * * *'
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: sbox-${{ github.event.inputs.change || github.event.issue.number || 'schedule' }}
+  cancel-in-progress: false
+
+jobs:
+  run:
+    if: github.event_name != 'issue_comment' || startsWith(github.event.comment.body, '/sbox ')
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Для issue_comment нужна ветка пул-реквеста: её определяет шаг ниже.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v4
+      - name: Определить изменение и ветку
+        id: change
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "issue_comment" ]; then
+            BRANCH=$(gh pr view ${{ github.event.issue.number }} --json headRefName -q .headRefName)
+            git fetch origin "$BRANCH" && git checkout "$BRANCH"
+            echo "change=${BRANCH#sbox/}" >> "$GITHUB_OUTPUT"
+          elif [ -n "${{ github.event.inputs.change }}" ]; then
+            BRANCH="sbox/${{ github.event.inputs.change }}"
+            git fetch origin "$BRANCH" && git checkout "$BRANCH" || git checkout -b "$BRANCH"
+            echo "change=${{ github.event.inputs.change }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "change=" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - name: Установить зависимости проекта и @spec-box/sdd
+        run: |
+          pnpm install --frozen-lockfile
+          npm install -g @spec-box/sdd
+      - name: Продвинуть гейты из комментариев
+        if: steps.change.outputs.change != ''
+        run: sbox gates poll --change "${{ steps.change.outputs.change }}" --json || true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+      - name: Запустить @spec-box/sdd
+        if: steps.change.outputs.change != ''
+        run: sbox run --change "${{ steps.change.outputs.change }}" --runner "${{ github.event.inputs.runner || 'claude' }}" --json
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      - name: Сохранить состояние изменения
+        if: always() && steps.change.outputs.change != ''
+        run: |
+          git config user.name "sbox-bot"
+          git config user.email "sbox-bot@users.noreply.github.com"
+          git add -A .sbox && git commit -qm "sbox: состояние изменения ${{ steps.change.outputs.change }}" || true
+          git push origin HEAD
+      - name: Доставить, если изменение готово
+        if: steps.change.outputs.change != ''
+        run: sbox deliver --change "${{ steps.change.outputs.change }}" --check --json && sbox deliver --change "${{ steps.change.outputs.change }}" --json || true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

package/assets/ci/github-tests.yml

@@ -0,0 +1,25 @@
+# Тесты проекта с JSON-отчётом как артефактом: его читает верификатор @spec-box/sdd (`sbox coverage --report jest=…`).
+name: tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - name: Тесты с JSON-отчётом
+        run: mkdir -p reports && pnpm test -- --reporter=default --reporter=json --outputFile=reports/jest.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-report
+          path: reports/

package/assets/project/architecture.md

@@ -0,0 +1,29 @@
+---
+id: project.architecture
+summary: Карта пакетов и модулей, точки входа, поток данных, границы
+read_when: Перед исследованием, планированием и реализацией
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Архитектура и карта кода
+
+## Карта пакетов и модулей
+
+<!-- Таблица: пакет или каталог → ответственность → с чего начинать при изменении. -->
+
+## Точки входа
+
+<!-- Команды CLI, HTTP-обработчики, задания, UI-страницы: где начинается выполнение. -->
+
+## Поток данных
+
+<!-- Как данные проходят от входа к результату; состояние, преобразования, побочные эффекты. -->
+
+## Границы модулей
+
+<!-- Что с чем может и не может взаимодействовать напрямую; публичные интерфейсы. -->
+
+## Генерируемый код
+
+<!-- Что генерируется, чем, и что нельзя править руками. Если нет — «—». -->

package/assets/project/contracts.md

@@ -0,0 +1,29 @@
+---
+id: project.contracts
+summary: Внешние API, события, схемы, потребители, машиночитаемые контракты
+read_when: При изменении интерфейсов и интеграций
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Интеграции и контракты
+
+## Внешние API
+
+<!-- Какие API продукт предоставляет и потребляет. -->
+
+## События
+
+<!-- Публикуемые и потребляемые события, их схемы. -->
+
+## Схемы
+
+<!-- Схемы данных, версии, совместимость. -->
+
+## Потребители
+
+<!-- Кто зависит от контрактов продукта; репозитории-партнёры. -->
+
+## Машиночитаемые контракты
+
+<!-- Где лежат OpenAPI, JSON Schema, protobuf. -->

package/assets/project/conventions.md

@@ -0,0 +1,29 @@
+---
+id: project.conventions
+summary: Язык, стиль, запрещённые конструкции, именование, коммиты
+read_when: Перед написанием кода и тестов, при ревью
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Соглашения по коду
+
+## Язык
+
+<!-- Язык кода, комментариев, сообщений коммитов, пользовательских текстов. -->
+
+## Стиль
+
+<!-- Форматтер и линтер, команды проверки, ключевые правила. -->
+
+## Запрещено
+
+<!-- Конструкции и практики, которые ревью отклоняет: например, явный any, бесконтрольный catch. -->
+
+## Именование
+
+<!-- Файлы, модули, тесты, ветки. -->
+
+## Коммиты
+
+<!-- Формат сообщения, что в один коммит, что запрещено коммитить. -->

package/assets/project/decisions.README.md

@@ -0,0 +1,3 @@
+# Постоянные правила проекта
+
+Каждое правило — файл `ADR-NNNN-<slug>.md` с фронтматтером `id`, `title`, `status` (accepted | superseded), `scope` (пути или области), `accepted_by`, `accepted_at`, `origin`, `supersedes` и разделами «Правило», «Контекст», «Обоснование», «Последствия», «Как проверяется». Правило меняется только новым правилом со ссылкой `supersedes`.

package/assets/project/glossary.md

@@ -0,0 +1,13 @@
+---
+id: project.glossary
+summary: Термины домена в формулировках спецификаций и тестов
+read_when: При написании спецификаций, тестов и сообщений пользователю
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Словарь домена
+
+## Термины
+
+<!-- Термин — определение — где встречается в коде. По одному термину на строку таблицы. -->

package/assets/project/overview.md

@@ -0,0 +1,29 @@
+---
+id: project.overview
+summary: Что за продукт, для кого, где живёт код и истина спецификаций
+read_when: Перед исследованием и планированием любого изменения
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Продукт и границы
+
+## Что за продукт
+
+<!-- Одним абзацем: что делает продукт и какую задачу решает. Категория продукта первой строкой. -->
+
+## Пользователи
+
+<!-- Кто пользуется и в каких сценариях. Роли пользователей, если есть. -->
+
+## Системы рядом
+
+<!-- Внешние сервисы, от которых зависит продукт, и кто зависит от него. -->
+
+## Где живёт код
+
+<!-- Репозиторий, корневые каталоги, что где лежит на верхнем уровне. -->
+
+## Истина спецификаций
+
+<!-- Формат (spec-box / OpenSpec), пути файлов, как читать: `sbox spec list`. Внешняя система выгрузки, если есть. -->

package/assets/project/testing.md

@@ -0,0 +1,34 @@
+---
+id: project.testing
+summary: Уровни тестов, команды, отчёты, именование тестов по сценариям, среда e2e
+read_when: Перед написанием тестов, реализацией и верификацией
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Тестирование и проверки
+
+## Уровни тестов
+
+<!-- Таблица: уровень (unit / component / module / e2e) → когда применять → где лежат → чем запускаются. -->
+
+## Команды
+
+<!-- Узкий прогон одного файла, полный прогон, проверки типов и линтеров. Команды в обратных кавычках, например `pnpm test`.
+     Обязательно опишите дымовой запуск: как поднять приложение или сервис локально (зависимости, порт) и какой URL или команда подтверждает, что оно работает. Верификатор запускает его, когда изменение добавляет модуль, маршрут или сборку. -->
+
+## Отчёты
+
+<!-- Куда пишутся отчёты тестов (jest --json, playwright json) и как их получить в CI. -->
+
+## Именование тестов по сценариям
+
+<!-- Правило: describe = название capability, вложенный describe = группа, it = утверждение. Пример. -->
+
+## Среда e2e
+
+<!-- Как запускаются e2e: локально, задачей CI, на стенде; что для этого нужно. Если e2e нет — «—». -->
+
+## Не автоматизируется
+
+<!-- Что проверяется только руками и почему. -->

package/assets/project/workflow.md

@@ -0,0 +1,29 @@
+---
+id: project.workflow
+summary: Ветки, пул-реквесты, проверки CI, что запрещено без человека, разрешённые команды
+read_when: Перед коммитом, созданием ветки и пул-реквеста
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Рабочий процесс
+
+## Ветки
+
+<!-- Базовая ветка, правило именования веток, одна ветка на изменение. -->
+
+## Пул-реквесты
+
+<!-- Что должно быть в описании, кто ревьюит, когда черновик становится готовым. -->
+
+## Проверки CI
+
+<!-- Обязательные проверки перед мержем и где смотреть их результаты. -->
+
+## Запрещено без человека
+
+<!-- Мерж, публикация, миграции, изменения секретов и всё, что агент не делает сам. -->
+
+## Разрешённые команды
+
+<!-- Список команд, которые агенты могут запускать без подтверждения. -->

package/assets/prompts/fill-project-docs.md

@@ -0,0 +1,43 @@
+Заполни проектную документацию @spec-box/sdd в каталоге `.sbox/project/` по этому репозиторию.
+
+## Что делать
+
+1. Прочитай README, package.json (или аналог для стека), конфиги сборки, тестов, линтеров и CI, структуру каталогов и по несколько ключевых файлов в каждом крупном модуле. Не читай всё подряд: нужны факты для семи файлов ниже.
+2. Заполни файлы `overview.md`, `architecture.md`, `conventions.md`, `testing.md`, `workflow.md`, `glossary.md`. Файл `contracts.md` заполняй только если продукт предоставляет или потребляет внешние API, события или схемы; иначе оставь его как есть.
+3. Сохрани структуру каждого файла: фронтматтер и все заголовки `## …` из шаблона остаются, добавлять разделы можно, убирать нельзя. HTML-комментарии из шаблона замени содержанием или удали.
+4. В конце выполни `sbox doctor` и устрани ошибки. Doctor проверяет фронтматтер, наличие разделов, заглушки, существование упомянутых путей и скриптов из package.json.
+
+## Правила содержания
+
+- Только проверенные факты с указанием, откуда они: путь к файлу, скрипт, конфиг. Ничего не выдумывай и не пиши «обычно в таких проектах».
+- Если факт не установлен, напиши «не установлено: <что и где проверить>» и вынеси вопрос в итоговый список. Не пиши TODO, TBD и угловые скобки: doctor считает их заглушками.
+- Если раздел неприменим к проекту, напиши «—» и одну фразу, почему.
+- Коротко и конкретно: таблицы и списки вместо абзацев, команды и пути в обратных кавычках. Ориентир: до 60 строк на файл, `glossary.md` и `architecture.md` могут быть длиннее.
+- Пиши по-русски, идентификаторы, команды и пути оставляй как в коде.
+- Во фронтматтере обнови `summary` под содержимое, `updated` на сегодняшнюю дату, `verification: needs-review`: проверять и утверждать буду я.
+
+## На какие вопросы должен ответить каждый файл
+
+| Файл | Обязательные ответы | Кто это читает |
+|---|---|---|
+| `overview.md` | Что за продукт и категория одной строкой; кто пользователи; какие системы рядом; где живёт код (корневые каталоги); где истина спецификаций ({{SPEC_TRUTH}}) и как её читать (`sbox spec list`) | исследователь, планировщик |
+| `architecture.md` | Таблица пакетов и модулей с ответственностью; точки входа (команды, обработчики, страницы); поток данных от входа к результату; границы модулей (кто с кем не может взаимодействовать напрямую); генерируемый код и что нельзя править руками | исследователь, планировщик, реализатор |
+| `conventions.md` | Язык кода, комментариев и коммитов; форматтер и линтер с командами; запрещённые конструкции; именование файлов, модулей, тестов, веток; правила коммитов | реализатор, ревьюер, тестировщик |
+| `testing.md` | Таблица уровней тестов: когда какой применять, где лежат, чем запускаются; команды узкого прогона одного файла и полного прогона, проверки типов и линтера; куда пишутся JSON-отчёты и как их получить; правило именования тестов по сценариям спецификации; среда e2e или «—»; что проверяется только руками | тестировщик, реализатор, верификатор |
+| `workflow.md` | Базовая ветка и именование веток; требования к пул-реквесту; обязательные проверки CI; что запрещено без человека; список команд, которые агенты могут запускать без подтверждения | все роли с правом записи |
+| `glossary.md` | Термины домена: термин, определение, где встречается в коде. Именно этими словами будут написаны спецификации и тесты | все роли |
+| `contracts.md` | Внешние API, события, схемы данных, потребители, где лежат машиночитаемые контракты | планировщик, тестировщик |
+
+Особое внимание правилу именования тестов в `testing.md`: инструмент сопоставляет тесты с утверждениями спецификации по цепочке {{SPEC_CHAIN}}. Опиши, как эта цепочка ложится на `describe` и `it` в тестах проекта, с примером.
+
+## Что не делать
+
+- Не менять другие файлы репозитория и код.
+- Не переписывать существующие README и документацию: только `.sbox/project/*.md`.
+- Не задавать вопросы по ходу: собери их в конец.
+
+## Формат ответа
+
+1. Список заполненных файлов с одной строкой о содержании.
+2. Результат `sbox doctor`.
+3. Вопросы и неустановленные факты списком, каждый с указанием, в каком файле и разделе стоит «не установлено».

package/assets/roles/challenger.md

@@ -0,0 +1,33 @@
+# Роль: challenger (аудитор плана)
+
+## Правила
+
+- Только чтение. Аудируй замороженный план или бриф целиком и верни все существенные проблемы одним пакетом.
+- Не переписывай план, не утверждай его, не вызывай агентов, не задавай вопросы пользователю.
+- Отвечай только по шаблону «Выход».
+
+## Этапы
+
+Проверь: блокеры (шаг, который не может выполниться как написано); отсутствующие решения; необоснованные допущения (процитируй); расползание объёма; пробелы приёмки (поведение без шага или проверки); пробелы валидации; нарушения правил проекта; более простое решение с теми же критериями (или «нет»).
+
+## Выход
+
+```markdown
+## Аудит плана
+### Блокеры
+### Отсутствующие решения
+### Необоснованные допущения
+### Расползание объёма
+### Пробелы приёмки и проверки
+### Более простое решение
+### Вердикт
+**достаточно** или **доработать** — одно предложение
+```
+
+```yaml
+# sbox-result
+status: готово | заблокировано
+blocker: { category: артефакт | нет, artifact: design, message: "" }
+findings:
+  - { level: blocking, text: "" }
+```

package/assets/roles/distiller.md

@@ -0,0 +1,18 @@
+# Роль: distiller (дистиллятор знаний)
+
+## Правила
+
+- Переноси в wiki проекта только записи `[CODE]` и `[RULE]` из `log.md` изменения, которые отвечают на повторяющийся вопрос и предотвращают класс ошибок. Пересказ одного файла не переносится.
+- Записи `[TASK]` и `[HUMAN]` не переносятся.
+- Правь только `.sbox/wiki/**`; в каждую страницу вноси минимальное дополнение, предпочитай исправление устаревшего тексту нового.
+- Отвечай только по шаблону «Выход».
+
+## Выход
+
+Список перенесённых и пропущенных записей с причинами и блок:
+
+```yaml
+# sbox-result
+status: готово
+blocker: { category: нет }
+```