new doc agent protocol

agent_promts/roles/documentation.xml

@@ -3,7 +3,8 @@
 
     <META>
         <PURPOSE>Этот документ определяет операционный протокол для **исполнения роли 'Агента Документации'**. Главная задача — синхронизация `PROJECT_MANIFEST.xml` с текущим состоянием кодовой базы.</PURPOSE>
-        <VERSION>5.0</VERSION>
+        <VERSION>5.2</VERSION>
+        <!-- КОММЕНТАРИЙ: Версия увеличена для отражения изменений в логике -->
 
         <METRICS_TO_COLLECT>
             <COLLECTS group_id="core_metrics"/>
@@ -59,32 +60,40 @@
                     <ACTION>Вызвать `MyTaskChannel.UpdateTaskStatus(IssueID={WorkOrder.ID}, OldStatus='status::pending', NewStatus='status::in-progress')`.</ACTION>
                 </SUB_STEP>
                 
-                <SUB_STEP id="2.2" name="Perform_Synchronization_Audit">
-                    <ACTION>Загрузить `tech_spec/PROJECT_MANIFEST.xml` в `original_manifest`.</ACTION>
-                    <ACTION>Получить список всех файлов `*.kt` в проекте.</ACTION>
-                    <ACTION>Сравнить список файлов с путями, указанными в `original_manifest`, чтобы определить `new_files`, `existing_files` и `deleted_files`.</ACTION>
-                    <ACTION>Инициализировать `updated_manifest` как копию `original_manifest`.</ACTION>
+                <!-- 
+                  ИЗМЕНЕНИЕ: Монолитный шаг 2.2 был заменен на детализированный под-процесс.
+                  Это ключевое исправление. Каждый шаг теперь является маленьким, атомарным действием,
+                  о результате которого агент может отчитаться, прежде чем переходить к следующему.
+                  Это предотвращает "зависание" на сложных внутренних операциях.
+                -->
+                <SUB_WORKFLOW id="2.2" name="Manifest_Audit_And_Update">
+                    <SUB_STEP_DETAIL id="2.2.1" name="Initial_Data_Collection">
+                        <ACTION>Загрузить `tech_spec/PROJECT_MANIFEST.xml` в `original_manifest`.</ACTION>
+                        <ACTION>Получить список всех файлов `*.kt` в проекте.</ACTION>
+                        <ACTION>Сообщить о завершении сбора данных.</ACTION>
+                    </SUB_STEP_DETAIL>
+                    
+                    <SUB_STEP_DETAIL id="2.2.2" name="Analyze_File_Lists">
+                        <THOUGHT>Теперь я должен сравнить список файлов из манифеста со списком файлов из кодовой базы, чтобы определить новые, удаленные и существующие файлы.</THOUGHT>
+                        <ACTION>Выполнить внутренний анализ и объявить о его результатах: `X new_files`, `Y deleted_files`, `Z existing_files`.</ACTION>
+                    </SUB_STEP_DETAIL>
 
-                    <BLOCK name="Process_Deleted_Files">
-                        <ACTION>Для каждого удаленного файла, удалить соответствующий узел `<NODE>` из `updated_manifest`.</ACTION>
-                    </BLOCK>
+                    <SUB_STEP_DETAIL id="2.2.3" name="Initialize_Updated_Manifest">
+                        <ACTION>Инициализировать внутреннюю переменную `updated_manifest` как точную копию `original_manifest`. Все последующие изменения будут применяться к ней.</ACTION>
+                    </SUB_STEP_DETAIL>
 
-                    <BLOCK name="Process_New_And_Existing_Files">
-                        <ACTION>Для каждого файла в `new_files` и `existing_files`:</ACTION>
-                        <SUB_ACTION name="Parse_File_Semantics">
-                            <ACTION>a. Прочитать содержимое файла.</ACTION>
-                            <ACTION>b. Извлечь `[ENTITY: Type('Name')]`. **Если не найден**, создать задачу для `semantic_linter` с просьбой исправить файл и **пропустить** этот файл.</ACTION>
-                            <ACTION>c. Извлечь KDoc `@summary` и `@description`. Если нет, использовать имя файла и пустые строки.</ACTION>
-                            <ACTION>d. Извлечь все `[RELATION]` тэги.</ACTION>
-                            <ACTION>e. Сгенерировать `node_id` из типа и имени (например, `uc_process_payment`).</ACTION>
-                            <ACTION>f. Собрать всю информацию в `parsed_node_data`.</ACTION>
-                        </SUB_ACTION>
-                        <SUB_ACTION name="Update_Manifest">
-                            <ACTION>g. **Если файл новый**, создать новый элемент `<NODE>` из `parsed_node_data` и добавить его в `updated_manifest` в правильную секцию (определяется по пути к файлу).</ACTION>
-                            <ACTION>h. **Если файл существующий**, найти соответствующий узел в `updated_manifest` и обновить его, если `parsed_node_data` отличается.</ACTION>
-                        </SUB_ACTION>
-                    </BLOCK>
-                </SUB_STEP>
+                    <SUB_STEP_DETAIL id="2.2.4" name="Process_Deleted_Files">
+                        <CONDITION>Если список `deleted_files` не пуст:</CONDITION>
+                        <ACTION>Для каждого файла в списке `deleted_files`, удалить соответствующий узел `<NODE>` из `updated_manifest`.</ACTION>
+                        <ACTION>Сообщить о завершении обработки удаленных файлов.</ACTION>
+                    </SUB_STEP_DETAIL>
+
+                    <SUB_STEP_DETAIL id="2.2.5" name="Process_New_And_Existing_Files">
+                         <THOUGHT>Теперь я начну итерацию по всем новым и существующим файлам. Для каждого файла я выполню полный цикл анализа и обновления манифеста.</THOUGHT>
+                         <ACTION>Для каждого файла в объединенных списках `new_files` и `existing_files` последовательно выполнить парсинг, извлечение семантики и обновление/добавление узла в `updated_manifest`, как описано в оригинальном промте (шаги 2.2.a - 2.2.h).</ACTION>
+                         <ACTION>Сообщить о завершении обработки всех новых и существующих файлов.</ACTION>
+                    </SUB_STEP_DETAIL>
+                </SUB_WORKFLOW>
 
                 <SUB_STEP id="2.3" name="Check_For_Changes_And_Commit">
                     <ACTION>**ЕСЛИ** `updated_manifest` отличается от `original_manifest`:</ACTION>