Compare commits
20 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Дмитрий
|
515acb654c | ||
|
Дмитрий
|
7bc9ded118 | ||
|
Дмитрий
|
30d1a3c756 | ||
|
Дмитрий
|
7e167cf943 | ||
|
Дмитрий
|
cb5bb7dbaf | ||
|
Дмитрий
|
942f5364e8 | ||
|
Дмитрий
|
fcba06172a | ||
|
Дмитрий
|
947290f1dc | ||
|
Дмитрий
|
14f405a84a | ||
|
Дмитрий
|
781a59cbf6 | ||
|
Дмитрий
|
b1765e98f7 | ||
|
Дмитрий
|
c2c9210317 | ||
|
Дмитрий
|
07eacdbceb | ||
|
Дмитрий
|
ef5da8def8 | ||
|
Дмитрий
|
78bae4addf | ||
|
Дмитрий
|
049eaf0dfc | ||
|
Дмитрий
|
1ab84d8038 | ||
|
Дмитрий
|
83a8d58096 | ||
|
Дмитрий
|
8dbdd5aac0 | ||
|
Дмитрий
|
235b1d4e8c |
@@ -64,6 +64,15 @@
|
||||
"command": "node -e \"const f=process.env.CLAUDE_FILE_PATH||''; const pd=process.env.CLAUDE_PROJECT_DIR||''; const path=require('path'); if (f && pd && path.resolve(f) === path.resolve(pd, 'CLAUDE.md')) { process.stderr.write('\\n[hook] WARNING: Direct edit of root CLAUDE.md detected. Per CLAUDE.md §5 п.10, prefer /claude-md-management:revise-claude-md or /claude-md-management:claude-md-improver. If invoked via that skill, this warning is informational.\\n'); }\""
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "Task",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node \"C:/моя/проекты/портал crm/Документация/tools/subagent-prompt-prefix.mjs\""
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: Project-local wrapper для superpowers:subagent-driven-development — добавляет обязательный git-safety verify-протокол per Pravila §15.1. Использовать вместо marketplace-варианта при работе с git-коммит-задачами в субагентах.
|
||||
---
|
||||
|
||||
# Subagent-Driven Development (project wrapper)
|
||||
|
||||
Этот скил — проектная обёртка над marketplace-скилом `superpowers:subagent-driven-development`. Дополняет его обязательным git-safety verify-протоколом per Pravila §15.1.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
Когда нужно делегировать задачу субагенту через Task tool — особенно git-коммит-задачи (Sprint 6 прецедент: Haiku-субагенты угнали ветку параллельной сессии).
|
||||
|
||||
## Что делать
|
||||
|
||||
1. **Откройте marketplace-скил** `superpowers:subagent-driven-development` для общего workflow (fresh subagent per task + two-stage review).
|
||||
2. **Перед каждой Task-инвокацией** прочитайте и выполните pre-spawn-чеклист — [references/git-safety-checklist.md](references/git-safety-checklist.md) §A.
|
||||
3. **После каждой Task-инвокации** прочитайте и выполните post-subagent-чеклист — там же §B.
|
||||
4. **Hard-rule §15.1** — git-коммит-задача = модель Sonnet/Opus, никогда Haiku. Read-only git-операции (`log`, `status`, `diff`, `rev-parse`, `branch --show-current`, `worktree list`) разрешены любой модели.
|
||||
|
||||
Хук `tools/subagent-prompt-prefix.mjs` (зарегистрирован в `.claude/settings.json`) автоматически инжектит git-safety заголовок в каждый Task-prompt — это **первая** линия защиты. Чеклист из этого скила — **вторая** линия (защита со стороны контроллера).
|
||||
|
||||
## Cross-refs
|
||||
|
||||
- Pravila §15.1 — hard-rule субагенты + git.
|
||||
- Spec: `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md` §5.
|
||||
- Memory: `memory/feedback_subagent_git_reliability.md`.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Git-safety Checklist для контроллера субагентов
|
||||
|
||||
Per Pravila §15.1 — выполнять каждый раз при делегировании задачи через Task tool.
|
||||
|
||||
## §A. Pre-spawn чеклист (до Task-инвокации)
|
||||
|
||||
1. **Резолвите 4 значения** (запишите у себя для post-check):
|
||||
|
||||
```bash
|
||||
git branch --show-current # → ожидаемая ветка
|
||||
git rev-parse HEAD # → pre-spawn parent SHA
|
||||
git rev-parse --show-toplevel # → worktree root
|
||||
pwd # → cwd
|
||||
```
|
||||
|
||||
2. **Выберите модель** субагенту:
|
||||
- Задача требует `git commit`/`push`/`stage`/`checkout`/`switch`/`merge`/`rebase`? → **Sonnet или Opus**, никогда Haiku (§15.1).
|
||||
- Только read-только `git log`/`status`/`diff`/`rev-parse` ИЛИ только Edit/Read/Grep? → любая модель.
|
||||
3. **Если задача правит нормативку из списка §15.2** (Pravila / CLAUDE.md / Tooling / PSR_v1 / MEMORY.md / Открытые_вопросы / docs/adr/* / db/schema.sql):
|
||||
|
||||
```bash
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
```
|
||||
|
||||
Не пусто → **ребейз/merge до инвокации**, не после. Pre-flight также проверить `docs/sessions/CURRENT.md` на конфликт scope-files / version-claims.
|
||||
|
||||
## §B. Post-subagent чеклист (сразу после возврата субагента)
|
||||
|
||||
1. **`git rev-parse HEAD`** — сравнить с pre-spawn parent SHA.
|
||||
- Равно → субагент не коммитил (OK для Edit-задач без commit).
|
||||
- Отличается ровно одним коммитом, чей parent = pre-spawn HEAD → OK для commit-задач.
|
||||
- **Иначе → STOP, разбор инцидента.**
|
||||
2. **`git branch --show-current`** — сравнить с pre-spawn branch.
|
||||
- Не равно → **STOP, разбор инцидента** (Sprint 6 паттерн).
|
||||
3. **`git log -1 --format='%s%n%P'`** — проверить subject + parent последнего коммита.
|
||||
- Subject соответствует задаче?
|
||||
- Parent = pre-spawn HEAD?
|
||||
4. Если несколько коммитов — ручная проверка subject'ов каждого.
|
||||
|
||||
## §C. Red-flag-список — любой = hard-stop разбор
|
||||
|
||||
- `branch ≠ ожидаемая`;
|
||||
- `parent коммита ≠ pre-spawn HEAD` (висячий коммит / попадание на чужую ветку);
|
||||
- HEAD двинулся, но субагент в отчёте об этом не упомянул;
|
||||
- в diff'е есть файлы вне scope задачи.
|
||||
|
||||
## §D. Обязательный формат отчёта субагента
|
||||
|
||||
Субагент в конце ответа выписывает блок:
|
||||
|
||||
```
|
||||
=== GIT REPORT ===
|
||||
cwd: <pwd>
|
||||
branch: <git branch --show-current>
|
||||
HEAD: <git rev-parse HEAD>
|
||||
HEAD^: <git rev-parse HEAD^>
|
||||
status: <git status --short>
|
||||
=== END GIT REPORT ===
|
||||
```
|
||||
|
||||
Отсутствие блока = контроллер считает результат недостоверным и запускает §B-чеклист сам через Bash.
|
||||
|
||||
## §E. Соотношение с code-review
|
||||
|
||||
Двухстадийное review (Pravila §4.5 / PSR_v1 R10) сохраняется. Git-safety-чеклист **не заменяет** code-review — он стоит **до** него (нет смысла ревьюить diff, если он не в той ветке).
|
||||
@@ -1420,3 +1420,11 @@ JTBD
|
||||
тулчейне
|
||||
пинами
|
||||
evals
|
||||
|
||||
# parallel-sessions-coordination spec (2026-05-18)
|
||||
коммитит
|
||||
инвокейшн
|
||||
парсимый
|
||||
парсится
|
||||
ревьюить
|
||||
инвокацией
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# Plugin Stack Rules — Superpowers + Frontend Design (v3.12)
|
||||
# Plugin Stack Rules — Superpowers + Frontend Design (v3.13)
|
||||
|
||||
**Дата:** 17.05.2026
|
||||
**Дата:** 18.05.2026
|
||||
**Назначение:** свод правил совместного использования плагинов Claude Code в проекте Лидерра — paired-stack ядро `obra/superpowers` (14 skills) + `anthropics/frontend-design`, плюс расширенный пул UI-инструментов `ui-ux-pro-max` (skill, marketplace `nextlevelbuilder/ui-ux-pro-max-skill`) и `21st.dev Magic MCP` (MCP-сервер `magic`), плюс инфраструктурный `claude-md-management` (skills, marketplace `anthropics/claude-plugins-official`), плюс **debug-runtime MCP** `@sentry/mcp-server` + `@modelcontextprotocol/server-redis` (v2.1+, R10.1 Блок 3).
|
||||
|
||||
**v3.13** — Anthropic dev-tooling: R10.1 Блок 1 +5 строк таблицы — **skill-creator** (#56) / **plugin-dev** (#57) / **hookify** (#58) / **claude-code-setup** (#59) / **context7** (#60) — 5 Anthropic-плагинов из `anthropics/claude-plugins-official`, уже включённых в `~/.claude/settings.json` `enabledPlugins` user-level без формализации (L1-паттерн). +note (v3.13). Новые 13-я (**authoring-tooling** — #56-#58) и 14-я (**dev-support** — #59-#60) off-phase подкатегории — не UI → вне R6.0/R6.1/R14. **hookify HK1** — hard-rule pre-check на коллизию с economy/skill-discipline хуками; закрывает 🔴-конфликт карты `hookify_plugin ↔ hk_pre_claude`. Содержательных изменений R0–R14: 0. ADR-010. Связано: Tooling v2.14, Pravila v1.28, CLAUDE.md v2.15; план `docs/superpowers/plans/2026-05-18-anthropic-dev-tooling-formalization.md`.
|
||||
|
||||
**v3.12** — discovery-interview: R10.1 Блок 1 +note (v3.12) — **discovery-interview** (Tooling #55, self-authored project-скил `.claude/skills/discovery-interview/`, как process-modeling/process-analysis; режимы FEATURE + SYSTEM). Новая 12-я off-phase подкатегория **discovery-tooling** (§4.30) — не UI → вне R6.0/R6.1/R14. Содержательных изменений R0–R14: 0. Связано: Tooling v2.13, Pravila v1.26, CLAUDE.md v2.13; план `docs/superpowers/plans/2026-05-18-discovery-interview-integration.md`.
|
||||
|
||||
**v3.11** — C10 business-process: R10.1 Блок 1 +1 строка **operations** (`operations@knowledge-work-plugins` v1.2.0, Anthropic Verified, 9 скилов, marketplace-плагин) + Блок 1 note (v3.11) — **process-modeling** + **process-analysis** (self-authored project-скилы `.claude/skills/`) + Блок 3 +1 строка **n8n-mcp** (DEFERRED — workflow-движок n8n, у портала нет n8n). Новая 11-я off-phase подкатегория **business-process** (Tooling #51-54, раздел C10 карты) — не UI → вне R6.0/R6.1/R14, как architecture-tooling/audit-security/ml-ai-tooling. Содержательных изменений R0–R14: 0. Связано: Tooling v2.12, Pravila v1.25, CLAUDE.md v2.12; план `docs/superpowers/plans/2026-05-17-c10-business-process-tooling-integration.md`.
|
||||
@@ -418,6 +420,11 @@ Stack — **головной**. Все плагины вне stack'а — **ин
|
||||
| **product-management** *(6 команд `/write-spec`, `/roadmap-update` и др.)* | `anthropics/knowledge-work-plugins` (plugin `product-management@knowledge-work-plugins`, Anthropic Verified) | product-strategy церемонии (problem→spec, roadmap, stakeholder updates, research synthesis, competitive analysis, metrics review). Категория: **project-management** (Tooling #42). 0 хуков | при product-strategy work: написание спеки, обновление роадмапа, анализ конкурентов. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **Design plugin** *(Design Critique / Accessibility Audit / UX Writing / Research Synthesis)* | `anthropics/knowledge-work-plugins` (Anthropic Verified) | дизайн-критика и UX — ревью макетов, дизайн-уровневый a11y-аудит, UX-копирайт, research synthesis. Категория: **design-tooling** (Tooling #46, вне UI-пула) | при дизайн-критике макета, UX-анализе, написании микрокопирайта — pre-code (ADR-006). Не подменяет FD #30 (генерация) и `requesting-code-review`. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **operations** *(9 skills: `process-doc` / `process-optimization` / `change-request` / `capacity-plan` / `compliance-tracking` / `risk-assessment` / `runbook` / `status-report` / `vendor-review`)* | `anthropics/knowledge-work-plugins` (plugin `operations@knowledge-work-plugins` v1.2.0, Anthropic Verified) | бизнес-процессы — документирование процесса, оптимизация, change-management, capacity-планирование. Категория: **business-process** (Tooling #51, вне UI-пула). 0 lifecycle-хуков | при работе с бизнес-процессом — документирование/оптимизация/change-request/capacity. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **skill-creator** *(1 skill)* | `anthropics/claude-plugins-official` (Anthropic Verified) | конструктор скилов — создание standalone-скилов с нуля, модификация, performance-eval/benchmark, оптимизация `description` под триггеринг. Категория: **authoring-tooling** (Tooling #56, вне UI-пула) | при создании нового **standalone** проектного скила. SC1 — граница с plugin-dev:skill-development (скилы внутри плагина); SC2 — вендоренные/self-authored скилы правятся прямым Edit, не через skill-creator (риск потери провенанса). Не UI → вне R6.0/R6.1/R14 |
|
||||
| **plugin-dev** *(8 skills + агенты `agent-creator` / `plugin-validator` / `skill-reviewer`)* | `anthropics/claude-plugins-official` (Anthropic Verified) | конструктор Claude-плагинов — структура / агенты / скилы / команды / хуки / MCP-интеграция / settings. Категория: **authoring-tooling** (Tooling #57) | при разработке собственного marketplace-плагина. PD1 — не для модификации вендоренного/self-authored (SC2); PD3 — `plugin-dev:hook-development` генерирует хук → применяется правило HK1. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **hookify** *(skills `/hookify` / `/configure` / `/list` / `/help` + `writing-rules` + агент `conversation-analyzer`)* | `anthropics/claude-plugins-official` (Anthropic Verified) | генератор хуков из анализа транскриптов диалога / явных инструкций. Категория: **authoring-tooling** (Tooling #58) | **только по явному `/hookify`**, не проактивно (HK2). **HK1 hard-rule:** перед генерацией хука — обязательный pre-check на коллизию с уже-зарегистрированными хуками в `~/.claude/settings.json`; перезапись 6-компонентной economy/skill-discipline архитектуры (economy-mode / skill-marker / skill-check / state-guard / postcompact / verifier) **запрещена**; при коллизии — остановка, ручное согласование. HK3 — закрывает 🔴-конфликт карты `hookify_plugin ↔ hk_pre_claude`. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **claude-code-setup** *(skill `claude-automation-recommender`)* | `anthropics/claude-plugins-official` (Anthropic Verified) | рекомендатель Claude Code automations — анализ кодовой базы + советы (хуки / суб-агенты / скилы / плагины / MCP). Read-only. Категория: **dev-support** (Tooling #59, вне UI-пула) | при запросе на оптимизацию Claude Code setup. CCS1 — рекомендации фильтруются R0 stack-gate + R10.1; ничего не устанавливается без явного согласования заказчика. Не UI → вне R6.0/R6.1/R14 |
|
||||
| **context7** *(MCP-tools `query-docs` / `resolve-library-id`)* | `anthropics/claude-plugins-official` (Anthropic Verified) — плагин в `enabledPlugins`, не `.mcp.json`-сервер | актуальная документация библиотек / фреймворков / SDK — отдаёт upstream-доки, обходит cutoff training data. Категория: **dev-support** (Tooling #60) | **первый выбор** для документации **известной библиотеки** (Laravel / Vue / Vuetify / Pest / React / …). CTX1 — WebFetch для конкретного URL, WebSearch — поиск без знания библиотеки. Не UI → вне R6.0/R6.1/R14 |
|
||||
|
||||
**Блок 1 — note (v3.3):** **mermaid-skill** (Tooling #37, генератор C4/architecture-диаграмм) — вендоренный сторонний скил в `.claude/skills/mermaid/` (`WH-2099/mermaid-skill`, MIT), **не** через marketplace и **не** в `enabledPlugins`. Пассивная утилита (генерация Mermaid-исходника), не решатель — формально вне типологии трёх блоков; регистрируется здесь для полноты. Категория **architecture-tooling**, вне R6/R14.
|
||||
|
||||
@@ -431,6 +438,8 @@ Stack — **головной**. Все плагины вне stack'а — **ин
|
||||
|
||||
**Блок 1 — note (v3.12):** **discovery-interview** (Tooling #55) — self-authored project-скил в `.claude/skills/discovery-interview/`, **не** вендоренный сторонний и **не** через marketplace; написан проектом (паттерн project-скилов `audit-portal`/`regression`/`process-modeling`/`process-analysis`). **Линтуется** lefthook'ом (cspell+markdownlint), **не** в `cspell.json` `ignorePaths` / `.markdownlintignore` (LINT1). Категория **discovery-tooling** (12-я off-phase подкатегория), вне R6.0/R6.1/R14.
|
||||
|
||||
**Блок 1 — note (v3.13):** 5 Anthropic dev-плагинов — **skill-creator** (#56) / **plugin-dev** (#57) / **hookify** (#58) / **claude-code-setup** (#59) / **context7** (#60) — marketplace-плагины из `anthropics/claude-plugins-official`, включены в `~/.claude/settings.json` `enabledPlugins` user-level. Формализованы 18.05.2026 после аудита «мозга» (L1-паттерн «плагин включён без формализации» — повтор UPM/21st 10.05 и Sentry/Redis 13.05). Две новые off-phase подкатегории: **authoring-tooling** (13-я — #56-#58, создание Claude-артефактов) + **dev-support** (14-я — #59-#60, поддержка/документация Claude-разработки), не UI → вне R6.0/R6.1/R14. **hookify** несёт hard-rule HK1 (pre-check на коллизию с existing хуками). `context7` — плагин из marketplace (не `.mcp.json`-сервер Блока 3), хотя предоставляет MCP-tools. ADR-010, Tooling §4.31–§4.35.
|
||||
|
||||
**Отмена:** через удаление из `enabledPlugins` в `~/.claude/settings.json` или через live-override `/имя-плагина` (R0.4.B) на одно действие.
|
||||
|
||||
#### Блок 2: Built-in skills Claude Code (всегда доступны через `Skill` tool по `/имя`)
|
||||
|
||||
@@ -1,10 +1,14 @@
|
||||
# Правила работы Claude в проекте «Лидерра»
|
||||
|
||||
**Версия:** v1.26 (18.05.2026)
|
||||
**Версия:** v1.28 (18.05.2026)
|
||||
**Дата:** 18.05.2026
|
||||
**Назначение:** настройки проекта (Project instructions) — Claude читает этот файл в каждом чате и следует правилам ниже.
|
||||
**Статус документа:** ✅ утверждён. Содержимое скопировано в поле "Project instructions" Claude.ai. Файл хранится в архиве как служебный документ.
|
||||
|
||||
**Что изменилось в v1.28 относительно v1.27:** §13.2 +абзац «Off-phase authoring-tooling + dev-support» — формализованы 5 Anthropic dev-плагинов из `anthropics/claude-plugins-official`, уже включённых в `~/.claude/settings.json` `enabledPlugins` user-level без формализации (#56 skill-creator, #57 plugin-dev, #58 hookify — тринадцатая off-phase подкатегория authoring-tooling; #59 claude-code-setup, #60 context7 — четырнадцатая off-phase подкатегория dev-support). L1-паттерн «плагин включён без формализации» (повтор UPM/21st 10.05, Sentry/Redis 13.05). hookify несёт hard-rule HK1 — pre-check на коллизию с economy/skill-discipline хуками. Границы — ADR-010. Связано: Tooling v2.14 / PSR_v1 v3.13 / CLAUDE.md v2.15. План `docs/superpowers/plans/2026-05-18-anthropic-dev-tooling-formalization.md`.
|
||||
|
||||
**Что изменилось в v1.27 относительно v1.26:** +§15 hard-rule «Параллельные сессии» (15.1 субагенты+git Sonnet/Opus only, 15.2 нормативка+pre-flight sync, 15.3 cross-refs). §15 третье hard-rule после §12 и §14. Список «нормативка» — 8 позиций. Спек — `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md`.
|
||||
|
||||
**Что изменилось в v1.26 относительно v1.25:** §13.2 +абзац «Off-phase discovery-tooling» — формализован скил `discovery-interview` (Tooling #55; self-authored project-скил `.claude/skills/discovery-interview/`, режимы FEATURE+SYSTEM) как двенадцатая off-phase подкатегория; как проектный скил регистрируется в §13.2, не §12.2. Границы — ADR-009 (DI1–DI6, разрез по слою-источнику с process-analysis #53). Связано: Tooling v2.13 / PSR_v1 v3.12 / CLAUDE.md v2.13. План `docs/superpowers/plans/2026-05-18-discovery-interview-integration.md`.
|
||||
|
||||
**Что изменилось в v1.25 относительно v1.24:** §13.2 +абзац «Off-phase business-process» — формализованы инструменты раздела C10 карты «Бизнес-процессы (общее)» (#51 operations — marketplace-плагин 9 скилов; #52 process-modeling, #53 process-analysis — self-authored project-скилы; #54 n8n-mcp — DEFERRED, у портала нет n8n) как одиннадцатая off-phase подкатегория. Границы — ADR-008. Связано: Tooling v2.12 / PSR_v1 v3.11 / CLAUDE.md v2.12. План `docs/superpowers/plans/2026-05-17-c10-business-process-tooling-integration.md`.
|
||||
@@ -585,6 +589,8 @@ P0 = блокер старта спринта или регуляторного
|
||||
| **v1.24** | **17.05.2026** | A11 ml-ai-tooling: §13.2 +абзац «Off-phase ml-ai-tooling» — формализованы инструменты раздела A11 карты «ML / AI-разработка» (#48 promptfoo — npm devDependency, CLI-eval LLM-промптов; #49 Data Scientist skill — вендоренный сторонний скил; #50 Jupyter MCP — DEFERRED, требует Python ML-окружения) как десятая off-phase подкатегория, отдельная от всех предыдущих; не UI → вне R6.0/R6.1/R14. promptfoo делает платные LLM-вызовы — только вручную/CI, никогда в хук (ML1). Границы — ADR-007. Связано: Tooling v2.10 / PSR_v1 v3.10 / CLAUDE.md v2.10. Через manual Edit всех 4 нормативных файлов (claude-md-management неприменим — исполнение в worktree, §5 п.10 worktree-constraint эксцепшн). План `docs/superpowers/plans/2026-05-17-a11-ml-ai-tooling-integration.md`. Архитектурных изменений в §§1–12 + §§13.1, 13.3–14: 0. |
|
||||
| **v1.25** | **17.05.2026** | C10 business-process: §13.2 +абзац «Off-phase business-process» — формализованы инструменты раздела C10 карты «Бизнес-процессы (общее)» (#51 operations — marketplace-плагин 9 скилов; #52 process-modeling — self-authored BPMN-скил; #53 process-analysis — self-authored discovery-скил; #54 n8n-mcp — DEFERRED, workflow-движок, у портала нет n8n) как одиннадцатая off-phase подкатегория, отдельная от всех предыдущих; не UI → вне R6.0/R6.1/R14. Границы — ADR-008. Связано: Tooling v2.12 / PSR_v1 v3.11 / CLAUDE.md v2.12. Через manual Edit всех 4 нормативных файлов (claude-md-management неприменим — исполнение в worktree, §5 п.10 worktree-constraint эксцепшн — как v1.24). План `docs/superpowers/plans/2026-05-17-c10-business-process-tooling-integration.md`. Архитектурных изменений в §§1–12 + §§13.1, 13.3–14: 0. |
|
||||
| **v1.26** | **18.05.2026** | discovery-interview: §13.2 +абзац «Off-phase discovery-tooling» — формализован скил `discovery-interview` (Tooling #55, §4.30; self-authored project-скил `.claude/skills/discovery-interview/`, режимы FEATURE+SYSTEM — интервью-discovery до проектирования) как двенадцатая off-phase подкатегория, отдельная от всех предыдущих; не UI → вне R6.0/R6.1/R14. Как проектный скил регистрируется в §13.2, **не** в §12.2 (карта Superpowers-скилов); триггер-eval 20/20. Границы — ADR-009 (DI1–DI6). Связано: Tooling v2.13 / PSR_v1 v3.12 / CLAUDE.md v2.13. Через manual Edit всех 4 нормативных файлов (claude-md-management неприменим — исполнение в worktree, §5 п.10 worktree-constraint эксцепшн — как v1.24/v1.25). План `docs/superpowers/plans/2026-05-18-discovery-interview-integration.md`. Архитектурных изменений в §§1–12 + §§13.1, 13.3–14: 0. |
|
||||
| **v1.27** | **18.05.2026** | Параллельные сессии: координация. +§15 hard-rule (15.1 субагенты+git Sonnet/Opus only, 15.2 нормативка+pre-flight sync, 15.3 cross-refs). §15 третье hard-rule после §12 и §14; список «нормативка» — 8 позиций. Лечит два класса инцидентов параллельных-сессий: (A) субагенты теряются между worktree (Sprint 6 прецедент), (B) нормативка/MEMORY дрейфует (Tooling v2.11 collision 17.05.2026). Спек — `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md`, план — `docs/superpowers/plans/2026-05-18-parallel-sessions-coordination.md`. |
|
||||
| **v1.28** | **18.05.2026** | Anthropic dev-tooling: §13.2 +абзац «Off-phase authoring-tooling + dev-support» — формализованы 5 Anthropic-плагинов из `anthropics/claude-plugins-official`, уже включённых в `~/.claude/settings.json` `enabledPlugins` user-level без формализации (#56 skill-creator / #57 plugin-dev / #58 hookify — тринадцатая off-phase подкатегория authoring-tooling; #59 claude-code-setup / #60 context7 — четырнадцатая off-phase подкатегория dev-support); не UI → вне R6.0/R6.1/R14. L1-паттерн «плагин включён без формализации» (повтор UPM/21st 10.05, Sentry/Redis 13.05). hookify несёт hard-rule HK1 — pre-check на коллизию с economy/skill-discipline хуками; закрывает 🔴-конфликт карты `hookify_plugin ↔ hk_pre_claude`. Границы — ADR-010 (SC1–SC3 / PD1–PD3 / HK1–HK3 / CCS1 / CTX1–CTX2). Связано: Tooling v2.14 / PSR_v1 v3.13 / CLAUDE.md v2.15. Через manual Edit всех 4 нормативных файлов (claude-md-management неприменим — исполнение в worktree, §5 п.10 worktree-constraint эксцепшн — как v1.24/v1.25/v1.26). **NB:** перенумеровано v1.27→v1.28 — v1.27 параллельно занят parallel-sessions §15 (origin/main `781a59c`); ветка `feat/anthropic-dev-tooling` ребейзнута на §15. План `docs/superpowers/plans/2026-05-18-anthropic-dev-tooling-formalization.md`. Архитектурных изменений в §§1–12 + §§13.1, 13.3–14: 0. |
|
||||
|
||||
---
|
||||
|
||||
@@ -735,6 +741,8 @@ Frontend Design и `obra/superpowers` (v5.1.0, 14 skills) — **парный sta
|
||||
|
||||
**Off-phase discovery-tooling (v1.26, 18.05.2026):** скил `discovery-interview` (Tooling #55, §4.30; self-authored project-скил `.claude/skills/discovery-interview/` — как `audit-portal`/`regression`/`process-modeling`/`process-analysis`) — структурированное интервью-discovery до проектирования: режим FEATURE (JTBD-интервью заказчика — вскрывает проблему, отдаёт discovery-brief в `brainstorming`), режим SYSTEM (интервью-ориентация по мета-слою проекта — карта/CLAUDE.md/MEMORY/Открытые_вопросы/Tooling/git log). **Двенадцатая** off-phase подкатегория. Не UI → вне R6.0/R6.1/R14 PSR_v1. Как **проектный** скил (не Superpowers-скил) регистрируется здесь в §13.2, **не** в §12.2 (карта Superpowers-скилов) — триггерится штатным механизмом using-superpowers по `description` (триггер-eval 20/20). Дубль с `process-analysis` #53 исключён разрезом по слою-источнику; границы — ADR-009 (DI1–DI6). Регулируется PSR_v1 R10.1 Блок 1 note (self-authored project-скил). Установлен 18.05.2026 на ветке `worktree-discovery-interview`; план `docs/superpowers/plans/2026-05-18-discovery-interview-integration.md`.
|
||||
|
||||
**Off-phase authoring-tooling + dev-support (v1.28, 18.05.2026):** 5 Anthropic dev-плагинов из marketplace `anthropics/claude-plugins-official`, уже включённых в `~/.claude/settings.json` `enabledPlugins` user-level — формализованы 18.05.2026 после аудита «мозга» (L1-паттерн «плагин фактически включён без формализации в правилах» — повтор UPM/21st 10.05 и Sentry/Redis 13.05). Подкатегория **authoring-tooling** (тринадцатая, создание Claude-артефактов): #56 `skill-creator` (Tooling §4.31; конструктор standalone-скилов), #57 `plugin-dev` (§4.32; конструктор marketplace-плагинов — 8 sub-skills + 3 агента), #58 `hookify` (§4.33; генератор хуков). Подкатегория **dev-support** (четырнадцатая, поддержка/документация Claude-разработки): #59 `claude-code-setup` (§4.34; рекомендатель Claude Code automations, read-only), #60 `context7` (§4.35; актуальная документация библиотек). Off-phase, не UI → вне R6.0/R6.1/R14 PSR_v1. **hookify** — особое правило: вызов только по явному `/hookify`, перед генерацией хука обязательный pre-check на коллизию с уже-зарегистрированными хуками в `~/.claude/settings.json` (перезапись 6-компонентной economy/skill-discipline архитектуры запрещена — конфликт-аудит HK1; закрывает 🔴-конфликт карты `hookify_plugin ↔ hk_pre_claude`). Границы D2–D5 — ADR-010. Регулируется PSR_v1 R10.1 Блок 1. Установлены 18.05.2026 на ветке `feat/anthropic-dev-tooling`; план `docs/superpowers/plans/2026-05-18-anthropic-dev-tooling-formalization.md`.
|
||||
|
||||
### 13.3. Скоуп
|
||||
|
||||
| Тип задачи | Кто отвечает |
|
||||
@@ -860,6 +868,53 @@ Hard-link идёт через цепочку: R14 нарушено → R10.4 «
|
||||
|
||||
---
|
||||
|
||||
## 15. Параллельные сессии — hard rule (субагенты + git, нормативка + pre-flight sync)
|
||||
|
||||
Действует с 18.05.2026. **Hard rule**: §9 «Отступления» к §15 не применяется (как §12 и §14).
|
||||
|
||||
### 15.1 Субагенты + git
|
||||
|
||||
Git-коммит-задачи субагенту (любой `Task`-инвокейшн, чей prompt содержит `git commit`, `git push`, `git stage`, `git checkout`, `git switch`, `git merge`, `git rebase`, либо где явно ожидается коммит в результате) — **только модель Sonnet или Opus**, никогда Haiku. Контроллер, делегирующий git-операцию Haiku-субагенту — нарушение §15.1, фиксируется в feedback того же уровня, что §12.
|
||||
|
||||
Исключение — read-only git-операции (`git log`, `git status`, `git diff`, `git rev-parse`, `git branch --show-current`, `git worktree list`) — разрешены любой модели.
|
||||
|
||||
Прецедент-источник: Sprint 6 (17.05.2026) — Haiku-субагенты угнали ветку параллельной сессии, устранено через `git reflog` + `reset`. Корневая причина — отсутствие верификации HEAD/branch после Task-инвокации. Verify-протокол — `.claude/skills/subagent-driven-development/references/git-safety-checklist.md`.
|
||||
|
||||
### 15.2 Нормативные правки + pre-flight sync
|
||||
|
||||
Любая правка файлов из списка «нормативка» (см. ниже) выполняется **только** на актуальной базе `origin/main`. Pre-flight обязателен:
|
||||
|
||||
```bash
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
```
|
||||
|
||||
Если есть untracked commits на `origin/main`, ребейз/merge **до начала правки**, не после.
|
||||
|
||||
Параллельная нормативная правка на устаревшей базе — нарушение §15.2. Признак нарушения: коммит правит файл, чья последняя версия на `origin/main` новее, чем версия в parent коммите правки.
|
||||
|
||||
**Список «нормативка» — 8 позиций:**
|
||||
|
||||
1. `docs/Pravila_raboty_Claude_v1_1.md`
|
||||
2. `CLAUDE.md`
|
||||
3. `docs/Tooling_v8_3.md`
|
||||
4. `docs/Plugin_stack_rules_v1.md`
|
||||
5. `memory/MEMORY.md` (и все `memory/*.md`)
|
||||
6. `docs/Открытые_вопросы_v8_3.md`
|
||||
7. `docs/adr/*.md` (glob — collision на ADR-NNN номере = тот же класс, что version-bump нормативки)
|
||||
8. `db/schema.sql` (параллельные миграции из разных сессий = реальный риск; запись в `db/CHANGELOG_schema.md` сама не защищает от version-base дрейфа)
|
||||
|
||||
Расширение списка — отдельная правка §15.2, не «по ощущениям».
|
||||
|
||||
Дополнительно: при параллельных активных сессиях контроллер обязан добавить запись в `docs/sessions/CURRENT.md` до первой нормативной правки (claim) — формат и жизненный цикл записи описаны в `docs/sessions/README.md`. Конфликт-резолюция (file overlap / section overlap / version-claim collision) — там же.
|
||||
|
||||
### 15.3 Cross-refs в других файлах
|
||||
|
||||
- **CLAUDE.md §1 priority chain** — §15 рядом с §12 и §14 как hard-rule (см. footer-абзац после цепочки).
|
||||
- **PSR_v1** — не правится: §15 не про координацию плагинов, а про координацию сессий.
|
||||
- **Tooling** — не правится.
|
||||
|
||||
---
|
||||
|
||||
## Что сделано после утверждения
|
||||
|
||||
Заказчик согласовал v1.1-DRAFT (короткий ответ «а» = вариант A: поправить §4.8 и шапку, выпустить v1.1) в сессии 05.05.2026. Claude выполнил:
|
||||
|
||||
+76
-4
File diff suppressed because one or more lines are too long
@@ -0,0 +1,77 @@
|
||||
# ADR-010: Anthropic dev-tooling formalization
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-05-18
|
||||
- **Deciders:** Дмитрий
|
||||
|
||||
## Context
|
||||
|
||||
Пять Anthropic-плагинов включены в `~/.claude/settings.json` `enabledPlugins`
|
||||
user-level, но не имеют номера в реестре Tooling §3.3 / PSR_v1 R10.1:
|
||||
`skill-creator`, `plugin-dev`, `hookify`, `claude-code-setup`, `context7`. Все пять
|
||||
из marketplace `anthropics/claude-plugins-official`.
|
||||
|
||||
Это повторение L1-паттерна «плагин фактически включён без формализации в правилах»:
|
||||
зафиксирован 2026-05-10 (UPM #31 / 21st #32 — обнаружены только когда заказчик
|
||||
спросил про конфликты), повторился 2026-05-13 (Sentry #34 / Redis #35 —
|
||||
формализованы retrospective в v1.92). Любое использование неформализованного
|
||||
плагина — байпас PSR_v1 R0.2/R10. Карта `docs/automation-graph.html` имеет
|
||||
соответствующие 5 узлов (iter7 audit-actualization 16.05.2026), но без номеров и
|
||||
без edge к governing-правилу; узел `hookify_plugin` несёт незакрытый 🔴-конфликт
|
||||
`hookify_plugin ↔ hk_pre_claude` (плагин hookify может перезаписать существующие
|
||||
хуки в `settings.json`).
|
||||
|
||||
Аудит «мозга» (discovery-interview SYSTEM-режим, 2026-05-18) вскрыл долг; заказчик
|
||||
выбрал формализовать все 5, предварительно закрыв риски.
|
||||
|
||||
## Decision
|
||||
|
||||
Пять плагинов формализуются как позиции #56–#60 реестра Tooling в **двух новых
|
||||
off-phase подкатегориях** (семантика разная — одна категория запутала бы правила):
|
||||
|
||||
- **authoring-tooling** — создание Claude-артефактов: #56 skill-creator,
|
||||
#57 plugin-dev, #58 hookify.
|
||||
- **dev-support** — поддержка/документация Claude-разработки: #59 claude-code-setup,
|
||||
#60 context7.
|
||||
|
||||
Граничные правила (locked):
|
||||
|
||||
1. **hookify (#58)** — вызов только по явному `/hookify`, не проактивно. Перед
|
||||
генерацией хука — обязательный pre-check на коллизию с уже-зарегистрированными
|
||||
хуками в `~/.claude/settings.json`; перезапись 6-компонентной economy/
|
||||
skill-discipline архитектуры запрещена. Это закрывает 🔴-конфликт
|
||||
`hookify_plugin ↔ hk_pre_claude` (🔴 → 🟢).
|
||||
2. **skill-creator (#56) ↔ plugin-dev:skill-development (#57)** — skill-creator для
|
||||
standalone проектных скилов; plugin-dev:skill-development — для скилов внутри
|
||||
разрабатываемого marketplace-плагина. Вендоренные и self-authored скилы
|
||||
модифицируются прямым Edit, не через skill-creator.
|
||||
3. **context7 (#60) ↔ WebFetch ↔ WebSearch** — context7 первый выбор для
|
||||
документации известной библиотеки; WebFetch — конкретный URL; WebSearch — поиск
|
||||
без URL.
|
||||
4. **claude-code-setup (#59)** — read-only анализатор; рекомендации фильтруются
|
||||
через R0/R10.1, ничего не устанавливается без явного согласования.
|
||||
|
||||
Обе подкатегории — не UI → вне фильтров PSR_v1 R6.0/R6.1 и R14 pipeline; регулируются
|
||||
R10.1 Блок 1 как infrastructure (по образцу claude-md-management #33).
|
||||
|
||||
ADR обязателен (не retrospective-без-ADR как Sentry/Redis #34/#35): здесь 5 позиций
|
||||
и 2 новые подкатегории — decision-grain выше порога.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Положительно: L1-долг для 5 Anthropic-плагинов закрыт — использование больше не
|
||||
байпас R0.2/R10; 🔴-конфликт hookify закрыт правилом (🔴 → 🟢, классификация карты
|
||||
🔴1/⚫3/🟢7 → 🔴0/⚫3/🟢8); карта получает edge к governing-правилу для 5 узлов.
|
||||
- Отрицательно: реестр Tooling растёт 55 → 60; число off-phase подкатегорий 12 → 14.
|
||||
- Риск: эти 5 плагинов включены user-level — влияют на все проекты машины;
|
||||
формализация в Лидерра-нормативке другие проекты не ломает (они её не читают) —
|
||||
это не риск, а ограничение области действия.
|
||||
- Defer: изменение `enabledPlugins` (выключение плагинов) — отвергнуто заказчиком в
|
||||
пользу формализации; не выполняется.
|
||||
|
||||
## Enforcement
|
||||
|
||||
None — формализация декларативная (реестр + границы в R10.1 / Pravila §13.2).
|
||||
hookify pre-check на коллизию хуков — поведенческое правило, проверяется code review,
|
||||
не автоматическим гейтом. Границы #56–#60 зафиксированы в Tooling §4.31–§4.32 и
|
||||
PSR_v1 R10.1 Блок 1.
|
||||
+31
-26
@@ -228,10 +228,10 @@ function pos(ring, angleDeg) {
|
||||
|
||||
const NODES = [
|
||||
// ── ПРАВИЛА (4) ── центр + первое кольцо ───────
|
||||
{ id: 'pravila', label: 'Pravila v1.24', group: 'rules', size: 38, ring: 0, ...pos(0, 0) },
|
||||
{ id: 'claude_md', label: 'CLAUDE.md v2.10', group: 'rules', size: 34, ring: 1, ...pos(1, 30) },
|
||||
{ id: 'psr_v1', label: 'PSR_v1 v3.10', group: 'rules', size: 32, ring: 1, ...pos(1, 150) },
|
||||
{ id: 'tooling', label: 'Tooling v2.10', group: 'rules', size: 30, ring: 1, ...pos(1, 270) },
|
||||
{ id: 'pravila', label: 'Pravila v1.28', group: 'rules', size: 38, ring: 0, ...pos(0, 0) },
|
||||
{ id: 'claude_md', label: 'CLAUDE.md v2.15', group: 'rules', size: 34, ring: 1, ...pos(1, 30) },
|
||||
{ id: 'psr_v1', label: 'PSR_v1 v3.13', group: 'rules', size: 32, ring: 1, ...pos(1, 150) },
|
||||
{ id: 'tooling', label: 'Tooling v2.14', group: 'rules', size: 30, ring: 1, ...pos(1, 270) },
|
||||
|
||||
// ── ПЛАГИНЫ (13) ── второе кольцо ──────────────
|
||||
{ id: 'superpowers', label: 'Superpowers v5.1', group: 'plugins', size: 30, ring: 2, ...pos(2, 45) },
|
||||
@@ -509,10 +509,8 @@ const EDGES = [
|
||||
E('mcp_boost', 'ag_rls', 'схема БД\nдля RLS-review'),
|
||||
|
||||
// ── АУДИТ-АКТУАЛИЗАЦИЯ 16.05.2026 — связи новых узлов ──
|
||||
E('psr_v1', 'skill_creator', 'R10.1:\nвнешний инструмент'),
|
||||
E('psr_v1', 'claude_setup', 'R10.1:\nвнешний инструмент'),
|
||||
E('psr_v1', 'plugin_dev', 'R10.1:\nвнешний инструмент'),
|
||||
E('psr_v1', 'context7', 'R10.1:\nвнешний инструмент'),
|
||||
// 4 ребра psr_v1→skill_creator/claude_setup/plugin_dev/context7 — перенесены
|
||||
// в ADT-блок 18.05.2026 (точные категории authoring-tooling/dev-support, дедуп)
|
||||
E('plugin_dev', 'ag_pcreator', 'содержит\nагента'),
|
||||
E('plugin_dev', 'ag_pvalid', 'содержит\nагента'),
|
||||
E('plugin_dev', 'ag_skreview', 'содержит\nагента'),
|
||||
@@ -568,12 +566,19 @@ const EDGES = [
|
||||
E('discovery_interview', 'sk_brainstorm', 'хэндофф:\nFEATURE-brief'),
|
||||
E('discovery_interview', 'process_analysis', 'граница: слой-источник\n(ADR-009 DI2)'),
|
||||
|
||||
// ── ANTHROPIC DEV-TOOLING 18.05.2026 — связи 5 узлов ──
|
||||
E('psr_v1', 'skill_creator', 'R10.1 блок 1:\nauthoring-tooling'),
|
||||
E('psr_v1', 'plugin_dev', 'R10.1 блок 1:\nauthoring-tooling'),
|
||||
E('psr_v1', 'hookify_plugin', 'R10.1 блок 1:\nauthoring-tooling (HK1)'),
|
||||
E('psr_v1', 'claude_setup', 'R10.1 блок 1:\ndev-support'),
|
||||
E('psr_v1', 'context7', 'R10.1 блок 1:\ndev-support'),
|
||||
|
||||
// ══════════════════════════════════════════════════
|
||||
// КОНФЛИКТЫ — 3-color classification (iter2 §4)
|
||||
// 🔴 не закрыт правилом / ⚫ возник на практике / 🟢 закрыт правилом
|
||||
// ══════════════════════════════════════════════════
|
||||
CONFLICT('sk_rls', 'ag_rls', 'RLS: граница задана — скил по таблице, агент по diff/PR (spec 2026-05-16)', 'GREEN'),
|
||||
CONFLICT('hookify_plugin', 'hk_pre_claude', 'hookify может перезаписать существующий хук', 'RED'),
|
||||
CONFLICT('hookify_plugin', 'hk_pre_claude', 'Закрыто правилом HK1 (ADR-010, PSR_v1 R10.1 v3.13): hookify вызывается только по явному /hookify + обязательный pre-check на коллизию с зарегистрированными хуками; перезапись economy/skill-discipline архитектуры запрещена', 'GREEN'),
|
||||
CONFLICT('mcp_pw', 'sk_parallel', 'Browser is already in use (квирк #2)', 'BLACK'),
|
||||
CONFLICT('ag_pest', 'mcp_redis', 'Квирк 72 устранён 16.05.2026 (commit 0fa1a73 — array-стор в тестах): гонки в Redis при Pest --parallel больше нет', 'GREEN'),
|
||||
CONFLICT('psr_v1', 'claude_md', 'Закрыто §5п.10 CLAUDE.md + хук CLAUDE.md-warn', 'GREEN'),
|
||||
@@ -681,7 +686,7 @@ const NODE_DETAILS = {
|
||||
[{ name: 'CLAUDE.md', desc: 'CLAUDE.md §5 п.10 требует править только через скил claude-md-management, а PSR_v1 это ограничение не повторяет — риск прямых Edit', type: 'GREEN' }]
|
||||
),
|
||||
tooling: nd(
|
||||
'Реестр 70 позиций — 50 формализованных инструментов + 20 ruflo-плагинов; §4.10 — ruflo как advisory/automation-подсистема. Когда что использовать, команды установки, конфликты.',
|
||||
'Реестр 80 позиций — 60 формализованных инструментов + 20 ruflo-плагинов; §4.10 — ruflo как advisory/automation-подсистема. Когда что использовать, команды установки, конфликты.',
|
||||
'При выборе инструмента для фазы (нулевая документация / первая backend / вторая frontend / третья перед запуском в боевую среду), при добавлении нового инструмента, при обновлении версий.',
|
||||
'При прямом конфликте с CLAUDE.md побеждает CLAUDE.md (оперативная карта уровня 2a). Любая правка требует синхронизации с CLAUDE.md §3.',
|
||||
[
|
||||
@@ -737,12 +742,12 @@ const NODE_DETAILS = {
|
||||
hookify_plugin: nd(
|
||||
'Плагин создания хуков — анализирует разговоры и предлагает новые автоматизации в виде хуков.',
|
||||
'При запросе «давай повесим хук на это поведение» или после серии повторяющихся ошибок — анализ через агента conversation-analyzer.',
|
||||
'Правило PSR_v1 R10.1. Новые хуки могут конфликтовать с существующими (см. конфликты ниже) — обязательная проверка файла настроек до создания.',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1: формализован' }],
|
||||
'PSR_v1 R10.1 блок 1 #58 (authoring-tooling). HK1 hard-rule: только по явному /hookify, не проактивно; перед генерацией хука — обязательный pre-check на коллизию с зарегистрированными хуками settings.json; перезапись 6-компонентной economy/skill-discipline архитектуры запрещена. ADR-010.',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1 блок 1 #58: authoring-tooling, HK1 pre-check (ADR-010)' }],
|
||||
[{ name: 'агент hookify:conversation-analyzer', cond: 'запускает анализ разговоров' }],
|
||||
[{ name: 'агент hookify:conversation-analyzer', cond: 'плагин и агент работают в паре' }],
|
||||
[
|
||||
{ name: 'хук pre-claude-warn', desc: 'плагин hookify создаёт новые хуки PreToolUse на лету — может перезаписать или конкурировать с этим хуком', type: 'RED' }
|
||||
{ name: 'хук pre-claude-warn', desc: 'Закрыто правилом HK1 (ADR-010): hookify — только по явному /hookify, перед генерацией хука обязательный pre-check на коллизию с существующими хуками settings.json; перезапись 6-компонентной economy/skill-discipline архитектуры запрещена', type: 'GREEN' }
|
||||
]
|
||||
),
|
||||
|
||||
@@ -1599,7 +1604,7 @@ const NODE_DETAILS = {
|
||||
'Плагин Anthropic для создания новых скилов — eval-driven подход: датасеты сценариев, train/test split, бенчмарк-цикл.',
|
||||
'При формализации повторяющегося процесса в скил с проверяемым выводом (генерация кода, преобразование файлов).',
|
||||
'Включён в настройках (~/.claude/settings.json). Для discipline-скилов (TDD-типа) предпочтительнее скил writing-skills плагина Superpowers — у них разные философии.',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1: внешний плагин-инструмент' }],
|
||||
[{ name: 'PSR_v1', cond: 'R10.1 блок 1 #56: authoring-tooling (ADR-010)' }],
|
||||
[],
|
||||
[{ name: 'скил writing-skills', cond: 'обе создают скилы — skill-creator eval-driven, writing-skills через TDD' }]
|
||||
),
|
||||
@@ -1607,7 +1612,7 @@ const NODE_DETAILS = {
|
||||
'Плагин Anthropic — рекомендатель автоматизаций (claude-automation-recommender): анализирует репозиторий и советует, какие MCP-серверы, скилы, хуки, суб-агентов добавить.',
|
||||
'При настройке/ревизии автоматизации проекта — «чего не хватает в тулчейне».',
|
||||
'Включён в настройках (~/.claude/settings.json). Рекомендации — совещательные, решение за заказчиком.',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1: внешний плагин-инструмент' }],
|
||||
[{ name: 'PSR_v1', cond: 'R10.1 блок 1 #59: dev-support — рекомендации фильтруются R0/R10.1 (CCS1, ADR-010)' }],
|
||||
[],
|
||||
[]
|
||||
),
|
||||
@@ -1615,7 +1620,7 @@ const NODE_DETAILS = {
|
||||
'Плагин Anthropic для разработки плагинов Claude Code — 7 скилов (структура плагина, разработка скилов / агентов / хуков / команд, интеграция MCP, настройки).',
|
||||
'При создании или правке плагина и его компонентов.',
|
||||
'Включён в настройках. Содержит 3 агента, уже представленные на карте (agent-creator / plugin-validator / skill-reviewer).',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1: внешний плагин-инструмент' }],
|
||||
[{ name: 'PSR_v1', cond: 'R10.1 блок 1 #57: authoring-tooling — только для marketplace-плагинов, не для вендоренного/self-authored (PD1, ADR-010)' }],
|
||||
[
|
||||
{ name: 'агент plugin-dev:agent-creator', cond: 'входит в плагин' },
|
||||
{ name: 'агент plugin-dev:plugin-validator', cond: 'входит в плагин' },
|
||||
@@ -1627,7 +1632,7 @@ const NODE_DETAILS = {
|
||||
'Плагин Anthropic — актуальная документация библиотек / фреймворков / API через MCP-инструменты query-docs и resolve-library-id.',
|
||||
'При вопросах по библиотеке / фреймворку / SDK / CLI — синтаксис API, конфигурация, миграция версий. Предпочтительнее веб-поиска для документации библиотек.',
|
||||
'Включён в настройках. Не для рефакторинга / отладки бизнес-логики / ревью — только документация.',
|
||||
[{ name: 'PSR_v1', cond: 'R10.1: внешний плагин-инструмент' }],
|
||||
[{ name: 'PSR_v1', cond: 'R10.1 блок 1 #60: dev-support — первый выбор для документации библиотек; WebFetch/WebSearch как fallback (CTX1, ADR-010)' }],
|
||||
[],
|
||||
[]
|
||||
),
|
||||
@@ -1882,17 +1887,17 @@ const META_WINDOW = '09–16.05.2026'; // окно подсчёта испо
|
||||
// usesSrc: 'скил' | 'агент' | 'MCP' | 'хук' | 'memory-чтение' | 'коммиты' | 'инспекция' | '—'
|
||||
const NODE_META = {
|
||||
// ── ПРАВИЛА (4) — узлы-правила, напрямую не вызываются ──
|
||||
pravila: { since: '06.05.2026', changed: '17.05.2026', uses: null, usesSrc: '—' },
|
||||
claude_md: { since: '06.05.2026', changed: '17.05.2026', uses: null, usesSrc: '—' },
|
||||
psr_v1: { since: '09.05.2026', changed: '17.05.2026', uses: null, usesSrc: '—' },
|
||||
tooling: { since: '06.05.2026', changed: '17.05.2026', uses: null, usesSrc: '—' },
|
||||
pravila: { since: '06.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
claude_md: { since: '06.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
psr_v1: { since: '09.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
tooling: { since: '06.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
|
||||
// ── ПЛАГИНЫ (5) ──
|
||||
superpowers: { since: '09.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
fd_plugin: { since: '10.05.2026', changed: '—', uses: 1, usesSrc: 'скил' },
|
||||
upm: { since: '10.05.2026', changed: '—', uses: 0, usesSrc: 'скил' },
|
||||
claude_md_mgmt: { since: '10.05.2026', changed: '—', uses: 15, usesSrc: 'скил' },
|
||||
hookify_plugin: { since: '—', changed: '—', uses: null, usesSrc: '—' },
|
||||
hookify_plugin: { since: '—', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
|
||||
// ── СКИЛЫ SUPERPOWERS (14) — связка подключена 09.05.2026 ──
|
||||
sk_brainstorm: { since: '09.05.2026', changed: '—', uses: 44, usesSrc: 'скил' },
|
||||
@@ -1991,10 +1996,10 @@ const NODE_META = {
|
||||
|
||||
// ── АУДИТ-АКТУАЛИЗАЦИЯ 16.05.2026 — узлы добавлены по полному аудиту карты ──
|
||||
// uses новых узлов по транскриптам не измерялись (null = нет данных).
|
||||
skill_creator: { since: '11.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
claude_setup: { since: '11.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
plugin_dev: { since: '—', changed: '—', uses: null, usesSrc: '—' },
|
||||
context7: { since: '—', changed: '—', uses: null, usesSrc: '—' },
|
||||
skill_creator: { since: '11.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
claude_setup: { since: '11.05.2026', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
plugin_dev: { since: '—', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
context7: { since: '—', changed: '18.05.2026', uses: null, usesSrc: '—' },
|
||||
hk_self_check: { since: '10.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
hk_skill_marker: { since: '10.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
hk_skill_check: { since: '10.05.2026', changed: '—', uses: null, usesSrc: '—' },
|
||||
|
||||
@@ -0,0 +1,224 @@
|
||||
# CURRENT.md — активные Claude-сессии
|
||||
|
||||
> Формат и жизненный цикл записей: [docs/sessions/README.md](README.md).
|
||||
> Pravila §15.2 — описание правила в нормативке.
|
||||
|
||||
## session: 2026-05-18-parallel-sessions-coordination
|
||||
|
||||
- branch: feat/parallel-sessions-coordination
|
||||
- worktree: c:/моя/проекты/портал crm/Документация
|
||||
- started: 2026-05-18T09:30+03:00
|
||||
- scope-files:
|
||||
- docs/Pravila_raboty_Claude_v1_1.md §15 (new)
|
||||
- CLAUDE.md §1 (cross-ref), §0 (Pravila version row)
|
||||
- tools/subagent-prompt-prefix.mjs (new)
|
||||
- .claude/settings.json (PreToolUse Task block)
|
||||
- .claude/skills/subagent-driven-development/ (new wrapper-skill)
|
||||
- docs/sessions/README.md, CURRENT.md (new — этот файл)
|
||||
- version-claims:
|
||||
- Pravila: 1.26 → 1.27
|
||||
- CLAUDE.md: 2.13 → 2.14
|
||||
- status: closed-b1765e9
|
||||
- closes: docs/superpowers/plans/2026-05-18-parallel-sessions-coordination.md
|
||||
|
||||
---
|
||||
|
||||
## Retro-claim'ы активных worktrees (snapshot 2026-05-18)
|
||||
|
||||
Per Pravila §15.2 — backfill для существующих параллельных сессий. Эти записи retroactive, scope/version-claims заполнены best-effort из последних коммитов worktree-веток. Активные сессии при возобновлении работы обновляют свой блок.
|
||||
|
||||
## session: 2026-05-17-a11-ml-ai-tooling
|
||||
|
||||
- branch: worktree-a11-ml-ai-tooling
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/a11-ml-ai-tooling
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/automation-graph.html [A11 section] [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-17-a3-integration-tooling
|
||||
|
||||
- branch: feat/a3-integration-tooling
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/a3-integration-tooling
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- cspell-words.txt [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-17-adr006-icon-path-boundary
|
||||
|
||||
- branch: worktree-adr006-icon-path-boundary
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/adr006-icon-path-boundary
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/adr/006-design-tooling-figma-universal-icons-design-plugin.md [best-effort]
|
||||
- CLAUDE.md §3.3 (#45), §0 cross-ref Tooling v2.11 [best-effort]
|
||||
- docs/Tooling_v8_3.md §4.20 [best-effort]
|
||||
- version-claims:
|
||||
- Tooling: 2.10 → 2.11
|
||||
- status: closed-9cf0f0c (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-18-anthropic-dev-tooling
|
||||
|
||||
- branch: feat/anthropic-dev-tooling
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/anthropic-dev-tooling
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/automation-graph.html [E5 discovery-tooling section] [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: closed-b40f2c8 (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-18-c10-business-process-tooling
|
||||
|
||||
- branch: worktree-c10-business-process-tooling
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/c10-business-process-tooling
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/superpowers/specs/2026-05-17-c10-business-process-tooling-integration-design.md [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-17-c9-project-management-tooling
|
||||
|
||||
- branch: worktree-c9-project-management-tooling
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/c9-project-management-tooling
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/automation-graph.html [C9 section] [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-18-discovery-interview
|
||||
|
||||
- branch: worktree-discovery-interview
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/discovery-interview
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/automation-graph.html [E5 discovery-tooling section] [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: closed-b40f2c8 (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-16-iter6-automation-graph
|
||||
|
||||
- branch: feat/rls-tooling-boundary
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/iter6-automation-graph
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/automation-graph.html [viewMode/usage/dupes UI] [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-15-plan-6-regions
|
||||
|
||||
- branch: plan-6-regions
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/plan-6-regions
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- app/resources/js/components/projects/ProjectDetailsDrawer.vue [best-effort]
|
||||
- app/resources/js/stores/projectsStore.ts [best-effort]
|
||||
- app/resources/js/views/projects/NewProjectDialog.vue [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-16-ruflo-recollage
|
||||
|
||||
- branch: worktree-ruflo-recollage
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/ruflo-recollage
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/superpowers/specs/2026-05-10-claude-brain-extraction-design.md [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-16-sprint4-historical-import
|
||||
|
||||
- branch: worktree-sprint4-historical-import
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint4-historical-import
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- app/routes/web.php [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-17-sprint5a-auth-polish
|
||||
|
||||
- branch: worktree-sprint5a-auth-polish
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint5a-auth-polish
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/superpowers/plans/2026-05-16-sprint5a-auth-polish.md [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: docs/superpowers/plans/2026-05-16-sprint5a-auth-polish.md
|
||||
|
||||
## session: 2026-05-17-sprint5b-layout-views
|
||||
|
||||
- branch: worktree-sprint5b-layout-views
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint5b-layout-views
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/superpowers/plans/2026-05-17-sprint5b-layout-views.md [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: docs/superpowers/plans/2026-05-17-sprint5b-layout-views.md
|
||||
|
||||
## session: 2026-05-17-sprint5c-billing-admin
|
||||
|
||||
- branch: worktree-sprint5c-billing-admin
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint5c-billing-admin
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- app/tests/Feature/Admin/AdminPricingTiersControllerTest.php [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
|
||||
## session: 2026-05-17-sprint5d-cleanup
|
||||
|
||||
- branch: worktree-sprint5d-cleanup
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint5d-cleanup
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- docs/superpowers/plans/2026-05-17-sprint5d-cleanup-mock-fallback.md [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: docs/superpowers/plans/2026-05-17-sprint5d-cleanup-mock-fallback.md
|
||||
|
||||
## session: 2026-05-17-sprint6-p3-polish
|
||||
|
||||
- branch: worktree-sprint6-p3-polish
|
||||
- worktree: C:/моя/проекты/портал crm/Документация/.claude/worktrees/sprint6-p3-polish
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- app/resources/js/views/ProjectsView.vue [best-effort]
|
||||
- version-claims:
|
||||
- none verified — backfill
|
||||
- status: in-progress (backfilled)
|
||||
- closes: unknown — backfill
|
||||
@@ -0,0 +1,61 @@
|
||||
# docs/sessions/ — координация параллельных Claude-сессий
|
||||
|
||||
**Источник правила:** Pravila §15.2 (раздел про CURRENT.md в конце текста §15.2).
|
||||
|
||||
## Назначение
|
||||
|
||||
`docs/sessions/CURRENT.md` — заявочный лог активных параллельных Claude-сессий проекта. Решает класс инцидентов «нормативка/MEMORY дрейфует» (см. spec — `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md`).
|
||||
|
||||
## Когда писать в CURRENT.md
|
||||
|
||||
Перед **первой** нормативной правкой в сессии (правки файлов из списка §15.2 — Pravila, CLAUDE.md, Tooling, PSR_v1, MEMORY.md, Открытые_вопросы, docs/adr/*, db/schema.sql). Запись добавляется отдельным атомарным коммитом `sessions: claim <topic>` — до plan-документа и до первой содержательной правки.
|
||||
|
||||
## Формат записи
|
||||
|
||||
```
|
||||
## session: YYYY-MM-DD-<topic-kebab>
|
||||
- branch: <git branch --show-current>
|
||||
- worktree: <git rev-parse --show-toplevel>
|
||||
- started: <ISO 8601 with timezone>
|
||||
- scope-files:
|
||||
- <relative path> [§/раздел/строка]
|
||||
- ...
|
||||
- version-claims:
|
||||
- <file-or-topic>: <from> → <to>
|
||||
- ...
|
||||
- status: in-progress | closed-<commit-sha>
|
||||
- closes: <relative path к plan-документу>
|
||||
```
|
||||
|
||||
`scope-files` — какие нормативные файлы и в каких секциях правит сессия. `version-claims` — какие новые версии (Tooling 2.X, Pravila 1.Y и т.п.) или номера (ADR-NNN) сессия резервирует.
|
||||
|
||||
## Жизненный цикл
|
||||
|
||||
- **claim** — добавить запись со `status: in-progress` + атомарный коммит `sessions: claim <topic>`.
|
||||
- **check** — pre-flight перед нормативной правкой: `Read docs/sessions/CURRENT.md` + проверить пересечение `scope-files` / `version-claims` с активными записями.
|
||||
- **release** — на закрытии (после push на main) изменить `status: closed-<commit-sha>` (запись остаётся в CURRENT.md — append-only-вариант).
|
||||
|
||||
Closed-записи переезжают в `docs/sessions/archive/YYYY-MM.md` через ≥30 дней после закрытия (ручная архивация раз в месяц, не cron).
|
||||
|
||||
## Конфликт-резолюция
|
||||
|
||||
| Тип пересечения | Реакция |
|
||||
|---|---|
|
||||
| Файловое пересечение (одинаковый файл, разные секции) | **soft-warn** — продолжать можно, но pre-flight fetch перед каждым коммитом обязателен (§15.2). |
|
||||
| Section-пересечение (одна и та же секция §X.Y) | **hard-stop** — координация с заказчиком до начала правки. |
|
||||
| Version-claim collision (две сессии заявили один номер) | **hard-stop** — кто claim'нул раньше (по `started`-timestamp), тот его и берёт. Вторая сессия сдвигается на +1. |
|
||||
|
||||
## Pre-flight snippet (для plan-документов и скила subagent-driven-development)
|
||||
|
||||
```bash
|
||||
# Перед нормативной правкой:
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
grep -A 20 'status: in-progress' docs/sessions/CURRENT.md
|
||||
```
|
||||
|
||||
## Что мы НЕ делаем (явный YAGNI)
|
||||
|
||||
- Pre-commit hook на CURRENT.md — добавим только если будут зафиксированы инциденты игнорирования.
|
||||
- TTL / auto-expire записей — добавим, если файл реально засорится.
|
||||
- Machine-readable JSON-формат — markdown достаточен, парсится grep/sed.
|
||||
- Интеграция с GitHub Issues — отдельная тема, не блокер.
|
||||
@@ -0,0 +1,320 @@
|
||||
# Anthropic Dev-Tooling Formalization — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Git-commit-bearing tasks — **controller-only (Sonnet)**, never delegated to Haiku-subagent (Sprint 3F/5/6 lessons).
|
||||
|
||||
**Goal:** Формализовать 5 Anthropic-плагинов уже включённых в `~/.claude/settings.json` user-level (skill-creator, plugin-dev, hookify, claude-code-setup, context7) — добавить как позиции #56–#60 в две новые off-phase подкатегории Tooling: **authoring-tooling** (#56-#58) + **dev-support** (#59-#60). Закрыть 🔴-конфликт `hookify_plugin ↔ hk_pre_claude` правилом pre-check в PSR_v1 R10.1.
|
||||
|
||||
**Architecture:** retrospective formalization paired со spec ADR-010. Никакой кодовой регрессии — только текстовая нормативка (4 файла) + карта (5 узлов refresh + 5 новых edge) + memory + ADR. Worktree уже создан (`feat/anthropic-dev-tooling` от origin/main `b40f2c8`). Спека: `docs/superpowers/specs/2026-05-18-anthropic-dev-tooling-formalization-design.md`.
|
||||
|
||||
> **Rebase-девиация (исполнение 18.05.2026):** во время эпика origin/main ушёл `b40f2c8`→`781a59c` — параллельная сессия запушила parallel-sessions §15 (Pravila v1.27, CLAUDE.md v2.14). Ветка ребейзнута на `781a59c`; коммиты Pravila/CLAUDE.md дропнуты из rebase (`--skip`) и пересозданы поверх §15. Целевые версии перенумерованы: **Pravila v1.27→v1.28, CLAUDE.md v2.14→v2.15** (Tooling v2.14 / PSR_v1 v3.13 — без изменений, §15 их не трогал). Шаги ниже отражают исходный план — фактические версии нормативки см. §9 CLAUDE.md / §13 Pravila.
|
||||
|
||||
**Tech Stack:** Tooling Прил. Н / PSR_v1 / Pravila / CLAUDE.md / ADR-010 / automation-graph.html / memory. Pre-push — `bin/gitleaks.exe detect --no-banner` (full-history) + `npx lychee --offline --no-progress .` (или из главного дерева во избежание квирка #92).
|
||||
|
||||
---
|
||||
|
||||
## Tool Identity & Decisions (verified 2026-05-18)
|
||||
|
||||
| # | Plugin | Marketplace | Category | Sub-skills/agents | Role |
|
||||
|---|---|---|---|---|---|
|
||||
| 56 | `skill-creator@claude-plugins-official` | anthropics/claude-plugins-official | authoring-tooling | skill `skill-creator` | Создание standalone скилов с performance-метриками |
|
||||
| 57 | `plugin-dev@claude-plugins-official` | anthropics/claude-plugins-official | authoring-tooling | 8 skills (plugin-structure, agent-development, skill-development, command-development, hook-development, mcp-integration, plugin-settings) + 2 agents (agent-creator, plugin-validator, skill-reviewer) | Конструктор marketplace-плагинов |
|
||||
| 58 | `hookify@claude-plugins-official` | anthropics/claude-plugins-official | authoring-tooling | skills (hookify, configure, list, help, writing-rules) + agent (conversation-analyzer) | Генератор хуков из анализа транскриптов |
|
||||
| 59 | `claude-code-setup@claude-plugins-official` | anthropics/claude-plugins-official | dev-support | skill `claude-automation-recommender` | Анализатор кодовой базы + рекомендации |
|
||||
| 60 | `context7@claude-plugins-official` | anthropics/claude-plugins-official | dev-support | MCP `plugin_context7_context7` (tools `query-docs`, `resolve-library-id`) | Актуальная документация библиотек |
|
||||
|
||||
**Locked decisions (D1-D8):** см. спеку §Decisions.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Pre-flight — baseline, snapshot
|
||||
|
||||
**Files:** none modified (read-only)
|
||||
|
||||
- [ ] **Step 1: Verify worktree state**
|
||||
|
||||
```bash
|
||||
cd ".claude/worktrees/anthropic-dev-tooling"
|
||||
git status --short # должен быть clean (spec+plan еще не закоммичены)
|
||||
git rev-parse --short HEAD # должен быть b40f2c8
|
||||
git branch --show-current # должен быть feat/anthropic-dev-tooling
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Snapshot the live Tooling counter (NUM1)**
|
||||
|
||||
```bash
|
||||
grep -E "^\*\*Прил\. Н" docs/Tooling_v8_3.md | head -1
|
||||
grep -E "Итого формализованных позиций.*55" docs/Tooling_v8_3.md
|
||||
```
|
||||
|
||||
Expected: «v2.13», count «55». Если иное (главное origin/main продвинулось дальше) — **остановка**, ребейз worktree на актуальный origin/main, перенумеровка позиций.
|
||||
|
||||
- [ ] **Step 3: Snapshot map state**
|
||||
|
||||
```bash
|
||||
grep -c "id: 'skill_creator'" docs/automation-graph.html
|
||||
grep -c "id: 'plugin_dev'" docs/automation-graph.html
|
||||
grep -c "id: 'hookify_plugin'" docs/automation-graph.html
|
||||
grep -c "id: 'claude_setup'" docs/automation-graph.html
|
||||
grep -c "id: 'context7'" docs/automation-graph.html
|
||||
```
|
||||
|
||||
Each expected = 1. Если 0 — узел не существует, плана недостаточно, нужен add (не refresh). **NB:** claude-code-setup имеет map-id `claude_setup` (verified Task 1, 2026-05-18) — не `cc_setup`.
|
||||
|
||||
- [ ] **Step 4: Stage spec + plan**
|
||||
|
||||
```bash
|
||||
git add docs/superpowers/specs/2026-05-18-anthropic-dev-tooling-formalization-design.md \
|
||||
docs/superpowers/plans/2026-05-18-anthropic-dev-tooling-formalization.md
|
||||
git commit -m "docs(adt): brainstorming spec + implementation plan — Anthropic dev-tooling formalization"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: ADR-010 — Anthropic dev-tooling decision
|
||||
|
||||
**Files:** `docs/adr/ADR-010-anthropic-dev-tooling.md` (create)
|
||||
|
||||
- [ ] **Step 1:** Создать ADR по шаблону ADR-009 (discovery-interview) с секциями:
|
||||
- Status: Accepted (date 2026-05-18)
|
||||
- Context: 5 плагинов в settings.json без формализации; L1-паттерн повторяется (UPM/21st, Sentry/Redis); карта iter7 audit имеет узлы, но без правил
|
||||
- Decision: split на 2 подкатегории (D1); правила D2–D5; ADR-010 как умолчание для retrospective формализации крупнее 2 позиций
|
||||
- Consequences: + closes L1 для 5 плагинов; + закрывает 🔴 hookify; − добавляет 5 позиций к 55 (рост реестра)
|
||||
- References: spec link, ADR-004/005/006/007/008/009 как прецеденты
|
||||
|
||||
- [ ] **Step 2:** Commit
|
||||
|
||||
```bash
|
||||
git add docs/adr/ADR-010-anthropic-dev-tooling.md
|
||||
git commit -m "docs(adr): ADR-010 — Anthropic dev-tooling formalization decision"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Tooling Прил. Н — 2 подкатегории + 5 позиций
|
||||
|
||||
**Files:** `docs/Tooling_v8_3.md`
|
||||
|
||||
- [ ] **Step 1:** §0 счётчик 55→60. Шапка v2.13 → v2.14. Версия в любых других местах файла где упоминается — sync.
|
||||
|
||||
- [ ] **Step 2:** Добавить §4.31 «authoring-tooling» с подпунктами:
|
||||
- §4.31.1 #56 skill-creator (роль, install через marketplace, граница D3, конфликт-аудит SC1: standalone vs plugin-dev; SC2: self-authored — direct Edit, не trigger; SC3: bus-factor — Anthropic Verified)
|
||||
- §4.31.2 #57 plugin-dev (роль, 8 sub-skills, граница D3, конфликт-аудит PD1-PD3: marketplace vs standalone; PD2: вендоренные/self-authored — не trigger; PD3: 8 sub-skills overlap внутри plugin'а)
|
||||
- §4.31.3 #58 hookify (роль, generator, **HK1 hard-rule pre-check на коллизию с economy/skill-discipline 6-компонентной архитектурой; HK2: только по явному /hookify; HK3: hookify_plugin ↔ hk_pre_claude конфликт — закрыт правилом**)
|
||||
|
||||
- [ ] **Step 3:** Добавить §4.32 «dev-support» с подпунктами:
|
||||
- §4.32.1 #59 claude-code-setup (роль, /claude-automation-recommender, read-only, CCS1: рекомендации фильтровать R0/R10.1)
|
||||
- §4.32.2 #60 context7 (роль, MCP-доки, граница D4 с WebFetch/WebSearch, CTX1: первый выбор для known library docs; CTX2: не trigger при WebSearch без библиотеки)
|
||||
|
||||
- [ ] **Step 4:** §13 (история версий) +entry v2.14: «Anthropic dev-tooling integration — формализация 5 плагинов (#56-#60) в 2 новых off-phase подкатегориях».
|
||||
|
||||
- [ ] **Step 5:** Commit
|
||||
|
||||
```bash
|
||||
git add docs/Tooling_v8_3.md
|
||||
git commit -m "docs(adt): Tooling Прил. Н v2.14 — register #56-#60 (authoring-tooling + dev-support)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: PSR_v1 R10.1 — +5 строк + hookify-special note
|
||||
|
||||
**Files:** `docs/Plugin_stack_rules_v1.md`
|
||||
|
||||
- [ ] **Step 1:** R10.1 Блок 1 (`enabledPlugins`) +5 строк по образцу adr-kit / architecture-patterns / operations / product-management / design:
|
||||
- skill-creator (роль / когда инвокировать — «при создании нового standalone скила; вендоренное/self-authored — direct Edit»)
|
||||
- plugin-dev (роль / когда — «при разработке собственного marketplace-плагина; не для модификации вендоренного/self-authored»)
|
||||
- hookify (роль / когда — «только по явному `/hookify`; **обязательный pre-check на коллизию с existing хуками в `~/.claude/settings.json`**; перезапись economy/skill-discipline хуков запрещена»)
|
||||
- claude-code-setup (роль / когда — «по запросу или превентивно; рекомендации **фильтровать R0/R10.1**; не устанавливать без явного согласования»)
|
||||
- context7 (роль / когда — «**первый выбор для документации известной библиотеки**; fallback на WebFetch при конкретном URL, WebSearch — без знания URL/библиотеки»)
|
||||
|
||||
- [ ] **Step 2:** Note блока (после строк): «Подкатегории **authoring-tooling** (#56-#58) и **dev-support** (#59-#60) — не UI → вне фильтров R6.0/R6.1 и R14 pipeline. Регулируются PSR_v1 R10.1 Блок 1 как infrastructure (по образцу claude-md-management #33).»
|
||||
|
||||
- [ ] **Step 3:** §0 (история) +entry: «v3.13 — Anthropic dev-tooling: R10.1 Блок 1 +5 строк + hookify pre-check hard-rule. Связано: Tooling v2.14, Pravila v1.27, CLAUDE.md v2.14.»
|
||||
|
||||
- [ ] **Step 4:** Шапка PSR v3.12 → v3.13.
|
||||
|
||||
- [ ] **Step 5:** Commit
|
||||
|
||||
```bash
|
||||
git add docs/Plugin_stack_rules_v1.md
|
||||
git commit -m "docs(adt): PSR_v1 v3.13 — R10.1 Блок 1 +5 строк (skill-creator/plugin-dev/hookify/claude-code-setup/context7) + hookify pre-check"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Pravila §13.2 — +2 абзаца
|
||||
|
||||
**Files:** `docs/Pravila_raboty_Claude_v1_1.md`
|
||||
|
||||
- [ ] **Step 1:** §13.2 +абзац «Off-phase authoring-tooling»: 3 позиции (#56 skill-creator, #57 plugin-dev, #58 hookify), категория для создания Claude-артефактов; не UI → вне R6/R14; **hookify — особое правило pre-check (PSR_v1 R10.1 hookify-строка hard-rule)**.
|
||||
|
||||
- [ ] **Step 2:** §13.2 +абзац «Off-phase dev-support»: 2 позиции (#59 claude-code-setup read-only анализатор; #60 context7 MCP-документация для known libraries — первый выбор); не UI → вне R6/R14.
|
||||
|
||||
- [ ] **Step 3:** §0 +entry v1.27 («Anthropic dev-tooling: 13-я и 14-я off-phase подкатегории»).
|
||||
|
||||
- [ ] **Step 4:** Шапка Pravila v1.26 → v1.27.
|
||||
|
||||
- [ ] **Step 5:** Commit
|
||||
|
||||
```bash
|
||||
git add docs/Pravila_raboty_Claude_v1_1.md
|
||||
git commit -m "docs(adt): Pravila v1.27 — §13.2 +Off-phase authoring-tooling + dev-support"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: CLAUDE.md — §3/§1/§3.3/§6/§9 (worktree-эксцепшн §5 п.10)
|
||||
|
||||
**Files:** `CLAUDE.md` (прямой Edit в worktree — прецедент A11/C10/discovery, claude-md-management не наводится на worktree-копию), `docs/CHANGELOG_claude_md.md`
|
||||
|
||||
- [ ] **Step 1:** §3 title «55» → «60». §1 priority chain row 2b «55» → «60».
|
||||
|
||||
- [ ] **Step 2:** §3.3 +5 строк #56-#60 по образцу #51-#55 (operations / process-modeling / process-analysis / n8n / discovery). Каждая строка: ID-плагина, marketplace, категория (authoring-tooling/dev-support), роль, когда инвокировать, регламент-cross-ref на PSR R10.1 + Pravila §13.2. Для hookify — **bold pre-check note**.
|
||||
|
||||
- [ ] **Step 3:** §3.3 footer count 55→60 + двенадцатая→четырнадцатая off-phase подкатегория (authoring-tooling + dev-support).
|
||||
|
||||
- [ ] **Step 4:** §0 cross-refs row Pravila v1.26→v1.27 / PSR v3.12→v3.13 / Tooling v2.13→v2.14.
|
||||
|
||||
- [ ] **Step 5:** §6 +абзац «2026-05-18 Anthropic dev-tooling integration: формализованы #56–#60 в 2 новых off-phase подкатегориях…».
|
||||
|
||||
- [ ] **Step 6:** §9 +entry v2.14.
|
||||
|
||||
- [ ] **Step 7:** Шапка CLAUDE.md v2.13 → v2.14.
|
||||
|
||||
- [ ] **Step 8:** CHANGELOG_claude_md.md +entry v2.14.
|
||||
|
||||
- [ ] **Step 9:** Commit
|
||||
|
||||
```bash
|
||||
git add CLAUDE.md docs/CHANGELOG_claude_md.md
|
||||
git commit -m "docs(adt): CLAUDE.md v2.14 + CHANGELOG — register #56-#60 (worktree direct Edit, §5 п.10 эксцепшн)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Карта — refresh узлов + лейблы правил + edge
|
||||
|
||||
**Files:** `docs/automation-graph.html`
|
||||
|
||||
- [ ] **Step 1:** Обновить лейблы 4 узлов-правил: pravila v1.27, claude_md v2.14, psr_v1 v3.13, tooling v2.14. NODE_META.changed для всех 4 → 18.05.2026.
|
||||
|
||||
- [ ] **Step 2:** Обновить nd() 5 узлов (skill_creator, plugin_dev, hookify_plugin, claude_setup, context7):
|
||||
- `desc` — добавить номер «#NN» в начало
|
||||
- `limits` — добавить ключевые ограничения из R10.1 (для hookify — обязательный pre-check; для plugin-dev — вендоренное не трогать; для context7 — первый выбор для known library docs)
|
||||
- `reportsTo` — добавить «PSR_v1 R10.1 Блок 1 / Pravila §13.2 / Tooling §4.31-4.32»
|
||||
|
||||
- [ ] **Step 3:** Добавить 5 рёбер `psr_v1 → {skill_creator, plugin_dev, hookify_plugin, claude_setup, context7}` тип «R10.1 блок 1» (по образцу `psr_v1→adr_kit`/`arch_patterns`/`ccpm`/...). EDGE_DETAILS — поля type «правило», when «всегда», transfers «coverage», mandatory «обязательно», rule «PSR_v1 R10.1 Блок 1». EDGES_NORMAL +5.
|
||||
|
||||
- [ ] **Step 4:** Конфликт-edge `hookify_plugin ↔ hk_pre_claude` (строка 1844): тип `RED` → `GREEN`, rule «D2 R10.1 hookify pre-check (ADR-010)». Конфликт-классификация в legend footer: 🔴1/⚫3/🟢7 → 🔴0/⚫3/🟢8.
|
||||
|
||||
- [ ] **Step 5:** Обновить tooling-узел nd() count «70 / 50» → «75 / 60» (75 — это позиции tooling + ruflo-плагины, 60 — формализованных).
|
||||
|
||||
- [ ] **Step 6:** NODE_META.changed → 18.05.2026 для 5 узлов.
|
||||
|
||||
- [ ] **Step 7:** Smoke (Playwright headless или ручной visual в Edge): NODES.length=124, EDGES.length=135 (130+5), 0 JS-ошибок, hookify_plugin конфликт стал 🟢.
|
||||
|
||||
- [ ] **Step 8:** Commit
|
||||
|
||||
```bash
|
||||
git add docs/automation-graph.html
|
||||
git commit -m "feat(map): adt — register #56-#60 in nd(), 5 edges to psr_v1, hookify conflict 🔴→🟢, rule labels v2.14"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Memory updates
|
||||
|
||||
**Files:** `MEMORY.md` + `feedback_plugin_paired_stack.md` + `project_state.md` + `reference_archive.md` + `project_automation_map.md` + new `project_anthropic_dev_tooling.md`
|
||||
|
||||
- [ ] **Step 1:** Создать `project_anthropic_dev_tooling.md` (новый файл) — краткий summary эпика: 5 позиций, 2 подкатегории, decisions D1-D8, key learnings (формализация L1-паттерна для Anthropic-плагинов, прецедент).
|
||||
|
||||
- [ ] **Step 2:** `MEMORY.md` +pointer на новый memory-файл.
|
||||
|
||||
- [ ] **Step 3:** `feedback_plugin_paired_stack.md` — добавить блок «Обновление 2026-05-18 — Anthropic dev-tooling (новые off-phase подкатегории authoring-tooling + dev-support)». Active versions bump до v2.14/v3.13/v1.27/v2.14. Off-phase подкатегорий теперь 14 (было 12).
|
||||
|
||||
- [ ] **Step 4:** `project_state.md` — branch state и HEAD update (после push в Task 9).
|
||||
|
||||
- [ ] **Step 5:** `reference_archive.md` — version refs sync до v2.14/v3.13/v1.27/v2.14.
|
||||
|
||||
- [ ] **Step 6:** `project_automation_map.md` — добавить entry «2026-05-18 Anthropic dev-tooling: 5 узлов refresh + 5 edge + hookify конфликт 🔴→🟢».
|
||||
|
||||
- [ ] **Step 7:** Commit
|
||||
|
||||
```bash
|
||||
git add ../../../memory/ # путь от worktree до user-level memory — see memory location convention
|
||||
# NB: memory лежит в C:\Users\Administrator\.claude\projects\…\memory — НЕ в репозитории. Memory files правятся через Write, не через git. Commit относится только к репозиторию.
|
||||
```
|
||||
|
||||
**Replan:** memory file commits — N/A. Memory updates делаются через Write, без git. Эта задача не имеет commit-step, только Write-операции.
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Pre-push + push
|
||||
|
||||
**Files:** none (verification + push)
|
||||
|
||||
- [ ] **Step 1:** Pre-commit verification (последний раз — должен быть зелёным от atomic commits в Task 1-7):
|
||||
|
||||
```bash
|
||||
cd ".claude/worktrees/anthropic-dev-tooling"
|
||||
./bin/gitleaks.exe protect --staged --no-banner # 0 leaks ожидается
|
||||
```
|
||||
|
||||
Если квирк #97 «lefthook not in PATH в worktree» — пропустить lefthook, gitleaks вызывать вручную.
|
||||
|
||||
- [ ] **Step 2:** Pre-push gitleaks full history:
|
||||
|
||||
```bash
|
||||
./bin/gitleaks.exe detect --no-banner # должен быть 0 leaks
|
||||
```
|
||||
|
||||
- [ ] **Step 3:** Pre-push lychee — **запускать из главного дерева** (`c:/моя/проекты/портал crm/Документация/`, не из worktree — квирк #92, относительные пути ломаются из worktree):
|
||||
|
||||
```bash
|
||||
cd "c:/моя/проекты/портал crm/Документация"
|
||||
./bin/lychee.exe --offline --no-progress . 2>&1 | tail -5
|
||||
# ожидается 0 broken
|
||||
```
|
||||
|
||||
- [ ] **Step 4:** Push:
|
||||
|
||||
```bash
|
||||
cd ".claude/worktrees/anthropic-dev-tooling"
|
||||
git push origin feat/anthropic-dev-tooling:main
|
||||
```
|
||||
|
||||
Pattern `<ветка>:main` — разрешённый в `~/.claude/settings.json` `Bash(git push origin main:*)` (хотя тут он `<ветка>:main`, проверить permissions; если deny — ручной push заказчиком).
|
||||
|
||||
- [ ] **Step 5:** Verify push:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git rev-parse origin/main # должен совпадать с HEAD worktree
|
||||
```
|
||||
|
||||
- [ ] **Step 6:** Update `project_state.md` post-push с новым origin/main HEAD SHA.
|
||||
|
||||
- [ ] **Step 7:** Сообщить заказчику: «эпик ADT закрыт, push прошёл, новые версии v2.14/v3.13/v1.27/v2.14 на origin/main».
|
||||
|
||||
---
|
||||
|
||||
## Verification Plan
|
||||
|
||||
После каждой task (atomic commit) — короткая локальная проверка:
|
||||
- Task 3: `grep "Итого формализованных позиций.*60" docs/Tooling_v8_3.md` → 1 match
|
||||
- Task 4: `grep -c "skill-creator\|plugin-dev\|hookify\|claude-code-setup\|context7" docs/Plugin_stack_rules_v1.md` → ≥5
|
||||
- Task 5: `grep "authoring-tooling\|dev-support" docs/Pravila_raboty_Claude_v1_1.md` → ≥2
|
||||
- Task 6: `grep "v2.14" CLAUDE.md` → ≥2 (шапка + §0/§9)
|
||||
- Task 7: smoke карты — Playwright или Edge
|
||||
|
||||
Перед claim «эпик закрыт» — invoke `superpowers:verification-before-completion`.
|
||||
|
||||
---
|
||||
|
||||
## Risk register (post-execution)
|
||||
|
||||
- **Push permissions:** `Bash(git push origin main:*)` allowed; `<ветка>:main` — under same pattern? Verify Task 9 Step 4. Если deny — pause, ручной push заказчиком.
|
||||
- **lychee из worktree:** квирк #92 — relative paths ломаются. **Mitigation:** Step 3 из главного дерева.
|
||||
- **Wholesale rebase нужен:** если за время выполнения origin/main продвинется (parallel session) — Task 9 Step 4 fail, нужен rebase + retry. Mitigation: эпик короткий, parallel sessions сейчас нет (single Claude Code instance).
|
||||
- **Memory file path mistake** в Task 8: memory лежит на user-level, не в репозитории — учтено в Task 8 Replan.
|
||||
- **adr-judge job 9 in lefthook:** ADR-010 проходит regex-валидацию? Verify Task 2.
|
||||
@@ -0,0 +1,995 @@
|
||||
# Parallel Sessions Coordination — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Лечим два класса параллельных-сессий инцидентов (субагенты теряются между worktree / нормативка дрейфует) — добавляем Pravila §15 hard-rule, заявочный лог `docs/sessions/CURRENT.md`, PreToolUse-хук `tools/subagent-prompt-prefix.mjs`, references-wrapper к скилу subagent-driven-development.
|
||||
|
||||
**Architecture:** 4 артефакта, 0 новых плагинов / MCP. Pravila §15 — корневое правило. CURRENT.md — координация scope/version-claims. Хук — авто-инжект git-safety заголовка в каждый Task-prompt. Wrapper-скил — verify-чеклист контроллера.
|
||||
|
||||
**Tech Stack:** Markdown (нормативка + лог), Node 22 ESM (`tools/*.mjs` с `node --test`), git, lefthook (pre-commit), Bash (на Windows через Git Bash).
|
||||
|
||||
**Spec:** [docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md](../specs/2026-05-18-parallel-sessions-coordination-design.md)
|
||||
|
||||
**Branch:** `feat/parallel-sessions-coordination` (создана от origin/main `b40f2c8`, верифицирована pre-flight — `git log HEAD..origin/main` пуст).
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
**Создаются:**
|
||||
|
||||
- `docs/sessions/README.md` — описание формата CURRENT.md, лайфциклов, конфликт-резолюции.
|
||||
- `docs/sessions/CURRENT.md` — заявочный лог + retro-claim для активных worktrees на момент имплементации.
|
||||
- `tools/subagent-prompt-prefix.mjs` — PreToolUse-хук на Task, инжектит cwd/branch/HEAD заголовок.
|
||||
- `tools/subagent-prompt-prefix.test.mjs` — `node --test` test-suite.
|
||||
- `.claude/skills/subagent-driven-development/SKILL.md` — wrapper-скил с проектным verify-протоколом (references-обёртка над marketplace-скилом).
|
||||
- `.claude/skills/subagent-driven-development/references/git-safety-checklist.md` — pre/post-subagent чеклист, формат GIT REPORT.
|
||||
|
||||
**Модифицируются:**
|
||||
|
||||
- `docs/Pravila_raboty_Claude_v1_1.md` — добавить §15 (15.1 + 15.2 + 15.3), bump header v1.26 → v1.27, add §10 changelog entry.
|
||||
- `CLAUDE.md` — §1 priority chain footer-абзац (cross-ref на §15), §0 row Pravila version v1.26 → v1.27. Через `/claude-md-management:claude-md-improver`.
|
||||
- `.claude/settings.json` — добавить PreToolUse block `matcher: "Task"`.
|
||||
- `cspell-words.txt` — добавить транслитерации появляющиеся в хуке/wrapper-скиле (по факту падений).
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Pravila §15 hard-rule
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (add §15 after §14, bump header version, add §10 changelog entry)
|
||||
|
||||
- [ ] **Step 1.1: Verify §15 still free**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
grep -nE '^## 1[5-9]\.|^## 2[0-9]\.' docs/Pravila_raboty_Claude_v1_1.md
|
||||
```
|
||||
|
||||
Expected: empty (no §15 collision). If non-empty — STOP, разбор.
|
||||
|
||||
- [ ] **Step 1.2: Find insertion point after §14**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
grep -nE '^## (14|15|11)\.' docs/Pravila_raboty_Claude_v1_1.md
|
||||
```
|
||||
|
||||
Expected: line for `## 14. Ruflo Queen routing — hard rule (триггер queen/королева)` (was line 820 at design time; verify актуально). Find end-of-§14 boundary (next `^##` heading или EOF).
|
||||
|
||||
- [ ] **Step 1.3: Add §15 content**
|
||||
|
||||
Insert after the closing line of §14 (before next `##` heading or EOF). Exact text:
|
||||
|
||||
```markdown
|
||||
## 15. Параллельные сессии — hard rule (субагенты + git, нормативка + pre-flight sync)
|
||||
|
||||
Действует с 18.05.2026. **Hard rule**: §9 «Отступления» к §15 не применяется (как §12 и §14).
|
||||
|
||||
### 15.1 Субагенты + git
|
||||
|
||||
Git-коммит-задачи субагенту (любой `Task`-инвокейшн, чей prompt содержит `git commit`, `git push`, `git stage`, `git checkout`, `git switch`, `git merge`, `git rebase`, либо где явно ожидается коммит в результате) — **только модель Sonnet или Opus**, никогда Haiku. Контроллер, делегирующий git-операцию Haiku-субагенту — нарушение §15.1, фиксируется в feedback того же уровня, что §12.
|
||||
|
||||
Исключение — read-only git-операции (`git log`, `git status`, `git diff`, `git rev-parse`, `git branch --show-current`, `git worktree list`) — разрешены любой модели.
|
||||
|
||||
Прецедент-источник: Sprint 6 (17.05.2026) — Haiku-субагенты угнали ветку параллельной сессии, устранено через `git reflog` + `reset`. Корневая причина — отсутствие верификации HEAD/branch после Task-инвокации. Verify-протокол — `.claude/skills/subagent-driven-development/references/git-safety-checklist.md`.
|
||||
|
||||
### 15.2 Нормативные правки + pre-flight sync
|
||||
|
||||
Любая правка файлов из списка «нормативка» (см. ниже) выполняется **только** на актуальной базе `origin/main`. Pre-flight обязателен:
|
||||
|
||||
```bash
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
```
|
||||
|
||||
Если есть untracked commits на `origin/main`, ребейз/merge **до начала правки**, не после.
|
||||
|
||||
Параллельная нормативная правка на устаревшей базе — нарушение §15.2. Признак нарушения: коммит правит файл, чья последняя версия на `origin/main` новее, чем версия в parent коммите правки.
|
||||
|
||||
**Список «нормативка» — 8 позиций:**
|
||||
|
||||
1. `docs/Pravila_raboty_Claude_v1_1.md`
|
||||
2. `CLAUDE.md`
|
||||
3. `docs/Tooling_v8_3.md`
|
||||
4. `docs/Plugin_stack_rules_v1.md`
|
||||
5. `memory/MEMORY.md` (и все `memory/*.md`)
|
||||
6. `docs/Открытые_вопросы_v8_3.md`
|
||||
7. `docs/adr/*.md` (glob — collision на ADR-NNN номере = тот же класс, что version-bump нормативки)
|
||||
8. `db/schema.sql` (параллельные миграции из разных сессий = реальный риск; запись в `db/CHANGELOG_schema.md` сама не защищает от version-base дрейфа)
|
||||
|
||||
Расширение списка — отдельная правка §15.2, не «по ощущениям».
|
||||
|
||||
Дополнительно: при параллельных активных сессиях контроллер обязан добавить запись в `docs/sessions/CURRENT.md` до первой нормативной правки (claim) — формат и жизненный цикл записи описаны в `docs/sessions/README.md`. Конфликт-резолюция (file overlap / section overlap / version-claim collision) — там же.
|
||||
|
||||
### 15.3 Cross-refs в других файлах
|
||||
|
||||
- **CLAUDE.md §1 priority chain** — §15 рядом с §12 и §14 как hard-rule (см. footer-абзац после цепочки).
|
||||
- **PSR_v1** — не правится: §15 не про координацию плагинов, а про координацию сессий.
|
||||
- **Tooling** — не правится.
|
||||
|
||||
```
|
||||
|
||||
- [ ] **Step 1.4: Bump Pravila header v1.26 → v1.27**
|
||||
|
||||
Find first occurrence of `v1.26` in the file header (~lines 1–10) and replace one instance with `v1.27`. Update date if needed — `от 18.05.2026` stays.
|
||||
|
||||
Run check после правки:
|
||||
```bash
|
||||
head -10 docs/Pravila_raboty_Claude_v1_1.md
|
||||
```
|
||||
|
||||
Expected: header содержит `v1.27 от 18.05.2026`.
|
||||
|
||||
- [ ] **Step 1.5: Add §10 changelog entry**
|
||||
|
||||
Find `## 10. История версий` (was line 561). Add at the **top** of the version list (newest first per existing pattern; verify pattern in §10 head — if oldest-first, append at bottom; the entry text is the same):
|
||||
|
||||
```markdown
|
||||
**v1.27 от 18.05.2026** — Параллельные сессии: координация. +§15 hard-rule (15.1 субагенты+git Sonnet/Opus only, 15.2 нормативка+pre-flight sync, 15.3 cross-refs). §15 третье hard-rule после §12 и §14; список «нормативка» — 8 позиций. Лечит два класса инцидентов параллельных-сессий: (A) субагенты теряются между worktree (Sprint 6 прецедент), (B) нормативка/MEMORY дрейфует (Tooling v2.11 collision 17.05.2026). Спек — `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md`, план — `docs/superpowers/plans/2026-05-18-parallel-sessions-coordination.md`.
|
||||
```
|
||||
|
||||
- [ ] **Step 1.6: Verify Pravila correctness**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
grep -cE '^## 15\.' docs/Pravila_raboty_Claude_v1_1.md
|
||||
grep -cE '^### 15\.[123]' docs/Pravila_raboty_Claude_v1_1.md
|
||||
grep -c 'v1.27' docs/Pravila_raboty_Claude_v1_1.md
|
||||
```
|
||||
|
||||
Expected: `1`, `3`, `≥2` (header + §10 entry).
|
||||
|
||||
- [ ] **Step 1.7: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/Pravila_raboty_Claude_v1_1.md
|
||||
git commit -m "feat(pravila): §15 hard-rule — параллельные сессии (субагенты+git, нормативка+pre-flight sync)
|
||||
|
||||
Bump Pravila v1.26 → v1.27 + §10 changelog entry. §15 третье hard-rule
|
||||
после §12 (Superpowers) и §14 (Ruflo Queen). §15 лечит два класса
|
||||
инцидентов параллельных Claude-сессий — субагенты путают ветки/worktree
|
||||
(Sprint 6) и нормативка/MEMORY дрейфует (Tooling v2.11 collision 17.05.2026).
|
||||
|
||||
Cross-refs to CLAUDE.md §1 — отдельная правка через
|
||||
/claude-md-management:claude-md-improver (Task 5 плана).
|
||||
|
||||
Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md
|
||||
Plan: docs/superpowers/plans/2026-05-18-parallel-sessions-coordination.md
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
Pre-commit chain должен пройти: gitleaks 0, markdownlint 0, cspell 0 (если новые транслитерации появятся — добавить в `cspell-words.txt` отдельным fixup-commit'ом до основного коммита).
|
||||
|
||||
---
|
||||
|
||||
## Task 2: docs/sessions/ — каталог + README + CURRENT.md retro-claim
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `docs/sessions/README.md`
|
||||
- Create: `docs/sessions/CURRENT.md`
|
||||
|
||||
- [ ] **Step 2.1: Resolve active worktrees**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git worktree list --porcelain
|
||||
```
|
||||
|
||||
Expected: список worktree (на 18.05.2026 — 16 штук). Сохранить вывод для retro-claim записей.
|
||||
|
||||
- [ ] **Step 2.2: Create docs/sessions/README.md**
|
||||
|
||||
Полное содержимое (никаких placeholder'ов):
|
||||
|
||||
```markdown
|
||||
# docs/sessions/ — координация параллельных Claude-сессий
|
||||
|
||||
**Источник правила:** Pravila §15.2 (раздел про CURRENT.md в конце текста §15.2).
|
||||
|
||||
## Назначение
|
||||
|
||||
`docs/sessions/CURRENT.md` — заявочный лог активных параллельных Claude-сессий проекта. Решает класс инцидентов «нормативка/MEMORY дрейфует» (см. spec — `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md`).
|
||||
|
||||
## Когда писать в CURRENT.md
|
||||
|
||||
Перед **первой** нормативной правкой в сессии (правки файлов из списка §15.2 — Pravila, CLAUDE.md, Tooling, PSR_v1, MEMORY.md, Открытые_вопросы, docs/adr/*, db/schema.sql). Запись добавляется отдельным атомарным коммитом `sessions: claim <topic>` — до plan-документа и до первой содержательной правки.
|
||||
|
||||
## Формат записи
|
||||
|
||||
```markdown
|
||||
## session: YYYY-MM-DD-<topic-kebab>
|
||||
- branch: <git branch --show-current>
|
||||
- worktree: <git rev-parse --show-toplevel>
|
||||
- started: <ISO 8601 with timezone>
|
||||
- scope-files:
|
||||
- <relative path> [§/раздел/строка]
|
||||
- ...
|
||||
- version-claims:
|
||||
- <file-or-topic>: <from> → <to>
|
||||
- ...
|
||||
- status: in-progress | closed-<commit-sha>
|
||||
- closes: <relative path к plan-документу>
|
||||
```
|
||||
|
||||
`scope-files` — какие нормативные файлы и в каких секциях правит сессия. `version-claims` — какие новые версии (Tooling 2.X, Pravila 1.Y и т.п.) или номера (ADR-NNN) сессия резервирует.
|
||||
|
||||
## Жизненный цикл
|
||||
|
||||
- **claim** — добавить запись со `status: in-progress` + атомарный коммит `sessions: claim <topic>`.
|
||||
- **check** — pre-flight перед нормативной правкой: `Read docs/sessions/CURRENT.md` + проверить пересечение `scope-files` / `version-claims` с активными записями.
|
||||
- **release** — на закрытии (после push на main) изменить `status: closed-<commit-sha>` (запись остаётся в CURRENT.md — append-only-вариант).
|
||||
|
||||
Closed-записи переезжают в `docs/sessions/archive/YYYY-MM.md` через ≥30 дней после закрытия (ручная архивация раз в месяц, не cron).
|
||||
|
||||
## Конфликт-резолюция
|
||||
|
||||
| Тип пересечения | Реакция |
|
||||
|---|---|
|
||||
| Файловое пересечение (одинаковый файл, разные секции) | **soft-warn** — продолжать можно, но pre-flight fetch перед каждым коммитом обязателен (§15.2). |
|
||||
| Section-пересечение (одна и та же секция §X.Y) | **hard-stop** — координация с заказчиком до начала правки. |
|
||||
| Version-claim collision (две сессии заявили один номер) | **hard-stop** — кто claim'нул раньше (по `started`-timestamp), тот его и берёт. Вторая сессия сдвигается на +1. |
|
||||
|
||||
## Pre-flight snippet (для plan-документов и скила subagent-driven-development)
|
||||
|
||||
```bash
|
||||
# Перед нормативной правкой:
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
grep -A 20 'status: in-progress' docs/sessions/CURRENT.md
|
||||
```
|
||||
|
||||
## Что мы НЕ делаем (явный YAGNI)
|
||||
|
||||
- Pre-commit hook на CURRENT.md — добавим только если будут зафиксированы инциденты игнорирования.
|
||||
- TTL / auto-expire записей — добавим, если файл реально засорится.
|
||||
- Machine-readable JSON-формат — markdown достаточен, парсится grep/sed.
|
||||
- Интеграция с GitHub Issues — отдельная тема, не блокер.
|
||||
|
||||
```
|
||||
|
||||
- [ ] **Step 2.3: Create docs/sessions/CURRENT.md с retro-claim**
|
||||
|
||||
Структура с заголовком + текущей сессией parallel-sessions-coordination + retro-claim записями для каждой активной worktree из Step 2.1.
|
||||
|
||||
Для текущей сессии (заполнить gотовыми значениями):
|
||||
|
||||
```markdown
|
||||
# CURRENT.md — активные Claude-сессии
|
||||
|
||||
> Формат и жизненный цикл записей: [docs/sessions/README.md](README.md).
|
||||
> Pravila §15.2 — описание правила в нормативке.
|
||||
|
||||
## session: 2026-05-18-parallel-sessions-coordination
|
||||
- branch: feat/parallel-sessions-coordination
|
||||
- worktree: c:/моя/проекты/портал crm/Документация
|
||||
- started: 2026-05-18T09:30+03:00
|
||||
- scope-files:
|
||||
- docs/Pravila_raboty_Claude_v1_1.md §15 (new)
|
||||
- CLAUDE.md §1 (cross-ref), §0 (Pravila version row)
|
||||
- tools/subagent-prompt-prefix.mjs (new)
|
||||
- .claude/settings.json (PreToolUse Task block)
|
||||
- .claude/skills/subagent-driven-development/ (new wrapper-skill)
|
||||
- docs/sessions/README.md, CURRENT.md (new — этот файл)
|
||||
- version-claims:
|
||||
- Pravila: 1.26 → 1.27
|
||||
- status: in-progress
|
||||
- closes: docs/superpowers/plans/2026-05-18-parallel-sessions-coordination.md
|
||||
|
||||
---
|
||||
|
||||
## Retro-claim'ы активных worktrees (snapshot 2026-05-18)
|
||||
|
||||
Per Pravila §15.2 — backfill для существующих параллельных сессий. Эти записи retroactive, scope/version-claims заполнены best-effort из последних коммитов worktree-веток. Активные сессии при возобновлении работы обновляют свой блок.
|
||||
```
|
||||
|
||||
Дальше — по одной записи на каждую worktree из Step 2.1 (кроме основной `Документация`, которая = текущая сессия). Для каждой записи:
|
||||
|
||||
- `branch`: имя ветки из `git worktree list`
|
||||
- `worktree`: путь
|
||||
- `started`: `2026-05-18T00:00+03:00` (best-effort backfill, не точный)
|
||||
- `scope-files`: best-effort из последнего коммита ветки (`git log -1 --name-only <branch>`). Если scope непонятен — `- <unknown — backfill>`
|
||||
- `version-claims`: `- <none verified — backfill>` если непонятно
|
||||
- `status`: `in-progress (backfilled)` если HEAD ветки не на origin/main, иначе `closed-<sha> (backfilled)`
|
||||
|
||||
Например (шаблон для одной retro-записи; повторить для каждой worktree):
|
||||
|
||||
```markdown
|
||||
## session: 2026-05-XX-<topic-from-branch-name>
|
||||
- branch: <worktree-branch-name>
|
||||
- worktree: <worktree path>
|
||||
- started: 2026-05-18T00:00+03:00 (backfill)
|
||||
- scope-files:
|
||||
- <best-effort from git log -1 --name-only>
|
||||
- version-claims:
|
||||
- <none verified — backfill>
|
||||
- status: in-progress (backfilled) | closed-<sha> (backfilled)
|
||||
- closes: <unknown — backfill>
|
||||
```
|
||||
|
||||
- [ ] **Step 2.4: Verify created files**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
ls -la docs/sessions/
|
||||
wc -l docs/sessions/README.md docs/sessions/CURRENT.md
|
||||
grep -c '^## session:' docs/sessions/CURRENT.md
|
||||
```
|
||||
|
||||
Expected: оба файла существуют; CURRENT.md содержит ≥1 запись (текущая) + retro-claim для каждой worktree из Step 2.1.
|
||||
|
||||
- [ ] **Step 2.5: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/sessions/
|
||||
git commit -m "feat(sessions): CURRENT.md + README — заявочный лог параллельных Claude-сессий
|
||||
|
||||
Создаём docs/sessions/ — координация per Pravila §15.2 (claim/check/release
|
||||
жизненный цикл, конфликт-резолюция). CURRENT.md содержит текущую сессию
|
||||
parallel-sessions-coordination + retro-claim записи для существующих
|
||||
активных worktrees (16 штук на 2026-05-18).
|
||||
|
||||
Backfill scope/version-claims заполнен best-effort; активные сессии
|
||||
обновят свой блок при возобновлении работы.
|
||||
|
||||
Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Hook tests (TDD — failing first)
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `tools/subagent-prompt-prefix.test.mjs`
|
||||
|
||||
- [ ] **Step 3.1: Write the failing test file**
|
||||
|
||||
Полное содержимое (`node --test` runner, паттерн один-в-один с `tools/ruflo-recall-hook.test.mjs`):
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Tests for tools/subagent-prompt-prefix.mjs — PreToolUse Task git-safety header inject.
|
||||
*
|
||||
* Per Pravila §15.1 — hook injects cwd/branch/HEAD/worktree-root into каждый Task-prompt.
|
||||
* FAIL-OPEN: any error → return {continue: true} без модификации.
|
||||
*
|
||||
* Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md §4
|
||||
*/
|
||||
import { test } from 'node:test';
|
||||
import { strict as assert } from 'node:assert';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { dirname, join } from 'node:path';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const HOOK_PATH = join(__dirname, 'subagent-prompt-prefix.mjs');
|
||||
|
||||
function runHook(stdinJson) {
|
||||
return spawnSync('node', [HOOK_PATH], {
|
||||
input: JSON.stringify(stdinJson),
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
});
|
||||
}
|
||||
|
||||
test('hook injects SUBAGENT GIT-SAFETY HEADER into Task prompt', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Task',
|
||||
tool_input: { prompt: 'do something' },
|
||||
});
|
||||
assert.equal(result.status, 0, `stderr: ${result.stderr}`);
|
||||
const out = JSON.parse(result.stdout);
|
||||
assert.ok(out.hookSpecificOutput, 'has hookSpecificOutput');
|
||||
assert.equal(out.hookSpecificOutput.hookEventName, 'PreToolUse');
|
||||
assert.equal(out.hookSpecificOutput.permissionDecision, 'allow');
|
||||
const newPrompt = out.hookSpecificOutput.updatedInput.prompt;
|
||||
assert.match(newPrompt, /=== SUBAGENT GIT-SAFETY HEADER/);
|
||||
assert.match(newPrompt, /=== END SUBAGENT GIT-SAFETY HEADER ===/);
|
||||
assert.match(newPrompt, /do something/, 'preserves original prompt');
|
||||
});
|
||||
|
||||
test('hook injects real cwd, branch, HEAD values', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Task',
|
||||
tool_input: { prompt: 'noop' },
|
||||
});
|
||||
assert.equal(result.status, 0);
|
||||
const out = JSON.parse(result.stdout);
|
||||
const newPrompt = out.hookSpecificOutput.updatedInput.prompt;
|
||||
// cwd — absolute path
|
||||
assert.match(newPrompt, /Working directory \(cwd\): [A-Za-z]:[\\/]|Working directory \(cwd\): \//);
|
||||
// branch — non-empty
|
||||
assert.match(newPrompt, /Branch \(git branch --show-current\): \S+/);
|
||||
// HEAD — 40-char SHA
|
||||
assert.match(newPrompt, /Parent commit \(git rev-parse HEAD\): [0-9a-f]{40}/);
|
||||
});
|
||||
|
||||
test('hook passes through non-Task tools without modification', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Edit',
|
||||
tool_input: { file_path: '/foo', old_string: 'a', new_string: 'b' },
|
||||
});
|
||||
assert.equal(result.status, 0);
|
||||
const out = JSON.parse(result.stdout);
|
||||
// Non-Task → either {continue: true} OR no updatedInput
|
||||
if (out.hookSpecificOutput) {
|
||||
assert.equal(out.hookSpecificOutput.updatedInput, undefined);
|
||||
} else {
|
||||
assert.equal(out.continue, true);
|
||||
}
|
||||
});
|
||||
|
||||
test('hook fail-open on malformed stdin', () => {
|
||||
const result = spawnSync('node', [HOOK_PATH], {
|
||||
input: 'not-json',
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
});
|
||||
assert.equal(result.status, 0, `should not crash; stderr: ${result.stderr}`);
|
||||
// Either {continue: true} or empty output — both acceptable fail-open
|
||||
});
|
||||
|
||||
test('hook fail-open when git not available', () => {
|
||||
const result = spawnSync('node', [HOOK_PATH], {
|
||||
input: JSON.stringify({ tool_name: 'Task', tool_input: { prompt: 'x' } }),
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
env: { ...process.env, PATH: '' }, // strip PATH → git not found
|
||||
});
|
||||
assert.equal(result.status, 0, `should not crash when git missing; stderr: ${result.stderr}`);
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3.2: Verify tests FAIL (hook doesn't exist yet)**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
node --test tools/subagent-prompt-prefix.test.mjs
|
||||
```
|
||||
|
||||
Expected: ALL tests FAIL — `Cannot find module '.../subagent-prompt-prefix.mjs'` or similar ENOENT. Это **ожидаемое** — TDD red-phase.
|
||||
|
||||
- [ ] **Step 3.3: Commit (TDD: failing test первым)**
|
||||
|
||||
```bash
|
||||
git add tools/subagent-prompt-prefix.test.mjs
|
||||
git commit -m "test(hooks): subagent-prompt-prefix — failing tests (TDD red)
|
||||
|
||||
5 тестов для Task git-safety inject хука:
|
||||
- inject SUBAGENT GIT-SAFETY HEADER в Task-prompt
|
||||
- inject real cwd/branch/HEAD/worktree-root
|
||||
- passes through non-Task tools
|
||||
- fail-open on malformed stdin
|
||||
- fail-open when git unavailable
|
||||
|
||||
Tests FAIL — hook implementation в следующем коммите (TDD green-phase).
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Hook implementation (TDD green)
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `tools/subagent-prompt-prefix.mjs`
|
||||
|
||||
- [ ] **Step 4.1: Write hook implementation**
|
||||
|
||||
Полное содержимое (паттерн из `tools/ruflo-recall-hook.mjs` — `execFile`, FAIL-OPEN, ESM):
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* PreToolUse hook — git-safety header inject for Task tool.
|
||||
*
|
||||
* For каждый Task-инвокейшн контроллера: дописывает в начало tool_input.prompt
|
||||
* заголовок с cwd / branch / parent SHA / worktree-root + правилами поведения
|
||||
* (rule 1–5). Это компенсирует класс инцидентов «субагент путает ветку/worktree»
|
||||
* (Sprint 6, Pravila §15.1).
|
||||
*
|
||||
* FAIL-OPEN: любая ошибка / тайм-аут / git-не-в-PATH → {continue: true} без
|
||||
* модификации; хук НИКОГДА не блокирует Task.
|
||||
*
|
||||
* Non-Task tools — pass-through без модификации.
|
||||
*
|
||||
* Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md §4
|
||||
* Rule: docs/Pravila_raboty_Claude_v1_1.md §15.1
|
||||
*/
|
||||
import { execFile } from 'node:child_process';
|
||||
import { promisify } from 'node:util';
|
||||
|
||||
const execFileP = promisify(execFile);
|
||||
const GIT_TIMEOUT_MS = 1500;
|
||||
|
||||
/** Read all stdin into a string. */
|
||||
async function readStdin() {
|
||||
let buf = '';
|
||||
for await (const chunk of process.stdin) buf += chunk;
|
||||
return buf;
|
||||
}
|
||||
|
||||
/** Parse hook input JSON; return null on any parse error. */
|
||||
function parseHookInput(raw) {
|
||||
try { return JSON.parse(raw); } catch { return null; }
|
||||
}
|
||||
|
||||
/** Run a single fixed-args git command; return trimmed stdout, or null on any error. */
|
||||
async function gitCmd(args) {
|
||||
try {
|
||||
const { stdout } = await execFileP('git', args, { timeout: GIT_TIMEOUT_MS, encoding: 'utf8' });
|
||||
return stdout.trim();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Build the safety header block. Returns null if any of the 4 git values can't be resolved. */
|
||||
async function buildHeader() {
|
||||
const cwd = process.cwd();
|
||||
const [branch, head, top] = await Promise.all([
|
||||
gitCmd(['branch', '--show-current']),
|
||||
gitCmd(['rev-parse', 'HEAD']),
|
||||
gitCmd(['rev-parse', '--show-toplevel']),
|
||||
]);
|
||||
if (!branch || !head || !top) return null;
|
||||
return [
|
||||
'=== SUBAGENT GIT-SAFETY HEADER (Pravila §15.1, auto-injected) ===',
|
||||
`Working directory (cwd): ${cwd}`,
|
||||
`Branch (git branch --show-current): ${branch}`,
|
||||
`Parent commit (git rev-parse HEAD): ${head}`,
|
||||
`Worktree root (git rev-parse --show-toplevel): ${top}`,
|
||||
'',
|
||||
'ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:',
|
||||
'1. Все git-операции выполняй ТОЛЬКО внутри cwd выше. Если pwd ≠ cwd — STOP, верни ошибку.',
|
||||
'2. ЗАПРЕЩЕНО: `git checkout <branch>`, `git switch <branch>`, `git checkout -b`, `git branch -m`, `git worktree add/remove`, `git push --force`, `git reset --hard`.',
|
||||
'3. После КАЖДОГО `git commit` — выполни `git rev-parse HEAD` и `git branch --show-current`, выпиши результат в ответ. Это обязательная часть отчёта.',
|
||||
'4. Если обнаружил, что находишься не в той ветке/worktree — STOP, не правь ничего, верни ошибку с raw output `git status` и `git branch --show-current`.',
|
||||
'5. Если задача не требует git-операций (только Edit/Read/Grep) — этот блок информационный, follow rule 1.',
|
||||
'',
|
||||
'=== END SUBAGENT GIT-SAFETY HEADER ===',
|
||||
'',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
/** Emit fail-open response and exit 0. */
|
||||
function failOpen() {
|
||||
process.stdout.write(JSON.stringify({ continue: true }));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const raw = await readStdin();
|
||||
const input = parseHookInput(raw);
|
||||
if (!input) return failOpen();
|
||||
|
||||
// Non-Task — pass-through
|
||||
if (input.tool_name !== 'Task') return failOpen();
|
||||
|
||||
const originalPrompt = input.tool_input?.prompt;
|
||||
if (typeof originalPrompt !== 'string') return failOpen();
|
||||
|
||||
const header = await buildHeader();
|
||||
if (!header) {
|
||||
// git unavailable / not in worktree — fail-open per spec §4.5 edge-case 3
|
||||
process.stderr.write('[subagent-prompt-prefix] git resolution failed — passing through\n');
|
||||
return failOpen();
|
||||
}
|
||||
|
||||
const newPrompt = header + originalPrompt;
|
||||
process.stdout.write(JSON.stringify({
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'PreToolUse',
|
||||
permissionDecision: 'allow',
|
||||
permissionDecisionReason: 'git-safety header injected (Pravila §15.1)',
|
||||
updatedInput: { prompt: newPrompt },
|
||||
},
|
||||
}));
|
||||
}
|
||||
|
||||
main().catch(() => failOpen());
|
||||
```
|
||||
|
||||
- [ ] **Step 4.2: Run tests — verify GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
node --test tools/subagent-prompt-prefix.test.mjs
|
||||
```
|
||||
|
||||
Expected: ALL 5 tests PASS (`# pass 5 / # fail 0`).
|
||||
|
||||
Если какой-то тест падает — STOP, фикс реализации (НЕ теста), повторить.
|
||||
|
||||
- [ ] **Step 4.3: Smoke test inject вручную**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
echo '{"tool_name":"Task","tool_input":{"prompt":"hello"}}' | node tools/subagent-prompt-prefix.mjs | python -m json.tool
|
||||
```
|
||||
|
||||
Expected: JSON с `hookSpecificOutput.updatedInput.prompt`, начинающимся `=== SUBAGENT GIT-SAFETY HEADER`, с реальными cwd/branch/HEAD значениями.
|
||||
|
||||
- [ ] **Step 4.4: Commit**
|
||||
|
||||
```bash
|
||||
git add tools/subagent-prompt-prefix.mjs
|
||||
git commit -m "feat(hooks): subagent-prompt-prefix — PreToolUse git-safety inject (TDD green)
|
||||
|
||||
Per Pravila §15.1 — инжектит cwd/branch/HEAD/worktree-root + правила
|
||||
поведения в каждый Task-prompt. FAIL-OPEN на любой ошибке (git
|
||||
не в PATH, malformed stdin, non-Task tools).
|
||||
|
||||
Все 5 тестов из subagent-prompt-prefix.test.mjs PASS.
|
||||
Регистрация в .claude/settings.json — Task 6 плана.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: CLAUDE.md cross-ref через claude-md-management
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `CLAUDE.md` (через плагин, не прямой Edit)
|
||||
|
||||
- [ ] **Step 5.1: Запустить /claude-md-management:claude-md-improver**
|
||||
|
||||
Через слэш-команду в Claude Code. Передать конкретные правки:
|
||||
|
||||
> Обнови CLAUDE.md под добавление Pravila §15:
|
||||
>
|
||||
> 1. **§0 cross-ref row Pravila** — `v1.26` → `v1.27`. Сводный комментарий в скобках после версии: «(v1.27 от 18.05.2026 — §15 hard-rule: параллельные сессии (15.1 субагенты+git, 15.2 нормативка+pre-flight sync, 15.3 cross-refs); третье hard-rule после §12 и §14)».
|
||||
>
|
||||
> 2. **§1 priority chain** — добавить **footer-абзац** после блок-схемы цепочки (после слов «...alongside CLAUDE.md как корневая карта Claude Code.»). Текст footer-абзаца:
|
||||
>
|
||||
> > **Hard-rules вне §9 «Отступления»** (Pravila): §12 (Superpowers — инвокация skill ПЕРВОЙ), §14 (Ruflo Queen routing — триггер queen/королева), **§15** (параллельные сессии — 15.1 субагенты+git Sonnet/Opus only, 15.2 нормативка+pre-flight sync с 8-позиционным списком, 15.3 cross-refs). Эти три параграфа Pravila — explicit override-floor под §9; transitive hard-rule через §13 — координация Plugin_stack_rules_v1.
|
||||
>
|
||||
> 1. **§9 «История версий»** — добавить запись v2.14 (или next-free version) с описанием изменений согласно §6 шаблону предыдущих записей.
|
||||
|
||||
Плагин сам бамп'нет шапку CLAUDE.md (v2.13 → v2.14) и сделает commit per §5 п.10.
|
||||
|
||||
- [ ] **Step 5.2: Verify after plugin run**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git log -1 --stat
|
||||
grep -c 'v1.27' CLAUDE.md
|
||||
grep -c '§15' CLAUDE.md
|
||||
```
|
||||
|
||||
Expected: latest коммит трогает только CLAUDE.md; `v1.27` встречается ≥1 раз; `§15` встречается ≥2 раз (§0 + §1 footer).
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Register hook в .claude/settings.json
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `.claude/settings.json` — добавить новый `PreToolUse` block с `matcher: "Task"`
|
||||
|
||||
- [ ] **Step 6.1: Найти существующий PreToolUse секцию**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
grep -n '"PreToolUse"' .claude/settings.json
|
||||
```
|
||||
|
||||
Expected: одна строка (например `"PreToolUse": [`).
|
||||
|
||||
- [ ] **Step 6.2: Добавить новый matcher block**
|
||||
|
||||
Внутри массива `PreToolUse` добавить **новый** объект-block (НЕ внутри существующего `matcher: "Edit|Write"` block, отдельный объект массива):
|
||||
|
||||
```json
|
||||
{
|
||||
"matcher": "Task",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node \"C:/моя/проекты/портал crm/Документация/tools/subagent-prompt-prefix.mjs\""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Точный путь — абсолютный (паттерн из существующих ruflo-хуков в этом же файле). Запятая после предыдущего объекта массива обязательна — `Edit|Write` объект должен оканчиваться `},`.
|
||||
|
||||
- [ ] **Step 6.3: Validate JSON**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8')); console.log('OK')"
|
||||
```
|
||||
|
||||
Expected: `OK`. Если ошибка — STOP, ловить trailing comma / unbalanced brace.
|
||||
|
||||
- [ ] **Step 6.4: Smoke test end-to-end**
|
||||
|
||||
Перезапустить Claude Code (хук перечитывается на старте сессии). В новой сессии запустить тривиальный Task — субагент должен в ответе содержать `=== SUBAGENT GIT-SAFETY HEADER ===` в начале промпта (можно проверить, попросив субагента выписать первые 10 строк своего промпта).
|
||||
|
||||
Если перезапуск Claude Code невозможен в текущем рабочем потоке — отметить шаг как «verified at next session start» в коммит-сообщении.
|
||||
|
||||
- [ ] **Step 6.5: Commit**
|
||||
|
||||
```bash
|
||||
git add .claude/settings.json
|
||||
git commit -m "chore(hooks): register subagent-prompt-prefix PreToolUse Task hook
|
||||
|
||||
Регистрирует tools/subagent-prompt-prefix.mjs как PreToolUse-хук
|
||||
matcher:'Task'. JSON валиден (node -e JSON.parse). End-to-end smoke
|
||||
verified at next session start (хук перечитывается на старте сессии).
|
||||
|
||||
Per Pravila §15.1 (третье hard-rule).
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Wrapper-скил subagent-driven-development
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `.claude/skills/subagent-driven-development/SKILL.md`
|
||||
- Create: `.claude/skills/subagent-driven-development/references/git-safety-checklist.md`
|
||||
|
||||
- [ ] **Step 7.1: Create SKILL.md (wrapper)**
|
||||
|
||||
Полное содержимое:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: Project-local wrapper для superpowers:subagent-driven-development — добавляет обязательный git-safety verify-протокол per Pravila §15.1. Использовать вместо marketplace-варианта при работе с git-коммит-задачами в субагентах.
|
||||
---
|
||||
|
||||
# Subagent-Driven Development (project wrapper)
|
||||
|
||||
Этот скил — проектная обёртка над marketplace-скилом `superpowers:subagent-driven-development`. Дополняет его обязательным git-safety verify-протоколом per Pravila §15.1.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
Когда нужно делегировать задачу субагенту через Task tool — особенно git-коммит-задачи (Sprint 6 прецедент: Haiku-субагенты угнали ветку параллельной сессии).
|
||||
|
||||
## Что делать
|
||||
|
||||
1. **Откройте marketplace-скил** `superpowers:subagent-driven-development` для общего workflow (fresh subagent per task + two-stage review).
|
||||
2. **Перед каждой Task-инвокацией** прочитайте и выполните pre-spawn-чеклист — [references/git-safety-checklist.md](references/git-safety-checklist.md) §A.
|
||||
3. **После каждой Task-инвокации** прочитайте и выполните post-subagent-чеклист — там же §B.
|
||||
4. **Hard-rule §15.1** — git-коммит-задача = модель Sonnet/Opus, никогда Haiku. Read-only git-операции (`log`, `status`, `diff`, `rev-parse`, `branch --show-current`, `worktree list`) разрешены любой модели.
|
||||
|
||||
Хук `tools/subagent-prompt-prefix.mjs` (зарегистрирован в `.claude/settings.json`) автоматически инжектит git-safety заголовок в каждый Task-prompt — это **первая** линия защиты. Чеклист из этого скила — **вторая** линия (защита со стороны контроллера).
|
||||
|
||||
## Cross-refs
|
||||
|
||||
- Pravila §15.1 — hard-rule субагенты + git.
|
||||
- Spec: `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md` §5.
|
||||
- Memory: `memory/feedback_subagent_git_reliability.md`.
|
||||
```
|
||||
|
||||
- [ ] **Step 7.2: Create references/git-safety-checklist.md**
|
||||
|
||||
Полное содержимое:
|
||||
|
||||
```markdown
|
||||
# Git-safety Checklist для контроллера субагентов
|
||||
|
||||
Per Pravila §15.1 — выполнять каждый раз при делегировании задачи через Task tool.
|
||||
|
||||
## §A. Pre-spawn чеклист (до Task-инвокации)
|
||||
|
||||
1. **Резолвите 4 значения** (запишите у себя для post-check):
|
||||
```bash
|
||||
git branch --show-current # → ожидаемая ветка
|
||||
git rev-parse HEAD # → pre-spawn parent SHA
|
||||
git rev-parse --show-toplevel # → worktree root
|
||||
pwd # → cwd
|
||||
```
|
||||
|
||||
1. **Выберите модель** субагенту:
|
||||
- Задача требует `git commit`/`push`/`stage`/`checkout`/`switch`/`merge`/`rebase`? → **Sonnet или Opus**, никогда Haiku (§15.1).
|
||||
- Только read-только `git log`/`status`/`diff`/`rev-parse` ИЛИ только Edit/Read/Grep? → любая модель.
|
||||
2. **Если задача правит нормативку из списка §15.2** (Pravila / CLAUDE.md / Tooling / PSR_v1 / MEMORY.md / Открытые_вопросы / docs/adr/* / db/schema.sql):
|
||||
|
||||
```bash
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
```
|
||||
|
||||
Не пусто → **ребейз/merge до инвокации**, не после. Pre-flight также проверить `docs/sessions/CURRENT.md` на конфликт scope-files / version-claims.
|
||||
|
||||
## §B. Post-subagent чеклист (сразу после возврата субагента)
|
||||
|
||||
1. **`git rev-parse HEAD`** — сравнить с pre-spawn parent SHA.
|
||||
- Равно → субагент не коммитил (OK для Edit-задач без commit).
|
||||
- Отличается ровно одним коммитом, чей parent = pre-spawn HEAD → OK для commit-задач.
|
||||
- **Иначе → STOP, разбор инцидента.**
|
||||
2. **`git branch --show-current`** — сравнить с pre-spawn branch.
|
||||
- Не равно → **STOP, разбор инцидента** (Sprint 6 паттерн).
|
||||
3. **`git log -1 --format='%s%n%P'`** — проверить subject + parent последнего коммита.
|
||||
- Subject соответствует задаче?
|
||||
- Parent = pre-spawn HEAD?
|
||||
4. Если несколько коммитов — ручная проверка subject'ов каждого.
|
||||
|
||||
## §C. Red-flag-список — любой = hard-stop разбор
|
||||
|
||||
- `branch ≠ ожидаемая`;
|
||||
- `parent коммита ≠ pre-spawn HEAD` (висячий коммит / попадание на чужую ветку);
|
||||
- HEAD двинулся, но субагент в отчёте об этом не упомянул;
|
||||
- в diff'е есть файлы вне scope задачи.
|
||||
|
||||
## §D. Обязательный формат отчёта субагента
|
||||
|
||||
Субагент в конце ответа выписывает блок:
|
||||
|
||||
```
|
||||
=== GIT REPORT ===
|
||||
cwd: <pwd>
|
||||
branch: <git branch --show-current>
|
||||
HEAD: <git rev-parse HEAD>
|
||||
HEAD^: <git rev-parse HEAD^>
|
||||
status: <git status --short>
|
||||
=== END GIT REPORT ===
|
||||
```
|
||||
|
||||
Отсутствие блока = контроллер считает результат недостоверным и запускает §B-чеклист сам через Bash.
|
||||
|
||||
## §E. Соотношение с code-review
|
||||
|
||||
Двухстадийное review (Pravila §4.5 / PSR_v1 R10) сохраняется. Git-safety-чеклист **не заменяет** code-review — он стоит **до** него (нет смысла ревьюить diff, если он не в той ветке).
|
||||
|
||||
```
|
||||
|
||||
- [ ] **Step 7.3: Verify скил**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
ls -la .claude/skills/subagent-driven-development/
|
||||
ls -la .claude/skills/subagent-driven-development/references/
|
||||
```
|
||||
|
||||
Expected: SKILL.md + references/git-safety-checklist.md существуют.
|
||||
|
||||
- [ ] **Step 7.4: Commit**
|
||||
|
||||
```bash
|
||||
git add .claude/skills/subagent-driven-development/
|
||||
git commit -m "feat(skills): subagent-driven-development project wrapper + git-safety-checklist
|
||||
|
||||
Project-local обёртка над marketplace-скилом superpowers:subagent-driven-development.
|
||||
Добавляет обязательный pre/post-subagent git-safety verify-протокол
|
||||
per Pravila §15.1 (Sprint 6 прецедент-источник: Haiku-субагенты
|
||||
угнали ветку параллельной сессии).
|
||||
|
||||
Состав:
|
||||
- SKILL.md — точка входа, ссылка на marketplace + §A/§B/§C из checklist.
|
||||
- references/git-safety-checklist.md — pre-spawn / post-subagent / red-flags / GIT REPORT format / code-review boundary.
|
||||
|
||||
Хук tools/subagent-prompt-prefix.mjs — первая линия защиты (auto-inject),
|
||||
этот checklist — вторая линия (контроллер verify).
|
||||
|
||||
Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md §5.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Final regression + push
|
||||
|
||||
**Files:** none (verification + push only)
|
||||
|
||||
- [ ] **Step 8.1: Update CURRENT.md status — release**
|
||||
|
||||
Прочитать `docs/sessions/CURRENT.md`, изменить запись текущей сессии:
|
||||
|
||||
- `status: in-progress` → `status: closed-<последний commit SHA из git log -1>`
|
||||
|
||||
Это **append-only** правка в смысле жизненного цикла — запись остаётся, только меняется статус.
|
||||
|
||||
- [ ] **Step 8.2: Commit status change**
|
||||
|
||||
```bash
|
||||
git add docs/sessions/CURRENT.md
|
||||
git commit -m "chore(sessions): release parallel-sessions-coordination session
|
||||
|
||||
status: in-progress → closed-<sha>
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
- [ ] **Step 8.3: Verify everything is staged correctly**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git log --oneline origin/main..HEAD
|
||||
```
|
||||
|
||||
Expected: working tree clean (кроме dirty файлов вне нашего scope: `.gitignore`, `app/dev-indices.json`, `_demo_*` — не трогаем); `git log` показывает 8 atomic commits (по одному на task'у, + spec-commit `235b1d4` из brainstorming).
|
||||
|
||||
- [ ] **Step 8.4: Pre-push full regression**
|
||||
|
||||
Run параллельно (в одном tool-сообщении):
|
||||
|
||||
```bash
|
||||
./bin/gitleaks.exe detect --source . --redact -v
|
||||
```
|
||||
|
||||
Expected: 0 leaks (full history scan).
|
||||
|
||||
```bash
|
||||
./bin/lychee.exe --no-progress 'docs/**/*.md' '*.md'
|
||||
```
|
||||
|
||||
Expected: 0 broken links.
|
||||
|
||||
(Pest --parallel / Vitest — пропускаем: scope не трогает PHP/JS-код приложения, только tools/+docs/+.claude/. Если settings.json правка влияет на запуск сессии — это не testable в этом репо.)
|
||||
|
||||
- [ ] **Step 8.5: Push to origin (только после явного «делай push» от заказчика)**
|
||||
|
||||
```bash
|
||||
git push origin feat/parallel-sessions-coordination:feat/parallel-sessions-coordination
|
||||
```
|
||||
|
||||
Затем — либо PR через GitHub MCP, либо прямой FF-merge на main по решению заказчика. PR-вариант предпочтителен из-за объёма (8 atomic commits + новая нормативка §15).
|
||||
|
||||
- [ ] **Step 8.6: Update memory `MEMORY.md`**
|
||||
|
||||
Через `/claude-md-management:revise-claude-md` (capture session-learnings) ИЛИ ручной Edit `memory/MEMORY.md` + создание `memory/project_parallel_sessions.md`. Важные факты:
|
||||
|
||||
- Pravila §15 — третье hard-rule (после §12, §14).
|
||||
- `docs/sessions/CURRENT.md` — claim/check/release координация.
|
||||
- Хук `tools/subagent-prompt-prefix.mjs` — PreToolUse Task auto-inject.
|
||||
- Wrapper-скил `.claude/skills/subagent-driven-development/`.
|
||||
- Прецедент Sprint 6 → исторический корень §15.1.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**1. Spec coverage** — каждая секция spec'а покрыта:
|
||||
|
||||
- spec §0 Контекст — упомянут в Goal плана.
|
||||
- spec §1 Архитектура — 4 артефакта → tasks 1, 2, 3+4+6, 7.
|
||||
- spec §2 Pravila §15 — Task 1 целиком (15.1/15.2/15.3 + список 8).
|
||||
- spec §3 CURRENT.md — Task 2 (формат + lifecycle + retro-claim).
|
||||
- spec §4 Хук — Tasks 3 (TDD red) + 4 (green) + 6 (register).
|
||||
- spec §5 Verify-протокол — Task 7 (wrapper-skill + references).
|
||||
- spec §6 Тесты+migration — Tasks 3+4 (хук-тесты), Task 2 (retro-claim migration), Task 8 (final regression).
|
||||
- spec §7 Ограничения — учтены в pre-flight (§15 свободен verified) и в Task 7 (references-wrapper вместо vendor-патча — confirmed `.claude/skills/subagent-driven-development/` отсутствует).
|
||||
- spec §8 Acceptance — все 7 пунктов адресованы tasks.
|
||||
|
||||
**2. Placeholder scan** — все шаги содержат конкретный код / точную команду / ожидаемый вывод. Никаких «TBD / implement later / add validation».
|
||||
|
||||
**3. Type consistency** — формат хука (JSON output структура) consistent между Task 3 (тесты) и Task 4 (имплементация): `hookSpecificOutput.updatedInput.prompt`, `hookEventName: 'PreToolUse'`, `permissionDecision: 'allow'`. GIT REPORT формат (`cwd / branch / HEAD / HEAD^ / status`) consistent между Task 4 (header instructs subagent) и Task 7 (checklist §D).
|
||||
|
||||
**4. Гарантии TDD** — Task 3 явно требует RED-фазу (тесты падают), Task 4 — GREEN. Атомарные коммиты RED-then-GREEN сохраняют TDD-историю.
|
||||
|
||||
---
|
||||
|
||||
## Risks / Out-of-scope
|
||||
|
||||
- **Smoke-test перезапуска сессии** (Task 6 Step 6.4) — может не сработать в текущем рабочем потоке (если плановщик хочет провести все таски в одной сессии). Mitigation: «verified at next session start» отметка в commit'е.
|
||||
- **Retro-claim accuracy** (Task 2 Step 2.3) — `scope-files` для existing worktrees заполнены best-effort из `git log -1 --name-only`. Точность ограничена; активные сессии при возобновлении обновят свой блок. Spec §6.2 явно фиксирует «§15 действует с момента введения, не ретроактивно».
|
||||
- **CLAUDE.md правки через плагин** (Task 5) — `/claude-md-management:claude-md-improver` может предложить другие версии bump'а или другую формулировку footer-абзаца — это нормально, плагин — owner CLAUDE.md (§5 п.10).
|
||||
- **Out-of-scope** (явный YAGNI из spec §6.3): реестр зарезервированных версий, pre-commit hook на CURRENT.md, JSON-формат CURRENT.md, запрет параллельных сессий, изменения PSR_v1/Tooling, subagent-без-git (вариант C).
|
||||
@@ -0,0 +1,171 @@
|
||||
# Anthropic Dev-Tooling Formalization — Design
|
||||
|
||||
**Date:** 2026-05-18
|
||||
**Topic:** Формализация 5 Anthropic-плагинов уже включённых в `~/.claude/settings.json` user-level, но без номера в реестре Tooling §3.3 / PSR_v1 R10.1.
|
||||
**Deciders:** Дмитрий
|
||||
**Method:** аудит «мозга» через discovery-interview (SYSTEM-режим, 2026-05-18). Решение по варианту (а) — формализовать все 5, риски закрыть предварительно.
|
||||
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Закрыть **L1-паттерн** «плагин фактически включён в settings.json без формализации в правилах» (зафиксирован 2026-05-10 на UPM/21st; повторился 2026-05-13 на Sentry/Redis MCP). За неделю интеграционных эпиков (A6/D3/C9/A11/A3/A4/deptrac/C10/discovery) реестр Tooling вырос с 35 до 55 позиций, но **5 Anthropic dev-плагинов** оставались формализационным долгом — они есть в карте (iter7 audit 16.05.2026), но не в Tooling/PSR/Pravila.
|
||||
|
||||
Превратить долг в полноценные позиции #56–#60 с двумя новыми off-phase подкатегориями, по проверенному паттерну C10/A11/A3.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
**5 плагинов в `~/.claude/settings.json` `enabledPlugins` без номера:**
|
||||
|
||||
1. `skill-creator@claude-plugins-official` (Anthropic) — создание скилов, performance-метрики, оптимизация описаний для триггеринга
|
||||
2. `plugin-dev@claude-plugins-official` (Anthropic) — конструктор плагинов: 8 sub-skills (plugin-structure / agent-development / skill-development / command-development / hook-development / mcp-integration / plugin-settings) + 2 агента (agent-creator, plugin-validator, skill-reviewer)
|
||||
3. `hookify@claude-plugins-official` (Anthropic) — генератор хуков из анализа транскриптов или явных инструкций (`/hookify` + skill `writing-rules` + агент `conversation-analyzer`)
|
||||
4. `claude-code-setup@claude-plugins-official` (Anthropic) — анализатор кодовой базы + рекомендации Claude Code automations (`/claude-automation-recommender`)
|
||||
5. `context7@claude-plugins-official` (Anthropic) — MCP-документация для библиотек/фреймворков (актуальные доки React/Laravel/Vue/Prisma/Tailwind/…)
|
||||
|
||||
**Карта (`docs/automation-graph.html`)** иметь 5 соответствующих узлов: `skill_creator`, `plugin_dev`, `hookify_plugin`, `claude_setup`, `context7` — добавлены в iter7 audit-actualization 16.05.2026. Узлы **есть**, но nd()-блоки не несут номера/правил, и edge к `psr_v1` «R10.1 блок 1» — отсутствуют. Один из узлов (`hookify_plugin`) уже носит 🔴-конфликт `hookify_plugin ↔ hk_pre_claude` (карта строка 1844).
|
||||
|
||||
**Project-level `.mcp.json`** — все 9 MCP формализованы (#2/#3/#10/#25/#34/#35/#45/#47 + ruflo §4.10). User-level `.claude.json` `mcpServers` — только `magic` (#32). Project `.claude/settings.json` hooks — описаны в Pravila §14 / Tooling §14. Утечек инвентаря вне 5 пунктов выше **нет**.
|
||||
|
||||
**Прецеденты формализации post-факт:**
|
||||
- 2026-05-10 (UPM #31 + 21st Magic MCP #32) — после явного вопроса заказчика «хочу добавить плагины»
|
||||
- 2026-05-13 (Sentry MCP #34 + Redis MCP #35) — retrospective в v1.92 после PR #3 merge
|
||||
- 2026-05-17/18 (A6/D3/C9/A11/A3/A4/deptrac/C10/discovery) — проактивная сектор-за-сектором формализация
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: Две off-phase подкатегории, не одна
|
||||
|
||||
Семантика разная — нельзя свалить в одну категорию:
|
||||
|
||||
- **authoring-tooling** (создание Claude-артефактов): `skill-creator` #56, `plugin-dev` #57, `hookify` #58
|
||||
- **dev-support** (поддержка/документация Claude-разработки): `claude-code-setup` #59, `context7` #60
|
||||
|
||||
Это даёт более чистые правила в R10.1 и более точные триггеры в Pravila §13.2.
|
||||
|
||||
### D2: hookify — отдельное hard-правило в R10.1 (закрывает 🔴-конфликт)
|
||||
|
||||
Текущее состояние: 🔴-конфликт `hookify_plugin ↔ hk_pre_claude` на карте (плагин hookify может перезаписать существующие хуки в `~/.claude/settings.json` без diff).
|
||||
|
||||
Правило закрытия:
|
||||
|
||||
> hookify вызывается **только по явному `/hookify`**, не проактивно. Перед генерацией хука — обязательный pre-check на коллизию с уже-зарегистрированными хуками в `~/.claude/settings.json` (особенно: economy-mode / skill-marker / skill-check / state-guard / postcompact / verifier — это 6-компонентная архитектура runtime-enforcement, никакие из них не должны перезаписываться). При обнаружении коллизии — остановка с пометкой «hookify не может выполнить генерацию автоматически — требуется ручное согласование изменений в settings.json».
|
||||
|
||||
После правила: 🔴 → 🟢 (закрыто правилом).
|
||||
|
||||
### D3: skill-creator ↔ plugin-dev:skill-development — граница
|
||||
|
||||
Оба умеют создавать скилы. Граница:
|
||||
|
||||
- **skill-creator** — для **standalone** скилов (`.claude/skills/<name>/`), c performance-метриками и benchmarking. Использовать первым при создании нового **проектного** скила.
|
||||
- **plugin-dev:skill-development** — для скилов **внутри marketplace-плагина**, который ты разрабатываешь. Использовать только при работе над собственным Claude-плагином (не наш кейс на 2026-05-18).
|
||||
|
||||
Дополнительно: **вендоренные сторонние скилы** (`.claude/skills/mermaid/`, `data-scientist/`, `ccpm/`) и **self-authored проектные** (`audit-portal/`, `regression/`, `process-modeling/`, `process-analysis/`, `discovery-interview/`) — модифицируются **прямым Edit**, не через skill-creator (он может предложить переписать как новый, потерять провенанс).
|
||||
|
||||
### D4: context7 ↔ WebFetch ↔ WebSearch — граница источников документации
|
||||
|
||||
Текущая практика: я обращался к context7 на A11/A3/discovery эпиках для актуальных доков (Laravel/Pest/Vue), но это нигде не документировано.
|
||||
|
||||
Правило в R10.1 dev-support:
|
||||
|
||||
- **context7** — первый выбор для документации **известной библиотеки** (Laravel, Vue, React, Pest, Vuetify, Tailwind, …). MCP отдаёт актуальную версию из upstream, обходит cutoff training data.
|
||||
- **WebFetch** — fallback на конкретный URL (GitHub README, ADR-документ внешнего проекта).
|
||||
- **WebSearch** — поиск без знания URL, либо актуальные события/статьи.
|
||||
|
||||
### D5: claude-code-setup — read-only анализатор
|
||||
|
||||
`/claude-automation-recommender` — анализирует кодовую базу и предлагает плагины/хуки/скилы. Правило:
|
||||
|
||||
- Рекомендации **фильтровать** через R0 stack-gate + R10.1 (R0.6 hard-стопы — брендовое UI, ru-стек, уже формализованное и т.п.).
|
||||
- **Не устанавливать** ничего по рекомендации без явного согласования с заказчиком.
|
||||
- Использование read-only/advisory — не trigger'ит R6.0/R6.1/R14.
|
||||
|
||||
### D6: ADR-010 — новый ADR-документ
|
||||
|
||||
По образцу ADR-004 (C9 project-management) / ADR-005 (deptrac) / ADR-006 (A4 design) / ADR-007 (A11 ml-ai) / ADR-008 (C10 business-process) / ADR-009 (discovery-interview). Содержание: формализация retrospective, split на 2 подкатегории, locked границы D2-D5.
|
||||
|
||||
Альтернатива (retrospective без ADR, как Sentry/Redis #34/#35 в v1.92) — отвергается: тут 5 позиций и 2 новые подкатегории, decision-grain выше — ADR обязателен.
|
||||
|
||||
### D7: Карта — refresh, не add
|
||||
|
||||
Узлы skill_creator / plugin_dev / hookify_plugin / claude_setup / context7 в карте **есть** (iter7 16.05). Нужно:
|
||||
|
||||
- Обновить лейблы 4 узлов-правил (Pravila/CLAUDE.md/PSR_v1/Tooling) на новые версии **v1.27 / v2.14 / v3.13 / v2.14** (после A6 v1.24/v2.10/v3.10/v2.10 дрейф копится — последний refresh `de66b8b` 17.05; за C10 и discovery + сейчас за this эпик)
|
||||
- Каждому из 5 узлов — обновить nd() с номером (#56-#60), категорией, ограничениями, edge к `psr_v1` «R10.1 блок 1»
|
||||
- Конфликт `hookify_plugin ↔ hk_pre_claude` — 🔴 → 🟢 с rule «D2 правило в R10.1»
|
||||
- NODE_META.changed → 18.05.2026 для всех 5
|
||||
- tooling-узел nd() count: «70 / 50» → «75 / 55» (после регистрации 5 позиций) — но это уже стало неактуально (последний refresh говорит 70/50, после C10 и discovery — реально 75/55 уже). Verify Task 7.
|
||||
- `NODE_SECTION` — узлы остаются в текущих разделах (E7), не перетегируются (REU4 паттерн)
|
||||
- Метрики карты — 124/130 (узлы и рёбра без изменений в количестве; только nd-наполнение + 5 новых edge к psr_v1 = 124/135)
|
||||
|
||||
### D8: Memory — single-bump
|
||||
|
||||
После эпика — update `feedback_plugin_paired_stack.md` (active versions + 6-я off-phase подкатегория — wait, после A11 их уже 10, после C10 11, после discovery 12, после нас 13). MEMORY.md и project_state.md — стандартные version bumps.
|
||||
|
||||
---
|
||||
|
||||
## Conflict audit — locked
|
||||
|
||||
Полный аудит R1–R14 проведён в discovery-сессии 2026-05-18. Сводка:
|
||||
|
||||
| # | Риск | Severity | Locked resolution |
|
||||
|---|---|---|---|
|
||||
| R1 | hookify может перезаписать settings.json (🔴) | 🟡 → 🟢 после правила | D2 — отдельное правило pre-check в R10.1 |
|
||||
| R2 | plugin-dev может предложить переделать наши self-authored скилы | 🟡 | D3 — граница «standalone vs marketplace; вендоренное/self-authored — direct Edit» |
|
||||
| R3 | skill-creator ↔ plugin-dev:skill-development overlap | 🟢 | D3 — граница |
|
||||
| R4 | context7 ↔ WebFetch ↔ WebSearch overlap | 🟢 | D4 — приоритет |
|
||||
| R5 | claude-code-setup может предложить установить плагин | 🟢 | D5 — read-only фильтр |
|
||||
| R6 | Карта: 5 узлов есть, без номеров и edge | 🟢 | D7 — refresh + 5 новых edge |
|
||||
| R7 | Категоризация в одну подкатегорию запутает | 🟢 | D1 — две подкатегории |
|
||||
| R8 | User-level настройки на 16 параллельных проектах машины | 🟢 | Формализация в Лидерра-нормативке не ломает другие проекты |
|
||||
| R9 | Кодовая регрессия | 🟢 | Её нет — только текстовая нормативка; pre-commit + pre-push стандарт |
|
||||
| R10 | Темп: 5 позиций в один эпик | 🟢 | Норм — посильно по образцу A11 (3) / C10 (4) |
|
||||
| R11 | ADR нужен? | 🟢 | D6 — да, ADR-010 |
|
||||
| R12 | Memory upd | 🟢 | D8 — стандартный bump |
|
||||
| R13 | Версии нормативки | 🟢 | Tooling v2.13→v2.14 / PSR v3.12→v3.13 / Pravila v1.26→v1.27 / CLAUDE.md v2.13→v2.14 |
|
||||
| R14 | Конфликт-аудит пометки в Tooling §3.3 | 🟢 | По образцу AK1/MK1/ML3/LINT1 — короткие SC1-SC5 / PD1-PD3 / HK1-HK3 / CCS1 / CTX1 |
|
||||
|
||||
---
|
||||
|
||||
## File structure
|
||||
|
||||
| File | Action | Responsibility |
|
||||
|---|---|---|
|
||||
| `docs/adr/ADR-010-anthropic-dev-tooling.md` | Create | Формализация retrospective decision, split 2 подкатегории, locked границы D2-D5 |
|
||||
| `docs/Tooling_v8_3.md` | Modify | Прил. Н — 2 новых subsection (§4.31 authoring-tooling, §4.32 dev-support); §4.31-§4.35 5 позиций (#56-#60); §0 счётчик 55→60 |
|
||||
| `docs/Plugin_stack_rules_v1.md` | Modify | R10.1 Блок 1 — +5 строк с ролями и triggers; hookify-special note (D2); §0 +entry v3.13 |
|
||||
| `docs/Pravila_raboty_Claude_v1_1.md` | Modify | §13.2 — +2 абзаца (authoring-tooling + dev-support); §0 +entry v1.27 |
|
||||
| `CLAUDE.md` | Modify (через `/claude-md-management:claude-md-improver` ИЛИ прямой Edit в worktree — §5 п.10 worktree-эксцепшн, прецедент A11/C10/discovery v2.10/v2.12/v2.13) | §3 title 55→60; §1 priority chain row 2b 55→60; §3.3 +5 строк #56-#60; §3.3 footer 55→60 + 13 off-phase подкатегорий; §0 cross-refs Pravila v1.27 / PSR v3.13 / Tooling v2.14; §6 +абзац интеграции; §9 +entry v2.14; шапка v2.13 → v2.14 |
|
||||
| `docs/CHANGELOG_claude_md.md` | Modify | Entry v2.14 |
|
||||
| `docs/automation-graph.html` | Modify | 5 узлов (skill_creator/plugin_dev/hookify_plugin/claude_setup/context7) — refresh nd() с номерами + edge к `psr_v1`; 4 узла-правила — refresh лейблы под новые версии; конфликт hookify ⊥ hk_pre_claude 🔴→🟢; tooling-узел nd() count refresh |
|
||||
| `MEMORY.md` + `feedback_plugin_paired_stack.md` + `project_state.md` + `reference_archive.md` | Modify | Standard bumps + new memory `project_anthropic_dev_tooling.md` для этой интеграции |
|
||||
|
||||
**Files NOT modified:**
|
||||
- `~/.claude/settings.json` — настройки не трогаем (плагины уже включены)
|
||||
- `~/.claude.json` — то же
|
||||
- `.mcp.json` — не затронут (только context7 — но он `enabledPlugins`, не MCP-сервер в .mcp.json)
|
||||
- `lefthook.yml` — нет хуков от этих плагинов в pre-commit/pre-push
|
||||
- Test files — кодовой регрессии нет
|
||||
|
||||
---
|
||||
|
||||
## Severable scope
|
||||
|
||||
**Core scope (Task 1–9):** ADR-010 + 4 normative files + map refresh + memory + pre-push + push. Закрывает эпик целиком.
|
||||
|
||||
**Out of scope (defer):**
|
||||
- Изменение `enabledPlugins` (выключение/включение) — это вариант (б)/(в), отвергнут заказчиком в пользу (а)
|
||||
- Изменение хуков hookify в `.claude/settings.json` — формализуем правило, не код
|
||||
- Создание `docs/<category>/README.md` (как сделано в A11 `docs/ml/`, C10 `docs/process/`, discovery `docs/discovery/`) — для authoring-tooling и dev-support **не нужно**: это infrastructure-категория, не имеет проектных артефактов (как и claude-md-management #33 не имеет `docs/claude-md/`). Pravila §13.2 абзаца + Tooling subsection достаточно.
|
||||
|
||||
---
|
||||
|
||||
## Sequencing
|
||||
|
||||
Worktree уже создан: `.claude/worktrees/anthropic-dev-tooling`, branch `feat/anthropic-dev-tooling`, базовый коммит origin/main `b40f2c8` (последний — discovery-interview map node).
|
||||
|
||||
Все 9 tasks плана исполняются в этой ветке последовательно (механика суб-агентов разрешена, но git-задачи — контроллер Sonnet, никакого Haiku-commit, урок Sprint 3F/5/6). Push: `git push origin feat/anthropic-dev-tooling:main` после pre-push (gitleaks-full-history + lychee).
|
||||
@@ -0,0 +1,275 @@
|
||||
# Параллельные сессии: координация — дизайн
|
||||
|
||||
**Дата:** 2026-05-18
|
||||
**Автор:** Claude (Opus 4.7, brainstorming с Дмитрием, экономия 5%)
|
||||
**Статус:** черновик → ревью заказчика → writing-plans
|
||||
**Связано:** Pravila §12 / §14 (hard rules), memory `feedback_subagent_git_reliability.md`, Sprint 6 инцидент.
|
||||
|
||||
---
|
||||
|
||||
## 0. Контекст и проблема
|
||||
|
||||
При параллельной работе нескольких Claude-сессий на одном репозитории — что является ежедневной нормой проекта (на 18.05.2026 в `git worktree list` 16 активных worktrees) — наблюдаются два класса инцидентов:
|
||||
|
||||
**Класс A — субагенты теряются между worktree.**
|
||||
Запущенный из контроллера субагент (особенно Haiku) путает рабочую директорию или ветку: коммитит в чужую ветку, делает orphan-коммит, не возвращает git-state в отчёте. Прецедент — Sprint 6: Haiku-субагенты угнали ветку параллельной сессии, инцидент устранён через `git reflog` + `reset`. Корневая причина — контроллер не верифицирует HEAD/branch после Task-инвокации.
|
||||
|
||||
**Класс B — нормативка/MEMORY дрейфует.**
|
||||
Параллельные сессии правят один и тот же набор файлов (Pravila / CLAUDE.md / Tooling / PSR_v1 / MEMORY.md / `Открытые_вопросы_*.md`) и претендуют на один version-номер. Прецедент — 17.05.2026: ADR-006 D4 и C10 одновременно претендовали на Tooling v2.11, C10 пришлось переномеровать в v2.12 (видно в шапке CLAUDE.md). За неделю 18.05.2026 разделы A11/A3/A4/A6/C9/C10/discovery-interview — все 7 — трогали один набор из 4 нормативных файлов.
|
||||
|
||||
Обе проблемы — следствие одного: **параллельность без явного контракта на scope**.
|
||||
|
||||
## 1. Архитектура
|
||||
|
||||
Решение из 4 артефактов, без новых плагинов / MCP-серверов:
|
||||
|
||||
1. **Pravila §15** (новое hard-rule) — два пункта: §15.1 (субагенты + git), §15.2 (нормативка + pre-flight sync). Hard-rule = §9 «Отступления» не применяется (как §12 и §14).
|
||||
2. **`docs/sessions/CURRENT.md`** — заявочный лог активных параллельных сессий.
|
||||
3. **`.claude/hooks/subagent-prompt-prefix.mjs`** — PreToolUse-хук, инжектящий в каждый `Task`-prompt заголовок git-safety.
|
||||
4. **Verify-протокол** в скиле `superpowers:subagent-driven-development` — pre-spawn + post-subagent чеклист контроллера.
|
||||
|
||||
Зависимости: артефакт 1 (Pravila §15) — корень всех правил; артефакты 2–4 ссылаются на §15.1 / §15.2 как enforcement floor.
|
||||
|
||||
## 2. Pravila §15 — текст обоих пунктов
|
||||
|
||||
### §15.1 Субагенты + git
|
||||
|
||||
> Git-коммит-задачи субагенту (любой `Task`-инвокейшн, чей prompt содержит `git commit`, `git push`, `git stage`, `git checkout`, `git switch`, `git merge`, `git rebase`, либо где явно ожидается коммит в результате) — **только модель Sonnet или Opus**, никогда Haiku. Контроллер, делегирующий git-операцию Haiku-субагенту — нарушение §15.1, фиксируется в feedback того же уровня, что §12.
|
||||
>
|
||||
> Исключение — read-only git-операции (`git log`, `git status`, `git diff`, `git rev-parse`, `git branch --show-current`, `git worktree list`) — разрешены любой модели.
|
||||
|
||||
### §15.2 Нормативные правки + pre-flight sync
|
||||
|
||||
> Любая правка файлов из списка «нормативка» (см. ниже) выполняется **только** на актуальной базе `origin/main`. Pre-flight обязателен: `git fetch origin && git log HEAD..origin/main --oneline` — если есть untracked commits на origin/main, ребейз/merge **до начала правки**, не после.
|
||||
>
|
||||
> Параллельная нормативная правка на устаревшей базе — нарушение §15.2. Признак нарушения: коммит правит файл, чья последняя версия на `origin/main` новее, чем версия в parent коммите правки.
|
||||
>
|
||||
> **Список «нормативка» — 8 позиций:**
|
||||
>
|
||||
> 1. `docs/Pravila_raboty_Claude_v1_1.md`
|
||||
> 2. `CLAUDE.md`
|
||||
> 3. `docs/Tooling_v8_3.md`
|
||||
> 4. `docs/Plugin_stack_rules_v1.md`
|
||||
> 5. `memory/MEMORY.md` (и все `memory/*.md`)
|
||||
> 6. `docs/Открытые_вопросы_v8_3.md`
|
||||
> 7. `docs/adr/*.md` (glob — collision на ADR-NNN номере = тот же класс, что version-bump нормативки)
|
||||
> 8. `db/schema.sql` (параллельные миграции из разных сессий = реальный риск; запись в `db/CHANGELOG_schema.md` сама не защищает от version-base дрейфа)
|
||||
>
|
||||
> Расширение списка — отдельная правка §15.2, не «по ощущениям».
|
||||
|
||||
### §15.3 Cross-refs в других файлах
|
||||
|
||||
- **CLAUDE.md §1 priority chain** — упомянуть §15 рядом с §12 и §14 как hard-rules (footer-абзац после цепочки).
|
||||
- **PSR_v1** — не правится (§15 не про координацию плагинов, а про координацию сессий).
|
||||
- **Tooling** — не правится.
|
||||
|
||||
## 3. `docs/sessions/CURRENT.md` — заявочный лог
|
||||
|
||||
### 3.1 Формат
|
||||
|
||||
Один markdown-файл, append-only, парсимый. Запись на каждую активную параллельную сессию:
|
||||
|
||||
```markdown
|
||||
## session: 2026-05-18-discovery-interview
|
||||
- branch: worktree-discovery-interview
|
||||
- worktree: c:/моя/проекты/портал crm/Документация-discovery
|
||||
- started: 2026-05-18T14:30+03:00
|
||||
- scope-files:
|
||||
- docs/Tooling_v8_3.md §4.30
|
||||
- docs/Pravila_raboty_Claude_v1_1.md §13.2
|
||||
- docs/Plugin_stack_rules_v1.md R10.1
|
||||
- CLAUDE.md §3.3 #55
|
||||
- docs/adr/009-*.md (new)
|
||||
- version-claims:
|
||||
- Tooling: 2.12 → 2.13
|
||||
- Pravila: 1.25 → 1.26
|
||||
- PSR_v1: 3.11 → 3.12
|
||||
- CLAUDE.md: 2.12 → 2.13
|
||||
- status: in-progress
|
||||
- closes: docs/superpowers/plans/2026-05-18-discovery-interview-integration.md
|
||||
```
|
||||
|
||||
### 3.2 Жизненный цикл записи
|
||||
|
||||
- **claim** — на старте сессии (до первой нормативной правки) контроллер добавляет запись + атомарный коммит `sessions: claim <topic>`. Отдельный коммит от plan-документа.
|
||||
- **check** — pre-flight перед своей правкой: `Read docs/sessions/CURRENT.md` + scan записей со `status: in-progress`. Конфликт = пересечение `scope-files` ИЛИ `version-claims` с активной соседней сессией.
|
||||
- **release** — на закрытии (push на main) контроллер меняет `status: closed-<commit-sha>`. Append-only-вариант (closed-записи остаются). Closed-записи переезжают в `docs/sessions/archive/YYYY-MM.md` через ≥30 дней после закрытия (ручная архивация раз в месяц, не cron).
|
||||
|
||||
### 3.3 Конфликт-резолюция
|
||||
|
||||
1. **Файловое пересечение** (две сессии правят один и тот же файл, не обязательно одну секцию) — **soft-warn**, продолжать можно, но pre-flight fetch перед каждым коммитом обязателен (§15.2).
|
||||
2. **Section-пересечение** (одна и та же секция §X.Y) — **hard-stop**, координация с заказчиком до начала правки.
|
||||
3. **Version-claim collision** (две сессии заявили один номер) — **hard-stop**, кто claim'нул раньше (по timestamp в CURRENT.md) — тот его и берёт; вторая сессия сдвигается на +1.
|
||||
|
||||
### 3.4 Что НЕ включаем (YAGNI)
|
||||
|
||||
- TTL / auto-expire записей — добавим, если файл реально засорится.
|
||||
- Machine-readable JSON-формат — markdown достаточен, парсится `grep`/`sed`.
|
||||
- Интеграция с GitHub Issues — отдельная тема, не блокер.
|
||||
- Pre-commit hook на проверку CURRENT.md — добавим только если будут зафиксированы инциденты игнорирования.
|
||||
|
||||
### 3.5 Pre-flight snippet (для plan-документов и скила)
|
||||
|
||||
```bash
|
||||
# Перед нормативной правкой:
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
grep -A 20 'status: in-progress' docs/sessions/CURRENT.md
|
||||
```
|
||||
|
||||
## 4. Хук `.claude/hooks/subagent-prompt-prefix.mjs`
|
||||
|
||||
### 4.1 Тип и matcher
|
||||
|
||||
Тип хука — **PreToolUse**, matcher `Task`. Перехватывает `tool_input.prompt`, дописывает в начало обязательный заголовок git-safety, возвращает модифицированный prompt через стандартный JSON-output API хук-системы Claude Code:
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "allow",
|
||||
"permissionDecisionReason": "git-safety header injected (Pravila §15.1)",
|
||||
"updatedInput": { "prompt": "<header>\n\n<original prompt>" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Точный формат API подтвердить против реально работающих `tools/ruflo-queen-hook.mjs` / `tools/ruflo-recall-hook.mjs` на этапе имплементации.
|
||||
|
||||
### 4.2 Тело заголовка
|
||||
|
||||
```text
|
||||
=== SUBAGENT GIT-SAFETY HEADER (Pravila §15.1, auto-injected) ===
|
||||
Working directory (cwd): <absolute path>
|
||||
Branch (git branch --show-current): <branch-name>
|
||||
Parent commit (git rev-parse HEAD): <sha>
|
||||
Worktree root (git rev-parse --show-toplevel): <path>
|
||||
|
||||
ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:
|
||||
1. Все git-операции выполняй ТОЛЬКО внутри cwd выше. Если pwd ≠ cwd — STOP, верни ошибку.
|
||||
2. ЗАПРЕЩЕНО: `git checkout <branch>`, `git switch <branch>`, `git checkout -b`, `git branch -m`, `git worktree add/remove`, `git push --force`, `git reset --hard`.
|
||||
3. После КАЖДОГО `git commit` — выполни `git rev-parse HEAD` и `git branch --show-current`, выпиши результат в ответ. Это обязательная часть отчёта.
|
||||
4. Если обнаружил, что находишься не в той ветке/worktree — STOP, не правь ничего, верни ошибку с raw output `git status` и `git branch --show-current`.
|
||||
5. Если задача не требует git-операций (только Edit/Read/Grep) — этот блок информационный, follow rule 1.
|
||||
|
||||
=== END SUBAGENT GIT-SAFETY HEADER ===
|
||||
<здесь — оригинальный prompt контроллера>
|
||||
```
|
||||
|
||||
### 4.3 Резолюция переменных
|
||||
|
||||
Хук резолвит 4 значения сам в момент инжекта — не из контроллера. Резолв через стандартный Node child-process API c fixed-string `git`-командами (без подстановки user-input в shell — все аргументы статичны: `git rev-parse HEAD`, `git rev-parse --show-toplevel`, `git branch --show-current`, `pwd`/`process.cwd()`). Контроллер мог быть запущен в одной директории, но Task инвокируется по факту в ней же — хук берёт `process.cwd()` рантайма.
|
||||
|
||||
### 4.4 Какие модели затрагиваются
|
||||
|
||||
Заголовок инжектится для **всех** Task-инвокаций (универсально). §15.1 (Sonnet-only для git) — **не в хук**, а в Pravila + чеклист скила (Секция 5). Хук не знает, является ли задача git-задачей: анализ prompt'а — ненадёжный signal, пусть это решает контроллер.
|
||||
|
||||
### 4.5 Edge-cases
|
||||
|
||||
1. **Task без git** (только read/edit) — заголовок присутствует, безвреден (rule 5 нейтрализует).
|
||||
2. **Контроллер уже включил похожий заголовок** — двойная защита, не проблема.
|
||||
3. **Хук упал** (например, `git` не в PATH) — возвращает `{"continue": true}` без модификации prompt'а + логирует stderr. Не блокирующий: лучше Task без заголовка, чем сломанный Task.
|
||||
4. **Несколько worktree в разных терминалах** — каждый запуск Claude Code имеет свой cwd, хук резолвит локально.
|
||||
|
||||
### 4.6 Объём и latency
|
||||
|
||||
~60 строк JS, паттерн один-в-один с `tools/ruflo-queen-hook.mjs` / `tools/ruflo-recall-hook.mjs`. Latency ~5–10 мс на Task (3 локальных `git`-вызова).
|
||||
|
||||
## 5. Verify-протокол в скиле `subagent-driven-development`
|
||||
|
||||
### 5.1 Где живёт
|
||||
|
||||
Добавочный чеклист-блок в скиле `superpowers:subagent-driven-development`:
|
||||
|
||||
- если скил вендорится в `.claude/skills/` — патчится напрямую;
|
||||
- если только marketplace-скил без локальной копии — добавляем `references/git-safety-checklist.md` рядом + одну строку «обязательный verify-блок после каждого субагента» в проектную обёртку. Фактический способ решается при имплементации (см. §7 ограничения).
|
||||
|
||||
### 5.2 Pre-spawn чеклист (до Task-инвокации)
|
||||
|
||||
1. Резолвить и записать: cwd, branch, parent SHA, worktree root — те же 4 значения, что инжектит хук. Контроллер хранит их у себя для post-check.
|
||||
2. Если задача git-коммит → выбрать model `sonnet` или `opus`. **Никогда** `haiku` (§15.1).
|
||||
3. Если задача правит нормативку из списка §15.2 → pre-flight `git fetch && git log HEAD..origin/main --oneline`. Не пусто → ребейз до инвокации, не после.
|
||||
|
||||
### 5.3 Post-subagent чеклист (сразу после возврата)
|
||||
|
||||
1. `git rev-parse HEAD` — сравнить с pre-spawn parent SHA. Ожидание: либо равно (субагент не коммитил), либо отличается **ровно одним коммитом** на pre-spawn HEAD.
|
||||
2. `git branch --show-current` — сравнить с pre-spawn branch. Не равно → **STOP**, разбор инцидента (Sprint 6 паттерн).
|
||||
3. `git log -1 --format='%s%n%P'` — проверить subject (соответствует задаче?) + parent (родитель = pre-spawn HEAD?).
|
||||
4. Если субагент коммитил несколько коммитов — не запрещено, но требует ручной проверки subject'ов.
|
||||
|
||||
### 5.4 Red-flag-список (любой = hard-stop разбор)
|
||||
|
||||
- branch ≠ ожидаемая;
|
||||
- parent коммита ≠ pre-spawn HEAD (= висячий коммит / попадание на чужую ветку);
|
||||
- HEAD двинулся, но субагент в отчёте об этом не упомянул;
|
||||
- в diff'е есть файлы вне scope задачи.
|
||||
|
||||
### 5.5 Формат отчёта субагента
|
||||
|
||||
Субагент обязан выписать в конце ответа блок:
|
||||
|
||||
```
|
||||
=== GIT REPORT ===
|
||||
cwd: <pwd>
|
||||
branch: <git branch --show-current>
|
||||
HEAD: <git rev-parse HEAD>
|
||||
HEAD^: <git rev-parse HEAD^>
|
||||
status: <git status --short>
|
||||
=== END GIT REPORT ===
|
||||
```
|
||||
|
||||
Отсутствие блока = контроллер считает результат недостоверным и запускает 5.3-чеклист сам через Bash.
|
||||
|
||||
### 5.6 Соотношение с code-review
|
||||
|
||||
Двухстадийное review сохраняется (Pravila §4.5 / R10 PSR_v1): сильная модель делает code-review артефакта субагента. Git-safety-чеклист **не заменяет** code-review, он стоит **до** него (нет смысла ревьюить diff, если он не в той ветке).
|
||||
|
||||
## 6. Тесты, migration, контракт записи
|
||||
|
||||
### 6.1 Тесты самих защит
|
||||
|
||||
| Защита | Тест | Ожидание |
|
||||
|---|---|---|
|
||||
| Хук (inject) | `echo '{"tool_input":{"prompt":"X"}}' \| node .claude/hooks/subagent-prompt-prefix.mjs` | `updatedInput.prompt` начинается с `=== SUBAGENT GIT-SAFETY HEADER ===`; cwd/branch/HEAD — реальные |
|
||||
| Хук — failure-mode | временно сломать (`mv .git → .git.bak`) → запустить хук | `{"continue":true}`, без модификации; Task не должен крашиться |
|
||||
| Verify-протокол (5.3) | Task субагенту с prompt `"do nothing, run git status, return"` | в ответе субагента — блок `=== GIT REPORT ===`; контроллер сверяет HEAD до/после — должны быть равны |
|
||||
| §15.1 enforcement | Ручной dry-run: попытаться делегировать `git commit` Haiku-субагенту | согласно чеклисту контроллер отказывается и перенаправляет Sonnet'у |
|
||||
| §15.2 pre-flight | Симулировать diverged state: `git fetch` + сделать divergence → попытаться правнуть Pravila | pre-flight snippet ловит, требует rebase |
|
||||
| CURRENT.md claim collision | Две параллельные сессии: добавить запись с тем же version-claim | вторая сессия должна вручную увидеть конфликт через grep `version-claims` |
|
||||
|
||||
Никакой автоматизации сверх этого (no pre-commit hook, no CI check) — YAGNI. Если CURRENT.md начнёт игнорироваться — добавим pre-commit grep отдельной правкой.
|
||||
|
||||
### 6.2 Migration существующих параллельных worktrees
|
||||
|
||||
На момент 18.05.2026 — 16 активных worktree (`git worktree list`). Шаги:
|
||||
|
||||
1. После merge §15 + хука + CURRENT.md на `main` — каждая активная worktree-сессия делает `git fetch` + ребейз на свежий `main` (получает §15 + хук).
|
||||
2. Каждая активная сессия дописывает свою запись в CURRENT.md одним коммитом (`sessions: backfill claim <topic>`) — не блокирует работу, retro-claim.
|
||||
3. Существующие version-collision'ы (A11 / C9 / A4 / discovery — последние 2 недели) **не пересматриваем**; §15 действует **с момента введения**, не ретроактивно.
|
||||
|
||||
### 6.3 Что НЕ делаем сейчас (явный YAGNI)
|
||||
|
||||
- Реестр зарезервированных версий — пропущен;
|
||||
- pre-commit hook на CURRENT.md — пропущен;
|
||||
- машинно-читаемый JSON-формат CURRENT.md — пропущен;
|
||||
- запрет параллельных сессий — нет, параллельность — норма проекта;
|
||||
- изменения PSR_v1 / Tooling — не требуются, §15 — внутри Pravila;
|
||||
- subagent-без-git (вариант C из брейншторма) — отложен до повторного инцидента после A+B.
|
||||
|
||||
## 7. Ограничения / что не верифицировано в дизайне
|
||||
|
||||
- **Не верифицировал** через grep, что в Pravila нет пересекающихся правил под номером §15 — проверено в формате headings `## 13. ... / ## 14. ...`, §15 свободен. Подтверждено на этапе brainstorming.
|
||||
- **Не верифицировал** API хук-системы Claude Code на актуальной версии CLI — формат `updatedInput` в PreToolUse для Task tool требует подтверждения против реально работающих `tools/ruflo-queen-hook.mjs` / `tools/ruflo-recall-hook.mjs` перед написанием хука. Задача имплементации, не дизайна.
|
||||
- **Не верифицировал**, что `subagent-driven-development` скил вендорится в `.claude/skills/`. Может быть только маркетплейс-скил без локальной копии — фактический способ патчинга решится при имплементации (Секция 5.1).
|
||||
- **Не верифицировал** Windows-специфику резолва `git`-команд через Node child-process в хуке — на Windows работало для `ruflo-queen-hook.mjs`, должно работать и здесь.
|
||||
|
||||
## 8. Acceptance criteria (для writing-plans)
|
||||
|
||||
Дизайн считается реализованным, когда:
|
||||
|
||||
1. Pravila §15 (15.1 + 15.2) добавлен, версия Pravila bumped, CHANGELOG entry есть.
|
||||
2. `docs/sessions/CURRENT.md` создан, формат описан в README рядом, в нём есть retro-claim запись для всех активных worktrees на момент имплементации (Migration §6.2; на дату дизайна — 16 штук).
|
||||
3. `.claude/hooks/subagent-prompt-prefix.mjs` написан, зарегистрирован в `.claude/settings.json`, прошёл тесты 6.1 (рукопись + failure-mode + e2e Task).
|
||||
4. Скил `subagent-driven-development` патчен (5.1) — verify-протокол доступен контроллеру.
|
||||
5. CLAUDE.md §1 cross-ref на §15 добавлен.
|
||||
6. Pre-commit gitleaks + Pest/Vitest GREEN; gitleaks-full-history + lychee — перед push.
|
||||
7. Регрессия Pest --parallel / Vitest — 0 регрессий vs baseline.
|
||||
@@ -0,0 +1,109 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* PreToolUse hook — git-safety header inject for Task tool.
|
||||
*
|
||||
* For каждый Task-инвокейшн контроллера: дописывает в начало tool_input.prompt
|
||||
* заголовок с cwd / branch / parent SHA / worktree-root + правилами поведения
|
||||
* (rule 1–5). Это компенсирует класс инцидентов «субагент путает ветку/worktree»
|
||||
* (Sprint 6, Pravila §15.1).
|
||||
*
|
||||
* FAIL-OPEN: любая ошибка / тайм-аут / git-не-в-PATH → {continue: true} без
|
||||
* модификации; хук НИКОГДА не блокирует Task.
|
||||
*
|
||||
* Non-Task tools — pass-through без модификации.
|
||||
*
|
||||
* Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md §4
|
||||
* Rule: docs/Pravila_raboty_Claude_v1_1.md §15.1
|
||||
*/
|
||||
import { execFile } from 'node:child_process';
|
||||
import { promisify } from 'node:util';
|
||||
|
||||
const execFileP = promisify(execFile);
|
||||
const GIT_TIMEOUT_MS = 1500;
|
||||
|
||||
/** Read all stdin into a string. */
|
||||
async function readStdin() {
|
||||
let buf = '';
|
||||
for await (const chunk of process.stdin) buf += chunk;
|
||||
return buf;
|
||||
}
|
||||
|
||||
/** Parse hook input JSON; return null on any parse error. */
|
||||
function parseHookInput(raw) {
|
||||
try { return JSON.parse(raw); } catch { return null; }
|
||||
}
|
||||
|
||||
/** Run a single fixed-args git command; return trimmed stdout, or null on any error. */
|
||||
async function gitCmd(args) {
|
||||
try {
|
||||
const { stdout } = await execFileP('git', args, { timeout: GIT_TIMEOUT_MS, encoding: 'utf8' });
|
||||
return stdout.trim();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Build the safety header block. Returns null if any of the 4 git values can't be resolved. */
|
||||
async function buildHeader() {
|
||||
const cwd = process.cwd();
|
||||
const [branch, head, top] = await Promise.all([
|
||||
gitCmd(['branch', '--show-current']),
|
||||
gitCmd(['rev-parse', 'HEAD']),
|
||||
gitCmd(['rev-parse', '--show-toplevel']),
|
||||
]);
|
||||
if (!branch || !head || !top) return null;
|
||||
return [
|
||||
'=== SUBAGENT GIT-SAFETY HEADER (Pravila §15.1, auto-injected) ===',
|
||||
`Working directory (cwd): ${cwd}`,
|
||||
`Branch (git branch --show-current): ${branch}`,
|
||||
`Parent commit (git rev-parse HEAD): ${head}`,
|
||||
`Worktree root (git rev-parse --show-toplevel): ${top}`,
|
||||
'',
|
||||
'ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:',
|
||||
'1. Все git-операции выполняй ТОЛЬКО внутри cwd выше. Если pwd ≠ cwd — STOP, верни ошибку.',
|
||||
'2. ЗАПРЕЩЕНО: `git checkout <branch>`, `git switch <branch>`, `git checkout -b`, `git branch -m`, `git worktree add/remove`, `git push --force`, `git reset --hard`.',
|
||||
'3. После КАЖДОГО `git commit` — выполни `git rev-parse HEAD` и `git branch --show-current`, выпиши результат в ответ. Это обязательная часть отчёта.',
|
||||
'4. Если обнаружил, что находишься не в той ветке/worktree — STOP, не правь ничего, верни ошибку с raw output `git status` и `git branch --show-current`.',
|
||||
'5. Если задача не требует git-операций (только Edit/Read/Grep) — этот блок информационный, follow rule 1.',
|
||||
'',
|
||||
'=== END SUBAGENT GIT-SAFETY HEADER ===',
|
||||
'',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
/** Emit fail-open response and exit 0. */
|
||||
function failOpen() {
|
||||
process.stdout.write(JSON.stringify({ continue: true }));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const raw = await readStdin();
|
||||
const input = parseHookInput(raw);
|
||||
if (!input) return failOpen();
|
||||
|
||||
// Non-Task — pass-through
|
||||
if (input.tool_name !== 'Task') return failOpen();
|
||||
|
||||
const originalPrompt = input.tool_input?.prompt;
|
||||
if (typeof originalPrompt !== 'string') return failOpen();
|
||||
|
||||
const header = await buildHeader();
|
||||
if (!header) {
|
||||
// git unavailable / not in worktree — fail-open per spec §4.5 edge-case 3
|
||||
process.stderr.write('[subagent-prompt-prefix] git resolution failed — passing through\n');
|
||||
return failOpen();
|
||||
}
|
||||
|
||||
const newPrompt = header + originalPrompt;
|
||||
process.stdout.write(JSON.stringify({
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'PreToolUse',
|
||||
permissionDecision: 'allow',
|
||||
permissionDecisionReason: 'git-safety header injected (Pravila §15.1)',
|
||||
updatedInput: { prompt: newPrompt },
|
||||
},
|
||||
}));
|
||||
}
|
||||
|
||||
main().catch(() => failOpen());
|
||||
@@ -0,0 +1,96 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Tests for tools/subagent-prompt-prefix.mjs — PreToolUse Task git-safety header inject.
|
||||
*
|
||||
* Per Pravila §15.1 — hook injects cwd/branch/HEAD/worktree-root into каждый Task-prompt.
|
||||
* FAIL-OPEN: any error → return {continue: true} без модификации.
|
||||
*
|
||||
* Spec: docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md §4
|
||||
*/
|
||||
import { test } from 'node:test';
|
||||
import { strict as assert } from 'node:assert';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { dirname, join } from 'node:path';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const HOOK_PATH = join(__dirname, 'subagent-prompt-prefix.mjs');
|
||||
|
||||
function runHook(stdinJson) {
|
||||
return spawnSync('node', [HOOK_PATH], {
|
||||
input: JSON.stringify(stdinJson),
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
});
|
||||
}
|
||||
|
||||
test('hook injects SUBAGENT GIT-SAFETY HEADER into Task prompt', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Task',
|
||||
tool_input: { prompt: 'do something' },
|
||||
});
|
||||
assert.equal(result.status, 0, `stderr: ${result.stderr}`);
|
||||
const out = JSON.parse(result.stdout);
|
||||
assert.ok(out.hookSpecificOutput, 'has hookSpecificOutput');
|
||||
assert.equal(out.hookSpecificOutput.hookEventName, 'PreToolUse');
|
||||
assert.equal(out.hookSpecificOutput.permissionDecision, 'allow');
|
||||
const newPrompt = out.hookSpecificOutput.updatedInput.prompt;
|
||||
assert.match(newPrompt, /=== SUBAGENT GIT-SAFETY HEADER/);
|
||||
assert.match(newPrompt, /=== END SUBAGENT GIT-SAFETY HEADER ===/);
|
||||
assert.match(newPrompt, /do something/, 'preserves original prompt');
|
||||
});
|
||||
|
||||
test('hook injects real cwd, branch, HEAD values', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Task',
|
||||
tool_input: { prompt: 'noop' },
|
||||
});
|
||||
assert.equal(result.status, 0);
|
||||
const out = JSON.parse(result.stdout);
|
||||
const newPrompt = out.hookSpecificOutput.updatedInput.prompt;
|
||||
// cwd — absolute path
|
||||
assert.match(newPrompt, /Working directory \(cwd\): [A-Za-z]:[\\/]|Working directory \(cwd\): \//);
|
||||
// branch — non-empty
|
||||
assert.match(newPrompt, /Branch \(git branch --show-current\): \S+/);
|
||||
// HEAD — 40-char SHA
|
||||
assert.match(newPrompt, /Parent commit \(git rev-parse HEAD\): [0-9a-f]{40}/);
|
||||
});
|
||||
|
||||
test('hook passes through non-Task tools without modification', () => {
|
||||
const result = runHook({
|
||||
tool_name: 'Edit',
|
||||
tool_input: { file_path: '/foo', old_string: 'a', new_string: 'b' },
|
||||
});
|
||||
assert.equal(result.status, 0);
|
||||
const out = JSON.parse(result.stdout);
|
||||
// Non-Task → either {continue: true} OR no updatedInput
|
||||
if (out.hookSpecificOutput) {
|
||||
assert.equal(out.hookSpecificOutput.updatedInput, undefined);
|
||||
} else {
|
||||
assert.equal(out.continue, true);
|
||||
}
|
||||
});
|
||||
|
||||
test('hook fail-open on malformed stdin', () => {
|
||||
const result = spawnSync('node', [HOOK_PATH], {
|
||||
input: 'not-json',
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
});
|
||||
assert.equal(result.status, 0, `should not crash; stderr: ${result.stderr}`);
|
||||
// Either {continue: true} or empty output — both acceptable fail-open
|
||||
});
|
||||
|
||||
test('hook fail-open when git not available', () => {
|
||||
// Cross-platform: set PATH to node's own directory only — node spawns OK,
|
||||
// git not in node's bin dir → ENOENT → hook fail-opens per spec §4.5.
|
||||
// (Previous approach `PATH: ''` kills node.exe spawn resolution on Windows.)
|
||||
const nodeDir = dirname(process.execPath);
|
||||
const result = spawnSync('node', [HOOK_PATH], {
|
||||
input: JSON.stringify({ tool_name: 'Task', tool_input: { prompt: 'x' } }),
|
||||
encoding: 'utf8',
|
||||
timeout: 5000,
|
||||
env: { PATH: nodeDir, PATHEXT: process.env.PATHEXT || '.EXE' },
|
||||
});
|
||||
assert.equal(result.status, 0, `should not crash when git missing; stderr: ${result.stderr}`);
|
||||
});
|
||||
Reference in New Issue
Block a user