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

name, author, version, description

name	author	version	description
mappa-session-orient	ours	1.1.0	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

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).

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

• 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 (order — the ritual)

1. Contract

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, full cycle)

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 part)

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)

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 summary (using-system-snapshot) — "alive/dead"

One or two probes in the current turn, compress into 3–4 lines, no raw dumps:

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 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 (consumer of session-live-ingest, #1022/#1024)

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=<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 → "@ 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).

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

• 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

• 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

• 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

• 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).