Настройка процесса генерации документации

_process/04. Analitycs artefacts - documentation.md

@@ -0,0 +1,289 @@
+## 1. Формат ведения технической документации агентом
+
+## 1.1. Общие принципы
+
+Техническая документация, формируемая агентом, должна строиться как система атомарных, не пересекающихся по смыслу документов, связанных между собой явными ссылками.
+
+Ключевые принципы:
+- один документ описывает одну сущность или один устойчивый технический аспект;
+- документ не должен дублировать соседние документы;
+- общая система знаний должна собираться через ссылки, а не через копипасту;
+- структура документации должна быть пригодна как для чтения человеком, так и для индексирования в RAG.
+
+## 1.2. Требования к заголовкам
+
+- Заголовок должен отражать только суть раздела.
+- Заголовок не должен содержать метаданные (`id`, `doc_type`, `application`, `platform`, `domain`, `sub_domain`).
+- Метаданные указываются отдельными строками в теле раздела или в YAML frontmatter.
+
+Пример:
+- правильно: `## 6.2 Метод UFS получения списка заказов`
+- неправильно: `## 6.2 Блок api_method (id=..., platform=ufs)`
+
+## 1.3. Базовые типы документных единиц
+
+Базовые типы:
+- `ui_page`
+- `api_method`
+- `logic_block`
+
+Дополнительно могут использоваться:
+- `architecture_overview`
+- `integration_doc`
+- `domain_entity`
+- `glossary_item`
+- `index_page`
+
+## 1.4. Принцип декомпозиции страниц / файлов
+
+### Один устойчивый объект - один документ
+Если объект можно переиспользовать или на него могут ссылаться другие документы, его нужно выносить в отдельный файл.
+
+### Документы не должны пересекаться по смыслу
+Если описание повторяется в нескольких местах, нужно выделять общий документ и ссылаться на него.
+
+### Use case и детали живут раздельно
+Сценарий описывает поток работы, а детали выносятся в функциональные требования, отдельные блоки логики или контрактные описания.
+
+## 1.5. Иерархическая организация документации
+
+Документация должна быть организована как иерархическое дерево каталогов и файлов.
+
+Пример:
+
+```text
+docs/
+  ui/
+  api/
+  logic/
+  domains/
+  integrations/
+  architecture/
+  glossary/
+  errors/
+```
+
+## 1.6. Учет связей между документами
+
+Связи должны быть явными.
+
+Примеры:
+- UI-страница ссылается на вызываемые API;
+- API-документ ссылается на используемые блоки логики;
+- логический блок ссылается на интеграции;
+- документ по коду ссылается на системную аналитику, инициировавшую изменения.
+
+## 1.7. Формат markdown-документов
+
+Каждый документ состоит из:
+1. YAML frontmatter;
+2. Markdown body.
+
+## 1.8. YAML frontmatter
+
+### Обязательные поля
+- `id`
+- `title`
+- `doc_type`
+- `status`
+- `domain`
+- `sub_domain`
+- `related_docs`
+
+### Рекомендуемые поля
+- `owner`
+- `entities`
+- `tags`
+- `feature`
+- `system_analytics_refs`
+- `source_of_truth`
+- `related_code`
+
+### Допустимые значения `doc_type`
+- `ui_page`
+- `api_method`
+- `logic_block`
+- `architecture_overview`
+- `integration_doc`
+- `domain_entity`
+- `glossary_item`
+- `index_page`
+
+### Допустимые значения `status`
+- `draft`
+- `in_review`
+- `approved`
+- `outdated`
+- `generated`
+- `active`
+
+## 1.9. Синхронизация с системной аналитикой
+
+Техническая документация строится на основе системной аналитики (features).
+
+Обязательно учитывать:
+- концептуальный уровень аналитики;
+- детализацию технической документации;
+- согласованность терминов, ролей и интеграционных цепочек.
+
+Если атрибуты или детали отсутствуют в аналитике:
+- определить их из текста аналитики;
+- дополнить данными из репозитория (код, контракты, существующие документы);
+- зафиксировать итог в документации как явные метаданные и требования.
+
+## 1.10. Формат body-разделов для блока изменений
+
+Для секции изменений (по аналогии с разделом `6` в аналитике) использовать единый формат.
+
+Под корнем секции изменений указывать общие атрибуты:
+- `domain`
+- `sub_domain`
+
+Для каждого подраздела `X.Y` указывать метаданные строками сразу после заголовка:
+- `id`
+- `doc_type`
+- `application`
+- `platform`
+
+## 1.11. Различие аналитики и документации
+
+- Аналитика - концептуальный уровень, упрощенный use case.
+- Документация - детальный инженерный уровень.
+
+Для документации:
+- технический use case должен быть детализированным;
+- функциональные требования расширяют use case и описывают детали интеграций, логики и поведения;
+- функциональные требования не должны копировать шаги сценария без добавления новой информации.
+
+Источник правил:
+- `src/app/core/agent/processes/v2/doc_rules_v2/common-elements/tech-use-case.md`
+- `src/app/core/agent/processes/v2/doc_rules_v2/common-elements/fr.md`
+
+## 1.12. Требования к `ui_page`
+
+Обязательная структура:
+- `### Технический use case`
+- `### Требования к UI`
+- `### Функциональные требования`
+- `### Нефункциональные требования`
+
+### Требования к UI
+Внутри обязательно отдельно описывать каждую форму UI:
+- табличное представление;
+- пустой список (empty state);
+- ошибка (error state).
+
+Обязательные правила:
+- если есть интеграция, обязательно описать показ ошибки;
+- если показывается список, обязательно описать показ отсутствия данных.
+
+### UI-элементы
+UI-поля и элементы в документации описываются строго в таблицах.
+
+Обязательные колонки (заполнять там, где применимо):
+- `Код элемента`
+- `Название и описание`
+- `Данные`
+- `Поведение`
+- `Валидация`
+
+## 1.13. Пользовательская аналитика для `ui_page`
+
+События пользовательской аналитики оформляются таблицей:
+- `Название события`
+- `Описание`
+- `Точка вызова`
+- `Payload`
+
+## 1.14. Требования к `api_method`
+
+Обязательная структура:
+- `### Технический use case`
+- `### Функциональные требования`
+- `### Нефункциональные требования`
+- `### Контракт`
+
+### Технический use case
+Оформляется детально по правилам `tech-use-case.md`.
+
+Обязательные части:
+- название
+- предусловия
+- триггер
+- основной сценарий
+- альтернативный сценарий
+- обработка ошибок
+- постусловие
+
+### Функциональные требования
+Оформляются по правилам `fr.md`:
+- формат `FR.<номер>. <Название>`;
+- FR расширяют use case;
+- FR не дублируют шаги сценария без дополнительной ценности;
+- для интеграционных шагов FR обязательны.
+
+## 1.15. Нефункциональные требования для `api_method`
+
+Разделять на подразделы:
+- `#### Аудит` (если применимо)
+- `#### Мониторинг`
+
+### Мониторинг
+Оформлять таблицей:
+- `Метрика`
+- `Описание`
+- `Условие срабатывания`
+
+Правила:
+- в условиях указывать, при каких состояниях фиксируется событие;
+- не использовать формулировку вида «точка измерения = метод»;
+- базово закладывать метрики:
+  - `<METRIC_NAME>_SUCCESS`
+  - `<METRIC_NAME>_FAIL`
+  - `<METRIC_NAME>_BUSINESS_ERROR`
+
+## 1.16. Распределение ответственности по слоям
+
+- Проверка ролевой модели пользователя обычно выполняется в `ufs`.
+- Для `pprb` аудит может не фиксироваться, если это согласовано правилами домена.
+- Если проверка ролей вынесена в `ufs`, не дублировать этот шаг в use case `pprb`.
+
+## 1.17. Контракты API
+
+Контракт может быть:
+- в markdown-таблицах;
+- в OpenAPI;
+- в отдельном контрактном файле.
+
+Для markdown-контракта минимум:
+- endpoint/method;
+- request fields;
+- required/optional;
+- constraints;
+- response;
+- errors;
+- auth;
+- retry;
+- timeout;
+- idempotency.
+
+## 1.18. Integrations-блок
+
+Если у документа есть интеграции, выделять отдельный `## Integrations`.
+
+Рекомендуемые атрибуты интеграции:
+- `target`
+- `target_type`
+- `direction`
+- `interaction`
+- `via`
+- `purpose`
+- `details`
+
+## 1.19. Общие требования к markdown body
+
+- В документе должен быть один `H1`, совпадающий с `title`.
+- Основные разделы - `H2`, подразделы - `H3`.
+- Не допускать хаотичной вложенности заголовков.
+- Вместо дублирования использовать ссылки на связанные документы.
+- Сценарии, правила, ограничения и кодовые привязки держать раздельно.

_process/04. Analitycs artefacts - features.md

@@ -0,0 +1,185 @@
+# Системная аналитика
+
+## Общее описание
+
+Документ описывает изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков и проходит согласование с экспертами по архитектуре, безопасности и сопровождению.
+
+Документ может описывать как новый процесс, так и инкремент доработки существующей функциональности.
+
+## Требования к заголовкам
+
+- Заголовок должен отражать суть раздела.
+- Заголовок не должен содержать лишнюю информацию, которая относится к метаданным (id, doc_type, platform, application и т.д.).
+- Метаданные указываются отдельными строками в теле раздела.
+
+## Состав документа
+
+Каждый раздел верхнего уровня оформляется заголовком уровня `#`.
+
+### 1. Цели
+
+- Коротко описать, какую проблему и для кого решаем.
+- 1-2 предложения.
+- Не дублировать критерии приемки.
+
+### 2. Процесс AS IS и TO BE
+
+- Фокус на пользовательских и бизнес-изменениях.
+- Не указывать технические детали (платформы, API, внутренние интеграции).
+
+### 3. Ограничения
+
+- Ограничения и допущения в техническом и бизнесовом плане.
+
+### 4. Критерии приемки
+
+- Описывать с точки зрения пользователя.
+- Не добавлять технические детали (платформы, API, внутренние компоненты).
+
+### 5. Архитектура
+
+Нужно указать:
+
+- схему контейнеров,
+- таблицу интеграций,
+- сквозные интеграционные сценарии.
+
+Слои:
+
+- `ui` - web-приложение, клиент.
+- `ufs` - BFF: аутентификация/авторизация, агрегация и маппинг данных.
+- `pprb` - backend: API, БД, логика жизненного цикла сущностей.
+
+#### Диаграмма
+
+Mermaid-диаграмма должна содержать:
+
+- основные контейнеры,
+- названия приложений и платформ,
+- интеграции между приложениями,
+- названия вызываемых endpoint или топиков.
+
+#### Таблица интеграций
+
+Обязательные колонки:
+
+- Код
+- Название endpoint/топика
+- Источник данных
+- Потребитель данных
+- Инициатор вызова
+- Передаваемые данные
+
+#### Сквозной интеграционный сценарий
+
+- Нумерованный список вызовов вида: «Компонент 1 вызывает endpoint в Компонент 2».
+- Только интеграционная цепочка, без детального разбора логики.
+
+### 6. Описание изменений
+
+Раздел состоит из подразделов уровня `##` (например, `6.1`, `6.2`, `6.3`).
+
+Под корнем раздела `# 6` указываются общие метаданные:
+
+- `domain`
+- `sub_domain`
+
+Для каждого раздела `6.x` обязательно указывать метаданные строками сразу после заголовка:
+
+- `id`
+- `doc_type`
+- `application`
+- `platform`
+
+#### 6.x для `ui_page`
+
+Обязательная структура:
+
+- `### Технический use case (тезисно)`
+- `### Требования к UI`
+- `### Функциональные требования`
+- `### Нефункциональные требования`
+
+Требования к разделу `### Требования к UI`:
+
+- Внутри нужно отдельно описывать каждую UI-форму.
+- Если есть интеграция, обязательно описать, как показывается ошибка.
+- Если показываем список, обязательно описать, как показывается отсутствие данных.
+
+Рекомендуемая детализация UI-форм:
+
+- табличное представление,
+- пустой список (empty state),
+- ошибка (error state).
+
+Правила описания UI-полей:
+
+- Поля описывать списком (не таблицей).
+- Общие правила (например, read-only, поведение при пустом значении) выносить в общий блок, не дублировать для каждого поля.
+
+Нефункциональные требования для `ui_page`:
+
+- пользовательская аналитика оформляется таблицей с колонками:
+  - `Название события`
+  - `Описание`
+  - `Точка вызова`
+  - `Payload`
+
+#### 6.x для `api_method`
+
+Обязательная структура:
+
+- `### Технический use case (тезисно)`
+- `### Функциональные требования`
+- `### Нефункциональные требования`
+- `### Контракт метода`
+
+Правило для функциональных требований:
+
+- Если дополнительных требований нет (дублируют сценарий), писать: `Не выявлены`.
+
+Нефункциональные требования:
+
+- Разделять на подразделы:
+  - `#### Аудит` (если применимо)
+  - `#### Мониторинг`
+
+Для `Мониторинг` использовать таблицу с колонками:
+
+- `Метрика`
+- `Описание`
+- `Условие срабатывания`
+
+Важно:
+
+- В мониторинге описывать условия срабатывания, а не «точку измерения = метод».
+- Базово закладывать 3 метрики:
+  - `<METRIC_NAME>_SUCCESS`
+  - `<METRIC_NAME>_FAIL`
+  - `<METRIC_NAME>_BUSINESS_ERROR`
+
+Контракт метода:
+
+- Для запроса: таблица параметров (`header/query/path`) с колонками: название, тип параметра, тип данных, обязательность, описание, пример.
+- Для тела JSON (если есть): структура отдельной таблицей.
+- Для ответа JSON: таблица с колонками: название, тип данных, обязательность, описание, заполнение, пример.
+
+#### 6.x для `logic_block`
+
+Обязательная структура:
+
+- `### Технический use case (тезисно)`
+- `### Функциональные требования`
+- `### Нефункциональные требования`
+
+## Дополнительные правила по слоям
+
+- Проверка ролевой модели пользователя обычно выполняется на уровне `ufs`.
+- Для `pprb` аудит может не фиксироваться, если это правило принято для конкретной фичи/домена.
+- Если проверка ролей вынесена в `ufs`, не дублировать этот шаг в сценарии `pprb`.
+
+## Термины
+
+- Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
+- Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.
+

_process/04. Analitycs artefacts.md

@@ -1,852 +0,0 @@
-## 1. Формат ведения технической документации агентом
-
-## 1.1. Общие принципы
-
-Техническая документация, формируемая агентом, должна строиться как **система атомарных, не пересекающихся по смыслу документов**, связанных между собой явными ссылками.
-
-Ключевые принципы:
-- один документ описывает одну сущность или один устойчивый технический аспект;
-- документ не должен дублировать соседние документы;
-- общая система знаний должна собираться через ссылки, а не через копипасту;
-- структура документации должна быть пригодна как для чтения человеком, так и для индексирования в RAG.
-
-## 1.2. Базовые типы документных единиц
-
-На первом этапе логично сохранить текущую семантику типов документов, но перенести ее в файловую модель.
-
-Базовые типы:
-- `ui_page`
-- `api_method`
-- `logic_block`
-
-Позже могут добавиться:
-- `architecture_overview`
-- `integration_doc`
-- `domain_entity`
-- `glossary_item`
-- `index_page`
-
-## 1.3. Принцип декомпозиции страниц / файлов
-
-### Один устойчивый объект — один документ
-Если объект можно переиспользовать или на него могут ссылаться другие документы, его надо выносить в отдельный файл.
-
-Примеры:
-- отдельная UI-страница;
-- отдельный API endpoint;
-- отдельный блок логики;
-- отдельный интеграционный сценарий.
-
-### Документы не должны пересекаться по смыслу
-Если описание повторяется в нескольких местах, нужно выделять общий документ и ссылаться на него.
-
-Примеры:
-- фронтальная страница не должна заново описывать логику API;
-- документ по API не должен заново раскрывать общую логику переиспользуемого блока;
-- вместо дублирования должен быть переход по ссылке.
-
-### Use case и детальные правила живут раздельно
-Сценарий описывает поток работы, а детали выносятся в функциональные требования, отдельные блоки логики или контрактные описания.
-
-Это важно и для RAG-индексации:
-- сценарии индексируются как workflows;
-- отдельные правила — как facts;
-- сущности и блоки — как entities.
-
-## 1.4. Иерархическая организация документации
-
-Документация должна быть организована как иерархическое дерево каталогов и файлов, а не как набор неструктурированных страниц.
-
-Пример верхнего уровня:
-
-```text
-docs/
-  ui/
-  api/
-  logic/
-  domains/
-  integrations/
-  architecture/
-  glossary/
-  errors/
-```
-
-Пример организации:
-
-```text
-docs/
-  ui/
-    order-create-page.md
-    order-edit-page.md
-  api/
-    orders-create.md
-    orders-get.md
-  logic/
-    order-validation.md
-    order-enrichment.md
-  architecture/
-    system-overview.md
-    integration-landscape.md
-  errors/
-    catalog.yaml
-```
-
-## 1.5. Учет связей между документами
-
-Связи должны быть **явными и поддерживаемыми агентом**.
-
-Примеры:
-- UI-страница ссылается на API, который она вызывает;
-- API-документ ссылается на переиспользуемые логические блоки;
-- логический блок ссылается на связанные интеграции;
-- архитектурный обзор ссылается на набор конкретных модулей и документов;
-- документ по коду может ссылаться на системную аналитику, которая инициировала изменение.
-
-Именно эта сеть ссылок затем индексируется в слоях:
-- `D1_DOCUMENT_CATALOG`
-- `D3_ENTITY_CATALOG`
-- `D4_WORKFLOW_INDEX`
-- `D5_REFERENCE_GRAPH`
-- `D6_DOC_CODE_LINKS`
-
-## 1.6. Формат markdown-документов
-
-Основной формат технической документации — `Markdown`.
-
-Каждый документ состоит из двух частей:
-1. **YAML frontmatter** — структурные метаданные;
-2. **Markdown body** — основное содержимое по шаблону.
-
-## 3.7. YAML frontmatter
-
-Frontmatter нужен для:
-- определения типа документа;
-- идентификации документа;
-- определения его места в иерархии;
-- фиксации связей с кодом и другими документами;
-- выделения сущностей и тегов;
-- упрощения построения слоев `D1`, `D3`, `D5`, `D6`.
-
-### Базовый frontmatter
-
-```yaml
----
-id: ui-order-create-page
-title: Страница создания заказа
-doc_type: ui_page
-domain: orders
-status: draft
-related_docs:
-  - api-orders-create
-  - logic-order-validation
-entities:
-  - Order
-  - CreateOrder
-tags:
-  - ui
-  - orders
-  - creation
-#owner: system-analyst
-#source_of_truth: code
-#related_code:
-#  - src/orders/ui/create_page.tsx
-#  - src/orders/api/orders_controller.py
----
-```
-
-### Обязательные поля
-
-- `id` — стабильный уникальный идентификатор документа;
-- `title` — человекочитаемый заголовок;
-- `doc_type` — тип документа;
-- `related_docs` — ссылки на связанные документы;
-- `status` — статус документа;
-- `domain` - домен фичи (Карточка клиента, Задачи, Сделки, Предложения)
-- `sub_domain` - поддомен внутри основной сущности (Счета, ЗДА, ECM)
-
-### Рекомендуемые поля
-- `owner`
-- `entities`
-- `tags`
-- `parent`
-- `children`
-- `feature`
-- `system_analytics_refs`
-- `business_refs`
-- `updated_from`
-- `reviewers`
-- `source_of_truth`
-- `related_code`
-
-### Допустимые значения `doc_type`
-- `ui_page`
-- `api_method`
-- `logic_block`
-- `architecture_overview`
-- `integration_doc`
-- `domain_entity`
-- `glossary_item`
-- `index_page`
-
-### Допустимые значения `status`
-- `draft`
-- `in_review`
-- `approved`
-- `outdated`
-- `generated`
-- `active`
-
-### Допустимые значения `source_of_truth`
-- `code`
-- `doc`
-- `system_analysis`
-- `business_requirements`
-- `mixed`
-
-## 1.8. Typed frontmatter для разных типов документов
-
-У каждого типа документа есть:
-- **общие поля**;
-- **тип-специфичные поля**.
-
-### Пример для `api_method`
-
-```yaml
----
-id: api.create_invoice
-doc_type: api_method
-domain: billing
-title: Создание инвойса
-
-endpoint: POST /api/v1/invoices
-auth: USER
-idempotent: false
-timeout_ms: 3000
-
-links:
-  called_by:
-    - ui.invoice_form
-  uses_logic:
-    - logic.invoice_validation
-  writes_db:
-    - db.invoices
-    - db.invoice_items
-  integrates_with:
-    - int.crm_sync
-
-related_docs:
-  - ui.invoice_form
-  - logic.invoice_validation
-related_code:
-  - services/billing/api/create_invoice.py
-entities:
-  - Invoice
-  - CreateInvoice
-
-tags:
-  - invoice
-  - create
-  - billing
-status: active
-version: 1.3
-source_of_truth: code
----
-```
-
-### Для `api_method` полезно поддерживать
-
-- `endpoint`
-- `sup_parameters`
-- `role_model_actions`
-- `monitoring_actions`
-- `audit_actions`
-- `idempotent`
-- `timeout_ms`
-- `links.called_by`
-- `links.uses_logic`
-- `links.writes_db`
-- `links.integrates_with`
-
-### Для `ui_page` позже полезно поддерживать
-- `calls_api`
-- `user_analitycs_actions`
-- `sup_parameters`
-- `role_model_actions`
-- `entry_points`
-- `uses_logic`
-
-### Для `logic_block` полезно поддерживать
-
-- `called_from`
-- `uses_logic`
-- `reads_db`
-- `writes_db`
-- `integrates_with`
-
-## 1.9. Двухслойная структура документа: `Summary` + `Details`
-
-LLM не должна каждый раз тонуть в полном документе. Поэтому каждый документ должен содержать два уровня представления.
-
-### `Summary`
-Короткая, строго структурированная спецификация. Это слой **быстрого контекста**.
-
-Рекомендуемый объем:
-- примерно 30–60 строк;
-- без длинных пояснений;
-- только ключевые факты.
-
-Пример:
-
-```md
-## Summary
-- Purpose: создание инвойса из формы
-- Actor: пользователь
-- Trigger: Submit
-- Main API: POST /api/v1/invoices (api.create_invoice)
-- Validation: required fields, amount > 0, date <= today
-- Errors: 400(field errors), 409(duplicate), 503(retryable)
-- Analytics: event invoice_submit, invoice_error
-```
-
-### `Details`
-Полное раскрытие объекта:
-- use case;
-- функциональные требования;
-- UI;
-- API;
-- integrations;
-- ошибки;
-- НФТ;
-- связи;
-- кодовые привязки.
-
-### Блок `## Integrations`
-
-Если у объекта есть интеграции, они должны быть выделены в отдельный блок `## Integrations`.
-Интеграции не нужно дублировать во frontmatter.
-Основное описание хранится в body документа.
-
-Ожидаемый принцип:
-- одна интеграция = одна отдельная запись внутри блока;
-- у интеграции есть краткое имя;
-- у интеграции есть структурированные атрибуты;
-- дополнительные детали допускаются в свободной форме через вложенный словарь.
-
-Рекомендуемые атрибуты интеграции:
-- `target`
-- `target_type`
-- `direction`
-- `interaction`
-- `via`
-- `purpose`
-- `details`
-
-Где:
-- `target` - идентификатор или имя целевого объекта;
-- `target_type` - тип цели: `api`, `ui`, `entity`, `service`, `queue`, `db`, `external_system`;
-- `direction` - направление: `inbound`, `outbound`, `bidirectional`;
-- `interaction` - тип взаимодействия: `calls`, `reads`, `writes`, `emits`, `consumes`, `depends_on`;
-- `via` - технический канал интеграции;
-- `purpose` - зачем нужна интеграция;
-- `details` - словарь с гибкой структурой под дополнительные параметры.
-
-Пример:
-
-```md
-## Integrations
-
-### Orders API
-- target: api.orders.create
-- target_type: api
-- direction: outbound
-- interaction: calls
-- via: POST /api/orders
-- purpose: создание заказа
-- details:
-  - auth: service-token
-  - retry: true
-
-### Order Entity
-- target: domain.order
-- target_type: entity
-- direction: outbound
-- interaction: writes
-- via: repository
-- purpose: сохранение состояния заказа
-- details:
-  - transaction: required
-```
-
-Этот блок должен быть пригоден и для чтения человеком, и для последующего извлечения в отдельный RAG-слой интеграций.
-
-## 1.10. Общие требования к markdown body
-
-1. В документе должен быть один `H1`, совпадающий с `title`.
-2. Основные разделы используют `H2`.
-3. Подразделы внутри разделов используют `H3`.
-4. Не должно быть хаотической вложенности заголовков.
-5. Один раздел должен описывать одну смысловую часть.
-6. Текст не должен дублировать соседние документы.
-7. Вместо дублирования должны использоваться явные ссылки на связанные документы.
-8. Сценарии, правила, ограничения и ссылки на код должны быть отделены друг от друга.
-
-## 1.11. Базовый каркас markdown-документа
-
-```md
----
-id: api-orders-create
-title: Метод создания заказа
-doc_type: api_method
-domain: orders
-status: draft
-source_of_truth: code
-related_docs:
-  - logic-order-validation
-  - ui-order-create-page
-related_code:
-  - src/orders/api/create_order.py
-entities:
-  - Order
-  - CreateOrder
-tags:
-  - api
-  - orders
----
-
-# Метод создания заказа
-
-## Summary
-- Purpose: создание заказа
-- Actor: пользователь
-- Trigger: submit формы
-- Main API: POST /orders
-
-## Details
-### Описание
-### Технический use case
-### Функциональные требования
-### Нефункциональные требования
-### Контракт
-
-
-## 3.13. Специализированные шаблоны документов
-
-### UI Page
-
-```md
-# <Название страницы>
-
-## Summary
-## Назначение
-## Контекст
-## Технический use case
-## Описание UI
-## UI Elements
-## Функциональные требования
-## Нефункциональные требования
-## Связанные API
-## Связанные блоки логики
-## Связанный код
-## Связанные документы
-## История изменений
-```
-
-#### Требования к разделу `Описание UI`
-Для каждого элемента желательно описывать:
-- тип элемента;
-- назначение;
-- источник данных;
-- default / placeholder;
-- правила активации;
-- поведение при взаимодействии;
-- валидацию.
-
-#### Требования к разделу `UI Elements`
-UI-элементы должны храниться в **табличном** или **полуструктурированном** виде.
-
-Пример:
-
-```md
-## UI Elements
-
-| id     | type   | label   | data_source | validation | behavior |
-|--------|--------|---------|------------|------------|----------|
-| amount | input  | Amount  | local      | >0         | enables submit |
-| submit | button | Create  | -          | -          | calls api.create_invoice |
-```
-
-Если модель UI сложная, допустим sidecar-файл `ui_elements.yaml` или `ui_elements.json` рядом с основным документом.
-
-### API Method
-
-```md
-# <Название API метода>
-
-## Summary
-## Назначение
-## Контекст
-## Технический use case
-## Функциональные требования
-## Contract
-## Integrations
-## Errors
-## Нефункциональные требования
-## Связанные блоки логики
-## Связанный код
-## Связанные документы
-## История изменений
-```
-
-#### Требования к разделу `Contract`
-Контракт может:
-- быть кратко описан прямо в документе;
-- ссылаться на OpenAPI;
-- ссылаться на отдельный контрактный файл.
-
-Для REST API целевым источником истины должен становиться `OpenAPI`.
-
-### Reusable Logic Block
-
-```md
-# <Название блока логики>
-
-## Summary
-## Назначение
-## Контекст
-## Технический use case
-## Функциональные требования
-## Integrations
-## Ограничения и условия вызова
-## Нефункциональные требования
-## Связанные API / UI / integration points
-## Связанный код
-## Связанные документы
-## История изменений
-```
-
-## 3.14. Машинно-читаемые API-контракты
-
-Для API контрактов **источником истины** должен становиться:
-- `OpenAPI` — предпочтительно;
-- либо временно строгий markdown/yaml-контракт, если OpenAPI еще нет.
-
-Минимальный набор для API-контракта:
-- `endpoint`
-- `method`
-- `request fields`
-- `required / optional`
-- `constraints`
-- `response`
-- `errors`
-- `idempotency`
-- `retry`
-- `timeout`
-- `auth`
-
-## 3.15. Каталог ошибок
-
-Ошибки, HTTP-коды, retry-правила и клиентское поведение не должны размазываться по разным документам.
-
-Нужен единый каталог ошибок, например `docs/errors/catalog.yaml`.
-
-Пример:
-
-```yaml
-errors:
-  - error_id: invoice_validation_failed
-    http_code: 400
-    internal_code: BILLING_400_01
-    when: invalid request fields
-    client_behavior: show field errors
-    retry: false
-    owner: billing
-
-  - error_id: invoice_duplicate
-    http_code: 409
-    internal_code: BILLING_409_01
-    when: duplicate invoice detected
-    client_behavior: show duplicate warning
-    retry: false
-    owner: billing
-
-  - error_id: crm_sync_unavailable
-    http_code: 503
-    internal_code: BILLING_503_02
-    when: downstream CRM unavailable
-    client_behavior: retry later
-    retry: true
-    owner: billing
-```
-
-В API- и logic-документах лучше ссылаться на `error_id`, а не заново подробно описывать каждую ошибку.
-
-## 3.16. Требования к качеству документа для RAG
-
-1. **Явные заголовки** — не использовать безымянные блоки текста.
-2. **Атомарные утверждения** — не смешивать несколько правил в одном пункте, если их можно разделить.
-3. **Явные сущности** — использовать стабильные названия компонентов, API, модулей, страниц.
-4. **Явные ссылки** — не писать «этот метод», если можно указать конкретную ссылку или идентификатор.
-5. **Минимум дублирования** — повторяющийся контент должен заменяться ссылками.
-6. **Привязка к коду** — если документ описывает кодовый объект, это должно быть явно указано.
-7. **Разделение сценариев и правил** — workflow и fact-like требования должны быть отделены.
-
-## 3.17. Как структура markdown помогает RAG
-
-- `frontmatter` + заголовки → `D1_DOCUMENT_CATALOG`
-- `entities`, `tags`, устойчивые термины → `D3_ENTITY_CATALOG`
-- атомарные функциональные и нефункциональные требования → `D2_FACT_INDEX`
-- `Технический use case` → `D4_WORKFLOW_INDEX`
-- `related_docs`, явные ссылки → `D5_REFERENCE_GRAPH`
-- `related_code`, упоминания symbols и файлов → `D6_DOC_CODE_LINKS`
-- `Summary` → быстрый retrieval и short-form context для LLM
-
-## 3.18. Принципы генерации документации агентом
-
-Когда документ пишет агент, он должен:
-- сначала извлечь evidence из кода, системной аналитики и существующих документов;
-- определить тип документа;
-- заполнить frontmatter;
-- построить markdown body по шаблону;
-- явно указать связи с кодом и другими документами;
-- не дублировать уже существующее описание, если можно сослаться на него.
-
----
-
-
-## 4.4. Layered RAG
-
-RAG строится как система специализированных слоев для двух основных доменов:
-- `CODE RAG`
-- `DOCS RAG`
-
-Каждый graph извлекает контекст не из одного общего индекса, а из нужного набора слоев в зависимости от intent.
-
-## 4.5. Evidence gate
-
-Перед синтезом ответа или документа агент должен проверять, хватает ли опоры.
-
-Примеры:
-- найден ли symbol;
-- найдено ли достаточное количество code chunks;
-- есть ли supporting relations;
-- есть ли document evidence;
-- есть ли docs ↔ code mapping.
-
-Если опоры недостаточно, агент должен:
-- деградировать в упрощенный режим;
-- честно фиксировать неполноту ответа;
-- при необходимости уходить в fallback.
-
-## 4.6. Synthesis layer
-
-На этом этапе LLM:
-- агрегирует найденные артефакты;
-- формирует объяснение;
-- пишет документ;
-- структурирует результат под нужный шаблон.
-
-LLM не должна быть основным источником фактов. Фактическая основа должна приходить из RAG и диагностируемого pipeline.
-
-## 4.7. Diagnostics
-
-Система должна сохранять диагностический след:
-- какой graph был выбран;
-- какие слои использовались;
-- что было найдено;
-- где retrieval был слабым;
-- почему был выбран fallback;
-- какие evidence стали основой ответа.
-
-## 4.8. Сценарии: Target Architecture vs MVP-now
-
-### 4.8.1. Target Architecture
-
-#### CODE
-- `OPEN_FILE` — открыть конкретный файл;
-- `OPEN_SYMBOL` — открыть класс / функцию / метод;
-- `EXPLAIN` — объяснить, как работает сущность или фрагмент;
-- `FIND_TESTS` — найти релевантные тесты;
-- `FIND_ENTRYPOINTS` — найти основные точки входа;
-- `RELATED_CODE` — найти связанные сущности и ближайший контекст.
-
-#### DOCS
-- `DOC_SEARCH` — найти релевантный фрагмент документации;
-- `DOC_EXPLAIN` — кратко объяснить, что сказано в документации по теме;
-- `DOC_ENTITY_LOOKUP` — найти разделы, связанные с сущностью или компонентом;
-- `GENERATE_DOCS_FROM_CODE` — сформировать документацию по коду с нуля для модуля, класса, функции, компонента или сценария.
-
-#### CROSS-DOMAIN
-- `FIND_IMPLEMENTATION_BY_DOC` — найти реализацию по описанию;
-- `FIND_DOC_BY_CODE` — найти документацию по коду;
-- `COMPARE_DOCS_AND_CODE` — базовое сопоставление документации и реализации.
-
-#### GENERAL / FALLBACK
-- `GENERAL_QA` — общий сценарий ответа на вопрос, если домен или интент не удалось определить уверенно.
-
-### 4.8.2. MVP-now
-
-В текущем цикле фокус на сценариях:
-
-- `OPEN_FILE`
-- `EXPLAIN`
-- `FIND_TESTS`
-- `FIND_ENTRYPOINTS`
-- `GENERAL_QA`
-
-DOCS и CROSS_DOMAIN остаются частью target architecture; в текущем цикле они не являются обязательной частью test-first MVP.
-
----
-
-## 5. Структура слоев RAG
-
-## 5.1. CODE RAG
-
-### C0 — Source Chunks
-**Назначение:** базовые фрагменты исходного кода.  
-**Единица:** chunk кода.  
-**Как формируется:** исходные файлы обходятся и режутся на chunk’и с учетом структурных границ.  
-**Статус в MVP:** да.
-
-### C1 — Symbol Catalog
-**Назначение:** каталог модулей, классов, функций, методов и других значимых сущностей.  
-**Единица:** symbol.  
-**Как формируется:** из AST и синтаксического разбора кода.  
-**Статус в MVP:** да.
-
-### C2 — Symbol Relations
-**Назначение:** связи между symbols.  
-**Единица:** relation.  
-**Как формируется:** вторым проходом по AST и структурным зависимостям.  
-**Статус в MVP:** да, в ограниченном виде.
-
-### C3 — Entrypoints
-**Назначение:** каталог точек входа системы.  
-**Единица:** entrypoint.  
-**Как формируется:** специализированными детекторами entrypoint-паттернов.  
-**Статус в MVP:** да, минимально.
-
-### C4 — Execution Paths
-**Назначение:** типовые пути исполнения.  
-**Единица:** path.  
-**Как формируется:** поверх `C2` и `C3` через производную трассировку.  
-**Статус в MVP:** нет.
-
-### C5 — Test Mappings
-**Назначение:** связи production code ↔ tests.  
-**Единица:** mapping.  
-**Как формируется:** по путям, именам, импортам и конвенциям проекта.  
-**Статус в MVP:** да, минимально.
-
-### C6 — Code Facts
-**Назначение:** нормализованные факты из кода.  
-**Единица:** fact.  
-**Как формируется:** поверх `C1–C3` как производный слой.  
-**Статус в MVP:** нет.
-
-## 5.2. DOCS RAG
-
-### D0 — Document Chunks
-**Назначение:** базовые фрагменты документации.  
-**Единица:** document chunk.  
-**Как формируется:** документы нормализуются и режутся на chunk’и с сохранением `section path`.  
-**Статус в MVP:** да.
-
-### D1 — Document Catalog
-**Назначение:** каталог документов и разделов.  
-**Единица:** `document node / section node`.  
-**Как формируется:** из структуры документов и их заголовков.  
-**Статус в MVP:** да.
-
-### D2 — Fact Index
-**Назначение:** атомарные факты из документации.  
-**Единица:** fact.  
-**Как формируется:** из `D0/D1` через правила, шаблоны и при необходимости LLM extraction с валидацией.  
-**Статус в MVP:** частично.
-
-### D3 — Entity Catalog
-**Назначение:** каталог сущностей и понятий документации.  
-**Единица:** entity / concept.  
-**Как формируется:** из устойчивых терминов, заголовков, словарей и нормализации повторяющихся сущностей.  
-**Статус в MVP:** да, минимально.
-
-### D4 — Workflow Index
-**Назначение:** процедуры, сценарии, последовательности шагов.  
-**Единица:** workflow.  
-**Как формируется:** из use case, процессных разделов и последовательных описаний шагов.  
-**Статус в MVP:** нет.
-
-### D5 — Reference Graph
-**Назначение:** граф ссылок между документами, секциями, сущностями и фактами.  
-**Единица:** reference link.  
-**Как формируется:** из явных и неявных cross-links между документами.  
-**Статус в MVP:** нет.
-
-### D6 — Doc-Code Links
-**Назначение:** мост между документацией и кодом.  
-**Единица:** `doc artifact ↔ code artifact link`.  
-**Как формируется:** из имен, aliases, путей, устойчивых терминов и других надежных соответствий.  
-**Статус в MVP:** да, минимально.
-
-## 5.3. Layer scope: Target Architecture vs MVP-now
-
-### 5.3.1. Target Architecture
-
-Полная карта слоёв:
-
-- **CODE:** C0–C6 (Source Chunks, Symbol Catalog, Symbol Relations, Entrypoints, Execution Paths, Test Mappings, Code Facts)
-- **DOCS:** D0–D6 (Document Chunks, Document Catalog, Fact Index, Entity Catalog, Workflow Index, Reference Graph, Doc-Code Links)
-
-### 5.3.2. MVP-now
-
-**Обязательные сейчас:**
-
-- `C0_SOURCE_CHUNKS`
-- `C1_SYMBOL_CATALOG`
-- `C2_SYMBOL_RELATIONS`
-- `C3_ENTRYPOINTS`
-
-**В облегчённом виде:**
-
-- `C5_TEST_MAPPINGS` или `C5-lite`
-
-**Не блокируют текущий этап:**
-
-- `C4_EXECUTION_PATHS`
-- `C6_CODE_FACTS`
-- весь docs runtime (слои D0–D6 в исполнении runtime)
-
-Слои документации остаются частью target architecture; docs retrieval пока не обязателен для текущего code-first milestone.
-
----
-
-## 6. Итоговая рамка MVP-now
-
-Сейчас система должна стабильно работать в **test-first** режиме.
-
-**Фокус:**
-
-- CODE_QA;
-- через тесты настраиваются:
-  - intent routing (IntentRouterV2);
-  - layered retrieval;
-  - evidence sufficiency;
-  - answer quality;
-  - diagnostics.
-
-**Не входят в текущий milestone:**
-
-- UI-интеграция;
-- docs runtime;
-- полная интеграция orchestration переносится на следующий этап после стабилизации test pipeline.
-
-В целевой архитектуре по-прежнему заложены:
-- уверенная работа с кодом, symbols, entrypoints, тестами;
-- ответ по документации и мост docs ↔ code;
-- генерация документации по коду;
-- fallback при неуверенном роутинге.
-
-В MVP-now сознательно **не включаются** самые дорогие части:
-- полноценные execution paths для всей системы;
-- богатые fact-индексы по всем доменам;
-- полный reference graph документации;
-- глубокая автоматизация подготовки системной аналитики.

_process/05. MVP - process_v2.1.md

@@ -0,0 +1,33 @@
+Нужно реализовать 2 вещи
+
+Создать процесс внесения изменений в файл документации
+Создать контекст этого процесса
+
+Контекст наполнять атрибутами
+что-то явно задано, фоллбэк через ллм
+
+
+
+Написать тестовую аналитику - круд над сущностью
+фронт, ефс, ппрб
+Все в своей БД
+Атрибуты сущности задать в требованиях
+
+
+
+
+Аналитика имеет структуру
+Внутри модули - один модуль на правку одного файла.
+
+
+Модуль извлекается из аналитики парсером и из него формируется задача на редактирование файла
+если парсер не сработал - фоллбэк ан ллм
+
+
+
+Процесс редактирования работает стандартно
+
+
+
+
+

_process/doc_rules_v3/README.md

@@ -0,0 +1,37 @@
+# Documentation Rules V3
+
+Этот каталог содержит правила генерации технической документации из системной аналитики.
+
+## Цель
+- синхронизировать требования к документации с требованиями к аналитике (`04. Analitycs artefacts - features.md`);
+- сохранить детальность техдокументации по сравнению с аналитикой;
+- убрать дублирование структуры и manifest-слоя между разными файлами;
+- собирать итоговый промпт из модулей: глобальные правила + template с manifest + блоки.
+
+## Структура
+- `documentation-rules.md` — верхнеуровневый регламент и порядок сборки.
+- `global/` — общие правила (заголовки, frontmatter, слой ответственности, мост аналитика->документация).
+- `common-elements/` — правила для общих блоков (`summary`, `details`, `use case`, `FR`, `NFR`, `UI`, `Contract`).
+- `templates/` — единственный источник истины для структуры итоговой страницы и manifest-метаданных типа документа.
+
+## Принцип сборки
+Для конкретного документа агент собирает единый набор правил из:
+1. `documentation-rules.md`
+2. `global/*.md`
+3. `templates/<doc_type>.template.md`
+4. `common-elements/*.md`, указанных в frontmatter template
+
+## Правило без дублирования
+- `templates/` отвечают за структуру документа, порядок разделов и manifest-метаданные типа.
+- `common-elements/` отвечают только за правила написания конкретного раздела.
+- отдельный слой `types/` не нужен, если для типа документа используется один основной template.
+
+## Формат template-manifest
+Manifest оформляется в YAML frontmatter самого template.
+
+Обязательные поля manifest:
+- `doc_type`
+- `required_common_elements`
+
+Рекомендуемые поля:
+- `special_rules`

_process/doc_rules_v3/common-elements/api-contract.md

@@ -0,0 +1,21 @@
+# API Contract Rules
+
+## Обязательные части
+- request parameters (`header/query/path`)
+- request body (если применимо)
+- response body
+- errors
+- auth
+- timeout
+- retry/idempotency (если применимо)
+
+## Табличный формат
+Для request/response таблицы должны содержать:
+- название
+- тип данных
+- обязательность
+- описание
+- пример
+
+Для response дополнительно:
+- заполнение (mapping/логика источника данных)

_process/doc_rules_v3/common-elements/db-columns.md

@@ -0,0 +1,17 @@
+# DB Columns Rules
+
+## Формат
+Структура таблицы оформляется таблицей.
+
+## Обязательные колонки
+- `Поле`
+- `Тип`
+- `Nullable`
+- `Описание`
+- `Источник заполнения`
+- `Использование`
+
+## Правила
+- перечислять все ключевые поля таблицы;
+- для служебных полей (`id`, `created_at`, `updated_at`, `deleted_at`) явно описывать назначение;
+- если тип или nullable не заданы в аналитике, допускается инженерное предположение с рабочим вариантом.

_process/doc_rules_v3/common-elements/db-constraints.md

@@ -0,0 +1,16 @@
+# DB Constraints Rules
+
+## Что включать
+- primary key;
+- unique constraints;
+- foreign keys;
+- важные индексы;
+- бизнес-ограничения на уровне БД.
+
+## Формат
+- списком или таблицей;
+- для каждого индекса и ограничения писать, зачем оно нужно.
+
+## Правила
+- если индекс нужен для сценария чтения/пагинации, это должно быть явно сказано;
+- если точные названия индексов неизвестны, можно использовать осмысленные проектные названия.

_process/doc_rules_v3/common-elements/db-purpose.md

@@ -0,0 +1,12 @@
+# DB Table Purpose Rules
+
+## Что описывать
+- назначение таблицы;
+- в каком сценарии она используется;
+- кто является владельцем данных;
+- является ли таблица источником истины или производным хранилищем.
+
+## Формат
+- 1-3 абзаца без воды;
+- явно указывать доменную сущность, которую хранит таблица;
+- если сделаны допущения по БД, фиксировать их отдельной фразой.

_process/doc_rules_v3/common-elements/db-usage.md

@@ -0,0 +1,11 @@
+# DB Usage Rules
+
+## Что описывать
+- какие API / logic block / batch job используют таблицу;
+- какие операции выполняются: read / insert / update / delete;
+- как таблица участвует в пользовательском сценарии.
+
+## Правила
+- ссылки на связанные документы давать по `doc_id` или path;
+- не дублировать полный use case, а показывать роль таблицы в сценарии;
+- если таблица используется для пагинации, фильтрации или сортировки, это нужно отметить явно.

_process/doc_rules_v3/common-elements/details.md

@@ -0,0 +1,10 @@
+# Details Rules
+
+## Назначение
+Этот файл задает общие правила для секции `## Details`.
+
+## Правила
+- `Details` оформляется как `## Details`.
+- Внутри `Details` используются заголовки уровня `###` и ниже.
+- Структура `Details` определяется template типа документа.
+- В `Details` не нужно дублировать навигацию и связи, если они уже есть во frontmatter.

_process/doc_rules_v3/common-elements/fr.md

@@ -0,0 +1,31 @@
+# Functional Requirements Rules
+
+## Формат
+- `FR.<номер>. <Название>`
+- Нумерация инкрементальная внутри документа.
+
+## Правила
+- FR расширяют шаги сценария.
+- FR не копируют шаги сценария без добавления новой информации.
+- Для интеграционных шагов FR обязательны.
+- Если в сценарии есть вызов внешнего API / сервиса / БД, нужен отдельный FR на интеграцию.
+
+## FR для интеграционных шагов
+Для интеграционного FR обязательно раскрывать:
+- как формируется запрос;
+- откуда берется каждый значимый атрибут запроса;
+- какой downstream вызывается;
+- какой ответ считается успешным;
+- какие ответы и ситуации считаются бизнес-ошибкой;
+- какие ситуации считаются технической ошибкой;
+- как downstream-ответ маппится в контракт текущего слоя.
+
+## FR для шагов доступа к БД
+Если шаг читает или пишет БД, FR должен по возможности включать:
+- таблицу или набор таблиц;
+- логику фильтрации;
+- логику сортировки;
+- логику пагинации;
+- пример SQL или близкий к рабочему псевдо-SQL.
+
+Если СУБД и диалект не заданы, допускается сделать рабочее предположение и явно зафиксировать его.

_process/doc_rules_v3/common-elements/nfr.md

@@ -0,0 +1,20 @@
+# Non-Functional Requirements Rules
+
+## Для api_method
+- Подразделы:
+  - `#### Аудит` (если применимо)
+  - `#### Мониторинг`
+
+## Мониторинг
+Оформлять таблицей:
+- `Метрика`
+- `Описание`
+- `Условие срабатывания`
+
+Запрещено:
+- использовать «точка измерения = метод» вместо условий срабатывания.
+
+Базовые суффиксы метрик:
+- `_SUCCESS`
+- `_FAIL`
+- `_BUSINESS_ERROR`

_process/doc_rules_v3/common-elements/sql-example.md

@@ -0,0 +1,15 @@
+# SQL Example Rules
+
+## Назначение
+Секция показывает пример рабочего SQL для основного сценария использования таблицы.
+
+## Правила
+- SQL должен быть близок к рабочему, а не абстрактным псевдокодом;
+- если диалект БД не указан, допускается выбрать наиболее вероятный вариант и явно зафиксировать допущение;
+- пример должен отражать реальный сценарий документа: чтение, вставка, обновление или агрегация;
+- для read-сценариев по возможности показывать фильтрацию, сортировку и пагинацию;
+- если есть join, нужно кратко пояснить, зачем он нужен.
+
+## Формат
+- fenced code block с указанием `sql`;
+- под кодом 1-3 поясняющих bullets о ключевых условиях, индексах и параметрах.

_process/doc_rules_v3/common-elements/summary.md

@@ -0,0 +1,10 @@
+# Summary Rules
+
+## Назначение
+Этот файл задает правила для секции `## Summary`.
+
+## Правила
+- `Summary` должен быть коротким слоем быстрого контекста.
+- `Summary` должен объяснять суть документа без длинных деталей.
+- Предпочтительный формат: краткий список ключевых фактов.
+- `Summary` не должен дублировать `Details`.

_process/doc_rules_v3/common-elements/tech-use-case.md

@@ -0,0 +1,16 @@
+# Tech Use Case Rules
+
+## Обязательные части
+- название
+- предусловия
+- триггер
+- основной сценарий
+- альтернативный сценарий
+- обработка ошибок
+- постусловие
+
+## Правила шага
+- Один шаг = одно предложение до 15-20 слов.
+- Формат шага: смысловое действие + техническая реализация (endpoint/топик/операция).
+- Длинные технические детали выносить в FR и ссылаться на FR из шага.
+- Для интеграционных шагов описание обработки ошибок обязательно.

_process/doc_rules_v3/common-elements/ui-requirements.md

@@ -0,0 +1,22 @@
+# UI Requirements Rules
+
+## Структура блока
+- `### Требования к UI`
+- Внутри обязательно отдельные формы:
+  - табличное представление
+  - пустой список (empty state)
+  - ошибка (error state)
+
+## Обязательные правила
+- Если есть интеграция, обязательно описывать показ ошибки.
+- Если есть список, обязательно описывать показ отсутствия данных.
+
+## Описание UI-элементов
+UI-элементы описываются строго в таблице.
+
+Обязательные колонки (где применимо):
+- `Код элемента`
+- `Название и описание`
+- `Данные`
+- `Поведение`
+- `Валидация`

_process/doc_rules_v3/common-elements/user-analytics.md

@@ -0,0 +1,7 @@
+# User Analytics Rules
+
+События пользовательской аналитики оформлять таблицей:
+- `Название события`
+- `Описание`
+- `Точка вызова`
+- `Payload`

_process/doc_rules_v3/documentation-rules.md

@@ -0,0 +1,45 @@
+# Documentation Rules V3
+
+## 1. Общий контракт
+- Документация строится на основе системной аналитики, но на более детальном уровне.
+- Заголовки отражают только суть раздела; метаданные в заголовках запрещены.
+- Метаданные указываются во frontmatter и/или отдельными строками в body.
+- Структура документа определяется только template соответствующего типа.
+- Правила написания конкретного раздела определяются только соответствующим `common-elements` файлом.
+- Manifest типа документа хранится во frontmatter соответствующего template.
+
+## 2. Источники требований
+При генерации документа учитывать:
+- `/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - documentation.md`
+- `/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - features.md`
+- правила v2 из `src/app/core/agent/processes/v2/doc_rules_v2`
+
+## 3. Разрыв аналитика vs документация
+- Аналитика: концептуальная, укрупненная.
+- Документация: технически детальная.
+- Технический use case в документации не копирует аналитический 1-в-1, а детализирует его.
+- Функциональные требования расширяют сценарий и не дублируют шаги без новой информации.
+
+## 4. Заполнение пробелов
+Если атрибуты/детали отсутствуют в аналитике:
+1. восстановить из формулировок аналитики;
+2. уточнить по репозиторию (код, контракты, существующие документы);
+3. зафиксировать в документации явно.
+
+## 5. Сборка итогового промпта
+1. Загрузить global-правила.
+2. Загрузить template типа документа.
+3. Прочитать YAML frontmatter template как manifest.
+4. Загрузить общие блоки, указанные в manifest.
+5. Применить body template как единственный источник структуры.
+5. Проверить чек-лист совместимости с аналитикой (domain/sub_domain, роли слоев, интеграции, ошибки).
+
+## 6. Формат manifest типа документа
+Manifest типа документа хранится во frontmatter `templates/<doc_type>.template.md`.
+
+Минимальная схема:
+- `doc_type`
+- `required_common_elements`
+
+Дополнительно можно указывать:
+- `special_rules`

_process/doc_rules_v3/global/analytics-to-doc.md

@@ -0,0 +1,10 @@
+# Analytics to Documentation Mapping
+
+## Принцип
+- Системная аналитика задает «что».
+- Документация детализирует «как».
+
+## Маппинг
+- Из раздела архитектуры аналитики переносить контейнеры, интеграции и цепочки вызовов.
+- Из раздела изменений аналитики строить отдельные технические страницы (`ui_page`, `api_method`, `logic_block`).
+- Если в аналитике упрощенный use case, в документации раскрывать полный технический сценарий по правилам `tech-use-case.md`.

_process/doc_rules_v3/global/filepaths.md

@@ -0,0 +1,67 @@
+# Правила определения путей файлов
+
+Текущая happy-path реализация строит путь документа по фиксированному шаблону:
+
+`docs/<domain>/<platform>/<doc_type>/<doc_id>.md`
+
+Пример:
+
+`docs/orders/pprb/ui_page/orders.ui.list.md`
+
+## Источники атрибутов
+
+Для построения пути используются четыре основных атрибута:
+
+- `domain`
+- `application`
+- `platform`
+- `doc_type`
+- `id` как `doc_id`
+
+Если атрибуты явно указаны в подразделе `6.x`, нужно использовать их.
+Если атрибут не указан, он может быть взят из общих метаданных аналитики или определен fallback-логикой.
+
+## Нормализация сегментов
+
+Каждый сегмент пути нормализуется одинаково:
+
+- значение переводится в lowercase;
+- все символы, кроме `a-z`, `0-9`, `.`, `_`, `-`, заменяются на `-`;
+- ведущие и хвостовые `.` и `-` удаляются.
+
+Примеры нормализации:
+
+- `Payment Status` -> `payment-status`
+- `UFS Orders` -> `ufs-orders`
+- `crm.mobile` -> `crm.mobile`
+
+## Значения по умолчанию
+
+Если после нормализации сегмент пустой, используются fallback-значения:
+
+- корневая папка: `domain`, иначе `application`, иначе `common`
+- `platform` -> `web`
+- `doc_type` -> `misc`
+- `doc_id` -> `untitled`
+
+## Что важно в текущей версии
+
+- для корневой папки сначала используется `domain`;
+- если `domain` не задан, используется `application`;
+- `sub_domain` сейчас не участвует в построении пути;
+- операции `create`, `update`, `delete` работают с одним и тем же правилом вычисления пути;
+- специальных исключений для разных типов документов пока нет;
+- отдельные каталоги для `pprb`, `ufs`, `web` задаются только через значение `platform`.
+
+## Практическое правило для агента
+
+Если нужно предложить или определить путь новой страницы, агент должен:
+
+1. определить `application`;
+2. определить `domain`;
+3. определить `platform`;
+4. определить `doc_type`;
+5. определить стабильный `doc_id`;
+6. взять корневую папку как `domain`, а если он пустой, то `application`;
+7. нормализовать все сегменты;
+8. собрать путь по шаблону `docs/<root>/<platform>/<doc_type>/<doc_id>.md`.

_process/doc_rules_v3/global/frontmatter.md

@@ -0,0 +1,32 @@
+# Frontmatter Rules
+
+## Обязательные поля
+```yaml
+id: string
+title: string
+doc_type: string
+domain: string
+sub_domain: string
+related_docs: []
+status: string
+```
+
+## Рекомендуемые поля
+```yaml
+tags: []
+entities: []
+source_of_truth: string
+related_code: []
+system_analytics_refs: []
+```
+
+## Body-метаданные для секции изменений
+Под корнем секции изменений указывать:
+- `domain`
+- `sub_domain`
+
+Для каждого подраздела `X.Y` указывать строками:
+- `id`
+- `doc_type`
+- `application`
+- `platform`

_process/doc_rules_v3/global/header-rules.md

@@ -0,0 +1,10 @@
+# Header Rules
+
+## Правила
+- Заголовок описывает только смысл раздела.
+- Не включать в заголовок: `id`, `doc_type`, `application`, `platform`, `domain`, `sub_domain`.
+- Метаданные указываются отдельными строками ниже заголовка или во frontmatter.
+
+## Пример
+- Правильно: `## 6.2 Метод UFS получения списка заказов`
+- Неправильно: `## 6.2 Блок api_method (id=..., platform=ufs)`

_process/doc_rules_v3/global/layer-responsibility.md

@@ -0,0 +1,10 @@
+# Layer Responsibility
+
+- `ui`: отображение, UX, запуск пользовательских сценариев.
+- `ufs`: авторизация/аутентификация, агрегация, маппинг, оркестрация вызовов.
+- `pprb`: API, БД, доменная логика backend.
+
+## Правила согласованности
+- Проверка ролевой модели пользователя обычно фиксируется на уровне `ufs`.
+- Если проверка роли вынесена в `ufs`, в `pprb`-сценарии не дублировать этот шаг.
+- Аудит для `pprb` может отсутствовать, если это явно принято для домена/фичи.

_process/doc_rules_v3/templates/api_method.template.md

@@ -0,0 +1,34 @@
+---
+doc_type: api_method
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/fr.md
+  - common-elements/nfr.md
+  - common-elements/api-contract.md
+special_rules:
+  - Технический use case детализируется по `common-elements/tech-use-case.md`.
+  - FR расширяют use case и не дублируют шаги сценария без новой информации.
+  - Для интеграционных шагов FR обязательны.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/nfr.md`
+
+### Контракт
+Правила оформления: `../common-elements/api-contract.md`

_process/doc_rules_v3/templates/db_table.template.md

@@ -0,0 +1,38 @@
+---
+doc_type: db_table
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/db-purpose.md
+  - common-elements/db-columns.md
+  - common-elements/db-constraints.md
+  - common-elements/db-usage.md
+  - common-elements/sql-example.md
+special_rules:
+  - Документ описывает одну физическую таблицу БД или materialized view.
+  - Нужно фиксировать назначение таблицы, поля, ограничения, индексы, связи и сценарии использования.
+  - Если точные детали БД не заданы, допустимо сделать рабочие инженерные допущения и явно записать их в документ.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Назначение таблицы
+Правила оформления: `../common-elements/db-purpose.md`
+
+### Структура таблицы
+Правила оформления: `../common-elements/db-columns.md`
+
+### Ограничения и индексы
+Правила оформления: `../common-elements/db-constraints.md`
+
+### Использование в сценариях
+Правила оформления: `../common-elements/db-usage.md`
+
+### Пример SQL
+Правила оформления: `../common-elements/sql-example.md`

_process/doc_rules_v3/templates/logic_block.template.md

@@ -0,0 +1,28 @@
+---
+doc_type: logic_block
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/fr.md
+  - common-elements/nfr.md
+special_rules:
+  - Logic block описывает переиспользуемую логику без дублирования UI/API деталей.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/nfr.md`

_process/doc_rules_v3/templates/ui_page.template.md

@@ -0,0 +1,33 @@
+---
+doc_type: ui_page
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/ui-requirements.md
+  - common-elements/fr.md
+  - common-elements/user-analytics.md
+special_rules:
+  - Для списочных страниц обязательно описывать табличное представление, empty state и error state.
+  - UI-элементы описываются в таблицах по правилам `common-elements/ui-requirements.md`.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Требования к UI
+Правила оформления: `../common-elements/ui-requirements.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/user-analytics.md`