specdojo 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -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
+ 自動実行しません。
@@ -0,0 +1,184 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:remote-host-development-guide
4
+ type: guide
5
+ status: draft
6
+ ---
7
+
8
+ # 常時稼働ホスト運用ガイド
9
+
10
+ Remote Host Development Guide
11
+
12
+ agent の実行を止めずに開発を続けるため、常時稼働するホストへリモート接続して作業する構成例を示します。この文書は特定の製品構成を推奨するものではなく、**構成例**です。
13
+
14
+ **対象読者**
15
+
16
+ - `routine` の定期実行や長時間の `exec run` を、作業端末の状態に依存せず継続したい開発者
17
+
18
+ **この文書で分かること**
19
+
20
+ - なぜ常時稼働ホストが要るか、どの部分がどの機能に対応するか、切断と再接続の扱い
21
+
22
+ **次に読む文書**
23
+
24
+ - 定期実行の設定は [routine運用ガイド](routine-operation-guide.md)、agent の実行設定は [exec設定ガイド](exec-config-guide.md) を参照してください。
25
+
26
+ ## 1. なぜ常時稼働ホストが要るか
27
+
28
+ SpecDojo は自律実行を前提とします。次の 2 つが作業端末の状態に依存します。
29
+
30
+ | 機能 | 依存 |
31
+ | -------------------------------- | ------------------------------------------------------------ |
32
+ | `routine`(`routine run --due`) | cron などの定期実行。ホストが動いていないと起動しない |
33
+ | `exec run` | 1 回あたり数分から数十分。完了前に端末が切断されると中断する |
34
+
35
+ ノート PC で作業する場合、蓋を閉じる、スリープする、移動する、といった操作で実行が止まります。作業端末とは別に、**動き続けるホストで実行する**構成にすると、この依存が切れます。
36
+
37
+ `exec run --worktree` は worktree を保持するため、中断しても `--resume` で再開できます。ただし再開の操作は人が行う必要があり、夜間の `routine` では翌朝まで止まります。
38
+
39
+ ## 2. 構成の要素
40
+
41
+ 次の 4 つを組み合わせます。いずれも SpecDojo の機能ではなく、一般的なツールです。
42
+
43
+ | 要素 | 役割 | 代替 |
44
+ | -------------------- | -------------------------- | ---------------------------------------------- |
45
+ | 常時稼働ホスト | 実行の場所 | 手元のデスクトップ、自宅サーバ、クラウドの VM |
46
+ | ネットワーク到達手段 | 外出先からホストへ接続する | Tailscale、WireGuard、VPN、ポート開放 + 鍵認証 |
47
+ | 端末多重化 | 切断しても shell を保つ | tmux、GNU Screen、Zellij |
48
+ | 実行環境 | 依存とツールを固定する | devcontainer、ローカルの Node.js 環境 |
49
+
50
+ この文書では Tailscale + SSH + tmux + devcontainer の組み合わせを例にしますが、役割が満たせれば置き換えて構いません。
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
+
73
+ ## 3. 構成例
74
+
75
+ ```text
76
+ 作業端末(任意の場所)
77
+ └─ SSH(Tailscale などの到達手段)
78
+ └─ 常時稼働ホスト
79
+ └─ tmux セッション
80
+ └─ devcontainer
81
+ └─ specdojo exec run / routine
82
+ ```
83
+
84
+ 要点は、**SpecDojo の実行を tmux セッションの中で開始する**ことです。SSH が切れても tmux のセッションは残り、再接続して同じ状態へ戻れます。
85
+
86
+ ## 4. 切断と再接続
87
+
88
+ ### 4.1. セッションへ入る
89
+
90
+ 接続のたびに新規作成せず、既存があればそれへ入ります。
91
+
92
+ ```bash
93
+ tmux new-session -A -s specdojo
94
+ ```
95
+
96
+ `-A` は「あれば attach、なければ作成」です。セッション名を固定すると、複数端末から同じ場所へ戻れます。
97
+
98
+ ### 4.2. 実行はセッションの中で始める
99
+
100
+ ```bash
101
+ tmux new-session -A -s specdojo
102
+ npx specdojo exec run --project <project-id> --register <PJR-XXXX> --worktree
103
+ ```
104
+
105
+ エディタの統合ターミナルで直接実行すると、エディタの接続が切れた時点で終了する場合があります。長時間の実行は tmux の中で始めます。
106
+
107
+ ### 4.3. 切断された実行の扱い
108
+
109
+ 再接続しても、実行中だった処理が自動で再開されるわけではありません。
110
+
111
+ | 対象 | 再開方法 |
112
+ | -------------------------- | ------------------------------------------------------------ |
113
+ | `exec run --worktree` | `exec run --register <id> --resume --worktree` |
114
+ | agent CLI の対話セッション | CLI ごとの再開機能(会話履歴は各 CLI が保持する) |
115
+ | `routine` | 次の起動時刻を待つか、`routine run --id <id>` で明示実行する |
116
+
117
+ `exec run` は worktree と pipeline の状態を保持するため、executor が完了していれば reporter 段だけを再開できます。
118
+
119
+ ### 4.4. セッションが消える場合
120
+
121
+ 実行環境を作り直すとセッションも消えます。
122
+
123
+ | 操作 | tmux セッション |
124
+ | ------------------------ | --------------- |
125
+ | SSH の切断・再接続 | 残る |
126
+ | エディタの再接続 | 残る |
127
+ | コンテナの再起動・再作成 | **消える** |
128
+
129
+ コンテナを作り直す前に、実行中の処理がないことを確認します。
130
+
131
+ ## 5. 定期実行
132
+
133
+ `routine` はホスト側で動き続ける必要があります。cron を使う場合、実行環境の中で cron を動かし、コンテナ停止時に定期実行も止まることを前提にします。
134
+
135
+ ```cron
136
+ 0 * * * * cd /path/to/project && npx specdojo routine run --due >> /var/log/specdojo-routine.log 2>&1
137
+ ```
138
+
139
+ 設定の詳細は [routine運用ガイド](routine-operation-guide.md) を参照してください。取りこぼした実行枠の扱い(`missed_run`)と重複起動の扱い(`overlap`)は routine 定義で指定します。
140
+
141
+ ## 6. 既知の制限
142
+
143
+ ### 6.1. 入れ子のリモート接続でポート転送が届かない
144
+
145
+ 「作業端末 → SSH → ホスト → コンテナ」という入れ子構成では、エディタが動的に張るポート転送が作業端末まで届かないことがあります。エディタ側の転送機能は、エディタを起動している接続にのみ有効なためです。
146
+
147
+ 対処として、コンテナ側で固定ポートを公開し、SSH の local forwarding で転送します。
148
+
149
+ ```text
150
+ # ~/.ssh/config
151
+ Host <ホスト名>
152
+ LocalForward 5173 127.0.0.1:5173
153
+ ```
154
+
155
+ `LocalForward` は 1 行につき 1 ポートを転送します。開発サーバを複数使う場合は、公開したポートごとに 1 行ずつ書きます。`LocalForward` はその設定を持つ SSH 接続にだけ有効です。tmux セッションへ直接入る接続用のエントリを別に作っている場合は、そちら側へ設定します。この方式は SSH 接続が張られている間有効で、エディタの起動有無に依存しません。
156
+
157
+ ### 6.2. 実行環境の起動に失敗する
158
+
159
+ SSH 経由の非対話シェルでは `PATH` が対話シェルと異なることがあり、コンテナ起動用のコマンドが見つからない場合があります。接続元から次を実行して確認します。
160
+
161
+ ```bash
162
+ ssh <ホスト名> 'printf "PATH=%s\n" "$PATH"; command -v node || true'
163
+ ```
164
+
165
+ ## 7. 運用上のセキュリティ
166
+
167
+ この構成は、常時稼働ホストを外部から到達可能にします。次を守ります。
168
+
169
+ - ネットワーク到達手段は認証付きのものを使う。SSH を公開する場合は鍵認証のみとし、パスワード認証を無効にする。
170
+ - API key、SSH 秘密鍵、tailnet 名などをターミナルの scrollback やコマンド履歴へ残さない。
171
+ - agent の認証状態は秘密情報として扱う。リポジトリや設定ファイルへ書かない。
172
+ - agent の権限を広げる指定(全ツール許可、権限確認の省略、完全アクセス)は通常運用で使わない。境界は worktree、保護設定、commit 許可リストで作る。詳細は [exec設定ガイド](exec-config-guide.md) を参照してください。
173
+
174
+ 常時稼働させる以上、ホスト自体の更新と監視は利用者の責任範囲です。
175
+
176
+ ## 8. この構成を採らない選択
177
+
178
+ 常時稼働ホストは必須ではありません。次の場合は不要です。
179
+
180
+ - `routine` を使わず、`exec run` を都度実行する
181
+ - 実行のたびに完了まで端末を開いたままにできる
182
+ - `register` だけを使い、agent 実行を行わない
183
+
184
+ `register` の起票・状態遷移・生成物の再構築はいずれも短時間で完了するため、この構成を前提としません。