specs/openspec/specs/multi-repository-delivery/spec.md

# multi-repository-delivery Specification

## Purpose

Определяет полную поставку одного SDD-изменения через независимые frontend, backend, specs и docs репозитории без потерянных областей, фиктивных коммитов и преждевременного статуса done.

## Requirements

### Requirement: Каждый change содержит полный Delivery Map

Каждый legacy `wealth-ledger-sdd` change MUST оценивать delivery areas `frontend`, `backend`, `specs` и `docs` в Design Delivery Map и для каждой области указывать `affected` либо `N/A` с конкретной причиной. Для `wealth-ledger-sdd-v2` Design оценивает implementation impact `main`, `frontend`, `backend` (и `qa`, только если существует repo), а Docs Impact отдельно оценивает `docs`; `specs` владеет SDD artifacts и native sync/archive без фиктивной implementation task. Для обоих workflows `docs` SHALL быть affected для каждой поставленной пользовательской фичи; для технического или процессного change она MAY быть `N/A` только когда фактическая устойчивая документация не изменяется. `frontend` и `backend` SHALL быть affected только когда меняется их поведение, контракт, реализация или обязательный локальный gate. Пустой коммит MUST NOT использоваться для имитации участия незатронутого репозитория.

#### Scenario: Фича затрагивает клиент и API

- **WHEN** change меняет пользовательский поток и соответствующее API-поведение
- **THEN** legacy Delivery Map отмечает frontend, backend, specs и docs как affected; v2 Design отмечает frontend/backend, а Docs Impact — docs и отдельный specs artifact не превращается в пустую task

#### Scenario: Область не затронута

- **WHEN** поведение, контракт, реализация, guardrails и фактическая документация области не меняются
- **THEN** соответствующий impact artifact содержит проверяемую причину `N/A`, а delivery не требует пустого коммита этого репозитория

### Requirement: Частичная multi-repository delivery не считается завершённой

Change MUST оставаться active, пока каждая affected область не реализована и не прошла свои обязательные локальные gates. Успех одной области MUST NOT позволять архивировать change, если другая affected область отсутствует, не проверена либо не соответствует согласованному поведению. После archive change MUST NOT получить terminal status `done`, пока фактические результаты всех применимых delivery areas выбранной schema не представлены в Completion Evidence.

#### Scenario: Backend готов, а frontend ещё не реализован

- **WHEN** Delivery Map помечает frontend и backend как affected, но завершён и проверен только backend
- **THEN** change остаётся active и не может быть архивирован

#### Scenario: Все affected области готовы

- **WHEN** каждая affected область реализована, согласована по общим контрактам и прошла требуемые локальные gates
- **THEN** change может перейти к семантической верификации и archive, после которого формируется Completion Evidence для terminal status

### Requirement: Completion Evidence содержит только наблюдённые результаты

Completion Evidence MUST создаваться после выполнения работы и MUST связывать canonical change с commit identifier каждого изменённого Git-репозитория, точными выполненными non-mutating verification commands и их наблюдёнными результатами. Для каждой оценённой области с `N/A` evidence SHALL сохранять согласованную причину отсутствия изменения. Planned commands, ожидаемые результаты, незавершённые checklist items и предполагаемые commit identifiers MUST NOT представляться как completion evidence.

#### Scenario: Change готовится к terminal status

- **WHEN** implementer заявляет, что multi-repository change завершён
- **THEN** reviewer может сопоставить impact artifacts выбранной schema с фактическими commits, результатами gates и причинами `N/A` для всех оценённых областей

#### Scenario: Команда ещё не была выполнена

- **WHEN** verification command только запланирована или её результат не сохранён
- **THEN** она остаётся implementation checklist item и не засчитывается как Completion Evidence

### Requirement: Общий локальный verifier сохраняет gates репозиториев

Workspace SHALL предоставлять один non-mutating локальный verification entrypoint для multi-repository delivery. Он MUST проверять совместимость runtime до application gates, запускать канонический gate каждой selected affected области и сохранять их ошибки как blocking result. Общий verifier MUST NOT заменять или ослаблять локальные gates независимых репозиториев.

#### Scenario: Запущен неподдерживаемый runtime

- **WHEN** multi-repository verifier запускается с runtime, не соответствующим объявленному проектом контракту
- **THEN** проверка завершается ошибкой до получения вводящего в заблуждение результата application tests

#### Scenario: Один repository gate завершается ошибкой

- **WHEN** общий verifier проверяет несколько affected областей и канонический gate одной из них не проходит
- **THEN** общий результат является неуспешным и явно указывает failing area без обхода её локального gate

### Requirement: Каждая задача объявляет единственную delivery area

Каждый checkbox legacy Tasks MUST объявлять ровно одного owner из `frontend`, `backend`, `specs`, `docs` или `workspace`; `workspace` SHALL использоваться только для cross-area orchestration или verification без владения repository implementation. Каждый checkbox v2 Tasks MUST объявлять ровно одного repository owner из `main`, `frontend`, `backend`, `docs`, `specs` или существующего `qa`; `main` владеет только workspace/Compose/release/configuration, `specs` — genuine repository maintenance, `docs` — approved Docs Impact, `qa` — только реальная automation delivery, но не manual acceptance checkbox. Implementation work, изменяющая несколько Git-репозиториев, MUST быть разделена на repository-owned tasks. Для каждой `affected` implementation area Tasks MUST содержать её implementation work и canonical local gate, а task ownership MUST соответствовать утверждённым impact artifacts выбранной schema.

#### Scenario: Change затрагивает frontend и backend

- **WHEN** одна delivery intent требует изменения клиента и API
- **THEN** Tasks содержит отдельные frontend-owned и backend-owned checkbox items вместо одной общей implementation task

#### Scenario: Выполняется общий verification gate

- **WHEN** задача только оркестрирует проверку нескольких affected areas и не изменяет их implementation
- **THEN** legacy task MAY использовать `workspace`; v2 использует `main` только при реальном workspace-owned outcome, не маскируя независимую Validation под implementation checkbox

#### Scenario: Task ссылается на N/A area

- **WHEN** checkbox объявляет owner области, которая имеет статус `N/A` в Delivery Map
- **THEN** planning validation завершается ошибкой и указывает несогласованную delivery area выбранной schema

### Requirement: Tasks трассируются к утверждённым требованиям

Каждый checkbox Tasks MUST содержать coverage reference: одну или несколько пар из точного capability path и точного Requirement heading либо `N/A` с конкретной причиной для работы, которая не реализует spec-level behavior. Причина `N/A` MUST объяснять отсутствие самостоятельного observable behavior, техническую необходимость задачи и её связь с утверждённым Design или delivery; для v2 также допустима связь с System Analysis или Docs Impact. Однословная категория или неразрешённый placeholder не являются достаточной причиной. Каждый Requirement из Delta Specs MUST быть покрыт хотя бы одной task; для v2 допустимо явное объяснение отсутствия implementation work. Planning validation MUST отклонять отсутствующее покрытие, ссылку на несуществующий capability или Requirement, пустую причину `N/A` и неразрешённый placeholder. Содержательная достаточность непустой причины SHALL оцениваться semantic approval и independent review и MUST NOT выдаваться за детерминированный hard guardrail. Traceability SHALL использовать нативную идентичность requirement и MUST NOT вводить параллельный namespace собственных requirement IDs.

#### Scenario: Delta requirement покрыт реализацией

- **WHEN** Tasks планирует поставку изменённого requirement
- **THEN** хотя бы один checkbox ссылается на точный capability path и Requirement heading этого delta

#### Scenario: Задача не меняет spec-level behavior

- **WHEN** task обновляет infrastructure, documentation или verification без самостоятельного requirement
- **THEN** coverage reference содержит `N/A` и конкретно объясняет техническую необходимость задачи и её связь с утверждённым Design или delivery

#### Scenario: N/A содержит placeholder

- **WHEN** coverage reference оставляет template placeholder вместо фактической причины
- **THEN** planning validation блокирует approval Tasks и указывает незавершённую metadata

#### Scenario: N/A содержит непустую слабую причину

- **WHEN** coverage reference формально заполнена, но не объясняет необходимость задачи или её связь с утверждённым change
- **THEN** semantic review запрашивает уточнение без представления эвристической текстовой оценки как hard guardrail

#### Scenario: Requirement остался без задачи

- **WHEN** хотя бы один Requirement из Delta Specs не указан ни в одной coverage reference
- **THEN** planning validation блокирует approval Tasks и перечисляет uncovered Requirement