# Правила работы агентов — Randomayzer Документ адресован любому исполнителю: человеку или агенту. Он описывает не устройство проекта, а обязательный порядок работы над ним. ## 1. Границы задачи Задание определяет область. Выход за неё запрещён, даже когда исправление очевидно и занимает минуту: перемешанные изменения нельзя независимо отревьюить и откатить. Замеченное рядом — отдельным списком в отчёт и предложением следующей задачи. Изменять `Randomizer`, `AuditProof`, deterministic proof format, snapshot hash algorithm и алгоритм `HMAC_SHA256_FY_V1` можно только по отдельному прямому заданию владельца проекта. ## 2. Факты и догадки Выдумывать нельзя. Если решение не принято, версия неизвестна, поведение не проверено или контракт VK не подтверждён — так и пишем: `UNVERIFIED` / `не определено`. Для фактов о VK API, VK ID, OAuth, token scopes, limits и method capabilities источник истины — актуальная официальная документация VK/VKCOM. Старые примеры, сторонние SDK и предположения не выдавать за подтверждённый контракт. ## 3. Проверка «Работает» — не результат проверки. В отчёт идут команды и фактический результат их запуска. Минимальный gate для production-кода: ```text npm ci npx prisma generate npm test npm run lint npm run build ``` Если какая-либо команда не запускалась или среда не позволила её выполнить, это указывается явно. Нельзя писать `green`, `PASS`, `готово` или `закрыто`, если соответствующая проверка фактически не была выполнена. Для concurrency/security задач обязательны заявленные в задании regression/adversarial tests, а не только happy-path unit tests. ## 4. Задания и результаты Задания и отчёты живут в `agents/`. Полная схема — в `agents/README.md`. Коротко: задание — в `agents//inbox/`, результат — в `agents//done/`, черновики — в `agents//notes/`. Задание, пришедшее в чате, агент сначала фиксирует в своём `inbox/`, и только потом работает. Своих служебных папок за пределами `agents//` не заводить. Каждый результат обязан содержать: - base commit SHA; - resulting commit SHA, если код менялся; - список изменённых файлов; - фактически выполненные команды проверки и их результат; - `CRITICAL/HIGH/MEDIUM/LOW` findings, если это review; - список `UNVERIFIED` утверждений; - оставшиеся blockers и non-blocking tech debt. ## 5. Роли агентов Роль задаётся конкретным заданием и не расширяется самостоятельно. - **Antigravity** — основной implementation-agent. Пишет код только в рамках задания, добавляет regression tests и отчёт. - **OpenCode** — implementation/review agent по отдельному заданию. Не дублирует одновременно зону Antigravity без прямого указания. - **Grok** — по умолчанию adversarial/stress reviewer. Production source не меняет, если это прямо не разрешено заданием. - **Claude** — по умолчанию независимый security/code reviewer. Production source не меняет, если это прямо не разрешено заданием. - **Главный агент/координатор** — принимает работу, сводит независимые ревью, определяет статус фазы и разрешает следующий этап. Ни один исполнитель не объявляет самостоятельно `Phase CLOSED`, `release-ready` или `production-ready` — это решение принимает только главный агент после проверки evidence. ## 6. Git и main Каждая задача начинается с фиксации base SHA. Перед отчётом агент обязан указать фактический HEAD/result SHA. Самостоятельный force-push запрещён. Пушить/мержить в `main` разрешено только главному implementation-agent, явно назначенному владельцем проекта для текущей задачи. Review-агенты (Grok/Claude) не пушат production-код и не смешивают review-artifacts с незапрошенными исправлениями. Если несколько агентов работают параллельно, их зоны должны быть непересекающимися либо работа должна идти в отдельных ветках/коммитах с последующим контролируемым merge. ## 7. Security review gate Любое изменение в следующих областях требует независимой проверки до закрытия фазы: - authentication / OAuth / PKCE; - authorization / ownership / IDOR; - sessions / cookies / CSRF; - token storage / TokenVault / refresh; - VK auth resolver / SERVICE→USER fallback; - Prisma ownership/credential migrations; - idempotency / rate limiting; - draw concurrency / snapshot integrity; - public verify/audit boundary. Минимум один независимый reviewer должен проверить security-sensitive change. Если уже есть `CRITICAL` или `HIGH`, найденный независимым reviewer, он считается открытым, пока отдельная повторная проверка не подтвердит `CLOSED` или главный агент не документирует осознанное исключение. Исполнитель не может сам закрыть собственный security finding только формулировкой в отчёте — нужен код/tests/evidence, а для `CRITICAL/HIGH` предпочтительно независимое re-review. ## 8. Правило доказательности фаз Фаза считается закрытой только когда одновременно выполнено: 1. Definition of Done исходного задания; 2. test/lint/build gate или явно принятая владельцем инфраструктурная оговорка; 3. нет открытых release-blocking `CRITICAL/HIGH`; 4. независимые review findings сведены и классифицированы; 5. итоговый commit SHA зафиксирован; 6. главный агент явно объявил фазу закрытой. Наличие большого числа тестов само по себе не доказывает отсутствие уязвимости. Для найденного PoC обязательно добавляется regression test, воспроизводящий именно этот сценарий. ## 9. Секреты и реальные VK credentials Никогда не коммитить и не помещать в review-архивы реальные: - VK access/refresh/service/community tokens; - `VK_CLIENT_SECRET`; - `TOKEN_ENCRYPTION_KEY`; - `AUTH_SECRET`; - `.env`, `.env.local`, private keys и credential files. Реальные credentials используются только через локальные environment variables. В tests/docs применяются очевидно фальшивые marker tokens. Логи, ошибки, API responses, AuditProof и review reports не должны содержать plaintext или encrypted credential values. ## 10. Review snapshots Если reviewer не имеет прямого доступа к репозиторию, source of truth — архив, созданный `tools/export-review.ps1` из конкретного commit SHA. Reviewer обязан указать, какой SHA он проверял. Нельзя незаметно подменять snapshot текущим GitHub `HEAD`. Для небольшого исправления предпочтителен diff-review от явно указанного base SHA. ## 11. Архитектурные инварианты Randomayzer Без отдельного задания нельзя нарушать следующие инварианты: - Giveaway принадлежит одному authenticated organizer; ownerless production giveaway запрещён. - Чужой organizer credential никогда не выбирается по client-supplied id. - SERVICE token предпочтителен для допустимых публичных VK операций; USER fallback только по явной whitelist-policy. - Rate-limit/network/timeout/temporary/validation errors не используются как причина переключения токена. - Expired/unknown USER credential не используется молча. - Token refresh не должен перезаписывать более новую credential state. - Public verification остаётся отделённой от private organizer/participant/credential данных. - VK auth/token metadata не входит в deterministic draw proof. - Partial participant import не может быть сохранён как полный результат без явного partial/error contract. ## 12. Новые call sites и trust boundaries Любой новый route, background job или service, который вызывает `VkProvider`, `VkAuthContextResolver`, `TokenRefresher` или credential repository, обязан доказать происхождение `organizerId` из доверенного server-side контекста. Запрещено передавать в credential resolution `organizerId`, `userId` или `vkUserId`, полученные напрямую из body/query/header клиента, без server-side authorization binding. При добавлении нового call site необходимо добавить тест на cross-user/IDOR сценарий или явно объяснить, почему такой сценарий невозможен. ## 13. Отчётность о несоответствиях Если документация, тест и production-код расходятся, source of truth — фактический production-код и реально выполненная проверка. Расхождение фиксируется отдельным finding; нельзя молча «считать», что документация описывает реализованное поведение. Если один reviewer говорит `PASS`, а другой воспроизводит конкретный PoC, приоритет имеет воспроизводимый PoC до его опровержения или исправления.