# Триаж ревью: `fix-http-handler-tests` ## Сводка - **Размер:** малое. **Сложность:** знакомое. **Метка:** `small`. Обоснование разметки (`review-scope`): изменение трогает один тестовый файл и одну строку конфига линтера, поведение сервиса не меняется, отрицательный тест метки (миграция, формат файла на диске, публичный контракт API, имя ключа) не срабатывает — контракт HTTP API спекой **фиксируется**, а не меняется. - **Режим прогона:** по графу. Дизайн — одна стадия (`specs`), код — `autotests` → `specs` + `code` → триаж. - **Сигнал о заниженной метке:** пришёл от `review-code` — возражений нет, метку `small` проход счёл обоснованной. `review-basics` не запускался (своих тем у проекта нет), второго независимого подтверждения метки нет. - **Состояние гейта (проверено мной на этом прогоне):** - `go test ./...` — **зелёный** (`ok internal/controller/http 0.013s`); это и есть цель изменения; - `golangci-lint run` — **4 замечания, ровно объявленный долг** (`speechkit.go:55`, `main.go:124`, `worker.go:51`, `service/transcribe.go:394`). Ни одного нового, в том числе после снятия исключения `errcheck` для `_test.go`; - критерий приёмки «не зависит от `ffprobe`» подтверждён: собранный `go test -c` бинарь проходит под `env -i PATH=<пустой каталог>`; - критерий «`os.Chdir` не остаётся» подтверждён: `grep -rn 'os.Chdir' internal/` пуст. - Итог: гейт красный **только унаследованным долгом**; новых красных шагов нет. ### План разметки с исходом по каждой теме | тема | дом | глубина | закрывает | исход | |---|---|---|---|---| | requirements | `openspec/changes/fix-http-handler-tests/specs/intake/spec.md` | сверка | `specs` | **закрыта**, 3 находки (потолок 3/3 сработал), 2 из них починены и мной перепроверены мутацией | | autotests | `CLAUDE.md` § Гейт | — | `autotests` | **закрыта**, 0 находок; отчёт о гейте + 1 строка в границы покрытия. О своём потолке проход не сообщил | | conventions | `docs/conventions/README.md` (на `small` — только README) | сверка | `code` | **закрыта**, 1 находка (потолок 1/2), **не починена** — единственный блокер ниже | | architecture | `CLAUDE.md` § Инварианты | сверка | `code` | **закрыта**, 0 находок (потолок инвариантов 0/1) | | security | `CLAUDE.md` § Инварианты | сверка | `code` | **закрыта**, 0 находок — но см. предупреждение ниже | | operations | `CLAUDE.md` § Инварианты | сверка | `code` | **закрыта**, 0 находок | Тем без отчёта нет. Тем без дома нет. **Предупреждение по теме `security`.** «0 находок» здесь не значит «чисто». Нарушение `critical`-инварианта «содержимое записи остаётся приватным» (`internal/service/transcribe.go:107` пишет `"file_name", fileName` — имя файла пользователя — в журнал) найдено **на стадии дизайна** и **сознательно отложено решением человека на чекпоинте**, поэтому проход кода вернул пустой итог: находка уже известна и вынесена. Она в урожае, не в блокерах, и это решение человека, а не моё. Тот же путь проходят записи из Telegram. ### Арифметика - **На входе:** 14 позиций — 7 именованных находок (`specs` 3, `code` 4), 3 названные ниже потолка, 3 отложенные решением человека, 1 замечание о непокрытом конвейере от `autotests`. - **После дедупликации, добычи оракулов и отсева:** **2** позиции, требующие действия (1 блокер + 1 развилка). Остальное — в урожай, гипотезы и promote, ничего не выброшено молча. - Починенное проверено мной независимо: обе `major`-находки `specs` закрыты, мутации их роняют (оракулы ниже). --- ## Блокирует мердж ### `CLAUDE.md` продолжает объявлять долгом отказ, которого больше нет, — и следующий настоящий отказ тестов приёма спишут на него молча - Файл: `CLAUDE.md:96-101`; сопутствующее: `tasks/BACKLOG.md:23`, `tasks/items/http-handler-tests-never-green.md` - Severity: major - Confidence: high - Действие: **инлайн** - Оракул (мой, на этом прогоне): - дословно `CLAUDE.md:98-101`: «`go test ./...` падает в `internal/controller/http`: тесты требуют `testdata/sample.m4a`, которого в репозитории нет и не было… Заведено задачей `http-handler-tests-never-green`»; - `go test ./...` → `ok git.vakhrushev.me/av/transcriber/internal/controller/http 0.013s`; - дословно `CLAUDE.md` § Работа: «Два объявленных долга из раздела „Гейт“ сломанным состоянием **не** считаются, пока их не закрыли задачами». - Последствие: после мерджа проект будет письменно утверждать, что красный `go test` в `internal/controller/http` — это норма. Ровно этот механизм записан в журнале дефектов (`docs/review.md`, запись 2026-08-10): «тест, который никогда не проходил, обнуляет сигнал всего пакета: настоящий отказ в нём становится неотличим от привычного шума». Изменение восстанавливает сигнал в коде и оставляет его выключенным в документе, по которому судят «сломано ли». Отказ будет молчаливым: никто не станет разбираться в отказе, объявленном известным. - Предложение: убрать первый из двух известных отказов в `CLAUDE.md` § Гейт (остаётся только `golangci-lint`), закрыть задачу штатным путём каталога (`tasks.py close` — реализованные в `REJECTED.md` не идут, у них есть коммит), снять строку из `tasks/BACKLOG.md`. Задача `tasks.md` этого шага не содержит — добавить его в чек-лист. - Найдено проходом: `review-code`/конвенции; оракул и провенанс — триаж. - Почему блокер, а не «стоит исправить»: `CLAUDE.md` § Работа — единственное место, где записано, что считается сломанным. Пока оно врёт, определение сделанного у следующей задачи опирается на неверный список. Правка механическая, путь документирован, цена — минуты. **Замечание о разделении обязанностей.** Общая согласованность документов между собой и с кодом — работа скилла `av-dev-docs:healthcheck`, а не ревью (`CLAUDE.md` § Гейт говорит это прямо). Здесь исключение узкое и обосновано: речь не о дрейфе документации вообще, а о том, что **это самое изменение** закрывает долг, поимённо перечисленный в `CLAUDE.md`, и без правки определение «сломано» становится ложным в момент мерджа. --- ## Стоит исправить сейчас ### Переименование маршрута `POST /api/audio` в `main.go` уедет зелёным: тест ходит по своей копии регистрации - Файл: `main.go:198-202` против `internal/controller/http/transcribe_test.go:140-144` - Severity: minor - Confidence: high - Действие: **развилка** - Оракул (мой, мутация в копии дерева, `/tmp/.../scratchpad/mut`): `api.POST("/audio", …)` → `api.POST("/upload", …)` в `main.go`; `go build ./...` проходит, `go test ./internal/controller/http/ -count=1` → `ok … 0.017s`. Тест зелёный при сломанном контракте. Для сравнения — то, что теперь ловится: переименование тега `json:"job_id"` → `json:"jobId"` роняет `TestCreateTranscribeJob_Success` («does not contain "job_id"»), удаление `s.jobRepo.Create(job)` роняет его же. - Последствие: имена полей ответа изменение защитило (это и была починенная `major`-находка), а путь маршрута — часть того же публичного контракта HTTP API, объявленного в `CLAUDE.md` **необратимым**, — остался незащищённым. Внешняя программа сломается молча, машина промолчит. Вероятность невысока (мутация видна в диффе `main.go`), но класс тот же самый. - Развилка для человека — правка трогает продуктовый код, а `design.md` объявил это Non-Goal («код `internal/service` и `internal/controller/http` не правится»): 1. **Вынести регистрацию маршрутов** в экспортируемую функцию пакета `internal/controller/http` (например, `RegisterRoutes(r gin.IRouter, h *TranscribeHandler)`), звать её из `main.go` и из сборки теста. Цена: ~10 строк продуктового кода, выход за объявленный Non-Goal задачи, зато контракт маршрута закрыт машиной. 2. **Оставить как есть**, записать в урожай отдельной задачей. Цена: контракт маршрута остаётся на человеке до следующей задачи, которая и так трогает `main.go` (например, `json-api-for-spa`). 3. **Оставить как есть и не заводить задачу**, приняв, что маршрут проверяется глазами. Цена: класс дефекта известен, но не записан нигде — при следующем промахе оракула не будет. - Найдено проходом: `review-specs` (там — `minor`, «цена исправления выше цены дефекта»); оракул мутацией — триаж. Второго пункта в этой секции нет: остальное либо починено и перепроверено, либо не имеет цены, оправдывающей правку (см. «Отсеяно» и «Урожай»). --- ## Гипотезы без доказательства ### Понижено оракулом: «зелёный прогон печатает ERROR-строки в stderr» — заявленного последствия нет - Исходно: `review-code`/техника, `minor`. Часть починена (логгер сборки теста уведён в `io.Discard`), остаток — `log.Printf("Err: %v", err)` в `internal/controller/http/transcribe.go:45`. - Мой оракул: `go test ./internal/controller/http/ -count=1 2>&1 | grep -c 'Err:'` → **0**. `go test` буферизует вывод пакета и на успехе его не печатает. Строка видна только под `-v` или при прямом запуске собранного бинаря — то есть на зелёном `task gate` признак ничем не размывается. - Итог: последствие в формулировке находки не воспроизводится, находка снята. Остаётся факт «продуктовый код пишет мимо `slog`» — он **уже записан** в `docs/conventions/logging.md:161` как расхождение, новой находкой не является, ушёл в promote (механизация правила). ### Понижено: «база `:memory:` без ограничения пула» - Исходно: `review-code`/техника, `minor`, `Confidence: low`, «сегодня не срабатывает». Оракула, показывающего отказ, нет ни у прохода, ни у меня. Починка (`db.SetMaxOpenConns(1)`, одна строка, с комментарием почему) уже внесена, безвредна и оставлена как есть. Действия не требует. ### Не понижалось, но перепроверено: две `major`-находки `specs` Обе были заявлены с оракулом и обе починены. Я не поверил на слово и повторил мутации в копии дерева — см. оракул в секции «Стоит исправить сейчас». Обе мутации теперь роняют тест. Находки закрыты. --- ## Отсеяно - **Мёртвая строка `router.MaxMultipartMemory` в сборке теста** (`transcribe_test.go:138`, названо `review-code` ниже потолка). Проверено: гиновский `MaxMultipartMemory` читается только в `c.FormFile`/`c.MultipartForm`, а обработчик зовёт `c.Request.FormFile`, который использует собственный `defaultMaxMemory` = 32 MiB — то же число. Поведение не меняется ни в тесте, ни в `main.go`, стоимость следующего изменения не растёт, записанной конвенции нет. Выброшено, а не смягчено. - **Проектных ложноположительных (`docs/review.md` → «Типовые ложноположительные», 4 пункта) в выводах не оказалось ни одного.** Ближайший сосед — «Файлы и объекты не удаляются, диск растёт» — к отложенной находке про файл-сироту **не относится**: та запись про отсутствие срока хранения, а находка — про файл, на который нет ни задачи, ни записи в учёте. По этому пункту ничего не отсеяно. --- ## Promote candidates 1. **Имена полей публичного ответа судятся по сырому JSON, а не по разобранной структуре.** Приём в разобранную структуру переименовывает тег вместе с ожиданием, и проверка теряет способность упасть — это ровно та `major`, что нашлась здесь. Приём (`map[string]json.RawMessage` + `assert.Contains`) сработал дважды в одном файле. Дома у правила пока нет: в `docs/conventions/` файла про тесты нет. Кандидат в новый раздел конвенций. 2. **Стандартный `log` в продуктовом коде — механизировать, а не помнить.** `docs/conventions/logging.md` уже пишет «**Механизировано:** ничего. Ни `sloglint`, ни `forbidigo` в `.golangci.yml` не заведено» и поимённо называет расхождение `internal/controller/http/transcribe.go`. Правило записано и механизируемо, значит это не находка ревью, а `Promote candidate`: `forbidigo` на `log.` в `.golangci.yml`. 3. **Регистрация маршрутов — одна на процесс и на тест** (производное от развилки выше; актуально, если человек выберет вариант 2 или 3). --- ## Урожай Формулировка → оракул → провенанс. Ничего из этого не чинится в этом изменении. 1. **Приём пишет имя файла пользователя в журнал — нарушение `critical`-инварианта.** `internal/service/transcribe.go:107`: `s.logger.Info("Creating transcribe job", "file_id", …, "file_name", fileName, …)`. Оракул: дословно `CLAUDE.md` § Инварианты — «Содержимое записи остаётся приватным. Текст расшифровки, **имя файла пользователя** и его сообщение в лог не пишутся — только длина и идентификаторы. Нарушение необратимо: строки уже уехали в журнал контейнера. **critical**». Плюс вопрос темы `security` в `docs/review.md`. Путь общий с Telegram, то есть касается живых записей. Провенанс: ревью дизайна; **отложено решением человека на чекпоинте**, записано в `design.md` § Risks. Спека `intake` нормирует только хранилище и о журнале молчит намеренно. 2. **Отказ чтения метаданных оставляет файл на диске без уборки.** `internal/service/transcribe.go:129-133` (ветка `metaviewer.GetInfo`) против `152-157` (ветка `fileRepo.Create`, где `os.Remove` есть). Оракул: чтение кода; ни задачи, ни записи в учёте под такой файл нет — сопоставить его не с чем. Провенанс: ревью дизайна; отложено решением человека (правка трогает три ветки отказа и меняет поведение на диске). 3. **Настоящий `ffprobe` после этой правки не проверяется ничем.** У `internal/adapter/metaviewer/ffmpeg` своего теста нет; разбор вывода `ffprobe` не покрыт. Оракул: `go test ./...` → `? …/adapter/metaviewer/ffmpeg [no test files]`. Провенанс: `design.md` § Risks, названо прямо. Формально покрытие не потеряно — прежний тест проверял отказ `ffprobe` и выдавал его за проверку приёма. 4. **Конвейер задач не покрыт ни одним тестом.** `FindAndRunConversionJob`, `FindAndRunTranscribeJob`, `FindAndRunTranscribeCheckJob`, `internal/controller/worker`. Три воркера читают общий `*sql.DB`, теста с параллельным доступом нет. Оракул: `go test ./...` → `[no test files]` у `internal/service` и `internal/controller/worker`. Провенанс: `autotests`, вне scope задачи. Совпадает со свойством, добавленным в `docs/review.md` («изменённое место покрыто хоть одним **проходящим** тестом») и с вопросом темы `autotests`. 5. **Опечатка `transcibe` в тексте ошибки теперь закреплена проверкой.** `internal/controller/http/transcribe.go:46` и `transcribe_test.go:379` — `"Failed to create transcibe job"`. Оракул: обе строки дословно. Исправление меняет тело ответа, то есть **публичный контракт HTTP API**, объявленный в `CLAUDE.md` необратимым, — значит спрашивается у человека и не делается походя. Провенанс: `review-specs`, ниже потолка. Действия сейчас не требует: статус-кво зафиксирован сознательно. 6. **Требование «имя отправителя не попадает в хранилище» проверяется только благополучными именами.** Проверено мной попутно (вопрос темы `security` из `docs/review.md`: «не строится ли путь на диске из значения, пришедшего снаружи»): обхода каталога нет **по построению** — `filepath.Ext` не пересекает разделитель пути, и на входах `../../../etc/passwd.m4a`, `evil.m4a/../../x`, `/etc/passwd`, `a.b/../../c`, `..` результат всегда `` внутри каталога хранения (оракул: прогон `filepath.Ext` + `filepath.Join` на этих восьми входах, вывод снят на этом прогоне). Дефекта нет; недостающее — сторожевой случай, который зафиксирует это свойство. Провенанс: триаж. --- ## Границы покрытия ### План: темы, дома, глубины Полностью воспроизведён в сводке выше вместе с исходом каждой темы. Тем без дома нет, тем без отчёта нет. Дома тем `architecture`, `security` и `operations` — раздел «Инварианты» `CLAUDE.md`, глубина «сверка». ### Какие проходы запускались - Ревью дизайна: `review-specs`, одна стадия, метка `small`. - Ревью кода: `review-autotests` → `review-specs` + `review-code` → триаж. Режим — по графу, метка `small`. - **Не запускался `review-basics`**: своих тем у проекта нет — так сказал план. Следствие названо ниже, в строке про корректор метки. ### Сработавшие потолки - `review-specs` (код): **3 из 3**, потолок сработал. Ниже среза остались названными: литералы сообщений об ошибке, включая опечатку `transcibe`; расхождение сценария «Поля с записью нет» с тем, что делал тест (починено). - `review-code`: **техника 3/3 — сработал**; **конвенции 1/2**; **инварианты 0/1**. Ниже среза осталась названной мёртвая строка `router.MaxMultipartMemory`. - `review-autotests`: **о своём потолке не сообщил**. Это находка о прогоне: по контракту проход обязан сказать, сколько нашёл, каков был потолок и что осталось за срезом. Судить, есть ли за его срезом что-то ещё, нечем. - Триаж: потолок 3/4 не исчерпан (1 блокер, 1 в «стоит исправить»). Из-за потолка **ничего не выброшено**. ### Что каждый запущенный проход не мог проверить в принципе Ниже — по отчётам проходов; charter'ы агентов мне дословно не подавались, поэтому это пересказ их собственных заявлений, а не цитата устава. - `review-autotests`: судит наличие и зелёность проверок, а не правильность нормы, которую они проверяют. Прогнал `go test` 5× подряд и с `-race` — флаки не обнаружен; это отсутствие сигнала на пяти прогонах, а не доказательство детерминированности. - `review-specs`: судит соответствие кода дельта-спеке; правильность самой спеки вне его входа. Приём из Telegram спекой `intake` не описан сознательно — значит, и не проверялся. - `review-code`: на метке `small` конвенции сверялись только с `docs/conventions/README.md`, а `architecture`/`security`/`operations` — только с записанными инвариантами `CLAUDE.md`. - Триаж: **ничего нового не находит по определению**. Я не читаю код в поисках дефектов, я работаю с чужими выводами. Пропуск любого прохода — мой пропуск тоже; всё, что я могу, — назвать его поимённо, что и сделано выше. ### Что осталось целиком на человеке Из `docs/review.md` → «Недоступно проверке», **двумя отдельными списками, как записано**: **Не проверит ни один проход:** - `operations`: поведение внешних сервисов под нагрузкой и на границах — SpeechKit и Object Storage поднять в тесте нечем; - `operations`: реальный профиль нагрузки. Проект работает на единицах записей в день, и утверждения о росте остаются условиями, а не замерами; - `security`: стойкость `ffmpeg` к вредоносному входу — разбор чужого формата отдан внешней программе, и она вне нашей границы. **Перестали проверять сознательно:** - по записи в `docs/review.md` — «Ничего не отключали: проверять пока и не начинали». **Однако этим изменением список пополняется фактически**: приём перестал проверяться сквозь настоящий `ffprobe` (решение записано в `design.md` § Risks и обосновано — прежняя проверка проверяла отказ внешней программы и выдавала его за проверку приёма). Раздел `docs/review.md` этого ещё не знает; строку туда добавляет синк документации, не я. Сверх записанного в проекте — общее, чего не видит ни один прогон: история инцидентов, поведение под реальным потоком, поведение внешних систем в их версиях, завязка потребителей на текущее поведение и вопрос «а нужна ли эта функциональность вообще». ### Каких документов проекта не хватило Строкой на каждый, с причиной — деградация поразрядная: - `docs/conventions/` **про тесты файла нет**: конвенции покрывают конфиг, базу, ошибки, журнал и веб-UI. Изменение целиком про тесты, и сверять его форму было не с чем — отсюда promote-кандидат №1, а не находка. - `docs/adr/` **пуст**: только `README.md` и `template.md`, ни одного решения. См. обязательную строку 1 ниже. - `docs/research/` — только `README.md`, записанных замеров нет. См. строку 2. - `docs/review.md` § «Как настроен конвейер» **устарел с этого прогона**: там написано «Конвейера ревью в проекте пока нет: плагин не подключён, ни одного прогона не было». Прогон был — этот. Отсев ложноположительных при этом **не был слепым**: раздел «Типовые ложноположительные» заполнен наперёд, четыре пункта, и я им пользовался. - `docs/security.md` в проекте **есть**, но на метке `small` план отправил тему `security` в инварианты `CLAUDE.md`, и как дом темы `security.md` не открывался. См. строку 5 ниже. ### Четыре строки, которых не принесёт ни один проход 1. **Решения проекта не сверялись.** `docs/adr/*` — процессный документ, прогон его не открывает. Расхождение изменения с записанным решением ловит сверка документации (скилл `av-dev-docs:healthcheck`), а не ревью. Здесь у этого есть и вторая сторона: каталог решений пуст, сверять было бы не с чем. 2. **Записанные наблюдения проекта не использовались.** `docs/research/` — тоже процессный. Всякое число в этом отчёте снято командой на этом прогоне; чисел без приложенной команды в отчёте нет. 3. **Поимённая сверка с руководствами по стилю Go не задавалась ни одним проходом.** Различение «идиоматично против просто распространено» на этом прогоне не спрашивал никто. 4. **Альтернативной реализации, с которой можно сдиффить решения, у конвейера нет.** Проход независимой реализации снят по стоимости, а не по замеру. «Не знаю, чего не знаю» здесь никто не достаёт: например, вопрос «а верна ли сама форма подстановки в сборке теста» не задал никто, кроме автора дизайна. ### Пятая строка — следствие метки `small` Темы `security`, `operations` и `architecture` сверялись **только с записанными инвариантами `CLAUDE.md`**; дома этих тем (`docs/security.md`, `docs/architecture.md`, `docs/conventions/logging.md` как источник норм журнала) не открывались. Свойство, которого нет в семи пунктах инвариантов, на этом прогоне не проверил никто. ### Отдельно про корректор метки `review-code` метку `small` подтвердил, сигнала о занижении не подал. `review-basics` **не запускался**, поэтому второго, независимого от `review-code` подтверждения метки нет. Согласия двух проходов здесь не было бы и при запуске: несколько агентов — один источник, высказавшийся несколько раз; совпадение подняло бы приоритет, но не `confidence`.