houseplan-card/docs/reviews/SPEC-REVIEW-225-r2.md

SPEC-REVIEW — issue #225, цикл r2/2

• Issue: https://github.com/Matysh/houseplan-card/issues/225
• ТЗ: тело issue #225 (лёгкий трек small, файл в docs/specs/ не создаётся, §5 PROCESS.md)
• Трек: small — лимит циклов ревью ТЗ = 2 (§4 PROCESS.md); это последний допустимый цикл
• Ревьюер: Claude (роль «Ревьюер ТЗ», отдельная сессия от автора)
• Вердикт: зелёный · цикл r2/2 · High: 0 · Medium: 0

Скоуп проверки (по дельте, §2.10 PROCESS.md)

Раунд r1 закончился жёлтым вердиктом с одной Medium-находкой в скоупе (M1: третий пример в AC4 требовал None, хотя по собственному контракту ТЗ («query не участвует в резолвинге») корректная реализация обязана вернуть валидный путь — критерий был недоказуем без нарушения контракта). Автор внёс правку только в тело issue; ветка issue/225-* не создавалась, код не менялся — подтверждено: git log --oneline после коммита be0277f (докладной документ r1) новых коммитов нет.

SHA/версия r1 не названы в вердикте явно — это найдено при подготовке этого раунда, как и предупреждает §2.10: комментарий-вердикт r1 (2026-08-20T18:14:47Z) не указывает, к какой версии тела issue он относится. Восстановлено косвенно: r1 дословно цитирует AC4 в том виде, в каком он был опубликован комментарием автора 2026-08-20T18:08:06Z («ТЗ написано в теле issue... Отправляю на ревью ТЗ»), и это совпадает с текущей историей правок issue (правки по r1 внесены следующим комментарием, 2026-08-20T18:18:05Z, уже после вердикта). Коммит be0277f5f5ca7595b15f2c64d3b79bd031ed4130 — тот, что добавил документ SPEC-REVIEW-225-r1.md, и остаётся HEAD dev на момент этого раунда: код и остальные файлы репозитория с r1 не менялись, дельта целиком в тексте issue.

Дельта r1 → r2 (сравнение цитат из документа r1 с текущим телом issue):

1. Таблица AC: пример …/files/m1/doc.pdf?x=/../../etc убран из AC4 и перенесён в новый AC4a с обратным ожиданием (резолвится в валидный путь), плюс добавлен второй пример с #fragment.
2. AC1 расширен веткой plans/_/... с query (/houseplan_files/plans/f1.svg?v=1 → <root>/plans/f1.svg).
3. Блок «Принято предположительно» получил пункты 3 и 4, документирующие ревизию r2.

Контракт поведения, AC2/AC3/AC5/AC6/AC7, план автотестов, мутационный гейт, риски, откат, release-артефакты — текст не менялся. По правилу «дельта, а не задача целиком» они не разбираются заново; закрытие round r1 показано ниже, а неизменное — в разделе «Унаследовано».

Дельта локальна (правка двух строк таблицы + один пункт в предположениях, без смены контракта, без ребейза, без новой подсистемы) — полный разбор не требуется по критериям §2.10.

Как проверялось

• Получено тело issue #225 (текущая версия) и все 5 комментариев через gh issue view 225 --json body,comments,labels.
• Восстановлен текст AC4 на момент r1 из цитат в docs/reviews/SPEC-REVIEW-225-r1.md (коммит be0277f) и построчно сверен с текущим AC4/AC4a.
• Перепроверена сама правка на непротиворечивость контракту:
  • AC4a, пример 1 (…/files/m1/doc.pdf?x=/../../etc): по контракту путь берётся из urlsplit(url).path; query — это x=/../../etc, в .path не попадает. .path = .../files/m1/doc.pdf, без единой точки ... Хвост после префикса — m1/doc.pdf, ровно 2 сегмента, оба проходят sanitize_* без изменений → ожидание «резолвится в валидный <root>/files/m1/doc.pdf» совпадает с тем, что контракт обязан выдать. Совпадает и с уже проверенным в r1 расчётом (там это был пример 3 AC4, только с противоположным, ошибочным ожиданием None).
  • AC4a, пример 2 (…/files/m1/doc.pdf#/../..): urlsplit кладёт /../.. во fragment, .path не меняется. По контракту fragment тоже не участвует в резолвинге — то же ожидание, тот же вывод: валидный путь. Новый пример, ранее не разбирался; логика идентична предыдущему.
  • AC4 (оставшиеся 3 примера): не изменились, построчно уже проверены в r1 без ошибок (все три сегментированы так, что дают None уже сегодняшней проверкой числа сегментов/наличия /, независимо от query) — сверено, что текст этих трёх строк в issue не редактировался.
  • AC1, добавленная ветка plans/_/... с query: ветка plans в _internal_path (по описанию в issue и r1: import_export.py:355) отклоняет только хвосты, содержащие /; f1.svg?v=1 после отсечения query по urlsplit даёт хвост f1.svg — один сегмент без /, сравнение sanitize_filename проходит. Ожидание AC1 (резолвится в <root>/plans/f1.svg) согласуется с контрактом, новой неоднозначности не вносит.
  • Пункты 3–4 блока «Принято предположительно»: описывают ровно произошедшую правку (перенос примера, расширение AC1) и не подменяют продуктовое решение — технические примечания к диффу, а не новое решение за пользователя.
• Проверено, что контракт поведения, AC2/AC3/AC5/AC6/AC7, план автотестов, мутационный гейт, риски и «Не в скоупе» текстуально идентичны версии, которую разобрал r1 (посимвольное сравнение с цитатами в SPEC-REVIEW-225-r1.md) — правок нет, переразбор не требуется.
• Мутационный гейт (3 id: internal-path-ignores-query, internal-path-allows-traversal, roundtrip-import-with-attachment) остался без изменений; для AC4a отдельного id не заведено — не требуется: AC4a не защищает от регрессии существующего поведения, а описывает новое ожидание, которое доказывается собственным будущим тестом на AC4a напрямую (если реализация ошибочно отклонит валидный запрос, красным станет сам тест AC4a, отдельный мутант не нужен).
• Гейты кода не запускались: этап — ревью ТЗ, реализации нет, ни один файл репозитория кроме docs/reviews/*.md не менялся с r1.

Закрытие раунда r1

Находка r1	Чем закрыта	Где это видно
M1 (Medium, в скоупе) — третий пример AC4 (…/files/m1/doc.pdf?x=/../../etc) требовал None, что противоречит контракту ТЗ («query не участвует в резолвинге»)	Пример вынесен из AC4 в новый AC4a с противоположным (корректным по контракту) ожиданием — «резолвятся в валидный <root>/files/m1/doc.pdf»; AC4 сохранил только три traversal-примера, ранее уже проверенных как корректные	Тело issue #225, раздел «Критерии приёмки»: строки AC4 (3 примера) и AC4a (2 примера); авторский комментарий 2026-08-20T18:18:05Z: «M1 закрыт... пример перенесён в новый AC4a с обратным ожиданием»

Дополнительно (не находка, инициатива автора, не требовала действия ревьюера): AC1 расширен веткой plans/_/... с query — комментарий автора сам называет это «дополнительно, не находка»; проверено выше и признано корректным.

Унаследовано из r1

Документ: docs/reviews/SPEC-REVIEW-225-r1.md, SHA be0277f5f5ca7595b15f2c64d3b79bd031ed4130 (коммит, добавивший документ; версия текста issue на тот момент — комментарий-публикация ТЗ от 2026-08-20T18:08:06Z, до правок по r1).

Принято без повторной проверки в этом раунде, так как дельта их не касается:

• Диагноз бага (_internal_path режет URL по / без отделения query, _looks_internal смотрит только на префикс, _SAFE_NAME_RE ломает сравнение на ?/=) — проверен чтением кода в r1, текст issue не менялся.
• Применимость лёгкого трека small (сложность ≤3, одна поверхность, без миграции/compatibility/UX-контракта/перф/touch) — критерии не пересматривались.
• AC2, AC3, AC5, AC6, AC7 — текст не менялся, однозначны и доказуемы по выводам r1.
• AC1 в части, не связанной с добавленной веткой plans (резолвинг files/... с query, CONTENT_URL-префиксом, #fragment, ?v=1#page=2) — не менялась, проверена в r1.
• Риск смены классификации content_manifest (external → internal) и сохранение совместимости через identity() (:1034-1039, storage не в ключе сравнения) — код не менялся, проверка r1 остаётся в силе.
• Идемпотентность plan_only-проверки (:704, AC7) — не затронута.
• Решение не брать текст ошибки invalid_content в скоуп — продуктовое решение владельца на этапе аналитики, не пересматривается ревью ТЗ.
• Откат и release-артефакты (User-Visible: yes, оба changelog) — текст не менялся.
• Мутационный гейт (3 id) — текст не менялся, соответствие AC не пересматривалось за исключением явной проверки, что деление AC4/AC4a не требует нового id (см. «Как проверялось»).

Находки

Нет находок в этом раунде (High: 0, Medium: 0, Low: 0). Единственная Medium-находка r1 (M1) закрыта корректно, новых противоречий правка не вносит.

Что проверено и корректно

• M1 закрыт по существу, а не переименован: новое AC4a требует ровно то поведение, которое обязан выдать заявленный контракт («query и fragment не участвуют в резолвинге»), и оба его примера (?x=/../../etc и #/../..) построчно пересчитаны и дают валидный путь, а не None.
• AC4 после удаления спорного примера остался внутренне согласован: три оставшихся примера — реальные traversal-случаи в самом пути, а не в query/fragment, и ожидание None для них верно уже сегодняшней логикой подсчёта сегментов.
• Расширение AC1 веткой plans/_/...?v=... не создаёт скрытого нового контракта — это то же отделение query той же функцией, применённое ко второй ветке, которую r1 отдельно отметил как непроверенную (и намеренно не поднял до находки).
• Дельта не расширяет скоуп и не меняет контракт поведения, поэтому ограниченный по объёму раунд корректен по критериям §2.10 (локальность правки, отсутствие ребейза, отсутствие новой подсистемы).
• Лимит циклов лёгкого трека (2) не превышен: это второй и последний цикл, вердикт зелёный — задача может двигаться в «Готово к разработке».

Чего не проверял

• Гейты кода (npx tsc --noEmit, npm test, npm run build, python -m pytest tests_backend -q) — не запускались: реализации ещё нет, ни один продуктовый файл не менялся между r1 и r2, только текст issue.
• Не пересматривался диагноз бага и код _internal_path / _looks_internal / content_manifest / _content_state — не изменился с r1, где уже проверен чтением построчно.
• Не проверялась ветка plans в реальном коде на предмет иных, не описанных в ТЗ побочных эффектов — вне зоны этого ревью (ревью ТЗ судит текст, а не реализацию, которой ещё нет).
• Percent-encoding в именах файлов и нормализация существующих конфигов — по-прежнему намеренно вне скоупа issue, не проверялись.