PJR-0148 docs/外への[[id]]（wikilink）解決範囲拡張の要否検討
1. 概要
現状specdojo index buildの走査対象はdocs/配下のみで、.github/instructions/やREADME.md等docs/外のファイルは[[id]]で参照できない。docs/外への[[id]]解決範囲拡張が必要かどうかを、走査対象拡大に伴う除外ロジック変更・frontmatter契約の非互換・ID衝突リスク等を踏まえて検討する
PJR-0146の検討過程で、specdojo index build の既定走査対象が docs/ 配下に限定されているため、.github/instructions/、README.md、CLAUDE.md 等 docs/ 外のファイルは [[id]]（wikilink）で参照できないことが判明した。docs/ 外への [[id]] 解決範囲拡張が必要かどうかを、実装上の制約と費用対効果を踏まえて検討する。
1.1. 前回の判断を差し戻した理由
1回目の実行は「拡張しない」と結論したが、根拠が循環していたため差し戻した。
結論の根拠は「docs/ 外に置かれた実文書中の wikilink が 0 件」であった。しかしこれは需要の 不在を示さない。0 件である理由は次の2つで、いずれも機能が無いことの帰結である。
index buildの走査対象がdocs/配下に限られるため、docs/外に wikilink を書いても解決 しない。使えないものは使われない。.github/instructions/markdown.instructions.mdが「docs/外のファイルを参照する場合は リポジトリルートからの相対パスをインラインコードまたはプレーンテキストで書く」と定めている。 規約が wikilink を禁じている。
つまり「規約で禁じた記法が使われていないこと」を「需要がないこと」の証拠にしている。
同じ調査は逆の解釈を支持する事実も記録していた。docs/ から .github/instructions/ への参照は 42 ファイル・55 箇所あり、すべて生パスで書かれている。
| 参照先 | 箇所 |
|---|---|
vitest.instructions.md | 24 |
markdown.instructions.md | 20 |
typescript.instructions.md | 6 |
| その他 3 ファイル | 5 |
これは参照需要が無いのではなく、需要はあるが wikilink を使えないため生パスで書いている状態で ある。生パスは改名時に壊れる。wikilink が解こうとしている問題そのものが現れている。
再実行では次を守る。
- 「使われていない」を「必要でない」の根拠にしない。使われていない原因を先に確かめる。
- 生パス参照 55 箇所が改名時に負う修正コストを、拡張の費用と比べる。実際に改名が起きた履歴が あれば数える。
- 規約（
markdown.instructions.md）が生パスを求めている前提を明示する。拡張する場合はこの規約の 改訂が伴うため、費用に含める。 - 「拡張しない」が結論になること自体は妥当であり得る。費用と便益を比べた結果としてなら採用する。
2. 完了条件
docs/外への[[id]]拡張が必要な具体的なユースケース（対象ファイル種別・参照頻度）が洗い出されている。- 拡張する場合の実装上の論点（
walkDirのドット始まりディレクトリ一律除外、.github/instructions/*.mdのapplyTo:frontmatter との非互換、README.md/CLAUDE.mdのfrontmatterなし前提、ID衝突リスク）が整理されている。 - 全面拡張・限定拡張（
.specdojo/index-config.yamlのnested_id_files等を用いた対象パスの個別追加）・拡張しない、のいずれかの方針が決まっている。 - 方針が採用された場合の対応要否（実装todoの起票要否を含む）が明記されている。
- 「
docs/外の wikilink が 0 件」を需要の不在の根拠にしていない。0 件である原因（機能の不在と 規約による禁止）を踏まえた judgement になっている。 - 生パス参照 55 箇所の保守コストと、拡張の実装コストが比較されている。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | docs/ 外への [[id]] 参照ニーズの洗い出し | ARC | done | instructions への生パス参照を確認。ルート README 等を安定 ID で参照する実需要は未確認 |
| 2 | 拡張時の実装上の論点整理（除外ロジック・frontmatter契約・ID衝突リスク） | ARC | done | 走査、メタ情報、言語スコープ、一意性、設定契約への影響を整理 |
| 3 | 全面拡張/限定拡張/非対応の方針決定 | ARC | done | 参照追従実績と恒久的な実装費を比較し、現時点では拡張しない |
| 4 | 方針に応じた後続対応（実装todoの起票等）の要否判断 | ARC | done | 現時点で実装 todo は不要。再評価条件を対応結果に明記 |
4. 対応結果
現時点では docs/ 外へ [[id]] の解決範囲を拡張しない。これは外部ファイルへの参照需要が 無いという判断ではない。PJR-0146 で定めた生パス表記が実際に使われており、改名時の追従を 減らす便益はある。一方、現時点の追従費用は機械的な一括置換で対処でき、外部 ID の契約を 恒久的に導入する費用を上回らないためである。
当面は PJR-0146 の規約どおり、履歴蓄積ファイルから docs/ 外を参照するときは、リポジトリ ルート相対パスをインラインコードまたはプレーンテキストで記載する。
4.1. ユースケースと参照頻度
2026-09-04 時点のリポジトリを再計測した。差戻し時に提示された「生パス参照 55 箇所」は、 docs/ 配下の全ファイルを対象に .github/instructions/<file>.md を数えた場合に再現した。 同じ条件の参照元は 32 ファイルであり、差戻し時の「42 ファイル」は再現しなかった。内訳には executor のログと evidence JSON の 10 箇所、4 ファイルが含まれる。編集対象となる Markdown に限定すると 45 箇所、28 ファイルであり、内訳は次のとおりである。PJR-0148 自身は循環計上を 避けるため除外した。
| 参照先 | Markdown の参照箇所 | 参照元ファイル数 |
|---|---|---|
.github/instructions/markdown.instructions.md | 20 | 17 |
.github/instructions/vitest.instructions.md | 14 | 12 |
.github/instructions/typescript.instructions.md | 6 | 6 |
| その他 3 instruction | 5 | 4 |
| 合計 | 45 | 28 |
同じファイルが複数の instruction を参照するため、参照元ファイル数の合計は全体の 28 と一致しない。 この実測から、主なユースケースは履歴や設計から適用規約を参照し、instruction の移動・改名時の 追従を避けることである。docs/ 外に wikilink が 0 件であることは、機能と規約が許可して いない結果なので、需要の不在を示す根拠には用いない。
ルート README.md、CLAUDE.md、AGENTS.md の検索結果は 11 箇所だった。ルート README の 責務を扱う PJR-0145 の 1 箇所を除くと、PJR-0148 の問題記述、ファイル種別の例、または配布 テンプレートの README を指している。ルートファイルを扱う実需要は 1 タスクにあるが、同じ ファイルを安定 ID で反復参照する需要は確認できなかった。
4.2. 改名時の保守費用
現在参照されている 6 instruction の Git 履歴を確認したところ、5 ファイルは改名実績がなく、 rulebook.instructions.md だけが 2026-04-18 に rules.instructions.md から改名されている。 この改名コミットでは docs の原本 9 ファイル、生成物を含めて 21 ファイルが更新された。生パス 参照には追従費用が実在し、参照が増えれば更新対象も増えることを示している。
一方、55 箇所のうち永続的な evidence 10 箇所は過去実行の記録であり、改名時の書換対象に しない。追従対象になり得る Markdown 45 箇所は、旧パスの検索、機械的な一括置換、Markdown 検査で対処できる。同じファイル名を再利用しない限り検索で更新漏れも検出できる。改名のたびに 発生するこの変動費は無視できないが、現時点では限定 ID 機能の実装・検証・契約維持という固定費 より小さいと判断する。
4.3. 実装上の論点
- 走査境界:
src/doc-index.tsのwalkDirはドット始まりのディレクトリを一律に除外するため、走査ルートをリポジトリルートへ変えても.github/は対象にならない。例外を加える場合は、秘密情報やツール内部ファイルを誤って対象にしない明示的な許可リストが必要になる。 - SpecDojo Unit と言語スコープ: ドキュメントIDおよびファイル命名標準 は 1 つの
docs/ルートを SpecDojo Unit と定義し、docs/直下を基準にja/enを判定する。走査ルートをリポジトリルートへ広げるとこの前提が崩れ、言語 variant の判定方法も変更が必要になる。 - Frontmatter 契約: Markdown の ID 抽出は
specdojo.idを前提とする。一方、.github/instructions/*.mdは外部ツール向けのトップレベルapplyToだけを持ち、README、CLAUDE、AGENTS は Frontmatter を持たない。これらへspecdojo.id/type/statusを強制すると、SpecDojo 文書ではない設定・案内ファイルにメタ情報契約を拡張し、外部ツールとの互換性確認とスキーマ方針が必要になる。 - 設定契約: 現行
.specdojo/index-config.yamlのnested_id_filesは、走査済み YAML 内のネストした ID を追加収集する設定であり、走査外ファイルを追加する機能ではない。限定拡張には、ファイル内容を走査するinclude_pathsまたは ID とパスを直接対応付けるextra_entries等の新しい契約と検証が必要になる。 - ID 衝突: 現行の一意性境界は
docs/の SpecDojo Unit である。リポジトリ全体へ広げると、配布テンプレート、テスト fixture、複数ツール向け設定の ID が同じ索引へ混在し、既存 ID との衝突や、コピーされた同一文書の重複が起こり得る。 - 参照元の扱い:
index buildは参照先の ID とパスを収集する処理であり、docs/外のファイルを参照元にするだけなら索引走査の拡張は不要である。既存のindex replaceは入力ファイルを個別指定できるため、必要な参照先がdocs/内なら現在の索引で解決できる。 - 表示経路:
.vitepress/config.mtsはサイト対象をdocs/配下に限定する設計である。外部パスを索引へ追加しても、agent 向けのindex replace --format pathでは利用できる一方、VitePress 上の遷移先として表示できるとは限らない。限定拡張時は path 解決だけを契約にするか、サイト表示も支えるかを決めて検証する必要がある。
4.4. 選択肢の比較
| 方針 | 得られる便益 | 費用・リスク | 判断 |
|---|---|---|---|
| 全面拡張 | 設定なしでリポジトリ内の広い範囲を ID 解決できる | 除外規則、言語判定、メタ情報契約、一意性境界を同時に変更する。不要な fixture や秘密領域の混入も防ぐ必要がある | 採用しない |
| 限定拡張 | 許可した外部ファイルの改名時に Markdown 45 箇所の追従を省ける | extra_entries 等の設定契約、パス境界・存在・ID 形式・重複・表示経路の検証と、その継続保守が必要 | 将来の再評価時の優先候補 |
| 拡張なし | 現行 Unit と外部ツールのファイル契約を維持できる | 55 箇所を影響検索し、書換対象の Markdown 45 箇所を一括置換・検査する。実績は 1 改名で原本 9 ファイルの追従 | 現時点で採用 |
限定拡張は全面走査より安全だが、現状の nested_id_files をそのまま流用できる小変更ではない。 ID とパスを設定に二重管理する負担、docs/ の ID との衝突、VitePress では表示できない可能性まで 含めると、観測された改名頻度に対して固定費が大きい。
4.5. 後続対応
拡張しない方針のため、現時点で実装 todo は起票しない。次のいずれかが発生した場合に再評価する。
docs/外の同一ファイルの移動・改名により、複数の履歴参照を繰り返し修正する事例が発生した場合。- agent や自動処理が
docs/外のファイルを安定 ID で解決しなければ成立しない機能要件が追加された場合。 docs/外のファイルを SpecDojo 文書として管理し、ID の所有元、一意性境界、メタ情報契約を定義する方針が別途採択された場合。
再評価時はディレクトリの全面走査ではなく、.specdojo/index-config.yaml に明示した ID と リポジトリ相対パスだけを索引へ加える限定方式を優先する。その際は、許可パス、ファイル存在、 ID 形式、docs/ 索引との重複、リポジトリ外参照の拒否、言語中立 ID と localized ID の衝突、 index lookup / index replace / VitePress の期待動作を受け入れ条件とする。
4.6. 完了条件との対応
- instruction 参照を主要ユースケースとして、参照箇所数と対象ファイル種別を記録した。
- 走査境界、Frontmatter、Unit と言語、設定契約、ID 衝突、参照元、表示経路を整理した。
- 全面拡張、限定拡張、拡張なしの費用と便益を比較し、現時点では拡張なしに決定した。
- 「外部 wikilink が 0 件」は判断根拠にせず、生パス参照 55 箇所の上限規模と改名実績を費用比較に用いた。
- 実装 todo は現時点で不要とし、再評価条件と、その場合に優先する限定拡張の受け入れ条件を明記した。
4.5. 受け入れ確認
orchestrator が次を確認した。
- 差し戻しの理由であった循環論法が解消されている。冒頭で「外部ファイルへの参照需要が無いという 判断ではない」と明示し、生パス表記が実際に使われている事実を認めたうえで費用比較から結論して いる。
- 差し戻し時に orchestrator が示した「42 ファイル・55 箇所」を再計測し、evidence JSON 10 箇所・ 4 ファイルの混入を指摘している。編集対象の Markdown に限ると 45 箇所・28 ファイルである。 orchestrator の集計が不正確であり、agent の再計測が正しい。
- 改名時の追従費用を Git 履歴で確認している。参照先 6 ファイルのうち改名実績は 1 件で、その際 docs 原本 9 ファイル・生成物を含め 21 ファイルが更新された。費用の実在を認めたうえで、頻度が 低く一括置換で対処できることを根拠にしている。
lint:mdと単体テスト 1368 件が通る。
実行時に test-unit が失敗して waiting へ遷移したが、tests/src/exec-run-lock.test.ts の heartbeat で lock の更新時刻を進める は時刻に依存する。単独で 3 回、全件で 1 回いずれも成功 したため、grade 走査と並行したことによる負荷が原因と判断した。reporter 段から再開して完了させた。
統合時に個票の conclusion が衝突した。orchestrator が差し戻し時に記録した旧結論と、再実行の 新結論が競合したためである。循環論法に基づく旧結論を捨て、新結論を採用した。
4.6. 補足: ソース参照の目的を区別する
クローズ後、src/ 配下を参照する将来需要について確認した。結論は変わらないが、判断材料として 記録する。
docs/ 外のファイルを扱う要求は3つに分かれ、必要な手段が異なる。
| 目的 | 手段 | 現状 |
|---|---|---|
| 内容を表示 | VitePress のコードスニペット | 可能 |
| リンクを張る | リポジトリルート相対の生パス | 可能 |
| 改名へ追従 | 安定 ID による wikilink | 不可 |
本項目が扱ったのは3つ目だけである。1つ目は VitePress の標準機能で既に解決しており、docs/ 配下へ ソースをラップした Markdown を作る必要はない。
<<< @/src/git-environment.ts{ts}@ はリポジトリルートを指すため docs/ の外へ出られる。実リポジトリで src/git-environment.ts の内容が生成物へ埋め込まれることを確認した。行範囲の指定（{1,5}）も動作する。
この事実は「拡張しない」判断を補強する。src/ の参照需要が増えても、表示はスニペット、リンクは 生パスで足り、wikilink 拡張が必須になるわけではない。再評価が要るのは改名追従の費用が上回った ときに限られる。
ただしスニペットには制約がある。参照先が存在しないとビルドが失敗する。生パスのリンクは壊れて も表示上のリンク切れに留まるが、スニペットは docs:build を止める。改名時の追従漏れがより早く 表面化する一方、影響も大きい。スニペットを使う場合はこの違いを踏まえる。