docs(specs): archive documentation entrypoints remediation
This commit is contained in:
+2
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-24
|
||||
+91
@@ -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 не переписывать.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
## Why
|
||||
|
||||
После поставки MVP корневой `MVP.md` и template README-файлы описывают
|
||||
устаревшую или неполную картину системы. Новый разработчик или AI-агент
|
||||
вынужден восстанавливать delivered capabilities, domain terminology,
|
||||
локальный bootstrap и ограничения verification из кода и архивов, хотя эта
|
||||
информация должна быть доступна через устойчивую документацию.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING** Удалить корневой `MVP.md` как завершённую карту поставки и
|
||||
удалить ссылки, представляющие его актуальным источником.
|
||||
- Перенести канонический domain glossary из корневого `CONTEXT.md` в
|
||||
`docs/architecture/domain-glossary.md`, сохранив утверждённые термины и
|
||||
обновив навигацию.
|
||||
- Добавить фактический system overview с delivered capabilities, локальными
|
||||
границами и Mermaid-потоками auth/session и T-Bank → backend → frontend.
|
||||
- Заменить template README frontend/backend на компактные onboarding entrypoints
|
||||
с Node 22, безопасным bootstrap, локальными gates и ссылками на
|
||||
authoritative/JIT documentation.
|
||||
- Сделать indexes architecture, development и features навигаторами по
|
||||
устойчивой документации; исправить feature-doc summaries, противоречащие
|
||||
delivered accounts, portfolio, ledger и future cash events.
|
||||
- Обновить scoped agent instructions только для актуальной маршрутизации,
|
||||
сохранив detail и review trigger deferred Prisma e2e в remediation registry.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
_Нет._
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `project-documentation`: устойчивые documentation entrypoints, glossary и
|
||||
фактическая архитектурная карта должны позволять определить delivered
|
||||
поведение и его границы без обращения к устаревшему MVP-файлу.
|
||||
- `project-foundation`: workspace больше не хранит корневой MVP delivery map;
|
||||
локальные инструкции направляют к durable documentation и canonical
|
||||
OpenSpec authority.
|
||||
|
||||
## Impact
|
||||
|
||||
Затрагиваются `docs`, корневые workspace файлы, документация и `AGENTS.md` в
|
||||
`frontend`, `backend` и `specs`, а также OpenSpec requirements и remediation
|
||||
registry. Runtime-код, HTTP API, зависимости, generated artifacts, CI/CD и
|
||||
Prisma e2e policy не изменяются.
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Устойчивая документация имеет доступные фактические точки входа
|
||||
Репозиторий `docs` SHALL содержать indexes архитектуры, разработки и фич,
|
||||
которые ведут разработчика или AI-агента к фактической устойчивой документации
|
||||
без обращения к архивированному change или корневому delivery-plan файлу.
|
||||
Архитектурная документация MUST содержать system overview поставленных
|
||||
возможностей и локальных границ, канонический domain glossary, а также
|
||||
Mermaid-диаграммы потоков auth/session и T-Bank → клиент. Feature documentation
|
||||
MUST предоставлять index поставленных фич и MUST NOT описывать поставленные
|
||||
Brokerage Accounts, Portfolio, Account Ledger или Future Cash Events как
|
||||
отложенные.
|
||||
|
||||
#### Scenario: Новый участник находит поставленную систему
|
||||
- **WHEN** новый участник открывает устойчивую документацию
|
||||
- **THEN** он может перейти из index к system overview, glossary, документам
|
||||
поставленных фич и соответствующему development workflow
|
||||
|
||||
#### Scenario: Участник различает близкие доменные понятия
|
||||
- **WHEN** участнику нужно описать cached portfolio data или account operation
|
||||
- **THEN** канонический glossary различает Client Cached Snapshot и Portfolio
|
||||
Snapshot, а также Future Cash Event и Ledger Entry
|
||||
|
||||
### Requirement: README репозиториев являются компактными onboarding entrypoints
|
||||
Репозитории frontend и backend SHALL предоставлять русскоязычные README
|
||||
entrypoints, которые указывают Node 22, lockfile-safe bootstrap, локальные
|
||||
non-mutating verification commands, требуемую локальную configuration и ссылки
|
||||
на authoritative или just-in-time documentation. README MUST различать deferred
|
||||
check и passing verification gate, а detailed rationale deferred Prisma e2e и
|
||||
его review trigger MUST быть ссылкой на remediation registry, а не дублироваться.
|
||||
|
||||
#### Scenario: Участник bootstrap-ит application repository
|
||||
- **WHEN** участник открывает frontend или backend README на чистой локальной
|
||||
машине
|
||||
- **THEN** он может определить требуемый runtime, подготовить local
|
||||
configuration, установить зависимости из lockfile и запустить
|
||||
документированные local gates без угадывания
|
||||
|
||||
#### Scenario: Участник видит ограничение backend e2e
|
||||
- **WHEN** участник читает backend onboarding instructions
|
||||
- **THEN** он узнаёт, что Prisma e2e gate отложен, и может перейти к
|
||||
remediation registry за его точным статусом и review trigger
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Репозитории содержат локальные инструкции для AI-агентов
|
||||
Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и
|
||||
отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs.
|
||||
Инструкции MUST описывать назначение области, локальные команды проверки,
|
||||
границы ответственности и связь с SDD-артефактами. Каждая инструкция MUST
|
||||
объявлять `wealth-ledger-specs` и `specs/openspec` как canonical OpenSpec
|
||||
authority, требовать явный `--store wealth-ledger-specs` для поддерживаемых
|
||||
OpenSpec операций и запрещать versioned framework-specific planning artifacts
|
||||
вне canonical store. Локальные инструкции MUST направлять агента к durable
|
||||
documentation, относящейся к его области, и к durable remediation registry,
|
||||
когда задача связана с findings технического аудита. Backend instructions MUST
|
||||
различать non-mutating verification commands и явные auto-fix commands.
|
||||
|
||||
#### Scenario: Агент начинает работу в отдельном репозитории
|
||||
- **WHEN** агент открывает любой из репозиториев frontend, backend, specs или
|
||||
docs
|
||||
- **THEN** он может определить локальные правила работы, canonical OpenSpec
|
||||
authority, источник связанных спецификаций и относящийся к области durable
|
||||
documentation из `AGENTS.md` этого репозитория
|
||||
|
||||
#### Scenario: Агент получает audit-derived задачу из отдельного репозитория
|
||||
- **WHEN** задача ссылается на finding технического аудита
|
||||
- **THEN** локальный `AGENTS.md` указывает на remediation registry и canonical
|
||||
OpenSpec workflow с явным store selection до начала изменения кода
|
||||
|
||||
#### Scenario: Агент выбирает backend quality gate
|
||||
- **WHEN** агент читает backend instructions перед локальной проверкой
|
||||
- **THEN** он запускает документированные non-mutating lint/typecheck commands
|
||||
и не получает auto-fix как неявный quality gate
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Локальный план MVP не является источником спецификации
|
||||
**Reason**: Поставка MVP завершена; корневой `MVP.md` дублирует и частично
|
||||
противоречит фактическому поведению, OpenSpec и устойчивой документации.
|
||||
|
||||
**Migration**: Удалить `MVP.md`; использовать canonical OpenSpec для
|
||||
requirements и `docs/architecture/system-overview.md` для фактической карты
|
||||
поставленной системы и её локальных границ.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Корень рабочей области не хранит delivery-plan файл
|
||||
Корень рабочей области MUST NOT содержать `MVP.md` или другой versioned
|
||||
delivery-plan файл как источник требований, порядка поставки или фактического
|
||||
поведения. Требования SHALL оставаться в OpenSpec, а delivered system overview
|
||||
и долговечные ограничения SHALL находиться в `docs`. Frontend и backend MUST
|
||||
требовать Node 22 и документировать lockfile-safe bootstrap через `npm ci`.
|
||||
|
||||
#### Scenario: Агент определяет границы поставленной системы
|
||||
- **WHEN** агент начинает работу и ищет актуальные границы WealthLedger
|
||||
- **THEN** он находит их в durable documentation и canonical OpenSpec, а не в
|
||||
корневом delivery-plan файле
|
||||
|
||||
#### Scenario: Агент bootstrap-ит application repository
|
||||
- **WHEN** агент начинает локальную проверку frontend или backend на чистой
|
||||
машине
|
||||
- **THEN** он может определить Node 22 и выполнить `npm ci` без угадывания
|
||||
runtime policy
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
## 1. Состояние remediation и навигация по устойчивой архитектуре
|
||||
|
||||
- [x] 1.1 Отметить WL-P2-10 как `active` в `docs/development/audit-remediation.md`, связать с ним этот OpenSpec change и убрать устаревший текст об отсутствии active/следующей задаче без terminal evidence до archive.
|
||||
- [x] 1.2 Создать `docs/architecture/domain-glossary.md`, перенёсши утверждённые термины из корневого `CONTEXT.md`; сохранить различия Client Cached Snapshot и Portfolio Snapshot, а также Future Cash Event и Ledger Entry.
|
||||
- [x] 1.3 Создать `docs/architecture/system-overview.md` с delivered capabilities, локальными MVP-границами, ссылками на feature docs и ADR, а также Mermaid-потоками auth/session и T-Bank → backend → frontend.
|
||||
- [x] 1.4 Превратить `docs/architecture/README.md` в index system overview, domain glossary и ADR index без дублирования их содержания.
|
||||
|
||||
## 2. Onboarding и documentation entrypoints
|
||||
|
||||
- [x] 2.1 Заменить template content `frontend/README.md` русскоязычным onboarding: Node 22, `npm ci`, `npm run verify`, local configuration и ссылки на FSD, API, testing и OpenAPI documentation.
|
||||
- [x] 2.2 Заменить template content `backend/README.md` русскоязычным onboarding: Node 22, `.env.example`, `npm ci`, non-mutating lint/typecheck/unit-test gates, явный `lint:fix`, ссылки на API/development documentation и короткую ссылку на deferred Prisma e2e registry record.
|
||||
- [x] 2.3 Расширить `docs/development/README.md` до index frontend workflow, backend local workflow, runtime OpenAPI verification, OpenSpec authority/lifecycle и audit remediation; registry остаётся единственным detailed owner deferred Prisma status.
|
||||
- [x] 2.4 Расширить `docs/features/README.md` до краткого index всех delivered feature documents и исправить `docs/features/tbank-connection.md`, чтобы он больше не описывал accounts, portfolio, ledger или future cash events как deferred.
|
||||
- [x] 2.5 Обновить корневой и scoped `AGENTS.md`, только убрав stale MVP routing и направив agents к relevant durable documentation entrypoints при сохранении canonical OpenSpec authority и local gates.
|
||||
|
||||
## 3. Удаление superseded root entrypoints и согласование ссылок
|
||||
|
||||
- [x] 3.1 Обновить active documentation и project-owned specification references, чтобы они направляли читателей к durable docs и canonical OpenSpec, а не к корневым `MVP.md` или `CONTEXT.md`.
|
||||
- [x] 3.2 Удалить корневые `MVP.md` и `CONTEXT.md` только после появления durable replacements и active links; immutable audits и historical archives оставить evidence.
|
||||
- [x] 3.3 Проверить, что resulting README, index и glossary prose остаются русскоязычными, а команды, API paths и technical identifiers сохраняют каноническое написание.
|
||||
|
||||
## 4. Верификация и review перед archive
|
||||
|
||||
- [x] 4.1 Выполнить read-only repository-wide active-link/path review удалённых root files, architecture/development/features navigation и README links; подтвердить намеренное сохранение historical audit/archive references.
|
||||
- [x] 4.2 Выполнить applicable non-mutating checks: `git diff --check` в каждом affected Git repository, `bash specs/scripts/verify-openspec-authority.sh`, `openspec validate refresh-project-documentation-and-agent-entrypoints --type change --strict --store wealth-ledger-specs` и strict validation synced specs.
|
||||
- [x] 4.3 Провести independent read-only review точности документации по delivered specs, `package.json` scripts, `.env.example`, domain glossary, deferred Prisma wording и scope; устранить каждый blocking finding.
|
||||
- [x] 4.4 Выполнить applicable `opsx-verify` procedure и устранить каждый blocking result completeness, correctness или coherence до archive.
|
||||
Reference in New Issue
Block a user