diff --git a/AGENTS.md b/AGENTS.md index 0c36664..604b162 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,18 @@ # Акылдаш — инструкции для агента Проект: юридическая информационно-аналитическая платформа; 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). Не запрашивай доступы повторно. +Python, SQLite и OpenSearch. Для инфраструктурных задач используй Skill +`commerce-infra`, контур `commerce`, проект `akyldash`. Сверяй состояние с +[`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md) и +[правилами доступа](docs/operations/ACCESS.md). HTTP 200 сам по себе не +подтверждает готовность индекса или восстановимость данных. - Архитектура и процедуры: [инфраструктура](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`, не читай файлы с учётными данными. +- `main` защищена. Изменения проходят через PR по правилам ниже. +- Доступ к VPS для диагностики ограничен read-only. Не давай серверному + пользователю `codex` общий sudo или доступ к Docker socket. Root-действия + выполняет владелец. - Репозиторный Gitea Actions runner описан в [CI_RUNNER.md](docs/operations/CI_RUNNER.md). Регистрация выполняется владельцем через Settings → Actions → Runners для `admin/akyldash`; токен @@ -66,59 +60,25 @@ Python, SQLite и OpenSearch. На 2026-10-25 публичный `/review` и п - Полная процедура, метрики, 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-команды отдельно, без объединения с другими - командами. +- Создавай ветку от актуальной `main`, коммиты и PR через Gitea Codex MCP. + Обновления вноси в тот же PR. Автор не одобряет и не сливает свой PR. +- После каждого push отдельный ревьюер проверяет полный diff относительно + base и ранее найденные дефекты. Формальное ревью публикуется через Gitea + Agent MCP. Разные учётные записи обеспечивают разделение полномочий. + Независимость требует отдельного исполнителя ревью. +- После первого успешного ревью и CI внеси значимое изменение в существующий + changelog и отправь коммит в тот же PR. Повтори полное ревью итогового diff + и CI. Для docs-only задачи версию приложения повышай только при явном + требовании к этой правке. +- Merge через Gitea Agent MCP допускается после независимого ревью и только + при явном разрешении владельца репозитория. Перед слиянием проверь `admin/akyldash`, номер PR, автора `codex`, base + `main`, ожидаемую ветку и точные SHA head/base. Нужны все успешные + обязательные checks и gates, отсутствие открытых блокеров и действующих + `REQUEST_CHANGES`, формальный `APPROVED` от `agent` с + `commit_id == head_sha`, `stale == false` и `dismissed == false`. + При изменении head или base повтори проверки и ревью. Используй обычный + server-side merge с `head_commit_id`, без force и обхода branch protection. + При неизвестном, ожидающем или неуспешном обязательном условии оставь PR + открытым и укажи причину. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f5bc51..ad5b65e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Не выпущено +- Документация: инструкции Акылдаша переведены на нативный Windows Codex, + `commerce-infra` и Gitea MCP. Сохранены независимое ревью, обязательные + CI-проверки, одобрение текущего head и ограничения production-доступа. - Deployment: подготовлен внешний handoff для Windows-клиента от точного Gitea commit. Bundle фиксирует commit/tree/blob identity и SHA-256; installer проверяет bundle и ACL до записи и не запускает Git. Bootstrap на release A diff --git a/docs/development/DELIVERY_POLICY.md b/docs/development/DELIVERY_POLICY.md index ed01a51..a771ede 100644 --- a/docs/development/DELIVERY_POLICY.md +++ b/docs/development/DELIVERY_POLICY.md @@ -173,5 +173,6 @@ regressions и rollback baseline остаются `N/A`, пока не появ Каждый блокер содержит файл/участок, шаги воспроизведения или точное условие, последствие и минимальный безопасный fix. Остальные замечания — отдельный -неблокирующий список. Review и approval остаются за людьми; агент не начинает -review сам и не сливает PR. +неблокирующий список. Независимый ревьюер проверяет полный diff и передаёт +результат через Gitea Agent MCP. Формальное одобрение и разрешённый Merge +следуют условиям [AGENTS.md](../../AGENTS.md#согласование-изменений). diff --git a/docs/operations/ACCESS.md b/docs/operations/ACCESS.md index 156f89c..9445d1c 100644 --- a/docs/operations/ACCESS.md +++ b/docs/operations/ACCESS.md @@ -2,20 +2,14 @@ ## Discover existing access first -In a new Codex session, inspect the SSH alias and key file metadata without -printing key contents, then check the connection: +For repository work in Windows Codex, use `commerce-infra` to read the +`commerce/akyldash` context through Gitea Infrastructure Registry MCP. Use +Gitea Codex MCP to read the project sources and prepare changes. +Use the repository PR rules for formal review and permitted merge. -```bash -ssh -F ~/.ssh/config -G akyldash_vps | awk '$1 == "hostname" || $1 == "user" || $1 == "port" || $1 == "identityfile" { print }' -test -r ~/.ssh/akyldash_codex && echo 'SSH key is available' -ssh -F ~/.ssh/config -o BatchMode=yes akyldash_vps id -ssh -F ~/.ssh/config -o BatchMode=yes akyldash_vps hostname -f -gitea-api GET /version -gitea-api GET /repos/admin/akyldash -``` - -Do not ask for the host, login, password, token, or key again before these -checks. Never print a private key, token, or complete environment file. +Host access is needed only for separately authorized runtime diagnostics. +Check the configured SSH alias and key metadata without reading key contents. +Do not request passwords, tokens, or keys, or print a complete environment file. ## VPS @@ -42,36 +36,27 @@ checks. Never print a private key, token, or complete environment file. It does not start Compose or create volumes. - Never connect to other VPS hosts or Synology as part of this deployment. -This execution environment is WSL2. The repository is on the Windows-mounted -`/mnt/d` filesystem, while SSH config and the identity file are in the Linux -home directory. Do not assume Windows SSH credentials are available or copy -keys between environments. Plain `ssh akyldash_vps` failed because the system -SSH config include had unsafe permissions. Use `ssh -F ~/.ssh/config ...`; in a -network-restricted session this read-only command may also require approved -execution. If the key is missing in a future environment, report that -limitation and do not retrieve it elsewhere. +For authorized runtime diagnostics, use the configured read-only SSH access. +Validate the resolved alias, hostname, user and port before connecting. Only +use an existing approved key for this environment. If access is unavailable, +record the limitation. Do not copy keys between environments. ## Gitea - Repository: `https://git.vakanaut.ru/admin/akyldash`. -- Use the installed `gitea-api` helper; it reads credentials from the - environment. Never inspect local credential files, print environment values, - or construct HTTP authorization headers. -- The audited API token can read/write this repository and create issues, but - does not have `read:user` or `read:package`. Listing repository Actions - runners returns `403` because the API principal is not the repository owner. - An API `403` caused by missing scope/ownership is not evidence that no runner - exists. -- Protected `main` requires one approval. Do not push directly to `main`, merge - automatically, or start a review. Work on a feature branch and use a PR. -- Gitea Actions and package features are enabled for the repository. The Actions - task API currently returns no runs, but runner availability and package - publishing permissions have not been confirmed. The repository-level runner - is prepared by `infra/runner/install-runner.sh`, but is not installed or - registered yet. Only a repository owner may obtain its registration token in - `admin/akyldash` Settings → Actions → Runners; do not use organization or - instance tokens and never put the token in Git, a command argument, or a - report. See [CI_RUNNER.md](CI_RUNNER.md). +- Use Gitea Codex MCP to read the repository, prepare changes in a separate + branch and open the PR. Use Gitea Agent MCP for formal review, approval and + permitted merge according to [AGENTS.md](../../AGENTS.md#согласование-изменений). + Do not inspect credential files, print secret environment values, or construct + authorization headers. +- Protected `main` requires at least one independent approval and the required + CI checks. Direct push to `main` is prohibited. Merge requires the current + head approval and the checks listed in AGENTS.md. +- A `403` can indicate missing scope or owner permissions. It does not establish + runner absence. Only a repository owner may obtain the repository runner + registration token in `admin/akyldash` Settings → Actions → Runners. Do not use + organization or instance tokens or put the token in Git, a command argument, + or a report. See [CI_RUNNER.md](CI_RUNNER.md). ## Who can do what