claude-harness/skills/harness-doctor/SKILL.md

---
name: harness-doctor
description: Диагностика обвязки Claude Code (claude-harness) — когда хук сработал не так, codegraph пустой, агент пишет в main, тесты не видят ключ, обвязка «не подключена» или просто непонятно, что установлено. Запускает doctor.sh, читает отчёт по чеклисту, чинит то, что чинится безопасно, остальное формулирует как находку.
---

# harness-doctor

Один прогон → один отчёт → одинаковое прочтение агентом и человеком.

## Когда запускать
- Любой симптом про обвязку: «хук отбрил/пропустил», «codegraph возвращает пусто», «agent запушил в main», «SessionStart ругается», «tea не отвечает», «тесты делают платные запросы».
- Перед первой фичей в новом или только что подключённом проекте.
- По просьбе пользователя «продиагностируй обвязку» / «doctor».

## Как
1. `bash ~/.claude/skills/harness-doctor/scripts/doctor.sh [папка проекта]` — только чтение, ничего не меняет. Отчёт целиком показать пользователю без сокращений.
2. Прочитать по чеклисту ниже. Каждую строку `MISS`/`WARN` либо починить (если в списке «чинится само»), либо назвать находкой с маркером `O-n` и предложить действие.
3. Если отчёт нужен человеку вне Claude Code — он вставляет его как есть; тот же чеклист.

## Чеклист прочтения

**Машина**
- `MISS` бинарник → установить (`npm i -g @fission-ai/openspec @colbymchenry/codegraph`, `brew install tea`); не обходить, обвязка без него неполная. Формулы `codegraph` в brew нет.
- После установки `codegraph` подключить MCP: `claude mcp add-json -s user codegraph '{"type":"stdio","command":"codegraph","args":["serve","--mcp"],"alwaysLoad":true}'`, перезапустить сессию, в проекте — `codegraph init`. Не `codegraph install`: он дописывает секцию в `~/.claude/CLAUDE.md`, `install.sh` её сотрёт, а файл выйдет за 3 КБ.
- `MISS plugin superpowers` → `/plugin install superpowers@claude-plugins-official`. `WARN plugin beads/template-bridge` → удалить, конфликтуют со skills superpowers.
- `MISS`/`WARN hook …` → `bash <пакет>/install.sh`; «не зарегистрирован» — settings.json правился руками, тот же install.sh сольёт заново.
- `WARN в окружении есть *_API_KEY` → ключ виден всем сабагентам и делает интеграционные тесты платными при каждом `npm test`. Убрать из профиля shell, передавать только в строке запуска. Это находка для пользователя, агент сам профиль не правит.
- Глобальный CLAUDE.md без «маркировка: да» или «projectPath: да» → старая версия, `install.sh`.
- `MISS roles/<r>.md`, `MISS skill role`, `MISS agent briefing`, `MISS link-roles.sh` → `bash <пакет>/install.sh` (версия ≥ 0.3.0).
- `WARN глобальный CLAUDE.md > 3 КБ` → в `~/.claude/CLAUDE.md` дописано лишнее; процесс роли живёт в `~/.claude/roles/<r>.md`, перенести туда.

**Самотест хуков** — любое `WARN … (ожидалось N)` означает, что хук установлен, но не делает того, что должен. Причины по убыванию частоты: правлен руками; `python3` не в PATH сессии; settings.json зовёт другой путь. Чинится `install.sh`; если и после него WARN — приложить строку к находке, это дефект пакета.

**Корпус хуков** — `ok корпус хуков: N/N`: установленные хуки дают на реальных командах пилота те же вердикты, что размечены. `WARN корпус хуков: N/M` и строки над ним — расхождения: `id`, класс, ожидалось, получено, команда. После `install.sh` расхождение — регрессия пакета; разобрать одну команду: `python3 ~/.claude/hooks/harness_target.py targets '<команда>' <cwd>`. `MISS корпус хуков` — нет `harness_target.py` или раннера, чинится `install.sh`.

**Проект**
- `MISS CLAUDE.md`/`openspec/`/`.codegraph/` или `WARN без секции` → обвязка не подключена: `bash ~/.claude/harness/adopt-project.sh <root>` (сам делает ветку и ff-merge; дерево должно быть чистым).
- «worktree; основной: …» + «MCP смотрит на индекс основного checkout» → в вызовах `codegraph_explore` передавать `projectPath=<root worktree>`; если индекса в worktree нет — `codegraph init` там.
- «ветка: detached» → не работать, вернуться на ветку; guard-main блокирует detached HEAD намеренно.
- «чистое дерево: НЕТ» в основном checkout при закрытии → `git pull --ff-only` не делать, перечислить файлы пользователю.
- «планы: 0» и нет `.bounded` при правке кода → require-plan заблокирует; это не ошибка хука, нужен brainstorming или `.bounded`.
- «code-paths: умолчание» при коде вне `src/` → создать `.claude/code-paths`.
- «SDD workspace: …» при отсутствии активной фичи → хвост незакрытой фичи; проверить чеклист закрытия.
- `WARN .bounded не в .gitignore` → добавить строку, иначе уедет в main.
- `WARN нет allow-правила для git push origin --delete` → находка владельцу: готовую строку из WARN он сам добавляет в `.claude/settings.json` проекта (решение владельца 2, чеклист закрытия п. 4); агент `settings.json` не правит. `ok allow …` называет файл, где правило найдено: проектный `settings.json`, `settings.local.json` или глобальный.
- `WARN tea не отвечает` → `tea logins list`; токен нужен со scopes read:user, write:repository, write:issue.
- «workspace (не git)» → режим нескольких репозиториев. `WARN … битая ссылка` → репозиторий направления переименован или файл удалён: `bash ~/.claude/harness/link-roles.sh <workspace>`. `WARN нет <dir>/.claude/roles/<r>.md` → создать проектный файл роли из `~/.claude/harness/project-template/role-repo/ROLE.md`.
- `WARN индекс auto-memory > 3 КБ` → индекс снова стал журналом состояния; свернуть закрытое в `registry-closed.md`, уроки — в `notes/` направления (политика памяти в глобальном CLAUDE.md).

## Чинится само (без вопроса)
`install.sh`, `link-roles.sh` в workspace, `codegraph init` в worktree, `.claude/code-paths`, строка в `.gitignore` на ветке. Всё остальное — находка пользователю: профиль shell, плагины, токены, удаление чего-либо.

## Чего не делать
Не «улучшать» хуки по месту: их источник — пакет claude-harness, правка идёт туда и ставится install.sh. Не отключать хук ради того, чтобы «прошло».