adr-reindex

ADR の再インデックス

adr-index は行の追加またはアップサートのみを行い、行を削除する方法はありません。ADR ファイル（または残存するファイル内の単一の関連行）を削除しても、adr-index が書き込んだ行は、その行を指す孤立参照も循環参照もないまま、その後の adr-index の実行後も永続的に残ります。その結果のグラフでは、出入りするエッジがゼロの孤立行はどちらのチェックでも検出されないため、adr-verify は正常と判定します。issue #2666 を参照してください。

これは、古さ（ADR が変更されたのに、保存済みのレコードが更新されていない状態）とは異なる障害モードです。古さへの対応は収束であり、adr-index の役割です。こちらは刈り取りです。信頼できる情報源（ADR ファイル）がなくなったため、それから派生したキャッシュ行も削除する必要があります。刈り取りを確実に行う唯一の方法は、両方の名前空間を削除し、現時点でディスク上にある内容から再構築することです。

使用するタイミング

• ADR ファイルを削除した後（またはファイルから関連行を削除した後）
• 定期的な調整として（adr-verify では adr-reindex が検出する問題を検出できません。以下を参照）
• adr-verify の ADR 件数が find docs/adr -name '*.md' | wc -l より多い場合

手順

node plugins/ruflo-adr/scripts/reindex.mjs

任意の環境変数：

• REINDEX_FORMAT=json — Markdown の代わりに JSON を出力します
• REINDEX_DRY_RUN=1 — 実行内容を報告し、何も削除・書き込みしません
• ADR_ROOT=/path — スキャンするルートと、基盤となる memory purge／memory store サブプロセスの実行ルートの両方を指定します（adr-index を最後に実行したときのルートと一致させる必要があります。一致しないと、別のリポジトリの名前空間を調整してしまいます）

動作内容

1. 削除 — memory purge --namespace <ns> --force を使い、adr-patterns と adr-edges のすべての行を完全に削除します（CLI の実際の DELETE FROM memory_entries を実行します。memory delete のソフト削除では、同じキーへの再保存が引き続き妨げられます。「adr-index + memory delete を使わない理由」を参照してください）。
2. 再構築 — ディスク上に現在存在するすべての ADR を再スキャンし（adr-index と同じデュアル形式パーサーを使用）、新たに保存します。
3. 事後条件 — adr-patterns を再度一覧表示し、その件数がスキャンした ADR ファイル数と一致することを検証します。これは adr-index の「N 件保存、エラー 0 件」という集計よりも厳密です。同時に実行された memory.db の書き込み処理が削除を上書きした場合（「注意事項」を参照）、保存ループではすべての呼び出しが成功と報告されます。新たな件数確認だけがそれを検出できます。

事後条件に失敗すると、ゼロ以外の終了コードで終了します。

adr-index + memory delete を使わない理由

memory delete はソフト削除（UPDATE ... SET status='deleted'）です。行は UNIQUE(namespace, key) のスロットを占有し続けるため、後から同じキーで memory store をアップサートなしで実行しても失敗します。memory cleanup が削除するのは、経過時間／TTL／品質に基づくエントリだけであり、「元のファイルがまだ存在するかどうか」ではありません。孤立という概念はありません。どちらの方法でもグラフをクリーンな状態には戻せません。実際に名前空間を指定した DELETE FROM を実行する必要があり、memory purge（およびこのスキル）はそれを使用します。

注意事項

• 取り消し不可です。 差分ではなく、名前空間全体を削除します。手順 2 ですぐにディスク上の最新の真実から再構築するため、この処理では常に安全ですが、この手順以外で adr-patterns／adr-edges に対して memory purge を直接実行しないでください。
• #2621（未対処）： 削除処理は、同じ memory.db に対する別の削除／パージ処理とはロックによって競合を防ぎますが、すべての書き込み処理との競合を防ぐわけではありません。sql.js のフォールバック経路でデーモンまたは MCP サーバーが読み取り・変更・書き込みサイクルの途中にある場合、後から古いイメージを書き戻し、今回削除した内容を復元する可能性があります。事後条件チェックは、この事態を検出するためのものです。失敗した場合は、このスキルを再実行してください。
• このルートではスキャンされなかった ADR を参照する、リポジトリ間の related／depends-on エッジ（孤立参照ではなく、正当な兄弟リポジトリへの参照）は、adr-edges の他のすべての内容と同様に再構築時に削除されます。兄弟リポジトリの ADR が同じ実行でインデックス化された場合にのみ復元されます。これは adr-verify のドキュメントにも記載されている「孤立参照の一般的な原因は兄弟リポジトリ」という注意事項と一致しており、このスキルによって新たな不整合が生じるわけではありません。

相互参照

• adr-index — 収束（追加／アップサート）；このスキルは削除されたものを取り除きます
• adr-verify — 読み戻し整合性チェック；再インデックス後に実行し、adrCount がディスク上の件数と一致することを確認します
• scripts/reindex.mjs — 実装
• ADR-0002（docs/adrs/）— このスキルの決定記録