From 47479a9b7528ce330ac95f2651127c24d7d9c983 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Thu, 11 Jun 2026 08:47:02 +0300 Subject: [PATCH] analyst(ET): auto-commit from analyst run_id=632 --- docs/work-items/ORCH-011/01-brd.md | 199 ++++++++++++++++++ docs/work-items/ORCH-011/02-trz.md | 191 +++++++++++++++++ .../ORCH-011/03-acceptance-criteria.md | 187 ++++++++++++++++ docs/work-items/ORCH-011/04-test-plan.yaml | 117 ++++++++++ 4 files changed, 694 insertions(+) create mode 100644 docs/work-items/ORCH-011/01-brd.md create mode 100644 docs/work-items/ORCH-011/02-trz.md create mode 100644 docs/work-items/ORCH-011/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-011/04-test-plan.yaml 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