From 3b2f9d894e085ddc205a9528e9c178936f080805 Mon Sep 17 00:00:00 2001
From: busya <uglypod@gmail.com>
Date: Sun, 7 Sep 2025 22:00:06 +0300
Subject: [PATCH] chore(lint): apply semantic enrichment\n\nFiles modified: 1

---
 .../knowledge_base/semantic_linting.md        |  76 -----------
 .../knowledge_base/semantic_linting.xml       | 127 ++++++++++++++++++
 .../com/homebox/lens/data/di/ApiModule.kt     |   2 +-
 3 files changed, 128 insertions(+), 77 deletions(-)
 delete mode 100644 agent_promts/knowledge_base/semantic_linting.md
 create mode 100644 agent_promts/knowledge_base/semantic_linting.xml

diff --git a/agent_promts/knowledge_base/semantic_linting.md b/agent_promts/knowledge_base/semantic_linting.md
deleted file mode 100644
index f1dd131..0000000
--- a/agent_promts/knowledge_base/semantic_linting.md
+++ /dev/null
@@ -1,76 +0,0 @@
-[SemanticLintingCompliance]
-**Tags:** LINTING, SEMANTICS, STRUCTURE, ANCHORS, FILE_HEADER, TAXONOMY
-
-> Этот принцип определяет строгие правила структурирования кода, которые превращают его из простого текста в машиночитаемый, 'линтуемый' семантический артефакт. Моя задача — генерировать код, который не просто работает, но и на 100% соответствует этим правилам. Это не рекомендации по стилю, а строгие требования к архитектуре файла.
-
-## Rules
-
-### FileHeaderIntegrity
-Каждый `.kt` файл ДОЛЖЕН начинаться со стандартного заголовка из трех якорей, за которым следует объявление `package`. Порядок строгий и не подлежит изменению.
-
-**Rationale:** Этот заголовок служит 'паспортом' файла, позволяя любому инструменту (включая меня) мгновенно понять его расположение, имя и основное назначение, не парся код.
-
-**Example:**
-```kotlin
-// [PACKAGE] com.example.your.package.name
-// [FILE] YourFileName.kt
-// [SEMANTICS] ui, viewmodel, state_management
-package com.example.your.package.name
-```
-
-### SemanticKeywordTaxonomy
-Содержимое якоря `[SEMANTICS]` ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного, контролируемого списка (таксономии).
-
-**Rationale:** Это устраняет неоднозначность и обеспечивает консистентность семантического тегирования по всему проекту, делая поиск и анализ на основе этих тегов надежным и предсказуемым.
-
-#### Example Taxonomy
-- **Layer**: `ui`, `domain`, `data`, `presentation`
-- **Component**: `viewmodel`, `usecase`, `repository`, `service`, `screen`, `component`, `dialog`, `model`, `entity`
-- **Concern**: `networking`, `database`, `caching`, `authentication`, `validation`, `parsing`, `state_management`, `navigation`, `di`, `testing`
-
-### EntityContainerization
-Каждая ключевая сущность (`class`, `interface`, `object`, `data class`, `sealed class`, `enum class` и каждая публичная `fun`) ДОЛЖНА быть обернута в 'семантический контейнер'. Контейнер состоит из двух частей: открывающего блока разметки ПЕРЕД сущностью и закрывающего якоря ПОСЛЕ нее.
-
-**Rationale:** Это превращает плоский текстовый файл в иерархическое дерево семантических узлов. Это позволяет будущим AI-инструментам надежно парсить, анализировать и рефакторить код, точно зная, где начинается и заканчивается каждая сущность.
-
-**Structure:**
-1.  **Открывающий Блок Разметки:** Располагается непосредственно перед KDoc/декларацией. Содержит сначала якорь `[ENTITY]`.
-2.  **Тело Сущности:** KDoc, сигнатура и тело функции/класса.
-3.  **Закрывающий Якорь:** Располагается сразу после закрывающей фигурной скобки `}` сущности. Формат: `// [END_ENTITY: Type('Name')]`.
-
-**Example:**
-```kotlin
-// [ENTITY: DataClass('Success')]
-/**
- * @summary Состояние успеха...
- */
-data class Success(val labels: List<Label>) : LabelsListUiState
-// [END_ENTITY: DataClass('Success')]
-```
-
-### StructuralAnchors
-Крупные, не относящиеся к конкретной сущности блоки файла, такие как импорты и главный контракт файла, также должны быть обернуты в парные якоря.
-
-**Rationale:** Это четко разграничивает секции файла, позволяя инструментам работать с ними изолированно (например, 'добавить новый импорт в блок `[IMPORTS]`').
-
-**Pairs:**
-- `// [IMPORTS]` и `// [END_IMPORTS]`
-- `// [CONTRACT]` и `// [END_CONTRACT]`
-
-### FileTermination
-Каждый файл должен заканчиваться специальным закрывающим якорем, который сигнализирует о его полном завершении.
-
-**Rationale:** Это служит надежным маркером конца файла, защищая от случайного усечения и упрощая парсинг.
-
-**Template:** `// [END_FILE_YourFileName.kt]`
-
-### NoStrayComments
-Традиционные, 'человеческие' комментарии (`// Вот это сложная логика` или `/* ... */`) КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ.
-
-**Rationale:** Такие комментарии являются 'семантическим шумом' для AI. Они неструктурированы, часто устаревают и не могут быть использованы для автоматического анализа. Вся необходимая информация должна передаваться через семантические якоря или формальные KDoc-контракты.
-
-#### Approved Alternative
-В исключительном случае, когда мне нужно оставить заметку для другого AI-агента или для себя в будущем (например, объяснить сложное архитектурное решение), я использую специальный, структурированный якорь:
-
-**Format:** `// [AI_NOTE]: Пояснение сложного решения.`
-[/End SemanticLintingCompliance]
diff --git a/agent_promts/knowledge_base/semantic_linting.xml b/agent_promts/knowledge_base/semantic_linting.xml
new file mode 100644
index 0000000..faaba83
--- /dev/null
+++ b/agent_promts/knowledge_base/semantic_linting.xml
@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<SemanticProtocol version="1.1">
+    <Description>
+        Этот документ является единственным источником истины для правил, которые должны
+        соблюдаться в кодовой базе. Он используется как для автоматизированной валидации
+        (Python-скриптом), так и в качестве инструкции для LLM-агентов.
+    </Description>
+
+    <Rules>
+        <Rule id="FileHeaderIntegrity" enforcement="strict">
+            <Description>Каждый `.kt` файл ДОЛЖЕН начинаться со стандартного заголовка из трех якорей, за которым следует объявление package.</Description>
+            <Rationale>Заголовок служит 'паспортом' файла, позволяя инструментам мгновенно понять его расположение, имя и назначение.</Rationale>
+            <Definition type="regex">
+                <!-- CDATA используется для того, чтобы символы вроде '<' или '>' не были интерпретированы как XML -->
+                <Pattern><![CDATA[^\s*//\s*\[PACKAGE\]\s*(?P<package>.*?)\n//\s*\[FILE\]\s*(?P<file>.*?)\n//\s*\[SEMANTICS\]\s*(?P<semantics>.*)]]></Pattern>
+            </Definition>
+            <Example><![CDATA[
+// [PACKAGE] com.example.your.package.name
+// [FILE] YourFileName.kt
+// [SEMANTICS] ui, viewmodel, state_management
+package com.example.your.package.name
+            ]]></Example>
+        </Rule>
+        <Rule id="SemanticKeywordTaxonomy" enforcement="strict">
+            <Description>Содержимое якоря [SEMANTICS] ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного списка (таксономии).</Description>
+            <Rationale>Устраняет неоднозначность и обеспечивает консистентность тегирования по всему проекту.</Rationale>
+            <Definition type="taxonomy" targetGroup="semantics" delimiter=",">
+                <AllowedValues>
+                    <Group name="Layer">
+                        <Value>ui</Value><Value>domain</Value><Value>data</Value><Value>presentation</Value>
+                    </Group>
+                    <Group name="Component">
+                        <Value>viewmodel</Value><Value>usecase</Value><Value>repository</Value><Value>service</Value><Value>screen</Value><Value>component</Value><Value>dialog</Value><Value>model</Value><Value>entity</Value>
+                    </Group>
+                    <Group name="Concern">
+                        <Value>networking</Value><Value>database</Value><Value>caching</Value><Value>authentication</Value><Value>validation</Value><Value>parsing</Value><Value>state_management</Value><Value>navigation</Value><Value>di</Value><Value>testing</Value>
+                    </Group>
+                </AllowedValues>
+            </Definition>
+        </Rule>
+        <Rule id="EntityContainerization" enforcement="strict">
+            <Description>Каждая ключевая сущность (class, interface, fun и т.д.) ДОЛЖНА быть обернута в парные якоря [ENTITY]...[END_ENTITY].</Description>
+            <Rationale>Превращает плоский текстовый файл в иерархическое дерево семантических узлов для надежного парсинга AI-инструментами.</Rationale>
+            <Definition type="paired_regex">
+                <!-- Обратные ссылки (?P=type) и (?P=name) гарантируют симметричность тегов -->
+                <Pattern name="start"><![CDATA[//\s*\[ENTITY:\s*(?P<type>\w+)\('(?P<name>.*?)'\)\]]]></Pattern>
+                <Pattern name="end"><![CDATA[//\s*\[END_ENTITY:\s*(?P=type)\('(?P=name)'\)\]]]></Pattern>
+            </Definition>
+            <Example><![CDATA[
+// [ENTITY: DataClass('Success')]
+/**
+ * @summary Состояние успеха...
+ */
+data class Success(val labels: List<Label>) : LabelsListUiState
+// [END_ENTITY: DataClass('Success')]
+            ]]></Example>
+        </Rule>
+        <Rule id="StructuralAnchors" enforcement="strict">
+            <Description>Крупные, не относящиеся к конкретной сущности блоки файла, также должны быть обернуты в парные якоря.</Description>
+            <Rationale>Четко разграничивает секции файла, позволяя инструментам работать с ними изолированно (например, 'добавить новый импорт в блок IMPORTS').</Rationale>
+            <Definition type="paired_tags">
+                <Pairs>
+                    <Pair><Start>// [IMPORTS]</Start><End>// [END_IMPORTS]</End></Pair>
+                    <Pair><Start>// [CONTRACT]</Start><End>// [END_CONTRACT]</End></Pair>
+                </Pairs>
+            </Definition>
+            <Example><![CDATA[
+// ... file header ...
+package com.example
+
+// [IMPORTS]
+import a.b.c
+// [END_IMPORTS]
+
+// [CONTRACT]
+/** @summary ... */
+interface YourMainInterface
+// [END_CONTRACT]
+            ]]></Example>
+        </Rule>
+        
+        <Rule id="FileTermination" enforcement="strict">
+            <Description>Каждый файл должен заканчиваться специальным закрывающим якорем, который сигнализирует о его полном завершении.</Description>
+            <Rationale>Служит надежным маркером конца файла, защищая от случайного усечения и упрощая парсинг.</Rationale>
+            <Definition type="dynamic_regex">
+                <!-- Плейсхолдер {file_name} будет заменяться на имя файла во время валидации -->
+                <Pattern><![CDATA[//\s*\[END_FILE_{file_name}\]\s*$]]></Pattern>
+            </Definition>
+            <Example><![CDATA[
+// ... file content ...
+}
+// [END_ENTITY: SomeClass('MyClass')]
+
+// [END_FILE_MyClass.kt]
+            ]]></Example>
+        </Rule>
+        <Rule id="NoStrayComments" enforcement="strict">
+            <Description>Традиционные, 'человеческие' комментарии (`// ...` или `/* ... */`) КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ.</Description>
+            <Rationale>Такие комментарии являются 'семантическим шумом' для AI, неструктурированы и не могут быть использованы для автоматического анализа.</Rationale>
+            <Definition type="negative_regex">
+                <!-- Этот regex находит // (не являющийся частью якоря) и блочные комментарии /* */ -->
+                <Pattern><![CDATA[(?<!\[)\s*\/\/[^\[\n\r]*|(?<!:)\/\*[\s\S]*?\*\/]]></Pattern>
+            </Definition>
+            <Example type="forbidden"><![CDATA[
+// Это плохой, запрещенный комментарий
+val x = 1 
+
+/*
+    И это тоже запрещено
+*/
+val y = 2
+            ]]></Example>
+        </Rule>
+        <Rule id="ApprovedAINote" enforcement="allowed">
+            <Description>Единственным исключением из правила 'NoStrayComments' является специальный, структурированный якорь для заметок между AI-агентами.</Description>
+            <Rationale>Позволяет оставлять пояснения к сложным архитектурным решениям в машиночитаемом формате.</Rationale>
+            <Definition type="regex">
+                <Pattern><![CDATA[//\s*\[AI_NOTE\]:\s*(.*)]]></Pattern>
+            </Definition>
+            <Example type="allowed"><![CDATA[
+// [AI_NOTE]: Эта реализация использует кастомный алгоритм из-за требований к производительности.
+fun processData() { /* ... */ }
+            ]]></Example>
+        </Rule>
+
+    </Rules>
+</SemanticProtocol>
\ No newline at end of file
diff --git a/data/src/main/java/com/homebox/lens/data/di/ApiModule.kt b/data/src/main/java/com/homebox/lens/data/di/ApiModule.kt
index 8287850..763efeb 100644
--- a/data/src/main/java/com/homebox/lens/data/di/ApiModule.kt
+++ b/data/src/main/java/com/homebox/lens/data/di/ApiModule.kt
@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.data.di
 // [FILE] ApiModule.kt
-// [SEMANTICS] di, hilt, networking
+// [SEMANTICS] di, networking
 package com.homebox.lens.data.di
 
 // [IMPORTS]