From d0939026fbf5e40a55390688c58a8929f8a23927 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Sun, 23 Aug 2026 13:00:28 +0300 Subject: [PATCH] docs(specs): archive audit remediation workflow --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/audit-remediation-workflow/spec.md | 0 .../specs/project-documentation/spec.md | 0 .../specs/project-foundation/spec.md | 0 .../tasks.md | 26 ++++++------ .../specs/audit-remediation-workflow/spec.md | 40 +++++++++++++++++++ openspec/specs/project-documentation/spec.md | 11 +++++ openspec/specs/project-foundation/spec.md | 6 ++- 10 files changed, 69 insertions(+), 14 deletions(-) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/.openspec.yaml (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/design.md (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/proposal.md (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/specs/audit-remediation-workflow/spec.md (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/specs/project-documentation/spec.md (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/specs/project-foundation/spec.md (100%) rename openspec/changes/{establish-audit-remediation-workflow => archive/2026-08-23-establish-audit-remediation-workflow}/tasks.md (67%) create mode 100644 openspec/specs/audit-remediation-workflow/spec.md diff --git a/openspec/changes/establish-audit-remediation-workflow/.openspec.yaml b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/.openspec.yaml similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/.openspec.yaml rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/.openspec.yaml diff --git a/openspec/changes/establish-audit-remediation-workflow/design.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/design.md similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/design.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/design.md diff --git a/openspec/changes/establish-audit-remediation-workflow/proposal.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/proposal.md similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/proposal.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/proposal.md diff --git a/openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md diff --git a/openspec/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/project-documentation/spec.md similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/project-documentation/spec.md diff --git a/openspec/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/project-foundation/spec.md similarity index 100% rename from openspec/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/specs/project-foundation/spec.md diff --git a/openspec/changes/establish-audit-remediation-workflow/tasks.md b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/tasks.md similarity index 67% rename from openspec/changes/establish-audit-remediation-workflow/tasks.md rename to openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/tasks.md index 9bf86ba..4754ef1 100644 --- a/openspec/changes/establish-audit-remediation-workflow/tasks.md +++ b/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/tasks.md @@ -1,25 +1,25 @@ ## 1. Durable remediation registry -- [ ] 1.1 Copy the immutable `audit-20-08-2026.md` to `docs/audits/audit-20-08-2026.md`, add `docs/audits/README.md`, and record that this versioned file is the canonical evidence source. -- [ ] 1.2 Create `docs/development/audit-remediation.md` with the registry contract, allowed statuses, required terminal evidence fields and a link to the canonical audit snapshot. -- [ ] 1.3 Add one `planned` record for each of the 5 P1, 13 P2 and 8 P3 confirmed findings; preserve Audit IDs, priorities, affected repositories and concise remediation goals without duplicating the full audit text. -- [ ] 1.4 Record that no audit remediation change is active and mark `stabilize-frontend-query-and-strict-contracts` as the sole next recommended change for WL-P1-01 and WL-P1-02. -- [ ] 1.5 Add the registry to `docs/development/README.md` and state that this bootstrap change does not by itself close WL-P2-13 or any other audit finding. +- [x] 1.1 Copy the immutable `audit-20-08-2026.md` to `docs/audits/audit-20-08-2026.md`, add `docs/audits/README.md`, and record that this versioned file is the canonical evidence source. +- [x] 1.2 Create `docs/development/audit-remediation.md` with the registry contract, allowed statuses, required terminal evidence fields and a link to the canonical audit snapshot. +- [x] 1.3 Add one `planned` record for each of the 5 P1, 13 P2 and 8 P3 confirmed findings; preserve Audit IDs, priorities, affected repositories and concise remediation goals without duplicating the full audit text. +- [x] 1.4 Record that no audit remediation change is active and mark `stabilize-frontend-query-and-strict-contracts` as the sole next recommended change for WL-P1-01 and WL-P1-02. +- [x] 1.5 Add the registry to `docs/development/README.md` and state that this bootstrap change does not by itself close WL-P2-13 or any other audit finding. ## 2. Agent discovery -- [ ] 2.1 Add a concise audit-work link and canonical OpenSpec continuation rule to `frontend/AGENTS.md`, `backend/AGENTS.md`, `specs/AGENTS.md` and `docs/AGENTS.md`; do not copy the backlog into those files. -- [ ] 2.2 From each of the four Git roots, verify that the documented relative path resolves to the same registry and that a linked Audit ID leads to the canonical OpenSpec workflow. +- [x] 2.1 Add a concise audit-work link and canonical OpenSpec continuation rule to `frontend/AGENTS.md`, `backend/AGENTS.md`, `specs/AGENTS.md` and `docs/AGENTS.md`; do not copy the backlog into those files. +- [x] 2.2 From each of the four Git roots, verify that the documented relative path resolves to the same registry and that a linked Audit ID leads to the canonical OpenSpec workflow. ## 3. Evidence and review -- [ ] 3.1 Review the registry against `audit-remediation-workflow` scenarios: dated audit remains unmodified, statuses are valid, there is at most one active record, the next task is unique, and no `done` record lacks terminal evidence. -- [ ] 3.2 Run non-mutating checks: `openspec validate establish-audit-remediation-workflow --type change --store wealth-ledger-specs`, `git diff --check` in each affected repository, and a read-only link/record structure check. -- [ ] 3.3 Perform an independent review of registry-to-audit mapping, OpenSpec links, instruction discoverability and unintended scope expansion; resolve every confirmed issue before completion. +- [x] 3.1 Review the registry against `audit-remediation-workflow` scenarios: dated audit remains unmodified, statuses are valid, there is at most one active record, the next task is unique, and no `done` record lacks terminal evidence. +- [x] 3.2 Run non-mutating checks: `openspec validate establish-audit-remediation-workflow --type change --store wealth-ledger-specs`, `git diff --check` in each affected repository, and a read-only link/record structure check. +- [x] 3.3 Perform an independent review of registry-to-audit mapping, OpenSpec links, instruction discoverability and unintended scope expansion; resolve every confirmed issue before completion. ## 4. Completion -- [ ] 4.1 Add this bootstrap change to the registry history with its exact commands and observed results, without marking any audit finding `done`. -- [ ] 4.2 Run `opsx-verify` for the change and resolve every blocking result before archive. -- [ ] 4.3 Archive the change only after all tasks and required evidence are complete; sync resulting delta specs into main specs. +- [x] 4.1 Add this bootstrap change to the registry history with its exact commands and observed results, without marking any audit finding `done`. +- [x] 4.2 Run `opsx-verify` for the change and resolve every blocking result before archive. +- [x] 4.3 Archive the change only after all tasks and required evidence are complete; sync resulting delta specs into main specs. - [ ] 4.4 Commit the change separately in each affected Git repository with no unrelated files. diff --git a/openspec/specs/audit-remediation-workflow/spec.md b/openspec/specs/audit-remediation-workflow/spec.md new file mode 100644 index 0000000..32c6ea5 --- /dev/null +++ b/openspec/specs/audit-remediation-workflow/spec.md @@ -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 сохраняет причину решения и условия, при которых оно должно быть пересмотрено diff --git a/openspec/specs/project-documentation/spec.md b/openspec/specs/project-documentation/spec.md index 944e8fe..858e970 100644 --- a/openspec/specs/project-documentation/spec.md +++ b/openspec/specs/project-documentation/spec.md @@ -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 diff --git a/openspec/specs/project-foundation/spec.md b/openspec/specs/project-foundation/spec.md index 9e6efe3..e813480 100644 --- a/openspec/specs/project-foundation/spec.md +++ b/openspec/specs/project-foundation/spec.md @@ -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.