From 5b7bc0fdaf8202acfc8ac1ef5510b3f3abad2bbc Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Mon, 24 Aug 2026 10:29:00 +0300 Subject: [PATCH] docs(specs): archive documentation entrypoints remediation --- AGENTS.md | 3 +- .../.openspec.yaml | 2 + .../design.md | 91 +++++++++++++++++++ .../proposal.md | 47 ++++++++++ .../specs/project-documentation/spec.md | 42 +++++++++ .../specs/project-foundation/spec.md | 61 +++++++++++++ .../tasks.md | 27 ++++++ .../.openspec.yaml | 2 + .../design.md | 91 +++++++++++++++++++ .../proposal.md | 47 ++++++++++ .../specs/project-documentation/spec.md | 42 +++++++++ .../specs/project-foundation/spec.md | 61 +++++++++++++ .../tasks.md | 27 ++++++ openspec/specs/project-documentation/spec.md | 41 +++++++++ openspec/specs/project-foundation/spec.md | 40 ++++++-- 15 files changed, 613 insertions(+), 11 deletions(-) create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/.openspec.yaml create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/design.md create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/proposal.md create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md create mode 100644 openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/tasks.md create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/design.md create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/proposal.md create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md create mode 100644 openspec/changes/refresh-project-documentation-and-agent-entrypoints/tasks.md diff --git a/AGENTS.md b/AGENTS.md index 38d099f..c6bdeaa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,9 +15,10 @@ bash scripts/verify-runtime-openapi.sh ## Границы -- Change содержит proposal, design, delta-specs и tasks; требования и задачи живут здесь, не в `MVP.md` или коде. +- Change содержит proposal, design, delta-specs и tasks; требования и задачи живут здесь, не в delivery-plan файле или коде. - Реализация отмечается в tasks только после выполненной работы. Перед архивированием change проходит `opsx-verify` и получает связанную документацию в `../docs`. - Не хранить код приложений и долгоживущие ADR в этом репозитории. +- Для фактических границ системы и терминов использовать [`../docs/architecture/system-overview.md`](../docs/architecture/system-overview.md) и [`../docs/architecture/domain-glossary.md`](../docs/architecture/domain-glossary.md). - Для задачи по Audit ID, продолжения remediation или выбора следующего улучшения сначала прочитать [`../docs/development/audit-remediation.md`](../docs/development/audit-remediation.md); продолжать или создавать change только в store `wealth-ledger-specs`. - Все OpenSpec commands, читающие или изменяющие change, обязаны указывать `--store wealth-ledger-specs`; nearest-root и global-default selection не поддерживаются. - Не создавать и не коммитить framework-specific planning/spec/task/design artifacts вне `openspec/` (то есть `specs/openspec` от workspace), включая `superpowers/plans`; `../references/**` остаётся read-only исключением. diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/.openspec.yaml b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/.openspec.yaml new file mode 100644 index 0000000..4102db8 --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-24 diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/design.md b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/design.md new file mode 100644 index 0000000..2c2641d --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/design.md @@ -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 не переписывать. diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/proposal.md b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/proposal.md new file mode 100644 index 0000000..88a8cca --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/proposal.md @@ -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 не изменяются. diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md new file mode 100644 index 0000000..96ba69a --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md new file mode 100644 index 0000000..b00bcea --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md @@ -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 diff --git a/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/tasks.md b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/tasks.md new file mode 100644 index 0000000..3b275ad --- /dev/null +++ b/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/tasks.md @@ -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. diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml new file mode 100644 index 0000000..4102db8 --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-24 diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/design.md b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/design.md new file mode 100644 index 0000000..2c2641d --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/design.md @@ -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 не переписывать. diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/proposal.md b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/proposal.md new file mode 100644 index 0000000..88a8cca --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/proposal.md @@ -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 не изменяются. diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md new file mode 100644 index 0000000..96ba69a --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md @@ -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 diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md new file mode 100644 index 0000000..b00bcea --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md @@ -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 diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/tasks.md b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/tasks.md new file mode 100644 index 0000000..3b275ad --- /dev/null +++ b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/tasks.md @@ -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. diff --git a/openspec/specs/project-documentation/spec.md b/openspec/specs/project-documentation/spec.md index 78ecb79..1d4b87d 100644 --- a/openspec/specs/project-documentation/spec.md +++ b/openspec/specs/project-documentation/spec.md @@ -48,3 +48,44 @@ #### Scenario: Agent планирует незавершённый change - **WHEN** агент создаёт requirements, design или tasks для незавершённого изменения - **THEN** он сохраняет их под `specs/openspec` и не создаёт framework-specific planning document в `docs` + +### 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 diff --git a/openspec/specs/project-foundation/spec.md b/openspec/specs/project-foundation/spec.md index 4508c93..5961929 100644 --- a/openspec/specs/project-foundation/spec.md +++ b/openspec/specs/project-foundation/spec.md @@ -7,26 +7,46 @@ ## 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 remediation registry, когда задача связана с findings технического аудита. Backend instructions MUST различать non-mutating verification commands и явные auto-fix commands. +Система 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 и источник связанных спецификаций из `AGENTS.md` этого репозитория +- **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 до начала изменения кода +- **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 +- **THEN** он запускает документированные non-mutating lint/typecheck commands + и не получает auto-fix как неявный quality gate -### Requirement: Локальный план MVP не является источником спецификации -Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs. Frontend и backend MUST требовать Node 22 и документировать lockfile-safe bootstrap через `npm ci`. +### 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: Решение уточняется во время SDD-изменения -- **WHEN** изменение уточняет наблюдаемое поведение системы -- **THEN** оно фиксируется в OpenSpec и соответствующей документации, а `MVP.md` остается компактной картой поставки +#### Scenario: Агент определяет границы поставленной системы +- **WHEN** агент начинает работу и ищет актуальные границы WealthLedger +- **THEN** он находит их в durable documentation и canonical OpenSpec, а не в + корневом delivery-plan файле #### Scenario: Агент bootstrap-ит application repository - **WHEN** агент начинает локальную проверку frontend или backend на чистой машине