# IMPLEMENTATION PLAN

Этот документ описывает рекомендуемый порядок реализации `ducklm` от пустого репозитория до рабочего локального runtime с тестовым веб-чатом.

План опирается на [`TASK_3.md`](/home/mirivlad/git/ducklm/TASK_3.md) и [`ARCHITECTURE.md`](/home/mirivlad/git/ducklm/ARCHITECTURE.md).

## 1. Goal

Собрать систему по этапам так, чтобы после каждого этапа оставался рабочий, проверяемый инкремент, а не набор недоделанных слоёв.

Главный принцип:

- сначала каркас и контракты
- потом runtime core
- потом execution path
- потом memory / critic / recovery
- потом удобные интерфейсы проверки

## 2. Milestones Overview

1. Project skeleton and typed contracts
2. Config system and dependency wiring
3. Runtime loop skeleton
4. Event bus and event store
5. State persistence and checkpointing
6. Context builder and orchestrator adapter
7. Router and directive flow
8. Execution engine and task graph
9. Permission system and tool sandbox
10. MVP tools
11. FastAPI API and health surface
12. Web chat test client
13. Coder integration
14. Critic integration
15. Memory system
16. Memory write policy
17. Retry, recovery, replay
18. CLI and operator utilities
19. Hardening and tests

## 3. Detailed Stages

### Stage 1. Project Skeleton and Typed Contracts

Цель:

- создать структуру директорий
- завести базовые модели данных
- убрать двусмысленность интерфейсов между слоями

Сделать:

- создать `app/`, `config/`, `data/`, `tests/`
- добавить core contracts:
  - `UserTask`
  - `PlanStep`
  - `ToolCall`
  - `ToolResult`
  - `CriticScore`
  - `RuntimeEvent`
  - `TaskCheckpoint`
  - `ExecutionDirective`

Результат этапа:

- проект компилируется
- типы и схемы являются source of truth для остальных модулей

Проверка:

- unit tests на валидацию схем

### Stage 2. Config System and Dependency Wiring

Цель:

- вынести runtime behavior в конфиги
- зафиксировать единый способ загрузки настроек

Сделать:

- `config/models.json`
- `config/prompts.json`
- `config/permissions.json`
- `config/runtime.json`
- loader и typed config models

Результат этапа:

- runtime можно запускать с консистентной конфигурацией

Проверка:

- config load smoke test

### Stage 3. Runtime Loop Skeleton

Цель:

- создать heart of system без полной бизнес-логики

Сделать:

- `runtime_loop.py`
- `runtime_controller.py`
- минимальный lifecycle:
  - receive task
  - create state
  - build empty context
  - emit initial event
  - return placeholder directive/result

Результат этапа:

- есть центральный control loop
- остальные слои начинают подстраиваться под него, а не наоборот

Проверка:

- smoke test на прохождение задачи через loop skeleton

### Stage 4. Event Bus and Event Store

Цель:

- создать внутреннюю event backbone

Сделать:

- `event_bus.py`
- `event_types.py`
- `event_store.py`
- monotonic sequence per task
- append-only storage
- базовый replay reader

Результат этапа:

- у каждой задачи есть воспроизводимая хронология

Проверка:

- event ordering tests
- dedup/idempotency tests

### Stage 5. State Persistence and Checkpointing

Цель:

- убрать зависимость task lifecycle от памяти процесса

Сделать:

- `task_state_store.py`
- `checkpoint_store.py`
- SQLite backend
- checkpoint after critical transitions
- resume loading primitives

Результат этапа:

- runtime готов к recovery после падения

Проверка:

- save/load checkpoint tests

### Stage 6. Context Builder and Orchestrator Adapter

Цель:

- зафиксировать правильный вход в reasoning path

Сделать:

- `context_builder.py`
- token-budget-aware assembly
- orchestrator adapter abstraction
- planning mode / orchestration mode interfaces

Результат этапа:

- все будущие вызовы reasoning model идут через один нормализованный путь

Проверка:

- tests на context assembly priorities

### Stage 7. Router and Directive Flow

Цель:

- зафиксировать router как pure decision layer

Сделать:

- `router.py`
- `state + context -> ExecutionDirective`
- no side effects
- routing rules for:
  - retrieval needed
  - planning needed
  - permission needed
  - critic needed

Результат этапа:

- runtime loop применяет решения, а не изобретает их сам

Проверка:

- unit tests на routing decisions

### Stage 8. Execution Engine and Task Graph

Цель:

- получить управляемое исполнение шагов, а не “вызовы по месту”

Сделать:

- `execution_engine.py`
- `execution_scheduler.py`
- task graph validation
- sequential DAG scheduler
- adapters for tool/coder execution

Результат этапа:

- runtime может исполнять direct action и multi-step plans

Проверка:

- task graph validation tests
- step ordering tests

### Stage 9. Permission System and Tool Sandbox

Цель:

- не дать runtime выполнять опасные действия напрямую

Сделать:

- permission rules
- persistent approval store
- shell safety classifier
- sandbox execution adapter
- timeout/resource/path restrictions

Результат этапа:

- опасные команды требуют policy decision до запуска

Проверка:

- permission flow tests
- sandbox boundary smoke tests

### Stage 10. MVP Tools

Цель:

- сделать минимально полезный execution path

Сделать:

- `shell_exec`
- `file_read`
- `file_write`
- unified tool registry
- unified `ToolResult`

Результат этапа:

- runtime уже может выполнять реальные локальные задачи

Проверка:

- integration tests для трёх базовых tools

### Stage 11. FastAPI API and Health Surface

Цель:

- открыть runtime наружу через стабильный backend interface

Сделать:

- `POST /chat`
- `WS /stream`
- `GET /health`
- базовый request/response models
- error handling

Результат этапа:

- систему уже можно дергать из внешнего клиента

Проверка:

- API smoke tests

### Stage 12. Web Chat Test Client

Цель:

- получить быстрый способ руками проверить поведение всей системы через браузер

Сделать:

- минимальный локальный веб-чат
- простую страницу с:
  - вводом задачи
  - окном сообщений
  - панелью streaming events
  - индикацией permission requests
  - отображением final result
- подключение к `POST /chat` и `WS /stream`

Требования:

- это не production UI
- это не отдельный продуктовый frontend
- это thin test client для ручной проверки runtime

Лучше всего разместить как:

- `app/api/static/` или отдельный `web/` модуль с минимальным стеком

Результат этапа:

- можно открыть браузер и увидеть, как runtime планирует, исполняет шаги и стримит события

Проверка:

- ручной e2e smoke test через браузер

### Stage 13. Coder Integration

Цель:

- подключить отдельную coding model без смешивания ролей

Сделать:

- `core/coder.py`
- `generate_code`
- `fix_code`
- `refactor_code`
- structured coder result

Результат этапа:

- runtime может делегировать кодогенерацию специализированной модели

Проверка:

- tests на coder request/response flow

### Stage 14. Critic Integration

Цель:

- получить formal evaluation layer после tools/coder

Сделать:

- critic adapter
- `CriticScore`
- fallback policy when critic unavailable

Результат этапа:

- результаты можно оценивать единообразно

Проверка:

- critic scoring contract tests

### Stage 15. Memory System

Цель:

- добавить долговременную retrieval memory

Сделать:

- SQLite metadata store
- FAISS/hnswlib vector index
- insert/search/delete/reindex
- embedding versioning

Результат этапа:

- runtime получает semantic retrieval вместо контекста “только текущая задача”

Проверка:

- memory insert/search tests

### Stage 16. Memory Write Policy

Цель:

- не допустить хаотичной записи всего подряд

Сделать:

- deterministic write policy
- threshold model
- dedup / merge rules
- conflict handling

Результат этапа:

- память пополняется контролируемо, а не по одному score cutoff

Проверка:

- memory policy decision tests

### Stage 17. Retry, Recovery, Replay

Цель:

- довести runtime до устойчивого long-running поведения

Сделать:

- planner retry
- tool retry for allowed cases
- partial failure recovery
- replay path from event store
- resume from checkpoint

Результат этапа:

- система может переживать ошибки без полной потери исполнения

Проверка:

- recovery smoke tests
- replay tests

### Stage 18. CLI and Operator Utilities

Цель:

- дать локальный интерфейс помимо API/веб-чата

Сделать:

- send task
- show result
- follow events
- memory search
- replay task history

Результат этапа:

- разработчик может проверять runtime без браузера

Проверка:

- CLI smoke tests

### Stage 19. Hardening and Tests

Цель:

- довести проект до инженерно приемлемого состояния

Сделать:

- structured logging refinement
- failure-path tests
- concurrency edge cases
- docs refresh
- cleanup of temporary stubs

Результат этапа:

- проект становится пригодным для реальной итеративной разработки

Проверка:

- full critical-path smoke suite

## 4. Recommended First Working Demo

Первый нормальный demo checkpoint должен быть на этапе `Stage 12`.

Что должно работать к этому моменту:

- браузерный веб-чат открывается локально
- пользователь отправляет задачу
- runtime принимает task
- событие начала работы видно в UI
- если нужен plan, это видно в events panel
- tool execution видно в events panel
- final response возвращается в чат

На этом этапе memory, critic и recovery ещё могут быть частично stubbed, но:

- runtime loop
- event bus
- state persistence
- router
- execution engine
- permissions
- базовые tools
- API
- web chat

должны быть уже реальными.

## 5. Order Rationale

Почему веб-чат не в самом конце:

- он нужен как live inspection surface для runtime
- через него проще проверять streaming, permissions и event ordering
- он быстрее выявляет архитектурные проблемы, чем голые unit tests

Но веб-чат ставится только после:

- runtime core
- event bus
- persistence
- basic execution path
- API

Иначе он станет красивой оболочкой над несуществующей системой.