specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/design.md

Context

См. мотивацию в proposal.md. Корневой audit-20-08-2026.md является исходной локальной копией dated evidence snapshot; её versioned canonical copy будет храниться в docs/audits/audit-20-08-2026.md. 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 snapshot в docs/audits и один registry в docs/development

docs/audits/audit-20-08-2026.md становится неизменяемым canonical evidence source под Git. docs/development/audit-remediation.md становится единственным живым обзором audit findings и хранит только ID, краткую цель, priority, status, linked change, affected repositories, next action и terminal evidence. Это предотвращает расхождение двух полных копий аудита, отделяет historical evidence от текущего workflow и даёт Git history в durable documentation repository.

Альтернатива — хранить evidence snapshot внутри OpenSpec change — отклонена: archive перемещает change и делает постоянную ссылку нестабильной. Альтернатива — обновлять 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/audits/README.md индексирует immutable snapshots, а docs/development/README.md — registry. Каждый versioned local AGENTS.md в frontend, backend, specs и docs получает короткую ссылку «для audit-derived work прочитать registry, snapshot и связанный 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. Скопировать immutable audit snapshot в docs/audits, добавить index и зафиксировать его как canonical source для registry.
2. Создать development registry и индекс со всеми confirmed findings от 20.08.2026 в состоянии planned.
3. Добавить local instruction links и проверить их из каждого Git root.
4. Пометить stabilize-frontend-query-and-strict-contracts как единственную следующую задачу, не создавая этот functional change в данном scope.
5. Проверить change в canonical store; после implementation и archive использовать registry для первого functional remediation change.