--- name: ragraf-core description: Работа с ядром RAGRAF (C:\AutoClaw\RAGRAF) — графово-векторным индексом кода для агентов. Use when работа идёт с индексом корпуса, операциями чтения, свежестью, схлопыванием дублей, исключениями, языками, CPG/Joern, телеметрией; когда индекс отдаёт устаревшие факты, capability=degraded, реестр пуст; когда нужно выбрать операцию вместо чтения файлов. --- # RAGRAF Core Навык работы с ядром RAGRAF: как получить факт из индекса, как понять, что факту нельзя верить, и что делать, когда индекс сломан. Всё опирается на файлы проекта `C:\AutoClaw\RAGRAF`; где стоит `файл:строка` — это проверено чтением, а не памятью. Правила проекта лежат в `AGENTS.md` в корне проекта (читается автоматически), глубокий паспорт — `docs/AGENTS-context.md`, чекер конвенций — `tools/Invoke-ProjectDoctrine.ps1`. ## 1. Когда этот навык применяется - Нужен ответ о коде проекта вместо чтения файлов: где определено, кто вызывает, что сломается, что в таблице, где запись в таблицу, где применяется класс. - Индекс и код разошлись: результат выглядит устаревшим, ревизия старая, сторож сообщает о расхождении. - Корпус не отвечает: `capability=degraded`, операция отказывает, срез недоступен. - Меняются исключения, список языков или настройки корпуса. - Реестр разработок показывает пустую ревизию или нули при живом индексе. ## 2. Первый шаг любой задачи — актуализировать корпус Факты берутся из индекса, поэтому устаревший индекс запрещён: ```powershell python tools/ragraf.py ensure <каталог проекта> # найти, пересобрать, создать python tools/ragraf.py -p config/ragraf.yaml check # только сверка суммы ``` `ensure` отвечает полем `status`: `actual` — индекс актуален, `reindexed` — пересобран только что, `created` — корпуса не было и он создан, `not_a_project` — каталог не похож на проект, `error` — причина в поле `reason`. Признак `stale` в ответе любой операции означает, что код ушёл вперёд и факты индекса неверны. Работать по ним нельзя. ## 3. Выбор операции вместо чтения файлов | Вопрос | Операция | |---|---| | «Какой корпус выбран и на каком основании» (работает и без выбора) | `context` | | «Где определена функция или класс» | `symbol` | | «Где описано, как устроено» | `search` | | «Кто вызывает» / «что вызывает» | `callers` / `callees` | | «Что затронет правка» | `impact` | | «Тело функции» (только когда нужен текст) | `code` | | «Что в таблице» / «кто читает и пишет» | `schema` / `table_usage` | | «Можно ли так записать» — до написания SQL | `write_check` | | «Кто и по какому условию получает право» | `policy_trace` | | «Есть ли правило в стилях и где класс применён» | `class_usage` | | «Актуален ли индекс» | `freshness`, `index_status` | | «Общая структура» | `repo_map` | | «Что заведено в реестре» | `catalog` | | «Актуальное содержимое файла с пометкой отличий» | `live_read` | | «Что в ЖИВОЙ базе: базы, таблицы, колонки, типы» | `db_schema` | | «Устройство одной таблицы» | `db_table` | | «Связи таблицы: факт и вывод» | `db_relations` | | «Как выглядят данные» (сборный пример) | `db_sample` | | «Что изменилось в структуре баз» | `db_drift` | | «Чего нет в базе из того, что код использует» | `db_cross` | Через оболочку это `python tools/ragraf.py -p <конфиг> query <операция> …`, через инструменты агента — `ragraf_<операция>`. Подробный разбор выбора — `reference/operations.md`. Чего операция не заменяет: полнотекстового чтения там, где нужны детали. `symbol` и `code` возвращают диапазон строк, а не файл целиком. ## 4. Жёсткие правила **Слой живых баз: четыре границы, которые нельзя переступать.** 1. **`db_relations` делит связи по происхождению.** `stated` — внешний ключ, это ФАКТ (достоверность 1.0). `derived` — вывод по имени колонки (`user_id` → `users`), это ПРЕДПОЛОЖЕНИЕ (0.4). Ссылаться на вывод как на структуру нельзя: в живых базах внешние ключи часто не объявлены (измерено: 0 связей из FK на 86 таблиц), поэтому вывод — единственный способ увидеть связи, но он бывает неверным. 2. **`db_sample` — снимок, а не текущее состояние.** Строки меняются, структура нет. Не пересказывать пример как факт о данных. 3. **«Скрыто: персональные данные» — не пустое поле.** Значения персональных колонок не собираются вовсе. Колонка присутствует, значение закрыто. 4. **Схема из миграций и живая база — РАЗНЫЕ источники.** `schema` читает миграции («как задумано»), `db_schema` — живую базу («как есть»). Расхождение между ними — находка. 1. **Факт без ссылки `файл:строка` — догадка.** Каждый значимый вывод подкреплять ссылкой на код. 2. **Число из документа проверять по коду.** Проект уже расходился с собственной документацией: на разных этапах код объявлял больше, чем называли документы (аудит 12.10.2026: 22 операции фасада и 23 инструмента против 17, 18, 16 и 21 в документах — дефект B-01 в реестре). Действующие числа на 16.10.2026 — **40 инструментов и 38 операций фасада** (`src/ragraf/mcp_server.py`, `src/ragraf/facade.py`) плюс 39 имён в CLI (`OPS` в `src/ragraf/cli.py`). Числа проверяются подсчётом `"name": "ragraf_*"`, `def op_*` и `OPS`, а не памятью. 3. **Не читать секретоносные имена** (перечень — `AGENTS.md`, раздел 6): только имя, размер и правило. Реестра git в проекте нет — единственная защита в том, чтобы не открывать их. 4. **Не запускать чужой код во время разведки.** Проект исполняется только тогда, когда задача именно об этом. 5. **Не считать `selftest` гейтом:** он всегда возвращает код 0 (`src/ragraf/cli.py:906`). 6. **`empty result` — это код 0 с `found=false`**, а не ошибка; код 3 означает «операция невыполнима сейчас», например срез при `capability != "full"` (`src/ragraf/cli.py:336-356`). ## 5. Что ломается чаще всего 1. **Реестр расходится с индексом после `ensure`.** `src/ragraf/ensure.py:308-312` регистрирует корпус до индексации и не записывает результат прогона. Измерено: запись с триггером `register` имеет пустые `rev_id`/`capability` и `node_count=0`, тогда как в индексе 1855 узлов. Лечение — рецепт в `reference/repair.md`. 2. **Правка исключений молча выбрасывает рабочий код.** Сопоставление регистрозависимо (`src/ragraf/util.py:72-158`); `**/cache/**` не ловит `src/Cache/`. Перед расширением списка — `python tools/measure_safe_excludes.py`. 3. **Схлопывание дублей включают, не понимая цены.** Включение меняет контрольную сумму корпуса: сторож свежести один раз переиндексирует корпус. Выбор главной копии обязан быть детерминированным (`src/ragraf/dedupe.py:165-223`), иначе переиндексация не остановится. 4. **`capability=degraded` принимают за поломку.** Это честная пометка: CPG не построен, срез недоступен, остальное работает. Причина всегда записана в `index_status`. 5. **Видеокарта считается гарантией.** Путь вычислений на карте требует `sentence-transformers` и `torch`, не объявленных в описании пакета (`src/ragraf/compute.py:141-146`); порог окупаемости — 1800 текстов для векторов и около 5000 вершин для графа. ## 6. Порядок работы 1. Актуализировать корпус (`ensure`). 2. Сформулировать вопрос в терминах операции, а не файла. 3. Получить факты со ссылками и убедиться, что индекс не помечен устаревшим. 4. Читать файл целиком только там, где операция не отвечает на вопрос. 5. После правки ядра: ```powershell python tools/ragraf.py -p config/ragraf.yaml reindex python tools/ragraf.py -p config/ragraf.yaml check pwsh -NoLogo -NoProfile -NonInteractive -File tools/Invoke-ProjectDoctrine.ps1 ``` 6. Чекер знает свой baseline: **0 ошибок, 0 предупреждений** (`checks: 19`), ошибок нет с 9 октября 2026 (`AGENTS.md`, раздел 10). Ошибка или новое предупреждение — находка. ## 7. Файлы навыка - `reference/operations.md` — как выбрать операцию и чего она не показывает. - `reference/repair.md` — рецепты: устаревший индекс, пустой реестр, `degraded`, зацикливание сторожа, ошибка в исключениях, откат к процессорному вычислителю.