skills/skills/mappa-session-orient/SKILL.md

name, author, version, description

name	author	version	description
mappa-session-orient	ours	1.0.0	Старт-фаза форкфлоу: контракт + чтение (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 → «вёл @, не завершена» (краш-детект).
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).