StatCraft — Генеральный регламент разработки (AGENTS.md)

Стандарт экосистемы ArtCraft / storytold

Данный документ является высшим нормативным актом (законом) для Главного агента-оркестратора и всех специализированных субагентов, работающих с кодовой базой StatCraft.

Каждое правило обязательно к неукоснительному соблюдению. Проект создается в строгом соответствии с каноном экосистемы ArtCraft ({Function}Craft).

1. Канон экосистемы ArtCraft (Ecosystem Foundations)

1.1. Языковой стек (Language: Rust Only)

• Только Rust. Никакого JavaScript или TypeScript.
• Для сборки под Web (WebAssembly) используется wasm-bindgen с генерацией минимального загрузчика. Запрещено писать JS вручную.
• Все вычисления, парсеры и UI компилируются нативно.

1.2. Лицензирование и бренд (Licence & Brand)

• Кодовая база лицензируется под двойной лицензией: MIT OR Apache-2.0 (LICENSE-MIT, LICENSE-APACHE, NOTICE).
• Все используемые сторонние ассеты (иконки Lucide, открытые шрифты) обязаны иметь пермиссивные лицензии, файл лицензии хранится рядом с ассетом (например, assets/icons/LICENSE-lucide.txt), и каждый ассет вносится в ATTRIBUTION.md.
• Логотипы и айдентика ArtCraft в docs/brand/ не являются open source (docs/brand/LICENSE-brand.txt).
• Шрифты берутся из централизованного репозитория storytold/craft-fonts через переменную сборки CRAFT_FONTS_DIR, а не вшиваются в репозиторий.

1.3. Принцип Clean-room (Чистая комната)

• СТРОГО ЗАПРЕЩЕНО копировать исходный код, шейдеры, бинарники, иконки или иные ассеты из проприетарного ПО (такого как IBM SPSS Statistics).
• Поведение, интерфейс и форматы воспроизводятся исключительно путем наблюдения, открытых стандартов и академической литературы:
  • Математические процедуры — по открытым учебникам и публикациям;
  • Форматы .sav / .zsav — по открытой спецификации GNU PSPP и библиотеке ReadStat (MIT);
  • Логика команд и меню — по публичной документации SPSS без заимствования проприетарных ресурсов.

2. Надежность: Железный запрет паник (Never Crash)

• В нетестовом коде категорически запрещены паники:
  • ❌ unwrap()
  • ❌ expect(...)
  • ❌ panic!(...)
  • ❌ unreachable!(...)
  • ❌ todo!(...)
  • ❌ unimplemented!(...)
• Категорический запрет unsafe: Кодовая база — 100% safe Rust.
• Обработка ошибок: Все потенциальные сбои передаются через типизированные ошибки Result<T, E> и оператор ?.
• Валидация входов: Все индексы строк, столбцов, смещения и размеры файлов обязаны проходить строгую проверку границ перед обращением.
• Любое исправление потенциального падения обязано сопровождаться регрессионным тестом.

3. Архитектура: Команды вместо обработчиков (Commands, Not Handlers)

• Любая новая функциональность — это типизированная команда движка (Engine Command), а не изолированный UI-коллбэк.
• UI лишь запрашивает выполнение команды через CommandBus:
  1. Идентификатор команды: Иерархический идентификатор в стиле SPSS (stat.descriptives, stat.ttest.independent, data.sort_cases, transform.compute). Позиция в меню задается путем каталога.
  2. Спецификация параметров (Schema for Agents): Каждая команда предоставляет сигнатуру параметров specs() (например, {"vars":["salary"],"ci":0.95}), доступную для чтения AI-агентам через MCP и командную строку.
  3. Предикат доступности (enabled): Логика, определяющая, активна ли команда в текущем контексте (например, t-тест неактивен, если в датасете нет хотя бы одной количественной и одной группирующей переменной).
  4. История и Undo/Redo: Выполнение команды возвращает JSON-результат и формирует ровно один шаг истории. Сессии ввода текста и перетаскивания объединяются (coalesce).
  5. Синтаксический эквивалент: Каждая команда умеет сериализоваться в строку классического синтаксиса SPSS (.sps) и восстанавливаться из нее.
  6. Диалоговые окна: Параметрические процедуры получают управляемые схемой диалоговые окна с живым предпросмотром (live preview).
  7. Паритет функций: Обновление docs/parity-checklist.md через инструмент cargo xtask parity.

4. Слоистая архитектура и строгая проверка (Layering & xtask)

Кодовая база разделена на независимые слои (L0–L6). Зависимости идут строго сверху вниз:

L6: statcraft_app        (Десктопный GUI на egui / eframe / egui_dock)
 └── L5: statcraft_syntax (Командная шина CommandBus, парсер синтаксиса .sps)
      ├── L4: statcraft_reporting (Модель Pivot Tables, экспорт PDF / DOCX / LaTeX)
      ├── L3: statcraft_charts    (Векторные графики egui_plot, Brushing & Linking)
      └── L2: statcraft_algo      (Математика, тесты, алгоритмы, statrs, faer)
           └── L1: statcraft_core (Apache Arrow/Polars, DataSet, VariableDictionary)
                └── L0: statcraft_io (Кодеки .stc Parquet, SPSS .sav, CSV, Excel)

Вспомогательные сквозные модули:
* statcraft_i18n   (Движок локализации без хардкода строк)
* statcraft_bridge (MCP-сервер и локальный IPC-сокет для AI-агентов)
* xtask            (Утилиты сборщика: layers, parity, test-corpus)

• Проверка архитектуры: Команда cargo xtask layers обязана проходить без ошибок. Новые крейты обязательно регистрируются в xtask/src/layers.rs. Нижние уровни (L0–L2) не знают о существовании UI.

5. Ограничение системных ресурсов (Resource Guard)

• СТРОГО ЗАПРЕЩЕНО запускать компиляцию, тесты или проверки без явного флага ограничения потоков:

  cargo test --workspace -j 1
  cargo check --workspace -j 1
  cargo clippy --workspace -j 1
  cargo build --package statcraft_app --release -j 1

• Максимально допустимое значение: -j 2 — только при прямом письменном согласовании с пользователем.
• В файлах конфигурации .cargo/config.toml и Cargo.toml всегда зафиксированы jobs = 1 и codegen-units = 1.

6. Тестирование и «Золотой оракул» (Testing & Corpora)

• Обязательные тесты на каждый коммит:
  • Кодеки форматов данных (statcraft_io) обязаны содержать тесты на round-trip (запись $\to$ чтение $\to$ равенство) и обработку поврежденных файлов (malformed input tests) без паник.
  • Математический Золотой Оракул (Golden Oracle): Для всех статистических процедур (statcraft_algo) обязательна сверка результатов (значения критериев, $p$-value, степени свободы, доверительные интервалы) с референтными эталонами (Python scipy.stats / GNU PSPP) с точностью не хуже $10^{-6}$.
  • Корпусные тесты (Real-file Corpora): Запуск cargo xtask test-corpus на реальных массивах .sav и .csv. Сами тяжелые файлы корпусов никогда не коммитятся в git-репозиторий.
• Качество кода: Обязательное прохождение cargo fmt --check, cargo clippy --workspace -j 1 -- -D warnings, cargo run -p xtask -j 1 -- file-guard и cargo test -p statcraft_app --test output_viewer_invariants -j 1.

7. Нулевой хардкод строк и доступность локализации (Zero-Hardcode i18n)

• ЖЕЛЕЗНЫЙ ЗАПРЕТ: В исходном коде графического интерфейса (crates/statcraft_app, диалогах, меню, таблицах) категорически запрещены строковые литералы на естественных языках (как на русском, так и на английском).
• Любой текст интерфейса запрашивается по семантическому ключу:

  // ПРАВИЛЬНО:
  ui.label(t!("dialog.file.open_csv"));
  ui.button(t!("action.calculate"));
  
  // КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО:
  ui.label("Открыть CSV...");
  ui.button("Calculate");

• Каталоги локализации хранятся в открытом декларативном формате Fluent (locales/ru.ftl, locales/en.ftl).
• Любой контрибьютор может добавить перевод на новый язык (locales/es.ftl, locales/de.ftl), просто добавив файл в папку, без изменения кода Rust и без перекомпиляции программы.
• Смена языка интерфейса происходит «на лету» без перезапуска.

8. Запрет невоспроизводимых глифов (Vector-First UI)

Базовый шрифт egui не содержит эмодзи и редких символов Unicode. Попытка их вывода приводит к появлению уродливых квадратов «тофу» (□).

• КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ любые Emoji в UI: ❌ 📊, 📈, ⏳, ⚠️, 💡, 📁, 💾, ⚙, 🔍, ✨.
• КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ нестандартные Unicode-символы: ❌ ● (U+25CF), • (U+2022), ✓, ✔, ✕, ✖.
• ПРАВИЛА ОТРИСОВКИ:
  1. Все стили, цвета и отступы берутся из дизайн-системы theme::Tokens и компонентов widgets::*.
  2. Все служебные иконки, индикаторы шкал (Nominal / Ordinal / Scale), стрелки и маркеры отрисовываются векторными примитивами через ui.painter() (circle_filled, line_segment, rect_stroke) либо через кэшированные векторные SVG.
  3. Индикаторы прогресса и вычислений отображаются анимированным векторным спиннером или текстовым "..." с мягкой подсветкой.
  4. Визуальная верификация перед сдачей задач.

9. Протоколы ИИ и «Agent-First» архитектура

• Встроенный Model Context Protocol (MCP) сервер и локальный IPC-сокет: внешние AI-агенты (Antigravity, Claude, локальные LLM) могут через стандартные инструменты исследовать структуру переменных, запускать тесты и автоматически вставлять результаты и их интерпретацию в Output Viewer.

10. Принцип технической честности (Zero-Yesman)

• Агенты обязаны критически анализировать идеи и технические предложения, а не слепо поддакивать.
• Если предложение грозит потерей точности вычислений, ухудшением отзывчивости интерфейса при миллионах строк, утечкой памяти, паникой или нарушением clean-room:
  1. Агент обязан провести краткое исследование;
  2. Прямо и аргументированно предупредить разработчика о рисках;
  3. Предложить промышленную, надежную альтернативу.

11. Проактивная оркестрация субагентов

Для сохранения чистоты контекста Главного агента-оркестратора разработка делится между специализированными ролями:

• stat-math-specialist: реализация математических алгоритмов на Rust (faer, statrs) и валидация через Golden Oracle против SciPy;
• data-engine-specialist: структуры данных в памяти (Arrow/Polars, буфер правок, VariableDictionary);
• ui-specialist: интерфейс на egui, докинг egui_dock, виртуализированный грид таблицы, сводные Pivot Tables;
• i18n-specialist: каталоги переводов (Fluent), модуль statcraft_i18n, линтер отсутствия хардкода строк;
• quality-auditor: прогон тестов строго с -j 1, линтеры, слои (xtask layers), соответствие Definition of Done;
• chronicle-writer: синхронное ведение двуязычной хроники проекта в docs/CHRONICLE.md и docs/CHRONICLE.en.md.

Независимые задачи запускаются параллельно в одном вызове invoke_subagent.

12. Защита от раздутия файлов и инварианты сохранения функционала (File Size Guard & Feature Retention)

12.1. Дифференцированные лимиты строк (File Size Limits)

Для предотвращения деградации контекста LLM и монолитизации кодовой базы установлены предельные размеры файлов:

• Листовые функциональные модули (crates/statcraft_algo/**, crates/statcraft_syntax/**, dialogs/**, views/output_view/**): жесткий лимит 500 строк на файл.
• Комплексные интерактивные редакторы (views/data_view.rs, views/variable_view.rs, views/syntax_editor.rs): лимит 1000 строк на файл.
• Корневой координатор приложения (src/app.rs): потолок 1500 строк.
• Все остальные модули: максимум 1000 строк на файл.
• Обязательное прохождение проверки:

  cargo run -p xtask -j 1 -- file-guard

12.2. Принцип «Разделяй, а не урезай» (Anti-Goodhart Counterweight)

• КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО «укладываться в лимит» ценой урезания функционала: удаления колонок, вырезания таблиц, сжатия кода в однострочники или превращения реализаций в заглушки (todo!(), unimplemented!()).
• Единственным легитимным решением при превышении лимита является архитектурная декомпозиция: выделение изолированных подмодулей (подпапка с mod.rs и дочерними модулями, вынос поддиалогов, разделение процедурных таблиц).

12.3. Инвариант сохранности функционала (Feature Retention Invariant)

• Запрещено изменять или удалять поведение ранее реализованных статистических процедур, истории и отображения сводных таблиц.
• Обязательное прохождение пакета тестов интерфейсных инвариантов:

  cargo test -p statcraft_app --test output_viewer_invariants -j 1

13. Канон дизайн-системы диалоговых окон и защита от халтуры (DialogKit & Design Guard)

13.1. Железный стандарт верстки окон (SPSS Canonical Design)

• Все диалоговые окна обязаны следовать каноническому руководству docs/DESIGN_GUIDE.md и строиться исключительно на базе переиспользуемых компонентов DialogKit (crates/statcraft_app/src/dialogs/common/):
  • DialogShell: управление модальным окном, размерами (DialogSize::Standard 560 × 430, Subdialog 360 × 300, Properties 460 × 380, Compute 620 × 480), центрированием и модальностью;
  • VariablePicker: унифицированный список переменных с отображением иконки шкалы измерения и формата Метка [Имя];
  • TransferButton: векторная адаптивная кнопка переноса (-> / <-), автоматически ориентированная на активный список;
  • DialogActionBar: нижний ряд кнопок действий Type 1 ([ OK ] [ Paste ] [ Reset ] [ Cancel ] [ Help ]) с автоматическим выравниванием по правилу i18n Shield (одинаковая ширина $\ge 80 \times 26$ px, скругление 3 px);
  • SubdialogActionBar: нижняя панель поддиалогов Type 2 ([ Continue ] [ Cancel ] [ Help ]);
  • SubdialogSidebar: правая колонка модальных настроек ([ Statistics... ], [ Options... ], 90 × 24 px);
  • GroupBox: визуальная группировка переключателей и полей ввода.

13.2. Статический линтер дизайна (Design Guard)

• КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО создавать кнопки OK, Paste, Reset, Cancel, Continue сырыми вызовами ui.button(...), а также хардкодить произвольные размеры окон в обход DialogShell.
• Обязательное прохождение линтера дизайна и тестов инвариантов окон в Definition of Done:

  cargo run -p xtask -j 1 -- design-guard
  cargo test -p statcraft_app --test dialog_invariants -j 1

14. Автоматический контроль перед пушем (Local Quality Gate & Pre-Push Hook)

• СТРОГО ОБЯЗАТЕЛЬНО: Перед отправкой любых коммитов в удаленный репозиторий (git push) локально обязан быть выполнен полный Quality Gate:

  cargo run -p xtask -j 1 -- ci

• В репозитории настроен автоматический Git hook через версионируемую папку .githooks/pre-push и git config core.hooksPath .githooks (устанавливается командой cargo run -p xtask -j 1 -- install-hooks).
• КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО обходить проверку хука флагами --no-verify или -n при вызове git push. Любые замечания линтеров, формата или сломанные тесты обязаны быть исправлены локально до попадания в удаленную ветку.