admin/orchestrator

Fork 0

Files

claude-bot 58e5dfe55d

CI / test (push) Successful in 1m15s

Details

CI / test (pull_request) Successful in 1m12s

Details

docs(serial-gate): sync system showcase + clean stray tags (ORCH-124)

Addresses reviewer REQUEST_CHANGES (run 768) on ORCH-124 — docs-only,
no src/tests touched, fix scope unchanged.

P1: update docs/overview/ showcase for the new serial-gate "pause without
blocking" axis (changed task-routing functionality, ORCH-011/ORCH-079):
- tech-pipeline.md: FIFO exception "pause without blocking" next to freeze
- tech-data-model.md: durable signal tasks.paused_at on the Task row
- tech-observability.md: paused/reason in serial_gate GET /queue block +
  operator endpoints POST /serial-gate/pause|resume

P2: strip leaked tool-call trailing tags (</content>/</invoke>) from 4
golden-source docs of this PR (06-adr/ADR-001, adr-0051,
08-data-requirements.md, 10-tech-risks.md).

CHANGELOG "Доки" bullet extended accordingly. Full suite green (2178 passed);
test_system_docs.py green (machine-checked showcase facts intact).

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

2026-06-16 21:50:45 +03:00

5.9 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: полный или багфикс), рабочая ветка, счётчики откатов, отметки отмены и паузы (paused_at — durable-сигнал «пропустить меня в serial gate», не терминальный). Натуральные ключи — 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`	машинный журнал уроков — структурированные отклонения конвейера
`transition_lease`	durable-владение side-effectful переходом стадии: один владелец на задачу, liveness по pid+boot-id (предотвращает двойное применение необратимых эффектов)

Все изменения схемы — аддитивные и идемпотентные (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.9 KiB Raw Blame History Unescape Escape