125 lines
12 KiB
Markdown
125 lines
12 KiB
Markdown
# Акылдаш — инструкции для агента
|
||
|
||
Проект: юридическая информационно-аналитическая платформа; 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-команды отдельно, без объединения с другими
|
||
командами.
|