workhorse-ai-mcp 0.7.2 → 0.7.4

package/README.md

@@ -11,8 +11,7 @@ is never the same as *accepted* (the orchestrator verified it).
 
 ## Install
 
-The npm package is not published yet — the final name is pending a rebrand.
-Once published, add the server to your `.mcp.json`:
+Add the server to your `.mcp.json`:
 
 ```json
 {
@@ -25,7 +24,7 @@ Once published, add the server to your `.mcp.json`:
 }
 ```
 
-Until then, run it straight from the monorepo:
+Or run it straight from a checkout:
 
 ```json
 {
@@ -38,8 +37,9 @@ Until then, run it straight from the monorepo:
 }
 ```
 
-Data lives in `~/.workhorse/workhorse.db` (override with `WORKHORSE_DB`).
+Data lives in `~/.workhorse-ai/journal.db` (override with `WORKHORSE_DB`).
 On first start the server creates the directory and the database itself.
+`sync.json` always sits next to the database.
 
 ## Connect to the cloud (optional)
 
@@ -60,6 +60,17 @@ a normalized `<username>-<hostname>`. After that, every journal write is
 auto-pushed; `sync` forces a push, and `inbox`/`take` pull task intents
 from the cloud.
 
+## Orchestration skill
+
+The package ships `skills/workhorse-ai/SKILL.md` (in Russian) — the delegation
+discipline the journal is built around: orchestrator/worker roles, the
+`REPORTED != ACCEPTED` invariant, the mandatory project bootstrap, and the
+working order from `search_precedents` to `accept`.
+
+Copy it into your agent's skill directory (for Claude Code:
+`~/.claude/skills/workhorse-ai/SKILL.md`), or just hand the file to the agent
+as instructions.
+
 ## License
 
 MIT

package/mcp/server.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 // workhorse-mcp — MCP-сервер журнала делегирования оркестратор ↔ рабочая лошадка.
-// Хранилище: ~/.workhorse/workhorse.db (event sourcing: append-only events,
-// проекции tasks/incidents через триггеры, FTS5). Zero deps: node:sqlite (Node >= 22.5).
+// Хранилище: ~/.workhorse-ai/journal.db (event sourcing: append-only events,
+// проекции tasks/incidents через триггеры, FTS5); путь перекрывается
+// WORKHORSE_DB — см. resolveDbPath в sync.mjs.
+// Zero deps: node:sqlite (Node >= 22.5).
 
 import { DatabaseSync } from "node:sqlite";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -14,10 +15,11 @@ import {
 	inboxUrlFromSyncUrl,
 	loadSyncConfig,
 	pushJournal,
+	resolveDbPath,
 	writeSyncConfig,
 } from "./sync.mjs";
 
-const DB_PATH = process.env.WORKHORSE_DB ?? join(homedir(), ".workhorse", "workhorse.db");
+const DB_PATH = resolveDbPath();
 const SCHEMA_PATH =
 	process.env.WORKHORSE_SCHEMA ?? join(dirname(fileURLToPath(import.meta.url)), "..", "schema.sql");
 
@@ -844,7 +846,7 @@ function handle(msg) {
 			respond(id, {
 				protocolVersion: params?.protocolVersion ?? "2024-11-05",
 				capabilities: { tools: {}, prompts: {} },
-				serverInfo: { name: "workhorse-mcp", version: "0.7.1" },
+				serverInfo: { name: "workhorse-mcp", version: "0.7.4" },
 				instructions: SERVER_INSTRUCTIONS,
 			});
 		} else if (method === "prompts/list") {

package/mcp/sync.mjs

@@ -12,8 +12,15 @@ import { pathToFileURL } from "node:url";
 
 export const BATCH_SIZE = 200;
 
-function defaultDbPath(env) {
-	return env.WORKHORSE_DB ?? join(homedir(), ".workhorse", "workhorse.db");
+// Данные под бренд Workhorse AI: директория по бренду, файл по смыслу.
+export const DEFAULT_DB_DIR = ".workhorse-ai";
+export const DEFAULT_DB_FILE = "journal.db";
+
+// Единственный резолвер пути к базе (сервер и CLI пушера используют его же):
+// WORKHORSE_DB перекрывает всё, иначе ~/.workhorse-ai/journal.db.
+// Чистая функция — env и homedir подменяемы, тестируется без реальной ФС.
+export function resolveDbPath({ env = process.env, homedir: home = homedir() } = {}) {
+	return env.WORKHORSE_DB ?? join(home, DEFAULT_DB_DIR, DEFAULT_DB_FILE);
 }
 
 // Конфиг синка: JSON-файл {url, token, journalId} рядом с базой (sync.json),
@@ -21,7 +28,7 @@ function defaultDbPath(env) {
 // WORKHORSE_SYNC_URL / WORKHORSE_SYNC_TOKEN / WORKHORSE_SYNC_JOURNAL_ID
 // перекрывают значения файла. Нет ни файла, ни env → синк выключен (null) — это норма.
 export function loadSyncConfig({ dbPath, env = process.env, log = console.error } = {}) {
-	const resolvedDbPath = dbPath ?? defaultDbPath(env);
+	const resolvedDbPath = dbPath ?? resolveDbPath({ env });
 	const configPath = env.WORKHORSE_SYNC_CONFIG ?? join(dirname(resolvedDbPath), "sync.json");
 
 	let fileConfig = {};
@@ -48,7 +55,7 @@ export function loadSyncConfig({ dbPath, env = process.env, log = console.error
 // Перезапись существующего файла — осознанное действие пользователя (connect).
 // Возвращает путь записанного файла.
 export function writeSyncConfig({ dbPath, env = process.env, config }) {
-	const resolvedDbPath = dbPath ?? defaultDbPath(env);
+	const resolvedDbPath = dbPath ?? resolveDbPath({ env });
 	const configPath = env.WORKHORSE_SYNC_CONFIG ?? join(dirname(resolvedDbPath), "sync.json");
 	writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`);
 	return configPath;
@@ -164,7 +171,7 @@ const isCli =
 	process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 
 if (isCli) {
-	const dbPath = defaultDbPath(process.env);
+	const dbPath = resolveDbPath();
 	const config = loadSyncConfig({ dbPath });
 	if (!config) {
 		console.error(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workhorse-ai-mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": false,
   "type": "module",
   "description": "Delegation journal for orchestrator/worker AI workflows: event sourcing over SQLite with an MCP interface. Zero dependencies.",
@@ -21,11 +21,13 @@
   },
   "files": [
     "mcp/",
+    "skills/",
     "schema.sql",
     "README.md",
     "LICENSE"
   ],
   "bin": {
+    "workhorse-ai-mcp": "mcp/server.mjs",
     "workhorse-mcp": "mcp/server.mjs",
     "workhorse-sync": "mcp/sync.mjs"
   },

package/skills/workhorse-ai/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: workhorse-ai
+description: Use when delegating substantive implementation work (feature, bugfix, refactor, tests) to another agent and accepting the result — the discipline of the workhorse delegation journal (draft → delegate → report → own verification → accept).
+---
+
+# Workhorse AI — дисциплина оркестрации
+
+## Обзор
+
+Работа разделена на две роли: **оркестратор** (планирует, ставит задание,
+верифицирует, принимает) и **исполнитель** (пишет код по готовому заданию).
+Ядро дисциплины: *доверие исполнителю — ноль, доверие своей верификации — всё*.
+Исполнитель может честно ошибаться о собственном успехе — его прогон тестов
+это информация, а не доказательство.
+
+Журнал делегирования — MCP-сервер `workhorse` (инструменты `mcp__workhorse__*`):
+append-only лог событий поверх SQLite, проекции задач и инцидентов, полнотекстовый
+поиск. Журнал валидирует переходы статусов, так что руками в базу лезть не нужно
+и нельзя. Файлов задач в репозитории проекта не создавать — состояние живёт
+только в журнале.
+
+## Роли
+
+| Этап | Кто | Почему |
+|---|---|---|
+| Диагноз, root cause | оркестратор | Задание без доказанной причины = исполнитель уходит в исследование и дрейфует |
+| План и декомпозиция | оркестратор | Scope-контроль до работы, а не после |
+| Написание кода | исполнитель | По готовому заданию, с явными запретами |
+| Ревью диффа | оркестратор | Построчно, до любого прогона |
+| Сборка и полный прогон тестов | **только оркестратор** | Не делегируется никогда |
+| Коммит / push / деплой | **только оркестратор** | После собственного зелёного прогона |
+
+Мелочь в одну-три строки с уже готовым диагнозом делается инлайн: делегирование
+дороже самой правки.
+
+## Статусы и ключевой инвариант
+
+```
+DRAFT → DELEGATED → REPORTED → ACCEPTED | REWORK (→ DELEGATED …) | FAILED
+```
+
+`REPORTED` («исполнитель считает, что готово») **≠** `ACCEPTED`
+(«оркестратор верифицировал сам»). Это главный инвариант журнала: между этими
+статусами обязан лежать собственный полный прогон тестов оркестратора.
+
+## Bootstrap — жёсткое precondition
+
+Пока проект не прошёл bootstrap, с ним не работать вообще: ни `draft_task`,
+ни делегаций, ни артефактов. Bootstrap состоит из двух шагов:
+
+1. `register_project` — имя-неймспейс и `root_path`. Перед регистрацией
+   обязательно `resolve_project` (по пути и/или имени): почти-дубли
+   (`foo` ~ `foo-app`, вложенные пути) сервер отобьёт; осознанный обход —
+   `force: true`.
+2. Артефакт `Project baseline: <project>` (kind `spec`): стек и конвенции,
+   команды сборки и тестов, **базовая цифра полного прогона**, запреты для
+   исполнителей.
+
+Проверка при каждом входе в делегацию: проект есть в `list_projects` **и**
+baseline есть в `list_artifacts`. Нет — остановиться и сделать bootstrap
+(с реальным полным прогоном тестов), только потом продолжать. «Задача
+маленькая» не исключение: без эталонной цифры прогона приёмка недоказуема.
+Проект, где журнал не нужен, — просто не регистрировать.
+
+После существенных изменений проекта baseline обновить: та же `title` = новая
+версия артефакта, старая остаётся в истории.
+
+## Порядок работы
+
+1. **`search_precedents`** — обязательно ДО постановки: похожие задачи,
+   артефакты и инциденты по всем проектам. Дешевле вспомнить, чем повторить.
+2. **`record_artifact`** — если решению предшествовало обсуждение, зафиксировать
+   спеку / план / ADR / решение (kind: `spec`/`plan`/`adr`/`decision`/`note`)
+   ДО делегации. Значимое решение фиксировать сразу — иначе оно умрёт вместе
+   с сессией.
+3. **`draft_task`** — полный текст задания в `task_text`. Хорошее задание состоит,
+   по порядку, из:
+   - **контекста**: репозиторий, ветка, «прочитай инструкции проекта», стек-правила;
+   - **готового root cause**: точные `file:line`, доказательства, эталон поведения —
+     «не переисследуй»;
+   - **порядка работ**: TDD — падающий тест (зафиксируй вывод) → минимальный фикс →
+     точечный прогон → полный прогон с указанием базовой цифры («база N/N, любое
+     новое падение — твоё»);
+   - **запретов**: не коммитить, не пушить, не трогать перечисленные файлы и
+     каталоги, не расширять scope, не добавлять зависимости;
+   - **формата отчёта**: по каждому пункту «падал → прошёл» с выводом команд,
+     список изменённых файлов, находки.
+
+   Если исполнитель должен что-то оценить сам — дать критерий остановки
+   («нашёл потребителя → не удаляй, доложи»).
+4. **`delegate`** (+ запуск исполнителя). В промпт исполнителя входят: `task_id`,
+   текст задания и три обязанности журнала — `search_precedents` до старта;
+   прогресс по ходу через `record_artifact` (kind `note`, привязан `task_id`,
+   стабильный `title` вида `progress: <slug>` — версионируется); `submit_report`
+   в конце. Отчёт полезно дублировать файлом: файл переживает крах shell'а
+   исполнителя, а событие в журнале при крахе до `submit_report` — нет.
+5. Пока исполнитель работает, оркестратор не ждёт вслепую: поллит `get_task` и
+   `list_artifacts` по `task_id`. Если исполнитель умер до `submit_report` —
+   оркестратор сдаёт отчёт в журнал сам из файла.
+6. **Приёмка**: прочитать отчёт → **дифф построчно**, сверить со scope задания →
+   собственная сборка и **полный** прогон тестов → сравнить с базовой цифрой.
+   Новые падения → сначала подозревать интерференцию (осиротевшие фоновые
+   сборки, гонка за артефактами, флейки инфраструктуры), потом код.
+7. Ровно одно из: **`accept`** (только после зелёного прогона и коммита,
+   с `verify_commit`) / **`request_rework`** (затем снова `delegate`) /
+   **`mark_failed`**.
+8. Были грабли → **`record_incident`**: описание симптома и урок на будущее.
+
+Обзор состояния: `get_task` (задача + история событий), `list_tasks`
+(фильтры по статусу и проекту), `list_artifacts`.
+
+## Правила журнала
+
+- Статус меняется только событием через MCP. Прямой INSERT мимо сервера
+  обходит валидацию переходов.
+- Артефакты версионируются: повторная запись с тем же `title` = новая версия,
+  старая остаётся в истории.
+- Продолжение уже закрытой задачи — всегда **новая** задача + `link_tasks`
+  (`kind: continues`) на старую; rework-цикл живёт только внутри незакрытой.
+  Работа, найденная по ходу другой, — новая задача + `discovered_from`.
+- Журнал — информация для поиска и ретроспективы. Доказательство приёмки —
+  собственный прогон оркестратора, а не запись в базе.
+
+## Известные грабли
+
+| Симптом / соблазн | Реальность |
+|---|---|
+| «Исполнитель написал: все тесты прошли» | Прогон исполнителя — информация, не доказательство. Песочница умеет съедать падение таймаутом. |
+| Исполнитель завис на сборке или тестах | Не ждать: остановить задачу, код обычно уже написан, верификация всё равно твоя. |
+| Внезапная пачка падений, прогон в разы дольше обычного | Почти всегда интерференция с осиротевшими процессами сборки, а не дифф. Прибить, перегнать. |
+| Два-три зелёных прогона подряд «доказали», что база стабильна | При флейке такая серия выпадает сама собой. Связывать падения с правкой только после A/B (stash → прогон → pop → прогон), минимум три пары. |
+| «Задание простое, root cause пусть найдёт сам» | Без готового диагноза исполнитель переисследует, дрейфует и жжёт лимиты. Диагноз — работа оркестратора. |
+| «Закоммичу его коммитом, он же автор» | Коммит = принятая ответственность. Коммитит тот, кто верифицировал. |
+| «Заведу проект в реестре на глаз» | Почти-дубли плодятся мгновенно, а миграция-переименование базы однажды уносит данные. Сначала `resolve_project`; переносы базы — только с бэкапом. |
+| Перепечатать токен руками, «тут же одна строка» | Одна опечатка = битые креды. Только копирование, после записи — сверка. |
+| Смешать в одной команде работу в worktree и в основном репозитории | Merge ответит «Already up to date», прогон отработает вхолостую. Разносить по отдельным вызовам. |
+
+## Облако — опциональный слой
+
+Журнал полностью работает офлайн; синхронизация с облаком добавляется поверх
+и ничего не меняет в дисциплине.
+
+- **`connect`** — проверяет соединение и записывает конфиг синка рядом с базой.
+  После этого каждая запись в журнал уезжает наверх fire-and-forget.
+- **`sync`** — форсированный пуш (направление строго вверх: журнал наверх,
+  журнал не переписывается облаком).
+- **`inbox`** / **`take`** — намерения задач приходят из облака: `inbox` показывает
+  очередь, `take` забирает намерение в работу. Намерение — это ещё не задание:
+  оно проходит обычный путь через `draft_task` с полным текстом.
+
+Недоступное облако не должно блокировать работу: локальный журнал — источник
+истины, пуш — транспорт.