docs(skills): mappa-session-orient 1.0.1→1.1.0 — English translation, bilingual triggers (task:1086)
This commit is contained in:
@@ -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=<name>, 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=<cwd>`; 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=<cwd>`; opt-in — the string
|
||||
`inbox monitor: raise on start` in AGENTS.md, live re-check every tick). Sweep:
|
||||
`mcp__mappa__inbox_monitor(project=<name>)` — 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 → «вёл
|
||||
<runtime>@<machine>, не завершена» (краш-детект).
|
||||
3. **«Другая связка + не завершена»** → предложить (peer-канон, решение за
|
||||
человеком): забить / дернуть письмом (`mappa-messaging`: письмо той связке)
|
||||
/ продолжить самому.
|
||||
4. **Same-triple (`/resume`):** та же связка {runtime, machine, folder} → догрузить
|
||||
остаток (пи-нативный resume или бриф из mappa).
|
||||
1. `mcp__mappa__session_list(project=<name>, 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 →
|
||||
"<runtime>@<machine> 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).
|
||||
|
||||
Reference in New Issue
Block a user