feat(mappa-session-orient): new skill v1.0.0 — start-phase ritual (contract→pull→handoff-read→inbox-raise→liveness→live-ingest query); absorbs pulling-before-work/session-handoff(read)/session-inbox-monitor/using-system-snapshot; 404-skip for undeployed /session [skip-tdd: visual]

2026-08-24 22:52:20 +03:00
parent 3dff74d584
commit 60f317ace0
13 changed files with 157 additions and 513 deletions
--- a/skills/mappa-session-orient/SKILL.md
+++ b/skills/mappa-session-orient/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: mappa-session-orient
+author: ours
+version: 1.0.0
+description: >
+  Старт-фаза форкфлоу: контракт + чтение (pull --ff-only → handoff read →
+  inbox raise → liveness-сводка «живо/мертво» → live-ingest query). Нужен и
+  для ad-hoc, где нет AGENTS.md-контракта. Поглощает pulling-before-work,
+  session-handoff(read), session-inbox-monitor(raise), using-system-snapshot
+  (liveness) + live-ingest query (старые имена — триггер-синонимы). Граница:
+  orient отвечает «живо/мертво» одной строкой; глубокая диагностика — вне
+  suite (эскалация человеку/диагностической сессии). Триггеры: «что на
+  сессии», «кто последним работал», «продолжи с места», «orient me»,
+  session-start ритуал, «pull remote before work».
+---
+
+# mappa-session-orient
+
+Старт-фаза цикла агента: **контракт + чтение**, тонкий слой — отвечает на
+вопрос «живо/мертво» (одна строка на секцию), не углубляется. Нужен и для
+ad-hoc-сессий (где нет AGENTS.md-контракта — ориентация всё равно обязательна).
+
+> **Граница session-orient / ops (w:2605, round 3):** orient — «живо/мертво»;
+> ops — «почему и что дальше». Проблема на старте → **не углубляться**:
+> передать человеку или диагностической сессии (вне suite).
+
+## Когда использовать
+
+- Старт сессии (ритуал, порядок строго по Steps).
+- «что на сессии», «кто последним работал», «продолжи с места», «orient me».
+- Ad-hoc-сессия без трека/таски — ориентация всё равно (контракт + чтение).
+
+## Steps (порядок — ритуал)
+
+### 1. Контракт
+
+Прочитать `AGENTS.md` проекта (canon; `CLAUDE.md` — legacy-указатель). Если
+AGENTS.md нет — ad-hoc: контракта нет, но ориентация продолжается (шаги 2–6
+не зависят от него).
+
+### 2. Pull (pulling-before-work, полный цикл)
+
+`git pull --ff-only` — один раз на старте. Проверки по порядку: git-work-tree?
+(нет → silent exit), политика pull (`pull.rebase=true` + `pull.ff=only`,
+set-if-absent), origin remote? (нет → skip), дерево чистое? (грязно → skip,
+не stash), HEAD attached? (нет → skip), upstream? (нет → skip), `git pull --ff-only`.
+**Никогда auto-merge/rebase, никогда stash.** Повторный pull — только по явному
+«sync».
+
+### 3. Handoff read (session-handoff read-часть)
+
+1. `mcp__mappa__entity_search(q='', type='handoff', project=<имя>, limit=1)` —
+   если пусто, silent exit (первая сессия проекта).
+2. **Staleness:** `meta.date` > 7 дней → спросить user'а «handoff устарел,
+   оверрайдить или продолжить?».
+3. **Summarize + Orient:** пересказать одним блоком (summary / open_treks /
+   ask_user / guards / recent_commits): «прошлая сессия предложила X. Делаем?»
+4. **Wait.** Никаких действий до подтверждения user'ом. Default = orient + ask,
+   никакого auto-execute.
+
+### 4. Inbox raise + sweep (session-inbox-monitor)
+
+Поднять персистентный монитор на инбокс проекта (pi: расширение inbox-monitor
+поллит `GET /inbox?project=<cwd>`; opt-in — строка `inbox monitor: raise on
+start` в AGENTS.md, live re-check каждый тик). Свип: `mcp__mappa__inbox_monitor(project=<имя>)`
+— непрочитанные письма могут менять план; обработай каждое по `mappa-messaging`
+(письмо — first-class, в начале ближайшего хода).
+
+### 5. Liveness-сводка (using-system-snapshot) — «живо/мертво»
+
+Один-два зонда в текущем turn, сжать в 3–4 строки, не raw-дампить:
+
+```
+mcp__mappa__meta_health           → 🟢/🔴 Mappa alive (заголовок при падении)
+mcp__mappa__admin_status          → счётчики по типам/проектам (нагрузка)
+mcp__projects-meta__meta_system_snapshot → poller (running? + проекты) / docker (N/N up,
+                                          иначе проблемные) / tasks (Σ active/blocked,
+                                          кэш — может быть stale)
+```
+
+**Never assert liveness по памяти** — только вызов тула в этом же turn. Если
+snapshot показал проблему → **эскалация, не углубление**: «проблема на старте,
+не разбираю — передаю человеку/диагностической сессии» (ops вне suite).
+
+### 6. Live-ingest query (потребитель session-live-ingest, #1022/#1024)
+
+Зависимость: сервер #1022 (v0.8.0) + клиентская часть #1024 (pi session-sync,
+.session пишется клиентом). Контракт — w:2604.
+
+1. `mcp__mappa__session_list(project=<имя>, stale_minutes?)` — последние сессии
+   проекта, latest-first (`updated_at DESC`), с end-state/ts/meta-тройкой
+   {project, runtime, machine, folder}.
+2. **Stale-active детект:** end-state≠clean AND updated_at < now−X → «вёл
+   <runtime>@<machine>, не завершена» (краш-детект).
+3. **«Другая связка + не завершена»** → предложить (peer-канон, решение за
+   человеком): забить / дернуть письмом (`mappa-messaging`: письмо той связке)
+   / продолжить самому.
+4. **Same-triple (`/resume`):** та же связка {runtime, machine, folder} → догрузить
+   остаток (пи-нативный resume или бриф из mappa).
+
+**Замечание (2026-08-24):** роуты `/session` ещё не задеплоены на прод
+(сервер #1022 в репо, деплой ждёт #1055) — при 404/«no route» live-ingest query
+пропускается без фейла: orient продолжается (шаги 1–5), query-часть — по факту
+доступности.
+
+## Failure modes
+
+- **Проблема на старте** (сервис упал, snapshot красный, конфликт pull) → не
+  углубляться: эскалация человеку/диагностической сессии (ops вне suite).
+- **Pull diverged** → `⚠️ diverged — resolve manually`; не auto-merge/rebase.
+- **Handoff stale (>7 дней)** → спросить user'а, не оверрайдить молча.
+- **Live-ingest недоступен** (404 no route / нет клиента #1024) → пропустить
+  шаг 6, не блокировать ориентацию.
+- **Проект не в mappa** (нет handoff/session-сущностей) → silent exit по
+  соответствующим шагам; первая сессия проекта — норм.
+
+## Side effects
+
+- Ничего не пишет, ничего не мутирует (ориентация read-only: pull — локальный
+  ff, inbox-raise — монитор, liveness — зонды, live-ingest — чтение).
+- Поднимает персистентный inbox-монитор (живёт до конца сессии).
+
+## What NOT to do
+
+- **Не auto-execute** из handoff'а — orient + ask, никакого авто-действия.
+- **Не углубляться в диагностику** — orient = «живо/мертво»; «почему» — вне suite.
+- **Не assert liveness по памяти** — только зонд в этом же turn.
+- **Не stash/не auto-merge/не auto-rebase** при pull — только `--ff-only`.
+- **Не повторять pull** в сессии без явного «sync».
+- **Не ходить по многохоповым цепочкам** live-ingest — одна строка «кто
+  последним», предложение — человеку.
+- **Не писать** (handoff/вики/таски) на ориентации — это финиш-фаза
+  (`mappa-closing-ritual`).
+
+## Reference
+
+- Финиш-фаза: `mappa-closing-ritual` (handoff write + PROPOSE).
+- Задачи: `mappa-task-work` (борд после ориентации).
+- Почта: `mappa-messaging` (ответы на письма, дернуть связку).
+- Знание: `mappa-knowledge`. Делегирование: `mappa-delegation`.
+- Live-ingest спека: `concepts/session-live-ingest` (wiki:2604).
+- Глубокая диагностика (вне suite): `using-vds-ops` (контейнеры VDS).