docs: review document for #635

Issue: #635
User-Visible: no

docs/reviews/CODE-REVIEW-635-r2.md

@@ -0,0 +1,249 @@
+# CODE-REVIEW-635-r2
+
+- **Issue:** #635 «Индекс документов ревью, уроки, правило хранения раундов»
+- **Этап:** code (PROCESS.md §2.7)
+- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4 (лимит 4)
+- **Материал:** `3e96b37656b9ce49cd56e1aa2f65ebf0808f113b` (рабочая копия репозитория была на нём; `git fetch`/`checkout` не выполнялись). Диапазон `origin/dev..HEAD` — три коммита: `898642f8` (исходная реализация #635), `4d9754a1` (публикация документа r1), `3e96b376` (правка r2).
+
+## Скоуп
+
+r1 (`CODE-REVIEW-635-r1.md`, SHA `db0f5b9b1be025fca86736f70d6aedd71d057487`) закрыл вердикт жёлтым с одним High: `parseCounts` брал первое совпадение `High:`/`Medium:` по всему тексту документа (часто — цитата чужого раунда), а `parseFindings` не знал живых форматов заголовков находок (`### Medium (в скоупе…) — …`), из-за чего у 108/990 документов колонки H/M были ненулевые, а «Находки» — пустые, и `grep form-kit docs/reviews/INDEX.md` не находил ничего вопреки собственному примеру автора.
+
+Дельта r2 — ровно один коммит `3e96b376` поверх `4d9754a1`, 4 файла: `scripts/reviews-index.mjs` (+182/-х строк), `test/reviews-index.test.mjs` (+63), `scripts/mutation-registry.mjs` (+11), `docs/reviews/INDEX.md` (пересборка). Это переписывает `parseVerdict`/`parseCounts`/`parseFindings` почти целиком и добавляет `parseFiles` — объём дельты (182 строки правки в файле, который в исходной реализации весил 159 строк) сопоставим с исходной задачей, поэтому разбор в этом раунде — полный по изменённому коду (`scripts/reviews-index.mjs`, тесты, мутант), а не только «проверка, что H1 закрыт». `PROCESS.md`, `docs/LESSONS.md`, `.github/workflows/process.yml`, `parseDocName` дельтой не задеты — унаследованы из r1 (раздел ниже).
+
+## Как проверялось
+
+1. Прочитан полный `git diff 4d9754a1..3e96b376` для всех четырёх файлов дельты.
+2. Прочитан целиком текущий `scripts/reviews-index.mjs` (298 строк) и `test/reviews-index.test.mjs` (161 строка).
+3. `node --test test/reviews-index.test.mjs` — 9/9 pass (включая тест живого каталога, который читает реальный `docs/reviews/`).
+4. Мутант `reviews-index-counts-first-match` проверен вручную: патч `for (const scope of [text]) {` вместо цепочки приоритетов → целевой тест падает (`node --test --test-name-pattern="#635 r2: счётчик" test/reviews-index.test.mjs`), файл восстановлен. Тест умеет падать.
+5. Дословно воспроизведены оба заявления автора против живого `docs/reviews/INDEX.md`: `grep -c form-kit` → 6 (совпадает); строка `#635 | CODE-REVIEW-635-r1.md` теперь показывает 🟡 1 0 с текстом находки (совпадает).
+6. Прогнан `node scripts/reviews-index.mjs --dir=docs/reviews --check` на самом материале ревью (без модификаций рабочей копии, только чтение) — обнаружил H1 ниже.
+7. Для H2 (см. ниже) — прямой вызов экспортированных `parseFindings`/`parseCounts` на реальных файлах `docs/reviews/CODE-REVIEW-485-r4.md` и `docs/reviews/CODE-REVIEW-258-r1.md` через `node -e`, плюс скрипт-сканер по всему `docs/reviews/`, воспроизводящий внутреннюю логику `severityBlocks`, чтобы оценить масштаб (11 документов пойманы узкой эвристикой, вероятно больше).
+
+## Находки
+
+### H1 — `docs/reviews/INDEX.md`, зафиксированный в материале ревью, устарел на собственном SHA — не проходит `--check`, которым сам же себя проверяет
+
+**Файл:** `docs/reviews/INDEX.md` (весь материал ревью, `3e96b376`).
+
+Воспроизведение — три команды, ничего в рабочей копии не менялось:
+
+```
+$ git rev-parse HEAD
+3e96b37656b9ce49cd56e1aa2f65ebf0808f113b
+$ git status --short
+(пусто)
+$ node scripts/reviews-index.mjs --dir=docs/reviews --check
+docs/reviews/INDEX.md устарел — пересобрать: node scripts/reviews-index.mjs
+```
+
+Регенерация в `/tmp` и построчный `diff` с закоммиченным файлом показывают ровно
+4 отсутствующие строки — весь issue `#625` (`SPEC-REVIEW-625-r1.md`,
+`SPEC-REVIEW-625-r2.md`, `CODE-REVIEW-625-r1.md`, `CODE-REVIEW-625-r2.md`) — и
+изменившуюся шапку: «Документов: 992, issue: 345» вместо фактических 996/346.
+Эти четыре файла реально лежат в дереве материала (`git ls-files docs/reviews | grep 625`
+их находит, `git log --oneline -1 -- docs/reviews/CODE-REVIEW-625-r1.md` → `f10dd1eb`,
+предок `3e96b376`), т.е. не артефакт окружения ревьюера, а часть проверяемого коммита.
+
+Причина, по всей видимости, в многократных ребейзах ветки (`Ревью не запускалось`
+×3 в истории issue): `docs/reviews/INDEX.md` — статичный blob, который
+перегенерируется только явным запуском скрипта; когда ветку перевозили на новый
+`dev`, база успевала получить новые документы ревью (`#625`), а уже закоммиченный
+снимок индекса — нет. `--check` — это именно тот гейт, который должен был поймать
+расхождение, но он существует только как локальная CLI-опция; ни в одном workflow
+(`grep -rn reviews-index .github/workflows/*.yml` — единственное вхождение
+в `process.yml`, шаг публикации, не проверка) он не запускается на PR/ветке как
+блокирующий шаг. `npm test` тоже не ловит: тест «живой каталог» (`test/reviews-index.test.mjs:87-93`)
+проверяет свойства `docs/reviews/` напрямую (покрытие, доля распознанных
+вердиктов), а не совпадение с уже закоммиченным `INDEX.md` — так что зелёный
+Validate на этом SHA (о котором сказано в задании ревью) действительно не покрывает
+этот дефект, это не пропуск в моей проверке гейтов.
+
+Последствие: ровно то, ради чего заведён #635, — «агент, берущий задачу по
+диалогам, не найдёт [решение или урок], кроме как перечитав документ» —
+воспроизводится внутри собственного индекса: обе находки `#625` невидимы через
+`INDEX.md`, хотя документы существуют. AC1 («индекс покрывает 100 % документов
+каталога») не выполнено на материале ревью.
+
+**Серьёзность:** High, в скоупе. Фикс: перед коммитом дельты (или в отдельном
+шаге пайплайна) запускать `node scripts/reviews-index.mjs --dir=docs/reviews`
+против **финального** дерева ветки (после последнего ребейза), не против
+локального кеша разработчика; либо жёстко привязать регенерацию к
+пред-мержевому гейту, а не только к шагу публикации документа ревью.
+
+### M1 — `parseFindings`/`parseFiles`: фолбэк «первая строка тела блока» вырезает начало буллета и подставляет обрывок продолжения
+
+**Файл:** `scripts/reviews-index.mjs:190-196` (ветка `severityBlocks` → `first`).
+
+Когда у заголовка находки (`### Low`, `### Medium` и т. п.) нет собственного
+текста после разделителя и нет пронумерованных пунктов (`**M1. …**`), код берёт
+первую строку тела, которая не начинается с `|#<-`:
+
+```js
+const first = block.body.map((l) => l.trim()).find((l) => l && !/^[|#<-]/.test(l));
+```
+
+Символ `-` в этом исключении означает «пропустить маркер буллета», но
+эффект — пропустить **весь буллет**, если он в один физический абзац не
+уместился и перенесён на следующую строку (обычный стиль этой кодовой базы —
+переносы строк внутри длинного предложения). Тогда «первой подходящей
+строкой» становится не начало пункта, а его хвост — бессвязный вне контекста.
+
+Воспроизведение (реальный файл материала, без изменений):
+
+```
+$ node -e "
+import('./scripts/reviews-index.mjs').then(({parseFindings}) => {
+  console.log(parseFindings(require('fs').readFileSync('docs/reviews/CODE-REVIEW-485-r4.md','utf8')));
+});"
+[ 'пусто). Не эскалирую третий раунд подряд по той же логике r2/r3: защитные' ]
+```
+
+Настоящий текст пункта в документе (`docs/reviews/CODE-REVIEW-485-r4.md:110-113`):
+«Нет golden-сцены для радара (`find demo/golden -iname "*radar*"` — по-прежнему
+пусто). Не эскалирую третий раунд подряд по той же логике r2/r3…» — индекс
+показывает обрывок с несогласованным «пусто)» в начале, будто предложение
+начинается с закрывающей скобки.
+
+Это не единичный случай. Точечный скан по `docs/reviews/` (репродуцирует
+эвристику `severityBlocks` без изменения кода) находит минимум 11 документов с
+этим паттерном, включая документы с реальным ненулевым Medium — не только
+инертные «Low, унаследовано»:
+
+- `CODE-REVIEW-258-r1.md` (🟡 M:1) — второй элемент «Находки» в индексе:
+  `'Записи толщины, которые не найдутся по ключу' теперь мёртв — wall_key`
+  (начинается с висячей одиночной кавычки — обрывок цитаты).
+- `CODE-REVIEW-514-r3.md` (🟡 M:1) — второй элемент: `High не найдено. Medium
+  вне скоупа не найдено — единственный Medium (M1) целиком внутри…` — это не
+  находка, а мета-фраза «находок нет», которую `NOTHING_RE` должна была
+  отсеять, но отсеивает только когда это **всё** тело строки, а не когда это
+  «первая непустая строка» внутри более длинного абзаца.
+- `CODE-REVIEW-476-r1.md`, `SPEC-REVIEW-199-r1.md`, `SPEC-REVIEW-309-r1.md`,
+  `CODE-REVIEW-304-r1.md`, `CODE-REVIEW-485-r1.md`, `CODE-REVIEW-485-r2.md`,
+  `SPEC-REVIEW-152-r1.md`, `SPEC-REVIEW-419-r1.md` — тот же паттерн (см. лог
+  проверки ниже).
+
+Числа High/Medium (`parseCounts`) этим багом не затронуты — они не используют
+эту ветку. Ломается именно то, ради чего добавлена колонка «Находки»/«Файлы» в
+этом же раунде: агент, читающий строку индекса вместо документа, получает
+синтаксически рваный, не соответствующий по смыслу текст вместо реальной сути
+находки — то есть тот же класс дефекта, что и закрытый H1 r1 («индекс молчаливо
+[искажает] находки»), только не пустотой, а произвольным обрывком.
+
+**Серьёзность:** Medium, в скоупе (код и тесты дельты r2, `parseFindings` — то
+самое, что в этом раунде переписывалось). Фикс в рамках задачи: при выборе
+«первой строки тела» либо склеивать физически перенесённые строки одного
+буллета перед поиском первой подходящей, либо не отфильтровывать строки,
+начинающиеся с `-`, а прицельно вырезать только буллет-маркер (`^[-*]\s+`) и
+использовать очищенную первую непустую строку целиком; плюс усилить `NOTHING_RE`
+проверкой не только всей строки, но и вхождения фраз «не найдено»/«целиком
+внутри» в начале извлечённого текста. Нужен тест-фикстура с многострочным
+буллетом (аналогично уже добавленным фикстурам на реальных документах в этом же
+раунде).
+
+## Что проверено и корректно
+
+- **AC2 (пример автора).** `grep form-kit docs/reviews/INDEX.md` — 6 строк
+  (было 0 в r1). Совпадает с заявлением.
+- **Приоритет источника вердикта/счётчика.** Пересказ чужого раунда строчными
+  буквами в шапке документа (`CODE-REVIEW-152-r2.md:9` — «вердикт красный,
+  High: 1») больше не перебивает собственный зелёный вердикт документа
+  (строка 142: «**Вердикт: зелёный … High: 0 · Medium: 0**») — проверено и по
+  живому файлу, и по регэкспу (`VERDICT_OWN_LINE_RE` требует заглавную
+  «Вердикт» с начала строки).
+- **Регресс-мутант.** `reviews-index-counts-first-match` действительно ловится
+  целевым тестом (проверено ручным патчем, не только доверием к отчёту автора).
+- **Новые форматы заголовков находок.** `### Medium (в скоупе…) — …`,
+  `## Находка N (High…) — …`, `### [High] …`, `**M1. …**`-пункты внутри секции
+  — все разбираются тестами `test/reviews-index.test.mjs:104-150`, и я
+  подтвердил на реальных `CODE-REVIEW-639-r1.md`/`637-r1.md`, что
+  соответствующие строки `docs/reviews/INDEX.md` не пустые.
+- **Собственный документ r1.** `CODE-REVIEW-635-r1.md` в живом индексе (строка
+  12) теперь 🟡 1 0 с корректным текстом находки — ретроспективная проверка,
+  что H1 закрыт не только на синтетических фикстурах.
+- **9/9 юнит-тестов** `test/reviews-index.test.mjs`, включая тест живого
+  каталога (100 % покрытие имён, >90 % распознанных вердиктов) — прогнан лично,
+  не только со слов автора.
+
+## Чего не проверял
+
+- `npx tsc --noEmit`, полный `npm test`, `npm run build` — зачтено по зелёному
+  Validate на этом SHA (run `35859217407`, ссылка дана в задании ревью); диф не
+  трогает `.ts`/`src/**`, риск расхождения низкий.
+- `node scripts/check-docs.mjs` — не запускал: diff не заходит в `src/**`
+  (только `scripts/`, `test/`, `docs/reviews/INDEX.md`), отпечаток скриншотов
+  документации не мог устареть от этой правки.
+- `npm run invariants`, backend pytest, golden, performance-профили — не
+  относятся: геометрия, Python и рендер не затронуты.
+- `demo/smoke_*.mjs` — фронтенд-дифф отсутствует, `smoke-select.mjs` не
+  запускал (аналогично r1, диф той же природы).
+- Полный аудит остальных ~980 документов на предмет ещё не найденных
+  вариаций M1 — сканировал узкой эвристикой (одна конкретная форма фолбэка),
+  реальный масштаб может быть шире 11 найденных; не пытался перечислить все.
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где видно |
+|---|---|---|
+| H1 — `parseCounts` брал первое `High:`/`Medium:` по всему тексту (цитата чужого раунда, пример `CODE-REVIEW-594-r1.md`); `parseVerdict` так же терял приоритет собственной строки (пример `CODE-REVIEW-152-r2.md`); `parseFindings` не знал живых форматов заголовков (`### Medium (в скоупе…) — …`, `## Находка N (…)`, `**M1. …**`); колонки «Файлы» не было, `grep form-kit` находил 0 строк | Три правки в `scripts/reviews-index.mjs`: (1) `parseCounts`/`parseVerdict` — цепочка приоритета «своя строка `Вердикт` → секция `## Вердикт` → единственное значение по тексту → подсчёт по заголовкам» (`verdictLine`, `verdictSection`, `countsIn`); (2) `parseFindings` — `severityBlocks`/`numberedItems`/`FINDING_HEADING_RE` покрывают перечисленные живые форматы; (3) новая `parseFiles` + колонка «Файлы» | `scripts/reviews-index.mjs:50-220` (`git diff 4d9754a1..3e96b376`); тесты-регрессы на реальных документах `test/reviews-index.test.mjs:104-160` (594-r1, 152-r2, 639/637/162/141-фикстуры); в живом `docs/reviews/INDEX.md` — строка `#635 | CODE-REVIEW-635-r1.md` теперь 🟡 1 0 с текстом находки (было бы `0 0 —` до фикса), `grep form-kit` — 6 строк вместо 0; мутант `reviews-index-counts-first-match` (`scripts/mutation-registry.mjs`) — поймано вручную в этом раунде |
+
+## Унаследовано из r1 (без повторного разбора — дельта r2 этого не касается)
+
+Документ: `docs/reviews/CODE-REVIEW-635-r1.md`, SHA материала r1
+`db0f5b9b1be025fca86736f70d6aedd71d057487`.
+
+- **AC3 / PROCESS.md §2.10** — правило хранения раундов (все раунды текущей
+  линии в `docs/reviews/`, перенос в `legacy/` при стабильном релизе) записано
+  и принято r1; `PROCESS.md` не входит в diff `4d9754a1..3e96b376`.
+- **`docs/LESSONS.md`** (12 датированных уроков) — не изменялся в дельте r2,
+  принят по содержанию r1.
+- **`.github/workflows/process.yml`** — интеграция публикации (индекс
+  пересобирается и коммитится тем же коммитом, что документ ревью;
+  `review-doc-guard` пропускает `docs/reviews/`) — не изменялся в дельте r2,
+  принято по r1. (Отдельно от этого унаследованного факта — H1 этого раунда
+  показывает, что сама пересборка не гарантирует свежесть после последующих
+  ребейзов; это новый дефект процесса, не отменяющий корректность самой
+  интеграции шага.)
+- **`parseDocName`** и разбор старых форматов заголовков находок (`### 1. …`,
+  строки таблиц `| H1 | … |`) — байт-в-байт не менялись в дельте r2 (только
+  обёрнуты в `forEach` без изменения самих регэкспов) — приняты по r1.
+- **Мутанты `reviews-index-skips-self-check`, `reviews-index-verdict-substring`**
+  — не менялись в дельте, приняты по r1 (там же вручную проверено «поймано 1
+  из 1»).
+
+## Гейты — что прогнал, что нет
+
+| Гейт | Статус | Почему |
+|---|---|---|
+| `npx tsc --noEmit`, `npm test`, `npm run build` | не гонял | зелёный Validate на `3e96b376` (run 35859217407); diff не касается `.ts`/`src/**` |
+| `node --test test/reviews-index.test.mjs` | прогнал, 9/9 | дешёвый, прямое покрытие дельты |
+| `node scripts/reviews-index.mjs --dir=docs/reviews --check` | прогнал, **упал** | не покрыт ни Validate, ни `npm test`; это и есть H1 |
+| Мутант `reviews-index-counts-first-match` | прогнал вручную (патч + тест) | ловится |
+| `node scripts/check-docs.mjs` | не гонял | diff не в `src/**` |
+| `npm run invariants` | не нужен | геометрия не затронута |
+| `demo/smoke_*.mjs`, `smoke-select.mjs` | не гонял | фронтенд-диффа нет |
+| `npm run golden:verify` | не нужен | рендер не затронут |
+| `pytest tests_backend` | не нужен | Python не затронут |
+
+## Вердикт
+
+Жёлтый. High: 1 (`INDEX.md` материала ревью устарел, не проходит собственный
+`--check`, AC1 не выполнено на этом SHA), Medium: 1 (в скоупе — `parseFindings`
+подставляет обрывки многострочных буллетов вместо текста находки, минимум 11
+документов). Оба — по коду, изменённому в этой же дельте r2, чинятся в этом же
+issue.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/635-reviews-index`, коммит `3e96b37656b9` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `1cca2716ecd7f5004a0a235b1ff47da5ffb43019`
+  ```
+  git log --all --format='%H %T' | grep 1cca2716ecd7
+  ```
+- Тело issue: `6ae105e700c9b3bc91974f4e25052237ef671f31d5e59ee5a0841cbaa1bb26a6`
+- Вердикт конвейера: `yellow` · High 1