140 lines
9.4 KiB
Markdown
140 lines
9.4 KiB
Markdown
# OpenSpec authority и lifecycle
|
||
|
||
## Назначение
|
||
|
||
Этот документ описывает фактически настроенный OpenSpec workflow WealthLedger. Общие определения, approval policy, risk-based testing и build-versus-buy находятся в [Engineering governance](engineering-governance.md).
|
||
|
||
## Единственный SDD store
|
||
|
||
- Canonical store: `wealth-ledger-specs`.
|
||
- Физический root: `specs/openspec` относительно workspace.
|
||
- Requirements, Delta Specs, Design, Tasks, changes и archives хранятся только в этом store.
|
||
- Команда, читающая или изменяющая change, всегда получает `--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority проекта.
|
||
- Versioned framework-specific planning artifacts вне `specs/openspec`, включая `superpowers/plans`, запрещены. `references/**` остаётся read-only исключением.
|
||
|
||
Exact поддерживаемая OpenSpec CLI version хранится в `specs/openspec/.cli-version`. Перед project-owned операциями выполняется:
|
||
|
||
```bash
|
||
bash specs/scripts/verify-openspec-version.sh
|
||
```
|
||
|
||
Несовпадение version блокирует операцию до чтения или изменения store.
|
||
Публикация новой stable версии не меняет этот contract автоматически. Upgrade
|
||
выполняется отдельным SDD change после staged проверки schema, instructions,
|
||
agent workflow, store resolution и hard blockers; historical archives
|
||
не переписываются.
|
||
|
||
## Project-local schema
|
||
|
||
Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 3 из
|
||
`specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
|
||
|
||
```text
|
||
proposal → specs → design → tasks → apply
|
||
```
|
||
|
||
OpenSpec обеспечивает structural order, а явное решение Change Owner — переход
|
||
между артефактами. Agent создаёт один текущий artifact и останавливается для
|
||
approval. Роли артефактов и cascade rules определены в governance policy;
|
||
исполняемые templates и instructions принадлежат schema. Каждая instruction
|
||
начинается компактным блоком `Critical Rules`; основной explanatory prose
|
||
написан по-русски, а exact OpenSpec headings, tokens и normative keywords
|
||
сохраняются на английском.
|
||
|
||
Delta Spec template является operation-neutral comment guide. Он перечисляет
|
||
`ADDED`, `MODIFIED`, `REMOVED` и `RENAMED`, но не создаёт активную operation
|
||
section. Автор добавляет только применимые sections и не оставляет пустых.
|
||
|
||
До запроса approval выполняется доступная stage-aware проверка:
|
||
|
||
```bash
|
||
bash specs/scripts/verify-openspec-planning.sh <change>
|
||
```
|
||
|
||
Proposal проверяется без ложного объявления полного change success; по мере
|
||
появления Specs, Design и Tasks добавляются strict validation, Delivery Map,
|
||
rollback, area ownership и exact Requirement coverage. Planning result имеет
|
||
три категории: `artifact-validation` (exit 1), `invocation` (exit 2) и
|
||
`environment` (exit 3). Только первая разрешает менять проверяемый planning
|
||
artifact; две остальные требуют исправить invocation или prerequisite.
|
||
Structural success не означает approval.
|
||
|
||
Project-local schema проверяется из `specs`:
|
||
|
||
```bash
|
||
openspec schema validate wealth-ledger-sdd --verbose
|
||
openspec schema which wealth-ledger-sdd --json
|
||
```
|
||
|
||
`schema which` должен указывать project-local source. `specs/openspec/config.yaml` хранит default schema и компактный routing context, а не копию полной policy.
|
||
|
||
## Stage context и handoff
|
||
|
||
До supporting reads agent определяет текущую OpenSpec-фазу и affected areas.
|
||
Native instruction и возвращённые `contextFiles` задают planning context;
|
||
repository-local `AGENTS.md` добавляет только routing и canonical gate своей
|
||
area. Architecture, glossary, audit registry и подробный operational playbook
|
||
загружаются по применимому trigger, а не blanket-набором перед любой задачей.
|
||
|
||
После явного approval planning artifact следующая фаза может начаться в новой
|
||
Codex task. Handoff сохраняет change identity, последний approved artifact,
|
||
current phase, affected areas, unresolved blockers и один следующий outcome.
|
||
Содержание artifacts повторно не пересказывается и остаётся в canonical store.
|
||
Если явный approval нельзя подтвердить из новой task, agent повторно запрашивает
|
||
его до создания downstream artifact.
|
||
|
||
Apply → Verify использует ту же boundary, добавляя фактический implementation
|
||
scope и unresolved failures без полной истории tool calls. Подробная форма
|
||
handoff и evidence-batching guidance описаны в
|
||
[Token-efficient agent workflow](agent-token-efficiency.md).
|
||
|
||
## Agent entrypoints и обновление OpenSpec
|
||
|
||
Root `.opencode/commands` и `.opencode/skills` — локальные non-authority
|
||
entrypoints. Они удобны для работы агента, но не являются SDD source of truth и
|
||
не имеют отдельного versioned projection source. Нормативный contract хранится
|
||
в schema, `AGENTS.md`, governance и non-mutating scripts.
|
||
|
||
`openspec update` не запускается напрямую из workspace root. Новую upstream
|
||
version сначала проверяют в isolated staging и повторно накладывают минимальные
|
||
project constraints: fixed store, one-artifact-at-a-time, stage planning gate,
|
||
Apply feedback routing и hard archive blockers. Authority fixtures проверяют
|
||
version preflight, permissive archive, conditional store selection и второй
|
||
`openspec` root как failures.
|
||
|
||
## Реализация и проверка change
|
||
|
||
Design содержит Delivery Map для `frontend`, `backend`, `specs` и `docs`. Из workspace один non-mutating dispatcher проверяет карту и запускает canonical gates affected areas:
|
||
|
||
```bash
|
||
bash specs/scripts/verify-workspace-change.sh <change>
|
||
```
|
||
|
||
`specs` проверяется всегда. Dispatcher читает явный Contract Gate Decision из Design и сравнивает backend runtime OpenAPI с committed frontend snapshot только при `runtime-openapi: required`; этот status допустим лишь при affected frontend и backend. Child failure блокирует общий результат; fallback и auto-fix отсутствуют.
|
||
|
||
Перед affected-area gates dispatcher повторяет planning verifier. Tasks имеют
|
||
формат `X.Y [area] action` и indented `Covers`/`Verification`; каждый Delta
|
||
Requirement покрывается точной ссылкой хотя бы один раз, а `workspace` остаётся
|
||
только owner orchestration/verification. Для `N/A` verifier отклоняет пустой,
|
||
separator-only или unresolved placeholder, а содержательность rationale
|
||
подтверждается semantic review.
|
||
|
||
Apply читает planning artifacts только из `contextFiles`, возвращённых native
|
||
`openspec instructions apply --json`, затем repository-local `AGENTS.md`
|
||
affected areas. Второй context mapping не поддерживается. Без reapproval можно
|
||
исправить только Markdown heading, typo без изменения нормативного смысла или
|
||
table alignment; Requirement, Scenario, architecture и planned Verification
|
||
являются semantic changes.
|
||
|
||
Перед archive отдельно подтверждаются structural и semantic gates:
|
||
|
||
```bash
|
||
bash specs/scripts/verify-openspec-authority.sh
|
||
openspec validate <change> --type change --strict --store wealth-ledger-specs
|
||
openspec validate --specs --strict --store wealth-ledger-specs
|
||
```
|
||
|
||
Structural success не доказывает соответствие реализации. Project-owned verify workflow сопоставляет реализацию с Proposal, Delta Specs, Design и Tasks, затем требует independent read-only review без Critical и Important findings.
|
||
|
||
Archive отклоняется при незавершённом artifact approval, unchecked task, failed affected-area gate, отсутствующей semantic verification или independent review. Confirmation override для этих условий отсутствует. Completion Evidence создаётся только после archive и delivery commits по двухфазному протоколу [Engineering governance](engineering-governance.md); final evidence commit не подменяется незакрытым task.
|