jellybit/openspec/changes/large-release-recognition/specs/recognition/spec.md

## MODIFIED Requirements

### Requirement: Разбор сигналов LLM в структурированный план

Система SHALL передавать LLM недоверенные сигналы (имя торрента, дерево файлов с
размерами, текстовый контекст и накопленные подсказки, пред-парс) и получать
структурированный план в схеме: `type` (`movie`|`series`), `title`,
`original_title`, `year`, `provider_hint`, `files[]` и `confidence`. Каждый
элемент `files[]` SHALL адресовать файл раздачи номером строки из напечатанного
системой списка файлов, а не копией пути, и нести `role`
(`main`|`episode`|`subtitle`|`extra`|`sample`|`ignore`) и, для сериала,
per-file `season`/`episode` (отдельного скалярного `season` быть SHALL NOT — так
выражаются мультисезонные паки и спецвыпуски). Путь файла (`src`) SHALL
подставлять сама система резолвом номера по своему списку. Ответ, где элемент
`files[]` несёт путь вместо номера, система SHALL принимать как запасной формат,
проверяя совпадение пути с реальным файлом торрента. Элемент, несущий и номер, и
путь, система SHALL резолвить по номеру; несовпадение присланного пути с
резолвом номера SHALL давать причину ухода в `review` (сигнал сдвига адресации),
а не молчаливое затирание.

Негодный элемент `files[]` — номер вне диапазона списка, повторная адресация уже
адресованного файла, отсутствие и номера, и пути — система SHALL отбрасывать с
причиной ухода в `review`, сохраняя остальной план; при повторной адресации в
плане SHALL оставаться первый элемент. Отбраковка отдельных элементов SHALL NOT
считаться ошибкой разбора и SHALL NOT порождать повторный запрос к модели. План,
в котором после отбраковки не осталось ни одного файла, система SHALL считать
неразобранным.

Порядок списка файлов SHALL быть свойством самого распознавания, а не
дисциплиной вызывающего: распознавание SHALL приводить полученный список к
детерминированному порядку само, печатать промпт и резолвить номера по одному и
тому же упорядоченному списку. Повторное распознавание той же раздачи SHALL
давать ту же нумерацию.

План MAY дополнительно нести опциональное скалярное поле `director` (режиссёр).
Это поле НЕ требуется от LLM и НЕ участвует в структурной валидации или гейте
авто-раскладки; его заполняют подтверждённый матч метабазы (авто) или закреплённый
в ревью выбранный источник (через override, см. `metadata-match`/`review`) как
недоверенное косметическое значение для вывода отображаемого имени. Как недоверенное
человекочитаемое поле, `director` SHALL NOT входить в plan-санитайзинг (он чистит
`title`/`original_title`/`provider_hint`); очистка режиссёра применяется при рендере
имени. Пустой `director` SHALL быть штатным (режиссёр неизвестен).

#### Scenario: План сериала с per-file нумерацией

- **GIVEN** сезон-пак из 10 видеофайлов
- **WHEN** LLM возвращает план
- **THEN** `type` = `series`, а каждый видеофайл несёт свои `season`/`episode`

#### Scenario: Номер файла резолвится в путь

- **GIVEN** список из 180 файлов, напечатанный в промпте
- **WHEN** модель возвращает элемент плана с номером 13
- **THEN** система подставляет в `src` путь тринадцатого файла своего списка

#### Scenario: Номер вне диапазона отбрасывает элемент, а не план

- **GIVEN** раздача из 180 файлов и ответ модели, где один элемент несёт номер 181,
  а остальные 179 корректны
- **WHEN** план разбирается
- **THEN** негодный элемент отброшен, остальные 179 файлов остаются в плане
- **AND** задача уходит в `review` с причиной, называющей отброшенный элемент
- **AND** повторный запрос к модели не выполняется

#### Scenario: Повторная адресация одного файла

- **GIVEN** ответ модели, где два элемента адресуют один и тот же файл
- **WHEN** план разбирается
- **THEN** в плане остаётся первый элемент, второй отброшен
- **AND** задача уходит в `review` с причиной, называющей повторную адресацию

#### Scenario: Все элементы негодны — план не разобран

- **GIVEN** ответ модели, где ни один элемент `files[]` не адресует реальный файл
- **WHEN** план разбирается
- **THEN** план не принимается как валидный

#### Scenario: Путь вместо номера принимается как запасной формат

- **GIVEN** ответ модели, где элемент `files[]` несёт путь файла вместо номера
- **WHEN** план разбирается
- **THEN** разбор успешен, если путь совпадает с реальным файлом торрента
- **AND** correction-ретрай не выполняется

#### Scenario: Номер и путь одновременно — главенствует номер

- **GIVEN** элемент `files[]`, несущий и номер, и путь, которые указывают на разные файлы
- **WHEN** план разбирается
- **THEN** `src` берётся резолвом номера
- **AND** задача уходит в `review` с причиной о несовпадении присланного пути с резолвом

#### Scenario: Несуществующий src отклоняется

- **GIVEN** ответ LLM, где `files[].src` не совпадает ни с одним файлом торрента
- **WHEN** план разбирается
- **THEN** такой элемент отбрасывается с причиной, а посторонний путь в план не попадает

#### Scenario: Нумерация не зависит от вызывающего

- **GIVEN** два вызова распознавания одной раздачи, получившие список файлов в разном порядке
- **WHEN** собирается промпт
- **THEN** напечатанная нумерация в обоих вызовах одинакова

#### Scenario: Режиссёр не требуется от LLM и не влияет на гейт

- **GIVEN** ответ LLM без поля `director`
- **WHEN** план разбирается и оценивается
- **THEN** разбор успешен, `director` пуст
- **AND** отсутствие режиссёра не влияет на структурную валидацию и решение
  auto/review

### Requirement: Провайдер LLM за абстракцией со структурированным выводом

Доступ к LLM SHALL быть за интерфейсом с выбором реализации по полю `[llm].type`
(первый тип — `openai-compat`). Система SHALL запрашивать JSON-режим
(`response_format: {"type":"json_object"}`), срезать ```-ограждения и
валидировать ответ в Go против схемы плана. При ошибке разбора система SHALL
ретраить до `[llm].max_retries`, передавая модели саму ошибку и схему. Если после
ретраев ответ не разобран, задача SHALL уходить в `review` (НЕ в `failed`) с
причиной «ответ LLM не разобран».

Повторный запрос SHALL NOT переприсылать список файлов раздачи: список назван в
первом сообщении диалога, и его номера сохраняют смысл на всех попытках. Размер
запроса SHALL NOT расти пропорционально числу попыток.

Признак завершения генерации (`finish_reason`) SHALL доходить до распознавания.
Ответ, оборванный по длине, система SHALL уводить в `review` с отдельной
причиной «ответ модели обрезан» и SHALL NOT повторять запрос ни тем же промптом,
ни его вариантом: обрыв означает, что ответ не поместился, а не что модель
ошиблась.

#### Scenario: Неразобранный ответ уходит в review

- **GIVEN** LLM, чей ответ не проходит валидацию схемы после всех ретраев
- **WHEN** завершается распознавание
- **THEN** задача переходит в `review` с причиной «ответ LLM не разобран»
- **AND** задача НЕ переходит в `failed`

#### Scenario: Повторная попытка не переприсылает список файлов

- **GIVEN** раздача из 180 файлов и ответ модели с ошибкой разбора
- **WHEN** выполняется correction-ретрай
- **THEN** список файлов раздачи повторно не печатается
- **AND** размер запроса второй попытки сопоставим с размером первой

#### Scenario: Обрыв по длине не ретраится

- **GIVEN** ответ модели с признаком обрыва генерации по длине
- **WHEN** завершается распознавание
- **THEN** задача переходит в `review` с причиной «ответ модели обрезан»
- **AND** повторных запросов к модели не выполняется

### Requirement: Модель уверенности и решение auto/review

Система SHALL раскладывать автоматически (без review) только при выполнении
ВСЕГО: (1) подтверждённый единичный сильный матч в базе (`metadata-match`) с
`provider_id`; (2) структурная валидация без предупреждений (фильм — ровно один
основной видеофайл; сериал — число серий бьётся с базой, нумерация S·E
консистентна); (3) согласованность пред-парса и LLM по типу/названию/году. Иначе
задача SHALL уходить в `review` с явной причиной. Самооценку LLM (`confidence`)
система SHALL учитывать лишь как вспомогательный сигнал, НЕ как единственный гейт.

Список причин распознавания SHALL быть неоднородным: кроме блокирующих причин он
MAY содержать информационные строки, которые показываются человеку и сохраняются
вместе с распознаванием, но авто-раскладку НЕ отменяют — такова сводка покрытия
плана (см. «Причины по нумерации серий и покрытию плана»). Поэтому решение
auto/review система SHALL считать по **блокирующим** причинам, а НЕ по длине
списка причин: непустой список сам по себе SHALL NOT означать `review`.

#### Scenario: Нет матча в базе — всегда review

- **GIVEN** план без подтверждённого матча в базе (база выключена или матча нет)
- **WHEN** принимается решение auto/review
- **THEN** задача уходит в `review`, авто-раскладка не делается

#### Scenario: Матч и чистая валидация — авто

- **GIVEN** подтверждённый единичный матч, чистая структурная валидация и
  согласованность сигналов
- **WHEN** принимается решение
- **THEN** допускается авто-раскладка (при отсутствии `force_review`)

#### Scenario: Информационная причина авто не отменяет

- **GIVEN** подтверждённый матч и чистая валидация, но покрытие плана неполно
  только за счёт файлов-спутников
- **WHEN** принимается решение auto/review
- **THEN** список причин непуст — в нём сводка покрытия
- **AND** авто-раскладка допускается

## ADDED Requirements

### Requirement: Полный список файлов раздачи в промпте

Промпт распознавания SHALL включать все файлы раздачи, а не фиксированную их
часть. Предельное число файлов и предельный размер ответа модели SHALL задаваться
настройками `[recognition].max_files` и `[recognition].max_tokens`; предел числа
файлов служит предохранителем от аномальной раздачи, а не рабочим ограничением, и
его значение по умолчанию SHALL соответствовать размеру промпта, который заведомо
принимает модель. Если список всё же усечён пределом, распознавание SHALL называть
усечение отдельной причиной ухода в `review`. Отказ модели, вызванный размером
запроса, распознавание SHALL называть причиной о размере запроса, а не текстом
провайдера.

#### Scenario: Раздача на сотни файлов показана модели целиком

- **GIVEN** раздача из 180 файлов и `max_files` = 500
- **WHEN** собирается промпт распознавания
- **THEN** в списке файлов промпта присутствуют все 180 файлов

#### Scenario: Усечение названо причиной

- **GIVEN** раздача, число файлов которой превышает `max_files`
- **WHEN** завершается распознавание
- **THEN** задача уходит в `review`, и среди причин названо усечение списка файлов

### Requirement: Причины по нумерации серий и покрытию плана компактны

Причины ухода в `review`, порождённые нумерацией серий, SHALL быть свёрнуты: на
сезон приходится не более одной причины, перечисляющей недостающие серии.

Распознавание SHALL называть покрытие плана — сколько файлов раздачи попало в
план из общего числа, — когда покрыты не все файлы. Блокировать авто-раскладку
SHALL только непокрытый видеофайл: файл, который модель не адресовала и который
по расширению является видео, означает потерянную серию или фильм. Непокрытые
файлы-спутники (субтитры, изображения, тексты, служебные файлы) SHALL
показываться в покрытии, но SHALL NOT входить в структурную валидацию и SHALL NOT
влиять на решение auto/review: модель вправе не перечислять то, что не
раскладывается.

#### Scenario: Пропуски сезона свёрнуты в одну причину

- **GIVEN** план сезона, где недостают серии E05, E07 и E11
- **WHEN** формируются причины ухода в review
- **THEN** этому сезону соответствует одна причина, перечисляющая недостающие серии

#### Scenario: Непокрытый видеофайл блокирует авто

- **GIVEN** раздача, где один видеофайл не адресован ни одним элементом плана
- **WHEN** принимается решение auto/review
- **THEN** задача уходит в `review` с причиной о непокрытом видеофайле

#### Scenario: Непокрытые файлы-спутники авто не блокируют

- **GIVEN** раздача, где не адресованы только `.nfo`, скриншоты и текстовый файл,
  а все видеофайлы покрыты, матч подтверждён и валидация чиста
- **WHEN** принимается решение auto/review
- **THEN** авто-раскладка допускается
- **AND** покрытие плана показано человеку, но причиной ухода в review не является