brain/docs/adr/013-backend-tooling.md

ADR-013: A1 backend-tooling — наполнение раздела карты A1

Status: Accepted Date: 2026-05-20 Контекст: эпик A1 backend-tooling, spec docs/superpowers/specs/2026-05-20-a1-backend-tooling-design.md.

Context

Раздел карты A1 «Программирование — backend» был тонким — 3 узла: Boost #10 (Laravel-контекст), Pint #11 (стиль), Larastan #12 (типы). Backend-смежное уехало в другие разделы (Pest→A5, squawk/pg_partman→A9, deptrac→A6, openapi→A3, Sentry/Redis→A7). Дефициты чистого A1: авто-рефакторинг, метрики сложности/архитектуры, кодифицированные backend-конвенции Лидерры, коррелированная runtime-телеметрия. На Anthropic-marketplace чистого backend-кодинга нет (knowledge-work + meta); A1 закрывается GitHub PHP-экосистемой плюс одним self-authored скилом.

Decision

1. Rector (#64) — rector/rector + driftingly/rector-laravel (Composer dev-dep). Авто-рефакторинг + version-aware апгрейды. Конфиг app/rector.php — консервативный старт (deadCode + codeQuality, БЕЗ type-declaration наборов и LaravelSetProvider).
   • Постура: manual/CI (composer rector / composer rector:fix), НЕ блокирующий lefthook. Spike dry-run = 16 файлов (>5 порога → код-мутирующий инструмент не гейтит коммит; прецедент promptfoo ML1). LaravelSetProvider — для разовых апгрейдов вручную.
2. PHP Insights (#65) — nunomaduro/phpinsights (Composer dev-dep). Метрики complexity / architecture / maintainability. Конфиг app/phpinsights.php.
   • Постура: on-demand/CI (composer insights с порогами --min-*), НЕ блокирующий lefthook (BT9 — избегаем четверного гейта Pint/Larastan/deptrac/Rector). Style-ось выключена (владелец стиля — Pint); акцент Complexity + Architecture.
3. laravel-backend-patterns (#66) — self-authored project-скил (.claude/skills/). Кодификация backend-конвенций Лидерры (слоистость / RLS-aware / bcmath-деньги / идемпотентность / partition-aware). Активен.
4. NightOwl (#67) — self-hosted runtime-телеметрия. DEFERRED (pending Б-1 / Linux). Блокер: native-Windows без pcntl/posix (агент не запускается); OSS-версия без MCP (MCP только managed); hosted = риск 152-ФЗ. Spike + условия активации: docs/backend/nightowl-spike.md. Прецедент: Sentry #34 / Figma #44 / Jupyter #50.

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

• BT1 Rector ↔ Pint: трансформация vs форматирование — разные операции.
• BT2 Rector ↔ Larastan: Rector чинит, Larastan находит — комплементарны.
• BT3 Rector ↔ deptrac: трансформация кода vs граф слоёв — ортогональны.
• BT4 PHP Insights ↔ Pint/Larastan: style/code оси выключены; уникум = 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? — нет (избегаем четверного гейта); on-demand/CI.

Consequences

• A1 непуст: 3 → 6 узлов активных (Boost/Pint/Larastan + Rector/PHP Insights/backend-patterns) + 1 DEFERRED (NightOwl).
• Новая off-phase подкатегория backend-tooling (16-я).
• Rector и PHP Insights не гейтят коммит (manual/CI) — осознанно, чтобы не дублировать существующие блокирующие гейты (Pint/Larastan/deptrac) и не авто-мутировать код на коммите.
• Rector оставляет разовый задел чистки (16 файлов) — применяется вручную через composer rector:fix с ревью + полным прогоном тестов, не в этом эпике.
• NightOwl — capability-readiness: задокументирован, активация при появлении Linux/боевого сервера (Б-1).