PJR-44J9 exec plan の共通規約が、新しい利用者の環境で実行できない検査を求める
1. 課題内容
公開物での実地の確認(2026-10-08)で、init で作った新しいリポジトリで exec run を流すと、作業は済んだのに executor の検証の失敗で waiting になった。共通規約(xep-common-conventions-template.md)が、Markdown の変更に npx markdownlint(SpecDojo の依存ではない)を、docs/ja/projects/ 配下の変更に specdojo catalog validate(catalog_path がないと実行できない)を一律に求めるため。
2. 影響範囲
| 観点 | 影響 |
|---|---|
| スコープ | 全 exec plan に入る共通規約(docs/ja/specdojo/exec-templates/xep-common-conventions-template.md)の検査の表と、その生成 |
| スケジュール | v0.3.0 の公開を止める(判定基準 3) |
| コスト | 新しい利用者の最初の exec が必ず waiting になる |
| 品質 | 作業が済んでいても、実行できない検査の失敗で止まる |
| 関係者 | カタログや markdownlint を導入していない利用者 |
3. 対応方針
| 項目 | 内容 |
|---|---|
| 原因 | 共通規約の検査の表が、SpecDojo 本体の開発環境(markdownlint の導入、成果物カタログの設定)を前提にしている |
| 対応策 | 下記の「完了条件の詳細」のとおり、検査を実行できる場合に限る |
| 依存事項 | PJR-BK4K(requires_human)、PJR-6QDA(選択式の init) |
| 完了条件 | 下記の「完了条件の詳細」を満たす |
3.1. 完了条件の詳細
- 共通規約の検査の表で、利用者の環境によって実行できない検査に適用の条件を付ける。少なくとも次を扱う。
npx markdownlint: リポジトリに markdownlint(またはmarkdownlint-cli2)が導入されている場合だけ実行する。導入されていない場合は実行せず、validations にも書かない。specdojo catalog validate: project にcatalog_pathが設定されている場合だけ実行する。- そのほか、表の中で SpecDojo 本体の開発環境を前提にしている検査があれば、同じく条件を付ける。
- 条件に当たらず実行しない検査は、validations に
not_runとして書かない(書くと runner が block するため)。条件の判断に迷う場合の扱いも規約に書く。 - SpecDojo 本体のリポジトリでは、これまでどおりすべての検査が実行される(markdownlint もカタログもあるため)。
- plan の生成が共通規約を埋め込む箇所に条件の判断の材料(例:
catalog_pathの有無)が要る場合は、plan の生成で渡す。 - unit test で、カタログのない project の plan に
catalog validateの指示が入らないこと(または条件付きで入ること)を確かめる。 npm run checkが通る。
4. 対応結果
xep-common-conventions-template.mdの検査規約に、依存パッケージ、npm script、project 設定、SpecDojo CLI の起動可否による適用条件を追加した。- Markdown lint は
markdownlint-cli/markdownlint/markdownlint-cli2が対象リポジトリに導入されている場合だけ実行し、未導入の検査をnot_runとして validations に記録しないよう定めた。 catalog validate/catalog buildは対象 project にcatalog_pathが設定されている場合だけ実行するよう定めた。register / schedule に関する検査と npm script による検査にも、それぞれ対応する設定の存在条件を追加した。catalog_pathがない project の生成 plan に、catalog 検査の適用条件と、非適用の検査を validations へ記録しない指示が含まれることを unit test に追加した。