60 lines
7.2 KiB
Markdown
60 lines
7.2 KiB
Markdown
## 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.
|