# A3 Integration-Tooling Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Наполнить пустой раздел A3 «Программирование — интеграции (API, вебхуки)» карты `automation-graph.html` — формализовать 2 новых интеграционных инструмента + кросс-реф 5 существующих, синхронизировать 4 нормативных файла.

**Architecture:** Параллельно A6/D3. Новый аддитивный слой `NODE_SECTION_SECONDARY` в карте (`NODE_SECTION` 1:1 не трогается) даёт кросс-реф существующих узлов в A3. `openapi-mcp-server` — реальная установка (`.mcp.json`), `api-docs` agent — 0-install (claude-flow). Нормативка — A6/D3-паттерн (Tooling §4.22 + PSR_v1 R10.1 + Pravila §13.2 + CLAUDE.md через `claude-md-improver`).

**Tech Stack:** `automation-graph.html` (vis.js, vanilla JS), `.mcp.json` (stdio MCP), Markdown (Tooling/PSR_v1/Pravila/CLAUDE.md), claude-flow `api-docs` agent, npm/npx.

**Спецификация:** [docs/superpowers/specs/2026-05-17-a3-integration-tooling-design.md](../specs/2026-05-17-a3-integration-tooling-design.md)

---

## Verification Approach

Интеграция — **документация + конфиг + vis.js-карта**, прикладного кода (Laravel/Vue) не трогает → unit-TDD-поверхности нет (как у A6/D3). Верификация по задачам:

- lefthook pre-commit (gitleaks / markdownlint / cspell / adr-judge) — на каждом коммите;
- MCP-smoke — `openapi-mcp-server` поднимается в stdio;
- визуальный smoke карты — 118 узлов, 0 JS-ошибок в консоли, панель «Разделы» показывает A3;
- регрессия `quick` (lint/format/type-check) — перед финальным коммитом нормативки.

Если cspell блокирует новый валидный термин — добавить в `cspell-words.txt` (в том же коммите).

**Изоляция:** работа в worktree `.claude/worktrees/a3-integration-tooling` (ветка `feat/a3-integration-tooling`). В native-worktree `lefthook` может быть не в PATH (квирк #97) → pre-commit хуки молча пропускаются; cspell/gitleaks гонять вручную перед коммитом/push.

---

## File Structure

- Create: `docs/api/openapi.yaml` — стартовый OpenAPI-скелет (smoke, deals API)
- Modify: `.mcp.json` — +`openapi` server entry
- Modify: `docs/automation-graph.html` — `NODE_SECTION_SECONDARY` слой + 2 узла + рендер
- Modify: `docs/Tooling_v8_3.md` — §4.22 + §0 счётчик, v2.8→v2.9
- Modify: `docs/Plugin_stack_rules_v1.md` — R10.1 Блок 3, v3.8→v3.9
- Modify: `docs/Pravila_raboty_Claude_v1_1.md` — §13.2, v1.22→v1.23
- Modify: `CLAUDE.md` — через `/claude-md-management:claude-md-improver`, v2.8→v2.9
- Modify: `cspell-words.txt` — новые термины по мере надобности
- Modify: `memory/project_automation_map.md`, `memory/reference_archive.md` — после push

---

## Task 1: OpenAPI-скелет через api-docs agent (smoke)

**Files:**

- Create: `docs/api/openapi.yaml`
- Read (контекст для агента): `app/routes/api.php`, `app/app/Http/Controllers/` (deals-контроллеры)

- [ ] **Step 1: Найти роуты deals API**

Run: `Grep` по `app/routes/api.php` паттерн `deals` (output_mode content). Зафиксировать список эндпоинтов `/api/deals*` (index/show/store/update/transition/destroy/restore/export).

- [ ] **Step 2: Dispatch api-docs agent**

Через `Agent` tool, `subagent_type: api-docs`, model `sonnet` (механическая генерация). Промпт: «Сгенерируй OpenAPI 3.1 скелет ТОЛЬКО для группы эндпоинтов `/api/deals*` проекта Лидерра (Laravel 13). Источник — `app/routes/api.php` + контроллеры. Только paths + базовые request/response shapes, без полной схемы компонентов. Результат — валидный YAML, верни raw-текст файла.»

- [ ] **Step 3: Записать результат**

Записать вывод агента в `docs/api/openapi.yaml`. В шапку добавить комментарий:

```yaml
# Стартовый OpenAPI-скелет (smoke A3-интеграции, 2026-05-17).
# Покрывает только группу /api/deals*. Полная спека REST API — отдельная задача вне scope A3.
```

- [ ] **Step 4: Валидировать YAML**

Run: `npx --yes @redocly/cli@latest lint docs/api/openapi.yaml` (или `npx --yes @stoplight/spectral-cli lint`).
Expected: парсится без fatal-ошибок (warning'и о неполноте допустимы — это скелет).
Если CLI недоступен — минимум: `node -e "require('js-yaml').load(require('fs').readFileSync('docs/api/openapi.yaml','utf8'))"` → без исключения.

- [ ] **Step 5: Commit**

```bash
git add docs/api/openapi.yaml
git commit -m "docs(a3): OpenAPI skeleton for /api/deals — A3 smoke artifact"
```

Если cspell блокирует — добавить термины (`openapi`, `redocly`, `spectral` и т.п.) в `cspell-words.txt`, `git add` его, повторить коммит.

---

## Task 2: Установить и сконфигурировать openapi-mcp-server

**Files:**

- Modify: `.mcp.json` (корень репозитория)

- [ ] **Step 1: Определить точное имя npm-пакета**

Run: `npm view @ivotoby/openapi-mcp-server version` — основной кандидат (GitHub `ivo-toby/mcp-openapi-server`).
Fallback при ошибке: `npm view openapi-mcp-server version`, затем `npm view mcp-openapi-server version`.
Зафиксировать имя пакета с непустой версией и репозиторием `ivo-toby/mcp-openapi-server`. Обозначить как `<PKG>`.

- [ ] **Step 2: Прочитать текущий `.mcp.json`**

Run: `Read` по `.mcp.json`. Зафиксировать формат существующих stdio-серверов (`redis`, `sentry`) — `command` / `args` / `env`.

- [ ] **Step 3: Добавить server-блок `openapi`**

В объект `mcpServers` добавить рядом с `redis`/`sentry` (stdio, через `npx`, без глобальной установки — как redis MCP):

```json
"openapi": {
  "command": "npx",
  "args": ["-y", "<PKG>"],
  "env": {
    "API_BASE_URL": "http://localhost",
    "OPENAPI_SPEC_PATH": "./docs/api/openapi.yaml"
  }
}
```

Точные имена env-переменных свериться с README пакета (Step 1 дал репозиторий) — `API_BASE_URL` / `OPENAPI_SPEC_PATH` либо CLI-флаги `--api-base-url` / `--openapi-spec`. Использовать тот вариант, что в README пакета.

- [ ] **Step 4: Smoke — сервер поднимается**

Run: `npx -y <PKG> --help` (проверка, что пакет ставится и запускается на native-Windows).
Expected: печатает usage без краша. Если падает (native-Windows несовместимость / кириллица в пути, квирк #26) — **fallback:** оставить server-блок в `.mcp.json` закомментированным-эквивалентом не выйдет (JSON не поддерживает комментарии) → задокументировать в Tooling §4.22 статус «pending: native-Windows install не верифицирован» (прецедент — Sentry MCP «pending Б-1»), узел карты остаётся. Зафиксировать факт в коммите Step 5.

- [ ] **Step 5: Commit**

```bash
git add .mcp.json
git commit -m "feat(a3): register openapi-mcp-server in .mcp.json"
```

---

## Task 3: Карта — слой NODE_SECTION_SECONDARY + интеграция в рендер

**Files:**

- Modify: `docs/automation-graph.html` (3 точки: после `NODE_SECTION`, build `SECTION_NODES`, `ld-section` в Паспорте, `showSectionsLegend`)

- [ ] **Step 1: Добавить объект `NODE_SECTION_SECONDARY`**

После закрывающей `};` объекта `NODE_SECTION` (локализовать Grep'ом: закрывающая `};` объекта `NODE_SECTION` перед `const SECTION_BY_ID`) вставить:

```js
// Вторичная классификация: узел первично в NODE_SECTION, дополнительно — в этих
// разделах (кросс-реф). Введено A3-интеграцией 17.05.2026 — раздел A3 наполняется
// частично кросс-реф существующих интеграционных инструментов. NODE_SECTION 1:1 не трогается.
const NODE_SECTION_SECONDARY = {
  mcp_boost:   ['A3'],
  context7:    ['A3'],
  ag_pest:     ['A3'],
  mcp_semgrep: ['A3'],
  mcp_sentry:  ['A3'],
};
```

- [ ] **Step 2: Модифицировать build `SECTION_NODES`**

Текущий код (локализовать Grep'ом `const SECTION_NODES = new Map`):

```js
const SECTION_NODES = new Map(SECTIONS.map(s => [s.id, []]));
NODES.forEach(n => {
  const sid = NODE_SECTION[n.id];
  if (sid && SECTION_NODES.has(sid)) SECTION_NODES.get(sid).push(n.id);
});
```

Заменить на:

```js
const SECTION_NODES = new Map(SECTIONS.map(s => [s.id, []]));
NODES.forEach(n => {
  const sid = NODE_SECTION[n.id];
  if (sid && SECTION_NODES.has(sid)) SECTION_NODES.get(sid).push(n.id);
  (NODE_SECTION_SECONDARY[n.id] || []).forEach(secId => {
    if (SECTION_NODES.has(secId)) SECTION_NODES.get(secId).push(n.id);
  });
});
```

- [ ] **Step 3: Модифицировать строку «Раздел» Паспорта**

Текущий код (локализовать Grep'ом `ld-section` в `showNodeLegend`):

```js
  const _sec = NODE_SECTION[nodeId] ? SECTION_BY_ID.get(NODE_SECTION[nodeId]) : null;
  document.getElementById('ld-section').textContent = _sec ? `${_sec.id} · ${_sec.label}` : '—';
```

Заменить на:

```js
  const _sec = NODE_SECTION[nodeId] ? SECTION_BY_ID.get(NODE_SECTION[nodeId]) : null;
  const _secExtra = (NODE_SECTION_SECONDARY[nodeId] || [])
    .map(id => SECTION_BY_ID.get(id)).filter(Boolean);
  let _secText = _sec ? `${_sec.id} · ${_sec.label}` : '—';
  if (_secExtra.length) _secText += ` (+${_secExtra.map(s => s.id).join(', ')})`;
  document.getElementById('ld-section').textContent = _secText;
```

- [ ] **Step 4: Проверить, что счётчик в `showSectionsLegend` уже корректен**

(Локализовать Grep'ом `nodeIds.length` в `showSectionsLegend`): `nodeIds.length` берётся из `SECTION_NODES.get(sec.id)` — после Step 2 счётчик автоматически учитывает кросс-реф. Правок не требуется. Зафиксировать факт (no-op проверка).

- [ ] **Step 5: Визуальный smoke (промежуточный)**

Открыть `docs/automation-graph.html` через Playwright MCP (`browser_navigate` file:// — квирк #90: file:// отвергается → использовать локальный сервер `npx -y serve docs -l 8123` + `browser_navigate http://localhost:8123/automation-graph.html`). Нажать «📂 Разделы». Раздел A3 пока показывает 5 узлов (context7/Boost/Pest/Semgrep/Sentry) — новых узлов ещё нет. Консоль (`browser_console_messages`) — 0 ошибок.

- [ ] **Step 6: Commit**

```bash
git add docs/automation-graph.html
git commit -m "feat(map): NODE_SECTION_SECONDARY layer — cross-ref nodes into A3"
```

---

## Task 4: Карта — 2 новых узла A3

**Files:**

- Modify: `docs/automation-graph.html` (5 точек: `NODES`, `NODE_SECTION`, `NODE_DETAILS` блок `nd()`, `NODE_TIMELINE`, `EDGES`, комментарий-счётчик)

- [ ] **Step 1: Добавить узел `ag_apidocs` в `NODES`**

В секции агентов (после `ag_rls`, формат-образец `ag_pest` — Grep `id: 'ag_pest'` — `group: 'agents'`, `ring: 4`) вставить:

```js
  // A3 integration-tooling (17.05.2026) — agent раздела «Программирование — интеграции»
  { id: 'ag_apidocs',  label: 'api-docs (agent)',     group: 'agents', size: 18, ring: 4, ...pos(4, 85)  },
```

`pos(4, 85)` — свободный угол между `ag_guide` (`pos(4,70)`) и `hk_session` (`pos(4,100)`); при перекрытии на визуальном smoke (Step 6 Task 5) сдвинуть на ±5.

- [ ] **Step 2: Добавить узел `mcp_openapi` в `NODES`**

В секции MCP-серверов (после `mcp_semgrep`, формат-образец `mcp_boost` — Grep `id: 'mcp_boost'` — `group: 'mcp'`, `ring: 5`) вставить:

```js
  // A3 integration-tooling (17.05.2026) — MCP-сервер раздела «Программирование — интеграции»
  { id: 'mcp_openapi', label: 'MCP: openapi',         group: 'mcp', size: 20, ring: 5, ...pos(5, 330) },
```

`pos(5, 330)` — свободный угол после `mcp_redis` (`pos(5,310)`); при перекрытии сдвинуть.

- [ ] **Step 2a: Свериться с фактическим положением узлов MCP/agents**

Run: `Grep` по `automation-graph.html` паттерн `id: 'mcp_semgrep'|id: 'ag_rls'` — подтвердить точку вставки и отсутствие конфликта углов `pos()` с соседями.

- [ ] **Step 3: Добавить записи в `NODE_SECTION`**

В объекте `NODE_SECTION` после строки с A6-узлами (`adr_kit: 'A6', arch_patterns: 'A6', mermaid_skill: 'A6',`) или после D3-узлов — добавить:

```js
  // A3 integration-tooling 17.05.2026 — раздел «Программирование — интеграции» наполнен
  ag_apidocs: 'A3', mcp_openapi: 'A3',
```

- [ ] **Step 4: Добавить `nd()`-детали в `NODE_DETAILS`**

После D3-блока `nd()` (`tob_skills`/`sec_guidance`, локализовать Grep'ом `tob_skills`) добавить (формат-образец `adr_kit` — Grep `adr_kit: nd\(` — 6 аргументов `nd()`: что делает / когда / ограничения / кому подчиняется / кто подчиняется / с кем работает):

```js
  // ── A3 INTEGRATION-TOOLING (17.05.2026) ──────────
  ag_apidocs: nd(
    'Агент claude-flow — генерирует OpenAPI-спеку REST API по роутам и контроллерам Laravel. Pattern learning. 0 установки — агент доступен в сессии.',
    'При фиксации контракта REST API: генерация/обновление OpenAPI-спеки группы эндпоинтов. Результат — docs/api/.',
    'Sub-агент claude-flow — узел карты, но без отдельного номера в реестре Tooling Прил. Н (реестр — plugin-grain; 11 agent-узлов карты так же без Tooling-номеров). Не UI → вне фильтров R6.0/R6.1/R14.',
    [{ name: 'CLAUDE.md', cond: '§3.3 — упомянут при #47 openapi-mcp' }],
    [],
    [{ name: 'MCP: openapi', cond: 'генерирует спеку → openapi-mcp отдаёт её как MCP-ресурс' }]
  ),
  mcp_openapi: nd(
    'MCP-сервер (npm, stdio) — отдаёт OpenAPI-спеку как MCP-ресурс/тулы; introspection своей и чужих API при интеграционной разработке.',
    'При работе с интеграциями (API/вебхуки) — обращение к структуре OpenAPI-спеки из сессии Claude. READ-ONLY introspection.',
    'Правило PSR_v1 R10.1 блок 3 (integration-tooling, off-phase — 9-я подкатегория). stdio-режим, без port-conflict. Не UI → вне фильтров R6.0/R6.1/R14. Tooling §4.22 #47, CLAUDE.md §3.3 #47.',
    [{ name: 'PSR_v1', cond: 'R10.1 блок 3: integration-tooling' }, { name: 'Tooling', cond: '§4.22 #47 — реестр' }],
    [],
    [{ name: 'docs/api/', cond: 'источник OpenAPI-спеки' }]
  ),
```

- [ ] **Step 5: Добавить записи в `NODE_TIMELINE`**

После A6/D3-записей в `NODE_TIMELINE` (формат-образец `skill_creator` — Grep `skill_creator:.*since` — `{ since, changed, uses, usesSrc }`) добавить:

```js
  // ── A3 INTEGRATION-TOOLING (17.05.2026) ──
  ag_apidocs:  { since: '17.05.2026', changed: '—', uses: null, usesSrc: '—' },
  mcp_openapi: { since: '17.05.2026', changed: '—', uses: null, usesSrc: '—' },
```

- [ ] **Step 6: Добавить рёбра в `EDGES`**

После D3-блока рёбер (локализовать Grep'ом `E('psr_v1', 'sec_guidance'`) добавить:

```js
  // ── A3 INTEGRATION-TOOLING 17.05.2026 — связи новых узлов ──
  E('psr_v1',     'mcp_openapi', 'R10.1 блок 3:\nintegration-tooling'),
  E('tooling',    'mcp_openapi', '§4.22 #47 — реестр'),
  E('ag_apidocs', 'mcp_openapi', 'спека → MCP-ресурс'),
```

- [ ] **Step 7: Обновить комментарий-счётчик `NODE_SECTION`**

(Grep-комментарий `Покрывает все NNN узлов карты` — сейчас 116, ставим 118): `// Узел -> раздел. Покрывает все 116 узлов карты.` → `118 узлов`.
Run: `Grep` по `automation-graph.html` паттерн `\b(116|117|118)\b.*узлов` и `рёбер` — найти прочие счётчики/метрики, если есть, инкрементировать (узлы +2, рёбра +3). Если иных счётчиков нет — зафиксировать факт.

- [ ] **Step 8: Commit**

```bash
git add docs/automation-graph.html
git commit -m "feat(map): A3 nodes — api-docs agent + openapi MCP, section «Программирование — интеграции»"
```

---

## Task 5: Визуальный smoke карты

**Files:** нет правок — только проверка.

- [ ] **Step 1: Поднять локальный сервер и открыть карту**

Run (background): `npx -y serve docs -l 8123`. Через Playwright MCP: `browser_navigate http://localhost:8123/automation-graph.html`.

- [ ] **Step 2: Проверить граф**

`browser_console_messages` — 0 ошибок JS. Граф рендерится, 2 новых узла (`api-docs (agent)`, `MCP: openapi`) видны в секторах agents/mcp, без перекрытий. При перекрытии — вернуться в Task 4 Step 1/2, скорректировать угол `pos()`.

- [ ] **Step 3: Проверить панель «Разделы»**

Нажать «📂 Разделы». Раздел **A3** не пустой, показывает **7 узлов** (api-docs, openapi + 5 кросс-реф). Клик по узлу `MCP: openapi` → Паспорт, строка «Раздел» = `A3 · Программирование — интеграции (API, вебхуки)`. Клик по `MCP: laravel-boost` → строка «Раздел» = `A1 · … (+A3)`.

- [ ] **Step 4: Скриншот-доказательство**

`browser_take_screenshot` панели «Разделы» с раскрытым A3 → сохранить как `a3-section-smoke.png` (корень, как `iter-recollage-smoke.png`; **не коммитить** — артефакт smoke).

- [ ] **Step 5: Остановить сервер**

Завершить background-процесс `serve`.

Коммита нет — задача проверочная.

---

## Task 6: Tooling Прил. Н — §4.22 + счётчик

**Files:**

- Modify: `docs/Tooling_v8_3.md`

- [ ] **Step 1: Прочитать §4.21/§4.20 (A4-записи)**

Run: `Read` `docs/Tooling_v8_3.md`, `Grep` паттерн `§4.21|§4.20|§4.19` — зафиксировать структуру/стиль off-phase subsection (#44/#45/#46 design-tooling) для зеркалирования.

- [ ] **Step 2: Добавить §4.22**

После §4.21 добавить новый подраздел (зеркалируя стиль §4.19/§4.20/§4.21):

```markdown
### §4.22. #47 openapi-mcp-server — off-phase integration-tooling

**Пакет:** `<PKG>` (npm, репозиторий `ivo-toby/mcp-openapi-server`), stdio MCP, server `openapi` в `.mcp.json`, tools `mcp__openapi__*`.
**Категория:** off-phase, **integration-tooling** (9-я off-phase подкатегория — после UI-пула / infrastructure / debug-runtime / orchestration / architecture-tooling / audit-security / project-management / design-tooling). Раздел A3 карты «Программирование — интеграции (API, вебхуки)».
**Назначение:** отдаёт OpenAPI-спеку как MCP-ресурс/тулы; introspection своей и чужих API при интеграционной разработке. READ-ONLY.
**Парный узел карты:** `api-docs` agent (claude-flow) — генератор OpenAPI-спеки; узел карты A3 без отдельного Tooling-номера (sub-агент, реестр — plugin-grain).
**Координация:** PSR_v1 R10.1 Блок 3 (MCP-серверы). Не UI → не trigger'ит R6.0/R6.1, вне R14 pipeline.
**Статус установки:** [подставить из Task 2 Step 4 — «verified» либо «pending: native-Windows install не верифицирован»].
```

`<PKG>` — подставить точное имя из Task 2 Step 1.

- [ ] **Step 3: Обновить счётчик §0**

Run: `Grep` по `docs/Tooling_v8_3.md` паттерн `46|формализованных позиций|off-phase` — найти строку-счётчик §0 (после A4 = «46 формализованных позиций: 29 active + 16 off-phase + 1 historic» либо аналог). Инкрементировать: позиций 46→**47**, off-phase 16→**17**. Обновить перечисление off-phase subsections (добавить §4.22) и упоминание подкатегорий (добавить integration-tooling).

- [ ] **Step 4: Bump версии Прил. Н**

Шапка/колонтитул Прил. Н: v2.8 → **v2.9**. Добавить changelog-строку «v2.9 от 17.05.2026 — A3 integration-tooling: §4.22 #47 openapi-mcp-server, 9-я off-phase подкатегория integration-tooling; §0 счётчик 46→47. Связано: PSR_v1 v3.9, Pravila v1.23, CLAUDE.md v2.9.»

- [ ] **Step 5: Commit**

```bash
git add docs/Tooling_v8_3.md
git commit -m "docs(a3): Tooling Прил. Н v2.9 — register #47 openapi-mcp-server (§4.22)"
```

cspell-блок → добавить термины в `cspell-words.txt`, повторить.

---

## Task 7: PSR_v1 — R10.1 Блок 3

**Files:**

- Modify: `docs/Plugin_stack_rules_v1.md`

- [ ] **Step 1: Прочитать R10.1 Блок 3**

Run: `Grep` `docs/Plugin_stack_rules_v1.md` паттерн `R10.1|Блок 3|sentry|redis` — зафиксировать структуру Блока 3 (MCP-серверы; sentry/redis с категорией debug-runtime).

- [ ] **Step 2: Добавить строку в Блок 3**

В таблицу/список Блока 3 R10.1 добавить строку (зеркалируя строки sentry/redis):

```markdown
| openapi-mcp-server | integration-tooling | off-phase. stdio MCP, server `openapi` в `.mcp.json`. Раздел A3 карты. Не trigger'ит R6.0/R6.1, вне R14 pipeline. Tooling §4.22 #47. |
```

Точный формат строки — по факту таблицы (колонки сверить в Step 1).

- [ ] **Step 3: Bump версии**

Шапка PSR_v1: v3.8 → **v3.9**. Changelog-строка «v3.9 от 17.05.2026 — R10.1 Блок 3 +1 строка openapi-mcp-server (категория integration-tooling, off-phase, раздел A3). Не UI → вне R6/R14. Связано: Tooling v2.9, Pravila v1.23, CLAUDE.md v2.9.» Обновить cross-refs шапки, если они перечисляют версии родственных файлов.

- [ ] **Step 4: Commit**

```bash
git add docs/Plugin_stack_rules_v1.md
git commit -m "docs(a3): PSR_v1 v3.9 — R10.1 Блок 3 +openapi-mcp (integration-tooling)"
```

---

## Task 8: Pravila — §13.2

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md`

- [ ] **Step 1: Прочитать §13.2**

Run: `Grep` `docs/Pravila_raboty_Claude_v1_1.md` паттерн `§13.2|Off-phase|audit-security|architecture-tooling` — зафиксировать структуру абзацев off-phase подкатегорий (последний добавленный — audit-security, D3).

- [ ] **Step 2: Добавить абзац**

После абзаца «Off-phase audit-security» добавить:

```markdown
**Off-phase integration-tooling.** Инструменты раздела A3 карты «Программирование — интеграции (API, вебхуки)» — #47 `openapi-mcp-server` (Tooling §4.22; введён A3-интеграцией 17.05.2026) и `api-docs` agent (claude-flow, узел карты A3 без отдельного Tooling-номера). Off-phase, не UI → вне R6/R14 PSR_v1. READ-ONLY introspection. Регулируются PSR_v1 R10.1 Блок 3.
```

- [ ] **Step 3: Bump версии + счётчик правил**

Шапка Pravila: v1.22 → **v1.23**. Если §13.2 (или §11.5) содержит счётчик подкатегорий/правил — свериться `Grep`'ом и инкрементировать. Changelog-строка «v1.23 от 17.05.2026 — §13.2 +абзац Off-phase integration-tooling (#47 openapi-mcp-server / api-docs agent — раздел A3 карты). Связано: Tooling v2.9, PSR_v1 v3.9, CLAUDE.md v2.9.»

- [ ] **Step 4: Commit**

```bash
git add docs/Pravila_raboty_Claude_v1_1.md
git commit -m "docs(a3): Pravila v1.23 — §13.2 +Off-phase integration-tooling"
```

---

## Task 9: CLAUDE.md — через claude-md-management

**Files:**

- Modify: `CLAUDE.md` (только через скил — §5 п.10)

- [ ] **Step 1: Инвокировать claude-md-improver**

Invoke `/claude-md-management:claude-md-improver` со списком targeted-правок:

- §3 title «Карта 46 инструментов» → «47»;
- §3.3 +строка #47 openapi-mcp-server (integration-tooling, off-phase; Tooling §4.22) + упоминание `api-docs` agent как парного узла карты A3 без Tooling-номера;
- §1 priority-chain row 2b «реестр 46» → «47»;
- §3.3 footer count 46→47 + integration-tooling как 9-я off-phase подкатегория;
- §3.4 нумерационная сноска — добавить #47 в перечисление off-phase, обновить арифметику;
- §0 cross-refs: Pravila v1.22→**v1.23**, PSR_v1 v3.8→**v3.9**, Tooling v2.8→**v2.9**;
- §6 +абзац A3 integration-tooling (по образцу абзацев A6/D3/A4);
- шапка v2.8 → **v2.9** + §9 changelog-запись.

- [ ] **Step 2: Проверить синхронность (§5 п.7)**

Убедиться, что внутри flow скила Tooling (Task 6) и Pravila (Task 8) уже синхронизированы — версии в §0 cross-refs CLAUDE.md совпадают с фактическими шапками файлов.

- [ ] **Step 3: Commit**

Скил/ручной коммит:

```bash
git add CLAUDE.md
git commit -m "docs(a3): CLAUDE.md v2.9 — register #47 openapi-mcp-server (A3 integration-tooling)"
```

---

## Task 10: Регрессия + память + handoff на push

**Files:**

- Modify: `memory/project_automation_map.md`, `memory/reference_archive.md` (после успешной регрессии)

- [ ] **Step 1: Регрессия quick**

Invoke skill `regression` с аргументом `quick` (lint/format/type-check). Зафиксировать канонический статус-лайн + вердикт. Ожидание GREEN — правки только в `.md`/`.html`/`.json`/`.yaml`, прикладной код не тронут.

- [ ] **Step 2: Финальная сверка счётчика (риск нумерации)**

Run: `git log --oneline origin/main..HEAD` + `Grep` Tooling §0 — подтвердить, что #47/§4.22 не пересёкся с A11, если та смёрджилась в main (C9/deptrac/A4 уже влиты). При коллизии — перенумеровать openapi-mcp на следующий свободный номер во всех 4 файлах + карте, повторить затронутые коммиты.

- [ ] **Step 3: Обновить memory**

- `memory/project_automation_map.md` — метрики 116→118 узлов / +3 ребра, раздел A3 наполнен (7 узлов: 2 новых + 5 кросс-реф), `NODE_SECTION_SECONDARY` слой.
- `memory/reference_archive.md` — версии Tooling v2.9 / PSR_v1 v3.9 / Pravila v1.23 / CLAUDE.md v2.9.
- `MEMORY.md` — обновить строки-указатели при необходимости.

- [ ] **Step 4: Commit memory**

```bash
git add memory/
git commit -m "docs(a3): memory sync — A3 integration-tooling closed"
```

- [ ] **Step 5: Handoff на push**

Не пушить автоматически. Представить заказчику: ветка `feat/a3-integration-tooling`, перечень коммитов, напоминание про pre-push (`gitleaks` full-history + `lychee`) и про порядок merge относительно D3/A11/C9. Push — по явному «пушь» (паттерн `git push origin feat/a3-integration-tooling:main`).

---

## Self-Review

**Spec coverage:**

- spec §3.1 (2 новых узла) → Task 1 (api-docs smoke), Task 2 (openapi-mcp install), Task 4 (узлы карты). ✓
- spec §3.2 (5 кросс-реф) → Task 3 (`NODE_SECTION_SECONDARY`). ✓
- spec §4 (правка модели карты) → Task 3 + Task 4 + Task 5. ✓
- spec §5 (нормативка 4 файла) → Task 6 (Tooling), 7 (PSR_v1), 8 (Pravila), 9 (CLAUDE.md). ✓
- spec §6 (smoke/верификация) → Task 1 Step 4, Task 2 Step 4, Task 5, Task 10 Step 1. ✓
- spec §7 (риск нумерации) → Task 10 Step 2. ✓
- spec §8 (ветка/артефакты) → ветка создана (`feat/a3-integration-tooling`), spec/plan на месте, push-handoff Task 10 Step 5. ✓

**Placeholder scan:** `<PKG>` — намеренный плейсхолдер, разрешается в Task 2 Step 1 (`npm view`) и подставляется в Task 2 Step 3 / Task 6 Step 2; «[подставить из Task 2 Step 4]» — статус установки, разрешается в рамках Task 2. Иных плейсхолдеров нет.

**Type consistency:** имена узлов `ag_apidocs` / `mcp_openapi` — единообразны во всех задачах (NODES, NODE_SECTION, NODE_DETAILS, NODE_TIMELINE, EDGES, NODE_SECTION_SECONDARY не содержит их — они первичны в A3). Объект `NODE_SECTION_SECONDARY` — одно имя везде. Версии: Tooling v2.9 / PSR_v1 v3.9 / Pravila v1.23 / CLAUDE.md v2.9 — консистентны в Tasks 6-9 и §0 cross-refs.
