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/architecture/README.md b/docs/architecture/README.md index aaeb882..1a50dfb 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -245,6 +245,27 @@ Type B). Анти-дрейф — `tests/test_bundle_compose.py` / `test_bundled_ [adr-0038](adr/adr-0038-bundled-replication-canon.md), детально — `docs/work-items/ORCH-103/06-adr/ADR-001-bundled-stack-compose-and-bootstrap.md`. +## Витрина системы `docs/overview/` (ORCH-011 — design) + +Единая точка входа «бизнес + тех» для трёх аудиторий (заказчик / менеджер / разработчик) — +новый docs-раздел **`docs/overview/`** (семантика разделов: `overview/` — «что это за система +и как устроена», `architecture/` — инженерный справочник, `deployment/` — «как развернуть у +себя», `operations/` — «как эксплуатировать наш прод»). Состав — плоский каталог, 10 файлов: +индекс `README.md` (маршруты 3 аудиторий + норматив сопровождения), `business.md` +(бизнес-уровень без жаргона), 7 × `tech-*.md` (= 7 блоков: архитектура / конвейер / агенты / +модель объектов / интеграции / качество-безопасность / наблюдаемость), `presentation.md` +(слайдо-источник). **Link-first:** витрина ссылается на golden sources (этот README, internals, +стандарты, ADR), не форкает их; разрешённый дубль — только машинно-сверяемый тестом факт +(стадии/гейты/агенты — derive-тестами из `STAGE_TRANSITIONS`/`QG_CHECKS`/glob промптов). +**Канон презентации:** `.pptx` (тёмный дизайн) собирается из `presentation.md` dev-скриптом +`scripts/build_presentation.py` (python-pptx, запуск только вне рантайма; зависимость в +прод-образ не попадает — машинный гард); **собранный бинарь в git не коммитится**. **Норматив +сопровождения (кросс-каттинг):** «изменил функциональность → обнови витрину в том же PR»; +reviewer-ось обзорных доков (ORCH-079) расширена на витрину (finding ≥ P1). Анти-дрейф — +структурный `tests/test_system_docs.py` (паттерн `test_lite_setup_doc.py`); новый QG не +вводится, рантайм байт-в-байт. Подробнее: [adr-0039](adr/adr-0039-system-overview-docs-canon.md), +детально — `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`. + ## Конвейер и Quality Gates ``` diff --git a/docs/architecture/adr/adr-0039-system-overview-docs-canon.md b/docs/architecture/adr/adr-0039-system-overview-docs-canon.md new file mode 100644 index 0000000..d4b350b --- /dev/null +++ b/docs/architecture/adr/adr-0039-system-overview-docs-canon.md @@ -0,0 +1,95 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# adr-0039: Витрина системы `docs/overview/` — единая точка входа (бизнес + тех) и канон презентации (ORCH-011) + +## Статус +Proposed + +## Контекст + +Документация платформы богатая, но фрагментированная: паспорт `CLAUDE.md` (реестр доработок), +тех-витрина `README.md`, vision `docs/PRODUCT_VISION.md`, инженерный справочник +`docs/architecture/` (~1246 строк + internals), 38 сквозных ADR, стандарты, операционные и +deployment-доки. Единой точки входа «бизнес + тех» для трёх аудиторий (заказчик / менеджер / +разработчик) нет; презентацию о возможностях собирать не из чего. С тиражируемостью +(ORCH-101/102/103) появился внешний читатель. Решения Владельца: слайды PowerPoint в тёмном +дизайне; единое место — `docs/`; витрина поддерживается актуальной. + +Живые доказательства проблемы в самом репо: схема конвейера в `PRODUCT_VISION.md` §2 устарела +(нет `deploy-staging`/`cancelled`); `docs/PRODUCT_VISION.pptx` закоммичен **без пути генерации** +(невоспроизводим). Reviewer-ось обзорных доков (ORCH-079, adr-0023) по букве привязана к +`README.md` «Известные ограничения» — новую витрину не покрывает. + +Сквозной характер: вводится новый docs-раздел с нормативом сопровождения, обязательным для +**всех будущих функциональных PR**, расширяется reviewer-ось и фиксируется канон +презентационных артефактов. Детальный пакет решений (D1…D9, исходы OQ-1…OQ-5) — work-item ADR: +`docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`. + +## Решение + +1. **Новый docs-раздел `docs/overview/` — витрина системы.** Семантика разделов после ORCH-011: + `overview/` — «что это за система и как устроена» (вход для любой аудитории), `architecture/` + — инженерный справочник, `deployment/` — «как развернуть у себя», `operations/` — «как + эксплуатировать наш прод», `_standards/` — нормативы агентов. Состав — плоский каталог, + 10 файлов: индекс `README.md` (точка входа, 3 маршрута аудиторий, норматив сопровождения), + `business.md` (бизнес-уровень: проблема → решение → способности → ценность → сценарии; без + жаргона; числа только с подтверждением), 7 файлов `tech-*.md` = 7 блоков контент-карты + (архитектура / конвейер / агенты / модель объектов / интеграции / качество-безопасность / + наблюдаемость), `presentation.md` (слайдо-источник). +2. **Link-first, канон не форкается:** витрина даёт цельную картину и ссылается на golden + sources за деталями; запрещён дубль живых таблиц (компоненты, env, статусы). Разрешённый + дубль — только машинно-сверяемый тестом факт: стадии/гейты/агенты derive-тестами из + `STAGE_TRANSITIONS`/`QG_CHECKS`/glob промптов (прецедент key-sync ORCH-102). +3. **Канон презентации:** источник — `presentation.md` (машинно-парсимая слайдо-структура + `## Слайд N:` + тезисы, 14–18 слайдов); генератор — `scripts/build_presentation.py` на + python-pptx (тёмная тема, редактируемый текст, кириллица), запуск **только вне рантайма** + (dev-venv, явный запуск человеком — паттерн ORCH-009); зависимость в + `requirements*`/`Dockerfile` НЕ попадает (машинный гард в тестах). **Собранный `.pptx` в git + не коммитится** (источник истины — markdown + скрипт; существующий `PRODUCT_VISION.pptx` не + трогается, но прецедентом не является). +4. **Норматив сопровождения (кросс-каттинг):** «изменил функциональность платформы → обнови + витрину `docs/overview/` в том же PR» — в индексе витрины и `CLAUDE.md` (правило агентов №2); + **reviewer-ось обзорных доков ORCH-079 расширяется** точечной врезкой в + `.openclaw/agents/reviewer.md`: функциональность из витрины изменена, витрина не обновлена → + finding ≥ P1 (расширение трактовки той же оси; канон 52d и verdict-ключи — байт-в-байт; + анти-регресс `test_agent_prompts_canon.py`). +5. **Анти-дрейф — `tests/test_system_docs.py`** (структурный, без сети/LLM/subprocess, паттерн + `test_lite_setup_doc.py`): наличие/непустота 10 файлов; маршруты и норматив в индексе; + сверка стадий и имён гейтов импортом из кода; полнота 6 агентов glob'ом промптов; валидность + относительных ссылок; полнотекстовый FORBIDDEN-скан (импорт из `test_no_host_hardcodes.py`) + + секрет-эвристика; парс слайдо-источника функцией самого генератора; чистота + `requirements*`/`Dockerfile` от pptx; указатели README/CLAUDE/CHANGELOG. Новый QG НЕ + регистрируется — тесты исполняются существующими гейтами. + +Рантайм байт-в-байт: `src/**`, compose, Dockerfile, `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/ +machine-verdict/схема БД — не тронуты; kill-switch не нужен (доки и dev-скрипт конвейером не +исполняются). + +## Последствия + +- **+** Закрывается корневая фрагментация: одна точка входа для трёх аудиторий; презентация + собирается за одну команду из версионируемого источника; машинно-проверяемые факты витрины — + CI-гарантии. +- **+** Нулевой риск рантайма; для enduro-trails инертно. +- **−** Новый golden source = обязанность каждого функционального PR (в этом смысл задачи); + митигировано link-first + derive-тестами + reviewer-осью. +- **−** Точечная правка промпта reviewer — поверхность канона 52d; держится анти-регресс + тестами. +- **Откат:** удалить `docs/overview/`, тест-модуль, скрипт, вернуть точечные правки указателей + и промпта — 1:1, без миграций и состояния. + +## Ссылки + +- Детально: `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md` (D1…D9), + `docs/work-items/ORCH-011/10-tech-risks.md` +- BRD/TRZ/AC: `docs/work-items/ORCH-011/01-brd.md` / `02-trz.md` / `03-acceptance-criteria.md` +- Соседние каноны: adr-0019 (стандарт доков), adr-0021 (канон промптов 52d), adr-0023 + (ось обзорных доков ORCH-079 — расширяется), adr-0029 (порядок под-гейтов), adr-0037/0038 + (deployment-каноны) 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/docs/work-items/ORCH-011/00-business-request.md b/docs/work-items/ORCH-011/00-business-request.md new file mode 100644 index 0000000..32cbc7f --- /dev/null +++ b/docs/work-items/ORCH-011/00-business-request.md @@ -0,0 +1,7 @@ +# Business Request: Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций) + +Work Item ID: ORCH-011 + +## Description + +TBD diff --git a/docs/work-items/ORCH-011/01-brd.md b/docs/work-items/ORCH-011/01-brd.md new file mode 100644 index 0000000..213e29f --- /dev/null +++ b/docs/work-items/ORCH-011/01-brd.md @@ -0,0 +1,199 @@ +--- +work_item: ORCH-011 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# 01 — BRD: ORCH-011 — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций) + +Work Item: **ORCH-011** · Repo: **orchestrator** (self-hosting) · Стадия: analysis +Заказчик: Владелец (Слава) +Тип: docs+tests (паттерн ORCH-102/103 — golden-source-документ + структурные анти-дрейф тесты; рантайм не трогается) + +--- + +## 1. Бизнес-контекст и проблема + +### 1.1. Цель +Описать работу **всей** мультиагентной системы оркестратора в **одном месте** — от бизнес-смысла +(зачем, какую проблему решает, что умеет) до технического устройства (архитектура, конвейер, +агенты, модель объектов, интеграции, качество, наблюдаемость). Документация нужна, чтобы: +1. **другие люди** (разработчики, заказчики, менеджеры проектов) могли разобраться, как работает + оркестратор, не раскапывая 60+ work-item пакетов и 40 ADR; +2. на её основе **генерировать презентационные материалы** по использованию и возможностям + (решение Владельца: слайды PowerPoint, стильный тёмный дизайн, точный рендеринг). + +### 1.2. Корневая проблема — документация богатая, но фрагментированная +Установленные факты (проверено по дереву репо, не изобретать): + +| Что есть | Где | Ограничение как «единого места» | +|----------|-----|---------------------------------| +| Паспорт проекта | `CLAUDE.md` | для агентов/разработчиков; плотный реестр доработок, не вводный текст | +| Тех-витрина | `README.md` | только технический уровень; обзор без бизнес-слоя | +| Бизнес-видение | `docs/PRODUCT_VISION.md` (v1.0, 2026-06-04) | «концепция развития» (vision), не описание текущего состояния; не покрывает тех-уровень | +| Детальная архитектура | `docs/architecture/README.md` (~1246 строк), `internals.md` | глубокий справочник для инженеров; нечитаем «с нуля» нетехническим читателем | +| Решения | `docs/architecture/adr/` (40 сквозных ADR) + per-work-item ADR | точечные решения, не цельная картина | +| Стандарты | `docs/_standards/` (PIPELINE_DOCS, HANDOFF_PROTOCOL, TRACEABILITY) | нормативы для агентов | +| Эксплуатация/тираж | `docs/operations/` (8 runbook'ов), `docs/deployment/` (LITE_SETUP, BUNDLED_SETUP) | операторские инструкции | +| История/уроки | `docs/history/`, `docs/epics/self-evolution.md` | сырьё, не витрина | + +**Ни один** из этих документов не является единой точкой входа «бизнес + тех» для трёх целевых +аудиторий. Новому человеку (заказчику, менеджеру, новому разработчику) сегодня нужно собирать +картину из 5–8 разных мест с разной степенью детализации и разным языком. Презентацию о +возможностях системы собирать не из чего — нет слайдо-готового источника. + +### 1.3. Почему сейчас +- Платформа достигла тиражируемости (ORCH-101/102/103: Lite- и Bundled-развёртывание у заказчика) + — появился **внешний читатель** (заказчики-тестеры), которому нужно объяснять систему. +- Самовоспроизводящийся темп доработок (self-hosting) без единой витрины делает порог входа всё + выше с каждой задачей. + +### 1.4. Решения Владельца (из бизнес-запроса) — приняты как требования +| # | Решение | +|---|---------| +| D-1 | Формат презентационных материалов — **слайды PowerPoint**, стильный **тёмный дизайн**, точный рендеринг. | +| D-2 | Аудитория документации — **разработчики, заказчики, менеджеры проектов** (три явных маршрута чтения). | +| D-3 | Единое место — репозиторий orchestrator: `docs/` (+ возможно compiled-wiki — как опция, см. §2.2). | +| D-4 | Поддерживать в актуальном состоянии: документация обновляется **сразу после изменения функционала** (правило CLAUDE.md §2 распространяется на новую витрину). | + +--- + +## 2. Объём (scope) + +### 2.1. В объёме +- **Единая витрина системы** — новый связный раздел в `docs/` с одной точкой входа (индексом), + покрывающий **два уровня**: + - **Бизнес-уровень** (для нетехнических читателей и презентаций): зачем нужен оркестратор и + какую проблему решает; что умеет (автономный конвейер «задача → прод», мультипроектность, + самовосстановление, пакетный авто-режим, багфикс-трек, тиражируемость); ценность и + возможности простым языком; сценарии использования. + - **Технический уровень** (7 блоков, контент-карта — TRZ §3): + 1) архитектура — компоненты и их связи; 2) конвейер/стадии и гейты на переходах; + 3) агенты — 6 ролей, входы/выходы, артефакты, шаблоны; 4) структура объектов — + Project/Work-Item, реестр проектов, jobs-очередь, события/дедуп, каноническая модель БД; + 5) интеграции — Plane, Gitea, LLM-модели, Telegram; 6) качество/безопасность; + 7) аналитика/наблюдаемость. +- **Маршруты чтения** для трёх аудиторий (D-2): «я заказчик / я менеджер / я разработчик — + с чего начать и что читать дальше». +- **Презентационная основа** (D-1): слайдо-структурированный источник (последовательность + слайдов: заголовок/тезисы/визуальный мотив) + воспроизводимый путь получения `.pptx` в тёмном + дизайне. Выбор инструмента генерации — за архитектором (TRZ §3.4, OQ-2). +- **Норматив сопровождения**: правило «изменил функционал → обнови витрину в том же PR» + зафиксировано в витрине и в правилах агентов (D-4; ось reviewer'а по обзорным докам уже + существует — ORCH-079). +- **Анти-дрейф**: структурные pytest-тесты каркаса витрины (по образцу + `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py`): обязательные разделы, сверка + карты стадий импортом `src/stages.py::STAGE_TRANSITIONS`, полнота 6 агентов, валидность + внутренних ссылок, запрет секретов/хост-хардкодов. +- Обновление указателей: `README.md`, `CLAUDE.md` (ссылка на витрину), `CHANGELOG.md`. + +### 2.2. Вне объёма (явно, не делать) +- **Любые изменения рантайма:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, + machine-verdict ключи, схема БД, compose/Dockerfile — байт-в-байт. +- **Compiled-wiki / внешняя вики-платформа** — вне объёма v1: репозиторий остаётся единственным + источником истины («канон не форкается», паттерн ORCH-009 BR-2); экспорт в wiki — возможное + развитие, фиксируется как открытый вопрос (TRZ §9 OQ-4), не реализуется. +- **Перенос вне-репозиторных источников в репо**: `tasks/orchestrator/STATUS.md`, `BACKLOG.md`, + PROGRESS-журналы, дневники `memory/` физически в репозитории отсутствуют — они служат лишь + затравками для содержания; сами файлы в гит не переносятся (внутренняя кухня, риск утечки + контекста/секретов). +- **Переписывание/замена существующих golden sources** (`docs/architecture/README.md`, + `internals.md`, стандарты `docs/_standards/`, deployment-доки): витрина ссылается на них, + а не дублирует и не подменяет (анти-«второй источник истины», BR-4). +- **Автогенерация документации из кода** (doc-from-code, autodoc) — вне объёма. +- **Маркетинговые материалы за пределами PPTX-основы** (видео, лендинги, демо-стенды). +- Новые runtime-зависимости прод-образа (включая библиотеки генерации презентаций) — запрещено + (NFR-2). + +--- + +## 3. Заинтересованные стороны +- **Владелец/оператор (Слава)** — заказчик задачи; принимает витрину и презентационную основу; + использует слайды для показа возможностей платформы. +- **Заказчики платформы** (внешние, включая тестеров Lite/Bundled-тиража ORCH-102/103) — читают + бизнес-уровень и сценарии; смотрят презентацию. +- **Менеджеры проектов** — читают бизнес-уровень + конвейер/статусную модель (что видно в Plane, + какие человеческие гейты есть). +- **Разработчики** (люди и агенты самого оркестратора) — входят через витрину в технический + уровень и далее по ссылкам в golden sources. +- **Reviewer-агент конвейера** — контролирует соблюдение норматива сопровождения витрины + (расширение оси «обзорные доки» ORCH-079). + +--- + +## 4. Бизнес-требования (BR) + +| ID | Требование | Связь | +|----|------------|-------| +| BR-1 | В `docs/` существует **единая точка входа** (индекс витрины), из которой достижимы оба уровня (бизнес/тех) и все 7 тех-блоков; любой из трёх читателей начинает с одного места. | D-3, AC-1 | +| BR-2 | **Бизнес-уровень** читается нетехническим человеком: проблема → решение → ценность → возможности → сценарии использования; термины конвейера объяснены по-человечески; без необъяснённого жаргона и кодовых идентификаторов в основном тексте. | D-2, AC-2 | +| BR-3 | **Технический уровень** покрывает все 7 заявленных блоков (§2.1) и соответствует фактическому коду/канону репо: карта стадий = `STAGE_TRANSITIONS`, реестр гейтов = `QG_CHECKS` + под-гейты, агенты = 6 промптов `.openclaw/agents/` + таблица модель/эффорт (ORCH-41), модель данных = фактические таблицы `src/db.py`. | AC-3, AC-4, AC-5 | +| BR-4 | **Link-first / не форкается канон:** витрина даёт цельную картину и ссылается на golden sources за деталями (architecture/README, internals, стандарты, ADR, deployment-доки); не создаёт второй источник истины и не противоречит коду. | §2.2, AC-6 | +| BR-5 | **Презентационная основа:** в репо есть слайдо-структурированный источник (бизнес-нарратив → слайды) и воспроизводимый, документированный путь получения `.pptx` в тёмном дизайне (D-1). Инструмент — выбор архитектора; запуск — вне рантайма конвейера. | D-1, AC-7 | +| BR-6 | **Маршруты аудиторий:** витрина содержит явные маршруты чтения для заказчика / менеджера / разработчика (D-2). | D-2, AC-8 | +| BR-7 | **Норматив сопровождения:** правило «изменил функционал → обнови витрину в том же PR» зафиксировано в витрине и видимо агентам (CLAUDE.md-указатель); reviewer-ось обзорных доков покрывает витрину. | D-4, AC-9 | +| BR-8 | **Анти-дрейф:** каркас витрины и её ключевые машинно-проверяемые факты (стадии, агенты, ссылки, отсутствие секретов) защищены структурными pytest-тестами; их падение ловит расхождение витрины с кодом. | AC-10 | +| BR-9 | Существующие указатели актуализированы: `README.md` и `CLAUDE.md` ссылаются на витрину; `CHANGELOG.md` несёт запись. | AC-11 | + +--- + +## 5. Нефункциональные требования (NFR) + +| ID | Требование | +|----|------------| +| NFR-1 | **docs+tests only:** `src/**` байт-в-байт; `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД / compose / Dockerfile — не тронуты. Kill-switch не нужен: документация не исполняется (паттерн ORCH-102/103). | +| NFR-2 | **Прод-образ без новых зависимостей:** генерация презентации (если скриптом) исполняется вне рантайма (host/dev-окружение, явный запуск человеком — паттерн ORCH-009); зависимости генерации НЕ попадают в `requirements`/образ оркестратора. | +| NFR-3 | **Без секретов и хост-специфики** в новых доках/источниках презентации: токены, внутренние URL/имена хостов — только плейсхолдерами (паттерн `tests/test_no_host_hardcodes.py` / fenced-скан `test_lite_setup_doc.py`). | +| NFR-4 | **Язык:** русский (канон репо; языковое исключение deployer.md не затрагивается). Терминология единая со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS. | +| NFR-5 | **Self-hosting safety:** задача не рестартит/не роняет прод-контейнер; прод-деплой — только штатным маршрутом конвейера (staging-гейт + Confirm Deploy). | +| NFR-6 | **Поддерживаемость:** витрина модульная (отдельные файлы по блокам, связанные индексом), чтобы будущие правки были точечными; объём основного текста разумен за счёт link-first (BR-4). | + +--- + +## 6. Допущения и ограничения +- **Вне-репозиторные затравки** (`tasks/orchestrator/STATUS.md`, `BACKLOG.md`, PROGRESS-журналы, + `memory/`) в worktree недоступны — содержание витрины строится из **внутрирепозиторных** golden + sources (CLAUDE.md, README, PRODUCT_VISION, architecture/, _standards/, ADR, deployment/, + history/). Этого достаточно: репо самодостаточен по фактам (проверено §1.2). +- `docs/PRODUCT_VISION.md` остаётся самостоятельным vision-документом; витрина переиспользует его + бизнес-нарратив со сверкой с фактическим состоянием (что из vision уже реализовано — например, + тираж ORCH-101/102/103) и ссылается на него. +- Точное имя/структура каталога витрины — решение архитектора (рекомендация TRZ §2: новый каталог + в `docs/`, например `docs/overview/`); анти-дрейф тесты пишутся под выбранные пути. +- Бинарный артефакт `.pptx`: коммит бинаря в git спорен — решает архитектор (OQ-3); требование + BR-5 — воспроизводимость пути генерации, не обязательность бинаря в репо. +- Задача объёмная по контенту: допускается реализация витрины «вглубь по блокам» в одном PR + (один прогон developer); если объём не помещается — эскалация на уровне задач (разбиение) + по штатному маршруту, не молчаливое сокращение объёма. + +--- + +## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md) +- AC-1 единая точка входа существует и связывает оба уровня и маршруты аудиторий. +- AC-2 бизнес-уровень самодостаточен для нетехнического читателя. +- AC-3…AC-5 тех-уровень покрывает 7 блоков и сходится с кодом (стадии/гейты/агенты/модель данных). +- AC-6 link-first: ссылки на golden sources валидны, дублирования-противоречий нет. +- AC-7 презентационная основа есть; путь к `.pptx` (тёмный дизайн) воспроизводим и документирован. +- AC-8 маршруты трёх аудиторий присутствуют. +- AC-9 норматив сопровождения зафиксирован. +- AC-10 структурные анти-дрейф тесты существуют и зелёные; полный pytest зелёный. +- AC-11 README/CLAUDE.md/CHANGELOG обновлены; `src/**` не тронут. + +--- + +## 8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор) +- **R-1 — гниение витрины.** Self-hosting темп (несколько задач в неделю) быстро устаревает любой + снапшот. Митигция: link-first (BR-4) + норматив сопровождения (BR-7) + структурные тесты на + машинно-проверяемые факты (BR-8) — дрейф ловится CI, а не глазами. +- **R-2 — второй источник истины.** Дублирование деталей architecture/README в витрине приведёт к + противоречиям. Митигция: витрина = картина + ссылки; детали живут в существующих golden sources. +- **R-3 — объём одного прогона.** Полная витрина + презентация + тесты могут не поместиться в один + PR разумного размера. Митигция: модульность (NFR-6), приоритет блоков, при необходимости — + эскалация/разбиение (допущение §6). +- **R-4 — зависимость генерации презентации.** Библиотека генерации PPTX в прод-образе — лишний + attack-surface/вес. Митигция: NFR-2 (вне рантайма), решение по инструменту — ADR архитектора. +- **R-5 — расползание скопа в маркетинг.** Слайды → «а давайте ещё видео/лендинг». Митигция: + жёсткая граница §2.2. diff --git a/docs/work-items/ORCH-011/02-trz.md b/docs/work-items/ORCH-011/02-trz.md new file mode 100644 index 0000000..c467cf1 --- /dev/null +++ b/docs/work-items/ORCH-011/02-trz.md @@ -0,0 +1,191 @@ +--- +work_item: ORCH-011 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# 02 — ТЗ (TRZ): ORCH-011 — Полная документация системы мультиагентов оркестратора + +Work Item: **ORCH-011** · Repo: **orchestrator** · Стадия: analysis + +> ТЗ описывает **что** должно появиться/измениться и **где** (файлы, структура, контент-карта, +> источники истины). **Как** (точное имя каталога витрины, инструмент генерации PPTX, разбиение +> на файлы) — решает архитектор в `06-adr/`. Тип изменения — **docs+tests** (паттерн +> ORCH-102/103): рантайм не трогается. + +--- + +## 1. Сводка изменения +Создать в `docs/` **единую витрину системы** — связный набор документов с одной точкой входа, +описывающий мультиагентный оркестратор на двух уровнях (бизнес + технический, 7 блоков), +с маршрутами чтения для трёх аудиторий (разработчики / заказчики / менеджеры), слайдо-готовой +презентационной основой (PowerPoint, тёмный дизайн) и нормативом сопровождения. Каркас и +машинно-проверяемые факты витрины защитить структурными pytest-тестами (анти-дрейф). Обновить +указатели (`README.md`, `CLAUDE.md`, `CHANGELOG.md`). `src/**` — байт-в-байт. + +--- + +## 2. Задействованные модули / пути + +| Путь | Действие | +|------|----------| +| `docs/<витрина>/` (рекомендация: `docs/overview/`; финальное имя — ADR архитектора) | **создать**: индекс + бизнес-часть + тех-часть (7 блоков) + маршруты аудиторий + презентационная основа | +| `docs/<витрина>/README.md` (или `index.md` — по ADR) | **создать**: единая точка входа (BR-1) | +| `tests/test_system_docs.py` (имя — по паттерну `test_lite_setup_doc.py`; финал — ADR) | **создать**: структурный анти-дрейф витрины (FR-7) | +| `scripts/` (опционально, по ADR — например `scripts/build_presentation.py`) | **создать (опц.)**: генерация `.pptx` из презентационной основы (FR-4) | +| `README.md` | изменить: ссылка на витрину (раздел-указатель) | +| `CLAUDE.md` | изменить: указатель на витрину + норматив сопровождения (FR-6) | +| `CHANGELOG.md` | изменить: запись `docs:` | +| `docs/PRODUCT_VISION.md` | НЕ переписывать; допустима врезка-ссылка на витрину | +| `src/**`, `docker-compose.yml`, `Dockerfile`, `requirements*` | **НЕ трогать** (NFR-1, NFR-2) | + +Чтение (источники истины для контента, без изменения): `src/stages.py`, `src/qg/checks.py`, +`src/db.py`, `src/projects.py`, `src/plane_sync.py`, `src/notifications.py`, `src/queue_worker.py`, +`src/agents/launcher.py`, `.openclaw/agents/*.md`, `docs/architecture/README.md`, `internals.md`, +`docs/_standards/*`, `docs/architecture/adr/*`, `docs/deployment/*`, `docs/operations/*`, +`docs/PRODUCT_VISION.md`. + +--- + +## 3. Функциональные требования + +### FR-1 — Единая точка входа и каркас витрины (BR-1, NFR-6) +- Новый каталог в `docs/` с индекс-документом, который: (а) в 1–2 абзацах отвечает «что это за + система»; (б) ведёт на бизнес-часть и тех-часть; (в) несёт маршруты чтения трёх аудиторий + (FR-5); (г) несёт норматив сопровождения (FR-6). +- Витрина модульная: отдельные файлы по частям/блокам, связанные индексом (а не один монолит) — + точечные правки в будущем дешевле. Точная разбивка — ADR. +- Все внутренние ссылки — относительные, валидные (проверяется тестом FR-7). + +### FR-2 — Бизнес-уровень (BR-2) +Содержание (для нетехнического читателя; источники: `docs/PRODUCT_VISION.md` §1–2, `README.md`, +`CLAUDE.md` TL;DR — со сверкой с фактическим состоянием кода): +- **Проблема и решение:** люди-бутылочное-горлышко в передачах между ролями → конвейер ИИ-агентов + «постановка → прод», человек = постановщик и приёмщик. +- **Что умеет (фактическое состояние, не vision):** автономный конвейер задача→прод с гейтами + качества; мультипроектность (несколько репо из одного инстанса); самовосстановление + (reconciler / job-reaper / watchdog'и / sidecar); пакетный авто-режим (serial gate ORCH-088 + + autoApprove/autoDeploy ORCH-089); дешёвый багфикс-трек (ORCH-019); отмена задач (STOP, + ORCH-090); наблюдаемость (живая Telegram-карточка, `/queue`, `/metrics`, журнал уроков); + самообслуживание (self-hosting — платформа дорабатывает себя); тиражируемость (Lite/Bundled, + ORCH-101/102/103). +- **Ценность простым языком:** скорость / стоимость / автономность / надёжность / масштаб + (переиспользовать формулировки PRODUCT_VISION, сверив цифры с реальностью; цифры без + подтверждения в репо не изобретать). +- **Сценарии использования** (минимум): «фича за вечер» (полный цикл с человеческими гейтами + Approved / Confirm Deploy); «багфикс по короткому маршруту» (метка Bug); «пакет задач на ночь» + (serial gate + авто-лейблы); «несколько проектов параллельно»; «развернуть платформу у себя» + (Lite/Bundled); «остановить задачу» (STOP). +- Кодовые идентификаторы (`ORCH-NNN`, имена функций) в основном бизнес-тексте не используются; + допустимы сноски/ссылки. + +### FR-3 — Технический уровень: 7 блоков с контент-картой (BR-3, BR-4) +Каждый блок: цельное изложение + ссылки на golden source за деталями. Обязательная привязка +к фактам кода (источники указаны; не дублировать детали сверх необходимого — link-first): + +| # | Блок | Обязательное содержание | Источник истины (ссылаться) | +|---|------|------------------------|------------------------------| +| 1 | Архитектура | компоненты и связи: FastAPI-приём вебхуков (Plane/Gitea, HMAC, дедуп), очередь jobs + worker, stage-engine, agent launcher (Claude CLI, git worktree), QG-реестр, plane-sync, notifications, фоновые демоны (reconciler, job-reaper, disk-watchdog, build-cache-pruner), sidecar-watchdog; одна диаграмма потока «вебхук → очередь → агент → гейт → переход» | `docs/architecture/README.md` «Компоненты», `internals.md`, `src/main.py` lifespan | +| 2 | Конвейер/стадии | схема `created → analysis → architecture → development → review → testing → deploy-staging → deploy → done` (+ `cancelled`-сток); exit-гейты рёбер; под-гейты ребра `deploy-staging→deploy` (security → merge → coverage → image-freshness) и `deploy→done` (merge-verify) как врезки, не стадии; откаты REQUEST_CHANGES (max 3); человеческие гейты (Approved BRD, Confirm Deploy) и их снятие авто-лейблами; багфикс-маршрут (пропуск architecture); serial gate / freeze; статусная модель Plane = индикация ≠ управление | `src/stages.py::STAGE_TRANSITIONS`, `src/qg/checks.py::QG_CHECKS`, `docs/_standards/PIPELINE_DOCS.md` §1–3, CLAUDE.md (ORCH-059/066/088/089/019/090) | +| 3 | Агенты | 6 ролей (analyst/architect/developer/reviewer/tester/deployer): задача роли, вход/выход, артефакты по стадиям, machine-verdict ключи; таблица модель/эффорт (резолв из config, ORCH-41/74/81); канон промптов (5 XML-секций, 52d) и где лежат промпты; handoff-протокол | `.openclaw/agents/*.md`, `docs/_standards/PIPELINE_DOCS.md` §2, `HANDOFF_PROTOCOL.md`, таблица моделей `docs/architecture/README.md` | +| 4 | Структура объектов | каноническая модель: Project (реестр `projects.py`: plane-project → repo+prefix) → Work-Item/Task (`tasks`: stage, track, ветка) → Jobs (очередь: статусы, atomic claim, deps, ретраи/backoff/breaker) → Agent-runs (стоимость/токены/effort) → события вебхуков и дедуп → вспомогательные таблицы (`repo_freeze`, `coverage_baseline`, `tracker_messages`, `lessons`); словарь терминов (стадия/гейт/под-гейт/job/worktree/lease) | `src/db.py` (фактические таблицы), `src/projects.py`, `internals.md` «Database Schema», ADR соответствующих задач | +| 5 | Интеграции | Plane (issues/states/labels/webhooks; статусная модель ORCH-066; вход конвейера «To Analyse»); Gitea (репо/ветки/PR; merge строго через PR-API — INV-4; merge-актор с retry ORCH-093; CI `check_ci_green`); LLM (Claude CLI, `--model`/`--effort` из config); Telegram (live-карточка bump-режима, алерты; sidecar-канал отдельно) | `src/plane_sync.py`, `src/webhooks/*`, `src/merge_gate.py`, `src/agents/launcher.py`, `src/notifications.py`, CLAUDE.md (ORCH-042/067/087/093) | +| 6 | Качество/безопасность | философия Quality Gates: машинные вердикты только из YAML-frontmatter (никогда проза), единый контракт `src/frontmatter.py`; реестр гейтов и что каждый ловит; security-гейт (ORCH-022) и coverage-гейт с baseline-ratchet (ORCH-027); канон секретов (.env, не в гит; `gen_secrets.py`); self-hosting-страховки (staging 8501, Confirm Deploy, запрет force-push в main, никогда не ронять прод) | `src/qg/checks.py`, `src/frontmatter.py`, `docs/_standards/PIPELINE_DOCS.md` §3, CLAUDE.md «Self-hosting», `docs/operations/INFRA.md` | +| 7 | Аналитика/наблюдаемость | живая Telegram-карточка задачи (стадии, модель/эффорт, стоимость/токены, честные метрики времени); `GET /queue` (снимки всех подсистем: serial_gate, auto_labels, bug_fast_track, coverage, lessons, reaper, reconcile, …); `GET /metrics` (машинный контракт для sidecar, schema_version); sidecar-watchdog (наблюдатель отделён от наблюдаемого); журнал уроков `lessons` (фундамент петли самообучения); стоимость по агентам (`agent_runs`) | `src/metrics.py`, `src/notifications.py`, `src/lessons.py`, `docs/architecture/README.md` (§ /metrics, § sidecar), CLAUDE.md (ORCH-098/099/100) | + +- **Согласованность с кодом обязательна:** перечень стадий, имена гейтов, имена агентов, имена + таблиц в витрине должны совпадать с фактическими (`src/stages.py`, `src/qg/checks.py`, + `src/db.py`); расхождение — дефект (ловится FR-7 и reviewer'ом). + +### FR-4 — Презентационная основа и путь к PPTX (BR-5, D-1) +- В витрине есть **презентационный источник**: упорядоченная последовательность слайдов + (рекомендация: markdown с явной слайдо-структурой — «слайд N: заголовок / 3–5 тезисов / + подпись-визуал»), покрывающая бизнес-нарратив (проблема → решение → как работает → возможности → + сценарии → тираж → статус платформы). Объём — ориентир 12–20 слайдов (финал — у архитектора). +- Зафиксирован **воспроизводимый путь** получения `.pptx` в тёмном дизайне: либо скрипт в + `scripts/` (запуск вне рантайма, host/dev-окружение), либо документированная ручная процедура + поверх источника. Выбор инструмента (python-pptx / Marp→pptx / иное) и факт коммита бинаря — + решение архитектора (OQ-2, OQ-3). Требования к пути: тёмная тема, кириллица рендерится точно, + процедура описана пошагово с проверкой результата (паттерн «команда + Проверка:» из + LITE_SETUP). +- Зависимости генерации **не** попадают в прод-образ/`requirements` оркестратора (NFR-2). + +### FR-5 — Маршруты аудиторий (BR-6, D-2) +- Индекс несёт три явных маршрута: **заказчик** (бизнес-часть → сценарии → презентация → + Lite/Bundled-доки), **менеджер** (бизнес-часть → конвейер и статусная модель Plane → + человеческие гейты → наблюдаемость), **разработчик** (тех-часть → architecture/README → + internals → стандарты → ADR-реестр → CLAUDE.md). + +### FR-6 — Норматив сопровождения (BR-7, D-4) +- В витрине (индексе) — явная норма: «изменил функционал → обнови витрину в том же PR» + (формулировка по образцу NFR-5 ORCH-102/103). +- `CLAUDE.md` — краткий указатель на витрину в существующем правиле документации (§2 правил + агентов); reviewer-ось «обзорные доки» (ORCH-079) распространяется на витрину — фиксируется + формулировкой в витрине/ADR (изменение промпта reviewer'а НЕ требуется, если ось уже + сформулирована обобщённо — проверить при реализации; если требуется правка промпта, она + следует канону 52d и анти-регресс тестам `test_agent_prompts_canon.py`). + +### FR-7 — Структурный анти-дрейф (BR-8) +Новый тест-модуль (паттерн `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py` / +`test_orch_52b_docs_standard.py`; без сети/LLM/subprocess): +- наличие файлов витрины и обязательных разделов индекса (вкл. маршруты 3 аудиторий и норматив + сопровождения); +- **сверка карты стадий** в витрине импортом `src.stages.STAGE_TRANSITIONS` (полнота и порядок — + как тест полноты `_STAGE_STATUS_LABEL` ORCH-091: derive из кода, не статичный список); +- **полнота 6 агентов** (analyst/architect/developer/reviewer/tester/deployer) в блоке агентов; +- валидность относительных внутренних ссылок витрины (целевые файлы существуют); +- FORBIDDEN-скан новых доков/презент-источника: запрещённые хост-литералы (импорт списка из + `tests/test_no_host_hardcodes.py`, как делает `test_lite_setup_doc.py`) + секрет-эвристика; +- наличие ссылки на витрину в `README.md`. + +--- + +## 4. Изменения API +**Нет.** Эндпоинты/вебхуки не добавляются и не меняются. + +## 5. Изменения схемы БД +**Нет.** Таблицы/миграции не вводятся. + +## 6. Требования к новым/изменённым QG checks +**Нет.** Реестр `QG_CHECKS`/`check_*` не меняется. Анти-дрейф витрины — обычные pytest-тесты в +`tests/` (исполняются существующими гейтами `check_ci_green`/`check_tests_passed`/coverage-гейтом +штатно), **не** новый Quality Gate. + +## 7. Совместимость / регресс +- **Нулевая регрессия рантайма по построению:** меняются только `docs/**`, `tests/**`, + `README.md`, `CLAUDE.md`, `CHANGELOG.md` (+ опц. `scripts/`); `src/**` байт-в-байт. Kill-switch + не нужен — документация и dev-скрипт не исполняются конвейером (паттерн ORCH-009/102/103). +- Существующие тесты остаются зелёными; новые тесты аддитивны. +- enduro-trails не затрагивается (общих артефактов нет). +- Откат = revert PR (доки/тесты), без операционных последствий. +- Self-hosting: прод-контейнер не рестартится в рамках задачи; выкат — штатным маршрутом. + +--- + +## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR разработки) +- Витрина `docs/<…>/` (FR-1…FR-5) + презентационный источник. +- `tests/test_system_docs.py` (FR-7). +- `README.md` (ссылка), `CLAUDE.md` (указатель + норматив), `CHANGELOG.md` (`docs:`-запись). +- ADR архитектора: `docs/work-items/ORCH-011/06-adr/ADR-001-.md` (структура витрины, + инструмент PPTX, политика бинаря, состав тестов); при сквозной значимости — зеркало в + `docs/architecture/adr/`. + +--- + +## 9. Открытые вопросы для архитектора (не блокируют анализ) +- **OQ-1:** Имя и внутренняя структура каталога витрины (`docs/overview/` vs `docs/system/`; + один индекс + N файлов блоков vs два файла «business/tech»). Рекомендация аналитика — + `docs/overview/` с индексом и помодульными файлами (NFR-6). +- **OQ-2:** Инструмент генерации PPTX: скрипт `scripts/` (python-pptx; host/dev-venv, вне + прод-образа) vs конвертация из markdown (Marp и т.п.) vs документированная ручная процедура. + Критерии: тёмная тема, точный рендеринг кириллицы, воспроизводимость, NFR-2. +- **OQ-3:** Коммитить ли собранный `.pptx` в репо (бинарь в git) или хранить только источник + + процедуру сборки. +- **OQ-4:** Compiled-wiki/экспорт (упомянут в бизнес-запросе как «возможно»): фиксируем вне + объёма v1; нужно ли заводить follow-up work item. +- **OQ-5:** Достаточна ли текущая формулировка reviewer-оси обзорных доков (ORCH-079) для + покрытия витрины, или нужна точечная правка промпта reviewer (тогда — по канону 52d, с + обновлением `test_agent_prompts_canon.py`). diff --git a/docs/work-items/ORCH-011/03-acceptance-criteria.md b/docs/work-items/ORCH-011/03-acceptance-criteria.md new file mode 100644 index 0000000..7ad9415 --- /dev/null +++ b/docs/work-items/ORCH-011/03-acceptance-criteria.md @@ -0,0 +1,187 @@ +--- +work_item: ORCH-011 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки: ORCH-011 — Полная документация системы мультиагентов + +Work Item: **ORCH-011** · Repo: **orchestrator** · Стадия: analysis + +Каждый критерий — однозначный PASS/FAIL. Reviewer/Tester проверяют буквально по файлам +репозитория (пути витрины — те, что зафиксирует ADR архитектора; ниже «витрина» = выбранный +каталог в `docs/`). + +--- + +## AC-1 — Единая точка входа существует (BR-1) + +**Условие:** в `docs/` создан каталог витрины с индекс-документом. +- **PASS:** индекс существует; из него по относительным ссылкам достижимы: бизнес-часть, + тех-часть (все 7 блоков FR-3), презентационная основа, маршруты трёх аудиторий, норматив + сопровождения. Каталог и индекс совпадают с зафиксированными в ADR-001 путями. +- **FAIL:** индекса нет, ИЛИ хотя бы одна из перечисленных частей недостижима из индекса. + +--- + +## AC-2 — Бизнес-уровень самодостаточен для нетехнического читателя (BR-2) + +**Условие:** бизнес-часть содержит все 5 обязательных смысловых разделов. +- **PASS:** присутствуют разделы: (1) проблема, которую решает оркестратор; (2) суть решения + (конвейер агентов, человек = постановщик/приёмщик); (3) что умеет — фактические способности + (минимум: автономный конвейер задача→прод, мультипроектность, самовосстановление, пакетный + авто-режим, багфикс-трек, отмена STOP, наблюдаемость, self-hosting, тиражируемость + Lite/Bundled); (4) ценность (скорость/стоимость/автономность/надёжность/масштаб); + (5) сценарии использования (минимум 5 из перечня FR-2). В основном тексте нет необъяснённых + кодовых идентификаторов/имён функций. +- **FAIL:** отсутствует любой из 5 разделов, ИЛИ способности из обязательного минимума + пропущены, ИЛИ текст оперирует жаргоном без объяснения. + +--- + +## AC-3 — Тех-уровень покрывает 7 блоков (BR-3) + +**Условие:** тех-часть содержит все блоки контент-карты TRZ §3 FR-3. +- **PASS:** присутствуют и непусты блоки: 1) архитектура/компоненты (включая фоновые демоны и + sidecar), 2) конвейер/стадии/гейты (включая под-гейты и человеческие гейты), 3) агенты, + 4) структура объектов/каноническая модель, 5) интеграции (Plane/Gitea/LLM/Telegram), + 6) качество/безопасность, 7) аналитика/наблюдаемость. Блок 1 содержит хотя бы одну + диаграмму/схему потока (текстовую ASCII или mermaid). +- **FAIL:** любой блок отсутствует/пуст, ИЛИ схема потока отсутствует. + +--- + +## AC-4 — Карта стадий и гейтов сходится с кодом (BR-3, FR-7) + +**Условие:** конвейер в витрине = `src/stages.py::STAGE_TRANSITIONS` + реестр `QG_CHECKS`. +- **PASS:** все стадии из `STAGE_TRANSITIONS` (включая `deploy-staging` и сток `cancelled`) + присутствуют в витрине в правильном порядке; exit-гейты рёбер названы фактическими именами + (`check_analysis_approved` … `check_deploy_status`); под-гейты ребра + `deploy-staging→deploy` описаны в фактическом порядке (security → merge → coverage → + image-freshness) и явно помечены как врезки, не стадии. Структурный тест сверяет перечень + стадий импортом `src.stages.STAGE_TRANSITIONS` и зелёный. +- **FAIL:** стадия/гейт пропущены или названы несуществующим именем, ИЛИ порядок противоречит + коду, ИЛИ тест-сверка отсутствует/красная. + +--- + +## AC-5 — Агенты: 6 ролей с полным паспортом (BR-3) + +**Условие:** блок агентов описывает все 6 ролей. +- **PASS:** для каждой роли (analyst, architect, developer, reviewer, tester, deployer) указаны: + назначение, стадия работы, вход, выходные артефакты (по `PIPELINE_DOCS.md` §2) и + machine-verdict ключ (где есть: `verdict:`/`result:`/`staging_status:`/`deploy_status:`); + присутствует таблица модель/эффорт, совпадающая с фактическим резолвом config (ORCH-41/81: + developer=`xhigh`, tester/deployer=`medium`, прочие=`high`). Структурный тест полноты 6 ролей + зелёный. +- **FAIL:** роль пропущена, ИЛИ артефакты/ключи противоречат `PIPELINE_DOCS.md`, ИЛИ таблица + модель/эффорт расходится с config. + +--- + +## AC-6 — Link-first: ссылки валидны, канон не форкается (BR-4) + +**Условие:** витрина ссылается на golden sources, не подменяя их. +- **PASS:** витрина содержит работающие относительные ссылки минимум на: + `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`. Все относительные ссылки витрины резолвятся в + существующие файлы (структурный тест зелёный). Существующие golden sources не удалены и не + переписаны (допустимы только врезки-ссылки). +- **FAIL:** битая ссылка, ИЛИ обязательная ссылка отсутствует, ИЛИ витрина дублирует-подменяет + существующий golden source (например, копия таблицы компонентов architecture/README вместо + ссылки с кратким резюме). + +--- + +## AC-7 — Презентационная основа и путь к PPTX (BR-5) + +**Условие:** слайдовый источник существует; путь к `.pptx` воспроизводим. +- **PASS:** в витрине есть презентационный источник с явной слайдо-структурой (нумерованные + слайды: заголовок + тезисы), покрывающий бизнес-нарратив FR-4 (проблема → решение → как + работает → возможности → сценарии → тираж → статус); зафиксирована пошаговая воспроизводимая + процедура получения `.pptx` в тёмном дизайне (скрипт `scripts/` ИЛИ документированная + процедура — по ADR-001), каждая команда — с проверкой результата; зависимости генерации + отсутствуют в `requirements*` и `Dockerfile` оркестратора (NFR-2). +- **FAIL:** источника нет, ИЛИ слайдо-структура не выражена, ИЛИ путь к `.pptx` не описан / + невоспроизводим, ИЛИ зависимость генерации попала в прод-образ. + +--- + +## AC-8 — Маршруты трёх аудиторий (BR-6) + +**Условие:** индекс несёт маршруты чтения. +- **PASS:** в индексе явно выделены 3 маршрута — заказчик, менеджер проекта, разработчик — каждый + с упорядоченным списком «что читать» (состав по FR-5). +- **FAIL:** хотя бы один маршрут отсутствует или пуст. + +--- + +## AC-9 — Норматив сопровождения зафиксирован (BR-7) + +**Условие:** правило актуальности витрины закреплено. +- **PASS:** индекс витрины несёт норму «изменил функционал → обнови витрину в том же PR»; + `CLAUDE.md` содержит указатель на витрину; в ADR-001 зафиксировано, как reviewer-ось обзорных + доков (ORCH-079) покрывает витрину (с правкой промпта reviewer или обоснованием, что правка + не нужна; при правке промпта — канон 52d сохранён и `tests/test_agent_prompts_canon.py` + зелёный). +- **FAIL:** норматив отсутствует в витрине, ИЛИ CLAUDE.md не обновлён, ИЛИ вопрос reviewer-оси + не разрешён в ADR. + +--- + +## AC-10 — Анти-дрейф тесты существуют и зелёные (BR-8) + +**Условие:** структурный тест-модуль витрины создан и проходит. +- **PASS:** новый тест-модуль (паттерн `test_lite_setup_doc.py`) покрывает: наличие + файлов/разделов витрины, сверку стадий импортом `STAGE_TRANSITIONS`, полноту 6 агентов, + валидность относительных ссылок, FORBIDDEN-скан (импорт запрещённых литералов из + `tests/test_no_host_hardcodes.py` + секрет-эвристика) по новым докам и презентационному + источнику, наличие ссылки на витрину в `README.md`. `pytest tests/ -q` полностью зелёный. +- **FAIL:** тест-модуль отсутствует, ИЛИ любая из перечисленных проверок не реализована, ИЛИ + pytest красный. + +--- + +## AC-11 — Рантайм не тронут; указатели обновлены (NFR-1, BR-9) + +**Условие:** изменение строго docs+tests(+опц. scripts). +- **PASS:** diff PR не содержит изменений `src/**`, `docker-compose.yml`, `Dockerfile`, + `requirements*`, схемы БД; `README.md` ссылается на витрину; `CHANGELOG.md` несёт + `docs:`-запись по ORCH-011; в новых файлах нет секретов/боевых токенов/хост-хардкодов + (FORBIDDEN-скан AC-10 зелёный). +- **FAIL:** любой файл рантайма изменён, ИЛИ указатели не обновлены, ИЛИ найден + секрет/хост-хардкод. + +--- + +## AC-12 — Самодостаточность против вне-репозиторных источников (допущение BRD §6) + +**Условие:** витрина не зависит от файлов вне репо. +- **PASS:** витрина не содержит ссылок на вне-репозиторные пути (`tasks/…`, `memory/…`, + локальные пути хоста); всё содержание подтверждается внутрирепозиторными источниками. +- **FAIL:** есть ссылка на файл, отсутствующий в репозитории, или цитата «по памяти» без + внутрирепозиторного источника. + +--- + +## Сводная матрица AC ↔ BR/FR + +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-2 / FR-2 | +| AC-3 | BR-3 / FR-3 | +| AC-4 | BR-3, BR-8 / FR-3, FR-7 | +| AC-5 | BR-3 / FR-3 | +| AC-6 | BR-4 / FR-1, FR-3 | +| AC-7 | BR-5 / FR-4, NFR-2 | +| AC-8 | BR-6 / FR-5 | +| AC-9 | BR-7 / FR-6 | +| AC-10 | BR-8 / FR-7 | +| AC-11 | BR-9, NFR-1, NFR-3 | +| AC-12 | BRD §6 (допущения), NFR-3 | diff --git a/docs/work-items/ORCH-011/04-test-plan.yaml b/docs/work-items/ORCH-011/04-test-plan.yaml new file mode 100644 index 0000000..e71d054 --- /dev/null +++ b/docs/work-items/ORCH-011/04-test-plan.yaml @@ -0,0 +1,117 @@ +work_item: ORCH-011 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-11 +model_used: claude-opus-4-8 +title: "Полная документация системы мультиагентов: структурный анти-дрейф витрины" +framework: pytest +scope: > + Покрывается: каркас витрины (файлы/разделы/маршруты/норматив), сходимость + машинно-проверяемых фактов с кодом (стадии из STAGE_TRANSITIONS, 6 агентов), + валидность внутренних ссылок, отсутствие секретов/хост-хардкодов, обновление + указателей README/CLAUDE.md, неизменность рантайма (полный регресс). + Вне покрытия: качество прозы/дизайна слайдов (проверяет reviewer/человек), + фактический рендеринг .pptx (ручная проверка по процедуре AC-7). +notes: > + Все тесты — структурные, без сети/LLM/subprocess (паттерн tests/test_lite_setup_doc.py, + test_bundled_setup_doc.py, test_orch_52b_docs_standard.py). Точные пути витрины фиксирует + ADR-001 архитектора (рекомендация TRZ: docs/overview/); имя тест-модуля ниже — + tests/test_system_docs.py — может быть уточнено в ADR, состав проверок обязателен. + Сверки derive-из-кода (стадии) обязаны импортировать src.stages, а не дублировать + статичный список (анти-дрейф, образец — тест полноты ORCH-091). FORBIDDEN-скан + импортирует список запрещённых литералов из tests/test_no_host_hardcodes.py. + Полный регресс tests/ должен оставаться зелёным. + +tests: + # ---- FR-1: каркас витрины и единая точка входа ---- + - id: TC-01 + type: unit + description: "Каталог витрины и индекс существуют; индекс содержит обязательные разделы: вход «что это», ссылки на бизнес-часть и тех-часть, маршруты аудиторий, норматив сопровождения (AC-1)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-02 + type: unit + description: "Из индекса по относительным ссылкам достижимы все файлы витрины: бизнес-часть, тех-блоки 1–7, презентационный источник (AC-1/AC-3)." + module: tests/test_system_docs.py + expected: PASS + + # ---- FR-2: бизнес-уровень ---- + - id: TC-03 + type: unit + description: "Бизнес-часть содержит 5 обязательных смысловых разделов (проблема, решение, что умеет, ценность, сценарии) и минимум 5 сценариев использования (AC-2)." + module: tests/test_system_docs.py + expected: PASS + + # ---- FR-3: тех-уровень, сходимость с кодом ---- + - id: TC-04 + type: unit + description: "Тех-часть содержит все 7 блоков контент-карты (архитектура, конвейер, агенты, объекты, интеграции, качество/безопасность, наблюдаемость); блок архитектуры несёт схему потока (AC-3)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-05 + type: unit + description: "Карта стадий витрины сверена импортом src.stages.STAGE_TRANSITIONS: каждая стадия (включая deploy-staging и cancelled) упомянута; derive из кода, не статичный список (AC-4)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-06 + type: unit + description: "Имена exit-гейтов рёбер в витрине существуют в реестре qg.checks.QG_CHECKS (нет выдуманных имён гейтов) (AC-4)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-07 + type: unit + description: "Блок агентов покрывает все 6 ролей (analyst/architect/developer/reviewer/tester/deployer); каждой роли сопоставлены артефакты; таблица модель/эффорт присутствует (AC-5)." + module: tests/test_system_docs.py + expected: PASS + + # ---- FR-1/FR-3: link-first ---- + - id: TC-08 + type: unit + description: "Все относительные ссылки витрины резолвятся в существующие файлы; обязательные ссылки на golden sources (architecture/README, internals, PIPELINE_DOCS, HANDOFF_PROTOCOL, adr/, LITE_SETUP, BUNDLED_SETUP, PRODUCT_VISION, CLAUDE.md) присутствуют (AC-6)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-09 + type: unit + description: "Витрина не ссылается на вне-репозиторные пути (tasks/, memory/, абсолютные пути хоста) (AC-12)." + module: tests/test_system_docs.py + expected: PASS + + # ---- FR-4: презентационная основа ---- + - id: TC-10 + type: unit + description: "Презентационный источник существует, несёт явную слайдо-структуру (нумерованные слайды с заголовками, не менее 12) и покрывает обязательный нарратив (проблема/решение/как работает/возможности/сценарии/тираж) (AC-7)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-11 + type: unit + description: "Зависимости генерации презентации не попали в прод-образ: requirements*/Dockerfile не содержат библиотек генерации (например python-pptx) (AC-7/NFR-2)." + module: tests/test_system_docs.py + expected: PASS + + # ---- FR-6: норматив и указатели ---- + - id: TC-12 + type: unit + description: "Индекс витрины несёт норматив сопровождения («в том же PR»); README.md содержит ссылку на витрину; CLAUDE.md содержит указатель (AC-9/AC-11)." + module: tests/test_system_docs.py + expected: PASS + + # ---- NFR-3: секреты/хост-хардкоды ---- + - id: TC-13 + type: unit + description: "FORBIDDEN-скан новых доков и презентационного источника: запрещённые хост-литералы (импорт из tests/test_no_host_hardcodes.py) и секрет-эвристика не находят совпадений (AC-10/AC-11)." + module: tests/test_system_docs.py + expected: PASS + + # ---- Регресс ---- + - id: TC-14 + type: integration + description: "Полный регресс: pytest tests/ -q зелёный; существующие структурные док-тесты (test_lite_setup_doc, test_bundled_setup_doc, test_orch_52b_docs_standard, test_agent_prompts_canon) не сломаны (AC-10/AC-11)." + module: tests/ + expected: PASS diff --git a/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md b/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md new file mode 100644 index 0000000..b04acb7 --- /dev/null +++ b/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md @@ -0,0 +1,388 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# ADR-001: Витрина системы `docs/overview/` — структура, путь к PPTX, анти-дрейф контур + +Work Item: **ORCH-011** — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций) +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0039-system-overview-docs-canon.md`** +(новый docs-раздел `docs/overview/` с нормативом сопровождения, обязательным для всех будущих +функциональных PR, + расширение reviewer-оси обзорных доков ORCH-079 — кросс-каттинг). + +## Статус +Proposed + +## Контекст + +Решения Владельца (BRD §1.4): D-1 презентация = PowerPoint, тёмный дизайн, точный рендеринг; +D-2 три аудитории (разработчики/заказчики/менеджеры); D-3 единое место — `docs/` репозитория; +D-4 витрина поддерживается актуальной сразу после изменения функционала. + +Факты, сверенные с кодом/репо на ветке задачи: + +- **Документация богатая, но фрагментированная** (BRD §1.2, проверено): паспорт `CLAUDE.md` + (реестр доработок, не вводный текст), тех-витрина `README.md`, vision + `docs/PRODUCT_VISION.md` (v1.0, «концепция развития»), инженерный справочник + `docs/architecture/README.md` (~1246 строк) + `internals.md`, 38 сквозных ADR, стандарты + `docs/_standards/`, операционные/деплойные доки. Единой точки входа «бизнес + тех» нет. +- **Живое доказательство риска гниения (R-1):** схема конвейера в `docs/PRODUCT_VISION.md` §2 + уже устарела — в ней нет стадии `deploy-staging` и стока `cancelled`, фактически + присутствующих в `src/stages.py::STAGE_TRANSITIONS` (9 ключей + `cancelled`). Снапшот без + машинной сверки расходится с кодом за недели. +- **Прецедент бинаря без воспроизводимости:** `docs/PRODUCT_VISION.pptx` закоммичен, но пути + его генерации в репо нет (`grep pptx scripts/ docs/` — пусто) — ровно тот паттерн + «невоспроизводимый артефакт», который BR-5 требует исключить. +- **Reviewer-ось обзорных доков (ORCH-079) по букве привязана к README:** + `.openclaw/agents/reviewer.md` формулирует ось через «пункт из `README.md` „Известные + ограничения“»; новая витрина под букву оси не подпадает (релевантно OQ-5). История ORCH-079 + показывает: общего правила «документация = golden source» недостаточно — обзорные доки гниют, + пока ось не названа явно. +- **Тестовая механика готова:** паттерны структурных доков-тестов — + `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py` (разделы по порядку, кирпичи, + скан FORBIDDEN импортом из `tests/test_no_host_hardcodes.py` (`FORBIDDEN`, + `find_violations`), секрет-эвристика, кросс-рефы); импорт `STAGE_TRANSITIONS` в тестах — + норма (ORCH-091: полнота derive из кода, не статичный список); импорт `QG_CHECKS` — + `tests/test_qg_registry_snapshot.py`; импорт чистых функций из `scripts/` — + `tests/test_bootstrap_script.py`. +- **Источники контента самодостаточны внутри репо** (BRD §6): вне-репозиторные затравки + (`tasks/…`, `memory/…`) недоступны и не нужны; таблица модель/эффорт — ORCH-41/81 + (developer=`xhigh`, tester/deployer=`medium`, прочие=`high`, все на `claude-opus-4-8`). +- `docs/overview/` свободен (коллизий имён нет). + +Задача — **docs+tests (+dev-скрипт)** (паттерн ORCH-102/103): `src/**`, +`docker-compose.yml`, `Dockerfile`, `requirements*` читаются как источник истины и НЕ меняются; +конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт. +Kill-switch не нужен: документация и dev-скрипт конвейером не исполняются (активация генерации — +только явный запуск человеком, паттерн ORCH-009). + +## Решение + +### Сводка + +Создаётся новый docs-раздел **`docs/overview/`** — витрина системы: индекс `README.md` +(точка входа, маршруты трёх аудиторий, норматив сопровождения), бизнес-часть `business.md`, +семь тех-файлов `tech-*.md` (= 7 блоков контент-карты TRZ FR-3, link-first), слайдо-источник +`presentation.md` + dev-скрипт `scripts/build_presentation.py` (python-pptx, вне прод-образа; +бинарь `.pptx` НЕ коммитится — D5). Машинно-проверяемые факты витрины (стадии, гейты, агенты, +ссылки, гигиена секретов, слайдо-структура, чистота prod-зависимостей) защищаются структурным +`tests/test_system_docs.py` (D6). Reviewer-ось обзорных доков точечно расширяется на витрину +(D7). Исходы всех открытых вопросов ТЗ §9 (OQ-1…OQ-5) — в D1/D4/D5/D9/D7 соответственно. + +### D1 (исход OQ-1) — Размещение и состав: `docs/overview/`, плоский каталог, 10 файлов + +**Решение: каталог `docs/overview/`** (рекомендация аналитика подтверждена). Семантика +docs-разделов после ORCH-011: `overview/` — «что это за система и как она устроена» (читатель — +любой из трёх аудиторий, входит впервые); `architecture/` — инженерный справочник (детали); +`deployment/` — «как развернуть у себя» (ORCH-102/103); `operations/` — «как эксплуатировать +наш прод»; `_standards/` — нормативы для агентов. + +**Состав — плоский каталог, 10 файлов** (модульность NFR-6: будущие правки точечные; плоскость — +одна глубина относительных ссылок и простые globs в тестах; индекс — `README.md`, а не +`index.md`: авто-рендер в web-UI Gitea, симметрия `docs/architecture/README.md`): + +| Файл | Содержание | Покрывает | +|------|-----------|-----------| +| `README.md` | индекс: «что это» в 1–2 абзацах; навигация на все части; 3 маршрута аудиторий (D8); норматив сопровождения (D8) | FR-1, FR-5, FR-6, AC-1, AC-8, AC-9 | +| `business.md` | бизнес-уровень (D2) | FR-2, AC-2 | +| `tech-architecture.md` | блок 1: компоненты и связи + диаграмма потока | FR-3.1, AC-3 | +| `tech-pipeline.md` | блок 2: конвейер/стадии/гейты/под-гейты/откаты/человеческие гейты/авто-лейблы/багфикс-трек/serial gate/статусная модель Plane | FR-3.2, AC-4 | +| `tech-agents.md` | блок 3: 6 ролей, входы/выходы/артефакты/verdict-ключи, таблица модель/эффорт, канон промптов | FR-3.3, AC-5 | +| `tech-data-model.md` | блок 4: Project → Work-Item/Task → Jobs → Agent-runs → события/дедуп → вспомогательные таблицы; словарь терминов | FR-3.4 | +| `tech-integrations.md` | блок 5: Plane / Gitea / LLM / Telegram | FR-3.5 | +| `tech-quality-security.md` | блок 6: философия QG, frontmatter-контракт, security/coverage-гейты, канон секретов, self-hosting-страховки | FR-3.6 | +| `tech-observability.md` | блок 7: live-карточка, `/queue`, `/metrics`, sidecar, журнал уроков, стоимость | FR-3.7 | +| `presentation.md` | слайдо-источник + процедура сборки `.pptx` (D4) | FR-4, AC-7 | + +Один тех-блок = один файл (а не монолит `tech.md` и не два файла «business/tech»): блоки +независимы по темпу устаревания (pipeline меняется чаще, чем интеграции), точечный PR правит +один файл; тесту проще ассертить присутствие и непустоту каждого блока пофайлово. + +Привязка: BR-1, NFR-6, AC-1, AC-3. + +### D2 — Бизнес-уровень: текущее состояние, не vision; числа только с подтверждением + +**Решение: `business.md` описывает фактическое состояние платформы** (контент-минимум FR-2: +проблема → решение → что умеет → ценность → ≥5 сценариев), переиспользуя нарратив +`docs/PRODUCT_VISION.md` §1–2 со сверкой с кодом. Нормативные правила: + +- **Разделение ролей документов:** PRODUCT_VISION остаётся vision («куда идём», не трогается; + допустима врезка-ссылка на витрину — на усмотрение developer); `business.md` — «что есть + сейчас». Расхождение vision ↔ код (пример: устаревшая схема конвейера в vision §2) в витрину + не переносится — витрина строится от `STAGE_TRANSITIONS`. +- **Числовые метрики** (скорость/стоимость) — только с внутрирепозиторным подтверждением либо + с явной атрибуцией «оценка из PRODUCT_VISION»; новые цифры не изобретать (FR-2, AC-12). +- **Без жаргона:** кодовые идентификаторы (`ORCH-NNN`, имена функций/модулей) в основном тексте + не используются; термины конвейера (стадия, гейт, ревью) объясняются по-человечески; детали — + сносками/ссылками в тех-часть (AC-2). +- Обязательный минимум способностей — список AC-2 (конвейер задача→прод, мультипроектность, + самовосстановление, пакетный авто-режим, багфикс-трек, STOP, наблюдаемость, self-hosting, + тираж Lite/Bundled) — каждый пункт сводится к одному абзацу простым языком. + +Привязка: BR-2, FR-2, AC-2, AC-12. + +### D3 — Тех-уровень: 7 файлов по контент-карте TRZ, link-first, согласованность с кодом + +**Решение: контент-карта TRZ §3 FR-3 принимается как нормативная** (обязательное содержание и +источники истины каждого блока — таблица FR-3, в ADR не дублируется). Архитектурные уточнения: + +- **Link-first (BR-4, анти-«вторая правда»):** каждый файл даёт цельную картину уровня + «понять устройство» и ведёт ссылкой в golden source за деталями + (`docs/architecture/README.md`, `internals.md`, `_standards/*`, ADR-реестр, deployment-доки). + Запрещено копировать в витрину таблицы/списки, которые живут в golden source и меняются с + кодом (таблица компонентов, карта env, 22 статуса Plane). Разрешённый дубль — только + машинно-сверяемый тестом факт (перечень стадий, имена гейтов, 6 агентов, таблица + модель/эффорт) — ровно потому, что тест D6 рвёт CI при дрейфе (прецедент — key-sync TC-02b + ORCH-102). +- **`tech-architecture.md` несёт одну диаграмму потока** «вебхук → очередь → агент → гейт → + переход» (mermaid или ASCII — на выбор developer; AC-3 требует хотя бы одну). +- **`tech-pipeline.md`:** схема стадий включает `deploy-staging` и сток `cancelled`; под-гейты + ребра `deploy-staging→deploy` перечисляются в фактическом порядке **security → merge → + coverage → image-freshness** (нормативный порядок — adr-0029/ORCH-027) и явно помечаются как + **врезки в переход, а не стадии** (AC-4); под-гейт `deploy→done` (merge-verify) — аналогично; + человеческие гейты (Approved, Confirm Deploy) и их снятие авто-лейблами (ORCH-089), STOP + (ORCH-090), багфикс-маршрут (ORCH-019), serial gate/freeze (ORCH-088); «статусы Plane = + индикация ≠ управление» (ORCH-066). +- **`tech-agents.md`:** паспорт каждой из 6 ролей по `PIPELINE_DOCS.md` §2 (назначение, стадия, + вход, артефакты, machine-verdict ключ — имена байт-в-байт: `verdict:`/`result:`/ + `staging_status:`/`deploy_status:`/`security_status:`); таблица модель/эффорт = фактический + резолв config (ORCH-41/74/81). +- **Терминология** едина со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS (NFR-4); язык — + русский. + +Привязка: BR-3, BR-4, FR-3, AC-3…AC-6. + +### D4 (исход OQ-2) — Презентация: `presentation.md` (машинно-парсимый источник) + `scripts/build_presentation.py` на python-pptx + +**Решение: слайдо-источник — `docs/overview/presentation.md`** с жёсткой машинно-парсимой +структурой: + +```markdown +## Слайд N: <Заголовок> +- <тезис 1> (3–6 тезисов на слайд) +- <тезис 2> +> Визуал: <подпись визуального мотива слайда> (опционально) +``` + +Нумерация сквозная с 1; объём — **14–18 слайдов** (в коридоре ориентира FR-4 12–20); +нормативные смысловые биты нарратива (порядок FR-4): проблема → решение → как работает +(конвейер+гейты) → роли агентов → человек в контуре → возможности (автономный пакетный режим, +багфикс-трек, самовосстановление, наблюдаемость) → сценарии → тираж → статус платформы. +Точная нарезка по слайдам — за developer; тест D6 ассертит структуру и биты, не прозу. + +**Генератор — `scripts/build_presentation.py` на `python-pptx`:** + +- **Запуск только вне рантайма** (host/dev venv, явный запуск человеком — паттерн ORCH-009); + `python-pptx` НЕ добавляется в `requirements*`/`Dockerfile` (NFR-2; машинный гард — D6 TC-09). +- **Архитектура скрипта:** чистая функция-парсер `parse_slides(text) -> list[Slide]` + (stdlib-only, без импорта pptx) + рендерер с **ленивым** `import pptx` внутри функции сборки. + Один парсер = один источник истины о формате: `tests/test_system_docs.py` импортирует + `parse_slides` (механика импорта из `scripts/` — прецедент `test_bootstrap_script.py`) и + валидирует слайдо-источник без установленного python-pptx. +- **Тёмный дизайн (D-1):** константы темы в скрипте — тёмный фон (≈`#1F1F2E`), светлый текст, + один акцентный цвет; шрифты — стандартные системные с полной кириллицей (Calibri/Arial). + python-pptx пишет **настоящий редактируемый текст** в slide-объекты → «точный рендеринг» + гарантирован самим PowerPoint (а не headless-браузером), кириллица не растрируется, Владелец + может править слайды руками. +- **Процедура — в `presentation.md`**, раздел «Как собрать .pptx», форма «fenced-команда + + Проверка:» (канон LITE_SETUP): создать venv → `pip install python-pptx` → запуск скрипта → + проверка (скрипт печатает число собранных слайдов; файл открывается, тема тёмная). Дефолтный + выход — `build/orchestrator-overview.pptx` (D5). + +**Почему python-pptx, а не альтернативы:** Marp → pptx требует Node+Chromium и экспортирует +слайды растровыми картинками (нередактируемо, текст не выделяется — против «точного +рендеринга» как редактируемого артефакта); pandoc → pptx ограниченно управляет тёмной темой +(reference-doc с мастер-слайдами — отдельный бинарный артефакт в репо); «только ручная +процедура» — слабейшая воспроизводимость (человек = источник дрейфа). python-pptx: один +pip-пакет в одноразовом dev-venv, детерминированный код-как-дизайн, тестируемый парсер. + +Привязка: BR-5, FR-4, AC-7, NFR-2. + +### D5 (исход OQ-3) — Бинарь `.pptx` НЕ коммитится; источник истины — markdown + скрипт + +**Решение: собранный `.pptx` в git НЕ коммитится.** Канон: источник истины — +`presentation.md` + `build_presentation.py`; артефакт собирается по требованию за одну команду. +Обоснование: бинарь не диффуем, анти-дрейф тесты его содержимое не проверяют → закоммиченный +deck молча устаревает относительно источника (живой пример — `docs/PRODUCT_VISION.pptx`: +закоммичен, пути генерации нет, контент vision уже разошёлся с кодом); BR-5 требует +воспроизводимость пути, не бинарь (BRD §6). + +- Дефолтный выход генератора — `build/orchestrator-overview.pptx`; в `.gitignore` добавляется + строка `build/` (разрешённое отклонение диффа, не рантайм). +- **Существующий `docs/PRODUCT_VISION.pptx` не трогается** (артефакт другого work item; + ретроактивная чистка — вне объёма §2.2). Новый канон действует на витрину и вперёд. + +Привязка: BR-5, AC-7, BRD §6. + +### D6 (FR-7) — Анти-дрейф контур: `tests/test_system_docs.py` + +**Решение: один структурный модуль, детерминированный, без сети/LLM/subprocess** (образец — +`test_lite_setup_doc.py`/`test_bundled_setup_doc.py`). Нормативные семейства проверок (точная +нарезка по тест-функциям — за developer, `04-test-plan.yaml` дополняется на development): + +| TC | Проверка | Механика | +|----|----------|----------| +| TC-01 | Все 10 файлов витрины D1 существуют и непусты | `Path.exists()` + размер | +| TC-02 | Индекс: 3 маршрута аудиторий («Я заказчик» / «Я менеджер» / «Я разработчик») и норматив сопровождения присутствуют; из индекса по относительным ссылкам достижимы business / все 7 tech / presentation (AC-1) | regex-извлечение ссылок + подстроки | +| TC-03 | **Карта стадий = код:** каждый ключ `src.stages.STAGE_TRANSITIONS` (вкл. `deploy-staging`, `cancelled`) упомянут в `tech-pipeline.md`; порядок основной цепочки created→…→done — по возрастанию позиций вхождений; derive из импорта, не статичный список (паттерн ORCH-091) | `import src.stages` + поиск позиций | +| TC-04 | **Гейты = код:** имя exit-гейта каждого ребра (`qg` из `STAGE_TRANSITIONS`) упомянуто в `tech-pipeline.md`; под-гейты названы фактическими именами реестра `QG_CHECKS` (`check_security_gate`, `check_branch_mergeable`, `check_coverage_gate`, `check_staging_image_fresh`) и идут в нормативном порядке security → merge → coverage → image-freshness (порядок — фикс adr-0029, позиционный ассерт); рядом с под-гейтами есть маркер «не стадии» (врезки) | импорт `STAGE_TRANSITIONS` + `QG_CHECKS`, позиции подстрок | +| TC-05 | **Полнота 6 агентов:** derive из glob `.openclaw/agents/*.md` (не статичный список) — стем каждого файла упомянут в `tech-agents.md`; таблица эффортов сходится с config-дефолтами (поля class-default `agent_effort_`, ORCH-81) | glob + `import src.config` | +| TC-06 | **Валидность ссылок:** все относительные md-ссылки всех файлов витрины резолвятся в существующие файлы; обязательный список ссылок AC-6 (architecture/README, internals, PIPELINE_DOCS, HANDOFF_PROTOCOL, adr-реестр, LITE_SETUP, BUNDLED_SETUP, PRODUCT_VISION, CLAUDE.md) присутствует | regex `\[..\]\((..)\)` + `Path.exists()` относительно файла | +| TC-07 | **Гигиена:** полнотекстовый скан всех 10 файлов витрины — нет литералов центрального списка `FORBIDDEN` (импорт из `tests/test_no_host_hardcodes.py`, не копия) и секретоподобных значений (эвристика hex/base64 ≥ 32 симв., не плейсхолдер); нет ссылок на вне-репозиторные пути (`tasks/`, `memory/`) (AC-12) | `find_violations` + эвристика | +| TC-08 | **Слайдо-источник:** парс через `parse_slides` из `scripts/build_presentation.py` (один парсер — D4): ≥ 12 слайдов, нумерация сквозная с 1, на каждом ≥ 1 тезис; нормативные биты нарратива FR-4 присутствуют (подстроки: проблема/решение/сценарии/тираж/статус) | импорт чистой функции (прецедент `test_bootstrap_script.py`) | +| TC-09 | **NFR-2 машинно:** подстрока `pptx` отсутствует в `requirements*` и `Dockerfile` | чтение файлов | +| TC-10 | **Указатели:** `README.md` ссылается на `docs/overview/`; `CLAUDE.md` несёт указатель на витрину; `CHANGELOG.md` несёт `ORCH-011` | подстроки | + +Скоуп FORBIDDEN-скана — **полнотекстовый** (не только fenced, в отличие от ORCH-102 TC-05): +витрина по построению не дублирует дефолты/хост-специфику даже в прозе (NFR-3), упоминать +боевые литералы ей незачем → ложно-красных нет, а защита шире. Существующие тесты не +ослабляются; новые попадают в существующие гейты (`check_ci_green`/`check_tests_passed`/ +merge-gate re-test/coverage ORCH-027) автоматически — **новый QG НЕ регистрируется** (ТЗ §6). + +Привязка: BR-8, FR-7, AC-4, AC-5, AC-10, AC-11, AC-12. + +### D7 (исход OQ-5) — Reviewer-ось обзорных доков: точечная правка промпта НУЖНА + +**Решение: расширить существующую ось ORCH-079 в `.openclaw/agents/reviewer.md` точечной +врезкой, называющей витрину явно.** Обоснование: по букве ось привязана к `README.md` +«Известные ограничения» («если PR закрывает/меняет пункт из README…»); витрина под букву не +подпадает, а история ORCH-079 показала, что общего правила «документация = golden source» +для обзорных доков недостаточно — ось работает, когда названа явно (❌→✅-паттерн). Норматив +правки: + +- В оси 4 «Документация» и в соответствующем ❌→✅-пункте `` существующая + формулировка ORCH-079 дополняется: *PR меняет функциональность, описанную в витрине + `docs/overview/` (стадии, гейты, агенты, интеграции, способности из business.md), а витрина + не обновлена → finding ≥ P1* — **расширение трактовки той же оси, не новая ось**. +- Канон 52d сохраняется байт-в-байт: 5 XML-секций и их порядок не меняются, verdict-ключ + `verdict: APPROVED|REQUEST_CHANGES` не трогается; правка — добавление текста внутрь + существующих секций (паттерн самой ORCH-079). +- `tests/test_agent_prompts_canon.py` расширяется ассертом на упоминание витрины в оси + обзорных доков (анти-регресс; существующие ассерты остаются зелёными). +- Зеркальная правка правила №6 `CLAUDE.md` («Reviewer проверяет…») — упоминание витрины. + +Привязка: BR-7, FR-6, AC-9. + +### D8 — Индекс: маршруты аудиторий и норматив сопровождения; указатели репо + +**Маршруты (FR-5, нормативный состав):** индекс несёт три явных маршрута с упорядоченными +списками «что читать»: +- **«Я заказчик»:** `business.md` → сценарии → `presentation.md` → + `docs/deployment/LITE_SETUP.md`/`BUNDLED_SETUP.md`; +- **«Я менеджер проекта»:** `business.md` → `tech-pipeline.md` (конвейер, статусная модель + Plane, человеческие гейты) → `tech-observability.md`; +- **«Я разработчик»:** `tech-*` (1→7) → `docs/architecture/README.md` → `internals.md` → + `docs/_standards/` → реестр ADR → `CLAUDE.md`. + +**Норматив сопровождения (FR-6, формулировка по образцу NFR-5 ORCH-102/103):** в индексе — +явная норма «**изменил функциональность платформы → обнови витрину `docs/overview/` в том же +PR**» (+ указание, какой файл какому классу изменений соответствует). Указатели: +- `CLAUDE.md`: в правило №2 («Документация = golden source») добавляется указатель на витрину + и норматив; правка правила №6 — D7; строка о витрине в разделе «Структура» (`docs/`). +- `README.md`: ссылка на витрину в начале (рядом с «Архитектура») — «единая точка входа в + документацию системы». +- `CHANGELOG.md`: запись `docs:` по ORCH-011. + +Привязка: BR-6, BR-7, BR-9, FR-5, FR-6, AC-8, AC-9, AC-11. + +### D9 — Границы изменения; 07/08 — N/A; исход OQ-4; эскалация не требуется + +- **Дифф задачи:** `docs/overview/` (10 файлов, D1), `tests/test_system_docs.py` (D6), + `scripts/build_presentation.py` (D4), правки `.openclaw/agents/reviewer.md` + + `tests/test_agent_prompts_canon.py` (D7), `README.md`/`CLAUDE.md`/`CHANGELOG.md` (D8), + `.gitignore` (+`build/`, D5), ADR-пакет work item + сквозной adr-0039 + секция в + `docs/architecture/README.md`. **`src/**`, `docker-compose.yml`, `Dockerfile`, + `requirements*` — ноль изменений** (NFR-1; машинный гард — TC-09); любое отклонение — только + новым ADR. +- `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема БД — байт-в-байт; новых + эндпоинтов/флагов/kill-switch нет (выключать нечего: доки и dev-скрипт не исполняются + конвейером). +- **`07-infra-requirements.md` / `08-data-requirements.md` — N/A** (прецедент ORCH-102 D9): + топология не меняется (ни контейнера, ни порта, ни маунта), схема БД не меняется (ТЗ §5). + Dev-venv для генерации `.pptx` — не инфра-предусловие конвейера: создаётся ad-hoc человеком + при сборке презентации (процедура — `presentation.md`). +- **Исход OQ-4 (compiled-wiki/экспорт):** вне объёма v1 — зафиксировано; репозиторий — + единственный источник истины («канон не форкается», ORCH-009 BR-2). Follow-up work item не + заводится автоматически: потребность в wiki-экспорте — решение Владельца после приёмки + витрины (если витрина в репо закрывает D-2/D-3, экспорт не нужен вовсе). +- **Объём одного прогона (R-3):** допущение BRD §6 принимается; приоритет при дефиците объёма: + каркас+индекс → tech-pipeline/tech-agents (машинно-сверяемые) → business → остальные tech → + presentation+скрипт. Молчаливое сокращение запрещено — недоезд = эскалация разбиением. +- **Self-hosting (NFR-5):** прод-контейнер не рестартится; выкат — штатный конвейер + (deploy-staging 8501 → Confirm Deploy). Для enduro-trails изменение инертно (общих + артефактов нет). +- **Эскалация:** `arch:major-change` не требуется (нет новой стадии/компонента/смены БД — + docs-канон); ТЗ удовлетворимо без нарушения принципов — возврат в анализ не нужен. + +## Альтернативы + +- **Расширить `README.md` вместо нового раздела** — отвергнуто: README — тех-витрина с + собственной ролью (и осью ORCH-079); бизнес-уровень + 7 блоков + маршруты раздули бы его в + монолит против NFR-6; D-3 предполагает выделенное «единое место». +- **`docs/system/` как имя каталога** — отвергнуто: «overview» точнее передаёт роль (обзор для + входа), рекомендация аналитика, прецедентов коллизии нет. +- **Монолит `tech.md` (или пара business/tech)** — отвергнуто: блоки устаревают с разным + темпом; точечные правки и пофайловые ассерты тестов дешевле на 7 файлах (NFR-6). +- **Marp / pandoc для PPTX** — отвергнуто (D4): Node+Chromium-тулчейн и растровые слайды + (Marp) / ограниченная тёмная тема через бинарный reference-doc (pandoc); python-pptx даёт + редактируемый текст и код-как-дизайн с одним pip-пакетом вне прод-образа. +- **Коммитить собранный `.pptx`** — отвергнуто (D5): недиффуемый, тестами не проверяемый, + молча устаревает (живой пример — `PRODUCT_VISION.pptx` без пути генерации); BR-5 требует + воспроизводимость, не бинарь. +- **Жёсткий снапшот-тест контента витрины (хэши/полные списки компонентов)** — отвергнуто: + превратил бы каждую docs-правку в красный CI (ложная жёсткость); тесты держат только + машинно-проверяемые факты, derive из кода (стадии/гейты/агенты), остальное — за reviewer. +- **Не править промпт reviewer (положиться на общее правило)** — отвергнуто (D7): по букве ось + ORCH-079 привязана к README; сам ORCH-079 существует потому, что общего правила для обзорных + доков не хватило; одна строка расширения дешевле гниющей витрины. +- **Автогенерация витрины из кода (autodoc)** — отвергнуто: явно вне объёма (BRD §2.2); + derive-from-code остаётся в тестах (сверка), не в генерации текста. + +## Последствия + +- **+** Единая точка входа для трёх аудиторий закрывает корневую проблему фрагментации + (BRD §1.2); презентация собирается за одну команду из версионируемого источника. +- **+** Машинно-проверяемые факты витрины (стадии/гейты/агенты/ссылки/гигиена/чистота + prod-зависимостей) — CI-гарантии (TC-01…TC-10), а не обещания: дрейф ловится тестом, гниение + прозы — расширенной reviewer-осью (D7). +- **+** Нулевой риск рантайма: docs+tests+dev-скрипт, конвейер байт-в-байт, kill-switch не + нужен; для enduro-trails инертно. +- **−** Новый golden source = новая обязанность сопровождения каждого функционального PR — + принято осознанно (в этом смысл задачи), митигировано link-first (правится одна строка-резюме, + не трактат), нормативом в индексе/CLAUDE.md и осью reviewer. +- **−** Разрешённый машинно-сверяемый дубль (стадии/гейты/агенты в `tech-pipeline.md`/ + `tech-agents.md`) — двойная запись фактов кода; защищён derive-тестами TC-03…TC-05 + (прецедент TC-02b ORCH-102). +- **−** Правка промпта reviewer — расширение поверхности канона 52d; митигировано: только + добавление внутрь существующих секций, анти-регресс `test_agent_prompts_canon.py`. +- **−** `.pptx` не в репо — показ «здесь и сейчас» требует одной команды сборки; принято + (Владелец собирает deck при необходимости; альтернатива — гниющий бинарь — хуже). +- **Откат:** удалить `docs/overview/`, `tests/test_system_docs.py`, + `scripts/build_presentation.py`, вернуть точечные правки README/CLAUDE/CHANGELOG/.gitignore/ + reviewer.md — состояние 1:1, ни миграций, ни состояния (ТЗ §7). + +## Ссылки + +- BRD: `docs/work-items/ORCH-011/01-brd.md` (решения Владельца D-1…D-4, факты §1.2) +- TRZ: `docs/work-items/ORCH-011/02-trz.md` (FR-1…FR-7, OQ-1…OQ-5) +- Acceptance: `docs/work-items/ORCH-011/03-acceptance-criteria.md` (AC-1…AC-12) +- Риски: `docs/work-items/ORCH-011/10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0039-system-overview-docs-canon.md` +- Сверено по коду/репо: `src/stages.py::STAGE_TRANSITIONS` (9 стадий + `cancelled`), + `src/qg/checks.py::QG_CHECKS` (14 проверок), `.openclaw/agents/*.md` (6 промптов; ось + ORCH-079 в `reviewer.md`), `docs/PRODUCT_VISION.md` §1–2 (+ устаревшая схема конвейера §2), + `docs/PRODUCT_VISION.pptx` (бинарь без пути генерации), `tests/test_lite_setup_doc.py` / + `test_bundled_setup_doc.py` (паттерн структурных доков-тестов), + `tests/test_no_host_hardcodes.py` (`FORBIDDEN`, `find_violations`), + `tests/test_qg_registry_snapshot.py` (импорт QG_CHECKS), `tests/test_bootstrap_script.py` + (импорт чистых функций из `scripts/`), `.gitignore` +- Инварианты соседних решений: adr-0019 (стандарт доков), adr-0021/ORCH-092 (канон промптов + 52d), adr-0023 (ось обзорных доков ORCH-079), adr-0029 (порядок под-гейтов), adr-0037/0038 + (deployment-каноны — ссылаемся, не форкаем), ORCH-041/074/081 (модель/эффорт), + ORCH-066 (статусная модель), `docs/_standards/PIPELINE_DOCS.md` §4 (ADR-naming), + `docs/_standards/TRACEABILITY.md` (маркеры) diff --git a/docs/work-items/ORCH-011/10-tech-risks.md b/docs/work-items/ORCH-011/10-tech-risks.md new file mode 100644 index 0000000..5e63bd6 --- /dev/null +++ b/docs/work-items/ORCH-011/10-tech-risks.md @@ -0,0 +1,40 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-011 — Полная документация системы мультиагентов (витрина + PPTX) + +Work Item: **ORCH-011** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн. +> Базовые бизнес-риски R-1…R-5 — BRD §8; здесь — их техническая детализация + новые. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Гниение витрины** (R-1): self-hosting темп быстро устаревает снапшот; живой пример уже в репо — схема конвейера в `PRODUCT_VISION.md` §2 потеряла `deploy-staging`/`cancelled` | Выс. | Сред. | Машинно-проверяемые факты держат derive-тесты (ADR-001 D6 TC-03…TC-05: стадии/гейты/агенты импортом из кода); проза — норматив сопровождения в индексе + расширенная reviewer-ось (D7); link-first сводит правку к одной строке-резюме | +| TR-2 | **Второй источник истины** (R-2): дубль деталей architecture/README в витрине → противоречия | Сред. | Сред. | Норматив D3: запрещён дубль живых таблиц golden sources; разрешённый дубль — только машинно-сверяемый тестом факт (прецедент key-sync ORCH-102 TC-02b); контроль — AC-6 + reviewer | +| TR-3 | **Объём одного прогона** (R-3): 10 файлов + скрипт + тесты + правка промпта могут не поместиться в разумный PR | Сред. | Сред. | Модульность D1 (правки независимы); нормативный приоритет блоков при дефиците (D9); молчаливое сокращение запрещено — эскалация разбиением по штатному маршруту | +| TR-4 | **Утечка зависимости генерации в прод-образ** (R-4): `python-pptx` случайно попадает в `requirements*`/`Dockerfile` | Низ. | Выс. | Архитектура скрипта D4 (lazy import, запуск только вне рантайма); **машинный гард TC-09** (скан `requirements*`/`Dockerfile` на `pptx`) — попадание рвёт CI | +| TR-5 | **Ложная жёсткость анти-дрейф тестов:** слишком буквальные ассерты (точные фразы прозы) делают каждую будущую docs-правку красной → тесты начнут ослаблять | Сред. | Сред. | D6: ассерты только на стабильное (заголовки, имена из кода через импорт, относительные ссылки, биты-подстроки); снапшот-контента отвергнут явно (ADR-001 «Альтернативы») | +| TR-6 | **Регресс канона 52d при правке промпта reviewer** (D7): нарушение порядка секций / verdict-ключа | Низ. | Выс. | Правка — только добавление текста внутрь существующих секций (паттерн ORCH-079); анти-регресс `tests/test_agent_prompts_canon.py` (существующие ассерты + новый на упоминание витрины) | +| TR-7 | **Кириллица/тема в PPTX:** артефакт собирается, но рендеринг не «точный» (D-1): шрифт без кириллицы, контраст темы | Низ. | Сред. | python-pptx пишет редактируемый текст (не растр); шрифты — системные с полной кириллицей (Calibri/Arial); процедура в `presentation.md` несёт явную «Проверка:» (открыть файл, тема тёмная, кириллица читается); приёмка — AC-7 | +| TR-8 | **Парсер слайдо-источника расходится с тестом:** свой regex в тесте ≠ парсер скрипта → источник валиден для теста, но не собирается | Низ. | Сред. | Один парсер: тест импортирует `parse_slides` из `scripts/build_presentation.py` (D4/D6 TC-08; прецедент импорта из scripts — `test_bootstrap_script.py`) | +| TR-9 | **Цифры в бизнес-части не подтверждаются репо** (метрики скорости/стоимости из vision) → витрина теряет доверие / выдаёт желаемое за действительное | Сред. | Низ. | Норматив D2: числа только с внутрирепозиторным подтверждением или явной атрибуцией «оценка из PRODUCT_VISION»; новые цифры не изобретать (AC-12; reviewer проверяет) | +| TR-10 | **Путаница канона бинарей:** в репо остаётся `docs/PRODUCT_VISION.pptx` (старый паттерн), новый канон — «бинарь не коммитим» (D5) → будущий агент скопирует старый паттерн | Низ. | Низ. | Канон зафиксирован сквозным adr-0039 + нормативом в `presentation.md`; PRODUCT_VISION.pptx не трогается (чужой артефакт), но прецедентом не является — явная оговорка в ADR-001 D5 | + +## Сводный вывод + +Доминирующий класс — **риски сопровождения документации** (TR-1/TR-2/TR-5): изменение не несёт +рантайм-риска вовсе (docs+tests+dev-скрипт, `src/**` байт-в-байт, машинный гард TC-09), но +создаёт новый golden source, который без машинной сверки и явной reviewer-оси начал бы гнить с +первой же задачи. Митигация встроена в само решение (derive-тесты + link-first + норматив + +ось D7). Эскалация `arch:major-change` не требуется (нет новой стадии/компонента/смены БД); +возврат в анализ не нужен. Остаточный риск для прод-конвейера (self-hosting): **низкий** — +прод-контейнер не затрагивается, деплой штатным маршрутом, для enduro-trails изменение инертно. diff --git a/docs/work-items/ORCH-011/12-review.md b/docs/work-items/ORCH-011/12-review.md new file mode 100644 index 0000000..28048f8 --- /dev/null +++ b/docs/work-items/ORCH-011/12-review.md @@ -0,0 +1,106 @@ +--- +verdict: APPROVED +work_item: ORCH-011 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-11 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-011 +version: 1 +--- + +# Review ORCH-011 + +## Summary + +PR (`7f0298b`, ветка `feature/ORCH-011-`) создаёт витрину системы `docs/overview/` строго по +ADR-001 (D1–D9): 10 файлов плоского каталога (индекс + business + 7×tech-* + presentation), +dev-скрипт `scripts/build_presentation.py` (stdlib-парсер `parse_slides` + ленивый `import pptx`), +структурный анти-дрейф `tests/test_system_docs.py`, точечное расширение reviewer-оси ORCH-079 на +витрину (D7) + анти-регресс ассерт, указатели README/CLAUDE.md/PRODUCT_VISION/CHANGELOG, +сквозной `adr-0039` + секция в `docs/architecture/README.md`, `build/` в `.gitignore` (D5). + +Проверено по 4 осям: + +1. **Соответствие ТЗ (FR-1…FR-7, AC-1…AC-12)** — выполнено, детальная сверка ниже. Все 12 AC — PASS. +2. **Соответствие ADR** — реализация 1:1 с ADR-001 D1–D9 и adr-0039; исходы OQ-1…OQ-5 воплощены + (каталог `docs/overview/`, python-pptx вне прод-образа, бинарь не закоммичен, OQ-4 вне объёма, + правка промпта reviewer по канону 52d). Глобальные ADR не нарушены: канон 52d (adr-0021) — + 5 секций/порядок/verdict-ключ целы (зелёный `test_agent_prompts_canon.py`); ось ORCH-079 + (adr-0023) — расширена аддитивно, не ослаблена; порядок под-гейтов (adr-0029) в витрине — + фактический security → merge → coverage → image-freshness (позиционный тест). + **Трассировка (TRACEABILITY):** правка блока с чужим маркером ORCH-079 в `reviewer.md` сверена + с его ADR — инвариант не сломан, расширение зафиксировано собственным D7 + тестом. +3. **Качество кода** — `tests/test_system_docs.py`: 20 содержательных тест-функций, derive-сверки + импортом `STAGE_TRANSITIONS`/`QG_CHECKS`/glob промптов/class-default'ов config (не статика), + границы токенов стадий (`deploy` не матчится в `deploy-staging`), негативный самочек + секрет-эвристики, анти-выдумка имён гейтов по всем 10 файлам. `build_presentation.py` — + докстринги на всех публичных функциях, честные коды возврата, ImportError-подсказка. + **Полный регресс: `pytest tests/ -q` → 1873 passed, 0 failed.** +4. **Документация** — обновлена в том же PR (см. раздел ниже). `src/**` НЕ изменён + (docs+tests+dev-скрипт), P0-правило «src без доки» неприменимо и не нарушено. + +Сверка машинных фактов витрины с кодом (независимо от тестов): +- стадии/exit-гейты таблицы `tech-pipeline.md` = `src/stages.py::STAGE_TRANSITIONS` байт-в-байт + (`check_analysis_approved` … `check_deploy_status`, `done`/`cancelled` — терминалы); +- таблица модель/эффорт `tech-agents.md` = `src/config.py` (default `claude-opus-4-8`; + developer=`xhigh`, tester/deployer=`medium`, прочие=`high`); +- verdict-ключи ролей (`verdict:`/`result:`/`staging_status:`/`deploy_status:`) = канон AC-5; +- бинарь `.pptx` в diff отсутствует; `pptx` в `requirements*`/`Dockerfile` отсутствует (NFR-2); +- `docker-compose.yml`/`Dockerfile`/`requirements*`/схема БД/`QG_CHECKS` — ноль изменений (AC-11). + +## Findings + +### P0 — Blocker +Нет. + +### P1 — Must fix +Нет. + +### P2 — Should fix +Нет. + +### P3 — Nice to have +- [ ] `docs/overview/tech-pipeline.md`, раздел «Статусная модель Plane»: «Управляющих статусов + ровно три: запуск в работу, Approved/Confirm Deploy … и STOP» — фактически перечислены четыре + статуса в трёх группах; формулировка «три управляющих воздействия (запуск, человеческие гейты, + отмена)» была бы точнее. Косметика прозы, машинных фактов не искажает (привязка: AC-4/FR-3.2 — + согласованность трактовок; не блокирует). +- [ ] `04-test-plan.yaml` не дополнен на development (норматив ADR-001 D6 «точная нарезка по + тест-функциям — за developer, 04-test-plan.yaml дополняется на development»). Решение developer + консервативно-корректное: правило №3 CLAUDE.md запрещает править артефакты других этапов, а все + TC-01…TC-14 плана реализованы 1:1 (маппинг «план TC-NN» зафиксирован в докстрингах + `test_system_docs.py`, TC-14 = полный зелёный регресс) — tester может работать по плану как есть. + Фиксирую как observation для будущего уточнения норматива, не как дефект. + +## Сверка по критериям приёмки + +| AC | Вердикт | Основание | +|----|---------|-----------| +| AC-1 точка входа | PASS | индекс `docs/overview/README.md`; все части достижимы (тест `test_index_links_reach_every_showcase_part`) | +| AC-2 бизнес-уровень | PASS | 5 разделов + 6 сценариев (≥5); без необъяснённого жаргона; цифра «35 минут» с атрибуцией Product Vision (D2) | +| AC-3 7 тех-блоков | PASS | 7 файлов `tech-*`; ASCII-схема потока «вебхук → очередь → агент → гейт → переход» в блоке 1 | +| AC-4 стадии/гейты = код | PASS | сверено с `src/stages.py` напрямую + derive-тесты (стадии, порядок цепочки, имена гейтов, порядок под-гейтов, маркер «не стадии») | +| AC-5 6 агентов | PASS | паспорта ролей + verdict-ключи + таблица модель/эффорт = config (сверено с `src/config.py`) | +| AC-6 link-first | PASS | все 9 обязательных golden-source ссылок присутствуют и резолвятся (тесты); живые таблицы не форкнуты | +| AC-7 презентация | PASS | 16 слайдов «## Слайд N:», нарратив полный; процедура «команда + Проверка:» ×3 шага; `pptx` вне прод-образа; бинарь не закоммичен | +| AC-8 3 маршрута | PASS | «Я заказчик / Я менеджер / Я разработчик» с упорядоченными списками по FR-5/D8 | +| AC-9 норматив | PASS | норма «в том же PR» + таблица «класс изменения → файл» в индексе; CLAUDE.md правила №2/№6; D7 разрешён правкой промпта + тест | +| AC-10 анти-дрейф | PASS | `tests/test_system_docs.py` покрывает все семейства D6; `pytest tests/ -q` → 1873 passed | +| AC-11 рантайм не тронут | PASS | diff: ноль изменений `src/**`/compose/Dockerfile/requirements; указатели обновлены; FORBIDDEN-скан зелёный | +| AC-12 самодостаточность | PASS | запрет `tasks/`/`memory/` — тест зелёный; источники внутрирепозиторные | + +## Документация + +Изменение само является документационным; все сопутствующие обязательства выполнены в том же PR: + +- **Обновлено:** `CHANGELOG.md` (детальная `docs:`-запись ORCH-011), `README.md` (ссылка на + витрину), `CLAUDE.md` (строка «Структура», правила №2 и №6), `docs/PRODUCT_VISION.md` + (врезка-ссылка «фактическое состояние — витрина», vision не переписан — по ТЗ §2), + `docs/architecture/README.md` (секция витрины), ADR-пакет: work-item + `06-adr/ADR-001-system-overview-canon.md` + сквозной `adr-0039-system-overview-docs-canon.md`. +- **Обзорные доки (ORCH-079):** «Известные ограничения» README данный PR не закрывает — + обновления не требуется. Сама ось расширена на новую витрину (D7) с анти-регресс тестом. +- **Дополнительно обновлять нечего:** API/env/конфигурация/QG/схема БД не менялись (ТЗ §4–§6). diff --git a/docs/work-items/ORCH-011/13-test-report.md b/docs/work-items/ORCH-011/13-test-report.md new file mode 100644 index 0000000..e9d1361 --- /dev/null +++ b/docs/work-items/ORCH-011/13-test-report.md @@ -0,0 +1,79 @@ +--- +result: PASS +work_item: ORCH-011 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-11 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-011 +--- + +# Test Report — ORCH-011 + +Полная документация системы мультиагентов: витрина `docs/overview/` + структурный анти-дрейф. + +## Окружение +- Worktree (код ветки): `/repos/_wt/orchestrator/feature_ORCH-011-` (ветка `feature/ORCH-011-`) +- Python: 3.12.13 +- pytest: 8.3.3 +- Дата: 2026-06-11 +- Предусловие: `12-review.md` → `verdict: APPROVED` ✅ + +## Smoke API (read-only) +| Эндпоинт | Результат | +|----------|-----------| +| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` | +| `GET /status` | PASS — задача ORCH-011 активна на стадии `testing` | +| `GET /queue` | PASS — payload несёт блоки `serial_gate` (ORCH-088) **и** `auto_labels` (наряду с `coverage`/`stop`/`bug_fast_track`/`lessons`) — регресса смока нет | + +## Результаты (покрытие test-plan ↔ acceptance-criteria) + +Изменение — docs+tests+dev-скрипт; анти-дрейф витрины реализован в `tests/test_system_docs.py` +(28 содержательных тест-функций), полностью зелёном. Каждый TC из `04-test-plan.yaml` выполнен и +сопоставлен с критериями `03-acceptance-criteria.md`. + +| TC ID | Описание | AC | Тест-функция(и) `test_system_docs.py` | Результат | +|-------|----------|----|----------------------------------------|-----------| +| TC-01 | Каталог витрины + индекс с обязательными разделами | AC-1 | `test_all_showcase_files_exist_and_nonempty`, `test_index_carries_maintenance_normative` | PASS | +| TC-02 | Из индекса достижимы все части витрины | AC-1/AC-3 | `test_index_links_reach_every_showcase_part` | PASS | +| TC-03 | Бизнес-часть: 5 разделов + ≥5 сценариев | AC-2 | `test_business_part_has_five_mandatory_sections`, `test_business_part_has_at_least_five_scenarios` | PASS | +| TC-04 | Тех-часть: 7 блоков + схема потока | AC-3 | `test_architecture_block_carries_flow_diagram` (+ link-reach) | PASS | +| TC-05 | Стадии сверены импортом `STAGE_TRANSITIONS` (derive) | AC-4 | `test_every_stage_from_code_is_mentioned_in_pipeline_doc`, `test_main_chain_order_in_pipeline_doc_matches_code` | PASS | +| TC-06 | Имена exit-гейтов существуют в `QG_CHECKS` | AC-4 | `test_every_exit_gate_from_code_is_named_in_pipeline_doc`, `test_no_invented_gate_names_anywhere_in_showcase`, `test_subgates_in_normative_order_and_marked_as_insets` | PASS | +| TC-07 | 6 ролей + артефакты + таблица модель/эффорт = config | AC-5 | `test_every_agent_prompt_stem_is_covered`, `test_effort_table_matches_config_class_defaults` | PASS | +| TC-08 | Все ссылки резолвятся + обязательные golden sources | AC-6 | `test_all_relative_links_resolve_to_existing_files`, `test_mandatory_golden_source_links_present` | PASS | +| TC-09 | Нет вне-репозиторных путей (`tasks/`/`memory/`/абс. хоста) | AC-12 | `test_no_out_of_repo_references` | PASS | +| TC-10 | Презентация: ≥12 нумерованных слайдов + нарратив | AC-7 | `test_presentation_source_parses_with_canonical_parser`, `test_presentation_covers_mandatory_narrative_bits`, `test_presentation_carries_reproducible_build_procedure` | PASS | +| TC-11 | Зависимости генерации (`python-pptx`) вне прод-образа | AC-7/NFR-2 | `test_no_pptx_dependency_in_prod_image`, `test_build_script_toplevel_imports_are_stdlib_only` | PASS | +| TC-12 | Норматив «в том же PR» + ссылки README/CLAUDE.md | AC-9/AC-11 | `test_index_carries_maintenance_normative`, `test_repo_readme_links_overview`, `test_claude_md_carries_overview_pointer_and_normative`, `test_changelog_has_orch_011_entry` | PASS | +| TC-13 | FORBIDDEN-скан хост-литералов + секрет-эвристика | AC-10/AC-11 | `test_showcase_carries_no_forbidden_host_literals`, `test_showcase_carries_no_secret_like_values`, `test_secret_heuristic_is_not_evergreen` | PASS | +| TC-14 | Полный регресс `pytest tests/` зелёный; существующие док-тесты не сломаны | AC-10/AC-11 | весь прогон `tests/` (вкл. `test_lite_setup_doc`/`test_bundled_setup_doc`/`test_orch_52b_docs_standard`/`test_agent_prompts_canon`) | PASS | + +Также покрыты `test_index_carries_three_audience_routes` (AC-8 — 3 маршрута аудиторий). + +## Вывод pytest + +Модуль витрины: +``` +$ python3 -m pytest tests/test_system_docs.py -v +... +======================== 28 passed, 1 warning in 0.43s ========================= +``` + +Полный регресс: +``` +$ cd /repos/_wt/orchestrator/feature_ORCH-011- && pytest tests/ -v --tb=short +... +================== 1873 passed, 1 warning in 71.36s (0:01:11) ================== +``` + +(Единственный warning — преэкзистентный `PydanticDeprecatedSince20` в `src/config.py:8`, +не связан с ORCH-011, к коду ветки не относится.) + +## Итог + +PASS — все 14 TC выполнены и сопоставлены с критериями приёмки (AC-1…AC-12), smoke read-only +зелёный (`serial_gate` + `auto_labels` присутствуют в `/queue`), полный регресс `tests/` — +**1873 passed, 0 failed**. Стадия переходит на `deploy-staging`. diff --git a/docs/work-items/ORCH-011/14-deploy-log.md b/docs/work-items/ORCH-011/14-deploy-log.md new file mode 100644 index 0000000..90fa5e4 --- /dev/null +++ b/docs/work-items/ORCH-011/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-011 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM. 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)" + )