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:
@@ -1565,3 +1565,6 @@ lemed
|
||||
спекам
|
||||
джобе
|
||||
биллингового
|
||||
непуст
|
||||
гейтят
|
||||
гейты
|
||||
|
||||
@@ -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).
|
||||
@@ -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,6 +1,6 @@
|
||||
# Brain Status (auto-generated)
|
||||
|
||||
Last updated: 2026-05-21T01:18:44.764Z
|
||||
Last updated: 2026-05-21T01:18:46.313Z
|
||||
|
||||
| Контролёр | Состояние | Детали |
|
||||
|---|---|---|
|
||||
|
||||
Reference in New Issue
Block a user