# Промт: диагностика RAGRAF после обновления AutoClaw

Назначение файла — быть **готовым заданием** для агента в новой версии AutoClaw.
Владелец запускает его после обновления приложения; агент проводит диагностику
по точкам ниже и вносит правки **только в фактически сломанное**.

Как запускать: передать агенту текст из раздела «ЗАДАНИЕ» целиком. Если агент
работает в том же рабочем каталоге, достаточно строки
«прочитай `docs/03_implementation/PROMPT-AFTER-AUTOCLAW-UPDATE.md` и выполни
раздел ЗАДАНИЕ».

Базис (эталон «до обновления») замерен **12 октября 2026**, версия AutoClaw
до обновления — `1.18.5` (`.openclaw-autoclaw\.startup-validation.json`).
После обновления номер версии изменится — это ожидаемо и находкой не является.

---

## ЗАДАНИЕ

### 0. Роль и порядок работы

Ты работаешь в проекте **RAGRAF** (`RAGRAF`) — графово-векторный
индекс кода, к которому подключён AutoClaw. Перед любым действием прочитай
`AGENTS.md` проекта и `docs/AGENTS-context.md` и работай по ним: там инварианты,
которые нельзя ломать. Факт без ссылки `файл:строка` — догадка, а не факт.

Задача — разовая: **после обновления AutoClaw проверить, что оно не испортило
связку «AutoClaw ↔ RAGRAF», и починить испорченное.** Не перестраивать проект,
не «улучшать» ничего сверх найденного дефекта, не переименовывать, не
переформатировать.

### 0.1 Границы, которые нельзя нарушать

1. **Ничего не удалять из существующих файлов владельца.** Только добавлять и
   изменять. Если правка требует удаления файла или его части — назвать это
   владельцу и дождаться ответа.
2. **Не трогать установленное приложение**: `C:\Program Files\AutoClaw\**`,
   включая `resources\zcode\` и любые подписанные бинарники. Патч приложения
   запрещён.
3. **Не включать и не выключать MCP-серверы правкой файлов настроек.** Файлами
   `openclaw.json`, `mcporter.json`, `settings.json` управляет само приложение;
   автоконфигурация MCP может включаться сама. Тебе разрешено их **читать** и
   сообщать о расхождении, но не править.
4. **Не печатать содержимое секретоносных путей.** Раздел 6 правил проекта
   перечисляет их по именам: только имя, размер и вывод «не открывался».
   Реестра git в проекте нет — единственная защита в том, что эти пути не читают.
5. **Не выдавать желаемое за проверенное.** Проверку, которую запустить не
   удалось, назвать прямо и не писать вместо неё вывод.
6. **`~\.pi\agent\AGENTS.md` — не перезаписывать целиком.** В нём 134 466 байт
   правил, среди которых живые реквизиты (§7.2 — пароль открытым текстом).
   Если содержимое утрачено, восстанавливать только утраченные разделы из
   резервных копий рядом с файлом, а не генерировать файл заново.

### 0.2 Первое действие — актуализировать корпус

```powershell
cd RAGRAF
python tools/ragraf.py ensure RAGRAF
```

Ожидается `status=actual` (или `reindexed`). Если `error` или `not_a_project` —
сказать об этом прямо и дальше работать чтением файлов, отметив в отчёте, что
факты не подтверждены индексом.

**Самопроверка подхвата правил.** Если, выполняя это задание, ты **не видишь в
своих инструкциях раздела «8. Обязательное использование RAGRAF»** — правила
из `~\.pi\agent\AGENTS.md` больше не подхватываются. Это находка уровня «стоп»:
зафиксируй её первой строкой отчёта и переходи к блоку 1.

### 0.3 Эталон «до обновления» (замерено 12.10.2026)

Сверяй с этим. Отличаться **должны**: версия приложения, счётчики ревизий и
прогонов, размер `catalog.json`, содержимое логов и трасс. Отличаться **не
должны** хеши файлов правил, навыка, ядра и настройки подключения.

| Точка | Путь | Эталон |
|---|---|---|
| Индекс проекта | `config/ragraf.yaml` | ревизия `rev-0039`, файлов 491 |
| Сумма корпуса | `check` | `514a115a52a54b009f611c6d89b51669076ecb7c0c8c089183d6d055e4b08659` |
| Правила проекта | `AGENTS.md` | 53 970 б, sha256 `6B941AB8867CFBDF…` |
| Паспорт проекта | `docs/AGENTS-context.md` | 34 065 б, sha256 `1573DC0F7A7EA1CF…` |
| Конфиг корпуса | `config/ragraf.yaml` | 5 156 б, sha256 `325C07B87E1D78C6…` |
| Реестр разработок | `catalog/catalog.json` | 16 разработок (растёт — норма) |
| Навык в репозитории | `docs/skills/ragraf-core/SKILL.md` | 9 811 б, `6D4C33534B675357…` |
| Навык, ссылка операций | `…/reference/operations.md` | 7 546 б, `21C6AF9F456C348C1…` |
| Навык, восстановление | `…/reference/repair.md` | 11 271 б, `995A56BB9036B6B92…` |
| Правила рабочего каталога | `AGENTS.md` | 12 524 б, `901C10FD66EA8CDF…` |
| Правила pwsh-среды | `~\.pi\agent\AGENTS.md` | 134 466 б, `1E658D75A9E43EBB…` |
| Линтер PowerShell | `~\.pi\agent\tools\Test-PwshApiVintage.ps1` | 12 846 б, `AA8C1FC6AEE62111…` |
| Чекер конвенций | `tools/Invoke-ProjectDoctrine.ps1` | 14 проверок, 0 ошибок, 0 предупреждений |
| Чистота текстов | `tools/check_bom_crlf.py` | 38 из 38 чистых |
| Git-источник | `RAGRAF.git\RAGRAF` | ветка `main`, коммит `6a62a07` |
| MCP рабочего каталога | `config\mcporter.json` | 2 сервера, оба `enabled: true`: `autoclaw-productivity`, `autoclaw-github` |
| Админ-панель RAGRAF | `src/ragraf/admin_server.py` | порт 8777, токен печатается при старте |
| Сервер Joern | порт 9500 | свободен, процессов `java.exe` — 0 |
| Конфигов корпусов | `config/*.yaml` | 18 (растёт — норма) |

---

### Блок 1. Правила агента и подхват файлов (самый вероятный ущерб)

**П1.1. Целостность файла правил pwsh-среды.**

```powershell
$f = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.pi\agent\AGENTS.md'
$i = Get-Item -LiteralPath $f
"{0} байт; {1}" -f $i.Length, (Get-FileHash -LiteralPath $f -Algorithm SHA256).Hash
```

Ожидается 134 466 байт и хеш `1E658D75A9E43EBB…`. Если размер или хеш
изменились — выяснить, что именно пропало, а не перезаписывать файл.

**П1.2. Разделы на месте.** В файле обязаны присутствовать разделы `## 0.` … `## 11.`,
в том числе `## 8. Обязательное использование RAGRAF`, `### 8.17`, `### 8.20`,
`## 10.` и `## 11.`. Проверять **свойством**, а не поиском отдельной строки:

```powershell
$t = Get-Content -LiteralPath $f -Raw
[regex]::Matches($t, '(?m)^##\s+\d+\.').Count          # ожидается 12 (0..11)
('### 8.17 .*' -match '(?m)^###\s+8\.17\s+\S+')
```

**П1.3. Файлы-маркеры рабочего каталога.** Проверить, что на месте и не
обнулены: `AGENTS.md`, `USER.md`, `TOOLS.md`, `SOUL.md`,
`IDENTITY.md`, `HEARTBEAT.md`. У пяти последних эталон от 26.08.2026 — они
обновлением меняться не должны.

**П1.4. Рабочий каталог агента.** В `.openclaw-autoclaw\openclaw.json` поле
`agents.defaults.workspace` обязано остаться `<полигон>`. Список `agents.list`
обязан содержать запись с `default: true` и тем же workspace. Если каталог
поменялся, **весь каскад** подхвата файлов (проектный `AGENTS.md` из
родительских каталогов до границы `.git`, пользовательский `.pi\agent\AGENTS.md`)
перестанет работать — это находка первой важности.

**П1.5. Инструкции, приходящие от платформы.** Проверить, что рабочие инструкции
(`.cluster\expert-playbook.md`) на месте. Файлы SOP платформы
(`expert-sop-im.txt`, `expert-sop-last-known-good.json`) обновлением меняются
законно — их содержимое не сверять построчно, достаточно проверить, что в
`expert-sop-last-known-good.json` осталось упоминание `ragraf` (до обновления —
1 совпадение). Пропало — это разрыв связки, сообщить владельцу.

**П1.6. Хранилище инструкций проекта.** В `runtime\runtime.sqlite` таблица
`governed_project_instruction_revisions` содержала 38 строк. Миграции при
обновлении могут добавлять строки — уменьшение или пустая таблица означает
потерю слепка инструкций проекта.

```powershell
# только чтение, режим ro
python -c "import sqlite3;print('строк:', 'см. таблицу governed_project_instruction_revisions')"
```

### Блок 2. Навыки

Навык `ragraf-core` — **локальный навык проекта**, а не запись магазина: его нет
в `runtime\zwork-agent\skills-preinstall.json`, и подделывать идентификатор
магазина нельзя.

**П2.1. Навык в репозитории не изменён.** Три файла `docs\skills\ragraf-core\`
обязаны иметь эталонные хеши из таблицы 0.3. Если изменились — сначала
посмотреть, кто и когда (mtime), а не восстанавливать вслепую.

**П2.2. Навык развёрнут в каждый аккаунт.** На машине две учётные записи:

- `…\AutoClaw-oversea-official\accounts\53fa6b3b559c638c798a72686d01e6da331c2f0a886bd5428db5ed926884a587\runtime\zwork-agent\skills\ragraf-core\`
- `…\AutoClaw-oversea-official\accounts\fe79f9171d45287e51711ad5acd75648ac5c24af77965bf7cc761a590e5213d4\runtime\zwork-agent\skills\ragraf-core\`

Копии обязаны совпадать с репозиторием **побайтово** (те же хеши). Порядок при
расхождении: правка идёт в проект, затем копируется в служебный каталог, а не
наоборот.

**П2.3. Форма навыка.** `SKILL.md` начинается с `---`; поля `name` и
`description` разбираются построчно; размер не больше 256 КиБ; UTF-8 без BOM;
переводы строк LF.

```powershell
$s = 'docs\skills\ragraf-core\SKILL.md'
$b = [IO.File]::ReadAllBytes($s)
"BOM={0}  CRLF={1}  first3={2}" -f (($b[0] -eq 0xEF) -and ($b[1] -eq 0xBB) -and ($b[2] -eq 0xBF)),
    ([IO.File]::ReadAllText($s) -match "`r`n"), ($b[0..2] -join ',')
```

**П2.4. Навык виден агенту.** Если в текущем Run навык `ragraf-core` не
перечислен среди доступных — это находка (навыки читаются из служебного каталога
аккаунта; смена аккаунта или новые правила изоляции могли его отключить).

**П2.5. Посторонние навыки.** Список каталогов в `…\zwork-agent\skills\` до
обновления содержал 23 навыка и `ragraf-core` среди них. Обновление **добавляет**
навыки — это норма; **исчезновение** своего навыка — находка.

### Блок 3. Подключение RAGRAF к AutoClaw

**П3.1. Состояние подключения — факт, а не догадка.** До обновления MCP-сервер
RAGRAF **не был зарегистрирован** в AutoClaw: в `openclaw.json` раздел `mcp.servers`
содержал только `autoclaw-productivity`, `autoclaw-github`, `autoclaw-figma`,
`notion`, `connector:vercel`, `connector:cloudflare`; инструментов `ragraf_*`
в сессии не было, и работа шла через оболочку командами
`python tools/ragraf.py …` — это штатный путь, он описан в разделе 8.2.1 правил.

Проверить:

```powershell
# инструменты ragraf_* в текущем Run (если доступен tool_search)
# и реестр MCP
Get-Content 'C:\Users\<пользователь>\.openclaw-autoclaw\openclaw.json' -Raw |
  Select-String -Pattern 'ragraf' -SimpleMatch
```

Возможны два исхода, и оба надо назвать честно:

- `ragraf_*` **не появились** — как было, связка работает через CLI; ничего не
  делать, зафиксировать в отчёте.
- `ragraf_*` **появились** — проверить их работу и, если сервер поднят с
  `--project`, убедиться, что он указывает на нужный корпус
  (`tools\ragraf-mcp.py --project <конфиг> --agent AutoClaw --agent-kind autoclaw`).
  Имя агента в статистике брать из `clientInfo`, а если не задано — передавать
  параметром.

**П3.2. Автоконфигурация MCP не должна была тронуть конфиги рабочего каталога.**
Сверить `config\mcporter.json` с эталоном 0.3: два сервера, оба
включены. Отличие — находка, **но править файл самому нельзя** (см. 0.1, п. 3):
сообщить владельцу и предложить шаг через интерфейс приложения.

**П3.3. Одноразовая установка автоматизирована без нашего участия.** Плагин
`zcode-runtime` с `runtimeEnabled` и набор `pi-resources` (включая 11 ревизий, где
лежит копия навыка `ragraf-core`) — служебные. Уменьшение числа ревизий
`pi-resources` — не потеря, это ротация; тревогой считать только исчезновение
последней ревизии.

**П3.4. Настройки безопасности и прав не понижены.** В `openclaw.json`:
`tools.exec.security = full`, `tools.exec.ask = off`, `tools.deny` содержит
`browser`. В `settings.json`: `safety.highRiskAction = allow`,
`safety.defaultDecision = allow`. Изменение любого из этих значений —
находка, которую надо назвать владельцу **до** любых правок: это его решение,
а не дефект.

### Блок 4. Ядро RAGRAF не пострадало

**П4.1. Индекс и сумма.**

```powershell
cd RAGRAF
python tools/ragraf.py -p config/ragraf.yaml check
```

Ожидается: ревизия `rev-0039`, сумма совпадает с записанной, «реиндексация не
требуется». Расхождение суммы при неизменных файлах — находка: смотреть, какой
файл выпал из скана или добавился.

**П4.2. Точка входа MCP отвечает.**

```powershell
python tools/ragraf.py -p config/ragraf.yaml query symbol --name corpus_hash
python tools/ragraf.py -p config/ragraf.yaml status
```

Пустой результат — это код 0 и `found=false`, а не ошибка. Код 3 — операция
невыполнима сейчас (`slice` при `capability != "full"`).

**П4.3. Режим не завышен.** В `status` поле `capability` обязано **соответствовать
содержимому графа**: `full` — только если в графе есть рёбра от свойств кода.
Ложный `full` — измеренный дефект этого проекта; если появился, это находка.

**П4.4. Панель управления.**

```powershell
python tools/ragraf-admin.py --no-browser
```

Ожидается запуск на `127.0.0.1:8777` и напечатанный локально токен. Токен в
отчёт и в документы не переносить. После проверки панель остановить.

**П4.5. Висящие процессы.** До работы и после неё:

```powershell
Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
  Select-Object ProcessId, @{n='MB';e={[int]($_.WorkingSetSize/1MB)}}
(Get-NetTCPConnection -LocalPort 9500 -ErrorAction SilentlyContinue | Measure-Object).Count
```

Ожидается 0 процессов и свободный порт 9500. Оставшиеся JVM держат гигабайты и
порт; остановка сервера Joern по правилам проекта может уходить в интерпретатор
предыдущего поколения — при снятии процесса проверять и родительский `cmd.exe`.

### Блок 5. Окружение исполнения (что обновление могло сдвинуть)

**П5.1. Интерпретатор оболочки.** `$PSVersionTable.PSVersion` — 7.6.x,
`PSEdition` = `Core`. Если Run начал идти под 5.1 — это находка: весь
PowerShell-код проекта написан под `pwsh` 7.6 и использует `??`, `?.`, `?:`,
`-Encoding utf8NoBOM`.

**П5.2. Состав переменных окружения.** В сессии исполнения **отсутствуют**
`APPDATA`, `LOCALAPPDATA`, `HOME`, `USER`, `TMP` — это норма для exec-сессии;
пути к пользовательским каталогам берутся только через
`[Environment]::GetFolderPath(...)`. Если переменные **появились** — хорошо, но
код менять не нужно; если исчезли `TEMP`, `USERPROFILE`, `PATHEXT` — находка.

```powershell
foreach($n in 'APPDATA','LOCALAPPDATA','HOME','USER','TMP','TEMP','USERPROFILE','PATHEXT'){
  "{0} = {1}" -f $n, $(if($null -eq [Environment]::GetEnvironmentVariable($n)){'<нет>'}else{'<есть>'})
}
```

**П5.3. Git подписывается владельцем, а не агентом.** Переменные
`GIT_AUTHOR_NAME`/`GIT_COMMITTER_NAME` в сессии равны `zwork` — так было до
обновления. Перед **любым** коммитом их снимать и задавать идентичность владельца:

```powershell
Remove-Item Env:\GIT_AUTHOR_NAME,Env:\GIT_AUTHOR_EMAIL,`
            Env:\GIT_COMMITTER_NAME,Env:\GIT_COMMITTER_EMAIL -ErrorAction SilentlyContinue
# идентичность — из истории репозитория, а не из памяти:
# git log -1 --format='%an <%ae>'
```

**П5.4. Java и модель эмбеддингов.** Отсутствие JVM, видеокарты или модели —
повод поставить честную пометку и причину, а не исключение. Деградация — не дефект.

### Блок 6. Регресс: проверки проекта

```powershell
cd RAGRAF
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
python tools/check_bom_crlf.py
python tools/check_service_excludes.py
```

Ожидается: чекер — **14 проверок, 0 ошибок, 0 предупреждений**; `check_bom_crlf`
— 38 из 38; ревизия и сумма согласованы.

По типу правки — профильные проверки, каждая печатает вердикт:

```powershell
python tests/test_ensure.py            # реестр и ensure
python tests/test_dedupe.py            # схлопывание дублей
python tests/test_lang_routing.py      # языки разбора
python tests/test_graph_algo.py        # направление обхода, сохранение массы
python tests/test_capability_consistency.py   # режим против содержимого графа
```

**Любая ошибка или новое предупреждение чекера — находка.** Ожидаемого красного
состояния нет.

**Чего не делать в проверках.** Не запускать `python -m pytest`: конфигурации
pytest в репозитории нет, он не соберёт ни одного теста. Не считать
`selftest` гейтом: он всегда возвращает код 0. Не править строки, на которые
смотрит проверка, чтобы проверка прошла.

### Блок 7. Как чинить найденное

Порядок для каждого дефекта:

1. **Сначала назвать факт замера** — команда, вывод, `файл:строка`. Без замера
   правка не начинается.
2. **Найти ближайший прецедент в коде** и повторить его, а не изобретать.
3. **Дифф минимальный.** Постоянное состояние, контракт ответа, схема хранилища,
   нумерация ревизий и реестр — трогать только с предупреждением владельцу и
   планом отката.
4. **Замеренный дефект закрепить проверкой** в том же изменении: дефект без
   проверки возвращается.
5. **Обновить документы в том же изменении**, если правка меняет инвариант или
   число, записанное в документе: `AGENTS.md`, `docs/AGENTS-context.md`,
   `tools/Invoke-ProjectDoctrine.ps1`.

Типовые восстановления:

| Что сломано | Где взять | Как вернуть |
|---|---|---|
| Разделы `~\.pi\agent\AGENTS.md` §0–§11 | резервные копии рядом: 23 файла `AGENTS.md.bak-*`, самый свежий `AGENTS.md.bak-session5` | дописать **только утраченные разделы** в конец, не перезаписывая файл целиком |
| Линтер `~\.pi\agent\tools\Test-PwshApiVintage.ps1` | копии на машине нет | сообщить владельцу: это единственная точка без резерва, восстановлению из репозитория не подлежит |
| Навык `ragraf-core` | `docs\skills\ragraf-core\` (репозиторий) | скопировать в служебный каталог **каждой** учётной записи и сверить хеши |
| Файлы навыка в репозитории | `RAGRAF.git\RAGRAF` (ветка `main`) | сверить и, при необходимости, взять версию из коммита `6a62a07` |
| Правила рабочего каталога `AGENTS.md` | резервная копия `AGENTS.md.bak.20261004-203526-before-mysql` рядом | восстановить утраченный раздел, не перезаписывая файл |
| Ядро RAGRAF | `RAGRAF.git\RAGRAF` | сверить рабочее дерево с `main` и взять расходящийся файл из коммита |
| Индекс корпуса | — | `python tools/ragraf.py -e … reindex`; индекс производный, восстановление пересборкой |

**Про секретоносные пути.** В `AGENTS.md` проекта они перечислены по именам
(раздел 6), и среди них есть файлы с суффиксом резервной копии в каталоге
временных файлов. Правило то же: не открывать, не печатать, не копировать, не
добавлять в индекс. Отдельно: `~\.pi\agent\AGENTS.md` содержит живые реквизиты
стенда (§7.2). **Никогда не копировать этот файл в репозиторий и не добавлять его
в индекс любого корпуса** — он вне корпуса именно поэтому.

### Блок 8. Отчёт и откат

**Формат отчёта.**

1. Версия приложения до и после (`.startup-validation.json`), дата запуска.
2. Таблица по точкам 0.3: точка → эталон → факт → вердикт `OK` / `ИЗМЕНЕНО` /
   `НЕДОСТУПНО`. Вердикт «НЕДОСТУПНО» ставится там, где проверку запустить не
   удалось, с причиной.
3. Найденные дефекты: каждый — факт замера, решение, ссылка `файл:строка`.
4. Внесённые правки: файлы, что делает каждая, чем достаточна; затрагивает ли
   контракт, состояние, права.
5. Проверки после правок: команда → результат. Что не удалось запустить — прямо.
6. Ревизия индекса после работы, совпала ли контрольная сумма.
7. Откат: для всего, что касается состояния, схемы хранилища или нумерации
   ревизий — точная последовательность возврата.
8. Отдельный раздел «посторонние находки»: замеченный дефект вне задачи не
   правится молча, а называется.

**Если всё зелёное** — отчёт обязан сказать это числами: ревизия, сумма, хеши
файлов правил и навыка, вердикт чекера. Фраза «изменений не требуется» без чисел
отчётом не является.

---

## Чего делать не надо (сводка запретов)

- Не перезаписывать `~\.pi\agent\AGENTS.md` целиком и не копировать его в
  репозиторий или в индекс.
- Не править файлы настроек приложения, чтобы «дочинить» MCP.
- Не патчить бинарники AutoClaw.
- Не подавлять ошибку, чтобы она исчезла: `-ErrorAction SilentlyContinue` вокруг
  устаревшего обращения — скрытый дефект, а не исправление.
- Не выдавать `python -m pytest` за штатный путь и не считать `selftest` гейтом.
- Не удалять файлы владельца, даже если кажется, что новая структура их заменяет.
- Не оставлять висящие процессы `java.exe` и занятый порт 9500.
- Не считать оценку токенов измерением и не выдавать вывод по устаревшему
  индексу за актуальный.