# Section VII regroup + Section X Russian/Hierarchy — Design (v2)

**Дата:** 2026-05-10 (ночь финал, mode 0% rigor)
**Статус:** Approved by user · ready for writing-plans
**Файл-цель:** [`docs/visualizations/hooks-skills-plugins-map.html`](../../visualizations/hooks-skills-plugins-map.html) (2983 строки на момент написания spec'а)
**Mode:** Написан под «экономия 0%» — full file:line refs, honest disclosures, no shortcuts

---

## 1. Цель

Две связанные правки в существующем `hooks-skills-plugins-map.html`:

1. **§VII (Скилы по назначению, `hooks-skills-plugins-map.html:2116`):** перегруппировать с 6 функциональных категорий на 5 plugin-based групп
2. **§X (Связи — interactive map, `hooks-skills-plugins-map.html:2431`):**
   - Локализация всех UI-strings на русский (filter chips, legend edge labels, sidebar badges, tooltip text)
   - Sidebar при клике на узел показывает иерархию: «За что отвечает» / «Кто руководит» / «Кем руководит» / «Связи»
   - Edge-click открывает sidebar с описанием типа связи + переходами к источнику/цели

## 2. Scope

### 2.1. В scope

- `§VII` (строки 2116-2293 примерно): полная перепись 6 категорий → 5 plugin-based групп
- `§X` HTML: filter chips (`hooks-skills-plugins-map.html:2442-2448`) + legend edges (`hooks-skills-plugins-map.html:2477-2484`) — текстовые правки на русский
- `§X` JS (`hooks-skills-plugins-map.html:2811-2870` showSidebar/highlight/clearHighlight) — refactor под новую иерархическую структуру + новая функция edge-click handler
- `§X` CSS: добавление 2-3 новых классов для sidebar секций (governance markers + navigation buttons)

### 2.2. Не в scope (YAGNI)

- Изменения data model (`type`, `id`, `source`, `target` поля в GRAPH_NODES / GRAPH_LINKS остаются)
- Визуальная hierarchical layout на самом графе (force-axis по уровням, цветные обводки родителей)
- Breadcrumb / history sidebar'ов
- Search по узлам
- Изменения других секций (§I, §II, §III, §IV, §V, §VI, §VIII, §IX, §XI)

---

## 3. Change A: §VII Skills — regroup by plugin

### 3.1. Текущее состояние (до)

`hooks-skills-plugins-map.html:2116-2293` содержит секцию VII с **6 функциональными категориями**:

| Line | Symbol | Category | Skills |
|---|---|---|---|
| 2127-2129 | § | Процесс работы | 14 (superpowers) |
| 2193-2195 | ¶ | Документация | 2 (claude-md-management) |
| 2211-2213 | ◊ | UI / Дизайн | 2 (fd + ui-ux-pro-max) |
| 2229-2231 | ⚙ | Конфигурация и инфраструктура | 6 standalone |
| 2263-2265 | ↻ | Автоматизация и циклы | 2 standalone (loop, schedule) |
| 2281-2283 | ⌖ | Code review | 2 standalone (review, security-review) |

### 3.2. Целевое состояние (после)

**5 plugin-based групп** (4 плагина + 1 standalone):

| # | Plugin source | Symbol | Skills | Skill IDs (data model match) |
|---|---|---|---|---|
| 1 | superpowers (obra/superpowers v5.1.0) | ⚡ | 14 | brainstorming, writing-plans, executing-plans, test-driven-development, systematic-debugging, requesting-code-review, receiving-code-review, verification-before-completion, finishing-a-development-branch, using-git-worktrees, subagent-driven-development, dispatching-parallel-agents, using-superpowers, writing-skills |
| 2 | claude-md-management (anthropic) | ¶ | 2 | claude-md-improver, revise-claude-md |
| 3 | frontend-design (anthropic) | ◊ | 1 | frontend-design |
| 4 | ui-ux-pro-max (nextlevelbuilder) | △ | 1 | ui-ux-pro-max |
| 5 | Standalone / встроенные (нет плагина) | ⌖ | 10 | update-config, keybindings-help, simplify, fewer-permission-prompts, init, claude-api, loop, schedule, review, security-review |

**Total:** 28 skills, никаких потерь.

### 3.3. Visual

- **Section title** (`hooks-skills-plugins-map.html:2119`): «Скилы по&nbsp;назначению» → **«Скилы по&nbsp;плагинам»**
- **Section lede** (`hooks-skills-plugins-map.html:2120-2123`): обновить — указать что группы теперь по plugin parent, не по функции
- `sp-row` структура без изменений (existing CSS `hooks-skills-plugins-map.html:719`)
- `sp-cat-name` (`hooks-skills-plugins-map.html:749`): имя плагина
- `sp-cat-meta` (`hooks-skills-plugins-map.html:756`): «14 skills · obra/superpowers v5.1.0» формат
- `sp-cat-symbol` (`hooks-skills-plugins-map.html:739`): новые символы из таблицы выше (5 unique)
- `sp-skills-detail` (`hooks-skills-plugins-map.html`, в каждом sp-row): описания каждого skill — **переезжают** из текущих 6 категорий в новые 5 групп, тексты без изменений

### 3.4. Не теряем

- ✅ Все 28 skills остаются на странице
- ✅ Все описания (italic emphasis + текст) сохраняются — только переезжают
- ✅ CSS классы остаются — никаких CSS-добавок не требуется

---

## 4. Change B.1: §X Russian translation

### 4.1. UI strings — полный mapping

#### HTML strings (текстовые правки)

| Где (file:line) | English (текущее) | Russian (новое) |
|---|---|---|
| `hooks-skills-plugins-map.html:2433` | «Связи &mdash; interactive map» | «Связи &mdash; интерактивная карта» |
| `hooks-skills-plugins-map.html:2454` | «Reset layout» | «Сбросить расположение» |
| `hooks-skills-plugins-map.html:2442` | Plugins | Плагины |
| `hooks-skills-plugins-map.html:2443` | Skills | Скилы |
| `hooks-skills-plugins-map.html:2444` | Scripts | Скрипты |
| `hooks-skills-plugins-map.html:2445` | Events | События |
| `hooks-skills-plugins-map.html:2446` | State | Состояние |
| `hooks-skills-plugins-map.html:2447` | Perms | Права |
| `hooks-skills-plugins-map.html:2448` | Rules | Правила |
| `hooks-skills-plugins-map.html:2467` | Plugin (4) | Плагин (4) |
| `hooks-skills-plugins-map.html:2468` | Skill (28) | Скил (28) |
| `hooks-skills-plugins-map.html:2469` | Hook script (7) | Скрипт хука (7) |
| `hooks-skills-plugins-map.html:2470` | Hook event (5) | Событие хука (5) |
| `hooks-skills-plugins-map.html:2471` | State file (1) | Файл состояния (1) |
| `hooks-skills-plugins-map.html:2472` | Permission (3) | Права (3) |
| `hooks-skills-plugins-map.html:2473` | Rule (2) | Правило (2) |
| `hooks-skills-plugins-map.html:2477` | contains | содержит |
| `hooks-skills-plugins-map.html:2478` | triggers | запускает |
| `hooks-skills-plugins-map.html:2479` | writes | пишет |
| `hooks-skills-plugins-map.html:2480` | reads | читает |
| `hooks-skills-plugins-map.html:2481` | mandates | обязывает |
| `hooks-skills-plugins-map.html:2482` | references | ссылается |
| `hooks-skills-plugins-map.html:2483` | blocks | блокирует |
| `hooks-skills-plugins-map.html:2484` | denies | запрещает |

**Total HTML правок:** 24 строки в HTML.

#### JS strings — добавить mapping constants

Новые константы в JS блоке (`hooks-skills-plugins-map.html:~2700`):

```js
const EDGE_TYPE_RU = {
  contains: 'содержит',
  triggers: 'запускает',
  writes: 'пишет',
  reads: 'читает',
  mandates: 'обязывает',
  references: 'ссылается',
  blocks: 'блокирует',
  denies: 'запрещает'
};

const NODE_TYPE_RU = {
  plugin: 'Плагин',
  skill: 'Скил',
  script: 'Скрипт',
  event: 'Событие',
  state: 'Состояние',
  perm: 'Права',
  rule: 'Правило'
};
```

Use sites:

- `showSidebar` (`hooks-skills-plugins-map.html:2811`) — badge text → `NODE_TYPE_RU[node.type]`
- connection list entries (`hooks-skills-plugins-map.html:~2820, 2825`) — replace `${l.type}` → `${EDGE_TYPE_RU[l.type]}`
- Tooltip (`hooks-skills-plugins-map.html:~2891`) — replace `${l.type}` → `${EDGE_TYPE_RU[l.type]}`

### 4.2. Что НЕ меняем (явно)

- **Internal data `type` values** в GRAPH_NODES / GRAPH_LINKS — остаются английскими (`contains`, `triggers`, etc.). Это data model, не display.
- CSS class names — остаются с английскими постфиксами (`.gl-contains`, `.gl-triggers`) — соответствие data model.
- `data-type` атрибуты на filter chips — остаются английскими (`data-type="plugin"`) — JS логика использует data attribute для filtering, не label.

---

## 5. Change B.2: Sidebar — иерархия (governance)

### 5.1. Классификация edge types на 2 категории

| Edge type | Категория | Реальная семантика |
|---|---|---|
| contains | **governance** | Плагин управляет составом своих скилов |
| mandates | **governance** | Pravila §12 обязывает использовать skill |
| triggers | **governance** | Event запускает script (runtime control) |
| blocks | **governance** | permissions.ask контролирует доступ к script |
| denies | **governance** | permissions.deny блокирует операции с state |
| writes | data flow | Поток данных в state |
| reads | data flow | Поток данных из state |
| references | data flow | Ссылка между документами (priority chain — навигация, не управление) |

Реализация: `const GOVERNANCE_TYPES = ['contains', 'mandates', 'triggers', 'blocks', 'denies']`.

### 5.2. Sidebar structure при клике на УЗЕЛ

```
┌─────────────────────────────────────┐
│ {Имя узла}            [Закрыть ×]    │
│ [Russian type badge]                │
│                                     │
│ [За что отвечает]                   │
│ {desc field}                        │
│                                     │
│ [Кто руководит (N)]                 │ ← incoming, governance only
│ • {src.label} {RU edge type}        │
│ ...                                  │
│                                     │
│ [Кем руководит (N)]                 │ ← outgoing, governance only
│ • {RU edge type} → {tgt.label}      │
│ ...                                  │
│                                     │
│ [Связи (info flow) (N)]              │ ← all non-governance edges, both directions
│ • пишет → {tgt}                     │
│ • {src} ссылается                   │
│ ...                                  │
└─────────────────────────────────────┘
```

**Каждая секция отображается только если есть данные** (skip empty sections). Если у узла нет ни одной governance связи в одну сторону — секция не показывается.

### 5.3. Algorithm

```js
function classifyEdges(node) {
  const incoming = GRAPH_LINKS.filter(l => target_id(l) === node.id);
  const outgoing = GRAPH_LINKS.filter(l => source_id(l) === node.id);
  return {
    governedBy:  incoming.filter(l => GOVERNANCE_TYPES.includes(l.type)),
    governing:   outgoing.filter(l => GOVERNANCE_TYPES.includes(l.type)),
    infoFlow:    [...incoming, ...outgoing].filter(l => !GOVERNANCE_TYPES.includes(l.type))
  };
}
```

---

## 6. Change B.3: Edge click → sidebar

### 6.1. New behavior

- Сейчас edge имеет только **hover tooltip** (`hooks-skills-plugins-map.html:~2885 linkSel.on('mouseover')`)
- Добавляем: **linkSel.on('click', ...)** → `showEdgeSidebar(edge)`
- При edge-click: подсвечиваются только source + target + сама edge (analog of node highlight)
- Click на пустой SVG — clearHighlight (already exists)

### 6.2. Sidebar structure при клике на EDGE

```
┌─────────────────────────────────────┐
│ {RU edge type}        [Закрыть ×]    │
│ [Связь]                             │
│                                     │
│ [Что это значит]                    │
│ {EDGE_DESC[type]}                   │
│                                     │
│ [Источник]                          │
│ {src.label}                         │
│ {src type RU badge}                 │
│ {src.desc}                          │
│ [Перейти к узлу →]                  │
│                                     │
│ [Цель]                              │
│ {tgt.label}                         │
│ {tgt type RU badge}                 │
│ {tgt.desc}                          │
│ [Перейти к узлу →]                  │
└─────────────────────────────────────┘
```

### 6.3. Edge type descriptions

| Type | Russian label | Description |
|---|---|---|
| contains | содержит | Плагин упаковывает скил и доставляет его в систему как часть marketplace-пакета. |
| triggers | запускает | Hook event запускает скрипт автоматически в момент события (SessionStart, PreToolUse, Stop, etc.). |
| writes | пишет | Скрипт записывает данные в общий state-файл `$TEMP/claude-economy-<session_id>.json` для других хуков той же сессии. |
| reads | читает | Скрипт читает данные из state-файла, чтобы знать активный уровень экономии и применять соответствующие правила. |
| mandates | обязывает | Pravila §12 hard rule обязывает использовать этот skill для подходящих задач — §9 «Отступления» к §12 НЕ применяется. |
| references | ссылается | Документ ссылается на другой как часть приоритетной цепочки правил (CLAUDE.md §1). При конфликте — приоритет у верхнего уровня. |
| blocks | блокирует | permissions.ask требует явный approve пользователя перед Edit/Write этого файла. Защита от tampering. |
| denies | запрещает | permissions.deny полностью запрещает Bash-операции (rm/mv/cp) над защищёнными файлами — обхода нет. |

### 6.4. Highlight при edge-select

```js
function highlightEdge(edge) {
  activeId = `edge:${edge_index}`;
  const sId = source_id(edge);
  const tId = target_id(edge);
  nodeSel.classed('dimmed', d => d.id !== sId && d.id !== tId);
  linkSel.classed('dimmed', l => l !== edge);
  showEdgeSidebar(edge);
}
```

### 6.5. Navigation buttons

В sidebar при edge-click — две кнопки «Перейти к узлу →». Click → `highlightNode(src/tgt)` (как если бы пользователь кликнул на узел).

---

## 7. Implementation details

### 7.1. Files modified

Только `c:/моя/проекты/портал crm/Документация/docs/visualizations/hooks-skills-plugins-map.html`. Никаких других файлов.

### 7.2. Размер изменений (оценка)

| Раздел | Изменение | Строк |
|---|---|---|
| §VII rewrite | 6 категорий → 5 групп, 28 skills переезжают | -180/+185 в `hooks-skills-plugins-map.html:2116-2293` |
| §X HTML chips/legend | 24 текстовые правки | inline ~24 edits |
| §X JS constants | EDGE_TYPE_RU, NODE_TYPE_RU, EDGE_DESC, GOVERNANCE_TYPES | +~40 строк |
| §X JS sidebar refactor | showSidebar + новая showEdgeSidebar + highlightEdge | +~60/-25 строк |
| §X JS click handler | `linkSel.on('click', ...)` | +~5 строк |
| §X CSS additions | sidebar section variants, navlink button | +~25 строк |
| **Total** | **~210 строк добавки/правок** | файл 2983 → ~3050 |

### 7.3. Risks

| # | Риск | Severity | Митигация |
|---|---|---|---|
| 1 | Edge click event может конфликтовать с hover tooltip | LOW | `event.stopPropagation()` на edge click; tooltip уже дополнен `defaultPrevented` |
| 2 | applyFilters скрывает active edge → sidebar показывает stale info | MEDIUM | Уже есть guard для node (Fix 1 в предыдущей итерации); добавить аналог для edge: если active edge скрыт filter'ом — clearHighlight |
| 3 | Russian text длиннее → layout break в filter chips | LOW | `flex-wrap` уже стоит на `.graph-filters` (`hooks-skills-plugins-map.html:577`) |
| 4 | EDGE_TYPE_RU mapping пропуск — `undefined` text в UI | LOW | Все 8 типов в data model перечислены; добавить fallback `EDGE_TYPE_RU[type] ?? type` |
| 5 | NODE_TYPE_RU пропуск — `undefined` в badge | LOW | Все 7 типов перечислены; добавить fallback |
| 6 | Стандартный skill `init` без плагина — где показывать в §VII | RESOLVED | В группе «Standalone / встроенные» (§3.2 №5) |
| 7 | «Кто руководит» / «Кем руководит» empty состояния — раздражение | LOW | Skip empty sections (described в §5.2) |
| 8 | Navigation кнопки «Перейти к узлу» из edge sidebar — циклы навигации | LOW | Каждый click это новый `highlightNode` — sidebar обновляется, циклы безопасны |

### 7.4. Что не верифицировано (mode 0% honesty)

- **Реальный визуальный рендеринг** русских filter chips и legend — теоретически flex-wrap справится, но фактическую ширину не измерял.
- **D3 v7 поведение** `linkSel.on('click', ...)` — не верифицировал в этой сессии (только `mouseover` сейчас работает). Документация D3 гарантирует, но реальное поведение увижу только после имплементации + browser test.
- **Полнота EDGE_DESC** mapping'а — 8 типов, проверил все против GRAPH_LINKS data model в `hooks-skills-plugins-map.html:GRAPH_LINKS` array. Совпадает.

---

## 8. Success criteria

После имплементации:

- [ ] §VII: 5 групп вместо 6, заголовок «Скилы по плагинам»
- [ ] §VII: все 28 skills присутствуют в новых группах (никаких потерь)
- [ ] §VII: символы 5 групп: ⚡ / ¶ / ◊ / △ / ⌖ — уникальные
- [ ] §X title: «Связи — интерактивная карта»
- [ ] §X filter chips: 7 русских названий (Плагины/Скилы/Скрипты/События/Состояние/Права/Правила)
- [ ] §X legend edges: 8 русских (содержит/запускает/пишет/читает/обязывает/ссылается/блокирует/запрещает)
- [ ] §X legend nodes: 7 русских (Плагин/Скил/Скрипт хука/Событие хука/Файл состояния/Права/Правило)
- [ ] §X reset button: «Сбросить расположение»
- [ ] §X sidebar при клике на узел: видны секции «За что отвечает», «Кто руководит» (если есть), «Кем руководит» (если есть), «Связи (info flow)» (если есть)
- [ ] §X sidebar при клике на edge: видны секции «Что это значит» + Источник + Цель + 2 кнопки «Перейти»
- [ ] §X edge click подсвечивает только src+tgt + саму edge
- [ ] §X tooltip text: Russian (e.g., «содержит: A → B»)
- [ ] §X sidebar badge: Russian (e.g., «Плагин» вместо «plugin»)
- [ ] HTML well-formed (0 unclosed / 0 orphans) — verify через Python HTMLParser
- [ ] No JS console errors при загрузке + клики
- [ ] No D3 fallback message (D3 v7 CDN работает)
- [ ] File grows from 2983 → ~3050 строк

---

## 9. Open questions

Нет. Все архитектурные выборы утверждены через AskUserQuestion:

- §VII: regroup by plugin (recommended option) — approved
- §X hierarchy: только в sidebar (recommended) — approved

---

## 10. Next steps

После approve этого spec'а:

1. **`superpowers:writing-plans`** — пошаговый план имплементации с bite-sized tasks
2. **Execution**: inline через executing-plans (я в контексте файла), без subagent-driven (Stage 0 не блокирует project file edits, но subagent-driven для этого размера overhead'ный)

---

**Status: rewritten under mode 0% rigor · awaiting user review.**
