Перейти к основному содержимому

ADR 0095 — Gate necessidade-validada закрывается отдельным подтверждением человека, а не самопроверкой Criativo

  • Статус: Принят
  • Дата: 2026-08-17
  • Контекст: аудит fluxo.yml × код (Волна 6/последняя, пункт B2, docs/explanation/auditoria-fluxo-vs-codigo.md, раздел D)
  • Расширяет: ADR 0054 (владелец дизайна docs/gates.yml)
  • Ссылки: docs/explanation/modelo-de-time.md — антипаттерн, который мотивирует это решение, уже был зафиксирован там как ожидающий

Контекст​

docs/fluxo.yml (роль criativo) объявляет gate_saida: { id: necessidade-validada, status: proposto } со времён ADR 0085 (v3 потока). Gate никогда по-настоящему не существовал: нет записи в docs/gates.yml и нет никакого механизма в коде. docs/explanation/modelo-de-time.md уже фиксировал причину его застоя в списке «Предложения, ожидающие решения»:

Антипаттерн Criativo как реальной проверки gate necessidade-validada.

Антипаттерн таков: Criativo — это агент, который ПРОИЗВОДИТ бизнес-потребность (через emit_artifact/confirm_readiness, сведённую в artifact.product_brief). Если бы сама модель решала, когда эта потребность «проверена» — например, выводя готовность из беседы, — gate был бы самооценкой автора, а не настоящими воротами. Gate без независимой проверки ничего не измеряет; он лишь притворяется, что измеряет.

Что уже существует и не является этим​

  • confirm_readiness/RN-142 — структурный нижний порог: отказывает, когда в сессии было зафиксировано НОЛЬ бизнес-правил (CriativoServer, handle_call(:confirm_readiness, ...)). Это проверка ФОРМЫ (есть ли содержимое?), а не СУТИ (верно ли содержимое?). Продолжает действовать ровно как есть — этот ADR его не трогает.
  • AcceptHandoffUseCase — принятие handoff со стороны PO структурно: переводит handoff в accepted и включает целевого агента. Оно не судит о СОДЕРЖИМОМ того, что принимает; это тот же общий механизм, который использует каждый handoff (QA принимает от dev, Dev Lead принимает от Arquiteto и т. д.). Считать это принятие «проверкой потребности» означало бы молча переиспользовать событие, означающее другое.

Ни то, ни другое не является gate по существу. Не хватает третьего механизма, намеренного.

Решение​

Gate закрывается явным и ОТДЕЛЬНЫМ кликом пользователя — тот же интерактивный шаблон, что у «Подтвердить готовность архитектуры» (RN-160): выделенная кнопка в SessionPage.tsx, выделенный HTTP-маршрут (POST .../agents/criativo/validate-necessity), выделенный сценарий использования (ValidateNecessityUseCase), который записывает доменное событие necessity.validated (RN-406).

Цепочка: после confirm_readiness, а не параллельно с ним​

Разумными были два порядка: (а) кнопка проверки включается только ПОСЛЕ того, как confirm_readiness уже отработал (product_brief существует); или (б) обе кнопки сосуществуют, каждая со своим предусловием, без отношения порядка между ними.

Выбран (а). Решающий аргумент: нет смысла «проверять» product_brief, который ещё не сведён, — necessidade-validada — это gate ВЫХОДА Criativo в docs/fluxo.yml, момент, когда его работа уже произвела конкретный артефакт для суждения пользователя. Вариант (б) позволил бы проверить потребность ДО того, как появится исполнительное резюме, которое её представляет, что перевернуло бы порядок самого потока (потребность — ЭТО сведённый product_brief, а не свободная беседа, которая ему предшествует). hasProductBrief (events.some(e => e.type === 'artifact.product_brief')) — предусловие новой кнопки, по тому же шаблону, что hasBusinessRule/hasPromotedStory, которые уже охраняют две соседние кнопки.

Почему НЕ сигнализирует engine​

В отличие от OfferInfraHandoffUseCase (RN-160/ADR 0086), который вызывает engineClient.offerInfraHandoff/offerDevHandoff, потому что ПОДТВЕРЖДЕНИЕ — это то, что включает следующий шаг, здесь handoff Criativo→PO уже произошёл внутри самого confirm_readiness (CriativoServer.executar_confirm_readiness/1 вызывает EngineApiClient.create_handoff ещё до появления этого gate). Нет ни одного агента, ожидающего necessity.validated, чтобы действовать, — событие — лишь запись того, что человек подтвердил суть уже поставленного. У ValidateNecessityUseCase нет порта к engine в конструкторе, намеренно: ничего, кроме SessionEventRepository (прочитать самый свежий product_brief) и AppendSessionEventUseCase (записать).

docs/gates.yml: warn, а не block​

aprovacao_humana: true (это буквально клик человека) и verificacao: script (скрипт проверки уже может извлечь necessity.validated из event log). Но severidade: warn: ни один механизм продукта сегодня не ПРОВЕРЯЕТ, пройден ли этот gate, прежде чем позволить PO продолжить, — в отличие от story-promovida/plano-de-adocao (block, потому что реальная блокировка в коде не даёт их пропустить), этот gate — измерение, а не ворота. Тот же дух, что в комментарии, уже используемом в implementavel: «рождается warn, даже когда включается». Если позже появится блокирующий механизм (напр.: PO, отказывающийся работать без проверки), повышение до block — это новое продуктовое решение со своим ADR, а не что-то подразумеваемое в этой поставке.

Последствия​

За

  • Закрывает ПОСЛЕДНЮЮ из шести волн плана аудита fluxo.yml × код (docs/explanation/auditoria-fluxo-vs-codigo.md, раздел D) — все шесть закрыты (3, 4 и 5 были выполнены досрочно вне очереди ADR 0089/0090; 1 и 2 закрыты в предыдущих PR; эта — 6-я и последняя).
  • В docs/gates.yml больше нет gate с ролью active без записи — последнего пробела такого типа, на который указал аудит.
  • Механизм узнаваем: тот, кто уже читал «Подтвердить готовность архитектуры» (RN-160), прочитает этот бесплатно — тот же шаблон выделенной кнопки + предусловие
    • собственное событие.

Против

  • Ещё один клик в потоке Criativo, когда confirm_readiness уже сам производит product_brief и handoff. Принято: именно этот лишний клик отделяет «модель решила» от «человек проверил» — без него не было бы никакого gate, лишь тот же привычный механизм под новым именем.
  • Gate warn НИЧЕМУ не мешает продолжаться без него — проект может жить вечно, ни разу не запустив necessidade-validada, и PO продолжает работать как обычно. Принято намеренно: выдумывать блокировку, когда никто в продукте не просил жёстких ворот, было бы ошибкой того же класса, что ADR 0041/0042/0077 уже отвергают для выдуманных capability/оценок, — объявить gate честным измерением лучше, чем притворяться, что он блокирует то, чего не блокирует.

Рассмотренные альтернативы​

Переиспользовать confirm_readiness — одна кнопка, которая уже считается за обе вещи. Явно отвергнуто запросом, породившим этот ADR: confirm_readiness/RN-142 — структурный нижний порог («существует хотя бы 1 зафиксированное правило»), а не суждение по существу о СОДЕРЖИМОМ потребности. Слияние двух сохранило бы мелкий порог, замаскированный под новый gate.

Criativo (модель) решает сам, через новый инструмент (confirm_necessity_validated как tool call). Отвергнуто: это тот самый антипаттерн, ради избежания которого существует этот ADR, — агент, который произвёл product_brief, не может быть тем, кто удостоверяет, что он верен.

Считать AcceptHandoffUseCase (PO, принимающий handoff) проверкой. Отвергнуто: принятие структурно и общее для ЛЮБОГО handoff продукта — изменение его смысла только для этого источника сломало бы прочтение «принять = я начал работать», на которое QA, Infra и Dev Lead тоже полагаются.

severidade: block сразу, блокируя PO, пока потребность не будет проверена. Отвергнуто: это потребовало бы выдумать механизм блокировки (напр.: ActivateAgentUseCase, отказывающийся включать PO без necessity.validated), о котором никто не просил и которого сегодня нет ни для одного эквивалентного gate (arquitetura-pronta/RN-160 тоже ничего не блокирует в backend вне перепроверки продвинутой истории). Зафиксировано как будущая возможность, а не как часть этой поставки.

Ссылки​

  • apps/api/src/application/use-cases/agents/validate-necessity.use-case.ts
  • apps/api/src/interfaces/http/agents/agents.controller.ts (validateNecessityHandoff)
  • apps/web/src/routes/SessionPage.tsx (hasProductBrief, necessidadeJaValidada, handleValidateNecessity)
  • docs/gates.yml — gate necessidade-validada
  • docs/fluxo.yml — роль criativo, gate_saida
  • RN-406
  • RN-160 — скопированный интерактивный шаблон
  • docs/explanation/modelo-de-time.md — антипаттерн, мотивировавший решение (удалён из списка ожидающих этим ADR)
  • docs/explanation/auditoria-fluxo-vs-codigo.md — находка B2, раздел D (Волна 6, последняя в плане)