Фиксирую состояние

_process/04. Analitycs artefacts - features.md

@@ -91,6 +91,12 @@ Mermaid-диаграмма должна содержать:
 - `application`
 - `platform`
 
+Дополнительные метаданные для случаев изменения существующей документации:
+
+- `action`
+- `target_doc_id`
+- `target_path`
+
 #### 6.x для `ui_page`
 
 Обязательная структура:
@@ -117,6 +123,24 @@ Mermaid-диаграмма должна содержать:
 - Поля описывать списком (не таблицей).
 - Общие правила (например, read-only, поведение при пустом значении) выносить в общий блок, не дублировать для каждого поля.
 
+Отдельно нужно различать два сценария описания:
+
+1. Если описывается новая UI-страница или новая самостоятельная UI-форма, раздел оформляется полноценно по шаблону `ui_page`.
+- Нужно дать достаточный контекст для разработки и тестирования.
+- Нужно подробно описывать структуру формы, состояния отображения, поведение полей, ошибки, empty state и пользовательские действия.
+
+2. Если описывается доработка уже существующей страницы или существующей UI-формы, не нужно повторно копировать полное описание из действующей документации.
+- Нужно учитывать уже существующее описание страницы в документации и аналитике.
+- В аналитике нужно явно указать, что именно меняется в существующем сценарии: что добавляется, редактируется или удаляется.
+- Нужно указывать точку изменения: в какой существующей странице, форме, блоке или сценарии вносится изменение.
+- Нужно ссылаться на существующий документ или раздел, где базовое поведение уже описано.
+- Нужно описывать только delta изменений, достаточную для реализации доработки и актуализации документации.
+- Полное описание существующей страницы в таком разделе не дублируется.
+- Для такой доработки в metadata нужно явно указывать `action: update`.
+- Если изменение должно попасть в уже существующий markdown-документ, нужно явно указывать `target_doc_id` и/или `target_path`.
+- `target_doc_id` должен совпадать с `id` существующего документа, который требуется обновить.
+- Если `target_doc_id`/`target_path` не указаны, агент может ошибочно интерпретировать раздел как создание нового документа.
+
 Нефункциональные требования для `ui_page`:
 
 - пользовательская аналитика оформляется таблицей с колонками:
@@ -172,6 +196,10 @@ Mermaid-диаграмма должна содержать:
 - `### Функциональные требования`
 - `### Нефункциональные требования`
 
+`logic_block` удобно использовать для фиксации точечных изменений существующего сценария, если раздел не описывает новую самостоятельную страницу или новую самостоятельную форму, а только уточняет delta к уже существующей документации.
+
+Если точечное изменение должно изменить существующий документ другого типа, `logic_block` для этого использовать нельзя. В этом случае metadata раздела должна указывать тип и идентификатор целевого существующего документа, который требуется обновить.
+
 ## Дополнительные правила по слоям
 
 - Проверка ролевой модели пользователя обычно выполняется на уровне `ufs`.
@@ -182,4 +210,3 @@ Mermaid-диаграмма должна содержать:
 
 - Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
 - Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.
-

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

@@ -1,5 +1,7 @@
 # API Contract Rules
 
+Этот rule описывает только тело секции `### Контракт`.
+
 ## Обязательные части
 - request parameters (`header/query/path`)
 - request body (если применимо)
@@ -9,6 +11,11 @@
 - timeout
 - retry/idempotency (если применимо)
 
+## Правила заголовков внутри тела секции
+- Не повторять заголовок `Контракт`.
+- Запрещено выводить `## Контракт` и `### Контракт` внутри тела секции.
+- Если нужны подзаголовки, использовать только уровень ниже родительской секции: `#### Запрос`, `#### Ответ`, `#### Ошибки`, `#### Auth`, `#### Timeout`, `#### Retry/Idempotency`.
+
 ## Табличный формат
 Для request/response таблицы должны содержать:
 - название

_process/doc_rules_v3/common-elements/fr.md

@@ -1,5 +1,7 @@
 # Functional Requirements Rules
 
+Этот rule описывает только тело секции `### Функциональные требования`.
+
 ## Формат
 - `FR.<номер>. <Название>`
 - Нумерация инкрементальная внутри документа.
@@ -9,6 +11,7 @@
 - FR не копируют шаги сценария без добавления новой информации.
 - Для интеграционных шагов FR обязательны.
 - Если в сценарии есть вызов внешнего API / сервиса / БД, нужен отдельный FR на интеграцию.
+- Запрещено повторять заголовок `### Функциональные требования` внутри тела секции.
 
 ## FR для интеграционных шагов
 Для интеграционного FR обязательно раскрывать:

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

@@ -1,5 +1,7 @@
 # Tech Use Case Rules
 
+Этот rule описывает только тело секции `### Технический use case`.
+
 ## Обязательные части
 - название
 - предусловия
@@ -14,3 +16,4 @@
 - Формат шага: смысловое действие + техническая реализация (endpoint/топик/операция).
 - Длинные технические детали выносить в FR и ссылаться на FR из шага.
 - Для интеграционных шагов описание обработки ошибок обязательно.
+- Запрещено повторять заголовок `### Технический use case` внутри тела секции.

_process/doc_rules_v3/documentation-rules.md

@@ -7,6 +7,10 @@
 - Структура документа определяется только template соответствующего типа.
 - Правила написания конкретного раздела определяются только соответствующим `common-elements` файлом.
 - Manifest типа документа хранится во frontmatter соответствующего template.
+- Генератор секции всегда пишет только тело секции, а не сам заголовок секции.
+- Дублирование заголовков запрещено: нельзя повторно выводить заголовок текущей секции внутри ее тела.
+- Если template уже содержит `### <Заголовок секции>`, то внутри тела допустимы только подзаголовки более глубокого уровня (`####` и ниже).
+- Нельзя повышать уровень заголовка внутри тела секции до `##` или повторять `###` с тем же названием секции.
 
 ## 2. Источники требований
 При генерации документа учитывать:
@@ -34,7 +38,14 @@
 5. Применить body template как единственный источник структуры.
 5. Проверить чек-лист совместимости с аналитикой (domain/sub_domain, роли слоев, интеграции, ошибки).
 
-## 6. Формат manifest типа документа
+## 6. Специальные инварианты для `api_method`
+- Во frontmatter обязательно должно присутствовать поле `endpoint`.
+- Внутри `## Details` секция `### Контракт` должна присутствовать ровно один раз.
+- Внутри тела секции `### Контракт` запрещено повторять заголовки `## Контракт` и `### Контракт`.
+- Внутри `### Технический use case` запрещено повторять заголовок `### Технический use case`.
+- Внутри `### Функциональные требования` запрещено повторять заголовок `### Функциональные требования`.
+
+## 7. Формат manifest типа документа
 Manifest типа документа хранится во frontmatter `templates/<doc_type>.template.md`.
 
 Минимальная схема:

_process/doc_rules_v3/global/frontmatter.md

@@ -20,6 +20,11 @@ related_code: []
 system_analytics_refs: []
 ```
 
+## Дополнительные обязательные поля по типам документов
+- Для `doc_type: api_method` поле `endpoint` обязательно.
+- Значение `endpoint` должно содержать HTTP-метод и путь, например: `GET /orders/{orderId}`.
+- Если в аналитике endpoint указан в заголовке раздела, use case, контракте или интеграционной схеме, его нужно перенести во frontmatter и не опускать.
+
 ## Body-метаданные для секции изменений
 Под корнем секции изменений указывать:
 - `domain`