журнал решений: разложен по теме на файл, метки решений стали номерами
- DECISIONS.md (4040 строк, 65 тем) → decisions/, файл на тему плюс указатель; - буквенные метки решений заменены сквозными Р1–Р234, следствия получили префикс С при прежних номерах: схема букв выродилась до пятибуквенных и сломалась — `АЕАКЛ` была занята и темой 53, и темой 65; - 42 перекрёстные ссылки переписаны под новые номера и стали живыми; где номер означал тему, а слово стояло «решение», формулировка исправлена.
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
# 36. Темы ревью: документ проекта стал направлением проверки (2026-08-06)
|
||||
|
||||
Замечено при сверке документов канона с составом ступеней: **три документа
|
||||
остались без читателя ниже `wide`** — `security.md`, `database.md` и `adr/`.
|
||||
Проект поддерживал их, а на 90% задач их не открывал никто. Причина оказалась не
|
||||
в переезде проходов, а в том, как описан состав прогона.
|
||||
|
||||
**Р148. Тема первична, проход вторичен, и это правило 0 конвейера.** Список тем
|
||||
нигде не был записан: он существовал побочным продуктом списка проходов. Проход
|
||||
уезжал в верхнюю ступень — и тема уезжала с ним **беззвучно**: отчёт честно
|
||||
говорил «`ops` не запускался» и не говорил «эксплуатацию не смотрел никто», а
|
||||
нужно второе. Теперь прогон описывается таблицей «тема → дом → глубина → кто
|
||||
закрывает», и таблица есть в каждом отчёте.
|
||||
|
||||
**Р149. Тема есть документ, и список тем открытый.** Всё, что проект кладёт в
|
||||
`docs/`, становится темой ревью; запретить нельзя, разрешения не надо. Не темы
|
||||
ровно две: `docs/tasks/` и `docs/review.*` (настройка самого конвейера — слой
|
||||
над темами). Отсюда главное следствие: **`docs/` перестал быть документацией и
|
||||
стал конфигурацией конвейера.** Проект настраивает проверку тем, что пишет о
|
||||
себе, а не отдельным файлом настроек, который разошёлся бы с документами.
|
||||
|
||||
Ядро — шесть тем: `requirements`, `autotests`, `conventions`, `architecture`,
|
||||
`security`, `operations`. Их дома канон обещает. Всё сверх — темы проекта, и их
|
||||
разбирает `basics`: именных проходов конечное число, а тем столько, сколько
|
||||
заведёт проект, поэтому приёмник обязателен.
|
||||
|
||||
**Р150. Тема живёт файлом или каталогом, на выбор проекта.** `docs/security.md`
|
||||
и `docs/security/` — одно и то же. Прежде форма была задана поимённо
|
||||
(`conventions`, `research`, `adr` — каталоги, остальные — файлы), и обосновать
|
||||
это было нечем; заодно в TODO висел открытый вопрос «а если `architecture.md`
|
||||
разрастётся». Теперь ответ механический: разросся — стал каталогом с
|
||||
`README.md`, и это не смена версии канона. Обе формы сразу — ошибка, и `docs.py`
|
||||
её ловит: два дома для одного факта расходятся молча.
|
||||
|
||||
**Р151. Ступень выбирает разметчик, а не автор.** Заведён `review-scope`
|
||||
(`sonnet`), стадия 0, до гейта: находит документы, выводит темы, назначает
|
||||
глубины, выбирает ступень с обоснованием. Довод сильнее, чем синхронизация
|
||||
документов: **до сих пор профиль называл тот же оркестратор, который написал
|
||||
код** — то есть в точке выбора глубины проверки разведённости с автором не было
|
||||
вовсе, и решала она под давлением «я почти закончил». Вызывающий пайплайн
|
||||
профиль больше не передаёт.
|
||||
|
||||
Право у разметчика симметричное — поднять и понизить, — но обоснование
|
||||
обязательно всегда, а не только при отступлении от умолчания.
|
||||
|
||||
**Р152. Разметчик передаёт адреса, а не пересказ.** Проект однажды уже держал
|
||||
файл-посредник между документами и проходами (`review-brief.md`) и убрал его:
|
||||
второй дом расходится с первым и выглядит актуальным. Пересказ в задании — тот
|
||||
же посредник, живущий один прогон. Исключение одно: **отсутствие дома** — этого
|
||||
проход сам дёшево не выяснит.
|
||||
|
||||
`sonnet` ему хватает потому, что вывод устроен как **список**: каждый файл в
|
||||
`docs/` обязан попасть в план темой или строкой «не тема, потому что», и план
|
||||
сверяется с `ls docs/` за секунду. Выбор ступени — суждение, но у него три
|
||||
независимых корректора: отрицательный тест `quick`, правило «спорный случай
|
||||
вниз» и сигнал `basics` о заниженной ступени.
|
||||
|
||||
**Р153. `quick` и `standard` совпали составом и разошлись глубиной.** Требование
|
||||
«нижние ступени закрывают все темы, просто не так глубоко» иначе не выполняется:
|
||||
темы одни и те же, а различать ступени больше нечем. Глубин три и они про способ
|
||||
доказательства, а не про старательность: **сверка** (открыть дом, открыть дифф,
|
||||
сравнить), **разбор** (построить сценарий рассуждением), **доказательство**
|
||||
(прогнать, померить, построить путь). Третья есть только в `wide` — она одна и
|
||||
требует машины.
|
||||
|
||||
Цена принята: это единственное место конвейера, где профиль не выводится из
|
||||
списка проходов, поэтому глубина объявляется в отчёте наравне со ступенью.
|
||||
|
||||
**Р154. `review-code` переписан: технический разбор плюс конвенции.** Обнаружено
|
||||
по ходу: **никто не читал код как код.** `specs` сверял с требованиями, `basics`
|
||||
— с отказами окружения, `architecture` — с устройством, а `code` был проходом
|
||||
только по прозаическим конвенциям и прямо объявлял, что дефекты рантайма и
|
||||
логики не его. «Здесь ошибка в логике» не говорил никто, и это была самая
|
||||
крупная дыра конвейера — крупнее любой недосмотренной темы.
|
||||
|
||||
Теперь у прохода две половины: девять классов технического дефекта
|
||||
(необработанная ветка отказа, пустое и нулевое, граница диапазона, перепутанный
|
||||
операнд, неосвобождённый ресурс, изменение под итерацией, неверно применённый
|
||||
интерфейс библиотеки, недостижимая ветка, «сделано соседнее») и прежняя сверка с
|
||||
конвенциями. Модель поднята до `opus` по признаку [темы
|
||||
35](35-model-revision.md): цена **пропущенной** находки — дефект в проде, и она
|
||||
не оставляет следа ни в отчёте, ни в границах покрытия.
|
||||
|
||||
**Р155. Вопросы проекта переадресованы темам.** В `docs/review.*` было «Вопросы
|
||||
к проходам» в форме `ops: <вопрос>` — и когда `ops` уехал в `wide`, вопрос
|
||||
перестал задаваться молча. Стало «Вопросы по темам». Туда же «Недоступно
|
||||
проверке» — по темам, обоими подразделами.
|
||||
|
||||
## Что из этого следует
|
||||
|
||||
**С137. Состав, описанный исполнителями, теряет предмет при перестановке
|
||||
исполнителей.** Список проходов отвечает «кто работал», а нужен ответ «что
|
||||
проверено». Первое выглядит полным ровно тогда, когда второе неверно.
|
||||
|
||||
**С138. Открытый список нуждается в приёмнике, иначе он обещание.** Разрешить
|
||||
проекту завести свою тему и не назначить, кто её разбирает, — то же, что не
|
||||
разрешать.
|
||||
|
||||
**С139. Регулятор глубины проверки нельзя оставлять в руках автора.** Не потому
|
||||
что он злонамерен, а потому что давление «я почти закончил» действует всегда и в
|
||||
одну сторону.
|
||||
|
||||
**С140. Дыру в покрытии находят не там, где ищут находки.** Три осиротевших
|
||||
документа нашлись сверкой канона с составом ступеней, а отсутствие технического
|
||||
ревью кода — сверкой оптик проходов между собой. Ни то ни другое не всплыло бы
|
||||
на прогоне: прогон честно сообщал, что все запущенные проходы отработали.
|
||||
Reference in New Issue
Block a user