92 lines
5.8 KiB
Markdown
92 lines
5.8 KiB
Markdown
## 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 не переписывать.
|