# ADR-019: Off-phase research-tooling (Perplexity Pack)

**Status:** Accepted
**Date:** 2026-06-14
**Контекст:** эпик «Perplexity Pack», spec `docs/superpowers/specs/2026-06-14-perplexity-pack-research-tooling-design-v3.md`, провенанс-вет `docs/research/research-vet.md`.

## Context

В тулчейне Лидерры не было выделенного слоя веб-разведки. Существующие узлы дают
знания узких типов: `context7` (#60) — документация библиотек/SDK; `openapi`-mcp (#47)
— интроспекция нашего REST-API; `Laravel Boost` (#10) — Laravel-экосистема и runtime-запросы;
`Sentry`/`Redis` MCP (#34/#35) — runtime-факты прод-системы; `graphify` (#86) — внутренний
граф проекта; `GitHub` MCP (#3) — операции с репозиторием. Ни один не покрывает **открытый
веб**: актуальные практики, нормативные требования, фич-разведку конкурентов, deep-research
с цитатами.

Три зрелых MCP-сервера закрывают этот пробел: **perplexity** (ранжированный ответ-с-источниками поверх sonar), **exa** (нейро/семантическое обнаружение источников), **firecrawl** (глубокое чтение и обход страниц). Все три присутствовали только в ветке `worktree-perplexity-pack`;
main и нормативка их не знали.

Аналогичный паттерн «новый off-phase слой» закрывался ранее: A8 infosec (ADR-014), C1
marketing (ADR-015), knowledge-graph (ADR-017). Дисциплина та же: провенанс-вет IS9 →
перенос конфигурации в main → формализация в нормативке → реестр узлов.

**Риск ecosystem.** Все три — внешние пакеты с платными API-ключами. Snyk/SentinelOne
«ToxicSkills» 2025: ≈13% маркетплейс-артефактов содержат критичные дефекты. Провенанс-гейт
IS9 (прецедент A8/C1) обязателен ДО формализации; вет завершён — `docs/research/research-vet.md`,
все три **ПРИНЯТ**.

**Решение заказчика (зафиксировано):** платные API приняты владельцем (owner waiver,
Вариант 2); ключи (`PERPLEXITY_API_KEY` / `EXA_API_KEY` / `FIRECRAWL_API_KEY`) живут только
в пользовательском окружении, никогда в репозитории.

## Decision

Принят слой **research-tooling** — новая **20-я off-phase подкатегория**, номера Tooling
**#87–#89**, классификация роутера `research`.

| # | Узел | Источник | Тип | Назначение |
|---|---|---|---|---|
| 87 | perplexity MCP | `@perplexity-ai/mcp-server` | внешний MCP, READ-ONLY | ранжированный ответ-с-источниками (search/ask/research/reason; sonar) |
| 88 | exa MCP | `exa-mcp-server` (exa-labs) | внешний MCP, READ-ONLY | семантическое/нейро обнаружение источников (web_search_exa/web_fetch_exa) |
| 89 | firecrawl MCP | `firecrawl-mcp` (Firecrawl/Mendable) | внешний MCP, READ-ONLY (read-тяжёлый) | глубокое чтение и обход (scrape/batch/map/search/crawl/extract + agent) |

**Детали решений:**

1. **#87 perplexity** — первичный «дай ответ-с-источниками». Четыре инструмента поверх
   sonar-моделей: `perplexity_search` (ранжированный web), `perplexity_ask` (sonar-pro
   real-time), `perplexity_research` (sonar-deep-research, медленный 30s+), `perplexity_reason`
   (sonar-reasoning-pro). READ-ONLY. Базовый URL через AITUNNEL-прокси (`PERPLEXITY_BASE_URL`).
2. **#88 exa** — обнаружение того, что keyword-поиск пропускает: семантический `web_search_exa` плюс `web_fetch_exa`. READ-ONLY.
3. **#89 firecrawl** — прочитать страницу целиком/обойти сайт/извлечь структурированное;
   `firecrawl_agent` — автономный web-research. READ-ONLY (read-тяжёлый режим).

**Gate-постура (реализована, commit `bfc1f575`):** все инструменты трёх серверов
(`mcp__perplexity__*` / `mcp__exa__*` / `mcp__firecrawl__*`) классифицированы как **read_only**
в `tools/mcp-tool-classifier.mjs` (+тест). Это не намерение, а зафиксированный факт: router-gate
пускает их без approve, мутаций они не несут.

## Boundaries (конфликт-аудит)

- **RT1 — ↔ context7 (#60):** разные слои знаний. context7 = документация библиотек/SDK
  (vendor docs известного пакета); research-tooling = открытый веб — практики, нормы,
  конкуренты, новости. context7 первый для «как настроить пакет X»; research для «что
  индустрия делает с Y».
- **RT2 — ↔ openapi-mcp (#47):** разный объект. openapi = наш REST-спек (introspection
  endpoints/схем); research = внешние источники в вебе.
- **RT3 — ↔ Laravel Boost (#10):** разный масштаб. Boost = Laravel-экосистема и runtime-запросы
  в app/; research = веб вне проекта.
- **RT4 — ↔ Sentry (#34) / Redis (#35):** разная плоскость. Sentry/Redis = runtime-факты
  прод-системы (ошибки/очереди/кэш); research = внешние знания.
- **RT5 — ↔ graphify (#86):** направление. graphify = внутренний граф проекта (наружу не
  ходит); research = наружу, в открытый веб. Post-mortem: graphify даёт blast radius внутри,
  research приносит внешний контекст.
- **RT6 — ↔ GitHub MCP (#3):** разный канал. GitHub = операции с репозиторием/issues/PR;
  research = открытый веб.
- **RT7 — внутренние слои (anti-overlap внутри пака):** хотя все три «ищут в вебе», роли
  не пересекаются. **perplexity** = ранжированный ответ-с-источниками; **exa** = семантическое
  обнаружение источников по смыслу; **firecrawl** = глубокое чтение/обход конкретных страниц.
  Канонический порядок — связка L17: perplexity (ответ) → exa (обнаружение) → firecrawl
  (глубокое чтение).
- **RT8 — платные API + запрет авто-трат:** все три держат платные ключи (прецедент MKT8
  / READ-ONLY Sentry/Redis). Ключи только в пользовательском окружении; без авто-расхода
  без нужды; gitleaks стережёт утечку в репозиторий.
- **RT9 — классификация `research` ≠ analysis/knowledge_graph_query/planning:** `research`
  = разведка широты во внешнем вебе на крупных/абстрактных задачах. Не перехватывает
  `analysis` (статанализ кода — Semgrep/ToB), `knowledge_graph_query` (внутренний граф —
  graphify), `planning` (Superpowers/CCPM). Разграничение — триггер-ключевые слова +
  настоящий ADR.

## Alternatives Considered

- **Только WebSearch/WebFetch (встроенные)** — отклонено: дают сырой список/одну страницу,
  без ранжированного ответа-с-источниками, без семантического обнаружения, без глубокого
  обхода. research-tooling — качественный апгрейд.
- **Один сервер вместо трёх** — отклонено: роли не дублируются (RT7); ответ ≠ обнаружение ≠
  глубокое чтение. Один сервер не закрывает все три потребности.
- **DEFERRED до Б-1** — отклонено: владелец принял платные API сейчас (owner waiver);
  слой полезен немедленно для разведки практик/норм при проектировании.

## Consequences

**Positive:**

- Закрыт пробел «открытый веб»: 0 → 3 узла research-разведки.
- Новая **20-я off-phase подкатегория research-tooling**; номера #87–#89.
- Связка **L17** research chain (`brainstorming` → perplexity → exa → firecrawl) в
  routing-off-phase.md (canonical chain).
- Провенанс-вет IS9 всех трёх пройден ДО формализации — ни одного FAIL.
- Gate-постура read_only зафиксирована в коде (не декларация): мутаций нет.

**Neutral / Cautionary:**

- Платные API: расход контролируется дисциплиной (без авто-вызовов без нужды); ключи в env.
- Bulk-load MCP-инструментов исторически ронял субагентов API-ошибкой; +3 сервера
  увеличивают суммарное число инструментов — митигация через deferred-tools (схемы по запросу),
  риск помечен в дом-README раздела.
- `perplexity_research` медленный (30s+) — для глубоких задач, не для быстрых вопросов.

## Related Decisions

- **ADR-014** — A8 infosec-tooling; IS9-провенанс-дисциплина, прецедент платных/внешних.
- **ADR-015** — C1 marketing-tooling; паттерн «пустой/новый слой → наполнение», MKT8
  (READ-ONLY + запрет авто-трат) — прямой предок RT8.
- **ADR-017** — knowledge-graph-tooling; граница «внутрь vs наружу» (graphify ↔ research, RT5).

## Enforcement

Граница research-tooling против смежных узлов (RT1–RT9) проверяется при маршрутизации: задача
«открытый веб / практики / нормы / конкуренты» → research-узлы (#87–#89); задача «документация
библиотеки» → context7 (#60); «наш API» → openapi (#47); «внутренний граф» → graphify (#86);
«runtime прод» → Sentry/Redis (#34/#35). Read-only-постура трёх серверов закреплена в
`tools/mcp-tool-classifier.mjs` (+тест в `tools/mcp-tool-classifier.test.mjs`) — router-gate
пускает их без approve и блокирует любую не-read_only попытку по умолчанию. Ключи API только
в пользовательском окружении; gitleaks (pre-commit/pre-push) блокирует утечку в репозиторий.
Узлы #87–#89 живут в `docs/registry/nodes.yaml` (`subcategory: research-tooling`,
`triggers.classification: research`); инвариант покрытия карточками (Машина 3-E) требует
контракт-карточку на каждый узел (`docs/registry/contracts/{perplexity,exa,firecrawl}-mcp.contract.json`).

## References

- `docs/superpowers/specs/2026-06-14-perplexity-pack-research-tooling-design-v3.md` — design (D1–D9).
- `docs/research/research-vet.md` — IS9 провенанс-вет (#87/#88/#89, все ПРИНЯТ).
- `docs/research/README.md` — дом раздела research-tooling.
- `docs/Tooling_v8_3.md` §4.60–§4.62 — 9-атрибутные блоки узлов #87–#89.
- `docs/Plugin_stack_rules_v1.md` R10.1 Блок 3 + R15.6 — реестр ролей MCP-серверов.
- `docs/Pravila_raboty_Claude_v1_1.md` §13.2 — Off-phase research-tooling абзац.
- `docs/routing-off-phase.md` — связка L17 (research chain) + routing #87–#89.
- `.mcp.json` — три блока mcpServers (perplexity/exa/firecrawl); commit `bfc1f575` (gate read_only).