diff --git a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml b/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml deleted file mode 100644 index 4102db8..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -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 deleted file mode 100644 index 2c2641d..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/design.md +++ /dev/null @@ -1,91 +0,0 @@ -## 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 deleted file mode 100644 index 88a8cca..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/proposal.md +++ /dev/null @@ -1,47 +0,0 @@ -## 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 deleted file mode 100644 index 96ba69a..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-documentation/spec.md +++ /dev/null @@ -1,42 +0,0 @@ -## 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 deleted file mode 100644 index b00bcea..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/specs/project-foundation/spec.md +++ /dev/null @@ -1,61 +0,0 @@ -## 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 deleted file mode 100644 index 3b275ad..0000000 --- a/openspec/changes/refresh-project-documentation-and-agent-entrypoints/tasks.md +++ /dev/null @@ -1,27 +0,0 @@ -## 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.