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