docs: роли в HARNESS.md и README, CHANGELOG 0.3.0, решения плана в спеке

Refs #2

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

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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`.

CLAUDE.md

@@ -11,15 +11,18 @@
 - macOS и Linux; `python3` должен быть в PATH сессии Claude Code.
 
 ## Архитектура
-- `hooks/` — поведение обвязки, единственный «код» с логикой. `guard-main.sh` (PreToolUse на Edit/Write/MultiEdit/Bash): запрет записи на main/master/detached HEAD, исключение для openspec-only коммитов. `require-plan.sh` (PreToolUse на Edit/Write/MultiEdit): правки в каталогах кода только при плане для ветки или файле `.bounded`. `harness-check.sh` (SessionStart): проверка, что проект подключён. `settings.hooks.json` — блок, который `install.sh` сливает в `~/.claude/settings.json`.
+- `hooks/` — поведение обвязки, единственный «код» с логикой. `guard-main.sh` (PreToolUse на Edit/Write/MultiEdit/Bash): запрет записи на main/master/detached HEAD, исключение для openspec-only коммитов. `require-plan.sh` (PreToolUse на Edit/Write/MultiEdit): правки в каталогах кода только при плане для ветки или файле `.bounded`. `harness-check.sh` (SessionStart): проверка, что проект подключён. `role-hint.sh` (SessionStart, все источники): подсказка роли по `session_title`. `settings.hooks.json` — блок, который `install.sh` сливает в `~/.claude/settings.json`.
 - `install.sh`, `adopt-project.sh`, `new-project.sh` — установка и бутстрап. `install.sh` копирует `global/`, `hooks/`, `project-template/`, `adopt-project.sh`, `new-project.sh` и `skills/harness-doctor` в `~/.claude/{CLAUDE.md,hooks,harness,skills}`. `adopt-project.sh` работает на ветке `chore/harness-init` и вливает её ff в текущую ветку; это единственная разрешённая запись на main вне PR.
 - `global/CLAUDE.md` — глобальные правила процесса, ставятся в `~/.claude/CLAUDE.md`. `project-template/` — `CLAUDE.md`, `CLAUDE.harness-section.md` (секция «OpenSpec и superpowers», по ней `harness-check` узнаёт подключённый проект), `ARCHITECTURE.md`, `gitignore`.
 - `skills/harness-doctor/` — skill диагностики: `scripts/doctor.sh` снимает состояние машины и проекта и прогоняет самотест хуков; `SKILL.md` — чеклист прочтения отчёта.
+- `roles/` — общий слой ролей (формат: четыре раздела, см. спеку ролей), `skills/role/` — skill `/role`, `agents/briefing.md` — агент выжимки, `link-roles.sh` — симлинки workspace → репозитории направлений. Ставятся `install.sh` в `~/.claude/{roles,skills/role,agents,harness}`.
+- `tests/` — тесты пакета на bash: `run.sh` + `test-*.sh`, работают с источниками, `install.sh` ставят во временный `CLAUDE_CONFIG_DIR`.
 - `caveman/config.json` — выключенный по умолчанию caveman. `examples/` — реальный `CLAUDE.md` проекта-пилота.
 - `docs/HARNESS.md` — как устроен цикл фичи, SDD, маркировка, закрытие. `docs/PILOT-2026-09-27.md` — пилот. `docs/retro/` — ретроспектива 11.10.2026 и скрипты подсчёта по транскриптам. `docs/superpowers/specs/` — спеки фич обвязки, `docs/superpowers/plans/` — планы.
 - Связь слоёв: хуки читают JSON вызова из stdin и состояние git проекта; скрипты бутстрапа читают `project-template/`; `doctor.sh` читает установленные копии в `~/.claude`, не репозиторий.
 
 ## Команды
+- `bash tests/run.sh [имя]` — весь набор тестов. Зелёным считается только весь набор.
 - `bash install.sh --check` — проверка окружения: бинарники, плагины, конфликты.
 - `bash install.sh` — установка глобальной части, идемпотентно.
 - `bash skills/harness-doctor/scripts/doctor.sh [проект]` — отчёт и самотест хуков. Только чтение.
@@ -28,7 +31,7 @@
 - `python3 docs/retro/scripts/retro_stats.py <каталог транскриптов>` и `retro_blocks.py` — статистика сессий и блокировок хуков для ретро.
 
 ## Тесты
-- Отдельного набора тестов нет. Единственная автоматическая проверка — самотест хуков в `doctor.sh`: фиктивные вызовы Write/Bash на main и на ветке, `src/` с планом и без, `.bounded`. Прогоняется по установленным копиям, поэтому перед проверкой изменений в `hooks/` сначала `bash install.sh`.
+- `tests/run.sh` — автоматические тесты источников (хуки через фиктивный JSON, скрипты во временных каталогах, размеры). Самотест хуков в `doctor.sh` проверяет установленные копии; перед ним `bash install.sh`.
 - Ручная проверка хука: на main в любом репозитории попросить агента создать файл, ожидается `BLOCKED`.
 - Регрессионные тесты хуков на реальных командах из транскриптов — бэклог ретро B2, пока не сделаны.
 

README.md

@@ -11,6 +11,7 @@
 | Текущее поведение системы | OpenSpec | требования, дельты, история решений | `npm i -g @fission-ai/openspec` |
 | Карта кода | codegraph (MCP) | связи символов для сабагентов | `brew install`/`npm i -g` |
 | Контекст по модулям | вложенные CLAUDE.md, ARCHITECTURE.md | границы, конвенции | этот пакет |
+| Роль сессии | `roles/`, skill `/role`, агент `briefing`, хук `role-hint.sh` | правила, файлы и память своей роли | этот пакет |
 | Жёсткие правила | `guard-main.sh`, `require-plan.sh` (PreToolUse) | то, что нельзя доверять промпту | этот пакет |
 
 Что **не** входит и почему: beads (дублирует Gitea), template-bridge (устарел, дублирует ledger), caveman по умолчанию (сжимает отчёты и рулинги; остаётся доступен по `/caveman`).
@@ -27,6 +28,14 @@ project-template/         CLAUDE.md, ARCHITECTURE.md, gitignore для ново
 examples/                 реальный CLAUDE.md проекта-пилота
 install.sh                установка глобальной части, идемпотентно; --check проверяет окружение
 new-project.sh            каркас нового проекта: git, CLAUDE.md, openspec init, codegraph init, remote
+roles/<r>.md              общий слой ролей dev/admin/analyst/qa → ~/.claude/roles/
+skills/role/SKILL.md      /role <r>: загрузить роль, память, запустить briefing → ~/.claude/skills/role/
+agents/briefing.md        выжимка состояния для роли (sonnet, только чтение) → ~/.claude/agents/
+hooks/role-hint.sh        подсказка роли по заголовку сессии (SessionStart)
+link-roles.sh             симлинки ролей/агентов из workspace в репозитории направлений → ~/.claude/harness/
+project-template/workspace/   CLAUDE.md workspace с таблицей репозиториев, roles/dev.md
+project-template/role-repo/   репозиторий направления: CLAUDE.md, ROLE.md, notes/README.md
+tests/run.sh              тесты пакета (bash): bash tests/run.sh
 docs/HARNESS.md           как это работает: слои, цикл фичи, SDD, дисциплина закрытия
 docs/PILOT-2026-09-27.md  результаты пилота и находки
 ```
@@ -39,6 +48,21 @@ bash ~/projects/cc-skills/claude-harness/adopt-project.sh ~/projects/foo   # [--
 
 Запускать из терминала, не из Claude Code: хук guard-main не даёт агенту писать на main, а бутстрап — это запись на main. Скрипт делает ветку `chore/harness-init`, дописывает секцию харнеса в существующий `CLAUDE.md` (или создаёт его из шаблона), добавляет `ARCHITECTURE.md`, строки в `.gitignore`, `openspec init`, `codegraph init`, коммитит и вливает в main fast-forward. Заполнить описание проекта в `CLAUDE.md` потом можно агентом bounded-задачей на ветке.
 
+## Workspace из нескольких репозиториев и роли
+
+```
+bash ~/.claude/harness/adopt-project.sh --workspace ~/projects/foo                      # есть каталог с репозиториями
+bash ~/.claude/harness/new-project.sh --workspace ~/projects/foo --role admin --role qa # с нуля
+```
+
+Заполните таблицу репозиториев в `CLAUDE.md` workspace и перезапустите `link-roles.sh`. Сессии запускайте из корня workspace с ролью в заголовке: `claude -n "admin спринт 3"`. Удобно завести алиасы в профиле shell (обвязка их не ставит):
+
+```bash
+alias cc-dev='claude -n "dev"'; alias cc-admin='claude -n "admin"'; alias cc-qa='claude -n "qa"'; alias cc-analyst='claude -n "analyst"'
+```
+
+В сессии: `/role` — текущая роль и список; `/role admin` — переключить. Подробности в `docs/HARNESS.md`, раздел «Роли».
+
 ## Установка
 
 ```bash
@@ -58,6 +82,7 @@ bash install.sh
 
 # 4. Проверка хука: в любом репозитории на main запустить claude и попросить создать файл.
 #    Ожидается BLOCKED и предложение создать worktree.
+#    bash tests/run.sh — тесты пакета должны быть зелёными.
 ```
 
 ## Новый проект

docs/HARNESS.md

@@ -72,13 +72,26 @@ Fix loop: раунды 1–3 продолжают того же implementer, 4
 | Никаких изменений на main / detached HEAD | `guard-main.sh`, PreToolUse на Edit/Write/MultiEdit/Bash | проверяет ветку; для Bash блокирует команды, похожие на запись (`>`, `tee`, `sed -i`, `mv`, `rm`, `git commit/push`…), пропускает `git worktree add`; коммит/push в main разрешены только если изменены исключительно файлы в `openspec/` (архивация) |
 | Правки в коде только при плане или `.bounded` | `require-plan.sh`, PreToolUse на Edit/Write/MultiEdit | защищает любой `src/` на любой глубине (`api/src/`, `packages/*/src/`) или каталоги из `.claude/code-paths`; ищет план в `docs/superpowers/plans/` для текущей ветки или файл `.bounded` |
 | Обвязка подключена к проекту | `harness-check.sh`, SessionStart | при старте сессии проверяет `openspec/`, `.codegraph/`, секцию в CLAUDE.md; если чего-то нет — пишет агенту инструкцию запустить `~/.claude/harness/adopt-project.sh` (спросив пользователя; `HARNESS_AUTO_ADOPT=1` — без вопроса) |
+| Подсказка роли по заголовку сессии | `role-hint.sh`, SessionStart (все источники) | читает `session_title`; если начинается с `dev|admin|analyst|qa` — одна строка-подсказка вызвать `/role`; ничего не блокирует |
 | Тесты зелёные перед коммитом | git pre-commit в проекте (не входит в пакет) | обычный git-хук с командой тестов |
 
 Exit 2 блокирует вызов и показывает агенту stderr, поэтому агент сам делает то, что просит сообщение. Оба обхода, замеченные на пилоте (запись через `echo >` вместо Write; push через detached HEAD), закрыты.
 
 ## Дисциплина между сессиями
 
-Новая сессия начинается с `tea issues ls` и `openspec list`, а не с памяти о прошлой. Незавершённый план возобновляется из ledger в worktree. Связка разваливается не на исполнении, а на закрытии — поэтому «закрывай» выполняет весь чеклист без остановок.
+Новая сессия начинается с роли (`/role`), затем `tea issues ls` и `openspec list`, а не с памяти о прошлой. Незавершённый план возобновляется из ledger в worktree. Связка разваливается не на исполнении, а на закрытии — поэтому «закрывай» выполняет весь чеклист без остановок.
+
+## Роли
+
+Одна сессия — одна роль: `dev`, `admin`, `analyst`, `qa`. Роль даёт сессии только свои правила, свои файлы на старте и свой раздел памяти; процесс разработки (superpowers → Gitea → OpenSpec, SDD, чеклист закрытия) живёт в роли dev и не загружается в сессии admin.
+
+Два слоя, оба в git: общий — `~/.claude/roles/<r>.md` (из пакета, `install.sh`), проектный — `<workspace>/.claude/roles/<r>.md` (для dev — файл, для остальных — симлинк в репозиторий направления `admin/`, `qa/`, `analysis/`). Формат одинаковый: четыре раздела «Процесс», «Читать на старте», «Не делать», «Делегировать»; при конфликте побеждает проектный слой.
+
+Выбор роли, от автоматического к ручному: заголовок сессии (`claude -n "admin …"`; хук `role-hint.sh` печатает подсказку `[claude-harness] Роль сессии: admin`), вывод из первого сообщения (правило в глобальном CLAUDE.md: объявить «Роль: admin; если не так, скажи»), явно — `/role <r>`. Skill `/role` читает оба слоя, раздел памяти роли, строки «Читать на старте», а строки с префиксом `brief:` отдаёт фоновому агенту `briefing`, который возвращает выжимку: активные задачи, решения, открытые вопросы, ловушки.
+
+Workspace из нескольких репозиториев (не git, cwd всех сессий) описывается таблицей `| Каталог | Репозиторий | Роль |` в его CLAUDE.md; `link-roles.sh` по ней создаёт симлинки на проектные файлы ролей и агентов направлений. Память агентов (`memory: project`) через симлинк каталога не работает (проверено 2026-10-11, спека, раздел 11), поэтому агентам направлений применяется запасной вариант спеки 6.5: поле `memory` не используется, промпт агента велит читать `<dir>/notes/agent-memory.md` при старте и дописывать в конце. `adopt-project.sh --workspace` и `new-project.sh --workspace --role …` собирают workspace из шаблонов; `doctor.sh` проверяет ссылки и размеры.
+
+Политика памяти (глобальный CLAUDE.md): состояние задачи — в трекере; уроки, решения владельца и рецепты — в `notes/` направления и памяти агентов (в git); в локальной auto-memory — только ловушки машины и индекс со ссылками. При закрытии файл auto-memory задачи сворачивается в строку `registry-closed.md`.
 
 ## Стоимость
 

docs/superpowers/specs/2026-10-11-roles-and-memory-design.md

@@ -285,3 +285,9 @@ SDD-контроллер и implementer-ы остаются описанием
   Цена ошибки: выжимка приходит после первого ответа; если это мешает, флаг `--wait`.
 - 11.10.2026. Спека лежит в `docs/superpowers/specs/` репозитория обвязки, а не в `openspec/`: обвязка к самой себе не
   подключена, OpenSpec в ней нет. Вопрос «подключать ли обвязку к обвязке» открыт, владельцу не задавался. Цена ошибки: перенос файла.
+- 11.10.2026 (план). Тесты пакета — `tests/run.sh` на bash в репозитории, в дополнение к самотесту `doctor.sh` (спека, раздел 8, упоминала только doctor). Обоснование: TDD по задачам плана невозможен против установленных копий. Цена ошибки: лишний каталог.
+- 11.10.2026 (план). Хук `role-hint.sh` регистрируется записью без `matcher` (документация: отсутствующий matcher = все источники), а не перечислением `startup|resume|clear|compact`. Цена ошибки: одна строка в `settings.hooks.json`.
+- 11.10.2026 (план). Формат таблицы репозиториев workspace зафиксирован: `| Каталог | Репозиторий | Роль |`; `link-roles.sh` и `doctor.sh` узнают workspace по заголовку этой таблицы. Цена ошибки: правка двух regex.
+- 11.10.2026 (план). `role-hint.sh` понимает заголовок без учёта регистра и с префиксом `cc-` (алиасы из README). Цена ошибки: нет.
+- 11.10.2026 (план). Часть 2 (awp-ca: проектные файлы ролей, агенты jira-admin/qa-runner, репозитории направлений, чистка памяти, песочница, перенос) — отдельный план в workspace awp-ca после merge этой ветки; каталог для роли analyst — `analysis/`. Цена ошибки: нет.
+- 11.10.2026 (план). Чеклист закрытия получил п. 7 (память задачи, спека 7.1) и новый п. 8 (итоговое сообщение); нумерация старых п. 1–6 сохранена.