# 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 как полигон — первое ретро по нему делается на той машине.