forgeplan scan-import

forgeplan scan-import обходит файловую систему (по умолчанию - стандартные каталоги документации, или пользовательский --path), обнаруживает markdown-файлы, похожие на артефакты Forgeplan, и импортирует их в индекс LanceDB. Это основной инструмент для двух сценариев: адаптации устаревшего проекта, у которого уже есть документация, и перестроения производного индекса из отслеживаемого markdown после свежего git clone.

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

Адаптация существующих проектов (Brownfield onboarding). У вас есть существующие RFC, PRD или ADR в markdown, и вы хотите перевести их под методологию Forgeplan без переписывания.
Свежее клонирование Git. .forgeplan/{adrs,prds,rfcs,...} отслеживается в Git, но .forgeplan/lance/ - нет. scan-import перестраивает индекс из отслеживаемого markdown.
После массовых внешних правок. Если вы редактировали markdown напрямую (вне forgeplan update), scan-import повторно синхронизирует индекс LanceDB, чтобы он соответствовал изменениям.
Восстановление индекса. rm -rf .forgeplan/lance && forgeplan scan-import - это безопасный способ удалить и перестроить производный слой, не затрагивая артефакты.

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

Для восстановления резервной копии - используйте forgeplan import с JSON-файлом. scan-import читает только markdown и не может восстановить историю оценок или состояние распада.
Для создания новых артефактов - используйте forgeplan new <kind>. scan-import предназначен для обнаружения существующих файлов.
Для исправления несоответствий схемы - используйте forgeplan migrate. scan-import предполагает, что схема уже актуальна.

Использование

forgeplan scan-import [OPTIONS]

Опции

      --path <PATH>  Каталог для сканирования (по умолчанию: стандартные каталоги документации)
      --dry-run      Только предварительный просмотр, без фактического импорта
  -h, --help         Вывести справку
  -V, --version      Вывести версию

Примеры

Пример 1: Перестроение индекса после клонирования Git

git clone <repo> && cd <repo>
forgeplan init -y
forgeplan scan-import
forgeplan list

Стандартный рецепт для “свежего клонирования”. .forgeplan/lance/ игнорируется Git, поэтому каждая новая выгрузка требует init + scan-import для воссоздания производного индекса из отслеживаемого markdown.

Пример 2: Сухой запуск перед подтверждением импорта

forgeplan scan-import --dry-run

Выводит список файлов, которые будут импортированы, их обнаруженный тип артефакта и любые предупреждения парсинга - без затрагивания LanceDB. Используйте это для незнакомых устаревших репозиториев перед реальным запуском.

Пример 3: Адаптация существующих проектов с пользовательским путём

forgeplan init -y
forgeplan scan-import --path docs/architecture
forgeplan list
forgeplan health

Направляет сканер на нестандартный каталог. Полезно, когда устаревшая документация находится в docs/, architecture/ или decisions/ вместо .forgeplan/.

Пример 4: Полное перестроение индекса без повторной инициализации

rm -rf .forgeplan/lance
forgeplan scan-import
forgeplan health

Безопасно, потому что markdown является источником истины (ADR-003). Папка LanceDB является производной и всегда может быть перестроена. НЕ rm -rf .forgeplan/ - только подпапку lance/.

Как это вписывается в рабочий процесс

scan-import - это мост между необработанным markdown и индексом Forgeplan. Типичные места использования:

Начало сессии после клонирования: forgeplan init -y → forgeplan scan-import → forgeplan health
Настройка существующих проектов (Brownfield setup): forgeplan init -y --scan эквивалентно совместному запуску init и scan-import
Восстановление: rm -rf .forgeplan/lance && forgeplan scan-import после любого повреждения индекса

Поскольку markdown является авторитетным (ADR-003), эта команда идемпотентна и безопасна для многократного запуска. Она не будет дублировать артефакты - повторный запуск согласовывает индекс с файловой системой.

Примечания по безопасности

Только .forgeplan/lance/ безопасно удалять. Никогда не rm -rf .forgeplan/ без предварительного экспорта. Подпапки markdown (adrs/, prds/ и т. д.) являются источником истины и не могут быть восстановлены из LanceDB.
Сначала используйте --dry-run для незнакомых репозиториев. Сканирование может выявить файлы, которые вы не собирались импортировать (README.md, CHANGELOG.md и т. д.). Предварительно просмотрите перед подтверждением.
Прямое редактирование markdown работает, но требует scan-import для синхронизации. Рекомендуемый путь - forgeplan update, который автоматически синхронизирует оба слоя.
Сканирование учитывает frontmatter. Файлы без действительного YAML frontmatter Forgeplan (kind, id, status) могут быть пропущены или импортированы как общие Note в зависимости от эвристики обнаружения.
История оценок не восстанавливается. scan-import восстанавливает идентификацию и связи, но распад доказательств и исторические значения R_eff возвращаются только через forgeplan import из JSON-экспорта.

См. также

forgeplan init - создаёт оболочку рабочего пространства перед сканированием; init --scan объединяет оба шага
forgeplan import - восстанавливает полное состояние, включая оценки (требует JSON, а не markdown)
forgeplan export - резервное копирование перед любой деструктивной операцией
forgeplan migrate - применяет изменения схемы, не затрагивая содержимое
forgeplan health - проверяет, соответствует ли индекс ожиданиям после сканирования
ADR-003 - почему markdown является источником истины