# A1 backend-tooling integration — design

**Дата:** 2026-05-20
**Раздел карты:** A1 «Программирование — backend»
**Тип:** off-phase tooling integration (как A11 / C10 / discovery / finance)
**Статус:** design (на утверждение заказчика)

---

## 1. Контекст и проблема

Раздел A1 «Программирование — backend» на карте `docs/automation-graph.html` — **тонкий, 3 узла**:

- `mcp_boost` — Laravel Boost MCP (схема / Eloquent / доки / логи / ошибки / запросы);
- `lh_pint` — Pint (стиль кода, lefthook job 5);
- `lh_larastan` — Larastan (статанализ типов, lefthook job 6).

Всё backend-смежное живёт в других разделах: Pest → A5, squawk/pg_partman → A9, deptrac → A6, openapi/api-docs → A3, Sentry/Redis MCP → A7.

**Дефициты чистого A1** (написание / трансформация / качество backend-кода — отдельно от тестов A5, безопасности A8, данных A9, архитектуры A6, интеграций A3):

1. Автоматический рефакторинг и version-aware апгрейды кода — **нет**.
2. Метрики сложности / maintainability / архитектурного распределения — **нет** (Pint = стиль, Larastan = типы; ось сложности не покрыта).
3. Кодифицированные backend-конвенции самой Лидерры (деньги, multi-tenant изоляция, идемпотентные джобы) — **нет** (есть только generic architecture-patterns #38).
4. Коррелированная runtime-телеметрия для дебага кода — **частично** (Pail = tail логов, Boost = снапшот, Sentry #34 = ошибки A7 pending Б-1; единый трейс request↔job↔query↔cache отсутствует).

**Источник «антропик vs github»:** на Anthropic-marketplace чистого backend-кодинга нет (knowledge-work + meta + dev-support; «engineering» plugin = incident/runbook docs, дублирует `operations` #51, это A7-ops). A1 объективно закрывается **GitHub PHP-экосистемой + одним self-authored скилом**.

## 2. Scope

4 новых узла A1, новая **16-я off-phase подкатегория «backend-tooling»**, номера Tooling **#64–#67** (продолжение после finance #61–63):

| ID карты | # | Узел | Источник | Активность |
|---|---|---|---|---|
| `rector` | 64 | Rector + rector-laravel | GitHub `rectorphp/rector` + `driftingly/rector-laravel`, Composer dev-dep | gate-постура по spike |
| `php_insights` | 65 | PHP Insights | GitHub `nunomaduro/phpinsights`, Composer dev-dep | on-demand / CI |
| `backend_patterns` | 66 | laravel-backend-patterns | self-authored project-скил | активно |
| `nightowl` | 67 | NightOwl (self-hosted) | GitHub `lemed99/nightowl-agent` + `laravel/nightwatch` | активно (spike по MCP-доступу) |

### Out of scope (осознанно отброшено)

- **Laravel Nightwatch hosted (free-tier)** — отброшен в пользу self-hosted NightOwl (паттерн self-hosted Sentry; данные не уходят наружу).
- **Laravel Horizon** — человеческий дашборд Redis-очередей (A7), не Claude-tooling; слабый узел карты A1.
- **Anthropic «engineering» plugin** — incident/runbook docs (A7-ops), дублирует `operations` #51.
- **Laravel Herd MCP** — проект на native-Windows стеке (Chocolatey PG + Memurai + native PHP), не Herd.

## 3. Дизайн узлов

### #64 Rector (`rector`)

- `rector/rector` (v2.4.3, 12.05.2026) + `driftingly/rector-laravel` в `app/composer.json` `require-dev`.
- Конфиг `app/rector.php`: `LaravelSetProvider` (авто-наборы по версии Laravel из composer.json) + консервативный старт — **dead-code + code-quality наборы, БЕЗ агрессивных type-declaration наборов** на первом заходе.
- **Gate-постура — решается по spike** (Task: `rector process --dry-run` на `app/`, счёт нарушений):
  - 0 / около-0 → блокирующий lefthook **job 16** на staged `app/**/*.php` (паттерн deptrac: первый прогон 0 → baseline не нужен, падение только на новом дрейфе);
  - много → `composer rector` script + CI-прогон, блокирующий гейт отложить (паттерн promptfoo — код-мутирующий инструмент не в хук без доказанной чистоты).
- **Граница (ADR-013):** Pint = стиль, Larastan = типы, deptrac = направление зависимостей, **Rector = семантическая трансформация / апгрейд**. Нет пересечения — разные операции над кодом.

### #65 PHP Insights (`php_insights`)

- `nunomaduro/phpinsights` в `require-dev`, конфиг `app/phpinsights.php`.
- **Постура: on-demand / CI с порогами** (`--min-quality`, `--min-complexity`, `--min-architecture`), **НЕ блокирующий lefthook** — иначе четверное гейтование с Pint/Larastan/deptrac/Rector на каждом коммите.
- Style-проверки **отключить** (владелец стиля — Pint); конфиг акцентирует **Complexity + Architecture** оси, которых нет ни у одного текущего инструмента.
- Реюз: метрика в `audit-portal` скиле (показатель здоровья кода для периодических аудитов).
- **Граница (ADR-013):** перекрытие с Pint (style) и Larastan (code) по двум осям → эти оси выключены; уникум PHP Insights = complexity + architecture distribution.

### #66 laravel-backend-patterns (`backend_patterns`)

- Self-authored project-скил `.claude/skills/laravel-backend-patterns/` (паттерн `billing-audit` / `ru-tax-accounting`): `SKILL.md` + `references/` + (опц.) `evals/`.
- Кодифицирует backend-конвенции Лидерры:
  - слоистость `controller → FormRequest → service → job` (deptrac-aligned, 13 слоёв `app/deptrac.yaml`);
  - RLS-aware Eloquent: `SET LOCAL app.current_tenant_id` через `SetTenantContext`; явный `where(tenant_id)` в queued-джобах под ролью `crm_supplier_worker` (BYPASSRLS);
  - деньги через bcmath / `LedgerService` (cross-ref `billing-audit` #62 — без дублирования money-инвариантов, ссылка);
  - идемпотентные джобы (advisory-locks, паттерн `HistoricalImportService` / `CsvReconcileJob`);
  - partition-aware запросы к `deals` / `supplier_lead_costs`.
- Триггеры: «как писать backend в Лидерре», «паттерн контроллера/сервиса/джоба», scaffolding новой backend-фичи.
- **Граница (ADR-013):** `architecture-patterns` #38 = generic (Clean / Hexagonal / DDD); этот скил = project-specific конвенции Лидерры. `billing-audit` #62 = аудит денежной корректности (проверка); этот = как писать (генерация). Линтуется (не вендоренный → не в lefthook ignorePaths).

### #67 NightOwl (`nightowl`)

- `laravel/nightwatch` (официальный пакет сбора телеметрии) + `lemed99/nightowl-agent` (open-source self-hosted агент → маршрутизация в PostgreSQL Лидерры).
- Покрывает коррелированный трейс: request ↔ outgoing request ↔ job ↔ query ↔ mail ↔ cache ↔ scheduled task.
- **Spike (Task):** доступен ли MCP-доступ в self-hosted open-source варианте.
  - доступен → регистрируем MCP-сервер в `.mcp.json` (READ-ONLY);
  - только managed-tier → fallback: Claude читает таблицы телеметрии через Boost `database-query` (телеметрия в том же PG). Узел остаётся активным, меняется только access-path.
- **Граница (ADR-013):** Sentry #34 = ошибки / трейсбэки (A7, pending Б-1); Pail = real-time tail логов; Boost = снапшот логов/запросов по требованию; **NightOwl = коррелированный сквозной трейс** работающего портала. READ-ONLY usage (как Sentry/Redis MCP).

## 4. Роутер footprint (ADR-011 brain governance)

- **`docs/router-procedure.md`** v1.1 → **v1.2**: без изменения процедуры; bump cross-ref-строк под новый набор узлов (шаг 3 читает 9-атрибутный реестр Tooling).
- **`docs/routing-off-phase.md`** v1.2 → **v1.3**: +4 строки routing-таблицы (триггер → узел) для #64–67 + новая каноническая связка **L14 «backend-quality chain»**: Rector (#64, авто-трансформация) → PHP Insights (#65, метрики) → Larastan (#12, типы) → deptrac (#43, слои). Anti-pattern: не запускать Rector-автоправку и PHP Insights-метрику как один блокирующий шаг (трансформация и измерение — разные фазы).
- **9-атрибутный реестр** (Tooling Прил. Н §4.39–4.42) — вход роутера (step 3): каждый узел получает полный 9-attribute блок.

## 5. Наблюдатель footprint (ADR-011 / observer factor-analysis)

- **9-атрибутные «Атрибуты»-блоки** на 4 новых узлах в Tooling Прил. Н (как finance §4.36–38) — кормят и роутер, и факторный анализ наблюдателя.
- **Контролёры:**
  - **C1 l1-watcher** (lefthook job 11, STRICT): новый MCP-сервер NightOwl в `.mcp.json` обязан иметь формализацию в Tooling Прил. Н — иначе блок коммита. При групповом/human-имени — alias в `tools/.l1-watcher-aliases.txt`.
  - **C2 cross-ref-checker** (lefthook job 12, STRICT): требует **атомарного version-bump-набора** (Tooling / PSR_v1 / Pravila / CLAUDE.md в одном коммите нормативки) — иначе drift и блок коммита.
- Наблюдатель пишет evidence по эпизодам сессии (Stop-hook) как обычно; новые узлы становятся видимы факторному анализу `/brain-retro`.

## 6. Нормативный footprint (атомарный набор)

- **Tooling Прил. Н** v2.18 → **v2.19**: §4.39–4.42 (#64–67 + 9-атрибутные блоки) + §0 счётчик 63 → 67 + 16-я off-phase подкатегория backend-tooling.
- **PSR_v1** v3.18 → **v3.19**: R10.1 Блок 1/3 +4 строки (не UI → вне R6/R14).
- **Pravila** v1.34 → **v1.35**: §13.2 +абзац «Off-phase backend-tooling».
- **CLAUDE.md** v2.21 → **v2.22**: §3.3 +#64–67, §6 +абзац, §9 +запись (через прямой Edit — worktree-эксцепшн §5 п.10, прецедент A11/C10/discovery/finance).
- **ADR-013** — границы узлов + коды конфликт-аудита BT1–BT9 (§8).

## 7. Карта footprint

- `docs/automation-graph-data.js`: +4 узла в `NODE_SECTION` (все A1), рёбра (4 узла + L14-связка + reuse-кросс-рефы на Pint/Larastan/deptrac/billing-audit), версии-метки в шапке (v1.35/v2.22/v3.19/v2.19), счётчики узлов/рёбер.
- Browser-smoke карты после правки (как iter9 / finance).

## 8. Конфликт-аудит (коды BT — для ADR-013)

- **BT1** Rector ↔ Pint: трансформация vs форматирование — разные операции, нет дубля.
- **BT2** Rector ↔ Larastan: Rector чинит, Larastan находит типовые ошибки — комплементарны (Rector может закрывать часть Larastan-находок авто-правкой).
- **BT3** Rector ↔ deptrac: трансформация кода vs граф слоёв — ортогональны.
- **BT4** PHP Insights ↔ Pint/Larastan: перекрытие по style/code осям → эти оси в PHP Insights выключены; уникум = complexity + architecture.
- **BT5** backend-patterns ↔ architecture-patterns #38: project-specific vs generic.
- **BT6** backend-patterns ↔ billing-audit #62: генерация (как писать) vs аудит (проверка денег) — ссылка, не дубль.
- **BT7** NightOwl ↔ Sentry #34: коррелированный трейс vs ошибки/трейсбэки.
- **BT8** NightOwl ↔ Pail / Boost: сквозной трейс vs tail / снапшот по требованию.
- **BT9** PHP Insights blocking? — нет (избегаем четверного гейта Pint/Larastan/deptrac/Rector); on-demand/CI.

## 9. Spikes / риски (ранние задачи плана)

1. **Rector dry-run count** на `app/` → определяет gate-постуру #64 (§3).
2. **NightOwl self-hosted MCP-доступность** → определяет access-path #67 (MCP vs Boost database-query).
3. **PHP Insights baseline-прогон** → подтверждает пороги `--min-*`.
4. **Атомарность version-bump** (C2 STRICT) — нормативку коммитить одним набором.

## 10. Подход к исполнению

- Изолированный `git worktree` от актуального `origin/main` (паттерн A11/C10/finance; Pravila §15 параллельные сессии).
- Subagent-driven: скилы / ADR / конфиги — Sonnet-субагенты по полным спекам; нормативка / карта / контроллер — Opus.
- Атомарные коммиты (один логический change → один коммит); финальная регрессия (Pest/Vitest/Larastan) GREEN перед push.
- CLAUDE.md правится прямым Edit (worktree-эксцепшн §5 п.10).

## 11. Открытые решения заказчика (зафиксировано)

- PHP Insights постура — **отчёт on-demand/CI** (не блокирующий гейт). ✅ принято 20.05.2026.
- Состав скила #66 — деньги без потери копеек / изоляция клиентов / аккуратные фоновые задачи. ✅ принято 20.05.2026.
- Роутер + наблюдатель — включены в footprint (§4, §5) по поправке заказчика 20.05.2026. ✅
