[feat] add tasks

AGENTS.md

@@ -41,7 +41,7 @@
 - Keep HTTP models and middleware inside `adapter/http/fastapi/`
 
 ## Workflow
-- Use `tasks.md` for planning
+- Use dir `tasks/` for planning
 - Do not use Beads
 - Do not use `bd`
 - Use `uv` for Python commands and dependency management

tasks/roadmap.md

@@ -0,0 +1,279 @@
+# Roadmap: workspace/chat/files + artifacts
+
+## Цель
+
+Следующий продуктовый приоритет для `master-service`:
+1. управление `workspace` / `chat` / `chat files`
+2. хранение и выдача `artifacts`
+
+Идея этапа: превратить текущий sandbox MVP в storage-centric control plane, где sandbox работает поверх явных пользовательских данных, а не только поверх `chat_id`.
+
+## Что считаем в scope этого roadmap
+
+- workspace metadata
+- chat metadata и chat directories
+- `history.md` рядом с чатом
+- upload/list/download/delete/clear для chat files
+- quota / usage accounting
+- artifact metadata
+- object storage adapter для artifacts
+- delivery / mark-for-delete flow для artifacts
+- интеграция storage model с текущим sandbox lifecycle
+
+## Что пока вне scope
+
+- полноценный auth/access control
+- access lease и WebSocket handoff
+- multi-node orchestration как отдельный эпик
+- full retention engine для workspace/account lifecycle
+- внешние messenger integrations
+
+## Зафиксированные продуктовые решения
+
+- trusted caller передает `user_id: UUID`
+- в v1 один `Workspace` на одного `User`
+- metadata adapters пока делаем `in-memory`
+- chat history в v1 хранится в `history.md`
+- chat files отдаем через master: metadata API + download endpoint
+- soft quota 10 GB блокирует quota-relevant write-path операции, но не делает hard reservation
+- chat create сам по себе не блокируется quota check, пока не появляется значимый file/artifact payload
+- delete в v1 — hard delete; chat delete запрещен при active sandbox
+- artifact delivery подтверждается явным ack
+- artifact blob отдается через presigned URL, metadata — через master
+- object storage layout: один bucket на environment + prefixes
+- artifact states: `created`, `stored`, `delivered`, `delivery_failed`, `marked_for_delete`, `deleted`
+- artifact retention: после ack -> `marked_for_delete` -> async cleanup; без ack действует отдельный TTL
+
+## Принципы выполнения
+
+- Clean Architecture и dependency direction сохраняются
+- filesystem и object storage живут только во внешних adapter/repository слоях
+- `domain/` и `usecase/` не знают про FastAPI, Docker, OpenTelemetry, env
+- один delivery slice = одна атомарная задача = один commit
+- архитектурные развилки сначала фиксируются кратким ADR-lite в `docs/`
+
+## Легенда исполнителей
+
+- `primary-agent` — архитектура, ADR, domain/contracts, финальная сборка решений
+- `junior` — простые in-memory adapters и базовые unit-level задачи
+- `junior+opus` — usecase/adapter/API slices со средним уровнем связности
+- `test-engineer` — regression и integration test packs
+- `code-reviewer` — review-only этапы
+
+---
+
+## Phase 0. Design checkpoints
+
+### R00. ADR: storage source of truth
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Зачем:** определить, что является source of truth для `Workspace`, `Chat`, `ChatFile`, `Artifact`
+- **Нужно решить:** как устроен in-memory-first этап, как metadata связаны с filesystem paths, как sandbox получает path текущего chat
+- **Выход:** ADR-lite + список сущностей и ownership boundaries
+
+### R01. ADR: artifact lifecycle
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Зачем:** зафиксировать states и delivery contract для artifact flow
+- **Нужно решить:** `created -> stored -> delivered -> delivery_failed -> marked_for_delete -> deleted`
+- **Выход:** ADR-lite + минимальный state machine
+
+### R02. ADR: chat history policy
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Зачем:** зафиксировать, как `history.md` соотносится с metadata чата
+- **Нужно решить:** кто создает файл, кто пишет initial header, как читать/обновлять metadata без парсинга файла
+- **Выход:** ADR-lite + правила sync между metadata и history file
+
+---
+
+## Phase 1. Foundation for workspace/chat/file domain
+
+### R10. Domain model for user storage
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Scope:** `Workspace`, `Chat`, `ChatFile`, domain errors
+- **Layer:** `domain/`
+- **Выход:** минимальные сущности, value objects, ошибки конфликтов/не-найдено/квота
+- **Depends on:** `R00`, `R02`
+
+### R11. Usecase ports for storage and metadata
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Scope:** repository/storage interfaces для workspace/chat/chat-file/history/quota
+- **Layer:** `usecase/`
+- **Выход:** порты для metadata repo, file storage, usage reader, id generator, clock и trusted caller identity input
+- **Depends on:** `R10`
+
+### R12. In-memory metadata adapter foundation
+- **Рекомендуемый исполнитель:** `junior`
+- **Scope:** первая metadata implementation для workspace/chat/chat-file/artifact metadata
+- **Layer:** `repository/`
+- **Примечание:** это промежуточный этап; durable DB идет отдельным follow-up после storage/product slice
+- **Выход:** in-memory CRUD для workspace/chat/chat-file/artifact metadata
+- **Depends on:** `R11`
+
+### R13. Filesystem storage adapter foundation
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** storage adapter для chat directories, `history.md`, uploads и file metadata extraction
+- **Layer:** `adapter/` или `repository/` в зависимости от финальной границы
+- **Выход:** операции create/list/delete/read metadata для chat files, history path management и download path resolution
+- **Depends on:** `R11`
+
+### R14. Sandbox integration with chat metadata
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** перестать считать `chat_id` единственным источником layout, использовать metadata-backed chat path
+- **Layer:** `usecase/` + outer adapters
+- **Выход:** sandbox mounts current chat directory, созданную через storage model
+- **Depends on:** `R12`, `R13`
+
+---
+
+## Phase 2. Workspace and chat API
+
+### R20. Create workspace on first touch
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** auto-create workspace при первом запросе на user storage
+- **API:** внутренний usecase + при необходимости явная HTTP ручка
+- **Выход:** гарантированный `Workspace` для пользователя по `user_id`
+- **Depends on:** `R12`
+
+### R21. Chat CRUD
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** create/get/list/delete chat
+- **API:** versioned HTTP under `/api/v1`
+- **Выход:** first-class chat metadata вместо implicit-only `chat_id`
+- **Depends on:** `R20`, `R12`, `R13`
+
+### R22. History file lifecycle
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** создавать `history.md` вместе с chat directory, читать и обновлять metadata
+- **Выход:** первый стабильный contract для истории чата в filesystem
+- **Depends on:** `R21`, `R13`
+
+### R23. Chat file upload and file metadata API
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** upload/list/get metadata/delete single file/clear chat files
+- **API:** HTTP adapter + schemas
+- **Выход:** базовый file management API на chat scope + master download endpoint
+- **Depends on:** `R21`, `R13`
+
+### R24. Usage and quota accounting
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** считать storage usage по workspace/chat, мягкая quota 10 GB
+- **Выход:** usecases и metrics для current usage; file/artifact write-path reject при превышении soft quota
+- **Depends on:** `R23`
+
+### R25. Tests and review for storage slice
+- **Рекомендуемый исполнитель:** `test-engineer`
+- **Scope:** unit + adapter + HTTP tests, boundary review
+- **Выход:** regression coverage для workspace/chat/files
+- **Depends on:** `R20`-`R24`
+
+---
+
+## Phase 3. Artifact pipeline
+
+### R30. Artifact domain and metadata model
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Scope:** `Artifact` entity, states, delivery metadata, linkage to `user/chat`
+- **Layer:** `domain/`, `usecase/`
+- **Выход:** базовая artifact model + errors + repository ports для in-memory metadata stage
+- **Depends on:** `R01`, `R12`
+
+### R31. Object storage adapter
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** S3-compatible adapter for artifact blobs
+- **Layer:** outer `adapter/` or `repository/`
+- **Выход:** upload/get/delete primitives behind interface + presigned URL support
+- **Depends on:** `R30`
+
+### R32. Artifact registration and upload flow
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** usecase, который связывает metadata и object storage
+- **Выход:** artifact можно зарегистрировать, сохранить blob и получить external reference
+- **Depends on:** `R30`, `R31`
+
+### R33. Artifact list/get metadata API
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** list artifacts by chat/user, get artifact metadata/status
+- **Выход:** внешний API для управления artifact metadata и выдачи presigned download references
+- **Depends on:** `R32`
+
+### R34. Delivery acknowledgement flow
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** mark artifact as delivered / delivery_failed
+- **Выход:** подтвержденный delivery state через explicit ack и база для retention
+- **Depends on:** `R32`
+
+### R35. Artifact delete / mark-for-delete policy
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** policy-driven cleanup hooks после delivery confirmation или TTL
+- **Выход:** artifact lifecycle завершен, metadata и blob cleanup согласованы, `marked_for_delete` используется как переходное состояние
+- **Depends on:** `R34`
+
+### R36. Tests and review for artifact slice
+- **Рекомендуемый исполнитель:** `test-engineer`
+- **Scope:** unit + adapter + HTTP tests, boundary review
+- **Выход:** regression coverage для artifact lifecycle и object storage integration
+- **Depends on:** `R30`-`R35`
+
+---
+
+## Phase 4. Cross-slice hardening
+
+### R40. Observability for storage usage and artifacts
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** metrics по usage/quota, artifact upload latency, artifact errors
+- **Выход:** dashboards and alerts for storage-centric flows
+- **Depends on:** `R24`, `R32`, `R35`
+
+### R41. Cleanup safety rules
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Scope:** не удалять chat files/artifacts, если есть активный sandbox или незавершенный delivery flow
+- **Выход:** safe cleanup invariants
+- **Depends on:** `R24`, `R35`
+
+### R42. Docs refresh
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Scope:** README, ADRs, API docs, operator notes
+- **Выход:** актуальная документация для storage and artifact flows
+- **Depends on:** все предыдущие slices
+
+---
+
+## Рекомендуемый порядок выполнения
+
+### Priority A — workspace/chat/files
+1. `R00` `R02`
+2. `R10` `R11`
+3. `R12` `R13`
+4. `R20` `R21` `R22`
+5. `R23` `R24`
+6. `R14` `R25`
+
+### Priority B — artifacts
+1. `R01`
+2. `R30` `R31`
+3. `R32` `R33`
+4. `R34` `R35`
+5. `R36`
+
+### Future follow-up after Priority A+B
+1. durable metadata repository instead of in-memory adapters
+2. auth/access control and access lease
+3. multi-node storage/session coordination
+
+### Priority C — hardening
+1. `R40`
+2. `R41`
+3. `R42`
+
+---
+
+## Что даст этот roadmap
+
+После выполнения Priority A + B сервис сможет:
+- создавать и хранить workspace/chat metadata
+- управлять файлами пользователя в chat scope
+- хранить историю чата в предсказуемом layout
+- поднимать sandbox поверх first-class chat storage
+- хранить artifact metadata и blob отдельно
+- отдавать artifact metadata наружу и подтверждать доставку
+
+То есть `master-service` станет не только sandbox orchestrator, но и полноценным control-plane для user storage и artifact lifecycle.

tasks/sprint-01-storage-foundation.md

@@ -0,0 +1,130 @@
+# Sprint 01 — storage foundation
+
+## Цель спринта
+
+Подготовить первый исполнимый storage slice для `workspace` / `chat` / `chat files` без durable DB и без auth, но с корректными clean-architecture границами.
+
+## Зафиксированные допущения
+
+- trusted caller передает `user_id: UUID`
+- один `Workspace` на одного `User`
+- metadata adapters пока `in-memory`
+- история чата живет в `history.md`
+- chat files отдаются через master download endpoint
+- soft quota блокирует quota-relevant write-path операции
+- chat create сам по себе quota не блокирует
+- delete в v1 — hard delete; chat delete запрещен при active sandbox
+
+## Scope in
+
+- domain model для `Workspace`, `Chat`, `ChatFile`
+- usecase ports для metadata, filesystem storage и usage
+- in-memory metadata adapters
+- filesystem adapter для chat directories, `history.md` и file operations
+- usecases для auto-create workspace, chat CRUD и file CRUD
+- HTTP API для chat/file operations
+- базовый usage/quota check
+
+## Scope out
+
+- durable DB
+- auth/access control
+- artifacts
+- retention engine
+- p2p/access lease
+- multi-node behavior
+
+## Легенда исполнителей
+
+- `primary-agent` — архитектура, ADR, domain/contracts
+- `junior` — простые repositories и базовые unit tasks
+- `junior+opus` — adapter/usecase/API задачи средней сложности
+- `test-engineer` — test packs
+- `code-reviewer` — review-only этап
+
+## Порядок задач
+
+### S01. ADR-lite и storage contracts
+- **Рекомендуемый исполнитель:** `primary-agent`
+- **Commit:** `add storage foundation contracts`
+- **Scope:** зафиксировать storage source-of-truth и history policy; добавить domain entities и usecase ports
+- **Files:** `docs/009-storage-foundation.md`, `docs/010-chat-history-policy.md`, `domain/*`, `usecase/interface.py` или новые storage usecase files
+- **Acceptance:** есть минимальные сущности/ошибки/порты; ADR краткий и консистентный
+
+### S02. In-memory metadata adapters
+- **Рекомендуемый исполнитель:** `junior`
+- **Commit:** `add in-memory storage repositories`
+- **Scope:** `WorkspaceRepository`, `ChatRepository`, `ChatFileRepository` in-memory implementations
+- **Files:** `repository/*`
+- **Acceptance:** CRUD и базовые query paths работают без HTTP
+
+### S03. Filesystem chat storage adapter
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Commit:** `add chat filesystem storage`
+- **Scope:** create chat directory, create `history.md`, save/list/delete files, collect file metadata
+- **Files:** outer adapter/repository storage files
+- **Acceptance:** chat directory layout стабилен; adapter не протекает внутрь
+
+### S04. Workspace and chat usecases
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Commit:** `add workspace and chat usecases`
+- **Scope:** auto-create workspace on first touch, create/get/list/delete chat
+- **Files:** `usecase/*`, `adapter/di/container.py`
+- **Acceptance:** delete chat конфликтует при active sandbox; history path создается через storage adapter
+
+### S05. Chat file usecases + quota
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Commit:** `add chat file usecases`
+- **Scope:** upload/list/metadata/delete/clear files; current usage and soft quota reject on write
+- **Files:** `usecase/*`, `adapter/di/container.py`
+- **Acceptance:** file write-path reject при quota overflow; usage включает `history.md` и chat files; chat metadata create не блокируется quota check
+
+### S06. HTTP API for chat and files
+- **Рекомендуемый исполнитель:** `junior+opus`
+- **Commit:** `add chat and file http api`
+- **Scope:** versioned routes, schemas, error mapping, file download endpoint
+- **Files:** `adapter/http/fastapi/*`
+- **Acceptance:** API тонкий; FastAPI не протекает во внутренние слои
+
+### S07. Tests for storage foundation
+- **Рекомендуемый исполнитель:** `test-engineer`
+- **Commit:** `add storage foundation tests`
+- **Scope:** unit + adapter + HTTP tests для workspace/chat/files/quota
+- **Files:** `test/*`
+- **Acceptance:** есть regression coverage для CRUD, history creation, quota reject, delete conflict, file download
+
+### S08. Boundary review
+- **Рекомендуемый исполнитель:** `code-reviewer`
+- **Commit:** no
+- **Scope:** final review storage foundation slice
+- **Acceptance:** clean architecture соблюдена, нет must-fix замечаний
+
+## Definition of done
+
+Спринт считается завершенным, когда:
+- можно создать chat для `user_id`
+- для chat создается directory и `history.md`
+- можно загрузить и удалить chat files
+- можно получить metadata и скачать файл через master
+- quota check блокирует quota-relevant file write operations
+- все тесты проходят
+- boundary review не содержит must-fix замечаний
+
+## Риски
+
+- in-memory metadata не переживает restart
+- download endpoint может потребовать уточнения streaming contract
+- quota semantics нужно держать простыми, чтобы не породить скрытый retention scope
+
+## Что идет следующим спринтом
+
+Сразу после этого спринта нужен bridge-спринт для sandbox/storage integration:
+- metadata-backed chat path для sandbox flow
+- wiring текущего `CreateSandbox` поверх first-class chat metadata
+- review, что sandbox lifecycle не расходится с новым storage slice
+
+И только потом логично брать artifact slice:
+- artifact domain + metadata
+- object storage adapter
+- artifact upload/list/status
+- delivery ack flow