OpeItcLoc03/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(skills): mappa-session-orient 1.0.1→1.1.0 — English translation, bilingual triggers (task:1086)

Browse Source
This commit is contained in:
vitya
2026-08-25 17:42:34 +03:00
parent 41a805d66c
commit 271fcfae93
1 changed files with 108 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
skills/mappa-session-orient/SKILL.md
View File

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