skills: admin-runbooks — проектный скил зоны админа (USE/EXECUTE/WRITE + индекс, поглощает writing-runbooks)

.agents/skills/admin-runbooks/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: admin-runbooks
+author: ours
+version: 1.0.0
+description: >
+  Единый контур ранбуков зоны админа (.admin): НАЙТИ нужный ранбук перед любой
+  прод-операцией → ИСПОЛНИТЬ по нему (чек-лист + verify + откат + письмо/таска) →
+  ВЕСТИ (обновлять после инцидентов/изменений) и СОЗДАВАТЬ новые. Поглощает
+  writing-runbooks (v1.0.0, superseded) — секция WRITE это его канон.
+  Trigger (user): деплой/редеплой/рестарт/ротация/миграция любого сайта или стека;
+  «по ранбуку», «как деплоить X», «напиши/обнови ранбук», «есть ли ранбук по X»;
+  любой прод-инцидент на сайте, который может потребовать операции.
+---
+
+# admin-runbooks
+
+Один контур: **индекс → USE → EXECUTE → WRITE/UPDATE**. Цель — устранить
+«рыскание» (поиск рецепта по сессиям/чатам/grep), когда ранбук есть или должен быть.
+
+> ⚠️ **СЛУЖЕБНАЯ зона `.admin`.** Ранбуки — служебные документы `.admin`:
+> применять/выполнять может только `.admin`; другие проекты читают по запросу,
+> не выполняют; наружу не выносить. Прод-операция по ранбуку = таска на борде
+> `.admin` + письмо от заказчика (исполнитель-не-админ не деплоит сам).
+
+## 0. ИНДЕКС РАНБУКОВ (всегда первый шаг)
+
+**Индекс:** `.admin/.wiki/concepts/runbooks-index.md` (единственный источник
+«какой ранбук для чего»). **Прибит в AGENTS.md** — контур обязателен.
+
+Перед ЛЮБОЙ прод-операцией (деплой/редеплой/рестарт/ротация/миграция/инцидент):
+
+1. **Прочитай индекс** (`read .admin/.wiki/concepts/runbooks-index.md`) — найди
+   строку по проекту/операции → путь ранбука.
+2. Ранбук может жить в трёх местах (индекс указывает, где):
+   - `.admin/.wiki/concepts/*-runbook*.md` — канон для VDS-проектов;
+   - `<репо-проекта>/.wiki/concepts/docker-deploy.md` и т.п. — репо-вики проекта
+     (pilorama98.ru: `apps/web/.wiki/concepts/docker-deploy.md`);
+   - mappa wiki (`wiki_search`) — если индекса ещё нет, искать там.
+3. **Нет ранбука → НЕ деплоить молча.** Создать (см. WRITE) до/вместе с операцией:
+   отдельной таской или в теле операционной таски (пункт «нужен ранбук»).
+   Это не бюрократия: отсутствие ранбука = повторное рыскание в следующий раз.
+
+## 1. USE — найти и прочитать ранбук
+
+- Сначала индекс → ранбук. Не начинать grep по сессиям/чатам — это анти-паттерн
+  (источник этой секции: инцидент 2026-08-26 pilonuxt — рыскал, ранбука не было).
+- Прочитать ранбук **целиком** перед операцией (секреты — плейсхолдеры, реальные
+  значения — из pass по указателям; ранбук сам секретов не несёт).
+- Сверить актуальность: теги/версии на проде могут обогнать ранбук (пример:
+  stostayer-web ранбук показывал 0.3.23, прод был 0.3.26 → тег брать с проде,
+  а ранбук потом обновить — WRITE). Если расхождение → пометить на апдейт.
+
+## 2. EXECUTE — деплой/операция по ранбуку
+
+Выполнять шаги ранбука как чек-лист, **не пропуская**:
+
+1. **Предусловия** (auth: JWT/токены из pass; docker login; pull-ДО-рестарта;
+   .dockerignore/.yarnrc временные модификации — пометить на возврат).
+2. **Шаги операции** — дословно по ранбуку, порядок важен (gotchas в ранбуке).
+3. **Verify** по секции ранбука (страницы/эндпоинты/логи/uptime) — зелёный перед
+   закрытием. При красном — rollback-путь из ранбука, не импровизация.
+4. **Фиксация результата:**
+   - sync source-of-truth compose (если менялся тег) → commit + push;
+   - письмо-отчёт заказчику (inbox_send, from `.admin`, с verify-таблицей);
+   - закрыть операционную таску (reason = что сделано + verify);
+   - при необходимости — обновить ранбук (WRITE): новый тег, новые gotchas.
+
+Ограничения: одна попытка там, где ранбук велит одну (egress-баны, retry-штормы);
+не отклоняться от ранбука без причины — отклонение фиксировать в письме.
+
+## 3. WRITE / UPDATE — создание и ведение ранбуков
+
+Канон (наследие writing-runbooks v1.0.0, поглощено):
+
+### Жёсткие правила
+
+1. **Ранбук — служебный документ `.admin`.** Применять может только `.admin`.
+2. **Из проекта не выносить.** Не копировать в другие вики, не публиковать.
+3. **Деплой = таска + письмо админу.** Любая прод-операция — по задаче на борде
+   `.admin` и письму. Исполнитель-не-админ ставит задачу, не деплоит сам.
+4. **Служебный блок — в первых абзацах** (машиночитаемый маркер служебности):
+
+```markdown
+> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.**
+> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять.
+> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать.
+> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют.
+```
+
+Дословно, без перефразирования.
+
+### Гигиена секретов (решение 5, write-тайм сканер mappa)
+
+**В ранбуках никогда не бывает реальных секретов.** Только плейсхолдеры +
+указатели на pass: `<из pass <path>/<FIELD>>`. Сканер блокирует запись (422)
+на password/token/api_key/secret+значение ≥6 симв., AKIA…, JWT, ssh-ключи.
+Обход плейсхолдером: значение <6 симв. (`'<...>'`), либо ключ-слово не латиницей,
+либо разрыв `: ` коротким словом (`PASSWORD: см. pass (…)`). После записи —
+проверить `admin_secret_scan` (0 хитов).
+
+### Структура ранбука
+
+1. Frontmatter: `title`, `type: concept`, `tags: [.., runbook]`, `related`, `updated`.
+2. H1 + служебный блок (обязательно, дословно).
+3. Scope (VDS, стек Portainer Id, endpointId, source-of-truth compose).
+4. Артефакты (код/образ/стек/БД/эндпоинт; тег = как на проде).
+5. Шаги операции (копируемые команды) + таблица «рестарт vs пересборка» если уместно.
+6. Verify/smoke после операции.
+7. Rollback-путь всегда.
+8. Gotchas из практики (нумерованные, с датой).
+
+### Ведение (UPDATE)
+
+Обновлять ранбук когда:
+- прод ушёл вперёд (новый тег/версия) — поправить инвентарь/таблицы;
+- появилась новая gotcha (инцидент с неочевидной причиной);
+- изменился канал деплоя (адреса/стек/порядок).
+После правки: bump `updated:`, синхронизировать с индексом (что покрывает),
+проверить secret_scan. Коммит отдельный от операционного («docs(runbook): …»).
+
+## Порядок записи (мутации вики)
+
+- Файл ранбука живёт в `.admin/.wiki/concepts/` (репо .admin, git). Писать файл →
+  commit → push (проектная дисциплина: push свободно). mappa-импорт подхватит при
+  следующем импорте (индекс/ранбуки доступны и через wiki_search после импорта).
+- Секрет-сканер: `mcp__mappa__admin_secret_scan` после записи — 0 hits.
+
+## Место жительства этого скила
+
+Скил лежит в `.admin/.agents/skills/admin-runbooks/SKILL.md` — проектные скилы
+`.admin` (pi: `.agents/skills/` в cwd). НЕ дублировать в `~/.agents/skills/`
+(глобальная установка, перезаписывается update-skills) и НЕ в общий skills-репо.
+Обновление — правкой файла в проекте + commit/push (.admin).
+
+## Связи
+
+- `concepts/runbooks-index.md` — индекс ранбуков (обязательный первый шаг).
+- `writing-skills` — RED-GREEN-REFACTOR для скилов (если править сам скил).
+- `using-vds-ops` — диагностика контейнеров (read-only), не деплой.
+- `project-discipline` — семвер/пуш-правила при правке версионируемых артефактов.