82 lines
12 KiB
Markdown
82 lines
12 KiB
Markdown
## Контекст
|
||
|
||
Мотивация приведена в `proposal.md`, а поведенческий контракт — в delta specs. `specs/openspec` уже является единственным project-owned физическим OpenSpec root, но unscoped OpenSpec CLI resolution сейчас зависит от изменяемого machine default. Workspace и четыре независимых репозитория имеют agent instructions, тогда как восемь `.opencode` commands и восемь соответствующих skills сохраняют сгенерированный selection guidance, допускающий nearest-root fallback. Текущие archive instructions также позволяют owner-confirmed archive с incomplete artifacts или tasks.
|
||
|
||
`docs/development/audit-remediation.md` является durable evidence, а не вторым SDD store. `references/**` содержит импортированные framework plans и должен остаться нетронутым. Archive `2026-08-17-redesign-position-cards` имеет два unchecked lifecycle tasks, поэтому он является historical evidence, противоречащим целевой policy.
|
||
|
||
## Цели и нецели
|
||
|
||
**Цели:**
|
||
|
||
- Сделать каждую supported OpenSpec operation детерминированной из любого project-owned entrypoint.
|
||
- Сохранить единственный versioned SDD authority, оставив `docs` durable documentation и evidence.
|
||
- Превратить authority и archive rules в read-only, воспроизводимый verification result.
|
||
- Убрать incomplete-task исключение из archive и честно согласовать известное historical exception.
|
||
|
||
**Не входит в scope:**
|
||
|
||
- Не изменять OpenSpec CLI, глобальную OpenSpec configuration или несвязанные registered stores.
|
||
- Не удалять, не перемещать и не нормализовать artifacts под `references/**`.
|
||
- Не вводить Superpowers plans, другой planning framework, CI, runtime application changes или external tracker integration.
|
||
- Не переписывать прошлые Git commits и не утверждать, что historical lifecycle steps произошли в другую дату.
|
||
|
||
## Решения
|
||
|
||
### Canonical store contract заменяет contextual selection
|
||
|
||
`wealth-ledger-specs` — фиксированный идентификатор store, а `specs/openspec` — его единственный project-owned artifact root. Root, frontend, backend, specs и docs `AGENTS.md` используют одну краткую policy: requirements, design, delta specs, tasks, changes и archives принадлежат только этому store; все OpenSpec commands, читающие или изменяющие change, используют `--store wealth-ledger-specs`.
|
||
|
||
Восемь `.opencode/commands/opsx-*.md` и восемь `.opencode/skills/openspec-*/SKILL.md` заменят сгенерированные conditional store-selection blocks на блок для WealthLedger. Каждый конкретный OpenSpec invocation в этих project-owned workflows включает фиксированный flag; archive workflow использует тот же fixed selection. `references/**` исключается, поскольку не является project-owned workflow surface.
|
||
|
||
Сохранение существующих entrypoints не ломает discovery агентов и имена workflows. Опора на `openspec` root pointer или global default отклонена, поскольку они зависят от текущей директории или состояния машины. Удаление entrypoints отклонено, поскольку это ослабит, а не усилит документированный локальный workflow.
|
||
|
||
### Границы artifacts определяются их lifecycle role
|
||
|
||
Policy различает SDD state и durable documentation:
|
||
|
||
- `specs/openspec` владеет mutable и archived versioned SDD state: specs, changes, proposals, designs, delta specs и tasks.
|
||
- `docs` владеет durable architecture, development, feature, audit и remediation documentation, включая completion evidence со ссылкой на archive.
|
||
- `frontend` и `backend` владеют runtime code и tests; change planning artifacts в них не создаются.
|
||
- `references/**` остаётся read-only и исключён из cleanup и policy scanning.
|
||
|
||
Instructions запретят коммит framework-specific planning/spec/task/design artifacts вне canonical store, явно включая `superpowers/plans`. Запрет относится к параллельным sources of truth, а не к использованию инструмента или временным заметкам в разговоре. Полный запрет любого Markdown вне `specs` отклонён, поскольку он ошибочно запретит durable docs и существующий reference content.
|
||
|
||
### Repository-local verifier проверяет стабильные policy signals
|
||
|
||
Change добавит POSIX shell verifier в репозитории `specs` и документированную command, работающую из любого workspace cwd. Script определяет workspace по собственному расположению, не делает writes и сообщает о каждом нарушенном инварианте перед возвратом ненулевого результата.
|
||
|
||
Он проверит metadata зарегистрированного store и canonical path `specs/openspec`; отсутствие любого дополнительного project-owned `openspec/` directory; явное canonical-store wording и flag в root и четырёх repository `AGENTS.md`; а также compliance фиксированного набора из шестнадцати `.opencode` entrypoint documents. Он отклонит сгенерированные формулировки nearest-root/global-default и известные framework planning locations вне `specs/openspec`, исключая `references/**`, `.git`, dependencies и generated outputs из discovery.
|
||
|
||
Verifier намеренно является structural guardrail, а не general natural-language classifier для каждого возможного будущего framework. Policy text запрещает все parallel framework artifacts; verifier защищает known paths и entrypoints, которые могут воспроизвести audited failure. Широкое сканирование всего Markdown или всех directories с именем `plan` отклонено, поскольку оно создаст false positives в durable docs и reference material.
|
||
|
||
### Archive становится hard gate, а evidence фиксируется post-archive, не в task
|
||
|
||
Project-owned archive command и skill остановятся до sync или move change, если любой required planning artifact незавершён, если отсутствует `tasks.md` или если он содержит `- [ ]`. Owner-confirmation override отсутствует. До archive workflow также требует normal verification evidence; после archive он указывает implementer обновить durable registry/history evidence и выполнить commits затронутых repositories.
|
||
|
||
Post-archive work не представляется checkbox в change, потому что archive path нельзя фактически подтвердить до успешного move. Registry/history entry фиксирует actual archive path, commit IDs, commands и observed results после этого события. Это жертвует atomic cross-repository bookkeeping, но не позволяет archived change заявлять о completed tasks при известной incomplete work. Archive workflow, автоматически отмечающий произвольную работу, отклонён, поскольку он производил бы вымышленное evidence.
|
||
|
||
### Historical reconciliation фиксирует current evidence без изменения history
|
||
|
||
Historical archive `2026-08-17-redesign-position-cards` будет согласован на месте только после того, как read-only evidence установит actual archive path и commits затронутых repositories. Его две lifecycle tasks будут отмечены complete рядом с dated reconciliation note, отличающей original archive от текущей evidence review. Не изменяются implementation files, delta specs, archive date или past commits.
|
||
|
||
Оставить его без изменений отклонено, поскольку он останется контрпримером policy. Воссоздать change или изменить Git history отклонено, поскольку это скроет фактическую временную линию.
|
||
|
||
## Риски и компромиссы
|
||
|
||
- [Будущая OpenSpec command не содержит fixed store flag] → verifier использует фиксированный manifest всех шестнадцати текущих entrypoints и должен расширяться в том же change, который добавляет entrypoint.
|
||
- [Новый framework artifact не распознан path-based detection] → instructions задают широкое ограничение, а review и known-location checks verifier дают многоуровневую защиту без false-positive scanning durable docs.
|
||
- [Post-archive registry update прервано] → finding остаётся non-terminal, пока его durable evidence не заполнено; в archive не скрывается incomplete task.
|
||
- [Historical commits невозможно доказать из local history] → tasks остаются unresolved, а недостающее evidence фиксируется вместо ложного утверждения о complete.
|
||
- [Пользователь вручную запускает raw unscoped OpenSpec CLI] → supported commands и instructions остаются scoped; policy не изменяет внешнее поведение CLI.
|
||
|
||
## План миграции
|
||
|
||
1. Добавить формулировки canonical authority и artifact boundaries во все project-owned `AGENTS.md`, затем hard-bind шестнадцать `.opencode` entrypoints.
|
||
2. Добавить read-only verifier и запустить его из workspace и каждого independent repository context.
|
||
3. Заменить archive confirmation branches для incomplete artifacts/tasks на hard failures, потребовать `tasks.md` и задокументировать post-archive evidence sequence.
|
||
4. Добавить durable documentation, объясняющую authority/lifecycle contract, и обновить remediation registry: WL-P1-03 и WL-P1-04 получают статус `active` на время change.
|
||
5. Согласовать historical archive только по observed Git/OpenSpec evidence; если evidence неполно, не отмечать его tasks complete.
|
||
6. Проверить completed change, sync delta specs, архивировать его только при отмеченных tasks, затем добавить actual archive/commit/check evidence в registry и history.
|
||
|
||
Откат ограничен revert commits, добавляющими policy и instructions. Runtime data, API contract, package dependency или external configuration не мигрируются.
|