Compare commits

...
Author SHA1 Message Date
codex 7f8f6cd297 docs: зафиксировать переход инструкций на Gitea MCP в changelog
CI / tests-and-images (pull_request) Successful in 2m40s
Runner smoke test / runner-smoke (pull_request) Successful in 4s
2026-11-15 18:55:56 +00:00
codex 2a30def397 docs: устранить конфликтующие инструкции по результатам ревью
CI / tests-and-images (pull_request) Successful in 3m1s
Runner smoke test / runner-smoke (pull_request) Successful in 4s
2026-11-15 18:51:41 +00:00
codex d3f5b2b9d1 docs: перейти на Windows Codex и Gitea MCP
CI / tests-and-images (pull_request) Successful in 2m59s
Runner smoke test / runner-smoke (pull_request) Successful in 3s
2026-11-15 18:48:53 +00:00
4 changed files with 60 additions and 111 deletions

No files matched your search

+30 -70
View File
@@ -1,24 +1,18 @@
# Акылдаш — инструкции для агента # Акылдаш — инструкции для агента
Проект: юридическая информационно-аналитическая платформа; Search API на Проект: юридическая информационно-аналитическая платформа; Search API на
Python, SQLite и OpenSearch. На 2026-10-25 публичный `/review` и прямой origin Python, SQLite и OpenSearch. Для инфраструктурных задач используй Skill
отвечают HTTP 200; состав production-контейнеров, готовность индекса и `commerce-infra`, контур `commerce`, проект `akyldash`. Сверяй состояние с
проверенность backup/restore не подтверждены. Сверяй актуальное состояние с [`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md) и
[`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md), не считай HTTP 200 [правилами доступа](docs/operations/ACCESS.md). HTTP 200 сам по себе не
доказательством готовности поиска. подтверждает готовность индекса или восстановимость данных.
- Начинай с [инфраструктурного состояния](docs/operations/CURRENT_STATE.md) и
[правил доступа](docs/operations/ACCESS.md). Не запрашивай доступы повторно.
- Архитектура и процедуры: [инфраструктура](docs/operations/INFRASTRUCTURE.md), - Архитектура и процедуры: [инфраструктура](docs/operations/INFRASTRUCTURE.md),
[деплой](docs/operations/DEPLOYMENT.md), [backup](docs/operations/BACKUP.md), [деплой](docs/operations/DEPLOYMENT.md), [backup](docs/operations/BACKUP.md),
[rollback](docs/operations/ROLLBACK.md), [восстановление](docs/operations/RECOVERY.md). [rollback](docs/operations/ROLLBACK.md), [восстановление](docs/operations/RECOVERY.md).
- Работай в feature/fix/refactor-ветке. `main` защищена; изменения вноси через - `main` защищена. Изменения проходят через PR по правилам ниже.
PR. DEV не одобряет и не сливает собственный PR. Условный merge выполняет - Доступ к VPS для диагностики ограничен read-only. Не давай серверному
только REVIEWER по правилам раздела «Автономный workflow PR» ниже. Сохраняй пользователю `codex` общий sudo или доступ к Docker socket. Root-действия
незакоммиченные изменения. выполняет владелец.
- SSH alias — `akyldash_vps`; используй только read-only диагностику. Не давай
`codex` общий sudo или доступ к Docker socket. Root-действия требует владелец.
Для Gitea используй `gitea-api`, не читай файлы с учётными данными.
- Репозиторный Gitea Actions runner описан в - Репозиторный Gitea Actions runner описан в
[CI_RUNNER.md](docs/operations/CI_RUNNER.md). Регистрация выполняется [CI_RUNNER.md](docs/operations/CI_RUNNER.md). Регистрация выполняется
владельцем через Settings → Actions → Runners для `admin/akyldash`; токен владельцем через Settings → Actions → Runners для `admin/akyldash`; токен
@@ -66,59 +60,25 @@ Python, SQLite и OpenSearch. На 2026-10-25 публичный `/review` и п
- Полная процедура, метрики, Gitea-ограничения и проверенные временные бюджеты: - Полная процедура, метрики, Gitea-ограничения и проверенные временные бюджеты:
[DELIVERY_POLICY.md](docs/development/DELIVERY_POLICY.md). [DELIVERY_POLICY.md](docs/development/DELIVERY_POLICY.md).
## Автономный workflow PR ## Согласование изменений
- Маршруты ниже указаны из контекста оркестратора/root: оркестратор — thread - Создавай ветку от актуальной `main`, коммиты и PR через Gitea Codex MCP.
`01a144a5-8b95-77c3-b311-9a9afd062ca8`, host `local`; DEV — thread Обновления вноси в тот же PR. Автор не одобряет и не сливает свой PR.
`01a138f1-3b34-7c91-a9ed-4b43c3c85f1f`, host - После каждого push отдельный ревьюер проверяет полный diff относительно
`remote-ssh-codex-managed:712b8d4e-24e1-4dd5-92af-85d1fbd26449`, Gitea base и ранее найденные дефекты. Формальное ревью публикуется через Gitea
`codex` (ID 6); REVIEWER — thread `01a144f9-5b51-7923-8398-61d4a6a98306`, Agent MCP. Разные учётные записи обеспечивают разделение полномочий.
host `remote-ssh-codex-managed:b61555d7-8d1a-4cfa-988b-c8da4791d426`, Gitea Независимость требует отдельного исполнителя ревью.
`agent` (ID 7). Если этот же чат отображает REVIEWER как `local` внутри его - После первого успешного ревью и CI внеси значимое изменение в существующий
собственного app-server, это self-label и не является маршрутом из контекста changelog и отправь коммит в тот же PR. Повтори полное ревью итогового diff
оркестратора. и CI. Для docs-only задачи версию приложения повышай только при явном
- DEV принимает только явно зарегистрированную оркестратором человеческую требовании к этой правке.
задачу с полями `task`, `repo`, `branch`, `pr`, `head_sha`, `phase`. Репозиторий - Merge через Gitea Agent MCP допускается после независимого ревью и только
должен быть `admin/akyldash`; работай только в назначенной ветке и PR. Веди при явном разрешении владельца репозитория. Перед слиянием проверь `admin/akyldash`, номер PR, автора `codex`, base
одну задачу/PR за раз и не подхватывай старые PR самостоятельно. `main`, ожидаемую ветку и точные SHA head/base. Нужны все успешные
- Допустимые фазы: `initial_review` — реализация и устранение review findings; обязательные checks и gates, отсутствие открытых блокеров и действующих
`final_review_and_merge` — только после первоначального успешного review, `REQUEST_CHANGES`, формальный `APPROVED` от `agent` с
changelog-коммита и отдельного назначения оркестратора. Не переходи к следующей `commit_id == head_sha`, `stale == false` и `dismissed == false`.
фазе без назначения. Если задача приостановлена, останови любые действия; При изменении head или base повтори проверки и ревью. Используй обычный
после resume перепроверь назначение, PR, head/base, checks и review с нуля. server-side merge с `head_commit_id`, без force и обхода branch protection.
- Повторная доставка одного назначения идемпотентна по ключу При неизвестном, ожидающем или неуспешном обязательном условии оставь PR
`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-команды отдельно, без объединения с другими
командами.
+3
View File
@@ -2,6 +2,9 @@
## Не выпущено ## Не выпущено
- Документация: инструкции Акылдаша переведены на нативный Windows Codex,
`commerce-infra` и Gitea MCP. Сохранены независимое ревью, обязательные
CI-проверки, одобрение текущего head и ограничения production-доступа.
- Deployment: подготовлен внешний handoff для Windows-клиента от точного Gitea - Deployment: подготовлен внешний handoff для Windows-клиента от точного Gitea
commit. Bundle фиксирует commit/tree/blob identity и SHA-256; installer commit. Bundle фиксирует commit/tree/blob identity и SHA-256; installer
проверяет bundle и ACL до записи и не запускает Git. Bootstrap на release A проверяет bundle и ACL до записи и не запускает Git. Bootstrap на release A
+3 -2
View File
@@ -173,5 +173,6 @@ regressions и rollback baseline остаются `N/A`, пока не появ
Каждый блокер содержит файл/участок, шаги воспроизведения или точное условие, Каждый блокер содержит файл/участок, шаги воспроизведения или точное условие,
последствие и минимальный безопасный fix. Остальные замечания — отдельный последствие и минимальный безопасный fix. Остальные замечания — отдельный
неблокирующий список. Review и approval остаются за людьми; агент не начинает неблокирующий список. Независимый ревьюер проверяет полный diff и передаёт
review сам и не сливает PR. результат через Gitea Agent MCP. Формальное одобрение и разрешённый Merge
следуют условиям [AGENTS.md](../../AGENTS.md#согласование-изменений).
+24 -39
View File
@@ -2,20 +2,14 @@
## Discover existing access first ## Discover existing access first
In a new Codex session, inspect the SSH alias and key file metadata without For repository work in Windows Codex, use `commerce-infra` to read the
printing key contents, then check the connection: `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 Host access is needed only for separately authorized runtime diagnostics.
ssh -F ~/.ssh/config -G akyldash_vps | awk '$1 == "hostname" || $1 == "user" || $1 == "port" || $1 == "identityfile" { print }' Check the configured SSH alias and key metadata without reading key contents.
test -r ~/.ssh/akyldash_codex && echo 'SSH key is available' Do not request passwords, tokens, or keys, or print a complete environment file.
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.
## VPS ## VPS
@@ -42,36 +36,27 @@ checks. Never print a private key, token, or complete environment file.
It does not start Compose or create volumes. It does not start Compose or create volumes.
- Never connect to other VPS hosts or Synology as part of this deployment. - 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 For authorized runtime diagnostics, use the configured read-only SSH access.
`/mnt/d` filesystem, while SSH config and the identity file are in the Linux Validate the resolved alias, hostname, user and port before connecting. Only
home directory. Do not assume Windows SSH credentials are available or copy use an existing approved key for this environment. If access is unavailable,
keys between environments. Plain `ssh akyldash_vps` failed because the system record the limitation. Do not copy keys between environments.
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.
## Gitea ## Gitea
- Repository: `https://git.vakanaut.ru/admin/akyldash`. - Repository: `https://git.vakanaut.ru/admin/akyldash`.
- Use the installed `gitea-api` helper; it reads credentials from the - Use Gitea Codex MCP to read the repository, prepare changes in a separate
environment. Never inspect local credential files, print environment values, branch and open the PR. Use Gitea Agent MCP for formal review, approval and
or construct HTTP authorization headers. permitted merge according to [AGENTS.md](../../AGENTS.md#согласование-изменений).
- The audited API token can read/write this repository and create issues, but Do not inspect credential files, print secret environment values, or construct
does not have `read:user` or `read:package`. Listing repository Actions authorization headers.
runners returns `403` because the API principal is not the repository owner. - Protected `main` requires at least one independent approval and the required
An API `403` caused by missing scope/ownership is not evidence that no runner CI checks. Direct push to `main` is prohibited. Merge requires the current
exists. head approval and the checks listed in AGENTS.md.
- Protected `main` requires one approval. Do not push directly to `main`, merge - A `403` can indicate missing scope or owner permissions. It does not establish
automatically, or start a review. Work on a feature branch and use a PR. runner absence. Only a repository owner may obtain the repository runner
- Gitea Actions and package features are enabled for the repository. The Actions registration token in `admin/akyldash` Settings → Actions → Runners. Do not use
task API currently returns no runs, but runner availability and package organization or instance tokens or put the token in Git, a command argument,
publishing permissions have not been confirmed. The repository-level runner or a report. See [CI_RUNNER.md](CI_RUNNER.md).
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).
## Who can do what ## Who can do what