RAGRAF Core

Навык работы с ядром RAGRAF: как получить факт из индекса, как понять, что факту нельзя верить, и что делать, когда индекс сломан. Всё опирается на файлы проекта C:\AutoClaw\RAGRAF; где стоит файл:строка — это проверено чтением, а не памятью.

Правила проекта лежат в AGENTS.md в корне проекта (читается автоматически), глубокий паспорт — docs/AGENTS-context.md, чекер конвенций — tools/Invoke-ProjectDoctrine.ps1.

1. Когда этот навык применяется

• Нужен ответ о коде проекта вместо чтения файлов: где определено, кто вызывает, что сломается, что в таблице, где запись в таблицу, где применяется класс.
• Индекс и код разошлись: результат выглядит устаревшим, ревизия старая, сторож сообщает о расхождении.
• Корпус не отвечает: capability=degraded, операция отказывает, срез недоступен.
• Меняются исключения, список языков или настройки корпуса.
• Реестр разработок показывает пустую ревизию или нули при живом индексе.

2. Первый шаг любой задачи — актуализировать корпус

Факты берутся из индекса, поэтому устаревший индекс запрещён:

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 — живую базу («как есть»). Расхождение между ними — находка.

5. Факт без ссылки файл:строка — догадка. Каждый значимый вывод подкреплять ссылкой на код.

6. Число из документа проверять по коду. Проект уже расходился с собственной документацией: на разных этапах код объявлял больше, чем называли документы (аудит 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, а не памятью.
7. Не читать секретоносные имена (перечень — AGENTS.md, раздел 6): только имя, размер и правило. Реестра git в проекте нет — единственная защита в том, чтобы не открывать их.
8. Не запускать чужой код во время разведки. Проект исполняется только тогда, когда задача именно об этом.
9. Не считать selftest гейтом: он всегда возвращает код 0 (src/ragraf/cli.py:906).
10. 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. После правки ядра:

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

1. Чекер знает свой baseline: 0 ошибок, 0 предупреждений (checks: 19), ошибок нет с 9 октября 2026 (AGENTS.md, раздел 10). Ошибка или новое предупреждение — находка.

7. Файлы навыка

• reference/operations.md — как выбрать операцию и чего она не показывает.
• reference/repair.md — рецепты: устаревший индекс, пустой реестр, degraded, зацикливание сторожа, ошибка в исключениях, откат к процессорному вычислителю.