specdojo 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +122 -1
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-handoff.js +336 -0
  15. package/dist/exec-parent-validation.js +317 -43
  16. package/dist/exec-pipeline-state.js +74 -9
  17. package/dist/exec-plans.js +115 -113
  18. package/dist/exec-protection-handoff.js +43 -2
  19. package/dist/exec-provider-scaffold.js +247 -15
  20. package/dist/exec-register-resume.js +65 -19
  21. package/dist/exec-register.js +9 -3
  22. package/dist/exec-repo-integration.js +811 -0
  23. package/dist/exec-repo-trace.js +182 -0
  24. package/dist/exec-reporter.js +613 -132
  25. package/dist/exec-results.js +81 -56
  26. package/dist/exec-run-lock.js +110 -107
  27. package/dist/exec-run.js +1585 -356
  28. package/dist/exec-shared.js +7 -0
  29. package/dist/exec-slot-lock.js +242 -0
  30. package/dist/exec-task-repos.js +415 -0
  31. package/dist/exec-trial.js +51 -25
  32. package/dist/exec-worktree-command.js +87 -43
  33. package/dist/exec-worktree-ops.js +502 -57
  34. package/dist/exec-worktree.js +114 -27
  35. package/dist/exec.js +13 -6
  36. package/dist/grade-result.js +128 -0
  37. package/dist/grade.js +809 -72
  38. package/dist/init-command.js +443 -0
  39. package/dist/job.js +160 -10
  40. package/dist/orchestrator.js +213 -0
  41. package/dist/register-event-merge.js +169 -0
  42. package/dist/register-item.js +7 -1
  43. package/dist/register.js +294 -86
  44. package/dist/review-grade.js +252 -0
  45. package/dist/review-plan.js +111 -1
  46. package/dist/review-types.js +40 -1
  47. package/dist/routine.js +72 -5
  48. package/dist/schedule-build.js +2 -2
  49. package/dist/schedule.js +17 -4
  50. package/dist/specdojo-config.js +465 -19
  51. package/dist/specdojo-gitignore.js +135 -0
  52. package/dist/specdojo.js +6 -0
  53. package/dist/viewpoint-document-kinds-check.js +128 -0
  54. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  55. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  56. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  57. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  58. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  59. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  60. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  61. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  62. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  63. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  65. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  67. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  68. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  69. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  70. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  71. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  72. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  73. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  74. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  75. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  76. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  77. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  78. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  79. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  80. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  81. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  82. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  83. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  84. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  85. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  86. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  87. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  88. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  89. package/docs/ja/specdojo/index.md +2 -2
  90. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  91. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  92. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  93. package/docs/ja/specdojo/references/command-reference.md +335 -92
  94. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  95. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  96. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  97. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  98. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  99. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  100. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  101. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  102. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  104. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  105. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  106. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  107. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  108. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  109. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  110. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  111. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  112. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  113. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  114. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  115. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  116. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  117. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  118. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  119. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  120. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  121. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  122. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  123. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  124. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  125. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  126. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  127. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  128. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  129. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  130. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  131. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  132. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  133. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  134. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  135. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  136. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  137. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  138. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  139. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  140. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  141. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  142. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  143. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  144. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  145. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  146. package/package.json +15 -9
  147. package/templates/antigravity/README.md +27 -2
  148. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  149. package/templates/antigravity/exec-defaults-snippet.yaml +7 -6
  150. package/templates/antigravity/orchestrator.md +18 -7
  151. package/templates/antigravity/settings.global.json +55 -0
  152. package/templates/claude/agents/claude-executor.md +14 -0
  153. package/templates/claude/agents/claude-reporter.md +16 -0
  154. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  155. package/templates/claude/settings.edit.json +27 -1
  156. package/templates/codex/README.md +5 -4
  157. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  158. package/templates/codex/orchestrator.md +18 -7
  159. package/templates/copilot/README.md +7 -5
  160. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  161. package/templates/devcontainer/devcontainer.json +27 -0
  162. package/templates/devcontainer/emacs/init.el +88 -0
  163. package/templates/devcontainer/post-create.sh +62 -0
  164. package/templates/init-agent-members.yaml +200 -0
  165. package/templates/init-exec-defaults.yaml +72 -0
  166. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  167. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  168. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -19,6 +19,7 @@ SpecDojo で扱うドキュメントの編集に役立つ、Visual Studio Code
19
19
 
20
20
  - 文書編集に役立つ VS Code 拡張と SpecDojo 拡張の導入方法・役割
21
21
  - 見出し番号の付け方、Markdown プレビューの使い方、表の整形方法
22
+ - 文書サイトのビルド方法と、サイドバー・検索・package 同梱文書の扱い
22
23
 
23
24
  **次に読む文書**
24
25
 
@@ -325,3 +326,22 @@ npx specdojo-docs-lint md-content \
325
326
  --schema docs/ja/specdojo/schemas/v1/guide-content.schema.yaml \
326
327
  --data "docs/ja/specdojo/guides/*-guide.md"
327
328
  ```
329
+
330
+ ## 6. 文書サイトを確認する
331
+
332
+ VitePress の文書サイトが必要なリポジトリでは、任意パッケージ `@specdojo/docs-site` を導入します。CLI 本体の `specdojo` だけを使う場合、このパッケージは不要です。
333
+
334
+ ```bash
335
+ npm install --save-dev @specdojo/docs-site
336
+ npx specdojo-docs-site build .
337
+ ```
338
+
339
+ 開発サーバは `npx specdojo-docs-site dev .` で起動します。`build` と `dev` は、利用リポジトリに存在しない package 同梱の kata・guide・reference を、gitignore 済みの `specdojo-kata-staging/` へ一時的に複製して `/ja/specdojo/` で配信します。eject 済みの文書は利用リポジトリ側を優先するため、サイト表示のために `kata install --all` を実行する必要はありません。
340
+
341
+ サイト上の情報量を抑えるため、ナビゲーションと検索には次の範囲を使います。
342
+
343
+ - `/ja/specdojo/` では SpecDojo 文書、`/ja/projects/<project-id>/` では対象 project の文書をサイドバーに表示します。
344
+ - plan / result / event などの実行記録はページとして公開しますが、サイドバーには列挙しません。project の dashboard から `exec-records.md` を経由して辿ります。
345
+ - ローカル検索は登録簿一覧 `pjr-index` を入口にし、個票、状態別などの派生ビュー、管理ログ、実行記録を検索インデックスから除外します。個票本文を探す場合は `pjr-index` から対象個票へ移動します。
346
+
347
+ ステージングの参照元、Mermaid SVG だけを生成するコマンドなど、package 固有の設定は `packages/docs-site/README.md` を参照してください。
@@ -19,7 +19,7 @@ SpecDojoで扱うドキュメントの全体構成について、以下のガイ
19
19
  **この文書で分かること**
20
20
 
21
21
  - SpecDojo Unit、文書分類、ドキュメントオーナー、命名方針、標準ディレクトリ構成の考え方
22
- - 成果物と実践体系(philosophy / standard / rulebook / recipe / sample / template)の関係
22
+ - 成果物と型(Kata、philosophy / standard / rulebook / recipe / sample / template)の関係
23
23
  - 成果物カタログ(dct)・Schedule(sch)・実行管理(exec)の関係
24
24
 
25
25
  **次に読む文書**
@@ -41,24 +41,24 @@ SpecDojoで扱うドキュメントの全体構成について、以下のガイ
41
41
  | 確認したいこと | 読む章 |
42
42
  | --------------------------------- | --------------------------------------------------------------------------------- |
43
43
  | 文書の分類と責任の考え方 | `SpecDojoで扱うドキュメントの全体構成`〜`ドキュメントオーナー` |
44
- | 成果物・DCT・Schedule・execの関係 | `成果物と実践体系の関係`〜`成果物カタログ・Schedule・実行管理の関係` |
44
+ | 成果物・DCT・Schedule・execの関係 | `成果物と型の関係`〜`成果物カタログ・Schedule・実行管理の関係` |
45
45
  | ディレクトリの命名・構成方針 | `ディレクトリ・ファイルの命名ルール` 以降 |
46
- | プロダクトと別リポジトリで運用 | `別リポジトリ構成(Detached Unit)` |
46
+ | プロダクトと別リポジトリで運用 | `別リポジトリ構成` |
47
47
  | ファイル単位の完全な配置一覧 | [ディレクトリレイアウトリファレンス](../references/directory-layout-reference.md) |
48
48
 
49
49
  ## 1. SpecDojoで扱うドキュメントの全体構成
50
50
 
51
- - SpecDojo は、1つの SpecDojo Unit で1つのプロダクト文脈を扱うことを基本とします。SpecDojo Unit とは、プロダクトドキュメント、プロジェクトドキュメント、実践体系をまとめて扱う論理的な管理境界です。
51
+ - SpecDojo は、1つの SpecDojo Unit で1つのプロダクト文脈を扱うことを基本とします。SpecDojo Unit とは、プロダクトドキュメント、プロジェクトドキュメント、型(Kata)をまとめて扱う論理的な管理境界です。
52
52
  - 1つの SpecDojo Unit には、対象プロダクトを構築・改修するための複数のプロジェクトが存在します。プロジェクトごとにプロジェクトドキュメントを作成します。
53
- - 既定の Detached Unit では、プロダクトドキュメントをプロダクトリポジトリへ、プロジェクトドキュメントと実践体系を SpecDojo 専用リポジトリへ置きます。Attached Unit では、これらを1つのリポジトリの `docs/` ルートに置きます。
53
+ - 既定の別リポジトリ構成では、プロダクトドキュメントをプロダクトリポジトリへ、プロジェクトドキュメントと型をプロジェクトリポジトリへ置きます。同一リポジトリ構成では、これらを1つのリポジトリの `docs/` ルートに置きます。
54
54
  - 1つのリポジトリで複数プロダクトを扱う場合は、プロダクトごとに文書の管理境界を分け、それぞれを独立した SpecDojo Unit として扱います。
55
55
  - 成果物IDは、原則として SpecDojo Unit 内で一意にします。複数の SpecDojo Unit を横断して扱う場合は、必要に応じて Unit ID と成果物IDの組み合わせで識別します。
56
56
 
57
57
  ### 1.1. 構成の選び方
58
58
 
59
- 利用プロジェクトでは、SpecDojo の成果物更新、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離する **Detached Unit を既定**とします。成果物と実装が同じ変更で動き、履歴も一体として扱う必要がある場合に限り、同一リポジトリの Attached Unit を選びます。CLI はどちらの構成も許容し、この選択を強制しません。
59
+ 利用プロジェクトでは、SpecDojo の成果物更新、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離する **別リポジトリ構成を既定**とします。成果物と実装が同じ変更で動き、履歴も一体として扱う必要がある場合に限り、同一リポジトリ構成を選びます。CLI はどちらの構成も許容し、この選択を強制しません。
60
60
 
61
- Detached Unit の配置と現行実装の制約は `別リポジトリ構成(Detached Unit)` を参照してください。
61
+ 別リポジトリ構成の配置と現行実装の制約は `別リポジトリ構成` を参照してください。
62
62
 
63
63
  ## 2. ドキュメントの分類
64
64
 
@@ -200,9 +200,9 @@ flowchart TB
200
200
  - 図中のアーキテクチャ設計は、個別仕様に先立つ全体構造の設計を表します。
201
201
  - 「業務要件を含む」とは、業務仕様の冒頭に業務要件相当(対象範囲・成功条件・制約等)を含めることを指します。
202
202
 
203
- ## 5. 成果物と実践体系の関係
203
+ ## 5. 成果物と型の関係
204
204
 
205
- 成果物と、その作成を支援する実践体系(philosophy / standard / rulebook / recipe / template / sample / guide / reference)の関係、各種別の役割、成果物への紐付け方(解決の仕組み)は [実践体系構成ガイド](practice-system-composition-guide.md) を正本とします。`approach` に応じた rulebook / recipe / sample / template の参照方針は [実践の進め方ガイド](ryu-guide.md) を参照してください。
205
+ 成果物と、その作成を支援する型(Kata、philosophy / standard / rulebook / recipe / template / sample / guide / reference)の関係、各種別の役割、成果物への紐付け方(解決の仕組み)は [型の構成ガイド](practice-system-composition-guide.md) を正本とします。`approach` に応じた rulebook / recipe / sample / template の参照方針は [実践の進め方ガイド](ryu-guide.md) を参照してください。
206
206
 
207
207
  ## 6. 成果物カタログ・Schedule・実行管理の関係
208
208
 
@@ -342,64 +342,74 @@ product/
342
342
 
343
343
  ファイル単位の完全なツリーは [ディレクトリレイアウトリファレンス](../references/directory-layout-reference.md) の `プロダクトドキュメントの構成` を参照してください。
344
344
 
345
- ## 10. 別リポジトリ構成(Detached Unit)
345
+ ## 10. 別リポジトリ構成
346
346
 
347
- Detached Unit は、SpecDojo Unit の運用記録をプロダクトと同じリポジトリに置かず、専用のリポジトリで管理する既定構成です。SpecDojo のプロジェクト成果物、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離します。
347
+ 別リポジトリ構成は、SpecDojo Unit の運用記録をプロダクトと同じリポジトリに置かず、プロジェクトリポジトリで管理する既定構成です。プロジェクトリポジトリとは、登録簿・計画・実行記録などのプロジェクトドキュメントと型を置くリポジトリです。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。この構成により、SpecDojo のプロジェクト成果物、登録簿の状態遷移、exec の実行記録をプロダクトの Git 履歴から分離します。
348
348
 
349
349
  ### 10.1. 採用条件
350
350
 
351
- | 利用形態 | 判断 |
352
- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
353
- | 一般の利用プロジェクト | Detached Unit を既定とする |
354
- | プロジェクト文書と SpecDojo の運用記録だけを扱う | `app1-specdojo/` 内で catalog、Schedule、exec、grade を完結できる |
355
- | プロダクト文書または実装を1つの登録簿項目で変更する | PJR-P7HY 完了までは複数リポジトリを自動統合せず、項目を分けるか人が統合を管理する |
356
- | SpecDojo 自身の開発のように、成果物と実装が常に同じ変更・履歴として動く | 例外として Attached Unit を選べる |
351
+ | 利用形態 | 判断 |
352
+ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
353
+ | 一般の利用プロジェクト | 別リポジトリ構成を既定とする |
354
+ | プロジェクト文書と SpecDojo の運用記録だけを扱う | `app1-specdojo/` 内で catalog、Schedule、exec、grade を完結できる |
355
+ | プロダクト文書または実装を1つの登録簿項目で変更する | project に `repos` を宣言し、`exec run --worktree` で全リポジトリを統合する |
356
+ | SpecDojo 自身の開発のように、成果物と実装が常に同じ変更・履歴として動く | 例外として同一リポジトリ構成を選べる |
357
357
 
358
- 実装を伴う項目の二重 worktree、親検証のリポジトリ別割り当て、統合と回復は [[prj-0001:pjr-p7hy-multi-repo-single-item|PJR-P7HY 1つの項目が複数リポジトリを変更する場合の統合を扱う]] の完了まで未対応です。それまでは `app1-specdojo/` の agent から `app1/` を直接更新しません。
358
+ プロダクトリポジトリ(`app1/` など)を変更する項目は、`.specdojo/specdojo.config.json` の project に `repos` を宣言してから実行します。宣言の書き方は [[specdojo:specdojo-config-reference|specdojo.config.json リファレンス]] の「`repos`のキー」を参照してください。宣言できるプロダクトリポジトリの数に上限はなく、1つの項目でプロジェクトリポジトリと複数のプロダクトリポジトリを変更できます。宣言済みのリポジトリは exec のタスク対象にでき、`specdojo orchestrator launch` で起動したオーケストレーターも参照・変更できます。宣言していないリポジトリは exec とオーケストレーターの管理外であり、`app1-specdojo/` の agent から直接更新しません。
359
359
 
360
360
  ### 10.2. ディレクトリレイアウト
361
361
 
362
- 3つのルートを互いに独立したディレクトリとして配置します。`app1/` と `app1-specdojo/` はそれぞれ別の Git リポジトリです。`app1-worktrees/` は両リポジトリの外に置く worktree 用の領域です。
362
+ プロダクトごとの親ディレクトリ(例: `app1-workspace/`)の下に、3つのルートを互いに独立したディレクトリとして配置します。`app1/` と `app1-specdojo/` はそれぞれ別の Git リポジトリです。`app1-specdojo-worktrees/` は両リポジトリの外に置く worktree 用の領域です。
363
363
 
364
364
  ```text
365
- workspace/
365
+ app1-workspace/
366
366
  ├── app1/ # プロダクトのリポジトリ
367
367
  │ ├── src/
368
368
  │ └── docs/ja/product/ # 実装と同期して更新するプロダクト文書
369
- ├── app1-specdojo/ # SpecDojo の運用リポジトリ
369
+ ├── app1-specdojo/ # プロジェクトリポジトリ
370
370
  │ ├── .specdojo/
371
371
  │ ├── docs/ja/projects/
372
372
  │ └── package.json # npm i -D specdojo で CLI を導入する
373
- └── app1-worktrees/ # task 単位の worktree 置き場
373
+ └── app1-specdojo-worktrees/ # task 単位の worktree 置き場
374
374
  ```
375
375
 
376
- `.specdojo/specdojo.config.json` の project パスは `app1-specdojo/` を基準とし、`run.worktree_base` は `../app1-worktrees` とします。SpecDojo CLI の実行、プロジェクト成果物の解決、doc index の生成、運用記録の検証は `app1-specdojo/` 側で行います。
376
+ `.specdojo/specdojo.config.json` の project パスは `app1-specdojo/` を基準とします。`config init` はリポジトリのディレクトリ名から `run.worktree_base` を作るため、この例では `../app1-specdojo-worktrees` になります。SpecDojo CLI の実行、プロジェクト成果物の解決、doc index の生成、運用記録の検証は `app1-specdojo/` 側で行います。
377
377
 
378
378
  ### 10.3. プロダクト文書の配置
379
379
 
380
380
  プロダクト文書は実装と同期して改訂するため、`app1/docs/ja/product/` に置きます。README、ソースコードから生成する API リファレンス、パッケージ利用者向けの手順など、コードと同じ revision で読む付属文書も `app1/` に置きます。
381
381
 
382
- `app1-specdojo/` には `docs/ja/projects/` と `docs/ja/specdojo/` を置きます。前者はプロジェクト固有の目的、判断、計画、実行記録、後者は運用に使う philosophy / standard / rulebook / recipe / sample / template などの実践体系です。この境界により、プロダクトの内容と同じ revision が必要な文書は `app1/`、SpecDojo の記帳と再利用可能な実践体系は `app1-specdojo/` の履歴に残ります。
382
+ `app1-specdojo/` には `docs/ja/projects/` と `docs/ja/specdojo/` を置きます。前者はプロジェクト固有の目的、判断、計画、実行記録、後者は運用に使う philosophy / standard / rulebook / recipe / sample / template などの型です。この境界により、プロダクトの内容と同じ revision が必要な文書は `app1/`、SpecDojo の記帳と再利用可能な型は `app1-specdojo/` の履歴に残ります。
383
383
 
384
- プロダクト文書の catalog `base_path` を別リポジトリへ解決する機能と、[[prj-0001:pjr-xkks-grade-sidecar|PJR-XKKS grade result のサイドカー化]] で定める成果物へ書き込まない grade 運用は、複数リポジトリ対応の前提です。現行実装でプロダクト文書を自動処理できるとはみなしません。
384
+ プロダクト文書の catalog `base_path` を別リポジトリへ解決する機能と、[[prj-0001:pjr-xkks-grade-sidecar|PJR-XKKS grade result のサイドカー化]] で定める成果物へ書き込まない grade 運用は、プロダクト文書を成果物として管理する場合の前提です。exec はプロダクト文書をファイルとして変更・統合できますが、catalog・grade・doc index の対象にはしません。
385
385
 
386
386
  ### 10.4. 現行実装の境界
387
387
 
388
- 現行の exec worktree は SpecDojo リポジトリの1つのルートと1つの worktree の組を管理します。そのため、`app1-specdojo/` の agent が `app1/` のプロダクト文書または実装を同じ項目で更新する運用には、次の未対応点があります。
388
+ `repos` を宣言した project では、exec がプロジェクトリポジトリと宣言したプロダクトリポジトリを1つのタスクとして扱います。現行実装が扱う範囲と、扱わない範囲は次のとおりです。
389
389
 
390
- | 論点 | 現行の境界 |
391
- | ----------------- | -------------------------------------------------------------------------- |
392
- | 編集対象の解決 | job の `paths` と task の `targets` は SpecDojo ルート相対で解決する |
393
- | worktree の隔離 | SpecDojo リポジトリのみを隔離し、`app1/` の更新は task worktree の外に出る |
394
- | commit のスコープ | 変更ファイルと commit 対象を SpecDojo リポジトリに対して計算する |
395
- | 親検証の実行場所 | 親検証は1つの `cwd` で実行し、検証 ID ごとに `app1/` へ割り当てられない |
390
+ | 論点 | 現行実装の扱い |
391
+ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
392
+ | 編集対象の解決 | `targets`・`paths` の `<repo>:<path>`(例: `app1:src/auth/token.ts`)をプロダクトリポジトリのパスとして解決する。接頭辞の無い値は従来どおり解決する |
393
+ | worktree の隔離 | タスクごとに全リポジトリの worktree を作り、agent はプロジェクト worktree を `cwd` としてプロダクト worktree へ書き込む |
394
+ | 依存の導入 | プロダクト worktree の作成時に、追跡されている `package-lock.json` ごとにプロジェクト側と同じ `npm ci` を実行する。lock が無い場合は導入せずログに残す。`setup.install: false` のリポジトリと、再利用する worktree では導入しない |
395
+ | 統合 | runner がリポジトリごとに commit し、宣言順のプロダクト、最後にプロジェクトの順で統合する |
396
+ | commit のスコープ | 変更ファイルと commit 対象をリポジトリごとに計算し、evidence にはプロダクト側を `<repo>:<path>` で記録する |
397
+ | 親検証の実行場所 | `pipeline.parent_validations` の `{ id, repo }` で検証ごとにリポジトリを割り当てる |
398
+ | 保護設定の検査 | 保護設定と Git 状態の検査を全リポジトリの worktree に適用する |
396
399
 
397
- これらが解消されるまでは、`app1/` を agent のサンドボックス外から直接更新したり、手動の Git 操作で実質的な二重 worktree にしたりしません。`app1-specdojo/` 内のプロジェクト文書だけを変更する項目に限定するか、プロダクト文書・実装の変更を別の実行単位として人が管理します。
400
+ 次の範囲は扱いません。
401
+
402
+ - プロダクト文書の doc id による参照。プロダクト側の `targets` はパスで指定します。
403
+ - `exec worktree commit` / `merge` によるプロダクト側の統合。分割コマンドはプロジェクト側だけを統合し、プロダクト worktree に変更が残るタスクは commit の前に停止します。プロダクト側を含めた統合は `exec run --worktree` で行います。
404
+ - exec が起動する opencode agent からプロダクト worktree への書き込み。opencode は agent 定義の `permission.external_directory` で作業ディレクトリ外を拒否するため、runner が起動引数で許可を加えられません。対話型オーケストレーターは `specdojo orchestrator launch` が起動時の inline config へ宣言済みルートだけを注入するため、この制約の対象外です。
405
+ - 宣言していないリポジトリの変更。`app1/` を agent のサンドボックス外から直接更新したり、手動の Git 操作で exec の管理外の worktree を作ったりしません。
406
+
407
+ `repos` を宣言しない project(同一リポジトリ構成を含む)の worktree の配置、commit、統合は従来と変わりません。
398
408
 
399
409
  ### 10.5. result によるトレーサビリティ
400
410
 
401
- プロダクト実装の変更を伴う項目では、登録簿の item ID を履歴改変に依存しないトレースキーとし、
402
- app 側の commit message と SpecDojo 側の result 本文の両方に記録します。result frontmatter は
411
+ プロダクト実装の変更を伴う項目では、登録簿の item ID をプロジェクト ID で修飾した `<project-id>:<item-id>`(例: `prj-0001:PJR-XXXX`)を履歴改変に依存しないトレースキーとし、
412
+ app 側の commit message と SpecDojo 側の result 本文の両方に記録します。登録簿の ID はプロジェクトの中でしか一意でないため、修飾しないと複数プロジェクトの構成やプロダクトリポジトリの履歴から所属を特定できません。result frontmatter は
403
413
  scaffold の構造を維持し、独自キーを追加しません。
404
414
 
405
415
  app 側では、対象項目に対応する commit message の body 末尾に `Refs:` trailer を記載します。
@@ -409,33 +419,44 @@ feat(auth): トークン失効処理を追加する
409
419
 
410
420
  認証済み端末を紛失した場合に、利用者がセッションを失効できるようにする。
411
421
 
412
- Refs: PJR-XXXX
422
+ Refs: prj-0001:PJR-XXXX
413
423
  ```
414
424
 
415
- SpecDojo 側の result には、同じ item ID と app 側の参照を本文へ記録します。commit hash は特定時点の
416
- スナップショットであり、主たる参照にはしません。Pull Request を使わない場合は `app PR` を
417
- `not applicable` とし、理由を添えます。
425
+ `specdojo.config.json` の project に `repos` を宣言し、`exec run --register` で項目を統合する場合は、runner が次を自動で行います。
426
+
427
+ - プロダクト側の exec branch の commit と、統合先ブランチへの merge commit の両方に `Refs: <project-id>:<item-id>` を付けます。プロダクト側の merge commit には、遷移や agent 名などプロジェクト側の記帳を複製しません。
428
+ - プロジェクト側の merge commit の `Refs:` も同じ修飾形で付けます。
429
+ - 宣言順にプロダクトを統合した後、プロジェクトを統合する前に、リポジトリごとの統合先ブランチと commit snapshot を result 本文の末尾に「トレーサビリティ」の章として記録します。統合を再開した場合は同じ章を書き直します。
430
+
431
+ `repos` を宣言しない project では、プロダクト側の統合と trace 表の記録は行いません。プロジェクト側の merge commit の `Refs:` だけが修飾形になります。
432
+
433
+ SpecDojo 側の result には、同じトレースキーと app 側の参照を本文へ記録します。commit hash は特定時点の
434
+ スナップショットであり、主たる参照にはしません。Pull Request を使わない場合は `PR` を
435
+ `not applicable` とし、理由を添えます。runner がローカルで統合した行は `not applicable` になります。
418
436
 
419
437
  ```markdown
420
- | trace key | app repository | app PR | app commit snapshot | 確認時点 |
421
- | --------- | -------------- | ------ | ------------------------------------------ | ------------------------ |
422
- | PJR-XXXX | app1 | #123 | `0123456789abcdef0123456789abcdef01234567` | 統合先ブランチへの統合後 |
438
+ | trace key | repository | integration branch | PR | commit snapshot | recorded at |
439
+ | ------------------- | ---------- | ------------------ | -------------- | ------------------------------------------ | ------------------------ |
440
+ | `prj-0001:PJR-XXXX` | `app1` | `main` | #123 | `0123456789abcdef0123456789abcdef01234567` | 2026-10-01T00:00:00.000Z |
441
+ | `prj-0001:PJR-XXXX` | `app2` | `release` | not applicable | not applicable (no changes) | 2026-10-01T00:00:00.000Z |
423
442
  ```
424
443
 
425
444
  次の規則で運用します。
426
445
 
427
- - `Refs:` の値は登録簿の item ID と完全一致させます。表示名や一時的な branch 名をトレースキーに
428
- しません。
446
+ - `Refs:` の値は `<project-id>:<item-id>` とし、item ID は登録簿の ID と完全一致させます。表示名や一時的な branch 名をトレースキーに
447
+ しません。1 つの commit が複数の項目に関わる場合は、`Refs:` を項目ごとに 1 行ずつ書きます。
448
+ - プロダクトリポジトリから参照される project ID は、別々のプロジェクトリポジトリの間で重ならないよう、意味のある名前(例: `app1`)にします。
429
449
  - app 側の対象 commit には `Refs:` trailer を付けます。複数 commit を1つへ squash する場合は、
430
450
  最終 commit message に trailer を1行残します。app のソースや設定ファイルへ逆参照を埋め込みません。
431
451
  - PR を使う場合は、番号だけでリポジトリを特定できないため、result へ repository 名と PR 番号または
432
452
  URL を対で記録します。
433
453
  - app commit snapshot は、意図する統合先ブランチが実装変更を含んだ直後の40文字の完全長 hash と
434
454
  します。merge commit が作られた場合はその merge commit、fast-forward または squash merge の
435
- 場合は統合後の先端を記録します。
455
+ 場合は統合後の先端を記録します。統合する変更が無かったリポジトリは `not applicable (no changes)` とします。
436
456
  - 記録と確認は app 側の統合成功後、SpecDojo 側の result と成果物を統合する前に行います。app 側への
437
457
  統合が未完了なら PR や hash を推測で記録しません。
438
458
  - 文書のみの項目で app 側の変更がない場合は、`app change: not applicable` とその理由を記録します。
459
+ - 過去の commit の `Refs: PJR-XXXX`(修飾なし)は書き換えません。検索するときは修飾形と修飾なしの両方を対象にします。
439
460
 
440
461
  #### 10.5.1. rebase / squash merge 後の確認
441
462
 
@@ -443,26 +464,32 @@ rebase や squash により commit hash は変わるため、統合後の commit
443
464
  いることを完了条件として確認します。
444
465
 
445
466
  1. rebase 後は、書き換え後の各対象 commit の message を確認する。commit をまとめた場合は、残った
446
- commit の body 末尾に `Refs: PJR-XXXX` があることを確認する。
447
- 2. squash merge では、最終 commit message を確定する画面またはコマンドで `Refs: PJR-XXXX` を
467
+ commit の body 末尾に `Refs: prj-0001:PJR-XXXX` があることを確認する。
468
+ 2. squash merge では、最終 commit message を確定する画面またはコマンドで `Refs: prj-0001:PJR-XXXX` を
448
469
  明示的に残す。プラットフォームによる commit message の自動連結には依存しない。
449
470
  3. 統合後の app リポジトリで次を実行し、統合先ブランチから到達可能な commit が表示されることを
450
471
  確認する。
451
472
 
452
473
  ```bash
453
- git log <target-branch> --grep='^Refs: PJR-XXXX$' --format='%H %s'
474
+ git log <target-branch> --grep='^Refs: prj-0001:PJR-XXXX$' --format='%H %s'
454
475
  ```
455
476
 
456
477
  1. 表示された最終 hash と PR 番号または URL を result へ記録する。対象 commit が表示されなければ、
457
478
  SpecDojo 側を統合せず、app 側のトレースキーを是正する。
458
479
 
480
+ 修飾形を導入する前の履歴も含めて検索する場合は、修飾なしの `Refs: PJR-XXXX` も対象にします。修飾なしの ID は別のプロジェクトの同じ ID にも一致し得るため、表示された commit がどのプロジェクトの項目かを result や期間で確かめます。
481
+
482
+ ```bash
483
+ git log <target-branch> -E --grep='^Refs: (prj-0001:)?PJR-XXXX$' --format='%H %s'
484
+ ```
485
+
459
486
  この確認により、rebase や squash で hash が変わっても item ID から app の到達可能な履歴を検索
460
487
  できます。PR は squash 後の commit とレビュー経緯を結ぶ補助参照、hash は確認時点を固定する補助値
461
488
  です。
462
489
 
463
490
  #### 10.5.2. 逆参照の範囲
464
491
 
465
- Detached Unit は SpecDojo の状態遷移や実行記録を app の履歴から分離しますが、app の変更理由を
492
+ 別リポジトリ構成は SpecDojo の状態遷移や実行記録を app の履歴から分離しますが、app の変更理由を
466
493
  登録簿へ結び直す最小限の逆参照として、commit message の `Refs:` trailer は必須とします。app の
467
494
  ファイルへの ID 追記、SpecDojo の遷移 commit の複製、2つのリポジトリの原子的な統合は求めません。
468
495
  履歴を汚さない範囲を commit message 1行に限定し、履歴改変後の追跡可能性を優先します。
@@ -482,38 +509,44 @@ Detached Unit は SpecDojo の状態遷移や実行記録を app の履歴から
482
509
 
483
510
  移行のために共有済みの app 履歴を rebase、amend、force-push しません。
484
511
 
485
- ### 10.6. 二重 worktree の構成案と統合順序
512
+ ### 10.6. 複数リポジトリの worktree と統合順序
486
513
 
487
- 文書とソースの両方を1つの登録簿項目で扱う将来構成では、同じ task ID の下に両リポジトリの worktree を作ります。
514
+ `repos` を宣言した project では、同じ task ID の下にリポジトリごとの worktree を作ります。プロジェクトリポジトリの worktree は予約名 `project`、プロダクトリポジトリの worktree は宣言した `name` のディレクトリに置きます。
488
515
 
489
516
  ```text
490
- app1-worktrees/
517
+ app1-specdojo-worktrees/
491
518
  └── <task-id>/
492
- ├── docs/ # app1-specdojo の worktree
493
- └── src/ # app1 の worktree
519
+ ├── project/ # app1-specdojo の worktree(agent の cwd)
520
+ ├── app1/ # app1 の worktree
521
+ └── app2/ # app2 の worktree(宣言した場合)
494
522
  ```
495
523
 
524
+ 各 exec branch は、プロジェクト側が現在の統合先から、プロダクト側が `integration_branch`(省略時はそのリポジトリの現在のブランチ)の先端から作ります。agent はプロジェクト worktree を作業ディレクトリとし、プロダクト worktree の絶対パスを環境変数 `SPECDOJO_REPO_<NAME>` で受け取ります。provider ごとの書き込み許可は runner が起動引数へ付け足します。
525
+
496
526
  統合は次の順序で行います。
497
527
 
498
- 1. `src/` で app 側の検証を実行し、`app1/` の統合先ブランチへ統合する。
499
- 2. 統合後の app 履歴に `Refs:` trailer が残っていることを確認し、trace key、PR 参照、最終 commit
500
- snapshot を `docs/` 側の result 本文へ記録する。
501
- 3. `docs/` で SpecDojo 側の検証を実行し、`app1-specdojo/` の統合先ブランチへ統合する。
528
+ 1. 全リポジトリで commit 対象を commit し、merge できるかを事前に検査する。1つでも統合できないリポジトリがあれば、どのリポジトリも統合しない。
529
+ 2. 宣言順にプロダクトの exec branch を統合先ブランチへ merge commit で統合する。プロダクト側の commit と merge commit には `Refs: <project-id>:<item-id>` を付ける(register 項目の場合)。
530
+ 3. 統合後のプロダクトの trace key と commit snapshot を、プロジェクト側の result 本文へ記録する。
531
+ 4. プロジェクトの exec branch を `app1-specdojo/` の統合先ブランチへ統合する。
532
+ 5. 全リポジトリの統合後に、全リポジトリの worktree と exec branch をまとめて撤去する。
502
533
 
503
- ソースを先に統合することで、プロダクトの統合を SpecDojo 側の統合成否から切り離します。失敗時の部分状態は次の2つに限定します。
534
+ ソースを先に統合することで、プロダクトの統合を SpecDojo 側の統合成否から切り離します。プロジェクト側の記帳(`review` への遷移と result)は、プロダクトがすべて統合された後にだけ統合先へ入ります。
504
535
 
505
- | 失敗箇所 | 統合状態 | 登録簿と再開の扱い |
506
- | ----------------------- | --------------------------- | --------------------------------------------------------------------- |
507
- | app 側の統合が失敗 | app / SpecDojo ともに未統合 | 項目を `waiting` とし、app 側の統合から再開する |
508
- | SpecDojo 側の統合が失敗 | app のみ統合済み | 項目を `waiting` とし、app を再統合せず SpecDojo 側の統合だけ再開する |
536
+ ### 10.7. 複数リポジトリの統合の失敗と再開
509
537
 
510
- app のみ統合済みの状態は完了ではないため、`review` へ進めません。SpecDojo 側の統合を打ち切る場合、app の変更を残すか revert するかは、通常の統合後の判断として人が決めます。自動的に履歴を巻き戻しません。
538
+ 統合が途中で失敗した場合、失敗位置より前のリポジトリは統合済みのまま残り、失敗位置から後ろは統合しません。Git は複数リポジトリの原子的な更新を持たないため、runner は統合済みの範囲を巻き戻さず、リポジトリ別の状態を記録して失敗位置から再開します。
511
539
 
512
- ### 10.7. 二重 worktree の採用前に必要な実装
540
+ | 失敗箇所 | 統合状態 | 登録簿と再開の扱い |
541
+ | ------------------------ | -------------------------------------------- | --------------------------------------------------------------------------- |
542
+ | 事前検査 | 全リポジトリが未統合 | 項目を `waiting` とし、原因を解消してから統合段を再開する |
543
+ | n 番目のプロダクトの統合 | 1〜n-1 番目のプロダクトだけ統合済み | 項目を `waiting` とし、統合済みのプロダクトを飛ばして n 番目から再開する |
544
+ | プロジェクトの統合 | 全プロダクトが統合済み、プロジェクトは未統合 | 項目を `waiting` とし、プロダクトを再統合せずプロジェクトの統合だけ再開する |
513
545
 
514
- プロダクト実装も同じ項目で扱うには、少なくとも次を実装します。
546
+ - リポジトリ別の状態(`pending` / `merged` / `unchanged` / `failed`)は、run の `pipeline-state.json` の `stages.integrate.repos` に記録します。失敗の詳細は同じ run の `integrate.log` に残ります。
547
+ - `block_reason` には、失敗したリポジトリ、統合済みのリポジトリ、未統合のリポジトリを記録します。
548
+ - 失敗後も全リポジトリの worktree と exec branch を保持します。原因を解消した後、`exec run --register <item-id> --worktree --resume` で統合段から再開します。agent は再実行しません。
549
+ - 再開の前に、runner は未統合のリポジトリにだけ統合先の最新を取り込みます。`stages.integrate.repos` で統合済み(`merged` / `unchanged`)のプロダクトは取り込まず、exec branch に merge commit を作りません。
550
+ - 再開時は、統合先へ取り込み済みのプロダクトを merge し直さず、最初の統合で作った merge commit を result の trace 表へ記録します。
515
551
 
516
- - **親検証の割り当て**: 検証 ID ごとに実行対象のリポジトリと `cwd` を宣言し、ソースの test は `src/`、文書の lint と schema 検証は `docs/` で実行する。
517
- - **agent の作業ディレクトリ**: `<task-id>/` を agent の作業ディレクトリとして両 worktree を読み書き可能にし、`paths` と `targets` の解決基準を明示する。
518
- - **失敗時の worktree 保持**: 失敗した段と統合済みのリポジトリを識別し、調査・再開に必要な worktree の保持と撤去条件を定める。
519
- - **統合処理の複製**: commit 対象の算出、branch への統合、統合済み判定、pipeline state の記録を repo / worktree の2組に対応させ、app → SpecDojo の順序と再開位置を保存する。
552
+ 一部のリポジトリだけが統合済みの状態は完了ではないため、`review` へ進めません。統合を打ち切る場合、統合済みのプロダクトの変更を残すか revert するかは、通常の統合後の判断として人が決めます。自動的に履歴を巻き戻しません。