Files

claude-bot 6d798c01ef docs(overview): витрина системы docs/overview/ — бизнес+тех, 3 аудитории, презентация (ORCH-011)

Единая точка входа в документацию платформы (ADR-001 D1–D9):
- docs/overview/ — 10 файлов: индекс (маршруты «Я заказчик / Я менеджер /
  Я разработчик» + норматив «изменил функциональность → обнови витрину в том же
  PR»), business.md (без жаргона, 6 сценариев), 7 тех-блоков (link-first),
  presentation.md (16 слайдов + процедура сборки «команда + Проверка:»).
- scripts/build_presentation.py — генератор .pptx в тёмном дизайне (python-pptx;
  чистый stdlib-парсер parse_slides + ленивый import pptx; бинарь не коммитится,
  build/ в .gitignore; зависимость НЕ в прод-образе — машинный гард TC-09).
- tests/test_system_docs.py — структурный анти-дрейф: derive-сверки стадий/
  гейтов/агентов импортом STAGE_TRANSITIONS/QG_CHECKS/glob промптов/config,
  валидность ссылок, FORBIDDEN-скан + секрет-эвристика, слайды каноническим
  парсером, NFR-2, указатели.
- reviewer.md — ось обзорных доков ORCH-079 расширена на витрину (D7; канон 52d
  байт-в-байт, только текст внутри секций) + анти-регресс ассерт в
  test_agent_prompts_canon.py.
- Указатели: README.md, CLAUDE.md (правила №2/№6, «Структура»),
  PRODUCT_VISION.md (врезка-ссылка), CHANGELOG.md.

Рантайм байт-в-байт: src/**, docker-compose.yml, Dockerfile, requirements* —
ноль изменений (docs+tests+dev-скрипт, паттерн ORCH-102/103). pytest: 1873 passed.

Refs: ORCH-011

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

2026-06-11 09:36:40 +03:00

5.7 KiB

Raw Blame History

Блок 1. Архитектура: компоненты и связи

Обзорный уровень. Полная таблица компонентов с деталями и историей решений — в инженерном справочнике («Компоненты») и internals; здесь — цельная картина, как части складываются в конвейер.

Поток одной задачи

            Plane (трекер)            Gitea (git/CI)
                 │ вебхук                  │ вебхук
                 ▼                         ▼
        ┌────────────────────────────────────────┐
        │   FastAPI-приём (HMAC-подпись, дедуп)  │
        └───────────────────┬────────────────────┘
                            ▼
   вебхук → очередь (jobs) → агент (Claude CLI в worktree) → гейт (QG) → переход стадии
                            ▲                                              │
                            └────────── следующая стадия / откат ◄─────────┘

Каждое продвижение задачи — один и тот же цикл: событие принято → в очередь поставлен job → worker запустил агента стадии → результат проверен гейтом качества → state machine перевела задачу на следующую стадию (или откатила назад).

Компоненты

Компонент	Роль
Webhook-приёмники (`src/webhooks/`)	Принимают события Plane (статусы задач) и Gitea (push, PR, CI). Проверяют HMAC-подпись, дедуплицируют повторные доставки.
Очередь задач (`jobs` + worker)	Собственная очередь на SQLite: атомарный захват job'а, ретраи с backoff, зависимости между job'ами, ограничение параллелизма.
State machine (`src/stages.py`)	Карта стадий `STAGE_TRANSITIONS`: для каждой стадии — следующая, агент и гейт выхода. Единственный источник истины о конвейере.
Stage engine (`src/stage_engine.py`)	Исполняет переходы: диспетчеризация гейтов, откаты, под-гейты деплойного ребра, синхронизация статусов с Plane.
Agent launcher (`src/agents/launcher.py`)	Запускает Claude CLI агента в изолированном git worktree ветки задачи, следит за процессом (watchdog), авто-продвигает стадию по завершении.
Реестр гейтов (`src/qg/checks.py`)	`QG_CHECKS` — машинные проверки выхода со стадий; вердикты читаются только из YAML-frontmatter артефактов.
Plane-sync (`src/plane_sync.py`)	Индикация статусов в Plane (слой «показать человеку», никогда не управление конвейером).
Notifications (`src/notifications.py`)	Живая Telegram-карточка задачи и алерты.

Фоновые демоны (самовосстановление)

Поднимаются в lifespan FastAPI-приложения (src/main.py) и работают рядом с конвейером:

reconciler — находит расхождения «БД говорит одно, реальность другое» (зависшие стадии, потерянные ветки) и возвращает задачи в консистентное состояние;
job-reaper — возвращает в очередь job'ы, чей исполнитель умер (упавший процесс, рестарт);
disk-watchdog — следит за местом на диске, чистит устаревшие worktree;
build-cache-pruner — прибирает докер-кэш сборок.

Отдельно от приложения живёт sidecar-watchdog — независимый контейнер-наблюдатель: следит за самим оркестратором снаружи (health, метрики) и шлёт алерты в собственный Telegram-канал. Наблюдатель сознательно отделён от наблюдаемого: падение оркестратора не валит сторожа.

Изоляция работы агентов

Каждая задача живёт в собственной git-ветке (feature/<ID>-slug) и собственном worktree — изолированной рабочей копии репозитория. Агенты разных задач не видят незакоммиченную работу друг друга; слияние в main происходит только через PR в Gitea после всех гейтов.

Подробнее: компоненты и API · внутренности и схема БД · следующий блок — конвейер и стадии.

5.7 KiB Raw Blame History Unescape Escape