Imported from Leadaxe/LxBox (AGENTS.md). Install upstream with npx skills add Leadaxe/LxBox. Copyright stays with the author.

Руководство для агентов (L×Box)

Правила для AI-агентов и автоматизации, работающих с этим репозиторием.

Git: коммиты и отправка на сервер

Завершённую работу коммитить сразу (решение оператора, 24.07.2026): атомарный коммит в develop с содержательным сообщением, как только изменение закончено и проверено (тесты/analyze). git add — точечно по своим файлам, никогда git add . (параллельные сессии оставляют в дереве чужую незакоммиченную работу — её не трогать).

Push в develop допустим вместе с завершением работы. Только по явной команде оператора:

• git push --force и любое переписывание опубликованной истории;
• всё, что касается main и тегов vX.Y.Z (это релизный процесс — docs/RELEASE_PROCESS.md);
• gh pr create и прочая публикация вовне.

Незавершённую/непроверенную работу не коммитить — сначала цикл код → проверка (для device-фич: APK → подтверждение оператора).

Ветки

• develop — основная ветка разработки. Все feature/fix идут сюда (напрямую или через feature-ветки → PR в develop).
• main — релизная ветка. Сюда пишем только когда готовим релиз: merge из develop, финальные правки заметок / pubspec.yaml, тег vX.Y.Z, автоматический бот-коммит docs/latest.json. Feature-работа в main — нет.
• Теги vX.Y.Z — только на коммитах в main. Полный протокол — docs/RELEASE_PROCESS.md.

Если не указано иное, при работе над задачей исходить из того, что текущая ветка — develop (или feature-ветка от неё). Переключаемся на main только на время релиз-подготовки.

Язык интерфейса

Базовый язык интерфейса — английский, и он единственный. Весь пользовательский текст приложения — экраны, меню, кнопки, надписи, подсказки, диалоги, snackbar'ы, push-уведомления, сообщения об ошибках, пустые состояния — пишется только по-английски.

• Новый UI-текст добавляем на английском (литералом в коде или через будущий механизм локализации) — никогда по-русски или на другом языке.
• Другие языки допустимы только когда и если будет вводиться полноценная локализация (i18n). До этого второго языка в интерфейсе нет.
• Это касается только продуктового текста в приложении. Документация, спеки, комментарии в коде, сообщения коммитов и общение в чате — на русском.

Подробнее — docs/DEVELOPMENT_GUIDE.md → «Архитектурные принципы → 5. Язык интерфейса».

Прочее

Дополнительные правила по мере появления — дополнять этот файл по указанию оператора.

Контракт с лаунчером (SPEC 103)

Всё, что видят оба приложения — LxBox и десктопный лаунчер, — описано в общем контракте раньше, чем реализовано в коде. Два парсера, разошедшиеся на одной подписке, дают пользователю разный набор нод на телефоне и на десктопе; найти такое постфактум дороже, чем описать заранее.

• Источник контракта — репозиторий лаунчера, каталог contract/. В LxBox лежит копия: app/tool/sync_contract.sh кладёт её в app/contract (git её игнорирует) и пишет app/contract.lock с sha256. Копию не редактируют — правки идут в источник.
• Нормативны: registry/** (словари протоколов, allowlist'ы, коды warning'ов, лимиты, переменные), schema/**, docs/** (CANON, IDENTITY, TEMPLATE_LANG, BACKUP). Код обязан им соответствовать, а не наоборот.
• Каждый словарь — под sync-тестом (test/contract/registry_sync_test.dart). Реестр без проверки — просто текст: список в коде уезжает, реестр остаётся, стороны расходятся молча.
• Общее поведение — под общим корпусом contract/corpus/**: те же фикстуры гоняет лаунчер. Новая схема, форма тела подписки или конструкция языка шаблонов добавляется вместе с фикстурой — иначе вторая сторона узнает о ней от пользователя.
• Осознанная разница фиксируется per-app override со ссылкой на решение (IDENTITY.md §4, CANON.md §7); бесхозный override — ошибка.

Перед запуском контрактных тестов синхронизируй копию:

bash app/tool/sync_contract.sh

Памятка суб-агенту (исполнителю по ТЗ)

Проверяется оркестратором при приёмке — нарушение = переделка.

• НЕ трогать: app/analysis_options.yaml, app/pubspec.lock, app/contract.lock, app/contract/** (read-only копия контракта: код подгоняется под фикстуры, не наоборот). Их правки в дереве, если есть, — чужие и предшествуют твоей сессии.
• git add / git commit суб-агент не делает — коммитит оркестратор.
• flutter analyze baseline = 19 issues (все предсуществующие); новых — 0.
• Допустимых красных в полном прогоне НЕТ: flutter test зелёный целиком (последний бывший исключением test/contract/backup_corpus_test.dart: directions_created_on_import закрыт мини-фазой B спеки 393). Любой красный — твой.
• После правки UI-строк / шаблона: dart run tool/l10n/ui_check.dart, template_check, hardcoded_check — 0 failures / 0 warnings.
• UI-тексты только EN; русский каталог app/assets/l10n/ru/* ключуется английским исходником — смена строки = перемап ключа + перевод со склонением (Направление — средний род).
• В слове «канал» два мира: роутинг-домен переименован в Direction/Направление; IPC (MethodChannel, cc_channel.dart, platform_channels.dart), канал установки (§390) и sing-box-термин «исходящий канал» (outbound) остаются каналами. Слепой sed запрещён.
• Тестов на форматирование UI-строк не писать. Ожидания в тестах — через условия/события, не через Future.delayed фиксированной длительности.