akyldash/AGENTS.md

Акылдаш — инструкции для агента

Проект: юридическая информационно-аналитическая платформа; Search API на Python, SQLite и OpenSearch. Production пока не развернут.

• Начинай с инфраструктурного состояния и правил доступа. Не запрашивай доступы повторно.
• Архитектура и процедуры: инфраструктура, деплой, backup, rollback, восстановление.
• Работай в 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. Регистрация выполняется владельцем через 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 по фактическим проверкам.

Автономный 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-команды отдельно, без объединения с другими командами.