docs(ai): adopt task-driven scoped context
This commit is contained in:
@@ -1,198 +1,35 @@
|
||||
# OpenSpec authority и lifecycle
|
||||
# OpenSpec: optional legacy workflow
|
||||
|
||||
## Назначение
|
||||
Обязательный SDD lifecycle отменён для обычной разработки. Текущие правила —
|
||||
[engineering governance](engineering-governance.md),
|
||||
[context discipline](agent-token-efficiency.md) и root/local AGENTS.
|
||||
Задача пользователя не требует Proposal/Delta/Design/Tasks, отдельных agent roles,
|
||||
Completion Evidence или archive как условия завершения.
|
||||
|
||||
Это исполняемая процедура 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
|
||||
`specs/openspec` сохраняет behavioral specs, active changes, schemas и archives.
|
||||
Существующий planning artifact описывает только свой прежний scope и не доказывает
|
||||
готовность нового запроса. Датированные evidence/archives не переписываются.
|
||||
Нужную behavioral spec выбирай через [specs index](../../specs/AI_INDEX.md).
|
||||
|
||||
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 не переписываются.
|
||||
## Если OpenSpec запрошен явно
|
||||
|
||||
## Native planning
|
||||
|
||||
Перед Node-командами выберите runtime через применимую `.nvmrc` командой
|
||||
`nvm use --silent`. Работая с change, сначала получите его фактическую структуру:
|
||||
Canonical store прежнего workflow — `wealth-ledger-specs`, физически
|
||||
`specs/openspec`. Перед Node-командами выбери frontend `.nvmrc`, если у specs
|
||||
нет своей. Для чтения/изменения change всегда задавай store явно:
|
||||
|
||||
```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.
|
||||
Native status/instructions определяют фактические artifacts и schema. Получай
|
||||
разрешение на именно запрошенное изменение, не выводи approval из наличия файлов.
|
||||
Sync/archive меняют existing specs/history и выполняются только в рамках такой
|
||||
явной задачи, после проверки ожидаемого semantic diff и сохранности данных.
|
||||
Structural validation не доказывает соответствие реализации задаче.
|
||||
|
||||
Для 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.
|
||||
Прежнее rationale — [ADR 010](../adr/010-native-openspec-sdd-and-local-orchestration.md)
|
||||
и [011](../adr/011-native-openspec-lifecycle-with-repository-gates.md);
|
||||
текущий выбор прямой работы — [ADR 012](../adr/012-task-driven-development-with-scoped-context.md).
|
||||
|
||||
Reference in New Issue
Block a user