Роль · кто есть кто

ЧЕЛОВЕК

Человек, который стоит в цикле фабрики. Не программа, а живой человек: он проверяет спеки (ТЗ), оценивает результаты шагов и принимает решения, которые система не должна принимать сама.

В коде роль называется ЧЕЛОВЕК (actor=human) · на главную · про спеку (ТЗ) · SPEC-AGENT · DEV-AGENT · про Gate · про Temporal

Что это такое

ЧЕЛОВЕК — это роль человека в workflow. Система автоматизирует агентов, но не всё отдаёт им на откуп: есть решения, которые требуют человека. В коде эта роль обозначается ЧЕЛОВЕК (значение actor=human), и появляется она там, где workflow останавливается и ждёт вердикта человека.

Простая аналогия: агенты — это «сотрудники» (аналитик SPEC-AGENT и разработчик DEV-AGENT), а ЧЕЛОВЕК — это руководитель, который проверяет их работу и даёт добро.

Где ЧЕЛОВЕК участвует

В текущем пайплайне человек подключён в трёх местах:

✅ Проверка спеки (ТЗ)

одобрить или вернуть на доработку черновик ТЗ до того, как начнётся разработка (Gate спеки).

📋 Оценка результатов шагов

смотреть вывод агента-разработчика и решать: шаг принят, нужна доработка или всё остановить.

🚨 Эскалация

когда цикл не может решиться сам (например, спека возвращалась слишком много раз) — решение передаётся человеку.

Принцип: агенты предлагают, человек решает. Система останавливается на Gate и ждёт человека — она никогда не «додумывает» за него и не проталкивает результат молча.

По каким каналам ЧЕЛОВЕК общается с системой

Человек связан с workflow двумя каналами, и они работают вместе:

Канал 1. Решение — через artifacts-service (REST)

Это «официальный» канал: человек меняет статус артефакта через HTTP-запрос POST /status (decide_transition, actor=human). Именно здесь спека (ТЗ) или результат шага реально переходит из pending_review в approved или rejected:

POST /status { "target_status": "approved" }   # человек одобрил
POST /status { "target_status": "rejected" }  # человек вернул

Это единственный легальный способ вывести артефакт из состояния «на проверке».

Канал 2. «Стук в дверь» — сигнал Temporal

Смена статуса — ещё не всё: workflow в этот момент «спит» и ждёт, пока его разбудят. Для этого есть сигнал human_verdict — уведомление «человек вынес вердикт»:

signal human_verdict(artifact_id, step_id, feedback)
# feedback — текст замечаний при возврате спеки (ТЗ)
Важно: сигнал — только «будильник». Workflow не верит ему на слово: после сигнала он сам перечитывает реальный статус артефакта через artifacts-service и решает по факту. Поэтому порядок «сначала POST, потом сигнал» или «только POST, сигнал потерялся» — не ломает решение.

Что ЧЕЛОВЕК видит и что отдаёт

МоментЧеловек видитЧеловек отдаёт
Проверка спеки (ТЗ)черновик ТЗ (артефакт kind=spec в статусе pending_review)approved — можно работать / rejected — вернуть с текстом замечаний
Оценка результата шагавывод DEV-AGENT (артефакт-результат)approved / rejected (настроение решения по факту вывода)
Эскалациясостояние workflow с причиной «нужен человек»решение: что делать дальше

Как система ждёт человека

Пока человек думает, workflow durably спит — ничего не опрашивает и не тратит ресурсы. Ждать он готов долго (таймаут ожидания вердикта по умолчанию — 24 часа), но не вечно:

  1. Workflow доходит до Gate и «засыпает».
  2. Ждёт сигнала human_verdict (или истечения таймаута).
  3. На любой «стук» сам перечитывает реальный статус артефакта.
  4. Статус изменился (человек решил) → Gate завершается.
  5. Статус не изменился → workflow продолжает ждать; при долгом молчании — эскалация.

Связи

Вход

спека (ТЗ) на проверке, вывод DEV-AGENT, запрос на эскалацию.

Выход

вердикт approved/rejected + при возврате текст замечаний.

Куда смотрит

артефакты в спеке (ТЗ) и результатах шагов.

С кем связан

проверяет работу SPEC-AGENT и DEV-AGENT.