portal/docs/superpowers/specs/2026-05-17-a3-integration-tooling-design.md

A3 Integration-Tooling — дизайн интеграции

Дата: 2026-05-17 Раздел карты: A3 «Программирование — интеграции (API, вебхуки)» Параллель: A6 architecture-tooling (17.05.2026), D3 audit-security (17.05.2026) Ветка: feat/a3-integration-tooling (rebased на origin/main 1313d89, CLAUDE.md v2.8)

1. Проблема

Раздел A3 карты docs/automation-graph.html пуст — 0 узлов в NODE_SECTION (строки 1868-1911, ни одного значения 'A3'). Интеграционная работа физически идёт — REST-эндпоинты (deals/lookup/billing/admin), webhook-приём (HMAC + per-token rate-limit), ~5 внешних API (Unisender Go / Yandex Cloud / Yandex 360 / JivoSite / Sentry) — но инструментами разделов A1/A5/A7/A8/E7. Ни один инструмент не классифицирован как A3. Состояние — как у A6 до 17.05. (строки 1868-1911 в оригинальном форке — после ребейза локализовать Grep'ом по 'A3' в NODE_SECTION).

2. Цель и scope

Наполнить раздел A3 карты — параллельно A6/D3.

Scope = формализация инструментов, не их применение. A6-прецедент: поставил adr-kit, но не аудировал весь код; создал ADR-000/001/002 + одну C4-диаграмму как smoke.

Вне scope: полная OpenAPI-спека REST API проекта; рефактор webhook-кода; mock-инфраструктура внешних API в тестах (Microcks отклонён — требует Docker/JVM+Mongo, несовместим с native-Windows-no-Docker стеком проекта).

3. Состав узлов A3 (7)

3.1. Новые узлы карты (2)

Узел (id карты)	Что	Установка	Tooling-реестр
api-docs agent (ag_apidocs, claude-flow)	генерация OpenAPI-спеки REST API, pattern learning	0 — агент уже доступен в сессии	нет номера — claude-flow sub-агент; реестр Прил. Н — plugin-grain (как 11 уже существующих agent-узлов карты, ни один не имеет Tooling-номера)
openapi-mcp-server (mcp_openapi, npm, stdio MCP)	отдаёт OpenAPI-спеку как MCP-ресурс/тулы; introspection своей и чужих API	npm i + запись в .mcp.json	#47, Tooling §4.22

3.2. Кросс-реф вторичным тегом A3 (5 — первично остаются в своих разделах)

Узел	Первичный раздел	Роль в A3
context7	E7	актуальная дока внешних API при интеграции
mcp_boost / Boost #10	A1	серверные REST-эндпоинты, HTTP-клиент, Sanctum-auth
ag_pest / Pest 4 #18	A5	contract/integration-тесты эндпоинтов и вебхук-приёма
mcp_semgrep / Semgrep #25	A8	безопасность интеграций (hardcoded webhook URL, API-key leak)
mcp_sentry / Sentry MCP #34	A7	runtime-ошибки вебхук-хендлеров и внешних вызовов

4. Правка модели карты (docs/automation-graph.html)

Развилка: NODE_SECTION строго 1:1 (узел → один раздел), кросс-реф 5 существующих узлов в A3 механически невозможен. Решение — аддитивный слой:

• Новый объект NODE_SECTION_SECONDARY (NODE_SECTION 1:1 не трогается):

  const NODE_SECTION_SECONDARY = {
    mcp_boost: ['A3'], context7: ['A3'], ag_pest: ['A3'],
    mcp_semgrep: ['A3'], mcp_sentry: ['A3'],
  };
  

• Цикл SECTION_NODES (строка ~1915): узел добавляется в первичный раздел И в каждый раздел из NODE_SECTION_SECONDARY.

• Панель «Разделы» — узел показывается под всеми своими разделами.

• Паспорт узла, строка «Раздел» (#ld-section, строка 147): формат A1 (+A3) для кросс-реф узлов.

• 2 новых объекта NODES: ag_apidocs (group agents), mcp_openapi (group mcp) + позиционирование pos().

• NODE_SECTION: ag_apidocs: 'A3', mcp_openapi: 'A3' (первичный раздел).

• NODE_TIMELINE: ag_apidocs / mcp_openapi — since: '17.05.2026'.

• Рёбра (~2-3): новые узлы → governing-правила, напр. E('psr_v1', 'mcp_openapi', 'R10.1 блок 3:\nintegration-tooling').

• Счётчики: 116→118 узлов, +3 ребра. Новых конфликтов не ожидается.

5. Нормативка (4 файла — как A6/D3)

Файл	Правка	Версия
Tooling Прил. Н	§4.22 (новый) — #47 openapi-mcp-server; §0 счётчик 46→47; 9-я off-phase подкатегория integration-tooling	v2.8→v2.9
PSR_v1	R10.1 Блок 3 (MCP-серверы) +1 строка openapi-mcp; integration-tooling — не UI → вне R6/R14	v3.8→v3.9
Pravila	§13.2 +абзац «Off-phase integration-tooling»	v1.22→v1.23
CLAUDE.md	§3 title 46→47; §3.3 +строка #47 (+упоминание api-docs agent); §1 row 2b 46→47; §3.3 footer; §0 cross-refs; §6 +абзац A3	v2.8→v2.9

CLAUDE.md — через /claude-md-management:claude-md-improver (§5 п.10). Кросс-реф 5 существующих инструментов — только map-модель; в нормативный реестр не попадает (инструменты уже зарегистрированы по своей идентичности).

6. Smoke / верификация

• Аудит установки openapi-mcp: точное имя npm-пакета (кандидат ivo-toby/mcp-openapi-server), native-Windows совместимость, stdio-режим (без port-conflict), кириллица в пути (квирк #26).
• Smoke: openapi-mcp поднят на тестовой спеке (PONG-эквивалент) + dispatch api-docs agent на одну группу эндпоинтов (deals API) → стартовый OpenAPI-скелет как proof. Полную спеку не генерируем.
• Регрессия quick (lint/format/type-check) перед коммитом нормативки.
• Визуальный smoke карты: открыть automation-graph.html — 118 узлов, 0 JS-ошибок, панель «Разделы» показывает A3 с 7 узлами.
• git без bypass хуков.

7. Нумерация (риск реализовался — закрыт)

Ветка feat/a3-integration-tooling исходно форкнулась от D3-эры (7c12b74). За это время в origin/main влиты C9 (#41 CCPM / #42 product-management), deptrac (#43), A4 (#44/#45/#46). Риск из исходной редакции §7 материализовался. Закрыт ребейзом feat/a3 на актуальный origin/main 1313d89: openapi-mcp-server подтверждён как #47, Tooling §4.22, integration-tooling — 9-я off-phase подкатегория. Остаточный риск: если ещё одна интеграция (напр. A11) смёрджится в main раньше A3 — финально сверить счётчик Tooling §0 перед коммитом нормативки (план Task 10 Step 2).

8. Ветка и артефакты

• Ветка feat/a3-integration-tooling rebased на origin/main 1313d89.
• Spec: этот файл.
• План: docs/superpowers/plans/2026-05-17-a3-integration-tooling-integration.md.
• Merge: git push origin feat/a3-integration-tooling:main после D3 (ветка A3 содержит D3-коммиты как предков — корректный порядок merge).