From 7d904eff54026ef2fbf7d9c3ff895f6216388869 Mon Sep 17 00:00:00 2001 From: xodapi <4956501+xodapi@users.noreply.github.com> Date: Sun, 5 Jul 2026 09:39:32 +0700 Subject: [PATCH] docs(plan): publish final project plan v3 (closes #159) --- docs/PROJECT_PLAN_FINAL.ru.md | 212 +++++++++++++++++++++++++++++++ docs/PROJECT_PLAN_FINAL_v2.ru.md | 153 ++++++++++++++++++++++ docs/PROJECT_PLAN_FINAL_v3.ru.md | 165 ++++++++++++++++++++++++ 3 files changed, 530 insertions(+) create mode 100644 docs/PROJECT_PLAN_FINAL.ru.md create mode 100644 docs/PROJECT_PLAN_FINAL_v2.ru.md create mode 100644 docs/PROJECT_PLAN_FINAL_v3.ru.md diff --git a/docs/PROJECT_PLAN_FINAL.ru.md b/docs/PROJECT_PLAN_FINAL.ru.md new file mode 100644 index 0000000..f6deefe --- /dev/null +++ b/docs/PROJECT_PLAN_FINAL.ru.md @@ -0,0 +1,212 @@ +# xodapi/vimit + live-core — Финальный план проекта + +> **Статус:** историческая версия. Заменена актуальным планом +> `PROJECT_PLAN_FINAL_v3.ru.md`. + +**Статус:** Планирование завершено. Документ фиксирует итоговые решения +и порядок работ для передачи агентам (Droid Factory / Claude Code). +Дальнейшие изменения — только по факту реализации, не новые раунды +исследования. + +**Дата фиксации:** 2 июля 2026. + +--- + +## 0. Что уже сделано (не трогать, не пересматривать) + +- **vimit v0.6.2+**: CLI/TUI/GUI, floating overlay, living creature + визуализация (шипы/органика skins), self-update, tray, desktop + notifications, demo/mock режимы, daily limit tracking, offline + indicator, Android APK в разработке (Issue с API key settings). +- **Governance**: `AGENTS.md` + `MULTI-AGENT.md` — рабочий процесс + через GitHub Issues, файловые зоны, порядок для параллельных агентов. + Уже применяется, работает. +- **live-core**: полная архитектурная спецификация готова — + `LIVE_CORE_FULL_SPEC.ru.md` (модули, cyberimmunity-модель, ratchet-gate, + 13 диагностических вопросов, научное обоснование). Отдельно — + `LIVE_CORE_SECURITY_AUDIT.ru.md` для LLM-ревью готового кода. +- **Roadmap-документы**: `MOBILE_ROADMAP.ru.md` (Android/iOS перспектива + для самого vimit, не live-core), `SUBMISSION_simple.ru.md` (конкурсная + подача, уже отправлена). + +--- + +## 1. Два независимых трека работ + +Треки не блокируют друг друга — разные репозитории/зоны, можно вести +параллельно разными агентами. + +### Трек A — vimit (существующий репозиторий, продолжение) + +### Трек B — live-core (новый репозиторий/крейт, с нуля по спецификации) + +--- + +## 2. Трек A: vimit — оставшиеся задачи + +### A.1 Немедленно (административное, 5 минут, сделать вручную) + +```bash +gh repo edit xodapi/vimit \ + --description "Living quota monitor for VibeMode — your remaining credits, visualized as a creature that reacts to your usage" +``` +Repo description и topics всё ещё содержат устаревшее "NeuroGate" — +поправить сейчас, это не требует агента. + +### A.2 В работе (агент, уже начато) + +- **Android APK** (`feat(android): add API key settings for test APK`) + — довести до готового состояния. Критерий: APK устанавливается, + принимает API-ключ через Android-friendly UI, сохраняет локально, + не выводит в лог. + +### A.3 Следующий приоритет после Android APK + +- Скриншоты/демо-материалы обновить под текущую версию (living + creature, overlay) — старые демо из конкурсной подачи устарели. +- Ревью открытых Issues в репозитории — закрыть неактуальные, + оставить только то, что реально в работе (после конкурса накопилось + много Issues, часть уже неактуальна). + +### A.4 Явно не трогать сейчас + +- Интеграция `live-core` в vimit — отдельная задача **после** + стабилизации live-core (см. Трек B, раздел 7 критериев приёмки). +- 3D/Bevy-визуализация зверька — задокументирована в ROADMAP как + перспектива, не текущая работа. +- iOS-порт — статус "tech-preview" у самого Slint, не готов для + продакшена. + +--- + +## 3. Трек B: live-core — порядок реализации + +Полная спецификация: `LIVE_CORE_FULL_SPEC.ru.md`. Ниже — порядок, +в котором агент должен идти по ней, чтобы не утонуть в объёме документа. + +### B.1 Порядок модулей (зависимости учтены) + +``` +1. Clock + Instant (раздел 2.4a) — фундамент, всё остальное + зависит от него +2. rolling_buffer (раздел 2.1) — независим, можно параллельно с (1) +3. threshold (раздел 2.2) — независим, можно параллельно +4. offline_tracker (раздел 2.4) — зависит от (1) +5. state_machine + StateHistory (2.3) — зависит от (1) для History +6. Observer trait (раздел 2.6) — инжектируется во все выше, + добавляется последним как + сквозной слой +7. Concurrency/Send+Sync policy (2.7) — проверяется после (1)-(6), + не отдельный модуль, а аудит + уже написанного +8. poller (раздел 2.5, feature=async) — опционально, последним, + зависит от (1) и (4) +``` + +### B.2 Формат передачи агенту + +Не отдавать всю спецификацию одним Issue — она рассчитана как +reference-документ, не как единственная задача. Разбить на Issues +по модулям из B.1, каждый со ссылкой на соответствующий раздел +спецификации и с explicit critical requirements: + +``` +Issue: live-core — module 1: Clock + Instant + +См. LIVE_CORE_FULL_SPEC.ru.md, раздел 2.4a. + +Обязательно: +- trait Clock { fn now(&self) -> Instant } +- Instant — newtype, не реэкспорт std::time::Instant +- Instant::duration_since() -> core::time::Duration +- #[cfg(feature = "std")] impl Clock for StdClock +- Учесть Embassy как вероятный будущий embedded-consumer + (см. экосистемное уточнение в том же разделе спецификации) + +Критерий приёмки: cargo test --locked проходит, включая edge case +пустого/единственного значения. no_std-сборка (--no-default-features) +компилируется без Clock::StdClock (только trait). + +zone: live-core/clock +``` + +Аналогично для остальных модулей — каждый Issue самодостаточен, +ссылается на конкретный раздел, не требует от агента читать весь +документ целиком для одной задачи. + +### B.3 Что проверяется на каждом Issue (сквозные требования) + +Не повторять в каждом Issue текстом — один раз зафиксировать как +общее правило в `AGENTS.md` живого репозитория `live-core`: + +- `cargo test --locked` +- `cargo clippy --all-targets -- -D warnings` +- `cargo fmt --check` +- Ratchet-gate: `cargo bench -- --save-baseline main` — обязателен + для rolling_buffer, threshold, state_machine, offline_tracker + (раздел 5 спецификации, конкретный список бенчмарков) +- Naming discipline: нет `client`/`http`/`connection` в публичных + сигнатурах (раздел 3.2) +- Каждый `unsafe` (если появится) — обоснован по таксономии 19 SP + (раздел 3, Решение 4) + +### B.4 Критерий готовности live-core v1 (весь трек B) + +Из раздела 7 спецификации, без изменений: +- `cargo test` + `cargo bench` работают +- Пример в `examples/`, использующий 4 обязательных модуля + (rolling_buffer, threshold, state_machine, offline_tracker) +- `cargo clippy` чисто +- README с Security principle (раздел 8 спецификации, готовый текст) +- Отчёт "сколько строк кода из vimit можно было бы заменить" + (оценочно, не обязательная реализация замены) + +**Что НЕ входит в v1** (полный список — раздел 7 спецификации): +интеграция в vimit, Slint/ratatui-зависимости, embedded/носимая +интеграция, `derive`-макрос для StateMachine, `tokio`/`backoff` +как обязательные зависимости, `serde`-сериализация буферов. + +--- + +## 4. Использование мультиагентной координации + +Оба трека используют уже отработанный паттерн из `AGENTS.md`/ +`MULTI-AGENT.md`: + +- Каждый Issue — своя ветка `issue-N-slug` +- Файловые зоны (`zone:vimit-android`, `zone:live-core-clock`, + `zone:live-core-buffer` и т.д.) — не пересекаются, агенты работают + параллельно без конфликтов +- `Cargo.toml`/`Cargo.lock` — только один активный Issue одновременно + на репозиторий (правило из MULTI-AGENT.md уже применимо к live-core + как новому репозиторию) + +--- + +## 5. Порядок действий прямо сейчас + +1. Поправить repo description vimit (раздел A.1) — вручную, 5 минут. +2. Создать репозиторий `xodapi/live-core`, положить туда + `LIVE_CORE_FULL_SPEC.ru.md` и `LIVE_CORE_SECURITY_AUDIT.ru.md` + как reference-документы (не как единственный Issue). +3. Скопировать `AGENTS.md`/`MULTI-AGENT.md` в новый репозиторий, + адаптировать раздел "Контекст проекта" под live-core (структура + модулей вместо структуры vimit). +4. Создать 8 Issues по модулям из B.1, в указанном порядке + приоритета, с телом по шаблону из B.2. +5. Продолжить Android APK для vimit параллельно — не блокирует + live-core, разные репозитории. +6. Не создавать новых research-Issues по live-core до тех пор, пока + v1 (раздел B.4) не будет закрыт целиком — дальнейшие + архитектурные вопросы решаются по факту реализации, не заранее. + +--- + +## 6. Финальное напоминание себе (зафиксировано по итогам обсуждения) + +Спецификация live-core прошла три независимых раунда технического +ревью (Grok, Deepseek дважды), два научных источника (PermRust, LBAC), +эмпирическое исследование unsafe-безопасности (19 Safety Properties) +и финальную сверку с состоянием экосистемы (Embassy, Slint) на май +2026. Дальнейшее расширение объёма документа даёт убывающую отдачу — +следующий шаг с наибольшей ценностью теперь код, не текст. diff --git a/docs/PROJECT_PLAN_FINAL_v2.ru.md b/docs/PROJECT_PLAN_FINAL_v2.ru.md new file mode 100644 index 0000000..9e32fac --- /dev/null +++ b/docs/PROJECT_PLAN_FINAL_v2.ru.md @@ -0,0 +1,153 @@ +# xodapi/vimit + live-core — Итоговый план (обновлённая версия) + +> **Статус:** историческая версия. Заменена актуальным планом +> `PROJECT_PLAN_FINAL_v3.ru.md`. + +**Статус:** Финальная консолидация. Заменяет `PROJECT_PLAN_FINAL.ru.md` +как актуальный источник правды. Дальше — выполнение, не новое +планирование. + +**Дата:** 2 июля 2026. + +--- + +## 0. Что уже сделано (не пересматривать) + +- vimit v0.6.2+: CLI/TUI/GUI, overlay, living creature, self-update, + tray, notifications, demo/mock, daily limit, offline indicator. +- Конкурс «Новое звено»: **3 место, $30**. +- `AGENTS.md` + `MULTI-AGENT.md` — рабочий процесс через Issues и + файловые зоны, применяется на практике. +- `live-core` — полная архитектурная спецификация готова + (`LIVE_CORE_FULL_SPEC.ru.md`), прошла три раунда ревью (Grok, + Deepseek×2), подкреплена научными источниками (PermRust, LBAC, + эмпирика 19 Safety Properties), сверена с экосистемой (Embassy, + Slint 1.16) на май 2026. +- `LIVE_CORE_SECURITY_AUDIT.ru.md` — чек-лист для LLM-ревью кода. +- `MOBILE_ROADMAP.ru.md` — перспектива Android/iOS для vimit. + +--- + +## 1. Немедленные административные правки (вручную, 10 минут) + +Не сделаны, несмотря на прошлые договорённости — сделать сейчас: + +```bash +gh repo edit xodapi/vimit \ + --description "Living quota monitor for VibeMode — your remaining credits, visualized as a creature that reacts to your usage" +``` + +В README.md/README.ru.md заменить вступительный абзац на формулировку +про living creature (черновик уже был согласован ранее в переписке) — +текущий текст всё ещё говорит только "single native binary to monitor +VibeMode quota", без упоминания overlay/существа. + +--- + +## 2. Срочное расследование — расхождение в Issues + +**Обнаружено:** агент ранее отчитался о закрытии #28 (naming debt) и +#29 (Windows install path), но оба всё ещё числятся **Open** в +репозитории. Причина неизвестна — нужно установить точно, не +закрывать повторно вслепую. + +**Действие:** отдать агенту задачу с использованием `claude-tap` +(локальный прокси-перехватчик трафика Claude Code/Codex CLI) — +прогнать сессию повторного закрытия через `claude-tap --tap-host +127.0.0.1`, найти в трейсе реальный tool call `gh issue close`, +установить: неверный номер / неверный repo / команда упала / +auth истёк / что-то иное. Подробное задание уже сформулировано в +переписке, готово к отправке агенту как отдельный Issue. + +**Попутное правило в `AGENTS.md`:** после любого `gh issue close` — +обязательная проверка `gh issue view N --json state`, не полагаться +на то, что команда "должна была сработать". + +--- + +## 3. Трек A — vimit, оставшиеся задачи + +| Приоритет | Задача | Статус | +|---|---|---| +| Высокий | Расследование #28/#29 через claude-tap | новое, см. раздел 2 | +| Высокий | Android APK (API key settings) | в работе | +| Высокий | Repo description/README апдейт | см. раздел 1 | +| Средний | Аудит всех 22 открытых Issues — закрыть неактуальные | не начато | +| Средний | Демо-материалы под текущую версию (creature, overlay) | не начато | +| Низкий | iOS через GitHub Actions macOS-раннер | ROADMAP, не начато | + +**Критерий готовности Android APK v1** (зафиксирован ранее): +установка на реальное устройство, ключ не в logcat, live-режим +работает с реальным API, экраны читаемы на типичном экране 6"+. + +--- + +## 4. Трек B — live-core, порядок реализации + +Без изменений относительно предыдущей версии плана. Восемь модулей +в порядке зависимостей (`Clock` → `rolling_buffer`/`threshold` +параллельно → `offline_tracker` → `state_machine` → `Observer` → +Send/Sync-аудит → `poller` последним). Каждый — отдельный Issue со +ссылкой на конкретный раздел `LIVE_CORE_FULL_SPEC.ru.md`, не вся +спецификация одним заданием. + +**Следующий конкретный шаг:** создать репозиторий `xodapi/live-core`, +перенести туда оба спецификационных документа как reference (не как +единственный Issue), скопировать и адаптировать `AGENTS.md`/ +`MULTI-AGENT.md`, создать первые Issues по модулям 1-3 (Clock, +rolling_buffer, threshold — независимы друг от друга, можно +параллельно). + +**Потенциальный грант:** Sentient Foundation Open Source AGI Grant +Program (Трек А, без equity) — `live-core` хорошо совпадает по +формулировке "инфраструктура доверия для автономных агентов", +особенно с учётом cyberimmunity-архитектуры. Слабое место — критерий +"good for humanity/underserved markets" (это инфраструктура для +разработчиков, не прямой продукт для уязвимых групп) — требует +честного позиционирования в заявке. **Условие подачи:** нужен хотя бы +рабочий v1 (раздел 7 спецификации) — заявка с одной спецификацией без +кода будет выглядеть как обещание, не как репозиторий. + +--- + +## 5. Явно отложено в ROADMAP — не начинать сейчас + +Зафиксировано по итогам всей сессии, чтобы не открывать заново: + +- **Rig (rig-core)** — фреймворк для LLM-агентов, не нужен ни vimit, + ни live-core (они не вызывают LLM). Применим только для гипотетического + будущего "умного" CLI-оркестратора с LLM-выбором задач для агентов — + не текущая надобность. +- **jj (Jujutsu) + git-cliff** — devtools-миссия, независимая от + live-core/vimit, пилотировать отдельно когда будет время, не сейчас. +- **3D/Bevy-визуализация зверька** — задокументировано как крупный + будущий этап, требует полноценной WGPU-интеграции. +- **iOS-порт** — требует macOS/Xcode, решение через GitHub Actions + macOS-раннер намечено, не начато. +- **Percentile/median в rolling_buffer, derive-макрос StateMachine, + serde-сериализация** — все явно помечены в спецификации live-core + как v2, не блокируют v1. + +--- + +## 6. Порядок действий на сегодня — если нужен один короткий список + +1. Поправить repo description (раздел 1) — 2 минуты. +2. Отдать агенту Issue про claude-tap-расследование (раздел 2). +3. Проверить прогресс Android APK Issue. +4. Если время останется — начать создание репозитория `xodapi/live-core` + и первые три Issues (Clock, rolling_buffer, threshold). + +Всё остальное из раздела 5 — сознательно не трогать сегодня. + +--- + +## 7. Личное примечание + +Работа последних дней — по сути диалог с накопленным опытом множества +инженеров и исследователей через разные модели (Grok, Deepseek, +Perplexity, научные статьи с arXiv, сам Claude) — каждая добавляла +свой срез экспертизы: архитектурную строгость, эмпирические данные +по CVE, свежие данные экосистемы. Синтез этого в `live-core` — редкий +случай, когда процесс планирования сам по себе стал содержательным +результатом, не только подготовкой к нему. diff --git a/docs/PROJECT_PLAN_FINAL_v3.ru.md b/docs/PROJECT_PLAN_FINAL_v3.ru.md new file mode 100644 index 0000000..dfb7c3c --- /dev/null +++ b/docs/PROJECT_PLAN_FINAL_v3.ru.md @@ -0,0 +1,165 @@ +# xodapi/vimit + live-core — Итоговый план (v3) + +**Статус:** Актуальный source of truth на 5 июля 2026. +Заменяет `PROJECT_PLAN_FINAL.ru.md` (v1) и `PROJECT_PLAN_FINAL_v2.ru.md` +(v2) — оба сохраняются в `docs/` как историческая основа, не как +текущий план. v2 успел устареть быстрее, чем предполагалось на +момент написания — проект продвинулся значительно дальше между +2 и 5 июля. + +--- + +## 0. Что изменилось относительно v2 (коротко) + +- Расследование #28/#29 через claude-tap — **больше не нужно**. + Оба issue закрыты 28 июня 2026, расхождение было временным + артефактом, не системной проблемой. Раздел удалён из плана. +- Android APK — прошёл значительно дальше состояния "API key + settings в работе". Ниже — полный актуальный список сделанного. +- live-core — остаётся отдельным треком, но явно **после** + стабилизации Android, не параллельно. В v2 трек B шёл сразу + вторым приоритетом — это скорректировано. + +--- + +## 1. Governance — без изменений + +`AGENTS.md` — главный источник правды по процессу. Любое изменение +только через Issue с label `agent`, отдельная ветка `issue-N-slug`, +проверки, PR. Не коммитить `.env`, ключи, keystore, пароли. Работать +в отдельном `git worktree` под issue, если основной worktree грязный. + +--- + +## 2. Android/core — что уже сделано (не пересматривать, не мержить заново) + +**Инфраструктура:** +- Android minimal APK entrypoint +- Android API key settings для test APK +- Android APK artifact/manual test workflow +- Android manifest/library checks +- `INTERNET` permission +- `POST_NOTIFICATIONS` в manifest metadata +- `android-gui` feature с нужной Android/JNI связкой +- Android touch-friendly layout +- Android notification/vibration bridge +- Android foreground polling plan (в docs) +- Android bridge вынесен из `src/lib.rs` в `src/android.rs` + +**Общая логика:** +- Shared dashboard refresh model для desktop/Android +- Core pulse model +- Stuck token burn detector +- Android Vimichi alarm state для runaway burn +- Cache TTL и `--no-cache` поведение +- Stale cache/offline API семантика выровнена в CLI/TUI/JSON +- Lightweight CI annotations для threshold breaches +- MCP stdio server для IDE integration +- GUI/TUI/core refactor задачи закрыты + +**Закрытые PR/Issues (для справки, не трогать):** +- #150/#157 — configurable cache TTL, explicit cache bypass +- #151/#156 — stale/offline semantics +- #152/#155 — CI annotation mode +- #154 — already resolved in main +- #101/#158 — docs про VIBEMODE_API_KEY на Android и безопасность +- #99 — already resolved +- #100/#102/#104 — старый Android stacked PR stack, закрыты как + obsolete. **Не пытаться оживлять или мержить.** + +--- + +## 3. Актуальный next queue — единственный источник приоритета + +### 3.1 #113 — feat(android): request notification permission at runtime +**Главная текущая задача.** Android 13+ требует runtime-запрос +разрешения `POST_NOTIFICATIONS` — сейчас оно только в manifest, +без runtime-диалога. + +Не трогать: API key handling, `.env`, desktop notifications (это +zone других задач). + +Проверки перед PR: +```bash +cargo test --locked +cargo clippy --all-targets -- -D warnings +cargo fmt --check +cargo apk build --features android-gui --target aarch64-linux-android --lib +``` + +### 3.2 #103 — feat(android): show Vimichi mascot on dashboard +Старый PR (был поверх #100) закрыт как obsolete, но сам issue +актуален — нужен **чистый redo от свежего main**, не восстановление +старой ветки. + +- Использовать существующий `PulseOrganism` (уже реализован для + desktop overlay — переиспользовать, не писать заново) +- Работать с текущими `src/android.rs` и `ui/app.slint` — **не** со + старым `src/lib.rs`, откуда Android-логика уже вынесена +- **Осторожно:** может конфликтовать с #113, если оба трогают + `ui/app.slint` — проверить, кто идёт первым, второй агент делает + rebase после merge первого + +### 3.3 #105 — feat(android): agent activity pulse and live token chart +**Blocked.** Не брать сейчас. Пересмотреть после того, как #113 и +#103 смержены — вероятно оба зависят от структуры, которую они +меняют в `ui/app.slint`/`src/android.rs`. + +### 3.4 #129 — chore(build): resolve Windows vimit.pdb filename collision +**Blocked.** Не брать. + +--- + +## 4. Порядок работы прямо сейчас + +1. **#113** (notification permission) — брать первым, наименее + рискованная зона конфликта. +2. **#103** (Vimichi mascot) — брать после #113 смержен, или + параллельно если явно подтверждено что `ui/app.slint`-изменения + не пересекаются построчно. +3. **#105** — переоценить только после обоих выше, снять `blocked` + вручную, не агентом. +4. **#129** — не трогать, ждёт отдельного решения по Windows build. + +--- + +## 5. live-core — статус трека + +Полная спецификация готова (`LIVE_CORE_FULL_SPEC.ru.md`, +`LIVE_CORE_SECURITY_AUDIT.ru.md`) — архитектура не пересматривается. + +**Явное решение:** live-core — **следующий трек после стабилизации +Android** (после закрытия #113, #103, разблокировки и оценки #105), +не параллельный трек прямо сейчас. Причина — ограниченное внимание +координатора лучше сфокусировать на одном активном треке за раз, +даже если технически репозитории независимы. + +Когда Android-очередь (раздел 3) закрыта — вернуться к разделу +"Трек B" из `PROJECT_PLAN_FINAL_v2.ru.md` (создание `xodapi/live-core`, +первые Issues по модулям Clock/rolling_buffer/threshold) без +изменений в самой архитектуре. + +--- + +## 6. Явно отложено — не открывать заново + +Без изменений относительно v2: Rig, jj+git-cliff, 3D/Bevy-визуализация, +iOS-порт, percentile/median в rolling_buffer, derive-макрос +StateMachine, serde-сериализация буферов. Все — future work, +не текущая работа. + +**Дополнительно к списку:** не открывать новых research-направлений +до закрытия текущей Android-очереди — правило зафиксировано отдельно +по итогам ревью этого плана. + +--- + +## 7. Правило для будущих обновлений плана + +Каждое следующее обновление плана (v4 и далее) должно: +- явно указывать, что изменилось относительно предыдущей версии + (раздел 0 по образцу этого документа), не переписывать всё заново +- сверяться с реальным состоянием GitHub Issues перед фиксацией + "next queue", не полагаться на память предыдущей версии плана +- предыдущие версии не удалять, хранить в `docs/` с пометкой + superseded — история решений имеет ценность сама по себе