orchestrator/docs/work-items/ORCH-119/08-data-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-119	architecture	architect	proposed	2026-06-17	claude-opus-4-8

08 — Требования к данным: ORCH-119 — durable-персист description задачи

Work Item: ORCH-119 · Repo: orchestrator · Стадия: architecture

When-applicable / информационный (гейтом не парсится). Применимо: фикс требует durable-хранения description в строке tasks для пути B (отложенный срез ветки, ORCH-088).

Изменения схемы БД

• Новая колонка tasks.description TEXT — добавляется идемпотентным _ensure_column(conn, "tasks", "description", "TEXT") (src/db.py, рядом с tasks.title, src/db.py:125). Прецедент 1:1 — tasks.title / tasks.track / tasks.cancelled_at.
• Базовый CREATE TABLE tasks (src/db.py:31–42) не трогается.
• Индексы не требуются (колонка не участвует в выборках/JOIN; читается по PK tasks.id).
• NULL по умолчанию; для уже существующих задач остаётся NULL (ретро-генерация вне объёма).

Новые/изменённые сущности

• tasks.description — plain-text описание запроса (предпочтительно description_stripped Plane-issue), записывается при создании задачи внутри атомарного INSERT create_task_atomic (src/db.py:678–683; список колонок/значений расширяется, параметр description аддитивен с дефолтом). Читается на пути B в _spawn (SELECT ..., description FROM tasks, src/agents/launcher.py:561) и передаётся в _materialize_deferred_branch → _create_initial_docs.
• Инвариант данных: значение пишется как есть, без обрезки/искажения; многострочный текст и markdown-спецсимволы сохраняются (00-business-request.md гейтом не парсится — спецсимволы безопасны, NFR-2). Пустое/NULL → рендер деградирует на fallback-маркер (ADR-001 D3), не на отказ.

Совместимость данных / миграции

• Аддитивность: только ADD COLUMN через _ensure_column; существующая боевая ОБЩАЯ БД и enduro-trails не затронуты (для них description тоже просто рендерится — улучшение, не регресс).
• Идемпотентность: _ensure_column — no-op при наличии колонки; повторный init_db безопасен (TC-05). _create_initial_docs на Gitea-422 — no-op (тело не перезаписывается, TC-06).
• Restart-safe / атомарность: запись description — в том же INSERT под _CREATE_TASK_LOCK (ORCH-053), без окна «задача создана, описание отсутствует»; реклейм/материализация после рестарта безопасны.
• Down-миграция: не требуется — revert PR оставляет колонку инертной (без обязательного DROP на общей прод-БД).
• Влияние на общую прод-БД (self-hosting): одна аддитивная колонка, без рестарта прода в рамках схемы (применяется на следующем init_db); без новых сетевых вызовов в горячем claim_next_job (NFR-4).