diff --git a/skills/mappa-session-orient/SKILL.md b/skills/mappa-session-orient/SKILL.md index 0ed4f14..14c54b8 100644 --- a/skills/mappa-session-orient/SKILL.md +++ b/skills/mappa-session-orient/SKILL.md @@ -1,146 +1,152 @@ --- name: mappa-session-orient author: ours -version: 1.0.1 +version: 1.1.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». + Start phase of the forkflow: contract + reading (pull --ff-only → handoff + read → inbox raise → liveness summary "alive/dead" → live-ingest query). + Also needed for ad-hoc sessions without an AGENTS.md contract. Absorbs + pulling-before-work, session-handoff(read), session-inbox-monitor(raise), + using-system-snapshot (liveness) + live-ingest query (old names are + trigger-synonyms). Boundary: orient answers "alive/dead" in one line; deep + diagnosis is outside the suite (escalate to a human / a diagnostic session). + Triggers (bilingual): «что на сессии», «кто последним работал», «продолжи с + места», «orient me», "what's on the session", "who worked last", "continue + from where I stopped", "orient me", session-start ritual, «pull remote before + work», "pull remote before work". --- # mappa-session-orient -Старт-фаза цикла агента: **контракт + чтение**, тонкий слой — отвечает на -вопрос «живо/мертво» (одна строка на секцию), не углубляется. Нужен и для -ad-hoc-сессий (где нет AGENTS.md-контракта — ориентация всё равно обязательна). +Start phase of the agent cycle: **contract + reading**, a thin layer — answers +the question "alive/dead" (one line per section), does not go deep. Also needed +for ad-hoc sessions (where there is no AGENTS.md contract — orientation is +still mandatory). -> **Граница session-orient / ops (w:2605, round 3):** orient — «живо/мертво»; -> ops — «почему и что дальше». Проблема на старте → **не углубляться**: -> передать человеку или диагностической сессии (вне suite). +> **Boundary session-orient / ops (w:2605, round 3):** orient = "alive/dead"; +> ops = "why and what's next". A problem at start → **do not dig deeper**: +> hand it to the human or to a diagnostic session (outside the suite). -## Когда использовать +## When to use -- Старт сессии (ритуал, порядок строго по Steps). -- «что на сессии», «кто последним работал», «продолжи с места», «orient me». -- Ad-hoc-сессия без трека/таски — ориентация всё равно (контракт + чтение). +- Session start (ritual, order strictly per Steps). +- «что на сессии», «кто последним работал», «продолжи с места», «orient me», + "what's on the session", "who worked last", "continue from where I stopped". +- Ad-hoc session without a track/task — orientation anyway (contract + reading). -## Steps (порядок — ритуал) +## Steps (order — the ritual) -### 1. Контракт +### 1. Contract -Прочитать `AGENTS.md` проекта (canon; `CLAUDE.md` — legacy-указатель). Если -AGENTS.md нет — ad-hoc: контракта нет, но ориентация продолжается (шаги 2–6 -не зависят от него). +Read the project's `AGENTS.md` (canon; `CLAUDE.md` — legacy pointer). If there +is no AGENTS.md — ad-hoc: no contract, but orientation continues (steps 2–6 +don't depend on it). -### 2. Pull (pulling-before-work, полный цикл) +### 2. Pull (pulling-before-work, full cycle) -`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». +`git pull --ff-only` — once at start. Checks in order: git work-tree? (no → +silent exit), pull policy (`pull.rebase=true` + `pull.ff=only`, set-if-absent), +origin remote? (no → skip), clean tree? (dirty → skip, no stash), HEAD +attached? (no → skip), upstream? (no → skip), `git pull --ff-only`. +**Never auto-merge/rebase, never stash.** Repeat pull — only on explicit +"sync". -### 3. Handoff read (session-handoff read-часть) +### 3. Handoff read (session-handoff read part) -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. +1. `mcp__mappa__entity_search(q='', type='handoff', project=, limit=1)` — + if empty, silent exit (project's first session). +2. **Staleness:** `meta.date` > 7 days → ask the user "the handoff is stale, + override or continue?". +3. **Summarize + Orient:** retell in one block (summary / open_treks / + ask_user / guards / recent_commits): "the previous session proposed X. Do we do it?" +4. **Wait.** No actions until the user confirms. Default = orient + ask, no + auto-execute. ### 4. Inbox raise + sweep (session-inbox-monitor) -Поднять персистентный монитор на инбокс проекта (pi: расширение inbox-monitor -поллит `GET /inbox?project=`; opt-in — строка `inbox monitor: raise on -start` в AGENTS.md, live re-check каждый тик). Свип: `mcp__mappa__inbox_monitor(project=<имя>)` -— непрочитанные письма могут менять план; обработай каждое по `mappa-messaging` -(письмо — first-class, в начале ближайшего хода). +Raise the persistent monitor on the project's inbox (pi: the inbox-monitor +extension polls `GET /inbox?project=`; opt-in — the string +`inbox monitor: raise on start` in AGENTS.md, live re-check every tick). Sweep: +`mcp__mappa__inbox_monitor(project=)` — unread letters may change the +plan; handle each per `mappa-messaging` (a letter is first-class, at the start +of the nearest turn). -### 5. Liveness-сводка (using-system-snapshot) — «живо/мертво» +### 5. Liveness summary (using-system-snapshot) — "alive/dead" -Один-два зонда в текущем turn, сжать в 3–4 строки, не raw-дампить: +One or two probes in the current turn, compress into 3–4 lines, no raw dumps: ``` -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) +mcp__mappa__meta_health → 🟢/🔴 Mappa alive (header on outage) +mcp__mappa__admin_status → counters by type/project (load) +mcp__projects-meta__meta_system_snapshot → poller (running? + projects) / docker (N/N up, + else the problematic ones) / tasks (Σ active/blocked, + cache — may be stale) ``` -**Never assert liveness по памяти** — только вызов тула в этом же turn. Если -snapshot показал проблему → **эскалация, не углубление**: «проблема на старте, -не разбираю — передаю человеку/диагностической сессии» (ops вне suite). +**Never assert liveness from memory** — only a tool call in this same turn. If +the snapshot shows a problem → **escalate, don't dig**: "problem at start, not +investigating — handing to the human / a diagnostic session" (ops outside the +suite). -### 6. Live-ingest query (потребитель session-live-ingest, #1022/#1024) +### 6. Live-ingest query (consumer of session-live-ingest, #1022/#1024) -Зависимость: сервер #1022 (v0.8.0) + клиентская часть #1024 (pi session-sync, -.session пишется клиентом). Контракт — w:2604. +Dependency: server #1022 (v0.8.0) + client part #1024 (pi session-sync, +.session written by the client). Contract — 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). +1. `mcp__mappa__session_list(project=, stale_minutes?)` — the project's + latest sessions, latest-first (`updated_at DESC`), with + end-state/ts/meta-triple {project, runtime, machine, folder}. +2. **Stale-active detect:** end-state≠clean AND updated_at < now−X → + "@ was running, not finished" (crash-detect). +3. **"Different triple + not finished"** → propose (peer canon, human's + decision): ignore / nudge by letter (`mappa-messaging`: letter to that + triple) / continue yourself. +4. **Same-triple (`/resume`):** same triple {runtime, machine, folder} → load + the remainder (pi-native resume or a brief from mappa). -**Замечание (2026-08-24):** роуты `/session` ещё не задеплоены на прод -(сервер #1022 в репо, деплой ждёт #1055) — при 404/«no route» live-ingest query -пропускается без фейла: orient продолжается (шаги 1–5), query-часть — по факту -доступности. +**Note (2026-08-24):** the `/session` routes are not yet deployed to prod +(server #1022 in repo, deploy awaits #1055) — on 404/"no route" the live-ingest +query is skipped without failing: orient continues (steps 1–5), the query part +— per actual availability. ## 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 по - соответствующим шагам; первая сессия проекта — норм. +- **Problem at start** (service down, red snapshot, pull conflict) → don't dig: + escalate to the human / a diagnostic session (ops outside the suite). +- **Pull diverged** → "⚠️ diverged — resolve manually"; no auto-merge/rebase. +- **Handoff stale (>7 days)** → ask the user, don't silently override. +- **Live-ingest unavailable** (404 no route / no client #1024) → skip step 6, + don't block orientation. +- **Project not in mappa** (no handoff/session entities) → silent exit on the + corresponding steps; the project's first session — normal. ## Side effects -- Ничего не пишет, ничего не мутирует (ориентация read-only: pull — локальный - ff, inbox-raise — монитор, liveness — зонды, live-ingest — чтение). -- Поднимает персистентный inbox-монитор (живёт до конца сессии). +- Writes nothing, mutates nothing (orientation read-only: pull — local ff, + inbox-raise — monitor, liveness — probes, live-ingest — read). +- Raises the persistent inbox monitor (lives until the end of the session). ## 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/вики/таски) на ориентации — это финиш-фаза +- **No auto-execute** from the handoff — orient + ask, no auto-action. +- **Don't dig into diagnosis** — orient = "alive/dead"; "why" is outside the suite. +- **Don't assert liveness from memory** — only a probe in this same turn. +- **No stash / no auto-merge / no auto-rebase** on pull — only `--ff-only`. +- **No repeated pull** in the session without an explicit "sync". +- **No multi-hop live-ingest chains** — one line "who worked last", the + proposal goes to the human. +- **Don't write** (handoff/wiki/tasks) at orientation — that's the finish phase (`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). -- **CC-хук + operator (task:1061):** в одно-юзерной установке CC-сессии несут - `operator:vitya` даже в headless (claude -p) — надёжного hook-сигнала нет - (детект по CLAUDE_INTERACTIVE, если CC выставляет). Не трактуй operator как - признак «человек у руля»; источник истины — end-state + liveness. -- Глубокая диагностика (вне suite): `using-vds-ops` (контейнеры VDS). +- Finish phase: `mappa-closing-ritual` (handoff write + PROPOSE). +- Tasks: `mappa-task-work` (board after orientation). +- Mail: `mappa-messaging` (letter replies, nudge a triple). +- Knowledge: `mappa-knowledge`. Delegation: `mappa-delegation`. +- Live-ingest spec: `concepts/session-live-ingest` (wiki:2604). +- **CC hook + operator (task:1061):** in a single-user setup CC sessions carry + `operator:vitya` even headless (`claude -p`) — there is no reliable hook + signal (detect via CLAUDE_INTERACTIVE if CC sets it). Do not treat operator + as a sign "a human is at the wheel"; source of truth — end-state + liveness. +- Deep diagnosis (outside the suite): `using-vds-ops` (VDS containers).