codecartographer

CodeCartographer — это фреймворк для изучения незнакомой кодовой базы с помощью ИИ-агента для программирования и создания проверенной, не зависящей от языка спецификации реимплементации. Он распространяется как расширение Pi, MCP-сервер или готовый шаблон `.codecarto/` из файлов Markdown и YAML. Как это работает: «код» представляет собой структурированный Markdown плюс YAML внутри `.codecarto/`. `GUIDE.md` — точка входа для LLM, `workflow/pipeline.yaml` определяет фазы и зависимости, `workflow/status.yaml` хранит изменяемое состояние по проекту, а `workflow/VALIDATE.md` описывает протокол валидации. Фазы образуют DAG — контракты и протоколы могут выполняться параллельно после архитектуры, портирование ждёт обе ветки, а спецификация реимплементации идёт последней. Хост читает активный конвейер, находит следующую фазу с выполненными зависимостями, передаёт LLM инструкции этой фазы, валидирует вывод и продвигает статус. Доказательства и валидация: каждая фаза записывает меньший по объёму шаблонный артефакт с тегами доказательств в `.codecarto/findings/`, а последующие фазы перечитывают нужные им конкретные вышестоящие файлы. Находки помечаются как наблюдаемый факт, сильное умозаключение, риск переносимости, утверждение о внешнем поведении или открытый вопрос. Вывод каждой фазы завершается таблицей `## Validation`, отмечающей каждый критерий завершения как PASS, PARTIAL или FAIL с доказательством; валидация разбирает эту таблицу и перекрёстно проверяет связку доказательства и действия, а также заявленные вторичные выводы, отказываясь продвигаться при FAIL, отсутствующем выводе или нечитаемом вердикте. Среди создаваемых артефактов — карта архитектуры, отчёт о дефектах, трекер исправления дефектов, поведенческие контракты, протоколы и состояние, пакет для портирования и финальная спецификация реимплементации с модулями, сценариями приёмки и известными неизвестными. Варианты конвейера: по умолчанию используется 7-фазный глубокий аудит, разделяющий сканирование дефектов на механический и семантический проходы. Другие варианты включают scout-first (8 фаз), full-with-audit (6), full (5), defect scan (2), lite (3), architecture-only (1) и synthesis (4). Варианты можно переключать на месте без удаления находок или прогресса. Устойчивость контекста: долговременной памятью служит файловая система, а не разговор. Каждая фаза получает свежее окно контекста; завершённые находки хранятся на диске; `status.yaml` фиксирует прогресс, открытые вопросы, переносимые элементы и список задач после конвейера. Транскрипты фаз Pi хранятся в файлах и остаются доступными через `/resume`, `/tree` и `/export`. Суммаризации компактификации с учётом фаз сохраняются как контрольные точки в `.codecarto/scratch/checkpoints/`. В README отмечается, что давление на контекст внутри фазы ограничивается, а не устраняется. Интерфейсы и возможности: расширение Pi добавляет слэш-команды, живой виджет агентов, файловые сессии фаз, сводки по завершении фаз, опциональные начальные промпты под управлением LLM, отслеживание использования по фазам и перехват инструментов (bash заблокирован; edit/write ограничены `.codecarto/`). MCP-сервер предоставляет промпты фаз, валидацию и экспериментальные операции публикации/списка/переиндексации библиотеки для других агентов с поддержкой MCP. Одностраничный HTML-дашборд агрегирует прогресс, ссылки, использование и опциональную повествовательную сводку. Прямой синтез объединяет видение продукта с подтверждёнными человеком спецификациями библиотеки в план проекта с прослеживаемым происхождением, а предполётные проверки во время выполнения требуют явного подтверждения человеком перед слиянием или финализацией.