wiki/tasks/orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md

DEV TASK — ORCH-9 (часть 1): документация орка по канону + промпты агентов + reviewer-gate

Проект: orchestrator | Сервер: slin@82.22.50.71 (pw motoZ@yaz2010) | Репо: /home/slin/repos/orchestrator Ветка: docs/ORCH-9-canon из свежего origin/main (git fetch && git checkout main && git pull --ff-only && git checkout -b docs/ORCH-9-canon). PR push в main ЗАПРЕЩЁН, НЕ мержить. Коммит в ветку + PR в Gitea.

ЦЕЛЬ

Привести документацию репо orchestrator к канону проекта enduro-trails (golden source = репо), завести недостающие промпты агентов (чтобы орк мог дорабатывать сам себя — self-hosting), и включить reviewer-gate на обновление документации.

ВХОДНЫЕ ДАННЫЕ

Готовый комплект документации (написан Стрим, выверен против кода и канона enduro) лежит ГОТОВЫМ архивом на хосте slin:

• /tmp/orch_docs_canon.tgz на slin@82.22.50.71 (8 файлов). Распакуй: mkdir -p /tmp/orch_unpack && tar xzf /tmp/orch_docs_canon.tgz -C /tmp/orch_unpack && ls -R /tmp/orch_unpack
• Содержимое: CLAUDE.md, CHANGELOG.md, docs/architecture/README.md, docs/architecture/adr/{README,adr-0001,adr-0002,adr-0003}.md, docs/operations/INFRA.md

НЕ генери эти файлы заново — они выверены. Только размести в репо + реструктурируй существующее. Если архив не найден — СТОП, запроси у Стрим.

ЧАСТЬ A — заливка готовой документации + реструктуризация docs/

A1. Распаковать готовый комплект в корень репо

Из архива (8 файлов) в корень репо:

• CLAUDE.md (корень)
• CHANGELOG.md (корень)
• docs/architecture/README.md
• docs/architecture/adr/README.md
• docs/architecture/adr/adr-0001-multi-repo-registry.md
• docs/architecture/adr/adr-0002-job-queue.md
• docs/architecture/adr/adr-0003-staging-gate.md
• docs/operations/INFRA.md

A2. Реструктуризация существующих docs/ под канон (через git mv, сохранить историю)

• docs/DEPLOY_HOOK.md → docs/operations/DEPLOY_HOOK.md
• docs/STAGING.md → docs/operations/STAGING.md
• docs/STAGING_CHECK.md → docs/operations/STAGING_CHECK.md
• docs/SETUP_WEBHOOKS.md → docs/operations/SETUP_WEBHOOKS.md
• docs/BUGFIXES_2026-05-21.md, docs/BUGFIXES_2026-06-02.md, docs/BUGFIXES_2026-06-02_ORCH2.md, docs/BUGFIXES_2026-06-03.md → docs/history/
• docs/LESSONS_ET006.md → docs/history/
• docs/INCIDENT_2026-06-02_webhook_autorun.txt → docs/history/
• docs/BACKLOG_PIPELINE.md → docs/history/ (исторический бэклог)
• docs/ORCH-1_JOB_QUEUE.md → docs/history/ (содержание сведено в ADR-0002; оставить как архив)
• docs/PRODUCT_VISION.md → ОСТАВИТЬ в docs/PRODUCT_VISION.md (видение продукта, верхний уровень). docs/PRODUCT_VISION.pptx — тоже оставить.

A3. Старый docs/ARCHITECTURE.md — НЕ выбрасывать (там ценная глубина: схема БД SQL, Resilience, Потоки данных, Dockerfile-детали)

• git mv docs/ARCHITECTURE.md docs/architecture/internals.md
• В новом docs/architecture/README.md (обзор) добавь в конце ссылку: Детали реализации (схема БД, потоки, resilience): [internals.md](internals.md).
• В internals.md обнови верхний заголовок и, если есть, цепочку стадий на актуальную (testing → deploy-staging → deploy → done) — НЕ переписывай весь файл, только если там старая цепочка deploy → done без staging.

A4. Обновить корневой README.md

README сейчас содержит УСТАРЕВШУЮ цепочку стадий (без deploy-staging) и устаревшую структуру docs/. Привести:

• Цепочку стадий → актуальная (см. CLAUDE.md / docs/architecture/README.md)
• Таблицу стадий → актуальные QG (development=check_ci_green, testing=check_tests_passed, deploy-staging=check_staging_status, deploy=check_deploy_status)
• Блок «Структура проекта» → актуальная структура docs/ (architecture/, operations/, adr/, work-items/, history/)
• Добавить в начало ссылки: См. CLAUDE.md (паспорт проекта) и docs/architecture/README.md (архитектура).
• НЕ ломать существующие корректные разделы (API Endpoints, Конфигурация env — они актуальны).

A5. Проверить перекрёстные ссылки

После перемещений все ссылки docs/operations/DEPLOY_HOOK.md, STAGING.md в новых файлах должны резолвиться. Прогони проверку битых относительных ссылок в .md (grep ссылок → проверка существования файла). Почини если что-то битое.

ЧАСТЬ B — промпты агентов орка (self-hosting)

У орка в .openclaw/agents/ ТОЛЬКО deployer.md. Нужен ПОЛНЫЙ набор: analyst, architect, developer, reviewer, tester (+ deployer уже есть).

Образец и принципы (НЕ копировать enduro дословно)

• Эталон структуры промптов — /home/slin/repos/enduro-trails/.openclaw/agents/*.md. Изучи каждый.
• Промпты орка ДОЛЖНЫ быть СПЕЦИФИЧНЫ для orchestrator (Python/FastAPI/SQLite/pytest, НЕ MapLibre/OSRM/terrain как у enduro).
• Каждый промпт орка ОБЯЗАН:
  1. В начале: «Прочти CLAUDE.md и docs/architecture/README.md перед работой».
  2. Указывать какие артефакты читать/писать по канону орка (точные имена из CLAUDE.md: 01-brd.md, 02-trz.md, 03-acceptance-criteria.md, 04-test-plan.yaml, 06-adr/ADR-NNN-slug.md, 07/08/10, 12-review.md, 13-test-report.md, 14-deploy-log.md, 15-staging-log.md).
  3. Обязывать обновлять документацию при изменении функционала (golden source).
  4. Архитектор: заводить ADR (per-work-item 06-adr/ADR-NNN-slug.md, сквозные docs/architecture/adr/adr-NNNN-slug.md).
  5. Содержать раздел про self-hosting риск (для тех ролей, что касаются деплоя/рестарта): НЕ ронять прод-контейнер, см. INFRA.md.
• Модели по ролям — как в src/agents/launcher.py AGENT_CONFIGS (architect/reviewer на opus, остальные sonnet) — не выдумывай, сверь с launcher.

B-deployer

deployer.md уже есть (создан в ORCH-35, знает deploy-staging). НЕ ломать, при необходимости дополнить ссылкой на CLAUDE.md/INFRA.md.

ЧАСТЬ C — reviewer-gate на обновление документации

В промпте reviewer орка (создаёшь в части B) ЖЁСТКО прописать правило:

• Reviewer проверяет: если PR меняет функционал (src/), но документация (docs/, CHANGELOG.md, релевантный ADR) НЕ обновлена → вердикт REQUEST_CHANGES с указанием, какую доку обновить.
• Вердикт пишется в 12-review.md через YAML-frontmatter verdict: (канон гейтов).
• ⚠️ Это ТОЛЬКО инструкция в промпте reviewer (текст), НЕ менять код QG check_reviewer_verdict. Гейт уже читает verdict: — reviewer просто будет выставлять REQUEST_CHANGES по новому правилу.

⛔ OFF-LIMITS

• НЕ трогать код src/, tests/, docker-compose.yml, .env*, scripts/ (это docs+промпты задача).
• НЕ менять QG-логику src/qg/checks.py (reviewer-gate — через текст промпта, не код).
• НЕ генерить документацию заново — комплект Стрим уже выверен, ты его РАЗМЕЩАЕШЬ + реструктуризируешь существующее.
• PR push в main запрещён. НЕ мержить. НЕ nohup, НЕ docker-рестарты прода.
• Если архив комплекта недоступен или факт разошёлся с ТЗ — СТОП, запроси у Стрим.

ПРОВЕРКА (пруф в отчёт)

1. find docs CLAUDE.md CHANGELOG.md -type f | sort — новая структура канона на месте.
2. ls .openclaw/agents/ — полный набор: analyst, architect, developer, reviewer, tester, deployer.
3. Битые ссылки в .md: прогон проверки относительных ссылок → 0 битых.
4. git mv сохранил историю: git log --follow docs/operations/DEPLOY_HOOK.md показывает прошлое.
5. README цепочка стадий = актуальная (с deploy-staging).
6. reviewer.md содержит правило REQUEST_CHANGES при необновлённой доке.
7. git diff --name-status origin/main..ветка — только docs/, .md, .openclaw/agents/ (НЕ src/tests/compose/.env/scripts).
8. git log --oneline origin/main..origin/docs/ORCH-9-canon — коммиты после push.

РЕЗУЛЬТАТ

Отчёт → tasks/orchestrator/reports/dev-2026-06-05-orch9-docs-canon.md. Коммиты по смыслу: docs(orchestrator): adopt enduro doc canon + CLAUDE.md + ADR (ORCH-9), feat(agents): add full agent prompt set for self-hosting (ORCH-9). Верни: список новых/перемещённых файлов, ls .openclaw/agents/, проверку ссылок, git diff --name-status, коммит-хэши, номер PR.