docs(adr): ADR-013 backend-tooling boundaries (BT1-BT9) + NightOwl deferred spike

ADR-013: 4 узла A1 (#64-67) + границы BT1-BT9 + постуры. NightOwl DEFERRED
(native-Windows нет pcntl/posix + OSS без MCP + hosted 152-ФЗ) -> Linux/Б-1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Дмитрий
2026-05-20 15:40:05 +03:00
parent 76ea9bbb04
commit 1a02b4b5f2
4 changed files with 94 additions and 1 deletions
+3
View File
@@ -1565,3 +1565,6 @@ lemed
спекам
джобе
биллингового
непуст
гейтят
гейты
+57
View File
@@ -0,0 +1,57 @@
# 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).
+33
View File
@@ -0,0 +1,33 @@
# NightOwl (#67) — feasibility spike + decision
**Дата:** 2026-05-20
**Узел:** #67 NightOwl (раздел A1, backend-tooling) — self-hosted runtime-телеметрия.
**Вывод:** **DEFERRED** (pending-слот, активация на Linux/боевом сервере при Б-1). Решение заказчика 20.05.2026.
## Что выяснил spike
Источник: `github.com/lemed99/nightowl-agent` (MIT) + `laravel/nightwatch` (сбор телеметрии).
| Вопрос | Ответ |
|---|---|
| Self-hosted ingest в свой PostgreSQL без managed-аккаунта? | **Да** — open-source агент пишет телеметрию напрямую в PG (≈13 400 payloads/s). |
| MCP-сервер для AI (Claude Code) в open-source? | **Нет.** MCP — только в managed-сервисе usenightowl.com (платный). OSS-агент даёт сырые таблицы телеметрии, но не MCP. |
| Запускается на native-Windows? | **Нет.** Требует PHP-расширения `pcntl` + `posix` (UNIX-only, на native-Windows отсутствуют). Windows-поддержка в доках не упомянута. |
## Блокер
Та же причина, что блокировала Docker / pg_partman / Jupyter MCP на этой машине — **native-Windows стек без UNIX-окружения**. Агент NightOwl не запустится локально (`pcntl`/`posix`), а готовый MCP-доступ есть только в облачном платном тире.
Облачная альтернатива (hosted Nightwatch free-tier + официальный Nightwatch MCP) технически работает на Windows, но **отправляет телеметрию портала во внешнее облако** — риск по 152-ФЗ (персональные данные). Отклонено заказчиком (как и hosted Sentry в своё время).
## Решение (заказчик, 20.05.2026)
**Отложить до боевого сервера.** Узел #67 регистрируется в реестре как **DEFERRED / pending-слот** (прецеденты: Sentry MCP #34 pending Б-1, Figma MCP #44, Jupyter MCP #50). Ничего не устанавливаем, `.mcp.json` не трогаем, данные никуда не уходят.
## Условия активации (когда снимать DEFERRED)
1. Появился Linux/боевой сервер (Б-1) с PHP `pcntl`/`posix`.
2. Развёрнут open-source `nightowl-agent`, телеметрия пишется в PostgreSQL Лидерры.
3. Доступ Claude к телеметрии: либо managed MCP (если приемлемо по 152-ФЗ — телеметрия без ПДн), либо чтение таблиц телеметрии через Boost `database-query` (READ-ONLY) — fallback без облака.
Граница с соседями (ADR-013): Sentry #34 = ошибки/трейсбэки; Pail = tail логов; Boost = снапшот логов/запросов; NightOwl = коррелированный сквозной трейс request↔job↔query↔cache.
+1 -1
View File
@@ -1,6 +1,6 @@
# Brain Status (auto-generated)
Last updated: 2026-05-21T01:18:44.764Z
Last updated: 2026-05-21T01:18:46.313Z
| Контролёр | Состояние | Детали |
|---|---|---|