factory/lib/projects-meta-mcp/docs/superpowers/specs/2026-04-30-federated-knowledge-ask-projects-design.md

Federated knowledge query — knowledge.ask_projects / knowledge.get_from

Status: design approved 2026-04-30 Repo: projects-meta-mcp Adds: 2 read-only MCP tools + 1 sync extension + 1 cache field

Problem

Сейчас knowledge.search / knowledge.get читают только из shared projects-wiki (общая мета-вики). Если знания там нет — у агента тупик. При этом локальные .wiki/ отдельных проектов могут это знание содержать (например, node-utils/.wiki/concepts/windows-yarn-exec.md — частный кейс который никто ещё не промоутил в shared).

Хотим: если в shared не нашлось → опросить конкретные другие проекты (юзер указывает имена) на предмет того же знания. Если и там нет — оформить через уже существующий tasks.create({target_project, body}).

Non-goals

• Broadcast по всем проектам. Спрашиваем только перечисленные явно — экономим токены и сетку, юзер знает кого спрашивать.
• Авто-fallback внутри knowledge.search. search остаётся узким (только shared); агент сам решает звать ли ask_projects.
• Новый "request-knowledge-prep" механизм. tasks.create уже умеет ставить задачу другому проекту — Оккам.
• Confirm-gate / dry-run. Оба новых тула read-only.

Architecture

Tools (новые, read-only)

knowledge.ask_projects(query, projects[], limit?, types?)

Ищет в .wiki/ указанных репо.

Input:

field	type	required	default
query	string	yes	—
projects	string[]	yes	—
limit	int (1–20)	no	5 (per project)
types	string[]	no	["entities","concepts","packages","sources"] (raw исключён по дефолту — тяжёлые dumps; чтобы включить, явно перечисли все 5)

Output:

{
  "asked_projects": ["foo", "bar"],
  "results": [
    {
      "project": "foo",
      "matches": [
        {"slug": "concepts/x", "type": "concepts", "title": "...", "snippet": "..."}
      ]
    },
    {"project": "bar", "error": "no wiki — repo has no .wiki/index.md"}
  ],
  "next_action_hint": "knowledge.get_from(project, slug) для полного текста; tasks.create(target_project, body) если знание не оформлено"
}

knowledge.get_from(project, slug)

Полный текст одной страницы из конкретного проекта (live через Gitea API).

Input:

field	type	required
project	string	yes
slug	string	yes — относительный путь под .wiki/ без .md, включает type-префикс (например concepts/foo или entities/bar)

Output: raw markdown body, либо {error} если не найдено.

Sync extension

Расширяем runSync в src/lib/sync-runner.ts:

• В per-repo worker добавляется параллельный getRawFile(user, repo, '.wiki/index.md', branch) рядом с уже существующим .tasks/STATUS.md.
• Если оба null → skip как и раньше. Если есть хоть один — пишем ProjectStatus.

Cache extension

В src/lib/cache.ts:

interface ProjectStatus {
  // ...existing fields
  wiki_index?: string;  // NEW — raw .wiki/index.md, undefined если нет
}

Один общий cache.json, не плодим параллельный кэш.

Index parser

Новый src/lib/wiki-index-parser.ts:

• Парсит canonical index.md (формат из src/lib/wiki-writer.ts freshIndexMd() / insertIndexEntry()).
• Возвращает Array<{slug: string; type: WikiPageType; title: string}>.
• Структура — секции по типам, под каждой list - [title](type/slug.md).

Read flow ask_projects

1. readCache(cacheFile) → найти проекты из projects[] параметра по name.
2. Для каждого:
   • wiki_index === undefined → {project, error: "no wiki — ..."}
   • Иначе: парсим index, фильтр по types, substring case-insensitive по slug + title против query.
   • Берём первые limit совпадений.
   • Для каждого — backend.getRawFile(user, project, '.wiki/' + type + '/' + slug + '.md', branch) (concurrency-pool).
   • Из body вырезаем snippet (~80 char вокруг матча, как в knowledge.search).
3. Если проекта нет в кэше → {project, error: "unknown project — run sync first"}.
4. Если live fetch упал → matched entry с snippet: "(fetch failed)", slug+title сохраняем.

Read flow get_from

1. readCache → найти project → default_branch.
2. backend.getRawFile(user, project, '.wiki/' + slug + '.md', branch) — slug включает type-префикс (тот же формат что отдаёт ask_projects в matches[].slug).
3. null → error page not found: <project>/.wiki/<slug>.md.

Matching semantics

Реплицируем knowledge.search:

• Substring case-insensitive
• Сначала по slug + title (на index)
• Потом по body (для snippet) при fetched-странице
• raw тип исключён по дефолту (тяжёлые dumps); включается явным перечислением — types: ["concepts","raw"] или все 5 типов

Error branches

Случай	Поведение
Index.md отсутствует в репо	{project, error: "no wiki"} — тихо, остальные проекты обрабатываются
Project не в cache.projects[]	{project, error: "unknown project — run sync first"}
Live fetch страницы упал	matched entry с snippet: "(fetch failed)"
Парсинг index.md упал	{project, error: "wiki index malformed: <reason>"}
backend не сконфигурирован (auth.toml нет)	tool возвращает error — как сейчас у write-tools

Configuration

Новых конфиг-полей нет. Целевые проекты передаются параметром projects[]. Sync уже знает все репы юзера через listUserRepos.

Testing

Все новые тесты — vitest, stub Backend. Никаких реальных Gitea-вызовов.

Файл	Что покрывает
tests/lib/wiki-index-parser.test.ts	Валидный index.md, пустые секции, поломанный markdown, nested slugs (concepts/foo/bar)
tests/lib/sync-runner.test.ts (расширение)	wiki_index подтягивается параллельно с STATUS.md; репо только с .wiki/ без .tasks/ попадает в кэш; ни того ни другого → skip
tests/tools/knowledge-ask-projects.test.ts	Match по slug+title, default types-фильтр (raw исключён), limit per project, error-branches (no wiki, unknown project, fetch fail, malformed index), partial success (один проект упал, другие отдали)
tests/tools/knowledge-get-from.test.ts	Happy path, project not found, page not found

Files

New:

• src/lib/wiki-index-parser.ts
• tests/lib/wiki-index-parser.test.ts
• tests/tools/knowledge-ask-projects.test.ts
• tests/tools/knowledge-get-from.test.ts

Modify:

• src/lib/cache.ts — wiki_index?: string в ProjectStatus
• src/lib/sync-runner.ts — параллельный getRawFile для .wiki/index.md
• src/tools/knowledge.ts — 2 новых тула, описания включают цепочку с tasks.create для случая "знания нет"
• src/server.ts — проверить что cacheFile + backend пробрасываются в makeKnowledgeTools (уже частично есть)
• tests/lib/sync-runner.test.ts — расширить existing

Implementation phases

1. Parser — wiki-index-parser.ts + тест.
2. Cache + sync — поле wiki_index, расширенный runSync, тесты.
3. ask_projects — тул + тест.
4. get_from — тул + тест.
5. Wiring — server.ts deps + description тулов с hint про tasks.create.
6. Smoke — npm run build, реальный sync, ручной вызов из новой Claude-сессии.

Out of scope (для будущих итераций)

• Авто-suggest проектов в response от knowledge.search (heuristic / тематический mapping).
• Federated write — пробрасывать ingest сразу в чужой репо (можно уже сейчас через knowledge.ingest({target_project: "foo", ...}) — есть в MVP-4).
• Кэширование тел страниц (сейчас кэшируем только index — это компромисс размер/свежесть).