specdojo 0.2.1 → 0.3.1

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 (242) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +298 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/catalog-build-references.js +144 -0
  8. package/dist/catalog-build-render.js +144 -0
  9. package/dist/catalog-build.js +13 -290
  10. package/dist/catalog-generate.js +6 -9
  11. package/dist/catalog-plan-generate.js +2 -2
  12. package/dist/catalog-plan.js +6 -6
  13. package/dist/catalog-scaffold.js +4 -4
  14. package/dist/catalog.js +2 -2
  15. package/dist/dashboard-exec-records.js +105 -0
  16. package/dist/dashboard-routines.js +255 -0
  17. package/dist/dashboard-shared.js +14 -0
  18. package/dist/dashboard-timeline.js +175 -0
  19. package/dist/dashboard.js +31 -444
  20. package/dist/deliverable-trash.js +3 -3
  21. package/dist/devcontainer-command.js +43 -0
  22. package/dist/devcontainer-scaffold.js +165 -0
  23. package/dist/doc-index.js +3 -3
  24. package/dist/exec-agent-config.js +107 -9
  25. package/dist/exec-agent-git-state.js +18 -0
  26. package/dist/exec-agent-protected-config.js +46 -8
  27. package/dist/exec-commands.js +557 -0
  28. package/dist/exec-core.js +457 -0
  29. package/dist/exec-evidence.js +254 -11
  30. package/dist/exec-handoff.js +336 -0
  31. package/dist/exec-parent-validation.js +317 -43
  32. package/dist/exec-pipeline-state.js +74 -9
  33. package/dist/exec-plans-core.js +693 -0
  34. package/dist/exec-plans-generation.js +206 -0
  35. package/dist/exec-plans-storage.js +131 -0
  36. package/dist/exec-plans.js +3 -1016
  37. package/dist/exec-protection-handoff.js +43 -2
  38. package/dist/exec-provider-scaffold.js +247 -15
  39. package/dist/exec-register-resume.js +65 -19
  40. package/dist/exec-register.js +9 -3
  41. package/dist/exec-repo-integration-git.js +23 -0
  42. package/dist/exec-repo-integration-sync.js +264 -0
  43. package/dist/exec-repo-integration.js +534 -0
  44. package/dist/exec-repo-trace.js +182 -0
  45. package/dist/exec-reporter-output.js +206 -0
  46. package/dist/exec-reporter.js +525 -248
  47. package/dist/exec-results.js +103 -71
  48. package/dist/exec-run-agent-pipeline.js +256 -0
  49. package/dist/exec-run-agent.js +531 -0
  50. package/dist/exec-run-in-place.js +541 -0
  51. package/dist/exec-run-job.js +717 -0
  52. package/dist/exec-run-lifecycle-commands.js +522 -0
  53. package/dist/exec-run-lock.js +110 -107
  54. package/dist/exec-run-mode-shared.js +140 -0
  55. package/dist/exec-run-register-command.js +244 -0
  56. package/dist/exec-run-register-core.js +386 -0
  57. package/dist/exec-run-register-mode.js +206 -0
  58. package/dist/exec-run-register-resume.js +393 -0
  59. package/dist/exec-run-register-state.js +322 -0
  60. package/dist/exec-run-register-worktree.js +509 -0
  61. package/dist/exec-run-schedule-mode.js +294 -0
  62. package/dist/exec-run-schedule-prepare.js +353 -0
  63. package/dist/exec-run-schedule-task.js +572 -0
  64. package/dist/exec-run-shared.js +399 -0
  65. package/dist/exec-run.js +11 -4953
  66. package/dist/exec-shared.js +9 -2
  67. package/dist/exec-slot-lock.js +242 -0
  68. package/dist/exec-task-repos.js +415 -0
  69. package/dist/exec-trial-commands.js +558 -0
  70. package/dist/exec-trial-core.js +371 -0
  71. package/dist/exec-trial.js +2 -895
  72. package/dist/exec-worktree-command.js +87 -43
  73. package/dist/exec-worktree-ops-commit.js +707 -0
  74. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  75. package/dist/exec-worktree-ops-merge.js +303 -0
  76. package/dist/exec-worktree-ops.js +3 -847
  77. package/dist/exec-worktree.js +146 -31
  78. package/dist/exec.js +2 -999
  79. package/dist/frontmatter-namespace.js +2 -2
  80. package/dist/grade-apply.js +734 -0
  81. package/dist/grade-command-apply.js +250 -0
  82. package/dist/grade-command-inspect.js +138 -0
  83. package/dist/grade-command-plan.js +101 -0
  84. package/dist/grade-command-shared.js +68 -0
  85. package/dist/grade-core.js +307 -0
  86. package/dist/grade-markdown.js +274 -0
  87. package/dist/grade-pipeline-state.js +184 -0
  88. package/dist/grade-plan.js +507 -0
  89. package/dist/grade-result.js +133 -5
  90. package/dist/grade-target-discovery.js +265 -0
  91. package/dist/grade-targets.js +432 -0
  92. package/dist/grade.js +14 -2451
  93. package/dist/init-command.js +443 -0
  94. package/dist/job-definition.js +670 -0
  95. package/dist/job.js +64 -578
  96. package/dist/kata-command.js +2 -2
  97. package/dist/orchestrator.js +213 -0
  98. package/dist/register-command-types.js +1 -0
  99. package/dist/register-core.js +363 -0
  100. package/dist/register-create-commands.js +245 -0
  101. package/dist/register-event-merge.js +169 -0
  102. package/dist/register-events.js +4 -4
  103. package/dist/register-item.js +13 -7
  104. package/dist/register-maintenance-commands.js +187 -0
  105. package/dist/register-migration.js +268 -0
  106. package/dist/register-renumber.js +314 -0
  107. package/dist/register-transition-commands.js +248 -0
  108. package/dist/register-update.js +230 -0
  109. package/dist/register-views.js +256 -0
  110. package/dist/register.js +175 -1975
  111. package/dist/review-grade.js +252 -0
  112. package/dist/review-plan.js +114 -4
  113. package/dist/review-types.js +40 -1
  114. package/dist/routine-definition.js +401 -0
  115. package/dist/routine.js +73 -402
  116. package/dist/schedule-approach.js +2 -2
  117. package/dist/schedule-build.js +2 -2
  118. package/dist/schedule-strategy-generate-document.js +273 -0
  119. package/dist/schedule-strategy-generate-scope.js +199 -0
  120. package/dist/schedule-strategy-generate.js +9 -473
  121. package/dist/schedule.js +19 -6
  122. package/dist/specdojo-config.js +465 -20
  123. package/dist/specdojo-gitignore.js +135 -0
  124. package/dist/specdojo.js +6 -0
  125. package/dist/viewpoint-document-kinds-check.js +128 -0
  126. package/dist/yaml-pages.js +4 -4
  127. package/dist/yaml.js +28 -0
  128. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  129. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  130. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  131. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  132. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  133. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  134. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  135. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  136. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  137. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  138. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  139. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  140. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  141. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  142. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  143. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  144. package/docs/ja/specdojo/guides/exec-config-guide.md +93 -49
  145. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  146. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  147. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  148. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +45 -22
  149. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  150. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  151. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  152. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  153. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  154. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  155. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  156. package/docs/ja/specdojo/guides/routine-operation-guide.md +75 -10
  157. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  158. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  159. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  160. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  161. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  162. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  163. package/docs/ja/specdojo/index.md +2 -2
  164. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  165. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  166. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  167. package/docs/ja/specdojo/references/command-reference.md +335 -92
  168. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  169. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  170. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  171. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  172. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  173. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  174. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  175. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  176. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  177. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  178. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  179. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  180. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  181. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  182. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  183. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  184. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  185. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  186. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  187. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  188. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  189. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  190. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  191. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  192. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  193. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  195. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  196. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  197. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  198. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  199. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  200. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  201. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  202. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  203. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  204. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  205. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  206. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  207. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  208. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  209. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  210. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  211. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  212. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  213. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  214. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  215. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  216. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  217. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  218. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  219. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  220. package/package.json +17 -12
  221. package/templates/antigravity/README.md +29 -4
  222. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  223. package/templates/antigravity/exec-defaults-snippet.yaml +10 -7
  224. package/templates/antigravity/orchestrator.md +18 -7
  225. package/templates/antigravity/settings.global.json +55 -0
  226. package/templates/claude/agents/claude-executor.md +14 -0
  227. package/templates/claude/agents/claude-reporter.md +16 -0
  228. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  229. package/templates/claude/settings.edit.json +27 -1
  230. package/templates/codex/README.md +5 -4
  231. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  232. package/templates/codex/orchestrator.md +18 -7
  233. package/templates/copilot/README.md +7 -5
  234. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  235. package/templates/devcontainer/devcontainer.json +27 -0
  236. package/templates/devcontainer/emacs/init.el +88 -0
  237. package/templates/devcontainer/post-create.sh +62 -0
  238. package/templates/init-agent-members.yaml +200 -0
  239. package/templates/init-exec-defaults.yaml +74 -0
  240. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  241. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  242. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -79,9 +79,12 @@ specdojo register scaffold --project <project-id>
79
79
  登録は `register add` で行います。ID は省略すると自動採番されます。
80
80
 
81
81
  ```bash
82
- specdojo register add --project <project-id> --type todo --title "在庫初期データの登録"
82
+ specdojo register add --project <project-id> --type todo \
83
+ --title "在庫初期データの登録" --topic inventory-seed
83
84
  ```
84
85
 
86
+ タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID を変更できます。
87
+
85
88
  `--priority` は次の目安で付けます(省略時は `medium`)。
86
89
 
87
90
  | priority | 目安 |
@@ -123,8 +126,8 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
123
126
  | 他者・外部の対応を待つ | `register wait` | `waiting` |
124
127
  | 確認・レビューに回す | `register review` | `review` |
125
128
  | 完了する | `register close` | `done`(`decision` / `question` は `decided`。`note` は終端させない) |
126
- | 対応しないと判断する | `register reject` | `rejected` |
127
- | 延期する | `register defer` | `deferred` |
129
+ | 対応しないと判断する | `register reject` | `rejected`(`note` は拒否) |
130
+ | 延期する | `register defer` | `deferred`(`note` は拒否) |
128
131
  | 終了済み項目を再開する | `register reopen` | `open` |
129
132
  | 担当・期限などを変更する | `register update` | (状態は変えずフィールドを更新) |
130
133
 
@@ -147,8 +150,8 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
147
150
  - 状態遷移は `open` から終端まで順に辿る必要はありません。人が対応した項目や、対話型 orchestrator がその場で処理した項目は、`start` を経ずに `close` / `reject` して構いません。着手を記録していない時点の遷移を後から補うと、実際には起きていない事実がイベントログに残ります。詳しい基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `中間状態を経ない終端` を参照します。
148
151
  - 直接終端させる場合は、誰がどの経路で対応したかを `register close --by <actor> --reason "<経路と根拠>"` で残します。exec 経由でないため plan / result / evidence が生成されず、実施内容と検証結果は個票の対応結果が唯一の記録になります。
149
152
  - agent へ実行させる項目は `exec run --register` を使います。この経路では runner が `start` と `wait` / `review` を記録し、plan / result / evidence も残ります。着手の記録が要る項目は、この経路を選びます。
150
- - 動いていない `open` や期限切れの項目は放置せず、期限の更新、優先度の見直し、`defer` / `reject` のいずれかへ整理します。ただし `note` の `open` は生きている記録を意味し、終端させません。対応・回答・判断が必要になった場合は、目的に合う別項目を起票します。
151
- - `waiting` へ移す理由は `register wait --reason "<理由>"` で個票 Frontmatter の `block_reason` に記録します。これは途中経過であり、終端時の結論を表す `conclusion` は変更しません。旧 `--conclusion` も互換性のため受け付けますが、記録先は `block_reason` です。
153
+ - 動いていない `open` や期限切れの項目は放置せず、期限の更新、優先度の見直し、`defer` / `reject` のいずれかへ整理します。ただし `note` の `open` は生きている記録を意味し、終端させません。`register close` / `register reject` / `register defer` は `note` をエラー終了し、対応・回答・判断が必要な場合は、目的に合う別項目の起票を案内します。
154
+ - `waiting` へ移す理由は `register wait --reason "<理由>"` で個票 Frontmatter の `block_reason` に記録します。これは `waiting` 中だけの現在値であり、`start` / `review` / `close` などで別の状態へ遷移すると個票から削除されます。削除前の理由は項目別イベントログに残り、終端時の結論を表す `conclusion` は変更しません。旧 `--conclusion` も互換性のため受け付けますが、記録先は `block_reason` です。誤った現在値を状態遷移なしで削除する場合は `register update --block-reason -` を使います。
152
155
 
153
156
  すべての登録項目は個票(`pjr-XXXX-<topic>.md`)を持ちます。`close` / `reject` は処理状態の遷移とあわせて個票 Frontmatter の `status`(文書成熟度)も更新します。処理状態とは別の状態軸であり、遷移基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `個票 status の遷移基準` を正本とします。
154
157
 
@@ -159,6 +162,18 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
159
162
 
160
163
  - 変更前に確認したい場合は `--dry-run` を付けると、個票 Frontmatter の変更予定と再生成されるビューを表示します。
161
164
 
165
+ 記帳と commit を一つの操作として完了させる場合は、`add` / `update` / `renumber` と各状態遷移コマンドに `--commit` を付けます。
166
+
167
+ ```bash
168
+ specdojo register close \
169
+ --project <project-id> \
170
+ --id PJR-0005 \
171
+ --conclusion "取消処理で在庫数を戻すよう修正" \
172
+ --commit
173
+ ```
174
+
175
+ `--commit` は register の worktree 実行の記帳・統合と同じ `register lifecycle` 枠が空くまで待ち、枠の内側で記帳、`register build` 相当の検証・再生成、commit を順に行います。commit 対象はそのコマンドが新たに変更した個票・event・参照文書だけで、開始前からあるほかの未 commit 変更は残します。対象個票やevent自体に開始前の変更がある場合は、既存差分を混ぜないため書き込み前に停止します。既定の件名は `docs(register PJR-XXXX): <command> <title>` で、`-m <message>` または `--message <message>` で上書きできます。`--dry-run` と同時に指定した場合は表示だけを行い、枠の取得と commit は行いません。
176
+
162
177
  ### 2.2. 個票の作成
163
178
 
164
179
  すべての登録項目は、type 別のテンプレート(`pjr-todo-template.md` など `pjr-<type>-template.md`)から作る個票です。`register add` は個票の Frontmatter に構造化フィールドを書き込み、H1 と本文にタイトル・説明を置きます。
@@ -289,13 +304,13 @@ specdojo register history --project <project-id> --since 2026-08-01 --json
289
304
  2026-08-09T08:20:00Z reg_cd2 PJR-0012 updated status: review -> done; completed: - -> 2026-08-09 # close by PO: accepted
290
305
  ```
291
306
 
292
- - `register add`、状態遷移、`register update`、`register renumber` は、現在値を個票へ、event を項目別イベントファイルへ書き込みます。`--by` と `--reason` を指定すると actor と理由を明示できます。
307
+ - `register add`、状態遷移、`register update`、`register renumber` は、現在値を個票へ、event を項目別イベントファイルへ書き込みます。`--by` と `--reason` を指定すると actor と理由を明示できます。記帳と再生成を `register lifecycle` 枠の内側で commit まで完了させる場合は `--commit` を付けます。
293
308
  - 一覧の列に現れない変更(対応結果本文の追記、個票 `status` の昇格など)は event になりません。個票の全差分が必要な場合は `git log -p` を使います。
294
309
  - `--status-only` は追加・削除・状態遷移だけを残し、変更内容も遷移に関わる項目(`status` / `type` / `completed` / `conclusion`)へ絞ります。
295
310
  - `renumber` による ID 付け替えは、`id` の変更を含む `updated` イベントとして現れます。
296
311
  - 複数の遷移を1コミットへまとめたり squash したりしても、項目別イベントファイルに残る各 event の発生日時・actor・変更内容は失われません。`register start` を含む遷移時の commit policy は別の運用判断です。
297
312
  - 個票とイベントログはそれぞれ一時ファイルを同一ディレクトリで完成させてから置換します。同じ現在値への再実行は event を増やさず、`register build` がファイルの 1 対 1 対応、イベント ID・直前参照・状態連鎖・最新状態を検証するため、中断による片側だけの更新も検出できます。
298
- - 異なる項目の並行実行は別の個票とイベントファイルへ書くため共有ログ競合を起こしません。同じ項目を複数 worktree で変更した場合は項目別イベントファイルの競合として統合を止め、片方の event を削除せず再実行または手動統合します。
313
+ - 異なる項目の並行実行は別の個票とイベントファイルへ書くため共有ログ競合を起こしません。同じ項目を複数 worktree で変更してイベントファイルが競合した場合は、統合時に両側のイベントの和集合で解決します。
299
314
  - exec event と共通化するのは UTC 秒精度、version、actor、reason、追記・検証の原則です。exec は task state の SSOT で 1 event 1 JSON、Register は現在値を個票に維持し項目別 YAML 配列を監査履歴とするため、保存形式と fold 処理は共通化しません。
300
315
  - 生成物(`generated/` 配下)は追跡対象外のため、PR の差分にも Git 履歴にも現れません。レビュー対象は個票と `events/` 配下の項目別ログです。
301
316
  - 既存プロジェクトは移行前でも動作し、event のない個票は Git 履歴から再構成します。`register migrate --dry-run` で件数を確認し、`register migrate` で復元可能な Git 履歴を決定的な event ID へ変換します。浅い clone などで履歴が不足する場合は無理に合成せず Git フォールバックを維持します。
@@ -338,8 +353,8 @@ specdojo exec run --project <project-id> --register PJR-0012
338
353
  # 複数項目を指定順に直列実行する(成功IDごとにcommit、途中失敗でも継続)
339
354
  specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --register-commit --on-failure continue
340
355
 
341
- # 成果物を worktree に隔離して実行し、統合ブランチへ merge back する
342
- specdojo exec run --project <project-id> --register PJR-0012 --worktree
356
+ # 設定に関係なく、現在の作業ツリーで明示的に実行する
357
+ specdojo exec run --project <project-id> --register PJR-0012 --in-place
343
358
 
344
359
  # worktree 隔離のまま複数項目を並列実行する
345
360
  specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree --parallel 2
@@ -347,13 +362,15 @@ specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree
347
362
 
348
363
  - type が `todo` / `issue` / `change-request` の項目は成果物・実装を変更する対応、`question` / `risk` の項目は調査して結論案を result に記録する対応になります。`decision` / `note` は実行対象外です。
349
364
  - 状態は register の遷移(`in-progress` / `review` / `waiting`)で追跡され、agent は項目を終端化しません。成功後は人が内容を確認して `register close` します。
350
- - 個票の「関連ドキュメント」に `[[文書ID]]` 形式で記載された対象成果物は、plan 生成時に直近の自動評価(grade)結果があれば `_GRADE_FINDINGS_` として plan に展開されます。表示は最大10文書・各20件までに制限され、超過分はサイドカーを参照するよう促します。サイドカーがない場合は「finding なし」と表示されます。
365
+ - 個票 Frontmatter の `targets` に宣言した変更対象文書は、plan 生成時に直近の自動評価(grade)結果があれば `_GRADE_FINDINGS_` として plan に展開されます。`targets` がない場合は finding を展開しません。「関連ドキュメント」は根拠や参考への導線であり、そこに wikilink があるだけでは解消対象になりません。表示は最大10文書・各20件までに制限され、超過分はサイドカーを参照するよう促します。サイドカーがない場合は「finding なし」と表示されます。
351
366
  - `--register` には複数の PJR-ID を空白区切り・カンマ区切り(またはその混在)で渡せます。指定順に1件ずつ実行し、各IDが plan/result 生成・開始・agent実行・状態遷移まで完結してから次へ進みます。重複したIDは最初の1件だけを実行します。
352
367
  - 全ID処理後にID別の成否・状態遷移・commit 結果を一覧表示します。いずれかが失敗した場合は終了コード 1 で終了します。
353
- - `--register-commit` を付けると成功IDごとに、その実行で生じた変更だけをcommitします(実行前から作業ツリーにある利用者の変更は含めません)。`--on-failure`(`stop` 既定 / `continue`)で途中失敗時に停止するか継続するかを選びます。`stop` では失敗以降のIDが skipped として記録されます。
354
- - 既定は in-place の直列実行で、変更は作業ツリーに残ります(`--register-commit` を付けると commit します)。
355
- - `--worktree` を付けると、成果物の変更を git worktree に隔離して実行し、成功時に統合ブランチへ merge back します。task worktree では root と package-lock 付き独立 package ごとに `npm ci` を実行し、書き込み可能な独立 `node_modules` を準備してから agent を起動します。成功時の `start → review`、plan、result、成果物は `exec(register <PJR-ID>): <title>` の merge commit に同梱され、統合ブランチの first-parent には1項目1commitだけが増えます。失敗時は `start → waiting` と plan / result を `exec(register <PJR-ID>): wait` commit 1件にまとめ、worktree を保持します。`--resume` で再開した場合の `start` 遷移も exec branch 側に記録され、成功時は merge commit 1件、再び失敗した場合は `wait` commit 1件になります。worktree モードは常に commit するため `--register-commit` は無視されます(指定すると注記を表示します)。
356
- - `--worktree` と併用する場合に限り `--parallel <n>` で複数項目を並列実行できます。状態遷移は直列化され、成果物は項目ごとの worktree に隔離されます。`--parallel` を単独(`--worktree` なし)で指定するとエラーになります。失敗時は当該項目の worktree を保持します(調査・再実行のため)。
368
+ - `--register-commit` を付けると成功IDごとに、その実行で生じた変更だけをcommitします(実行前から作業ツリーにある利用者の変更は含めません)。commit subject は `exec(register <PJR-ID>): <title>` とし、commitlint の100文字上限を超える場合は末尾を `…` に置き換えて100文字へ切り詰めます。`--on-failure`(`stop` 既定 / `continue`)で途中失敗時に停止するか継続するかを選びます。`stop` では失敗以降のIDが skipped として記録されます。
369
+ - 実行場所の既定は `.specdojo/exec-defaults.yaml` の `run.register_execution` で `worktree` / `in-place` を選びます。未設定の既存リポジトリは互換性のため in-place です。CLI の `--worktree` / `--in-place` は設定を上書きし、同時指定はエラーになります。
370
+ - worktree モードでは、成果物の変更を git worktree に隔離して実行し、成功時に統合ブランチへ merge back します。task worktree では root と package-lock 付き独立 package ごとに `npm ci` を実行し、書き込み可能な独立 `node_modules` を準備してから agent を起動します。成功時の `start → review`、plan、result、成果物は `exec(register <PJR-ID>): <title>` の merge commit に同梱され、統合ブランチの first-parent には1項目1commitだけが増えます。失敗時は `start → waiting` と plan / result を `exec(register <PJR-ID>): wait` commit 1件にまとめ、worktree を保持します。`--resume` で再開した場合の `start` 遷移も exec branch 側に記録され、成功時は merge commit 1件、再び失敗した場合は `wait` commit 1件になります。worktree モードは常に commit するため `--register-commit` は無視されます(指定すると注記を表示します)。
371
+ - worktree の準備時間が見合わない小さな作業で、失敗差分を現在の作業ツリーで直ちに整理できる場合だけ `--in-place` を明示します。in-place は直列実行で、変更を作業ツリーへ残します。`--register-commit` を付けると成功IDごとに commit しますが、`--resume` / `--force-restart` / `--join` と `--parallel` は使えません。
372
+ - worktree モードに限り `--parallel <n>` で複数項目を並列実行できます。状態遷移は直列化され、成果物は項目ごとの worktree に隔離されます。親 runner の検証(`pipeline.parent_validations`)も既定では 1 項目ずつ直列に実行され、executor と reporter だけが並列に動きます(同時数は `pipeline.parent_validation_concurrency` で変更できます)。in-place モードで `--parallel` を指定するとエラーになります。失敗時は当該項目の worktree を保持します(調査・再実行のため)。
373
+ - `--worktree` の実行中に別の項目を後から並行させる場合は、後から起動する run に `--join` を付けます(例: `exec run --register <PJR-ID> --worktree --join`)。状態遷移・統合・生成物の再生成、provider の `max_concurrency`、親検証の枠は、合流した run を跨いで統制されます。同時に動かせる run の数は `run.max_concurrent_runs`(既定 4)で、使用中の枠は `exec slots` で確認できます。詳細は [exec運用ガイド](exec-operation-guide.md) の「実行中の register worktree 実行へ後から合流する」を参照してください。
357
374
  - 実行せずに plan の内容だけ確認したい場合は `exec plan --register <PJR-ID>` を使います。
358
375
  - open な項目の定期スイープなど、時刻条件で繰り返す場合は routine(`rtn-*.yaml`)を使います。
359
376
 
@@ -0,0 +1,264 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:release-v0-3-0-migration-guide
4
+ type: guide
5
+ status: draft
6
+ ---
7
+
8
+ # v0.3.0 移行ガイド
9
+
10
+ Migration Guide for v0.3.0
11
+
12
+ SpecDojo v0.2.1 から v0.3.0 へ更新するときに、利用者側の設定、overlay、コピー済みの実行
13
+ テンプレート、既存の grade 結果を移行する手順を示します。既定値をそのまま参照している
14
+ プロジェクトでは、依存 package の更新と検証だけで移行できます。
15
+
16
+ **対象読者**
17
+
18
+ - v0.2.1 のレビュー観点を overlay しているプロジェクトの管理者
19
+ - SpecDojo の kata または実行テンプレートをリポジトリへコピーして保守している利用者
20
+ - v0.2.1 以前の grade 結果を保持している利用者
21
+
22
+ **この文書で分かること**
23
+
24
+ - レビュー観点、rubric、review verdict とテンプレートの旧値・新値の対応
25
+ - overlay、コピー済みテンプレート、既存 grade 結果の移行手順
26
+ - 複数リポジトリ構成の変更点と、プロダクトリポジトリを exec の対象にする手順
27
+ - 移行後の検証方法と、人が行う公開作業の境界
28
+
29
+ **次に読む文書**
30
+
31
+ - 変更の一覧は、リポジトリ直下(npm package にも同梱)の `CHANGELOG.md` を参照してください。
32
+ - 現行の grade と review の分担は [[specdojo:review-guide|レビューガイド]] を参照してください。
33
+ - overlay の規則は同ガイド、kata の参照状態は
34
+ [[specdojo:command-reference|CLIコマンドリファレンス]]を参照してください。
35
+
36
+ ## 1. 更新前に確認する
37
+
38
+ **実行環境の更新:**
39
+ SpecDojo 本体、docs-site、docs-lint の実行には Node 22.13 以上が必要になりました。
40
+ Node のバージョンが要件を満たしているか確認し、必要に応じて更新してください。
41
+
42
+ 作業中の plan / result がない状態で更新し、利用リポジトリの変更を commit してから始めます。
43
+ 次のファイルや記録を変更している場合は、移行対象です。
44
+
45
+ | 対象 | 確認箇所 | 必要な対応 |
46
+ | -------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
+ | レビュー観点の overlay | project の `viewpoints_path` | `evaluation`、`continuous`、rubric、verdict を更新する |
48
+ | コピー済み kata | `npx specdojo kata status` | v0.3.0 の package 原本との差分を確認する |
49
+ | コピー済み実行テンプレート | `docs/ja/specdojo/exec-templates/` | review テンプレートを同期し、削除済みファイルを除く |
50
+ | 既存 review plan | `execution/exec/plans/` | 未着手の review plan を更新後に再生成する |
51
+ | 既存 grade 結果 | grade result サイドカー | rubric v2 で再評価する |
52
+ | 登録簿の `note` の扱い | `note` を close する運用や script | `register close` / `reject` / `defer` が `note` を拒否するため、`open` のまま追記する運用へ改める |
53
+ | `Refs:` で履歴を引く script | commit message を検索する処理 | `Refs: <project-id>:<item-id>` の修飾形も検索の対象にする |
54
+ | プロダクトリポジトリの変更 | 項目を分けるか人が統合している運用 | 必要に応じて `repos` を宣言し、`exec run --worktree` の統合へ移す |
55
+ | routine が起動する Job の出力 | 作業場所に残った出力を人が commit する運用 | 統合前に review する Job は `job-*.yaml` に `task.review` を宣言し、必要なら `task.review.agent` で review agent を指名する。routine の `action.commit` は互換のため読まれるが推奨しない |
56
+ | コピー済みの共通規約テンプレート | `xep-common-conventions-template.md` | 作業用のファイルを `tmp/` かリポジトリ外へ置く規則を同期する。`tmp/` 配下は commit 対象から除外される |
57
+ | `.gitignore` | `config init` を再実行する運用 | 同じ意味の行がなければ `node_modules/` と生成物の行が追記されるため、追記内容を確認して commit する |
58
+
59
+ 依存 package を更新します。`@specdojo/docs-lint` は v0.3.0 の変更対象ではないため、利用中の
60
+ 版をそのまま使えます。docs サイトを直接利用している場合は `@specdojo/docs-site@0.2.0` へ
61
+ 更新します。
62
+
63
+ ```bash
64
+ npm install --save-dev specdojo@0.3.0
65
+ npm install --save-dev @specdojo/docs-site@0.2.0
66
+ ```
67
+
68
+ 2 行目は `@specdojo/docs-site` を導入している場合だけ実行します。
69
+
70
+ ## 2. `evaluation` を移行する
71
+
72
+ `evaluation` は判定主体ではなく、正しさを決める規準の所在を表す値になりました。旧値は
73
+ 自動変換されず、移行先を示すエラーで停止します。
74
+
75
+ | v0.2.1 | v0.3.0 | 移行規則 |
76
+ | --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
77
+ | `deterministic` | `deterministic` | 変更不要。schema や lint など機械可読な規則で判定する |
78
+ | `agent` | `referential` または `discretionary` | 原則は `referential`。明示された比較先がなく、十分性や粒度を判定者が決める場合は `discretionary` |
79
+ | `human` | `referential` または `discretionary` | 実行主体では決めない。`check` に比較先があれば `referential`、なければ `discretionary` |
80
+
81
+ 共通 28 観点を overlay している場合の対応は次のとおりです。表にない旧 `agent` は
82
+ `referential`、表にない旧 `human` は `discretionary` へ変更します。
83
+
84
+ | v0.3.0 の値 | 旧値から再分類する観点 |
85
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
86
+ | `discretionary` | `vp-arc-conciseness`、`vp-ux-user-flow`(旧 `agent`) |
87
+ | `referential` | `vp-po-purpose-alignment`、`vp-po-publication-accountability`、`vp-pm-dependency-risk`、`vp-pm-control-reporting`、`vp-dev-change-impact`、`vp-dev-testability`、`vp-ops-agent-boundary`(旧 `human`) |
88
+
89
+ 独自観点は、その `check` が「何と比較するか」を明示していれば `referential`、判定者が
90
+ 「必要な範囲」「使える粒度」などの規準を持ち込むなら `discretionary` とします。値だけを
91
+ 一括置換せず、観点ごとに判定してください。
92
+
93
+ ## 3. `continuous` と rubric を移行する
94
+
95
+ `continuous` は schema と共通 28 観点から削除されました。overlay 内に残っている
96
+ `continuous: true` / `continuous: false` をすべて削除してください。残した場合は、未知の
97
+ property として schema 検証に失敗します。grade の対象は `grade_targets` と
98
+ `document_kinds` で決まり、適用される 28 観点をすべて評価します。
99
+
100
+ rubric を overlay している場合は、package 同梱の
101
+ `docs/ja/specdojo/defaults/pm-review-viewpoints.yaml` を正として次を反映します。
102
+
103
+ | 項目 | v0.2.1 | v0.3.0 |
104
+ | ------------ | ------------------- | -------------------------------------------------------------------------------------- |
105
+ | rubric ID | `grade-rubric-v1` | `grade-rubric-v2` |
106
+ | category | 4 category | 9 category(`purpose`、`planning`、`business`、`implementation`、`operations` を追加) |
107
+ | weight | 共通の重み | `kata` と `deliverable` ごとの重み |
108
+ | `pass_score` | 70 | 75 |
109
+ | grade 対象 | `continuous` で選択 | 文書種別に適用される全観点 |
110
+
111
+ rubric v1 と v2 は評価する category が異なるため、score を時系列比較しません。旧 rubric の
112
+ 結果は次のコマンドで抽出し、通常の grade 実行経路で再評価します。結果の `rubric` が現在の
113
+ ID と異なるもの、および ID の記録がないものが対象です。
114
+
115
+ ```bash
116
+ npx specdojo grade list --target kata --rubric-outdated --project <project-id>
117
+ npx specdojo grade list --target deliverable --rubric-outdated --project <project-id>
118
+ ```
119
+
120
+ `--rubric-outdated` と `--ungraded` は併用できません。結果がない文書は `--ungraded`、旧 rubric
121
+ の結果がある文書は `--rubric-outdated` で別々に選びます。
122
+
123
+ ## 4. review の verdict を移行する
124
+
125
+ review が表すのは成果物の品質ではなく、タスクの完了可否です。grade の文書 verdict
126
+ (`pass` / `needs-work` / `fail`)は別の語彙であり、変更しません。
127
+
128
+ | v0.2.1 の review 値 | v0.3.0 の verdict | 補足 |
129
+ | ------------------- | ------------------------------------------------------------- | --------------------------------------------- |
130
+ | `pass` | `complete` | 完了条件を満たし、完了を妨げる finding がない |
131
+ | `conditional_pass` | `complete-with-findings` | finding はあるがタスクは完了できる |
132
+ | `changes_requested` | `incomplete` | plan または完了条件に未充足がある |
133
+ | `blocked` | `grade-stale` / `grade-unavailable` / `changed-during-review` | 保留理由に応じて選ぶ |
134
+ | `approve` | `complete` または `complete-with-findings` | finding が完了を妨げるかで選ぶ |
135
+ | `revise` / `reject` | `incomplete` | 未充足事項と改善指示を記録する |
136
+
137
+ `blocked` は一括置換できません。grade が古い場合は `grade-stale`、評価不能なら
138
+ `grade-unavailable`、review 中に対象が変わった場合は `changed-during-review` とします。
139
+ `verdict_definitions`、rubric の `review_verdict`、独自 reporter の出力に旧値が残ると、移行先を
140
+ 示すエラーで停止します。
141
+
142
+ ## 5. review テンプレートと既存 plan を移行する
143
+
144
+ v0.3.0 の review は grade の結果を確定済みの入力として使い、観点ごとの
145
+ `pass` / `fail` / `unclear` を付け直しません。次の変更をローカルコピーへ反映します。
146
+
147
+ - `xrp-*` は「評価結果」と `done_criteria` を入力に、タスクの完了可否を判断する構成へ
148
+ 更新する。
149
+ - `xrr-template.md` は `grade_check`、`rationale`、`improvements`、`approach`、`verdict` を
150
+ 記録する構成へ更新する。
151
+ - 共通の判断手順は `xep-common-conventions-template.md` の review 専用節と同期する。
152
+ - `xrp-viewpoint-detail-template.md` と `xrr-viewpoint-detail-template.md` を削除し、参照も除く。
153
+
154
+ 実行テンプレートと schema は CLI と同じ版で使う必要があるため、現在は個別 eject の対象では
155
+ ありません。過去にソース一式をコピーした、または独自に上書きした場合は、次の表示内容と
156
+ ローカルファイルを比較し、上記の変更を手動で同期するかローカルコピーを除いて package 原本を
157
+ 参照します。
158
+
159
+ ```bash
160
+ npx specdojo kata show xrp-template
161
+ npx specdojo kata show xrr-template
162
+ npx specdojo kata status --kind exec-template
163
+ ```
164
+
165
+ 改訂前に生成した未着手の review plan は観点別評価を指示したままなので、v0.3.0 への更新後に
166
+ 再生成します。進行中の review は新旧の指示を混在させず、いったん中止して grade の鮮度を確認し、
167
+ 新しい plan から再開してください。
168
+
169
+ ## 6. 複数リポジトリ構成へ移行する
170
+
171
+ v0.3.0 では、1 つの項目でプロジェクトリポジトリと複数のプロダクトリポジトリを変更し、
172
+ `exec run --worktree` で統合できるようになりました。`repos` を宣言しない project の
173
+ worktree の配置、commit、統合は v0.2.1 と同じです。宣言しない場合の変更点は、
174
+ `exec run --register` がプロジェクト側の merge commit に付ける `Refs:` の書式だけです。
175
+
176
+ | 項目 | v0.2.1 | v0.3.0 |
177
+ | ------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
178
+ | プロジェクト側の merge commit の Refs | `Refs: <item-id>` | `Refs: <project-id>:<item-id>` |
179
+ | プロダクトリポジトリの変更 | exec の対象外(項目を分けるか人が統合する) | project の `repos` に宣言したリポジトリを、同じ項目で変更・統合する |
180
+ | `targets`・`paths` | doc id または SpecDojo ルート相対のパス | 加えて `<repo>:<path>` でプロダクトリポジトリのパスを指定できる |
181
+ | task の worktree | `<worktree_base>/<task-id>/` | `repos` を宣言した project だけ `<task-id>/project/` と `<task-id>/<name>/` に分かれる |
182
+ | 親検証 | ID の配列をプロジェクトリポジトリで実行する | 要素に `{ id, repo }` を書き、リポジトリを割り当てられる |
183
+ | result | 本文の構成は変わらない | `repos` を宣言した project の register 項目は「トレーサビリティ」の章を末尾に持つ |
184
+
185
+ 過去の commit の `Refs: <item-id>` は書き換えません。履歴を検索する script は、修飾形と
186
+ 修飾なしの両方を対象にします。
187
+
188
+ ```bash
189
+ git log <target-branch> -E --grep='^Refs: (<project-id>:)?<item-id>$' --format='%H %s'
190
+ ```
191
+
192
+ プロダクトリポジトリを exec の対象にする場合は、次の順で移行します。
193
+
194
+ 1. 作業中の項目がない状態で、`.specdojo/specdojo.config.json` の project に `repos` を追加する。
195
+ 書き方と検証規則は [[specdojo:specdojo-config-reference|specdojo.config.json リファレンス]]
196
+ の「`repos`のキー」を参照する。
197
+ 2. プロダクトリポジトリで実行する親検証があれば、`.specdojo/exec-defaults.yaml` の
198
+ `pipeline.parent_validations` に `{ id, repo }` を追加し、プロダクト側の `package.json` に
199
+ 同じ名前の npm script を用意する。詳細は [[specdojo:exec-config-guide|exec設定ガイド]] を
200
+ 参照する。
201
+ 3. プロダクトを変更する項目の `targets` に `<repo>:<path>` を書く。プロダクト文書は doc id では
202
+ 参照できないため、パスで指定する。
203
+ 4. executor に使う provider を確認する。claude・codex・antigravity・copilot は runner が
204
+ プロダクト worktree への書き込み許可を起動引数へ付け足す。opencode は agent 定義の
205
+ `permission.external_directory` で作業ディレクトリ外を拒否するため、そのままでは
206
+ プロダクト worktree へ書き込めない。
207
+ 5. `exec worktree prepare` などの分割コマンドで手動運用している場合は、プロダクト側の統合を
208
+ `exec run --worktree` へ移す。分割コマンドはプロダクト側を統合しない。
209
+
210
+ 統合の順序、失敗時の部分状態、再開は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]]
211
+ の「別リポジトリ構成」を参照してください。
212
+
213
+ ## 7. agent 名簿を保護設定へ移行する
214
+
215
+ agent 定義は project ごとの `pm-members.yaml` から、repository 共通の `.specdojo/agent-members.yaml` へ移りました。`pm-members.yaml` に `type: agent` が残っていると、読み込みはファイルと nickname を示して停止します。
216
+
217
+ 1. 作業中の agent 実行がないことを確認します。
218
+ 2. `npx specdojo config migrate-members --dry-run` で、各 project から移す件数と出力先を確認します。
219
+ 3. 人間または orchestrator が `npx specdojo config migrate-members` を実行します。agent 自身には `.specdojo/**` の変更を許可しません。
220
+ 4. 出力先を変える場合は、`.specdojo/specdojo.config.json` のトップレベルへ `"agent_members_path": ".specdojo/<name>.yaml"` を追加します。
221
+ 5. `pm-members.yaml` に人間だけ、agent 定義ファイルに agent だけが残り、nickname が両者で重複しないことを確認します。
222
+
223
+ 複数 project の同名 agent は repository 共通定義へ1件だけ統合する必要があります。移行コマンドが重複を報告した場合は、自動で上書きせず、どの定義を正本にするか人間が決めてから再実行してください。
224
+
225
+ ## 8. 移行を検証する
226
+
227
+ overlay を含む設定と、生成される plan / result を検証します。
228
+
229
+ ```bash
230
+ npm run check
231
+ npm run docs:build
232
+ ```
233
+
234
+ エラーが出た場合は、最初のエラーに含まれる旧値と移行先を確認します。代表的な原因は次の
235
+ とおりです。
236
+
237
+ | エラーの対象 | 修正 |
238
+ | ------------------------------------------- | --------------------------------------------------- |
239
+ | `evaluation: agent` / `evaluation: human` | 2 章の規準で `referential` / `discretionary` を選ぶ |
240
+ | `continuous` | 観点からフィールドを削除する |
241
+ | 旧 `verdict_definitions` / `recommendation` | 4 章の対応表で新 verdict へ移す |
242
+ | 旧 review plan の観点別結果 | plan を再生成し、最新 grade を入力にする |
243
+ | rubric v1 の score | `--rubric-outdated` で抽出して再評価する |
244
+
245
+ 検証後は、overlay と独自テンプレートの差分、再評価を後回しにした grade 結果の件数を移行記録へ
246
+ 残してください。
247
+
248
+ ## 9. リリース作業の境界
249
+
250
+ このリポジトリで v0.3.0 を公開する場合、agent の作業は版、リリース文書、移行ガイド、検証まで
251
+ です。次は maintainer が行います。
252
+
253
+ 1. develop から main への Pull Request で変更内容と検証結果を確認し、承認後に merge する。
254
+ merge だけでは公開もサイトの更新も起きない。
255
+ 2. 公開すると決めた時点で、main の昇格 merge commit に `v0.3.0` tag を付けて push する。
256
+ tag の push で publish workflow とサイトの deploy が起動する。
257
+ 3. publish workflow が作成した staged release を `npm stage list specdojo` で確認する。
258
+ 4. `npm stage download <stage-id>` で tarball を取得し、`CHANGELOG.md` と必要な package 内容を
259
+ 含むことを確認する。
260
+ 5. 2FA を使って `npm stage approve <stage-id>` を実行し、公開を確定する。
261
+ 6. GitHub Release を作成し、公開された package の版と一致することを確認する。
262
+
263
+ main への merge、tag の作成と push、npm の staged release の承認、GitHub Release の作成は
264
+ 自動実行しません。
@@ -49,6 +49,27 @@ SpecDojo は自律実行を前提とします。次の 2 つが作業端末の
49
49
 
50
50
  この文書では Tailscale + SSH + tmux + devcontainer の組み合わせを例にしますが、役割が満たせれば置き換えて構いません。
51
51
 
52
+ ### 2.1. Dev Container を生成する(任意)
53
+
54
+ 利用リポジトリに `.devcontainer/` がない場合は、指定した provider の CLI を含む最小構成を生成できます。まず dry-run で対象を確認します。
55
+
56
+ ```bash
57
+ npx specdojo devcontainer scaffold --provider claude,codex --dry-run
58
+ npx specdojo devcontainer scaffold --provider claude,codex
59
+ ```
60
+
61
+ 既存の `.devcontainer/` は通常実行では上書きしません。置き換える場合だけ `--force` を指定します。生成設定は provider の設定ディレクトリを名前付きボリュームへ保存し、ホストの認証情報・秘密鍵・`.env` は既定でマウントしません。Ollama 接続、コンテナ内の cron、コンテナ内の tmux が必要な場合だけ `--ollama`、`--cron`、`--tmux` を追加します。本書の構成図のようにホスト側の tmux でコンテナ自体を包む場合、`--tmux` は不要です。
62
+
63
+ 生成する `devcontainer.json` は、利用リポジトリ単体ではなく、その親ディレクトリを `/workspaces/specdojo-workspace` へマウントします。別リポジトリ構成では `repos` の参照先(例: `../app1`)と `worktree_base`(例: `../app1-specdojo-worktrees`)が利用リポジトリの外にあるためです。これらの Git リポジトリと worktree は `safe.directory` の対象になります。一方、同じ親ディレクトリに置いたその他のファイルもコンテナから見えるため、秘密情報などコンテナへ公開しないファイルは別の場所へ置いてください。
64
+
65
+ 端末版 Emacs と TypeScript・Markdown・YAML・Bash の LSP 環境を追加する場合は `--editor emacs` を指定します。
66
+
67
+ ```bash
68
+ npx specdojo devcontainer scaffold --provider claude,codex --editor emacs
69
+ ```
70
+
71
+ 生成される `.devcontainer/emacs/init.el` は、`~/.emacs`、`~/.emacs.el`、`~/.emacs.d/init.el`、`~/.config/emacs/init.el` のいずれも無い場合だけコピーされます。空の `~/.emacs.d` があればその中の `init.el` へ、なければ `~/.config/emacs/init.el` へ配置し、配置先を出力します。初回作成前の既定値は生成されたテンプレートで変更でき、作成後は出力されたコピー先を編集します。dotfiles が設定を配置していれば上書きされません。
72
+
52
73
  ## 3. 構成例
53
74
 
54
75
  ```text
@@ -131,7 +152,7 @@ Host <ホスト名>
131
152
  LocalForward 5173 127.0.0.1:5173
132
153
  ```
133
154
 
134
- `LocalForward` はその設定を持つ SSH 接続にだけ有効です。tmux セッションへ直接入る接続用のエントリを別に作っている場合は、そちら側へ設定します。この方式は SSH 接続が張られている間有効で、エディタの起動有無に依存しません。
155
+ `LocalForward` は 1 行につき 1 ポートを転送します。開発サーバを複数使う場合は、公開したポートごとに 1 行ずつ書きます。`LocalForward` はその設定を持つ SSH 接続にだけ有効です。tmux セッションへ直接入る接続用のエントリを別に作っている場合は、そちら側へ設定します。この方式は SSH 接続が張られている間有効で、エディタの起動有無に依存しません。
135
156
 
136
157
  ### 6.2. 実行環境の起動に失敗する
137
158