diff --git a/skills/mappa-closing-ritual/SKILL.md b/skills/mappa-closing-ritual/SKILL.md index 3ad4b95..571c3ed 100644 --- a/skills/mappa-closing-ritual/SKILL.md +++ b/skills/mappa-closing-ritual/SKILL.md @@ -1,148 +1,152 @@ --- name: mappa-closing-ritual author: ours -version: 1.2.0 +version: 1.3.0 description: > - Финиш-фаза форкфлоу: handoff write (mcp__mappa__handoff_write, версия h:N) - + PROPOSE wiki-ingest + PROPOSE закрытий тасок. Мутации — только после - подтверждения пользователя. Ad-hoc: mode=light — явный вопрос «Сделать - handoff?» в конце сессии (НЕ автоматический sweep), решение за человеком. - Старое имя — триггер-синоним: session-handoff (write-часть). Чтение на - старте — mappa-session-orient. Триггеры: «завершаем сессию», «сворачиваемся», - «закругляемся», «wrap up session», «end session», «we're done for now». - Анти-триггеры (task-зона, не session-end): «закрываем эту таску», «pause», - «отбой», «разбегаемся». + Finish phase of the forkflow: handoff write (mcp__mappa__handoff_write, + version h:N) + PROPOSE wiki-ingest + PROPOSE task closes. Mutations — only + after user confirmation. Ad-hoc: mode=light — an explicit question "Write + handoff?" at the end of the session (NOT an automatic sweep), the decision + is the human's. Old name — trigger-synonym: session-handoff (write part). + Reading at start — mappa-session-orient. Triggers (bilingual): «завершаем + сессию», «сворачиваемся», «закругляемся», "wrap up session", "end session", + "we're done for now". Anti-triggers (task-zone, not session-end): + «закрываем эту таску», «pause», «отбой», «разбегаемся». --- # mappa-closing-ritual -Финиш-фаза цикла агента: **записать handoff → предложить wiki-ingest → -предложить закрытия тасок**. Старт ≠ финиш: чтение handoff на старте — -`mappa-session-orient`; здесь — write-путь с процедурой и подтверждением. +Finish phase of the agent cycle: **write handoff → propose wiki-ingest → +propose task closes**. Start ≠ finish: reading the handoff at start — +`mappa-session-orient`; here — the write path with procedure and confirmation. -Канал — **handoff-сущность Mappa** (`mcp__mappa__handoff_write`, тип `h:`, -per-project): поля `session_id`/`date`/`status`/`summary`/`open_treks[]`/ -`ask_user[]`/`guards[]`/`recent_commits[]`. Каждый write = **новая версия** -(append-only, versioned-история). Файлового `.tasks/NEXT_SESSION.md` больше нет. +Channel — the **Mappa handoff entity** (`mcp__mappa__handoff_write`, type +`h:`, per-project): fields `session_id`/`date`/`status`/`summary`/ +`open_treks[]`/`ask_user[]`/`guards[]`/`recent_commits[]`. Each write = a **new +version** (append-only, versioned history). The file-based +`.tasks/NEXT_SESSION.md` no longer exists. -## Когда использовать +## When to use -- Session-end фразы: «завершаем сессию», «сворачиваемся», «закругляемся», - «wrap up session», «end session», «we're done for now». -- Ad-hoc-сессия без трека/таски в конце: **mode=light** — явный вопрос - «Сделать handoff?» (не автоматический sweep), решение за человеком. -- AGENTS.md проекта содержит trigger-строку `session handoff: read on start, write on end`. +- Session-end phrases: «завершаем сессию», «сворачиваемся», «закругляемся», + "wrap up session", "end session", "we're done for now". +- Ad-hoc session without a track/task at the end: **mode=light** — an explicit + question "Write handoff?" (not an automatic sweep), the human decides. +- The project's AGENTS.md contains the trigger line + `session handoff: read on start, write on end`. -**Skip (task-зона, не session-end):** «закрываем эту таску» (task close → +**Skip (task-zone, not session-end):** «закрываем эту таску» (task close → `mappa-task-work`), «pause», «приостанови» (task-pause), «отбой», «разбегаемся» -(слишком broad), «сейчас завершу одну задачу и тогда поговорим» (частичное -завершение). При неоднозначности — **ASK**: «закрываем сессию или таску?» +(too broad), "let me finish one task first, then we'll talk" (partial finish). +On ambiguity — **ASK**: "are we closing the session or a task?" ## Steps ### 1. Scope check -Это текущий проект (cwd). Никаких global мутаций, никаких других проектов. +This is the current project (cwd). No global mutations, no other projects. ### 2. Mid-task capture -Если есть 🔴 active таска проекта (борд mappa / `.tasks/`) — захватить в summary: +If there is a 🔴 active task of the project (mappa board / `.tasks/`) — capture +into summary: ``` left mid-task: -where_stopped: <одна строка> +where_stopped: ``` -Без борда — писать handoff без mid-task секции, не блокировать. +No board — write the handoff without the mid-task section, don't block. -### 3. Compose content (поля handoff) +### 3. Compose content (handoff fields) -- `session_id` — `` или идентификатор сессии; -- `status` — `active` (работа продолжается) / `paused` (заморожено) / `done` (завершено); -- `summary` — связка: где остановились, mid-task, ключевые решения; -- `open_treks` — массив открытых треков (готовность + entry-point); -- `ask_user` — pending решения / ожидаемые разрешения; -- `guards` — «не делать» (preemptive guards); -- `recent_commits` — 3–5 последних коммитов (`: `). +- `session_id` — `` or session identifier; +- `status` — `active` (work continues) / `paused` (frozen) / `done` (finished); +- `summary` — the link: where we stopped, mid-task, key decisions; +- `open_treks` — array of open tracks (readiness + entry-point); +- `ask_user` — pending decisions / expected resolutions; +- `guards` — "don't do" (preemptive guards); +- `recent_commits` — 3–5 latest commits (`: `). -Forward-looking, не timeline: handoff = связка новых вещей конкретно для -следующего разворота, не overview всего проекта. Борд mappa / вики остаются -авторитетными для своего scope'а — не дублировать их в handoff. +Forward-looking, not a timeline: handoff = a link of new things specifically +for the next turn, not an overview of the whole project. The mappa board / wiki +remain authoritative for their own scope — don't duplicate them in the handoff. ### 4. Append -`mcp__mappa__handoff_write(project=<имя>, session_id, status, summary, open_treks?, ask_user?, guards?, recent_commits?)` — сервис создаёт новую версию `h:N` (предыдущие остаются; чтение последней — `entity_search(type='handoff', project, limit=1)`). Поля-массивы передавать как `[]`, если пусто (следующий агент видит: пусто, не забыто). Пишется без лиза (как инбокс). +`mcp__mappa__handoff_write(project=, session_id, status, summary, open_treks?, ask_user?, guards?, recent_commits?)` — the service creates a new `h:N` version (previous ones remain; reading the latest — `entity_search(type='handoff', project, limit=1)`). Pass array fields as `[]` when empty (the next agent sees: empty, not forgotten). Written without a lease (like inbox). -> **Confirm gate:** handoff write — мутация. В mode=light (ad-hoc) и при -> неоднозначности — сначала явный вопрос «Сделать handoff?», только после «да» — +> **Confirm gate:** handoff write is a mutation. In mode=light (ad-hoc) and on +> ambiguity — first an explicit question "Write handoff?", only after "yes" — > write. -### 5. Propose wiki-ingest (не писать!) +### 5. Propose wiki-ingest (don't write!) -Если за сессию появилось durable-знание — **ПРЕДЛОЖИТЬ** ingest -(`mappa-knowledge`: mappa wiki create — карв-аут, update — version+409, wiki:2660), перечислив кандидатов. -Ничего не писать без подтверждения. +If durable knowledge appeared during the session — **PROPOSE** the ingest +(`mappa-knowledge`: mappa wiki create — carve-out, update — version+409, +wiki:2660), listing the candidates. Don't write anything without confirmation. -### 6. Propose task-board closes (не закрывать!) +### 6. Propose task-board closes (don't close!) -Если есть задачи, выглядящие закрытыми — **ПРЕДЛОЖИТЬ** закрытия -(`mappa-task-work`: task_close с version+409, wiki:2660). Уважать ralph-loop: verifier-задачи -закрывать только через verifier (attempt/harness-record). +If there are tasks that look closed — **PROPOSE** the closes +(`mappa-task-work`: task_close with version+409, wiki:2660). Respect ralph-loop: +verifier tasks close only via the verifier (attempt/harness-record). -### 7. Формат предложения — один блок +### 7. Proposal format — one block ``` -Ритуал закрытия: -(а) заингестить X в вики? -(б) закрыть Y? -(в) ничего. +Closing ritual: +(a) ingest X into the wiki? +(b) close Y? +(c) nothing. ``` -Ждать ответа. Отказ = пропуск (не настаивать, не повторять в этой сессии). +Wait for the answer. Refusal = skip (don't insist, don't repeat in this session). --- -## mode=light (ad-hoc-сессии) +## mode=light (ad-hoc sessions) -Ad-hoc-сессия (без таски/трека, но могут рождаться артефакты): след в mappa -пишется всегда (контракт сервиса — session live-ingest), но **структурирование — -по явному вопросу**: в конце сессии спроси «Сделать handoff?» (решение за -человеком). НЕ автоматический sweep: без «да» — ничего не писать, след -остаётся в mappa как есть. +Ad-hoc session (no task/track, but artifacts may be born): the trace in mappa +is always written (service contract — session live-ingest), but +**structuring happens only on an explicit question**: at the end of the +session ask "Write handoff?" (the human decides). NOT an automatic sweep: +without "yes" — write nothing, the trace stays in mappa as is. ## Failure modes -- **Secret detected.** Контент матчит паттерны секретов (`AKIA...`, `sk-...`, +- **Secret detected.** Content matches secret patterns (`AKIA...`, `sk-...`, `ghp_...`, `ssh-rsa`, `BEGIN PRIVATE KEY`, `password=`/`token=`) → **abort - write**. Сообщить user'у с указанием подозрительной строки. -- **Неоднозначная фраза** → ASK «закрываем сессию или таску?», не угадывать. -- **Mid-task без борда** → handoff без mid-task секции, не блокировать. -- **User отказал на предложения ритуала** → пропустить, не настаивать. -- **Проект не в mappa** → silent exit (первая сессия). + write**. Tell the user with the suspicious line indicated. +- **Ambiguous phrase** → ASK "are we closing the session or a task?", don't guess. +- **Mid-task without a board** → handoff without the mid-task section, don't block. +- **User refused the ritual proposals** → skip, don't insist. +- **Project not in mappa** → silent exit (first session). ## Side effects -- Пишет handoff-сущность проекта (append-only, versioned-история). Никаких - файлов, никаких git-коммитов за handoff. -- Ритуал **предлагает** wiki-ingest и закрытия тасок — но НЕ пишет их без «да». -- Никаких global мутаций, никаких других проектов. +- Writes the project's handoff entity (append-only, versioned history). No + files, no git commits for the handoff. +- The ritual **proposes** wiki-ingest and task closes — but does NOT write + them without "yes". +- No global mutations, no other projects. ## What NOT to do -- **Не auto-execute** — каждая мутация (handoff write / wiki-ingest / task - close) только после явного «да» пользователя. -- **Не гонять ритуал на substantive commit.** Только session-end фраза (или - явный запрос user'а). -- **Не sweep автоматически в ad-hoc** — mode=light: явный вопрос «Сделать - handoff?», решение за человеком. -- **Не писать секреты** в handoff. Матч secret-patterns → abort. -- **Не писать handoff на каждый commit** — только финиш. -- **Не дублировать борд / вики** — handoff = forward-looking связка. -- **Не cross-project** — per-project scope. -- **Не считать handoff авторитетным** на стороне читателя — это рекомендация - прошлой сессии, не директива; user может override. +- **No auto-execute** — every mutation (handoff write / wiki-ingest / task + close) only after an explicit "yes" from the user. +- **Don't run the ritual on a substantive commit.** Only a session-end phrase + (or an explicit user request). +- **Don't sweep automatically in ad-hoc** — mode=light: an explicit question + "Write handoff?", the human decides. +- **Don't write secrets** into the handoff. Secret-pattern match → abort. +- **Don't write a handoff on every commit** — only at the finish. +- **Don't duplicate the board / wiki** — handoff = forward-looking link. +- **No cross-project** — per-project scope. +- **Don't treat the handoff as authoritative** on the reader's side — it's the + previous session's recommendation, not a directive; the user can override. ## Reference -- Чтение handoff на старте: `mappa-session-orient`. -- Закрытия тасок: `mappa-task-work` (pre-close coverage, notify-письмо). +- Reading the handoff at start: `mappa-session-orient`. +- Task closes: `mappa-task-work` (pre-close coverage, notify letter). - Wiki-ingest: `mappa-knowledge`. -- Письма: `mappa-messaging`. Делегирование: `mappa-delegation`. -- Session live-ingest (след в mappa пишется всегда): `concepts/session-live-ingest` (wiki:2604). +- Letters: `mappa-messaging`. Delegation: `mappa-delegation`. +- Session live-ingest (the trace in mappa is always written): `concepts/session-live-ingest` (wiki:2604).