forgeplan reindex

Перестраивает поисковый и метаданный индекс LanceDB из файлов markdown в .forgeplan/. Это операция только для чтения ваших источников markdown - файлы .md являются источником истины (ADR-003), а lance/ - это производный, игнорируемый Git-ом кеш, который всегда может быть пересчитан.

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

forgeplan reindex

Опции

  -h, --help     Вывести справку
  -V, --version  Вывести версию

Что делает команда

1. Сканирует каждую директорию артефактов в .forgeplan/ (adrs, rfcs, prds, epics, specs, evidence, problems, solutions, notes, refresh).
2. Парсит YAML frontmatter + тело markdown каждого файла.
3. Перестраивает таблицы LanceDB (artifacts, links, tags, events).
4. Пересчитывает производные поля (входные данные для оценки R_eff, канонизация тегов).
5. Оставляет ваши файлы markdown нетронутыми.

Когда запускать

• После git clone - .forgeplan/lance/ игнорируется Git-ом и не существует при свежем извлечении. Запустите forgeplan init -y && forgeplan reindex, чтобы инициализировать рабочее пространство.
• После ручного редактирования markdown - если вы редактировали файлы PRD/RFC вне CLI (текстовый редактор, поиск и замена), reindex синхронизирует изменения в LanceDB, чтобы search, list и health их видели.
• После git pull, который принес новые артефакты от коллег - см. также forgeplan git-sync для инкрементального варианта.
• Восстановление после повреждения - если lance/ поврежден или схема LanceDB мигрировала, полная переиндексация восстанавливает данные из markdown.
• Миграция схемы - новые столбцы LanceDB при обновлении Forgeplan требуют переиндексации для их заполнения.

Пример

# Инициализация после свежего клонирования
git clone <repo> && cd myproject
forgeplan init -y
forgeplan reindex
forgeplan list       # проверка

# После редактирования PRD в текстовом редакторе
vim .forgeplan/prds/prd-001-auth.md
forgeplan reindex
forgeplan search "auth"

Безопасность

reindex безопасно запускать в любое время. Он никогда не записывает в файлы .md, только в производный индекс lance/. Если вы не уверены, синхронизирован ли индекс, просто запустите его - затраты заключаются в сканировании вашего дерева артефактов (секунды для типичных рабочих пространств).

Примечание к v0.18.0 (PROB-027)

До v0.18.0 reindex предполагал, что .forgeplan/lance/ уже существует и мог завершиться ошибкой при свежих клонированиях. Начиная с v0.18.0 команда инициализирует директорию индекса, если она отсутствует, поэтому рабочий процесс “клонирование → переиндексация” теперь работает полностью без отдельного шага init в существующих рабочих пространствах.

Очистка сиротских связей (хотфикс v0.17.1)

Начиная с v0.17.1 (PROB-028, PRD-044) reindex выполняет проход Фазы 3, который удаляет сиротские связи - ссылки в таблице relations, чей исходный или целевой артефакт больше не существует в таблице artifacts.

До v0.17.1 удаление или отмена артефакта оставляло его строки связей в LanceDB. Эти сиротские ссылки приводили к появлению фантомных строк ? в выводе forgeplan tree и завышали количество ссылок в forgeplan health. Фаза 3 удаляет их и выводит счетчик:

Reindex complete: 147 artifacts, 3 removed (corrupt kind), 5 orphan relations trimmed

Причины удаления, сообщаемые в выводе:

Причина	Что произошло
corrupt kind field	Строка с непарсируемым полем kind - нет допустимой директории
no .md file found	Строка LanceDB без соответствующего файла markdown
orphan relation (source missing)	Связь, указывающая от удаленного артефакта
orphan relation (target missing)	Связь, указывающая на удаленный артефакт
orphan relation (both missing)	Оба конца связи отсутствуют

Когда запускать

• После массовых удалений - если вы вручную удалили несколько файлов .md.
• После ручного удаления .md - rm .forgeplan/prds/prd-old.md оставляет висячую строку LanceDB до тех пор, пока вы не переиндексируете.
• Начало сессии после git pull - коллеги могли отменить или удалить артефакты в своих ветках.
• После обновления с версии до v0.17.1 - одна переиндексация очищает все накопленные сиротские связи из эпохи до исправления.

reindex против scan-import

• reindex - целенаправленное перестроение LanceDB из текущего состояния markdown. Используйте в обычной повседневной работе.
• scan-import - низкоуровневый сканер, который также может импортировать устаревшие/внешние артефакты в новое рабочее пространство. Предпочтительнее использовать reindex, если вы не выполняете одноразовый импорт или миграцию.

См. также

• Обзор CLI
• forgeplan scan-import - массовый импорт + пересканирование
• forgeplan git-sync - инкрементальная синхронизация после pull
• forgeplan watch - непрерывный демон автосинхронизации
• forgeplan health - проверка целостности индекса