docs(specs): version audit snapshot in docs
This commit is contained in:
@@ -1,6 +1,6 @@
|
|||||||
## Context
|
## 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.
|
См. мотивацию в `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 / Non-Goals
|
||||||
|
|
||||||
@@ -20,11 +20,11 @@
|
|||||||
|
|
||||||
## Decisions
|
## Decisions
|
||||||
|
|
||||||
### Один versioned registry в `docs/development`
|
### Versioned snapshot в `docs/audits` и один 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 именно там, где хранится устойчивая документация.
|
`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.
|
||||||
|
|
||||||
Альтернатива — обновлять dated audit checkboxes — отклонена, потому что это смешивает состояние снимка на 20.08.2026 с последующими решениями. Альтернатива — использовать только active/archived OpenSpec directories — отклонена, потому что они не представляют ещё не начатые findings одним приоритетным списком.
|
Альтернатива — хранить evidence snapshot внутри OpenSpec change — отклонена: archive перемещает change и делает постоянную ссылку нестабильной. Альтернатива — обновлять dated audit checkboxes — отклонена, потому что это смешивает состояние снимка на 20.08.2026 с последующими решениями. Альтернатива — использовать только active/archived OpenSpec directories — отклонена, потому что они не представляют ещё не начатые findings одним приоритетным списком.
|
||||||
|
|
||||||
### Реестр контролирует выбор, OpenSpec контролирует реализацию
|
### Реестр контролирует выбор, OpenSpec контролирует реализацию
|
||||||
|
|
||||||
@@ -40,7 +40,7 @@ Registry допускает не более одной `active` записи и
|
|||||||
|
|
||||||
### Progressive discovery через короткие локальные ссылки
|
### 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.
|
`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.
|
Альтернатива — ссылка только в root `AGENTS.md` — отклонена: agent может открыть один из независимых Git roots напрямую и не получить root context.
|
||||||
|
|
||||||
@@ -53,7 +53,8 @@ Registry допускает не более одной `active` записи и
|
|||||||
|
|
||||||
## Migration Plan
|
## Migration Plan
|
||||||
|
|
||||||
1. Создать development registry и индекс со всеми confirmed findings от 20.08.2026 в состоянии `planned`.
|
1. Скопировать immutable audit snapshot в `docs/audits`, добавить index и зафиксировать его как canonical source для registry.
|
||||||
2. Добавить local instruction links и проверить их из каждого Git root.
|
2. Создать development registry и индекс со всеми confirmed findings от 20.08.2026 в состоянии `planned`.
|
||||||
3. Пометить `stabilize-frontend-query-and-strict-contracts` как единственную следующую задачу, не создавая этот functional change в данном scope.
|
3. Добавить local instruction links и проверить их из каждого Git root.
|
||||||
4. Проверить change в canonical store; после implementation и archive использовать registry для первого functional remediation change.
|
4. Пометить `stabilize-frontend-query-and-strict-contracts` как единственную следующую задачу, не создавая этот functional change в данном scope.
|
||||||
|
5. Проверить change в canonical store; после implementation и archive использовать registry для первого functional remediation change.
|
||||||
|
|||||||
@@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
## What Changes
|
## What Changes
|
||||||
|
|
||||||
- Добавить долговечный реестр remediation-аудита в `docs/development`, связанный с неизменяемым `audit-20-08-2026.md`.
|
- Сохранить неизменяемый versioned snapshot аудита в `docs/audits` и добавить долговечный remediation registry в `docs/development`, связанный с этим snapshot.
|
||||||
- Ввести machine-readable-in-spirit правила статусов `planned`, `active`, `done`, `deferred` и `accepted`, включая обязательные поля evidence для каждого terminal status.
|
- Ввести machine-readable-in-spirit правила статусов `planned`, `active`, `done`, `deferred` и `accepted`, включая обязательные поля evidence для каждого terminal status.
|
||||||
- Зафиксировать один путь продолжения работы: реестр указывает одну следующую рекомендуемую задачу и связывает каждую активную работу с canonical OpenSpec change.
|
- Зафиксировать один путь продолжения работы: реестр указывает одну следующую рекомендуемую задачу и связывает каждую активную работу с canonical OpenSpec change.
|
||||||
- Добавить краткие ссылки на реестр в локальные agent instructions, не дублируя в них backlog.
|
- Добавить краткие ссылки на реестр в локальные agent instructions, не дублируя в них backlog.
|
||||||
@@ -23,4 +23,4 @@
|
|||||||
|
|
||||||
## Impact
|
## 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.
|
Затрагиваются `specs/openspec` (новый capability и требования), `docs/audits` (versioned audit snapshot), `docs/development` (реестр и индекс) и короткие ссылки в `AGENTS.md` репозиториев frontend, backend, specs и docs. API, модель данных, runtime-код и зависимости не меняются. Первой функциональной задачей, которую реестр должен сделать однозначно доступной, остаётся будущий change `stabilize-frontend-query-and-strict-contracts` для WL-P1-01 и WL-P1-02.
|
||||||
|
|||||||
+2
-2
@@ -5,7 +5,7 @@
|
|||||||
## ADDED Requirements
|
## ADDED Requirements
|
||||||
|
|
||||||
### Requirement: Реестр remediation отделён от снимка аудита
|
### Requirement: Реестр remediation отделён от снимка аудита
|
||||||
Система SHALL хранить durable remediation registry в репозитории `docs`, а исходный dated audit SHALL оставаться неизменяемым снимком. Каждая запись registry MUST ссылаться на Audit ID и не дублировать полный текст finding, если он уже содержится в аудите.
|
Система 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: Агент открывает работу по аудиту в новой сессии
|
#### Scenario: Агент открывает работу по аудиту в новой сессии
|
||||||
- **WHEN** агент получает задачу устранить или продолжить audit finding
|
- **WHEN** агент получает задачу устранить или продолжить audit finding
|
||||||
@@ -13,7 +13,7 @@
|
|||||||
|
|
||||||
#### Scenario: Обновляется прогресс remediation
|
#### Scenario: Обновляется прогресс remediation
|
||||||
- **WHEN** работа по finding меняет статус
|
- **WHEN** работа по finding меняет статус
|
||||||
- **THEN** dated audit не редактируется, а изменение фиксируется только в registry с датой и необходимым evidence
|
- **THEN** versioned audit snapshot не редактируется, а изменение фиксируется только в registry с датой и необходимым evidence
|
||||||
|
|
||||||
### Requirement: Registry задаёт однозначный статус и следующий change
|
### Requirement: Registry задаёт однозначный статус и следующий change
|
||||||
Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. Registry MUST содержать не более одного `active` change и ровно одну следующую рекомендуемую задачу, пока остаются findings со статусом `planned`.
|
Каждая audit-derived запись SHALL иметь ровно один статус из `planned`, `active`, `done`, `deferred` или `accepted`. Registry MUST содержать не более одного `active` change и ровно одну следующую рекомендуемую задачу, пока остаются findings со статусом `planned`.
|
||||||
|
|||||||
+2
-2
@@ -1,11 +1,11 @@
|
|||||||
## ADDED Requirements
|
## ADDED Requirements
|
||||||
|
|
||||||
### Requirement: Документация процесса содержит remediation registry
|
### Requirement: Документация процесса содержит remediation registry
|
||||||
Репозиторий `docs` SHALL содержать versioned remediation registry в разделе development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes, следующую рекомендуемую задачу и evidence завершённых remediation changes.
|
Репозиторий `docs` SHALL содержать immutable versioned audit snapshots в `docs/audits` и versioned remediation registry в разделе development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes, следующую рекомендуемую задачу и evidence завершённых remediation changes.
|
||||||
|
|
||||||
#### Scenario: Участник проекта ищет состояние технических улучшений
|
#### Scenario: Участник проекта ищет состояние технических улучшений
|
||||||
- **WHEN** участник открывает development documentation
|
- **WHEN** участник открывает development documentation
|
||||||
- **THEN** он может найти registry через development index и определить, какие findings planned, active, done, deferred или accepted
|
- **THEN** он может найти audit snapshot и registry через documentation indexes и определить, какие findings planned, active, done, deferred или accepted
|
||||||
|
|
||||||
#### Scenario: Завершён audit-derived change
|
#### Scenario: Завершён audit-derived change
|
||||||
- **WHEN** связанный OpenSpec change архивирован после успешной проверки
|
- **WHEN** связанный OpenSpec change архивирован после успешной проверки
|
||||||
|
|||||||
@@ -1,9 +1,10 @@
|
|||||||
## 1. Durable remediation registry
|
## 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.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 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.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 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.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 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.
|
- [ ] 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.
|
||||||
|
|
||||||
## 2. Agent discovery
|
## 2. Agent discovery
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user