# 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 исключением.

Native OpenSpec CLI валидирует schema, changes и main specs с явным store;
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 и не оставляет пустых.

Structural validation выполняется native OpenSpec CLI с
`--store wealth-ledger-specs` и не означает 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`.
Перед archive canonical gates каждого affected repository выполняются по одному
разу. `specs` проверяется всегда native strict validation. При required
`runtime-openapi` запускают backend `npm run test:openapi-contract`; этот status
допустим лишь при affected frontend и backend.

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 отдельно подтверждаются native structural и semantic gates:

```bash
openspec validate <change> --type change --strict --store wealth-ledger-specs
openspec validate --specs --strict --store wealth-ledger-specs
```

Structural success не доказывает соответствие реализации. Semantic verification
сопоставляет реализацию с 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.