From 8ab644232169c0898d4a0f8be5385618bd447b8a Mon Sep 17 00:00:00 2001 From: Stream Date: Fri, 5 Jun 2026 12:30:01 +0300 Subject: [PATCH] auto-sync: 2026-06-05 12:30:01 --- memory/2026-06-05.md | 13 ++- .../orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md | 99 +++++++++++++++++++ tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md | 94 ++++++++++++++++++ .../dev-2026-06-05-orch9-docs-canon.md | 37 +++++++ 4 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 tasks/orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md create mode 100644 tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md create mode 100644 tasks/orchestrator/reports/dev-2026-06-05-orch9-docs-canon.md diff --git a/memory/2026-06-05.md b/memory/2026-06-05.md index a7a7c0d..e96d267 100644 --- a/memory/2026-06-05.md +++ b/memory/2026-06-05.md @@ -371,6 +371,17 @@ - ORCH-11 «Полная дока мультиагентов» id `a396db3e-8618-491f-b62c-cc2bc490e502` (пустая) - ORCH-24 «Персистентная БЗ» id `4c2009b3-3dad-456f-9f9e-1c1fa3d9dda6` (пустая) -### ТЕКУЩАЯ РАБОТА (делаю САМА — дока моя зона): привести docs/ орка к канону + INFRA.md. Согласовано: ДА на всё. +### РЕШЕНИЯ Славы (финал по канону): +1. **Паспорт = per-repo `CLAUDE.md`** (НЕ AGENTS.md, НЕ единый на все). Изоляция репо/проектов — фича. Каждый проект — свой паспорт, точно описывает свой проект. Канон enduro: CLAUDE.md + docs/architecture/ (папка!) + adr/, артефакты 00-business-request..15-staging-log, 04-test-plan.YAML (не md!), per-wi ADR-NNN (upper) / global adr-NNNN (lower). НЕТ CONTRIBUTING.md — конвенции внутри CLAUDE.md. +2. INFRA.md остаётся как орк-специфика (у enduro аналога нет, но self-hosting риск реален). +3. Промпты агентов + reviewer-gate — СЕЙЧАС через Dev. +4. ORCH-9 — сформировать ПРИНЦИПЫ подготовки промптов (методичка), ET = пример-референс, НЕ генерить промпты под enduro. + +### СДЕЛАНО: +- **Комплект доки** (8 файлов) написала САМА по канону enduro, выверено против кода (ДВА ревью: сначала нашла что выдумала свой канон ≡ AGENTS/CONTRIBUTING, потом переписала под enduro-канон). Архив: `temp/orch_docs_canon.tgz`, доставлен на slin `/tmp/orch_docs_canon.tgz`. Исходники: `temp/orch_docs/`. +- **Методичка ORCH-9** `tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md` — принципы подготовки промптов (каркас, инварианты, роль-специфика, reviewer-gate, ET=референс). Ссылка добавлена в описание ORCH-9. +- **Dev запущен** (orch9_docs_canon, session eef3f0c0): ТЗ `DEV_TASK_ORCH9_DOCS_CANON.md` — заливка доки + реструктуризация docs/ (git mv в operations/, history/, ARCHITECTURE.md→architecture/internals.md) + промпты агентов (analyst..tester) + reviewer-gate. Ветка docs/ORCH-9-canon, PR не мержить. + +### ПРОВЕРИТЬ после Dev (лично): структура docs/ по канону, полный набор .openclaw/agents/ (6 ролей), 0 битых ссылок, git mv сохранил историю, README цепочка актуальная, reviewer-gate в promptе, diff только docs/.openclaw (НЕ src/tests/compose). 🏁🏁🏁 СЕРИЯ САМОДЕПЛОЯ ПОЛНОСТЬЮ ЗАВЕРШЕНА 05.06.2026. Орк имеет staging-предохранитель: прод-деплой недостижим, пока staging-гейт не зелёный (для self-hosting). Следующий шаг когда вернёмся — ORCH-36 (исполняемый деплой) с 5 метриками доверия. diff --git a/tasks/orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md b/tasks/orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md new file mode 100644 index 0000000..130c145 --- /dev/null +++ b/tasks/orchestrator/DEV_TASK_ORCH9_DOCS_CANON.md @@ -0,0 +1,99 @@ +# 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. diff --git a/tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md b/tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md new file mode 100644 index 0000000..54bdee5 --- /dev/null +++ b/tasks/orchestrator/ORCH9_PROMPT_PRINCIPLES.md @@ -0,0 +1,94 @@ +# ORCH-9 — Принципы подготовки промптов агентов (методичка онбординга) + +> Часть методологии онбординга нового проекта в оркестратор (ORCH-9). +> Это **принципы и инструкции**, КАК готовить промпты агентов для ЛЮБОГО проекта. +> **enduro-trails (ET) используется как пример-референс** — НЕ как шаблон для копирования. Каждый проект пишет СВОИ промпты под свою специфику. + +--- + +## 1. Базовый принцип: изоляция +- Промпты живут в репо проекта: `.openclaw/agents/.md`. Launcher читает их в рабочем дереве задачи (`cat {system_prompt}` внутри work_path). +- **Промпты СПЕЦИФИЧНЫ для проекта.** Стек, домен, ограничения — свои у каждого. НЕ копировать чужие промпты дословно — копировать СТРУКТУРУ и ПРИНЦИПЫ. +- Полный набор ролей: `analyst`, `architect`, `developer`, `reviewer`, `tester`, `deployer`. + +## 2. Обязательная структура промпта (каркас) +Каждый промпт роли строится по единому каркасу (референс — `enduro-trails/.openclaw/agents/architect.md`): + +``` +--- +name: +description: <одна строка — роль и зона ответственности> +model: <модель — сверить с src/agents/launcher.py AGENT_CONFIGS> +tools: + - <разрешённые инструменты, напр. Filesystem Read везде / Write только docs|src> +--- + +# System prompt: +<кто ты в этом проекте, твоя задача> + +## Контекст проекта +<стек, среды, ключевая специфика — КОРОТКО, детали в CLAUDE.md> + +## Что прочесть в начале +1. CLAUDE.md (паспорт проекта) +2. docs/architecture/README.md +3. <релевантные артефакты задачи: docs/work-items//...> +4. <глобальные ADR: docs/architecture/adr/ — для architect/developer> + +## Что произвести +<точные имена артефактов, которые роль ПИШЕТ — по канону проекта> + +## Принципы +<доменные принципы проекта — из BRD/архитектуры> + +## Запрещено +<анти-паттерны для этого проекта> + +## Эскалация +<когда возврат на предыдущую стадию / нужен approve Owner> +``` + +## 3. Что ОБЯЗАНО быть в КАЖДОМ промпте (инварианты канона) +Независимо от проекта: +1. **«Прочти `CLAUDE.md` и `docs/architecture/README.md` перед работой»** — в разделе «Что прочесть в начале». +2. **Точные имена артефактов проекта** в «Что произвести» (берутся из CLAUDE.md проекта; у каждого проекта свой набор — см. п.5). +3. **Golden source:** «изменил функционал → обнови документацию В ТОМ ЖЕ изменении». +4. **Не править артефакты других стадий.** +5. **Не закрывать задачу самостоятельно** — это делает CI / финальная стадия. +6. **Машинные вердикты** — только YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`), никогда проза. Это читают Quality Gates. + +## 4. Роль-специфичные инварианты +- **analyst** → производит BRD/ТЗ/AC/Test-Plan; НЕ проектирует решения. +- **architect** → заводит ADR (per-work-item + сквозные в `docs/architecture/adr/`); обновляет `docs/architecture/README.md` при изменении состава компонентов; эскалирует крупные изменения (лейбл `arch:major-change`, approve Owner). +- **developer** → код+тесты+PR; обновляет CHANGELOG и релевантную доку; не закрывает задачу. +- **reviewer** → пишет `12-review.md` с `verdict:`. **Reviewer-gate:** если PR меняет функционал, а документация (docs/, CHANGELOG, ADR) НЕ обновлена → `verdict: REQUEST_CHANGES` с указанием, что обновить. Это держит канон автоматически. +- **tester** → прогон по test-plan → `13-test-report.md` с машинным PASS/FAIL. +- **deployer** → деплой/проверка; пишет `14-deploy-log.md` (+ `15-staging-log.md` если у проекта есть staging-гейт). Знает инфра-риски проекта (см. `docs/operations/INFRA.md` если есть). + +## 5. Откуда брать значения для конкретного проекта +| Что | Источник | +|-----|----------| +| Имена артефактов | `CLAUDE.md` проекта (раздел «Артефакты задачи») | +| Модель роли | `src/agents/launcher.py` → `AGENT_CONFIGS` (НЕ выдумывать) | +| Стек / домен / ограничения | `CLAUDE.md` + `docs/architecture/README.md` проекта | +| Цепочка стадий и QG | `src/stages.py` / `docs/architecture/README.md` | +| Инфра-риски (для deployer) | `docs/operations/INFRA.md` проекта (если есть) | + +## 6. Пример-референс: enduro-trails +Готовый, обкатанный в бою набор: `/home/slin/repos/enduro-trails/.openclaw/agents/*.md`. +Изучать как ОБРАЗЕЦ структуры и тона: +- `architect.md` — эталон каркаса (frontmatter → контекст → что прочесть → что произвести → принципы → запрещено → эскалация). +- Видно, как доменная специфика (MapLibre/OSRM/terrain, «всё в Docker», «vanilla JS > React») зашита в «Принципы» и «Запрещено». +- **При онбординге нового проекта:** взять этот каркас, заменить ВСЁ доменное содержимое на специфику нового проекта. Не тащить enduro-специфику в чужой проект. + +## 7. Чеклист готовности набора промптов проекта +- [ ] Все 6 ролей заведены в `.openclaw/agents/` +- [ ] Каждый ссылается на CLAUDE.md + docs/architecture/README.md +- [ ] Имена артефактов совпадают с CLAUDE.md проекта +- [ ] Модели сверены с launcher.py +- [ ] reviewer содержит reviewer-gate на документацию +- [ ] Доменные «Принципы» и «Запрещено» — под этот проект, не скопированы у другого +- [ ] deployer знает инфра-специфику/риски проекта + +--- +*Методичка ORCH-9. enduro-trails — пример-референс, не шаблон. Каждый проект изолирован и пишет свои промпты по этим принципам.* diff --git a/tasks/orchestrator/reports/dev-2026-06-05-orch9-docs-canon.md b/tasks/orchestrator/reports/dev-2026-06-05-orch9-docs-canon.md new file mode 100644 index 0000000..c06f12e --- /dev/null +++ b/tasks/orchestrator/reports/dev-2026-06-05-orch9-docs-canon.md @@ -0,0 +1,37 @@ +# Dev Report: ORCH-9 — Документация орка по канону + промпты агентов + reviewer-gate +Дата: 2026-06-05 +Статус: IN PROGRESS + +## Задача +- Привести документацию репо orchestrator к канону enduro-trails +- Разместить 8 файлов из готового архива /tmp/orch_docs_canon.tgz +- Реструктурировать docs/ через git mv (история сохраняется) +- Добавить промпты агентов: analyst, architect, developer, reviewer, tester +- Прописать reviewer-gate на обновление доки + +## Сделано +- [ ] Подключение к серверу, проверка архива +- [ ] Создание ветки docs/ORCH-9-canon +- [ ] Распаковка архива +- [ ] ЧАСТЬ A: размещение 8 файлов +- [ ] ЧАСТЬ A: git mv реструктуризация +- [ ] ЧАСТЬ A: ARCHITECTURE.md → internals.md +- [ ] ЧАСТЬ A: обновление README.md +- [ ] ЧАСТЬ A: проверка ссылок +- [ ] ЧАСТЬ B: промпты агентов +- [ ] ЧАСТЬ C: reviewer-gate в reviewer.md +- [ ] git commit docs +- [ ] git commit agents +- [ ] PR создан + +## Изменённые файлы +(заполнится по ходу) + +## Результат +(заполнится в конце) + +## Проблемы и решения +(заполнится по ходу) + +## Следующий шаг +Начало выполнения — подключение к серверу.