добавлен конвейер ревью и пайплайн задачи
- одиннадцать проходов ревью перенесены из jellybit и переписаны под домен: приём пакетов, слои, координатная идентичность, чувствительность данных - скиллы task-pipeline и review-pipeline, контракт находок, журнал промахов
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
---
|
||||
name: review-pipeline
|
||||
description: Конвейер ревью изменений healthlog — детерминированный гейт, сверка с дельта-спеками OpenSpec в обе стороны, generative-проходы (рубрика, независимая реализация, stdlib grounding, negative space), архитектура, враждебные постановки и обязательный триаж. Вызывается из task-pipeline (чекпоинты ревью) и отдельно — профилем design на OpenSpec-предложении ДО кода.
|
||||
---
|
||||
|
||||
# Конвейер ревью (healthlog)
|
||||
|
||||
Готовит ревью — **не заменяет его**. Потребитель отчёта — оркестратор, который
|
||||
чинит код; человек читает только сводку, развилки и границы покрытия.
|
||||
|
||||
## Три правила, из которых всё следует
|
||||
|
||||
Если ситуация не покрыта инструкцией — решай по ним.
|
||||
|
||||
1. **Recall чек-листа равен длине чек-листа.** Проход, устроенный как «проверь
|
||||
пункты 1..N», найдёт ровно перечисленное. Всё неявное — идиомы, форма
|
||||
решения, «так не делают» — неперечислимо по определению: перечислимое уже
|
||||
стало бы конвенцией. Отсюда деление проходов на **applicative** (применяют
|
||||
заданный критерий) и **generative** (сперва порождают критерий или
|
||||
альтернативу, потом сравнивают). Расширять чек-листы бесполезно; неявный слой
|
||||
достают только generative-проходы.
|
||||
2. **Ценность верификатора = наличие внешнего оракула × декорреляция с
|
||||
автором**, а не число ролей. Под всеми ролями одна модель с одними
|
||||
априорными, вход у всех общий: седьмая роль почти не добавляет recall, но
|
||||
линейно удорожает триаж. Иерархия надёжности: детерминированный инструмент >
|
||||
агент, который его **запускает** и интерпретирует вывод > агент с чистым
|
||||
мнением. Максимум работы переносим вниз.
|
||||
3. **Отчёт без границ покрытия хуже отсутствия отчёта.** «Критичных проблем не
|
||||
обнаружено» потребляет ощущение проверенности, ничего не гарантируя. Секция
|
||||
границ покрытия обязательна и не сокращается — в том числе в докладе человеку.
|
||||
|
||||
## Что этот конвейер защищает в healthlog
|
||||
|
||||
Инварианты, нарушение которых — по умолчанию `critical` (подробно —
|
||||
`CLAUDE.md`, `docs/architecture.md`):
|
||||
|
||||
- **Точка хранится дословно.** Всё, что теряет поле внутри точки, необратимо:
|
||||
сырой архив живёт 14 дней, дальше истина — сами точки.
|
||||
- **Идентичность по координатам** (`метрика + слой + метка`). `source` в ключ
|
||||
не входит. Неверное правило слияния портит историю молча — заметить это
|
||||
можно только сверкой с родным экспортом Apple, то есть месяцами позже.
|
||||
- **Агрегации при записи нет.** Свёртка живёт только в ответе и только с
|
||||
измеренным родом метрики. Нижний слой HAE не суммируется никогда.
|
||||
- **Данные о здоровье чувствительнее токенов.** Тело запроса в логе на уровне
|
||||
выше `DEBUG`, файл выгрузки под контролем версий — это утечка, а не
|
||||
неаккуратность.
|
||||
- **Приём не теряет доставку.** Код ответа отражает доставку, а не разбор;
|
||||
тело ложится на диск до разбора.
|
||||
|
||||
## Профили
|
||||
|
||||
| Профиль | Когда | Стадии |
|
||||
|---|---|---|
|
||||
| `quick` | багфикс, локальная правка, доки | 0, 1, 5 |
|
||||
| `standard` | новая функциональность в существующем пакете | 0, 1, 2, 5 |
|
||||
| `deep` | новый пакет, изменение публичного контракта, миграция БД, трогает инварианты выше | 0, 1, 2, 3, 4, 5 |
|
||||
| `design` | **до кода**, на OpenSpec-предложении | rubric + idiom + architecture (см. ниже) |
|
||||
|
||||
Правило выбора — по факту изменения, не по ощущению важности:
|
||||
|
||||
- есть миграция в `internal/store/migrations/`, новый пакет `internal/*`,
|
||||
изменение контракта Read API или MCP, трогается правило слияния точек или
|
||||
вывод слоя → `deep`;
|
||||
- иначе меняется поведение, видимое снаружи (эндпоинт, форма ответа, код
|
||||
ответа приёма, формат лога) → `standard`;
|
||||
- иначе → `quick`.
|
||||
|
||||
Профиль объявляется в отчёте. Понижение профиля — решение оркестратора, и оно
|
||||
попадает в границы покрытия строкой «профиль понижен до X, потому что …».
|
||||
|
||||
## Стадия 0 — Gate (обязательна во всех профилях)
|
||||
|
||||
Агент `healthlog-review-gate`. Запускает `task gate` и интерпретирует вывод.
|
||||
|
||||
**Пока гейт красный — опиниативные проходы не запускаются.** Оркестратор чинит и
|
||||
перезапускает гейт. Исключение одно: отказ, унаследованный от базовой ветки
|
||||
(гейт проверяет это прогоном на базе) — тогда он фиксируется находкой и не
|
||||
блокирует.
|
||||
|
||||
Гейт возвращает не только «зелено/красно», но и находки класса **отсутствующая
|
||||
верификация**: изменённые строки без покрытия, конкурентность без теста с
|
||||
параллельным доступом, флаки-тест (не ниже `major`), недоступный инструмент.
|
||||
|
||||
Шаги выбираются по изменённым файлам: правка документации не гоняет тесты,
|
||||
линтеры и `-race`. Пропуск при этом не молчит — он виден в сводке с причиной и
|
||||
уезжает в границы покрытия, как и любой другой `SKIP`.
|
||||
|
||||
Два шага гейта специфичны для healthlog и красят его безусловно:
|
||||
`no-health-data` (файл из `data/` попал под контроль версий) и `config-samples`
|
||||
(структура конфига изменилась, а `config.example.toml`/`config.docker.toml` —
|
||||
нет).
|
||||
|
||||
## Стадия 1 — Conformance (обязательна во всех профилях)
|
||||
|
||||
Два applicative-прохода: оба применяют **записанный** критерий, оба дешёвые,
|
||||
запускаются **одним сообщением параллельно**.
|
||||
|
||||
- `healthlog-review-specs` — критерий взят из **дельта-спек change в
|
||||
`openspec/changes/<id>/specs/`**, а не из proposal, сообщения коммита или
|
||||
описания задачи. Сверка двунаправленная; направление `code → spec` важнее.
|
||||
- `healthlog-review-code` — критерий взят из `docs/conventions.md`, и только та
|
||||
его часть, которая **не выражается правилом**: механизируемое уже проверила
|
||||
стадия 0 (`sloglint`, `forbidigo`, `errorlint`, `depguard`). Уровень лога по
|
||||
адресату, единственный логирующий чекпоинт на доменной границе, трансляция
|
||||
ошибки на внешней границе, `ident.Parse` на входной границе, время в UTC
|
||||
через `store.Now()`.
|
||||
|
||||
Recall обоих равен длине их источника — это и есть предел applicative-проходов,
|
||||
ради которого существует стадия 2.
|
||||
|
||||
## Стадия 2 — Tacit layer (generative; `standard`, `deep`)
|
||||
|
||||
Четыре прохода, каждый в своём контексте, запускаются **одним сообщением
|
||||
параллельно**:
|
||||
|
||||
- `healthlog-review-rubric` — порождает рубрику до чтения кода, потом судит по ней;
|
||||
- `healthlog-review-reimpl` — пишет свою реализацию, не открывая существующую,
|
||||
затем диффит по решениям (в профиле `standard` включается только если
|
||||
изменение содержит новый файл или функцию длиннее ~60 строк — иначе дорог и
|
||||
бесполезен);
|
||||
- `healthlog-review-idiom` — заземляет «идиоматичность» на stdlib и поимённые
|
||||
положения гайдов;
|
||||
- `healthlog-review-negative` — чего нет и что лишнее.
|
||||
|
||||
## Стадия 3 — Global (`deep`, `design`)
|
||||
|
||||
Агент `healthlog-review-architecture`. Получает **вход шире диффа**: дерево
|
||||
пакетов с назначением, граф внутренних зависимостей, инвентарь существующих
|
||||
концепций проекта. Готовит вход команда:
|
||||
|
||||
```
|
||||
task review:context > tmp/review-context.md
|
||||
```
|
||||
|
||||
Главный вопрос — концептуальная целостность и **второй способ** делать то, что
|
||||
уже делается. Потолок — 3 находки плюс секция «дешевле переделать до мерджа».
|
||||
|
||||
## Стадия 4 — Adversarial и operational (`deep`)
|
||||
|
||||
`healthlog-review-adversary` (находка = построенный путь, не свойство) и
|
||||
`healthlog-review-ops` (постмортем от симптома у владельца сервиса к строке).
|
||||
Запускаются параллельно со стадией 2, если профиль `deep`.
|
||||
|
||||
Для healthlog эксплуатационный проход обязан держать в голове: телефон шлёт
|
||||
непрерывно и молча, тела доходили до 42 МБ, запись в часовой объект —
|
||||
read-modify-write под конкурентными доставками, а тихо сломавшаяся
|
||||
автоматизация обнаруживается не сразу.
|
||||
|
||||
## Стадия 5 — Triage (обязательна)
|
||||
|
||||
Агент `healthlog-review-triage`. Единственный, кто агрегирует. Получает сырые
|
||||
выводы всех проходов и `git diff`; возвращает финальный отчёт.
|
||||
|
||||
Без триажа шесть проходов дают порядка сорока замечаний при единицах
|
||||
существенных. Потребитель здесь — оркестратор, который **молча реализует** всё,
|
||||
что прочитал: цена нетриажированного отчёта — не потерянное время человека, а
|
||||
разросшийся от вкусовщины код.
|
||||
|
||||
Порядок: дедупликация по причине → оракул для всего `critical`/`major` →
|
||||
понижение неподтверждённого до гипотезы → отсев вкусовщины → ранжирование по
|
||||
ущербу × вероятности → потолок 7 пунктов в основном списке.
|
||||
|
||||
## Профиль `design` — до кода
|
||||
|
||||
Запускается на шаге ревью спек (`task-pipeline` шаг 4), когда change уже имеет
|
||||
`proposal.md` + дельта-спеки, но кода ещё нет. Состав:
|
||||
|
||||
1. `healthlog-review-specs` в режиме «дизайн ДО кода»;
|
||||
2. `healthlog-review-rubric`, фаза 1 без фазы 2: рубрика на задуманный узел
|
||||
становится приёмочными критериями и уезжает в `tasks.md`;
|
||||
3. `healthlog-review-idiom` по описанию решения (какие конструкции stdlib
|
||||
закрывают задачу; не изобретаем ли то, что уже есть);
|
||||
4. `healthlog-review-architecture` на предложении: вводит ли change новое
|
||||
понятие, можно ли выразить существующими, не появляется ли второй способ;
|
||||
5. вопрос автору дизайна: **«предложи три формы решения и назови компромисс
|
||||
каждой»** — если ответ показывает, что рассматривалась одна, это находка.
|
||||
|
||||
Смысл профиля: архитектурная находка на готовом коде стоит переписывания и
|
||||
поэтому игнорируется; та же находка на предложении стоит абзаца обсуждения.
|
||||
|
||||
## Контракт находок
|
||||
|
||||
Единый для всех проходов — [references/finding-contract.md](references/finding-contract.md).
|
||||
Коротко: заголовок через **последствие**, обязательные поля `Файл`, `Severity`,
|
||||
`Confidence`, `Оракул`, `Последствие`, `Предложение`, `Найдено проходом`.
|
||||
`critical` без оракула или построенного пути не существует. Находка без поля
|
||||
«Последствие» не выводится вовсе.
|
||||
|
||||
Каждый проход завершает вывод блоком `## Coverage of this pass`.
|
||||
|
||||
## Что происходит с находками дальше
|
||||
|
||||
- Оркестратор чинит помеченное `Действие: инлайн` и **не логирует мелочь**.
|
||||
- `Действие: развилка` — на человека через `AskUserQuestion`, вопросом с
|
||||
вариантами.
|
||||
- Находка не для этого мерджа, но реальная (отложенный `major`, развилка,
|
||||
решённая «потом») — не теряется: заводится задачей через скилл `backlog`
|
||||
(интейк из ревью), с оракулом и провенансом в теле. Мелочь класса `nit` — в
|
||||
пакетный файл, а не файлом на находку.
|
||||
- `Promote candidates` — по процедуре
|
||||
[references/promote.md](references/promote.md): находка → конвенция → правило
|
||||
линтера → **удаление из конвенций и из промптов**. Третий шаг обязателен.
|
||||
- Дефект, проскочивший ревью и всплывший позже, идёт в
|
||||
[docs/review-journal.md](../../../docs/review-journal.md) — сразу, не
|
||||
ретроспективно: теряется именно причина непоймания.
|
||||
|
||||
## Честный предел
|
||||
|
||||
Модель воспроизводит медиану публичного Go, смещённую к популярному и
|
||||
туториальному: отсюда тяга к интерфейсам ради интерфейсов, лишним мокам и
|
||||
конфигурируемости, которую никто не просил. **«Идиоматично» и «распространено» —
|
||||
разные вещи**; проходы обязаны различать их и опираться на поимённое положение
|
||||
гайда, а не на ощущение частотности.
|
||||
|
||||
Согласие нескольких проходов — **не подтверждение**: это один источник,
|
||||
высказавшийся несколько раз. Совпадение повышает приоритет, но не `confidence`.
|
||||
|
||||
Ни одному проходу принципиально недоступно:
|
||||
|
||||
- поведение Health Auto Export на следующем обновлении приложения;
|
||||
- то, что реально лежит в Apple Health, — сверить можно только с ручным
|
||||
экспортом, а он делается раз в 2–3 месяца;
|
||||
- поведение таблицы SQLite под объёмом нескольких лет истории;
|
||||
- завязка внешних потребителей (агент-медик, трекер, игра) на текущую форму
|
||||
ответа;
|
||||
- суждение «этой метрики не должно существовать».
|
||||
|
||||
Это и есть причина, по которой конвейер готовит ревью, а не заменяет его.
|
||||
|
||||
## Ссылки
|
||||
|
||||
- [references/finding-contract.md](references/finding-contract.md) — контракт находок.
|
||||
- [references/promote.md](references/promote.md) — промоут находка → конвенция → правило → удаление.
|
||||
- [docs/review-journal.md](../../../docs/review-journal.md) — журнал проскочивших дефектов.
|
||||
Reference in New Issue
Block a user