PJR-PM2R external_projects で SpecDojo のリポジトリへ起票を任せられない
1. 課題内容
external_projects の起票の委譲は相手の node_modules/.bin/specdojo を呼ぶが、SpecDojo 自身のリポジトリには npm install 後もこの実行ファイルがないため、利用者のリポジトリから本家へ起票できない。
- 起きた条件: 利用者のリポジトリ（coderdojo-lessons-specdojo）から、clone した SpecDojo のリポジトリ（
project/prj-0001/develop、0.4.5）へ、prj-0001:pjr-ss72-maintenance-plan-md036 などを起票しようとした。 - 確かめたこと:
targetSpecdojoExecutable（src/register/external-project.ts）は<相手のリポジトリ>/node_modules/.bin/specdojoがないとエラーにする。SpecDojo のリポジトリでnpm installとnpm run buildを実行しても、自分自身の bin はnode_modules/.binに入らない。 - 実際に
external_projectsを設定して委譲を試してはいない。上の2点から、委譲はExternal project repository does not have SpecDojo installedで止まると判断した。 - 回避: SpecDojo のリポジトリの clone で
node dist/specdojo.js register add ... --commitを直接実行して起票した。
2. 影響範囲
| 観点 | 影響 |
|---|---|
| スコープ | 利用者のリポジトリから SpecDojo の登録簿への起票の委譲 |
| スケジュール | 利用者は SpecDojo のリポジトリの clone で CLI を直接使う必要がある |
| コスト | clone での npm install と npm run build が要る |
| 品質 | なし |
| 関係者 | SpecDojo へ不具合を報告する利用者 |
3. 対応方針
| 項目 | 内容 |
|---|---|
| 原因 | 委譲は相手のリポジトリに npm で導入された CLI だけを想定している |
| 対応策 | 相手が SpecDojo 自身のリポジトリの場合は dist/specdojo.js を使う、など実行ファイルの探し方を広げる。対応しない場合は、文書に制約と回避の手順を書く |
| 依存事項 | なし |
| 完了条件 | 利用者のリポジトリから SpecDojo のリポジトリの project へ register add --project <別名> --commit で起票できる。または、制約と回避の手順が文書にある |
3.1. 完了条件（追記）
- v0.4.6 の範囲とする（2026-10-24、利用者が承認）。上の表の対応策のうち、実行ファイルの探し方を広げる方で直す（文書に制約を書くだけにはしない）。
- 委譲の相手のリポジトリに
node_modules/.bin/specdojoがなく、相手のpackage.jsonのnameがspecdojo（SpecDojo 自身のリポジトリ）でdist/specdojo.jsがある場合は、node <相手>/dist/specdojo.jsで起動する。dist/specdojo.jsがない場合は、npm run buildを案内して止まる。版の確かめ（0.4.2 以上）は今のまま行う。 - 統合テストで、SpecDojo 自身のリポジトリに見立てた一時のリポジトリ（
name: specdojoとdist/specdojo.jsを持つ）へ、別の一時のリポジトリから起票できることを確かめる。 - 作業を終える前に、
npm run typecheck・npm run lint:ts・npm run test:unitを実行して通す。 - 親の検証（lint-ts・lint-fm・lint-md・typecheck・test-unit・test-integration・validate-schema）が通る。
- CHANGELOG の
## [Unreleased]の節に書く（なければ作る）。
4. 対応結果
src/register/external-project.tsの CLI 解決を拡張した。インストール済みの CLI を優先し、存在しない場合に相手のpackage.jsonのnameがspecdojoなら、process.execPathと相手のdist/specdojo.jsで版の確認と起票を行う。未ビルドの場合はnpm run buildを案内して、起票前に停止する。- 単体テストに、Node.js に渡す引数、インストール済み CLI の優先、未ビルド時の停止、別パッケージの除外、既存の版の条件を追加した。統合テストには、
name: specdojoとdist/specdojo.jsを持ち、node_modules/.bin/specdojoのない一時リポジトリへの起票を追加した。相手の統合ブランチへの 1 件の commit と呼び出し元が変わらないことを検証する。 - CLI コマンドリファレンス・設定リファレンス・登録簿運用ガイド に起動方法とビルドの前提を追記し、CHANGELOG の Unreleased に記載した。
- executor で Prettier 整形、本体のビルド、登録簿の派生ビュー生成、カタログ検証が通った。カタログ検証は未作成の成果物に関する警告を出したが、終了コードは 0。型検査、lint、単体テスト・統合テスト、schema 検査の成否は、executor 終了後に実行する親 runner の evidence を正とする。統合後の実 agent による確認は PJR-JSEY で行う。
5. 関連ドキュメント
- prj-0001:pjr-ss72-maintenance-plan-md036：委譲を試すきっかけになった不具合
- prj-0001:pjr-68kr-checkpoint-failure-summary：同じく起票した不具合