## Работа с кодом: сначала RAGRAF, потом чтение файлов (обязательно)

RAGRAF — графово-векторный индекс кода, подключённый как MCP-сервер `ragraf`.
Полное имя инструмента — `mcp__ragraf__ragraf_<имя>`, например
`mcp__ragraf__ragraf_ensure`; ниже — короткая форма (`ensure`). Полный список
инструментов печатает `index_status`, реестр разработок — `catalog`.

**Правило.** Любая задача о коде проекта начинается с `ensure`, а факт берётся
из индекса со ссылкой `файл:строка` — до чтения файлов целиком. Причина не в
удобстве: знания о конкретном проекте у модели — смесь догадок и устаревших
данных, а индекс отдаёт проверяемую ссылку.

1. **Первый шаг — `ensure`.** Он сверяет контрольную сумму корпуса с
   проиндексированной и сам пересобирает отставший индекс. `status` в ответе:
   `actual` — актуален, `reindexed` — пересобран только что, `created` — корпуса
   не было и он создан, `not_a_project` — каталог не похож на проект, `error` —
   причина в `reason`.
2. **Если непонятно, о каком проекте отвечает сервер — `context`.** Он работает
   и когда корпус не выбран: называет корпус, основание выбора, корень, ревизию,
   свежесть и режим. Отвечать о чужом репозитории молча — измеренная ошибка.
3. **Корпус выбирается автоматически** из рабочего каталога. Если каталог чужой,
   инструменты ответят «корпус не выбран»: сначала `catalog`, затем
   `use_project` с именем разработки или путём к каталогу.
4. **Признак `stale: true` значит, что фактам индекса верить нельзя** до
   переиндексации: код ушёл вперёд. После правок кода — снова `ensure`.
5. **Поиск — `search` (несколько запросов сразу) и `symbol`**; файловый поиск
   (`grep`/`rg`/`Grep`) допустим только после того, как индекс не дал ответа, и
   в отчёте называется причина «индекс не нашёл X».
6. **Перед написанием SQL — `write_check`**: единственная проверка, которая
   ловит несуществующую колонку до запуска кода.
7. **Перед правкой прав — `policy_trace`**; красный флаг
   `default_behavior: allow` значит «неизвестное действие получает право».
8. **Режим не завышается.** `capability=degraded` — честная пометка: граф
   свойств кода не построен, срез недоступен, остальное работает.
9. **Если инструментов `mcp__ragraf__*` нет вовсе** — работать чтением файлов и
   прямо сказать, что факты НЕ подтверждены индексом.

### Что делает хук, установленный вместе с сервером

* **SessionStart** — в контекст приходит строка: имя корпуса, ревизия, свеж ли
  индекс. Это не украшение: иначе первый шаг задачи начинается с догадки.
* **UserPromptSubmit** — первый запрос сеанса становится меткой задачи, и все
  обращения к индексу учитываются в ней. Последующие запросы метку не меняют:
  иначе одна задача дробилась бы на десять.
* **PreToolUse** — перед файловым поиском и чтением гейт напоминает про
  `search`/`symbol`. Режим по умолчанию `warn` (только подсказка); строгие
  включаются переменной `RAGRAF_GATE_MODE=ask|deny|off`.
* **Stop** — в конце хода приходит строка отчёта по задаче: сколько обращений,
  сколько фактов, доля со ссылкой `файл:строка`.

### Секреты

Значения не печатать и не хардкодить. Пароль, токен или ключ ищется в хранилище
RAGRAF: `secrets list --query <что>` → `secrets show` → `secrets reveal --reason
"<зачем>"` (выдача попадает в аудит). Встреченный секрет сохраняется копией под
новым именем, а не перезаписью: истории версий в хранилище нет.

### Git

`.ragraf/` — машинно-локальный индекс, в коммит не попадает: строка `.ragraf/` в
**корневом** `.gitignore`, проверка — `git check-ignore -v .ragraf`. Резервные
копии файлов кладутся в `.ragraf/` или вне корпуса: копия рядом с рабочим файлом
сдвигает контрольную сумму корпуса и запускает лишнюю переиндексацию.