ee0d876f6b
Design note и spec delta для фазы #41: два режима контроллера (главная сессия / фоновый сабагент), асинхронный протокол диспатча и отчётов, fix-loop, ledger с ## Findings, карта из двух маршрутов моделей. Основание — измеренные ограничения DSH 0.2.1-rc.3: subagent.maxDepth по умолчанию 1, у subagent нет provider/model без modelSelectionSettings, выбор модели работает сразу только в workflow.agent(). Co-Authored-By: DeepSeek Harness <noreply@deepseek.com>
160 lines
12 KiB
Markdown
160 lines
12 KiB
Markdown
# Design: DSH-native SDD
|
||
|
||
## Context
|
||
|
||
Claude-SDD (`~/.dsh/skills/subagent-driven-development/SKILL.md`) опирается на
|
||
синхронный `Task`: контроллер вызвал implementer'а и в том же ходе получил
|
||
отчёт. DSH так не умеет — и это не деталь, а другая форма исполнения.
|
||
|
||
Что измерено в DSH 0.2.1-rc.3 (`@deepseek-ai/dsh-tool-subagent`,
|
||
`dsh-subagent`, `dsh-tool-workflow`, `dsh-workflow-ptc`):
|
||
|
||
| Свойство | Значение в DSH | Следствие для SDD |
|
||
|---|---|---|
|
||
| `subagent` возвращает | `started subagent <id>` сразу, результат — уведомлением позже | нет синхронного ожидания; ход контроллера заканчивается |
|
||
| Продолжение ребёнка | `send_message` (провайдер `spawn` continuable) | раунды фикса идут в того же implementer'а |
|
||
| `subagent_fork` | наследует завершённые ходы родителя | для implementer'а не годится: нужен свежий контекст |
|
||
| `subagent.maxDepth` | по умолчанию **1** (настройка сервиса, volatile) | контроллер-сабагент не позовёт implementer'а, пока не поднято до 2 |
|
||
| Выбор модели у `subagent` | только при `modelSelectionSettings: true` на строке `tool-subagent`; иначе ребёнок наследует модель сессии | «укажи модель в dispatch» невыполнимо без правки профиля |
|
||
| `workflow` | синхронный, один вызов инструмента; `agent(prompt, {schema, provider, model, label, phase})` | годится для детерминированного fan-out с выбором модели без настроек |
|
||
| Кэпы `workflow` | `maxTotalAgents`, `maxConcurrentAgents`, `maxItemsPerCall` | backstop для веера; для 3 задач не упираемся |
|
||
| Наблюдение за детьми | `list_agents`, `interrupt_agent`, уведомления | «дождаться» = закончить ход и проснуться от уведомления |
|
||
| Модели в окружении | `deepseek-official/deepseek-flash`, `deepseek-official/deepseek-v4-pro` | три тира роли схлопываются в два |
|
||
|
||
Строка `subagent-model-selection-settings` есть в web/desktop-профиле и
|
||
отсутствует в headless. Поэтому флаг `modelSelectionSettings` нельзя ставить в
|
||
бандл: headless упадёт на загрузке с «requires … in the Host scope». Он живёт
|
||
в opt-in overlay профиля.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals**
|
||
- Инструкция, по которой DSH-сессия исполняет план без вранья о возможностях
|
||
платформы: два режима контроллера, протокол отчётов, ревью задачи, fix-loop,
|
||
ledger с `## Findings`, финальное ревью.
|
||
- Проверяемый прогон: план из 3 задач в temp-репозитории, дефект найден
|
||
ревьюером и закрыт в fix-loop.
|
||
- Тесты, идущие без DSH runtime.
|
||
- Явная таблица отличий от Claude-SDD.
|
||
|
||
**Non-Goals**
|
||
- Паритет с `Task`: его не будет, и это фиксируется, а не имитируется.
|
||
- Переписывание `~/.dsh/skills/subagent-driven-development/` — skill
|
||
superpowers остаётся как есть; DSH-семантика живёт в отдельном skill.
|
||
- Правка `roles/dev.md` в общем слое: роль для DSH — слой `~/.dsh/roles`.
|
||
- Автоматическое включение выбора модели и глубины: это решение владельца.
|
||
|
||
## Решения владельца (brainstorming 24.10.2026)
|
||
|
||
- **Режим контроллера зависит от контекста, а не один на всех.**
|
||
Одна сложная задача — контроллер главная сессия. Несколько задач параллельно,
|
||
каждая по SDD, — контроллер фоновый сабагент на задачу.
|
||
|
||
## Design
|
||
|
||
### Режим 1 — главная сессия контроллер
|
||
|
||
Главная сессия читает план, ведёт ledger, диспатчит `subagent` (depth 1,
|
||
укладывается в дефолтный `maxDepth: 1`), получает уведомление, диспатчит
|
||
ревьюера, при находках — `send_message` implementer'у. Плюс: рулинги по
|
||
конфликтам плана принимает тот, у кого есть спека и контекст. Минус: контекст
|
||
главной сессии растёт, поэтому отчёты — файлами, а в контекст возвращается
|
||
только статус, коммиты и одна строка тестов.
|
||
|
||
### Режим 2 — фоновый контроллер
|
||
|
||
Один `subagent` на план, `maxDepth: 2`. Контроллер не блокируется: диспатч
|
||
implementer'а возвращает id, ход заканчивается, уведомление о завершении
|
||
начинает следующий ход. Пропущенное уведомление ловится `list_agents` перед
|
||
следующим диспатчем. Главная сессия в это время свободна для другой задачи.
|
||
|
||
### Протокол (общий для обоих режимов)
|
||
|
||
1. Setup: ledger `.superpowers/sdd/<plan>/progress.md`, первая строка —
|
||
путь плана; скан плана на конфликты (таблица в ledger, рулинги до Task 1).
|
||
2. Dispatch implementer'а: brief файлом, отчёт файлом, контракт — `DONE`,
|
||
`DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED`.
|
||
3. Ревью задачи: пакет диффа файлом, вердикт по спеке и по качеству, находки
|
||
`T<n>.<k>`.
|
||
4. Fix-loop до 5 раундов: раунды 1–3 — тот же implementer через
|
||
`send_message`, 4–5 — свежий и на тир выше; затем адъюдикация.
|
||
5. Финальное ревью ветки: `C-n`/`I-n`/`M-n`, один fix-диспатч, одно
|
||
скоуп-ревью.
|
||
6. Ledger: `## Findings` с маркером и статусом; рулинги `R-n (design #n)`.
|
||
|
||
### Модели
|
||
|
||
Два маршрута вместо трёх тиров:
|
||
|
||
| Роль в SDD | Маршрут | Почему |
|
||
|---|---|---|
|
||
| implementer по готовому коду из плана | `deepseek-official/deepseek-flash` | транскрипция + тесты |
|
||
| implementer по прозе, интеграция | `deepseek-official/deepseek-v4-pro` | решение в нескольких файлах |
|
||
| ревью задачи, ре-ревью | `deepseek-official/deepseek-v4-pro` | вердикт важнее цены |
|
||
| финальное ревью ветки | `deepseek-official/deepseek-v4-pro` | самый широкий дифф |
|
||
|
||
Без overlay всё идёт на модели сессии (`deepseek-flash`); тиры становятся
|
||
недоступны, и инструкция это явно говорит, а не молча игнорирует.
|
||
|
||
### Где живёт
|
||
|
||
`dsh/skills/sdd/SKILL.md` — в репозитории обвязки, ставится
|
||
`dsh/install.sh --skills` в `~/.dsh/skills`. Claude Code его не получает:
|
||
DoD порта требует, чтобы CC-харнес не менялся.
|
||
|
||
## Альтернативы
|
||
|
||
- **Только workflow.** Детерминированный fan-out силён для независимых задач,
|
||
но решения по конфликтам плана, адъюдикация находок и «стоп, план врёт»
|
||
требуют суждения в моменте. Скрипт может ветвиться по структурному ответу
|
||
ревьюера, но не может решить, что находка неверна.
|
||
- **Только фоновый контроллер.** Дороже на одну задачу и требует поднятой
|
||
глубины; для одиночной задачи лишний уровень.
|
||
- **Гибрид.** `workflow` — для веера независимых задач внутри плана,
|
||
контроллер — для последовательной петли. Держим как расширение, в первой
|
||
версии не включаем: веер ещё не встречался в планах этого репозитория.
|
||
|
||
## Риски
|
||
|
||
- Уведомление о завершении ребёнка не пришло (обрыв, компакция) — контроллер
|
||
обязан сверяться с `list_agents` и git, а не с памятью.
|
||
- `maxDepth: 2` не поднят, а режим 2 выбран — диспатч упадёт
|
||
`subagent depth 2 exceeds maxDepth 1`; инструкция требует проверить до
|
||
старта и откатиться в режим 1 с записью рулинга.
|
||
- Ledger лежит в git-ignored scratch: `git clean -fdx` его уничтожает;
|
||
восстановление — по `git log`.
|
||
- Модели две: «haiku» из Claude-текста не существует, перенос формулировок
|
||
тиров без таблицы превратится в фикцию.
|
||
|
||
## Что должен доказать пробный прогон
|
||
|
||
| Пункт приёмки #41 | Чем доказывается |
|
||
|---|---|
|
||
| 3 задачи не теряются | ledger: три `Task N: complete`, три коммита |
|
||
| отчёты собираются | файлы отчётов implementer'ов + строки в ledger |
|
||
| ревьюер находит дефект | `T1.1` с `fixed <commit>` |
|
||
| fix-loop завершается | раунд в ledger, ре-ревью чистое |
|
||
| ledger содержит `## Findings` со статусами | сам файл |
|
||
| отличие от Claude-SDD указано | таблица выше + раздел в skill |
|
||
|
||
## Decisions made without discussion
|
||
|
||
- **24.10.2026 — overlay вместо флага в бандле.** Обоснование: headless-профиль
|
||
не содержит строку `subagent-model-selection-settings`, включённый флаг роняет
|
||
загрузку. Цена ошибки: владельцу нужно скопировать три записи в профиль
|
||
руками; забыл — работает на модели сессии.
|
||
- **24.10.2026 — карта тиров.** `flash` — транскрипция и механика, `v4-pro` —
|
||
интеграция и все ревью. Цена ошибки: дороже прогон или слабее ревью; правится
|
||
одной таблицей в skill.
|
||
- **24.10.2026 — skill ставится только в `~/.dsh`.** Обоснование: DoD порта
|
||
запрещает менять CC-харнес. Цена ошибки: в Claude-сессиях инструкции про
|
||
DSH-режимы нет — там работает исходный `subagent-driven-development`.
|
||
- **24.10.2026 — гибрид отложен.** `workflow` описан как расширение, не
|
||
реализуется в этом change. Цена ошибки: веер задач придётся ввести позже
|
||
отдельной правкой skill.
|
||
|
||
## Открытые вопросы
|
||
|
||
- Нужно ли после приёмки добавить в `~/.dsh/roles/dev.md` строку «в DSH
|
||
исполнение плана — skill `sdd`» (сейчас роль ссылается на superpowers-SDD).
|