From ea587970ae6123bb5fe5289a138ef42878dbd7ab Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Sun, 23 Aug 2026 12:40:03 +0300 Subject: [PATCH] docs(specs): add audit remediation workflow plan --- .../.openspec.yaml | 2 + .../design.md | 59 +++++++++++++++++++ .../proposal.md | 26 ++++++++ .../specs/audit-remediation-workflow/spec.md | 38 ++++++++++++ .../specs/project-documentation/spec.md | 12 ++++ .../specs/project-foundation/spec.md | 12 ++++ .../tasks.md | 24 ++++++++ 7 files changed, 173 insertions(+) create mode 100644 openspec/changes/establish-audit-remediation-workflow/.openspec.yaml create mode 100644 openspec/changes/establish-audit-remediation-workflow/design.md create mode 100644 openspec/changes/establish-audit-remediation-workflow/proposal.md create mode 100644 openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md create mode 100644 openspec/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md create mode 100644 openspec/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md create mode 100644 openspec/changes/establish-audit-remediation-workflow/tasks.md diff --git a/openspec/changes/establish-audit-remediation-workflow/.openspec.yaml b/openspec/changes/establish-audit-remediation-workflow/.openspec.yaml new file mode 100644 index 0000000..44f55ff --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-23 diff --git a/openspec/changes/establish-audit-remediation-workflow/design.md b/openspec/changes/establish-audit-remediation-workflow/design.md new file mode 100644 index 0000000..2444027 --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/design.md @@ -0,0 +1,59 @@ +## Context + +См. мотивацию в `proposal.md`. `audit-20-08-2026.md` является dated evidence snapshot в workspace root, а frontend, backend, specs и docs — независимые Git-репозитории. OpenSpec already captures a concrete change, но не даёт сводного состояния всех ещё не начатых audit findings и не связывает terminal status с evidence по нескольким Git roots. + +## Goals / Non-Goals + +**Goals:** + +- Сделать следующую audit-derived задачу однозначной для новой сессии. +- Сохранить неизменяемость исходного аудита и versioned history remediation decisions. +- Связать prioritised finding с canonical OpenSpec change и проверяемым completion evidence. +- Сделать discovery доступным из каждого независимого репозитория без дублирования backlog в `AGENTS.md`. + +**Non-Goals:** + +- Не исправлять runtime code, P1 cache identity или strict TypeScript в этом change. +- Не заменять OpenSpec tasks, archive или существующие feature/ADR docs. +- Не вводить CI, hosted workflow, external issue tracker либо автоматическое обновление registry. +- Не менять archive CLI enforcement: отдельный future change устранит WL-P1-04 на уровне machine gate. + +## Decisions + +### Один versioned registry в `docs/development` + +`docs/development/audit-remediation.md` становится единственным живым обзором audit findings. Dated audit остаётся evidence source и содержит полные доказательства; registry хранит только ID, краткую цель, priority, status, linked change, affected repositories, next action и terminal evidence. Это предотвращает расхождение двух полных копий аудита и даёт Git history именно там, где хранится устойчивая документация. + +Альтернатива — обновлять dated audit checkboxes — отклонена, потому что это смешивает состояние снимка на 20.08.2026 с последующими решениями. Альтернатива — использовать только active/archived OpenSpec directories — отклонена, потому что они не представляют ещё не начатые findings одним приоритетным списком. + +### Реестр контролирует выбор, OpenSpec контролирует реализацию + +Registry допускает не более одной `active` записи и указывает ровно одну следующую рекомендуемую задачу, когда активной нет. `active` допускается только после создания canonical OpenSpec change; tasks/change artifacts являются источником требований и исполнения. В registry все 26 confirmed findings из аудита сначала записываются как `planned`; WL-P1-01 и WL-P1-02 объединяются в следующую задачу `stabilize-frontend-query-and-strict-contracts`. + +Альтернатива — хранить одну общую очередь только в OpenSpec — отклонена: это вынудит agent исследовать множество архивов и не покажет deferred/accepted decisions. + +### Terminal evidence — структурированные поля, а не свободный summary + +Для `done` registry содержит дату, OpenSpec archive path, перечисление `{repository, commit}`, а также точные non-mutating commands и observed results. Для `deferred`/`accepted` он хранит дату, rationale и review trigger или owner decision. На первом этапе проверка структуры выполняется review/verification checklist; её machine enforcement остаётся отдельной задачей, чтобы не смешивать documentation workflow с изменением archive tooling. + +Альтернатива — требовать только ссылку на commit — отклонена: один commit не доказывает покрытие всех затронутых Git roots или успешные checks. + +### Progressive discovery через короткие локальные ссылки + +`docs/development/README.md` индексирует registry. Каждый versioned local `AGENTS.md` в frontend, backend, specs и docs получает короткую ссылку «для audit-derived work прочитать registry и связанный OpenSpec change». Инструкции не копируют statuses и audit details. Root `AGENTS.md` остаётся компактной картой workspace и не становится отдельным, неверсированным backlog source. + +Альтернатива — ссылка только в root `AGENTS.md` — отклонена: agent может открыть один из независимых Git roots напрямую и не получить root context. + +## Risks / Trade-offs + +- [Ручное обновление registry может отстать от change] → tasks каждого audit-derived change включают обновление registry после verification; `done` без evidence не допускается review checklist. +- [Одна active запись ограничивает параллельную работу] → это сознательное ограничение локального MVP для однозначного handoff; изменение правила потребует отдельного решения. +- [Короткие ссылки в четырёх `AGENTS.md` могут drift] → ссылка указывает на один stable path, а изменение registry location требует обновить все ссылки и проверить их в одном change. +- [Evidence может быть слишком объёмным] → registry хранит command/result summary и links; полные логи остаются в terminal/CI-equivalent artifacts, если они появятся позже. + +## Migration Plan + +1. Создать development registry и индекс со всеми confirmed findings от 20.08.2026 в состоянии `planned`. +2. Добавить local instruction links и проверить их из каждого Git root. +3. Пометить `stabilize-frontend-query-and-strict-contracts` как единственную следующую задачу, не создавая этот functional change в данном scope. +4. Проверить change в canonical store; после implementation и archive использовать registry для первого functional remediation change. diff --git a/openspec/changes/establish-audit-remediation-workflow/proposal.md b/openspec/changes/establish-audit-remediation-workflow/proposal.md new file mode 100644 index 0000000..fe95603 --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/proposal.md @@ -0,0 +1,26 @@ +## Why + +Аудит от 20.08.2026 фиксирует подтверждённые технические находки, но сам является неизменяемым снимком и не отвечает, какую задачу продолжать в новой сессии, что уже завершено и каким evidence это подтверждено. Без отдельного реестра агенту приходится заново интерпретировать аудит и OpenSpec archives, из-за чего растёт риск взять не тот change или преждевременно считать находку закрытой. + +## What Changes + +- Добавить долговечный реестр remediation-аудита в `docs/development`, связанный с неизменяемым `audit-20-08-2026.md`. +- Ввести machine-readable-in-spirit правила статусов `planned`, `active`, `done`, `deferred` и `accepted`, включая обязательные поля evidence для каждого terminal status. +- Зафиксировать один путь продолжения работы: реестр указывает одну следующую рекомендуемую задачу и связывает каждую активную работу с canonical OpenSpec change. +- Добавить краткие ссылки на реестр в локальные agent instructions, не дублируя в них backlog. +- Описать, как закрытие OpenSpec change обновляет реестр с archive path, commits и результатами non-mutating verification. + +## Capabilities + +### New Capabilities + +- `audit-remediation-workflow`: единый способ планировать, продолжать и подтверждать исправление findings из технического аудита между сессиями и независимыми Git-репозиториями. + +### Modified Capabilities + +- `project-foundation`: локальные `AGENTS.md` направляют агента к durable remediation registry, когда работа связана с аудитом. +- `project-documentation`: документация процесса хранит remediation registry и доказательства завершения audit-derived changes. + +## Impact + +Затрагиваются `specs/openspec` (новый capability и требования), `docs/development` (реестр и индекс) и короткие ссылки в `AGENTS.md` репозиториев frontend, backend, specs и docs. API, модель данных, runtime-код и зависимости не меняются. Первой функциональной задачей, которую реестр должен сделать однозначно доступной, остаётся будущий change `stabilize-frontend-query-and-strict-contracts` для WL-P1-01 и WL-P1-02. diff --git a/openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md b/openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md new file mode 100644 index 0000000..3edab2a --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/specs/audit-remediation-workflow/spec.md @@ -0,0 +1,38 @@ +## Purpose + +Определяет устойчивый способ продолжать и подтверждать устранение findings технического аудита WealthLedger между сессиями и независимыми репозиториями. + +## ADDED Requirements + +### Requirement: Реестр remediation отделён от снимка аудита +Система SHALL хранить durable remediation registry в репозитории `docs`, а исходный dated audit SHALL оставаться неизменяемым снимком. Каждая запись registry MUST ссылаться на Audit ID и не дублировать полный текст finding, если он уже содержится в аудите. + +#### Scenario: Агент открывает работу по аудиту в новой сессии +- **WHEN** агент получает задачу устранить или продолжить audit finding +- **THEN** он находит linked registry, исходный Audit ID, текущий статус, связанный OpenSpec change и следующее действие без повторной интерпретации всего аудита + +#### Scenario: Обновляется прогресс remediation +- **WHEN** работа по finding меняет статус +- **THEN** dated audit не редактируется, а изменение фиксируется только в 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/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md b/openspec/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md new file mode 100644 index 0000000..01a900e --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/specs/project-documentation/spec.md @@ -0,0 +1,12 @@ +## ADDED Requirements + +### Requirement: Документация процесса содержит remediation registry +Репозиторий `docs` SHALL содержать versioned remediation registry в разделе development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes, следующую рекомендуемую задачу и evidence завершённых remediation changes. + +#### Scenario: Участник проекта ищет состояние технических улучшений +- **WHEN** участник открывает development documentation +- **THEN** он может найти registry через development index и определить, какие 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/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md b/openspec/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md new file mode 100644 index 0000000..41daab2 --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/specs/project-foundation/spec.md @@ -0,0 +1,12 @@ +## MODIFIED Requirements + +### Requirement: Репозитории содержат локальные инструкции для AI-агентов +Система 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 до начала изменения кода diff --git a/openspec/changes/establish-audit-remediation-workflow/tasks.md b/openspec/changes/establish-audit-remediation-workflow/tasks.md new file mode 100644 index 0000000..ade7a86 --- /dev/null +++ b/openspec/changes/establish-audit-remediation-workflow/tasks.md @@ -0,0 +1,24 @@ +## 1. Durable remediation registry + +- [ ] 1.1 Create `docs/development/audit-remediation.md` with the registry contract, allowed statuses, required terminal evidence fields and a link to the immutable `audit-20-08-2026.md`. +- [ ] 1.2 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.3 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.4 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. + +## 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. + +## 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. +- [ ] 4.4 Commit the change separately in each affected Git repository with no unrelated files.