docs(specs): archive session workflow changes

2026-08-27 15:24:31 +03:00
parent 69d4e63a51
commit 216956e0c6
14 changed files with 1014 additions and 0 deletions
@@ -0,0 +1,125 @@
+# agent-sdd-session-workflow Specification
+
+## Purpose
+Определяет воспроизводимый session-oriented workflow для AI-assisted SDD,
+сохраняющий OpenSpec единственным источником спецификации и границы независимых
+инженерных ролей.
+
+## Requirements
+
+### Requirement: Каждая agent-сессия имеет одну SDD-роль
+
+Session-oriented SDD workflow SHALL направлять каждую новую agent-сессию ровно
+в одну роль: Discovery, Specification, Implementation, Validation или
+Finalization. Сессия MUST завершаться после результата своей роли и MUST NOT
+самостоятельно выполнять следующую роль. Когда роль Specification готовит
+planning artifact, она MUST соблюдать canonical OpenSpec artifact graph и
+explicit approval boundary.
+
+#### Scenario: Начинается новый change
+
+- **WHEN** пользователь начинает SDD-workflow для нового change
+- **THEN** workflow направляет сессию только в Discovery и не начинает
+  Specification, Implementation, Validation или Finalization в той же сессии
+
+#### Scenario: Завершилась реализация
+
+- **WHEN** Implementation завершает разрешённый scope работы
+- **THEN** workflow фиксирует результат Implementation как вход для следующей
+  сессии, направляет продолжение в Validation и не выполняет Validation в
+  завершившейся Implementation-сессии
+
+#### Scenario: Specification подготавливает planning artifact
+
+- **WHEN** Specification готовит следующий OpenSpec planning artifact
+- **THEN** workflow создаёт только artifact, разрешённый текущей approval
+  boundary, и останавливается до явного решения Change Owner
+
+### Requirement: Продолжение workflow восстанавливает только нужный контекст
+
+Workflow SHALL определять следующую роль из сохранённого состояния change и
+минимального handoff предыдущей роли. Он MUST загружать phase-specific canonical
+authority, а не полную историю предыдущих сессий или все прежние handoff-данные.
+После появления OpenSpec change его approved artifacts MUST быть источником
+требований для последующих ролей; handoff MAY передавать только навигационные
+факты, результаты и нерешённые блокеры.
+
+#### Scenario: Пользователь продолжает change после другой сессии
+
+- **WHEN** пользователь запрашивает продолжение известного change
+- **THEN** workflow определяет следующую разрешённую роль из сохранённого
+  состояния и загружает текущий handoff и применимую canonical authority этой
+  роли
+
+#### Scenario: Есть история нескольких попыток
+
+- **WHEN** change содержит предыдущие handoff-данные или результаты ранних
+  попыток
+- **THEN** workflow не загружает их по умолчанию и обращается к ним только при
+  необходимости расследовать проблему текущей роли
+
+### Requirement: Handoff не заменяет canonical OpenSpec authority
+
+Workflow handoff SHALL сохранять только состояние перехода между ролями,
+краткий результат, известные блокеры и один следующий допустимый outcome. Handoff
+MUST NOT становиться альтернативным хранилищем Requirements, Delta Specs,
+Design, Tasks, acceptance scenarios или approval decisions.
+
+#### Scenario: Specification уже завершена
+
+- **WHEN** следующая роль получает handoff после Specification
+- **THEN** она использует OpenSpec artifacts для требований и технических
+  решений, а handoff использует только для маршрутизации и известных ограничений
+
+#### Scenario: Требование нужно изменить во время реализации
+
+- **WHEN** Implementation обнаруживает, что requirement или архитектурное
+  решение неполно либо противоречиво
+- **THEN** workflow возвращает работу к соответствующей canonical planning
+  boundary и не изменяет требование только в handoff или реализации
+
+### Requirement: Validation остаётся независимой и без побочных исправлений
+
+Validation SHALL независимо сопоставлять canonical OpenSpec artifacts с
+состоянием репозитория, релевантными проверками и наблюдаемым поведением. Она
+MUST NOT изменять production implementation или спецификацию. Validation MUST
+возвращать PASS, FAIL либо SPEC_ISSUE и направлять следующую сессию к
+Finalization, Implementation либо соответствующей planning boundary.
+
+#### Scenario: Реализация соответствует утверждённому change
+
+- **WHEN** Validation подтверждает requirements, relevant checks и границы
+  scope без blocking findings
+- **THEN** она возвращает PASS и разрешает следующую сессию Finalization
+
+#### Scenario: Найдена проблема реализации
+
+- **WHEN** Validation находит несоответствие реализации утверждённому OpenSpec
+- **THEN** она возвращает FAIL с наблюдаемым finding и направляет следующую
+  сессию к Implementation без самостоятельного исправления
+
+#### Scenario: Найдена проблема спецификации
+
+- **WHEN** Validation находит противоречие или пробел в canonical planning
+  artifacts
+- **THEN** она возвращает SPEC_ISSUE и направляет работу к самой ранней
+  затронутой planning boundary без переписывания specification под реализацию
+
+### Requirement: Finalization требует успешной независимой Validation
+
+Workflow SHALL разрешать Finalization только после последней независимой
+Validation с результатом PASS. Если Finalization обнаруживает failure обязательной
+проверки или проблему корректности, она MUST сообщить блокировку и направить
+работу к ответственной предыдущей роли, не исправляя реализацию самостоятельно.
+
+#### Scenario: Последняя Validation прошла
+
+- **WHEN** Finalization получает change после последнего PASS Validation
+- **THEN** она выполняет только допустимые действия завершения canonical
+  lifecycle и фиксирует результат завершения
+
+#### Scenario: В Finalization обнаружена проблема
+
+- **WHEN** Finalization обнаруживает failed check или проблему корректности
+- **THEN** она возвращает блокировку с наблюдаемой причиной и не закрывает
+  lifecycle change до работы ответственной роли