wiki

name	wiki
description	Use when working with the project wiki layer — new reports in docs/reports/ are not yet covered in wiki/index.md, a new concept needs to be saved, session needs wiki context, or pages may be stale

Wiki Operations

Overview

Workflow для работы с LLM Wiki — слоем синтезированных знаний проекта.

Когда использовать

• Ingest: после появления новых отчётов в docs/reports/ — синтезировать выводы в wiki-страницы.
• Save: при обнаружении нового концепта или инсайта, который не укладывается ни в один существующий файл проекта.
• Query: в начале сессии или при исследовании темы — прочитать релевантные wiki-страницы для контекста.
• Lint: пользователь просит проверить актуальность wiki-страниц.

Принципы

1. Wiki — persistent artifact. Страницы живут между сессиями и накапливают знания. Это не scratch pad.
2. LLM writes, Human directs. Агент создаёт и обновляет страницы, пользователь решает что исследовать и когда.
3. Знание компилируется один раз. Если вывод получен из 5 отчётов, он записывается в wiki-страницу, а не пересинтезируется каждый раз.
4. Wiki ≠ копия. Страницы содержат только синтез, которому нет канонического места в проекте. Не дублировать:
   • Архитектуру → AGENTS.md, docs/DATA_FLOW.md
   • Модули → MODULE_INDEX.md
   • Текущее состояние → CONTEXT_HANDOFF.md
   • Сырые результаты → docs/reports/
5. knowledge-rag ≠ source of truth. MCP server knowledge-rag нужен для поиска кандидатов; выводы фиксируй только после чтения найденных первоисточников.

Структура wiki/

wiki/
├── index.md          # Каталог wiki-страниц (LLM-maintained)
├── REPO_integrity.md # Integrity map всего репо (auto-generated)
├── log.md            # Append-only хронология операций
├── wiki.py           # Инструмент: generate / verify / status / search
├── research/         # Синтез отчётов из docs/reports/
├── concepts/         # Синтезированные концепты проекта
└── .archive/         # Устаревшие wiki-страницы (не удалять, не править)

Операции

Ingest

Синтез новых отчётов в wiki-страницы.

Hard rule: если агент прочитал новые отчёты из docs/reports/, и они ещё не покрыты в wiki/index.md, операцию Ingest нужно довести до конца в этой же задаче. Если какой-то шаг не выполнен, агент должен прямо указать это и назвать причину.

1. Запусти ./.venv/bin/python wiki/wiki.py status — покажет непокрытые отчёты, изменившиеся файлы, битые ссылки. Сравни с wiki/index.md для навигации.
2. Прочитай новые отчёты и существующие wiki-страницы по теме.
3. Реши: обновить существующую страницу или создать новую.
   • Обновить, если отчёт продолжает ту же линию исследования.
   • Создать новую, если отчёт открывает новое направление.
4. Напиши/обнови страницу (формат — см. ниже).
5. Если обнаружен новый концепт — создай страницу в concepts/.
6. Обнови wiki/index.md (добавь новые страницы, обнови покрытие).
7. Добавь запись в wiki/log.md.
8. Запусти ./.venv/bin/python wiki/wiki.py generate.

Save

Сохранение нового концепта или инсайта.

1. Убедись, что концепт действительно нуждается в wiki-странице (не дублирует существующий файл).
2. Создай страницу в wiki/concepts/ (формат — см. ниже).
3. Обнови wiki/index.md.
4. Добавь запись в wiki/log.md.

Query

Использование wiki как контекста.

1. Сначала прочитай wiki/index.md, чтобы понять существующий синтез.
2. Быстрый grep: ./.venv/bin/python wiki/wiki.py search "<термин>" — найди точные совпадения в wiki/.
3. Уточни через MCP server knowledge-rag, tool search_knowledge — смысловой поиск по проекту.
4. Открой релевантные wiki/research/, wiki/concepts/ и найденные первоисточники (docs/reports/, docs/, код).
5. Если найден новый устойчивый синтез или непокрытый отчёт — сообщи об этом и предложи Save/Ingest. Не выполняй без явного запроса.

Lint

Проверка актуальности wiki-страниц.

1. Запусти ./.venv/bin/python wiki/wiki.py status — покажет непокрытые отчёты, изменившиеся файлы, битые ссылки. Непокрытые отчёты и битые ссылки — прямые проблемы; изменившиеся файлы — проверь, влияет ли изменение на wiki-контент.
2. Для wiki-страниц с проблемами проверь:
   • Упомянутые файлы/пути всё ещё существуют.
   • Цифры и выводы соответствуют текущим отчётам.
   • Нет ли новых отчётов, которые дополняют или опровергают синтез.
3. Обнови устаревшие страницы, добавь запись в wiki/log.md.

Generate

Обновление integrity map.

./.venv/bin/python wiki/wiki.py generate

Обновляет wiki/REPO_integrity.md с актуальными хешами. Включён в Ingest (шаг 8). Запускай отдельно, если wiki-страницы правились без полного Ingest.

Формат wiki-страниц

Research (wiki/research/)

---
last_updated: YYYY-MM-DD
sources: N
status: active | completed | stale
---

# Название линии исследования

> Одна фраза — что исследовалось и какой главный вывод.

## Хронология

Краткая эволюция: какие этапы, что менялось от этапа к этапу.

## Ключевые результаты

Таблицы, цифры, сравнения — факты из нескольких отчётов.

## Выводы

Что работает, что нет, что стало понятно из совокупности отчётов.

## Открытые вопросы

Что не проверено, где нужно больше данных.

## Источники

- Ссылки на `docs/reports/` с кратким описанием каждого.

Concepts (wiki/concepts/)

---
last_updated: YYYY-MM-DD
status: confirmed | preliminary | disputed
---

# Название концепта

> Одна фраза — суть концепта.

## Суть

Описание концепта: что это, почему важно.

## Детали

Таблицы, цифры, характеристики.

## Практические следствия

Как это влияет на решения в проекте.

## Где использовано

Ссылки на wiki-страницы и отчёты, где концепт применяется.

## Источники

Ссылки на первоисточники (отчёты, код).

Правила

• Одна страница = одна линия исследования или один концепт. Не смешивать.
• Всегда указывать источники (docs/reports/, код).
• Каждая операция = запись в wiki/log.md.
• wiki/index.md — всегда актуален (обновлять при любом изменении страниц).
• Для research/: создавать страницу когда отчёт приносит новое знание.
• Для concepts/: создавать когда концепт устойчив и подтверждён данными.
• При обновлении страницы — не переписывать историю, а дополнять хронологию.