av-dev-pipeline: починены находки ревью, бриф заводится скиллом

- скилл project-brief: бриф собирается из CLAUDE.md, архитектуры, Taskfile
  и конвенций и показывается человеку. Раньше единственная инструкция по
  его созданию лежала внутри шаблона, поэтому деградированный режим был не
  аварийным, а единственным: critical по основанию «нарушен инвариант»
  недостижим ни на одной задаче
- rebase перенесён внутрь worktree задачи: прежняя форма падала на занятой
  ветке, и агент уводил весь батч в провалившиеся с ложной причиной
- контракт брифа дополнен восемью слотами; проверен заполнением на обоих
  проектах, незаполнимых нет. Прецедент healthlog вынут из общего charter'а
  в бриф — там он вмёрз вместе с числами
- шов: пайплайн задачу не закрывает и записи учёта не трогает, урожай
  отдаёт списком, правило остатка — ссылкой на av-dev-tasks
- деградированный абзац во всех девяти проходах, вопрос 9 в ops,
  пространство имён в вызовах, раздел предпосылок
This commit is contained in:
av
2026-08-03 11:45:40 +03:00
parent 20dca29add
commit 0eca206460
18 changed files with 1021 additions and 214 deletions
@@ -1,7 +1,8 @@
# Шаблон брифа проекта
Скопируй в `docs/review-brief.md` и заполни. Контракт разделов — в
[project-brief.md](project-brief.md); здесь только образец заполнения.
Образец заполнения. Контракт разделов — в
[project-brief.md](project-brief.md); заводит бриф по этому образцу скилл
`av-dev-pipeline:project-brief` — руками копировать не надо, но читать полезно.
Курсивом даны пояснения — их из готового брифа убирают. Примеры взяты из двух
разных проектов (коллектор данных с непрерывным потоком и связующий сервис вокруг
@@ -26,7 +27,8 @@
## Инварианты
*Проверяемое свойство + последствие + severity по умолчанию. Цитируются
формулировкой.*
формулировкой. Severity проект обычно не пишет — тогда она выводится по
обратимости и помечается: «по умолчанию `critical` (выведена по обратимости)».*
- **Точка сохраняется дословно.** Незнакомое поле не отбрасывается, число не
округляется при записи. Нарушение — необратимая потеря: сырой архив живёт
@@ -70,12 +72,26 @@
- Карта проекта для архитектурного прохода: `task review:context > tmp/review-context.md`
- Поднять изменение вживую: `task restart`, логи — `task logs`
- Тесты и линт: `task test`, `task lint`
- Дорогое, вручную: `task verify:archive` (минута, живые данные)
- **Дорогое вне гейта, с адресатом:** `task verify:archive` (минута, живые
данные). **Кто и когда обязан:** пайплайн задачи — после любого изменения
разбора входного формата или правила слияния, до архивации change; вручную —
человек перед выкладкой. Не прогонялась — строка в границы покрытия, а не
молчание.
- **Запускать запрещено:** ничего, что пишет в `./data`, в рабочую БД и в боевой
каталог архива. Замеры — только на копиях в `./tmp`.
## Прод и поток
*Первая строка — главный вопрос эксплуатации этого проекта.*
> **Главный вопрос:** поток идёт непрерывно и молча, отправитель об отказе не
> узнает и не повторит — значит, дороже всего тихо потерянная доставка, а не
> упавший сервис.
> *(В сервисе, который сам опрашивает чужих демонов, первая строка была бы
> противоположной: «главный вопрос — что происходит, когда внешний сервис
> отвечает медленно, а не когда он упал».)*
- **Где:** один статический бинарь в контейнере на домашнем сервере, перед ним
обратный прокси с TLS, SQLite на диске. Ни оркестратора, ни реплик, ни дежурной
смены.
@@ -84,11 +100,17 @@
параллельной записью; приложение-источник на телефоне — молча перестаёт слать.
*(В другом проекте здесь были бы качалка, медиасервер, LLM и база метаданных, и
каждая — со своим «отвечает медленно», а не только «упала».)*
*(Если зависимостей нет — так и пишут: «внешних зависимостей нет, смотри на
диск и на СУБД». Пустой пункт называется пустым.)*
- **Кто заметит отказ:** один пользователь-владелец, в лучшем случае вечером, а
скорее не заметит вовсе.
- **Характер потока:** телефон шлёт непрерывно и молча; обратной связи у
отправителя нет, об отказах он не сообщает, расписание плавает. Тихо
сломавшаяся доставка — главный эксплуатационный риск.
- **Представление данных и настройки хранилища:** запись — сжатый BLOB, читается
и пересобирается целиком на каждой операции (`internal/store`); журнал СУБД —
WAL; таймаут занятости — 5000 мс (`config.example.toml`); лимит тела приёма —
64 МБ; ретеншен сырого архива — 14 дней.
- **Числа (с провенансом):** нижний слой — порядка 135 тыс. точек в сутки
(замер, `docs/local-research.md`); тела доходили до 42 МБ (там же); запись —
read-modify-write под конкурентными доставками (`docs/architecture.md`).
@@ -98,6 +120,19 @@
## Модель угроз
*Первая строка — периметр.*
> **Периметр:** сервис открыт наружу через обратный прокси, недоверенным считается
> всё, что приходит по HTTP. Злоумышленник в локальной сети — вне периметра.
> *(У сервиса в доверенном контуре первая строка противоположна: «контур
> доверенный, публичного интернета здесь нет — не выдумывай его; недоверенное
> здесь — то, что отдают внешние демоны и трекеры».)*
> *(Контур ещё не развёрнут — тогда периметров два: «целевой — за прокси с TLS;
> сегодняшний — только локальная машина, токены пусты осознанно. **Находки
> строятся против целевого**, отсутствие TLS сегодня находкой не является».)*
- **Недоверенное:** тело доставки целиком (имена метрик, единицы, формы точек,
метки времени, глубина вложенности, размер); заголовки доставки, часть которых
участвует в решениях; содержимое архива внешнего экспорта (имена файлов внутри
@@ -117,13 +152,25 @@
## Карта
- **Основная ветка:** `master`. От неё берутся ветки задач, в неё вливается батч,
база диффа по умолчанию — `git merge-base HEAD master` (на самой ветке `HEAD~1`).
- Актуальные спеки: `openspec/specs/<capability>/spec.md`
- Дельта-спеки изменения: `openspec/changes/<id>/specs/*/spec.md`
- Конвенции прозой: `docs/conventions.md`. Механизировано и потому **не
проверяется проходом по конвенциям**: форма логов, `fmt.Print*`/`os.Getenv`/
`time.Now` мимо единых точек, сравнение ошибок, сторонние пакеты ошибок —
всё это правила в `.golangci.yml`.
- **Нарезка capability и что из неё переехало в спеки:** режем по домену
(`ingest`, `storage`, `read-api`, `mcp`), а не по транспорту. В актуальные
спеки перенесены `ingest` и `storage`; `read-api` описан только в
`docs/architecture.md`, `mcp` — пока только в коде. Пробел в спеке по этим двум
темам — не находка, а известное состояние.
- Конвенции прозой: `docs/conventions.md` *(в другом проекте это каталог из
нескольких файлов — тогда перечисляют все:
`docs/conventions/{logging,errors,config,database,web-ui}.md`)*. Механизировано
и потому **не проверяется проходом по конвенциям**: форма логов,
`fmt.Print*`/`os.Getenv`/`time.Now` мимо единых точек, сравнение ошибок,
сторонние пакеты ошибок — всё это правила в `.golangci.yml`.
- Архитектура и решения: `docs/architecture.md`
- **Наблюдения на живых данных:** `docs/local-research.md` — что реально шлёт
источник и чем это расходится с его документацией. *(Не ведём — так и пишут:
«наблюдений на живых данных не ведём».)*
- Журнал проскочивших дефектов: `docs/review-journal.md`
- **Единые точки:** идентификаторы — `internal/ident`; время — `store.Now()`;
разбор дат входного формата — один парсер в `internal/parse`; маппинг доменной
@@ -159,6 +206,53 @@
- **Клиент внешнего сервиса** — таймаут, протяжка `context`, поведение при
«медленно» против «упало», ретраи и их граница.
## Прецеденты
*Воспроизведённые случаи этого проекта: класс — симптом — чем воспроизведён —
чем закончилось. Прецедентов нет — так и пишут: «прецедентов не накоплено».*
- **Вырожденный ответ библиотеки, неотличимый от штатного.** Симптом: пересборка
докладывала «журнал разобран целиком», а часть записей не доезжала. Причина:
контрольная точка журнала СУБД под занятой блокировкой возвращала `-1` вместо
пары чисел, и сравнение `-1 >= -1` читалось как успех — 1492 тика из 5502.
Воспроизведено экспериментом на стенде (`tmp/probe-checkpoint/`), из
документации драйвера не следовало. Закончилось: явная проверка вырожденного
значения + вопрос 8 в эксплуатационном проходе.
- **Канонизация внутри транзакции.** Симптом: соседняя доставка получала «база
занята». Причина: пересборка держала блокировку записи 5.019 с при таймауте
занятости 5000 мс — канонизация и хеширование шли внутри транзакции.
Воспроизведено замером на копии БД. Закончилось: вынос канонизации из
транзакции; числа — в раздел `## Прод и поток`.
- **Пик памяти на распаковке.** Симптом: контейнер убивался по памяти на крупных
доставках. Причина: сжатая запись распаковывалась целиком, пик 768 МиБ на теле
40 МБ. Воспроизведено прогоном на реальном пакете из `testdata`. Закончилось:
потоковая обработка; факт «запись — сжатый BLOB» вынесен в бриф, потому что без
него замер не читается как аномалия.
## Типовые ложноположительные
*Находки, которые здесь выглядят убедительно и всегда неверны. Пусто — так и
пишут.*
- «Значения из входа надо нормализовать перед записью» — инвариант требует
дословного хранения; нормализация тут порча, а не улучшение.
- «Приём должен отвечать ошибкой на непонятое содержимое» — инвариант «сохранили
— значит приняли»; отправитель доставку не повторит.
- «Порядок ключей в JSON стабилен, канонизация избыточна» — наблюдение на живых
данных говорит обратное.
- «Вынести в конфиг» про значения, заданные внешним форматом.
## Вопросы к проходам
*Производные от журнала: вопрос конкретному проходу плюс ссылка на запись, из
которой он взялся. Пусто — так и пишут.*
- `ops`: что произойдёт при откате бинаря поверх уже накатившейся миграции —
стартует ли старая версия молча (журнал, запись 2026-05-12).
- `adversary`: имена файлов внутри архива внешнего экспорта мы не формировали —
проверь путь от имени в архиве до операции с файловой системой (журнал, запись
2026-06-03).
## Триггеры
- `deep`: миграция в `internal/store/migrations/`, новый пакет `internal/*`,
@@ -170,6 +264,10 @@
## Недоступно проверке
### Не проверит ни один проход
*Принципиальные границы. По факту промаха не пересматриваются.*
- Поведение внешнего приложения-источника на следующем его обновлении.
- Что реально лежит в системе-источнике: сверить можно только ручным экспортом,
а он делается раз в 2–3 месяца.
@@ -177,3 +275,15 @@
нагрузки.
- Завязка внешних потребителей на текущую форму ответа.
- Суждение «этой функциональности не должно существовать».
### Перестали проверять сознательно
*Что, когда, почему и где записано. Пересматривается первым, как только что-то
проскочило. Пусто — так и пишут: «сознательно ничего не отключали».*
- **Поимённая сверка со стайлгайдами языка** — с 2026-05, вместе с упразднением
прохода про идиоматичность (журнал ревью, запись 2026-05-04). Класс обратимый:
портит форму кода, не данные.
- **Правило линтера про длину функции** — снято 2026-06-18: ложных срабатываний
больше трети (журнал, там же). Вернуть, если проскочит дефект «функция делает
три вещи».