feat: harden OpenSpec SDD workflow

2026-08-26 00:42:35 +03:00
parent 039b72eed3
commit a8b2c4eed9
42 changed files with 4024 additions and 181 deletions
@@ -7,20 +7,29 @@
 ## Requirements

 ### Requirement: Реестр remediation отделён от снимка аудита
-Система SHALL создавать отдельный неизменяемый versioned audit snapshot в `docs/audits` для каждого завершённого аудита и SHALL поддерживать один актуальный durable remediation registry в `docs/development`, охватывающий findings всех audit snapshots. Каждый snapshot SHALL оставаться source of facts своего аудита и MUST NOT редактироваться для отражения последующей remediation. Registry SHALL хранить текущее состояние, связанный canonical change, следующее действие и completion evidence каждой записи, MUST ссылаться на однозначный Audit ID и исходный snapshot и MUST NOT дублировать полный текст finding, если он уже содержится в snapshot.
+
+Система SHALL создавать отдельный неизменяемый versioned audit snapshot в `docs/audits` для каждого завершённого аудита и SHALL поддерживать один актуальный durable remediation registry в `docs/development`, охватывающий findings всех audit snapshots. Для завершённого multi-source audit система SHALL сохранять каждый source file byte-for-byte и объединять их одним snapshot index. Каждый snapshot SHALL оставаться source of claims своего аудита и MUST NOT редактироваться для отражения последующей remediation. Внешняя модельная оценка MUST быть обозначена как неавторитетный источник claims и MUST NOT подменять requirements, governance или проверенное состояние проекта. Registry SHALL хранить текущее состояние, связанный canonical change, следующее действие и completion evidence каждой записи, MUST ссылаться на однозначный Audit ID и каждый относящийся source snapshot и MUST NOT дублировать полный текст finding, если он уже содержится в snapshot.

 #### Scenario: Агент открывает работу по аудиту в новой сессии
+
 - **WHEN** агент получает задачу устранить или продолжить finding из любого завершённого аудита
 - **THEN** он находит в едином registry исходный snapshot и Audit ID, текущий статус, связанный OpenSpec change, evidence и следующее действие без повторной интерпретации всех аудитов

 #### Scenario: Проводится повторный аудит
+
 - **WHEN** новый аудит завершён после предыдущего audit snapshot
 - **THEN** система добавляет новый immutable snapshot и обновляет тот же live registry, не переписывая предыдущий snapshot и не создавая конкурирующий registry

 #### Scenario: Обновляется прогресс remediation
+
 - **WHEN** работа по finding меняет статус
 - **THEN** versioned audit snapshots не редактируются, а изменение фиксируется только в live registry с датой и необходимым evidence

+#### Scenario: Один аудит содержит несколько внешних оценок
+
+- **WHEN** завершённая assessment использовала несколько независимых source reports
+- **THEN** snapshot index связывает byte-for-byte сохранённые reports в один audit и явно отделяет их claims от project authority
+
 ### Requirement: Registry задаёт однозначный статус и следующий change
 Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. `planned` MUST означать согласованную работу, которую можно начать без внешнего review trigger; запись, ожидающая версии зависимости, внешнего события или отдельного решения владельца, MUST иметь статус `deferred` с условием пересмотра. Registry MUST содержать не более одного `active` remediation change и ровно одну следующую рекомендуемую задачу, пока существуют findings со статусом `planned`.

@@ -46,3 +55,22 @@ Registry SHALL NOT представлять finding как `done` без дат
 #### Scenario: Риск сознательно не исправляется сейчас
 - **WHEN** владелец переносит finding или принимает риск
 - **THEN** registry сохраняет причину решения и условия, при которых оно должно быть пересмотрено
+
+### Requirement: Каждое audit claim получает доказательный disposition
+
+Каждое уникальное claim завершённого multi-source audit MUST входить ровно в один нормализованный Audit ID и иметь triage disposition `confirmed`, `already-covered`, `rejected` или `deferred`. Нормализованная запись MUST ссылаться на каждый source report, содержащий claim. `confirmed` MUST связываться с remediation status и change либо terminal evidence; `already-covered` MUST приводить проверяемое существующее evidence; `rejected` MUST содержать конкретное rationale; `deferred` MUST содержать review trigger. Triage disposition MUST оставаться отдельным от remediation status `planned`, `active`, `done`, `deferred` или `accepted`, чтобы внешняя рекомендация не становилась принятой policy без проверки.
+
+#### Scenario: Несколько моделей повторяют одно замечание
+
+- **WHEN** два или более source reports описывают один и тот же underlying gap
+- **THEN** registry содержит один нормализованный Audit ID со ссылками на все источники и одним доказательным disposition
+
+#### Scenario: Рекомендация уже реализована
+
+- **WHEN** проверяемое состояние проекта полностью покрывает external claim
+- **THEN** disposition `already-covered` ссылается на существующий requirement, guardrail или completion evidence без создания фиктивной remediation work
+
+#### Scenario: Внешняя рекомендация противоречит authority
+
+- **WHEN** source report предлагает неподдерживаемый либо ухудшающий действующий invariant подход
+- **THEN** disposition `rejected` фиксирует конкретное противоречие и не превращает recommendation в requirement
@@ -67,3 +67,22 @@

 - **WHEN** change объявляет новое правило блокирующим
 - **THEN** completion evidence подтверждает как успешный compliant case, так и обнаружение контролируемого representative violation
+
+### Requirement: Труднообратимое изменение имеет rollback contract
+
+Design MUST определять rollback trigger, rollback actions, data safety и rollback verification, когда change затрагивает auth или security behavior, data integrity или migration, public contract либо другое существенно труднообратимое решение. Rollback contract MUST учитывать данные и совместимость, созданные после поставки change, и MUST быть выполним без нового неутверждённого архитектурного решения. Когда указанные риски неприменимы, Design SHALL фиксировать конкретную проверяемую причину `N/A` и MUST NOT создавать отдельный artifact или формальный rollback plan ради процесса.
+
+#### Scenario: Change мигрирует данные
+
+- **WHEN** Design изменяет хранимые данные способом, который может потребовать возврата
+- **THEN** он определяет trigger, безопасные действия отката, судьбу новых данных и проверку восстановленного состояния до утверждения Tasks
+
+#### Scenario: Change меняет публичный контракт
+
+- **WHEN** Design вводит несовместимое изменение публичного контракта
+- **THEN** rollback contract объясняет восстановление совместимости и проверяемое условие успешного отката
+
+#### Scenario: Rollback risk отсутствует
+
+- **WHEN** change не затрагивает auth, security, данные, публичный контракт или другое труднообратимое решение
+- **THEN** Design указывает конкретную причину `N/A` без создания дополнительного rollback artifact
@@ -61,3 +61,41 @@ Workspace SHALL предоставлять один non-mutating локальн

 - **WHEN** общий verifier проверяет несколько affected областей и канонический gate одной из них не проходит
 - **THEN** общий результат является неуспешным и явно указывает failing area без обхода её локального gate
+
+### Requirement: Каждая задача объявляет единственную delivery area
+
+Каждый checkbox Tasks MUST объявлять ровно одного owner из `frontend`, `backend`, `specs`, `docs` или `workspace`. Implementation work, изменяющая несколько Git-репозиториев, MUST быть разделена на repository-owned tasks; `workspace` SHALL использоваться только для cross-area orchestration или verification без владения repository implementation. Для каждой `affected` area Tasks MUST содержать её implementation work и canonical local gate, а task ownership MUST соответствовать утверждённому Delivery Map.
+
+#### Scenario: Change затрагивает frontend и backend
+
+- **WHEN** одна delivery intent требует изменения клиента и API
+- **THEN** Tasks содержит отдельные frontend-owned и backend-owned checkbox items вместо одной общей implementation task
+
+#### Scenario: Выполняется общий verification gate
+
+- **WHEN** задача только оркестрирует проверку нескольких affected areas и не изменяет их implementation
+- **THEN** task использует owner `workspace` и не подменяет repository-owned implementation или canonical gates
+
+#### Scenario: Task ссылается на N/A area
+
+- **WHEN** checkbox объявляет owner области, которая имеет статус `N/A` в Delivery Map
+- **THEN** planning validation завершается ошибкой и указывает несогласованную delivery area
+
+### Requirement: Tasks трассируются к утверждённым требованиям
+
+Каждый checkbox Tasks MUST содержать coverage reference: одну или несколько пар из точного capability path и точного Requirement heading либо `N/A` с конкретной причиной для работы, которая не реализует spec-level behavior. Каждый Requirement из Delta Specs MUST быть покрыт хотя бы одной task. Planning validation MUST отклонять отсутствующее покрытие, ссылку на несуществующий capability или Requirement и пустую причину `N/A`. Traceability SHALL использовать нативную идентичность requirement и MUST NOT вводить параллельный namespace собственных requirement IDs.
+
+#### Scenario: Delta requirement покрыт реализацией
+
+- **WHEN** Tasks планирует поставку изменённого requirement
+- **THEN** хотя бы один checkbox ссылается на точный capability path и Requirement heading этого delta
+
+#### Scenario: Задача не меняет spec-level behavior
+
+- **WHEN** task обновляет infrastructure, documentation или verification без самостоятельного requirement
+- **THEN** coverage reference содержит `N/A` и конкретно объясняет отсутствие spec-level связи
+
+#### Scenario: Requirement остался без задачи
+
+- **WHEN** хотя бы один Requirement из Delta Specs не указан ни в одной coverage reference
+- **THEN** planning validation блокирует approval Tasks и перечисляет uncovered Requirement
@@ -35,7 +35,7 @@ Versioned SDD change SHALL проходить последовательност

 ### Requirement: Изменение upstream artifact требует каскадной проверки

-Изменение утверждённого Proposal MUST инициировать повторную проверку Delta Specs, Design и Tasks; изменение утверждённых Delta Specs MUST инициировать повторную проверку Design и Tasks; изменение утверждённого Design MUST инициировать повторную проверку Tasks. Изменение Tasks MUST NOT неявно менять scope, наблюдаемое поведение или архитектурные решения upstream artifacts; при таком обнаружении workflow SHALL вернуть работу к соответствующему upstream artifact и его approval gate.
+Изменение утверждённого Proposal MUST инициировать повторную проверку Delta Specs, Design и Tasks; изменение утверждённых Delta Specs MUST инициировать повторную проверку Design и Tasks; изменение утверждённого Design MUST инициировать повторную проверку Tasks. Изменение Tasks MUST NOT неявно менять scope, наблюдаемое поведение или архитектурные решения upstream artifacts; при таком обнаружении workflow SHALL вернуть работу к самому раннему затронутому upstream artifact и его approval gate. Если несоответствие обнаружено во время Design или Apply, downstream-работа MUST остановиться, а Change Owner MUST получить наблюдаемое основание возврата и решения, требуемые на выбранном уровне. Механическое исправление синтаксиса или формата, которое не меняет утверждённые намерение, поведение, архитектурные решения или состав задач, MUST пройти повторную structural validation и MUST NOT само по себе инвалидировать approvals.

 #### Scenario: После Design изменилось намерение

@@ -47,6 +47,16 @@ Versioned SDD change SHALL проходить последовательност
 - **WHEN** implementation checklist требует поведение, которого нет в утверждённых Delta Specs
 - **THEN** агент не расширяет scope через Tasks и возвращает change к Delta Specs

+#### Scenario: Apply выявляет архитектурное расхождение
+
+- **WHEN** во время реализации обнаружено, что утверждённый Design не позволяет выполнить Specs без другого архитектурного решения
+- **THEN** Apply останавливается, Tasks теряет прежнее подтверждение, а change возвращается к Design с наблюдаемым основанием и вариантами решения
+
+#### Scenario: Исправляется только структурный формат
+
+- **WHEN** утверждённый artifact содержит исправимую синтаксическую или formatting-ошибку без изменения его смысла
+- **THEN** workflow исправляет ошибку, повторяет structural validation и сохраняет действующие approvals
+
 ### 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, текущей директории или глобального значения по умолчанию машины.

@@ -82,7 +92,7 @@ Canonical store и policy расположения artifacts SHALL иметь do

 ### Requirement: OpenSpec tooling имеет проверяемый version contract

-SDD workflow MUST объявлять поддерживаемую версию OpenSpec CLI и проверять фактическую версию до команд, читающих или изменяющих canonical change. Несовместимая либо неопределённая версия MUST давать actionable blocking result и MUST NOT приводить к молчаливому изменению artifact graph, templates или project-owned entrypoints.
+SDD workflow MUST объявлять одну текущую поддерживаемую версию OpenSpec CLI в canonical version contract и проверять фактическую версию до команд, читающих или изменяющих canonical change. Normative checks и проверяемые generated markers MUST получать ожидаемую версию из этого контракта и MUST NOT независимо закреплять конкретный version literal. Несовместимая либо неопределённая версия MUST давать actionable blocking result и MUST NOT приводить к молчаливому изменению artifact graph, templates или project-owned entrypoints. Публикация новой stable версии MUST NOT автоматически менять поддерживаемую версию проекта. Upgrade SHALL изменять version contract только после изолированной проверки совместимости schema, agent workflow, canonical store и hard blockers и SHALL сохранять историческое evidence с фактически использованными ранее версиями.

 #### Scenario: Версия CLI соответствует контракту

@@ -94,6 +104,16 @@ SDD workflow MUST объявлять поддерживаемую версию O
 - **WHEN** доступная версия OpenSpec не совпадает с объявленным совместимым контрактом
 - **THEN** локальная preflight-проверка блокирует SDD-операцию и сообщает ожидаемую и фактическую версии

+#### Scenario: Опубликована новая stable версия
+
+- **WHEN** upstream публикует новую stable версию, которая ещё не прошла project compatibility assessment
+- **THEN** текущий version contract остаётся действующим и новая версия не становится неявным требованием для разработки
+
+#### Scenario: Подготовлен upgrade candidate
+
+- **WHEN** Engineering Owner рассматривает смену поддерживаемой версии
+- **THEN** изолированная проверка подтверждает schema, agent workflow, store selection и hard blockers до изменения version contract и project-owned projection
+
 ### Requirement: Structural и semantic verification являются разными gates

 OpenSpec structural validation SHALL проверять schema, artifact graph и формальную корректность specs, но MUST NOT считаться доказательством соответствия реализации. До terminal status change MUST пройти semantic verification реализации против Proposal, Delta Specs, Design и Tasks, а затем независимый read-only review. Если основной agent entrypoint semantic verification недоступен, workflow SHALL использовать versioned эквивалентную процедуру с теми же входными артефактами, категориями проверки и наблюдаемым evidence.
@@ -122,3 +142,31 @@ Project-owned archive workflow MUST отклонять archive, если отс
 #### Scenario: Change завершил все tasks
 - **WHEN** каждый planning artifact утверждён, каждый task отмечен, required verification, implementation и pre-archive gates всех affected areas успешно завершены
 - **THEN** workflow допускает archive и фиксирует его результат через определённый completion-evidence path без создания post-archive task
+
+### Requirement: Project-owned agent workflow воспроизводим из versioned authority
+
+Project-owned agent workflow SHALL восстанавливаться в новом workspace из committed authority inputs и текущей поддерживаемой версии инструмента без использования прежнего локального generated state. Workspace-level projection SHALL оставаться derived output и MUST NOT становиться конкурирующим SDD authority. Non-mutating verifier MUST обнаруживать отсутствие required projection, расхождение с versioned inputs и несовместимый generated version marker; установленные зависимости и machine-local runtime state MUST NOT считаться authority inputs.
+
+#### Scenario: Workspace собирается заново
+
+- **WHEN** участник получает чистые checkout всех project repositories и поддерживаемый инструмент
+- **THEN** documented workflow воспроизводит project-owned agent projection из versioned inputs без копирования файлов с прежней машины
+
+#### Scenario: Derived projection изменена вручную
+
+- **WHEN** локальная project-owned projection больше не соответствует versioned authority inputs
+- **THEN** non-mutating verifier завершает проверку ошибкой и указывает на projection drift
+
+### Requirement: Planning artifact проверяется до запроса approval
+
+Каждый создаваемый planning artifact SHALL пройти все применимые на его текущем этапе non-mutating structural checks до запроса approval Change Owner. Если полный change validation ещё заблокирован отсутствующими downstream artifacts, workflow MUST выполнить доступные проверки текущего artifact и явно оставить недоступную проверку незавершённой, а не заявлять общий успех. Техническая ошибка проверяемого формата SHALL исправляться и проверяться повторно без передачи ручного исправления Change Owner; structural success MUST NOT подменять semantic approval.
+
+#### Scenario: Текущий artifact имеет проверяемое нарушение
+
+- **WHEN** сгенерированный planning artifact нарушает обязательный формат или ссылочную целостность, доступные для проверки на текущем этапе
+- **THEN** workflow исправляет нарушение и повторяет structural checks до запроса owner approval
+
+#### Scenario: Downstream artifacts ещё отсутствуют
+
+- **WHEN** Proposal создан, а Delta Specs, Design и Tasks ещё не существуют
+- **THEN** workflow сообщает результат доступных Proposal checks и не представляет отсутствующую full-change validation как успешную