Compare commits
1 Commits
feature/OR
...
feat/ORCH-
| Author | SHA1 | Date | |
|---|---|---|---|
|
8a292b9d33 |
45
.env.example
45
.env.example
@@ -1,8 +1,4 @@
|
||||
ORCH_PLANE_API_URL=http://plane-app-api-1:8000
|
||||
# External (browser) web URL of Plane for clickable issue links in notifications
|
||||
# (ORCH-017). Falls back to ORCH_PLANE_API_URL; a loopback fallback is treated as
|
||||
# "no web URL" and the Plane link is omitted. Example: https://plane.example.org
|
||||
ORCH_PLANE_WEB_URL=
|
||||
ORCH_PLANE_API_TOKEN=
|
||||
ORCH_PLANE_WORKSPACE_SLUG=
|
||||
ORCH_PLANE_WEBHOOK_SECRET=
|
||||
@@ -12,44 +8,3 @@ ORCH_GITEA_WEBHOOK_SECRET=
|
||||
ORCH_CLAUDE_BIN=/usr/bin/claude
|
||||
ORCH_REPOS_DIR=/home/slin/repos
|
||||
ORCH_DB_PATH=/app/data/orchestrator.db
|
||||
# ORCH-042: live-tracker mode. edit (DEFAULT) -> the task card is edited in place
|
||||
# (editMessageText). bump -> on every update the old card is deleted and a fresh
|
||||
# one is sent silently to the BOTTOM of the chat (deleteMessage + sendMessage +
|
||||
# repoint). One card per task in both modes. Any value other than "bump" -> edit.
|
||||
ORCH_TRACKER_MODE=edit
|
||||
# ORCH-043: merge-gate (auto-rebase onto current origin/main + re-test + merge-lock)
|
||||
# on the deploy-staging -> deploy edge. Deterministic sub-gate (no LLM) that catches
|
||||
# the branch up to the CURRENT origin/main, re-tests it, and serialises merges so two
|
||||
# green parallel branches can't break main.
|
||||
# ENABLED -> global kill-switch (false -> whole gate is a no-op pass).
|
||||
# REPOS -> CSV of repos where the gate is REAL; empty -> only the self-hosting
|
||||
# repo (orchestrator); other repos -> conditional no-op (mirrors ORCH-35).
|
||||
# RETEST_TIMEOUT_S -> wall-clock budget for the post-rebase re-test.
|
||||
# RETEST_TARGET -> pytest target for the re-test.
|
||||
# LOCK_TIMEOUT_S -> max merge-lease age before a stale lease is reclaimed.
|
||||
# DEFER_DELAY_S -> delay before re-running the gate when the lock is busy.
|
||||
# DEFER_MAX_ATTEMPTS -> defer retries before escalation (avoids livelock).
|
||||
ORCH_MERGE_GATE_ENABLED=true
|
||||
ORCH_MERGE_GATE_REPOS=
|
||||
ORCH_MERGE_RETEST_TIMEOUT_S=600
|
||||
ORCH_MERGE_RETEST_TARGET=tests/
|
||||
ORCH_MERGE_LOCK_TIMEOUT_S=300
|
||||
ORCH_MERGE_DEFER_DELAY_S=60
|
||||
ORCH_MERGE_DEFER_MAX_ATTEMPTS=5
|
||||
|
||||
# ORCH-053: stuck-task reconciler (sweeper for lost webhooks). A background daemon
|
||||
# replays a missed stage transition through the SAME gates/handlers a webhook would,
|
||||
# fixing tasks that got stuck on a dropped event (502 on rebuild, no Plane/Gitea
|
||||
# retries, unresolved sha->branch).
|
||||
# ENABLED -> global kill-switch (self-hosting safety / staged rollout).
|
||||
# PLANE_ENABLED -> separate flag for the F-2 Plane-API poll (mute only F-2).
|
||||
# INTERVAL_S -> background sweep period (seconds).
|
||||
# GRACE_DEFAULT_S -> default "stuck" threshold on tasks.updated_at (seconds).
|
||||
# GRACE_OVERRIDES_JSON -> per-stage thresholds, e.g. {"development":300}; bad JSON -> default.
|
||||
# NOTIFY_UNBLOCK -> send a Telegram message when a stuck task is unblocked.
|
||||
ORCH_RECONCILE_ENABLED=true
|
||||
ORCH_RECONCILE_PLANE_ENABLED=true
|
||||
ORCH_RECONCILE_INTERVAL_S=120
|
||||
ORCH_RECONCILE_GRACE_DEFAULT_S=600
|
||||
ORCH_RECONCILE_GRACE_OVERRIDES_JSON=
|
||||
ORCH_RECONCILE_NOTIFY_UNBLOCK=true
|
||||
|
||||
@@ -21,20 +21,10 @@ On stage `deploy-staging` your job is to run the staging test suite and write a
|
||||
|
||||
### Steps:
|
||||
|
||||
1. Run the staging test suite against the live staging environment.
|
||||
**CANONICAL: run INSIDE the `orchestrator-staging` container via `docker exec`**
|
||||
(ORCH-048, ADR-001) — NOT from the host:
|
||||
1. Run the staging test suite against the live staging environment:
|
||||
```bash
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
Why: the B6 registry-isolation check reads the registry from the running
|
||||
instance's own process-env (`.env.staging`). Running from the host leaves
|
||||
`ORCH_PROJECTS_JSON` unset → B6 falls back to the default (ET+ORCH) registry
|
||||
→ false FAIL → spurious rollback. The script path is `/repos/orchestrator/scripts/…`
|
||||
(bind-mount); `scripts/` is NOT copied into the image, so `/app/scripts` does
|
||||
not exist. Details: `docs/operations/STAGING_CHECK.md`.
|
||||
|
||||
2. Check the exit code:
|
||||
- Exit code **0** = all tests PASS → `staging_status: SUCCESS`
|
||||
|
||||
10
CHANGELOG.md
10
CHANGELOG.md
@@ -5,12 +5,6 @@
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- **Sweeper потерянных webhook (реконсиляция застрявших стадий)** (ORCH-053): фоновый daemon-поток `src/reconciler.py` (паттерн `queue_worker`), который устраняет тихое застревание задач, когда конвейер не двигается из-за потерянного события (502 на ребилде инстанса, отсутствие ретраев у Plane/Gitea, неразрезолвленный `sha→branch` — класс инцидента ORCH-044). Реконсилятор периодически (`reconcile_interval_s`) доигрывает пропущенный переход **через те же штатные гейты/обработчики**, что и webhook, не дублируя логику конвейера: **F-1 gate-side** (`reconcile_gate_once`) — для задач `stage≠done`, без активного job и `age(updated_at) ≥ grace_for_stage(stage)` делает read-only пред-оценку канонического QG стадии; зелёный → продвижение строго через неизменный `stage_engine.advance_stage(..., finished_agent=None)`; красный → тишина (спам нотификаций структурно невозможен — `advance_stage` на красном гейте не вызывается вовсе); `analysis` F-1 не трогает (человеческий гейт). **F-2 plane-side** (`reconcile_plane_once`) — опрос Plane API per-project (новый `plane_sync.list_issues_by_state`, курсорная пагинация, never-raise) и реплей In Progress / Approved / Rejected через существующие `webhooks.plane.handle_status_start` / `handle_verdict` (async-обработчики вызываются из sync-потока через `asyncio.run`). **F-3** — усиление `sha→branch` в `handle_ci_status`: при неразрезолвленном sha — БД-fallback по единственной development-задаче repo (`db.get_development_tasks_by_repo`; неоднозначность → не резолвим, ложного матча нет), `logger.debug`→`logger.info` для видимости потерянного CI-события. Анти-дубль на создании задачи (`db.create_task_atomic` под process-wide `threading.Lock`: SELECT-exists→INSERT, проигравший в гонке reconcile↔webhook не плодит второй task/branch/worktree/стартовый analyst-job). Старт/стоп в `main.lifespan` (после `worker.start()` / перед `worker.stop()`), restart-safe, never-raise на единицу работы. Наблюдаемость (F-4): при разблокировке — лог-строка `reconciler: <wi> <stage> разблокирована (потерян webhook)` + Telegram (`reconcile_notify_unblock`) и блок `reconcile` в `GET /queue`. Kill-switches: `ORCH_RECONCILE_ENABLED` (глобально), `ORCH_RECONCILE_PLANE_ENABLED` (гасит только F-2), `ORCH_RECONCILE_INTERVAL_S` (120), `ORCH_RECONCILE_GRACE_DEFAULT_S` (600), `ORCH_RECONCILE_GRACE_OVERRIDES_JSON` (per-stage), `ORCH_RECONCILE_NOTIFY_UNBLOCK` (true). Схема БД и реестры (`STAGE_TRANSITIONS`/`QG_CHECKS`) НЕ менялись. ADR `docs/work-items/ORCH-053/06-adr/ADR-001-stuck-task-reconciler.md`, глобальный `docs/architecture/adr/adr-0007-reconciler.md`. Тесты: `tests/test_reconciler.py`, `tests/test_reconciler_plane.py`, `tests/test_gitea_sha_resolve.py`, `tests/test_config.py`.
|
||||
- **Merge-gate: авто-rebase на текущий `origin/main` + повторный прогон тестов + сериализация мержей** (ORCH-043): детерминированный (без LLM) суб-гейт на ребре `deploy-staging → deploy`, выполняемый ПЕРЕД мержем PR деплоером. Закрывает класс гонок «две зелёные ветки в одном репо ломают `main`»: пайплайн валидирует ветку против того `main`, от которого она ответвилась, а не против `main` в момент мержа — между «ветка зелёная» и «ветка смержена» параллельная задача может сдвинуть `main` (семантический конфликт: git мержит без текстового конфликта, но совмещённый `main` красный). Для self-hosting репозитория `orchestrator` это означало бы красный `main` инструмента, обслуживающего ВСЕ проекты. Новый модуль `src/merge_gate.py` (контракт «never raise», все git-операции — в per-branch worktree, ORCH-2/S-4): `branch_is_behind_main` (`git merge-base --is-ancestor origin/main HEAD`), `auto_rebase_onto_main` (rebase + `git push --force-with-lease` ТОЛЬКО ветки задачи — `main` НИКОГДА не пушится; текстовый конфликт → `rebase --abort` + чистый worktree), `retest_branch` (`python -m pytest <target>` в догнанном worktree, бюджет `merge_retest_timeout_s`), файловый merge-lease (`acquire_merge_lease`/`release_merge_lease`, атомарный `O_CREAT|O_EXCL`, holder-aware release, реклейм протухшего/битого лиза — без изменения схемы БД). Новый quality-gate `check_branch_mergeable` (`src/qg/checks.py`, зарегистрирован в `QG_CHECKS`) композирует примитивы под лизом: kill-switch/вне-области → no-op pass; lock занят → `(False, "merge-lock busy")` (сигнал DEFER, не код-фолт); ветка свежая → pass (лиз ДЕРЖИТСЯ до мержа); отстала → rebase → конфликт = fail+release, чисто → retest → зелёный = pass (лиз держится) / красный|timeout = fail+release. Интеграция в `src/stage_engine.py` (суб-гейт на `deploy-staging`, БЕЗ новой стадии в `STAGE_TRANSITIONS`): pass → advance на `deploy`; «merge-lock busy» → DEFER (повторная постановка деплоера на `deploy-staging` с задержкой `available_at`, анти-дедлок при `max_concurrency=1`, restart-safe счётчик по `task_content`, лимит `merge_defer_max_attempts` → block+Telegram); конфликт/красный retest → ROLLBACK на `development` + ретрай developer-а (кап `MAX_DEVELOPER_RETRIES`, без бесконечного баунса). Лиз освобождается на `deploy→done`, на rollback и по webhook смерженного PR (`src/webhooks/gitea.py`). Новый параметр `enqueue_job(..., available_at_delay_s=...)` (`src/db.py`) — отложенная постановка без изменения схемы. Условность раскатки (зеркало ORCH-35): `merge_gate_repos` (CSV) или по умолчанию только self-hosting `orchestrator`; глобальный kill-switch `merge_gate_enabled`. Новые настройки `ORCH_MERGE_GATE_ENABLED` (true), `ORCH_MERGE_GATE_REPOS` (""), `ORCH_MERGE_RETEST_TIMEOUT_S` (600), `ORCH_MERGE_RETEST_TARGET` (tests/), `ORCH_MERGE_LOCK_TIMEOUT_S` (300), `ORCH_MERGE_DEFER_DELAY_S` (60), `ORCH_MERGE_DEFER_MAX_ATTEMPTS` (5). ADR `docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md`, глобальный `docs/architecture/adr/adr-0006-merge-gate.md`. Тесты: `tests/test_merge_gate.py`, `tests/test_qg_merge_gate.py`, `tests/test_merge_gate_race.py`, `tests/test_stage_engine.py::TestMergeGate`, `tests/test_config.py`.
|
||||
- **Режим `bump` live-трекера Telegram** (ORCH-042): новый `ORCH_TRACKER_MODE` (`Settings.tracker_mode`, дефолт `edit`) выбирает поведение карточки задачи. `edit` (как было) — карточка редактируется на месте (`editMessageText`). `bump` — на каждом обновлении старое сообщение удаляется и карточка отправляется заново вниз чата (best-effort `delete_telegram(старый_id)` → `send_telegram(text, disable_notification=True)` → `set_tracker_message_id(new_id)`), чтобы актуальный статус всегда был последним в чате при активной переписке. Инвариант «одна карточка на задачу» сохранён в обоих режимах: за один вызов `update_task_tracker` шлётся ≤1 нового сообщения; `set_tracker_message_id` вызывается ТОЛЬКО при успешном send (транзиентный `None` не затирает указатель); результат delete НЕ блокирует отправку новой карточки (delete-fail у сообщения >48ч → всё равно шлём новое). Резолюция режима в `notifications` (case-insensitive, trim): всё, что ≠ `"bump"` (включая пустое/мусор) → `edit` → нулевая регрессия и оркестратор не падает на любом значении флага. Новый low-level helper `delete_telegram(message_id) -> bool` (контракт «never raises», маркеры `_DELETE_GONE_MARKERS`): `ok:true` или «уже нет / нельзя удалить» → `True`; неизвестный `ok:false`/5xx/исключение → `False`; нет кредов → `False` без HTTP. Сигнатуры `send_telegram`/`edit_telegram`/`update_task_tracker` и схема БД (`tasks.tracker_message_id`) не менялись. ADR `docs/work-items/ORCH-042/06-adr/ADR-001-tracker-bump-mode.md`. Тесты: `tests/test_tracker_bump.py`, `tests/test_config.py`.
|
||||
- **Дословный текст findings reviewer/tester встраивается в `task_desc` заворота** (ORCH-046): при откате на `development` строка `task_desc` (попадает в `.task-dev.md` developer-агента) теперь несёт суть претензий, а не только ссылку на файл — устраняет «испорченный телефон», из-за которого агент шёл «читать файл», терял ключевые P0/P1 / причину FAIL и заворачивался снова, выжигая `MAX_DEVELOPER_RETRIES` и токены. Новый defensive-модуль `src/review_parse.py` (контракт «never raise», как `src/frontmatter.py`): `extract_review_findings(path)` — дословные пункты P0/P1 из секции `## Findings` файла `12-review.md`; `extract_test_failures(path)` — релевантный фрагмент тела `13-test-report.md` (приоритет `## Вывод pytest` → FAIL-строки `## Результаты` → `## Итог`). Обе функции усекают результат до `MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS` (≈2000) с маркером `…(truncated)`. Две rollback-ветки `src/stage_engine.py` (reviewer REQUEST_CHANGES, tester `check_tests_passed` FAIL) встраивают извлечённый текст и **сохраняют ссылку** на полный файл («Полный контекст»); при пустом/битом артефакте — graceful-фоллбэк на прежнюю ссылку-строку (никаких исключений в `advance_stage`). Tester-ветка дополнительно всегда включает `reason` гейта. Последовательность отката, `_developer_retry_count`, поля `AdvanceResult` и реестр `QG_CHECKS` не менялись. ADR `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md`. Тесты: `tests/test_review_parse.py`, `tests/test_stage_engine.py::TestRollbackTaskDescEmbedding`.
|
||||
- **Поллинг с ретраем в quality-gate `check_ci_green`** (ORCH-045): гейт CI превращён из single-shot в polling, чтобы устранить race condition — раньше один опрос combined commit-status сразу после пуша developer-а ловил транзиентный `pending` (типично 1-3с, реальный кейс ORCH-017: опрос 17:58:54 → pending, CI дозеленел 17:58:55) и задача застревала насмерть без повторного опроса. Теперь: `success` → пропуск сразу; `failure`/`error` → провал сразу (терминально, ретрай бессмыслен); `pending`/unknown → `time.sleep` и повторный опрос до `ci_poll_max_attempts` раз; истечение попыток → явный `(False, "CI still pending after <T>s")` (тупик больше не молчаливый); 404 → как раньше; транзиентная `httpx.HTTPError` на попытке логируется и ретраится в рамках бюджета. Параметры — новые настройки `ORCH_CI_POLL_MAX_ATTEMPTS` (12) и `ORCH_CI_POLL_INTERVAL_S` (10) в `src/config.py` (~2 мин ожидания pending). Сигнатура `check_ci_green(repo, branch)` и реестр `QG_CHECKS` не менялись; `check_tests_passed` не затронут. ADR `docs/architecture/adr/adr-0004-ci-poll-retry.md`. Тесты: `tests/test_qg.py::TestCheckCIGreen`.
|
||||
- **Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве** (ORCH-017): пингующее сообщение `notify_approve_requested` теперь встраивает две HTML-`<a>`-ссылки — на `docs/work-items/<WI>/01-brd.md` (Gitea branch-view: `gitea_public_url`→`gitea_url`) и на issue в Plane (`{web_base}/{workspace}/projects/{project_id}/issues/{plane_issue_id}/`). Новая настройка `ORCH_PLANE_WEB_URL` (внешний браузерный web-URL Plane; фолбэк на `plane_api_url`). **Loopback-guard:** если итоговый Plane web-base указывает на localhost/127.0.0.1/0.0.0.0/::1 или пуст — Plane-ссылка опускается (не выпускаем битый localhost-URL). Graceful degradation: каждая ссылка строится независимо и опускается при нехватке данных, сообщение и призыв «Переведите задачу в статус Approved …» сохраняются всегда; ровно одно пингующее сообщение, разделяемая `send_telegram` не тронута. Динамические подписи экранируются `html.escape`, `parse_mode=HTML` сохранён. ADR `docs/work-items/ORCH-017/06-adr/ADR-001-telegram-approve-links.md`. Тесты: `test_notify_approve_links.py`, `test_analysis_approve_flow_links.py`.
|
||||
- **Конфигурируемые модель LLM и режим работы (`--effort`) агентов** (ORCH-41): модель/effort каждого агента вынесены из хардкода `launcher.py` в конфиг — глобально per-agent (`ORCH_AGENT_MODEL_<AGENT>` / `ORCH_AGENT_EFFORT_<AGENT>`, дефолты `ORCH_AGENT_MODEL_DEFAULT=claude-opus-4-8`, `ORCH_AGENT_EFFORT_DEFAULT=high`) и per-project (`agent_models` / `agent_efforts` в `ORCH_PROJECTS_JSON`). Резолверы `resolve_agent_model` / `resolve_agent_effort` (приоритет project > per-agent env > default > пусто), валидация effort `{low,medium,high,xhigh,max}`, опц. `ORCH_AGENT_FALLBACK_MODEL` (`--fallback-model`). Хардкод `"model":"opus"` (architect/reviewer) удалён. Тесты: `test_resolve_agent_model.py`, `test_resolve_agent_effort.py`.
|
||||
- **Единый status-коммент агентов в Plane** (ORCH-016): `usage.build_status_comment(...)` — один хелпер для ВСЕХ ролей (analyst..deployer). HTML-формат: header `{icon} {Role} — {описание}`, опциональная строка `Verdict/Status: …` из YAML-frontmatter артефакта, **строка `Длительность: 4m 12s`** (явный `duration_s` от launcher, fallback из `agent_runs` для аналитика), `<b>Документы:</b><ul><li><a>…</a></li></ul>`, тех-хвост `<sub>tokens · cost</sub>`. Утилитки: `usage.fmt_duration`, `usage.get_agent_duration`, новый модуль `src/frontmatter.py` (defensive YAML reader). ADR `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md`.
|
||||
- **Документация по канону** (ORCH-9): `CLAUDE.md` (паспорт проекта), структура `docs/` (`architecture/` + `adr/`, `operations/`, `work-items/`, `history/`), `docs/operations/INFRA.md` (RUNBOOK с инфра-изоляцией и self-hosting рисками).
|
||||
@@ -22,14 +16,10 @@
|
||||
- **Реестр проектов** (ORCH-6): `src/projects.py`, фильтрация вебхуков по проекту.
|
||||
|
||||
### Changed
|
||||
- **Русификация и косметика карточки live-трекера Telegram** (ORCH-042, оба режима): метка `Подтверждение BRD` вместо «Ревью БРД» (`_BRD_LABEL`); после прохождения approve-gate строка подтверждения BRD начинается с ✅ вместо ⏸️ (ветка ожидания человека сохраняет ⏸️/⏳); русские display-labels стадий в `_TRACKER_STAGES` (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`) — применяются и в «✅ …», и в «🔄 … идёт»; финальная строка готовой задачи `📦 Внедрено` вместо `deployed` (`_done_link`). Меняются только отображаемые строки — ключи стадий и имена агентов не трогаются. Существующие ассерты `tests/test_telegram_tracker.py` обновлены под русские метки.
|
||||
- **Status-коммент агентов теперь HTML и единообразен** (ORCH-016): `src/usage.usage_comment(...)` помечен deprecated и стал тонкой обёрткой над `build_status_comment`; `src/usage.artifact_links(...)` теперь возвращает `<li><a>…</a></li>` HTML-фрагменты (раньше — markdown `[label](url)`); `stage_engine._build_analyst_ready_comment(...)` — тонкая обёртка, аналитик идёт через ту же ветку `build_status_comment(agent="analyst", ...)`. Реестр `QG_CHECKS` и `STAGE_TRANSITIONS` НЕ изменялись.
|
||||
- Цепочка стадий: `... testing → deploy-staging → deploy → done` (была без `deploy-staging`).
|
||||
|
||||
### Fixed
|
||||
- **Контейнер и агенты бегут под uid хоста (1000:1000), не root** (ORCH-040): оба сервиса в `docker-compose.yml` (`orchestrator`, `orchestrator-staging`) получили `user: "1000:1000"` (slin) — устраняет корень проблемы, при которой Claude-CLI агенты, запускаемые через `subprocess.Popen` внутри root-контейнера, создавали все артефакты конвейера (git worktree `/repos/_wt/...`, коммиты в `docs/work-items/...`) с владельцем `root:root` на хосте, из-за чего `git pull`/`git reset` под slin падали с `insufficient permission for adding an object` и каждый деплой требовал ручного `chown`. Теперь файлы сразу `slin:slin`. Доступ к docker.sock сохранён через `group_add: ["999"]` (МИНА 1 — НЕ удалена). SSH-маунт приведён к единому HOME агента: target `/root/.ssh` → `/home/slin/.ssh` (`/home/slin/.orchestrator-ssh:/home/slin/.ssh:ro`), синхронно с `HOME=/home/slin`, который launcher форсит в env Popen и git_env — устранён скрытый рассинхрон SSH-маунта с форсимым HOME. `src/agents/launcher.py` и `Dockerfile` НЕ менялись (numeric uid работает без записи в `/etc/passwd`; `safe.directory '*'` уже покрывает git над bind-mount). Требует host-prerequisites Owner (P-1…P-4, вне кода): блокер P-1 — `chown -R 1000:1000 /home/slin/.claude` для доступа uid 1000 к claude creds (иначе preflight заворачивает конвейер); прод-рестарт self — только в окно тишины (общий инстанс с enduro-trails), страховка — staging-гейт (adr-0003). ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md`, глобальный `docs/architecture/adr/adr-0005-container-runs-as-host-uid.md`; INFRA.md обновлён (рантайм-uid, volumes/SSH target, host-prerequisites). Тесты: `tests/test_orch040_compose.py`.
|
||||
- **Staging-чек B6 читает реестр из окружения работающего staging-инстанса** (ORCH-048): блок B6 «Registry: sandbox present, prod ET/ORCH absent» в `scripts/staging_check.py` давал **ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`) при фактически исправной изоляции — единственный чек suite, который не ходил к инстансу по HTTP, а импортировал `src.projects` локально через host-path хак `sys.path.insert(0, "/repos/orchestrator")` + `importlib.reload`, строя реестр из `ORCH_PROJECTS_JSON` **process-env запускающего процесса**. При фактическом запуске деплоером с хоста переменная не задана → дефолт `_DEFAULT_PROJECTS` (ET+ORCH) → ложный FAIL → лишний откат `deploy-staging → development`. Решение (вариант «в», ADR-001): host-path хак удалён; suite канонически запускается ВНУТРИ контейнера `orchestrator-staging` через `docker exec … python3 /repos/orchestrator/scripts/staging_check.py` (`scripts/` доступен только через bind-mount, `import src.projects` резолвится через `PYTHONPATH=/app` из кода контейнера, env — `.env.staging`) → B6 читает реестр именно работающего инстанса, без HTTP-bootstrap и «курицы-яйца». Логика вердикта вынесена в чистую `_evaluate_b6(known) -> (passed, detail)` (инвариант `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known`, формат detail сохранён) + `_known_project_ids_from_registry()` / `_run_b6()` с детерминированным FAIL при недоступности источника (не ложный PASS, не необработанное исключение). Синхронно обновлены `.openclaw/agents/deployer.md` (команда стадии через `docker exec`) и `docs/operations/STAGING_CHECK.md`. `src/projects.py`, `.env*` и прочие чеки A/B4/B5/C не тронуты; реестр `QG_CHECKS` и `check_staging_status` (ADR-0003) не менялись. ADR `docs/work-items/ORCH-048/06-adr/ADR-001-b6-registry-via-in-container-run.md`. Тесты: `tests/test_staging_check_b6.py`.
|
||||
- **Testing-гейт `check_tests_passed` читает `result:` наравне с `verdict:`/`status:`** (ORCH-047): парсер `_parse_tests_verdict` (`src/qg/checks.py`) теперь принимает три равноправных машиночитаемых поля frontmatter `13-test-report.md` — `result:` (канон промпта тестера `.openclaw/agents/tester.md`, `result: PASS|FAIL`), плюс легаси `verdict:` и `status:` (enduro-trails ET-001..ET-014); достаточно любого одного непустого. Устраняет рассинхрон контракта: тестер честно эмитил `result: PASS` без `verdict:`/`status:`, парсер попадал в ветку «нет машинного вердикта» → откат `testing → development` в петлю до исчерпания `MAX_DEVELOPER_RETRIES` (наблюдалось на ORCH-17; ORCH-016 прошёл лишь из-за избыточного дублирования полей). Семантика приоритетов сохранена и распространена на все три поля через объединённую строку: negative-токен в любом поле авторитетен (перебивает positive), наборы токенов заморожены (обратная совместимость). Сигнатура гейта, имя и реестр `QG_CHECKS` не менялись. ADR `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md`. Тесты: `tests/test_qg.py::TestCheckTestsPassed`.
|
||||
- БАГ-8: провал deploy/deploy-staging → корректный откат на `development`.
|
||||
- Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings.
|
||||
|
||||
|
||||
@@ -129,12 +129,6 @@ uvicorn src.main:app --reload --port 8500
|
||||
| `ORCH_TRANSIENT_MAX_ATTEMPTS` | Ретраи для 429/недоступности | `5` |
|
||||
| `ORCH_BREAKER_THRESHOLD` | transient подряд до открытия breaker | `3` |
|
||||
| `ORCH_BREAKER_PAUSE_SECONDS` | Пауза при открытом breaker | `300` |
|
||||
| `ORCH_RECONCILE_ENABLED` | Kill-switch sweeper потерянных webhook (ORCH-053) | `true` |
|
||||
| `ORCH_RECONCILE_PLANE_ENABLED` | Отдельный флаг F-2 (опрос Plane API) | `true` |
|
||||
| `ORCH_RECONCILE_INTERVAL_S` | Период фонового прохода reconciler, сек | `120` |
|
||||
| `ORCH_RECONCILE_GRACE_DEFAULT_S` | Порог «застряла» по `tasks.updated_at`, сек | `600` |
|
||||
| `ORCH_RECONCILE_GRACE_OVERRIDES_JSON` | Per-stage пороги, напр. `{"development":300}` | `""` |
|
||||
| `ORCH_RECONCILE_NOTIFY_UNBLOCK` | Telegram при разблокировке застрявшей задачи | `true` |
|
||||
|
||||
## Очередь задач (ORCH-1 / F-2b)
|
||||
|
||||
|
||||
@@ -3,11 +3,6 @@ services:
|
||||
build: .
|
||||
container_name: orchestrator
|
||||
restart: unless-stopped
|
||||
# ORCH-040: бежим под uid:gid хоста (slin=1000:1000), а не root, чтобы
|
||||
# артефакты конвейера (worktree + docs) создавались как slin:slin и git на
|
||||
# хосте работал без ручного chown. Доступ к docker.sock сохранён через
|
||||
# group_add: ["999"] (МИНА 1 — НЕ удалять). См. ADR-001 ORCH-040.
|
||||
user: "1000:1000"
|
||||
# init: true injects docker-init (tini) as PID 1 so reparented grandchild
|
||||
# processes from the claude/node subprocess tree are reaped (no zombies, B-2).
|
||||
init: true
|
||||
@@ -20,8 +15,7 @@ services:
|
||||
- /usr/bin/node:/usr/bin/node:ro
|
||||
- /home/slin/.claude:/home/slin/.claude
|
||||
- /home/slin/.claude.json:/home/slin/.claude.json:ro
|
||||
# ORCH-040: target согласован с HOME=/home/slin (launcher), не /root/.ssh.
|
||||
- /home/slin/.orchestrator-ssh:/home/slin/.ssh:ro
|
||||
- /home/slin/.orchestrator-ssh:/root/.ssh:ro
|
||||
env_file: .env
|
||||
environment:
|
||||
- ORCH_REPOS_DIR=/repos
|
||||
@@ -41,8 +35,6 @@ services:
|
||||
build: .
|
||||
container_name: orchestrator-staging
|
||||
restart: unless-stopped
|
||||
# ORCH-040: тот же uid хоста, что и у prod (см. комментарий выше / ADR-001).
|
||||
user: "1000:1000"
|
||||
init: true
|
||||
network_mode: host
|
||||
command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8501"]
|
||||
@@ -54,8 +46,7 @@ services:
|
||||
- /usr/bin/node:/usr/bin/node:ro
|
||||
- /home/slin/.claude:/home/slin/.claude
|
||||
- /home/slin/.claude.json:/home/slin/.claude.json:ro
|
||||
# ORCH-040: target согласован с HOME=/home/slin (launcher), не /root/.ssh.
|
||||
- /home/slin/.orchestrator-ssh:/home/slin/.ssh:ro
|
||||
- /home/slin/.orchestrator-ssh:/root/.ssh:ro
|
||||
env_file: .env.staging
|
||||
environment:
|
||||
- ORCH_REPOS_DIR=/repos
|
||||
|
||||
@@ -7,11 +7,9 @@
|
||||
- **Webhook Receivers** (`src/webhooks/plane.py`, `gitea.py`) — приём событий, HMAC-проверка, дедупликация (`_dedup.py`). Роуты: `POST /webhook/plane`, `POST /webhook/gitea`.
|
||||
- **State Machine** (`src/stages.py`) — `STAGE_TRANSITIONS`: переходы, агент и QG каждой стадии. Хелперы: `get_next_stage`, `get_agent_for_stage`, `get_qg_for_stage`, `get_previous_stage`.
|
||||
- **Stage Engine** (`src/stage_engine.py`) — исполнение переходов, диспетчеризация QG (`_run_qg`), откаты, синхронизация с Plane.
|
||||
- **Review/Test Parsers** (`src/review_parse.py`, ORCH-046) — defensive-извлечение дословного must-fix текста из артефактов для встраивания в `task_desc` заворота: `extract_review_findings` (P0/P1 из `12-review.md`), `extract_test_failures` (фрагмент тела `13-test-report.md`). Контракт «never raise»: любая ошибка → `""`.
|
||||
- **Quality Gates** (`src/qg/checks.py`) — проверки выхода со стадии, реестр `QG_CHECKS`.
|
||||
- **Agent Launcher** (`src/agents/launcher.py`) — запуск Claude CLI агентов в изолированном git worktree, мониторинг, auto-advance.
|
||||
- **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe.
|
||||
- **Reconciler** (`src/reconciler.py`, ORCH-053 — реализовано, [adr-0007](adr/adr-0007-reconciler.md)) — фоновый daemon-поток (паттерн `queue_worker`), стартует/останавливается в `main.lifespan` (после `worker.start()` / перед `worker.stop()`). Реконсилирует рассинхрон «источник истины ≠ стадия задачи» при потерянном webhook. F-1 gate-side (продвигает застрявшую стадию по локальной БД через штатный `advance_stage(..., finished_agent=None)`), F-2 plane-side (опрос Plane API → `handle_*` из `plane.py`), F-3 (БД-fallback `sha→branch` в `handle_ci_status`). Источник истины — гейт/Plane, не событие; идемпотентность (active-job guard + atomic-claim + grace); kill-switch `ORCH_RECONCILE_ENABLED`. `analysis` F-1 не трогает (человеческий гейт). Наблюдаемость — блок `reconcile` в `GET /queue`.
|
||||
- **Project Registry** (`src/projects.py`, ORCH-6) — Plane project id → repo + prefix; фильтрация вебхуков по проекту.
|
||||
- **Plane Sync** (`src/plane_sync.py`) — синхронизация статусов/комментариев в Plane.
|
||||
|
||||
@@ -35,67 +33,19 @@ created → analysis → architecture → development → review → testing →
|
||||
| deploy | — | `check_deploy_status` | 14-deploy-log.md (`deploy_status:`) |
|
||||
| done | — | — | — |
|
||||
|
||||
**Реестр QG** (`QG_CHECKS`): check_analysis_approved, check_analysis_complete, check_architecture_done, check_ci_green, check_review_approved, check_tests_passed, check_reviewer_verdict, check_tests_local, check_deploy_status, check_staging_status, check_branch_mergeable (ORCH-043).
|
||||
**Реестр QG** (`QG_CHECKS`): check_analysis_approved, check_analysis_complete, check_architecture_done, check_ci_green, check_review_approved, check_tests_passed, check_reviewer_verdict, check_tests_local, check_deploy_status, check_staging_status.
|
||||
|
||||
**Канон гейтов:** машинные вердикты читаются ТОЛЬКО из YAML-frontmatter, никогда из прозы. Лог-файлы мержатся в `origin/main` отдельным PR; гейт читает из `origin/main`.
|
||||
|
||||
### Условный staging-гейт (ORCH-35)
|
||||
`check_staging_status` реален только для self-hosting (`is_self_hosting_repo(repo)` → `orchestrator`); для остальных проектов → no-op `(True, "Staging gate N/A")`. Для orchestrator парсит `staging_status:` из `15-staging-log.md`; FAILED → откат на `development`. Подробнее: [ADR-0003](adr/adr-0003-staging-gate.md).
|
||||
|
||||
### Merge-gate: догон `main` + re-test + сериализация слияний (ORCH-043)
|
||||
Детерминированный под-гейт (`check_branch_mergeable`, без LLM) на ребре **`deploy-staging → deploy`**: исполняется ПОСЛЕ `check_staging_status` и ДО запуска deployer'а, который вливает PR в `main` (deployer мержит в начале стадии `deploy`). Стадии (`STAGE_TRANSITIONS`) НЕ меняются — это «под-гейт» ребра, а не отдельная стадия (триггер — то же событие «staging-deployer завершился»).
|
||||
|
||||
Назначение: ветка валидируется относительно того `main`, из которого создана; параллельная задача могла уйти вперёд → семантический конфликт слияния (зелёная ветка ломает обновлённый `main`). Merge-gate гарантирует проверку против **актуального** `origin/main` перед слиянием:
|
||||
- **Догон:** ветка отстаёт (⇔ `origin/main` не предок HEAD) → `rebase origin/main` в worktree + `push --force-with-lease` (ТОЛЬКО ветка задачи; `main` — никогда). Текстовый конфликт → `rebase --abort` → откат на `development`.
|
||||
- **Re-test:** `python -m pytest` (`merge_retest_target`, дефолт `tests/`) в worktree догнанной ветки, тайм-аут `merge_retest_timeout_s`. Красный/тайм-аут → откат на `development`.
|
||||
- **Сериализация (merge-lock):** файловый **merge-lease** на репо (`<repos_dir>/.merge-lease-<repo>.json`), живёт от гейта до фактического merge. Acquire **неблокирующий** (anti-deadlock при `max_concurrency=1`): busy → **defer** (повторная постановка deployer'а на `deploy-staging` с задержкой через `available_at`), а не откат. Release — на PR-merged вебхуке / `deploy→done` / откате / по возрасту (crash-реклейм). Restart-safe; без изменения схемы БД.
|
||||
- **Условность (как ORCH-35):** реален для `orchestrator`; прочие репо — no-op. Флаги `merge_gate_enabled` / `merge_gate_repos` — поэтапный раскат. Контракт **never-raise**.
|
||||
|
||||
Подробнее: [adr-0006](adr/adr-0006-merge-gate.md), детально — `docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md`.
|
||||
|
||||
### Reconciler: реконсиляция потерянных webhook (ORCH-053 — реализовано)
|
||||
Конвейер продвигается только входящими webhook; потерянное событие (502 на ребилде,
|
||||
нет ретраев у Plane/Gitea, неразрезолвленный `sha→branch`) → задача застревает молча
|
||||
(инцидент ORCH-044). Фоновый поток `reconciler` периодически (`reconcile_interval_s`)
|
||||
находит застрявшие задачи и доигрывает пропущенный переход **через те же штатные
|
||||
гейты/обработчики**, что и webhook:
|
||||
- **F-1 gate-side:** для задач со `stage∉{done}`, без активного job и
|
||||
`age(updated_at) ≥ grace_for_stage(stage)` — read-only пред-оценка канонического QG;
|
||||
зелёный → `stage_engine.advance_stage(..., finished_agent=None)`; красный →
|
||||
тишина (спам нотификаций структурно невозможен). `analysis` не реконсилируется.
|
||||
- **F-2 plane-side:** опрос Plane API per-project → `handle_status_start` /
|
||||
`handle_verdict` из `webhooks/plane.py` (логика не дублируется).
|
||||
- **F-3:** усиление `sha→branch` в `handle_ci_status` (БД-fallback по единственной
|
||||
development-задаче repo; неоднозначность → не резолвим).
|
||||
- **F-4 observability:** при разблокировке — лог-строка `reconciler: <wi> <stage>
|
||||
разблокирована (потерян webhook)` + Telegram (`reconcile_notify_unblock`); снимок
|
||||
состояния в `GET /queue` (блок `reconcile`).
|
||||
|
||||
Реализация: `src/reconciler.py` (daemon-поток по образцу `queue_worker`), стартует в
|
||||
`main.lifespan` **после** `worker.start()`, останавливается в `finally` **перед**
|
||||
`worker.stop()`.
|
||||
|
||||
Инварианты: источник истины — гейт/Plane, не событие; идемпотентность (active-job
|
||||
guard + atomic-claim на создании под process-wide Lock + grace + `max_concurrency=1`);
|
||||
never-raise на единицу работы; тишина при синхронности; restart-safe; kill-switch
|
||||
`ORCH_RECONCILE_ENABLED` (+ `ORCH_RECONCILE_PLANE_ENABLED` гасит только F-2). Схема БД
|
||||
и реестры (`STAGE_TRANSITIONS`/`QG_CHECKS`) не меняются. Подробнее:
|
||||
[adr-0007](adr/adr-0007-reconciler.md), детально — `docs/work-items/ORCH-053/06-adr/ADR-001-stuck-task-reconciler.md`.
|
||||
|
||||
## Откаты
|
||||
- Reviewer REQUEST_CHANGES → откат на `development` + retry (`MAX_DEVELOPER_RETRIES = 3`).
|
||||
- Tester `check_tests_passed` FAIL → откат на `development` + retry.
|
||||
- Deploy / deploy-staging FAILED → откат на `development`.
|
||||
- Merge-gate FAIL (конфликт rebase / красный re-test, ORCH-043) → откат на `development` + retry; `merge-lock busy` → **defer** (не откат, dev-retry не тратится).
|
||||
- `get_previous_stage` использует порядок ключей `STAGE_TRANSITIONS`.
|
||||
|
||||
### Обогащение `task_desc` при заворотах (ORCH-046)
|
||||
При откате на `development` `task_desc` (попадает в `.task-dev.md` developer-агента) несёт **дословный must-fix текст**, а не только ссылку — чтобы агент видел суть претензий сразу и не повторял ту же ошибку:
|
||||
- **reviewer REQUEST_CHANGES** → дословные пункты P0/P1 из секции `## Findings` файла `12-review.md` (`extract_review_findings`);
|
||||
- **tester `check_tests_passed` FAIL** → `reason` гейта + фрагмент тела `13-test-report.md` (приоритет: `## Вывод pytest` → FAIL-строки `## Результаты` → `## Итог`; `extract_test_failures`).
|
||||
|
||||
Ссылка на полный файл-артефакт сохраняется всегда («Полный контекст»). Парсеры `src/review_parse.py` — defensive (never-raise); при отсутствующем/битом артефакте `task_desc` graceful-фоллбэк на прежнюю ссылку-строку, последовательность отката и retry-счётчик не меняются (ADR `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md`).
|
||||
|
||||
### Plane Sync: единый status-коммент агентов (ORCH-016)
|
||||
Все агенты (analyst / architect / developer / reviewer / tester / deployer) пишут финальный коммент через **один хелпер** `usage.build_status_comment(...)` (ADR `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md`). Формат HTML, разделители `<br>`:
|
||||
|
||||
@@ -108,7 +58,7 @@ never-raise на единицу работы; тишина при синхрон
|
||||
```
|
||||
|
||||
- **Длительность** считается launcher'ом (`_monitor_agent`) и пробрасывается в `_post_usage_comments`; для analyst (коммент строится в `stage_engine`) используется DB-фоллбэк `usage.get_agent_duration(task_id, agent)`.
|
||||
- **Vердикт-парсер** — `src/frontmatter.read_frontmatter_value(...)` (defensive, никогда не raise). Машинные ключи: reviewer → `verdict:` (12-review.md); **testing-гейт `check_tests_passed` (13-test-report.md) → любое из трёх равноправных: `result:` (канон промпта тестера), `verdict:`, `status:`** (ORCH-047, ADR-001); deployer → `deploy_status:` (14-deploy-log.md), `staging_status:` (15-staging-log.md). Negative-токен в любом поле авторитетен (перебивает positive).
|
||||
- **Vердикт-парсер** — `src/frontmatter.read_frontmatter_value(...)` (defensive, никогда не raise). Машинные ключи: `verdict:` (reviewer/tester), `deploy_status:` (14-deploy-log.md), `staging_status:` (15-staging-log.md).
|
||||
- Формат коммента **не** меняет реестр гейтов и стадий; коммент — отображение, не управление.
|
||||
|
||||
## База данных (SQLite)
|
||||
@@ -125,7 +75,7 @@ never-raise на единицу работы; тишина при синхрон
|
||||
|--------|------|----------|
|
||||
| GET | `/health` | health check |
|
||||
| GET | `/status` | активные задачи (stage != done) |
|
||||
| GET | `/queue` | очередь: counts + max_concurrency + resilience + reconcile (ORCH-053) + последние jobs |
|
||||
| GET | `/queue` | очередь: counts + max_concurrency + последние jobs |
|
||||
| POST | `/webhook/plane` | Plane webhook |
|
||||
| POST | `/webhook/gitea` | Gitea webhook (push, PR, CI status) |
|
||||
|
||||
@@ -139,4 +89,4 @@ never-raise на единицу работы; тишина при синхрон
|
||||
Схема БД, потоки данных, resilience-слой, детали Dockerfile — [internals.md](internals.md).
|
||||
|
||||
---
|
||||
*Актуально на 2026-06-06. Обновлять при изменении src/stages.py, src/qg/checks.py, src/main.py. ORCH-043: merge-gate — design (см. adr-0006), реализация в ветке feature/ORCH-043. ORCH-053: reconciler — реализовано (см. adr-0007, src/reconciler.py).*
|
||||
*Актуально на 2026-06-05 (main `f1b3146`). Обновлять при изменении src/stages.py, src/qg/checks.py, src/main.py.*
|
||||
|
||||
@@ -8,10 +8,6 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
|
||||
| adr-0001 | Реестр проектов (multi-repo) | accepted | 2026-06-02 | ORCH-6 |
|
||||
| adr-0002 | Очередь задач вместо in-process потоков | accepted | 2026-06-03 | ORCH-1 |
|
||||
| adr-0003 | Условный staging-гейт перед прод-деплоем | accepted | 2026-06-05 | ORCH-35 |
|
||||
| adr-0004 | Поллинг с ретраем в check_ci_green (фикс CI-race) | accepted | 2026-06-05 | ORCH-045 |
|
||||
| adr-0005 | Контейнеры бегут под uid:gid хоста (1000:1000) | accepted | 2026-06-06 | ORCH-040 |
|
||||
| adr-0006 | Merge-gate (догон main + re-test + сериализация слияний) | proposed | 2026-06-06 | ORCH-043 |
|
||||
| adr-0007 | Reconciler застрявших стадий (sweeper потерянных webhook) | accepted | 2026-06-06 | ORCH-053 |
|
||||
|
||||
## Формат
|
||||
**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# adr-0004: Поллинг с ретраем в quality-gate check_ci_green (фикс CI-race)
|
||||
|
||||
- **Статус:** accepted
|
||||
- **Дата:** 2026-06-05
|
||||
- **Задача:** ORCH-045
|
||||
|
||||
## Контекст
|
||||
Quality-gate `check_ci_green(repo, branch)` (`src/qg/checks.py`) проверяет combined commit-status ветки через Gitea API сразу после того, как developer-агент запушил код. Реализация была **single-shot**: один `GET /repos/{owner}/{repo}/commits/{branch}/status`, чтение `data["state"]` — `success` → пропуск, иначе → сразу `False`.
|
||||
|
||||
Это создавало race condition. Gitea-CI после пуша 1–3 секунды держит combined state `pending`, пока не отработают чек-раннеры. Если гейт опрашивал статус в этом окне, он получал `pending` и возвращал `False` **ровно один раз** — повторного опроса не было. Combined state затем дозеленевал до `success`, но гейт уже промахнулся, и задача застревала насмерть без видимой причины.
|
||||
|
||||
Реальный инцидент **ORCH-017**: гейт опросил статус в 17:58:54 → `pending`; CI дозеленел в 17:58:55. Задача встала в тупик (см. `docs/history` / lessons ORCH-017).
|
||||
|
||||
## Решение
|
||||
`check_ci_green` превращён из single-shot в **polling с ретраем**:
|
||||
|
||||
- `state == "success"` → `(True, "CI green")` немедленно.
|
||||
- `state in ("failure", "error")` → `(False, "CI state: <state>")` немедленно — CI красный, ретрай бессмыслен (терминальное состояние).
|
||||
- `state == "pending"` (или `unknown` / иное не-терминальное) → `time.sleep(interval)` и опрос снова, до `N` попыток.
|
||||
- После исчерпания всех попыток при всё ещё `pending` → `(False, "CI still pending after <T>s")` — **явный** провал с причиной, чтобы оператор видел тупик, а не молчаливый стол.
|
||||
- `404` → `(False, "Branch ... not found or no status")` — как раньше.
|
||||
- Транзиентная `httpx.HTTPError` на отдельной попытке — **не падаем сразу**: логируем и пробуем ещё в рамках лимита попыток; если все попытки — сетевая ошибка → `(False, "API error: <e>")`.
|
||||
|
||||
Параметры вынесены в `src/config.py` (pydantic-settings, env-prefix `ORCH_`, единый стиль с остальными настройками):
|
||||
- `ci_poll_max_attempts` (env `ORCH_CI_POLL_MAX_ATTEMPTS`, дефолт **12**)
|
||||
- `ci_poll_interval_s` (env `ORCH_CI_POLL_INTERVAL_S`, дефолт **10**)
|
||||
|
||||
Итого по умолчанию гейт ждёт `pending` до ~2 минут (12 × 10s) перед тем как явно провалиться. Каждая не-финальная попытка логируется через существующий `logger` (`check_ci_green: attempt i/N, state=..., retrying in Ns`). `timeout=10` на каждый отдельный запрос сохранён.
|
||||
|
||||
Сигнатура `check_ci_green(repo, branch) -> tuple[bool, str]` **не менялась** — её зовёт stage_engine и реестр гейтов `QG_CHECKS`.
|
||||
|
||||
## Альтернативы
|
||||
- **Оставить single-shot, опрашивать гейт повторно снаружи (на уровне stage_engine/воркера).** Отклонено: размазывает логику CI-ожидания по слоям, дублирует таймауты; гейт — естественное место знания о combined-status.
|
||||
- **Webhook от Gitea на завершение CI вместо поллинга.** Отложено: требует надёжной доставки/дедупликации вебхуков именно по CI-статусу и переписывания триггера стадии; поллинг — минимальный, локализованный фикс race-а здесь и сейчас.
|
||||
- **Бесконечный ретрай до зелёного.** Отклонено: задача могла бы висеть вечно при реально зависшем CI; ограниченный бюджет + явный `False` с причиной даёт оператору сигнал.
|
||||
|
||||
## Последствия
|
||||
- CI-race ORCH-017 закрыт: транзиентный `pending` переживается ретраем, гейт не промахивается.
|
||||
- `check_ci_green` теперь **блокирующий** до ~`max_attempts × interval` секунд при затяжном `pending` (по умолчанию ~2 мин). Это осознанный trade-off; для красного CI и success — выход немедленный, без задержки.
|
||||
- Тупик больше не молчаливый: истечение попыток → `(False, "CI still pending after <T>s")`, причина видна.
|
||||
- Бюджет/интервал настраиваемы через env без правки кода.
|
||||
- `check_tests_passed` / `_parse_tests_verdict` (ORCH-47) **не затронуты**.
|
||||
|
||||
## Связи
|
||||
ORCH-017 (инцидент-первоисточник: deadlock shared-gate из-за CI-race), реестр гейтов `QG_CHECKS` (`check_ci_green`), стадия `development`. Тесты: `tests/test_qg.py::TestCheckCIGreen`.
|
||||
@@ -1,42 +0,0 @@
|
||||
# adr-0005: Контейнеры оркестратора бегут под uid:gid хоста (1000:1000)
|
||||
|
||||
- **Статус:** accepted
|
||||
- **Дата:** 2026-06-06
|
||||
- **Задача:** ORCH-040
|
||||
|
||||
## Контекст
|
||||
Оба контейнера (`orchestrator`, `orchestrator-staging`) запускались под `uid=0 (root)` и
|
||||
монтировали хостовый `/home/slin/repos` → `/repos` (rw). Claude-CLI агенты исполняются
|
||||
`subprocess.Popen` внутри контейнера под тем же root, поэтому все артефакты конвейера
|
||||
(git worktree, коммиты в `docs/`) появлялись на хосте как `root:root`. Деплой прода под
|
||||
`slin` (uid 1000) ломался на правах git до ручного `chown`. Это сквозное свойство рантайма:
|
||||
касается агентов **всех** проектов, а не отдельной фичи.
|
||||
|
||||
## Решение
|
||||
Оба сервиса в `docker-compose.yml` запускаются под `user: "1000:1000"` (uid:gid хоста `slin`).
|
||||
- `group_add: ["999"]` сохраняется — доступ к docker.sock идёт через gid 999, не через root.
|
||||
- target SSH-маунта приведён к `/home/slin/.ssh` (был `/root/.ssh`), синхронно с
|
||||
`HOME=/home/slin`, который форсит launcher → единый HOME по осям uid/claude/ssh.
|
||||
- Образ и launcher не меняются: numeric uid не требует записи в `/etc/passwd`,
|
||||
`git config --system safe.directory '*'` уже есть.
|
||||
|
||||
Обязательные host-prerequisites (Owner, вне кода): доступ uid 1000 к
|
||||
`/home/slin/.claude/.credentials.json` (блокер), ssh-ключи в новом HOME, рестарт prod
|
||||
только в окно тишины. Детали и команды — work-item ADR-001 и `docs/operations/INFRA.md`.
|
||||
|
||||
## Альтернативы
|
||||
- **drop-privileges только для subprocess агента** (`gosu`/`setuid`) — контейнер остаётся
|
||||
root; новый код в горячем пути launcher, два uid в одном контейнере; отклонён.
|
||||
- **chown-хук после каждой стадии** — лечит симптом, требует root внутри контейнера
|
||||
(несовместимо), хрупкий пост-шаг; отклонён (fallback на крайний случай).
|
||||
|
||||
## Последствия
|
||||
- Артефакты создаются под `slin:slin`; деплой прода не требует ручного `chown`.
|
||||
- HOME консистентен (uid = claude = ssh = `/home/slin`); устранён рассинхрон SSH-маунта.
|
||||
- Появляется явная привязка рантайма к uid 1000 хоста (задокументирована в INFRA.md).
|
||||
- Прод-рестарт self = групповой риск (общий инстанс с enduro-trails) → строго окно тишины;
|
||||
страховка — staging-гейт (adr-0003).
|
||||
|
||||
## Связи
|
||||
adr-0003 (staging-гейт — обязательная проверка перед прод-рестартом self),
|
||||
adr-0001 (`is_self_hosting_repo`), work-item `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md`.
|
||||
@@ -1,53 +0,0 @@
|
||||
# adr-0006: Merge-gate — догон `main` + re-test + сериализация слияний
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-06
|
||||
- **Задача:** ORCH-043
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md`
|
||||
|
||||
## Контекст
|
||||
Ветка валидируется относительно того `main`, из которого создана, а не относительно `main`
|
||||
на момент слияния. Параллельная задача могла влиться раньше → **семантический конфликт
|
||||
слияния** (git мержит без текстового конфликта, но `main` сломан). Для self-hosting это
|
||||
красный `main` инструмента, обслуживающего все проекты. Слияние в `main` делает
|
||||
deployer-агент в начале стадии `deploy`; замена механизма PR-merge — вне объёма.
|
||||
|
||||
## Решение
|
||||
Детерминированный merge-gate (`check_branch_mergeable`, без LLM) на ребре
|
||||
`deploy-staging → deploy`, ДО запуска deployer'а, который мержит. `STAGE_TRANSITIONS` не
|
||||
меняется (минимальный blast-radius); в `QG_CHECKS` добавлен `check_branch_mergeable`.
|
||||
|
||||
- **Догон:** ветка отстаёт ⇔ `origin/main` не предок HEAD → `rebase origin/main` в worktree
|
||||
+ `push --force-with-lease` (ТОЛЬКО ветка задачи; `main` — никогда). Текстовый конфликт →
|
||||
`rebase --abort` → откат на `development`.
|
||||
- **Re-test:** `python -m pytest tests/` в worktree догнанной ветки, тайм-аут
|
||||
`merge_retest_timeout_s`. Красный/тайм-аут → откат на `development`.
|
||||
- **Сериализация (BR-5):** файловый **merge-lease** на репо
|
||||
(`<repos_dir>/.merge-lease-<repo>.json`), живёт от гейта до фактического merge.
|
||||
Acquire **неблокирующий** (anti-deadlock при `max_concurrency=1`): busy → **defer**
|
||||
(re-enqueue deployer с задержкой через `available_at`), не rollback. Release — на
|
||||
PR-merged вебхуке / `deploy→done` / откате / по возрасту (crash-реклейм). Restart-safe.
|
||||
- **Условность (как ORCH-35):** реален для `orchestrator`; прочие репо — no-op. Флаги
|
||||
`merge_gate_enabled` / `merge_gate_repos` для поэтапного раската.
|
||||
|
||||
## Альтернативы
|
||||
- **Новая стадия `merge-gate`** (кандидат B) — «пустая» стадия без агента не имеет триггера
|
||||
(`advance_stage` срабатывает только на завершении агента/вебхуке); потребовала бы chaining
|
||||
в движке (не restart-safe) или синтетический job-тип. Отклонено.
|
||||
- **Перенос merge в детерминированный шаг оркестратора** (кандидат C) — запрещён объёмом
|
||||
(замена механизма PR-merge вне scope). Отклонено.
|
||||
- **Блокирующий lock** — дедлок при одном worker-слоте. Отклонено в пользу defer.
|
||||
|
||||
## Последствия
|
||||
- Сценарий «две зелёные ветки ломают `main`» закрыт: re-test против актуального `main` +
|
||||
сериализация слияний.
|
||||
- Плата: merge-gate — «скрытый» под-гейт ребра (нет в `STAGE_TRANSITIONS`); сериализация
|
||||
опирается на PR-merged вебхук со страховкой реклеймом по возрасту; defer перепрогоняет
|
||||
staging; длинный re-test держит worker-слот.
|
||||
- Сквозное изменение конвейера → `arch:major-change`; прод-деплой ORCH-043 строго через
|
||||
staging-гейт (8501).
|
||||
|
||||
## Связи
|
||||
adr-0001 (`is_self_hosting_repo`), adr-0003 (условный staging-гейт — образец условности),
|
||||
adr-0002 (очередь / `available_at` для defer), ORCH-2 (worktree-изоляция), ORCH-046
|
||||
(дословный reason в `task_desc` при откате).
|
||||
@@ -1,69 +0,0 @@
|
||||
# adr-0007: Reconciler застрявших стадий (sweeper потерянных webhook)
|
||||
|
||||
- **Статус:** accepted (реализовано в `src/reconciler.py`)
|
||||
- **Дата:** 2026-06-06
|
||||
- **Задача:** ORCH-053
|
||||
- **Детальный ADR:** `docs/work-items/ORCH-053/06-adr/ADR-001-stuck-task-reconciler.md`
|
||||
|
||||
## Контекст
|
||||
Конвейер продвигается **только** входящими webhook (Plane status / Gitea CI/PR).
|
||||
Потерянное событие (502 на ребилде, отсутствие ретраев у Plane/Gitea,
|
||||
неразрезолвленный `sha→branch`) → источник истины изменился, а стадия задачи —
|
||||
нет; задача застревает молча (инцидент ORCH-044). Существующий resilience
|
||||
(`requeue_running_jobs`, orphan-recovery, events de-dup ORCH-5, `ci_poll`
|
||||
ORCH-045) работает на уровне jobs/agent_runs и **не реконсилирует**
|
||||
рассинхрон «источник истины ≠ стадия задачи».
|
||||
|
||||
## Решение
|
||||
Фоновый daemon-поток `src/reconciler.py` (паттерн `queue_worker`, module-singleton,
|
||||
`threading.Event`), стартует в `main.lifespan` после `worker.start()`, стоп в
|
||||
`finally` перед `worker.stop()`. Две взаимодополняющие ветки на каждом тике
|
||||
(`reconcile_interval_s`, дефолт 120с):
|
||||
|
||||
- **F-1 gate-side** (локальная БД): для каждой `task` где `stage∉{done}`, **нет**
|
||||
активного job, `age(updated_at) ≥ grace_for_stage(stage)` — read-only пред-оценка
|
||||
канонического QG стадии; если зелёный → продвижение **штатным**
|
||||
`stage_engine.advance_stage(..., finished_agent=None)` (тот же путь, что у Plane
|
||||
Approved-webhook). Красный → **тишина** (нет advance, нет нотификаций — спам
|
||||
структурно невозможен). `analysis` F-1 **не** реконсилирует (человеческий гейт →
|
||||
отдан F-2).
|
||||
- **F-2 plane-side** (опрос Plane API per-project через `list_issues_by_state`):
|
||||
`In Progress`+нет задачи → `handle_status_start`; `Approved`+не сдвинута →
|
||||
`handle_verdict(approved=True)`; `Rejected`+не откатана →
|
||||
`handle_verdict(approved=False)`. Обработчики `webhooks/plane.py`
|
||||
**переиспользуются** (async → `asyncio.run` из sync-потока), логика не дублируется.
|
||||
- **F-3:** усиление `sha→branch` в `handle_ci_status` (БД-fallback по
|
||||
`repo`+`stage='development'`, видимость на INFO) — defense-in-depth.
|
||||
|
||||
**Инварианты:** источник истины — гейт/Plane, не событие; продвижение только через
|
||||
`advance_stage`; идемпотентность (active-job guard + atomic-claim на создании +
|
||||
grace + `max_concurrency=1`); never-raise на единицу работы; тишина при
|
||||
синхронности; restart-safe; kill-switch.
|
||||
|
||||
## Альтернативы
|
||||
- **Флаг подавления нотификаций в `advance_stage`** — отклонён: меняет общий
|
||||
критический путь. Вместо этого «не вызывать advance_stage на красном гейте».
|
||||
- **UNIQUE-индекс `tasks.plane_id`** для анти-дубля — отклонён как primary: риск
|
||||
падения миграции на проде; выбран process-wide `threading.Lock` (single-process
|
||||
топология). Индекс — задокументированное будущее упрочнение для multi-process.
|
||||
- **Отдельная стадия/QG реконсиляции** — вне объёма; нарушает «источник истины —
|
||||
существующий гейт».
|
||||
- **Реконсиляция analysis по локальным артефактам** — отклонена: автопродвижение
|
||||
неодобренного человеком BRD.
|
||||
|
||||
## Последствия
|
||||
- Потерянный webhook ≠ молча застрявшая задача; ручной heartbeat-watchdog не нужен;
|
||||
резервная сетка к ORCH-51 (буфер недоставленных) и ORCH-36 (deploy).
|
||||
- Плата: фоновый поток + опрос Plane API (митигируется интервалом/фильтром/
|
||||
per-project); двойная оценка гейта на зелёной задаче; анти-дубль опирается на
|
||||
single-process-допущение (как и очередь ORCH-1).
|
||||
- Self-hosting: `reconcile_enabled` — обязательный kill-switch; поэтапный раскат
|
||||
(`reconcile_plane_enabled` гасит только F-2); reconciler не рестартит/не роняет
|
||||
прод-контейнер. БД-схема и реестры (`STAGE_TRANSITIONS`/`QG_CHECKS`) не меняются.
|
||||
|
||||
## Связи
|
||||
adr-0002 (очередь / `available_at`, single-process-singleton), adr-0003 (условный
|
||||
гейт — образец условности/флагов раската), adr-0006 (merge-gate как под-гейт ребра
|
||||
внутри `advance_stage`), adr-0001 (реестр проектов для F-2 per-project), ORCH-5
|
||||
(events de-dup — защита от дублей; reconciler — обратная защита от потерь),
|
||||
ORCH-045 (`ci_poll`).
|
||||
@@ -107,27 +107,6 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||||
2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer
|
||||
3. Если >= MAX_DEV_RETRIES — эскалация (логирование + уведомление)
|
||||
|
||||
### 7. Live Telegram tracker (`src/notifications.py`)
|
||||
|
||||
Вместо ~15 отдельных сообщений на задачу оркестратор держит **ОДНУ** live-карточку на задачу (`update_task_tracker`), которая обновляется на каждом переходе стадии. Текст рендерится статически из БД (`render_task_tracker`: стадии, токены, стоимость, BRD-подтверждение, итоги). Карточка всегда тихая (`disable_notification=True`); отдельные пинги шлют только `notify_approve_requested` / `notify_error`. `message_id` хранится в `tasks.tracker_message_id`; helpers `get_tracker_message_id` / `set_tracker_message_id`. Контракт всего компонента — **never raises**.
|
||||
|
||||
**Режимы (ORCH-042, `ORCH_TRACKER_MODE` → `Settings.tracker_mode`).** Резолвится в `update_task_tracker` (case-insensitive, trim); всё, что ≠ `"bump"` (включая пустое/мусор/None), трактуется как `edit` → нулевая регрессия и безопасный фолбэк. Инвариант «одна карточка на задачу» сохраняется в обоих режимах.
|
||||
|
||||
| Режим | Поведение при обновлении |
|
||||
|-------|--------------------------|
|
||||
| `edit` (дефолт) | первый вызов → `send_telegram` (тихо) + сохранение `message_id`; далее → `edit_telegram` на сохранённый id. Новое сообщение шлётся ТОЛЬКО при `EDIT_GONE` (удалено/старше 48ч/невалидный id). `EDIT_NOT_MODIFIED` / `EDIT_FAILED` → нового сообщения нет (анти-дубль). |
|
||||
| `bump` | карточка пересоздаётся внизу чата: best-effort `delete_telegram(старый_id)` → `send_telegram(text, disable_notification=True)` → `set_tracker_message_id(new_id)` **только** при успешном send (`new_mid is not None`). За один вызов — не более одного нового сообщения. |
|
||||
|
||||
**`delete_telegram(message_id) -> bool`** (low-level, never raises). Семантика возврата — «исчезло ли старое сообщение»:
|
||||
- `ok:true` → `True`;
|
||||
- `ok:false` с маркерами `_DELETE_GONE_MARKERS` (`message to delete not found`, `message can't be deleted`, `message_id_invalid`) → `True` (старше 48ч / уже удалено — не транзиент);
|
||||
- прочий `ok:false` / 5xx / исключение (сеть/таймаут) → `False` + `logger.warning`;
|
||||
- нет токена/chat_id → `False`, HTTP не выполняется.
|
||||
|
||||
Результат `delete_telegram` **не** блокирует отправку новой карточки (BR-6: delete-fail у сообщения >48ч → всё равно шлём новое); `False` означает лишь «старое, возможно, ещё живо» — будет вычищено повторной попыткой на следующем переходе. При транзиентном сбое send (`None`) указатель `tracker_message_id` **не** затирается (анти-затирание, симметрично edit-fallback).
|
||||
|
||||
**Текст карточки (оба режима, ORCH-042):** метка `Подтверждение BRD` (была «Ревью БРД»); после прохождения approve-gate строка BRD начинается с ✅ (ветка ожидания сохраняет ⏸️/⏳); русские display-labels стадий (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`); финальная строка `📦 Внедрено` (было `deployed`). Меняются только отображаемые строки — ключи стадий и имена агентов (завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются.
|
||||
|
||||
## Database Schema
|
||||
|
||||
```sql
|
||||
|
||||
@@ -1,128 +0,0 @@
|
||||
# Lessons Learned — 2026-06-05 (вечер): ORCH-17/45/47 + деплой прода
|
||||
|
||||
## Итог дня
|
||||
Закрыты три задачи (ORCH-17, ORCH-45, ORCH-47), два прод-гейта стали умнее, заведено
|
||||
4 системных задачи в бэклог (ORCH-44/46/48 + B6). Главный сквозной урок: **конвейер не мог
|
||||
провести эти задачи автономно из-за дыр в самом конвейере** — потребовались ручные merge и
|
||||
ребилды прода. Корни задокументированы, чинятся отдельными задачами.
|
||||
|
||||
---
|
||||
|
||||
## 1. ORCH-17 — approve-ping links (закрыта вручную)
|
||||
Подробный разбор: `docs/history/LESSONS_ORCH-017.md`. Кратко: косметика (2 ссылки)
|
||||
застряла 5 раз, объективный дедлок shared-гейта, ручной merge PR #37 (`26c6f267`).
|
||||
|
||||
---
|
||||
|
||||
## 2. ORCH-45 — CI-гонка в `check_ci_green` (исправлена, в проде)
|
||||
|
||||
### Проблема
|
||||
`check_ci_green` делал **один** запрос статуса CI сразу после developer. Если CI ещё
|
||||
`pending` 1-3 секунды (реальный кейс: опрос 17:58:54 → pending, CI позеленел 17:58:55) —
|
||||
гейт возвращал False **один раз** и задача застревала насмерть с зелёным CI.
|
||||
|
||||
### Решение (PR #39, merge `982698c4`)
|
||||
Поллинг с ретраем: `success`/`failure` — терминальны (сразу), `pending` → ждать
|
||||
`CI_POLL_INTERVAL_S`(10с) до `CI_POLL_MAX_ATTEMPTS`(12) раз, истёк лимит → явный
|
||||
`False` с причиной "CI still pending after Ns" (не виснет молча). Параметры в `config.py`
|
||||
как env `ORCH_CI_POLL_*`. ADR-0004. +5 тестов (мок httpx + time.sleep).
|
||||
|
||||
---
|
||||
|
||||
## 3. ORCH-47 — тестер-гейт игнорил `result:` (исправлен, в проде)
|
||||
|
||||
### Проблема (уловка-22)
|
||||
`check_tests_passed`/`_parse_tests_verdict` читал только `verdict:`/`status:` из frontmatter
|
||||
`13-test-report.md`, но промпт tester-агента велит писать `result: PASS|FAIL`. Честный тестер
|
||||
(`result: PASS`, без `verdict:`) → гейт «No machine-readable verdict» → ложный FAIL → петля
|
||||
dev↔review↔tester → Blocked. **И сама ORCH-47 (которая это чинит) попала в тот же капкан:**
|
||||
в проде крутился старый гейт → не понимал её собственный `result: PASS` → 3 круга петли.
|
||||
Змея кусает хвост: чтобы пройти гейт автономно, фикс уже должен быть в проде.
|
||||
|
||||
### Решение (PR #40, merge `5d04de9e`)
|
||||
`result:` добавлен как равноправное поле наряду с `verdict:`/`status:`. Любое одно непустое
|
||||
поле достаточно. Negative-токен (BLOCKED/FAILED) в ЛЮБОМ поле авторитетен (ET-013 кейс
|
||||
сохранён). Token sets заморожены для обратной совместимости. ADR-001. +6 тестов (68 passed).
|
||||
После деплоя ручной `advance_stage` пнул застрявшую task → гейт принял `result: PASS` →
|
||||
прошёл testing. Петля исчезла навсегда.
|
||||
|
||||
### Остаточная находка → B6 / ORCH-48
|
||||
На staging деплоер дал 9/10 PASS, завалил **B6 Registry isolation**: staging-реестр видит
|
||||
боевые ET+ORCH вместо одного sandbox (нарушает «staging — только sandbox»). Деплоер честно
|
||||
поставил FAILED и НЕ стал натягивать зелёнку (вне мандата) → откат by design. К фиксу гейта
|
||||
отношения не имеет (E2E против sandbox прошёл). Заведена ORCH-48.
|
||||
|
||||
---
|
||||
|
||||
## 4. ДЕПЛОЙ ПРОДА — как правильно (важная операционная памятка)
|
||||
|
||||
### `/app` запечён в образ, НЕ volume
|
||||
`docker-compose.yml`: `build: .` + `COPY src/ ./src/`. Поэтому `git pull` + рестарт с
|
||||
`--no-build` **НЕ довозит код** — нужен `docker compose build orchestrator`. Деплой-хук
|
||||
(`scripts/orchestrator-deploy-hook.sh`) по дефолту целит в **staging** (by design) — для
|
||||
прода нужны env `TARGET_SERVICE=orchestrator TARGET_PORT=8500 COMPOSE_PROFILE=''`.
|
||||
|
||||
### Порты/профили
|
||||
- prod orchestrator = порт **8500** (`/health` → `{"status":"ok"}`), `network_mode: host`,
|
||||
профиль prod = пустой (стартует обычным `docker compose up -d orchestrator`).
|
||||
- staging = порт **8501**, профиль `staging` (стартует только `--profile staging`).
|
||||
|
||||
### Рабочая последовательность деплоя (проверена дважды 05.06)
|
||||
1. `sudo chown -R slin:slin /home/slin/repos/orchestrator` (см. грабля ниже).
|
||||
2. `git checkout main && git reset --hard origin/main && git clean -fd -e '*.bak*' -e '.deploy-prev-image-prod'`.
|
||||
3. `docker compose build orchestrator`.
|
||||
4. `docker compose up -d orchestrator` + health-loop на :8500.
|
||||
5. **Проверка claude-auth** (ребилд её ломает — см. ниже).
|
||||
6. Проверка что новый код активен в `/app` (grep маркера правки).
|
||||
|
||||
### ⚠️ ГРАБЛЯ: хост-репо рассинхронизирован с git (агенты пишут под root)
|
||||
Хост-репо `/home/slin/repos/orchestrator` оказывался на feature-ветке (не main), а рабочая
|
||||
копия засеяна untracked+modified файлами, созданными агентами **под uid=0 (root-owned)** прямо
|
||||
в репо. → `git pull --ff-only` падал `Permission denied` / `would be overwritten`, обычный
|
||||
`rm` под slin не мог снести root-файлы. **Лечение:** `sudo chown -R slin:slin <repo>` →
|
||||
проверить что modified=совпадает-с-main и untracked=уже-в-main (дубликаты, не теряем) →
|
||||
`git reset --hard origin/main` + `git clean`. **Хук это НЕ разруливает** — сверять состояние
|
||||
хост-репо перед каждым деплоем.
|
||||
|
||||
### ⚠️ ГРАБЛЯ: ребилд ломает claude-auth (проверять ВСЕГДА)
|
||||
Пересоздание контейнера может root-овнить `/home/slin/.claude/.credentials.json` и сделать
|
||||
`/root/.claude` пустышкой → агенты падают `Not logged in`. Защита — монтирование creds в
|
||||
compose (`/home/slin/.claude` + `.claude.json`), launcher форсит `HOME=/home/slin`.
|
||||
**После каждого ребилда боевая проверка:**
|
||||
`docker exec orchestrator bash -c 'cd /tmp && HOME=/home/slin /opt/claude-code/bin/claude.exe --print "ОК"'`
|
||||
(timeout 90с). 05.06 auth пережил оба ребилда — защита держит.
|
||||
|
||||
---
|
||||
|
||||
## 5. ЗАПУСК конвейера и Gitea API
|
||||
|
||||
### Старт конвейера = Plane Backlog → In Progress
|
||||
Конвейер стартует штатно переводом задачи в Plane из Backlog в **In Progress** (код:
|
||||
`webhooks/plane.py handle_status_start` — «pipeline is started when Slava moves the issue
|
||||
into In Progress»). Webhook создаёт task-row, заводит ветку, запускает analyst. Никаких
|
||||
ручных вставок в БД.
|
||||
|
||||
### QG-0: лимит заголовка 80 символов
|
||||
При старте задача с заголовком >80 символов заворачивается на QG-0 («Title слишком длинный»)
|
||||
и уходит в Blocked. Чинить — укоротить `name` (суть в заголовок, детали в description),
|
||||
вернуть в Backlog, снова In Progress.
|
||||
|
||||
### Gitea API грабли
|
||||
- **merge/create PR** требуют заголовок `Authorization: token <ORCH_GITEA_TOKEN>` (форма
|
||||
с префиксом `token `), иначе 401 "token is required".
|
||||
- **heredoc через ssh+docker exec глотает вывод** python-скрипта. Надёжный путь: написать
|
||||
`.py` локально → `base64 -w0` → `ssh "echo <b64> | base64 -d > /tmp/x.py"` → `docker cp`
|
||||
→ `docker exec python3 /tmp/x.py`. Это же обходит экранирование кириллицы/скобок.
|
||||
|
||||
---
|
||||
|
||||
## Состояние прод-гейтов после 05.06
|
||||
- ✅ `check_ci_green` — поллинг с ретраем (ORCH-45)
|
||||
- ✅ `check_tests_passed` — читает `result:`/`verdict:`/`status:` (ORCH-47)
|
||||
|
||||
## Бэклог (high) после дня
|
||||
- **ORCH-44** — надёжность запуска агента (preflight слеп к auth; `--effort` гасит вывод;
|
||||
пустой run-лог → должен быть failed).
|
||||
- **ORCH-46** — «испорченный телефон»: орк не передаёт деву ТЕКСТ замечаний reviewer/tester
|
||||
(только ссылку на файл), противоречивые сигналы tester↔reviewer, нет памяти между кругами.
|
||||
- **ORCH-48 / B6** — staging registry isolation (staging видит прод-проекты вместо sandbox).
|
||||
@@ -1,103 +0,0 @@
|
||||
# Lessons Learned — ORCH-017 (Telegram approve-ping links)
|
||||
|
||||
## Дата: 2026-06-05
|
||||
## Задача: ORCH-017 — Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве BRD
|
||||
## Итог: смержено **вручную** (PR #37, merge `26c6f267`) после ~5 застреваний конвейера
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
Косметическая задача (две HTML-ссылки в уведомлении) **5 раз застряла** в конвейере и каждый
|
||||
раз требовала ручного пинка. Корень — **не баг задачи, а дыры автономности конвейера**. Код был
|
||||
готов и зелёный (434 теста), но пайплайн не мог довести его до merge сам. В итоге — ручной merge
|
||||
Owner-ом; четыре системные дыры заведены в бэклог (ORCH-44/45/46/47).
|
||||
|
||||
---
|
||||
|
||||
## Хронология застреваний
|
||||
|
||||
1. **Auth claude после rebuild** — агенты падали `Not logged in` (root-owned creds + `/root/.claude`
|
||||
пустышка). См. отдельный разбор в memory/INCIDENT по auth. → починено + защищено монтированием.
|
||||
2. **`check_ci_green` race** — гейт опросил CI **один раз** в `17:58:54` → `pending`; CI дозеленел в
|
||||
`17:58:55` (промах на 1 секунду). Повторного опроса нет → задача висит насмерть с зелёным CI.
|
||||
3. **Петля dev↔review↔testing → `max retries reached`** (MAX_DEVELOPER_RETRIES=3).
|
||||
4. **Откат неполный** — убрали код shared-гейта, но оставили 2 doc-строки про него → рассинхрон
|
||||
код↔доки → reviewer снова REQUEST_CHANGES.
|
||||
5. **Объективный дедлок** (см. ниже) → ручной merge.
|
||||
|
||||
---
|
||||
|
||||
## Корневые проблемы (→ бэклог)
|
||||
|
||||
### P1. `check_ci_green` промахивается на гонке CI (→ ORCH-45)
|
||||
Гейт читает статус CI **ровно один раз** сразу после developer. Если CI ещё `pending` — задача
|
||||
застревает молча, без повторного опроса. Нужен polling с ретраем: `pending` → ждать N×15с,
|
||||
`success` → advance, `failure` → rollback, вечный `pending` → уведомить (не застревать молча).
|
||||
|
||||
### P2. Developer не понимает замечаний reviewer/tester — "испорченный телефон" (→ ORCH-46)
|
||||
**Это прямой удар по автономности.** Три причины, почему dev повторял одну и ту же ошибку:
|
||||
- **Испорченный телефон.** При REQUEST_CHANGES `stage_engine.py:~421` шлёт developer-у только
|
||||
`"Fix findings in docs/work-items/<WI>/12-review.md"` — **без текста претензий**, лишь ссылку на
|
||||
файл. Ключевую governance-мысль легко проскочить. → Вклеивать ТЕКСТ findings прямо в task_desc.
|
||||
- **Противоречивые сигналы.** После tester прилетает `"Tests FAILED. Fix failures"` (толкает чинить
|
||||
связанное с тестами → dev лез в test-gate). После reviewer — `"не трогай gate"`. Два
|
||||
противоположных приказа. → Склеивать замечания tester+reviewer в одно непротиворечивое ТЗ.
|
||||
- **Нет памяти между кругами.** Каждый запуск developer — новый чистый агент, не помнит прошлых
|
||||
заворотов. Видит "тесты падают" → снова лезет в gate. → Передавать историю прошлых REQUEST_CHANGES/
|
||||
FAIL ("на чём уже погорел, чего НЕ делать"). Можно: ранняя эскалация к Owner при повторе.
|
||||
|
||||
### P3. `check_tests_passed` игнорирует поле `result:` (→ ORCH-47)
|
||||
`_parse_tests_verdict` (`src/qg/checks.py`) читал только `verdict:`/`status:` из frontmatter
|
||||
`13-test-report.md`. НО промпт tester-агента (`.openclaw/agents/tester*`) предписывает писать
|
||||
`result: PASS | FAIL`. Честный тестер (отчёт ORCH-017: `result: PASS`, без `verdict:`/`status:`)
|
||||
проваливал гейт ложным «Tests FAILED» → откат на development. ORCH-016 проходил лишь потому, что
|
||||
дублировал `verdict:` И `result:`. → Гейт должен читать `result:` как первоклассное машинное поле.
|
||||
**ВАЖНО:** это shared-гейт (влияет на ВСЕ проекты общего прода) → требует отдельного ADR
|
||||
(CLAUDE.md правило 2), потому вынесено в свой work item, не в ORCH-017.
|
||||
|
||||
### P4. Preflight слеп к auth и битым флагам (→ ORCH-44)
|
||||
`claude --version` отвечает даже без логина → preflight=ok, а реальный запуск падает `Not logged in`.
|
||||
Плюс `--effort` с CLI 2.1.142 + `--print`/`--output-format json` гасит вывод. Нужны: дешёвая
|
||||
проверка auth без токенов (права+дата истечения OAuth в `.credentials.json`), фикс effort,
|
||||
«пустой лог + job running + процесс мёртв → failed».
|
||||
|
||||
---
|
||||
|
||||
## Главный урок: объективный дедлок shared-инфры
|
||||
|
||||
ORCH-017 попала в **неразрешимый автономно дедлок** из-за того, что тест-отчёт уже написан под
|
||||
новый контракт (`result: PASS`):
|
||||
- **С фиксом гейта в ветке** → reviewer заворачивает (governance: shared-инфра без ADR). ❌
|
||||
- **Без фикса гейта** → `check_tests_passed` не видит `result:` → ложный FAIL → откат. ❌
|
||||
|
||||
**Вывод:** изменение shared quality-gate нельзя протаскивать внутри прикладной задачи. Оно создаёт
|
||||
циклическую зависимость (артефакты задачи зависят от изменённого гейта, а гейт нельзя менять без
|
||||
отдельного ADR). Менять shared-гейты — только отдельным work item со своим ADR. Если артефакты уже
|
||||
написаны под новый контракт — задача физически не пройдёт, пока не приедет фикс гейта.
|
||||
|
||||
---
|
||||
|
||||
## Урок про роль ассистента/оператора
|
||||
|
||||
Когда оператор **раз за разом пинает гейты и чистит за dev вручную** — это сигнал «конвейер не тянет
|
||||
автономно». Честнее предложить Owner-у ручной merge/эскалацию, чем гонять карусель кругов и доказывать
|
||||
конвейеру то, что уже готово (код зелёный, reviewer: «технически корректно», претензии процедурные).
|
||||
|
||||
---
|
||||
|
||||
## Урок про откат
|
||||
|
||||
При откате **кода** обязательно откатывать и **доки/CHANGELOG**, иначе возникает обратный
|
||||
рассинхрон код↔доки (доки описывают фичу, которой в коде уже нет) → reviewer заворачивает. Откат —
|
||||
это код + доки + changelog + (при необходимости) тест-отчёт одним согласованным движением.
|
||||
|
||||
---
|
||||
|
||||
## Что сработало хорошо
|
||||
|
||||
- **Reviewer ловит governance-нарушения** — корректно завернул протаскивание shared-гейта в
|
||||
прикладную задачу. Процедурно прав, даже когда код технически верный.
|
||||
- **Безопасный ручной пинок гейта** через `stage_engine.advance_stage(...)` — без ребилда/мержа,
|
||||
перевызывает QG внутри процесса орка.
|
||||
- **Ручной merge как осознанный выход** из дедлока (с явным ОК Owner), а не бесконечные круги.
|
||||
@@ -1,119 +0,0 @@
|
||||
# LESSONS — ORCH-048 (B6 staging registry isolation, вариант «в»)
|
||||
|
||||
**Дата:** 2026-06-06
|
||||
**Work item:** ORCH-048 — «staging B6 check reads registry from host worktree, not staging container»
|
||||
**Статус:** ✅ Done. Merge PR #45 (`2a36ed80`), Plane → Done, task 38 → done. Прод не тронут.
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
B6-чек staging-suite давал **ложный FAIL** (`prod-ET=YES, prod-ORCH=YES`), блокируя `deploy-staging` у **всех** ORCH-задач, хотя изоляция реестра в staging работала корректно. Починили, выбрав архитектурный вариант, который **не порождает новых ловушек автономности**. По дороге словили три урока, которые стоят дороже самой фичи.
|
||||
|
||||
---
|
||||
|
||||
## 1. Root cause (для истории)
|
||||
|
||||
`scripts/staging_check.py` блок **B6** был единственным чеком suite, который не ходил по HTTP к живому инстансу, а **импортировал Python-код локально**:
|
||||
|
||||
```python
|
||||
sys.path.insert(0, "/repos/orchestrator") # host-worktree
|
||||
importlib.reload(sys.modules["src.projects"]) # подхватывает env ТЕКУЩЕГО процесса
|
||||
known = known_plane_project_ids()
|
||||
```
|
||||
|
||||
Деплоер запускал suite **с хоста**, где `ORCH_PROJECTS_JSON` не задан → `src.projects` грузил встроенный `_DEFAULT_PROJECTS` (ET+ORCH) → `known_plane_project_ids()` возвращал боевые id → **ложный FAIL**. То есть B6 проверял реестр НЕ того окружения, реестр которого реально использует staging-инстанс.
|
||||
|
||||
Изоляция при этом была исправна: внутри `orchestrator-staging` `known_plane_project_ids()` корректно отдавал только sandbox (`.env.staging`).
|
||||
|
||||
---
|
||||
|
||||
## 2. ГЛАВНЫЙ УРОК: «курица-яйцо» в staging-гейте
|
||||
|
||||
Архитектор на первом прогоне выбрал **вариант (а): новый HTTP-эндпоинт `GET /projects`**, и B6 стал ходить на него. Решение красивое (единый HTTP-стиль с остальными чеками), **но оно само себя заблокировало**:
|
||||
|
||||
- B6 проверяет **работающий** staging-инстанс (порт 8501).
|
||||
- Эндпоинт `/projects` **запечён в Docker-образ** (`src/main.py`).
|
||||
- В текущем (ещё не пересобранном) образе эндпоинта НЕТ → `GET /projects` → **404** → B6 FAIL → откат на development.
|
||||
- Чтобы чек прошёл, нужен **ручной bootstrap-деплой** образа. А деплой не происходит, потому что чек красный. **Тупик by design.**
|
||||
|
||||
Подтверждено на проде: `GET /projects` на 8501 и 8500 → 404 → `deploy-staging FAILED`.
|
||||
|
||||
**Вывод-правило:**
|
||||
> Staging-чек НЕ должен проверять то, что появляется в работающем инстансе только ПОСЛЕ деплоя проверяемой ветки. Иначе первый прогон всегда падает и требует ручного bootstrap — это прямая поломка автономности.
|
||||
|
||||
**Решение — вариант (в):** запускать suite **ВНУТРИ** staging-контейнера (`docker exec orchestrator-staging`), читать реестр из собственного process-env контейнера, убрать host-path хак. Преимущество принципиальное:
|
||||
- B6 не зависит от того, что отдаёт инстанс по HTTP.
|
||||
- `staging_check.py` берётся из bind-mount → свежий код подхватывается **без ребилда образа**.
|
||||
- **Курицы-яйца нет ни на первом прогоне, ни в будущем.**
|
||||
|
||||
Вариант (б) (`docker exec ... python3 -c "..."` + парсинг stdout) отклонён: хрупкое экранирование (см. `LESSONS_2026-06-05.md`).
|
||||
|
||||
**Как это попало в реализацию:** после FAIL под (а) — откатили ветку к analyst-артефактам (`git reset --hard <analyst-commit>`), стёрли ADR(а)+код(а), зашили в `02-trz.md §4` блок «РЕШЕНИЕ ПРИНЯТО ВЛАДЕЛЬЦЕМ: вариант (в)» с обоснованием и чек-листом, откатили задачу на `architecture` + поставили job архитектору заново. Второй прогон: arch→dev→review→tester→deploy-staging — без петель, **B6 ✓ PASS, 10/10**.
|
||||
|
||||
---
|
||||
|
||||
## 3. УРОК: орк мержит в main ТОЛЬКО логи, а не фикс-код
|
||||
|
||||
После прохождения staging орк сам:
|
||||
- закрыл задачу в `done`,
|
||||
- смержил в `main` PR с **логами** (`15-staging-log.md`, `14-deploy-log.md`),
|
||||
- но **сам фикс-код остался в feature-ветке** — `main` всё ещё содержал старый сломанный B6.
|
||||
|
||||
Это by design: фичу в main вливает **владелец**. Поймали проверкой:
|
||||
|
||||
```bash
|
||||
git fetch origin -q
|
||||
git log --oneline origin/main..origin/feature/<branch> # покажет невлитые коммиты фикса
|
||||
git show origin/main:scripts/staging_check.py | grep -c '_evaluate_b6' # 0 = фикс НЕ в main
|
||||
```
|
||||
|
||||
**Правило:**
|
||||
> Прежде чем считать задачу реально доставленной — проверить `git log origin/main..feature` и наличие ключевой функции/строки фикса в `origin/main`. `done` в Plane + смерженные логи ≠ код в main.
|
||||
|
||||
Финальный шаг: смерджить feature-PR в main (Gitea API, `Do: merge`), затем синхронизировать host-репо.
|
||||
|
||||
---
|
||||
|
||||
## 4. УРОК: rollout bind-mount-фикса = host `git pull`, без ребилда/рестарта прода
|
||||
|
||||
ORCH-048 менял только **bind-mounted / non-runtime** артефакты:
|
||||
|
||||
| Файл | Как доходит до прода |
|
||||
|------|----------------------|
|
||||
| `scripts/staging_check.py` | bind-mount (`/home/slin/repos` → `/repos`); **не** в образе (`scripts/` нет в `/app`) → host `git pull` → live сразу |
|
||||
| `.openclaw/agents/deployer.md` | bind-mounted промпт, читается при запуске агента → live на следующем запуске |
|
||||
| `tests/`, `docs/` | не деплоятся |
|
||||
|
||||
`src/` и `Dockerfile` НЕ менялись → **рестарт/ребилд прод-контейнера 8500 не нужен и не делался** (zero group-risk для ET).
|
||||
|
||||
**Грабли host-репо:** `git pull` в `/home/slin/repos/orchestrator` сначала упёрся в `sudo: a password is required` — ложная тревога. Репо принадлежит `slin`, sudo не нужен; прямой `git pull --ff-only origin main` прошёл. **Сначала проверь `ls -ld` / `stat -c %U` репо — не лезь в sudo вслепую.**
|
||||
|
||||
**Верификация rollout в живом bind-mount (обязательна):**
|
||||
```bash
|
||||
grep -c '_evaluate_b6' scripts/staging_check.py # >=1
|
||||
grep -c 'sys.path.insert(0, "/repos/orchestrator")' scripts/staging_check.py # 0
|
||||
grep -c 'docker exec orchestrator-staging' .openclaw/agents/deployer.md # >=1
|
||||
curl -s -o /dev/null -w '%{http_code}' http://localhost:8500/health # 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Технические заметки (gotchas)
|
||||
|
||||
- **В контейнере orchestrator НЕТ `curl`** — для Gitea/Plane API использовать `urllib` через python (script-file → base64 → `docker cp` → `docker exec`).
|
||||
- **Plane state-id зависят от проекта.** Approved для проекта orchestrator = `63f2c8fe-dcda-4ace-952f-dd88bd0118ff` (НЕ дефолтный `a519a341...` из кода — тот для sandbox/ET). Брать реальные state-id через `GET .../states/`.
|
||||
- **BRD-апрув = перевод Plane-issue в статус Approved** → webhook ловит смену статуса → путь `agent=None` → `approved-via-status` → гейт пропускает, БЕЗ повторного запуска `check_analysis_approved`.
|
||||
- **Dockerfile НЕ копирует `scripts/`** в образ — `staging_check.py` доступен в контейнере только через mount. Путь запуска внутри контейнера учитывать (не `/app/scripts`).
|
||||
- **Перезапуск стадии вручную:** `update_task_stage(task_id, "<stage>")` + `enqueue_job(agent, repo, task_content, task_id)`. Guard перед этим: `agent_running IS NULL` И нет jobs со `status IN ('queued','running')` для task_id.
|
||||
|
||||
---
|
||||
|
||||
## 6. Итог по гейтам/ядру после серии ORCH-45/46/47/48
|
||||
|
||||
- ✅ `check_ci_green` — поллинг (ORCH-45)
|
||||
- ✅ `check_tests_passed` — читает `result:` (ORCH-47)
|
||||
- ✅ `stage_engine` — передаёт деву **текст** findings, не только ссылку (ORCH-46)
|
||||
- ✅ B6 staging — читает реестр ВНУТРИ staging-контейнера, больше не ложный FAIL (ORCH-48) → **deploy-staging разблокирован для всех ORCH-задач**
|
||||
|
||||
Конвейер стал по-настоящему автономным: задача проходит analyst→deploy без ручного пинания стадий.
|
||||
@@ -30,40 +30,18 @@
|
||||
|
||||
Оба: `network_mode: host`, `init: true` (tini как PID 1 — reaping зомби, B-2), `restart: unless-stopped`.
|
||||
|
||||
### Рантайм-uid (ORCH-040)
|
||||
Оба сервиса бегут под `user: "1000:1000"` (slin), **не** root. Артефакты конвейера
|
||||
(git worktree `/repos/_wt/...`, коммиты в `docs/work-items/...`) создаются как
|
||||
`slin:slin`, поэтому `git pull` / `git reset` на хосте под slin работают без ручного
|
||||
`chown`. Доступ к docker.sock сохранён через `group_add: ["999"]` (gid docker, **не**
|
||||
через root — НЕ удалять). При переносе на другой хост uid пересматривается. См.
|
||||
ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и глобальный
|
||||
`docs/architecture/adr/adr-0005-container-runs-as-host-uid.md`.
|
||||
|
||||
**Host-prerequisites (обязательная процедура Owner, в git не коммитятся):**
|
||||
- **P-1 (блокер):** uid 1000 читает claude creds — `chown -R 1000:1000 /home/slin/.claude`;
|
||||
проверка `sudo -u '#1000' test -r /home/slin/.claude/.credentials.json`. Без этого
|
||||
preflight (ORCH-044) заворачивает весь конвейер.
|
||||
- **P-2:** ssh-ключи в `/home/slin/.orchestrator-ssh` читаемы uid 1000 (маунт ведёт в `/home/slin/.ssh`).
|
||||
- **P-3:** `id slin` → `1000:1000`; `/repos`, `/app/data` уже `1000:1000`.
|
||||
- **P-4:** прод-рестарт self — только в окно тишины (`GET /status` без активных задач):
|
||||
общий инстанс с enduro-trails.
|
||||
- Разовый разгребающий `chown -R 1000:1000 /home/slin/repos/orchestrator` для старых
|
||||
`root:root` файлов из истории (вне объёма кода).
|
||||
|
||||
### Тома (volumes)
|
||||
- `./data` → `/app/data` (БД; у staging — `./data/staging`)
|
||||
- `/home/slin/repos` → `/repos` (рабочие репозитории проектов)
|
||||
- `/var/run/docker.sock` (для docker-операций деплоя)
|
||||
- claude-code, node, `~/.claude*` (CLI агентов, ro)
|
||||
- `~/.orchestrator-ssh` → `/home/slin/.ssh` (ro, деплой по ssh; target в HOME агента,
|
||||
согласован с `HOME=/home/slin` из launcher — ORCH-040, ранее `/root/.ssh`)
|
||||
- `~/.orchestrator-ssh` → `/root/.ssh` (ro, деплой по ssh)
|
||||
|
||||
## Переменные окружения (карта; значения — в `.env`)
|
||||
|
||||
| Переменная | Назначение |
|
||||
|-----------|-----------|
|
||||
| `ORCH_PLANE_API_URL` / `_TOKEN` / `_WORKSPACE_SLUG` | доступ к Plane API |
|
||||
| `ORCH_PLANE_WEB_URL` | внешний (браузерный) web-URL Plane для кликабельных ссылок на issue в уведомлениях (ORCH-017); пусто → фолбэк на `ORCH_PLANE_API_URL`, loopback-фолбэк → ссылка опускается |
|
||||
| `ORCH_PLANE_WEBHOOK_SECRET` | HMAC-проверка вебхуков Plane |
|
||||
| `ORCH_GITEA_URL` / `_TOKEN` / `_WEBHOOK_SECRET` | доступ к Gitea + HMAC |
|
||||
| `ORCH_CLAUDE_BIN` | путь к claude CLI |
|
||||
@@ -75,12 +53,6 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл
|
||||
| `ORCH_AGENT_EFFORT_DEFAULT` | режим работы `--effort` по умолчанию (ORCH-41): low\|medium\|high\|xhigh\|max; дефолт `high` |
|
||||
| `ORCH_AGENT_EFFORT_<AGENT>` | per-agent effort; дефолт: думающие → high, tester/deployer → medium |
|
||||
| `ORCH_AGENT_FALLBACK_MODEL` | опц. фолбэк-модель при overloaded (`--fallback-model`); пусто → без флага |
|
||||
| `ORCH_RECONCILE_ENABLED` | kill-switch sweeper потерянных webhook (ORCH-053); дефолт `true`. **При инциденте/раскатке** — `false` глушит весь фоновый reconciler |
|
||||
| `ORCH_RECONCILE_PLANE_ENABLED` | отдельный флаг F-2 (опрос Plane API); `false` гасит только plane-ветку, F-1 продолжает работать; дефолт `true` |
|
||||
| `ORCH_RECONCILE_INTERVAL_S` | период фонового прохода reconciler, сек; дефолт `120` |
|
||||
| `ORCH_RECONCILE_GRACE_DEFAULT_S` | порог «застряла» по `tasks.updated_at`, сек; дефолт `600` |
|
||||
| `ORCH_RECONCILE_GRACE_OVERRIDES_JSON` | per-stage пороги, напр. `{"development":300}`; невалидный JSON → дефолт |
|
||||
| `ORCH_RECONCILE_NOTIFY_UNBLOCK` | слать Telegram при разблокировке застрявшей задачи; дефолт `true` |
|
||||
| `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука |
|
||||
|
||||
**Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`.
|
||||
|
||||
@@ -36,53 +36,34 @@ Exit code: **0** = все PASS, **non-zero** = есть FAIL.
|
||||
|
||||
## Способы запуска
|
||||
|
||||
### 1. Внутри контейнера (КАНОНИЧЕСКИЙ — обязателен для деплоера)
|
||||
### 1. Внутри контейнера (рекомендуемый)
|
||||
|
||||
```bash
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py --mode stub
|
||||
```
|
||||
|
||||
### 2. С хоста (если есть токены в env)
|
||||
|
||||
```bash
|
||||
export ORCH_STAGING=true
|
||||
export ORCH_PLANE_API_TOKEN=...
|
||||
# ... остальные переменные ...
|
||||
|
||||
python3 scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 \
|
||||
--mode stub
|
||||
```
|
||||
|
||||
### 3. Из docker exec с передачей URL
|
||||
|
||||
```bash
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
--base-url http://localhost:8501 \
|
||||
--mode stub
|
||||
```
|
||||
|
||||
Это единственный канонический способ для стадии `deploy-staging` (ORCH-048, ADR-001).
|
||||
Внутри контейнера env уже staging (`.env.staging`), а чек **B6** строит реестр проектов из
|
||||
собственного process-env инстанса (см. ниже). Путь к скрипту — `/repos/orchestrator/scripts/…`
|
||||
(bind-mount); `scripts/` **не** копируется в образ, поэтому `/app/scripts` не существует.
|
||||
|
||||
### 2. С хоста — НЕ рекомендуется
|
||||
|
||||
```bash
|
||||
# ⚠️ Воспроизводит баг ORCH-048: на хосте ORCH_PROJECTS_JSON не задан →
|
||||
# B6 строит реестр из дефолта (ET+ORCH) → ложный FAIL.
|
||||
# Допустимо ТОЛЬКО если env хоста полностью повторяет staging (включая ORCH_PROJECTS_JSON).
|
||||
export ORCH_STAGING=true
|
||||
export ORCH_PROJECTS_JSON=... # обязателен, иначе B6 даст ложный FAIL
|
||||
export ORCH_PLANE_API_TOKEN=...
|
||||
# ... остальные переменные ...
|
||||
|
||||
python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Механика чека B6 (ORCH-048, ADR-001)
|
||||
|
||||
B6 «Registry: sandbox present, prod ET/ORCH absent» подтверждает изоляцию: в реестре
|
||||
работающего staging-инстанса есть только sandbox-проект и НЕТ боевых (ET/ORCH).
|
||||
|
||||
- B6 импортирует `known_plane_project_ids()` из `src.projects` **кода контейнера**
|
||||
(`/app/src` через `PYTHONPATH=/app`), env которого — `.env.staging`. Реестр отражает
|
||||
именно работающий staging-инстанс.
|
||||
- Прежний host-path хак (`sys.path.insert(0, "/repos/orchestrator")` + `importlib.reload`)
|
||||
удалён: он подхватывал env процесса-запускателя и при запуске с хоста давал ложный FAIL.
|
||||
- Логика вердикта вынесена в чистую функцию `_evaluate_b6(known) -> (passed, detail)`:
|
||||
`passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known`. Покрыта юнит-тестами
|
||||
(`tests/test_staging_check_b6.py`) на оба исхода без поднятия инстанса/docker.
|
||||
- При недоступности источника реестра B6 даёт детерминированный FAIL (не ложный PASS,
|
||||
не необработанное исключение).
|
||||
|
||||
**Поэтому B6 достоверен только при каноническом запуске (способ 1).**
|
||||
|
||||
---
|
||||
|
||||
## Режимы (`--mode`)
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве
|
||||
|
||||
Work Item ID: ORCH-017
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,91 +0,0 @@
|
||||
# 01-BRD — ORCH-017: Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве
|
||||
|
||||
Work Item: **ORCH-017**
|
||||
Repo: `orchestrator` · Branch: `feature/ORCH-017-brd-plane-telegram`
|
||||
Тип: косметическая правка (UX уведомлений). Парная с ORCH-016.
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
Когда оркестратор завершает стадию `analysis` и просит подтвердить BRD, в Telegram уходит
|
||||
отдельное «пингующее» уведомление (`notify_approve_requested` в `src/notifications.py`).
|
||||
Сейчас в этом сообщении **нет ссылок**: владелец (Слава) вынужден вручную зайти в Plane,
|
||||
найти нужную issue, открыть комментарий аналитика, оттуда перейти к BRD-документу. Это
|
||||
лишние ручные шаги на каждой задаче.
|
||||
|
||||
Текущий текст уведомления:
|
||||
> 📋 {WI}: BRD/ТЗ/AC готовы. Переведите задачу в статус Approved в Plane для продолжения.
|
||||
|
||||
## 2. Цель
|
||||
В **этом же** уведомлении дать две прямые кликабельные ссылки, чтобы весь сценарий
|
||||
прохождения апрува выполнялся из Telegram, без ручной навигации в Plane:
|
||||
1. **Ссылка на BRD** — открывает `01-brd.md` в Gitea (прочитать документ).
|
||||
2. **Ссылка на Plane-issue** — открывает задачу в Plane (перевести в Approved / отклонить с комментом).
|
||||
|
||||
## 3. Целевой сценарий (Слава)
|
||||
Получил уведомление → кликнул «📄 BRD» → прочитал → кликнул «✅ Задача» → перевёл в
|
||||
Approved (или отклонил с комментарием). Всё из Telegram.
|
||||
|
||||
## 4. Объём (Scope)
|
||||
### В объёме (выбранный по умолчанию минимальный вариант — см. §8 открытые вопросы)
|
||||
- Доработка **только** функции `notify_approve_requested(task_id)` в `src/notifications.py`
|
||||
(стадия `analysis`, запрос статуса Approved).
|
||||
- Формирование двух ссылок и встраивание их в текст того же отдельного уведомления.
|
||||
- Формат — HTML-ссылки в тексте (`<a href="…">label</a>`), т.к. `send_telegram` уже шлёт
|
||||
`parse_mode="HTML"`. Альтернатива (inline-кнопки) — открытый вопрос §8.
|
||||
- Новая конфиг-настройка для внешнего web-URL Plane (см. §6, риск №1).
|
||||
- Обновление документации (`CLAUDE.md` env-карта при необходимости, `CHANGELOG.md`,
|
||||
`.env.example`) в том же PR.
|
||||
|
||||
### Вне объёма (НЕ трогать)
|
||||
- Логика апрува: `:approved:`-handler, `check_analysis_approved`, переходы стадий.
|
||||
- Живой Telegram-трекер (`update_task_tracker` / `render_task_tracker`, PR #21/#22) — его
|
||||
текст и поведение не меняем; новое уведомление остаётся ОТДЕЛЬНЫМ сообщением, дубли
|
||||
трекера не создаём.
|
||||
- Содержимое комментариев в Plane (это смежная задача ORCH-016).
|
||||
- Ссылки в других уведомлениях (deploy-failed, agent-failed, error) — вне объёма по
|
||||
умолчанию (см. открытый вопрос §8.2).
|
||||
|
||||
## 5. Заинтересованные стороны
|
||||
- **Owner / получатель уведомления:** Слава.
|
||||
- **Поставщик данных:** оркестратор (БД `tasks`: repo, branch, work_item_id, plane_issue_id).
|
||||
|
||||
## 6. Функциональные требования
|
||||
| # | Требование |
|
||||
|---|------------|
|
||||
| FR-1 | Уведомление об апруве BRD содержит кликабельную ссылку на документ `docs/work-items/<WI>/01-brd.md` в Gitea. |
|
||||
| FR-2 | То же уведомление содержит кликабельную ссылку на соответствующую Plane-issue. |
|
||||
| FR-3 | Существующий текст-призыв («Переведите задачу в статус Approved …») сохраняется. |
|
||||
| FR-4 | Уведомление остаётся ОДНИМ отдельным пингующим сообщением (без дублей, без второго сообщения). |
|
||||
| FR-5 | Ссылка на BRD строится на внешнем `gitea_public_url` (фоллбэк `gitea_url`), формат branch-view: `{base}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{WI}/01-brd.md`. Переиспользовать существующий паттерн из `src/usage.py`. |
|
||||
| FR-6 | Ссылка на Plane-issue строится на внешнем web-URL Plane + workspace + project + issue. |
|
||||
|
||||
## 7. Нефункциональные требования
|
||||
| # | Требование |
|
||||
|---|------------|
|
||||
| NFR-1 | **Никогда не ронять оркестратор** из-за уведомления: построение ссылок обёрнуто в защиту, при отсутствии данных (нет branch / нет plane_issue_id / не задан web-URL) — сообщение всё равно отправляется, просто без соответствующей ссылки (graceful degradation). |
|
||||
| NFR-2 | Не нарушать self-hosting: правка не требует рестарта прод-контейнера сверх обычного деплоя; не меняет реестр гейтов/стадий. |
|
||||
| NFR-3 | Сохранить `parse_mode="HTML"`; экранировать динамические подписи (`html.escape`), URL формировать из доверенных конфиг-значений. |
|
||||
|
||||
## 8. Открытые вопросы (требуют решения Owner; в документах принят безопасный дефолт)
|
||||
1. **Формат ссылок.** Дефолт BRD: HTML-ссылки в тексте (минимальная правка). Альтернатива —
|
||||
inline-кнопки «📄 Открыть BRD» / «✅ К задаче в Plane», что требует доработки `send_telegram`
|
||||
(параметр `reply_markup`/`inline_keyboard`). → решение к стадии architecture.
|
||||
2. **Охват.** Дефолт: только BRD-апрув (`notify_approve_requested`). Альтернатива — все точки,
|
||||
требующие решения Славы (напр. согласование макета ORCH-14). → если «все точки», объём
|
||||
расширяется, нужен отдельный перечень событий.
|
||||
3. **Внешний web-URL Plane.** В конфиге сейчас только внутренний `plane_api_url`
|
||||
(`http://localhost:8091`) — он НЕ годится для браузерной ссылки. Дефолт: завести новую
|
||||
env-настройку `ORCH_PLANE_WEB_URL` (внешний адрес Plane) с фоллбэком на `plane_api_url`.
|
||||
Точное значение URL должен подтвердить Owner/INFRA.
|
||||
4. **Формат Plane-ссылки.** `…/{workspace}/projects/{project_id}/issues/{issue_id}/` (надёжно,
|
||||
issue_id есть в `tasks.plane_issue_id`) vs короткий `…/{workspace}/browse/<IDENT>/`
|
||||
(зависит от соответствия `work_item_id` ↔ Plane identifier, что не гарантировано из-за
|
||||
zero-padding ORCH-017 vs ORCH-17). → решение к стадии architecture.
|
||||
|
||||
## 9. Зависимости и связки
|
||||
- **PR #14** — `gitea_public_url`: переиспользуем для кликабельных ссылок на доки.
|
||||
- **PR #21/#22** — живой Telegram-трекер: новое сообщение остаётся отдельным, трекер не трогаем.
|
||||
- **ORCH-016** — единые коммент-артефакты в Plane (парная задача про навигацию к документам).
|
||||
|
||||
## 10. Критерий бизнес-успеха
|
||||
Слава из одного Telegram-уведомления одним кликом открывает BRD и одним кликом — задачу в
|
||||
Plane, не заходя в Plane вручную и не ища комментарий.
|
||||
@@ -1,87 +0,0 @@
|
||||
# 02-ТЗ — ORCH-017: Прямые ссылки в Telegram-уведомлении об апруве BRD
|
||||
|
||||
Work Item: **ORCH-017** · Repo: `orchestrator`
|
||||
Опирается на 01-brd.md. Уточняет конкретные изменения кода/конфигурации.
|
||||
|
||||
> Примечание по канону: ТЗ фиксирует ТРЕБОВАНИЯ к изменениям, а не готовое
|
||||
> архитектурное решение. Выбор формата (текст vs inline-кнопки) и точного формата
|
||||
> Plane-URL — за стадией architecture (см. открытые вопросы 01-brd.md §8). Если по
|
||||
> ходу разработки ТЗ окажется неполным/неверным — возврат на стадию Анализ, без
|
||||
> правок ТЗ задним числом.
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
| Модуль | Роль в задаче |
|
||||
|--------|---------------|
|
||||
| `src/notifications.py` | **Основной.** Функция `notify_approve_requested(task_id)` (≈ строки 547–566) — единственная точка отправки пингующего уведомления об апруве BRD. Сюда добавляются ссылки. |
|
||||
| `src/config.py` | Класс `Settings`. Добавить настройку внешнего web-URL Plane (`plane_web_url`, env `ORCH_PLANE_WEB_URL`) с дефолтом-фоллбэком. |
|
||||
| `src/projects.py` | (Чтение) `get_project_by_repo(repo)` → `plane_project_id` для построения Plane-URL. |
|
||||
| `src/usage.py` | (Референс, не править) Эталонный паттерн branch-view ссылки на доки (`{base}/{owner}/{repo}/src/branch/{branch}/<rel>`), строки ≈483–503 — переиспользовать тот же формат. |
|
||||
| `src/db.py` | (Чтение) Таблица `tasks`: поля `work_item_id`, `repo`, `branch`, `plane_issue_id`. Источник данных для ссылок. |
|
||||
|
||||
## 2. Источники данных (из `tasks` по `task_id`)
|
||||
- `work_item_id` — путь к BRD-документу и (опц.) идентификатор issue.
|
||||
- `repo`, `branch` — построение Gitea branch-view URL.
|
||||
- `plane_issue_id` — uuid issue в Plane для прямой ссылки.
|
||||
- `project_id` — через `projects.get_project_by_repo(repo).plane_project_id`.
|
||||
|
||||
`notify_approve_requested` сейчас принимает только `task_id` и тянет лишь `work_item_id`
|
||||
через `_get_work_item_id`. Требуется дополнительно прочитать `repo`, `branch`,
|
||||
`plane_issue_id` из `tasks` (один SELECT, в защищённом try/except).
|
||||
|
||||
## 3. Требуемые изменения
|
||||
|
||||
### 3.1 `src/notifications.py`
|
||||
- Построить **BRD-ссылку** (FR-1/FR-5):
|
||||
`{base}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{work_item_id}/01-brd.md`,
|
||||
где `base = (settings.gitea_public_url or settings.gitea_url).rstrip('/')`,
|
||||
`owner = settings.gitea_owner`. Если нет `base`/`repo`/`branch`/`work_item_id` — ссылку
|
||||
опустить (NFR-1).
|
||||
- Построить **Plane-ссылку** (FR-2/FR-6):
|
||||
`{plane_web_base}/{workspace_slug}/projects/{project_id}/issues/{plane_issue_id}/`
|
||||
(точный формат — решение architecture, см. 01-brd §8.4). Если нет данных — опустить.
|
||||
- Встроить обе ссылки в текст того же сообщения (FR-3/FR-4), формат HTML-`<a>` по умолчанию.
|
||||
Сохранить существующий призыв «Переведите задачу в статус Approved …».
|
||||
- Сохранить вызов как **одно** `send_telegram(msg)` (пингующее, не silent). Порядок
|
||||
существующих действий не менять: старт BRD-часов (`mark_brd_review_started`) →
|
||||
`update_task_tracker(task_id)` → `send_telegram(msg)`.
|
||||
- Динамические подписи экранировать `html.escape` (NFR-3).
|
||||
|
||||
### 3.2 `src/config.py`
|
||||
- Добавить в `Settings` поле `plane_web_url: str = ""` (env `ORCH_PLANE_WEB_URL`).
|
||||
- Семантика фоллбэка: `plane_web_base = (settings.plane_web_url or settings.plane_api_url).rstrip('/')`.
|
||||
|
||||
### 3.3 Опционально (если выбран вариант inline-кнопок — открытый вопрос 01-brd §8.1)
|
||||
- Расширить `send_telegram(text, disable_notification=False, reply_markup=None)`:
|
||||
при наличии `reply_markup` прокидывать его в payload `sendMessage`. Обратная
|
||||
совместимость — обязательна (текущие вызовы без аргумента работают как раньше).
|
||||
- ⚠️ Это РАСШИРЯЕТ объём; включается только по явному решению Owner на стадии architecture.
|
||||
|
||||
## 4. Изменения API
|
||||
Нет. Публичные HTTP-эндпоинты (`/webhook/*`, `/status`, `/queue`, `/health`) не затрагиваются.
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
Нет. Все нужные поля (`repo`, `branch`, `work_item_id`, `plane_issue_id`) уже существуют в `tasks`.
|
||||
|
||||
## 6. Изменения конфигурации / окружения
|
||||
- Новая env-переменная `ORCH_PLANE_WEB_URL` (внешний web-адрес Plane). Прописать в
|
||||
`.env.example` (канон секретов/настроек), описать в env-карте (`CLAUDE.md` /
|
||||
`docs/operations/INFRA.md`). Реальное значение задаётся в `.env`/`.env.staging` на хосте.
|
||||
- Существующие `ORCH_GITEA_PUBLIC_URL`, `ORCH_GITEA_OWNER`, `ORCH_PLANE_WORKSPACE_SLUG`
|
||||
переиспользуются как есть.
|
||||
|
||||
## 7. Требования к новым QG checks
|
||||
Нет. Реестр `QG_CHECKS`, стадии и машинные вердикты не меняются (правка — отображение,
|
||||
не управление конвейером).
|
||||
|
||||
## 8. Артефакты pipeline, которые должны быть обновлены в ЭТОМ PR
|
||||
- `CHANGELOG.md` — запись о фиче.
|
||||
- `.env.example` — новая `ORCH_PLANE_WEB_URL`.
|
||||
- При добавлении настройки — env-карта в `CLAUDE.md` / `docs/operations/INFRA.md`.
|
||||
- ADR (стадия architecture): `docs/work-items/ORCH-017/06-adr/ADR-001-*.md` — фиксирует выбор
|
||||
формата (текст vs кнопки) и формат Plane-URL.
|
||||
|
||||
## 9. Ограничения
|
||||
- Не трогать `:approved:`-handler и `check_analysis_approved` (только текст/формат уведомления).
|
||||
- Не плодить сообщения: одно отдельное пингующее сообщение; живой трекер (PR #21/#22) не дублировать.
|
||||
- Соблюдать self-hosting: не ронять/не рестартить прод сверх штатного деплоя; обязательная
|
||||
страховка `deploy-staging` (8501) перед прод-деплоем орка.
|
||||
@@ -1,64 +0,0 @@
|
||||
# 03-Acceptance Criteria — ORCH-017
|
||||
|
||||
Work Item: **ORCH-017** · Repo: `orchestrator`
|
||||
Каждый критерий формулирует условие PASS/FAIL. Источник — 01-brd.md / 02-trz.md.
|
||||
|
||||
## AC-1 — Ссылка на BRD присутствует в уведомлении
|
||||
- **PASS:** Текст, сформированный `notify_approve_requested`, содержит кликабельную ссылку
|
||||
на `docs/work-items/<WI>/01-brd.md` вида
|
||||
`{gitea_public_url|gitea_url}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{WI}/01-brd.md`.
|
||||
- **FAIL:** Ссылки на BRD нет, либо она ведёт не на `01-brd.md`/не на нужный WI.
|
||||
|
||||
## AC-2 — Ссылка на Plane-issue присутствует в уведомлении
|
||||
- **PASS:** Тот же текст содержит кликабельную ссылку на issue в Plane, построенную на
|
||||
внешнем web-URL Plane + workspace + project + `plane_issue_id` (или согласованный браузер-формат).
|
||||
- **FAIL:** Ссылки на issue нет, либо она указывает на внутренний `localhost`/неверную issue.
|
||||
|
||||
## AC-3 — Базовый URL берётся из внешних настроек
|
||||
- **PASS:** BRD-ссылка использует `gitea_public_url`, при его пустоте — `gitea_url`; Plane-ссылка
|
||||
использует `plane_web_url` (env `ORCH_PLANE_WEB_URL`), при пустоте — `plane_api_url`.
|
||||
- **FAIL:** Захардкожен хост, либо ссылка нерабочая снаружи деплой-хоста.
|
||||
|
||||
## AC-4 — Существующий призыв сохранён
|
||||
- **PASS:** Текст по-прежнему содержит призыв перевести задачу в статус Approved (смысл строки
|
||||
«Переведите задачу в статус Approved … для продолжения» сохранён).
|
||||
- **FAIL:** Призыв удалён/искажён.
|
||||
|
||||
## AC-5 — Одно отдельное пингующее сообщение, без дублей
|
||||
- **PASS:** `notify_approve_requested` отправляет ровно одно сообщение через `send_telegram`
|
||||
(пингующее, не silent). Живой трекер (`update_task_tracker`) обновляется как раньше и не
|
||||
дублируется новым сообщением.
|
||||
- **FAIL:** Появляется второе/дубль-сообщение, либо трекер шлётся повторно как новое сообщение.
|
||||
|
||||
## AC-6 — Graceful degradation (никогда не ронять оркестратор)
|
||||
- **PASS:** При отсутствии `branch` / `plane_issue_id` / незаданном Plane web-URL функция НЕ
|
||||
бросает исключение: уведомление уходит с доступными ссылками (или без отсутствующей), орк жив.
|
||||
- **FAIL:** Отсутствие данных приводит к исключению/падению потока уведомлений.
|
||||
|
||||
## AC-7 — HTML-безопасность
|
||||
- **PASS:** Сохранён `parse_mode="HTML"`; динамические подписи экранируются (`html.escape`),
|
||||
URL валиден и не ломает разметку сообщения.
|
||||
- **FAIL:** Сообщение приходит с битой HTML-разметкой или с неэкранированным пользовательским текстом.
|
||||
|
||||
## AC-8 — Логика апрува не затронута
|
||||
- **PASS:** `:approved:`-handler, `check_analysis_approved`, переходы стадий и реестр `QG_CHECKS`
|
||||
без изменений; правка касается только текста/формата уведомления.
|
||||
- **FAIL:** Изменена логика гейта/перехода стадий.
|
||||
|
||||
## AC-9 — Документация обновлена в том же PR
|
||||
- **PASS:** Обновлены `CHANGELOG.md` и `.env.example` (новая `ORCH_PLANE_WEB_URL`); если добавлена
|
||||
настройка — отражено в env-карте (`CLAUDE.md`/`docs/operations/INFRA.md`); заведён ADR на
|
||||
выбранный формат. (Reviewer проверяет доку → нет обновления = REQUEST_CHANGES.)
|
||||
- **FAIL:** Код изменён, документация — нет.
|
||||
|
||||
## AC-10 — Тесты зелёные
|
||||
- **PASS:** Новые/затронутые тесты (`tests/test_notify_approve_links.py` и существующие
|
||||
`tests/test_telegram_tracker.py`, `tests/test_notify_done_regression.py`) проходят; `pytest tests/ -q` зелёный.
|
||||
- **FAIL:** Любой связанный тест падает.
|
||||
|
||||
---
|
||||
### Зависит от решений Owner (open questions 01-brd §8)
|
||||
- Если выбран вариант **inline-кнопок** — AC-1/AC-2 считаются выполненными при наличии кнопок
|
||||
«📄 Открыть BRD» / «✅ К задаче в Plane» с теми же URL; дополнительно AC: обратная совместимость
|
||||
`send_telegram` (старые вызовы без `reply_markup` работают).
|
||||
- Если охват расширен до **всех точек решения** — AC-1/AC-2 проверяются для каждой такой точки.
|
||||
@@ -1,99 +0,0 @@
|
||||
work_item: ORCH-017
|
||||
title: "Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве"
|
||||
notes: >
|
||||
Тесты изолируют сеть: send_telegram/httpx мокируются, проверяется СФОРМИРОВАННЫЙ текст
|
||||
(и/или reply_markup, если выбран вариант кнопок), а не реальная отправка. БД tasks
|
||||
наполняется фикстурой (work_item_id, repo, branch, plane_issue_id). Маппинг на критерии — в поле acceptance.
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "notify_approve_requested формирует текст с кликабельной ссылкой на 01-brd.md (Gitea branch-view)"
|
||||
module: tests/test_notify_approve_links.py
|
||||
setup: "task в tasks с work_item_id=ORCH-017, repo=orchestrator, branch=feature/ORCH-017-..., gitea_public_url задан; send_telegram замокан"
|
||||
expected: PASS
|
||||
acceptance: [AC-1, AC-3]
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "Текст содержит ссылку на Plane-issue с внешним web-URL + workspace + project + plane_issue_id"
|
||||
module: tests/test_notify_approve_links.py
|
||||
setup: "plane_web_url(ORCH_PLANE_WEB_URL) и workspace заданы; project резолвится по repo; plane_issue_id в tasks"
|
||||
expected: PASS
|
||||
acceptance: [AC-2, AC-3]
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "При пустом gitea_public_url BRD-ссылка строится на gitea_url (фоллбэк); при пустом plane_web_url — на plane_api_url"
|
||||
module: tests/test_notify_approve_links.py
|
||||
expected: PASS
|
||||
acceptance: [AC-3]
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "Сохранён призыв перевести задачу в статус Approved (подстрока 'Approved' присутствует)"
|
||||
module: tests/test_notify_approve_links.py
|
||||
expected: PASS
|
||||
acceptance: [AC-4]
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "send_telegram вызван ровно один раз (пингующее сообщение), без disable_notification=True"
|
||||
module: tests/test_notify_approve_links.py
|
||||
setup: "mock send_telegram, assert call_count == 1 и аргумент disable_notification не True"
|
||||
expected: PASS
|
||||
acceptance: [AC-5]
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "Graceful: branch=None / plane_issue_id=None — функция не бросает исключение, сообщение всё равно отправляется"
|
||||
module: tests/test_notify_approve_links.py
|
||||
setup: "task без branch и без plane_issue_id; убедиться что send_telegram всё равно вызван, отсутствующая ссылка опущена"
|
||||
expected: PASS
|
||||
acceptance: [AC-6]
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "Plane web-URL не задан и plane_api_url пуст — Plane-ссылка опускается, BRD-ссылка остаётся, орк не падает"
|
||||
module: tests/test_notify_approve_links.py
|
||||
expected: PASS
|
||||
acceptance: [AC-6]
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "Сохранён parse_mode=HTML; динамические подписи экранированы, HTML-разметка ссылок валидна"
|
||||
module: tests/test_notify_approve_links.py
|
||||
expected: PASS
|
||||
acceptance: [AC-7]
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "Регрессия трекера: update_task_tracker по-прежнему работает (silent edit), новое сообщение его не дублирует"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
acceptance: [AC-5, AC-8]
|
||||
|
||||
- id: TC-10
|
||||
type: integration
|
||||
description: "Поток analysis-approved: _handle_analysis_approved_flow при готовых артефактах вызывает notify_approve_requested; БД tasks даёт корректные repo/branch/plane_issue_id для ссылок"
|
||||
module: tests/test_analysis_approve_flow_links.py
|
||||
setup: "замокать сетевые вызовы Plane/Gitea/Telegram; убедиться, что check_analysis_approved/переходы стадий не изменены"
|
||||
expected: PASS
|
||||
acceptance: [AC-1, AC-2, AC-8]
|
||||
|
||||
# Условные тесты — включаются ТОЛЬКО если Owner выбрал вариант inline-кнопок (01-brd §8.1)
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "(Условный) Вариант кнопок: payload содержит reply_markup.inline_keyboard с кнопками '📄 Открыть BRD' и '✅ К задаче в Plane' с верными url"
|
||||
module: tests/test_notify_approve_links.py
|
||||
expected: PASS
|
||||
condition: "only if inline-buttons variant chosen"
|
||||
acceptance: [AC-1, AC-2]
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "(Условный) Обратная совместимость send_telegram: вызовы без reply_markup работают как раньше (payload без поля reply_markup)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
condition: "only if inline-buttons variant chosen"
|
||||
acceptance: [AC-5]
|
||||
@@ -1,117 +0,0 @@
|
||||
# ADR-001: Прямые ссылки в Telegram-уведомлении об апруве BRD (формат и Plane-URL)
|
||||
|
||||
Work Item: **ORCH-017** · Repo: `orchestrator` · Стадия: architecture
|
||||
Тип: per-work-item ADR (НЕ сквозной — реестр гейтов/стадий/компонентов не меняется).
|
||||
|
||||
## Статус
|
||||
Accepted
|
||||
|
||||
## Контекст
|
||||
BRD (`01-brd.md`) и ТЗ (`02-trz.md`) требуют добавить в пингующее уведомление об апруве
|
||||
BRD (`notify_approve_requested(task_id)` в `src/notifications.py`) две кликабельные ссылки:
|
||||
на документ `01-brd.md` в Gitea и на Plane-issue. ТЗ намеренно оставило за стадией
|
||||
architecture три развилки (открытые вопросы `01-brd.md` §8):
|
||||
|
||||
1. **§8.1 — формат ссылок:** HTML-`<a>` в тексте (минимум) **vs** inline-кнопки
|
||||
(`reply_markup` в `send_telegram`).
|
||||
2. **§8.4 — формат Plane-URL:** полный путь `.../projects/{project_id}/issues/{issue_id}/`
|
||||
**vs** короткий `.../browse/<IDENT>/`.
|
||||
3. **§8.3 — внешний web-URL Plane:** в конфиге есть только внутренний `plane_api_url`
|
||||
(`http://localhost:8091`), непригодный для браузерной ссылки.
|
||||
|
||||
Жёсткое ограничение контекста — **self-hosting**: правка живёт в инструменте, который сейчас
|
||||
обслуживает другие проекты из общего прод-контейнера. Любое расширение blast radius
|
||||
(особенно правка разделяемой функции `send_telegram`, которой пользуется и живой трекер
|
||||
PR #21/#22) — групповой риск. Поэтому из равноценных вариантов выбирается тот, что меняет
|
||||
меньше кода и не трогает общие точки.
|
||||
|
||||
Фактическое состояние кода, проверенное на ветке:
|
||||
- `send_telegram(text, disable_notification=False)` (`src/notifications.py:42`) шлёт
|
||||
`parse_mode="HTML"` — HTML-`<a>` работает без изменения сигнатуры.
|
||||
- Эталон branch-view ссылки на доки — `src/usage.py:455-458`:
|
||||
`base = (gitea_public_url or gitea_url).rstrip('/')`, `owner = gitea_owner`,
|
||||
URL `{base}/{owner}/{repo}/src/branch/{branch}/<rel>`.
|
||||
- Plane-issue uuid надёжно лежит в `tasks.plane_issue_id`; `project_id` берётся через
|
||||
`projects.get_project_by_repo(repo).plane_project_id`.
|
||||
- В `plane_sync.py` строки `.../workspaces/{slug}/projects/{pid}/issues/{id}/` — это **API**
|
||||
путь (`{plane_api_url}/api/v1/...`), НЕ браузерный. Браузерный роут Plane —
|
||||
`{web_base}/{workspace_slug}/projects/{project_id}/issues/{issue_id}` (без `/api/v1`,
|
||||
без сегмента `/workspaces/`).
|
||||
|
||||
## Решение
|
||||
|
||||
### Р-1 (§8.1) — HTML-ссылки в тексте. Inline-кнопки отклонены.
|
||||
Ссылки встраиваются как `<a href="…">подпись</a>` в текст того же одного сообщения.
|
||||
**`send_telegram` НЕ трогаем** (сигнатура без `reply_markup`). Inline-кнопки потребовали бы
|
||||
правки разделяемой функции, которой пользуется живой трекер, — это рост blast radius без
|
||||
бизнес-выгоды для одной точки уведомления. Расширение до кнопок — **вне объёма ORCH-017**;
|
||||
при реальной потребности заводится отдельный work item.
|
||||
|
||||
### Р-2 (§8.4) — полный путь Plane-issue по uuid. Короткий `browse/<IDENT>` отклонён.
|
||||
Формат:
|
||||
```
|
||||
{plane_web_base}/{workspace_slug}/projects/{project_id}/issues/{plane_issue_id}/
|
||||
```
|
||||
Источники: `plane_web_base` (Р-3), `workspace_slug = settings.plane_workspace_slug`,
|
||||
`project_id = get_project_by_repo(repo).plane_project_id`, `plane_issue_id = tasks.plane_issue_id`.
|
||||
Короткий `browse/<IDENT>` отклонён: он опирается на совпадение `work_item_id` с Plane-identifier,
|
||||
которое не гарантировано из-за zero-padding (`ORCH-017` в БД vs `ORCH-17` как identifier).
|
||||
uuid в `plane_issue_id` — детерминированный и уже в наличии источник.
|
||||
|
||||
### Р-3 (§8.3) — новая настройка `ORCH_PLANE_WEB_URL` + loopback-guard.
|
||||
В `src/config.py` добавляется `plane_web_url: str = ""` (env `ORCH_PLANE_WEB_URL`).
|
||||
База резолвится как:
|
||||
```python
|
||||
plane_web_base = (settings.plane_web_url or settings.plane_api_url).rstrip("/")
|
||||
```
|
||||
**Loopback-guard (разрешение конфликта AC-2 ↔ AC-3):** дефолт-фоллбэк `plane_api_url` равен
|
||||
`http://localhost:8091` и снаружи хоста не кликается. Поэтому: если итоговый `plane_web_base`
|
||||
указывает на loopback/локальный хост (`localhost`, `127.0.0.1`, `0.0.0.0`, `[::1]`) **или**
|
||||
пуст — **Plane-ссылка опускается целиком** (а не вставляется битой). Так одновременно:
|
||||
AC-2 (не выпускаем localhost-ссылку), AC-3 (цепочка фоллбэка соблюдена как попытка),
|
||||
AC-6/NFR-1 (никаких исключений, сообщение уходит без отсутствующей ссылки).
|
||||
|
||||
### Р-4 — graceful degradation как контракт построения ссылок.
|
||||
Чтение `repo/branch/plane_issue_id` из `tasks` — один SELECT в `try/except`. Каждая из двух
|
||||
ссылок строится независимо; при нехватке данных конкретная ссылка опускается, призыв
|
||||
«Переведите задачу в статус Approved …» и само сообщение сохраняются всегда. Динамические
|
||||
подписи — через `html.escape`; URL формируются только из доверенных конфиг/БД-значений.
|
||||
|
||||
### Р-5 — инвариант «одно сообщение, без дублей».
|
||||
Порядок действий в `notify_approve_requested` сохраняется: `mark_brd_review_started` →
|
||||
`update_task_tracker(task_id)` → один `send_telegram(msg)` (пингующий, не silent). Живой
|
||||
трекер не дублируется. Реестр `QG_CHECKS`, стадии, `:approved:`-handler,
|
||||
`check_analysis_approved` — без изменений (правка — отображение, не управление конвейером).
|
||||
|
||||
## Затронутые модули (для стадии development)
|
||||
| Модуль | Изменение |
|
||||
|--------|-----------|
|
||||
| `src/notifications.py` | `notify_approve_requested`: SELECT `repo/branch/plane_issue_id`; сборка двух ссылок (Р-2/Р-3/Р-4); встраивание в текст. |
|
||||
| `src/config.py` | `Settings.plane_web_url: str = ""` (env `ORCH_PLANE_WEB_URL`). |
|
||||
| `src/projects.py` | (чтение) `get_project_by_repo(repo).plane_project_id`. |
|
||||
| `src/usage.py` | (референс, НЕ править) паттерн branch-view URL. |
|
||||
| `.env.example`, `CHANGELOG.md`, env-карта (`CLAUDE.md`/`INFRA.md`) | документация в том же PR. |
|
||||
|
||||
Без изменений API и схемы БД. Все требуемые поля уже есть в `tasks`.
|
||||
|
||||
## Последствия
|
||||
**Плюсы:**
|
||||
- Минимальный blast radius: разделяемая `send_telegram` не тронута → нулевой риск для живого
|
||||
трекера и прочих уведомлений; безопасно для self-hosting.
|
||||
- Детерминированная Plane-ссылка (uuid), не зависит от zero-padding identifier.
|
||||
- Loopback-guard снимает противоречие AC-2/AC-3 и исключает «битые localhost-ссылки» в проде.
|
||||
- Деплой штатный: не требует рестарта прод-контейнера сверх обычного деплоя; деплой ORCH
|
||||
идёт через обязательный `deploy-staging` (8501).
|
||||
|
||||
**Минусы / ограничения:**
|
||||
- Нет inline-кнопок (по дизайну отклонено) — UX чуть менее «кнопочный»; при необходимости
|
||||
отдельный work item.
|
||||
- Plane-ссылка появится только после задания `ORCH_PLANE_WEB_URL` на хосте (`.env`/`.env.staging`)
|
||||
— см. `07-infra-requirements.md`. До этого момента graceful degradation: уведомление уходит
|
||||
только с BRD-ссылкой.
|
||||
- Корректность браузерного роута Plane (`/{workspace}/projects/{id}/issues/{id}/`) зависит от
|
||||
версии Plane; риск зафиксирован в `10-tech-risks.md`.
|
||||
|
||||
## Открытые вопросы, переданные дальше
|
||||
- **Значение `ORCH_PLANE_WEB_URL`** подтверждает Owner/INFRA при деплое (см. `07-infra-requirements.md`).
|
||||
Это конфиг-параметр, а не блокер архитектуры.
|
||||
@@ -1,38 +0,0 @@
|
||||
# 07-Infra Requirements — ORCH-017
|
||||
|
||||
Work Item: **ORCH-017** · Repo: `orchestrator`
|
||||
Опирается на ADR-001 (Р-3). Меняется только env-карта; топология контейнеров/портов — без изменений.
|
||||
|
||||
## 1. Новая env-переменная
|
||||
| Ключ | env | Дефолт | Назначение |
|
||||
|------|-----|--------|------------|
|
||||
| `plane_web_url` | `ORCH_PLANE_WEB_URL` | `""` (пусто) | Внешний **браузерный** базовый URL Plane для кликабельной ссылки на issue из Telegram. НЕ путать с внутренним `ORCH_PLANE_API_URL` (`http://localhost:8091`), который пригоден только для API. |
|
||||
|
||||
### Семантика резолва (ADR-001 Р-3)
|
||||
```
|
||||
plane_web_base = (ORCH_PLANE_WEB_URL or ORCH_PLANE_API_URL).rstrip("/")
|
||||
```
|
||||
- Если `plane_web_base` пуст **или** указывает на loopback (`localhost`, `127.0.0.1`,
|
||||
`0.0.0.0`, `[::1]`) — Plane-ссылка **опускается** (graceful degradation, NFR-1). Без
|
||||
заданного `ORCH_PLANE_WEB_URL` уведомление уходит только с BRD-ссылкой — это нормально.
|
||||
|
||||
## 2. Что требуется от Owner / INFRA
|
||||
1. **Подтвердить значение `ORCH_PLANE_WEB_URL`** — внешний адрес Plane UI (тот, по которому
|
||||
Слава открывает Plane в браузере). Это единственный внешний вход, требующий решения Owner.
|
||||
2. Прописать ключ в `.env` (prod-хост) и `.env.staging` (staging-песочница). В git значение
|
||||
НЕ коммитится — канон секретов/настроек (`.env.example` — образец без значения).
|
||||
3. Браузерный роут issue, который будет собран:
|
||||
`{ORCH_PLANE_WEB_URL}/{ORCH_PLANE_WORKSPACE_SLUG}/projects/{plane_project_id}/issues/{plane_issue_id}/`.
|
||||
Проверить на одной задаче, что он открывается в текущей версии Plane (см. риск R-3 в
|
||||
`10-tech-risks.md`).
|
||||
|
||||
## 3. Переиспользуемые (без изменений) настройки
|
||||
- `ORCH_GITEA_PUBLIC_URL` / `ORCH_GITEA_URL`, `ORCH_GITEA_OWNER` — для BRD-ссылки.
|
||||
- `ORCH_PLANE_WORKSPACE_SLUG` — workspace в Plane-URL.
|
||||
|
||||
## 4. Топология / деплой
|
||||
- Контейнеры, порты, сети — **без изменений**. Новый ключ читается из `.env` при старте
|
||||
(`pydantic Settings`, `env_prefix=ORCH_`).
|
||||
- Деплой self (ORCH) — штатный, через обязательный `deploy-staging` (8501) перед прод-деплоем
|
||||
(`orchestrator`, 8500). Рестарт прода сверх обычного деплоя НЕ требуется.
|
||||
- Документировать ключ в env-карте: `CLAUDE.md` и/или `docs/operations/INFRA.md` (в том же PR).
|
||||
@@ -1,19 +0,0 @@
|
||||
# 10-Tech Risks — ORCH-017
|
||||
|
||||
Work Item: **ORCH-017** · Repo: `orchestrator`
|
||||
Опирается на ADR-001. Шкала: вероятность × влияние.
|
||||
|
||||
| ID | Риск | Вер. | Влияние | Митигация |
|
||||
|----|------|------|---------|-----------|
|
||||
| R-1 | **Self-hosting: уведомление роняет поток.** Исключение при построении ссылок (нет данных в `tasks`, неконсистентный реестр проектов) прерывает `notify_approve_requested` и тормозит конвейер всех проектов. | Низк. | Выс. | NFR-1/ADR Р-4: один SELECT в `try/except`, каждая ссылка строится независимо и опускается при нехватке данных; сообщение и призыв отправляются всегда. Тест на ветви degradation (`tests/test_notify_approve_links.py`). |
|
||||
| R-2 | **Битый/непубличный Plane-URL.** Фоллбэк на `plane_api_url=localhost:8091` дал бы некликабельную ссылку снаружи хоста (нарушение AC-2). | Сред. | Сред. | ADR Р-3 loopback-guard: при пустом/loopback базовом URL Plane-ссылка опускается, а не вставляется битой. Значение `ORCH_PLANE_WEB_URL` подтверждает Owner/INFRA (`07-infra-requirements.md`). |
|
||||
| R-3 | **Несовпадение браузерного роута Plane.** Формат `/{workspace}/projects/{id}/issues/{id}/` зависит от версии Plane; иной роут → ссылка ведёт в никуда (открывается, но не на ту issue). | Низк. | Сред. | Проверить роут на одной реальной задаче после задания `ORCH_PLANE_WEB_URL` (acceptance в staging). uuid `plane_issue_id` детерминирован — ошибка может быть только в шаблоне пути, не в идентификаторе. |
|
||||
| R-4 | **Поломка HTML-разметки сообщения.** Неэкранированная динамическая подпись (напр. символы `<`/`&` в `work_item_id`/title) ломает `parse_mode="HTML"` → Telegram отвергает сообщение. | Низк. | Сред. | NFR-3/ADR Р-4: `html.escape` на всех подписях; URL только из доверенных конфиг/БД-значений. Тест на спецсимволы. |
|
||||
| R-5 | **Регрессия «дубль-сообщения».** Случайное добавление второго `send_telegram` или повторная отправка трекера как нового сообщения. | Низк. | Низк. | ADR Р-5: инвариант «один `send_telegram`», порядок действий зафиксирован; регресс-тесты `tests/test_telegram_tracker.py`, `tests/test_notify_done_regression.py`. |
|
||||
| R-6 | **Zero-padding identifier.** Короткий `browse/<IDENT>` промахнулся бы по issue (`ORCH-017` vs `ORCH-17`). | — | — | Снят на корню: ADR Р-2 использует uuid `plane_issue_id`, короткий формат отклонён. |
|
||||
|
||||
## Сводно
|
||||
Изменение косметическое и изолированное: нет правок реестра гейтов/стадий, схемы БД, API и
|
||||
разделяемой `send_telegram`. Главный класс риска — self-hosting-устойчивость (R-1) — закрыт
|
||||
graceful-degradation контрактом ADR Р-4. Внешний незакрытый вход — значение `ORCH_PLANE_WEB_URL`
|
||||
(R-2/R-3), проверяется в staging до прод-деплоя.
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-017
|
||||
verdict: REQUEST_CHANGES
|
||||
version: 4
|
||||
---
|
||||
|
||||
# Review ORCH-017
|
||||
|
||||
## Summary
|
||||
Основная фича (прямые BRD-/Plane-ссылки в `notify_approve_requested`) реализована
|
||||
качественно и соответствует ТЗ, ADR-001 и всем критериям приёмки (подтверждено в
|
||||
review v2: изменения по фиче — только `src/config.py` и `src/notifications.py`).
|
||||
|
||||
P0 из review v3 (правка разделяемого гейта `check_tests_passed` коммитом `e62d51a`,
|
||||
нарушавшая ADR-001 Р-5 и ТЗ §7) **снят**: коммит `d615747` откатил изменение
|
||||
`src/qg/checks.py` (вынесено в отдельный work item ORCH-47 со своим ADR). Код гейта
|
||||
теперь идентичен `main` (читает только `verdict:`/`status:`); ADR-001 Р-5 и ТЗ §7
|
||||
снова консистентны с кодом. ✔
|
||||
|
||||
Однако откат кода **не сопровождён откатом документации**: `CHANGELOG.md` и
|
||||
`docs/architecture/README.md` всё ещё описывают откаченную правку гейта и ссылаются
|
||||
на не существующие в этом PR тесты `tests/test_qg.py`. Это новый doc↔code конфликт
|
||||
(golden source). → REQUEST_CHANGES (P1).
|
||||
|
||||
## Соответствие ТЗ
|
||||
- §3.1–§3.2, §4–§6 (фича уведомления) — выполнено. `_build_brd_link` /
|
||||
`_build_plane_issue_link` строят ссылки независимо, встроены в текст одного
|
||||
сообщения; призыв «Переведите задачу в статус Approved …» сохранён;
|
||||
`html.escape` на динамике; порядок `mark_brd_review_started → update_task_tracker
|
||||
→ send_telegram(msg)` соблюдён; `Settings.plane_web_url` + фолбэк добавлены. ✔
|
||||
- §7 — соблюдено. Реестр `QG_CHECKS`, стадии и машинные вердикты в коде не меняются
|
||||
(правка гейта откачена в `d615747`). ✔
|
||||
|
||||
## Соответствие ADR
|
||||
- ADR-001 (Р-1…Р-5) — соблюдён. Ссылки HTML-`<a>` в тексте, `send_telegram` не
|
||||
тронута; полный Plane-URL по uuid; `ORCH_PLANE_WEB_URL` + loopback-guard
|
||||
(`_is_loopback_base`); graceful degradation; «одно сообщение, без дублей». ✔
|
||||
- ADR-001 Р-5 vs код — конфликт снят откатом гейта. ✔
|
||||
|
||||
## Качество кода
|
||||
Фича `notifications.py`/`config.py` — без замечаний. Чтение полей задачи
|
||||
(`_get_task_link_fields`) и обе сборки ссылок защищены try/except и никогда не
|
||||
роняют alert (AC-6); loopback-guard корректно опускает некликабельный Plane-URL
|
||||
(AC-2/AC-3); `html.escape(..., quote=True)` на href и `html.escape(work_item_id)`
|
||||
на подписи (AC-7). Тесты `tests/test_notify_approve_links.py`,
|
||||
`tests/test_analysis_approve_flow_links.py` присутствуют и содержательны.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- [ ] **Документация описывает откаченный код (doc↔code конфликт).** После
|
||||
revert-коммита `d615747` код `src/qg/checks.py` НЕ читает `result:` (только
|
||||
`verdict:`/`status:`), но документация осталась от состояния `e62d51a`:
|
||||
- `docs/architecture/README.md:61` утверждает, что `check_tests_passed`
|
||||
читает `verdict:`/`status:`/`result:` — это ложно для текущего кода и
|
||||
вводит в заблуждение по поведению разделяемого прод-гейта (self-hosting:
|
||||
tester, написавший только `result: PASS`, реально провалит гейт).
|
||||
- `CHANGELOG.md:24` (секция Fixed) содержит запись о правке гейта
|
||||
`check_tests_passed` под тегом ORCH-017 и ссылается на отсутствующие в PR
|
||||
тесты `tests/test_qg.py::TestCheckTestsPassed::test_result_pass_only_passes`
|
||||
/ `…::test_result_fail_only_fails`.
|
||||
**Резолюция:** убрать из ORCH-017 PR обе записи (откатить README:61 к
|
||||
формулировке `main` и удалить CHANGELOG-entry про гейт) — правка гейта
|
||||
принадлежит ORCH-47 и должна документироваться там вместе с её кодом.
|
||||
|
||||
### P2 — Should fix
|
||||
- [ ] `13-test-report.md` (`result: PASS`) относится к прогону, включавшему
|
||||
откаченную правку гейта; после устранения P1 канонический ре-тест — на
|
||||
стадии testing (отчёт не должен ссылаться на снятые из PR изменения).
|
||||
|
||||
## Документация
|
||||
Правило «изменён `src/` → обновлена документация в том же PR» по фиче уведомления —
|
||||
выполнено: `CHANGELOG.md` (Added), `.env.example` (`ORCH_PLANE_WEB_URL`),
|
||||
`docs/operations/INFRA.md` (env-карта), ADR-001. ✔
|
||||
|
||||
Неконсистентность (P1): документация про откаченную правку гейта `check_tests_passed`
|
||||
осталась в `CHANGELOG.md` (Fixed) и `docs/architecture/README.md`, хотя
|
||||
соответствующий код отозван (`d615747`) и перенесён в ORCH-47. Доку нужно привести в
|
||||
соответствие с кодом этого PR.
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-017
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-017
|
||||
|
||||
Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве BRD.
|
||||
Вердикт review (`12-review.md`): **APPROVED** ✔ — прогон регресса допущен.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3 (pytest-asyncio 0.23.8, anyio 4.13.0)
|
||||
- Дата: 2026-06-05
|
||||
- Ветка: `feature/ORCH-017-brd-plane-telegram`
|
||||
- Прод-контейнер `orchestrator` (8500) НЕ перезапускался; smoke — только read-only GET.
|
||||
|
||||
## Smoke test API (prod, read-only)
|
||||
| Endpoint | HTTP | Результат |
|
||||
|----------|------|-----------|
|
||||
| `GET /health` | 200 | `{"status":"ok","service":"orchestrator"}` — PASS |
|
||||
| `GET /status` | 200 | active_tasks содержит task #35 ORCH-017 (stage=testing) — PASS |
|
||||
| `GET /queue` | 200 | counts running=1, failed=0, breaker=closed, preflight ok — PASS |
|
||||
|
||||
> `curl` в окружении отсутствует — smoke выполнен через `urllib.request` (GET, без побочных эффектов).
|
||||
|
||||
## Результаты по test-plan (04-test-plan.yaml)
|
||||
|
||||
| TC ID | Описание | Тест | Результат |
|
||||
|-------|----------|------|-----------|
|
||||
| TC-01 | BRD-ссылка на `01-brd.md` (Gitea branch-view) | `test_notify_approve_links::test_tc01_brd_link_present` | PASS |
|
||||
| TC-02 | Plane-ссылка (web-URL+workspace+project+issue_id) | `…::test_tc02_plane_link_present` | PASS |
|
||||
| TC-03 | Фоллбэки URL (gitea_public_url→gitea_url, plane_web_url→plane_api_url) | `…::test_tc03_url_fallbacks` | PASS |
|
||||
| TC-04 | Сохранён призыв «Approved» | `…::test_tc04_keeps_approved_call_to_action` | PASS |
|
||||
| TC-05 | Ровно одно пингующее сообщение (не silent) | `…::test_tc05_single_notifying_message` | PASS |
|
||||
| TC-06 | Graceful: branch/issue=None — без исключения | `…::test_tc06_graceful_missing_branch_and_issue` | PASS |
|
||||
| TC-07 | Пустой Plane-base → Plane-ссылка опущена, BRD остаётся | `…::test_tc07_plane_base_empty_drops_plane_link_keeps_brd` | PASS |
|
||||
| TC-07b | Loopback Plane-base отбрасывается (доп.) | `…::test_tc07b_loopback_plane_base_dropped` | PASS |
|
||||
| TC-08 | parse_mode=HTML, html.escape, валидная разметка | `…::test_tc08_html_escaped_and_valid_markup` | PASS |
|
||||
| TC-08b | send_telegram сохраняет parse_mode=HTML (доп.) | `…::test_tc08b_send_telegram_keeps_parse_mode_html` | PASS |
|
||||
| TC-09 | Регрессия трекера (silent edit, без дублей) | `test_telegram_tracker.py` (полный набор) | PASS |
|
||||
| TC-10 | Поток analysis-approved строит ссылки из БД | `test_analysis_approve_flow_links::test_tc10_approved_flow_builds_links_from_db` | PASS |
|
||||
| TC-11 | (Условный) inline-кнопки | — | N/A — вариант кнопок отклонён (ADR-001 Р-1) |
|
||||
| TC-12 | (Условный) обратная совместимость send_telegram c reply_markup | — | N/A — вариант кнопок отклонён (ADR-001 Р-1) |
|
||||
|
||||
Все запланированные тесты (TC-01…TC-10) — PASS. Условные TC-11/TC-12 не применимы:
|
||||
ADR-001 (Р-1) зафиксировал HTML-ссылки в тексте без изменения сигнатуры `send_telegram`.
|
||||
|
||||
## Покрытие критериев приёмки (03-acceptance-criteria.md)
|
||||
| AC | Покрывающие TC | Статус |
|
||||
|----|----------------|--------|
|
||||
| AC-1 | TC-01, TC-10 | PASS |
|
||||
| AC-2 | TC-02, TC-10 | PASS |
|
||||
| AC-3 | TC-01, TC-02, TC-03 | PASS |
|
||||
| AC-4 | TC-04 | PASS |
|
||||
| AC-5 | TC-05, TC-09 | PASS |
|
||||
| AC-6 | TC-06, TC-07, TC-07b | PASS |
|
||||
| AC-7 | TC-08, TC-08b | PASS |
|
||||
| AC-8 | TC-09, TC-10 | PASS |
|
||||
| AC-9 | проверено review (CHANGELOG/.env.example/INFRA.md/ADR) | PASS |
|
||||
| AC-10 | полный регресс `pytest tests/` | PASS |
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
### Целевые тесты ORCH-017
|
||||
```
|
||||
tests/test_notify_approve_links.py::test_tc01_brd_link_present PASSED
|
||||
tests/test_notify_approve_links.py::test_tc02_plane_link_present PASSED
|
||||
tests/test_notify_approve_links.py::test_tc03_url_fallbacks PASSED
|
||||
tests/test_notify_approve_links.py::test_tc04_keeps_approved_call_to_action PASSED
|
||||
tests/test_notify_approve_links.py::test_tc05_single_notifying_message PASSED
|
||||
tests/test_notify_approve_links.py::test_tc06_graceful_missing_branch_and_issue PASSED
|
||||
tests/test_notify_approve_links.py::test_tc07_plane_base_empty_drops_plane_link_keeps_brd PASSED
|
||||
tests/test_notify_approve_links.py::test_tc07b_loopback_plane_base_dropped PASSED
|
||||
tests/test_notify_approve_links.py::test_tc08_html_escaped_and_valid_markup PASSED
|
||||
tests/test_notify_approve_links.py::test_tc08b_send_telegram_keeps_parse_mode_html PASSED
|
||||
tests/test_analysis_approve_flow_links.py::test_tc10_approved_flow_builds_links_from_db PASSED
|
||||
11 passed in 0.53s
|
||||
```
|
||||
|
||||
### Полный регресс
|
||||
```
|
||||
======================== 434 passed, 1 warning in 7.99s ========================
|
||||
```
|
||||
Единственное предупреждение — PydanticDeprecatedSince20 (`src/config.py:4`, class-based config),
|
||||
предсуществующее, к ORCH-017 не относится, на результат не влияет.
|
||||
|
||||
## Итог
|
||||
**PASS** — 434/434 теста зелёные, целевые TC-01…TC-10 пройдены, все 10 критериев приёмки
|
||||
покрыты, smoke API прод-инстанса OK. Задача готова к стадии **deploy-staging**.
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Агенты пишут файлы под root в смонтированный хост-репо: ломает git/ребилд
|
||||
|
||||
Work Item ID: ORCH-040
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,106 +0,0 @@
|
||||
# 01 — BRD: Агенты пишут файлы под root в смонтированный хост-репо
|
||||
|
||||
Work Item: **ORCH-040**
|
||||
Тип: инфра-фикс (runtime / docker-compose)
|
||||
Исполнение: через Dev напрямую (по решению Owner)
|
||||
|
||||
## 1. Бизнес-контекст и проблема
|
||||
|
||||
Контейнер `orchestrator` (prod, 8500) работает под `uid=0 (root)`. Он монтирует
|
||||
хостовый каталог `/home/slin/repos` → `/repos` (rw). Claude-CLI агенты запускаются
|
||||
через `subprocess.Popen` **внутри контейнера**, то есть тоже под root. Они пишут:
|
||||
|
||||
- в git worktree задач — `/repos/_wt/<repo>/<branch>/...`;
|
||||
- в прод-клон — `/repos/<repo>/docs/work-items/...` (через коммит/пуш из worktree).
|
||||
|
||||
В результате на **хосте** файлы создаются с владельцем `root:root`.
|
||||
|
||||
### Симптом
|
||||
При ребилде/деплое прода `git pull` / `git reset` под пользователем `slin` падает:
|
||||
|
||||
```
|
||||
error: insufficient permission for adding an object to repository database .git/objects
|
||||
Permission denied (на docs/work-items/ORCH-016, владелец root:root)
|
||||
```
|
||||
|
||||
Каждый будущий деплой будет ломаться, пока вручную не выполнить `chown`.
|
||||
|
||||
### Диагноз (живая разведка 05–06.06)
|
||||
- `docker exec orchestrator id` → `uid=0(root) gid=0(root) groups=0,999`.
|
||||
- Хост `slin` = `uid=1000 gid=1000`, группы: `sudo`, `docker(999)`.
|
||||
- `/home/slin/repos` → `/repos` (rw); на хосте `/repos` уже `1000:1000 rwxrwxr-x`.
|
||||
- `docs/work-items/*` на хосте — `root:root` (наследие прошлых прогонов).
|
||||
|
||||
## 2. Цель
|
||||
|
||||
Агенты конвейера **не должны** создавать `root`-файлы в хостовом репозитории.
|
||||
После любого прогона конвейера `git pull/status/reset` под `slin` на хосте
|
||||
работает **без ручного chown**.
|
||||
|
||||
## 3. Объём (scope)
|
||||
|
||||
В объёме:
|
||||
- Изменение runtime-режима контейнера так, чтобы артефакты создавались под
|
||||
`uid:gid` хоста (`1000:1000`).
|
||||
- Сохранение работоспособности: claude-auth (preflight), git/ssh, docker.sock
|
||||
(деплой), запуск конвейера.
|
||||
- Обновление документации (INFRA.md, CHANGELOG, ADR с обоснованием варианта).
|
||||
- Проверка на staging (8501) ДО прода.
|
||||
|
||||
Вне объёма:
|
||||
- Массовое исправление прав уже существующих `root:root` файлов в истории
|
||||
(разовый `chown` на хосте делает Owner; в задаче — только описать команду).
|
||||
- Изменение логики конвейера, QG, схемы БД.
|
||||
- Смена модели/effort агентов, прочие фичи.
|
||||
|
||||
## 4. Заинтересованные стороны
|
||||
- Owner (Слава) — заказчик, владелец хоста mva154.
|
||||
- Стрим — разведка/контекст.
|
||||
- Проект enduro-trails — co-tenant того же прод-инстанса (групповой риск).
|
||||
|
||||
## 5. Ограничения и риски (off-limits)
|
||||
|
||||
Self-hosting: прод-инстанс `orchestrator` ОДИН на все прод-проекты, общая БД и
|
||||
очередь. **Нельзя ломать**: запуск конвейера, доступ к Plane/Gitea/SSH из агентов,
|
||||
docker.sock. Любой рестарт контейнера под новым uid — **только в окно тишины**
|
||||
(нет активных задач). Тестировать на staging ПЕРЕД продом.
|
||||
|
||||
### Известные мины (подтверждены разведкой)
|
||||
- **МИНА 1 — docker.sock**: `/var/run/docker.sock` = `srw-rw---- root:999`.
|
||||
Доступ идёт через gid 999, не через root. При переходе на непривилегированный
|
||||
uid обязателен supplementary group `999`. *В текущем `docker-compose.yml` уже
|
||||
есть `group_add: ["999"]` для обоих сервисов — учесть, не сломать.*
|
||||
- **МИНА 2 — claude creds (БЛОКЕР)**: `/home/slin/.claude/.credentials.json` =
|
||||
`root:root 0600`. Сейчас читает контейнер-root. Под `uid=1000` без доступа →
|
||||
`claude-auth` ломается → весь конвейер умирает (preflight ORCH-044 заворачивает).
|
||||
Проверить ПЕРВЫМ.
|
||||
- **МИНА 3 — claude бинарь**: реальный бинарь `/opt/claude-code/bin/claude.exe`
|
||||
(root:root, `+x` для всех — ok). `ORCH_CLAUDE_BIN=/usr/bin/claude` в env не
|
||||
существует; launcher использует hardcode `CLAUDE_BIN=/opt/claude-code/bin/claude.exe`.
|
||||
Под uid 1000 исполним, но проверить запуск.
|
||||
- **SSH-маунт**: `/home/slin/.orchestrator-ssh` → `/root/.ssh:ro`. При смене uid
|
||||
HOME/домашний каталог меняется — путь к ключам нужно поправить (деплой по ssh).
|
||||
- **HOME**: launcher форсит `HOME=/home/slin` (две точки: env Popen и git_env).
|
||||
Креды читаются из `/home/slin/.claude`. Учесть при смене uid.
|
||||
|
||||
## 6. Бизнес-ценность
|
||||
Устранение постоянного ручного `chown` после каждого деплоя; деплой прода
|
||||
перестаёт ломаться на правах; снимается источник простоя конвейера всех проектов.
|
||||
|
||||
## 7. Допущения
|
||||
- Хост-каталоги `/app/data` и `/repos` уже `1000:1000` (запись под uid 1000 пройдёт).
|
||||
- Dockerfile уже содержит `git config --system --add safe.directory '*'`.
|
||||
- Окно тишины для рестарта контейнера согласуется с Owner.
|
||||
|
||||
## 8. Host-prerequisites (предусловия на стороне Owner)
|
||||
Часть фикса невозможно закрыть только кодом — есть действия на хосте mva154,
|
||||
которые выполняет Owner (в гит не коммитятся, фиксируются в ADR/INFRA). Это
|
||||
обязательные предусловия Варианта 1; без них переход на uid 1000 ломает конвейер:
|
||||
- **P-1 (блокер, МИНА 2):** обеспечить чтение `/home/slin/.claude/.credentials.json`
|
||||
под uid 1000 (рекомендация — `chown -R 1000:1000 /home/slin/.claude`). Способ
|
||||
выбирает ADR; анализ фиксирует факт предусловия.
|
||||
- **P-2:** ssh-ключи (`/home/slin/.orchestrator-ssh`) читаемы uid 1000.
|
||||
- **P-3:** подтверждение `slin = uid 1000 gid 1000` (подтверждено разведкой).
|
||||
- **P-4:** рестарт прод-self только в окно тишины (`GET /status` без активных задач).
|
||||
|
||||
Детализация и команды — в `02-trz.md` §10.
|
||||
@@ -1,112 +0,0 @@
|
||||
# 02 — ТЗ: agent-файлы под uid хоста (не root)
|
||||
|
||||
Work Item: **ORCH-040**
|
||||
|
||||
## 1. Суть требования
|
||||
Артефакты конвейера (worktree + docs) должны создаваться на хосте под
|
||||
`uid:gid = 1000:1000` (slin), а не `root:root`. При этом сохраняется работа
|
||||
claude-auth, git, ssh-деплоя и docker.sock.
|
||||
|
||||
## 2. Задействованные модули и файлы
|
||||
|
||||
| Файл | Роль в задаче |
|
||||
|------|----------------|
|
||||
| `docker-compose.yml` | runtime-режим контейнера (prod `orchestrator` + `orchestrator-staging`). Основная точка изменения. |
|
||||
| `Dockerfile` | возможные правки под непривилегированный запуск (safe.directory уже есть; при необходимости — создание пользователя/прав). |
|
||||
| `src/agents/launcher.py` | `HOME=/home/slin` хардкод (env Popen ~стр.326 и git_env ~стр.513); путь `CLAUDE_BIN` (стр.187). Проверить совместимость при смене uid; править ТОЛЬКО при необходимости. |
|
||||
| `docs/operations/INFRA.md` | блок «Тома (volumes)» (SSH-маунт `/root/.ssh`), карта рантайма — обновить. |
|
||||
| `CHANGELOG.md` | запись об изменении. |
|
||||
| `docs/work-items/ORCH-040/06-adr/` | ADR с выбором варианта + обоснованием (создаёт архитектор). |
|
||||
|
||||
## 3. Варианты решения (вход для ADR — выбор и обоснование за архитектором)
|
||||
|
||||
> Анализ фиксирует варианты как требование «выбрать и обосновать в ADR».
|
||||
> Рекомендация разведки — Вариант 1.
|
||||
|
||||
1. **Вариант 1 (рекомендован): `user: "1000:1000"` в docker-compose.**
|
||||
Все файлы сразу `slin:slin`, git на хосте без chown. Обязательные довески:
|
||||
- сохранить/проверить `group_add: ["999"]` (docker.sock) — **уже присутствует**;
|
||||
- обеспечить доступ uid 1000 к claude creds (`/home/slin/.claude/.credentials.json`):
|
||||
`chown 1000:1000` на хосте ИЛИ права на чтение для 1000 (задокументировать);
|
||||
- поправить SSH-маунт: `/home/slin/.orchestrator-ssh` → домашний каталог uid 1000
|
||||
(`/home/slin/.ssh`), а не `/root/.ssh`; согласовать с `HOME` в launcher;
|
||||
- проверить запуск `claude.exe` + `git` + `ssh` под uid 1000.
|
||||
|
||||
2. **Вариант 2: subprocess агента под непривилегированным uid внутри контейнера**
|
||||
(`Popen preexec_fn setuid` / `gosu`). Точечно, но сложнее; контейнер остаётся root.
|
||||
|
||||
3. **Вариант 3 (fallback, костыль): chown-хук нормализации прав после стадии**
|
||||
(`chown -R 1000:1000` worktree/доки). Лечит симптом, не корень. Применять, только
|
||||
если В1 неустранимо рвёт creds/sock.
|
||||
|
||||
## 4. Требуемые изменения (при выбранном Варианте 1)
|
||||
|
||||
### 4.1 docker-compose.yml (оба сервиса: `orchestrator`, `orchestrator-staging`)
|
||||
- Добавить `user: "1000:1000"`.
|
||||
- Сохранить `group_add: ["999"]` (НЕ удалять).
|
||||
- Изменить SSH-маунт: target `/root/.ssh` → каталог `.ssh` пользователя 1000,
|
||||
синхронно с `HOME`, который форсит launcher (`/home/slin`). То есть привести к
|
||||
единому HOME: маунт `/home/slin/.orchestrator-ssh` → `/home/slin/.ssh:ro`.
|
||||
- Маунт `/home/slin/.claude` и `.claude.json` — оставить; проверить доступ uid 1000.
|
||||
|
||||
### 4.2 Доступ к claude creds
|
||||
- Обеспечить, что `/home/slin/.claude/.credentials.json` читается uid 1000
|
||||
(на хосте — операция Owner; в ТЗ зафиксировать команду и проверку).
|
||||
|
||||
### 4.3 src/agents/launcher.py
|
||||
- Проверить, что `HOME=/home/slin` остаётся валиден под uid 1000 (домашний каталог
|
||||
существует и доступен). Менять ТОЛЬКО при доказанной необходимости.
|
||||
- Не менять CLAUDE_BIN, если запуск под 1000 подтверждён.
|
||||
|
||||
### 4.4 Dockerfile
|
||||
- Менять при необходимости (например, гарантировать существование `/home/slin` и
|
||||
права). `git config --system --add safe.directory '*'` уже есть — оставить.
|
||||
|
||||
## 5. Изменения API
|
||||
Нет.
|
||||
|
||||
## 6. Изменения схемы БД
|
||||
Нет.
|
||||
|
||||
## 7. Новые QG checks
|
||||
Нет. Существующий staging-гейт (`check_staging_status`, ORCH-35) — обязательная
|
||||
страховка перед прод-деплоем self (без изменений).
|
||||
|
||||
## 8. Артефакты pipeline, которые должны быть созданы/обновлены
|
||||
- `06-adr/ADR-NNN-<slug>.md` — выбор варианта + обоснование (мины 1–3, SSH, HOME).
|
||||
- `docs/operations/INFRA.md` — обновить блок volumes (SSH target) и, при изменении
|
||||
режима, упоминание uid рантайма.
|
||||
- `CHANGELOG.md` — запись `fix:`/`refactor:` по Conventional Commits.
|
||||
- `12-review.md`, `13-test-report.md`, `15-staging-log.md` — по ходу конвейера.
|
||||
|
||||
## 9. Порядок безопасного внедрения (требование)
|
||||
1. Живая разведка прав creds/sock/ssh ДО кода.
|
||||
2. Применить и проверить на **staging (8501)** end-to-end.
|
||||
3. Прод-рестарт контейнера под новым uid — только в окно тишины (нет активных задач).
|
||||
4. Регресс на хосте: новые tracked-артефакты `1000:1000`, `git pull` под slin без ошибок.
|
||||
|
||||
## 10. Зависимости и host-prerequisites (действия на хосте, вне кода)
|
||||
|
||||
Эти пункты — предусловия для Варианта 1; их выполняет Owner на хосте mva154 (в гит
|
||||
не коммитятся, но фиксируются в ADR/INFRA как обязательная процедура). Без них
|
||||
переход контейнера на uid 1000 ломает конвейер (МИНА 2 — блокер).
|
||||
|
||||
| # | Предусловие | Команда / проверка | Зачем |
|
||||
|---|-------------|--------------------|-------|
|
||||
| P-1 | Доступ uid 1000 к claude creds | `chown -R 1000:1000 /home/slin/.claude` (вкл. `.credentials.json`); проверка `sudo -u '#1000' test -r /home/slin/.claude/.credentials.json` | МИНА 2: без доступа preflight ORCH-044 завернёт весь конвейер |
|
||||
| P-2 | SSH-ключи в HOME нового uid и читаемы | ключи в `/home/slin/.orchestrator-ssh` читаемы uid 1000; маунт ведёт в `/home/slin/.ssh` (см. §4.1) | деплой по ssh (DEPLOY_SSH_*) |
|
||||
| P-3 | Подтверждение uid:gid рантайма | `id slin` → `uid=1000 gid=1000`; `/repos` и `/app/data` уже `1000:1000` (подтверждено разведкой) | целевые файлы создаются под slin |
|
||||
| P-4 | Окно тишины для рестарта self | `GET /status` → нет активных задач перед рестартом прод-контейнера | self-hosting: общий инстанс с enduro-trails |
|
||||
|
||||
> **Открытый выбор для ADR (не решается анализом):** способ обеспечения P-1 —
|
||||
> `chown` creds (рекомендация разведки) vs. ослабление read-прав vs. отказ от
|
||||
> Варианта 1 в пользу Варианта 3 (chown-хук). Анализ фиксирует P-1 как
|
||||
> обязательное предусловие при любом из вариантов 1/2; для Варианта 3 — неактуально.
|
||||
|
||||
## 11. Подтверждённые факты текущего рантайма (anchor для Dev)
|
||||
Сверено с веткой `feature/ORCH-040-root-git` на 06.06:
|
||||
- `docker-compose.yml`: оба сервиса имеют `group_add: ["999"]` (МИНА 1 — НЕ удалять);
|
||||
SSH-маунт обоих = `/home/slin/.orchestrator-ssh:/root/.ssh:ro` (требует правки target);
|
||||
claude-маунты = `/home/slin/.claude` и `/home/slin/.claude.json:ro`.
|
||||
- `src/agents/launcher.py`: `HOME="/home/slin"` форсится в env Popen (стр. 326) и в
|
||||
git_env (стр. 513); `CLAUDE_BIN="/opt/claude-code/bin/claude.exe"` (стр. 187).
|
||||
@@ -1,62 +0,0 @@
|
||||
# 03 — Критерии приёмки: ORCH-040
|
||||
|
||||
Work Item: **ORCH-040**
|
||||
|
||||
Каждый критерий имеет чёткое условие PASS/FAIL. Задача считается принятой, когда
|
||||
**все** критерии = PASS.
|
||||
|
||||
## AC-1 — Артефакты создаются под uid хоста (корневой критерий)
|
||||
- **PASS**: после прогона тестовой задачи конвейером end-to-end новые tracked-файлы
|
||||
в `/home/slin/repos/orchestrator/docs/work-items/*` и в worktree
|
||||
(`/repos/_wt/...`) имеют владельца `slin:slin` (1000:1000).
|
||||
`ls -ld /home/slin/repos/orchestrator/docs/work-items/*` → НЕ `root:root`.
|
||||
- **FAIL**: появляются новые `root:root` tracked-файлы.
|
||||
|
||||
## AC-2 — git под slin работает без ручного chown
|
||||
- **PASS**: на хосте под `slin` `git -C /home/slin/repos/orchestrator pull`,
|
||||
`git status`, `git reset` выполняются без `Permission denied` /
|
||||
`insufficient permission for adding an object`.
|
||||
- **FAIL**: любая из команд падает на правах.
|
||||
|
||||
## AC-3 — claude-агенты стартуют (preflight ok)
|
||||
- **PASS**: `claude-auth`/preflight проходит; агент конвейера запускается и
|
||||
завершается `exit_code=0` (не `Not logged in`, не отказ доступа к creds).
|
||||
- **FAIL**: агент падает на авторизации/чтении `/home/slin/.claude`.
|
||||
|
||||
## AC-4 — docker.sock доступен (деплой не сломан)
|
||||
- **PASS**: из контейнера под новым uid `docker ps` / docker-операции деплоя
|
||||
(ORCH-36 путь) работают — доступ через gid 999 сохранён (`group_add: ["999"]`).
|
||||
- **FAIL**: docker-операции отваливаются (`permission denied` на сокете).
|
||||
|
||||
## AC-5 — SSH-деплой работает
|
||||
- **PASS**: ssh-ключи читаются из домашнего каталога нового uid; деплой-хук по ssh
|
||||
(`DEPLOY_SSH_*`) выполняется.
|
||||
- **FAIL**: ssh не находит/не читает ключи (маунт указывает на чужой HOME).
|
||||
|
||||
## AC-6 — Конвейер не сломан (без регресса)
|
||||
- **PASS**: тестовая задача проходит стадии без падения запуска конвейера; доступ к
|
||||
Plane/Gitea из агентов сохранён; `pytest tests/ -q` зелёный.
|
||||
- **FAIL**: конвейер встаёт / тесты падают.
|
||||
|
||||
## AC-7 — Проверено на staging ДО прода
|
||||
- **PASS**: изменение прогнано на staging (8501), `15-staging-log.md` →
|
||||
`staging_status:` положительный; прод-рестарт выполнен в окно тишины.
|
||||
- **FAIL**: изменение применено сразу на прод без staging-прогона.
|
||||
|
||||
## AC-8 — Документация обновлена (golden source)
|
||||
- **PASS**: `docs/operations/INFRA.md` (блок volumes / SSH target / uid рантайма)
|
||||
и `CHANGELOG.md` обновлены; ADR с выбором варианта и обоснованием создан в
|
||||
`06-adr/`. Reviewer подтверждает.
|
||||
- **FAIL**: код изменён, документация/ADR не обновлены.
|
||||
|
||||
## AC-9 — Прод-контейнер не уронен вне окна тишины
|
||||
- **PASS**: рестарт self выполнен без активных задач; конвейер enduro-trails не
|
||||
пострадал.
|
||||
- **FAIL**: рестарт во время активных задач / падение прод-инстанса.
|
||||
|
||||
## AC-10 — Host-prerequisites зафиксированы и выполнены
|
||||
- **PASS**: предусловия P-1…P-4 (TRZ §10 / BRD §8) описаны в ADR/INFRA как
|
||||
обязательная процедура Owner; P-1 (доступ uid 1000 к claude creds) фактически
|
||||
обеспечен — подтверждается прохождением AC-3.
|
||||
- **FAIL**: фикс применён без обеспечения доступа к creds (P-1) → preflight/конвейер
|
||||
падает; либо предусловия нигде не задокументированы.
|
||||
@@ -1,81 +0,0 @@
|
||||
work_item: ORCH-040
|
||||
description: >
|
||||
Инфра-фикс: контейнер/агенты не плодят root-файлы в хостовом репо.
|
||||
Часть проверок автоматизируема через pytest (валидация compose-конфига),
|
||||
часть — обязательные ops/integration проверки на staging и хосте (manual),
|
||||
т.к. касаются прав файловой системы хоста и рантайма docker.
|
||||
|
||||
tests:
|
||||
# --- Автоматизируемые (pytest, парсинг docker-compose.yml) ---
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: >
|
||||
docker-compose.yml: оба сервиса (orchestrator, orchestrator-staging)
|
||||
имеют user: "1000:1000" (при выборе Варианта 1).
|
||||
module: tests/test_orch040_compose.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: >
|
||||
docker-compose.yml: оба сервиса сохраняют group_add со значением "999"
|
||||
(доступ к docker.sock не потерян — МИНА 1).
|
||||
module: tests/test_orch040_compose.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: >
|
||||
docker-compose.yml: SSH-маунт согласован с HOME агента — target каталога
|
||||
.ssh лежит под /home/slin (а не /root/.ssh), для обоих сервисов.
|
||||
module: tests/test_orch040_compose.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: >
|
||||
launcher: HOME, форсимый в окружении агента и git_env, указывает на каталог,
|
||||
совместимый с SSH/claude-маунтами (/home/slin) — нет рассинхрона HOME vs uid.
|
||||
module: tests/test_orch040_compose.py
|
||||
expected: PASS
|
||||
|
||||
# --- Регресс существующего поведения ---
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: >
|
||||
Весь существующий набор тестов зелёный (нет регресса логики конвейера/launcher).
|
||||
module: tests/ # pytest tests/ -q
|
||||
expected: PASS
|
||||
|
||||
# --- Integration / ops (staging 8501, затем хост) ---
|
||||
- id: TC-06
|
||||
type: integration
|
||||
description: >
|
||||
На staging (8501) прогнать тестовую задачу конвейером end-to-end; артефакты
|
||||
worktree и docs создаются под 1000:1000 (НЕ root:root). Проверка AC-1.
|
||||
module: scripts/staging_check.py # + ls -ld на хосте
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: integration
|
||||
description: >
|
||||
После staging-прогона на хосте под slin: git -C /home/slin/repos/orchestrator
|
||||
pull/status/reset без Permission denied. Проверка AC-2.
|
||||
module: manual/host-check
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: integration
|
||||
description: >
|
||||
claude preflight/auth проходит под новым uid: агент стартует и завершается
|
||||
exit_code=0 (creds /home/slin/.claude читаются). Проверка AC-3 (МИНА 2).
|
||||
module: manual/staging-agent-run
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: integration
|
||||
description: >
|
||||
docker.sock доступен из контейнера под uid 1000 (docker ps работает) и
|
||||
ssh-деплой-хук выполняется. Проверка AC-4, AC-5 (МИНА 1 + SSH).
|
||||
module: manual/staging-deploy-path
|
||||
expected: PASS
|
||||
@@ -1,109 +0,0 @@
|
||||
# ADR-001: Контейнер и агенты бегут под uid:gid хоста (1000:1000), а не root
|
||||
|
||||
- **Статус:** Accepted
|
||||
- **Дата:** 2026-06-06
|
||||
- **Задача:** ORCH-040
|
||||
- **Связи:** глобальный [adr-0005](../../../architecture/adr/adr-0005-container-runs-as-host-uid.md), adr-0003 (staging-гейт — страховка перед прод-рестартом self), adr-0001 (`is_self_hosting_repo`).
|
||||
|
||||
## Контекст
|
||||
|
||||
Контейнер `orchestrator` (prod, 8500) работает под `uid=0 (root)` и монтирует хостовый
|
||||
`/home/slin/repos` → `/repos` (rw). Claude-CLI агенты запускаются через
|
||||
`subprocess.Popen` **внутри контейнера**, т.е. под тем же root. Все артефакты конвейера
|
||||
(git worktree `/repos/_wt/...`, коммиты в `docs/work-items/...`) появляются на **хосте**
|
||||
с владельцем `root:root`.
|
||||
|
||||
Следствие: при каждом деплое прода `git pull` / `git reset` под пользователем `slin`
|
||||
(uid 1000) падает с `insufficient permission for adding an object to repository database`
|
||||
/ `Permission denied`. Каждый деплой ломается, пока вручную не сделать `chown`.
|
||||
|
||||
Разведкой (05–06.06) подтверждено:
|
||||
- `slin = uid 1000 gid 1000`, в группах `sudo`, `docker(999)`; на хосте `/repos` и
|
||||
`/app/data` уже `1000:1000`.
|
||||
- launcher **уже** форсит `HOME=/home/slin` в двух местах: env `Popen` (`launcher.py:326`)
|
||||
и `git_env` (`launcher.py:513`). Креды читаются из `/home/slin/.claude`.
|
||||
- `docker-compose.yml`: оба сервиса имеют `group_add: ["999"]` (доступ к docker.sock —
|
||||
через gid 999, **не** через root); SSH-маунт обоих = `/home/slin/.orchestrator-ssh:/root/.ssh:ro`.
|
||||
- `CLAUDE_BIN=/opt/claude-code/bin/claude.exe` (`launcher.py:187`), `+x` для всех.
|
||||
- Dockerfile содержит `git config --system --add safe.directory '*'`.
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
1. **Вариант 1 (выбран): `user: "1000:1000"` в docker-compose для обоих сервисов.**
|
||||
Контейнер целиком бежит под uid 1000. Все файлы сразу `slin:slin`, git на хосте без
|
||||
chown. Лечит корень проблемы одной декларативной строкой на сервис, без нового кода.
|
||||
|
||||
2. **Вариант 2: drop-privileges только для subprocess агента** (`gosu` / `preexec_fn setuid`).
|
||||
Контейнер остаётся root, агент бежит под 1000. Точечно, но: новый код в горячем пути
|
||||
launcher, два класса процессов с разными uid в одном контейнере (uvicorn root vs агент
|
||||
1000), сложнее отлаживать, выше риск регресса конвейера. Корень (root-владение из самого
|
||||
uvicorn-процесса при операциях с `/repos`) лечится не полностью.
|
||||
|
||||
3. **Вариант 3 (fallback): chown-хук нормализации прав после стадии**
|
||||
(`chown -R 1000:1000` worktree/docs). Лечит симптом, не причину; требует root внутри
|
||||
контейнера (т.е. несовместим с В1) и добавляет хрупкий пост-шаг в каждый переход стадии.
|
||||
|
||||
## Решение
|
||||
|
||||
Принимаем **Вариант 1**. Изменения (применяет Dev на стадии development):
|
||||
|
||||
1. **`docker-compose.yml`** — для **обоих** сервисов (`orchestrator`, `orchestrator-staging`):
|
||||
- добавить `user: "1000:1000"`;
|
||||
- **сохранить** `group_add: ["999"]` (МИНА 1 — НЕ удалять);
|
||||
- изменить target SSH-маунта `/root/.ssh` → `/home/slin/.ssh`, чтобы он совпал с
|
||||
`HOME=/home/slin`, который форсит launcher. Итог: `/home/slin/.orchestrator-ssh:/home/slin/.ssh:ro`;
|
||||
- claude-маунты (`/home/slin/.claude`, `/home/slin/.claude.json:ro`) — оставить как есть.
|
||||
|
||||
2. **`src/agents/launcher.py`** — НЕ менять. `HOME=/home/slin` и
|
||||
`CLAUDE_BIN=/opt/claude-code/bin/claude.exe` остаются валидными под uid 1000
|
||||
(`/home/slin` материализуется bind-маунтами; бинарь исполним для всех). Правка
|
||||
допустима ТОЛЬКО при доказанной поломке запуска под 1000.
|
||||
|
||||
3. **`Dockerfile`** — НЕ менять. Отдельный non-root user внутри образа не создаём:
|
||||
numeric `user: "1000:1000"` работает без записи в `/etc/passwd`; `safe.directory '*'`
|
||||
уже покрывает git над bind-маунтом. Правка допустима только если запуск под 1000
|
||||
выявит отсутствующий каталог/право.
|
||||
|
||||
### Host-prerequisites (вне кода, выполняет Owner — обязательная процедура)
|
||||
|
||||
Без них переход на uid 1000 ломает конвейер. Фиксируются здесь и в INFRA.md как
|
||||
обязательная процедура; в git не коммитятся.
|
||||
|
||||
| # | Предусловие | Команда / проверка | Зачем |
|
||||
|---|-------------|--------------------|-------|
|
||||
| P-1 (блокер) | uid 1000 читает claude creds | `chown -R 1000:1000 /home/slin/.claude`; проверка `sudo -u '#1000' test -r /home/slin/.claude/.credentials.json` | МИНА 2: иначе preflight (ORCH-044) завернёт весь конвейер |
|
||||
| P-2 | ssh-ключи читаемы uid 1000 и в новом HOME | ключи в `/home/slin/.orchestrator-ssh` читаемы 1000; маунт ведёт в `/home/slin/.ssh` | деплой по ssh (`DEPLOY_SSH_*`) |
|
||||
| P-3 | uid:gid рантайма подтверждён | `id slin` → `1000:1000`; `/repos`, `/app/data` уже `1000:1000` | целевые файлы под slin |
|
||||
| P-4 | рестарт self только в окно тишины | `GET /status` без активных задач перед рестартом prod | self-hosting: общий инстанс с enduro-trails |
|
||||
|
||||
**Выбор способа P-1:** `chown -R 1000:1000 /home/slin/.claude` (рекомендация разведки).
|
||||
Обоснование: креды и так принадлежат slin по смыслу; chown проще и надёжнее ослабления
|
||||
read-битов и не оставляет файл world-readable. Маунт `/home/slin/.claude` оставлен rw —
|
||||
claude CLI может обновлять токен; под uid 1000 после chown это работает.
|
||||
|
||||
## Порядок безопасного внедрения (обязателен)
|
||||
|
||||
1. Применить и проверить **на staging (8501)** end-to-end (артефакты → `1000:1000`,
|
||||
агент `exit_code=0`, docker.sock и ssh-деплой живы) — `15-staging-log.md`,
|
||||
гейт `check_staging_status`.
|
||||
2. Прод-рестарт под новым uid — **только в окно тишины** (P-4).
|
||||
3. Регресс на хосте: новые tracked-артефакты `1000:1000`, `git pull` под slin без ошибок.
|
||||
|
||||
## Последствия
|
||||
|
||||
**Плюсы:**
|
||||
- Корень устранён: артефакты создаются под `slin:slin`, ручной `chown` после деплоя не нужен.
|
||||
- `HOME` теперь консистентен по всем осям (uid = claude = ssh = `/home/slin`); устранён
|
||||
скрытый рассинхрон SSH-маунта (`/root/.ssh`) с форсимым HOME.
|
||||
- Минимальная поверхность изменения: декларативный compose, без нового кода в launcher.
|
||||
|
||||
**Минусы / ограничения:**
|
||||
- Появляется жёсткая привязка к `uid 1000` хоста — задокументирована в INFRA.md;
|
||||
при переносе на другой хост uid пересматривается.
|
||||
- Требуются host-prerequisites (P-1…P-4) — часть фикса не закрывается кодом; P-1 — блокер.
|
||||
- Прод-рестарт self = групповой риск (enduro-trails) → строго окно тишины (P-4),
|
||||
страховка — staging-гейт (adr-0003).
|
||||
|
||||
**Вне объёма:** массовый `chown` уже существующих `root:root` файлов в истории (разовая
|
||||
операция Owner, команда описана в INFRA.md); логика конвейера/QG/схема БД — без изменений.
|
||||
```
|
||||
@@ -1,47 +0,0 @@
|
||||
# 07 — Инфра-требования: ORCH-040
|
||||
|
||||
Work Item: **ORCH-040** · Решение: [ADR-001](06-adr/ADR-001-run-agents-as-host-uid.md) (Вариант 1)
|
||||
|
||||
> Требования к рантайму/инфре, которые Dev обязан реализовать, а Reviewer — проверить.
|
||||
> Топология стадий и БД **не меняются**. Меняется только runtime-uid контейнера и target SSH-маунта.
|
||||
|
||||
## R-1 — runtime uid контейнера
|
||||
- Оба сервиса в `docker-compose.yml` запускаются под `user: "1000:1000"`.
|
||||
- `group_add: ["999"]` **сохраняется** на обоих (docker.sock через gid 999, МИНА 1).
|
||||
|
||||
## R-2 — SSH-маунт согласован с HOME
|
||||
- target SSH-маунта = `/home/slin/.ssh` (не `/root/.ssh`) на обоих сервисах.
|
||||
- Совпадает с `HOME=/home/slin`, форсимым в `src/agents/launcher.py` (L326, L513).
|
||||
- Источник (`/home/slin/.orchestrator-ssh`) и режим `:ro` — без изменений.
|
||||
|
||||
## R-3 — claude-маунты без изменений
|
||||
- `/home/slin/.claude` (rw) и `/home/slin/.claude.json:ro` остаются.
|
||||
- Доступ под uid 1000 обеспечивается host-prerequisite P-1 (chown creds), см. ADR.
|
||||
|
||||
## R-4 — образ и launcher без изменений (по умолчанию)
|
||||
- `Dockerfile` не меняется (numeric uid не требует записи в `/etc/passwd`;
|
||||
`safe.directory '*'` уже есть). Изменение допустимо только при доказанной поломке под 1000.
|
||||
- `src/agents/launcher.py` не меняется (`HOME`, `CLAUDE_BIN` валидны под 1000).
|
||||
|
||||
## R-5 — host-prerequisites (Owner, вне кода)
|
||||
P-1…P-4 из ADR §«Host-prerequisites» — обязательная процедура. P-1 (доступ uid 1000 к
|
||||
claude creds) — блокер: без него preflight (ORCH-044) заворачивает конвейер.
|
||||
|
||||
## R-6 — порядок внедрения
|
||||
1. staging (8501) end-to-end → `15-staging-log.md` / `check_staging_status` зелёный;
|
||||
2. прод-рестарт self — только в окно тишины (`GET /status` без активных задач, P-4);
|
||||
3. регресс на хосте: новые tracked-артефакты `1000:1000`, `git pull` под slin без ошибок.
|
||||
|
||||
## R-7 — обновление документации (golden source)
|
||||
Dev в том же PR обновляет:
|
||||
- `docs/operations/INFRA.md` — блок «Тома (volumes)» (SSH target `/home/slin/.ssh`) и
|
||||
явное указание runtime-uid (`user: 1000:1000`) контейнеров; команда разового хост-`chown`
|
||||
legacy `root:root` файлов.
|
||||
- `CHANGELOG.md` — запись `fix:`/`refactor:`.
|
||||
- глобальный [adr-0005](../../architecture/adr/adr-0005-container-runs-as-host-uid.md) уже
|
||||
заведён архитектором; индекс `docs/architecture/adr/README.md` обновлён.
|
||||
|
||||
## Что НЕ требуется
|
||||
- Новых томов, портов, env-переменных — нет.
|
||||
- Изменения API, схемы БД, реестра QG/стадий — нет.
|
||||
- Multi-node / облачные сервисы — нет (принципы архитектуры).
|
||||
@@ -1,19 +0,0 @@
|
||||
# 10 — Технические риски: ORCH-040
|
||||
|
||||
Work Item: **ORCH-040** · Решение: [ADR-001](06-adr/ADR-001-run-agents-as-host-uid.md)
|
||||
|
||||
| # | Риск | Вероятн. | Влияние | Митигация |
|
||||
|---|------|----------|---------|-----------|
|
||||
| TR-1 | **МИНА 2 — claude creds недоступны uid 1000** → preflight (ORCH-044) валит весь конвейер | Средн. | Крит. (блокер) | P-1: `chown -R 1000:1000 /home/slin/.claude` ДО рестарта; проверка `sudo -u '#1000' test -r .../.credentials.json`; staging-прогон ловит до прода (AC-3) |
|
||||
| TR-2 | **МИНА 1 — потеря доступа к docker.sock** при смене uid → деплой-операции падают | Низк. | Высок. | `group_add: ["999"]` сохраняется на обоих сервисах (НЕ удалять); проверка `docker ps` из контейнера (AC-4) |
|
||||
| TR-3 | **SSH-маунт ведёт в чужой HOME** (`/root/.ssh`) → ssh-деплой не находит ключи | Средн. | Высок. | R-2: target → `/home/slin/.ssh`, синхронно с форсимым `HOME`; проверка деплой-хука (AC-5) |
|
||||
| TR-4 | **Рестарт prod self вне окна тишины** роняет конвейер всех проектов (enduro-trails) | Средн. | Крит. | P-4: рестарт только при `GET /status` без активных задач; страховка — staging-гейт adr-0003 (AC-7, AC-9) |
|
||||
| TR-5 | **Регресс launcher** при невалидном HOME/uid (`/home/slin` отсутствует, claude.exe не исполним) | Низк. | Высок. | `/home/slin` материализуется bind-маунтами; `claude.exe` `+x` для всех; staging end-to-end + `pytest tests/ -q` (AC-6) |
|
||||
| TR-6 | **Legacy `root:root` файлы в истории** мешают git под slin даже после фикса | Высок. | Средн. | Вне объёма задачи: разовый хост-`chown` делает Owner; команда описана в INFRA.md |
|
||||
| TR-7 | **Привязка к uid 1000 конкретного хоста** усложняет перенос на другой хост | Низк. | Низк. | Задокументировано в INFRA.md как явное допущение рантайма; пересмотр при миграции хоста |
|
||||
| TR-8 | **Запись в bind-маунты под 1000** (`/app/data`, `/repos`) при неверных правах хоста | Низк. | Средн. | P-3: `/repos` и `/app/data` уже `1000:1000` (подтверждено разведкой) |
|
||||
|
||||
## Сводный вывод
|
||||
Основной блокер — TR-1 (creds). Все критичные риски снимаются обязательным staging-прогоном
|
||||
(adr-0003) ПЕРЕД прод-рестартом и выполнением host-prerequisites P-1…P-4. Изменение
|
||||
декларативное (compose), без правок горячего кода launcher → низкая поверхность регресса.
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-040
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-040
|
||||
|
||||
## Summary
|
||||
Фикс переводит оба compose-сервиса (`orchestrator`, `orchestrator-staging`) на
|
||||
`user: "1000:1000"` (Вариант 1 из ADR-001 / adr-0005), чтобы артефакты конвейера
|
||||
создавались как `slin:slin` и git на хосте работал без ручного `chown`. Реализация
|
||||
точно соответствует ТЗ и ADR, документация (INFRA.md, CHANGELOG.md, work-item ADR-001,
|
||||
глобальный adr-0005) обновлена в том же PR, host-prerequisites (P-1…P-4) задокументированы.
|
||||
Полный прогон `pytest tests/ -q` — **501 passed**. Блокеров и must-fix нет.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- нет
|
||||
|
||||
### P1 — Must fix
|
||||
- нет
|
||||
|
||||
### P2 — Should fix
|
||||
- нет
|
||||
|
||||
### P3 — Nice to have
|
||||
- [ ] (опц.) AC-1/2/3/4/5 — это runtime/host-критерии; их фактическое PASS подтверждается
|
||||
на стадиях `testing` и `deploy-staging` (`15-staging-log.md`, `staging_status:`), а не
|
||||
ревью кода. Зафиксировано как ожидание к следующим стадиям, не как замечание к PR.
|
||||
|
||||
## Проверка по осям
|
||||
|
||||
**1. Соответствие ТЗ (02-trz.md §4):**
|
||||
- §4.1 `docker-compose.yml`: оба сервиса получили `user: "1000:1000"` ✅; `group_add: ["999"]`
|
||||
сохранён (МИНА 1 — не удалён) ✅; SSH-маунт target `/root/.ssh` → `/home/slin/.ssh` ✅;
|
||||
claude-маунты (`/home/slin/.claude`, `.claude.json:ro`) не тронуты ✅.
|
||||
- §4.3 `src/agents/launcher.py` не менялся; `HOME=/home/slin` остаётся на стр. 326 и 513
|
||||
(подтверждено grep) — согласован с новым SSH target ✅.
|
||||
- §4.4 `Dockerfile` не менялся (numeric uid не требует записи в `/etc/passwd`,
|
||||
`safe.directory '*'` уже есть) — в полном соответствии с решением ADR ✅.
|
||||
- §5/§6/§7: изменений API/БД/QG нет — подтверждено ✅.
|
||||
|
||||
**2. Соответствие ADR (ADR-001 + global adr-0005):**
|
||||
- Выбран и реализован Вариант 1 ровно как описано в ADR (compose-only, без нового кода
|
||||
в launcher и Dockerfile) ✅.
|
||||
- Host-prerequisites P-1…P-4 из ADR перенесены в INFRA.md как обязательная процедура Owner ✅.
|
||||
- Нарушений глобальных ADR нет; связи с adr-0003 (staging-гейт как страховка) учтены ✅.
|
||||
|
||||
**3. Качество кода:**
|
||||
- Изменения декларативные, с поясняющими комментариями и ссылкой на ADR ✅.
|
||||
- Тесты `tests/test_orch040_compose.py` содержательные: проверяют `user`, сохранение
|
||||
`group_add 999`, SSH target под HOME и согласованность HOME launcher'а с маунтами
|
||||
(TC-01…TC-04, привязаны к AC) — не тривиальные ✅.
|
||||
- Регресс отсутствует: `pytest tests/ -q` → 501 passed ✅.
|
||||
|
||||
## Документация
|
||||
Обновлена корректно и в том же PR (golden source соблюдён, AC-8 PASS):
|
||||
- `docs/operations/INFRA.md` — добавлен блок «Рантайм-uid (ORCH-040)», host-prerequisites,
|
||||
блок volumes/SSH target приведён к `/home/slin/.ssh` ✅;
|
||||
- `CHANGELOG.md` — запись в разделе Fixed ✅;
|
||||
- `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` — выбор варианта +
|
||||
обоснование + P-1…P-4 ✅;
|
||||
- глобальный `docs/architecture/adr/adr-0005-container-runs-as-host-uid.md` (+ запись в
|
||||
`adr/README.md`) — сквозное решение зафиксировано ✅.
|
||||
|
||||
Изменения `src/` Python-кода нет (правка только в `docker-compose.yml` + тесты), но
|
||||
документация всё равно обновлена — требование §2 CLAUDE.md выполнено с запасом.
|
||||
@@ -1,94 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-040
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-040
|
||||
|
||||
Тема: agent-файлы конвейера создаются под uid хоста (`1000:1000`, slin),
|
||||
а не `root:root`. Реализация — Вариант 1 (`user: "1000:1000"` в обоих
|
||||
compose-сервисах), правка только в `docker-compose.yml` + тесты.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Сервис (prod 8500): `/health` → 200 `{"status":"ok"}`; preflight_ok=true (`2.1.142 (Claude Code)`)
|
||||
- Дата: 2026-06-06T15:06:25Z
|
||||
- Ветка: feature/ORCH-040-root-git
|
||||
|
||||
## Smoke test API (read-only GET, прод-контейнер не трогался)
|
||||
| Endpoint | Результат |
|
||||
|----------|-----------|
|
||||
| GET /health | 200 — `{"status":"ok","service":"orchestrator"}` |
|
||||
| GET /status | 200 — активная задача ORCH-040 (stage=testing) |
|
||||
| GET /queue | 200 — counts ok, max_concurrency=1, breaker=closed, preflight_ok=true |
|
||||
|
||||
> curl в окружении тестера отсутствует; smoke выполнен эквивалентным запросом
|
||||
> через `python -m urllib.request` (только GET, без побочных эффектов).
|
||||
|
||||
## Результаты (по 04-test-plan.yaml)
|
||||
|
||||
| TC ID | Описание | Тип | Результат |
|
||||
|-------|----------|-----|-----------|
|
||||
| TC-01 | compose: оба сервиса `user: "1000:1000"` (Вариант 1) | unit | PASS |
|
||||
| TC-02 | compose: оба сервиса сохраняют `group_add: ["999"]` (МИНА 1, docker.sock) | unit | PASS |
|
||||
| TC-03 | compose: SSH-маунт target под `/home/slin/.ssh`, согласован с HOME | unit | PASS |
|
||||
| TC-04 | launcher: форсимый HOME совместим с claude/SSH-маунтами (`/home/slin`) | unit | PASS |
|
||||
| TC-05 | полный регресс `pytest tests/` зелёный (нет регресса конвейера/launcher) | unit | PASS (501 passed) |
|
||||
| TC-06 | staging E2E: артефакты worktree/docs создаются `1000:1000` (AC-1) | integration | DEFERRED → deploy-staging |
|
||||
| TC-07 | хост под slin: `git pull/status/reset` без Permission denied (AC-2) | integration | DEFERRED → deploy-staging |
|
||||
| TC-08 | claude preflight/auth под uid 1000, агент exit_code=0 (AC-3, МИНА 2) | integration | DEFERRED → deploy-staging |
|
||||
| TC-09 | docker.sock + ssh-деплой под uid 1000 (AC-4, AC-5) | integration | DEFERRED → deploy-staging |
|
||||
|
||||
**О TC-06…TC-09:** по дизайну test-plan'а это ops/integration-проверки на
|
||||
staging (8501) и хосте, касающиеся прав ФС хоста и docker-рантайма. Они
|
||||
относятся к стадии `deploy-staging` (их PASS фиксируется в `15-staging-log.md`,
|
||||
`staging_status:`) и не воспроизводимы в окружении стадии `testing` без
|
||||
рестарта контейнера под новым uid. Это совпадает с замечанием ревью
|
||||
(12-review.md, P3): runtime/host-критерии AC-1…AC-5 подтверждаются на
|
||||
`deploy-staging`, а не при тестировании кода. Запуск деструктивных операций /
|
||||
рестарт self в рамках стадии testing запрещён (CLAUDE.md, self-hosting).
|
||||
|
||||
## Покрытие критериев приёмки (03-acceptance-criteria.md)
|
||||
| AC | Статус на стадии testing |
|
||||
|----|--------------------------|
|
||||
| AC-1 (артефакты под uid хоста) | runtime — проверяется на deploy-staging |
|
||||
| AC-2 (git под slin) | runtime — проверяется на deploy-staging |
|
||||
| AC-3 (claude preflight ok) | preflight_ok=true в `/queue`; полное E2E — deploy-staging |
|
||||
| AC-4 (docker.sock доступен) | конфиг подтверждён TC-02; runtime — deploy-staging |
|
||||
| AC-5 (SSH-деплой) | конфиг подтверждён TC-03; runtime — deploy-staging |
|
||||
| AC-6 (конвейер без регресса, pytest зелёный) | **PASS** — 501 passed |
|
||||
| AC-7 (проверено на staging до прода) | стадия deploy-staging |
|
||||
| AC-8 (документация/ADR обновлены) | **PASS** — подтверждено ревью (APPROVED) |
|
||||
| AC-9 (прод не уронен вне окна тишины) | стадия deploy/окно тишины |
|
||||
| AC-10 (host-prerequisites зафиксированы) | **PASS** — P-1…P-4 в ADR/INFRA |
|
||||
|
||||
## Вывод pytest
|
||||
```
|
||||
$ python -m pytest tests/ -v --tb=short
|
||||
platform linux -- Python 3.12.13, pytest-8.3.3, pluggy-1.6.0
|
||||
configfile: pytest.ini
|
||||
plugins: anyio-4.13.0, asyncio-0.23.8
|
||||
...
|
||||
======================== 501 passed, 1 warning in 8.54s ========================
|
||||
|
||||
$ python -m pytest tests/test_orch040_compose.py -v
|
||||
tests/test_orch040_compose.py::test_tc01_service_runs_as_host_uid[orchestrator] PASSED
|
||||
tests/test_orch040_compose.py::test_tc01_service_runs_as_host_uid[orchestrator-staging] PASSED
|
||||
tests/test_orch040_compose.py::test_tc02_group_add_keeps_docker_gid[orchestrator] PASSED
|
||||
tests/test_orch040_compose.py::test_tc02_group_add_keeps_docker_gid[orchestrator-staging] PASSED
|
||||
tests/test_orch040_compose.py::test_tc03_ssh_mount_under_home[orchestrator] PASSED
|
||||
tests/test_orch040_compose.py::test_tc03_ssh_mount_under_home[orchestrator-staging] PASSED
|
||||
tests/test_orch040_compose.py::test_tc04_launcher_home_matches_mounts PASSED
|
||||
========================= 7 passed, 1 warning in 0.31s =========================
|
||||
```
|
||||
(1 warning — Pydantic V2 deprecation в `src/config.py`, не относится к ORCH-040.)
|
||||
|
||||
## Итог
|
||||
**PASS** — все автоматизируемые тесты (TC-01…TC-05) зелёные, полный регресс
|
||||
501 passed, smoke API ok, документация/ADR подтверждены ревью. Runtime/host
|
||||
критерии (TC-06…TC-09, AC-1…AC-5/7/9) корректно отложены на обязательную
|
||||
стадию `deploy-staging` (8501) — страховку self-hosting перед прод-деплоем.
|
||||
|
||||
Задача переходит на стадию **deploy-staging**.
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
timestamp: 2026-06-06T15:10:00+00:00
|
||||
target: prod orchestrator (8500) + staging orchestrator-staging (8501)
|
||||
mode: artifact-validated; prod restart handed off to Owner (self-hosting safeguard)
|
||||
---
|
||||
|
||||
# Deploy Log — ORCH-040
|
||||
|
||||
## Verdict
|
||||
|
||||
`deploy_status: SUCCESS` — deployable artifact validated and ready. The automated
|
||||
deploy-stage responsibility is complete. **The actual prod-container restart is an
|
||||
Owner action** (see Handoff) and was deliberately NOT performed by this agent.
|
||||
|
||||
## Why no in-task prod restart
|
||||
|
||||
ORCH-040 is a **self-hosting** change: it makes the running prod instance
|
||||
`orchestrator` (8500) run as `user: "1000:1000"` instead of root. Per CLAUDE.md
|
||||
rule #1 and INFRA.md §Self-hosting, an ORCH task **must not** restart or drop the
|
||||
prod container — the single prod instance with a shared DB/queue also serves
|
||||
enduro-trails, so a restart inside the task is a group risk for all projects.
|
||||
Real prod deploys go through `scripts/orchestrator-deploy-hook.sh` (DEPLOY_HOOK.md)
|
||||
executed by the Owner, not by the deployer agent.
|
||||
|
||||
## What was validated
|
||||
|
||||
- **Staging gate green** — `15-staging-log.md` → `staging_status: SUCCESS`,
|
||||
10/10 checks PASS on the live staging instance (8501), already running under
|
||||
`user: "1000:1000"`. Artifacts created as `slin:slin`, agent `exit_code=0`,
|
||||
docker.sock + ssh-deploy paths live. This is the canonical pre-prod safeguard
|
||||
(ADR-0003 staging gate, ADR-001 §Порядок безопасного внедрения step 1).
|
||||
- **Deployable artifact correct** — `docker-compose.yml` on branch
|
||||
`feature/ORCH-040-root-git` (commit `f81715b`):
|
||||
- both services have `user: "1000:1000"`;
|
||||
- `group_add: ["999"]` **present** for both (МИНА 1 — docker.sock access via gid
|
||||
999, not root — NOT removed);
|
||||
- SSH mount retargeted `/root/.ssh` → `/home/slin/.ssh` to match the launcher's
|
||||
forced `HOME=/home/slin`;
|
||||
- claude mounts unchanged.
|
||||
- `src/agents/launcher.py` and `Dockerfile` unchanged, as the ADR mandates.
|
||||
|
||||
## Handoff — Owner prod cut-over (out-of-code, ADR-001 §Host-prerequisites & §Порядок)
|
||||
|
||||
Perform in this order, **only in a quiet window** (P-4):
|
||||
|
||||
1. **P-1 (BLOCKER)** — `chown -R 1000:1000 /home/slin/.claude`; verify
|
||||
`sudo -u '#1000' test -r /home/slin/.claude/.credentials.json`. Without this,
|
||||
preflight (ORCH-044) will fail the whole pipeline.
|
||||
2. **P-2** — ssh keys in `/home/slin/.orchestrator-ssh` readable by uid 1000.
|
||||
3. **P-3** — confirm `id slin` → `1000:1000`; `/repos`, `/app/data` already `1000:1000`.
|
||||
4. **P-4** — confirm `GET http://localhost:8500/status` shows **no active tasks**
|
||||
before restarting prod (shared instance with enduro-trails).
|
||||
5. Prod cut-over via the deploy hook (conscious prod override):
|
||||
```bash
|
||||
TARGET_SERVICE=orchestrator TARGET_PORT=8500 \
|
||||
TARGET_IMAGE=orchestrator-orchestrator COMPOSE_PROFILE="" \
|
||||
PREV_IMAGE_FILE=/home/slin/repos/orchestrator/.deploy-prev-image-prod \
|
||||
bash scripts/orchestrator-deploy-hook.sh --deploy
|
||||
```
|
||||
The hook captures the previous image, runs a 60s health loop, and auto-rolls
|
||||
back on failure.
|
||||
6. Post-deploy regression: new tracked artifacts are `slin:slin`; `git pull`
|
||||
under slin works without manual `chown`.
|
||||
|
||||
## Summary
|
||||
|
||||
| Item | State |
|
||||
|------|-------|
|
||||
| Staging gate (`check_staging_status`) | SUCCESS (10/10) |
|
||||
| Compose artifact (user/group_add/ssh) | correct, МИНА 1 intact |
|
||||
| In-task prod restart | NOT performed (self-hosting safeguard, by design) |
|
||||
| Prod cut-over | handed off to Owner (P-1…P-4 + deploy hook) |
|
||||
| Deploy stage verdict | SUCCESS |
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-06T15:08:10+00:00
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed. All checks passed.
|
||||
|
||||
- **Work item:** ORCH-040
|
||||
- **Mode:** stub
|
||||
- **Execution:** canonical — `docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub` (ORCH-048, ADR-001)
|
||||
- **Result:** 10/10 checks PASS (exit code 0)
|
||||
|
||||
## Check results
|
||||
|
||||
| Check | Result | Detail |
|
||||
|-------|--------|--------|
|
||||
| A1 GET /health → 200 status=ok | PASS | body `{status: ok, service: orchestrator}` |
|
||||
| A2 GET /queue → 200 with counts/max_concurrency/resilience | PASS | keys present |
|
||||
| A3 ORCH_STAGING=true (not prod) | PASS | `ORCH_STAGING=true` |
|
||||
| B4 Plane: sandbox project accessible | PASS | found 5 project(s), sandbox=YES |
|
||||
| B5 Gitea: orchestrator-sandbox accessible, push=true | PASS | admin/push/pull=true |
|
||||
| B6 Registry: sandbox present, prod ET/ORCH absent | PASS | sandbox=YES, prod-ET=NO, prod-ORCH=NO |
|
||||
| C7 Create issue in Plane SANDBOX | PASS | HTTP 201 |
|
||||
| C8 Trigger pipeline via /webhook/plane | PASS | HTTP 200, status=accepted |
|
||||
| C9a Branch appears in orchestrator-sandbox | PASS | feature/SANDBOX-016-staging-check-e2e |
|
||||
| C9b Analyst job enqueued in staging queue | PASS | job queued, agent=analyst |
|
||||
|
||||
Cleanup (branch, Plane issue, DB rows) completed successfully via try/finally.
|
||||
|
||||
> Note: Docker CLI was unavailable in the deployer environment; the canonical
|
||||
> in-container exec was performed via the Docker Engine API over the unix socket
|
||||
> (equivalent to `docker exec`). B6 registry-isolation therefore reflects the
|
||||
> running staging instance's own `.env.staging` process-env — no host-env
|
||||
> fallback (avoids the ORCH-048 false-FAIL).
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Telegram live-tracker: режим bump (карточка падает вниз при обновлении)
|
||||
|
||||
Work Item ID: ORCH-042
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,65 +0,0 @@
|
||||
# 01 — BRD: Telegram live-tracker, режим bump + русификация карточки
|
||||
|
||||
**Work Item:** ORCH-042
|
||||
**Тип:** UX-улучшение (notifications)
|
||||
**Приоритет:** средний
|
||||
**Запрос:** Слава, 05.06. Связь: `feat/telegram-live-tracker` (Variant B+).
|
||||
**Self-hosting:** да — правка самого оркестратора, проходит через его же конвейер (общая БД/очередь с enduro-trails). См. `docs/operations/INFRA.md`.
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
Live-tracker задачи (`src/notifications.py`) — это ОДНА карточка на задачу в Telegram, которая обновляется на каждом переходе стадии через `editMessageText` (Variant B+). Так сделано СПЕЦИАЛЬНО, чтобы убить старую проблему «~15 отдельных карточек/дублей на задачу».
|
||||
|
||||
Побочный эффект текущего решения: карточка редактируется **на месте в истории чата**. При активной переписке в чате карточка «тонет» вверху и её неудобно искать — приходится скроллить вверх к старому сообщению, чтобы увидеть актуальный статус задачи.
|
||||
|
||||
Дополнительно накопились косметические претензии к тексту карточки: смесь англоязычных меток стадий с русским текстом, неудачная формулировка «Ревью БРД», и финальный технический хвост `deployed` вместо человекочитаемого «Внедрено».
|
||||
|
||||
## 2. Цель
|
||||
|
||||
1. Дать Славе альтернативный режим отображения трекера — **bump**: при каждом обновлении карточка «падает вниз» свежим сообщением (всегда последняя в чате), но БЕЗ возврата к проблеме дублей (по-прежнему ОДНА карточка на задачу) и БЕЗ спама звуками/пингами.
|
||||
2. Привести текст карточки к единому русскому виду и поправить формулировки.
|
||||
|
||||
## 3. Заинтересованные лица
|
||||
|
||||
- **Слава (Owner)** — единственный получатель Telegram-уведомлений; принимает UX.
|
||||
- **Агенты конвейера** — косвенно: трекер обновляется из `notify_*`-хелперов на каждой стадии.
|
||||
|
||||
## 4. Требования (бизнес-уровень)
|
||||
|
||||
### 4.1. Режим работы трекера (флаг)
|
||||
- **BR-1.** Новый конфиг-флаг `ORCH_TRACKER_MODE` с двумя значениями:
|
||||
- `edit` — текущее поведение (редактирование на месте). **Это ДЕФОЛТ** (обратная совместимость, никакой регрессии без явного включения).
|
||||
- `bump` — новый режим «карточка падает вниз».
|
||||
- **BR-2.** Неизвестное/пустое значение флага трактуется как `edit` (безопасный фолбэк, оркестратор не падает).
|
||||
|
||||
### 4.2. Поведение режима bump
|
||||
- **BR-3.** При обновлении карточки в режиме `bump`: старое сообщение удаляется (`deleteMessage`), отправляется новое (`sendMessage`), указатель `tracker_message_id` перенаправляется на новое сообщение. Итог: в чате всегда ровно ОДНА карточка задачи, и она всегда внизу.
|
||||
- **BR-4.** Bump тихий: новое сообщение отправляется с `disable_notification=true` — карточка всплывает внизу, но БЕЗ звука/пинга на каждой стадии (как и сейчас в edit-режиме).
|
||||
- **BR-5.** Первое обновление (карточки ещё нет) в режиме `bump` — просто тихо отправить новое и запомнить id (удалять нечего).
|
||||
|
||||
### 4.3. Устойчивость (критично — не сломать защиту от дублей)
|
||||
- **BR-6.** Fallback: если `deleteMessage` не удался (сообщение старше 48 ч / уже удалено / недоступно) — карточка всё равно отправляется заново, оркестратор НЕ падает.
|
||||
- **BR-7.** Любой сбой нотификации (сеть/таймаут/5xx/Telegram-ошибка) НЕ роняет оркестратор (контракт «never raises» сохраняется) и НЕ плодит дубли карточек в пределах одного обновления.
|
||||
- **BR-8.** Режим `edit` после изменений работает строго как раньше — без регрессий (защита от ~15 дублей сохранена).
|
||||
|
||||
### 4.4. Текстовые правки карточки (применяются в ОБОИХ режимах)
|
||||
- **BR-9.** Метку «Ревью БРД» заменить на «Подтверждение BRD».
|
||||
- **BR-10.** После того как задача переведена в Approved (человеческий gate пройден, время ревью зафиксировано), эмодзи в строке подтверждения BRD заменить на галочку (✅) вместо текущей паузы (⏸️). Пока ждём человека — оставить прежний индикатор ожидания.
|
||||
- **BR-11.** Русифицировать метки стадий карточки: `Analysis → Анализ`, `Architecture → Архитектура`, `Development → Разработка`, `Review → Код ревью`, `Testing → Тестирование`, `Deploy → Внедрение`.
|
||||
- **BR-12.** В итоговой (последней) строке готовой задачи заменить технический `deployed` на «Внедрено».
|
||||
|
||||
## 5. Вне scope
|
||||
- Изменение состава событий, которые шлются ОТДЕЛЬНЫМИ пингами (approve-gate / deploy-fail / agent-fail / error) — остаётся как есть.
|
||||
- Изменение формата метрик (токены/стоимость/длительность), макета строк, логики «попытка N».
|
||||
- Любые изменения в Plane-комментариях агентов (`usage.build_status_comment`).
|
||||
- Хранение истории карточек / несколько карточек на задачу.
|
||||
|
||||
## 6. Влияние на документацию (golden source)
|
||||
- `CHANGELOG.md` — запись в `[Unreleased]`.
|
||||
- `docs/architecture/internals.md` (или соответствующая секция про live-tracker) — описать режимы `edit`/`bump` и `ORCH_TRACKER_MODE`.
|
||||
- `.env.example` — добавить `ORCH_TRACKER_MODE` с пояснением.
|
||||
|
||||
## 7. Критерии успеха (резюме)
|
||||
Слава может выставить `ORCH_TRACKER_MODE=bump` и видеть актуальную карточку всегда внизу чата, одну на задачу, без звона; при откате на `edit` (дефолт) поведение неотличимо от текущего; текст карточки полностью русифицирован по BR-9..BR-12. Полные условия PASS/FAIL — `03-acceptance-criteria.md`.
|
||||
</content>
|
||||
</invoke>
|
||||
@@ -1,118 +0,0 @@
|
||||
# 02 — ТЗ: Telegram live-tracker, режим bump + русификация
|
||||
|
||||
**Work Item:** ORCH-042 · См. `01-brd.md`, `03-acceptance-criteria.md`.
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
| Файл | Что меняется |
|
||||
|------|--------------|
|
||||
| `src/config.py` | Новое поле `Settings.tracker_mode` (env `ORCH_TRACKER_MODE`). |
|
||||
| `src/notifications.py` | Новый helper `delete_telegram(message_id)`; ветвление `update_task_tracker` по режиму; текстовые правки в `_BRD_LABEL`, `_TRACKER_STAGES`, BRD-строке `render_task_tracker`, `_done_link`. |
|
||||
|
||||
БД — **без изменений** (используется существующая колонка `tasks.tracker_message_id` и хелперы `get_tracker_message_id` / `set_tracker_message_id` в `src/db.py`). API HTTP-эндпоинты оркестратора — **без изменений**. Новые QG checks — **не требуются**.
|
||||
|
||||
## 2. Изменения конфигурации (`src/config.py`)
|
||||
|
||||
Добавить в класс `Settings` (рядом с блоком «Telegram notifications»):
|
||||
|
||||
```python
|
||||
# ORCH-042: режим live-трекера задачи.
|
||||
# edit -> карточка редактируется на месте (editMessageText), ДЕФОЛТ (как было).
|
||||
# bump -> при обновлении старое сообщение удаляется и карточка отправляется
|
||||
# заново вниз чата (deleteMessage + sendMessage + repoint message_id),
|
||||
# тихо (disable_notification). Одна карточка на задачу в обоих режимах.
|
||||
# Неизвестное/пустое значение трактуется как edit (см. notifications).
|
||||
tracker_mode: str = "edit"
|
||||
```
|
||||
|
||||
- `env_prefix = "ORCH_"` уже задан → переменная окружения `ORCH_TRACKER_MODE`.
|
||||
- Резолюция режима — в `notifications`: всё, что не равно (case-insensitive, trimmed) `"bump"`, считается `edit`. Не падать на любом значении.
|
||||
|
||||
## 3. Изменения нотификаций (`src/notifications.py`)
|
||||
|
||||
### 3.1. Новый low-level helper `delete_telegram`
|
||||
Рядом с `send_telegram` / `edit_telegram`. Контракт «never raises».
|
||||
|
||||
```python
|
||||
def delete_telegram(message_id: int) -> bool:
|
||||
"""Delete a Telegram message. Never raises.
|
||||
|
||||
Returns True if the message is gone after the call (deleted now, OR Telegram
|
||||
says it's already not there / can't be deleted -> treat as "no longer our
|
||||
problem", caller proceeds to send a fresh card). Returns False only on a
|
||||
transient failure (network / timeout / 5xx / unknown error) where the old
|
||||
message may still be alive.
|
||||
"""
|
||||
```
|
||||
|
||||
Требования к реализации:
|
||||
- Эндпоинт `https://api.telegram.org/bot{token}/deleteMessage`, тело `{chat_id, message_id}`, `timeout=5`.
|
||||
- Нет токена/chat_id → вернуть `False` (как и прочие helpers при отсутствии кредов — ничего не отправлено, ничего не удалено).
|
||||
- `ok:true` → `True`.
|
||||
- `ok:false` с описанием «уже нет / нельзя удалить» (маркеры: `"message to delete not found"`, `"message can't be deleted"`, `"message_id_invalid"`) → `True` (сообщение и так недоступно; не транзиент).
|
||||
- Прочие `ok:false` (неизвестный 400 / 5xx) и исключения (сеть/таймаут) → `False` + `logger.warning`.
|
||||
- Вынести маркеры в модульную константу (по аналогии с `_GONE_MARKERS`), например `_DELETE_GONE_MARKERS`.
|
||||
|
||||
### 3.2. Ветвление `update_task_tracker` по режиму
|
||||
Сохранить существующий путь `edit` без изменений поведения. Добавить путь `bump`.
|
||||
|
||||
Псевдокод целевой логики:
|
||||
```python
|
||||
def update_task_tracker(task_id: int):
|
||||
try:
|
||||
from .db import get_tracker_message_id, set_tracker_message_id
|
||||
text = render_task_tracker(task_id)
|
||||
mode = (_get_settings().tracker_mode or "edit").strip().lower()
|
||||
mid = get_tracker_message_id(task_id)
|
||||
|
||||
if mode == "bump":
|
||||
# bump: одна карточка, но всегда внизу.
|
||||
if mid is not None:
|
||||
delete_telegram(mid) # best-effort; fallback -> всё равно шлём новое
|
||||
new_mid = send_telegram(text, disable_notification=True)
|
||||
if new_mid is not None:
|
||||
set_tracker_message_id(task_id, new_mid)
|
||||
# send вернул None (нет кредов / транзиент) -> mid не трогаем,
|
||||
# дубля в пределах вызова нет; перерисуется на следующем переходе.
|
||||
return
|
||||
|
||||
# mode == "edit" (ДЕФОЛТ): существующая логика без изменений.
|
||||
... # текущий код edit/EDIT_GONE-fallback as is
|
||||
except Exception as e:
|
||||
logger.warning(f"update_task_tracker({task_id}) failed: {e}")
|
||||
```
|
||||
|
||||
Инварианты bump-ветки:
|
||||
- В пределах ОДНОГО вызова отправляется максимум одно новое сообщение → дублей нет (BR-7).
|
||||
- `set_tracker_message_id` вызывается ТОЛЬКО при успешном `send` (`new_mid is not None`). При сбое send id остаётся прежним; на следующем переходе старый будет удалён (или уже мёртв) и отправлен новый — без накопления карточек.
|
||||
- `delete_telegram` — best-effort: его результат НЕ блокирует отправку новой карточки (BR-6: delete-fail → всё равно шлём новое).
|
||||
- Bump всегда тихий: `disable_notification=True` (BR-4).
|
||||
|
||||
### 3.3. Текстовые правки (общие для обоих режимов)
|
||||
|
||||
| BR | Где | Было | Стало |
|
||||
|----|-----|------|-------|
|
||||
| BR-9 | `_BRD_LABEL` (модульная константа) | `"Ревью БРД"` | `"Подтверждение BRD"` |
|
||||
| BR-10 | `render_task_tracker`, ветка BRD-строки при `review_seconds is not None` | префикс `⏸️` (`⏸️`) | `✅` (`✅`). Ветка ожидания (`review_seconds is None`, с ⏳) — НЕ менять. |
|
||||
| BR-11 | `_TRACKER_STAGES` (метки) | `Analysis / Architecture / Development / Review / Testing / Deploy` | `Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение` |
|
||||
| BR-12 | `_done_link` | `"\U0001f4e6 deployed"` | `"\U0001f4e6 Внедрено"` |
|
||||
|
||||
Примечания:
|
||||
- В `_TRACKER_STAGES` меняется ТОЛЬКО display-label (2-й элемент кортежа). Ключи стадий (`analysis`,…) и имена агентов (`analyst`,…) НЕ трогать — они завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД.
|
||||
- Выравнивание `{label:<13}` и `{_BRD_LABEL:<13}` оставить как есть (все новые русские метки ≤13 символов; «Подтверждение BRD» длиннее — формат просто не паддит, косметика, поведение не ломает).
|
||||
- Метки используются и в «✅ …»-строках завершённых стадий, и в «🔄 … идёт»-строке активной стадии — обе автоматически станут русскими (правка в одном месте).
|
||||
|
||||
## 4. Совместимость и риски
|
||||
- Дефолт `edit` гарантирует нулевую регрессию без явного включения bump (BR-8). Подробно — `10-tech-risks.md` (заводит архитектор/девелопер при необходимости).
|
||||
- Самохостинг: изменения только в коде нотификаций, миграций БД нет, перезапуск self — по стандартной страховке `deploy-staging` (8501) перед prod (см. `CLAUDE.md`).
|
||||
|
||||
## 5. Артефакты pipeline, которые ДОЛЖНЫ быть обновлены в этом же PR
|
||||
- `CHANGELOG.md` → запись в `[Unreleased] / Added` (режим bump) + `Changed` (русификация текста).
|
||||
- `docs/architecture/internals.md` — секция про live-tracker: режимы `edit`/`bump`, `ORCH_TRACKER_MODE`, контракт `delete_telegram`.
|
||||
- `.env.example` — `ORCH_TRACKER_MODE=edit` с комментарием.
|
||||
- Тесты — см. `04-test-plan.yaml`. **Существующие тесты в `tests/test_telegram_tracker.py`, проверяющие англоязычные метки (`"✅ Analysis"`, `"🔄 Deploy"`, `"Review"`) и метку `"Ревью БРД"`, ОБЯЗАТЕЛЬНО обновить под новые русские строки** — иначе регрессия в CI. Это правка существующих ассертов, не изменение контракта.
|
||||
|
||||
## 6. Замечания по реализации (без расширения scope)
|
||||
- Не вводить новых зависимостей; `httpx` уже используется.
|
||||
- Не менять сигнатуры `send_telegram` / `edit_telegram` / `update_task_tracker` (внешние вызовы из `launcher`/`stage_engine` не трогаются).
|
||||
- Не менять состав отдельных пингов (approve-gate / error / deploy-fail / agent-fail).
|
||||
</content>
|
||||
@@ -1,55 +0,0 @@
|
||||
# 03 — Критерии приёмки: ORCH-042
|
||||
|
||||
Каждый критерий — однозначное условие PASS/FAIL. Покрытие тестами — `04-test-plan.yaml`.
|
||||
|
||||
## Конфигурация
|
||||
- **AC-1.** `Settings.tracker_mode` существует, дефолт `"edit"`, читается из env `ORCH_TRACKER_MODE`.
|
||||
- PASS: `Settings().tracker_mode == "edit"` без env; `ORCH_TRACKER_MODE=bump` → `"bump"`.
|
||||
- FAIL: поле отсутствует / другой дефолт / не читает env.
|
||||
- **AC-2.** Неизвестное/пустое значение режима трактуется как `edit` (оркестратор не падает).
|
||||
- PASS: `ORCH_TRACKER_MODE=garbage` (или пусто) → `update_task_tracker` идёт по edit-ветке, исключений нет.
|
||||
- FAIL: исключение / выбор bump-ветки на мусоре.
|
||||
|
||||
## Режим edit (регрессия — поведение как было)
|
||||
- **AC-3.** Первый вызов (нет `tracker_message_id`): `sendMessage` тихо (`disable_notification=True`), id сохраняется; `editMessageText` НЕ вызывается.
|
||||
- **AC-4.** Повторный вызов при живом сообщении: `editMessageText` на сохранённый id; новое сообщение НЕ шлётся.
|
||||
- **AC-5.** `edit` вернул `EDIT_GONE` → шлётся НОВОЕ сообщение, id обновляется (fallback как раньше).
|
||||
- **AC-6.** `edit` вернул `EDIT_NOT_MODIFIED` или `EDIT_FAILED` → новое сообщение НЕ шлётся, id не меняется (защита от дублей сохранена).
|
||||
- Все AC-3..AC-6 проверяются при `tracker_mode="edit"` (дефолт). FAIL — любое расхождение с текущим поведением.
|
||||
|
||||
## Режим bump
|
||||
- **AC-7.** Первый вызов в `bump` (нет id): `deleteMessage` НЕ вызывается; `sendMessage` тихо (`disable_notification=True`); возвращённый id сохраняется.
|
||||
- PASS: ровно один `send_telegram(..., disable_notification=True)`, `delete_telegram` не вызван, `get_tracker_message_id == new_id`.
|
||||
- FAIL: вызван delete / громкое сообщение / id не сохранён.
|
||||
- **AC-8.** Повторный вызов в `bump` при существующем id: вызывается `delete_telegram(старый_id)`, затем `send_telegram(..., disable_notification=True)`, затем `tracker_message_id` перенаправляется на новый id.
|
||||
- PASS: порядок delete→send соблюдён, id == новый.
|
||||
- FAIL: нет delete / нет send / id остался старым.
|
||||
- **AC-9.** Bump тихий: новое сообщение всегда с `disable_notification=True`.
|
||||
- FAIL: `disable_notification` False/отсутствует.
|
||||
- **AC-10.** Одна карточка на задачу: за один вызов `update_task_tracker` в bump шлётся НЕ более одного нового сообщения.
|
||||
- FAIL: более одного `send_telegram` за вызов.
|
||||
|
||||
## Устойчивость
|
||||
- **AC-11.** Fallback при delete-fail: если `delete_telegram` вернул False (старое >48ч / транзиент) — новое сообщение всё равно отправляется, id обновляется, исключений нет.
|
||||
- PASS: `delete_telegram→False` → ровно один send → id == новый.
|
||||
- FAIL: send пропущен / исключение всплыло.
|
||||
- **AC-12.** `delete_telegram` классификация (httpx замокан, never raises):
|
||||
- `ok:true` → `True`;
|
||||
- `ok:false` с `"message to delete not found"` / `"message can't be deleted"` / `"message_id_invalid"` → `True`;
|
||||
- неизвестный `ok:false` / 5xx → `False`;
|
||||
- исключение (таймаут/сеть) → `False`;
|
||||
- нет токена/chat_id → `False`, HTTP-вызов не выполняется.
|
||||
- **AC-13.** Транзиентный сбой send в bump (send вернул None): `tracker_message_id` НЕ затирается на None; исключений нет; дублей нет (≤1 попытка send за вызов).
|
||||
- **AC-14.** `update_task_tracker` никогда не выбрасывает исключение ни в одном режиме (контракт «never raises») при любых сбоях БД/сети/Telegram.
|
||||
|
||||
## Текстовые правки (оба режима)
|
||||
- **AC-15.** Метка «Подтверждение BRD» присутствует в карточке там, где раньше была «Ревью БРД»; строки «Ревью БРД» в выводе нет.
|
||||
- **AC-16.** После прохождения approve-gate (зафиксированы `brd_review_started_at` и `brd_review_ended_at`) строка подтверждения BRD начинается с ✅ (не ⏸️). Пока ждём человека (`brd_review_ended_at` пуст) — индикатор ожидания/⏳ сохраняется (не ✅).
|
||||
- **AC-17.** Метки стадий в карточке русские: `Анализ`, `Архитектура`, `Разработка`, `Код ревью`, `Тестирование`, `Внедрение`. Английских меток (`Analysis`/`Architecture`/`Development`/`Review`/`Testing`/`Deploy`) в выводе нет — ни в «✅ …»-строках, ни в «🔄 … идёт».
|
||||
- **AC-18.** Итоговая строка готовой задачи содержит «📦 Внедрено» (не «deployed»).
|
||||
|
||||
## Регрессия и качество
|
||||
- **AC-19.** Состав отдельных пингов не изменён: `notify_approve_requested` шлёт ровно один НЕтихий пинг и стартует BRD-часы; `notify_error` — один НЕтихий пинг; `notify_stage_change` / `notify_agent_started` / `notify_qg_failure` — НЕ шлют отдельных сообщений (только refresh трекера).
|
||||
- **AC-20.** Вся существующая и новая pytest-сюита зелёная (`pytest tests/ -q`). Существующие ассерты в `tests/test_telegram_tracker.py` обновлены под русские метки и «Подтверждение BRD».
|
||||
- **AC-21.** Документация обновлена в ТОМ ЖЕ PR: `CHANGELOG.md`, `docs/architecture/internals.md` (режимы + `ORCH_TRACKER_MODE` + `delete_telegram`), `.env.example` (`ORCH_TRACKER_MODE`). Отсутствие — REQUEST_CHANGES на ревью.
|
||||
</content>
|
||||
@@ -1,160 +0,0 @@
|
||||
work_item: ORCH-042
|
||||
description: >
|
||||
Режим bump live-трекера (delete+send+repoint, тихо, fallback, never-raises),
|
||||
сохранение режима edit без регрессий, и текстовые правки карточки
|
||||
(Подтверждение BRD, ✅ после approve, русские метки стадий, «Внедрено»).
|
||||
Сеть не трогаем: httpx / низкоуровневые helpers мокаются; изолированная temp-БД.
|
||||
|
||||
tests:
|
||||
# --- config ---
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "Settings.tracker_mode по умолчанию 'edit' и читается из ORCH_TRACKER_MODE (AC-1)"
|
||||
module: tests/test_config.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "Неизвестное/пустое значение режима -> update_task_tracker идёт по edit-ветке, без исключений (AC-2)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
# --- edit mode regression ---
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "edit: первый вызов -> sendMessage тихо, id сохранён, editMessageText не вызван (AC-3)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "edit: повторный вызов -> editMessageText на сохранённый id, нового send нет (AC-4)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "edit: EDIT_GONE -> отправка нового, id обновлён (AC-5)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "edit: EDIT_NOT_MODIFIED и EDIT_FAILED -> нового сообщения нет, id не меняется (AC-6)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
# --- bump mode ---
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "bump: первый вызов (нет id) -> delete не вызван, send тихий, id сохранён (AC-7, AC-9)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "bump: повторный вызов -> delete(старый) затем send(тихо), id перенаправлен на новый, порядок delete->send (AC-8, AC-9, AC-10)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "bump fallback: delete_telegram->False -> новое всё равно отправлено, id обновлён, без исключений (AC-11)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "bump: send вернул None (транзиент) -> id не затёрт на None, ровно одна попытка send, без исключений (AC-13)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "bump: одна карточка за вызов -> send_telegram вызван <=1 раза (AC-10)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
# --- delete_telegram classification ---
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "delete_telegram: ok:true -> True (httpx замокан)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: "delete_telegram: ok:false 'message to delete not found' / 'message can't be deleted' / 'message_id_invalid' -> True (AC-12)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: "delete_telegram: неизвестный ok:false / 5xx -> False (AC-12)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: unit
|
||||
description: "delete_telegram: исключение (таймаут/сеть) -> False, never raises (AC-12, AC-14)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: "delete_telegram: нет токена/chat_id -> False, HTTP не вызывается (AC-12)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
# --- never raises ---
|
||||
- id: TC-17
|
||||
type: unit
|
||||
description: "update_task_tracker никогда не бросает (DB/сеть сбой) в обоих режимах (AC-14)"
|
||||
module: tests/test_tracker_bump.py
|
||||
expected: PASS
|
||||
|
||||
# --- text changes ---
|
||||
- id: TC-18
|
||||
type: unit
|
||||
description: "render: метка 'Подтверждение BRD' присутствует, 'Ревью БРД' отсутствует (AC-15)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-19
|
||||
type: unit
|
||||
description: "render: approve-gate пройден (brd_review_ended_at задан) -> строка BRD с ✅, не ⏸️ (AC-16)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-20
|
||||
type: unit
|
||||
description: "render: ожидание человека (brd_review_ended_at пуст) -> индикатор ожидания/⏳, не ✅ (AC-16)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-21
|
||||
type: unit
|
||||
description: "render: русские метки стадий (Анализ/Архитектура/Разработка/Код ревью/Тестирование/Внедрение), английских нет — в ✅- и 🔄-строках (AC-17)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-22
|
||||
type: unit
|
||||
description: "render done: итоговая строка содержит '📦 Внедрено', не 'deployed' (AC-18)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
# --- separate alerts regression ---
|
||||
- id: TC-23
|
||||
type: unit
|
||||
description: "Состав отдельных пингов не изменён: approve-gate/error шлют 1 нетихий пинг; stage_change/agent_started/qg_failure не шлют (AC-19)"
|
||||
module: tests/test_telegram_tracker.py
|
||||
expected: PASS
|
||||
|
||||
# --- full suite ---
|
||||
- id: TC-24
|
||||
type: integration
|
||||
description: "Вся pytest-сюита зелёная; обновлённые ассерты под русские метки проходят (AC-20)"
|
||||
module: tests/
|
||||
expected: PASS
|
||||
</content>
|
||||
@@ -1,85 +0,0 @@
|
||||
# ADR-001: Режим bump live-трекера через delete+send+repoint, edit как дефолт
|
||||
|
||||
**Work Item:** ORCH-042 · См. `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `10-tech-risks.md`.
|
||||
|
||||
## Статус
|
||||
Accepted
|
||||
|
||||
## Контекст
|
||||
|
||||
Live-tracker (`src/notifications.py`, ветка `feat/telegram-live-tracker`, Variant B+) держит **ОДНУ** карточку на задачу и редактирует её на месте (`editMessageText`) на каждом переходе стадии. Это сознательно убило прежнюю боль — «~15 отдельных карточек/дублей на задачу». Защита от дублей — главный инвариант компонента и не должна регрессировать.
|
||||
|
||||
Побочный эффект edit-режима: при активной переписке в чате карточка «тонет» вверху истории — актуальный статус задачи приходится искать скроллом. Слава просит альтернативу: карточка должна всегда быть последней в чате, но без возврата дублей и без звона на каждой стадии.
|
||||
|
||||
Дополнительно — косметика текста карточки (смесь EN-меток стадий с RU-текстом, «Ревью БРД», технический хвост `deployed`). Текстовые правки тривиальны и сами по себе архитектурного решения не требуют; ключевое решение — как реализовать новый режим, не сломав инвариант «одна карточка».
|
||||
|
||||
Ограничения окружения (см. `CLAUDE.md`, `docs/operations/INFRA.md`):
|
||||
- Контракт компонента: `update_task_tracker` и low-level helpers **никогда не бросают** (сбой нотификации не должен валить конвейер).
|
||||
- Self-hosting: правка инструмента, который сейчас в проде и обслуживает другие проекты из общей БД/очереди. Прод-рестарт self — только через `deploy-staging` (8501).
|
||||
- Telegram Bot API: `deleteMessage` не работает для сообщений старше 48 ч и для уже удалённых/недоступных — это нормальный ожидаемый исход, а не ошибка.
|
||||
|
||||
## Решение
|
||||
|
||||
### Р-1. Поведение задаётся конфиг-флагом, дефолт `edit` (нулевая регрессия)
|
||||
Новое поле `Settings.tracker_mode` (env `ORCH_TRACKER_MODE`), значения `edit` | `bump`, **дефолт `edit`**. Резолюция режима — в `notifications`, case-insensitive + trim; всё, что не равно `"bump"` (включая пустое/мусор/None), трактуется как `edit`. Без явного включения bump поведение неотличимо от текущего → нулевая регрессия и безопасный фолбэк (оркестратор не падает на любом значении флага).
|
||||
|
||||
### Р-2. Режим bump = delete + send + repoint, инвариант «одна карточка» сохраняется иначе
|
||||
edit-режим держит одну карточку, *редактируя* её. bump держит одну карточку, *пересоздавая* её внизу:
|
||||
1. если сохранён `tracker_message_id` — best-effort `delete_telegram(старый_id)`;
|
||||
2. `send_telegram(text, disable_notification=True)` — новая карточка внизу, тихо;
|
||||
3. при успехе (`new_mid is not None`) — `set_tracker_message_id` перенаправляется на новый id.
|
||||
|
||||
Итог: в чате всегда ровно одна карточка задачи, и она всегда последняя. За **один** вызов `update_task_tracker` отправляется **не более одного** нового сообщения → дублей в пределах вызова нет.
|
||||
|
||||
### Р-3. delete — best-effort, никогда не блокирует отправку новой карточки
|
||||
Новый low-level helper `delete_telegram(message_id) -> bool` с контрактом «never raises». Семантика возврата — «исчезло ли старое сообщение»:
|
||||
- `ok:true` → `True`;
|
||||
- `ok:false` с маркерами «уже нет / нельзя удалить» (`message to delete not found`, `message can't be deleted`, `message_id_invalid`, вынести в константу `_DELETE_GONE_MARKERS`) → `True` (не транзиент, сообщение и так недоступно);
|
||||
- прочий `ok:false` / 5xx / исключение (сеть/таймаут) → `False` + `logger.warning`;
|
||||
- нет токена/chat_id → `False`, HTTP не выполняется.
|
||||
|
||||
**Результат `delete_telegram` НЕ влияет на решение отправлять новую карточку** — её шлём всегда (BR-6: delete-fail у сообщения >48 ч → всё равно новое). `False` означает лишь «старое, возможно, ещё живо»; на следующем переходе оно будет удалено повторно (или уже мёртво). Накопления карточек это не даёт, т.к. указатель всегда хранит ровно один id.
|
||||
|
||||
### Р-4. repoint только при успешном send (анти-затирание указателя)
|
||||
`set_tracker_message_id` вызывается **только** при `new_mid is not None`. Если send вернул None (нет кредов / транзиент 5xx/таймаут) — id **не трогаем** (не затираем на None): карточка перерисуется на следующем переходе, дубля нет (≤1 попытка send за вызов). Это симметрично существующему edit-fallback, который тоже не плодит сообщения при транзиенте.
|
||||
|
||||
### Р-5. bump всегда тихий
|
||||
Новая карточка отправляется с `disable_notification=True` — всплывает внизу, но без звука/пинга, как и edit сейчас. Состав отдельных НЕтихих пингов (approve-gate / error / deploy-fail / agent-fail) не меняется (вне scope).
|
||||
|
||||
### Р-6. Текстовые правки — в одной точке, общие для обоих режимов
|
||||
Правки (`_BRD_LABEL` → «Подтверждение BRD»; ✅ вместо ⏸️ после approve-gate; русские display-labels в `_TRACKER_STAGES`; `_done_link` → «Внедрено») затрагивают только **отображаемые** строки. Ключи стадий (`analysis`, …) и имена агентов (`analyst`, …) НЕ меняются — они завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД. Правка `_TRACKER_STAGES` в одном месте автоматически русифицирует и «✅ …», и «🔄 … идёт».
|
||||
|
||||
### Что НЕ меняется (границы решения)
|
||||
- БД: миграций нет, используется существующая колонка `tasks.tracker_message_id` и хелперы `get_tracker_message_id` / `set_tracker_message_id`. → `08-data-requirements.md` не требуется.
|
||||
- Инфраструктура / топология / порты / контейнеры — без изменений. → `07-infra-requirements.md` не требуется.
|
||||
- State machine (`src/stages.py`), реестр QG (`src/qg/checks.py`), стадии, компоненты — без изменений. → глобальный (cross-cutting) ADR не требуется, решение локально для компонента notifications.
|
||||
- Сигнатуры `send_telegram` / `edit_telegram` / `update_task_tracker` — без изменений (внешние вызовы из `launcher`/`stage_engine` не трогаются).
|
||||
- Новых зависимостей нет (`httpx` уже используется).
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **A1. Только bump, без флага.** Отклонено: ломает обратную совместимость и единственного пользователя (Слава может предпочесть edit); рост риска регрессии защиты от дублей. Флаг с дефолтом `edit` даёт мгновенный откат.
|
||||
- **A2. Pin-сообщение (закрепить карточку).** Отклонено: pin не решает «карточка внизу при переписке», шлёт системное уведомление о закреплении (звон), и усложняет API-контракт. Вне духа «тихого» трекера.
|
||||
- **A3. send-then-delete (сначала новое, потом удалить старое).** Отклонено как дефолтный порядок: в окне между send и delete в чате видны ДВЕ карточки; при падении на delete остаётся осиротевшая старая → визуальный дубль. delete-then-send гарантирует ≤1 карточку в любой момент при нормальном пути и ≤1 *новую* отправку за вызов в любом случае.
|
||||
- **A4. Хранить историю/несколько карточек.** Вне scope и противоречит исходному инварианту «одна карточка».
|
||||
|
||||
## Последствия
|
||||
|
||||
**Плюсы**
|
||||
- Слава получает актуальную карточку всегда внизу чата, одну на задачу, без звона.
|
||||
- Нулевая регрессия по умолчанию (edit), мгновенный откат флагом.
|
||||
- Контракт «never raises» и инвариант «одна карточка» сохранены в обоих режимах.
|
||||
- Изменения локальны (`config.py` + `notifications.py`), без миграций и без рестарта-критичных зависимостей.
|
||||
|
||||
**Минусы / ограничения**
|
||||
- bump расходует Telegram API на 2 запроса вместо 1 (delete + send) на переход — для одного получателя несущественно (rate-limit Telegram не угрожает).
|
||||
- При транзиентном delete-fail возможна кратко осиротевшая старая карточка до следующего перехода (она будет вычищена попыткой delete на следующем апдейте) — приемлемо, дублей всё равно не плодит.
|
||||
- bump теряет визуальную «эволюцию на месте» edit-режима (история чата получает по карточке-замене) — но в чате всегда одна актуальная, что и требуется.
|
||||
|
||||
**Риски** — см. `10-tech-risks.md`.
|
||||
|
||||
## Связи
|
||||
- BRD/ТЗ/AC: `docs/work-items/ORCH-042/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`; тест-план `04-test-plan.yaml`.
|
||||
- Компонент: live-tracker (`src/notifications.py`), `feat/telegram-live-tracker` (Variant B+).
|
||||
- Контекст self-hosting / staging-страховка: `CLAUDE.md`, `docs/operations/INFRA.md`, `docs/architecture/adr/adr-0003-staging-gate.md`.
|
||||
- Обновляемая дока (в том же PR, стадия development): `CHANGELOG.md`, `docs/architecture/internals.md` (секция live-tracker: режимы + `ORCH_TRACKER_MODE` + `delete_telegram`), `.env.example`.
|
||||
@@ -1,21 +0,0 @@
|
||||
# 10 — Технические риски: ORCH-042
|
||||
|
||||
См. `02-trz.md`, `06-adr/ADR-001-tracker-bump-mode.md`, `03-acceptance-criteria.md`.
|
||||
|
||||
Шкала: Вероятность × Влияние ∈ {низк., сред., выс.}.
|
||||
|
||||
| # | Риск | Вер. | Влияние | Митигация | Контроль (AC/TC) |
|
||||
|---|------|------|---------|-----------|-------------------|
|
||||
| R-1 | **Регрессия защиты от дублей** — рефактор `update_task_tracker` ломает edit-ветку, возвращается боль «~15 карточек». | низк. | выс. | edit — дефолт и неизменяемая ветка; bump добавляется отдельной веткой `if mode == "bump"`, edit-код не трогается. Полное покрытие edit-регрессии тестами. | AC-3..AC-6, AC-8; TC-03..TC-06, TC-24 |
|
||||
| R-2 | **Двойная отправка / накопление карточек в bump** — delete и send рассинхронизированы, в чате >1 карточки. | низк. | сред. | Инвариант: ≤1 `send_telegram` за вызов; `set_tracker_message_id` только при успешном send; delete best-effort и не блокирует. | AC-8, AC-10, AC-11; TC-08, TC-09, TC-11 |
|
||||
| R-3 | **Затирание `tracker_message_id` на None** при транзиентном send-fail → потеря указателя, следующий апдейт не найдёт старое. | низк. | сред. | repoint только при `new_mid is not None`; при None id сохраняется как есть. | AC-13; TC-10 |
|
||||
| R-4 | **Нарушение контракта «never raises»** — исключение из `delete_telegram`/новой ветки валит конвейер (групповой риск из-за общей очереди). | низк. | выс. | `delete_telegram` обёрнут try/except → bool; внешний try/except в `update_task_tracker` сохранён; сеть/httpx мокаются в тестах. | AC-12, AC-14; TC-12..TC-17 |
|
||||
| R-5 | **Ложная классифик. delete-ответа** — неизвестный `ok:false` принят за «исчезло» (или наоборот), вечные ретраи/тишина. | низк. | низк. | Явные `_DELETE_GONE_MARKERS` → True; всё прочее (включая 5xx) → False; повтор delete на следующем апдейте безопасен (идемпотентно). | AC-12; TC-13, TC-14 |
|
||||
| R-6 | **Падение CI на старых ассертах** — тесты `tests/test_telegram_tracker.py` проверяют EN-метки/«Ревью БРД». | сред. | сред. | ТЗ §5 явно требует обновить существующие ассерты под русские метки и «Подтверждение BRD» в том же PR. | AC-20; TC-18, TC-21, TC-24 |
|
||||
| R-7 | **Сломанная human-gate индикация** — ✅ показан до прохождения approve-gate (ввод в заблуждение). | низк. | низк. | ✅ только при заданном `brd_review_ended_at`; ветка ожидания (`review_seconds is None`, ⏳) не меняется. | AC-16; TC-19, TC-20 |
|
||||
| R-8 | **Скрытая зависимость от display-label** — русификация `_TRACKER_STAGES` ломает логику, завязанную на текст метки. | низк. | сред. | Меняется только 2-й элемент кортежа (label); ключи стадий и имена агентов (`_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются. | AC-17; TC-21 |
|
||||
| R-9 | **Self-hosting: прод-сбой при выкатке self** — общая БД/очередь, рестарт орка останавливает все проекты. | низк. | выс. | Изменения только в коде нотификаций, миграций БД нет; обязательная страховка `deploy-staging` (8501) перед prod (CLAUDE.md, INFRA.md, adr-0003). Дефолт edit → даже при выкатке поведение не меняется без явного флага. | стадия deploy-staging; `check_staging_status` |
|
||||
| R-10 | **Документация не обновлена** в том же PR (internals.md / .env.example / CHANGELOG) → REQUEST_CHANGES. | сред. | низк. | ТЗ §5 и AC-21 фиксируют список; reviewer проверяет наличие. | AC-21 |
|
||||
|
||||
## Сводный вывод
|
||||
Все риски — **низкие по вероятности** при соблюдении инвариантов из ADR-001 (edit-дефолт, ≤1 send/вызов, repoint-only-on-success, never-raises, правка только display-label). Остаточный групповой self-hosting-риск (R-9) полностью покрывается обязательным `deploy-staging`-гейтом и тем, что дефолтное поведение не меняется. Блокеров для перехода на стадию development нет.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-042
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-042
|
||||
|
||||
## Summary
|
||||
Telegram live-tracker: добавлен режим `bump` (`ORCH_TRACKER_MODE` / `Settings.tracker_mode`, дефолт `edit`) + русификация и косметика карточки. Реализация точно соответствует `02-trz.md` и `06-adr/ADR-001-tracker-bump-mode.md`. Все 21 критерий приёмки покрыты; `pytest tests/ -q` — **494 passed**. Документация обновлена в том же PR. Замечаний уровня P0/P1/P2 нет.
|
||||
|
||||
## Проверка по осям
|
||||
|
||||
### 1. Соответствие ТЗ
|
||||
- `Settings.tracker_mode = "edit"` + env `ORCH_TRACKER_MODE` — есть (config.py).
|
||||
- `delete_telegram(message_id) -> bool` — контракт «never raises», `_DELETE_GONE_MARKERS` вынесены в константу, классификация ok/gone/transient/no-creds реализована дословно по ТЗ §3.1.
|
||||
- Ветвление `update_task_tracker`: bump = delete(best-effort) → send(silent) → repoint только при `new_mid is not None`; edit-ветка сохранена без изменений (§3.2). Инварианты bump (≤1 send/вызов, анти-затирание указателя, delete не блокирует send, всегда тихо) соблюдены.
|
||||
- Текстовые правки BR-9..BR-12 (`_BRD_LABEL`→«Подтверждение BRD», ✅ вместо ⏸️ после approve-gate, русские display-labels `_TRACKER_STAGES`, `_done_link`→«Внедрено») — на месте; ключи стадий и имена агентов не тронуты.
|
||||
- БД, API, сигнатуры helpers, зависимости — без изменений (как и требовалось).
|
||||
|
||||
### 2. Соответствие ADR (ADR-001)
|
||||
Реализация соответствует решениям Р-1..Р-6: флаг с дефолтом edit (нулевая регрессия), delete+send+repoint, best-effort delete, repoint только при успешном send, всегда тихий bump, текст в одной точке. Выбран порядок delete-then-send (A3 отклонён обоснованно). Глобальные ADR не нарушены; решение локально для компонента notifications, что зафиксировано в ADR.
|
||||
|
||||
### 3. Качество кода
|
||||
- Defensive-контракты «never raises» соблюдены и в helper, и в `update_task_tracker`.
|
||||
- Docstrings содержательные; логирование (`debug`/`warning`) корректно разнесено по случаям.
|
||||
- Security/утечек нет; новых зависимостей нет.
|
||||
|
||||
### 4. Качество тестов
|
||||
- `tests/test_config.py` (AC-1), `tests/test_tracker_bump.py` (AC-7..AC-14: ордеринг delete→send, delete-fail, send=None, ≤1 send, классификация delete_telegram, never-raises), `tests/test_telegram_tracker.py` (AC-2 garbage→edit, AC-15..AC-18 русификация, регрессия edit).
|
||||
- Существующие англоязычные ассерты обновлены под русские метки и «Подтверждение BRD» (AC-20).
|
||||
- Тесты содержательные, не тривиальные. `pytest tests/ -q` → 494 passed.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- нет
|
||||
|
||||
### P1 — Must fix
|
||||
- нет
|
||||
|
||||
### P2 — Should fix
|
||||
- нет
|
||||
|
||||
### P3 — Nice to have
|
||||
- [ ] В `_TRACKER_STAGES` строчные комментарии-дубли (`# Анализ` и т.п.) после уже русских меток избыточны — косметика, на поведение не влияет.
|
||||
|
||||
## Документация
|
||||
Обновлена в том же PR, полностью соответствует AC-21:
|
||||
- `CHANGELOG.md` — записи в `[Unreleased] / Added` (bump-режим + `delete_telegram`) и `Changed` (русификация). ✅
|
||||
- `docs/architecture/internals.md` — новая секция «Live Telegram tracker»: режимы edit/bump (таблица), `ORCH_TRACKER_MODE`, контракт `delete_telegram`, текстовые правки. ✅
|
||||
- `.env.example` — `ORCH_TRACKER_MODE=edit` с комментарием. ✅
|
||||
- ADR заведён: `06-adr/ADR-001-tracker-bump-mode.md`. ✅
|
||||
|
||||
Изменения `src/` (config.py, notifications.py) полностью отражены в документации — правило «документация = golden source» выполнено.
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-042
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-042
|
||||
|
||||
Telegram live-tracker: режим `bump` (delete+send+repoint, тихо, fallback, never-raises),
|
||||
сохранение режима `edit` без регрессий, русификация карточки.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Ветка: feature/ORCH-042-telegram-live-tracker-bump
|
||||
- Дата: 2026-06-06
|
||||
- Prod orchestrator (8500): `/health` → `{"status":"ok"}`, активна задача #40 (ORCH-042, stage=testing)
|
||||
|
||||
## Smoke test API
|
||||
| Endpoint | Результат |
|
||||
|----------|-----------|
|
||||
| GET /health | PASS — `{"status":"ok","service":"orchestrator"}` |
|
||||
| GET /status | PASS — активная задача ORCH-042 (stage=testing) |
|
||||
| GET /queue | PASS — queued:0 running:1 done:99 failed:0, breaker=closed |
|
||||
|
||||
(`curl` в окружении недоступен — smoke выполнен через `urllib`.)
|
||||
|
||||
## Результаты по тест-плану (04-test-plan.yaml)
|
||||
|
||||
| TC ID | Описание | AC | Результат |
|
||||
|-------|----------|----|-----------|
|
||||
| TC-01 | Settings.tracker_mode дефолт 'edit', читается из ORCH_TRACKER_MODE | AC-1 | PASS |
|
||||
| TC-02 | Мусорное/пустое значение → edit-ветка, без исключений | AC-2 | PASS |
|
||||
| TC-03 | edit: первый вызов → send тихо, id сохранён, edit не вызван | AC-3 | PASS |
|
||||
| TC-04 | edit: повтор → editMessageText на сохранённый id, нового send нет | AC-4 | PASS |
|
||||
| TC-05 | edit: EDIT_GONE → отправка нового, id обновлён | AC-5 | PASS |
|
||||
| TC-06 | edit: EDIT_NOT_MODIFIED/EDIT_FAILED → нового нет, id не меняется | AC-6 | PASS |
|
||||
| TC-07 | bump: первый вызов → delete не вызван, send тихий, id сохранён | AC-7,9 | PASS |
|
||||
| TC-08 | bump: повтор → delete(старый)→send(тихо)→repoint, порядок соблюдён | AC-8,9,10 | PASS |
|
||||
| TC-09 | bump fallback: delete→False → новое всё равно отправлено | AC-11 | PASS |
|
||||
| TC-10 | bump: send=None → id не затёрт, ≤1 send | AC-13 | PASS |
|
||||
| TC-11 | bump: одна карточка за вызов (send ≤1) | AC-10 | PASS |
|
||||
| TC-12 | delete_telegram: ok:true → True | AC-12 | PASS |
|
||||
| TC-13 | delete_telegram: gone-маркеры → True | AC-12 | PASS |
|
||||
| TC-14 | delete_telegram: неизвестный ok:false / 5xx → False | AC-12 | PASS |
|
||||
| TC-15 | delete_telegram: исключение → False, never raises | AC-12,14 | PASS |
|
||||
| TC-16 | delete_telegram: нет кредов → False, HTTP не вызван | AC-12 | PASS |
|
||||
| TC-17 | update_task_tracker never raises (оба режима) | AC-14 | PASS |
|
||||
| TC-18 | render: «Подтверждение BRD» есть, «Ревью БРД» нет | AC-15 | PASS |
|
||||
| TC-19 | render: approve-gate пройден → строка BRD с ✅ | AC-16 | PASS |
|
||||
| TC-20 | render: ожидание человека → ⏳, не ✅ | AC-16 | PASS |
|
||||
| TC-21 | render: русские метки стадий, английских нет | AC-17 | PASS |
|
||||
| TC-22 | render done: «📦 Внедрено», не «deployed» | AC-18 | PASS |
|
||||
| TC-23 | состав отдельных пингов не изменён | AC-19 | PASS |
|
||||
| TC-24 | вся pytest-сюита зелёная | AC-20 | PASS |
|
||||
|
||||
Все 24 тест-кейса плана покрыты и пройдены. Критерии AC-1..AC-20 подтверждены
|
||||
тестами; AC-21 (документация) подтверждён на ревью (12-review.md, verdict APPROVED).
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
Целевые модули ORCH-042:
|
||||
```
|
||||
tests/test_config.py tests/test_telegram_tracker.py tests/test_tracker_bump.py
|
||||
52 passed, 1 warning in 1.38s
|
||||
```
|
||||
|
||||
Полный регресс:
|
||||
```
|
||||
======================== 494 passed, 1 warning in 8.57s ========================
|
||||
```
|
||||
|
||||
(Единственный warning — PydanticDeprecatedSince20 в `src/config.py:4`, не связан с
|
||||
ORCH-042, существовал ранее, на результат не влияет.)
|
||||
|
||||
## Итог
|
||||
**PASS** — полный регресс 494/494 зелёный, целевые модули 52/52 PASS, smoke API OK.
|
||||
Задача готова к стадии deploy-staging.
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
timestamp: 2026-06-06T10:20:38Z
|
||||
work_item: ORCH-042
|
||||
branch: feature/ORCH-042-telegram-live-tracker-bump
|
||||
commit: 753eea37fc9b0b7bffd9f896ae8149f5a515fc26
|
||||
target_service: orchestrator
|
||||
target_port: 8500
|
||||
deploy_mode: artifact-only
|
||||
staging_gate: SUCCESS
|
||||
prod_container_restarted: false
|
||||
rebuild_required: true
|
||||
---
|
||||
|
||||
# Deploy Log — ORCH-042
|
||||
|
||||
## Verdict
|
||||
|
||||
**`deploy_status: SUCCESS`** — артефактный (artifact-only) деплой-вердикт.
|
||||
|
||||
Реальный `git pull` + `docker compose ... --build` + рестарт прод-контейнера
|
||||
`orchestrator` (8500) в рамках этой стадии **НЕ выполняется**. Он делегирован
|
||||
хуку `scripts/orchestrator-deploy-hook.sh` (ORCH-36), который запускается
|
||||
Владельцем **после** мерджа ветки `feature/ORCH-042-telegram-live-tracker-bump`
|
||||
в `main`. Guardrail: агент никогда не перезапускает общий прод-инстанс внутри
|
||||
ORCH-задачи — это self-hosting групповой риск (CLAUDE.md / INFRA.md
|
||||
§Self-hosting): рестарт прод-орка остановил бы конвейер ВСЕХ проектов.
|
||||
|
||||
## Pre-conditions (все ✓)
|
||||
|
||||
| Артефакт | Поле | Значение |
|
||||
|----------|------|----------|
|
||||
| `12-review.md` | `verdict` | `APPROVED` |
|
||||
| `13-test-report.md` | `result` | `PASS` |
|
||||
| `15-staging-log.md` | `staging_status` | `SUCCESS` (10/10 staging-checks, прогон внутри `orchestrator-staging` :8501) |
|
||||
| `04-test-plan.yaml` | — | покрывает AC задачи |
|
||||
| ADR | `06-adr/ADR-001-tracker-bump-mode.md` | заведён |
|
||||
| `CHANGELOG.md` | — | обновлён |
|
||||
|
||||
Стадия `deploy` достижима только потому, что условный staging-гейт
|
||||
(`check_staging_status`, реальный для self-hosting repo=orchestrator) — зелёный.
|
||||
|
||||
## Change scope — почему нужен rebuild+restart (но не сейчас)
|
||||
|
||||
ORCH-042 меняет **рантайм-код `src/`**, который копируется в образ (`/app/src`)
|
||||
и исполняется прод-процессом — значит для вступления в силу на проде нужен
|
||||
rebuild + restart контейнера:
|
||||
|
||||
| Файл | Тип | Как доезжает до прода |
|
||||
|------|-----|------------------------|
|
||||
| `src/notifications.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
|
||||
| `src/config.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
|
||||
| `.env.example` | дескриптор | реальные значения — в `.env` на хосте (не в гит) |
|
||||
| `docs/**`, `CHANGELOG.md` | docs | мерж в `main` |
|
||||
| `tests/**` | тесты, не деплоятся | n/a |
|
||||
|
||||
`rebuild_required: true`. Изменения добавляют режим **bump** live-tracker'а
|
||||
Telegram (карточка перемещается вниз при обновлении) + русификацию текста
|
||||
уведомлений; они активируются новыми env-флагами (см. `.env.example`).
|
||||
Чтобы новое поведение вступило в силу на проде, прод-инстанс `orchestrator`
|
||||
(8500) должен быть **пересобран и перезапущен Владельцем через деплой-хук
|
||||
после мерджа** — не данным агентом.
|
||||
|
||||
## Deploy-хук (выполняет Владелец после мерджа в main)
|
||||
|
||||
```bash
|
||||
# на хосте mva154, прод-таргет (порт 8500, profile отсутствует → default)
|
||||
TARGET_SERVICE=orchestrator \
|
||||
TARGET_PORT=8500 \
|
||||
TARGET_IMAGE=orchestrator-orchestrator \
|
||||
COMPOSE_PROFILE= \
|
||||
scripts/orchestrator-deploy-hook.sh --deploy
|
||||
```
|
||||
|
||||
Хук: снимает снапшот текущего образа → `git pull origin main` → перезапуск
|
||||
сервиса → health-check (10×6s, до 60s по `GET /health`) → при провале
|
||||
**авто-rollback** на предыдущий образ. Прод-env-флаги bump-режима выставляются
|
||||
в `.env` на хосте до перезапуска.
|
||||
|
||||
> ⚠️ Self-hosting: rebuild прод-орка = групповой риск (общая БД + очередь с
|
||||
> enduro-trails). Деплой проводить в окно низкой активности конвейера;
|
||||
> страховка — авто-rollback хука и зелёный staging-гейт (8501).
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-06T10:19:10+00:00
|
||||
base_url: http://localhost:8501
|
||||
work_item: ORCH-042
|
||||
mode: stub
|
||||
checks: 10/10 PASS
|
||||
---
|
||||
|
||||
# Staging Gate Log — ORCH-042
|
||||
|
||||
Staging test suite completed against the live staging environment
|
||||
(`orchestrator-staging`, port 8501). All checks passed.
|
||||
|
||||
## Execution
|
||||
|
||||
Canonical procedure (ORCH-048, ADR-001): run **inside** the
|
||||
`orchestrator-staging` container so the B6 registry-isolation check reads the
|
||||
registry from the running instance's own process-env (`.env.staging`).
|
||||
|
||||
```
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
|
||||
(Executed via the Docker Engine API over the mounted unix socket, since no
|
||||
docker CLI is present in the agent environment; equivalent to the canonical
|
||||
`docker exec`.)
|
||||
|
||||
**Exit code: 0 → staging_status: SUCCESS**
|
||||
|
||||
## Results — 10/10 PASS
|
||||
|
||||
### Block A — SMOKE
|
||||
- ✓ A1 GET /health → 200 status=ok
|
||||
- ✓ A2 GET /queue → 200 with counts/max_concurrency/resilience
|
||||
- ✓ A3 ORCH_STAGING=true (not prod)
|
||||
|
||||
### Block B — ACCESS
|
||||
- ✓ B4 Plane: sandbox project accessible (5 projects, sandbox=YES)
|
||||
- ✓ B5 Gitea: orchestrator-sandbox accessible, push=true
|
||||
- ✓ B6 Registry: sandbox present, prod ET/ORCH absent (isolation confirmed)
|
||||
|
||||
### Block C — E2E (mode=stub)
|
||||
- ✓ C7 Create issue in Plane SANDBOX (HTTP 201)
|
||||
- ✓ C8 Trigger pipeline via /webhook/plane (HTTP 200, HMAC)
|
||||
- ✓ C9a Branch appears in orchestrator-sandbox
|
||||
- ✓ C9b Analyst job enqueued in staging queue
|
||||
|
||||
### Cleanup
|
||||
- ✓ Branch deleted, Plane issue deleted, staging DB job/task rows removed.
|
||||
|
||||
```
|
||||
============================================================
|
||||
RESULT: 10/10 checks PASS
|
||||
============================================================
|
||||
```
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Безопасная параллель в одном репо: merge-gate + auto-rebase + re-test
|
||||
|
||||
Work Item ID: ORCH-043
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,114 +0,0 @@
|
||||
# 01 — Business Requirements Document (BRD)
|
||||
|
||||
**Work Item:** ORCH-043
|
||||
**Тема:** Безопасная параллель в одном репо: merge-gate + auto-rebase + re-test
|
||||
**Проект:** orchestrator (self-hosting)
|
||||
**Автор:** Analyst
|
||||
**Дата:** 2026-06-06
|
||||
|
||||
---
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
Оркестратор ведёт несколько work item **параллельно**, каждый в своём изолированном
|
||||
git worktree / ветке (`feature/ORCH-NNN-slug`, ORCH-2/S-4). Все ветки одного проекта
|
||||
исходят из общего `origin/main` и в конце конвейера **вливаются обратно в `main`**.
|
||||
|
||||
Текущий конвейер валидирует ветку **относительно того состояния `main`, из которого
|
||||
она была создана**, а не относительно `main` на момент слияния:
|
||||
|
||||
- `check_ci_green` (стадия `development`) — CI зелёный **на ветке** (Gitea commit status ветки).
|
||||
- `check_tests_passed` (стадия `testing`) — вердикт тестировщика по коду **ветки**.
|
||||
- На стадии `deploy` ветка вливается в `main` (слияние выполняет deployer-агент,
|
||||
см. `src/webhooks/gitea.py` — комментарий про «deployer merges the PR at the START of its run»).
|
||||
|
||||
**Между «ветка проверена» и «ветка влита» `main` мог уйти вперёд** из-за слияния другой
|
||||
параллельной задачи. Возникает **семантический (логический) конфликт слияния**: git
|
||||
сливает ветки без текстового конфликта, но объединённый код `main` сломан — тесты,
|
||||
которые были зелёными на ветке, на обновлённом `main` падают.
|
||||
|
||||
### Почему это критично именно здесь (self-hosting)
|
||||
Проект ORCH правит инструмент, который СЕЙЧАС работает в проде и обслуживает другие
|
||||
проекты (enduro-trails) из одного инстанса с общей БД и общей очередью (см. `CLAUDE.md`,
|
||||
`docs/operations/INFRA.md`). Сломанный `main` оркестратора = встал конвейер ВСЕХ проектов.
|
||||
Две параллельные ORCH-задачи, каждая «зелёная» по отдельности, при последовательном
|
||||
слиянии способны положить прод.
|
||||
|
||||
### Сценарий-иллюстрация
|
||||
1. Задачи A и B ответвлены от `main@C0`.
|
||||
2. A проходит конвейер, вливается → `main@C1`.
|
||||
3. B тестировалась против `C0`; её CI зелёный относительно `C0`. Git-слияние B в `C1`
|
||||
проходит без текстового конфликта, но `C1` содержит изменения A, ломающие B.
|
||||
4. `main` становится красным. Конвейер всех проектов деградирует.
|
||||
|
||||
---
|
||||
|
||||
## 2. Цель
|
||||
|
||||
Гарантировать, что ветка вливается в `main` **только если она проверена против
|
||||
актуального `origin/main`**. Перед слиянием ветка автоматически догоняет `main`
|
||||
(auto-rebase) и **повторно тестируется** (re-test); зелёный результат на актуальном
|
||||
`main` — обязательное условие слияния (merge-gate). Слияния в `main` одного репозитория
|
||||
**сериализуются**, чтобы окно гонки не воспроизводилось между двумя гейтами.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
- **Owner / разработчики** — не хотят красный `main` и ручные разборы конфликтов.
|
||||
- **Все проекты на инстансе** — зависят от живого прод-оркестратора.
|
||||
- **Агенты конвейера** — получают детерминированный гейт вместо ручной координации.
|
||||
|
||||
## 4. Объём (Scope)
|
||||
|
||||
### В объёме
|
||||
1. **Merge-gate** — детерминированный гейт перед слиянием в `main`: пропускает
|
||||
слияние только если ветка не отстаёт от `origin/main` И повторная проверка зелёная.
|
||||
2. **Auto-rebase** — если ветка отстаёт от `origin/main`, автоматически догнать `main`
|
||||
(rebase/merge ветки на актуальный `origin/main`) в worktree и запушить результат.
|
||||
3. **Re-test** — после auto-rebase повторно прогнать тест-набор на догнанной ветке;
|
||||
зелёный результат — условие прохода гейта.
|
||||
4. **Сериализация слияний** — в пределах одного репозитория одновременно «догон+слияние»
|
||||
выполняет только одна задача (merge-lock), иначе гонка воспроизводится.
|
||||
5. **Откаты при неуспехе** — текстовый конфликт rebase ИЛИ красный re-test → возврат
|
||||
задачи на `development` (по образцу существующих откатов) с понятным комментарием.
|
||||
6. **Конфигурируемость** — пороги/тайм-ауты re-test и поведение гейта вынесены в `settings`.
|
||||
|
||||
### Вне объёма
|
||||
- Изменение логики стадий `analysis` / `architecture` / `review`.
|
||||
- Замена самого механизма слияния PR в Gitea (UI/настройки репозитория).
|
||||
- Реальные прод-деплои (остаются за `scripts/orchestrator-deploy-hook.sh`).
|
||||
- Кросс-репозиторная сериализация (гейт защищает `main` каждого репо отдельно).
|
||||
|
||||
## 5. Бизнес-требования (BR)
|
||||
|
||||
| ID | Требование |
|
||||
|----|------------|
|
||||
| BR-1 | Перед слиянием ветки в `main` оркестратор обязан проверить, что ветка содержит последний `origin/main` (не отстаёт). |
|
||||
| BR-2 | Если ветка отстаёт — оркестратор автоматически догоняет её до `origin/main` без участия человека (auto-rebase). |
|
||||
| BR-3 | После догона тест-набор повторно прогоняется; слияние разрешено только при зелёном результате (re-test). |
|
||||
| BR-4 | Текстовый конфликт при auto-rebase или красный re-test НЕ приводит к слиянию: задача откатывается на `development` для ручного фикса. |
|
||||
| BR-5 | В пределах одного репозитория «догон+проверка+слияние» сериализуются: две задачи не могут одновременно пройти merge-gate и влиться. |
|
||||
| BR-6 | Гейт детерминированный (Python/гит-команды + код тестов), а не доверие LLM-агенту. |
|
||||
| BR-7 | Гейт обязателен минимум для self-hosting репозитория `orchestrator`; применим к любому репо с параллельными задачами. |
|
||||
| BR-8 | Все события гейта (догон, re-test, проход/откат) логируются и отражаются комментарием в Plane, без рассинхрона стадий. |
|
||||
|
||||
## 6. Критерии успеха
|
||||
- Воспроизводимый ранее сценарий «две зелёные ветки ломают `main`» более не приводит
|
||||
к красному `main`: вторая ветка либо догоняется и проходит re-test, либо откатывается.
|
||||
- Прод-контейнер `orchestrator` не перезапускается и не падает в рамках задачи.
|
||||
- Реестр гейтов и стадий остаётся консистентным (snapshot-тесты обновлены осознанно).
|
||||
|
||||
## 7. Риски и ограничения
|
||||
- **Гонка между двумя гейтами** — снимается merge-lock (BR-5); без него фикс неполон.
|
||||
- **Долгий re-test** — нужен тайм-аут и понятный откат, а не вис задачи.
|
||||
- **Force-push догнанной ветки** — допустим только `--force-with-lease` и только по
|
||||
own-ветке задачи; никогда по `main`.
|
||||
- **Self-hosting** — любые изменения не должны ронять/рестартить прод-оркестратор;
|
||||
обязательная страховка стадией `deploy-staging` (порт 8501) сохраняется.
|
||||
- Окончательное место встройки в конвейер (новая стадия / гейт существующего перехода /
|
||||
шаг перед слиянием) — **решение архитектора** (ADR), BRD фиксирует требуемое поведение.
|
||||
|
||||
## 8. Связанные артефакты
|
||||
- `02-trz.md` — техническое задание (модули, гейт, конфиг, точки встройки).
|
||||
- `03-acceptance-criteria.md` — критерии приёмки PASS/FAIL.
|
||||
- `04-test-plan.yaml` — план тестов.
|
||||
- Контекст кода: `src/qg/checks.py`, `src/stage_engine.py`, `src/git_worktree.py`,
|
||||
`src/agents/launcher.py`, `src/webhooks/gitea.py`, `src/stages.py`, `src/config.py`.
|
||||
@@ -1,161 +0,0 @@
|
||||
# 02 — Техническое задание (ТЗ)
|
||||
|
||||
**Work Item:** ORCH-043
|
||||
**Тема:** merge-gate + auto-rebase + re-test (безопасная параллель в одном репо)
|
||||
**Автор:** Analyst
|
||||
|
||||
> ТЗ описывает ТРЕБУЕМОЕ поведение и конкретные точки изменения кода. Окончательный
|
||||
> выбор места встройки в конвейер (новая стадия vs гейт существующего перехода vs шаг
|
||||
> перед слиянием) и детали reconciliation — **за архитектором** (ADR в `06-adr/`).
|
||||
> Если ТЗ окажется нереализуемым — вернуть на стадию `analysis`, не комментировать задним числом.
|
||||
|
||||
---
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
|
||||
| Модуль | Роль в изменении |
|
||||
|--------|------------------|
|
||||
| `src/merge_gate.py` (**новый**) | Ядро фичи: ancestor-check, auto-rebase, re-test, merge-lock. Чистые функции + git-операции в worktree. |
|
||||
| `src/qg/checks.py` | Новый QG-check `check_branch_mergeable` (merge-gate) + регистрация в `QG_CHECKS`. Переиспользует паттерн `check_tests_local` (pytest в worktree) и `_repo_path`. |
|
||||
| `src/stages.py` | Встройка merge-gate в `STAGE_TRANSITIONS` (точное место — за архитектором; см. §6). |
|
||||
| `src/stage_engine.py` | Ветка отката merge-gate → `development` в `_handle_qg_failure_rollbacks` + диспетчеризация нового check в `_run_qg`. |
|
||||
| `src/git_worktree.py` | Возможные хелперы: проверка «behind origin/main», rebase, push `--force-with-lease`. Не ломать сигнатуры `ensure_worktree` / `get_worktree_path`. |
|
||||
| `src/config.py` | Новые `settings`: тайм-аут re-test, вкл/выкл гейта, политика отстающей ветки, тайм-аут lock. |
|
||||
| `src/agents/launcher.py` | Если merge-gate встраивается как шаг перед слиянием на стадии `deploy` — точка, где deployer запускается, может потребовать координации с lock (за архитектором). |
|
||||
| `tests/` | Новые тесты (см. `04-test-plan.yaml`) + обновление snapshot-тестов реестра/стадий. |
|
||||
|
||||
## 2. Функциональные требования к `src/merge_gate.py`
|
||||
|
||||
Предлагаемый публичный контракт (имена финализирует архитектор; поведение обязательно):
|
||||
|
||||
### 2.1 `branch_is_behind_main(repo, branch) -> bool`
|
||||
- `git fetch origin main` в main-clone/worktree (best-effort, never-raise → трактуем
|
||||
как «не удалось определить» и НЕ пропускаем слияние вслепую).
|
||||
- Ветка считается отстающей, если `origin/main` **не** является предком HEAD ветки
|
||||
(`git merge-base --is-ancestor origin/main <branch>` → ненулевой код).
|
||||
|
||||
### 2.2 `auto_rebase_onto_main(repo, branch) -> (ok: bool, reason: str)`
|
||||
- Выполняется в изолированном worktree ветки (`ensure_worktree`), НЕ в общем clone.
|
||||
- Догнать ветку до `origin/main` (rebase либо merge — выбор архитектора; критично:
|
||||
результат содержит весь `origin/main` и историю/изменения ветки).
|
||||
- **Текстовый конфликт** → отменить операцию (`git rebase --abort` / `git merge --abort`),
|
||||
worktree оставить чистым, вернуть `(False, "rebase conflict: <файлы>")`.
|
||||
- **Чистый догон** → `git push --force-with-lease origin <branch>` (ТОЛЬКО ветка задачи,
|
||||
НИКОГДА `main`). Вернуть `(True, ...)`.
|
||||
- Контракт never-raise: любая git/OS-ошибка → `(False, "<reason>")`, не исключение.
|
||||
|
||||
### 2.3 `retest_branch(repo, branch) -> (ok: bool, reason: str)`
|
||||
- Прогнать тест-набор проекта в worktree догнанной ветки. Канон — как в
|
||||
`check_tests_local`: `python -m pytest` (точная команда/каталог — за архитектором,
|
||||
согласованно с CI-конфигом `.gitea/workflows/`).
|
||||
- Тайм-аут `settings.merge_retest_timeout_s`; превышение → `(False, "re-test timeout")`.
|
||||
- Возврат: `(True, "re-test green")` при коде 0, иначе `(False, "re-test failed: <tail>")`.
|
||||
|
||||
### 2.4 Merge-lock (сериализация, BR-5)
|
||||
- Реализовать межзадачную сериализацию «догон+re-test+слияние» в пределах одного `repo`.
|
||||
- Допустимые реализации (выбор архитектора): файловый lock в `repos_dir`, advisory-lock,
|
||||
либо строка-замок в SQLite. Требования: restart-safe, с тайм-аутом
|
||||
`settings.merge_lock_timeout_s`, корректное освобождение при ошибке/падении.
|
||||
- Под локом: повторно сверить «не отстаёт» ПОСЛЕ захвата (double-check), т.к. `main`
|
||||
мог уйти, пока ждали lock.
|
||||
|
||||
## 3. Новый QG-check (`src/qg/checks.py`)
|
||||
|
||||
```
|
||||
check_branch_mergeable(repo, work_item_id, branch) -> tuple[bool, str]
|
||||
```
|
||||
|
||||
Поведение (детерминированно, без участия LLM):
|
||||
1. Захватить merge-lock для `repo` (с тайм-аутом). Не удалось → `(False, "merge-lock busy")`.
|
||||
2. Если ветка не отстаёт от `origin/main` → `(True, "branch up-to-date with main")`.
|
||||
3. Иначе `auto_rebase_onto_main`:
|
||||
- конфликт → `(False, "rebase conflict: ...")`;
|
||||
- успех → `retest_branch`:
|
||||
- зелёный → `(True, "rebased onto main, re-test green")`;
|
||||
- красный/тайм-аут → `(False, "re-test failed after rebase: ...")`.
|
||||
4. Освободить lock в `finally`.
|
||||
- Зарегистрировать в `QG_CHECKS` под ключом `"check_branch_mergeable"`.
|
||||
- Контракт never-raise (как у соседних чеков): исключение → `(False, "<reason>")`.
|
||||
|
||||
> **Опционально (за архитектором):** флаг `settings.merge_gate_enabled`; при `False`
|
||||
> чек возвращает `(True, "merge-gate disabled")` (безопасный no-op для постепенного
|
||||
> раскатывания, по образцу условного staging-гейта ORCH-35).
|
||||
|
||||
## 4. Изменения схемы БД
|
||||
- **Не требуется** для базовой реализации (lock через файл/advisory).
|
||||
- ЕСЛИ архитектор выберет lock через SQLite — добавить таблицу/строку-замок миграцией,
|
||||
совместимой с текущей инициализацией `src/db.py` (никаких ломающих изменений `tasks`,
|
||||
`agent_runs`, `jobs`, `events`). Это решение фиксируется в ADR.
|
||||
|
||||
## 5. Изменения API
|
||||
- Новых HTTP-эндпоинтов **не требуется**.
|
||||
- Допустимо (не обязательно) расширить `GET /status` или `GET /queue` индикатором
|
||||
«merge-gate: rebasing/re-testing/locked» для наблюдаемости — на усмотрение архитектора,
|
||||
без изменения существующих контрактов ответов.
|
||||
|
||||
## 6. Точки встройки в конвейер (требование + кандидаты)
|
||||
|
||||
**Требование:** merge-gate отрабатывает как можно ближе к фактическому слиянию в `main`
|
||||
и ДО него. Слияние ветки в `main` НЕ должно происходить в обход гейта.
|
||||
|
||||
Кандидаты (окончательно — ADR архитектора):
|
||||
- **(A)** Гейт на переходе `deploy-staging → deploy` или новый под-гейт перед слиянием:
|
||||
deployer вливает PR на стадии `deploy`, поэтому проверка «догнать+re-test» логично
|
||||
встаёт непосредственно перед запуском deployer.
|
||||
- **(B)** Новая стадия `merge-gate` между `deploy-staging` и `deploy` с агентом=None и
|
||||
`qg="check_branch_mergeable"`.
|
||||
- **(C)** Перенести само слияние в `main` из ответственности deployer-агента в
|
||||
детерминированный шаг оркестратора, защищённый merge-gate (более крупное изменение).
|
||||
|
||||
При любом варианте, меняющем `STAGE_TRANSITIONS` или `QG_CHECKS`:
|
||||
- обновить `docs/architecture/README.md` (таблица стадий + реестр QG, §«Конвейер»);
|
||||
- обновить snapshot-тесты `tests/test_qg_registry_snapshot.py`
|
||||
(`_EXPECTED_QGS`, `_EXPECTED_TRANSITIONS`) — осознанно, в этом же PR;
|
||||
- сохранить порядок ключей `STAGE_TRANSITIONS` (от него зависит `get_previous_stage`).
|
||||
|
||||
## 7. Откаты (интеграция со `stage_engine`)
|
||||
В `_handle_qg_failure_rollbacks` добавить ветку для merge-gate FAIL по образцу
|
||||
`check_staging_status` / `check_deploy_status`:
|
||||
- `update_task_stage(task_id, "development")`, `set_issue_blocked(work_item_id)`;
|
||||
- комментарий в Plane (`plane_add_comment`, author="deployer" или системный) с причиной
|
||||
(конфликт rebase / красный re-test) — дословный `reason` гейта;
|
||||
- Telegram-алерт (`send_telegram`);
|
||||
- учитывать `MAX_DEVELOPER_RETRIES`, не плодить бесконечные заворот-циклы.
|
||||
- В `_run_qg` добавить диспетчеризацию `check_branch_mergeable` с сигнатурой
|
||||
`(repo, work_item_id, branch)` (как у артефактных чеков).
|
||||
|
||||
## 8. Изменения конфигурации (`src/config.py`, env-префикс `ORCH_`)
|
||||
| Setting | Назначение | Дефолт (предложение) |
|
||||
|---------|-----------|----------------------|
|
||||
| `merge_gate_enabled: bool` | Глобальный вкл/выкл гейта | `True` |
|
||||
| `merge_retest_timeout_s: int` | Тайм-аут повторного прогона тестов | `600` |
|
||||
| `merge_lock_timeout_s: int` | Тайм-аут ожидания merge-lock | `300` |
|
||||
| `merge_gate_repos: str` | (опц.) ограничить гейт списком репо; пусто = все | `""` |
|
||||
|
||||
Значения и имена финализирует архитектор; задокументировать в `.env.example` и
|
||||
`docs/architecture/README.md`.
|
||||
|
||||
## 9. Требования к наблюдаемости / документации (golden source)
|
||||
- Обновить `docs/architecture/README.md`: описание merge-gate, auto-rebase, re-test,
|
||||
merge-lock; при изменении стадий/реестра — соответствующие таблицы.
|
||||
- Обновить `CHANGELOG.md`.
|
||||
- Завести ADR `docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md` (механизм догона,
|
||||
выбор rebase vs merge, реализация lock, место встройки).
|
||||
- Все ветки кода — с лог-сообщениями (`logger.info/warning/error`) по образцу соседних
|
||||
гейтов, чтобы поведение читалось в `/app/data/runs` и логах сервиса.
|
||||
|
||||
## 10. Нефункциональные требования
|
||||
- **Безопасность self-hosting:** никогда не push в `main`; force только `--force-with-lease`
|
||||
по ветке задачи; прод-контейнер `orchestrator` не рестартить/не ронять.
|
||||
- **Изоляция:** все git-операции — в worktree ветки (`ensure_worktree`), не в общем clone,
|
||||
чтобы не словить S-4-гонку параллельных задач.
|
||||
- **Идемпотентность/restart-safe:** lock и гейт корректно ведут себя при рестарте сервиса.
|
||||
- **Never-raise** контракт у всех новых чеков/парсеров (как в текущем `src/qg/checks.py`).
|
||||
- **Совместимость:** не менять сигнатуры/поведение существующих QG-чеков и вебхуков.
|
||||
|
||||
## 11. Артефакты pipeline, которые должны быть созданы/обновлены
|
||||
- `src/merge_gate.py` (новый), изменения в `src/qg/checks.py`, `src/stages.py`,
|
||||
`src/stage_engine.py`, `src/config.py`, при необходимости `src/git_worktree.py`.
|
||||
- Новые тесты в `tests/` + обновлённые snapshot-тесты.
|
||||
- `docs/architecture/README.md`, `CHANGELOG.md`, `.env.example`,
|
||||
`docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md`.
|
||||
@@ -1,105 +0,0 @@
|
||||
# 03 — Критерии приёмки (Acceptance Criteria)
|
||||
|
||||
**Work Item:** ORCH-043 — merge-gate + auto-rebase + re-test
|
||||
**Автор:** Analyst
|
||||
|
||||
Каждый критерий имеет однозначное условие PASS/FAIL. Все критерии должны быть PASS.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — Ветка актуальна: гейт пропускает без догона
|
||||
- **Дано:** ветка содержит последний `origin/main` (не отстаёт).
|
||||
- **Когда:** выполняется `check_branch_mergeable(repo, work_item_id, branch)`.
|
||||
- **PASS:** возвращает `(True, ...)` с причиной «up-to-date», auto-rebase НЕ запускается,
|
||||
ветка не пушится повторно.
|
||||
- **FAIL:** возвращает `False`, либо выполняет ненужный rebase/push.
|
||||
|
||||
## AC-2 — Ветка отстаёт + чистый догон + зелёный re-test → проход
|
||||
- **Дано:** ветка отстаёт от `origin/main`; rebase проходит без текстового конфликта;
|
||||
тест-набор на догнанной ветке зелёный.
|
||||
- **Когда:** выполняется merge-gate.
|
||||
- **PASS:** ветка догнана до `origin/main`, запушена `--force-with-lease`, re-test зелёный,
|
||||
гейт возвращает `(True, ...)`.
|
||||
- **FAIL:** гейт возвращает `False` при чистом догоне и зелёном re-test, либо `main` тронут,
|
||||
либо push выполнен НЕ через `--force-with-lease`.
|
||||
|
||||
## AC-3 — Текстовый конфликт rebase → откат на development, без слияния
|
||||
- **Дано:** auto-rebase упирается в текстовый конфликт.
|
||||
- **Когда:** выполняется merge-gate.
|
||||
- **PASS:** rebase отменён (worktree чист), гейт возвращает `(False, "rebase conflict...")`,
|
||||
задача переведена на `development`, в Plane — комментарий с причиной, слияния в `main` нет.
|
||||
- **FAIL:** ветка осталась в конфликтном состоянии, или задача продвинулась к слиянию,
|
||||
или `main` изменён.
|
||||
|
||||
## AC-4 — Красный re-test после догона → откат на development, без слияния
|
||||
- **Дано:** rebase чистый, но тесты на догнанной ветке падают.
|
||||
- **Когда:** выполняется merge-gate.
|
||||
- **PASS:** гейт возвращает `(False, "re-test failed after rebase...")`, задача на
|
||||
`development`, комментарий в Plane, слияния нет.
|
||||
- **FAIL:** гейт вернул `True`, либо слияние произошло при красном re-test.
|
||||
|
||||
## AC-5 — Сериализация слияний (merge-lock)
|
||||
- **Дано:** две задачи одного `repo` одновременно подходят к merge-gate.
|
||||
- **Когда:** обе пытаются пройти гейт.
|
||||
- **PASS:** «догон+re-test+слияние» выполняет одновременно только одна задача; вторая
|
||||
ждёт освобождения lock (в пределах `merge_lock_timeout_s`), после чего повторно
|
||||
сверяет «не отстаёт» и при необходимости догоняется. Воспроизводимый сценарий
|
||||
«две зелёные ветки ломают main» НЕ приводит к красному `main`.
|
||||
- **FAIL:** обе задачи параллельно проходят гейт и вливаются, воспроизводя гонку.
|
||||
|
||||
## AC-6 — Re-test тайм-аут управляем
|
||||
- **Дано:** re-test превышает `settings.merge_retest_timeout_s`.
|
||||
- **PASS:** прогон прерывается, гейт возвращает `(False, "re-test timeout...")`, задача
|
||||
не виснет, идёт штатный откат.
|
||||
- **FAIL:** задача висит дольше тайм-аута или падает с необработанным исключением.
|
||||
|
||||
## AC-7 — Никогда не push/merge в main напрямую из гейта
|
||||
- **PASS:** код merge-gate не выполняет `git push ... main` и не форс-пушит `main`;
|
||||
force-операции — только `--force-with-lease` по ветке задачи.
|
||||
- **FAIL:** найден любой push/force-push в `main` из логики гейта.
|
||||
|
||||
## AC-8 — Изоляция в worktree
|
||||
- **PASS:** все git-операции гейта идут в worktree ветки (`get_worktree_path` /
|
||||
`ensure_worktree`), а не в общем `/repos/<repo>` clone.
|
||||
- **FAIL:** rebase/тесты выполняются в общем clone, создавая S-4-гонку.
|
||||
|
||||
## AC-9 — Контракт never-raise
|
||||
- **Дано:** недоступен git/сеть, бит worktree, отсутствует ветка и т.п.
|
||||
- **PASS:** `check_branch_mergeable` и функции `merge_gate.py` возвращают `(False, "<reason>")`
|
||||
(или безопасный фоллбэк), НИКОГДА не пробрасывают исключение в `advance_stage`.
|
||||
- **FAIL:** любое необработанное исключение всплывает из гейта.
|
||||
|
||||
## AC-10 — Реестр QG и снапшоты консистентны
|
||||
- **PASS:** `"check_branch_mergeable"` зарегистрирован в `QG_CHECKS` и callable;
|
||||
`tests/test_qg_registry_snapshot.py` (`_EXPECTED_QGS`, при изменении стадий —
|
||||
`_EXPECTED_TRANSITIONS`) обновлены и зелёные; порядок ключей `STAGE_TRANSITIONS`
|
||||
сохранён (не сломан `get_previous_stage`).
|
||||
- **FAIL:** дрейф реестра/стадий без обновления снапшотов; красные snapshot-тесты.
|
||||
|
||||
## AC-11 — Интеграция отката в stage_engine
|
||||
- **PASS:** в `_handle_qg_failure_rollbacks` есть ветка merge-gate FAIL → `development`
|
||||
с уведомлениями (Plane + Telegram) и учётом `MAX_DEVELOPER_RETRIES`; `_run_qg`
|
||||
корректно диспетчеризует новый чек.
|
||||
- **FAIL:** FAIL гейта не приводит к откату, или нет уведомления, или зацикливание заворотов.
|
||||
|
||||
## AC-12 — Условный no-op / выключение (если реализовано)
|
||||
- **Дано:** `settings.merge_gate_enabled = False` (или репо вне `merge_gate_repos`).
|
||||
- **PASS:** гейт возвращает `(True, "merge-gate disabled")`, конвейер работает как прежде.
|
||||
- **FAIL:** гейт блокирует/ломает конвейер при выключенном флаге.
|
||||
|
||||
## AC-13 — Документация обновлена (golden source)
|
||||
- **PASS:** обновлены `docs/architecture/README.md` (merge-gate/auto-rebase/re-test,
|
||||
при изменении — таблицы стадий/реестра), `CHANGELOG.md`, `.env.example` (новые
|
||||
`ORCH_*` настройки); создан ADR `06-adr/ADR-001-merge-gate.md`.
|
||||
- **FAIL:** функционал изменён, документация/ADR/CHANGELOG не обновлены (Reviewer →
|
||||
REQUEST_CHANGES).
|
||||
|
||||
## AC-14 — Безопасность self-hosting
|
||||
- **PASS:** в рамках задачи прод-контейнер `orchestrator` (8500) не рестартился и не падал;
|
||||
изменения не трогают `.env*`, `docker-compose.yml`, прод-инфраструктуру; страховка
|
||||
стадией `deploy-staging` сохранена.
|
||||
- **FAIL:** любой рестарт/падение прод-оркестратора или правка прод-инфры в рамках задачи.
|
||||
|
||||
## AC-15 — Зелёный регресс
|
||||
- **PASS:** `pytest tests/ -q` зелёный целиком (новые тесты ORCH-043 + существующий набор).
|
||||
- **FAIL:** любой упавший/сломанный существующий тест.
|
||||
@@ -1,163 +0,0 @@
|
||||
work_item: ORCH-043
|
||||
title: "merge-gate + auto-rebase + re-test — безопасная параллель в одном репо"
|
||||
framework: pytest
|
||||
notes: >
|
||||
Тесты на git-операции используют локальные временные репозитории (init bare "origin"
|
||||
+ рабочая ветка), мокают сеть/Plane/Telegram (как в tests/test_qg.py:
|
||||
ORCH_DB_PATH/ORCH_REPOS_DIR в tmp, httpx замокан). Каталог тестов/команда pytest для
|
||||
re-test должны совпадать с CI-конфигом проекта. Финальные имена функций/модулей сверять
|
||||
с реализацией архитектора.
|
||||
|
||||
tests:
|
||||
# ---- merge_gate core: ancestor / behind detection ----
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "branch_is_behind_main → True, когда origin/main ушёл вперёд относительно ветки"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "branch_is_behind_main → False, когда ветка уже содержит весь origin/main"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "branch_is_behind_main never-raise: недоступный git/clone → безопасный возврат, не исключение"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
|
||||
# ---- auto-rebase ----
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "auto_rebase_onto_main: чистый догон → (True), ветка содержит origin/main, push выполнен через --force-with-lease"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "auto_rebase_onto_main: текстовый конфликт → rebase отменён (worktree чист), (False, 'rebase conflict...'), main не тронут"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "auto_rebase_onto_main НЕ пушит и не форс-пушит main ни при каком исходе (проверка вызванных git-команд)"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
|
||||
# ---- re-test ----
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "retest_branch: pytest rc=0 → (True, 're-test green')"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "retest_branch: pytest rc!=0 → (False, 're-test failed...') с хвостом вывода"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "retest_branch: превышен merge_retest_timeout_s → (False, 're-test timeout...'), без виса"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
|
||||
# ---- merge-lock / сериализация ----
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "merge-lock: второй захват того же repo не проходит, пока lock удержан; освобождается в finally/после ошибки"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "merge-lock restart-safe: устаревший/осиротевший lock не блокирует навсегда (тайм-аут merge_lock_timeout_s)"
|
||||
module: tests/test_merge_gate.py
|
||||
expected: PASS
|
||||
|
||||
# ---- QG check_branch_mergeable ----
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "check_branch_mergeable: ветка актуальна → (True, 'up-to-date'), rebase не вызывался"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: "check_branch_mergeable: отстаёт + чистый rebase + зелёный re-test → (True)"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: "check_branch_mergeable: конфликт rebase → (False, 'rebase conflict...')"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-15
|
||||
type: unit
|
||||
description: "check_branch_mergeable: красный re-test после догона → (False, 're-test failed after rebase...')"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: "check_branch_mergeable never-raise: внутренняя ошибка → (False, reason), не исключение; lock освобождён"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
- id: TC-17
|
||||
type: unit
|
||||
description: "merge_gate_enabled=False (или репо вне merge_gate_repos) → (True, 'merge-gate disabled') no-op"
|
||||
module: tests/test_qg_merge_gate.py
|
||||
expected: PASS
|
||||
|
||||
# ---- реестр QG / стадии ----
|
||||
- id: TC-18
|
||||
type: unit
|
||||
description: "'check_branch_mergeable' присутствует в QG_CHECKS и callable"
|
||||
module: tests/test_qg_registry_snapshot.py
|
||||
expected: PASS
|
||||
- id: TC-19
|
||||
type: unit
|
||||
description: "snapshot STAGE_TRANSITIONS/_EXPECTED_QGS обновлён осознанно и совпадает; порядок ключей сохранён (get_previous_stage не сломан)"
|
||||
module: tests/test_qg_registry_snapshot.py
|
||||
expected: PASS
|
||||
|
||||
# ---- интеграция со stage_engine (откаты) ----
|
||||
- id: TC-20
|
||||
type: integration
|
||||
description: "_run_qg диспетчеризует check_branch_mergeable с сигнатурой (repo, work_item_id, branch)"
|
||||
module: tests/test_stage_engine.py
|
||||
expected: PASS
|
||||
- id: TC-21
|
||||
type: integration
|
||||
description: "merge-gate FAIL → advance_stage откатывает задачу на 'development', set_issue_blocked, комментарий Plane, Telegram-алерт (моки)"
|
||||
module: tests/test_stage_engine.py
|
||||
expected: PASS
|
||||
- id: TC-22
|
||||
type: integration
|
||||
description: "merge-gate FAIL уважает MAX_DEVELOPER_RETRIES — нет бесконечного цикла заворотов"
|
||||
module: tests/test_stage_engine.py
|
||||
expected: PASS
|
||||
- id: TC-23
|
||||
type: integration
|
||||
description: "merge-gate PASS → задача продвигается к слиянию/деплою, рассинхрона стадий нет"
|
||||
module: tests/test_stage_engine.py
|
||||
expected: PASS
|
||||
|
||||
# ---- сквозной сценарий гонки ----
|
||||
- id: TC-24
|
||||
type: integration
|
||||
description: >
|
||||
Воспроизведение бизнес-сценария: A и B от main@C0; A влита (main@C1);
|
||||
B проходит merge-gate → догоняется до C1 и re-test зелёный → безопасное слияние;
|
||||
при красном re-test B откатывается, main остаётся зелёным
|
||||
module: tests/test_merge_gate_race.py
|
||||
expected: PASS
|
||||
|
||||
# ---- конфигурация ----
|
||||
- id: TC-25
|
||||
type: unit
|
||||
description: "Новые ORCH_* настройки (merge_gate_enabled, merge_retest_timeout_s, merge_lock_timeout_s, merge_gate_repos) читаются с дефолтами и env-override"
|
||||
module: tests/test_config.py
|
||||
expected: PASS
|
||||
|
||||
# ---- регресс ----
|
||||
- id: TC-26
|
||||
type: integration
|
||||
description: "Полный набор pytest tests/ -q зелёный (существующие гейты/вебхуки/стадии не сломаны)"
|
||||
module: tests/
|
||||
expected: PASS
|
||||
@@ -1,235 +0,0 @@
|
||||
# ADR-001: Merge-gate + auto-rebase + re-test (безопасная параллель в одном репо)
|
||||
|
||||
## Статус
|
||||
Proposed
|
||||
|
||||
> Решение архитектора по ТЗ ORCH-043 (`02-trz.md`). Реализует BR-1..BR-8, удовлетворяет
|
||||
> AC-1..AC-15. Глобальный сквозной аналог — `docs/architecture/adr/adr-0006-merge-gate.md`.
|
||||
|
||||
---
|
||||
|
||||
## Контекст
|
||||
|
||||
Конвейер валидирует ветку относительно того `main`, из которого она была создана, а не
|
||||
относительно `main` на момент слияния. Между «ветка проверена» и «ветка влита» `main` мог
|
||||
уйти вперёд из-за слияния другой параллельной задачи → **семантический конфликт слияния**:
|
||||
git сливает без текстового конфликта, но объединённый код `main` сломан. Для self-hosting
|
||||
(`orchestrator`) это = красный `main` инструмента, обслуживающего ВСЕ проекты из одного
|
||||
инстанса с общей БД/очередью.
|
||||
|
||||
Ключевые факты текущей архитектуры, влияющие на решение (проверено по коду):
|
||||
|
||||
1. **Где происходит слияние в `main`.** Ветку в `main` вливает **deployer-агент в начале
|
||||
своего запуска на стадии `deploy`** (см. `src/webhooks/gitea.py:336-353` — комментарий
|
||||
«deployer merges the PR at the START of its run»). Замена самого механизма слияния PR
|
||||
в Gitea — **вне объёма** (BRD §4). Значит, merge остаётся PR-merge через deployer.
|
||||
2. **Как запускается deployer стадии `deploy`.** При прохождении `check_staging_status`
|
||||
на стадии `deploy-staging` движок (`stage_engine.advance_stage`) переводит задачу
|
||||
`deploy-staging → deploy` и запускает `get_agent_for_stage("deploy-staging") = deployer`.
|
||||
Этот deployer и делает merge. Значит **merge-gate обязан отработать на ребре
|
||||
`deploy-staging → deploy`, ДО запуска этого deployer'а**.
|
||||
3. **Чем триггерится QG.** `advance_stage` вызывается ТОЛЬКО при (а) завершении
|
||||
LLM-агента (`launcher._try_advance_stage`) или (б) приходе вебхука. **Стадия без агента
|
||||
не имеет собственного триггера** (стадия `deploy` оценивается, когда заканчивает
|
||||
deployer, исполняющийся ВО ВРЕМЯ неё). Поэтому новая «пустая» стадия `merge-gate`
|
||||
между `deploy-staging` и `deploy` зависла бы без триггера (нужен был бы chaining в
|
||||
движке либо синтетический job — лишняя и не-restart-safe поверхность).
|
||||
4. **Concurrency.** `max_concurrency` по умолчанию `1`; QG исполняется в monitor-thread
|
||||
агента. Блокирующее ожидание lock внутри `advance_stage` при одном worker-слоте даёт
|
||||
**дедлок** (задача B держит слот, ожидая merge задачи A, которой нужен тот же слот).
|
||||
Сериализация обязана быть **неблокирующей**.
|
||||
|
||||
---
|
||||
|
||||
## Решение
|
||||
|
||||
### 1. Место встройки — ребро `deploy-staging → deploy` (кандидат A ТЗ §6), без новой стадии
|
||||
|
||||
Merge-gate — детерминированный шаг в `advance_stage`, исполняемый **после** прохождения
|
||||
`check_staging_status` и **до** `update_task_stage(deploy)` / запуска deployer'а, который
|
||||
мержит. `STAGE_TRANSITIONS` **не меняется** (минимальный blast-radius; `get_previous_stage`
|
||||
не затрагивается; snapshot `_EXPECTED_TRANSITIONS` без изменений). В реестр `QG_CHECKS`
|
||||
добавляется один ключ `check_branch_mergeable` (snapshot `_EXPECTED_QGS` обновляется
|
||||
осознанно, AC-10).
|
||||
|
||||
Отвергнутые варианты:
|
||||
- **(B) Новая стадия `merge-gate`** — концептуально честнее, но «пустая» стадия без агента
|
||||
не имеет триггера (см. Контекст §3). Потребовала бы chaining в `advance_stage`
|
||||
(не restart-safe для безагентного перехода) или синтетический job-тип в очереди
|
||||
(поверхность в `launcher`/`queue_worker`, который сейчас умеет только LLM-агентов).
|
||||
- **(C) Перенос merge в детерминированный шаг оркестратора** — прямо запрещён объёмом
|
||||
(BRD §4: «Замена механизма слияния PR в Gitea — вне объёма»).
|
||||
|
||||
Триггер гейта — **существующее** событие «staging-deployer завершился» → отдельного
|
||||
механизма триггера не вводим.
|
||||
|
||||
### 2. Догон ветки — `rebase` onto `origin/main` + `push --force-with-lease`
|
||||
|
||||
Выбор `rebase` (а не merge-commit) обусловлен критериями приёмки AC-2/AC-7, которые прямо
|
||||
требуют `push --force-with-lease` догнанной ветки. Алгоритм `auto_rebase_onto_main`:
|
||||
|
||||
1. `git fetch origin main` в worktree ветки (`ensure_worktree`, AC-8 — изоляция).
|
||||
2. `branch_is_behind_main`: ветка отстаёт ⇔ `git merge-base --is-ancestor origin/main <HEAD>`
|
||||
вернул ненулевой код. Не удалось определить (git/сеть) → трактуем как «не пропускаем
|
||||
вслепую» (never-raise → `(False, reason)`), НЕ как «up-to-date».
|
||||
3. Не отстаёт → `(True, "branch up-to-date with main")`, rebase/push **не выполняются** (AC-1).
|
||||
4. Отстаёт → `git rebase origin/main`:
|
||||
- **текстовый конфликт** → `git rebase --abort`, worktree чист → `(False, "rebase conflict: <файлы>")` (AC-3);
|
||||
- **чистый rebase** → `git push --force-with-lease origin <branch>` (**ТОЛЬКО ветка задачи; НИКОГДА `main`**, AC-7) → далее re-test.
|
||||
5. Контракт **never-raise**: любая git/OS-ошибка → `(False, "<reason>")` (AC-9).
|
||||
|
||||
`main` гейтом не пушится и не форс-пушится никогда. Единственная force-операция —
|
||||
`--force-with-lease` по ветке задачи.
|
||||
|
||||
### 3. Re-test — `python -m pytest` в worktree догнанной ветки
|
||||
|
||||
`retest_branch(repo, branch)`:
|
||||
- Команда `python -m pytest <merge_retest_target>` (`merge_retest_target` по умолчанию
|
||||
`tests/`) из корня worktree ветки — согласовано с CI orchestrator
|
||||
(`pytest tests/ -q`, CLAUDE.md) и паттерном `check_tests_local`.
|
||||
- Тайм-аут `settings.merge_retest_timeout_s` (дефолт 600); превышение →
|
||||
`(False, "re-test timeout (<T>s)")` (AC-6), процесс убивается, задача не виснет.
|
||||
- `returncode == 0` → `(True, "re-test green")`; иначе `(False, "re-test failed after rebase: <tail>")` (AC-4).
|
||||
|
||||
> Гейт по умолчанию реален для self-hosting репо `orchestrator` (BR-7). Для других репо
|
||||
> применять только при совпадающей тест-команде/раскладке — через `merge_gate_repos`
|
||||
> (см. §6). Команда re-test параметризуется `merge_retest_target` для портируемости.
|
||||
|
||||
### 4. Сериализация слияний — файловый merge-lease на репозиторий (BR-5, AC-5)
|
||||
|
||||
Цель: «догон + re-test + **слияние**» одного репо выполняет одновременно только одна
|
||||
задача. Слияние делает deployer ПОЗЖЕ и в ОТДЕЛЬНОМ запуске, поэтому простой
|
||||
context-manager-lock внутри гейта окно гонки не закрывает — нужен **lease, живущий от
|
||||
гейта до фактического merge**.
|
||||
|
||||
**Механизм — файловый lease**, БЕЗ изменения схемы БД (ТЗ §4 предпочитает no-schema-change):
|
||||
- Файл `<repos_dir>/.merge-lease-<repo>.json`, содержимое `{task_id, work_item_id, branch,
|
||||
acquired_at, pid}`.
|
||||
- **Acquire — атомарный, НЕблокирующий** (`open(..., O_CREAT|O_EXCL)`):
|
||||
- файла нет → захват, запись метаданных;
|
||||
- файл есть, holder == self → идемпотентно «уже наш» (restart/повтор);
|
||||
- файл есть, holder != self, возраст `< merge_lock_timeout_s` → **busy**;
|
||||
- файл есть, возраст `>= merge_lock_timeout_s` → **stale, перезахват** с `logger.warning`
|
||||
(crash-recovery: процесс-холдер умер, не освободив lease).
|
||||
- **Release — идемпотентный** (`os.remove`, ignore-missing).
|
||||
- **Restart-safe**: lease на диске; зависший lease реклеймится по возрасту.
|
||||
|
||||
**Поведение `check_branch_mergeable(repo, work_item_id, branch)`** (детерминированно, без LLM):
|
||||
1. Попытка acquire (неблокирующая). Busy → `(False, "merge-lock busy")` — **сигнальный
|
||||
reason** (НЕ провал кода, см. §5: defer, а не rollback).
|
||||
2. **Double-check под lease**: повторно `branch_is_behind_main` (пока ждали/между тиками
|
||||
`main` мог уйти — например, другая задача только что влилась).
|
||||
3. Не отстаёт → `(True, "branch up-to-date with main")`.
|
||||
4. Отстаёт → `auto_rebase_onto_main`:
|
||||
- конфликт → `(False, "rebase conflict: ...")`;
|
||||
- успех → `retest_branch`: зелёный → `(True, "rebased onto main, re-test green")`;
|
||||
красный/тайм-аут → `(False, "re-test failed after rebase: ...")`.
|
||||
5. **При успехе lease НЕ освобождается** — он удерживается до фактического merge.
|
||||
**При любом провале (конфликт/красный re-test) lease освобождается** (откат на
|
||||
development, слияния не будет).
|
||||
6. Регистрация в `QG_CHECKS["check_branch_mergeable"]`; сигнатура `(repo, work_item_id,
|
||||
branch)` совпадает с дефолтной артефактной → `_run_qg` диспетчеризует без спец-кейса.
|
||||
|
||||
**Жизненный цикл lease (точки release):**
|
||||
- **PR-merged вебхук** ветки (`gitea.handle_pr`, `action=closed & merged`) → release;
|
||||
- **`deploy → done`** в `advance_stage` (страховочный release);
|
||||
- **любой откат на development** из merge-gate / `check_deploy_status` → release;
|
||||
- **возраст `>= merge_lock_timeout_s`** → авто-реклейм (backstop при краше).
|
||||
|
||||
### 5. Откаты и defer (интеграция в `stage_engine`, BR-4/BR-8, AC-11)
|
||||
|
||||
`check_branch_mergeable` различает два негативных исхода:
|
||||
|
||||
- **`reason == "merge-lock busy"` → DEFER, не rollback.** Код задачи исправен — нельзя
|
||||
слать на development и нельзя тратить `MAX_DEVELOPER_RETRIES`. Движок **повторно
|
||||
ставит deployer на `deploy-staging` с задержкой** `settings.merge_defer_delay_s`
|
||||
(через `available_at`-гейт очереди, ORCH-1; задача остаётся на `deploy-staging`).
|
||||
Неблокирующий defer освобождает worker-слот → задача-холдер успевает влиться (нет
|
||||
дедлока при `max_concurrency=1`). Повторов defer — ограниченное число
|
||||
(`merge_defer_max_attempts`), исчерпание → Telegram-алерт + блокировка.
|
||||
- **`reason` = конфликт rebase ИЛИ красный re-test → rollback на `development`** по образцу
|
||||
`check_staging_status`/`check_deploy_status` в `_handle_qg_failure_rollbacks`:
|
||||
`update_task_stage(development)`, `set_issue_blocked`, дословный `reason` в Plane
|
||||
(`plane_add_comment`, author="deployer"), `send_telegram`, учёт `MAX_DEVELOPER_RETRIES`,
|
||||
**release lease**. Дословный `reason` встраивается в `task_desc` developer'а (по образцу
|
||||
ORCH-046), чтобы агент видел суть.
|
||||
|
||||
### 6. Конфигурация (`src/config.py`, env-префикс `ORCH_`)
|
||||
|
||||
| Setting | Назначение | Дефолт |
|
||||
|---------|-----------|--------|
|
||||
| `merge_gate_enabled: bool` | Глобальный вкл/выкл (no-op `(True, "merge-gate disabled")` при False, AC-12) | `True` |
|
||||
| `merge_gate_repos: str` | CSV-список репо, где гейт реален; пусто = только self-hosting (`orchestrator`) | `""` |
|
||||
| `merge_retest_timeout_s: int` | Тайм-аут re-test | `600` |
|
||||
| `merge_retest_target: str` | pytest-цель для re-test (портируемость) | `tests/` |
|
||||
| `merge_lock_timeout_s: int` | Макс. возраст lease (ожидание/реклейм) | `300` |
|
||||
| `merge_defer_delay_s: int` | Задержка перед повтором гейта при busy | `60` |
|
||||
| `merge_defer_max_attempts: int` | Лимит defer-повторов до эскалации | `5` |
|
||||
|
||||
Семантика `merge_gate_repos`: пусто → гейт реален ТОЛЬКО для `orchestrator`
|
||||
(`is_self_hosting_repo`), для прочих — no-op `(True, "merge-gate N/A for <repo>")`
|
||||
(по образцу условного staging-гейта ORCH-35). Это безопасный поэтапный раскат.
|
||||
|
||||
### 7. API
|
||||
Новых HTTP-эндпоинтов нет. Допустимо (необязательно) добавить в `GET /status`/`GET /queue`
|
||||
индикатор состояния merge-lease для наблюдаемости — без изменения существующих контрактов.
|
||||
|
||||
---
|
||||
|
||||
## Последствия
|
||||
|
||||
### Плюсы
|
||||
- Закрывает воспроизводимый сценарий «две зелёные ветки ломают `main`»: перед слиянием
|
||||
ветка догоняется до актуального `origin/main` и повторно тестируется; слияния
|
||||
сериализуются lease'ом.
|
||||
- Минимальный blast-radius: `STAGE_TRANSITIONS` не тронут, snapshot-переходы не меняются,
|
||||
+1 ключ в `QG_CHECKS`. Триггер — существующее событие, без chaining/новых job-типов.
|
||||
- Restart-safe и deadlock-safe: файловый lease с реклеймом по возрасту; неблокирующий
|
||||
acquire + defer вместо блокирующего ожидания.
|
||||
- Соответствует self-hosting-инвариантам: никогда не пуш/форс-пуш `main`; force только
|
||||
`--force-with-lease` по ветке задачи; прод-контейнер не рестартится; страховка
|
||||
`deploy-staging` сохранена.
|
||||
- Поэтапный раскат через `merge_gate_enabled` / `merge_gate_repos`.
|
||||
|
||||
### Минусы / ограничения
|
||||
- **Merge-gate как «скрытый» под-гейт** ребра `deploy-staging → deploy` не отражён в
|
||||
`STAGE_TRANSITIONS` (плата за отказ от новой стадии). Смягчение: явно описан в
|
||||
`docs/architecture/README.md` и этом ADR.
|
||||
- **Сериализация зависит от вебхука PR-merged** для своевременного release. Деградация
|
||||
предусмотрена (реклейм по возрасту `merge_lock_timeout_s`), но при «потерянном»
|
||||
вебхуке возможна задержка следующей задачи до тайм-аута lease.
|
||||
- **Defer перезапускает staging-deployer** (повторно прогоняет staging-проверку и
|
||||
перезаписывает `15-staging-log.md`) — переиспользует существующий механизм очереди
|
||||
ценой лишнего прогона staging. Допустимо; альтернатива (отдельный «retry-gate» job-тип)
|
||||
дороже по поверхности.
|
||||
- **Длинный re-test (до 600s)** исполняется синхронно в monitor-thread staging-deployer'а
|
||||
и удерживает worker-слот на это время (при `max_concurrency=1` приостанавливает прочие
|
||||
задачи). Это неотъемлемая стоимость «re-test перед слиянием».
|
||||
- **`rebase --force-with-lease`** переписывает историю ветки и обновляет head открытого PR;
|
||||
прежний approve ревьюера может пометиться stale в Gitea. На стадии `deploy` ревью
|
||||
повторно не проверяется — функционально безопасно.
|
||||
|
||||
### Влияние на масштаб изменения
|
||||
Вводится новый модуль (`src/merge_gate.py`), новый QG, lease-подсистема и изменение
|
||||
поведения ребра `deploy-staging → deploy` + откаты/вебхук. Это **сквозное изменение
|
||||
конвейера** → рекомендуется лейбл `arch:major-change` и обязательная страховка стадией
|
||||
`deploy-staging` (8501) перед прод-деплоем самого ORCH-043. Глобальный ADR —
|
||||
`docs/architecture/adr/adr-0006-merge-gate.md`.
|
||||
|
||||
---
|
||||
|
||||
## Точки изменения кода (для developer; имена функций — финальные)
|
||||
- `src/merge_gate.py` (**новый**): `branch_is_behind_main`, `auto_rebase_onto_main`,
|
||||
`retest_branch`, lease (`acquire_merge_lease`/`release_merge_lease`/реклейм).
|
||||
- `src/qg/checks.py`: `check_branch_mergeable(repo, work_item_id, branch)` + регистрация в `QG_CHECKS`.
|
||||
- `src/stage_engine.py`: вызов merge-gate на ребре `deploy-staging → deploy` (после
|
||||
`check_staging_status`, до advance); ветка rollback merge-gate в
|
||||
`_handle_qg_failure_rollbacks`; defer-ветка для `"merge-lock busy"`; release lease в
|
||||
`deploy → done` и в откатах.
|
||||
- `src/webhooks/gitea.py`: release lease в `handle_pr` (closed & merged).
|
||||
- `src/db.py` (опц.): `enqueue_job(..., available_at_delay_s=...)` для defer, либо переиспользовать `available_at`.
|
||||
- `src/config.py`: настройки §6.
|
||||
- `tests/`: тесты по `04-test-plan.yaml` + обновить `tests/test_qg_registry_snapshot.py`
|
||||
(`_EXPECTED_QGS` += `check_branch_mergeable`; `_EXPECTED_TRANSITIONS` — **без изменений**).
|
||||
- Документация: `docs/architecture/README.md` (обновлена в этом PR), `CHANGELOG.md`,
|
||||
`.env.example` (новые `ORCH_*`).
|
||||
@@ -1,25 +0,0 @@
|
||||
# 07 — Требования к инфраструктуре (ORCH-043)
|
||||
|
||||
## Вывод: топология не меняется. Новых контейнеров/портов/сервисов нет.
|
||||
|
||||
| Аспект | Требование |
|
||||
|--------|-----------|
|
||||
| Контейнеры | Без изменений. Прод `orchestrator` (8500) и `orchestrator-staging` (8501) — как есть. |
|
||||
| Порты | Без изменений. |
|
||||
| Сеть/внешние сервисы | Без новых зависимостей. Используются существующие git/Gitea (fetch/push) и pytest. |
|
||||
| Файловая система | Новый артефакт времени выполнения — lease-файл `<repos_dir>/.merge-lease-<repo>.json` (см. `08-data-requirements.md`). Лежит в уже примонтированном `repos_dir` (`/repos`). Дополнительного volume не требуется. |
|
||||
| Worktree | Переиспользуется существующая изоляция (`/repos/_wt/<repo>/<branch>`, ORCH-2). Все git-операции merge-gate — в worktree. |
|
||||
| `.env` / compose / прод-инфра | **НЕ изменяются** (AC-14). Новые `ORCH_*` настройки имеют безопасные дефолты (см. ADR-001 §6) и документируются в `.env.example`. |
|
||||
|
||||
## Эксплуатационные требования
|
||||
- **git push прав** для оркестратора достаточно существующих (он уже пушит ветки/PR-артефакты).
|
||||
Merge-gate пушит ТОЛЬКО ветку задачи (`--force-with-lease`), `main` — никогда.
|
||||
- **Раскат поэтапно**: `merge_gate_enabled=False` или пустой `merge_gate_repos` (реален
|
||||
только для `orchestrator`) позволяют включать гейт постепенно без риска для чужих репо.
|
||||
- **Self-hosting-страховка сохранена**: изменения ORCH-043 проходят обязательную стадию
|
||||
`deploy-staging` (8501) до прод-деплоя самого оркестратора; прод-контейнер не рестартится
|
||||
в рамках задачи.
|
||||
|
||||
## Рекомендация по процессу
|
||||
Изменение сквозное (новый QG + поведение ребра `deploy-staging → deploy`) →
|
||||
рекомендуется лейбл `arch:major-change`. Прод-деплой ORCH-043 — строго через staging-гейт.
|
||||
@@ -1,27 +0,0 @@
|
||||
# 08 — Требования к данным / схеме БД (ORCH-043)
|
||||
|
||||
## Вывод: изменение схемы SQLite НЕ требуется.
|
||||
|
||||
Merge-lease (сериализация слияний, BR-5) реализуется **файлом**, а не таблицей:
|
||||
|
||||
- Путь: `<repos_dir>/.merge-lease-<repo>.json` (`settings.repos_dir`, по умолчанию `/repos`).
|
||||
- Содержимое: `{ "task_id": int, "work_item_id": str, "branch": str,
|
||||
"acquired_at": "<ISO>", "pid": int }`.
|
||||
- Жизненный цикл — см. ADR-001 §4 (acquire неблокирующий / release идемпотентный /
|
||||
реклейм по возрасту `merge_lock_timeout_s`).
|
||||
|
||||
### Почему файл, а не таблица БД
|
||||
- ТЗ §4 прямо предпочитает реализацию без миграции схемы.
|
||||
- Файловый lease проще делается **restart-safe** (реклейм по mtime/возрасту + `pid`) и не
|
||||
трогает инициализацию `src/db.py` (никаких изменений `tasks`/`agent_runs`/`jobs`/`events`).
|
||||
- Атомарность захвата обеспечивается `open(O_CREAT|O_EXCL)` на одном хосте (mva154,
|
||||
один инстанс) — достаточно для сериализации в пределах одного процесса-оркестратора.
|
||||
|
||||
### Существующие таблицы — без изменений
|
||||
`tasks`, `agent_runs`, `jobs`, `events` не модифицируются. Defer-механизм переиспользует
|
||||
существующий столбец `jobs.available_at` (ORCH-1) для отложенного повторного запуска
|
||||
deployer'а — **новых столбцов не нужно**.
|
||||
|
||||
> Если в будущем потребуется кросс-процессная/мульти-хостовая сериализация — lease можно
|
||||
> мигрировать в таблицу (или advisory-lock). Это будет отдельным ADR; в рамках ORCH-043
|
||||
> файловый lease достаточен (один хост, один инстанс).
|
||||
@@ -1,24 +0,0 @@
|
||||
# 10 — Технические риски (ORCH-043)
|
||||
|
||||
Merge-gate + auto-rebase + re-test. Риски, их влияние и меры снижения. Привязка к AC.
|
||||
|
||||
| # | Риск | Влияние | Снижение | AC |
|
||||
|---|------|---------|----------|----|
|
||||
| R-1 | **Дедлок при `max_concurrency=1`**: блокирующее ожидание merge-lock в `advance_stage` держит единственный worker-слот, а задаче-холдеру тот же слот нужен для merge. | Полная остановка конвейера (self-hosting = все проекты). | Acquire **неблокирующий**; busy → **defer** (re-enqueue с задержкой, слот освобождается), НЕ блокирующее ожидание. | AC-5 |
|
||||
| R-2 | **Потерянный PR-merged вебхук** → lease не освобождается вовремя. | Следующая задача ждёт до тайм-аута. | Реклейм lease по возрасту `merge_lock_timeout_s`; release продублирован в `deploy→done` и в откатах. | AC-5 |
|
||||
| R-3 | **Краш сервиса под lease** (зависший lease-файл после рестарта). | Блокировка merge репо. | Файловый lease с реклеймом по возрасту + `pid`; идемпотентный re-acquire холдером. Restart-safe. | AC-5, AC-9 |
|
||||
| R-4 | **Долгий re-test (до 600s)** держит worker-слот и блокирует прочие задачи. | Замедление конвейера. | Жёсткий тайм-аут `merge_retest_timeout_s` + kill; осознанная стоимость re-test-перед-merge. | AC-6 |
|
||||
| R-5 | **Случайный push/force-push в `main`** из логики гейта. | Прямая порча `main` прод-инструмента. | Код гейта НИКОГДА не пушит `main`; единственная force — `--force-with-lease` по ветке задачи; покрыто тестом-стражем. | AC-7 |
|
||||
| R-6 | **Необработанное исключение** из гейта всплывает в `advance_stage`. | Падение авто-advance, зависшая задача. | Контракт **never-raise** во всех функциях `merge_gate.py` и `check_branch_mergeable`: исключение → `(False, reason)`. | AC-9 |
|
||||
| R-7 | **Git-операции в общем clone** `/repos/<repo>` вместо worktree → S-4-гонка параллельных задач. | Порча рабочих копий, ложные конфликты. | Все операции — в worktree ветки (`ensure_worktree`/`get_worktree_path`). | AC-8 |
|
||||
| R-8 | **Defer-петля** (lease вечно busy из-за залипшего холдера) → бесконечные перепрогоны staging. | Зацикливание, расход токенов/CPU. | `merge_defer_max_attempts` + Telegram-эскалация + блокировка; реклейм lease (R-2/R-3) снимает первопричину. | AC-5, AC-11 |
|
||||
| R-9 | **rebase --force-with-lease** помечает прежний approve ревьюера stale и пересоздаёт head PR. | Теоретическая потеря «зелёного» статуса PR. | На стадии `deploy` ревью повторно не проверяется; re-test в гейте — авторитетная проверка. Документировано в ADR. | AC-2 |
|
||||
| R-10 | **Re-test-команда не подходит чужому репо** (раскладка enduro-trails ≠ orchestrator). | Ложный красный re-test на не-self-hosting репо. | Гейт по умолчанию реален ТОЛЬКО для `orchestrator`; прочие — no-op; `merge_retest_target` параметризует цель. | AC-12, BR-7 |
|
||||
| R-11 | **Дрейф snapshot-реестра** при добавлении QG. | Красные тесты / расхождение контракта. | Обновить `_EXPECTED_QGS` (+`check_branch_mergeable`) осознанно; `_EXPECTED_TRANSITIONS` НЕ менять (стадии не трогаем). | AC-10 |
|
||||
| R-12 | **Рестарт/падение прод-контейнера** `orchestrator` в рамках задачи. | Остановка конвейера всех проектов. | Не трогаем `.env*`/`docker-compose.yml`/инфру; обязательная страховка `deploy-staging` (8501). | AC-14 |
|
||||
| R-13 | **Регресс существующих тестов** от изменения `advance_stage`/`gitea.handle_pr`. | Поломка конвейера. | `pytest tests/ -q` целиком зелёный; изменения аддитивны (новая ветвь на ребре, существующие пути не меняются). | AC-15 |
|
||||
|
||||
## Остаточные риски (принимаются)
|
||||
- **Скрытый под-гейт** (merge-gate не отражён в `STAGE_TRANSITIONS`) — плата за минимальный
|
||||
blast-radius; смягчён документацией (README + ADR).
|
||||
- **Лишний прогон staging** при defer — переиспользование очереди вместо нового job-типа.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-043
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-043 — merge-gate + auto-rebase + re-test
|
||||
|
||||
## Summary
|
||||
Реализован детерминированный (без LLM) merge-gate `check_branch_mergeable` на ребре
|
||||
`deploy-staging → deploy`: догон ветки до актуального `origin/main` (`rebase` +
|
||||
`push --force-with-lease` ТОЛЬКО ветки задачи), повторный прогон тестов в worktree
|
||||
догнанной ветки и файловый merge-lease для сериализации слияний. Интеграция в
|
||||
`stage_engine` (defer при busy-lock, rollback при конфликте/красном re-test с капом
|
||||
`MAX_DEVELOPER_RETRIES`), release lease на `deploy→done` / rollback / PR-merged вебхуке.
|
||||
|
||||
Соответствие ТЗ (`02-trz.md`) и AC-1..AC-15 — полное. Реализация соответствует
|
||||
`ADR-001-merge-gate.md` и глобальному `adr-0006`. Контракт never-raise соблюдён
|
||||
во всех новых функциях, все git-операции изолированы в worktree (AC-8), `main`
|
||||
никогда не пушится/форс-пушится (AC-7). Документация обновлена в этом же PR.
|
||||
|
||||
`pytest tests/ -q` — **535 passed** (AC-15). Snapshot-реестр обновлён осознанно
|
||||
(`_EXPECTED_QGS += check_branch_mergeable`, `_EXPECTED_TRANSITIONS` не тронут — AC-10).
|
||||
Прод-инфра (`docker-compose*`, `.env`, `.gitea/`, `Dockerfile`) не затронута (AC-14).
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- (нет)
|
||||
|
||||
### P2 — Should fix
|
||||
- [ ] **Двойное назначение `merge_lock_timeout_s` (300s).** Один и тот же тайм-аут
|
||||
служит и порогом «лиз протух → реклейм» (crash-backstop), и фактическим окном
|
||||
удержания лиза от гейта до мержа. Если deploy-деплоер по какой-то причине мержит
|
||||
PR дольше 300s, ожидающая задача реклеймит лиз как stale и может пойти на слияние
|
||||
параллельно — узкое окно, теоретически воспроизводящее гонку, которую закрывает
|
||||
AC-5. На практике deployer мержит в начале запуска, окно мало; тайм-аут
|
||||
конфигурируем. Рекомендация (не блокер): развести «возраст реклейма краша» и
|
||||
«ожидаемое время удержания», либо добавить наблюдаемость (лог/алерт при
|
||||
stale-реклейме непустого холдера).
|
||||
- [ ] **Двойной `git fetch origin main`** — в `branch_is_behind_main` и затем в
|
||||
`auto_rebase_onto_main` на пути «ветка отстаёт». Незначительная неэффективность,
|
||||
не баг; можно переиспользовать результат первого fetch.
|
||||
|
||||
## Документация
|
||||
Обновлено полностью, документация = golden source соблюдена (AC-13):
|
||||
- `docs/architecture/README.md` — добавлен раздел «Merge-gate…», ветка откатов,
|
||||
реестр QG (`check_branch_mergeable`), `STAGE_TRANSITIONS` корректно НЕ изменён.
|
||||
- `CHANGELOG.md` — подробная запись ORCH-043.
|
||||
- `.env.example` — все 7 новых `ORCH_MERGE_*` настроек с комментариями.
|
||||
- ADR per-work-item `docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md` (Proposed)
|
||||
и глобальный `docs/architecture/adr/adr-0006-merge-gate.md` + строка в `adr/README.md`.
|
||||
- Тесты: `test_merge_gate.py`, `test_qg_merge_gate.py`, `test_merge_gate_race.py`,
|
||||
`test_stage_engine.py::TestMergeGate`, `test_config.py`, обновлён
|
||||
`test_qg_registry_snapshot.py`.
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-043
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-043 (merge-gate + auto-rebase + re-test)
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Ветка: `feature/ORCH-043-merge-gate-auto-rebase-re-test` (HEAD `ba51aa1`)
|
||||
- Дата: 2026-06-06T17:37Z
|
||||
|
||||
## Smoke API (read-only, прод-контейнер не трогался)
|
||||
- `GET /health` → HTTP 200 `{"status":"ok","service":"orchestrator"}`
|
||||
- `GET /status` → HTTP 200, активная задача ORCH-043 на стадии `testing`
|
||||
- `GET /queue` → HTTP 200, breaker `closed`, preflight_ok=true, max_concurrency=1
|
||||
|
||||
## Результаты (test-plan 04-test-plan.yaml)
|
||||
|
||||
| TC ID | Описание | Модуль | Результат |
|
||||
|-------|----------|--------|-----------|
|
||||
| TC-01 | branch_is_behind_main → True (main ушёл вперёд) | test_merge_gate.py | PASS |
|
||||
| TC-02 | branch_is_behind_main → False (ветка содержит main) | test_merge_gate.py | PASS |
|
||||
| TC-03 | branch_is_behind_main never-raise | test_merge_gate.py | PASS |
|
||||
| TC-04 | auto_rebase: чистый догон + push --force-with-lease | test_merge_gate.py | PASS |
|
||||
| TC-05 | auto_rebase: конфликт → abort, worktree чист, main не тронут | test_merge_gate.py | PASS |
|
||||
| TC-06 | auto_rebase не пушит/форс-пушит main | test_merge_gate.py | PASS |
|
||||
| TC-07 | retest_branch: rc=0 → (True,'re-test green') | test_merge_gate.py | PASS |
|
||||
| TC-08 | retest_branch: rc!=0 → (False) с хвостом вывода | test_merge_gate.py | PASS |
|
||||
| TC-09 | retest_branch: тайм-аут → (False,'re-test timeout') | test_merge_gate.py | PASS |
|
||||
| TC-10 | merge-lock: повторный захват блокируется, release в finally | test_merge_gate.py | PASS |
|
||||
| TC-11 | merge-lock restart-safe: устаревший lock не блокирует | test_merge_gate.py | PASS |
|
||||
| TC-12 | check_branch_mergeable: актуальна → (True,'up-to-date') | test_qg_merge_gate.py | PASS |
|
||||
| TC-13 | check_branch_mergeable: отстаёт+rebase+зелёный re-test → True | test_qg_merge_gate.py | PASS |
|
||||
| TC-14 | check_branch_mergeable: конфликт rebase → (False) | test_qg_merge_gate.py | PASS |
|
||||
| TC-15 | check_branch_mergeable: красный re-test → (False) | test_qg_merge_gate.py | PASS |
|
||||
| TC-16 | check_branch_mergeable never-raise, lock освобождён | test_qg_merge_gate.py | PASS |
|
||||
| TC-17 | merge_gate_enabled=False / вне merge_gate_repos → no-op | test_qg_merge_gate.py | PASS |
|
||||
| TC-18 | 'check_branch_mergeable' в QG_CHECKS и callable | test_qg_registry_snapshot.py | PASS |
|
||||
| TC-19 | snapshot реестра/стадий обновлён, порядок ключей сохранён | test_qg_registry_snapshot.py | PASS |
|
||||
| TC-20 | _run_qg диспетчеризует check_branch_mergeable | test_stage_engine.py | PASS |
|
||||
| TC-21 | merge-gate FAIL → откат на development + Plane/Telegram | test_stage_engine.py | PASS |
|
||||
| TC-22 | merge-gate FAIL уважает MAX_DEVELOPER_RETRIES | test_stage_engine.py | PASS |
|
||||
| TC-23 | merge-gate PASS → продвижение к слиянию/деплою | test_stage_engine.py | PASS |
|
||||
| TC-24 | сквозной сценарий гонки A/B, main остаётся зелёным | test_merge_gate_race.py | PASS |
|
||||
| TC-25 | новые ORCH_* настройки: дефолты + env-override | test_config.py | PASS |
|
||||
| TC-26 | полный регресс pytest tests/ зелёный | tests/ | PASS |
|
||||
|
||||
Целевые файлы ORCH-043 (`test_merge_gate`, `test_qg_merge_gate`, `test_merge_gate_race`,
|
||||
`test_config`, `test_qg_registry_snapshot`): 33 passed; merge-gate в `test_stage_engine`: 7 passed.
|
||||
|
||||
## Соответствие критериям приёмки
|
||||
AC-1..AC-15 — все покрыты прошедшими тестами (см. маппинг TC выше) и подтверждены
|
||||
APPROVED-ревью (`12-review.md`). AC-15 (зелёный регресс) — подтверждён ниже.
|
||||
|
||||
## Вывод pytest
|
||||
```
|
||||
======================= 535 passed, 1 warning in 12.70s ========================
|
||||
```
|
||||
(единственное warning — PydanticDeprecatedSince20 в `src/config.py:4`, не относится к ORCH-043, нефатальное)
|
||||
|
||||
## Итог
|
||||
PASS — 535/535 тестов зелёные, smoke API OK, прод-контейнер не затронут.
|
||||
Задача готова к стадии `deploy-staging`.
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
timestamp: 2026-06-06T17:44:25Z
|
||||
work_item: ORCH-043
|
||||
target: prod orchestrator (8500) — self-hosting
|
||||
staging_gate: SUCCESS
|
||||
merge_gate: SUCCESS
|
||||
rebuild_required: true
|
||||
restart_required: true
|
||||
mode: artifact-validated; prod rebuild+restart handed off to Owner (self-hosting safeguard)
|
||||
---
|
||||
|
||||
# Production Deploy Log — ORCH-043
|
||||
|
||||
`feat(merge-gate): auto-rebase onto current main + re-test + serialise merges`
|
||||
|
||||
## Verdict
|
||||
|
||||
`deploy_status: SUCCESS` — the deployable artifact is validated and ready, and the
|
||||
automated deploy-stage responsibility is complete. ORCH-043 changes **runtime
|
||||
`src/` code**, so the live prod rollout needs a container **rebuild + restart**.
|
||||
Per the self-hosting guardrail that step is an **Owner action** (see Handoff) and was
|
||||
deliberately **NOT** performed by this agent.
|
||||
|
||||
## Precondition: staging gate (`check_staging_status`)
|
||||
|
||||
`deploy` is reachable only because the staging gate passed:
|
||||
|
||||
- `15-staging-log.md` → `staging_status: SUCCESS`, **10/10 checks PASS** on the live
|
||||
`orchestrator-staging` instance (8501), run inside the staging container
|
||||
(ORCH-048 canon). This is the mandatory pre-prod safeguard for self-hosting
|
||||
(ADR-0003 staging gate).
|
||||
|
||||
## Precondition: merge-gate (`check_branch_mergeable`, ORCH-043 itself)
|
||||
|
||||
The new merge-gate runs on the `deploy-staging → deploy` edge, before this stage:
|
||||
it validates the branch against **current** `origin/main` (catch-up rebase + re-test
|
||||
+ serialised merge-lease). The branch reached `deploy`, so the gate did not roll back
|
||||
or defer. Note: the branch carries this same gate code — it is the first task to be
|
||||
gated by its own feature (dog-fooding), which the green staging run exercised.
|
||||
|
||||
## Change scope (why a prod rebuild+restart IS required)
|
||||
|
||||
Unlike bind-mount-only changes (cf. ORCH-048), ORCH-043 modifies code that lives
|
||||
**inside the prod image** and is executed by the running app:
|
||||
|
||||
| File | Kind | Reaches prod via |
|
||||
|------|------|------------------|
|
||||
| `src/merge_gate.py` | new runtime module | image rebuild |
|
||||
| `src/config.py` | runtime config (merge-gate flags, retest target/timeout) | image rebuild |
|
||||
| `src/db.py` | merge-lease helpers (schema-compatible, **no migration**) | image rebuild |
|
||||
| `src/qg/checks.py` | new `check_branch_mergeable` gate | image rebuild |
|
||||
| `src/stage_engine.py` | sub-gate dispatch on the deploy edge | image rebuild |
|
||||
| `src/webhooks/gitea.py` | PR-merged → release merge-lease | image rebuild |
|
||||
| `tests/*`, `docs/*` | tests + docs | n/a (not deployed) |
|
||||
|
||||
Because `src/` changed, the running prod process picks up ORCH-043 **only** after a
|
||||
rebuild + restart of the shared prod `orchestrator` (8500).
|
||||
|
||||
## Deploy action
|
||||
|
||||
- **Prod container rebuild/restart:** required, **not performed** (guardrail: never
|
||||
rebuild/restart the shared prod `orchestrator` within an ORCH task — it serves all
|
||||
projects incl. enduro-trails from one instance with a shared DB/queue; an in-task
|
||||
restart is a group risk for every project).
|
||||
- **Real docker/SSH deploy hook** (`scripts/orchestrator-deploy-hook.sh`): **not
|
||||
triggered** by this agent (not explicitly instructed; reserved for the Owner per
|
||||
ORCH-36 / DEPLOY_HOOK.md).
|
||||
- **Effective delivery:** merge of this branch to `main` lands the source of truth;
|
||||
the prod cut-over (rebuild + restart) is the documented Owner step below.
|
||||
|
||||
## Handoff — Owner prod cut-over (DEPLOY_HOOK.md, INFRA.md §Self-hosting)
|
||||
|
||||
Perform **only in a quiet window** and in this order:
|
||||
|
||||
1. **P-4 (BLOCKER)** — confirm `GET http://localhost:8500/status` shows **no active
|
||||
tasks** before touching prod (shared instance with enduro-trails).
|
||||
2. Host `git pull` on `main` under uid 1000 (`/home/slin/repos/orchestrator`).
|
||||
3. Prod cut-over via the deploy hook (conscious prod override — defaults are staging):
|
||||
```bash
|
||||
TARGET_SERVICE=orchestrator TARGET_PORT=8500 \
|
||||
TARGET_IMAGE=orchestrator-orchestrator COMPOSE_PROFILE="" \
|
||||
PREV_IMAGE_FILE=/home/slin/repos/orchestrator/.deploy-prev-image-prod \
|
||||
bash scripts/orchestrator-deploy-hook.sh --deploy
|
||||
```
|
||||
The hook snapshots the previous image, runs a 60s health loop on `:8500/health`,
|
||||
and **auto-rolls back** if the new container is unhealthy.
|
||||
4. Post-deploy smoke: `GET /health` → `200 {"status":"ok"}`, `GET /queue` returns
|
||||
counts; confirm a subsequent ORCH/ET task transitions cleanly through the new
|
||||
merge-gate (no spurious defer/rollback).
|
||||
|
||||
## Summary
|
||||
|
||||
| Item | State |
|
||||
|------|-------|
|
||||
| Staging gate (`check_staging_status`) | SUCCESS (10/10) |
|
||||
| Merge-gate (`check_branch_mergeable`) | SUCCESS (branch reached deploy) |
|
||||
| DB schema migration | none (lease is schema-compatible) |
|
||||
| In-task prod rebuild/restart | NOT performed (self-hosting safeguard, by design) |
|
||||
| Prod cut-over | handed off to Owner (P-4 + deploy hook, prod override) |
|
||||
| Deploy stage verdict | SUCCESS |
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-06T17:40:13Z
|
||||
base_url: http://localhost:8501
|
||||
mode: stub
|
||||
result: 10/10 checks PASS
|
||||
---
|
||||
|
||||
# Staging Gate Log — ORCH-043
|
||||
|
||||
Staging test suite completed against the live `orchestrator-staging` instance
|
||||
(port 8501). **All 10/10 checks passed**, suite exit code `0`.
|
||||
|
||||
## Execution
|
||||
|
||||
Canonical invocation — run INSIDE the `orchestrator-staging` container
|
||||
(ORCH-048, ADR-001) so Block A's `ORCH_STAGING=true` guard and the B6
|
||||
registry-isolation check read the running instance's own process-env
|
||||
(`.env.staging`):
|
||||
|
||||
```
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
|
||||
> Note: the host worktree environment has no `docker` CLI, so the exec was
|
||||
> driven directly through the Docker Engine API over `/var/run/docker.sock`
|
||||
> (equivalent to the command above — same container, same in-container env).
|
||||
> Block A `A3 ORCH_STAGING=true` and B6 both PASS, confirming the suite ran
|
||||
> with the live staging registry (no host-path fallback / false FAIL).
|
||||
|
||||
## Results
|
||||
|
||||
```
|
||||
============================================================
|
||||
ORCH-33 Staging Check Suite
|
||||
base_url : http://localhost:8501
|
||||
mode : stub
|
||||
utc_time : 2026-06-06T17:40:13.623652+00:00
|
||||
============================================================
|
||||
|
||||
[Block A] SMOKE
|
||||
✓ PASS A1 GET /health → 200 status=ok
|
||||
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience
|
||||
✓ PASS A3 ORCH_STAGING=true (not prod)
|
||||
|
||||
[Block B] ACCESS
|
||||
✓ PASS B4 Plane: sandbox project accessible [found 5 project(s), sandbox=YES]
|
||||
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true
|
||||
✓ PASS B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)]
|
||||
|
||||
[Block C] E2E (mode=stub)
|
||||
✓ PASS C7 Create issue in Plane SANDBOX
|
||||
✓ PASS C8 Trigger pipeline via /webhook/plane
|
||||
✓ PASS C9a Branch appears in orchestrator-sandbox
|
||||
✓ PASS C9b Analyst job enqueued in staging queue
|
||||
|
||||
[CLEANUP]
|
||||
✓ PASS CLEANUP: deleted test branch, Plane issue, task + job rows
|
||||
|
||||
============================================================
|
||||
RESULT: 10/10 checks PASS
|
||||
============================================================
|
||||
|
||||
[docker-exec] ExitCode=0
|
||||
```
|
||||
|
||||
Cleanup ran fully in the `finally` block — no residual test task, branch, or
|
||||
job rows left on the staging stand.
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
timestamp: 2026-06-06T08:44:04Z
|
||||
work_item: ORCH-044
|
||||
branch: feature/ORCH-044-preflight-auth-effort
|
||||
commit: 08ace892bbf1809a65c1dc504459d052bfd71f79
|
||||
target_service: orchestrator
|
||||
target_port: 8500
|
||||
deploy_mode: artifact-only
|
||||
staging_gate: SUCCESS
|
||||
prod_container_restarted: false
|
||||
rebuild_required: true
|
||||
---
|
||||
|
||||
# Deploy Log — ORCH-044
|
||||
|
||||
## Verdict
|
||||
|
||||
**`deploy_status: SUCCESS`** — артефактный (artifact-only) деплой-вердикт.
|
||||
|
||||
Реальный `git pull` + `docker compose ... --build` + рестарт прод-контейнера
|
||||
`orchestrator` (8500) в рамках этой стадии **НЕ выполняется**. Он делегирован
|
||||
хуку `scripts/orchestrator-deploy-hook.sh` (ORCH-36), который запускается
|
||||
Владельцем **после** мерджа ветки `feature/ORCH-044-preflight-auth-effort` в
|
||||
`main`. Guardrail: агент никогда не перезапускает общий прод-инстанс внутри
|
||||
ORCH-задачи (CLAUDE.md / INFRA.md §Self-hosting).
|
||||
|
||||
## Pre-conditions (все ✓)
|
||||
|
||||
| Артефакт | Поле | Значение |
|
||||
|----------|------|----------|
|
||||
| `12-review.md` | `verdict` | `APPROVED` |
|
||||
| `13-test-report.md` | `result` | `PASS` |
|
||||
| `15-staging-log.md` (origin/main) | `staging_status` | `SUCCESS` (10/10 staging-checks, прогон внутри `orchestrator-staging` :8501) |
|
||||
| `04-test-plan.yaml` | — | покрывает AC (P2/`--effort` исключён владельцем → ORCH-50, N/A) |
|
||||
| ADR | `06-adr/ADR-001-preflight-auth-and-empty-result-failure.md` | заведён |
|
||||
| `CHANGELOG.md` | — | обновлён |
|
||||
|
||||
Стадия `deploy` достижима только потому, что условный staging-гейт
|
||||
(`check_staging_status`, реальный для self-hosting repo=orchestrator) — зелёный.
|
||||
|
||||
## Change scope — почему нужен rebuild+restart (но не сейчас)
|
||||
|
||||
В отличие от чисто bind-mount изменений (ср. ORCH-048), ORCH-044 меняет
|
||||
**рантайм-код `src/`**, который копируется в образ (`/app/src`) и исполняется
|
||||
прод-процессом:
|
||||
|
||||
| Файл | Тип | Как доезжает до прода |
|
||||
|------|-----|------------------------|
|
||||
| `src/preflight.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
|
||||
| `src/agents/launcher.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
|
||||
| `src/config.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
|
||||
| `docs/**`, `CHANGELOG.md` | docs | мерж в `main` |
|
||||
| `tests/**` | тесты, не деплоятся | n/a |
|
||||
|
||||
`rebuild_required: true`. Чтобы новый token-free auth-гейт preflight и
|
||||
«пустой лог ⇒ провал» вступили в силу на проде, прод-инстанс `orchestrator`
|
||||
(8500) должен быть пересобран и перезапущен. **Это делает Владелец через
|
||||
деплой-хук после мерджа**, не данный агент.
|
||||
|
||||
## Self-hosting policy
|
||||
|
||||
> ORCH-044 правит слой запуска агента (preflight/launcher/config) того самого
|
||||
> инструмента, который СЕЙЧАС обслуживает все прод-проекты (orchestrator +
|
||||
> enduro-trails) из одного инстанса `orchestrator:8500` с общей БД и общей
|
||||
> очередью.
|
||||
|
||||
Поэтому в рамках этой стадии:
|
||||
- **Прод-контейнер `orchestrator` (8500) НЕ трогался** — ни рестарта, ни
|
||||
пересборки (групповой риск для всех проектов).
|
||||
- **Деплой-хук** `scripts/orchestrator-deploy-hook.sh` (реальный docker/SSH)
|
||||
**не запускался** этим агентом (не было явной инструкции Owner; зарезервирован
|
||||
за ним, ORCH-36). У хука есть health-цикл (10×6с) + авто-rollback —
|
||||
страховка на момент боевого rebuild+restart.
|
||||
- **Страховка пройдена:** staging (8501, изолированная БД/реестр) — зелёный
|
||||
перед прод-деплоем (ORCH-35).
|
||||
|
||||
## Deploy action
|
||||
|
||||
- **Prod rebuild/restart:** требуется (`src/` изменён), **не выполнен** этим
|
||||
агентом (guardrail self-hosting). Выполняется Владельцем через деплой-хук
|
||||
после мерджа в `main`.
|
||||
- **Эффективный rollout:** мерж ветки в `main` → Owner запускает
|
||||
`scripts/orchestrator-deploy-hook.sh` (прод-режим: `TARGET_SERVICE=orchestrator
|
||||
TARGET_PORT=8500 COMPOSE_PROFILE=""`) с health-check + авто-rollback.
|
||||
|
||||
## Verdict
|
||||
|
||||
`deploy_status: SUCCESS` — все гейты зелёные, артефакт-вердикт зафиксирован,
|
||||
боевой rebuild+restart делегирован Owner-хуку. Прод-инстанс не затронут.
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-06T08:41:49Z
|
||||
base_url: http://localhost:8501
|
||||
---
|
||||
|
||||
# Staging Gate Log
|
||||
|
||||
Staging test suite completed. All checks passed (10/10).
|
||||
|
||||
- Work item: ORCH-044
|
||||
- Repo: orchestrator (self-hosting → staging gate is real, not a no-op)
|
||||
- Container: `orchestrator-staging` (port 8501)
|
||||
- Command (canonical, ran INSIDE the container so B6 reads the instance's own `.env.staging` process-env):
|
||||
`python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`
|
||||
- Exit code: 0
|
||||
|
||||
## Results
|
||||
|
||||
```
|
||||
[Block A] SMOKE
|
||||
✓ PASS A1 GET /health → 200 status=ok
|
||||
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience
|
||||
✓ PASS A3 ORCH_STAGING=true (not prod)
|
||||
|
||||
[Block B] ACCESS
|
||||
✓ PASS B4 Plane: sandbox project accessible
|
||||
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true
|
||||
✓ PASS B6 Registry: sandbox present, prod ET/ORCH absent
|
||||
|
||||
[Block C] E2E (mode=stub)
|
||||
✓ PASS C7 Create issue in Plane SANDBOX
|
||||
✓ PASS C8 Trigger pipeline via /webhook/plane
|
||||
✓ PASS C9a Branch appears in orchestrator-sandbox
|
||||
✓ PASS C9b Analyst job enqueued in staging queue
|
||||
|
||||
[CLEANUP]
|
||||
✓ PASS CLEANUP: deleted branch in orchestrator-sandbox
|
||||
✓ PASS CLEANUP: deleted Plane issue
|
||||
✓ PASS CLEANUP DB: deleted job + task rows
|
||||
|
||||
RESULT: 10/10 checks PASS
|
||||
```
|
||||
|
||||
> Note: the host in this environment lacks the `docker` CLI, so the canonical
|
||||
> `docker exec orchestrator-staging ...` was performed via the Docker Engine API
|
||||
> over `/var/run/docker.sock` (Python stdlib, no host-env leakage). Semantics are
|
||||
> identical to `docker exec`: the script ran inside `orchestrator-staging` with
|
||||
> its own `.env.staging` process-env, keeping the B6 registry-isolation check valid.
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: stage_engine: pass reviewer/tester findings text to developer (not just link)
|
||||
|
||||
Work Item ID: ORCH-046
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,86 +0,0 @@
|
||||
# BRD — ORCH-046: pass reviewer/tester findings text to developer (not just link)
|
||||
|
||||
Work Item ID: ORCH-046
|
||||
Stage: analysis
|
||||
Author: analyst
|
||||
Date: 2026-06-06
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
Оркестратор при заворотах задачи деву (откат на `development`) формирует
|
||||
описание задачи (`task_desc`), которое попадает в `.task-dev.md` запускаемого
|
||||
агента-разработчика. Сейчас в двух ветках отката этот текст содержит **только
|
||||
ссылку на файл-артефакт**, без сути замечаний:
|
||||
|
||||
- **Reviewer → REQUEST_CHANGES** (`src/stage_engine.py`, ветка
|
||||
`_handle_qg_failure_rollbacks`, ~стр. 419): `task_desc` =
|
||||
`"…Fix findings in docs/work-items/<id>/12-review.md"`.
|
||||
- **Tester → FAIL** (`check_tests_passed`, ~стр. 455): `task_desc` =
|
||||
`"…Fix failures described in docs/work-items/<id>/13-test-report.md"`.
|
||||
|
||||
В результате developer-агент получает инструкцию «иди читай файл». Ключевые
|
||||
претензии (P0/P1 у ревьюера, причина падения у тестера) часто проскакивают —
|
||||
агент не открывает файл целиком или теряет фокус, повторяет ту же ошибку, и
|
||||
задача снова заворачивается. Это «испорченный телефон»: расход циклов retry
|
||||
(`MAX_DEVELOPER_RETRIES = 3`), деньги на токены, простой конвейера.
|
||||
|
||||
## 2. Бизнес-цель
|
||||
|
||||
Убрать «испорченный телефон» между reviewer/tester и developer при заворотах:
|
||||
встраивать **дословный текст ключевых замечаний** прямо в `task_desc`, чтобы
|
||||
developer-агент видел суть претензий сразу, а не только ссылку.
|
||||
|
||||
Это снижает число повторных заворотов и расход retry-бюджета на одну задачу.
|
||||
|
||||
## 3. Объём (вариант A — выбран Славой 06.06)
|
||||
|
||||
Минимальное, низкорисковое изменение **ядра** (`stage_engine`), которое:
|
||||
|
||||
1. Извлекает из `12-review.md` блок findings и выносит **must-fix (P0/P1)
|
||||
дословно** в `task_desc` при reviewer REQUEST_CHANGES.
|
||||
2. Извлекает из `13-test-report.md` причину FAIL (reason из гейта + релевантный
|
||||
фрагмент тела отчёта) в `task_desc` при tester FAIL.
|
||||
3. Во всех случаях **сохраняет ссылку на полный файл** как дополнительный
|
||||
контекст («полный контекст — см. файл»).
|
||||
4. Извлечение выполняется новым отдельным хелпером-парсером
|
||||
(`src/review_parse.py`), который **никогда не бросает исключение**: при
|
||||
отсутствующем/битом файле возвращает пустой результат, и вызывающий код
|
||||
делает graceful fallback на прежнюю ссылку-строку.
|
||||
|
||||
## 4. Что НЕ входит в объём (out of scope)
|
||||
|
||||
- НЕ трогать гейты `check_*` (в т. ч. ORCH-45 `check_ci_green`,
|
||||
ORCH-47 `_parse_tests_verdict`) — они в проде, поведение неизменно.
|
||||
- НЕ трогать реестр `QG_CHECKS`.
|
||||
- НЕ менять сигнатуры публичных функций (`advance_stage`, `_run_qg`,
|
||||
`check_*`).
|
||||
- НЕ менять webhook-пути.
|
||||
- НЕ менять retry-счётчик (`_developer_retry_count`, `MAX_DEVELOPER_RETRIES`)
|
||||
и rollback-логику (последовательность `update_task_stage` →
|
||||
`notify_stage_change` → `plane_notify_stage` → enqueue) — поведение
|
||||
идентично.
|
||||
- НЕ менять формат Plane-комментариев (`build_status_comment`).
|
||||
|
||||
## 5. Заинтересованные стороны
|
||||
|
||||
- **Owner (Слава)** — заказчик, выбрал вариант A.
|
||||
- **Developer-агенты** — потребители `task_desc`: получают суть замечаний.
|
||||
- **Конвейер всех проектов** (self-hosting) — выигрывает за счёт меньшего
|
||||
числа заворотов.
|
||||
|
||||
## 6. Ограничения и риски (self-hosting)
|
||||
|
||||
- Правка ядра `stage_engine` — компонент крутится в продакшене и обслуживает
|
||||
все проекты из общего инстанса/БД/очереди. Любая регрессия в формировании
|
||||
`task_desc` или (тем более) исключение в `advance_stage` останавливает
|
||||
конвейер всех проектов → **парсер обязан быть полностью graceful**.
|
||||
- Обязателен прогон `deploy-staging` (8501) перед прод-деплоем.
|
||||
- Это правка ядра → требуется ADR (per-work-item).
|
||||
|
||||
## 7. Критерий успеха (бизнес)
|
||||
|
||||
- При заворотах в `.task-dev.md` есть дословный текст ключевых замечаний
|
||||
(P0/P1 ревьюера; reason+фрагмент тестера) плюс ссылка на полный файл.
|
||||
- Парсер устойчив к битым/отсутствующим артефактам (graceful fallback на
|
||||
старую ссылку-строку).
|
||||
- Существующие тесты зелёные; поведение retry/rollback не изменилось.
|
||||
@@ -1,209 +0,0 @@
|
||||
# ТЗ — ORCH-046: встраивание текста findings reviewer/tester в task_desc
|
||||
|
||||
Work Item ID: ORCH-046
|
||||
Stage: analysis
|
||||
Author: analyst
|
||||
Date: 2026-06-06
|
||||
|
||||
> Вариант A (минимальный, низкий риск). Это правка ЯДРА — обязателен ADR
|
||||
> (per-work-item, `docs/work-items/ORCH-046/06-adr/`).
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
|
||||
| Модуль | Изменение |
|
||||
|--------|-----------|
|
||||
| `src/review_parse.py` | **НОВЫЙ** хелпер-парсер: `extract_review_findings(path) -> str`, `extract_test_failures(path) -> str`. |
|
||||
| `src/stage_engine.py` | Две ветки в `_handle_qg_failure_rollbacks`: reviewer REQUEST_CHANGES (~стр. 419) и tester `check_tests_passed` FAIL (~стр. 455) — встраивают извлечённый текст в `task_desc`. |
|
||||
|
||||
Источники-образцы (не менять, использовать как референс паттерна «never raise» и
|
||||
формата артефактов):
|
||||
- `src/qg/checks.py::_parse_tests_verdict` — образец «never raise», split по `---`, `yaml.safe_load`.
|
||||
- `src/frontmatter.py::read_frontmatter_value` — образец defensive-парсера.
|
||||
- `.openclaw/agents/reviewer.md` — канонический формат `12-review.md`.
|
||||
- `.openclaw/agents/tester.md` — канонический формат `13-test-report.md`.
|
||||
|
||||
## 2. Новый модуль `src/review_parse.py`
|
||||
|
||||
### 2.1. `extract_review_findings(path: str) -> str`
|
||||
|
||||
Назначение: вернуть **дословный** текст must-fix findings (P0 + P1) из
|
||||
`12-review.md` для встраивания в `task_desc`.
|
||||
|
||||
Формат входного файла (канон reviewer.md, секция `## Findings`):
|
||||
|
||||
```markdown
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- [ ] <описание>
|
||||
|
||||
### P1 — Must fix
|
||||
- [ ] <описание>
|
||||
|
||||
### P2 — Should fix
|
||||
- [ ] <описание>
|
||||
```
|
||||
|
||||
Требования к реализации:
|
||||
|
||||
1. **Никогда не бросает исключение.** Любая ошибка (нет файла, IOError, кривой
|
||||
markdown, нет секции `## Findings`) → возврат `""` (пустая строка).
|
||||
2. Парсит **только** подсекции P0 и P1 (must-fix). P2/P3 игнорируются.
|
||||
3. Заголовки подсекций распознаются устойчиво к регистру и к тире/дефису:
|
||||
соответствие по наличию токена `P0` / `P1` в строке-заголовке уровня `###`.
|
||||
4. Из распознанных подсекций берётся текст до следующего заголовка `###`/`##`
|
||||
(т. е. тело подсекции дословно: пункты списка `- [ ] …` / `- …`).
|
||||
5. Пустые подсекции (нет содержательных пунктов, только `(если есть)`-плейсхолдер
|
||||
или ничего) — пропускаются. Если ни одного содержательного P0/P1 пункта нет
|
||||
→ возврат `""`.
|
||||
6. Результат — компактный многострочный текст, пригодный для вставки в
|
||||
`task_desc` (например, заголовок подсекции + её пункты). Длина результата
|
||||
ограничивается разумным лимитом (`MAX_FINDINGS_CHARS`, напр. 2000) с
|
||||
усечением и маркером `…(truncated)`; полный контекст всё равно остаётся в
|
||||
файле.
|
||||
7. Frontmatter (верхний `--- … ---`) при необходимости отбрасывается, чтобы не
|
||||
попасть в тело; парсинг секции делается по телу markdown.
|
||||
|
||||
Сигнатура и контракт (стабильны):
|
||||
```python
|
||||
def extract_review_findings(path: str) -> str:
|
||||
"""Дословный текст P0/P1 findings из 12-review.md. Never raises; '' при ошибке/пусто."""
|
||||
```
|
||||
|
||||
### 2.2. `extract_test_failures(path: str) -> str`
|
||||
|
||||
Назначение: вернуть текст причины падения тестов из `13-test-report.md` для
|
||||
встраивания в `task_desc`.
|
||||
|
||||
Формат входного файла (канон tester.md): frontmatter `result: PASS|FAIL`, далее
|
||||
тело с секциями `## Результаты` (таблица TC), `## Вывод pytest`, `## Итог`.
|
||||
|
||||
Требования к реализации:
|
||||
|
||||
1. **Никогда не бросает исключение.** Любая ошибка → возврат `""`.
|
||||
2. Извлекает релевантный фрагмент тела, помогающий понять причину FAIL.
|
||||
Приоритет источников (берём первый непустой):
|
||||
- секция `## Вывод pytest` (вывод прогона — где видно упавшие тесты), и/или
|
||||
- строки таблицы `## Результаты`, содержащие `FAIL`, и/или
|
||||
- секция `## Итог`.
|
||||
3. Результат усекается до `MAX_FAILURES_CHARS` (напр. 2000) с маркером
|
||||
`…(truncated)`.
|
||||
4. Если ничего извлечь не удалось → возврат `""` (вызывающий код делает
|
||||
fallback на ссылку).
|
||||
|
||||
> Примечание: «reason» из самого гейта (`check_tests_passed` → второй элемент
|
||||
> кортежа) у вызывающего кода уже есть (`reason`) — он добавляется в `task_desc`
|
||||
> вызывающим кодом (как и сейчас в комментарии тестера). `extract_test_failures`
|
||||
> добавляет **фрагмент тела отчёта** поверх этого reason.
|
||||
|
||||
Сигнатура и контракт (стабильны):
|
||||
```python
|
||||
def extract_test_failures(path: str) -> str:
|
||||
"""Релевантный фрагмент тела 13-test-report.md (причина FAIL). Never raises; '' при ошибке/пусто."""
|
||||
```
|
||||
|
||||
### 2.3. Общие требования модуля
|
||||
|
||||
- Модуль логирует диагностические сообщения на уровне `logger.debug`
|
||||
(`logging.getLogger("orchestrator.review_parse")`), как `frontmatter.py`.
|
||||
- Никаких сетевых вызовов, только чтение файла с диска.
|
||||
- Константы лимитов вынесены модульными (`MAX_FINDINGS_CHARS`,
|
||||
`MAX_FAILURES_CHARS`).
|
||||
|
||||
## 3. Изменения `src/stage_engine.py`
|
||||
|
||||
### 3.1. Ветка reviewer REQUEST_CHANGES (внутри `_handle_qg_failure_rollbacks`)
|
||||
|
||||
Текущее (~стр. 418–424):
|
||||
```python
|
||||
task_desc = (
|
||||
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
|
||||
f"Stage: development\nNote: REQUEST_CHANGES from reviewer "
|
||||
f"(attempt {retry_count+1}/3). Fix findings in "
|
||||
f"docs/work-items/{work_item_id}/12-review.md"
|
||||
)
|
||||
```
|
||||
|
||||
Целевое поведение:
|
||||
- Сформировать путь к `12-review.md` через `get_worktree_path(repo, branch)` +
|
||||
`docs/work-items/{work_item_id}/12-review.md` (как в `_check_review_approved_by_branch`).
|
||||
- Вызвать `extract_review_findings(path)`.
|
||||
- Если результат непустой — встроить findings **дословно** в `task_desc`
|
||||
(под подзаголовком, напр. `Findings (P0/P1):\n<text>`), а ссылку на файл
|
||||
оставить как «полный контекст» (`Полный контекст: docs/work-items/<id>/12-review.md`).
|
||||
- Если результат пустой (graceful fallback) — `task_desc` остаётся **как
|
||||
сейчас** (ссылка-строка). Никаких исключений.
|
||||
- Префиксная часть (`Work item / Repo / Branch / Stage / Note: REQUEST_CHANGES …
|
||||
(attempt N/3)`) сохраняется без изменений.
|
||||
|
||||
### 3.2. Ветка tester FAIL (`check_tests_passed`, внутри `_handle_qg_failure_rollbacks`)
|
||||
|
||||
Текущее (~стр. 454–459):
|
||||
```python
|
||||
task_desc = (
|
||||
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
|
||||
f"Stage: development\nNote: Tests FAILED. "
|
||||
f"Fix failures described in docs/work-items/{work_item_id}/13-test-report.md"
|
||||
)
|
||||
```
|
||||
|
||||
Целевое поведение:
|
||||
- Сформировать путь к `13-test-report.md` аналогично.
|
||||
- Вызвать `extract_test_failures(path)`.
|
||||
- В `task_desc` всегда включить `reason` (он уже доступен в этой ветке —
|
||||
передаётся в `_handle_qg_failure_rollbacks`).
|
||||
- Если фрагмент тела непустой — встроить его дословно
|
||||
(`Причина: {reason}\nДетали:\n<fragment>`), плюс ссылку на файл как полный
|
||||
контекст.
|
||||
- Если фрагмент пустой — `task_desc` содержит `reason` + ссылку (graceful
|
||||
fallback, не хуже текущего поведения). Никаких исключений.
|
||||
- Префиксная часть и существующий Plane-комментарий тестера
|
||||
(`❌ Тесты не прошли: {reason}…`) НЕ меняются.
|
||||
|
||||
### 3.3. Инварианты (НЕ менять поведение)
|
||||
|
||||
- Последовательность rollback в обеих ветках: `update_task_stage(task_id,
|
||||
"development")` → `notify_stage_change` → `plane_notify_stage` →
|
||||
(`set_issue_in_progress` для тестера) → проверка `_developer_retry_count` <
|
||||
`MAX_DEVELOPER_RETRIES` → `enqueue_job("developer", …)` либо
|
||||
`send_telegram` alert. Порядок и условия идентичны.
|
||||
- `result.rolled_back_to`, `result.enqueued_agent`, `result.enqueued_job_id`,
|
||||
`result.alerted` выставляются как сейчас.
|
||||
- Меняется **только содержимое строки `task_desc`**, передаваемой в
|
||||
`enqueue_job`.
|
||||
- Импорт нового модуля — `from .review_parse import extract_review_findings,
|
||||
extract_test_failures` в шапке `stage_engine.py`.
|
||||
|
||||
## 4. Изменения API
|
||||
|
||||
Нет. Публичные HTTP-эндпоинты (`/health`, `/status`, `/queue`,
|
||||
`/webhook/plane`, `/webhook/gitea`) не затрагиваются.
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
|
||||
Нет. Таблицы `tasks`, `agent_runs`, `jobs`, `events` не меняются.
|
||||
`enqueue_job` вызывается с прежней сигнатурой.
|
||||
|
||||
## 6. Требования к новым QG checks
|
||||
|
||||
Нет. Реестр `QG_CHECKS` и все `check_*` не трогаются (явно out of scope).
|
||||
|
||||
## 7. Артефакты pipeline (создать/обновить в этом PR)
|
||||
|
||||
- `src/review_parse.py` — новый модуль.
|
||||
- `tests/test_review_parse.py` — юнит-тесты парсера (см. 04-test-plan.yaml).
|
||||
- Возможные дополнения в `tests/test_stage_engine.py` — проверка встраивания
|
||||
текста в `task_desc` (rollback-ветки).
|
||||
- `docs/work-items/ORCH-046/06-adr/ADR-001-*.md` — ADR (правка ядра).
|
||||
- `docs/architecture/README.md` / `internals.md` — описание нового хелпера и
|
||||
поведения заворотов (если reviewer сочтёт необходимым; компонент описать в
|
||||
разделе Stage Engine / Откаты).
|
||||
- `CHANGELOG.md` — запись о ORCH-046.
|
||||
|
||||
## 8. Контроль качества / проверка
|
||||
|
||||
```bash
|
||||
python -m pytest tests/ -q # в контейнере; все тесты зелёные
|
||||
```
|
||||
|
||||
Обязательно: стадия `deploy-staging` (8501) перед прод-деплоем (self-hosting).
|
||||
@@ -1,99 +0,0 @@
|
||||
# Критерии приёмки — ORCH-046
|
||||
|
||||
Work Item ID: ORCH-046
|
||||
Stage: analysis
|
||||
Author: analyst
|
||||
Date: 2026-06-06
|
||||
|
||||
Каждый критерий имеет чёткое условие PASS/FAIL. Reviewer/Tester проверяют по
|
||||
этому списку.
|
||||
|
||||
## AC-1 — Дословные P0/P1 findings ревьюера в task_desc
|
||||
|
||||
**Условие:** при reviewer REQUEST_CHANGES (откат `review`/`testing` →
|
||||
`development`) строка `task_desc`, переданная в `enqueue_job("developer", …)`,
|
||||
содержит ДОСЛОВНЫЙ текст findings уровня P0/P1 из `12-review.md` (не только
|
||||
ссылку).
|
||||
|
||||
- **PASS:** в `task_desc` присутствуют дословные строки P0/P1 пунктов из секции
|
||||
`## Findings` файла `12-review.md`.
|
||||
- **FAIL:** `task_desc` содержит только ссылку на файл, без текста findings (при
|
||||
наличии валидного файла с P0/P1).
|
||||
|
||||
## AC-2 — Причина падения тестера в task_desc
|
||||
|
||||
**Условие:** при tester FAIL (`check_tests_passed`, откат `testing` →
|
||||
`development`) строка `task_desc` содержит причину падения: `reason` из гейта +
|
||||
релевантный фрагмент тела `13-test-report.md`.
|
||||
|
||||
- **PASS:** `task_desc` содержит `reason` И непустой фрагмент тела отчёта
|
||||
(вывод pytest / FAIL-строки / Итог), когда отчёт валиден.
|
||||
- **FAIL:** `task_desc` содержит только ссылку на файл без причины/фрагмента
|
||||
(при наличии валидного отчёта).
|
||||
|
||||
## AC-3 — Ссылка на полный файл сохранена
|
||||
|
||||
**Условие:** в обеих ветках (reviewer, tester) `task_desc` по-прежнему содержит
|
||||
ссылку на полный файл-артефакт (`docs/work-items/<id>/12-review.md` /
|
||||
`13-test-report.md`) как дополнительный контекст.
|
||||
|
||||
- **PASS:** путь к файлу присутствует в `task_desc` в обоих сценариях.
|
||||
- **FAIL:** ссылка на файл удалена/отсутствует.
|
||||
|
||||
## AC-4 — Парсер устойчив к отсутствию/битому файлу (graceful)
|
||||
|
||||
**Условие:** `extract_review_findings(path)` и `extract_test_failures(path)`
|
||||
НИКОГДА не бросают исключение; при отсутствующем/нечитаемом/битом файле
|
||||
возвращают `""`, а вызывающий код в `stage_engine` делает fallback на прежнюю
|
||||
ссылку-строку.
|
||||
|
||||
- **PASS:** на несуществующем пути, пустом файле, файле без секций, битом
|
||||
markdown/YAML — функции возвращают `""` без исключения; `advance_stage`
|
||||
отрабатывает откат как раньше (ссылка-строка в `task_desc`).
|
||||
- **FAIL:** любое исключение наружу из парсера или из `advance_stage` из-за
|
||||
парсинга.
|
||||
|
||||
## AC-5 — Тесты зелёные + новые юнит-тесты парсера
|
||||
|
||||
**Условие:** существующие тесты не сломаны; добавлены юнит-тесты парсера,
|
||||
покрывающие: findings есть / findings пусто / битый YAML(frontmatter) / только
|
||||
P3 (нет P0/P1).
|
||||
|
||||
- **PASS:** `python -m pytest tests/ -q` зелёный; `tests/test_review_parse.py`
|
||||
содержит как минимум кейсы: P0/P1 присутствуют → текст возвращён; нет
|
||||
findings/только P2-P3 → `""`; битый файл → `""`; отсутствующий путь → `""`;
|
||||
для test-report: FAIL-фрагмент извлечён / пустой отчёт → `""`.
|
||||
- **FAIL:** падение существующих тестов или отсутствие перечисленных кейсов.
|
||||
|
||||
## AC-6 — Retry-счётчик и rollback НЕ изменены по поведению
|
||||
|
||||
**Условие:** логика `_developer_retry_count`, `MAX_DEVELOPER_RETRIES = 3`,
|
||||
последовательность откатов и поля `AdvanceResult` (`rolled_back_to`,
|
||||
`enqueued_agent`, `enqueued_job_id`, `alerted`) идентичны прежним.
|
||||
|
||||
- **PASS:** существующие тесты `test_stage_engine.py` на rollback/retry зелёные;
|
||||
при 4-м заходе по-прежнему alert вместо enqueue; меняется только текст
|
||||
`task_desc`.
|
||||
- **FAIL:** изменилось число retry, порядок вызовов, или значения полей
|
||||
`AdvanceResult`.
|
||||
|
||||
## AC-7 — Out-of-scope не затронут
|
||||
|
||||
**Условие:** не изменены: `check_*` гейты, реестр `QG_CHECKS`, сигнатуры
|
||||
публичных функций (`advance_stage`, `_run_qg`, `check_*`), webhook-пути, формат
|
||||
Plane-комментариев.
|
||||
|
||||
- **PASS:** `git diff` не содержит изменений в `src/qg/checks.py` (логика
|
||||
гейтов), сигнатурах публичных функций, `src/webhooks/*`,
|
||||
`usage.build_status_comment`; `test_qg_registry_snapshot` зелёный.
|
||||
- **FAIL:** любое из перечисленного изменено.
|
||||
|
||||
## AC-8 — Документация и ADR обновлены (golden source)
|
||||
|
||||
**Условие:** правка ядра → заведён ADR (`06-adr/`), обновлён `CHANGELOG.md`, при
|
||||
необходимости — `docs/architecture/README.md`/`internals.md` (раздел Stage
|
||||
Engine / Откаты).
|
||||
|
||||
- **PASS:** присутствует `docs/work-items/ORCH-046/06-adr/ADR-001-*.md`; в
|
||||
`CHANGELOG.md` есть запись ORCH-046.
|
||||
- **FAIL:** ADR или запись в CHANGELOG отсутствуют.
|
||||
@@ -1,108 +0,0 @@
|
||||
work_item: ORCH-046
|
||||
description: >
|
||||
Тест-план для встраивания дословного текста findings reviewer/tester в
|
||||
task_desc при заворотах деву. Покрывает новый парсер src/review_parse.py
|
||||
(graceful, never-raise) и две rollback-ветки src/stage_engine.py.
|
||||
|
||||
tests:
|
||||
# --- Парсер review findings (extract_review_findings) -------------------
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "extract_review_findings возвращает дословный текст P0/P1 при их наличии в 12-review.md"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-1, AC-5]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "extract_review_findings возвращает '' когда есть только P2/P3 (нет must-fix P0/P1)"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-5]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "extract_review_findings возвращает '' для отсутствующего файла (несуществующий путь), без исключения"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-4]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "extract_review_findings возвращает '' для битого/пустого файла или markdown без секции ## Findings, без исключения"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-4, AC-5]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "extract_review_findings усекает очень длинные findings до лимита с маркером truncated"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-1]
|
||||
expected: PASS
|
||||
|
||||
# --- Парсер test failures (extract_test_failures) ----------------------
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "extract_test_failures извлекает релевантный фрагмент тела (Вывод pytest / FAIL-строки / Итог) из 13-test-report.md с result: FAIL"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-2, AC-5]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "extract_test_failures возвращает '' для отсутствующего файла, без исключения"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-4]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "extract_test_failures возвращает '' для битого/пустого отчёта (нет тела/секций), без исключения"
|
||||
module: tests/test_review_parse.py
|
||||
covers: [AC-4, AC-5]
|
||||
expected: PASS
|
||||
|
||||
# --- Интеграция со stage_engine (rollback task_desc) -------------------
|
||||
- id: TC-09
|
||||
type: integration
|
||||
description: "advance_stage: reviewer REQUEST_CHANGES -> в enqueue_job('developer') task_desc содержит дословные P0/P1 findings И ссылку на 12-review.md"
|
||||
module: tests/test_stage_engine.py
|
||||
covers: [AC-1, AC-3]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: integration
|
||||
description: "advance_stage: tester check_tests_passed FAIL -> task_desc содержит reason + фрагмент 13-test-report.md И ссылку на файл"
|
||||
module: tests/test_stage_engine.py
|
||||
covers: [AC-2, AC-3]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-11
|
||||
type: integration
|
||||
description: "advance_stage: reviewer REQUEST_CHANGES при отсутствующем/битом 12-review.md -> graceful fallback, task_desc = прежняя ссылка-строка, без исключения"
|
||||
module: tests/test_stage_engine.py
|
||||
covers: [AC-4, AC-3]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-12
|
||||
type: integration
|
||||
description: "advance_stage: rollback/retry поведение неизменно — последовательность откатов, _developer_retry_count, alert на 4-й заход, поля AdvanceResult"
|
||||
module: tests/test_stage_engine.py
|
||||
covers: [AC-6]
|
||||
expected: PASS
|
||||
|
||||
# --- Регресс / неизменность out-of-scope ------------------------------
|
||||
- id: TC-13
|
||||
type: integration
|
||||
description: "Реестр QG_CHECKS не изменён (snapshot), гейты check_* нетронуты"
|
||||
module: tests/test_qg_registry_snapshot.py
|
||||
covers: [AC-7]
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: integration
|
||||
description: "Полный регресс существующего набора зелёный: python -m pytest tests/ -q"
|
||||
module: tests/
|
||||
covers: [AC-5, AC-6, AC-7]
|
||||
expected: PASS
|
||||
@@ -1,143 +0,0 @@
|
||||
# ADR-001: дословный текст findings reviewer/tester встраивается в `task_desc` через отдельный graceful-парсер
|
||||
|
||||
- **Статус:** Accepted
|
||||
- **Дата:** 2026-06-06
|
||||
- **Задача:** ORCH-046
|
||||
- **Область:** ЯДРО `src/stage_engine.py` (rollback-ветки) + новый модуль `src/review_parse.py`. Общий прод-инстанс (orchestrator + enduro-trails), self-hosting.
|
||||
|
||||
## Контекст
|
||||
|
||||
При заворотах задачи на `development` (откат) `stage_engine` формирует `task_desc`,
|
||||
который попадает в `.task-dev.md` запускаемого developer-агента. В двух ветках
|
||||
`_handle_qg_failure_rollbacks` этот текст содержит **только ссылку на файл-артефакт**:
|
||||
|
||||
- reviewer REQUEST_CHANGES (`src/stage_engine.py` ~стр. 419) → `…Fix findings in docs/work-items/<id>/12-review.md`;
|
||||
- tester `check_tests_passed` FAIL (~стр. 455) → `…Fix failures described in docs/work-items/<id>/13-test-report.md`.
|
||||
|
||||
Developer-агент получает инструкцию «иди читай файл»; ключевые претензии (P0/P1
|
||||
ревьюера, причина падения тестера) теряются — агент повторяет ту же ошибку, и
|
||||
задача заворачивается снова. Это «испорченный телефон»: расход retry-бюджета
|
||||
(`MAX_DEVELOPER_RETRIES = 3`), токенов и простой конвейера (для всех проектов
|
||||
общего инстанса).
|
||||
|
||||
Ограничение из BRD/ТЗ (вариант A, выбран Owner): минимальная, низкорисковая
|
||||
правка ядра. Любая регрессия в формировании `task_desc` или (тем более)
|
||||
исключение в `advance_stage` останавливает конвейер ВСЕХ проектов — следовательно
|
||||
извлечение текста обязано быть полностью graceful.
|
||||
|
||||
## Решение
|
||||
|
||||
Встраивать **дословный текст ключевых замечаний** в `task_desc` при заворотах,
|
||||
сохраняя ссылку на полный файл как дополнительный контекст. Извлечение вынести в
|
||||
отдельный defensive-модуль, чтобы изолировать blast radius от ядра.
|
||||
|
||||
1. **Новый модуль `src/review_parse.py`** с двумя чистыми функциями чтения с диска:
|
||||
- `extract_review_findings(path: str) -> str` — дословные пункты P0/P1 из секции
|
||||
`## Findings` файла `12-review.md`;
|
||||
- `extract_test_failures(path: str) -> str` — релевантный фрагмент тела
|
||||
`13-test-report.md` (приоритет: `## Вывод pytest` → FAIL-строки `## Результаты`
|
||||
→ `## Итог`).
|
||||
- **Контракт «never raise»** (как `src/frontmatter.py` и
|
||||
`src/qg/checks.py::_parse_tests_verdict`): любая ошибка — нет файла, IOError,
|
||||
кривой markdown/YAML, нет секции — возвращает `""`. Логирование на
|
||||
`logger.debug` (`logging.getLogger("orchestrator.review_parse")`). Никаких
|
||||
сетевых вызовов.
|
||||
- Результат усекается модульными лимитами `MAX_FINDINGS_CHARS`,
|
||||
`MAX_FAILURES_CHARS` (≈2000) с маркером `…(truncated)`; полный контекст всегда
|
||||
остаётся в файле.
|
||||
|
||||
2. **Две ветки `_handle_qg_failure_rollbacks` в `src/stage_engine.py`** строят путь
|
||||
через `get_worktree_path(repo, branch)` (как `_check_review_approved_by_branch`),
|
||||
вызывают соответствующий парсер и:
|
||||
- если результат непустой — встраивают findings/фрагмент **дословно** под
|
||||
подзаголовком + оставляют ссылку как «полный контекст»;
|
||||
- если результат пустой — `task_desc` остаётся **как сейчас** (graceful fallback
|
||||
на ссылку-строку);
|
||||
- tester-ветка дополнительно всегда включает `reason` из гейта (он уже доступен).
|
||||
|
||||
3. **Изоляция ядра.** Меняется ТОЛЬКО содержимое строки `task_desc`, передаваемой в
|
||||
`enqueue_job`. Последовательность отката (`update_task_stage` →
|
||||
`notify_stage_change` → `plane_notify_stage` → [`set_issue_in_progress` для
|
||||
тестера] → проверка `_developer_retry_count` < `MAX_DEVELOPER_RETRIES` →
|
||||
`enqueue_job`/`send_telegram`), значения `AdvanceResult` (`rolled_back_to`,
|
||||
`enqueued_agent`, `enqueued_job_id`, `alerted`) и Plane-комментарии — без
|
||||
изменений.
|
||||
|
||||
### Почему отдельный модуль, а не inline в `stage_engine`
|
||||
|
||||
- Тестируемость: парсер покрывается юнит-тестами `tests/test_review_parse.py`
|
||||
изолированно от тяжёлого `advance_stage`.
|
||||
- Blast radius: вся парсинг-логика (и её исключения) физически отделена от
|
||||
hot-path ядра; ядро только подставляет строку и делает try-around-граничный
|
||||
fallback.
|
||||
- Согласованность с уже принятым паттерном defensive-парсеров
|
||||
(`frontmatter.py`).
|
||||
|
||||
### Почему НЕ переиспользуется `frontmatter.read_frontmatter_value`
|
||||
|
||||
Тот хелпер читает одиночное значение из YAML-frontmatter. Здесь нужно извлекать
|
||||
**тело markdown** (подсекции `## Findings`/`### P0`, фрагменты `## Вывод pytest`),
|
||||
а не frontmatter-ключ. Это другая задача парсинга; общий контракт «never raise»
|
||||
повторяется намеренно (как уже зафиксировано в ORCH-016/ADR-001 §5 — слияние
|
||||
парсеров отдельной задачей).
|
||||
|
||||
### Почему per-work-item ADR, а не глобальный
|
||||
|
||||
Изменение НЕ добавляет гейт/стадию/компонент и НЕ меняет топологию или реестр
|
||||
`QG_CHECKS` — это обогащение содержимого `task_desc` в существующих rollback-ветках
|
||||
плюс вспомогательный модуль. По прецеденту ORCH-047/ADR-001 такого класса правки
|
||||
фиксируются per-work-item ADR. Глобальный `docs/architecture/adr/` не требуется.
|
||||
|
||||
### Альтернативы (отклонены)
|
||||
|
||||
- **Inline-парсинг прямо в `stage_engine`** — отклонено: раздувает ядро, хуже
|
||||
тестируется, исключения ближе к hot-path.
|
||||
- **Менять промпты reviewer/tester, чтобы они сами клали суть в `task_desc`** —
|
||||
отклонено: `task_desc` формирует ядро, а не агент; зависит от дисциплины двух
|
||||
агентов вместо детерминированного кода; шире поверхность регрессии.
|
||||
- **Передавать весь файл целиком в `task_desc`** — отклонено: раздувает промпт
|
||||
developer-агента и стоимость токенов; теряется фокус на must-fix. Усечение по
|
||||
P0/P1 + лимит решает проблему «испорченного телефона» дешевле.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **Плюс:** developer-агент видит суть претензий (P0/P1, причина FAIL) сразу в
|
||||
`.task-dev.md`; меньше повторных заворотов, экономия retry-бюджета и токенов на
|
||||
всех проектах общего инстанса.
|
||||
- **Плюс:** при битом/отсутствующем артефакте поведение не хуже текущего (ссылка
|
||||
сохраняется); ссылка на полный файл присутствует всегда (AC-3).
|
||||
- **Плюс:** изменение аддитивное — публичные сигнатуры (`advance_stage`, `_run_qg`,
|
||||
`check_*`), реестр `QG_CHECKS`, webhook-пути и `build_status_comment` не
|
||||
затрагиваются; снапшот `test_qg_registry_snapshot` остаётся зелёным (AC-7).
|
||||
- **Минус/ограничение:** парсинг тела markdown чувствительнее к формату артефактов,
|
||||
чем чтение одного frontmatter-ключа. Митигировано: распознавание P0/P1 устойчиво
|
||||
к регистру/тире; при несовпадении формата — пустой результат и fallback на
|
||||
ссылку (никогда не исключение).
|
||||
- **Минус:** усечение лимитом может обрезать длинные findings — приемлемо, полный
|
||||
контекст остаётся в файле, ссылка сохранена.
|
||||
- **Self-hosting риск:** правка ядра в общем прод-контейнере. Обязателен прогон
|
||||
`deploy-staging` (8501) перед прод-деплоем; прод-контейнер `orchestrator` (8500)
|
||||
не перезапускать в рамках разработки/тестинга. Граничный риск — исключение из
|
||||
парсера в `advance_stage`; закрыт контрактом «never raise» + юнит-кейсами на
|
||||
битый/пустой/отсутствующий ввод (AC-4, AC-5).
|
||||
|
||||
## Влияние на документацию (golden source)
|
||||
|
||||
В PR разработки (вместе с кодом) обновить:
|
||||
- `docs/architecture/README.md` — раздел **Stage Engine** / **Откаты**: упомянуть,
|
||||
что `task_desc` при заворотах reviewer/tester несёт дословные findings + ссылку,
|
||||
и новый модуль `src/review_parse.py` (defensive, never-raise).
|
||||
- `CHANGELOG.md` — запись ORCH-046.
|
||||
- `docs/architecture/internals.md` — по усмотрению reviewer, если детализируется
|
||||
поток отката.
|
||||
|
||||
## Связи
|
||||
|
||||
- BRD/ТЗ/AC: `docs/work-items/ORCH-046/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`.
|
||||
- Образцы паттерна «never raise»: `src/frontmatter.py`,
|
||||
`src/qg/checks.py::_parse_tests_verdict`.
|
||||
- Каноны артефактов: `.openclaw/agents/reviewer.md` (`12-review.md` `## Findings`),
|
||||
`.openclaw/agents/tester.md` (`13-test-report.md` `result:` + тело).
|
||||
- Прецедент per-work-item ADR на правку парсинга: ORCH-047/ADR-001.
|
||||
- Технические риски: `docs/work-items/ORCH-046/10-tech-risks.md`.
|
||||
- Staging-страховка: `docs/architecture/adr/adr-0003-staging-gate.md`.
|
||||
@@ -1,29 +0,0 @@
|
||||
# Технические риски — ORCH-046
|
||||
|
||||
Work Item ID: ORCH-046
|
||||
Stage: architecture
|
||||
Author: architect
|
||||
Date: 2026-06-06
|
||||
|
||||
Связано: `06-adr/ADR-001-embed-findings-in-task-desc.md`.
|
||||
|
||||
| # | Риск | Вероятн. | Влияние | Митигация | Контроль (AC/тест) |
|
||||
|---|------|----------|---------|-----------|--------------------|
|
||||
| R-1 | Исключение из парсера всплывает в `advance_stage` → встаёт конвейер ВСЕХ проектов (self-hosting, общий инстанс) | Низк. | **Критич.** | Контракт «never raise» в `review_parse.py`; вызов в `stage_engine` обёрнут так, что пустой результат → fallback на прежнюю ссылку-строку | AC-4; юнит-кейсы «нет файла / битый YAML / пустой / только P3» в `tests/test_review_parse.py` |
|
||||
| R-2 | Регрессия в последовательности отката или полях `AdvanceResult` (меняется не только `task_desc`) | Низк. | Высок. | Жёсткий инвариант ТЗ §3.3: трогать ТОЛЬКО строку `task_desc`; порядок вызовов и условия retry неизменны | AC-6; существующие `tests/test_stage_engine.py` (rollback/retry) зелёные |
|
||||
| R-3 | Парсер чувствителен к формату артефактов: дрейф `12-review.md`/`13-test-report.md` → пустой результат | Сред. | Низк. | Распознавание P0/P1 устойчиво к регистру/тире; при несовпадении → `""` + fallback на ссылку (деградация, не отказ) | AC-1/AC-2/AC-4 |
|
||||
| R-4 | Раздувание `task_desc` длинными findings → рост стоимости/потеря фокуса developer-агента | Сред. | Низк. | Лимиты `MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS` (~2000) + маркер `…(truncated)`; only P0/P1 (P2/P3 отброшены) | AC-1; проверка усечения в юнит-тестах |
|
||||
| R-5 | Случайный выход за out-of-scope (правка `check_*`, `QG_CHECKS`, сигнатур, webhooks, `build_status_comment`) | Низк. | Сред. | Явный out-of-scope в ТЗ §4/§6; ревью diff | AC-7; `test_qg_registry_snapshot` зелёный |
|
||||
| R-6 | Прод-деплой self без страховки staging | Низк. | **Критич.** | Обязательная стадия `deploy-staging` (8501); прод `orchestrator` (8500) не рестартить в разработке/тестинге | adr-0003; стадийный гейт `check_staging_status` |
|
||||
| R-7 | Дублирование defensive-парсинга (3-й модуль рядом с `frontmatter.py` и `_parse_tests_verdict`) → техдолг | Сред. | Низк. | Осознанно принято (как ORCH-016/ADR-001 §5): малый blast radius важнее DRY; слияние парсеров — отдельная follow-up задача | — (техдолг, не блокер) |
|
||||
|
||||
## Заметки
|
||||
|
||||
- **Граничный try в ядре.** Даже при контракте «never raise» в `review_parse`,
|
||||
вызов в `stage_engine` следует считать недоверенным: подстановка результата в
|
||||
`task_desc` не должна зависеть от внутренней корректности парсера. Fallback на
|
||||
ссылку-строку обязателен и при пустом результате, и при любой неожиданности.
|
||||
- **Эскалация не требуется.** Изменение укладывается в принципы (минимум
|
||||
зависимостей, raw-парсинг без новых либ, без новых компонентов/стадий/QG).
|
||||
Лейбл `arch:major-change` НЕ ставится; возврат в Анализ не требуется — ТЗ
|
||||
реализуемо без нарушения принципов.
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-046
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-046
|
||||
|
||||
## Summary
|
||||
|
||||
Правка ядра «вариант A»: при заворотах на `development` `task_desc` теперь несёт
|
||||
**дословный must-fix текст** (P0/P1 ревьюера, причина FAIL тестера) вместо одной
|
||||
ссылки на файл. Извлечение вынесено в новый defensive-модуль `src/review_parse.py`
|
||||
с контрактом «never raise»; две rollback-ветки `_handle_qg_failure_rollbacks`
|
||||
встраивают текст и сохраняют ссылку как «Полный контекст», при пустом/битом
|
||||
артефакте — graceful-фоллбэк на прежнюю строку.
|
||||
|
||||
Реализация полностью соответствует ТЗ (`02-trz.md`), ADR-001 и всем критериям
|
||||
приёмки. Документация обновлена в этом же PR. Тесты зелёные (`461 passed`).
|
||||
|
||||
Проверено по осям:
|
||||
|
||||
**1. Соответствие ТЗ.** Сигнатуры `extract_review_findings`/`extract_test_failures`
|
||||
точно как в ТЗ §2; never-raise, логирование на `logger.debug`, модульные лимиты
|
||||
`MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS`, отбрасывание frontmatter, устойчивость
|
||||
P0/P1-заголовков к регистру/тире, пропуск плейсхолдеров `(если есть)`/`<…>`,
|
||||
приоритет источников тестера (`## Вывод pytest` → FAIL-строки `## Результаты` →
|
||||
`## Итог`). Префикс `task_desc`, `reason` в tester-ветке, ссылка-фоллбэк — как
|
||||
предписано §3. API/БД/QG не тронуты (§4–6).
|
||||
|
||||
**2. Соответствие ADR-001.** Отдельный модуль (blast radius), путь через
|
||||
`get_worktree_path`, изоляция ядра (меняется только строка `task_desc`),
|
||||
последовательность отката и поля `AdvanceResult` сохранены. Per-work-item ADR
|
||||
обоснован. Реализация ⇄ решение совпадают.
|
||||
|
||||
**3. Качество кода.** Docstrings на всех публичных функциях; defensive `_read`
|
||||
ловит `OSError`, внешний `try/except Exception` в обоих экстракторах гарантирует
|
||||
never-raise (подтверждено кейсом на directory-path). Регэксп `_P01_HEADER_RE`
|
||||
корректно отсекает ложные совпадения (`P05` и т.п.). Код читабелен, без дублей.
|
||||
|
||||
**4. Качество тестов.** `tests/test_review_parse.py` покрывает TC-01..08 (findings
|
||||
есть / только P2-P3 / нет файла / битый YAML / усечение / регистр-тире / directory).
|
||||
`tests/test_stage_engine.py::TestRollbackTaskDescEmbedding` проверяет встраивание
|
||||
в обе ветки, graceful-фоллбэк, неизменность retry/rollback на 4-м заходе (alert
|
||||
вместо enqueue). Содержательные, не тривиальные.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- [ ] (нет)
|
||||
|
||||
### P1 — Must fix
|
||||
- [ ] (нет)
|
||||
|
||||
### P2 — Should fix
|
||||
- [ ] (нет)
|
||||
|
||||
## Соответствие критериям приёмки
|
||||
|
||||
- AC-1 (дословные P0/P1 в `task_desc`) — PASS: `Findings (P0/P1):\n{findings}`.
|
||||
- AC-2 (причина тестера: `reason` + фрагмент тела) — PASS: `Причина: {reason}` + `Детали:`.
|
||||
- AC-3 (ссылка на полный файл сохранена) — PASS: «Полный контекст»/fallback-ссылка в обеих ветках.
|
||||
- AC-4 (graceful never-raise) — PASS: `""`→ссылка-фоллбэк, исключений нет (тесты TC-03/04/07/08, directory-path).
|
||||
- AC-5 (тесты зелёные + новые юнит-тесты) — PASS: `461 passed`; все перечисленные кейсы присутствуют.
|
||||
- AC-6 (retry/rollback не изменены) — PASS: TC-12 + существующие rollback-тесты зелёные.
|
||||
- AC-7 (out-of-scope не затронут) — PASS: diff не касается `src/qg/checks.py`, `src/webhooks/*`, `usage.py`, `stages.py`, `main.py`; сигнатуры публичных функций не менялись.
|
||||
- AC-8 (документация + ADR) — PASS: ADR-001 заведён, `CHANGELOG.md` и `docs/architecture/README.md` обновлены.
|
||||
|
||||
## Документация
|
||||
|
||||
Обновлена корректно и в том же PR (golden source соблюдён):
|
||||
- `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md` — заведён (правка ядра).
|
||||
- `CHANGELOG.md` — запись ORCH-046 в `[Unreleased] / Added`.
|
||||
- `docs/architecture/README.md` — добавлен компонент **Review/Test Parsers** и раздел **Обогащение `task_desc` при заворотах (ORCH-046)**.
|
||||
|
||||
Изменение `src/` сопровождено обновлением документации — требование п.4/п.6 правил
|
||||
агентов выполнено.
|
||||
|
||||
## Примечание (self-hosting)
|
||||
Правка ядра в общем прод-инстансе. Перед прод-деплоем обязательна стадия
|
||||
`deploy-staging` (8501) согласно ADR-001 / CLAUDE.md — это страховка следующих
|
||||
стадий, не блокер ревью.
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-046
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-046
|
||||
|
||||
Встраивание дословного must-fix текста findings reviewer/tester в `task_desc`
|
||||
при заворотах на `development` (новый модуль `src/review_parse.py` + две
|
||||
rollback-ветки `src/stage_engine.py`).
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3 (asyncio mode=AUTO)
|
||||
- Ветка: feature/ORCH-046-stage-engine-pass-reviewer-tes
|
||||
- Дата: 2026-06-06
|
||||
|
||||
## Результаты
|
||||
|
||||
| TC ID | Описание | Покрывает | Результат |
|
||||
|-------|----------|-----------|-----------|
|
||||
| TC-01 | `extract_review_findings` возвращает дословный P0/P1 текст | AC-1, AC-5 | PASS |
|
||||
| TC-02 | `extract_review_findings` → `""` при только P2/P3 | AC-5 | PASS |
|
||||
| TC-03 | `extract_review_findings` → `""` для отсутствующего файла | AC-4 | PASS |
|
||||
| TC-04 | `extract_review_findings` → `""` для битого/без секции файла | AC-4, AC-5 | PASS |
|
||||
| TC-05 | `extract_review_findings` усекает длинный текст с маркером truncated | AC-1 | PASS |
|
||||
| TC-06 | `extract_test_failures` извлекает фрагмент тела (Вывод pytest/FAIL/Итог) | AC-2, AC-5 | PASS |
|
||||
| TC-07 | `extract_test_failures` → `""` для отсутствующего файла | AC-4 | PASS |
|
||||
| TC-08 | `extract_test_failures` → `""` для битого/пустого отчёта | AC-4, AC-5 | PASS |
|
||||
| TC-09 | reviewer REQUEST_CHANGES → `task_desc` содержит P0/P1 + ссылку | AC-1, AC-3 | PASS |
|
||||
| TC-10 | tester FAIL → `task_desc` содержит reason + фрагмент + ссылку | AC-2, AC-3 | PASS |
|
||||
| TC-11 | graceful fallback при отсутствующем/битом файле (обе ветки) | AC-4, AC-3 | PASS |
|
||||
| TC-12 | rollback/retry поведение неизменно (alert на 4-й заход, поля AdvanceResult) | AC-6 | PASS |
|
||||
| TC-13 | Реестр `QG_CHECKS` не изменён (snapshot), гейты нетронуты | AC-7 | PASS |
|
||||
| TC-14 | Полный регресс существующего набора зелёный | AC-5, AC-6, AC-7 | PASS |
|
||||
|
||||
Сопоставление TC ↔ тесты:
|
||||
- TC-01..08 → `tests/test_review_parse.py` (`TestExtractReviewFindings`, `TestExtractTestFailures`), 14 кейсов, все PASS.
|
||||
- TC-09..12 → `tests/test_stage_engine.py::TestRollbackTaskDescEmbedding`, все PASS.
|
||||
- TC-13 → `tests/test_qg_registry_snapshot.py` (registry/callables/transitions snapshot), все PASS.
|
||||
- TC-14 → полный прогон `pytest tests/` → **461 passed**.
|
||||
|
||||
## Smoke test API (read-only, прод-инстанс не затронут)
|
||||
|
||||
| Endpoint | HTTP | Ответ |
|
||||
|----------|------|-------|
|
||||
| GET /health | 200 | `{"status":"ok","service":"orchestrator"}` |
|
||||
| GET /status | 200 | active_tasks включает task 37 (ORCH-046, stage=testing) |
|
||||
| GET /queue | 200 | counts: queued=0, running=1, failed=0; breaker=closed; preflight_ok=true |
|
||||
|
||||
> `curl` в окружении отсутствует — smoke выполнен через `urllib`. Только GET-запросы,
|
||||
> деструктивных операций над прод-контейнером не выполнялось (self-hosting safety).
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
```
|
||||
============================= test session starts ==============================
|
||||
platform linux -- Python 3.12.13, pytest-8.3.3, pluggy-1.6.0
|
||||
rootdir: .../feature_ORCH-046-stage-engine-pass-reviewer-tes
|
||||
configfile: pytest.ini
|
||||
plugins: anyio-4.13.0, asyncio-0.23.8
|
||||
asyncio: mode=Mode.AUTO
|
||||
...
|
||||
======================== 461 passed, 1 warning in 7.59s ========================
|
||||
```
|
||||
|
||||
Прицельный прогон ORCH-046 (`test_review_parse.py` + `test_stage_engine.py` +
|
||||
`test_qg_registry_snapshot.py`): **53 passed**.
|
||||
|
||||
Единственный warning — преэкзистентный `PydanticDeprecatedSince20` в `src/config.py`
|
||||
(не связан с ORCH-046).
|
||||
|
||||
## Покрытие критериев приёмки
|
||||
|
||||
| AC | Критерий | Подтверждение | Статус |
|
||||
|----|----------|---------------|--------|
|
||||
| AC-1 | Дословные P0/P1 в `task_desc` | TC-01, TC-09 | PASS |
|
||||
| AC-2 | Причина тестера (reason + фрагмент) в `task_desc` | TC-06, TC-10 | PASS |
|
||||
| AC-3 | Ссылка на полный файл сохранена | TC-09, TC-10, TC-11 | PASS |
|
||||
| AC-4 | Парсер graceful (never-raise) | TC-03, TC-04, TC-07, TC-08, TC-11 | PASS |
|
||||
| AC-5 | Тесты зелёные + новые юнит-тесты | TC-14 (461 passed) | PASS |
|
||||
| AC-6 | Retry/rollback не изменены | TC-12 | PASS |
|
||||
| AC-7 | Out-of-scope не затронут | TC-13 | PASS |
|
||||
| AC-8 | Документация + ADR | проверено reviewer (12-review.md, APPROVED) | PASS |
|
||||
|
||||
## Итог
|
||||
|
||||
**PASS** — все 14 TC из тест-плана зелёные, полный регресс 461 passed,
|
||||
smoke API 200 по всем эндпоинтам, прод-инстанс здоров. Все критерии приёмки
|
||||
выполнены. Задача готова к стадии `deploy-staging` (8501) — обязательной
|
||||
страховке self-hosting перед прод-деплоем.
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
staging_status: FAILED
|
||||
timestamp: 2026-06-06T04:47:45Z
|
||||
base_url: http://localhost:8501
|
||||
mode: stub
|
||||
result: 9/10 checks PASS
|
||||
failed_checks: [B6]
|
||||
---
|
||||
|
||||
# Staging Gate Log — ORCH-046
|
||||
|
||||
Staging test suite **FAILED**. Exit code 1 (9/10 checks passed).
|
||||
|
||||
## Verdict
|
||||
|
||||
The staging gate is **red**: one check failed (`B6`). Per pipeline policy a
|
||||
non-zero staging suite is `staging_status: FAILED` → rollback to `development`.
|
||||
|
||||
## Failed check
|
||||
|
||||
```
|
||||
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent
|
||||
[sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
|
||||
```
|
||||
|
||||
**What it means.** The staging container's project registry is **not isolated**:
|
||||
it sees the production projects `enduro-trails` (ET) and `orchestrator` (ORCH),
|
||||
and the `orchestrator-sandbox` (SANDBOX) project is **absent**. This violates the
|
||||
hard isolation invariant for staging (`docs/operations/INFRA.md`: «Staging видит
|
||||
ТОЛЬКО `orchestrator-sandbox` (SANDBOX) — изоляция»). The staging gate exists
|
||||
precisely to catch this class of safety breach before any prod deploy of the
|
||||
self-hosting orchestrator.
|
||||
|
||||
**Triage note (for humans).** This is a **staging environment / configuration**
|
||||
issue — the staging container's `ORCH_PROJECTS_JSON` is pointing at the prod
|
||||
registry instead of the sandbox-only registry. It is **not** a code regression
|
||||
introduced by the ORCH-046 changeset (which only touches `src/review_parse.py`
|
||||
and rollback `task_desc` enrichment). However, the gate is authoritative and red,
|
||||
so the work item cannot pass to `deploy`. Fix the staging `.env.staging` /
|
||||
`ORCH_PROJECTS_JSON` to expose only SANDBOX, re-run the staging suite, and the
|
||||
gate will go green.
|
||||
|
||||
> ⚠️ Safety note: the first run aborted at `A3` because `ORCH_STAGING` was not
|
||||
> set in the runner env (the script's guard against accidentally hitting prod).
|
||||
> Re-run with `ORCH_STAGING=true` against the staging URL (8501) executed the
|
||||
> full suite. Prod (8500) was never touched.
|
||||
|
||||
## Full suite output
|
||||
|
||||
```
|
||||
============================================================
|
||||
ORCH-33 Staging Check Suite
|
||||
base_url : http://localhost:8501
|
||||
mode : stub
|
||||
utc_time : 2026-06-06T04:47:27.628664+00:00
|
||||
============================================================
|
||||
|
||||
[Block A] SMOKE
|
||||
✓ PASS A1 GET /health → 200 status=ok [HTTP 200, body={'status': 'ok', 'service': 'orchestrator'}]
|
||||
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience [HTTP 200, keys=['counts', 'max_concurrency', 'poll_interval', 'resilience', 'recent']]
|
||||
✓ PASS A3 ORCH_STAGING=true (not prod) [ORCH_STAGING=true]
|
||||
|
||||
[Block B] ACCESS
|
||||
✓ PASS B4 Plane: sandbox project accessible [HTTP 200, found 5 project(s), sandbox=YES]
|
||||
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true [HTTP 200, permissions={'admin': True, 'push': True, 'pull': True}]
|
||||
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
|
||||
|
||||
[Block C] E2E (mode=stub)
|
||||
· C7: Creating issue in SANDBOX project...
|
||||
✓ PASS C7 Create issue in Plane SANDBOX [HTTP 201, issue_id=2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4]
|
||||
· C8: Triggering pipeline via POST /webhook/plane ...
|
||||
· Using HMAC signature (secret len=40)
|
||||
✓ PASS C8 Trigger pipeline via /webhook/plane [HTTP 200, resp={'status': 'accepted'}]
|
||||
· C9a: Polling for branch in orchestrator-sandbox (up to 60s)...
|
||||
✓ PASS C9a Branch appears in orchestrator-sandbox [branch=feature/SANDBOX-011-staging-check-e2e-20260606t044]
|
||||
· C9b: Checking staging job queue for analyst job (up to 30s)...
|
||||
· (Plane comment check skipped: bot-tokens not added to SANDBOX project)
|
||||
✓ PASS C9b Analyst job enqueued in staging queue [job_id=7, status=queued, agent=analyst]
|
||||
|
||||
[CLEANUP]
|
||||
✓ PASS CLEANUP: deleted branch 'feature/SANDBOX-011-staging-check-e2e-20260606t044' (HTTP 204)
|
||||
✓ PASS CLEANUP: deleted Plane issue 2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4 (HTTP 204)
|
||||
· CLEANUP DB: no task row found for plane_id=2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4
|
||||
· CLEANUP DB dedup: no such table: events_dedup
|
||||
|
||||
============================================================
|
||||
RESULT: 9/10 checks PASS
|
||||
============================================================
|
||||
EXIT_CODE=1
|
||||
```
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: check_tests_passed: gate must read result: field from test report
|
||||
|
||||
Work Item ID: ORCH-047
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,57 +0,0 @@
|
||||
# BRD — ORCH-047: check_tests_passed должен читать поле `result:` из тест-отчёта
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
Quality Gate `check_tests_passed` (`src/qg/checks.py`, функция-парсер `_parse_tests_verdict`) гейтит переход `testing → deploy-staging`. Он читает машиночитаемый вердикт из YAML-frontmatter артефакта `13-test-report.md`.
|
||||
|
||||
**Дефект (обнаружен дев-агентом в ходе ORCH-17, подтверждён 05.06.2026):**
|
||||
парсер читает ТОЛЬКО поля `verdict:` и `status:`. Однако промпт тестер-агента (`.openclaw/agents/tester.md`, строки 51–56 и 78–80) предписывает эмитить машиночитаемое поле **`result: PASS|FAIL`** — и НЕ упоминает ни `verdict:`, ни `status:`.
|
||||
|
||||
В результате тестер, честно следующий своей инструкции (реальный отчёт ORCH-017: `result: PASS`, без `verdict:`/`status:`), упирается в ветку «ни verdict, ни status не заданы» → гейт возвращает `False` с причиной *"No machine-readable verdict/status in test report frontmatter"* → задача откатывается `testing → development`.
|
||||
|
||||
**Последствие:** ЛЮБАЯ задача, где тестер пишет `result: PASS` (то есть строго по своей инструкции), застревает в бесконечной петле `testing ↔ development` до исчерпания `MAX_DEVELOPER_RETRIES`. Именно это крутило ORCH-17. ORCH-016 прошёл раньше лишь потому, что его отчёт избыточно нёс И `verdict:`, И `result:`.
|
||||
|
||||
**Корень:** рассинхрон контракта. Гейт (потребитель) и промпт тестера (производитель) описывают разные имена машиночитаемого поля.
|
||||
|
||||
## 2. Бизнес-цель
|
||||
|
||||
Привести контракт гейта `check_tests_passed` в соответствие с тем, что тестер-агенту реально велено эмитить, чтобы корректные тест-отчёты (`result: PASS`) проходили гейт, а отрицательные (`result: FAIL`) — надёжно откатывали задачу. Устранить ложноотрицательные срабатывания, ломающие конвейер всех проектов.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
|
||||
- **Owner / Стрим, Слава** — выявили дефект при разборе ORCH-17 (05.06).
|
||||
- **Все проекты общего прод-инстанса** (orchestrator self-hosting + enduro-trails) — потребители shared quality-gate. Это SHARED-изменение, влияет на всех.
|
||||
- **Тестер-агент** — производитель `13-test-report.md`.
|
||||
|
||||
## 4. Объём работ (scope)
|
||||
|
||||
### В объёме
|
||||
- `_parse_tests_verdict` читает `result:` как первоклассное машиночитаемое поле НАРАВНЕ с `verdict:` и `status:`.
|
||||
- Семантика приоритетов сохраняется и распространяется на все три поля:
|
||||
- negative-токен в ЛЮБОМ из трёх (`result`/`verdict`/`status`) → FAIL и авторитетен (перебивает positive в другом поле);
|
||||
- при отсутствии negative — positive-токен в ЛЮБОМ из трёх → PASS;
|
||||
- ни одно из трёх полей не задано → FAIL (нет машиночитаемого вердикта);
|
||||
- заданы, но не распознаны → FAIL.
|
||||
- Обратная совместимость: отчёты, несущие только `verdict:`/`status:` (стиль enduro-trails ET-001…ET-014, ORCH-016), продолжают работать ровно как раньше.
|
||||
- **ADR** на изменение семантики shared testing-гейта (правило 2 CLAUDE.md — обязательно для сквозного изменения).
|
||||
- Обновление документации: `docs/architecture/README.md` (строка про машинные ключи вердикт-парсера), `CHANGELOG.md`.
|
||||
|
||||
### Вне объёма
|
||||
- Изменение промпта тестера (`.openclaw/agents/tester.md`). Контракт приводится со стороны гейта к тому, что тестеру УЖЕ велено эмитить; промпт не трогаем.
|
||||
- Изменение других гейтов (`check_reviewer_verdict`, `check_deploy_status`, `check_staging_status`) — у них свои поля (`verdict:`, `deploy_status:`, `staging_status:`), они вне этого дефекта.
|
||||
- Изменения ORCH-017 (про ссылки) — это отдельный work item.
|
||||
|
||||
## 5. Ограничения и риски
|
||||
|
||||
- **SHARED quality-gate, общий прод-инстанс.** Изменение затрагивает enduro-trails наравне с orchestrator. Регресс недопустим: набор положительных/отрицательных токенов и поведение для старого формата (`verdict:`/`status:`) должны остаться неизменными.
|
||||
- **Self-hosting.** Орк правит сам себя; деплой проходит через обязательную стадию `deploy-staging` (8501). Прод-контейнер `orchestrator` (8500) не ронять.
|
||||
- Изменение читает только frontmatter, никогда не прозу (канон гейтов из `docs/architecture/README.md`).
|
||||
- Парсер не должен бросать исключения ни при каком вводе (битый YAML, пустой файл, frontmatter-не-mapping) → всегда `(False, reason)`.
|
||||
|
||||
## 6. Эталонный код
|
||||
|
||||
Дев-агент уже написал референс-реализацию в ветке `feature/ORCH-017` (`src/qg/checks.py` + `tests/test_qg.py`, 23 теста). Его допустимо использовать как ориентир, но оформить чисто через данный work item с собственным ADR.
|
||||
|
||||
## 7. Критерий успеха
|
||||
|
||||
Тест-отчёт с одним лишь `result: PASS` проходит гейт `check_tests_passed`; с `result: FAIL` — нет. Старый формат (`verdict:`/`status:`) не регрессирует. Все pytest зелёные. ADR заведён.
|
||||
@@ -1,68 +0,0 @@
|
||||
# ТЗ — ORCH-047: `_parse_tests_verdict` читает `result:` наравне с `verdict:`/`status:`
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
|
||||
| Файл | Что меняется |
|
||||
|------|--------------|
|
||||
| `src/qg/checks.py` | Функция `_parse_tests_verdict` (стр. ~223–265). Добавить чтение поля `result:` из frontmatter и включить его в проверку токенов наравне с `verdict:`/`status:`. Обновить докстринг функции и `check_tests_passed`. |
|
||||
|
||||
Точка входа `check_tests_passed(repo, work_item_id, branch)` (стр. ~182) и реестр `QG_CHECKS` НЕ меняются (сигнатура и имя гейта те же).
|
||||
|
||||
## 2. Требуемое поведение `_parse_tests_verdict`
|
||||
|
||||
Вход — строковое тело `13-test-report.md`. Выход — `tuple[bool, str]`.
|
||||
|
||||
1. Нет frontmatter (`content` не начинается с `---`) → `(False, "No YAML frontmatter ...")`.
|
||||
2. Frontmatter некорректен (split по `---` даёт < 3 частей) → `(False, "Malformed YAML frontmatter ...")`.
|
||||
3. YAML не парсится → `(False, "Invalid YAML frontmatter ...: <e>")` (никогда не raise).
|
||||
4. YAML не mapping → `(False, "Malformed YAML frontmatter ... (not a mapping)")`.
|
||||
5. Прочитать три поля, нормализовать (`str(...).upper().strip()`, защита от `None`):
|
||||
- `verdict`
|
||||
- `status`
|
||||
- **`result` ← НОВОЕ**
|
||||
6. Если ВСЕ три пусты → `(False, "No machine-readable verdict/status/result in test report frontmatter")`.
|
||||
7. Собрать объединённую строку полей `fields = f"{verdict} {status} {result}"`.
|
||||
8. Если в `fields` встречается ЛЮБОЙ negative-токен (`_TESTS_NEGATIVE_TOKENS`) → `(False, "Test verdict: <значение> (<NEG>)")`. **Negative авторитетен** — проверяется ПЕРВЫМ, перебивает любой positive.
|
||||
9. Иначе если встречается ЛЮБОЙ positive-токен (`_TESTS_POSITIVE_TOKENS`) → `(True, "Test verdict: <значение> (PASS)")`.
|
||||
10. Иначе (заданы, но не распознаны) → `(False, "No recognized PASS verdict in frontmatter (...)")`.
|
||||
|
||||
Наборы токенов НЕ изменяются (важно для обратной совместимости с enduro-trails):
|
||||
```python
|
||||
_TESTS_NEGATIVE_TOKENS = ("BLOCKED", "FAILED", "FAIL", "REQUEST_CHANGES", "REJECT", "RED")
|
||||
_TESTS_POSITIVE_TOKENS = ("PASSED", "PASS", "READY-TO-DEPLOY", "READY_TO_DEPLOY", "GREEN", "APPROVED")
|
||||
```
|
||||
|
||||
> Примечание для разработчика (порядок токенов): negative-список проверяется раньше positive — это даёт авторитетность отрицания. Внутри positive-набора `"PASSED"` идёт перед `"PASS"` лишь для аккуратного reason-текста; на результат (bool) порядок не влияет, т.к. это подстрочный поиск.
|
||||
|
||||
## 3. Контракт поля (golden source)
|
||||
|
||||
После изменения машиночитаемыми полями testing-гейта считаются **три равноправных**: `result:` (канон промпта тестера), `verdict:`, `status:` (легаси/enduro-trails). Достаточно ЛЮБОГО одного. Это и есть приведение гейта к тому, что тестеру велено эмитить в `.openclaw/agents/tester.md` (`result: PASS|FAIL`).
|
||||
|
||||
## 4. Изменения API
|
||||
|
||||
Нет. HTTP-эндпоинты (`/health`, `/status`, `/queue`, вебхуки) не затрагиваются. Сигнатуры функций гейта не меняются.
|
||||
|
||||
## 5. Изменения схемы БД
|
||||
|
||||
Нет.
|
||||
|
||||
## 6. Требования к новым QG checks
|
||||
|
||||
Новых гейтов нет. Меняется внутренняя логика существующего `check_tests_passed` (через `_parse_tests_verdict`). Реестр `QG_CHECKS` без изменений → снапшот-тест `tests/test_qg_registry_snapshot.py` должен остаться зелёным.
|
||||
|
||||
## 7. Артефакты pipeline (создать/обновить в этом PR)
|
||||
|
||||
- `docs/work-items/ORCH-047/06-adr/ADR-001-*.md` — **обязательно** (правило 2 CLAUDE.md): ADR на изменение семантики SHARED testing-гейта (влияет на все проекты общего инстанса). Заводит архитектор.
|
||||
- `docs/architecture/README.md` — обновить строку о вердикт-парсере (раздел «Plane Sync», п. про машинные ключи): для testing-гейта перечислить `result:`/`verdict:`/`status:`.
|
||||
- `CHANGELOG.md` — запись `fix:` про ORCH-047.
|
||||
- `tests/test_qg.py` — добавить кейсы на `result:` (см. `04-test-plan.yaml`).
|
||||
|
||||
## 8. Нефункциональные требования
|
||||
|
||||
- Парсер не бросает исключений ни на каком вводе.
|
||||
- Изменение читает только frontmatter, не прозу (канон гейтов).
|
||||
- Полная обратная совместимость: существующие тесты `TestCheckTestsPassed` остаются зелёными без правок (кроме, возможно, переименования reason-строки в п.6 BRD — текст причины «No machine-readable verdict/status...» обновляется на «...verdict/status/result...», соответствующий ассерт при наличии обновить).
|
||||
|
||||
## 9. Деплой
|
||||
|
||||
Self-hosting: стандартный путь через `deploy-staging` (8501) перед прод-деплоем. Прод-контейнер `orchestrator` (8500) не перезапускать в рамках разработки/тестинга.
|
||||
@@ -1,68 +0,0 @@
|
||||
# Критерии приёмки — ORCH-047
|
||||
|
||||
Каждый критерий имеет однозначное условие PASS/FAIL.
|
||||
|
||||
## AC-01 — `result: PASS` проходит гейт (главный кейс ORCH-17)
|
||||
- **Дано:** `13-test-report.md` с frontmatter, содержащим только `result: PASS` (без `verdict:`/`status:`).
|
||||
- **Ожидается:** `check_tests_passed(...)` → `(True, ...)`, в reason присутствует «PASS».
|
||||
- **PASS:** возвращается True. **FAIL:** возвращается False.
|
||||
|
||||
## AC-02 — `result: FAIL` откатывает задачу
|
||||
- **Дано:** frontmatter с `result: FAIL` (без `verdict:`/`status:`).
|
||||
- **Ожидается:** `(False, ...)`, reason содержит токен отрицания (`FAIL`).
|
||||
- **PASS:** False. **FAIL:** True.
|
||||
|
||||
## AC-03 — Negative авторитетен поверх positive (в т.ч. между полями)
|
||||
- **Дано:** `result: PASS`, но `verdict: BLOCKED` (или `status: failed`).
|
||||
- **Ожидается:** `(False, ...)`, reason упоминает negative-токен (`BLOCKED`/`FAILED`).
|
||||
- **PASS:** False. **FAIL:** True.
|
||||
|
||||
## AC-04 — Positive в любом из трёх полей даёт PASS
|
||||
- **Дано (каждый подкейс отдельно):**
|
||||
- только `verdict: PASS`;
|
||||
- только `status: PASSED`;
|
||||
- только `result: ready-to-deploy`.
|
||||
- **Ожидается:** все три → `(True, ...)`.
|
||||
- **PASS:** все True. **FAIL:** хоть один False.
|
||||
|
||||
## AC-05 — Обратная совместимость (enduro-trails / ORCH-016)
|
||||
- **Дано:** существующие реальные формы из `TestCheckTestsPassed`:
|
||||
- `verdict: PASS` + `status: pass`;
|
||||
- `verdict: PASS — ready-to-deploy`;
|
||||
- `verdict: ready-to-deploy` + `status: PASSED`;
|
||||
- `verdict: stage:ready-to-deploy` + `status: pass`;
|
||||
- `verdict: BLOCKED` + проза «23 passed».
|
||||
- **Ожидается:** результаты идентичны прежним (PASS-кейсы → True, BLOCKED → False). Старые тесты `TestCheckTestsPassed` зелёные.
|
||||
- **PASS:** поведение не изменилось. **FAIL:** любой регресс.
|
||||
|
||||
## AC-06 — Ни одно из трёх полей не задано → FAIL
|
||||
- **Дано:** frontmatter без `result`/`verdict`/`status` (например, только `type:`/`version:`); тело может содержать «Result: PASS» прозой.
|
||||
- **Ожидается:** `(False, ...)`, причина про отсутствие машиночитаемого вердикта.
|
||||
- **PASS:** False. **FAIL:** True.
|
||||
|
||||
## AC-07 — Только проза, без frontmatter → FAIL
|
||||
- **Дано:** отчёт без YAML-frontmatter, в теле «Result: PASS / All tests passed».
|
||||
- **Ожидается:** `(False, ...)`, причина про отсутствие frontmatter. Прозу не читаем.
|
||||
- **PASS:** False. **FAIL:** True.
|
||||
|
||||
## AC-08 — Битый YAML → FAIL без исключения
|
||||
- **Дано:** некорректный YAML во frontmatter.
|
||||
- **Ожидается:** `(False, ...)` c упоминанием YAML/frontmatter, функция НЕ бросает исключение.
|
||||
- **PASS:** False и нет raise. **FAIL:** raise или True.
|
||||
|
||||
## AC-09 — Отчёт отсутствует → FAIL
|
||||
- **Дано:** файла `13-test-report.md` нет.
|
||||
- **Ожидается:** `(False, "...not found...")`.
|
||||
- **PASS:** False. **FAIL:** True.
|
||||
|
||||
## AC-10 — Реестр гейтов неизменен
|
||||
- **Ожидается:** `QG_CHECKS` содержит ровно те же ключи, что и до изменения; `tests/test_qg_registry_snapshot.py` зелёный.
|
||||
- **PASS:** снапшот совпал. **FAIL:** снапшот изменился.
|
||||
|
||||
## AC-11 — Документация и ADR обновлены (правило 2/6 CLAUDE.md)
|
||||
- **Ожидается:** заведён `docs/work-items/ORCH-047/06-adr/ADR-001-*.md`; обновлены `docs/architecture/README.md` (вердикт-парсер testing-гейта) и `CHANGELOG.md`.
|
||||
- **PASS:** все три присутствуют и описывают изменение. **FAIL:** что-либо отсутствует → REQUEST_CHANGES на review.
|
||||
|
||||
## AC-12 — Полный регресс зелёный
|
||||
- **Ожидается:** `pytest tests/ -q` — все тесты PASS.
|
||||
- **PASS:** exit code 0. **FAIL:** любой упавший тест.
|
||||
@@ -1,97 +0,0 @@
|
||||
work_item: ORCH-047
|
||||
module_under_test: src/qg/checks.py::_parse_tests_verdict (via check_tests_passed)
|
||||
test_file: tests/test_qg.py
|
||||
notes: >
|
||||
Добавить в класс TestCheckTestsPassed. Шаблон записи отчёта — существующий
|
||||
хелпер self._write(dir, content). Наборы токенов не меняются; проверяем, что
|
||||
поле result: теперь равноправно с verdict:/status:, а старые кейсы не регрессируют.
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: "result: PASS без verdict/status -> гейт PASS (главный кейс ORCH-17, AC-01)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\ntype: test-report\nresult: PASS\n---\n\n# Test Report\n"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: "result: FAIL без verdict/status -> гейт FAIL, reason содержит FAIL (AC-02)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nresult: FAIL\n---\n\nbody\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: "result: PASS, но verdict: BLOCKED -> negative авторитетен -> FAIL (AC-03)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nresult: PASS\nverdict: BLOCKED\n---\n\n23 passed\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: "result: PASS, но status: failed -> negative авторитетен -> FAIL (AC-03)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nresult: PASS\nstatus: failed\n---\n\nbody\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: "result: ready-to-deploy (positive-токен, без слова PASS) -> PASS (AC-04)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nresult: ready-to-deploy\n---\n\nbody\n"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: "Только verdict: PASS (легаси) -> PASS, без регресса (AC-05)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nverdict: PASS\nstatus: pass\n---\n\nbody\n"
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: "verdict: BLOCKED + проза '23 passed' (ET-013 баг) -> FAIL, без регресса (AC-05)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nverdict: BLOCKED\n---\n\nTests: 23 passed, 0 failed.\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: "Ни result, ни verdict, ни status; тело с прозой 'Result: PASS' -> FAIL (AC-06)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\ntype: test-report\nversion: 1\n---\n\nResult: PASS\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: "Нет frontmatter, проза 'Result: PASS' -> FAIL (AC-07)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "# Test Report\n\nResult: PASS\nAll tests passed.\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: "Битый YAML во frontmatter -> FAIL без исключения, reason про YAML/frontmatter (AC-08)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: "---\nresult: [unclosed\n : : :\n---\n\nbody PASS\n"
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: "Файл 13-test-report.md отсутствует -> FAIL, reason 'not found' (AC-09)"
|
||||
module: tests/test_qg.py
|
||||
fixture_frontmatter: null
|
||||
expected: FAIL
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: "Реестр QG_CHECKS не изменился -> снапшот зелёный (AC-10)"
|
||||
module: tests/test_qg_registry_snapshot.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: integration
|
||||
description: "Полный регресс pytest tests/ -q зелёный, существующий TestCheckTestsPassed без правок логики (AC-05, AC-12)"
|
||||
module: tests/
|
||||
expected: PASS
|
||||
@@ -1,80 +0,0 @@
|
||||
# ADR-001: testing-гейт читает `result:` наравне с `verdict:`/`status:`
|
||||
|
||||
- **Статус:** Accepted
|
||||
- **Дата:** 2026-06-05
|
||||
- **Задача:** ORCH-047
|
||||
- **Область:** SHARED quality-gate `check_tests_passed` (общий прод-инстанс: orchestrator + enduro-trails)
|
||||
|
||||
## Контекст
|
||||
|
||||
Quality Gate `check_tests_passed` (`src/qg/checks.py`, парсер `_parse_tests_verdict`) гейтит
|
||||
переход `testing → deploy-staging`, читая машиночитаемый вердикт ТОЛЬКО из YAML-frontmatter
|
||||
артефакта `13-test-report.md` (канон гейтов: frontmatter, никогда не проза — см.
|
||||
`docs/architecture/README.md`).
|
||||
|
||||
Существует рассинхрон контракта между производителем и потребителем вердикта:
|
||||
|
||||
- **Потребитель** (`_parse_tests_verdict`) читает поля `verdict:` и `status:`.
|
||||
- **Производитель** (`.openclaw/agents/tester.md`, строки 51–56, 78–80) предписывает тестеру
|
||||
эмитить машиночитаемое поле **`result: PASS|FAIL`** и НЕ упоминает `verdict:`/`status:`.
|
||||
|
||||
Тестер, честно следуя своей инструкции, пишет `result: PASS` без `verdict:`/`status:`. Парсер
|
||||
попадает в ветку «ни verdict, ни status не заданы» → `(False, "No machine-readable
|
||||
verdict/status…")` → откат `testing → development` и петля до исчерпания
|
||||
`MAX_DEVELOPER_RETRIES`. Это наблюдалось на ORCH-17; ORCH-016 прошёл лишь потому, что его отчёт
|
||||
избыточно нёс И `verdict:`, И `result:`.
|
||||
|
||||
Корень — несовпадение имён поля контракта, а не логики токенов. Наборы positive/negative-токенов
|
||||
исправны и менять их нельзя (обратная совместимость с реальными отчётами enduro-trails
|
||||
ET-001…ET-014).
|
||||
|
||||
## Решение
|
||||
|
||||
Привести контракт гейта к тому, что тестеру УЖЕ велено эмитить — со стороны гейта, не трогая
|
||||
промпт тестера.
|
||||
|
||||
1. `_parse_tests_verdict` читает **три равноправных** машиночитаемых поля из frontmatter:
|
||||
`result:` (канон промпта тестера), `verdict:`, `status:` (легаси/enduro-trails). Достаточно
|
||||
ЛЮБОГО одного непустого.
|
||||
2. Семантика приоритетов сохраняется и распространяется на все три поля через объединённую строку
|
||||
`fields = f"{verdict} {status} {result}"`:
|
||||
- negative-токен (`_TESTS_NEGATIVE_TOKENS`) в любом поле → FAIL и **авторитетен** (проверяется
|
||||
первым, перебивает positive в другом поле);
|
||||
- иначе positive-токен (`_TESTS_POSITIVE_TOKENS`) в любом поле → PASS;
|
||||
- ни одно из трёх не задано → FAIL («No machine-readable verdict/status/result…»);
|
||||
- заданы, но не распознаны → FAIL.
|
||||
3. Наборы токенов **не изменяются**.
|
||||
4. Парсер не бросает исключений ни на каком вводе (битый YAML, пустой файл, frontmatter-не-mapping)
|
||||
→ всегда `(False, reason)`.
|
||||
5. Сигнатура `check_tests_passed`, имя гейта и реестр `QG_CHECKS` **не меняются** — снапшот
|
||||
`tests/test_qg_registry_snapshot.py` остаётся зелёным.
|
||||
|
||||
### Альтернативы (отклонены)
|
||||
|
||||
- **Править промпт тестера** (`verdict:` вместо `result:`) — отклонено: контракт уже задокументирован
|
||||
для тестера как `result:`; единичная правка гейта дешевле и не требует переучивать агента, плюс
|
||||
ломала бы совместимость со старыми отчётами, где встречается `verdict:`/`status:`.
|
||||
- **Глобальный ADR в `docs/architecture/adr/`** — не требуется: изменение не добавляет гейт/стадию/
|
||||
компонент и не меняет топологию; это приведение парсинга существующего гейта к контракту. Канон
|
||||
гейтов в README обновляется точечно.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **Плюс:** корректные отчёты `result: PASS` проходят гейт; `result: FAIL` надёжно откатывает.
|
||||
Петля `testing ↔ development` устранена для всех проектов общего инстанса.
|
||||
- **Плюс:** полная обратная совместимость — отчёты только с `verdict:`/`status:` работают как
|
||||
раньше; существующие тесты `TestCheckTestsPassed` зелёные без правок (кроме обновления reason-текста
|
||||
«…verdict/status…» → «…verdict/status/result…»).
|
||||
- **Минус/ограничение:** число распознаваемых имён поля растёт до трёх — формально шире поверхность
|
||||
«случайного PASS». Митигируется тем, что negative-токен авторитетен и читается только frontmatter.
|
||||
- **SHARED-риск:** изменение затрагивает enduro-trails наравне с orchestrator. Регресс по наборам
|
||||
токенов недопустим → они заморожены; покрытие — `04-test-plan.yaml` (AC-04/AC-05).
|
||||
- **Self-hosting:** деплой строго через `deploy-staging` (8501); прод-контейнер `orchestrator`
|
||||
(8500) не перезапускать в рамках разработки/тестинга.
|
||||
|
||||
## Связи
|
||||
|
||||
- BRD/ТЗ: `docs/work-items/ORCH-047/01-brd.md`, `02-trz.md`.
|
||||
- Канон гейтов и вердикт-парсер: `docs/architecture/README.md`.
|
||||
- Промпт-производитель: `.openclaw/agents/tester.md` (`result: PASS|FAIL`).
|
||||
- adr-0003 (staging-гейт) — обязательная страховка перед прод-деплоем self.
|
||||
@@ -1,10 +0,0 @@
|
||||
# Технические риски — ORCH-047
|
||||
|
||||
| # | Риск | Вероятность | Влияние | Митигация |
|
||||
|---|------|-------------|---------|-----------|
|
||||
| R-1 | Регресс набора токенов ломает enduro-trails (SHARED-гейт, общий прод-инстанс) | Низкая | Высокое | Наборы `_TESTS_NEGATIVE_TOKENS`/`_TESTS_POSITIVE_TOKENS` **заморожены** (не трогать). Покрытие AC-05 на реальных формах ET-001…ET-014 + ORCH-016. |
|
||||
| R-2 | Новое поле `result:` расширяет поверхность ложного PASS | Низкая | Среднее | Negative-токен авторитетен (проверяется первым, перебивает positive). Читается только frontmatter, не проза (AC-03, AC-06, AC-07). |
|
||||
| R-3 | Парсер бросает исключение на битом вводе → падение `_run_qg` | Низкая | Высокое | Defensive-контракт сохранён: любой ввод (нет frontmatter / битый YAML / не-mapping / пустой) → `(False, reason)`, никогда raise (AC-08). |
|
||||
| R-4 | Незаметное изменение реестра гейтов | Очень низкая | Среднее | Сигнатура, имя гейта и `QG_CHECKS` неизменны; снапшот `tests/test_qg_registry_snapshot.py` зелёный (AC-10). |
|
||||
| R-5 | Self-hosting: деплой роняет прод-контейнер всех проектов | Низкая | Высокое | Деплой только через `deploy-staging` (8501); прод `orchestrator` (8500) не перезапускать в dev/test (CLAUDE.md, adr-0003). |
|
||||
| R-6 | Изменение поведения без обновления golden-source доки → REQUEST_CHANGES на review | Средняя | Низкое | ADR-001 заведён; `docs/architecture/README.md` (вердикт-парсер) обновлён архитектором; `CHANGELOG.md` — дев в том же PR (AC-11). |
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-047
|
||||
verdict: APPROVED
|
||||
version: 3
|
||||
---
|
||||
|
||||
# Review ORCH-047
|
||||
|
||||
## Summary
|
||||
Гейт `check_tests_passed` (через `_parse_tests_verdict`) теперь читает `result:` наравне с
|
||||
`verdict:`/`status:`. Реализация точно соответствует ТЗ (`02-trz.md`), ADR-001 и критериям
|
||||
приёмки. Независимый прогон: `pytest tests/ -q` → **442 passed**; снапшот реестра гейтов не
|
||||
изменился. Документация (README, ADR-001, CHANGELOG) обновлена в том же PR. Блокеров и
|
||||
must-fix нет → APPROVED.
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- нет
|
||||
|
||||
### P1 — Must fix
|
||||
- нет
|
||||
|
||||
### P2 — Should fix
|
||||
- нет
|
||||
|
||||
### P3 — Nice-to-have
|
||||
- [ ] Докстринг `check_tests_passed` (≈стр. 184) по-прежнему говорит «Gate the testing ->
|
||||
deploy transition», тогда как фактический переход — `testing → deploy-staging`.
|
||||
Несоответствие предсуществующее, этим PR не введено; чистая косметика, не блокирует.
|
||||
|
||||
## Соответствие ТЗ и AC
|
||||
- **ТЗ §2** — все 10 правил поведения реализованы: чтение `result:` (стр. 261, нормализация
|
||||
`str(...).upper().strip()` + защита от `None`); все три пусты → корректная reason-строка
|
||||
«...verdict/status/result...» (стр. 263–264); объединённая строка `fields = "{verdict}
|
||||
{status} {result}"` (стр. 267); negative-токен проверяется ПЕРВЫМ и авторитетен
|
||||
(стр. 268–270); positive (стр. 271–273); fallback на нераспознанные (стр. 275–279).
|
||||
Наборы `_TESTS_NEGATIVE_TOKENS`/`_TESTS_POSITIVE_TOKENS` не тронуты. ✅
|
||||
- **ТЗ §4/§5/§6** — сигнатура `check_tests_passed`, имя гейта, `QG_CHECKS`, HTTP-API, схема БД
|
||||
не изменены. Снапшот `tests/test_qg_registry_snapshot.py` зелёный (AC-10). ✅
|
||||
- **AC-01..AC-09** — покрыты новыми кейсами в `TestCheckTestsPassed`: `result: PASS/FAIL`,
|
||||
авторитетность negative между полями (`verdict: BLOCKED`, `status: failed` поверх
|
||||
`result: PASS`), `result: ready-to-deploy`, отсутствие машинных полей (reason упоминает
|
||||
`result`). Легаси-кейсы остались зелёными без правок логики (AC-05). ✅
|
||||
- **AC-12** — `pytest tests/ -q` → 442 passed (независимый прогон ревьюера). ✅
|
||||
|
||||
## Соответствие ADR
|
||||
- ADR-001 (`06-adr/ADR-001-result-field-in-tests-gate.md`): решение «три равноправных поля,
|
||||
токены заморожены, negative авторитетен, реестр/сигнатура неизменны» полностью отражено
|
||||
в коде.
|
||||
- Глобальный ADR обоснованно не требуется (изменение не добавляет гейт/стадию/компонент,
|
||||
не меняет топологию) — согласуется с конвенцией CLAUDE.md. SHARED-риск общего инстанса
|
||||
(orchestrator + enduro-trails) учтён: токены заморожены, обратная совместимость покрыта
|
||||
тестами.
|
||||
|
||||
## Документация
|
||||
ОБНОВЛЕНА в том же PR (правило 2/6 CLAUDE.md, AC-11):
|
||||
- `docs/architecture/README.md` — строка вердикт-парсера: для testing-гейта перечислены
|
||||
`result:`/`verdict:`/`status:` + пометка про авторитетность negative. ✅
|
||||
- `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md` — заведён. ✅
|
||||
- `CHANGELOG.md` — запись в `Fixed` про ORCH-047. ✅
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-047
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-047
|
||||
|
||||
`check_tests_passed` / `_parse_tests_verdict` читает `result:` наравне с `verdict:`/`status:`.
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Ветка: feature/ORCH-047-check-tests-passed-gate-must-r
|
||||
- Среда: dev worktree (прод-контейнер `orchestrator` :8500 не затронут)
|
||||
- Дата: 2026-06-05
|
||||
|
||||
## Smoke test API (prod :8500, read-only)
|
||||
| Endpoint | Результат |
|
||||
|----------|-----------|
|
||||
| `GET /health` | `{"status":"ok","service":"orchestrator"}` — OK |
|
||||
| `GET /status` | 200, активные задачи отдаются (ORCH-047 в testing) — OK |
|
||||
| `GET /queue` | 200, counts/breaker/preflight в норме (running:1, failed:0) — OK |
|
||||
|
||||
## Результаты (план `04-test-plan.yaml`)
|
||||
|
||||
| TC ID | Описание | Тест | Результат |
|
||||
|-------|----------|------|-----------|
|
||||
| TC-01 | `result: PASS` без verdict/status → PASS (AC-01) | `test_result_pass_passes` | PASS |
|
||||
| TC-02 | `result: FAIL` → FAIL, reason содержит FAIL (AC-02) | `test_result_fail_fails` | PASS |
|
||||
| TC-03 | `result: PASS` + `verdict: BLOCKED` → negative авторитетен → FAIL (AC-03) | `test_result_pass_but_verdict_blocked_fails` | PASS |
|
||||
| TC-04 | `result: PASS` + `status: failed` → FAIL (AC-03) | `test_result_pass_but_status_failed_fails` | PASS |
|
||||
| TC-05 | `result: ready-to-deploy` → PASS (AC-04) | `test_result_ready_to_deploy_passes` | PASS |
|
||||
| TC-06 | Легаси `verdict: PASS` → PASS, без регресса (AC-05) | `test_verdict_pass_passes` | PASS |
|
||||
| TC-07 | `verdict: BLOCKED` + проза «23 passed» → FAIL (AC-05) | `test_passed_count_in_body_but_blocked_verdict_fails` | PASS |
|
||||
| TC-08 | Нет машинных полей, проза «Result: PASS» → FAIL (AC-06) | `test_no_machine_field_reason_mentions_result` | PASS |
|
||||
| TC-09 | Нет frontmatter → FAIL (AC-07) | `test_no_frontmatter_fails` | PASS |
|
||||
| TC-10 | Битый YAML → FAIL без исключения (AC-08) | `test_invalid_yaml_fails_no_exception` | PASS |
|
||||
| TC-11 | Отчёт отсутствует → FAIL «not found» (AC-09) | `test_no_report` | PASS |
|
||||
| TC-12 | Реестр `QG_CHECKS` неизменен (AC-10) | `test_qg_registry_snapshot.py` (3 теста) | PASS |
|
||||
| TC-13 | Полный регресс зелёный (AC-05, AC-12) | `pytest tests/` | PASS |
|
||||
|
||||
## Покрытие критериев приёмки
|
||||
|
||||
| AC | Статус |
|
||||
|----|--------|
|
||||
| AC-01 `result: PASS` проходит | PASS |
|
||||
| AC-02 `result: FAIL` откатывает | PASS |
|
||||
| AC-03 negative авторитетен между полями | PASS |
|
||||
| AC-04 positive в любом из трёх полей → PASS | PASS |
|
||||
| AC-05 обратная совместимость (TestCheckTestsPassed) | PASS |
|
||||
| AC-06 ни одно поле не задано → FAIL | PASS |
|
||||
| AC-07 только проза без frontmatter → FAIL | PASS |
|
||||
| AC-08 битый YAML → FAIL без raise | PASS |
|
||||
| AC-09 отчёт отсутствует → FAIL | PASS |
|
||||
| AC-10 реестр гейтов неизменен | PASS |
|
||||
| AC-11 ADR/README/CHANGELOG обновлены | PASS |
|
||||
| AC-12 полный регресс зелёный | PASS |
|
||||
|
||||
AC-11 проверено вручную:
|
||||
- `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md` — присутствует.
|
||||
- `docs/architecture/README.md` — строка вердикт-парсера перечисляет `result:`/`verdict:`/`status:`.
|
||||
- `CHANGELOG.md` — запись `fix:` про ORCH-047.
|
||||
|
||||
## Вывод pytest
|
||||
```
|
||||
tests/test_qg.py ............................... TestCheckTestsPassed (все PASS,
|
||||
включая новые test_result_* и легаси-кейсы)
|
||||
tests/test_qg_registry_snapshot.py::test_tc20_qg_callables_unchanged PASSED
|
||||
tests/test_qg_registry_snapshot.py::test_tc20_stage_transitions_unchanged PASSED
|
||||
...
|
||||
======================== 442 passed, 1 warning in 7.77s ========================
|
||||
```
|
||||
(1 warning — предсуществующий PydanticDeprecatedSince20 в `src/config.py`, не связан с ORCH-047.)
|
||||
|
||||
## Итог
|
||||
PASS — все 13 TC и 12 AC выполнены, полный регресс зелёный (442 passed), smoke OK,
|
||||
реестр гейтов не изменён. Задача готова к стадии deploy-staging.
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
staging_status: FAILED
|
||||
timestamp: 2026-06-05T21:30:45Z
|
||||
base_url: http://localhost:8501
|
||||
mode: stub
|
||||
result: 9/10 checks PASS
|
||||
exit_code: 1
|
||||
---
|
||||
|
||||
# Staging Gate Log — ORCH-047
|
||||
|
||||
Staging test suite **FAILED**: 9/10 checks passed, exit code 1.
|
||||
|
||||
## Verdict
|
||||
|
||||
The live staging service on `:8501` is healthy and the full E2E pipeline ran
|
||||
correctly against the **sandbox** project (issue created → webhook accepted →
|
||||
branch created in `orchestrator-sandbox` → analyst job enqueued → cleanup OK).
|
||||
|
||||
The single failing check is **B6 — Registry isolation**: the project registry as
|
||||
seen by the test harness still contains the production projects
|
||||
(`enduro-trails`, `ORCH`) and does **not** isolate to the sandbox project only.
|
||||
This violates the staging isolation requirement (CLAUDE.md: "staging — только
|
||||
sandbox-проект"). Because the staging gate returned a non-zero exit code, the
|
||||
machine verdict is `FAILED` and the task is rolled back to `development`.
|
||||
|
||||
### Notes for follow-up (development)
|
||||
|
||||
- B6 imports `src.projects.known_plane_project_ids()` and asserts the registry
|
||||
contains the sandbox id (`8c5a3025-…`) while the prod ids
|
||||
(`7a79f0a9-…` ET, `8da6aa25-…` ORCH) are absent. It observed
|
||||
`sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)`.
|
||||
- This is a staging-environment / registry-isolation signal, not a verdict on the
|
||||
ORCH-047 code change itself (which targets the `check_tests_passed` gate).
|
||||
Investigate whether the staging container's isolated project registry env is
|
||||
loaded, or whether the harness's in-process registry import is reading the host
|
||||
(`/repos/orchestrator`) prod env instead of the container's env.
|
||||
- Deployer did **not** modify any production infrastructure, registry, `.env`,
|
||||
or `docker-compose.yml` to alter this result (per deployer mandate).
|
||||
|
||||
## Full test output
|
||||
|
||||
```
|
||||
============================================================
|
||||
ORCH-33 Staging Check Suite
|
||||
base_url : http://localhost:8501
|
||||
mode : stub
|
||||
utc_time : 2026-06-05T21:30:45.071676+00:00
|
||||
============================================================
|
||||
|
||||
[Block A] SMOKE
|
||||
✓ PASS A1 GET /health → 200 status=ok [HTTP 200, body={'status': 'ok', 'service': 'orchestrator'}]
|
||||
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience [HTTP 200, keys=['counts', 'max_concurrency', 'poll_interval', 'resilience', 'recent']]
|
||||
✓ PASS A3 ORCH_STAGING=true (not prod) [ORCH_STAGING=true]
|
||||
|
||||
[Block B] ACCESS
|
||||
✓ PASS B4 Plane: sandbox project accessible [HTTP 200, found 5 project(s), sandbox=YES]
|
||||
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true [HTTP 200, permissions={'admin': True, 'push': True, 'pull': True}]
|
||||
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
|
||||
|
||||
[Block C] E2E (mode=stub)
|
||||
· C7: Creating issue in SANDBOX project...
|
||||
✓ PASS C7 Create issue in Plane SANDBOX [HTTP 201, issue_id=5040c202-592f-45d0-9463-ca1e9944e6ba]
|
||||
· C8: Triggering pipeline via POST /webhook/plane ...
|
||||
· Using HMAC signature (secret len=40)
|
||||
✓ PASS C8 Trigger pipeline via /webhook/plane [HTTP 200, resp={'status': 'accepted'}]
|
||||
· C9a: Polling for branch in orchestrator-sandbox (up to 60s)...
|
||||
✓ PASS C9a Branch appears in orchestrator-sandbox [branch=feature/SANDBOX-010-staging-check-e2e-20260605t213]
|
||||
· C9b: Checking staging job queue for analyst job (up to 30s)...
|
||||
· (Plane comment check skipped: bot-tokens not added to SANDBOX project)
|
||||
✓ PASS C9b Analyst job enqueued in staging queue [job_id=6, status=queued, agent=analyst]
|
||||
|
||||
[CLEANUP]
|
||||
✓ PASS CLEANUP: deleted branch 'feature/SANDBOX-010-staging-check-e2e-20260605t213' (HTTP 204)
|
||||
✓ PASS CLEANUP: deleted Plane issue 5040c202-592f-45d0-9463-ca1e9944e6ba (HTTP 204)
|
||||
· CLEANUP DB: no task row found for plane_id=5040c202-592f-45d0-9463-ca1e9944e6ba
|
||||
· CLEANUP DB dedup: no such table: events_dedup
|
||||
|
||||
============================================================
|
||||
RESULT: 9/10 checks PASS
|
||||
============================================================
|
||||
EXIT_CODE=1
|
||||
```
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: staging B6 check reads registry from host worktree, not staging container
|
||||
|
||||
Work Item ID: ORCH-048
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,86 +0,0 @@
|
||||
# 01 — Business Requirements Document (BRD)
|
||||
|
||||
**Work Item:** ORCH-048
|
||||
**Title:** staging B6 check reads registry from host worktree, not staging container
|
||||
**Stage:** analysis
|
||||
**Author:** analyst
|
||||
**Date:** 2026-06-06
|
||||
|
||||
---
|
||||
|
||||
## 1. Контекст и проблема
|
||||
|
||||
`scripts/staging_check.py` — suite живых проверок staging-стенда orchestrator (порт 8501, ADR-0003). Деплоер запускает его на стадии `deploy-staging` и пишет `staging_status:` в `15-staging-log.md`. FAIL любого чека = откат на `development`.
|
||||
|
||||
Блок B содержит проверку **B6 «Registry: sandbox present, prod ET/ORCH absent»** — она должна подтверждать, что в staging-реестре проектов есть только sandbox-проект и НЕТ боевых проектов (enduro-trails / orchestrator). Это страховка изоляции: staging не должен обслуживать прод-проекты.
|
||||
|
||||
**B6 даёт ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`), хотя сама изоляция реестра в staging РАБОТАЕТ корректно.
|
||||
|
||||
### Root cause (подтверждён прямым запуском, Стрим, 06.06)
|
||||
|
||||
- Внутри контейнера `orchestrator-staging` `known_plane_project_ids()` корректно отдаёт `count=1, sandbox=True, ET=False, ORCH=False`. `.env.staging` верно задаёт `ORCH_PROJECTS_JSON` = только sandbox. **Изоляция реестра исправна.**
|
||||
- Все остальные чеки (A1–A3, B4, B5, блок C E2E) обращаются к работающему staging-инстансу по HTTP и **зелёные**.
|
||||
- **B6 — единственный чек, который не ходит по HTTP, а импортирует Python-код локально.** В блоке B6 (строки ~263–284) выполняется:
|
||||
```python
|
||||
sys.path.insert(0, "/repos/orchestrator") # ХОСТ-worktree
|
||||
importlib.reload(sys.modules["src.projects"]) # подхватывает env ТЕКУЩЕГО процесса
|
||||
from src.projects import known_plane_project_ids
|
||||
```
|
||||
- Деплоер по факту запускает скрипт **с хоста** (`.openclaw/agents/deployer.md`: `python3 scripts/staging_check.py --base-url http://localhost:8501`). В env хост-процесса `ORCH_PROJECTS_JSON` НЕ задан → `src.projects` грузит встроенный `_DEFAULT_PROJECTS` (ET + ORCH) → `known_plane_project_ids()` возвращает боевые id → **ложный FAIL**.
|
||||
- Иными словами, B6 проверяет реестр НЕ того окружения, реестр которого реально использует staging-инстанс. Гипотеза деплоера про misconfig staging-контейнера — **опровергнута**.
|
||||
|
||||
## 2. Бизнес-цель
|
||||
|
||||
B6 должен достоверно отражать реестр проектов **именно работающего staging-инстанса** (изолированное окружение), а не реестр, восстановленный из локального импорта в произвольном process-env. При этом B6 обязан по-прежнему ловить реальное нарушение изоляции.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
|
||||
| Роль | Интерес |
|
||||
|------|---------|
|
||||
| Deployer-агент | Достоверный сигнал staging-гейта; нет ложных откатов на development |
|
||||
| Owner / прод | Изоляция staging от прод-проектов реально проверяется (не ложно-зелёная и не ложно-красная) |
|
||||
| Self-hosting pipeline | `deploy-staging` — обязательная страховка перед прод-деплоем орка; ложный FAIL блокирует доставку всех ORCH-задач |
|
||||
|
||||
## 4. Объём (Scope)
|
||||
|
||||
### В объёме
|
||||
- Исправление блока B6 в `scripts/staging_check.py`, чтобы он читал реестр в окружении staging-инстанса.
|
||||
- Тест на корректность B6: оба исхода (PASS при чистой изоляции; FAIL при попадании прод-проекта в staging-реестр).
|
||||
- Обновление документации B6 (`docs/operations/STAGING_CHECK.md`, при необходимости `docs/architecture/README.md`/CHANGELOG) в том же PR.
|
||||
|
||||
### Вне объёма (НЕ ТРОГАТЬ)
|
||||
- `src/projects.py` — реестр работает корректно.
|
||||
- `.env` / `.env.staging` — конфигурация верна.
|
||||
- Прод-логика оркестратора.
|
||||
- Остальные staging-чеки B1–B5 и блок C E2E — зелёные.
|
||||
|
||||
## 5. Бизнес-требования
|
||||
|
||||
| ID | Требование |
|
||||
|----|------------|
|
||||
| BR-1 | B6 на staging даёт PASS (`sandbox=YES`, `prod-ET=NO`, `prod-ORCH=NO`), читая реестр из окружения staging-инстанса, а не из локального импорта хост-worktree. |
|
||||
| BR-2 | B6 по-прежнему детектирует реальное нарушение изоляции: если бы прод-проект реально попал в staging-реестр, B6 обязан выдать FAIL. |
|
||||
| BR-3 | Остальные staging-чеки не сломаны; `src/projects.py` и `.env*` не изменяются. |
|
||||
| BR-4 | Существующие unit-тесты остаются зелёными (`pytest tests/ -q`). |
|
||||
| BR-5 | Документация B6 обновлена в том же PR (golden source). |
|
||||
|
||||
## 6. Допущения и ограничения
|
||||
|
||||
- Решение должно быть минимально инвазивным и не затрагивать прод-логику.
|
||||
- Скрипт `scripts/staging_check.py` использует только stdlib (нет `requests`/`httpx`) — это конвенция файла, её нужно сохранить.
|
||||
- Способ запуска suite может варьироваться (с хоста / `docker exec` внутри контейнера) — выбранное решение должно быть корректным для канонического способа запуска деплоером и задокументировано.
|
||||
|
||||
## 7. Критерий успеха (бизнес)
|
||||
|
||||
- staging-прогон `scripts/staging_check.py` → **B6 PASS** при работающей изоляции.
|
||||
- При искусственно нарушенной изоляции → **B6 FAIL** (проверяется тестом, без реального изменения staging).
|
||||
- `python -m pytest tests/ -q` — зелёный.
|
||||
|
||||
## 8. Открытые вопросы (для архитектора)
|
||||
|
||||
Бизнес-запрос предлагает три варианта реализации (выбор за архитектором, см. 02-trz §4):
|
||||
- (а) B6 читает реестр через HTTP-эндпоинт staging-инстанса;
|
||||
- (б) B6 выполняет проверку через subprocess в окружении staging-контейнера (`docker exec`);
|
||||
- (в) staging_check запускается ВНУТРИ staging-контейнера и читает собственный process-env (убрать host-path хак).
|
||||
|
||||
Предпочтение бизнес-запроса: минимально инвазивный вариант, не трогающий прод-логику.
|
||||
@@ -1,118 +0,0 @@
|
||||
# 02 — Техническое задание (ТЗ / TRZ)
|
||||
|
||||
**Work Item:** ORCH-048
|
||||
**Title:** staging B6 check reads registry from host worktree, not staging container
|
||||
**Stage:** analysis
|
||||
**Author:** analyst
|
||||
**Date:** 2026-06-06
|
||||
|
||||
> Это ТЗ фиксирует требования и инварианты. Выбор одного из трёх архитектурных вариантов (§4) — за архитектором (ADR). Анализ варианты НЕ выбирает.
|
||||
|
||||
---
|
||||
|
||||
## 1. Задействованные модули
|
||||
|
||||
| Путь | Роль | Характер изменений |
|
||||
|------|------|--------------------|
|
||||
| `scripts/staging_check.py` | Suite живых staging-проверок; блок B6 (~строки 263–284) | **Изменяется** — переписать механику получения реестра в B6 |
|
||||
| `tests/` (новый файл, напр. `tests/test_staging_check_b6.py`) | Unit-тест корректности B6 | **Создаётся** |
|
||||
| `docs/operations/STAGING_CHECK.md` | Док запуска suite | **Обновляется** (описание B6 + способ запуска) |
|
||||
| `docs/architecture/README.md` / `CHANGELOG.md` | Golden source | **Обновляется** при необходимости |
|
||||
|
||||
### НЕ изменять (жёсткий инвариант scope)
|
||||
- `src/projects.py` — реестр работает корректно.
|
||||
- `.env`, `.env.staging`, `.env.example` — конфиг верен.
|
||||
- Прод-логику оркестратора (`src/main.py` прод-роуты, `src/webhooks/*`, `src/stage_engine.py`, `src/qg/*`) — кроме случая варианта (а), если архитектор решит добавить read-only эндпоинт (см. §4а, отдельно обоснованный риск).
|
||||
- Блоки A1–A3, B4, B5 и блок C E2E в `staging_check.py`.
|
||||
|
||||
## 2. Текущее поведение (то, что чиним)
|
||||
|
||||
Блок B6 (`scripts/staging_check.py`):
|
||||
```python
|
||||
sys.path.insert(0, "/repos/orchestrator") # хост-worktree path
|
||||
import importlib
|
||||
if "src.projects" in sys.modules:
|
||||
importlib.reload(sys.modules["src.projects"]) # перечитывает env ТЕКУЩЕГО процесса
|
||||
from src.projects import known_plane_project_ids
|
||||
known = known_plane_project_ids()
|
||||
```
|
||||
Проблема: реестр строится из `ORCH_PROJECTS_JSON` **process-env того процесса, в котором исполняется скрипт**. При запуске деплоером с хоста (`python3 scripts/staging_check.py --base-url http://localhost:8501`) переменная не задана → `_DEFAULT_PROJECTS` (ET+ORCH) → ложный FAIL. B6 не отражает реестр работающего staging-инстанса.
|
||||
|
||||
## 3. Требуемое поведение (контракт B6)
|
||||
|
||||
| ID | Требование |
|
||||
|----|------------|
|
||||
| TR-1 | B6 определяет набор «известных staging-инстансу Plane project id» из источника, который **гарантированно отражает окружение работающего staging-инстанса** (порт 8501 / контейнер `orchestrator-staging`), а не из локального импорта в process-env скрипта. |
|
||||
| TR-2 | B6 PASS ⟺ `SANDBOX_PROJECT_ID ∈ known` И `PROD_ET_PROJECT_ID ∉ known` И `PROD_ORCH_PROJECT_ID ∉ known`. Идентификаторы — те же константы, что уже в скрипте. |
|
||||
| TR-3 | B6 сохраняет формат вывода `Results.add(label, passed, detail)` с человекочитаемым detail (`sandbox=…, prod-ET=…, prod-ORCH=…`). |
|
||||
| TR-4 | При недоступности источника реестра B6 даёт **детерминированный FAIL** с понятным detail (не падает с необработанным исключением, не даёт ложный PASS). |
|
||||
| TR-5 | Скрипт остаётся на stdlib (без сторонних зависимостей), если выбранный вариант это допускает. |
|
||||
| TR-6 | Удаляется зависимость B6 от хардкод-пути `/repos/orchestrator` для построения реестра (host-path хак), несовместимого с целью проверки. |
|
||||
|
||||
## 4. Варианты реализации — РЕШЕНИЕ ВЛАДЕЛЬЦА (обязательно)
|
||||
|
||||
> **РЕШЕНИЕ ПРИНЯТО ВЛАДЕЛЬЦЕМ ПРОЕКТА (Слава, 06.06): выбран ВАРИАНТ (в).**
|
||||
> Архитектор НЕ выбирает заново — он фиксирует вариант (в) в ADR с обоснованием ниже.
|
||||
>
|
||||
> ### Почему (в), а НЕ (а) и НЕ (б)
|
||||
> - **(а) HTTP-эндпоинт `GET /projects`** — ОТКЛОНЁН. Порождает «курицу-яйцо»: B6 ходит на эндпоинт **работающего** staging-инстанса, а эндпоинт запечён в Docker-образ → на первом прогоне его в живом инстансе ещё нет (404) → ложный FAIL → откат. Требует ручного bootstrap-деплоя. Это ровно тот класс поломки автономности, который мы устраняем. (Подтверждено на проде 06.06: `GET /projects` на 8501 → 404 → deploy-staging FAILED.)
|
||||
> - **(б) `docker exec` subprocess** — ОТКЛОНЁН. Хрупкое экранирование (см. `docs/history/LESSONS_2026-06-05.md`), зависимость от docker-CLI и имени контейнера.
|
||||
> - **(в) запуск suite ВНУТРИ staging-контейнера + чтение собственного process-env** — ВЫБРАН. B6 не зависит от того, что отдаёт инстанс по HTTP; `staging_check.py` берётся из mount (свежий код сразу, без ребилда образа); реестр читается из env самого `orchestrator-staging`. **Курицы-яйца нет ни на первом прогоне, ни в будущем.** Автономность не ломается.
|
||||
>
|
||||
> ### Что обязан зафиксировать архитектор в ADR (вариант в)
|
||||
> 1. Убрать из B6 host-path хак `sys.path.insert(0, "/repos/orchestrator")` и `importlib.reload(src.projects)`.
|
||||
> 2. Канонизировать запуск suite ВНУТРИ контейнера: `docker exec orchestrator-staging python3 <путь к staging_check.py> --base-url http://localhost:8501` (или эквивалент, где cwd/PYTHONPATH и env — staging-контейнера). Код импортируется из кода контейнера, env уже staging.
|
||||
> 3. **Синхронно** обновить `.openclaw/agents/deployer.md` (способ запуска suite через `docker exec`, НЕ с хоста) и `docs/operations/STAGING_CHECK.md` — иначе host-запуск воспроизведёт баг.
|
||||
> 4. Логику вердикта B6 вынести в чистую функцию `_evaluate_b6(known: set[str]) -> tuple[bool, str]` (TR-2/§9) для unit-теста на оба исхода (AC-2).
|
||||
> 5. НЕ добавлять HTTP-эндпоинт `/projects` и НЕ трогать прод-`src/main.py`. НЕ трогать `src/projects.py`, `.env*`, прочие чеки A/B4/B5/C.
|
||||
>
|
||||
> ### Нюанс топологии (учесть)
|
||||
> `Dockerfile` НЕ копирует `scripts/` в образ → `staging_check.py` доступен в контейнере только через mount `/repos/orchestrator/scripts/...`. Архитектор должен указать в ADR корректный путь запуска внутри контейнера, учитывая этот mount (а не `/app/scripts`).
|
||||
|
||||
---
|
||||
|
||||
## 4-original. Варианты реализации (исходный анализ — справочно)
|
||||
## 4. Варианты реализации (выбор — архитектор, в ADR)
|
||||
|
||||
Бизнес-запрос предлагает три варианта. Анализ перечисляет их с известными плюсами/минусами; решение и обоснование — в `06-adr/`.
|
||||
|
||||
### (а) HTTP-эндпоинт staging-инстанса
|
||||
B6 запрашивает реестр у работающего staging-инстанса по HTTP (как делают A/B4/B5/C).
|
||||
- **Сейчас подходящего эндпоинта НЕТ.** `/health`, `/status`, `/queue` реестр проектов не отдают (`src/main.py`).
|
||||
- Потребуется добавить read-only эндпоинт (напр. `GET /projects`, отдающий `known_plane_project_ids()` или список репо/prefix). Это касается прод-`main.py` → выходит за «не трогать прод-логику», но изменение read-only и низкорисковое — архитектор взвешивает.
|
||||
- Плюс: B6 гарантированно читает реестр именно того процесса, что обслуживает webhooks. Единый HTTP-стиль с остальными чеками.
|
||||
|
||||
### (б) Subprocess в окружении staging-контейнера
|
||||
B6 выполняет `docker exec orchestrator-staging python3 -c "from src.projects import known_plane_project_ids; ..."` и парсит stdout.
|
||||
- Плюс: не трогает прод-`main.py`; читает env контейнера напрямую.
|
||||
- Минус: требует доступности docker-CLI и имени контейнера из среды запуска suite; усложняет запуск «изнутри контейнера»; есть нюансы экранирования (см. `docs/history/LESSONS_2026-06-05.md`).
|
||||
|
||||
### (в) Запуск suite внутри контейнера + чтение собственного process-env
|
||||
Канонизировать запуск `staging_check.py` ВНУТРИ `orchestrator-staging` (`docker exec orchestrator-staging python3 …`), убрать `sys.path.insert(0, "/repos/orchestrator")`, импортировать `src.projects` из кода контейнера (его cwd/PYTHONPATH), env уже staging.
|
||||
- Плюс: минимально инвазивно, не трогает прод-логику и `src.projects`; согласуется с «рекомендуемым способом запуска» в `STAGING_CHECK.md §Способы запуска.1`.
|
||||
- Условие: деплоер должен запускать suite через `docker exec` (а не с хоста). Нужно синхронно обновить `.openclaw/agents/deployer.md` и `STAGING_CHECK.md`, иначе host-запуск воспроизведёт баг.
|
||||
- Нюанс: внутри контейнера код лежит в `/app` (Dockerfile `COPY`), а `/repos/orchestrator` — отдельный mount; импорт должен резолвиться из кода, чьим env реально живёт инстанс.
|
||||
|
||||
## 5. Изменения API
|
||||
|
||||
- Варианты (б) и (в): **нет** изменений API.
|
||||
- Вариант (а): новый read-only эндпоинт (напр. `GET /projects`) — точная схема ответа определяется архитектором. Если выбран — задокументировать в `docs/architecture/README.md` (таблица API) и `CHANGELOG.md`.
|
||||
|
||||
## 6. Изменения схемы БД
|
||||
Нет.
|
||||
|
||||
## 7. Требования к новым QG checks
|
||||
Нет новых QG. Поведение `check_staging_status` (ADR-0003) не меняется — меняется только достоверность одного из чеков suite, чей агрегат пишется в `15-staging-log.md`.
|
||||
|
||||
## 8. Артефакты pipeline, создаваемые/обновляемые
|
||||
- Код: `scripts/staging_check.py` (B6), новый тест в `tests/`.
|
||||
- Док: `docs/operations/STAGING_CHECK.md`; при выборе варианта (а) — `docs/architecture/README.md` (API) и `CHANGELOG.md`; при выборе (в) — `.openclaw/agents/deployer.md` (способ запуска) и `STAGING_CHECK.md`.
|
||||
- ADR: `docs/work-items/ORCH-048/06-adr/ADR-001-*.md` — обоснование выбранного варианта.
|
||||
|
||||
## 9. Тестируемость
|
||||
- Логика «PASS/FAIL по набору known id» B6 должна быть выделена в чистую, юнит-тестируемую функцию (напр. `_evaluate_b6(known: set[str]) -> tuple[bool, str]`), чтобы тест проверял оба исхода без поднятия staging-инстанса/docker. План — `04-test-plan.yaml`.
|
||||
|
||||
## 10. Definition of Done
|
||||
- BR-1…BR-5 (01-brd) выполнены.
|
||||
- staging-прогон → B6 PASS; `pytest tests/ -q` зелёный.
|
||||
- Док и (при необходимости) ADR обновлены в том же PR.
|
||||
@@ -1,67 +0,0 @@
|
||||
# 03 — Критерии приёмки (Acceptance Criteria)
|
||||
|
||||
**Work Item:** ORCH-048
|
||||
**Title:** staging B6 check reads registry from host worktree, not staging container
|
||||
**Stage:** analysis
|
||||
**Author:** analyst
|
||||
**Date:** 2026-06-06
|
||||
|
||||
Каждый критерий формулирует чёткое условие PASS/FAIL. Источник — бизнес-запрос ORCH-048 (AC-1…AC-4) + BRD.
|
||||
|
||||
---
|
||||
|
||||
## AC-1 — B6 PASS на staging, читая реестр из staging-окружения
|
||||
|
||||
**Условие PASS:**
|
||||
- При staging-прогоне `scripts/staging_check.py` (канонический способ запуска, выбранный архитектором) чек **B6** выдаёт `✓ PASS` c detail `sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)`.
|
||||
- Набор known id, по которому судит B6, получен из окружения работающего staging-инстанса (HTTP-эндпоинт / docker-окружение контейнера / собственный process-env при запуске внутри контейнера), **не** из локального импорта `src.projects` в произвольном process-env с host-path хаком `/repos/orchestrator`.
|
||||
|
||||
**FAIL, если:** B6 даёт ложный FAIL (`prod-ET=YES(BAD!)` / `prod-ORCH=YES(BAD!)`) при фактически исправной изоляции; либо реестр в B6 по-прежнему строится локальным импортом, зависящим от env процесса-запускателя.
|
||||
|
||||
## AC-2 — B6 ловит РЕАЛЬНОЕ нарушение изоляции (оба исхода покрыты тестом)
|
||||
|
||||
**Условие PASS:**
|
||||
- Существует unit-тест, проверяющий логику вердикта B6 на **двух** входах:
|
||||
1. «чистый» staging-реестр (`known = {SANDBOX}`) → B6 вердикт **PASS**;
|
||||
2. «загрязнённый» реестр (например `known = {SANDBOX, PROD_ET}` и/или `{SANDBOX, PROD_ORCH}`) → B6 вердикт **FAIL**.
|
||||
- Тест не требует поднятия живого staging-инстанса/docker (логика вердикта изолирована и тестируема, см. 02-trz §9).
|
||||
|
||||
**FAIL, если:** покрыт только один исход; либо B6 даёт PASS при наличии прод-проекта в реестре (потеря защитной функции).
|
||||
|
||||
## AC-3 — Остальные staging-чеки не сломаны; src/projects.py и .env не тронуты
|
||||
|
||||
**Условие PASS:**
|
||||
- Блоки A1–A3, B4, B5 и блок C (E2E) в `scripts/staging_check.py` функционально не изменены (формат вывода и логика прежние).
|
||||
- `git diff` work item НЕ содержит изменений в `src/projects.py`, `.env`, `.env.staging`, `.env.example`.
|
||||
- Прод-логика оркестратора не затронута. Исключение допускается только если архитектор в ADR выбрал вариант (а) и добавил read-only эндпоинт — тогда изменение ограничено добавлением этого эндпоинта, прод-поведение существующих роутов неизменно.
|
||||
|
||||
**FAIL, если:** изменён `src/projects.py` или любой `.env*`; либо затронута/сломана логика прочих чеков.
|
||||
|
||||
## AC-4 — Существующие unit-тесты зелёные
|
||||
|
||||
**Условие PASS:**
|
||||
- `python -m pytest tests/ -q` завершается с кодом 0; все ранее зелёные тесты остаются зелёными; новый тест B6 (AC-2) проходит.
|
||||
|
||||
**FAIL, если:** любой тест падает.
|
||||
|
||||
## AC-5 — Документация обновлена в том же PR (golden source)
|
||||
|
||||
**Условие PASS:**
|
||||
- `docs/operations/STAGING_CHECK.md` отражает исправленную механику B6 и канонический способ запуска suite.
|
||||
- При выборе варианта (а): обновлены таблица API в `docs/architecture/README.md` и `CHANGELOG.md`.
|
||||
- При выборе варианта (в): обновлены `.openclaw/agents/deployer.md` (запуск через `docker exec`) и `STAGING_CHECK.md`.
|
||||
- Заведён ADR `docs/work-items/ORCH-048/06-adr/ADR-001-*.md` с обоснованием выбранного варианта.
|
||||
|
||||
**FAIL, если:** код изменён, а соответствующая док/ADR не обновлены.
|
||||
|
||||
---
|
||||
|
||||
## Сводная проверка (как мерить приёмку)
|
||||
|
||||
| AC | Команда / действие | Ожидаемый результат |
|
||||
|----|--------------------|---------------------|
|
||||
| AC-1 | staging-прогон suite (выбранным способом) | `B6 … ✓ PASS [sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)]` |
|
||||
| AC-2 | `pytest tests/test_staging_check_b6.py -q` | оба кейса (clean→PASS, polluted→FAIL) зелёные |
|
||||
| AC-3 | `git diff --name-only` по ветке | нет `src/projects.py`, нет `.env*`; чеки A/B4/B5/C не изменены по сути |
|
||||
| AC-4 | `python -m pytest tests/ -q` | exit 0, все PASS |
|
||||
| AC-5 | ревью diff документации | STAGING_CHECK.md + ADR-001 присутствуют и согласованы с кодом |
|
||||
@@ -1,97 +0,0 @@
|
||||
work_item: ORCH-048
|
||||
title: staging B6 check reads registry from host worktree, not staging container
|
||||
stage: analysis
|
||||
notes: >
|
||||
B6 в staging_check.py должен оценивать реестр окружения работающего staging-инстанса.
|
||||
Для тестируемости логика вердикта B6 выделяется в чистую функцию (напр.
|
||||
_evaluate_b6(known: set[str]) -> tuple[bool, str]); тесты бьют именно её и не
|
||||
поднимают живой staging-инстанс/docker. Идентификаторы — те же константы из скрипта:
|
||||
SANDBOX_PROJECT_ID=8c5a3025-4f9d-4190-b79f-fa06276bb27e,
|
||||
PROD_ET_PROJECT_ID=7a79f0a9-5278-49cd-9007-9a338f238f9c,
|
||||
PROD_ORCH_PROJECT_ID=8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a.
|
||||
|
||||
tests:
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: >
|
||||
B6-вердикт PASS при чистом staging-реестре: known={SANDBOX} ->
|
||||
passed=True, detail содержит sandbox=YES, prod-ET=NO, prod-ORCH=NO. (AC-1, AC-2)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: >
|
||||
B6-вердикт FAIL при попадании прод-ET в реестр: known={SANDBOX, PROD_ET} ->
|
||||
passed=False, detail помечает prod-ET как нарушение. (AC-2)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: >
|
||||
B6-вердикт FAIL при попадании прод-ORCH в реестр: known={SANDBOX, PROD_ORCH} ->
|
||||
passed=False, detail помечает prod-ORCH как нарушение. (AC-2)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: >
|
||||
B6-вердикт FAIL при отсутствии sandbox в реестре: known=set() (пусто) ->
|
||||
passed=False (sandbox absent), детерминированно, без исключения. (AC-2, TR-4)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: >
|
||||
B6-вердикт FAIL при загрязнении и ET, и ORCH одновременно:
|
||||
known={SANDBOX, PROD_ET, PROD_ORCH} -> passed=False. (AC-2)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: >
|
||||
Источник реестра в B6 больше не зависит от host-path хака
|
||||
sys.path.insert(0,"/repos/orchestrator"): проверить (статически/через структуру
|
||||
кода или мок источника), что построение known не делается локальным импортом
|
||||
src.projects из произвольного process-env. (AC-1, TR-6)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: >
|
||||
Деградация источника реестра (HTTP-ошибка / недоступный контейнер / битый ответ)
|
||||
-> B6 даёт детерминированный FAIL с понятным detail, а не ложный PASS и не
|
||||
необработанное исключение. (TR-4)
|
||||
module: tests/test_staging_check_b6.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: >
|
||||
Регрессия реестра: существующие тесты src/projects.py остаются зелёными,
|
||||
подтверждая, что src/projects.py не изменён. (AC-3, AC-4)
|
||||
module: tests/test_projects.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: integration
|
||||
description: >
|
||||
Полный прогон pytest без падений после правок:
|
||||
`python -m pytest tests/ -q` -> exit 0. (AC-4)
|
||||
module: tests/
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: integration
|
||||
description: >
|
||||
Живой staging-прогон (ручной, вне CI): запустить scripts/staging_check.py
|
||||
выбранным архитектором способом против orchestrator-staging (8501) ->
|
||||
B6 == PASS (sandbox=YES, prod-ET=NO, prod-ORCH=NO); блоки A/B4/B5/C не сломаны.
|
||||
(AC-1, AC-3) Выполняется деплоером на стадии deploy-staging.
|
||||
module: scripts/staging_check.py
|
||||
expected: PASS
|
||||
@@ -1,139 +0,0 @@
|
||||
# ADR-001: B6 читает реестр через запуск suite ВНУТРИ staging-контейнера
|
||||
|
||||
## Статус
|
||||
Accepted
|
||||
|
||||
- **Задача:** ORCH-048
|
||||
- **Дата:** 2026-06-06
|
||||
- **Автор:** architect
|
||||
- **Решение варианта:** принято Владельцем проекта (Слава, 06.06) — вариант **(в)**. Архитектор фиксирует и обосновывает.
|
||||
|
||||
## Контекст
|
||||
|
||||
Чек **B6 «Registry: sandbox present, prod ET/ORCH absent»** в `scripts/staging_check.py`
|
||||
(блок B, ~строки 263–284) — страховка изоляции staging: подтверждает, что в реестре
|
||||
проектов работающего staging-инстанса есть только sandbox-проект и НЕТ боевых
|
||||
(enduro-trails / orchestrator).
|
||||
|
||||
B6 даёт **ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`), хотя изоляция
|
||||
реестра в staging исправна. Root cause (подтверждён прямым запуском, 06.06):
|
||||
|
||||
```python
|
||||
sys.path.insert(0, "/repos/orchestrator") # host-worktree path
|
||||
import importlib
|
||||
if "src.projects" in sys.modules:
|
||||
importlib.reload(sys.modules["src.projects"]) # перечитывает env ТЕКУЩЕГО процесса
|
||||
from src.projects import known_plane_project_ids
|
||||
known = known_plane_project_ids()
|
||||
```
|
||||
|
||||
B6 — единственный чек, который не ходит к инстансу по HTTP, а импортирует Python-код
|
||||
локально и строит реестр из `ORCH_PROJECTS_JSON` **process-env того процесса, в котором
|
||||
исполняется скрипт**. Деплоер фактически запускает suite **с хоста**
|
||||
(`python3 scripts/staging_check.py --base-url http://localhost:8501`), где
|
||||
`ORCH_PROJECTS_JSON` не задан → `src.projects` грузит встроенный `_DEFAULT_PROJECTS`
|
||||
(ET + ORCH) → ложный FAIL. B6 проверяет реестр НЕ того окружения, реестр которого
|
||||
реально использует staging-инстанс.
|
||||
|
||||
### Топология (ключевой факт для решения)
|
||||
|
||||
- Контейнер `orchestrator-staging`: `WORKDIR /app`, `ENV PYTHONPATH=/app`; код приложения
|
||||
**скопирован** в образ (`Dockerfile: COPY src/ ./src/`) → живёт в `/app/src/`.
|
||||
- `.env.staging` (env_file контейнера) задаёт `ORCH_PROJECTS_JSON` = только sandbox.
|
||||
- `Dockerfile` **НЕ копирует** `scripts/` в образ. Скрипт доступен в контейнере только
|
||||
через bind-mount `/home/slin/repos:/repos` → `/repos/orchestrator/scripts/staging_check.py`.
|
||||
|
||||
Из этого следует: при запуске `docker exec orchestrator-staging python3
|
||||
/repos/orchestrator/scripts/staging_check.py` интерпретатор добавляет в `sys.path[0]`
|
||||
каталог скрипта (`/repos/orchestrator/scripts`), а `import src.projects` резолвится через
|
||||
`PYTHONPATH=/app` → `/app/src/projects.py` (собственный код контейнера) с env из
|
||||
`.env.staging`. Это ровно реестр работающего staging-инстанса — без HTTP, без host-path хака.
|
||||
|
||||
## Решение
|
||||
|
||||
Принят **вариант (в): канонизировать запуск suite ВНУТРИ `orchestrator-staging` и читать
|
||||
собственный process-env контейнера.**
|
||||
|
||||
Архитектурно фиксируется (детальная реализация — стадия development):
|
||||
|
||||
1. **Убрать из B6 host-path хак:** удалить `sys.path.insert(0, "/repos/orchestrator")` и
|
||||
`importlib.reload(sys.modules["src.projects"])`. Импорт `from src.projects import
|
||||
known_plane_project_ids` остаётся, но резолвится из кода контейнера (`/app/src` через
|
||||
`PYTHONPATH=/app`), env которого — staging (`.env.staging`).
|
||||
|
||||
2. **Канонизировать запуск suite внутри контейнера** (а не с хоста):
|
||||
```bash
|
||||
docker exec orchestrator-staging \
|
||||
python3 /repos/orchestrator/scripts/staging_check.py \
|
||||
--base-url http://localhost:8501 --mode stub
|
||||
```
|
||||
`--base-url http://localhost:8501` корректен изнутри контейнера: сеть `network_mode: host`.
|
||||
Путь к скрипту — `/repos/orchestrator/scripts/...` (mount), а НЕ `/app/scripts` (в образе
|
||||
scripts отсутствует).
|
||||
|
||||
3. **Синхронно обновить документацию запуска** (этот же PR), иначе host-запуск воспроизведёт
|
||||
баг:
|
||||
- `.openclaw/agents/deployer.md` — команда стадии `deploy-staging` через `docker exec`.
|
||||
- `docs/operations/STAGING_CHECK.md` — канонический способ запуска и описание механики B6.
|
||||
|
||||
4. **Логику вердикта B6 вынести в чистую функцию** `_evaluate_b6(known: set[str]) ->
|
||||
tuple[bool, str]`, инвариант (TR-2): `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧
|
||||
PROD_ORCH ∉ known`; `detail` сохраняет формат `sandbox=…, prod-ET=…, prod-ORCH=…` (TR-3).
|
||||
Функция юнит-тестируема без поднятия инстанса/docker (TC-01…TC-07).
|
||||
|
||||
5. **Детерминированная деградация (TR-4):** при недоступности источника реестра (ошибка
|
||||
импорта/построения `known`) B6 даёт FAIL с понятным detail, без необработанного исключения
|
||||
и без ложного PASS.
|
||||
|
||||
### Границы (scope guards — обязательны)
|
||||
|
||||
- **НЕ** добавлять HTTP-эндпоинт `GET /projects`; **НЕ** трогать прод-`src/main.py`,
|
||||
`src/webhooks/*`, `src/stage_engine.py`, `src/qg/*`.
|
||||
- **НЕ** изменять `src/projects.py`, `.env`, `.env.staging`, `.env.example`.
|
||||
- **НЕ** менять блоки A1–A3, B4, B5 и блок C (E2E): формат вывода и логика прежние.
|
||||
- Реестр QG и стадий не меняется; ADR-0003 (`check_staging_status`) в силе — меняется только
|
||||
достоверность одного чека внутри suite, чей агрегат пишется в `15-staging-log.md`.
|
||||
|
||||
## Альтернативы (отклонены)
|
||||
|
||||
### (а) HTTP-эндпоинт `GET /projects` работающего staging-инстанса — ОТКЛОНЁН
|
||||
Порождает «курицу-яйцо»: B6 ходит на эндпоинт **работающего** инстанса, а эндпоинт запечён
|
||||
в Docker-образ → на первом прогоне его в живом инстансе ещё нет (404) → ложный FAIL → откат.
|
||||
Требует ручного bootstrap-деплоя. Это ровно тот класс поломки автономности, который мы
|
||||
устраняем. Подтверждено на проде 06.06: `GET /projects` на 8501 → 404 → deploy-staging FAILED.
|
||||
(Предыдущая итерация архитектора выбрала (а); решение отклонено Владельцем, код и ADR(а)
|
||||
удалены, ветка откатана к analyst-артефактам.)
|
||||
|
||||
### (б) `docker exec` subprocess + парсинг stdout — ОТКЛОНЁН
|
||||
`docker exec orchestrator-staging python3 -c "..."` из процесса suite. Хрупкое экранирование
|
||||
(`docs/history/LESSONS_2026-06-05.md`), зависимость от наличия docker-CLI и имени контейнера
|
||||
в среде запуска, усложняет запуск «изнутри контейнера».
|
||||
|
||||
### (в) Запуск suite внутри контейнера + собственный process-env — ВЫБРАН
|
||||
B6 не зависит от того, что отдаёт инстанс по HTTP; `staging_check.py` берётся из mount (свежий
|
||||
код сразу, без ребилда образа); реестр читается из env самого `orchestrator-staging`. Курицы-яйца
|
||||
нет ни на первом прогоне, ни в будущем. Минимально инвазивно, прод-логика и `src/projects.py` не
|
||||
тронуты. Согласуется с «рекомендуемым способом запуска» (`STAGING_CHECK.md §Способы запуска.1`).
|
||||
|
||||
## Последствия
|
||||
|
||||
**Плюсы**
|
||||
- B6 достоверно отражает реестр работающего staging-инстанса; ложные FAIL/откаты устранены.
|
||||
- Автономность self-hosting не ломается: нет bootstrap-зависимости от запечённого в образ кода.
|
||||
- Свежий `staging_check.py` подхватывается из mount без ребилда образа.
|
||||
- Защитная функция B6 сохранена и покрыта юнит-тестами на оба исхода (PASS/FAIL).
|
||||
|
||||
**Минусы / ограничения**
|
||||
- Запуск suite **обязан** идти через `docker exec` внутри `orchestrator-staging`. Запуск с
|
||||
хоста воспроизведёт исходный баг (host-env без `ORCH_PROJECTS_JSON`). Это закреплено в
|
||||
`deployer.md` и `STAGING_CHECK.md`; способ «с хоста» остаётся возможен, только если env
|
||||
хоста корректно повторяет staging (не рекомендуется, помечено).
|
||||
- Деплоер должен иметь доступ к docker-CLI/сокету (есть: `/var/run/docker.sock` смонтирован в
|
||||
контейнер оркестратора, у которого deployer-агент исполняется; `deployer.md` tools: Bash docker).
|
||||
|
||||
## Связи
|
||||
- ADR-0003 (`docs/architecture/adr/adr-0003-staging-gate.md`) — staging-гейт, который этот чек
|
||||
обслуживает.
|
||||
- ORCH-6 / `src/projects.py` — реестр проектов (источник `known_plane_project_ids()`),
|
||||
НЕ изменяется.
|
||||
- `docs/history/LESSONS_2026-06-05.md` — обоснование отказа от варианта (б).
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
type: review
|
||||
work_item_id: ORCH-048
|
||||
verdict: APPROVED
|
||||
version: 1
|
||||
---
|
||||
|
||||
# Review ORCH-048
|
||||
|
||||
## Summary
|
||||
|
||||
PR чинит ложный FAIL чека **B6** в `scripts/staging_check.py`: реестр проектов теперь
|
||||
читается из окружения работающего staging-инстанса (вариант «в», выбранный Владельцем и
|
||||
зафиксированный в ADR-001), host-path хак `sys.path.insert(0, "/repos/orchestrator")` +
|
||||
`importlib.reload` удалён. Реализация соответствует ТЗ, ADR-001 и всем критериям приёмки.
|
||||
Документация обновлена синхронно. `pytest tests/ -q` — **470 passed**.
|
||||
|
||||
Соответствие осям проверки:
|
||||
|
||||
- **ТЗ (02-trz):** TR-1…TR-6 выполнены. TR-1/TR-6 — реестр строится из process-env
|
||||
инстанса, host-path хак удалён. TR-2 — инвариант `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉
|
||||
known ∧ PROD_ORCH ∉ known` в `_evaluate_b6`. TR-3 — формат detail сохранён. TR-4 —
|
||||
детерминированный FAIL при недоступности источника (`_run_b6` ловит `Exception`, нет
|
||||
ложного PASS, нет необработанного исключения). TR-5 — stdlib. §9 — логика вердикта
|
||||
вынесена в чистую `_evaluate_b6` для unit-теста.
|
||||
- **ADR-001:** реализация дословно следует пунктам 1–5 решения и scope-guards.
|
||||
HTTP-эндпоинт не добавлен, прод-`src/main.py` не тронут.
|
||||
- **AC-1…AC-5:** AC-1 — механика читает реестр инстанса; AC-2 — оба исхода покрыты
|
||||
(TC-01 clean→PASS, TC-02/03/05 polluted→FAIL); AC-3 — `git diff` не содержит
|
||||
`src/projects.py`/`.env*`, блоки A1–A3/B4/B5/C не тронуты; AC-4 — 470 passed; AC-5 —
|
||||
STAGING_CHECK.md, deployer.md, CHANGELOG, ADR-001 обновлены в этом же PR.
|
||||
- **Качество кода:** чистые функции, докстринги на всех новых функциях, defensive-обработка,
|
||||
`sys` остаётся используемым (`sys.exit`), без мёртвых импортов. Тесты содержательные
|
||||
(7 TC + happy-path wiring + статическая проверка отсутствия хака).
|
||||
|
||||
## Findings
|
||||
|
||||
### P0 — Blocker
|
||||
- нет
|
||||
|
||||
### P1 — Must fix
|
||||
- нет
|
||||
|
||||
### P2 — Should fix
|
||||
- нет
|
||||
|
||||
### P3 — Nice-to-have
|
||||
- [ ] `test_tc06_no_host_path_hack_in_source` и `test_tc06_registry_loader_uses_src_projects`
|
||||
носят одинаковый префикс `tc06` — формально это два разных кейса; имена можно было бы
|
||||
развести для читаемости отчёта pytest. Косметика, на приёмку не влияет.
|
||||
|
||||
## Документация
|
||||
|
||||
Полностью обновлена в том же PR (golden source соблюдён):
|
||||
|
||||
- `docs/operations/STAGING_CHECK.md` — канонический способ запуска (способ 1 через
|
||||
`docker exec`), способ «с хоста» помечен как невалидный/воспроизводящий баг, добавлена
|
||||
секция «Механика чека B6».
|
||||
- `.openclaw/agents/deployer.md` — команда стадии `deploy-staging` переведена на
|
||||
`docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py …`
|
||||
с пояснением, почему host-запуск ломает B6.
|
||||
- `CHANGELOG.md` — запись в разделе Fixed с полным описанием root cause и решения.
|
||||
- ADR `docs/work-items/ORCH-048/06-adr/ADR-001-b6-registry-via-in-container-run.md` —
|
||||
обоснование варианта (в), отклонённые (а)/(б), scope-guards.
|
||||
|
||||
`docs/architecture/README.md` обновлять не требовалось: API, реестр стадий и `QG_CHECKS`
|
||||
не менялись (изменение касается только достоверности одного чека внутри suite).
|
||||
|
||||
**Вердикт: APPROVED** — P0/P1 отсутствуют.
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
type: test-report
|
||||
work_item_id: ORCH-048
|
||||
result: PASS
|
||||
---
|
||||
|
||||
# Test Report — ORCH-048
|
||||
|
||||
**Title:** staging B6 check reads registry from host worktree, not staging container
|
||||
**Stage:** testing
|
||||
**Branch:** feature/ORCH-048-staging-b6-check-reads-registr
|
||||
|
||||
## Окружение
|
||||
- Python: 3.12.13
|
||||
- pytest: 8.3.3
|
||||
- Дата: 2026-06-06T07:06Z
|
||||
- Prod API (8500): `/health` 200 ok, `/status` 200 (ORCH-048 в stage=testing), `/queue` 200 (breaker closed, preflight ok)
|
||||
|
||||
## Результаты
|
||||
|
||||
| TC ID | Тип | Описание | Результат |
|
||||
|-------|-----|----------|-----------|
|
||||
| TC-01 | unit | `known={SANDBOX}` → B6 PASS, detail sandbox=YES/prod-ET=NO/prod-ORCH=NO | PASS |
|
||||
| TC-02 | unit | `known={SANDBOX,PROD_ET}` → B6 FAIL, prod-ET помечен нарушением | PASS |
|
||||
| TC-03 | unit | `known={SANDBOX,PROD_ORCH}` → B6 FAIL, prod-ORCH помечен нарушением | PASS |
|
||||
| TC-04 | unit | `known=set()` (нет sandbox) → детерминированный FAIL без исключения | PASS |
|
||||
| TC-05 | unit | `known={SANDBOX,PROD_ET,PROD_ORCH}` → B6 FAIL | PASS |
|
||||
| TC-06 | unit | Нет host-path хака `/repos/orchestrator`; реестр строится не локальным импортом в произвольном process-env | PASS |
|
||||
| TC-07 | unit | Деградация источника реестра → детерминированный FAIL с понятным detail (не ложный PASS, не необработанное исключение) | PASS |
|
||||
| TC-08 | unit | Регрессия `src/projects.py` (16 тестов) зелёные — реестр не изменён | PASS |
|
||||
| TC-09 | integration | `python -m pytest tests/ -q` → exit 0 | PASS |
|
||||
| TC-10 | integration | Живой staging-прогон B6 на 8501 | DEFERRED — выполняется деплоером на стадии deploy-staging (см. 04-test-plan TC-10) |
|
||||
|
||||
Доп. покрытие: `test_run_b6_records_pass_for_clean_registry` (happy-path wiring `_run_b6`).
|
||||
|
||||
## Покрытие критериев приёмки
|
||||
|
||||
| AC | Подтверждение | Статус |
|
||||
|----|---------------|--------|
|
||||
| AC-1 | B6 PASS на чистом реестре (TC-01), источник — окружение инстанса, host-path хак удалён (TC-06) | PASS |
|
||||
| AC-2 | Оба исхода покрыты: clean→PASS (TC-01), polluted→FAIL (TC-02/03/05), без sandbox→FAIL (TC-04) | PASS |
|
||||
| AC-3 | `git diff origin/main...HEAD` НЕ содержит `src/projects.py` / `.env*`; блоки A/B4/B5/C не тронуты | PASS |
|
||||
| AC-4 | `pytest tests/ -q` → exit 0, 470 passed | PASS |
|
||||
| AC-5 | STAGING_CHECK.md, deployer.md, CHANGELOG.md, ADR-001 обновлены в том же PR (подтверждено review) | PASS |
|
||||
|
||||
## Проверка scope (AC-3)
|
||||
Изменённые файлы ветки vs origin/main:
|
||||
```
|
||||
.openclaw/agents/deployer.md
|
||||
CHANGELOG.md
|
||||
docs/operations/STAGING_CHECK.md
|
||||
docs/work-items/ORCH-048/* (артефакты задачи)
|
||||
scripts/staging_check.py
|
||||
tests/test_staging_check_b6.py
|
||||
```
|
||||
Forbidden-path check: OK — `src/projects.py` и `.env*` НЕ затронуты.
|
||||
|
||||
## Вывод pytest
|
||||
|
||||
Полный прогон:
|
||||
```
|
||||
470 passed, 1 warning in 9.07s
|
||||
pytest exit code: 0
|
||||
```
|
||||
(warning — PydanticDeprecatedSince20 в `src/config.py`, предсуществующий, к ORCH-048 не относится.)
|
||||
|
||||
B6 suite:
|
||||
```
|
||||
tests/test_staging_check_b6.py ......... [9 passed]
|
||||
9 passed, 1 warning in 0.29s
|
||||
```
|
||||
|
||||
projects-регрессия (TC-08):
|
||||
```
|
||||
16 passed, 1 warning in 0.31s
|
||||
```
|
||||
|
||||
## Итог
|
||||
**PASS** — все unit/integration тесты зелёные (470 passed, exit 0), smoke API prod исправен, scope-инвариант AC-3 соблюдён. Живой staging-прогон B6 (TC-10) выполняется деплоером на стадии deploy-staging.
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
deploy_status: SUCCESS
|
||||
timestamp: 2026-06-06T07:12:00Z
|
||||
work_item: ORCH-048
|
||||
target: orchestrator (prod, self-hosting)
|
||||
restart_required: false
|
||||
rebuild_required: false
|
||||
staging_gate: SUCCESS
|
||||
---
|
||||
|
||||
# Production Deploy Log — ORCH-048
|
||||
|
||||
Production rollout of ORCH-048 (`fix(staging_check): B6 reads registry from running staging instance env`) is **complete on merge** — no prod container rebuild or restart was required, and none was performed.
|
||||
|
||||
## Precondition: staging gate
|
||||
|
||||
`deploy` is reachable only because the staging gate (`deploy-staging`) passed:
|
||||
|
||||
- `15-staging-log.md` → `staging_status: SUCCESS`, **10/10 checks PASS** (incl. B6 registry-isolation, the fix's target), run inside `orchestrator-staging` (8501).
|
||||
|
||||
## Change scope (why no restart)
|
||||
|
||||
The work item changes touch **only bind-mounted / non-runtime artifacts** — `src/` (the code running in the prod container) and the `Dockerfile` are untouched:
|
||||
|
||||
| File | Kind | How it reaches prod |
|
||||
|------|------|---------------------|
|
||||
| `scripts/staging_check.py` | bind-mounted (`/home/slin/repos` → `/repos`); **not** copied into the image (`scripts/` absent from `/app`) | host `git pull` → live immediately |
|
||||
| `.openclaw/agents/deployer.md` | bind-mounted agent prompt, read at agent launch | host `git pull` → live on next agent run |
|
||||
| `CHANGELOG.md`, `docs/operations/STAGING_CHECK.md` | docs | n/a |
|
||||
| `tests/test_staging_check_b6.py` | test, not deployed | n/a |
|
||||
|
||||
Because nothing in `src/` or the image changed, there is **no container rebuild and no restart** for the shared prod `orchestrator` (8500). Per CLAUDE.md / INFRA.md self-hosting rules, the prod container that serves all projects (enduro-trails + orchestrator) was **not** touched — zero group-risk.
|
||||
|
||||
## Deploy action
|
||||
|
||||
- **Prod container restart/rebuild:** not required, not performed (guardrail: never restart prod `orchestrator` within an ORCH task).
|
||||
- **Real docker/SSH deploy hook** (`scripts/orchestrator-deploy-hook.sh`): not triggered by this agent (not explicitly instructed; reserved for Owner per ORCH-36).
|
||||
- **Effective rollout:** merge of this branch to `main` + routine host `git pull` makes the corrected `staging_check.py` and `deployer.md` live; the prod app process is unaffected.
|
||||
|
||||
## Verdict
|
||||
|
||||
`deploy_status: SUCCESS` — staging gate green, change is bind-mount-only, prod instance untouched, no rollback needed.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
staging_status: SUCCESS
|
||||
timestamp: 2026-06-06T07:08:59Z
|
||||
base_url: http://localhost:8501
|
||||
work_item: ORCH-048
|
||||
mode: stub
|
||||
result: 10/10 checks PASS
|
||||
---
|
||||
|
||||
# Staging Gate Log — ORCH-048
|
||||
|
||||
Staging test suite completed against the live `orchestrator-staging` instance (port 8501). **All 10/10 checks passed.**
|
||||
|
||||
## Execution context
|
||||
|
||||
- **Where**: inside the `orchestrator-staging` container via Docker Engine API exec (canonical per ORCH-048 / ADR-001; `docker` CLI not present in this agent env, so the bind-mounted socket `/var/run/docker.sock` was used directly).
|
||||
- **Command**: `python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`
|
||||
- **Exit code**: `0`
|
||||
- **Container state**: `orchestrator-staging` running (Up 25 hours).
|
||||
|
||||
Running inside the container is required so the B6 registry-isolation check reads the registry from the running instance's own process-env (`.env.staging` → `ORCH_PROJECTS_JSON` = sandbox-only). This is precisely the behaviour ORCH-048 corrects.
|
||||
|
||||
## Results
|
||||
|
||||
```
|
||||
[Block A] SMOKE
|
||||
✓ PASS A1 GET /health → 200 status=ok
|
||||
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience
|
||||
✓ PASS A3 ORCH_STAGING=true (not prod)
|
||||
|
||||
[Block B] ACCESS
|
||||
✓ PASS B4 Plane: sandbox project accessible (found 5 project(s), sandbox=YES)
|
||||
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true
|
||||
✓ PASS B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)]
|
||||
|
||||
[Block C] E2E (mode=stub)
|
||||
✓ PASS C7 Create issue in Plane SANDBOX
|
||||
✓ PASS C8 Trigger pipeline via /webhook/plane
|
||||
✓ PASS C9a Branch appears in orchestrator-sandbox
|
||||
✓ PASS C9b Analyst job enqueued in staging queue
|
||||
|
||||
[CLEANUP]
|
||||
✓ PASS CLEANUP: deleted sandbox branch, Plane issue, and DB rows
|
||||
|
||||
============================================================
|
||||
RESULT: 10/10 checks PASS
|
||||
============================================================
|
||||
```
|
||||
|
||||
**B6 verdict (the ORCH-048 target check): PASS** — registry read from the running staging instance correctly shows sandbox present and prod ET/ORCH absent, with no false FAIL / spurious rollback.
|
||||
@@ -1,7 +0,0 @@
|
||||
# Business Request: Sweeper потерянных webhook: реконсиляция застрявших стадий (stuck-task)
|
||||
|
||||
Work Item ID: ORCH-053
|
||||
|
||||
## Description
|
||||
|
||||
TBD
|
||||
@@ -1,128 +0,0 @@
|
||||
# BRD — ORCH-053: Sweeper потерянных webhook (реконсиляция застрявших стадий)
|
||||
|
||||
Work Item ID: ORCH-053
|
||||
Стадия: analysis → (architecture)
|
||||
Тип: надёжность конвейера (проектирование + реализация). Self-hosting (ORCH).
|
||||
|
||||
## 1. Проблема (бизнес-контекст)
|
||||
|
||||
Продвижение задач между стадиями конвейера завязано **исключительно** на входящие
|
||||
webhook-события:
|
||||
- **Plane** (`work_item.updated` → статус In Progress / Approved / Rejected) — единственный
|
||||
триггер старта задачи, advance и rollback (`src/webhooks/plane.py`).
|
||||
- **Gitea** (CI-status `success`/`failure`, push, PR reviewed/merged) — триггер
|
||||
development→review, architecture→development, review→testing, deploy→done
|
||||
(`src/webhooks/gitea.py`).
|
||||
|
||||
Если входящее событие **потеряно** (502 на падающем/ребилдящемся инстансе, Plane/Gitea
|
||||
не повторяют доставку, сетевой сбой, sha→branch не разрезолвился, вебхук был временно
|
||||
выключен) — статус в источнике истины (Plane / зелёный CI) уже изменился, **а задача в
|
||||
оркестраторе не сдвинулась**. Задача висит молча, без какого-либо механизма восстановления.
|
||||
|
||||
**Живой инцидент (ORCH-044, 06.06):** dev-агент отработал (exit 0, CI позеленел), но
|
||||
Gitea webhook о CI-success не продвинул задачу (не дошёл / не сматчился sha→branch).
|
||||
Задача висела бы на `development` молча навсегда — спасли только ручным дёрганьем гейта
|
||||
`check_ci_green`. Это **системная дыра**, а не разовый сбой; сейчас её ловит ручной
|
||||
heartbeat-watchdog Стрима (костыль).
|
||||
|
||||
### Что уже есть и почему недостаточно
|
||||
| Механизм | Что покрывает | Почему не закрывает дыру |
|
||||
|----------|---------------|--------------------------|
|
||||
| `requeue_running_jobs()` (startup) | зависшие **jobs** при рестарте | про jobs, не про застрявший **stage-переход** |
|
||||
| orphan-recovery (`main.py`) | `agent_runs` без `finished_at` | job-уровень, не stage |
|
||||
| ORCH-5 events de-dup (`delivery_id`) | защита от **дублей** webhook | обратной защиты от **потери** нет |
|
||||
| ORCH-045 `ci_poll` в `check_ci_green` | поллит CI 12×10с | только **если гейт уже вызван** webhook'ом; не пришёл webhook → гейт не вызывается |
|
||||
|
||||
Общий принцип всех существующих механизмов — restart-safe resilience на уровне jobs.
|
||||
**Нет ни одного механизма, реконсилирующего рассинхрон «источник истины ≠ стадия задачи».**
|
||||
|
||||
## 2. Цель
|
||||
|
||||
Задача **не должна застревать молча** из-за потерянного входящего события. Ввести
|
||||
фоновый периодический **sweeper / reconciler**, который сам находит «зависшие» задачи
|
||||
и доигрывает пропущенный переход — через **те же штатные гейты и обработчики**, что и
|
||||
webhook (никакой параллельной логики продвижения). Убрать необходимость в ручном
|
||||
heartbeat-watchdog.
|
||||
|
||||
## 3. Заинтересованные стороны
|
||||
- **Owner / Стрим (Слава)** — перестаёт ловить зависания вручную.
|
||||
- **Все проекты на инстансе** (enduro-trails + orchestrator) — конвейер не встаёт молча.
|
||||
- **Self-hosting (ORCH)** — особенно при ребилде прода (ORCH-51): вебхуки, прилетевшие
|
||||
на падающий инстанс, подбираются реконсиляцией после старта.
|
||||
|
||||
## 4. Объём (Scope)
|
||||
|
||||
В объёме — **две взаимодополняющие ветки реконсиляции** (обе обязательны):
|
||||
|
||||
### F-1. Gate-side sweeper (реконсиляция застрявшей стадии по локальной БД)
|
||||
Периодический проход по таблице `tasks`: найти задачи, у которых
|
||||
(а) `stage != done`, (б) нет активных job'ов в очереди, (в) с момента `updated_at`
|
||||
прошло больше **per-stage порога** → пере-проверить QG текущей стадии и, если passed —
|
||||
продвинуть **штатным путём** (`stage_engine.advance_stage(..., finished_agent=None)`,
|
||||
тот же путь, что использует webhook). Закрывает потерю Gitea CI/PR-вебхуков (ORCH-044).
|
||||
|
||||
### F-2. Plane-side reconciler (реконсиляция потерянного Plane status-webhook)
|
||||
Периодический опрос Plane API по проектам реестра (`projects.py`): issues в статусах,
|
||||
требующих действия (In Progress / Approved / Rejected). Сверить с локальной `tasks` и
|
||||
доиграть **через существующие обработчики `webhooks/plane.py`**:
|
||||
- **In Progress + нет задачи в БД** → создать+запустить (`handle_status_start`/`start_pipeline`);
|
||||
- **Approved + стадия не сдвинута** → advance (`handle_verdict(approved=True)`);
|
||||
- **Rejected + не откатана** → rollback (`handle_verdict(approved=False)`).
|
||||
|
||||
### F-3. Усиление sha→branch резолва в Gitea-вебхуке
|
||||
В `handle_ci_status` добавить надёжный fallback (поиск task по БД), чтобы исходный
|
||||
webhook реже терялся из-за неразрезолвленного branch. Sweeper работает от задачи
|
||||
(repo+branch известны из БД) и обходит эту хрупкость по определению.
|
||||
|
||||
### F-4. Наблюдаемость
|
||||
Лог (и опц. Telegram) каждый раз, когда sweeper **разблокировал** застрявшую задачу —
|
||||
чтобы видеть частоту срабатывания дыры (метрика потерянных webhook). Опц. вывод
|
||||
счётчика в `/queue` или `/reconcile`. Не спамить, когда всё синхронно.
|
||||
|
||||
### Вне объёма
|
||||
- Буфер недоставленных webhook (это ORCH-51; sweeper — резервная сетка к нему).
|
||||
- Изменение состава стадий/гейтов (`STAGE_TRANSITIONS`, `QG_CHECKS`).
|
||||
- Изменение логики самих гейтов и обработчиков (только переиспользование).
|
||||
- Новый исполняемый деплой (ORCH-36).
|
||||
|
||||
## 5. Ключевые требования (бизнес-уровень)
|
||||
|
||||
1. **Источник истины — гейт/Plane, а не событие.** Sweeper дёргает ровно те же функции
|
||||
продвижения, что и webhook. Параллельной логики продвижения быть не должно.
|
||||
2. **Идемпотентность (критично).** Задержавшийся или дублированный webhook + sweeper
|
||||
НЕ создают двойную задачу / двойной запуск / двойной advance. Тот же guard, что у
|
||||
webhook: нет активного job + стадия совпадает + atomic claim как в `queue_worker`.
|
||||
3. **Безопасность активной работы.** Sweeper НЕ трогает задачи с активными
|
||||
(`queued`/`running`) job'ами — они легитимно в работе, не потеряны.
|
||||
4. **Per-stage grace.** Разные стадии имеют разное нормальное время (analysis ~8–15 мин
|
||||
vs deploy). Порог застревания настраивается, чтобы не дёргать гейт у задачи, где агент
|
||||
законно работает.
|
||||
5. **Restart-safe.** Sweeper — фоновый поток, стартует с приложением, переживает рестарт
|
||||
(как `queue_worker`). Без потери состояния.
|
||||
6. **Self-hosting safety.** Sweeper не должен ронять/рестартить прод-контейнер; kill-switch
|
||||
в конфиге для поэтапного раската и аварийного отключения.
|
||||
7. **Без шума.** Когда всё синхронно — никаких действий и нотификаций.
|
||||
8. **Документация = golden source.** README/architecture, ADR, CHANGELOG обновляются в
|
||||
том же PR.
|
||||
|
||||
## 6. Эффект
|
||||
- Потерянный webhook больше не = молча застрявшая задача.
|
||||
- Ручной heartbeat-watchdog Стрима больше не нужен для ловли зависаний (AC-5 в эпике).
|
||||
- Резервная сетка к ORCH-51 при ребилде прода.
|
||||
|
||||
## 7. Связи
|
||||
- **Дополняет ORCH-51** (потеря webhook при рестарте — буфер; sweeper — реконсиляция).
|
||||
- **Дополняет ORCH-36** (если deploy-webhook потеряется — sweeper добьёт deploy→done).
|
||||
- **ORCH-1b** — та же философия resilience: транзиентный сбой не убивает задачу.
|
||||
- Эпик: звено **ORCH-54** (автономное внедрение). Параллельна ORCH-36 (разные файлы),
|
||||
но `max_concurrency=1` → встанет в очередь.
|
||||
|
||||
## 8. Риски (кратко; подробно — 10-tech-risks архитектора)
|
||||
- **Гонка sweeper ↔ живой webhook** → двойной запуск. Митигируется atomic claim +
|
||||
active-job guard + grace-период (не конкурировать с задержавшимся webhook).
|
||||
- **Spam нотификаций** при персистентно красном гейте на каждом тике. Митигируется:
|
||||
действие/нотификация только на изменении состояния (advance), не на каждый тик.
|
||||
- **Нагрузка на Plane API** при опросе каждые N сек. Митигируется интервалом + фильтром
|
||||
по статусам + per-project.
|
||||
- **Self-hosting:** sweeper правит инструмент, обслуживающий и другие проекты. Kill-switch
|
||||
обязателен.
|
||||
@@ -1,170 +0,0 @@
|
||||
# ТЗ — ORCH-053: Sweeper потерянных webhook (реконсиляция застрявших стадий)
|
||||
|
||||
Work Item ID: ORCH-053
|
||||
Базовая ветка: `feature/ORCH-053-sweeper-webhook-stuck-task`
|
||||
|
||||
> Это ТЗ фиксирует **конкретные изменения кода/конфига/доки**. Архитектурные развилки
|
||||
> (потокобезопасность, точная схема дампинга нотификаций, способ вызова async-обработчиков
|
||||
> из sync-потока) фиксирует архитектор в `06-adr/`. Если ТЗ окажется негодным — возврат в
|
||||
> Анализ (не комментировать задним числом).
|
||||
|
||||
## 0. Живая разведка ПЕРЕД реализацией (обязательна)
|
||||
Перед кодом разработчик обязан вживую проверить (как сейчас webhook продвигает стадию):
|
||||
- `src/webhooks/gitea.py::handle_ci_status` (success-ветка ~стр.199–217) и `handle_pr`;
|
||||
- `src/webhooks/plane.py::handle_issue_updated / handle_status_start / handle_verdict / start_pipeline`;
|
||||
- `src/stage_engine.py::advance_stage` (унифицированный путь, `finished_agent=None` = webhook-путь);
|
||||
- `src/queue_worker.py` (образец фонового daemon-потока + `threading.Event` + atomic claim);
|
||||
- `src/db.py::has_active_job_for_task / claim_next_job / update_task_stage` (`updated_at`).
|
||||
|
||||
## 1. Задействованные модули `src/`
|
||||
|
||||
| Модуль | Изменение |
|
||||
|--------|-----------|
|
||||
| `src/reconciler.py` | **НОВЫЙ.** Фоновый sweeper/reconciler (класс + module-singleton, паттерн `queue_worker`). Обе ветки F-1 (gate-side) и F-2 (plane-side). |
|
||||
| `src/config.py` | Новые настройки `reconcile_*` (интервал, kill-switch, per-stage grace, plane-poll flag). |
|
||||
| `src/main.py` | Старт/стоп reconciler в `lifespan` (после `worker.start()` / перед `worker.stop()`). |
|
||||
| `src/stage_engine.py` | Тонкий хелпер `advance_if_gate_passed(...)` (или `reconcile_advance`) — обёртка над `advance_stage(..., finished_agent=None)`, **подавляющая повторный спам нотификаций** при провале гейта (продвижение — переиспользуется как есть). |
|
||||
| `src/plane_sync.py` | НОВЫЙ хелпер `list_issues_by_state(project_id, state_uuids) -> list[dict]` (GET issues с пагинацией, фильтр по state). Используется F-2. |
|
||||
| `src/webhooks/gitea.py` | F-3: усилить sha→branch резолв в `handle_ci_status` (fallback на БД-поиск task), логировать неразрезолв на уровне INFO (видимость). |
|
||||
| `src/webhooks/plane.py` | F-2 переиспользует `handle_issue_updated` / `handle_status_start` / `handle_verdict` **без дублирования** логики (возможно, лёгкий рефактор для вызова из reconciler). |
|
||||
| `src/main.py` (API) | F-4 (опц.): расширить `/queue` блоком reconcile-метрик или добавить `GET /reconcile`. |
|
||||
|
||||
## 2. F-1 — Gate-side sweeper (реконсиляция по локальной БД)
|
||||
|
||||
### Алгоритм одного прохода (`reconcile_gate_once()`)
|
||||
```
|
||||
для каждой task где stage NOT IN ('done',) :
|
||||
если has_active_job_for_task(task.id): continue # в работе — не трогаем
|
||||
если get_qg_for_stage(task.stage) is None: continue # created/done — нет гейта
|
||||
grace = grace_for_stage(task.stage)
|
||||
если age(task.updated_at) < grace: continue # ещё не «застряла»
|
||||
# источник истины — гейт; путь продвижения — штатный
|
||||
advance_if_gate_passed(task.id, task.stage, task.repo, task.work_item_id, task.branch)
|
||||
```
|
||||
- **Продвижение** идёт через `stage_engine.advance_stage(task_id, stage, repo, work_item_id,
|
||||
branch, finished_agent=None)` — это **тот же** путь, которым пользуется Plane Approved-webhook
|
||||
(`webhooks/plane._try_advance_stage`). Никакой параллельной логики advance.
|
||||
- Для `development` → `advance_stage` прогонит `check_ci_green`; passed → `review` + enqueue
|
||||
`reviewer`. Для `review` → `check_reviewer_verdict` (канонический гейт стадии из
|
||||
`STAGE_TRANSITIONS`, читает `verdict:` из `12-review.md`). Для `testing` → `check_tests_passed`.
|
||||
Для `deploy` → `check_deploy_status`. Для `deploy-staging` → `check_staging_status`
|
||||
(+ merge-gate sub-gate отрабатывает внутри `advance_stage` как обычно).
|
||||
- **Стадия `analysis`** (gQG `check_analysis_approved`): это **человеческий** гейт. В
|
||||
`advance_stage` при `finished_agent=None` он трактуется как `approved-via-status` и
|
||||
продвинет задачу — чего при потере именно **Approved**-webhka мы и хотим **только** если
|
||||
Plane реально в статусе Approved. Поэтому **F-1 НЕ реконсилирует `analysis`** (advance
|
||||
для analysis отдаётся F-2, которая сверяется с реальным статусом Plane). Архитектор
|
||||
фиксирует это решение в ADR (защита от ложного продвижения неодобренного BRD).
|
||||
|
||||
### Подавление спама нотификаций (`advance_if_gate_passed`)
|
||||
- Если гейт **passed** → `advance_stage` продвигает и шлёт штатные нотификации advance.
|
||||
- Если гейт **failed** → НЕ повторять `notify_qg_failure`/`plane_notify_qg` на каждом тике.
|
||||
Хелпер вызывает `advance_stage` так, чтобы при провале была **тишина** (лог `INFO`/`DEBUG`),
|
||||
либо реализует продвижение, минуя ветку нотификации провала. Точную форму (флаг в
|
||||
`advance_stage` vs отдельный путь оценки гейта) выбирает архитектор; контракт:
|
||||
**на застрявшей-но-красной задаче sweeper не спамит**.
|
||||
|
||||
### Защита от гонки
|
||||
- `has_active_job_for_task` + `update_task_stage` обновляет `updated_at` → следующий тик
|
||||
увидит свежий `updated_at` и не сработает повторно.
|
||||
- Если в момент тика прилетел живой webhook и поставил job — sweeper увидит активный job и
|
||||
пропустит задачу.
|
||||
- `max_concurrency=1`: новый enqueued job встанет в общую очередь (без двойного запуска).
|
||||
|
||||
## 3. F-2 — Plane-side reconciler (опрос Plane API)
|
||||
|
||||
### Алгоритм одного прохода (`reconcile_plane_once()`)
|
||||
```
|
||||
для каждого проекта p в projects.PROJECTS:
|
||||
states = get_project_states(p.plane_project_id)
|
||||
for issue in list_issues_by_state(p.plane_project_id,
|
||||
[states['in_progress'], states['approved'], states['rejected']]):
|
||||
task = get_task_by_plane_id(issue.id)
|
||||
new_state = issue.state
|
||||
# идемпотентность: пропускаем, если есть активный job (живой webhook вот-вот придёт/в работе)
|
||||
если task and has_active_job_for_task(task.id): continue
|
||||
# доигрываем потерянный переход ЧЕРЕЗ существующие обработчики plane.py
|
||||
if new_state == in_progress and task is None: -> handle_status_start(issue_data, p.plane_project_id)
|
||||
elif new_state == approved and task and stage не сдвинут: -> handle_verdict(issue_data, ..., approved=True)
|
||||
elif new_state == rejected and task and не откатана: -> handle_verdict(issue_data, ..., approved=False)
|
||||
else: continue # всё синхронно — тишина
|
||||
```
|
||||
- **Переиспользовать** `handle_issue_updated`/`handle_status_start`/`handle_verdict` из
|
||||
`webhooks/plane.py`. Они `async` → reconciler (sync-поток) вызывает их через
|
||||
`asyncio.run(...)` либо собственный event loop. Способ — на усмотрение архитектора;
|
||||
**дублировать логику запрещено**.
|
||||
- `issue_data` собирается в форму, ожидаемую обработчиками (`{"id", "state": {"id":...},
|
||||
"project", "name", "description_stripped"}`). Недостающие поля (name/description)
|
||||
обработчики сами дотягивают через `fetch_issue_fields` (как сейчас для status-only вебхука).
|
||||
- **Grace для F-2:** не реагировать на issue, чей статус сменился совсем недавно (вебхук мог
|
||||
просто задержаться). Источник «давности» — поле времени из Plane (`updated_at`) и/или
|
||||
локальный grace по `tasks.updated_at`. Архитектор фиксирует точный критерий «потерян, а не
|
||||
задержан».
|
||||
- **Идемпотентность создания (In Progress без задачи):** `start_pipeline` уже защищён
|
||||
(`handle_status_start` создаёт только если `get_task_by_plane_id` пуст). Гонка sweeper↔webhook
|
||||
на создании: оба пройдут проверку «нет задачи» одновременно → возможен дубль. Требование:
|
||||
использовать тот же claim-механизм / уникальность (как `ensure_unique_work_item_id` +
|
||||
проверка существования под защитой). Архитектор обязан описать atomic-claim на создании в ADR.
|
||||
|
||||
### `list_issues_by_state` (новый в `plane_sync.py`)
|
||||
- `GET {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{pid}/issues/` с фильтром по state
|
||||
(через query-параметр Plane, либо постфильтрация результата по `issue.state`).
|
||||
- Пагинация (`results` + cursor/next) — обойти все страницы.
|
||||
- Never-raise: при ошибке API/сети → `[]` + лог `warning` (Plane outage деградирует мягко,
|
||||
не роняет тик).
|
||||
|
||||
## 4. F-3 — Усиление sha→branch резолва (`webhooks/gitea.py::handle_ci_status`)
|
||||
- Текущая цепочка: `branches[0].name` → `git branch -r --contains <sha>`. Добавить
|
||||
fallback **на БД**: если branch не определён, найти task по `repo` среди активных
|
||||
(`stage='development'`) и, при однозначности, использовать её branch; иначе — оставить
|
||||
неразрезолвленным.
|
||||
- Заменить `logger.debug("could not determine branch...")` на `logger.info(...)` (видимость
|
||||
потери). Sweeper (F-1) всё равно подберёт такую задачу — это defense-in-depth, не критпуть.
|
||||
- **Не менять** success/failure-семантику гейта.
|
||||
|
||||
## 5. Конфигурация (`src/config.py`, env-prefix `ORCH_`)
|
||||
|
||||
| Поле | Дефолт | Назначение |
|
||||
|------|--------|-----------|
|
||||
| `reconcile_enabled` | `True` | глобальный kill-switch sweeper'а (self-hosting safety, поэтапный раскат). |
|
||||
| `reconcile_interval_s` | `120` | период фонового прохода (сек). |
|
||||
| `reconcile_plane_enabled` | `True` | отдельный флаг для F-2 (опрос Plane API), чтобы можно было гасить только plane-ветку. |
|
||||
| `reconcile_grace_default_s` | `600` | дефолтный порог «застревания» по `tasks.updated_at`. |
|
||||
| `reconcile_grace_overrides_json` | `""` | JSON-объект per-stage порогов, напр. `{"analysis": 1800, "development": 300, "deploy": 900}`. Невалидный JSON → дефолт (как `agent_timeout_overrides_json`). |
|
||||
| `reconcile_notify_unblock` | `True` | слать Telegram при разблокировке (F-4). |
|
||||
|
||||
`grace_for_stage(stage)` = override из JSON, иначе `reconcile_grace_default_s`.
|
||||
|
||||
## 6. БД
|
||||
- **Изменения схемы НЕ требуются** (предпочтительно, по образцу merge-gate ORCH-043).
|
||||
Стуковость определяется по существующим `tasks.updated_at`, `tasks.stage` и таблице `jobs`
|
||||
(`has_active_job_for_task`). `update_task_stage` уже обновляет `updated_at`.
|
||||
- Если архитектор сочтёт необходимым анти-дребезг (`tasks.last_reconcile_at`) — допускается
|
||||
идемпотентная миграция через `_ensure_column` (как остальные ALTER в `db.py`). По умолчанию
|
||||
— **без новых колонок**.
|
||||
|
||||
## 7. API (опционально, F-4)
|
||||
- Расширить `GET /queue` блоком `"reconcile": {...}` (enabled, interval, last_run_ts,
|
||||
unblocked_total, last_unblocked) — по образцу `worker.status()`.
|
||||
- ИЛИ добавить `GET /reconcile` с теми же метриками. Выбор — архитектор. Не обязательно для
|
||||
прохождения AC, но крайне желательно для наблюдаемости.
|
||||
|
||||
## 8. Новые QG checks
|
||||
- **Нет.** Sweeper переиспускает существующие гейты из `QG_CHECKS` через `advance_stage`.
|
||||
Реестр `QG_CHECKS` и `STAGE_TRANSITIONS` не меняются.
|
||||
|
||||
## 9. Артефакты pipeline / документация (обязательно в ЭТОМ PR)
|
||||
- `docs/architecture/README.md` — раздел про reconciler (компонент + место в resilience-слое).
|
||||
- `docs/work-items/ORCH-053/06-adr/ADR-001-*.md` — архитектурное решение (потоки, гонки,
|
||||
async-вызов обработчиков, подавление спама, grace-критерий, atomic-claim на создании).
|
||||
- `CHANGELOG.md` — запись `feat: ORCH-053 stuck-task reconciler`.
|
||||
- При желании архитектора — global ADR в `docs/architecture/adr/` (сквозной resilience).
|
||||
- `docs/operations/INFRA.md` — упомянуть kill-switch `ORCH_RECONCILE_ENABLED` (self-hosting).
|
||||
|
||||
## 10. Нефункциональные требования
|
||||
- **Never-raise в тике:** исключение в обработке одной задачи/issue не должно ронять весь
|
||||
проход (изолировать try/except на единицу работы, как `queue_worker._drain_once`).
|
||||
- **Идемпотентность** — см. §2/§3.
|
||||
- **Restart-safe** — daemon-поток + `threading.Event`, чистый `stop()` в `lifespan.finally`.
|
||||
- **Тишина при синхронности** — нет действий → нет логов уровня INFO/нотификаций.
|
||||
- **Тесты** — см. `04-test-plan.yaml` (моки Plane/Gitea API и QG, без реальной сети).
|
||||
@@ -1,116 +0,0 @@
|
||||
# Acceptance Criteria — ORCH-053
|
||||
|
||||
Work Item ID: ORCH-053
|
||||
Формат: каждый критерий имеет явное условие PASS/FAIL. Критерий считается выполненным,
|
||||
только если соответствующие тесты из `04-test-plan.yaml` зелёные.
|
||||
|
||||
## AC-1 — Реконсиляция застрявшей стадии (gate-side, F-1)
|
||||
- **Дано:** task на стадии `development`, без активных job'ов, `updated_at` старше grace,
|
||||
гейт `check_ci_green` для её branch — зелёный (CI прошёл, но webhook потерян, как ORCH-044).
|
||||
- **Когда:** срабатывает фоновый проход `reconcile_gate_once()`.
|
||||
- **PASS:** задача продвинута `development → review`, заenqueuen `reviewer` (через
|
||||
`advance_stage(..., finished_agent=None)`), `tasks.updated_at` обновлён.
|
||||
- **FAIL:** задача осталась на `development`, либо продвижение пошло параллельной логикой
|
||||
(не через `advance_stage`).
|
||||
|
||||
## AC-2 — Источник истины — гейт, не событие
|
||||
- **PASS:** продвижение в F-1 выполняется исключительно вызовом
|
||||
`stage_engine.advance_stage(...)`; в `reconciler.py` НЕТ собственного
|
||||
`update_task_stage`+`enqueue_job` для advance стадии (только переиспользование).
|
||||
- **FAIL:** в reconciler продублирована логика advance/rollback.
|
||||
|
||||
## AC-3 — Идемпотентность: sweeper не трогает задачи с активным job
|
||||
- **Дано:** task с `queued` или `running` job (`has_active_job_for_task == True`).
|
||||
- **PASS:** sweeper пропускает задачу — ни advance, ни enqueue, ни нотификации.
|
||||
- **FAIL:** sweeper дёргает гейт / создаёт второй job для такой задачи.
|
||||
|
||||
## AC-4 — Идемпотентность: задержавшийся/дублированный webhook + sweeper не двоят
|
||||
- **Дано:** issue в Plane = In Progress, задержавшийся Plane-webhook ещё не обработан.
|
||||
- **Когда:** F-2 реконсилирует И затем (или одновременно) приходит реальный webhook.
|
||||
- **PASS:** создаётся **ровно одна** задача (один task row, один branch/worktree, один
|
||||
стартовый analyst-job). Повторный путь видит существующую задачу/активный job и не двоит.
|
||||
- **FAIL:** созданы две задачи / два стартовых job / два worktree на один `plane_id`.
|
||||
|
||||
## AC-5 — Per-stage grace соблюдается
|
||||
- **Дано:** task на стадии, чей `updated_at` свежее grace этой стадии (агент легитимно
|
||||
работает, напр. analysis 8 мин при grace 1800с).
|
||||
- **PASS:** sweeper НЕ трогает задачу (не дёргает гейт).
|
||||
- **PASS (граница):** как только `age(updated_at) >= grace_for_stage(stage)` и нет активного
|
||||
job — задача становится кандидатом.
|
||||
- **FAIL:** sweeper дёргает гейт у задачи в пределах grace.
|
||||
|
||||
## AC-6 — Plane In Progress без задачи → запуск (F-2)
|
||||
- **Дано:** issue в Plane = In Progress (статус сменён руками, webhook потерян), в `tasks`
|
||||
задачи нет, прошёл grace.
|
||||
- **PASS:** sweeper вызывает `handle_status_start`/`start_pipeline` → задача создана,
|
||||
заenqueuen analyst — как если бы пришёл webhook.
|
||||
- **FAIL:** задача не создана; либо создана дублирующей логикой, минуя `handle_status_start`.
|
||||
|
||||
## AC-7 — Plane Approved без advance → advance (F-2)
|
||||
- **Дано:** issue = Approved, task существует и стадия НЕ сдвинута, нет активного job, прошёл grace.
|
||||
- **PASS:** sweeper вызывает `handle_verdict(approved=True)` → штатный advance.
|
||||
- **FAIL:** нет advance, либо advance вне `handle_verdict`/`advance_stage`.
|
||||
|
||||
## AC-8 — Plane Rejected без rollback → rollback (F-2)
|
||||
- **Дано:** issue = Rejected, task существует и не откатана, нет активного job, прошёл grace.
|
||||
- **PASS:** sweeper вызывает `handle_verdict(approved=False)` → штатный rollback на предыдущую стадию.
|
||||
- **FAIL:** нет rollback, либо rollback вне штатного пути.
|
||||
|
||||
## AC-9 — Нет спама нотификаций на красном гейте
|
||||
- **Дано:** застрявшая задача, у которой гейт стабильно **красный** (напр. CI failure),
|
||||
нет активного job, прошёл grace.
|
||||
- **Когда:** sweeper проходит несколько тиков подряд.
|
||||
- **PASS:** `notify_qg_failure`/Telegram НЕ вызывается на каждом тике (≤1 раз / без
|
||||
повторов); задача не продвигается.
|
||||
- **FAIL:** на каждом тике летит нотификация о провале гейта.
|
||||
|
||||
## AC-10 — Тишина при синхронности
|
||||
- **Дано:** все задачи синхронны (нет застрявших; статусы Plane совпадают с локальными).
|
||||
- **PASS:** проход не выполняет действий, не пишет INFO-логов о разблокировке, не шлёт нотификаций.
|
||||
- **FAIL:** sweeper генерирует шум/действия при полностью синхронном состоянии.
|
||||
|
||||
## AC-11 — Restart-safe фоновый поток
|
||||
- **PASS:** reconciler стартует в `main.lifespan` (daemon-поток), корректно
|
||||
останавливается (`stop()`), переживает рестарт сервиса без потери (нет состояния в памяти,
|
||||
критичного для корректности; всё перечитывается из БД/Plane).
|
||||
- **FAIL:** reconciler не стартует автоматически, висит при shutdown, или дублирует действия
|
||||
после рестарта.
|
||||
|
||||
## AC-12 — Наблюдаемость разблокировки (F-4)
|
||||
- **Дано:** sweeper разблокировал застрявшую задачу.
|
||||
- **PASS:** в лог пишется явная строка вида
|
||||
`reconciler: <work_item_id> <stage> разблокирована (потерян webhook)`;
|
||||
при `reconcile_notify_unblock=True` — Telegram-уведомление.
|
||||
- **FAIL:** разблокировка происходит молча (невозможно измерить частоту дыры).
|
||||
|
||||
## AC-13 — Kill-switch
|
||||
- **Дано:** `reconcile_enabled=False` (env `ORCH_RECONCILE_ENABLED=false`).
|
||||
- **PASS:** фоновый поток reconciler не выполняет проходов (или не стартует); система
|
||||
работает как до ORCH-053. `reconcile_plane_enabled=False` гасит только F-2, F-1 работает.
|
||||
- **FAIL:** sweeper активен при выключенном флаге.
|
||||
|
||||
## AC-14 — Усиленный sha→branch резолв (F-3)
|
||||
- **Дано:** Gitea CI-status webhook без `branches` и со `sha`, не разрезолвившимся
|
||||
через `git branch -r --contains`.
|
||||
- **PASS:** добавленный БД-fallback однозначно находит task (по repo + активной
|
||||
development-стадии) и продвигает; неоднозначность логируется на уровне INFO; существующая
|
||||
success/failure-семантика гейта не изменена.
|
||||
- **FAIL:** регресс существующего резолва, либо ложный матч при неоднозначности.
|
||||
|
||||
## AC-15 — Never-raise в тике
|
||||
- **Дано:** обработка одной задачи/issue кидает исключение (битые данные, ошибка API).
|
||||
- **PASS:** исключение изолировано, проход продолжает остальные задачи; поток не падает.
|
||||
- **FAIL:** одно исключение роняет весь проход / поток reconciler.
|
||||
|
||||
## AC-16 — F-1 не продвигает analysis по локальному состоянию
|
||||
- **Дано:** task на `analysis`, артефакты на диске присутствуют, но Plane НЕ в статусе
|
||||
Approved (BRD не одобрен человеком), нет активного job, прошёл grace.
|
||||
- **PASS:** F-1 (gate-side) НЕ продвигает analysis→architecture (advance стадии analysis
|
||||
отдан F-2, которая сверяется с реальным статусом Plane Approved).
|
||||
- **FAIL:** sweeper автопродвинул неодобренный BRD.
|
||||
|
||||
## AC-17 — Документация обновлена (golden source)
|
||||
- **PASS:** в PR обновлены `docs/architecture/README.md`, заведён
|
||||
`docs/work-items/ORCH-053/06-adr/ADR-001-*.md`, обновлён `CHANGELOG.md`, упомянут
|
||||
kill-switch в `docs/operations/INFRA.md`.
|
||||
- **FAIL:** код изменён, документация — нет (Reviewer обязан вернуть REQUEST_CHANGES).
|
||||
@@ -1,200 +0,0 @@
|
||||
work_item: ORCH-053
|
||||
description: >
|
||||
Тесты sweeper/reconciler потерянных webhook. Вся сеть (Plane API, Gitea API, QG)
|
||||
мокируется (monkeypatch), как в существующих tests/. Telegram заглушён autouse-фикстурой
|
||||
conftest. Используется временная SQLite БД (ORCH_DB_PATH / фикстура setup_db по образцу
|
||||
test_webhooks.py / test_queue.py). Реальные агенты/CLI не запускаются.
|
||||
|
||||
tests:
|
||||
# ---- F-1: gate-side sweeper -------------------------------------------------
|
||||
- id: TC-01
|
||||
type: unit
|
||||
description: >
|
||||
reconcile_gate_once продвигает застрявшую development-задачу: нет активных job,
|
||||
updated_at старше grace, check_ci_green замокан в (True, "CI green") →
|
||||
advance_stage вызван, стадия стала review, заenqueuen reviewer.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-02
|
||||
type: unit
|
||||
description: >
|
||||
Источник истины — гейт: reconciler НЕ содержит собственного update_task_stage/
|
||||
enqueue_job для advance — продвижение идёт строго через stage_engine.advance_stage
|
||||
(проверка через мок/spy advance_stage, вызван с finished_agent=None).
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-03
|
||||
type: unit
|
||||
description: >
|
||||
Задача с активным job (has_active_job_for_task=True) пропускается: гейт не дёргается,
|
||||
advance_stage не вызывается, нотификаций нет.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-04
|
||||
type: unit
|
||||
description: >
|
||||
Per-stage grace: задача с updated_at свежее grace своей стадии не трогается;
|
||||
ровно на границе age>=grace и без активного job — становится кандидатом.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-05
|
||||
type: unit
|
||||
description: >
|
||||
grace_for_stage читает reconcile_grace_overrides_json (per-stage), при отсутствии
|
||||
ключа — reconcile_grace_default_s; невалидный JSON → дефолт, не падает.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-06
|
||||
type: unit
|
||||
description: >
|
||||
Нет спама: при стабильно красном гейте (check_ci_green=(False,...)) несколько проходов
|
||||
подряд НЕ вызывают notify_qg_failure повторно на каждом тике; задача не продвигается.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-07
|
||||
type: unit
|
||||
description: >
|
||||
Тишина при синхронности: когда все задачи done / имеют активный job / в пределах grace —
|
||||
проход не вызывает advance_stage и не пишет INFO-логов о разблокировке.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-08
|
||||
type: unit
|
||||
description: >
|
||||
AC-16: задача на analysis с артефактами на диске, но Plane НЕ Approved — F-1
|
||||
(reconcile_gate_once) НЕ продвигает analysis→architecture.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-09
|
||||
type: unit
|
||||
description: >
|
||||
Never-raise: если обработка одной задачи кидает исключение (advance_stage замокан на
|
||||
raise), проход ловит его и продолжает обрабатывать остальные задачи; поток не падает.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-10
|
||||
type: unit
|
||||
description: >
|
||||
Kill-switch: при reconcile_enabled=False reconcile_gate_once/plane_once не выполняют
|
||||
действий (no-op); при reconcile_plane_enabled=False гасится только F-2.
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
# ---- F-2: plane-side reconciler --------------------------------------------
|
||||
- id: TC-11
|
||||
type: unit
|
||||
description: >
|
||||
In Progress без задачи: list_issues_by_state возвращает issue в In Progress, в БД задачи
|
||||
нет → reconcile_plane_once вызывает handle_status_start (мок) ровно один раз с корректным
|
||||
issue_data (id/state/project).
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-12
|
||||
type: unit
|
||||
description: >
|
||||
Approved без advance: issue=Approved, task существует, нет активного job → вызван
|
||||
handle_verdict(approved=True) (мок) один раз.
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-13
|
||||
type: unit
|
||||
description: >
|
||||
Rejected без rollback: issue=Rejected, task существует, нет активного job → вызван
|
||||
handle_verdict(approved=False) (мок) один раз.
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-14
|
||||
type: unit
|
||||
description: >
|
||||
Идемпотентность F-2: issue в требующем-действия статусе, но у task есть активный job →
|
||||
handle_status_start/handle_verdict НЕ вызываются (живой webhook в работе).
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-15
|
||||
type: integration
|
||||
description: >
|
||||
AC-4 анти-дубль на создании: одновременная реконсиляция + обработка реального In Progress
|
||||
webhook для одного plane_id создают ровно ОДИН task row и один стартовый analyst-job
|
||||
(реальная временная БД, мок Gitea/Plane сетевых вызовов).
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-16
|
||||
type: unit
|
||||
description: >
|
||||
list_issues_by_state never-raise: при ошибке Plane API (httpx бросает / non-2xx) →
|
||||
возвращает [], тик не падает; при успехе — обходит пагинацию и фильтрует по state.
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-17
|
||||
type: unit
|
||||
description: >
|
||||
F-2 опрашивает все проекты реестра projects.PROJECTS и резолвит state-uuid через
|
||||
get_project_states per-project (enduro + orchestrator), не хардкодит uuid.
|
||||
module: tests/test_reconciler_plane.py
|
||||
expected: PASS
|
||||
|
||||
# ---- F-3: sha→branch резолв -------------------------------------------------
|
||||
- id: TC-18
|
||||
type: unit
|
||||
description: >
|
||||
handle_ci_status: при отсутствии branches и неразрезолвленном sha срабатывает БД-fallback
|
||||
и однозначно находит единственную development-задачу repo; продвижение идёт штатно.
|
||||
module: tests/test_gitea_sha_resolve.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-19
|
||||
type: unit
|
||||
description: >
|
||||
handle_ci_status: при неоднозначности (несколько development-задач repo) БД-fallback не
|
||||
делает ложный матч (branch остаётся неразрезолвленным, лог INFO), success/failure-семантика
|
||||
гейта не изменена.
|
||||
module: tests/test_gitea_sha_resolve.py
|
||||
expected: PASS
|
||||
|
||||
# ---- F-4 / интеграция фонового потока --------------------------------------
|
||||
- id: TC-20
|
||||
type: unit
|
||||
description: >
|
||||
Наблюдаемость: при разблокировке reconciler пишет явную лог-строку с work_item_id и
|
||||
stage; при reconcile_notify_unblock=True вызывается send_telegram (замокан).
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-21
|
||||
type: integration
|
||||
description: >
|
||||
Restart-safe поток: Reconciler.start() поднимает daemon-поток, stop() завершает его
|
||||
в пределах таймаута; повторный start идемпотентен (не плодит второй поток).
|
||||
module: tests/test_reconciler.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-22
|
||||
type: unit
|
||||
description: >
|
||||
Конфиг: новые поля reconcile_* присутствуют в Settings с заявленными дефолтами и
|
||||
читаются из env с префиксом ORCH_ (по образцу tests/test_config.py).
|
||||
module: tests/test_config.py
|
||||
expected: PASS
|
||||
|
||||
- id: TC-23
|
||||
type: unit
|
||||
description: >
|
||||
Регресс реестров: STAGE_TRANSITIONS и QG_CHECKS не изменены ORCH-053
|
||||
(snapshot-тест проходит как раньше).
|
||||
module: tests/test_qg_registry_snapshot.py
|
||||
expected: PASS
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user