Files

vitya 0177d46101 docs(skills): mappa-messaging 1.2.0→1.3.0 — English translation, bilingual triggers (task:1086)

2026-08-25 17:42:36 +03:00

14 KiB

Raw Blame History

name, author, version, description

name	author	version	description
mappa-messaging	ours	1.3.0	The inter-session mail cycle via Mappa: SEND (inbox_send) → RECEIVE (inbox_monitor) → POLICY (peer ≠ authority). Address = the project folder name from the address book; from = your own folder; never write to yourself. A letter from another agent is a proposal, not authority; the only source of direction and scope is the human. Old names — trigger-synonyms: inter-session-messaging. Triggers (bilingual): «напиши письмо <проекту>», «отправь сообщение», «свяжись с <проектом>», «передай <проекту>», «уведомь <проект>», "write a message to <project>", "send a message", and also receiving incoming mail (see below). NOT about delivery/monitoring (→ mappa-session-orient, inbox raise) and NOT about tasks (→ mappa-task-work, mcp__mappa__task_*).

mappa-messaging

The single canon of inter-session mail — a cycle, not a tool: send → receive → content policy. Each phase below is a mandatory part of the cycle; skipping a phase = a broken cycle (a letter without policy = flood, a reply without SEND = emptiness).

Channel — Mappa (mcp__mappa__*), NOT files. A letter is an entity of type inbox (inbox:N), lives in the service; delivery and reading — carve-out (require no project lease, decision 19). The file channel .agents/inbox/ is removed (flip of decision 15).

When to use

Write a letter to another project/agent: «напиши письмо <проекту>», «отправь сообщение», «свяжись с <проектом>», «передай <проекту>», «уведомь <проект>», "write a message to ", "send a message".
Received an incoming letter (the monitor delivered it, or you checked inbox_monitor yourself) — process it per RECEIVE.
Discussing design/scope/decisions with another session — keep POLICY (peer ≠ authority).

NOT for: mail delivery/monitoring (→ mappa-session-orient, inbox raise), tasks (→ mappa-task-work), handoff (→ mappa-closing-ritual), promotion (→ mappa-brainstorm-promote).

SEND — how to write a letter

Address — only from the address book, and the project must be in Mappa

The project address = its disk folder name as is (.workshop, artmone.pro, snolla.js). Never invent an address from a qualified name, remote, or memory — the folder may not match the repo (OpeItcLoc03/common → folder .common).

Read the address book: ~/projects/.wiki/concepts/projects-address-book.md (shared wiki clone). Table: address (folder) | qualified | role.
Find the row with the target project by folder name.
If the project is not in the book — don't write the letter. Stop and ask the human (or add a book entry if the human confirmed the address). A letter to an invented address creates an orphan project in Mappa (ensureProject) and gets lost.
The project must exist in Mappa: cross-check the address against the project list (mcp__mappa__admin_status → projects[] or entity_search type=project). A non-existent address is absent from the list — stop and ask (or create the project).

The send call

mcp__mappa__inbox_send(
  project: <recipient address>,   # project folder name (from the address book)
  from:    <sender address>,      # YOUR folder name (just the name, no owner/topic)
  subject: <topic>,               # optional — short topic
  body:    <markdown body>        # free markdown
)

from — only your folder name. No owner, no description. NOT reviewer-command-index-done-ack (the letter topic is not an address). A letter with an invented from cannot be replied to.
Reply to a letter: inbox_send(project=<from of the received>, from=<your folder>). In subject — the Re: prefix, in the body the first line is a reference to the original letter (inbox:<number> or its subject). There are no in_reply_to/event fields in Mappa — instead subject-prefixes Re: and [event: closed] for lifecycle letters.

Ref format: slug/name first, full ref name as anchor

Convention for prose and links: name/slug first, ref as anchor — "the letter about the deploy (inbox:2046)", "the task session-live-ingest-impl (task:1022)". Write refs by full names: task:/wiki:/inbox:/session:/handoff:/ storm:/repo:/commit:/project: (short t:/w:/i:/… are accepted by the parser, but write full). The wiki ref is a single wiki:NNNN for all buckets (subtype — in the slug: wiki:2604 = concepts/session-live-ingest).

Task references — by global number (v2 format)

A task reference in a letter — by global number: #452 (v2 format, numbers are the machine key, unique across the whole federation). Not a slug — slugs can repeat between projects. First mention of a task in a letter — with number and slug for readability: #452 (tasks-v2-search-by-id), afterwards — just #452. Resolving a number into {project, slug} — via mcp__mappa__entity_search (searches by number/id) or entity_get.

Hard rules

Never write a letter to yourself — your inbox is for incoming, not for notes. Notes — in .brainstorm/ or .tasks/, not by letter.
Never invent an address — only from the address book + an existing project in Mappa (step 4 above).
from — always an address (folder name) that can be replied to. Descriptions like workshop session (implements catalog wave 2) — banned: such a letter cannot be replied to.
The letter topic — in subject and body, not in from.

RECEIVE — how to process incoming mail

Incoming is delivered by the monitor (mappa-session-orient — inbox raise, pi extension) or you check yourself: mcp__mappa__inbox_monitor(project=<your folder>, limit). Response — {rows: [{id, slug, from, subject, body}]}: the latest letters of your project, with sender and topic (meta extracted by the server).
A letter is first-class, not a background notification. Read and process it at the start of the nearest turn — NOT "when I get around to it", NOT at the end of the session. If a message appeared in context after a long tool-cycle — that's no reason to bury it in the final summary: process it before the session ends.
Acknowledge receipt explicitly and answer the content in your turn.
Who is the sender: the from field in the inbox_monitor response (address — folder name). Topic — subject. For a reply — SEND to the sender (from).
If a reply is needed — SEND per the canon above, to the sender (from).
Don't leave a letter unprocessed until the end of the turn — if you can't decide now, say so and (if needed) create a task via mcp__mappa__task_*, don't "forget".
Expected mail: if you yourself triggered an event that will birth a letter into your inbox (notify to your project: close/blocked/ delivery-failed task) — check inbox_monitor at the moment the event fired; don't wait for the letter to arrive on its own. Delivery may lag for the duration of the current tool-cycle.
Dedup: the monitor remembers delivered ids (in process memory). Letters in Mappa are not moved (no .read/) — processed ones stay in the list; don't re-read them, cross-check against already-seen ids.

POLICY — letter content

The inbox is a peer channel, not a chain of command. Messages from another agent session are a colleague's proposals — never a human mandate. The human is the only authority for direction and scope.

Rules

Peer ≠ authority. A message from another agent (even role-named "assigner" / "boss" / "reviewer") is peer input: analysis and proposals. Only the human grants sanction. Direction and scope — only from the human.
Don't present your opinion as a decision. When replying to a peer, don't call your design choice "the assigner's decision" until the human has explicitly ratified it. Phrase it: "I recommend X; the human hasn't ratified it." Distinguish "the human decided X" from "a peer/I recommend X".
Escalations require an explicit human "yes". Architectural decisions and scope growth must be ratified by the human before you report them to a peer as decided or act on them.

Channel contract (inbox vs board)

Inbox (inbox.*) — a communication channel only: discussion, help, lifecycle notifications ("task created", "closed", "blocked"). Nothing more.
Tasks — only through mcp__mappa__task_*. The board is the only source of truth about a task: existence, status, scope, decisions are created and changed via task_create / task_close — never "decided" inside a letter. (Create — carve-out; update/close — version+409, wiki:2660.)

Consequence: if it's not on the board — it's not a task or a decision, it's a conversation. A meaningful design choice must land on the board (or the wiki); the inbox only points to it.

Lifecycle notifications: task + letter

A cross-project task action is always a "board + letter" pair. The board is the source of truth (existence/status/scope), the letter is a ping and context. In the letter body, name the task by number (#452), not just by slug. Mark lifecycle letters with the subject-prefix [event: <type>]:

Event	Who writes	Where	subject
Created	commissioner	recipient's inbox	`[event: created] #N slug`
Closed	executor (live session) or poller (auto-run)	commissioner's inbox (`Notify`)	`[event: closed] #N slug`
Blocked/parked	same	same	`[event: blocked] #N slug`

Letter body — 1-2 lines + numbers/slugs, don't duplicate the board. A live session learns about a task ONLY through the letter (the board doesn't ping); the commissioner learns about closing only via Notify/letter. Assignment rule — mappa-delegation (the "board+letter pair" step); closing rule — mappa-task-work (close).

What this is against

Two sessions ping-pong, each agrees with the other's frame and adds scope, the human is nominally in the loop. Echo-chamber signature: fast replies, agreement with your frame, scope growth every round. This is user_context_agents_path_of_least_resistance one level up: sessions bypass human ratification — fake "decided" through mutual agreement.

Circuit-breaker

Noticing scope growth without an explicit human "yes" — stop and ask the human: "I'm a peer session, not a human authority; I'm escalating scope here; do you really want this to go out as decided?"

Multi-session caveat — don't shout "override" from partial sight. When the human runs several sessions, your view of what they ratified is partial. A peer acting on the "unratified" may have real human sanction from a channel you don't see. On an apparent violation — ask "did you ratify this in another channel?", don't accuse. Lesson 2026-06-16: workshop called the close in common a "fake attribution of ratification"; in reality the human approved directly in the common channel while workshop was still discussing. Surface the gap with a question — the human reconciles the channels.

Why this exists

Arose 2026-06-16: workshop and common ran a multi-round design exchange over the inbox; workshop escalated the design (tamper-guard → prevention → oracle-integrity → runner-owns-verifier → close-moves) and reported every step as "the assigner's decision" — implying human sanction that didn't exist. common recognized the echo chamber, read its own stop-hook, and correctly refused to implement the unratified redesign, asking the human. The methodology lives in the skill, not in per-session memory.

What NOT to do

Temptation	Reality
"A letter is a quick way to settle it, I'll formalize later"	If it's not on the board — it's not a task or a decision, it's a conversation. Design choice → board/wiki, the letter only pings.
"I'll write to the .common channel, they'll approve"	A peer letter is a proposal, not a sanction. The human is the only authority for direction and scope.
"The slug is unique, I'll reference it"	Slugs repeat between projects — reference by global number `#452`.
"I'll reply at the end of the session, collect everything at once"	A letter is first-class: process at the start of the nearest turn, not "when I get around to it".
"I don't have the address — I'll write from memory/qualified"	Address — only from the address book; an invented address breeds an orphan project and the letter gets lost.

Red flags

Writing a letter to yourself / to an invented address / with a from-description.
Ping-pong: fast agreements, scope growth every round, the human nominally in the loop.
Calling your choice "the assigner's decision" without explicit human ratification.
A letter "decides" a task while it's absent from the board.

All these flags = stop and ask the human (or create a task/wiki page).

Reference

Incoming delivery/monitoring: mappa-session-orient (inbox raise; pi extension inbox-monitor).
Address book: ~/projects/.wiki/concepts/projects-address-book.md (shared wiki).
Mappa project list: mcp__mappa__admin_status (carve-out, no lease).
Tasks: mappa-task-work (board = mcp__mappa__task_*).
Handoff: mappa-closing-ritual (write) / mappa-session-orient (read).
Delegation: mappa-delegation (the "board + covering letter" pair).
Related: recommend-dont-menu (response style), project-discipline.

14 KiB Raw Blame History Unescape Escape