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,66 @@
+## ADDED Requirements
+
+### 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
@@ -0,0 +1,54 @@
+## ADDED Requirements
+
+### 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