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,2 @@
+schema: wealth-ledger-sdd
+created: 2026-08-27
@@ -0,0 +1,137 @@
+## Context
+
+Workspace уже использует canonical OpenSpec graph и явные approval gates, но
+существующие entrypoints ориентированы на отдельные OpenSpec-операции и могут
+вести одну agent-задачу через несколько инженерных ролей. Нужен локальный слой
+инструкций, который задаёт границу одной роли на сессию, не изменяя lifecycle
+OpenSpec и не создавая второй источник требований.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Дать пользователю один устойчивый вход для начала или продолжения
+  session-oriented SDD change.
+- Выделить пять ролей в самостоятельные, краткие и независимо применимые
+  agent skills.
+- Передавать между задачами только навигационный state и immutable phase record;
+  requirements, decisions и approvals остаются в canonical authority и
+  conversation Change Owner.
+- Сохранить retry flow Implementation ↔ Validation и возврат к planning при
+  SPEC_ISSUE.
+
+**Non-Goals:**
+
+- Не менять OpenSpec schema, lifecycle, approvals, archive rules или repository
+  quality gates.
+- Не вводить executable workflow engine, новый CLI, фоновую orchestration либо
+  автоматическое создание новых agent-сессий.
+- Не заменять существующие generic OpenSpec skills и не переносить их content.
+
+## Decisions
+
+### Локальный набор из шести skills
+
+В `.agents/skills` размещаются `sdd-session`, `sdd-discovery`,
+`sdd-specification`, `sdd-implementation`, `sdd-validation` и
+`sdd-finalization`. Каждый содержит только роль-specific procedure, входы,
+выходы и границы полномочий. Их descriptions остаются discriminating, поэтому
+skill можно выбрать по прямому запросу роли или по запросу начать/продолжить
+session-oriented SDD, не захватывая обычную OpenSpec-работу.
+
+`sdd-session` — тонкий router. Он восстанавливает state, выбирает ровно одну
+разрешённую роль и передаёт выполнение соответствующему phase contract. Phase
+skills проверяют, что запрошенная роль совпадает с текущим состоянием, поэтому
+прямой вызов не может обойти переход workflow.
+
+### Общий protocol и non-authority session state
+
+Общие инварианты state, phase records, transition table и bootstrap prompt
+живут в одном shared protocol рядом с локальными skills. Это единственное место
+для их формы; phase skills ссылаются на него, а не копируют protocol.
+
+Для каждого change создаётся local non-authority session directory под
+`.agents/sdd/changes/<change>`. В нём mutable state pointer хранит только change
+identity, текущую/следующую роль, ссылку на current record и iteration counters.
+Каждая завершённая роль добавляет новый immutable phase record; предыдущие
+records не переписываются. Record содержит краткий outcome, changed areas,
+checks, findings или blockers и один next outcome. Он не содержит нормативных
+требований, design/tasks либо approval markers.
+
+Это состояние не является versioned planning artifact и не требуется для
+доказательства approval: при его отсутствии или расхождении с OpenSpec skill
+останавливается и запрашивает недостающий owner decision либо recovery
+direction. После Specification requirements читаются из approved OpenSpec
+artifacts; старые phase records читаются только для расследования.
+
+### Границы ролей и переходы
+
+Каждая роль завершает session только после записи собственного phase record,
+обновления state pointer и выдачи короткого bootstrap prompt для новой задачи.
+Discovery направляет к Specification только при достаточной определённости.
+Specification остаётся адаптером к canonical OpenSpec: она создаёт лишь текущий
+разрешённый artifact и останавливается для approval. Implementation выполняет
+утверждённые Tasks, а при gap возвращает процесс к нужной planning boundary.
+Validation — read-only относительно implementation/specification, выдаёт PASS,
+FAIL или SPEC_ISSUE. Finalization допускается только после PASS и возвращает
+blocker к ответственной роли вместо исправления.
+
+### Явная граница между задачами
+
+Skills не пытаются очистить контекст текущей agent-сессии технически. Вместо
+этого они завершают работу после одной роли и выводят bootstrap prompt для новой
+изолированной задачи. Bootstrap содержит identity change и вход `sdd-session`,
+но не сериализует историю или содержание specification.
+
+## Delivery Map
+
+| Area | Status | Architectural outcome or N/A reason |
+| --- | --- | --- |
+| frontend | `N/A` | Не меняются пользовательское поведение, frontend agent routing, API snapshot или canonical frontend gate. |
+| backend | `N/A` | Не меняются backend behavior, данные, API contract, backend agent routing или canonical backend gate. |
+| specs | `affected` | Новый capability фиксирует наблюдаемые границы session-oriented SDD workflow в canonical OpenSpec store. |
+| docs | `N/A` | Пользователь запросил local agent skills; durable engineering policy и as-built product documentation не меняются и не должны дублировать новый planning capability. |
+
+### Contract Gate Decision
+
+| Gate | Status | Reason |
+| --- | --- | --- |
+| runtime-openapi | `N/A` | Не меняются ни frontend-, ни backend-сторона публичного API contract. |
+
+## Solution Assessment
+
+| Option | Fit and maturity | Security / operating cost | Constraints / migration cost | Decision |
+| --- | --- | --- | --- | --- |
+| Local Markdown skills with one shared protocol | Соответствует пользовательскому пути `.agents/skills`, существующему skill format и требуемой роли instructions | Не добавляет runtime, credentials, data path или service | Требует вручную начать новую задачу по bootstrap prompt | Выбрано |
+| Existing generic `.opencode/skills` | Зрелые entrypoints для individual OpenSpec operations | Не создаёт новых costs | Их fluid workflow не даёт одной роли на сессию и не хранит required session transitions | Не выбрано |
+| Custom workflow CLI or orchestration service | Мог бы автоматизировать state transitions | Добавляет shared tooling, maintenance и риск ошибочных side effects | Противоречит first-iteration scope без подтверждённой повторяемой потребности | Отложено |
+
+## Risks / Trade-offs
+
+- Локальный state может устареть или отсутствовать. Router сверяет его с
+  canonical change и не выводит approval из файла; при конфликте требуется
+  recovery direction от Change Owner.
+- Человеку нужно открыть новую задачу после bootstrap prompt. Это осознанная
+  цена за изоляцию context и независимую Validation.
+- Шесть skills увеличивают discovery surface. Короткие descriptions и единый
+  `sdd-session` entrypoint ограничивают этот cognitive load.
+
+## Migration Plan
+
+1. Добавить shared session protocol и шесть local skills с исходными
+   phase contracts.
+2. Проверить каждый skill на корректный frontmatter, ссылки на protocol и
+   отсутствие duplicated planning authority.
+3. Использовать router на новом change; дальнейшую автоматизацию рассматривать
+   только после повторяемого наблюдаемого затруднения.
+
+### Rollback Contract
+
+| Field | Decision |
+| --- | --- |
+| Status | `N/A` |
+| Reason | Изменение добавляет обратимые локальные instructions и non-authority session records, не меняя auth, данные, migration или public contract. |
+| Trigger | N/A |
+| Actions | N/A |
+| Data safety | N/A — workflow не создаёт и не изменяет пользовательские или runtime data. |
+| Verification | N/A |
@@ -0,0 +1,48 @@
+## Why
+
+AI-assisted работа над одним change сейчас может смешивать discovery,
+спецификацию, реализацию, проверку и завершение в одной задаче. Из-за этого
+контекст растёт без явной границы, проверка получает reasoning реализации и
+сложнее независимо оценить результат. Нужен повторяемый способ начинать и
+продолжать SDD-работу отдельными сессиями, не меняя OpenSpec как источник
+истины.
+
+## What Changes
+
+Ввести session-oriented SDD workflow для агентов: каждая сессия выполняет только
+одну из ролей Discovery, Specification, Implementation, Validation или
+Finalization, передаёт следующей сессии минимальное явное состояние и
+останавливается на границе фазы. Пользователь сможет начать или продолжить
+change без ручного восстановления всей истории; следующая фаза будет
+определяться сохранённым состоянием.
+
+Workflow сохраняет OpenSpec единственным источником требований, delta specs,
+design и tasks. История выполнения и краткие handoff-данные не дублируют
+спецификацию и не загружаются в новую сессию без необходимости. Validation
+остается независимой от Implementation и не исправляет реализацию.
+
+Non-goals:
+- Не изменяются существующий OpenSpec artifact graph, approval gates, canonical
+  store или archive blockers.
+- Не вводятся автоматическое выполнение нескольких фаз, собственный workflow
+  CLI, автоматические метрики либо отдельные domain-specific workflows.
+- Не меняется продуктовое поведение frontend, backend или публичный API.
+
+## Capabilities
+
+### New Capabilities
+- `agent-sdd-session-workflow`: агентский workflow, который изолирует SDD-фазы,
+  передаёт минимальное состояние между сессиями и сохраняет OpenSpec
+  единственным источником спецификации.
+
+### Modified Capabilities
+- _none_
+
+## Impact
+
+- Разработчики, которые запускают SDD-задачи с AI-агентами: явные границы роли
+  и повторяемое продолжение change.
+- Процесс Engineering/SDD: независимая validation, минимальная загрузка
+  контекста и сохраняемая история переходов фаз.
+- Workspace agent entrypoints и canonical OpenSpec specs: появляется новый
+  процессный capability без изменений приложений или API.
@@ -0,0 +1,124 @@
+## Purpose
+
+Определяет воспроизводимый session-oriented workflow для AI-assisted SDD,
+сохраняющий OpenSpec единственным источником спецификации и границы независимых
+инженерных ролей.
+
+## ADDED 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 до работы ответственной роли
@@ -0,0 +1,23 @@
+## 1. Session workflow entrypoints
+
+- [x] 1.1 [specs] Добавить shared session protocol рядом с local skills: форму non-authority state pointer, immutable phase record, допустимые transitions, recovery при расхождении с OpenSpec и короткий bootstrap prompt.
+  - **Covers:** `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Handoff не заменяет canonical OpenSpec authority`
+  - **Verification:** Прочитать protocol против обеих Requirements и подтвердить, что он не хранит Requirements, Delta Specs, Design, Tasks или approval markers.
+
+- [x] 1.2 [specs] Добавить `sdd-session`, `sdd-discovery` и `sdd-specification` с discriminating descriptions, phase guard и остановкой после собственного outcome.
+  - **Covers:** `agent-sdd-session-workflow` — `Каждая agent-сессия имеет одну SDD-роль`; `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`
+  - **Verification:** Проверить router и planning-phase contracts против сценариев нового change, продолжения известного change и подготовки одного разрешённого OpenSpec artifact.
+
+- [x] 1.3 [specs] Добавить `sdd-implementation`, `sdd-validation` и `sdd-finalization` с feedback routing, read-only validation и PASS-only входом в finalization.
+  - **Covers:** `agent-sdd-session-workflow` — `Каждая agent-сессия имеет одну SDD-роль`; `agent-sdd-session-workflow` — `Validation остаётся независимой и без побочных исправлений`; `agent-sdd-session-workflow` — `Finalization требует успешной независимой Validation`
+  - **Verification:** Проверить phase contracts для SPEC_ISSUE, FAIL, PASS и FINALIZATION_BLOCKED; убедиться, что ни Validation, ни Finalization не исправляют implementation/specification.
+
+## 2. Specs delivery and workflow proof
+
+- [x] 2.1 [specs] Выполнить structural validation canonical change и всех шести local skills после их создания.
+  - **Covers:** `N/A` — задача подтверждает delivery уже покрытых workflow Requirements и не добавляет самостоятельное observable behavior.
+  - **Verification:** Запустить `openspec validate add-session-oriented-sdd-skills --type change --strict --store wealth-ledger-specs`, `/Users/ksv741/.codex/skills/.system/skill-creator/scripts/quick_validate.py` для каждого skill directory и `git diff --check` в `specs`.
+
+- [x] 2.2 [workspace] Провести semantic walkthrough start → Discovery → Specification → Implementation → Validation → Finalization и независимый read-only review перед terminal lifecycle change.
+  - **Covers:** `N/A` — workspace task проверяет взаимодействие local entrypoints и canonical authority, не реализуя отдельный spec-level behavior.
+  - **Verification:** Сопоставить каждый Delta Requirement и Scenario с protocol/skills, подтвердить отсутствие Critical или Important findings в independent review и сохранить только observed evidence.