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