diff --git a/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/.openspec.yaml b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/.openspec.yaml new file mode 100644 index 0000000..f845845 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-08-27 diff --git a/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/design.md b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/design.md new file mode 100644 index 0000000..a8323d8 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/design.md @@ -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/`. В нём 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 | diff --git a/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/proposal.md b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/proposal.md new file mode 100644 index 0000000..fbb6836 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/proposal.md @@ -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. diff --git a/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/specs/agent-sdd-session-workflow/spec.md b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/specs/agent-sdd-session-workflow/spec.md new file mode 100644 index 0000000..855d0e9 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/specs/agent-sdd-session-workflow/spec.md @@ -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 до работы ответственной роли diff --git a/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/tasks.md b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/tasks.md new file mode 100644 index 0000000..863a791 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/tasks.md @@ -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. diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/.openspec.yaml b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/.openspec.yaml new file mode 100644 index 0000000..dd341e4 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/.openspec.yaml @@ -0,0 +1,7 @@ +schema: wealth-ledger-sdd +created: 2026-08-26 +goal: Reduce cumulative agent context usage without weakening WealthLedger SDD, + approvals, verification, or review quality. +affected_areas: + - specs + - docs diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/design.md b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/design.md new file mode 100644 index 0000000..f9e0160 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/design.md @@ -0,0 +1,212 @@ +## Context + +WealthLedger уже разделяет нормативные change artifacts, durable engineering +policy и компактные agent entrypoints, но root routing сейчас безусловно требует +несколько широких документов до определения стадии и affected areas. В длинных +сессиях широкие reads, verbose command results и последовательные независимые +tool calls накапливаются в conversation history и повторно передаются каждому +следующему model call. При этом OpenSpec уже предоставляет естественные +checkpoint: каждый planning artifact создаётся отдельно, проходит structural +gate и требует явного approval. + +Изменение должно использовать эти существующие boundaries, не создавать второй +context map, не переносить normative policy в session summary и не превращать +нестабильные показатели локальных rollout logs в completion gate. Workspace root +не является Git-репозиторием, поэтому compact root routing обновляется локально, +а versioned authority и as-built описание принадлежат `specs` и `docs`. + +## Goals / Non-Goals + +**Goals:** + +- сделать approved artifact естественной границей новой agent-сессии; +- заменить blanket documentation reads на stage- и area-aware routing с явными + условиями обязательного on-demand чтения; +- уменьшить избегаемые model/tool round-trips и объём переносимых успешных logs, + не теряя evidence для диагностики, verification и review; +- провести ограниченный pilot на 10 post-change SDD-фазах и оценить resource + usage вместе с качеством результата; +- сохранить рекомендации guidance до отдельного evidence-backed решения о hard + guardrail. + +**Non-Goals:** + +- менять artifact graph, approvals, canonical gates, semantic verification или + independent review; +- внедрять telemetry proxy, новый session-log parser, внешнюю интеграцию либо + обязательную зависимость; +- автоматически создавать, закрывать или переносить Codex tasks; +- оптимизировать системный prompt, model selection, pricing или provider quota; +- гарантировать одинаковый расход для несопоставимых по сложности фаз; +- продвигать numeric token budget в completion blocker в рамках этого change. + +## Decisions + +### Durable policy, lazy playbook и compact routing имеют разных владельцев + +Canonical Specs сохраняют только наблюдаемые инварианты: stage-scoped context, +approval-preserving handoff, сохранность evidence и совместную оценку ресурса с +качеством. Engineering governance фиксирует устойчивое различие guidance и hard +guardrail. Отдельный development playbook описывает операционные приёмы и pilot +protocol; он загружается только для agent workflow work или при диагностике +расхода. Root `AGENTS.md` остаётся коротким router: сначала stage и affected +areas, затем conditional pointers к governance, architecture, glossary и audit +material. Repository-local entrypoints сохраняют canonical gates и boundaries. + +Такое разделение предотвращает повторение подробного playbook в каждом agent +prefix. Альтернатива — поместить все правила batching и budgets прямо в root +`AGENTS.md` — отклонена, потому что увеличивает обязательный context каждой +сессии и смешивает routing с объясняющей policy. Полностью удалить pointers тоже +нельзя: agent должен иметь однозначный путь к authority при появлении +релевантного вопроса. + +### Canonical artifact является handoff interface, но не доказательством approval + +После явного approval Proposal, Delta Specs, Design или Tasks следующая фаза +может начинаться в новой Codex task. Минимальный handoff state содержит change +identity, последний явно approved artifact, текущую фазу, affected areas, +unresolved blockers и следующий разрешённый outcome. Planning content не +копируется: новая task получает его из canonical OpenSpec store. Для перехода +Apply → independent verification дополнительно передаётся фактический scope +изменений и доступное evidence. + +Handoff остаётся сообщением пользователя или conversation state, а не новым +versioned файлом. Наличие artifact без доступного явного approval не позволяет +переходить дальше: агент повторно запрашивает решение Change Owner. Это сохраняет +существующий approval contract и устраняет соблазн использовать summary как +параллельный authority. + +Альтернатива — продолжать весь lifecycle в одной task и полагаться только на +automatic compaction — отклонена: compaction наступает после накопления затрат и +не совпадает с semantic boundaries SDD. Обязательная новая task после любого +короткого действия также отклонена: стартовый context может быть дороже +продолжения; boundary применяется после завершённого artifact или другого +наблюдаемого milestone. + +### Evidence batching происходит только до следующего смыслового решения + +Agent сначала формирует bounded evidence set. Независимые read-only lookups, +status checks и scoped source reads получают одним batch, если ни один результат +не определяет следующий вызов. Discovery начинается с поиска identity или +символа, затем читает найденные ranges. Diff discovery начинается с scope и +paths, затем раскрывает relevant content. Успешный command result сохраняет +command identity, exit status и существенную summary; verbose output не +переносится полностью, если он не нужен следующему решению. + +Dependent calls, side effects, approval boundaries и semantic judgment остаются +последовательными. Failure или неоднозначная summary расширяет diagnostics; +canonical verification и reviewer получают весь relevant evidence. Soft output +budgets помогают выбрать форму результата, но никогда не обрезают единственный +диагностический сигнал. + +Альтернатива — blanket limit на строки или tool tokens — отклонена: статический +cap может скрыть причину failure или material diff. Альтернатива всегда сохранять +полный output — отклонена из-за доказанного накопления нерелевантного context. + +### Pilot измеряет фазу, resource usage и delivery quality совместно + +Immutable snapshot текущего session audit сохраняет baseline и его ограничения. +После активации guidance pilot собирает 10 завершённых SDD-фаз как минимум из +двух changes. Для каждого наблюдения фиксируются phase type, workload scope, +cumulative input, model calls, context-depth indicators, tool-output volume, +canonical-gate outcome, fix cycles и review findings. Незавершённые или +прерванные попытки не включаются в denominator completed-phase efficiency, но +учитываются отдельно как outcome, чтобы экономия не достигалась отбрасыванием +неудач. + +Сравнение выполняется внутри одинаковых phase types и близкого scope, когда это +возможно; общий aggregate сопровождается caveat о неоднородности задач. Успехом +считается направленное уменьшение resource usage без ухудшения gate success, +rework и findings. Результат pilot может подтвердить guidance, потребовать её +пересмотра или дать основание для отдельного Proposal о детерминированном +guardrail. Текущий change не повышает threshold автоматически. + +Change остаётся active до накопления и оценки 10 post-change фаз. Это увеличивает +его календарную длительность, но позволяет завершить change с наблюдаемым +результатом вместо предположения. Другие changes могут выполняться во время +окна наблюдения и становятся источником pilot data. + +### Measurement не вводит новый runtime или parser + +Pilot использует provider-counted usage и существующую процедуру анализа rollout +sessions. Raw rollout data не коммитится; versioned docs получают только +агрегированные показатели, scope, метод и caveats. Любая стоимость или quota +интерпретация отделяется от token counts и не объявляется причинно доказанной без +provider contract. + +## Delivery Map + +| Area | Status | Architectural outcome or N/A reason | +| --- | --- | --- | +| frontend | `N/A` | Application behavior, frontend agent routing и canonical frontend gate не меняются. | +| backend | `N/A` | Backend behavior, data, API contract, backend agent routing и canonical backend gate не меняются. | +| specs | `affected` | Canonical lifecycle и engineering-governance requirements получают token-efficient context, handoff, evidence и pilot invariants; change проходит существующий planning lifecycle и sync. | +| docs | `affected` | Durable engineering policy, lifecycle documentation, lazy operational playbook, development index, immutable baseline snapshot и pilot result описывают фактически активированный workflow без копирования planning artifacts. | + +Workspace root routing обновляется локально как orchestration outcome и не +получает фиктивный repository commit. + +### 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 | +| --- | --- | --- | --- | --- | +| Existing provider rollout usage plus project audit protocol | Уже доступные фактические session counters; достаточно для ограниченного pilot | Нет нового data path или runtime dependency; ручная классификация требует дисциплины | Формат usage может меняться, поэтому метод и caveats фиксируются вместе с результатом | Выбрано для pilot | +| Project-owned rollout parser and token gate | Может автоматизировать повторный отчёт | Создаёт shared observability tooling и maintenance burden вокруг private/unstable local format | Потребует fixtures, compatibility policy и ложится в обязательный local workflow до доказанной ценности | Отклонено до повторяемой потребности | +| External telemetry proxy or agent-cost platform | Зрелые варианты дают dashboards и cross-provider attribution | Меняет execution/data boundary, требует подключения, конфигурации и постоянной эксплуатации | Избыточно для локального pet-project pilot и не решает orchestration само по себе | Отклонено | +| Только субъективная оценка скорости работы | Нулевая стоимость внедрения | Не создаёт privacy или runtime риска | Не позволяет отличить реальное улучшение от ощущения и не выполняет утверждённые Specs | Отклонено | + +Выбранный вариант переиспользует существующие данные и не создаёт custom +observability subsystem. Trigger повторной оценки tooling: не менее двух +последовательных pilot cycles требуют одинаковой ручной обработки либо native +usage перестаёт давать необходимые counters. + +## Risks / Trade-offs + +- **Lazy context может скрыть обязательную authority.** Root routing сохраняет + явные triggers для domain, architecture, audit и gate questions; при появлении + такого вопроса relevant authority загружается до решения. +- **Batch может объединить зависимые действия.** Guidance ограничивает batching + заранее независимыми read-only calls; side effects и adaptive discovery + остаются последовательными. +- **Compact output может скрыть failure.** Любой non-zero или неоднозначный + result расширяет diagnostics, а review сохраняет full relevant scope. +- **Новая task может потерять approval.** Handoff требует явного owner decision; + при отсутствии подтверждения workflow повторно запрашивает approval. +- **Фазы различаются по сложности.** Pilot сохраняет phase type и scope, + сравнивает близкие наблюдения и публикует ограничения aggregate. +- **Долгий pilot задерживает archive.** Guidance начинает действовать до archive, + а фиксированное окно 10 фаз ограничивает длительность и предотвращает + бессрочное наблюдение. +- **Метрики могут стимулировать сокращение качества.** Gate outcomes, fix cycles, + interrupted attempts и review findings имеют равный статус с token usage. + +## Migration Plan + +1. Синхронизировать durable policy, lifecycle description и lazy operational + playbook с утверждёнными Specs; сохранить immutable baseline и measurement + protocol без raw session data. +2. Перевести root routing с blanket reads на stage/area-first conditional + pointers, сохранив existing authority, SDD approvals и canonical gates. +3. Активировать guidance для последующих agent phases и начать фиксированное + окно из 10 наблюдений минимум по двум changes. +4. Сопоставить resource и quality outcomes, документировать ограничения и не + продвигать numeric threshold автоматически. +5. После завершения pilot выполнить affected-area gates, semantic verification, + independent review и обычный sync/archive lifecycle. + +### Rollback Contract + +| Field | Decision | +| --- | --- | +| Status | `N/A` | +| Reason | Изменение затрагивает обратимые instructions и документацию, не меняет auth/security behavior, данные, migration или public contract; откат выполняется обычным revert affected commits и восстановлением предыдущего локального root routing. | +| Trigger | N/A | +| Actions | N/A | +| Data safety | N/A — пользовательские и runtime данные не создаются и не изменяются. | +| Verification | N/A | diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/proposal.md b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/proposal.md new file mode 100644 index 0000000..b208d44 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/proposal.md @@ -0,0 +1,60 @@ +## Why + +Недавний аудит Codex-сессий показал, что основной расход лимитов WealthLedger +создаёт не генерация кода и не обязательные SDD-артефакты, а большое количество +последовательных model/tool циклов на уже разросшемся контексте. Полное чтение +нерелевантных документов, повторные широкие diff и logs, а также продолжение +нескольких SDD-фаз в одной длинной сессии многократно переносят накопленный +контекст без соразмерного прироста качества. Это повышает риск преждевременной +компакции и исчерпания лимита именно в поздних фазах реализации и проверки. + +Процессу нужна измеримая token-efficient discipline, которая уменьшает +повторную передачу контекста, но сохраняет существующие authority, approval +gates, semantic verification и независимый review. + +## What Changes + +- Установить фазовые границы agent-сессий вокруг утверждённых SDD-артефактов, + чтобы следующая фаза продолжалась из canonical artifacts и явного решения + Change Owner, а не из полной истории обсуждения. +- Сделать загрузку проектного контекста целевой: сначала определять текущую + стадию и affected areas, затем читать только применимые authority и + релевантные диапазоны материалов. +- Сократить model/tool round-trips за счёт совместного получения независимых + evidence и компактного представления успешных command results, сохраняя + доступ к необходимым diagnostics при ошибке или семантической проверке. +- Провести pilot и сравнивать расход контекста на успешно завершённую SDD-фазу + вместе с качественными ограничителями: результатами canonical gates, + количеством циклов исправления и findings независимого review. +- Считать числовые budgets и пороги guidance до появления репрезентативных + данных и детерминированной локальной проверки; pilot не вводит новый hard + guardrail и не блокирует корректную работу только по объёму токенов. + +Не входят в change: удаление или объединение SDD-стадий, ослабление owner +approvals, semantic verification, canonical gates или independent review; +создание параллельного handoff/planning artifact; изменение пользовательского +поведения frontend или backend; управление тарифами, quota, моделями или +системным контекстом Codex; запрет tools или subagents как класса; немедленное +введение обязательного token cap без результатов pilot. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `openspec-authority-and-lifecycle`: сделать переход между SDD-фазами и + загрузку agent context целевыми, сохраняя canonical artifacts и явные + approval gates единственным основанием продолжения работы. +- `engineering-change-governance`: определить измеримую token-efficient + guidance и условия, при которых будущая рекомендация может стать + проверяемым hard guardrail без снижения качества поставки. + +## Impact + +Изменение затрагивает Engineering Owner и AI-агентов, которые планируют, +реализуют и проверяют WealthLedger changes. Оно меняет нормативный SDD workflow, +agent routing и as-built process documentation, но не изменяет frontend, +backend, пользовательское поведение, данные или runtime API contracts. diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/engineering-change-governance/spec.md b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/engineering-change-governance/spec.md new file mode 100644 index 0000000..27a12ce --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/engineering-change-governance/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/openspec-authority-and-lifecycle/spec.md b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/openspec-authority-and-lifecycle/spec.md new file mode 100644 index 0000000..418d403 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/specs/openspec-authority-and-lifecycle/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/tasks.md b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/tasks.md new file mode 100644 index 0000000..8fd6ce3 --- /dev/null +++ b/openspec/changes/archive/2026-08-27-optimize-agent-token-workflow/tasks.md @@ -0,0 +1,38 @@ +## 1. Policy, routing и baseline + +- [x] 1.1 [docs] Сохранить исходный session-token audit как immutable dated snapshot, добавить его в audits index и создать lazy development playbook с routing matrix, handoff envelope, evidence-batching boundaries, failure expansion и pilot protocol без копирования OpenSpec artifacts + - **Covers:** `openspec-authority-and-lifecycle` — `Agent context следует текущей SDD-фазе`; `openspec-authority-and-lifecycle` — `Session handoff сохраняет approval boundary`; `engineering-change-governance` — `Token-efficient execution сохраняет delivery evidence`; `engineering-change-governance` — `Token-efficiency оценивается на завершённых фазах вместе с качеством` + - **Verification:** Сверить source/snapshot checksum и byte count, затем выполнить scoped review playbook против всех четырёх Requirements и проверить links обоих indexes. +- [x] 1.2 [docs] Обновить engineering governance и OpenSpec lifecycle documentation до durable policy stage/area-first context, explicit approval handoff, guidance-only output budgets и quality-coupled pilot, оставив подробные операции в lazy playbook + - **Covers:** `openspec-authority-and-lifecycle` — `Agent context следует текущей SDD-фазе`; `openspec-authority-and-lifecycle` — `Session handoff сохраняет approval boundary`; `engineering-change-governance` — `Token-efficient execution сохраняет delivery evidence`; `engineering-change-governance` — `Token-efficiency оценивается на завершённых фазах вместе с качеством` + - **Verification:** Провести read-only ownership review updated policy, lifecycle и playbook и подтвердить одно authoritative место для каждого правила без blanket duplication. +- [x] 1.3 [specs] Сделать specs-local agent routing stage-scoped и compact, сохранив fixed store, one-artifact approvals, current-stage instructions и conditional pointer к lazy playbook без встраивания подробного token guidance в каждый schema artifact + - **Covers:** `openspec-authority-and-lifecycle` — `Agent context следует текущей SDD-фазе`; `openspec-authority-and-lifecycle` — `Session handoff сохраняет approval boundary` + - **Verification:** Получить instructions Proposal, Specs, Design, Tasks и Apply из project schema, затем подтвердить current-stage authority, approval boundary, fixed store и отсутствие повторённого full playbook в prefix inputs. +- [x] 1.4 [workspace] Заменить root blanket reads на compact stage/affected-area-first routing и conditional triggers для governance, architecture, domain и audit material, добавив короткий handoff и evidence-batching pointer без создания versioned workspace artifact + - **Covers:** `N/A` — workspace root routing оркестрирует применение repository-owned policy и не является самостоятельным behavior contract или repository implementation. + - **Verification:** На read-only routing matrix для scoped repository work, cross-area architecture, domain semantics, audit-derived work и failed verification подтвердить минимальный initial context и обязательную загрузку каждого relevant authority trigger. + +## 2. Pilot observation и verdict + +- [x] 2.1 [workspace] Активировать approved guidance и собрать local non-authority dataset для 10 последующих завершённых SDD-фаз минимум по двум changes, отдельно учитывая interrupted attempts, phase/scope, input, model calls, context depth, tool output, gate outcome, fix cycles и review findings + - **Covers:** `N/A` — workspace task собирает observation inputs для docs-owned pilot verdict и не подменяет repository-owned implementation Requirements. + - **Verification:** Проверить 10 completed observations минимум для двух change identities, наличие всех resource/quality fields, отдельный перечень interrupted attempts и отсутствие raw rollout content в Git. +- [x] 2.2 [docs] Опубликовать агрегированный pilot result с method, scope, comparable phase groups, resource и quality outcomes, confounders и verdict; обновить guidance только в пределах наблюдаемых данных и не продвигать numeric budget в hard guardrail + - **Covers:** `engineering-change-governance` — `Token-efficiency оценивается на завершённых фазах вместе с качеством` + - **Verification:** Пересчитать агрегаты из local pilot dataset, сопоставить verdict с gate/fix/review outcomes и проверить отсутствие unsupported quota, cost или causal claims. + +## 3. Affected-area gates и итоговая проверка + +- [x] 3.1 [specs] Выполнить canonical specs checks для compact routing и полного planning change после завершения pilot + - **Covers:** `N/A` — задача проверяет specs delivery уже покрытых lifecycle Requirements и не вводит самостоятельное observable behavior. + - **Verification:** Запустить OpenSpec version preflight, schema validation, planning verifier, strict change validation, strict main-spec validation, authority verifier и `git diff --check` в `specs`. +- [x] 3.2 [docs] Выполнить canonical docs gate и scoped проверку baseline snapshot, development indexes, policy/playbook links и pilot result + - **Covers:** `N/A` — задача проверяет docs delivery уже покрытых Requirements и не создаёт новый behavior contract. + - **Verification:** Запустить `npm run verify` в `docs`, подтвердить affected local links и повторно сверить immutable baseline checksum. +- [x] 3.3 [workspace] Выполнить canonical cross-area dispatcher с Delivery Map `specs/docs=affected`, `frontend/backend=N/A` и Contract Gate `runtime-openapi=N/A` + - **Covers:** `N/A` — workspace task оркестрирует affected-area gates и не подменяет repository-owned implementation. + - **Verification:** Запустить `bash specs/scripts/verify-workspace-change.sh optimize-agent-token-workflow` и проверить наблюдаемый выбор только утверждённых affected areas и gates. +- [x] 3.4 [workspace] Провести semantic verification реализации и pilot verdict против Proposal, всех 4 Delta Requirements, 14 Scenarios, Design и Tasks, затем independent read-only review без Critical или Important findings + - **Covers:** `N/A` — terminal semantic verification и independent review проверяют change целиком, но не реализуют отдельный Requirement. + - **Verification:** Зафиксировать observed coverage каждого Requirement/Scenario и устранить blocking findings до archive eligibility. diff --git a/openspec/specs/agent-sdd-session-workflow/spec.md b/openspec/specs/agent-sdd-session-workflow/spec.md new file mode 100644 index 0000000..a1e1d1b --- /dev/null +++ b/openspec/specs/agent-sdd-session-workflow/spec.md @@ -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 до работы ответственной роли diff --git a/openspec/specs/engineering-change-governance/spec.md b/openspec/specs/engineering-change-governance/spec.md index 295b752..bbed0f2 100644 --- a/openspec/specs/engineering-change-governance/spec.md +++ b/openspec/specs/engineering-change-governance/spec.md @@ -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 diff --git a/openspec/specs/openspec-authority-and-lifecycle/spec.md b/openspec/specs/openspec-authority-and-lifecycle/spec.md index 59ebf11..733e189 100644 --- a/openspec/specs/openspec-authority-and-lifecycle/spec.md +++ b/openspec/specs/openspec-authority-and-lifecycle/spec.md @@ -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