## Context

SDD lifecycle уже опирается на canonical OpenSpec store, versioned engineering
governance, repository-local routing и необязательные agent adapters. Сейчас эти
слои частично повторяют lifecycle rules, а session state не связывает сохранённый
approval с неизменностью одобренного artifact. Implementation ориентирована на
полное завершение change за один outcome, Validation и Finalization местами
повторяют evidence work, а Completion Evidence живёт вне canonical archive.

Подход должен сохранить OpenSpec единственной authority для change-specific
знания, `docs/development` — authority для общей policy и context discipline, а
active instructions — короткими routing entrypoints. Canonical workflow должен
оставаться выполнимым без конкретного AI-agent runtime. Все репозитории
независимы, CI отсутствует, а локальные gates выполняются под Node 22.

## Goals / Non-Goals

**Goals:**

- Разделить vendor-neutral lifecycle core, repository-local boundaries и
  необязательные runtime adapters без дублирования общей policy.
- Представить Specification как две ограниченные последовательности с отдельной
  approval boundary перед каждым downstream artifact.
- Сделать persisted session navigation достаточной для точного продолжения, но
  не превращать её в альтернативу canonical artifacts или самостоятельное
  доказательство approval.
- Разрешить Implementation завершаться проверенным checkpoint и направлять
  Validation и Finalization по точным, не пересекающимся обязанностям.
- Хранить фактическое Completion Evidence вместе с canonical archive.

**Non-Goals:**

- Изменять пользовательское поведение WealthLedger, доменную модель или API.
- Вводить новый workflow engine, CI service либо обязательный agent runtime.
- Переносить Requirements, Design, Tasks или acceptance scenarios в session
  records, documentation или active instructions.
- Автоматически считать сохранённое состояние approval решением Change Owner.

## Decisions

### 1. Canonical core и active entrypoints имеют разные обязанности

Общая lifecycle policy и context discipline остаются в двух versioned
vendor-neutral authorities внутри `docs/development`: первая определяет стадии,
ownership и completion safeguards, вторая — bounded reads, evidence batching и
handoff discipline. OpenSpec schema задаёт форму и stage-specific native
instructions для canonical artifacts. Root и repository-local active
instructions содержат только ссылочную маршрутизацию, локальные boundaries и
canonical gates.

Необязательные skills, commands и session records являются adapters поверх этой
модели. Они могут автоматизировать routing и persistence, но canonical outcomes
должны быть достижимы вручную через OpenSpec и repository gates. Общие правила не
копируются в каждый adapter: adapter ссылается на authority и добавляет только
runtime-specific mechanics.

Альтернатива — сделать agent skill tree источником полного workflow — отклонена:
она привязывает completion safeguards к одному runtime и создаёт расходящиеся
копии policy. Оставить дублирование во всех `AGENTS.md` также отклонено из-за
непроверяемого semantic drift.

### 2. Specification использует две bounded progression с четырьмя approval boundaries

Specification сохраняет одну роль, но делится на пары `Proposal + Delta Specs`
и `Design + Tasks`. После draft каждого artifact workflow ждёт explicit approval
его неизменившегося содержимого. Approval Proposal разрешает только Delta Specs;
approval Delta Specs завершает первую пару и направляет следующий Specification
outcome к Design. Аналогично approval Design разрешает только Tasks, а approval
Tasks — переход к Implementation.

Navigation state хранит для текущей границы наблюдённый approval status,
identity artifact и стабильный fingerprint его содержимого. Первичное значение
`approved` появляется только после явного решения Change Owner. При продолжении
fingerprint сверяется с canonical artifact: совпадение позволяет использовать
сохранённый observed status, отсутствие статуса требует повторного решения, а
несовпадение сбрасывает approval изменённого artifact и всех downstream
artifacts. Immutable record сообщает только наблюдённый переход и следующий
outcome; canonical content в него не копируется.

Альтернатива — всегда повторно спрашивать approval в новой сессии — безопасна,
но противоречит требуемому восстановлению контекста. Approval только по имени
artifact без fingerprint отклонён, потому что не обнаруживает semantic edit.

### 3. Session recovery читает один актуальный envelope

Mutable state остаётся единственным navigation pointer, а immutable phase record
— self-contained handoff текущего outcome. Recovery сначала выбирает одну роль и
один разрешённый outcome, затем читает только текущий record, phase-specific
authority и canonical artifacts этой роли. Старые records доступны лишь как
evidence при расследовании конкретного расхождения.

Обновление выполняется в порядке `canonical outcome → immutable record → state
pointer`. Незавершённая запись не продвигает pointer; конфликт конкурентных
изменений остаётся видимым через filesystem/Git и не разрешается last-write-wins
логикой. Records не содержат Requirements, decisions, Tasks или acceptance
scenarios.

### 4. Implementation checkpoint является нормальным outcome той же роли

Implementation выбирает связный batch из ещё не выполненных approved Tasks.
После реализации она отмечает только фактически завершённые canonical Tasks и
сохраняет релевантные observed checks. Если implementation-owned Tasks остаются,
outcome остаётся Implementation checkpoint с completed/remaining scope и одним
следующим Implementation outcome; это не blocker и не готовность к Validation.

Только отсутствие remaining implementation-owned Tasks вместе с успешными
релевантными проверками создаёт `READY_FOR_VALIDATION`. Размер batch не задаётся
искусственным числом: граница определяется связностью изменения и возможностью
дать проверяемый checkpoint без частично нарушенного инварианта.

Альтернатива — требовать реализацию всего change за одну сессию — отклонена из-за
неограниченного контекста и потери проверяемых промежуточных результатов.

### 5. Validation производит независимый verdict, Finalization только потребляет его

Validation выполняется в отдельной read-only роли относительно production code,
planning artifacts и Tasks. Она объединяет affected canonical gates, semantic и
acceptance verification, применимые edge cases и independent review в один
verdict: `PASS`, `FAIL` либо `SPEC_ISSUE`. Validation-owned проверки не
представляются implementation checkboxes.

Record `PASS` связывается с identity проверенных planning и delivery inputs.
Finalization проверяет, что эти inputs не изменились, но не повторяет актуальную
Validation. Отсутствующий или устаревший `PASS` направляется в Validation;
implementation finding — в Implementation; planning issue — к самой ранней
затронутой Specification boundary; retryable completion failure остаётся в
Finalization.

Альтернатива — разрешить Validation сразу исправлять findings — отклонена,
поскольку смешивает независимый verdict с авторством изменений. Повторять все
проверки в Finalization отклонено как дублирование уже привязанного к inputs
evidence.

### 6. Completion Evidence формируется до archive только из существующих фактов

После успешной Validation delivery changes и их repository commits уже должны
существовать. Finalization собирает фактическую Delivery Map, commit identifiers,
точные observed gate outcomes и independent review result в Completion Evidence
внутри active canonical change, затем архивирует change вместе с этой записью.
После archive as-built remediation registry может ссылаться на canonical archive
и не дублирует evidence.

Для `N/A` area сохраняется проверяемая причина без фиктивного commit или gate.
Если любой факт отсутствует, Completion Evidence не создаёт placeholder и
archive остаётся заблокирован. Тем самым archive является единственным
долговечным evidence bundle, а docs сохраняет только as-built navigation.

Альтернатива — вести отдельный evidence store в docs — отклонена, поскольку он
расходится с change authority и усложняет восстановление terminal status.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `affected` | Repository-local active instructions согласуются с vendor-neutral lifecycle authority и сохраняют только frontend boundaries и canonical gate. Product code и runtime behavior не меняются. |
| backend | `affected` | Repository-local active instructions согласуются с vendor-neutral lifecycle authority и сохраняют только backend boundaries и canonical gate. API и runtime behavior не меняются. |
| specs | `affected` | Canonical Delta Specs, OpenSpec schema instructions и completion/archive model закрепляют bounded Specification, Implementation checkpoints и разделение Validation/Finalization. |
| docs | `affected` | Engineering governance, lifecycle/context documentation и remediation semantics становятся общей vendor-neutral authority и указывают на Completion Evidence в canonical archive. |

Workspace-owned root routing и optional runtime adapters меняются как
orchestration surface, но не подменяют repository-owned outcomes из Delivery
Map.

### Contract Gate Decision

| Gate | Status | Reason |
| --- | --- | --- |
| runtime-openapi | `N/A` | Change не меняет backend API contract, frontend contract consumer или runtime OpenAPI snapshot. |

## Solution Assessment

Change существенно меняет shared SDD tooling, поэтому оценены следующие
варианты:

| Option | Fit and maturity | Security / operating cost | Constraints / migration cost |
| --- | --- | --- | --- |
| Расширить существующие OpenSpec schema, versioned Markdown authorities и малый navigation adapter | Высокое соответствие; OpenSpec уже является canonical store и поддерживает native artifact lifecycle | Не добавляет внешнего сервиса или credential surface; использует существующие local gates | Требует согласованно обновить active instructions и мигрировать текущий state envelope |
| Сделать vendor-specific skills/commands обязательным workflow engine | Хорошая автоматизация только внутри одного runtime; portability низкая | Добавляет runtime lock-in и отдельную поверхность сопровождения safeguards | Нарушает достижимость canonical outcomes без optional framework и усложняет переход между agents |
| Ввести отдельный general-purpose workflow/BPM/CI orchestrator | Зрелые продукты существуют, но их возможности существенно шире локального session routing | Добавляет сервис, конфигурацию, supply-chain и operational ownership | Непропорциональная миграция при отсутствии CI и серверной orchestration requirement |
| Написать собственный orchestration engine | Можно точно подогнать под state machine, но зрелость начинается с нуля | Максимальная стоимость тестирования, совместимости и поддержки | Дублирует OpenSpec lifecycle и создаёт новую authority boundary |

Выбран первый вариант: он расширяет уже ответственную платформу и сохраняет
малый custom surface только для локальной навигации. Повторная оценка нужна,
если появятся multi-user concurrent execution, обязательный remote CI или
невозможность выразить новый lifecycle invariant native OpenSpec validation.

## Risks / Trade-offs

- Fingerprint защищает approval от незаметного изменения artifact, но не
  превращает navigation state в криптографическое доказательство личности
  Change Owner. Модель доверия остаётся repository-local и явной.
- Разделение authorities снижает дублирование, но повышает важность корректных
  routing links. Canonical gates и scoped review должны обнаруживать broken
  links и противоречащие active instructions.
- Миграция активного change может встретить legacy state без approval binding.
  Такой state не угадывается: текущая boundary запрашивает решение повторно.
- Input-bound `PASS` требует точно определить relevant inputs. Слишком широкий
  набор вызывает лишнюю Validation, слишком узкий — риск stale verdict; binding
  включает все approved planning artifacts и affected delivery state.
- Перенос Completion Evidence в archive меняет порядок Finalization. Archive
  остаётся заблокированным до существования delivery commits и всех observed
  verification facts.

## Migration Plan

1. Сначала изменить canonical schema и vendor-neutral lifecycle/context
   authorities так, чтобы новые state transitions, approval invalidation,
   checkpoint outcomes, verdict routing и archive evidence имели одно
   нормативное определение.
2. Затем согласовать root и repository-local active instructions с новыми
   authorities, сохранив только routing, boundaries и local gates.
3. После этого обновить optional runtime adapters и session envelope. Legacy
   state без artifact fingerprint остаётся читаемым для выбора change/phase, но
   не переносит approval автоматически.
4. Перевести Implementation, Validation и Finalization adapters на новые
   outcomes и input bindings; удалить дублирующий evidence flow после появления
   canonical archive path.
5. Завершить миграцию согласованной проверкой всех affected instruction
   surfaces и native OpenSpec lifecycle без зависимости от optional runtime.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `N/A` |
| Reason | Изменение состоит из versioned process artifacts, local instructions и обратимого navigation state; оно не меняет auth/security, данные, public contract или необратимую runtime infrastructure. До завершения миграции прежние canonical artifacts сохраняются в Git, а legacy state без нового binding приводит к повторному approval, а не к потере данных. |
| Trigger | N/A |
| Actions | N/A |
| Data safety | N/A |
| Verification | N/A |