Document portable SDD workflow and Storybook catalog
This commit is contained in:
@@ -2,117 +2,177 @@
|
||||
|
||||
## Назначение
|
||||
|
||||
Этот документ описывает фактически настроенный OpenSpec workflow WealthLedger. Общие определения, approval policy, risk-based testing и build-versus-buy находятся в [Engineering governance](engineering-governance.md).
|
||||
Это исполняемая процедура 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.
|
||||
- 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 исключением.
|
||||
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 OpenSpec CLI валидирует schema, changes и main specs с явным store;
|
||||
historical archives не переписываются.
|
||||
## Native planning
|
||||
|
||||
## Project-local schema
|
||||
Перед Node-командами выберите runtime через применимую `.nvmrc` командой
|
||||
`nvm use --silent`. Работая с change, сначала получите его фактическую структуру:
|
||||
|
||||
Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 3 из
|
||||
`specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
|
||||
|
||||
```text
|
||||
proposal → specs → design → tasks → apply
|
||||
```bash
|
||||
openspec status --change <change> --json --store wealth-ledger-specs
|
||||
```
|
||||
|
||||
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
|
||||
сохраняются на английском.
|
||||
Для нового согласованного change используется native
|
||||
`openspec new change <change> --store wealth-ledger-specs`. До создания Proposal
|
||||
Discovery разрешает неизвестные intent/scope вопросы. В Specification запрашивайте
|
||||
только разрешённый сейчас artifact:
|
||||
|
||||
Delta Spec template является operation-neutral comment guide. Он перечисляет
|
||||
`ADDED`, `MODIFIED`, `REMOVED` и `RENAMED`, но не создаёт активную operation
|
||||
section. Автор добавляет только применимые sections и не оставляет пустых.
|
||||
```bash
|
||||
openspec instructions <artifact> --change <change> --json --store wealth-ledger-specs
|
||||
```
|
||||
|
||||
Structural validation выполняется native OpenSpec CLI с
|
||||
`--store wealth-ledger-specs` и не означает approval.
|
||||
`<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.
|
||||
|
||||
Project-local schema проверяется из `specs`:
|
||||
Новые 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. `specs/openspec/config.yaml` хранит default schema и компактный routing context, а не копию полной policy.
|
||||
`schema which` должен указывать project-local source. Delta template остаётся
|
||||
operation-neutral guide: автор создаёт только применимые `ADDED`, `MODIFIED`,
|
||||
`REMOVED`, `RENAMED` sections. Native validation проверяет структуру, не approval.
|
||||
|
||||
## Stage context и handoff
|
||||
## Implementation и Validation
|
||||
|
||||
До 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 Tasks получите native Apply context:
|
||||
|
||||
После явного 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.
|
||||
```bash
|
||||
openspec instructions apply --change <change> --json --store wealth-ledger-specs
|
||||
```
|
||||
|
||||
Apply → Verify использует ту же boundary, добавляя фактический implementation
|
||||
scope и unresolved failures без полной истории tool calls. Подробная форма
|
||||
handoff и evidence-batching guidance описаны в
|
||||
[Token-efficient agent workflow](agent-token-efficiency.md).
|
||||
Прочитайте каждый возвращённый `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.
|
||||
|
||||
## 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:
|
||||
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
|
||||
```
|
||||
|
||||
Structural success не доказывает соответствие реализации. Semantic verification
|
||||
сопоставляет реализацию с Proposal, Delta Specs, Design и Tasks, затем требуется
|
||||
independent read-only review без Critical и Important findings.
|
||||
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.
|
||||
|
||||
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.
|
||||
## 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. Изменённые 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.
|
||||
|
||||
Reference in New Issue
Block a user