docs(specs): plan bounded SDD workflow

openspec/changes/optimize-session-oriented-sdd-v2/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: wealth-ledger-sdd
+created: 2026-08-28

openspec/changes/optimize-session-oriented-sdd-v2/design.md

@@ -0,0 +1,230 @@
+## 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 |

openspec/changes/optimize-session-oriented-sdd-v2/proposal.md

@@ -0,0 +1,59 @@
+## Why
+
+Текущий session-oriented SDD уже отделяет инженерные роли и сохраняет OpenSpec
+единственным источником требований, но продолжение change всё ещё требует
+лишних переключений между сессиями, повторного восстановления неизменившегося
+контекста и неоднозначной передачи ответственности за checkpoints,
+verification и завершение. Эти издержки затрудняют локальную разработку и
+создают повторную работу без дополнительной гарантии корректности. Workflow
+нужно сделать проще и предсказуемее сейчас, сохранив explicit approvals,
+независимую Validation и жёсткие blockers завершения.
+
+## What Changes
+
+- Сгруппировать тесно связанные planning artifacts в ограниченные
+  Specification-сессии, сохранив отдельное явное решение Change Owner перед
+  каждым downstream artifact.
+- Сделать продолжение workflow однозначным и достаточным по минимальному
+  актуальному состоянию, без обязательного перечитывания неизменившейся истории
+  или повторного подтверждения уже принятого и не пересмотренного artifact.
+- Разрешить Implementation завершать связный ограниченный batch, сохранять
+  оставшуюся работу и продолжаться в следующей Implementation-сессии без
+  ложного blocker outcome.
+- Закрепить, что semantic verification, acceptance verification и independent
+  review принадлежат Validation, а Finalization использует актуальный PASS и
+  направляет проблему к точной ответственной роли без повторения неизменившейся
+  проверки.
+- Устранить противоречия и дублирование в активных SDD и repository
+  instructions, сделать операционный workflow независимым от конкретного
+  AI-agent runtime и сохранить одну понятную authority для context discipline.
+- Перенести Completion Evidence к завершённому canonical change и сохранять в
+  ней только уже существующие факты поставки, не вынуждая технический change
+  создавать несвязанное as-built documentation.
+- Не вводить telemetry, числовые token budgets, автоматический multi-agent
+  pipeline, отдельный workflow service или database и не менять поведение
+  frontend/backend приложения либо публичный API.
+- Не ослаблять explicit approvals, canonical gates, risk-based testing,
+  semantic verification, independent review или archive blockers; не
+  переписывать historical changes, audits и иные датированные evidence.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+
+- `agent-sdd-session-workflow`: уточнить наблюдаемую модель bounded sessions,
+  approvals, восстановления контекста, Implementation checkpoints, независимой
+  Validation и точной маршрутизации Finalization.
+- `project-documentation`: изменить контракт Completion Evidence и terminal
+  verification так, чтобы фактическое завершение сохранялось рядом с canonical
+  archived change без обязательной параллельной docs-записи.
+
+## Impact
+
+Change затрагивает участников, которые планируют, реализуют, проверяют и
+завершают SDD changes в локальной multi-repository workspace. Он меняет
+ожидаемый процесс перехода между SDD-ролями, форму durable completion evidence и
+активные инженерные инструкции, но не пользовательские возможности WealthLedger,
+данные, публичные контракты или runtime-поведение приложения.

openspec/changes/optimize-session-oriented-sdd-v2/specs/agent-sdd-session-workflow/spec.md

@@ -0,0 +1,250 @@
+## ADDED Requirements
+
+### Requirement: Implementation сохраняет ограниченные checkpoints
+
+Implementation SHALL выбирать связный ограниченный batch из оставшихся
+утверждённых Tasks и MAY завершить сессию, оставаясь в роли Implementation,
+если весь change ещё не реализован. Такой checkpoint MUST фиксировать
+завершённые canonical Tasks, оставшуюся работу и достаточный результат
+релевантных проверок, не выдавая неполный change за готовый к Validation.
+
+#### Scenario: Завершён один связный batch
+
+- **WHEN** Implementation завершила и проверила ограниченный batch, но в
+  canonical Tasks осталась implementation-owned работа
+- **THEN** workflow сохраняет завершённые и оставшиеся Tasks, направляет
+  продолжение в новую Implementation-сессию и не сообщает blocker или
+  готовность к Validation
+
+#### Scenario: Завершена вся implementation-owned работа
+
+- **WHEN** все утверждённые implementation-owned Tasks выполнены и релевантные
+  проверки Implementation успешны
+- **THEN** workflow фиксирует готовность change к независимой Validation
+
+### Requirement: Активные инструкции согласованы и независимы от agent runtime
+
+Активные SDD и repository instructions SHALL направлять участника к одной
+authority для общей lifecycle policy и одной authority для операционной context
+discipline. Они MUST сохранять одинаковые approval и completion safeguards и
+MUST NOT требовать конкретный AI-agent runtime или его необязательные
+framework-specific entrypoints для выполнения canonical workflow.
+
+#### Scenario: Участник начинает работу из любого active entrypoint
+
+- **WHEN** участник открывает root или repository-local active instructions
+- **THEN** он получает согласованный canonical lifecycle, применимые локальные
+  boundaries и ссылки на общую authority без противоречащей копии shared policy
+
+#### Scenario: Необязательный agent runtime отсутствует
+
+- **WHEN** участник выполняет workflow без vendor-specific commands, skills или
+  instruction tree
+- **THEN** все canonical planning, implementation, validation и finalization
+  outcomes остаются достижимыми без ослабления safeguards
+
+## MODIFIED Requirements
+
+### Requirement: Каждая agent-сессия имеет одну SDD-роль
+
+Session-oriented SDD workflow SHALL направлять каждую agent-сессию ровно в одну
+роль: Discovery, Specification, Implementation, Validation или Finalization.
+Сессия MUST NOT самостоятельно выполнять следующую роль, но создание immutable
+phase record или ожидание решения MUST NOT само по себе принуждать к новой
+сессии той же роли. Specification MUST поддерживать bounded progression
+`Proposal + Delta Specs` и `Design + Tasks`, сохраняя отдельную explicit
+approval boundary перед каждым downstream artifact.
+
+#### Scenario: Начинается новый change
+
+- **WHEN** пользователь начинает SDD-workflow для нового change
+- **THEN** workflow направляет сессию только в Discovery и не начинает
+  Specification, Implementation, Validation или Finalization в той же сессии
+
+#### Scenario: Specification подготавливает planning artifact
+
+- **WHEN** Specification подготовила structurally valid Proposal
+- **THEN** workflow запрашивает явный approval Change Owner и не создаёт Delta
+  Specs до получения решения
+
+#### Scenario: Proposal явно одобрен
+
+- **WHEN** Change Owner явно одобряет неизменившийся Proposal в bounded
+  `Proposal + Delta Specs` progression
+- **THEN** Specification MAY продолжить в той же роли и создать Delta Specs без
+  перехода к Design или другой SDD-роли
+
+#### Scenario: Delta Specs явно одобрены
+
+- **WHEN** Change Owner явно одобряет неизменившиеся Delta Specs
+- **THEN** workflow завершает bounded `Proposal + Delta Specs` progression и
+  направляет следующий Specification outcome к Design
+
+#### Scenario: Design явно одобрен
+
+- **WHEN** Change Owner явно одобряет неизменившийся Design в bounded
+  `Design + Tasks` progression
+- **THEN** Specification MAY продолжить в той же роли и создать Tasks без
+  перехода к Implementation до отдельного approval Tasks
+
+#### Scenario: Завершилась реализация
+
+- **WHEN** Implementation завершает все утверждённые implementation-owned Tasks
+- **THEN** workflow фиксирует результат Implementation как вход для следующей
+  Validation-сессии и не выполняет Validation в завершившейся
+  Implementation-сессии
+
+### Requirement: Продолжение workflow восстанавливает только нужный контекст
+
+Workflow SHALL однозначно определять текущую роль и разрешённый outcome из
+сохранённого состояния change и одного актуального self-contained handoff. Он
+MUST загружать только phase-specific canonical authority и изменившийся
+relevant evidence, а не полную историю, прежние handoff-данные или уже
+прочитанные неизменившиеся inputs. После появления OpenSpec change его approved
+artifacts MUST быть источником intent, requirements, design и tasks.
+
+#### Scenario: Пользователь продолжает change после другой сессии
+
+- **WHEN** пользователь запрашивает продолжение известного change
+- **THEN** workflow определяет ровно одну текущую роль, читает только актуальный
+  handoff и применимую canonical authority этой роли
+
+#### Scenario: Есть история нескольких попыток
+
+- **WHEN** change содержит более старые records или результаты прежних попыток
+- **THEN** workflow не загружает их по умолчанию и обращается к ним только для
+  расследования конкретной проблемы текущей роли
+
+#### Scenario: Независимые evidence доступны одновременно
+
+- **WHEN** до следующего смыслового решения нужны несколько независимых
+  read-only inputs
+- **THEN** workflow получает их одним bounded batch и сохраняет полный relevant
+  scope для failure или review findings
+
+#### Scenario: Успешный gate уже выполнен на неизменившихся inputs
+
+- **WHEN** успешный gate был выполнен и его relevant inputs после этого не
+  изменялись
+- **THEN** workflow использует сохранённый observed outcome и не повторяет gate
+  без причины
+
+### Requirement: Handoff не заменяет canonical OpenSpec authority
+
+Workflow handoff SHALL сохранять только состояние перехода, краткий observed
+result, известные блокеры и один следующий допустимый outcome. Navigation state
+MAY сохранять approval status текущих planning artifacts для продолжения
+workflow, но handoff и state MUST NOT становиться альтернативным хранилищем
+Requirements, Delta Specs, Design, Tasks или acceptance scenarios и MUST NOT
+считаться самостоятельным доказательством решения Change Owner.
+
+#### Scenario: Specification уже завершена
+
+- **WHEN** следующая роль получает handoff после Specification
+- **THEN** она использует approved OpenSpec artifacts для требований и решений,
+  а handoff — только для маршрутизации, observed results и известных
+  ограничений
+
+#### Scenario: Approval подтверждён для неизменившегося artifact
+
+- **WHEN** новый Specification context содержит сохранённый approved status и
+  workflow не изменял соответствующий planning artifact
+- **THEN** workflow продолжает к разрешённому downstream artifact без
+  повторного запроса того же approval
+
+#### Scenario: Workflow изменяет planning artifact
+
+- **WHEN** workflow семантически изменяет planning artifact
+- **THEN** approval этого artifact и всех зависимых downstream artifacts
+  сбрасывается до нового явного решения Change Owner
+
+#### Scenario: Требование нужно изменить во время реализации
+
+- **WHEN** Implementation обнаруживает, что requirement или архитектурное
+  решение неполно либо противоречиво
+- **THEN** workflow возвращает работу к самой ранней затронутой canonical
+  planning boundary и не изменяет требование только в handoff или реализации
+
+### Requirement: Validation остаётся независимой и без побочных исправлений
+
+Validation SHALL независимо выполнять affected canonical gates, semantic и
+acceptance verification, проверку применимых edge cases и independent read-only
+review относительно approved OpenSpec artifacts. Она MUST NOT изменять
+production implementation, specification или Tasks и MUST возвращать только
+PASS, FAIL либо SPEC_ISSUE с маршрутизацией к Finalization, Implementation либо
+самой ранней затронутой planning boundary. Validation-owned verification и
+review MUST NOT оставаться unchecked implementation Tasks.
+
+#### Scenario: Реализация соответствует утверждённому change
+
+- **WHEN** Validation подтверждает approved requirements, affected gates,
+  acceptance behavior и отсутствие blocking review findings
+- **THEN** она возвращает PASS и разрешает следующую сессию Finalization
+
+#### Scenario: Найдена проблема реализации
+
+- **WHEN** Validation находит несоответствие реализации утверждённому OpenSpec
+- **THEN** она возвращает FAIL с точным observed finding и направляет следующую
+  сессию к Implementation без самостоятельного исправления
+
+#### Scenario: Найдена проблема спецификации
+
+- **WHEN** Validation находит противоречие или пробел в approved planning
+  artifacts
+- **THEN** она возвращает SPEC_ISSUE и направляет работу к самой ранней
+  затронутой planning boundary без переписывания specification под реализацию
+
+#### Scenario: Tasks планируют независимую проверку
+
+- **WHEN** Tasks описывают ожидаемую semantic verification или independent
+  review после реализации
+- **THEN** завершение Implementation не зависит от checkbox, который может
+  закрыть только Validation
+
+### Requirement: Finalization требует успешной независимой Validation
+
+Workflow SHALL разрешать Finalization только после последней независимой
+Validation с PASS, если после неё не было relevant изменений planning или
+delivery inputs. Finalization MUST выполнять только archive и completion
+mechanics, MUST NOT повторять актуальную Validation и MUST направлять каждый
+blocker к точной ответственной роли без исправления production implementation
+или planning artifacts.
+
+#### Scenario: Последняя Validation прошла
+
+- **WHEN** Finalization получает change после PASS и relevant inputs с момента
+  этой Validation не изменялись
+- **THEN** она использует observed PASS и выполняет completion mechanics без
+  повторной independent Validation
+
+#### Scenario: Implementation-owned Task не завершена
+
+- **WHEN** Finalization обнаруживает незавершённую implementation-owned Task
+- **THEN** она возвращает blocker в Implementation и не архивирует change
+
+#### Scenario: PASS отсутствует или устарел
+
+- **WHEN** последняя Validation не завершилась PASS либо после PASS изменились
+  relevant planning или delivery inputs
+- **THEN** Finalization возвращает blocker в Validation и не считает прежний
+  outcome актуальным
+
+#### Scenario: Обнаружена planning issue
+
+- **WHEN** Finalization обнаруживает противоречие или пробел в approved planning
+  artifacts
+- **THEN** она возвращает blocker к самой ранней затронутой Specification
+  boundary без самостоятельного исправления
+
+#### Scenario: Completion mechanics временно недоступны
+
+- **WHEN** production и planning inputs корректны, но собственное retryable
+  действие завершения не выполнено из-за environment или completion failure
+- **THEN** workflow остаётся в Finalization с observed blocker и не повторяет
+  Implementation или Validation без изменения их inputs
+
+#### Scenario: В Finalization обнаружена проблема
+
+- **WHEN** Finalization обнаруживает любой blocker завершения
+- **THEN** она не закрывает lifecycle change, сохраняет observed cause и
+  направляет продолжение к точной ответственной роли

openspec/changes/optimize-session-oriented-sdd-v2/specs/project-documentation/spec.md

@@ -0,0 +1,119 @@
+## MODIFIED Requirements
+
+### Requirement: Completion Evidence сохраняет фактическое завершение change
+
+Canonical archived OpenSpec change SHALL хранить Completion Evidence с
+фактической Delivery Map, commit identifiers изменённых delivery areas, точными
+выполненными verification commands и их observed results, а также итогом
+independent read-only review. Completion Evidence MUST создаваться только после
+существования этих фактов, MUST быть доступно вместе с canonical archive и MUST
+NOT представляться как unchecked Task, планируемый результат или обязательная
+docs-мутация для area со статусом `N/A`.
+
+#### Scenario: Участник проверяет основание terminal status
+
+- **WHEN** участник открывает canonical archive завершённого change в новой
+  сессии
+- **THEN** он может проследить связь от Delivery Map к фактическим commits,
+  affected local gates и independent review без восстановления контекста из
+  чата или параллельного evidence store
+
+#### Scenario: Реализация ещё продолжается
+
+- **WHEN** часть delivery commits, commands, observed results или review ещё не
+  существует
+- **THEN** change не представляет ожидаемые значения как Completion Evidence и
+  не получает terminal status
+
+#### Scenario: Технический change не меняет as-built documentation
+
+- **WHEN** фактическая Delivery Map обоснованно устанавливает `docs: N/A`
+- **THEN** Completion Evidence сохраняет эту причину рядом с canonical archive
+  и не требует несвязанного изменения docs repository
+
+### Requirement: OpenSpec change закрывается только после полной верификации
+
+OpenSpec change MUST содержать все обязательные planning artifacts и
+завершённые implementation-owned Tasks до архивирования. Archive MUST быть
+заблокирован, пока отсутствует успешный canonical gate любой affected area,
+semantic и acceptance verification реализации относительно approved artifacts
+либо independent read-only review без Critical и Important findings; для area
+со статусом `N/A` MUST существовать конкретная проверяемая причина.
+
+#### Scenario: Команда пытается архивировать незавершенное изменение
+
+- **WHEN** для change отсутствует обязательный artifact, implementation-owned
+  результат, affected-area gate, semantic или acceptance verification,
+  допустимый independent review либо требуемая as-built documentation
+- **THEN** change не архивируется и остаётся незавершённым без confirmation
+  override
+
+#### Scenario: Delivery area не затронута
+
+- **WHEN** Delivery Map помечает area как `N/A`
+- **THEN** archive допускает отсутствие её commit и gate только при наличии
+  конкретной проверяемой причины
+
+### Requirement: Документация процесса содержит remediation registry
+
+Репозиторий `docs` SHALL содержать immutable versioned audit snapshots в
+`docs/audits` и versioned remediation registry в development documentation.
+Registry MUST документировать source audit, допустимые статусы, связанные
+OpenSpec changes и следующую рекомендуемую задачу. Для завершённого
+audit-derived change registry MUST ссылаться на canonical archive и его
+Completion Evidence, а не дублировать commits и verification results как
+отдельный evidence store.
+
+#### Scenario: Участник проекта ищет состояние технических улучшений
+
+- **WHEN** участник открывает development documentation
+- **THEN** он может найти audit snapshot и registry через documentation indexes
+  и определить, какие findings planned, active, done, deferred или accepted
+
+#### Scenario: Завершён audit-derived change
+
+- **WHEN** связанный OpenSpec change получил terminal status после успешной
+  проверки
+- **THEN** registry содержит его итоговый статус и ссылку на canonical archive
+  с Completion Evidence
+
+### Requirement: Durable documentation is not a parallel SDD store
+
+Репозиторий `docs` SHALL хранить только долговечную architecture, development,
+feature, audit и remediation documentation. Документация MUST описывать
+фактическое текущее состояние поставленной системы и MUST NOT представлять
+планируемое или частично реализованное поведение как доступное. Change-specific
+requirements, proposals, designs, delta specifications, tasks и Completion
+Evidence MUST храниться только в canonical OpenSpec store и MUST NOT
+пересказываться в `docs` как параллельная спецификация или evidence store. Docs
+SHALL обновляться после реализации и проверки только когда её as-built subject
+действительно affected.
+
+#### Scenario: Change требует постоянной документации
+
+- **WHEN** завершённый change меняет поставленное поведение, архитектурную
+  границу, устойчивое решение или другой as-built subject docs
+- **THEN** documentation фиксирует реализованное состояние и MAY ссылаться на
+  canonical OpenSpec change без дублирования его planning artifacts или
+  Completion Evidence
+
+#### Scenario: Agent планирует незавершённый change
+
+- **WHEN** агент создаёт requirements, design или tasks для незавершённого
+  изменения
+- **THEN** он сохраняет их в canonical OpenSpec store и не создаёт
+  framework-specific planning document или описание будущего поведения в docs
+
+#### Scenario: Реализация расходится с прежней документацией
+
+- **WHEN** проверенный change изменяет поставленное поведение, архитектурную
+  границу или устойчивое решение
+- **THEN** affected docs обновляется до фактического текущего состояния до
+  terminal status и не сохраняет прежнее утверждение как действующее
+
+#### Scenario: Docs не входит в Delivery Map
+
+- **WHEN** технический change не меняет ни один as-built subject docs и Delivery
+  Map устанавливает `docs: N/A` с проверяемой причиной
+- **THEN** terminal status не требует изменения docs только ради Completion
+  Evidence

openspec/changes/optimize-session-oriented-sdd-v2/tasks.md

@@ -0,0 +1,74 @@
+## 1. OpenSpec-native planning and Apply context
+
+- [ ] 1.1 [specs] Обновить project-local `wealth-ledger-sdd` schema metadata и зависимость Tasks с `design` на `design + specs`, чтобы native Tasks instructions возвращали утверждённый Design и все Delta Specs, необходимые для exact `Covers`
+  - **Covers:** `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Handoff не заменяет canonical OpenSpec authority`
+  - **Verification:** `openspec instructions tasks --change optimize-session-oriented-sdd-v2 --store wealth-ledger-specs` возвращает dependency paths Design и Delta Specs без дополнительных planning artifacts; `openspec schema validate wealth-ledger-sdd --verbose`
+- [ ] 1.2 [specs] Дополнить только `apply.instruction` bounded Implementation semantics: выбирать связный batch pending Tasks, сохранять checkpoint при remaining work и выдавать `READY_FOR_VALIDATION` только после завершения всех implementation-owned Tasks и релевантных checks
+  - **Covers:** `agent-sdd-session-workflow` — `Implementation сохраняет ограниченные checkpoints`
+  - **Verification:** `openspec instructions apply --change optimize-session-oriented-sdd-v2 --store wealth-ledger-specs` различает checkpoint и `READY_FOR_VALIDATION`, сохраняет чтение CLI-resolved `contextFiles` и не запускает Validation или Finalization
+
+## 2. Vendor-neutral engineering authority
+
+- [ ] 2.1 [docs] Обновить engineering lifecycle authority: зафиксировать bounded Specification approvals, нормальный Implementation checkpoint, независимую Validation и Finalization, которая потребляет только актуальный input-bound `PASS`
+  - **Covers:** `agent-sdd-session-workflow` — `Каждая agent-сессия имеет одну SDD-роль`; `agent-sdd-session-workflow` — `Implementation сохраняет ограниченные checkpoints`; `agent-sdd-session-workflow` — `Validation остаётся независимой и без побочных исправлений`; `agent-sdd-session-workflow` — `Finalization требует успешной независимой Validation`
+  - **Verification:** Scoped documentation review прослеживает каждую transition и blocker к одной ответственной роли без повторной Validation или side-effect repair
+- [ ] 2.2 [docs] Обновить authority context discipline для recovery из одного актуального envelope, fingerprint-bound approval, bounded evidence reads и запрета копировать canonical artifacts в handoff
+  - **Covers:** `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Handoff не заменяет canonical OpenSpec authority`
+  - **Verification:** Scoped documentation review подтверждает порядок canonical outcome → immutable record → state pointer, invalidation при fingerprint mismatch и чтение старых records только для конкретного расследования
+- [ ] 2.3 [docs] Перенести durable completion semantics к canonical archive и согласовать remediation registry и documentation indexes с ссылкой на archived Completion Evidence без отдельного evidence store
+  - **Covers:** `project-documentation` — `Completion Evidence сохраняет фактическое завершение change`; `project-documentation` — `OpenSpec change закрывается только после полной верификации`; `project-documentation` — `Документация процесса содержит remediation registry`
+  - **Verification:** Scoped link and ownership review подтверждает, что registry сохраняет source audit, status, related change и next task, а completed entry ссылается на canonical archive вместо дублирования commits и gate results
+
+## 3. Active repository entrypoints
+
+- [ ] 3.1 [frontend] Свести frontend active instructions к ссылке на vendor-neutral lifecycle/context authorities, frontend boundaries и canonical local gate без копии shared SDD policy
+  - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime`
+  - **Verification:** Frontend entrypoint остаётся достаточным для выбора canonical workflow и local gate без обращения к optional skill или vendor-specific command
+- [ ] 3.2 [backend] Свести backend active instructions к ссылке на vendor-neutral lifecycle/context authorities, backend boundaries и canonical local gate без копии shared SDD policy
+  - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime`
+  - **Verification:** Backend entrypoint остаётся достаточным для выбора canonical workflow и local gate без обращения к optional skill или vendor-specific command
+- [ ] 3.3 [specs] Согласовать specs active instructions с canonical lifecycle authority, fixed store, one-artifact approvals, native stage routing и specs gate без дублирования общей policy
+  - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime`
+  - **Verification:** Specs entrypoint направляет к `wealth-ledger-specs`, native OpenSpec instructions и canonical validation без обязательного runtime adapter
+- [ ] 3.4 [docs] Согласовать docs active instructions с canonical lifecycle authority, as-built ownership, remediation routing и docs gate без дублирования общей policy
+  - **Covers:** `agent-sdd-session-workflow` — `Активные инструкции согласованы и независимы от agent runtime`; `project-documentation` — `Документация процесса содержит remediation registry`
+  - **Verification:** Docs entrypoint однозначно различает canonical planning authority, as-built documentation и remediation registry и не требует optional runtime adapter
+- [ ] 3.5 [workspace] Свести root routing и optional command entrypoints к vendor-neutral authorities, fixed canonical store и repository-local boundaries
+  - **Covers:** `N/A` — workspace orchestration реализует утверждённое Design-разделение canonical core и optional adapters, но не добавляет самостоятельного observable requirement
+  - **Verification:** Из root entrypoint можно определить SDD phase, canonical authority и affected repository gates без vendor-specific command tree
+
+## 4. Optional session adapters
+
+- [ ] 4.1 [workspace] Обновить `.agents/skills/sdd-session/SKILL.md` и `.agents/skills/sdd-session/references/workflow-protocol.md`: добавить observed approval status, artifact identity и стабильный fingerprint в navigation envelope, downstream invalidation, безопасный recovery legacy state и точный phase routing
+  - **Covers:** `N/A` — workspace navigation adapter технически реализует утверждённые Design decisions для approval recovery, тогда как normative behavior принадлежит canonical specs
+  - **Verification:** Контролируемые `sdd-session` protocol scenarios показывают продолжение при совпадающем fingerprint, повторный запрос при отсутствии binding, invalidation при изменении artifact и маршрутизацию ровно в одну роль
+- [ ] 4.2 [workspace] Обновить `.agents/skills/sdd-specification/SKILL.md` для пар `Proposal + Delta Specs` и `Design + Tasks`, сохранив отдельную explicit approval boundary перед каждым downstream artifact и запрет перехода к Implementation до approval Tasks
+  - **Covers:** `N/A` — optional Specification orchestration проецирует approved canonical lifecycle и не создаёт отдельного requirement surface
+  - **Verification:** `sdd-specification` scenarios проходят четыре approval boundaries, разрешают bounded продолжение внутри одной роли и останавливаются до Implementation без отдельного approval Tasks
+- [ ] 4.3 [workspace] Обновить `.agents/skills/sdd-implementation/SKILL.md` для выбора связного batch, фиксации completed/remaining Tasks и checkpoint outcome без ложного blocker или преждевременного `READY_FOR_VALIDATION`
+  - **Covers:** `N/A` — optional Implementation orchestration реализует approved checkpoint architecture, а observable invariant остаётся в canonical spec
+  - **Verification:** `sdd-implementation` scenarios различают checkpoint с remaining implementation work и `READY_FOR_VALIDATION` только после завершения всех implementation-owned Tasks и релевантных checks
+- [ ] 4.4 [workspace] Обновить `.agents/skills/sdd-validation/SKILL.md`: сохранить read-only boundary относительно production implementation, planning artifacts и Tasks и связать `PASS`, `FAIL`, `SPEC_ISSUE` с identity проверенных planning/delivery inputs
+  - **Covers:** `N/A` — optional Validation orchestration реализует approved independent-verdict architecture без нового spec-level behavior
+  - **Verification:** `sdd-validation` scenarios не выполняют repair mutations, сохраняют input binding и направляют каждый verdict к Finalization, Implementation либо самой ранней Specification boundary
+- [ ] 4.5 [workspace] Обновить `.agents/skills/sdd-finalization/SKILL.md`: проверять свежесть `PASS`, точно маршрутизировать blockers и формировать Completion Evidence внутри active canonical change только из уже существующих фактов перед archive
+  - **Covers:** `N/A` — optional Finalization orchestration реализует approved completion mechanics; normative archive safeguards принадлежат canonical specs
+  - **Verification:** `sdd-finalization` scenarios блокируют missing/stale `PASS`, unchecked implementation task и incomplete evidence, не повторяют актуальную Validation, архивируют Completion Evidence вместе с change и оставляют retryable completion failure в Finalization
+
+## 5. Affected-area gates and workflow consistency
+
+- [ ] 5.1 [frontend] Выполнить frontend canonical gate после изменения repository-local active instructions
+  - **Covers:** `N/A` — это обязательная проверка affected frontend delivery, а не самостоятельное observable behavior
+  - **Verification:** `npm run verify` под frontend `.nvmrc`
+- [ ] 5.2 [backend] Выполнить backend canonical gate после изменения repository-local active instructions
+  - **Covers:** `N/A` — это обязательная проверка affected backend delivery, а не самостоятельное observable behavior
+  - **Verification:** `npm run verify` под backend `.nvmrc`
+- [ ] 5.3 [specs] Выполнить native strict validation schema, active change и main specs в canonical store после реализации specs-owned work
+  - **Covers:** `N/A` — это обязательный canonical gate affected specs delivery и structural proof, не новое requirement
+  - **Verification:** `openspec schema validate wealth-ledger-sdd --verbose`; `openspec validate optimize-session-oriented-sdd-v2 --type change --strict --store wealth-ledger-specs`; `openspec validate --specs --strict --store wealth-ledger-specs`
+- [ ] 5.4 [docs] Выполнить docs canonical gate и scoped local-link review после изменения governance, context authority и remediation navigation
+  - **Covers:** `N/A` — это обязательная проверка affected docs delivery и ссылочной целостности, а не самостоятельное observable behavior
+  - **Verification:** `npm run verify` под docs `.nvmrc`; scoped review изменённых local links
+- [ ] 5.5 [workspace] Проверить согласованность всех active entrypoints и достижимость canonical planning, implementation, validation и finalization outcomes без optional runtime adapters
+  - **Covers:** `N/A` — cross-area orchestration проверяет vendor-neutral delivery согласно Design, но не подменяет independent Validation и не создаёт новый requirement
+  - **Verification:** Из clean shell пройти routing для каждой SDD-роли через canonical docs, native OpenSpec instructions и repository gates без вызова optional skills/commands; выполнить scoped semantic review против approved Delta Specs и Design