workflow-ai 1.0.62 → 1.0.64

package/src/skills/create-plan/knowledge/plan-completeness.md

@@ -0,0 +1,67 @@
+# Полнота плана: чеклист для самопроверки
+
+План — это **единственный источник правды** для исполнителей. Если данных нет в плане, их нет у агентов. Исполнители **не имеют доступа** к исходному ТЗ, переписке, устным договорённостям.
+
+## Принцип: план = самодостаточный документ
+
+> Агент-исполнитель, получив тикет из плана, должен иметь **всё необходимое** для реализации без обращения к другим документам.
+
+## Чеклист извлечения данных из ТЗ
+
+При создании плана на основе внешнего документа (ТЗ, спецификация, RFC, задача от стейкхолдера) — **извлеки и перенеси в план ВСЕ конкретные данные**:
+
+### Обязательно переносить
+
+| Категория | Примеры | Куда в плане |
+|-----------|---------|-------------|
+| **Credentials / ключи / токены** | API keys, secret keys, measurement IDs, tokens | Секция "Справочные данные" |
+| **URLs и endpoints** | API endpoints, формы, debug URLs, webhook URLs | Секция "Справочные данные" |
+| **Конфигурационные значения** | Константы, интервалы, лимиты, имена alarm'ов, storage keys | Секция "Справочные данные" |
+| **Permissions / манифесты** | JSON-фрагменты, YAML-конфигурации, строки для конфигов | Секция "Справочные данные" |
+| **Карты файлов** | Какой код → в какой файл → при каком триггере → с какими параметрами | Секция "Справочные данные" (таблица) |
+| **Параметры событий/запросов** | Имена, типы, описания, допустимые значения каждого параметра | Секция "Справочные данные" (таблица) |
+| **Схемы данных** | Storage keys, типы полей, форматы, валидация | Секция "Справочные данные" |
+| **Бизнес-логика и edge cases** | Порядок операций, условия (ДО/ПОСЛЕ), only-if логика | Описание задач |
+| **Troubleshooting** | Типичные ошибки, причины, решения | Задача тестирования |
+| **Внешние ресурсы** | Описания форм, структура опросов, тексты | Секция "Справочные данные" |
+
+### НЕ переносить (оставить в scope исключений)
+
+- Инструкции по настройке внешних сервисов (если это ручная работа вне scope)
+- Общие описания подходов (если они очевидны из контекста)
+- Дублирование одних и тех же данных в нескольких местах плана
+
+## Красные флаги неполного плана
+
+Если в плане встречаются следующие формулировки — это сигнал, что данные не перенесены:
+
+| Формулировка в плане | Проблема |
+|---------------------|----------|
+| "URL из ТЗ" / "URL уже создан" | URL не указан — исполнитель его не знает |
+| "см. документацию" / "описано в спецификации" | Исполнитель не имеет доступа к спецификации |
+| "настроить credentials" (без значений) | Какие credentials? Где взять? |
+| "добавить параметры" (без списка) | Какие параметры? Какие типы? |
+| "интегрировать событие" (без деталей) | Какое имя? Какие params? В какой файл? При каком триггере? |
+| "обновить конфиг" (без конкретного JSON/YAML) | Что именно добавить? |
+
+## Секция "Справочные данные" в плане
+
+Каждый план, основанный на внешнем ТЗ, **должен содержать** секцию "Справочные данные" между "Контекст" и "Scope". Эта секция — справочник для всех задач плана.
+
+Структура секции:
+```markdown
+## Справочные данные
+
+### {Подсекция по категории}
+{Таблицы, code blocks, конкретные значения}
+```
+
+Подсекции определяются содержимым ТЗ. Типичные:
+- Credentials / API keys
+- URLs и endpoints
+- Карта событий / API / маршрутов
+- Схема данных (storage, DB, state)
+- Конфигурации (manifests, permissions, configs)
+- Константы и интервалы
+
+<!-- РАСШИРЕНИЕ: добавляй новые категории данных для извлечения ниже -->

package/src/skills/create-plan/knowledge/plan-lifecycle.md

@@ -0,0 +1,33 @@
+# Жизненный цикл статусов плана
+
+Каждый план проходит через определённые статусы. Скил `create-plan` должен знать их, чтобы корректно устанавливать начальный статус и не использовать невалидные значения.
+
+## Статусы
+
+```
+draft → approved → active → completed → archived
+```
+
+| Статус | Описание | Кто устанавливает |
+|--------|----------|-------------------|
+| `draft` | Черновик. План создан, но ещё не утверждён стейкхолдером | Скил `create-plan` при создании |
+| `approved` | Утверждён стейкхолдером. Готов к декомпозиции на тикеты | Стейкхолдер после ревью плана |
+| `active` | В работе. Тикеты созданы и прошли машинную проверку атомарности | Pipeline: стадия `verify-atomicity` при `status: passed` (не декомпозитор) |
+| `completed` | Все тикеты плана завершены | Pipeline после завершения всех тикетов |
+| `archived` | Архивирован. Перемещён в `plans/archive/` | Команда `workflow.archivePlan` |
+
+## Правила для скила create-plan
+
+1. **Всегда создавай план со статусом `draft`** — план должен пройти ревью и утверждение стейкхолдером
+2. **Не ставь `approved` автоматически** — утверждение делает стейкхолдер
+3. **Не ставь `active`** — этот статус устанавливается после декомпозиции
+
+## Связь с pipeline
+
+Скрипт `check-plan-decomposed.js` сканирует планы в `plans/current/` и декомпозирует **только** планы со статусом `approved`. Планы в `draft` пропускаются.
+
+Это значит: пока стейкхолдер не утвердит план (`status: approved`), pipeline **не будет** его декомпозировать.
+
+**Переход `approved → active`** выполняется стадией `verify-atomicity` пайплайна (`src/skills/decompose-plan/scripts/verify-atomicity.js`), **не** декомпозитором и **не** скилом `create-plan`. Условие перехода: все тикеты плана прошли машинную проверку атомарности (`status: passed`). Если атомарность упала и счётчик попыток `atomicity_check_attempts` достиг `max: 3` — план остаётся в `approved`, в работу не уходит; стадия `increment-atomicity-counter` передаёт управление в `check-conditions` без активации плана.
+
+<!-- РАСШИРЕНИЕ: добавляй новые статусы и правила ниже -->

package/src/skills/create-plan/knowledge/task-verification-pairs.md

@@ -0,0 +1,151 @@
+# Парные задачи верификации
+
+Каждая задача плана, которая изменяет код продукта, должна сопровождаться задачами верификации. Набор парных задач зависит от характера изменения.
+
+## Правило
+
+Если задача плана предполагает **изменение кода продукта** (исправление, доработка, новая функциональность), определи для неё необходимые задачи верификации:
+
+1. **Актуализация автотестов** (обязательна всегда) — добавление или обновление unit/integration-тестов, покрывающих изменённое поведение
+2. **Ручная проверка** (если изменение наблюдаемо пользователем) — тестировщик вручную проверяет исправление по шагам воспроизведения или acceptance criteria
+
+## Определение набора парных задач
+
+Для каждой задачи, изменяющей код, архитектор определяет какие верификационные задачи нужны, задавая два вопроса:
+
+1. **Может ли пользователь заметить изменение?** (видимый эффект в UI, поведении, выводе) → если да, нужна **ручная проверка**
+2. **Можно ли покрыть изменение автоматическим тестом?** (есть вход/выход, поведение формализуемо) → если да, нужна **актуализация автотестов**
+
+| Ответы на вопросы | Автотесты | Ручная проверка |
+|---|---|---|
+| Пользователь заметит + можно покрыть тестом | Да | Да |
+| Пользователь заметит + нельзя покрыть тестом (чисто визуальное) | Нет | Да |
+| Пользователь не заметит + можно покрыть тестом | Да | Нет |
+| Пользователь не заметит + нельзя покрыть тестом | Обосновать в плане, почему верификация не нужна |
+
+Если не очевидно — включай обе задачи (лучше проверить лишний раз).
+
+## Структура группы задач
+
+```
+# Полная группа (изменение с наблюдаемым эффектом):
+Задача N:   Изменение кода (исполнитель: agent)
+Задача N+1: Ручная проверка задачи N (исполнитель: agent, зависимость: задача N)
+Задача N+2: Актуализация автотестов для задачи N (исполнитель: agent, зависимость: задача N)
+
+# Сокращённая группа (внутреннее изменение без UI-эффекта):
+Задача N:   Изменение кода (исполнитель: agent)
+Задача N+1: Актуализация автотестов для задачи N (исполнитель: agent, зависимость: задача N)
+```
+
+## Когда применять
+
+- **Применяется:** задача изменяет исходный код продукта (логику, UI, стили, конфигурацию продукта)
+- **НЕ применяется:** задача изменяет только документацию, тестовые утилиты (mock, test helpers), workflow-артефакты, или является чисто исследовательской
+
+## Исключения
+
+Объединение ручных проверок нескольких задач в одну сводную задачу **по умолчанию запрещено**. Каждая задача изменения кода с наблюдаемым эффектом получает **свою** парную задачу ручной проверки рядом — не в конце плана.
+
+**Когда сводная задача допустима** (все условия одновременно):
+1. Объединяемые задачи изменяют **один и тот же UI-объект** (одна view, один компонент, один экран) — а не несколько независимых областей продукта
+2. Каждая отдельная проверка тривиальна (1-2 шага) — иначе сводный сценарий распухает и теряет фокус
+3. В плане **явно перечислены** ID объединяемых задач и обоснование, почему раздельная проверка избыточна
+
+**Антипаттерн:** одна задача «Ручная проверка задач 1-7» в конце плана, охватывающая разные UI-области. Это не сводная проверка — это пропуск парных задач. Декомпозитор не сможет создать корректные парные тикеты, верификация теряет связь с исходной задачей, ревью затрудняется.
+
+## Self-check перед сохранением плана
+
+Перед записью файла плана пройди по списку задач и для **каждой** задачи, изменяющей код продукта с наблюдаемым эффектом, ответь:
+
+1. Есть ли рядом с этой задачей парная задача ручной проверки именно для неё?
+2. Если ручная проверка вынесена в сводную задачу — выполнены ли все три условия из секции «Исключения»?
+3. Если не выполнены — разбей сводную задачу на парные и помести каждую рядом с её основной задачей.
+
+Если задача изменения кода найдена без парной ручной проверки и без обоснованного исключения — план **не готов к сохранению**.
+
+## Data assertions в QA-задачах
+
+Каждый тест-кейс в QA-задаче плана должен содержать **ожидаемое значение**, а не только ожидаемое наличие элемента.
+
+### Правило
+
+Вместо «компонент X находится в состоянии Y» → «компонент X показывает конкретное значение `Z`».
+
+### Критерий применения
+
+Задай вопрос: **«Может ли значение измениться между запусками или зависит от входных данных?»**
+
+| Ответ | Тип данных | Примеры | Нужен data assertion |
+|-------|-----------|---------|----------------------|
+| Да | Динамические: счётчики, имена, время, параметризованные статусы | «Прогресс: 3 из 5» | ✅ Да |
+| Нет | Статические: иконки, фиксированные подписи, кнопки | «Кнопка «Открыть» видна» | ❌ Нет |
+
+### Примеры переформулировки
+
+| Слабое (только наличие) | Сильное (data assertion) |
+|-------------------------|--------------------------|
+| «Статус-строка показывает Running» | «Статус-строка показывает `Running \| <имя текущего шага>`» |
+| «История содержит записи» | «История содержит N записей, каждая с временем > 0s» |
+
+### Ограничения
+
+- Не требуй data assertion для непредсказуемых значений (случайные ID, временны́е метки с миллисекундной точностью) — в таких случаях проверяй формат: «timestamp соответствует паттерну `ISO 8601`»
+- Одна проверка значения на ключевой динамический элемент достаточна — не раздувай тест-кейс
+
+<!-- РАСШИРЕНИЕ: добавляй уточнения и исключения ниже -->
+
+## Entry points и config variations в QA-задачах
+
+При создании QA-задачи для функции/команды необходимо перечислить ВСЕ способы её вызова и все конфигурации, влияющие на поведение.
+
+### Правило
+
+Для каждой тестируемой функции/команды выполни 4 шага:
+
+1. **Определи все entry points** — изучи проектный манифест (конфиг, декларацию расширения/плагина) и код, чтобы найти ВСЕ точки входа (меню, сочетания клавиш, inline UI, контекстное меню, программный API). Каждый entry point — потенциально отдельный TC.
+
+2. **Покрой каждый entry point TC-ом** — не ограничивайся «основным» способом запуска. Функция считается протестированной только если каждый задекларированный entry point проверен отдельно.
+
+3. **Определи config variations** — найди все конфигурационные параметры, влияющие на поведение функции: допустимые значения, граничные значения, отсутствие опциональных параметров. Каждая значимая вариация — отдельный TC или параметризованный шаг.
+
+4. **Добавь persistence TC для stateful-функций** — если функция сохраняет данные (история, кэш, настройки), включи TC: данные сохраняются после перезапуска приложения и корректно накапливаются при повторных запусках.
+
+### Критерий применения
+
+Задай вопрос: **«Может ли пользователь вызвать эту функцию более чем одним способом?»**
+
+| Ответ | Действие |
+|-------|----------|
+| Да | Перечислить все entry points, добавить TC на каждый |
+| Нет | Один TC на единственный entry point |
+
+И: **«Зависит ли поведение от конфигурации или сохраняет ли функция данные между сессиями?»**
+
+| Ответ | Действие |
+|-------|----------|
+| Да, конфиг влияет | TC для каждого значения/варианта, влияющего на поведение |
+| Да, данные сохраняются | TC на persistence и накопление |
+| Нет | Конфигурационные и persistence TC не нужны |
+
+### Пример структуры анализа entry points (абстрактный)
+
+```
+Функция: «Запустить проверку»
+
+Entry points (из манифеста и кода):
+  [ ] Главное меню → «App: Run Check»
+  [ ] Клавиатурное сочетание → Ctrl+Shift+R
+  [ ] Контекстное меню → правый клик → «Run Check»
+  [ ] Inline-кнопка → иконка ▶ в строке элемента
+  [ ] Программный API → app.runCheck()
+
+Config variations:
+  [ ] mode = fast (по умолчанию)
+  [ ] mode = full
+  [ ] mode отсутствует (edge case)
+
+Persistence (если stateful):
+  [ ] История запусков сохраняется после перезапуска
+  [ ] Накопление: N запусков → N записей в истории
+```

package/src/skills/create-plan/scripts/validate-completeness.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+/**
+ * validate-completeness.js — валидация полноты плана по чеклисту из plan-completeness.md
+ *
+ * Использование:
+ *   node validate-completeness.js <path-to-plan>
+ *
+ * Проверяет:
+ * - Обязательные поля frontmatter (id, title, status, author, created_at)
+ * - Обязательные секции (# Цель, ## Контекст, ## Справочные данные, ## Scope, ## Высокоуровневые задачи, ## Риски, ## Критерии успеха)
+ * - Красные флаги (отсылки вместо содержания, пустые секции)
+ *
+ * Вывод: JSON {errors, warnings, valid} через ---RESULT---
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { findProjectRoot } from 'workflow-ai/lib/find-root.mjs';
+import { printResult } from 'workflow-ai/lib/utils.mjs';
+
+const REQUIRED_FRONTMATTER_FIELDS = ['id', 'title', 'status', 'author', 'created_at'];
+
+const REQUIRED_SECTIONS = [
+  '# Цель',
+  '## Контекст',
+  '## Справочные данные',
+  '## Scope',
+  '## Высокоуровневые задачи',
+  '## Риски',
+  '## Критерии успеха'
+];
+
+const RED_FLAG_PATTERNS = [
+  { pattern: /см\.\s*ТЗ|по ссылке|см\.\s*документацию|описано в спецификации/gi, message: 'Отсылка к внешнему документу вместо содержания' },
+  { pattern: /URL[а-яё]*\s*(уже создан|создан|получен)|credentials\s*(настроены|получены|готовы)/gi, message: 'Значение не указано (только упоминание)' },
+  { pattern: /^#\s*.+\n\n+$/gm, message: 'Пустая секция (только заголовок без содержания)', isEmptySection: true }
+];
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.error('Ошибка: не указан путь к файлу плана');
+    console.error('Использование: node validate-completeness.js <path-to-plan>');
+    process.exit(1);
+  }
+  return args[0];
+}
+
+function parseFrontmatter(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    return { raw: null, data: null };
+  }
+
+  const fmContent = fmMatch[1];
+  const data = {};
+
+  const lines = fmContent.split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+
+    data[key] = value;
+  }
+
+  return { raw: fmMatch[0], data };
+}
+
+function checkFrontmatter(fm) {
+  const errors = [];
+
+  if (!fm || !fm.data) {
+    errors.push({ field: 'frontmatter', message: 'Frontmatter отсутствует' });
+    return errors;
+  }
+
+  for (const field of REQUIRED_FRONTMATTER_FIELDS) {
+    if (!fm.data[field]) {
+      errors.push({ field, message: `Обязательное поле "${field}" отсутствует` });
+    }
+  }
+
+  return errors;
+}
+
+function checkSections(content) {
+  const errors = [];
+  const lines = content.split('\n');
+
+  for (const section of REQUIRED_SECTIONS) {
+    const sectionPattern = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(sectionPattern, 'i');
+
+    if (!regex.test(content)) {
+      errors.push({ section, message: `Секция "${section}" отсутствует` });
+    }
+  }
+
+  return errors;
+}
+
+function checkRedFlags(content) {
+  const warnings = [];
+  const lines = content.split('\n');
+
+  for (const { pattern, message, isEmptySection } of RED_FLAG_PATTERNS) {
+    if (isEmptySection) {
+      const matches = content.match(/^#+\s+.+$/gm);
+      if (matches) {
+        for (const heading of matches) {
+          const headingLineNum = content.split('\n').findIndex(l => l.trim() === heading.trim());
+          if (headingLineNum !== -1) {
+            const nextLine = lines[headingLineNum + 1];
+            if (!nextLine || !nextLine.trim()) {
+              warnings.push({ pattern: heading, message: `Пустая секция: ${heading}` });
+            }
+          }
+        }
+      }
+    } else {
+      const matches = content.match(pattern);
+      if (matches) {
+        for (const match of matches) {
+          warnings.push({ pattern: match.slice(0, 50), message });
+        }
+      }
+    }
+  }
+
+  return warnings;
+}
+
+function validatePlan(planPath) {
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(planPath)) {
+    errors.push({ file: planPath, message: 'Файл не существует' });
+    return { errors, warnings, valid: false };
+  }
+
+  const content = fs.readFileSync(planPath, 'utf-8');
+
+  const fmErrors = checkFrontmatter(parseFrontmatter(content));
+  errors.push(...fmErrors);
+
+  const sectionErrors = checkSections(content);
+  errors.push(...sectionErrors);
+
+  const redFlagWarnings = checkRedFlags(content);
+  warnings.push(...redFlagWarnings);
+
+  const valid = errors.length === 0;
+
+  return { errors, warnings, valid };
+}
+
+function main() {
+  const planPath = parseArgs();
+
+  const absolutePath = path.isAbsolute(planPath)
+    ? planPath
+    : path.resolve(process.cwd(), planPath);
+
+  const result = validatePlan(absolutePath);
+
+  console.log('---RESULT---');
+  console.log(JSON.stringify(result, null, 2));
+  console.log('---RESULT---');
+}
+
+main();

package/src/skills/create-plan/tests/cases/TC-CREATE-PLAN-001/current/claude-sonnet/trial-1.md

@@ -0,0 +1,5 @@
+# TRIAL ERRORED
+
+agent: claude-sonnet
+trial: 1
+error: Stage "TC-CREATE-PLAN-001-claude-sonnet-trial-1" timed out after 1200s

package/src/skills/create-plan/tests/cases/TC-CREATE-PLAN-001/current/claude-sonnet/trial-2.md

@@ -0,0 +1,39 @@
+`valid: true`, errors пусты. Предупреждения о "пустых секциях" — артефакт валидатора, который проверяет следующую строку после заголовка: в markdown принято оставлять пустую строку после `##`. Эти предупреждения некритичны (они есть в любом корректно отформатированном Markdown-файле).
+
+Финальный план сохранён:
+
+`.workflow/plans/current/PLAN-001.md`
+
+---
+
+## PLAN-001: Добавить тёмную тему в приложение
+
+**Статус:** `draft`
+
+### Что сделано
+
+**Цель (SMART):** реализовать переключение light/dark-темы с сохранением выбора в `localStorage` без перезагрузки страницы, подтверждённое ручной проверкой и автотестами.
+
+**Справочные данные зафиксированы:** ключ localStorage — `app-theme`, атрибут — `data-theme`, дефолт — `light`, файл токенов — `src/styles/tokens.css`.
+
+**13 задач** с парными задачами верификации:
+
+| Задача | Тип |
+|--------|-----|
+| 1. Аудировать цветовую схему | Исследование |
+| 2. Создать CSS-токены light/dark | Реализация |
+| 2.1. Ручная проверка токенов | Верификация |
+| 3. Заменить хардкод-цвета на CSS-переменные | Реализация |
+| 3.1. Ручная проверка регрессии светлой темы | Верификация |
+| 3.2. Актуализировать автотесты | Верификация |
+| 4. Создать компонент ThemeToggle | Реализация |
+| 4.1. Ручная проверка переключателя | Верификация |
+| 4.2. Автотесты ThemeToggle | Верификация |
+| 5. Логика переключения + localStorage | Реализация |
+| 5.1–5.2. Ручная проверка + автотесты | Верификация |
+| 6. Инициализация темы при старте | Реализация |
+| 6.1–6.2. Ручная проверка + автотесты | Верификация |
+| 7. Совместимость иконок/изображений | Реализация |
+| 7.1. Ручная проверка иконок | Верификация |
+
+**4 риска** оценены по матрице (MEDIUM×2, HIGH×1, MEDIUM×1) с митигацией.

package/src/skills/create-plan/tests/cases/TC-CREATE-PLAN-001/current/claude-sonnet/trial-3.md

@@ -0,0 +1,35 @@
+Валидация прошла: `valid: true`. Предупреждения о "пустых секциях" — ложные срабатывания скрипта (он проверяет только следующую строку после заголовка, а стандартный Markdown предполагает пустую строку между заголовком и контентом). Все секции плана содержат содержательный текст.
+
+---
+
+План создан: **`.workflow/plans/current/PLAN-001.md`**
+
+## Что сделано
+
+**SMART-цель:** к 2026-04-27 пользователь может переключать light/dark тему через кнопку в Header, выбор сохраняется между сессиями, все основные компоненты корректно стилизованы.
+
+**Справочные данные** содержат:
+- Полные CSS design tokens (14 переменных для обеих тем)
+- localStorage-схему (ключ `theme`, допустимые значения)
+- Алгоритм инициализации с fallback на `prefers-color-scheme`
+- Таблицу иконок и aria-label для ThemeToggle
+
+**15 задач** — атомарные, одно действие на задачу:
+
+| Задачи | Тип |
+|--------|-----|
+| 1 | Аудит хардкодных цветов (исследование) |
+| 2 | CSS custom properties → global.css |
+| 3–4 | Ручная проверка + автотесты для задачи 2 |
+| 5 | ThemeContext с `data-theme` на `<html>` |
+| 6–7 | Ручная проверка + автотесты для задачи 5 |
+| 8 | Сохранение темы в localStorage |
+| 9–10 | Ручная проверка + автотесты для задачи 8 |
+| 11 | Компонент ThemeToggle |
+| 12 | Интеграция ThemeToggle в Header |
+| 13 | Сводная ручная проверка задач 11+12 |
+| 14–15 | Автотесты для задач 11 и 12 |
+
+**5 рисков** с митигацией (2× HIGH: хардкодные цвета и CSS-in-JS стек).
+
+**Статус:** `draft` — ожидает утверждения стейкхолдером.