docs(specs): plan bounded SDD workflow
This commit is contained in:
@@ -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 |
|
||||
Reference in New Issue
Block a user