feat(skills): интерактивный контракт (wiki:2660) — выпил claim/TTL/heartbeat из mappa-* скилов (#1040)

- mappa-task-work 1.0.0→1.1.0: «взять таску» = task_update(status=active, owner=<сессия>, version) + 409-retry; release = status=ready; close с version; heartbeat убран (живость из session live-ingest); MCP-таблица и loop-mode обновлены
- mappa-knowledge 1.0.0→1.1.0: wiki_create карв-аут, wiki_update version+409; лиз-секция убрана
- mappa-delegation 1.0.0→1.1.0: task_create карв-аут, close/update version+409
- mappa-brainstorm-promote 1.2.0→1.3.0: create карв-аут, 422 busy → 409-семантика
- mappa-messaging 1.0.0→1.1.0: task_create/close карв-аут + version+409
- mappa-closing-ritual: task_close version+409 (упоминания)

Откат claim-механики из скилов; контракт = wiki:2660.
This commit is contained in:
2026-08-25 00:27:25 +03:00
parent aa80e9faa5
commit ae45a51420
6 changed files with 109 additions and 106 deletions

View File

@@ -1,7 +1,7 @@
---
name: mappa-knowledge
author: ours
version: 1.0.0
version: 1.1.0
description: >
Цикл работы со знаниями проекта в Mappa (Karpathy LLM Wiki, канал =
mappa-сущности): ingest → query → lint + граф-слой для
@@ -11,7 +11,7 @@ description: >
«что связывает X и Y», «как связаны», «путь между X и Y», «what connects
X and Y», «что ссылается на X», «backlinks of X», «сироты», «битые ссылки»,
«orphan pages». Wiki = сущности type=wiki (чтение — карв-аут лиза; запись —
под лизом проекта, решение 19). Реляционные вопросы — через graph_* (BFS на
version+409, wiki:2660). Реляционные вопросы — через graph_* (BFS на
стороне сервиса), guarded failure-mode: одна страница и стоп, без
многохоповых цепочек чтением. Skip для одно-страничных контентных вопросов.
---
@@ -25,7 +25,7 @@ query / lint) + **граф-слой** для реляционных и стру
сущностями читают через граф (graph_*).
Канал — Mappa (`mcp__mappa__*`), НЕ файлы. Страница — сущность `type=wiki`
(`wiki:N`); чтение — карв-аут лиза, запись — под лизом проекта (решение 19).
(`wiki:N`); чтение — карв-аут, запись — version+409 (wiki:2660).
Файлового `.wiki/` больше нет; `setup-wiki` умер (нечего настраивать).
## Когда использовать
@@ -66,19 +66,17 @@ README/ADR (не персистентная база знаний), проект
|---|---|---|
| Чтение страницы | `mcp__mappa__wiki_get(project?, slug)` | чтение — карв-аут (решение 19) |
| Поиск страниц | `mcp__mappa__entity_search(q, type='wiki', project?, scope?, limit)` | ILIKE по body/title |
| Лиз для записи | `mcp__mappa__task_claim_next(project, owner)` | → `token`; таска может отсутствовать |
| Продление лиза | `mcp__mappa__task_heartbeat(project, claim_token)` | долгие ingest-циклы |
| Создать страницу | `mcp__mappa__wiki_create(project, slug, body, claim_token)` | под лизом |
| Обновить страницу | `mcp__mappa__wiki_update(project, id, title?, body?, claim_token)` | под лизом; id — internal |
| Создать страницу | `mcp__mappa__wiki_create(project, slug, body)` | карв-аут (wiki:2660), лиз не нужен |
| Обновить страницу | `mcp__mappa__wiki_update(project, id, title?, body?, version)` | version+409; id — internal |
| Путь между сущностями | `mcp__mappa__graph_path({from, to})` | кратчайшая цепочка, BFS |
| Соседи / исходящие | `mcp__mappa__graph_neighbors({id})` | рёбра узла с резолвом целей |
| Входящие ссылки | `mcp__mappa__graph_backlinks({id})` | кто ссылается на узел |
| Здоровье графа | `mcp__mappa__graph_stats()` | nodes/edges/components |
**Запись всегда под лизом.** Мутации wiki гейтятся лизом проекта: без
валидного `claim_token` — 422 busy. Лиз экспирится по TTL (дефолт 600s);
закрыть вручную нечем (кроме `admin_release_lease` для залипших) — пиши,
затем отпусти (не держи лиз на время чтения/размышлений).
**Запись — version+409 (wiki:2660 interactive contract).** `wiki_create`
карв-аут (лиз не нужен); `wiki_update` несёт `version` из последнего чтения,
конфликт → 409 → `wiki_get` заново → retry. Долгих лизов/TTL/heartbeat больше
нет — живость владельца из session live-ingest.
**Рефы и id (#1037/#1028).** Публичная поверхность несёт per-type реф полным
именем первым полем: `ref: "wiki:3"` (решение 20, конвенция #1028), `num`
@@ -99,7 +97,7 @@ per-type рефы полными именами (`[[task:N]]`/`[[inbox:N]]`).
3. Создай `sources/<slug>` — одну страницу-резюме на источник (~50150 строк;
ссылку на raw клади в frontmatter `raw_path` + `ingested:`).
4. Для каждой затронутой страницы:
- есть → обнови (`wiki_update(project, id, body, claim_token)`). **Противоречия
- есть → обнови (`wiki_update(project, id, body, version)`). **Противоречия
помечай явно** блоком `> **Противоречие:** источник A говорит X, источник B — Y`.
Не затирай молча.
- нет → создай (`wiki_create`).
@@ -115,9 +113,8 @@ per-type рефы полными именами (`[[task:N]]`/`[[inbox:N]]`).
**Один ingest может затронуть 1015 страниц. Это нормально — для того LLM и нужны.**
Порядок записи: сначала лиз (`task_claim_next`), затем все wiki-мутации одним
циклом (не бери лиз на чтение), затем отпусти (лиз живёт TTL — просто закончи
писать; heartbeat только если цикл реально долгий).
Порядок записи: все wiki-мутации одним циклом; `wiki_update`со свежей
`version` из чтения (409 → retry). Создание новых страниц — карв-аут.
### Query — вопрос по вики
@@ -234,7 +231,7 @@ level/since/component/entity, retention 14d). Ручную `log`-страниц
- **Не-ASCII слаги.** Ломают grep и кросс-платформенность. Транслитерируй.
- **Пропущенные противоречия в lint.** Ценность вики — во вскрытых напряжениях,
а не в ложном консенсусе.
- **Запись без лиза.** Wiki-мутации без `claim_token` → 422 busy.
- **Запись — version+409 (wiki:2660).** `wiki_create` — карв-аут; `wiki_update` со свежей `version` (конфликт → 409 → retry).
- **Держать лиз на чтение/раздумья.** Лиз — на время записи. Чтение — карв-аут.
- **Реляционный вопрос чтением одной страницы.** Это тот самый 0%-recall
провал — зови graph_*.