claude-harness/openspec/changes/harness-retro/proposal.md

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