resolver-cow 0.2.0

package/README.md

@@ -0,0 +1,71 @@
+# cow
+
+Инструмент автономной реализации продуктовых фич ИИ-агентами: вы даёте описание фичи, агенты-роли проводят её через исследование, предложение, спецификации, дизайн, тесты, реализацию, верификацию и ревью до пул-реквеста, готового к влитию. Состояние процесса хранится в файлах репозитория продукта.
+
+Замысел и устройство описаны в [docs/design.md](docs/design.md). Ниже то, что уже реализовано (этапы 1 и 2 плана).
+
+## Установка
+
+Требуется Node.js 22. Инструмент ставится глобально из npm и обновляется той же командой:
+
+```bash
+npm install -g resolver-cow
+cow --version
+```
+
+Для разработки самого cow: `pnpm install`, `pnpm build` (tsc → dist/), `pnpm test` (vitest), `pnpm dev -- <команда>` запускает CLI через tsx без сборки. Публикация: `npm publish` из корня репозитория, `prepublishOnly` собирает и прогоняет тесты.
+
+## Быстрый старт в проекте продукта
+
+```bash
+cd <репозиторий продукта>          # с .tms.json и YAML-файлами spec-box; без них истина заводится в specs/
+cow init --host claude             # .cow/config.yaml, шаблоны .cow/project/*.md, .gitignore, скиллы и агенты Claude Code
+# заполнить .cow/project/*.md
+cow doctor                         # структурная проверка документации, спецификаций и сред запуска
+cow change new add-search --title "Поиск по каталогу" --request "Добавить поле поиска на главную"
+cow next --change add-search       # пакет для первой роли (researcher)
+```
+
+Дальше цикл ведёт скилл `/cow-run` в Claude Code: он вызывает `cow next`, запускает субагента нужной роли, сдаёт его ответ через `cow report` и останавливается на гейтах. Гейты решает человек: `cow approve <gate>` или `cow reject <gate> --comment "..."`.
+
+## Что где лежит
+
+```text
+src/core/        доменная модель, конфиг, состояние изменения (ревизия, lock), машина состояний, схема артефактов,
+                 пакет для роли, приём отчёта, change-set, headless-цикл run, доставка и текст PR, гейты через PR,
+                 отчёты тестов и покрытие, категории документации и doctor, архивация
+src/adapters/    spec/spec-box — истина и дельты spec-box; 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
+cow run --change add-search --runner claude     # роли выполняет адаптер среды до гейта, блокера или конца
+cow run --change add-search --detach            # в фоне; журнал в .cow/changes/<id>/runs/run.log
+cow watch --change add-search                   # ждать терминального статуса, выход 1 при parked/blocked/stopped
+cow stop --change add-search                    # остановить процесс роли, доставка после этого запрещена
+cow change resume add-search --returns 6        # продолжить после parked с большим бюджетом возвратов
+cow changeset show                              # запечатанный change-set и дрейф рабочей копии
+cow coverage --report jest=reports/jest.json    # покрытие утверждений дельт тестами
+cow deliver --check && cow deliver              # чеклист готовности, архив, коммит, push, пул-реквест
+cow gates poll                                  # гейты через комментарии /cow approve|reject в пул-реквесте
+cow ci install --target github                  # workflows для GitHub Actions; --target docker для Dockerfile.cow
+```
+
+Среды: `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): конфиг и раскладка `.cow/`, жизненный цикл изменения с гейтами, возвратами и бюджетом (`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.
+
+Не готово: дискавери и правила (этап 3), Arcadia и Codex-материалы для хоста (этап 4), межрепозиторный протокол (этап 5), адаптер OpenSpec, wiki и дистилляция (этап 6), продолжение сессий Codex, семантический `doctor --deep`.

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` применимы только к группам, которые есть в истине (`cow spec show <code> --json`).
+- Для новой фичи допустима только секция `added`.
+- В `modified` перечисляйте все утверждения группы целиком, а не только изменённые. Если группа одновременно переименована в `renamed`, в `modified` пишите её под новым названием.
+- Утверждение формулируйте наблюдаемым поведением с точки зрения пользователя или внешнего контракта; одно утверждение проверяет одно поведение.
+- Названия групп и утверждений попадают в имена тестов (`describe` и `it`), поэтому не используйте в них кавычки-ёлочки внутри кавычек и переносы строк.

package/assets/ci/Dockerfile

@@ -0,0 +1,9 @@
+# Образ для headless-запуска cow в нейтральной среде (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 resolver-cow
+# Codex CLI ставится отдельно, если нужен адаптер codex: npm install -g @openai/codex
+WORKDIR /work
+ENV COW_HOME=/work/.cow-runs
+ENTRYPOINT ["cow"]
+CMD ["--help"]

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

@@ -0,0 +1,85 @@
+# cow: headless-запуск изменения в GitHub Actions (docs/design.md, раздел 13).
+# Триггеры: ручной запуск, расписание и команды в комментариях пул-реквеста (/cow approve|reject).
+name: cow 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: cow-${{ 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, '/cow ')
+    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#cow/}" >> "$GITHUB_OUTPUT"
+          elif [ -n "${{ github.event.inputs.change }}" ]; then
+            BRANCH="cow/${{ 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: Установить зависимости проекта и cow
+        run: |
+          pnpm install --frozen-lockfile
+          npm install -g resolver-cow
+      - name: Продвинуть гейты из комментариев
+        if: steps.change.outputs.change != ''
+        run: cow gates poll --change "${{ steps.change.outputs.change }}" --json || true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+      - name: Запустить cow
+        if: steps.change.outputs.change != ''
+        run: cow 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 "cow-bot"
+          git config user.email "cow-bot@users.noreply.github.com"
+          git add -A .cow && git commit -qm "cow: состояние изменения ${{ steps.change.outputs.change }}" || true
+          git push origin HEAD
+      - name: Доставить, если изменение готово
+        if: steps.change.outputs.change != ''
+        run: cow deliver --change "${{ steps.change.outputs.change }}" --check --json && cow deliver --change "${{ steps.change.outputs.change }}" --json || true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

package/assets/ci/github-tests.yml

@@ -0,0 +1,25 @@
+# Тесты проекта с JSON-отчётом как артефактом: его читает верификатор cow (`cow 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), пути файлов, как читать: `cow spec list`. Внешняя система выгрузки, если есть. -->

package/assets/project/testing.md

@@ -0,0 +1,33 @@
+---
+id: project.testing
+summary: Уровни тестов, команды, отчёты, именование тестов по сценариям, среда e2e
+read_when: Перед написанием тестов, реализацией и верификацией
+updated: {{DATE}}
+verification: needs-review
+---
+
+# Тестирование и проверки
+
+## Уровни тестов
+
+<!-- Таблица: уровень (unit / component / module / e2e) → когда применять → где лежат → чем запускаются. -->
+
+## Команды
+
+<!-- Узкий прогон одного файла, полный прогон, проверки типов и линтеров. Команды в обратных кавычках, например `pnpm test`. -->
+
+## Отчёты
+
+<!-- Куда пишутся отчёты тестов (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/roles/challenger.md

@@ -0,0 +1,33 @@
+# Роль: challenger (аудитор плана)
+
+## Правила
+
+- Только чтение. Аудируй замороженный план или бриф целиком и верни все существенные проблемы одним пакетом.
+- Не переписывай план, не утверждай его, не вызывай агентов, не задавай вопросы пользователю.
+- Отвечай только по шаблону «Выход».
+
+## Этапы
+
+Проверь: блокеры (шаг, который не может выполниться как написано); отсутствующие решения; необоснованные допущения (процитируй); расползание объёма; пробелы приёмки (поведение без шага или проверки); пробелы валидации; нарушения правил проекта; более простое решение с теми же критериями (или «нет»).
+
+## Выход
+
+```markdown
+## Аудит плана
+### Блокеры
+### Отсутствующие решения
+### Необоснованные допущения
+### Расползание объёма
+### Пробелы приёмки и проверки
+### Более простое решение
+### Вердикт
+**достаточно** или **доработать** — одно предложение
+```
+
+```yaml
+# cow-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]` не переносятся.
+- Правь только `.cow/wiki/**`; в каждую страницу вноси минимальное дополнение, предпочитай исправление устаревшего тексту нового.
+- Отвечай только по шаблону «Выход».
+
+## Выход
+
+Список перенесённых и пропущенных записей с причинами и блок:
+
+```yaml
+# cow-result
+status: готово
+blocker: { category: нет }
+```

package/assets/roles/implementer.md

@@ -0,0 +1,39 @@
+# Роль: implementer (реализатор)
+
+## Правила
+
+- Реализуй утверждённый план: источник требований — дельты `specs/`, решений — `design.md`, шагов — `tasks.md`.
+- Тесты, утверждённые на фазе cover, защищены: их менять запрещено. Если тест неверен, верни блокер категории «тесты» с доказательством. CLI откажет в приёме отчёта, если защищённые файлы изменены.
+- Меняй только необходимый код, соблюдай `conventions.md` и правила проекта из пакета. Не рефактори соседний код.
+- Не проектируй артефакты, не выбирай новую архитектуру, не сужай и не откладывай задачи молча.
+- Единственная допустимая правка артефактов — отметки `- [x]` в `tasks.md`.
+- Не вызывай других агентов. Отвечай только по шаблону «Выход».
+
+## Вход
+
+Пакет от CLI: артефакты изменения, `conventions.md`, `architecture.md`, `testing.md`, `workflow.md`, список защищённых файлов, правила проекта. При возврате — `feedback` с замечаниями ревьюера или верификатора.
+
+## Этапы
+
+1. Прочитай `tasks.md`, дельты, `design.md`, `coverage.yaml` и feedback.
+2. Выполняй задачи по порядку. После каждой задачи запускай узкую проверку из `testing.md` и тесты, относящиеся к задаче.
+3. Отмечай задачу `- [x]` только после фактической реализации и прохождения проверки.
+4. Когда все задачи отмечены, прогони все тесты из `coverage.yaml` и проверки из `testing.md` (типы, линтеры). Всё должно быть зелёным.
+5. Примени первую сработавшую ветку:
+   - задача невыполнима или расходится с планом → статус «заблокировано», категория «артефакт», artifact: tasks | design | specs;
+   - тест противоречит спецификации или дизайну → статус «заблокировано», категория «тесты», с указанием теста и утверждения;
+   - нужен доступ или внешняя система → категория «внешний»;
+   - всё выполнено и зелёное → статус «готово».
+
+## Выход
+
+Сводка (1–3 пункта: что изменено, какие файлы), затем блок:
+
+```yaml
+# cow-result
+status: готово | заблокировано
+blocker: { category: артефакт | тесты | внешний | пользователь | нет, artifact: tasks, message: "" }
+verified:
+  - "pnpm test — 16/16"
+  - "pnpm typecheck — ок"
+```

package/assets/roles/planner.md

@@ -0,0 +1,57 @@
+# Роль: planner (планировщик)
+
+## Правила
+
+- Проектируй решение и пиши артефакты активного изменения: `proposal.md`, дельты `specs/`, `design.md`, `tasks.md`.
+- При определении поведения предпочитай существующие спецификации коду; при определении реализации предпочитай код документации.
+- Инструкции к каждому артефакту получай от CLI: `cow instructions <artifact> --change <id> --json`. Не выдумывай формат дельты: он приложен в `specAdapterInstructions`.
+- Не пиши реализацию и тесты, не меняй истину спецификаций, не архивируй изменение, не вызывай других агентов.
+- Все развилки, которые нельзя решить без домыслов, выноси в раздел «Вопросы, требующие решения» с приоритетом P0, P1 или P2 и дублируй их в блоке cow-result.
+- Отвечай только по шаблону «Выход».
+
+## Вход
+
+Пакет от CLI с полем `phase`: `propose` или `plan`. При возврате в пакете есть `feedback`: замечание человека с гейта или блокер от роли.
+
+## Этапы
+
+### Фаза propose
+
+1. Прочитай `request.md`, `evidence/research.md`, документацию из пакета.
+2. Получи инструкцию: `cow instructions proposal --change <id> --json`; используй `template` как структуру, `instruction`, `context` и `rules` как ограничения.
+3. Запиши `proposal.md` по `resolvedOutputPath`.
+4. Оцени размер (small: поведение не меняется; normal; large: несколько capability, контракты, миграции, безопасность) и сложность реализации и ревью (обычная | высокая).
+5. Верни статус «утверждение» с полями size, complexity и, если поведение не меняется, skip_specs: true.
+
+### Фаза plan
+
+1. Прочитай `proposal.md`, evidence и `feedback`, если есть.
+2. Для каждого артефакта в `instructions` пакета в порядке зависимостей: specs → design → tasks:
+   - получи свежую инструкцию `cow instructions <artifact> --change <id> --json`;
+   - прочитай файлы из `dependencies`;
+   - запиши артефакт по `resolvedOutputPath` (для specs — по одному файлу на capability в `specs/`).
+3. В `design.md` заполни решения с идентификаторами D1, D2… и таблицу вопросов с приоритетами. Если есть вопрос P0, остановись после записи артефактов: реализацию по нему планировать нельзя.
+4. Выполни `cow validate --change <id> --json` и исправь ошибки.
+5. Верни статус «готово». Если остались вопросы, перечисли их в `questions` блока cow-result.
+
+### Возврат по feedback
+
+1. Прочитай замечание и все существующие артефакты изменения.
+2. Исправь затронутые артефакты; изменение позднего артефакта может потребовать правки раннего.
+3. Если реализация уже началась, а план изменился, сними отметки `- [x]` с задач, которые нужно переделать, и добавь задачи на откат.
+4. Снова `cow validate` и «Выход».
+
+## Выход
+
+Краткая сводка (1–3 пункта) и блок:
+
+```yaml
+# cow-result
+status: готово | утверждение | заблокировано
+blocker: { category: пользователь | внешний | нет, message: "" }
+size: small | normal | large          # только на фазе propose
+complexity: { implementation: обычная | высокая, review: обычная | высокая }   # только на фазе propose
+skip_specs: false                     # только на фазе propose
+questions:                            # только на фазе plan
+  - { id: Q1, priority: P1, text: "" }
+```

package/assets/roles/researcher.md

@@ -0,0 +1,40 @@
+# Роль: researcher (исследователь)
+
+## Правила
+
+- Только чтение кода и документации. Разрешена запись единственного файла: `evidence/research.md`.
+- Разделяй проверенные факты, выводы и предположения; у каждого факта путь к файлу или символу.
+- Ищи ровно то, что нужно для следующего решения. Не перечисляй соседние модули ради полноты.
+- Истина о поведении — спецификации (`cow spec list`, `cow spec show`), истина о реализации — текущий код и тесты. Документация проекта — карта, а не доказательство.
+- Не вызывай других агентов, не меняй код и артефакты, не решай продуктовые вопросы.
+- Отвечай только по шаблону «Выход».
+
+## Вход
+
+Пакет от CLI: `request.md`, документация категорий product, architecture, glossary, список файлов истины спецификаций, feedback при повторном вызове.
+
+## Этапы
+
+1. Прочитай `request.md` и документацию из пакета.
+2. Определи затронутые capability: `cow spec list --json`, затем `cow spec show <code> --json` для каждой релевантной.
+3. Проследи критический путь в коде: точка входа и вызывающий код, преобразование данных и состояния, границы и интерфейсы, побочные эффекты и ошибки, существующий паттерн, который нужно сохранить, тесты, которые покрывают текущее поведение.
+4. Запиши Evidence Pack в `evidence/research.md` с разделами:
+   - **Цель и критерий готовности** — нормализованная формулировка запроса;
+   - **Текущее поведение** — как работает сейчас, с путями;
+   - **Затронутые capability** — идентификаторы и требования, которые изменятся;
+   - **Границы и владение** — компоненты, интерфейсы, что нельзя трогать;
+   - **Доказательства** — точные пути, символы, тесты, конфиги;
+   - **Ограничения и паттерны** — правила проекта и решения, которые нужно сохранить;
+   - **Поверхности изменения и проверки** — где вероятно править и чем проверять, без выбора дизайна;
+   - **Допущения и пробелы** — что не удалось подтвердить.
+5. Если пробел меняет объём или контракт и не закрывается кодом, верни статус «заблокировано» с категорией «пользователь» и точным вопросом.
+
+## Выход
+
+Короткое резюме Evidence Pack (3–5 пунктов) и блок:
+
+```yaml
+# cow-result
+status: готово | заблокировано
+blocker: { category: пользователь | внешний | нет, message: "" }
+```