andrey.epifantsev
b77776849e
OpenSpec change harness-retro: proposal, specs (harness-retro — новая capability; hook-guards — MODIFIED «Регрессионный корпус хуков»: сегменты и known), design с Decisions made without discussion. По итогам brainstorming 24.10.2026: черновик ретро, срез одного проекта, запуск из репозитория обвязки, разметка блокировок агентом в корпус, хвосты по текущему состоянию, поправки владельца по процессу, подход A. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
70 lines
6.5 KiB
Markdown
70 lines
6.5 KiB
Markdown
# Proposal: `/harness-retro` — регулярное ретро обвязки
|
||
|
||
Issue: #29. Источники:
|
||
- ретро `docs/retro/2026-10-11.md` — B12, решение владельца 3 (замер codegraph);
|
||
- находки O-10, O-11 (#21), O-17 (#28);
|
||
- brainstorming 24.10.2026.
|
||
|
||
## Why
|
||
|
||
Ретро 11.10 считали два одноразовых скрипта, `docs/retro/scripts/retro_stats.py` и `retro_blocks.py`. У них нет функций и тестов. В них зашиты имена репозиториев awp-ca, и они ничего не знают про `.claude/worktrees/`. Вывод — текст для глаз, поэтому таблицу «Цифры» собирали вручную.
|
||
|
||
Повторить такое ретро и сравнить его с прошлым нельзя, а именно сравнение показывает, помогли ли изменения обвязки: хуки 0.4.0, роли 0.3.0, allow-правила 0.5.0. Решение владельца 3 требует замерить codegraph в одном срезе, и метрика должна входить в `/harness-retro`.
|
||
|
||
Владелец хочет видеть в ретро места, где он поправлял агента по процессу. Сейчас они теряются в транскриптах.
|
||
|
||
Блокировки, размеченные при ретро, в регрессионный корпус хуков не попадают. Ложный блок, найденный на ретро, тестом не становится.
|
||
|
||
## What Changes
|
||
|
||
- **Новый проектный skill `/harness-retro`** (`.claude/skills/harness-retro/`). Запускается в сессии в репозитории обвязки: `/harness-retro <папка проекта или workspace> [--since ГГГГ-ММ-ДД]`. Работа идёт по циклу фичи: issue, `EnterWorktree`, PR. Результат — черновик `docs/retro/<дата>.md` по шаблону и `docs/retro/<дата>.metrics.json`. Утверждение — merge владельца.
|
||
- **`docs/retro/scripts/retro_metrics.py`** — stdlib, на функциях, с тестами. Даёт метрики среза по транскриптам и памяти проекта:
|
||
- сессии, промпты, инструменты, роли, сабагенты, skills, токены, компакции;
|
||
- стартовый контекст;
|
||
- блокировки хуков;
|
||
- отказы классификатора и владельца;
|
||
- codegraph против чтения кода;
|
||
- поправки владельца;
|
||
- «перечитай память»;
|
||
- размер памяти.
|
||
|
||
Выводит JSON, таблицу «Цифры» со сравнением с прошлым `*.metrics.json` и кандидатов в поправки владельца с контекстом.
|
||
- **`docs/retro/scripts/retro_leftovers.py`** ищет хвосты чеклиста закрытия по текущему состоянию репозиториев проекта:
|
||
- слитые ветки на сервере и локально, worktree на них;
|
||
- `.superpowers/sdd/*`;
|
||
- неархивные changes в `origin/main`;
|
||
- отставший или грязный основной checkout.
|
||
|
||
Только чтение; `--fetch` по запросу.
|
||
- **`hook_blocks_export.py --since`** выгружает блокировки среза в `docs/retro/fixtures/hook-blocks-<дата>.jsonl`. Агент размечает их по спеке `hook-guards` в `hook-labels-<дата>.json` (вердикт, класс, раскладка песочницы), и `hook_cases_build.py` дописывает их в корпус.
|
||
- **Корпус хуков** состоит из сегментов: у каждого своя шапка `{home, layout}`, раннер строит песочницу на сегмент. Запись с `known: "RT-n"` — известная ошибка текущих хуков, тест на ней не падает. Doctor показывает число известных ошибок.
|
||
- `retro_stats.py` и `retro_blocks.py` удаляются. Их заменяет `retro_metrics.py`. Ретро 11.10 ссылается на них как на историю.
|
||
- `docs/retro/2026-10-11.metrics.json` переносится один раз из таблицы ретро 11.10, чтобы следующему ретро было с чем сравнивать.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
- `harness-retro`: срез метрик обвязки по транскриптам, памяти и состоянию репозиториев проекта; кандидаты в поправки владельца; разметка блокировок в корпус; черновик ретро и сравнение с прошлым.
|
||
|
||
### Modified Capabilities
|
||
- `hook-guards`: требование «Регрессионный корпус хуков» — сегменты с собственной раскладкой и известные ошибки `known`.
|
||
|
||
## Impact
|
||
|
||
- **Код:**
|
||
- новые `docs/retro/scripts/retro_metrics.py`, `retro_leftovers.py`;
|
||
- `hook_blocks_export.py` (`--since`, id);
|
||
- `hook_cases_build.py` (разметка из `hook-labels-*.json`, сегменты);
|
||
- `skills/harness-doctor/scripts/hook_corpus.py` (сегменты, `known`);
|
||
- `doctor.sh` (строка корпуса).
|
||
- **Skill:** `.claude/skills/harness-retro/SKILL.md` и `template.md`. Он проектный, поэтому `install.sh` не меняется.
|
||
- **Тесты:**
|
||
- новые `tests/test-retro-metrics.sh`, `tests/test-retro-leftovers.sh`;
|
||
- дополнения в `test-hook-corpus.sh`, `test-hook-export.sh`, `test-doctor.sh`.
|
||
- **Документация:** `CLAUDE.md` («Команды», «Архитектура», «Тесты»), `docs/HARNESS.md` (раздел «Ретро»), `README.md`, `CHANGELOG.md` 0.6.0.
|
||
- **Вне задачи:**
|
||
- сторона Gitea в хвостах закрытия: открытые issue после слитого PR, пропущенные follow-up;
|
||
- срезы по нескольким проектам сразу;
|
||
- автоматические находки по порогам;
|
||
- workspace awp-ca как полигон — первое ретро по нему делается на той машине.
|