specdojo 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +122 -1
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-handoff.js +336 -0
  15. package/dist/exec-parent-validation.js +317 -43
  16. package/dist/exec-pipeline-state.js +74 -9
  17. package/dist/exec-plans.js +115 -113
  18. package/dist/exec-protection-handoff.js +43 -2
  19. package/dist/exec-provider-scaffold.js +247 -15
  20. package/dist/exec-register-resume.js +65 -19
  21. package/dist/exec-register.js +9 -3
  22. package/dist/exec-repo-integration.js +811 -0
  23. package/dist/exec-repo-trace.js +182 -0
  24. package/dist/exec-reporter.js +613 -132
  25. package/dist/exec-results.js +81 -56
  26. package/dist/exec-run-lock.js +110 -107
  27. package/dist/exec-run.js +1585 -356
  28. package/dist/exec-shared.js +7 -0
  29. package/dist/exec-slot-lock.js +242 -0
  30. package/dist/exec-task-repos.js +415 -0
  31. package/dist/exec-trial.js +51 -25
  32. package/dist/exec-worktree-command.js +87 -43
  33. package/dist/exec-worktree-ops.js +502 -57
  34. package/dist/exec-worktree.js +114 -27
  35. package/dist/exec.js +13 -6
  36. package/dist/grade-result.js +128 -0
  37. package/dist/grade.js +809 -72
  38. package/dist/init-command.js +443 -0
  39. package/dist/job.js +160 -10
  40. package/dist/orchestrator.js +213 -0
  41. package/dist/register-event-merge.js +169 -0
  42. package/dist/register-item.js +7 -1
  43. package/dist/register.js +294 -86
  44. package/dist/review-grade.js +252 -0
  45. package/dist/review-plan.js +111 -1
  46. package/dist/review-types.js +40 -1
  47. package/dist/routine.js +72 -5
  48. package/dist/schedule-build.js +2 -2
  49. package/dist/schedule.js +17 -4
  50. package/dist/specdojo-config.js +465 -19
  51. package/dist/specdojo-gitignore.js +135 -0
  52. package/dist/specdojo.js +6 -0
  53. package/dist/viewpoint-document-kinds-check.js +128 -0
  54. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  55. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  56. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  57. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  58. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  59. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  60. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  61. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  62. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  63. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  65. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  67. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  68. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  69. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  70. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  71. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  72. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  73. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  74. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  75. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  76. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  77. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  78. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  79. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  80. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  81. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  82. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  83. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  84. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  85. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  86. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  87. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  88. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  89. package/docs/ja/specdojo/index.md +2 -2
  90. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  91. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  92. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  93. package/docs/ja/specdojo/references/command-reference.md +335 -92
  94. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  95. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  96. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  97. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  98. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  99. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  100. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  101. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  102. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  104. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  105. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  106. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  107. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  108. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  109. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  110. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  111. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  112. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  113. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  114. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  115. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  116. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  117. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  118. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  119. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  120. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  121. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  122. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  123. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  124. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  125. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  126. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  127. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  128. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  129. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  130. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  131. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  132. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  133. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  134. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  135. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  136. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  137. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  138. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  139. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  140. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  141. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  142. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  143. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  144. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  145. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  146. package/package.json +15 -9
  147. package/templates/antigravity/README.md +27 -2
  148. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  149. package/templates/antigravity/exec-defaults-snippet.yaml +7 -6
  150. package/templates/antigravity/orchestrator.md +18 -7
  151. package/templates/antigravity/settings.global.json +55 -0
  152. package/templates/claude/agents/claude-executor.md +14 -0
  153. package/templates/claude/agents/claude-reporter.md +16 -0
  154. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  155. package/templates/claude/settings.edit.json +27 -1
  156. package/templates/codex/README.md +5 -4
  157. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  158. package/templates/codex/orchestrator.md +18 -7
  159. package/templates/copilot/README.md +7 -5
  160. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  161. package/templates/devcontainer/devcontainer.json +27 -0
  162. package/templates/devcontainer/emacs/init.el +88 -0
  163. package/templates/devcontainer/post-create.sh +62 -0
  164. package/templates/init-agent-members.yaml +200 -0
  165. package/templates/init-exec-defaults.yaml +72 -0
  166. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  167. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  168. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -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