Gate — проверка: пропустить или остановиться

Что такое Gate

Gate (читается «гейт») — это контрольная точка между шагами. Агент что-то сделал — а gate проверяет: «можно это пропускать дальше или нет?». Отсюда и аналогия с воротами: открыть ворота и пропустить работу, вернуть на доработку или закрыть совсем.

Простая аналогия: gate — это ворота с охранником. Работа подходит к воротам, охранник её осматривает и решает: «проходи» (PASS), «переделай» (REWORK), «стоп» (FAIL) или «это не мне решать — зови старшего» (ESCALATE).

В пайплайне сейчас два вида ворот:

Exit-gate (после шага)

проверяет результат шага по exit_code: 0 → PASS, дальше; иначе — стоп.

Gate спеки (ТЗ)

спека (ТЗ) уходит ЧЕЛОВЕКУ на проверку: approve → PASS, reject → переделка.

Исходы: что решает gate

Любой gate завершается одним из четырёх исходов (enum Outcome):

✅ PASS

работа принята — идём к следующему шагу.

🔁 REWORK

надо переделать: вернуть агенту с замечаниями и попробовать снова.

⛔ FAIL

стоп: шаг провален, дальше по этой ветке не идём.

🚨 ESCALATE

система сама не решит — передать человеку.

Какой исход что означает дальше — решает чистая функция route():

route(вердикт, rework_count, spec):
    PASS    → "proceed"   # пропустить дальше
    ESCALATE → "escalate"  # человеку
    REWORK  → если rework_count < max_rework: "rework"   # переделать
              иначе:                             "escalate"  # слишком много раз
    FAIL    → "halt"       # стоп

Максимум переделок задаётся в GateSpec.max_rework. Пока переделок меньше потолка — «rework»; дошли до потолка — «escalate», а не бесконечный круг.

Кто проверяет: два verifier'а

Gate сам ничего не проверяет — он только «ворота». Проверяет verifier — он приносит вердикт, а gate по нему решает. Их два:

AutoVerifier

проверяет автоматически — по exit_code агента: 0 → PASS; ошибка → FAIL; зависание → ESCALATE.

HumanVerifier

ждёт вердикт ЧЕЛОВЕКА: перечитывает реальный статус артефакта и решает по нему (см. ниже).

Gate спеки (ТЗ) — где решает человек

Самый показательный gate — проверка спеки (ТЗ). После того как SPEC-AGENT написал черновик, его нельзя использовать сразу — он проходит через gate, где решает ЧЕЛОВЕК:

Workflow отправляет спеку (ТЗ) на ревью: статус становится pending_review.
Gate «засыпает» и ждёт вердикт человека (durable-ожидание).
Человек решает через POST /status (approved / rejected) + сигнал human_verdict.
Gate перечитывает реальный статус спеки и завершается.
Approved → PASS, работа едет к DEV-AGENT.
Rejected → REWORK: SPEC-AGENT переделывает с учётом замечаний.
Слишком много возвратов (потолок) → ESCALATE: дальше решает человек, а не цикл.

Как gate «спит» и просыпается

Gate, который ждёт человека, работает по принципу «сигнал — только будильник»:

Workflow доходит до gate и «засыпает» (ничего не опрашивает).
Приходит сигнал human_verdict — «человек что-то решил».
Gate не верит сигналу на слово: сам перечитывает реальный статус артефакта через artifacts-service.
Только результат этого чтения решает исход.

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

Связи

Вход

что проверять: exit_code шага или артефакт на ревью (спека (ТЗ), результат).

Проверяющие

AutoVerifier (автоматически) и HumanVerifier (ждёт ЧЕЛОВЕКА).

Исходы

PASS / REWORK / FAIL / ESCALATE → route() решает: proceed / rework / escalate / halt.

Где стоит

после каждого шага (exit-gate) и на проверке спеки (ТЗ).