diff --git a/cspell-words.txt b/cspell-words.txt index 9f942072..a2d9b4d1 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1565,3 +1565,6 @@ lemed спекам джобе биллингового +непуст +гейтят +гейты diff --git a/docs/adr/013-backend-tooling.md b/docs/adr/013-backend-tooling.md new file mode 100644 index 00000000..e2cd9c2e --- /dev/null +++ b/docs/adr/013-backend-tooling.md @@ -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). diff --git a/docs/backend/nightowl-spike.md b/docs/backend/nightowl-spike.md new file mode 100644 index 00000000..b5e58d20 --- /dev/null +++ b/docs/backend/nightowl-spike.md @@ -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. diff --git a/docs/observer/STATUS.md b/docs/observer/STATUS.md index 8b64b059..dae174f0 100644 --- a/docs/observer/STATUS.md +++ b/docs/observer/STATUS.md @@ -1,6 +1,6 @@ # Brain Status (auto-generated) -Last updated: 2026-05-21T01:18:44.764Z +Last updated: 2026-05-21T01:18:46.313Z | Контролёр | Состояние | Детали | |---|---|---|