dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/project-deep-dive/references/tool-and-process.md

@@ -0,0 +1,86 @@
+# API project_memory и детали анализа
+
+> Часть навыка project-deep-dive. ≈2 950 токенов. Читать, когда: нужны полная таблица действий и аргументов, детали шагов анализа, форма отчёта или антипаттерны.
+
+## 1. Хранилище и API
+
+Хранилище: `%USERPROFILE%\.dsh\projects-memory\<slug>\` — `PROJECT.md`, `ARCHITECTURE.md`, `CODE-MAP.md`, `INVARIANTS.md`, `GOTCHAS.md`, `RUNBOOK.md`, `JOURNAL/YYYY-MM.md`, `INDEX.json`.
+
+Сигнатура: `project_memory(action, project?, file?, content?, query?, root?, name?, mode?, maxChars?)`. В текущей сборке у `register` есть необязательный `stack` — короткое описание стека.
+
+| 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 секции по каркасам из `section-templates.md`.
+- `append_journal` сам выбирает `JOURNAL/YYYY-MM.md` по текущему месяцу.
+- `update_section` — единственный способ писать секции; `INDEX.json` руками не правь — иначе рассинхронизируются индекс и свежесть.
+
+## 2. Детали восьми шагов
+
+1. **Статус и проект.** `status` до чтения файлов. Проект найден — запомни slug. Нет проекта — `register`. Несколько кандидатов или непонятно, о каком проекте речь, — **спроси пользователя**, не угадывай. Досье устарело — предупреди сразу; устаревшие факты в новых секциях помечай `[устарело]`.
+2. **Что уже известно.** Прочитай существующие секции (`read`, `maxChars` 6000–8000), чтобы не дублировать и не противоречить. Новый факт спорит со старым — перепроверь по коду: победивший запиши, проигравший пометь `[устарело]`.
+3. **Разведка (только чтение).** Источники по порядку: `AGENTS.md` → `README*` → манифесты → структура каталогов → git. Манифесты и конфиги: `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`. Рецепты — `recon-commands.md`. Не запускай миграции, seed, деплой, install и другие изменяющие команды.
+4. **Трассировка потоков.** Веди цепочку «точка входа → маршрут → обработчик → домен → данные → тесты». Фиксируй не всё подряд, а то, что объясняет: как запустить, где бизнес-логика, где данные, что легко сломать. Команды — `recon-commands.md`.
+5. **Сборка секций.** Порядок: `PROJECT` → `ARCHITECTURE` → `CODE-MAP` → `INVARIANTS` → `GOTCHAS` → `RUNBOOK`. Каждая секция — отдельный `update_section`; после записи прочитай её обратно (`read`). Минимумы: `PROJECT` 8–15 строк, `ARCHITECTURE` 15+, `CODE-MAP` 10+ записей, `INVARIANTS` 5+, `GOTCHAS` 3+, `RUNBOOK` 5+ команд. Малый проект — минимумы пропорционально ниже, блоки те же.
+6. **Метки достоверности.** `[проверено]` — прочитано в файле или подтверждено выводом команды, рядом `path:line`. `[выведено]` — логический вывод (соглашение фреймворка, косвенная связь), прямого источника нет. `[устарело]` — было верно в прошлой версии/ветке, требует перепроверки. Ссылка — `относительный/путь:строка`; копировать код, логи и дампы нельзя.
+7. **Журнал.** Значимую сессию зафиксируй `append_journal` (сжато, по шаблону навыка `project-memory-maintenance`): что анализировали, что выяснили, какие решения, что осталось.
+8. **Отчёт.** Не пропускай «Неясно»: перечисли каждую записанную секцию, каждый проверенный факт со ссылкой и каждый неясный пункт.
+
+## 3. Каркасы секций (сжато)
+
+- `PROJECT`: что делает; стек и версии; репозиторий и прод; как поднять; статус и владелец.
+- `ARCHITECTURE`: слои и модули; поток данных текстом; очереди/крон; внешние сервисы; ключевые решения.
+- `CODE-MAP`: таблица «область | путь | зачем»; точки входа; модели/схема; тесты; конфиги.
+- `INVARIANTS`: нумерованные «нельзя», каждое с причиной и способом проверки.
+- `GOTCHAS`: симптом → причина → обход; отдельная ловушка — отдельный пункт.
+- `RUNBOOK`: окружение; установка; запуск; тесты; сборка; деплой; откат; бэкап; где логи.
+
+Полные шаблоны с примерами — `section-templates.md`.
+
+## 4. Форма отчёта
+
+```markdown
+## Записано в досье
+- PROJECT — ...
+- ARCHITECTURE — ...
+
+## Проверено
+- [проверено] ... (path:line)
+
+## Неясно / требует проверки
+1. ...
+2. ...
+
+## Дальше
+- ...
+```
+
+## 5. Антипаттерны
+
+- Копировать целые файлы, конфиги, миграции и логи «чтобы было».
+- Сохранять `.env`, дампы, токены, персональные данные.
+- Отправлять код/конфиги в веб-поиск или внешние API «для уточнения».
+- Писать «очевидно», «скорее всего» без метки `[выведено]`.
+- Заполнять шаблон пунктами без доказательств.
+- Править файлы досье и `INDEX.json` руками.
+- Начинать анализ без `status`.
+- Оставлять старые факты без пометки и заявлять о свежести досье.
+- Складывать всё в одну гигантскую секцию вместо ссылок на файлы.
+
+## 6. Связанное
+
+- Постоянное ведение памяти — `project-memory-maintenance` (журнал, дедупликация, свежесть).
+- Процесс разработки — `dev-workflow`; планирование — `requirements-and-planning`; финальное ревью — `code-review-checklist`.

package/skills/project-memory-maintenance/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: project-memory-maintenance
+description: "Ведение памяти проектов через project_memory: журнал сессий, секции досье, дедупликация, лимиты, свежесть INDEX.json."
+whenToUse: "После значимой сессии (до ответа), при изменении архитектуры/инвариантов/команд, найденной ловушке, устаревании досье, просьбе «запомни это»."
+user-invocable: true
+---
+
+# Project-memory-maintenance
+
+## 0. Контракт
+1. Журнал — после значимой сессии, до ответа.
+2. В секции — долговечное; ход работы — в журнал.
+3. Перед записью `search`; дубликат — в существующий.
+4. Секреты, PII, код, дампы — не в досье, журнале, `INDEX.json`.
+5. Только `project_memory`; файлы не правь.
+
+## 1. Что значимо и API
+- Значимо: код/схема, решение, исправленный баг с проверкой, инвариант/ловушка, деплой, deep-dive; тривиальное — нет (сомневаешься — короткая запись).
+- API: `project_memory(...)`; `file` — секция, `mode` — replace/append, `maxChars` 500–30000.
+
+## 2. Конец сессии
+1. `status` — проект/свежесть.
+2. `search` 1–3 темы с синонимами (`maxChars=4000`).
+3. `append_journal` в `JOURNAL/YYYY-MM.md`; связанные шаги — одна запись.
+4. `update_section` — только долговечное, одна секция — один вызов.
+5. `read` 1–2 секции, гейт, отчёт.
+
+## 3. Журнал
+`## YYYY-MM-DD — <сессия>` + 5 пунктов: делали, выявили, решения, проверки, осталось; все обязательны (пусто — «нет»), 1–3 строки. Без кода/логов/дампов/чата; «выявили» — факты, «проверки» — запуски и результат, «осталось» — шаги/риски. Секреты: «ошибка с DB_PASSWORD (значение не сохранено)».
+
+## 4. Секции
+`PROJECT` — стек/пути/прод/статус (не история); `ARCHITECTURE` — компоненты/потоки (не алгоритмы); `CODE-MAP` — модули/маршруты (не код); `INVARIANTS` — жёсткие правила (не советы); `GOTCHAS` — ловушки с симптомом (не банальности); `RUNBOOK` — команды/деплой (не архитектура); `JOURNAL` — сессии (не дампы/секреты).
+
+`append` — добавить, `replace` — перестроить (сначала `read`). Один факт — одно место; в двух секциях — `path:line`.
+
+## 5. Дедупликация и лимиты
+1–3 термина (модуль, команда, ошибка, синонимы); `search` каждый; найдено — `read` + дополни, нет — добавь; после — `read`: дубля, секрета, мёртвой ссылки нет.
+Секция ≤ 40 KB; пункт 1–3 строки; детали — `docs`/README, в секции `path:line`. Раздуто — вынеси, оставь ссылки; журнал по месяцам, повторяющиеся выводы — в секции.
+
+## 6. Свежесть и INDEX.json
+`INDEX.json` — машинный, руками нельзя. `lastAnalyzedAt` — только полный анализ; `git.branch`/`head` — на чём; `confidence` — высокая/средняя/низкая по `[проверено]`/смеси/`[устарело]`.
+`status` в начале; branch/HEAD разошлись — устарело: перечитай, обнови, старое помечай. Полный анализ — коммит в отчёт; частичная правка не выглядит полной. `confidence` — по тегам. Расхождение `status` — в отчёт, файл не правь.
+
+## 7. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
+|---|---|---|
+| API, чек-лист, антипаттерны | `references/api-and-checklist.md` | ≈2 600 |
+| Журнал: шаблон | `references/journal-template.md` | ≈1 100 |
+| Правила секций | `references/section-rules.md` | ≈1 750 |
+
+## 8. Гейт перед сдачей
+- [ ] `status`; проект; `search` до записи, дублей нет.
+- [ ] JOURNAL дописан (5 пунктов); досье обновлено; `git.head` сверен; старое помечено.
+- [ ] Нет секретов/PII/кода; теги/`path:line`; ≤ 40 KB.
+- [ ] В отчёт — что записано.

package/skills/project-memory-maintenance/references/api-and-checklist.md

@@ -0,0 +1,99 @@
+# API, критерии, лимиты и чек-лист памяти
+
+> Часть навыка project-memory-maintenance. ≈2 600 токенов. Читать, когда: нужны полная таблица `project_memory`, критерии значимой сессии, лимиты, свежесть `INDEX.json`, финальный чек-лист или антипаттерны.
+
+## 1. API
+
+Сигнатура: `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` | в начале и в конце сессии | — |
+| `list` | если нужно найти проект | — |
+| `read` | перед правкой секции | `project`, `file`, `maxChars` |
+| `search` | перед любой записью (дедуп) | `project`, `query`, `maxChars` |
+| `append_journal` | после сессии | `project`, `content` |
+| `update_section` | долговечный факт | `project`, `file`, `content`, `mode` |
+| `register` | новый проект | `name`, `root` (+ `stack`) |
+
+- `file` — `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `INVARIANTS`, `GOTCHAS`, `RUNBOOK`, `JOURNAL`.
+- `mode` — `replace` (по умолчанию) или `append`.
+- `project` по умолчанию — проект текущей сессии; при работе с чужим проектом указывай slug явно.
+- `maxChars` ограничивает вывод `read` (500–30000, по умолчанию 12000); не выкачивай досье целиком без нужды.
+- `root` — абсолютный путь, `name` — slug в kebab-case, `stack` — короткое описание стека.
+- `append_journal` пишет в `JOURNAL/YYYY-MM.md` текущего месяца; `update_section` — единственный способ писать секции.
+
+## 2. Что считать значимой сессией
+
+Да:
+- изменение кода/конфига/схемы данных;
+- архитектурное или продуктовое решение;
+- найденная и исправленная ошибка, подтверждённая проверкой;
+- новый инвариант или ловушка, которые должны пережить сессию;
+- деплой, откат, смена окружения или команд запуска;
+- глубокий анализ проекта (`project-deep-dive`).
+
+Нет:
+- тривиальный вопрос, чтение файла без выводов;
+- повторное обсуждение уже записанного;
+- неудачная попытка без нового знания.
+
+Сомневаешься — пиши короткую запись в журнал: лишняя строка дешевле потерянного знания.
+
+## 3. Дедупликация, лимиты, свежесть
+
+Дедупликация:
+1. Сформулируй 1–3 термина по теме (имя модуля, команда, текст ошибки, синонимы: «очереди/jobs/queue»).
+2. По каждому: `project_memory(action="search", project="<slug>", query="<термин>", maxChars=4000)`.
+3. Нашёл — `read` секцию и дополни существующий пункт; не создавай второй.
+4. Не нашёл — добавь новый пункт.
+5. После записи — `read` секцию: дубля нет, секрета нет, ссылка существует.
+
+Лимиты:
+- Каждая секция ≤ 40 KB. Приближаешься к лимиту — сокращай до выводов и ссылок.
+- 1 пункт — 1–3 строки; без воды, повторов и пересказа кода.
+- Подробности, таблицы и длинные списки — в reference-файлы проекта (`docs/`, `references/`, README); в секции — ссылка `path:line`.
+- `JOURNAL/` уже разделён по месяцам: не раздувай месяц, повторяющиеся выводы своди в секции.
+- Раздутая секция — признак того, что в досье тащат детали реализации; перенеси их в проект и оставь ссылки.
+
+Свежесть и `INDEX.json`:
+- `INDEX.json` — машинный файл хранилища; вручную не редактируется.
+- `lastAnalyzedAt` — когда досье проанализировано целиком (а не косметически поправлено).
+- `git.branch`, `git.head` — ветка и коммит, на которых сделан анализ.
+- `confidence` — сводная уверенность: высокая при ключевых `[проверено]`, средняя при смеси, низкая при заметном `[устарело]`.
+- В начале сессии `status`; сравни `git.head`/ветку с текущими: `git -C <root> rev-parse --abbrev-ref HEAD` и `git -C <root> rev-parse --short HEAD`.
+- Расходятся — досье устарело: перечитай затронутые секции, обнови факты, старые пометь `[устарело]`.
+- Полный анализ (`project-deep-dive`) — в отчёте укажи, на каком коммите он сделан; частичная правка не должна выглядеть как полный анализ.
+- `confidence` повышай только новыми `[проверено]`; понижай при `[устарело]` и большом объёме `[выведено]`.
+- Если после записи `status` показывает неактуальные поля — это расхождение инструмента: зафиксируй в отчёте, но `INDEX.json` руками не правь.
+
+## 4. Финальный чек-лист
+
+- [ ] `status` вызван, проект определён.
+- [ ] `search` был до записи, дублей нет.
+- [ ] Журнал записан по шаблону, все пять пунктов на месте.
+- [ ] Секции обновлены только долговечными фактами.
+- [ ] Секретов, PII и копий кода нет.
+- [ ] У ключевых утверждений метка `[проверено]`/`[выведено]`/`[устарело]` и ссылка `path:line`.
+- [ ] Секции ≤ 40 KB; детали вынесены в references.
+- [ ] Свежесть в порядке: `git.head` соответствует анализу, устаревшее помечено.
+- [ ] Пользователю перечислено, что записано.
+
+## 5. Антипаттерны
+
+- Писать в досье после каждого шага: журнал — да, секции — нет.
+- Дублировать один факт в нескольких секциях и журнале.
+- Копировать код, логи, дампы, переписку.
+- Секреты и PII в журнале («пароль ...», «токен ...»).
+- Править файлы досье и `INDEX.json` руками.
+- Превращать `PROJECT.md` в дневник.
+- Заявлять полный анализ после косметической правки.
+- Раздувать секцию до огромного размера вместо ссылок.
+- Записывать одноразовые детали, которые не переживут сессию.
+
+## 6. Связанное
+
+- Первичный анализ проекта — `project-deep-dive`.
+- Процесс разработки — `dev-workflow`; финальное ревью — `code-review-checklist`.

package/skills/project-memory-maintenance/references/journal-template.md

@@ -0,0 +1,50 @@
+# Шаблон журнала проекта
+
+> Часть навыка project-memory-maintenance. ≈1 100 токенов. Читать, когда: нужен точный шаблон записи, требования к пяти пунктам, пример или антипримеры.
+
+Журнал — хронология значимых сессий. Файл: `JOURNAL/YYYY-MM.md` (месяц определяется датой записи).
+Пишется действием `append_journal`, не вручную.
+
+## Точный шаблон
+
+```markdown
+## YYYY-MM-DD — <краткое название сессии>
+- Что делали: ...
+- Что выявили: ...
+- Решения: ...
+- Проверки: ...
+- Осталось: ...
+```
+
+## Требования к записи
+
+| Пункт | Что писать | Объём |
+|---|---|---|
+| Что делали | конкретные действия и затронутые области | 1–3 строки |
+| Что выявили | факты, меняющие понимание проекта: причины, зависимости, ловушки | 1–3 строки |
+| Решения | что выбрали и почему (альтернативу — одной фразой) | 1–3 строки |
+| Проверки | что запускалось и результат: тесты, линтер, сборка, ручной сценарий | 1–3 строки |
+| Осталось | следующие шаги, риски, открытые вопросы | 1–3 строки, «нет» допустимо |
+
+- Все пять пунктов обязательны; пустой пункт не удаляй, пиши «нет».
+- Ссылки на файлы — `path:line`, без копий кода и логов.
+- Секреты и PII вырезаются: «ошибка с `DB_PASSWORD` (значение не сохранено)».
+- Одна сессия — одна запись. Продолжение в тот же день — дополняй последнюю запись или пиши отдельную с пометкой «продолжение».
+
+## Пример
+
+```markdown
+## 2026-11-04 — разбор очередей и деплоя
+- Что делали: прочитали `config/queue.php`, `app/Jobs/*`, CI-пайплайн; проверили команды запуска.
+- Что выявили: воркер запускается только на проде через systemd, локально очередь работает в sync-режиме; ретраи не настроены.
+- Решения: в досье зафиксировали как ловушку; локальные тесты очередей требуют `QUEUE_CONNECTION=database`.
+- Проверки: `php artisan queue:work --once` на тестовой БД — успешно; PHPUnit — 42 теста зелёные.
+- Осталось: проверить поведение при падении воркера; уточнить таймаут ретраев у владельца.
+```
+
+## Антипримеры
+
+- «Сделали задачу» — что именно, где, чем проверено, что осталось.
+- Копия вывода тестов на 100 строк — оставь счётчик и путь к отчёту.
+- «Исправили пароль в .env на SECRET123» — секрет, так нельзя.
+- Шесть записей за один день по одному шагу — одна запись на сессию.

package/skills/project-memory-maintenance/references/section-rules.md

@@ -0,0 +1,59 @@
+# Правила обновления секций досье
+
+> Часть навыка project-memory-maintenance. ≈1 750 токенов. Читать, когда: обновляешь конкретную секцию досье и нужны границы «что писать / что не писать», структура и правила устаревания.
+
+Общие принципы для всех секций:
+- Только долговечные факты: верны через месяц и вне сегодняшнего контекста.
+- Ссылка `path:line` вместо копии кода; одно утверждение — один источник.
+- Ключевые утверждения с меткой `[проверено]/[выведено]/[устарело]`.
+- Объём секции ≤ 40 KB; детали — в файлах проекта, в секции — ссылка.
+- Перед правкой — `read`, после правки — `read` обратно (проверка дублей и секретов).
+
+## PROJECT.md
+- Обновляй: сменился стек или версии, переехал репозиторий/прод, другой способ запуска, изменился владелец или статус.
+- Структура: назначение, стек и версии, расположение (копия/прод), запуск, статус и владелец.
+- Не пиши: историю сессий, подробности реализации, списки файлов (это `CODE-MAP`).
+- Ошибка: «сегодня настроили окружение» — это журнал, а не проект.
+
+## ARCHITECTURE.md
+- Обновляй: новый/удалённый компонент, изменение границ, потока данных, очередей/крона, внешних сервисов, ключевое решение.
+- Структура: компоненты и границы, точки входа, поток данных (текстом), внешние зависимости, решения и компромиссы.
+- Не пиши: детали алгоритмов, полный список классов, код.
+- Помечай `[выведено]`, если границы восстановлены по косвенным признакам.
+
+## CODE-MAP.md
+- Обновляй: новый модуль/маршрут/точка входа/сервис/конфиг/тест; сдвинулись якоря после рефакторинга.
+- Структура: таблица «область | путь | зачем»; точки входа; модели и схема; тесты; конфиги.
+- Не пиши: код и пересказ методов; записи без назначения.
+- Проверяй актуальность путей перед сохранением: мёртвая ссылка хуже отсутствующей.
+
+## INVARIANTS.md
+- Обновляй: появилось жёсткое правило, подтверждённое тестом, пользователем или инцидентом.
+- Структура на пункт: правило → почему → как проверить → источник `path:line`/тест.
+- Не пиши: советы, вкусовые предпочтения, «желательно».
+- Устаревший инвариант не удаляй молча: помечай `[устарело]` и указывай, чем заменён.
+
+## GOTCHAS.md
+- Обновляй: встретили неочевидную ловушку с воспроизводимым симптомом и обходом.
+- Структура: симптом → причина → обход → риск, если игнорировать.
+- Не пиши: банальности («проверяй null»), предположения без подтверждения.
+- Ловушка, исправленная навсегда (например, баг закрыт), помечается `[устарело]`.
+
+## RUNBOOK.md
+- Обновляй: изменились команды запуска/тестов/сборки, окружение, деплой, откат, бэкап, места логов.
+- Структура: окружение, установка, запуск, тесты, сборка, деплой и откат, бэкап, диагностика.
+- Не пиши: объяснение архитектуры (это `ARCHITECTURE`).
+- Команды копируй из README/AGENTS/CI; не сочиняй «примерно так».
+- Для опасных команд явно: когда нельзя запускать (прод, боевая БД).
+
+## JOURNAL/YYYY-MM.md
+- Обновляй: каждая значимая сессия (см. §3 основного файла).
+- Пиши только через `append_journal`.
+- Не пиши: дампы, длинные логи, секреты, пересказ чата.
+- Не смешивай журнал с досье: «что делали» остаётся здесь, «как устроено» — в секциях.
+
+## INDEX.json
+- Ручная правка запрещена.
+- Отражает свежесть: `lastAnalyzedAt`, `git.branch`, `git.head`, `confidence`.
+- `lastAnalyzedAt` — только после полного анализа, не после каждой правки секции.
+- Если `status` показывает расхождение с фактическим состоянием — зафиксируй в отчёте, не правь файл.

package/skills/release-and-deploy/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: release-and-deploy
+description: "Выпуск и выкатка: SemVer, immutable-артефакт, SHA-256 checksums, бэкап, деплой штатным скриптом, smoke и откат."
+whenToUse: "Перед подготовкой релиза, сборкой артефакта, выкаткой на сервер, обновлением с миграциями и когда нужен план отката."
+user-invocable: true
+---
+
+# Релиз и выкатка (универсально)
+
+## 0. Когда применять
+- Готовишь релиз: версия, артефакт, checksums, тег, release notes.
+- Просят «задеплой», обновить стенд или прод.
+- В обновлении есть миграции/данные — сначала `pg-upgrade-verify`.
+- После выкатки нужны smoke и решение «оставить или откатить».
+
+## 1. Главное
+
+**Версия и артефакт**
+- SemVer/правила проекта: feature → minor, fix → patch, breaking → major. Версия — в артефакте, на сервере и в CHANGELOG.
+- Артефакт собирается **один раз** и выкатывается неизменным; пересборка = новая версия и sha256.
+- Без `.env*`, `vendor/`, `node_modules/`, сборок, `storage/`, `.git`, дампов и PII (если проект не требует иного).
+- Проверить состав и отсутствие секретов; SHA-256 — в `checksums.txt` (`sha256sum` / `Get-FileHash -Algorithm SHA256`).
+- CHANGELOG/RELEASE-NOTES: изменения, миграции, риски, план отката.
+
+**Перед выкаткой**
+- Зелёные: линтер, статанализ, unit/feature, E2E/UI; baseline не хуже.
+- Бэкап БД, файлов и текущего кода; копия читается (`pg_restore -l`, пробное восстановление) и хранится вне сервера.
+- Свободное место, maintenance-окно и выполнимый план отката.
+- Миграции проверены на копии (`pg-upgrade-verify`) и аддитивны; при риске — maintenance.
+
+**Выкатка**
+- Сверить checksums: `sha256sum -c checksums.txt`.
+- Применять штатным скриптом; зависимости, сборку и кэши не делать вразнобой.
+- Перезапустить очереди/воркеры/php-fpm, сбросить и собрать кэши, проверить права на `storage`.
+- Smoke: версия/health, `/login` и вход, ключевой сценарий записи, старые данные, админ и пользователь, логи без ошибок, очередь жива.
+
+**Откат**
+- Код: предыдущий артефакт/папка/тег. БД: только если менялись данные/схема — из проверенного дампа и с подтверждением.
+- Снять maintenance, повторить smoke, сообщить пользователям, зафиксировать причину.
+
+**После**
+- Наблюдать логи, метрики и фоновые задачи 15–30 минут; старые артефакты хранить до стабильности.
+- Записать версию, sha256, smoke и откат в память/CHANGELOG.
+
+## 2. Куда грузить дальше
+`git-and-ci` — ветки/теги/CI; `pg-upgrade-verify` — проверка на копии живой БД; `database-safety` / `service-desk-db-safety` — бэкап; `service-desk-release` — проектный tgz + `deploy/update.sh`.
+
+## 3. Гейт перед сдачей
+- [ ] Версия, CHANGELOG и sha256 сверены с артефактом.
+- [ ] Бэкап читается и лежит вне сервера; откат выполним.
+- [ ] Миграции прогнаны на копии; выкатка — штатным скриптом.
+- [ ] Smoke: версия, вход, ключевой сценарий, старые данные, админ + пользователь, логи/очередь.
+- [ ] Факт выкатки записан.

package/skills/requirements-and-planning/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: requirements-and-planning
+description: "Любая новая задача до реализации: требования, критерии приёмки, декомпозиция, риски, варианты решений и проверяемый план — для кода, дизайна, SEO, данных, релизов."
+whenToUse: "Перед началом работы, когда запрос расплывчат, нужен план/ТЗ/оценка, сравнение вариантов или критерии «готово» до правок кода."
+user-invocable: true
+---
+
+# Requirements & Planning — ядро
+> ≈1 600 токенов. Это ядро; детали — по ссылкам и только когда реально нужны.
+
+## 0. Когда применять
+- Новая задача: фича, страница, релиз, миграция — до первой правки.
+- Запрос расплывчат: «сделай красиво», «ускорь», «почини», «улучши как-то».
+- Нужны ТЗ, оценка, сравнение вариантов, критерии «готово»; результат — выводы и план, а не осмотр.
+
+## 1. Главное (алгоритм)
+
+**Контракт:**
+1. **Одно предложение:** переформулируй запрос — что изменится для пользователя.
+2. **Неясное уточняй** одним сообщением (1–3 вопроса), но не блокируйся: некритичное — допущение и дальше; критичное (данные, деньги, права, необратимость) — только после ответа.
+3. **Критерии приёмки — до кода**, проверяемые (Given/When/Then или чек-лист).
+4. **План — до правок:** шаги, файлы, зависимости, проверки, откат.
+5. **Scope guard:** явно «входит / не входит»; не расширяй молча.
+6. **Финал:** отчёт «сделано / как проверено / риски / дальше» по критериям.
+
+**8 шагов:**
+1. **Понять запрос:** кто пользователь, что болит, что есть и что должно стать, формат результата.
+2. **Разведка:** память/досье, `AGENTS.md`, затронутые файлы/маршруты/модели/тесты, ограничения (стек, права, бэкапы, SEO, дизайн-система).
+3. **Требования:** цель, сценарий, входит/не входит, критерии, ограничения (шаблон — `references/templates-and-estimates.md`).
+4. **Варианты:** 2–3 с плюсами/минусами/рисками; для рискованного — самый обратимый; крупное — вертикальный срез.
+5. **План:** шаги по 1–2 ч с файлами и проверкой; порядок: бэкап → изменения → проверка → откат.
+6. **Риски:** риск → вероятность/влияние → митигация; перед необратимым — бэкап, dry-run, копия, feature-флаг.
+7. **Исполнение:** чекпоинт после каждого блока; отклонения объясняй; scope creep — в «потом».
+8. **Сдача:** таблица «критерий → проверка → результат», отчёт, память/версия.
+
+## 2. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
+|---|---|---|
+| Детали 8 шагов и что проверять на каждом | references/process-steps.md | ≈1 350 |
+| Бриф, критерии приёмки по типам, эвристики оценки | references/templates-and-estimates.md | ≈630 |
+| Антипаттерны и чек-лист перед стартом | references/antipatterns-and-checklist.md | ≈480 |
+
+## 3. Гейт перед сдачей
+- [ ] Запрос переформулирован; неясности уточнены или допущения зафиксированы.
+- [ ] Прочитаны память/досье, найдены затронутые файлы.
+- [ ] Критерии приёмки зафиксированы до кода и сверены: критерий → проверка → результат.
+- [ ] План с проверками и откатом выполнен; scope не расширен молча, «потом» вынесено.
+- [ ] Подобраны скиллы (`skills-router`), пройдены их гейты: тесты/скриншоты/SEO/бэкап.
+- [ ] Отчёт «сделано / как проверено / риски / дальше»; память и версия обновлены.

package/skills/requirements-and-planning/references/antipatterns-and-checklist.md

@@ -0,0 +1,20 @@
+# Антипаттерны и чек-лист перед стартом
+
+> Часть навыка requirements-and-planning. ≈480 токенов. Читать, когда: проверяешь план на типовые ошибки или начинаешь задачу и нужен стартовый чек-лист.
+
+## Антипаттерны
+- Начать с кода, не поняв, что считать «готово».
+- Уточнять «потом», когда уже всё сломано.
+- План из одного пункта «сделать всё».
+- Нет критериев приёмки → бесконечные правки и споры.
+- Нет откат-плана для миграций/релизов/прод-правок.
+- Молча расширить scope («заодно переделал ещё 10 страниц»).
+- Считать «сделал» = «написал код» (без проверки и отчёта).
+
+## Чек-лист перед стартом
+- [ ] Запрос переформулирован одним предложением.
+- [ ] Критичные неясности уточнены или зафиксированы допущения.
+- [ ] Прочитана память/досье, найдены затронутые файлы.
+- [ ] Критерии приёмки зафиксированы.
+- [ ] Есть план с проверками и откатом.
+- [ ] Подобраны скиллы (`skills-router`) под типы работ.

package/skills/requirements-and-planning/references/process-steps.md

@@ -0,0 +1,52 @@
+# Восемь шагов планирования — детально
+
+> Часть навыка requirements-and-planning. ≈1 350 токенов. Читать, когда: нужен полный разбор шагов — разведка, варианты, план, риски, чекпоинты, сдача.
+
+## Шаг 1. Понять запрос
+- Кто пользователь и в каком контексте? Что болит? Какая цель: сэкономить время, снизить ошибки, продать, найти?
+- Что уже есть (текущее поведение / скриншот / код)? Что должно стать?
+- Формат результата: экран? файл? архив? релиз? отчёт? API?
+
+## Шаг 2. Контекст и разведка
+- Прочитай память/досье проекта (`memory/INDEX.md`, `memory/projects/<проект>.md`), `AGENTS.md`.
+- Найди затронутые файлы, маршруты, модели, шаблоны, тесты, конфиги.
+- Проверь ограничения: стек, версии, окружение, права, бэкапы, кэш, SEO, дизайн-система.
+- Не проектируй вслепую: 10 минут разведки экономят часы.
+
+## Шаг 3. Требования и критерии приёмки
+Заполни:
+- **Цель:** <одно предложение>
+- **Пользователь и сценарий:** <кто / что делает / зачем>
+- **Входит:** <...>
+- **Не входит:** <...>
+- **Критерии приёмки:** проверяемые пункты, например «заявка создаётся с выбранной срочностью», «на 390px нет overflow», «title/description/canonical на странице», «PHPUnit зелёный, +2 теста».
+- **Ограничения:** <бюджет времени, стек, нельзя ломать…>
+
+## Шаг 4. Варианты решения
+- 2–3 варианта (если выбор неочевиден): плюсы, минусы, риски, трудозатраты.
+- Выбери и обоснуй. Для рискованных — предпочти самый обратимый.
+- Для крупных задач — вертикальный срез (тонкая сквозная реализация), а не «сначала весь бэкенд».
+
+## Шаг 5. План
+```
+1. <шаг> — файлы: ... — проверка: ...
+2. <шаг> — файлы: ... — проверка: ...
+```
+- Декомпозируй до шагов на 1–2 часа; отметь зависимости и параллелизм.
+- Для каждого шага — как проверить: тест, скриншот, запрос, аудит.
+- Зафиксируй порядок: сначала бэкап/подготовка, потом изменения, потом проверка, потом откат-план.
+
+## Шаг 6. Риски и откат
+- Таблица: риск → вероятность/влияние → митигация.
+- Что может сломаться: данные, прод, кэш, SEO, дизайн, интеграции? Как откатим?
+- Перед необратимым: бэкап, dry-run, копия, feature-флаг.
+
+## Шаг 7. Исполнение с чекпоинтами
+- Двигайся по плану; после каждого блока — быстрая проверка (тест/линт/скриншот).
+- Отклонение от плана — фиксируй и объясняй; scope creep — в отдельный список «потом».
+- Для UI/SEO/БД используй соответствующие скиллы и их гейты.
+
+## Шаг 8. Сдача
+- Сверь результат с критериями приёмки: таблица «критерий → как проверено → результат».
+- Отчёт: что сделано, как проверено, риски/ограничения, что дальше.
+- Обнови память (`SESSIONS.md`, досье) и версию/документацию, если применимо.

package/skills/requirements-and-planning/references/templates-and-estimates.md

@@ -0,0 +1,29 @@
+# Шаблоны брифа и критериев, эвристики оценки
+
+> Часть навыка requirements-and-planning. ≈630 токенов. Читать, когда: нужно быстро собрать бриф, сформулировать критерии приёмки по типу работы или оценить трудозатраты.
+
+## Шаблон брифа (короткий)
+```
+Задача: <одно предложение>
+Зачем: <польза>
+Пользователь/сценарий: <...>
+Входит / Не входит: <...>
+Критерии приёмки: <3–7 проверяемых пунктов>
+Ограничения: <стек, сроки, нельзя ломать>
+Риски/откат: <...>
+План: <3–7 шагов с проверками>
+```
+
+## Шаблон критериев приёмки
+- Given <контекст>, when <действие>, then <результат>.
+- UI: 1440/768/390, light/dark, состояния, контраст AA, нет overflow.
+- SEO: title/description, один H1, canonical, OG, schema, sitemap/robots (если применимо).
+- API/данные: код ответа, валидация, транзакция, права, отсутствие N+1.
+- Тесты: baseline не ухудшен, новые тесты зелёные.
+- Релиз: артефакт собран, checksum, инструкция, откат.
+
+## Эвристики оценки
+- Небольшая правка — 0,5–2 ч; компонент — 2–6 ч; экран — 0,5–2 дня; фича с БД/тестами — 1–3 дня.
+- Неизвестный стек / чужая кодовая база — ×1,5–2 к оценке.
+- Всегда добавляй время на проверку (тесты/скриншоты/аудит) и на непредвиденное (+20–30%).
+- Если оценка > 2 дней — дели на этапы с отдельной сдачей.

package/skills/security-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: security-review
+description: "Безопасность кода: OWASP-минимум, доступ и IDOR, ввод/вывод, загрузки, секреты, зависимости, реакция на инцидент."
+whenToUse: "Новые маршруты, формы, API, загрузки, права и роли, работа с секретами; перед релизом, ревью и после инцидента."
+user-invocable: true
+---
+
+# Безопасность (универсальный чек-лист)
+
+## 0. Когда применять
+- Новый маршрут/форма/API/загрузка, права и роли, секреты; перед релизом/ревью; инцидент.
+
+## 1. Главное
+
+**OWASP-минимум (A01–A10):**
+- **A01 Доступ:** deny-by-default; `auth` + право на каждом маршруте; IDOR — проверка владельца; привилегированные действия — отдельное право; тест admin/user/guest.
+- **A02+A08 Крипто/целостность:** bcrypt/argon2 (не MD5/SHA1), TLS, секреты не в коде; не десериализовать недоверенное, подписи вебхуков, SRI.
+- **A03 Инъекции:** SQL — параметры/ORM, команды — без shell, XML — без внешних сущностей; `fillable`/явные поля.
+- **A04+A05 Дизайн/конфиг:** лимиты, least privilege, модель угроз (деньги/PII/админка); `APP_DEBUG=false`, без дефолтных паролей, CSP/`X-Content-Type-Options`/frame-ancestors, cookie HttpOnly/Secure/SameSite.
+- **A06 Зависимости:** `composer audit`, `npm audit --omit=dev`; критичное — обновить.
+- **A07 Аутентификация:** регенерация сессии при входе, выход инвалидирует, разумный срок; rate limit на вход/чувствительные действия; MFA админам; парольная политика.
+- **A09+A10 Логи/SSRF:** вход/права/админ-действия без секретов и PII, алерты; allowlist исходящих URL, блок private/metadata IP.
+
+**Ввод/вывод:** серверная валидация всех полей (тип/длина/диапазон/формат), клиент — только UX; экранирование по контексту; HTML — только санитайзер с whitelist; никаких `{!! !!}`/`innerHTML`/`v-html`; ошибки не отдают стек/секреты; PII — не в логах/URL/скриншотах.
+
+**Загрузки:** whitelist расширений и MIME, лимит размера, случайные имена; вне webroot или безопасная отдача; не-изображения — `Content-Disposition: attachment`; изображения перекодировать; запрет path traversal и архивов-бомб.
+
+**Секреты:** `.env`/секрет-хранилище; `.env` в `.gitignore` (`git check-ignore -v .env`); не в коде/логах/коммитах/памяти; утечка → ротация; прод — минимум прав.
+
+**Инцидент:** зафиксировать, изолировать, сменить секреты, выпустить фикс, уведомить по политике, записать в память.
+
+## 2. Куда грузить дальше
+Смежные: `code-review-checklist`, `release-and-deploy`.
+
+## 3. Гейт перед сдачей
+- [ ] OWASP-минимум пройден, проверены admin/user/guest и IDOR.
+- [ ] Ввод валидируется на сервере, вывод экранируется, опасного HTML нет.
+- [ ] Загрузки: whitelist, лимит, безопасное хранение/отдача.
+- [ ] Секретов нет в коде/логах/гите; `.env` игнорируется; аудит зависимостей.
+- [ ] Прод: debug off, cookies/headers, rate limit; PII не в логах/URL/скриншотах.