From 6d798c01ef46ecdee348414fb2ea70a717d4b69f Mon Sep 17 00:00:00 2001 From: claude-bot Date: Thu, 11 Jun 2026 09:24:01 +0300 Subject: [PATCH] =?UTF-8?q?docs(overview):=20=D0=B2=D0=B8=D1=82=D1=80?= =?UTF-8?q?=D0=B8=D0=BD=D0=B0=20=D1=81=D0=B8=D1=81=D1=82=D0=B5=D0=BC=D1=8B?= =?UTF-8?q?=20docs/overview/=20=E2=80=94=20=D0=B1=D0=B8=D0=B7=D0=BD=D0=B5?= =?UTF-8?q?=D1=81+=D1=82=D0=B5=D1=85,=203=20=D0=B0=D1=83=D0=B4=D0=B8=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=B8=D0=B8,=20=D0=BF=D1=80=D0=B5=D0=B7=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20(ORCH-011)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Единая точка входа в документацию платформы (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 --- .gitignore | 3 + .openclaw/agents/reviewer.md | 8 +- .task-dev.md | 4 +- CHANGELOG.md | 5 + CLAUDE.md | 6 +- README.md | 3 + docs/PRODUCT_VISION.md | 3 + docs/overview/README.md | 89 +++++ docs/overview/business.md | 105 ++++++ docs/overview/presentation.md | 190 +++++++++++ docs/overview/tech-agents.md | 60 ++++ docs/overview/tech-architecture.md | 63 ++++ docs/overview/tech-data-model.md | 70 ++++ docs/overview/tech-integrations.md | 54 +++ docs/overview/tech-observability.md | 54 +++ docs/overview/tech-pipeline.md | 103 ++++++ docs/overview/tech-quality-security.md | 63 ++++ scripts/build_presentation.py | 192 +++++++++++ tests/test_agent_prompts_canon.py | 15 + tests/test_system_docs.py | 444 +++++++++++++++++++++++++ 20 files changed, 1528 insertions(+), 6 deletions(-) create mode 100644 docs/overview/README.md create mode 100644 docs/overview/business.md create mode 100644 docs/overview/presentation.md create mode 100644 docs/overview/tech-agents.md create mode 100644 docs/overview/tech-architecture.md create mode 100644 docs/overview/tech-data-model.md create mode 100644 docs/overview/tech-integrations.md create mode 100644 docs/overview/tech-observability.md create mode 100644 docs/overview/tech-pipeline.md create mode 100644 docs/overview/tech-quality-security.md create mode 100644 scripts/build_presentation.py create mode 100644 tests/test_system_docs.py diff --git a/.gitignore b/.gitignore index 51128ba..3134dc5 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,6 @@ data/staging/ # ORCH-103: Bundled-тираж — локальные клоны репо bundle-инсталляции (целевой хост); # deploy/bundled/.env и deploy/bundled/data покрыты неякорными `.env` / `data/` выше deploy/bundled/repos/ +# ORCH-011 (D5): собранная презентация (scripts/build_presentation.py) — бинарь .pptx +# в git не коммитится, источник истины — docs/overview/presentation.md +build/ diff --git a/.openclaw/agents/reviewer.md b/.openclaw/agents/reviewer.md index b17c22b..e79f569 100644 --- a/.openclaw/agents/reviewer.md +++ b/.openclaw/agents/reviewer.md @@ -57,7 +57,10 @@ tools: ограничения» (обзорная витрина проекта), README ДОЛЖЕН быть обновлён в том же PR — пункт снят или помечен закрытым с ORCH-ссылкой. Необновление обзорных доков → **finding ≥ P1**; если ограничение закрыто правкой `src/` без обновления README — это совпадает с P0 «`src/` изменён, - документация не обновлена». Это усиление трактовки оси, а не отдельная ось. + документация не обновлена». Это усиление трактовки оси, а не отдельная ось. Та же ось + покрывает **витрину системы** (ORCH-011): PR меняет функциональность, описанную в витрине + `docs/overview/` (стадии, гейты, агенты, интеграции, способности из `business.md`), а витрина + не обновлена → **finding ≥ P1** — расширение трактовки той же оси, не новая ось. @@ -77,6 +80,9 @@ frontmatter-вердиктом, см. ``). - ❌ PR закрыл пункт из `README.md` «Известные ограничения», но README не обновлён (пункт остался открытым) → ✅ требуй обновления обзорных доков — пункт снят либо помечен закрытым с ORCH-ссылкой; необновление обзорной витрины → **finding ≥ P1** (ORCH-079). +- ❌ PR меняет функциональность, описанную в витрине `docs/overview/` (стадии, гейты, агенты, + интеграции, способности из `business.md`), но витрина не обновлена → ✅ требуй обновления витрины + в том же PR; необновление → **finding ≥ P1** (расширение оси обзорных доков ORCH-079 — ORCH-011). **Severity:** - **P0 (blocker):** не реализовано требование ТЗ; нарушен ADR; критическая уязвимость; diff --git a/.task-dev.md b/.task-dev.md index 0a85c2a..ed13550 100644 --- a/.task-dev.md +++ b/.task-dev.md @@ -1,4 +1,4 @@ -Work item: ORCH-103 +Work item: ORCH-011 Repo: orchestrator -Branch: feature/ORCH-103-orch-10b-bundled-bootstrap +Branch: feature/ORCH-011- Stage: development \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index a41bc74..fb01fe1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,11 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **Витрина системы `docs/overview/`: бизнес + тех, маршруты трёх аудиторий, презентация** (ORCH-011, `docs`): единая точка входа в документацию платформы — новый docs-раздел `docs/overview/` (плоский каталог, 10 файлов, ADR-001 D1): индекс `README.md` (маршруты «Я заказчик / Я менеджер / Я разработчик» + норматив сопровождения «изменил функциональность → обнови витрину в том же PR»), бизнес-часть `business.md` (проблема → решение → что умеет фактически → ценность → 6 сценариев; без жаргона, цифры только с атрибуцией), 7 тех-блоков `tech-*.md` (архитектура со схемой потока, конвейер/гейты, агенты, модель объектов, интеграции, качество/безопасность, наблюдаемость; link-first — за деталями ссылки в golden sources, разрешённый дубль только машинно-сверяемый). **Docs+tests+dev-скрипт** (паттерн ORCH-102/103): `src/**`/`docker-compose.yml`/`Dockerfile`/`requirements*`/`STAGE_TRANSITIONS`/`QG_CHECKS`/machine-verdict/схема БД — ноль изменений. ADR: `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`, сквозной `adr-0039-system-overview-docs-canon.md`. + - **Презентация (D4/D5):** слайдо-источник `docs/overview/presentation.md` (16 слайдов в машинно-парсимой структуре «## Слайд N: …» + процедура сборки «команда + Проверка:») + dev-скрипт `scripts/build_presentation.py` (python-pptx, тёмный дизайн, редактируемый текст с точной кириллицей; чистый stdlib-парсер `parse_slides` + ленивый импорт pptx). Запуск только вне рантайма; `python-pptx` НЕ в прод-образе (машинный гард); собранный `.pptx` в git не коммитится — `build/` в `.gitignore`. + - **Анти-дрейф (D6):** новый структурный `tests/test_system_docs.py` (без сети/LLM/subprocess, паттерн `test_lite_setup_doc.py`) — 10 файлов витрины; маршруты/норматив; derive-сверки с кодом: стадии импортом `src.stages.STAGE_TRANSITIONS` (вкл. `deploy-staging`/`cancelled`, порядок цепочки), exit-гейты и под-гейты именами реестра `QG_CHECKS` в нормативном порядке security → merge → coverage → image-freshness (+ маркер «не стадии»), 6 агентов glob'ом промптов, таблица эффортов class-default'ами config (ORCH-41/81); валидность относительных ссылок + обязательные golden-source ссылки; полнотекстовый FORBIDDEN-скан (импорт из `test_no_host_hardcodes.py`) + секрет-эвристика + запрет вне-репозиторных путей; слайды каноническим парсером; `pptx` отсутствует в `requirements*`/`Dockerfile`; указатели README/CLAUDE/CHANGELOG. + - **Reviewer-ось (D7):** ось обзорных доков ORCH-079 в `.openclaw/agents/reviewer.md` точечно расширена на витрину (необновлённая витрина при изменении описанной в ней функциональности → finding ≥ P1; канон 52d байт-в-байт, только добавление внутрь существующих секций) + анти-регресс ассерт в `tests/test_agent_prompts_canon.py`; зеркальные правки правил №2/№6 `CLAUDE.md`. + - **Указатели (D8):** `README.md` — ссылка на витрину; `CLAUDE.md` — указатель в правиле №2 и строке «Структура»; `docs/PRODUCT_VISION.md` — врезка-ссылка «фактическое состояние — витрина» (vision не переписывается; расхождения vision↔код в витрину не переносятся — она строится от кода). - **ORCH-10b Bundled-тираж: весь стек одним комплектом + bootstrap-скрипт** (ORCH-103, `feat`): закрыт Type B эпика ORCH-10 — заказчик **без собственной инфраструктуры** получает конвейер «под ключ»: одна команда `docker compose -f deploy/bundled/docker-compose.yml up -d` поднимает весь стек (орк + watchdog + Gitea + зеркало upstream Plane CE ≈14 контейнеров), один прогон `scripts/bootstrap_bundle.py apply` доводит его до рабочего состояния. Рантайм байт-в-байт: `src/**`/корневой compose/`Dockerfile`/`STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД — ноль изменений (паттерн ORCH-009/102, kill-switch не нужен — активация только явным запуском оператора на целевом хосте). ADR: `docs/work-items/ORCH-103/06-adr/ADR-001-bundled-stack-compose-and-bootstrap.md`, сквозной `adr-0038-bundled-replication-canon.md`. - **Bundle-compose (D1–D4):** новый top-level каталог `deploy/` (дистрибутивы развёртывания); `deploy/bundled/docker-compose.yml` — один самодостаточный файл, project name `orchestrator-bundle` (узнаваемый префикс томов/контейнеров, по нему preflight детектирует «грязный хост»); `container_name` не пиннится (bundle и Lite не сталкиваются на одном хосте); staging-контура орка нет вовсе (self-hosting у заказчика = маршрут Lite). Все сторонние образы пиннованы неподвижными тегами (Plane CE v0.23.1 upstream-имена сервисов, Gitea 1.22.6, postgres/valkey/rabbitmq/minio). Сеть — одна bridge: машинный трафик строго сервис-DNS (`http://orchestrator:8500/webhook/plane|gitea`, `ORCH_GITEA_URL=http://gitea:3000`), наружу — только человеческие порты `BUNDLE_ORCH_PORT`/`BUNDLE_PLANE_PORT`/`BUNDLE_GITEA_HTTP_PORT`; postgres/redis/mq/minio не публикуются; мина Gitea закрыта `GITEA__webhook__ALLOWED_HOST_LIST=orchestrator`. Конфиг-канон — `deploy/bundled/.env.example` (только плейсхолдеры, ни одного дефолтного пароля; key-set-sync интерполяций держит тест); runtime-конфиг орка/watchdog — корневые `.env`/`.env.watchdog` (канон Lite 1:1, `env_file required: false` — первый `up` живёт до сборки конфига). - **Bootstrap (D5–D8):** `scripts/bootstrap_bundle.py` — python stdlib-only (модули платформы не импортируются, держится ast-сканом), режимы `plan` (дефолт, ноль мутаций) / `apply` / `verify`, step-движок check→ensure (повторный запуск = каскад skip, resume после manual-step = повторный запуск), exit-контракт 0/2/1. Шаги: preflight (fail-fast ДО мутаций: docker/compose, порты, RAM/диск, чистота хоста по префиксу) → секреты (webhook — **строго** субпроцессом `gen_secrets.py`; bundle-креды — stdlib `secrets`; существующие не перетираются без `--force-secrets`; значения не печатаются) → up+готовность (healthchecks + poll, migrator exit 0) → init Gitea полностью автоматом (`gitea admin user create`/`generate-access-token`; branch protection НЕ настраивается — норматив D10 ORCH-009/INV-4) → init Plane (честные manual-step c API-верификацией результата; workspace-webhook — ensure с fallback на manual-step) → онбординг sandbox-проекта **строго** `onboard_project.py apply+verify` (нулевой дрейф канона статусов/лейблов) → git-доступ агентов HTTP token-remote (ssh-контур не вводится) → сборка корневых `.env`/`.env.watchdog` (bootstrap — единственный писатель, права 600) → health/итоговая сводка PASS/FAIL. Delete-операций НЕТ вообще (D9): teardown — только документированная процедура. diff --git a/CLAUDE.md b/CLAUDE.md index 04f0592..94b8fd1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,7 @@ - `src/qg/checks.py` — Quality Gate проверки - `src/webhooks/` — приём вебхуков Plane/Gitea - `tests/` — pytest -- `docs/` — документация, ADR, work-items, operations +- `docs/` — документация, ADR, work-items, operations; **витрина системы — `docs/overview/`** (единая точка входа «бизнес + тех», ORCH-011) - `scripts/` — утилиты (staging_check.py, orchestrator-deploy-hook.sh) ## Конвейер (кратко; детали — docs/architecture/README.md) @@ -395,11 +395,11 @@ API → `manual-step` (fail-safe); **runbook** `docs/operations/ONBOARDING.md` ( ## Правила для агентов 1. Перед любым действием прочесть этот файл и `docs/architecture/README.md`. -2. **Документация = golden source наравне с кодом.** Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR (формат — `docs/_standards/PIPELINE_DOCS.md` §4). Структура номерных доков и шаблоны — `docs/_standards/PIPELINE_DOCS.md` + `docs/_templates/`. Обнови `CHANGELOG.md`. +2. **Документация = golden source наравне с кодом.** Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR (формат — `docs/_standards/PIPELINE_DOCS.md` §4). Структура номерных доков и шаблоны — `docs/_standards/PIPELINE_DOCS.md` + `docs/_templates/`. Обнови `CHANGELOG.md`. **Витрина системы `docs/overview/` (ORCH-011):** изменил функциональность платформы → обнови витрину в том же PR (какой файл какому классу изменений — таблица в индексе витрины); машинно-проверяемые факты витрины держит `tests/test_system_docs.py`. 3. Никогда не править артефакты других этапов. 4. Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ. 5. Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия. -6. **Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.** Это включает **обзорные доки** (ORCH-079, 52f — финал эпика 52): если PR закрывает пункт `README.md` «Известные ограничения», но README не обновлён → finding ≥P1 (витрина проекта не должна выдавать решённое за открытое). +6. **Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.** Это включает **обзорные доки** (ORCH-079, 52f — финал эпика 52): если PR закрывает пункт `README.md` «Известные ограничения», но README не обновлён → finding ≥P1 (витрина проекта не должна выдавать решённое за открытое). Та же ось покрывает витрину системы (ORCH-011): PR меняет функциональность, описанную в `docs/overview/`, а витрина не обновлена → finding ≥P1. 7. Не использовать `--no-verify` без явного одобрения Owner. 8. Секреты — только в `.env`/`.env.staging` на хосте, в гит НЕ коммитятся (канон — `.env.example`). 9. **Трассировка маркеров (ORCH-078, ORCH-52e):** правишь строку/блок с маркером `ORCH-NNN` → diff --git a/README.md b/README.md index 5f7bb1f..a2b1904 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # Multi-Agent Orchestrator > См. [CLAUDE.md](CLAUDE.md) (паспорт проекта) и [docs/architecture/README.md](docs/architecture/README.md) (архитектура). +> +> **Витрина системы — [docs/overview/](docs/overview/README.md)**: единая точка входа в документацию +> (бизнес + тех, 7 блоков, маршруты для заказчика / менеджера / разработчика, презентация). ORCH-011. FastAPI-сервис для оркестрации мульти-агентного пайплайна разработки. Принимает webhooks от Plane и Gitea, управляет жизненным циклом задач через Quality Gates, запускает Claude CLI агентов на каждой стадии. diff --git a/docs/PRODUCT_VISION.md b/docs/PRODUCT_VISION.md index c14233a..ecca064 100644 --- a/docs/PRODUCT_VISION.md +++ b/docs/PRODUCT_VISION.md @@ -4,6 +4,9 @@ **Версия:** 1.0 · **Дата:** 2026-06-04 · **Статус:** концепция развития +> **Фактическое текущее состояние платформы** (что уже умеет, как устроена) — витрина системы +> [docs/overview/](overview/README.md) (ORCH-011). Этот документ — vision: «куда идём». + --- ## 1. Зачем это (бизнес-взгляд) diff --git a/docs/overview/README.md b/docs/overview/README.md new file mode 100644 index 0000000..0ceeed0 --- /dev/null +++ b/docs/overview/README.md @@ -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).* diff --git a/docs/overview/business.md b/docs/overview/business.md new file mode 100644 index 0000000..5463e43 --- /dev/null +++ b/docs/overview/business.md @@ -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).* diff --git a/docs/overview/presentation.md b/docs/overview/presentation.md new file mode 100644 index 0000000..1577fbc --- /dev/null +++ b/docs/overview/presentation.md @@ -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 +``` + +Проверка: скрипт печатает `Собрано слайдов: → build/orchestrator-overview.pptx`, где +`` равно числу слайдов в этом файле — PASS; `ОШИБКА: …` — FAIL (текст подскажет причину). + +**Шаг 3. Открыть и проверить результат:** + +Откройте `build/orchestrator-overview.pptx` в PowerPoint/LibreOffice. Проверка: тема тёмная +(тёмный фон, светлый текст, акцентные заголовки), кириллица отображается точно, текст слайдов +выделяется и редактируется — PASS. Каталог `build/` в `.gitignore`: собранный бинарь в git +не попадает. + +--- + +*Нарратив слайдов опирается на [business.md](business.md); технические утверждения — на +тех-блоки витрины ([конвейер](tech-pipeline.md), [агенты](tech-agents.md)).* diff --git a/docs/overview/tech-agents.md b/docs/overview/tech-agents.md new file mode 100644 index 0000000..af5174e --- /dev/null +++ b/docs/overview/tech-agents.md @@ -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): пять обязательных секций в +нормативном порядке `` → `` → `` → `` → +``, запреты в формате «❌ X → ✅ Y», секция эскалации у решающих ролей. Каждый +агент эмитит единую frontmatter-схему в своих документах (work item, стадия, автор, статус, +дата, модель). Промпт читается из worktree в момент запуска — обновление промптов вступает в +силу со следующей задачи, без рестарта прода. + +Особенность: промпт `deployer` сознательно на английском (самый safety-critical — несёт +запреты self-hosting в видной рамке); остальные пять — на русском. + +## Человек как седьмая роль + +Человек не пишет артефакты конвейера, но принимает два решения, которые не делегированы +агентам: одобрение постановки (после `analyst`) и подтверждение прод-выкладки (перед финалом +работы `deployer`). Подробнее — [человеческие гейты](tech-pipeline.md). + +--- + +*Структуры документов, которые сдаёт каждая роль, — [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md); +скелеты — `docs/_templates/`.* diff --git a/docs/overview/tech-architecture.md b/docs/overview/tech-architecture.md new file mode 100644 index 0000000..a639087 --- /dev/null +++ b/docs/overview/tech-architecture.md @@ -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/-slug`) и собственном **worktree** — +изолированной рабочей копии репозитория. Агенты разных задач не видят незакоммиченную работу +друг друга; слияние в `main` происходит только через PR в Gitea после всех гейтов. + +--- + +*Подробнее: [компоненты и API](../architecture/README.md) · [внутренности и схема БД](../architecture/internals.md) · +следующий блок — [конвейер и стадии](tech-pipeline.md).* diff --git a/docs/overview/tech-data-model.md b/docs/overview/tech-data-model.md new file mode 100644 index 0000000..e3be005 --- /dev/null +++ b/docs/overview/tech-data-model.md @@ -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//) + └── Plane-проект ↔ git-репозиторий ↔ префикс задач +``` + +### Project — проект в реестре +Связка «Plane-проект ↔ git-репозиторий ↔ префикс задач» (например, `ORCH-`). Реестр живёт в +конфиге (`src/projects.py`): один инстанс платформы обслуживает несколько проектов; по +префиксу задачи платформа находит репозиторий и настройки. + +### Work-Item / Task — задача конвейера +Строка таблицы `tasks`: текущая **стадия** (`stage`), **маршрут** (`track`: полный или +багфикс), рабочая **ветка**, счётчики откатов, отметки отмены. Натуральные ключи — ID задачи +в Plane и человекочитаемый номер (`ORCH-NNN`). На каждой стадии задача накапливает +**артефакты** — номерные документы в `docs/work-items//` (от бизнес-запроса до +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).* diff --git a/docs/overview/tech-integrations.md b/docs/overview/tech-integrations.md new file mode 100644 index 0000000..f771c5a --- /dev/null +++ b/docs/overview/tech-integrations.md @@ -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).* diff --git a/docs/overview/tech-observability.md b/docs/overview/tech-observability.md new file mode 100644 index 0000000..27a513b --- /dev/null +++ b/docs/overview/tech-observability.md @@ -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).* diff --git a/docs/overview/tech-pipeline.md b/docs/overview/tech-pipeline.md new file mode 100644 index 0000000..dbbf6a7 --- /dev/null +++ b/docs/overview/tech-pipeline.md @@ -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).* diff --git a/docs/overview/tech-quality-security.md b/docs/overview/tech-quality-security.md new file mode 100644 index 0000000..f8ca251 --- /dev/null +++ b/docs/overview/tech-quality-security.md @@ -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).* diff --git a/scripts/build_presentation.py b/scripts/build_presentation.py new file mode 100644 index 0000000..6e4cf2f --- /dev/null +++ b/scripts/build_presentation.py @@ -0,0 +1,192 @@ +#!/usr/bin/env python3 +"""ORCH-011 (ADR-001 D4): сборка `.pptx` из слайдо-источника витрины. + +Источник истины — `docs/overview/presentation.md` (машинно-парсимая +слайдо-структура: `## Слайд N: Заголовок` + тезисы `- ...` + опциональная +строка `> Визуал: ...`). Скрипт собирает редактируемую PowerPoint-презентацию +в тёмном дизайне (D-1 Владельца): тёмный фон, светлый текст, один акцентный +цвет, системные шрифты с полной кириллицей. + +Канон (D4/D5): +- запуск ТОЛЬКО вне рантайма конвейера (host/dev venv, явный запуск человеком — + паттерн ORCH-009); `python-pptx` НЕ входит в requirements*/Dockerfile (NFR-2); +- `parse_slides` — чистая stdlib-функция БЕЗ импорта pptx: её импортирует + `tests/test_system_docs.py` (один парсер = один источник истины о формате); +- рендерер импортирует pptx ЛЕНИВО внутри `build_pptx`; +- дефолтный выход — `build/orchestrator-overview.pptx` (в `.gitignore`; + собранный бинарь в git НЕ коммитится — D5). + +Процедура запуска (канон «команда + Проверка:») — `docs/overview/presentation.md`, +раздел «Как собрать .pptx». +""" + +from __future__ import annotations + +import argparse +import re +from dataclasses import dataclass, field +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +DEFAULT_SOURCE = REPO_ROOT / "docs" / "overview" / "presentation.md" +DEFAULT_OUTPUT = REPO_ROOT / "build" / "orchestrator-overview.pptx" + +# Тёмная тема (D4): фон ~#1F1F2E, светлый текст, один акцент, приглушённый серый. +DARK_BG = "1F1F2E" +TEXT_MAIN = "F2F2F7" +ACCENT = "8AB4F8" +TEXT_MUTED = "9A9AAD" +FONT_NAME = "Calibri" # системный шрифт с полной кириллицей (D4) + +_SLIDE_RE = re.compile(r"^##\s+Слайд\s+(\d+)\s*:\s*(.+?)\s*$") +_BULLET_RE = re.compile(r"^-\s+(.+?)\s*$") +_VISUAL_RE = re.compile(r"^>\s*Визуал\s*:\s*(.+?)\s*$") +_ANY_HEADING_RE = re.compile(r"^#{1,6}\s+") + + +@dataclass +class Slide: + """Один слайд источника: номер, заголовок, тезисы, подпись визуала.""" + + number: int + title: str + bullets: list[str] = field(default_factory=list) + visual: str | None = None + + +def parse_slides(text: str) -> list[Slide]: + """Разобрать слайдо-источник в список :class:`Slide` (чистая, stdlib-only). + + Формат (D4): слайд открывается строкой ``## Слайд N: Заголовок``; его тезисы — + строки ``- ...``; опциональная подпись визуала — ``> Визуал: ...``. Любой + другой markdown-заголовок (например, раздел «Как собрать .pptx») завершает + текущий слайд — служебные разделы источника в слайды не попадают. + """ + slides: list[Slide] = [] + current: Slide | None = None + for line in text.splitlines(): + m = _SLIDE_RE.match(line) + if m: + current = Slide(number=int(m.group(1)), title=m.group(2)) + slides.append(current) + continue + if _ANY_HEADING_RE.match(line): + current = None # служебный раздел — не слайд + continue + if current is None: + continue + bullet = _BULLET_RE.match(line) + if bullet: + current.bullets.append(bullet.group(1)) + continue + visual = _VISUAL_RE.match(line) + if visual: + current.visual = visual.group(1) + return slides + + +def build_pptx(slides: list[Slide], output: Path) -> None: + """Собрать `.pptx` в тёмном дизайне из распарсенных слайдов. + + Импорт `pptx` — ленивый (D4): без установленного `python-pptx` модуль + остаётся импортируемым (нужно тестам), а сборка честно подсказывает + `pip install python-pptx`. Текст пишется настоящими редактируемыми + run'ами — кириллица не растрируется, слайды правятся руками. + """ + from pptx import Presentation + from pptx.dml.color import RGBColor + from pptx.util import Inches, Pt + + prs = Presentation() + prs.slide_width = Inches(13.333) # 16:9 + prs.slide_height = Inches(7.5) + blank_layout = prs.slide_layouts[6] + + for slide_def in slides: + slide = prs.slides.add_slide(blank_layout) + slide.background.fill.solid() + slide.background.fill.fore_color.rgb = RGBColor.from_string(DARK_BG) + + title_box = slide.shapes.add_textbox( + Inches(0.6), Inches(0.45), prs.slide_width - Inches(1.2), Inches(1.2) + ) + title_tf = title_box.text_frame + title_tf.word_wrap = True + run = title_tf.paragraphs[0].add_run() + run.text = slide_def.title + run.font.size = Pt(34) + run.font.bold = True + run.font.name = FONT_NAME + run.font.color.rgb = RGBColor.from_string(ACCENT) + + body_box = slide.shapes.add_textbox( + Inches(0.8), Inches(1.85), prs.slide_width - Inches(1.6), Inches(4.4) + ) + body_tf = body_box.text_frame + body_tf.word_wrap = True + for i, bullet in enumerate(slide_def.bullets): + para = body_tf.paragraphs[0] if i == 0 else body_tf.add_paragraph() + run = para.add_run() + run.text = f"• {bullet}" + run.font.size = Pt(20) + run.font.name = FONT_NAME + run.font.color.rgb = RGBColor.from_string(TEXT_MAIN) + para.space_after = Pt(10) + + if slide_def.visual: + cap_box = slide.shapes.add_textbox( + Inches(0.8), Inches(6.55), prs.slide_width - Inches(1.6), Inches(0.6) + ) + cap_tf = cap_box.text_frame + cap_tf.word_wrap = True + run = cap_tf.paragraphs[0].add_run() + run.text = f"Визуал: {slide_def.visual}" + run.font.size = Pt(13) + run.font.italic = True + run.font.name = FONT_NAME + run.font.color.rgb = RGBColor.from_string(TEXT_MUTED) + + output.parent.mkdir(parents=True, exist_ok=True) + prs.save(str(output)) + + +def main(argv: list[str] | None = None) -> int: + """CLI: распарсить источник, собрать `.pptx`, напечатать число слайдов.""" + parser = argparse.ArgumentParser( + description="Сборка docs/overview/presentation.md -> .pptx (тёмный дизайн, ORCH-011 D4)." + ) + parser.add_argument( + "--source", + type=Path, + default=DEFAULT_SOURCE, + help=f"слайдо-источник (default: {DEFAULT_SOURCE.relative_to(REPO_ROOT)})", + ) + parser.add_argument( + "--out", + type=Path, + default=DEFAULT_OUTPUT, + help=f"выходной .pptx (default: {DEFAULT_OUTPUT.relative_to(REPO_ROOT)})", + ) + args = parser.parse_args(argv) + + if not args.source.is_file(): + print(f"ОШИБКА: источник не найден: {args.source}") + return 1 + slides = parse_slides(args.source.read_text(encoding="utf-8")) + if not slides: + print(f"ОШИБКА: в {args.source} не найдено ни одного слайда (формат: '## Слайд N: ...')") + return 1 + try: + build_pptx(slides, args.out) + except ImportError: + print( + "ОШИБКА: python-pptx не установлен. Сборка выполняется в одноразовом " + "dev-venv ВНЕ прод-образа (NFR-2): pip install python-pptx" + ) + return 1 + print(f"Собрано слайдов: {len(slides)} → {args.out}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_agent_prompts_canon.py b/tests/test_agent_prompts_canon.py index c364a73..06fdb5f 100644 --- a/tests/test_agent_prompts_canon.py +++ b/tests/test_agent_prompts_canon.py @@ -282,6 +282,21 @@ def test_reviewer_carries_overview_docs_axis(): ) +def test_reviewer_overview_axis_covers_system_showcase(): + """ORCH-011 (ADR-001 D7): the ORCH-079 overview-docs axis explicitly extends + to the system showcase `docs/overview/` — a PR changing functionality described + in the showcase without updating it must yield a finding >= P1. Guarded here + because the axis history (ORCH-079) shows overview docs rot unless named + explicitly in the prompt.""" + text = _read("reviewer") + assert "docs/overview/" in text, ( + "reviewer.md does not extend the overview-docs axis to the docs/overview/ showcase" + ) + assert "ORCH-011" in text, ( + "reviewer.md does not anchor the showcase extension to ORCH-011" + ) + + # --------------------------------------------------------------------------- # # ORCH-092 (epilogue of epic ORCH-52): prompt audit of the 6 agents — # de-hardcode date/model, gate-name parity, escalation sections, dead-line diff --git a/tests/test_system_docs.py b/tests/test_system_docs.py new file mode 100644 index 0000000..248cd6a --- /dev/null +++ b/tests/test_system_docs.py @@ -0,0 +1,444 @@ +"""ORCH-011 (FR-7 / AC-1…AC-12): анти-дрейф контур витрины системы `docs/overview/`. + +Структурные проверки витрины (ADR-001 D6, образец — `tests/test_lite_setup_doc.py` / +`test_bundled_setup_doc.py`): 10 файлов D1 существуют и непусты (TC-01); индекс несёт +маршруты трёх аудиторий и норматив сопровождения, из него достижимы все части (TC-02); +бизнес-часть несёт 5 обязательных смысловых разделов и ≥5 сценариев (AC-2); +карта стадий и гейтов derive-сверяется импортом `src.stages.STAGE_TRANSITIONS` и +`src.qg.checks.QG_CHECKS` — не статичным списком (TC-03/TC-04, паттерн ORCH-091); +полнота агентов derive из glob `.openclaw/agents/*.md`, таблица эффортов — из +class-default'ов `src.config.Settings` (TC-05, ORCH-41/81); все относительные ссылки +резолвятся, обязательные golden-source ссылки AC-6 присутствуют (TC-06); гигиена — +полнотекстовый FORBIDDEN-скан (импорт из `tests/test_no_host_hardcodes.py`, не копия) + +секрет-эвристика + запрет вне-репозиторных путей (TC-07, AC-12); слайдо-источник +валидируется каноническим парсером `parse_slides` из `scripts/build_presentation.py` +(TC-08, один парсер — один источник истины о формате, прецедент +`test_bootstrap_script.py`); NFR-2 машинно: `pptx` отсутствует в `requirements*` / +`Dockerfile` (TC-09); указатели README/CLAUDE/CHANGELOG обновлены (TC-10). +Детерминировано: без сети/LLM/subprocess. Новый QG НЕ регистрируется (ТЗ §6) — +модуль исполняется существующими гейтами (`check_ci_green` / `check_tests_passed`). +""" + +import ast +import importlib.util +import re +import sys +from pathlib import Path + +from src.config import Settings +from src.qg.checks import QG_CHECKS +from src.stages import STAGE_TRANSITIONS + +# Один источник истины запрещённых боевых литералов (ORCH-101 AC-7). +from tests.test_no_host_hardcodes import FORBIDDEN + +REPO_ROOT = Path(__file__).resolve().parents[1] +OVERVIEW = REPO_ROOT / "docs" / "overview" +AGENTS_DIR = REPO_ROOT / ".openclaw" / "agents" +BUILD_SCRIPT = REPO_ROOT / "scripts" / "build_presentation.py" + +# Нормативный состав витрины (ADR-001 D1: плоский каталог, 10 файлов). +SHOWCASE_FILES: tuple[str, ...] = ( + "README.md", + "business.md", + "tech-architecture.md", + "tech-pipeline.md", + "tech-agents.md", + "tech-data-model.md", + "tech-integrations.md", + "tech-quality-security.md", + "tech-observability.md", + "presentation.md", +) + +# Под-гейты ребра deploy-staging→deploy: фактические имена реестра QG_CHECKS в +# нормативном порядке security → merge → coverage → image-freshness (adr-0029). +SUBGATES_IN_ORDER: tuple[str, ...] = ( + "check_security_gate", + "check_branch_mergeable", + "check_coverage_gate", + "check_staging_image_fresh", +) + +# Обязательные golden-source ссылки витрины (AC-6), repo-relative POSIX. +MANDATORY_LINK_TARGETS: tuple[str, ...] = ( + "docs/architecture/README.md", + "docs/architecture/internals.md", + "docs/_standards/PIPELINE_DOCS.md", + "docs/_standards/HANDOFF_PROTOCOL.md", + "docs/architecture/adr", + "docs/deployment/LITE_SETUP.md", + "docs/deployment/BUNDLED_SETUP.md", + "docs/PRODUCT_VISION.md", + "CLAUDE.md", +) + +# Маркдаун-ссылка: [текст](цель) — цель без пробелов. +_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)") + +# Секрет-эвристика (паттерн ORCH-102 D8): hex-run >= 32 / чистый alnum-run >= 40. +_SECRET_HEX_RE = re.compile(r"\b[0-9a-fA-F]{32,}\b") +_SECRET_ALNUM_RE = re.compile(r"\b[A-Za-z0-9]{40,}\b") + + +# --------------------------------------------------------------------------- +# helpers +# --------------------------------------------------------------------------- +def _read(name: str) -> str: + """Текст файла витрины; падает с внятным сообщением, если файла нет.""" + path = OVERVIEW / name + assert path.is_file(), f"docs/overview/{name} отсутствует (D1 / AC-1)" + return path.read_text(encoding="utf-8") + + +def _stage_token_re(stage: str) -> re.Pattern: + """Регэксп стадии с границами: `deploy` не матчится внутри `deploy-staging`, + `review` — внутри `reviewer`/`12-review.md` (дефис и \\w исключены с обеих сторон).""" + return re.compile(rf"(? int: + """Позиция первого вхождения стадии (с границами) или -1.""" + m = _stage_token_re(stage).search(text) + return m.start() if m else -1 + + +def _main_chain() -> list[str]: + """Основная цепочка стадий, derive проходом по `next` от created (не статика).""" + chain: list[str] = [] + stage = "created" + while stage is not None: + chain.append(stage) + stage = STAGE_TRANSITIONS[stage]["next"] + return chain + + +def _rel_link_targets(name: str) -> list[str]: + """Относительные цели md-ссылок файла (внешние URL и якоря — мимо).""" + targets: list[str] = [] + for target in _LINK_RE.findall(_read(name)): + if target.startswith(("http://", "https://", "mailto:", "#")): + continue + targets.append(target.split("#", 1)[0]) + return [t for t in targets if t] + + +def _load_build_module(): + """Импорт scripts/build_presentation.py по файлу (прецедент test_bootstrap_script): + top-level скрипта обязан быть stdlib-only, иначе сам импорт здесь упадёт.""" + spec = importlib.util.spec_from_file_location("build_presentation", BUILD_SCRIPT) + mod = importlib.util.module_from_spec(spec) + # Регистрация в sys.modules ДО exec: dataclass резолвит строковые аннотации + # (`from __future__ import annotations`) через sys.modules[cls.__module__]. + sys.modules[spec.name] = mod + spec.loader.exec_module(mod) + return mod + + +# --------------------------------------------------------------------------- +# TC-01: все 10 файлов витрины существуют и непусты (AC-1 / D1). +# --------------------------------------------------------------------------- +def test_all_showcase_files_exist_and_nonempty(): + for name in SHOWCASE_FILES: + text = _read(name).strip() + assert len(text) > 300, f"docs/overview/{name} подозрительно пуст (D1)" + + +# --------------------------------------------------------------------------- +# TC-02: индекс — маршруты 3 аудиторий, норматив, достижимость всех частей (AC-1/8/9). +# --------------------------------------------------------------------------- +def test_index_carries_three_audience_routes(): + text = _read("README.md") + for route in ("Я заказчик", "Я менеджер", "Я разработчик"): + assert route in text, f"маршрут {route!r} отсутствует в индексе (FR-5 / AC-8)" + + +def test_index_carries_maintenance_normative(): + text = _read("README.md") + assert "в том же PR" in text, ( + "норматив сопровождения «изменил функциональность → обнови витрину " + "в том же PR» отсутствует в индексе (FR-6 / AC-9)" + ) + + +def test_index_links_reach_every_showcase_part(): + targets = {t.removeprefix("./") for t in _rel_link_targets("README.md")} + for name in SHOWCASE_FILES[1:]: + assert name in targets, ( + f"{name} недостижим из индекса по относительной ссылке (AC-1)" + ) + + +# --------------------------------------------------------------------------- +# TC-03: бизнес-часть — 5 обязательных разделов + >=5 сценариев (AC-2). +# --------------------------------------------------------------------------- +def test_business_part_has_five_mandatory_sections(): + text = _read("business.md") + for marker in ("## Проблема", "## Решение", "Что умеет", "## Ценность", "## Сценарии"): + assert marker in text, f"бизнес-раздел {marker!r} отсутствует (FR-2 / AC-2)" + + +def test_business_part_has_at_least_five_scenarios(): + text = _read("business.md") + count = text.count("### Сценарий") + assert count >= 5, f"в business.md {count} сценариев, требуется >= 5 (FR-2 / AC-2)" + + +# --------------------------------------------------------------------------- +# TC-04: 7 тех-блоков присутствуют (через TC-01) + схема потока в блоке 1 (AC-3). +# --------------------------------------------------------------------------- +def test_architecture_block_carries_flow_diagram(): + text = _read("tech-architecture.md") + fenced = re.findall(r"```[^\n]*\n(.*?)```", text, flags=re.DOTALL) + assert fenced, "tech-architecture.md не несёт ни одного fenced-блока со схемой (AC-3)" + flow = [b for b in fenced if ("вебхук" in b.lower() or "webhook" in b.lower()) and "→" in b] + assert flow, ( + "схема потока «вебхук → очередь → агент → гейт → переход» отсутствует " + "в tech-architecture.md (FR-3.1 / AC-3)" + ) + + +# --------------------------------------------------------------------------- +# TC-05 (план TC-05): карта стадий = код, derive из STAGE_TRANSITIONS (AC-4). +# --------------------------------------------------------------------------- +def test_every_stage_from_code_is_mentioned_in_pipeline_doc(): + text = _read("tech-pipeline.md") + missing = [s for s in STAGE_TRANSITIONS if _first_stage_pos(text, s) == -1] + assert not missing, ( + f"стадии из src.stages.STAGE_TRANSITIONS отсутствуют в tech-pipeline.md " + f"(AC-4): {missing}" + ) + + +def test_main_chain_order_in_pipeline_doc_matches_code(): + text = _read("tech-pipeline.md") + chain = _main_chain() + positions = [_first_stage_pos(text, s) for s in chain] + assert -1 not in positions, "стадия основной цепочки не найдена в tech-pipeline.md" + assert positions == sorted(positions), ( + f"порядок первых вхождений стадий {chain} в tech-pipeline.md противоречит " + f"коду (AC-4): позиции {positions}" + ) + + +# --------------------------------------------------------------------------- +# TC-06 (план TC-06): гейты = код; под-гейты в нормативном порядке (AC-4). +# --------------------------------------------------------------------------- +def test_every_exit_gate_from_code_is_named_in_pipeline_doc(): + text = _read("tech-pipeline.md") + exit_gates = {t["qg"] for t in STAGE_TRANSITIONS.values() if t["qg"]} + missing = sorted(g for g in exit_gates if g not in text) + assert not missing, f"exit-гейты рёбер не названы в tech-pipeline.md (AC-4): {missing}" + + +def test_no_invented_gate_names_anywhere_in_showcase(): + """Каждое упомянутое имя check_* существует в реестре QG_CHECKS (анти-выдумка).""" + for name in SHOWCASE_FILES: + mentioned = set(re.findall(r"check_[a-z_]+[a-z]", _read(name))) + unknown = sorted(mentioned - set(QG_CHECKS)) + assert not unknown, ( + f"docs/overview/{name} упоминает несуществующие гейты (AC-4): {unknown}" + ) + + +def test_subgates_in_normative_order_and_marked_as_insets(): + text = _read("tech-pipeline.md") + for gate in SUBGATES_IN_ORDER: + assert gate in QG_CHECKS, f"под-гейт {gate} исчез из реестра QG_CHECKS" + positions = [text.find(g) for g in SUBGATES_IN_ORDER] + assert -1 not in positions, ( + f"под-гейт ребра deploy-staging→deploy не назван в tech-pipeline.md: " + f"{[g for g, p in zip(SUBGATES_IN_ORDER, positions) if p == -1]}" + ) + assert positions == sorted(positions), ( + "под-гейты идут не в нормативном порядке security → merge → coverage → " + "image-freshness (adr-0029 / AC-4)" + ) + assert "не стадии" in text, ( + "tech-pipeline.md обязан явно помечать под-гейты как врезки в переход, " + "«не стадии» (AC-4)" + ) + + +# --------------------------------------------------------------------------- +# TC-07 (план TC-07): полнота агентов derive из glob; эффорты = config (AC-5). +# --------------------------------------------------------------------------- +def test_every_agent_prompt_stem_is_covered(): + stems = sorted(p.stem for p in AGENTS_DIR.glob("*.md")) + assert stems, ".openclaw/agents/*.md не найдены — glob сломан" + text = _read("tech-agents.md") + missing = [s for s in stems if s not in text] + assert not missing, f"роли из .openclaw/agents/ не описаны в tech-agents.md: {missing}" + + +def test_effort_table_matches_config_class_defaults(): + """Таблица модель/эффорт сходится с class-default'ами Settings (ORCH-41/81).""" + text = _read("tech-agents.md") + table_rows = [ln for ln in text.splitlines() if ln.strip().startswith("|")] + assert table_rows, "tech-agents.md не несёт таблицы модель/эффорт (AC-5)" + model_default = Settings.model_fields["agent_model_default"].default + assert model_default in text, ( + f"дефолтная модель {model_default!r} (config) не упомянута в tech-agents.md" + ) + effort_default = Settings.model_fields["agent_effort_default"].default + for stem in sorted(p.stem for p in AGENTS_DIR.glob("*.md")): + fld = Settings.model_fields.get(f"agent_effort_{stem}") + effort = (fld.default if fld else "") or effort_default + role_rows = [ln for ln in table_rows if stem in ln] + assert role_rows, f"строка таблицы для роли {stem!r} отсутствует (AC-5)" + assert any(f"`{effort}`" in ln for ln in role_rows), ( + f"эффорт роли {stem!r} в таблице разъехался с config " + f"(ожидается `{effort}`, ORCH-81)" + ) + + +# --------------------------------------------------------------------------- +# TC-08 (план TC-08/TC-09): валидность ссылок + обязательные golden sources (AC-6). +# --------------------------------------------------------------------------- +def test_all_relative_links_resolve_to_existing_files(): + broken: list[str] = [] + for name in SHOWCASE_FILES: + for target in _rel_link_targets(name): + if not (OVERVIEW / target).resolve().exists(): + broken.append(f"{name}: {target}") + assert not broken, "битые относительные ссылки витрины (AC-6):\n" + "\n".join(broken) + + +def test_mandatory_golden_source_links_present(): + resolved: set[str] = set() + for name in SHOWCASE_FILES: + for target in _rel_link_targets(name): + path = (OVERVIEW / target).resolve() + if path.exists(): + resolved.add(path.relative_to(REPO_ROOT).as_posix()) + missing = [t for t in MANDATORY_LINK_TARGETS if t not in resolved] + assert not missing, f"обязательные ссылки на golden sources отсутствуют (AC-6): {missing}" + + +def test_no_out_of_repo_references(): + """AC-12: витрина самодостаточна — никаких ссылок на вне-репозиторные пути.""" + for name in SHOWCASE_FILES: + text = _read(name) + for needle in ("tasks/", "memory/"): + assert needle not in text, ( + f"docs/overview/{name} ссылается на вне-репозиторный путь " + f"{needle!r} (AC-12)" + ) + + +# --------------------------------------------------------------------------- +# TC-09 (план TC-13): гигиена — FORBIDDEN-скан полнотекстом + секрет-эвристика. +# --------------------------------------------------------------------------- +def test_showcase_carries_no_forbidden_host_literals(): + """Полнотекстовый скан (шире fenced-скана ORCH-102 — обоснование ADR D6).""" + offenders = [ + f"{name}: {literal!r}" + for name in SHOWCASE_FILES + for literal in FORBIDDEN + if literal in _read(name) + ] + assert not offenders, ( + "боевые хост-литералы в витрине (NFR-3 / AC-11):\n" + "\n".join(offenders) + ) + + +def test_showcase_carries_no_secret_like_values(): + offenders = [] + for name in SHOWCASE_FILES: + for rx in (_SECRET_HEX_RE, _SECRET_ALNUM_RE): + m = rx.search(_read(name)) + if m is not None: + offenders.append(f"{name}: {m.group(0)[:16]}…") + assert not offenders, ( + "секретоподобные значения в витрине (NFR-3):\n" + "\n".join(offenders) + ) + + +def test_secret_heuristic_is_not_evergreen(): + """Негативный самочек (паттерн ORCH-101/102): эвристика реально ловит.""" + assert _SECRET_HEX_RE.search("token=" + "0f" * 20) is not None + assert _SECRET_ALNUM_RE.search("bot" + "Q7" * 25) is not None + assert _SECRET_HEX_RE.search("обычный текст витрины 8500/8501") is None + assert _SECRET_ALNUM_RE.search("`check_staging_image_fresh` и `STAGE_TRANSITIONS`") is None + + +# --------------------------------------------------------------------------- +# TC-10 (план TC-10): слайдо-источник через канонический парсер (AC-7 / D4). +# --------------------------------------------------------------------------- +def test_build_script_toplevel_imports_are_stdlib_only(): + """Ленивый импорт pptx (D4): top-level скрипта не тянет python-pptx.""" + tree = ast.parse(BUILD_SCRIPT.read_text(encoding="utf-8")) + top_imports: set[str] = set() + for node in tree.body: + if isinstance(node, ast.Import): + top_imports.update(alias.name.split(".")[0] for alias in node.names) + elif isinstance(node, ast.ImportFrom): + top_imports.add((node.module or "").split(".")[0]) + assert "pptx" not in top_imports, ( + "scripts/build_presentation.py импортирует pptx на top-level — " + "parse_slides обязан работать без python-pptx (D4)" + ) + + +def test_presentation_source_parses_with_canonical_parser(): + mod = _load_build_module() + slides = mod.parse_slides(_read("presentation.md")) + assert len(slides) >= 12, ( + f"слайдов {len(slides)}, требуется >= 12 (FR-4: ориентир 14–18)" + ) + assert [s.number for s in slides] == list(range(1, len(slides) + 1)), ( + "нумерация слайдов не сквозная с 1 (D4)" + ) + for s in slides: + assert s.title.strip(), f"слайд {s.number}: пустой заголовок" + assert s.bullets, f"слайд {s.number}: ни одного тезиса (D4: 3–6 тезисов)" + + +def test_presentation_covers_mandatory_narrative_bits(): + low = _read("presentation.md").lower() + for bit in ("проблем", "решени", "конвейер", "сценари", "тираж", "статус"): + assert bit in low, f"нормативный бит нарратива {bit!r} отсутствует (FR-4 / AC-7)" + + +def test_presentation_carries_reproducible_build_procedure(): + text = _read("presentation.md") + assert "build_presentation.py" in text, ( + "процедура сборки .pptx не ссылается на скрипт (AC-7)" + ) + assert "Проверка" in text, ( + "процедура сборки не несёт явных маркеров «Проверка:» (канон LITE_SETUP)" + ) + + +# --------------------------------------------------------------------------- +# TC-11 (план TC-11): NFR-2 машинно — pptx не в прод-образе. +# --------------------------------------------------------------------------- +def test_no_pptx_dependency_in_prod_image(): + files = sorted(REPO_ROOT.glob("requirements*")) + [REPO_ROOT / "Dockerfile"] + assert files, "requirements*/Dockerfile не найдены — скан пуст" + offenders = [ + p.name for p in files if "pptx" in p.read_text(encoding="utf-8").lower() + ] + assert not offenders, ( + f"зависимость генерации презентации попала в прод-образ (NFR-2): {offenders}" + ) + + +# --------------------------------------------------------------------------- +# TC-12 (план TC-12): указатели репо — README / CLAUDE.md / CHANGELOG (AC-9/AC-11). +# --------------------------------------------------------------------------- +def test_repo_readme_links_overview(): + assert "docs/overview/" in (REPO_ROOT / "README.md").read_text(encoding="utf-8"), ( + "README.md не ссылается на витрину docs/overview/ (AC-11)" + ) + + +def test_claude_md_carries_overview_pointer_and_normative(): + text = (REPO_ROOT / "CLAUDE.md").read_text(encoding="utf-8") + assert "docs/overview/" in text, "CLAUDE.md не несёт указатель на витрину (AC-9)" + + +def test_changelog_has_orch_011_entry(): + assert "ORCH-011" in (REPO_ROOT / "CHANGELOG.md").read_text(encoding="utf-8"), ( + "CHANGELOG.md не несёт docs:-записи по ORCH-011 (AC-11)" + )