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

project-documentation Specification

Purpose

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

Requirements

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 содержать все требуемые артефакты, реализацию, критические тесты, успешную проверку opsx-verify и связанную документацию до архивирования.

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

• WHEN для изменения отсутствует реализация, верификация или feature-документ
• THEN изменение не считается готовым к архивированию

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

Репозиторий docs SHALL содержать immutable versioned audit snapshots в docs/audits и versioned remediation registry в разделе development documentation. Registry MUST документировать source audit, допустимые статусы, связанные OpenSpec changes, следующую рекомендуемую задачу и evidence завершённых remediation changes.

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

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

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

• WHEN связанный OpenSpec change архивирован после успешной проверки
• THEN registry обновляется с archive path, commits затронутых репозиториев и результатами exact verification commands

Requirement: Durable documentation is not a parallel SDD store

Репозиторий docs SHALL хранить только долговечную architecture, development, feature, audit и remediation documentation вместе с completion evidence. Change-specific requirements, designs, delta specifications и tasks MUST храниться только в canonical OpenSpec store и MUST NOT создаваться как framework-specific planning artifacts в docs.

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

• WHEN завершённый change должен оставить устойчивое объяснение решения или evidence
• THEN documentation фиксирует реализованное решение или completion evidence и ссылается на canonical OpenSpec change без дублирования его requirements, design или tasks

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

• WHEN агент создаёт requirements, design или tasks для незавершённого изменения
• THEN он сохраняет их под specs/openspec и не создаёт framework-specific planning document в docs