# Акылдаш — инструкции для агента Проект: юридическая информационно-аналитическая платформа; Search API на Python, SQLite и OpenSearch. На 2026-10-25 публичный `/review` и прямой origin отвечают HTTP 200; состав production-контейнеров, готовность индекса и проверенность backup/restore не подтверждены. Сверяй актуальное состояние с [`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md), не считай HTTP 200 доказательством готовности поиска. - Начинай с [инфраструктурного состояния](docs/operations/CURRENT_STATE.md) и [правил доступа](docs/operations/ACCESS.md). Не запрашивай доступы повторно. - Архитектура и процедуры: [инфраструктура](docs/operations/INFRASTRUCTURE.md), [деплой](docs/operations/DEPLOYMENT.md), [backup](docs/operations/BACKUP.md), [rollback](docs/operations/ROLLBACK.md), [восстановление](docs/operations/RECOVERY.md). - Работай в feature/fix/refactor-ветке. `main` защищена; изменения вноси через PR. DEV не одобряет и не сливает собственный PR. Условный merge выполняет только REVIEWER по правилам раздела «Автономный workflow PR» ниже. Сохраняй незакоммиченные изменения. - SSH alias — `akyldash_vps`; используй только read-only диагностику. Не давай `codex` общий sudo или доступ к Docker socket. Root-действия требует владелец. Для Gitea используй `gitea-api`, не читай файлы с учётными данными. - Репозиторный Gitea Actions runner описан в [CI_RUNNER.md](docs/operations/CI_RUNNER.md). Регистрация выполняется владельцем через Settings → Actions → Runners для `admin/akyldash`; токен вводится интерактивно и не попадает в Git. Runner использует отдельный rootless Docker daemon; job-контейнеры не получают Docker socket или production secrets. Не включай production deployment из CI без отдельного проверенного deploy-helper. - Локальные проверки: `PYTHONPATH=backend python3 -m unittest discover -s backend -p 'test_*.py' -v` и `python3 -m unittest discover -s tools/telegram-bot -p 'test_*.py' -v`, `python3 -m unittest discover -s infra/backup -p 'test_*.py' -v` и `python3 -m unittest discover -s infra/deploy -p 'test_*.py' -v`, `bash infra/bootstrap/test-host-guard.sh`. Production images собираются командами из `.gitea/workflows/ci.yaml`. - Перед изменениями production необходим проверенный backup. Формального механизма миграций нет; проверяй совместимость SQLite/OpenSearch. Не меняй SSH, firewall или production вручную без владельца и последующего PR. - Холодный backup требует согласованного окна простоя; восстановление допускается только в новый staging-каталог, пока владелец отдельно не проверил процедуру для нового хоста. - После каждого изменения инфраструктуры обновляй `docs/operations/CURRENT_STATE.md` по фактическим проверкам. ## Delivery First: проверка по уровню риска - Перед работой укажи в PR уровень `LOW`, `MEDIUM` или `HIGH`; при сомнении выбери более высокий. Уровень добавляет нужную проверку, но никогда не отменяет CI, одобрение или защиту `main`. - Каждый PR сохраняет текущие проверки Gitea Actions: job IDs `tests-and-images` и `runner-smoke`. Не переименовывай и не обходи их, не удаляй тесты или проверки безопасности ради скорости. - `LOW`: документация, комментарии и тексты без изменения исполняемого поведения или контракта; проверяй diff и актуальность утверждений, затем дождись обычного CI. - `MEDIUM`: изменение поведения в одном компоненте; добавь регрессионный тест, выполни целевые проверки и обычный CI. - `HIGH`: доступ/авторизация, данные и ingestion, схемы/хранилища, backup/restore/recovery, production config, секреты, runner/CI, безопасность или deploy; выполни целевые тесты вместе с обычным CI и приложи проверяемое обоснование угроз, совместимости и rollback. Production-действия остаются за владельцем. - Ревью блокирует только конкретный воспроизводимый дефект, нарушение границы доступа/безопасности, несовместимость данных или контракта, пропущенную обязательную проверку либо отсутствие безопасного rollback. Идеи и стилистические замечания перечисляй отдельно как неблокирующие. - Полная процедура, метрики, Gitea-ограничения и проверенные временные бюджеты: [DELIVERY_POLICY.md](docs/development/DELIVERY_POLICY.md). ## Автономный workflow PR - Маршруты ниже указаны из контекста оркестратора/root: оркестратор — thread `01a144a5-8b95-77c3-b311-9a9afd062ca8`, host `local`; DEV — thread `01a138f1-3b34-7c91-a9ed-4b43c3c85f1f`, host `remote-ssh-codex-managed:712b8d4e-24e1-4dd5-92af-85d1fbd26449`, Gitea `codex` (ID 6); REVIEWER — thread `01a144f9-5b51-7923-8398-61d4a6a98306`, host `remote-ssh-codex-managed:b61555d7-8d1a-4cfa-988b-c8da4791d426`, Gitea `agent` (ID 7). Если этот же чат отображает REVIEWER как `local` внутри его собственного app-server, это self-label и не является маршрутом из контекста оркестратора. - DEV принимает только явно зарегистрированную оркестратором человеческую задачу с полями `task`, `repo`, `branch`, `pr`, `head_sha`, `phase`. Репозиторий должен быть `admin/akyldash`; работай только в назначенной ветке и PR. Веди одну задачу/PR за раз и не подхватывай старые PR самостоятельно. - Допустимые фазы: `initial_review` — реализация и устранение review findings; `final_review_and_merge` — только после первоначального успешного review, changelog-коммита и отдельного назначения оркестратора. Не переходи к следующей фазе без назначения. Если задача приостановлена, останови любые действия; после resume перепроверь назначение, PR, head/base, checks и review с нуля. - Повторная доставка одного назначения идемпотентна по ключу `task`+`pr`+`head_sha`+`stage`: не дублируй commit, push, review-запрос или merge; сообщи оркестратору о уже выполненном результате. Новый head или stage образует новое назначение и требует повторной проверки. - Межчатовое чтение недоступно: оркестратор через central relay сам читает результаты и выдаёт назначения. Завершай каждый этап отчётом с полями `task`, `repo`, `branch`, `pr`, `head_sha`, `stage`, `checks`, `findings`, `next_action`. Не настраивай отдельные webhook, daemon или транспорт. - DEV исследует, изменяет, проверяет, коммитит и отправляет изменения; REVIEWER не меняет код и независимо проверяет полный diff от base после каждого push, включая предыдущие findings. DEV не одобряет и не сливает свой PR. - Только после первоначального успешного формального review DEV добавляет значимые изменения в существующий changelog, коммитит и отправляет их в тот же PR. Затем REVIEWER полностью проверяет итоговый diff. Для docs-only задачи не придумывай изменения кода; правила версии применяй только если они явно относятся к этой документационной правке. - Слияние может выполнить только REVIEWER для зарегистрированной человеческой задачи, в фазе `final_review_and_merge`, после явного назначения оркестратора. Непосредственно перед ним REVIEWER подтверждает `admin/akyldash`, PR, base `main`, ожидаемую ветку, автора PR `codex` (ID 6), неизменность base и head, причём head должен совпадать с зарегистрированным `head_sha`, включая `head_commit_id` для merge-запроса. Требуются все успешные required CI/test checks и gates, отсутствие pending/failed/unknown checks, открытых findings и активных `REQUEST_CHANGES`, плюс актуальный формальный `APPROVED` от REVIEWER для точного текущего commit с параметрами `commit_id == head_sha`, `stale == false`, `dismissed == false`. При изменении head или base review и проверки выполняются заново. Комментарий с approval не является формальным review. Используй только обычный server-side merge с `head_commit_id`; не используй `force_merge` и не обходи branch protection. Если любой существенный gate, статус или защита неизвестны либо не проверяются — не сливай PR и сообщи оркестратору, что именно осталось неизвестным. - Все Gitea API-вызовы выполняй только через `gitea-api` с личным окружением; Git используй с обычным credential helper. Не читай credentials из файлов репозитория. Запускай Git- и API-команды отдельно, без объединения с другими командами.