# 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 ``` 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 ``` `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 --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.