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
package/README.md CHANGED
@@ -1,13 +1,22 @@
1
1
  # SpecDojo
2
2
 
3
- SpecDojo は、仕様駆動開発のためのドキュメントフレームワークです。
4
- プロダクトの構築・改修に必要な情報を体系化し、人と生成 AI が同じ成果物を作成・検証・更新できるようにします。
3
+ SpecDojo は、仕様道(Spec-Dō)の道場です。
4
+ 仕様と設計を作り、運用まで保つための体系を整えます。判断を記帳し、型に沿って実戦で書き、評定で鍛え続け、講評で完了を判断します。人と生成 AI が同じ成果物を作成・検証・更新できるようにし、仕様駆動開発のツールに対しては、その上流で仕様と設計の体系を担います。
5
5
 
6
- **登録簿ひとつから始められます。** 設定 2 行で使い始め、必要になった分だけ広げられます。
6
+ **記して、形にして、磨き続ける。**
7
+
8
+ **記帳ひとつから始められます。** 設定 2 行で使い始め、必要になった分だけ広げられます。
9
+ 迷いを question として起票し、decision で決め、仕様書に書き、後日 change-request で直すまでを 10 分で体験できます。kata(型)を事前に用意する必要はありません。手順は [Quick Start ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/quick-start-guide.html) 冒頭の「10分で体験する — 仕様の判断台帳」を参照してください。
10
+
11
+ | 道場の言葉 | SpecDojo の仕組み |
12
+ | ---------- | ------------------------------------------------------------------------------------------------------- |
13
+ | 型(Kata) | 成果物の作り方を定める rulebook・recipe・sample・template |
14
+ | 技(Waza) | `specdojo` CLI。決定を残す記帳、成果物を作る実戦、品質を見る評定、完了を見る講評 |
15
+ | 流(Ryu) | 成果物・型・技をつなぐ `approach`。タスクごとに型をどこまで基準にして技を使うか(守・破・離など)を表す |
7
16
 
8
17
  ## できること
9
18
 
10
- ### 気づいたことを、型に沿って残せる
19
+ ### 記帳 — 気づいたことを、型に沿って残せる
11
20
 
12
21
  作業だけでなく、判断・保留・観測・リスク・変更要求も同じ登録簿へ記録します。種別を選ぶと
13
22
  本文の章構成が与えられるため、「選択肢を比較して理由を書く」といった記録が形を保ちます。
@@ -20,10 +29,16 @@ SpecDojo は、仕様駆動開発のためのドキュメントフレームワ
20
29
  調査や議論の内容がそのまま個票の本文になるため、別途まとめ直す必要がありません。
21
30
  状態を変える操作は実行前に提示して承認を求め、`git push` や破壊的操作は行いません。
22
31
 
23
- ### 必要になったら、成果物の型へ広げられる
32
+ ### 型と実戦 — 必要になったら、成果物の型へ広げられる
24
33
 
25
34
  要件、設計、テスト、運用まで 100 種類以上の記述規則・手順・テンプレート・サンプルを持ちます。
26
- 使うものだけをカタログで宣言し、型に沿って作れます。最初から全部を用意する必要はありません。
35
+ 使うものだけをカタログで宣言し、型に沿った実戦で成果物を作れます。最初から全部を用意する必要はありません。
36
+
37
+ ### 評定と講評 — 品質評価と完了判断を分けて残せる
38
+
39
+ `grade` は成果物の品質を共通の観点で評価し、`review` はその結果と実行記録・完了条件を照合して、タスクを完了してよいかを判断します。品質の finding とタスクの未充足事項を混同せず、最終的な `ready` への確定は人が行います。
40
+
41
+ v0.3.0 の `grade` は試験的な機能です。npm package では `grade list` / `plan` / `apply` / `validate` / `result` などの部品を利用できますが、これらを通しで実行する SpecDojo 本体リポジトリの開発用スクリプト `tools/grade/run-per-document.sh` は package に含まれません。成果物を評価するには、project の `catalog_path` も設定してください。1 文書を部品で評価する手順は [CLI コマンドリファレンス](docs/ja/specdojo/references/command-reference.md#81-npm-package-で-1-文書を評価する)を参照してください。
27
42
 
28
43
  日本語ドキュメントは [SpecDojo ドキュメントサイト](https://specdojo.github.io/specdojo/ja/) で公開しています。
29
44
 
@@ -34,14 +49,29 @@ SpecDojo は、仕様駆動開発のためのドキュメントフレームワ
34
49
 
35
50
  ## 使い始める
36
51
 
52
+ 現在の変更点は [CHANGELOG](CHANGELOG.md) にまとめています。v0.2.1 から更新する場合は、
53
+ レビュー観点、rubric、review テンプレートに互換性のない変更があるため、
54
+ [v0.3.0 移行ガイド](docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md)を先に確認してください。
55
+
37
56
  ### npm で導入する
38
57
 
39
- 既定では、プロダクトリポジトリ `app1/` の隣に SpecDojo 専用リポジトリ
40
- `app1-specdojo/` と worktree 用ディレクトリ `app1-worktrees/` を置く Detached Unit で始めます。
41
- workspace 直下で次を実行します。
58
+ 既定では、SpecDojo の記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
59
+
60
+ - **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
61
+ - **プロジェクトリポジトリ** `app1-specdojo/`: 登録簿・計画・実行記録などのプロジェクトドキュメントと、文書の作り方を定める型(Kata)を置きます。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。
62
+ - **worktree 用ディレクトリ** `app1-specdojo-worktrees/`: タスクごとの変更を隔離して進めるために、Git worktree を作る場所です。名前はプロジェクトリポジトリのディレクトリ名から決まります。
63
+
64
+ ```text
65
+ app1-workspace/
66
+ ├── app1/ # プロダクトリポジトリ
67
+ ├── app1-specdojo/ # プロジェクトリポジトリ
68
+ └── app1-specdojo-worktrees/ # タスクごとの作業場所
69
+ ```
70
+
71
+ `app1-workspace/` 直下で次を実行します。
42
72
 
43
73
  ```sh
44
- mkdir app1-specdojo app1-worktrees
74
+ mkdir app1-specdojo
45
75
  git -C app1-specdojo init
46
76
  cd app1-specdojo
47
77
  npm init -y
@@ -49,40 +79,50 @@ npm install --save-dev specdojo @specdojo/docs-lint
49
79
  npx specdojo config init
50
80
  ```
51
81
 
52
- SpecDojo は文書と実行管理のためのツールで、成果物へ同梱されるものではないため `--save-dev` で導入します。あわせて、kata は `node_modules/specdojo` から参照されるため、`package-lock.json` が kata の版も固定します。グローバル導入(`npm install -g`)では版がプロジェクトに記録されず再現できません。
82
+ SpecDojo は開発時に使う文書・実行管理ツールなので、`--save-dev` で導入します。kata は、成果物を書くための規則・手順・テンプレート・サンプルの総称です。kata もインストールした package から参照されるため、`package-lock.json` によって SpecDojo と同じ版へ固定されます。
53
83
 
54
- `config init` は `.specdojo/specdojo.config.json` とその親ディレクトリを作成します。既定では
55
- `prj-0001` と `docs/ja/projects/prj-0001/controls/project-register` を使う最小構成です。別の
56
- project ID や配置を使う場合は、生成された設定の `current_project`、`projects` のキー、
57
- `base_path` を次へ進む前に変更してください。catalog や schedule へ進むときに追加するキーは
58
- [SpecDojo設定リファレンス](https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html)で確認できます。
84
+ `config init` は、登録簿を使い始めるための最小設定を `.specdojo/specdojo.config.json` に作成します。worktree の既定先はリポジトリのディレクトリ名から `../<リポジトリ名>-worktrees` として作られます。設定を変える方法は、後述の「設定を変えたいとき」を参照してください。
85
+
86
+ あわせて、`npm install` で作られる `node_modules/` と SpecDojo の生成物(`docs/**/generated/*`、`.specdojo/doc-index.json` など)を git の管理から外す行を `.gitignore` に用意します。`.gitignore` が無ければ作成し、既にあれば足りない行だけを末尾へ追記します。`node_modules`、`/node_modules` など同じ意味の行が既にあれば `node_modules/` は追記しません。生成物を管理外にしておくと、登録簿の項目を並行実行したときに生成物どうしが衝突しません。追記する行は `npx specdojo config init --dry-run` で事前に確認できます。すでに `node_modules/` や生成物を git で管理している場合は、表示される案内に従って `git rm -r --cached` で管理から外し、コミットします。
59
87
 
60
88
  ### オーケストレーターを配置する
61
89
 
62
- SpecDojo は対話型オーケストレーターを同梱しています。CLI を直接叩く代わりに、会話で意図を伝えると、
63
- 対応するコマンドを提案し、承認を得てから実行します。利用する provider の設定を配置します。
90
+ SpecDojo は、会話を CLI 操作へ変換する対話型オーケストレーターを同梱しています。利用する AI ツール(provider)の設定を配置します。次は Claude Code を使う例です。
64
91
 
65
92
  ```sh
66
93
  npx specdojo config scaffold --provider claude
67
94
  ```
68
95
 
69
- `--provider` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定できます。
70
- オーケストレーターの配置先と起動方法は provider ごとに異なります。
96
+ このコマンドを実行すると、オーケストレーターの定義ファイルが配置され、`package.json` へ起動用のスクリプトが追加されます(`package.json` が存在する場合)。追加されたスクリプトで起動します。
71
97
 
72
- | provider | 配置先 | 起動 |
73
- | ------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
74
- | `claude` | `.claude/agents/specdojo-orchestrator.md` | `claude --agent specdojo-orchestrator` |
75
- | `opencode` | `.opencode/agents/specdojo-orchestrator.md` | `opencode --agent specdojo-orchestrator` |
76
- | `codex` | `.specdojo/codex/orchestrator.md` | `codex "$(cat .specdojo/codex/orchestrator.md)"` |
77
- | `antigravity` | `.specdojo/antigravity/orchestrator.md` | `agy --add-dir "$(pwd)" -i "$(cat .specdojo/antigravity/orchestrator.md)"` |
98
+ | provider | 配置先 | 起動(`package.json` がある場合) |
99
+ | ------------- | ------------------------------------------- | --------------------------------- |
100
+ | `claude` | `.claude/agents/specdojo-orchestrator.md` | `npm run orch:opus` ほか |
101
+ | `opencode` | `.opencode/agents/specdojo-orchestrator.md` | `npm run orch:opencode` |
102
+ | `codex` | `.specdojo/codex/orchestrator.md` | `npm run orch:codex` |
103
+ | `antigravity` | `.specdojo/antigravity/orchestrator.md` | `npm run orch:agy` |
78
104
 
79
- `claude` と `opencode` は agent の定義ファイルを名前で選べるため、`--agent` で起動します。`codex` と
80
- `antigravity` は定義ファイルから agent を選ぶ仕組みを持たないため、規範の本文を起動時の指示として
81
- 渡します。antigravity の `.agents/` は rules と skills のためのディレクトリで、agent の定義は扱いません。
82
- rules へ置くと全セッションへ読み込まれ、executor として起動したときにも役割が混入します。
105
+ 配置されるファイルのモデル名は、手元で使えるモデルに合わせて編集してください。provider ごとの詳しい設定は [オーケストレーター運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/orchestrator-operation-guide.html) を参照してください。
83
106
 
84
- 配置されるファイルにはモデル名が書かれています。手元で使えるモデルに合わせて編集してください。
85
- executor / reporter の設定も同時に配置されるので、agent にタスクを実行させる段階で使います。
107
+ Antigravity CLI を無人実行する場合は、利用者のグローバル設定へ permission rule を追加します。この設定はすべてのリポジトリに効くため、必ず先に差分を確認してから適用してください。通常の scaffold はグローバル設定へ触れません。
108
+
109
+ ```sh
110
+ npx specdojo config scaffold --provider antigravity --global --dry-run
111
+ npx specdojo config scaffold --provider antigravity --global
112
+ ```
113
+
114
+ 実適用では既存設定を残し、変更前のファイルをバックアップします。追加する allow は `git status` / `diff` / `log` / `show` の読み取り操作だけです。
115
+
116
+ #### Dev Container を使う場合(任意)
117
+
118
+ 利用環境として Dev Container を使う場合は、オーケストレーターの配置に加えて次のコマンドを実行すると、指定した provider の CLI が組み込まれた `.devcontainer/` を生成できます。
119
+
120
+ ```sh
121
+ npx specdojo devcontainer scaffold --provider claude --dry-run
122
+ npx specdojo devcontainer scaffold --provider claude
123
+ ```
124
+
125
+ 既存の `.devcontainer/` は上書きせず、置き換える場合だけ `--force` を指定します。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。生成後、VS Code などでコンテナを立ち上げると、分離された環境ですぐにオーケストレーターを起動できます。Ollama 接続、cron、tmux はそれぞれ `--ollama`、`--cron`、`--tmux` で追加できます。
86
126
 
87
127
  ### 会話で操作する
88
128
 
@@ -90,7 +130,7 @@ executor / reporter の設定も同時に配置されるので、agent にタス
90
130
 
91
131
  ```text
92
132
  あなた : このプロジェクトを始めたい。まず登録簿を用意して、最初の作業を起票して。
93
- agent : 次を実行します。よろしいですか。
133
+ オーケストレーター : 次を実行します。よろしいですか。
94
134
  npx specdojo register scaffold --project prj-0001
95
135
  npx specdojo register add --project prj-0001 --type todo --title "..."
96
136
  あなた : お願いします。
@@ -109,7 +149,7 @@ kata の rulebook を確認したい
109
149
 
110
150
  ### CLI を直接使う
111
151
 
112
- agent を使わずに操作することもできます。最初の登録簿と todo を作り、一覧を生成します。
152
+ オーケストレーターを使わずに操作することもできます。最初の登録簿と、実施する作業を表す `todo` を作り、一覧を生成します。
113
153
 
114
154
  ```sh
115
155
  npx specdojo register scaffold --project prj-0001
@@ -120,16 +160,17 @@ npx specdojo register add \
120
160
  npx specdojo register build --project prj-0001
121
161
  ```
122
162
 
123
- ここまでの手順は、利用側へ kata をコピーせずに実行できます。生成された todo の個票が編集対象、
124
- `generated/pjr-index.md` が個票から作る一覧です。`register add` が表示した ID を使い、agent を
125
- 起動せずに exec plan の内容まで確認できます。
163
+ `exec run` と並行して記帳し、その変更だけを commit まで完了させる場合は、`register add` / `update` / `renumber` または状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待ち、ほかの未 commit 変更を含めずに記帳・一覧再生成・commit を行います。対象の個票や event に既存差分がある場合は、混在を避けるため記帳前に停止します。
164
+
165
+ ここまでの手順は、利用側へ kata をコピーせずに実行できます。生成された `todo` の個票が編集対象、
166
+ `generated/pjr-index.md` が個票から作る一覧です。`register add` が表示した ID を使い、AI に作業を
167
+ 依頼する前に実行計画(exec plan)の内容まで確認できます。
126
168
 
127
169
  ```sh
128
170
  npx specdojo exec plan --project prj-0001 --register PJR-XXXX
129
171
  ```
130
172
 
131
- kata は既定で npm package 内のものを参照します。適用中の rulebook を確認し、プロジェクトで
132
- 上書きする場合だけ eject します。
173
+ kata は既定で npm package 内のものを参照します。適用中の rulebook(成果物ごとの記述規則)を確認し、プロジェクトで変更する場合だけ `eject` でリポジトリへコピーします。
133
174
 
134
175
  ```sh
135
176
  npx specdojo kata list --kind rulebook
@@ -137,17 +178,26 @@ npx specdojo kata show specdojo:pjr-rulebook
137
178
  npx specdojo kata eject --id specdojo:pjr-rulebook
138
179
  ```
139
180
 
140
- provider と agent の設定を終えた後は、同じ登録項目を実行できます。成功後は人が result と成果物を
141
- 確認し、登録項目を close します。
181
+ provider の設定を終えた後は、同じ登録項目を AI に実行させられます。成功後は人が実行結果(result)と成果物を確認し、登録項目を完了(close)します。
142
182
 
143
183
  ```sh
144
184
  npx specdojo exec run --project prj-0001 --register PJR-XXXX
145
185
  ```
146
186
 
147
- agent の実行は数分から数十分かかり、`routine` は定期実行されます。作業端末の状態に依存せず
187
+ AI による実行は数分から数十分かかり、定期処理として登録した `routine` は決めた時刻に実行されます。作業端末の状態に依存せず
148
188
  実行を続けたい場合は、常時稼働するホストへリモート接続する構成例を
149
189
  [常時稼働ホスト運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/remote-host-development-guide.html) に示しています。
150
190
 
191
+ ### 設定を変えたいとき
192
+
193
+ `config init` が作る設定は、`prj-0001` の登録簿から始める例です。別のプロジェクト ID や配置を使う場合は、`.specdojo/specdojo.config.json` を変更します。
194
+
195
+ - `current_project`: `--project` を省略したときに使うプロジェクトです。
196
+ - `projects`: このプロジェクトリポジトリで扱うプロジェクトを定義します。複数登録できます。
197
+ - `base_path`: 各プロジェクトの文書を置く基準パスです。
198
+
199
+ 成果物カタログやスケジュールへ進むときに追加する設定は、[SpecDojo設定リファレンス](https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html) を参照してください。
200
+
151
201
  ### テンプレートリポジトリとして導入する
152
202
 
153
203
  npm package の参照方式ではなく、SpecDojo のソースと文書体系一式を最初から配置して
@@ -20,6 +20,26 @@ export function extractJsonText(raw) {
20
20
  return unfenced;
21
21
  return unfenced.slice(start, end + 1);
22
22
  }
23
+ /**
24
+ * agent の生応答から JSON 配列の本文を取り出す。
25
+ * 配列内の文字列にオブジェクト記号が含まれていても、配列全体を優先する。
26
+ */
27
+ export function extractJsonArrayText(raw) {
28
+ const unfenced = stripCodeFence(raw.trim());
29
+ for (let start = unfenced.indexOf("["); start >= 0; start = unfenced.indexOf("[", start + 1)) {
30
+ for (let end = unfenced.lastIndexOf("]"); end > start; end = unfenced.lastIndexOf("]", end - 1)) {
31
+ const candidate = unfenced.slice(start, end + 1);
32
+ try {
33
+ if (Array.isArray(JSON.parse(candidate)))
34
+ return candidate;
35
+ }
36
+ catch {
37
+ // 別の角括弧または不完全な配列を飛ばし、次の候補を試す。
38
+ }
39
+ }
40
+ }
41
+ return unfenced;
42
+ }
23
43
  // 最初のコードフェンスの中身を返す。フェンスが無ければ入力をそのまま返す。
24
44
  function stripCodeFence(text) {
25
45
  const fenced = /```[a-z]*\r?\n([\s\S]*?)```/i.exec(text);
package/dist/agent.js CHANGED
@@ -13,14 +13,14 @@ export function resolveAgentMember(roster, nickname) {
13
13
  return candidate.type === "agent" && candidate.nickname === nickname;
14
14
  });
15
15
  if (!members || members.length === 0) {
16
- return { error: `--by agent nickname not found in pm-members.yaml: ${nickname}` };
16
+ return { error: `--by agent nickname not found in agent-members.yaml: ${nickname}` };
17
17
  }
18
18
  if (members.length !== 1) {
19
- return { error: `--by agent nickname is not unique in pm-members.yaml: ${nickname}` };
19
+ return { error: `--by agent nickname is not unique in agent-members.yaml: ${nickname}` };
20
20
  }
21
21
  const [member] = members;
22
22
  if (member.disabled) {
23
- return { error: `--by agent is disabled in pm-members.yaml: ${nickname}` };
23
+ return { error: `--by agent is disabled in agent-members.yaml: ${nickname}` };
24
24
  }
25
25
  return { member };
26
26
  }
@@ -84,7 +84,7 @@ export function registerAgentCommands(program) {
84
84
  .command("run")
85
85
  .description("Feed a plan to one agent and capture its stdout")
86
86
  .requiredOption("--plan <path>", "Plan file passed to the agent on stdin")
87
- .requiredOption("--by <nickname>", "Agent nickname defined in pm-members.yaml")
87
+ .requiredOption("--by <nickname>", "Agent nickname defined in agent-members.yaml")
88
88
  .option("--out <path>", "Write the agent stdout to this file instead of the terminal")
89
89
  .option("--project <projectId>", "Project id in specdojo.config.json")
90
90
  .option("--exec-defaults <path>", "Override the exec-defaults.yaml path")
@@ -30,7 +30,29 @@ function isStepApplicable(scope, project) {
30
30
  return !!project.execution_path?.trim();
31
31
  }
32
32
  }
33
- function resolveSteps(scope, projectArgs, project) {
33
+ /**
34
+ * register build の対象 project を決める。index build はリポジトリ内のすべての登録簿の
35
+ * generated/pjr-index.md を要求する一方、生成物は git 管理外で新しい worktree には無い。
36
+ * そのため `--project` を明示しない build では、登録簿を持つ全 project を対象にする。
37
+ * `--project` を明示した場合は、従来どおりその project だけを対象にする。
38
+ */
39
+ export function resolveRegisterProjectIds(config, projectId, isProjectExplicit) {
40
+ if (!config)
41
+ return [];
42
+ if (isProjectExplicit) {
43
+ const project = projectId ? config.projects[projectId] : undefined;
44
+ return projectId && isStepApplicable("register", project) ? [projectId] : [];
45
+ }
46
+ return Object.keys(config.projects)
47
+ .filter((id) => isStepApplicable("register", config.projects[id]))
48
+ .sort();
49
+ }
50
+ export function resolveSteps(scope, projectArgs, project, registerProjectIds) {
51
+ const registerSteps = registerProjectIds.map((id) => ({
52
+ scope: "register",
53
+ label: registerProjectIds.length > 1 ? `register build (${id})` : "register build",
54
+ subArgs: ["register", "build", "--project", id],
55
+ }));
34
56
  const candidates = [
35
57
  {
36
58
  scope: "exec",
@@ -42,11 +64,7 @@ function resolveSteps(scope, projectArgs, project) {
42
64
  label: "catalog build",
43
65
  subArgs: ["catalog", "build", ...projectArgs],
44
66
  },
45
- {
46
- scope: "register",
47
- label: "register build",
48
- subArgs: ["register", "build", ...projectArgs],
49
- },
67
+ ...registerSteps,
50
68
  {
51
69
  scope: "yaml-pages",
52
70
  label: "yaml-pages build",
@@ -67,7 +85,8 @@ function resolveSteps(scope, projectArgs, project) {
67
85
  },
68
86
  ];
69
87
  const active = scope === "all" ? candidates : candidates.filter((s) => s.scope === scope);
70
- return active.filter((s) => isStepApplicable(s.scope, project));
88
+ // register の対象は registerProjectIds で解決済み。他の段は従来どおり 1 project で判定する。
89
+ return active.filter((s) => s.scope === "register" || isStepApplicable(s.scope, project));
71
90
  }
72
91
  // ================================
73
92
  // Logging
@@ -110,7 +129,8 @@ export function registerBuildCommand(program) {
110
129
  return;
111
130
  }
112
131
  const projectArgs = projectId ? ["--project", projectId] : [];
113
- const steps = resolveSteps(scope, projectArgs, project);
132
+ const registerProjectIds = resolveRegisterProjectIds(config, projectId, !!opts.project?.trim());
133
+ const steps = resolveSteps(scope, projectArgs, project, registerProjectIds);
114
134
  if (steps.length === 0) {
115
135
  logError(`No applicable steps for scope "${scope}". ` +
116
136
  `Check that required paths are configured in specdojo.config.json.`);
@@ -0,0 +1,144 @@
1
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { load } from "./yaml.js";
4
+ import { resolveBasePath, resolveDeliverablePath } from "./catalog-paths.js";
5
+ import { isDctCatalogFileName } from "./catalog-types.js";
6
+ import { readSpecdojoNamespace } from "./frontmatter-namespace.js";
7
+ // Walk all deliverables, resolving each one's document path using the
8
+ // leading-slash base_path convention (same rules as renderSections / dct build).
9
+ export function collectResolvedDeliverables(sections, parentBase, out) {
10
+ for (const section of sections) {
11
+ const sectionBase = resolveBasePath(parentBase, section.base_path);
12
+ for (const item of section.deliverables ?? []) {
13
+ out.push({ item, resolvedPath: resolveDeliverablePath(sectionBase, item.path) });
14
+ }
15
+ if (section.groups)
16
+ collectResolvedDeliverables(section.groups, sectionBase, out);
17
+ }
18
+ }
19
+ // Builds the project-global graph across all dct-*.yaml in the catalog directory.
20
+ // depends_on references are same-project local_ids, so they resolve to
21
+ // `<project_id>:<dep>`; this lets the graph span multiple catalog files.
22
+ function buildCatalogGraph(catalogPath) {
23
+ const nodes = new Map();
24
+ const files = readdirSync(catalogPath).filter(isDctCatalogFileName).sort();
25
+ for (const f of files) {
26
+ const filePath = join(catalogPath, f);
27
+ let doc;
28
+ try {
29
+ doc = load(readFileSync(filePath, "utf8"));
30
+ }
31
+ catch {
32
+ continue;
33
+ }
34
+ if (!doc || !Array.isArray(doc.groups) || !doc.project_id)
35
+ continue;
36
+ const projectId = doc.project_id;
37
+ const deliverables = [];
38
+ collectResolvedDeliverables(doc.groups, resolveBasePath("", doc.base_path), deliverables);
39
+ for (const { item, resolvedPath } of deliverables) {
40
+ const fullId = `${projectId}:${item.local_id}`;
41
+ nodes.set(fullId, {
42
+ fullId,
43
+ projectId,
44
+ localId: item.local_id,
45
+ kind: item.kind,
46
+ dependsOn: (item.depends_on ?? []).map((dep) => `${projectId}:${dep}`),
47
+ filePath,
48
+ resolvedDocPath: item.path ? resolvedPath : undefined,
49
+ });
50
+ }
51
+ }
52
+ return nodes;
53
+ }
54
+ // Transitive closure of a node's depends_on edges over the project-global graph.
55
+ function transitiveDependsOn(startId, nodes) {
56
+ const seen = new Set();
57
+ const stack = [...(nodes.get(startId)?.dependsOn ?? [])];
58
+ while (stack.length > 0) {
59
+ const current = stack.pop();
60
+ if (current === undefined || seen.has(current))
61
+ continue;
62
+ seen.add(current);
63
+ for (const dep of nodes.get(current)?.dependsOn ?? []) {
64
+ if (!seen.has(dep))
65
+ stack.push(dep);
66
+ }
67
+ }
68
+ return seen;
69
+ }
70
+ // Resolves a based_on reference per specdojo:id-and-file-naming-standard §5.2.
71
+ // Bare references resolve to the same project first, then to a global/product id.
72
+ function resolveReference(ref, projectId, nodes, knownIds) {
73
+ if (ref.includes(":")) {
74
+ if (nodes.has(ref)) {
75
+ return ref.startsWith(`${projectId}:`)
76
+ ? { kind: "catalog", fullId: ref }
77
+ : { kind: "external" };
78
+ }
79
+ return knownIds.has(ref) ? { kind: "external" } : { kind: "unresolved" };
80
+ }
81
+ const sameProjectId = `${projectId}:${ref}`;
82
+ if (nodes.has(sameProjectId))
83
+ return { kind: "catalog", fullId: sameProjectId };
84
+ if (knownIds.has(sameProjectId))
85
+ return { kind: "external" }; // same project, not a catalog deliverable
86
+ if (knownIds.has(ref))
87
+ return { kind: "external" }; // global / product doc
88
+ return { kind: "unresolved" };
89
+ }
90
+ // Reads the based_on list from a deliverable document's frontmatter.
91
+ // Returns null when the document file does not exist.
92
+ function readBasedOn(docFsPath) {
93
+ if (!existsSync(docFsPath))
94
+ return null;
95
+ const content = readFileSync(docFsPath, "utf8");
96
+ // based_on は Markdown frontmatter の `specdojo:` 名前空間配下にある。
97
+ const based = readSpecdojoNamespace(content).based_on;
98
+ if (!Array.isArray(based))
99
+ return [];
100
+ return based.filter((value) => typeof value === "string");
101
+ }
102
+ // Validates the invariant: every same-project catalog deliverable referenced in
103
+ // a document's based_on must lie within that deliverable's transitive depends_on
104
+ // closure (project-global). A basis document must be produced before the document
105
+ // based on it, so it has to be a (transitive) prerequisite in the WBS.
106
+ //
107
+ // References are resolved per specdojo:id-and-file-naming-standard §5.2:
108
+ // - bare refs resolve to the same project first, then to a global/product id;
109
+ // - `<project_id>:<local_id>` and other-project refs use the explicit id.
110
+ // `knownIds` is the universe of valid document ids (from the doc index); a
111
+ // reference that resolves to neither a catalog deliverable nor a known id is
112
+ // reported as an error (typo detection / resolve-or-error).
113
+ export function validateBasedOn(catalogPath, rootDir, knownIds) {
114
+ const errors = [];
115
+ const warnings = [];
116
+ const nodes = buildCatalogGraph(catalogPath);
117
+ for (const node of nodes.values()) {
118
+ if (node.kind !== "work" || !node.resolvedDocPath)
119
+ continue;
120
+ const basedOn = readBasedOn(join(rootDir, node.resolvedDocPath));
121
+ if (basedOn === null) {
122
+ warnings.push(`${node.filePath}: ${node.localId}: based_on を検証する文書が見つかりません (${node.resolvedDocPath})`);
123
+ continue;
124
+ }
125
+ const closure = transitiveDependsOn(node.fullId, nodes);
126
+ for (const ref of basedOn) {
127
+ const resolution = resolveReference(ref, node.projectId, nodes, knownIds);
128
+ if (resolution.kind === "unresolved") {
129
+ errors.push(`${node.filePath}: ${node.localId}: based_on '${ref}' を解決できません(プロジェクト内 deliverable にもグローバル ID にも一致しません)`);
130
+ continue;
131
+ }
132
+ if (resolution.kind === "external")
133
+ continue; // 他プロジェクト/グローバル参照は閉包検査の対象外
134
+ if (resolution.fullId === node.fullId) {
135
+ errors.push(`${node.filePath}: ${node.localId}: based_on が自分自身を参照しています`);
136
+ continue;
137
+ }
138
+ if (!closure.has(resolution.fullId)) {
139
+ errors.push(`${node.filePath}: ${node.localId}: based_on '${ref}' (${resolution.fullId}) が depends_on の推移閉包に含まれていません(根拠ドキュメントは先行成果物である必要があります)`);
140
+ }
141
+ }
142
+ }
143
+ return { ok: errors.length === 0, errors, warnings };
144
+ }
@@ -0,0 +1,144 @@
1
+ import { resolveBasePath } from "./catalog-paths.js";
2
+ import { buildSpecdojoFrontmatter } from "./frontmatter-namespace.js";
3
+ function formatDependsOn(deps) {
4
+ if (!deps || deps.length === 0)
5
+ return "-";
6
+ return deps.map((d) => `\`${d}\``).join(", ");
7
+ }
8
+ function renderTable(deliverables) {
9
+ const lines = ["<!-- prettier-ignore -->"];
10
+ const hasInstanceIdPattern = deliverables.some((item) => item.instance_id_pattern);
11
+ if (hasInstanceIdPattern) {
12
+ lines.push("| local-id | 実体IDパターン | 成果物名 | 種別 | 根拠 | 概要 |");
13
+ lines.push("| --- | --- | --- | --- | --- | --- |");
14
+ }
15
+ else {
16
+ lines.push("| local-id | 成果物名 | 種別 | 根拠 | 概要 |");
17
+ lines.push("| --- | --- | --- | --- | --- |");
18
+ }
19
+ for (const item of deliverables) {
20
+ const localId = `\`${item.local_id}\``;
21
+ const deps = formatDependsOn(item.depends_on);
22
+ if (hasInstanceIdPattern) {
23
+ const instanceIdPattern = item.instance_id_pattern ? `\`${item.instance_id_pattern}\`` : "-";
24
+ lines.push(`| ${localId} | ${instanceIdPattern} | ${item.name} | ${item.kind} | ${deps} | ${item.overview} |`);
25
+ }
26
+ else {
27
+ lines.push(`| ${localId} | ${item.name} | ${item.kind} | ${deps} | ${item.overview} |`);
28
+ }
29
+ }
30
+ return lines;
31
+ }
32
+ function renderDoneCriteria(deliverables) {
33
+ const lines = [];
34
+ for (const item of deliverables) {
35
+ if (item.kind !== "work" || !item.done_criteria || item.done_criteria.length === 0)
36
+ continue;
37
+ lines.push("");
38
+ lines.push(`**\`${item.local_id}\`** の完了条件:`);
39
+ lines.push("");
40
+ for (const criterion of item.done_criteria) {
41
+ lines.push(`- ${criterion.text}`);
42
+ }
43
+ }
44
+ return lines;
45
+ }
46
+ function renderSections(sections, parentBase, depth, prefix) {
47
+ const lines = [];
48
+ const hashes = "#".repeat(depth + 1);
49
+ let counter = 0;
50
+ for (const section of sections) {
51
+ const sectionBase = resolveBasePath(parentBase, section.base_path);
52
+ if (!section.name) {
53
+ // Unnamed section: output content without heading
54
+ if (section.base_path) {
55
+ lines.push("");
56
+ lines.push(`- 配置先: \`${sectionBase}\``);
57
+ }
58
+ if (section.note) {
59
+ lines.push("");
60
+ lines.push(section.note);
61
+ }
62
+ if (section.deliverables && section.deliverables.length > 0) {
63
+ lines.push("");
64
+ lines.push(...renderTable(section.deliverables));
65
+ lines.push(...renderDoneCriteria(section.deliverables));
66
+ }
67
+ if (section.groups && section.groups.length > 0) {
68
+ lines.push(...renderSections(section.groups, sectionBase, depth, prefix));
69
+ }
70
+ continue;
71
+ }
72
+ counter++;
73
+ const nums = [...prefix, counter];
74
+ const numStr = nums.join(".");
75
+ lines.push("");
76
+ lines.push(`${hashes} ${numStr}. ${section.name}`);
77
+ if (section.base_path) {
78
+ lines.push("");
79
+ lines.push(`- 配置先: \`${sectionBase}\``);
80
+ }
81
+ if (section.note) {
82
+ lines.push("");
83
+ lines.push(section.note);
84
+ }
85
+ if (section.deliverables && section.deliverables.length > 0) {
86
+ lines.push("");
87
+ lines.push(...renderTable(section.deliverables));
88
+ lines.push(...renderDoneCriteria(section.deliverables));
89
+ }
90
+ if (section.groups && section.groups.length > 0) {
91
+ lines.push(...renderSections(section.groups, sectionBase, depth + 1, nums));
92
+ }
93
+ }
94
+ return lines;
95
+ }
96
+ function buildFrontmatter(doc) {
97
+ const inner = [];
98
+ inner.push(`id: ${doc.id}`);
99
+ inner.push(`type: ${doc.type}`);
100
+ inner.push(`status: ${doc.status}`);
101
+ if (doc.part_of && doc.part_of.length > 0) {
102
+ inner.push("part_of:");
103
+ for (const p of doc.part_of) {
104
+ const val = p.includes(":") ? `'${p}'` : p;
105
+ inner.push(` - ${val}`);
106
+ }
107
+ }
108
+ inner.push("rulebook: specdojo:dct-rulebook");
109
+ return buildSpecdojoFrontmatter(inner).split("\n");
110
+ }
111
+ export function isRecord(value) {
112
+ return typeof value === "object" && value !== null && !Array.isArray(value);
113
+ }
114
+ // dct 成果物カタログのテンプレート(type: template)YAML かを判定する。
115
+ // テンプレートはインスタンス(type: project)と違い project_id を持たず local_id に
116
+ // プレースホルダを含むため、validateDctDoc/buildMarkdown は適用できない。yaml-pages の
117
+ // 表示ページで、YAML 丸写しのコードブロックではなく可読な表形式で描画するために使う。
118
+ export function isDctTemplateCatalog(yamlRelPath, parsed) {
119
+ if (!/\/templates\/dct-.+-template\.ya?ml$/.test(yamlRelPath))
120
+ return false;
121
+ if (!isRecord(parsed))
122
+ return false;
123
+ return (parsed.type === "template" && typeof parsed.domain === "string" && Array.isArray(parsed.groups));
124
+ }
125
+ // dct テンプレートの本文(成果物表+完了条件)を描画する。frontmatter・H1・注記は
126
+ // 呼び出し側(yaml-pages 表示ページ)が付与するため、ここでは本文セクションのみ返す。
127
+ // インスタンス(buildMarkdown)と同じ renderSections を共用し、表現を一致させる。
128
+ export function renderCatalogTemplateBody(doc) {
129
+ const topBase = resolveBasePath("", doc.base_path);
130
+ return renderSections(doc.groups, topBase, 1, []).join("\n").trim();
131
+ }
132
+ export function buildMarkdown(doc) {
133
+ const lines = [];
134
+ lines.push(...buildFrontmatter(doc));
135
+ lines.push("");
136
+ lines.push(`# 成果物カタログ: ${doc.domain}`);
137
+ lines.push("");
138
+ lines.push(`- project-id: \`${doc.project_id}\``);
139
+ lines.push(`- ドメイン: \`${doc.domain}\``);
140
+ const topBase = resolveBasePath("", doc.base_path);
141
+ lines.push(...renderSections(doc.groups, topBase, 1, []));
142
+ lines.push("");
143
+ return lines.join("\n");
144
+ }