199 lines
14 KiB
Markdown
199 lines
14 KiB
Markdown
# OpenSpec authority и lifecycle
|
||
|
||
## Назначение
|
||
|
||
Это исполняемая процедура canonical workflow без обязательного agent runtime.
|
||
Роли, approvals, Delivery Map и completion safeguards определяет
|
||
[Engineering governance](engineering-governance.md); чтение контекста и bindings
|
||
— [context authority](agent-token-efficiency.md). Optional skills и commands
|
||
могут выполнять те же шаги, но не заменяют эти authorities.
|
||
|
||
## Единственный SDD store
|
||
|
||
Canonical store — `wealth-ledger-specs`, физический root — `specs/openspec`
|
||
относительно workspace. Все команды, читающие или изменяющие change, получают
|
||
`--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority.
|
||
Planning artifacts, main specs, changes, Completion Evidence и archives
|
||
принадлежат только этому store. `references/**` остаётся read-only; historical
|
||
archives не переписываются.
|
||
|
||
## Native planning
|
||
|
||
Перед Node-командами выберите runtime через применимую `.nvmrc` командой
|
||
`nvm use --silent`. Работая с change, сначала получите его фактическую структуру:
|
||
|
||
```bash
|
||
openspec status --change <change> --json --store wealth-ledger-specs
|
||
```
|
||
|
||
Для нового согласованного change используется native
|
||
`openspec new change <change> --store wealth-ledger-specs`. До создания Proposal
|
||
Discovery разрешает неизвестные intent/scope вопросы. В Specification запрашивайте
|
||
только разрешённый сейчас artifact:
|
||
|
||
```bash
|
||
openspec instructions <artifact> --change <change> --json --store wealth-ledger-specs
|
||
```
|
||
|
||
`<artifact>` — `proposal`, `specs`, `design` или `tasks`. Прочитайте все
|
||
возвращённые dependencies/context files, подготовьте artifact по native
|
||
instructions, выполните доступную native structural проверку и получите
|
||
отдельный approval перед downstream artifact. Tasks instructions возвращают
|
||
Design и Delta Specs для exact `Covers`; второй context mapping не нужен.
|
||
Approval и bounded progression соблюдают governance policy.
|
||
|
||
Для Design определите
|
||
[UI/UX applicability и пакет](engineering-governance.md#uiux-пакет-design).
|
||
Прочитайте его применимые материалы, проверьте сохранённые пути, revision,
|
||
доступность и SHA-256 exports обычными файловыми операциями. Представьте весь
|
||
пакет в одном Design approval; native structural validation не проверяет
|
||
произвольные attachments или качество визуального решения автоматически.
|
||
|
||
Новые changes используют project-local schema `wealth-ledger-sdd` из
|
||
`specs/openspec/schemas/wealth-ledger-sdd` и граф
|
||
`proposal → specs → design → tasks → apply`. `config.yaml` хранит default schema
|
||
и routing context, schema — форму artifacts и stage-specific instructions.
|
||
Проверка из `specs`:
|
||
|
||
```bash
|
||
openspec schema validate wealth-ledger-sdd --verbose
|
||
openspec schema which wealth-ledger-sdd --json
|
||
```
|
||
|
||
`schema which` должен указывать project-local source. Delta template остаётся
|
||
operation-neutral guide: автор создаёт только применимые `ADDED`, `MODIFIED`,
|
||
`REMOVED`, `RENAMED` sections. Native validation проверяет структуру, не approval.
|
||
|
||
## Implementation и Validation
|
||
|
||
После approval Tasks получите native Apply context:
|
||
|
||
```bash
|
||
openspec instructions apply --change <change> --json --store wealth-ledger-specs
|
||
```
|
||
|
||
Прочитайте каждый возвращённый `contextFiles` и local `AGENTS.md` affected
|
||
repositories. Выберите связный batch pending Tasks, реализуйте его и выполните
|
||
релевантные checks. Зафиксируйте завершённые canonical checkboxes и observed
|
||
outcome. Remaining implementation work даёт checkpoint; вся завершённая работа
|
||
— готовность к отдельной Validation. Изменение artifact проверяется по
|
||
[approval binding](agent-token-efficiency.md#fingerprints), а semantic issue
|
||
возвращается к ответственной planning boundary.
|
||
|
||
При применимом UI/UX scope восстановите именно согласованный пакет из Design
|
||
до зависимой реализации. Missing material, digest mismatch и external-only
|
||
reference не компенсируются историей чата или текущим внешним макетом.
|
||
|
||
Validation читает approved planning artifacts и implementation scope, проверяет
|
||
свежесть сохранённых gate outcomes и выполняет отсутствующие affected gates.
|
||
Глобальный gate нельзя считать проверенным по более узкому fingerprint: binding
|
||
покрывает его relevant inputs. Specs gate использует native strict checks:
|
||
|
||
```bash
|
||
openspec validate <change> --type change --strict --store wealth-ledger-specs
|
||
openspec validate --specs --strict --store wealth-ledger-specs
|
||
```
|
||
|
||
Canonical gate остальных areas задан их `AGENTS.md`. Required
|
||
`runtime-openapi` дополнительно вызывает backend `npm run test:openapi-contract`.
|
||
Независимый reviewer сопоставляет реализацию с approved artifacts, acceptance
|
||
scenarios и применимыми edge cases; фиксирует `PASS`, `FAIL` или `SPEC_ISSUE`,
|
||
полный relevant evidence и reviewed input inventory/fingerprint. Он не исправляет
|
||
код, planning artifacts или Tasks. Отдельный versioned verdict artifact не
|
||
требуется: observed verdict и binding передаются в текущем handoff и затем
|
||
в canonical Completion Evidence.
|
||
|
||
Для UI/UX reviewer читает пакет той же revision и сопоставляет применимые
|
||
экраны, состояния, взаимодействия и responsive behavior. Однозначное отклонение
|
||
реализации — `FAIL`; противоречие либо неоднозначность пакета — `SPEC_ISSUE`.
|
||
Review не исправляет интерфейс или Design package и не подменяется наличием
|
||
stories, screenshots или успешной сборкой.
|
||
|
||
## Semantic sync перед archive
|
||
|
||
Перед terminal mutation сверяйте все deltas с текущей main baseline. Native
|
||
structural success и planning complete не заменяют эту проверку:
|
||
|
||
1. Используйте `artifactPaths.specs.existingOutputPaths` из текущего status JSON
|
||
как точный список deltas. Main root разрешается через
|
||
`planningHome.root/openspec/specs`; полный вложенный capability path
|
||
сохраняется. Пустой список не разрешает угадывать delta по другим файлам.
|
||
Явно выбранный subset должен целиком входить в native список; invalid path
|
||
блокирует sync, пустой subset не выполняет записей, выбор не расширяется.
|
||
2. Получите один актуальный snapshot native specs instructions той же командой
|
||
`openspec instructions specs --change <change> --json --store wealth-ledger-specs`
|
||
либо используйте уже прочитанный неизменившийся snapshot. Ошибка команды или
|
||
invalid JSON блокирует запись; отсутствие optional `rules` в корректном ответе
|
||
означает отсутствие дополнительных правил формы.
|
||
3. Прочитайте каждую delta и соответствующую main spec. Для `ADDED` проверьте
|
||
отсутствие конфликтующей identity; `MODIFIED` содержит полный requirement
|
||
и все сохраняемые scenarios; `REMOVED`/`RENAMED` меняют только явно указанные
|
||
identities. Сохраните незатронутые requirements, scenarios и existing Purpose.
|
||
Новая capability получает утверждённый Purpose, а не placeholder.
|
||
4. Покажите ожидаемый semantic diff до записи. Если новая baseline несовместима
|
||
с approved delta, верните change к самой ранней затронутой boundary. Не
|
||
переписывайте main spec или delta, чтобы скрыть конфликт.
|
||
5. После подтверждённого соответствия native archive выполняет sync вместе с
|
||
archive. Main specs сохраняют `Purpose` и `Requirements`, без delta operation
|
||
headers. Удаление всей capability допускается только при approved retirement
|
||
и `.openspec.yaml` с `retire_capabilities: true`: исходная capability была
|
||
непустой и корректной, текущая операция удалила все requirements, не осталось
|
||
другого содержимого кроме title/Purpose/Requirements, а реальный путь лежит
|
||
внутри specs root без symlink-выхода. Иначе capability не изменяется; пустая
|
||
Requirements section не записывается.
|
||
|
||
Отдельно запрошенный sync использует тот же semantic diff и native rules,
|
||
применяет только явно выбранные полные delta paths, затем выполняет strict
|
||
validation main specs. Он не даёт terminal status и не расширяет выбранный scope.
|
||
|
||
## Finalization и Completion Evidence
|
||
|
||
После актуального независимого PASS:
|
||
|
||
1. Сверьте approvals, завершённость implementation-owned Tasks и input binding
|
||
с текущим working tree. Blocker маршрутизируется по governance; неизменившиеся
|
||
gates и independent review повторно не запускаются.
|
||
2. Проверьте существующие delivery commits affected repositories. Если
|
||
разрешённая фиксация проверенных изменений ещё нужна, сделайте её до создания
|
||
evidence и повторно сравните content fingerprints. Commit/staging без
|
||
изменения inputs не устаревает PASS. Каждый delivery commit содержит
|
||
проверенное изменение своей области; unrelated working changes сохраняются.
|
||
3. Создайте `completion-evidence.md` внутри active canonical change только из
|
||
существующих фактов: Delivery Map, commit IDs, точные commands/results,
|
||
independent verdict и его input binding. Для `N/A` сохраните причину.
|
||
Собственные evidence/state/records исключены из self-hash; отдельной
|
||
обязательной docs-мутации ради evidence нет.
|
||
4. Выполните semantic sync review выше и перед archive снова проверьте, что
|
||
кроме ожидаемых completion mechanics relevant inputs не изменились.
|
||
Запустите native archive с его validation:
|
||
|
||
```bash
|
||
openspec archive <change> --yes --store wealth-ledger-specs
|
||
```
|
||
|
||
`--yes` автоматизирует prompt, не снимает safeguards. `--no-validate` и
|
||
`--skip-specs` не являются обходом failed gate, stale PASS или semantic conflict.
|
||
5. Проверьте наблюдённый archive path, сохранение Completion Evidence и ожидаемый
|
||
diff sync/move. Для применимого Design package проверьте сохранение
|
||
относительной структуры Design/visuals, доступность каждого материала,
|
||
совпадение SHA-256 и exact immutable reuse references после переноса.
|
||
Утрата или замена материала блокирует завершение. Изменённые archive/main-spec outputs проходят native strict
|
||
проверку; это проверка новых completion outputs, не повторная Validation
|
||
неизменившейся реализации. Зафиксируйте разрешённые archive/sync/evidence
|
||
изменения и сообщите созданный commit ID отдельно от evidence, чтобы избежать
|
||
self-reference. Audit-derived registry получает ссылку на archive/evidence
|
||
после успешного terminal outcome, без копирования commits и gate results.
|
||
|
||
Если archive недоступен, incomplete evidence или commit operation можно
|
||
повторить при тех же inputs — Finalization сохраняет observed blocker.
|
||
Частичный archive не повторяется вслепую: сначала установите фактические пути
|
||
и diff, затем продолжите недостающую completion operation. Неожиданное изменение
|
||
planning/delivery направляется к ответственной предыдущей роли.
|
||
|
||
## Обновление OpenSpec
|
||
|
||
`openspec update` сначала проверяют в isolated staging. После upstream update
|
||
проверяются fixed store, stage context, separate approvals, Apply feedback routing
|
||
и archive safeguards. Optional entrypoints остаются короткими указателями на
|
||
эту процедуру; vendor-specific command tree не является prerequisite.
|