diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/.openspec.yaml b/openspec/changes/optimize-session-oriented-sdd-v2/.openspec.yaml new file mode 100644 index 0000000..aea6d79 --- /dev/null +++ b/openspec/changes/optimize-session-oriented-sdd-v2/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-08-28 diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/design.md b/openspec/changes/optimize-session-oriented-sdd-v2/design.md new file mode 100644 index 0000000..255c0cb --- /dev/null +++ b/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 | diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/proposal.md b/openspec/changes/optimize-session-oriented-sdd-v2/proposal.md new file mode 100644 index 0000000..e086b37 --- /dev/null +++ b/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-поведение приложения. diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/specs/agent-sdd-session-workflow/spec.md b/openspec/changes/optimize-session-oriented-sdd-v2/specs/agent-sdd-session-workflow/spec.md new file mode 100644 index 0000000..9acfa1c --- /dev/null +++ b/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 и + направляет продолжение к точной ответственной роли diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/specs/project-documentation/spec.md b/openspec/changes/optimize-session-oriented-sdd-v2/specs/project-documentation/spec.md new file mode 100644 index 0000000..26aa666 --- /dev/null +++ b/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 diff --git a/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md b/openspec/changes/optimize-session-oriented-sdd-v2/tasks.md new file mode 100644 index 0000000..6db47dc --- /dev/null +++ b/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