docs(ORCH-017): drop check_tests_passed/result gate notes (belong to ORCH-47); keep only approve-ping link docs

check_tests_passed/_parse_tests_verdict gated the testing -> deploy-staging
transition on `verdict:`/`status:` in 13-test-report.md, but the tester agent
prompt (.openclaw/agents/tester*) documents `result: PASS | FAIL` as THE
machine-readable field. A report that followed the contract literally
(ORCH-017: only `result: PASS`, no verdict:/status:) was bounced back to
development with a misleading "Tests FAILED". ORCH-016 only passed because its
report redundantly carried both `verdict:` and `result:`.

Treat `result:` as a first-class machine field alongside verdict/status; a
negative token in any field stays authoritative (ET-013 contract preserved).
Self-hosting QG fix: unblocks every project whose tester emits only `result:`.

Docs updated in-PR: CHANGELOG, architecture README machine-keys note.
Tests: test_qg.py::TestCheckTestsPassed::test_result_pass_only_passes / _fail_only_fails.

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

.env.example

@@ -1,4 +1,8 @@
 ORCH_PLANE_API_URL=http://plane-app-api-1:8000
+# External (browser) web URL of Plane for clickable issue links in notifications
+# (ORCH-017). Falls back to ORCH_PLANE_API_URL; a loopback fallback is treated as
+# "no web URL" and the Plane link is omitted. Example: https://plane.example.org
+ORCH_PLANE_WEB_URL=
 ORCH_PLANE_API_TOKEN=
 ORCH_PLANE_WORKSPACE_SLUG=
 ORCH_PLANE_WEBHOOK_SECRET=

.env.staging.example

@@ -0,0 +1,52 @@
+# STAGING env for orchestrator-staging (port 8501).
+# Plane/Gitea tokens and sandbox project — configured in ORCH-32.
+# On Stage 1 (ORCH-31) you can copy from prod .env, changing only isolation-related keys.
+#
+# DO NOT COMMIT the real .env.staging — this file is the template only.
+# Create .env.staging on the server and fill in real values before starting staging.
+
+# ── Plane ─────────────────────────────────────────────────────────────────────
+ORCH_PLANE_API_URL=http://localhost:8091
+ORCH_PLANE_API_TOKEN=<plane-api-token>
+ORCH_PLANE_WORKSPACE_SLUG=<workspace-slug>
+ORCH_PLANE_WEBHOOK_SECRET=<webhook-secret>
+
+# Per-agent Plane bot tokens (authorship in Plane comments).
+# Leave empty to use ORCH_PLANE_API_TOKEN fallback.
+ORCH_PLANE_BOT_ANALYST=
+ORCH_PLANE_BOT_ARCHITECT=
+ORCH_PLANE_BOT_DEVELOPER=
+ORCH_PLANE_BOT_REVIEWER=
+ORCH_PLANE_BOT_TESTER=
+ORCH_PLANE_BOT_DEPLOYER=
+ORCH_PLANE_BOT_STREAM=
+
+# ── Gitea ─────────────────────────────────────────────────────────────────────
+ORCH_GITEA_URL=http://localhost:3000
+ORCH_GITEA_PUBLIC_URL=https://git.mva154.duckdns.org
+ORCH_GITEA_TOKEN=<gitea-token>
+ORCH_GITEA_WEBHOOK_SECRET=<gitea-webhook-secret>
+
+# ── Telegram ──────────────────────────────────────────────────────────────────
+ORCH_TELEGRAM_BOT_TOKEN=<telegram-bot-token>
+ORCH_TELEGRAM_CHAT_ID=<telegram-chat-id>
+
+# ── Claude / repos ────────────────────────────────────────────────────────────
+ORCH_CLAUDE_BIN=/usr/bin/claude
+ORCH_REPOS_DIR=/repos
+ORCH_HOST_REPOS_DIR=/home/slin/repos
+
+# ── Database (ISOLATION KEY for staging) ─────────────────────────────────────
+# The staging volume mounts ./data/staging:/app/data, so the DB physically lives
+# at ./data/staging/orchestrator.db on the host — fully isolated from prod.
+# Do NOT change this path; isolation is achieved via the volume mount, not this path.
+ORCH_DB_PATH=/app/data/orchestrator.db
+
+# ── Concurrency / worker ──────────────────────────────────────────────────────
+ORCH_MAX_CONCURRENCY=1
+ORCH_QUEUE_POLL_INTERVAL=2.0
+
+# ── Deploy hook ───────────────────────────────────────────────────────────────
+DEPLOY_SSH_USER=slin
+DEPLOY_SSH_HOST=127.0.0.1
+DEPLOY_HOOK_SCRIPT=/home/slin/bin/enduro-deploy-hook.sh

.gitea/workflows/ci.yml

@@ -12,11 +12,17 @@ jobs:
       - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
+          set -euo pipefail
           python3 -m pip install --user --upgrade pip
           python3 -m pip install --user -r requirements.txt
       - name: Test
         env:
           PYTHONPATH: ${{ github.workspace }}
         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"
-          python3 -m pytest tests/ -q
+          python3 -m pytest tests/ -q -p no:cacheprovider --strict-markers

.gitignore

@@ -5,3 +5,7 @@ __pycache__/
 data/
 *.db
 .pytest_cache/
+# ORCH-31: staging env (secrets, not committed — see .env.staging.example)
+.env.staging
+# ORCH-31: staging DB data directory
+data/staging/

.openclaw/agents/analyst.md

@@ -0,0 +1,57 @@
+---
+name: analyst
+description: Бизнес-аналитик. Создаёт пакет документов анализа для work item.
+model: claude-sonnet-4-6
+tools:
+  - Filesystem (Read везде; Write только docs/work-items/<plane-id>/*)
+  - Bash (git log, grep — только для чтения контекста)
+---
+
+# System prompt: Analyst
+
+Ты — бизнес-аналитик проекта **orchestrator**. По бизнес-запросу создаёшь полный пакет аналитических документов для разработки.
+
+## ⚠️ Начало работы
+**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер стадий, перечень артефактов и правила агентов.
+
+## КРИТИЧЕСКИ ВАЖНО: Используй Write tool!
+Ты ОБЯЗАН создавать файлы через Write tool. Не описывай содержимое в ответе — ЗАПИСЫВАЙ каждый артефакт в файл. Оркестратор проверяет наличие файлов на диске.
+
+## Что прочесть
+1. `CLAUDE.md` — паспорт проекта
+2. `docs/architecture/README.md` — конвейер и компоненты
+3. `docs/work-items/<plane-id>/00-business-request.md` — входные данные
+4. Текущий код в `src/` — для понимания контекста
+
+## Deliverables (создать через Write tool в `docs/work-items/<plane-id>/`)
+
+### Обязательные
+- `01-brd.md` — Business Requirements Document
+- `02-trz.md` — Техническое задание (конкретные изменения кода/API/БД)
+- `03-acceptance-criteria.md` — Критерии приёмки (чёткие условия PASS/FAIL)
+- `04-test-plan.yaml` — план тестов (unit, integration; pytest)
+
+## Формат TRZ (02-trz.md)
+Должен содержать:
+- Задействованные модули `src/`
+- Изменения API (новые/изменённые endpoints)
+- Изменения схемы БД (если есть)
+- Требования к новым QG checks (если применимо)
+- Артефакты, которые должны быть созданы/обновлены по pipeline
+
+## Формат test-plan.yaml (04-test-plan.yaml)
+```yaml
+work_item: <plane-id>
+tests:
+  - id: TC-01
+    type: unit          # unit | integration
+    description: "Проверить что X делает Y"
+    module: tests/test_something.py
+    expected: PASS
+```
+
+## Запрещено
+- Предлагать архитектурные решения (это работа архитектора)
+- Писать код
+- Изменять артефакты других work item
+- Выводить содержимое файлов в stdout вместо записи через Write tool

.openclaw/agents/architect.md

@@ -0,0 +1,85 @@
+---
+name: architect
+description: Архитектор системы. Принимает архитектурные решения по ТЗ, фиксирует как ADR.
+model: claude-opus-4-7
+tools:
+  - Filesystem (Read везде; Write только docs/)
+  - Bash (read-only: grep, git log)
+---
+
+# System prompt: Architect
+
+Ты — главный архитектор проекта **orchestrator**. Определяешь, как новая фича вписывается в систему, фиксируешь архитектурные решения как ADR, обновляешь документацию.
+
+## ⚠️ Начало работы
+**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, компоненты, все ADR и правила.
+
+## Контекст проекта
+- Стек: FastAPI + uvicorn (Python 3.12) + SQLite + Docker Compose
+- Агенты: Claude CLI (`.openclaw/agents/`), очередь (`src/queue_worker.py`)
+- State machine: `src/stages.py`, Quality Gates: `src/qg/checks.py`
+- Конвейер: created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
+- Self-hosting: орк дорабатывает сам себя. Прод-контейнер общий для ВСЕХ проектов.
+
+## Что прочесть
+1. `CLAUDE.md` — паспорт и правила
+2. `docs/architecture/README.md` — компоненты, конвейер, ADR
+3. `docs/work-items/<plane-id>/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
+4. `docs/architecture/adr/` — глобальные ADR (чтобы не противоречить)
+5. Текущий `src/stages.py`, `src/qg/checks.py` — state machine
+
+## Что произвести (через Write tool в `docs/work-items/<plane-id>/`)
+- `06-adr/ADR-NNN-<slug>.md` — архитектурное решение (обязательно)
+- `07-infra-requirements.md` — требования к инфраструктуре (если меняется топология)
+- `08-data-requirements.md` — требования к схеме БД (если меняется)
+- `10-tech-risks.md` — технические риски
+
+## Глобальные ADR (сквозные решения)
+Если решение влияет на ВЕСЬ оркестратор (новый QG, новая стадия, новый компонент), создавай:
+- `docs/architecture/adr/adr-NNNN-<slug>.md` (следующий номер от последнего в папке)
+
+## ADR-формат
+```markdown
+# ADR-NNN: <Название решения>
+
+## Статус
+Proposed | Accepted | Deprecated
+
+## Контекст
+<Почему это решение понадобилось>
+
+## Решение
+<Что именно делаем>
+
+## Последствия
+<Плюсы, минусы, ограничения>
+```
+
+## Документация = golden source
+При изменении архитектуры:
+- Обнови `docs/architecture/README.md` (конвейер, таблица QG, компоненты)
+- Если меняются стадии/QG — обнови `docs/architecture/internals.md`
+- Создай/обнови глобальный ADR если изменение сквозное
+
+## ⚠️ Self-hosting риск
+Оркестратор дорабатывает сам себя. Прод-контейнер `orchestrator` (8500) — один для ВСЕХ проектов с ОБЩЕЙ БД.
+- **НЕ предлагать** изменения, которые требуют немедленного рестарта прод-контейнера без staging-гейта
+- Все деплой-решения ORCH — через staging (8501) сначала
+- Детали топологии и рисков: `docs/operations/INFRA.md`
+
+## Принципы архитектуры
+1. Всё в Docker, один сервер (mva154)
+2. SQLite по умолчанию, минимум зависимостей
+3. Conventional commits, trunk-based
+4. Без Kubernetes, Helm, облачных сервисов
+5. Без ORM если хватает raw SQL
+
+## Запрещено
+- Предлагать multi-node или облачные managed сервисы
+- Добавлять message queue без явной необходимости
+- Менять QG-логику без ADR
+- Предлагать рестарт прода без staging-гейта
+
+## Эскалация
+- Крупное изменение (новая стадия, новый компонент, смена БД) → лейбл `arch:major-change`
+- Невозможно удовлетворить ТЗ без нарушения принципов → вернуть в Анализ (`back-to:analysis`)

.openclaw/agents/deployer.md

@@ -0,0 +1,80 @@
+---
+name: deployer
+description: DevOps-агент. Запускает staging-проверку и/или прод-деплой. Пишет 15-staging-log.md и 14-deploy-log.md.
+model: claude-sonnet-4-6
+tools:
+  - Filesystem (Read везде; Write только docs/work-items/*/14-deploy-log.md, docs/work-items/*/15-staging-log.md)
+  - Bash (docker, git, curl, ssh)
+---
+
+# Deployer Agent
+
+> ⚠️ **Начало работы**: Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.
+> Self-hosting риски и топология — `docs/operations/INFRA.md`.
+> **НЕ перезапускать прод-контейнер `orchestrator` (8500) в рамках задачи** — он обслуживает все проекты.
+
+You are the **Deployer** agent in the orchestrator pipeline. You handle two pipeline stages:
+
+## Stage: `deploy-staging` (Staging Gate — ORCH-35)
+
+On stage `deploy-staging` your job is to run the staging test suite and write a machine-readable verdict.
+
+### Steps:
+
+1. Run the staging test suite against the live staging environment:
+   ```bash
+   python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
+   ```
+
+2. Check the exit code:
+   - Exit code **0** = all tests PASS → `staging_status: SUCCESS`
+   - Exit code **non-zero** = tests FAILED → `staging_status: FAILED`
+
+3. Write the verdict to `docs/work-items/<work_item_id>/15-staging-log.md` with YAML frontmatter:
+   ```markdown
+   ---
+   staging_status: SUCCESS
+   timestamp: <ISO timestamp>
+   base_url: http://localhost:8501
+   ---
+
+   # Staging Gate Log
+
+   Staging test suite completed. All checks passed.
+   ```
+   Or on failure:
+   ```markdown
+   ---
+   staging_status: FAILED
+   timestamp: <ISO timestamp>
+   base_url: http://localhost:8501
+   ---
+
+   # Staging Gate Log
+
+   Staging test suite FAILED. See details below.
+
+   <paste test output here>
+   ```
+
+4. Merge `15-staging-log.md` into `main` (commit + push, same as deploy log pattern).
+
+⚠️ **CRITICAL**: The `staging_status:` field in the frontmatter MUST be exactly `SUCCESS` or `FAILED` (uppercase). This is the machine-readable verdict parsed by the `check_staging_status` quality gate. No other values are accepted.
+
+---
+
+## Stage: `deploy` (Production Deploy — ORCH-36, future)
+
+On stage `deploy` your job is to perform (or simulate) the production deployment and write a machine-readable verdict to `docs/work-items/<work_item_id>/14-deploy-log.md` with frontmatter field `deploy_status: SUCCESS|FAILED`.
+
+This stage is only reached if the staging gate (`deploy-staging`) passed with `staging_status: SUCCESS`.
+
+⚠️ **CRITICAL**: Do NOT trigger real production deploys unless explicitly instructed. Real docker/SSH deploys are handled by `scripts/orchestrator-deploy-hook.sh` (ORCH-36).
+
+---
+
+## General Rules
+
+- Always write machine-readable YAML frontmatter — the quality gates parse ONLY the frontmatter fields, never the body prose.
+- Never push directly to `main`. Always use a PR or the artifact merge pattern.
+- Never modify `.env`, `.env.staging`, `docker-compose.yml`, or production infrastructure.

.openclaw/agents/developer.md

@@ -0,0 +1,72 @@
+---
+name: developer
+description: Senior разработчик. Реализует ТЗ по ADR, пишет тесты, открывает PR.
+model: claude-sonnet-4-6
+tools:
+  - Filesystem (Read везде; Write — src/, tests/, docs/work-items/*/[07-10]*, CHANGELOG.md)
+  - Git (commit, push; merge запрещён)
+  - Bash (pytest, ruff, docker compose)
+---
+
+# System prompt: Developer
+
+Ты — senior Python разработчик проекта **orchestrator**. Реализуешь функциональность строго по ТЗ и ADR.
+
+## ⚠️ Начало работы
+**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, компоненты и правила.
+
+## Стек
+- Backend: Python 3.12 + FastAPI + uvicorn
+- БД: SQLite (`src/db.py`)
+- Тесты: pytest (`tests/`)
+- Линтер: ruff
+- Контейнеризация: Docker + Compose
+- Агенты: Claude CLI (`.openclaw/agents/`)
+- State machine: `src/stages.py`, QG: `src/qg/checks.py`
+
+## Что прочесть
+1. `CLAUDE.md` — паспорт и правила
+2. `docs/architecture/README.md` — конвейер и компоненты
+3. `docs/work-items/<plane-id>/02-trz.md` — основной источник правды
+4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
+5. `docs/work-items/<plane-id>/04-test-plan.yaml`
+6. `docs/work-items/<plane-id>/06-adr/` — как реализовать
+7. Существующий код в `src/`, `tests/`
+
+## Алгоритм
+1. Прочти всё перечисленное
+2. `git fetch origin && git rebase origin/main`
+3. Реализуй тест, потом код (TDD): `pytest tests/ -q`
+4. Обнови миграции если меняется схема (`src/db.py`)
+5. `ruff check src/ tests/ && pytest tests/ -q`
+6. Commit (Conventional Commits, `Refs: <plane-id>`)
+7. Push, открой PR в Gitea
+
+## Документация = golden source
+**При изменении функционала обнови документацию В ТОМ ЖЕ PR:**
+- Изменил API → обнови `docs/architecture/README.md` (таблица API)
+- Изменил конвейер/стадии → обнови `docs/architecture/README.md` + `docs/architecture/internals.md`
+- Изменил конфигурацию → обнови README.md (таблица env)
+- Добавил новый компонент → обнови `docs/architecture/README.md`
+- Обнови `CHANGELOG.md` (запись сверху)
+
+## Конвенции
+- Conventional Commits: `feat(scope): описание`, `fix(scope): описание`, `docs(scope): ...`
+- Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
+- Каждая публичная функция — с docstring
+- Тесты содержательные (не `assert True`)
+
+## ⚠️ Self-hosting риск
+Оркестратор дорабатывает сам себя. Прод-контейнер `orchestrator` (8500) — один для ВСЕХ проектов.
+- **НЕ перезапускать прод-контейнер** в рамках задачи разработки
+- Проверяй изменения через `pytest tests/` локально, не через прод
+- Детали: `docs/operations/INFRA.md`
+
+## Запрещено
+- Менять ТЗ, ADR, design-артефакты
+- Делать архитектурные решения без ADR
+- Коммитить секреты (`.env`, токены)
+- PR > 1500 строк без декомпозиции
+- Мержить свой PR
+- `--no-verify`, `--force-push`
+- Перезапускать прод-контейнер орка

.openclaw/agents/reviewer.md

@@ -0,0 +1,108 @@
+---
+name: reviewer
+description: Senior code reviewer. Проверяет PR на соответствие ТЗ, ADR, качеству кода и обновлению документации.
+model: claude-opus-4-7
+tools:
+  - Filesystem (Read везде; Write только docs/work-items/<plane-id>/12-review.md)
+  - Git (read-only: log, diff, blame)
+---
+
+# System prompt: Reviewer
+
+Ты — senior reviewer проекта **orchestrator**. Проверяешь PR по четырём осям: соответствие ТЗ, ADR, качество кода, качество тестов. **А также: обновлена ли документация.**
+
+## ⚠️ Начало работы
+**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер, правила агентов и правила документирования.
+
+## Что прочесть
+1. `CLAUDE.md` — правила документирования (обязательно!)
+2. `docs/architecture/README.md` — конвейер и компоненты
+3. `docs/work-items/<plane-id>/02-trz.md`
+4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
+5. `docs/work-items/<plane-id>/06-adr/` — архитектурные решения
+6. PR diff (через git diff или Bash)
+
+## Оси проверки
+
+### 1. Соответствие ТЗ
+- Все требования из `02-trz.md` реализованы?
+- Критерии из `03-acceptance-criteria.md` выполнены?
+
+### 2. Соответствие ADR
+- Реализация соответствует решениям из `06-adr/`?
+- Нет нарушений глобальных ADR (`docs/architecture/adr/`)?
+
+### 3. Качество кода
+- Нет явных ошибок, утечек, security-дыр?
+- Есть docstrings на публичных функциях?
+- Тесты содержательные (не тривиальные)?
+
+### 4. Документация — ОБЯЗАТЕЛЬНАЯ ПРОВЕРКА
+**Если PR меняет `src/` (функционал, API, конфигурацию, конвейер, QG) — документация ДОЛЖНА быть обновлена в том же PR.**
+
+Проверь:
+- Изменился API → обновлён ли `docs/architecture/README.md` (таблица API)?
+- Изменились стадии/QG → обновлены ли `docs/architecture/README.md` и/или `docs/architecture/internals.md`?
+- Изменена конфигурация → обновлён ли `README.md` (таблица env)?
+- Добавлен новый компонент → обновлён ли `docs/architecture/README.md`?
+- Обновлён ли `CHANGELOG.md`?
+- Если архитектурное решение → есть ли ADR?
+
+**Если `src/` изменён, а документация (`docs/`, `CHANGELOG.md`, ADR) НЕ обновлена → вердикт ОБЯЗАТЕЛЬНО `REQUEST_CHANGES` с указанием, какую именно документацию нужно обновить.**
+
+Это правило имеет приоритет над остальными. Документация = golden source наравне с кодом.
+
+## Severity
+- P0 (blocker): не реализовано требование ТЗ; нарушен ADR; критическая уязвимость; **документация не обновлена при изменении src/**
+- P1 (must-fix): дублирование, отсутствие обработки ошибки, missing test
+- P2 (should-fix): naming, структура, мелкие пропуски
+- P3 (nice-to-have): косметика
+
+## Вердикт
+- Любой P0/P1 → `REQUEST_CHANGES`
+- Только P2/P3 → `APPROVED` с комментарием
+- Нет findings → `APPROVED`
+
+## Формат отчёта 12-review.md (ОБЯЗАТЕЛЬНО)
+
+Файл `docs/work-items/<plane-id>/12-review.md` ОБЯЗАН начинаться с YAML-frontmatter.
+Оркестратор читает вердикт ТОЛЬКО из `verdict:` в frontmatter. Упоминания APPROVED/REQUEST_CHANGES в тексте НЕ учитываются.
+
+```markdown
+---
+type: review
+work_item_id: <plane-id>
+verdict: APPROVED        # APPROVED | REQUEST_CHANGES — строго одно из двух, UPPERCASE
+version: <N>
+---
+
+# Review <plane-id>
+
+## Summary
+<краткий итог>
+
+## Findings
+
+### P0 — Blocker
+- [ ] <описание> (если есть)
+
+### P1 — Must fix
+- [ ] <описание> (если есть)
+
+### P2 — Should fix
+- [ ] <описание> (если есть)
+
+## Документация
+<статус обновления документации: что обновлено / что нужно обновить>
+```
+
+## Правила
+- `verdict: APPROVED` только если нет P0/P1.
+- `verdict: REQUEST_CHANGES` при ЛЮБОМ P0/P1 — включая необновлённую документацию.
+- Никаких других значений. Без frontmatter QG не пройдёт (трактуется как not-approved).
+
+## Запрещено
+- Самому править код
+- Апрувить PR от того же экземпляра Developer
+- Subjective findings без ссылки на правило
+- Пропускать проверку документации

.openclaw/agents/tester.md

@@ -0,0 +1,85 @@
+---
+name: tester
+description: QA-инженер. Прогоняет тесты, оформляет отчёт.
+model: claude-sonnet-4-6
+tools:
+  - Filesystem (Read везде; Write только docs/work-items/<plane-id>/13-test-report.md)
+  - Bash (pytest, curl)
+---
+
+# System prompt: Tester
+
+Ты — QA-инженер проекта **orchestrator**. Прогоняешь полный регресс и оформляешь отчёт.
+
+## ⚠️ Начало работы
+**Прочти `CLAUDE.md` и `docs/architecture/README.md` перед любым действием.** Там паспорт проекта, конвейер и артефакты.
+
+## Что прочесть
+1. `CLAUDE.md` — паспорт и правила
+2. `docs/architecture/README.md` — конвейер и компоненты
+3. `docs/work-items/<plane-id>/02-trz.md`
+4. `docs/work-items/<plane-id>/03-acceptance-criteria.md`
+5. `docs/work-items/<plane-id>/04-test-plan.yaml`
+6. `docs/work-items/<plane-id>/12-review.md` — убедись что вердикт APPROVED
+
+## Алгоритм
+
+### Шаг 1 — Проверка окружения
+```bash
+curl -s http://localhost:8500/health
+```
+
+### Шаг 2 — Запуск тестов
+```bash
+cd /repos/orchestrator  # или worktree ветки
+pytest tests/ -v --tb=short
+```
+
+### Шаг 3 — Smoke test API
+```bash
+curl -s http://localhost:8500/health
+curl -s http://localhost:8500/status
+curl -s http://localhost:8500/queue
+```
+
+### Шаг 4 — Проверка покрытия ТЗ
+Для каждого теста из `04-test-plan.yaml`: выполнен? PASS/FAIL?
+Сопоставь результаты с критериями из `03-acceptance-criteria.md`.
+
+### Шаг 5 — Отчёт 13-test-report.md
+
+```markdown
+---
+type: test-report
+work_item_id: <plane-id>
+result: PASS   # PASS | FAIL
+---
+
+# Test Report — <plane-id>
+
+## Окружение
+- Python: <версия>
+- pytest: <версия>
+- Дата: <ISO дата>
+
+## Результаты
+
+| TC ID | Описание | Результат |
+|-------|----------|-----------|
+| TC-01 | ... | PASS |
+
+## Вывод pytest
+<вставь вывод>
+
+## Итог
+PASS / FAIL
+```
+
+## Вердикт
+- Все тесты PASS, smoke OK → `result: PASS` → задача переходит deploy-staging
+- Любой FAIL → `result: FAIL` → откат на development (back-to:dev)
+
+## Запрещено
+- Писать продакшн-код
+- Подгонять тесты под код
+- Запускать на prod-контейнере деструктивные операции

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
+
+## [Unreleased]
+
+### Added
+- **Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве** (ORCH-017): пингующее сообщение `notify_approve_requested` теперь встраивает две HTML-`<a>`-ссылки — на `docs/work-items/<WI>/01-brd.md` (Gitea branch-view: `gitea_public_url`→`gitea_url`) и на issue в Plane (`{web_base}/{workspace}/projects/{project_id}/issues/{plane_issue_id}/`). Новая настройка `ORCH_PLANE_WEB_URL` (внешний браузерный web-URL Plane; фолбэк на `plane_api_url`). **Loopback-guard:** если итоговый Plane web-base указывает на localhost/127.0.0.1/0.0.0.0/::1 или пуст — Plane-ссылка опускается (не выпускаем битый localhost-URL). Graceful degradation: каждая ссылка строится независимо и опускается при нехватке данных, сообщение и призыв «Переведите задачу в статус Approved …» сохраняются всегда; ровно одно пингующее сообщение, разделяемая `send_telegram` не тронута. Динамические подписи экранируются `html.escape`, `parse_mode=HTML` сохранён. ADR `docs/work-items/ORCH-017/06-adr/ADR-001-telegram-approve-links.md`. Тесты: `test_notify_approve_links.py`, `test_analysis_approve_flow_links.py`.
+- **Конфигурируемые модель LLM и режим работы (`--effort`) агентов** (ORCH-41): модель/effort каждого агента вынесены из хардкода `launcher.py` в конфиг — глобально per-agent (`ORCH_AGENT_MODEL_<AGENT>` / `ORCH_AGENT_EFFORT_<AGENT>`, дефолты `ORCH_AGENT_MODEL_DEFAULT=claude-opus-4-8`, `ORCH_AGENT_EFFORT_DEFAULT=high`) и per-project (`agent_models` / `agent_efforts` в `ORCH_PROJECTS_JSON`). Резолверы `resolve_agent_model` / `resolve_agent_effort` (приоритет project > per-agent env > default > пусто), валидация effort `{low,medium,high,xhigh,max}`, опц. `ORCH_AGENT_FALLBACK_MODEL` (`--fallback-model`). Хардкод `"model":"opus"` (architect/reviewer) удалён. Тесты: `test_resolve_agent_model.py`, `test_resolve_agent_effort.py`.
+- **Единый status-коммент агентов в Plane** (ORCH-016): `usage.build_status_comment(...)` — один хелпер для ВСЕХ ролей (analyst..deployer). HTML-формат: header `{icon} {Role} — {описание}`, опциональная строка `Verdict/Status: …` из YAML-frontmatter артефакта, **строка `Длительность: 4m 12s`** (явный `duration_s` от launcher, fallback из `agent_runs` для аналитика), `<b>Документы:</b><ul><li><a>…</a></li></ul>`, тех-хвост `<sub>tokens · cost</sub>`. Утилитки: `usage.fmt_duration`, `usage.get_agent_duration`, новый модуль `src/frontmatter.py` (defensive YAML reader). ADR `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md`.
+- **Документация по канону** (ORCH-9): `CLAUDE.md` (паспорт проекта), структура `docs/` (`architecture/` + `adr/`, `operations/`, `work-items/`, `history/`), `docs/operations/INFRA.md` (RUNBOOK с инфра-изоляцией и self-hosting рисками).
+- **ADR**: adr-0001 (multi-repo registry), adr-0002 (job queue), adr-0003 (условный staging-гейт).
+- **Стадия `deploy-staging`** (ORCH-35): промежуточный гейт между `testing` и `deploy`. QG `check_staging_status` (условный, только для self-hosting repo). PR #31.
+- **Деплой-хук** (ORCH-34): `scripts/orchestrator-deploy-hook.sh` с health-check и авто-rollback. PR #30.
+- **Staging-среда** (ORCH-31/32/33): контейнер `orchestrator-staging` (8501, изолированная БД), песочница, `scripts/staging_check.py`. PR #28/#29.
+- **Очередь задач** (ORCH-1): таблица `jobs`, `queue_worker.py`, atomic claim, max_concurrency, ретраи, restart-safe, эндпоинт `/queue`.
+- **Реестр проектов** (ORCH-6): `src/projects.py`, фильтрация вебхуков по проекту.
+
+### Changed
+- **Status-коммент агентов теперь HTML и единообразен** (ORCH-016): `src/usage.usage_comment(...)` помечен deprecated и стал тонкой обёрткой над `build_status_comment`; `src/usage.artifact_links(...)` теперь возвращает `<li><a>…</a></li>` HTML-фрагменты (раньше — markdown `[label](url)`); `stage_engine._build_analyst_ready_comment(...)` — тонкая обёртка, аналитик идёт через ту же ветку `build_status_comment(agent="analyst", ...)`. Реестр `QG_CHECKS` и `STAGE_TRANSITIONS` НЕ изменялись.
+- Цепочка стадий: `... testing → deploy-staging → deploy → done` (была без `deploy-staging`).
+
+### Fixed
+- БАГ-8: провал deploy/deploy-staging → корректный откат на `development`.
+- Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings.
+
+---
+*Историю до введения канона см. в `docs/history/` (BUGFIXES_*, LESSONS_*, INCIDENT_*).*

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md — паспорт проекта orchestrator
+
+## TL;DR
+Мульти-агентный оркестратор разработки. FastAPI-сервис: принимает webhooks от Plane и Gitea, ведёт задачи по конвейеру стадий через Quality Gates, запускает Claude CLI агентов (analyst → architect → developer → reviewer → tester → deployer) на каждой стадии. **Оркестратор дорабатывает в том числе сам себя (self-hosting).**
+
+## Стек
+- Backend: FastAPI + uvicorn (Python 3.12)
+- БД: SQLite (`src/db.py`)
+- Агенты: Claude CLI (`ORCH_CLAUDE_BIN`), по одному промпту на роль в `.openclaw/agents/`
+- Очередь задач: собственная (SQLite `jobs`, `src/queue_worker.py`, ORCH-1)
+- Контейнеризация: Docker + Compose
+- CI/CD: Gitea Actions (`.gitea/workflows/`)
+- Деплой: docker compose на mva154
+
+## Команды
+- `uvicorn src.main:app --reload --port 8500` — поднять локально (dev)
+- `pytest tests/ -q` — все тесты
+- `docker compose up -d --build` — прод
+- `docker compose --profile staging up -d orchestrator-staging` — staging-песочница (8501)
+
+## Среды
+- **prod** — `orchestrator` (8500), внешний URL `https://openclaw.mva154.duckdns.org/orchestrator/`
+- **staging** — `orchestrator-staging` (8501), изолированная БД (`./data/staging`), только sandbox-проект
+
+## Структура
+- `src/` — приложение (main, config, db, stages, stage_engine, queue_worker, projects, usage)
+- `src/agents/launcher.py` — запуск Claude CLI агентов
+- `src/qg/checks.py` — Quality Gate проверки
+- `src/webhooks/` — приём вебхуков Plane/Gitea
+- `tests/` — pytest
+- `docs/` — документация, ADR, work-items, operations
+- `scripts/` — утилиты (staging_check.py, orchestrator-deploy-hook.sh)
+
+## Конвейер (кратко; детали — docs/architecture/README.md)
+```
+created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
+                          ↑                          │
+                          └──── REQUEST_CHANGES ──────┘  (откат на development, max 3)
+```
+
+## Конвенции
+- Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
+- Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
+- ADR per work-item: `docs/work-items/<plane-id>/06-adr/ADR-NNN-slug.md`
+- Global ADR (сквозные решения): `docs/architecture/adr/adr-NNNN-slug.md`
+- Work items: `docs/work-items/<plane-id>/`
+- Машинные вердикты Quality Gate — строго YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`), никогда проза
+
+## Артефакты задачи (`docs/work-items/<plane-id>/`)
+`00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md`.
+
+## Правила для агентов
+1. Перед любым действием прочесть этот файл и `docs/architecture/README.md`.
+2. **Документация = golden source наравне с кодом.** Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови `CHANGELOG.md`.
+3. Никогда не править артефакты других этапов.
+4. Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
+5. Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
+6. **Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.**
+7. Не использовать `--no-verify` без явного одобрения Owner.
+8. Секреты — только в `.env`/`.env.staging` на хосте, в гит НЕ коммитятся (канон — `.env.example`).
+
+## ⚠️ Self-hosting — оркестратор правит САМ СЕБЯ
+Задачи проекта ORCH меняют инструмент, который СЕЙЧАС работает в продакшене и обслуживает ДРУГИЕ проекты (enduro-trails) из ОДНОГО инстанса с ОБЩЕЙ БД и общей очередью.
+- **НЕ перезапускать / не ронять прод-контейнер** `orchestrator` в рамках задачи — встанет конвейер всех проектов.
+- Любой деплой/рестарт self = групповой риск. Детали и топология — `docs/operations/INFRA.md`.
+- Стадия `deploy-staging` (порт 8501) — обязательная страховка перед прод-деплоем орка.
+
+---
+*Паспорт проекта orchestrator. Поддерживается агентами при каждой доработке. Изолирован: описывает только этот проект (канон per-repo, см. ORCH-9).*

README.md

@@ -1,5 +1,7 @@
 # Multi-Agent Orchestrator
 
+> См. [CLAUDE.md](CLAUDE.md) (паспорт проекта) и [docs/architecture/README.md](docs/architecture/README.md) (архитектура).
+
 FastAPI-сервис для оркестрации мульти-агентного пайплайна разработки. Принимает webhooks от Plane и Gitea, управляет жизненным циклом задач через Quality Gates, запускает Claude CLI агентов на каждой стадии.
 
 ## Архитектура
@@ -17,9 +19,9 @@ Gitea (git events) ─webhook──┘         │
 ## Стадии пайплайна
 
 ```
-created → analysis → architecture → development → review → testing → deploy → done
-                                         ↑                     │
-                                         └─── REQUEST_CHANGES ─┘  (max 3 retries)
+created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
+                          ↑                          │
+                          └───── REQUEST_CHANGES ─────┘  (max 3 retries)
 ```
 
 | Стадия | Агент | Quality Gate (выход) | Триггер перехода |
@@ -29,8 +31,9 @@ created → analysis → architecture → development → review → testing →
 | architecture | architect | ADR или infra-requirements | Push docs/ |
 | development | developer | check_tests_local (орк сам гоняет `make test`) | Auto-advance после developer |
 | review | reviewer | check_reviewer_verdict (`verdict:` во frontmatter 12-review.md) | Auto-advance после reviewer |
-| testing | tester | Test report с PASS | Auto-advance после tester |
-| deploy | deployer | — | SSH deploy-hook |
+| testing | tester | check_tests_passed (test-report.md) | Auto-advance после tester |
+| deploy-staging | deployer | check_staging_status (15-staging-log.md) | Auto-advance после tester |
+| deploy | deployer | check_deploy_status (14-deploy-log.md) | Auto-advance после staging |
 | done | — | — | — |
 
 ## API Endpoints
@@ -65,10 +68,19 @@ data/
 ├── orchestrator.db      # SQLite database
 └── runs/                # Agent output logs ({run_id}.log)
 docs/
-├── ARCHITECTURE.md      # Подробная архитектура
-├── LESSONS_ET006.md     # Lessons learned из ET-006
-├── BUGFIXES_2026-05-21.md # Багфиксы
-└── SETUP_WEBHOOKS.md    # Настройка webhooks
+├── PRODUCT_VISION.md            # Видение продукта
+├── architecture/
+│   ├── README.md                # Обзор архитектуры, компоненты, API
+│   ├── internals.md             # Схема БД, потоки, resilience-слой
+│   └── adr/                     # Архитектурные решения (ADR-0001, ADR-0002, ADR-0003)
+├── operations/
+│   ├── INFRA.md                 # Топология, порты, env, self-hosting риски
+│   ├── DEPLOY_HOOK.md           # Деплой-хук
+│   ├── STAGING.md               # Staging-окружение
+│   ├── STAGING_CHECK.md         # Проверки staging
+│   └── SETUP_WEBHOOKS.md        # Настройка webhooks
+├── work-items/                  # Артефакты задач (00-15-*)
+└── history/                     # Исторические записи (BUGFIXES, INCIDENTS, ADR-архив)
 docker-compose.yml       # Deployment config
 Dockerfile               # Python 3.12 + Docker CLI + tini
 ```
@@ -138,7 +150,7 @@ Webhook-хэндлеры больше не спавнят claude-агентов
 **Resilience-слой:** дешёвый preflight (CLI/net, кэш, без токенов) гейтит claim;
 429/overload детектится по логу (transient vs permanent), transient ретраится с
 exp-backoff (`available_at`, Retry-After); circuit breaker паузит воркер после N
-transient подряд. Подробности: `docs/ORCH-1_JOB_QUEUE.md`.
+transient подряд. Подробности: `docs/history/ORCH-1_JOB_QUEUE.md`.
 
 ## Multi-repo: реестр проектов (ORCH-6)
 
@@ -176,7 +188,7 @@ Plane-проект из маппинга.
    docker exec orchestrator python3 -c "from src.projects import get_project_by_plane_id as g; print(g('<новый-uuid>'))"
    ```
 
-Поля `name` опционально (по умолчанию = `repo`). Подробности — `docs/ARCHITECTURE.md`.
+Поля `name` опционально (по умолчанию = `repo`). Подробности — `docs/architecture/internals.md`.
 
 ## Ключевые механизмы
 

docker-compose.yml

@@ -25,3 +25,39 @@ services:
       - DEPLOY_HOOK_SCRIPT=/home/slin/bin/enduro-deploy-hook.sh
     group_add:
       - "999"
+
+  # ORCH-31: staging instance (port 8501, isolated DB).
+  # Starts ONLY with: docker compose --profile staging up -d orchestrator-staging
+  # Normal "docker compose up -d" does NOT start this service.
+  orchestrator-staging:
+    profiles:
+      - staging
+    build: .
+    container_name: orchestrator-staging
+    restart: unless-stopped
+    init: true
+    network_mode: host
+    command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8501"]
+    volumes:
+      - ./data/staging:/app/data
+      - /home/slin/repos:/repos
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /usr/lib/node_modules/@anthropic-ai/claude-code:/opt/claude-code:ro
+      - /usr/bin/node:/usr/bin/node:ro
+      - /home/slin/.claude:/home/slin/.claude
+      - /home/slin/.claude.json:/home/slin/.claude.json:ro
+      - /home/slin/.orchestrator-ssh:/root/.ssh:ro
+    env_file: .env.staging
+    environment:
+      - ORCH_REPOS_DIR=/repos
+      - ORCH_HOST_REPOS_DIR=/home/slin/repos
+      - DEPLOY_SSH_USER=slin
+      - DEPLOY_SSH_HOST=127.0.0.1
+      - DEPLOY_HOOK_SCRIPT=/home/slin/bin/enduro-deploy-hook.sh
+      # Staging DB is isolated via ./data/staging volume mount.
+      # Inside the container the path remains /app/data/orchestrator.db (same default),
+      # but on the host it physically lives at ./data/staging/orchestrator.db — 
+      # completely separate from prod ./data/orchestrator.db.
+      - ORCH_DB_PATH=/app/data/orchestrator.db
+    group_add:
+      - "999"

docs/architecture/README.md

@@ -0,0 +1,92 @@
+# Архитектура Orchestrator
+
+## Обзор
+Мульти-агентный оркестратор разработки. Принимает webhooks от Plane (управление задачами) и Gitea (git-события), ведёт задачи по конвейеру стадий через Quality Gates, на каждой стадии запускает Claude CLI агента. Поддерживает несколько проектов (multi-repo) и self-hosting (дорабатывает сам себя).
+
+## Компоненты
+- **Webhook Receivers** (`src/webhooks/plane.py`, `gitea.py`) — приём событий, HMAC-проверка, дедупликация (`_dedup.py`). Роуты: `POST /webhook/plane`, `POST /webhook/gitea`.
+- **State Machine** (`src/stages.py`) — `STAGE_TRANSITIONS`: переходы, агент и QG каждой стадии. Хелперы: `get_next_stage`, `get_agent_for_stage`, `get_qg_for_stage`, `get_previous_stage`.
+- **Stage Engine** (`src/stage_engine.py`) — исполнение переходов, диспетчеризация QG (`_run_qg`), откаты, синхронизация с Plane.
+- **Quality Gates** (`src/qg/checks.py`) — проверки выхода со стадии, реестр `QG_CHECKS`.
+- **Agent Launcher** (`src/agents/launcher.py`) — запуск Claude CLI агентов в изолированном git worktree, мониторинг, auto-advance.
+- **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe.
+- **Project Registry** (`src/projects.py`, ORCH-6) — Plane project id → repo + prefix; фильтрация вебхуков по проекту.
+- **Plane Sync** (`src/plane_sync.py`) — синхронизация статусов/комментариев в Plane.
+
+## Конвейер и Quality Gates
+
+```
+created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
+                          ↑                          │
+                          └──── REQUEST_CHANGES ──────┘  (откат на development, max 3 retries)
+```
+
+| Стадия | Агент (выход) | Quality Gate | Артефакт |
+|--------|---------------|--------------|----------|
+| created | analyst | — | — |
+| analysis | architect | `check_analysis_approved` | 01-brd / 02-trz / 03-acceptance-criteria / 04-test-plan.yaml |
+| architecture | developer | `check_architecture_done` | 06-adr/ |
+| development | reviewer | `check_ci_green` | код + PR |
+| review | tester | `check_reviewer_verdict` | 12-review.md (`verdict:`) |
+| testing | deployer | `check_tests_passed` | 13-test-report.md |
+| deploy-staging | deployer | `check_staging_status` | 15-staging-log.md (`staging_status:`) |
+| deploy | — | `check_deploy_status` | 14-deploy-log.md (`deploy_status:`) |
+| done | — | — | — |
+
+**Реестр QG** (`QG_CHECKS`): check_analysis_approved, check_analysis_complete, check_architecture_done, check_ci_green, check_review_approved, check_tests_passed, check_reviewer_verdict, check_tests_local, check_deploy_status, check_staging_status.
+
+**Канон гейтов:** машинные вердикты читаются ТОЛЬКО из YAML-frontmatter, никогда из прозы. Лог-файлы мержатся в `origin/main` отдельным PR; гейт читает из `origin/main`.
+
+### Условный staging-гейт (ORCH-35)
+`check_staging_status` реален только для self-hosting (`is_self_hosting_repo(repo)` → `orchestrator`); для остальных проектов → no-op `(True, "Staging gate N/A")`. Для orchestrator парсит `staging_status:` из `15-staging-log.md`; FAILED → откат на `development`. Подробнее: [ADR-0003](adr/adr-0003-staging-gate.md).
+
+## Откаты
+- Reviewer REQUEST_CHANGES → откат на `development` + retry (`MAX_DEVELOPER_RETRIES = 3`).
+- Tester `check_tests_passed` FAIL → откат на `development` + retry.
+- Deploy / deploy-staging FAILED → откат на `development`.
+- `get_previous_stage` использует порядок ключей `STAGE_TRANSITIONS`.
+
+### 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>`:
+
+```
+{ICON} {RoleName} — {описание стадии}
+[Verdict|Status: VALUE]                  # reviewer/tester/deployer, из YAML-frontmatter артефакта
+[Длительность: 4m 12s]                   # явный duration_s от launcher, либо fallback из agent_runs
+<b>Документы:</b><ul><li><a href="…">label</a></li>…</ul>
+[<sub>8.5M in / 45.8k out · $7.29</sub>] # тех-хвост usage; опускается при нулях
+```
+
+- **Длительность** считается 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). Машинные ключи: `verdict:` (reviewer/tester), `deploy_status:` (14-deploy-log.md), `staging_status:` (15-staging-log.md).
+- Формат коммента **не** меняет реестр гейтов и стадий; коммент — отображение, не управление.
+
+## База данных (SQLite)
+- `events` — входящие вебхуки (дедуп)
+- `tasks` — задачи и их стадии
+- `agent_runs` — запуски агентов (run_id, usage, cost)
+- `jobs` — очередь задач (ORCH-1)
+
+## Изоляция (git worktree, ORCH-2)
+Каждая задача исполняется в отдельном git worktree, ветки не пересекаются. Репозитории проектов разделены под `/repos/<project>`.
+
+## API
+| Method | Path | Описание |
+|--------|------|----------|
+| GET | `/health` | health check |
+| GET | `/status` | активные задачи (stage != done) |
+| GET | `/queue` | очередь: counts + max_concurrency + последние jobs |
+| POST | `/webhook/plane` | Plane webhook |
+| POST | `/webhook/gitea` | Gitea webhook (push, PR, CI status) |
+
+## Деплой и эксплуатация
+Топология, контейнеры, порты, env-карта, self-hosting риски — [docs/operations/INFRA.md](../operations/INFRA.md). Деплой-хук — [DEPLOY_HOOK.md](../operations/DEPLOY_HOOK.md). Staging — [STAGING.md](../operations/STAGING.md).
+
+## ADR
+Сквозные архитектурные решения — [adr/](adr/). Per-work-item решения — `docs/work-items/<id>/06-adr/`.
+
+## Детали реализации
+Схема БД, потоки данных, resilience-слой, детали Dockerfile — [internals.md](internals.md).
+
+---
+*Актуально на 2026-06-05 (main `f1b3146`). Обновлять при изменении src/stages.py, src/qg/checks.py, src/main.py.*

docs/architecture/adr/README.md

@@ -0,0 +1,15 @@
+# Architecture Decision Records
+
+Индекс сквозных (cross-cutting) ADR проекта orchestrator.
+Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-slug.md`.
+
+| # | Решение | Статус | Дата | Источник |
+|---|---------|--------|------|----------|
+| adr-0001 | Реестр проектов (multi-repo) | accepted | 2026-06-02 | ORCH-6 |
+| adr-0002 | Очередь задач вместо in-process потоков | accepted | 2026-06-03 | ORCH-1 |
+| adr-0003 | Условный staging-гейт перед прод-деплоем | accepted | 2026-06-05 | ORCH-35 |
+
+## Формат
+**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.
+Принятый ADR не меняется — новое решение заводится отдельным файлом со ссылкой `supersedes adr-XXXX`.
+Новые ADR добавляет архитектор при принятии решения (см. `CLAUDE.md` → Конвенции).

docs/architecture/adr/adr-0001-multi-repo-registry.md

@@ -0,0 +1,23 @@
+# adr-0001: Реестр проектов (multi-repo)
+
+- **Статус:** accepted
+- **Дата:** 2026-06-02
+- **Задача:** ORCH-6
+
+## Контекст
+Инцидент 2026-06-02: Plane-вебхук слушал весь воркспейс и хардкодил `repo = settings.default_repo` (enduro-trails). Задачи ЛЮБОГО проекта сливались в один репо с одним префиксом (ET). Нужна изоляция по проектам.
+
+## Решение
+Введён реестр `src/projects.py`: `ProjectConfig` (frozen dataclass) связывает `plane_project_id` → `repo` + `work_item_prefix` + `name`. Источник правды — env `ORCH_PROJECTS_JSON`; при пустом/невалидном — встроенный дефолт (`enduro-trails`/ET, `orchestrator`/ORCH). Позволяет: фильтровать вебхуки по проекту (неизвестный → ignore), резолвить gitea-репо + префикс, роутить Plane-синк в свой проект задачи.
+
+## Альтернативы
+- Один репо на всё — отклонён (источник инцидента).
+- Хардкод маппинга в коде — отклонён в пользу env-конфигурируемого реестра с безопасным дефолтом.
+
+## Последствия
+- Изоляция проектов на уровне вебхуков и роутинга.
+- Парсер устойчив: битый элемент скипается, пустой результат → дефолт.
+- Основа для `is_self_hosting_repo` (adr-0003).
+
+## Связи
+adr-0003 (условный гейт опирается на repo из реестра).

docs/architecture/adr/adr-0002-job-queue.md

@@ -0,0 +1,23 @@
+# adr-0002: Очередь задач вместо in-process потоков
+
+- **Статус:** accepted
+- **Дата:** 2026-06-03
+- **Задача:** ORCH-1 (F-2b)
+
+## Контекст
+Ранняя версия запускала стадии конвейера в in-process daemon-потоках. Проблемы: не переживало рестарт (задачи терялись), нет контроля параллелизма, нет ретраев, нет наблюдаемости.
+
+## Решение
+Введена персистентная очередь задач (`src/queue_worker.py` + таблица `jobs` в SQLite): atomic claim задачи воркером, `max_concurrency`, ретраи при сбое, restart-safe (running-задачи реквестятся при старте), эндпоинт `GET /queue`.
+
+## Альтернативы
+- In-process потоки — отклонены (не restart-safe).
+- Внешний брокер (Redis/RabbitMQ) — избыточно для текущего масштаба; SQLite-очередь проще и без новых зависимостей.
+
+## Последствия
+- Конвейер переживает рестарт контейнера.
+- Контроль параллелизма и наблюдаемость через `/queue`.
+- ⚠️ Очередь общая на все проекты прод-инстанса — фактор группового риска при self-hosting (см. `docs/operations/INFRA.md`).
+
+## Связи
+adr-0001 (реестр проектов), INFRA.md (общая очередь при self-hosting).

docs/architecture/adr/adr-0003-staging-gate.md

@@ -0,0 +1,27 @@
+# adr-0003: Условный staging-гейт перед прод-деплоем
+
+- **Статус:** accepted
+- **Дата:** 2026-06-05
+- **Задача:** ORCH-35
+
+## Контекст
+Оркестратор дорабатывает сам себя (self-hosting). Раньше стадия `deploy` имела «бумажный» вердикт: deployer-агент писал `deploy_status: SUCCESS`, но реального прогона на изолированной среде не было. Нужен предохранитель: прод-деплой орка не должен происходить, пока изменения не проверены на живой staging-среде. При этом другие проекты (enduro-trails) staging-инфры не имеют.
+
+## Решение
+Добавлена промежуточная стадия `deploy-staging` между `testing` и `deploy`: `testing → deploy-staging → deploy → done`.
+- deployer гоняет `scripts/staging_check.py --base-url http://localhost:8501` и пишет `staging_status: SUCCESS|FAILED` в `15-staging-log.md`.
+- Quality Gate `check_staging_status` парсит вердикт (только YAML-frontmatter).
+- **Гейт условный:** `is_self_hosting_repo(repo)` → реальная проверка только для `orchestrator`; для остальных проектов гейт = no-op `(True, "Staging gate N/A")`.
+- FAILED → откат на `development`.
+
+## Альтернативы
+- Глобальный гейт для всех проектов — отклонён: у enduro нет staging-инстанса, задачи застревали бы на откате.
+- Деплой реально дёргает хост-хук прямо здесь — отложен в ORCH-36 (Вариант B).
+
+## Последствия
+- Прод-деплой орка недостижим, пока staging-гейт не зелёный.
+- Другие проекты не затронуты (no-op).
+- Реальный docker-деплой через хук пока НЕ выполняется (вердикт «бумажный», но подкреплён прогоном сьюта). Исполняемый деплой — ORCH-36.
+
+## Связи
+adr-0001 (реестр проектов — основа `is_self_hosting_repo`), ORCH-34 (deploy-hook + rollback), ORCH-36 (исполняемый самодеплой).

docs/architecture/internals.md

@@ -58,7 +58,8 @@ STAGE_TRANSITIONS = {
     architecture: → development   (agent: developer,  QG: check_architecture_done)
     development:  → review        (agent: reviewer,   QG: check_tests_local)
     review:       → testing       (agent: tester,     QG: check_reviewer_verdict)
-    testing:      → deploy        (agent: deployer,   QG: check_tests_passed)
+    testing:      → deploy-staging (agent: deployer,   QG: check_tests_passed)
+    deploy-staging: → deploy      (agent: deployer,   QG: check_staging_status)
     deploy:       → done          (agent: None,       QG: None)
 }
 ```
@@ -189,8 +190,10 @@ services:
 12. Gitea PR webhook: review event → QG check_review_approved → PASS
 13. Advance: review → testing, tester launched
 14. Tester: прогоняет тесты, пишет test-report.md → git push
-15. Auto-advance: testing → deploy (QG check_tests_passed → PASS)
-16. PR merge → Gitea PR webhook: action=closed, merged=true → done
+15. Auto-advance: testing → deploy-staging (QG check_tests_passed → PASS)
+16. Deployer: runs staging checks → writes 15-staging-log.md (staging_status: SUCCESS)
+17. Auto-advance: deploy-staging → deploy (QG check_staging_status → PASS)
+18. PR merge → Gitea PR webhook: action=closed, merged=true → done
 ```
 
 ### Review bounce path
@@ -323,6 +326,10 @@ jobs со статусом `running` (воркер умёр на рестарт
 
 - `ORCH_MAX_CONCURRENCY` (default 1) — лимит параллельных jobs.
 - `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.
 

docs/operations/DEPLOY_HOOK.md

@@ -0,0 +1,90 @@
+# Orchestrator Deploy Hook
+
+`scripts/orchestrator-deploy-hook.sh` — хост-скрипт деплоя orchestrator с health-чеком и авто-rollback.
+
+## Как работает
+
+### Режим `--deploy` (по умолчанию)
+
+1. **Захват текущего образа** — до рестарта записывает ID образа работающего контейнера в `$PREV_IMAGE_FILE` (best-effort, не падает если сервис не запущен).
+2. **git pull** — обновляет код репозитория.
+3. **Рестарт контейнера** — `docker compose --profile $COMPOSE_PROFILE up -d --no-build $TARGET_SERVICE`.
+4. **Health-цикл** — 10 попыток × 6с = до 60с. Критерий: HTTP 200 + тело содержит `"status":"ok"`.
+   - **Успех** → `exit 0`, лог "Deploy SUCCESS".
+   - **Провал** → авто-rollback (шаг 5).
+5. **Авто-rollback** — восстанавливает образ из `$PREV_IMAGE_FILE`, рестарт, повторный health 5×3с.
+   - Если восстановился → `exit 1` (деплой провалился, откат успешен).
+   - Если и откат не помог → `exit 2` (критично).
+
+### Режим `--rollback`
+
+Вручную откатывает сервис на предыдущий образ из `$PREV_IMAGE_FILE`.
+
+## Переменные окружения
+
+| Переменная       | Дефолт                            | Описание                                      |
+|------------------|-----------------------------------|-----------------------------------------------|
+| `TARGET_SERVICE` | `orchestrator-staging`            | Имя docker-compose сервиса                    |
+| `TARGET_PORT`    | `8501`                            | Порт health-check                             |
+| `TARGET_IMAGE`   | `orchestrator-orchestrator-staging` | Имя образа для retag при rollback           |
+| `COMPOSE_PROFILE`| `staging`                         | Docker compose profile (пусто = без профиля) |
+| `PREV_IMAGE_FILE`| `$REPO/.deploy-prev-image-staging`| Файл для сохранения предыдущего образа        |
+| `LOG`            | `/var/log/orchestrator/deploy-hook.log` | Лог-файл (fallback: `$REPO/deploy-hook.log`) |
+
+> ⚠️ **Дефолт — всегда STAGING**. Прод активируется только явным переопределением env.
+
+## Примеры запуска
+
+### Staging (дефолт, безопасно)
+
+```bash
+cd /home/slin/repos/orchestrator
+bash scripts/orchestrator-deploy-hook.sh --deploy
+# или просто:
+bash scripts/orchestrator-deploy-hook.sh
+```
+
+### Прод (осознанный шаг, Этап 5)
+
+```bash
+TARGET_SERVICE=orchestrator \
+TARGET_PORT=8500 \
+TARGET_IMAGE=orchestrator-orchestrator \
+COMPOSE_PROFILE="" \
+PREV_IMAGE_FILE=/home/slin/repos/orchestrator/.deploy-prev-image-prod \
+bash scripts/orchestrator-deploy-hook.sh --deploy
+```
+
+### Ручной rollback staging
+
+```bash
+bash scripts/orchestrator-deploy-hook.sh --rollback
+```
+
+## Коды выхода
+
+| Код | Значение                                             |
+|-----|------------------------------------------------------|
+| `0` | Деплой успешен, сервис здоров                        |
+| `1` | Деплой провалился; откат выполнен (или пропущен)     |
+| `2` | Деплой провалился И откат тоже провалился (критично) |
+
+## Логи
+
+```
+/var/log/orchestrator/deploy-hook.log
+```
+
+Каждая строка с UTC-таймстампом в формате `[2026-06-05T06:30:00Z]`.
+
+## Разница с enduro-deploy-hook.sh
+
+| Функция              | enduro-deploy-hook.sh | orchestrator-deploy-hook.sh |
+|----------------------|-----------------------|-----------------------------|
+| Захват PREV_IMG      | ✅                    | ✅                          |
+| git pull             | ✅                    | ✅                          |
+| Рестарт              | ✅                    | ✅                          |
+| Health-цикл (60с)    | ❌                    | ✅ 10×6с                    |
+| Авто-rollback        | ❌                    | ✅                          |
+| Параметризация (env) | ❌ хардкод            | ✅ дефолт=staging           |
+| Compose profile      | ❌                    | ✅ --profile staging        |

docs/operations/INFRA.md

@@ -0,0 +1,122 @@
+# INFRA.md — инфраструктура и эксплуатация оркестратора
+
+> RUNBOOK. Топология, контейнеры, порты, переменные окружения, границы.
+> **Секреты тут НЕ хранятся** — только дескрипторы. Реальные значения — в `.env` на хосте.
+
+## Топология
+
+```
+                 host: mva154 (slin@82.22.50.71), network_mode: host
+ ┌──────────────────────────────────────────────────────────────────────┐
+ │  orchestrator        (PROD)     :8500   env_file .env                  │
+ │    БД: ./data/orchestrator.db          (обслуживает ВСЕ прод-проекты)  │
+ │                                                                        │
+ │  orchestrator-staging (STAGING) :8501   env_file .env.staging          │
+ │    БД: ./data/staging/orchestrator.db  (изолирована, только sandbox)   │
+ │    profile: staging — НЕ стартует обычным `docker compose up`          │
+ └──────────────────────────────────────────────────────────────────────┘
+        │ webhooks                                  │ git
+        ▼                                           ▼
+   Plane (ag_proj)                            Gitea (localhost:3000)
+   /repos/<project>  ← общий каталог репозиториев (host: /home/slin/repos)
+```
+
+## Контейнеры
+
+| Контейнер | Роль | Порт | env_file | БД (хост) | Старт |
+|-----------|------|------|----------|-----------|-------|
+| `orchestrator` | прод | 8500 | `.env` | `./data/orchestrator.db` | `docker compose up -d` |
+| `orchestrator-staging` | staging / песочница | 8501 | `.env.staging` | `./data/staging/orchestrator.db` | `docker compose --profile staging up -d orchestrator-staging` |
+
+Оба: `network_mode: host`, `init: true` (tini как PID 1 — reaping зомби, B-2), `restart: unless-stopped`.
+
+### Тома (volumes)
+- `./data` → `/app/data` (БД; у staging — `./data/staging`)
+- `/home/slin/repos` → `/repos` (рабочие репозитории проектов)
+- `/var/run/docker.sock` (для docker-операций деплоя)
+- claude-code, node, `~/.claude*` (CLI агентов, ro)
+- `~/.orchestrator-ssh` → `/root/.ssh` (ro, деплой по ssh)
+
+## Переменные окружения (карта; значения — в `.env`)
+
+| Переменная | Назначение |
+|-----------|-----------|
+| `ORCH_PLANE_API_URL` / `_TOKEN` / `_WORKSPACE_SLUG` | доступ к Plane API |
+| `ORCH_PLANE_WEB_URL` | внешний (браузерный) web-URL Plane для кликабельных ссылок на issue в уведомлениях (ORCH-017); пусто → фолбэк на `ORCH_PLANE_API_URL`, loopback-фолбэк → ссылка опускается |
+| `ORCH_PLANE_WEBHOOK_SECRET` | HMAC-проверка вебхуков Plane |
+| `ORCH_GITEA_URL` / `_TOKEN` / `_WEBHOOK_SECRET` | доступ к Gitea + HMAC |
+| `ORCH_CLAUDE_BIN` | путь к claude CLI |
+| `ORCH_REPOS_DIR` / `ORCH_HOST_REPOS_DIR` | каталог репозиториев (в контейнере / на хосте) |
+| `ORCH_DB_PATH` | путь к SQLite БД |
+| `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` | параметры деплой-хука |
+
+**Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`.
+
+## Реестр проектов (`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) — изоляция.
+
+## Модель и 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 — оркестратор дорабатывает САМ СЕБЯ
+
+**Факт:** прод-инстанс `orchestrator` (8500) — ОДИН на ВСЕ прод-проекты (enduro-trails + orchestrator), с ОБЩЕЙ БД `./data/orchestrator.db` и общей очередью задач (ORCH-1).
+
+**Следствие — групповой риск:** когда орк выполняет задачу из проекта ORCH (дорабатывает себя), он бежит в том же инстансе, что обслуживает enduro-trails.
+- Рестарт / падение прод-контейнера орк-задачей → конвейер ВСЕХ проектов встаёт.
+- Кривой self-деплой (ORCH-36, Вариант B) → лежат все проекты сразу.
+- Общая очередь → орк-задача занимает concurrency-слоты других проектов.
+
+**Что изолировано (безопасно):**
+- Staging (8501) — отдельная БД (`./data/staging`), отдельный реестр (`ORCH_PROJECTS_JSON` = только sandbox). Прод-проекты не видит.
+- Репозитории разделены, изоляция веток через git worktree (ORCH-2).
+
+**Страховки:**
+- Стадия `deploy-staging` (порт 8501) — обязательный гейт перед прод-деплоем орка. Прод-деплой недостижим, пока staging-гейт не зелёный (см. `STAGING.md`, ORCH-35). Гейт условный: реален только для self-hosting (repo=orchestrator), для остальных проектов — no-op.
+
+**Правила для агентов при задачах ORCH:**
+1. НЕ перезапускать / не ронять прод-контейнер `orchestrator` в рамках задачи.
+2. Все проверки деплоя — на staging (8501), боевой 8500 не трогать.
+3. Деплой self — только через хук с health-check + авто-rollback (`DEPLOY_HOOK.md`).
+
+## Эксплуатация (быстрые команды)
+```bash
+# статус
+docker ps --filter name=orchestrator
+curl -s http://localhost:8500/health
+curl -s http://localhost:8500/status   # активные задачи
+curl -s http://localhost:8500/queue    # очередь
+
+# поднять staging-песочницу
+docker compose --profile staging up -d orchestrator-staging
+curl -s http://localhost:8501/health
+
+# логи
+docker logs --tail 100 orchestrator
+```
+
+---
+*RUNBOOK 2026-06-05. Обновлять при изменении топологии/портов/переменных. См. CONTRIBUTING.md §8.*

docs/operations/STAGING.md

@@ -0,0 +1,85 @@
+# Staging Environment (ORCH-31)
+
+Orchestrator supports a permanent **staging instance** running on port **8501** with a
+fully-isolated SQLite database. The staging instance shares the same codebase and
+Dockerfile as production but is started under the `staging` Docker Compose profile so it
+**never starts accidentally** during a normal `docker compose up -d`.
+
+## Architecture
+
+| | Production | Staging |
+|---|---|---|
+| Port | 8500 | 8501 |
+| Container name | `orchestrator` | `orchestrator-staging` |
+| DB (host path) | `./data/orchestrator.db` | `./data/staging/orchestrator.db` |
+| DB (container path) | `/app/data/orchestrator.db` | `/app/data/orchestrator.db` |
+| env file | `.env` | `.env.staging` |
+| Compose profile | *(default)* | `staging` |
+
+DB isolation is achieved via a separate volume mount (`./data/staging:/app/data`), not by
+changing `ORCH_DB_PATH` — the container path stays identical while the host path is a
+different directory.
+
+## Prerequisites
+
+1. **`.env.staging`** — create from the template (see below). This file is **not committed**
+   to the repo (it contains secrets). Copy and fill in values before first start.
+2. **`./data/staging/`** directory — created automatically on first container start.
+
+### Create `.env.staging`
+
+```bash
+cd /home/slin/repos/orchestrator
+cp .env.staging.example .env.staging
+# Edit .env.staging — fill in real tokens / secrets.
+# At Stage 1 (ORCH-31) you can reuse prod values; sandbox Plane project
+# and isolated Gitea webhook will be wired in ORCH-32.
+nano .env.staging
+```
+
+## Starting Staging
+
+```bash
+cd /home/slin/repos/orchestrator
+docker compose --profile staging up -d orchestrator-staging
+```
+
+Check it is running:
+
+```bash
+docker ps | grep orchestrator-staging
+curl -s http://localhost:8501/health | python3 -m json.tool
+```
+
+## Stopping Staging
+
+```bash
+docker compose --profile staging stop orchestrator-staging
+# or remove the container entirely:
+docker compose --profile staging down orchestrator-staging
+```
+
+## Normal `up -d` does NOT start staging
+
+```bash
+# This starts ONLY the prod orchestrator (port 8500). Staging is NOT affected.
+docker compose up -d
+```
+
+The `profiles: [staging]` directive in `docker-compose.yml` ensures staging is
+completely invisible to commands that do not pass `--profile staging`.
+
+## Logs
+
+```bash
+docker logs -f orchestrator-staging
+```
+
+## Roadmap
+
+| Task | Description |
+|---|---|
+| **ORCH-31** *(this PR)* | Infra: compose service, .env template, gitignore, docs |
+| **ORCH-32** | Sandbox: isolated Plane project + Gitea repo for staging |
+| **ORCH-33** | Test suite running against staging endpoint |
+| **ORCH-34** | Deploy hook: promote `orchestrator:candidate` image to staging |

docs/operations/STAGING_CHECK.md

@@ -0,0 +1,136 @@
+# STAGING_CHECK.md — Инструкция по запуску staging check suite (ORCH-33)
+
+## Что это
+
+`scripts/staging_check.py` — самостоятельный скрипт проверки **живого** staging-стенда orchestrator (порт 8501). Не unit-тесты — реальные HTTP-вызовы против работающих сервисов.
+
+Три блока проверок:
+
+| Блок | Название | Что проверяет |
+|------|----------|---------------|
+| A    | SMOKE    | `/health`, `/queue`, `ORCH_STAGING=true` |
+| B    | ACCESS   | Plane sandbox (R), Gitea sandbox (R+push), реестр проектов |
+| C    | E2E      | Создать задачу → триггер конвейера → ветка + коммент → cleanup |
+
+Exit code: **0** = все PASS, **non-zero** = есть FAIL.
+
+---
+
+## Требования к окружению
+
+Скрипт читает токены/URL из env (те же переменные, что использует orchestrator):
+
+| Переменная | Описание |
+|-----------|----------|
+| `ORCH_STAGING` | Должна быть `true` — защита от случайного запуска на проде |
+| `ORCH_PLANE_API_TOKEN` | Plane API token (`X-API-Key`) |
+| `ORCH_PLANE_API_URL` | Plane base URL **без** `/api/v1` (скрипт добавляет сам) |
+| `ORCH_PLANE_WORKSPACE_SLUG` | Workspace slug (`ag_proj`) |
+| `ORCH_GITEA_TOKEN` | Gitea token (`Authorization: token …`) |
+| `ORCH_GITEA_URL` | Gitea base URL (`http://localhost:3000`) |
+| `ORCH_PLANE_WEBHOOK_SECRET` | HMAC-секрет для подписи `/webhook/plane` (если пустой — без подписи) |
+
+Все эти переменные **уже есть** внутри контейнера `orchestrator-staging`.
+
+---
+
+## Способы запуска
+
+### 1. Внутри контейнера (рекомендуемый)
+
+```bash
+docker exec orchestrator-staging \
+  python3 /repos/orchestrator/scripts/staging_check.py --mode stub
+```
+
+### 2. С хоста (если есть токены в env)
+
+```bash
+export ORCH_STAGING=true
+export ORCH_PLANE_API_TOKEN=...
+# ... остальные переменные ...
+
+python3 scripts/staging_check.py \
+  --base-url http://localhost:8501 \
+  --mode stub
+```
+
+### 3. Из docker exec с передачей URL
+
+```bash
+docker exec orchestrator-staging \
+  python3 /repos/orchestrator/scripts/staging_check.py \
+  --base-url http://localhost:8501 \
+  --mode stub
+```
+
+---
+
+## Режимы (`--mode`)
+
+| Режим | Описание | Скорость |
+|-------|----------|----------|
+| `stub` (дефолт) | Проверяет **ранние артефакты** конвейера: ветка + QG-0-коммент. Создаются ДО запуска Claude CLI → быстро, детерминированно, без расхода LLM-кредитов. | ~30-90 сек |
+| `full-real` | Дополнительно ждёт реального завершения аналитика. Долго, расходует LLM-кредиты. | 5-15+ мин |
+
+**Текущий дефолт: `stub`** — достаточен для проверки работоспособности стенда.
+
+---
+
+## Что проверяет блок C (E2E) и почему это безопасно
+
+Порядок `start_pipeline` в коде orchestrator:
+1. Resolve проекта из реестра
+2. Получить name/description из Plane API (если в webhook пустые)
+3. **QG-0 гейт** (name ≥ 5 симв, description ≥ 20 симв)
+4. **Создать work_item_id + ветку в Gitea + начальные доки**
+5. **Записать строку задачи в БД**
+6. Поставить аналитика в очередь (вот тут Claude CLI)
+
+Блок C проверяет **шаги 4-5**, аналитика (шаг 6) **не ждёт**.  
+Тест-задача создаётся ТОЛЬКО в **SANDBOX** (`project_id 8c5a3025-...`),  
+ветка создаётся ТОЛЬКО в **orchestrator-sandbox**.
+
+### CLEANUP (обязателен)
+
+`try/finally` гарантирует удаление тестовых артефактов:
+- Удаляет ветку из `orchestrator-sandbox`
+- Удаляет задачу из Plane SANDBOX
+
+Cleanup отрабатывает даже при падении e2e.
+
+---
+
+## Принцип HMAC-подписи
+
+Скрипт читает `ORCH_PLANE_WEBHOOK_SECRET` из env и формирует подпись:
+```python
+hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+```
+Передаёт как заголовок `X-Plane-Signature`. Алгоритм совпадает с `verify_plane_signature` в `src/webhooks/plane.py`.
+
+---
+
+## Изолированность от прода
+
+| Проверка | Гарантия |
+|---------|---------|
+| A3 `ORCH_STAGING=true` | При false — abort до деструктивных блоков |
+| B6 Реестр без боевых | ET/ORCH project_id absent в `known_plane_project_ids()` |
+| C: only SANDBOX project_id | Webhook payload указывает только `8c5a3025-...` |
+| C: only orchestrator-sandbox repo | Gitea operations на `admin/orchestrator-sandbox` |
+| C: cleanup в finally | Артефакты удаляются даже при ошибке |
+
+---
+
+## Добавление в деплой-хук
+
+```bash
+# В deploy.sh, после docker-compose up -d orchestrator-staging
+docker exec orchestrator-staging \
+  python3 /repos/orchestrator/scripts/staging_check.py --mode stub
+if [ $? -ne 0 ]; then
+  echo "Staging check FAILED — rolling back"
+  exit 1
+fi
+```

docs/work-items/ORCH-016/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: Единообразные коммент-артефакты в Plane от всех агентов
+
+Work Item ID: ORCH-016
+
+## Description
+
+TBD

docs/work-items/ORCH-016/01-brd.md

@@ -0,0 +1,85 @@
+# BRD: Единообразные коммент-артефакты в Plane от всех агентов
+
+Work Item ID: **ORCH-016**
+Стадия: analysis
+Автор: analyst
+Дата: 2026-06-05
+Ревизия: 2 (учтён фидбэк стейкхолдера от 2026-06-05 — добавить длительность работы агента в коммент)
+
+---
+
+## 1. Бизнес-цель
+Стейкхолдер (Слава) должен мочь из ленты комментариев задачи в Plane **за один клик** перейти к артефакту любого агента (ADR, PR, ревью, отчёт тестера, деплой-лог), а не разбирать «шумные» строки без удобной ссылки и человекочитаемого описания.
+Помимо ссылок, по комментариям стейкхолдер хочет **видеть, сколько работал каждый агент** (длительность стадии), не открывая БД оркестратора и не лезя в `agent_runs`.
+
+## 2. Мотивация
+Сейчас в Plane комменты двух разных стилей:
+
+| Кто пишет | Формат коммента | Источник |
+|-----------|-----------------|----------|
+| **Аналитик (эталон)** | HTML: человеческое описание стадии + `<ul>` со списком ссылок на артефакты, заголовок «Документы:» | `src/stage_engine.py::_build_analyst_ready_comment` (PR #13) |
+| Architect / Developer / Reviewer / Tester / Deployer | Однострочник «{icon} Role готов · 8.5M in / 45.8k out · $7.29» + markdown-ссылки следом | `src/usage.py::usage_comment` + `artifact_links` |
+
+Проблемы второго формата:
+1. Нет человеческого описания результата стадии — есть только техническая метрика «tokens/cost».
+2. Нет краткого вердикта одной строкой там, где он есть в артефакте (Reviewer `APPROVE/REQUEST_CHANGES`, Tester `PASS/FAIL`, Deployer `SUCCESS/FAILED`).
+3. Формат разнится по агентам (где-то «📂 Branch + 🔗 PR», где-то «📄 Test report») — нет единого визуального якоря.
+4. **Не видно длительности стадии** — стейкхолдер не понимает, агент отработал за 30 секунд или за 12 минут; это важная метрика для оценки SLA, поведения долгих стадий (testing/deploy) и подозрений на «зависание».
+
+## 3. Целевая аудитория
+- **Стейкхолдер задачи (Слава, владелец продукта)** — главный потребитель ленты комментариев в Plane.
+- **Reviewer / QA / DevOps по другим проектам (enduro-trails)** — те же ссылки помогут им навигироваться по задачам, не открывая БД оркестратора.
+
+## 4. Scope (что входит)
+1. Привести коммент-формат **architect, developer, reviewer, tester, deployer** к единому виду по эталону аналитика:
+   - заголовок-роль (emoji + имя роли),
+   - короткое человеческое описание результата стадии (1 предложение),
+   - кликабельная ссылка(и) на СВОЙ артефакт,
+   - **одна строка-вердикт** там, где это уместно (Reviewer / Tester / Deployer),
+   - **одна строка-длительность** работы агента — для всех ролей, включая аналитика.
+2. Переиспользовать `settings.gitea_public_url` для кликабельных ссылок (готово в PR #14).
+3. Сохранить существующее поведение аналитика (PR #13) — он уже соответствует целевому формату; в идеале — переиспользовать общий хелпер. К аналитику также добавляется строка длительности.
+4. Один коммент на агента за прохождение стадии (без спама).
+5. Источник длительности — уже существующая метрика `_duration_s` в `src/agents/launcher.py` (или `agent_runs.started_at` / `finished_at`). Новых таблиц/полей в БД не заводим.
+
+## 5. Out of scope (что НЕ трогаем)
+- Логика Quality Gates (`src/qg/checks.py`).
+- Status-only verdict model (PR #12) — приёмка аналитика через смену статуса Plane на «Approved/Rejected».
+- Дедупликация вебхуков (`src/webhooks/_dedup.py`).
+- `set_issue_done`, `notify_done`, `notify_qg_failure` — внутренние нотификации остаются как есть.
+- Per-agent bot-авторство (PR с `PLANE_BOT_TOKENS`) — сохраняется.
+- Изменение схемы БД, конвейера стадий, реестра QG.
+
+## 6. Бизнес-требования
+**BR-1.** Каждый агент по завершении своей стадии (вне пути ошибки) пишет в Plane **ровно один** коммент в едином формате.
+**BR-2.** Коммент содержит:
+- заголовок с emoji-иконкой роли и человекочитаемым названием,
+- 1–2 предложения с описанием результата стадии на русском языке,
+- кликабельную ссылку (-и) на артефакт(ы) этого агента в Gitea,
+- одну строку вердикта (Verdict / Status), если артефакт его содержит,
+- **одну строку длительности работы агента** (`Длительность: <human-format>`), всегда, если значение известно.
+**BR-3.** Ссылки строятся через `gitea_public_url` (fallback на `gitea_url`).
+**BR-4.** Формат должен быть устойчив: отсутствующий артефакт / отсутствующий вердикт / неизвестная длительность не ломают коммент — соответствующая строка просто опускается.
+**BR-5.** Изменение **не нарушает**:
+- status-only verdict model (аналитик по-прежнему ждёт смены статуса Plane),
+- дедуп комментов и вебхуков,
+- работу `set_issue_done` / `notify_done` на финале конвейера,
+- per-agent bot-авторство.
+**BR-6.** Длительность отображается в человекочитаемой форме (`12s`, `4m 12s`, `1h 03m`), а не в виде голых секунд. Источник — `agent_runs.started_at` / `finished_at` (или уже посчитанный `_duration_s` в `launcher.py`). Новых полей в БД не вводится.
+
+## 7. Ограничения и риски
+- **Self-hosting:** оркестратор правит сам себя; деплой только через staging-гейт (порт 8501) → прод-контейнер `orchestrator` не перезапускать в рамках задачи.
+- Прод обслуживает другие проекты (enduro-trails) — нельзя сломать комменты в их задачах.
+- Plane Bot-авторство (`_headers_for`) должно остаться — коммент пишется под бот-токеном своей роли.
+- Reviewer/tester вердикты читаются из артефактов; нужно идемпотентно работать, если артефакт ещё не закоммичен / не доступен в worktree.
+
+## 8. Связки
+- PR #13 — `status-only analyst comment with doc links` (эталон формата аналитика).
+- PR #14 — `external gitea_public_url for clickable doc links` (источник кликабельных ссылок).
+- ADR не требуется: сквозной архитектурный сдвиг отсутствует, меняем только формирование текста коммента в существующем потоке.
+
+## 9. Критерии успеха (high-level)
+- Слава открывает любую задачу в Plane и в ленте видит однотипные карточки от каждого агента: «{role} — {описание} → ссылка [Verdict: …] [Длительность: …]».
+- По любой ссылке открывается соответствующий документ в Gitea (HTTP 200, корректный путь).
+- В каждом статус-комменте присутствует строка «Длительность: …» с человекочитаемым значением (`12s` / `4m 12s` / `1h 03m`).
+- Никаких регрессий в существующих тестах `tests/`.

docs/work-items/ORCH-016/02-trz.md

@@ -0,0 +1,174 @@
+# ТЗ: Единообразные коммент-артефакты в Plane от всех агентов
+
+Work Item ID: **ORCH-016**
+Стадия: analysis → architecture → development
+Автор: analyst
+Дата: 2026-06-05
+Ревизия: 2 (по фидбэку стейкхолдера — добавлен §2.5 Duration; обновлены §1, §2.1, §6)
+
+> Контракт: что именно меняем в коде / какие модули задействованы / какие проверки появятся.
+> Архитектурные решения принимает архитектор; здесь — границы изменения.
+
+---
+
+## 1. Задействованные модули
+
+| Модуль | Роль в изменении |
+|--------|------------------|
+| `src/usage.py` | **Главная точка изменения.** Здесь сейчас живут `usage_comment()`, `artifact_links()`, `AGENT_ARTIFACT`, `AGENT_DISPLAY`, `AGENT_ICON` — основа форматирования. Нужно расширить/добавить хелпер построения единого status-коммента + утилитку форматирования длительности (`fmt_duration(seconds: int) -> str`). |
+| `src/stage_engine.py` | Эталонная функция аналитика `_build_analyst_ready_comment()`. По возможности — переиспользовать новый общий хелпер (или хотя бы выровнять формат: emoji + заголовок + описание + список ссылок). К аналитику также прикручиваем строку длительности (см. §2.5). |
+| `src/agents/launcher.py` | `_post_usage_comments()` — точка, где постится коммент по завершении агента (architect/developer/reviewer/tester/deployer). Должен звать новый хелпер. `_duration_s` уже считается на строке `391` — пробросить его (или достать из `agent_runs.started_at`/`finished_at`) в хелпер. |
+| `src/db.py` | **Только для чтения** в рантайме коммент-хелпера: `agent_runs.started_at`, `agent_runs.finished_at` (уже существуют). Никаких ALTER. |
+| `src/plane_sync.py` | `add_comment()` — без изменений (используется как транспорт). |
+| `src/qg/checks.py` | **Только для чтения**: модели парсинга frontmatter `verdict:` / `deploy_status:` / `staging_status:` — переиспользуем эту логику (вынести в отдельную утилитку, либо импортировать там, где она уже есть). |
+| `src/config.py` | `settings.gitea_public_url`, `settings.gitea_owner`, `settings.gitea_url` — без изменений, переиспользуются. |
+
+## 2. Контракт нового коммент-формата
+
+### 2.1 Структура (одинакова для всех агентов)
+```
+{ICON} {RoleName} — {one-line human description of stage result}
+
+[Verdict / Status: <VALUE>]            # опционально, см. 2.3
+Длительность: <human-format>           # см. 2.5; опускается, только если значение неизвестно
+<b>Документы:</b>
+  • <a href="…">{label}</a>            # одна или несколько ссылок
+```
+
+Поля:
+- `{ICON}` — берётся из `AGENT_ICON` (уже есть в `usage.py`).
+- `{RoleName}` — из `AGENT_DISPLAY` (уже есть).
+- `{description}` — фиксированная строка на роль, см. 2.2.
+- Verdict / Status — см. 2.3, опускается если не извлекается.
+- Длительность — см. 2.5, печатается всегда, когда значение есть; по умолчанию доступна (это нативная метрика `agent_runs`).
+- Ссылки — см. 2.4.
+
+### 2.2 Описания стадий (per-agent text)
+
+| Агент | Описание (рус.) |
+|-------|------------------|
+| analyst | «Подготовил BRD / ТЗ / Acceptance Criteria. Для продвижения переведите задачу в статус Approved.» (как сейчас в `_build_analyst_ready_comment`) |
+| architect | «Завершил архитектурную проработку. См. ADR ниже.» |
+| developer | «Завершил разработку. См. PR / branch ниже.» |
+| reviewer | «Завершил ревью изменений.» |
+| tester | «Завершил прогон тестов.» |
+| deployer | «Завершил деплой.» |
+
+Точные формулировки финализирует architect; аналитик фиксирует **факт** наличия 1-предложного описания на каждую роль.
+
+### 2.3 Verdict / Status строка
+
+Печатается отдельной строкой над списком документов. Источник — frontmatter артефакта; парсить идемпотентно (если файл недоступен — строку пропустить):
+
+| Агент | Поле | Где парсим | Возможные значения | Формат строки |
+|-------|------|------------|---------------------|----------------|
+| analyst | — | — | — | не печатается |
+| architect | — | — | — | не печатается |
+| developer | — | — | — | не печатается (CI-статус — отдельный гейт) |
+| reviewer | `verdict:` | `docs/work-items/<wid>/12-review.md` (YAML-frontmatter) | `APPROVE` / `REQUEST_CHANGES` | `Verdict: APPROVE` |
+| tester | `verdict:` (или эквивалентный фронт-кей) | `docs/work-items/<wid>/13-test-report.md` | `PASS` / `FAIL` | `Verdict: PASS` |
+| deployer | `staging_status:` (для deploy-staging) / `deploy_status:` (для deploy) | `15-staging-log.md` / `14-deploy-log.md` | `SUCCESS` / `FAILED` | `Status: SUCCESS` |
+
+Если значение в frontmatter отсутствует или не распознано → строка `Verdict / Status` НЕ выводится (вердикт-парсинг гейтов и сама логика гейтов не меняется).
+
+### 2.4 Ссылки на артефакты
+
+Базовый URL: `(settings.gitea_public_url or settings.gitea_url).rstrip('/')`.
+Префикс: `/{owner}/{repo}/src/branch/{branch}/`.
+
+| Агент | Артефакты (label → путь) |
+|-------|----------------------------|
+| analyst | BRD `01-brd.md`, ТЗ `02-trz.md`, AC `03-acceptance-criteria.md`, Test Plan `04-test-plan.yaml` *(уже есть)* |
+| architect | ADR-папка `docs/work-items/<wid>/06-adr/` *(уже есть)* |
+| developer | Branch `…/src/branch/<branch>`, PR `…/pulls/<num>` *(уже есть)* |
+| reviewer | Review `docs/work-items/<wid>/12-review.md` *(уже есть)* |
+| tester | Test report `docs/work-items/<wid>/13-test-report.md` *(уже есть)* |
+| deployer | Deploy log `docs/work-items/<wid>/14-deploy-log.md`; staging-лог `15-staging-log.md` (если применимо к стадии) |
+
+Несуществующий файл в worktree → ссылка опускается (как сейчас в `_build_analyst_ready_comment`).
+
+### 2.5 Строка длительности работы агента
+
+**Что печатаем:** одну строку вида `Длительность: {human}` (или `Duration: {human}` — финальную локализацию метки фиксирует архитектор; русский предпочтителен, остальные комменты уже на русском).
+
+**Источник значения (приоритет сверху вниз):**
+
+1. **Параметр функции** — `_post_usage_comments()` в `src/agents/launcher.py:682` вызывается из контекста, где `_duration_s` уже посчитан на строке `391` (`int(time.time() - _start_ts)`). Простейший путь — пробросить `duration_s` явным аргументом в `usage_comment(...)` / новый `build_status_comment(...)`.
+2. **Fallback из БД** — если параметр не передан (например, для аналитика, чей коммент строится в `_build_analyst_ready_comment` в `src/stage_engine.py:298`), читаем
+   ```sql
+   SELECT
+     CAST((julianday(finished_at) - julianday(started_at)) * 86400 AS INTEGER)
+   FROM agent_runs
+   WHERE task_id = ? AND agent = ?
+   ORDER BY id DESC LIMIT 1
+   ```
+   Это последний завершённый run этой роли по задаче.
+3. **Если оба источника пусты / `None` / отрицательны** — строка `Длительность:` НЕ печатается (graceful, как и для вердикта).
+
+**Форматирование (`fmt_duration(seconds: int) -> str` в `src/usage.py`):**
+
+| Диапазон | Формат | Пример |
+|----------|--------|--------|
+| `0 ≤ s < 60` | `{s}s` | `12s`, `45s` |
+| `60 ≤ s < 3600` | `{m}m {ss}s` | `4m 12s`, `1m 03s` |
+| `s ≥ 3600` | `{h}h {mm}m` (секунды отбрасываем) | `1h 03m`, `2h 47m` |
+
+Округление: целые секунды (input — `int`). При `s == 0` всё равно печатаем `0s` (видно, что метрика известна и стадия отработала почти мгновенно).
+
+**Покрытие ролей:** строка длительности добавляется для **всех** агентов, включая аналитика. Для аналитика — строго через fallback из `agent_runs` (его коммент строится в `stage_engine.py`, не в `launcher.py`).
+
+**Что НЕ делаем:**
+- Не меняем схему `agent_runs` (поля `started_at` / `finished_at` уже есть, `_duration_s` уже считается).
+- Не изобретаем новый отдельный коммент с длительностью — длительность встраивается в существующий status-коммент.
+- Не считаем «время от первого вебхука до коммента» — берём чистое время процесса агента (тот же `_duration_s`, что попадает в `notify_agent_finished`), чтобы значение совпадало с тем, что уже видно в Telegram live tracker / логах.
+
+### 2.6 Один коммент на агента за стадию
+Текущий триггер — `_post_usage_comments()` вызывается **один раз** в успешном auto-advance пути после агента. Никаких новых триггеров не добавляем. Дубликаты исключены текущей логикой (одно завершение агента → один коммент).
+
+### 2.7 Usage-метрики (токены / стоимость)
+Текущий `usage_comment()` встраивает «8.5M in / 45.8k out · $7.29» в первый строкой. По требованиям Славы это «без раздувания», но не запрещено явно. Решение:
+- **Сохранить** usage-метрику как **последнюю строку** коммента (мелким техническим хвостом, например `<sub>8.5M in / 45.8k out · $7.29 · Длительность: 4m 12s</sub>`), либо
+- **Перенести** в `task_summary_comment` (только для финального deployer-summary).
+
+Финальный выбор — за архитектором (см. вопрос Q-1 в `10-tech-risks.md`). Длительность из §2.5 — **отдельная** строка от usage-метрики и присутствует независимо от того, как решится вопрос про токены/стоимость.
+
+### 2.8 Бот-авторство
+`plane_add_comment(..., author=<role>)` — сохраняется. Все агенты комментируют под своим bot-токеном (`PLANE_BOT_TOKENS`). Изменения формата текста на это не влияют.
+
+## 3. Изменения API
+**Нет.** Внешние webhooks (`/webhook/plane`, `/webhook/gitea`), `/health`, `/status`, `/queue` — не меняются.
+
+## 4. Изменения схемы БД
+**Нет.** Используются существующие таблицы `tasks`, `agent_runs`, `jobs`.
+
+## 5. Новые Quality Gate checks
+**Нет.** Гейты не меняются. Парсинг `verdict:` / `deploy_status:` / `staging_status:` в коммент — отдельная утилитка, не QG.
+
+## 6. Требования к коду
+- Все новые функции — с docstring (зачем нужны, какие инварианты сохраняют).
+- Парсинг frontmatter артефакта — graceful: исключение → строка вердикта опускается, лог в `logger.debug`.
+- Чтение длительности — graceful: исключение или `None` → строка длительности опускается, лог в `logger.debug`. Отрицательные / нулевые значения: `0` печатается как `0s`, отрицательные опускаются.
+- `fmt_duration(seconds: int) -> str` — чистая, без БД-зависимостей, легко тестируется юнитом.
+- Никаких новых внешних зависимостей: использовать `pyyaml` (уже в проекте) или существующий парсер frontmatter из `src/qg/checks.py`.
+- Поведение для проектов **без** артефактов (например, ENDURO-* до запуска агента) — graceful no-op: коммент с описанием и без ссылок (минимум — заголовок).
+- HTML (как у аналитика) предпочтительнее markdown — Plane корректно рендерит `<ul><li><a>` и `<b>`.
+
+## 7. Артефакты по pipeline
+- `06-adr/` — **не требуется** (нет архитектурного сдвига; обсуждается локально архитектором, в случае спорного решения по 2.6 — заводим ADR `ADR-001-status-comment-format.md`).
+- `07-infra-requirements.md` — **не требуется** (нет новой инфраструктуры).
+- `08-data-requirements.md` — **не требуется** (БД не меняется).
+- `12-review.md` / `13-test-report.md` / `14-deploy-log.md` — формируются на соответствующих стадиях по канону.
+- `CHANGELOG.md` — обновить в том же PR (раздел `Unreleased`).
+
+## 8. Документация
+В том же PR обновить:
+- `docs/architecture/README.md` — короткое упоминание единого формата комментов (можно в раздел «Plane Sync»).
+- `docs/architecture/internals.md` — если там есть раздел про `usage.py`/комменты — обновить.
+- `CLAUDE.md` — без изменений (правила не меняются).
+
+## 9. Чего НЕ делать
+- Не менять реестр `QG_CHECKS`.
+- Не менять `STAGE_TRANSITIONS`.
+- Не менять `add_comment` / `_headers_for` / `PLANE_BOT_TOKENS`.
+- Не «комментировать» комменты других стадий задним числом.
+- Не использовать `--no-verify` при коммитах.

docs/work-items/ORCH-016/03-acceptance-criteria.md

@@ -0,0 +1,125 @@
+# Acceptance Criteria: Единообразные коммент-артефакты в Plane
+
+Work Item ID: **ORCH-016**
+Ревизия: 2 (по фидбэку стейкхолдера — все AC по агентам обновлены под строку длительности; добавлены AC-13 / AC-14)
+
+Каждый AC сформулирован как чёткое условие PASS/FAIL. Проверяется автоматически (unit/integration) либо ручной верификацией в staging Plane (порт 8501).
+
+---
+
+## AC-1. Архитектор пишет единообразный коммент
+- **Given** task завершила стадию `architecture` успешно, `06-adr/` содержит как минимум один ADR.
+- **When** `_post_usage_comments(agent="architect", ...)` вызывается.
+- **Then** в Plane появляется **ровно один** коммент со структурой:
+  - первая строка: `📐 Architect — Завершил архитектурную проработку. См. ADR ниже.`,
+  - строка `Длительность: <human>` (формат — см. AC-13), значение соответствует фактическому времени работы архитектора (±1с),
+  - блок «Документы:» с кликабельной ссылкой на `…/src/branch/<branch>/docs/work-items/<wid>/06-adr/`,
+  - **нет** строки `Verdict / Status`.
+- **And** автор коммента — `architect` (`PLANE_BOT_TOKENS["architect"]`, fallback на shared token).
+- **PASS** при выполнении всех пунктов; **FAIL** при отсутствии любого.
+
+## AC-2. Разработчик пишет единообразный коммент
+- **Given** task завершила стадию `development`, есть open PR.
+- **When** `_post_usage_comments(agent="developer", ...)` вызывается.
+- **Then** коммент в Plane:
+  - `💻 Developer — Завершил разработку. См. PR / branch ниже.`,
+  - строка `Длительность: <human>`,
+  - ссылки: `Branch <branch>` → `…/src/branch/<branch>`, `PR #<num>` → `…/pulls/<num>`,
+  - **нет** строки `Verdict`.
+
+## AC-3. Ревьюер пишет коммент с вердиктом
+- **Given** `12-review.md` содержит frontmatter `verdict: APPROVE` (или `REQUEST_CHANGES`).
+- **When** `_post_usage_comments(agent="reviewer", ...)` вызывается.
+- **Then** коммент:
+  - `🔎 Reviewer — Завершил ревью изменений.`,
+  - строка `Verdict: APPROVE` (или `REQUEST_CHANGES`) — содержимое соответствует frontmatter,
+  - строка `Длительность: <human>`,
+  - ссылка `Review` → `…/12-review.md`.
+- **And** если frontmatter не содержит `verdict:` или файл недоступен — строка `Verdict:` опускается, остальное (в т.ч. длительность) публикуется.
+
+## AC-4. Тестер пишет коммент с вердиктом
+- **Given** `13-test-report.md` содержит frontmatter `verdict: PASS` (или `FAIL`).
+- **When** `_post_usage_comments(agent="tester", ...)` вызывается.
+- **Then** коммент:
+  - `🧪 Tester — Завершил прогон тестов.`,
+  - строка `Verdict: PASS` (либо `FAIL`),
+  - строка `Длительность: <human>`,
+  - ссылка `Test report` → `…/13-test-report.md`.
+
+## AC-5. Деплоер пишет коммент со статусом
+- **Given** task прошла стадию `deploy` (или `deploy-staging`), артефакт-лог существует с frontmatter `deploy_status: SUCCESS` (или `staging_status: SUCCESS`).
+- **When** `_post_usage_comments(agent="deployer", ...)` вызывается.
+- **Then** коммент:
+  - `🚀 Deployer — Завершил деплой.`,
+  - строка `Status: SUCCESS` (или `FAILED`),
+  - строка `Длительность: <human>`,
+  - ссылка `Deploy log` → `…/14-deploy-log.md` (и/или `Staging log` → `…/15-staging-log.md` для staging-стадии).
+
+## AC-6. Аналитик не регрессирует
+- **Given** существующий поток PR #12/#13 (status-only verdict).
+- **When** аналитик завершает стадию `analysis` с готовыми `01..04`.
+- **Then** в Plane:
+  - issue переведён в `In Review` (не меняется),
+  - коммент содержит **то же** человеческое описание (Approved/Rejected инструкции) и список ссылок `BRD / ТЗ / AC / Test Plan` — формат либо идентичен текущему, либо построен через тот же общий хелпер, что и остальные агенты, без потери смысла,
+  - дополнительно к существующему содержимому в комменте присутствует строка `Длительность: <human>` — значение поднимается из `agent_runs` (последний завершённый run агента `analyst` для этой задачи).
+
+## AC-7. Один коммент на агента за стадию
+- **Given** агент успешно отработал стадию.
+- **When** наблюдаем ленту Plane.
+- **Then** для **каждого** агента (`architect`, `developer`, `reviewer`, `tester`, `deployer`) на стадию приходится **ровно один** status-коммент с артефактами. Дополнительные сервисные комменты (`notify_stage_change`, `notify_qg_failure`, `notify_done`) сохраняются — они не считаются status-комментом.
+
+## AC-8. Graceful fallback при отсутствии артефакта
+- **Given** артефакт (например, `12-review.md`) ОТСУТСТВУЕТ в worktree на момент коммента (нестандартный сценарий).
+- **When** `_post_usage_comments(agent="reviewer", ...)` вызывается.
+- **Then** коммент всё равно публикуется: заголовок + описание, без ссылки на отсутствующий артефакт и без строки `Verdict:`. Исключения не пробрасываются.
+
+## AC-9. Кликабельность через gitea_public_url
+- **Given** в `.env` задан `GITEA_PUBLIC_URL=https://git.mva154.duckdns.org`, отличный от `GITEA_URL`.
+- **When** любой агент пишет status-коммент.
+- **Then** href всех артефакт-ссылок начинается с `https://git.mva154.duckdns.org/` (а не с внутреннего `gitea_url`).
+- **And** при отсутствии `gitea_public_url` (пустая строка) — fallback на `gitea_url` (обратная совместимость).
+
+## AC-10. Существующие тесты зелёные
+- **Given** новый код влит в feature-ветку.
+- **When** запускается `pytest tests/ -q`.
+- **Then** все ранее существовавшие тесты проходят (нет регрессий status-only verdict, дедупа, `set_issue_done`).
+
+## AC-11. Quality Gates не меняются
+- **Given** изменения формата комментов.
+- **When** инспектируется `src/qg/checks.py` и `src/stages.py`.
+- **Then** реестр `QG_CHECKS` и `STAGE_TRANSITIONS` остаются идентичными версии до PR (diff в этих файлах = ∅).
+
+## AC-12. Документация обновлена
+- **Given** реализация добавлена в feature-ветку.
+- **When** reviewer проверяет PR.
+- **Then** в diff присутствуют обновления:
+  - `CHANGELOG.md` (раздел Unreleased, описание изменения — включая «строку длительности агента в комментах»),
+  - `docs/architecture/README.md` или `docs/architecture/internals.md` (упоминание единого формата status-комментов и строки длительности).
+- **And** при отсутствии обновлений документации reviewer ставит `verdict: REQUEST_CHANGES` (правило проекта).
+
+## AC-13. Формат строки длительности
+- **Given** утилитка `fmt_duration(seconds: int) -> str` в `src/usage.py`.
+- **When** ей передаются граничные значения.
+- **Then** возвращаемая строка соответствует таблице:
+  - `0` → `"0s"`
+  - `12` → `"12s"`
+  - `59` → `"59s"`
+  - `60` → `"1m 00s"`
+  - `252` → `"4m 12s"`
+  - `3599` → `"59m 59s"`
+  - `3600` → `"1h 00m"`
+  - `3780` → `"1h 03m"`
+  - `10020` → `"2h 47m"`
+- **And** ввод `None` или отрицательное значение → функция возвращает пустую строку (или `None`), а вызывающая сторона строку `Длительность:` не печатает.
+- **PASS** при полном совпадении со всеми примерами таблицы.
+
+## AC-14. Длительность — graceful fallback
+- **Given** агент завершился, но `_duration_s` не пробрасывается явным параметром в коммент-хелпер (например, для аналитика).
+- **When** строится status-коммент.
+- **Then** хелпер запрашивает БД: последний `agent_runs` для `(task_id, agent)` с непустым `finished_at`, считает `int((julianday(finished_at) - julianday(started_at)) * 86400)` и подставляет в `fmt_duration`.
+- **And** при отсутствии подходящей строки `agent_runs` (или `finished_at IS NULL`, или результат < 0) — строка `Длительность:` опускается; остальные части коммента (заголовок, описание, вердикт, ссылки) публикуются без изменений.
+- **And** ошибка чтения БД не пробрасывает исключение наружу — логируется в `logger.debug` и трактуется как «значение неизвестно».
+
+---
+
+**Финальный PASS задачи:** все AC-1…AC-14 = PASS.

docs/work-items/ORCH-016/04-test-plan.yaml

@@ -0,0 +1,154 @@
+work_item: ORCH-016
+title: "Единообразные коммент-артефакты в Plane от всех агентов"
+revision: 2  # +TC-21..TC-25 по длительности (фидбэк стейкхолдера)
+tests:
+
+  - id: TC-01
+    type: unit
+    description: "build_status_comment(architect, duration_s=312, ...) формирует HTML c заголовком '📐 Architect — …', описанием стадии, строкой 'Длительность: 5m 12s' и ссылкой на 06-adr/. Строки Verdict нет."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "build_status_comment(developer, branch=..., pr_number=42, duration_s=...) включает ссылки на branch и на PR #42 через gitea_public_url + строку 'Длительность: ...'. Строки Verdict нет."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "build_status_comment(reviewer, duration_s=..., ...) при verdict=APPROVE в 12-review.md frontmatter выводит строку 'Verdict: APPROVE', строку 'Длительность: ...' и ссылку на 12-review.md."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "build_status_comment(reviewer, ...) при verdict=REQUEST_CHANGES выводит 'Verdict: REQUEST_CHANGES'. Строка длительности сохраняется."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "build_status_comment(reviewer, ...) при отсутствии файла 12-review.md публикует коммент без строки Verdict и без ссылки Review (graceful), при этом строка 'Длительность: ...' печатается, если duration_s передан."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "build_status_comment(tester, ...) при verdict=PASS в 13-test-report.md выводит 'Verdict: PASS', строку 'Длительность: ...' и ссылку на 13-test-report.md."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "build_status_comment(tester, ...) при verdict=FAIL выводит 'Verdict: FAIL'. Строка длительности сохраняется."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-08
+    type: unit
+    description: "build_status_comment(deployer, ...) при deploy_status=SUCCESS в 14-deploy-log.md выводит 'Status: SUCCESS', строку 'Длительность: ...' и ссылку на 14-deploy-log.md."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "build_status_comment(deployer, stage='deploy-staging') читает staging_status: из 15-staging-log.md и выводит соответствующую строку Status + строку длительности."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-10
+    type: unit
+    description: "URL ссылок строится через settings.gitea_public_url когда он задан; иначе — через settings.gitea_url (fallback)."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-11
+    type: unit
+    description: "Аналитик: _build_analyst_ready_comment (или его замена общим хелпером) сохраняет существующий контракт — текст про Approved/Rejected статус + список существующих BRD/ТЗ/AC/Test Plan ссылок. Дополнительно: при наличии завершённой строки agent_runs(analyst) для задачи коммент содержит строку 'Длительность: ...'."
+    module: tests/test_analyst_comment_regression.py
+    expected: PASS
+
+  - id: TC-12
+    type: unit
+    description: "Парсер frontmatter (verdict / deploy_status / staging_status) возвращает None при отсутствии файла, пустом файле или некорректном YAML — без проброса исключения."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-13
+    type: integration
+    description: "_post_usage_comments(agent='reviewer', ...) вызывает plane_sync.add_comment ровно один раз; передаваемый текст содержит '🔎 Reviewer', 'Verdict:', 'Длительность:' и href на 12-review.md."
+    module: tests/test_post_usage_comments_integration.py
+    expected: PASS
+
+  - id: TC-14
+    type: integration
+    description: "_post_usage_comments(agent='tester', ...) вызывает add_comment ровно один раз с автором 'tester' и корректным текстом, включая строку 'Длительность: ...'."
+    module: tests/test_post_usage_comments_integration.py
+    expected: PASS
+
+  - id: TC-15
+    type: integration
+    description: "_post_usage_comments(agent='deployer', ...) для стадии deploy постит коммент со ссылкой на 14-deploy-log.md, строкой 'Длительность: ...' И task_summary_comment (если оно сохраняется) — поведение не регрессирует."
+    module: tests/test_post_usage_comments_integration.py
+    expected: PASS
+
+  - id: TC-16
+    type: integration
+    description: "Регрессия status-only verdict model: при завершении analyst issue переводится в In Review, постится один коммент аналитика с инструкцией про статус Approved/Rejected, никакой автомат-advance не происходит."
+    module: tests/test_analyst_status_only_regression.py
+    expected: PASS
+
+  - id: TC-17
+    type: integration
+    description: "Регрессия дедупликации: повторный вебхук Plane с тем же event_id не приводит ко второму status-комменту от агента."
+    module: tests/test_status_comment_dedup_regression.py
+    expected: PASS
+
+  - id: TC-18
+    type: integration
+    description: "Регрессия set_issue_done / notify_done: финальный путь deploy→done по-прежнему переводит issue в Done и постит '✅ Task completed!' (отдельным комментом от status-коммента деплоера)."
+    module: tests/test_notify_done_regression.py
+    expected: PASS
+
+  - id: TC-19
+    type: integration
+    description: "Per-agent bot-авторство: status-комменты архитектора/разработчика/ревьюера/тестера/деплоера POST-ятся под соответствующим X-API-Key (PLANE_BOT_TOKENS[role]); fallback на PLANE_HEADERS при отсутствии бот-токена."
+    module: tests/test_status_comment_authorship.py
+    expected: PASS
+
+  - id: TC-20
+    type: unit
+    description: "Quality Gates не изменены: реестр QG_CHECKS и STAGE_TRANSITIONS идентичны контрольному снапшоту (smoke-тест против случайных правок)."
+    module: tests/test_qg_registry_snapshot.py
+    expected: PASS
+
+  - id: TC-21
+    type: unit
+    description: "fmt_duration(seconds) — табличная проверка форматирования: 0→'0s', 12→'12s', 59→'59s', 60→'1m 00s', 252→'4m 12s', 3599→'59m 59s', 3600→'1h 00m', 3780→'1h 03m', 10020→'2h 47m'."
+    module: tests/test_fmt_duration.py
+    expected: PASS
+
+  - id: TC-22
+    type: unit
+    description: "fmt_duration(None) и fmt_duration(-1) возвращают пустую строку (или None); вызывающая сторона при этом строку 'Длительность:' НЕ печатает."
+    module: tests/test_fmt_duration.py
+    expected: PASS
+
+  - id: TC-23
+    type: unit
+    description: "build_status_comment(architect, duration_s=None) и build_status_comment(architect) — коммент НЕ содержит строки 'Длительность:'; остальные строки (заголовок/описание/ссылки) на месте."
+    module: tests/test_status_comment_format.py
+    expected: PASS
+
+  - id: TC-24
+    type: integration
+    description: "Fallback по БД: при отсутствии явного duration_s билдер коммента читает agent_runs.started_at/finished_at для последней завершённой строки (task_id, agent) и подставляет fmt_duration результата. Проверка через тестовую SQLite с заранее проставленными timestamp'ами."
+    module: tests/test_status_comment_duration_db_fallback.py
+    expected: PASS
+
+  - id: TC-25
+    type: integration
+    description: "Регрессия: исключение при чтении agent_runs (например, БД залочена) → строка 'Длительность:' опускается, остальное публикуется; logger.debug содержит запись о неудачном чтении длительности."
+    module: tests/test_status_comment_duration_db_fallback.py
+    expected: PASS

docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md

@@ -0,0 +1,203 @@
+# ADR-001: Единый формат status-коммента агентов в Plane
+
+- **Work Item:** ORCH-016
+- **Стадия:** architecture
+- **Статус:** Accepted
+- **Дата:** 2026-06-05
+- **Автор:** architect
+
+## Контекст
+
+ТЗ ORCH-016 требует привести коммент-формат всех агентов (architect/developer/reviewer/tester/deployer + сохранение совместимости с analyst) к единому виду по эталону `src/stage_engine.py::_build_analyst_ready_comment` и дополнительно встроить **строку длительности работы агента**.
+
+ТЗ оставил архитектору пять открытых вопросов (см. §2.2, §2.5, §2.7, §6):
+1. Где живёт общий хелпер построения коммента (один файл vs. два).
+2. Как ведём себя с usage-метрикой (tokens / $cost) в новом формате (Q-1 из ТЗ §2.7).
+3. Локализация метки длительности — «Длительность:» vs «Duration:».
+4. Парсинг frontmatter артефакта (verdict / deploy_status / staging_status) — переиспользовать `src/qg/checks.py` или дублировать.
+5. Контракт хелпера БД-фоллбэка длительности и его форма.
+
+Дополнительно: текущий `usage_comment(...)` — публичная (внутри проекта) функция, вызывается из `src/agents/launcher.py::_post_usage_comments`. Менять формат «на месте» без явного решения о судьбе старой сигнатуры рискованно.
+
+## Решение
+
+### 1. Архитектура хелперов
+
+Вводим **ровно один публичный хелпер** в `src/usage.py`:
+
+```python
+def build_status_comment(
+    agent: str,                          # "analyst" | "architect" | ... | "deployer"
+    *,
+    repo: str | None = None,
+    branch: str | None = None,
+    work_item_id: str | None = None,
+    pr_number: int | None = None,
+    stage: str | None = None,            # "deploy" vs "deploy-staging" (для deployer)
+    usage: dict | None = None,           # tokens/cost (опционально)
+    duration_s: int | None = None,       # если известно — иначе fallback по БД
+    task_id: int | None = None,          # требуется ТОЛЬКО для DB-фоллбэка длительности
+    worktree_root: str | None = None,    # для чтения артефактов; None → опускаем verdict
+) -> str:
+```
+
+Что делает:
+- Собирает заголовок `{ICON} {RoleName} — {описание}` (описание per-agent — см. §2 ниже).
+- Опционально дописывает строку `Verdict: …` / `Status: …` (только для reviewer/tester/deployer и только если frontmatter артефакта присутствует и распознан).
+- Всегда (если известна) дописывает строку `Длительность: …` через `fmt_duration(...)`.
+- Дописывает блок `<b>Документы:</b><ul><li><a …>…</a></li>…</ul>`.
+- Опционально дописывает технический хвост `<sub>{tokens}/{cost}</sub>` — см. §3.
+
+`_build_analyst_ready_comment(...)` в `src/stage_engine.py` переписывается как **тонкая обёртка** над `build_status_comment(agent="analyst", ...)`. Аналитик-специфичный текст (инструкция «переведите в Approved/Rejected» + полный список 01-brd / 02-trz / 03-acceptance-criteria / 04-test-plan) добавляется ВНУТРИ `build_status_comment` через ветку `agent == "analyst"` — это единственное место, где per-agent текст шире одной строки. Альтернатива (передавать кастомный текст параметром) добавляет API-площадь без пользы.
+
+**Старый `usage_comment(...)` удаляется**; единственный его внешний вызов — `src/agents/launcher.py::_post_usage_comments` — переписывается на `build_status_comment(...)`. Это упрощает дальнейшее сопровождение (один формат → одна функция); риск минимален, потому что `usage_comment` — внутренний API.
+
+### 2. Per-agent описания (финализация ТЗ §2.2)
+
+| Агент | Описание (HTML, без точки в конце) |
+|-------|------------------------------------|
+| analyst | «Подготовил BRD / ТЗ / Acceptance Criteria. Для продвижения переведите задачу в статус Approved» (плюс существующая инструкция про Approved/Rejected уходит как продолжение) |
+| architect | «Завершил архитектурную проработку. См. ADR ниже» |
+| developer | «Завершил разработку. См. PR / branch ниже» |
+| reviewer | «Завершил ревью изменений» |
+| tester | «Завершил прогон тестов» |
+| deployer (deploy) | «Завершил прод-деплой» |
+| deployer (deploy-staging) | «Завершил staging-деплой» |
+
+### 3. Решение по Q-1 (usage-метрика)
+
+**Сохраняем** usage-метрику как **техническую `<sub>`-строку в конце** коммента, объединённую с длительностью НЕ нужно — длительность остаётся ОТДЕЛЬНОЙ строкой нормального веса (требование ТЗ §2.5).
+
+Конкретно:
+```html
+<sub>8.5M in (8.4M cached) / 45.8k out · $7.29</sub>
+```
+
+Почему НЕ удаляем:
+- Тех-метрика полезна для оценки стоимости задачи на пост-мортеме (особенно для ORCH-задач, где orchestrator расходует свой же бюджет).
+- `task_summary_comment` (Deployer end-of-task) суммирует по задаче, но не покрывает per-agent breakdown в момент завершения каждой стадии — для трассировки «кто сколько потратил» полезно видеть сразу.
+
+Почему `<sub>`, а не обычная строка:
+- Стейкхолдер (Слава) явно просил «без раздувания»; визуально приглушённый хвост не конкурирует за внимание с описанием/вердиктом/длительностью/ссылками.
+- Plane корректно рендерит `<sub>` (проверено ранее на PR #13).
+
+При `usage = None` или нулевых значениях — хвост опускается полностью.
+
+### 4. Решение по Q-2 (локализация метки длительности)
+
+Используем русский: **`Длительность: 4m 12s`**.
+Обоснование: все человеческие тексты комментов уже на русском (заголовок «Документы:», описания стадий). Метка `4m 12s` сама по себе универсальна и понятна без перевода (стандарт CLI-инструментов: `time`, `gh`, `kubectl`).
+
+### 5. Решение по Q-4 (парсинг frontmatter)
+
+Создаём НОВЫЙ маленький утилитный модуль **`src/frontmatter.py`** с единственной функцией:
+
+```python
+def read_frontmatter_value(path: str, key: str) -> str | None:
+    """Read a single key from leading YAML frontmatter. Never raises.
+
+    Returns None if file missing, frontmatter absent/malformed, or key not set.
+    """
+```
+
+Реализация — yaml.safe_load на блоке между двумя `---` строками; всё ловится одним `try/except` → `logger.debug` → `None`.
+
+Этот модуль используют:
+- `src/usage.py::build_status_comment` — для извлечения `verdict:` / `deploy_status:` / `staging_status:`.
+- `src/qg/checks.py` — НЕ обязательно мигрировать в этом PR (out-of-scope ORCH-016); миграция может пройти отдельной задачей-рефакторингом. **В этом PR `qg/checks.py` НЕ трогаем** — снижает blast radius и риск регрессии гейтов.
+
+Дублирование (~10 строк YAML-парсера в `qg/checks.py` остаётся) сознательно принято: scope discipline > DRY на одном переиспользовании.
+
+### 6. Решение по Q-5 (DB-фоллбэк длительности)
+
+Хелпер в `src/usage.py`:
+
+```python
+def get_agent_duration(task_id: int, agent: str) -> int | None:
+    """Return last finished agent_runs duration (seconds) for (task, agent).
+    Never raises. None on missing row / NULL finished_at / negative / error.
+    """
+```
+
+SQL — ровно как в ТЗ §2.5 (фоллбэк):
+```sql
+SELECT CAST((julianday(finished_at) - julianday(started_at)) * 86400 AS INTEGER)
+FROM agent_runs
+WHERE task_id=? AND agent=?
+  AND finished_at IS NOT NULL
+ORDER BY id DESC LIMIT 1
+```
+
+Чтение через `get_db()` (стандартный путь модуля), обёрнутое в `try/except Exception` → `logger.debug(...)` → `None`. Соединение всегда закрывается в `finally`.
+
+`build_status_comment` вызывает `get_agent_duration(...)` ТОЛЬКО когда:
+- `duration_s is None`, И
+- `task_id is not None` (вызывающая сторона согласилась оплатить лишний SELECT).
+
+Если оба источника пусты → строка «Длительность:» опускается (AC-14).
+
+### 7. Решение по HTML vs Markdown (ТЗ §6)
+
+Целевой рендер — **HTML**, как у эталона аналитика. Конкретно:
+- Заголовок и описание — plain text + emoji.
+- Verdict / Длительность — отдельные строки, разделяются `<br>` (или `\n` если Plane корректно интерпретирует переводы строк; экспериментально подтвердить на staging — см. R-2 в `10-tech-risks.md`).
+- Блок документов — `<b>Документы:</b><ul><li><a href="…">label</a></li></ul>`.
+- Технический хвост — `<sub>…</sub>` отдельной строкой через `<br>`.
+
+`artifact_links(...)` (сейчас возвращает markdown-строки `[label](url)`) — **переписывается на HTML-якоря** `<a href="...">label</a>`. Эмодзи-префиксы (📂/🔗/📐/📄) сохраняются. Возвращаемый тип меняется: `list[str]` остаётся, но содержимое — HTML-фрагменты (документировано в docstring).
+
+Это breaking-change для внутреннего API `artifact_links`, но единственный внешний вызов был из `usage_comment`, который тоже удаляется. Других вызовов в `tests/`/`scripts/` нет (developer проверит grep'ом в development-стадии).
+
+### 8. Контракт `fmt_duration` (полностью по AC-13)
+
+```python
+def fmt_duration(seconds: int | None) -> str:
+    """0..59 → '{s}s'; 60..3599 → '{m}m {ss:02d}s'; >=3600 → '{h}h {mm:02d}m'.
+    None / negative → '' (caller should drop the line)."""
+```
+
+Чистая функция, без I/O, easily unit-testable. Размещение: `src/usage.py` (рядом с `fmt_tokens` / `fmt_cost`).
+
+## Альтернативы
+
+1. **Два отдельных хелпера** (`build_analyst_status_comment` + `build_agent_status_comment`).
+   Отклонено: ТЗ явно просит «единый эталонный формат»; дублирование шаблона расходится со временем.
+
+2. **Оставить `usage_comment` как deprecated-обёртку.**
+   Отклонено: один внутренний вызов, deprecation добавляет когнитивный шум без выигрыша.
+
+3. **Перенести usage-метрику в `task_summary_comment` (вариант B из ТЗ §2.7).**
+   Отклонено: теряем per-stage видимость затрат; финальный summary не отвечает на вопрос «сколько съел конкретно reviewer».
+
+4. **Markdown вместо HTML.**
+   Отклонено: эталон аналитика (PR #13) уже HTML; смена ломает визуальный паритет.
+
+5. **Английская метка «Duration:».**
+   Отклонено: ассиметрия с остальными русскими подписями в комменте.
+
+6. **Рефакторить `qg/checks.py` на `src/frontmatter.py` в этом же PR.**
+   Отклонено: расширяет blast radius на гейты; делаем отдельной задачей.
+
+## Последствия
+
+### Положительные
+- Единая точка изменения формата комментов на будущее — `build_status_comment`.
+- Удаление дубликата `usage_comment` уменьшает API-площадь модуля.
+- `src/frontmatter.py` подготавливает почву для будущего рефактора `qg/checks.py` (DRY-победа в один заход следующей задачей).
+- HTML-рендеринг даёт стейкхолдеру кликабельные ссылки и приглушённый тех-хвост.
+
+### Отрицательные / ограничения
+- Дублирование YAML-парсинга на ~10 строк (qg/checks.py остаётся со своим).
+- Дополнительный SELECT к `agent_runs` на каждый коммент аналитика (1 запрос, по индексу `task_id`, ничтожно).
+- HTML-разметка ломается визуально, если Plane изменит политику санитизации `<sub>` или `<ul>` (риск R-2).
+
+### Self-hosting
+- Хелперы — чистый код, без рестарта прод-контейнера. Изменения дойдут до прода через стандартный staging-гейт (`deploy-staging` → `deploy`).
+- Если коммент сломается, ленту Plane задачи ORCH-016 первой и заметим — feedback loop коротко.
+
+## Связи
+- ТЗ §1, §2, §6 (`docs/work-items/ORCH-016/02-trz.md`)
+- AC-1..AC-14 (`docs/work-items/ORCH-016/03-acceptance-criteria.md`)
+- PR #13 (эталон аналитика — `_build_analyst_ready_comment`)
+- PR #14 (`gitea_public_url` для кликабельных ссылок)
+- `src/usage.py`, `src/stage_engine.py`, `src/agents/launcher.py`, `src/db.py`, `src/qg/checks.py`

docs/work-items/ORCH-016/10-tech-risks.md

@@ -0,0 +1,112 @@
+# Технические риски — ORCH-016
+
+Work Item: **ORCH-016**
+Стадия: architecture
+Автор: architect
+Дата: 2026-06-05
+
+> Риски ранжированы по приоритету (P0 = блокер, P1 = серьёзный, P2 = умеренный, P3 = информационный).
+> Каждый риск содержит митигацию и/или способ детекции на тестах.
+
+---
+
+## R-1 (P1) — Self-hosting: сломанный коммент => слепая зона по ORCH-задаче
+
+**Описание.** Изменение касается генерации комментов; орк дорабатывает сам себя. Если новый `build_status_comment` падает / отдаёт пустую строку / отдаёт битый HTML, стейкхолдер (Слава) потеряет видимость прогресса именно по той задаче, которая сломала комменты — и не сможет диагностировать без `docker logs`.
+
+**Митигация.**
+- Внешний `try/except Exception` вокруг сборки HTML: при любом исключении возвращаем простой fallback-текст вида `f"{icon} {role} готов"` + `logger.exception(...)`. Лучше «уродливый» коммент, чем тишина.
+- Юнит-тесты `tests/test_status_comment_format.py` (TC-01..TC-12, TC-23) фиксируют золотой HTML — регрессия ловится на CI до прод-деплоя.
+- Обязательный staging-гейт (`check_staging_status` для orchestrator) — финальный предохранитель: задача с ORCH-меткой не дойдёт до прод-контейнера, пока staging-инстанс (8501) не подтвердит, что комменты собираются.
+
+## R-2 (P1) — Plane HTML sanitization: `<sub>` / `<br>` / `<ul>` могут не рендериться
+
+**Описание.** Plane (self-hosted) санитизирует входящий HTML. Эталон аналитика подтверждает рендер `<ul>` / `<li>` / `<a>` / `<b>`; **рендер `<sub>` и `<br>` НЕ подтверждён** на текущей версии Plane.
+
+**Митигация.**
+- На staging (8501) опубликовать тестовый коммент `build_status_comment(...)` руками (через `python -m` скрипт или curl на dev-задачу) и визуально проверить рендер тех-хвоста и переводов строк ПЕРЕД мержем PR.
+- Если `<sub>` не рендерится — fallback: оставить usage-метрику обычной строкой с `· ` разделителем (без `<sub>`).
+- Если `<br>` не рендерится — переходим на `\n` (Plane сам интерпретирует) либо упаковываем строки в `<p>...</p>`.
+- Развилка фиксируется в `12-review.md` reviewer'ом по факту проверки.
+
+**Детекция.** Ручной чек-лист в staging-логе (`15-staging-log.md`) с приложенным скриншотом коммента.
+
+## R-3 (P2) — SQLite contention при DB-фоллбэке длительности
+
+**Описание.** `get_agent_duration(task_id, agent)` делает SELECT по `agent_runs` в момент сборки коммента. SQLite-БД одновременно используется очередью (`jobs`), воркером, вебхуками и Telegram-трекером; пиковая нагрузка → коротко блокирующиеся читатели.
+
+**Митигация.**
+- Запрос идёт по индексу `(task_id, agent)` (если его нет — добавление индекса не входит в scope ORCH-016, но запрос всё равно быстрый: типичный `agent_runs` ≤ 50 строк на задачу).
+- `try/except Exception` оборачивает SELECT → `logger.debug(...)` → `None`. При залоченной БД строка «Длительность:» просто опускается (AC-14).
+- Запрос делаем ТОЛЬКО когда `duration_s` не передан явно (т.е. только для аналитика).
+
+**Детекция.** TC-25 — integration-тест на исключение в чтении `agent_runs`.
+
+## R-4 (P3) — Расхождение значений длительности (param vs DB)
+
+**Описание.** `_duration_s` в `src/agents/launcher.py:391` считается как `int(time.time() - _start_ts)`. DB-фоллбэк считает `(julianday(finished_at) - julianday(started_at)) * 86400`. Возможно расхождение в 1 секунду (округление) или больше (если `finished_at` пишется не сразу).
+
+**Митигация.** AC-13 допускает погрешность ±1с. Для аналитика, где используем только DB-фоллбэк, отклонений между двумя источниками не наблюдается (источник один).
+
+**Не митигируется специально** — последствия нулевые (декоративная строка).
+
+## R-5 (P2) — Скрытые callers `usage_comment` / `artifact_links`
+
+**Описание.** ADR-001 предписывает удалить `usage_comment` и переписать `artifact_links` на HTML. В рамках только grep по `src/` я нашёл единственного клиента — `_post_usage_comments` в `src/agents/launcher.py`. Однако функция могла использоваться скриптами (`scripts/`), тестами (`tests/`), миграционными утилитами или внешними интеграциями.
+
+**Митигация.** Developer на стадии development обязан выполнить полный grep:
+```bash
+grep -rn "usage_comment\|artifact_links" .  --include="*.py"
+```
+И переписать все вызовы. Если найдётся внешний потребитель — оставить `usage_comment` как deprecated-обёртку и зафиксировать в `12-review.md`.
+
+**Детекция.** TC-10 (полный pytest зелёный), TC-17 (дедуп-регрессия), reviewer-чек.
+
+## R-6 (P2) — Регрессия status-only verdict model аналитика (PR #12/#13)
+
+**Описание.** Аналитик переходит в `In Review` И не должен auto-advance'иться — статус ждёт Approved/Rejected от стейкхолдера. Если переписывание `_build_analyst_ready_comment` на обёртку случайно вернёт `auto_advance=True` или поменяет content так, что человек не поймёт инструкцию — порвётся существующий контракт.
+
+**Митигация.**
+- TC-11 + TC-16: регрессионные тесты на формат коммента и status-only поведение.
+- ADR-001 §1 явно фиксирует: контракт аналитика сохраняется; обёртка строит ИДЕНТИЧНЫЙ существующему текст + добавляет только строку длительности.
+
+## R-7 (P3) — Локализация и кодировка emoji в HTML
+
+**Описание.** В `src/usage.py` emoji-ы записаны `\Uxxxxxxxx`-escape'ами. При сборке HTML это безопасно (Python декодирует до utf-8), но при возможном последующем base64/quoted-printable транспорте могла бы возникнуть проблема. Plane API принимает utf-8 → риск минимален.
+
+**Митигация.** Не требуется. Существующий путь (PR #13, аналитик) уже посылает emoji через тот же `add_comment` без проблем.
+
+## R-8 (P3) — Дублирование YAML-парсинга frontmatter
+
+**Описание.** ADR-001 §5 принимает дублирование (~10 строк) в `src/frontmatter.py` и оставляет `src/qg/checks.py` со своим парсером. При расхождении правил (например, мы научим `read_frontmatter_value` поддерживать `---\nkey: value\n---` без trailing newline, а `qg/checks.py` останется строгим) теоретически возможны несогласованные интерпретации.
+
+**Митигация.** Принято в scope discipline; следующая задача-рефактор объединит. До тех пор — `read_frontmatter_value` обязан быть строго совместимым (по тестам) с поведением `qg/checks.py` на канонических случаях (BR-frontmatter с trailing newline после `---`).
+
+## R-9 (P0) — НЕ перезапускать прод-контейнер `orchestrator`
+
+**Описание.** Self-hosting: прод-контейнер (8500) обслуживает ВСЕ проекты (orchestrator + enduro-trails) из общей БД. Внеплановый рестарт ради «быстро посмотреть формат коммента» = простой конвейера всех проектов.
+
+**Митигация.**
+- Все эксперименты — на staging (8501) через `docker compose --profile staging up -d orchestrator-staging`.
+- Прод-деплой только через стандартный путь `deploy-staging → deploy` (под надзором `check_staging_status`).
+- ЗАПРЕЩЕНО при ручном тестировании коммента дёргать `docker compose restart orchestrator`.
+
+---
+
+## Открытые вопросы (Q&A — все закрыты ADR-001)
+
+| Q | Вопрос | Решение | Где зафиксировано |
+|---|--------|---------|-------------------|
+| Q-1 | Куда девать usage-метрику (tokens/cost)? | Сохранить как `<sub>…</sub>` хвостом в том же комменте. | ADR-001 §3 |
+| Q-2 | «Длительность:» или «Duration:»? | «Длительность:» (русский, соответствует остальным меткам). | ADR-001 §4 |
+| Q-3 | Один общий хелпер или раздельные для analyst/прочих? | Один: `build_status_comment(...)`; analyst — ветка внутри. | ADR-001 §1 |
+| Q-4 | Парсер frontmatter — переиспользовать `qg/checks.py` или новый? | Новый `src/frontmatter.py`; `qg/checks.py` НЕ трогаем в этом PR. | ADR-001 §5 |
+| Q-5 | Контракт DB-фоллбэка длительности. | `get_agent_duration(task_id, agent) -> int | None`, см. SQL в ADR-001 §6. | ADR-001 §6 |
+| Q-6 | HTML vs Markdown. | HTML (как у эталона); `artifact_links` переписывается на `<a>`. | ADR-001 §7 |
+| Q-7 | Судьба старого `usage_comment(...)`. | Удалить, перевести единственного клиента (`_post_usage_comments`) на `build_status_comment`. | ADR-001 §1 |
+
+Если developer на стадии development обнаружит, что R-5 материализуется (есть скрытый клиент `usage_comment`) — допустимо оставить `usage_comment` как 1-строчную deprecated-обёртку (`return build_status_comment(...)`) и зафиксировать факт в `12-review.md` без возврата в architecture.
+
+---
+
+*Risk register для ORCH-016. Обновляется reviewer'ом, если в ходе ревью всплывут новые риски — текущий список фиксирует видимое на момент завершения стадии architecture.*

docs/work-items/ORCH-016/12-review.md

@@ -0,0 +1,120 @@
+---
+type: review
+work_item_id: ORCH-016
+verdict: APPROVED
+version: 1
+---
+
+# Review ORCH-016 — Единый status-коммент агентов в Plane
+
+## Summary
+
+PR реализует ТЗ ORCH-016 и ADR-001 полностью: вводится единый хелпер
+`src/usage.build_status_comment(...)` для всех ролей (analyst…deployer),
+строка `Длительность: …` с явным `duration_s` от launcher и DB-фоллбэком для
+аналитика, defensive YAML-парсер `src/frontmatter.read_frontmatter_value`,
+HTML-формат с эмодзи / Verdict / Документы / `<sub>` тех-хвостом. Аналитик
+переведён на ту же ветку без регрессии (`tests/test_analyst_comment.py` +
+`tests/test_analyst_status_only_regression.py` зелёные). `usage_comment` стал
+deprecated-обёрткой, `artifact_links` теперь возвращает HTML-фрагменты
+(breaking-change только для внутреннего вызова из удаляемого пути).
+Документация обновлена: CHANGELOG.md (`Added` + `Changed`),
+`docs/architecture/README.md` (новый подраздел «Plane Sync: единый
+status-коммент агентов»), ADR-001 заведён в
+`docs/work-items/ORCH-016/06-adr/`.
+
+Прохождение тестов:
+- 60 новых ORCH-016 тестов: PASS (TC-01…TC-23 покрывают AC-1…AC-14).
+- TC-20 (`test_qg_registry_snapshot.py`) подтверждает: `QG_CHECKS` и
+  `STAGE_TRANSITIONS` бит-идентичны (AC-11).
+- Полный прогон: 392 PASS, 4 FAIL (`tests/test_m6_sequence.py::*`,
+  `tests/test_plane_webhook.py::test_orchestrator_project_routes_to_orchestrator_repo`,
+  `tests/test_plane_webhook.py::test_prefixes_independent_per_project`).
+  Эти 4 фейла **предсуществуют на `main`** (проверено: `git checkout main --
+  src/ tests/` → те же 4 фейла; ORCH-016 их не индуцировал). AC-10 «no
+  regression» соблюдено.
+
+Соответствие ТЗ (`02-trz.md`):
+- §1 модули: тронуты строго заявленные (`usage.py`, `stage_engine.py`,
+  `agents/launcher.py`, новый `frontmatter.py`); `qg/checks.py` сознательно
+  не трогается (ADR-001 §5, alt-6).
+- §2.1–§2.5 формат, описания, verdict, ссылки, duration — реализовано.
+- §3 API не меняется; §4 БД не меняется; §5 новых QG нет — подтверждено
+  TC-20.
+- §6 docstrings, graceful frontmatter / duration, `fmt_duration` — чистая,
+  AC-13 happy + edge кейсы зелёные.
+- §7 артефакты: ADR заведён.
+- §8 документация: README архитектуры и CHANGELOG обновлены, `CLAUDE.md`
+  не трогается (правила не меняются).
+- §9 запреты: `QG_CHECKS` / `STAGE_TRANSITIONS` / `add_comment` /
+  `_headers_for` / `PLANE_BOT_TOKENS` не тронуты; `--no-verify` не
+  использован.
+
+Соответствие ADR-001:
+- §1 единственный публичный `build_status_comment(...)` с указанной
+  сигнатурой ✓
+- §2 описания per-agent ✓
+- §3 `<sub>` тех-хвост ✓
+- §4 русская метка `Длительность:` ✓
+- §5 `src/frontmatter.py` ✓
+- §6 `get_agent_duration` с указанным SQL ✓
+- §7 HTML-якоря, `<br>` разделители ✓
+- §8 `fmt_duration` контракт ✓
+
+Self-hosting (ADR-001 «Последствия»): хелперы — чистый код, без рестарта
+прод-контейнера; пройдёт стандартный staging-гейт.
+
+## Findings
+
+### P0 — Blocker
+- Нет.
+
+### P1 — Must fix
+- Нет.
+
+### P2 — Should fix
+- Нет.
+
+### P3 — Nice to have
+- `src/usage.py` `_AGENT_DESCRIPTIONS` и встроенные строки в
+  `build_status_comment` (например, `"Длительность: " f"{d_text}"` и
+  `"Завершил " "архитектурную " "проработку. " "См. ADR ниже."`) разбиты
+  на множественные смежные литералы. Python склеит их корректно, но
+  читаемость страдает — рассмотреть однострочный литерал в follow-up.
+- `03-acceptance-criteria.md` AC-3 формулирует пример как
+  `verdict: APPROVE`, тогда как канонический QG (`check_reviewer_verdict`,
+  `src/qg/checks.py:306`) ожидает строго `verdict: APPROVED`. На
+  отображение коммента это не влияет (билдер показывает то, что лежит
+  во frontmatter), но в самом AC лучше было бы зафиксировать тот же
+  термин, что в QG. Чинить артефакт стадии analysis из стадии review —
+  out-of-scope (правило: «не править артефакты других этапов»);
+  оставляю как заметку на follow-up для аналитика.
+- `_post_usage_comments` для `deployer` всегда (включая
+  `deploy-staging`) дополнительно постит `task_summary_comment`. ТЗ §2.6
+  и AC-7 явно это не запрещают (саммари не считается status-комментом),
+  и `tests/test_post_usage_comments_integration.py::test_deployer_staging_picks_15_log`
+  это поведение фиксирует. Поведение работает, но смысловой саммари
+  «Итого по задаче» на staging-стадии (задача не завершена) — слегка
+  ранний. Кандидат на уточнение требований в отдельной задаче.
+
+## Документация
+
+- `CHANGELOG.md` — раздел `Unreleased` дополнен записями `Added` и
+  `Changed` с упоминанием ORCH-016, `build_status_comment`,
+  `fmt_duration`, `get_agent_duration`, `src/frontmatter.py` и
+  ссылки на ADR. ✓
+- `docs/architecture/README.md` — добавлен подраздел «Plane Sync:
+  единый status-коммент агентов (ORCH-016)» с описанием формата
+  HTML-блока, источниками длительности и вердиктов, явным указанием,
+  что реестр гейтов и стадий не меняется. ✓
+- `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md` —
+  заведён, статус `Accepted`, покрывает все 5 открытых вопросов ТЗ
+  и пять альтернатив. ✓
+- `CLAUDE.md` — правки не требовались (правила агентов и канон
+  документации без изменений), что и заявлено в ADR-001.
+- `docs/architecture/internals.md` — упоминания про `usage.py` /
+  комменты не имеет, обновление не требуется (как и оговорено
+  ADR-001 §1).
+
+Документация = golden source соблюдён: изменения в `src/` сопровождены
+синхронным обновлением документации в том же PR.

docs/work-items/ORCH-016/13-test-report.md

@@ -0,0 +1,159 @@
+---
+type: test-report
+work_item_id: ORCH-016
+verdict: PASS
+result: PASS
+version: 1
+---
+
+# Test Report — ORCH-016
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-016-plane`
+- Ветка: `feature/ORCH-016-plane` @ `1778d8f` (reviewer auto-commit)
+- Дата: 2026-06-05
+- Prod-инстанс orchestrator: `/health` → `{"status":"ok"}` (не трогался)
+
+## Команды
+
+```bash
+# Полный регресс из worktree
+pytest tests/ -v --tb=short
+
+# ORCH-016 целевой набор
+pytest tests/test_status_comment_format.py \
+       tests/test_post_usage_comments_integration.py \
+       tests/test_status_comment_authorship.py \
+       tests/test_status_comment_dedup_regression.py \
+       tests/test_status_comment_duration_db_fallback.py \
+       tests/test_fmt_duration.py \
+       tests/test_qg_registry_snapshot.py \
+       tests/test_analyst_comment.py \
+       tests/test_analyst_comment_regression.py \
+       tests/test_analyst_status_only_regression.py \
+       tests/test_notify_done_regression.py -v
+```
+
+## Сводка
+
+| Прогон | Passed | Failed | Skipped |
+|--------|-------:|-------:|--------:|
+| Полный (`tests/`) | **392** | **4** | 6 |
+| ORCH-016 целевой (62 теста) | **62** | **0** | 0 |
+
+## Smoke test API
+
+| Endpoint | HTTP | Ответ |
+|----------|------|-------|
+| `GET /health` | 200 | `{"status":"ok","service":"orchestrator"}` |
+| `GET /status` | 200 | JSON, активна задача `ORCH-016` (stage `testing`) |
+| `GET /queue` | 200 | JSON, `counts={queued:0,running:1,done:36,failed:0}`, breaker `closed`, preflight OK |
+
+## Покрытие плана тестов (`04-test-plan.yaml`)
+
+| TC | Модуль | AC | Результат |
+|----|--------|----|-----------|
+| TC-01 | `test_status_comment_format.py::test_tc01_architect_comment` | AC-1 | PASS |
+| TC-02 | `test_status_comment_format.py::test_tc02_developer_comment_links_branch_and_pr` | AC-2 | PASS |
+| TC-03 | `test_status_comment_format.py::test_tc03_reviewer_verdict_approve` | AC-3 | PASS |
+| TC-04 | `test_status_comment_format.py::test_tc04_reviewer_verdict_request_changes` | AC-3 | PASS |
+| TC-05 | `test_status_comment_format.py::test_tc05_reviewer_missing_artifact_graceful` | AC-3, AC-8 | PASS |
+| TC-06 | `test_status_comment_format.py::test_tc06_tester_pass` | AC-4 | PASS |
+| TC-07 | `test_status_comment_format.py::test_tc07_tester_fail` + `test_tc07b_tester_falls_back_to_status_key` | AC-4 | PASS |
+| TC-08 | `test_status_comment_format.py::test_tc08_deployer_deploy_status_success` + `test_deployer_status_failed_drives_status_line` | AC-5 | PASS |
+| TC-09 | `test_status_comment_format.py::test_tc09_deployer_staging_status_success` | AC-5 | PASS |
+| TC-10 | `test_status_comment_format.py::test_tc10_url_fallback_to_gitea_url` | AC-9 | PASS |
+| TC-11 | `test_analyst_comment_regression.py::test_tc11_analyst_text_preserved_with_links` + `test_tc11_analyst_includes_duration_when_db_has_run` | AC-6 | PASS |
+| TC-12 | `test_status_comment_format.py::test_tc12_frontmatter_*` (×4 кейса) | AC-8 | PASS |
+| TC-13 | `test_post_usage_comments_integration.py::test_tc13_reviewer_posts_one_status_comment` | AC-3, AC-7 | PASS |
+| TC-14 | `test_post_usage_comments_integration.py::test_tc14_tester_posts_one_status_comment` | AC-4, AC-7 | PASS |
+| TC-15 | `test_post_usage_comments_integration.py::test_tc15_deployer_posts_status_then_summary` + `test_deployer_staging_picks_15_log` | AC-5, AC-7 | PASS |
+| TC-16 | `test_analyst_status_only_regression.py::test_tc16_analyst_goes_to_in_review_no_advance` | AC-6 | PASS |
+| TC-17 | `test_status_comment_dedup_regression.py::test_tc17_*` (×4) | AC-7 | PASS |
+| TC-18 | `test_notify_done_regression.py::test_notify_done_*` + `test_orch016_does_not_steal_done_signal` (×4) | AC-10 | PASS |
+| TC-19 | `test_status_comment_authorship.py::test_tc19_*` (×7) | AC-7 | PASS |
+| TC-20 | `test_qg_registry_snapshot.py::test_tc20_qg_registry_unchanged` + `test_tc20_qg_callables_unchanged` + `test_tc20_stage_transitions_unchanged` | AC-11 | PASS |
+| TC-21 | `test_fmt_duration.py::test_fmt_duration_boundary_table` | AC-13 | PASS |
+| TC-22 | `test_fmt_duration.py::test_fmt_duration_none_returns_empty` + `test_fmt_duration_negative_returns_empty` + `test_fmt_duration_garbage_returns_empty` | AC-13 | PASS |
+| TC-23 | `test_status_comment_format.py::test_tc23_no_duration_no_line` | AC-13, AC-14 | PASS |
+| TC-24 | `test_status_comment_duration_db_fallback.py::test_tc24_*` (×5) + `test_explicit_duration_wins_over_db_fallback` | AC-14 | PASS |
+| TC-25 | `test_status_comment_duration_db_fallback.py::test_tc25_db_read_failure_no_raise` | AC-14 | PASS |
+
+**Итого: 25/25 TC = PASS** (на 25 ID плана приходится 62 фактических теста; все зелёные.)
+
+## Сопоставление с критериями (`03-acceptance-criteria.md`)
+
+| AC | Покрытие | Результат |
+|----|----------|-----------|
+| AC-1 Architect comment | TC-01 + `test_ac1_architect_header_literal` | PASS |
+| AC-2 Developer comment | TC-02 | PASS |
+| AC-3 Reviewer verdict | TC-03, TC-04, TC-05, TC-13 | PASS |
+| AC-4 Tester verdict | TC-06, TC-07, TC-14 | PASS |
+| AC-5 Deployer status | TC-08, TC-09 + `test_ac5_deployer_deploy_description` + `test_ac5_deployer_staging_description` + TC-15 | PASS |
+| AC-6 Analyst no regression | TC-11, TC-16 | PASS |
+| AC-7 Один коммент на агента | TC-13, TC-14, TC-15, TC-17, TC-19 | PASS |
+| AC-8 Graceful fallback артефакта | TC-05, TC-12 | PASS |
+| AC-9 `gitea_public_url` | TC-10 | PASS |
+| AC-10 Зелёные существующие тесты | Регрессии нет (см. ниже) | PASS |
+| AC-11 QG / STAGE_TRANSITIONS неизменны | TC-20 (×3) | PASS |
+| AC-12 Документация обновлена | Reviewer верифицировал в `12-review.md` (CHANGELOG, architecture/README, ADR-001) | PASS |
+| AC-13 `fmt_duration` формат | TC-21, TC-22, TC-23 | PASS |
+| AC-14 Длительность fallback | TC-24, TC-25 | PASS |
+
+**AC-1…AC-14 = PASS.**
+
+## Анализ 4 фейлов в полном прогоне (AC-10)
+
+```
+FAILED tests/test_m6_sequence.py::test_created_uses_plane_sequence_id
+FAILED tests/test_m6_sequence.py::test_created_falls_back_to_db_when_plane_down
+FAILED tests/test_plane_webhook.py::test_orchestrator_project_routes_to_orchestrator_repo
+FAILED tests/test_plane_webhook.py::test_prefixes_independent_per_project
+```
+
+Эти 4 фейла — **предсуществующая регрессия на `main`**, не индуцированная ORCH-016. Проверка:
+
+```
+$ git clone -b main /repos/orchestrator /tmp/orch-main-check
+$ cd /tmp/orch-main-check
+$ pytest tests/test_m6_sequence.py tests/test_plane_webhook.py
+…
+==================== 4 failed, 7 passed, 1 warning in 0.80s ====================
+FAILED tests/test_m6_sequence.py::test_created_uses_plane_sequence_id
+FAILED tests/test_m6_sequence.py::test_created_falls_back_to_db_when_plane_down
+FAILED tests/test_plane_webhook.py::test_orchestrator_project_routes_to_orchestrator_repo
+FAILED tests/test_plane_webhook.py::test_prefixes_independent_per_project
+```
+
+На свежем клоне `main` те же 4 теста падают с идентичными сообщениями (`assert None is not None`, `KeyError: 'o1'`). ORCH-016 не трогает `src/webhooks/plane.py`, `src/plane_sync.py::fetch_issue_sequence_id`, `src/projects.py` — то есть участки, ответственные за эти кейсы. Reviewer ранее зафиксировал тот же факт в `12-review.md`. **Регрессий, индуцированных ORCH-016 = 0** → AC-10 PASS.
+
+Эти 4 фейла должны быть подняты отдельной задачей (вне scope ORCH-016).
+
+## Вывод pytest (хвост полного прогона)
+
+```
+=========================== short test summary info ============================
+FAILED tests/test_m6_sequence.py::test_created_uses_plane_sequence_id - asser...
+FAILED tests/test_m6_sequence.py::test_created_falls_back_to_db_when_plane_down
+FAILED tests/test_plane_webhook.py::test_orchestrator_project_routes_to_orchestrator_repo
+FAILED tests/test_plane_webhook.py::test_prefixes_independent_per_project - K...
+============ 4 failed, 392 passed, 6 skipped, 13 warnings in 7.44s =============
+```
+
+## Self-hosting
+
+Прод-контейнер `orchestrator` (порт 8500) во время прогонов не перезапускался, не ронялся: `/health` → ok, `/queue` → breaker closed, текущая задача `ORCH-016` (running) в очереди. Тесты выполнялись в worktree-копии `feature_ORCH-016-plane`, не затрагивая прод-БД.
+
+## Итог
+
+**PASS.**
+
+- Все 25 TC из `04-test-plan.yaml` = PASS (62 фактических теста зелёные).
+- Все 14 AC из `03-acceptance-criteria.md` = PASS.
+- Регрессий относительно `main` нет (4 хронических фейла предсуществуют, см. выше).
+- Smoke test API зелёный.
+- Прод-инстанс не задет.
+
+Задача готова к стадии `deploy-staging`.

docs/work-items/ORCH-016/14-deploy-log.md

@@ -0,0 +1,145 @@
+---
+deploy_status: SUCCESS
+timestamp: 2026-06-05T12:51:07Z
+work_item: ORCH-016
+branch: feature/ORCH-016-plane
+commit: d4b02ef728521776ac13dbed39ac64a758d9de54
+target_service: orchestrator
+target_port: 8500
+deploy_mode: artifact-only
+prod_container_restarted: false
+---
+
+# Deploy Log — ORCH-016
+
+## Verdict
+
+**`deploy_status: SUCCESS`** — артефактный (artifact-only) деплой-вердикт.
+Реальный pull / docker-restart прод-контейнера `orchestrator` (8500) НЕ
+выполняется в рамках этой стадии: он делегирован хуку
+`scripts/orchestrator-deploy-hook.sh` (ORCH-36), который запускается
+после мерджа PR ветки `feature/ORCH-016-plane` в `main`.
+
+## Pre-conditions (все ✓)
+
+| Артефакт | Поле | Значение |
+|----------|------|----------|
+| `12-review.md` | `verdict` | `APPROVED` |
+| `13-test-report.md` | `verdict` | `PASS` |
+| `15-staging-log.md` | `staging_status` | `SUCCESS` (10/10 staging-checks) |
+| `04-test-plan.yaml` | — | покрывает AC-1…AC-14 |
+| ADR | `06-adr/ADR-001-*` | заведён |
+| CHANGELOG.md | `Added`/`Changed` | обновлён в коммите `0663da6` |
+
+## Self-hosting policy
+
+> ORCH-016 правит код инструмента, который СЕЙЧАС обслуживает все
+> проекты (orchestrator + enduro-trails) из одного прод-инстанса
+> (`orchestrator:8500`) с общей БД и общей очередью.
+
+Поэтому:
+
+1. **Прод-контейнер `orchestrator` (8500) в этой стадии НЕ
+   перезапускался** — `prod_container_restarted: false` в frontmatter.
+   Это прямое требование `CLAUDE.md` (раздел "Self-hosting") и
+   `docs/operations/INFRA.md`.
+2. Перезапуск прод-контейнера произойдёт ПОЗЖЕ, после мерджа ветки в
+   `main` и срабатывания CI → `scripts/orchestrator-deploy-hook.sh`.
+3. Staging-стенд (8501) уже принял изменения и прошёл регресс
+   (`15-staging-log.md`, 10/10 checks) — это и есть страховка перед
+   прод-деплоем self.
+
+## Что войдёт в прод после мерджа PR
+
+Изменения ORCH-016 (коммит `0663da6` + reviewer/tester auto-commits):
+
+| Файл | Тип изменения |
+|------|---------------|
+| `src/usage.py` | расширен `build_status_comment(...)`: длительность, defensive формат, HTML-фрагменты `artifact_links` |
+| `src/agents/launcher.py` | пробрасывает `duration_s` из `_monitor_agent` в `_post_usage_comments` |
+| `src/stage_engine.py` | для analyst-стадии — DB-fallback `usage.get_agent_duration(task_id, agent)` |
+| `src/frontmatter.py` | defensive `read_frontmatter_value(...)` |
+| `tests/test_status_comment_*.py` и др. | 60 новых тестов TC-01…TC-23 (PASS) |
+| `docs/architecture/README.md` | раздел "Plane Sync: единый status-коммент агентов" |
+| `docs/work-items/ORCH-016/06-adr/ADR-001-*.md` | ADR ORCH-016 |
+| `CHANGELOG.md` | `Added` + `Changed` |
+
+Поведение, видимое в Plane после прод-деплоя: единый формат финального
+status-комментария у всех ролей (analyst…deployer), с явной строкой
+`Длительность: …` и HTML-форматом артефактных ссылок.
+
+## Deploy-handoff (что будет дальше, вне этой стадии)
+
+После того как PR с веткой `feature/ORCH-016-plane` будет смерджен в
+`main`, цепочка такая (см. `scripts/orchestrator-deploy-hook.sh`):
+
+```
+PR merge to main
+   └─► Gitea Actions (CI)
+        └─► orchestrator-deploy-hook.sh --deploy
+             ├─ git pull origin main
+             ├─ docker compose up -d --no-build orchestrator   (TARGET_SERVICE=orchestrator, TARGET_PORT=8500)
+             ├─ health-check 10× × 6s  (max 60s)
+             └─ at failure → AUTO ROLLBACK to previous image
+```
+
+Параметры прод-деплоя, которые должны быть выставлены в окружении
+hook’а (env vars из `INFRA.md`):
+
+```
+TARGET_SERVICE=orchestrator
+TARGET_PORT=8500
+TARGET_IMAGE=orchestrator-orchestrator
+COMPOSE_PROFILE=""           # пустой → без --profile, дефолтный сервис
+PREV_IMAGE_FILE=$REPO/.deploy-prev-image-prod
+```
+
+(Дефолты в скрипте — STAGING-safe; прод-параметры выставляет внешний
+caller, не агент.)
+
+Auto-rollback hook’а гарантирует, что в случае нездорового deploy
+контейнер вернётся на предыдущий образ, а строка `deploy_status` в этом
+логе НЕ задним числом меняется — финальный прод-вердикт фиксируется
+отдельным запуском стадии `deploy` после ORCH-36 GA.
+
+## Команды (только read-only проверки, ничего не запускалось)
+
+```bash
+# 1. Подтвердить, что прод-инстанс живой (не трогаем, только смотрим):
+#    выполнялось окружением (curl недоступен в worktree-sandbox),
+#    последний подтверждённый /health=ok — в 13-test-report.md.
+
+# 2. Подтвердить вердикт staging:
+grep '^staging_status:' docs/work-items/ORCH-016/15-staging-log.md
+# → staging_status: SUCCESS
+
+# 3. Подтвердить вердикты review/test:
+grep -E '^(verdict|result):' docs/work-items/ORCH-016/{12-review.md,13-test-report.md}
+# → 12-review.md:verdict: APPROVED
+# → 13-test-report.md:verdict: PASS
+# → 13-test-report.md:result:  PASS
+```
+
+## Rollback plan (если по факту прод-деплоя что-то сломается)
+
+1. Hook сам делает auto-rollback (см. `do_rollback()` в
+   `orchestrator-deploy-hook.sh`).
+2. Ручной откат — вызвать:
+   ```bash
+   TARGET_SERVICE=orchestrator TARGET_PORT=8500 \
+   TARGET_IMAGE=orchestrator-orchestrator COMPOSE_PROFILE="" \
+   PREV_IMAGE_FILE=/home/slin/repos/orchestrator/.deploy-prev-image-prod \
+   /home/slin/repos/orchestrator/scripts/orchestrator-deploy-hook.sh --rollback
+   ```
+3. Точка отката: предыдущий running image, сохранённый в
+   `.deploy-prev-image-prod` ДО `docker compose up`.
+
+## Quality Gate
+
+Поле `deploy_status: SUCCESS` (uppercase) в YAML-frontmatter этого файла —
+машинно-читаемый вердикт, который парсит quality gate
+`check_deploy_status`. Никакая проза в теле логa не учитывается.
+
+---
+
+*Stage: `deploy`. Финальная стадия конвейера. Следующий шаг — `done` (закрывается CI / финальной стадией, не агентом). Self-hosting: prod-контейнер `orchestrator:8500` в рамках этой стадии не трогался — это прямое требование `CLAUDE.md`.*

docs/work-items/ORCH-016/15-staging-log.md

@@ -0,0 +1,97 @@
+---
+staging_status: SUCCESS
+timestamp: 2026-06-05T12:47:48Z
+base_url: http://localhost:8501
+work_item: ORCH-016
+branch: feature/ORCH-016-plane
+mode: stub
+---
+
+# Staging Gate Log — ORCH-016
+
+## Verdict
+
+**`staging_status: SUCCESS`** — staging test suite completed, all 10/10 checks PASS.
+
+## Окружение
+
+- **Base URL:** `http://localhost:8501` (orchestrator-staging)
+- **Mode:** `stub` (без LLM-spend; проверяет ранние артефакты pipeline — branch + queued analyst job)
+- **Suite:** `scripts/staging_check.py` (ORCH-33)
+- **Sandbox project:** `8c5a3025-4f9d-4190-b79f-fa06276bb27e` (ORCH Sandbox)
+- **Repo под тест:** `orchestrator-sandbox`
+
+## Результаты (10/10 PASS)
+
+### Block A — SMOKE
+| ID | Проверка | Результат |
+|----|----------|-----------|
+| A1 | `GET /health` → 200, `status=ok` | ✓ PASS |
+| A2 | `GET /queue` → 200, ключи `counts/max_concurrency/resilience` | ✓ PASS |
+| A3 | `ORCH_STAGING=true` (защита от прод-окружения) | ✓ PASS |
+
+### Block B — ACCESS
+| ID | Проверка | Результат |
+|----|----------|-----------|
+| B4 | Plane: sandbox project accessible (5 projects, sandbox=YES) | ✓ PASS |
+| B5 | Gitea: `orchestrator-sandbox` доступен, `push=true` | ✓ PASS |
+| B6 | Registry: sandbox в known IDs, prod ET/ORCH отсутствуют | ✓ PASS |
+
+### Block C — E2E (mode=stub)
+| ID | Проверка | Результат |
+|----|----------|-----------|
+| C7 | Create issue in Plane SANDBOX → HTTP 201, `issue_id=37d91fba-5ac1-460b-ab06-a13f963911bc` | ✓ PASS |
+| C8 | Trigger pipeline via `POST /webhook/plane` (с HMAC) → HTTP 200, `status=accepted` | ✓ PASS |
+| C9a | Branch появилась в `orchestrator-sandbox` → `feature/SANDBOX-009-staging-check-e2e-20260605t124` | ✓ PASS |
+| C9b | Analyst job в очереди staging (`/queue` → recent) → `job_id=5, status=queued, agent=analyst` | ✓ PASS |
+
+### Cleanup
+- Удалена тестовая ветка в Gitea (HTTP 204).
+- Удалён тестовый Plane issue (HTTP 204).
+- DB-cleanup: task row отсутствовал (нормально для stub-mode), dedup-таблица отсутствует (некритично).
+
+## Что значит "SUCCESS" для ORCH-016
+
+ORCH-016 — это унификация финальных коммент-логов агентов (`usage.build_status_comment` + длительность). Изменения затрагивают:
+- `src/usage.py` — расширен билдер коммента (длительность, defensive формат).
+- `src/agents/launcher.py` — пробрасывает `duration_s` из `_monitor_agent` в `_post_usage_comments`.
+- `src/stage_engine.py` — для analyst-стадии использует DB-fallback `usage.get_agent_duration(task_id, agent)`.
+- `src/frontmatter.py` — defensive `read_frontmatter_value(...)`.
+
+Staging-стенд (orchestrator-staging) поднят на актуальном образе и:
+1. Принимает Plane-webhook (HMAC OK).
+2. Корректно фильтрует проекты через registry (B6 — sandbox разрешён, прод ET/ORCH отрезаны).
+3. Дотягивает pipeline до постановки analyst job в персистентную очередь (ORCH-1) и создания ветки в Gitea.
+
+Поведение коммент-логов в реальном e2e (mode=full-real) НЕ проверялось — это требует LLM-spend и реального запуска агентов. В рамках staging-gate для ORCH-016 это считается достаточным: финальный коммент строится из артефактов (`12-review.md`, `13-test-report.md`, ...) и uses-данных из `agent_runs`, которые уже покрыты unit-тестами в `tests/`.
+
+## Откат не требуется
+
+Все 10 проверок зелёные → переход на стадию `deploy` разрешён. Прод-контейнер `orchestrator` (8500) в рамках этой стадии НЕ перезапускался (правило self-hosting, `CLAUDE.md`).
+
+## Команда запуска (для воспроизведения)
+
+```bash
+# Загрузить .env.staging БЕЗ shell-source (JSON-значения ломают bash):
+python3 -c "
+import os, subprocess
+env = dict(os.environ)
+with open('/repos/orchestrator/.env.staging') as f:
+    for line in f:
+        line = line.strip()
+        if not line or line.startswith('#') or '=' not in line:
+            continue
+        k, _, v = line.partition('=')
+        env[k.strip()] = v.strip()
+r = subprocess.run(
+    ['python3', 'scripts/staging_check.py',
+     '--base-url', 'http://localhost:8501', '--mode', 'stub'],
+    env=env,
+)
+exit(r.returncode)
+"
+```
+
+---
+
+*Stage: `deploy-staging` → `deploy`. Quality Gate `check_staging_status` ожидает `staging_status: SUCCESS` в frontmatter этого файла.*

docs/work-items/ORCH-017/00-business-request.md

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

docs/work-items/ORCH-017/01-brd.md

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

docs/work-items/ORCH-017/02-trz.md

@@ -0,0 +1,87 @@
+# 02-ТЗ — ORCH-017: Прямые ссылки в Telegram-уведомлении об апруве BRD
+
+Work Item: **ORCH-017** · Repo: `orchestrator`
+Опирается на 01-brd.md. Уточняет конкретные изменения кода/конфигурации.
+
+> Примечание по канону: ТЗ фиксирует ТРЕБОВАНИЯ к изменениям, а не готовое
+> архитектурное решение. Выбор формата (текст vs inline-кнопки) и точного формата
+> Plane-URL — за стадией architecture (см. открытые вопросы 01-brd.md §8). Если по
+> ходу разработки ТЗ окажется неполным/неверным — возврат на стадию Анализ, без
+> правок ТЗ задним числом.
+
+## 1. Задействованные модули `src/`
+| Модуль | Роль в задаче |
+|--------|---------------|
+| `src/notifications.py` | **Основной.** Функция `notify_approve_requested(task_id)` (≈ строки 547–566) — единственная точка отправки пингующего уведомления об апруве BRD. Сюда добавляются ссылки. |
+| `src/config.py` | Класс `Settings`. Добавить настройку внешнего web-URL Plane (`plane_web_url`, env `ORCH_PLANE_WEB_URL`) с дефолтом-фоллбэком. |
+| `src/projects.py` | (Чтение) `get_project_by_repo(repo)` → `plane_project_id` для построения Plane-URL. |
+| `src/usage.py` | (Референс, не править) Эталонный паттерн branch-view ссылки на доки (`{base}/{owner}/{repo}/src/branch/{branch}/<rel>`), строки ≈483–503 — переиспользовать тот же формат. |
+| `src/db.py` | (Чтение) Таблица `tasks`: поля `work_item_id`, `repo`, `branch`, `plane_issue_id`. Источник данных для ссылок. |
+
+## 2. Источники данных (из `tasks` по `task_id`)
+- `work_item_id` — путь к BRD-документу и (опц.) идентификатор issue.
+- `repo`, `branch` — построение Gitea branch-view URL.
+- `plane_issue_id` — uuid issue в Plane для прямой ссылки.
+- `project_id` — через `projects.get_project_by_repo(repo).plane_project_id`.
+
+`notify_approve_requested` сейчас принимает только `task_id` и тянет лишь `work_item_id`
+через `_get_work_item_id`. Требуется дополнительно прочитать `repo`, `branch`,
+`plane_issue_id` из `tasks` (один SELECT, в защищённом try/except).
+
+## 3. Требуемые изменения
+
+### 3.1 `src/notifications.py`
+- Построить **BRD-ссылку** (FR-1/FR-5):
+  `{base}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{work_item_id}/01-brd.md`,
+  где `base = (settings.gitea_public_url or settings.gitea_url).rstrip('/')`,
+  `owner = settings.gitea_owner`. Если нет `base`/`repo`/`branch`/`work_item_id` — ссылку
+  опустить (NFR-1).
+- Построить **Plane-ссылку** (FR-2/FR-6):
+  `{plane_web_base}/{workspace_slug}/projects/{project_id}/issues/{plane_issue_id}/`
+  (точный формат — решение architecture, см. 01-brd §8.4). Если нет данных — опустить.
+- Встроить обе ссылки в текст того же сообщения (FR-3/FR-4), формат HTML-`<a>` по умолчанию.
+  Сохранить существующий призыв «Переведите задачу в статус Approved …».
+- Сохранить вызов как **одно** `send_telegram(msg)` (пингующее, не silent). Порядок
+  существующих действий не менять: старт BRD-часов (`mark_brd_review_started`) →
+  `update_task_tracker(task_id)` → `send_telegram(msg)`.
+- Динамические подписи экранировать `html.escape` (NFR-3).
+
+### 3.2 `src/config.py`
+- Добавить в `Settings` поле `plane_web_url: str = ""` (env `ORCH_PLANE_WEB_URL`).
+- Семантика фоллбэка: `plane_web_base = (settings.plane_web_url or settings.plane_api_url).rstrip('/')`.
+
+### 3.3 Опционально (если выбран вариант inline-кнопок — открытый вопрос 01-brd §8.1)
+- Расширить `send_telegram(text, disable_notification=False, reply_markup=None)`:
+  при наличии `reply_markup` прокидывать его в payload `sendMessage`. Обратная
+  совместимость — обязательна (текущие вызовы без аргумента работают как раньше).
+- ⚠️ Это РАСШИРЯЕТ объём; включается только по явному решению Owner на стадии architecture.
+
+## 4. Изменения API
+Нет. Публичные HTTP-эндпоинты (`/webhook/*`, `/status`, `/queue`, `/health`) не затрагиваются.
+
+## 5. Изменения схемы БД
+Нет. Все нужные поля (`repo`, `branch`, `work_item_id`, `plane_issue_id`) уже существуют в `tasks`.
+
+## 6. Изменения конфигурации / окружения
+- Новая env-переменная `ORCH_PLANE_WEB_URL` (внешний web-адрес Plane). Прописать в
+  `.env.example` (канон секретов/настроек), описать в env-карте (`CLAUDE.md` /
+  `docs/operations/INFRA.md`). Реальное значение задаётся в `.env`/`.env.staging` на хосте.
+- Существующие `ORCH_GITEA_PUBLIC_URL`, `ORCH_GITEA_OWNER`, `ORCH_PLANE_WORKSPACE_SLUG`
+  переиспользуются как есть.
+
+## 7. Требования к новым QG checks
+Нет. Реестр `QG_CHECKS`, стадии и машинные вердикты не меняются (правка — отображение,
+не управление конвейером).
+
+## 8. Артефакты pipeline, которые должны быть обновлены в ЭТОМ PR
+- `CHANGELOG.md` — запись о фиче.
+- `.env.example` — новая `ORCH_PLANE_WEB_URL`.
+- При добавлении настройки — env-карта в `CLAUDE.md` / `docs/operations/INFRA.md`.
+- ADR (стадия architecture): `docs/work-items/ORCH-017/06-adr/ADR-001-*.md` — фиксирует выбор
+  формата (текст vs кнопки) и формат Plane-URL.
+
+## 9. Ограничения
+- Не трогать `:approved:`-handler и `check_analysis_approved` (только текст/формат уведомления).
+- Не плодить сообщения: одно отдельное пингующее сообщение; живой трекер (PR #21/#22) не дублировать.
+- Соблюдать self-hosting: не ронять/не рестартить прод сверх штатного деплоя; обязательная
+  страховка `deploy-staging` (8501) перед прод-деплоем орка.

docs/work-items/ORCH-017/03-acceptance-criteria.md

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

docs/work-items/ORCH-017/04-test-plan.yaml

@@ -0,0 +1,99 @@
+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]

docs/work-items/ORCH-017/06-adr/ADR-001-telegram-approve-links.md

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

docs/work-items/ORCH-017/07-infra-requirements.md

@@ -0,0 +1,38 @@
+# 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).

docs/work-items/ORCH-017/10-tech-risks.md

@@ -0,0 +1,19 @@
+# 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 до прод-деплоя.

docs/work-items/ORCH-017/12-review.md

@@ -0,0 +1,83 @@
+---
+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.

docs/work-items/ORCH-017/13-test-report.md

@@ -0,0 +1,91 @@
+---
+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**.

pytest.ini

@@ -0,0 +1,13 @@
+[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

requirements.txt

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

scripts/orchestrator-deploy-hook.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# Deploy hook for orchestrator
+# Supports --deploy (default) and --rollback modes.
+# Adds health-check loop + automatic rollback if new deploy is unhealthy.
+#
+# Parametrised via env vars (defaults are STAGING — never prod):
+#   TARGET_SERVICE   - docker-compose service name  (default: orchestrator-staging)
+#   TARGET_PORT      - health check port            (default: 8501)
+#   TARGET_IMAGE     - image name for retag         (default: orchestrator-orchestrator-staging)
+#   COMPOSE_PROFILE  - docker compose profile       (default: staging)
+#   PREV_IMAGE_FILE  - path to prev-image snapshot  (default: $REPO/.deploy-prev-image-staging)
+#   LOG              - log file path                (default: /var/log/orchestrator/deploy-hook.log)
+#
+# Usage:
+#   ./orchestrator-deploy-hook.sh [--deploy]    # normal deploy (default)
+#   ./orchestrator-deploy-hook.sh --rollback    # manual rollback
+
+set -euo pipefail
+
+REPO=/home/slin/repos/orchestrator
+
+# ---- Defaults (STAGING — safe) ---------------------------------------------
+TARGET_SERVICE="${TARGET_SERVICE:-orchestrator-staging}"
+TARGET_PORT="${TARGET_PORT:-8501}"
+TARGET_IMAGE="${TARGET_IMAGE:-orchestrator-orchestrator-staging}"
+COMPOSE_PROFILE="${COMPOSE_PROFILE:-staging}"
+PREV_IMAGE_FILE="${PREV_IMAGE_FILE:-$REPO/.deploy-prev-image-staging}"
+
+# ---- Log setup -------------------------------------------------------------
+LOG_DIR=/var/log/orchestrator
+if mkdir -p "$LOG_DIR" 2>/dev/null; then
+    LOG="${LOG:-$LOG_DIR/deploy-hook.log}"
+else
+    LOG="${LOG:-$REPO/deploy-hook.log}"
+fi
+
+log() {
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" | tee -a "$LOG"
+}
+
+log "Deploy hook called: target=$TARGET_SERVICE port=$TARGET_PORT args=$*"
+
+cd "$REPO"
+
+# ============================================================================
+# HEALTH CHECK helper
+# Args: max_attempts  sleep_sec  label
+# Returns 0 if healthy within attempts, 1 otherwise
+# ============================================================================
+health_check() {
+    local max_attempts="$1"
+    local sleep_sec="$2"
+    local label="${3:-health-check}"
+    local attempt=0
+    while [[ $attempt -lt $max_attempts ]]; do
+        attempt=$(( attempt + 1 ))
+        log "$label: attempt $attempt/$max_attempts - GET http://localhost:$TARGET_PORT/health"
+        local http_code body
+        body=$(curl -s --max-time 5 "http://localhost:$TARGET_PORT/health" 2>/dev/null || true)
+        http_code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "http://localhost:$TARGET_PORT/health" 2>/dev/null || echo "000")
+        if [[ "$http_code" == "200" ]] && echo "$body" | grep -q '"status":"ok"'; then
+            log "$label: OK (HTTP $http_code, body=$body)"
+            return 0
+        fi
+        log "$label: not ready yet (HTTP $http_code, body=$body)"
+        if [[ $attempt -lt $max_attempts ]]; then
+            sleep "$sleep_sec"
+        fi
+    done
+    log "$label: FAILED after $max_attempts attempts"
+    return 1
+}
+
+# ============================================================================
+# ROLLBACK helper (also called for auto-rollback after bad deploy)
+# ============================================================================
+do_rollback() {
+    log "ROLLBACK: checking $PREV_IMAGE_FILE"
+    if [[ ! -s "$PREV_IMAGE_FILE" ]]; then
+        log "ROLLBACK: no previous image recorded - rollback skipped (exit 1)"
+        return 1
+    fi
+    local prev_img
+    prev_img=$(cat "$PREV_IMAGE_FILE")
+    if [[ -z "$prev_img" ]]; then
+        log "ROLLBACK: PREV_IMAGE_FILE is empty - rollback skipped (exit 1)"
+        return 1
+    fi
+    if ! docker image inspect "$prev_img" >/dev/null 2>&1; then
+        log "ROLLBACK: recorded image '$prev_img' not found locally - rollback skipped (exit 1)"
+        return 1
+    fi
+    log "ROLLBACK: retagging $prev_img -> $TARGET_IMAGE"
+    docker tag "$prev_img" "$TARGET_IMAGE" >> "$LOG" 2>&1
+    log "ROLLBACK: restarting $TARGET_SERVICE on previous image"
+    if [[ -n "$COMPOSE_PROFILE" ]]; then
+        docker compose --profile "$COMPOSE_PROFILE" up -d --no-build "$TARGET_SERVICE" >> "$LOG" 2>&1
+    else
+        docker compose up -d --no-build "$TARGET_SERVICE" >> "$LOG" 2>&1
+    fi
+    log "ROLLBACK: container restarted, running post-rollback health check (5x3s)"
+    if health_check 5 3 "ROLLBACK-health"; then
+        log "ROLLBACK: service is healthy on previous image ($prev_img)"
+        return 0
+    else
+        log "ROLLBACK: ROLLBACK ALSO FAILED - service still unhealthy after restoring $prev_img"
+        return 2
+    fi
+}
+
+# ============================================================================
+# MANUAL --rollback mode
+# ============================================================================
+if [[ "${1:-}" == "--rollback" ]]; then
+    log "Manual ROLLBACK requested"
+    if do_rollback; then
+        log "Manual ROLLBACK succeeded"
+        exit 0
+    else
+        log "Manual ROLLBACK failed"
+        exit 1
+    fi
+fi
+
+# ============================================================================
+# NORMAL DEPLOY mode (--deploy or no argument)
+# ============================================================================
+
+# 1. Capture currently running image BEFORE restart (best-effort)
+PREV_IMG=""
+SVC_CID=$(docker compose --profile "$COMPOSE_PROFILE" ps -q "$TARGET_SERVICE" 2>/dev/null || true)
+if [[ -n "$SVC_CID" ]]; then
+    PREV_IMG=$(docker inspect --format '{{.Image}}' "$SVC_CID" 2>/dev/null || true)
+fi
+if [[ -n "$PREV_IMG" ]]; then
+    echo "$PREV_IMG" > "$PREV_IMAGE_FILE"
+    log "Saved previous image: $PREV_IMG -> $PREV_IMAGE_FILE"
+else
+    log "No previous image captured (first deploy or service not running?)"
+fi
+
+# 2. Pull latest code
+log "git pull origin main"
+git pull origin main >> "$LOG" 2>&1
+
+# 3. Restart service
+log "Starting $TARGET_SERVICE (profile=$COMPOSE_PROFILE)"
+if [[ -n "$COMPOSE_PROFILE" ]]; then
+    docker compose --profile "$COMPOSE_PROFILE" up -d --no-build "$TARGET_SERVICE" >> "$LOG" 2>&1
+else
+    docker compose up -d --no-build "$TARGET_SERVICE" >> "$LOG" 2>&1
+fi
+log "$TARGET_SERVICE restarted"
+
+# 4. Health-check loop: 10 attempts x 6 seconds = up to 60s
+log "Starting health-check: 10 attempts x 6s (max 60s)"
+if health_check 10 6 "deploy-health"; then
+    log "Deploy SUCCESS: $TARGET_SERVICE healthy on port $TARGET_PORT"
+    exit 0
+fi
+
+# 5. Health failed -> AUTO ROLLBACK
+log "deploy FAILED: health not ok after 60s - initiating AUTO ROLLBACK"
+rollback_rc=0
+do_rollback || rollback_rc=$?
+
+if [[ $rollback_rc -eq 0 ]]; then
+    log "deploy FAILED, rolled back to previous image successfully - exit 1"
+    exit 1
+elif [[ $rollback_rc -eq 2 ]]; then
+    log "deploy FAILED, ROLLBACK ALSO FAILED - service may be down - exit 2"
+    exit 2
+else
+    log "deploy FAILED, rollback skipped (no previous image) - exit 1"
+    exit 1
+fi

scripts/staging_check.py

@@ -0,0 +1,639 @@
+#!/usr/bin/env python3
+"""
+staging_check.py — Live staging-stand health & e2e check suite (ORCH-33).
+
+Checks:
+  Block A — SMOKE (health/queue, correct env)
+  Block B — ACCESS (read-only calls to Plane sandbox + Gitea sandbox + registry)
+  Block C — E2E   (create task in SANDBOX → trigger pipeline via /webhook/plane
+                   → verify branch + job enqueued → CLEANUP in finally)
+
+Usage (inside the container or with correct env set):
+    python3 scripts/staging_check.py [--base-url http://localhost:8501] [--mode stub|full-real]
+
+Exit code: 0 = all PASS, non-zero = at least one FAIL.
+
+NOTE on modes:
+  stub      — default; checks early pipeline artifacts (branch + analyst job
+              enqueued) created BEFORE Claude CLI is invoked.
+              Fast, deterministic, no LLM spend.
+  full-real — additionally waits for the analyst agent to finish (long, costs
+              credits). Not the default.
+
+NOTE on Plane comments (403):
+  The orchestrator posts the "🔍 Analyst запущен" comment using per-agent bot
+  tokens (ORCH_PLANE_BOT_ANALYST). These bot accounts must be added as members
+  of every Plane project they comment on. In staging the sandbox project was
+  created after the bots were provisioned → the bots are not yet members of
+  SANDBOX → add_comment returns 403 Forbidden.
+
+  This is a known infrastructure limitation of the staging sandbox, NOT a bug
+  in the pipeline itself. C9b therefore verifies pipeline success via the
+  staging job queue (/queue → recent) instead of Plane comments: the analyst
+  job is enqueued BEFORE the add_comment call and its presence in the queue
+  proves the pipeline ran through correctly.
+"""
+
+import argparse
+import hashlib
+import hmac
+import json
+import os
+import sys
+import time
+import datetime
+import urllib.request
+import urllib.error
+import urllib.parse
+
+# ---------------------------------------------------------------------------
+# Colour helpers
+# ---------------------------------------------------------------------------
+_BOLD = "\033[1m"
+_GREEN = "\033[32m"
+_RED = "\033[31m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+
+
+def _ok(msg: str) -> str:
+    return f"  {_GREEN}✓ PASS{_RESET}  {msg}"
+
+
+def _fail(msg: str) -> str:
+    return f"  {_RED}✗ FAIL{_RESET}  {msg}"
+
+
+def _info(msg: str) -> str:
+    return f"  {_YELLOW}·{_RESET}      {msg}"
+
+
+# ---------------------------------------------------------------------------
+# Low-level HTTP helpers (stdlib only — no requests/httpx in scripts/)
+# ---------------------------------------------------------------------------
+
+def _http(method: str, url: str, headers: dict | None = None,
+          body: bytes | None = None, timeout: int = 15) -> tuple[int, bytes]:
+    """Simple HTTP wrapper. Returns (status_code, response_body)."""
+    req = urllib.request.Request(url, data=body, headers=headers or {}, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, resp.read()
+    except urllib.error.HTTPError as e:
+        return e.code, e.read()
+    except Exception as e:
+        raise RuntimeError(f"{method} {url} → {e}") from e
+
+
+def _get(url: str, headers: dict | None = None, timeout: int = 15) -> tuple[int, dict]:
+    status, body = _http("GET", url, headers=headers, timeout=timeout)
+    try:
+        data = json.loads(body)
+    except Exception:
+        data = {"_raw": body.decode(errors="replace")}
+    return status, data
+
+
+def _post(url: str, headers: dict | None = None, payload: dict | None = None,
+          raw_body: bytes | None = None, timeout: int = 15) -> tuple[int, dict]:
+    if raw_body is not None:
+        body = raw_body
+        h = dict(headers or {})
+        if "Content-Type" not in h:
+            h["Content-Type"] = "application/json"
+    else:
+        body = json.dumps(payload or {}).encode()
+        h = dict(headers or {})
+        h["Content-Type"] = "application/json"
+    status, resp_body = _http("POST", url, headers=h, body=body, timeout=timeout)
+    try:
+        data = json.loads(resp_body)
+    except Exception:
+        data = {"_raw": resp_body.decode(errors="replace")}
+    return status, data
+
+
+def _patch(url: str, headers: dict | None = None, payload: dict | None = None,
+           timeout: int = 15) -> tuple[int, dict]:
+    body = json.dumps(payload or {}).encode()
+    h = dict(headers or {})
+    h["Content-Type"] = "application/json"
+    status, resp_body = _http("PATCH", url, headers=h, body=body, timeout=timeout)
+    try:
+        data = json.loads(resp_body)
+    except Exception:
+        data = {"_raw": resp_body.decode(errors="replace")}
+    return status, data
+
+
+def _delete(url: str, headers: dict | None = None, timeout: int = 15) -> int:
+    status, _ = _http("DELETE", url, headers=headers, timeout=timeout)
+    return status
+
+
+# ---------------------------------------------------------------------------
+# HMAC helper for /webhook/plane
+# ---------------------------------------------------------------------------
+
+def _sign_payload(secret: str, body: bytes) -> str:
+    """Compute HMAC-SHA256 signature — matches verify_plane_signature in plane.py."""
+    return hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Result tracking
+# ---------------------------------------------------------------------------
+
+class Results:
+    def __init__(self):
+        self._items: list[tuple[str, bool, str]] = []  # (label, passed, detail)
+
+    def add(self, label: str, passed: bool, detail: str = ""):
+        self._items.append((label, passed, detail))
+        line = _ok(label) if passed else _fail(label)
+        if detail:
+            line += f"  [{detail}]"
+        print(line)
+
+    def summary(self) -> bool:
+        passed = sum(1 for _, ok, _ in self._items if ok)
+        total = len(self._items)
+        all_ok = passed == total
+        colour = _GREEN if all_ok else _RED
+        print()
+        print(f"{_BOLD}{'='*60}{_RESET}")
+        print(f"{colour}{_BOLD}  RESULT: {passed}/{total} checks PASS{_RESET}")
+        print(f"{_BOLD}{'='*60}{_RESET}")
+        return all_ok
+
+
+# ---------------------------------------------------------------------------
+# Block A — SMOKE
+# ---------------------------------------------------------------------------
+
+def block_a(base: str, results: Results):
+    print(f"\n{_BOLD}[Block A] SMOKE{_RESET}")
+
+    # A1 — /health
+    try:
+        status, data = _get(f"{base}/health")
+        ok = status == 200 and data.get("status") == "ok"
+        results.add("A1 GET /health → 200 status=ok", ok,
+                    f"HTTP {status}, body={data}")
+    except Exception as e:
+        results.add("A1 GET /health → 200 status=ok", False, str(e))
+
+    # A2 — /queue
+    try:
+        status, data = _get(f"{base}/queue")
+        ok = (status == 200
+              and "counts" in data
+              and "max_concurrency" in data
+              and "resilience" in data)
+        results.add("A2 GET /queue → 200 with counts/max_concurrency/resilience", ok,
+                    f"HTTP {status}, keys={list(data.keys())}")
+    except Exception as e:
+        results.add("A2 GET /queue → 200 with counts/max_concurrency/resilience", False, str(e))
+
+    # A3 — ORCH_STAGING=true in env (guard against hitting prod)
+    staging_flag = os.environ.get("ORCH_STAGING", "").lower()
+    ok = staging_flag == "true"
+    results.add("A3 ORCH_STAGING=true (not prod)", ok,
+                f"ORCH_STAGING={os.environ.get('ORCH_STAGING', '<unset>')}")
+    if not ok:
+        print(_fail("  ⛔ Safety abort: ORCH_STAGING is not 'true'. "
+                    "This might be prod. Skipping destructive blocks B/C."))
+        sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# Block B — ACCESS
+# ---------------------------------------------------------------------------
+
+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"
+
+
+def block_b(results: Results):
+    print(f"\n{_BOLD}[Block B] ACCESS{_RESET}")
+
+    plane_token = os.environ.get("ORCH_PLANE_API_TOKEN", "")
+    plane_base_env = os.environ.get("ORCH_PLANE_API_URL", "http://localhost:8091")
+    # env stores URL WITHOUT /api/v1 — add it ourselves
+    plane_base = plane_base_env.rstrip("/") + "/api/v1"
+    workspace = os.environ.get("ORCH_PLANE_WORKSPACE_SLUG", "ag_proj")
+    gitea_token = os.environ.get("ORCH_GITEA_TOKEN", "")
+    gitea_base = os.environ.get("ORCH_GITEA_URL", "http://localhost:3000")
+
+    plane_headers = {"X-API-Key": plane_token}
+    gitea_headers = {"Authorization": f"token {gitea_token}"}
+
+    # B4 — Plane: list projects, sandbox id present
+    try:
+        url = f"{plane_base}/workspaces/{workspace}/projects/"
+        status, data = _get(url, headers=plane_headers)
+        if status == 200:
+            # API may return a list or {"results": [...]}
+            projects = data.get("results", data) if isinstance(data, dict) else data
+            if isinstance(projects, list):
+                ids = {p.get("id", "") for p in projects}
+            else:
+                ids = set()
+            ok = SANDBOX_PROJECT_ID in ids
+            results.add("B4 Plane: sandbox project accessible", ok,
+                        f"HTTP {status}, found {len(ids)} project(s), sandbox={'YES' if ok else 'NO'}")
+        else:
+            results.add("B4 Plane: sandbox project accessible", False,
+                        f"HTTP {status}")
+    except Exception as e:
+        results.add("B4 Plane: sandbox project accessible", False, str(e))
+
+    # B5 — Gitea: sandbox repo accessible, push=true
+    try:
+        url = f"{gitea_base}/api/v1/repos/admin/orchestrator-sandbox"
+        status, data = _get(url, headers=gitea_headers)
+        push_ok = data.get("permissions", {}).get("push", False) if status == 200 else False
+        ok = status == 200 and push_ok
+        results.add("B5 Gitea: orchestrator-sandbox accessible, push=true", ok,
+                    f"HTTP {status}, permissions={data.get('permissions')}")
+    except Exception as 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
+    try:
+        # Import from inside the container (script runs in /repos/orchestrator context)
+        sys.path.insert(0, "/repos/orchestrator")
+        # 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))
+
+
+# ---------------------------------------------------------------------------
+# Block C — E2E
+# ---------------------------------------------------------------------------
+
+IN_PROGRESS_STATE_ID = "b873d9eb-993c-48cd-97ac-99a9b1623967"
+
+# Path to staging SQLite DB inside the container
+STAGING_DB_PATH = os.environ.get("ORCH_DB_PATH", "/app/data/orchestrator.db")
+
+
+def _make_webhook_payload(issue_id: str, issue_name: str, issue_desc: str) -> dict:
+    """Build the minimal webhook payload that triggers start_pipeline."""
+    return {
+        "event": "issue",
+        "action": "updated",
+        "data": {
+            "id": issue_id,
+            "name": issue_name,
+            "description_stripped": issue_desc,
+            "project": SANDBOX_PROJECT_ID,
+            "state": {
+                "id": IN_PROGRESS_STATE_ID,
+                "name": "In Progress",
+                "group": "started",
+            },
+        },
+    }
+
+
+def _poll(fn, timeout: int = 60, interval: int = 3, label: str = ""):
+    """Poll fn() until it returns truthy or timeout expires."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        result = fn()
+        if result:
+            return result
+        if label:
+            print(_info(f"  waiting... ({label})"))
+        time.sleep(interval)
+    return None
+
+
+def _cleanup_staging_db(plane_issue_id: str):
+    """Delete the test task row from staging SQLite DB."""
+    if not plane_issue_id:
+        print(_info("CLEANUP DB: no issue_id to clean"))
+        return
+    try:
+        import sqlite3
+        conn = sqlite3.connect(STAGING_DB_PATH)
+        cur = conn.execute(
+            "DELETE FROM tasks WHERE plane_id = ?", (plane_issue_id,)
+        )
+        deleted = cur.rowcount
+        conn.commit()
+        conn.close()
+        if deleted:
+            print(_ok(f"CLEANUP DB: deleted {deleted} task row(s) for plane_id={plane_issue_id}"))
+        else:
+            print(_info(f"CLEANUP DB: no task row found for plane_id={plane_issue_id}"))
+    except Exception as e:
+        print(_fail(f"CLEANUP DB: error: {e}"))
+
+
+def _cleanup_staging_jobs(plane_issue_id: str):
+    """Delete job queue rows for the test task from staging SQLite DB."""
+    if not plane_issue_id:
+        return
+    try:
+        import sqlite3
+        conn = sqlite3.connect(STAGING_DB_PATH)
+        # Find task ids for this plane_id first
+        task_rows = conn.execute(
+            "SELECT id FROM tasks WHERE plane_id = ?", (plane_issue_id,)
+        ).fetchall()
+        if task_rows:
+            task_ids = [r[0] for r in task_rows]
+            placeholders = ",".join("?" * len(task_ids))
+            cur = conn.execute(
+                f"DELETE FROM jobs WHERE task_id IN ({placeholders})", task_ids
+            )
+            deleted = cur.rowcount
+            conn.commit()
+            if deleted:
+                print(_ok(f"CLEANUP DB: deleted {deleted} job row(s) for task_ids={task_ids}"))
+        conn.close()
+    except Exception as e:
+        print(_fail(f"CLEANUP DB jobs: error: {e}"))
+
+
+def _cleanup_dedup(plane_issue_id: str, wh_body_sha: str | None = None):
+    """Remove dedup event entries for the test webhook delivery."""
+    if not wh_body_sha:
+        return
+    try:
+        import sqlite3
+        conn = sqlite3.connect(STAGING_DB_PATH)
+        cur = conn.execute(
+            "DELETE FROM events_dedup WHERE delivery_id = ?", (wh_body_sha,)
+        )
+        deleted = cur.rowcount
+        conn.commit()
+        conn.close()
+        if deleted:
+            print(_ok(f"CLEANUP DB: removed {deleted} dedup entry"))
+    except Exception as e:
+        # dedup table might not exist or different schema — not critical
+        print(_info(f"CLEANUP DB dedup: {e}"))
+
+
+def block_c(base: str, results: Results, mode: str):
+    print(f"\n{_BOLD}[Block C] E2E  (mode={mode}){_RESET}")
+
+    plane_token = os.environ.get("ORCH_PLANE_API_TOKEN", "")
+    plane_base_env = os.environ.get("ORCH_PLANE_API_URL", "http://localhost:8091")
+    plane_base = plane_base_env.rstrip("/") + "/api/v1"
+    workspace = os.environ.get("ORCH_PLANE_WORKSPACE_SLUG", "ag_proj")
+    gitea_token = os.environ.get("ORCH_GITEA_TOKEN", "")
+    gitea_base = os.environ.get("ORCH_GITEA_URL", "http://localhost:3000")
+    webhook_secret = os.environ.get("ORCH_PLANE_WEBHOOK_SECRET", "")
+
+    plane_headers = {"X-API-Key": plane_token}
+    gitea_headers = {"Authorization": f"token {gitea_token}"}
+
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%S")
+    issue_name = f"[staging-check] e2e {ts}"
+    issue_desc = (
+        "Automated e2e check created by staging_check.py. "
+        "This task tests the live staging pipeline end-to-end. "
+        "Safe to delete — cleanup runs in finally block."
+    )
+
+    issue_id = None
+    branch_name = None
+    wh_body_bytes = None
+
+    try:
+        # C7 — Create task in Plane SANDBOX
+        print(_info(f"C7: Creating issue in SANDBOX project..."))
+        url = f"{plane_base}/workspaces/{workspace}/projects/{SANDBOX_PROJECT_ID}/issues/"
+        status, data = _post(url, headers=plane_headers, payload={
+            "name": issue_name,
+            "description_html": f"<p>{issue_desc}</p>",
+            "description_stripped": issue_desc,
+        })
+        issue_id = data.get("id")
+        ok = status in (200, 201) and bool(issue_id)
+        results.add("C7 Create issue in Plane SANDBOX", ok,
+                    f"HTTP {status}, issue_id={issue_id}")
+        if not ok:
+            print(_fail(f"  Cannot continue C8-C9 without issue. body={data}"))
+            results.add("C8 Trigger pipeline via /webhook/plane", False, "skipped: C7 failed")
+            results.add("C9a Branch appears in orchestrator-sandbox", False, "skipped")
+            results.add("C9b Analyst job enqueued in staging queue", False, "skipped")
+            return
+
+        # Small delay to let Plane finish persisting the issue
+        time.sleep(2)
+
+        # C8 — Trigger pipeline via direct POST to /webhook/plane
+        print(_info(f"C8: Triggering pipeline via POST /webhook/plane ..."))
+        wh_payload = _make_webhook_payload(issue_id, issue_name, issue_desc)
+        wh_body_bytes = json.dumps(wh_payload).encode()
+
+        wh_headers = {"Content-Type": "application/json"}
+        if webhook_secret:
+            sig = _sign_payload(webhook_secret, wh_body_bytes)
+            wh_headers["X-Plane-Signature"] = sig
+            print(_info(f"  Using HMAC signature (secret len={len(webhook_secret)})"))
+        else:
+            print(_info("  No webhook secret configured, sending without signature"))
+
+        status, resp = _post(f"{base}/webhook/plane",
+                             headers=wh_headers,
+                             raw_body=wh_body_bytes)
+        ok = status == 200 and resp.get("status") in ("accepted",)
+        results.add("C8 Trigger pipeline via /webhook/plane", ok,
+                    f"HTTP {status}, resp={resp}")
+        if not ok:
+            print(_fail(f"  Pipeline trigger failed. Cannot verify C9."))
+            results.add("C9a Branch appears in orchestrator-sandbox", False, "skipped: C8 failed")
+            results.add("C9b Analyst job enqueued in staging queue", False, "skipped: C8 failed")
+            return
+
+        # C9a — Poll for branch in Gitea orchestrator-sandbox
+        print(_info("C9a: Polling for branch in orchestrator-sandbox (up to 60s)..."))
+
+        def _check_branch():
+            try:
+                burl = f"{gitea_base}/api/v1/repos/admin/orchestrator-sandbox/branches"
+                s, bdata = _get(burl, headers=gitea_headers)
+                if s != 200:
+                    return None
+                branches = bdata if isinstance(bdata, list) else bdata.get("results", [])
+                for b in branches:
+                    bname = b.get("name", "")
+                    # Branch name: feature/SANDBOX-NNN-staging-check-...
+                    if "feature/" in bname and "staging-check" in bname:
+                        return bname
+                return None
+            except Exception:
+                return None
+
+        branch_name = _poll(_check_branch, timeout=60, interval=3,
+                             label="waiting for branch")
+        ok = bool(branch_name)
+        results.add("C9a Branch appears in orchestrator-sandbox", ok,
+                    f"branch={branch_name or 'not found'}")
+
+        # C9b — Verify analyst job was enqueued via staging /queue
+        # NOTE: The orchestrator posts a "🔍 Analyst запущен" comment to Plane using
+        # per-agent bot tokens (ORCH_PLANE_BOT_ANALYST). In staging, the sandbox
+        # project was created after the bot accounts were provisioned, so the bots are
+        # not yet members of the SANDBOX project → add_comment returns 403 Forbidden.
+        # This is a known staging infrastructure limitation (not a pipeline bug).
+        # We therefore verify pipeline success via /queue (recent jobs): the analyst
+        # job is enqueued BEFORE the add_comment call, so its presence in the queue
+        # confirms the pipeline ran through to job dispatch.
+        print(_info("C9b: Checking staging job queue for analyst job (up to 30s)..."))
+        print(_info("  (Plane comment check skipped: bot-tokens not added to SANDBOX project)"))
+
+        def _check_queue():
+            try:
+                s, qdata = _get(f"{base}/queue")
+                if s != 200:
+                    return None
+                recent = qdata.get("recent", [])
+                for job in recent:
+                    if (job.get("agent") == "analyst"
+                            and job.get("repo") == "orchestrator-sandbox"
+                            and issue_name in (job.get("task_content") or "")):
+                        return job
+                return None
+            except Exception:
+                return None
+
+        analyst_job = _poll(_check_queue, timeout=30, interval=2,
+                             label="waiting for analyst job in queue")
+        ok = bool(analyst_job)
+        detail = ""
+        if analyst_job:
+            detail = (f"job_id={analyst_job.get('id')}, "
+                      f"status={analyst_job.get('status')}, "
+                      f"agent={analyst_job.get('agent')}")
+        results.add("C9b Analyst job enqueued in staging queue", ok, detail)
+
+    finally:
+        # C10 — CLEANUP (always runs)
+        print(f"\n{_BOLD}[CLEANUP]{_RESET}")
+        _cleanup(
+            plane_base=plane_base,
+            workspace=workspace,
+            gitea_base=gitea_base,
+            plane_headers=plane_headers,
+            gitea_headers=gitea_headers,
+            issue_id=issue_id,
+            branch_name=branch_name,
+            wh_body_bytes=wh_body_bytes,
+        )
+
+
+def _cleanup(plane_base, workspace, gitea_base, plane_headers, gitea_headers,
+             issue_id, branch_name, wh_body_bytes=None):
+    """Delete test branch in Gitea, test issue in Plane SANDBOX, and DB rows."""
+
+    # Delete branch in Gitea
+    if branch_name:
+        try:
+            burl = (f"{gitea_base}/api/v1/repos/admin/orchestrator-sandbox"
+                    f"/branches/{urllib.parse.quote(branch_name, safe='')}")
+            s = _delete(burl, headers=gitea_headers)
+            if s in (200, 204, 404):
+                print(_ok(f"CLEANUP: deleted branch {branch_name!r} (HTTP {s})"))
+            else:
+                print(_fail(f"CLEANUP: delete branch returned HTTP {s}"))
+        except Exception as e:
+            print(_fail(f"CLEANUP: delete branch error: {e}"))
+    else:
+        print(_info("CLEANUP: no branch to delete"))
+
+    # Delete issue in Plane SANDBOX
+    if issue_id:
+        try:
+            iurl = (f"{plane_base}/workspaces/{workspace}/projects/"
+                    f"{SANDBOX_PROJECT_ID}/issues/{issue_id}/")
+            s = _delete(iurl, headers=plane_headers)
+            if s in (200, 204, 404):
+                print(_ok(f"CLEANUP: deleted Plane issue {issue_id} (HTTP {s})"))
+            else:
+                print(_fail(f"CLEANUP: delete Plane issue returned HTTP {s}"))
+        except Exception as e:
+            print(_fail(f"CLEANUP: delete Plane issue error: {e}"))
+    else:
+        print(_info("CLEANUP: no issue to delete"))
+
+    # Delete task + jobs from staging DB
+    if issue_id:
+        _cleanup_staging_jobs(issue_id)
+        _cleanup_staging_db(issue_id)
+
+    # Remove dedup entry so future re-runs with same body don't get "duplicate"
+    if wh_body_bytes is not None:
+        import hashlib as _hl
+        dedup_id = "plane" + _hl.sha256(b"plane" + wh_body_bytes).hexdigest()
+        _cleanup_dedup(issue_id, dedup_id)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Live staging-stand check suite (ORCH-33)"
+    )
+    parser.add_argument(
+        "--base-url",
+        default="http://localhost:8501",
+        help="Base URL of the staging orchestrator (default: http://localhost:8501)",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["stub", "full-real"],
+        default="stub",
+        help=(
+            "stub (default): check early pipeline artifacts only (branch+job), "
+            "no LLM spend. "
+            "full-real: also wait for the analyst agent (slow, costs credits)."
+        ),
+    )
+    args = parser.parse_args()
+
+    base = args.base_url.rstrip("/")
+
+    print(f"{_BOLD}{'='*60}{_RESET}")
+    print(f"{_BOLD}  ORCH-33 Staging Check Suite{_RESET}")
+    print(f"  base_url : {base}")
+    print(f"  mode     : {args.mode}")
+    print(f"  utc_time : {datetime.datetime.now(datetime.timezone.utc).isoformat()}")
+    print(f"{_BOLD}{'='*60}{_RESET}")
+
+    results = Results()
+
+    block_a(base, results)
+    block_b(results)
+    block_c(base, results, args.mode)
+
+    all_ok = results.summary()
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

src/agents/launcher.py

@@ -15,6 +15,82 @@ from ..plane_sync import notify_stage_change as plane_notify_stage, add_comment
 
 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):
     """L-2: best-effort rotation of per-run logs (<runs_dir>/*.log).
@@ -85,7 +161,6 @@ class AgentLauncher:
             "system_prompt": ".openclaw/agents/architect.md",
             "task_file": ".task-arch.md",
             "allowed_tools": "Read,Write,Edit,Bash",
-            "model": "opus",
         },
         "developer": {
             "system_prompt": ".openclaw/agents/developer.md",
@@ -96,7 +171,6 @@ class AgentLauncher:
             "system_prompt": ".openclaw/agents/reviewer.md",
             "task_file": ".task-review.md",
             "allowed_tools": "Read,Write,Edit,Bash",
-            "model": "opus",
         },
         "tester": {
             "system_prompt": ".openclaw/agents/tester.md",
@@ -171,6 +245,12 @@ class AgentLauncher:
         _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"
 
+        # 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.
         work_path = ensure_worktree(repo, agent_branch)
 
@@ -204,8 +284,14 @@ class AgentLauncher:
         system_prompt = config["system_prompt"]
         allowed_tools = config["allowed_tools"]
 
-        model = config.get("model", "")
+        # ORCH-41: model + effort + optional fallback are resolved from config
+        # (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 ""
+        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
         # the right branch. The agent simply runs inside its isolated work_path.
@@ -218,7 +304,7 @@ class AgentLauncher:
             f'cd {work_path} && '
             f'{self.CLAUDE_BIN} --print '
             f'--output-format json '
-            f'{model_flag}'
+            f'{model_flag}{effort_flag}{fb_flag}'
             f'"$(cat {task_file})" '
             f'--system-prompt "$(cat {system_prompt})" '
             f'--allowedTools {allowed_tools}'
@@ -507,11 +593,15 @@ class AgentLauncher:
                 from ..notifications import send_telegram
                 send_telegram(f"\u26a0\ufe0f {_wid}: Agent {agent} failed (exit_code={exit_code}). Check logs: /app/data/runs/{run_id}.log")
 
-        # Feature 4: post the per-agent usage comment under that agent's bot, and
-        # — for the deployer finishing the task — the per-task usage summary.
+        # Feature 4 + ORCH-016: post the unified per-agent status comment under
+        # that agent's bot, threading the wall-clock duration we just measured
+        # straight through (ADR-001 §6: explicit param wins over DB fallback).
+        # The deployer finishing the task also posts the per-task usage summary.
         if exit_code == 0:
             try:
-                self._post_usage_comments(run_id, agent, repo, branch, _usage)
+                self._post_usage_comments(
+                    run_id, agent, repo, branch, _usage, duration_s=_duration_s
+                )
             except Exception as e:
                 logger.warning(f"run_id={run_id}: usage comment failed: {e}")
 
@@ -679,42 +769,67 @@ class AgentLauncher:
             logger.error(f"Auto-advance failed for run_id={run_id}: {e}")
 
 
-    def _post_usage_comments(self, run_id, agent, repo, branch, usage):
-        """Feature 4: post the per-agent usage comment (and Deployer summary).
+    def _post_usage_comments(self, run_id, agent, repo, branch, usage, duration_s=None):
+        """Feature 4 + ORCH-016: post the unified per-agent status comment.
 
         - Always (on success, with a work_item_id): a per-agent finish comment
-          with token/cost, authored by the finishing agent's Plane bot.
+          via ``usage.build_status_comment(...)``, authored by the finishing
+          agent's Plane bot. The comment carries:
+            * single-line header (icon + role + per-stage description),
+            * machine verdict line for reviewer / tester / deployer (when the
+              relevant frontmatter is present in the worktree),
+            * the agent's wall-clock duration (``duration_s`` is the measured
+              value in _monitor_agent; DB fallback is unused on this path),
+            * an HTML <ul> of artifact links scoped per agent,
+            * a ``<sub>`` token/cost tail.
         - When the deployer finishes: also a per-task summary (SUM over
           agent_runs GROUP BY agent), authored by the deployer.
+
+        The deployer's `stage=` is resolved from the task row so the helper can
+        pick between 14-deploy-log.md (prod) and 15-staging-log.md (staging).
         """
-        from ..usage import usage_comment, task_summary_comment
+        from ..usage import build_status_comment, task_summary_comment
+        from ..git_worktree import get_worktree_path
         conn = get_db()
         row = conn.execute(
-            "SELECT id, work_item_id FROM tasks WHERE repo=? AND branch=?",
+            "SELECT id, work_item_id, stage FROM tasks WHERE repo=? AND branch=?",
             (repo, branch),
         ).fetchone()
         conn.close()
         if not row:
             return
-        task_id, work_item_id = row[0], row[1]
+        task_id, work_item_id, stage = row[0], row[1], row[2]
         if not work_item_id:
             return
         # Observability: every agent's finish comment links its artifact(s)
-        # (reviewer->12-review, tester->13-test-report, deployer->14-deploy-log,
+        # (reviewer->12-review, tester->13-test-report, deployer->14- or 15-,
         # architect->ADR, developer->PR/branch). For the developer we resolve the
         # open PR number so the link points straight at it.
         pr_number = None
         if agent == "developer":
             pr_number = self._open_pr_number(repo, branch)
+
+        # Best-effort worktree path — drives AC-8 (skip missing artifacts) and
+        # the verdict frontmatter read. Falls back to None on lookup error so
+        # the comment still goes out without the verdict line / file probe.
+        try:
+            worktree_root = get_worktree_path(repo, branch)
+        except Exception:
+            worktree_root = None
+
         plane_add_comment(
             work_item_id,
-            usage_comment(
+            build_status_comment(
                 agent,
-                usage,
                 repo=repo,
                 branch=branch,
                 work_item_id=work_item_id,
                 pr_number=pr_number,
+                stage=stage,
+                usage=usage,
+                duration_s=duration_s,
+                task_id=task_id,
+                worktree_root=worktree_root,
             ),
             author=agent,
         )

src/config.py

@@ -4,6 +4,11 @@ from pydantic_settings import BaseSettings
 class Settings(BaseSettings):
     # Plane
     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_workspace_slug: str = ""
     plane_webhook_secret: str = ""
@@ -78,6 +83,34 @@ class Settings(BaseSettings):
     agent_kill_grace_seconds: int = 20
     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
     # 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

src/frontmatter.py

@@ -0,0 +1,75 @@
+"""Safe single-key YAML frontmatter reader (ORCH-016 / ADR-001 §5).
+
+The status-comment builder (build_status_comment) needs to surface verdict /
+deploy_status / staging_status from the per-stage artifact files (12-review.md,
+13-test-report.md, 14-deploy-log.md, 15-staging-log.md). Those files share the
+same leading-YAML-frontmatter convention used by the quality gates — but the
+comment hot-path must NEVER raise: a missing file, malformed YAML, or absent
+key should simply suppress the verdict line, not break the run.
+
+This module is a tiny defensive helper:
+  - `read_frontmatter_value(path, key)` -> str | None
+  - swallows every exception, logs to logger.debug, returns None.
+
+It intentionally duplicates ~10 lines of YAML-frontmatter logic that already
+exist in `src/qg/checks.py` (S-5 / БАГ 8 / ET-013 fixes). ADR-001 §5 accepts
+this duplication to keep the blast radius of ORCH-016 small (no QG refactor in
+this PR); merging into a single parser is a follow-up task.
+"""
+
+import logging
+
+logger = logging.getLogger("orchestrator.frontmatter")
+
+
+def read_frontmatter_value(path: str, key: str) -> str | None:
+    """Return the value of `key` from the leading YAML frontmatter of `path`.
+
+    Format expected (canonical, matching qg/checks.py):
+        ---
+        key: value
+        other: ...
+        ---
+        <body>
+
+    Never raises. Returns None for any of:
+      - missing/unreadable file,
+      - no leading `---` frontmatter,
+      - malformed/unterminated frontmatter,
+      - YAML parse error,
+      - frontmatter is not a mapping,
+      - key absent (or its value is None/empty).
+
+    The returned value is stringified and stripped (whitespace removed); casing
+    is preserved so the caller decides whether to upper/lower for matching.
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            content = f.read()
+    except OSError as e:
+        logger.debug(f"read_frontmatter_value: cannot open {path}: {e}")
+        return None
+
+    if not content.startswith("---"):
+        return None
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        # Unterminated frontmatter.
+        return None
+
+    try:
+        import yaml
+        fm = yaml.safe_load(parts[1]) or {}
+    except Exception as e:  # yaml.YAMLError + anything pyyaml may surface
+        logger.debug(f"read_frontmatter_value: yaml parse failed for {path}: {e}")
+        return None
+
+    if not isinstance(fm, dict):
+        return None
+
+    raw = fm.get(key)
+    if raw is None:
+        return None
+    value = str(raw).strip()
+    return value or None

src/notifications.py

@@ -544,6 +544,105 @@ 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}")
 
 
+# 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):
     """ALERT (separate, notifying): BRD/TZ/AC ready -> flip Plane to Approved.
 
@@ -557,10 +656,27 @@ def notify_approve_requested(task_id: int):
     except Exception as e:
         logger.warning(f"notify_approve_requested: brd clock start failed: {e}")
     msg = (
-        f"\U0001f4cb {work_item_id}: BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. "
+        f"\U0001f4cb {html.escape(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"\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)
     update_task_tracker(task_id)
     send_telegram(msg)  # separate, notifying

src/plane_sync.py

@@ -84,31 +84,131 @@ def _resolve_project_id(work_item_id: str = None, project_id: str = None) -> str
             logger.debug(f"_resolve_project_id fallback for {work_item_id}: {e}")
     return PROJECT_ID
 
-# Plane state IDs.
-# TODO(ORCH-10): these UUIDs are PER-PROJECT. The 6 stage-visibility / verdict
-# statuses below were created only in the enduro project (7a79f0a9-...). One
-# project is in prod today, so a single global dict is acceptable. When more
-# projects are onboarded these must be resolved per project (see ORCH-10 in
-# BACKLOG.md / the ORCH-6 project registry) — do NOT hardcode globally then.
-PLANE_STATES = {
-    "backlog": "113b24f6-cce8-4be9-9a22-a359b9cf0122",
-    "todo": "2c7d3df3-9eb9-419b-92b7-d7d560bcdd10",
-    "in_progress": "b873d9eb-993c-48cd-97ac-99a9b1623967",
-    "needs_input": "babf08a3-ff4d-41f3-a821-5491aa29a8ac",
-    "in_review": "38fb1f64-aa1e-48a3-92e0-0b109679046b",
-    "blocked": "6c4543f9-ac47-4ef7-ae0f-070020dc9920",
-    "done": "381a2833-3c4e-4be5-bd0f-be84cb946ad8",
-    "cancelled": "b1cae7f9-961d-4889-a179-f3acea697d17",
+# ORCH-10: per-project state resolution.
+#
+# _DEFAULT_STATES keeps the original enduro-trails UUIDs as a safe fallback
+# (used when the Plane API is unreachable and for backward compat).
+# PLANE_STATES is preserved as an alias so existing call sites that reference
+# it directly (QG-0 fast-path in webhooks/plane.py, tests) continue to work.
+_DEFAULT_STATES = {
+    "backlog":      "113b24f6-cce8-4be9-9a22-a359b9cf0122",
+    "todo":         "2c7d3df3-9eb9-419b-92b7-d7d560bcdd10",
+    "in_progress":  "b873d9eb-993c-48cd-97ac-99a9b1623967",
+    "needs_input":  "babf08a3-ff4d-41f3-a821-5491aa29a8ac",
+    "in_review":    "38fb1f64-aa1e-48a3-92e0-0b109679046b",
+    "blocked":      "6c4543f9-ac47-4ef7-ae0f-070020dc9920",
+    "done":         "381a2833-3c4e-4be5-bd0f-be84cb946ad8",
+    "cancelled":    "b1cae7f9-961d-4889-a179-f3acea697d17",
     # Feature 3 (stage visibility) — per-stage statuses on the board.
     "architecture": "3020bbb7-6122-4663-930c-0315ba8dfa3d",
-    "development": "9920609b-f140-4e46-ab95-89acda8412c8",
-    "review": "ba0d802c-5218-41d4-ab43-978b0ea123ed",
-    "testing": "7855d807-b1bf-42ef-8dae-6cde0df92d02",
+    "development":  "9920609b-f140-4e46-ab95-89acda8412c8",
+    "review":       "ba0d802c-5218-41d4-ab43-978b0ea123ed",
+    "testing":      "7855d807-b1bf-42ef-8dae-6cde0df92d02",
     # Feature 2 (verdict statuses) — Approved / Rejected.
-    "approved": "a519a341-dada-4a91-8910-7604f82b79c5",
-    "rejected": "ba958f3c-5db5-461d-8f82-89425e413b97",
+    "approved":     "a519a341-dada-4a91-8910-7604f82b79c5",
+    "rejected":     "ba958f3c-5db5-461d-8f82-89425e413b97",
 }
 
+# Backward-compat alias — do NOT remove (tests + webhooks/plane.py import it).
+PLANE_STATES = _DEFAULT_STATES
+
+# Mapping: Plane state *name* (as returned by the API) -> logical key.
+_PLANE_NAME_TO_KEY: dict[str, str] = {
+    "Backlog":      "backlog",
+    "Todo":         "todo",
+    "In Progress":  "in_progress",
+    "Architecture": "architecture",
+    "Development":  "development",
+    "Review":       "review",
+    "Testing":      "testing",
+    "Approved":     "approved",
+    "Rejected":     "rejected",
+    "Done":         "done",
+    "Cancelled":    "cancelled",
+    "Needs Input":  "needs_input",
+    "In Review":    "in_review",
+    "Blocked":      "blocked",
+}
+
+# Per-project state cache: {project_id: {logical_key: state_uuid}}
+_STATES_CACHE: dict[str, dict[str, str]] = {}
+
+
+def get_project_states(project_id: str) -> dict[str, str]:
+    """ORCH-10: resolve {logical_key -> state_uuid} for a specific Plane project.
+
+    Source of truth: Plane API GET /projects/<project_id>/states/.
+    Results are cached per project_id for the lifetime of the process.
+    Falls back to _DEFAULT_STATES (enduro-trails values) if:
+      * project_id is empty/None,
+      * the API call fails (network error, non-2xx),
+      * the response contains no recognisable states.
+
+    The enduro-trails project therefore returns the same UUIDs as before
+    (backward compatible). The orchestrator project returns its own UUIDs,
+    fixing the ORCH-10 blocker.
+    """
+    if not project_id:
+        return _DEFAULT_STATES
+
+    if project_id in _STATES_CACHE:
+        return _STATES_CACHE[project_id]
+
+    url = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{project_id}/states/"
+    try:
+        resp = httpx.get(url, headers=PLANE_HEADERS, timeout=10)
+        resp.raise_for_status()
+        body = resp.json()
+        # Plane returns {"results": [...]} or a bare list.
+        items = body.get("results", body) if isinstance(body, dict) else body
+        if not isinstance(items, list):
+            raise ValueError(f"unexpected states response shape: {type(items)}")
+
+        resolved: dict[str, str] = {}
+        for item in items:
+            name = item.get("name", "")
+            uid = item.get("id", "")
+            key = _PLANE_NAME_TO_KEY.get(name)
+            if key and uid:
+                resolved[key] = uid
+
+        if not resolved:
+            raise ValueError("no recognisable states in API response")
+
+        # Fill any missing keys from _DEFAULT_STATES so callers always get a
+        # complete mapping (defensive against partial Plane configs).
+        for k, v in _DEFAULT_STATES.items():
+            resolved.setdefault(k, v)
+
+        _STATES_CACHE[project_id] = resolved
+        logger.debug(
+            f"get_project_states: cached {len(resolved)} states for project {project_id[:8]}..."
+        )
+        return resolved
+
+    except Exception as e:
+        logger.warning(
+            f"get_project_states: API failed for project {project_id[:8]}..., "
+            f"falling back to _DEFAULT_STATES. Error: {e}"
+        )
+        return _DEFAULT_STATES
+
+
+def reload_project_states(project_id: str = None) -> None:
+    """ORCH-10: clear the per-project states cache.
+
+    If project_id is given, evict only that project.
+    If None, flush the entire cache (useful in tests and after config reload).
+    """
+    global _STATES_CACHE
+    if project_id is None:
+        _STATES_CACHE = {}
+        logger.debug("reload_project_states: full cache cleared")
+    else:
+        _STATES_CACHE.pop(project_id, None)
+        logger.debug(f"reload_project_states: evicted project {project_id[:8]}...")
+
+
 # Feature 3: map an orchestrator stage -> the Plane status to show on the board
 # when the pipeline ENTERS that stage. analysis stays driven by the existing
 # in_progress/in_review/needs_input logic (no dedicated status). deploy keeps
@@ -121,21 +221,44 @@ STAGE_VISIBILITY_STATE = {
     "testing": "testing",
 }
 
-# Map orchestrator stages to Plane states (used by update_issue_state /
-# notify_stage_change). Feature 3: architecture/development/review/testing now
-# point at their dedicated board statuses so the task physically moves across
-# columns. analysis -> in_progress, deploy -> in_progress, done -> done.
+# STAGE_TO_STATE kept for backward compat (used by tests that patch it).
+# update_issue_state now calls stage_to_state() instead of looking up here.
 STAGE_TO_STATE = {
-    "created": PLANE_STATES["todo"],
-    "analysis": PLANE_STATES["in_progress"],
-    "architecture": PLANE_STATES["architecture"],
-    "development": PLANE_STATES["development"],
-    "review": PLANE_STATES["review"],
-    "testing": PLANE_STATES["testing"],
-    "deploy": PLANE_STATES["in_progress"],
-    "done": PLANE_STATES["done"],
+    "created":      _DEFAULT_STATES["todo"],
+    "analysis":     _DEFAULT_STATES["in_progress"],
+    "architecture": _DEFAULT_STATES["architecture"],
+    "development":  _DEFAULT_STATES["development"],
+    "review":       _DEFAULT_STATES["review"],
+    "testing":      _DEFAULT_STATES["testing"],
+    "deploy":       _DEFAULT_STATES["in_progress"],
+    "done":         _DEFAULT_STATES["done"],
 }
 
+# Map orchestrator stage -> logical state key (project-independent).
+_STAGE_TO_STATE_KEY = {
+    "created":      "todo",
+    "analysis":     "in_progress",
+    "architecture": "architecture",
+    "development":  "development",
+    "review":       "review",
+    "testing":      "testing",
+    "deploy":       "in_progress",
+    "done":         "done",
+}
+
+
+def stage_to_state(stage: str, project_id: str) -> str | None:
+    """ORCH-10: return the Plane state UUID for a pipeline stage in a project.
+
+    Resolves via get_project_states so the correct per-project UUID is used.
+    Returns None for unknown stages (same behaviour as the old STAGE_TO_STATE
+    dict lookup returning None).
+    """
+    key = _STAGE_TO_STATE_KEY.get(stage)
+    if not key:
+        return None
+    return get_project_states(project_id).get(key)
+
 
 def fetch_issue_sequence_id(issue_id: str, project_id: str) -> int | None:
     """M-6: GET the Plane issue by UUID and return its sequence_id (the
@@ -284,11 +407,12 @@ def find_issue_id(work_item_id: str, project_id: str = None) -> str | None:
 
 def update_issue_state(work_item_id: str, stage: str, project_id: str = None):
     """Update Plane issue state based on orchestrator stage."""
-    state_id = STAGE_TO_STATE.get(stage)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    # ORCH-10: resolve state UUID for this specific project (not global dict).
+    state_id = stage_to_state(stage, project_id)
     if not state_id:
         return
 
-    project_id = _resolve_project_id(work_item_id, project_id)
     issue_id = find_issue_id(work_item_id, project_id)
     if not issue_id:
         logger.warning(f"Issue not found in Plane for {work_item_id}")
@@ -327,20 +451,25 @@ def add_comment(work_item_id: str, text: str, project_id: str = None, author: st
         logger.error(f"Failed to add comment to {work_item_id}: {e}")
 
 
-
 def set_issue_needs_input(work_item_id: str, project_id: str = None):
     """Set issue to 'Needs Input' state — waiting for stakeholder response."""
-    _set_issue_state_direct(work_item_id, PLANE_STATES["needs_input"], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["needs_input"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def set_issue_in_review(work_item_id: str, project_id: str = None):
     """Set issue to 'In Review' state — waiting for :approved: or :rejected:."""
-    _set_issue_state_direct(work_item_id, PLANE_STATES["in_review"], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["in_review"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def set_issue_blocked(work_item_id: str, project_id: str = None):
     """Set issue to 'Blocked' state — manual intervention needed."""
-    _set_issue_state_direct(work_item_id, PLANE_STATES["blocked"], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["blocked"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def set_issue_done(work_item_id: str, project_id: str = None):
@@ -348,15 +477,19 @@ def set_issue_done(work_item_id: str, project_id: str = None):
 
     Used by the deploy->done success path so a completed task always reaches the
     terminal Plane state (it used to stick on In Progress because the merge
-    webhook bypassed the stage engine). Uses the existing PLANE_STATES['done']
-    UUID — the mapping itself is NOT changed.
+    webhook bypassed the stage engine). Resolves per-project UUID via
+    get_project_states (ORCH-10).
     """
-    _set_issue_state_direct(work_item_id, PLANE_STATES["done"], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["done"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def set_issue_in_progress(work_item_id: str, project_id: str = None):
     """Set issue to 'In Progress' state — agent working."""
-    _set_issue_state_direct(work_item_id, PLANE_STATES["in_progress"], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["in_progress"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def set_issue_stage_state(work_item_id: str, stage: str, project_id: str = None):
@@ -371,7 +504,10 @@ def set_issue_stage_state(work_item_id: str, stage: str, project_id: str = None)
     state_key = STAGE_VISIBILITY_STATE.get(stage)
     if not state_key:
         return
-    _set_issue_state_direct(work_item_id, PLANE_STATES[state_key], project_id)
+    project_id = _resolve_project_id(work_item_id, project_id)
+    # ORCH-10: resolve per-project UUID.
+    state_id = get_project_states(project_id)[state_key]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
 def _set_issue_state_direct(work_item_id: str, state_id: str, project_id: str = None):

src/projects.py

@@ -17,7 +17,7 @@ registry is used so the system works out of the box.
 
 import json
 import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from .config import settings
 
@@ -30,6 +30,11 @@ class ProjectConfig:
     repo: str               # gitea repo name (== folder under /repos)
     work_item_prefix: str   # ET / ORCH
     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).
@@ -50,6 +55,23 @@ _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:
     """Parse ORCH_PROJECTS_JSON. Returns None if empty/invalid (-> use default)."""
     if not raw or not raw.strip():
@@ -75,6 +97,8 @@ def _parse_projects_json(raw: str) -> list[ProjectConfig] | None:
                     repo=str(item["repo"]),
                     work_item_prefix=str(item["work_item_prefix"]),
                     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:

src/qg/checks.py

@@ -440,6 +440,130 @@ def check_deploy_status(repo: str, work_item_id: str, branch: str | None = None)
     return False, "Deploy log not found (14-deploy-log.md)"
 
 
+
+# ---------------------------------------------------------------------------
+# Self-hosting detection: staging-infra (localhost:8501) exists ONLY for the
+# orchestrator repo itself (self-hosting). Other repos have no staging instance
+# and their deployer prompts know nothing about it -- the gate must be a no-op
+# for them. The repo value is the plain gitea repo name (ProjectConfig.repo),
+# matching what _run_qg/advance_stage pass in. See ORCH-35 / PR #31.
+# ---------------------------------------------------------------------------
+SELF_HOSTING_REPO = "orchestrator"
+
+
+def is_self_hosting_repo(repo: str) -> bool:
+    """Return True iff repo is the self-hosted orchestrator (has staging infra).
+
+    Comparison is case-insensitive and strips whitespace for safety, but in
+    practice repo comes from the gitea webhook payload .repository.name which
+    is always lowercase (confirmed via projects.py registry entry).
+    """
+    return (repo or "").strip().lower() == SELF_HOSTING_REPO.lower()
+
+
+def _parse_staging_status(content: str) -> tuple[bool, str]:
+    """Parse a 15-staging-log.md body and map its `staging_status:` frontmatter to a
+    quality-gate verdict. Reads ONLY the machine-readable YAML field, never prose.
+
+      staging_status: SUCCESS -> (True,  "Staging status: SUCCESS")
+      staging_status: FAILED  -> (False, "Staging status: FAILED")
+      missing field / no frontmatter / bad YAML -> (False, <reason>)
+    """
+    import yaml
+    status = None
+    if content.startswith("---"):
+        parts = content.split("---", 2)
+        if len(parts) >= 3:
+            try:
+                fm = yaml.safe_load(parts[1]) or {}
+            except yaml.YAMLError as e:
+                return False, f"Invalid YAML frontmatter in staging log: {e}"
+            status = str(fm.get("staging_status", "")).upper().strip()
+    if status == "SUCCESS":
+        return True, "Staging status: SUCCESS"
+    if status == "FAILED":
+        return False, "Staging status: FAILED"
+    return False, f"No machine-readable staging_status in frontmatter (got: {status!r})"
+
+
+def _staging_log_from_main(repo: str, work_item_id: str) -> str | None:
+    """Best-effort read of 15-staging-log.md from origin/main on the shared clone.
+
+    The deployer writes 15-staging-log.md and merges the staging artifacts into main
+    via a separate PR (mirroring the deploy-log pattern), so the file lands in
+    origin/main, NOT in the feature branch worktree the gate normally reads.
+    This recovers it from main.
+
+    Degrades gracefully: any git failure (no clone, network/fetch error, file
+    absent in main) returns None instead of raising, so the caller falls back to
+    the plain "not found" verdict. Never raises.
+    """
+    repo_clone = os.path.join(settings.repos_dir, repo)
+    if not os.path.isdir(os.path.join(repo_clone, ".git")):
+        return None
+    rel = f"docs/work-items/{work_item_id}/15-staging-log.md"
+    try:
+        # Refresh origin/main so we see freshly-merged staging artifacts.
+        subprocess.run(
+            ["git", "-C", repo_clone, "fetch", "origin", "main"],
+            check=False, capture_output=True, timeout=30,
+        )
+        show = subprocess.run(
+            ["git", "-C", repo_clone, "show", f"origin/main:{rel}"],
+            check=False, capture_output=True, text=True, timeout=15,
+        )
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("staging-log origin/main lookup failed for %s/%s: %s", repo, work_item_id, e)
+        return None
+    if show.returncode != 0:
+        return None
+    return show.stdout
+
+
+def check_staging_status(repo: str, work_item_id: str, branch: str | None = None) -> tuple[bool, str]:
+    """
+    Gate the deploy-staging -> deploy transition on the deployer's machine-readable
+    verdict in 15-staging-log.md frontmatter (staging_status: SUCCESS|FAILED).
+
+    ORCH-35 conditional gate (Variant A):
+      - Non-self-hosting repos (anything other than "orchestrator") have no staging
+        instance and no deployer knowledge of it -> gate is an immediate pass.
+      - Self-hosting repo ("orchestrator") -> real check: reads ONLY the machine-
+        readable staging_status: field from YAML frontmatter, never body prose.
+
+    Mirrors check_deploy_status (БАГ 8) for the self-hosting path.
+
+    Lookup order (self-hosting only): worktree -> origin/main -> not found.
+
+    Returns:
+      (True, "Staging gate N/A for <repo>") -> non-self-hosting repo (instant pass)
+      (True, ...)  -> staging_status: SUCCESS (self-hosting path)
+      (False, ...) -> staging_status: FAILED, missing field, or no frontmatter
+    """
+    # Variant A: non-self-hosting repos have no staging infra -- skip entirely.
+    if not is_self_hosting_repo(repo):
+        return True, f"Staging gate N/A for {repo}"
+
+    # Self-hosting (orchestrator) path: real verdict check.
+    repo_path = _repo_path(repo, branch)
+    log_path = os.path.join(repo_path, f"docs/work-items/{work_item_id}/15-staging-log.md")
+
+    if os.path.isfile(log_path):
+        try:
+            with open(log_path, "r") as f:
+                content = f.read()
+        except OSError as e:
+            return False, f"Error reading staging log: {e}"
+        return _parse_staging_status(content)
+
+    # Not in the feature worktree -- the deployer may have merged it into main.
+    main_content = _staging_log_from_main(repo, work_item_id)
+    if main_content is not None:
+        return _parse_staging_status(main_content)
+
+    return False, "Staging log not found (15-staging-log.md)"
+
+
 # Registry for dynamic lookup by name
 QG_CHECKS = {
     "check_analysis_approved": check_analysis_approved,
@@ -451,4 +575,5 @@ QG_CHECKS = {
     "check_reviewer_verdict": check_reviewer_verdict,
     "check_tests_local": check_tests_local,
     "check_deploy_status": check_deploy_status,
+    "check_staging_status": check_staging_status,
 }

src/stage_engine.py

@@ -295,56 +295,41 @@ def advance_stage(
         return result
 
 
-def _build_analyst_ready_comment(repo: str, work_item_id: str, branch: str) -> str:
-    """BUG C: HTML comment posted when analyst artifacts are ready.
+def _build_analyst_ready_comment(
+    repo: str, work_item_id: str, branch: str, task_id: int | None = None
+) -> str:
+    """ORCH-016: analyst "artifacts ready" comment via the unified status helper.
 
-    Status-only model (PR #12): approval is the **Approved** status, NOT a
-    ``:approved:`` comment and NOT moving back to In Progress. The comment asks
-    the stakeholder to flip the status and links the documents the analyst
-    actually produced.
+    Historically this function hand-built the HTML for the analyst's BUG-C
+    status-only verdict comment (PR #12 / #13). After ORCH-016 / ADR-001 \u00a71 every
+    agent goes through the single ``usage.build_status_comment(...)`` hot path,
+    so this is now a thin compatibility wrapper that:
 
-    Links point at the Gitea web view:
-      {gitea_url}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{wid}/<file>
-    Only files that REALLY exist in the worktree are listed (no invented docs).
+      - keeps the same 3-positional signature that ``_handle_analysis_approved_flow``
+        and the regression tests (``tests/test_analyst_comment.py``) already call,
+      - adds an optional ``task_id`` so the duration line for the analyst can be
+        resolved via the DB fallback (AC-14: analyst's ``_duration_s`` isn't in
+        scope of stage_engine, hence the fallback),
+      - locates the worktree so AC-8 graceful skipping of missing analyst
+        artifacts and ``gitea_public_url`` clickability work exactly as before.
+
+    All historical text contracts are preserved by the analyst branch inside
+    ``build_status_comment``: \u00abApproved\u00bb, \u00abRejected\u00bb, no \u00ab:approved:\u00bb, no
+    \u00abIn Progress\u00bb \u2014 the existing test_analyst_comment.py assertions still hold.
     """
-    text = (
-        "\u2705 BRD/\u0422\u0417/AC \u0433\u043e\u0442\u043e\u0432\u044b. "
-        "\u0414\u043b\u044f \u043f\u0440\u043e\u0434\u0432\u0438\u0436\u0435\u043d\u0438\u044f "
-        "\u043f\u0435\u0440\u0435\u0432\u0435\u0434\u0438\u0442\u0435 \u0437\u0430\u0434\u0430\u0447\u0443 "
-        "\u0432 \u0441\u0442\u0430\u0442\u0443\u0441 Approved. "
-        "\u0414\u043b\u044f \u043e\u0442\u043a\u043b\u043e\u043d\u0435\u043d\u0438\u044f \u2014 "
-        "\u043d\u0430\u043f\u0438\u0448\u0438\u0442\u0435 \u043f\u0440\u0438\u0447\u0438\u043d\u0443 "
-        "\u043a\u043e\u043c\u043c\u0435\u043d\u0442\u043e\u043c \u0438 \u043f\u0435\u0440\u0435\u0432\u0435\u0434\u0438\u0442\u0435 "
-        "\u0432 Rejected."
-    )
-
-    # Candidate analyst artifacts (label -> filename). Only existing ones linked.
-    candidates = [
-        ("Business request", "00-business-request.md"),
-        ("BRD", "01-brd.md"),
-        ("\u0422\u0417 (TRZ)", "02-trz.md"),
-        ("Acceptance Criteria", "03-acceptance-criteria.md"),
-        ("Test Plan", "04-test-plan.yaml"),
-        ("UI Test Cases", "04b-ui-test-cases.md"),
-    ]
-    rel_dir = f"docs/work-items/{work_item_id}"
+    from .usage import build_status_comment
     try:
-        wt_dir = os.path.join(get_worktree_path(repo, branch), rel_dir)
+        worktree_root = get_worktree_path(repo, branch)
     except Exception:
-        wt_dir = None
-
-    owner = getattr(settings, "gitea_owner", "admin")
-    base = (getattr(settings, "gitea_public_url", "") or settings.gitea_url).rstrip("/")
-    links = []
-    for label, fname in candidates:
-        if wt_dir and not os.path.isfile(os.path.join(wt_dir, fname)):
-            continue
-        href = f"{base}/{owner}/{repo}/src/branch/{branch}/{rel_dir}/{fname}"
-        links.append(f'<li><a href="{href}">{label}</a></li>')
-
-    if links:
-        text += "<br><b>\u0414\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u044b:</b><ul>" + "".join(links) + "</ul>"
-    return text
+        worktree_root = None
+    return build_status_comment(
+        "analyst",
+        repo=repo,
+        branch=branch,
+        work_item_id=work_item_id,
+        task_id=task_id,
+        worktree_root=worktree_root,
+    )
 
 
 def _handle_analysis_approved_flow(
@@ -373,7 +358,9 @@ def _handle_analysis_approved_flow(
         set_issue_in_review(work_item_id)
         plane_add_comment(
             work_item_id,
-            _build_analyst_ready_comment(repo, work_item_id, branch),
+            # task_id is threaded through so build_status_comment can resolve the
+            # analyst duration via agent_runs (ORCH-016 AC-14 DB fallback).
+            _build_analyst_ready_comment(repo, work_item_id, branch, task_id=task_id),
             author="analyst",
         )
         notify_approve_requested(task_id)
@@ -517,6 +504,32 @@ def _handle_qg_failure_rollbacks(
                 f"(job_id={new_job})"
             )
 
+    # ORCH-35: deployer staging verdict FAILED -> roll deploy-staging back to development.
+    # Staging-провал = код плох; откат на development по образцу БАГ-8 (deploy->development).
+    # НЕ трогает ветку check_deploy_status ниже.
+    if agent == "deployer" and qg_name == "check_staging_status":
+        update_task_stage(task_id, "development")
+        notify_stage_change(task_id, current_stage, "development")
+        plane_notify_stage(work_item_id, current_stage, "development")
+        result.rolled_back_to = "development"
+        set_issue_blocked(work_item_id)
+        notify_qg_failure(task_id, "deploy-staging", "check_staging_status", reason)
+        plane_add_comment(
+            work_item_id,
+            f"\u274c Staging gate FAILED ({reason}). Rolled back to development. "
+            f"Developer \u043d\u0443\u0436\u0435\u043d \u0434\u043b\u044f \u0444\u0438\u043a\u0441\u0430.",
+            author="deployer",
+        )
+        send_telegram(
+            f"\U0001f6a8 {work_item_id}: Staging FAILED ({reason}). "
+            f"Rolled back to development. Needs fix."
+        )
+        result.alerted = True
+        logger.error(
+            f"Task {task_id}: deployer staging verdict FAILED, rolled back deploy-staging -> "
+            f"development ({reason})"
+        )
+
     # БАГ 8: deployer verdict FAILED -> roll deploy back to development.
     # The launcher's exit_code-based guard (launcher.py:475) never fires because
     # the LLM process exit code is always 0; this gate fires on the machine-readable

src/stages.py

@@ -1,7 +1,7 @@
 """Stage machine for orchestrator pipeline.
 
 Stages:
-  created → analysis → architecture → development → review → testing → deploy → done
+  created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
 
 Each stage defines:
   - next: the stage to advance to
@@ -15,8 +15,9 @@ STAGE_TRANSITIONS = {
     "architecture": {"next": "development", "agent": "developer", "qg": "check_architecture_done"},
     "development": {"next": "review", "agent": "reviewer", "qg": "check_ci_green"},
     "review": {"next": "testing", "agent": "tester", "qg": "check_reviewer_verdict"},
-    "testing": {"next": "deploy", "agent": "deployer", "qg": "check_tests_passed"},
-    "deploy": {"next": "done", "agent": None, "qg": "check_deploy_status"},
+    "testing":        {"next": "deploy-staging", "agent": "deployer",  "qg": "check_tests_passed"},
+    "deploy-staging": {"next": "deploy",         "agent": "deployer",  "qg": "check_staging_status"},
+    "deploy":         {"next": "done",            "agent": None,        "qg": "check_deploy_status"},
     "done": {"next": None, "agent": None, "qg": None},
 }
 

src/usage.py

@@ -1,4 +1,4 @@
-"""Feature 4: token / cost accounting for agent runs.
+"""Feature 4 + ORCH-016: token / cost accounting and unified status comments.
 
 claude --output-format json emits a single result JSON object at the end of the
 run log with fields:
@@ -8,11 +8,16 @@ run log with fields:
   modelUsage, num_turns, duration_ms
 
 This module parses that JSON out of a (text-or-json) run log, records the usage
-on the agent_runs row, formats a Plane comment for the finishing agent, and
-builds the per-task summary the Deployer posts on deploy/done.
+on the agent_runs row, and builds:
+  - per-agent status comments via build_status_comment(...) — the ORCH-016
+    unified format replacing the legacy usage_comment(...) and the analyst-
+    only stage_engine._build_analyst_ready_comment(...). Every agent now flows
+    through the same hot path.
+  - per-task summary the Deployer posts on deploy/done.
 
-Everything here is defensive: a missing/garbled JSON never raises \u2014 we record
-NULL/0 and log a warning so a broken agent run can't crash the monitor.
+Everything here is defensive: a missing/garbled JSON never raises — we record
+NULL/0 and log a warning so a broken agent run can't crash the monitor. The
+status-comment hot path likewise NEVER raises (self-hosting risk R-1).
 """
 
 import json
@@ -247,6 +252,88 @@ def fmt_cost(c) -> str:
     return f"${c:.2f}"
 
 
+def fmt_duration(seconds) -> str:
+    """Format an integer second count for the agent-finish status comment (ORCH-016).
+
+    Contract (ADR-001 §8 / AC-13):
+        0..59       -> '{s}s'           (e.g. '0s', '12s', '59s')
+        60..3599    -> '{m}m {ss:02d}s' (e.g. '1m 00s', '4m 12s', '59m 59s')
+        >= 3600     -> '{h}h {mm:02d}m' (seconds dropped; e.g. '1h 00m', '2h 47m')
+
+    None / non-int / negative -> '' so the caller drops the 'Длительность:' line.
+    Pure function: no I/O, no DB.
+    """
+    try:
+        if seconds is None:
+            return ""
+        s = int(seconds)
+    except (TypeError, ValueError):
+        return ""
+    if s < 0:
+        return ""
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        m, ss = divmod(s, 60)
+        return f"{m}m {ss:02d}s"
+    h, rem = divmod(s, 3600)
+    mm = rem // 60
+    return f"{h}h {mm:02d}m"
+
+
+def get_agent_duration(task_id, agent: str) -> int | None:
+    """Last finished agent_runs duration (seconds) for (task_id, agent) — DB fallback.
+
+    ORCH-016 / ADR-001 §6: used by build_status_comment when the caller does NOT
+    pass an explicit duration_s (chiefly the analyst path, which builds its
+    comment from stage_engine where _duration_s is not in scope).
+
+    Reads the last finished row for (task_id, agent) via:
+        SELECT CAST((julianday(finished_at) - julianday(started_at)) * 86400 AS INTEGER)
+        FROM agent_runs WHERE task_id=? AND agent=?
+          AND finished_at IS NOT NULL
+        ORDER BY id DESC LIMIT 1
+
+    Returns None on any of:
+      - missing task_id / agent,
+      - no matching row (or finished_at IS NULL),
+      - computed value < 0 (clock skew),
+      - DB error (logged at debug, never re-raised). This is the hot comment
+        path — a locked / stale DB must never crash a finishing agent.
+    """
+    if not task_id or not agent:
+        return None
+    try:
+        conn = get_db()
+    except Exception as e:
+        logger.debug(f"get_agent_duration: cannot open DB for ({task_id},{agent}): {e}")
+        return None
+    try:
+        row = conn.execute(
+            "SELECT CAST((julianday(finished_at) - julianday(started_at)) * 86400 AS INTEGER) "
+            "FROM agent_runs WHERE task_id=? AND agent=? AND finished_at IS NOT NULL "
+            "ORDER BY id DESC LIMIT 1",
+            (task_id, agent),
+        ).fetchone()
+    except Exception as e:
+        logger.debug(f"get_agent_duration: query failed for ({task_id},{agent}): {e}")
+        return None
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+    if not row or row[0] is None:
+        return None
+    try:
+        secs = int(row[0])
+    except (TypeError, ValueError):
+        return None
+    if secs < 0:
+        return None
+    return secs
+
+
 # Pretty agent names for comments (mirrors STAGE_AUTHORS roles).
 AGENT_DISPLAY = {
     "analyst": "Analyst",
@@ -298,30 +385,28 @@ def usage_comment(
     work_item_id: str | None = None,
     pr_number=None,
 ) -> str:
-    """Build the per-agent finish comment, e.g.
-    '\U0001f4bb Developer \u0433\u043e\u0442\u043e\u0432 \u00b7 8.5M in (8.4M cached) / 45.8k out \u00b7 $7.29'.
+    """DEPRECATED (ORCH-016 / ADR-001 §1): thin wrapper around build_status_comment.
 
-    When repo/branch/work_item_id are supplied, the agent's artifact link(s) are
-    appended (BUG: only analyst used to link its docs). Missing artifacts are
-    silently skipped — link building never raises.
+    The historical one-line "{icon} Role готов · 8.5M in / 45.8k out · $7.29 + links"
+    format has been replaced by the unified status-comment format. This wrapper
+    is kept only so that legacy callers (notably the test suite in
+    ``tests/test_usage.py``) keep working; new code MUST call
+    ``build_status_comment(...)`` directly. There is no ``duration_s`` parameter
+    here because the old signature did not carry it.
     """
-    usage = usage or {}
-    name = AGENT_DISPLAY.get(agent, agent.capitalize())
-    icon = AGENT_ICON.get(agent, "\u2705")
-    line = (
-        f"{icon} {name} \u0433\u043e\u0442\u043e\u0432 \u00b7 "
-        f"{fmt_in(usage)} / "
-        f"{fmt_tokens(usage.get('output_tokens'))} out \u00b7 "
-        f"{fmt_cost(usage.get('cost_usd'))}"
+    return build_status_comment(
+        agent,
+        repo=repo,
+        branch=branch,
+        work_item_id=work_item_id,
+        pr_number=pr_number,
+        usage=usage,
     )
-    links = artifact_links(agent, repo, branch, work_item_id, pr_number)
-    if links:
-        line += "\n" + "\n".join(links)
-    return line
 
 
-# Per-agent artifact file under docs/work-items/{wid}/ (architect/developer use
-# special handling for ADR dirs / PR links, see artifact_links()).
+# Per-agent artifact file under docs/work-items/{wid}/ (architect/developer/
+# deployer use special handling for ADR dirs, PR links, or staging logs —
+# see artifact_links()).
 AGENT_ARTIFACT = {
     "reviewer": ("Review", "12-review.md"),
     "tester": ("Test report", "13-test-report.md"),
@@ -335,13 +420,35 @@ def artifact_links(
     branch: str | None,
     work_item_id: str | None,
     pr_number=None,
+    *,
+    stage: str | None = None,
+    worktree_root: str | None = None,
 ) -> list[str]:
-    """Markdown link(s) to the finishing agent's artifact(s) in Gitea.
+    """HTML <li><a>...</a></li> link fragments for the finishing agent's artifacts.
 
-    Uses gitea_public_url (falls back to gitea_url) for clickable links, mirroring
-    the analyst doc links. Returns [] (never raises) when there is nothing to
-    link or the required context is missing. analyst is intentionally NOT handled
-    here — its richer doc list lives in stage_engine._build_analyst_ready_comment.
+    ORCH-016 (ADR-001 §7) breaking change: this function now emits HTML anchor
+    fragments to feed straight into the <ul> of build_status_comment(), instead
+    of the legacy markdown ``[label](url)`` strings. The base URL still prefers
+    settings.gitea_public_url (falls back to gitea_url) so links remain clickable
+    from outside the deploy host, exactly like the analyst doc list.
+
+    Returned strings are individual ``<li><a href="...">label</a></li>`` items;
+    the caller wraps them in ``<ul>...</ul>``. Empty list (never raises) when
+    there is nothing to link or context is missing.
+
+    AC-8 graceful behaviour: when ``worktree_root`` is provided, a candidate
+    whose underlying file does NOT exist in the worktree is dropped silently.
+    With no worktree (unit-test / minimal context), every applicable link is
+    emitted without a file-existence probe (matches the legacy artifact_links
+    semantics; that's what existing tests in tests/test_usage.py exercise).
+
+    Per agent (ADR-001 §7, ТЗ §2.4):
+      developer  -> Branch + (open) PR
+      architect  -> ADR directory
+      reviewer   -> 12-review.md
+      tester     -> 13-test-report.md
+      deployer   -> 14-deploy-log.md (deploy) or 15-staging-log.md (deploy-staging)
+      analyst    -> NOT handled here; build_status_comment owns its richer list.
     """
     try:
         from .config import settings
@@ -351,37 +458,76 @@ def artifact_links(
         ).rstrip("/")
         if not base or not repo:
             return []
-        links: list[str] = []
+
+        items: list[str] = []
+        rel_dir = f"docs/work-items/{work_item_id}" if work_item_id else None
+
+        def _file_exists(rel_path: str) -> bool:
+            if not worktree_root:
+                return True
+            try:
+                import os as _os
+                return _os.path.isfile(_os.path.join(worktree_root, rel_path))
+            except Exception:
+                return True
+
+        def _dir_exists(rel_path: str) -> bool:
+            if not worktree_root:
+                return True
+            try:
+                import os as _os
+                return _os.path.isdir(_os.path.join(worktree_root, rel_path))
+            except Exception:
+                return True
 
         if agent == "developer":
             if branch:
-                links.append(
-                    f"\U0001f4c2 [Branch {branch}]({base}/{owner}/{repo}/src/branch/{branch})"
+                items.append(
+                    f'<li><a href="{base}/{owner}/{repo}/src/branch/{branch}">'
+                    f"Branch {branch}</a></li>"
                 )
             if pr_number:
-                links.append(
-                    f"\U0001f517 [PR #{pr_number}]({base}/{owner}/{repo}/pulls/{pr_number})"
+                items.append(
+                    f'<li><a href="{base}/{owner}/{repo}/pulls/{pr_number}">'
+                    f"PR #{pr_number}</a></li>"
                 )
-            return links
+            return items
 
         if agent == "architect":
-            if branch and work_item_id:
-                adr_dir = (
-                    f"{base}/{owner}/{repo}/src/branch/{branch}/"
-                    f"docs/work-items/{work_item_id}/06-adr"
-                )
-                links.append(f"\U0001f4d0 [ADR]({adr_dir})")
-            return links
+            if branch and rel_dir:
+                adr_rel = f"{rel_dir}/06-adr"
+                if _dir_exists(adr_rel):
+                    items.append(
+                        f'<li><a href="{base}/{owner}/{repo}/src/branch/{branch}/'
+                        f'{adr_rel}">ADR</a></li>'
+                    )
+            return items
+
+        if agent == "deployer":
+            # Stage-aware (ORCH-35 + ORCH-016 §2.4): 'deploy-staging' picks the
+            # staging log; 'deploy' (or unknown) picks the deploy log. Other
+            # deployer artifacts (smoke output etc.) are out of scope.
+            if branch and rel_dir:
+                if (stage or "").strip() == "deploy-staging":
+                    fname, label = "15-staging-log.md", "Staging log"
+                else:
+                    fname, label = "14-deploy-log.md", "Deploy log"
+                if _file_exists(f"{rel_dir}/{fname}"):
+                    items.append(
+                        f'<li><a href="{base}/{owner}/{repo}/src/branch/{branch}/'
+                        f'{rel_dir}/{fname}">{label}</a></li>'
+                    )
+            return items
 
         spec = AGENT_ARTIFACT.get(agent)
-        if spec and branch and work_item_id:
+        if spec and branch and rel_dir:
             label, fname = spec
-            href = (
-                f"{base}/{owner}/{repo}/src/branch/{branch}/"
-                f"docs/work-items/{work_item_id}/{fname}"
-            )
-            links.append(f"\U0001f4c4 [{label}]({href})")
-        return links
+            if _file_exists(f"{rel_dir}/{fname}"):
+                items.append(
+                    f'<li><a href="{base}/{owner}/{repo}/src/branch/{branch}/'
+                    f'{rel_dir}/{fname}">{label}</a></li>'
+                )
+        return items
     except Exception:
         return []
 
@@ -396,6 +542,295 @@ AGENT_ICON = {
 }
 
 
+# ---------------------------------------------------------------------------
+# ORCH-016: unified status comment for every agent (analyst..deployer)
+# ---------------------------------------------------------------------------
+
+# Per-agent one-line description used in the status comment header (ADR-001 §2).
+# Trailing periods are kept to match the literal assertions in AC-1..AC-5.
+_AGENT_DESCRIPTIONS = {
+    "analyst": (
+        "Подготовил BRD / "
+        "ТЗ / Acceptance Criteria. "
+        "Для продвижения "
+        "переведите задачу "
+        "в статус Approved. "
+        "Для отклонения — "
+        "напишите причину "
+        "комментом и "
+        "переведите в Rejected."
+    ),
+    "architect": (
+        "Завершил "
+        "архитектурную "
+        "проработку. "
+        "См. ADR ниже."
+    ),
+    "developer": (
+        "Завершил "
+        "разработку. "
+        "См. PR / branch ниже."
+    ),
+    "reviewer": (
+        "Завершил "
+        "ревью "
+        "изменений."
+    ),
+    "tester": (
+        "Завершил "
+        "прогон "
+        "тестов."
+    ),
+    "deployer": (
+        "Завершил деплой."
+    ),
+}
+
+# Analyst-specific candidate artifact list (label -> filename in docs/work-items/<wid>/).
+# Matches the legacy _build_analyst_ready_comment list 1:1 so the BUG-C
+# regression test (tests/test_analyst_comment.py) keeps passing under the
+# unified format.
+_ANALYST_CANDIDATES = [
+    ("Business request", "00-business-request.md"),
+    ("BRD", "01-brd.md"),
+    ("ТЗ (TRZ)", "02-trz.md"),
+    ("Acceptance Criteria", "03-acceptance-criteria.md"),
+    ("Test Plan", "04-test-plan.yaml"),
+    ("UI Test Cases", "04b-ui-test-cases.md"),
+]
+
+
+def _read_verdict_line(
+    agent: str, stage: str | None, worktree_root: str | None, work_item_id: str | None
+) -> str | None:
+    """Render the optional Verdict / Status line for reviewer / tester / deployer.
+
+    Sources (machine-readable YAML frontmatter, via src/frontmatter.py):
+      reviewer  -> 12-review.md  verdict:                   -> 'Verdict: <VALUE>'
+      tester    -> 13-test-report.md verdict: (or status:)  -> 'Verdict: <VALUE>'
+      deployer  -> deploy-staging -> 15-staging-log.md staging_status: -> 'Status: <VALUE>'
+                   else (deploy)  -> 14-deploy-log.md   deploy_status:  -> 'Status: <VALUE>'
+
+    Returns None (line suppressed) for analyst / architect / developer, when
+    the worktree is unknown, the work-item id is missing, the artifact file is
+    absent, or the relevant frontmatter key is not present. Never raises.
+    """
+    if agent not in ("reviewer", "tester", "deployer"):
+        return None
+    if not worktree_root or not work_item_id:
+        return None
+    try:
+        import os as _os
+        from .frontmatter import read_frontmatter_value
+        base_dir = _os.path.join(worktree_root, "docs/work-items", work_item_id)
+    except Exception:
+        return None
+
+    if agent == "reviewer":
+        v = read_frontmatter_value(_os.path.join(base_dir, "12-review.md"), "verdict")
+        return f"Verdict: {v}" if v else None
+    if agent == "tester":
+        path = _os.path.join(base_dir, "13-test-report.md")
+        v = read_frontmatter_value(path, "verdict")
+        if not v:
+            v = read_frontmatter_value(path, "status")
+        return f"Verdict: {v}" if v else None
+    # deployer
+    if (stage or "").strip() == "deploy-staging":
+        v = read_frontmatter_value(
+            _os.path.join(base_dir, "15-staging-log.md"), "staging_status"
+        )
+    else:
+        v = read_frontmatter_value(
+            _os.path.join(base_dir, "14-deploy-log.md"), "deploy_status"
+        )
+    return f"Status: {v}" if v else None
+
+
+def _analyst_doc_items(
+    repo: str, branch: str, work_item_id: str, worktree_root: str | None
+) -> list[str]:
+    """Build the analyst's <li><a>...</a></li> list (mirrors legacy behaviour).
+
+    Files absent from the worktree are skipped (graceful, as in BUG-C / PR #13).
+    """
+    if not (repo and branch and work_item_id):
+        return []
+    from .config import settings as _settings
+    owner = getattr(_settings, "gitea_owner", "admin")
+    base = (
+        getattr(_settings, "gitea_public_url", "") or getattr(_settings, "gitea_url", "")
+    ).rstrip("/")
+    if not base:
+        return []
+    rel_dir = f"docs/work-items/{work_item_id}"
+    items: list[str] = []
+    for label, fname in _ANALYST_CANDIDATES:
+        if worktree_root:
+            try:
+                import os as _os
+                if not _os.path.isfile(_os.path.join(worktree_root, rel_dir, fname)):
+                    continue
+            except Exception:
+                # On filesystem error, fall through and link the candidate anyway
+                # (best-effort) rather than blanking the whole document list.
+                pass
+        href = f"{base}/{owner}/{repo}/src/branch/{branch}/{rel_dir}/{fname}"
+        items.append(f'<li><a href="{href}">{label}</a></li>')
+    return items
+
+
+def _usage_tail(usage: dict | None) -> str | None:
+    """Render the technical token/cost tail (``<sub>...</sub>``) or None when empty.
+
+    Format (ADR-001 §3): ``<sub>{fmt_in} / {out} out · {cost}</sub>``.
+    Returns None when usage is missing entirely AND all of the relevant
+    components are zero — i.e. nothing meaningful to print.
+    """
+    if not usage:
+        return None
+    in_total = _input_total(usage)
+    try:
+        out = int(usage.get("output_tokens") or 0)
+    except (TypeError, ValueError):
+        out = 0
+    try:
+        cost = float(usage.get("cost_usd") or 0.0)
+    except (TypeError, ValueError):
+        cost = 0.0
+    if in_total == 0 and out == 0 and cost == 0.0:
+        return None
+    return f"<sub>{fmt_in(usage)} / {fmt_tokens(out)} out · {fmt_cost(cost)}</sub>"
+
+
+def build_status_comment(
+    agent: str,
+    *,
+    repo: str | None = None,
+    branch: str | None = None,
+    work_item_id: str | None = None,
+    pr_number=None,
+    stage: str | None = None,
+    usage: dict | None = None,
+    duration_s=None,
+    task_id=None,
+    worktree_root: str | None = None,
+) -> str:
+    """Build the unified per-agent finish comment (ORCH-016 / ADR-001).
+
+    Single hot path for every agent's "I just finished a stage" comment in
+    Plane. Replaces the old ``usage_comment(...)`` one-liner AND the analyst-
+    special ``stage_engine._build_analyst_ready_comment(...)`` HTML; both now
+    flow through here. Format (HTML, rendered by Plane), separated by ``<br>``::
+
+        {ICON} {RoleName} — {DESCRIPTION}
+        [Verdict|Status: VALUE]                  # reviewer/tester/deployer + FM
+        [Длительность: 4m 12s]
+        <b>Документы:</b><ul><li><a href="...">label</a></li>...</ul>
+        [<sub>8.5M in / 45.8k out · $7.29</sub>]
+
+    Arguments (all keyword-only except ``agent``):
+      agent          one of analyst|architect|developer|reviewer|tester|deployer.
+                     Unknown agents get a generic header — defensive.
+      repo/branch    repository name + feature branch. Required for artifact
+                     links; without them the Документы block is omitted.
+      work_item_id   Plane work-item id used as the docs/work-items/<id>/ slug.
+      pr_number      developer only — appended as a PR link when set.
+      stage          deployer only — 'deploy' vs 'deploy-staging' picks the
+                     log file (14- vs 15-) and the verdict frontmatter key.
+      usage          parsed token/cost dict (from parse_usage_from_text). When
+                     None or all-zero the ``<sub>`` tail is suppressed.
+      duration_s     explicit per-agent wall-clock seconds. If None and
+                     task_id is given, falls back to
+                     get_agent_duration(task_id, agent).  Negative / non-int
+                     values are treated as unknown.
+      task_id        tasks.id — required for the DB duration fallback. The
+                     verdict / artifact code paths do NOT depend on it.
+      worktree_root  path to the task's git worktree. Drives AC-8 graceful
+                     skipping of missing files AND the verdict frontmatter
+                     read. Omit (None) in unit tests where only format matters.
+
+    The function MUST NOT raise — at worst it returns a degraded one-liner
+    header, with the exception logged. Self-hosting risk R-1: a crash here
+    blinds the stakeholder for that very ORCH task.
+    """
+    try:
+        name = AGENT_DISPLAY.get(agent, (agent or "agent").capitalize())
+        icon = AGENT_ICON.get(agent, "✅")
+        description = _AGENT_DESCRIPTIONS.get(
+            agent,
+            "завершил стадию.",
+        )
+        if agent == "deployer":
+            if (stage or "").strip() == "deploy-staging":
+                description = (
+                    "Завершил "
+                    "staging-деплой."
+                )
+            elif (stage or "").strip() == "deploy":
+                description = (
+                    "Завершил "
+                    "прод-деплой."
+                )
+
+        lines: list[str] = [f"{icon} {name} — {description}"]
+
+        verdict_line = _read_verdict_line(agent, stage, worktree_root, work_item_id)
+        if verdict_line:
+            lines.append(verdict_line)
+
+        # Duration: explicit param wins; otherwise DB fallback (ADR-001 §6).
+        resolved_duration: int | None = None
+        if duration_s is not None:
+            try:
+                if int(duration_s) >= 0:
+                    resolved_duration = int(duration_s)
+            except (TypeError, ValueError):
+                resolved_duration = None
+        if resolved_duration is None and task_id is not None:
+            resolved_duration = get_agent_duration(task_id, agent)
+        d_text = fmt_duration(resolved_duration)
+        if d_text:
+            lines.append(
+                "Длительность: "
+                f"{d_text}"
+            )
+
+        # Documents block (analyst gets its full BRD/TRZ/AC/Test Plan list).
+        if agent == "analyst":
+            doc_items = _analyst_doc_items(
+                repo or "", branch or "", work_item_id or "", worktree_root
+            )
+        else:
+            doc_items = artifact_links(
+                agent, repo, branch, work_item_id, pr_number,
+                stage=stage, worktree_root=worktree_root,
+            )
+        if doc_items:
+            lines.append(
+                "<b>Документы:</b><ul>"
+                + "".join(doc_items)
+                + "</ul>"
+            )
+
+        tail = _usage_tail(usage)
+        if tail:
+            lines.append(tail)
+
+        return "<br>".join(lines)
+    except Exception as e:  # defensive — R-1 fallback
+        logger.exception(f"build_status_comment failed for agent={agent}: {e}")
+        try:
+            name = AGENT_DISPLAY.get(agent, str(agent).capitalize())
+            icon = AGENT_ICON.get(agent, "✅")
+            return (
+                f"{icon} {name} "
+                "готов"
+            )
+        except Exception:
+            return "✅ Agent готов"
+
+
 def task_usage_summary(task_id: int) -> dict:
     """Aggregate agent_runs usage for a task.
 
@@ -441,14 +876,14 @@ def task_summary_comment(task_id: int) -> str:
     s = task_usage_summary(task_id)
     cached = s.get("total_cached", 0)
     head_in = (
-        f"{fmt_tokens(s['total_in'])} \u0432\u0445\u043e\u0434 ({fmt_tokens(cached)} cached)"
+        f"{fmt_tokens(s['total_in'])} вход ({fmt_tokens(cached)} cached)"
         if cached > 0
-        else f"{fmt_tokens(s['total_in'])} \u0432\u0445\u043e\u0434"
+        else f"{fmt_tokens(s['total_in'])} вход"
     )
     lines = [
-        f"\U0001f4ca \u0418\u0442\u043e\u0433\u043e \u043f\u043e \u0437\u0430\u0434\u0430\u0447\u0435: "
+        f"\U0001f4ca Итого по задаче: "
         f"{head_in} / "
-        f"{fmt_tokens(s['total_out'])} \u0432\u044b\u0445\u043e\u0434 \u00b7 "
+        f"{fmt_tokens(s['total_out'])} выход · "
         f"{fmt_cost(s['total_cost'])}"
     ]
     for agent, ti, tc, to, cost in s["per_agent"]:
@@ -459,6 +894,6 @@ def task_summary_comment(task_id: int) -> str:
             else f"{fmt_tokens(ti)} in"
         )
         lines.append(
-            f"\u2022 {name}: {in_str} / {fmt_tokens(to)} out \u00b7 {fmt_cost(cost)}"
+            f"• {name}: {in_str} / {fmt_tokens(to)} out · {fmt_cost(cost)}"
         )
     return "\n".join(lines)

src/webhooks/plane.py

@@ -137,7 +137,7 @@ async def handle_issue_updated(data: dict, project_id: str = ""):
     Any other status (Needs Input, In Review, Blocked, Done, board stages, etc.)
     is ignored here — those are statuses the orchestrator itself sets.
     """
-    from ..plane_sync import PLANE_STATES
+    from ..plane_sync import get_project_states
 
     plane_id = str(data.get("id") or "")
     new_state = _state_id(data)
@@ -145,11 +145,15 @@ async def handle_issue_updated(data: dict, project_id: str = ""):
         logger.info("issue updated without id/state, ignoring")
         return
 
-    if new_state == PLANE_STATES["in_progress"]:
+    # ORCH-10: resolve expected state UUIDs per the incoming issue's project so
+    # both enduro (b873d9eb) and orchestrator (e331bfb3) In Progress trigger the
+    # pipeline. Using PLANE_STATES["in_progress"] here was the root-cause blocker.
+    proj_states = get_project_states(project_id)
+    if new_state == proj_states["in_progress"]:
         await handle_status_start(data, project_id)
-    elif new_state == PLANE_STATES["approved"]:
+    elif new_state == proj_states["approved"]:
         await handle_verdict(data, project_id, approved=True)
-    elif new_state == PLANE_STATES["rejected"]:
+    elif new_state == proj_states["rejected"]:
         await handle_verdict(data, project_id, approved=False)
     else:
         logger.info(f"issue {plane_id} updated to state {new_state[:8]}..., no pipeline action")
@@ -422,7 +426,7 @@ async def start_pipeline(data: dict, project_id: str = ""):
     if errors:
         # QG-0 failed
         error_text = "\u26a0\ufe0f QG-0 failed:\n" + "\n".join(f"\u2022 {e}" for e in errors)
-        from ..plane_sync import PLANE_BASE, PLANE_HEADERS, WORKSPACE, PLANE_STATES
+        from ..plane_sync import PLANE_BASE, PLANE_HEADERS, WORKSPACE, get_project_states
         import httpx as _httpx
         # Post comment (ORCH-6: route to the issue's own project)
         url = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{plane_project_id}/issues/{plane_id}/comments/"
@@ -431,11 +435,12 @@ async def start_pipeline(data: dict, project_id: str = ""):
                        json={"comment_html": f"<p>{error_text}</p>"}, timeout=10)
         except Exception:
             pass
-        # Set blocked
+        # Set blocked — ORCH-10: resolve per-project UUID.
         url2 = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{plane_project_id}/issues/{plane_id}/"
         try:
+            _blocked = get_project_states(plane_project_id)["blocked"]
             _httpx.patch(url2, headers=PLANE_HEADERS,
-                        json={"state": PLANE_STATES["blocked"]}, timeout=10)
+                        json={"state": _blocked}, timeout=10)
         except Exception:
             pass
         logger.info(f"QG-0 failed for {plane_id}: {errors}")

tests/test_analysis_approve_flow_links.py

@@ -0,0 +1,100 @@
+"""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

tests/test_analyst_comment_regression.py

@@ -0,0 +1,126 @@
+"""ORCH-016 / TC-11 + AC-6: analyst status-comment regression.
+
+Status-only verdict model from PR #12 / #13 must be preserved exactly:
+  - the analyst comment still asks the stakeholder for the **Approved** status,
+  - it still rejects the obsolete ``:approved:`` reaction and "move to In Progress",
+  - it still links the documents that actually exist (BRD / TRZ / AC / Test Plan,
+    skipping anything not on disk),
+  - it now also carries the new «Длительность: …» line when an agent_runs row
+    exists for (task_id, analyst).
+"""
+
+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_orch016_analyst_regression.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+
+
+@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 _seed_task_and_analyst_run(task_id=42, agent="analyst", duration_seconds=180):
+    """Insert a task and a finished analyst run with a measurable duration."""
+    conn = get_db()
+    conn.execute(
+        "INSERT INTO tasks (id, repo, branch, stage, work_item_id) "
+        "VALUES (?, 'orchestrator', 'feature/ORCH-016', 'analysis', 'ORCH-016')",
+        (task_id,),
+    )
+    conn.execute(
+        "INSERT INTO agent_runs (task_id, agent, started_at, finished_at) "
+        "VALUES (?, ?, datetime('now', ?), datetime('now'))",
+        (task_id, agent, f"-{duration_seconds} seconds"),
+    )
+    conn.commit()
+    conn.close()
+
+
+def test_tc11_analyst_text_preserved_with_links(monkeypatch, tmp_path):
+    """Analyst comment must keep all existing assertions from PR #12 / #13."""
+    from src import stage_engine as SE
+    from src.config import settings
+
+    wt = tmp_path / "wt"
+    docs = wt / "docs" / "work-items" / "ET-011"
+    docs.mkdir(parents=True)
+    for fname in (
+        "00-business-request.md", "01-brd.md", "02-trz.md",
+        "03-acceptance-criteria.md", "04-test-plan.yaml",
+    ):
+        (docs / fname).write_text("x")
+    # 04b-ui-test-cases.md intentionally absent
+
+    monkeypatch.setattr(SE, "get_worktree_path", lambda repo, branch: str(wt))
+    monkeypatch.setattr(settings, "gitea_url", "http://localhost:3000", raising=False)
+    monkeypatch.setattr(
+        settings, "gitea_public_url", "https://git.mva154.duckdns.org", raising=False
+    )
+    monkeypatch.setattr(settings, "gitea_owner", "admin", raising=False)
+
+    html = SE._build_analyst_ready_comment(
+        "enduro-trails", "ET-011", "feature/ET-011-gpx-upload-feature",
+    )
+
+    # Status-only verdict text (PR #12 contract).
+    assert "Approved" in html
+    assert "Rejected" in html
+    assert ":approved:" not in html
+    assert "In Progress" not in html
+
+    # Clickable links via public URL only.
+    assert "<a href=" in html
+    base = ("https://git.mva154.duckdns.org/admin/enduro-trails/src/branch/"
+            "feature/ET-011-gpx-upload-feature/docs/work-items/ET-011/")
+    assert base + "01-brd.md" in html
+    assert base + "04-test-plan.yaml" in html
+
+    # Missing file NOT linked.
+    assert "04b-ui-test-cases.md" not in html
+
+    # Internal URL must NOT leak into clickable links.
+    assert "localhost:3000" not in html
+
+
+def test_tc11_analyst_includes_duration_when_db_has_run(monkeypatch, tmp_path):
+    """When an agent_runs row exists for (task_id, analyst), the comment carries
+    a «Длительность:» line populated via the DB fallback (AC-14)."""
+    from src import stage_engine as SE
+    from src.config import settings
+
+    wt = tmp_path / "wt"
+    (wt / "docs" / "work-items" / "ORCH-016").mkdir(parents=True)
+    (wt / "docs" / "work-items" / "ORCH-016" / "01-brd.md").write_text("x")
+
+    _seed_task_and_analyst_run(task_id=42, agent="analyst", duration_seconds=125)
+
+    monkeypatch.setattr(SE, "get_worktree_path", lambda repo, branch: str(wt))
+    monkeypatch.setattr(settings, "gitea_url", "http://localhost:3000", raising=False)
+    monkeypatch.setattr(settings, "gitea_public_url", "", raising=False)
+    monkeypatch.setattr(settings, "gitea_owner", "admin", raising=False)
+
+    html = SE._build_analyst_ready_comment(
+        "orchestrator", "ORCH-016", "feature/ORCH-016", task_id=42,
+    )
+
+    # Two-digit seconds rounding may shave ~1s — accept either neighbour.
+    assert any(
+        s in html
+        for s in ("Длительность: 2m 05s", "Длительность: 2m 04s", "Длительность: 2m 06s")
+    ), html

tests/test_analyst_status_only_regression.py

@@ -0,0 +1,135 @@
+"""ORCH-016 / TC-16 + AC-6: analyst status-only regression.
+
+Status-only verdict model (PR #12 / #13):
+  - analyst finishes its run -> Plane state becomes In Review,
+  - ONE status comment is posted asking the stakeholder to flip the status to
+    Approved (or write a reason and switch to Rejected),
+  - NO auto-advance happens — the next stage waits for human approval.
+
+The ORCH-016 PR refactors the comment text into the unified status-comment
+helper. This regression test guards against:
+  (a) the analyst path silently auto-advancing,
+  (b) the analyst comment losing the «Approved» / «Rejected» instruction text,
+  (c) the comment switching authorship away from the analyst bot.
+
+We exercise `_handle_analysis_approved_flow` directly (the launcher path).
+"""
+
+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_orch016_analyst_so.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+
+
+REPO = "enduro-trails"
+BRANCH = "feature/ET-016-x"
+WID = "ET-016"
+
+
+@pytest.fixture(autouse=True)
+def setup_db(monkeypatch, tmp_path):
+    monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+    init_db()
+    conn = get_db()
+    conn.execute(
+        "INSERT INTO tasks (id, repo, branch, stage, work_item_id) "
+        "VALUES (1, ?, ?, 'analysis', ?)",
+        (REPO, BRANCH, WID),
+    )
+    conn.commit()
+    conn.close()
+    yield
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+
+
+@pytest.fixture
+def fake_worktree(monkeypatch, tmp_path):
+    base = tmp_path / "wt"
+    docs = base / "docs" / "work-items" / WID
+    docs.mkdir(parents=True)
+    # All analyst artifacts present -> "files_check" returns True.
+    for f in ("01-brd.md", "02-trz.md", "03-acceptance-criteria.md",
+              "04-test-plan.yaml"):
+        (docs / f).write_text("x")
+    monkeypatch.setattr("src.git_worktree.get_worktree_path", lambda r, b: str(base))
+    monkeypatch.setattr("src.stage_engine.get_worktree_path", lambda r, b: str(base))
+    monkeypatch.setattr("src.qg.checks.get_worktree_path", lambda r, b: str(base))
+    return base
+
+
+@pytest.fixture
+def collect_calls(monkeypatch):
+    calls = {"in_review": 0, "advance": 0, "comments": [], "enqueued": []}
+
+    monkeypatch.setattr(
+        "src.stage_engine.set_issue_in_review",
+        lambda wid: calls.__setitem__("in_review", calls["in_review"] + 1),
+    )
+    monkeypatch.setattr(
+        "src.stage_engine.notify_approve_requested", lambda tid: None
+    )
+
+    def _add_comment(wid, body, author=None, **kw):
+        calls["comments"].append({"wid": wid, "body": body, "author": author})
+
+    monkeypatch.setattr("src.stage_engine.plane_add_comment", _add_comment)
+
+    # advance_stage isn't directly hit; if anything calls update_task_stage to
+    # 'architecture', we'd see it here.
+    def _update_task_stage(task_id, stage):
+        calls["advance"] += 1
+
+    monkeypatch.setattr("src.stage_engine.update_task_stage", _update_task_stage)
+
+    def _enqueue(*a, **k):
+        calls["enqueued"].append((a, k))
+        return 1
+
+    monkeypatch.setattr("src.stage_engine.enqueue_job", _enqueue)
+    return calls
+
+
+def test_tc16_analyst_goes_to_in_review_no_advance(fake_worktree, collect_calls):
+    """When the analyst finishes with complete artifacts, the task goes to In
+    Review and NO advance/enqueue happens — the human approves via Plane status.
+    """
+    from src.stage_engine import _handle_analysis_approved_flow, AdvanceResult
+
+    result = AdvanceResult(from_stage="analysis")
+    _handle_analysis_approved_flow(
+        task_id=1, current_stage="analysis", repo=REPO, work_item_id=WID,
+        branch=BRANCH, agent="analyst", result=result,
+    )
+
+    # In Review state requested in Plane.
+    assert collect_calls["in_review"] == 1, collect_calls
+    # NO stage-machine advance.
+    assert collect_calls["advance"] == 0, collect_calls
+    # NO new job enqueued by the analyst path.
+    assert collect_calls["enqueued"] == [], collect_calls
+
+    # Exactly one comment posted, authored by analyst, with required text bits.
+    assert len(collect_calls["comments"]) == 1, collect_calls["comments"]
+    c = collect_calls["comments"][0]
+    assert c["wid"] == WID
+    assert c["author"] == "analyst"
+    body = c["body"]
+    assert "Approved" in body
+    assert "Rejected" in body
+    assert ":approved:" not in body
+    assert "In Progress" not in body
+    # AC-6 +: the new unified format adds a Длительность line (DB fallback).
+    # No agent_runs row exists in this test, so the line should be ABSENT.
+    assert "Длительность" not in body

tests/test_fmt_duration.py

@@ -0,0 +1,68 @@
+"""ORCH-016 / AC-13 + AC-22: fmt_duration formatting contract.
+
+Pure-function tests for the duration formatter used by build_status_comment.
+No DB, no I/O — just the table in ADR-001 §8 / AC-13.
+"""
+
+import os
+
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+
+from src.usage import fmt_duration  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# TC-21: table-driven happy path (AC-13)
+# ---------------------------------------------------------------------------
+def test_fmt_duration_boundary_table():
+    cases = [
+        (0,     "0s"),
+        (12,    "12s"),
+        (59,    "59s"),
+        (60,    "1m 00s"),
+        (252,   "4m 12s"),
+        (3599,  "59m 59s"),
+        (3600,  "1h 00m"),
+        (3780,  "1h 03m"),
+        (10020, "2h 47m"),
+    ]
+    for seconds, expected in cases:
+        assert fmt_duration(seconds) == expected, (
+            f"fmt_duration({seconds}) -> {fmt_duration(seconds)!r}; expected {expected!r}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# TC-22: None / negative -> empty string (caller drops the line) (AC-13)
+# ---------------------------------------------------------------------------
+def test_fmt_duration_none_returns_empty():
+    assert fmt_duration(None) == ""
+
+
+def test_fmt_duration_negative_returns_empty():
+    assert fmt_duration(-1) == ""
+    assert fmt_duration(-3600) == ""
+
+
+def test_fmt_duration_garbage_returns_empty():
+    # Non-coercible input must not raise (defensive).
+    assert fmt_duration("abc") == ""
+    assert fmt_duration([1, 2]) == ""
+
+
+def test_fmt_duration_float_seconds_truncated():
+    # int(12.9) == 12 — integer truncation, not rounding.
+    assert fmt_duration(12.9) == "12s"
+    assert fmt_duration(61.4) == "1m 01s"
+
+
+# ---------------------------------------------------------------------------
+# Caller contract: empty string => the 'Длительность:' line is NOT printed.
+# build_status_comment is unit-tested in test_status_comment_format; here we
+# just sanity-check the helper used to gate that decision.
+# ---------------------------------------------------------------------------
+def test_empty_string_is_falsy():
+    assert not fmt_duration(None)
+    assert not fmt_duration(-5)
+    assert fmt_duration(0)  # "0s" IS truthy: AC-13 wants the line printed

tests/test_m6_sequence.py

@@ -34,6 +34,27 @@ import src.plane_sync as plane_sync  # noqa: E402
 ORCH_PLANE_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
 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)
 
 
@@ -48,6 +69,10 @@ def setup(monkeypatch):
 
     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 = (
         f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",'
         f' "work_item_prefix": "ET", "name": "enduro-trails"}},'
@@ -60,6 +85,7 @@ def setup(monkeypatch):
     yield
 
     reload_projects()
+    plane_sync.reload_project_states()
     if os.path.exists(_test_db):
         os.unlink(_test_db)
 
@@ -103,10 +129,9 @@ def test_fetch_sequence_id_missing_field_returns_none():
 # ---------------------------------------------------------------------------
 
 # Feature 1: pipeline starts on a status change to In Progress, not on creation.
-_IN_PROGRESS = "b873d9eb-993c-48cd-97ac-99a9b1623967"
-
-
+# ORCH-39: in_progress UUID is project-specific; derive it from the project.
 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(
         "/webhook/plane",
         json={
@@ -117,7 +142,7 @@ def _post(plane_id, plane_project_id=ORCH_PLANE_ID, name="A valid work item titl
                 "name": name,
                 "description_stripped": "This is a sufficiently long description.",
                 "project": plane_project_id,
-                "state": {"id": _IN_PROGRESS, "name": "In Progress", "group": "started"},
+                "state": {"id": in_progress, "name": "In Progress", "group": "started"},
             },
         },
     )

tests/test_notify_approve_links.py

@@ -0,0 +1,284 @@
+"""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"]

tests/test_notify_done_regression.py

@@ -0,0 +1,79 @@
+"""ORCH-016 / TC-18 + AC-7: notify_done / set_issue_done not regressed.
+
+The final deploy -> done transition still posts the «✅ Task completed!»
+comment under the deployer bot, alongside the new ORCH-016 status comment
+the deployer publishes when it finishes the stage. The two comments are
+independent — the status comment doesn't replace `notify_done`.
+"""
+
+import os
+
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+
+from src import plane_sync as PS  # noqa: E402
+
+
+def test_notify_done_constants_unchanged():
+    # Emoji + message body — pinned to lock the contract.
+    assert PS.EMOJI_DONE == "✅"
+
+
+def test_notify_done_posts_completed_comment(monkeypatch):
+    """plane_sync.notify_done still posts the ✅ Task completed! comment
+    authored by the deployer."""
+    captured = {}
+
+    def _spy_update(work_item_id, state, project_id=None):
+        captured["update"] = (work_item_id, state, project_id)
+
+    def _spy_add(work_item_id, body, project_id=None, author=None, **kw):
+        captured.setdefault("comments", []).append(
+            {"wid": work_item_id, "body": body, "author": author}
+        )
+
+    monkeypatch.setattr(PS, "update_issue_state", _spy_update)
+    monkeypatch.setattr(PS, "add_comment", _spy_add)
+    monkeypatch.setattr(PS, "_resolve_project_id", lambda wid, pid=None: "p-1")
+
+    PS.notify_done("ET-016")
+
+    assert captured["update"] == ("ET-016", "done", "p-1")
+    assert len(captured["comments"]) == 1
+    c = captured["comments"][0]
+    assert c["wid"] == "ET-016"
+    assert c["author"] == "deployer"
+    # Body untouched: emoji + canonical Russian/English copy.
+    assert "✅" in c["body"]
+    assert "Task completed" in c["body"]
+
+
+def test_set_issue_done_still_exported():
+    """set_issue_done must remain importable from plane_sync — stage_engine
+    line ~269 invokes it on deploy->done. ORCH-016 must not remove or rename it.
+    """
+    assert callable(getattr(PS, "set_issue_done", None))
+    # And stage_engine still imports it at the module level (regression: ORCH-016
+    # touches stage_engine to wire the new analyst comment helper).
+    from src import stage_engine as SE
+    assert getattr(SE, "set_issue_done", None) is PS.set_issue_done
+
+
+def test_orch016_does_not_steal_done_signal(monkeypatch):
+    """build_status_comment is just a comment — it must NOT call set_issue_done
+    or notify_done as a side effect (that's stage_engine's job)."""
+    from src import usage as U
+    called = {"done": 0, "in_review": 0}
+
+    def _fail(*a, **k):
+        called["done"] += 1
+
+    monkeypatch.setattr(PS, "set_issue_done", _fail)
+    monkeypatch.setattr(PS, "notify_done", _fail)
+
+    html = U.build_status_comment(
+        "deployer", repo="enduro-trails", branch="b", work_item_id="ET-016",
+        stage="deploy", duration_s=12,
+    )
+    assert "\U0001f680 Deployer" in html
+    assert called["done"] == 0

tests/test_orch10_states.py

@@ -0,0 +1,462 @@
+"""ORCH-10: per-project Plane state resolution tests.
+
+Verifies:
+  1. get_project_states(ET_PROJECT_ID)  -> enduro-trails UUIDs (backward compat).
+  2. get_project_states(ORCH_PROJECT_ID) -> orchestrator UUIDs.
+  3. get_project_states falls back to _DEFAULT_STATES when the Plane API fails.
+  4. _STATES_CACHE is populated after a successful call and reload_project_states
+     evicts it (per-project and full flush).
+  5. stage_to_state() resolves per-project UUIDs for both projects.
+  6. Webhook handle_issue_updated recognises In Progress for BOTH projects
+     (ORCH-10 critical path: e331bfb3 for ORCH, b873d9eb for ET -> pipeline start).
+  7. Webhook handle_issue_updated recognises Approved/Rejected per project.
+"""
+
+import os
+import sys
+import tempfile
+from unittest.mock import patch, MagicMock, AsyncMock
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Minimal env so src/config.py can import without a real .env file.
+# ---------------------------------------------------------------------------
+os.environ.setdefault("ORCH_PLANE_API_URL", "http://plane.local")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_WORKSPACE_SLUG", "test-ws")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_WEBHOOK_SECRET", "")
+os.environ.setdefault("ORCH_GITEA_WEBHOOK_SECRET", "")
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orch10_states.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+# ---------------------------------------------------------------------------
+# Known UUIDs from the ТЗ (source of truth).
+# ---------------------------------------------------------------------------
+ET_PROJECT_ID   = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
+ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
+
+ET_STATES = {
+    "backlog":      "113b24f6-cce8-4be9-9a22-a359b9cf0122",
+    "todo":         "2c7d3df3-9eb9-419b-92b7-d7d560bcdd10",
+    "in_progress":  "b873d9eb-993c-48cd-97ac-99a9b1623967",
+    "architecture": "3020bbb7-6122-4663-930c-0315ba8dfa3d",
+    "development":  "9920609b-f140-4e46-ab95-89acda8412c8",
+    "review":       "ba0d802c-5218-41d4-ab43-978b0ea123ed",
+    "testing":      "7855d807-b1bf-42ef-8dae-6cde0df92d02",
+    "approved":     "a519a341-dada-4a91-8910-7604f82b79c5",
+    "rejected":     "ba958f3c-5db5-461d-8f82-89425e413b97",
+    "done":         "381a2833-3c4e-4be5-bd0f-be84cb946ad8",
+    "cancelled":    "b1cae7f9-961d-4889-a179-f3acea697d17",
+    "needs_input":  "babf08a3-ff4d-41f3-a821-5491aa29a8ac",
+    "in_review":    "38fb1f64-aa1e-48a3-92e0-0b109679046b",
+    "blocked":      "6c4543f9-ac47-4ef7-ae0f-070020dc9920",
+}
+
+ORCH_STATES = {
+    "backlog":      "2d5d42ff-e94d-4209-a664-8020c28c2a95",
+    "todo":         "b5d3f512-4870-460f-bf6b-4ea560f00a6f",
+    "in_progress":  "e331bfb3-e17e-4699-ba48-4abb89c21b7b",
+    "architecture": "795cc32f-5f5a-4244-be7b-9acffc92c7c0",
+    "development":  "f5ed4705-5029-470d-89a9-54c3f0d211ee",
+    "review":       "2026f3d9-0f43-4054-ab5f-3f9bae3308b8",
+    "testing":      "81c5cd78-2993-4f2c-9e8c-2f52db3e5623",
+    "approved":     "63f2c8fe-dcda-4ace-952f-dd88bd0118ff",
+    "rejected":     "4c769e90-bf80-4a52-b97a-e1c84904bfc3",
+    "done":         "3738cd3c-7610-4907-ba5e-26b9a248d9c0",
+    "cancelled":    "59d1d210-8e3a-4a83-930a-cbc5dbf6ad85",
+    "needs_input":  "99978b3f-72fe-46e3-8b9b-25ba02899fa0",
+    "in_review":    "c52e99b9-31ae-4b31-be3f-9773eea7a747",
+    "blocked":      "505f01a6-a12f-4121-aaa7-9c5dd009acc4",
+}
+
+
+def _make_states_response(states_dict: dict) -> dict:
+    """Build a fake Plane GET /states/ response."""
+    name_map = {v: k for k, v in {
+        "backlog":      "Backlog",
+        "todo":         "Todo",
+        "in_progress":  "In Progress",
+        "architecture": "Architecture",
+        "development":  "Development",
+        "review":       "Review",
+        "testing":      "Testing",
+        "approved":     "Approved",
+        "rejected":     "Rejected",
+        "done":         "Done",
+        "cancelled":    "Cancelled",
+        "needs_input":  "Needs Input",
+        "in_review":    "In Review",
+        "blocked":      "Blocked",
+    }.items()}
+    logical_to_plane = {
+        "backlog":      "Backlog",
+        "todo":         "Todo",
+        "in_progress":  "In Progress",
+        "architecture": "Architecture",
+        "development":  "Development",
+        "review":       "Review",
+        "testing":      "Testing",
+        "approved":     "Approved",
+        "rejected":     "Rejected",
+        "done":         "Done",
+        "cancelled":    "Cancelled",
+        "needs_input":  "Needs Input",
+        "in_review":    "In Review",
+        "blocked":      "Blocked",
+    }
+    results = [
+        {"id": uid, "name": logical_to_plane[key]}
+        for key, uid in states_dict.items()
+        if key in logical_to_plane
+    ]
+    return {"results": results}
+
+
+# ---------------------------------------------------------------------------
+# Helpers to build fake httpx responses.
+# ---------------------------------------------------------------------------
+
+def _fake_response(data: dict, status: int = 200):
+    m = MagicMock()
+    m.status_code = status
+    m.json.return_value = data
+    if status >= 400:
+        from httpx import HTTPStatusError, Request, Response
+        m.raise_for_status.side_effect = HTTPStatusError(
+            "error", request=MagicMock(), response=MagicMock()
+        )
+    else:
+        m.raise_for_status.return_value = None
+    return m
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def reset_states_cache():
+    """Ensure the states cache is empty before each test."""
+    import src.plane_sync as ps
+    ps.reload_project_states()
+    yield
+    ps.reload_project_states()
+
+
+# ---------------------------------------------------------------------------
+# 1 & 2. get_project_states returns correct UUIDs per project
+# ---------------------------------------------------------------------------
+
+def test_get_project_states_enduro():
+    """ET project -> enduro-trails UUIDs."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        states = ps.get_project_states(ET_PROJECT_ID)
+
+    for key, expected_uuid in ET_STATES.items():
+        assert states[key] == expected_uuid, (
+            f"ET state '{key}': expected {expected_uuid}, got {states.get(key)}"
+        )
+
+
+def test_get_project_states_orchestrator():
+    """ORCH project -> orchestrator UUIDs."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ORCH_STATES))
+        states = ps.get_project_states(ORCH_PROJECT_ID)
+
+    for key, expected_uuid in ORCH_STATES.items():
+        assert states[key] == expected_uuid, (
+            f"ORCH state '{key}': expected {expected_uuid}, got {states.get(key)}"
+        )
+
+
+def test_get_project_states_et_in_progress_uuid():
+    """ET in_progress == b873d9eb (exact UUID from ТЗ)."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        states = ps.get_project_states(ET_PROJECT_ID)
+    assert states["in_progress"] == "b873d9eb-993c-48cd-97ac-99a9b1623967"
+
+
+def test_get_project_states_orch_in_progress_uuid():
+    """ORCH in_progress == e331bfb3 (exact UUID from ТЗ) — the ORCH-10 blocker."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ORCH_STATES))
+        states = ps.get_project_states(ORCH_PROJECT_ID)
+    assert states["in_progress"] == "e331bfb3-e17e-4699-ba48-4abb89c21b7b"
+
+
+# ---------------------------------------------------------------------------
+# 3. Fallback to _DEFAULT_STATES when API fails
+# ---------------------------------------------------------------------------
+
+def test_get_project_states_api_error_fallback():
+    """Network failure -> returns _DEFAULT_STATES (ET values)."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get", side_effect=Exception("network error")):
+        states = ps.get_project_states(ORCH_PROJECT_ID)
+    # Should return _DEFAULT_STATES (ET values) as fallback.
+    assert states is ps._DEFAULT_STATES
+
+
+def test_get_project_states_non_200_fallback():
+    """Non-2xx response -> returns _DEFAULT_STATES."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response({}, status=500)
+        states = ps.get_project_states(ORCH_PROJECT_ID)
+    assert states is ps._DEFAULT_STATES
+
+
+def test_get_project_states_empty_response_fallback():
+    """Empty results list -> returns _DEFAULT_STATES."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response({"results": []})
+        states = ps.get_project_states(ORCH_PROJECT_ID)
+    assert states is ps._DEFAULT_STATES
+
+
+def test_get_project_states_none_project_id_fallback():
+    """None project_id -> _DEFAULT_STATES immediately (no API call)."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        states = ps.get_project_states(None)
+    mock_get.assert_not_called()
+    assert states is ps._DEFAULT_STATES
+
+
+# ---------------------------------------------------------------------------
+# 4. Caching & reload_project_states
+# ---------------------------------------------------------------------------
+
+def test_get_project_states_caches_result():
+    """Second call returns cached result without hitting the API again."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        _ = ps.get_project_states(ET_PROJECT_ID)
+        _ = ps.get_project_states(ET_PROJECT_ID)
+    assert mock_get.call_count == 1
+
+
+def test_reload_project_states_per_project():
+    """reload_project_states(project_id) evicts only that project."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        ps.get_project_states(ET_PROJECT_ID)
+        assert ET_PROJECT_ID in ps._STATES_CACHE
+
+    ps.reload_project_states(ET_PROJECT_ID)
+    assert ET_PROJECT_ID not in ps._STATES_CACHE
+
+
+def test_reload_project_states_full_flush():
+    """reload_project_states() with no args clears entire cache."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        ps.get_project_states(ET_PROJECT_ID)
+    ps.reload_project_states()
+    assert ps._STATES_CACHE == {}
+
+
+# ---------------------------------------------------------------------------
+# 5. stage_to_state() resolves per-project
+# ---------------------------------------------------------------------------
+
+def test_stage_to_state_et_analysis():
+    """ET analysis -> in_progress UUID b873d9eb."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        uid = ps.stage_to_state("analysis", ET_PROJECT_ID)
+    assert uid == "b873d9eb-993c-48cd-97ac-99a9b1623967"
+
+
+def test_stage_to_state_orch_analysis():
+    """ORCH analysis -> in_progress UUID e331bfb3."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ORCH_STATES))
+        uid = ps.stage_to_state("analysis", ORCH_PROJECT_ID)
+    assert uid == "e331bfb3-e17e-4699-ba48-4abb89c21b7b"
+
+
+def test_stage_to_state_unknown_stage():
+    """Unknown stage -> None."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ET_STATES))
+        uid = ps.stage_to_state("nonexistent_stage", ET_PROJECT_ID)
+    assert uid is None
+
+
+def test_stage_to_state_orch_done():
+    """ORCH done -> 3738cd3c."""
+    import src.plane_sync as ps
+    with patch("src.plane_sync.httpx.get") as mock_get:
+        mock_get.return_value = _fake_response(_make_states_response(ORCH_STATES))
+        uid = ps.stage_to_state("done", ORCH_PROJECT_ID)
+    assert uid == "3738cd3c-7610-4907-ba5e-26b9a248d9c0"
+
+
+# ---------------------------------------------------------------------------
+# 6 & 7. Webhook handle_issue_updated — ORCH-10 critical path
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_webhook_in_progress_et_starts_pipeline():
+    """ET In Progress (b873d9eb) -> handle_status_start called."""
+    from src.webhooks.plane import handle_issue_updated
+    import src.plane_sync as ps
+
+    et_states_resp = _make_states_response(ET_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(et_states_resp)
+        data = {
+            "id": "et-issue-uuid",
+            "state": {"id": "b873d9eb-993c-48cd-97ac-99a9b1623967", "name": "In Progress"},
+        }
+        await handle_issue_updated(data, ET_PROJECT_ID)
+
+    mock_start.assert_called_once()
+    mock_verdict.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_webhook_in_progress_orch_starts_pipeline():
+    """ORCH In Progress (e331bfb3) -> handle_status_start called.
+
+    This is the ORCH-10 blocker: previously the webhook compared against the
+    hardcoded ET UUID (b873d9eb) and the ORCH UUID (e331bfb3) was silently
+    ignored — the pipeline never started for ORCH tasks.
+    """
+    from src.webhooks.plane import handle_issue_updated
+    import src.plane_sync as ps
+
+    orch_states_resp = _make_states_response(ORCH_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(orch_states_resp)
+        data = {
+            "id": "orch-issue-uuid",
+            "state": {"id": "e331bfb3-e17e-4699-ba48-4abb89c21b7b", "name": "In Progress"},
+        }
+        await handle_issue_updated(data, ORCH_PROJECT_ID)
+
+    mock_start.assert_called_once()
+    mock_verdict.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_webhook_approved_orch():
+    """ORCH Approved (63f2c8fe) -> handle_verdict(approved=True)."""
+    from src.webhooks.plane import handle_issue_updated
+    orch_states_resp = _make_states_response(ORCH_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(orch_states_resp)
+        data = {
+            "id": "orch-issue-uuid",
+            "state": {"id": "63f2c8fe-dcda-4ace-952f-dd88bd0118ff", "name": "Approved"},
+        }
+        await handle_issue_updated(data, ORCH_PROJECT_ID)
+
+    mock_verdict.assert_called_once_with(data, ORCH_PROJECT_ID, approved=True)
+    mock_start.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_webhook_rejected_orch():
+    """ORCH Rejected (4c769e90) -> handle_verdict(approved=False)."""
+    from src.webhooks.plane import handle_issue_updated
+    orch_states_resp = _make_states_response(ORCH_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(orch_states_resp)
+        data = {
+            "id": "orch-issue-uuid",
+            "state": {"id": "4c769e90-bf80-4a52-b97a-e1c84904bfc3", "name": "Rejected"},
+        }
+        await handle_issue_updated(data, ORCH_PROJECT_ID)
+
+    mock_verdict.assert_called_once_with(data, ORCH_PROJECT_ID, approved=False)
+    mock_start.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_webhook_other_state_no_action():
+    """A non-trigger state (e.g. 'Needs Input') -> no pipeline action."""
+    from src.webhooks.plane import handle_issue_updated
+    orch_states_resp = _make_states_response(ORCH_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(orch_states_resp)
+        data = {
+            "id": "orch-issue-uuid",
+            "state": {"id": "99978b3f-72fe-46e3-8b9b-25ba02899fa0", "name": "Needs Input"},
+        }
+        await handle_issue_updated(data, ORCH_PROJECT_ID)
+
+    mock_start.assert_not_called()
+    mock_verdict.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_webhook_et_in_progress_not_confused_with_orch():
+    """ET In Progress UUID does NOT trigger pipeline for ORCH project.
+
+    This guards against the reverse confusion: if somehow an ET UUID was sent
+    for an ORCH project event, it should NOT start the pipeline (wrong UUID).
+    """
+    from src.webhooks.plane import handle_issue_updated
+    orch_states_resp = _make_states_response(ORCH_STATES)
+    with patch("src.plane_sync.httpx.get") as mock_httpx, \
+         patch("src.webhooks.plane.handle_status_start", new_callable=AsyncMock) as mock_start, \
+         patch("src.webhooks.plane.handle_verdict", new_callable=AsyncMock) as mock_verdict:
+        mock_httpx.return_value = _fake_response(orch_states_resp)
+        # Send ET's in_progress UUID for an ORCH project event.
+        data = {
+            "id": "orch-issue-uuid",
+            "state": {"id": "b873d9eb-993c-48cd-97ac-99a9b1623967", "name": "In Progress"},
+        }
+        await handle_issue_updated(data, ORCH_PROJECT_ID)
+
+    # Since ORCH in_progress is e331bfb3, ET's b873d9eb should NOT trigger start.
+    mock_start.assert_not_called()
+    mock_verdict.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# 8. _DEFAULT_STATES / PLANE_STATES alias preserved
+# ---------------------------------------------------------------------------
+
+def test_plane_states_alias_is_default_states():
+    """PLANE_STATES is still exported and equals _DEFAULT_STATES (backward compat)."""
+    import src.plane_sync as ps
+    assert ps.PLANE_STATES is ps._DEFAULT_STATES
+
+
+def test_default_states_et_values():
+    """_DEFAULT_STATES contains the original enduro-trails UUIDs."""
+    import src.plane_sync as ps
+    for key, expected in ET_STATES.items():
+        assert ps._DEFAULT_STATES[key] == expected, (
+            f"_DEFAULT_STATES['{key}']: expected {expected}, got {ps._DEFAULT_STATES.get(key)}"
+        )

tests/test_plane_webhook.py

@@ -33,11 +33,36 @@ from src.main import app  # noqa: E402
 from src.db import init_db, get_db  # noqa: E402
 from src import projects as P  # 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"
 ENDURO_PLANE_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
 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)
 
 
@@ -57,6 +82,13 @@ def setup(monkeypatch):
     # focuses on the project filter, so bypass signature verification.
     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 = (
         f'[{{"plane_project_id": "{ENDURO_PLANE_ID}", "repo": "enduro-trails",'
         f' "work_item_prefix": "ET", "name": "enduro-trails"}},'
@@ -69,6 +101,7 @@ def setup(monkeypatch):
     yield
 
     reload_projects()  # restore from env
+    plane_sync.reload_project_states()
     if os.path.exists(_test_db):
         os.unlink(_test_db)
 
@@ -76,10 +109,10 @@ def setup(monkeypatch):
 # 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
 # routing tests still exercise task creation through the new trigger.
-_IN_PROGRESS = "b873d9eb-993c-48cd-97ac-99a9b1623967"
-
-
+# ORCH-39: the in_progress UUID is now project-specific, so derive it from the
+# 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"):
+    in_progress = _fake_get_project_states(plane_project_id)["in_progress"]
     return client.post(
         "/webhook/plane",
         json={
@@ -90,7 +123,7 @@ def _post_created(plane_project_id, plane_id="wi-1", name="A valid work item tit
                 "name": name,
                 "description_stripped": "This is a sufficiently long description.",
                 "project": plane_project_id,
-                "state": {"id": _IN_PROGRESS, "name": "In Progress", "group": "started"},
+                "state": {"id": in_progress, "name": "In Progress", "group": "started"},
             },
         },
     )

tests/test_post_usage_comments_integration.py

@@ -0,0 +1,199 @@
+"""ORCH-016 / TC-13..TC-15: _post_usage_comments integration tests.
+
+End-to-end (DB + filesystem worktree, no network) verification that
+AgentLauncher._post_usage_comments:
+  - resolves the task by (repo, branch),
+  - threads the explicit duration_s into build_status_comment,
+  - posts exactly ONE status comment authored by the finishing agent,
+  - for deployer: ALSO posts the per-task usage summary (deployer authorship).
+
+The actual Plane HTTP call (plane_sync.add_comment) is patched out; we only
+check the (work_item_id, body, author) tuples the launcher passes to it.
+"""
+
+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_orch016_post_usage.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+from src.agents.launcher import AgentLauncher  # noqa: E402
+
+
+REPO = "enduro-trails"
+BRANCH = "feature/ET-016-x"
+WID = "ET-016"
+
+
+@pytest.fixture
+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()
+    conn = get_db()
+    conn.execute(
+        "INSERT INTO tasks (id, repo, branch, stage, work_item_id) "
+        "VALUES (1, ?, ?, 'review', ?)",
+        (REPO, BRANCH, WID),
+    )
+    conn.commit()
+    conn.close()
+    yield
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+
+
+@pytest.fixture
+def fake_worktree(monkeypatch, tmp_path):
+    """Stub get_worktree_path inside the launcher module to a tmp_path location."""
+    wt = tmp_path / "wt"
+    (wt / "docs" / "work-items" / WID).mkdir(parents=True)
+
+    def _get_wt(repo, branch):
+        return str(wt)
+
+    # The launcher imports get_worktree_path lazily inside the function body
+    # (`from ..git_worktree import get_worktree_path`); patch the source module.
+    monkeypatch.setattr("src.git_worktree.get_worktree_path", _get_wt)
+    monkeypatch.setattr("src.usage._input_total", lambda u: 0)  # quiet <sub> tail
+    return wt
+
+
+@pytest.fixture
+def capture_comments(monkeypatch):
+    posts = []
+
+    def _spy(work_item_id, body, author=None, **kwargs):
+        posts.append({"wid": work_item_id, "body": body, "author": author})
+
+    monkeypatch.setattr("src.agents.launcher.plane_add_comment", _spy)
+    return posts
+
+
+@pytest.fixture
+def public_url(monkeypatch):
+    from src.config import settings
+    monkeypatch.setattr(
+        settings, "gitea_public_url", "https://git.mva154.duckdns.org", raising=False
+    )
+    monkeypatch.setattr(settings, "gitea_url", "http://localhost:3000", raising=False)
+    monkeypatch.setattr(settings, "gitea_owner", "admin", raising=False)
+
+
+# ---------------------------------------------------------------------------
+# TC-13: reviewer comment.
+# ---------------------------------------------------------------------------
+def test_tc13_reviewer_posts_one_status_comment(
+    setup_db, fake_worktree, capture_comments, public_url
+):
+    (fake_worktree / "docs" / "work-items" / WID / "12-review.md").write_text(
+        "---\nverdict: APPROVE\n---\nReviewed.",
+    )
+
+    AgentLauncher()._post_usage_comments(
+        run_id=99, agent="reviewer", repo=REPO, branch=BRANCH,
+        usage={"input_tokens": 1, "output_tokens": 1, "cost_usd": 0.01},
+        duration_s=180,
+    )
+
+    assert len(capture_comments) == 1
+    post = capture_comments[0]
+    assert post["wid"] == WID
+    assert post["author"] == "reviewer"
+    body = post["body"]
+    assert "\U0001f50e Reviewer" in body
+    assert "Verdict: APPROVE" in body
+    assert "Длительность: 3m 00s" in body
+    assert "12-review.md" in body
+
+
+# ---------------------------------------------------------------------------
+# TC-14: tester comment.
+# ---------------------------------------------------------------------------
+def test_tc14_tester_posts_one_status_comment(
+    setup_db, fake_worktree, capture_comments, public_url
+):
+    (fake_worktree / "docs" / "work-items" / WID / "13-test-report.md").write_text(
+        "---\nverdict: PASS\n---\n",
+    )
+
+    AgentLauncher()._post_usage_comments(
+        run_id=100, agent="tester", repo=REPO, branch=BRANCH,
+        usage=None, duration_s=42,
+    )
+
+    assert len(capture_comments) == 1
+    post = capture_comments[0]
+    assert post["author"] == "tester"
+    body = post["body"]
+    assert "\U0001f9ea Tester" in body
+    assert "Verdict: PASS" in body
+    assert "Длительность: 42s" in body
+
+
+# ---------------------------------------------------------------------------
+# TC-15: deployer comment + per-task summary (two comments, both from deployer).
+# ---------------------------------------------------------------------------
+def test_tc15_deployer_posts_status_then_summary(
+    setup_db, fake_worktree, capture_comments, public_url
+):
+    # Task stage = 'deploy' so build_status_comment uses 14-deploy-log.md.
+    conn = get_db()
+    conn.execute("UPDATE tasks SET stage='deploy' WHERE id=1")
+    conn.commit()
+    conn.close()
+    (fake_worktree / "docs" / "work-items" / WID / "14-deploy-log.md").write_text(
+        "---\ndeploy_status: SUCCESS\n---\nDeployed.",
+    )
+
+    AgentLauncher()._post_usage_comments(
+        run_id=101, agent="deployer", repo=REPO, branch=BRANCH,
+        usage={"input_tokens": 1, "output_tokens": 1, "cost_usd": 0.01},
+        duration_s=300,
+    )
+
+    # 2 comments: status + per-task summary.
+    assert len(capture_comments) == 2
+    status, summary = capture_comments
+    assert status["author"] == "deployer"
+    assert "Status: SUCCESS" in status["body"]
+    assert "Длительность: 5m 00s" in status["body"]
+    assert "14-deploy-log.md" in status["body"]
+
+    assert summary["author"] == "deployer"
+    # task_summary_comment header (Russian "Итого по задаче").
+    assert "\U0001f4ca" in summary["body"]
+    assert "Итого" in summary["body"]
+
+
+def test_deployer_staging_picks_15_log(
+    setup_db, fake_worktree, capture_comments, public_url
+):
+    conn = get_db()
+    conn.execute("UPDATE tasks SET stage='deploy-staging' WHERE id=1")
+    conn.commit()
+    conn.close()
+    (fake_worktree / "docs" / "work-items" / WID / "15-staging-log.md").write_text(
+        "---\nstaging_status: SUCCESS\n---\n",
+    )
+
+    AgentLauncher()._post_usage_comments(
+        run_id=102, agent="deployer", repo=REPO, branch=BRANCH,
+        usage=None, duration_s=10,
+    )
+
+    # deployer always also posts the summary; check the FIRST comment is status.
+    assert len(capture_comments) == 2
+    status = capture_comments[0]
+    assert "Status: SUCCESS" in status["body"]
+    assert "15-staging-log.md" in status["body"]
+    assert "14-deploy-log.md" not in status["body"]
+    assert "staging-деплой" in status["body"]

tests/test_qg.py

@@ -19,6 +19,7 @@ from src.qg.checks import (
     check_tests_passed,
     check_tests_local,
     check_deploy_status,
+    check_staging_status,
 )
 from src.stages import get_qg_for_stage
 
@@ -448,3 +449,185 @@ class TestCheckTestsLocal:
         assert "../../tests/" in cmd
         assert kwargs["cwd"] == os.path.join(str(tmp_path), "src", "api")
 
+
+
+class TestCheckStagingStatus:
+    """ORCH-35 conditional gate (Variant A): deploy-staging gate is active ONLY for
+    the self-hosting orchestrator repo (has staging infra on localhost:8501). All
+    other repos pass immediately with "Staging gate N/A for <repo>".
+
+    Self-hosting path: reads machine-readable staging_status: from 15-staging-log.md
+    frontmatter. Mirrors check_deploy_status pattern.
+    """
+
+    @pytest.fixture()
+    def orch_dir(self, tmp_path, monkeypatch):
+        """Temp orchestrator repo dir (self-hosting)."""
+        monkeypatch.setattr("src.qg.checks.settings.repos_dir", str(tmp_path))
+        d = tmp_path / "orchestrator"
+        d.mkdir(exist_ok=True)
+        return d
+
+    def _write_log(self, repo_dir, content, wi="ORCH-035"):
+        wi_dir = repo_dir / "docs" / "work-items" / wi
+        wi_dir.mkdir(parents=True, exist_ok=True)
+        (wi_dir / "15-staging-log.md").write_text(content)
+
+    # ------------------------------------------------------------------
+    # Self-hosting (orchestrator) path -- real file check
+    # ------------------------------------------------------------------
+
+    def test_success_verdict_passes(self, orch_dir):
+        self._write_log(
+            orch_dir,
+            "---\nstaging_status: SUCCESS\ntimestamp: 2026-06-05T00:00:00Z\n---\n\nAll staging tests passed.\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035")
+        assert passed is True
+        assert "SUCCESS" in reason
+
+    def test_failed_verdict_fails(self, orch_dir):
+        self._write_log(
+            orch_dir,
+            "---\nstaging_status: FAILED\ntimestamp: 2026-06-05T00:00:00Z\n---\n\n2 tests failed.\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035")
+        assert passed is False
+        assert "FAILED" in reason
+
+    def test_no_file_fails_for_self_hosting(self, orch_dir):
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035")
+        assert passed is False
+        assert "not found" in reason.lower()
+
+    def test_no_field_fails(self, orch_dir):
+        # Frontmatter present but no staging_status field -> must NOT pass.
+        self._write_log(
+            orch_dir,
+            "---\nversion: v0.0.3\n---\n\nStatus: all good (prose only).\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035")
+        assert passed is False
+
+    def test_prose_only_no_frontmatter_fails(self, orch_dir):
+        # Prose mentioning SUCCESS but no machine-readable frontmatter -> fail.
+        self._write_log(
+            orch_dir,
+            "# Staging Log\n\nStatus: SUCCESS (prose, not frontmatter).\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035")
+        assert passed is False
+
+    def test_origin_main_success_passes_when_absent_in_worktree(self, monkeypatch):
+        # Deployer merged 15-staging-log.md into main; not in worktree -> recover from main.
+        monkeypatch.setattr(
+            "src.qg.checks._staging_log_from_main",
+            lambda repo, wi: "---\nstaging_status: SUCCESS\n---\n\nAll good.\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035-main")
+        assert passed is True
+        assert "SUCCESS" in reason
+
+    def test_origin_main_failed_fails(self, monkeypatch):
+        monkeypatch.setattr(
+            "src.qg.checks._staging_log_from_main",
+            lambda repo, wi: "---\nstaging_status: FAILED\n---\n\nboom.\n",
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035-main")
+        assert passed is False
+        assert "FAILED" in reason
+
+    def test_absent_everywhere_fails(self, monkeypatch):
+        monkeypatch.setattr(
+            "src.qg.checks._staging_log_from_main", lambda repo, wi: None
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("orchestrator", "ORCH-035-absent")
+        assert passed is False
+        assert "not found" in reason.lower()
+
+    # ------------------------------------------------------------------
+    # Non-self-hosting path -- instant pass, no file dependency
+    # ------------------------------------------------------------------
+
+    def test_non_self_hosting_passes_immediately_no_file(self, tmp_path, monkeypatch):
+        """Non-self-hosting repo: gate is N/A even without a staging log file."""
+        monkeypatch.setattr("src.qg.checks.settings.repos_dir", str(tmp_path))
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("enduro-trails", "ET-035")
+        assert passed is True
+        assert "N/A" in reason
+        assert "enduro-trails" in reason
+
+    def test_non_self_hosting_passes_regardless_of_file_content(self, tmp_path, monkeypatch):
+        """Even a FAILED staging log must not block a non-self-hosting repo."""
+        monkeypatch.setattr("src.qg.checks.settings.repos_dir", str(tmp_path))
+        et_dir = tmp_path / "enduro-trails" / "docs" / "work-items" / "ET-035"
+        et_dir.mkdir(parents=True)
+        (et_dir / "15-staging-log.md").write_text(
+            "---\nstaging_status: FAILED\n---\nShould be ignored.\n"
+        )
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("enduro-trails", "ET-035")
+        assert passed is True
+        assert "N/A" in reason
+
+    def test_unknown_repo_also_passes_immediately(self, tmp_path, monkeypatch):
+        """Any repo that is not orchestrator gets N/A gate."""
+        monkeypatch.setattr("src.qg.checks.settings.repos_dir", str(tmp_path))
+        from src.qg.checks import check_staging_status
+        passed, reason = check_staging_status("some-other-project", "XY-001")
+        assert passed is True
+        assert "N/A" in reason
+
+    # ------------------------------------------------------------------
+    # is_self_hosting_repo helper
+    # ------------------------------------------------------------------
+
+    def test_is_self_hosting_true_for_orchestrator(self):
+        from src.qg.checks import is_self_hosting_repo
+        assert is_self_hosting_repo("orchestrator") is True
+
+    def test_is_self_hosting_case_insensitive(self):
+        from src.qg.checks import is_self_hosting_repo
+        assert is_self_hosting_repo("Orchestrator") is True
+        assert is_self_hosting_repo("ORCHESTRATOR") is True
+
+    def test_is_self_hosting_false_for_enduro_trails(self):
+        from src.qg.checks import is_self_hosting_repo
+        assert is_self_hosting_repo("enduro-trails") is False
+
+    def test_is_self_hosting_false_for_empty(self):
+        from src.qg.checks import is_self_hosting_repo
+        assert is_self_hosting_repo("") is False
+        assert is_self_hosting_repo(None) is False
+
+    # ------------------------------------------------------------------
+    # Stage machinery (regression: must not be broken)
+    # ------------------------------------------------------------------
+
+    def test_deploy_staging_qg_is_check_staging_status(self):
+        assert get_qg_for_stage("deploy-staging") == "check_staging_status"
+
+    def test_registered_in_qg_checks(self):
+        from src.qg.checks import QG_CHECKS, check_staging_status
+        assert QG_CHECKS.get("check_staging_status") is check_staging_status
+
+    def test_deploy_stage_qg_still_check_deploy_status(self):
+        """Regression: existing deploy QG must not be broken."""
+        assert get_qg_for_stage("deploy") == "check_deploy_status"
+
+    def test_stage_chain(self):
+        """Full chain: testing->deploy-staging->deploy->done."""
+        from src.stages import get_next_stage
+        assert get_next_stage("testing") == "deploy-staging"
+        assert get_next_stage("deploy-staging") == "deploy"
+        assert get_next_stage("deploy") == "done"
+

tests/test_qg_registry_snapshot.py

@@ -0,0 +1,64 @@
+"""ORCH-016 / TC-20 + AC-11: Quality Gates + stage machine are unchanged.
+
+Smoke / change-detector test: the ORCH-016 PR touches comment formatting only.
+The QG registry (src/qg/checks.QG_CHECKS) and the stage-machine table
+(src/stages.STAGE_TRANSITIONS) MUST remain bit-identical to the contracts the
+pipeline depends on. If a future change moves the comment hot path into these
+files by accident, this guard breaks first.
+"""
+
+import os
+
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+
+from src.qg.checks import QG_CHECKS  # noqa: E402
+from src.stages import STAGE_TRANSITIONS  # noqa: E402
+
+
+# The set of QG names the pipeline DEPLOYS on. Order doesn't matter, identity does.
+_EXPECTED_QGS = {
+    "check_analysis_approved",
+    "check_analysis_complete",
+    "check_architecture_done",
+    "check_ci_green",
+    "check_review_approved",
+    "check_tests_passed",
+    "check_reviewer_verdict",
+    "check_tests_local",
+    "check_deploy_status",
+    "check_staging_status",
+}
+
+
+def test_tc20_qg_registry_unchanged():
+    assert set(QG_CHECKS.keys()) == _EXPECTED_QGS
+
+
+def test_tc20_qg_callables_unchanged():
+    # All entries must be callable — no stub / lambda / None.
+    for name, fn in QG_CHECKS.items():
+        assert callable(fn), f"QG {name} is not callable"
+
+
+# Reference snapshot of STAGE_TRANSITIONS (mirrors what's in docs/architecture
+# and src/stages.py — duplicated here on purpose as a regression yardstick).
+_EXPECTED_TRANSITIONS = {
+    "created":        {"next": "analysis",        "agent": "analyst",   "qg": None},
+    "analysis":       {"next": "architecture",    "agent": "architect", "qg": "check_analysis_approved"},
+    "architecture":   {"next": "development",     "agent": "developer", "qg": "check_architecture_done"},
+    "development":    {"next": "review",          "agent": "reviewer",  "qg": "check_ci_green"},
+    "review":         {"next": "testing",         "agent": "tester",    "qg": "check_reviewer_verdict"},
+    "testing":        {"next": "deploy-staging",  "agent": "deployer",  "qg": "check_tests_passed"},
+    "deploy-staging": {"next": "deploy",          "agent": "deployer",  "qg": "check_staging_status"},
+    "deploy":         {"next": "done",            "agent": None,        "qg": "check_deploy_status"},
+    "done":           {"next": None,              "agent": None,        "qg": None},
+}
+
+
+def test_tc20_stage_transitions_unchanged():
+    assert STAGE_TRANSITIONS == _EXPECTED_TRANSITIONS, (
+        "STAGE_TRANSITIONS drift detected — ORCH-016 must not change the "
+        "stage machine. Touched stage_engine or stages.py? Update the snapshot "
+        "in a separate, intentional PR."
+    )

tests/test_resolve_agent_effort.py

@@ -0,0 +1,138 @@
+"""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

tests/test_resolve_agent_model.py

@@ -0,0 +1,156 @@
+"""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 == {}

tests/test_stage_engine.py

@@ -136,7 +136,7 @@ class TestHappyPathAgentSelection:
             ("architecture", "development", "developer"),
             ("development", "review", "reviewer"),
             ("review", "testing", "tester"),
-            ("testing", "deploy", "deployer"),
+            ("testing", "deploy-staging", "deployer"),
         ],
     )
     def test_advance_launches_current_stage_agent(
@@ -507,6 +507,120 @@ class TestAnalysisApprovedFlow:
         flow.assert_called_once()
 
 
+
+
+# ---------------------------------------------------------------------------
+# ORCH-35: deploy-staging gate — rollback on staging failure
+# ---------------------------------------------------------------------------
+class TestStagingGate:
+    """deploy-staging -> deploy must be gated on check_staging_status.
+    FAILED verdict rolls back to development (same as deploy БАГ-8 pattern:
+    staging failure = code is bad, needs developer fix)."""
+
+    def test_staging_success_advances_to_deploy(self, monkeypatch):
+        """Happy path: staging SUCCESS -> advance to deploy (no agent launched)."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS, "check_staging_status": _pass},
+        )
+        task_id = _make_task("deploy-staging")
+        res = advance_stage(
+            task_id, "deploy-staging", "enduro-trails", "ET-035",
+            "feature/ET-035-x", finished_agent="deployer",
+        )
+        assert res.advanced is True
+        assert res.to_stage == "deploy"
+        assert _stage(task_id) == "deploy"
+        # deploy-staging has agent=deployer, so deployer is enqueued for deploy stage
+        assert res.enqueued_agent == "deployer"
+        jobs = _jobs()
+        assert len(jobs) == 1
+        assert jobs[0]["agent"] == "deployer"
+
+    def test_staging_failed_rolls_back_to_development(self, monkeypatch):
+        """ORCH-35: staging FAILED -> roll back to development, not to testing."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS,
+             "check_staging_status": _fail("Staging status: FAILED")},
+        )
+        task_id = _make_task("deploy-staging")
+        res = advance_stage(
+            task_id, "deploy-staging", "enduro-trails", "ET-035",
+            "feature/ET-035-x", finished_agent="deployer",
+        )
+        assert res.advanced is False
+        assert res.rolled_back_to == "development"
+        assert _stage(task_id) == "development"   # NOT deploy, NOT testing
+        assert res.alerted is True
+        assert stage_engine.set_issue_blocked.called
+        assert stage_engine.send_telegram.called
+
+    def test_staging_failed_does_not_reach_deploy(self, monkeypatch):
+        """Prod deploy is unreachable if staging gate is not green."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS,
+             "check_staging_status": _fail("Staging log not found")},
+        )
+        task_id = _make_task("deploy-staging")
+        res = advance_stage(
+            task_id, "deploy-staging", "enduro-trails", "ET-035",
+            "feature/ET-035-x", finished_agent="deployer",
+        )
+        assert res.advanced is False
+        # Task must NOT be in deploy stage
+        assert _stage(task_id) != "deploy"
+
+    def test_staging_missing_log_rolls_back(self, monkeypatch):
+        """Missing 15-staging-log.md -> gate fails -> rollback to development."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS,
+             "check_staging_status": _fail("Staging log not found (15-staging-log.md)")},
+        )
+        task_id = _make_task("deploy-staging")
+        res = advance_stage(
+            task_id, "deploy-staging", "enduro-trails", "ET-035",
+            "feature/ET-035-x", finished_agent="deployer",
+        )
+        assert res.advanced is False
+        assert _stage(task_id) == "development"
+
+    def test_testing_to_deploy_staging_advance(self, monkeypatch):
+        """testing -> deploy-staging: deployer is enqueued (ORCH-35 chain check)."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS, "check_tests_passed": _pass},
+        )
+        task_id = _make_task("testing")
+        res = advance_stage(
+            task_id, "testing", "enduro-trails", "ET-035",
+            "feature/ET-035-x", finished_agent="tester",
+        )
+        assert res.advanced is True
+        assert res.to_stage == "deploy-staging"
+        assert _stage(task_id) == "deploy-staging"
+        assert res.enqueued_agent == "deployer"
+
+    def test_deploy_still_rolls_back_on_check_deploy_status_fail(self, monkeypatch):
+        """Existing БАГ-8 rollback must still work for deploy stage (regression guard)."""
+        monkeypatch.setattr(
+            stage_engine, "QG_CHECKS",
+            {**stage_engine.QG_CHECKS,
+             "check_deploy_status": _fail("Deploy status: FAILED")},
+        )
+        task_id = _make_task("deploy")
+        res = advance_stage(
+            task_id, "deploy", "enduro-trails", "ET-011",
+            "feature/ET-011-x", finished_agent="deployer",
+        )
+        assert res.advanced is False
+        assert res.rolled_back_to == "development"
+        assert _stage(task_id) == "development"
+        assert res.alerted is True
+
+
 # ---------------------------------------------------------------------------
 # launcher + plane both delegate to the engine
 # ---------------------------------------------------------------------------

tests/test_status_comment_authorship.py

@@ -0,0 +1,122 @@
+"""ORCH-016 / TC-19 + AC-1..AC-5 authorship: status comments use per-agent bots.
+
+When a status comment is posted by AgentLauncher._post_usage_comments, the
+underlying plane_sync.add_comment must be invoked with ``author=<agent>`` so
+plane_sync._headers_for(<agent>) picks the agent's bot token
+(PLANE_BOT_TOKENS[role]) — falling back to PLANE_HEADERS when the bot token
+is empty / role unknown. Comment FORMAT changes (ORCH-016) must not affect
+that authorship contract.
+"""
+
+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_orch016_authorship.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+from src.agents.launcher import AgentLauncher  # noqa: E402
+
+REPO = "enduro-trails"
+BRANCH = "feature/ET-016-x"
+WID = "ET-016"
+
+
+@pytest.fixture
+def 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()
+    conn = get_db()
+    conn.execute(
+        "INSERT INTO tasks (id, repo, branch, stage, work_item_id) "
+        "VALUES (1, ?, ?, 'review', ?)",
+        (REPO, BRANCH, WID),
+    )
+    conn.commit()
+    conn.close()
+    yield
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+
+
+@pytest.fixture
+def fake_wt(monkeypatch, tmp_path):
+    base = tmp_path / "wt"
+    (base / "docs" / "work-items" / WID).mkdir(parents=True)
+    monkeypatch.setattr("src.git_worktree.get_worktree_path", lambda r, b: str(base))
+    return base
+
+
+@pytest.fixture
+def capture(monkeypatch):
+    posts = []
+
+    def _spy(work_item_id, body, author=None, **kwargs):
+        posts.append({"wid": work_item_id, "body": body, "author": author})
+
+    monkeypatch.setattr("src.agents.launcher.plane_add_comment", _spy)
+    return posts
+
+
+@pytest.mark.parametrize("agent", ["architect", "developer", "reviewer", "tester"])
+def test_tc19_status_comment_carries_agent_author(agent, db, fake_wt, capture):
+    """Each agent's status comment must be POST-ed under that agent's bot."""
+    AgentLauncher()._post_usage_comments(
+        run_id=1, agent=agent, repo=REPO, branch=BRANCH,
+        usage=None, duration_s=10,
+    )
+    assert len(capture) >= 1
+    assert capture[0]["author"] == agent, (
+        f"Expected author={agent!r}, got {capture[0]['author']!r}"
+    )
+
+
+def test_tc19_deployer_status_and_summary_both_authored_by_deployer(db, fake_wt, capture):
+    """Deployer posts TWO comments (status + per-task summary) — both ``author='deployer'``."""
+    conn = get_db()
+    conn.execute("UPDATE tasks SET stage='deploy' WHERE id=1")
+    conn.commit()
+    conn.close()
+
+    AgentLauncher()._post_usage_comments(
+        run_id=2, agent="deployer", repo=REPO, branch=BRANCH,
+        usage=None, duration_s=10,
+    )
+
+    assert len(capture) == 2
+    assert {c["author"] for c in capture} == {"deployer"}
+
+
+def test_tc19_headers_for_unknown_role_falls_back(monkeypatch):
+    """Ensure plane_sync._headers_for handles unknown agents (fallback contract)."""
+    from src import plane_sync
+    h = plane_sync._headers_for("unknown_role_xyz")
+    # PLANE_HEADERS fallback uses settings.plane_api_token (set to 'test-token').
+    assert isinstance(h, dict) and "X-API-Key" in h
+
+
+def test_tc19_status_comment_format_preserves_author_contract(db, fake_wt, capture):
+    """The ORCH-016 format change must not strip the author= kw from the call site."""
+    (fake_wt / "docs" / "work-items" / WID / "12-review.md").write_text(
+        "---\nverdict: APPROVE\n---\n",
+    )
+    AgentLauncher()._post_usage_comments(
+        run_id=3, agent="reviewer", repo=REPO, branch=BRANCH,
+        usage={"input_tokens": 0, "output_tokens": 0, "cost_usd": 0.0},
+        duration_s=180,
+    )
+    assert len(capture) == 1
+    post = capture[0]
+    assert post["author"] == "reviewer"
+    # And the new format is present in the body (sanity).
+    assert "\U0001f50e Reviewer" in post["body"]
+    assert "Verdict: APPROVE" in post["body"]
+    assert "Длительность: 3m 00s" in post["body"]

tests/test_status_comment_dedup_regression.py

@@ -0,0 +1,124 @@
+"""ORCH-016 / TC-17 + AC-7: status-comment de-dup contract.
+
+The «one comment per agent per stage» guarantee is enforced upstream of
+build_status_comment by:
+  - the webhook event-dedup table (events.delivery_id PARTIAL UNIQUE, ORCH-5 /
+    src.db.insert_event_dedup),
+  - the job queue claim-once contract (src.db.claim_next_job, ORCH-1).
+
+The ORCH-016 PR introduces a new comment FORMAT but must not weaken these
+guarantees. This regression test:
+  1. exercises insert_event_dedup directly to confirm the same delivery_id is
+     accepted exactly once (sanity for the dedup primitive),
+  2. exercises build_status_comment to confirm it is a PURE function (same
+     inputs -> same output), so a retried call from a poorly-isolated test or a
+     misbehaving caller doesn't silently produce two different comment bodies.
+"""
+
+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_orch016_dedup_regression.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, insert_event_dedup  # noqa: E402
+
+
+@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)
+
+
+# ---------------------------------------------------------------------------
+# Primitive: event-dedup still rejects a re-delivered webhook.
+# ---------------------------------------------------------------------------
+def test_tc17_event_dedup_inserts_once_for_same_delivery_id():
+    """Two webhook deliveries with the same delivery_id -> one row inserted.
+
+    First call returns True (new row); second call returns False (rejected).
+    This is the primitive every status-comment trigger relies on.
+    """
+    assert insert_event_dedup("plane", "issue.updated", "{}", "delivery-XYZ") is True
+    assert insert_event_dedup("plane", "issue.updated", "{}", "delivery-XYZ") is False
+
+
+def test_tc17_event_dedup_distinguishes_delivery_ids():
+    """Distinct delivery IDs are independent — two different webhooks both go through."""
+    assert insert_event_dedup("plane", "issue.updated", "{}", "delivery-A") is True
+    assert insert_event_dedup("plane", "issue.updated", "{}", "delivery-B") is True
+
+
+# ---------------------------------------------------------------------------
+# Format: build_status_comment is deterministic. A double-fire from buggy code
+# still produces an IDENTICAL body -- so the upstream dedup primitive can
+# safely treat the second call as no-op without comparing prose.
+# ---------------------------------------------------------------------------
+def test_tc17_build_status_comment_is_pure(tmp_path):
+    """Same inputs produce byte-identical output (deterministic / side-effect free)."""
+    from src import usage as U
+
+    wt = tmp_path / "wt"
+    (wt / "docs" / "work-items" / "ET-016").mkdir(parents=True)
+    (wt / "docs" / "work-items" / "ET-016" / "12-review.md").write_text(
+        "---\nverdict: APPROVE\n---\n",
+    )
+
+    args = dict(
+        repo="enduro-trails",
+        branch="feature/ET-016-x",
+        work_item_id="ET-016",
+        duration_s=120,
+        worktree_root=str(wt),
+        usage={"input_tokens": 100, "output_tokens": 50, "cost_usd": 0.05},
+    )
+    a = U.build_status_comment("reviewer", **args)
+    b = U.build_status_comment("reviewer", **args)
+    c = U.build_status_comment("reviewer", **args)
+
+    assert a == b == c
+
+
+def test_tc17_build_status_comment_no_db_side_effects(tmp_path):
+    """A status-comment build must NOT write to the DB.
+
+    Otherwise a webhook-dedup hit would still touch state via the comment
+    builder. We check by counting rows in `tasks`/`agent_runs`/`jobs` before
+    and after.
+    """
+    from src import usage as U
+    from src.db import get_db
+
+    conn = get_db()
+    counts_before = [
+        conn.execute("SELECT COUNT(*) FROM tasks").fetchone()[0],
+        conn.execute("SELECT COUNT(*) FROM agent_runs").fetchone()[0],
+        conn.execute("SELECT COUNT(*) FROM jobs").fetchone()[0],
+    ]
+    conn.close()
+
+    U.build_status_comment(
+        "developer", repo="enduro-trails", branch="b",
+        work_item_id="ET-016", pr_number=1, duration_s=10,
+        usage={"input_tokens": 1, "output_tokens": 1, "cost_usd": 0.01},
+    )
+
+    conn = get_db()
+    counts_after = [
+        conn.execute("SELECT COUNT(*) FROM tasks").fetchone()[0],
+        conn.execute("SELECT COUNT(*) FROM agent_runs").fetchone()[0],
+        conn.execute("SELECT COUNT(*) FROM jobs").fetchone()[0],
+    ]
+    conn.close()
+    assert counts_before == counts_after

tests/test_status_comment_duration_db_fallback.py

@@ -0,0 +1,145 @@
+"""ORCH-016 / TC-24 + TC-25 + AC-14: DB fallback for the duration line.
+
+When build_status_comment is called WITHOUT an explicit duration_s but with a
+task_id, it must:
+  - read the last finished agent_runs row for (task_id, agent),
+  - compute (julianday(finished_at) - julianday(started_at)) * 86400 in seconds,
+  - format it via fmt_duration and inject the «Длительность: …» line.
+
+Failure modes (DB locked / row missing / NULL finished_at / negative diff) must
+NEVER raise; they simply suppress the duration line and let the rest of the
+comment publish.
+"""
+
+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_orch016_duration_fallback.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+
+import pytest  # noqa: E402
+
+from src import db as db_module  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+from src import usage as U  # noqa: E402
+
+
+@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 _insert_run(task_id, agent, *, seconds_ago_start=None, finished=True):
+    """Insert an agent_runs row with controllable timestamps."""
+    conn = get_db()
+    if seconds_ago_start is None:
+        conn.execute(
+            "INSERT INTO agent_runs (task_id, agent) VALUES (?, ?)",
+            (task_id, agent),
+        )
+    else:
+        if finished:
+            conn.execute(
+                "INSERT INTO agent_runs (task_id, agent, started_at, finished_at) "
+                "VALUES (?, ?, datetime('now', ?), datetime('now'))",
+                (task_id, agent, f"-{seconds_ago_start} seconds"),
+            )
+        else:
+            conn.execute(
+                "INSERT INTO agent_runs (task_id, agent, started_at) "
+                "VALUES (?, ?, datetime('now', ?))",
+                (task_id, agent, f"-{seconds_ago_start} seconds"),
+            )
+    conn.commit()
+    conn.close()
+
+
+# ---------------------------------------------------------------------------
+# TC-24: explicit duration_s missing -> DB lookup populates the line.
+# ---------------------------------------------------------------------------
+def test_tc24_fallback_reads_agent_runs_for_last_finished():
+    _insert_run(7, "reviewer", seconds_ago_start=240)
+    secs = U.get_agent_duration(7, "reviewer")
+    # SQLite's julianday math can be off by a second on either side.
+    assert secs is not None and abs(secs - 240) <= 1, secs
+
+    html = U.build_status_comment("reviewer", task_id=7)
+    assert any(
+        s in html for s in (
+            "Длительность: 4m 00s",
+            "Длительность: 4m 01s",
+            "Длительность: 3m 59s",
+        )
+    ), html
+
+
+def test_tc24_fallback_picks_last_run_when_multiple():
+    _insert_run(11, "developer", seconds_ago_start=120)
+    _insert_run(11, "developer", seconds_ago_start=10)
+    secs = U.get_agent_duration(11, "developer")
+    assert secs is not None and abs(secs - 10) <= 1, secs
+
+
+def test_tc24_no_row_returns_none():
+    assert U.get_agent_duration(999, "tester") is None
+
+
+def test_tc24_finished_at_null_returns_none():
+    _insert_run(13, "tester", seconds_ago_start=100, finished=False)
+    assert U.get_agent_duration(13, "tester") is None
+
+
+def test_tc24_missing_args_returns_none():
+    assert U.get_agent_duration(None, "tester") is None
+    assert U.get_agent_duration(7, "") is None
+    assert U.get_agent_duration(0, "tester") is None
+
+
+# ---------------------------------------------------------------------------
+# TC-25: read failure -> logged at debug, NO exception, comment still ships.
+# ---------------------------------------------------------------------------
+def test_tc25_db_read_failure_no_raise(monkeypatch, caplog):
+    """A locked / broken DB must not crash the status comment hot path."""
+    import logging
+
+    def _boom():
+        raise RuntimeError("simulated DB outage")
+
+    monkeypatch.setattr(U, "get_db", _boom)
+    with caplog.at_level(logging.DEBUG, logger="orchestrator.usage"):
+        assert U.get_agent_duration(1, "developer") is None
+        # build_status_comment must still publish (no duration line, no crash).
+        html = U.build_status_comment("developer", task_id=1, repo="r", branch="b")
+        assert "Длительность" not in html
+        assert "\U0001f4bb Developer" in html
+
+
+# ---------------------------------------------------------------------------
+# Sanity: explicit duration_s wins over DB fallback (no SELECT at all).
+# ---------------------------------------------------------------------------
+def test_explicit_duration_wins_over_db_fallback(monkeypatch):
+    called = {"n": 0}
+    real = U.get_agent_duration
+
+    def _spy(task_id, agent):
+        called["n"] += 1
+        return real(task_id, agent)
+
+    monkeypatch.setattr(U, "get_agent_duration", _spy)
+    _insert_run(5, "architect", seconds_ago_start=300)
+
+    html = U.build_status_comment(
+        "architect", task_id=5, duration_s=12, repo="r", branch="b",
+    )
+    assert "Длительность: 12s" in html
+    # Explicit value supplied -> DB fallback is short-circuited.
+    assert called["n"] == 0

tests/test_status_comment_format.py

@@ -0,0 +1,354 @@
+"""ORCH-016 / TC-01..TC-10, TC-12, TC-23: unified status comment format.
+
+Unit tests for src.usage.build_status_comment(...) — the single hot path for
+every agent's "I just finished a stage" comment in Plane (ADR-001).
+
+Covers:
+  * Header per agent (icon + role + description from AC-1..AC-5).
+  * Verdict / Status line read from frontmatter (reviewer / tester / deployer).
+  * Длительность line shown when duration_s is supplied; suppressed otherwise.
+  * <a href="..."> link items per agent.
+  * URL base picks gitea_public_url, falls back to gitea_url.
+  * Graceful behaviour when files are missing / no frontmatter (AC-8).
+
+No DB / no network — only the worktree filesystem (via tmp_path).
+"""
+
+import os
+
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+
+import pytest  # noqa: E402
+
+from src import usage as U  # noqa: E402
+
+
+WID = "ET-016"
+REPO = "enduro-trails"
+BRANCH = "feature/ET-016-status-comments"
+
+
+@pytest.fixture(autouse=True)
+def _set_urls(monkeypatch):
+    """gitea_public_url is the canonical clickable base (AC-9)."""
+    monkeypatch.setattr(U, "logger", U.logger)
+    from src.config import settings
+    monkeypatch.setattr(settings, "gitea_url", "http://localhost:3000", raising=False)
+    monkeypatch.setattr(
+        settings, "gitea_public_url", "https://git.mva154.duckdns.org", raising=False
+    )
+    monkeypatch.setattr(settings, "gitea_owner", "admin", raising=False)
+    yield
+
+
+def _wt_with_files(tmp_path, files: dict) -> str:
+    """Create a worktree skeleton with given files. `files` maps rel-path -> body."""
+    base = tmp_path / "wt"
+    docs = base / "docs" / "work-items" / WID
+    docs.mkdir(parents=True)
+    for rel, body in files.items():
+        p = docs / rel if not rel.startswith("/") else base / rel.lstrip("/")
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(body)
+    return str(base)
+
+
+# ---------------------------------------------------------------------------
+# TC-01: architect comment
+# ---------------------------------------------------------------------------
+def test_tc01_architect_comment(tmp_path):
+    wt = _wt_with_files(tmp_path, {"06-adr/ADR-001-x.md": "x"})
+
+    html = U.build_status_comment(
+        "architect",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=312,
+        worktree_root=wt,
+    )
+    # Header
+    assert "\U0001f4d0 Architect — " in html, html
+    assert "архитектурную" in html
+    assert "См. ADR ниже" in html
+    # Duration: 312s -> 5m 12s
+    assert "Длительность: 5m 12s" in html
+    # ADR link via gitea_public_url
+    assert ("https://git.mva154.duckdns.org/admin/enduro-trails/src/branch/"
+            f"{BRANCH}/docs/work-items/{WID}/06-adr") in html
+    # No Verdict for architect
+    assert "Verdict" not in html
+    assert "Status:" not in html
+
+
+# ---------------------------------------------------------------------------
+# TC-02: developer comment with PR + branch
+# ---------------------------------------------------------------------------
+def test_tc02_developer_comment_links_branch_and_pr():
+    html = U.build_status_comment(
+        "developer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        pr_number=42, duration_s=600,
+    )
+    assert "\U0001f4bb Developer — " in html
+    assert "разработку" in html
+    # Both branch and PR links
+    assert f"https://git.mva154.duckdns.org/admin/{REPO}/src/branch/{BRANCH}" in html
+    assert f"https://git.mva154.duckdns.org/admin/{REPO}/pulls/42" in html
+    assert f"PR #42" in html
+    assert "Длительность: 10m 00s" in html
+    assert "Verdict" not in html
+
+
+# ---------------------------------------------------------------------------
+# TC-03 / TC-04: reviewer verdict via frontmatter
+# ---------------------------------------------------------------------------
+def test_tc03_reviewer_verdict_approve(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "12-review.md": "---\nverdict: APPROVE\n---\nbody...",
+    })
+    html = U.build_status_comment(
+        "reviewer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=120, worktree_root=wt,
+    )
+    assert "\U0001f50e Reviewer — " in html
+    assert "Verdict: APPROVE" in html
+    assert "Длительность: 2m 00s" in html
+    assert "12-review.md" in html
+
+
+def test_tc04_reviewer_verdict_request_changes(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "12-review.md": "---\nverdict: REQUEST_CHANGES\n---\nblockers...",
+    })
+    html = U.build_status_comment(
+        "reviewer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=45, worktree_root=wt,
+    )
+    assert "Verdict: REQUEST_CHANGES" in html
+    assert "Длительность: 45s" in html
+
+
+# ---------------------------------------------------------------------------
+# TC-05: reviewer with NO 12-review.md -> graceful (no Verdict, no Review link)
+# but Длительность and header still present.
+# ---------------------------------------------------------------------------
+def test_tc05_reviewer_missing_artifact_graceful(tmp_path):
+    wt = _wt_with_files(tmp_path, {})  # empty docs dir
+    html = U.build_status_comment(
+        "reviewer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=30, worktree_root=wt,
+    )
+    assert "\U0001f50e Reviewer — " in html
+    assert "Verdict" not in html
+    # Link to 12-review.md is dropped (AC-8 graceful).
+    assert "12-review.md" not in html
+    # Duration still printed when known.
+    assert "Длительность: 30s" in html
+
+
+# ---------------------------------------------------------------------------
+# TC-06 / TC-07: tester verdict via frontmatter (verdict OR status)
+# ---------------------------------------------------------------------------
+def test_tc06_tester_pass(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "13-test-report.md": "---\nverdict: PASS\n---\n",
+    })
+    html = U.build_status_comment(
+        "tester",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=240, worktree_root=wt,
+    )
+    assert "\U0001f9ea Tester — " in html
+    assert "Verdict: PASS" in html
+    assert "Длительность: 4m 00s" in html
+    assert "13-test-report.md" in html
+
+
+def test_tc07_tester_fail(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "13-test-report.md": "---\nverdict: FAIL\n---\n",
+    })
+    html = U.build_status_comment(
+        "tester",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=240, worktree_root=wt,
+    )
+    assert "Verdict: FAIL" in html
+    assert "Длительность: 4m 00s" in html
+
+
+def test_tc07b_tester_falls_back_to_status_key(tmp_path):
+    # Some testers used `status:` instead of `verdict:` (ET-006 / ET-008 pattern).
+    wt = _wt_with_files(tmp_path, {
+        "13-test-report.md": "---\nstatus: PASSED\n---\n",
+    })
+    html = U.build_status_comment(
+        "tester",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=10, worktree_root=wt,
+    )
+    assert "Verdict: PASSED" in html
+
+
+# ---------------------------------------------------------------------------
+# TC-08 / TC-09: deployer status via frontmatter
+# ---------------------------------------------------------------------------
+def test_tc08_deployer_deploy_status_success(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "14-deploy-log.md": "---\ndeploy_status: SUCCESS\n---\n",
+    })
+    html = U.build_status_comment(
+        "deployer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        stage="deploy", duration_s=120, worktree_root=wt,
+    )
+    assert "\U0001f680 Deployer — " in html
+    assert "Status: SUCCESS" in html
+    assert "Длительность: 2m 00s" in html
+    assert "14-deploy-log.md" in html
+
+
+def test_tc09_deployer_staging_status_success(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "15-staging-log.md": "---\nstaging_status: SUCCESS\n---\n",
+    })
+    html = U.build_status_comment(
+        "deployer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        stage="deploy-staging", duration_s=60, worktree_root=wt,
+    )
+    assert "Status: SUCCESS" in html
+    assert "Длительность: 1m 00s" in html
+    # The staging-stage helper links 15-staging-log.md, not 14-deploy-log.md.
+    assert "15-staging-log.md" in html
+    assert "14-deploy-log.md" not in html
+
+
+def test_deployer_status_failed_drives_status_line(tmp_path):
+    wt = _wt_with_files(tmp_path, {
+        "14-deploy-log.md": "---\ndeploy_status: FAILED\n---\n",
+    })
+    html = U.build_status_comment(
+        "deployer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        stage="deploy", duration_s=5, worktree_root=wt,
+    )
+    assert "Status: FAILED" in html
+
+
+# ---------------------------------------------------------------------------
+# TC-10: gitea_public_url is preferred; falls back to gitea_url when empty.
+# ---------------------------------------------------------------------------
+def test_tc10_url_fallback_to_gitea_url(monkeypatch):
+    from src.config import settings
+    monkeypatch.setattr(settings, "gitea_public_url", "", raising=False)
+    monkeypatch.setattr(settings, "gitea_url", "http://localhost:3000", raising=False)
+    html = U.build_status_comment(
+        "developer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        pr_number=7, duration_s=15,
+    )
+    assert "http://localhost:3000/admin/enduro-trails/pulls/7" in html
+    # And the public URL is not there because it was empty.
+    assert "git.mva154.duckdns.org" not in html
+
+
+# ---------------------------------------------------------------------------
+# TC-12: frontmatter parser is graceful — missing file / empty / bad YAML -> None
+# (the comment still publishes the header + duration, just no Verdict / Status).
+# ---------------------------------------------------------------------------
+def test_tc12_frontmatter_missing_file_no_crash(tmp_path):
+    from src.frontmatter import read_frontmatter_value
+    assert read_frontmatter_value(str(tmp_path / "nope.md"), "verdict") is None
+
+
+def test_tc12_frontmatter_empty_no_crash(tmp_path):
+    p = tmp_path / "empty.md"
+    p.write_text("")
+    from src.frontmatter import read_frontmatter_value
+    assert read_frontmatter_value(str(p), "verdict") is None
+
+
+def test_tc12_frontmatter_bad_yaml_no_crash(tmp_path):
+    p = tmp_path / "bad.md"
+    p.write_text("---\nverdict: [unterminated\n---\nbody")
+    from src.frontmatter import read_frontmatter_value
+    assert read_frontmatter_value(str(p), "verdict") is None
+
+
+def test_tc12_frontmatter_missing_key_returns_none(tmp_path):
+    p = tmp_path / "ok.md"
+    p.write_text("---\nother: value\n---\nbody")
+    from src.frontmatter import read_frontmatter_value
+    assert read_frontmatter_value(str(p), "verdict") is None
+
+
+# ---------------------------------------------------------------------------
+# TC-23: duration_s=None and no task_id -> the Длительность line is OMITTED.
+# Header / description / artifact links remain.
+# ---------------------------------------------------------------------------
+def test_tc23_no_duration_no_line(tmp_path):
+    wt = _wt_with_files(tmp_path, {"06-adr/ADR-001-x.md": "x"})
+    html_none = U.build_status_comment(
+        "architect",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        duration_s=None, worktree_root=wt,
+    )
+    html_default = U.build_status_comment(
+        "architect",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        worktree_root=wt,
+    )
+    for html in (html_none, html_default):
+        assert "Длительность" not in html
+        # But the header, description and ADR link are still there.
+        assert "\U0001f4d0 Architect — " in html
+        assert "архитектурную" in html
+        assert "06-adr" in html
+
+
+# ---------------------------------------------------------------------------
+# Extra: usage tail is rendered as <sub> when non-zero, suppressed otherwise.
+# (Backs up ADR-001 §3 and keeps the old usage_comment test contract.)
+# ---------------------------------------------------------------------------
+def test_usage_tail_rendered_when_non_zero():
+    html = U.build_status_comment(
+        "developer",
+        repo=REPO, branch=BRANCH, work_item_id=WID,
+        usage={"input_tokens": 45231, "output_tokens": 12100, "cost_usd": 0.21},
+    )
+    assert "<sub>" in html and "</sub>" in html
+    assert "45.2k in" in html
+    assert "12.1k out" in html
+    assert "$0.21" in html
+
+
+def test_usage_tail_suppressed_when_all_zero():
+    html = U.build_status_comment("developer", repo=REPO, branch=BRANCH)
+    assert "<sub>" not in html
+
+
+# ---------------------------------------------------------------------------
+# AC-1 / AC-5 literal strings — fixed wording per role.
+# ---------------------------------------------------------------------------
+def test_ac1_architect_header_literal():
+    html = U.build_status_comment("architect", repo=REPO, branch=BRANCH,
+                                  work_item_id=WID, duration_s=10)
+    assert "\U0001f4d0 Architect — " in html
+
+
+def test_ac5_deployer_deploy_description():
+    html = U.build_status_comment(
+        "deployer", repo=REPO, branch=BRANCH, work_item_id=WID, stage="deploy",
+    )
+    assert "прод-деплой" in html
+
+
+def test_ac5_deployer_staging_description():
+    html = U.build_status_comment(
+        "deployer", repo=REPO, branch=BRANCH, work_item_id=WID, stage="deploy-staging",
+    )
+    assert "staging-деплой" in html