transcriber/openspec/changes/archive/2026-08-11-fix-http-handler-tests/review/triage.md

Триаж ревью: 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, .. результат всегда <uuid><ext> внутри каталога хранения (оракул: прогон 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.