Files

claude-bot c4a97a7a28 fix(stage-engine): address ORCH-114 review — env/docs canon + in-region rollback CAS

Resolves the REQUEST_CHANGES findings on ORCH-114 (durable transition-ownership
lease + expected-stage CAS):

P1 — documentation = golden source:
- .env.example: add ORCH_TRANSITION_LEASE_ENABLED / ORCH_TRANSITION_LEASE_REPOS
  (canon of 100% start keys, ORCH-101), next to the other gate kill-switches.
- CLAUDE.md: add the ORCH-114 passport section (mechanism, invariant, flags,
  ADR links) so a future agent editing advance_stage/reaper/webhooks finds the
  ownership invariant in the first mandatory-read doc (ORCH-078 traceability index).

P2 — should-fix:
- docs/overview/ (system showcase, ORCH-011): add transition_lease to
  tech-data-model.md (helper tables), tech-observability.md (/queue blocks) and
  tech-architecture.md (components).
- ADR-001 D4 alignment: the four side-effectful-edge rollback handlers
  (_handle_merge_gate_rollback / _handle_security_gate / _handle_coverage_gate /
  _handle_image_freshness) now write `development` through the expected-stage CAS
  via a shared _rollback_stage_cas helper (defence against the rollback↔done
  contradiction, BR-6) instead of a bare unconditional update_task_stage. Under the
  held lease the sole owner always wins; a lost race aborts WITHOUT side effects.
  Kill-switch off / out-of-scope repo -> degenerates to the prior write -> 1:1.
- Test isolation: make tests/test_webhooks.py order-independent by pinning the
  proj-1 registry per-test (mirrors test_webhook_dedup.proj_registry); it had only
  passed by relying on import order. Drop the needless module-level ORCH_DB_PATH
  setdefault in test_orch114 (fresh_db already isolates db_path).

New regression tests (TC-11): in-region rollback writes route through CAS;
rollback CAS wins when at expected stage; rollback CAS-lost does NOT clobber `done`;
kill-switch-off rollback degenerates to the unconditional write.

ruff clean (src/stage_engine.py, src/transition_lease.py); full suite 2052 passed.

Refs: ORCH-114
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-15 19:28:38 +03:00

4.3 KiB

Raw Blame History

Блок 7. Наблюдаемость и аналитика

Машинный контракт метрик и устройство sidecar-наблюдателя — в инженерном справочнике (разделы /metrics и sidecar-watchdog).

Живая Telegram-карточка задачи

Каждая задача — одна карточка в Telegram, обновляемая на каждом событии:

текущая стадия и Plane-статус (включая человеческие гейты — видно, когда задача ждёт вас);
строка работающего агента: роль · модель · эффорт;
стоимость задачи нарастающим итогом (токены/доллары по каждому запуску агента);
честные метрики времени на финише: время агентов / время ожидания человека / общее календарное — три независимые цифры, а не одна вводящая в заблуждение сумма;
кликабельный номер задачи (ведёт в Plane), отметка багфикс-маршрута.

Карточка тихая (без пингов); пингуют только алерты: красный гейт, ожидание решения человека, инциденты.

Служебные страницы платформы

GET /queue — человекочитаемый снимок всего конвейера: очередь и job'ы, состояние serial gate и заморозок, авто-лейблы, багфикс-трек, coverage, журнал уроков, владение переходами (transition_lease), фоновые демоны. Первая точка диагностики «что сейчас происходит».
GET /metrics — машинный контракт для внешнего наблюдателя (версионированная схема): health, возраст последних событий, счётчики сбоев.
GET /health — живость процесса.

Sidecar-watchdog: наблюдатель отделён от наблюдаемого

Отдельный контейнер-сторож опрашивает /metrics платформы и шлёт алерты в собственный Telegram-канал со своим ботом. Падение платформы, зависание очереди или протухание событий видно даже тогда, когда сама платформа уже не может пожаловаться.

Журнал уроков

Машинная таблица отклонений конвейера: красные гейты, ложные блокировки слияния, исчерпание ретраев, деградации после выкладки. Каждая запись — контекст (задача, стадия, агент, репо), первопричина и предложение. Журнал — наблюдатель (никогда не влияет на продвижение задач) и фундамент петли самообучения платформы: уроки доступны через API и копятся для будущего ретроспективного анализа.

Стоимость и аналитика по агентам

Каждый запуск агента фиксирует модель, эффорт, длительность и стоимость (модель объектов). Это даёт ответы на вопросы «сколько стоит задача», «какая роль ест бюджет», «как изменилась экономика после смены модели» — по фактам, не по ощущениям.

Что делать при инцидентах и как устроен прод — docs/operations/ (через инженерный справочник); бизнес-взгляд на наблюдаемость — business.md.

4.3 KiB Raw Blame History Unescape Escape