---
name: Velorix-repo-hygiene
description: >-
  Глубокая уборка репозитория Velorix: мёртвый код, мусорные файлы, аудит
  tests/scripts, сверка rules/skills/docs на дубли и противоречия. Запускать по
  явной просьбе владельца («repo hygiene», «уборка», «аудит governance»).
disable-model-invocation: true
---

# Repo hygiene — уборка и governance (Velorix)

**Триггер:** владелец просит уборку / аудит tests+scripts / сверку rules+skills+docs / «составь план» по hygiene.

## План (обязательно перед работой)

**Если** владелец просит **план** (не «начинай чистить») **то:**

1. **SwitchMode → Plan** (или **CreatePlan**).
2. План — **только** артефакт Plan mode (`.cursor/plans/*.plan.md` через CreatePlan). **Запрещено:** создавать `docs/*PLAN*.md`, `docs/REPO_HYGIENE*.md` и любые markdown-планы в репо **без явной просьбы** «запиши план в docs/…».
3. В плане: фазы 0–6, gates, deliverables, todos — **кратко**, без простыни в чат.
4. **Ждать подтверждения** плана владельцем; **не** удалять код/tests/scripts до approve.
5. После approve — исполнять фазы по этому skill; инвентаризация ф.0 — таблица в ответе или todo плана, **не** отдельный doc-файл, если владелец не просил.

**Если** владелец дал команду `hygiene N` / «начинай фазу N» **то** план уже подтверждён или не нужен — идти к фазе N.

---

**Триггер исполнения:** `hygiene 0` … `hygiene 6`, `hygiene all`, или явное «начинай уборку» после approve плана.

**Запрещено:** спешить; удалять без классификации; трогать `docs/archive/*.OLD.md` как активный канон; `git restore` старого UI ([`velorix-no-git-restore.mdc`](../../rules/velorix-no-git-restore.mdc)); ломать `npm run check:quiet`.

**Обязательно:** работать **фазами**; после каждой фазы с diff — `npm run check:quiet`; одна `J-NNN` на фазу (skill [`velorix-journal-entry`](../velorix-journal-entry/SKILL.md)).

## Временные артефакты (обязательная уборка)

**Если** для выполнения hygiene создаётся что-то **временное** (one-off script, scratch `.mjs`/`.ts`, helper, промежуточный отчёт, debug output, таблица в `docs/` без явной просьбы) **то:**

1. **Предпочитать** существующие `npm run audit:*` и gate-скрипты — не плодить новые файлы без нужды.
2. **Вести список** созданных временных путей (в ответе или todo фазы).
3. **Удалить всё временное** до конца **той же фазы** (или в **ф.6**, если артефакт нужен нескольким фазам).
4. **Gate:** `git status --short` не содержит hygiene-scratch; `check:quiet` зелёный.

**Исключение (KEEP, не мусор):** артефакт оформлен как постоянный — npm script в `package.json`, wiring в `scripts-inventory-meta.ts`, тест-guard, audit в manifest. Тогда sync inventory, **не** удалять.

**Запрещено:** оставлять one-off scripts/tests/reports «на потом» после завершения фазы или всего прогона hygiene.

**Иерархия при конфликте текстов:** [`.cursor/rules/velorix-rules-explicit.mdc`](../../rules/velorix-rules-explicit.mdc) (глоссарий) → исполняемые `.mdc` → skills → `docs/SOURCES_OF_TRUTH.md` → `AGENTS.md` / `agent-contract.txt` (индексы, не дублировать канон).

---

## Фаза 0 — инвентаризация (read-only)

Собрать артефакты **до** удалений:

| Команда / файл | Зачем |
| -------------- | ----- |
| `npm run audit:orphan-scripts` | scripts без npm entry (может быть wiring-exempt) |
| `npm run audit:dead-type-reexports` | мёртвые `export type` |
| `npm run audit:todo-debt` | TODO/FIXME в `src/`, `tests/` |
| `npm run audit:structural` | файлы >500 строк без justification |
| `npm run audit:inventory` + `audit:inventory-sync` | расхождение manifest vs диск |
| `npm run audit:copy-paste` | дубли parse/helpers |
| `src/shared/scripts-inventory-meta.ts` | wiring-exempt e2e (`neon-ref-visual-*`, `import-neon-refs`) |
| `tests/scripts/scripts-inventory.test.ts` | контракт scripts/tests layout |
| `scripts/gate/run-quiet-check.mjs` | что входит в quiet gate |
| `git status --short` | untracked (`*.bak`, capture artifacts) |

**Deliverable:** таблица «кандидат | класс | риск | действие» (KEEP / DELETE / MERGE / MOVE) — в подтверждённом Plan или в ответе агента; **не** писать `docs/REPO_HYGIENE*.md` без явной просьбы.

---

## Фаза 1 — мёртвый и мусорный код (`src/`)

**Цель:** убрать код, который **не** нужен backend + **не** нужен активному ref (**ref.1**).

**Обязательно проверить перед удалением:**

- Post **UI PURGE v3:** renderer rebuild — **не** восстанавливать legacy shell из git.
- Маршруты refs 2–27: dev-навигация может быть stub; удалять только если нет тест-guard и нет ссылки в `VELORIX_NEON_REFERENCE_SCREEN_RELS`.
- IPC/main/preload: удалять только если `audit:ipc-architecture` + тесты зелёные.

**Типичные кандидаты (проверять, не слепо):**

- Неиспользуемые re-export типов (`audit:dead-type-reexports`).
- Legacy preview scene (towers/car/watermark) если ref.1 capture их не использует.
- Дубли helpers, которые покрывает `audit:copy-paste`.

**Запрещено:** drive-by рефактор вне классифицированного списка.

**Gate:** `npm run check:quiet` + `npm run typecheck` при diff в `src/`.

---

## Фаза 2 — мусорные файлы

**Удалять без согласования (если не в `.gitignore` и не нужны gate):**

- `*.bak`, `*.tmp`, случайные дубликаты (`app-build-info.json.bak`).
- Untracked артефакты capture, если уже в `.neon-ref-visual/` и не запрошены владельцем.

**Проверить перед удалением tracked:**

- `docs/archive/` — **ARCHIVE**, не трогать без явной просьбы.
- `scripts/e2e/import-neon-refs-from-assets.mjs`, `neon-ref-visual-breakdown.mjs`, `neon-ref-visual-display.mjs` — **НЕ orphan** (import + `SCRIPTS_WIRING_EXEMPT`); **KEEP**.
- Любой файл из `SCRIPTS_WIRING_EXEMPT_REL_PATHS` / `audit-manifest.json`.

**Gate:** `npm run check:quiet`.

---

## Фаза 3 — аудит tests (необходимость)

**Классы тестов:**

| Класс | Критерий KEEP | Критерий DELETE/MERGE |
| ----- | ------------- | --------------------- |
| **Gate / guard** | входит в `check:quiet` или ловит регресс ref.1 | дублирует другой guard byte-в-byte |
| **Backend contract** | IPC, ffmpeg, yt-dlp, settings — реальная логика | — |
| **NEON shell stub** | ref N ещё не sign-off; guard route+минимальный DOM | ref sign-off `[x]` и тест не добавляет coverage |
| **Governance lock** | `toolchain-baseline`, `agents-checklist-test-snapshot`, `scripts-inventory` | устаревшие числа без sync с Vitest |
| **One-off / snapshot** | привязан к живому скрипту | скрипт удалён; тест только historical |

**Обязательно для ref.1 era:**

- `neon-processing-shell*.test.ts` (3 файла) — тяжёлые CSS guards; **не** удалять без замены coverage; при merge — один файл + sections.
- `neon-*-shell.test.ts` (×27 refs) — аудит **по ref**: stub vs реальный rebuild.

**Deliverable:** список DELETE с обоснованием; MERGE pairs.

**Gate:** `npm run test` → `npm run check:quiet`.

---

## Фаза 4 — аудит scripts (необходимость)

**Классы:**

| Класс | Примеры | Правило |
| ----- | ------- | ------- |
| **Quiet gate** | `scripts/gate/*` | KEEP; удаление = изменение `run-quiet-check.mjs` |
| **Release** | `scripts/release/*` | KEEP если в `package.json` или release skill |
| **Maint one-shot** | `journal-consolidate`, `apply-terminal-*` | KEEP если npm script или wiring-exempt |
| **Audit info** | `audit:orphan-scripts`, `audit:todo-debt` | KEEP (не в quiet — OK) |
| **Orphan** | нет npm, нет import, нет exempt | DELETE или добавить в inventory + npm |

**Обязательно:** после удаления script — убрать из `package.json`, `scripts-inventory-meta.ts`, `audit-manifest.json`, тестов inventory.

**Gate:** `npm run check:scripts-wiring` + `check:quiet`.

---

## Фаза 5 — rules / skills / docs (дубли, противоречия, сокращение)

### Карта ролей (целевая)

| Артефакт | Роль | Не дублировать |
| -------- | ---- | -------------- |
| `velorix-rules-explicit.mdc` | **Глоссарий** терминов | длинные процедуры |
| `velorix-ref-visual-blocks.mdc` | **Исполняемое** ref-блоки 1:1 | таблицу refs 1–27 |
| `velorix-agent.mdc` | **Исполняемое** agent: git, quiet, UI блокер | полный текст continue skill |
| `velorix-no-git-restore.mdc` | **Блокер** restore | — |
| `velorix-simplicity.mdc` | anti-bloat + legacy delete | — |
| `velorix-core.mdc` | индекс + toolchain | дубли agent |
| `velorix-journal.mdc` / `velorix-checklist.mdc` | globs для MD файлов | — |
| `velorix-react.mdc` / `velorix-electron.mdc` | globs для кода | — |
| Skills | **процедуры** (continue, journal, release, **этот hygiene**, checklist-audit) | копия `.mdc` |
| `AGENTS.md` | **индекс** + 1 экран текста | канон sprint/ref |
| `agent-contract.txt` | SDK краткий контракт | расхождение с agent.mdc |
| `IMPLEMENTATION_NEON_CHECKLIST.md` | sprint + матрица refs | — |
| `SOURCES_OF_TRUTH.md` | иерархия | — |

### Известные расхождения (проверять каждый прогон)

- **Git по J-NNN:** «следующий commit/push» — одно число в: `velorix-agent.mdc`, `velorix-rules-explicit.mdc`, `AGENTS.md`, `agent-contract.txt`, `continue.txt`, `initial.txt` (journal last J → `ceil to %5` / `%10`).
- **Ref-блоки / frozen / overall %:** `velorix-ref-visual-blocks.mdc` = канон; `agent-contract.txt` и `VELORIX_NEON_THEME.md` **синхронизировать** (убрать «layoutMismatchPercent не откат» если заменено на «only active ROI»).
- **snap.3 test counts:** `AGENTS.md` ↔ `IMPLEMENTATION_NEON_CHECKLIST.md` ↔ факт Vitest (`agents-checklist-test-snapshot.test.ts` **не** сверяет с Vitest — обновлять вручную или расширить тест).
- **POST PURGE UI 0%:** не возвращать `[~]` / проценты готовности в checklist.

### Процедура сверки

1. Прочитать все `.cursor/rules/*.mdc` + `.cursor/skills/*/SKILL.md` + `AGENTS.md` + `agent-contract.txt` + `docs/SOURCES_OF_TRUTH.md`.
2. Выписать **дубли** (один смысл в 2+ местах) → оставить **один канон**, остальное → ссылка 1 строкой.
3. Выписать **противоречия** (разные числа, разные запреты) → один commit sync.
4. **Сократить** текст: таблицы + «Запрещено/Обязательно»; убрать повтор глоссария вне `rules-explicit`.
5. **Перенос в skills:** длинные пошаговые workflow (release, checklist audit, **hygiene**, journal) — только в skills; `.mdc` — ссылка + 3–5 строк исполняемого.

**Gates:** `npm run check:rules-explicit` + `check:docs-governance` + `check:quiet`.

**Обязательно при правке Git по J или ref-блоков:** один commit обновляет весь список из [`velorix-checklist.mdc`](../../rules/velorix-checklist.mdc) § sync.

---

## Фаза 6 — финал

- **Удалить все временные артефакты** hygiene (см. § «Временные артефакты») — scripts, scratch-файлы, промежуточные отчёты; `git status --short` чист от one-off.
- Обновить `AGENTS.md` skills list (+ `velorix-repo-hygiene` если ещё не добавлен).
- Обновить `docs/SOURCES_OF_TRUTH.md` строку skills.
- Краткий отчёт владельцу: удалено / оставлено / merged / какие противоречия закрыты / какие временные файлы сняты.
- **Запрещено:** `git push` без явной просьбы.

---

## Анти-паттерны (запрещено)

- «Быстро почистить» без фазы 0.
- Удалить test/script потому что «orphan» без проверки `scripts-inventory-meta`.
- Сократить rules до потери чисел/команд/путей (`check:rules-explicit` упадёт).
- Чистка renderer refs 2–27 во время активного **ref.1** sprint (если владелец не просил).
- Создать one-off script/файл для hygiene и **не удалить** его в конце фазы или в ф.6.