forgeplan validate

forgeplan validate запускает валидатор схемы для одного артефакта (или для всех) и сообщает о каждом нарушении правил, зарегистрированных для данного типа и глубины. Правила MUST являются блокирующими - они предотвращают переключение жизненного цикла в состояние active командой forgeplan activate. Правила SHOULD - это предупреждения, которые формируют качество, но не блокируют гейт. Валидатор учитывает глубину: тактический PRD имеет менее строгий набор правил, чем глубокий PRD, поэтому вы никогда не будете оштрафованы за выбор правильной глубины.

Когда использовать

Сразу после создания артефакта из шаблона (чтобы обнаружить пустые разделы MUST, пока вы не забыли).
Непосредственно перед forgeplan activate - активация всё равно откажется выполняться при ошибках MUST.
В CI с --ci на ветке документации / артефактов, чтобы блокировать слияния, которые вводят заглушки PRD.
Во время /audit для запуска --adversarial и выявления результатов состязательной ревью.

Когда НЕ использовать

Для Note или только что маршрутизированной тактической задачи - пока нечего валидировать.
В качестве замены человеческого ревью - валидатор проверяет структуру, а не качество рассуждений.

Использование

forgeplan validate [OPTIONS] [ID]

Аргументы

  [ID]  ID артефакта (валидирует все, если пропущено)

Опции

      --json         Вывод в формате JSON для машинной обработки
      --adversarial  Запуск состязательной ревью ("адвоката дьявола")
      --ci           Режим CI: код выхода 1, если какое-либо правило MUST не выполнено
  -h, --help         Вывести справку
  -V, --version      Вывести версию

Примеры

Валидация одного PRD перед активацией

forgeplan validate PRD-001

Выводит таблицу результатов MUST и SHOULD. Типичный вывод:

PRD-001 - Auth System
  MUST  Missing section: Problem
  MUST  FR list empty
  SHOULD density < 50 words in Goals

Исправьте два MUST, запустите снова, затем forgeplan activate PRD-001.

Валидация всего и сбой CI при ошибках MUST

forgeplan validate --ci

Код выхода 1, если какой-либо артефакт имеет хотя бы одно нарушение MUST. Используйте это в GitHub Action перед слиянием на ветках, затрагивающих .forgeplan/.

Состязательная ревью для глубокого решения

forgeplan validate ADR-005 --adversarial

Запускает проход “адвоката дьявола” (вдохновлённый BMAD). Ревьюеры ДОЛЖНЫ находить проблемы - если состязательный проход сообщает о нуле проблем, запустите его снова с более сильной моделью или эскалируйте до /audit.

Машиночитаемый вывод

forgeplan validate PRD-001 --json | jq '.must_violations'

Интерпретация вывода

MUST - блокирующее. Активация будет отклонена. Исправьте перед PR.
SHOULD - предупреждение. Отслеживайте их, но они не блокируют гейт.
Применяются псевдонимы правил (## Motivation == ## Problem, ## Out of Scope == ## Non-Goals) - полный список см. в руководстве по методологии.
Код выхода 0 = чисто, 1 = сбой MUST (только в режиме --ci).

Режим CI (`--ci`)

Добавленный в спринте 11.3 как часть работы по обеспечению целостности методологии (PRD-034 / PRD-043), forgeplan validate --ci превращает валидатор в жёсткий гейт конвейера. В режиме CI команда завершается с кодом 1, если любое правило MUST не выполняется для active или stale артефакта - черновики намеренно исключены, чтобы вас не блокировали заглушки в процессе работы, которые ещё не были активированы.

Поведение

forgeplan validate --ci → сканирует каждый артефакт, фильтрует по статусу в {active, stale}, запускает набор правил MUST, учитывающий глубину, и завершается с кодом 1, если какой-либо артефакт имеет хотя бы одно нарушение MUST.
Черновики по-прежнему валидируются для человека (выводятся предупреждения), но не вызывают ненулевой выход. Предполагается, что черновик - это явно состояние WIP, а активация - это реальная точка обязательства.
Вывод по умолчанию остаётся человекочитаемым; используйте в паре с --json, если вы хотите постобработать в CI (например, аннотировать PR с результатами).

Фрагмент GitHub Actions

Добавьте это в .github/workflows/ci.yml рядом с вашим шагом forgeplan health --ci:

- name: Forgeplan validate gate
  run: |
    forgeplan scan-import
    forgeplan validate --ci

Если это завершается с кодом 1, PR будет заблокирован. Исправьте нарушения MUST (или заместите / отмените проблемный артефакт, если он действительно заброшен) перед повторным запуском.

Используйте в паре с forgeplan health --ci для двухуровневого гейта: validate обнаруживает сбои структурной полноты, health обнаруживает методологический долг (слепые пятна, сироты (артефакты без связей), просроченные). Вместе они предотвращают попадание в dev как “у этого PRD нет раздела Problem”, так и “у этого PRD нет доказательств”.

Как это вписывается в рабочий процесс

route → new → validate → reason (ADI) → code → evidence → review → activate
                 ↑                                           ↑
                 └───────── повторный запуск после каждого редактирования ──────────┘

validate - это гейт “заполнил ли я форму”. review - это гейт “готов ли я к выпуску” поверх него. activate откажется запускаться, если validate не пройдёт.

См. также

forgeplan review - добавляет чек-лист жизненного цикла поверх валидации
forgeplan activate - гейт, который питает validate
forgeplan score - качество за пределами структурных правил
Гейты качества - философия MUST/SHOULD/состязательной ревью
Обзор CLI