sfera/CODEX_INSTRUCTIONS.md

Codex Instructions for SFERA

Ты реализуешь SFERA по шагам. Не перескакивай к AI и UI, пока не работает semantic core.

Абсолютные правила

1. Не писать autonomous code generation до готового SIR + parser + graph.
2. Каждый parser bug превращать в golden fixture.
3. Не писать напрямую в Neo4j вне projection-engine.
4. Все изменения в будущем должны быть связаны с task/session/user, но в Phase 1 можно оставить placeholders.
5. Русский UI и команды по умолчанию, но должен быть выбор английского интерфейса/команд; internal models — English.
6. BSL parser обязан поддерживать смешанный русский/английский синтаксис 1С в одном тексте.
7. Любые integration/security/agent слои делать только после core.

Test stand and workspace

• Тестирование интегрированного проекта проводить на docker-test / test-docker, а не на локальном Docker Engine.
• На docker-test разворачивать обе части: backend/server services и frontend.
• Docker endpoint: ssh://test-docker.
• Host: docker-test.cin.su (192.168.200.61), SSH user: test.
• Portainer: http://docker-test.cin.su:9000/, user admin; пароль не сохранять в репозитории и проектных файлах.
• Локальный рабочий путь проекта: Z:\codex\SFERA.
• Z:\codex\SFERA — подмонтированная сетевая папка \\nas\MST\codex\SFERA.
• Для Windows/npm/frontend команд использовать Z:\codex\SFERA, не UNC current directory.

Frontend contract

Перед любым изменением frontend:

1. Прочитать docs/frontend/SFERA_FRONTEND_PRODUCT_CONTRACT.md.
2. Прочитать docs/frontend/SFERA_IDE_UI_CONTRACT.md.
3. Если меняется дерево 1С - прочитать docs/frontend/SFERA_METADATA_TREE_CONTRACT.md.
4. Если меняются настройки проекта - прочитать docs/frontend/SFERA_PROJECT_SETTINGS_CONTRACT.md.
5. Если контракт устарел - сначала обновить контракт, затем код.
6. Все UI-изменения фиксировать в docs/frontend/SFERA_FRONTEND_CHANGELOG.md.

Не ломать принятую модель: SFERA = metadata-first semantic configurator for 1C, основной экран = IDE последнего проекта, проект выбирается сверху, левая панель = дерево текущего проекта, основная конфигурация и расширения = configuration-like roots одного уровня, центр = рабочая область, правая панель = контекстные свойства, низ = открытые объекты, tools и status.

Для 1C-specific поведения использовать official 1C docs через ITS/v8.1c.ru/1C DN или локальные knowledge packs. ITS credentials брать только из .env.local; реальные credentials не коммитить, не писать в markdown/Dockerfile и не выводить в logs.

Текущий приоритет

Реализовать Phase 1:

packages/sir
rust/crates/bsl-parser
packages/semantic-kernel
packages/projection-engine
packages/incremental-indexer

Стиль кода

• Python 3.12+.
• Pydantic v2.
• Async где есть IO.
• Rust parser сначала простой и детерминированный.
• Тесты обязательны.
• Минимальная магия.

Definition of Done Phase 1

1. BSL procedures extracted.
2. Calls extracted.
3. Queries extracted.
4. Writes extracted.
5. SIR snapshot validates.
6. Neo4j projection works.
7. Incremental update works on changed file.