brain/docs/adr/ADR-017-knowledge-graph-tooling.md

# ADR-017: Knowledge-graph tooling formalization (graphify)

- **Status:** Accepted
- **Date:** 2026-05-27
- **Deciders:** Дмитрий

## Context

Spike `spike/graphify-2026-05-27` (worktree `.claude/worktrees/graphify-spike`)
отработал три фазы построения knowledge-graph портала через инструмент
**graphify** (npm-обёртка `graphifyy`, бинарь `graphify.exe`, установлен через
`uv tool install graphifyy` v0.8.20+):

- **Phase 1** (docs/): 1352 узла / 1455 рёбер / 147 communities — 271 markdown
  файл, deep semantic extraction через Claude subagent dispatch (~2.4M tokens,
  275 messages из 5h-окна).
- **Phase 2** (.claude/): 1135 узлов / 1234 рёбер / 139 communities — 262 файла
  (66 code + 196 docs), deep semantic, ~2.0M tokens, 11 субагентов, retry
  потребовался после session-limit.
- **Phase 3** (app/): 3818 узлов / 4064 рёбер — 824 PHP/Vue/TS файла, pure AST
  extraction (БЕЗ субагентов, ~30 сек wall-clock, **0 LLM-токенов**).
- **Ultimate combined** (через `graphify merge-graphs`): **6305 узлов / 6753
  рёбер / 1009 communities**, 93% EXTRACTED / 7% INFERRED / 0% AMBIGUOUS.

Spike дал воспроизводимую методологию: subfolder + `graphify merge-graphs` —
безопасно строить фазами с откатом по бэкапам без потери прежних узлов.
Дополнительные узлы карты Лидерры — `lib/graph_node:*` для трёх фаз +
ultimate, провенанс-связки к источникам.

graphify — **off-phase инструмент** (не входит в фазовую раскладку #1-#29):
для knowledge-management проекта, а не для конкретной фазы разработки.
Параллельный ряду существующих off-phase подкатегорий (debug-runtime /
architecture-tooling / audit-security / project-management / design-tooling /
integration-tooling / ml-ai-tooling / business-process / discovery-tooling /
authoring-tooling / dev-support / finance-tooling / backend-tooling /
infosec-tooling / marketing-tooling), но граничит с context7 (#60),
Boost (#10), openapi-mcp-server (#47), Sentry MCP (#34) и adr-kit/mermaid
(#36/#37) по семантике; границы фиксируются в Decision ниже.

NB: параллельная сессия завершает раздел A10 BI-tooling
(`feat/a10-bi-tooling`, Tasks 1-4 из 19, 5 узлов #84-#88 — узлы агентов
nodes.yaml уже заняли #84/#85, BI на feature-branch без merge). Порядок
merge решит финальную нумерацию подкатегории (19-я или 20-я); счётчики
закрываются normative-sync агентом после merge.

Альтернативный backend Ollama — отдельный установленный для 152-ФЗ-чувствительных
задач инструмент; graphify его НЕ читает (graphify читает только `GEMINI_API_KEY`/
`GOOGLE_API_KEY` или fallback на Claude Code subagent dispatch).

## Decision

Graphify формализуется как узел **#86 graphifyy** в реестре Tooling Прил. Н
в новой **девятнадцатой off-phase подкатегории «knowledge-graph-tooling»**.

### Граничные правила (locked)

1. **graphify (#86) ↔ context7 (#60).** Разные слои документации:
   - **context7** — внешние библиотеки/SDK/фреймворки (актуальные docs от vendor).
     Первый выбор для «как использовать React/Laravel/Vue».
   - **graphify** — внутренний codebase + спеки + .claude/-артефакты Лидерры.
     Первый выбор для «как устроен наш модуль/где вызывается наша функция/
     связан ли наш скил X с агентом Y».
   Не дублируют. context7 ничего не знает про наш код; graphify ничего не знает
   про публичные SDK.

2. **graphify (#86) ↔ Laravel Boost (#10).** Разный grain:
   - **Boost** — MCP-сервер с Eloquent/DB/Laravel-docs query-апи (например, `php
     artisan tinker --execute`, query schema, search Laravel docs). Точечный
     ввод/вывод по конкретному запросу к app/.
   - **graphify** — статический knowledge graph через все слои (docs+config+code).
     Cross-layer навигация и «структурные карты», не runtime queries.
   Boost остаётся первым выбором для «выполни SQL» / «прочитай model» / «найди
   в Laravel-docs»; graphify — для «покажи связи между нашим спеком и кодом» /
   «какие концепты связаны с X».

3. **graphify (#86) ↔ openapi-mcp-server (#47).** Разный объект:
   - **openapi-mcp-server** — introspection одного OpenAPI-спека (`docs/api/
     openapi.yaml`), tools/resources MCP-сервера, READ-ONLY.
   - **graphify** — весь проект (docs+config+code), включая OpenAPI как часть
     более широкого графа.
   openapi-mcp-server остаётся первым выбором когда вопрос локализован в API-
     спеке («какие эндпоинты`?»); graphify — когда вопрос пересекает спек +
   реализацию + тесты + договорённости.

4. **graphify (#86) ↔ Sentry MCP (#34).** Разная плоскость:
   - **Sentry** — runtime ошибки (что упало в проде), READ-ONLY.
   - **graphify** — структурные отношения (как код связан), статика.
   Для post-mortem «упало X, что с чем связано» — Sentry находит X, graphify
   показывает blast radius.

5. **graphify (#86) ↔ adr-kit (#36) + mermaid-skill (#37).** Разная природа:
   - **adr-kit / mermaid** — manual authoring решений и диаграмм (декларативно
     заказчиком/Claude).
   - **graphify** — auto-discovery связей из исходников (deterministic AST + LLM
     semantic).
   Не пересекаются: ADR — нормативное решение; graphify-граф — наблюдаемая
   структура.

### Узел #86 graphifyy — атрибуты

- **Категория:** off-phase, knowledge-graph-tooling (19-я подкатегория).
- **Источник:** npm `graphifyy` v0.8.20+ (через `uv tool install graphifyy`),
  binary `graphify.exe`.
- **Установка:** `uv tool install graphifyy`; работает с user-level skill
  `~/.claude/skills/graphify/SKILL.md` (через `graphify install --platform
  claude`).
- **Активация:** explicit `/graphify <команда>`, не проактивно.
- **Артефакты:** `graphify-out/{graph.json,GRAPH_REPORT.md,graph.html,cache/}` в
  CWD откуда запущен. Должны быть **в `.gitignore`** (`graphify-out*/`), чтобы
  build-артефакты не попадали в diff/commit.
- **LLM-backend:** GEMINI_API_KEY/GOOGLE_API_KEY (если есть) или fallback на
  Claude Code subagent dispatch. **НЕ читает ANTHROPIC_API_KEY, OPENAI_API_KEY,
  Ollama API.**
- **Ollama compliance:** Ollama установлен в проекте для 152-ФЗ
  чувствительных задач (локальный LLM без отправки в Anthropic), но
  graphify Ollama НЕ использует — это два независимых инструмента.

### Стратегия обновлений (locked)

- **Manual update пока единственный безопасный режим:** `/graphify --update` (LLM
  для doc/MD-изменений; AST-only для code-изменений).
- **Auto-update post-commit hook отложен.** Spike-попытка 27.05 вечером:
  `graphify update .` от широкого scope разнесло граф 6305 → 41586 узлов (38 МБ
  bloat), потому что подхватил `tools/` + root-level .mjs + другое за пределами
  трёх фаз. **Откат через re-merge phase-бэкапов восстановил canonical
  6305/6753/1009.** Перед auto-update необходимо:
  - Спроектировать узкий scope или exclude-pattern (vendor/, tools/, node_modules/).
  - Узкий manifest, корректно покрывающий все 3 фазы.
  - Smoke-test перед wire-in lefthook.
  
  До этого момента — никакого автоматического обновления.

### Spike worktree → main стратегия

- Spike worktree (`spike/graphify-2026-05-27`) остаётся локально для повторяемых
  rebuild'ов через `subfolder + merge-graphs` методологию.
- На main commit'ятся: эта ADR-017, обновления нормативки (CLAUDE.md/Pravila/
  PSR_v1/Tooling/nodes.yaml/routing-off-phase.md), `.gitignore` add
  `graphify-out*/`. Phase 1+2+3 binaries (graph.json + ультимейт ~5MB) **не
  коммитятся** — пересобираются по запросу.
- Spec/plan на main (`docs/superpowers/specs/2026-05-27-graphify-spike-design.md`
  - `docs/superpowers/plans/2026-05-27-graphify-spike.md`) — untracked,
  требуют revision (Ollama assumption в исходной spec ошибочен). Можно
  обновить post-формализации либо drop.

## Consequences

**+** Knowledge-graph для всего портала Лидерры — формализованный инструмент
ответа на cross-layer вопросы («где наш скил X используется в коде / в каких
спеках упоминается агент Y / какие концепты связаны с биллингом»).

**+** Bридирует gap между документацией (docs/), конфигом (.claude/) и
реализацией (app/) — единый граф для onboarding и architectural reasoning.

**+** Subfolder + merge-graphs методология воспроизводима для дополнения
графа без потери прежних узлов; provenance к источникам сохраняется.

**+** Граничные правила фиксируют когда что использовать → нет дублирования с
context7/Boost/openapi/Sentry/adr-kit.

**–** Первичная сборка дорогая по subagent-токенам (Phase 1+2 = ~4.4M tokens).
Регенерация графа не должна быть рутинной операцией.

**–** Auto-update отложен → граф быстро устаревает между manual rebuild'ами.
До wire-in safety review — этот риск осознанный.

**–** Третий канал документации проекта (после CLAUDE.md/MEMORY.md и реестра
Tooling) — нагрузка на дисциплину обновлений.

**–** Размер canonical graph.json ~5 МБ — должен быть в `.gitignore`; иначе
diff'ы будут шумные.

## Compliance

- Узел #86 graphifyy в реестре Tooling Прил. Н, 19-я подкатегория
  knowledge-graph-tooling.
- CLAUDE.md §3.3 +строка #89; §0 cross-refs Pravila/PSR_v1/Tooling bumped; §6 +
  абзац о spike; §9 changelog entry.
- Pravila §13.2 +абзац «Off-phase knowledge-graph-tooling».
- PSR_v1 R10.1 Блок 1 note (graphifyy не UI → вне R6/R14); R15.6 +knowledge-
  graph-tooling в список off-phase подкатегорий.
- nodes.yaml: узел #86 graphifyy с subcategory `knowledge-graph-tooling`.
- routing-off-phase.md: trigger «knowledge graph / codebase structure / cross-
  layer concept query» → #86.
- spike worktree `.gitignore` update: `graphify-out*/`.

## Cross-refs

- Spike spec (untracked, revision pending): `docs/superpowers/specs/2026-05-27-
  graphify-spike-design.md`.
- Spike plan (untracked, revision pending): `docs/superpowers/plans/2026-05-27-
  graphify-spike.md`.
- Memory (user-local): `~/.claude/projects/.../memory/project_graphify_phase3_
  done.md` — runtime handoff state, инцидент с auto-hook + откат.
- Skill (user-level, через `graphify install --platform claude`):
  `~/.claude/skills/graphify/SKILL.md`.