PJR-8QT0 追加の kata のパッケージ（variant package）の扱いを決める
1. 背景
規則では業界や用途ごとの kata の一式を別の authority のパッケージ（variant package）として持てるとしているが、置き場所・公開の仕方・利用者のリポジトリから読む仕組み・authority の登録の仕方が決まっておらず、実装もない。coderdojo-lessons で育てる edu-scratch の kata を将来配る前提で決める
2026-10-23 時点の事実は次のとおり。
- 規則（specdojo:id-and-file-naming-standard・specdojo:practice-system-composition-guide）では、package が所有する kata は
<authority>:<local-id>の id を持ち、SpecDojo core はspecdojo:、業界ごとの variant package の例としてconstruction-dojo:を挙げている。authority はファイル名に入らない。 - kata の解決は、利用者のリポジトリの
docs/と、resolver が返す SpecDojo package の 5 種別（rulebook・recipe・sample・template・standard）のディレクトリを走査する。variant package を読む仕組みはない。 - 0.4.3（PJR-CT6G）で、利用者のリポジトリの kata を設定の
kata_authorityの authority でdocs/ja/kata/の下に作り、そのリポジトリだけから解決するようになった。 - coderdojo-lessons で、Scratch 教材の kata を
edu-scratch:の authority で作ろうとしている。形が固まったら、ほかの教材のプロジェクトでも使えるよう配りたい。
2. 検討した選択肢
2.1. 置き場所と公開
| 選択肢 | 内容 | 利点 | 懸念 |
|---|---|---|---|
| L1（推奨） | 公式に保守する variant は、specdojo のリポジトリの packages/kata-<authority>/ に置き、npm に別のパッケージ（例: @specdojo/kata-edu-scratch）として公開する。版と公開のタグは docs-lint と同じく別に持つ | 本体と同じ規則・検査・ビルドで保守できる。本体の版と独立に出せる | 本体のリポジトリが大きくなる |
| L2 | variant ごとに別のリポジトリで持つ | 本体と切り離せる | 規則や検査を各リポジトリで持つことになり、本体の変更に追従しにくい |
| L3 | 本体のパッケージ（specdojo）に同梱する | 1 つのパッケージで済む | 本体に専門の kata が混ざり、authority を分ける意味が薄れる |
2.2. 利用者のリポジトリから読む仕組み
| 選択肢 | 内容 | 利点 | 懸念 |
|---|---|---|---|
| R1（推奨） | 設定に読む variant package の名前を並べる（例: kata_packages）。各パッケージは package.json に自分の authority を宣言する。resolver は宣言されたパッケージの 5 種別のディレクトリを、パッケージごとに別のスコープとして走査する | 何を読むかが設定で明示され、node_modules 全体を探さずに済む（今の方針と同じ） | 設定とパッケージの宣言の両方が要る |
| R2 | node_modules の中から authority を宣言したパッケージを自動で探す | 設定が要らない | 何が読まれるかが分かりにくい。走査が重くなる |
解決の順は、利用者のリポジトリ（同じ完全 id の eject による上書き、kata_authority の自前の kata）を最優先とし、次に宣言した variant package、最後に SpecDojo core とする。同じ authority を宣言するパッケージが 2 つあれば、設定の検証で止める。
2.3. authority の扱い
| 選択肢 | 内容 | 利点 | 懸念 |
|---|---|---|---|
| A1（推奨） | specdojo は core 専用の予約とする。公式の variant の authority は文書に一覧を持ち、重ならないようにする。第三者の variant は自由に名乗れるが、prj- で始めない | 公式どうしの衝突を防げる。第三者の自由を妨げない | 一覧の保守が要る |
| A2 | authority の登録の仕組み（レジストリ）を作る | 衝突を仕組みで防げる | 今の規模には重い |
2.4. 利用者のリポジトリで育てた kata の移し方
| 選択肢 | 内容 | 利点 | 懸念 |
|---|---|---|---|
| M1（推奨） | id（edu-scratch:<local-id>）を変えずに、利用者のリポジトリの docs/ja/kata/ から variant package へ移す。利用者のリポジトリは自前の kata を消し、パッケージを依存に入れて kata_packages に並べる。その後も同じ完全 id の上書きはできる | 参照を書き換えずに済む | 移すときに、利用者のリポジトリの kata_authority と variant の authority が同じになる期間の扱いを決める必要がある（同じ id が両方にある場合は利用者のリポジトリを優先する） |
| M2 | 移すときに id を変える | 移した後の所有が明確 | 参照の書き換えが要る |
3. 決定内容
推奨のとおり、次のように決める。
- 置き場所と公開は L1 とする。公式に保守する variant は specdojo のリポジトリの
packages/kata-<authority>/に置き、npm に別のパッケージ（例:@specdojo/kata-edu-scratch）として公開する。版と公開のタグは本体と別に持つ。 - 利用者のリポジトリから読む仕組みは R1 とする。設定に読む variant package の名前を並べ、各パッケージは
package.jsonに自分の authority を宣言する。node_modules全体は探さない。解決の順は、利用者のリポジトリ、宣言した variant package、SpecDojo core とし、同じ authority を宣言するパッケージが 2 つあれば設定の検証で止める。 - authority の扱いは A1 とする。
specdojoは core 専用の予約とし、公式の variant の authority は文書に一覧を持つ。第三者の variant は自由に名乗れるが、prj-で始めない。 - 利用者のリポジトリで育てた kata の移し方は M1 とする。id もパスも変えずに variant package へ移す。
- kata の置き場所は Q1 とする。本体の kata は
docs/ja/specdojo/<種類>s/<local-id>.md、それ以外の authority はdocs/ja/specdojo/<種類>s/<authority>/<local-id>.mdとし、利用者のリポジトリと variant package で同じパスを使う。0.4.3 のdocs/ja/kata/は 0.4.4 でこの形に直す。 - variant package を読む仕組み（R1）の実装は、coderdojo-lessons の
edu-scratch:の kata が形になった時点で todo を起票する。
4. 採択理由
- 公式の variant を本体のリポジトリで保守することで、規則と検査に追従しやすく、本体と独立に版を出せる。
- 読むパッケージを設定で明示することで、今の resolver の方針（
node_modules全体を探さない）を保てる。 - kata を SpecDojo の領域（
docs/ja/specdojo/）に収めることで、利用者の文書のディレクトリと authority の名前がぶつからず、本体の kata も移さずに済む（利用者の提案）。 - id もパスも変えずに移せるため、利用者のリポジトリで育てた kata を配るときに参照の書き換えが要らない。
5. 承認
| 項目 | 内容 |
|---|---|
| 決定者 | 利用者（indie） |
| 決定日 | 2026-10-23 |
| 承認方式 | commit |
| 証跡 | orchestrator との会話（2026-10-23）で、L1・R1・A1・M1 と、利用者の提案の置き場所 Q1 を「推奨でお願いします」として承認 |
- 承認方式は
commitまたはPRを記載する。PRの場合は証跡に PR URL と merge SHA を本文テキストで記載する。 - 不可逆・高リスク・framework schema 破壊的変更に該当する決定は
PR方式で承認する。
6. 影響範囲とフォローアップ
| 項目 | 内容 |
|---|---|
| 影響範囲 | kata の解決（src/kata/）、設定の schema、id とファイル名の規則、kata のガイド、docs-site のステージング |
| 必要な対応 | 0.4.3 の docs/ja/kata/ を Q1 の置き場所に直す todo を起票した。variant package を読む仕組みの todo は、edu-scratch: の kata が形になった時点で起票する |
| 追跡先 | 置き場所を直す todo（本決定と同時に起票） |
7. 関連ドキュメント
- specdojo:id-and-file-naming-standard
- specdojo:practice-system-composition-guide
- PJR-CT6G（kata を新しく作る approach の実装）