231 lines
19 KiB
Markdown
231 lines
19 KiB
Markdown
## 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 |
|