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