shturman/CLAUDE.md

Штурман — инструкции проекта

Open-source русскоязычный companion-слой («ОС поверх Linux») для авто на RK3588: быстрый Slint-UI + голосовой RU-ассистент, читающий OBD/CAN только на чтение + расширяемый Plugin API. Лицензия MIT. Общение и комментарии — по-русски; код-идентификаторы — как есть.

Фаза: РЕАЛИЗАЦИЯ (v0)

Проектирование завершено. Источник правды по дизайну — каталог docs/ (Tier 0–3 + 8 контрактов + детальный roadmap.md; всё прошло многоагентный adversarial-ревью). Не противоречь докам; если реальность расходится с доком — синхронизируй док (двунаправленные швы, как в дизайн-фазе).

КРАСНЫЕ ЛИНИИ (нерушимы)

1. Никогда не safety-critical — двигатель/тормоза/ABS/ESP/руль/подушки; в системе нет actuator-путей.
2. CAN только на чтение — стандартные OBD-II read-запросы (Mode 01/03/07/09/0A) допустимы; запрещены write/actuator/Mode-04/UDS-write. Граница и энфорсмент — docs/contracts/safety.md.

Стек (canonical — docs/tech-stack.md)

Rust везде в проде (Python — только dev/симуляторы). D-Bus control-plane; PipeWire+WirePlumber (аудио); Wayland + smithay-композитор (Shell); Slint (UI); bubblewrap + Perm-Broker (песочница плагинов); NM/MM + BlueZ (GPL-демоны через D-Bus, изолированы). License-гигиена — cargo-deny.

Dev-окружение (docs/dev-environment.md)

Всё в Lima ARM64-VM (Ubuntu) — нативно к таргету RK3588, разработка без машины (принцип #13): vcan + Vehicle Simulator + моки (аудио/BT/камера/GPS/сеть/plugin-host/нав/облако). justfile — единые команды (just vm-up, just sim, just test, … — создаём по ходу). Перф-вердикт — на реальном RK3588 (не на dev-Mac), бюджеты — docs/contracts/performance.md.

Как работаем (реализация)

• Roadmap ведёт. Идём по вехам docs/roadmap.md. Текущая цель — v0 (критпуть: образ → power-safe → shell).
• Цикл на веху: спека (раскладка/границы/D-Bus-интерфейсы/тест-план/acceptance) → TDD → реализация → verify в Lima-VM → коммит. Не писать код до утверждённой спеки.
• Скиллы: test-driven-development, writing-plans/executing-plans, verification-before-completion, systematic-debugging, requesting-code-review.
• Коммиты: feat/fix/chore(<area>): …; ветка от main (без явного «ок» в main не коммитим); в конце — Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>.
• Сквозные гейты каждой вехи: safety (red-lines/distraction), performance (бюджеты), design-system (визуальный язык).

Текущая цель — v0 (см. docs/roadmap.md § v0)

Фундамент готов и в main (Планы 1–5 ч.1; спека docs/specs/v0.1-v0.6-foundation.md + планы docs/specs/plans/): воркспейс + shturman-common/ipc/sdk + стаб-сервисы firstboot/settings/power (интеграция на D-Bus) + первый Slint-кадр (shell) + dev-tools (валидатор/scaffolding) + systemd/Lima/E2E-файлы. just ci зелёный.

План 5 ч.2 — ГОТОВО (ветка feat/v0.6-lima-e2e): Lima-VM поднимается (just vm-up), сквозной just e2e зелёный с нуля (just vm-reset && just e2e): boot → data.mount → firstboot → machine-id bind → Power/Settings на системной шине → fake-ACC AccChanged → первый Slint-кадр (software-render → PNG, oneshot-сервис) → base-бюджеты (journald volatile / zram / oomd / fake-hwclock→/data / eMMC-прокси) → reboot: персист Settings + machine-id стабилен. Приёмка §9.4 (v0.1 + v0.6 + шагающий скелет) выполнена. Швы реализации — спека §13.

v0.2 Boot-конвейер — ГОТОВО (ветка feat/v0.2-boot-pipeline): спека docs/specs/v0.2-boot-pipeline.md + план docs/specs/plans/06-v0.2-boot-pipeline.md. shturman.target → зонтик фаз Stage 0/1/2; shturman-splash (Stage 0, software-render → /run/shturman/splash.png, Before=shell → до первого кадра) + shturman-stage2-warmup (деферред After=shell); общий рендер-хелпер shturman-render (shell+splash). just vm-reset && just e2e зелёный с нуля: фазы разделены (splash ≤ frame ≤ stage2), регресс v0.1/v0.6 цел. Приёмка спека v0.2 §9.3 выполнена.

v0.3 Power-safe ядро — ГОТОВО (ветка feat/v0.3-power-safe): спека docs/specs/v0.3-power-safe.md + план docs/specs/plans/07-v0.3-power-safe.md. Стаб Power → реальный lifecycle-FSM: чистый PowerFsm (off↔accessory↔running→shutting_down{abortable→committed}→off, abort до PONR) + сервис ru.shturman.Power оживлён из FSM (dev-mock кормит события, grace-таймер + durable-barrier sync на commit); watchdog-конфиг (B05/A14) + save-time timer (B07). just vm-reset && just e2e зелёный с нуля: N=3 цикла зажигания (/data + счётчик целы), abort до PONR (ShutdownAborted, /data RW, running), power-cut-сим (SIGKILL → fsck clean, durable-value цел); регресс v0.1/v0.2 + machine-id-стабильность цел. prod-build-gate: --no-default-features без PowerMock1. Приёмка спека v0.3 §9.4 выполнена. VM-модель (abort/PONR = stop+umount+remount); аппаратное (MCU/hold-up/fail-safe-таймер, B08/B09) → v0.4.

v0.4 MCU/thermal fail-safe — ГОТОВО (ветка feat/v0.4-mcu-thermal): спека docs/specs/v0.4-mcu-thermal.md + план docs/specs/plans/08-v0.4-mcu-thermal.md. Поверх FSM v0.3, в стиле «чистое ядро → абстракция → dev-mock»: A12/B10 тепло — чистая ThermalPolicy (банды + гистерезис) → Event::ThermalTrip (реюз FSM) + abort ThermalCleared; TempSource/Throttler абстракции (VM mock/noop; sysfs/cpufreq + пороги → RK3588). B08 MCU-протокол (SocToMcu/McuToSoc) + кодек (CRC16/replay/desync-guard) + CoprocessorClient (heartbeat/wait-for-completion/ safe-to-cut). B09 fail-safe-таймер — модель (MockCoprocessor: hang/budget → Event::FailsafeCut → off). ru.shturman.Power += ThermalState/ThermalChanged (рендер «перегрев» → v0.5). just vm-reset && just e2e зелёный с нуля: thermal-trip→ShutdownImminent(thermal), throttle-банд, MCU fail-safe (HangSoc → cut); регресс v0.1–v0.3 цел. prod-build-gate без PowerMock1/SetTemp/HangSoc. Приёмка спека v0.4 §9.4 выполнена. Физический выбор B08/B09 (MCU vs supercap-only) + реальное железо (UART/MCU-чип/таймер/cpufreq) → HW-bring-up-подфаза (нужна плата RK3588).

Следующее: v0.5 полный shell (живой weston-shell; замкнёт thermal-UX-рендер) — поверх v0.2. HW-bring-up (MCU/supercap, реальный UART/cpufreq/B09-чип, тепловой/перф-вердикт) — отдельной подфазой при появлении платы.

CI: GitHub-Actions-конфиг удалён (его ловит Gitea). Гейт — локальный just ci. CI на Gitea — решение позже.

Карта документации

• Архитектура/процессы/шина: docs/architecture.md · стек: docs/tech-stack.md · принципы (13): docs/principles.md.
• Контракты (docs/contracts/): ipc · data-model · security-privacy · plugin-sdk · hardware · safety · performance · design-system.
• Домены (docs/domains/): A base-system · B power-lifecycle · C shell-ux · D assistant · E vehicle-data · F plugin-host · G…L.
• План: docs/capability-catalog.md (170 функций, ID <буква><NN>) · docs/roadmap.md (вехи v0.1…v4.5) + docs/roadmap.html.

Решения-🟡 (всплывут по ходу — НЕ блокеры старта)

A01 Armbian/Debian vs Yocto, A02 f2fs vs ext4 — на сборке прод-образа (dev использует Lima Ubuntu). B08/B09 MCU vs supercap-only — на v0.4 (вероятно нужна аппаратная проверка). Полный реестр — docs/roadmap.md «Риск-реестр».

Гочи

• §-якоря в доках = номера РАЗДЕЛОВ, не строк.
• Adversarial-ревью через Workflow: НЕ ставить сырые backticks в template-literal промптах агентов (закрывают строку, валят скрипт) — код-идентификаторы в одинарных кавычках.