# Rules audit fixes — implementation plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Закрыть 14 находок аудита нормативной документации (CLAUDE.md v1.83, Pravila v1.8, PSR_v1 v1.4, Tooling Прил. Н v1.12) с сохранением максимальной эффективности и всеобъемлющего использования всех плагинов и скилов.

**Architecture:** Правки группируются **по файлу**, не по находке. CLAUDE.md правки идут через `claude-md-management:claude-md-improver` (CLAUDE.md §5 п.10). Pravila/PSR_v1/Tooling — прямые `Edit` (Pravila §12.3 exclusion для документационных правок уровня §4). Финал — `superpowers:verification-before-completion`. Бамп версий: CLAUDE.md v1.83→v1.84, Pravila v1.8→v1.9, PSR_v1 v1.4→v1.5, Tooling v1.12→v1.13. Single-source-of-truth: Pravila §12.3 — для exclusions §12; CLAUDE.md §1 — для file-priority chain (7 уровней).

**Tech Stack:** Markdown editing, Skill (claude-md-management:claude-md-improver, superpowers:verification-before-completion), Edit, Grep.

---

## Task 1: Tooling §7 — добавить PSR_v1 в иерархию (находка #1)

**Files:**

- Modify: `docs/Tooling_v8_3.md` (§7 «Source of truth — приоритет правил», ~line 322)

- [ ] **Step 1:** Заменить 5-уровневую цепочку на 7-уровневую с явным PSR_v1 на уровне 3:

  ```
  docs/Pravila_raboty_Claude_v1_1.md (§12 hard rule — выше всех)
          ↓
  docs/Pravila_raboty_Claude_v1_1.md (остальные параграфы)
          ↓
  CLAUDE.md (корень — оперативная карта)
          ↓
  docs/Plugin_stack_rules_v1.md (PSR_v1 — координация stack'а)
          ↓
  .claude/settings.json (хуки, permissions)
          ↓
  memory/*.md (динамическая память)
          ↓
  Прочие плагины и встроенные skills Claude Code
  ```

- [ ] **Step 2:** Sync с CLAUDE.md §1 — структура совпадает.

---

## Task 2: Tooling §4 — добавить #33 claude-md-management (находка #2)

**Files:**

- Modify: `docs/Tooling_v8_3.md` (§4 фаза 2, после §4.6 — добавить §4.7)
- Modify: `docs/Tooling_v8_3.md` (§0 сводка — обновить счётчик до 33)

- [ ] **Step 1:** Добавить §4.7 «Инфраструктурный слой — claude-md-management plugin (off-phase tool)»:
  - роль: единственный интерфейс правок CLAUDE.md (CLAUDE.md §5 п.10)
  - два skill: `claude-md-improver` (audit + targeted updates), `revise-claude-md` (capture session learnings)
  - marketplace: `anthropics/claude-plugins-official`
  - категория: «инфраструктурный, не UI» — поэтому отдельная категория от UPM/21st
- [ ] **Step 2:** Обновить §0 сводку: «32 формализованных позиций» → «33 формализованных позиций (19/29 по фазам + 3 off-phase: UPM, 21st, claude-md-management)».
- [ ] **Step 3:** Обновить шапку Tooling «Что нового в v1.13».

---

## Task 3: Tooling §6 — добавить новые конфликты v1.4 (находка #3)

**Files:**

- Modify: `docs/Tooling_v8_3.md` (§6 «Конфликты и решения», ~line 304)

- [ ] **Step 1:** Добавить 5 новых строк в таблицу конфликтов:
  - UPM ↔ FD на одной фазе → R10.1 + R14.5: не параллельно
  - 21st ↔ существующий Vuetify-компонент → R0.6 пункт 10: hard-стоп
  - 21st ↔ брендовый App* → R0.6 пункт 9: hard-стоп
  - framer-motion ↔ motion-v → R15.1 vs R15.2 (разные регуляции)
  - UPM ↔ 21st на одной фазе → R14.5: не параллельно

---

## Task 4: Tooling §4.6 — починить «settings.json» → «.claude.json» (находка #11)

**Files:**

- Modify: `docs/Tooling_v8_3.md` (§4.6 раздел Безопасность, ~line 284)

- [ ] **Step 1:** Заменить «При случайном попадании settings.json в репо» на «При случайном попадании `~/.claude.json` (где хранится API-ключ) в репо».

---

## Task 5: PSR_v1 R10.1 — разделить плагины/skills/MCP (находка #8)

**Files:**

- Modify: `docs/Plugin_stack_rules_v1.md` (R10.1 «Реестр внешних плагинов», ~line 376)

- [ ] **Step 1:** Разбить таблицу R10.1 на три блока:
  - **Блок 1: `enabledPlugins` через marketplace** — ui-ux-pro-max, claude-md-management
  - **Блок 2: Built-in skills Claude Code** — review, security-review, init, simplify, update-config, keybindings-help, fewer-permission-prompts, loop, schedule, claude-api
  - **Блок 3: MCP-серверы** — 21st.dev Magic, Boost MCP

---

## Task 6: PSR_v1 R8 — добавить тай-брейкер FD↔21st (находка #14)

**Files:**

- Modify: `docs/Plugin_stack_rules_v1.md` (R8 «Тай-брейкеры», ~line 322)

- [ ] **Step 1:** Добавить строку в R8: «**FD ↔ 21st** на одной задаче → R14.4 implicit «последовательно, FD ведущий»; 21st вызывается в фазе 5 как подзадача FD, не параллельно».

---

## Task 7: PSR_v1 — отметить hard-rule tier (находка #9)

**Files:**

- Modify: `docs/Plugin_stack_rules_v1.md` (после R10.4 + после R14.7)

- [ ] **Step 1:** В R10.4 + R14.7 добавить пометку «**Tier:** transitive hard-rule (через цепочку Pravila §13.9/§13.10 → §13). Не explicit hard-rule как Pravila §12, но эквивалент по последствиям. Pravila §9 «Отступления» к нему **не применяется** (наследуется от §13.9/§13.10 hard-link)».

---

## Task 8: Pravila §12.3 — объявить SoT для exclusions (находка #5)

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (§12.3 ~line 532)
- Modify: `docs/Plugin_stack_rules_v1.md` (R0.4.A ~line 84)

- [ ] **Step 1:** В Pravila §12.3 добавить шапку: «**Single Source of Truth для exclusions §12.** При расширении списка — править только этот раздел; в CLAUDE.md §5 п.11 и PSR_v1 R0.4.A — только cross-ref сюда».
- [ ] **Step 2:** В PSR_v1 R0.4.A добавить cross-ref: «См. Pravila §12.3 (SoT). Список ниже — отражает Pravila §12.3, при расхождении побеждает Pravila».

---

## Task 9: Pravila §13 — упомянуть claude-md-management (находка #6)

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (§13.2 «Парность» ~line 578)

- [ ] **Step 1:** Добавить абзац в §13.2 (после описания paired stack'а): «**Инфраструктурные плагины (вне расширенного UI-пула):** `claude-md-management` (CLAUDE.md edits, §5 п.10) — не UI-инструмент, регулируется PSR_v1 R10.1 как off-pool tool. Аналогичные категории — review/security-review/init/simplify (built-in skills Claude Code, по явному `/имя`)».

---

## Task 10: Pravila §13.6 — оформить tier hard-rule (находка #9)

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (§13.6 ~line 612)

- [ ] **Step 1:** В §13.6 добавить: «**Hard-rule tier-структура:** §12 — explicit hard-rule (§9 не применяется). §13.9/§13.10 — transitive hard-rule (через hard-link на нарушение PSR_v1 R10/R14; по последствиям эквивалентны §12 — фиксация в feedback memory + утрата головенства stack'а). §9 «Отступления» к §13.9/§13.10 **не применяется**, наследуется от §12-эквивалентного статуса».

---

## Task 11: Pravila/PSR_v1/CLAUDE.md — добавить scope-метки к цепочкам (находка #4)

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (§0 ~line 64)
- Modify: `docs/Plugin_stack_rules_v1.md` (R0.1 таблица ~line 26)

- [ ] **Step 1:** В Pravila §0 добавить one-liner: «**Scope этой цепочки:** внутрипараграфный приоритет Pravila. Файловая иерархия — в CLAUDE.md §1; scope головенства stack'а — в PSR_v1 R0.1».
- [ ] **Step 2:** В PSR_v1 R0.1 в шапку таблицы добавить: «**Scope:** головенство stack'а над уровнями файловой иерархии CLAUDE.md §1. Не дублирует Pravila §0 (внутрипараграфный) и не дублирует CLAUDE.md §1 (общая 7-уровневая цепочка)».

---

## Task 12: CLAUDE.md правки через claude-md-improver (находки #2, #5, #7, #12, #4)

**Files:**

- Modify: `CLAUDE.md` через `Skill claude-md-management:claude-md-improver`

- [ ] **Step 1:** Через `claude-md-improver` сделать targeted updates:
  - **§3.3 (после #32):** добавить #33 claude-md-management как off-phase tool с ролью «инфраструктурный плагин для CLAUDE.md edits».
  - **§5 п.5:** свернуть длинный текст до 2-3 строк с cross-ref «детали — PSR_v1 R14»; убрать дублирование UPM-rule (находка #12).
  - **§5 п.11:** добавить cross-ref на Pravila §12.3 как SoT для exclusions.
  - **§1 priority chain:** добавить one-liner «общая 7-уровневая файловая иерархия; см. Pravila §0 для внутрипараграфного, PSR_v1 R0.1 для scope головенства» (находка #4).
- [ ] **Step 2:** Bump CLAUDE.md v1.83 → v1.84 в шапке.
- [ ] **Step 3:** Обновить «История версий» в CLAUDE.md.

---

## Task 13: Версионные шапки и cross-refs (sync)

**Files:**

- Modify: `docs/Pravila_raboty_Claude_v1_1.md` (шапка)
- Modify: `docs/Plugin_stack_rules_v1.md` (шапка)
- Modify: `docs/Tooling_v8_3.md` (шапка)

- [ ] **Step 1:** Pravila v1.8 → v1.9, добавить «Что изменилось» (Tasks 8, 9, 10, 11).
- [ ] **Step 2:** PSR_v1 v1.4 → v1.5, добавить «История версий» (Tasks 5, 6, 7, 8, 11).
- [ ] **Step 3:** Tooling v1.12 → v1.13, добавить «Что нового в v1.13» (Tasks 1, 2, 3, 4).
- [ ] **Step 4:** Sync cross-refs во всех файлах: «Pravila v1.9+», «PSR_v1 v1.5+», «Tooling v1.13+», «CLAUDE.md v1.84+».

---

## Task 14: Финальная верификация — superpowers:verification-before-completion

**Files:**

- Read: все 4 нормативных документа

- [ ] **Step 1:** Инвокировать `Skill superpowers:verification-before-completion`.
- [ ] **Step 2:** Прогнать чек-лист по 14 находкам аудита: каждая закрыта?
- [ ] **Step 3:** Cross-ref проверка: все версии синхронны (Pravila v1.9 ↔ PSR_v1 v1.5 ↔ Tooling v1.13 ↔ CLAUDE.md v1.84)?
- [ ] **Step 4:** Grep на старые версии («v1.4 PSR» когда уже v1.5; «v1.8 Pravila» когда уже v1.9 и т.д.) — должны быть только в исторических контекстах.
- [ ] **Step 5:** Self-review по CLAUDE.md §8: 0 orphan-ссылок, метрики не сломаны.

---

## Не закрывается этим планом (по решению аудита)

- **Находка #10:** R0.6 пункт 11 ⊂ пункт 6 — оставлено намеренно (motion-специальный flow R15.2 vs общий R12).
- **Находка #13:** §13.10 формально избыточен — оставлено намеренно (явная запись лучше транзитивного вывода).

---

## Последовательность исполнения

```
1. Tooling правки (Tasks 1, 2, 3, 4) — параллельно в одном файле
2. PSR_v1 правки (Tasks 5, 6, 7, 11.2) — параллельно
3. Pravila правки (Tasks 8, 9, 10, 11.1) — параллельно
4. CLAUDE.md правки (Task 12) — через claude-md-improver
5. Версионные sync (Task 13)
6. Верификация (Task 14)
```

Зависимостей между Tasks 1–11 нет (разные файлы / разные секции). Task 12 зависит от Task 2 (нужен номер #33). Task 13 — после всех правок. Task 14 — последний.
