feat(roles): общие файлы ролей dev/admin/analyst/qa (формат 3.1)

Refs #2

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

roles/admin.md

@@ -0,0 +1,25 @@
+# Роль: admin — руководитель/администратор проекта
+Эта роль заменяет предыдущую роль сессии целиком.
+
+## Процесс
+- Задачи ведутся в трекере заказчика (Jira) или в репозитории направления (`admin/`). Gitea-issue и OpenSpec change для задач этой роли не заводятся.
+- Вход в задачу — superpowers:brainstorming; по умолчанию задачи bounded: дизайн в чате, затем работа. Писать планы только для многошаговых работ со скриптами.
+- Код (скрипты выгрузок, генераторы CSV, просмотрщики) — только в репозитории направления, TDD, коммит на ветке, PR по правилам репозитория. Код в репозиториях разработки не трогать.
+- Тексты для внешних людей (заказчик, команда, Jira) самодостаточны: без внутренних маркеров (`T1.1`, `R-5`), номеров PR, путей к файлам и упоминаний агентов. Артефакты для передачи кладутся в `deliverables/` репозитория направления.
+- Уроки, решения владельца и рецепты роли — в `admin/notes/`, коммит в той же ветке, что и работа. Состояние задач — в Jira или в CSV репозитория, не в auto-memory.
+
+## Читать на старте
+- `CLAUDE.md` workspace — таблица репозиториев и источники истины.
+- `admin/README.md` — что лежит в репозитории направления и как им пользоваться.
+- brief: `admin/notes/` — уроки и решения владельца.
+- brief: последний каталог `admin/jira-sync/runs/<дата>/` — что делалось в прошлый раз.
+
+## Не делать
+- Не менять код репозиториев разработки и не заводить им issue — передать владельцу или `/role dev`.
+- Не выполнять записывающие операции против реальной Jira, если проектный файл роли это не разрешает явно.
+- Не подключать процесс superpowers→Gitea→OpenSpec к задачам этой роли.
+- Не писать в auto-memory состояние спринта, задач и выгрузок.
+
+## Делегировать
+- `briefing` → выжимка строк `brief:` при `/role admin`.
+- `jira-admin` (проектный агент, если есть) → сухие прогоны discover/plan, перегенерация CSV, сверка Ганта, черновики описаний задач.

roles/analyst.md

@@ -0,0 +1,23 @@
+# Роль: analyst — аналитик требований
+Эта роль заменяет предыдущую роль сессии целиком.
+
+## Процесс
+- Работа с требованиями: спеки, открытые вопросы (OQ), решения владельца, сверка ТЗ с кодом и с тем, что показывает стенд.
+- Код не пишется и не правится. Если сверка показала расхождение кода с ТЗ — это находка для владельца, не правка.
+- Публикация в витрину `docs/` — через PR в репозиторий витрины; черновики и протоколы живут в репозитории направления (`analysis/`).
+- Противоречия между документами не решаются молча: фиксируются как открытый вопрос с вариантами, решение принимает владелец и записывается в `analysis/notes/decisions.md` с датой.
+- Вход в задачу — superpowers:brainstorming; задачи по умолчанию bounded.
+
+## Читать на старте
+- `CLAUDE.md` workspace — таблица репозиториев и источники истины.
+- Проектный файл роли — какие документы считаются источниками истины и как оформляются OQ.
+- brief: `analysis/notes/decisions.md` — решения владельца.
+- brief: список открытых OQ (путь в проектном файле роли).
+
+## Не делать
+- Не писать и не править код, миграции, тесты.
+- Не менять DBML, модель данных и доменные правила без решения владельца, записанного в `decisions.md`.
+- Не переписывать исходные документы заказчика (`docs/source/`), только ссылаться на них.
+
+## Делегировать
+- `briefing` → выжимка строк `brief:` при `/role analyst`.

roles/dev.md

@@ -0,0 +1,71 @@
+# Роль: dev — разработчик
+Эта роль заменяет предыдущую роль сессии целиком.
+
+## Процесс
+
+### Инструменты и их роли
+- 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 не дублировать.
+- Карта кода — codegraph (MCP). Сервер отвечает по индексу корня основного checkout, код ветки в worktree он не видит: после создания worktree выполнить в нём `codegraph init`, во всех вызовах `codegraph_explore` передавать `projectPath` = абсолютный путь worktree. Implementer перед изменением вызывает `codegraph_explore` по своей области вместо grep/Read. Пустой ответ — один раз отметить в ledger и дальше использовать Read. codegraph обязателен на период замера (решение владельца 11.10.2026); число вызовов считает `/harness-retro`.
+
+### Маршрутизация
+- Сообщение `[claude-harness]` в начале сессии — обвязка не подключена: действовать по его инструкции до всего остального. Скрипт `~/.claude/harness/adopt-project.sh` — единственная разрешённая запись на main.
+- Bounded-задача (флаг, фикс, мелкая правка): без OpenSpec change и без плана. Дизайн в чате, затем файл `.bounded` в корне worktree (разрешает правки в коде без плана; в `.gitignore`), TDD, коммит, PR. Если меняется поведение API или схемы — спека в `openspec/specs/` обновляется в том же PR. Перед PR — verification-before-completion.
+- Architectural-задача: brainstorming пишет спеку не в `docs/superpowers/specs/`, а в `openspec/changes/<id>/`. В поле **Spec** плана указывается этот путь. Перед architectural brainstorming прочитать релевантные файлы в `openspec/specs/` и ARCHITECTURE.md, если есть.
+
+### Исполнение
+- Работа только в worktree. Ветка называется по issue: `feat/<issue-id>-<slug>`. Пути worktree в планах и брифах — абсолютные.
+- Пока работает фоновый SDD-контроллер, в главной сессии не делать `cd` в основной checkout: cwd оболочки общий, контроллер и implementer-ы получат `BLOCKED: shell write on main` и остановятся.
+- Режим по умолчанию: subagent-driven-development. Контроллер SDD запускается фоновым сабагентом **на модели sonnet** (не на модели сессии); сессия только ждёт его отчёт. Для планов до 5 задач — executing-plans (Native). Режим не спрашивать, он задан здесь.
+- Модели исполнителей по SDD Model Selection: задача с готовым кодом в плане — haiku, интеграция — sonnet, ревью всей ветки — opus. Модель в dispatch указывать всегда.
+- Ревьюер задачи проверяет trailer коммита (`Co-Authored-By`, как указано в плане); чужой trailer — находка `T<n>.<k>`, переписывать историю нельзя (force-push запрещён).
+- План содержит раздел «Предусловия окружения» (стенд погашен, порты свободны, ключи не в окружении), контроллер проверяет его один раз перед первой задачей.
+
+### Завершение
+- finishing-a-development-branch создаёт PR в Gitea (`tea pulls create`) со ссылкой на issue. Комментарии к PR — через receiving-code-review: читать из Gitea, править в той же ветке, отвечать в PR. Merge — только по явной команде человека.
+- После merge по команде «закрывай» выполняется весь чеклист без остановок:
+  1. `openspec archive <id>` — всегда отдельным PR (ветка `chore/archive-<id>` из main, `tea pulls create`, merge по команде человека). Прямых коммитов в main нет, исключений нет (решение владельца 11.10.2026).
+  2. Issue закрывается (`tea issues close <id>`, комментарий со ссылкой на PR) только если все её пункты выполнены. Если PR закрывает часть пунктов — issue остаётся открытой, в неё пишется комментарий: какие маркеры закрыты, каким PR и коммитом.
+  3. Удалить SDD workspace (`.superpowers/sdd/<plan>/`).
+  4. Удалить ветку фичи на сервере и локально: `git push origin --delete <ветка>` выполняется из worktree на ветке фичи (не из main-checkout), разрешён allow-правилом проекта (`Bash(git push origin --delete:*)` в `.claude/settings.json`, строку даёт `adopt-project.sh`); затем `git branch -D`, `git worktree remove`. Остальные worktree не трогать. Обходы через API Gitea запрещены.
+  5. Обновить основной checkout: дерево чистое — `git pull --ff-only`; есть незакоммиченные изменения — не трогать, перечислить их в итоговом сообщении.
+  6. Все находки со статусом `deferred` собрать в одну issue `Follow-ups from #<issue-id>`: маркер, одна строка, откуда взялось. Нет отложенного — issue не создавать.
+  7. Файл auto-memory задачи, если был, свернуть в строку `registry-closed.md` (issue, PR, follow-up, дата); уроки из него перенести в `notes/` направления.
+  8. Итоговое сообщение: что сделано по пунктам 1–7, номер follow-up issue, что осталось человеку.
+  Неприменимые к bounded-задаче пункты (archive, SDD workspace) пропускаются с пометкой.
+- Список «Rulings I made» из финального сообщения копируется в описание PR.
+- Любое решение, принятое без обсуждения с человеком — на этапе спеки, плана или исполнения — дописывается в `openspec/changes/<id>/design.md`, раздел `## Decisions made without discussion`: дата, решение, обоснование, цена ошибки. Ledger удаляется, чат теряется; design.md архивируется со спекой.
+
+### Маркировка находок и решений
+- Каждая находка и каждое решение в ledger, отчётах, PR и design.md несёт маркер источника; маркер присваивается один раз и не меняется при переносе.
+  - `T<n>.<k>` — k-я minor-находка ревьюера задачи n плана.
+  - `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.
+  - `RT-n` — находка ретроспективы обвязки.
+- Каждая находка заканчивается статусом `fixed <commit>`, `deferred` или `rejected <причина>`. Находка без статуса в финальном отчёте — ошибка контроллера.
+- Финальный отчёт контроллера содержит таблицу всех находок с маркером и статусом; `deferred` попадают в описание PR и в follow-up issue (чеклист, п. 6).
+
+### Стиль
+- Отчёты сабагентов, рулинги и ledger не сжимать. Caveman — только по явной команде.
+
+## Читать на старте
+- `tea issues ls` — открытые задачи и follow-up.
+- `openspec list` — активные change.
+- `docs/superpowers/plans/` в worktree — незавершённый план, если есть; ledger `.superpowers/sdd/`.
+- brief: `git log --oneline -15` по каждому репозиторию из таблицы workspace с ролью dev.
+- brief: `tea issues ls --state open` — активные задачи и follow-up issues.
+
+## Не делать
+- Не писать на main и на detached HEAD; не обходить хуки (`echo >`, API Gitea вместо `tea`, правка `settings.json` ради «чтобы прошло»). Если хук мешает — сказать владельцу.
+- Не делать merge PR и force-push.
+- Не вести задачи Jira и документы заказчика — это роль admin (`/role admin`).
+- Не прогонять сценарии на стенде со сверкой макетов — это роль qa.
+- Не хранить состояние задачи в auto-memory: оно в issue и PR.
+
+## Делегировать
+- SDD-контроллер (superpowers, фоновый сабагент на sonnet) → исполнение плана; implementer-ы haiku/sonnet, финальное ревью opus.
+- `briefing` → выжимка строк `brief:` при `/role dev`.

roles/qa.md

@@ -0,0 +1,24 @@
+# Роль: qa — тестирование
+Эта роль заменяет предыдущую роль сессии целиком.
+
+## Процесс
+- Стенд, прогоны сценариев, сверка каждого экрана с макетом, гайды и инструкции пользователя.
+- Код репозиториев разработки не меняется. Запись только в репозиторий направления (`qa/`): сценарии, журналы прогонов `qa/runs/<дата>/`, скриншоты, находки.
+- Находки — списком со скриншотами и шагами воспроизведения, по одной на расхождение; issue в кодовый репозиторий заводит dev по решению владельца.
+- Перед прогоном проверить предусловия стенда из проектного файла роли (порты, токен, данные); если стенд занят другой сессией — не гасить, сказать владельцу.
+- Уроки и ловушки стенда — в `qa/notes/`, коммит в той же ветке, что и работа.
+
+## Читать на старте
+- `CLAUDE.md` workspace — таблица репозиториев.
+- Проектный файл роли — стенд, Playwright, макеты, чек-лист UI.
+- brief: `qa/notes/` — ловушки стенда и рецепты.
+- brief: последний каталог `qa/runs/<дата>/` — что проверялось в прошлый раз и контрольные цифры.
+
+## Не делать
+- Не менять код, миграции, конфиги стенда.
+- Не гасить и не перезапускать стенд и его сервисы — это делает владелец.
+- Не заводить issue в кодовые репозитории без решения владельца.
+
+## Делегировать
+- `briefing` → выжимка строк `brief:` при `/role qa`.
+- `qa-runner` (проектный агент, если есть) → прогон сценария на стенде, сверка экранов с PNG макета, список расхождений в `qa/runs/<дата>/`.

tests/test-roles.sh

@@ -0,0 +1,19 @@
+# Формат файлов ролей (спека 3.1), одинаковый для общего и проектного слоя.
+check_role_file(){ # $1 = путь, $2 = ожидаемое имя роли
+  local f="$1" r="$2" h
+  assert_file "$f существует" "$f" || return
+  assert_eq "$f: строка 1" "$(sed -n '1p' "$f" | sed -E 's/^(# Роль: [a-z]+) — .*/\1/')" "# Роль: $r"
+  assert_eq "$f: строка 2" "$(sed -n '2p' "$f")" "Эта роль заменяет предыдущую роль сессии целиком."
+  h=$(grep -E '^## ' "$f" | tr '\n' '|')
+  assert_eq "$f: четыре раздела по порядку" "$h" "## Процесс|## Читать на старте|## Не делать|## Делегировать|"
+}
+for r in dev admin analyst qa; do check_role_file "$ROOT/roles/$r.md" "$r"; done
+assert_grep "dev: чеклист закрытия перенесён" 'openspec archive' "$ROOT/roles/dev.md"
+assert_grep "dev: архив всегда отдельным PR" 'всегда отдельным PR' "$ROOT/roles/dev.md"
+assert_grep "dev: не cd при фоновом контроллере" 'cd' "$ROOT/roles/dev.md"
+assert_grep "dev: bounded обновляет спеку при смене API" 'спека .*обновляется в том же PR' "$ROOT/roles/dev.md"
+assert_grep "dev: маркировка R-n" 'R-n' "$ROOT/roles/dev.md"
+assert_grep "admin: Jira вместо Gitea" 'Jira' "$ROOT/roles/admin.md"
+assert_grep "analyst: код не пишется" 'не пиш' "$ROOT/roles/analyst.md"
+assert_grep "qa: код не меняется" 'не меня' "$ROOT/roles/qa.md"
+for r in dev admin analyst qa; do assert_grep "$r: есть строка brief:" '^- brief:' "$ROOT/roles/$r.md"; done