docs(specs): harden OpenSpec authority lifecycle

2026-08-23 17:49:52 +03:00
parent b8a3f96316
commit 51344d4988
18 changed files with 608 additions and 13 deletions
@@ -29,11 +29,11 @@
 - **THEN** агент продолжает связанный change и не создаёт второй remediation change без явного решения владельца

 ### Requirement: Terminal status подтверждён проверяемым evidence
-Registry SHALL NOT представлять finding как `done` без даты, archive path связанного OpenSpec change, commit identifiers для каждого затронутого Git-репозитория и точных non-mutating verification commands с результатами. Статусы `deferred` и `accepted` MUST содержать дату, rationale и условие пересмотра либо ссылку на явное решение владельца.
+Registry SHALL NOT представлять finding как `done` без даты, archive path связанного OpenSpec change, commit identifiers для каждого затронутого Git-репозитория и точных non-mutating verification commands с результатами. Архивированный audit-derived change MUST иметь все tasks завершёнными до archive; completion evidence после archive MUST быть отдельной записью registry или history, а не незакрытым task в archived change. Статусы `deferred` и `accepted` MUST содержать дату, rationale и условие пересмотра либо ссылку на явное решение владельца.

 #### Scenario: Change готовится к завершению
 - **WHEN** implementer хочет поставить связанный finding в `done`
- **THEN** registry содержит полный набор evidence, а tasks change и требуемая OpenSpec verification завершены до обновления статуса
+- **THEN** все tasks change и требуемая OpenSpec verification завершены до archive, а registry содержит полный набор post-archive evidence

 #### Scenario: Риск сознательно не исправляется сейчас
 - **WHEN** владелец переносит finding или принимает риск
@@ -7,7 +7,7 @@
 ## Requirements

 ### Requirement: User can retrieve an account ledger
-Система ДОЛЖНА предоставлять аутентифицированный журнал только для чтения одного Brokerage Account, принадлежащего текущему User. Журнал ДОЛЖЕН содержать только исполненные операции T-Bank и при отсутствии периода по умолчанию охватывать интервал от начала текущего календарного года до момента запроса.
+Система MUST предоставлять аутентифицированный журнал только для чтения одного Brokerage Account, принадлежащего текущему User. Журнал MUST содержать только исполненные операции T-Bank и при отсутствии периода по умолчанию охватывать интервал от начала текущего календарного года до момента запроса.

 #### Scenario: Получение журнала с периодом по умолчанию
 - **WHEN** аутентифицированный User запрашивает журнал принадлежащего ему Brokerage Account без периода
@@ -18,7 +18,7 @@
 - **THEN** система возвращает существующий ответ о недоступности счёта и не раскрывает операции

 ### Requirement: User can browse a filtered ledger
-Система ДОЛЖНА позволять User ограничивать журнал включительным периодом дат и любым подмножеством категорий trade, income, tax, fee, transfer, other. Система ДОЛЖНА разбивать упорядоченный результат на страницы с непрозрачным cursor и возвращать признак доступности следующей страницы.
+Система MUST позволять User ограничивать журнал включительным периодом дат и любым подмножеством категорий trade, income, tax, fee, transfer, other. Система MUST разбивать упорядоченный результат на страницы с непрозрачным cursor и возвращать признак доступности следующей страницы.

 #### Scenario: Фильтрация доходных операций за период
 - **WHEN** User запрашивает период дат и категорию income
@@ -29,7 +29,7 @@
 - **THEN** система возвращает следующую страницу без повторения записей предыдущей страницы

 ### Requirement: Ledger entries preserve broker operation meaning
-Система ДОЛЖНА представлять одну upstream-операцию одной записью журнала и ДОЛЖНА передавать её timestamp, тип операции, категорию, описание, доступные идентификаторы инструмента, денежную выплату, количество, цену, НКД и комиссию. Денежные поля ДОЛЖНЫ сохранять исходную валюту и точное десятичное значение.
+Система MUST представлять одну upstream-операцию одной записью журнала и MUST передавать её timestamp, тип операции, категорию, описание, доступные идентификаторы инструмента, денежную выплату, количество, цену, НКД и комиссию. Денежные поля MUST сохранять исходную валюту и точное десятичное значение.

 #### Scenario: Отображение купонной выплаты
 - **WHEN** T-Bank возвращает исполненную купонную операцию с выплатой и данными инструмента
@@ -44,7 +44,7 @@
 - **THEN** запись журнала передаёт доступное количество и не содержит искусственной денежной выплаты с нулевым значением

 ### Requirement: Account overview includes recent ledger events
-Обзор счёта ДОЛЖЕН показывать пять последних исполненных записей журнала этого счёта и действие перехода к его полному журналу. Неуспешный или пустой запрос последних записей ДОЛЖЕН оставаться локальным состоянием блока последних событий и НЕ ДОЛЖЕН заменять успешно отображённый обзор Portfolio.
+Обзор счёта MUST показывать пять последних исполненных записей журнала этого счёта и действие перехода к его полному журналу. Неуспешный или пустой запрос последних записей MUST оставаться локальным состоянием блока последних событий и MUST NOT заменять успешно отображённый обзор Portfolio.

 #### Scenario: Отображение последних событий
 - **WHEN** загружается обзор счёта и его журнал содержит исполненные операции
@@ -55,7 +55,7 @@
 - **THEN** обзор Portfolio остаётся доступным, а блок последних событий отображает собственное состояние восстановления

 ### Requirement: Full ledger presents compact rows
-Страница полного журнала ДОЛЖНА показывать для каждой записи дату, тип операции, инструмент и денежное изменение в исходной валюте. Она ДОЛЖНА обозначать записи без движения денег и НЕ ДОЛЖНА показывать цену или количество.
+Страница полного журнала MUST показывать для каждой записи дату, тип операции, инструмент и денежное изменение в исходной валюте. Она MUST обозначать записи без движения денег и MUST NOT показывать цену или количество.

 #### Scenario: Отображение записи только с инструментом
 - **WHEN** полный журнал отображает запись без денежной выплаты
@@ -0,0 +1,50 @@
+# openspec-authority-and-lifecycle Specification
+
+## Purpose
+Определяет единственный источник полномочий для OpenSpec и проверяемый жизненный цикл SDD-изменений независимо от текущей директории, глобальной конфигурации или agent framework.
+
+## Requirements
+
+### Requirement: Канонический authority OpenSpec задан явно
+WealthLedger SHALL использовать зарегистрированный store `wealth-ledger-specs` с физическим OpenSpec root `specs/openspec` как единственный поддерживаемый authority для versioned SDD artifacts. Каждый project-owned OpenSpec entrypoint и documented OpenSpec command MUST явно выбирать `--store wealth-ledger-specs`; он MUST NOT выбирать store из ближайшего root, текущей директории или глобального значения по умолчанию машины.
+
+#### Scenario: Агент начинает SDD-работу из репозитория приложения
+- **WHEN** агент начинает, продолжает, проверяет, синхронизирует или архивирует OpenSpec change из `frontend`, `backend`, `docs` или workspace root
+- **THEN** documented workflow явно выбирает `wealth-ledger-specs` и разрешает artifacts под `specs/openspec`
+
+#### Scenario: В окружении есть другой OpenSpec store или значение по умолчанию
+- **WHEN** машина имеет другой зарегистрированный OpenSpec store или другое глобальное значение по умолчанию
+- **THEN** project-owned entrypoints всё равно используют `wealth-ledger-specs` и не выполняют fallback к другому root
+
+### Requirement: Versioned planning artifacts имеют единственное допустимое расположение
+Система SHALL хранить committed OpenSpec specifications, changes, designs, delta specifications, tasks и archives только под `specs/openspec`. Она MUST NOT создавать или коммитить framework-specific planning, specification, task или design artifacts вне этого расположения, включая `superpowers/plans`. Это ограничение MUST NOT изменять или удалять read-only material под `references/**`.
+
+#### Scenario: Агент фиксирует функциональное изменение
+- **WHEN** агенту нужно зафиксировать requirements, design decisions или implementation tasks для функционального change
+- **THEN** он создаёт versioned SDD artifacts в canonical OpenSpec store и не создаёт parallel framework artifact вне него
+
+#### Scenario: Агент изучает reference material
+- **WHEN** агент встречает framework artifacts под `references/**`
+- **THEN** он рассматривает их как read-only reference content и не классифицирует их как нарушение policy
+
+### Requirement: Authority policy имеет read-only verifier
+Canonical store и policy расположения artifacts SHALL иметь documented read-only verifier. Verifier MUST возвращать ненулевой результат, когда project-owned OpenSpec entrypoint не выбирает canonical store, когда запрещённый project-owned planning artifact существует вне `specs/openspec`, или когда существует дополнительный project-owned `openspec/` root; он MUST исключать `references/**` из проверок расположения artifacts.
+
+#### Scenario: Canonical authority остаётся целостным
+- **WHEN** verifier запускается в compliant workspace
+- **THEN** он завершается без изменения tracked files и сообщает об успехе
+
+#### Scenario: Entry point вновь допускает неявный выбор store
+- **WHEN** project-owned OpenSpec entrypoint допускает выбор nearest-root или global-default
+- **THEN** verifier завершается ошибкой и указывает non-compliant entrypoint
+
+### Requirement: Archive блокируется незавершёнными tasks
+Project-owned archive workflow MUST отклонять archive, пока его `tasks.md` содержит любой unchecked task. Post-archive bookkeeping MUST NOT появляться как unchecked task; он SHALL фиксироваться через детерминированное completion evidence после успешного archive.
+
+#### Scenario: Change имеет unchecked task
+- **WHEN** implementer запрашивает archive и остаётся хотя бы один unchecked task
+- **THEN** workflow не архивирует change и сообщает incomplete tasks как blocking condition
+
+#### Scenario: Change завершил все tasks
+- **WHEN** каждый task отмечен и required verification успешно завершена
+- **THEN** workflow допускает archive и фиксирует его результат через определённый completion-evidence path без создания post-archive task
@@ -37,3 +37,14 @@
 #### Scenario: Завершён audit-derived change
 - **WHEN** связанный OpenSpec change архивирован после успешной проверки
 - **THEN** registry обновляется с archive path, commits затронутых репозиториев и результатами exact verification commands
+
+### Requirement: Durable documentation is not a parallel SDD store
+Репозиторий `docs` SHALL хранить только долговечную architecture, development, feature, audit и remediation documentation вместе с completion evidence. Change-specific requirements, designs, delta specifications и tasks MUST храниться только в canonical OpenSpec store и MUST NOT создаваться как framework-specific planning artifacts в `docs`.
+
+#### Scenario: Change требует постоянной документации
+- **WHEN** завершённый change должен оставить устойчивое объяснение решения или evidence
+- **THEN** documentation фиксирует реализованное решение или completion evidence и ссылается на canonical OpenSpec change без дублирования его requirements, design или tasks
+
+#### Scenario: Agent планирует незавершённый change
+- **WHEN** агент создаёт requirements, design или tasks для незавершённого изменения
+- **THEN** он сохраняет их под `specs/openspec` и не создаёт framework-specific planning document в `docs`
@@ -7,15 +7,15 @@
 ## Requirements

 ### Requirement: Репозитории содержат локальные инструкции для AI-агентов
-Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита.
+Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых OpenSpec операций и запрещать versioned framework-specific planning artifacts вне canonical store. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита.

 #### Scenario: Агент начинает работу в отдельном репозитории
 - **WHEN** агент открывает любой из репозиториев frontend, backend, specs или docs
- **THEN** он может определить локальные правила работы и источник связанных спецификаций из `AGENTS.md` этого репозитория
+- **THEN** он может определить локальные правила работы, canonical OpenSpec authority и источник связанных спецификаций из `AGENTS.md` этого репозитория

 #### Scenario: Агент получает audit-derived задачу из отдельного репозитория
 - **WHEN** задача ссылается на finding технического аудита
- **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical OpenSpec workflow до начала изменения кода
+- **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical OpenSpec workflow с явным store selection до начала изменения кода

 ### Requirement: Локальный план MVP не является источником спецификации
 Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs.