specdojo 0.3.0 → 0.4.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 (245) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +77 -18
  3. package/dist/catalog/build-references.js +144 -0
  4. package/dist/catalog/build-render.js +32 -0
  5. package/dist/{catalog-build.js → catalog/build.js} +18 -295
  6. package/dist/{catalog.js → catalog/catalog.js} +11 -11
  7. package/dist/{catalog-generate.js → catalog/generate.js} +13 -16
  8. package/dist/catalog/paths.js +1 -0
  9. package/dist/{catalog-plan-generate.js → catalog/plan-generate.js} +5 -5
  10. package/dist/{catalog-plan.js → catalog/plan.js} +9 -9
  11. package/dist/{catalog-scaffold.js → catalog/scaffold.js} +6 -6
  12. package/dist/{agent.js → commands/agent.js} +11 -11
  13. package/dist/{build-command.js → commands/build.js} +2 -2
  14. package/dist/{init-command.js → commands/init.js} +103 -37
  15. package/dist/{orchestrator.js → commands/orchestrator.js} +2 -2
  16. package/dist/{watch.js → commands/watch.js} +3 -3
  17. package/dist/dashboard/dashboard-timeline.js +175 -0
  18. package/dist/{dashboard.js → dashboard/dashboard.js} +16 -549
  19. package/dist/dashboard/exec-records.js +105 -0
  20. package/dist/dashboard/routines.js +256 -0
  21. package/dist/dashboard/shared.js +14 -0
  22. package/dist/{timeline-build.js → dashboard/timeline-build.js} +2 -1
  23. package/dist/{timeline.js → dashboard/timeline.js} +1 -1
  24. package/dist/{deliverable.js → deliverable/deliverable.js} +5 -5
  25. package/dist/{deliverable-trash.js → deliverable/trash.js} +7 -7
  26. package/dist/{devcontainer-command.js → devcontainer/command.js} +5 -3
  27. package/dist/{devcontainer-scaffold.js → devcontainer/scaffold.js} +94 -2
  28. package/dist/{doc-index.js → docs/doc-index.js} +3 -3
  29. package/dist/{frontmatter-namespace.js → docs/frontmatter-namespace.js} +2 -2
  30. package/dist/{index-command.js → docs/index-command.js} +1 -1
  31. package/dist/docs/template-resolution.js +1 -0
  32. package/dist/{viewpoint-document-kinds-check.js → docs/viewpoint-document-kinds-check.js} +3 -3
  33. package/dist/{yaml-pages-command.js → docs/yaml-pages-command.js} +1 -1
  34. package/dist/{yaml-pages.js → docs/yaml-pages.js} +5 -5
  35. package/dist/{exec-agent-config.js → exec/agent-config.js} +33 -4
  36. package/dist/{exec-agent-git-state.js → exec/agent-git-state.js} +1 -1
  37. package/dist/{exec-agent-protected-config.js → exec/agent-protected-config.js} +1 -1
  38. package/dist/{exec.js → exec/commands.js} +22 -467
  39. package/dist/exec/core.js +457 -0
  40. package/dist/{exec-events.js → exec/events.js} +2 -2
  41. package/dist/{exec-evidence.js → exec/evidence.js} +11 -6
  42. package/dist/exec/exec.js +2 -0
  43. package/dist/exec/format.js +1 -0
  44. package/dist/{exec-handoff.js → exec/handoff.js} +13 -12
  45. package/dist/{exec-limit.js → exec/limit.js} +93 -12
  46. package/dist/{exec-parent-validation.js → exec/parent-validation.js} +4 -4
  47. package/dist/{exec-pipeline-state.js → exec/pipeline-state.js} +16 -2
  48. package/dist/{exec-plans.js → exec/plans-core.js} +97 -468
  49. package/dist/exec/plans-generation.js +249 -0
  50. package/dist/exec/plans-storage.js +131 -0
  51. package/dist/exec/plans.js +3 -0
  52. package/dist/{exec-project.js → exec/project.js} +1 -1
  53. package/dist/{exec-protection-handoff.js → exec/protection-handoff.js} +3 -3
  54. package/dist/{exec-register-resume.js → exec/register-resume.js} +2 -2
  55. package/dist/{exec-register.js → exec/register.js} +92 -9
  56. package/dist/exec/repo-integration-git.js +23 -0
  57. package/dist/exec/repo-integration-sync.js +264 -0
  58. package/dist/{exec-repo-integration.js → exec/repo-integration.js} +13 -287
  59. package/dist/{exec-repo-trace.js → exec/repo-trace.js} +3 -3
  60. package/dist/exec/reporter-output.js +206 -0
  61. package/dist/{exec-reporter.js → exec/reporter.js} +29 -216
  62. package/dist/{exec-results.js → exec/results.js} +277 -36
  63. package/dist/exec/run/agent-pipeline.js +276 -0
  64. package/dist/exec/run/agent.js +583 -0
  65. package/dist/exec/run/in-place.js +570 -0
  66. package/dist/exec/run/job.js +746 -0
  67. package/dist/exec/run/lifecycle-commands.js +530 -0
  68. package/dist/{exec-run-lock.js → exec/run/lock.js} +4 -3
  69. package/dist/exec/run/mode-shared.js +140 -0
  70. package/dist/exec/run/register-command.js +252 -0
  71. package/dist/exec/run/register-core.js +411 -0
  72. package/dist/exec/run/register-mode.js +210 -0
  73. package/dist/exec/run/register-resume.js +398 -0
  74. package/dist/exec/run/register-state.js +325 -0
  75. package/dist/exec/run/register-worktree.js +540 -0
  76. package/dist/exec/run/run.js +11 -0
  77. package/dist/exec/run/schedule-mode.js +294 -0
  78. package/dist/exec/run/schedule-prepare.js +366 -0
  79. package/dist/exec/run/schedule-task.js +599 -0
  80. package/dist/exec/run/shared.js +449 -0
  81. package/dist/{exec-schedule-calendar.js → exec/schedule/calendar.js} +1 -1
  82. package/dist/{exec-schedule-cpm.js → exec/schedule/cpm.js} +2 -2
  83. package/dist/{exec-schedule-gantt-chart-render.js → exec/schedule/gantt-chart-render.js} +2 -2
  84. package/dist/exec/schedule/gantt-chart.js +2 -0
  85. package/dist/{exec-schedule-hash.js → exec/schedule/hash.js} +2 -2
  86. package/dist/exec/schedule/index.js +1 -0
  87. package/dist/{exec-schedule-initial.js → exec/schedule/initial.js} +2 -2
  88. package/dist/{exec-schedule-progress.js → exec/schedule/progress.js} +2 -2
  89. package/dist/{exec-schedule-ready.js → exec/schedule/ready.js} +2 -2
  90. package/dist/{exec-schedule.js → exec/schedule/schedule.js} +11 -11
  91. package/dist/exec/shared.js +63 -0
  92. package/dist/exec/slot-lock.js +1 -0
  93. package/dist/{exec-strategy.js → exec/strategy.js} +2 -2
  94. package/dist/{exec-task-repos.js → exec/task-repos.js} +2 -2
  95. package/dist/{exec-task-view.js → exec/task-view.js} +4 -4
  96. package/dist/{exec-trial.js → exec/trial-commands.js} +23 -388
  97. package/dist/exec/trial-core.js +371 -0
  98. package/dist/exec/trial.js +2 -0
  99. package/dist/{exec-worktree-command.js → exec/worktree-command.js} +25 -23
  100. package/dist/exec/worktree-ops-commit.js +672 -0
  101. package/dist/exec/worktree-ops-lifecycle.js +297 -0
  102. package/dist/exec/worktree-ops-merge.js +344 -0
  103. package/dist/exec/worktree-ops.js +3 -0
  104. package/dist/exec/worktree.js +305 -0
  105. package/dist/grade/apply.js +734 -0
  106. package/dist/grade/command-apply.js +250 -0
  107. package/dist/grade/command-inspect.js +138 -0
  108. package/dist/grade/command-plan.js +101 -0
  109. package/dist/grade/command-shared.js +68 -0
  110. package/dist/grade/core.js +307 -0
  111. package/dist/grade/grade.js +19 -0
  112. package/dist/grade/markdown.js +274 -0
  113. package/dist/grade/pipeline-state.js +184 -0
  114. package/dist/grade/plan.js +507 -0
  115. package/dist/{grade-result.js → grade/result.js} +7 -96
  116. package/dist/grade/target-discovery.js +265 -0
  117. package/dist/grade/targets.js +435 -0
  118. package/dist/{job.js → job/definition.js} +32 -574
  119. package/dist/job/job.js +568 -0
  120. package/dist/{kata-command.js → kata/command.js} +4 -4
  121. package/dist/{kata.js → kata/kata.js} +5 -5
  122. package/dist/register/approach.js +134 -0
  123. package/dist/register/command-types.js +1 -0
  124. package/dist/register/core.js +369 -0
  125. package/dist/register/create-commands.js +352 -0
  126. package/dist/{register-date.js → register/date.js} +1 -1
  127. package/dist/register/derivation.js +163 -0
  128. package/dist/{register-event-merge.js → register/event-merge.js} +32 -3
  129. package/dist/{register-events.js → register/events.js} +12 -6
  130. package/dist/{register-history.js → register/history.js} +7 -6
  131. package/dist/{register-item.js → register/item.js} +28 -10
  132. package/dist/register/lifecycle-lock.js +5 -0
  133. package/dist/register/maintenance-commands.js +193 -0
  134. package/dist/{register-migrate-timestamps.js → register/migrate-timestamps.js} +3 -3
  135. package/dist/register/migration.js +268 -0
  136. package/dist/register/register.js +404 -0
  137. package/dist/register/renumber.js +341 -0
  138. package/dist/register/transition-commands.js +248 -0
  139. package/dist/register/update.js +230 -0
  140. package/dist/register/views.js +296 -0
  141. package/dist/{review-grade.js → review/grade.js} +2 -2
  142. package/dist/{review-plan.js → review/plan.js} +5 -5
  143. package/dist/routine/definition.js +401 -0
  144. package/dist/{routine.js → routine/routine.js} +50 -419
  145. package/dist/{schedule-approach.js → schedule/approach.js} +9 -9
  146. package/dist/{schedule-build.js → schedule/build.js} +7 -4
  147. package/dist/{schedule.js → schedule/schedule.js} +9 -9
  148. package/dist/schedule/strategy-generate-document.js +273 -0
  149. package/dist/schedule/strategy-generate-scope.js +199 -0
  150. package/dist/schedule/strategy-generate.js +348 -0
  151. package/dist/shared/agent-types.js +23 -0
  152. package/dist/shared/artifact-path.js +9 -0
  153. package/dist/{build-if-stale.js → shared/build-if-stale.js} +1 -1
  154. package/dist/shared/catalog-render.js +115 -0
  155. package/dist/{exec-slot-lock.js → shared/cross-process-lock.js} +3 -1
  156. package/dist/shared/fs.js +30 -0
  157. package/dist/shared/git.js +316 -0
  158. package/dist/shared/grade-result.js +94 -0
  159. package/dist/{package-paths.js → shared/package-paths.js} +3 -3
  160. package/dist/shared/plan-templates.js +114 -0
  161. package/dist/{exec-provider-scaffold.js → shared/provider-scaffold.js} +3 -1
  162. package/dist/shared/random.js +4 -0
  163. package/dist/{exec-schedule-index.js → shared/schedule-index.js} +3 -1
  164. package/dist/shared/schedule-paths.js +9 -0
  165. package/dist/{specdojo-config.js → shared/specdojo-config.js} +96 -9
  166. package/dist/{exec-shared.js → shared/text.js} +0 -134
  167. package/dist/shared/time.js +28 -0
  168. package/dist/shared/yaml.js +28 -0
  169. package/dist/specdojo.js +22 -22
  170. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +29 -17
  171. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +1 -2
  172. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -2
  173. package/docs/ja/specdojo/exec-templates/xer-template.md +1 -3
  174. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +6 -4
  175. package/docs/ja/specdojo/guides/exec-config-guide.md +97 -22
  176. package/docs/ja/specdojo/guides/exec-operation-guide.md +145 -12
  177. package/docs/ja/specdojo/guides/exec-worktree-guide.md +2 -0
  178. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +51 -18
  179. package/docs/ja/specdojo/guides/quick-start-guide.md +81 -16
  180. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -1
  181. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -1
  182. package/docs/ja/specdojo/guides/review-guide.md +1 -1
  183. package/docs/ja/specdojo/guides/routine-operation-guide.md +6 -6
  184. package/docs/ja/specdojo/guides/use-case-guide.md +1 -1
  185. package/docs/ja/specdojo/references/command-reference.md +52 -28
  186. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +17 -11
  187. package/docs/ja/specdojo/standards/job-definition-standard.md +20 -18
  188. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
  189. package/docs/ja/specdojo/templates/pjr-derived-items-template.md +22 -0
  190. package/docs/ja/specdojo/templates/pjr-index-template.md +1 -0
  191. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +29 -2
  192. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +20 -0
  193. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +23 -0
  194. package/docs/specdojo/schemas/v1/job-run.schema.yaml +2 -2
  195. package/docs/specdojo/schemas/v1/job.schema.yaml +7 -0
  196. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +26 -0
  197. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  198. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +70 -7
  199. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +1 -1
  200. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -1
  201. package/package.json +4 -5
  202. package/templates/antigravity/README.md +7 -3
  203. package/templates/antigravity/agent-members-snippet.yaml +108 -12
  204. package/templates/antigravity/exec-defaults-snippet.yaml +10 -13
  205. package/templates/claude/README.md +27 -3
  206. package/templates/claude/agents/claude-executor.md +0 -1
  207. package/templates/claude/agents/claude-reporter.md +2 -1
  208. package/templates/claude/agents/claude-review-executor.md +0 -1
  209. package/templates/codex/README.md +23 -4
  210. package/templates/devcontainer/devcontainer.json +2 -2
  211. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +69 -0
  212. package/templates/devcontainer/remote-host/ssh-config.sample +16 -0
  213. package/templates/init-agent-members.yaml +75 -25
  214. package/templates/init-exec-defaults.yaml +26 -8
  215. package/templates/opencode/README.md +17 -3
  216. package/templates/opencode/agents/opencode-executor.md +0 -1
  217. package/templates/opencode/agents/opencode-reporter.md +2 -1
  218. package/templates/opencode/agents/opencode-review-executor.md +0 -1
  219. package/dist/exec-run.js +0 -6182
  220. package/dist/exec-schedule-gantt-chart.js +0 -2
  221. package/dist/exec-worktree-ops.js +0 -1292
  222. package/dist/exec-worktree.js +0 -446
  223. package/dist/grade.js +0 -3193
  224. package/dist/register.js +0 -2407
  225. package/dist/schedule-strategy-generate.js +0 -812
  226. package/templates/claude/agents/claude-expert-review-executor.md +0 -14
  227. /package/dist/{catalog-plan-prompt.js → catalog/plan-prompt.js} +0 -0
  228. /package/dist/{catalog-types.js → catalog/types.js} +0 -0
  229. /package/dist/{template-frontmatter.js → docs/template-frontmatter.js} +0 -0
  230. /package/dist/{role-types.js → exec/role-types.js} +0 -0
  231. /package/dist/{exec-schedule-gantt-chart-scope.js → exec/schedule/gantt-chart-scope.js} +0 -0
  232. /package/dist/{exec-types.js → exec/types.js} +0 -0
  233. /package/dist/{review-types.js → review/types.js} +0 -0
  234. /package/dist/{schedule-phase-sets.js → schedule/phase-sets.js} +0 -0
  235. /package/dist/{schedule-strategy-profiles.js → schedule/strategy-profiles.js} +0 -0
  236. /package/dist/{agent-response.js → shared/agent-response.js} +0 -0
  237. /package/dist/{catalog-paths.js → shared/catalog-paths.js} +0 -0
  238. /package/dist/{dist-freshness.js → shared/dist-freshness.js} +0 -0
  239. /package/dist/{git-environment.js → shared/git-environment.js} +0 -0
  240. /package/dist/{exec-format.js → shared/markdown-format.js} +0 -0
  241. /package/dist/{practice-id.js → shared/practice-id.js} +0 -0
  242. /package/dist/{spawn-self.js → shared/spawn-self.js} +0 -0
  243. /package/dist/{specdojo-gitignore.js → shared/specdojo-gitignore.js} +0 -0
  244. /package/dist/{template-resolution.js → shared/template-resolution.js} +0 -0
  245. /package/dist/{yaml-schema-modeline.js → shared/yaml-schema-modeline.js} +0 -0
@@ -93,7 +93,7 @@ pipeline では `agent_pipeline.stages` を `executor`、`reporter` の順に定
93
93
 
94
94
  ## 3. エージェントの定義
95
95
 
96
- `.specdojo/agent-members.yaml` の member には `type: agent` と `provider`・`capabilities`・`proficiency`・`priority` を定義します。起動コマンドは通常 member には書かず、`.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` を member 属性(`{nickname}`・`{mode}`・`{proficiency}` と `command_params` の変数)で展開して解決します。member の `command` はテンプレートで表現できない特殊構成向けの上書きとしてのみ使います。
96
+ `.specdojo/agent-members.yaml` の member には `type: agent` と `provider`・`capabilities`・`proficiency`・`priority` を定義します。特定のモデルを表す実体には `model` と、provider が対応する場合は `effort` も定義できます。起動コマンドは通常 member には書かず、`.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` を member 属性(`{nickname}`・`{model}`・`{mode}`・`{proficiency}` と `command_params` の変数)で展開して解決します。member の `command` はテンプレートで表現できない特殊構成向けの上書きとしてのみ使います。
97
97
 
98
98
  ```yaml
99
99
  members:
@@ -118,6 +118,33 @@ members:
118
118
  priority: 10
119
119
  ```
120
120
 
121
+ モデルを持つ実体の `nickname` は、モデルの版を含めず、モデルの系統と役割で付けます(例: `opus-executor`・`sol-review-executor`)。版は `model` に記録します。同じモデル系統を既定でない provider から使う場合は、`agy-opus-executor` のように provider 名を前に付けます。従来名など実体を指す名前はトップレベルの `aliases` に置き、`alias_of` で実体または別の alias を指します。
122
+
123
+ ```yaml
124
+ members:
125
+ - nickname: sol-executor
126
+ display_name: Sol Executor
127
+ email: null
128
+ roles: []
129
+ type: agent
130
+ provider: codex
131
+ model: gpt-5.6-sol
132
+ effort: high
133
+ mode: edit
134
+ stage_role: executor
135
+ capabilities: [web_search]
136
+ proficiency: expert
137
+ priority: 10
138
+
139
+ aliases:
140
+ - nickname: codex-expert-executor
141
+ alias_of: sol-executor
142
+ ```
143
+
144
+ alias の連鎖は使用できますが、循環してはならず、終端は存在する有効な member でなければなりません。`loadMemberRoster` はこの整合性を読み込み時に検証します。`aliases` のない従来形式も引き続き有効です。
145
+
146
+ `--by`・`--executor-by`・`--reporter-by`・`--fallback-executor-by`・`--fallback-reporter-by` の指定、Schedule / Job / routine の `agent` には、実体名と alias のどちらも使用できます。alias は command を組み立てる前に実体へ解決され、`{nickname}` と `{model}` には実体の値が入ります。自動選択は初めから実体を候補にします。event・pipeline state・result の actor には、実際に動いた model を追跡できるよう実体名だけを記録します。指定された alias は actor の別フィールドには保存せず、対応関係は agent 名簿を正本とします。
147
+
121
148
  pipeline 専用 agent には `stage_role: executor` または `stage_role: reporter` を指定します。`stage_role` を省略した既存 agent は従来の単一 agent フロー専用です。自動選択では、従来タスクから stage role 付き agent を除外し、pipeline stage から stage role 未指定 agent と異なる stage role の agent を除外します。これにより既存 agent 定義を変更せず、新しい pipeline agent を追加できます。
122
149
 
123
150
  `exec run --auto` は phase または pipeline stage の `capabilities` をすべて持つ agent を候補にします。`proficiency` が指定されている場合は一致する agent のみを候補にし、未指定の場合は全水準を候補に含めます。候補のソートキーは次の順に評価します。
@@ -128,7 +155,7 @@ pipeline 専用 agent には `stage_role: executor` または `stage_role: repor
128
155
 
129
156
  ソート後、`exec-defaults.yaml` の `providers.<provider>.max_concurrency` が設定された provider について、現在実行中の agent が上限に達していれば、その provider の候補を除外します。別 provider の候補が残ればそれを実行者に繰り上げます。すべての候補の provider が上限に達している場合は、claim も worktree 生成も行わずにそのタスクを繰り延べます(タスクは `todo` のまま保持され、取りこぼしません)。`--loop` 実行では、agent 終了時に provider の枠を解放し、空いた `--parallel` 枠へ次の Ready タスクを投入します。`max_concurrency` はグローバルな `--parallel` を下げないため、他 provider は並列実行を維持します。auto 選択以外では、register の worktree モードで実行する executor/reporter pipeline(`--parallel` / `--resume` を含む)に適用し、項目ごとの各 stage を provider の空き枠まで待機させます。その他の Schedule phase の `agent`、`--by` / `--edit-by` / `--review-by` / `--executor-by` / `--reporter-by` による明示指定や Schedule task の resume 実行には適用しません。
130
157
 
131
- phase の by-name agent が rate limit になった場合は、別 agent へ自動フォールバックせず待機状態にします。`exec resume` は同じ agent を再開し、運用者が差し替える場合だけ stage override を指定します。
158
+ phase の by-name agent や `--executor-by` / `--reporter-by` で指名した agent の rate limit は、`--on-rate-limit stop|wait|fallback` で扱いを選べます。`stop`(既定)は従来どおり待機状態にし、`wait` は provider の reset / retry-after(無ければ `cooldown_seconds`)まで待って同じ段を同じ agent で1回再開します。待ち時間が `pinned.max_wait_seconds`(既定8時間)を超える、または再開時刻が得られない場合は停止します。`fallback` は `--fallback-executor-by` / `--fallback-reporter-by`(または後述の既定)で指定した agent へ1回だけ切り替え、未指定時や fallback も rate limit の場合は停止します。`exec resume` でも同じ指定が使えます。
132
159
 
133
160
  ## 4. 実行フロー
134
161
 
@@ -187,6 +214,11 @@ rate_limit_detection:
187
214
  rate_limit_policy:
188
215
  cooldown_seconds:
189
216
  rate_limit: 900
217
+ pinned:
218
+ action: stop # stop | wait | fallback。CLI の --on-rate-limit が優先
219
+ max_wait_seconds: 28800 # 既定も8時間
220
+ # fallback_executor_by: claude-expert-executor
221
+ # fallback_reporter_by: claude-reporter
190
222
  on_non_critical:
191
223
  action: skip
192
224
  on_critical:
@@ -199,6 +231,8 @@ rate_limit_policy:
199
231
  on_exhausted: block
200
232
  ```
201
233
 
234
+ `wait` の待機中は、同一 worktree と register / pipeline の状態を別 run から保護するため project の実行ロックを保持します。register worktree の `--join` 実行は共有枠の範囲で引き続き動作できます。wait / fallback の再開時刻と切替元・切替先は pipeline state と executor evidence に記録されます。
235
+
202
236
  `test-integration` は組み込み許可リストで `npm run test:integration` へ解決されます。設定や executor evidence に command・引数を書くことはできません。未知 ID、重複 ID は agent 起動前の設定エラーになります。親 runner は `shell: false` の固定 argv で実行し、現時点で許可される ID は `validate-schema`、`typecheck`、`test-unit`、`test-integration`、`lint-ts`、`lint-fm`、`lint-md` の 7 つです。
203
237
 
204
238
  `typecheck`(`npm run typecheck`)は Vitest と異なり型検査を行うため、executor が残した TypeScript の型エラーを検出します。Vitest は型検査を行わないため、`typecheck` を親検証に含めないと型エラーは test-unit を通過して統合時の pre-commit hook で初めて失敗するため、既定では `test-unit` の前に置いて早めに止めます(PJR-W66B)。
@@ -235,7 +269,7 @@ pipeline:
235
269
 
236
270
  provider ごとに挙動が異なる設定は `providers.<provider>` に置きます。各キーは対応するグローバル値を完全に置き換え、未指定のキーはグローバル値にフォールバックします。`<provider>` は `pm-members[].provider` に対応します。指定できるキーは次のとおりです。
237
271
 
238
- - `command_template`: その provider の agent を起動するコマンドテンプレート。`{nickname}`・`{mode}`・`{proficiency}` と `command_params` の変数を member 属性で展開します。グローバル既定は持ちません。
272
+ - `command_template`: その provider の agent を起動するコマンドテンプレート。`{nickname}`・`{model}`・`{mode}`・`{proficiency}` と `command_params` の変数を member 属性で展開します。`model` のない従来 member は、これまでどおり `command_params` の `model` を使用できます。グローバル既定は持ちません。
239
273
  - `command_params`: テンプレートの追加変数表。`by_mode.<mode>`、`by_proficiency.<proficiency>`、`by_nickname.<nickname>` に変数名と値の組を置きます。同じ変数は `by_nickname`、`by_proficiency`、`by_mode` の順で優先します。
240
274
  - `rate_limit_detection`: provider 固有の検出シグナル(`stderr_patterns` を優先します)。
241
275
  - `rate_limit_policy`: provider 固有のリトライ/フォールバック/block ポリシー。
@@ -247,27 +281,35 @@ provider ごとに挙動が異なる設定は `providers.<provider>` に置き
247
281
  ```yaml
248
282
  providers:
249
283
  claude:
250
- command_template: "claude -p --verbose --agent {nickname} --settings .specdojo/claude/settings.{mode}.json"
284
+ command_template: "claude -p --verbose --agent {agent} --model {model} --settings .specdojo/claude/settings.{mode}.json"
285
+ command_params:
286
+ by_mode:
287
+ edit: { agent: claude-executor }
288
+ review: { agent: claude-review-executor }
289
+ report: { agent: claude-reporter }
251
290
 
252
291
  codex:
253
292
  command_template: 'codex exec --ephemeral --sandbox workspace-write -c approval_policy="never" -c sandbox_workspace_write.network_access=false --model {model} -c model_reasoning_effort="{effort}"'
254
293
  command_params:
255
- by_proficiency:
256
- normal: { model: gpt-5.4-mini, effort: medium }
257
- expert: { model: gpt-5.5, effort: high }
294
+ by_proficiency: # model は実体の member の model を使い、effort だけを切り替える
295
+ normal: { effort: medium }
296
+ expert: { effort: high }
258
297
 
259
298
  antigravity:
260
299
  command_template: 'agy --sandbox --add-dir "$(pwd)" --model {model} -p "$(cat)"'
300
+ # model を持たない従来の 1 段の member だけが、次の model を使う
261
301
  command_params:
262
302
  by_proficiency:
263
303
  normal: { model: gemini-3.8-flash-medium }
264
- expert: { model: gemini-3.1-pro-high }
304
+ expert: { model: gemini-3.8-flash-high }
265
305
  by_nickname:
266
- agy-claude-expert-executor: { model: claude-opus-4-6-thinking }
306
+ agy-claude-expert-executor: { model: claude-opus-5-5-high }
267
307
  ```
268
308
 
269
309
  `by_nickname` は、同じ provider の一部 member だけモデルなどを差し替える用途です。層をまたぐ同名変数は意図的な上書きとして許可されます。一方、`nickname`、`mode`、`proficiency` は組み込み変数なので、どの `command_params` 層でも再定義できません。
270
310
 
311
+ Claude Code と OpenCode は、member の identity と `--agent` で選ぶ役割定義を分けます。実体 member の `model` は `{model}` へ、`command_params` の `agent` は `{agent}` へ展開し、同じ役割ファイルを複数モデルで共有します。edit / review / report は `by_mode`、expert や grade のように mode だけで一意に決まらない役割は `by_proficiency` または `by_nickname` で `agent` を上書きします。
312
+
271
313
  `max_concurrency` は、同一ホストの単一モデルを共有する provider(例: ローカル Ollama の `opencode`)が複数同時起動でメモリ競合・モデルロード待ちにより不安定になるのを防ぐために使います。グローバルな `--parallel` を下げずに、その provider だけを直列化できます。register の並列 pipeline では executor と reporter の各 stage が個別に枠を取得するため、別 provider の executor を並列化しつつ、同一 provider の reporter だけを直列化できます。
272
314
 
273
315
  ```yaml
@@ -334,7 +376,12 @@ members:
334
376
  providers:
335
377
  opencode:
336
378
  max_concurrency: 1
337
- command_template: "opencode run --agent {nickname}"
379
+ command_template: "opencode run --agent {agent} --model {model}"
380
+ command_params:
381
+ by_mode:
382
+ edit: { agent: opencode-executor }
383
+ review: { agent: opencode-review-executor }
384
+ report: { agent: opencode-reporter }
338
385
  ```
339
386
 
340
387
  ### 6.2. クラウド executor とローカル reporter の混在構成
@@ -410,7 +457,7 @@ executor の出力は、そのまま reporter へ渡さずに run 単位の evid
410
457
  - executor が構造化した最終報告を返す場合は、標準出力に `<specdojo_executor_evidence>` タグで JSON(`final_message`・`validations`)を出します。`validations[].status` は `passed` / `failed` / `not_run` / `not_applicable` / `requires_human` のいずれかです。`not_applicable` はリポジトリが検査の適用条件を満たさない場合に使い、`reason` へ理由を必ず記録します。`requires_human` は、実 agent CLI の起動、利用枠や課金を伴う操作、認証情報やホスト側の操作など、agent の sandbox から実行できない確認だけに使います。実行できるが省略した検証には使わず、`not_run` として記録します。タグが無い場合は標準出力の残りを最終メッセージとして扱います。
411
458
  - `pipeline.parent_validations` には `validate-schema`(`npm run validate:schema`)、`typecheck`(`npm run typecheck`)、`test-unit`(`npm run test:unit`)、`test-integration`(`npm run test:integration`)、`lint-ts`(`npm run lint:ts`)、`lint-fm`(`npm run lint:fm`)、`lint-md`(`npm run lint:md`)を指定できます。親 runner は executor の成功後・reporter の起動前に、指定順で固定 argv の検証を実行します。
412
459
  - executor prompt には設定済み ID と対応コマンドを明示します。executor はそのコマンドや対象限定版を sandbox 内で実行せず、親 runner の結果だけを `source: runner` と許可リスト `id` 付きで同じ `validations` 配列へ保存します。これにより sandbox 内で成立しない検証を親へ移した場合も二重実行しません。
413
- - result の `changed_files` のパスは evidence の `changes` から、execution の evidence、project register とその派生ビュー、当該 result という runner 管理記録を除いて runner が機械生成します。除外後の変更一覧だけを reporter へ渡し、edit の変更説明は evidence のパスと対にして受け取ります。runner はパスで突き合わせるため、説明の順序は問いません。説明が不足したパスには差分参照を促す既定文を記録し、evidence にないパスの説明は捨てます。`outcome` と `block_reason` は stage の状態・終了コード・保護機構が保存した理由・executor / 親 runner の検証から機械生成します。reporter の JSON Schema は文章項目と対応づけ用のパスだけを受け付け、いずれかの検証が failed または `not_run` なら、reporter の文章にかかわらず機械判定は blocked です。ただし、executor が `not_run`(親 runner へ委譲)と記録したコマンドを、親 runner が同じリポジトリで同じコマンドとして実行し成功していれば、その `not_run` は満たされたものとして扱います。さらに、`npm run <name>` に対応する script がない、`npx <package>` の package が `dependencies` / `devDependencies` にない、または SpecDojo サブコマンドの設定上の適用条件を満たさないことを runner が機械的に確定できる場合、その `not_run` は block せず、edit result の申し送りへ「適用外の検証(runner の判定)」として追記します。SpecDojo の起動形は `specdojo <subcommand>`、`npx specdojo <subcommand>`、ソース/配布済み CLI の直接起動を認識し、`catalog validate` は対象 project の `catalog_path` で判定します。対象 project は、コマンドの `--project <id>`、run の対象 project(runner が execution path に一致する project を設定から特定したもの)、`current_project` の順に決めます。別の project が `catalog_path` を持っていても、run の対象 project に `catalog_path` がなければ適用外です。対象 project に `catalog_path` があっても、executor の変更(runner 管理記録を除き、rename は変更前後の両方を見ます)が `docs/ja/projects/` 配下に及ばない run では、plan の共通規約の検証表と同じく適用外とし、executor の `not_applicable` も受理します。変更が及ぶ run では従来どおり適用対象です。また、`<repo>:<path>` を引数に含むコマンドや `--prefix <repo>` 付きのコマンドは、対象 project が `repos` で宣言したそのプロダクトリポジトリの `package.json` で script と依存を判定します(`--prefix` はリポジトリ名か設定の `path` と一致するものを対象にします)。設定が読めない、対象 project を特定できない、または適用条件を未定義のサブコマンドは機械的な救済をせず、通常の `not_run` として扱います。executor の failed は親 runner の成功や適用外判定で打ち消しません。`npm run check` のように npm script を `&&` でつないだだけの合成コマンドを executor が `not_run` とした場合は、対象リポジトリの `package.json` の script を展開し、構成する各コマンドが同じリポジトリの親検証か executor 自身の検証で通っていれば満たされたものとして扱います。`npm test` は、`npm run test:unit` と `npm run test:integration` の両方が通っていれば満たされたものとします。構成するコマンドの script の中身と同じコマンドを executor が直接実行して通した場合も満たします(`tsx` の起動の書き方の違いはそろえて比べます)。任意のシェルを含む script は展開しません。理由付きの `not_applicable` は block の理由にせず、runner が edit result の申し送りへ「適用外の検証: `<コマンド>`(<理由>)」として機械的に追記します。ただし、理由がない場合、`npm run <name>` の script が存在する場合、または `npx <package>` の package が `dependencies` / `devDependencies` に存在する場合は誤申告として blocked にします。SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。適用条件が未定義なら理由付きの agent の申告に従います。`specdojo index build`(`npx specdojo index build`・`node --import tsx src/specdojo.ts index build` などの起動形を含みます)は runner が担う検証です。出力先の `.specdojo/doc-index.json` は agent が書き込めず、index は worktree の準備と統合の前に runner が再生成するため、executor への指示では実行も記録もしないよう伝えます。executor が `not_run` / `not_applicable` と記録しても block の理由にせず、`not_run` の場合は edit result の申し送りへ「runner が担う検証: `<コマンド>`(<理由>)」として追記します。runner の再生成が失敗した場合は worktree の準備で run が止まるか、runner の検証の失敗として block するため、満たしたものとは扱いません。executor の failed は救済せず、ほかの SpecDojo サブコマンドの `not_run` の扱いも変えません。executor の `requires_human` は block の理由にせず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」として機械的に追記します。項目は review へ進み、人が確認してから close します。
460
+ - result の `changed_files` のパスは evidence の `changes` から、execution の evidence、project register とその派生ビュー、当該 result という runner 管理記録を除いて runner が機械生成します。除外後の変更一覧だけを reporter へ渡し、edit の変更説明は evidence のパスと対にして受け取ります。runner はパスで突き合わせるため、説明の順序は問いません。説明が不足したパスには Git の変更メタデータ(追加・変更・削除・名前の変更、行数)を記録し、変更ファイルが多い場合(50 件超)はディレクトリごとに集約して記録します。evidence にないパスの説明は捨てます。`outcome` と `block_reason` は stage の状態・終了コード・保護機構が保存した理由・executor / 親 runner の検証から機械生成します。reporter の JSON Schema は文章項目と対応づけ用のパスだけを受け付け、いずれかの検証が failed または `not_run` なら、reporter の文章にかかわらず機械判定は blocked です。ただし、executor が `not_run`(親 runner へ委譲)と記録したコマンドを、親 runner が同じリポジトリで同じコマンドとして実行し成功していれば、その `not_run` は満たされたものとして扱います。さらに、`npm run <name>` に対応する script がない、`npx <package>` の package が `dependencies` / `devDependencies` にない、または SpecDojo サブコマンドの設定上の適用条件を満たさないことを runner が機械的に確定できる場合、その `not_run` は block せず、edit result の申し送りへ「適用外の検証(runner の判定)」として追記します。SpecDojo の起動形は `specdojo <subcommand>`、`npx specdojo <subcommand>`、ソース/配布済み CLI の直接起動を認識し、`catalog validate` は対象 project の `catalog_path` で判定します。対象 project は、コマンドの `--project <id>`、run の対象 project(runner が execution path に一致する project を設定から特定したもの)、`current_project` の順に決めます。別の project が `catalog_path` を持っていても、run の対象 project に `catalog_path` がなければ適用外です。対象 project に `catalog_path` があっても、executor の変更(runner 管理記録を除き、rename は変更前後の両方を見ます)が `docs/ja/projects/` 配下に及ばない run では、plan の共通規約の検証表と同じく適用外とし、executor の `not_applicable` も受理します。変更が及ぶ run では従来どおり適用対象です。また、`<repo>:<path>` を引数に含むコマンドや `--prefix <repo>` 付きのコマンドは、対象 project が `repos` で宣言したそのプロダクトリポジトリの `package.json` で script と依存を判定します(`--prefix` はリポジトリ名か設定の `path` と一致するものを対象にします)。設定が読めない、対象 project を特定できない、または適用条件を未定義のサブコマンドは機械的な救済をせず、通常の `not_run` として扱います。executor の failed は親 runner の成功や適用外判定で打ち消しません。`npm run check` のように npm script を `&&` でつないだだけの合成コマンドを executor が `not_run` とした場合は、対象リポジトリの `package.json` の script を展開し、構成する各コマンドが同じリポジトリの親検証か executor 自身の検証で通っていれば満たされたものとして扱います。`npm test` は、`npm run test:unit` と `npm run test:integration` の両方が通っていれば満たされたものとします。構成するコマンドの script の中身と同じコマンドを executor が直接実行して通した場合も満たします(`tsx` の起動の書き方の違いはそろえて比べます)。任意のシェルを含む script は展開しません。理由付きの `not_applicable` は block の理由にせず、runner が edit result の申し送りへ「適用外の検証: `<コマンド>`(<理由>)」として機械的に追記します。ただし、理由がない場合、`npm run <name>` の script が存在する場合、または `npx <package>` の package が `dependencies` / `devDependencies` に存在する場合は誤申告として blocked にします。SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。適用条件が未定義なら理由付きの agent の申告に従います。`specdojo index build`(`npx specdojo index build`・`node --import tsx src/specdojo.ts index build` などの起動形を含みます)は runner が担う検証です。出力先の `.specdojo/doc-index.json` は agent が書き込めず、index は worktree の準備と統合の前に runner が再生成するため、executor への指示では実行も記録もしないよう伝えます。executor が `not_run` / `not_applicable` と記録しても block の理由にせず、`not_run` の場合は edit result の申し送りへ「runner が担う検証: `<コマンド>`(<理由>)」として追記します。runner の再生成が失敗した場合は worktree の準備で run が止まるか、runner の検証の失敗として block するため、満たしたものとは扱いません。executor の failed は救済せず、ほかの SpecDojo サブコマンドの `not_run` の扱いも変えません。executor の `requires_human` は block の理由にせず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」として機械的に追記します。項目は review へ進み、人が確認してから close します。
414
461
  - reporter の出力は JSON Schema で厳格に検証します。形式不正のときは同じ plan と evidence のまま reporter だけを最大 3 回再実行し、executor は再実行しません。
415
462
  - reporter stage の再開では、現在の設定 ID と一致する親検証が保存済み evidence にそろっている場合だけ executor evidence を再利用します。`{ id, repo }` を使う場合は、ID とリポジトリの組が一致することを求めます。再実行時も同じ割り当てで、各リポジトリの worktree を `cwd` にします。保存済みの親検証がすべて成功していれば再実行しません。`failed` / `not_run` があれば、親 runner が現在の worktree で固定許可リストの親検証を再実行し、同じ ID の結果を evidence 上で置換してから reporter へ渡します。過去の親検証ログは置換せず、新しい失敗ログだけを追加します。executor 由来の検証は再実行・置換しません。設定 ID が変わった、または結果が欠けている場合、Schedule 実行は新しい executor run としてやり直し、register 実行は明示的な再実行を促して再開を拒否します。
416
463
  - result の frontmatter は runner が scaffold した内容を保ち、本文は検証済みの reporter 文章と evidence 由来の事実を組み合わせて runner が描画します。reporter はファイルを書きません。
@@ -423,7 +470,7 @@ agent が exec 実行時に読み込む provider 固有の設定(agent 定義
423
470
 
424
471
  | provider | 配布内容 | 配置先 |
425
472
  | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
426
- | claude | `agents/*.md`、`settings.edit.json` / `settings.review.json` / `settings.report.json` | `.claude/agents/`、`.specdojo/claude/` |
473
+ | claude | `agents/*.md`(役割ごとの agent 定義)、`settings.edit.json` / `settings.review.json` / `settings.report.json` | `.claude/agents/`、`.specdojo/claude/` |
427
474
  | codex | `agents/*.toml`(親 Codex が spawn する subagent 定義) | `.codex/agents/` |
428
475
  | opencode | `agents/*.md`(permission frontmatter 込みの agent 定義) | `.opencode/agents/` |
429
476
  | copilot | `agent-members-snippet.yaml`(agent 定義)と `exec-defaults-snippet.yaml`(`providers.copilot` の command template・rate limit 検出)の参照スニペット | `.specdojo/copilot/` |
@@ -460,6 +507,34 @@ specdojo config scaffold --provider claude
460
507
  - `settings.*.json` の `Edit(...)` / `Write(...)` パスパターンの調整は利用者に委ねます。scaffold は `.specdojo/specdojo.config.json` のパス設定に基づく書き換えを行いません(テンプレートを事実上の推奨レイアウト前提で配布します)。
461
508
  - 将来 provider を追加する場合は `templates/<provider>/` を追加し、`package.json` の `files` に含めます。repository 内へのコピーは provider 名からディレクトリを解決します。ユーザーディレクトリ設定も扱う provider だけは、グローバル設定原本と配置先を実装の許可リストへ明示します。
462
509
 
510
+ ### 7.2. agent の名簿の 2 段構成と移行
511
+
512
+ `specdojo init --exec` と `config scaffold` が配布する agent の名簿と定義は、実体と別名の 2 段構成です(0.4.0 から)。実体は model の系統と役割で名付け、provider・`model`・役割を持ちます。従来の名前は `aliases` で実体を指す別名として残します。claude と opencode の agent の定義は役割(executor・review executor・reporter)ごとの 1 ファイルで `model` を持たず、`command_params.by_mode` で mode から定義を選び、model は実体の `model` を `--model {model}` で渡します。
513
+
514
+ | provider | init が生成する実体 | 別名(従来の名前) | model の書き場所 |
515
+ | ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------- |
516
+ | claude | `sonnet-executor`・`sonnet-review-executor`・`sonnet-reporter` | `claude-executor`・`claude-review-executor`・`claude-reporter` | 実体の `model`(`sonnet`) |
517
+ | codex | `terra-executor`・`terra-review-executor`・`terra-reporter` | `codex-executor`・`codex-review-executor`・`codex-reporter` | 実体の `model`(effort は `by_proficiency`) |
518
+ | opencode | `gemma-executor`・`gemma-review-executor`・`gemma-reporter` | `opencode-executor`・`opencode-review-executor`・`opencode-reporter` | 実体の `model`(`opencode.json` の provider 名込み) |
519
+ | antigravity | `flash-executor`・`flash-review-executor`・`flash-reporter` | `agy-executor`・`agy-review-executor`・`agy-reporter` | 実体の `model`(推論強度を含む ID) |
520
+ | copilot | `copilot-executor`・`copilot-review-executor`・`copilot-reporter` | なし(`--model auto` で model を自動選択するため系統で名付けない) | `command_template` の `--model auto` |
521
+
522
+ init は選んだ provider の実体だけを名簿へ書き、別名は向き先の実体が選ばれたものだけを残します。次の手順の案内(`--executor-by` / `--reporter-by`)には別名を示します。antigravity の `agent-members-snippet.yaml` は実体を `disabled: true` で配布するため、別名は末尾にコメントの例として置きます。別名は無効な member を指せないので、向き先の実体を有効にしたものだけを `aliases` へ写します。
523
+
524
+ 既存の利用者の 1 段の名簿(`aliases` も `model` も持たない member と、`--agent {nickname}` の `command_template`)は、変更しなくてもそのまま動きます。
525
+
526
+ - `aliases` は省略でき、`model` を持たない member は従来どおり `command_params`(`by_proficiency` など)の `model` で起動します。member の `model` がある場合だけ、そちらが優先されます。
527
+ - init は既存の `.specdojo/agent-members.yaml` と `.specdojo/exec-defaults.yaml` を上書きしません。scaffold も、`--force` を指定しない限り既存の agent の定義を上書きしません。
528
+ - 注意点は、`--force` で claude / opencode の定義を役割ごとの定義(`model` を持たない)に置き換えた場合です。従来の `--agent {nickname}` のままだと model が渡らず、provider の既定の model で起動します。置き換える場合は、次の手順で 2 段へ移します。
529
+
530
+ 1 段から 2 段へ移す手順は次のとおりです。`.specdojo/` は agent が書き換えられない保護設定のため、人間(または orchestrator の承認を経た操作)が行います。
531
+
532
+ 1. member ごとに、使っている model の系統と役割から実体の名前を決め(`claude-expert-executor` が opus なら `opus-executor`)、`nickname` を実体の名前へ変え、`model`(版を含む ID)を加えます。同じ系統を既定でない provider から使う場合は `agy-opus-executor` のように provider 名を前に付けます。
533
+ 2. 従来の名前を、トップレベルの `aliases` に `nickname` と `alias_of`(実体の名前)の組で加えます。Job・routine・`sch-strategy`・文書・スクリプトにある名前は、別名として解決されるため変えなくて構いません。
534
+ 3. `.specdojo/exec-defaults.yaml` の `command_params.by_proficiency` などにある `model` を外し、member の `model` を正とします。codex の reasoning effort のように model 以外の値は残します。
535
+ 4. claude と opencode は、`templates/<provider>/agents/` の役割ごとの定義を `config scaffold --provider <name> --force` で配置し(手を加えた定義がある場合は差分を確認してから)、`command_template` を `--agent {agent} --model {model}` と `command_params.by_mode` の形へ改めます。model ごとに複製していた定義ファイル(`claude-expert-review-executor.md` など)は、別名から参照されなくなったら削除します。
536
+ 5. `npx specdojo exec run --register <id> --executor-by <alias> --reporter-by <alias> --dry-run` などで、別名から実体が選ばれ、起動のコマンドに `--model` の値が入ることを確かめてから、変更をコミットします。event と result の actor には実体の名前が記録されます。
537
+
463
538
  ## 8. agent 権限とプロンプトインジェクション対策
464
539
 
465
540
  exec の plan は done_criteria と成果物本文から生成され、agent は無人で実行されます。成果物やレビュー対象文書に埋め込まれた指示(プロンプトインジェクション)によって、agent がタスク外のファイル書き換え・情報持ち出しを行うリスクを前提に、権限を設計します。
@@ -491,8 +566,8 @@ providers:
491
566
  command_template: 'codex exec --ephemeral --sandbox workspace-write -c approval_policy="never" -c sandbox_workspace_write.network_access=false --model {model} -c model_reasoning_effort="{effort}"'
492
567
  command_params:
493
568
  by_proficiency:
494
- normal: { model: gpt-5.4-mini, effort: medium }
495
- expert: { model: gpt-5.5, effort: high }
569
+ normal: { effort: medium }
570
+ expert: { effort: high }
496
571
  ```
497
572
 
498
573
  - `--sandbox workspace-write`: 書き込みを worktree(cwd 配下)と一時ディレクトリに限定します。`danger-full-access` は claude の bypassPermissions に相当するため使いません。
@@ -537,11 +612,11 @@ providers:
537
612
  command_params:
538
613
  by_proficiency:
539
614
  normal: { model: gemini-3.8-flash-medium }
540
- expert: { model: gemini-3.1-pro-high }
615
+ expert: { model: gemini-3.8-flash-high }
541
616
  by_nickname:
542
- agy-claude-executor: { model: claude-sonnet-4-6 }
543
- agy-claude-expert-executor: { model: claude-opus-4-6-thinking }
544
- agy-claude-expert-review-executor: { model: claude-opus-4-6-thinking }
617
+ agy-claude-executor: { model: claude-sonnet-5-5-medium }
618
+ agy-claude-expert-executor: { model: claude-opus-5-5-high }
619
+ agy-claude-expert-review-executor: { model: claude-opus-5-5-high }
545
620
  agy-gpt-executor: { model: gpt-oss-120b-medium }
546
621
  ```
547
622
 
@@ -582,7 +657,7 @@ providers:
582
657
 
583
658
  ### 8.4. 親 runner が実行する設定と Git 状態の変更ガード
584
659
 
585
- commit 許可リストだけでは、register 由来の除外リスト方式や、commit より前に親 runner が検証を起動する経路を守れません。そのため `src/exec-agent-protected-config.ts` の固定定義で、次のパスを全 provider 共通の書き込み禁止対象にします。
660
+ commit 許可リストだけでは、register 由来の除外リスト方式や、commit より前に親 runner が検証を起動する経路を守れません。そのため `src/exec/agent-protected-config.ts` の固定定義で、次のパスを全 provider 共通の書き込み禁止対象にします。
586
661
 
587
662
  - `package.json`、`lefthook.yml` / `.lefthook.yml`
588
663
  - `.specdojo/**`(ただし既知の生成物 `.specdojo/doc-index.json` は除く)
@@ -597,17 +672,17 @@ runner は agent の各試行前後でファイル内容を比較し、差分が
597
672
 
598
673
  保護対象の候補はパスの固定定義で分類し、実際に block する対象は `agentProtectedConfigPaths()` で確定します。`.specdojo/doc-index.json` は `index build` が再生成し commit しない既知の生成物なので、リポジトリの ignore 規則にも一致する場合だけ除外します。判定には `git check-ignore --no-index` を使い、過去に追跡されていた worktree でも生成物として扱います。任意の ignore 対象を除外すると、agent が `.gitignore` と新規設定を同時に作って回避できるため、除外は既知の生成物の固定リストに限定します。Git による判定が失敗した場合や ignore 規則から外れた場合は除外せず、保護側へ倒します。agent 前後の snapshot と commit 前の再検査はこの判定を共有します。`pm-members.yaml` は schema により人間だけを受け付ける通常成果物なので、この保護対象には含めません。
599
674
 
600
- agentと親検証の子プロセスを起動する際は、`gitEnvironment()`で`GIT_DIR`、`GIT_WORK_TREE`、`GIT_COMMON_DIR`、index・object・replace関連のrepository固有環境変数を除去します。除去対象は`src/git-environment.ts`の`GIT_LOCAL_ENV_VARS`を正本とします。Vitestの全3設定も共通setupを使ってtest module読込前に同じ変数をworkerから除去するため、Git hook経由で`npm test`が起動されても、テストfixtureはcwdの一時repositoryを参照し、linked worktreeのgitdirや共有configを参照しません。
675
+ agentと親検証の子プロセスを起動する際は、`gitEnvironment()`で`GIT_DIR`、`GIT_WORK_TREE`、`GIT_COMMON_DIR`、index・object・replace関連のrepository固有環境変数を除去します。除去対象は`src/shared/git-environment.ts`の`GIT_LOCAL_ENV_VARS`を正本とします。Vitestの全3設定も共通setupを使ってtest module読込前に同じ変数をworkerから除去するため、Git hook経由で`npm test`が起動されても、テストfixtureはcwdの一時repositoryを参照し、linked worktreeのgitdirや共有configを参照しません。
601
676
 
602
677
  TypeScriptのテスト・tool・本体コードが`spawnSync`、`spawn`、`execFileSync`、`execFile`でGitを直接起動する箇所は、AST検査により`gitEnvironment()`から作った`env`だけを許可します。`env: process.env`や単なる`env`プロパティは隔離済みとは扱いません。shell scriptとnpm scriptのGit起動はこのAST検査の対象外ですが、現状のhook経路はVitest setupを必ず通り、hookから直接Gitを起動するテスト用scriptはありません。今後その経路を追加する場合は、入口で`GIT_LOCAL_ENV_VARS`相当を除去する専用検査を追加します。
603
678
 
604
679
  executor / reporter pipelineのexecutor promptは、commitとrepository設定を親runnerが所有することを明記し、`git commit`およびlocal / global / system configの変更(`user.name` / `user.email`を含む)を禁止します。fixture commitに使うテスト用identityはVitest workerと子プロセスの環境変数だけへ注入し、fixtureを含むrepositoryのlocal configへは書き込みません。
605
680
 
606
- さらに`src/exec-agent-git-state.ts`が各agent試行の直前にagentのcwdから解決したHEAD(commitとsymbolic ref)およびlocal configを記録し、終了直後に比較します。runnerが作成したworktree branchをVS Codeが発見した際に付与する`branch.*.vscode-merge-base`は表示用metadataなので比較から除外します。それ以外のlocal configは順序と重複を保って比較し、`core.bare`などrepository動作に関わる変更を検知します。HEADまたは監視対象設定に差分があれば`agent-git-state-write:`と変更フィールドを標準エラーへ出力し、親検証・reporter・commit・mergeへ進まずblockします。通常のworktree実行だけでなく、in-place、`exec trial`、`exec worktree agent`にも同じ境界を適用します。
681
+ さらに`src/exec/agent-git-state.ts`が各agent試行の直前にagentのcwdから解決したHEAD(commitとsymbolic ref)およびlocal configを記録し、終了直後に比較します。runnerが作成したworktree branchをVS Codeが発見した際に付与する`branch.*.vscode-merge-base`は表示用metadataなので比較から除外します。それ以外のlocal configは順序と重複を保って比較し、`core.bare`などrepository動作に関わる変更を検知します。HEADまたは監視対象設定に差分があれば`agent-git-state-write:`と変更フィールドを標準エラーへ出力し、親検証・reporter・commit・mergeへ進まずblockします。通常のworktree実行だけでなく、in-place、`exec trial`、`exec worktree agent`にも同じ境界を適用します。
607
682
 
608
683
  設定変更が必要なタスクでは、agent は対象パス、変更理由、提案差分、変更後に必要な検証を result の申し送りへ記載して block します。人間または対話型 orchestrator は agent 実行外で `specdojo exec handoff apply --project <project-id> --register <PJR-ID>` を実行し、表示された提案差分を確認して統合先へ適用・commit します。対話入力では `y` / `yes`、非対話実行では `--yes` が必要で、確認がなければ変更しません。`package.json` の依存定義を変更した場合は、コマンドの案内に従って対応する lock ファイルを再生成・commit してから `exec run --register ... --worktree --resume` で再開します。提案差分がない、切り詰められている、対象パスと一致しない、または統合先へ安全に適用できない場合は自動適用せずエラーにします。agent 用の解除フラグはありません。
609
684
 
610
- ただし block は agent の記入を待たずに成立するため、記入を agent の遵守だけに委ねると申し送りが `_TODO_` のまま残ります。そのため `src/exec-protection-handoff.ts` が、block した時点で機構側から result の申し送り節へ次を自動記録します(`agent-config-write` / `agent-git-state-write` の双方が対象です)。
685
+ ただし block は agent の記入を待たずに成立するため、記入を agent の遵守だけに委ねると申し送りが `_TODO_` のまま残ります。そのため `src/exec/protection-handoff.ts` が、block した時点で機構側から result の申し送り節へ次を自動記録します(`agent-config-write` / `agent-git-state-write` の双方が対象です)。
611
686
 
612
687
  - 保護機構名と、標準エラーへ出力するものと同じ block メッセージ。
613
688
  - 対象パス(`agent-config-write`)または対象フィールド(`agent-git-state-write`)。
@@ -17,7 +17,7 @@ Exec Operation Guide
17
17
 
18
18
  **この文書で分かること**
19
19
 
20
- - 実行経路の選び方、状態遷移、blocked 復帰、再実行、human タスクの扱い
20
+ - 実行経路の選び方、状態遷移、blocked 復帰、再実行、human タスクの扱い、register から approach を使って成果物・kata を作る・直す手順
21
21
 
22
22
  **次に読む文書**
23
23
 
@@ -73,17 +73,18 @@ register 実行は exec events を記録しないため、schedule の Ready・C
73
73
 
74
74
  ### 1.3. ユースケース別の選び方
75
75
 
76
- | やりたいこと | 代表コマンド | 状態追跡 | worktree |
77
- | --------------------------------------- | ------------------------------------- | --------------- | -------- |
78
- | 1 task をカレントで軽く実行する | `exec run --task` | なし | なし |
79
- | 1 task をカレントで実行し進捗へ反映する | `exec run --task --track-state` | あり | なし |
80
- | 1 task を隔離して実行する | `exec run --task --worktree` | あり | あり |
81
- | Ready 順に自動実行する | `exec run --auto` | あり | あり |
82
- | 登録簿の項目を agent に実行させる | `exec run --register` | register の遷移 | 設定依存 |
83
- | 登録簿の複数項目を指定順に実行する | `exec run --register PJR-A PJR-B` | register の遷移 | 設定依存 |
84
- | plan を確認してから実行する | `exec plan` -> `exec run --plan` | 任意 | 任意 |
85
- | worktree の各段階を人が確認する | `exec worktree prepare` から `remove` | 手動 | あり |
86
- | 同じplanで複数agentを比較する | `exec trial run` | なし | agent別 |
76
+ | やりたいこと | 代表コマンド | 状態追跡 | worktree |
77
+ | ----------------------------------------------------- | ------------------------------------- | --------------- | -------- |
78
+ | 1 task をカレントで軽く実行する | `exec run --task` | なし | なし |
79
+ | 1 task をカレントで実行し進捗へ反映する | `exec run --task --track-state` | あり | なし |
80
+ | 1 task を隔離して実行する | `exec run --task --worktree` | あり | あり |
81
+ | Ready 順に自動実行する | `exec run --auto` | あり | あり |
82
+ | 登録簿の項目を agent に実行させる | `exec run --register` | register の遷移 | 設定依存 |
83
+ | 登録簿の todo から approach で成果物・kata を実行する | `exec run --register <PJR-ID>` | register の遷移 | 設定依存 |
84
+ | 登録簿の複数項目を指定順に実行する | `exec run --register PJR-A PJR-B` | register の遷移 | 設定依存 |
85
+ | plan を確認してから実行する | `exec plan` -> `exec run --plan` | 任意 | 任意 |
86
+ | worktree の各段階を人が確認する | `exec worktree prepare` から `remove` | 手動 | あり |
87
+ | 同じplanで複数agentを比較する | `exec trial run` | なし | agent別 |
87
88
 
88
89
  `exec run --register ... --register-commit` は、各IDのcommit後にhookによる整形差分を同じcommitへ収束させ、対象差分が残っていないことを検証します。登録簿・派生ビュー・当該plan/resultはrunner管理パスとして扱い、その他の実行前からある利用者変更はcommitしません。過去の未commit plan/resultを検出した場合は、現在のIDへ混ぜず警告します。
89
90
 
@@ -535,3 +536,135 @@ specdojo exec refresh --project <project-id>
535
536
  ```
536
537
 
537
538
  成果物の `status` を `ready` に昇格できるのは人だけです。エージェント実行では、`ready` へ昇格させるコミットは exec のガードで拒否されます。
539
+
540
+ ## 4. register の todo から approach で成果物・kata を作る・直す手順
541
+
542
+ プロジェクト登録簿(register)の `todo` 個票に進め方(`approach`)と対象(`targets`)を指定し、成果物や kata(実践の型: rulebook / recipe / sample / template)を agent に作成・修正させる手順を説明します。
543
+
544
+ ### 4.1. register 経路と exec run --deliverable の違い
545
+
546
+ 成果物や kata を単発で作成・修正する経路には、`exec run --deliverable` と register 経由(`exec run --register`)の 2 つがあります。
547
+
548
+ | 観点 | `exec run --deliverable <localId>` | register 経由(`exec run --register <PJR-ID>`) |
549
+ | ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
550
+ | 実行場所・隔離 | カレントの作業ツリーでそのまま実行(in-place) | git worktree で作業を安全に隔離(`--worktree` 推奨) |
551
+ | ブランチ統合 | 統合ブランチへの merge commit を行わない | 成功時に統合ブランチへ merge commit(1 項目 1 commit) |
552
+ | 状態管理・レビュー | 状態イベントを記録せず、review 遷移もない | `open -> in-progress -> review` と遷移し、人間が確認可能 |
553
+ | 台帳・監査履歴 | 登録簿に記録されない | 個票および `events/` 配下の変更履歴に残る |
554
+
555
+ `exec run --deliverable` は作業場所でそのまま実行する軽量な経路ですが、worktree 隔離・統合・review・台帳の記帳を行いません。このため過去の版との互換性のために残されており、計画外や単発の作業であっても、成果物や kata を作る・直す際は変更の安全な隔離と台帳管理が揃った **register の経路(個票に approach を指定して `exec run --register` で実行)を推奨します**。
556
+
557
+ ### 4.2. 個票の起票と approach・target の指定
558
+
559
+ register 経由で実行するには、個票に `approach` と `targets` を指定します。
560
+
561
+ `register add` で新規起票するときに `--approach` と `--target` を指定します。
562
+
563
+ ```bash
564
+ # 成果物を作成・修正する todo を起票する例
565
+ specdojo register add \
566
+ --project <project-id> \
567
+ --type todo \
568
+ --title "SpecDojo 設定ガイドの改訂" \
569
+ --topic exec-config-guide-revision \
570
+ --approach fully-guided \
571
+ --target specdojo:exec-config-guide \
572
+ --owner DEV
573
+ ```
574
+
575
+ 既存の個票へ追加または変更する場合は `register update` を使います。
576
+
577
+ ```bash
578
+ specdojo register update \
579
+ --project <project-id> \
580
+ --id <PJR-ID> \
581
+ --approach fully-guided \
582
+ --target specdojo:exec-config-guide
583
+ ```
584
+
585
+ 個票 Frontmatter には次のように `approach` と `targets` が記録されます。
586
+
587
+ ```yaml
588
+ specdojo:
589
+ id: prj-0001:pjr-xxxx-exec-config-guide-revision
590
+ type: project
591
+ status: draft
592
+ rulebook: specdojo:pjr-rulebook
593
+ part_of:
594
+ - prj-0001:pjr-index
595
+ item_type: todo
596
+ item_status: open
597
+ priority: medium
598
+ owner: DEV
599
+ approach: fully-guided
600
+ targets:
601
+ - specdojo:exec-config-guide
602
+ ```
603
+
604
+ `approach` を指定した個票では、`targets` は **1 件だけ必須** です(schedule のタスクと同様に 1 件の成果物または 1 件の kata を対象にします)。
605
+
606
+ ### 4.3. 対象の指定方法と kata 保守 approach の選び方
607
+
608
+ `targets` に指定する対象文書の書き方と、kata 保守の進め方(`approach`)の選び方は次のとおりです。
609
+
610
+ #### 4.3.1. 成果物を対象にする場合
611
+
612
+ - **対象(`targets`)**: 成果物カタログ(DCT)に定義されている成果物の文書 ID(doc id)を指定します(例: `prj-0001:cxd-specdojo`、`specdojo:exec-config-guide`)。プロダクト成果物の場合は `local_id` の canonical 形式(`<project-id>:<local_id>`)も受け付けます。まだ文書ファイルが作成されていない成果物であっても、カタログに定義されていればカタログで解決され、起票・実行できます。
613
+ - **進め方(`approach`)**: 成果物を作成・修正する進め方(`fully-guided`、`recipe-guided`、`freeform`、`bootstrap`、`retrofit`、`cross-deliverable-dedup` など)から目的に応じて選びます。
614
+
615
+ #### 4.3.2. kata(実践の型)を対象にする場合
616
+
617
+ - **対象(`targets`)**: kata の文書 ID(doc id)を指定します(例: `specdojo:pjr-rulebook`、`specdojo:exec-human-finalize-recipe` など)。kata は文書索引(doc-index)で解決されます。
618
+ - **進め方(`approach`)の選び方**: 見直したい kata の種別に対応する保守 approach を選びます。kata 保守では、通常の「成果物 → 実践の型」という参照の向きが逆になり、実践の型そのものが改訂・編集の対象になります。
619
+
620
+ | kata の種別 | approach | 対象となる文書 |
621
+ | ----------- | ---------------------- | ----------------------------------------------------------------- |
622
+ | rulebook | `rulebook-maintenance` | 作成ルール、規律、品質基準(例: `specdojo:pjr-rulebook`) |
623
+ | recipe | `recipe-maintenance` | 実行手順、運用レシピ(例: `specdojo:exec-human-finalize-recipe`) |
624
+ | sample | `sample-maintenance` | 実例、サンプル成果物 |
625
+ | template | `template-maintenance` | 雛形、テンプレート(例: 個票や成果物のテンプレート) |
626
+
627
+ ### 4.4. 組み合わせの検証とエラー
628
+
629
+ `approach` と対象の組み合わせに誤りがある場合は、**起票・更新の時点(`register add` / `register update`)および実行の時点(`exec run --register` / `exec plan --register`)** で検証され、エラーで停止します。
630
+
631
+ - 成果物を対象に `rulebook-maintenance` などの kata 保守 approach を指定した場合、または kata 文書を対象に `fully-guided` などの成果物作成 approach を指定した場合は、種別の不一致として拒否されます。
632
+ - 指定した doc id が成果物カタログ(成果物の場合)または文書索引(kata の場合)で解決できない場合もエラーになります。
633
+ - `approach` を指定しながら `--target` が省略されている場合や、複数件指定されている場合もエラーになります。
634
+
635
+ ### 4.5. plan の生成と owner の扱い
636
+
637
+ `exec run --register`(または `exec plan --register`)で生成される plan は、通常の register plan ではなく、schedule と共通の approach テンプレートを用いた plan になります。
638
+
639
+ - **完了条件の合成**: 成果物カタログ(DCT)の `done_criteria` と、個票の「2. 完了条件」節に記載された条件の **両方が plan に載ります**。DCT の `done_criteria` を基本とし、個票の完了条件を追加の条件として併記します。
640
+ - **kata 保守の plan**: 指定された kata の文書 ID を編集対象とします。カタログ上でその kata を一意に宣言している成果物があれば根拠として併記し、共有または未宣言の場合は kata 単独の保守 plan を生成します。
641
+ - **owner の扱い**: schedule のタスクで使われる `owner_rules`(トラック別の自動解決規則)は参照せず、**個票の `owner`(例: `DEV`)をそのまま plan の担当(owner)として使用します**。
642
+
643
+ ### 4.6. 実行手順の流れ
644
+
645
+ 起票から完了までの一連のコマンド実行手順は次のとおりです。
646
+
647
+ ```bash
648
+ # 1. todo 個票を起票する(approach と target を指定)
649
+ specdojo register add \
650
+ --project <project-id> \
651
+ --type todo \
652
+ --title "SpecDojo 設定ガイドの改訂" \
653
+ --topic exec-config-guide-revision \
654
+ --approach fully-guided \
655
+ --target specdojo:exec-config-guide \
656
+ --owner DEV
657
+
658
+ # 2. (任意)事前に生成される plan の内容を確認する
659
+ specdojo exec plan --project <project-id> --register <PJR-ID>
660
+
661
+ # 3. worktree 隔離で agent を実行する
662
+ specdojo exec run --project <project-id> --register <PJR-ID> --worktree
663
+
664
+ # 4. agent が成功すると成果物が統合ブランチへマージされ、個票が review 状態に遷移する
665
+ # 成果物と対応結果を確認し、問題なければ close する
666
+ specdojo register close \
667
+ --project <project-id> \
668
+ --id <PJR-ID> \
669
+ --conclusion "設定ガイドを改訂し検証を通過"
670
+ ```
@@ -33,6 +33,8 @@ Exec Worktree Guide
33
33
 
34
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
35
 
36
+ `git worktree add` は、worktree と branch を作成した後で一時的な失敗を返す場合があるため、同じコマンドを再実行する前に作成結果を照合します。目的の path・branch・分岐元 commit がそろっていれば作成済みとして続行します。branch だけが同じ分岐元 commit に作られた部分状態は、その branch と未登録 path を片付けてから再試行します。branch が異なる commit を指す場合や別の worktree で使われている場合は削除せず、競合を報告して停止します。
37
+
36
38
  | コマンド | 責務 | Git変更 | イベント変更 |
37
39
  | ------------------ | -------------------------------------------------------------------------------- | --------- | ------------ |
38
40
  | `worktree prepare` | task worktree を準備し、実行管理ファイルを exec branch へ checkpoint commit する | あり | なし |
@@ -42,27 +42,29 @@ CLI を直接操作する場合の代表フローは [遂行の技活用ガイ
42
42
 
43
43
  `package.json` に、対話起動用の npm スクリプトを `orch:` 接頭辞で用意しています。Claude Code / Codex はモデル別に用意し、`:work` 付きは固定 worktree で起動します。
44
44
 
45
- | スクリプト | CLI・モデル | worktree |
46
- | ------------------- | ----------------------------------- | ----------------------------------------------- |
47
- | `orch:sonnet` | Claude Code / `sonnet` | なし |
48
- | `orch:sonnet:work` | Claude Code / `sonnet` | `../worktrees/claude-work`(無ければ自動作成) |
49
- | `orch:opus` | Claude Code / `opus` | なし |
50
- | `orch:opus:work` | Claude Code / `opus` | `../worktrees/claude-work`(無ければ自動作成) |
51
- | `orch:terra` | Codex / `gpt-5.6-terra` | なし |
52
- | `orch:terra:work` | Codex / `gpt-5.6-terra` | `../worktrees/codex-work`(無ければ自動作成) |
53
- | `orch:sol` | Codex / `gpt-5.6-sol` | なし |
54
- | `orch:sol:work` | Codex / `gpt-5.6-sol` | `../worktrees/codex-work`(無ければ自動作成) |
55
- | `orch:copilot` | GitHub Copilot | なし |
56
- | `orch:copilot:work` | GitHub Copilot | `../worktrees/copilot-work`(無ければ自動作成) |
57
- | `orch:qwen` | OpenCode / Qwen 3.8 | なし |
58
- | `orch:qwen:work` | OpenCode / Qwen 3.8 | `../worktrees/qwen-work`(無ければ自動作成) |
59
- | `orch:gemma` | OpenCode / Gemma 4 | なし |
60
- | `orch:gemma:work` | OpenCode / Gemma 4 | `../worktrees/gemma-work`(無ければ自動作成) |
61
- | `orch:agy` | Antigravity / `gemini-3.1-pro-high` | なし |
62
- | `orch:agy:work` | Antigravity / `gemini-3.1-pro-high` | `../worktrees/agy-work`(無ければ自動作成) |
45
+ | スクリプト | CLI・モデル | worktree |
46
+ | ------------------- | ------------------------------------- | ----------------------------------------------- |
47
+ | `orch:sonnet` | Claude Code / `sonnet` | なし |
48
+ | `orch:sonnet:work` | Claude Code / `sonnet` | `../worktrees/claude-work`(無ければ自動作成) |
49
+ | `orch:opus` | Claude Code / `opus` | なし |
50
+ | `orch:opus:work` | Claude Code / `opus` | `../worktrees/claude-work`(無ければ自動作成) |
51
+ | `orch:terra` | Codex / `gpt-5.6-terra` | なし |
52
+ | `orch:terra:work` | Codex / `gpt-5.6-terra` | `../worktrees/codex-work`(無ければ自動作成) |
53
+ | `orch:sol` | Codex / `gpt-5.6-sol` | なし |
54
+ | `orch:sol:work` | Codex / `gpt-5.6-sol` | `../worktrees/codex-work`(無ければ自動作成) |
55
+ | `orch:copilot` | GitHub Copilot | なし |
56
+ | `orch:copilot:work` | GitHub Copilot | `../worktrees/copilot-work`(無ければ自動作成) |
57
+ | `orch:qwen` | OpenCode / Qwen 3.8 | なし |
58
+ | `orch:qwen:work` | OpenCode / Qwen 3.8 | `../worktrees/qwen-work`(無ければ自動作成) |
59
+ | `orch:gemma` | OpenCode / Gemma 4 | なし |
60
+ | `orch:gemma:work` | OpenCode / Gemma 4 | `../worktrees/gemma-work`(無ければ自動作成) |
61
+ | `orch:agy` | Antigravity / `gemini-3.8-flash-high` | なし |
62
+ | `orch:agy:work` | Antigravity / `gemini-3.8-flash-high` | `../worktrees/agy-work`(無ければ自動作成) |
63
63
 
64
64
  Antigravity CLI(`agy`)はファイル定義の agent を持たないため、Codex と同じく SSOT `.agents/specdojo-orchestrator.agent.md` の本文を `-i`(初期プロンプトを与えて対話を続ける)で渡します。ラッパーは不要で、`.agents/rules/*.md` の薄いラッパー経由で `.github/instructions/` の規則も読み込まれます。
65
65
 
66
+ Antigravity で使えるモデル ID は `agy models` で確認してください。配布時点の既定値は、agy 1.3.5 で提供される `gemini-3.8-flash-high` です。
67
+
66
68
  用途に応じて使い分けます。
67
69
 
68
70
  ```bash
@@ -115,6 +117,37 @@ npx specdojo config scaffold --provider antigravity --global
115
117
 
116
118
  対象 project は、`--project <id>` → 環境変数 `SPECDOJO_PROJECT` → `specdojo.config.json` の `current_project` → `projects` 先頭、の順で解決します([遂行の技活用ガイド](waza-guide.md) の `プロジェクト解決順序` を参照)。会話で対象を特定できない場合は確認します。
117
119
 
120
+ ### 3.1. plan モードと register の使い分け
121
+
122
+ Claude Code などの AI ツールが備える plan モード(計画モード)と、`specdojo` のプロジェクト登録簿(register)は、目的とライフサイクルが異なります。オーケストレーターとの対話では、両者の役割を理解して適切に使い分けることが重要です。
123
+
124
+ #### plan モードと register の性質の違い
125
+
126
+ Claude Code の plan モードで作成される plan は、会話の中でアイデアを整理し、作業手順の当たりをつけるための「使い捨ての下書き(ドラフト)」です。既定では `~/.claude/plans/` 配下にランダムな名前で保存され、古いファイルは一定期間(約 30 日)で自動削除される一時的な性質を持ちます(Claude Code では `plansDirectory` 設定で保存先を変更できます)。これは Claude Code に限らず、他の AI ツール(Codex、Antigravity、OpenCode など)が提供する一時的な plan 機能や計画モードにも共通する特徴です。
127
+
128
+ 一方、`specdojo` のプロジェクト登録簿(register)は、プロジェクト進行中の意思決定、課題、作業を体系的に記録・追跡する「リポジトリの正本台帳」です(詳細は [[specdojo:register-operation-guide|登録簿運用ガイド]] を参照してください)。
129
+
130
+ 両者の違いを次の観点で対比します。
131
+
132
+ | 観点 | plan モードの plan(会話の下書き) | プロジェクト登録簿(register) |
133
+ | :------------------------ | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
134
+ | **識別** | ランダムな名前(UUID 等)。会話外や後からの参照は困難 | `PJR-XXXX` の恒久的な ID。コミットログや他文書から `Refs:` で追跡可能 |
135
+ | **種類** | 種別の区別なし(Markdown の自由記述) | 明確な種別区分(`decision`・`todo`・`issue`・`question`・`risk`・`note` など) |
136
+ | **状態の遷移とイベント** | 状態管理なし(会話終了や時間経過とともに消去) | 明示的な状態遷移(`open` → `in-progress` → `resolved` / `closed` 等)と `events/pjr-XXXX.yaml` による変更履歴の追跡 |
137
+ | **exec・commit との接続** | exec の plan / result や Git コミットとの体系的な紐付けなし | `specdojo exec` の plan / result への接続([[specdojo:exec-operation-guide\|exec運用ガイド]] 参照)、統合コミットとの紐付け |
138
+ | **意思決定の記録** | 決定内容や合意の経緯が会話ログに埋もれて散逸する | `decision` による決定者・決定日・承認方式(合意・レビュー・委任等)の確実な記録 |
139
+ | **履歴の永続性** | 既定で一時ディレクトリに保存され、一定期間(約 30 日)で削除される | リポジトリ内の個票(`pjr-XXXX-<topic>.md`)として Git 履歴とともに永続管理 |
140
+ | **一覧での見渡し** | 会話横断での俯瞰や残課題の一覧化は困難 | 生成される一覧(`pjr-index.md`)や派生ビューにより、全体の状況や残課題を一覧で見渡し可能 |
141
+
142
+ #### 運用の流れ
143
+
144
+ オーケストレーターと対話しながら進める場合、次のように plan モードから register へ情報を昇格させる運用を推奨します。
145
+
146
+ 1. **会話の中での検討・下書き(plan モード)**: オーケストレーターと対話しながらアプローチを検討する段階では、AI ツールの plan モードを使って自由に方針や作業手順を下書きします。この plan は使い捨てのドラフトとして扱います。手元にログを残したい場合でも、`plansDirectory` を `tmp/plans` などの Git コミット対象外のディレクトリに指定し、リポジトリにコミットしません。
147
+ 2. **残す判断の記録(register: decision)**: 会話や plan モードで合意した設計方針・重要な判断は、plan モード内に放置せず、`decision` 種別の個票として登録簿に書き写します。決定者、決定日、承認方式を記録することで、後から経緯を検証可能にします。
148
+ 3. **作業範囲と完了条件の確定(register: todo)**: 実行すべき作業範囲は、`todo` 種別の個票として登録簿に登録し、plan モードで検討した具体的な作業項目や検証条件を「完了条件」セクションへ書き写します。
149
+ 4. **タスクの実行と追跡(exec)**: 登録された todo に対して `specdojo exec` を実行し、exec plan と result を通じて成果物の変更と検証を進めます。
150
+
118
151
  ## 4. 安全と権限
119
152
 
120
153
  オーケストレーターは、状態やファイルを変える操作を承認なしに実行しません。CLI 側の権限機構でも同じ方針を多重に担保します。