claude-harness/CHANGELOG.md

Changelog

0.6.0 — 2026-10-24

• /harness-retro (B12, #29) — проектный skill регулярного ретро обвязки. Работает по циклу фичи: issue, worktree, PR. Результат — черновик docs/retro/<дата>.md по шаблону и <дата>.metrics.json со сравнением с прошлым ретро.

• docs/retro/scripts/retro_metrics.py считает срез метрик проекта по транскриптам и памяти:

  • сессии, промпты, инструменты, роли, сабагенты, skills, токены (по message.id, без синтетических сообщений об ошибке API), компакции, стартовый контекст;
  • блокировки хуков, отказы классификатора и владельца;
  • codegraph против чтения кода (решение владельца 3);
  • «перечитай», память;
  • кандидаты в поправки владельца по процессу (--corrections).

  Транскрипты сабагентов (<сессия>/subagents/) входят в сессию-родителя; период режется по меткам времени записей, поэтому длинная сессия делится между ретро. Без --since период берётся из существующего --out, --from рисует «Цифры» из сохранённого среза. Заменяет retro_stats.py и retro_blocks.py.

• docs/retro/scripts/retro_leftovers.py ищет хвосты чеклиста закрытия по состоянию репозиториев: слитые ветки на сервере и локально, worktree, SDD workspace закрытых задач, неархивные changes, отставший или грязный main.

• Корпус хуков разбит на сегменты со своей раскладкой; записи known — известные ошибки хуков (KNOWN-FIXED — пора снять пометку), doctor показывает их число. hook_blocks_export.py --since --id-prefix выгружает блокировки среза, hook_cases_build.py собирает корпус из hook-labels-<дата>.json.

• docs/retro/2026-10-11.metrics.json — метрики ретро 11.10, перенесённые из таблицы. Блокировки — 76 ошибок хука, из них 72 ложные (O-1). Ходы и токены 11.10 считались по строкам и помечены как несравнимые.

0.5.1 — 2026-10-24

• Worktree живут в <repo>/.claude/worktrees/<slug>, а не в соседнем каталоге: их создаёт EnterWorktree с именем, ветка worktree-<slug> переименовывается в feat/<id>-<slug> (#25). Вход в worktree вне .claude/worktrees/ спрашивает подтверждение при любых allow-правилах (Claude Code ≥ 2.1.206). Описано в roles/dev.md и HARNESS.md.
• .claude/worktrees/ — в .gitignore проектов: adopt-project.sh, project-template/gitignore, этот репозиторий. doctor.sh: WARN .claude/worktrees/ не в .gitignore.
• Спека hook-guards: сценарии «worktree внутри репозитория» для guard-main и require-plan — корень и ветка берутся из worktree. Тесты закрепляют уже существующее поведение, код хуков не менялся.
• Многорепозиторный workspace (awp-ca, .wt/<задача>/) не затронут — вопрос в части 2 #2.

0.5.0 — 2026-10-23

• install.sh ставит allow-правила цикла фичи (#24; пересмотр решения владельца 2). Список — global/permissions.json: git worktree, git branch -m/-D, git push -u origin feat/…/chore/…, git push origin --delete, tea issues, tea pulls create/list/edit, tea comments. Merge и push в main в список не входят. Правила только дописываются в permissions.allow файла ~/.claude/settings.json, чужие не трогаются; копия списка — ~/.claude/harness/permissions.json. --no-permissions пропускает шаг. --check и doctor.sh показывают permissions обвязки: N/M и недостающие правила.
• adopt-project.sh и new-project.sh печатают строку push --delete для установки с --no-permissions. WARN проверки в doctor.sh подсказывает bash install.sh.
• EnterWorktree в список не входит. Вход в worktree вне <repo>/.claude/worktrees/ спрашивает подтверждение при любых allow-правилах (Claude Code ≥ 2.1.206); перенос worktree — #25.
• harness-doctor: агент чинит install.sh --no-permissions, права ставит владелец.

0.4.2 — 2026-10-23

• Удаление ветки фичи на сервере (чеклист закрытия, п. 4; B3, RT-3, решение владельца 2): doctor.sh в разделе «Проект» ищет allow-правило для git push origin --delete в .claude/settings.json, settings.local.json проекта и в глобальном settings.json — ok с файлом или WARN с готовой строкой "Bash(git push origin --delete:*)". Строку печатают adopt-project.sh и new-project.sh во всех режимах (раньше — только adopt --workspace); файл настроек они не пишут, правило добавляет владелец (#22).
• HARNESS.md: шаг 10 — чеклист из 8 пунктов в roles/dev.md и рецепт п. 4. roles/dev.md, п. 4: git worktree remove раньше git branch -D (ветку, выведенную в worktree, git не удаляет).

0.4.1 — 2026-10-23

• harness-doctor и README: codegraph ставится npm i -g @colbymchenry/codegraph (формулы в brew нет) и подключается к Claude Code через claude mcp add-json -s user, не через codegraph install — тот дописывает секцию в ~/.claude/CLAUDE.md, которую сотрёт install.sh (#19, O-8).

0.4.0 — 2026-10-16

• guard-main решает по цели записи, а не по cwd и тексту команды (#6, B1; RT-1, RT-2, RT-7). Цели — файл Edit/Write, в Bash — редиректы (кроме /dev/null и N>&M), команды записи с учётом cd, git -C, sh -c, git-мутации. Цель вне репозитория или в worktree на ветке — пропуск; неразрешимый путь — пропуск, git-мутация с неопределённым репозиторием — блок. git push блокируется, только если пушит в main; git switch -c в той же команде переводит последующие коммиты на новую ветку. pip install больше не блокируется. Спека — openspec/specs/hook-guards/spec.md, change в архиве — openspec/changes/archive/2026-10-16-hooks-write-target/.
• Несовместимо: исключение для openspec-only коммитов и openspec archive на main удалено — архив всегда отдельным PR (решение владельца 1, 11.10.2026).
• require-plan берёт корень, ветку, .claude/code-paths, .bounded и планы из репозитория правимого файла.
• Общее ядро hooks/harness_target.py (python3 stdlib); guard-main.sh и require-plan.sh — обёртки, регистрация в settings.json прежняя. Режим targets показывает, какие цели видит хук.
• Сообщения блокировки: BLOCKED [guard-main]: / BLOCKED [require-plan]:, цель, корень репозитория, выход.
• Регрессионный корпус хуков (B2, RT-6): 126 записей из транскриптов пилота + 3 живых случая, размечены по спеке (docs/retro/scripts/hook_cases_build.py), прогон в песочнице — tests/test-hook-corpus.sh по источникам и строка «корпус хуков» в doctor.sh по установленным копиям. В песочнице старые хуки дают на корпусе 41 блок (37 ложных), новые — 4 (архивные коммиты в main).
• hook_blocks_export.py и retro_blocks.py считают только ошибки хуков: из 126 выгруженных записей 49 оказались выводом команд со словом BLOCKED (O-1), счёт RT-1 в ретро завышен.
• Тесты: test-hook-parse, test-hook-guard-main, test-hook-require-plan, test-hook-corpus, test-hook-export.

0.3.0 — 2026-10-11

• Роли сессии dev|admin|analyst|qa: общий слой roles/<r>.md (~/.claude/roles/), проектный слой <workspace>/.claude/roles/<r>.md; формат из четырёх разделов (спека docs/superpowers/specs/2026-10-11-roles-and-memory-design.md).
• Skill /role <r>: читает оба слоя, раздел памяти роли, «Читать на старте»; строки brief: — фоновому агенту briefing (sonnet, только чтение).
• SessionStart-хук role-hint.sh: подсказка роли по заголовку сессии (claude -n "admin …"), регистр и префикс cc- не важны; ничего не блокирует.
• link-roles.sh: симлинки ролей и агентов из workspace в репозитории направлений по таблице | Каталог | Репозиторий | Роль |. Память агентов через симлинк не работает (проверено, спека, раздел 11) — для неё запасной вариант 6.5 (notes/agent-memory.md).
• Шаблоны project-template/workspace/ и project-template/role-repo/; режим --workspace в adopt-project.sh и new-project.sh.
• Глобальный CLAUDE.md сжат до ≤ 3 КБ (роль, хуки, память, маркировка, стиль); процесс разработки переехал в roles/dev.md — таблица адресов docs/retro/2026-10-11-claude-md-addresses.md. Изменения правил: архив OpenSpec всегда отдельным PR; п. 4 чеклиста закрытия — из worktree по allow-правилу; bounded обновляет спеку при смене API; новый п. 7 — память задачи при закрытии.
• Политика памяти: состояние задачи в трекере, уроки в notes/ направления и памяти агентов, в auto-memory — только ловушки машины и индекс.
• doctor.sh: файлы ролей, самотест role-hint, режим workspace (симлинки, размеры CLAUDE.md и индекса памяти).
• Тесты пакета tests/run.sh (bash, без зависимостей): хук, роли, размеры, skill/agent, link-roles, workspace, doctor, install.
• Ретроспектива docs/retro/2026-10-11.md и скрипты docs/retro/scripts/.

0.2.0 — 2026-09-27

• Skill harness-doctor (doctor.sh + чеклист прочтения): машина, самотест хуков, проект; ставится в ~/.claude/skills/.
• require-plan: защищает любой src/ на любой глубине (было — только от корня), переопределение списком в .claude/code-paths.
• SessionStart-хук harness-check.sh: при старте сессии в неподключённом проекте агент предлагает (или с HARNESS_AUTO_ADOPT=1 — сразу выполняет) adopt-project.sh; скрипты бутстрапа ставятся в ~/.claude/harness/.
• adopt-project.sh — подключение обвязки к существующему репозиторию (ветка → бутстрап → ff-merge); project-template/CLAUDE.harness-section.md.
• codegraph: codegraph init в worktree и projectPath в вызовах codegraph_explore — MCP-сервер видит только индекс папки запуска.
• Порядок старта фичи: worktree на временной ветке → issue → переименование ветки (хук guard-main блокирует запись на main).
• Маркировка находок и решений: T<n>.<k>, C/I/M-n, R-n, O-n, H-n; обязательный статус fixed / deferred / rejected.
• Чеклист закрытия: issue закрывается только при выполнении всех её пунктов, иначе комментарий с закрытыми маркерами; неприменимые к bounded пункты пропускаются с пометкой.
• Чеклист закрытия: п. 6 — отложенные находки собираются в issue Gitea Follow-ups from #N.

0.1.0 — 2026-09-27

• Первая версия после пилота на obsidian-voice-note (10 задач, 125 тестов, PR #2).
• Хуки: guard-main (main + detached HEAD, Bash-запись, исключение для openspec/), require-plan (.bounded).
• Глобальный CLAUDE.md: маршрутизация superpowers/OpenSpec/Gitea/codegraph, контроллер SDD на sonnet, чеклист закрытия из 6 пунктов, раздел «Decisions made without discussion».
• new-project.sh и шаблон проекта.