docs(specs): archive session workflow changes
This commit is contained in:
@@ -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 до работы ответственной роли
|
||||
@@ -86,3 +86,68 @@ Design MUST определять rollback trigger, rollback actions, data safety
|
||||
|
||||
- **WHEN** change не затрагивает auth, security, данные, публичный контракт или другое труднообратимое решение
|
||||
- **THEN** Design указывает конкретную причину `N/A` без создания дополнительного rollback artifact
|
||||
|
||||
### Requirement: Token-efficient execution сохраняет delivery evidence
|
||||
|
||||
Project-owned agent guidance SHALL направлять AI-агента к совместному получению
|
||||
независимых read-only evidence, targeted чтению найденных диапазонов, сужению
|
||||
diff по затронутым paths и компактному представлению успешных command results.
|
||||
Такая оптимизация MUST сохранять exit status, существенный observed outcome и
|
||||
всё evidence, необходимое для текущего решения, canonical gate, semantic
|
||||
verification или independent review. При failure, неоднозначности или
|
||||
существенном расхождении workflow SHALL расширить diagnostics соразмерно
|
||||
наблюдаемой проблеме. Предпочтения по batching и размеру output SHALL оставаться
|
||||
guidance и MUST NOT блокировать корректную delivery без отдельного
|
||||
детерминированного hard guardrail.
|
||||
|
||||
#### Scenario: Требуются несколько независимых read-only результатов
|
||||
|
||||
- **WHEN** агент до следующего смыслового решения заранее знает несколько независимых source, status или diff запросов
|
||||
- **THEN** workflow направляет получить их одним evidence batch и вернуть только релевантные результаты без промежуточного model round-trip после каждого запроса
|
||||
|
||||
#### Scenario: Canonical gate проходит успешно
|
||||
|
||||
- **WHEN** обязательная verification command завершается успешно и её полный output не нужен для последующего смыслового решения
|
||||
- **THEN** agent context сохраняет точную command identity, exit status и существенную итоговую summary без обязательного переноса полного verbose log
|
||||
|
||||
#### Scenario: Verification завершается ошибкой
|
||||
|
||||
- **WHEN** compact command result сообщает failure или не позволяет определить причину
|
||||
- **THEN** workflow получает достаточные diagnostics для локализации ошибки и не скрывает необходимые failure details ради соблюдения output budget
|
||||
|
||||
#### Scenario: Independent review требует полный relevant diff
|
||||
|
||||
- **WHEN** reviewer должен проверить весь фактический scope реализации против утверждённых artifacts
|
||||
- **THEN** token-efficient guidance не исключает relevant diff или evidence, необходимые для semantic conclusion
|
||||
|
||||
### Requirement: Token-efficiency оценивается на завершённых фазах вместе с качеством
|
||||
|
||||
Token-efficiency pilot SHALL сравнивать resource usage на успешно завершённую
|
||||
SDD-фазу, включая cumulative input, количество model calls, глубину контекста и
|
||||
объём tool outputs, вместе с outcome indicators: результатами обязательных
|
||||
gates, количеством циклов исправления и findings independent review. Снижение
|
||||
resource usage MUST NOT считаться улучшением, если сопоставимая работа чаще не
|
||||
завершается, требует больше исправлений либо ухудшает verification или review
|
||||
outcomes. До накопления репрезентативных сопоставимых наблюдений числовые budgets
|
||||
SHALL оставаться guidance и MUST NOT становиться самостоятельным completion
|
||||
blocker.
|
||||
|
||||
#### Scenario: Resource usage снизился без ухудшения результата
|
||||
|
||||
- **WHEN** pilot показывает меньше cumulative input или model calls на сопоставимую завершённую фазу, а canonical gates, fix cycles и review findings не ухудшились
|
||||
- **THEN** изменение может быть представлено Engineering Owner как наблюдаемое улучшение с указанным measurement scope и ограничениями
|
||||
|
||||
#### Scenario: Дешёвая фаза создаёт больше rework
|
||||
|
||||
- **WHEN** вариант workflow использует меньше токенов, но чаще получает failed gates, дополнительные fix cycles или более серьёзные review findings
|
||||
- **THEN** pilot не представляет этот вариант как token-efficiency improvement
|
||||
|
||||
#### Scenario: Наблюдений недостаточно для обязательного порога
|
||||
|
||||
- **WHEN** pilot ещё не содержит репрезентативных сопоставимых завершённых фаз или надёжной локальной проверки
|
||||
- **THEN** model-call, context-depth и tool-output budgets остаются guidance и не блокируют delivery
|
||||
|
||||
#### Scenario: Числовой budget предлагается как hard guardrail
|
||||
|
||||
- **WHEN** последующий change предлагает сделать token budget обязательным completion condition
|
||||
- **THEN** он должен определить защищаемый риск, детерминированную non-mutating проверку и controlled compliant/violation evidence по общему contract Enforceable Engineering Invariant
|
||||
|
||||
@@ -228,3 +228,56 @@ CLI-resolved state.
|
||||
|
||||
- **WHEN** CLI уже разрешил planning artifacts и affected areas имеют локальные routing instructions
|
||||
- **THEN** Apply использует эти authorities и не блокируется отсутствием второго context mapping artifact
|
||||
|
||||
### Requirement: Agent context следует текущей SDD-фазе
|
||||
|
||||
Project-owned agent workflow SHALL начинать каждую работу с определения текущей
|
||||
SDD-фазы и affected delivery areas, а затем SHALL загружать canonical artifacts,
|
||||
локальные routing instructions и supporting authority, применимые к этой фазе и
|
||||
этим areas. Переход в новую agent-сессию после утверждения planning artifact
|
||||
SHALL использовать canonical artifact и явное решение Change Owner как основание
|
||||
продолжения. Workflow MUST NOT требовать полную историю предыдущей сессии или
|
||||
отдельный handoff/context artifact, дублирующий OpenSpec authority. Supporting
|
||||
material, не влияющий на текущую фазу, затронутую область, доменную семантику или
|
||||
обязательный gate, SHALL загружаться только при появлении наблюдаемой
|
||||
необходимости.
|
||||
|
||||
#### Scenario: Утверждённый artifact передаётся в новую сессию
|
||||
|
||||
- **WHEN** Change Owner явно утверждает текущий planning artifact и следующая agent-сессия продолжает change на разрешённой downstream-фазе
|
||||
- **THEN** workflow восстанавливает работу из canonical change artifacts, owner approval и применимых routing instructions без обязательной передачи полной истории обсуждения или создания второго handoff artifact
|
||||
|
||||
#### Scenario: Работа ограничена одной delivery area
|
||||
|
||||
- **WHEN** текущая фаза затрагивает одну определённую delivery area и не требует cross-system или доменной оценки
|
||||
- **THEN** workflow загружает authority и локальные instructions этой area, а нерелевантные architecture, domain и repository materials остаются lazy context
|
||||
|
||||
#### Scenario: Supporting material становится необходимым
|
||||
|
||||
- **WHEN** во время работы возникает вопрос, влияющий на domain semantics, cross-area architecture, audit disposition или обязательный gate
|
||||
- **THEN** workflow загружает соответствующий authoritative material до принятия решения и не использует token-efficiency guidance как основание пропустить требуемый контекст
|
||||
|
||||
### Requirement: Session handoff сохраняет approval boundary
|
||||
|
||||
Разделение agent-сессий SHALL происходить только на наблюдаемой границе, где
|
||||
завершённый результат представлен canonical artifact, применённым изменением или
|
||||
verification outcome. Handoff SHALL сохранять change identity, последний явно
|
||||
утверждённый artifact, текущую фазу, affected areas, unresolved blockers и
|
||||
следующий разрешённый outcome. Если новая сессия не имеет явного подтверждения
|
||||
approval, workflow MUST повторно запросить решение Change Owner и MUST NOT
|
||||
выводить approval только из наличия artifact.
|
||||
|
||||
#### Scenario: Planning-фаза завершилась approval
|
||||
|
||||
- **WHEN** Change Owner утвердил Proposal, Delta Specs или Design и работа продолжается в новой сессии
|
||||
- **THEN** handoff указывает change identity, утверждённую границу и единственный следующий разрешённый artifact, не перенося нерелевантную историю инструментов и обсуждений
|
||||
|
||||
#### Scenario: Approval невозможно подтвердить
|
||||
|
||||
- **WHEN** canonical artifact существует, но доступный контекст новой сессии не содержит явного решения Change Owner
|
||||
- **THEN** workflow останавливается перед downstream artifact и повторно запрашивает approval
|
||||
|
||||
#### Scenario: Реализация переходит к независимой проверке
|
||||
|
||||
- **WHEN** Apply завершил заявленную работу и change передаётся в свежий verification/review context
|
||||
- **THEN** handoff сохраняет approved artifacts, affected areas, фактический implementation scope и unresolved blockers, а reviewer получает необходимый diff и evidence без полной implementation history
|
||||
|
||||
Reference in New Issue
Block a user