specdojo 0.2.0 → 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 (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  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 +140 -9
  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-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -51,7 +51,7 @@ agent にタスクを実行させる経路は、実行対象の出どころに
51
51
  | 代表コマンド | `exec run --task` / `exec run --auto` | `exec run --register` | `routine run --due` |
52
52
  | 起動 | 人、または routine(`job-exec-auto`) | 人、または routine(`job-register-sweep`) | 外部スケジューラ(cron / CI) |
53
53
  | 状態追跡 | exec events(claim / complete / block) | register の遷移(in-progress / review / waiting) | `last_run` の記録のみ |
54
- | 隔離 | worktree(`--worktree` / `--auto`) | in-place のみ | -(実行経路へ委譲) |
54
+ | 隔離 | worktree(`--worktree` / `--auto`) | `run.register_execution` または CLI で選択 | -(実行経路へ委譲) |
55
55
  | 終端の扱い | `complete` event(human finalize で確定) | 人が確認して `register close` | -(発火の記録のみ) |
56
56
  | 典型用途 | 計画された成果物の作成・レビュー・確定 | 立ち上げ時の課題・判断、進行中の計画外対応・調査 | 日次スイープ・夜間バッチなどの定期実行 |
57
57
 
@@ -79,19 +79,25 @@ register 実行は exec events を記録しないため、schedule の Ready・C
79
79
  | 1 task をカレントで実行し進捗へ反映する | `exec run --task --track-state` | あり | なし |
80
80
  | 1 task を隔離して実行する | `exec run --task --worktree` | あり | あり |
81
81
  | Ready 順に自動実行する | `exec run --auto` | あり | あり |
82
- | 登録簿の項目を agent に実行させる | `exec run --register` | register の遷移 | なし |
83
- | 登録簿の複数項目を指定順に直列実行する | `exec run --register PJR-A PJR-B` | register の遷移 | なし |
82
+ | 登録簿の項目を agent に実行させる | `exec run --register` | register の遷移 | 設定依存 |
83
+ | 登録簿の複数項目を指定順に実行する | `exec run --register PJR-A PJR-B` | register の遷移 | 設定依存 |
84
84
  | plan を確認してから実行する | `exec plan` -> `exec run --plan` | 任意 | 任意 |
85
85
  | worktree の各段階を人が確認する | `exec worktree prepare` から `remove` | 手動 | あり |
86
86
  | 同じplanで複数agentを比較する | `exec trial run` | なし | agent別 |
87
87
 
88
88
  `exec run --register ... --register-commit` は、各IDのcommit後にhookによる整形差分を同じcommitへ収束させ、対象差分が残っていないことを検証します。登録簿・派生ビュー・当該plan/resultはrunner管理パスとして扱い、その他の実行前からある利用者変更はcommitしません。過去の未commit plan/resultを検出した場合は、現在のIDへ混ぜず警告します。
89
89
 
90
+ worktree の checkpoint 作成時に root の index に staged 変更がある場合、checkpoint 対象の plan、result、event、登録簿記帳と重なるパスだけを停止理由にします。重ならない staged 変更はパスを警告へ表示して保持したまま実行を続けます。checkpoint または register の runner commit が失敗した場合も、runner が対象にしたパスだけを unstage し、無関係な staged 変更は変更しません。
91
+
92
+ register 実行の場所は `.specdojo/exec-defaults.yaml` の `run.register_execution`(`worktree` / `in-place`)で選びます。設定がない既存リポジトリは互換性のため in-place のままです。CLI の `--worktree` / `--in-place` は設定を上書きし、両方を同時に指定するとエラーになります。
93
+
94
+ 通常は、失敗時の変更を隔離でき、`--resume` / `--force-restart` を使える worktree を選びます。worktree の準備時間が作業時間に見合わない、変更対象が小さく、失敗時に作業ツリーへ残る差分をその場で整理できる場合だけ `--in-place` を使います。in-place では `--resume` / `--force-restart` / `--join` と `--parallel` は使えません。`--register-commit` は in-place だけで意味を持ち、worktree は常に checkpoint と統合 commit を作ります。
95
+
90
96
  schedule タスクの自動実行・手動実行の具体的な手順は [Schedule実行運用ガイド](schedule-operation-guide.md)、routine の定義と実行は [routine運用ガイド](routine-operation-guide.md) を参照してください。
91
97
 
92
98
  ### 1.4. project単位の実行ロック
93
99
 
94
- `exec run` は、実行対象 project の `execution_path/exec/.locks/exec-run.lock` を run 全体で保持します。同じ project に対する手動実行、routine、CI の `exec run` は同時に進まず、1つの run 内の `--parallel` worker だけが並列に動きます。`exec resume` も同じロックへ参加するため、再開処理と新規実行も重なりません。`exec cycle` は再開・古い track の再生成・状態再計算・`--auto` loop の一連の step をこの単一ロック内で保持し、step 間に他の実行が割り込まないことを保証します。
100
+ `exec run` は、実行対象 project の `execution_path/exec/.locks/exec-run.lock` を run 全体で保持します。同じ project に対する手動実行、routine、CI の `exec run` は同時に進まず、1つの run 内の `--parallel` worker だけが並列に動きます(register の worktree 実行へ `--join` で合流する場合を除きます。後述の「実行中の register worktree 実行へ後から合流する」を参照してください)。`exec resume` も同じロックへ参加するため、再開処理と新規実行も重なりません。`exec cycle` は再開・古い track の再生成・状態再計算・`--auto` loop の一連の step をこの単一ロック内で保持し、step 間に他の実行が割り込まないことを保証します。
95
101
 
96
102
  ロックは別プロセスの heartbeat で更新されます。正常終了時は `finally` で解放し、プロセスが異常終了して heartbeat が stale になった場合は、後続 run がロックを安全に奪取します。
97
103
 
@@ -108,6 +114,48 @@ specdojo exec run --project <project-id> --auto --if-busy skip
108
114
  specdojo exec run --project <project-id> --auto --if-busy wait
109
115
  ```
110
116
 
117
+ #### 1.4.1. 実行中の register worktree 実行へ後から合流する
118
+
119
+ register の worktree 実行中に別の項目を並行で走らせたい場合は、後から起動する run に `--join` を付けます。`--join` の run は `exec-run.lock` ではなく `exec/.locks/exec-run-join/` の枠を取得し、実行中の run の終了を待たずに開始します。`--join` を付けない run の動作は従来どおりで、busy なら `--if-busy` に従います。
120
+
121
+ ```bash
122
+ # 実行中の run(PJR-T3NN)へ、別項目 PJR-00QV を合流させる
123
+ specdojo exec run --project <project-id> --register PJR-00QV --worktree --join
124
+ ```
125
+
126
+ 合流できるのは、register の worktree 実行どうしだけです。worktree 実行は、プロセスを跨いで共有される資源を次のとおり統制するため、並行しても衝突しません。
127
+
128
+ | 資源 | 統制の方法 | ロックの配置 |
129
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------- |
130
+ | agent の同時実行数 | provider の `max_concurrency` をプロセスを跨いで数える | `exec/.locks/provider-<provider>/` |
131
+ | root での状態遷移・生成物の再生成・統合段 | start 遷移・checkpoint・develop への merge・wait commit・派生ビューの再生成を 1 つずつ実行する | `exec/.locks/exec-lifecycle/` |
132
+ | 親 runner の検証(`parent_validations`) | `pipeline.parent_validation_concurrency` をプロセスを跨いで数える | `exec/.locks/parent-validation/` |
133
+ | 同じ項目の二重実行 | 従来どおり register の start 遷移が防ぐ。遷移は上記の直列化の中で行うため、2 つの run が同時に通らない | - |
134
+
135
+ - 同時に動かせる run の数は `exec-defaults.yaml` の `run.max_concurrent_runs`(既定 4。最初の run を含む)で決まります。`1` にすると `--join` を無効にできます。
136
+ - 合流の枠が埋まっている場合は `--if-busy` に従います。routine から `--if-busy skip` で起動した場合は、従来どおり skip として記録されます。
137
+ - `--auto`、`--task`、`exec cycle`、`exec resume` など register の worktree 実行以外の run は、合流中の run が残っている間は busy として扱われます。
138
+ - 各 run は自分の項目の結果だけを持ち、一方が失敗しても、もう一方の run と worktree には影響しません。
139
+ - 枠の待ちは run のログに `Waiting for <provider> slot held by another exec run`、`Waiting for the register lifecycle lock held by another exec run`、`Waiting for parent validation slot held by another exec run` として出力されます。
140
+
141
+ 上限と現在の使用枠は `exec slots` で確認できます。ロックは取得しないため、実行中にいつでも実行できます。
142
+
143
+ ```bash
144
+ specdojo exec slots --project <project-id>
145
+ ```
146
+
147
+ ```text
148
+ max concurrent runs: 4
149
+ exec run (primary): 1/1
150
+ exec-run (pid 1234, since 2026-09-28T10:00:00Z, joinable)
151
+ exec run (--join): 1/3
152
+ slot-1: exec-run (pid 5678, since 2026-09-28T10:05:00Z)
153
+ register lifecycle: 0/1
154
+ provider opencode: 1/1
155
+ slot-1: provider:opencode PJR-00QV executor (pid 5678, since 2026-09-28T10:05:10Z)
156
+ parent validations: 0/1
157
+ ```
158
+
111
159
  ### 1.5. 実行eventの保存粒度
112
160
 
113
161
  Schedule taskの状態eventは、`execution_path/exec/events/`へ1 event 1 JSONファイルで保存されます。ファイル名はUTC時刻、actor、task ID、event種別、衝突回避用の乱数を含みます。`exec refresh`などの読取処理は全eventを時系列に並べ、foldして現在状態を再構成します。この保存規範の正本は[[sysd-cross-cutting-policy|SpecDojo システム設計横断ルール]]の`scp-STA-001`です。
@@ -148,7 +196,7 @@ specdojo exec trial run \
148
196
 
149
197
  `--agent`だけならreporterなし、`--agent`と`--reporter-by`なら全trialで同じreporter、`--pair`ならtrialごとのreporterを使います。比較記録の`reporter_mode`にはそれぞれ`none` / `shared` / `paired`を保存します。
150
198
 
151
- 比較記録は`execution_path/exec/trials/<comparison-id>/comparison.json`へ集約します。planと実際のpromptのSHA-256、base commitと互換性確認、agent別の所要時間、終了コード、変更ファイル、検証結果、executor構造化出力を記録します。所要時間はexecutor、親検証、trial全体を分け、親検証の実行時間がagent比較へ混入しないようにします。検証件数もexecutor報告と親runner実行を分け、executorの`passed` / `failed` / `not_run`と報告総数を保存します。理由付きの`not_run`は意図した省略、報告件数の不足は未報告として比較できます。reporterについては構造化出力の成否、形式試行回数、形式再試行回数、結果、失敗理由に加え、失敗分類(`reported_blocked` / `invalid_output` / `invocation_failure` / `rate_limit`)を記録します。判断の質、文章の質、範囲の遵守は機械指標と混ぜず、`exec trial rate`で1〜5と注記を記録します。
199
+ 比較記録は`execution_path/exec/trials/<comparison-id>/comparison.json`へ集約します。planと実際のpromptのSHA-256、base commitと互換性確認、agent別の所要時間、終了コード、変更ファイル、検証結果、executor構造化出力を記録します。所要時間はexecutor、親検証、trial全体を分け、親検証の実行時間がagent比較へ混入しないようにします。検証件数もexecutor報告と親runner実行を分け、executorの`passed` / `failed` / `not_run` / `requires_human`と報告総数を保存します。適用外の検査は `not_applicable` と理由を検証結果へ記録し、`not_run` は適用される検査を実行しなかった場合に使います。`requires_human` は sandbox 外で人が行う確認、報告件数の不足は未報告として比較できます。reporterについては構造化出力の成否、形式試行回数、形式再試行回数、結果、失敗理由に加え、失敗分類(`evidence_blocked` / `invalid_output` / `invocation_failure` / `rate_limit`)を記録します。判断の質、文章の質、範囲の遵守は機械指標と混ぜず、`exec trial rate`で1〜5と注記を記録します。
152
200
 
153
201
  `pipeline.parent_validations`が設定されている場合、trialも通常のpipelineと同様にexecutor成功後・reporter起動前に各worktreeで親検証を実行します。結果は`source: runner`としてevidenceへ追記され、失敗したtrialは採用可能な`succeeded`になりません。executorが失敗して親検証へ進めなかった場合も`parent_validation.status: not_run`として比較記録と`trial status`に表示します。これにより、採用前に親検証の不足を確認できます。
154
202
 
@@ -164,7 +212,7 @@ specdojo exec trial rate \
164
212
  --notes "human review notes"
165
213
  ```
166
214
 
167
- 評価後は成功したtrialを1つだけ採用します。`adopt`は選択したbranchを現在branchへmergeし、残りのworktreeとbranchを破棄します。採用前に`trial status`の親検証状態とexecutorの報告総数・`not_run`件数を確認します。`not_run`の理由は`comparison.json`の`executor.validations`で確認できます。破棄後も中央の比較記録とagent別evidenceは残ります。どれも採用しない場合は`discard`を使います。
215
+ 評価後は成功したtrialを1つだけ採用します。`adopt`は選択したbranchを現在branchへmergeし、残りのworktreeとbranchを破棄します。採用前に`trial status`の親検証状態とexecutorの報告総数・`not_run`件数・`requires_human` 件数を確認します。それぞれの理由は`comparison.json`の`executor.validations`で確認できます。破棄後も中央の比較記録とagent別evidenceは残ります。どれも採用しない場合は`discard`を使います。
168
216
 
169
217
  ```bash
170
218
  specdojo exec trial adopt \
@@ -175,7 +223,7 @@ specdojo exec trial adopt \
175
223
  specdojo exec trial discard --project <project-id> --comparison <comparison-id>
176
224
  ```
177
225
 
178
- 1回の比較だけでは`pm-members.yaml`を自動変更しません。人が客観指標と主観評価を確認し、複数タスクで傾向が再現した場合にpriorityやcapabilitiesを更新します。この判断方針も比較記録の`agent_selection`へ保存されます。
226
+ 1回の比較だけでは`.specdojo/agent-members.yaml`を自動変更しません。人が客観指標と主観評価を確認し、複数タスクで傾向が再現した場合にpriorityやcapabilitiesを更新します。この判断方針も比較記録の`agent_selection`へ保存されます。
179
227
 
180
228
  agent起動時はhook由来の`GIT_DIR`などを継承せず、各trialのcwdからGit repositoryを解決します。trial前後でagent worktreeのHEADまたは監視対象のlocal configが変化した場合、そのtrialは`agent-git-state-write:`で失敗し、採用対象になりません。別worktreeで行われたrunnerの遷移commitと、runnerが作成したbranchの表示用metadataは検知対象に含めません。
181
229
 
@@ -204,7 +252,7 @@ agent起動時はhook由来の`GIT_DIR`などを継承せず、各trialのcwdか
204
252
 
205
253
  `release` は `doing` / `blocked` の試行を破棄して `todo` に戻します。`cancel` は `todo` のタスクを終端状態にする操作です。
206
254
 
207
- executor / reporter pipeline では、run ごとの `exec/evidence/<task>/<run>/pipeline-state.json` に各段(executor / reporter と、runner が担う統合段 `integrate`)の状態、agent、試行回数、evidence / result 参照を保存します。reporter 失敗の block event は `pipeline_stage=reporter`、統合失敗の block event は `pipeline_stage=integrate` を持ち、どちらも `pipeline_state_ref` から同じ run を再開します。`exec resume --task <task-id>` は state に応じて reporter または統合段だけを再開し、完了済みの agent 段を重複実行しません。
255
+ executor / reporter pipeline では、run ごとの `exec/evidence/<task>/<run>/pipeline-state.json` に各段(executor / reporter と、runner が担う統合段 `integrate`)の状態、agent、試行回数、evidence / result 参照を保存します。executor 中断の block event は `pipeline_stage=executor`、reporter 失敗は `pipeline_stage=reporter`、統合失敗は `pipeline_stage=integrate` を持ち、いずれも `pipeline_state_ref` から同じ run を再開します。`exec resume --task <task-id>` は state に応じて未完了の段から再開し、完了済みの agent 段を重複実行しません。
208
256
 
209
257
  stage agent を明示する場合は次のように指定します。片方を省略すると、その stage は要件と優先度から自動選択されます。
210
258
 
@@ -284,13 +332,15 @@ specdojo exec run --project <project-id> --task <task-id>
284
332
 
285
333
  AI モデルの rate limit に達した場合、`exec run` は `.specdojo/exec-defaults.yaml` の `rate_limit_policy` に従います。
286
334
 
287
- | 状況 | 代表対応 |
288
- | -------------------------------- | ----------------------------------------------------------------------- |
289
- | 別 provider / agent の候補がある | 次候補へ切り替え、独立した Ready task は継続する |
290
- | reset / retry-after を取得できる | 再開時刻と worktree を block event に保持し、`exec resume --due` で再開 |
291
- | 時刻不明で明示 cooldown がある | 設定済み cooldown から再開時刻を記録する |
292
- | 時刻不明で cooldown もない | 時刻を推定せず、通常の blocked として人に委ねる |
293
- | `quota_exhausted` | 自動再開せず、別 provider が無ければ人に委ねる |
335
+ | 状況 | 代表対応 |
336
+ | -------------------------------- | ------------------------------------------------------------------------ |
337
+ | 別 provider / agent の候補がある | 次候補へ切り替え、独立した Ready task は継続する |
338
+ | reset / retry-after を取得できる | 再開時刻と worktree を保持し、`exec resume --due` または `--task` で再開 |
339
+ | 時刻不明で明示 cooldown がある | 設定済み cooldown から再開時刻を記録する |
340
+ | 時刻不明で cooldown もない | 時刻を推定せず、通常の blocked として人に委ねる |
341
+ | `quota_exhausted` | 自動再開せず、別 provider が無ければ人に委ねる |
342
+
343
+ 再開時刻(due)が記録されたタスクは、一括で再開する `exec resume --due` と、指定したタスクを即時再開する `exec resume --task <task-id>` の両方を利用できます。定時実行による自動復旧には `--due` を使い、個別の動作確認や手動での早期再開には `--task` を選ぶことができます。
294
344
 
295
345
  定時起動する場合は routine から `job-exec-resume` を参照します。due 判定と `blocked -> doing` の確保は scheduler lock 内で行われるため、多重起動でも同じ task を重複実行しません。詳細は [routine運用ガイド](routine-operation-guide.md) を参照してください。
296
346
 
@@ -319,6 +369,13 @@ provider別の `max_concurrency` や agent 選択は [exec設定ガイド](exec-
319
369
  specdojo exec run --project <project-id> --task <task-id> --worktree
320
370
  ```
321
371
 
372
+ schedule に `agent_pipeline` を持たない plan(`exec plan --deliverable <localId> --mode review` で生成した review plan など)は、`exec run --plan` または `exec run --deliverable` に `--executor-by` / `--reporter-by` を足すと同じ 2 stage で実行します。片方だけ指定した場合、もう一方は `stage_role` による自動選択で決まります。reporter が scaffold 済みの result を記入するため、`--plan` では frontmatter に `task_id` を持つ plan が必要です。`--by` に `stage_role` を持つ pipeline 用 agent を指定すると、result 未記入の blocked にはせず、`--executor-by` / `--reporter-by` を使うよう案内するエラーで実行前に拒否します。
373
+
374
+ ```bash
375
+ specdojo exec run --project <project-id> --plan <execution-path>/exec/plans/<stem>-plan.md \
376
+ --executor-by <executor-nickname> --reporter-by <reporter-nickname>
377
+ ```
378
+
322
379
  run ごとの実行記録は `<execution_path>/exec/evidence/<task-id>/<run-id>/` に残ります。停止位置と再開可否はここを見て判断します。
323
380
 
324
381
  | ファイル | 確認できること |
@@ -327,20 +384,21 @@ run ごとの実行記録は `<execution_path>/exec/evidence/<task-id>/<run-id>/
327
384
  | `evidence.json` | executor の変更ファイル、diff サマリ、検証結果、最終メッセージ、executor / reporter のログ参照 |
328
385
  | `executor.log` | executor の出力抜粋(秘匿値は伏せ字化、64KiB で切り詰め) |
329
386
  | `reporter-attempt-<n>.stdout.log` / `reporter-attempt-<n>.stderr.log` | 失敗した reporter の形式試行別の生出力(秘匿値は伏せ字化、各ストリーム 64KiB で切り詰め) |
387
+ | `integrate.log` | checkpoint・統合段の commit / merge 失敗の stdout / stderr 全文(秘匿値は伏せ字化) |
330
388
 
331
- agent ログは人が調査するための参照先で、reporter には渡りません。reporter が受け取るのは plan と `evidence.json` と出力スキーマだけです。失敗理由の要約だけでは原因が分からない場合は、`evidence.json` の `log_refs` から stdout / stderr を個別に確認します。ログは Git 管理対象の evidence ディレクトリにありますが、失敗中の worktree では未コミットのため、`--force-restart` などで破棄する前に確認します(詳細は [exec設定ガイド](exec-config-guide.md) の `evidence とログの引き渡し方針`)。
389
+ agent ログは人が調査するための参照先で、reporter には渡りません。reporter が受け取るのは plan、runner 管理記録を除いた `evidence.json` の変更一覧、文章項目と対応づけ用パスだけの出力スキーマです。runner 管理記録は、解決済みの execution path 配下の evidence、project register とその派生ビュー、当該 result のパスを基準に除外します。ただし executor の試行中に runner 管理記録が実際に変わった場合、そのパスと状態は reporter 専用の `runner_context.runner_managed_attempt_changes` に含めます。reporter は、executor の最終メッセージがその変更に触れたのに `changed_files` にないという理由だけで確認を求めません。result の変更パスはこの除外後の `changes`、`outcome` と `block_reason` は executor の stage・終了コード・保護理由と検証結果から runner が機械生成します。executor または親 runner の検証に failed / `not_run` があれば blocked です。executor の `not_run` は、親 runner が同じコマンドを project で実行して成功していれば満たされたものとして扱います。また、対応する npm script がない、`npx` の package が未導入、または SpecDojo サブコマンドの設定上の適用条件を満たさないと runner が確定できる場合は適用外として block せず、result の申し送りへ「適用外の検証(runner の判定)」を残します。この判定は reporter 専用の `runner_context.mechanically_not_applicable` にも含め、reporter は同じ検証の実行を申し送りで求めません。`catalog validate` は対象 project の `catalog_path` で判定し、設定や対象 project を特定できない場合と適用条件が未定義のサブコマンドは救済しません。対象 project は `--project <id>`、run の対象 project、`current_project` の順に決めるため、別の project の `catalog_path` では判定しません。`<repo>:<path>` を引数に含むコマンドや `--prefix <repo>` 付きのコマンドは、そのプロダクトリポジトリの `package.json` で判定します。`npm run <name> -- <args>` と `npm run <name> <args>` も `<name>` の script が存在すれば適用外の申告を反証しますが、引数付きコマンドを親 runner が実行した引数なしコマンドと同一とはみなしません。`npm run check` のような合成コマンドは、構成する各コマンドが親 runner か executor の検証で通っていれば満たされたものとして扱います。理由付きの `not_applicable` は block せず result の申し送りへ残しますが、理由がない場合や、存在する npm script/依存 package を適用外とした場合は blocked です。ただし SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。executor の `requires_human` は sandbox 外で人が行う確認として block せず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」を機械的に追記します。reporter は実施内容、パスと対にした各変更の説明、申し送り、approach、review の判断根拠と改善指示だけを返します。runner はパスで説明を突き合わせ、順序は問いません。説明がない evidence のパスには差分参照を促す既定文を記録し、evidence にないパスの説明は捨てるため、件数の過不足で result の作成は失敗しません。機械管理項目を追加した出力は形式不正として拒否されます。失敗理由の要約だけでは原因が分からない場合は、記録済み `evidence.json` の `log_refs` から stdout / stderr を個別に確認します。ログは Git 管理対象の evidence ディレクトリにありますが、失敗中の worktree では未コミットのため、`--force-restart` などで破棄する前に確認します(詳細は [exec設定ガイド](exec-config-guide.md) の `evidence とログの引き渡し方針`)。
332
390
 
333
391
  stage 別の失敗と対応は次のとおりです。
334
392
 
335
- | 失敗 | 状態の見え方 | 対応 |
336
- | ----------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
337
- | executor の異常終了 | executor が `failed`、reporter は `pending` | 原因を解消し `exec unblock` で継続、または `exec release` でやり直す |
338
- | executor の rate limit | executor が `rate_limited`、block に再開時刻 | `レートリミット対応` と同じ(`exec resume --due`) |
339
- | reporter のプロセス失敗 | executor が `succeeded`、reporter が `failed` | `exec resume --task <task-id>` で reporter から再開する |
340
- | reporter の出力形式エラー | reporter を最大3回再実行した後に `failed` | 同上(executor は再実行されない) |
341
- | 親 runner の検証失敗 | evidence の `source: runner` が `failed` | 原因を解消して reporter を再開する(親検証だけ再実行される) |
342
- | reporter の `outcome=blocked` | result が `blocked` になり `block_reason` に理由が残る | 理由を読み、成果物側の不足を解消してから再実行する |
343
- | commit / merge / 撤去の失敗 | executor・reporter が `succeeded`、統合が `failed` | `exec resume --task <task-id>` で統合段だけ再開する |
393
+ | 失敗 | 状態の見え方 | 対応 |
394
+ | ----------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
395
+ | executor の異常終了 | executor が `failed`、reporter は `pending` | 原因を解消し `exec resume --task <task-id>` で executor から継続、または `exec release` でやり直す |
396
+ | executor の rate limit | executor が `rate_limited`、block に再開時刻 | `レートリミット対応` と同じ(`exec resume --due`) |
397
+ | reporter のプロセス失敗 | executor が `succeeded`、reporter が `failed` | `exec resume --task <task-id>` で reporter から再開する |
398
+ | reporter の出力形式エラー | reporter を最大3回再実行した後に `failed` | 同上(executor は再実行されない) |
399
+ | 親 runner の検証失敗 | evidence の `source: runner` が `failed` | 原因を解消して reporter を再開する(親検証だけ再実行される) |
400
+ | evidence の機械判定が blocked | result が `blocked` になり `block_reason` に理由が残る | executor または親検証の理由を読み、成果物側の不足を解消してから再実行する |
401
+ | commit / merge / 撤去の失敗 | executor・reporter が `succeeded`、統合が `failed` | `exec resume --task <task-id>` で統合段だけ再開する |
344
402
 
345
403
  reporter で止まったタスクは、同じ claim のまま reporter だけを再開できます。再開時は `pipeline-state.json` と executor evidence の task ID / run ID の一致を確認し、一致しない場合や欠損している場合は evidence を再利用せず、新しい run として executor から実行し直します。保存済みの親 runner 検証だけが失敗している場合は、現在の worktree でその固定許可リスト検証を再実行し、結果を evidence へ反映してから reporter を起動します。`source: executor` の検証失敗は成果物側の記録なので、この経路では再評価しません。
346
404
 
@@ -355,7 +413,22 @@ executor と reporter が成功した後の commit・merge・worktree 撤去で
355
413
 
356
414
  ### 2.7. register実行の再開
357
415
 
358
- register 実行(`exec run --register --worktree`)を executor/reporter パイプラインで走らせた場合、途中で止まった run は止まった段から再開できます。register 実行は exec events を持たないため、再開は `exec resume` ではなく `exec run --register` の `--resume` で行います。
416
+ 複数の register 項目を worktree で並列実行するときは、`--executor-by` に `PJR-ID=nickname` をカンマ区切りで渡すと、項目ごとに executor を固定できます。従来の `--executor-by <nickname>` は引き続き全項目への共通指定です。項目別指定は起動対象をすべて指定する必要があり、起動対象外の ID や指定漏れがあると、状態遷移や worktree 作成の前にエラーになります。`--dry-run` では各項目について解決した executor とコマンドを確認できます。
417
+
418
+ ```bash
419
+ specdojo exec run \
420
+ --project <project-id> \
421
+ --register PJR-0001 PJR-0002 PJR-0003 \
422
+ --executor-by PJR-0001=codex-expert-executor,PJR-0002=agy-expert-executor,PJR-0003=agy-claude-expert-executor \
423
+ --reporter-by gemma-reporter \
424
+ --worktree \
425
+ --parallel 3 \
426
+ --dry-run
427
+ ```
428
+
429
+ 並列 pipeline の executor と reporter は、それぞれの provider に設定された `max_concurrency` の枠を agent プロセスの実行中だけ使用します。同じ provider の枠が埋まっている stage は待機し、別 provider に空きがあればそちらは並行して進みます。このため、たとえばローカル provider の reporter を `max_concurrency: 1` にしたまま、複数のクラウド provider に executor を分散できます。
430
+
431
+ register 実行を worktree モードで executor/reporter パイプラインとして走らせた場合、途中で止まった run は止まった段から再開できます。register 実行は exec events を持たないため、再開は `exec resume` ではなく `exec run --register` の `--resume` で行います。
359
432
 
360
433
  ```bash
361
434
  specdojo exec run \
@@ -373,19 +446,43 @@ specdojo exec run \
373
446
  | `reporter` | executor が `succeeded`、reporter が未完了 | reporter だけを起動し、成功後に統合まで進む |
374
447
  | `integrate` | executor と reporter が `succeeded`、統合が未完了 | agent を起動せず、commit → merge → worktree 撤去だけ行う |
375
448
 
449
+ 親検証の失敗を executor に直させる場合は、reporter 段から再開可能な run に `--resume-from executor` を指定します。worktree、未コミット成果、plan/result は保持され、executor を新しい checkpoint で再実行します。通常の `--resume` は引き続き state が示す段から再開します。
450
+
451
+ ```bash
452
+ specdojo exec run \
453
+ --project <project-id> \
454
+ --register <PJR-ID> \
455
+ --worktree \
456
+ --resume \
457
+ --resume-from executor
458
+ ```
459
+
460
+ 強制した executor の prompt には、保存済み evidence にある失敗した親検証の ID と要約を申し送ります。保護機構の block から通常どおり executor を再開する場合は、保存済みの block 理由を申し送ります。統合段から executor へ戻す指定、worktree が無い run、再開できない run は、register の状態と既存成果を変えずに拒否します。
461
+
376
462
  executor のプロセス結果は、親 runner 検証を始める前に `executor.log` と `evidence.json` へ保存し、`pipeline-state.json` の executor を `succeeded` へ更新します。親検証中にプロセスが中断した場合、`--resume` は保存済みの executor evidence を再利用し、不足している親検証を実行してから reporter へ進みます。agent 実行中の中断で executor が `running` のまま残った場合は、未コミット成果を含む既存 worktree を破棄せず、同じ plan/result を入力に executor から再実行します。`--executor-by` / `--reporter-by` を省略した場合は state に記録された各 agent を引き継ぎます。
377
463
 
378
- `agent-config-write` または `agent-git-state-write` が executor を止めた場合は、通常の実装失敗を示す `failed` と区別して executor を `blocked` と記録します。申し送りを人または orchestrator が適用し、agent 由来の保護対象差分や Git 状態変更を worktree から解消した後、`--resume` は既存成果を保持したまま executor から再開します。申し送りを適用せず保護対象差分を残したまま再開した場合、executor が完了しても統合前の保護検査で再び block し、worktree を保持します。
464
+ どの段から再開する場合も、runner は親検証または agent の起動より前に、統合先ブランチの最新を exec branch と worktree へ merge commit で取り込みます。複数リポジトリの project では、宣言順に各プロダクトの統合先(`integration_branch`、未指定なら現在のブランチ)を取り込み、最後にプロジェクトの統合先を取り込みます。`pipeline-state.json` の `integrate.repos` で統合済み(`merged` / `unchanged`)のプロダクトは取り込まず、exec branch に merge commit を作りません。worktree に残る executor の未コミット成果は、未追跡ファイルを含めて一時退避し、取り込み後に index を復元せず戻します。同じファイルでも hunk が競合しなければ統合先と executor の変更を両方保持して再開します。取り込みで新しい commit が入った場合は、記録済みの親検証が成功していても検証し直します。これにより、wait の後に統合先で直した不具合や、人が統合先へ適用した保護対象設定が再開時の executor/親検証へ反映されます。`integrate` 段の再開で親検証が失敗した場合は、統合せずに `waiting` へ戻します。commit 済み変更の競合、または退避した成果を戻す際の競合が起きた場合は、同期用の merge commit を巻き戻して元の worktree へ executor の成果を戻し、register の状態を変えずに再開を拒否して理由を表示します。merge 済みで worktree の撤去だけが残っている統合再開では取り込みを行いません。
465
+
466
+ 中断した executor を再実行するとき、runner は再開前から worktree に存在する変更パスを prompt へ添え、既存差分を完了の証拠とみなさず plan 全体と全 `targets` を確認するよう指示します。再開後の executor evidence は各 target について `target_coverage` を持ち、変更した target は repo 相対 `path` が累積 worktree 差分に実在すること、変更不要の target は具体的な `reason` があることを runner が検査します。target の欠落、差分にない変更申告、理由のない未変更申告が一つでもあれば executor は `failed` となり、reporter と統合へ進みません。この検査は rate limit、crash、手動停止のいずれから executor 段を再開した場合も同じです。
467
+
468
+ register 由来の plan が `targets` を宣言していない場合、runner は初回 executor の開始前後を比較し、その試行で実質的に変更されたファイルを evidence の `attempt_changes` へ記録します。再開時は最初に記録した `attempt_changes` を target coverage の下限として使い、各パスについて `changed` または理由付きの `unchanged` を要求します。この集合は中断時点までに判明した対象だけを含む不完全な下限であり、作業範囲の上限ではありません。executor は下限外も含めて plan 全体を読み直し、必要な成果物を確認します。plan が `targets` を宣言している場合は、その宣言を優先し、初回変更集合から対象を導出しません。プロセスの強制終了などで runner が evidence を保存できず下限を記録できなかった場合は、従来どおり prompt による plan 全体の再確認を適用します。
469
+
470
+ 変更不要として受理した target の理由は reporter が生成する result の「申し送り」へ runner が転記します。これにより、ファイル差分がないことを黙って成功扱いにせず、変更不要と判断した根拠を完了記録に残します。通常の新規 run は既存 executor との互換性を保つため `target_coverage` を必須とせず、この追加ガードは中断後の executor 再開に限定します。
471
+
472
+ `agent-config-write` または `agent-git-state-write` が executor を止めた場合は、通常の実装失敗を示す `failed` と区別して executor を `blocked` と記録します。申し送りの設定変更を人または orchestrator が統合先へ適用し、agent 由来の保護対象差分や Git 状態変更を worktree から解消した後、`--resume` を実行します。runner が統合先を worktree へ取り込んでから、既存成果を保持した executor を再開するため、worktree で手動 merge する必要はありません。人が統合先へ適用した保護対象の内容と worktree に残る agent の変更が同じなら、同期によって agent 側の差分は解消され、その変更を理由に再び block されません。両者が異なり同じ箇所で競合する場合は、同期を巻き戻して register の状態を変えずに再開を拒否し、統合先には人が適用した内容、worktree には agent の提案内容をそれぞれ保持します。申し送りを適用せず保護対象差分を残したまま再開した場合、executor が完了しても統合前の保護検査で再び block し、worktree を保持します。
379
473
 
380
474
  reporter 段の再開の入力は、`pipeline-state.json`(stage 状態と plan / result の参照)と `evidence.json`(executor の変更・検証結果・最終メッセージ)です。`--reporter-by` を省略した場合は、その run で使った reporter agent を state から引き継ぎます。保存済みの親 runner 検証が失敗しているか不足していれば、Schedule 実行と同様に再実行して evidence を更新します。再開が成功した後は通常実行と同じ経路で、result の記入と status 更新、成果物の commit、統合ブランチへの merge、`register review` までを行います。
381
475
 
382
476
  統合段の再開は、executor と reporter が成功したまま commit・merge・worktree 撤去のいずれかが失敗した run が対象です。worktree は統合が完了したときにだけ撤去されるため、reporter 成功済みの worktree が残っていること自体が統合の未完了を意味します。この再開では agent を1つも起動せず、worktree に残っている成果物と記入済み result をそのまま統合します。前回の試行で merge まで完了していた場合は、取り込み済みの exec ブランチを再 merge せずに残りの手順(worktree 撤去と `register review`)だけを進めます。再開の開始時に項目は `in-progress` へ戻り、成功なら `review`、失敗なら `waiting` へ遷移するため、再試行の成否は登録簿の状態とイベントに残ります。統合段の進捗(開始と失敗)は `pipeline-state.json` の `integrate` にも記録します。
383
477
 
478
+ `specdojo.config.json` の project に `repos` を宣言している場合、統合段は宣言順のプロダクトリポジトリ、最後にプロジェクトリポジトリの順で統合し、リポジトリ別の状態(`pending` / `merged` / `unchanged` / `failed`)を `pipeline-state.json` の `integrate.repos` に記録します。途中で失敗すると、統合済みのリポジトリはそのまま残し、項目を `waiting` へ戻して全リポジトリの worktree を保持します。統合段の再開では、統合先へ取り込み済みのプロダクトを merge し直さず、失敗したリポジトリから統合を続けます。統合の順序と部分状態の詳細は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] の「複数リポジトリの統合の失敗と再開」を参照してください。
479
+
384
480
  再開できるかどうかは、対象 worktree の最新 run だけで判定します。次の場合は worktree・exec ブランチ・未コミットの成果を一切変更せず、理由を出力して終了コード 1 で終わります。
385
481
 
386
482
  | 状況 | 扱い |
387
483
  | ---------------------------------------------------- | ------------------------------------------------------------ |
388
484
  | 項目の exec worktree が無い | 再開せず、通常の再実行を促す |
485
+ | 宣言したプロダクトリポジトリの worktree が欠けている | 再開せず、通常の再実行を促す |
389
486
  | 最新 run の executor が `pending` / `failed` | 再開せず、通常の再実行を促す(古い run へは遡らない) |
390
487
  | 最新 run の executor が `rate_limited` / `blocked` | 既存 worktree の executor 段から再開する |
391
488
  | succeeded executor の `evidence.json` が欠損・不整合 | executor の記録を再利用できないため拒否する |
@@ -31,6 +31,8 @@ Exec Worktree Guide
31
31
 
32
32
  `exec run --worktree` と `exec run --auto` は、worktree 準備、agent 起動、commit、merge、状態更新を一括で行います。各段階を人が確認しながら進める場合は `exec worktree` 配下の分割コマンドを使います。
33
33
 
34
+ worktree の checkpoint・commit・merge などで実行する Git コマンドが `fatal: detected dubious ownership` で失敗した場合、共通の Git 実行層は 2 秒、5 秒、10 秒と間隔を広げながら最大 3 回まで待って同じコマンドを再試行し、待ち時間・回数・理由を警告ログへ記録します。作業ディレクトリに `.git` があるにもかかわらず `Not a git repository` で失敗した場合も、一時的な ownership 判定の失敗として同じ間隔と上限を共有します。これらの失敗は所有者が一致していても一時的に起き、すぐの再試行では収まらないことがあるためです。作業ディレクトリに `.git` がない場合や、3 回とも失敗した場合は従来どおり失敗として報告し、それ以外の Git エラーをこの条件では再試行しません。
35
+
34
36
  | コマンド | 責務 | Git変更 | イベント変更 |
35
37
  | ------------------ | -------------------------------------------------------------------------------- | --------- | ------------ |
36
38
  | `worktree prepare` | task worktree を準備し、実行管理ファイルを exec branch へ checkpoint commit する | あり | なし |
@@ -89,6 +91,21 @@ specdojo exec complete \
89
91
 
90
92
  project が解決できる場合、branch 名は project ID を含めます。例として `prj-0001:T-LAUNCH-prj-scope-010` は `exec/prj-0001-T-LAUNCH-prj-scope-010` になります。
91
93
 
94
+ ### 1.4. プロダクトリポジトリを宣言した project
95
+
96
+ `specdojo.config.json` の project に `repos` を宣言すると、分割コマンドはタスクの全リポジトリの worktree を扱います。宣言しない project の動作は前節までと同じです。
97
+
98
+ | コマンド | `repos` を宣言した project での動作 |
99
+ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
100
+ | `worktree prepare` | `<worktree_base>/<task-id>/project/` と、宣言したリポジトリごとの `<worktree_base>/<task-id>/<name>/` を作り、すべての path を表示する |
101
+ | `worktree status` | プロダクト worktree の path・branch・未 commit 変更(`<name>:<path>`)と、欠けている worktree を表示する |
102
+ | `worktree agent` | `SPECDOJO_REPO_<NAME>` と provider の追加ディレクトリを付けて agent を起動し、全 worktree で保護設定と Git 状態を検査する |
103
+ | `worktree commit` | プロダクト側を commit・統合しない。プロダクト worktree に変更が残る場合は、プロジェクト側も commit せずに停止する |
104
+ | `worktree remove` | 全リポジトリの worktree が撤去できることを確かめてから、まとめて撤去する |
105
+ | `worktree prune` | プロダクトリポジトリに残った孤立した exec ブランチも対象にする |
106
+
107
+ プロダクト側を含む commit と統合は `exec run --worktree`(register 項目は `exec run --register ... --worktree`)だけが行います。統合の順序、失敗時の部分状態、再開の扱いは [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] の「複数リポジトリの worktree と統合順序」と「複数リポジトリの統合の失敗と再開」を参照してください。
108
+
92
109
  ## 2. 分割コマンドの詳細
93
110
 
94
111
  各分割コマンドの役割、入出力、安全条件を示します。
@@ -109,13 +126,13 @@ specdojo exec worktree prepare \
109
126
  2. プロジェクトロックを取得します。
110
127
  3. plan、result、claim event を確認します。
111
128
  4. plan がなければ `exec plan` 相当で生成します。
112
- 5. root index に stage 済み変更がないことを確認します。
129
+ 5. root index の stage 済み変更が checkpoint 対象と重複しないことを確認します。
113
130
  6. 現在の統合先 HEAD から exec branch と worktree を作成します。
114
131
  7. root と、tracked `package-lock.json` を持つ独立 package で `npm ci` を実行します。
115
132
  8. worktree 内で `specdojo build` を実行し、生成物を用意します。
116
133
  9. plan、result、claim event を worktree へ複製し、exec branch へ checkpoint commit します。
117
134
 
118
- root にある無関係な未commit変更は checkpoint commit に含めません。ただし、stage 済み変更がある場合は停止します。checkpoint は exec branch だけに置かれるため、統合先の first-parent に `prepare execution` commit は増えません。root 側の plan、result、claim event は未commitのまま残り、task が `doing` であることは統合先からも見えます。これらの root 側の複製は `worktree merge` が統合の直前に解放し(HEAD の状態へ戻し)、merge が exec branch の commit 済み内容を持ち込みます。merge が失敗した場合は複製を元に戻します。
135
+ root にある無関係な未commit変更は checkpoint commit に含めません。stage 済み変更はパスを警告へ表示して保持し、plan、result、claim event などの checkpoint 対象と重複する場合だけ停止します。checkpoint commit が hook などで失敗した場合は、checkpoint 対象だけを unstage し、無関係な stage 済み変更は変更しません。checkpoint は exec branch だけに置かれるため、統合先の first-parent に `prepare execution` commit は増えません。root 側の plan、result、claim event は未commitのまま残り、task が `doing` であることは統合先からも見えます。これらの root 側の複製は `worktree merge` が統合の直前に解放し(HEAD の状態へ戻し)、merge が exec branch の commit 済み内容を持ち込みます。merge が失敗した場合は複製を元に戻します。
119
136
 
120
137
  作成または再利用した task worktree では、tracked `package-lock.json` ごとに `npm ci --include=dev` を実行し、root と独立 package の `node_modules` を worktree 内へ実体として配置します。依存関係を元 worktree と共有しないため、agent の sandbox は task worktree 内だけへの書き込みで build、typecheck、依存更新を実行できます。
121
138
 
@@ -183,17 +200,20 @@ specdojo exec worktree commit \
183
200
 
184
201
  commit 対象から除外する主なパス:
185
202
 
186
- | 除外対象 | 理由 |
187
- | -------------------------------- | -------------------------------------------- |
188
- | `exec/plans/` | plan は実行入力であり agent の成果物ではない |
189
- | 対象 task 以外の `exec/results/` | 他タスクの記録を混ぜない |
190
- | `exec/events/` | event は root 側の状態管理で扱う |
191
- | `generated/` | 再生成物を task 成果物に混ぜない |
203
+ | 除外対象 | 理由 |
204
+ | -------------------------------- | ---------------------------------------------- |
205
+ | `tmp/` | agent の作業用一時ファイルは commit に含めない |
206
+ | `exec/plans/` | plan は実行入力であり agent の成果物ではない |
207
+ | 対象 task 以外の `exec/results/` | 他タスクの記録を混ぜない |
208
+ | `exec/events/` | event は root 側の状態管理で扱う |
209
+ | `generated/` | 再生成物を task 成果物に混ぜない |
192
210
 
193
211
  対象 task の result は成果物変更と同じ commit に含めます。変更がない場合は commit を作成しません。
194
212
 
195
213
  上表の除外に加え、プロンプトインジェクション対策として commit 対象を mode 別の許可リストで絞ります。review は対象 task の result のみ、edit は result と plan の `targets` から解決した成果物(maintenance / bootstrap 系 approach は実践の型ディレクトリも)だけを commit し、許可リスト外の変更は `commit-scope:` 警告を出して worktree に残します。詳細は [exec設定ガイド](exec-config-guide.md) の `agent 権限とプロンプトインジェクション対策` を参照します。
196
214
 
215
+ 登録簿由来(`origin: register`)のタスクは許可リストを使わず、上表の除外だけを適用して作業ツリーの差分を commit します。HEAD に無い新規ファイルは、リポジトリ最上位、既知の成果物ディレクトリ(`docs/`、`src/`、`tests/`、`tools/`、`scripts/`、`packages/`)、HEAD で追跡済みの最上位ディレクトリ、対象 task の result と evidence、plan の `targets` から解決した成果物に置かれたものを commit します。`tmp/` 配下のファイルは常に commit 対象から除外します。それ以外の未追跡ディレクトリに置かれた新規ファイルは `commit-scope:` 警告を出して worktree に残し、pipeline 実行では run の `integrate.log` にも記録します。最上位に追加した新規ファイルを commit した場合は、統合ログと result の申し送りに「最上位に追加したファイル」として列挙します。既存ファイルの変更と削除、人間の作業(`execution: human`)は従来どおり commit します。`ready` への昇格検査は commit 対象のパスだけに適用するため、commit しない一時ファイルは統合を止めません。
216
+
197
217
  ### 2.5. merge
198
218
 
199
219
  `merge` は exec branch の commit を、コマンドを実行した現在ブランチへ統合します。
@@ -217,11 +237,20 @@ specdojo exec worktree merge \
217
237
 
218
238
  通常は `git merge --no-ff` 相当で統合します。自動実行では `exec(<task-id>): <task name>` を merge commit の subject に使い、統合先の first-parent を1タスク1commitにします(`prepare execution` / `apply task changes` は exec branch 側に残ります)。`--ff-only` 指定時は fast-forward 可能な場合だけ統合します。
219
239
 
220
- 競合または commit hook の失敗で merge commit を作れなかった場合は、runner が `git merge --abort` を実行して統合先を開始前の状態へ戻します。Schedule タスクは `blocked`、register 項目は `waiting` へ遷移し、再開に使う exec branch と worktree は保持します。register の `wait` commit は abort 後に作るため、統合先へ `MERGE_HEAD` を残したまま部分 commit を試みません。block reason には hook の罫線や色を除いた失敗ステップ名と最初のエラー行を記録し、executor/reporter pipeline では生の stdout / stderr と abort 結果を同じ run の `integrate.log` に保存します。
240
+ register 項目の統合で競合したのが項目自身の記帳ファイル(個票・イベント・plan・result)だけの場合は、記帳ファイルを次のように解決して merge commit を作ります。`waiting` を複数回経た項目では、wait 時の同期 merge の後も統合先と exec branch の双方で記帳ファイルが変わるためです。解決後の commit は通常の `git merge` と同じく pre-commit hook を実行しません。
241
+
242
+ - イベント(`events/pjr-<id>.yaml`)は、両側のイベントの和集合で解決します。同じ id のイベントは 1 件にまとめ、時刻順に並べて `previous_event_id` の連鎖を張り直します。`waiting` の間に統合先で追記されたイベント(`register update` など)も統合後に残ります。
243
+ - 統合先だけにある状態を変えないイベントは、並べ替え後の直前の状態を引き継ぎます。統合先だけに状態遷移があるなど、和集合で状態の連続性を保てない場合は、従来どおり exec branch 側で解決し、統合ログにその旨を出力します。
244
+ - 個票は exec branch 側を基準にし、統合先だけにあるイベントが変えた `type` / `priority` / `owner` / `due` をイベントから再構築します。同じフィールドを後から exec branch 側のイベントが変えている場合は、exec branch 側を残します。タイトル・説明(本文)、状態遷移に伴うフィールド、登録日時はイベントから元の値を復元できないため再構築しません。
245
+ - plan・result・登録簿(`pjr-index.md`)は exec branch 側(再開後の最新の記帳)の内容で解決します。
246
+
247
+ 上記以外の競合または commit hook の失敗で merge commit を作れなかった場合は、runner が `git merge --abort` を実行して統合先を開始前の状態へ戻します。Schedule タスクは `blocked`、register 項目は `waiting` へ遷移し、再開に使う exec branch と worktree は保持します。register の `wait` commit は abort 後に作るため、統合先へ `MERGE_HEAD` を残したまま部分 commit を試みません。block reason には hook の罫線や色を除いた失敗ステップ名、最初のエラー行、Vitest の末尾にある `FAIL`・`Test Files`・`Tests` の集計行を記録します。executor/reporter pipeline では checkpoint と統合段の commit / merge が失敗したときの stdout / stderr 全文と abort 結果を秘匿処理し、同じ run の `integrate.log` に保存します。
248
+
249
+ register 項目を `waiting` へ遷移したあとは、`wait` commit と、その時点までに統合先へ入った変更を exec branch へ通常 merge します。root の `wait` commit に保存済みの個票・イベント・plan・result は、worktree に残る同内容の未 commit 変更を解放してから merge し、これらの記帳パスの競合だけを `wait` commit 側で解決します。それ以外の競合は自動解決せずに同期 merge を中断します。これにより、再開時の merge-base を進めながら、別項目が統合先へ追加した成果を exec branch 側の削除として扱わないようにします。
221
250
 
222
- hook や検査を直した後は、Schedule タスクでは `specdojo exec resume --project <project-id> --task <task-id>`、register 項目では元の `exec run --register ... --worktree --resume` を実行します。統合段から再開するため agent は再実行せず、保持した exec branch を merge します。
251
+ hook や検査を直した後は、Schedule タスクでは `specdojo exec resume --project <project-id> --task <task-id>`、register 項目では元の `exec run --register ... --worktree --resume` を実行します。統合段から再開するため agent は再実行せず、保持した exec branch を merge します。親検証の失敗を成果物側で修正する必要がある register 項目は `--resume-from executor` を併用します。保護対象の設定変更を人が統合先へ適用した場合も、通常の `--resume` が統合先を exec branch と worktree へ取り込んでから executor を再開するため、worktree で手動 merge しません。
223
252
 
224
- 自動の `git merge --abort` 自体が失敗した場合は、runner が標準エラーへ手動復旧を案内します。案内された root worktree で状態と失敗原因を確認し、ロックファイルや Git プロセスなどの原因を解消してから次を実行してください。abort が完了するまでは commit や統合再開を行いません。
253
+ runner は `git merge --abort` の前に `git update-index -q --refresh` を実行します。同じ作業ツリーで動く routine などがファイルの stat だけを変えた場合でも、`not uptodate` で abort が失敗しないようにするためです。自動の `git merge --abort` 自体が失敗した場合は、runner が標準エラーへ手動復旧を案内します。案内された root worktree で状態と失敗原因を確認し、ロックファイルや Git プロセスなどの原因を解消してから次を実行してください。abort が完了するまでは commit や統合再開を行いません。
225
254
 
226
255
  ```bash
227
256
  git status
@@ -22,11 +22,11 @@ SpecDojo で成果物を作成・更新・レビューするときに、rulebook
22
22
  **次に読む文書**
23
23
 
24
24
  - 整備状況に応じた進め方(`approach`)の選び方は [実践の進め方ガイド](ryu-guide.md) を参照してください。
25
- - 実践の型そのものの種別と役割は [実践体系構成ガイド](practice-system-composition-guide.md) を参照してください。
25
+ - 実践の型そのものの種別と役割は [型の構成ガイド](practice-system-composition-guide.md) を参照してください。
26
26
 
27
27
  ## 1. 実践の型の使い分け
28
28
 
29
- 実践の型は rulebook / recipe / sample / template の4種です。各種別の役割の正本は [実践体系構成ガイド](practice-system-composition-guide.md) とし、本章では成果物を書くときの使い方を示します。
29
+ 実践の型は rulebook / recipe / sample / template の4種です。各種別の役割の正本は [型の構成ガイド](practice-system-composition-guide.md) とし、本章では成果物を書くときの使い方を示します。
30
30
 
31
31
  | 種別 | 役割 | 確認できること |
32
32
  | -------- | ------------------------------ | -------------------------------------------------- |
@@ -79,11 +79,11 @@ template は、記述する部分を _TODO_ などのプレースホルダとし
79
79
  | 実践の型メンテナンス(`*-maintenance`)の進め方 | [実践の進め方ガイド](ryu-guide.md) |
80
80
  | review でどこまで実践の型に照らすか | [実践の進め方ガイド](ryu-guide.md) |
81
81
 
82
- 型そのものの種別と実践体系全体での位置づけは [実践体系構成ガイド](practice-system-composition-guide.md) を正本とします。
82
+ 型そのものの種別と型全体での位置づけは [型の構成ガイド](practice-system-composition-guide.md) を正本とします。
83
83
 
84
84
  ## 4. 関連ドキュメント
85
85
 
86
86
  - [実践の進め方ガイド](ryu-guide.md): `approach` の選び方・一覧、参照の共通原則、メンテナンス・review への適用
87
- - [実践体系構成ガイド](practice-system-composition-guide.md): 実践の型を含む実践体系の種別と役割
87
+ - [型の構成ガイド](practice-system-composition-guide.md): 実践の型を含む型(Kata)の種別と役割
88
88
  - [プロジェクト概要 作成レシピ](../recipes/prj-overview-recipe.md): rulebook / recipe / sample の役割分担の記述例
89
89
  - [レビューガイド](review-guide.md): レビューの進め方と、実践の型の活用方法
@@ -80,6 +80,27 @@ frontier モデルは Claude Code が `opus`、Codex が `gpt-5.6-sol` に対応
80
80
 
81
81
  worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree を使い、無ければ起動時に作成します。ブランチは `worktree/<name>`、配置は `../worktrees/<name>` です。既存 worktree のブランチが一致しない場合は agent を起動しません。Claude Code の `--worktree` はブランチ名と配置を他の CLI に揃えられないため使用しません。
82
82
 
83
+ ### 2.1. 利用リポジトリへ設定を配置する
84
+
85
+ npm package から利用する場合は、起動前に provider の設定と npm script を利用リポジトリへ配置します。
86
+
87
+ ```bash
88
+ npx specdojo config scaffold --provider <name>
89
+ ```
90
+
91
+ scaffold が追加する `orch:*` は `specdojo orchestrator launch` を経由します。起動時に対象 project の `repos` を解決し、宣言済みのプロダクトリポジトリ本体だけを provider の追加ルートとして許可します。`repos` が無い場合の provider コマンドは従来どおりです。npm script に追加引数を渡す場合は `npm run orch:<name> -- <引数>` とし、その引数は provider CLI へそのまま渡されます。
92
+
93
+ OpenCode は起動引数に追加ルートの指定を持たないため、選択した orchestrator agent の `permission.external_directory` を実行時の inline config で上書きします。全外部ディレクトリを拒否してから宣言済みルートだけを許可し、同じルートの `permission.edit` も許可します。設定ファイル自体は変更しません。
94
+
95
+ Antigravity CLI の無人実行に必要な permission rule は、利用者のすべてのリポジトリに効くグローバル設定です。通常の scaffold では変更されないため、明示的に dry-run で追加 rule を確認してから適用します。既存設定は保持され、実適用前にバックアップされます。
96
+
97
+ ```bash
98
+ npx specdojo config scaffold --provider antigravity --global --dry-run
99
+ npx specdojo config scaffold --provider antigravity --global
100
+ ```
101
+
102
+ 分離環境が必要な場合は、追加の任意手順として `devcontainer scaffold` を利用できます。既存の `.devcontainer/` は上書きされず、provider の設定ディレクトリは名前付きボリュームへ保存されます。詳細は [CLIコマンドリファレンス](../references/command-reference.md) の `devcontainer` を参照してください。
103
+
83
104
  ## 3. 対話の進め方
84
105
 
85
106
  オーケストレーターは「提案 → 承認 → 実行」を基本とします。
@@ -107,7 +128,7 @@ worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通
107
128
 
108
129
  ## 5. 設定ファイルの構成
109
130
 
110
- 指示本文(システムプロンプト)の正本を1ファイルに集約し、各 agent CLI の設定はその本文を埋め込む薄いラッパーとしています。4系統の設定形式は非互換のため、単一のネイティブ設定ファイルを共有することはできません。
131
+ 指示本文(システムプロンプト)の正本を1ファイルに集約し、各 agent CLI の設定はその本文を埋め込む薄いラッパーとしています。4系統の設定形式は非互換のため、単一のネイティブ設定ファイルを共有することはできません。リポジトリ内で使うラッパーに加え、`config scaffold` で利用者へ配る provider テンプレートも同じ本文から生成します。
111
132
 
112
133
  | 役割 | パス |
113
134
  | ------------------ | ------------------------------------------ |
@@ -121,7 +142,7 @@ worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通
121
142
  本文を変更する場合は、次の手順で全環境を同期します。
122
143
 
123
144
  1. SSOT の `.agents/specdojo-orchestrator.agent.md` を編集します。
124
- 2. Markdown ラッパー4ファイルでは frontmatter より後を、Codex ラッパーでは `developer_instructions` の複数行文字列を、SSOT と同じ本文に更新します。
125
- 3. `npm run lint:orchestrator-sync` を実行し、5つのラッパーが SSOT とバイト単位で一致することを確認します。
145
+ 2. `npm run orchestrator:sync` を実行し、環境別ラッパーと配布テンプレートへ本文を生成します。
146
+ 3. `npm run lint:orchestrator-sync` を実行し、10個の同期対象が SSOT とバイト単位で一致することを確認します。
126
147
 
127
- この検証は対象ファイルの変更時に pre-commit hook からも自動実行され、不一致があれば commit を停止します。モデル・権限・provider の変更は本文ではなく、各ラッパーの frontmatter / TOML 側で行います。
148
+ 同期対象の一覧は `tools/validate-orchestrator-sync.mjs` を正本とします。pre-commit hook は対象ファイルの変更時に `npm run orchestrator:sync` を実行し、本文の反映漏れを自動で補います。モデル・権限・provider の変更は本文ではなく、各ラッパーの frontmatter / TOML 側で行います。
@@ -172,7 +172,7 @@ runner は一意名の新しい result を scaffold するとき、同じ `task_
172
172
 
173
173
  `exec status` が表示・集計する Schedule の `doing` / `blocked` などは event log から導出するタスク状態であり、result の status とは別です。このため、履歴上の `superseded` result が実行中件数や対応待ちの blocked 件数へ加算されることはありません。
174
174
 
175
- review の result には、scaffold 時に catalog から観点別セクション(RVP)を焼き込みます。同様に `finalize` / `bootstrap-finalize` の result には、done_criteria の確認チェックリスト(roles / viewpoint 注記付き)と確定対象(`status` を `ready` へ昇格する対象)のチェックリストを焼き込みます。human result は `execution: human` と `targets` を持ち、`plan_ref` を持ちません。確定手順・確認対象・確認記録・確定判断を result 側へ一元化し、恒久記録として残します。
175
+ review plan には、catalog の `done_criteria` と review 前段で得た grade の評価結果を焼き込みます。review result は観点を再評価する欄を持たず、`評価結果の確認`、`判断根拠`、`未充足事項・改善指示`、`approach` に応じた確認、6値の `verdict` を記録します。`finalize` / `bootstrap-finalize` の result には、`done_criteria` の確認チェックリスト(roles / viewpoint 注記付き)と確定対象(`status` を `ready` へ昇格する対象)のチェックリストを焼き込みます。human result は `execution: human` と `targets` を持ち、`plan_ref` を持ちません。確定手順・確認対象・確認記録・確定判断を result 側へ一元化し、恒久記録として残します。
176
176
 
177
177
  既に result が存在する場合は上書きせず、既存ファイルを使います。エージェントや人は result に実行内容、検証結果、残課題を記録します。
178
178
 
@@ -8,32 +8,32 @@ specdojo:
8
8
  - specdojo:docs-structure-guide
9
9
  ---
10
10
 
11
- # 実践体系構成ガイド
11
+ # 型の構成ガイド
12
12
 
13
- Practice System Composition Guide
13
+ Kata Composition Guide
14
14
 
15
- SpecDojo の実践体系(成果物の作成を支援する文書群)が、どの種別で構成され、各種別がどんな役割を持ち、成果物とどう結びつくかを示します。実践体系の全体像を記述する正本です。
15
+ SpecDojo の型(Kata、成果物の作成を支援する文書群)が、どの種別で構成され、各種別がどんな役割を持ち、成果物とどう結びつくかを示します。型の全体像を記述する正本です。
16
16
 
17
17
  **対象読者**
18
18
 
19
- - 実践体系の全体像を把握したい利用者、支援文書を設計・保守する作成者、エージェント
19
+ - 型の全体像を把握したい利用者、支援文書を設計・保守する作成者、エージェント
20
20
 
21
21
  **この文書で分かること**
22
22
 
23
- - 実践体系を構成する8種別の役割、種別間の関係、成果物への紐付け(解決の仕組み)
23
+ - 型を構成する8種別の役割、種別間の関係、成果物への紐付け(解決の仕組み)
24
24
 
25
25
  **次に読む文書**
26
26
 
27
27
  - `approach` に応じた rulebook / recipe / sample / template の参照方法は [実践の進め方ガイド](ryu-guide.md) を参照してください。
28
28
  - 文書の分類・ライフサイクル・配置は [ドキュメント構成ガイド](docs-structure-guide.md) を参照してください。
29
29
 
30
- ## 1. 実践体系とは
30
+ ## 1. 型とは
31
31
 
32
- SpecDojo は、成果物(プロダクトとプロジェクトの内容そのもの)と、その作成を支援する文書群を分けて管理します。後者を実践体系と呼びます。
32
+ SpecDojo は、成果物(プロダクトとプロジェクトの内容そのもの)と、その作成を支援する文書群を分けて管理します。後者を型(Kata)と呼びます。
33
33
 
34
- 実践体系は成果物を再掲するものではなく、成果物を「なぜ・何を・どう書くか」を支える別の役割を担います。本書は実践体系の構成の正本であり、[全体概要ガイド](specdojo-overview-guide.md) の `実践体系の役割` は本書の概要にあたります。
34
+ 型は成果物を再掲するものではなく、成果物を「なぜ・何を・どう書くか」を支える別の役割を担います。本書は型の構成の正本であり、[全体概要ガイド](specdojo-overview-guide.md) の `型の役割` は本書の概要にあたります。
35
35
 
36
- npm package が所有する実践体系文書は、package ごとの authority を ID に付けます。SpecDojo core は `specdojo:`、業界固有の variant package は `construction-dojo:` などを使用します。authority は論理IDにだけ含め、ファイル名には含めません。利用プロジェクトへコピーした標準文書を override する場合は同じ完全IDを維持し、独自文書を追加する場合は別IDを付けます。
36
+ npm package が所有する型の文書は、package ごとの authority を ID に付けます。SpecDojo core は `specdojo:`、業界固有の variant package は `construction-dojo:` などを使用します。authority は論理IDにだけ含め、ファイル名には含めません。利用プロジェクトへコピーした標準文書を override する場合は同じ完全IDを維持し、独自文書を追加する場合は別IDを付けます。
37
37
 
38
38
  ### 1.1. npm package からの参照と eject
39
39
 
@@ -45,7 +45,7 @@ package の探索では `node_modules` 全体を再帰走査せず、resolver
45
45
 
46
46
  ## 2. 種別と役割
47
47
 
48
- 実践体系は次の8種類の文書で構成されます。各種別は同じ内容を再掲するのではなく、それぞれ異なる問いに答えます。
48
+ 型は次の8種類の文書で構成されます。各種別は同じ内容を再掲するのではなく、それぞれ異なる問いに答えます。
49
49
 
50
50
  | 種別 | 答える問い | 使い方 |
51
51
  | ---------- | ---------------------------------------- | ---------------------------------------------- |
@@ -85,7 +85,7 @@ flowchart TB
85
85
  RB -->|frontmatterで宣言| TPL
86
86
  ```
87
87
 
88
- | 実践体系 | 成果物との紐付け方 | 例 |
88
+ | 型の種別 | 成果物との紐付け方 | 例 |
89
89
  | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
90
90
  | philosophy | standard / rulebook が前提とする方針・概念。個別成果物への直接の紐付けはない | specdojo:needs-to-implementation-philosophy |
91
91
  | standard | 全成果物・全 rulebook が共通して従う規約。個別成果物への直接の紐付けはない | specdojo:document-metadata-standard |
@@ -99,13 +99,13 @@ flowchart TB
99
99
 
100
100
  ## 4. 実践の型サブセットと活用
101
101
 
102
- exec plan が実行時に参照するのは、実践体系のうち rulebook / recipe / sample / template の4種(実践の型)です。これらをどこまで参照するか(`approach` に応じた参照方針)は [実践の進め方ガイド](ryu-guide.md) を正本とします。
102
+ exec plan が実行時に参照するのは、型のうち rulebook / recipe / sample / template の4種(実践の型)です。これらをどこまで参照するか(`approach` に応じた参照方針)は [実践の進め方ガイド](ryu-guide.md) を正本とします。
103
103
 
104
104
  philosophy / standard は全体に効く前提・共通規約として常に踏まえ、guide / reference は個別成果物に紐づかない横断文書として理解と参照に使います。
105
105
 
106
106
  ## 5. 関連ドキュメント
107
107
 
108
- - [全体概要ガイド](specdojo-overview-guide.md): 実践体系を含む SpecDojo 全体像
108
+ - [全体概要ガイド](specdojo-overview-guide.md): 成果物・型・技を含む SpecDojo 全体像
109
109
  - [実践の進め方ガイド](ryu-guide.md): `approach` に応じた実践の型の参照方法
110
110
  - [ドキュメント構成ガイド](docs-structure-guide.md): 文書の分類、命名、ディレクトリ配置
111
111
  - [ドキュメントメタ情報標準](../standards/document-metadata-standard.md): 各種別の Frontmatter 規約