admin/orchestrator

Fork 0

Files

claude-bot 1a132dcff2

CI / test (push) Successful in 18s

Details

CI / test (pull_request) Successful in 18s

Details

feat(deploy): dedicated "Confirm Deploy" status triggers prod deploy

Split the overloaded `Approved` Plane status: it served BOTH as the human BRD
gate on `analysis` AND as the silent Phase B prod-deploy trigger on `deploy`
(ORCH-036), so a routine approve could launch a self-hosting prod restart.

ORCH-059 introduces a dedicated logical status `confirm_deploy` ("Confirm
Deploy") that triggers ONLY Phase B on `deploy`; `Approved` stays purely a
pipeline gate.

- plane_sync: map "Confirm Deploy" -> "confirm_deploy" in _PLANE_NAME_TO_KEY;
  intentionally absent from _DEFAULT_STATES => fail-closed (no UUID -> .get
  yields None, no KeyError, no blind deploy).
- webhooks/plane: handle_issue_updated routes "Confirm Deploy" (fail-closed
  .get) to new handle_confirm_deploy (guarded to stage=="deploy") ->
  _try_advance_stage(confirm_deploy=True).
- stage_engine: advance_stage gains keyword-only confirm_deploy=False; Phase B
  block returns early for deploy+finished_agent is None but only initiates the
  deploy when confirm_deploy=True; a plain Approved is a deterministic no-op
  (returns before check_deploy_status -> no false БАГ-8 rollback).
- Phase A CTA now asks the operator for "Confirm Deploy", not "Approved".

Contracts unchanged: STAGE_TRANSITIONS, QG_CHECKS, check_deploy_status, hook
exit codes, Phases A/C, merge-gate, DB schema. Conditional like ORCH-35/36
(self-hosting only). Docs updated (CLAUDE.md, architecture/README.md, CHANGELOG).

Refs: ORCH-059

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

2026-06-07 19:12:41 +00:00

6.0 KiB

Raw Blame History

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, 16-post-deploy-log.md (post-deploy наблюдение, ORCH-021).

Правила для агентов

Перед любым действием прочесть этот файл и docs/architecture/README.md.
Документация = golden source наравне с кодом. Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови CHANGELOG.md.
Никогда не править артефакты других этапов.
Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.
Не использовать --no-verify без явного одобрения Owner.
Секреты — только в .env/.env.staging на хосте, в гит НЕ коммитятся (канон — .env.example).

⚠️ Self-hosting — оркестратор правит САМ СЕБЯ

Задачи проекта ORCH меняют инструмент, который СЕЙЧАС работает в продакшене и обслуживает ДРУГИЕ проекты (enduro-trails) из ОДНОГО инстанса с ОБЩЕЙ БД и общей очередью.

НЕ перезапускать / не ронять прод-контейнер orchestrator в рамках задачи — встанет конвейер всех проектов.
Любой деплой/рестарт self = групповой риск. Детали и топология — docs/operations/INFRA.md.
Стадия deploy-staging (порт 8501) — обязательная страховка перед прод-деплоем орка.
Прод-деплой орка запускается ТОЛЬКО переводом задачи на стадии deploy в выделенный Plane-статус «Confirm Deploy» (ORCH-059). Статус Approved — человеческий гейт конвейера и прод-деплой НЕ запускает (на deploy — no-op). Это разделяет «одобрить артефакт» и «выкатить в прод», чтобы привычный approve не ронял прод случайным кликом.

Паспорт проекта orchestrator. Поддерживается агентами при каждой доработке. Изолирован: описывает только этот проект (канон per-repo, см. ORCH-9).

6.0 KiB Raw Blame History Unescape Escape