admin/orchestrator
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Единая точка входа в документацию платформы (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>
This commit is contained in:
claude-bot
2026-06-11 09:24:01 +03:00
committed by orchestrator-deployer
parent c455931ae7
commit 6d798c01ef
20 changed files with 1528 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/PRODUCT_VISION.md
View File

@@ -4,6 +4,9 @@
**Версия:** 1.0 · **Дата:** 2026-06-04 · **Статус:** концепция развития
> **Фактическое текущее состояние платформы** (что уже умеет, как устроена) — витрина системы
> [docs/overview/](overview/README.md) (ORCH-011). Этот документ — vision: «куда идём».
---
## 1. Зачем это (бизнес-взгляд)

89
docs/overview/README.md Normal file
View File

@@ -0,0 +1,89 @@
# Витрина системы — Orchestrator
**Что это за система.** Orchestrator — автономная фабрика разработки: конвейер из шести
ИИ-агентов (аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер), который
проводит задачу от бизнес-постановки до выкладки на прод. Человек ставит задачу и принимает
результат; всё между — автономно, под защитой машинных гейтов качества. Платформа ведёт
несколько проектов из одного инстанса, дорабатывает сама себя (self-hosting) и тиражируется
на новые хосты.
**Зачем эта витрина.** Это единая точка входа в документацию системы: связное описание на двух
уровнях — бизнес (для нетехнического читателя) и технический (7 блоков), с маршрутами чтения
для трёх аудиторий и слайдо-готовой основой для презентации. Витрина — обзор; за деталями она
ведёт ссылками в инженерные golden sources, не подменяя их.
---
## Состав витрины
| Файл | О чём |
|------|-------|
| [business.md](business.md) | Бизнес-уровень: проблема, решение, что умеет, ценность, сценарии |
| [tech-architecture.md](tech-architecture.md) | Блок 1: компоненты и связи, схема потока |
| [tech-pipeline.md](tech-pipeline.md) | Блок 2: конвейер, стадии, гейты, откаты, человеческие гейты |
| [tech-agents.md](tech-agents.md) | Блок 3: 6 ролей агентов, артефакты, модель/эффорт |
| [tech-data-model.md](tech-data-model.md) | Блок 4: каноническая модель объектов, словарь терминов |
| [tech-integrations.md](tech-integrations.md) | Блок 5: Plane, Gitea, LLM, Telegram |
| [tech-quality-security.md](tech-quality-security.md) | Блок 6: гейты качества, безопасность, секреты |
| [tech-observability.md](tech-observability.md) | Блок 7: наблюдаемость, аналитика, журнал уроков |
| [presentation.md](presentation.md) | Слайдо-источник презентации + сборка `.pptx` |
---
## Маршруты чтения
### Я заказчик
1. [business.md](business.md) — проблема, решение, ценность.
2. [business.md → Сценарии использования](business.md#сценарии-использования) — как это выглядит в работе.
3. [presentation.md](presentation.md) — слайдовая версия рассказа (собирается в PowerPoint).
4. Развернуть у себя: [LITE_SETUP](../deployment/LITE_SETUP.md) (своя инфраструктура) или
[BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md) (весь стек одним комплектом).
### Я менеджер проекта
1. [business.md](business.md) — что платформа делает и где в процессе человек.
2. [tech-pipeline.md](tech-pipeline.md) — конвейер, статусная модель Plane, человеческие гейты
(одобрение постановки, подтверждение прод-деплоя).
3. [tech-observability.md](tech-observability.md) — как следить за ходом: живая Telegram-карточка,
статусы, стоимость.
### Я разработчик
1. Тех-блоки 1→7: [архитектура](tech-architecture.md) → [конвейер](tech-pipeline.md) →
[агенты](tech-agents.md) → [модель объектов](tech-data-model.md) →
[интеграции](tech-integrations.md) → [качество/безопасность](tech-quality-security.md) →
[наблюдаемость](tech-observability.md).
2. [Инженерный справочник архитектуры](../architecture/README.md) и
[internals](../architecture/internals.md) — детали реализации.
3. [Стандарты](../_standards/PIPELINE_DOCS.md) (структура доков конвейера),
[HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md) (машинный контракт стадий),
[TRACEABILITY](../_standards/TRACEABILITY.md) (маркеры решений).
4. [Реестр сквозных ADR](../architecture/adr/) — история архитектурных решений.
5. [CLAUDE.md](../../CLAUDE.md) — паспорт проекта и правила для агентов.
---
## Норматив сопровождения
> **Изменил функциональность платформы → обнови витрину `docs/overview/` в том же PR.**
Какой файл правится при каком классе изменений:
| Класс изменения | Файл витрины |
|-----------------|--------------|
| Новый компонент / демон / поток данных | [tech-architecture.md](tech-architecture.md) |
| Стадии, гейты, под-гейты, маршруты задач | [tech-pipeline.md](tech-pipeline.md) |
| Роли агентов, промпты, модель/эффорт | [tech-agents.md](tech-agents.md) |
| Таблицы БД, объекты, термины | [tech-data-model.md](tech-data-model.md) |
| Plane / Gitea / LLM / Telegram | [tech-integrations.md](tech-integrations.md) |
| Гейты качества, секреты, self-hosting-страховки | [tech-quality-security.md](tech-quality-security.md) |
| Эндпоинты наблюдаемости, метрики, уроки | [tech-observability.md](tech-observability.md) |
| Новая способность уровня продукта | [business.md](business.md) + при необходимости [presentation.md](presentation.md) |
Каркас и машинно-проверяемые факты витрины (перечень стадий, имена гейтов, полнота агентов,
валидность ссылок) защищены структурными тестами `tests/test_system_docs.py` — дрейф рвёт CI.
Прозу проверяет reviewer: необновлённая витрина при изменении описанной в ней функциональности —
finding ≥ P1 (расширение оси обзорных доков).
---
*Витрина — обзорный слой документации. Текущее состояние и реестр доработок — [CLAUDE.md](../../CLAUDE.md);
концепция развития — [Product Vision](../PRODUCT_VISION.md).*

105
docs/overview/business.md Normal file
View File

@@ -0,0 +1,105 @@
# Бизнес-уровень: что это и зачем
> Читатель этого документа — нетехнический: заказчик, руководитель, менеджер. Технические
> детали вынесены в [тех-часть витрины](README.md) и даются здесь только ссылками.
## Проблема
Классическая разработка — это люди-бутылочное-горлышко на каждом шаге: аналитик, архитектор,
разработчик, ревьюер, тестировщик, деплой-инженер. Каждая передача задачи между ними — потеря
времени, контекста и денег. Мелкая фича или баг едут до прода днями: не потому, что работа
сложная, а потому, что задача ждёт людей в очередях между ролями.
## Решение
**Orchestrator** — конвейер из ИИ-агентов, который проводит задачу через все стадии разработки
сам: анализ требований → проектирование → код → ревью → тестирование → репетиция выкладки →
выкладка на прод. Человек в этой схеме — **постановщик и приёмщик**: он формулирует задачу,
одобряет постановку и подтверждает выкладку на прод. Всё между — автономно.
Честность конвейера держат **гейты качества**: автоматические проверки на каждом переходе,
которые не пускают задачу дальше, пока стадия не выполнена по-настоящему (тесты зелёные,
ревью одобрено, репетиция выкладки успешна). Агент не может «уговорить» гейт — вердикты
машинные, не прозой.
## Что умеет платформа сегодня
Ниже — фактическое состояние, не планы (концепция развития — отдельный документ,
[Product Vision](../PRODUCT_VISION.md)).
- **Автономный конвейер «задача → прод».** Задача, поставленная в трекере, проходит весь путь
до выкладки без ручных пинков; человек участвует ровно в двух точках — одобрение постановки
и подтверждение прод-выкладки.
- **Мультипроектность.** Один инстанс платформы ведёт несколько проектов (репозиториев)
одновременно, с общей очередью и честным разделением работы.
- **Самовосстановление.** Фоновые механизмы находят и чинят зависшие задачи: упавший агент
перезапускается, осиротевшая задача возвращается в очередь, переполненный диск чистится,
а независимый сторож следит за самой платформой снаружи.
- **Пакетный авто-режим.** Задачи одного проекта выстраиваются в очередь и едут друг за другом
без столкновений; специальными метками на задаче можно снять оба человеческих одобрения —
и пакет задач уедет «за ночь» полностью автономно.
- **Дешёвый багфикс-маршрут.** Задача с меткой «баг» едет коротким путём — без тяжёлой
аналитики и отдельной стадии проектирования, но через все те же гейты качества.
- **Отмена задачи одной кнопкой.** Перевод задачи в статус «STOP» в трекере останавливает
работу, снимает её с очереди и прибирает за собой — безопасно даже посреди конвейера.
- **Наблюдаемость.** У каждой задачи — живая карточка в Telegram (стадия, время, стоимость);
у платформы — служебные страницы состояния и машинные метрики; история отклонений пишется
в журнал уроков.
- **Самообслуживание (self-hosting).** Платформа дорабатывает сама себя тем же конвейером,
с обязательной репетицией на песочнице и ручным подтверждением выкладки.
- **Тиражируемость.** Платформа разворачивается на новой инфраструктуре без правки кода:
вариант Lite (у заказчика своя инфраструктура) и вариант Bundled (весь стек одним
комплектом) — по пошаговым инструкциям.
## Ценность
- ⚡ **Скорость.** Полный цикл «постановка → прод» без очередей между ролями; по оценке из
[Product Vision](../PRODUCT_VISION.md) — порядка 35 минут на типовую фичу без ручных
вмешательств.
- 💰 **Стоимость.** Работа агентов в разы дешевле команды специалистов; стоимость каждой
задачи видна в её карточке — расходы прозрачны.
- 🎯 **Автономность.** Ноль ручных пинков в штатном прогоне: человек принимает решения,
а не двигает задачу.
- 🛡️ **Надёжность.** Многоуровневые гейты качества и репетиция выкладки на песочнице не
пускают недоделку на прод; сломавшаяся выкладка откатывается, проект замораживается до
разбора.
- 🔁 **Масштаб.** Одна платформа — несколько проектов; сама платформа тиражируется на новые
хосты за часы по инструкции.
## Сценарии использования
### Сценарий 1: фича за вечер
Заказчик формулирует задачу в трекере и переводит её в работу. Конвейер собирает требования,
проектирует, пишет код и тесты, проходит ревью и тестирование, репетирует выкладку. Человек
дважды нажимает «одобрить» — на постановке и перед продом. Вечером фича на проде.
### Сценарий 2: багфикс по короткому маршруту
На задачу ставится метка «баг» — конвейер пропускает тяжёлую аналитику и отдельное
проектирование, сразу чинит и фиксирует дефект регресс-тестом. Все гейты качества — без
исключений.
### Сценарий 3: пакет задач на ночь
Несколько задач проекта получают метки авто-одобрения. Очередь проводит их друг за другом:
каждая следующая стартует от свежей версии кода с результатом предыдущей. Утром — пакет
изменений на проде и полный след по каждой задаче.
### Сценарий 4: несколько проектов параллельно
Один инстанс платформы обслуживает несколько репозиториев: задачи разных проектов едут
одновременно, не мешая друг другу; внутри одного проекта порядок строго последовательный.
### Сценарий 5: развернуть платформу у себя
Заказчик получает платформу на своей инфраструктуре по инструкции
[Lite](../deployment/LITE_SETUP.md) (есть свои трекер и git) или
[Bundled](../deployment/BUNDLED_SETUP.md) (весь стек одним комплектом, ~14 контейнеров),
со свежими секретами и проверкой каждого шага.
### Сценарий 6: остановить задачу
Передумали — переводите задачу в статус «STOP»: работа агента останавливается, ветка и
рабочие материалы прибираются, задача помечается отменённой. Если задача в этот момент в
необратимой фазе выкладки — отмена аккуратно откладывается до её честного завершения.
---
*Технические детали каждой способности — в [тех-части витрины](README.md): как устроен
[конвейер](tech-pipeline.md), кто такие [агенты](tech-agents.md), как работает
[наблюдаемость](tech-observability.md).*

190
docs/overview/presentation.md Normal file
View File

@@ -0,0 +1,190 @@
# Презентация системы: слайдо-источник
> Источник истины презентации. Каждый слайд — блок `## Слайд N: Заголовок` с тезисами
> (3–6 на слайд) и опциональной подписью визуала. Из этого файла собирается редактируемый
> PowerPoint в тёмном дизайне — процедура в конце файла («Как собрать .pptx»). Собранный
> бинарь в git не коммитится: меняешь рассказ — правишь этот файл и пересобираешь.
## Слайд 1: Orchestrator — автономная фабрика разработки
- Конвейер из ИИ-агентов: от постановки задачи до выкладки на прод
- Человек ставит задачу и принимает результат — всё между автономно
- Платформа уже работает: ведёт несколько проектов и дорабатывает сама себя
> Визуал: тёмный титул, логотип-конвейер из шести звеньев
## Слайд 2: Проблема
- Классическая разработка — люди-бутылочное-горлышко на каждом шаге
- Каждая передача между ролями — потеря времени, контекста и денег
- Мелкая фича или баг едут до прода днями — из-за очередей, не сложности
> Визуал: цепочка из шести человек с песочными часами между ними
## Слайд 3: Решение
- Шесть ИИ-агентов проводят задачу через все стадии разработки сами
- Аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер
- Человек принимает два решения: одобрить постановку и подтвердить прод
- Честность держат машинные гейты качества — их нельзя «уговорить»
> Визуал: та же цепочка, но из агентов; человек над ней с двумя кнопками
## Слайд 4: Как это работает — конвейер
- Задача из трекера едет по стадиям: анализ → проектирование → код → ревью → тесты → репетиция → прод
- На каждом переходе — гейт: машинная проверка честности стадии
- Не прошёл гейт — задача возвращается на доработку с замечаниями
- Каждая задача — своя ветка и изолированная рабочая копия кода
> Визуал: горизонтальная схема стадий со шлагбаумами-гейтами
## Слайд 5: Гейты качества
- Вердикты машинные: зелёный CI, одобрение ревью, отчёт тестов — только структурированные ключи
- Перед продом — четыре дополнительных проверки: безопасность, слияние, покрытие тестами, свежесть сборки
- Покрытие тестами не может деградировать: базовая линия растёт только вверх
- Слияние в основную ветку — только через PR; прямой push запрещён всем
> Визуал: четыре шлагбаума подряд перед воротами «прод»
## Слайд 6: Роли агентов
- Аналитик: требования, критерии приёмки, тест-план
- Архитектор: проектные решения с фиксацией в ADR
- Разработчик: код + тесты + документация одним PR
- Ревьюер и тестировщик: независимые машинные вердикты
- Деплойер: репетиция на песочнице, затем прод
> Визуал: шесть карточек-ролей с артефактами на выходе
## Слайд 7: Человек в контуре
- Постановщик и приёмщик, а не оператор: ноль ручных пинков в штатном прогоне
- Решение 1: одобрить постановку после аналитики
- Решение 2: подтвердить выкладку на прод отдельным статусом
- Живая карточка задачи в Telegram показывает, когда конвейер ждёт вас
> Визуал: человек с двумя кнопками и карточка задачи в телефоне
## Слайд 8: Пакетный автономный режим
- Задачи одного проекта едут строго друг за другом — без столкновений
- Каждая следующая стартует от свежего кода с результатом предыдущей
- Метки авто-одобрения снимают оба человеческих гейта — пакет уезжает «за ночь»
- Технические проверки при этом не ослабляются ни на одну
> Визуал: ночная очередь задач, утром — стопка готовых
## Слайд 9: Багфикс за полцены
- Метка «баг» — и задача едет коротким маршрутом
- Пропускаются тяжёлая аналитика и отдельное проектирование
- Обязателен регресс-тест, фиксирующий дефект
- Все гейты качества — без исключений
> Визуал: развилка маршрутов — длинный и короткий путь к одному финишу
## Слайд 10: Самовосстановление
- Упавший агент перезапускается, осиротевшая задача возвращается в очередь
- Зависшие состояния находит и чинит фоновый сверщик
- Независимый сторож следит за платформой снаружи и шлёт алерты отдельным каналом
- Деградация прода после выкладки замораживает проект до разбора человеком
> Визуал: платформа с автоподзаводом и внешним сторожем
## Слайд 11: Наблюдаемость
- Одна задача — одна живая карточка: стадия, агент, стоимость, время
- Служебные страницы: снимок очереди и машинные метрики для мониторинга
- Журнал уроков копит отклонения конвейера — фундамент самообучения
- Стоимость каждой задачи и каждой роли видна по фактам
> Визуал: дашборд из карточки, очереди и графика стоимости
## Слайд 12: Одна платформа — много проектов
- Несколько репозиториев из одного инстанса с общей очередью
- Внутри проекта — строгий порядок, между проектами — параллельность
- Платформа дорабатывает сама себя тем же конвейером (self-hosting)
- Своя доработка репетируется на песочнице и требует явного подтверждения
> Визуал: один конвейер, несколько лент с разными проектами
## Слайд 13: Сценарии использования
- Фича за вечер: постановка → прод с двумя кликами человека
- Пакет задач на ночь: метки авто-одобрения, утром всё на проде
- Багфикс по короткому маршруту с обязательным регресс-тестом
- Остановить задачу: статус STOP — безопасная отмена с уборкой
- Несколько проектов параллельно без пересечений
> Визуал: пять пиктограмм-сценариев
## Слайд 14: Тираж платформы
- Разворачивается на новой инфраструктуре без правки кода — только конфиг
- Lite: у заказчика свои трекер и git — ставятся только оркестратор и сторож
- Bundled: весь стек одним комплектом (~14 контейнеров) и бутстрап-скрипт
- Свежие секреты, пошаговые инструкции с проверкой каждого шага
> Визуал: коробка-дистрибутив в двух размерах
## Слайд 15: Статус платформы сегодня
- В проде: автономный конвейер, мультипроектность, самовосстановление
- В проде: пакетный авто-режим, багфикс-маршрут, отмена задач, журнал уроков
- Тираж Lite и Bundled — готовые инструкции и инструменты
- Платформа развивает сама себя: документация и гейты растут с каждой задачей
> Визуал: чек-лист способностей с отметками «в проде»
## Слайд 16: Итог
- Разработка без очередей между ролями: задача → прод за один проход
- Человек принимает решения — конвейер делает работу
- Качество держат машинные гейты, прозрачность — живая карточка и метрики
- Следующий шаг: поставить первую задачу или развернуть платформу у себя
> Визуал: тёмный финальный слайд с одной фразой-приглашением
---
## Как собрать .pptx
Сборка выполняется **вне рантайма платформы** — в одноразовом dev-окружении на хосте
разработчика (зависимость генерации не входит в прод-образ). Скрипт —
`scripts/build_presentation.py`; формат слайдов выше парсится им же (один парсер — один
источник истины).
**Шаг 1. Создать venv и поставить python-pptx:**
```bash
python3 -m venv .venv-pptx
.venv-pptx/bin/pip install python-pptx
```
Проверка: `.venv-pptx/bin/pip show python-pptx` печатает версию пакета — PASS; ошибка
установки — FAIL (проверьте доступ к PyPI).
**Шаг 2. Собрать презентацию (из корня репозитория):**
```bash
.venv-pptx/bin/python scripts/build_presentation.py
```
Проверка: скрипт печатает `Собрано слайдов: <N> → build/orchestrator-overview.pptx`, где
`<N>` равно числу слайдов в этом файле — PASS; `ОШИБКА: …` — FAIL (текст подскажет причину).
**Шаг 3. Открыть и проверить результат:**
Откройте `build/orchestrator-overview.pptx` в PowerPoint/LibreOffice. Проверка: тема тёмная
(тёмный фон, светлый текст, акцентные заголовки), кириллица отображается точно, текст слайдов
выделяется и редактируется — PASS. Каталог `build/` в `.gitignore`: собранный бинарь в git
не попадает.
---
*Нарратив слайдов опирается на [business.md](business.md); технические утверждения — на
тех-блоки витрины ([конвейер](tech-pipeline.md), [агенты](tech-agents.md)).*

60
docs/overview/tech-agents.md Normal file
View File

@@ -0,0 +1,60 @@
# Блок 3. Агенты: 6 ролей конвейера
> Промпты ролей лежат в `.openclaw/agents/*.md` (по одному файлу на роль). Канон манифеста
> «документ → агент → стадия → гейт → machine-key» — [PIPELINE_DOCS §2](../_standards/PIPELINE_DOCS.md);
> машинный контракт передачи между стадиями — [HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md).
## Паспорта ролей
| Роль | Стадия | Вход | Выходные артефакты | Machine-verdict ключ |
|------|--------|------|--------------------|----------------------|
| `analyst` | analysis | бизнес-запрос (`00-business-request.md`) | `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml` | — (гейт проверяет полноту пакета + одобрение человека) |
| `architect` | architecture | пакет аналитики | `06-adr/ADR-NNN-*.md`, when-applicable `07-infra-requirements.md` / `08-data-requirements.md`, `10-tech-risks.md` | — (гейт проверяет наличие ADR) |
| `developer` | development | ТЗ + ADR | код в `src/`, тесты в `tests/`, обновлённые доки, `CHANGELOG.md`, PR в Gitea | — (гейт — зелёный CI ветки) |
| `reviewer` | review | PR diff + ТЗ/ADR | `12-review.md` | `verdict:` (`APPROVED` \| `REQUEST_CHANGES`) |
| `tester` | testing | ветка задачи + тест-план | `13-test-report.md` | `result:` (`PASS` \| `FAIL` \| `BLOCKED`) |
| `deployer` | deploy-staging / deploy | прошедшая гейты ветка | `15-staging-log.md`, `14-deploy-log.md` | `staging_status:` / `deploy_status:` (`SUCCESS` \| `FAILED`) |
Machine-verdict ключи читаются гейтами **только из YAML-frontmatter** артефакта (никогда из
прозы) и неизменны байт-в-байт — подробнее в [блоке качества](tech-quality-security.md).
## Модель и эффорт
Модель и эффорт каждой роли резолвятся **только из конфига** (не из промпта); текущие
дефолты конфига:
| Роль | Модель | Эффорт |
|------|--------|--------|
| `analyst` | `claude-opus-4-8` | `high` |
| `architect` | `claude-opus-4-8` | `high` |
| `developer` | `claude-opus-4-8` | `xhigh` |
| `reviewer` | `claude-opus-4-8` | `high` |
| `tester` | `claude-opus-4-8` | `medium` |
| `deployer` | `claude-opus-4-8` | `medium` |
Разработчику — максимальный эффорт (он пишет код); тестировщику и деплойеру хватает среднего
(их работа процедурная). Таблица сверяется с class-default'ами `src/config.py` структурным
тестом — дрейф рвёт CI.
## Канон промптов
Все промпты следуют единому канону (Anthropic XML, эпик 52): пять обязательных секций в
нормативном порядке `<context>` → `<task>` → `<deliverables>` → `<constraints>` →
`<output_format>`, запреты в формате «❌ X → ✅ Y», секция эскалации у решающих ролей. Каждый
агент эмитит единую frontmatter-схему в своих документах (work item, стадия, автор, статус,
дата, модель). Промпт читается из worktree в момент запуска — обновление промптов вступает в
силу со следующей задачи, без рестарта прода.
Особенность: промпт `deployer` сознательно на английском (самый safety-critical — несёт
запреты self-hosting в видной рамке); остальные пять — на русском.
## Человек как седьмая роль
Человек не пишет артефакты конвейера, но принимает два решения, которые не делегированы
агентам: одобрение постановки (после `analyst`) и подтверждение прод-выкладки (перед финалом
работы `deployer`). Подробнее — [человеческие гейты](tech-pipeline.md).
---
*Структуры документов, которые сдаёт каждая роль, — [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md);
скелеты — `docs/_templates/`.*

63
docs/overview/tech-architecture.md Normal file
View File

@@ -0,0 +1,63 @@
# Блок 1. Архитектура: компоненты и связи
> Обзорный уровень. Полная таблица компонентов с деталями и историей решений — в
> [инженерном справочнике](../architecture/README.md) («Компоненты») и
> [internals](../architecture/internals.md); здесь — цельная картина, как части складываются
> в конвейер.
## Поток одной задачи
```
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](../architecture/README.md) · [внутренности и схема БД](../architecture/internals.md) ·
следующий блок — [конвейер и стадии](tech-pipeline.md).*

70
docs/overview/tech-data-model.md Normal file
View File

@@ -0,0 +1,70 @@
# Блок 4. Структура объектов: каноническая модель
> Источник истины — фактическая схема SQLite в `src/db.py` и реестр проектов в
> `src/projects.py`; подробное описание таблиц — [internals, «Database Schema»](../architecture/internals.md).
## Каноническая модель
```
Project ──1:N──► Work-Item / Task ──1:N──► Job ──1:N──► Agent-run
│ │
│ └── артефакты задачи (docs/work-items/<ID>/)
└── Plane-проект ↔ git-репозиторий ↔ префикс задач
```
### Project — проект в реестре
Связка «Plane-проект ↔ git-репозиторий ↔ префикс задач» (например, `ORCH-`). Реестр живёт в
конфиге (`src/projects.py`): один инстанс платформы обслуживает несколько проектов; по
префиксу задачи платформа находит репозиторий и настройки.
### Work-Item / Task — задача конвейера
Строка таблицы `tasks`: текущая **стадия** (`stage`), **маршрут** (`track`: полный или
багфикс), рабочая **ветка**, счётчики откатов, отметки отмены. Натуральные ключи — ID задачи
в Plane и человекочитаемый номер (`ORCH-NNN`). На каждой стадии задача накапливает
**артефакты** — номерные документы в `docs/work-items/<ID>/` (от бизнес-запроса до
deploy-лога; манифест — [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md)).
### Job — единица работы в очереди
Строка таблицы `jobs`: что запустить (агент какой стадии), для какой задачи, в каком статусе
(`queued` → `running` → терминал). Очередь даёт: **атомарный захват** (два worker'а не возьмут
один job), **зависимости** между job'ами, **ретраи** с экспоненциальным backoff и breaker
после исчерпания бюджета, ограничение параллелизма.
### Agent-run — один запуск агента
Строка таблицы `agent_runs`: какой агент, какой моделью и эффортом, сколько длился, сколько
стоил (токены/доллары). Из этих строк складывается честная стоимость задачи в живой карточке
и аналитика по ролям.
### События вебхуков и дедуп
Входящие события Plane/Gitea фиксируются с ключом дедупликации: повторная доставка того же
события (ретраи источника, сетевые икоты) не порождает повторной работы.
## Вспомогательные таблицы
| Таблица | Зачем |
|---------|-------|
| `repo_freeze` | durable-заморозка репозитория после деградации прода (serial gate) |
| `coverage_baseline` | базовая линия покрытия тестами; растёт только вверх (ratchet) |
| `tracker_messages` | леджер всех Telegram-карточек задачи (зачистка сирот) |
| `lessons` | машинный журнал уроков — структурированные отклонения конвейера |
Все изменения схемы — аддитивные и идемпотентные (`CREATE TABLE IF NOT EXISTS`, ensure-column
при старте): обновление платформы не требует ручных миграций.
## Словарь терминов
| Термин | Значение |
|--------|----------|
| **Стадия** | Позиция задачи в конвейере; карта стадий — `STAGE_TRANSITIONS` ([блок 2](tech-pipeline.md)) |
| **Гейт (exit-гейт)** | Машинная проверка выхода со стадии; реестр — `QG_CHECKS` |
| **Под-гейт** | Проверка-врезка внутри перехода (не стадия); см. деплойное ребро в [блоке 2](tech-pipeline.md) |
| **Job** | Единица работы в очереди; задача порождает job'ы по мере продвижения |
| **Worktree** | Изолированная рабочая копия репозитория для ветки задачи |
| **Lease (merge-lease)** | Эксклюзивная блокировка «кто сейчас мержит этот репозиторий» — сериализация слияний |
| **Track (маршрут)** | Вариант пути задачи: полный цикл или багфикс с пропуском проектирования |
| **Freeze** | Заморозка очереди репозитория после инцидента до ручного разбора |
---
*Как объекты двигаются по конвейеру — [блок 2](tech-pipeline.md); кто их создаёт —
[агенты](tech-agents.md); как за ними наблюдать — [блок 7](tech-observability.md).*

54
docs/overview/tech-integrations.md Normal file
View File

@@ -0,0 +1,54 @@
# Блок 5. Интеграции: Plane, Gitea, LLM, Telegram
> Обзорный уровень; детали API, эндпоинтов и вебхуков — в
> [инженерном справочнике](../architecture/README.md) и [internals](../architecture/internals.md).
## Plane — управление задачами
- **Вход конвейера:** перевод задачи в статус «To Analyse» — единственная точка запуска
пайплайна. Вебхуки Plane (HMAC-подписанные) доставляют изменения задач.
- **Статусы = индикация, не управление** ([блок 2](tech-pipeline.md)): платформа сама
выставляет статусы доски, чтобы человек видел осмысленную картину; управляют конвейером
только машина стадий и три управляющих статуса (запуск, человеческие гейты, STOP).
- **Лейблы** — декларативные переключатели на задаче: `autoApprove` / `autoDeploy` (снятие
человеческих гейтов), `Bug` (багфикс-маршрут). Источник истины — Plane API: ошибка чтения
лейблов трактуется как «лейбла нет» (fail-safe — никогда не «авто» по ошибке).
- Платформа пишет в задачу комментарии о ходе работ (под ботами ролей) с кликабельными
ссылками на ветку/PR.
## Gitea — git, PR, CI
- **Каждая задача = одна ветка = один PR.** Ветка срезается от свежего `main`, работа идёт в
изолированном worktree, слияние — только после всех гейтов.
- **Слияние строго через PR-merge API** — платформенный инвариант: прямой push или
force-push в `main` запрещён всем акторам, включая агентов и сам движок.
- **Merge-актор устойчив к икотам:** транзиентные ошибки Gitea (таймаут, «try again later»)
ретраятся с backoff; необратимые — честный отказ без ложных повторов. Ветка, уже целиком
попавшая в `main`, распознаётся и не порождает мусорных PR.
- **CI (Gitea Actions)** гонит полный тест-сьют на каждый push ветки; зелёный CI — гейт
выхода из разработки (`check_ci_green`).
- Вебхуки Gitea (push, PR, статус CI) — второй источник событий конвейера.
## LLM — Claude CLI
- Агенты запускаются через **Claude CLI**: launcher собирает команду с промптом роли,
`--model` и эффортом, резолвленными **только из конфига** (таблица — в
[блоке агентов](tech-agents.md)); имя модели валидируется перед запуском.
- Запуск — в worktree ветки задачи: агент видит код своей задачи и ничего лишнего.
- Каждый запуск пишет в учёт стоимость и токены ([блок 7](tech-observability.md)).
## Telegram — живой трекер и алерты
- **Одна задача = одна живая карточка**: стадия, статус, модель/эффорт агента, стоимость,
честные метрики времени. Карточка обновляется «переездом вниз» чата (старая удаляется,
свежая приходит тихо); леджер карточек зачищает осиротевшие дубли.
- **Алерты** (упавший гейт, ожидание человека, инциденты) приходят отдельными сообщениями
с пингом.
- **Sidecar-watchdog шлёт в собственный канал** со своим ботом: наблюдатель за платформой
не зависит от её Telegram-стека.
---
*Развёртывание интеграций с нуля — [LITE_SETUP](../deployment/LITE_SETUP.md) /
[BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md); безопасность стыков —
[блок 6](tech-quality-security.md).*

54
docs/overview/tech-observability.md Normal file
View File

@@ -0,0 +1,54 @@
# Блок 7. Наблюдаемость и аналитика
> Машинный контракт метрик и устройство sidecar-наблюдателя — в
> [инженерном справочнике](../architecture/README.md) (разделы `/metrics` и sidecar-watchdog).
## Живая Telegram-карточка задачи
Каждая задача — одна карточка в Telegram, обновляемая на каждом событии:
- текущая стадия и Plane-статус (включая человеческие гейты — видно, когда задача ждёт вас);
- строка работающего агента: роль · модель · эффорт;
- стоимость задачи нарастающим итогом (токены/доллары по каждому запуску агента);
- честные метрики времени на финише: время агентов / время ожидания человека / общее
календарное — три независимые цифры, а не одна вводящая в заблуждение сумма;
- кликабельный номер задачи (ведёт в Plane), отметка багфикс-маршрута.
Карточка тихая (без пингов); пингуют только алерты: красный гейт, ожидание решения человека,
инциденты.
## Служебные страницы платформы
- **`GET /queue`** — человекочитаемый снимок всего конвейера: очередь и job'ы, состояние
serial gate и заморозок, авто-лейблы, багфикс-трек, coverage, журнал уроков, фоновые
демоны. Первая точка диагностики «что сейчас происходит».
- **`GET /metrics`** — машинный контракт для внешнего наблюдателя (версионированная схема):
health, возраст последних событий, счётчики сбоев.
- **`GET /health`** — живость процесса.
## Sidecar-watchdog: наблюдатель отделён от наблюдаемого
Отдельный контейнер-сторож опрашивает `/metrics` платформы и шлёт алерты в **собственный**
Telegram-канал со **своим** ботом. Падение платформы, зависание очереди или протухание
событий видно даже тогда, когда сама платформа уже не может пожаловаться.
## Журнал уроков
Машинная таблица отклонений конвейера: красные гейты, ложные блокировки слияния, исчерпание
ретраев, деградации после выкладки. Каждая запись — контекст (задача, стадия, агент, репо),
первопричина и предложение. Журнал — наблюдатель (никогда не влияет на продвижение задач) и
фундамент петли самообучения платформы: уроки доступны через API и копятся для будущего
ретроспективного анализа.
## Стоимость и аналитика по агентам
Каждый запуск агента фиксирует модель, эффорт, длительность и стоимость
([модель объектов](tech-data-model.md)). Это даёт ответы на вопросы «сколько стоит задача»,
«какая роль ест бюджет», «как изменилась экономика после смены модели» — по фактам, не по
ощущениям.
---
*Что делать при инцидентах и как устроен прод — `docs/operations/` (через
[инженерный справочник](../architecture/README.md)); бизнес-взгляд на наблюдаемость —
[business.md](business.md).*

103
docs/overview/tech-pipeline.md Normal file
View File

@@ -0,0 +1,103 @@
# Блок 2. Конвейер: стадии, гейты, маршруты
> Источник истины — карта переходов `STAGE_TRANSITIONS` в `src/stages.py` и реестр гейтов
> `QG_CHECKS` в `src/qg/checks.py`; перечень ниже сверяется с кодом структурным тестом
> (`tests/test_system_docs.py`). Норматив структуры доков конвейера —
> [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md).
## Схема конвейера
```
created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
↑ │
└──── REQUEST_CHANGES ─────┘ (откат на доработку, max 3)
```
Плюс системный сток **`cancelled`** — терминальное состояние отменённой задачи (кнопка STOP,
см. ниже). Это не ребро конвейера, а равноправный `done` сток: попасть в него можно с любой
стадии, выйти — нельзя.
## Стадии и гейты выхода
Гейт выхода (exit-гейт) — машинная проверка, без которой задача не покидает стадию:
| Стадия | Кто работает | Гейт выхода (имя в реестре) | Что проверяет |
|--------|--------------|------------------------------|----------------|
| `created` | — | — | вход конвейера (вебхук Plane) |
| `analysis` | analyst | `check_analysis_approved` | пакет аналитики полон И постановка одобрена человеком |
| `architecture` | architect | `check_architecture_done` | ADR / инфра-требования зафиксированы |
| `development` | developer | `check_ci_green` | CI на ветке задачи зелёный |
| `review` | reviewer | `check_reviewer_verdict` | машинный вердикт ревью: APPROVED |
| `testing` | tester | `check_tests_passed` | машинный вердикт тестера: PASS |
| `deploy-staging` | deployer | `check_staging_status` | репетиция выкладки на песочнице успешна |
| `deploy` | deployer / finalizer | `check_deploy_status` | прод-выкладка реально успешна |
| `done` | — | — | терминал |
| `cancelled` | — | — | терминал (сток отмены) |
## Под-гейты деплойного ребра — врезки, не стадии
На переходе `deploy-staging → deploy` исполняются четыре под-гейта в нормативном порядке
(security → merge → coverage → image-freshness):
1. `check_security_gate` — секреты/зависимости, вердикт из security-отчёта;
2. `check_branch_mergeable` — merge-gate: ветка догнана до свежего `main` (под merge-lease)
и мержабельна;
3. `check_coverage_gate` — покрытие тестами не ниже базовой линии/порога (baseline-ratchet);
4. `check_staging_image_fresh` — staging-образ собран из актуального кода.
Это **врезки в переход, а не стадии**: они не появляются в карте `STAGE_TRANSITIONS`, а
исполняются stage engine'ом внутри ребра. Провал любого из них — откат на доработку. На ребре
`deploy → done` аналогичная врезка merge-verify подтверждает, что код задачи реально слит в
`main` (слияние — только через PR-API Gitea, см. [интеграции](tech-integrations.md)).
## Откаты
`REQUEST_CHANGES` от ревьюера, проваленные тесты или красный под-гейт возвращают задачу на
стадию разработки с дословным перечнем замечаний. Лимит — 3 попытки подряд, дальше задача
останавливается и требует человека (анти-петля).
## Человеческие гейты и их снятие авто-лейблами
В штатном прогоне человек принимает ровно два решения:
- **Одобрение постановки** (на `analysis`): перевод задачи в статус Approved пропускает её
дальше;
- **Подтверждение прод-выкладки** (на `deploy`): отдельный статус **Confirm Deploy** — чтобы
привычный «approve» не выкатывал прод случайным кликом.
Оба решения можно снять декларативно — лейблами **autoApprove** / **autoDeploy** на задаче
(пакетный авто-режим). Снимается только ожидание человеческого сигнала: ни одна техническая
проверка не пропускается, autoDeploy физически не может выкатить непрошедшее под-гейты.
## Багфикс-маршрут
Задача с меткой **Bug** едет коротким путём: облегчённая аналитика (но полный пакет
документов) и пропуск стадии `architecture` — из аналитики сразу в разработку. Срезается
только аналитика/проектирование: **все гейты исполняются без изменений**. Сложный баг
эскалируется обратно в полный цикл.
## Последовательность внутри репозитория (serial gate)
Новая задача репозитория не входит в работу, пока не завершена более ранняя (FIFO): ветка
каждой задачи срезается от свежего `main`, уже содержащего код предшественника. Деградация
прода после выкладки замораживает репозиторий (freeze) до ручного разбора — следующие задачи
ждут.
## Отмена: STOP → `cancelled`
Перевод задачи в статус **STOP** останавливает агента, снимает job'ы с очереди, удаляет
рабочую ветку и worktree и переводит задачу в `cancelled`. Если задача в необратимой фазе
(идёт слияние/выкладка) — отмена откладывается и применяется после честного завершения шага.
STOP никогда не трогает `main` и прод-контейнер.
## Статусная модель Plane: индикация ≠ управление
Статусы в Plane — слой **индикации**: они показывают человеку осмысленную картину хода задачи,
но никогда не управляют конвейером (машина стадий — только `STAGE_TRANSITIONS`). Управляющих
статусов ровно три: запуск в работу, Approved/Confirm Deploy (человеческие гейты) и STOP
(отмена). Полная карта статусов — в [инженерном справочнике](../architecture/README.md).
---
*Кто работает на каждой стадии и что сдаёт — [агенты](tech-agents.md); как гейты читают
вердикты — [качество и безопасность](tech-quality-security.md).*

63
docs/overview/tech-quality-security.md Normal file
View File

@@ -0,0 +1,63 @@
# Блок 6. Качество и безопасность
> Реестр гейтов и их распределение по стадиям — [блок 2](tech-pipeline.md); механизм
> machine-verdict доков — [PIPELINE_DOCS §3](../_standards/PIPELINE_DOCS.md); машинный
> контракт стадий — [HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md).
## Философия Quality Gates
**Вердикты — машинные, никогда проза.** Гейт читает вердикт ТОЛЬКО из YAML-frontmatter
артефакта (ключи вида `verdict:`, `result:`, `staging_status:`, `deploy_status:`,
`security_status:` — имена и регистр неизменны байт-в-байт). Агент не может «уговорить» гейт
красивым отчётом: нет ключа — нет прохода. Парсинг frontmatter сведён к единому контракту
`src/frontmatter.py` — одна точка чтения для всех гейтов.
**Гейт ≠ маршрутизация.** Маршруты задач (багфикс-трек, авто-лейблы, serial gate) — свойство
планировщика; ни один из них не ослабляет ни одного гейта. Любая новая способность платформы
проектируется так, чтобы реестр гейтов и карта стадий не трогались.
**Анти-петля.** Откаты на доработку ограничены (max 3 подряд); инструментальные сбои
вспомогательных проверок по умолчанию fail-open с предупреждением (не запирают конвейер),
критичные проверки — fail-closed.
## Специальные гейты деплойного ребра
- **Security-гейт** (`check_security_gate`) — детерминированная (без LLM) проверка секретов и
зависимостей перед продом; вердикт — `security_status:` в отчёте задачи.
- **Coverage-гейт** (`check_coverage_gate`) — покрытие тестами измеряется на финальном коде
ветки; базовая линия по репозиторию растёт только вверх (ratchet при подтверждённом
слиянии) — покрытие не может деградировать молча.
Оба — врезки в переход ([блок 2](tech-pipeline.md)), включаются по конфигу и скоупятся по
репозиториям.
## Канон секретов
- Секреты живут **только в `.env`-файлах на хосте** и никогда не коммитятся; в git — только
канон-примеры с пустыми плейсхолдерами.
- Для нового хоста секреты **выпускаются свежими** (`scripts/gen_secrets.py`), боевые не
копируются.
- Анти-регресс машинный: структурные тесты сканируют исполняемый код на боевые хост-литералы,
а документацию — на секретоподобные значения; находка рвёт CI.
## Self-hosting-страховки
Платформа дорабатывает сама себя тем же конвейером — прод-инстанс при этом обслуживает и
другие проекты. Страховки:
- **Песочница обязательна:** перед прод-выкладкой платформы изменение репетируется на
staging-инстансе (отдельный порт/БД); guard не даёт staging-операциям коснуться прод-порта.
- **Прод-выкладка — только по явному человеческому статусу Confirm Deploy** (обычный approve
прод не выкатывает); деплой идёт детачнутым процессом с финализатором — честный исход
фиксируется даже при рестарте.
- **`main` неприкосновенен:** слияние только через PR-API, force-push запрещён всем.
- **Прод-контейнер никогда не роняется задачей**: агенты проверяют изменения локально и на
песочнице; рестарт прода — только штатным деплой-маршрутом.
- **Пост-деплой наблюдение:** после выкладки платформа следит за своим здоровьем; деградация
замораживает репозиторий и зовёт человека.
---
*Операционные детали и топология прода — `docs/operations/` (см.
[инженерный справочник](../architecture/README.md)); наблюдение за здоровьем —
[блок 7](tech-observability.md).*