@goodandready/dsh-kanban 0.1.17 → 0.1.19

package/docs/plans/2026-08-26-dsh-kanban-0.1.md

@@ -0,0 +1,169 @@
+# dsh-kanban — план реализации
+
+> **Для исполнителя:** это план для агента, у которого нет контекста обсуждения.
+> Перед любой правкой плагина DSH загрузи `dsh-plugin-authoring`.
+> Перед правкой профиля `web` — `dsh-web-profile-repair`.
+> Работа ведётся по `gitea-project-workflow`: issue → worktree от свежего
+> `origin/main` → WIP PR → ревью → merge → deploy → cleanup → закрытие issue.
+
+**Цель:** доска задач внутри DeepSeek Harness, которая берёт задачи из Gitea,
+показывает по ним ход работы и умеет запускать по каждой задаче отдельную
+сессию агента с выбранной моделью.
+
+**Архитектура:** отдельный плагин `@goodandready/dsh-kanban` со своим
+хранилищем задач. Gitea-доступ не дублируется — используется существующий
+плагин `@goodandready/dsh-gitea`, которому для этого добавляется сервис cordis.
+Запуск работы идёт через штатные сервисы ядра `agents`/`sessions`; плагин
+поднимает сессию и отдаёт первое сообщение, дальше работу ведёт агент по
+действующему воркфлоу.
+
+**Стек:** Node (ESM), cordis, `@deepseek-ai/schemastery`, React в браузерной
+половине через `window.__ModuleLoader__`, хранилище — `node:sqlite`.
+
+## Глобальные ограничения
+
+- Имя пакета `@goodandready/dsh-kanban` обязано совпадать в трёх местах:
+  `package.json` → `name`, `cordis.patch.yml` → `name:`, `lib/client.js` →
+  `load({ id })`. Короткий id патча — `dsh-kanban`.
+- Пространство настроек: `dsh-kanban`. Ключ слота карточки настроек обязан быть
+  равен пространству настроек, иначе карточка молча не появится.
+- Настройки — карточкой в `settings.plugin.item`. Свой раздел настроек НЕ
+  заводить. Раздел верхнего уровня заводится только для экрана доски.
+- Токен Gitea плагин не хранит, не спрашивает и не логирует. Доступ — только
+  через сервис `gitea` из `dsh-gitea`.
+- Ни абсолютных путей, ни адресов инстансов, ни имён машин в коде и README.
+  Машинно-зависимое живёт в настройках с пустым значением по умолчанию.
+- Все Git-операции — только через wrapper `git-<agent>`. Bare `git` запрещён.
+- Conventional Commits обязательны: `<type>(<scope>)!: <действие>`, footer
+  `Refs: #<номер>`.
+- Тесты идут без харнесса и без сети: `node --test test/*.test.mjs`.
+- Всё поднятое в `ctx.effect` гасится возвращённым уборщиком.
+- Хуки React объявляются выше всех возвратов.
+
+## Колонки доски
+
+Колонки повторяют реальный воркфлоу, а не абстрактный «в работе → готово».
+
+| Колонка | Признак входа |
+|---|---|
+| `backlog` | issue есть, никто не взял |
+| `in-progress` | сессия поднята, в issue есть стартовый комментарий с планом и веткой |
+| `review` | PR снят с WIP, ревьюер даёт PASS/FAIL |
+| `deploy` | PR влит в `main`, ждём согласованный deploy и production-проверку |
+| `cleanup` | ветка в Gitea, worktree и локальная ветка ещё не удалены |
+| `done` | issue закрыт И cleanup записан в итоговом комментарии |
+
+Колонка `cleanup` существует потому, что по воркфлоу задача не завершена, пока
+cleanup не сделан и не записан. Доска, отправляющая карточку в `done` по merge,
+будет врать ровно там, где копятся забытые ветки.
+
+WIP PR НЕ двигает карточку в `review`: он открывается рано и означает «работа
+идёт», а не «смотрите».
+
+## Что плагин НЕ делает
+
+Эти границы заданы воркфлоу и нарушать их нельзя:
+
+- Не создаёт ветки и worktree. По воркфлоу агент сначала делает preflight
+  (открытые ветки, `git status --short`) и только потом заводит worktree от
+  свежего `origin/main`. Плагин, создающий ветку заранее, ломает preflight.
+- Не пишет стартовый комментарий в issue — это делает агент после preflight.
+- Ветка и worktree на карточке — НАБЛЮДЕНИЕ, вычитанное из issue и событий
+  Gitea, а не намерение, заданное плагином.
+- Не трогает Hermes Kanban. Это другая система, и она этому CLI запрещена.
+
+## Выпуски
+
+**0.1 — доска, импорт, запуск.** Задачи хранятся локально, импортируются из
+Gitea по кнопке, карточки двигаются вручную, по кнопке «Начать» поднимается
+сессия с выбранной моделью. Синхронизация односторонняя: Gitea → канбан, в
+момент импорта и по кнопке обновления.
+
+**0.2 — автоперемещение.** События сессии агента, события Gitea, журнал
+переходов с источником. Инструмент `board_move` для агента пишется, но по
+умолчанию выключен — включается вместе с правкой скилла
+`gitea-project-workflow`.
+
+**0.3 — двусторонняя синхронизация.** Вебхуки Gitea, разрешение конфликтов по
+времени изменения, очередь повторов, деградация до опроса.
+
+## Состав 0.1
+
+| Issue | Репозиторий | Тема |
+|---|---|---|
+| G1 | dsh-gitea | Выставить сервис `gitea` наружу |
+| G2 | dsh-gitea | Техдолг: `gitea_worktree_add` зовёт bare git |
+| K1 | dsh-kanban | Каркас плагина и карточка настроек |
+| K2 | dsh-kanban | Хранилище задач |
+| K3 | dsh-kanban | HTTP-маршруты доски |
+| K4 | dsh-kanban | Импорт задачи из Gitea |
+| K5 | dsh-kanban | Экран доски |
+| K6 | dsh-kanban | Запуск работы по задаче |
+| K7 | dsh-kanban | Чип задачи в шапке чата |
+| K8 | dsh-kanban | Документация и релизный гейт 0.1 |
+
+Порядок: G1 → K1 → K2 → K3 → (K4, K5 параллельно) → K6 → K7 → K8.
+G2 независим и может идти когда угодно.
+
+## Структура файлов
+
+```
+lib/index.js        точка входа хоста: Config, apply, регистрация маршрутов
+lib/store.js        хранилище задач: схема, CRUD, дробный индекс
+lib/order.js        дробный индекс (чистая функция, без БД)
+lib/import.js       перенос issue Gitea в задачу доски
+lib/launcher.js     запуск сессии по задаче
+lib/routes.js       обработчики HTTP
+lib/client.js       браузерная половина: раздел доски, карточка настроек, чип
+test/*.test.mjs     тесты без харнесса и без сети
+```
+
+Разделение по ответственности, а не по слою. `order.js` отделён от `store.js`
+потому, что дробный индекс — единственная нетривиальная логика в хранилище и
+проверяется без БД вообще.
+
+## Проверенные интерфейсы ядра
+
+Ниже — реальные сигнатуры, снятые с исходников, а не пересказ. Исполнитель
+может опираться на них как есть.
+
+Создание сессии с выбранной моделью и первое сообщение:
+
+```js
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+
+const handle = await ctx.agents.create({
+  sessionId: SessionId(`kanban-${taskId}-${randomUUID()}`),
+  meta: { cwd },                       // ОБЯЗАТЕЛЬНО абсолютный путь
+  agentOptions: { provider, model },   // maxTokens необязателен
+})
+await handle.agent.whenIdle()
+handle.agent.followup(createUserMessage({
+  content,
+  source: { kind: 'plugin', plugin: 'dsh-kanban', form: 'task-start' },
+}))
+```
+
+- `ctx.agents.create(options)` возвращает `AgentHandle` с полями `agent` и
+  `dispose`. Живой образец — `dsh-messenger-gateway/lib/gateway.js:465`.
+- `meta.cwd` валидируется ядром: неабсолютный путь бросает исключение.
+- `agent.followup(message)` ставит обычный следующий ход и будит драйвер.
+- `agent.session.id` — идентификатор сессии, по нему карточка связывается с
+  чатом.
+- Модель по умолчанию берётся из сервиса `agentDefaultModel`; образец
+  разрешения провайдера и модели — `gateway.js:455`.
+
+События сессии, нужные в 0.2: `assistant/message`, `turn/end`,
+`approval/asked` (несёт `id`, имя инструмента, причину), `question/requested`.
+
+## Открытый технический риск
+
+`node:sqlite` — встроенный модуль Node, но он появился не во всех версиях.
+ПЕРВЫЙ шаг задачи K2 — проверить, что модуль есть в той версии Node, на которой
+крутится харнесс. Если модуля нет, хранилище делается на одном JSON-файле с
+атомарной записью (запись во временный файл рядом, затем `rename`), а схема
+таблиц из K2 переносится в форму объекта один-в-один. Дробный индекс и весь
+остальной план от выбора хранилища не зависят.
+
+Решение принимается фактом проверки, а не догадкой, и записывается в issue K2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-kanban",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Visual Kanban board for DeepSeek Harness: Gitea-backed tasks, workflow columns, and a dedicated agent session per task.",
   "type": "module",
   "main": "lib/index.js",
@@ -14,6 +14,7 @@
     "lib/",
     "cordis.patch.yml",
     "README.md",
+    "docs/",
     "LICENSE"
   ],
   "scripts": {