specs/openspec/specs/project-documentation/spec.md

project-documentation Specification

Purpose

Определяет обязательную документацию архитектурных решений и пользовательских возможностей, сопровождающую SDD-изменения WealthLedger.

Requirements

Requirement: Completion Evidence сохраняет фактическое завершение change

Canonical archived OpenSpec change SHALL хранить Completion Evidence с фактической Delivery Map, commit identifiers изменённых delivery areas, точными выполненными verification commands и их observed results, а также итогом independent read-only review. Completion Evidence MUST создаваться только после существования этих фактов, MUST быть доступно вместе с canonical archive и MUST NOT представляться как unchecked Task, планируемый результат или обязательная docs-мутация для area со статусом N/A.

Scenario: Участник проверяет основание terminal status

• WHEN участник открывает canonical archive завершённого change в новой сессии
• THEN он может проследить связь от Delivery Map к фактическим commits, affected local gates и independent review без восстановления контекста из чата или параллельного evidence store

Scenario: Реализация ещё продолжается

• WHEN часть delivery commits, commands, observed results или review ещё не существует
• THEN change не представляет ожидаемые значения как Completion Evidence и не получает terminal status

Scenario: Технический change не меняет as-built documentation

• WHEN фактическая Delivery Map обоснованно устанавливает docs: N/A
• THEN Completion Evidence сохраняет эту причину рядом с canonical archive и не требует несвязанного изменения docs repository

Requirement: Важные архитектурные решения фиксируются в ADR

Репозиторий docs SHALL содержать ADR для выбора локального хранилища, API-контракта, gRPC-интеграции T-Bank, хранения T-Bank токенов, устойчивости upstream-вызовов, auth-сессий и frontend-кэша. Каждый ADR MUST описывать контекст, решение и последствия.

Scenario: Разработчик оценивает архитектурное ограничение

• WHEN разработчик хочет изменить один из зафиксированных механизмов
• THEN он может определить исходное решение и его последствия из соответствующего ADR

Requirement: Реализованная фича получает документацию

Каждая завершенная пользовательская фича SHALL иметь Markdown-документ в docs/features, описывающий пользовательский поток, API-сценарий, ограничения и необходимые Mermaid-диаграммы.

Scenario: Функциональное изменение готово к закрытию

• WHEN реализация пользовательской фичи завершена
• THEN ее feature-документ существует и отражает фактическое поведение

Requirement: OpenSpec change закрывается только после полной верификации

OpenSpec change MUST содержать все обязательные planning artifacts и завершённые implementation-owned Tasks до архивирования. Archive MUST быть заблокирован, пока отсутствует успешный canonical gate любой affected area, semantic и acceptance verification реализации относительно approved artifacts либо independent read-only review без Critical и Important findings; для area со статусом N/A MUST существовать конкретная проверяемая причина.

Scenario: Команда пытается архивировать незавершенное изменение

• WHEN для change отсутствует обязательный artifact, implementation-owned результат, affected-area gate, semantic или acceptance verification, допустимый independent review либо требуемая as-built documentation
• THEN change не архивируется и остаётся незавершённым без confirmation override

Scenario: Delivery area не затронута

• WHEN Delivery Map помечает area как N/A
• THEN archive допускает отсутствие её commit и gate только при наличии конкретной проверяемой причины

Requirement: Документация процесса содержит remediation registry

Репозиторий docs SHALL содержать immutable versioned audit snapshots в docs/audits и versioned remediation registry в development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes и следующую рекомендуемую задачу. Для завершённого audit-derived change registry MUST ссылаться на canonical archive и его Completion Evidence, а не дублировать commits и verification results как отдельный evidence store.

Scenario: Участник проекта ищет состояние технических улучшений

• WHEN участник открывает development documentation
• THEN он может найти audit snapshot и registry через documentation indexes и определить, какие findings planned, active, done, deferred или accepted

Scenario: Завершён audit-derived change

• WHEN связанный OpenSpec change получил terminal status после успешной проверки
• THEN registry содержит его итоговый статус и ссылку на canonical archive с Completion Evidence

Requirement: Durable documentation is not a parallel SDD store

Репозиторий docs SHALL хранить только долговечную architecture, development, feature, audit и remediation documentation. Документация MUST описывать фактическое текущее состояние поставленной системы и MUST NOT представлять планируемое или частично реализованное поведение как доступное. Change-specific requirements, proposals, designs, delta specifications, tasks и Completion Evidence MUST храниться только в canonical OpenSpec store и MUST NOT пересказываться в docs как параллельная спецификация или evidence store. Docs SHALL обновляться после реализации и проверки только когда её as-built subject действительно affected.

Scenario: Change требует постоянной документации

• WHEN завершённый change меняет поставленное поведение, архитектурную границу, устойчивое решение или другой as-built subject docs
• THEN documentation фиксирует реализованное состояние и MAY ссылаться на canonical OpenSpec change без дублирования его planning artifacts или Completion Evidence

Scenario: Agent планирует незавершённый change

• WHEN агент создаёт requirements, design или tasks для незавершённого изменения
• THEN он сохраняет их в canonical OpenSpec store и не создаёт framework-specific planning document или описание будущего поведения в docs

Scenario: Реализация расходится с прежней документацией

• WHEN проверенный change изменяет поставленное поведение, архитектурную границу или устойчивое решение
• THEN affected docs обновляется до фактического текущего состояния до terminal status и не сохраняет прежнее утверждение как действующее

Scenario: Docs не входит в Delivery Map

• WHEN технический change не меняет ни один as-built subject docs и Delivery Map устанавливает docs: N/A с проверяемой причиной
• THEN terminal status не требует изменения docs только ради Completion Evidence

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 как отложенные.

Канонический domain glossary MUST закреплять различие между Brokerage Account, доступным через текущее T-Bank connection, Portfolio Snapshot, Portfolio Position, Currency Instrument Position, Cash Balance, Money, Instrument, Ledger Entry и Future Cash Event. Runtime/cache-термины MUST быть отделены от доменных терминов так, чтобы документация не представляла технический механизм как бизнес-сущность.

Scenario: Новый участник находит поставленную систему

• WHEN новый участник открывает устойчивую документацию
• THEN он может перейти из index к system overview, glossary, документам поставленных фич и соответствующему development workflow

Scenario: Участник различает близкие доменные понятия

• WHEN участнику нужно описать cached portfolio data, валютную позицию, денежный остаток или account operation
• THEN канонический glossary различает runtime/cache-механизмы, Portfolio Snapshot, Currency Instrument Position, Cash Balance, Future Cash Event и Ledger Entry

Requirement: README репозиториев являются компактными onboarding entrypoints

Репозитории frontend и backend SHALL предоставлять русскоязычные README entrypoints, которые указывают Node 24, 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