docs(specs): archive audit remediation workflow

2026-08-23 13:00:28 +03:00
parent ead48345de
commit d0939026fb
10 changed files with 69 additions and 14 deletions
@@ -0,0 +1,40 @@
+# audit-remediation-workflow Specification
+
+## Purpose
+
+Определяет устойчивый способ продолжать и подтверждать устранение findings технического аудита WealthLedger между сессиями и независимыми репозиториями.
+
+## Requirements
+
+### Requirement: Реестр remediation отделён от снимка аудита
+Система SHALL хранить неизменяемый versioned audit snapshot в `docs/audits` и durable remediation registry в `docs/development`. Snapshot SHALL оставаться source of facts; registry SHALL хранить только текущее состояние remediation. Каждая запись registry MUST ссылаться на Audit ID и не дублировать полный текст finding, если он уже содержится в snapshot.
+
+#### Scenario: Агент открывает работу по аудиту в новой сессии
+- **WHEN** агент получает задачу устранить или продолжить audit finding
+- **THEN** он находит linked registry, исходный Audit ID, текущий статус, связанный OpenSpec change и следующее действие без повторной интерпретации всего аудита
+
+#### Scenario: Обновляется прогресс remediation
+- **WHEN** работа по finding меняет статус
+- **THEN** versioned audit snapshot не редактируется, а изменение фиксируется только в registry с датой и необходимым evidence
+
+### Requirement: Registry задаёт однозначный статус и следующий change
+Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. Registry MUST содержать не более одного `active` change и ровно одну следующую рекомендуемую задачу, пока остаются findings со статусом `planned`.
+
+#### Scenario: В рабочей области нет активного remediation change
+- **WHEN** агент открывает registry и все незакрытые findings имеют статус `planned`
+- **THEN** он может выбрать ровно одну строку, отмеченную как следующая рекомендуемая задача, и создать связанный canonical OpenSpec change
+
+#### Scenario: В рабочей области уже есть активный remediation change
+- **WHEN** registry содержит запись со статусом `active`
+- **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 и условие пересмотра либо ссылку на явное решение владельца.
+
+#### Scenario: Change готовится к завершению
+- **WHEN** implementer хочет поставить связанный finding в `done`
+- **THEN** registry содержит полный набор evidence, а tasks change и требуемая OpenSpec verification завершены до обновления статуса
+
+#### Scenario: Риск сознательно не исправляется сейчас
+- **WHEN** владелец переносит finding или принимает риск
+- **THEN** registry сохраняет причину решения и условия, при которых оно должно быть пересмотрено
@@ -26,3 +26,14 @@
 #### Scenario: Команда пытается архивировать незавершенное изменение
 - **WHEN** для изменения отсутствует реализация, верификация или feature-документ
 - **THEN** изменение не считается готовым к архивированию
+
+### Requirement: Документация процесса содержит remediation registry
+Репозиторий `docs` SHALL содержать immutable versioned audit snapshots в `docs/audits` и versioned remediation registry в разделе development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes, следующую рекомендуемую задачу и evidence завершённых remediation changes.
+
+#### Scenario: Участник проекта ищет состояние технических улучшений
+- **WHEN** участник открывает development documentation
+- **THEN** он может найти audit snapshot и registry через documentation indexes и определить, какие findings planned, active, done, deferred или accepted
+
+#### Scenario: Завершён audit-derived change
+- **WHEN** связанный OpenSpec change архивирован после успешной проверки
+- **THEN** registry обновляется с archive path, commits затронутых репозиториев и результатами exact verification commands
@@ -7,12 +7,16 @@
 ## Requirements

 ### Requirement: Репозитории содержат локальные инструкции для AI-агентов
-Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами.
+Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами. Локальные инструкции MUST направлять агента к durable remediation registry, когда задача связана с findings технического аудита.

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

+#### Scenario: Агент получает audit-derived задачу из отдельного репозитория
+- **WHEN** задача ссылается на finding технического аудита
+- **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical OpenSpec workflow до начала изменения кода
+
 ### Requirement: Локальный план MVP не является источником спецификации
 Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs.