fix(plane): resolve issue states per-project instead of hardcoded enduro UUIDs (ORCH-10)

ORCH-10 root cause: PLANE_STATES was a global dict hardcoding enduro-trails UUIDs. The webhook comparison only matched ET UUID (b873d9eb) and silently ignored the ORCH in_progress UUID (e331bfb3), blocking pipeline start for all orchestrator-project tasks. Changes: - src/plane_sync.py: * Rename PLANE_STATES -> _DEFAULT_STATES (enduro UUIDs kept as safe fallback). * PLANE_STATES preserved as alias to _DEFAULT_STATES (backward compat). * Add get_project_states(project_id) -> {logical_key: state_uuid}: fetches Plane API GET /projects/<id>/states/, maps by state name, caches per project_id, falls back to _DEFAULT_STATES on API failure. * Add _STATES_CACHE: dict, reload_project_states(project_id=None). * Add _PLANE_NAME_TO_KEY mapping and _STAGE_TO_STATE_KEY for clean lookup. * Add stage_to_state(stage, project_id) using get_project_states(). * update_issue_state() uses stage_to_state() instead of STAGE_TO_STATE dict. * set_issue_{needs_input,in_review,blocked,done,in_progress,stage_state}() all resolve state UUID via get_project_states(project_id) instead of the global PLANE_STATES dict. - src/webhooks/plane.py: * handle_issue_updated: import get_project_states, resolve proj_states per incoming project_id, compare new_state against proj_states["in_progress"], proj_states["approved"], proj_states["rejected"]. * start_pipeline QG-0 blocked path: use get_project_states(plane_project_id) instead of PLANE_STATES["blocked"]. - tests/test_orch10_states.py: 23 new tests covering: * get_project_states returns correct UUIDs for both ET and ORCH projects. * API failure / empty response / None project_id -> _DEFAULT_STATES fallback. * Caching and reload_project_states (per-project and full flush). * stage_to_state() per-project resolution. * Webhook in_progress triggers pipeline for BOTH b873d9eb (ET) and e331bfb3 (ORCH). * Webhook approved/rejected routes correctly per project. * PLANE_STATES alias and _DEFAULT_STATES backward compat.
Merge pull request 'docs(orchestrator): doc canon + CLAUDE.md + agent prompts + reviewer-gate (self-hosting)' (#32 ) from docs/ORCH-9-canon into main
2026-06-05 14:23:31 +03:00 · 2026-06-05 13:28:50 +03:00 · 2026-06-05 12:33:55 +03:00 · 2026-06-05 10:43:38 +03:00
31 changed files with 1456 additions and 64 deletions
--- a/.openclaw/agents/analyst.md
+++ b/.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
--- a/.openclaw/agents/architect.md
+++ b/.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`)
--- a/.openclaw/agents/deployer.md
+++ b/.openclaw/agents/deployer.md
@@ -1,5 +1,18 @@
+---
+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)
--- a/.openclaw/agents/developer.md
+++ b/.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`
+- Перезапускать прод-контейнер орка
--- a/.openclaw/agents/reviewer.md
+++ b/.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 без ссылки на правило
+- Пропускать проверку документации
--- a/.openclaw/agents/tester.md
+++ b/.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-контейнере деструктивные операции
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,24 @@
+# Changelog
+
+Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
+
+## [Unreleased]
+
+### Added
+- **Документация по канону** (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
+- Цепочка стадий: `... testing → deploy-staging → deploy → done` (была без `deploy-staging`).
+
+### Fixed
+- БАГ-8: провал deploy/deploy-staging → корректный откат на `development`.
+- Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings.
+
+---
+*Историю до введения канона см. в `docs/history/` (BUGFIXES_*, LESSONS_*, INCIDENT_*).*
--- a/CLAUDE.md
+++ b/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).*
--- a/README.md
+++ b/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`.

 ## Ключевые механизмы

--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -0,0 +1,77 @@
+# Архитектура 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`.
+
+## База данных (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.*
--- a/docs/architecture/adr/README.md
+++ b/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` → Конвенции).
--- a/docs/architecture/adr/adr-0001-multi-repo-registry.md
+++ b/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 из реестра).
--- a/docs/architecture/adr/adr-0002-job-queue.md
+++ b/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).
--- a/docs/architecture/adr/adr-0003-staging-gate.md
+++ b/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 (исполняемый самодеплой).
--- a/docs/architecture/internals.md
+++ b/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
--- a/docs/history/BACKLOG_PIPELINE.md
+++ b/docs/history/BACKLOG_PIPELINE.md
--- a/docs/history/BUGFIXES_2026-05-21.md
+++ b/docs/history/BUGFIXES_2026-05-21.md
--- a/docs/history/BUGFIXES_2026-06-02.md
+++ b/docs/history/BUGFIXES_2026-06-02.md
--- a/docs/history/BUGFIXES_2026-06-02_ORCH2.md
+++ b/docs/history/BUGFIXES_2026-06-02_ORCH2.md
--- a/docs/history/BUGFIXES_2026-06-03.md
+++ b/docs/history/BUGFIXES_2026-06-03.md
--- a/docs/history/INCIDENT_2026-06-02_webhook_autorun.txt
+++ b/docs/history/INCIDENT_2026-06-02_webhook_autorun.txt
--- a/docs/history/LESSONS_ET006.md
+++ b/docs/history/LESSONS_ET006.md
--- a/docs/history/ORCH-1_JOB_QUEUE.md
+++ b/docs/history/ORCH-1_JOB_QUEUE.md
--- a/docs/operations/DEPLOY_HOOK.md
+++ b/docs/operations/DEPLOY_HOOK.md
--- a/docs/operations/INFRA.md
+++ b/docs/operations/INFRA.md
@@ -0,0 +1,96 @@
+# 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_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` |
+| `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) — изоляция.
+
+## ⚠️ 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.*
--- a/docs/operations/SETUP_WEBHOOKS.md
+++ b/docs/operations/SETUP_WEBHOOKS.md
--- a/docs/operations/STAGING.md
+++ b/docs/operations/STAGING.md
--- a/docs/operations/STAGING_CHECK.md
+++ b/docs/operations/STAGING_CHECK.md
--- a/src/plane_sync.py
+++ b/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):
--- a/src/webhooks/plane.py
+++ b/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}")
--- a/tests/test_orch10_states.py
+++ b/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)}"
+        )
Author	SHA1	Message	Date
Dev Agent	00325bcab0	fix(plane): resolve issue states per-project instead of hardcoded enduro UUIDs (ORCH-10) All checks were successful CI / test (push) Successful in 12s Details CI / test (pull_request) Successful in 10s Details ORCH-10 root cause: PLANE_STATES was a global dict hardcoding enduro-trails UUIDs. The webhook comparison only matched ET UUID (b873d9eb) and silently ignored the ORCH in_progress UUID (e331bfb3), blocking pipeline start for all orchestrator-project tasks. Changes: - src/plane_sync.py: * Rename PLANE_STATES -> _DEFAULT_STATES (enduro UUIDs kept as safe fallback). * PLANE_STATES preserved as alias to _DEFAULT_STATES (backward compat). * Add get_project_states(project_id) -> {logical_key: state_uuid}: fetches Plane API GET /projects/<id>/states/, maps by state name, caches per project_id, falls back to _DEFAULT_STATES on API failure. * Add _STATES_CACHE: dict, reload_project_states(project_id=None). * Add _PLANE_NAME_TO_KEY mapping and _STAGE_TO_STATE_KEY for clean lookup. * Add stage_to_state(stage, project_id) using get_project_states(). * update_issue_state() uses stage_to_state() instead of STAGE_TO_STATE dict. * set_issue_{needs_input,in_review,blocked,done,in_progress,stage_state}() all resolve state UUID via get_project_states(project_id) instead of the global PLANE_STATES dict. - src/webhooks/plane.py: * handle_issue_updated: import get_project_states, resolve proj_states per incoming project_id, compare new_state against proj_states["in_progress"], proj_states["approved"], proj_states["rejected"]. * start_pipeline QG-0 blocked path: use get_project_states(plane_project_id) instead of PLANE_STATES["blocked"]. - tests/test_orch10_states.py: 23 new tests covering: * get_project_states returns correct UUIDs for both ET and ORCH projects. * API failure / empty response / None project_id -> _DEFAULT_STATES fallback. * Caching and reload_project_states (per-project and full flush). * stage_to_state() per-project resolution. * Webhook in_progress triggers pipeline for BOTH b873d9eb (ET) and e331bfb3 (ORCH). * Webhook approved/rejected routes correctly per project. * PLANE_STATES alias and _DEFAULT_STATES backward compat.	2026-06-05 14:23:31 +03:00
Slava	5ecd1c4692	Merge pull request 'docs(orchestrator): doc canon + CLAUDE.md + agent prompts + reviewer-gate (self-hosting)' (#32 ) from docs/ORCH-9-canon into main	2026-06-05 13:28:50 +03:00
Dev Agent	7c68d1d812	docs(orchestrator): adopt enduro doc canon + CLAUDE.md + ADR (ORCH-9) All checks were successful CI / test (pull_request) Successful in 9s Details	2026-06-05 12:33:55 +03:00
Slava	f1b31463ad	Merge pull request 'feat(pipeline): add deploy-staging gate before prod deploy (ORCH-35)' (#31 ) from feature/ORCH-35-staging-gate into main	2026-06-05 10:43:38 +03:00