specs/openspec/changes/archive/2026-09-07-optimize-session-oriented-sdd-v2/design.md

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