feat(global): CLAUDE.md ≤ 3 КБ — роль, хуки, память, маркировка; таблица адресов

Refs #2

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MzkPQWjfA7RpqYWkjnqJwt

docs/retro/2026-10-11-claude-md-addresses.md

@@ -0,0 +1,33 @@
+# Куда переехал глобальный CLAUDE.md (0.2.0 → 0.3.0)
+
+Проверка критерия спеки «ни одно правило не потеряно». Старый файл — `global/CLAUDE.md` до коммита этой ветки (9155 Б).
+
+| Старый абзац (раздел → пункт) | Новый адрес |
+|---|---|
+| Роли инструментов → superpowers ведёт процесс | `roles/dev.md` → Процесс → Инструменты и их роли |
+| Роли инструментов → Gitea, одна фича = одна issue, порядок старта | `roles/dev.md` → Инструменты и их роли |
+| Роли инструментов → OpenSpec | `roles/dev.md` → Инструменты и их роли |
+| Роли инструментов → Ledger superpowers | `roles/dev.md` → Инструменты и их роли |
+| Маршрутизация → сообщение `[claude-harness]`, adopt-project.sh | `global/CLAUDE.md` → Хуки и ветки (сообщение); `roles/dev.md` → Маршрутизация (скрипт) |
+| Маршрутизация → bounded-задача | `roles/dev.md` → Маршрутизация (дополнено: спека при смене API, verification-before-completion) |
+| Маршрутизация → architectural-задача, спека в openspec/changes | `roles/dev.md` → Маршрутизация |
+| Маршрутизация → читать openspec/specs и ARCHITECTURE.md | `roles/dev.md` → Маршрутизация |
+| Маршрутизация → codegraph, projectPath, пустой ответ | `global/CLAUDE.md` → Хуки и ветки (init, projectPath); `roles/dev.md` → Инструменты (implementer, пустой ответ, замер) |
+| Исполнение → только в worktree, имя ветки | `roles/dev.md` → Исполнение |
+| Исполнение → SDD по умолчанию, контроллер на sonnet, executing-plans до 5 задач | `roles/dev.md` → Исполнение (дополнено: режим не спрашивать) |
+| Исполнение → модели исполнителей | `roles/dev.md` → Исполнение |
+| Завершение → finishing-a-development-branch, receiving-code-review, merge человеком | `roles/dev.md` → Завершение |
+| Завершение → чеклист закрытия п. 1 (архив в main) | `roles/dev.md` → Завершение п. 1 — изменено: архив всегда отдельным PR (решение владельца 11.10.2026) |
+| Завершение → чеклист п. 2–3 | `roles/dev.md` → Завершение п. 2–3 |
+| Завершение → чеклист п. 4 (удаление веток) | `roles/dev.md` → Завершение п. 4 — дополнено: из worktree, allow-правило |
+| Завершение → чеклист п. 5–7 | `roles/dev.md` → Завершение п. 5, 6, 8 (новый п. 7 — память, спека 7.1) |
+| Завершение → неприменимое к bounded пропускается | `roles/dev.md` → Завершение |
+| Завершение → любой другой push в main только через PR | `roles/dev.md` → Завершение п. 1 (без исключений) |
+| Завершение → «Rulings I made» в PR | `roles/dev.md` → Завершение |
+| Завершение → Decisions made without discussion | `roles/dev.md` → Завершение |
+| Маркировка → список маркеров | `global/CLAUDE.md` → Маркировка (кратко); `roles/dev.md` → Маркировка (полностью, + `RT-n`) |
+| Маркировка → статусы находок | `global/CLAUDE.md` → Маркировка; `roles/dev.md` → Маркировка |
+| Маркировка → таблица в финальном отчёте, deferred в PR и follow-up | `roles/dev.md` → Маркировка |
+| Стиль → не сжимать, caveman по команде | `global/CLAUDE.md` → Стиль |
+
+Новое, чего не было: раздел «Роль» (спека 4), раздел «Память» (спека 7.1), запрет обхода хуков (ретро, `feedback-no-harness-bypass`), `cd` при фоновом контроллере (RT-2), абсолютные пути worktree, trailer коммита (RT-9), предусловия окружения (RT-8).

global/CLAUDE.md

@@ -1,47 +1,24 @@
-# Процесс разработки
+# Правила сессии
 
-## Роли инструментов
-- Superpowers ведёт процесс внутри одной фичи: brainstorming → writing-plans → исполнение → ревью → finishing-a-development-branch.
-- Gitea (CLI `tea`) хранит задачи между сессиями. Одна фича = одна issue = одна ветка = один PR. Issue заводит агент (`tea issues create`) из формулировки цели, до brainstorming. Порядок: сначала worktree на временной ветке (хук не даёт писать на main), затем issue, затем ветка переименовывается в `feat/<issue-id>-<slug>`.
-- OpenSpec хранит требования. `openspec/specs/` — текущее поведение системы, `openspec/changes/<id>/` — дельта текущей фичи. Спека — единственный источник истины при рулингах.
-- Ledger superpowers (`.superpowers/sdd/`) — прогресс только внутри текущего плана. Задачи плана в Gitea не дублировать.
+## Роль
+- Сессия работает в одной из ролей: `dev`, `admin`, `analyst`, `qa`. Правила роли загружает `/role <r>`; новая роль заменяет предыдущую целиком.
+- Подсказка `[claude-harness] Роль сессии: <r>` от хука при старте — вызвать `/role <r>` до первого ответа.
+- Без подсказки: если роль очевидна из первого сообщения (Jira, Гант, спринт → admin; стенд, прогон, скриншот, макет → qa; ТЗ, OQ, спека, методика → analyst; срез, issue, PR, тест, миграция → dev) — объявить одной строкой «Роль: admin; если не так, скажи» и вызвать `/role`. Иначе — один вопрос с четырьмя вариантами.
+- Процесс и чеклисты роли — в её файле, не здесь.
 
-## Маршрутизация
-- Сообщение `[claude-harness]` в начале сессии означает, что обвязка к проекту не подключена: действовать по его инструкции до всего остального. Скрипт `~/.claude/harness/adopt-project.sh` — единственная разрешённая запись на main помимо архивации OpenSpec.
-- Bounded-задача (флаг, фикс, мелкая правка): без OpenSpec change и без плана. Дизайн в чате, затем создать файл `.bounded` в корне worktree (разрешает правки в src/ без плана; файл в `.gitignore`, в коммит не попадает), TDD, коммит, PR.
-- Architectural-задача: brainstorming пишет спеку не в `docs/superpowers/specs/`, а в `openspec/changes/<id>/`. В поле **Spec** плана указывается этот путь.
-- Перед architectural brainstorming прочитать релевантные файлы в `openspec/specs/` и ARCHITECTURE.md, если есть.
-- Карта кода — codegraph (MCP). MCP-сервер запускается в корне основного checkout и по умолчанию отвечает только по его индексу; код ветки в worktree он не видит. Поэтому сразу после создания worktree выполнить в нём `codegraph init` (индекс локальный, в git не попадает), а во всех вызовах `codegraph_explore` передавать `projectPath` = абсолютный путь worktree. Перед изменением implementer вызывает `codegraph_explore` по своей области вместо grep/Read по файлам. Если ответ всё же пуст — один раз отметить в ledger и дальше использовать Read, не тратя раунды на переиндексацию.
+## Хуки и ветки
+- guard-main блокирует запись на main/master и detached HEAD: работа только в worktree на ветке. require-plan: правки в коде только при плане для ветки или файле `.bounded`.
+- Сообщение `[claude-harness]` при старте — инструкция обвязки, выполняется до всего остального.
+- Хуки не обходить (`echo >`, API вместо `tea`). Если хук мешает — сказать владельцу.
+- codegraph: после создания worktree — `codegraph init` в нём; в `codegraph_explore` — `projectPath` = абсолютный путь worktree.
 
-## Исполнение
-- Работа только в worktree. Ветка называется по issue: `feat/<issue-id>-<slug>`.
-- Режим по умолчанию: subagent-driven-development. Контроллер SDD запускается как фоновый сабагент **на модели sonnet** (не на модели сессии) — сессия только ждёт его отчёт. Для планов до 5 задач — executing-plans (Native).
-- Модели исполнителей выбираются по SDD Model Selection: задача с готовым кодом в плане — haiku, интеграция — sonnet, ревью всей ветки — opus. Модель в dispatch указывать всегда.
+## Память
+- Состояние задачи живёт в трекере (Gitea issue, Jira), не в памяти.
+- В репозиторий направления (`<dir>/notes/`, память агента) пишутся уроки, решения владельца, рецепты. Коммит в той же ветке, что и работа.
+- В локальную auto-memory — только ловушки этой машины и обвязки и индекс со ссылками на `notes/` направлений.
 
-## Завершение
-- finishing-a-development-branch создаёт PR в Gitea (`tea pulls create`) и ссылается на issue. Комментарии к PR обрабатываются через receiving-code-review: агент читает их из Gitea, правит в той же ветке, отвечает в PR. Merge — только по явной команде человека.
-- После merge по команде «закрывай» выполняется весь чеклист закрытия, без остановок между пунктами:
-  1. `openspec archive <id>`, коммит и push архива прямо в main (единственное разрешённое исключение из правила «в main только через PR»: хук пропускает коммиты, затрагивающие только `openspec/`).
-  2. Issue закрывается (`tea issues close <id>`, комментарий со ссылкой на PR) только если все её пункты выполнены. Если PR закрывает часть пунктов (типично для follow-up issue) — issue остаётся открытой, в неё пишется комментарий: какие маркеры закрыты, каким PR и коммитом.
-  3. Удалить SDD workspace (`.superpowers/sdd/<plan>/`).
-  4. Удалить ветку фичи на сервере и локально (`git push origin --delete`, `git branch -D`), удалить worktree (`git worktree remove`). Остальные worktree не трогать.
-  5. Обновить основной checkout: если рабочее дерево там чистое — `git pull --ff-only`; если есть незакоммиченные изменения — не трогать, а перечислить их в итоговом сообщении.
-  6. Все находки со статусом `deferred` (см. «Маркировка») собрать в одну issue Gitea `tea issues create` с заголовком `Follow-ups from #<issue-id>`: маркер, одна строка, откуда взялось. Если отложенного нет — issue не создавать.
-  7. Итоговое сообщение: что сделано по пунктам 1–6, номер follow-up issue, что осталось человеку.
-  Пункты, не применимые к bounded-задаче (archive, SDD workspace), пропускаются с пометкой в итоговом сообщении.
-  Любой другой push в main — только через PR.
-- Список "Rulings I made" из финального сообщения копируется в описание PR.
-- Любое решение, принятое агентом без обсуждения с человеком — на этапе спеки, плана или исполнения — дописывается в `openspec/changes/<id>/design.md` в раздел `## Decisions made without discussion`: дата, решение, обоснование, что стоит ошибка. Ledger SDD удаляется, чат теряется; design.md архивируется вместе со спекой и остаётся в истории.
-
-## Маркировка находок и решений
-- Каждая находка и каждое решение в ledger, отчётах, PR и design.md несёт маркер источника. Маркер присваивается один раз и не меняется при переносе между документами.
-  - `T<n>.<k>` — k-я minor-находка ревьюера задачи n плана (`T4.1`, `T4.2`).
-  - `C-n` / `I-n` / `M-n` — critical / important / minor из финального ревью всей ветки.
-  - `R-n` — рулинг контроллера, сквозная нумерация в пределах фичи; рядом номер решения в design.md: `R-5 (design #33)`.
-  - `O-n` — наблюдение контроллера вне ревью (неточные отчёты, инструменты, окружение).
-  - `H-n` — замечание человека из PR, обработанное через receiving-code-review.
-- Каждая находка заканчивается одним из статусов: `fixed <commit>`, `deferred`, `rejected <причина>`. Находка без статуса в финальном отчёте — ошибка контроллера.
-- Финальный отчёт контроллера содержит таблицу всех находок с маркером и статусом; `deferred` попадают в описание PR и в follow-up issue при закрытии (чеклист, п. 6).
+## Маркировка
+- Каждая находка и каждое решение несёт маркер источника (`T<n>.<k>`, `C-n`/`I-n`/`M-n`, `R-n`, `O-n`, `H-n`, `RT-n`) и статус `fixed <commit>` / `deferred` / `rejected <причина>`. Маркер присваивается один раз. Подробности — в роли dev.
 
 ## Стиль
-- Отчёты сабагентов, рулинги и ledger не сжимать. Caveman включается только по явной команде.
+- Отвечать по-русски. Отчёты сабагентов, рулинги и ledger не сжимать; caveman — только по явной команде.

tests/test-sizes.sh

@@ -0,0 +1,13 @@
+# Размеры и обязательные строки глобального CLAUDE.md (спека 1, 4, 7.1, 8).
+G="$ROOT/global/CLAUDE.md"
+assert_max_bytes "global/CLAUDE.md ≤ 3 КБ" "$G" 3072
+assert_grep "правило выбора роли" 'Роль: admin; если не так' "$G"
+assert_grep "/role упомянут" '/role' "$G"
+assert_grep "политика памяти: трекер" 'Состояние задачи живёт в трекере' "$G"
+assert_grep "политика памяти: notes/" 'notes/' "$G"
+assert_grep "политика памяти: auto-memory" 'auto-memory' "$G"
+assert_grep "маркировка R-n" 'R-n' "$G"
+assert_grep "codegraph projectPath" 'projectPath' "$G"
+assert_grep "хук [claude-harness]" '\[claude-harness\]' "$G"
+assert_grep "worktree" 'worktree' "$G"
+assert_file "таблица адресов" "$ROOT/docs/retro/2026-10-11-claude-md-addresses.md"