docs(specs): archive documentation entrypoints remediation

2026-08-24 10:29:00 +03:00
parent 800450d075
commit 5b7bc0fdaf
15 changed files with 613 additions and 11 deletions
@@ -0,0 +1,91 @@
+## Context
+
+См. мотивацию в `proposal.md`. В текущем workspace durable documentation уже
+разделена на `architecture`, `development`, `features`, `adr` и `audits`, но
+README frontend/backend остаются template-страницами, indexes неполны, а
+корневые `MVP.md` и `CONTEXT.md` создают отдельный маршрут поиска фактов.
+Canonical OpenSpec store уже закреплён, поэтому новый change не создаёт
+параллельных requirements или planning artifacts в `docs`.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Сделать `docs` единственной точкой входа для фактической архитектурной
+  карты, domain glossary и navigation по delivered features.
+- Сделать README каждого application repository компактным, воспроизводимым
+  onboarding entrypoint для разработчика и AI-агента.
+- Удалить завершённую MVP-карту и обновить ссылки так, чтобы durable docs и
+  scoped instructions не противоречили delivered поведению.
+- Сохранить precise glossary terms и единственный detailed источник статуса
+  deferred Prisma e2e — remediation registry.
+
+**Non-Goals:**
+
+- Не менять runtime-код, HTTP contract, зависимости, generated artifacts,
+  CI/CD или Prisma e2e implementation.
+- Не вводить постоянный docs-linter, второй verification interface или новый
+  ADR: relocation glossary и документационная навигация не являются
+  необратимым архитектурным решением.
+- Не переписывать immutable audit snapshots и historical OpenSpec archives.
+
+## Decisions
+
+### `docs/architecture` владеет обзором и glossary
+
+`docs/architecture/system-overview.md` будет короткой factual map: delivered
+capabilities, локальные границы и два Mermaid data flow. Рядом
+`domain-glossary.md` заменит корневой `CONTEXT.md` без переименования терминов.
+`docs/architecture/README.md` свяжет оба документа и ADR index.
+
+Альтернатива — оставить `CONTEXT.md` в root — отвергнута: она сохраняет
+параллельную и плохо discoverable точку входа. Альтернатива — встроить glossary
+в overview — отвергнута: glossary изменяется независимо и ухудшит навигацию.
+
+### README остаются тонкими, специализированные документы — владельцами деталей
+
+`frontend/README.md` и `backend/README.md` будут содержать назначение,
+prerequisites, `.env`/bootstrap, короткий перечень gates и ссылки на
+authoritative docs. FSD, API, testing, OpenAPI и detailed Prisma diagnosis
+остаются в уже существующих JIT/development документах.
+
+Альтернатива — повторить полные инструкции в каждом README — отвергнута:
+она создаёт новый источник дрейфа.
+
+### Deferment Prisma описывается единожды
+
+README backend и system overview кратко отмечают, что e2e не является passing
+gate, и ссылаются на `docs/development/audit-remediation.md`. Реестр остаётся
+владельцем версии Prisma, воспроизведения и review trigger.
+
+Альтернатива — скрыть e2e из onboarding — отвергнута: это создаёт ложный
+зелёный verdict. Альтернатива — дублировать diagnostics — отвергнута из-за
+drift risk.
+
+### Проверка остаётся review-oriented
+
+Tasks потребуют read-only link/path check, `git diff --check`, OpenSpec
+validation и независимый review; новая постоянная documentation-linter команда
+не добавляется по согласованному scope.
+
+## Risks / Trade-offs
+
+- [Удаление root файлов оставит входящие ссылки] → выполнить repository-wide
+  read-only search и обновить только активные entrypoints; historical audit и
+  archive paths сохранятся как исторические evidence.
+- [Overview продублирует OpenSpec или feature docs] → ограничить его картой
+  capabilities, boundaries и ссылками, не requirements/API details.
+- [README снова устареют] → держать detailed policy в designated durable/JIT
+  docs и проверять README против фактических package scripts и `.env.example`
+  в рамках change review.
+- [Prisma deferment будет прочитано как разрешение игнорировать e2e] → явно
+  назвать e2e deferred, указать registry и не объявлять общий workspace verdict.
+
+## Migration Plan
+
+1. Создать и проверить новую документационную навигацию и README entrypoints.
+2. Переместить glossary content в `docs/architecture/domain-glossary.md`,
+   обновить active links и удалить root `CONTEXT.md` и `MVP.md`.
+3. Выполнить non-mutating documentation/SDD checks и independent review.
+4. После успешного archive добавить terminal evidence WL-P2-10 в remediation
+   registry; history и immutable audit snapshots не переписывать.