# dsh-sdd Specification

## Purpose
Исполнение плана субагентами в DeepSeek Harness (SDD). Контроллер диспатчит
implementer'а на задачу плана, получает отчёт, отправляет задачу на ревью
и ведёт fix-loop до чистоты, затем заказывает финальное ревью ветки. DSH не
имеет синхронного `Task`, поэтому протокол строится на асинхронном `subagent`
(идентификатор, уведомление, `send_message`) и на ledger как единственной
памяти между ходами.

## Requirements

### Requirement: Режим контроллера выбирается по контексту
Skill SHALL предлагать два режима и MUST выбирать между ними по числу
параллельных планов, а не по умолчанию.

- Один план в сессии — контроллер главная сессия; implementer'ы и ревьюеры
  диспатчатся на глубину 1, что укладывается в `subagent.maxDepth` по
  умолчанию.
- Несколько задач, каждая по SDD, — контроллер фоновый сабагент на план,
  глубина 2.

Skill MUST проверить доступную глубину до первого диспатча и MUST записать
рулинг с откатом в режим главной сессии, если глубина меньше нужной.

#### Scenario: Одна сложная задача
- **WHEN** в сессии один план и он архитектурный
- **THEN** контроллером остаётся главная сессия, а субагенты вызываются с
  глубины 1

#### Scenario: Глубина не поднята
- **WHEN** выбрано несколько параллельных планов, а `subagent.maxDepth` равен 1
- **THEN** skill не диспатчит контроллера, фиксирует рулинг об откате в режим
  главной сессии и продолжает исполнение в нём

### Requirement: Асинхронный протокол диспатча и отчёта
Диспатч implementer'а SHALL передавать требования файлом брифа, а результат
MUST возвращаться файлом отчёта; в контекст контроллера возвращается только
статус, коммиты, одна строка сводки тестов и concerns. Контракт статусов:
`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED`.

#### Scenario: Отчёт файлом
- **WHEN** implementer завершил задачу
- **THEN** полный отчёт лежит в файле отчёта, а в ledger и контекст попали
  только статус, коммиты и строка тестов

### Requirement: Ожидание без блокировки
Skill MUST NOT ждать ребёнка синхронно: в DSH такого средства нет. Пока
у контроллера есть локальная работа, он MUST продолжать её; когда работы нет,
он MUST закончить ход и продолжить по уведомлению о завершении. Перед каждым
следующим диспатчем контроллер MUST сверить живых детей через `list_agents`,
чтобы поймать завершившегося без отчёта.

#### Scenario: Ребёнок завершился без отчёта
- **WHEN** уведомление о завершении не пришло, а `list_agents` показывает
  неактивного ребёнка
- **THEN** контроллер считает задачу завершённой по git-состоянию и ledger,
  а не перезапускает её

### Requirement: Ревью задачи и fix-loop
Каждая задача MUST проходить ревью по спеке и по качеству; implementer self-review
его не заменяет. Fix-loop MUST длиться не более 5 раундов: раунды 1–3 — тот же
implementer через `send_message`, раунды 4–5 — свежий implementer на тир выше.
После пятого раунда контроллер MUST адъюдицировать каждую открытую находку.

#### Scenario: Дефект найден и закрыт
- **WHEN** ревьюер задачи вернул находку по существу
- **THEN** раунд фикса уходит тому же implementer'у, ре-ревью ограничено
  исправлением, находка получает статус `fixed <commit>`

### Requirement: Ledger и маркировка находок
Своя рабочая директория плана SHALL содержать `progress.md` с первой строкой —
путём плана. Ledger MUST содержать таблицу сканирования плана, рулинги
`R-n (design #n)` и раздел `## Findings`, где у каждой находки есть маркер
источника (`T<n>.<k>`, `C-n`/`I-n`/`M-n`) и статус `fixed <commit>`,
`deferred` или `rejected <причина>`.

#### Scenario: Находка без статуса
- **WHEN** финальное ревью ветки вернуло находку, а исполнение остановлено
- **THEN** отчёт контроллера обязан показать её со статусом; находка без
  статуса считается ошибкой контроллера

### Requirement: Тира моделей и деградация
Skill MUST называть маршруты моделей явно при каждом диспатче, если выбор
модели доступен, и MUST NOT выдавать это за гарантию: у `subagent` параметры
`provider`/`model` появляются только после включения выбора модели в профиле.
Без включённого выбора модели skill MUST исполнять всё на модели сессии и
указывать это в отчёте.

#### Scenario: Выбор модели выключен
- **WHEN** профиль не включает выбор модели для `subagent`
- **THEN** все implementer'ы и ревьюеры идут на модели сессии, а отчёт
  фиксирует отсутствие тиров как наблюдение, а не как выполненное требование

### Requirement: Отличие от Claude-SDD зафиксировано
Skill SHALL содержать таблицу отличий от `subagent-driven-development` Claude
Code: синхронный `Task` против асинхронного `subagent`, наличие `send_message`,
глубина по умолчанию, выбор модели, отсутствие уведомления как штатного
ожидания. Skill MUST NOT утверждать паритет с Claude-SDD.

#### Scenario: Чтение skill перед первым диспатчем
- **WHEN** модель загрузила skill и читает таблицу отличий
- **THEN** из неё видно, что ожидание строится на завершении хода и
  уведомлении, а не на возврате значения инструмента