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 промптах агентов
  (закрывают строку, валят скрипт) — код-идентификаторы в одинарных кавычках.