dsh-desktop-kit 0.0.0-stage → 1.0.0

package/skills/design-critique/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: design-critique
+description: "Дизайн-критик: аудит существующего интерфейса по 12 критериям, скриншоты, axe, приоритетные правки «до/после». Использовать для оценки и апгрейда готового UI."
+whenToUse: "Нужно оценить, «почему выглядит дёшево», провести дизайн-ревью страницы/дашборда/формы, сравнить варианты, поднять существующий UI до WOW-уровня."
+user-invocable: true
+---
+
+# DESIGN-CRITIQUE — дизайн-критик
+
+> Ты — строгий, но справедливый арт-директор. Твоя задача — увидеть проблемы, которые не видит автор,
+> и превратить «нормально» в «дорого». Критика всегда конкретная: что вижу → почему плохо → как исправить.
+
+## Когда использовать
+- Пользователь просит: «оцени дизайн», «почему выглядит дёшево», «сделай ревью», «докрути до WOW».
+- Перед сдачей любой UI-работы (второй взгляд на свой же результат).
+- Для сравнения 2–3 вариантов дизайна.
+
+## Процесс (не пропускай шаги)
+
+### 1. Зафиксируй контекст
+Кто пользователь, какая задача экрана, что важнее (скорость / доверие / конверсия / плотность данных)? Без этого
+«красиво» не существует. Запиши 1–2 строки.
+
+### 2. Собери «до»
+Скриншоты текущего состояния:
+```
+node ~/.dsh/skills/wow-design/assets/scripts/capture.mjs <file|url> --name before --out <outdir>
+node ~/.dsh/skills/wow-design/assets/scripts/audit.mjs  <file|url> --out <outdir>
+```
+Нужны: desktop 1440 (light), mobile 390, тёмная тема (если есть). Для живого сайта — URL; для локального файла — путь.
+Смотри PNG глазами через `read_image`.
+
+### 3. Быстрые тесты (10 минут)
+| Тест | Как | Что ловит |
+|---|---|---|
+| 5 секунд | Открыл, отвернулся, посмотрел | Непонятно, что это и куда нажать |
+| Squint test | Прищуриться / блюр 8px | Провалы иерархии, «серую кашу» |
+| Grayscale | Убрать цвет (DevTools) | Всё держится только на цвете, нет структуры |
+| 200% zoom | Увеличить | Мелкий текст, поломки сетки |
+| 390px | Мобильный вьюпорт | Горизонтальный скролл, обрезанные таблицы, мелкие тапы |
+| Tab | Пройти клавиатурой | Нет фокуса, ловушки, неработающие кнопки |
+| Dark | Тёмная тема | Инверсия вместо палитры, нечитаемый контраст |
+
+### 4. Оценка по рубрике
+12 критериев, шкала 1–5, веса; порог 4.4/5 и ни один критерий < 4. Полная рубрика с дескрипторами:
+`~/.dsh/skills/wow-design/references/critique-rubric.md`.
+
+| # | Критерий | Вес |
+|---|---|---|
+| 1 | Первое впечатление / концепция | 15% |
+| 2 | Визуальная иерархия и маршрут взгляда | 12% |
+| 3 | Типографика | 12% |
+| 4 | Цвет и контраст | 10% |
+| 5 | Сетка, выравнивание, ритм | 10% |
+| 6 | Воздух и плотность | 8% |
+| 7 | Компоненты и состояния | 8% |
+| 8 | Консистентность | 7% |
+| 9 | Детали и полировка | 6% |
+| 10 | Адаптив и мобильный | 5% |
+| 11 | Доступность | 4% |
+| 12 | Оригинальность vs польза | 3% |
+
+Считай средневзвешенное. 5 — уровень Linear/Stripe/Apple, 4 — крепкий профессиональный, 3 — «нормально, но без
+характера», 2 — заметно дёшево, 1 — сломано.
+
+### 5. Приоритизируй правки
+- **P0 (блокеры):** нечитаемый контраст, сломанный мобильный, нет иерархии, «AI-slop»-маркеры, нерабочие состояния,
+  критичные axe-нарушения. Без них нельзя сдавать.
+- **P1 (важное):** типографика, воздух, ритм, тени/радиусы, неконсистентные отступы, слабый первый экран.
+- **P2 (полировка):** микродетали, motion, selection/scrollbar/focus, редакционные штрихи.
+
+Каждый пункт: **что вижу (со скриншотом/координатой) → почему проблема → конкретное исправление (значения в px/rem/токенах) → приоритет.**
+Не пиши «сделать современнее». Пиши «H1 48→72px, tracking −0.02em; убрать 3 карточки с иконками, заменить
+редакционным нумерованным списком; радиус карточек 24→14px; добавить 48px воздуха до секции».
+
+### 6. Правки и «после»
+Внеси P0+P1, пересними скриншоты, сравни «до/после», проверь рубрику снова. Если правит другой исполнитель —
+отдай ему список P0/P1 с точными значениями и критериями приёмки.
+
+## Частые диагнозы и лекарства
+
+| Симптом | Диагноз | Лечение |
+|---|---|---|
+| «Выглядит как шаблон» | Нет характера: дефолтные радиусы/цвета/шрифт | 1 signature-деталь, serif display, свой акцент, асимметрия |
+| «Дёшево» | Мало воздуха, всё в рамках, мелкие заголовки | ×1.5–2 к отступам секций, H1 больше на 30–60%, контрастнее иерархия |
+| «Каша» | Нет маршрута взгляда, всего поровну | 1 главный акцент на экран, приглушить второстепенное (muted), убрать лишние рамки |
+| «Серо и скучно» | Только нейтрали, нет тёплого/акцента | 1 акцент + тёплый полутон (медь/терракота), тонкие линии, зерно 2% |
+| «Пёстро» | Много акцентов и цветов | 60-30-10: нейтрали 60%, вторичный 30%, акцент 10% |
+| «Тяжело читать» | Длинная строка, мелкий текст, низкий контраст | 60–72ch, 16–18px body, 1.6 line-height, контраст ≥ 4.5 |
+| «Дёргается» | Анимации ради анимаций, разные easing | Только hover/reveal, 160–260ms, один easing, reduced-motion |
+| «Неудобно» | Нет состояний, мелкие тапы, таблица ломается | states, 44px тапы, `.table-wrap`, явные CTA |
+| «Мобильный ужас» | Десктопный layout сжат | Мобильная композиция: стек, порядок, скрыть декор, sticky CTA |
+
+## Чек-лист доступности (обязательный)
+- [ ] Контраст текста ≥ 4.5:1, крупного ≥ 3:1, иконок/границ ≥ 3:1.
+- [ ] Все интерактивные элементы доступны с клавиатуры, `focus-visible` видим, порядок логичен.
+- [ ] У изображений alt, у иконок-кнопок aria-label, у модалок — focus trap и Escape.
+- [ ] Нет информации только цветом (статусы дублируются текстом/иконкой).
+- [ ] `prefers-reduced-motion` уважается.
+- [ ] axe: 0 critical/serious (если есть — блокер).
+
+## Формат отчёта
+
+```
+# Дизайн-ревью: <объект>
+Контекст: <аудитория, задача>
+Вердикт: SHIP / NEEDS WORK / REDESIGN
+Оценка: <средний балл>/5 (ниже 4: <критерии>)
+Первое впечатление (5 сек): <что понятно/непонятно>
+## P0 — блокеры
+1. <что вижу> → <почему> → <фикс> (скрин: path)
+## P1 — важное
+...
+## P2 — полировка
+...
+Что уже хорошо: <3–5 пунктов — обязательно>
+После правок: <новые скриншоты, повторная оценка>
+```

package/skills/dev-workflow/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: dev-workflow
+description: "Универсальный процесс разработки для любого проекта — этапы, качество, Definition of Done, работа с памятью и командой."
+whenToUse: "Начало любой задачи по коду в любом проекте; чтобы выбрать правильный порядок действий и не забыть проверки."
+user-invocable: true
+---
+
+# Универсальный процесс разработки
+
+## Шаг 0 — триаж навыков (обязательно)
+В начале задачи открой `skills-router`, определи тип работы и загрузи **все** применимые скиллы
+(`requirements-and-planning`, `wow-design`, `seo`, `php-laravel`, `database-safety`, `testing-strategy`,
+`security-review`, `release-and-deploy`, проектные и т.д.). Без этого не начинай разведку и правки.
+
+## Этапы (всегда в этом порядке)
+1. **Разведка:** прочитать память проекта, найти затронутые файлы/маршруты/модели, выявить риски.
+2. **План:** короткий список шагов + критерии приёмки; для крупного — todo/план и команда.
+3. **Бэкап/безопасность:** копия затрагиваемых файлов или git; для БД — дамп; план отката.
+4. **Реализация:** минимальные локальные правки; не менять чужие зоны без причины; соблюдать инварианты.
+5. **Проверки:** линтер + статанализ + тесты (unit/feature) + E2E/UI (если затронут интерфейс) + визуально.
+6. **Ревью:** пройтись по чек-листу (данные, безопасность, тесты, стиль) — см. скилл `code-review-checklist`.
+7. **Документация/версия:** обновить документацию/CHANGELOG, поднять версию по правилам проекта.
+8. **Релиз:** по скиллу `release-and-deploy` (артефакт → проверка → выкатка → smoke → откат при проблеме).
+9. **Память:** записать итог (что сделано, как проверено, риски) в файлы памяти проекта.
+
+## Definition of Done
+- [ ] Применимые скиллы загружены на старте и реально использованы; гейты пройдены (в отчёте перечислены).
+- [ ] Задача решена по критериям; поведение проверено вживую (не только тестами).
+- [ ] Автотесты: существующие зелёные, новые добавлены и падают без правки.
+- [ ] Линтер/статанализ без новых ошибок.
+- [ ] Интерфейс: скриншоты «до/после», светлая/тёмная тема, mobile (если UI).
+- [ ] Нет секретов, отладочного кода и случайных файлов в диффе.
+- [ ] Данные защищены (бэкап/аддитивные миграции), план отката есть.
+- [ ] Документация/версия/память обновлены.
+
+## Принципы
+- Сначала понять — потом менять. Одна задача — один связный дифф.
+- Не ломать чужие зоны; при необходимости — договариваться о границах.
+- Необратимые действия (удаление данных, деплой, публикация) — только с явного разрешения.
+- Если застрял: сузить проблему, собрать факты, написать минимальный репро; см. `debugging-playbook`.
+- Контекст не терять: ключевые факты — в память, длинные сессии — компактить.

package/skills/git-and-ci/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: git-and-ci
+description: "Работа с git и CI — ветки, коммиты, теги, гигиена репозитория, pre-commit проверки и пайплайн."
+whenToUse: "При инициализации репозитория, коммитах, ветках, тегах релизов и настройке CI для любого проекта."
+user-invocable: true
+---
+
+# Git и CI (универсально)
+
+## Репозиторий
+- `.gitignore` до начала работы: зависимости, сборки, секреты (`.env*`), runtime-данные, IDE.
+- Проверять `git status` перед коммитом: не должно быть мусора/секретов/сгенерированных файлов.
+- Не коммитить `vendor/`, `node_modules/`, `public/build`, `storage/`-рантайм, дампы БД, PII.
+
+## Ветки и коммиты
+- `main` — стабильная; работа — в `feature/<кратко>` / `fix/<кратко>`.
+- Коммиты небольшие и атомарные; сообщение — «что и зачем» (например, `feat: ...`, `fix: ...`, `chore: ...`).
+- Не смешивать форматирование и функциональные изменения в одном коммите.
+- Тег релиза: `vX.Y.Z` на проверенном коммите; тег не двигать после публикации.
+
+## Перед коммитом (pre-commit)
+1. Линтер по изменённым файлам.
+2. Статанализ (без новых ошибок).
+3. Тесты (unit/feature; E2E — если UI).
+4. Просмотр диффа целиком: секреты, отладка, случайные файлы.
+
+## CI-пайплайн (этапы)
+1. Checkout + кэш зависимостей.
+2. Установка зависимостей (lock-файл, без интерактива).
+3. Линтер + статанализ.
+4. Тесты на реальной СУБД (сервис-контейнер), с baseline.
+5. Сборка ассетов/compile.
+6. E2E (стенд поднимается в CI) + артефакты при падении (скриншоты/логи).
+7. Сборка релизного артефакта/checksums (по тегу).
+
+## Гигиена истории
+- `git log --oneline`, `git diff main...HEAD` перед ревью.
+- Откат: `git revert` для опубликованного, `git reset` — только для локального.
+- Большие бинарники/дампы — не в git (артефакты/хранилище).
+- Секрет, попавший в историю, считается скомпрометированным — ротировать.

package/skills/pg-upgrade-verify/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pg-upgrade-verify
+description: "Универсальная проверка обновления на копии живой PostgreSQL-базы — до/после без риска для прода."
+whenToUse: "Перед выкаткой любого обновления, которое трогает схему БД, сиды или данные; для доказательства, что данные не потеряны."
+user-invocable: true
+---
+
+# Проверка обновления на копии живой БД (PostgreSQL)
+
+Цель: доказать, что после обновления данные существующей базы не изменились и приложение работает.
+
+## 1. Подготовка
+1. Отдельная БД: `servicedesk_upgrade_test` (никогда не боевая!).
+2. Развернуть **старую** версию кода в отдельную папку (распаковать архив старой версии).
+3. Скопировать `vendor` из рабочей копии (если `composer.lock` совпадает) — так быстрее и без сети.
+4. `.env`: указать `DB_DATABASE=servicedesk_upgrade_test`, `APP_URL=http://localhost`, `APP_KEY` через `php artisan key:generate`.
+5. `php artisan migrate --force` + `db:seed --force` + при наличии `DemoDataSeeder`.
+6. Добавить «живые» данные: по 1–3 строки в ключевые таблицы (tickets, comments, attachments, assets, consumables, stock_moves, kb_articles, activity_logs, ticket_reads).
+
+## 2. Зафиксировать «до»
+```sql
+SELECT 'tickets' t, count(*) FROM tickets UNION ALL SELECT 'users', count(*) FROM users /* ... */;
+SELECT 'tickets_max', max(id)||'/'||max(number) FROM tickets;
+SELECT 'tickets_checksum', md5(string_agg(t::text,'|' ORDER BY id)) FROM tickets t;
+SELECT 'comments_checksum', md5(coalesce(string_agg(c::text,'|' ORDER BY id),'')) FROM ticket_comments c;
+```
+Сохранить в файл (например `_upgrade-before.txt`).
+
+## 3. Имитация обновления
+1. Наложить новый код поверх папки старой версии (`tar -xzf new.tgz -C <папка>`).
+2. `php artisan backup:run` (если используется) — проверить, что копия создалась.
+3. `php artisan migrate --force` (ожидаемо «Nothing to migrate», если миграций нет).
+4. `php artisan db:seed --force`.
+5. Обновить `APP_VERSION` в `.env` (как делает `deploy/update.sh`).
+
+## 4. Зафиксировать «после» и сравнить
+- Повторить SQL из п.2 → сравнить количества и md5 (должны совпасть; допустимый рост — только журналы от самих команд backup/seed).
+- Smoke: `/login` 200, вход, `/tickets` 200 со старыми номерами, `/tickets/{id}/edit` — старые комментарии/вложения видны.
+- `php artisan migrate:status | grep -c Ran` — все миграции Ran.
+
+## 5. Убрать за собой
+- Удалить тестовую БД (`DROP DATABASE servicedesk_upgrade_test`) и папку теста.
+- Артефакты «до/после» — в память/отчёт: `...\memory\projects\<проект>\tests\`.
+- Записать вывод в `SESSIONS.md`.
+
+## Важно
+- Не запускать на боевой БД; не использовать `migrate:fresh`.
+- Если контрольные суммы разошлись — остановиться, не выкатывать, искать причину в миграциях/сидерах.

package/skills/project-deep-dive/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: project-deep-dive
+description: "Глубокий анализ проекта с запоминанием в локальное досье через project_memory: разведка, архитектура, карта кода, инварианты, ловушки, runbook, теги достоверности и честный отчёт."
+whenToUse: "Пользователь просит «глубоко проанализируй / разберись и запомни <проект>», вызвана команда /remember, досье отсутствует или устарело (старый lastAnalyzedAt или другой git HEAD), либо предстоит крупная работа в незнакомом проекте."
+user-invocable: true
+---
+
+# PROJECT-DEEP-DIVE — анализ проекта и запоминание
+
+> Цель: понять проект настолько, чтобы дальше работать в нём без повторной разведки.
+> Результат — досье в `%USERPROFILE%\.dsh\projects-memory\<slug>\` и отчёт: что записано,
+> что проверено, что осталось неясным. Досье хранит выводы и ссылки, а не копии кода.
+
+## 0. Контракт (нарушать нельзя)
+
+1. **Первый вызов — `project_memory(action="status")`**, до чтения файлов проекта: он определяет проект, наличие и свежесть досье.
+2. **Никогда не отправляй содержимое проекта в сеть.** Ни `web_fetch`, ни `web_search`, ни внешние API не получают код, конфиги, пути, имена серверов, фрагменты БД и журналы. Анализ только локальный.
+3. **Никогда не сохраняй секреты и PII.** Пароли, токены, ключи, строки подключения, e-mail, телефоны, ФИО, адреса не попадают ни в досье, ни в журнал. Допустимо указать только имя переменной или файла: «секрет в `.env`, `DB_PASSWORD`».
+4. **Секции пишутся только через `update_section`.** Файлы досье и `INDEX.json` вручную не редактируй — иначе рассинхронизируются индекс и свежесть.
+5. **Финальный ответ обязан перечислить:** какие секции записаны, какие факты проверены, что осталось неясным. Отчёт без пункта «неясно» — признак поверхностного анализа.
+
+## 1. Когда применять
+
+- Просьба «глубоко проанализируй / разберись и запомни <проект>», «составь досье», «введи в курс».
+- Команда `/remember`: объём средний — `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `RUNBOOK`.
+- Перед крупной работой в незнакомом проекте: сначала досье, потом правки (см. `dev-workflow`, `requirements-and-planning`).
+- Досье устарело: `lastAnalyzedAt` старше ~30 дней, `git.head` в INDEX.json не равен текущему `git rev-parse HEAD`, сменилась ветка.
+- Не применять: точечный вопрос по одному файлу; разовая правка при актуальном досье.
+
+## 2. Инструмент project_memory
+
+Сигнатура: `project_memory(action, project?, file?, content?, query?, root?, name?, mode?, maxChars?)`.
+В текущей сборке инструмента у `register` есть также необязательный `stack` — короткое описание стека.
+Хранилище: `%USERPROFILE%\.dsh\projects-memory\<slug>\` — `PROJECT.md`, `ARCHITECTURE.md`, `CODE-MAP.md`, `INVARIANTS.md`, `GOTCHAS.md`, `RUNBOOK.md`, `JOURNAL/YYYY-MM.md`, `INDEX.json`.
+
+| action | Что делает | Обязательные аргументы | Пример |
+|---|---|---|---|
+| `status` | состояние хранилища, досье и свежести | — | `project_memory(action="status")` |
+| `register` | регистрирует проект | `name`, `root` (+ `stack`) | `project_memory(action="register", name="my-app", root="C:\work\my-app", stack="Laravel 13 / PostgreSQL")` |
+| `list` | список проектов | — | `project_memory(action="list")` |
+| `read` | читает файл досье | `project`, `file` | `project_memory(action="read", project="my-app", file="ARCHITECTURE", maxChars=8000)` |
+| `search` | ищет по досье перед записью | `query` | `project_memory(action="search", project="my-app", query="очереди")` |
+| `append_journal` | дописывает сессию в `JOURNAL/YYYY-MM.md` | `project`, `content` | `project_memory(action="append_journal", project="my-app", content="...")` |
+| `update_section` | записывает секцию досье | `project`, `file`, `content`, `mode` | `project_memory(action="update_section", project="my-app", file="ARCHITECTURE", content="...", mode="replace")` |
+
+- `file` — только `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `INVARIANTS`, `GOTCHAS`, `RUNBOOK`, `JOURNAL`.
+- `mode` — `replace` (секция перезаписывается целиком, по умолчанию) или `append` (дописать в конец).
+- `maxChars` — ограничение вывода `read` (500–30000, по умолчанию 12000); целиком досье не выкачивай.
+- `root` — абсолютный путь к корню проекта; `name` — slug в kebab-case (`service-desk`); `stack` — короткое описание стека при `register`.
+- `project` по умолчанию — проект текущей сессии; чужой проект указывай явно.
+- `content` — markdown секции по каркасам из §4.
+
+## 3. Процесс (8 шагов)
+
+### Шаг 1. Статус и проект
+`project_memory(action="status")`.
+- Проект найден — запомни slug и переходи к Шагу 2.
+- Нет проекта — `project_memory(action="register", name="<slug>", root="<абсолютный путь>")`.
+- Несколько кандидатов или непонятно, о каком проекте речь, — **спроси пользователя**, не угадывай.
+- Досье устарело — предупреди сразу; устаревшие факты в новых секциях помечай `[устарело]`.
+
+### Шаг 2. Что уже известно
+Прочитай существующие секции (`read` с `maxChars=6000–8000`). Цель — не дублировать и не противоречить.
+Новый факт спорит со старым — перепроверь по коду: победивший запиши, проигравший пометь `[устарело]`.
+
+### Шаг 3. Разведка (только чтение)
+Источники по порядку: `AGENTS.md` → `README*` → манифесты → структура каталогов → git.
+```powershell
+$root = "C:\path\to\project"
+git -C $root rev-parse --abbrev-ref HEAD; git -C $root rev-parse --short HEAD
+git -C $root log -5 --oneline; git -C $root status --short
+rg --files $root -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!.git' | Select-Object -First 300
+Get-ChildItem $root -Name
+```
+Манифесты и конфиги: `composer.json`, `package.json`, `pnpm-workspace.yaml`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `docker-compose.yml`, `Dockerfile`, `Makefile`, `.env.example`, `phpunit.xml`, `vite.config.*`, `tsconfig.json`.
+Дальше — `references/recon-commands.md` (рецепты для Laravel/PHP, JS/TS, Bitrix, generic).
+
+### Шаг 4. Трассировка потоков
+Веди цепочку «точка входа → маршрут → обработчик → домен → данные → тесты». Команды:
+```powershell
+rg -n "Route::|router\.|app\.(get|post)|urlpatterns" $root -g '!node_modules' -g '!vendor'
+rg --files $root | rg "migrations|schema|models|entities"
+rg -n "class \w+(Service|Controller|Handler|Repository)\b" $root -g '!vendor' -g '!node_modules'
+rg -n "process\.env|config\(|ENV\[|getenv\(" $root -g '!node_modules' -g '!vendor'
+rg --files $root | rg "(^|/)(tests?|spec|__tests__|phpunit|playwright)/"
+```
+Фиксируй не всё подряд, а то, что объясняет: как запустить, где бизнес-логика, где данные, что легко сломать.
+
+### Шаг 5. Сборка секций
+Порядок записи: `PROJECT` → `ARCHITECTURE` → `CODE-MAP` → `INVARIANTS` → `GOTCHAS` → `RUNBOOK`.
+Каждая секция — отдельный `update_section`; после записи прочитай её обратно (`read`).
+
+| Секция | Минимум | Обязательные блоки |
+|---|---|---|
+| `PROJECT` | 8–15 строк | назначение; стек и версии; где лежит (копия, прод); запуск; статус |
+| `ARCHITECTURE` | 15+ строк | компоненты и границы; точки входа; поток данных; внешние зависимости; ключевые решения |
+| `CODE-MAP` | 10+ записей | область → путь → зачем; сервисы; конфиги; тесты |
+| `INVARIANTS` | 5+ правил | правило → почему → как проверить → ссылка `path:line` |
+| `GOTCHAS` | 3+ ловушки | симптом → причина → обход |
+| `RUNBOOK` | 5+ команд | запуск; тесты; сборка; деплой и откат; бэкап; диагностика |
+
+Малый проект (один скрипт/сервис) — минимумы пропорционально ниже, но блоки те же. Подробные каркасы — `references/section-templates.md`.
+
+### Шаг 6. Метки достоверности и ссылки
+- `[проверено]` — прочитано в файле или подтверждено выводом команды; рядом ссылка `path:line`.
+- `[выведено]` — логический вывод (соглашение фреймворка, косвенная связь); прямого источника в коде нет.
+- `[устарело]` — было верно в прошлой версии/ветке; требует перепроверки.
+- Ссылка — всегда `относительный/путь:строка`; копировать код, логи и дампы в досье нельзя.
+
+### Шаг 7. Журнал
+Значимую сессию зафиксируй `append_journal` (сжато, по шаблону из `project-memory-maintenance`): что анализировали, что выяснили, какие решения, что осталось.
+
+### Шаг 8. Отчёт пользователю
+```markdown
+## Записано в досье
+- PROJECT — ...
+- ARCHITECTURE — ...
+
+## Проверено
+- [проверено] ... (path:line)
+
+## Неясно / требует проверки
+1. ...
+2. ...
+
+## Дальше
+- ...
+```
+Перечисли **каждую** записанную секцию и **каждый** неясный пункт. Не замалчивай сомнения.
+
+## 4. Каркасы секций (сжато)
+
+- `PROJECT`: что делает; стек и версии; репозиторий и прод; как поднять; статус и владелец.
+- `ARCHITECTURE`: слои и модули; поток данных текстом; очереди/крон; внешние сервисы; ключевые решения.
+- `CODE-MAP`: таблица «область | путь | зачем»; точки входа; модели/схема; тесты; конфиги.
+- `INVARIANTS`: нумерованные «нельзя», каждое с причиной и способом проверки.
+- `GOTCHAS`: симптом → причина → обход; отдельная ловушка — отдельный пункт.
+- `RUNBOOK`: окружение; установка; запуск; тесты; сборка; деплой; откат; бэкап; где логи.
+
+Полные шаблоны с примерами — `references/section-templates.md`.
+
+## 5. Гейт качества (перед сдачей)
+
+- [ ] `status` вызван первым, проект определён (slug зафиксирован).
+- [ ] Существующие секции прочитаны, дублей нет.
+- [ ] Каждая записанная секция отправлена отдельным `update_section` и прочитана обратно.
+- [ ] Секретов и PII нет: перечитанный текст не содержит значений паролей/токенов/персональных данных.
+- [ ] У ключевых утверждений есть метка достоверности и ссылка `path:line`.
+- [ ] Код и логи не скопированы в досье.
+- [ ] Минимумы по объёму соблюдены; каждая секция ≤ 40 KB.
+- [ ] Противоречия разобраны; устаревшее помечено `[устарело]`.
+- [ ] Отчёт содержит «Записано» и «Неясно».
+- [ ] В сеть ничего из проекта не уходило.
+
+## 6. Антипаттерны
+
+- Копировать целые файлы, конфиги, миграции и логи «чтобы было».
+- Сохранять `.env`, дампы, токены, персональные данные.
+- Отправлять код/конфиги в веб-поиск или внешние API «для уточнения».
+- Писать «очевидно», «скорее всего» без метки `[выведено]`.
+- Заполнять шаблон пунктами без доказательств.
+- Править файлы досье и `INDEX.json` руками.
+- Начинать анализ без `status`.
+- Оставлять старые факты без пометки и заявлять о свежести досье.
+- Складывать всё в одну гигантскую секцию вместо ссылок на файлы.
+
+## 7. Связанное
+
+- Постоянное ведение памяти — `project-memory-maintenance` (журнал, дедупликация, свежесть).
+- Процесс разработки — `dev-workflow`; планирование — `requirements-and-planning`; финальное ревью — `code-review-checklist`.

package/skills/project-deep-dive/references/recon-commands.md

@@ -0,0 +1,78 @@
+# Разведка проекта: команды и источники
+
+> Только чтение. Ничего не запускай на изменение (миграции, seed, деплой, install) ради досье.
+> Если `rg` нет — используй инструменты `glob`/`grep` или `Get-ChildItem -Recurse`.
+> Значения `.env` не читай: имена переменных бери из `.env.example` или из кода.
+
+## 0. Подготовка
+```powershell
+$root = "C:\path\to\project"     # абсолютный путь, проверить Test-Path
+Test-Path (Join-Path $root "AGENTS.md")
+Test-Path (Join-Path $root ".git")
+```
+
+## 1. Универсальный минимум (любой стек)
+```powershell
+Get-ChildItem $root -Name
+git -C $root rev-parse --abbrev-ref HEAD
+git -C $root rev-parse --short HEAD
+git -C $root log -5 --oneline
+git -C $root status --short
+rg --files $root -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!.git' | Select-Object -First 300
+```
+- `AGENTS.md` — правила работы в проекте (читать первым).
+- `README*`, `docs/`, `CONTRIBUTING*` — заявленный процесс; проверяй кодом, а не верь на слово.
+- Манифесты: `composer.json`, `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Dockerfile`, `docker-compose.yml`, `Makefile`, `.env.example`.
+- CI: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` — какие проверки реально гоняются.
+
+## 2. Laravel / PHP
+```powershell
+rg -n "Route::|->group\(|middleware\(" routes app -g '*.php'
+rg -n "class \w+Controller|class \w+Service|class \w+Repository|function handle" app -g '*.php'
+php artisan about            # безопасно: версии и окружение
+php artisan route:list --except-vendor
+php artisan migrate:status
+rg --files database/migrations
+rg -n "validate\(|Validator::|FormRequest|authorize\(" app -g '*.php'
+rg -n "DB::transaction|lockForUpdate|queue|dispatch\(" app -g '*.php'
+rg --files tests; rg -n "class \w+Test" tests -g '*.php'
+```
+- Модули/провайдеры: `config/`, `app/Providers/`, `bootstrap/app.php` (Laravel 11+).
+- Тесты: `php artisan test`, `php scripts/test.php`, `make test` — фиксируй команду из README/AGENTS, но не запускай полный прогон ради анализа.
+- Не выполняй `migrate:fresh`, `db:wipe`, `db:seed`, `config:cache` и прочие изменяющие команды.
+
+## 3. JS / TS (Node, React, Vite, Next)
+```powershell
+Get-Content (Join-Path $root "package.json") -Raw | ConvertFrom-Json | Select-Object -ExpandProperty scripts
+rg -n "process\.env\.|import\.meta\.env\." $root -g '!node_modules' -g '*.{ts,tsx,js,jsx}'
+rg --files $root -g '!node_modules' | rg "(^|/)(src|app|pages|routes|components|store|lib|services)/"
+rg -n "createRoot|Router|createBrowserRouter|NextPage|defineConfig" $root -g '!node_modules' -g '!dist'
+rg --files $root -g '!node_modules' | rg "\.(test|spec)\.(ts|tsx|js|jsx)$"
+```
+- Точки входа: `src/main.*`, `src/index.*`, `app/layout.*`, `pages/api/`.
+- Сборка/проверки: скрипты `build`, `lint`, `typecheck`, `test` из `package.json`.
+
+## 4. Bitrix / Aspro
+- Файлы сайта обычно только на сервере: фиксируй, что локально есть (`local/`, `bitrix/templates/aspro-*`), а что нет.
+- `local/php_interface/init.php`, `local/templates/<шаблон>/`, `bitrix/templates`, компоненты `local/components`, инфоблоки — по названиям и вызовам.
+- Не трогай ядро `bitrix/`; не запускай агенты, кеш-сбросы, обновления без разрешения.
+
+## 5. Python / Go / прочее
+- Python: `pyproject.toml`, `manage.py` (Django), `main.py`, роуты Flask/FastAPI (`@app.get`, `APIRouter`), `alembic/versions`.
+- Go: `go.mod`, `main.go`, `internal/`, `cmd/`, `*_test.go`.
+
+## 6. Свежесть и git
+```powershell
+git -C $root rev-parse --abbrev-ref HEAD
+git -C $root rev-parse HEAD
+git -C $root log -1 --format="%h %ad %s" --date=short
+git -C $root tag --sort=-v:refname | Select-Object -First 5
+```
+- Сравни с `INDEX.json` досье (`status`): другой `git.head`/ветка — досье устарело.
+- `lastAnalyzedAt` старше ~30 дней — предупреди пользователя.
+
+## 7. Что считать `[проверено]`
+- Прочитал файл и увидел реализацию — да, со ссылкой `path:line`.
+- Запустил безопасную read-only команду (`git`, `route:list`, `--version`) и увидел вывод — да.
+- Вывел из соглашений фреймворка без прямого источника — только `[выведено]`.
+- Изменил проект ради проверки — так делать нельзя: досье не повод править код.

package/skills/project-deep-dive/references/section-templates.md

@@ -0,0 +1,102 @@
+# Шаблоны секций досье
+
+> Правило: ссылки `path:line` вместо кода; метка достоверности у ключевых утверждений;
+> объём секции ≤ 40 KB; содержимое — выводы, а не дампы.
+> Примеры ниже — образец формы, а не текст для копирования.
+
+## PROJECT
+```markdown
+## Назначение
+- ... [проверено] (README.md:3)
+## Стек и версии
+- PHP 8.5, Laravel 13, PostgreSQL 18 (composer.json:8, .env.example:1)
+## Где лежит
+- Рабочая копия: C:\... ; прод: <сервер>, <путь> [выведено]
+## Запуск
+- ... (README.md:15)
+## Статус и владелец
+- ... [проверено]/[устарело]
+```
+Минимум 8–15 строк: назначение, стек, расположение, запуск, статус.
+
+## ARCHITECTURE
+```markdown
+## Компоненты и границы
+- <модуль> — отвечает за ..., границы: ... (modules/X/..., app/...)
+## Точки входа
+- HTTP: routes/... ; CLI: ... ; крон: ...
+## Поток данных
+1. запрос -> middleware -> контроллер (path:line) -> сервис (path:line) -> БД
+## Внешние зависимости
+- ... [проверено] (config/services.php:12)
+## Ключевые решения
+- Почему так: ... [выведено] / подтверждено тестом (tests/...:40)
+```
+15+ строк; если схема сложная — текстом или mermaid-блоком, без копий кода.
+
+## CODE-MAP
+```markdown
+| Область | Путь | Зачем |
+|---|---|---|
+| HTTP-маршруты | routes/web.php:1 | публичные и админ-маршруты |
+| Бизнес-логика | app/Services/...:1 | ... |
+| Модели/схема | app/Models, database/migrations | ... |
+| UI | resources/views, themes/... | ... |
+| Тесты | tests/Feature/... | ... |
+| Конфиги | config/... | ... |
+```
+10+ записей; для каждого пути — назначение, а не пересказ кода.
+
+## INVARIANTS
+```markdown
+1. Миграции только аддитивные; старые не редактировать.
+   - Почему: прод обновляется поверх живой БД.
+   - Проверка: git diff database/migrations в релизе.
+   - Источник: AGENTS.md:42 [проверено]
+```
+5+ пунктов; одно правило — один номер; обязательно «почему» и «как проверить».
+
+## GOTCHAS
+```markdown
+### <симптом одной строкой>
+- Симптом: ... [проверено] (path:line)
+- Причина: ...
+- Обход: ...
+- Риск, если игнорировать: ...
+```
+3+ ловушки; никаких «на всякий случай» — только реально встреченные или доказанные кодом.
+
+## RUNBOOK
+Разделы: `## Окружение`, `## Установка`, `## Запуск`, `## Тесты`, `## Сборка`, `## Деплой и откат`, `## Бэкап`, `## Диагностика`.
+Команды — отдельными блоками PowerShell по разделу, например:
+
+    # установка
+    ...
+    # тесты
+    ...
+
+5+ команд; команды копируй из README/AGENTS/CI, а не сочиняй; для опасных — пометка «не запускать на проде».
+
+## Отчёт пользователю (обязательная форма)
+```markdown
+## Записано в досье
+- PROJECT — <сколько фактов/строк, что главное>
+- ARCHITECTURE — ...
+- CODE-MAP — ...
+- INVARIANTS — ...
+- GOTCHAS — ...
+- RUNBOOK — ...
+
+## Уверенность
+- [проверено]: ключевые факты — <перечислить>
+- [выведено]: <что выведено и почему>
+- [устарело]: <что требует перепроверки>
+
+## Неясно / требует проверки
+1. <вопрос> — как проверить
+2. ...
+
+## Дальше
+- <следующий шаг>
+```
+Не сокращай «Неясно» до одной фразы и не прячь её в конце.