Compare commits

..

9 Commits

Author SHA1 Message Date
7481ce334e deployer(ORCH-016): deploy stage SUCCESS (artifact-only verdict)
All checks were successful
CI / test (push) Successful in 11s
CI / test (pull_request) Successful in 11s
Pre-conditions met:
- 12-review.md: APPROVED
- 13-test-report.md: PASS
- 15-staging-log.md: staging_status=SUCCESS (10/10)

Self-hosting policy honored: prod-container orchestrator:8500
NOT restarted in stage scope (CLAUDE.md). Real prod docker
pull/restart is delegated to scripts/orchestrator-deploy-hook.sh
(ORCH-36) on PR merge to main.

Quality Gate field: deploy_status: SUCCESS (uppercase) in
14-deploy-log.md frontmatter.
2026-06-05 12:52:06 +00:00
d4b02ef728 deployer(ORCH-016): staging gate SUCCESS (10/10 checks PASS)
All checks were successful
CI / test (push) Successful in 11s
CI / test (pull_request) Successful in 11s
Ran scripts/staging_check.py --base-url http://localhost:8501 --mode stub
against the live orchestrator-staging instance. All blocks green:
  - SMOKE (A1-A3): health, queue, ORCH_STAGING=true
  - ACCESS (B4-B6): Plane sandbox, Gitea sandbox, registry isolation
  - E2E   (C7-C9b): webhook -> branch -> analyst job enqueued
  - CLEANUP: branch + Plane issue deleted, no leftover task rows

Verdict (machine-readable, YAML frontmatter): staging_status: SUCCESS

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-05 12:49:39 +00:00
2fc3206f83 tester(ET): auto-commit from tester run_id=98
All checks were successful
CI / test (push) Successful in 11s
CI / test (pull_request) Successful in 12s
2026-06-05 12:46:42 +00:00
1778d8f8b8 reviewer(ET): auto-commit from reviewer run_id=97
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 11s
2026-06-05 12:44:21 +00:00
0663da6e4c feat(plane): unified status-comment format with duration line (ORCH-016)
All checks were successful
CI / test (push) Successful in 11s
CI / test (pull_request) Successful in 12s
Все агенты (analyst..deployer) теперь пишут финальный коммент через единый
хелпер usage.build_status_comment(...) — заголовок «{icon} {Role} — {описание}»,
опциональная строка Verdict/Status из YAML-frontmatter, строка
«Длительность: 4m 12s» (явный duration_s от launcher, fallback из agent_runs
для аналитика), HTML-блок Документы, тех-хвост <sub>tokens · cost</sub>.

- Новые публичные функции в src/usage.py: build_status_comment, fmt_duration,
  get_agent_duration. usage_comment(...) → тонкая deprecated-обёртка (legacy
  тесты в tests/test_usage.py продолжают работать). artifact_links(...)
  переписан на HTML <li><a>…</a></li> (breaking change для внутреннего API,
  но единственный внешний клиент — _post_usage_comments — мигрирован).
- Новый модуль src/frontmatter.py: defensive YAML reader, никогда не raise.
- stage_engine._build_analyst_ready_comment(...) теперь тонкая обёртка над
  build_status_comment(agent="analyst", ...); task_id пробрасывается из
  _handle_analysis_approved_flow для DB-фоллбэка длительности (AC-14).
- launcher._post_usage_comments(...) принимает duration_s, резолвит stage из
  tasks для deployer и worktree_root для AC-8 graceful skipping.

Тесты (16 файлов, 56 новых тестовых функций, покрывают TC-01..TC-25):
fmt_duration table, build_status_comment по всем агентам, DB-фоллбэк,
authorship под per-agent ботами, дедуп-инвариант, regression на
status-only verdict аналитика и финальный notify_done, snapshot
QG_CHECKS + STAGE_TRANSITIONS.

Документация: docs/architecture/README.md (раздел Plane Sync),
CHANGELOG.md (Unreleased Added/Changed).

Refs: ORCH-016

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-05 12:39:06 +00:00
1150cd9144 architect(ET): auto-commit from architect run_id=95
All checks were successful
CI / test (push) Successful in 12s
2026-06-05 12:15:40 +00:00
57a3f6c9f7 analyst(ET): auto-commit from analyst run_id=94
All checks were successful
CI / test (push) Successful in 13s
2026-06-05 12:05:17 +00:00
0f4d8714dd analyst(ET): auto-commit from analyst run_id=93
All checks were successful
CI / test (push) Successful in 11s
2026-06-05 11:48:54 +00:00
3cb10be03f docs: init ORCH-016 business request
All checks were successful
CI / test (push) Successful in 11s
2026-06-05 14:44:25 +03:00
103 changed files with 139 additions and 7998 deletions

View File

@@ -1,8 +1,4 @@
ORCH_PLANE_API_URL=http://plane-app-api-1:8000 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_API_TOKEN=
ORCH_PLANE_WORKSPACE_SLUG= ORCH_PLANE_WORKSPACE_SLUG=
ORCH_PLANE_WEBHOOK_SECRET= ORCH_PLANE_WEBHOOK_SECRET=
@@ -12,8 +8,3 @@ ORCH_GITEA_WEBHOOK_SECRET=
ORCH_CLAUDE_BIN=/usr/bin/claude ORCH_CLAUDE_BIN=/usr/bin/claude
ORCH_REPOS_DIR=/home/slin/repos ORCH_REPOS_DIR=/home/slin/repos
ORCH_DB_PATH=/app/data/orchestrator.db 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

View File

@@ -12,17 +12,11 @@ jobs:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: Install dependencies - name: Install dependencies
run: | run: |
set -euo pipefail
python3 -m pip install --user --upgrade pip python3 -m pip install --user --upgrade pip
python3 -m pip install --user -r requirements.txt python3 -m pip install --user -r requirements.txt
- name: Test - name: Test
env: env:
PYTHONPATH: ${{ github.workspace }} PYTHONPATH: ${{ github.workspace }}
run: | run: |
# ORCH-39: fail the job on ANY failure. Run the WHOLE suite from the
# repo root. --strict-markers + pytest-asyncio (asyncio_mode=auto, see
# pytest.ini) make async tests actually run instead of silently
# skipping (the hole that hid red tests behind a green CI).
set -euo pipefail
export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/.local/bin:$PATH"
python3 -m pytest tests/ -q -p no:cacheprovider --strict-markers python3 -m pytest tests/ -q

View File

@@ -21,20 +21,10 @@ On stage `deploy-staging` your job is to run the staging test suite and write a
### Steps: ### Steps:
1. Run the staging test suite against the live staging environment. 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:
```bash ```bash
docker exec orchestrator-staging \ python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
python3 /repos/orchestrator/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: 2. Check the exit code:
- Exit code **0** = all tests PASS → `staging_status: SUCCESS` - Exit code **0** = all tests PASS → `staging_status: SUCCESS`

View File

@@ -5,11 +5,6 @@
## [Unreleased] ## [Unreleased]
### Added ### Added
- **Режим `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`. - **Единый 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 рисками). - **Документация по канону** (ORCH-9): `CLAUDE.md` (паспорт проекта), структура `docs/` (`architecture/` + `adr/`, `operations/`, `work-items/`, `history/`), `docs/operations/INFRA.md` (RUNBOOK с инфра-изоляцией и self-hosting рисками).
- **ADR**: adr-0001 (multi-repo registry), adr-0002 (job queue), adr-0003 (условный staging-гейт). - **ADR**: adr-0001 (multi-repo registry), adr-0002 (job queue), adr-0003 (условный staging-гейт).
@@ -20,14 +15,10 @@
- **Реестр проектов** (ORCH-6): `src/projects.py`, фильтрация вебхуков по проекту. - **Реестр проектов** (ORCH-6): `src/projects.py`, фильтрация вебхуков по проекту.
### Changed ### 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` НЕ изменялись. - **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`). - Цепочка стадий: `... testing → deploy-staging → deploy → done` (была без `deploy-staging`).
### Fixed ### 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`. - БАГ-8: провал deploy/deploy-staging → корректный откат на `development`.
- Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings. - Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings.

View File

@@ -3,11 +3,6 @@ services:
build: . build: .
container_name: orchestrator container_name: orchestrator
restart: unless-stopped 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 # 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). # processes from the claude/node subprocess tree are reaped (no zombies, B-2).
init: true init: true
@@ -20,8 +15,7 @@ services:
- /usr/bin/node:/usr/bin/node:ro - /usr/bin/node:/usr/bin/node:ro
- /home/slin/.claude:/home/slin/.claude - /home/slin/.claude:/home/slin/.claude
- /home/slin/.claude.json:/home/slin/.claude.json:ro - /home/slin/.claude.json:/home/slin/.claude.json:ro
# ORCH-040: target согласован с HOME=/home/slin (launcher), не /root/.ssh. - /home/slin/.orchestrator-ssh:/root/.ssh:ro
- /home/slin/.orchestrator-ssh:/home/slin/.ssh:ro
env_file: .env env_file: .env
environment: environment:
- ORCH_REPOS_DIR=/repos - ORCH_REPOS_DIR=/repos
@@ -41,8 +35,6 @@ services:
build: . build: .
container_name: orchestrator-staging container_name: orchestrator-staging
restart: unless-stopped restart: unless-stopped
# ORCH-040: тот же uid хоста, что и у prod (см. комментарий выше / ADR-001).
user: "1000:1000"
init: true init: true
network_mode: host network_mode: host
command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8501"] command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8501"]
@@ -54,8 +46,7 @@ services:
- /usr/bin/node:/usr/bin/node:ro - /usr/bin/node:/usr/bin/node:ro
- /home/slin/.claude:/home/slin/.claude - /home/slin/.claude:/home/slin/.claude
- /home/slin/.claude.json:/home/slin/.claude.json:ro - /home/slin/.claude.json:/home/slin/.claude.json:ro
# ORCH-040: target согласован с HOME=/home/slin (launcher), не /root/.ssh. - /home/slin/.orchestrator-ssh:/root/.ssh:ro
- /home/slin/.orchestrator-ssh:/home/slin/.ssh:ro
env_file: .env.staging env_file: .env.staging
environment: environment:
- ORCH_REPOS_DIR=/repos - ORCH_REPOS_DIR=/repos

View File

@@ -7,7 +7,6 @@
- **Webhook Receivers** (`src/webhooks/plane.py`, `gitea.py`) — приём событий, HMAC-проверка, дедупликация (`_dedup.py`). Роуты: `POST /webhook/plane`, `POST /webhook/gitea`. - **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`. - **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. - **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`. - **Quality Gates** (`src/qg/checks.py`) — проверки выхода со стадии, реестр `QG_CHECKS`.
- **Agent Launcher** (`src/agents/launcher.py`) — запуск Claude CLI агентов в изолированном git worktree, мониторинг, auto-advance. - **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. - **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe.
@@ -47,13 +46,6 @@ created → analysis → architecture → development → review → testing →
- Deploy / deploy-staging FAILED → откат на `development`. - Deploy / deploy-staging FAILED → откат на `development`.
- `get_previous_stage` использует порядок ключей `STAGE_TRANSITIONS`. - `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) ### 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>`: Все агенты (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>`:
@@ -66,7 +58,7 @@ created → analysis → architecture → development → review → testing →
``` ```
- **Длительность** считается launcher'ом (`_monitor_agent`) и пробрасывается в `_post_usage_comments`; для analyst (коммент строится в `stage_engine`) используется DB-фоллбэк `usage.get_agent_duration(task_id, agent)`. - **Длительность** считается 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) ## База данных (SQLite)

View File

@@ -8,8 +8,6 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
| adr-0001 | Реестр проектов (multi-repo) | accepted | 2026-06-02 | ORCH-6 | | adr-0001 | Реестр проектов (multi-repo) | accepted | 2026-06-02 | ORCH-6 |
| adr-0002 | Очередь задач вместо in-process потоков | accepted | 2026-06-03 | ORCH-1 | | adr-0002 | Очередь задач вместо in-process потоков | accepted | 2026-06-03 | ORCH-1 |
| adr-0003 | Условный staging-гейт перед прод-деплоем | accepted | 2026-06-05 | ORCH-35 | | 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 |
## Формат ## Формат
**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded. **Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.

View File

@@ -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 после пуша 13 секунды держит 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`.

View File

@@ -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`.

View File

@@ -107,27 +107,6 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer 2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer
3. Если >= MAX_DEV_RETRIES — эскалация (логирование + уведомление) 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 ## Database Schema
```sql ```sql
@@ -347,10 +326,6 @@ jobs со статусом `running` (воркер умёр на рестарт
- `ORCH_MAX_CONCURRENCY` (default 1) — лимит параллельных jobs. - `ORCH_MAX_CONCURRENCY` (default 1) — лимит параллельных jobs.
- `ORCH_QUEUE_POLL_INTERVAL` (default 2.0) — период опроса. - `ORCH_QUEUE_POLL_INTERVAL` (default 2.0) — период опроса.
- `ORCH_AGENT_MODEL_DEFAULT` / `ORCH_AGENT_MODEL_<AGENT>` (ORCH-41) — модель агентов; дефолт `claude-opus-4-8`.
- `ORCH_AGENT_EFFORT_DEFAULT` / `ORCH_AGENT_EFFORT_<AGENT>` (ORCH-41) — режим `--effort` (low|medium|high|xhigh|max).
- `ORCH_AGENT_FALLBACK_MODEL` (ORCH-41) — опц. `--fallback-model` при overloaded.
- per-project override: `agent_models` / `agent_efforts` в `ORCH_PROJECTS_JSON`; резолверы `resolve_agent_model` / `resolve_agent_effort` (project > per-agent env > default > пусто).
Наблюдаемость: `GET /queue` — counts по статусам + последние 10 jobs. Наблюдаемость: `GET /queue` — counts по статусам + последние 10 jobs.

View File

@@ -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).

View File

@@ -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), а не бесконечные круги.

View File

@@ -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 без ручного пинания стадий.

View File

@@ -30,51 +30,24 @@
Оба: `network_mode: host`, `init: true` (tini как PID 1 — reaping зомби, B-2), `restart: unless-stopped`. Оба: `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) ### Тома (volumes)
- `./data``/app/data` (БД; у staging — `./data/staging`) - `./data``/app/data` (БД; у staging — `./data/staging`)
- `/home/slin/repos``/repos` (рабочие репозитории проектов) - `/home/slin/repos``/repos` (рабочие репозитории проектов)
- `/var/run/docker.sock` (для docker-операций деплоя) - `/var/run/docker.sock` (для docker-операций деплоя)
- claude-code, node, `~/.claude*` (CLI агентов, ro) - claude-code, node, `~/.claude*` (CLI агентов, ro)
- `~/.orchestrator-ssh``/home/slin/.ssh` (ro, деплой по ssh; target в HOME агента, - `~/.orchestrator-ssh``/root/.ssh` (ro, деплой по ssh)
согласован с `HOME=/home/slin` из launcher — ORCH-040, ранее `/root/.ssh`)
## Переменные окружения (карта; значения — в `.env`) ## Переменные окружения (карта; значения — в `.env`)
| Переменная | Назначение | | Переменная | Назначение |
|-----------|-----------| |-----------|-----------|
| `ORCH_PLANE_API_URL` / `_TOKEN` / `_WORKSPACE_SLUG` | доступ к Plane API | | `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_PLANE_WEBHOOK_SECRET` | HMAC-проверка вебхуков Plane |
| `ORCH_GITEA_URL` / `_TOKEN` / `_WEBHOOK_SECRET` | доступ к Gitea + HMAC | | `ORCH_GITEA_URL` / `_TOKEN` / `_WEBHOOK_SECRET` | доступ к Gitea + HMAC |
| `ORCH_CLAUDE_BIN` | путь к claude CLI | | `ORCH_CLAUDE_BIN` | путь к claude CLI |
| `ORCH_REPOS_DIR` / `ORCH_HOST_REPOS_DIR` | каталог репозиториев (в контейнере / на хосте) | | `ORCH_REPOS_DIR` / `ORCH_HOST_REPOS_DIR` | каталог репозиториев (в контейнере / на хосте) |
| `ORCH_DB_PATH` | путь к SQLite БД | | `ORCH_DB_PATH` | путь к SQLite БД |
| `ORCH_PROJECTS_JSON` | реестр проектов (Plane id → repo + prefix); пусто → дефолт из `src/projects.py` | | `ORCH_PROJECTS_JSON` | реестр проектов (Plane id → repo + prefix); пусто → дефолт из `src/projects.py` |
| `ORCH_AGENT_MODEL_DEFAULT` | LLM-модель агентов по умолчанию (ORCH-41); дефолт `claude-opus-4-8` |
| `ORCH_AGENT_MODEL_<AGENT>` | per-agent модель (ANALYST/ARCHITECT/DEVELOPER/REVIEWER/TESTER/DEPLOYER); пусто → default |
| `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`); пусто → без флага |
| `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука | | `DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT` | параметры деплой-хука |
**Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`. **Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`.
@@ -82,26 +55,6 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл
## Реестр проектов (`src/projects.py`, ORCH-6) ## Реестр проектов (`src/projects.py`, ORCH-6)
Связывает Plane project id → gitea repo + work-item prefix. Источник: `ORCH_PROJECTS_JSON`, fallback — встроенный дефолт. Прод видит: `enduro-trails` (ET), `orchestrator` (ORCH). Staging видит ТОЛЬКО `orchestrator-sandbox` (SANDBOX) — изоляция. Связывает Plane project id → gitea repo + work-item prefix. Источник: `ORCH_PROJECTS_JSON`, fallback — встроенный дефолт. Прод видит: `enduro-trails` (ET), `orchestrator` (ORCH). Staging видит ТОЛЬКО `orchestrator-sandbox` (SANDBOX) — изоляция.
## Модель и effort агентов (`src/config.py` + `src/agents/launcher.py`, ORCH-41)
Модель LLM и режим работы (`--effort`) каждого агента **конфигурируемы** — глобально per-agent (env) и per-project (через `ORCH_PROJECTS_JSON`).
**Приоритет резолвинга** (`resolve_agent_model` / `resolve_agent_effort`):
1. per-project override — `agent_models` / `agent_efforts` в записи `ORCH_PROJECTS_JSON`;
2. per-agent env — `ORCH_AGENT_MODEL_<AGENT>` / `ORCH_AGENT_EFFORT_<AGENT>` (если непусто);
3. глобальный дефолт — `ORCH_AGENT_MODEL_DEFAULT` (`claude-opus-4-8`) / `ORCH_AGENT_EFFORT_DEFAULT` (`high`);
4. пусто → флаг не передаётся, действует дефолт CLI.
**Значения effort:** `low` < `medium` < `high` < `xhigh` < `max` — рычаг «качество vs стоимость/время». Дефолтная раскладка: думающие агенты (analyst/architect/developer/reviewer) → `high`, механические (tester/deployer) → `medium`. Невалидное значение → лог-warning, флаг опускается.
**Per-project override в `ORCH_PROJECTS_JSON`** (поля `agent_models` / `agent_efforts` опциональны, старые записи работают):
```json
{"plane_project_id":"...","repo":"orchestrator","work_item_prefix":"ORCH",
"agent_models":{"developer":"claude-opus-4-8","reviewer":"claude-sonnet-4-6"},
"agent_efforts":{"developer":"xhigh","tester":"low"}}
```
> ⚠️ Бюджет (ORCH-38): `claude-opus-4-8` дефолт в коде; реальное переключение прод-env делается отдельно после согласования.
## ⚠️ Self-hosting — оркестратор дорабатывает САМ СЕБЯ ## ⚠️ Self-hosting — оркестратор дорабатывает САМ СЕБЯ
**Факт:** прод-инстанс `orchestrator` (8500) — ОДИН на ВСЕ прод-проекты (enduro-trails + orchestrator), с ОБЩЕЙ БД `./data/orchestrator.db` и общей очередью задач (ORCH-1). **Факт:** прод-инстанс `orchestrator` (8500) — ОДИН на ВСЕ прод-проекты (enduro-trails + orchestrator), с ОБЩЕЙ БД `./data/orchestrator.db` и общей очередью задач (ORCH-1).

View File

@@ -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 ```bash
docker exec orchestrator-staging \ docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \ 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`) ## Режимы (`--mode`)

View File

@@ -1,7 +0,0 @@
# Business Request: Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве
Work Item ID: ORCH-017
## Description
TBD

View File

@@ -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 вручную и не ища комментарий.

View File

@@ -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)` (≈ строки 547566) — единственная точка отправки пингующего уведомления об апруве 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>`), строки ≈483503 — переиспользовать тот же формат. |
| `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) перед прод-деплоем орка.

View File

@@ -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 проверяются для каждой такой точки.

View File

@@ -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]

View File

@@ -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`).
Это конфиг-параметр, а не блокер архитектуры.

View File

@@ -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).

View File

@@ -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 до прод-деплоя.

View File

@@ -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.

View File

@@ -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**.

View File

@@ -1,7 +0,0 @@
# Business Request: Агенты пишут файлы под root в смонтированный хост-репо: ломает git/ребилд
Work Item ID: ORCH-040
## Description
TBD

View File

@@ -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`.
### Диагноз (живая разведка 0506.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.

View File

@@ -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` — выбор варианта + обоснование (мины 13, 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).

View File

@@ -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/конвейер
падает; либо предусловия нигде не задокументированы.

View File

@@ -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

View File

@@ -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`.
Разведкой (0506.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/схема БД — без изменений.
```

View File

@@ -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 / облачные сервисы — нет (принципы архитектуры).

View File

@@ -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 → низкая поверхность регресса.

View File

@@ -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 выполнено с запасом.

View File

@@ -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**.

View File

@@ -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).

View File

@@ -1,7 +0,0 @@
# Business Request: Telegram live-tracker: режим bump (карточка падает вниз при обновлении)
Work Item ID: ORCH-042
## Description
TBD

View File

@@ -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>

View File

@@ -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>

View File

@@ -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>

View File

@@ -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>

View File

@@ -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`.

View File

@@ -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 нет.

View File

@@ -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» выполнено.

View File

@@ -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.

View File

@@ -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).

View File

@@ -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
============================================================
```

View File

@@ -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-хуку. Прод-инстанс не затронут.

View File

@@ -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.

View File

@@ -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

View File

@@ -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 не изменилось.

View File

@@ -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`)
Текущее (~стр. 418424):
```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`)
Текущее (~стр. 454459):
```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).

View File

@@ -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 отсутствуют.

View File

@@ -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

View File

@@ -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`.

View File

@@ -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` НЕ ставится; возврат в Анализ не требуется — ТЗ
реализуемо без нарушения принципов.

View File

@@ -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 не тронуты (§46).
**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 — это страховка следующих
стадий, не блокер ревью.

View File

@@ -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 перед прод-деплоем.

View File

@@ -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
```

View File

@@ -1,7 +0,0 @@
# Business Request: check_tests_passed: gate must read result: field from test report
Work Item ID: ORCH-047
## Description
TBD

View File

@@ -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`, строки 5156 и 7880) предписывает эмитить машиночитаемое поле **`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 заведён.

View File

@@ -1,68 +0,0 @@
# ТЗ — ORCH-047: `_parse_tests_verdict` читает `result:` наравне с `verdict:`/`status:`
## 1. Задействованные модули `src/`
| Файл | Что меняется |
|------|--------------|
| `src/qg/checks.py` | Функция `_parse_tests_verdict` (стр. ~223265). Добавить чтение поля `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) не перезапускать в рамках разработки/тестинга.

View File

@@ -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:** любой упавший тест.

View File

@@ -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

View File

@@ -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`, строки 5156, 7880) предписывает тестеру
эмитить машиночитаемое поле **`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.

View File

@@ -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). |

View File

@@ -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...» (стр. 263264); объединённая строка `fields = "{verdict}
{status} {result}"` (стр. 267); negative-токен проверяется ПЕРВЫМ и авторитетен
(стр. 268270); positive (стр. 271273); fallback на нераспознанные (стр. 275279).
Наборы `_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. ✅

View File

@@ -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.

View File

@@ -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
```

View File

@@ -1,7 +0,0 @@
# Business Request: staging B6 check reads registry from host worktree, not staging container
Work Item ID: ORCH-048
## Description
TBD

View File

@@ -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. **Изоляция реестра исправна.**
- Все остальные чеки (A1A3, B4, B5, блок C E2E) обращаются к работающему staging-инстансу по HTTP и **зелёные**.
- **B6 — единственный чек, который не ходит по HTTP, а импортирует Python-код локально.** В блоке B6 (строки ~263284) выполняется:
```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-чеки B1B5 и блок 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 хак).
Предпочтение бизнес-запроса: минимально инвазивный вариант, не трогающий прод-логику.

View File

@@ -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 (~строки 263284) | **Изменяется** — переписать механику получения реестра в 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а, отдельно обоснованный риск).
- Блоки A1A3, 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.

View File

@@ -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:**
- Блоки A1A3, 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 присутствуют и согласованы с кодом |

View File

@@ -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

View File

@@ -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, ~строки 263284) — страховка изоляции 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`.
- **НЕ** менять блоки A1A3, 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` — обоснование отказа от варианта (б).

View File

@@ -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:** реализация дословно следует пунктам 15 решения и 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*`, блоки A1A3/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 отсутствуют.

View File

@@ -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.

View File

@@ -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.

View File

@@ -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.

View File

@@ -1,13 +0,0 @@
[pytest]
# ORCH-39: make the async webhook/state tests (test_orch10_states.py) actually
# run in every environment. Without pytest-asyncio + asyncio_mode=auto these
# @pytest.mark.asyncio tests were silently SKIPPED, so a broken async path
# could pass CI. asyncio_mode=auto runs `async def test_*` natively.
asyncio_mode = auto
# Fail loudly on unknown markers so a typo'd @pytest.mark.* can't silently
# disable a test.
markers =
asyncio: mark a coroutine test to be run by pytest-asyncio.
testpaths = tests

View File

@@ -3,4 +3,3 @@ uvicorn[standard]==0.30.0
pydantic-settings==2.5.0 pydantic-settings==2.5.0
httpx==0.27.0 httpx==0.27.0
pytest==8.3.3 pytest==8.3.3
pytest-asyncio==0.23.8

View File

@@ -8,14 +8,8 @@ Checks:
Block C — E2E (create task in SANDBOX → trigger pipeline via /webhook/plane Block C — E2E (create task in SANDBOX → trigger pipeline via /webhook/plane
→ verify branch + job enqueued → CLEANUP in finally) → verify branch + job enqueued → CLEANUP in finally)
Usage — CANONICAL: run INSIDE the orchestrator-staging container (ORCH-048, ADR-001) Usage (inside the container or with correct env set):
so B6 reads the registry from the running instance's own env (.env.staging): python3 scripts/staging_check.py [--base-url http://localhost:8501] [--mode stub|full-real]
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 [--mode stub|full-real]
Running from the host leaves ORCH_PROJECTS_JSON unset → B6 falls back to the
default (ET+ORCH) registry → false FAIL. See docs/operations/STAGING_CHECK.md.
Exit code: 0 = all PASS, non-zero = at least one FAIL. Exit code: 0 = all PASS, non-zero = at least one FAIL.
@@ -220,59 +214,6 @@ SANDBOX_PROJECT_ID = "8c5a3025-4f9d-4190-b79f-fa06276bb27e"
PROD_ET_PROJECT_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c" PROD_ET_PROJECT_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
PROD_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a" PROD_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
B6_LABEL = "B6 Registry: sandbox present, prod ET/ORCH absent"
def _evaluate_b6(known: set[str]) -> tuple[bool, str]:
"""Pure verdict logic for the B6 registry-isolation check (ORCH-048).
PASS ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known (TR-2).
``detail`` keeps the human-readable ``sandbox=…, prod-ET=…, prod-ORCH=…``
format (TR-3). Isolated from any I/O so both outcomes are unit-testable
without a live staging instance or docker (02-trz §9, ADR-001).
"""
sandbox_present = SANDBOX_PROJECT_ID in known
et_absent = PROD_ET_PROJECT_ID not in known
orch_absent = PROD_ORCH_PROJECT_ID not in known
passed = sandbox_present and et_absent and orch_absent
detail = (
f"sandbox={'YES' if sandbox_present else 'NO'}, "
f"prod-ET={'NO(good)' if et_absent else 'YES(BAD!)'}, "
f"prod-ORCH={'NO(good)' if orch_absent else 'YES(BAD!)'}"
)
return passed, detail
def _known_project_ids_from_registry() -> set[str]:
"""Registry of the *running staging instance* — its own process-env (ORCH-048).
The suite is canonically run INSIDE ``orchestrator-staging`` via
``docker exec`` (ADR-001), so ``src.projects`` resolves through the
container's ``PYTHONPATH=/app`` to ``/app/src/projects.py`` and reads
``ORCH_PROJECTS_JSON`` from ``.env.staging``. This reflects exactly the
registry the live instance serves webhooks with — no host-path hack, no HTTP
bootstrap dependency.
"""
from src.projects import known_plane_project_ids
return known_plane_project_ids()
def _run_b6(results: Results) -> None:
"""Run the B6 registry-isolation check and record its verdict.
Builds the known-id set from the running instance's registry and applies
``_evaluate_b6``. Any failure to obtain the registry yields a deterministic
FAIL with a clear detail (TR-4) — never an unhandled exception and never a
false PASS.
"""
try:
known = _known_project_ids_from_registry()
except Exception as e:
results.add(B6_LABEL, False, f"registry source unavailable: {e}")
return
passed, detail = _evaluate_b6(known)
results.add(B6_LABEL, passed, detail)
def block_b(results: Results): def block_b(results: Results):
print(f"\n{_BOLD}[Block B] ACCESS{_RESET}") print(f"\n{_BOLD}[Block B] ACCESS{_RESET}")
@@ -319,11 +260,28 @@ def block_b(results: Results):
except Exception as e: except Exception as e:
results.add("B5 Gitea: orchestrator-sandbox accessible, push=true", False, str(e)) results.add("B5 Gitea: orchestrator-sandbox accessible, push=true", False, str(e))
# B6 — Registry: sandbox in known IDs, prod ET/ORCH NOT in known IDs (ORCH-048). # B6 — Registry: sandbox in known IDs, prod ET/ORCH NOT in known IDs
# Reads the registry of the running staging instance from its own process-env try:
# (canonical: docker exec inside orchestrator-staging — ADR-001). No host-path # Import from inside the container (script runs in /repos/orchestrator context)
# hack; deterministic FAIL if the registry source is unavailable (TR-4). sys.path.insert(0, "/repos/orchestrator")
_run_b6(results) # Force reload to pick up container env
import importlib
if "src.projects" in sys.modules:
importlib.reload(sys.modules["src.projects"])
from src.projects import known_plane_project_ids
known = known_plane_project_ids()
sandbox_present = SANDBOX_PROJECT_ID in known
et_absent = PROD_ET_PROJECT_ID not in known
orch_absent = PROD_ORCH_PROJECT_ID not in known
ok = sandbox_present and et_absent and orch_absent
detail = (
f"sandbox={'YES' if sandbox_present else 'NO'}, "
f"prod-ET={'NO(good)' if et_absent else 'YES(BAD!)'}, "
f"prod-ORCH={'NO(good)' if orch_absent else 'YES(BAD!)'}"
)
results.add("B6 Registry: sandbox present, prod ET/ORCH absent", ok, detail)
except Exception as e:
results.add("B6 Registry: sandbox present, prod ET/ORCH absent", False, str(e))
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------

View File

@@ -15,82 +15,6 @@ from ..plane_sync import notify_stage_change as plane_notify_stage, add_comment
logger = logging.getLogger("orchestrator.launcher") logger = logging.getLogger("orchestrator.launcher")
# ORCH-41: valid --effort values accepted by the Claude CLI. An effort that is
# not in this set is treated as misconfiguration: logged and dropped (no flag),
# never passed through to the CLI.
VALID_EFFORTS = frozenset({"low", "medium", "high", "xhigh", "max"})
def _resolve_agent_attr(agent, project_id, project_map_attr, env_attr_prefix,
default_attr):
"""ORCH-41 shared resolver with priority:
1. ProjectConfig.<project_map_attr>[agent] (per-project override)
2. settings.<env_attr_prefix><agent> (per-agent env, if non-empty)
3. settings.<default_attr> (global default)
4. "" (no flag -> CLI default)
project_id is the Plane project uuid. It is resolved to a ProjectConfig via
the registry; an unknown / empty id simply skips level 1. A missing per-agent
settings attribute (e.g. unknown agent name) skips level 2.
"""
# Level 1: per-project override.
if project_id:
from ..projects import get_project_by_plane_id
proj = get_project_by_plane_id(project_id)
if proj is not None:
override = getattr(proj, project_map_attr, {}).get(agent)
if override:
return override
# Level 2: per-agent env (settings.<prefix><agent>), if defined & non-empty.
per_agent = getattr(settings, f"{env_attr_prefix}{agent}", "")
if per_agent:
return per_agent
# Level 3: global default.
default = getattr(settings, default_attr, "")
if default:
return default
# Level 4: nothing -> CLI default.
return ""
def resolve_agent_model(agent: str, project_id: str = None) -> str:
"""ORCH-41: resolve the LLM model for an agent (optionally per-project).
Returns "" when no model is configured at any level -> caller omits --model
and the CLI default applies. See _resolve_agent_attr for the priority order.
"""
return _resolve_agent_attr(
agent, project_id,
project_map_attr="agent_models",
env_attr_prefix="agent_model_",
default_attr="agent_model_default",
)
def resolve_agent_effort(agent: str, project_id: str = None) -> str:
"""ORCH-41: resolve the --effort level for an agent (optionally per-project).
Same priority as resolve_agent_model. The resolved value is validated against
VALID_EFFORTS; an invalid value is logged and dropped (returns "") so a typo
in env/projects_json can never pass a bad flag to the CLI.
"""
value = _resolve_agent_attr(
agent, project_id,
project_map_attr="agent_efforts",
env_attr_prefix="agent_effort_",
default_attr="agent_effort_default",
)
if value and value not in VALID_EFFORTS:
logger.warning(
f"Invalid effort '{value}' for agent '{agent}' "
f"(allowed: {sorted(VALID_EFFORTS)}); omitting --effort"
)
return ""
return value
def prune_run_logs(runs_dir, keep_days=30, keep_max=500, active_paths=None): def prune_run_logs(runs_dir, keep_days=30, keep_max=500, active_paths=None):
"""L-2: best-effort rotation of per-run logs (<runs_dir>/*.log). """L-2: best-effort rotation of per-run logs (<runs_dir>/*.log).
@@ -161,6 +85,7 @@ class AgentLauncher:
"system_prompt": ".openclaw/agents/architect.md", "system_prompt": ".openclaw/agents/architect.md",
"task_file": ".task-arch.md", "task_file": ".task-arch.md",
"allowed_tools": "Read,Write,Edit,Bash", "allowed_tools": "Read,Write,Edit,Bash",
"model": "opus",
}, },
"developer": { "developer": {
"system_prompt": ".openclaw/agents/developer.md", "system_prompt": ".openclaw/agents/developer.md",
@@ -171,6 +96,7 @@ class AgentLauncher:
"system_prompt": ".openclaw/agents/reviewer.md", "system_prompt": ".openclaw/agents/reviewer.md",
"task_file": ".task-review.md", "task_file": ".task-review.md",
"allowed_tools": "Read,Write,Edit,Bash", "allowed_tools": "Read,Write,Edit,Bash",
"model": "opus",
}, },
"tester": { "tester": {
"system_prompt": ".openclaw/agents/tester.md", "system_prompt": ".openclaw/agents/tester.md",
@@ -245,12 +171,6 @@ class AgentLauncher:
_br_row = get_db().execute("SELECT branch FROM tasks WHERE id=?", (task_id,)).fetchone() if task_id else None _br_row = get_db().execute("SELECT branch FROM tasks WHERE id=?", (task_id,)).fetchone() if task_id else None
agent_branch = _br_row[0] if _br_row else "main" agent_branch = _br_row[0] if _br_row else "main"
# ORCH-41: resolve the Plane project uuid for this repo so per-project
# model/effort overrides apply. Unknown repo -> None (env/default only).
from ..projects import get_project_by_repo
_proj = get_project_by_repo(repo)
project_id = _proj.plane_project_id if _proj else None
# Ensure the per-branch worktree exists and is on the right branch. # Ensure the per-branch worktree exists and is on the right branch.
work_path = ensure_worktree(repo, agent_branch) work_path = ensure_worktree(repo, agent_branch)
@@ -284,14 +204,8 @@ class AgentLauncher:
system_prompt = config["system_prompt"] system_prompt = config["system_prompt"]
allowed_tools = config["allowed_tools"] allowed_tools = config["allowed_tools"]
# ORCH-41: model + effort + optional fallback are resolved from config model = config.get("model", "")
# (project-override > per-agent env > default), not hardcoded in AGENT_CONFIGS.
model = resolve_agent_model(agent, project_id)
effort = resolve_agent_effort(agent, project_id)
model_flag = f"--model {model} " if model else "" model_flag = f"--model {model} " if model else ""
effort_flag = f"--effort {effort} " if effort else ""
fb = settings.agent_fallback_model
fb_flag = f"--fallback-model {fb} " if fb else ""
# No git fetch/checkout here: ensure_worktree() already put the worktree on # No git fetch/checkout here: ensure_worktree() already put the worktree on
# the right branch. The agent simply runs inside its isolated work_path. # the right branch. The agent simply runs inside its isolated work_path.
@@ -304,7 +218,7 @@ class AgentLauncher:
f'cd {work_path} && ' f'cd {work_path} && '
f'{self.CLAUDE_BIN} --print ' f'{self.CLAUDE_BIN} --print '
f'--output-format json ' f'--output-format json '
f'{model_flag}{effort_flag}{fb_flag}' f'{model_flag}'
f'"$(cat {task_file})" ' f'"$(cat {task_file})" '
f'--system-prompt "$(cat {system_prompt})" ' f'--system-prompt "$(cat {system_prompt})" '
f'--allowedTools {allowed_tools}' f'--allowedTools {allowed_tools}'

View File

@@ -4,11 +4,6 @@ from pydantic_settings import BaseSettings
class Settings(BaseSettings): class Settings(BaseSettings):
# Plane # Plane
plane_api_url: str = "http://localhost:8091" plane_api_url: str = "http://localhost:8091"
# ORCH-017: external (browser) web URL of Plane for clickable issue links in
# notifications, e.g. https://plane.example.org. Falls back to plane_api_url,
# but a loopback fallback (localhost/127.0.0.1) is treated as "no web URL" and
# the Plane link is omitted (see notifications._build_plane_issue_link).
plane_web_url: str = ""
plane_api_token: str = "" plane_api_token: str = ""
plane_workspace_slug: str = "" plane_workspace_slug: str = ""
plane_webhook_secret: str = "" plane_webhook_secret: str = ""
@@ -83,34 +78,6 @@ class Settings(BaseSettings):
agent_kill_grace_seconds: int = 20 agent_kill_grace_seconds: int = 20
agent_timeout_overrides_json: str = "" agent_timeout_overrides_json: str = ""
# ORCH-41: per-agent LLM model. Empty -> agent_model_default. Resolution order:
# project-override (projects_json agent_models) > ORCH_AGENT_MODEL_<AGENT> >
# agent_model_default > CLI default (no --model flag). Default is 4-8 because
# 4-7 == 4-8 in price (Slava 05.06); do NOT hardcode the version anywhere else.
agent_model_default: str = "claude-opus-4-8"
agent_model_analyst: str = ""
agent_model_architect: str = ""
agent_model_developer: str = ""
agent_model_reviewer: str = ""
agent_model_tester: str = ""
agent_model_deployer: str = ""
# ORCH-41: per-agent effort / reasoning level: low|medium|high|xhigh|max.
# Empty -> agent_effort_default. Same resolution order as model. Default split:
# thinking agents (analyst/architect/developer/reviewer) -> high; mechanical
# agents (tester/deployer) -> medium.
agent_effort_default: str = "high"
agent_effort_analyst: str = "high"
agent_effort_architect: str = "high"
agent_effort_developer: str = "high"
agent_effort_reviewer: str = "high"
agent_effort_tester: str = "medium"
agent_effort_deployer: str = "medium"
# ORCH-41: optional per-agent fallback model used when the primary is
# overloaded (--fallback-model, works with --print). Empty -> no flag.
agent_fallback_model: str = ""
# L-2: run-log rotation. Old per-run logs in <data>/runs/*.log are pruned at # L-2: run-log rotation. Old per-run logs in <data>/runs/*.log are pruned at
# app startup (best-effort). A *.log is removed if it is older than # app startup (best-effort). A *.log is removed if it is older than
# log_keep_days OR not within the log_keep_max most-recent logs (whichever # log_keep_days OR not within the log_keep_max most-recent logs (whichever
@@ -121,27 +88,10 @@ class Settings(BaseSettings):
log_keep_max: int = 500 log_keep_max: int = 500
# ORCH-045: quality-gate CI poll/retry. check_ci_green polls the Gitea
# combined commit status up to ci_poll_max_attempts times, sleeping
# ci_poll_interval_s between attempts, to ride out a transient pending
# state right after the developer push (race fix, see ORCH-017).
# ci_poll_max_attempts -> max status polls (env ORCH_CI_POLL_MAX_ATTEMPTS)
# ci_poll_interval_s -> seconds between polls (env ORCH_CI_POLL_INTERVAL_S)
ci_poll_max_attempts: int = 12
ci_poll_interval_s: int = 10
# Telegram notifications # Telegram notifications
telegram_bot_token: str = "" telegram_bot_token: str = ""
telegram_chat_id: str = "" telegram_chat_id: str = ""
# ORCH-042: режим live-трекера задачи.
# edit -> карточка редактируется на месте (editMessageText), ДЕФОЛТ (как было).
# bump -> при обновлении старое сообщение удаляется и карточка отправляется
# заново вниз чата (deleteMessage + sendMessage + repoint message_id),
# тихо (disable_notification). Одна карточка на задачу в обоих режимах.
# Неизвестное/пустое значение трактуется как edit (см. notifications).
tracker_mode: str = "edit"
class Config: class Config:
env_prefix = "ORCH_" env_prefix = "ORCH_"
env_file = ".env" env_file = ".env"

View File

@@ -68,62 +68,6 @@ def send_telegram(text: str, disable_notification: bool = False):
return None return None
# Telegram error descriptions that mean a deleteMessage target is already gone /
# can't be deleted (>48h, already deleted, invalid id). Treated as "no longer our
# problem" -> the caller proceeds to send a fresh card. NOT a transient failure.
_DELETE_GONE_MARKERS = (
"message to delete not found",
"message can't be deleted",
"message_id_invalid",
)
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.
"""
s = _get_settings()
if not s.telegram_bot_token or not s.telegram_chat_id:
# No creds -> nothing was deleted; mirror the other helpers' no-op path.
return False
try:
url = f"https://api.telegram.org/bot{s.telegram_bot_token}/deleteMessage"
resp = httpx.post(
url,
json={
"chat_id": s.telegram_chat_id,
"message_id": message_id,
},
timeout=5,
)
data = resp.json()
if data.get("ok"):
return True
# ok:false -> classify. "Already gone / can't delete" is an expected,
# non-transient outcome (>48h, already deleted) -> the old message is no
# longer there, caller should still send a fresh card.
desc = str(data.get("description") or "").lower()
if any(m in desc for m in _DELETE_GONE_MARKERS):
logger.debug(
f"delete_telegram(mid={message_id}): already gone ({desc!r})"
)
return True
# Unknown 400 / 5xx -> transient; the old message may still be alive.
logger.warning(
f"delete_telegram(mid={message_id}): delete failed ({desc!r})"
)
return False
except Exception as e:
# Network / timeout -> transient; old message may still be alive.
logger.warning(f"delete_telegram(mid={message_id}): transient error: {e}")
return False
# edit_telegram outcome codes -> let update_task_tracker decide what to do: # edit_telegram outcome codes -> let update_task_tracker decide what to do:
# "ok" edit applied -> nothing else to do # "ok" edit applied -> nothing else to do
# "not_modified" Telegram says text is identical (400 "message is not # "not_modified" Telegram says text is identical (400 "message is not
@@ -222,23 +166,19 @@ def _get_work_item_id(task_id: int) -> str:
# the agent whose agent_runs rows describe that stage's work. "Ревью БРД" is NOT # the agent whose agent_runs rows describe that stage's work. "Ревью БРД" is NOT
# an agent stage — it is the human approve gate rendered between Analysis and # an agent stage — it is the human approve gate rendered between Analysis and
# Architecture from the task's brd_review_* timestamps. # Architecture from the task's brd_review_* timestamps.
# ORCH-042 (BR-11): display-labels are Russian. Stage KEYS (analysis, …) and
# agent names (analyst, …) are NOT touched — they are wired to
# _STAGE_ACTIVE_AGENT, last_done and the DB. Only the 2nd tuple element changed.
_TRACKER_STAGES = [ _TRACKER_STAGES = [
("analysis", "Анализ", "analyst"), # Анализ ("analysis", "Analysis", "analyst"),
("architecture", "Архитектура", "architect"), # Архитектура ("architecture", "Architecture", "architect"),
("development", "Разработка", "developer"), # Разработка ("development", "Development", "developer"),
("review", "Код ревью", "reviewer"), # Код ревью ("review", "Review", "reviewer"),
("testing", "Тестирование", "tester"), # Тестирование ("testing", "Testing", "tester"),
("deploy", "Внедрение", "deployer"), # Внедрение ("deploy", "Deploy", "deployer"),
] ]
# Map a pipeline stage -> the agent that is RUNNING while the task sits in it. # Map a pipeline stage -> the agent that is RUNNING while the task sits in it.
# (development is entered after architecture finishes, etc.) Used to render the # (development is entered after architecture finishes, etc.) Used to render the
# "🔄 <Stage> … идёт" line for the currently-active stage. # "🔄 <Stage> … идёт" line for the currently-active stage.
# ORCH-042 (BR-9): "Подтверждение BRD" (was "Ревью БРД"). _BRD_LABEL = "\u0420\u0435\u0432\u044c\u044e \u0411\u0420\u0414" # "Ревью БРД"
_BRD_LABEL = "Подтверждение BRD"
_STAGE_ACTIVE_AGENT = { _STAGE_ACTIVE_AGENT = {
"analysis": "analyst", "analysis": "analyst",
@@ -292,8 +232,7 @@ def render_task_tracker(task_id: int) -> str:
the BRD-review timestamps, then renders: the BRD-review timestamps, then renders:
- one '✅ <Stage> <dur> · <in>↓/<out>↑ · <cost> · <model>' line per finished - one '✅ <Stage> <dur> · <in>↓/<out>↑ · <cost> · <model>' line per finished
stage (latest run per stage), stage (latest run per stage),
- the '✅/⏸️ Подтверждение BRD <dur> · твоё время[ ⏳]' line between - the '⏸️ Ревью БРД <dur> · твоё время[ ⏳]' line between Analysis/Architecture,
Analysis/Architecture (✅ once the approve-gate passed, ⏸️+⏳ while waiting),
- a '🔄 <Stage> … идёт' line for the active (in-progress) stage, - a '🔄 <Stage> … идёт' line for the active (in-progress) stage,
- the '💰 <in>↓ / <out>↑ · <cost>' totals, - the '💰 <in>↓ / <out>↑ · <cost>' totals,
- on done: '⏱️ Всего .. · агенты .. · твоё ..' and a '🔗 PR / 📦' line. - on done: '⏱️ Всего .. · агенты .. · твоё ..' and a '🔗 PR / 📦' line.
@@ -426,11 +365,9 @@ def render_task_tracker(task_id: int) -> str:
if stage_key == "analysis" and brd_started: if stage_key == "analysis" and brd_started:
brd_label = f"{_BRD_LABEL:<13}" brd_label = f"{_BRD_LABEL:<13}"
if review_seconds is not None: if review_seconds is not None:
# ORCH-042 (BR-10): approve-gate passed -> \u2705 (was \u23f8\ufe0f). The
# still-waiting branch below keeps \u23f8\ufe0f + \u23f3 unchanged.
dur = _fmt_minutes(review_seconds) dur = _fmt_minutes(review_seconds)
lines.append( lines.append(
f"\u2705 {brd_label} {dur} \u00b7 \u0442\u0432\u043e\u0451 \u0432\u0440\u0435\u043c\u044f" f"\u23f8\ufe0f {brd_label} {dur} \u00b7 \u0442\u0432\u043e\u0451 \u0432\u0440\u0435\u043c\u044f"
) )
else: else:
# Still waiting on the human (ended not stamped yet). # Still waiting on the human (ended not stamped yet).
@@ -469,7 +406,7 @@ def render_task_tracker(task_id: int) -> str:
def _done_link(task_id: int, work_item_id) -> str | None: def _done_link(task_id: int, work_item_id) -> str | None:
"""Build the final '🔗 PR #n · 📦 Внедрено' line. Never raises -> None.""" """Build the final '🔗 PR #n · 📦 deployed' line. Never raises -> None."""
try: try:
from .config import settings from .config import settings
from .db import get_db from .db import get_db
@@ -499,7 +436,7 @@ def _done_link(task_id: int, work_item_id) -> str | None:
parts = [] parts = []
if pr_part: if pr_part:
parts.append(pr_part) parts.append(pr_part)
parts.append("\U0001f4e6 Внедрено") # ORCH-042 (BR-12): was "deployed" parts.append("\U0001f4e6 deployed")
return " \u00b7 ".join(parts) return " \u00b7 ".join(parts)
except Exception: except Exception:
return None return None
@@ -508,49 +445,19 @@ def _done_link(task_id: int, work_item_id) -> str | None:
def update_task_tracker(task_id: int): def update_task_tracker(task_id: int):
"""Render + push the live tracker for a task. Never raises. """Render + push the live tracker for a task. Never raises.
Two modes, selected by Settings.tracker_mode (env ORCH_TRACKER_MODE), First call (no stored tracker_message_id): sendMessage (silent) and store the
resolved case-insensitively here; anything other than "bump" -> "edit" returned message_id. Subsequent calls: editMessageText the stored message.
(ORCH-042). Both keep the "one card per task" invariant. A NEW message is sent ONLY when the original is truly gone (deleted / too old
/ invalid id). On "not modified" (text unchanged) or transient failures
edit (DEFAULT): (network / timeout / 5xx / unknown 400) we do NOT send a new message — that
First call (no stored tracker_message_id): sendMessage (silent) and store is exactly what produced duplicate trackers and orphaned (lagging) messages.
the returned message_id. Subsequent calls: editMessageText the stored
message. A NEW message is sent ONLY when the original is truly gone
(deleted / too old / invalid id). On "not modified" (text unchanged) or
transient failures (network / timeout / 5xx / unknown 400) we do NOT send
a new message — that is exactly what produced duplicate trackers and
orphaned (lagging) messages.
bump (ORCH-042):
The card is re-created at the BOTTOM of the chat on every update:
best-effort delete_telegram(old_id) (its result NEVER blocks the send),
then sendMessage (silent), then re-point tracker_message_id to the new id
— but ONLY on a successful send (new_mid is not None), so a transient send
failure never wipes the pointer to None. At most ONE new message is sent
per call -> no duplicates within a call.
The tracker is always sent with disable_notification so it never pings — The tracker is always sent with disable_notification so it never pings —
only the dedicated alert helpers ping. only the dedicated alert helpers ping.
""" """
try: try:
from .db import get_tracker_message_id, set_tracker_message_id from .db import get_tracker_message_id, set_tracker_message_id
text = render_task_tracker(task_id) text = render_task_tracker(task_id)
mode = (_get_settings().tracker_mode or "edit").strip().lower()
mid = get_tracker_message_id(task_id) mid = get_tracker_message_id(task_id)
if mode == "bump":
# bump: one card, always at the bottom (delete + send + repoint).
if mid is not None:
# best-effort; result does NOT gate the send (BR-6).
delete_telegram(mid)
new_mid = send_telegram(text, disable_notification=True)
if new_mid is not None:
set_tracker_message_id(task_id, new_mid)
# send returned None (no creds / transient) -> leave mid untouched;
# no duplicate within this call, redraws on the next transition.
return
# mode == "edit" (DEFAULT): existing behaviour, unchanged.
if mid is not None: if mid is not None:
result = edit_telegram(mid, text) result = edit_telegram(mid, text)
if result in (EDIT_OK, EDIT_NOT_MODIFIED): if result in (EDIT_OK, EDIT_NOT_MODIFIED):
@@ -637,105 +544,6 @@ def notify_qg_failure(task_id: int, stage: str, check: str, reason: str):
logger.warning(f"\u26a0\ufe0f {work_item_id}: QG {check} \u2014 failed: {reason}") logger.warning(f"\u26a0\ufe0f {work_item_id}: QG {check} \u2014 failed: {reason}")
# ORCH-017: hosts that are not clickable off the deploy box. A Plane web-base
# resolving to one of these (the plane_api_url loopback default) means "no usable
# browser URL" -> the Plane link is omitted rather than emitted broken (ADR-001 Р-3).
_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "0.0.0.0", "::1"})
def _is_loopback_base(url: str) -> bool:
"""True if the URL's host is a loopback/local address (not clickable off-host).
Empty/garbage URLs count as loopback (i.e. unusable) so callers omit the link.
"""
if not url:
return True
try:
from urllib.parse import urlparse
host = (urlparse(url).hostname or "").lower()
return (not host) or host in _LOOPBACK_HOSTS
except Exception:
return True
def _get_task_link_fields(task_id: int):
"""ORCH-017: read (repo, branch, plane_issue_id) for a task. Never raises.
Returns (None, None, None) on any error / missing row so link building can
degrade gracefully (AC-6).
"""
try:
from .db import get_db
conn = get_db()
row = conn.execute(
"SELECT repo, branch, plane_issue_id FROM tasks WHERE id=?", (task_id,)
).fetchone()
conn.close()
if not row:
return None, None, None
return row["repo"], row["branch"], row["plane_issue_id"]
except Exception as e:
logger.warning(f"_get_task_link_fields({task_id}) failed: {e}")
return None, None, None
def _build_brd_link(repo, branch, work_item_id) -> str | None:
"""ORCH-017: '<a>' to 01-brd.md in Gitea branch-view, or None if data missing.
Mirrors the canonical branch-view pattern in src/usage.py: base =
gitea_public_url or gitea_url, owner = gitea_owner (AC-1/AC-3). The href is
html.escaped as defence-in-depth even though parts come from trusted
config/DB (AC-7).
"""
s = _get_settings()
base = (
getattr(s, "gitea_public_url", "") or getattr(s, "gitea_url", "")
).rstrip("/")
owner = getattr(s, "gitea_owner", "")
if not (base and owner and repo and branch and work_item_id):
return None
url = (
f"{base}/{owner}/{repo}/src/branch/{branch}"
f"/docs/work-items/{work_item_id}/01-brd.md"
)
return (
f'<a href="{html.escape(url, quote=True)}">'
f"\U0001f4c4 Открыть BRD</a>"
)
def _build_plane_issue_link(repo, plane_issue_id) -> str | None:
"""ORCH-017: '<a>' to the Plane issue browser page, or None if unusable.
Full path per ADR-001 Р-2:
``{web_base}/{workspace_slug}/projects/{project_id}/issues/{issue_id}/``.
web_base = plane_web_url or plane_api_url (AC-3); a loopback base is treated
as "no web URL" and the link is omitted (loopback-guard, AC-2/AC-6).
"""
s = _get_settings()
web_base = (
getattr(s, "plane_web_url", "") or getattr(s, "plane_api_url", "")
).rstrip("/")
workspace = getattr(s, "plane_workspace_slug", "")
if not (web_base and workspace and plane_issue_id) or _is_loopback_base(web_base):
return None
try:
from .projects import get_project_by_repo
project = get_project_by_repo(repo) if repo else None
except Exception:
project = None
if not project or not getattr(project, "plane_project_id", ""):
return None
url = (
f"{web_base}/{workspace}/projects/{project.plane_project_id}"
f"/issues/{plane_issue_id}/"
)
return (
f'<a href="{html.escape(url, quote=True)}">'
f"✅ Задача в Plane</a>"
)
def notify_approve_requested(task_id: int): def notify_approve_requested(task_id: int):
"""ALERT (separate, notifying): BRD/TZ/AC ready -> flip Plane to Approved. """ALERT (separate, notifying): BRD/TZ/AC ready -> flip Plane to Approved.
@@ -749,27 +557,10 @@ def notify_approve_requested(task_id: int):
except Exception as e: except Exception as e:
logger.warning(f"notify_approve_requested: brd clock start failed: {e}") logger.warning(f"notify_approve_requested: brd clock start failed: {e}")
msg = ( msg = (
f"\U0001f4cb {html.escape(work_item_id)}: BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. " f"\U0001f4cb {work_item_id}: BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. "
f"\u041f\u0435\u0440\u0435\u0432\u0435\u0434\u0438\u0442\u0435 \u0437\u0430\u0434\u0430\u0447\u0443 \u0432 \u0441\u0442\u0430\u0442\u0443\u0441 Approved " f"\u041f\u0435\u0440\u0435\u0432\u0435\u0434\u0438\u0442\u0435 \u0437\u0430\u0434\u0430\u0447\u0443 \u0432 \u0441\u0442\u0430\u0442\u0443\u0441 Approved "
f"\u0432 Plane \u0434\u043b\u044f \u043f\u0440\u043e\u0434\u043e\u043b\u0436\u0435\u043d\u0438\u044f." f"\u0432 Plane \u0434\u043b\u044f \u043f\u0440\u043e\u0434\u043e\u043b\u0436\u0435\u043d\u0438\u044f."
) )
# ORCH-017: embed direct links to the BRD doc (Gitea) and the Plane issue so
# the reviewer can open both straight from the ping. Each link is built
# independently and omitted if its data is missing; building is defensive so
# it can NEVER break the alert (AC-1/AC-2/AC-6). Still exactly one notifying
# message (AC-5); the call to action above is always preserved (AC-4).
try:
repo, branch, plane_issue_id = _get_task_link_fields(task_id)
links = [
link for link in (
_build_brd_link(repo, branch, work_item_id),
_build_plane_issue_link(repo, plane_issue_id),
) if link
]
if links:
msg = msg + "\n\n" + "\n".join(links)
except Exception as e:
logger.warning(f"notify_approve_requested({task_id}): link build failed: {e}")
logger.info(msg) logger.info(msg)
update_task_tracker(task_id) update_task_tracker(task_id)
send_telegram(msg) # separate, notifying send_telegram(msg) # separate, notifying

View File

@@ -17,7 +17,7 @@ registry is used so the system works out of the box.
import json import json
import logging import logging
from dataclasses import dataclass, field from dataclasses import dataclass
from .config import settings from .config import settings
@@ -30,11 +30,6 @@ class ProjectConfig:
repo: str # gitea repo name (== folder under /repos) repo: str # gitea repo name (== folder under /repos)
work_item_prefix: str # ET / ORCH work_item_prefix: str # ET / ORCH
name: str # human-readable label name: str # human-readable label
# ORCH-41: optional per-project agent->model / agent->effort overrides parsed
# from projects_json. frozen dataclass + mutable default -> field(default_factory=dict)
# (a bare {} default raises ValueError). Empty dict = no override (old records work).
agent_models: dict = field(default_factory=dict)
agent_efforts: dict = field(default_factory=dict)
# Built-in default registry (used when ORCH_PROJECTS_JSON is empty/invalid). # Built-in default registry (used when ORCH_PROJECTS_JSON is empty/invalid).
@@ -55,23 +50,6 @@ _DEFAULT_PROJECTS = [
] ]
def _coerce_str_map(value, idx, field_name) -> dict:
"""ORCH-41: coerce an optional projects_json sub-object into a {str: str} dict.
Missing / null -> {} (no override). A non-object value is logged and dropped so
one malformed entry can never brick the whole registry; non-string keys/values
are stringified for safety.
"""
if value is None:
return {}
if not isinstance(value, dict):
logger.error(
f"ORCH_PROJECTS_JSON[{idx}].{field_name} is not an object, ignoring"
)
return {}
return {str(k): str(v) for k, v in value.items()}
def _parse_projects_json(raw: str) -> list[ProjectConfig] | None: def _parse_projects_json(raw: str) -> list[ProjectConfig] | None:
"""Parse ORCH_PROJECTS_JSON. Returns None if empty/invalid (-> use default).""" """Parse ORCH_PROJECTS_JSON. Returns None if empty/invalid (-> use default)."""
if not raw or not raw.strip(): if not raw or not raw.strip():
@@ -97,8 +75,6 @@ def _parse_projects_json(raw: str) -> list[ProjectConfig] | None:
repo=str(item["repo"]), repo=str(item["repo"]),
work_item_prefix=str(item["work_item_prefix"]), work_item_prefix=str(item["work_item_prefix"]),
name=str(item.get("name", item["repo"])), name=str(item.get("name", item["repo"])),
agent_models=_coerce_str_map(item.get("agent_models"), i, "agent_models"),
agent_efforts=_coerce_str_map(item.get("agent_efforts"), i, "agent_efforts"),
) )
) )
except KeyError as e: except KeyError as e:

View File

@@ -1,7 +1,6 @@
"""Quality Gate checks — real implementations using Gitea/Plane API and filesystem.""" """Quality Gate checks — real implementations using Gitea/Plane API and filesystem."""
import os import os
import time
import logging import logging
import subprocess import subprocess
import httpx import httpx
@@ -83,65 +82,23 @@ def check_ci_green(repo: str, branch: str) -> tuple[bool, str]:
""" """
Check if CI status is green for branch via Gitea API. Check if CI status is green for branch via Gitea API.
GET /repos/{owner}/{repo}/commits/{branch}/status GET /repos/{owner}/{repo}/commits/{branch}/status
ORCH-045: polling with retry to fix a race condition. The gate used to do a
single status read right after the developer push; if CI was still ``pending``
for the first 1-3s (real case ORCH-017: polled 17:58:54 -> pending, CI went
green 17:58:55) the gate returned False once and the task stalled silently.
Behaviour now:
* ``success`` -> (True, "CI green") immediately.
* ``failure`` / ``error`` -> (False, "CI state: <state>") immediately
(CI is red, retrying is pointless).
* ``pending`` / unknown -> sleep ``ci_poll_interval_s`` and poll again,
up to ``ci_poll_max_attempts`` times.
* still pending after all attempts -> (False, "CI still pending after <T>s").
* 404 -> (False, "Branch not found or no status").
* transient httpx errors -> logged and retried within the attempt budget;
if every attempt errors -> (False, "API error: <e>").
""" """
owner = settings.gitea_owner owner = settings.gitea_owner
url = f"{GITEA_BASE}/repos/{owner}/{repo}/commits/{branch}/status" url = f"{GITEA_BASE}/repos/{owner}/{repo}/commits/{branch}/status"
attempts = settings.ci_poll_max_attempts try:
interval = settings.ci_poll_interval_s resp = httpx.get(url, headers=GITEA_HEADERS, timeout=10)
last_state = "unknown" if resp.status_code == 404:
last_error: Exception | None = None return False, f"Branch '{branch}' not found or no status"
resp.raise_for_status()
for i in range(1, attempts + 1): data = resp.json()
try: state = data.get("state", "unknown")
resp = httpx.get(url, headers=GITEA_HEADERS, timeout=10) if state == "success":
if resp.status_code == 404: return True, "CI green"
return False, f"Branch '{branch}' not found or no status" return False, f"CI state: {state}"
resp.raise_for_status() except httpx.HTTPError as e:
data = resp.json() logger.error(f"Gitea API error checking CI: {e}")
last_state = data.get("state", "unknown") return False, f"API error: {e}"
last_error = None
if last_state == "success":
return True, "CI green"
if last_state in ("failure", "error"):
return False, f"CI state: {last_state}"
# non-terminal (pending / unknown / other) -> retry below
except httpx.HTTPError as e:
last_error = e
logger.error(f"check_ci_green: attempt {i}/{attempts} API error: {e}")
if i < attempts:
if last_error is not None:
logger.info(
f"check_ci_green: attempt {i}/{attempts}, error, retrying in {interval}s"
)
else:
logger.info(
f"check_ci_green: attempt {i}/{attempts}, state={last_state}, "
f"retrying in {interval}s"
)
time.sleep(interval)
if last_error is not None:
return False, f"API error: {last_error}"
return False, f"CI still pending after {attempts * interval}s"
def check_review_approved(repo: str, pr_number: int) -> tuple[bool, str]: def check_review_approved(repo: str, pr_number: int) -> tuple[bool, str]:
@@ -188,11 +145,8 @@ def check_tests_passed(repo: str, work_item_id: str, branch: str | None = None)
explicitly marked `verdict: BLOCKED` / `status: blocked` but whose prose mentioned explicitly marked `verdict: BLOCKED` / `status: blocked` but whose prose mentioned
"23 passed" / "✅ PASS" / "All checks passed" was treated as a pass, and an "23 passed" / "✅ PASS" / "All checks passed" was treated as a pass, and an
unfinished feature reached Done. This mirrors check_reviewer_verdict (S-5) and unfinished feature reached Done. This mirrors check_reviewer_verdict (S-5) and
check_deploy_status (БАГ 8): read ONLY the YAML frontmatter, never the body. check_deploy_status (БАГ 8): read ONLY the YAML frontmatter `verdict:` / `status:`
fields, never the body.
ORCH-047: the machine verdict is read from any of three equal-rank frontmatter
fields — `result:` (canonical, what the tester prompt emits), `verdict:` or
`status:` (legacy / enduro-trails). See _parse_tests_verdict.
File: docs/work-items/<work_item_id>/13-test-report.md File: docs/work-items/<work_item_id>/13-test-report.md
""" """
@@ -225,20 +179,15 @@ _TESTS_POSITIVE_TOKENS = ("PASSED", "PASS", "READY-TO-DEPLOY", "READY_TO_DEPLOY"
def _parse_tests_verdict(content: str) -> tuple[bool, str]: def _parse_tests_verdict(content: str) -> tuple[bool, str]:
"""Map a 13-test-report.md body to a quality-gate verdict by reading ONLY the """Map a 13-test-report.md body to a quality-gate verdict by reading ONLY the
machine-readable YAML frontmatter fields — never the prose body. machine-readable `verdict:` (and corroborating `status:`) YAML frontmatter fields.
Three equal-rank fields are accepted (ORCH-047): `result:` (the canonical field
the tester prompt `.openclaw/agents/tester.md` is told to emit, `result: PASS|FAIL`),
plus `verdict:` and `status:` (legacy / enduro-trails ET-001..ET-014). ANY single
non-empty field is sufficient. Token sets are frozen for backward compatibility.
Rules: Rules:
- No frontmatter / bad YAML / none of the three fields present -> (False, reason). - No frontmatter / bad YAML / neither field present -> (False, reason).
- A negative token (BLOCKED/FAILED/...) in ANY field -> (False) and is - A negative token (BLOCKED/FAILED/...) in verdict OR status -> (False) and is
authoritative (ET-013 main case: verdict BLOCKED wins over any prose PASS, and authoritative (ET-013 main case: verdict BLOCKED wins over any prose PASS).
beats a positive token in another field). - Otherwise a positive token (PASS/PASSED/READY-TO-DEPLOY/...) in verdict OR
- Otherwise a positive token (PASS/PASSED/READY-TO-DEPLOY/...) in ANY field -> (True). status -> (True).
- Anything else (fields set but unrecognized) -> (False, reason). - Anything else (unrecognized / empty verdict) -> (False, reason).
""" """
import yaml import yaml
@@ -258,25 +207,19 @@ def _parse_tests_verdict(content: str) -> tuple[bool, str]:
verdict = str(fm.get("verdict", "") or "").upper().strip() verdict = str(fm.get("verdict", "") or "").upper().strip()
status = str(fm.get("status", "") or "").upper().strip() status = str(fm.get("status", "") or "").upper().strip()
result = str(fm.get("result", "") or "").upper().strip()
if not verdict and not status and not result: if not verdict and not status:
return False, "No machine-readable verdict/status/result in test report frontmatter" return False, "No machine-readable verdict/status in test report frontmatter"
value = verdict or status or result fields = f"{verdict} {status}"
fields = f"{verdict} {status} {result}"
for neg in _TESTS_NEGATIVE_TOKENS: for neg in _TESTS_NEGATIVE_TOKENS:
if neg in fields: if neg in fields:
return False, f"Test verdict: {value} ({neg})" return False, f"Test verdict: {verdict or status} ({neg})"
for pos in _TESTS_POSITIVE_TOKENS: for pos in _TESTS_POSITIVE_TOKENS:
if pos in fields: if pos in fields:
return True, f"Test verdict: {value} (PASS)" return True, f"Test verdict: {verdict or status} (PASS)"
return ( return False, f"No recognized PASS verdict in frontmatter (verdict={verdict!r}, status={status!r})"
False,
f"No recognized PASS verdict in frontmatter "
f"(verdict={verdict!r}, status={status!r}, result={result!r})",
)
def check_analysis_approved(repo: str, work_item_id: str, branch: str | None = None) -> tuple[bool, str]: def check_analysis_approved(repo: str, work_item_id: str, branch: str | None = None) -> tuple[bool, str]:

View File

@@ -1,205 +0,0 @@
"""Defensive extractors for reviewer / tester artifact bodies (ORCH-046).
When a task is rolled back to ``development`` the stage engine builds the
``task_desc`` that ends up in the developer agent's ``.task-dev.md``. Historically
that text only carried a *link* to the artifact file (12-review.md /
13-test-report.md); the developer agent had to go read the file, and the key
must-fix points (reviewer P0/P1 findings, tester failure reason) were lost in
transit — "испорченный телефон" that burns the retry budget.
This module extracts the **verbatim** must-fix text so the stage engine can embed
it directly in ``task_desc`` (ADR docs/work-items/ORCH-046/06-adr/ADR-001-*).
Contract — **never raises** (mirrors ``src/frontmatter.py`` and
``src/qg/checks.py::_parse_tests_verdict``): any error — missing file, IOError,
malformed markdown/YAML, missing section — yields ``""``. The caller then falls
back to the previous link-only ``task_desc``. No network calls; disk reads only.
"""
import logging
import re
logger = logging.getLogger("orchestrator.review_parse")
# Truncation limits (module-level per ТЗ §2.3). The full context always stays in
# the artifact file; the embedded text is a focused excerpt.
MAX_FINDINGS_CHARS = 2000
MAX_FAILURES_CHARS = 2000
_TRUNCATED_MARKER = "\n…(truncated)"
# Recognize a `### P0`/`### P1` subsection header by the presence of the P0/P1
# token, tolerant to case and the dash/em-dash that follows it.
_P01_HEADER_RE = re.compile(r"(?<![A-Za-z0-9])p[01](?![0-9])", re.IGNORECASE)
def _read(path: str) -> str | None:
"""Read a file as UTF-8. Never raises; returns None on any OS error."""
try:
with open(path, "r", encoding="utf-8", errors="replace") as f:
return f.read()
except OSError as e:
logger.debug(f"review_parse: cannot open {path}: {e}")
return None
def _strip_frontmatter(content: str) -> str:
"""Drop a leading ``--- … ---`` YAML frontmatter block, if present."""
if content.startswith("---"):
parts = content.split("---", 2)
if len(parts) >= 3:
return parts[2]
return content
def _truncate(text: str, limit: int) -> str:
"""Trim ``text`` to ``limit`` chars, appending a truncation marker if cut."""
if len(text) <= limit:
return text
return text[:limit].rstrip() + _TRUNCATED_MARKER
def _section_body(md: str, heading_token: str) -> str:
"""Return the body lines under the first ``## <…heading_token…>`` heading.
Capture stops at the next level-2 (``## ``) heading. Matching is
case-insensitive substring match on the heading line, so callers pass a token
like ``"Вывод pytest"`` or ``"Findings"``. ``### ``-level headers do NOT
delimit the section (they start with ``"### "``, not ``"## "``).
"""
out: list[str] = []
capturing = False
for line in md.splitlines():
if line.startswith("## "):
if capturing:
break
if heading_token.lower() in line.lower():
capturing = True
continue
if capturing:
out.append(line)
return "\n".join(out)
def _is_placeholder_item(text: str) -> bool:
"""True for empty or template-placeholder list items (non-substantive).
The canonical reviewer template seeds each severity with
``- [ ] <описание> (если есть)``. Such lines must be ignored so an empty P0/P1
subsection does not leak the placeholder into ``task_desc``.
"""
t = text.strip()
if not t:
return True
if "(если есть)" in t:
return True
# An item whose entire payload is an angle-bracket placeholder, e.g. "<описание>".
if t.startswith("<") and t.endswith(">"):
return True
return False
def _item_payload(line: str) -> str | None:
"""If ``line`` is a markdown list item, return its payload text; else None.
Handles ``- foo``, ``* foo`` and checkbox forms ``- [ ] foo`` / ``- [x] foo``.
"""
m = re.match(r"\s*[-*]\s+(?:\[[ xX]?\]\s*)?(.*)$", line)
if not m:
return None
return m.group(1)
def _findings_subsections(findings_body: str):
"""Yield ``(header_line, body_lines)`` for each ``### `` subsection."""
header: str | None = None
body: list[str] = []
for line in findings_body.splitlines():
if line.startswith("### "):
if header is not None:
yield header, body
header = line
body = []
elif header is not None:
body.append(line)
if header is not None:
yield header, body
def extract_review_findings(path: str) -> str:
"""Дословный текст P0/P1 findings из 12-review.md. Never raises; '' при ошибке/пусто.
Reads the ``## Findings`` section of a reviewer report and returns the verbatim
P0 (Blocker) and P1 (Must fix) subsection items, suitable for embedding in a
rollback ``task_desc``. P2/P3 are ignored. Empty/placeholder-only subsections
are skipped; if no substantive P0/P1 item exists, returns ``""``. The result is
truncated to ``MAX_FINDINGS_CHARS``.
"""
content = _read(path)
if content is None:
return ""
try:
body = _strip_frontmatter(content)
findings_body = _section_body(body, "Findings")
if not findings_body.strip():
return ""
blocks: list[str] = []
for header, sub_body in _findings_subsections(findings_body):
if not _P01_HEADER_RE.search(header):
continue
kept: list[str] = []
for line in sub_body:
payload = _item_payload(line)
if payload is None:
continue
if _is_placeholder_item(payload):
continue
kept.append(line.rstrip())
if kept:
blocks.append("\n".join([header.rstrip(), *kept]))
if not blocks:
return ""
return _truncate("\n\n".join(blocks), MAX_FINDINGS_CHARS)
except Exception as e: # defensive: never raise out of the extractor
logger.debug(f"review_parse: extract_review_findings failed for {path}: {e}")
return ""
def extract_test_failures(path: str) -> str:
"""Релевантный фрагмент тела 13-test-report.md (причина FAIL). Never raises; '' при ошибке/пусто.
Picks the first non-empty source, in priority order:
1. ``## Вывод pytest`` — the pytest run output (shows failing tests);
2. rows of the ``## Результаты`` table that contain ``FAIL``;
3. ``## Итог`` — the verdict summary.
The result is truncated to ``MAX_FAILURES_CHARS``. The gate ``reason`` is added
by the caller; this returns the report-body excerpt on top of it.
"""
content = _read(path)
if content is None:
return ""
try:
# 1. pytest output.
pytest_out = _section_body(content, "Вывод pytest").strip()
if pytest_out:
return _truncate(pytest_out, MAX_FAILURES_CHARS)
# 2. FAIL rows from the results table.
results = _section_body(content, "Результаты")
fail_rows = [ln.rstrip() for ln in results.splitlines() if "FAIL" in ln.upper()]
if fail_rows:
return _truncate("\n".join(fail_rows).strip(), MAX_FAILURES_CHARS)
# 3. Verdict summary.
itog = _section_body(content, "Итог").strip()
if itog:
return _truncate(itog, MAX_FAILURES_CHARS)
return ""
except Exception as e: # defensive: never raise out of the extractor
logger.debug(f"review_parse: extract_test_failures failed for {path}: {e}")
return ""

View File

@@ -32,7 +32,6 @@ from dataclasses import dataclass, field
from .db import get_db, update_task_stage, enqueue_job from .db import get_db, update_task_stage, enqueue_job
from .stages import get_next_stage, get_qg_for_stage, get_agent_for_stage from .stages import get_next_stage, get_qg_for_stage, get_agent_for_stage
from .git_worktree import get_worktree_path from .git_worktree import get_worktree_path
from .review_parse import extract_review_findings, extract_test_failures
from .qg.checks import QG_CHECKS from .qg.checks import QG_CHECKS
from .notifications import ( from .notifications import (
notify_stage_change, notify_stage_change,
@@ -417,24 +416,12 @@ def _handle_qg_failure_rollbacks(
result.rolled_back_to = "development" result.rolled_back_to = "development"
retry_count = _developer_retry_count(task_id) retry_count = _developer_retry_count(task_id)
if retry_count < MAX_DEVELOPER_RETRIES: if retry_count < MAX_DEVELOPER_RETRIES:
# ORCH-046: embed the verbatim P0/P1 findings into task_desc so the task_desc = (
# developer agent sees the must-fix points directly (not just a link).
# extract_review_findings never raises; "" -> graceful link-only fallback.
review_ref = f"docs/work-items/{work_item_id}/12-review.md"
review_path = os.path.join(get_worktree_path(repo, branch), review_ref)
findings = extract_review_findings(review_path)
head = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n" f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: REQUEST_CHANGES from reviewer " f"Stage: development\nNote: REQUEST_CHANGES from reviewer "
f"(attempt {retry_count+1}/3)." f"(attempt {retry_count+1}/3). Fix findings in "
f"docs/work-items/{work_item_id}/12-review.md"
) )
if findings:
task_desc = (
f"{head}\nFindings (P0/P1):\n{findings}\n"
f"Полный контекст: {review_ref}"
)
else:
task_desc = f"{head} Fix findings in {review_ref}"
new_job = enqueue_job("developer", repo, task_desc, task_id=task_id) new_job = enqueue_job("developer", repo, task_desc, task_id=task_id)
result.enqueued_agent = "developer" result.enqueued_agent = "developer"
result.enqueued_job_id = new_job result.enqueued_job_id = new_job
@@ -465,23 +452,11 @@ def _handle_qg_failure_rollbacks(
) )
retry_count = _developer_retry_count(task_id) retry_count = _developer_retry_count(task_id)
if retry_count < MAX_DEVELOPER_RETRIES: if retry_count < MAX_DEVELOPER_RETRIES:
# ORCH-046: embed the gate `reason` plus a verbatim excerpt of the task_desc = (
# test-report body (pytest output / FAIL rows / Итог) into task_desc.
# extract_test_failures never raises; "" -> graceful reason+link fallback.
report_ref = f"docs/work-items/{work_item_id}/13-test-report.md"
report_path = os.path.join(get_worktree_path(repo, branch), report_ref)
failures = extract_test_failures(report_path)
head = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n" f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: Tests FAILED. Причина: {reason}." f"Stage: development\nNote: Tests FAILED. "
f"Fix failures described in docs/work-items/{work_item_id}/13-test-report.md"
) )
if failures:
task_desc = (
f"{head}\nДетали:\n{failures}\n"
f"Полный контекст: {report_ref}"
)
else:
task_desc = f"{head} Fix failures described in {report_ref}"
new_job = enqueue_job("developer", repo, task_desc, task_id=task_id) new_job = enqueue_job("developer", repo, task_desc, task_id=task_id)
result.enqueued_agent = "developer" result.enqueued_agent = "developer"
result.enqueued_job_id = new_job result.enqueued_job_id = new_job

View File

@@ -1,100 +0,0 @@
"""ORCH-017 / TC-10: analysis-approved flow wires DB fields into the approve ping.
When the analyst's artifacts are ready, `_handle_analysis_approved_flow` sets the
issue In Review, posts the analyst comment, and calls `notify_approve_requested`.
This test drives that flow with all network side-effects mocked and asserts the
resulting Telegram ping carries the BRD + Plane links built from the task's DB
row (repo / branch / plane_issue_id), while the approval gate name and the
no-self-advance contract are unchanged (AC-1 / AC-2 / AC-8).
"""
import os
import tempfile
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_approve_flow.db")
os.environ["ORCH_DB_PATH"] = _test_db
import pytest # noqa: E402
import src.db as db_module # noqa: E402
from src.db import init_db, get_db # noqa: E402
from src import notifications as N # noqa: E402
from src import stage_engine as SE # noqa: E402
_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
@pytest.fixture(autouse=True)
def setup_db(monkeypatch):
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
yield
if os.path.exists(_test_db):
os.unlink(_test_db)
def _mk_task(monkeypatch):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, "
"plane_issue_id) VALUES (?, ?, ?, ?, ?, ?, ?)",
("p1", "ORCH-017", "orchestrator",
"feature/ORCH-017-brd-plane-telegram", "analysis",
"Approve flow", "issue-uuid-7"),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def test_tc10_approved_flow_builds_links_from_db(monkeypatch):
tid = _mk_task(monkeypatch)
# Settings that make both links resolvable.
s = N._get_settings()
monkeypatch.setattr(s, "gitea_public_url", "https://git.example.org", raising=False)
monkeypatch.setattr(s, "gitea_owner", "orchteam", raising=False)
monkeypatch.setattr(s, "plane_web_url", "https://plane.example.org", raising=False)
monkeypatch.setattr(s, "plane_workspace_slug", "acme", raising=False)
# Isolate every network/fs side-effect of the flow.
monkeypatch.setitem(SE.QG_CHECKS, "check_analysis_complete",
lambda repo, wid, branch: (True, "ok"))
monkeypatch.setattr(SE, "set_issue_in_review", lambda wid: None)
monkeypatch.setattr(SE, "plane_add_comment", lambda *a, **k: None)
monkeypatch.setattr(SE, "_build_analyst_ready_comment", lambda *a, **k: "c")
# Capture the approve ping; stub the tracker refresh.
calls = []
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False: calls.append(text) or 1)
monkeypatch.setattr(N, "update_task_tracker", lambda task_id: None)
result = SE.AdvanceResult()
SE._handle_analysis_approved_flow(
tid, "analysis", "orchestrator", "ORCH-017",
"feature/ORCH-017-brd-plane-telegram", "analyst", result,
)
# Gate name + no-self-advance contract unchanged (AC-8).
assert result.qg_name == "check_analysis_approved"
assert result.note == "analysis-in-review"
assert result.advanced is False
# Exactly one ping carrying both links built from the DB row (AC-1 / AC-2).
assert len(calls) == 1
text = calls[0]
assert (
"https://git.example.org/orchteam/orchestrator/src/branch/"
"feature/ORCH-017-brd-plane-telegram/docs/work-items/ORCH-017/01-brd.md"
) in text
assert (
f"https://plane.example.org/acme/projects/{_ORCH_PROJECT_ID}"
f"/issues/issue-uuid-7/"
) in text

View File

@@ -1,27 +0,0 @@
"""ORCH-042: Settings.tracker_mode config field.
AC-1: tracker_mode defaults to "edit" and is read from env ORCH_TRACKER_MODE.
Settings is a Pydantic BaseSettings reading env at instantiation, so each case
builds a FRESH Settings() (the process-wide singleton is not mutated).
"""
from src.config import Settings
def test_tracker_mode_defaults_to_edit(monkeypatch):
# No env var -> default "edit" (TC-01 / AC-1).
monkeypatch.delenv("ORCH_TRACKER_MODE", raising=False)
assert Settings().tracker_mode == "edit"
def test_tracker_mode_reads_env_bump(monkeypatch):
# ORCH_TRACKER_MODE=bump -> "bump" (TC-01 / AC-1).
monkeypatch.setenv("ORCH_TRACKER_MODE", "bump")
assert Settings().tracker_mode == "bump"
def test_tracker_mode_reads_env_arbitrary(monkeypatch):
# The field is read verbatim from env; mode RESOLUTION (anything != "bump"
# -> edit) happens in notifications, not here (AC-1/AC-2 split).
monkeypatch.setenv("ORCH_TRACKER_MODE", "garbage")
assert Settings().tracker_mode == "garbage"

View File

@@ -34,27 +34,6 @@ import src.plane_sync as plane_sync # noqa: E402
ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a" ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c" ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
# ORCH-39: after ORCH-10 the webhook resolves Plane state UUIDs per-project via
# get_project_states(project_id). Mock it deterministically (no network) and
# send each request with the UUID that matches its own project.
_PROJECT_STATES = {
ENDURO_PLANE_ID: {
"in_progress": "b873d9eb-993c-48cd-97ac-99a9b1623967",
"approved": "a519a341-dada-4a91-8910-7604f82b79c5",
"rejected": "ba958f3c-5db5-461d-8f82-89425e413b97",
},
ORCH_PLANE_ID: {
"in_progress": "e331bfb3-e17e-4699-ba48-4abb89c21b7b",
"approved": "63f2c8fe-dcda-4ace-952f-dd88bd0118ff",
"rejected": "4c769e90-bf80-4a52-b97a-e1c84904bfc3",
},
}
def _fake_get_project_states(project_id):
return _PROJECT_STATES.get(project_id, _PROJECT_STATES[ENDURO_PLANE_ID])
client = TestClient(app) client = TestClient(app)
@@ -69,10 +48,6 @@ def setup(monkeypatch):
monkeypatch.setattr("src.webhooks.plane.verify_plane_signature", lambda body, sig: True) monkeypatch.setattr("src.webhooks.plane.verify_plane_signature", lambda body, sig: True)
# ORCH-39: deterministic per-project Plane states, clean cache per test.
plane_sync.reload_project_states()
monkeypatch.setattr(plane_sync, "get_project_states", _fake_get_project_states)
registry_json = ( registry_json = (
f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",' f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",'
f' "work_item_prefix": "ET", "name": "enduro-trails"}},' f' "work_item_prefix": "ET", "name": "enduro-trails"}},'
@@ -85,7 +60,6 @@ def setup(monkeypatch):
yield yield
reload_projects() reload_projects()
plane_sync.reload_project_states()
if os.path.exists(_test_db): if os.path.exists(_test_db):
os.unlink(_test_db) os.unlink(_test_db)
@@ -129,9 +103,10 @@ def test_fetch_sequence_id_missing_field_returns_none():
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# Feature 1: pipeline starts on a status change to In Progress, not on creation. # Feature 1: pipeline starts on a status change to In Progress, not on creation.
# ORCH-39: in_progress UUID is project-specific; derive it from the project. _IN_PROGRESS = "b873d9eb-993c-48cd-97ac-99a9b1623967"
def _post(plane_id, plane_project_id=ORCH_PLANE_ID, name="A valid work item title"): def _post(plane_id, plane_project_id=ORCH_PLANE_ID, name="A valid work item title"):
in_progress = _fake_get_project_states(plane_project_id)["in_progress"]
return client.post( return client.post(
"/webhook/plane", "/webhook/plane",
json={ json={
@@ -142,7 +117,7 @@ def _post(plane_id, plane_project_id=ORCH_PLANE_ID, name="A valid work item titl
"name": name, "name": name,
"description_stripped": "This is a sufficiently long description.", "description_stripped": "This is a sufficiently long description.",
"project": plane_project_id, "project": plane_project_id,
"state": {"id": in_progress, "name": "In Progress", "group": "started"}, "state": {"id": _IN_PROGRESS, "name": "In Progress", "group": "started"},
}, },
}, },
) )

View File

@@ -1,284 +0,0 @@
"""ORCH-017: tests for the direct BRD + Plane links in the approve-gate ping.
`notify_approve_requested` builds ONE notifying Telegram message that embeds:
* a Gitea branch-view link to docs/work-items/<WI>/01-brd.md (AC-1)
* a Plane issue browser link (AC-2)
Both links use external base URLs with documented fallbacks (AC-3), degrade
gracefully when data is missing / the Plane base is loopback (AC-6), keep the
'flip to Approved' call to action (AC-4), send exactly one notifying message
(AC-5) and stay HTML-safe (AC-7).
Network is isolated: send_telegram is replaced with an in-test recorder, the DB
is a temp SQLite seeded by a fixture. Mapping to acceptance criteria is in each
test's docstring (test ids TC-01..TC-08 from 04-test-plan.yaml).
"""
import os
import tempfile
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_approve_links.db")
os.environ["ORCH_DB_PATH"] = _test_db
from unittest.mock import MagicMock, patch # noqa: E402
import pytest # noqa: E402
import src.db as db_module # noqa: E402
from src.db import init_db, get_db # noqa: E402
from src import notifications as N # noqa: E402
# Captured at import time, BEFORE the conftest autouse fixture stubs it to a
# no-op, so TC-08 can exercise the REAL send_telegram (parse_mode=HTML) end-to-end.
_ORIG_SEND_TELEGRAM = N.send_telegram
# orchestrator repo -> default project registry uuid (src/projects.py).
_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
@pytest.fixture(autouse=True)
def setup_db(monkeypatch):
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
yield
if os.path.exists(_test_db):
os.unlink(_test_db)
def _mk_task(wid="ORCH-017", repo="orchestrator",
branch="feature/ORCH-017-brd-plane-telegram",
plane_issue_id="11112222-3333-4444-5555-666677778888",
title="Links in approve ping", stage="analysis"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, "
"plane_issue_id) VALUES (?, ?, ?, ?, ?, ?, ?)",
("p1", wid, repo, branch, stage, title, plane_issue_id),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def _set(monkeypatch, **kw):
"""Set settings attrs on the singleton notifications actually reads."""
s = N._get_settings()
for k, v in kw.items():
monkeypatch.setattr(s, k, v, raising=False)
def _record_send(monkeypatch):
"""Replace send_telegram with a recorder; returns the calls list."""
calls = []
def _fake(text, disable_notification=False):
calls.append({"text": text, "silent": disable_notification})
return 1
monkeypatch.setattr(N, "send_telegram", _fake)
# Tracker refresh is irrelevant here and would hit send_telegram too -> stub.
monkeypatch.setattr(N, "update_task_tracker", lambda task_id: None)
return calls
# --------------------------------------------------------------------------- #
# TC-01 — BRD link (Gitea branch-view), AC-1 / AC-3
# --------------------------------------------------------------------------- #
def test_tc01_brd_link_present(monkeypatch):
tid = _mk_task()
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_url="http://localhost:3000", gitea_owner="orchteam")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
assert len(calls) == 1
text = calls[0]["text"]
expected = (
'https://git.example.org/orchteam/orchestrator/src/branch/'
'feature/ORCH-017-brd-plane-telegram/docs/work-items/ORCH-017/01-brd.md'
)
assert expected in text
assert f'<a href="{expected}">' in text # clickable, points at 01-brd.md
# --------------------------------------------------------------------------- #
# TC-02 — Plane issue link (external web URL + workspace + project + issue id)
# AC-2 / AC-3
# --------------------------------------------------------------------------- #
def test_tc02_plane_link_present(monkeypatch):
tid = _mk_task(plane_issue_id="abcd-issue-uuid")
_set(monkeypatch, plane_web_url="https://plane.example.org",
plane_api_url="http://localhost:8091", plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
text = calls[0]["text"]
expected = (
f"https://plane.example.org/acme/projects/{_ORCH_PROJECT_ID}"
f"/issues/abcd-issue-uuid/"
)
assert expected in text
assert f'<a href="{expected}">' in text
# --------------------------------------------------------------------------- #
# TC-03 — fallback chain: gitea_public_url -> gitea_url, plane_web_url -> plane_api_url
# AC-3
# --------------------------------------------------------------------------- #
def test_tc03_url_fallbacks(monkeypatch):
tid = _mk_task(plane_issue_id="iss-1")
_set(monkeypatch,
gitea_public_url="", gitea_url="https://git-fallback.example.org",
gitea_owner="orchteam",
plane_web_url="", plane_api_url="https://plane-fallback.example.org",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
text = calls[0]["text"]
# BRD link uses gitea_url fallback.
assert "https://git-fallback.example.org/orchteam/orchestrator/" in text
# Plane link uses plane_api_url fallback (non-loopback -> allowed).
assert (
f"https://plane-fallback.example.org/acme/projects/{_ORCH_PROJECT_ID}"
f"/issues/iss-1/"
) in text
# --------------------------------------------------------------------------- #
# TC-04 — the 'flip to Approved' call to action is preserved. AC-4
# --------------------------------------------------------------------------- #
def test_tc04_keeps_approved_call_to_action(monkeypatch):
tid = _mk_task()
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam", plane_web_url="https://plane.example.org",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
assert "Approved" in calls[0]["text"]
# --------------------------------------------------------------------------- #
# TC-05 — exactly one notifying (non-silent) message. AC-5
# --------------------------------------------------------------------------- #
def test_tc05_single_notifying_message(monkeypatch):
tid = _mk_task()
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam", plane_web_url="https://plane.example.org",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
assert len(calls) == 1
assert calls[0]["silent"] is not True # notifying ping, not silent
# --------------------------------------------------------------------------- #
# TC-06 — graceful: no branch / no plane_issue_id -> still one message, missing
# links omitted, no exception. AC-6
# --------------------------------------------------------------------------- #
def test_tc06_graceful_missing_branch_and_issue(monkeypatch):
tid = _mk_task(branch=None, plane_issue_id=None)
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam", plane_web_url="https://plane.example.org",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid) # must not raise
assert len(calls) == 1
text = calls[0]["text"]
assert "Approved" in text # message still sent
assert "01-brd.md" not in text # BRD link omitted (no branch)
assert "/issues/" not in text # Plane link omitted (no issue id)
# --------------------------------------------------------------------------- #
# TC-07 — Plane base unusable (web url empty + api url empty) -> Plane link
# dropped, BRD link stays, orchestrator survives. AC-6
# --------------------------------------------------------------------------- #
def test_tc07_plane_base_empty_drops_plane_link_keeps_brd(monkeypatch):
tid = _mk_task()
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam",
plane_web_url="", plane_api_url="", plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
text = calls[0]["text"]
assert "01-brd.md" in text # BRD link survives
assert "/issues/" not in text # Plane link dropped
def test_tc07b_loopback_plane_base_dropped(monkeypatch):
"""Loopback fallback (plane_api_url=localhost) must NOT emit a broken link."""
tid = _mk_task()
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam",
plane_web_url="", plane_api_url="http://localhost:8091",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
text = calls[0]["text"]
assert "localhost" not in text # no loopback URL leaks into the ping
assert "/issues/" not in text # Plane link dropped by loopback-guard
assert "01-brd.md" in text
# --------------------------------------------------------------------------- #
# TC-08 — HTML safety: parse_mode=HTML preserved + dynamic parts escaped + valid
# <a> markup. AC-7
# --------------------------------------------------------------------------- #
def test_tc08_html_escaped_and_valid_markup(monkeypatch):
# work_item_id with an ampersand exercises html.escape on the dynamic label.
tid = _mk_task(wid="ORCH&17")
_set(monkeypatch, gitea_public_url="https://git.example.org",
gitea_owner="orchteam", plane_web_url="https://plane.example.org",
plane_workspace_slug="acme")
calls = _record_send(monkeypatch)
N.notify_approve_requested(tid)
text = calls[0]["text"]
# Dynamic work_item_id escaped in the header (no raw '&' before a word).
assert "ORCH&amp;17" in text
# Well-formed anchor markup: equal number of opening/closing tags.
assert text.count("<a href=") == text.count("</a>")
assert text.count("<a href=") >= 1
def test_tc08b_send_telegram_keeps_parse_mode_html(monkeypatch):
"""End-to-end through the REAL send_telegram: payload still parse_mode=HTML."""
# Restore the genuine send_telegram (conftest stubbed it to a no-op).
monkeypatch.setattr(N, "send_telegram", _ORIG_SEND_TELEGRAM)
monkeypatch.setattr(N, "update_task_tracker", lambda task_id: None)
_set(monkeypatch, telegram_bot_token="T", telegram_chat_id="C",
gitea_public_url="https://git.example.org", gitea_owner="orchteam",
plane_web_url="https://plane.example.org", plane_workspace_slug="acme")
tid = _mk_task()
with patch("src.notifications.httpx") as hx:
resp = MagicMock()
resp.json.return_value = {"ok": True, "result": {"message_id": 9}}
hx.post.return_value = resp
N.notify_approve_requested(tid)
assert hx.post.call_count == 1
payload = hx.post.call_args.kwargs["json"]
assert payload["parse_mode"] == "HTML"
assert payload["disable_notification"] is False # notifying
assert "<a href=" in payload["text"]

View File

@@ -1,112 +0,0 @@
"""ORCH-040: контейнер/агенты бегут под uid:gid хоста (1000:1000), не root.
Валидируют docker-compose.yml (Вариант 1 из ADR-001) и согласованность с
HOME, который форсит launcher. Чистые конфиг-тесты: парсят YAML и текст
launcher, без запуска docker/агентов.
См. docs/work-items/ORCH-040/{02-trz.md,03-acceptance-criteria.md,
04-test-plan.yaml} и 06-adr/ADR-001-run-agents-as-host-uid.md.
"""
from pathlib import Path
import pytest
import yaml
REPO_ROOT = Path(__file__).resolve().parents[1]
COMPOSE_PATH = REPO_ROOT / "docker-compose.yml"
LAUNCHER_PATH = REPO_ROOT / "src" / "agents" / "launcher.py"
# Сервисы, которые исполняют конвейер и обязаны бежать под uid хоста.
PIPELINE_SERVICES = ("orchestrator", "orchestrator-staging")
# Единый HOME агента (форсится launcher'ом); под ним должны лежать .ssh/.claude.
EXPECTED_HOME = "/home/slin"
@pytest.fixture(scope="module")
def compose() -> dict:
"""Распарсенный docker-compose.yml."""
with COMPOSE_PATH.open(encoding="utf-8") as fh:
data = yaml.safe_load(fh)
assert "services" in data, "docker-compose.yml без секции services"
return data
def _service(compose: dict, name: str) -> dict:
services = compose["services"]
assert name in services, f"сервис {name} отсутствует в docker-compose.yml"
return services[name]
def _ssh_mount_target(service: dict) -> str:
"""Target SSH-маунта (источник .orchestrator-ssh) для сервиса."""
for vol in service.get("volumes", []):
# формат "src:target[:mode]"
parts = vol.split(":")
src = parts[0]
if src.endswith(".orchestrator-ssh"):
assert len(parts) >= 2, f"SSH-маунт без target: {vol}"
return parts[1]
raise AssertionError("SSH-маунт (.orchestrator-ssh) не найден в volumes")
# --- TC-01: user: "1000:1000" в обоих сервисах ---------------------------------
@pytest.mark.parametrize("name", PIPELINE_SERVICES)
def test_tc01_service_runs_as_host_uid(compose, name):
"""TC-01/AC-1: сервис бежит под uid:gid хоста 1000:1000, а не root."""
service = _service(compose, name)
assert "user" in service, f"{name}: отсутствует ключ user (нужен '1000:1000')"
# docker допускает int или строку; нормализуем к строке.
assert str(service["user"]) == "1000:1000", (
f"{name}: user={service['user']!r}, ожидалось '1000:1000'"
)
# --- TC-02: group_add сохраняет "999" (docker.sock — МИНА 1) --------------------
@pytest.mark.parametrize("name", PIPELINE_SERVICES)
def test_tc02_group_add_keeps_docker_gid(compose, name):
"""TC-02/AC-4: group_add содержит 999 (доступ к docker.sock не потерян)."""
service = _service(compose, name)
group_add = service.get("group_add", [])
normalized = {str(g) for g in group_add}
assert "999" in normalized, (
f"{name}: group_add={group_add!r}, должен содержать '999' (docker.sock)"
)
# --- TC-03: SSH-маунт согласован с HOME (под /home/slin, не /root) --------------
@pytest.mark.parametrize("name", PIPELINE_SERVICES)
def test_tc03_ssh_mount_under_home(compose, name):
"""TC-03/AC-5: target SSH-маунта лежит в HOME агента (/home/slin/.ssh)."""
service = _service(compose, name)
target = _ssh_mount_target(service)
assert target == f"{EXPECTED_HOME}/.ssh", (
f"{name}: SSH target={target!r}, ожидалось '{EXPECTED_HOME}/.ssh' "
f"(не /root/.ssh — иначе рассинхрон с HOME агента)"
)
assert not target.startswith("/root/"), (
f"{name}: SSH target указывает на чужой HOME (/root): {target}"
)
# --- TC-04: HOME launcher'а совместим с SSH/claude-маунтами ---------------------
def test_tc04_launcher_home_matches_mounts(compose):
"""TC-04: HOME, форсимый launcher'ом, совпадает с базой SSH/claude-маунтов.
Нет рассинхрона HOME vs uid: и env Popen, и git_env, и target SSH-маунта
все указывают на /home/slin.
"""
source = LAUNCHER_PATH.read_text(encoding="utf-8")
# launcher форсит HOME в двух местах (env Popen и git_env).
occurrences = source.count(f'"HOME": "{EXPECTED_HOME}"')
assert occurrences >= 2, (
f"launcher.py: ожидалось >=2 форсинга HOME={EXPECTED_HOME!r}, "
f"найдено {occurrences}"
)
# И SSH-маунты обоих сервисов ведут в этот же HOME.
for name in PIPELINE_SERVICES:
target = _ssh_mount_target(_service(compose, name))
assert target.startswith(f"{EXPECTED_HOME}/"), (
f"{name}: SSH target {target} не под HOME агента {EXPECTED_HOME}"
)

View File

@@ -33,36 +33,11 @@ from src.main import app # noqa: E402
from src.db import init_db, get_db # noqa: E402 from src.db import init_db, get_db # noqa: E402
from src import projects as P # noqa: E402 from src import projects as P # noqa: E402
from src.projects import reload_projects # noqa: E402 from src.projects import reload_projects # noqa: E402
import src.plane_sync as plane_sync # noqa: E402
ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a" ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c" ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
UNKNOWN_PLANE_ID = "deadbeef-0000-0000-0000-000000000000" UNKNOWN_PLANE_ID = "deadbeef-0000-0000-0000-000000000000"
# ORCH-39: after ORCH-10 the webhook resolves Plane state UUIDs per-project via
# get_project_states(project_id). Hardcoding the enduro in_progress UUID for an
# ORCH-project payload no longer matches, so the pipeline never starts. We mock
# get_project_states with a deterministic per-project map (no network) and send
# each request with the UUID that matches its own project.
_PROJECT_STATES = {
ENDURO_PLANE_ID: {
"in_progress": "b873d9eb-993c-48cd-97ac-99a9b1623967",
"approved": "a519a341-dada-4a91-8910-7604f82b79c5",
"rejected": "ba958f3c-5db5-461d-8f82-89425e413b97",
},
ORCH_PLANE_ID: {
"in_progress": "e331bfb3-e17e-4699-ba48-4abb89c21b7b",
"approved": "63f2c8fe-dcda-4ace-952f-dd88bd0118ff",
"rejected": "4c769e90-bf80-4a52-b97a-e1c84904bfc3",
},
}
def _fake_get_project_states(project_id):
"""Deterministic per-project state map; mirrors get_project_states' fallback
for unknown projects so the webhook still behaves sensibly."""
return _PROJECT_STATES.get(project_id, _PROJECT_STATES[ENDURO_PLANE_ID])
client = TestClient(app) client = TestClient(app)
@@ -82,13 +57,6 @@ def setup(monkeypatch):
# focuses on the project filter, so bypass signature verification. # focuses on the project filter, so bypass signature verification.
monkeypatch.setattr("src.webhooks.plane.verify_plane_signature", lambda body, sig: True) monkeypatch.setattr("src.webhooks.plane.verify_plane_signature", lambda body, sig: True)
# ORCH-39: resolve Plane states deterministically per-project (no network)
# and start from a clean per-project cache so suites don't leak into each
# other. plane.py imports get_project_states locally from ..plane_sync, so
# patch it at the src.plane_sync source.
plane_sync.reload_project_states()
monkeypatch.setattr(plane_sync, "get_project_states", _fake_get_project_states)
registry_json = ( registry_json = (
f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",' f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",'
f' "work_item_prefix": "ET", "name": "enduro-trails"}},' f' "work_item_prefix": "ET", "name": "enduro-trails"}},'
@@ -101,7 +69,6 @@ def setup(monkeypatch):
yield yield
reload_projects() # restore from env reload_projects() # restore from env
plane_sync.reload_project_states()
if os.path.exists(_test_db): if os.path.exists(_test_db):
os.unlink(_test_db) os.unlink(_test_db)
@@ -109,10 +76,10 @@ def setup(monkeypatch):
# Feature 1: the pipeline now starts on a status change to In Progress (not on # Feature 1: the pipeline now starts on a status change to In Progress (not on
# creation). _post_created drives that status-change event so these ORCH-6 # creation). _post_created drives that status-change event so these ORCH-6
# routing tests still exercise task creation through the new trigger. # routing tests still exercise task creation through the new trigger.
# ORCH-39: the in_progress UUID is now project-specific, so derive it from the _IN_PROGRESS = "b873d9eb-993c-48cd-97ac-99a9b1623967"
# project being posted to (matches get_project_states resolution above).
def _post_created(plane_project_id, plane_id="wi-1", name="A valid work item title"): def _post_created(plane_project_id, plane_id="wi-1", name="A valid work item title"):
in_progress = _fake_get_project_states(plane_project_id)["in_progress"]
return client.post( return client.post(
"/webhook/plane", "/webhook/plane",
json={ json={
@@ -123,7 +90,7 @@ def _post_created(plane_project_id, plane_id="wi-1", name="A valid work item tit
"name": name, "name": name,
"description_stripped": "This is a sufficiently long description.", "description_stripped": "This is a sufficiently long description.",
"project": plane_project_id, "project": plane_project_id,
"state": {"id": in_progress, "name": "In Progress", "group": "started"}, "state": {"id": _IN_PROGRESS, "name": "In Progress", "group": "started"},
}, },
}, },
) )

View File

@@ -93,82 +93,38 @@ class TestCheckArchitectureDone:
assert passed is False assert passed is False
def _ci_status_resp(state, status_code=200):
"""Build a MagicMock httpx response for the Gitea combined-status endpoint."""
mock_resp = MagicMock()
mock_resp.status_code = status_code
mock_resp.json.return_value = {"state": state}
mock_resp.raise_for_status = MagicMock()
return mock_resp
class TestCheckCIGreen: class TestCheckCIGreen:
"""ORCH-045: check_ci_green now polls with retry to ride out a transient
`pending` right after the developer push (race fix, see ORCH-017)."""
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get") @patch("src.qg.checks.httpx.get")
def test_ci_success_first_attempt(self, mock_get, mock_sleep): def test_ci_success(self, mock_get):
mock_get.return_value = _ci_status_resp("success") mock_resp = MagicMock()
mock_resp.status_code = 200
mock_resp.json.return_value = {"state": "success"}
mock_resp.raise_for_status = MagicMock()
mock_get.return_value = mock_resp
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test") passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is True assert passed is True
assert "green" in reason.lower() assert "green" in reason.lower()
assert mock_get.call_count == 1
mock_sleep.assert_not_called()
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get") @patch("src.qg.checks.httpx.get")
def test_ci_pending_then_success(self, mock_get, mock_sleep): def test_ci_pending(self, mock_get):
# pending on the 1st poll, green on the 2nd -> success after one retry. mock_resp = MagicMock()
mock_get.side_effect = [ mock_resp.status_code = 200
_ci_status_resp("pending"), mock_resp.json.return_value = {"state": "pending"}
_ci_status_resp("success"), mock_resp.raise_for_status = MagicMock()
] mock_get.return_value = mock_resp
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is True
assert "green" in reason.lower()
assert mock_get.call_count == 2
assert mock_sleep.call_count == 1 # slept once between the two polls
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_failure_no_retry(self, mock_get, mock_sleep):
# CI is red -> terminal, return immediately without sleeping/retrying.
mock_get.return_value = _ci_status_resp("failure")
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test") passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is False assert passed is False
assert "failure" in reason
assert mock_get.call_count == 1
mock_sleep.assert_not_called()
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get") @patch("src.qg.checks.httpx.get")
def test_ci_pending_exhausts_attempts(self, mock_get, mock_sleep): def test_ci_branch_not_found(self, mock_get):
# Always pending -> after ci_poll_max_attempts polls return an explicit
# (False, "...pending...") so the operator sees the reason (no silent stall).
from src.qg.checks import settings as checks_settings
mock_get.return_value = _ci_status_resp("pending")
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is False
assert "pending" in reason.lower()
assert mock_get.call_count == checks_settings.ci_poll_max_attempts
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_branch_not_found(self, mock_get, mock_sleep):
mock_resp = MagicMock() mock_resp = MagicMock()
mock_resp.status_code = 404 mock_resp.status_code = 404
mock_get.return_value = mock_resp mock_get.return_value = mock_resp
passed, reason = check_ci_green("enduro-trails", "nonexistent") passed, reason = check_ci_green("enduro-trails", "nonexistent")
assert passed is False assert passed is False
assert "not found" in reason.lower()
assert mock_get.call_count == 1
class TestCheckReviewApproved: class TestCheckReviewApproved:
@@ -322,64 +278,6 @@ class TestCheckTestsPassed:
assert passed is False assert passed is False
assert "not found" in reason.lower() assert "not found" in reason.lower()
# --- ORCH-047: `result:` is read as an equal-rank machine field ---
def test_result_pass_passes(self, setup_work_item_dir):
# TC-01 / AC-01: canonical tester field `result: PASS` (no verdict/status).
self._write(
setup_work_item_dir,
"---\ntype: test-report\nresult: PASS\n---\n\n# Test Report\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is True
assert "PASS" in reason
def test_result_fail_fails(self, setup_work_item_dir):
# TC-02 / AC-02: `result: FAIL` (no verdict/status) -> rollback, reason has FAIL.
self._write(setup_work_item_dir, "---\nresult: FAIL\n---\n\nbody\n")
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "FAIL" in reason
def test_result_pass_but_verdict_blocked_fails(self, setup_work_item_dir):
# TC-03 / AC-03: negative in another field is authoritative over result: PASS.
self._write(
setup_work_item_dir,
"---\nresult: PASS\nverdict: BLOCKED\n---\n\n23 passed\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "BLOCKED" in reason
def test_result_pass_but_status_failed_fails(self, setup_work_item_dir):
# TC-04 / AC-03: status: failed authoritative over result: PASS.
self._write(
setup_work_item_dir,
"---\nresult: PASS\nstatus: failed\n---\n\nbody\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "FAILED" in reason
def test_result_ready_to_deploy_passes(self, setup_work_item_dir):
# TC-05 / AC-04: positive token without the word PASS, in result field.
self._write(
setup_work_item_dir,
"---\nresult: ready-to-deploy\n---\n\nbody\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is True
def test_no_machine_field_reason_mentions_result(self, setup_work_item_dir):
# AC-06: none of result/verdict/status -> fail; reason now lists result too.
self._write(
setup_work_item_dir,
"---\ntype: test-report\nversion: 1\n---\n\nResult: PASS\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "result" in reason.lower()
class TestCheckDeployStatus: class TestCheckDeployStatus:
"""BUG 8: deploy -> done must be gated on the deployer's machine-readable """BUG 8: deploy -> done must be gated on the deployer's machine-readable

View File

@@ -1,138 +0,0 @@
"""ORCH-41: tests for resolve_agent_effort + effort validation + flag assembly.
Mirrors test_resolve_agent_model's 4-level priority for the --effort lever, and
adds:
- validation: a value outside {low,medium,high,xhigh,max} is dropped -> ""
- flag assembly: --model / --effort / --fallback-model are present/absent in
the built command exactly when the resolved value is non-empty.
"""
import os
import tempfile
import pytest
os.environ.setdefault("ORCH_DB_PATH",
os.path.join(tempfile.gettempdir(), "test_orch41_effort.db"))
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
from src.agents.launcher import (
resolve_agent_effort, resolve_agent_model, VALID_EFFORTS,
)
from src.config import settings
from src import projects as P
from src.projects import ProjectConfig, reload_projects
ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
@pytest.fixture(autouse=True)
def _clean_settings(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_default", "high")
for a in ("analyst", "architect", "developer", "reviewer"):
monkeypatch.setattr(settings, f"agent_effort_{a}", "high")
for a in ("tester", "deployer"):
monkeypatch.setattr(settings, f"agent_effort_{a}", "medium")
monkeypatch.setattr(P.settings, "projects_json", "")
reload_projects()
yield
reload_projects()
def _install_registry(monkeypatch, agent_efforts):
reg = [ProjectConfig(
plane_project_id=ORCH_PLANE_ID, repo="orchestrator",
work_item_prefix="ORCH", name="orchestrator",
agent_efforts=agent_efforts,
)]
monkeypatch.setattr(P, "PROJECTS", reg)
monkeypatch.setattr(P, "_BY_PLANE_ID", {p.plane_project_id: p for p in reg})
monkeypatch.setattr(P, "_BY_REPO", {p.repo: p for p in reg})
# ---- default split ----------------------------------------------------------
def test_default_split():
assert resolve_agent_effort("developer") == "high"
assert resolve_agent_effort("architect") == "high"
assert resolve_agent_effort("tester") == "medium"
assert resolve_agent_effort("deployer") == "medium"
# ---- level 4: nothing -> "" -------------------------------------------------
def test_no_config_returns_empty(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_default", "")
monkeypatch.setattr(settings, "agent_effort_tester", "")
assert resolve_agent_effort("tester") == ""
# ---- level 2: per-agent env beats default -----------------------------------
def test_per_agent_env(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_tester", "low")
assert resolve_agent_effort("tester") == "low"
# ---- level 1: project override wins -----------------------------------------
def test_project_override(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_developer", "high")
_install_registry(monkeypatch, {"developer": "xhigh"})
assert resolve_agent_effort("developer", ORCH_PLANE_ID) == "xhigh"
assert resolve_agent_effort("developer") == "high"
# ---- validation: invalid value dropped --------------------------------------
def test_invalid_default_dropped(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_developer", "")
monkeypatch.setattr(settings, "agent_effort_default", "turbo")
assert resolve_agent_effort("developer") == ""
def test_invalid_env_dropped(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_reviewer", "ultra")
assert resolve_agent_effort("reviewer") == ""
def test_invalid_project_override_dropped(monkeypatch):
_install_registry(monkeypatch, {"developer": "bogus"})
assert resolve_agent_effort("developer", ORCH_PLANE_ID) == ""
def test_all_valid_efforts_pass(monkeypatch):
monkeypatch.setattr(settings, "agent_effort_developer", "")
for e in VALID_EFFORTS:
monkeypatch.setattr(settings, "agent_effort_default", e)
assert resolve_agent_effort("developer") == e
# ---- flag assembly (mirror of launcher cmd construction) --------------------
def _build_flags(model, effort, fb):
model_flag = f"--model {model} " if model else ""
effort_flag = f"--effort {effort} " if effort else ""
fb_flag = f"--fallback-model {fb} " if fb else ""
return f"{model_flag}{effort_flag}{fb_flag}"
def test_flags_present_when_configured(monkeypatch):
monkeypatch.setattr(settings, "agent_fallback_model", "claude-sonnet-4-6")
model = resolve_agent_model("developer")
effort = resolve_agent_effort("developer")
fb = settings.agent_fallback_model
flags = _build_flags(model, effort, fb)
assert "--model claude-opus-4-8 " in flags
assert "--effort high " in flags
assert "--fallback-model claude-sonnet-4-6 " in flags
def test_flags_absent_when_empty(monkeypatch):
monkeypatch.setattr(settings, "agent_model_default", "")
monkeypatch.setattr(settings, "agent_model_developer", "")
monkeypatch.setattr(settings, "agent_effort_default", "")
monkeypatch.setattr(settings, "agent_effort_developer", "")
monkeypatch.setattr(settings, "agent_fallback_model", "")
model = resolve_agent_model("developer")
effort = resolve_agent_effort("developer")
fb = settings.agent_fallback_model
flags = _build_flags(model, effort, fb)
assert flags == ""
assert "--model" not in flags
assert "--effort" not in flags
assert "--fallback-model" not in flags

View File

@@ -1,156 +0,0 @@
"""ORCH-41: tests for resolve_agent_model (per-agent + per-project LLM model).
Covers the 4-level resolution priority:
1. ProjectConfig.agent_models[agent] (per-project override, from projects_json)
2. settings.agent_model_<agent> (per-agent env, when non-empty)
3. settings.agent_model_default (global default)
4. "" (no override anywhere -> CLI default)
plus: unknown project_id / no project_id skips level 1, unknown agent skips
level 2, and the frozen ProjectConfig still accepts agent_models (default {}).
We never mutate the module-global registry permanently: tests that need a
custom registry install one via monkeypatch + reload_projects and restore the
default afterwards (autouse fixture).
"""
import os
import tempfile
import pytest
os.environ.setdefault("ORCH_DB_PATH",
os.path.join(tempfile.gettempdir(), "test_orch41_model.db"))
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
from src.agents.launcher import resolve_agent_model
from src.config import settings
from src import projects as P
from src.projects import ProjectConfig, reload_projects, _parse_projects_json
ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
@pytest.fixture(autouse=True)
def _clean_settings(monkeypatch):
"""Reset all per-agent/default model settings to a known baseline so tests
are order-independent regardless of what other modules set in the env."""
monkeypatch.setattr(settings, "agent_model_default", "claude-opus-4-8")
for a in ("analyst", "architect", "developer", "reviewer", "tester", "deployer"):
monkeypatch.setattr(settings, f"agent_model_{a}", "")
# default registry (no per-project overrides)
monkeypatch.setattr(P.settings, "projects_json", "")
reload_projects()
yield
reload_projects()
def _install_registry(monkeypatch, agent_models):
"""Install a single-project registry for ORCH with the given agent_models."""
reg = [ProjectConfig(
plane_project_id=ORCH_PLANE_ID, repo="orchestrator",
work_item_prefix="ORCH", name="orchestrator",
agent_models=agent_models,
)]
monkeypatch.setattr(P, "PROJECTS", reg)
monkeypatch.setattr(P, "_BY_PLANE_ID", {p.plane_project_id: p for p in reg})
monkeypatch.setattr(P, "_BY_REPO", {p.repo: p for p in reg})
# ---- Level 4: nothing configured -> "" --------------------------------------
def test_no_config_returns_empty(monkeypatch):
monkeypatch.setattr(settings, "agent_model_default", "")
assert resolve_agent_model("developer") == ""
assert resolve_agent_model("developer", ORCH_PLANE_ID) == ""
# ---- Level 3: global default ------------------------------------------------
def test_global_default():
assert resolve_agent_model("developer") == "claude-opus-4-8"
assert resolve_agent_model("architect") == "claude-opus-4-8"
# ---- Level 2: per-agent env beats default -----------------------------------
def test_per_agent_env_overrides_default(monkeypatch):
monkeypatch.setattr(settings, "agent_model_reviewer", "claude-sonnet-4-6")
assert resolve_agent_model("reviewer") == "claude-sonnet-4-6"
# other agents still fall through to default
assert resolve_agent_model("developer") == "claude-opus-4-8"
# ---- Level 1: per-project override beats per-agent env and default ----------
def test_project_override_beats_env_and_default(monkeypatch):
monkeypatch.setattr(settings, "agent_model_developer", "claude-sonnet-4-6")
_install_registry(monkeypatch, {"developer": "claude-opus-4-8"})
assert resolve_agent_model("developer", ORCH_PLANE_ID) == "claude-opus-4-8"
# without project_id, falls back to per-agent env
assert resolve_agent_model("developer") == "claude-sonnet-4-6"
def test_project_override_only_for_listed_agent(monkeypatch):
_install_registry(monkeypatch, {"developer": "claude-opus-4-8"})
# reviewer not in agent_models -> falls back to default
assert resolve_agent_model("reviewer", ORCH_PLANE_ID) == "claude-opus-4-8"
monkeypatch.setattr(settings, "agent_model_reviewer", "claude-sonnet-4-6")
assert resolve_agent_model("reviewer", ORCH_PLANE_ID) == "claude-sonnet-4-6"
# ---- unknown / empty project id skips level 1 -------------------------------
def test_unknown_project_id_skips_override(monkeypatch):
_install_registry(monkeypatch, {"developer": "x-model"})
assert resolve_agent_model("developer", "no-such-uuid") == "claude-opus-4-8"
assert resolve_agent_model("developer", None) == "claude-opus-4-8"
# ---- unknown agent skips per-agent env, still gets default ------------------
def test_unknown_agent_falls_to_default():
assert resolve_agent_model("nonexistent") == "claude-opus-4-8"
# ---- frozen ProjectConfig accepts agent_models ------------------------------
def test_projectconfig_frozen_with_agent_models():
pc = ProjectConfig(
plane_project_id="x", repo="r", work_item_prefix="P", name="n",
agent_models={"developer": "m"},
)
assert pc.agent_models == {"developer": "m"}
# default is an empty dict, not shared/mutable across instances
pc2 = ProjectConfig(plane_project_id="y", repo="r2",
work_item_prefix="P2", name="n2")
assert pc2.agent_models == {}
assert pc2.agent_models is not pc.agent_models
with pytest.raises(Exception):
pc.repo = "changed" # frozen
# ---- projects_json parsing of agent_models / agent_efforts ------------------
def test_parse_projects_json_with_overrides():
raw = (
'[{"plane_project_id":"p1","repo":"orchestrator",'
'"work_item_prefix":"ORCH",'
'"agent_models":{"developer":"claude-opus-4-8","reviewer":"claude-sonnet-4-6"},'
'"agent_efforts":{"developer":"xhigh","tester":"low"}}]'
)
parsed = _parse_projects_json(raw)
assert parsed is not None and len(parsed) == 1
pc = parsed[0]
assert pc.agent_models == {"developer": "claude-opus-4-8",
"reviewer": "claude-sonnet-4-6"}
assert pc.agent_efforts == {"developer": "xhigh", "tester": "low"}
def test_parse_projects_json_omitted_overrides_default_empty():
raw = ('[{"plane_project_id":"p1","repo":"r","work_item_prefix":"P"}]')
parsed = _parse_projects_json(raw)
assert parsed is not None and len(parsed) == 1
assert parsed[0].agent_models == {}
assert parsed[0].agent_efforts == {}
def test_parse_projects_json_malformed_override_ignored():
# agent_models is not an object -> dropped to {}, entry still valid
raw = ('[{"plane_project_id":"p1","repo":"r","work_item_prefix":"P",'
'"agent_models":"oops"}]')
parsed = _parse_projects_json(raw)
assert parsed is not None and parsed[0].agent_models == {}

View File

@@ -1,237 +0,0 @@
"""Unit tests for src/review_parse (ORCH-046).
Covers the defensive extractors that pull verbatim must-fix text out of the
reviewer / tester artifacts for embedding into the rollback ``task_desc``:
- extract_review_findings (12-review.md, ## Findings -> P0/P1)
- extract_test_failures (13-test-report.md, pytest/FAIL/Итог excerpt)
Both must NEVER raise (return "" on missing/broken/empty input) and must ignore
template placeholders / non-must-fix severities. See 04-test-plan.yaml (TC-01..08).
"""
import os
import tempfile
import pytest
from src.review_parse import (
extract_review_findings,
extract_test_failures,
MAX_FINDINGS_CHARS,
MAX_FAILURES_CHARS,
)
@pytest.fixture
def write_file(tmp_path):
def _w(name: str, content: str) -> str:
p = tmp_path / name
p.write_text(content, encoding="utf-8")
return str(p)
return _w
# ---------------------------------------------------------------------------
# extract_review_findings
# ---------------------------------------------------------------------------
_REVIEW_WITH_FINDINGS = """---
type: review
work_item_id: ORCH-046
verdict: REQUEST_CHANGES
version: 1
---
# Review ORCH-046
## Summary
Несколько проблем.
## Findings
### P0 — Blocker
- [ ] Документация не обновлена при изменении src/review_parse.py
### P1 — Must fix
- [ ] extract_test_failures не обрабатывает пустой отчёт
- [ ] Отсутствует docstring у _section_body
### P2 — Should fix
- [ ] Переименовать переменную blocks в more descriptive
## Документация
Требует обновления README.
"""
class TestExtractReviewFindings:
def test_tc01_returns_verbatim_p0_p1(self, write_file):
"""TC-01: P0/P1 findings present -> verbatim text returned (AC-1, AC-5)."""
path = write_file("12-review.md", _REVIEW_WITH_FINDINGS)
out = extract_review_findings(path)
# P0 + P1 verbatim items present.
assert "Документация не обновлена при изменении src/review_parse.py" in out
assert "extract_test_failures не обрабатывает пустой отчёт" in out
assert "Отсутствует docstring у _section_body" in out
# Subsection headers preserved.
assert "P0" in out and "P1" in out
# P2 must NOT leak in.
assert "Переименовать переменную" not in out
def test_tc02_only_p2_p3_returns_empty(self, write_file):
"""TC-02: only P2/P3 (no must-fix P0/P1) -> '' (AC-5)."""
content = """---
verdict: REQUEST_CHANGES
---
## Findings
### P0 — Blocker
- [ ] <описание> (если есть)
### P1 — Must fix
- [ ] <описание> (если есть)
### P2 — Should fix
- [ ] Косметика в naming
"""
path = write_file("12-review.md", content)
assert extract_review_findings(path) == ""
def test_tc03_missing_file_returns_empty(self):
"""TC-03: non-existent path -> '' without raising (AC-4)."""
missing = os.path.join(tempfile.gettempdir(), "no-such-review-orch046.md")
assert extract_review_findings(missing) == ""
def test_tc04_broken_or_no_findings_section_returns_empty(self, write_file):
"""TC-04: empty file / markdown without ## Findings -> '' (AC-4, AC-5)."""
# Empty file.
assert extract_review_findings(write_file("empty.md", "")) == ""
# No Findings section.
no_section = "# Review\n\n## Summary\nвсё хорошо\n"
assert extract_review_findings(write_file("nofind.md", no_section)) == ""
# Broken YAML frontmatter (unterminated) — body parsing still graceful.
broken = "---\nverdict: [unclosed\n# Review\nno findings here\n"
assert extract_review_findings(write_file("broken.md", broken)) == ""
def test_tc05_long_findings_truncated(self, write_file):
"""TC-05: very long findings truncated to limit with marker (AC-1)."""
big_item = "- [ ] " + ("x" * 5000)
content = f"## Findings\n\n### P0 — Blocker\n{big_item}\n"
path = write_file("12-review.md", content)
out = extract_review_findings(path)
assert len(out) <= MAX_FINDINGS_CHARS + len("\n…(truncated)")
assert "…(truncated)" in out
def test_case_insensitive_and_dash_tolerant_header(self, write_file):
"""P0/P1 recognized regardless of case / dash style."""
content = """## Findings
### p0 - blocker
- [ ] Нижний регистр заголовка
### P1 — Must fix
- [ ] Em-dash заголовок
"""
out = extract_review_findings(write_file("12-review.md", content))
assert "Нижний регистр заголовка" in out
assert "Em-dash заголовок" in out
def test_never_raises_on_directory_path(self, tmp_path):
"""Passing a directory path must not raise -> ''."""
assert extract_review_findings(str(tmp_path)) == ""
# ---------------------------------------------------------------------------
# extract_test_failures
# ---------------------------------------------------------------------------
_REPORT_FAIL = """---
type: test-report
work_item_id: ORCH-046
result: FAIL
---
# Test Report — ORCH-046
## Окружение
- Python: 3.12
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-01 | парсер findings | PASS |
| TC-09 | rollback task_desc | FAIL |
## Вывод pytest
FAILED tests/test_stage_engine.py::TestReviewerRequestChanges::test_embed - AssertionError
1 failed, 40 passed in 2.13s
## Итог
FAIL
"""
class TestExtractTestFailures:
def test_tc06_extracts_pytest_output(self, write_file):
"""TC-06: relevant body excerpt (pytest output) from FAIL report (AC-2, AC-5)."""
path = write_file("13-test-report.md", _REPORT_FAIL)
out = extract_test_failures(path)
assert "FAILED tests/test_stage_engine.py" in out
assert "1 failed, 40 passed" in out
def test_priority_falls_back_to_fail_rows(self, write_file):
"""No pytest section -> FAIL rows of the results table are used."""
content = """---
result: FAIL
---
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-01 | ok | PASS |
| TC-09 | broken | FAIL |
## Итог
FAIL
"""
out = extract_test_failures(write_file("13-test-report.md", content))
assert "TC-09" in out
assert "broken" in out
# PASS rows are not failure-relevant.
assert "TC-01" not in out
def test_priority_falls_back_to_itog(self, write_file):
"""No pytest section and no FAIL rows -> Итог summary is used."""
content = """---
result: FAIL
---
## Итог
Регресс упал: смотрите CI лог.
"""
out = extract_test_failures(write_file("13-test-report.md", content))
assert "Регресс упал" in out
def test_tc07_missing_file_returns_empty(self):
"""TC-07: non-existent path -> '' without raising (AC-4)."""
missing = os.path.join(tempfile.gettempdir(), "no-such-report-orch046.md")
assert extract_test_failures(missing) == ""
def test_tc08_broken_or_empty_report_returns_empty(self, write_file):
"""TC-08: empty / section-less report -> '' without raising (AC-4, AC-5)."""
assert extract_test_failures(write_file("empty.md", "")) == ""
no_sections = "---\nresult: FAIL\n---\n\n# Test Report\nничего полезного\n"
assert extract_test_failures(write_file("nosec.md", no_sections)) == ""
def test_long_failures_truncated(self, write_file):
"""Long pytest output is truncated to the limit with a marker."""
big = "x" * 5000
content = f"## Вывод pytest\n{big}\n"
out = extract_test_failures(write_file("13-test-report.md", content))
assert len(out) <= MAX_FAILURES_CHARS + len("\n…(truncated)")
assert "…(truncated)" in out
def test_never_raises_on_directory_path(self, tmp_path):
assert extract_test_failures(str(tmp_path)) == ""

View File

@@ -101,14 +101,6 @@ def _jobs():
return [dict(r) for r in rows] return [dict(r) for r in rows]
def _job_contents():
"""task_content of every enqueued job, oldest first (ORCH-046 task_desc check)."""
conn = get_db()
rows = conn.execute("SELECT task_content FROM jobs ORDER BY id").fetchall()
conn.close()
return [r[0] for r in rows]
def _add_developer_runs(task_id, n): def _add_developer_runs(task_id, n):
conn = get_db() conn = get_db()
for _ in range(n): for _ in range(n):
@@ -343,179 +335,6 @@ class TestTesterFail:
assert _jobs() == [] assert _jobs() == []
# ---------------------------------------------------------------------------
# ORCH-046: rollback task_desc carries verbatim reviewer/tester must-fix text
# ---------------------------------------------------------------------------
_REVIEW_MD = """---
type: review
work_item_id: ET-001
verdict: REQUEST_CHANGES
version: 1
---
# Review ET-001
## Summary
Есть блокеры.
## Findings
### P0 — Blocker
- [ ] Гонка в claim_next_job: отсутствует guard в WHERE
### P1 — Must fix
- [ ] Нет обработки OSError при чтении отчёта
### P2 — Should fix
- [ ] Переименовать blocks
"""
_REPORT_MD = """---
type: test-report
work_item_id: ET-001
result: FAIL
---
# Test Report — ET-001
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-09 | rollback | FAIL |
## Вывод pytest
FAILED tests/test_stage_engine.py::TestTaskDescEmbedding - AssertionError
1 failed, 50 passed in 3.01s
## Итог
FAIL
"""
class TestRollbackTaskDescEmbedding:
"""ORCH-046 AC-1/AC-2/AC-3/AC-4: the rollback task_desc embeds verbatim
must-fix text (reviewer P0/P1, tester reason + report excerpt) plus the link.
"""
def _patch_worktree(self, monkeypatch, tmp_path, work_item_id, filename, body):
"""Make get_worktree_path resolve to tmp_path and seed the artifact file."""
artifact = tmp_path / "docs" / "work-items" / work_item_id
artifact.mkdir(parents=True, exist_ok=True)
(artifact / filename).write_text(body, encoding="utf-8")
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
def test_tc09_reviewer_embeds_p0_p1_and_link(self, monkeypatch, tmp_path):
"""TC-09: reviewer REQUEST_CHANGES -> task_desc has verbatim P0/P1 + link."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
self._patch_worktree(monkeypatch, tmp_path, "ET-001", "12-review.md", _REVIEW_MD)
task_id = _make_task("review")
advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# AC-1: verbatim P0/P1 findings.
assert "Гонка в claim_next_job: отсутствует guard в WHERE" in desc
assert "Нет обработки OSError при чтении отчёта" in desc
# P2 must not leak.
assert "Переименовать blocks" not in desc
# AC-3: link to full file preserved.
assert "docs/work-items/ET-001/12-review.md" in desc
def test_tc10_tester_embeds_reason_excerpt_and_link(self, monkeypatch, tmp_path):
"""TC-10: tester FAIL -> task_desc has reason + report excerpt + link."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_tests_passed": _fail("1 test failed")},
)
self._patch_worktree(
monkeypatch, tmp_path, "ET-001", "13-test-report.md", _REPORT_MD
)
task_id = _make_task("testing")
advance_stage(task_id, "testing", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="tester")
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# AC-2: gate reason present.
assert "1 test failed" in desc
# AC-2: report body excerpt (pytest output) present.
assert "FAILED tests/test_stage_engine.py::TestTaskDescEmbedding" in desc
# AC-3: link to full file preserved.
assert "docs/work-items/ET-001/13-test-report.md" in desc
def test_tc11_reviewer_graceful_fallback_when_no_file(self, monkeypatch, tmp_path):
"""TC-11: missing/broken 12-review.md -> graceful link-only fallback (AC-4)."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
# Worktree resolves but the review file does not exist.
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
task_id = _make_task("review")
res = advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
# Rollback still happens exactly as before.
assert res.rolled_back_to == "development"
assert _stage(task_id) == "development"
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# Falls back to the previous link-string behavior (no findings block).
assert "Fix findings in docs/work-items/ET-001/12-review.md" in desc
assert "Findings (P0/P1):" not in desc
def test_tc11_tester_graceful_fallback_keeps_reason(self, monkeypatch, tmp_path):
"""AC-2/AC-4: missing report -> reason still present, link fallback."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_tests_passed": _fail("2 tests failed")},
)
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
task_id = _make_task("testing")
advance_stage(task_id, "testing", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="tester")
desc = _job_contents()[0]
assert "2 tests failed" in desc
assert "docs/work-items/ET-001/13-test-report.md" in desc
def test_tc12_retry_and_rollback_behavior_unchanged(self, monkeypatch, tmp_path):
"""TC-12 (AC-6): embedding does not change retry/rollback semantics.
4th developer attempt still alerts instead of enqueueing, even with a
valid review file present.
"""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
self._patch_worktree(monkeypatch, tmp_path, "ET-001", "12-review.md", _REVIEW_MD)
task_id = _make_task("review")
_add_developer_runs(task_id, 3) # already at the cap
res = advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
assert res.rolled_back_to == "development"
assert res.alerted is True
assert stage_engine.send_telegram.called
# No new developer job past the cap, regardless of embedding.
assert _jobs() == []
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# BUG 8: deploy verdict gates deploy -> done (not the LLM exit code) # BUG 8: deploy verdict gates deploy -> done (not the LLM exit code)
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------

Some files were not shown because too many files have changed in this diff Show More