Files

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

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

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

Refs: ORCH-011

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

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

5.5 KiB

Raw Blame History

Блок 4. Структура объектов: каноническая модель

Источник истины — фактическая схема SQLite в src/db.py и реестр проектов в src/projects.py; подробное описание таблиц — internals, «Database Schema».

Каноническая модель

Project ──1:N──► Work-Item / Task ──1:N──► Job ──1:N──► Agent-run
   │                    │
   │                    └── артефакты задачи (docs/work-items/<ID>/)
   └── Plane-проект ↔ git-репозиторий ↔ префикс задач

Project — проект в реестре

Связка «Plane-проект ↔ git-репозиторий ↔ префикс задач» (например, ORCH-). Реестр живёт в конфиге (src/projects.py): один инстанс платформы обслуживает несколько проектов; по префиксу задачи платформа находит репозиторий и настройки.

Work-Item / Task — задача конвейера

Строка таблицы tasks: текущая стадия (stage), маршрут (track: полный или багфикс), рабочая ветка, счётчики откатов, отметки отмены. Натуральные ключи — ID задачи в Plane и человекочитаемый номер (ORCH-NNN). На каждой стадии задача накапливает артефакты — номерные документы в docs/work-items/<ID>/ (от бизнес-запроса до deploy-лога; манифест — PIPELINE_DOCS).

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)
Гейт (exit-гейт)	Машинная проверка выхода со стадии; реестр — `QG_CHECKS`
Под-гейт	Проверка-врезка внутри перехода (не стадия); см. деплойное ребро в блоке 2
Job	Единица работы в очереди; задача порождает job'ы по мере продвижения
Worktree	Изолированная рабочая копия репозитория для ветки задачи
Lease (merge-lease)	Эксклюзивная блокировка «кто сейчас мержит этот репозиторий» — сериализация слияний
Track (маршрут)	Вариант пути задачи: полный цикл или багфикс с пропуском проектирования
Freeze	Заморозка очереди репозитория после инцидента до ручного разбора

Как объекты двигаются по конвейеру — блок 2; кто их создаёт — агенты; как за ними наблюдать — блок 7.

5.5 KiB Raw Blame History Unescape Escape