workflow-ai 1.1.0 → 1.3.0

package/src/skills/review-result/algorithms/verification.md

@@ -1,112 +0,0 @@
-# Алгоритм верификации результата
-
-Формализованный метод проверки что результат выполнения тикета реален, а не является галлюцинацией агента.
-
-## Вход
-
-- Тикет с заполненной секцией «Результат выполнения»
-- Список файлов из секции «Изменённые файлы»
-- Чеклист DoD с отметками `[x]`
-
-## Выход
-
-- `verified` — все артефакты реальны и соответствуют заявленному
-- `not_verified` — обнаружены расхождения + список проблем
-
-## Алгоритм
-
-### Шаг 1: Проверка существования файлов
-
-```
-ДЛЯ КАЖДОГО файла из «Изменённые файлы»:
-  1. Выполни Read(файл) или Glob(паттерн)
-  2. ЕСЛИ файл не найден через Read/Glob →
-     FALLBACK: выполни Bash("ls -la {путь}") для подтверждения
-     (Glob может не видеть файлы в новых untracked директориях)
-  3. ЕСЛИ файл не найден И через fallback → добавь в issues: "Файл {путь} не существует"
-  4. ЕСЛИ файл найден любым способом → перейди к шагу 2
-```
-
-> **⚠️ Почему fallback:** Glob/Read могут не находить файлы в новых директориях,
-> которые ещё не добавлены в git index. Bash(`ls`) работает напрямую с файловой
-> системой и всегда видит реальные файлы. Без fallback ревьюер ложно репортит
-> отсутствие файлов, которые были корректно созданы исполнителем.
-
-### Шаг 2: Проверка содержимого
-
-```
-ДЛЯ КАЖДОГО найденного файла:
-  1. Открой файл через Read
-  2. Проверь:
-     a. Файл НЕ пустой (> 0 строк содержательного контента)
-     b. Файл НЕ содержит только шаблонные плейсхолдеры
-     c. Контент соответствует типу файла (код = код, документ = текст)
-  3. ЕСЛИ файл пуст или placeholder → добавь в issues: "Файл {путь} — пустой/placeholder"
-```
-
-### Шаг 3: Проверка Summary
-
-```
-1. Найди секцию «Результат выполнения» → «Summary»
-2. ЕСЛИ Summary пуст или содержит заглушку ("TODO", "...", "Заполнить") → issues
-3. ЕСЛИ Summary < 10 слов → предупреждение (может быть слишком кратким)
-4. ЕСЛИ Summary содержательный → OK
-```
-
-### Шаг 4: Кросс-валидация DoD ↔ Артефакты
-
-```
-ДЛЯ КАЖДОГО пункта DoD отмеченного [x]:
-  1. Определи артефакт, к которому относится пункт
-  2. Открой артефакт
-  3. Проверь что критерий ДЕЙСТВИТЕЛЬНО выполнен:
-     - "Файл создан" → файл существует и не пуст
-     - "Секция X добавлена" → секция присутствует в файле
-     - "Нет ссылок на Y" → поиск Y по файлу = 0 результатов
-     - "Тесты проходят" → запустить тесты (если возможно)
-  4. ЕСЛИ критерий НЕ выполнен → issues: "DoD '{критерий}' отмечен [x], но не подтверждён"
-```
-
-### Шаг 5: Формирование результата
-
-```
-ЕСЛИ issues пуст:
-  → verified
-ИНАЧЕ:
-  → not_verified + список issues
-```
-
-## Пороги и правила
-
-| Правило | Значение |
-|---------|----------|
-| Минимум строк для «не пустой» файл | > 3 строки содержательного контента |
-| Маркеры placeholder | `TODO`, `TBD`, `XXX`, `FIXME`, `заполнить`, `...` |
-| Минимум слов в Summary | 10 слов |
-| Любой issue = failed | Да, без исключений |
-
-## Граничные случаи
-
-| Случай | Решение |
-|--------|---------|
-| Тикет с `executor_type: human` | Пропустить верификацию файлов — человек мог внести изменения вне системы |
-| Файл удалён как часть задачи | Проверить что файл действительно НЕ существует (обратная проверка) |
-| DoD содержит субъективный критерий | Оценить по best effort, отметить в комментарии |
-| Файл изменён, но не создан | Проверить что изменения присутствуют (diff или содержимое) |
-
-## Пример применения
-
-**Вход:**
-- Тикет XXX-005 с DoD: `[x] Создан workflows/process.md`, `[x] README создан`
-- Изменённые файлы: `workflows/process.md`, `README.md`
-
-**Проверка:**
-1. `Read("src/skills/example-skill/workflows/process.md")` → файл существует, 45 строк → OK
-2. `Read("src/skills/example-skill/README.md")` → файл существует, 30 строк → OK
-3. Summary: "Модульная реструктуризация..." — 15 слов → OK
-4. DoD `[x] workflows/` → файл есть, содержит шаги → verified
-5. DoD `[x] README` → файл есть, структура верна → verified
-
-**Результат:** `verified`
-
-<!-- РАСШИРЕНИЕ: добавляй новые проверки и граничные случаи ниже -->

package/src/skills/review-result/knowledge/baseline-snapshot-validation.md

@@ -1,67 +0,0 @@
-# Проверка baseline/snapshot-тестов на ревью
-
-Когда DoD тикета требует **baseline-теста**, **snapshot-сравнения**, **регрессионного эталона** или **побайтного/посимвольного совпадения** результата с зафиксированной версией, ревьюер обязан проверить **способ реализации теста**, а не только факт его существования и зелёный статус прогона.
-
-## Зачем ревьюеру проверять это отдельно
-
-«Тесты зелёные» и «файл создан» — необходимые, но не достаточные признаки. Тест может быть зелёным и одновременно не выполнять заявленной функции baseline:
-
-- ассерт по совпадению с регулярным выражением ловит только то, что регекс уже описывает; всё, что вне регекса, тест не отслеживает;
-- ассерт «значение truthy» или равенство одного поля проверяют точечный признак, а не целостный эталон;
-- проверка наличия подстроки в выводе — не сравнение с эталоном.
-
-Такие тесты **тавтологичны**: они зафиксированы лишь в той части, где автор уже знал ответ. Регрессия в любой другой части (новые поля, изменённые ключи, изменённый формат, потерянные строки stdout) проходит мимо. Если назначение теста — поймать **любую** регрессию по сравнению с эталонной версией, ассерт по фрагментам не реализует это назначение.
-
-## Триггеры применения
-
-Шаг применяется, если в DoD, секции «Детали задачи» или «Критериях успеха» родительского плана встречаются формулировки уровня семантического намерения:
-
-- baseline / эталон / reference / зафиксированный output;
-- snapshot / inline-snapshot / external-snapshot;
-- побайтное / посимвольное / точное совпадение;
-- регрессия (ловить регрессию, регрессионный тест на изменение формата);
-- «output не должен меняться», «формат стабилизирован», «контракт фиксируется».
-
-Если хотя бы одна формулировка присутствует — это не обычный «тест проходит», а заявление о наличии **эталона**, и проверка способа реализации обязательна.
-
-## Как проверять
-
-1. **Открой файл теста физически** (Read), не доверяй секции Result. Найди ассерты, относящиеся к baseline-проверке.
-2. **Сверь способ ассерта со способом, заявленным в DoD/плане:**
-
-   | Заявлено в DoD/плане | Что обязано быть в тесте | Что недопустимо |
-   |---|---|---|
-   | inline-snapshot / точное совпадение / эталон | Точное равенство (deep-equality для структур, побайтное равенство для строк) нормализованного output с зафиксированным литералом-эталоном. Эталон лежит **в файле теста как литерал** (или как сериализованный snapshot, на который тест ссылается). | Ассерт по регулярному выражению, проверка наличия подстроки, ассерт по одному полю без сверки остального вывода. |
-   | regression / not-changed / стабилизирован | Точное сравнение всего нормализованного output с эталоном. Любое отклонение должно ронять тест. | Набор фрагментарных ассертов (несколько регекс-проверок подряд) — не отвергает структурные изменения вне зон проверки. |
-   | побайтное совпадение | Бинарное/посимвольное равенство (буфер/строка целиком) после задокументированной нормализации. Нормализация описана в коде теста. | Любая «приблизительная» проверка. |
-
-3. **Проверь, что эталон существует физически.** Inline-snapshot должен быть литералом в коде; external-snapshot — отдельным файлом, на который тест ссылается. Если эталона нет — тест не baseline.
-
-4. **Проверь полноту нормализации.** Заявленные в DoD динамические поля (timestamps, абсолютные пути, рандомные id) должны нормализоваться **до** сравнения, а не игнорироваться через регекс. Если нормализация не реализована или неполна — тест либо хрупкий, либо тавтологичный.
-
-## Красные флаги при чтении теста
-
-- Регекс-ассерт в роли единственной проверки baseline-заявленного output.
-- Несколько фрагментарных ассертов (regex-match, substring-include) подряд по разным частям одного output без сравнения целого.
-- Отсутствие литерала-эталона в файле теста (нет inline-string, нет ссылки на snapshot-файл).
-- Нормализация-функция объявлена, но её результат используется только для фрагментарных ассертов, не для равенства целого.
-- DoD пункт «эталон зафиксирован» отмечен `[x]`, но в коде нет ни одного точного сравнения.
-- Утверждения в Result вида «N snapshot-тестов зелёные», когда в файле теста нет ни одного snapshot/equality-вызова.
-
-## Зелёные сигналы
-
-- Каждый baseline-сценарий завершается одним точным сравнением целого нормализованного output с литералом-эталоном.
-- Эталон прочитываем глазами: видно структуру и порядок полей; ревьюер может сказать, какое именно изменение уронит тест.
-- Нормализация описана и применяется ко всему output до сравнения.
-- При попытке вручную «сломать» один символ в эталоне или в исходнике — тест падает с понятной diff-разницей.
-
-## Что делать при обнаружении нарушения
-
-- `failed` с конкретным issue: какой пункт DoD заявил эталон, какой ассерт фактически реализован, почему ассерт не отвергает регрессии вне его покрытия.
-- Процитировать дословно: строку DoD с формулировкой эталона **и** строку теста с фактическим ассертом. Не пересказывать.
-- Не смягчать finding на основании того, что «тесты зелёные» или «количество кейсов соответствует» — проверка способа реализации ортогональна прогону и счётчику.
-
-## Когда проверка не применяется
-
-- DoD не содержит формулировок уровня эталона/snapshot/baseline/побайтного совпадения. Тест нацелен на проверку отдельной инвариантной фичи (наличие поля, формат id) — обычные ассерты допустимы.
-- В тикете явно зафиксировано, что эталон будет добавлен следующим тикетом, и текущая задача — только smoke-каркас. Такая декомпозиция должна быть явной в плане; молчаливое сведение baseline к smoke — нарушение.

package/src/skills/review-result/knowledge/dod-patterns.md

@@ -1,116 +0,0 @@
-# Паттерны DoD по типам тикетов
-
-Справочник типичных критериев готовности (Definition of Done) для разных типов задач. Помогает ревьюеру определить тип проверки и ожидания.
-
-## Паттерны по типу тикета
-
-### impl (реализация)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Файл `X` создан / изменён | `file_exists` | Проверить что файл не пустой, содержит реальный код |
-| Тесты проходят | `tests` | Запустить тесты, проверить покрытие |
-| Код проходит линтер | `compilation` | Запустить lint |
-| Реализована функция X | `text` | Проверить наличие функции, её сигнатуру и логику |
-| Тесты на маппинг/парсинг данных | `tests` + `text` | Проверить, что тестовые fixtures содержат **реальные** значения из runtime-источника (лог, конфиг, API), а не синтетические. Прочитать источник данных и сверить с fixtures. Если fixtures не соответствуют реальным данным — тесты тавтологичны |
-| Baseline / snapshot / эталон / regression-фиксация | `tests` + `structure` | Проверка способа реализации теста (точное сравнение нормализованного output с литералом-эталоном vs регекс/includes по подстроке). См. `knowledge/baseline-snapshot-validation.md` — обязательная загрузка при триггерных формулировках DoD. |
-| Документация обновлена | `text` | Проверить JSDoc / README / комментарии |
-
-### fix (исправление бага)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Баг исправлен | `tests` | Регрессионный тест покрывает сценарий бага |
-| Тесты не сломаны | `tests` | Все существующие тесты проходят |
-| Нет побочных эффектов | `text` | Минимальность изменений, не затронуты несвязанные файлы |
-
-### docs (документация)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Документ создан | `file_exists` | Файл существует и не пустой |
-| Структура соответствует шаблону | `structure` | Все обязательные секции присутствуют |
-| Файл самодостаточен | `text` | → Применить шаг 3.5 (проверка с позиции аудитории) |
-| Нет плейсхолдеров | `text` | Поиск `TODO`, `XXX`, `TBD`, `заменить` |
-
-### coach (улучшение скилов)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Файлы скила созданы | `file_exists` | workflows/, knowledge/, algorithms/ существуют |
-| SKILL.md обновлён | `text` | Таблицы загрузки, маршрутизация |
-| Нет ссылок на имена скилов | `text` | Поиск хардкода ролей — проверка изоляции |
-| README создан | `file_exists` + `structure` | Все обязательные секции |
-
-### rsh (исследование)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Отчёт создан | `file_exists` | Файл существует |
-| Источники указаны | `text` | Ссылки на источники, не голословные утверждения |
-| Выводы структурированы | `structure` | Секции, таблицы, приоритизация |
-
-### admin (административная)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Конфигурация обновлена | `file_exists` + `text` | Файл изменён, значения корректны |
-| Система работает | `compilation` | Проверить что конфиг валиден |
-
-## Универсальные проверки
-
-Применяются ко **всем** типам тикетов:
-
-| Проверка | Описание |
-|----------|----------|
-| Summary не пустой | Секция «Результат выполнения» содержит содержательное описание |
-| Изменённые файлы перечислены | Список файлов не пуст (для тикетов с артефактами) |
-| Файлы реально существуют | Все перечисленные файлы доступны через Read/Glob |
-| DoD ↔ Result согласованы | Каждый пункт DoD отражён в результате |
-
-### qa (тестирование / manual testing)
-
-| Типичный DoD | Тип проверки | На что обратить внимание |
-|--------------|-------------|-------------------------|
-| Сценарий X протестирован | `text` | Результат (PASS/FAIL/BLOCKER) задокументирован с evidence (a11y assertion + шаги) |
-| Найденные дефекты зафиксированы | `text` | Дефекты содержат шаги воспроизведения, ожидаемый/фактический результат |
-| Скриншоты приложены (если требуются в DoD) | `file_exists` + `visual` | Файлы существуют, **содержимое визуально проверено** — скриншот подтверждает заявление TC (шаг 3.7 review.md) |
-
-> **⚠️ КРИТИЧЕСКИ ВАЖНО — Правило оценки QA-тикетов:**
->
-> Для QA-тикетов обнаружение дефекта продукта — это **правильно выполненная работа тестировщика**, а НЕ ошибка выполнения тикета.
->
-> - Если тестировщик обнаружил, что функционал отсутствует или сломан, и **задокументировал это** (описал дефект, шаги воспроизведения, a11y assertion) → пункт DoD **выполнен**. Тестировщик не может починить продукт — его задача найти и зафиксировать проблему. Скриншоты от исполнителя не обязательны по умолчанию — только если явно требуются в DoD. Однако если TC содержит визуальный критерий (как объект выглядит пользователю) — ревьюер обязан применить шаг 4.7 review.md: найти скриншоты, открыть и визуально проверить, либо зафиксировать отсутствие визуального evidence как issue.
-> - FAIL на ревью QA-тикета допустим только если тестировщик **не выполнил свою работу**: не протестировал сценарий, не задокументировал результат, не приложил доказательства, пропустил сценарии без объяснения.
-> - Статус сценария BLOCKER/FAIL в матрице результатов ≠ FAIL ревью тикета. Это выявленный дефект = ценный результат работы.
-
-> **⚠️ КРИТИЧЕСКИ ВАЖНО — Подмена ручной проверки запуском автотестов:**
->
-> Если QA-тикет содержит DoD «проверены визуально», «UI протестирован», «рендеринг проверен» (или аналог, требующий реального host-окружения), а evidence в результате — assertion из unit/integration-тест файлов разработки (`.test.ts`, `.test.js`), запуск `mocha`/`jest`/`vitest`/любого test runner'а — это **fail ревью** независимо от того, сколько тестов прошло.
->
-> **Признаки подмены:**
-> - В Evidence для каждого TC указан assertion вида `assert.strictEqual(icon.id, ...)` со ссылкой на файл `*.test.*`
-> - В «Протоколе выполнения» — команда запуска test runner вместо MCP-вызовов desktop/browser-инструмента
-> - В заметках формулировка типа «эквивалентно визуальной проверке, так как объект X создаётся теми же конструкторами»
-> - Отсутствуют MCP snapshot/screenshot из реального host-окружения, в котором продукт исполняется конечным пользователем
->
-> **Почему это fail:** unit-тесты, на которые ссылается evidence, **уже были зелёными** до создания QA-тикета (они прошли в задаче реализации). Их повторный запуск не подтверждает работоспособность в реальной среде — он подтверждает только то, что уже было известно. Эквивалентность «конструктор объекта в unit-тесте = отрендеренный объект в реальном UI» ложная: unit-тест не воспроизводит host runtime, интеграцию с системой, accessibility tree, реальный пользовательский ввод.
->
-> **Правильное поведение тестировщика при недоступности host-окружения:** BLOCKED с обоснованной причиной + создание HUMAN-тикета, если сценарий критический. См. `manual-testing/algorithms/blocked-tool-strategy.md`. Ревьюер обязан принимать BLOCKED как валидный результат и отклонять подмену.
->
-> **Регресс между итерациями ревью:** если предыдущая итерация ревью корректно отклонила evidence как «code review без реальных assertions из запущенного расширения», а следующая итерация принимает **то же самое** evidence с переформулированным обоснованием — это сигнал, что ревьюер поддался на риторику «обоснования недоступности» вместо проверки фактов. Перечитай предыдущее ревью: если оно отклонило по той же причине — текущее evidence должно содержать **новый тип данных** (MCP snapshot, скриншот из host, лог реального запуска), а не переформулировку старого.
-
-## Специальные паттерны
-
-### Self-Modified DoD (`[x]` + дискламер «НЕ ПРОЙДЕН»)
-
-**Признак:** пункт DoD помечен `[x]`, но рядом написано «НЕ ПРОЙДЕН», «FAIL», «фактически: X».
-
-**Правило:** `[x]` + «НЕ ПРОЙДЕН» = структурный дефект артефакта. Тестировщик перепутал «проверен» с «выполнен».
-
-**Действие ревьюера:**
-- Зафиксировать как issue: «DoD п.N: помечен `[x]`, но фактически не выполнен — ожидалось Y, получено Z»
-- Общий вердикт определяется по фактическому результату (Z), а не по `[x]`
-- Если фактический результат соответствует ожиданиям задачи (например, задача — зафиксировать состояние, а не достичь цели) → passed, но issue фиксируется как LOW
-
-<!-- РАСШИРЕНИЕ: добавляй новые паттерны DoD по типам тикетов ниже -->

package/src/skills/review-result/knowledge/test-hygiene.md

@@ -1,44 +0,0 @@
-# Проверка изоляции тестов на ревью
-
-Когда DoD тикета требует создать/изменить автотест, ревьюер **отдельно** проверяет, что тест не пишет артефакты в рабочий репозиторий или в общие системные пути. Это не дублирует обычный «тесты проходят» — проверка изоляции ортогональна результату прогона (зелёный тест всё равно может быть токсичным).
-
-## Зачем ревьюеру проверять это отдельно
-
-Тест, который проходит в чистом прогоне, но пишет в рабочий репозиторий, создаёт отложенные инциденты:
-- в CI / на второй машине / при параллельном запуске тесты ложно падают или ложно проходят;
-- при прерывании (Ctrl+C, таймаут) оставленный state подхватывается следующим прогоном как валидный;
-- затираются файлы, нужные параллельным агентам/пайплайну;
-- ложно срабатывают механические проверки (verify-artifacts, git-snapshot).
-
-Поэтому «зелёный прогон» — необходимый, но не достаточный сигнал. Нужна **отдельная** проверка изоляции.
-
-## Что читать
-
-1. Файл(ы) теста, затронутые тикетом.
-2. Соседние test-файлы в той же директории — какой паттерн изоляции уже принят в проекте.
-
-## Красные флаги при чтении теста
-
-- Путь к тест-артефакту строится от корня репозитория или CWD (любая конструкция «директория исходника + подъём к корню», «текущий рабочий каталог», «заранее заданный projectRoot») **без** префикса стандартного системного tmp-корня языка.
-- `cleanup`-функция удаляет конкретный файл, а не весь tmp-корень. При прерывании до её вызова файл останется в рабочем репозитории.
-- Cleanup — в теле test-функции, а не в teardown/after-hook. Падение assertion до cleanup-вызова = утечка state.
-- Тест модифицирует реальный файл в config-, data-, state-, cache- или иных рабочих каталогах проекта внутри корня репозитория.
-- Глобальные константы теста указывают на рабочий репозиторий и используются более чем в одном тест-кейсе (shared mutable state).
-
-## Зелёные сигналы
-
-- Корень артефактов создаётся через стандартную tmp-функцию стандартной библиотеки языка (исполнитель выбирает конкретную по языку проекта).
-- Cleanup удаляет **весь корень** рекурсивно и идемпотентен (можно вызвать повторно без ошибки).
-- Cleanup в teardown/after-hook, гарантированно выполняется при любом исходе теста.
-- Каждый тест получает свой свежий корень — нет разделяемого изменяемого состояния между тестами.
-
-## Что делать при обнаружении нарушения
-
-- Если нарушена изоляция — `failed` с конкретным issue: какая строка файла указывает на реальный каталог проекта, почему cleanup не защищает от прерывания.
-- Не смягчай finding на основании того, что тест «проходит» — проверка изоляции ортогональна прогону.
-- В issue — процитировать фрагмент теста дословно (путь до корня проекта, функция очистки), а не пересказать.
-
-## Когда проверка не применяется
-
-- Тикет явно просит тест-генератор, который коммитит файлы в репозиторий как артефакт. В этом случае в DoD должно быть явное обоснование.
-- Тест read-only: не создаёт и не модифицирует файлы (только reads).